commit 8b068bdb10c9d7575448475b70f97e2e48106186
Author: darren <darrenmaverickz@gmail.com>
Date:   Thu Jul 16 22:16:45 2026 +0700

    init push

diff --git a/.air.toml b/.air.toml
new file mode 100644
index 0000000..ae26774
--- /dev/null
+++ b/.air.toml
@@ -0,0 +1,52 @@
+root = "."
+testdata_dir = "testdata"
+tmp_dir = "tmp"
+
+[build]
+  args_bin = []
+  bin = "./tmp/api"
+  cmd = "go build -o ./tmp/api ./cmd/api"
+  delay = 1000
+  exclude_dir = ["assets", "tmp", "vendor", "testdata"]
+  exclude_file = []
+  exclude_regex = ["_test.go"]
+  exclude_unchanged = false
+  follow_symlink = false
+  full_bin = ""
+  include_dir = []
+  include_ext = ["go", "tpl", "tmpl", "html"]
+  include_file = []
+  kill_delay = "0s"
+  log = "build-errors.log"
+  poll = false
+  poll_interval = 0
+  post_cmd = []
+  pre_cmd = []
+  rerun = false
+  rerun_delay = 500
+  send_interrupt = false
+  stop_on_error = false
+
+[color]
+  app = ""
+  build = "yellow"
+  main = "magenta"
+  runner = "green"
+  watcher = "cyan"
+
+[log]
+  main_only = false
+  silent = false
+  time = false
+
+[misc]
+  clean_on_exit = false
+
+[proxy]
+  app_port = 0
+  enabled = false
+  proxy_port = 0
+
+[screen]
+  clear_on_rebuild = false
+  keep_scroll = true
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..0c30068
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,33 @@
+.git
+.gitignore
+.github/
+.circleci/
+.gitlab-ci.yml
+.idea/
+.vscode/
+.DS_Store
+
+# Never send local secrets or editor/dev-only files into the build context.
+.env
+.env.*
+!.env.example
+.air.toml
+
+# Test and coverage artifacts are not needed for production image builds.
+**/*_test.go
+coverage.out
+coverage.html
+*.cover
+*.log
+
+# Exclude docs and directories not needed by the production Dockerfile.
+docs/*.md
+docs/collections/
+docs/swagger.json
+docs/swagger.yaml
+docs/docs_test.go
+deployments/
+migrations/
+tmp/
+dist/
+bin/
diff --git a/.env.local.example b/.env.local.example
new file mode 100644
index 0000000..de77183
--- /dev/null
+++ b/.env.local.example
@@ -0,0 +1,248 @@
+# Copy this to .env.local and fill in your values.
+# Never commit .env.local.
+
+# App
+APP_ENV=local
+
+# HTTP
+HTTP_PORT=8080
+HTTP_BODY_LIMIT=4194304
+HTTP_READ_TIMEOUT=10s
+HTTP_WRITE_TIMEOUT=15s
+HTTP_IDLE_TIMEOUT=60s
+HTTP_CORS_ALLOW_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:5173,http://127.0.0.1:5173
+HTTP_CORS_ALLOW_METHODS=GET,POST,PUT,PATCH,DELETE,OPTIONS,HEAD
+HTTP_CORS_ALLOW_HEADERS=Origin,Content-Type,Accept,Authorization,X-Requested-With,X-Pin-Verification-Token,X-Device-Type
+HTTP_CORS_EXPOSE_HEADERS=X-Request-ID
+HTTP_CORS_ALLOW_CREDENTIALS=true
+HTTP_CORS_MAX_AGE=300
+HTTP_REQUEST_TIMEOUT=30s
+HTTP_REQUEST_TIMEOUT_OVERRIDES=
+HTTP_SHUTDOWN_TIMEOUT=30s
+HTTP_RATE_LIMIT_MAX=120
+HTTP_RATE_LIMIT_WINDOW=1m
+HTTP_SECURITY_HSTS_MAX_AGE=0
+
+# MySQL
+MYSQL_DSN="root:password@tcp(localhost:3306)/fm_dev?parseTime=true"
+MYSQL_MAX_OPEN_CONNS=25
+MYSQL_MAX_IDLE_CONNS=10
+MYSQL_CONN_MAX_LIFETIME=5m
+MYSQL_CONN_MAX_IDLE_TIME=2m
+
+# Logging
+LOG_LEVEL=debug
+LOG_FORMAT=json
+
+# Audit
+AUDIT_LOG_QUEUE_SIZE=1024
+AUDIT_LOG_WORKERS=2
+
+# Email
+EMAIL_PROVIDER=mock
+EMAIL_MOCK_DIR=.local/emails
+
+# Circuit Breaker (default policy)
+CB_DEFAULT_ENABLED=true
+CB_DEFAULT_MAX_REQUESTS=1
+CB_DEFAULT_INTERVAL=1m
+CB_DEFAULT_BUCKET_PERIOD=10s
+CB_DEFAULT_TIMEOUT=30s
+CB_DEFAULT_MIN_REQUESTS=5
+CB_DEFAULT_FAILURE_RATIO=0.6
+CB_DEFAULT_CONSECUTIVE_FAILURES=5
+CB_MICROSOFT_SSO_ENABLED=true
+CB_MICROSOFT_SSO_MAX_REQUESTS=1
+CB_MICROSOFT_SSO_INTERVAL=1m
+CB_MICROSOFT_SSO_BUCKET_PERIOD=10s
+CB_MICROSOFT_SSO_TIMEOUT=30s
+CB_MICROSOFT_SSO_MIN_REQUESTS=5
+CB_MICROSOFT_SSO_FAILURE_RATIO=0.6
+CB_MICROSOFT_SSO_CONSECUTIVE_FAILURES=5
+CB_SES_ENABLED=true
+CB_SES_MAX_REQUESTS=1
+CB_SES_INTERVAL=1m
+CB_SES_BUCKET_PERIOD=10s
+CB_SES_TIMEOUT=30s
+CB_SES_MIN_REQUESTS=5
+CB_SES_FAILURE_RATIO=0.6
+CB_SES_CONSECUTIVE_FAILURES=5
+CB_SQS_ENABLED=true
+CB_SQS_MAX_REQUESTS=1
+CB_SQS_INTERVAL=1m
+CB_SQS_BUCKET_PERIOD=10s
+CB_SQS_TIMEOUT=30s
+CB_SQS_MIN_REQUESTS=5
+CB_SQS_FAILURE_RATIO=0.6
+CB_SQS_CONSECUTIVE_FAILURES=5
+
+# Auth
+AUTH_PASSWORD_PEPPER=change-me-local-pepper
+AUTH_IP_ENCRYPTION_KEY=change-me-local-ip-key
+AUTH_DEFAULT_ROLE=user
+AUTH_DISABLE_REGISTER=false
+AUTH_HASH_TIME=1
+AUTH_HASH_MEMORY_KB=65536
+AUTH_HASH_THREADS=4
+AUTH_HASH_KEY_LEN=32
+AUTH_EMAIL_VERIFY_TTL=24h
+AUTH_EMAIL_VERIFY_URL=http://localhost:3000/verify-email
+AUTH_INVITE_TTL=24h
+AUTH_SET_PASSWORD_URL=http://localhost:3000/set-password
+AUTH_PASSWORD_RESET_TTL=20m
+AUTH_PASSWORD_RESET_URL=http://localhost:3000/reset-password
+AUTH_FORGOT_PASSWORD_EMAIL_COOLDOWN=2m
+AUTH_FORGOT_PASSWORD_MIN_DURATION=150ms
+AUTH_FORGOT_PASSWORD_IP_RATE_MAX=10
+AUTH_FORGOT_PASSWORD_IP_RATE_WINDOW=15m
+AUTH_SECURITY_PIN_RESET_TTL=20m
+AUTH_SECURITY_PIN_RESET_URL=http://localhost:3000/reset-pin
+AUTH_FORGOT_SECURITY_PIN_EMAIL_COOLDOWN=2m
+AUTH_FORGOT_SECURITY_PIN_MIN_DURATION=150ms
+AUTH_SECURITY_PIN_MAX_ATTEMPTS=5
+AUTH_SECURITY_PIN_LOCK_DURATION=0s
+AUTH_SECURITY_PIN_ACTION_TOKEN_TTL=5m
+
+AUTH_JWT_COOKIE_DOMAIN=.mybit.co.id
+
+# JWT
+AUTH_JWT_ACCESS_SECRET=change-me-local-access-secret
+AUTH_JWT_REFRESH_SECRET=change-me-local-refresh-secret
+AUTH_JWT_ACCESS_TTL=10m
+AUTH_JWT_REFRESH_TTL=1h
+AUTH_JWT_REFRESH_TOTP_TTL=1h
+AUTH_JWT_COOKIE_SECURE=false
+AUTH_JWT_COOKIE_SAMESITE=Lax
+AUTH_JWT_ACCESS_COOKIE=wucher_at
+AUTH_JWT_REFRESH_COOKIE=wucher_rt
+
+# TOTP
+AUTH_TOTP_CHALLENGE_TTL=5m
+TOTP_ISSUER=Wucher
+TOTP_SECRET_KEY=change-me-local-totp-secret
+
+# SSO
+AUTH_SSO_STATE_TTL=10m
+AUTH_SSO_SUCCESS_REDIRECT=http://localhost:3000/sso/callback
+
+# WebAuthn
+AUTH_WEBAUTHN_RP_ID=localhost
+AUTH_WEBAUTHN_RP_DISPLAY_NAME=Wucher
+AUTH_WEBAUTHN_RP_ORIGINS=http://localhost:3000
+AUTH_WEBAUTHN_CHALLENGE_TTL=5m
+
+# Microsoft SSO
+MS_ENTRA_TENANT_ID=
+MS_ENTRA_CLIENT_ID=
+MS_ENTRA_CLIENT_SECRET=
+MS_ENTRA_REDIRECT_URL=http://localhost:8080/v1/auth/sso/microsoft/callback
+MS_ENTRA_AUTHORITY=https://login.microsoftonline.com/
+MS_ENTRA_SCOPES=openid,profile,email,offline_access,User.Read
+
+# Queue
+QUEUE_MESSAGE_SCHEMA_VERSION=v2
+QUEUE_ENABLE_LEGACY_PAYLOAD_FALLBACK=true
+QUEUE_IDEMPOTENCY_KEY_PREFIX=queue:idempotency:email:
+QUEUE_IDEMPOTENCY_TTL=24h
+QUEUE_PROCESSING_TTL=15m
+QUEUE_WORKER_CONCURRENCY=4
+QUEUE_WORKER_MAX_BATCH_SIZE=10
+QUEUE_WORKER_PROCESS_TIMEOUT=30s
+QUEUE_WORKER_SHUTDOWN_TIMEOUT=30s
+QUEUE_WORKER_BACKOFF_MIN=1s
+QUEUE_WORKER_BACKOFF_MAX=5m
+QUEUE_WORKER_PERMANENT_FAILURE_DELAY=30s
+QUEUE_WORKER_MONITOR_ADDR=127.0.0.1:9090
+QUEUE_WORKER_HEALTH_ERROR_THRESHOLD=3
+QUEUE_WORKER_DEPTH_POLL_INTERVAL=30s
+QUEUE_OUTBOX_ENABLED=true
+QUEUE_OUTBOX_POLL_INTERVAL=1s
+QUEUE_OUTBOX_BATCH_SIZE=10
+QUEUE_OUTBOX_DISPATCH_TIMEOUT=10s
+QUEUE_OUTBOX_LOCK_TTL=1m
+QUEUE_OUTBOX_MAX_ATTEMPTS=20
+
+# File Queue
+FILE_QUEUE_MESSAGE_SCHEMA_VERSION=v1
+FILE_QUEUE_IDEMPOTENCY_KEY_PREFIX=queue:idempotency:file:
+FILE_QUEUE_IDEMPOTENCY_TTL=24h
+FILE_QUEUE_PROCESSING_TTL=15m
+FILE_QUEUE_WORKER_CONCURRENCY=4
+FILE_QUEUE_WORKER_MAX_BATCH_SIZE=10
+FILE_QUEUE_WORKER_PROCESS_TIMEOUT=30s
+FILE_QUEUE_WORKER_SHUTDOWN_TIMEOUT=30s
+FILE_QUEUE_WORKER_BACKOFF_MIN=1s
+FILE_QUEUE_WORKER_BACKOFF_MAX=5m
+FILE_QUEUE_WORKER_PERMANENT_FAILURE_DELAY=30s
+FILE_QUEUE_WORKER_MONITOR_ADDR=127.0.0.1:9091
+FILE_QUEUE_WORKER_HEALTH_ERROR_THRESHOLD=3
+FILE_QUEUE_WORKER_DEPTH_POLL_INTERVAL=30s
+FILE_QUEUE_OUTBOX_ENABLED=true
+FILE_QUEUE_OUTBOX_POLL_INTERVAL=1s
+FILE_QUEUE_OUTBOX_BATCH_SIZE=10
+FILE_QUEUE_OUTBOX_DISPATCH_TIMEOUT=10s
+FILE_QUEUE_OUTBOX_LOCK_TTL=1m
+FILE_QUEUE_OUTBOX_MAX_ATTEMPTS=20
+
+# AWS
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=test
+AWS_SECRET_ACCESS_KEY=test
+
+# SQS (local uses localstack or similar)
+SQS_ENDPOINT=http://localhost:4566
+SQS_ALLOW_INSECURE_ENDPOINT=true
+SQS_QUEUE_URL=http://localhost:4566/000000000000/fm-email-queue
+SQS_QUEUE_TYPE=standard
+SQS_MESSAGE_GROUP_ID=email
+SQS_MAX_MESSAGES=10
+SQS_WAIT_TIME_SECONDS=20
+SQS_VISIBILITY_TIMEOUT=60s
+
+# SQS (file queue, local uses localstack or similar)
+FILE_SQS_REGION=us-east-1
+FILE_SQS_ENDPOINT=http://localhost:4566
+FILE_SQS_ALLOW_INSECURE_ENDPOINT=true
+FILE_SQS_QUEUE_URL=http://localhost:4566/000000000000/fm-file-queue
+FILE_SQS_QUEUE_TYPE=standard
+FILE_SQS_MESSAGE_GROUP_ID=file-processing
+FILE_SQS_MAX_MESSAGES=10
+FILE_SQS_WAIT_TIME_SECONDS=20
+FILE_SQS_VISIBILITY_TIMEOUT=60s
+
+# SES (local uses localstack or similar)
+SES_REGION=us-east-1
+SES_FROM=noreply@localhost
+SES_CONFIGURATION_SET=
+SES_SEND_TIMEOUT=10s
+SES_ENDPOINT=http://localhost:4566
+SES_ALLOW_INSECURE_ENDPOINT=true
+
+# File Storage (local uses localstack or similar)
+FILE_STORAGE_PROVIDER=s3
+FILE_S3_BUCKET=fm-local
+FILE_S3_REGION=us-east-1
+FILE_S3_ENDPOINT=http://localhost:4566
+FILE_S3_FORCE_PATH_STYLE=true
+FILE_S3_ALLOW_INSECURE_ENDPOINT=true
+FILE_S3_AUTO_CREATE_BUCKET=true
+FILE_OBJECT_KEY_PREFIX=fm/objects
+FILE_S3_PRESIGN_PUT_TTL=15m
+FILE_S3_PRESIGN_GET_TTL=15m
+FILE_MANAGER_UPLOAD_MAX_FILE_SIZE_BYTES=4194304
+FILE_MANAGER_UPLOAD_ALLOWED_MIME_TYPES=image/png,image/jpeg,application/pdf,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.ms-excel
+FILE_MANAGER_UPLOAD_ALLOWED_EXTENSIONS=png,jpg,jpeg,pdf,xlsx,xls
+FILE_MANAGER_UPLOAD_ALLOW_EMPTY_FILE=false
+FILE_MANAGER_UPLOAD_MAX_FILENAME_LENGTH=255
+
+FILE_MANAGER_TRASH_AUTO_PURGE_ENABLED=true
+FILE_MANAGER_TRASH_RETENTION=720h
+FILE_MANAGER_TRASH_AUTO_PURGE_INTERVAL=1h
+FILE_MANAGER_TRASH_AUTO_PURGE_BATCH_SIZE=200
+
+ENABLE_S3_TAGGING=true
+ENABLE_FILE_CLEANUP_JOB=false
+TEMP_FILE_TTL_DAYS=7
+ORPHAN_GRACE_PERIOD_DAYS=30
+FILE_CLEANUP_BATCH_SIZE=100
+FILE_CLEANUP_DRY_RUN=true
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..fcae96b
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,62 @@
+# Go
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+*.prof
+
+# Build
+/bin/
+/build/
+/dist/
+/tmp/
+
+# Coverage
+coverage.out
+coverage.txt
+
+# Go workspace
+/vendor/
+
+# IDE/editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*.swn
+*.tmp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env files
+.env
+.env.*
+!.env.local.example
+
+# Generated configs
+*.generated.json
+
+# Logs
+*.log
+
+# Docker
+**/.docker/
+
+# GoFiber (optional)
+# (No special ignores required beyond Go build artifacts)
+
+# Claude Config
+.claude/
+
+# Codex Config
+.codex
+
+# Graphify outputs
+**/graphify-out/
+.graphify-venv/
+AGENTS.md
diff --git a/.releaserc b/.releaserc
new file mode 100644
index 0000000..64786df
--- /dev/null
+++ b/.releaserc
@@ -0,0 +1,16 @@
+{
+  "branches": [
+    "main",
+    { "name": "staging", "prerelease": "rc" }
+  ],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@saithodev/semantic-release-gitea",
+      {
+        "giteaUrl": "https://repo.mybit.center"
+      }
+    ]
+  ]
+}
\ No newline at end of file
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..d7315cf
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,109 @@
+# syntax=docker/dockerfile:1.7
+
+# Override these in CI with immutable digests when you are ready to pin them fully.
+ARG GO_IMAGE=golang:1.26.2-alpine3.22
+ARG RUNTIME_IMAGE=gcr.io/distroless/static-debian12:nonroot
+
+FROM ${GO_IMAGE} AS build-base
+
+WORKDIR /src
+
+ENV CGO_ENABLED=0 \
+    GOOS=linux \
+    GOFLAGS=-buildvcs=false
+
+COPY go.mod go.sum ./
+RUN --mount=type=cache,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,target=/root/.cache/go-build,sharing=locked \
+    go mod download && go mod verify
+
+FROM build-base AS healthcheck-build
+
+COPY cmd/healthcheck/ ./cmd/healthcheck/
+RUN --mount=type=cache,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,target=/root/.cache/go-build,sharing=locked \
+    go build \
+        -trimpath \
+        -ldflags="-s -w" \
+        -o /out/healthcheck \
+        ./cmd/healthcheck
+
+FROM build-base AS worker-build
+
+COPY cmd/worker/ ./cmd/worker/
+COPY internal/ ./internal/
+RUN --mount=type=cache,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,target=/root/.cache/go-build,sharing=locked \
+    go build \
+        -trimpath \
+        -ldflags="-s -w" \
+        -o /out/wucher-worker \
+        ./cmd/worker
+RUN mkdir -p /out/.local/emails && touch /out/.local/emails/.keep
+
+FROM build-base AS file-worker-build
+
+COPY cmd/worker/ ./cmd/worker/
+COPY internal/ ./internal/
+RUN --mount=type=cache,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,target=/root/.cache/go-build,sharing=locked \
+    go build \
+        -trimpath \
+        -ldflags="-s -w" \
+        -o /out/wucher-file-worker \
+        ./cmd/worker
+
+FROM build-base AS api-build
+
+ARG VERSION=unknown
+ARG COMMIT=unknown
+ARG BUILD_TIME=unknown
+
+COPY cmd/api/ ./cmd/api/
+COPY internal/ ./internal/
+COPY docs/docs.go ./docs/docs.go
+RUN --mount=type=cache,target=/go/pkg/mod,sharing=locked \
+    --mount=type=cache,target=/root/.cache/go-build,sharing=locked \
+    go build \
+        -trimpath \
+        -ldflags="-s -w -X 'wucher/internal/buildinfo.Version=${VERSION}' -X 'wucher/internal/buildinfo.Commit=${COMMIT}' -X 'wucher/internal/buildinfo.BuildTime=${BUILD_TIME}'" \
+        -o /out/wucher-api \
+        ./cmd/api
+
+FROM ${RUNTIME_IMAGE} AS runtime-base
+
+WORKDIR /app
+
+FROM runtime-base AS worker
+
+COPY --from=healthcheck-build --chown=nonroot:nonroot /out/healthcheck /app/healthcheck
+COPY --from=worker-build --chown=nonroot:nonroot /out/wucher-worker /app/wucher-worker
+COPY --from=worker-build --chown=nonroot:nonroot /out/.local/emails/ /app/.local/emails/
+
+ENV WORKER_JOB=email
+
+USER nonroot:nonroot
+
+ENTRYPOINT ["/app/wucher-worker"]
+
+FROM runtime-base AS file-worker
+
+COPY --from=healthcheck-build --chown=nonroot:nonroot /out/healthcheck /app/healthcheck
+COPY --from=file-worker-build --chown=nonroot:nonroot /out/wucher-file-worker /app/wucher-file-worker
+
+ENV WORKER_JOB=file_processing
+
+USER nonroot:nonroot
+
+ENTRYPOINT ["/app/wucher-file-worker"]
+
+FROM runtime-base AS api
+
+COPY --from=healthcheck-build --chown=nonroot:nonroot /out/healthcheck /app/healthcheck
+COPY --from=api-build --chown=nonroot:nonroot /out/wucher-api /app/wucher-api
+
+USER nonroot:nonroot
+
+EXPOSE 8080
+
+ENTRYPOINT ["/app/wucher-api"]
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..2fc2a46
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,107 @@
+GO ?= go
+AIR ?= air
+SWAG ?= swag
+GOOSE ?= goose
+GOOSE_DIR ?= migrations/goose
+MIGRATE_APPLY_FROM ?= 20260414
+
+.PHONY: air swag test worker file-worker migrate-status migrate-up migrate-up-to migrate-apply migrate-reapply hospital-apply
+
+air:
+	@command -v $(AIR) >/dev/null 2>&1 || { \
+		echo "air not found. Install with: go install github.com/air-verse/air@latest"; \
+		exit 1; \
+	}
+	$(AIR) -c .air.toml
+
+swag:
+	@command -v $(SWAG) >/dev/null 2>&1 || { \
+		echo "swag not found. Install with: go install github.com/swaggo/swag/cmd/swag@latest"; \
+		exit 1; \
+	}
+	GOCACHE=$${GOCACHE:-/tmp/go-cache} $(SWAG) init -g cmd/api/main.go -o docs --parseDependency --parseInternal
+
+test:
+	$(GO) test ./... -coverprofile=coverage.out
+	$(GO) tool cover -func=coverage.out
+
+worker:
+	WORKER_JOB=email $(GO) run ./cmd/worker
+
+file-worker:
+	WORKER_JOB=file_processing $(GO) run ./cmd/worker
+
+migrate-status:
+	@command -v $(GOOSE) >/dev/null 2>&1 || { \
+		echo "goose not found. Install with: go install github.com/pressly/goose/v3/cmd/goose@latest"; \
+		exit 1; \
+	}
+	@MYSQL_DSN_VAL="$${MYSQL_DSN:-$$(grep -hE '^MYSQL_DSN=' .env .env.local 2>/dev/null | tail -n1 | cut -d= -f2-)}"; \
+	MYSQL_DSN_VAL="$${MYSQL_DSN_VAL#\"}"; MYSQL_DSN_VAL="$${MYSQL_DSN_VAL%\"}"; \
+	test -n "$$MYSQL_DSN_VAL" || { echo "MYSQL_DSN is required (set env or define in .env/.env.local)"; exit 1; }; \
+	$(GOOSE) -dir $(GOOSE_DIR) mysql "$$MYSQL_DSN_VAL" status
+
+migrate-up:
+	@command -v $(GOOSE) >/dev/null 2>&1 || { \
+		echo "goose not found. Install with: go install github.com/pressly/goose/v3/cmd/goose@latest"; \
+		exit 1; \
+	}
+	@MYSQL_DSN_VAL="$${MYSQL_DSN:-$$(grep -hE '^MYSQL_DSN=' .env .env.local 2>/dev/null | tail -n1 | cut -d= -f2-)}"; \
+	MYSQL_DSN_VAL="$${MYSQL_DSN_VAL#\"}"; MYSQL_DSN_VAL="$${MYSQL_DSN_VAL%\"}"; \
+	test -n "$$MYSQL_DSN_VAL" || { echo "MYSQL_DSN is required (set env or define in .env/.env.local)"; exit 1; }; \
+	$(GOOSE) -dir $(GOOSE_DIR) mysql "$$MYSQL_DSN_VAL" up
+
+migrate-up-to:
+	@command -v $(GOOSE) >/dev/null 2>&1 || { \
+		echo "goose not found. Install with: go install github.com/pressly/goose/v3/cmd/goose@latest"; \
+		exit 1; \
+	}
+	@MYSQL_DSN_VAL="$${MYSQL_DSN:-$$(grep -hE '^MYSQL_DSN=' .env .env.local 2>/dev/null | tail -n1 | cut -d= -f2-)}"; \
+	MYSQL_DSN_VAL="$${MYSQL_DSN_VAL#\"}"; MYSQL_DSN_VAL="$${MYSQL_DSN_VAL%\"}"; \
+	test -n "$$MYSQL_DSN_VAL" || { echo "MYSQL_DSN is required (set env or define in .env/.env.local)"; exit 1; }; \
+	test -n "$(v)" || { echo "usage: make migrate-up-to v=20260414"; exit 1; }; \
+	$(GOOSE) -dir $(GOOSE_DIR) mysql "$$MYSQL_DSN_VAL" up-to $(v)
+
+migrate-apply:
+	@command -v $(GOOSE) >/dev/null 2>&1 || { \
+		echo "goose not found. Install with: go install github.com/pressly/goose/v3/cmd/goose@latest"; \
+		exit 1; \
+	}
+	@MYSQL_DSN_VAL="$${MYSQL_DSN:-$$(grep -hE '^MYSQL_DSN=' .env .env.local 2>/dev/null | tail -n1 | cut -d= -f2-)}"; \
+	MYSQL_DSN_VAL="$${MYSQL_DSN_VAL#\"}"; MYSQL_DSN_VAL="$${MYSQL_DSN_VAL%\"}"; \
+	test -n "$$MYSQL_DSN_VAL" || { echo "MYSQL_DSN is required (set env or define in .env/.env.local)"; exit 1; }; \
+	MODULES="$(modules)"; \
+	test -n "$$MODULES" || { \
+		echo "usage: make migrate-apply modules=opc,kassa"; \
+		echo "hint: use 'make migrate-reapply [from=YYYYMMDD]' for full down-to/up behavior"; \
+		exit 1; \
+	}; \
+	TMP_DIR="$$(mktemp -d)"; \
+	echo "Applying selected import apply migrations for modules: $$MODULES"; \
+	for m in $$(echo "$$MODULES" | tr ',' ' '); do \
+		FOUND="$$(ls -1 $(GOOSE_DIR)/*_$${m}_import_apply.sql 2>/dev/null || true)"; \
+		if [ -z "$$FOUND" ]; then \
+			echo "No apply migration found for module '$$m' in $(GOOSE_DIR)"; \
+			rm -rf "$$TMP_DIR"; \
+			exit 1; \
+		fi; \
+		for f in $$FOUND; do cp "$$f" "$$TMP_DIR"/; done; \
+	done; \
+	$(GOOSE) -dir "$$TMP_DIR" -no-versioning mysql "$$MYSQL_DSN_VAL" up; \
+	rm -rf "$$TMP_DIR"
+
+migrate-reapply:
+	@command -v $(GOOSE) >/dev/null 2>&1 || { \
+		echo "goose not found. Install with: go install github.com/pressly/goose/v3/cmd/goose@latest"; \
+		exit 1; \
+	}
+	@MYSQL_DSN_VAL="$${MYSQL_DSN:-$$(grep -hE '^MYSQL_DSN=' .env .env.local 2>/dev/null | tail -n1 | cut -d= -f2-)}"; \
+	MYSQL_DSN_VAL="$${MYSQL_DSN_VAL#\"}"; MYSQL_DSN_VAL="$${MYSQL_DSN_VAL%\"}"; \
+	test -n "$$MYSQL_DSN_VAL" || { echo "MYSQL_DSN is required (set env or define in .env/.env.local)"; exit 1; }; \
+	FROM_VER="$(from)"; \
+	if [ -z "$$FROM_VER" ]; then FROM_VER="$(MIGRATE_APPLY_FROM)"; fi; \
+	echo "Re-applying migrations from version $$FROM_VER to latest"; \
+	$(GOOSE) -dir $(GOOSE_DIR) mysql "$$MYSQL_DSN_VAL" down-to "$$FROM_VER"; \
+	$(GOOSE) -dir $(GOOSE_DIR) mysql "$$MYSQL_DSN_VAL" up
+
+hospital-apply: migrate-apply
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..52a17d7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,435 @@
+# Wucher Backend
+
+Wucher is a Go backend built with GoFiber. The runtime uses MySQL for persistence and transient auth state, Amazon SQS for asynchronous email jobs, and Amazon SES v2 for email delivery.
+
+## Prerequisites
+
+- Go 1.25+
+- MySQL
+- LocalStack or AWS SQS/SES access for queue testing
+
+## Project Structure
+
+- `cmd/api/` API bootstrap
+- `cmd/worker/` SQS worker bootstrap
+- `internal/app/` application wiring
+- `internal/resilience/` circuit breaker executor and dependency error classifiers
+- `internal/service/` business logic
+- `internal/transport/http/` GoFiber handlers and middleware
+- `internal/repository/mysql/` MySQL repositories and transient stores
+- `internal/repository/sqs/` SQS publisher/consumer adapter
+- `internal/queue/` queue contracts, serializer, retry policy, and worker loop
+
+## Runtime Architecture
+
+- HTTP handlers stay thin and delegate to services.
+- Auth and other business writes persist to MySQL first.
+- API/service code never sends email synchronously.
+- Email jobs are written to `email_outbox_messages` when outbox is enabled, or published directly to SQS when outbox is disabled.
+- Worker publishes outbox rows to the SQS send queue, consumes SQS messages with long polling, and sends email through Amazon SES v2.
+- SES bounce, complaint, and delivery tracking should use a separate flow:
+  - SES Configuration Set
+  - SNS topic subscription
+  - dedicated SQS event queue
+- Circuit breakers are applied only at outbound dependency boundaries:
+  - Microsoft Entra token exchange
+  - SES delivery
+  - SQS publish/consume/ack calls
+- Transient auth state previously kept in Redis is now stored in MySQL tables:
+  - `auth_runtime_tokens`
+  - `queue_idempotency_records`
+
+`gorm` auto-migration creates these tables on startup.
+
+## Getting Started
+
+Install dependencies:
+
+```bash
+go mod tidy
+```
+
+Create local config from the example:
+
+```bash
+cp .env.example .env
+```
+
+Run the API:
+
+```bash
+go run ./cmd/api
+```
+
+Run the worker:
+
+```bash
+go run ./cmd/worker
+```
+
+Worker monitor endpoints:
+
+```bash
+curl http://127.0.0.1:9090/health
+curl http://127.0.0.1:9090/metrics
+curl http://127.0.0.1:9091/health
+curl http://127.0.0.1:9091/metrics
+```
+
+- `/metrics` exposes Prometheus format for API and worker processes.
+- `/health` remains JSON health/worker snapshot.
+
+## Environment Variables
+
+Example values are in `.env` for local development.
+
+Important groups:
+
+- Email delivery
+  - `EMAIL_PROVIDER`
+  - `EMAIL_MOCK_DIR`
+- MySQL
+  - `MYSQL_DSN`
+  - `MYSQL_MAX_OPEN_CONNS`
+  - `MYSQL_MAX_IDLE_CONNS`
+  - `MYSQL_CONN_MAX_LIFETIME`
+  - `MYSQL_CONN_MAX_IDLE_TIME`
+- Auth
+  - `AUTH_EMAIL_VERIFY_URL`
+  - `AUTH_PASSWORD_RESET_URL`
+  - `AUTH_SECURITY_PIN_RESET_URL`
+  - `AUTH_TOTP_CHALLENGE_TTL`
+  - `AUTH_SSO_STATE_TTL`
+  - `AUTH_JWT_ACCESS_SECRET`
+  - `AUTH_JWT_REFRESH_SECRET`
+  - `AUTH_WEBAUTHN_*`
+- Queue / worker
+  - `QUEUE_MESSAGE_SCHEMA_VERSION`
+  - `QUEUE_ENABLE_LEGACY_PAYLOAD_FALLBACK`
+  - `QUEUE_IDEMPOTENCY_KEY_PREFIX`
+  - `QUEUE_IDEMPOTENCY_TTL`
+  - `QUEUE_PROCESSING_TTL`
+  - `QUEUE_WORKER_CONCURRENCY`
+  - `QUEUE_WORKER_MAX_BATCH_SIZE`
+  - `QUEUE_WORKER_PROCESS_TIMEOUT`
+  - `QUEUE_WORKER_BACKOFF_MIN`
+  - `QUEUE_WORKER_BACKOFF_MAX`
+  - `QUEUE_WORKER_PERMANENT_FAILURE_DELAY`
+  - `QUEUE_OUTBOX_ENABLED`
+  - `QUEUE_OUTBOX_POLL_INTERVAL`
+  - `QUEUE_OUTBOX_BATCH_SIZE`
+  - `QUEUE_OUTBOX_DISPATCH_TIMEOUT`
+  - `QUEUE_OUTBOX_LOCK_TTL`
+  - `QUEUE_OUTBOX_MAX_ATTEMPTS`
+- File queue / file worker
+  - `FILE_QUEUE_MESSAGE_SCHEMA_VERSION`
+  - `FILE_QUEUE_IDEMPOTENCY_KEY_PREFIX`
+  - `FILE_QUEUE_IDEMPOTENCY_TTL`
+  - `FILE_QUEUE_PROCESSING_TTL`
+  - `FILE_QUEUE_WORKER_CONCURRENCY`
+  - `FILE_QUEUE_WORKER_MAX_BATCH_SIZE`
+  - `FILE_QUEUE_WORKER_PROCESS_TIMEOUT`
+  - `FILE_QUEUE_WORKER_SHUTDOWN_TIMEOUT`
+  - `FILE_QUEUE_WORKER_BACKOFF_MIN`
+  - `FILE_QUEUE_WORKER_BACKOFF_MAX`
+  - `FILE_QUEUE_WORKER_PERMANENT_FAILURE_DELAY`
+  - `FILE_QUEUE_WORKER_MONITOR_ADDR`
+  - `FILE_QUEUE_WORKER_HEALTH_ERROR_THRESHOLD`
+  - `FILE_QUEUE_WORKER_DEPTH_POLL_INTERVAL`
+  - `FILE_QUEUE_OUTBOX_ENABLED`
+  - `FILE_QUEUE_OUTBOX_POLL_INTERVAL`
+  - `FILE_QUEUE_OUTBOX_BATCH_SIZE`
+  - `FILE_QUEUE_OUTBOX_DISPATCH_TIMEOUT`
+  - `FILE_QUEUE_OUTBOX_LOCK_TTL`
+  - `FILE_QUEUE_OUTBOX_MAX_ATTEMPTS`
+- Circuit breakers
+  - `CB_DEFAULT_ENABLED`
+  - `CB_DEFAULT_MAX_REQUESTS`
+  - `CB_DEFAULT_INTERVAL`
+  - `CB_DEFAULT_BUCKET_PERIOD`
+  - `CB_DEFAULT_TIMEOUT`
+  - `CB_DEFAULT_MIN_REQUESTS`
+  - `CB_DEFAULT_FAILURE_RATIO`
+  - `CB_DEFAULT_CONSECUTIVE_FAILURES`
+  - `CB_MICROSOFT_SSO_ENABLED`
+  - `CB_SES_ENABLED`
+  - `CB_SQS_ENABLED`
+- AWS / SES
+  - `AWS_REGION`
+  - `SES_REGION`
+  - `SES_FROM`
+  - `SES_CONFIGURATION_SET`
+  - `SES_SEND_TIMEOUT`
+  - `SES_ENDPOINT`
+  - `SES_ALLOW_INSECURE_ENDPOINT`
+- AWS / SQS
+  - Email queue:
+  - `AWS_REGION`
+  - `AWS_ACCESS_KEY_ID`
+  - `AWS_SECRET_ACCESS_KEY`
+  - `SQS_ENDPOINT`
+  - `SQS_ALLOW_INSECURE_ENDPOINT`
+  - `SQS_QUEUE_URL`
+  - `SQS_QUEUE_TYPE`
+  - `SQS_MESSAGE_GROUP_ID`
+  - `SQS_MAX_MESSAGES`
+  - `SQS_WAIT_TIME_SECONDS`
+  - `SQS_VISIBILITY_TIMEOUT`
+  - File queue:
+  - `FILE_SQS_REGION`
+  - `FILE_SQS_ENDPOINT`
+  - `FILE_SQS_QUEUE_URL`
+  - `FILE_SQS_QUEUE_TYPE`
+  - `FILE_SQS_MESSAGE_GROUP_ID`
+  - `FILE_SQS_MAX_MESSAGES`
+  - `FILE_SQS_WAIT_TIME_SECONDS`
+  - `FILE_SQS_VISIBILITY_TIMEOUT`
+  - `FILE_SQS_ALLOW_INSECURE_ENDPOINT`
+- File storage (S3)
+  - `FILE_STORAGE_PROVIDER`
+  - `FILE_S3_BUCKET`
+  - `FILE_S3_REGION`
+  - `FILE_S3_ENDPOINT`
+  - `FILE_S3_FORCE_PATH_STYLE`
+  - `FILE_S3_ALLOW_INSECURE_ENDPOINT`
+  - `FILE_S3_AUTO_CREATE_BUCKET`
+  - `FILE_OBJECT_KEY_PREFIX`
+  - `FILE_S3_PRESIGN_PUT_TTL`
+  - `FILE_S3_PRESIGN_GET_TTL`
+- WOPI / Collabora
+  - `WOPI_TOKEN_SECRET`
+  - `WOPI_PROOF_SECRET`
+  - `WOPI_DISCOVERY_URL`
+  - `WOPI_PUBLIC_BASE_URL`
+  - `WOPI_EDIT_ACTION_URL`
+  - `WOPI_TOKEN_TTL`
+  - `WOPI_MAX_BODY_BYTES`
+  - `WOPI_REQUIRE_PROOF`
+- Worker mode selector
+  - `WORKER_JOB=email`
+  - `WORKER_JOB=file_processing`
+
+## WOPI / Collabora Hardening
+
+- Keep WOPI endpoints behind the dedicated `/wopi` router and do not expose them through the session-authenticated app middleware chain.
+- Use HTTPS end to end in production.
+- Restrict network access to the Collabora host or private network allowlist.
+- Set Collabora `aliasgroup`/host configuration so it can only call back to this backend.
+- Keep `WOPI_TOKEN_SECRET` and `WOPI_PROOF_SECRET` in env or a secrets manager and rotate them periodically.
+- Scope IAM to the minimum S3 bucket/prefix needed by file storage.
+- Keep direct S3 URLs disabled for editor access; the backend should proxy file bytes.
+- Ensure backend logs capture open/save/exit-save events for auditability.
+- Verify `/hosting/discovery` reachability and S3 connectivity in health checks before enabling Collabora traffic.
+
+Per-dependency overrides are supported with the same shape as the default block:
+
+- `CB_MICROSOFT_SSO_*`
+- `CB_SES_*`
+- `CB_SQS_*`
+
+Example: `CB_SES_TIMEOUT=45s` or `CB_SQS_CONSECUTIVE_FAILURES=3`.
+
+## Circuit Breakers
+
+- Breakers are scoped per outbound dependency, not per HTTP endpoint and not global middleware.
+- MySQL repositories and internal business logic are intentionally not wrapped.
+- Only dependency-health failures count toward opening the breaker.
+  - Microsoft SSO: network errors, timeouts, HTTP `429`, and `5xx`
+  - SES: network errors, throttling, and AWS server faults
+  - SQS: network errors, throttling, and AWS server faults
+- Client/config/input errors are excluded so they do not open the breaker.
+- State transitions are logged through the standard application logger.
+
+## Queue Behavior
+
+- Long polling is enabled through `SQS_WAIT_TIME_SECONDS`.
+- Messages are deleted only after successful processing or explicit ack of duplicates.
+- Transient failures use `ChangeMessageVisibility` with backoff.
+- Permanent failures are left unacked so SQS redrive policy can move them to the DLQ.
+- The default producer schema is `v2`; legacy payload fallback remains available for older messages.
+- Configure DLQ on the queue itself in AWS/LocalStack. The application no longer publishes directly to a DLQ URL.
+
+## Prometheus Metrics
+
+Scrape endpoints:
+
+- API: `http://<api-host>:8080/metrics`
+- Email worker monitor: `http://<worker-host>:9090/metrics`
+- File worker monitor: `http://<worker-host>:9091/metrics`
+
+Example Prometheus scrape config:
+
+```yaml
+scrape_configs:
+  - job_name: "wucher-api"
+    static_configs:
+      - targets: ["127.0.0.1:8080"]
+  - job_name: "wucher-email-worker"
+    static_configs:
+      - targets: ["127.0.0.1:9090"]
+  - job_name: "wucher-file-worker"
+    static_configs:
+      - targets: ["127.0.0.1:9091"]
+```
+
+Metrics and labels:
+
+- `app_aws_requests_total{component,service,operation,result}`
+- `app_aws_request_duration_seconds{component,service,operation}`
+- `app_aws_errors_total{component,service,operation,error_class}` where `error_class` is `4xx`, `5xx`, or `other`
+- `app_aws_transferred_bytes_total{component,service,operation,direction}`
+- `app_queue_messages_received_total{component,queue_name}`
+- `app_queue_messages_deleted_total{component,queue_name}`
+- `app_queue_visibility_changes_total{component,queue_name,result}`
+- `app_queue_send_total{component,queue_name,result}`
+- `app_queue_retries_total{component,queue_name,result}`
+- `app_queue_message_bytes_total{component,queue_name,direction}`
+- `app_queue_depth{component,queue_name}`
+- `app_worker_jobs_processed_total{component,job_type,result}`
+- `app_worker_job_duration_seconds{component,job_type}`
+- `app_email_send_total{component,provider,result}`
+- `app_email_send_duration_seconds{component,provider}`
+- `app_file_upload_total{component,result}`
+- `app_file_delete_total{component,result}`
+- `app_file_head_total{component,result}`
+- `app_file_presign_download_total{component,result}`
+
+PromQL examples:
+
+- Error rate per AWS operation:
+
+```promql
+sum by (component, service, operation) (rate(app_aws_requests_total{result="error"}[5m]))
+/
+clamp_min(sum by (component, service, operation) (rate(app_aws_requests_total[5m])), 1e-9)
+```
+
+- P95 latency per AWS operation:
+
+```promql
+histogram_quantile(
+  0.95,
+  sum by (le, component, service, operation) (
+    rate(app_aws_request_duration_seconds_bucket[5m])
+  )
+)
+```
+
+- Queue depth:
+
+```promql
+max by (component, queue_name) (app_queue_depth)
+```
+
+- Worker success/failure count:
+
+```promql
+sum by (component, job_type, result) (increase(app_worker_jobs_processed_total[15m]))
+```
+
+- SES send failure rate:
+
+```promql
+sum by (component) (rate(app_email_send_total{provider="ses", result="error"}[5m]))
+/
+clamp_min(sum by (component) (rate(app_email_send_total{provider="ses"}[5m])), 1e-9)
+```
+
+- S3 4xx/5xx error rate:
+
+```promql
+sum by (operation, error_class) (rate(app_aws_errors_total{service="s3"}[5m]))
+```
+
+- S3 GetObject transferred bytes (estimated from presign download flow):
+
+```promql
+sum by (component) (rate(app_aws_transferred_bytes_total{service="s3",operation="getobject",direction="download"}[5m]))
+```
+
+- SQS message bytes in/out:
+
+```promql
+sum by (component, queue_name, direction) (rate(app_queue_message_bytes_total[5m]))
+```
+
+- SQS retry/requeue count:
+
+```promql
+sum by (component, queue_name, result) (increase(app_queue_retries_total[15m]))
+```
+
+## File Manager
+
+- Queue separation:
+  - Email queue: `app-queue` (+ `app-queue-dlq`)
+  - File queue: `app-file-queue` (+ `app-file-queue-dlq`)
+- `FILE_SQS_QUEUE_URL` must be different from `SQS_QUEUE_URL`.
+- API startup validates queue separation and refuses startup on misconfiguration.
+- Upload writes file metadata + file outbox durably; file queue publish is handled asynchronously by the file outbox dispatcher.
+
+Local run checklist:
+
+```bash
+# 1) Start localstack (queue + bucket bootstrap script will run)
+cd ../localstack && docker compose up -d
+
+WORKER_JOB=file_processing go run ./cmd/worker
+```
+
+## SES Delivery Notes
+
+- `EMAIL_PROVIDER=mock` is the recommended local/dev default when you do not have real AWS SES access.
+- Mock delivery writes one JSON file per delivered email into `EMAIL_MOCK_DIR`.
+- `SES_FROM` must be a verified identity or domain in Amazon SES.
+- `SES_ENDPOINT` should be blank in production and only overridden for local/dev stacks such as LocalStack.
+- Do not point SES events to the main send queue. Use `SES_CONFIGURATION_SET` with SNS -> separate SQS event queue.
+- The codebase includes an SES event parser for SNS-wrapped notifications, but an event consumer is not started by default.
+
+## Migration Notes
+
+Detailed migration notes are in [docs/queue-sqs-migration.md](docs/queue-sqs-migration.md).
+Data migration tracking wiki is in [docs/data-migration-wiki.md](docs/data-migration-wiki.md).
+
+Main breaking changes:
+
+- Redis runtime support has been removed from the codebase.
+- Redis env vars are obsolete and should be removed from deployment config.
+- SMTP runtime env/config has been removed in favor of SES.
+- Worker now relies on MySQL for queue idempotency and auth/runtime state persistence.
+- SQS must have a redrive policy and DLQ configured outside the application.
+
+## CI / Build Selection
+
+The pipeline always builds and pushes the `api` image on every push to `development` or `staging`.
+
+To also build and push the worker or file-worker image, include the corresponding tag anywhere in the commit message:
+
+| Tag | Image built | Docker target |
+|---|---|---|
+| `#PUSH-WORKER` | `mybitlab/wfm:<tag>-worker` | `worker` |
+| `#PUSH-FILE-WORKER` | `mybitlab/wfm:<tag>-file-worker` | `file-worker` |
+
+Both tags can appear in the same commit message to build all three in one pipeline run:
+
+```
+ci: deploy all services #PUSH-WORKER #PUSH-FILE-WORKER
+```
+
+Omitting a tag skips that image entirely — it will not be built or pushed.
+
+## Testing
+
+Run the full test suite:
+
+```bash
+go test ./...
+```
+
+Generate coverage:
+
+```bash
+go test ./... -coverprofile=coverage.out
+go tool cover -func=coverage.out
+go tool cover -html=coverage.out -o coverage.html
+```
diff --git a/api b/api
new file mode 100644
index 0000000..4c8daa5
Binary files /dev/null and b/api differ
diff --git a/cmd/api/main.go b/cmd/api/main.go
new file mode 100644
index 0000000..57e57f1
--- /dev/null
+++ b/cmd/api/main.go
@@ -0,0 +1,392 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"wucher/internal/app/api"
+	"wucher/internal/config"
+	"wucher/internal/service"
+
+	_ "wucher/docs"
+)
+
+var (
+	apiRunFn   = run
+	apiFatalFn = log.Fatal
+)
+
+func configFilePath() string {
+	if v := os.Getenv("CONFIG_FILE"); v != "" {
+		return v
+	}
+	basePath := os.Getenv("CONFIG_BASE_PATH")
+	if basePath == "" {
+		basePath = "/tmp"
+	}
+	filename := os.Getenv("CONFIG_FILENAME")
+	if filename == "" {
+		filename = "config.generated.json"
+	}
+	return basePath + "/" + filename
+}
+
+type apiServer interface {
+	Start(addr string) error
+	Shutdown(ctx context.Context) error
+}
+
+// @title Wucher API
+// @version 1.0
+// @description Wucher backend API (JSON:API).
+// @description
+// @description Auth Flow (Email/Password):
+// @description 1) POST /api/v1/auth/register
+// @description 2) Check email, open verify link (GET /api/v1/auth/verify-email)
+// @description 3) POST /api/v1/auth/login
+// @description - If TOTP enabled: response 202 with challenge_token
+// @description 4) POST /api/v1/auth/totp/verify (challenge_token + code) -> cookies
+// @description
+// @description Auth Flow (TOTP setup):
+// @description 1) POST /api/v1/auth/totp/setup -> secret + otpauth_url (enabled=false)
+// @description 2) POST /api/v1/auth/totp/confirm -> enabled=true
+// @description
+// @description Auth Flow (Microsoft Entra SSO):
+// @description 1) GET /api/v1/auth/microsoft/login -> redirect to Microsoft
+// @description 2) Microsoft redirects to /api/v1/auth/microsoft/callback
+// @description 3) Backend checks existing SSO mapping (no auto-register)
+// @description 4) If linked user exists -> set cookies + optional redirect to AUTH_SSO_SUCCESS_REDIRECT
+// @description 5) If mapping not linked -> login rejected (401)
+// @description 6) Existing authenticated user can link/unlink via /api/v1/auth/sso/link and /api/v1/auth/sso/unlink
+// @tag.name Complaints - Sign Off
+// @tag.description Corrective-action sign-off for a helicopter. After a complaint's action_taken is recorded, it is signed off here (POST /action-signoffs/sign with complaint_id); a fleet-wide sign-off (no complaint_id) is also supported. A signed sign-off is the prerequisite for creating an EASA maintenance release.
+// @BasePath /
+func main() {
+	if err := apiRunFn(); err != nil {
+		apiFatalFn(err)
+	}
+}
+
+func run() error {
+	appCfg, err := config.LoadFromFile(configFilePath())
+	if err != nil {
+		return fmt.Errorf("load config: %w", err)
+	}
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+	return runWithContext(ctx, appCfg)
+}
+
+func runWithContext(ctx context.Context, appCfg config.AppConfig) error {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+
+	db, err := initializeDatabase(appCfg.MySQL)
+	if err != nil {
+		return err
+	}
+	if sqlDB, sqlErr := db.DB(); sqlErr == nil {
+		defer sqlDB.Close()
+	}
+
+	if err := bootstrapData(db); err != nil {
+		return err
+	}
+	repos, err := initializeRepositories(db)
+	if err != nil {
+		return err
+	}
+	infra, err := initializeInfrastructure(ctx, appCfg, db)
+	if err != nil {
+		return err
+	}
+	services, err := initializeServices(appCfg, repos, infra)
+	if err != nil {
+		return err
+	}
+	if err := services.MasterSettings.SeedMicrosoftEntraConfigIfMissing(ctx, appCfg.MicrosoftSSO); err != nil {
+		return fmt.Errorf("seed microsoft entra master settings: %w", err)
+	}
+	handlersSet, err := initializeHandlers(services, infra)
+	if err != nil {
+		return err
+	}
+	if err := initializeRealtimeComponents(ctx, repos, services, infra); err != nil {
+		return err
+	}
+
+	app, addr, err := buildHTTPServer(appCfg, services, handlersSet, infra)
+	if err != nil {
+		return err
+	}
+	srv := api.NewServer(app, api.WithShutdownTimeout(appCfg.HTTP.ShutdownTimeout))
+
+	infra.Logger.Info("api listening",
+		"addr", addr,
+		"queue_backend", "sqs",
+		"queue_outbox_enabled", appCfg.Queue.OutboxEnabled,
+	)
+	if err := serveAPI(ctx, srv, addr); err != nil {
+		return err
+	}
+	infra.Logger.Info("api stopped")
+	return nil
+}
+
+func serveAPI(ctx context.Context, srv apiServer, addr string) error {
+	if srv == nil {
+		return errors.New("api server is required")
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+
+	serverErrCh := make(chan error, 1)
+	go func() {
+		serverErrCh <- srv.Start(addr)
+	}()
+
+	select {
+	case err := <-serverErrCh:
+		return err
+	case <-ctx.Done():
+	}
+
+	shutdownErr := srv.Shutdown(context.Background())
+	serverErr := <-serverErrCh
+	if shutdownErr != nil {
+		return shutdownErr
+	}
+	return serverErr
+}
+
+func startFileManagerAutoPurgeLoop(
+	ctx context.Context,
+	fileManagerSvc *service.FileManagerService,
+	trashCfg config.FileManagerTrashPolicyConfig,
+	logger *slog.Logger,
+) {
+	if fileManagerSvc == nil || !trashCfg.AutoPurgeEnabled {
+		return
+	}
+	interval := trashCfg.AutoPurgeInterval
+	if interval <= 0 {
+		interval = time.Hour
+	}
+	batchSize := trashCfg.AutoPurgeBatchSize
+	if batchSize <= 0 {
+		batchSize = 200
+	}
+
+	runOnce := func() {
+		purgedFiles, purgedFolders, err := fileManagerSvc.PurgeExpiredTrash(ctx, time.Now().UTC(), batchSize)
+		if err != nil {
+			if logger != nil {
+				logger.Error("file manager auto-purge run failed", "error", err)
+			}
+			return
+		}
+		if logger != nil && (purgedFiles > 0 || purgedFolders > 0) {
+			logger.Info(
+				"file manager auto-purge completed",
+				"purged_files", purgedFiles,
+				"purged_folders", purgedFolders,
+				"batch_size", batchSize,
+			)
+		}
+	}
+
+	go func() {
+		ticker := time.NewTicker(interval)
+		defer ticker.Stop()
+		runOnce()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				runOnce()
+			}
+		}
+	}()
+}
+
+func startFleetStatusAOGRecomputeLoop(
+	ctx context.Context,
+	fleetStatusSvc *service.FleetStatusService,
+	logger *slog.Logger,
+) {
+	if fleetStatusSvc == nil {
+		return
+	}
+	// TESTING ONLY: sweep tiap menit supaya kolom AOG + audit nyusul cepat dengan
+	// MEL grace yang sementara dihitung dalam menit.
+	// TODO: kembalikan ke time.Hour sebelum production.
+	interval := time.Minute
+	runOnce := func() {
+		n, err := fleetStatusSvc.RecalculateAllAOG(ctx)
+		if err != nil {
+			if logger != nil {
+				logger.Error("fleet status AOG recompute failed", "error", err)
+			}
+			return
+		}
+		if logger != nil {
+			logger.Info("fleet status AOG recompute completed", "helicopters", n)
+		}
+	}
+	go func() {
+		ticker := time.NewTicker(interval)
+		defer ticker.Stop()
+		runOnce()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				runOnce()
+			}
+		}
+	}()
+}
+
+func startFileManagerLifecycleCleanupLoop(
+	ctx context.Context,
+	fileManagerSvc *service.FileManagerService,
+	lifecycleCfg config.FileManagerLifecycleConfig,
+	logger *slog.Logger,
+) {
+	if fileManagerSvc == nil || !lifecycleCfg.EnableCleanupJob {
+		return
+	}
+	interval := time.Hour
+	batchSize := lifecycleCfg.CleanupBatchSize
+	if batchSize <= 0 {
+		batchSize = 100
+	}
+	grace := time.Duration(lifecycleCfg.OrphanGraceDays) * 24 * time.Hour
+	tempGrace := time.Duration(lifecycleCfg.TempUploadGraceHours) * time.Hour
+	dryRun := lifecycleCfg.CleanupDryRun
+
+	runOnce := func() {
+		stats, err := fileManagerSvc.CleanupOrphanPendingFiles(ctx, time.Now().UTC(), grace, batchSize, dryRun)
+		if err != nil {
+			if logger != nil {
+				logger.Error("file manager lifecycle cleanup failed", "error", err)
+			}
+			return
+		}
+		if logger != nil {
+			logger.Info("file manager lifecycle cleanup run completed",
+				"scanned", stats.Scanned,
+				"deleted", stats.Deleted,
+				"skipped", stats.Skipped,
+				"failed", stats.Failed,
+				"dry_run", stats.DryRun,
+				"batch_size", batchSize,
+			)
+		}
+
+		tempStats, err := fileManagerSvc.CleanupStaleTempUploads(ctx, time.Now().UTC(), tempGrace, batchSize, dryRun)
+		if err != nil {
+			if logger != nil {
+				logger.Error("file manager temp upload cleanup failed", "error", err)
+			}
+			return
+		}
+		if logger != nil {
+			logger.Info("file manager temp upload cleanup run completed",
+				"scanned", tempStats.Scanned,
+				"deleted", tempStats.Deleted,
+				"skipped", tempStats.Skipped,
+				"failed", tempStats.Failed,
+				"dry_run", tempStats.DryRun,
+				"batch_size", batchSize,
+			)
+		}
+
+		draftStats, err := fileManagerSvc.CleanupStaleDraftFiles(ctx, time.Now().UTC(), tempGrace, batchSize, dryRun)
+		if err != nil {
+			if logger != nil {
+				logger.Error("file manager draft cleanup failed", "error", err)
+			}
+			return
+		}
+		if logger != nil {
+			logger.Info("file manager draft cleanup run completed",
+				"scanned", draftStats.Scanned,
+				"deleted", draftStats.Deleted,
+				"skipped", draftStats.Skipped,
+				"failed", draftStats.Failed,
+				"dry_run", draftStats.DryRun,
+				"batch_size", batchSize,
+			)
+		}
+	}
+
+	go func() {
+		ticker := time.NewTicker(interval)
+		defer ticker.Stop()
+		runOnce()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				runOnce()
+			}
+		}
+	}()
+}
+
+func startHelicopterFileAttachmentReconcileLoop(
+	ctx context.Context,
+	helicopterFileSvc *service.HelicopterFileService,
+	logger *slog.Logger,
+) {
+	if helicopterFileSvc == nil {
+		return
+	}
+	interval := 2 * time.Second
+	batchSize := 50
+
+	runOnce := func() int {
+		finalized, err := helicopterFileSvc.FinalizePendingAttachments(ctx, batchSize)
+		if err != nil {
+			if logger != nil {
+				logger.Error("helicopter file attachment reconcile failed", "error", err)
+			}
+			return 0
+		}
+		if logger != nil && finalized > 0 {
+			logger.Info("helicopter file attachment reconcile completed", "finalized", finalized, "batch_size", batchSize)
+		}
+		return finalized
+	}
+
+	go func() {
+		ticker := time.NewTicker(interval)
+		defer ticker.Stop()
+		for {
+			if ctx.Err() != nil {
+				return
+			}
+			if finalized := runOnce(); finalized > 0 {
+				continue
+			}
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+			}
+		}
+	}()
+}
diff --git a/cmd/api/main_test.go b/cmd/api/main_test.go
new file mode 100644
index 0000000..dcf05c5
--- /dev/null
+++ b/cmd/api/main_test.go
@@ -0,0 +1,153 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+)
+
+func TestMain_RunSuccess(t *testing.T) {
+	origRun := apiRunFn
+	origFatal := apiFatalFn
+	t.Cleanup(func() {
+		apiRunFn = origRun
+		apiFatalFn = origFatal
+	})
+
+	runCalled := false
+	fatalCalled := false
+	apiRunFn = func() error {
+		runCalled = true
+		return nil
+	}
+	apiFatalFn = func(v ...any) {
+		fatalCalled = true
+	}
+
+	main()
+
+	if !runCalled {
+		t.Fatalf("expected main to call run function")
+	}
+	if fatalCalled {
+		t.Fatalf("did not expect fatal function on successful run")
+	}
+}
+
+func TestMain_RunErrorCallsFatal(t *testing.T) {
+	origRun := apiRunFn
+	origFatal := apiFatalFn
+	t.Cleanup(func() {
+		apiRunFn = origRun
+		apiFatalFn = origFatal
+	})
+
+	errBoom := errors.New("boom")
+	fatalCalled := false
+	var fatalArgs []any
+
+	apiRunFn = func() error {
+		return errBoom
+	}
+	apiFatalFn = func(v ...any) {
+		fatalCalled = true
+		fatalArgs = v
+	}
+
+	main()
+
+	if !fatalCalled {
+		t.Fatalf("expected fatal function to be called on run error")
+	}
+	if len(fatalArgs) != 1 || fatalArgs[0] != errBoom {
+		t.Fatalf("unexpected fatal args: %#v", fatalArgs)
+	}
+}
+
+func TestServeAPI_StartError(t *testing.T) {
+	errBoom := errors.New("boom")
+	srv := &stubAPIServer{startErr: errBoom}
+
+	err := serveAPI(context.Background(), srv, ":8080")
+	if !errors.Is(err, errBoom) {
+		t.Fatalf("expected %v, got %v", errBoom, err)
+	}
+	if srv.shutdownCalled {
+		t.Fatalf("did not expect shutdown to be called on start error")
+	}
+}
+
+func TestServeAPI_ShutsDownOnContextCancel(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	srv := &stubAPIServer{
+		started:      make(chan struct{}),
+		releaseStart: make(chan struct{}),
+	}
+
+	errCh := make(chan error, 1)
+	go func() {
+		errCh <- serveAPI(ctx, srv, ":8080")
+	}()
+
+	<-srv.started
+	cancel()
+
+	if err := <-errCh; err != nil {
+		t.Fatalf("expected nil error, got %v", err)
+	}
+	if !srv.shutdownCalled {
+		t.Fatalf("expected shutdown to be called")
+	}
+}
+
+func TestServeAPI_ReturnsShutdownError(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	errBoom := errors.New("shutdown failed")
+	srv := &stubAPIServer{
+		started:      make(chan struct{}),
+		releaseStart: make(chan struct{}),
+		shutdownErr:  errBoom,
+	}
+
+	errCh := make(chan error, 1)
+	go func() {
+		errCh <- serveAPI(ctx, srv, ":8080")
+	}()
+
+	<-srv.started
+	cancel()
+
+	if err := <-errCh; !errors.Is(err, errBoom) {
+		t.Fatalf("expected %v, got %v", errBoom, err)
+	}
+}
+
+type stubAPIServer struct {
+	startErr       error
+	shutdownErr    error
+	started        chan struct{}
+	releaseStart   chan struct{}
+	shutdownCalled bool
+	releaseOnce    sync.Once
+}
+
+func (s *stubAPIServer) Start(string) error {
+	if s.started != nil {
+		close(s.started)
+	}
+	if s.releaseStart != nil {
+		<-s.releaseStart
+	}
+	return s.startErr
+}
+
+func (s *stubAPIServer) Shutdown(context.Context) error {
+	s.shutdownCalled = true
+	if s.releaseStart != nil {
+		s.releaseOnce.Do(func() {
+			close(s.releaseStart)
+		})
+	}
+	return s.shutdownErr
+}
diff --git a/cmd/api/startup.go b/cmd/api/startup.go
new file mode 100644
index 0000000..89fc419
--- /dev/null
+++ b/cmd/api/startup.go
@@ -0,0 +1,834 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/app/api"
+	queueapp "wucher/internal/app/queueing"
+	samlauth "wucher/internal/auth"
+	"wucher/internal/config"
+	filemanager "wucher/internal/domain/file_manager"
+	filemanagerrealtime "wucher/internal/realtime/filemanager"
+	helicopterfilerealtime "wucher/internal/realtime/helicopterfile"
+	"wucher/internal/repository/mysql"
+	s3repo "wucher/internal/repository/s3"
+	"wucher/internal/resilience"
+	"wucher/internal/service"
+	pkglogger "wucher/internal/shared/pkg/logger"
+	tzpkg "wucher/internal/shared/pkg/timezone"
+	userctx "wucher/internal/shared/pkg/userctx"
+	"wucher/internal/transport/http/handlers"
+)
+
+type Repositories struct {
+	User                          *mysql.UserRepository
+	Contact                       *mysql.ContactRepository
+	Role                          *mysql.RoleRepository
+	Helicopter                    *mysql.HelicopterRepository
+	HelicopterUsage               *mysql.HelicopterUsageRepository
+	FlightInspection              *mysql.FlightInspectionRepository
+	Flight                        *mysql.FlightRepository
+	FlightData                    *mysql.FlightDataRepository
+	Mission                       *mysql.MissionRepository
+	ReserveAc                     *mysql.ReserveAcRepository
+	HelicopterFile                *mysql.HelicopterFileRepository
+	FlightInspectionFileChecklist *mysql.FlightInspectionFileChecklistRepository
+	BeforeFlightInspection        *mysql.BeforeFlightInspectionRepository
+	AfterFlightInspection         *mysql.AfterFlightInspectionRepository
+	FMReport                      *mysql.FMReportRepository
+	FlightPrepCheck               *mysql.FlightPrepCheckRepository
+	Facility                      *mysql.FacilityRepository
+	Base                          *mysql.BaseRepository
+	Medicine                      *mysql.MedicineRepository
+	Vocation                      *mysql.VocationRepository
+	Opc                           *mysql.OpcRepository
+	ForcesPresent                 *mysql.ForcesPresentRepository
+	Hospital                      *mysql.HospitalRepository
+	HealthInsuranceCompanies      *mysql.HealthInsuranceCompaniesRepository
+	FederalState                  *mysql.FederalStateRepository
+	ICAO                          *mysql.ICAORepository
+	Land                          *mysql.LandRepository
+	Complaint                     *mysql.ComplaintRepository
+	EASARelease                   *mysql.EASAReleaseRepository
+	ActionSignoff                 *mysql.ActionSignoffRepository
+	OtherPerson                   *mysql.OtherPersonRepository
+	MCF                           *mysql.MCFRepository
+	FleetHistory                  *mysql.FleetHistoryRepository
+	HEMSOperationalData           *mysql.HEMSOperationalDataRepository
+	HEMSOperationCategory         *mysql.HEMSOperationCategoryRepository
+	HEMSOperation                 *mysql.HEMSOperationRepository
+	MasterSettings                *mysql.MasterSettingsRepository
+	FileManagerFolder             *mysql.FileManagerFolderRepository
+	FileManagerFile               *mysql.FileManagerFileRepository
+	FileManagerAttachment         *mysql.FileManagerAttachmentRepository
+	DutyRoster                    *mysql.DutyRosterRepository
+	AirRescuerChecklist           *mysql.AirRescuerChecklistRepository
+	InsurancePatientData          *mysql.InsurancePatientDataRepository
+	PatientData                   *mysql.PatientDataRepository
+	DUL                           *mysql.DULRepository
+	FleetStatus                   *mysql.FleetStatusRepository
+	TokenStore                    *mysql.TokenStore
+	Auth                          *mysql.AuthRepository
+	Audit                         *mysql.AuditRepository
+}
+
+type Infrastructure struct {
+	DB                *gorm.DB
+	Logger            *slog.Logger
+	SQSBreaker        *resilience.Executor
+	FileStorage       filemanager.ObjectStorage
+	EmailQueue        service.EmailQueue
+	FileQueue         filemanager.FileProcessingQueue
+	FileStatusHub     *filemanagerrealtime.Hub
+	HelicopterFileHub *helicopterfilerealtime.Hub
+	FileTrashPolicy   config.FileManagerTrashPolicyConfig
+	FileLifecycle     config.FileManagerLifecycleConfig
+}
+
+type Services struct {
+	User                      *service.UserService
+	Contact                   *service.ContactService
+	Role                      *service.RoleService
+	Helicopter                *service.HelicopterService
+	HelicopterUsage           *service.HelicopterUsageService
+	FlightInspection          *service.FlightInspectionService
+	Flight                    *service.FlightService
+	FlightData                *service.FlightDataService
+	Mission                   *service.MissionService
+	ReserveAc                 *service.ReserveAcService
+	Takeover                  *service.TakeoverService
+	OtherPerson               *service.OtherPersonService
+	HelicopterFile            *service.HelicopterFileService
+	FlightInspectionChecklist *service.FlightInspectionFileChecklistService
+	BeforeFlightInspection    *service.BeforeFlightInspectionService
+	AfterFlightInspection     *service.AfterFlightInspectionService
+	FMReport                  *service.FMReportService
+	FlightPrepCheck           *service.FlightPrepCheckService
+	Facility                  *service.FacilityService
+	Base                      *service.BaseService
+	Medicine                  *service.MedicineService
+	Vocation                  *service.VocationService
+	Opc                       *service.OpcService
+	ForcesPresent             *service.ForcesPresentService
+	Hospital                  *service.HospitalService
+	HealthInsuranceCompanies  *service.HealthInsuranceCompaniesService
+	FederalState              *service.FederalStateService
+	ICAO                      *service.ICAOService
+	Land                      *service.LandService
+	Complaint                 *service.ComplaintService
+	EASARelease               *service.EASAReleaseService
+	ActionSignoff             *service.ActionSignoffService
+	MCF                       *service.MCFService
+	FleetHistory              *service.FleetHistoryService
+	HEMSOperationalData       *service.HEMSOperationalDataService
+	HEMSOperationCategory     *service.HEMSOperationCategoryService
+	HEMSOperation             *service.HEMSOperationService
+	MasterSettings            *service.MasterSettingsService
+	FileManager               *service.FileManagerService
+	DutyRoster                *service.DutyRosterService
+	AirRescuerChecklist       *service.AirRescuerChecklistService
+	InsurancePatientData      *service.InsurancePatientDataService
+	PatientData               *service.PatientDataService
+	DUL                       *service.DULService
+	FleetStatus               *service.FleetStatusService
+	WOPI                      *service.WOPIService
+	Auth                      *service.AuthService
+	Audit                     *service.AuditLogService
+}
+
+type Handlers struct {
+	User                     *handlers.UserHandler
+	Contact                  *handlers.ContactHandler
+	Health                   *handlers.HealthHandler
+	BuildInfo                *handlers.BuildInfoHandler
+	Auth                     *handlers.AuthHandler
+	Role                     *handlers.RoleHandler
+	Helicopter               *handlers.HelicopterHandler
+	HelicopterUsage          *handlers.HelicopterUsageHandler
+	HelicopterFile           *handlers.HelicopterFileHandler
+	Flight                   *handlers.FlightHandler
+	FlightData               *handlers.FlightDataHandler
+	Mission                  *handlers.MissionHandler
+	FMReport                 *handlers.FMReportHandler
+	ReserveAc                *handlers.ReserveAcHandler
+	Takeover                 *handlers.TakeoverHandler
+	OtherPerson              *handlers.OtherPersonHandler
+	Facility                 *handlers.FacilityHandler
+	Base                     *handlers.BaseHandler
+	Medicine                 *handlers.MedicineHandler
+	Vocation                 *handlers.VocationHandler
+	Opc                      *handlers.OpcHandler
+	ForcesPresent            *handlers.ForcesPresentHandler
+	Hospital                 *handlers.HospitalHandler
+	HealthInsuranceCompanies *handlers.HealthInsuranceCompaniesHandler
+	FederalState             *handlers.FederalStateHandler
+	ICAO                     *handlers.ICAOHandler
+	Land                     *handlers.LandHandler
+	MasterSettings           *handlers.MasterSettingsHandler
+	Branding                 *handlers.BrandingHandler
+	FileManagerFolder        *handlers.FileManagerFolderHandler
+	FileManagerFile          *handlers.FileManagerFileHandler
+	FileManagerAttachment    *handlers.FileManagerAttachmentHandler
+	FileManagerEvents        *handlers.FileManagerEventsHandler
+	HelicopterFileEvents     *handlers.HelicopterFileEventsHandler
+	DutyRoster               *handlers.DutyRosterHandler
+	AirRescuerChecklist      *handlers.AirRescuerChecklistHandler
+	InsurancePatientData     *handlers.InsurancePatientDataHandler
+	PatientData              *handlers.PatientDataHandler
+	DUL                      *handlers.DULHandler
+	FleetStatus              *handlers.FleetStatusHandler
+	HEMSOperationalData      *handlers.HEMSOperationalDataHandler
+	HEMSOperationCategory    *handlers.HEMSOperationCategoryHandler
+	HEMSOperation            *handlers.HEMSOperationHandler
+	Complaint                *handlers.ComplaintHandler
+	EASARelease              *handlers.EASAReleaseHandler
+	ActionSignoff            *handlers.ActionSignoffHandler
+	MCF                      *handlers.MCFHandler
+}
+
+func initializeDatabase(mysqlCfg config.MySQLConfig) (*gorm.DB, error) {
+	return mysql.Connect(mysqlCfg)
+}
+
+func bootstrapData(db *gorm.DB) error {
+	if err := mysql.AutoMigrate(db); err != nil {
+		return fmt.Errorf("auto migrate: %w", err)
+	}
+	if err := db.Exec("UPDATE users SET timezone = ? WHERE timezone IS NULL OR timezone = ''", tzpkg.Default).Error; err != nil {
+		return fmt.Errorf("seed users timezone default: %w", err)
+	}
+	if err := api.SeedRoles(db); err != nil {
+		return fmt.Errorf("seed roles: %w", err)
+	}
+	if err := api.SeedPermissions(db); err != nil {
+		return fmt.Errorf("seed permissions: %w", err)
+	}
+	if err := api.SeedRolePermissions(db); err != nil {
+		return fmt.Errorf("seed role permissions: %w", err)
+	}
+	if err := api.SeedBaseCategories(db); err != nil {
+		return fmt.Errorf("seed base categories: %w", err)
+	}
+	if strings.EqualFold(strings.TrimSpace(os.Getenv("SEED_ROSTER_USERS")), "true") {
+		if err := api.SeedRosterUsers(db); err != nil {
+			return fmt.Errorf("seed roster users: %w", err)
+		}
+	}
+	return nil
+}
+
+func initializeRepositories(db *gorm.DB) (*Repositories, error) {
+	if db == nil {
+		return nil, errors.New("database is required")
+	}
+	repos := &Repositories{
+		User:                          mysql.NewUserRepository(db),
+		Contact:                       mysql.NewContactRepository(db),
+		Role:                          mysql.NewRoleRepository(db),
+		Helicopter:                    mysql.NewHelicopterRepository(db),
+		HelicopterUsage:               mysql.NewHelicopterUsageRepository(db),
+		FlightInspection:              mysql.NewFlightInspectionRepository(db),
+		Flight:                        mysql.NewFlightRepository(db),
+		FlightData:                    mysql.NewFlightDataRepository(db),
+		Mission:                       mysql.NewMissionRepository(db),
+		ReserveAc:                     mysql.NewReserveAcRepository(db),
+		HelicopterFile:                mysql.NewHelicopterFileRepository(db),
+		FlightInspectionFileChecklist: mysql.NewFlightInspectionFileChecklistRepository(db),
+		BeforeFlightInspection:        mysql.NewBeforeFlightInspectionRepository(db),
+		AfterFlightInspection:         mysql.NewAfterFlightInspectionRepository(db),
+		FMReport:                      mysql.NewFMReportRepository(db),
+		FlightPrepCheck:               mysql.NewFlightPrepCheckRepository(db),
+		Facility:                      mysql.NewFacilityRepository(db),
+		Base:                          mysql.NewBaseRepository(db),
+		Medicine:                      mysql.NewMedicineRepository(db),
+		Vocation:                      mysql.NewVocationRepository(db),
+		Opc:                           mysql.NewOpcRepository(db),
+		ForcesPresent:                 mysql.NewForcesPresentRepository(db),
+		Hospital:                      mysql.NewHospitalRepository(db),
+		HealthInsuranceCompanies:      mysql.NewHealthInsuranceCompaniesRepository(db),
+		FederalState:                  mysql.NewFederalStateRepository(db),
+		ICAO:                          mysql.NewICAORepository(db),
+		Land:                          mysql.NewLandRepository(db),
+		Complaint:                     mysql.NewComplaintRepository(db),
+		EASARelease:                   mysql.NewEASAReleaseRepository(db),
+		ActionSignoff:                 mysql.NewActionSignoffRepository(db),
+		OtherPerson:                   mysql.NewOtherPersonRepository(db),
+		MCF:                           mysql.NewMCFRepository(db),
+		FleetHistory:                  mysql.NewFleetHistoryRepository(db),
+		HEMSOperationalData:           mysql.NewHEMSOperationalDataRepository(db),
+		HEMSOperationCategory:         mysql.NewHEMSOperationCategoryRepository(db),
+		HEMSOperation:                 mysql.NewHEMSOperationRepository(db),
+		MasterSettings:                mysql.NewMasterSettingsRepository(db),
+		FileManagerFolder:             mysql.NewFileManagerFolderRepository(db),
+		FileManagerFile:               mysql.NewFileManagerFileRepository(db),
+		FileManagerAttachment:         mysql.NewFileManagerAttachmentRepository(db),
+		DutyRoster:                    mysql.NewDutyRosterRepository(db),
+		AirRescuerChecklist:           mysql.NewAirRescuerChecklistRepository(db),
+		InsurancePatientData:          mysql.NewInsurancePatientDataRepository(db),
+		PatientData:                   mysql.NewPatientDataRepository(db),
+		DUL:                           mysql.NewDULRepository(db),
+		FleetStatus:                   mysql.NewFleetStatusRepository(db),
+		TokenStore:                    mysql.NewTokenStore(db),
+		Auth:                          mysql.NewAuthRepository(db),
+		Audit:                         mysql.NewAuditRepository(db),
+	}
+	return repos, nil
+}
+
+func initializeInfrastructure(ctx context.Context, appCfg config.AppConfig, db *gorm.DB) (*Infrastructure, error) {
+	appLogger := pkglogger.New(appCfg.Logging).With("component", "api")
+	slog.SetDefault(appLogger)
+
+	if err := config.ValidateDistinctQueueURLs(appCfg.SQS, appCfg.FileSQS); err != nil {
+		return nil, err
+	}
+
+	resCfg := appCfg.Resilience
+	sqsBreaker := resilience.NewExecutor("sqs", resCfg.SQS, appLogger, resilience.ClassifySQSError)
+
+	var emailQueue service.EmailQueue
+	if !appCfg.Queue.OutboxEnabled {
+		emailProducer, err := queueapp.NewEmailProducer(ctx, appCfg.Queue, appCfg.SQS, sqsBreaker, appLogger)
+		if err != nil {
+			return nil, err
+		}
+		emailQueue = service.AdaptEmailQueue(emailProducer)
+	}
+
+	var fileStorage filemanager.ObjectStorage
+	if appCfg.FileStorage.Bucket != "" && appCfg.FileStorage.Region != "" {
+		storage, err := s3repo.NewFileObjectStorage(ctx, appCfg.FileStorage)
+		if err != nil {
+			return nil, err
+		}
+		fileStorage = storage
+	}
+
+	var fileQueue filemanager.FileProcessingQueue
+	if !appCfg.FileQueue.OutboxEnabled && strings.TrimSpace(appCfg.FileSQS.QueueURL) != "" {
+		fileProducer, err := queueapp.NewFileProcessingProducer(ctx, appCfg.FileQueue, appCfg.FileSQS, sqsBreaker, appLogger)
+		if err != nil {
+			return nil, err
+		}
+		fileQueue = service.AdaptFileProcessingQueue(fileProducer)
+	}
+
+	return &Infrastructure{
+		DB:                db,
+		Logger:            appLogger,
+		SQSBreaker:        sqsBreaker,
+		FileStorage:       fileStorage,
+		EmailQueue:        emailQueue,
+		FileQueue:         fileQueue,
+		FileStatusHub:     filemanagerrealtime.NewHub(64, appLogger),
+		HelicopterFileHub: helicopterfilerealtime.NewHub(64, appLogger),
+		FileTrashPolicy:   config.LoadFileManagerTrashPolicyConfigFromEnv(),
+		FileLifecycle:     config.LoadFileManagerLifecycleConfigFromEnv(),
+	}, nil
+}
+
+func initializeServices(appCfg config.AppConfig, repos *Repositories, infra *Infrastructure) (*Services, error) {
+	if repos == nil {
+		return nil, errors.New("repositories are required")
+	}
+	if infra == nil {
+		return nil, errors.New("infrastructure is required")
+	}
+
+	var protector service.SecretProtector
+	if p, err := service.NewAESGCMProtectorFromBase64(appCfg.Auth.TOTPSecretKeyB64); err == nil {
+		protector = p
+	}
+
+	fileManagerDeps := service.FileManagerServiceDependencies{
+		Storage:          infra.FileStorage,
+		FileQueue:        infra.FileQueue,
+		UploadPolicy:     filemanager.FileUploadPolicy{},
+		TrashRetention:   infra.FileTrashPolicy.Retention,
+		FileStatusEvents: repos.FileManagerFile,
+		Logger:           infra.Logger,
+		EnableS3Tagging:  infra.FileLifecycle.EnableS3Tagging,
+	}
+	if appCfg.FileQueue.OutboxEnabled {
+		fileManagerDeps.FileOutbox = repos.FileManagerFile
+		fileManagerDeps.FileOutboxSerializer = queueapp.NewFileProcessingSerializer(appCfg.FileQueue, appCfg.FileSQS)
+	}
+	fileManagerDeps.UploadPolicy = filemanager.FileUploadPolicy{
+		MaxFileSizeBytes:  appCfg.FileUpload.MaxFileSizeBytes,
+		AllowedMimeTypes:  appCfg.FileUpload.AllowedMimeTypes,
+		AllowedExtensions: appCfg.FileUpload.AllowedExtensions,
+		AllowEmptyFile:    appCfg.FileUpload.AllowEmptyFile,
+		MaxFilenameLength: appCfg.FileUpload.MaxFilenameLength,
+	}
+
+	flightDataSvc := service.NewFlightDataService(repos.FlightData)
+	flightSvc := service.NewFlightService(repos.Flight)
+	fileManagerSvc := service.NewFileManagerService(repos.FileManagerFolder, repos.FileManagerFile, repos.FileManagerAttachment, fileManagerDeps)
+	helicopterSvc := service.NewHelicopterService(repos.Helicopter)
+	helicopterUsageSvc := service.NewHelicopterUsageService(repos.HelicopterUsage)
+	afterFlightInspectionSvc := service.NewAfterFlightInspectionService(repos.AfterFlightInspection)
+
+	services := &Services{
+		User:                      service.NewUserService(repos.User),
+		Role:                      service.NewRoleService(repos.Role),
+		Helicopter:                helicopterSvc,
+		HelicopterUsage:           helicopterUsageSvc,
+		FlightInspection:          service.NewFlightInspectionService(repos.FlightInspection),
+		Flight:                    flightSvc,
+		FlightData:                flightDataSvc,
+		Mission:                   nil,
+		ReserveAc:                 service.NewReserveAcService(repos.ReserveAc),
+		Takeover:                  service.NewTakeoverService(infra.DB),
+		HelicopterFile:            service.NewHelicopterFileService(repos.HelicopterFile),
+		FlightInspectionChecklist: service.NewFlightInspectionFileChecklistService(repos.FlightInspectionFileChecklist),
+		BeforeFlightInspection:    service.NewBeforeFlightInspectionService(repos.BeforeFlightInspection),
+		AfterFlightInspection:     afterFlightInspectionSvc,
+		FMReport:                  service.NewFMReportService(repos.FMReport),
+		FlightPrepCheck:           service.NewFlightPrepCheckService(repos.FlightPrepCheck, repos.FlightInspection),
+		Facility:                  service.NewFacilityService(repos.Facility),
+		Base:                      service.NewBaseService(repos.Base),
+		Medicine:                  service.NewMedicineService(repos.Medicine),
+		Vocation:                  service.NewVocationService(repos.Vocation),
+		Opc:                       service.NewOpcService(repos.Opc),
+		ForcesPresent:             service.NewForcesPresentService(repos.ForcesPresent),
+		Hospital:                  service.NewHospitalService(repos.Hospital),
+		HealthInsuranceCompanies:  service.NewHealthInsuranceCompaniesService(repos.HealthInsuranceCompanies),
+		FederalState:              service.NewFederalStateService(repos.FederalState),
+		ICAO:                      service.NewICAOService(repos.ICAO),
+		Land:                      service.NewLandService(repos.Land),
+		Complaint:                 service.NewComplaintService(repos.Complaint),
+		EASARelease:               service.NewEASAReleaseService(repos.EASARelease),
+		ActionSignoff:             service.NewActionSignoffService(repos.ActionSignoff),
+		OtherPerson:               service.NewOtherPersonService(repos.OtherPerson),
+		MCF:                       service.NewMCFService(repos.MCF),
+		FleetHistory:              service.NewFleetHistoryService(repos.FleetHistory),
+		HEMSOperationalData:       service.NewHEMSOperationalDataService(repos.HEMSOperationalData),
+		HEMSOperationCategory:     service.NewHEMSOperationCategoryService(repos.HEMSOperationCategory),
+		HEMSOperation:             service.NewHEMSOperationService(repos.HEMSOperation),
+		MasterSettings:            service.NewMasterSettingsService(repos.MasterSettings, service.MasterSettingsServiceDependencies{Protector: protector}),
+		FileManager:               fileManagerSvc,
+		DutyRoster:                service.NewDutyRosterService(repos.DutyRoster),
+		AirRescuerChecklist:       service.NewAirRescuerChecklistService(repos.AirRescuerChecklist),
+		InsurancePatientData:      service.NewInsurancePatientDataService(repos.InsurancePatientData),
+		PatientData:               service.NewPatientDataService(repos.PatientData),
+		DUL:                       service.NewDULService(repos.DUL),
+		Audit:                     service.NewAuditLogService(repos.Audit, service.AuditLogServiceDependencies{QueueSize: appCfg.Audit.QueueSize, Workers: appCfg.Audit.Workers, IPEncryptionKey: appCfg.Auth.IPEncryptionKey}),
+		WOPI: service.NewWOPIService(service.WOPIConfig{
+			TokenSecret:   appCfg.WOPI.TokenSecret,
+			ProofSecret:   appCfg.WOPI.ProofSecret,
+			DiscoveryURL:  appCfg.WOPI.DiscoveryURL,
+			PublicBaseURL: appCfg.WOPI.PublicBaseURL,
+			EditActionURL: appCfg.WOPI.EditActionURL,
+			TokenTTL:      appCfg.WOPI.TokenTTL,
+			MaxBodyBytes:  appCfg.WOPI.MaxBodyBytes,
+			RequireProof:  appCfg.WOPI.RequireProof,
+		}),
+	}
+	services.Mission = service.NewMissionService(repos.Mission, flightSvc, flightDataSvc, afterFlightInspectionSvc)
+	services.FleetStatus = service.NewFleetStatusService(repos.FleetStatus, fileManagerSvc, helicopterSvc, services.Complaint).WithHistory(services.FleetHistory).WithUsage(services.HelicopterUsage)
+	flightDataSvc.WithAOGRecalculator(services.FleetStatus)
+	flightDataSvc.WithMissionResolver(services.Mission)
+	flightDataSvc.WithFlightLookup(services.Flight)
+	flightDataSvc.WithFMReportLookup(services.FMReport)
+	flightDataSvc.WithAfterFlightInspectionLookup(services.AfterFlightInspection)
+	services.FMReport.WithUsageRefresher(services.HelicopterUsage)
+
+	msSSO := service.NewMicrosoftSSO(appCfg.MicrosoftSSO).
+		WithExecutor(resilience.NewExecutor("microsoft_sso", appCfg.Resilience.MicrosoftSSO, infra.Logger, resilience.ClassifyMicrosoftSSOError)).
+		WithConfigResolver(func(ctx context.Context) (config.MicrosoftSSOConfig, error) {
+			cfg, err := services.MasterSettings.LoadMicrosoftEntraRuntimeConfig(ctx)
+			if err == nil {
+				return cfg, nil
+			}
+			// Fallback for local/dev when master settings are missing or stale.
+			// This prevents SSO flows from failing hard when DB-stored settings are invalid.
+			if service.IsMicrosoftSSOConfigComplete(appCfg.MicrosoftSSO) {
+				if infra.Logger != nil {
+					infra.Logger.Warn("microsoft sso runtime config fallback to env", "reason", err.Error())
+				}
+				return appCfg.MicrosoftSSO, nil
+			}
+			return config.MicrosoftSSOConfig{}, err
+		})
+
+	authDeps := service.AuthServiceDependencies{
+		SSO:                         msSSO,
+		Protector:                   protector,
+		Config:                      appCfg.Auth,
+		Audit:                       services.Audit,
+		EmailBranding:               service.NewAuthEmailBrandingResolver(services.MasterSettings, services.FileManager, infra.FileStorage),
+		EmailOTPEnabled:             services.MasterSettings.IsLoginEmailOTPEnabled,
+		DisableLegacyNoopEmailQueue: true,
+	}
+	if appCfg.Queue.OutboxEnabled {
+		authDeps.EmailOutbox = repos.Auth
+		authDeps.EmailSerializer = queueapp.NewOutboxSerializer(appCfg.Queue, appCfg.SQS)
+	}
+	services.Auth = service.NewAuthService(
+		repos.Auth,
+		repos.Role,
+		repos.TokenStore,
+		infra.EmailQueue,
+		authDeps,
+	)
+
+	services.Contact = service.NewContactService(repos.Contact, services.Auth)
+	services.HelicopterFile.
+		WithFileManagerService(services.FileManager).
+		WithHelicopterFileEvents(infra.HelicopterFileHub)
+	if infra.FileStorage != nil && !appCfg.FileQueue.OutboxEnabled && strings.TrimSpace(appCfg.FileSQS.QueueURL) == "" {
+		return nil, errors.New("FILE_SQS_QUEUE_URL is required when FILE_QUEUE_OUTBOX_ENABLED=false and file manager upload is enabled")
+	}
+
+	return services, nil
+}
+
+func initializeHandlers(services *Services, infra *Infrastructure) (*Handlers, error) {
+	if services == nil {
+		return nil, errors.New("services are required")
+	}
+	if infra == nil {
+		return nil, errors.New("infrastructure is required")
+	}
+
+	fleetStatusHandler := handlers.NewFleetStatusHandler(services.FleetStatus, handlers.FleetStatusDeps{
+		Helicopter: services.Helicopter,
+		Complaint:  services.Complaint,
+		EASA:       services.EASARelease,
+		History:    services.FleetHistory,
+		MCF:        services.MCF,
+		Signoff:    services.ActionSignoff,
+		Storage:    infra.FileStorage,
+	})
+
+	fmReportFlightHandler := handlers.NewFlightHandler(services.Flight).
+		WithAuthService(services.Auth).
+		WithAfterFlightInspectionService(services.AfterFlightInspection).
+		WithFMReportService(services.FMReport).
+		WithFlightDataService(services.FlightData).
+		WithTakeoverService(service.NewTakeoverModuleService(mysql.NewTakeoverRepository(infra.DB))).
+		WithHelicopterService(services.Helicopter).
+		WithReserveAcService(services.ReserveAc).
+		WithMissionService(services.Mission)
+
+	services.FMReport.WithFleetHistoryBuilder(handlers.NewFMReportFleetHistoryBuilder(fleetStatusHandler, fmReportFlightHandler))
+	services.FMReport.WithReportCodeResolver(fmReportFlightHandler)
+
+	return &Handlers{
+		User: handlers.NewUserHandler(services.User).
+			WithFileManagerService(services.FileManager).
+			WithFileStorage(infra.FileStorage),
+		Contact: handlers.NewContactHandler(services.Contact, services.Auth).
+			WithFileManagerService(services.FileManager).
+			WithFileStorage(infra.FileStorage),
+		Health:    handlers.NewHealthHandler(),
+		BuildInfo: handlers.NewBuildInfoHandler(),
+		Auth:      handlers.NewAuthHandler(services.Auth).WithFileStorage(infra.FileStorage).WithContactService(services.Contact),
+		Role:      handlers.NewRoleHandler(services.Role),
+		Helicopter: handlers.NewHelicopterHandler(services.Helicopter).
+			WithFileManagerService(services.FileManager).
+			WithFileStorage(infra.FileStorage).
+			WithReserveAcService(services.ReserveAc).
+			WithFleetStatusService(services.FleetStatus).
+			WithPINVerifier(services.Auth).
+			WithComplaintService(services.Complaint).
+			WithMCFService(services.MCF).
+			WithHistoryService(services.FleetHistory),
+		HelicopterUsage: handlers.NewHelicopterUsageHandler(services.HelicopterUsage),
+		HelicopterFile: handlers.NewHelicopterFileHandler(services.HelicopterFile).
+			WithFileManagerService(services.FileManager).
+			WithHelicopterService(services.Helicopter).
+			WithTakeoverService(services.Takeover).
+			WithHelicopterFileEvents(infra.HelicopterFileHub).
+			WithFileStorage(infra.FileStorage),
+		Flight: handlers.NewFlightHandler(services.Flight).
+			WithAuthService(services.Auth).
+			WithAfterFlightInspectionService(services.AfterFlightInspection).
+			WithFMReportService(services.FMReport).
+			WithFlightDataService(services.FlightData).
+			WithTakeoverService(service.NewTakeoverModuleService(mysql.NewTakeoverRepository(infra.DB))).
+			WithHelicopterService(services.Helicopter).
+			WithReserveAcService(services.ReserveAc).
+			WithMissionService(services.Mission),
+		FlightData: handlers.NewFlightDataHandler(services.FlightData).
+			WithMissionService(services.Mission).
+			WithUserService(services.User).
+			WithHospitalService(services.Hospital).
+			WithICAOService(services.ICAO).
+			WithFacilityService(services.Facility),
+		Mission: handlers.NewMissionHandler(services.Mission).WithFlightDataService(services.FlightData).WithFileStorage(infra.FileStorage).WithFileManagerService(services.FileManager),
+		FMReport: handlers.NewFMReportHandler(services.FMReport).
+			WithFlightHandler(fmReportFlightHandler).
+			WithMissionHandler(handlers.NewMissionHandler(services.Mission).WithFlightDataService(services.FlightData).WithFileStorage(infra.FileStorage).WithFileManagerService(services.FileManager)).
+			WithFlightInspectionService(services.FlightInspection).
+			WithAfterFlightInspectionService(services.AfterFlightInspection).
+			WithHelicopterUsageService(services.HelicopterUsage).
+			WithFleetStatusHandler(fleetStatusHandler).
+			WithTakeoverService(services.Takeover).
+			WithHelicopterService(services.Helicopter).
+			WithFileStorage(infra.FileStorage).
+			WithFileManagerService(services.FileManager),
+		ReserveAc: handlers.NewReserveAcHandler(services.ReserveAc).
+			WithFlightService(services.Flight).
+			WithFlightDataService(services.FlightData).
+			WithMissionService(services.Mission).
+			WithDutyRosterService(services.DutyRoster).
+			WithHelicopterService(services.Helicopter).
+			WithFlightInspectionService(services.FlightInspection).
+			WithBeforeFlightInspectionService(services.BeforeFlightInspection).
+			WithAfterFlightInspectionService(services.AfterFlightInspection).
+			WithFMReportService(services.FMReport).
+			WithFlightPrepCheckService(services.FlightPrepCheck).
+			WithHelicopterFileService(services.HelicopterFile).
+			WithFlightInspectionFileChecklistService(services.FlightInspectionChecklist).
+			WithFileStorage(infra.FileStorage),
+		Takeover: handlers.NewTakeoverHandler(infra.DB).
+			WithAuthService(services.Auth).
+			WithBaseService(services.Base).
+			WithFlightService(services.Flight).
+			WithFileManagerService(services.FileManager).
+			WithTakeoverAcService(service.NewTakeoverModuleService(mysql.NewTakeoverRepository(infra.DB))).
+			WithReserveAcService(services.ReserveAc).
+			WithDutyRosterService(services.DutyRoster).
+			WithHelicopterService(services.Helicopter).
+			WithComplaintService(services.Complaint).
+			WithMCFService(services.MCF).
+			WithFleetStatusService(services.FleetStatus).
+			WithFlightInspectionService(services.FlightInspection).
+			WithBeforeFlightInspectionService(services.BeforeFlightInspection).
+			WithFlightPrepCheckService(services.FlightPrepCheck).
+			WithHelicopterFileService(services.HelicopterFile).
+			WithFlightInspectionFileChecklistService(services.FlightInspectionChecklist).
+			WithFileStorage(infra.FileStorage),
+		OtherPerson:              handlers.NewOtherPersonHandler(services.OtherPerson),
+		Facility:                 handlers.NewFacilityHandler(services.Facility),
+		Base:                     handlers.NewBaseHandler(services.Base).WithFileManagerService(services.FileManager).WithFileStorage(infra.FileStorage),
+		Medicine:                 handlers.NewMedicineHandler(services.Medicine),
+		Vocation:                 handlers.NewVocationHandler(services.Vocation),
+		Opc:                      handlers.NewOpcHandler(services.Opc),
+		ForcesPresent:            handlers.NewForcesPresentHandler(services.ForcesPresent),
+		Hospital:                 handlers.NewHospitalHandler(services.Hospital),
+		HealthInsuranceCompanies: handlers.NewHealthInsuranceCompaniesHandler(services.HealthInsuranceCompanies),
+		FederalState:             handlers.NewFederalStateHandler(services.FederalState),
+		ICAO:                     handlers.NewICAOHandler(services.ICAO),
+		Land:                     handlers.NewLandHandler(services.Land),
+		MasterSettings:           handlers.NewMasterSettingsHandler(services.MasterSettings, services.FileManager, infra.FileStorage),
+		Branding:                 handlers.NewBrandingHandler(services.MasterSettings, services.FileManager, infra.FileStorage),
+		FileManagerFolder:        handlers.NewFileManagerFolderHandler(services.FileManager, infra.FileStorage),
+		FileManagerFile: handlers.NewFileManagerFileHandler(services.FileManager, infra.FileStorage).
+			WithHelicopterFileService(services.HelicopterFile).
+			WithAircraftService(services.Helicopter).
+			WithBaseService(services.Base).
+			WithDULService(services.DUL).
+			WithAuthService(services.Auth).
+			WithTakeoverService(services.Takeover).
+			WithMissionService(services.Mission).
+			WithUserService(services.User).
+			WithFleetStatusFileService(service.NewFleetStatusFileService(services.FileManager)).
+			WithHelicopterFileEvents(infra.HelicopterFileHub).
+			WithWOPIService(services.WOPI),
+		FileManagerAttachment: handlers.NewFileManagerAttachmentHandler(services.FileManager),
+		FileManagerEvents:     handlers.NewFileManagerEventsHandler(infra.FileStatusHub),
+		HelicopterFileEvents:  handlers.NewHelicopterFileEventsHandler(infra.HelicopterFileHub),
+		DutyRoster:            handlers.NewDutyRosterHandler(services.DutyRoster).WithAudit(services.Audit).WithFlightService(services.Flight),
+		AirRescuerChecklist:   handlers.NewAirRescuerChecklistHandler(services.AirRescuerChecklist),
+		InsurancePatientData:  handlers.NewInsurancePatientDataHandler(services.InsurancePatientData),
+		PatientData:           handlers.NewPatientDataHandler(services.PatientData),
+		DUL:                   handlers.NewDULHandler(services.DUL).WithBaseService(services.Base).WithContactService(services.Contact).WithFileManagerService(services.FileManager).WithFileStorage(infra.FileStorage),
+		FleetStatus:           fleetStatusHandler,
+		HEMSOperationalData:   handlers.NewHEMSOperationalDataHandler(services.HEMSOperationalData).WithFileManagerService(services.FileManager),
+		HEMSOperationCategory: handlers.NewHEMSOperationCategoryHandler(services.HEMSOperationCategory),
+		HEMSOperation:         handlers.NewHEMSOperationHandler(services.HEMSOperation),
+		Complaint:             handlers.NewComplaintHandler(services.Complaint).WithHelicopterService(services.Helicopter).WithMCFService(services.MCF).WithHistoryService(services.FleetHistory).WithAOGRecalculator(services.FleetStatus).WithActionSignoffService(services.ActionSignoff),
+		EASARelease:           handlers.NewEASAReleaseHandler(services.EASARelease).WithComplaintActionChecker(services.Complaint).WithActionSignoffChecker(services.ActionSignoff).WithHistoryService(services.FleetHistory).WithContactResolver(services.Contact).WithAOGRecalculator(services.FleetStatus),
+		ActionSignoff:         handlers.NewActionSignoffHandler(services.ActionSignoff).WithComplaintService(services.Complaint),
+		MCF:                   handlers.NewMCFHandler(services.MCF).WithHistoryService(services.FleetHistory),
+	}, nil
+}
+
+func initializeRealtimeComponents(
+	ctx context.Context,
+	repos *Repositories,
+	services *Services,
+	infra *Infrastructure,
+) error {
+	if repos == nil || services == nil || infra == nil {
+		return errors.New("repositories, services, and infrastructure are required")
+	}
+	userNameCache := userctx.NewUserNameCache(repos.User, 5*time.Minute)
+	handlers.WireUserNameGetter(userNameCache)
+
+	startFileManagerAutoPurgeLoop(ctx, services.FileManager, infra.FileTrashPolicy, infra.Logger)
+	startFileManagerLifecycleCleanupLoop(ctx, services.FileManager, infra.FileLifecycle, infra.Logger)
+	startHelicopterFileAttachmentReconcileLoop(ctx, services.HelicopterFile, infra.Logger)
+	startFleetStatusAOGRecomputeLoop(ctx, services.FleetStatus, infra.Logger)
+
+	fileStatusPoller := filemanagerrealtime.NewStatusPoller(infra.DB, infra.FileStatusHub, infra.Logger, filemanagerrealtime.StatusPollerConfig{
+		// Keep the SSE ready event responsive; this poller is the bridge between
+		// the async file processor and the live file.updated stream.
+		PollInterval: 250 * time.Millisecond,
+		BatchSize:    100,
+		OnPublished: func(ctx context.Context, event filemanagerrealtime.FileStatusEvent) error {
+			if filemanager.NormalizeFileStatus(event.Status) != filemanager.FileStatusReady {
+				return nil
+			}
+			if services == nil || services.HelicopterFile == nil {
+				return nil
+			}
+			finalized, err := services.HelicopterFile.FinalizePendingAttachmentsBySourceFileUUID(ctx, event.FileUUID, 50)
+			if err != nil {
+				return err
+			}
+			if finalized > 0 && infra.Logger != nil {
+				infra.Logger.Info("helicopter file attachments finalized from file ready event", "file_uuid", event.FileUUID, "finalized", finalized)
+			}
+			return nil
+		},
+	})
+	go func() {
+		if err := fileStatusPoller.Run(ctx); err != nil && ctx.Err() == nil {
+			infra.Logger.Error("file status poller stopped unexpectedly", "error", err)
+		}
+	}()
+
+	return nil
+}
+
+func buildHTTPServer(appCfg config.AppConfig, services *Services, handlersSet *Handlers, infra *Infrastructure) (*fiber.App, string, error) {
+	if services == nil || handlersSet == nil || infra == nil {
+		return nil, "", errors.New("services, handlers, and infra are required")
+	}
+	httpCfg := appCfg.HTTP
+	app := fiber.New(fiber.Config{
+		BodyLimit:    httpCfg.BodyLimit,
+		ReadTimeout:  httpCfg.ReadTimeout,
+		WriteTimeout: httpCfg.WriteTimeout,
+		IdleTimeout:  httpCfg.IdleTimeout,
+	})
+	api.UseDefaultMiddlewares(app, httpCfg)
+
+	envCfg := config.LoadEnvConfig()
+	hasJSONSAML := appCfg.SAML.CertFile != "" ||
+		appCfg.SAML.KeyFile != "" ||
+		appCfg.SAML.MetadataFile != "" ||
+		appCfg.SAML.RootURL != "" ||
+		appCfg.SAML.FrontendURL != "" ||
+		appCfg.SAML.CookieDomain != "" ||
+		appCfg.SAML.SessionTTLHr > 0
+	if appCfg.SAML.CertFile != "" {
+		envCfg.SAMLCertFile = appCfg.SAML.CertFile
+	}
+	if appCfg.SAML.KeyFile != "" {
+		envCfg.SAMLKeyFile = appCfg.SAML.KeyFile
+	}
+	if appCfg.SAML.MetadataFile != "" {
+		envCfg.SAMLMetadataFile = appCfg.SAML.MetadataFile
+	}
+	if appCfg.SAML.RootURL != "" {
+		envCfg.SAMLRootURL = appCfg.SAML.RootURL
+	}
+	if appCfg.SAML.FrontendURL != "" {
+		envCfg.FrontendURL = appCfg.SAML.FrontendURL
+	}
+	if appCfg.SAML.CookieDomain != "" {
+		envCfg.CookieDomain = appCfg.SAML.CookieDomain
+	}
+	if hasJSONSAML {
+		envCfg.CookieSecure = appCfg.SAML.CookieSecure
+	}
+	if appCfg.SAML.SessionTTLHr > 0 {
+		envCfg.SessionTTLHour = appCfg.SAML.SessionTTLHr
+	}
+
+	// Microsoft auth mode selector. Default "oauth" uses the OIDC/OAuth2 authorization
+	// code flow (Microsoft refresh tokens are stored in DB and validated on
+	// /api/v1/auth/refresh). Set MICROSOFT_AUTH_MODE=saml to fall back to the legacy
+	// SAML flow (kept intact for rollback).
+	microsoftAuthMode := strings.ToLower(strings.TrimSpace(os.Getenv("MICROSOFT_AUTH_MODE")))
+	if microsoftAuthMode == "" {
+		microsoftAuthMode = "oauth"
+	}
+
+	var samlHandler *samlauth.Handler
+	if microsoftAuthMode == "saml" {
+		if err := samlauth.InitSessionStoreDB(infra.DB); err == nil {
+			if err := samlauth.InitSAML(envCfg); err == nil {
+				samlHandler = samlauth.NewHandler(envCfg, services.Auth)
+			}
+		}
+	}
+	slog.Info("microsoft auth mode configured", slog.String("mode", microsoftAuthMode), slog.Bool("saml_active", samlHandler != nil))
+
+	api.RegisterRoutes(app, api.RouteDependencies{
+		Handlers: api.RouteHandlers{
+			User:                     handlersSet.User,
+			Contact:                  handlersSet.Contact,
+			Health:                   handlersSet.Health,
+			BuildInfo:                handlersSet.BuildInfo,
+			Auth:                     handlersSet.Auth,
+			Role:                     handlersSet.Role,
+			Helicopter:               handlersSet.Helicopter,
+			HelicopterUsage:          handlersSet.HelicopterUsage,
+			HelicopterFile:           handlersSet.HelicopterFile,
+			Flight:                   handlersSet.Flight,
+			FlightData:               handlersSet.FlightData,
+			Mission:                  handlersSet.Mission,
+			FMReport:                 handlersSet.FMReport,
+			ReserveAc:                handlersSet.ReserveAc,
+			Takeover:                 handlersSet.Takeover,
+			OtherPerson:              handlersSet.OtherPerson,
+			Facility:                 handlersSet.Facility,
+			Base:                     handlersSet.Base,
+			Medicine:                 handlersSet.Medicine,
+			Vocation:                 handlersSet.Vocation,
+			Opc:                      handlersSet.Opc,
+			ForcesPresent:            handlersSet.ForcesPresent,
+			Hospital:                 handlersSet.Hospital,
+			HealthInsuranceCompanies: handlersSet.HealthInsuranceCompanies,
+			FederalState:             handlersSet.FederalState,
+			ICAO:                     handlersSet.ICAO,
+			Land:                     handlersSet.Land,
+			MasterSettings:           handlersSet.MasterSettings,
+			Branding:                 handlersSet.Branding,
+			FileManagerFolder:        handlersSet.FileManagerFolder,
+			FileManagerFile:          handlersSet.FileManagerFile,
+			FileManagerAttachment:    handlersSet.FileManagerAttachment,
+			FileManagerEvents:        handlersSet.FileManagerEvents,
+			HelicopterFileEvents:     handlersSet.HelicopterFileEvents,
+			DutyRoster:               handlersSet.DutyRoster,
+			AirRescuerChecklist:      handlersSet.AirRescuerChecklist,
+			InsurancePatientData:     handlersSet.InsurancePatientData,
+			PatientData:              handlersSet.PatientData,
+			DUL:                      handlersSet.DUL,
+			FleetStatus:              handlersSet.FleetStatus,
+			HEMSOperationalData:      handlersSet.HEMSOperationalData,
+			HEMSOperationCategory:    handlersSet.HEMSOperationCategory,
+			HEMSOperation:            handlersSet.HEMSOperation,
+			Complaint:                handlersSet.Complaint,
+			EASARelease:              handlersSet.EASARelease,
+			ActionSignoff:            handlersSet.ActionSignoff,
+			MCF:                      handlersSet.MCF,
+			SAMLAuth:                 samlHandler,
+		},
+		Services: api.RouteServices{
+			Auth:  services.Auth,
+			Audit: services.Audit,
+			WOPI:  services.WOPI,
+		},
+	})
+
+	addr := ":8080"
+	if appCfg.HTTPPort > 0 {
+		addr = fmt.Sprintf(":%d", appCfg.HTTPPort)
+	}
+	return app, addr, nil
+}
diff --git a/cmd/file-lifecycle-backfill/main.go b/cmd/file-lifecycle-backfill/main.go
new file mode 100644
index 0000000..fd33dc0
--- /dev/null
+++ b/cmd/file-lifecycle-backfill/main.go
@@ -0,0 +1,129 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"time"
+
+	"wucher/internal/config"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/repository/mysql"
+	s3repo "wucher/internal/repository/s3"
+)
+
+type backfillReport struct {
+	Total            int  `json:"total"`
+	ActiveFiles      int  `json:"active_files"`
+	ProbableOrphans  int  `json:"probable_orphan_files"`
+	MissingS3Key     int  `json:"missing_s3_key"`
+	InvalidReference int  `json:"invalid_references"`
+	Skipped          int  `json:"skipped"`
+	DryRun           bool `json:"dry_run"`
+}
+
+func main() {
+	ctx := context.Background()
+	cfg, err := config.LoadFromFile(configFilePath())
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "load config: %v\n", err)
+		os.Exit(1)
+	}
+	db, err := mysql.Connect(cfg.MySQL)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "connect db: %v\n", err)
+		os.Exit(1)
+	}
+
+	fileRepo := mysql.NewFileManagerFileRepository(db)
+	lifecycleRepo, ok := any(fileRepo).(filemanager.FileLifecycleRepository)
+	if !ok {
+		fmt.Fprintln(os.Stderr, "file repository does not support lifecycle operations")
+		os.Exit(1)
+	}
+
+	dryRun := true
+	if raw := os.Getenv("BACKFILL_DRY_RUN"); raw != "" && (raw == "false" || raw == "0") {
+		dryRun = false
+	}
+
+	var storage filemanager.ObjectStorage
+	if cfg.FileStorage.Bucket != "" && cfg.FileStorage.Region != "" {
+		objStorage, s3Err := s3repo.NewFileObjectStorage(ctx, cfg.FileStorage)
+		if s3Err == nil {
+			storage = objStorage
+		}
+	}
+
+	rows := make([]filemanager.File, 0)
+	if err := db.WithContext(ctx).Model(&filemanager.File{}).Find(&rows).Error; err != nil {
+		fmt.Fprintf(os.Stderr, "query files: %v\n", err)
+		os.Exit(1)
+	}
+
+	report := backfillReport{DryRun: dryRun}
+	now := time.Now().UTC()
+	for i := range rows {
+		row := rows[i]
+		report.Total++
+		if row.DeletedAt != nil {
+			report.Skipped++
+			continue
+		}
+
+		referenced, refErr := lifecycleRepo.IsFileReferenced(ctx, row.ID)
+		if refErr != nil {
+			report.InvalidReference++
+			report.Skipped++
+			continue
+		}
+
+		if storage != nil {
+			if _, headErr := storage.HeadObject(ctx, row.ObjectKey); headErr != nil {
+				report.MissingS3Key++
+			}
+		}
+
+		if referenced {
+			report.ActiveFiles++
+			if !dryRun {
+				_ = lifecycleRepo.UpdateLifecycle(ctx, filemanager.FileLifecycleTransitionParams{
+					ID:              row.ID,
+					Status:          filemanager.FileLifecycleStatusActive,
+					AttachedAt:      &now,
+					ClearOrphanedAt: true,
+				})
+			}
+			continue
+		}
+
+		report.ProbableOrphans++
+		if !dryRun {
+			_ = lifecycleRepo.UpdateLifecycle(ctx, filemanager.FileLifecycleTransitionParams{
+				ID:         row.ID,
+				Status:     filemanager.FileLifecycleStatusOrphanPending,
+				OrphanedAt: &now,
+			})
+		}
+	}
+
+	enc := json.NewEncoder(os.Stdout)
+	enc.SetIndent("", "  ")
+	_ = enc.Encode(report)
+}
+
+func configFilePath() string {
+	if v := os.Getenv("CONFIG_FILE"); v != "" {
+		return v
+	}
+	basePath := os.Getenv("CONFIG_BASE_PATH")
+	if basePath == "" {
+		basePath = "/tmp"
+	}
+	filename := os.Getenv("CONFIG_FILENAME")
+	if filename == "" {
+		filename = "config.generated.json"
+	}
+	return basePath + "/" + filename
+}
diff --git a/cmd/healthcheck/main.go b/cmd/healthcheck/main.go
new file mode 100644
index 0000000..b943678
--- /dev/null
+++ b/cmd/healthcheck/main.go
@@ -0,0 +1,79 @@
+package main
+
+import (
+	"bufio"
+	"net"
+	"os"
+	"strings"
+	"time"
+)
+
+const (
+	defaultTarget = "http://127.0.0.1:8080/health"
+	timeout       = 2 * time.Second
+)
+
+func main() {
+	target := strings.TrimSpace(os.Getenv("HEALTHCHECK_URL"))
+	if target == "" {
+		target = defaultTarget
+	}
+	if len(os.Args) > 1 {
+		if arg := strings.TrimSpace(os.Args[1]); arg != "" {
+			target = arg
+		}
+	}
+
+	addr, path, ok := splitTarget(target)
+	if !ok {
+		os.Exit(1)
+	}
+
+	conn, err := net.DialTimeout("tcp", addr, timeout)
+	if err != nil {
+		os.Exit(1)
+	}
+	defer conn.Close()
+
+	_ = conn.SetDeadline(time.Now().Add(timeout))
+	request := "GET " + path + " HTTP/1.1\r\nHost: " + addr + "\r\nConnection: close\r\n\r\n"
+	if _, err := conn.Write([]byte(request)); err != nil {
+		os.Exit(1)
+	}
+
+	line, err := bufio.NewReader(conn).ReadString('\n')
+	if err != nil {
+		os.Exit(1)
+	}
+
+	fields := strings.Fields(line)
+	if len(fields) < 2 {
+		os.Exit(1)
+	}
+
+	code := fields[1]
+	if len(code) != 3 || (code[0] != '2' && code[0] != '3') {
+		os.Exit(1)
+	}
+}
+
+func splitTarget(target string) (string, string, bool) {
+	target = strings.TrimSpace(target)
+	if target == "" || strings.HasPrefix(target, "https://") {
+		return "", "", false
+	}
+
+	target = strings.TrimPrefix(target, "http://")
+	addr := target
+	path := "/"
+	if slash := strings.IndexByte(target, '/'); slash >= 0 {
+		addr = target[:slash]
+		path = target[slash:]
+	}
+
+	if addr == "" || !strings.Contains(addr, ":") {
+		return "", "", false
+	}
+
+	return addr, path, true
+}
diff --git a/cmd/worker/file_worker.go b/cmd/worker/file_worker.go
new file mode 100644
index 0000000..30d5f08
--- /dev/null
+++ b/cmd/worker/file_worker.go
@@ -0,0 +1,83 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"os/signal"
+	"strings"
+	"syscall"
+
+	queueapp "wucher/internal/app/queueing"
+	appworker "wucher/internal/app/worker"
+	"wucher/internal/config"
+	"wucher/internal/queue"
+	mysqlrepo "wucher/internal/repository/mysql"
+	s3repo "wucher/internal/repository/s3"
+	"wucher/internal/resilience"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/logger"
+)
+ 
+func runFileWorker(appCfg config.AppConfig) error {
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	appLogger := logger.New(appCfg.Logging).With("component", "worker", "job", "file_processing")
+	resCfg := appCfg.Resilience
+	fileQueueCfg := appCfg.FileQueue
+	fileSQSCfg := appCfg.FileSQS
+	if err := config.ValidateDistinctQueueURLs(appCfg.SQS, fileSQSCfg); err != nil {
+		return err
+	}
+	if strings.TrimSpace(fileSQSCfg.QueueURL) == "" {
+		return errors.New("FILE_SQS_QUEUE_URL is required for file worker")
+	}
+	db, err := mysqlrepo.Connect(appCfg.MySQL)
+	if err != nil {
+		return err
+	}
+
+	fileRepo := mysqlrepo.NewFileManagerFileRepository(db)
+	sqsBreaker := resilience.NewExecutor("sqs", resCfg.SQS, appLogger, resilience.ClassifySQSError)
+	consumer, serializer, err := queueapp.NewFileProcessingConsumer(ctx, fileQueueCfg, fileSQSCfg, sqsBreaker)
+	if err != nil {
+		return err
+	}
+	idempotency := queueapp.NewIdempotencyStoreWithPrefix(db, fileQueueCfg.IdempotencyKeyPrefix)
+	useCaseDeps := service.FileProcessingUseCaseDependencies{
+		Logger:           appLogger,
+		FileStatusEvents: fileRepo,
+		GotenbergURL:     appCfg.Gotenberg.URL,
+	}
+	fileStorageCfg := appCfg.FileStorage
+	if fileStorageCfg.Bucket != "" && fileStorageCfg.Region != "" {
+		storage, err := s3repo.NewFileObjectStorage(ctx, fileStorageCfg)
+		if err != nil {
+			return err
+		}
+		useCaseDeps.Storage = storage
+	}
+	useCase := service.NewFileProcessingUseCase(fileRepo, useCaseDeps)
+	handler := queue.NewFileProcessingJobQueueHandler(useCase, service.IsFileProcessingPermanentError)
+	var dispatcher *appworker.FileProcessingOutboxDispatcher
+	if fileQueueCfg.OutboxEnabled {
+		rawProducer, err := queueapp.NewQueueProducer(ctx, fileSQSCfg, sqsBreaker, "outbox_dispatcher")
+		if err != nil {
+			return err
+		}
+		dispatcher = appworker.NewFileProcessingOutboxDispatcher(fileQueueCfg, fileRepo, rawProducer, appLogger)
+	}
+	runner := appworker.NewFileProcessingRunner(fileQueueCfg, consumer, serializer, handler, idempotency, dispatcher, appLogger)
+
+	appLogger.Info("file worker started",
+		"backend", "sqs",
+		"monitor_addr", fileQueueCfg.WorkerMonitorAddr,
+		"queue_url", fileSQSCfg.QueueURL,
+		"outbox_enabled", fileQueueCfg.OutboxEnabled,
+	)
+	if err := runner.Start(ctx); err != nil {
+		return err
+	}
+	appLogger.Info("file worker stopped")
+	return nil
+}
diff --git a/cmd/worker/mail_worker.go b/cmd/worker/mail_worker.go
new file mode 100644
index 0000000..817e57e
--- /dev/null
+++ b/cmd/worker/mail_worker.go
@@ -0,0 +1,99 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"os/signal"
+	"syscall"
+
+	queueapp "wucher/internal/app/queueing"
+	appworker "wucher/internal/app/worker"
+	"wucher/internal/config"
+	"wucher/internal/shared/pkg/logger"
+	mysqlrepo "wucher/internal/repository/mysql"
+	"wucher/internal/resilience"
+	"wucher/internal/service"
+)
+
+func runMailWorker(appCfg config.AppConfig) error {
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	appLogger := logger.New(appCfg.Logging).With("component", "worker", "job", "email")
+	resCfg := appCfg.Resilience
+	emailCfg := appCfg.Email
+
+	queueCfg := appCfg.Queue
+	sqsCfg := appCfg.SQS
+	db, err := mysqlrepo.Connect(appCfg.MySQL)
+	if err != nil {
+		return err
+	}
+	authRepo := mysqlrepo.NewAuthRepository(db)
+
+	sqsBreaker := resilience.NewExecutor("sqs", resCfg.SQS, appLogger, resilience.ClassifySQSError)
+	consumer, serializer, err := queueapp.NewEmailConsumer(ctx, queueCfg, sqsCfg, sqsBreaker)
+	if err != nil {
+		return err
+	}
+	idempotency := queueapp.NewIdempotencyStore(db, queueCfg)
+	var dispatcher *appworker.OutboxDispatcher
+	if queueCfg.OutboxEnabled {
+		rawProducer, err := queueapp.NewQueueProducer(ctx, sqsCfg, sqsBreaker, "outbox_dispatcher")
+		if err != nil {
+			return err
+		}
+		dispatcher = appworker.NewOutboxDispatcher(queueCfg, authRepo, rawProducer, appLogger)
+	}
+
+	emailSender, err := buildEmailSender(ctx, emailCfg, appCfg.SES, resCfg, appLogger)
+	if err != nil {
+		return err
+	}
+	handler := service.NewEmailDeliveryHandler(emailSender, appLogger)
+	runner := appworker.NewRunner(queueCfg, consumer, serializer, handler, idempotency, dispatcher, appLogger)
+
+	appLogger.Info("worker started",
+		"backend", "sqs",
+		"email_provider", emailCfg.Provider,
+		"monitor_addr", queueCfg.WorkerMonitorAddr,
+		"outbox_enabled", queueCfg.OutboxEnabled,
+	)
+	if err := runner.Start(ctx); err != nil {
+		return err
+	}
+	appLogger.Info("worker stopped")
+	return nil
+}
+
+func buildEmailSender(
+	ctx context.Context,
+	emailCfg config.EmailDeliveryConfig,
+	sesCfg config.SESConfig,
+	resCfg config.ResilienceConfig,
+	appLogger *slog.Logger,
+) (service.EmailSender, error) {
+	switch emailCfg.Provider {
+	case "", "ses":
+		sesBreaker := resilience.NewExecutor("ses", resCfg.SES, appLogger, resilience.ClassifySESError)
+		sender, err := service.NewSESSender(ctx, sesCfg)
+		if err != nil {
+			return nil, err
+		}
+		sender = sender.WithExecutor(sesBreaker)
+		sender = sender.WithMetricsComponent("email_worker")
+		if !sender.Configured() {
+			return nil, errors.New("ses is not configured")
+		}
+		return sender, nil
+	case "mock":
+		sender := service.NewMockEmailSender(emailCfg.MockDir)
+		if !sender.Configured() {
+			return nil, errors.New("mock email sender is not configured")
+		}
+		return sender, nil
+	default:
+		return nil, errors.New("unsupported email provider: " + emailCfg.Provider)
+	}
+}
diff --git a/cmd/worker/main.go b/cmd/worker/main.go
new file mode 100644
index 0000000..7f33506
--- /dev/null
+++ b/cmd/worker/main.go
@@ -0,0 +1,80 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"strings"
+
+	"wucher/internal/config"
+)
+
+const (
+	workerJobEnvKey           = "WORKER_JOB"
+	workerJobEmail            = "email"
+	workerJobFileProcessing   = "file_processing"
+	workerJobAliasMail        = "mail"
+	workerJobAliasEmailWorker = "email_worker"
+	workerJobAliasFile        = "file"
+	workerJobAliasFileWorker  = "file_worker"
+)
+
+var (
+	workerRunFn     = run
+	workerFatalFn   = log.Fatal
+	runMailWorkerFn func(config.AppConfig) error = runMailWorker
+	runFileWorkerFn func(config.AppConfig) error = runFileWorker
+)
+
+func configFilePath() string {
+	if v := os.Getenv("CONFIG_FILE"); v != "" {
+		return v
+	}
+	basePath := os.Getenv("CONFIG_BASE_PATH")
+	if basePath == "" {
+		basePath = "/tmp"
+	}
+	filename := os.Getenv("CONFIG_FILENAME")
+	if filename == "" {
+		filename = "config.generated.json"
+	}
+	return basePath + "/" + filename
+}
+
+func main() {
+	if err := workerRunFn(); err != nil {
+		workerFatalFn(err)
+	}
+}
+
+func run() error {
+	appCfg, err := config.LoadFromFile(configFilePath())
+	if err != nil {
+		return fmt.Errorf("load config: %w", err)
+	}
+
+	job := normalizeWorkerJob(os.Getenv(workerJobEnvKey))
+
+	switch job {
+	case workerJobEmail:
+		return runMailWorkerFn(appCfg)
+	case workerJobFileProcessing:
+		return runFileWorkerFn(appCfg)
+	default:
+		return errors.New("unsupported worker job: " + job)
+	}
+}
+
+func normalizeWorkerJob(raw string) string {
+	job := strings.ToLower(strings.TrimSpace(raw))
+
+	switch job {
+	case "", workerJobEmail, workerJobAliasMail, workerJobAliasEmailWorker:
+		return workerJobEmail
+	case workerJobFileProcessing, workerJobAliasFile, workerJobAliasFileWorker:
+		return workerJobFileProcessing
+	default:
+		return job
+	}
+}
diff --git a/cmd/worker/main_test.go b/cmd/worker/main_test.go
new file mode 100644
index 0000000..85aaf9f
--- /dev/null
+++ b/cmd/worker/main_test.go
@@ -0,0 +1,136 @@
+package main
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"wucher/internal/config"
+	"wucher/internal/shared/pkg/logger"
+)
+
+// writeTestConfig writes a minimal valid JSON config to a temp file and sets
+// CONFIG_FILE so that run() can load it.
+func writeTestConfig(t *testing.T) {
+	t.Helper()
+	f := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(f, []byte("{}"), 0o600); err != nil {
+		t.Fatalf("writeTestConfig: %v", err)
+	}
+	t.Setenv("CONFIG_FILE", f)
+}
+
+func TestMain_CallsRun(t *testing.T) {
+	origRun := workerRunFn
+	t.Cleanup(func() { workerRunFn = origRun })
+
+	runCalled := false
+	workerRunFn = func() error {
+		runCalled = true
+		return nil
+	}
+
+	main()
+
+	if !runCalled {
+		t.Fatalf("expected worker run function to be called")
+	}
+}
+
+func TestRun_DefaultsToMailWorker(t *testing.T) {
+	origMail := runMailWorkerFn
+	origFile := runFileWorkerFn
+	t.Cleanup(func() {
+		runMailWorkerFn = origMail
+		runFileWorkerFn = origFile
+	})
+
+	writeTestConfig(t)
+	t.Setenv(workerJobEnvKey, "")
+	mailCalled := false
+	fileCalled := false
+	runMailWorkerFn = func(config.AppConfig) error {
+		mailCalled = true
+		return nil
+	}
+	runFileWorkerFn = func(config.AppConfig) error {
+		fileCalled = true
+		return nil
+	}
+
+	if err := run(); err != nil {
+		t.Fatalf("run: %v", err)
+	}
+	if !mailCalled {
+		t.Fatalf("expected mail worker to be called")
+	}
+	if fileCalled {
+		t.Fatalf("expected file worker not to be called")
+	}
+}
+
+func TestRun_UsesFileWorkerWhenConfigured(t *testing.T) {
+	origMail := runMailWorkerFn
+	origFile := runFileWorkerFn
+	t.Cleanup(func() {
+		runMailWorkerFn = origMail
+		runFileWorkerFn = origFile
+	})
+
+	writeTestConfig(t)
+	t.Setenv(workerJobEnvKey, workerJobFileProcessing)
+	mailCalled := false
+	fileCalled := false
+	runMailWorkerFn = func(config.AppConfig) error {
+		mailCalled = true
+		return nil
+	}
+	runFileWorkerFn = func(config.AppConfig) error {
+		fileCalled = true
+		return nil
+	}
+
+	if err := run(); err != nil {
+		t.Fatalf("run: %v", err)
+	}
+	if !fileCalled {
+		t.Fatalf("expected file worker to be called")
+	}
+	if mailCalled {
+		t.Fatalf("expected mail worker not to be called")
+	}
+}
+
+func TestRun_ReturnsErrorOnUnsupportedWorkerJob(t *testing.T) {
+	writeTestConfig(t)
+	t.Setenv(workerJobEnvKey, "unknown_worker")
+
+	err := run()
+	if err == nil || !strings.Contains(err.Error(), "unsupported worker job") {
+		t.Fatalf("expected unsupported worker job error, got %v", err)
+	}
+}
+
+func TestBuildEmailSenderMock(t *testing.T) {
+	sender, err := buildEmailSender(context.Background(), config.EmailDeliveryConfig{
+		Provider: "mock",
+		MockDir:  t.TempDir(),
+	}, config.SESConfig{}, config.ResilienceConfig{}, logger.NewDiscard())
+	if err != nil {
+		t.Fatalf("buildEmailSender: %v", err)
+	}
+	if sender == nil {
+		t.Fatalf("expected sender")
+	}
+}
+
+func TestBuildEmailSenderUnsupportedProvider(t *testing.T) {
+	_, err := buildEmailSender(context.Background(), config.EmailDeliveryConfig{
+		Provider: "unknown",
+	}, config.SESConfig{}, config.ResilienceConfig{}, logger.NewDiscard())
+	if err == nil || !strings.Contains(err.Error(), "unsupported email provider") {
+		t.Fatalf("expected unsupported provider error, got %v", err)
+	}
+}
diff --git a/config/local/config.json b/config/local/config.json
new file mode 100644
index 0000000..b6db2b5
--- /dev/null
+++ b/config/local/config.json
@@ -0,0 +1,310 @@
+{
+  "env": "${APP_ENV}",
+  "http": {
+    "port": ${HTTP_PORT},
+    "bodyLimit": ${HTTP_BODY_LIMIT},
+    "timeouts": {
+      "read": "${HTTP_READ_TIMEOUT}",
+      "write": "${HTTP_WRITE_TIMEOUT}",
+      "idle": "${HTTP_IDLE_TIMEOUT}",
+      "request": "${HTTP_REQUEST_TIMEOUT}",
+      "requestOverrides": "${HTTP_REQUEST_TIMEOUT_OVERRIDES}",
+      "shutdown": "${HTTP_SHUTDOWN_TIMEOUT}"
+    },
+    "cors": {
+      "allowOrigins": "${HTTP_CORS_ALLOW_ORIGINS}",
+      "allowMethods": "${HTTP_CORS_ALLOW_METHODS}",
+      "allowHeaders": "${HTTP_CORS_ALLOW_HEADERS}",
+      "exposeHeaders": "${HTTP_CORS_EXPOSE_HEADERS}",
+      "allowCredentials": ${HTTP_CORS_ALLOW_CREDENTIALS},
+      "maxAge": ${HTTP_CORS_MAX_AGE}
+    },
+    "rateLimit": {
+      "max": ${HTTP_RATE_LIMIT_MAX},
+      "window": "${HTTP_RATE_LIMIT_WINDOW}",
+      "endpoints": "${HTTP_RATE_LIMIT_ENDPOINTS}"
+    },
+    "security": {
+      "hstsMaxAge": ${HTTP_SECURITY_HSTS_MAX_AGE}
+    }
+  },
+  "database": {
+    "mysql": {
+      "dsn": "${MYSQL_DSN}",
+      "maxOpenConns": ${MYSQL_MAX_OPEN_CONNS},
+      "maxIdleConns": ${MYSQL_MAX_IDLE_CONNS},
+      "connMaxLifetime": "${MYSQL_CONN_MAX_LIFETIME}",
+      "connMaxIdleTime": "${MYSQL_CONN_MAX_IDLE_TIME}"
+    }
+  },
+  "logging": {
+    "level": "${LOG_LEVEL}",
+    "format": "${LOG_FORMAT}"
+  },
+  "audit": {
+    "queueSize": ${AUDIT_LOG_QUEUE_SIZE},
+    "workers": ${AUDIT_LOG_WORKERS}
+  },
+  "email": {
+    "provider": "${EMAIL_PROVIDER}",
+    "mockDir": "${EMAIL_MOCK_DIR}"
+  },
+  "circuitBreaker": {
+    "default": {
+      "enabled": ${CB_DEFAULT_ENABLED},
+      "maxRequests": ${CB_DEFAULT_MAX_REQUESTS},
+      "interval": "${CB_DEFAULT_INTERVAL}",
+      "bucketPeriod": "${CB_DEFAULT_BUCKET_PERIOD}",
+      "timeout": "${CB_DEFAULT_TIMEOUT}",
+      "minRequests": ${CB_DEFAULT_MIN_REQUESTS},
+      "failureRatio": ${CB_DEFAULT_FAILURE_RATIO},
+      "consecutiveFailures": ${CB_DEFAULT_CONSECUTIVE_FAILURES}
+    },
+    "microsoftSSO": {
+      "enabled": ${CB_MICROSOFT_SSO_ENABLED},
+      "maxRequests": ${CB_MICROSOFT_SSO_MAX_REQUESTS},
+      "interval": "${CB_MICROSOFT_SSO_INTERVAL}",
+      "bucketPeriod": "${CB_MICROSOFT_SSO_BUCKET_PERIOD}",
+      "timeout": "${CB_MICROSOFT_SSO_TIMEOUT}",
+      "minRequests": ${CB_MICROSOFT_SSO_MIN_REQUESTS},
+      "failureRatio": ${CB_MICROSOFT_SSO_FAILURE_RATIO},
+      "consecutiveFailures": ${CB_MICROSOFT_SSO_CONSECUTIVE_FAILURES}
+    },
+    "ses": {
+      "enabled": ${CB_SES_ENABLED},
+      "maxRequests": ${CB_SES_MAX_REQUESTS},
+      "interval": "${CB_SES_INTERVAL}",
+      "bucketPeriod": "${CB_SES_BUCKET_PERIOD}",
+      "timeout": "${CB_SES_TIMEOUT}",
+      "minRequests": ${CB_SES_MIN_REQUESTS},
+      "failureRatio": ${CB_SES_FAILURE_RATIO},
+      "consecutiveFailures": ${CB_SES_CONSECUTIVE_FAILURES}
+    },
+    "sqs": {
+      "enabled": ${CB_SQS_ENABLED},
+      "maxRequests": ${CB_SQS_MAX_REQUESTS},
+      "interval": "${CB_SQS_INTERVAL}",
+      "bucketPeriod": "${CB_SQS_BUCKET_PERIOD}",
+      "timeout": "${CB_SQS_TIMEOUT}",
+      "minRequests": ${CB_SQS_MIN_REQUESTS},
+      "failureRatio": ${CB_SQS_FAILURE_RATIO},
+      "consecutiveFailures": ${CB_SQS_CONSECUTIVE_FAILURES}
+    }
+  },
+  "auth": {
+    "publicBaseURL": "${APP_PUBLIC_BASE_URL}",
+    "passwordPepper": "${AUTH_PASSWORD_PEPPER}",
+    "ipEncryptionKey": "${AUTH_IP_ENCRYPTION_KEY}",
+    "defaultRole": "${AUTH_DEFAULT_ROLE}",
+    "disableRegister": ${AUTH_DISABLE_REGISTER},
+    "hash": {
+      "time": ${AUTH_HASH_TIME},
+      "memoryKB": ${AUTH_HASH_MEMORY_KB},
+      "threads": ${AUTH_HASH_THREADS},
+      "keyLen": ${AUTH_HASH_KEY_LEN}
+    },
+    "email": {
+      "verifyTTL": "${AUTH_EMAIL_VERIFY_TTL}",
+      "verifyURL": "${AUTH_EMAIL_VERIFY_URL}",
+      "inviteTTL": "${AUTH_INVITE_TTL}"
+    },
+    "password": {
+      "setURL": "${AUTH_SET_PASSWORD_URL}",
+      "resetTTL": "${AUTH_PASSWORD_RESET_TTL}",
+      "resetURL": "${AUTH_PASSWORD_RESET_URL}",
+      "forgotEmailCooldown": "${AUTH_FORGOT_PASSWORD_EMAIL_COOLDOWN}",
+      "forgotMinDuration": "${AUTH_FORGOT_PASSWORD_MIN_DURATION}",
+      "forgotIPRateMax": ${AUTH_FORGOT_PASSWORD_IP_RATE_MAX},
+      "forgotIPRateWindow": "${AUTH_FORGOT_PASSWORD_IP_RATE_WINDOW}",
+      "loginIPRateMax": ${AUTH_LOGIN_IP_RATE_MAX},
+      "loginIPRateWindow": "${AUTH_LOGIN_IP_RATE_WINDOW}"
+    },
+    "securityPin": {
+      "resetTTL": "${AUTH_SECURITY_PIN_RESET_TTL}",
+      "resetURL": "${AUTH_SECURITY_PIN_RESET_URL}",
+      "forgotEmailCooldown": "${AUTH_FORGOT_SECURITY_PIN_EMAIL_COOLDOWN}",
+      "forgotMinDuration": "${AUTH_FORGOT_SECURITY_PIN_MIN_DURATION}",
+      "maxAttempts": ${AUTH_SECURITY_PIN_MAX_ATTEMPTS},
+      "lockDuration": "${AUTH_SECURITY_PIN_LOCK_DURATION}",
+      "actionTokenTTL": "${AUTH_SECURITY_PIN_ACTION_TOKEN_TTL}"
+    },
+    "jwt": {
+      "accessSecret": "${AUTH_JWT_ACCESS_SECRET}",
+      "refreshSecret": "${AUTH_JWT_REFRESH_SECRET}",
+      "accessTTL": "${AUTH_JWT_ACCESS_TTL}",
+      "refreshTTL": "${AUTH_JWT_REFRESH_TTL}",
+      "refreshTotpTTL": "${AUTH_JWT_REFRESH_TOTP_TTL}",
+      "cookie": {
+        "domain": "${AUTH_JWT_COOKIE_DOMAIN}",
+        "secure": ${AUTH_JWT_COOKIE_SECURE},
+        "sameSite": "${AUTH_JWT_COOKIE_SAMESITE}",
+        "accessName": "${AUTH_JWT_ACCESS_COOKIE}",
+        "refreshName": "${AUTH_JWT_REFRESH_COOKIE}"
+      }
+    },
+    "totp": {
+      "challengeTTL": "${AUTH_TOTP_CHALLENGE_TTL}"
+    },
+    "sso": {
+      "stateTTL": "${AUTH_SSO_STATE_TTL}",
+      "successRedirect": "${AUTH_SSO_SUCCESS_REDIRECT}"
+    },
+    "webauthn": {
+      "rpId": "${AUTH_WEBAUTHN_RP_ID}",
+      "rpDisplayName": "${AUTH_WEBAUTHN_RP_DISPLAY_NAME}",
+      "rpOrigins": "${AUTH_WEBAUTHN_RP_ORIGINS}",
+      "challengeTTL": "${AUTH_WEBAUTHN_CHALLENGE_TTL}"
+    }
+  },
+  "totp": {
+    "issuer": "${TOTP_ISSUER}",
+    "secretKey": "${TOTP_SECRET_KEY}"
+  },
+  "microsoftSSO": {
+    "tenantId": "${MS_ENTRA_TENANT_ID}",
+    "clientId": "${MS_ENTRA_CLIENT_ID}",
+    "clientSecret": "${MS_ENTRA_CLIENT_SECRET}",
+    "redirectUrl": "${MS_ENTRA_REDIRECT_URL}",
+    "authority": "${MS_ENTRA_AUTHORITY}",
+    "scopes": "${MS_ENTRA_SCOPES}"
+  },
+  "saml": {
+    "certFile": "${SAML_CERT_FILE}",
+    "keyFile": "${SAML_KEY_FILE}",
+    "metadataFile": "${SAML_METADATA_FILE}",
+    "rootUrl": "${SAML_ROOT_URL}",
+    "frontendUrl": "${FRONTEND_URL}",
+    "cookieDomain": "${COOKIE_DOMAIN}",
+    "cookieSecure": ${COOKIE_SECURE},
+    "sessionTTLHour": ${SESSION_TTL_HOUR}
+  },
+  "queue": {
+    "messageSchemaVersion": "${QUEUE_MESSAGE_SCHEMA_VERSION}",
+    "enableLegacyPayloadFallback": ${QUEUE_ENABLE_LEGACY_PAYLOAD_FALLBACK},
+    "idempotencyKeyPrefix": "${QUEUE_IDEMPOTENCY_KEY_PREFIX}",
+    "idempotencyTTL": "${QUEUE_IDEMPOTENCY_TTL}",
+    "processingTTL": "${QUEUE_PROCESSING_TTL}",
+    "worker": {
+      "concurrency": ${QUEUE_WORKER_CONCURRENCY},
+      "maxBatchSize": ${QUEUE_WORKER_MAX_BATCH_SIZE},
+      "processTimeout": "${QUEUE_WORKER_PROCESS_TIMEOUT}",
+      "shutdownTimeout": "${QUEUE_WORKER_SHUTDOWN_TIMEOUT}",
+      "backoffMin": "${QUEUE_WORKER_BACKOFF_MIN}",
+      "backoffMax": "${QUEUE_WORKER_BACKOFF_MAX}",
+      "permanentFailureDelay": "${QUEUE_WORKER_PERMANENT_FAILURE_DELAY}",
+      "monitorAddr": "${QUEUE_WORKER_MONITOR_ADDR}",
+      "healthErrorThreshold": ${QUEUE_WORKER_HEALTH_ERROR_THRESHOLD},
+      "depthPollInterval": "${QUEUE_WORKER_DEPTH_POLL_INTERVAL}"
+    },
+    "outbox": {
+      "enabled": ${QUEUE_OUTBOX_ENABLED},
+      "pollInterval": "${QUEUE_OUTBOX_POLL_INTERVAL}",
+      "batchSize": ${QUEUE_OUTBOX_BATCH_SIZE},
+      "dispatchTimeout": "${QUEUE_OUTBOX_DISPATCH_TIMEOUT}",
+      "lockTTL": "${QUEUE_OUTBOX_LOCK_TTL}",
+      "maxAttempts": ${QUEUE_OUTBOX_MAX_ATTEMPTS}
+    }
+  },
+  "fileQueue": {
+    "messageSchemaVersion": "${FILE_QUEUE_MESSAGE_SCHEMA_VERSION}",
+    "idempotencyKeyPrefix": "${FILE_QUEUE_IDEMPOTENCY_KEY_PREFIX}",
+    "idempotencyTTL": "${FILE_QUEUE_IDEMPOTENCY_TTL}",
+    "processingTTL": "${FILE_QUEUE_PROCESSING_TTL}",
+    "worker": {
+      "concurrency": ${FILE_QUEUE_WORKER_CONCURRENCY},
+      "maxBatchSize": ${FILE_QUEUE_WORKER_MAX_BATCH_SIZE},
+      "processTimeout": "${FILE_QUEUE_WORKER_PROCESS_TIMEOUT}",
+      "shutdownTimeout": "${FILE_QUEUE_WORKER_SHUTDOWN_TIMEOUT}",
+      "backoffMin": "${FILE_QUEUE_WORKER_BACKOFF_MIN}",
+      "backoffMax": "${FILE_QUEUE_WORKER_BACKOFF_MAX}",
+      "permanentFailureDelay": "${FILE_QUEUE_WORKER_PERMANENT_FAILURE_DELAY}",
+      "monitorAddr": "${FILE_QUEUE_WORKER_MONITOR_ADDR}",
+      "healthErrorThreshold": ${FILE_QUEUE_WORKER_HEALTH_ERROR_THRESHOLD},
+      "depthPollInterval": "${FILE_QUEUE_WORKER_DEPTH_POLL_INTERVAL}"
+    },
+    "outbox": {
+      "enabled": ${FILE_QUEUE_OUTBOX_ENABLED},
+      "pollInterval": "${FILE_QUEUE_OUTBOX_POLL_INTERVAL}",
+      "batchSize": ${FILE_QUEUE_OUTBOX_BATCH_SIZE},
+      "dispatchTimeout": "${FILE_QUEUE_OUTBOX_DISPATCH_TIMEOUT}",
+      "lockTTL": "${FILE_QUEUE_OUTBOX_LOCK_TTL}",
+      "maxAttempts": ${FILE_QUEUE_OUTBOX_MAX_ATTEMPTS}
+    }
+  },
+  "aws": {
+    "region": "${AWS_REGION}",
+    "accessKeyId": "${AWS_ACCESS_KEY_ID}",
+    "secretAccessKey": "${AWS_SECRET_ACCESS_KEY}",
+    "sqs": {
+      "endpoint": "${SQS_ENDPOINT}",
+      "allowInsecureEndpoint": ${SQS_ALLOW_INSECURE_ENDPOINT},
+      "queueUrl": "${SQS_QUEUE_URL}",
+      "queueType": "${SQS_QUEUE_TYPE}",
+      "messageGroupId": "${SQS_MESSAGE_GROUP_ID}",
+      "maxMessages": ${SQS_MAX_MESSAGES},
+      "waitTimeSeconds": ${SQS_WAIT_TIME_SECONDS},
+      "visibilityTimeout": "${SQS_VISIBILITY_TIMEOUT}"
+    },
+    "fileSqs": {
+      "region": "${FILE_SQS_REGION}",
+      "endpoint": "${FILE_SQS_ENDPOINT}",
+      "allowInsecureEndpoint": ${FILE_SQS_ALLOW_INSECURE_ENDPOINT},
+      "queueUrl": "${FILE_SQS_QUEUE_URL}",
+      "queueType": "${FILE_SQS_QUEUE_TYPE}",
+      "messageGroupId": "${FILE_SQS_MESSAGE_GROUP_ID}",
+      "maxMessages": ${FILE_SQS_MAX_MESSAGES},
+      "waitTimeSeconds": ${FILE_SQS_WAIT_TIME_SECONDS},
+      "visibilityTimeout": "${FILE_SQS_VISIBILITY_TIMEOUT}"
+    },
+    "ses": {
+      "region": "${SES_REGION}",
+      "from": "${SES_FROM}",
+      "configurationSet": "${SES_CONFIGURATION_SET}",
+      "sendTimeout": "${SES_SEND_TIMEOUT}",
+      "endpoint": "${SES_ENDPOINT}",
+      "allowInsecureEndpoint": ${SES_ALLOW_INSECURE_ENDPOINT}
+    }
+  },
+  "file": {
+    "provider": "${FILE_STORAGE_PROVIDER}",
+    "s3": {
+      "bucket": "${FILE_S3_BUCKET}",
+      "region": "${FILE_S3_REGION}",
+      "endpoint": "${FILE_S3_ENDPOINT}",
+      "forcePathStyle": ${FILE_S3_FORCE_PATH_STYLE},
+      "allowInsecureEndpoint": ${FILE_S3_ALLOW_INSECURE_ENDPOINT},
+      "autoCreateBucket": ${FILE_S3_AUTO_CREATE_BUCKET},
+      "objectKeyPrefix": "${FILE_OBJECT_KEY_PREFIX}",
+      "presignPutTTL": "${FILE_S3_PRESIGN_PUT_TTL}",
+      "presignGetTTL": "${FILE_S3_PRESIGN_GET_TTL}"
+    },
+    "upload": {
+      "maxSize": ${FILE_MANAGER_UPLOAD_MAX_FILE_SIZE_BYTES},
+      "allowedMimeTypes": "${FILE_MANAGER_UPLOAD_ALLOWED_MIME_TYPES}",
+      "allowedExtensions": "${FILE_MANAGER_UPLOAD_ALLOWED_EXTENSIONS}",
+      "allowEmptyFile": ${FILE_MANAGER_UPLOAD_ALLOW_EMPTY_FILE},
+      "maxFilenameLength": ${FILE_MANAGER_UPLOAD_MAX_FILENAME_LENGTH}
+    },
+    "cleanup": {
+      "enableS3Tagging": ${ENABLE_S3_TAGGING},
+      "enableCleanupJob": ${ENABLE_FILE_CLEANUP_JOB},
+      "tempFileTTLDays": ${TEMP_FILE_TTL_DAYS},
+      "orphanGracePeriodDays": ${ORPHAN_GRACE_PERIOD_DAYS},
+      "batchSize": ${FILE_CLEANUP_BATCH_SIZE},
+      "dryRun": ${FILE_CLEANUP_DRY_RUN}
+    }
+  },
+  "wopi": {
+    "tokenSecret": "${WOPI_TOKEN_SECRET}",
+    "proofSecret": "${WOPI_PROOF_SECRET}",
+    "discoveryUrl": "${WOPI_DISCOVERY_URL}",
+    "publicBaseUrl": "${WOPI_PUBLIC_BASE_URL}",
+    "editActionUrl": "${WOPI_EDIT_ACTION_URL}",
+    "tokenTTL": "${WOPI_TOKEN_TTL}",
+    "maxBodyBytes": ${WOPI_MAX_BODY_BYTES},
+    "requireProof": ${WOPI_REQUIRE_PROOF}
+  },
+  "gotenberg": {
+    "url": "${GOTENBERG_URL}"
+  }
+}
diff --git a/config/prod/config.json b/config/prod/config.json
new file mode 100644
index 0000000..6bfb938
--- /dev/null
+++ b/config/prod/config.json
@@ -0,0 +1,307 @@
+{
+  "env": "${APP_ENV}",
+  "http": {
+    "port": ${HTTP_PORT},
+    "bodyLimit": ${HTTP_BODY_LIMIT},
+    "timeouts": {
+      "read": "${HTTP_READ_TIMEOUT}",
+      "write": "${HTTP_WRITE_TIMEOUT}",
+      "idle": "${HTTP_IDLE_TIMEOUT}",
+      "request": "${HTTP_REQUEST_TIMEOUT}",
+      "requestOverrides": "${HTTP_REQUEST_TIMEOUT_OVERRIDES}",
+      "shutdown": "${HTTP_SHUTDOWN_TIMEOUT}"
+    },
+    "cors": {
+      "allowOrigins": "${HTTP_CORS_ALLOW_ORIGINS}",
+      "allowMethods": "${HTTP_CORS_ALLOW_METHODS}",
+      "allowHeaders": "${HTTP_CORS_ALLOW_HEADERS}",
+      "exposeHeaders": "${HTTP_CORS_EXPOSE_HEADERS}",
+      "allowCredentials": ${HTTP_CORS_ALLOW_CREDENTIALS},
+      "maxAge": ${HTTP_CORS_MAX_AGE}
+    },
+    "rateLimit": {
+      "max": ${HTTP_RATE_LIMIT_MAX},
+      "window": "${HTTP_RATE_LIMIT_WINDOW}",
+      "endpoints": "${HTTP_RATE_LIMIT_ENDPOINTS}"
+    },
+    "security": {
+      "hstsMaxAge": ${HTTP_SECURITY_HSTS_MAX_AGE}
+    }
+  },
+  "database": {
+    "mysql": {
+      "dsn": "${MYSQL_DSN}",
+      "maxOpenConns": ${MYSQL_MAX_OPEN_CONNS},
+      "maxIdleConns": ${MYSQL_MAX_IDLE_CONNS},
+      "connMaxLifetime": "${MYSQL_CONN_MAX_LIFETIME}",
+      "connMaxIdleTime": "${MYSQL_CONN_MAX_IDLE_TIME}"
+    }
+  },
+  "logging": {
+    "level": "${LOG_LEVEL}",
+    "format": "${LOG_FORMAT}"
+  },
+  "audit": {
+    "queueSize": ${AUDIT_LOG_QUEUE_SIZE},
+    "workers": ${AUDIT_LOG_WORKERS}
+  },
+  "email": {
+    "provider": "${EMAIL_PROVIDER}",
+    "mockDir": "${EMAIL_MOCK_DIR}"
+  },
+  "circuitBreaker": {
+    "default": {
+      "enabled": ${CB_DEFAULT_ENABLED},
+      "maxRequests": ${CB_DEFAULT_MAX_REQUESTS},
+      "interval": "${CB_DEFAULT_INTERVAL}",
+      "bucketPeriod": "${CB_DEFAULT_BUCKET_PERIOD}",
+      "timeout": "${CB_DEFAULT_TIMEOUT}",
+      "minRequests": ${CB_DEFAULT_MIN_REQUESTS},
+      "failureRatio": ${CB_DEFAULT_FAILURE_RATIO},
+      "consecutiveFailures": ${CB_DEFAULT_CONSECUTIVE_FAILURES}
+    },
+    "microsoftSSO": {
+      "enabled": ${CB_MICROSOFT_SSO_ENABLED},
+      "maxRequests": ${CB_MICROSOFT_SSO_MAX_REQUESTS},
+      "interval": "${CB_MICROSOFT_SSO_INTERVAL}",
+      "bucketPeriod": "${CB_MICROSOFT_SSO_BUCKET_PERIOD}",
+      "timeout": "${CB_MICROSOFT_SSO_TIMEOUT}",
+      "minRequests": ${CB_MICROSOFT_SSO_MIN_REQUESTS},
+      "failureRatio": ${CB_MICROSOFT_SSO_FAILURE_RATIO},
+      "consecutiveFailures": ${CB_MICROSOFT_SSO_CONSECUTIVE_FAILURES}
+    },
+    "ses": {
+      "enabled": ${CB_SES_ENABLED},
+      "maxRequests": ${CB_SES_MAX_REQUESTS},
+      "interval": "${CB_SES_INTERVAL}",
+      "bucketPeriod": "${CB_SES_BUCKET_PERIOD}",
+      "timeout": "${CB_SES_TIMEOUT}",
+      "minRequests": ${CB_SES_MIN_REQUESTS},
+      "failureRatio": ${CB_SES_FAILURE_RATIO},
+      "consecutiveFailures": ${CB_SES_CONSECUTIVE_FAILURES}
+    },
+    "sqs": {
+      "enabled": ${CB_SQS_ENABLED},
+      "maxRequests": ${CB_SQS_MAX_REQUESTS},
+      "interval": "${CB_SQS_INTERVAL}",
+      "bucketPeriod": "${CB_SQS_BUCKET_PERIOD}",
+      "timeout": "${CB_SQS_TIMEOUT}",
+      "minRequests": ${CB_SQS_MIN_REQUESTS},
+      "failureRatio": ${CB_SQS_FAILURE_RATIO},
+      "consecutiveFailures": ${CB_SQS_CONSECUTIVE_FAILURES}
+    }
+  },
+  "auth": {
+    "publicBaseURL": "${APP_PUBLIC_BASE_URL}",
+    "passwordPepper": "${AUTH_PASSWORD_PEPPER}",
+    "ipEncryptionKey": "${AUTH_IP_ENCRYPTION_KEY}",
+    "defaultRole": "${AUTH_DEFAULT_ROLE}",
+    "disableRegister": ${AUTH_DISABLE_REGISTER},
+    "hash": {
+      "time": ${AUTH_HASH_TIME},
+      "memoryKB": ${AUTH_HASH_MEMORY_KB},
+      "threads": ${AUTH_HASH_THREADS},
+      "keyLen": ${AUTH_HASH_KEY_LEN}
+    },
+    "email": {
+      "verifyTTL": "${AUTH_EMAIL_VERIFY_TTL}",
+      "verifyURL": "${AUTH_EMAIL_VERIFY_URL}",
+      "inviteTTL": "${AUTH_INVITE_TTL}"
+    },
+    "password": {
+      "setURL": "${AUTH_SET_PASSWORD_URL}",
+      "resetTTL": "${AUTH_PASSWORD_RESET_TTL}",
+      "resetURL": "${AUTH_PASSWORD_RESET_URL}",
+      "forgotEmailCooldown": "${AUTH_FORGOT_PASSWORD_EMAIL_COOLDOWN}",
+      "forgotMinDuration": "${AUTH_FORGOT_PASSWORD_MIN_DURATION}",
+      "forgotIPRateMax": ${AUTH_FORGOT_PASSWORD_IP_RATE_MAX},
+      "forgotIPRateWindow": "${AUTH_FORGOT_PASSWORD_IP_RATE_WINDOW}",
+      "loginIPRateMax": ${AUTH_LOGIN_IP_RATE_MAX},
+      "loginIPRateWindow": "${AUTH_LOGIN_IP_RATE_WINDOW}"
+    },
+    "securityPin": {
+      "resetTTL": "${AUTH_SECURITY_PIN_RESET_TTL}",
+      "resetURL": "${AUTH_SECURITY_PIN_RESET_URL}",
+      "forgotEmailCooldown": "${AUTH_FORGOT_SECURITY_PIN_EMAIL_COOLDOWN}",
+      "forgotMinDuration": "${AUTH_FORGOT_SECURITY_PIN_MIN_DURATION}",
+      "maxAttempts": ${AUTH_SECURITY_PIN_MAX_ATTEMPTS},
+      "lockDuration": "${AUTH_SECURITY_PIN_LOCK_DURATION}",
+      "actionTokenTTL": "${AUTH_SECURITY_PIN_ACTION_TOKEN_TTL}"
+    },
+    "jwt": {
+      "accessSecret": "${AUTH_JWT_ACCESS_SECRET}",
+      "refreshSecret": "${AUTH_JWT_REFRESH_SECRET}",
+      "accessTTL": "${AUTH_JWT_ACCESS_TTL}",
+      "refreshTTL": "${AUTH_JWT_REFRESH_TTL}",
+      "refreshTotpTTL": "${AUTH_JWT_REFRESH_TOTP_TTL}",
+      "cookie": {
+        "domain": "${AUTH_JWT_COOKIE_DOMAIN}",
+        "secure": ${AUTH_JWT_COOKIE_SECURE},
+        "sameSite": "${AUTH_JWT_COOKIE_SAMESITE}",
+        "accessName": "${AUTH_JWT_ACCESS_COOKIE}",
+        "refreshName": "${AUTH_JWT_REFRESH_COOKIE}"
+      }
+    },
+    "totp": {
+      "challengeTTL": "${AUTH_TOTP_CHALLENGE_TTL}"
+    },
+    "sso": {
+      "stateTTL": "${AUTH_SSO_STATE_TTL}",
+      "successRedirect": "${AUTH_SSO_SUCCESS_REDIRECT}"
+    },
+    "webauthn": {
+      "rpId": "${AUTH_WEBAUTHN_RP_ID}",
+      "rpDisplayName": "${AUTH_WEBAUTHN_RP_DISPLAY_NAME}",
+      "rpOrigins": "${AUTH_WEBAUTHN_RP_ORIGINS}",
+      "challengeTTL": "${AUTH_WEBAUTHN_CHALLENGE_TTL}"
+    }
+  },
+  "totp": {
+    "issuer": "${TOTP_ISSUER}",
+    "secretKey": "${TOTP_SECRET_KEY}"
+  },
+  "microsoftSSO": {
+    "tenantId": "${MS_ENTRA_TENANT_ID}",
+    "clientId": "${MS_ENTRA_CLIENT_ID}",
+    "clientSecret": "${MS_ENTRA_CLIENT_SECRET}",
+    "redirectUrl": "${MS_ENTRA_REDIRECT_URL}",
+    "authority": "${MS_ENTRA_AUTHORITY}",
+    "scopes": "${MS_ENTRA_SCOPES}"
+  },
+  "saml": {
+    "certFile": "${SAML_CERT_FILE}",
+    "keyFile": "${SAML_KEY_FILE}",
+    "metadataFile": "${SAML_METADATA_FILE}",
+    "rootUrl": "${SAML_ROOT_URL}",
+    "frontendUrl": "${FRONTEND_URL}",
+    "cookieDomain": "${COOKIE_DOMAIN}",
+    "cookieSecure": ${COOKIE_SECURE},
+    "sessionTTLHour": ${SESSION_TTL_HOUR}
+  },
+  "queue": {
+    "messageSchemaVersion": "${QUEUE_MESSAGE_SCHEMA_VERSION}",
+    "enableLegacyPayloadFallback": ${QUEUE_ENABLE_LEGACY_PAYLOAD_FALLBACK},
+    "idempotencyKeyPrefix": "${QUEUE_IDEMPOTENCY_KEY_PREFIX}",
+    "idempotencyTTL": "${QUEUE_IDEMPOTENCY_TTL}",
+    "processingTTL": "${QUEUE_PROCESSING_TTL}",
+    "worker": {
+      "concurrency": ${QUEUE_WORKER_CONCURRENCY},
+      "maxBatchSize": ${QUEUE_WORKER_MAX_BATCH_SIZE},
+      "processTimeout": "${QUEUE_WORKER_PROCESS_TIMEOUT}",
+      "shutdownTimeout": "${QUEUE_WORKER_SHUTDOWN_TIMEOUT}",
+      "backoffMin": "${QUEUE_WORKER_BACKOFF_MIN}",
+      "backoffMax": "${QUEUE_WORKER_BACKOFF_MAX}",
+      "permanentFailureDelay": "${QUEUE_WORKER_PERMANENT_FAILURE_DELAY}",
+      "monitorAddr": "${QUEUE_WORKER_MONITOR_ADDR}",
+      "healthErrorThreshold": ${QUEUE_WORKER_HEALTH_ERROR_THRESHOLD},
+      "depthPollInterval": "${QUEUE_WORKER_DEPTH_POLL_INTERVAL}"
+    },
+    "outbox": {
+      "enabled": ${QUEUE_OUTBOX_ENABLED},
+      "pollInterval": "${QUEUE_OUTBOX_POLL_INTERVAL}",
+      "batchSize": ${QUEUE_OUTBOX_BATCH_SIZE},
+      "dispatchTimeout": "${QUEUE_OUTBOX_DISPATCH_TIMEOUT}",
+      "lockTTL": "${QUEUE_OUTBOX_LOCK_TTL}",
+      "maxAttempts": ${QUEUE_OUTBOX_MAX_ATTEMPTS}
+    }
+  },
+  "fileQueue": {
+    "messageSchemaVersion": "${FILE_QUEUE_MESSAGE_SCHEMA_VERSION}",
+    "idempotencyKeyPrefix": "${FILE_QUEUE_IDEMPOTENCY_KEY_PREFIX}",
+    "idempotencyTTL": "${FILE_QUEUE_IDEMPOTENCY_TTL}",
+    "processingTTL": "${FILE_QUEUE_PROCESSING_TTL}",
+    "worker": {
+      "concurrency": ${FILE_QUEUE_WORKER_CONCURRENCY},
+      "maxBatchSize": ${FILE_QUEUE_WORKER_MAX_BATCH_SIZE},
+      "processTimeout": "${FILE_QUEUE_WORKER_PROCESS_TIMEOUT}",
+      "shutdownTimeout": "${FILE_QUEUE_WORKER_SHUTDOWN_TIMEOUT}",
+      "backoffMin": "${FILE_QUEUE_WORKER_BACKOFF_MIN}",
+      "backoffMax": "${FILE_QUEUE_WORKER_BACKOFF_MAX}",
+      "permanentFailureDelay": "${FILE_QUEUE_WORKER_PERMANENT_FAILURE_DELAY}",
+      "monitorAddr": "${FILE_QUEUE_WORKER_MONITOR_ADDR}",
+      "healthErrorThreshold": ${FILE_QUEUE_WORKER_HEALTH_ERROR_THRESHOLD},
+      "depthPollInterval": "${FILE_QUEUE_WORKER_DEPTH_POLL_INTERVAL}"
+    },
+    "outbox": {
+      "enabled": ${FILE_QUEUE_OUTBOX_ENABLED},
+      "pollInterval": "${FILE_QUEUE_OUTBOX_POLL_INTERVAL}",
+      "batchSize": ${FILE_QUEUE_OUTBOX_BATCH_SIZE},
+      "dispatchTimeout": "${FILE_QUEUE_OUTBOX_DISPATCH_TIMEOUT}",
+      "lockTTL": "${FILE_QUEUE_OUTBOX_LOCK_TTL}",
+      "maxAttempts": ${FILE_QUEUE_OUTBOX_MAX_ATTEMPTS}
+    }
+  },
+  "aws": {
+    "region": "${AWS_REGION}",
+    "accessKeyId": "${AWS_ACCESS_KEY_ID}",
+    "secretAccessKey": "${AWS_SECRET_ACCESS_KEY}",
+    "sqs": {
+      "endpoint": "${SQS_ENDPOINT}",
+      "allowInsecureEndpoint": ${SQS_ALLOW_INSECURE_ENDPOINT},
+      "queueUrl": "${SQS_QUEUE_URL}",
+      "queueType": "${SQS_QUEUE_TYPE}",
+      "messageGroupId": "${SQS_MESSAGE_GROUP_ID}",
+      "maxMessages": ${SQS_MAX_MESSAGES},
+      "waitTimeSeconds": ${SQS_WAIT_TIME_SECONDS},
+      "visibilityTimeout": "${SQS_VISIBILITY_TIMEOUT}"
+    },
+    "fileSqs": {
+      "region": "${FILE_SQS_REGION}",
+      "endpoint": "${FILE_SQS_ENDPOINT}",
+      "allowInsecureEndpoint": ${FILE_SQS_ALLOW_INSECURE_ENDPOINT},
+      "queueUrl": "${FILE_SQS_QUEUE_URL}",
+      "queueType": "${FILE_SQS_QUEUE_TYPE}",
+      "messageGroupId": "${FILE_SQS_MESSAGE_GROUP_ID}",
+      "maxMessages": ${FILE_SQS_MAX_MESSAGES},
+      "waitTimeSeconds": ${FILE_SQS_WAIT_TIME_SECONDS},
+      "visibilityTimeout": "${FILE_SQS_VISIBILITY_TIMEOUT}"
+    },
+    "ses": {
+      "region": "${SES_REGION}",
+      "from": "${SES_FROM}",
+      "configurationSet": "${SES_CONFIGURATION_SET}",
+      "sendTimeout": "${SES_SEND_TIMEOUT}",
+      "endpoint": "${SES_ENDPOINT}",
+      "allowInsecureEndpoint": ${SES_ALLOW_INSECURE_ENDPOINT}
+    }
+  },
+  "file": {
+    "provider": "${FILE_STORAGE_PROVIDER}",
+    "s3": {
+      "bucket": "${FILE_S3_BUCKET}",
+      "region": "${FILE_S3_REGION}",
+      "endpoint": "${FILE_S3_ENDPOINT}",
+      "forcePathStyle": ${FILE_S3_FORCE_PATH_STYLE},
+      "allowInsecureEndpoint": ${FILE_S3_ALLOW_INSECURE_ENDPOINT},
+      "autoCreateBucket": ${FILE_S3_AUTO_CREATE_BUCKET},
+      "objectKeyPrefix": "${FILE_OBJECT_KEY_PREFIX}",
+      "presignPutTTL": "${FILE_S3_PRESIGN_PUT_TTL}",
+      "presignGetTTL": "${FILE_S3_PRESIGN_GET_TTL}"
+    },
+    "upload": {
+      "maxSize": ${FILE_MANAGER_UPLOAD_MAX_FILE_SIZE_BYTES},
+      "allowedMimeTypes": "${FILE_MANAGER_UPLOAD_ALLOWED_MIME_TYPES}",
+      "allowedExtensions": "${FILE_MANAGER_UPLOAD_ALLOWED_EXTENSIONS}",
+      "allowEmptyFile": ${FILE_MANAGER_UPLOAD_ALLOW_EMPTY_FILE},
+      "maxFilenameLength": ${FILE_MANAGER_UPLOAD_MAX_FILENAME_LENGTH}
+    },
+    "cleanup": {
+      "enableS3Tagging": ${ENABLE_S3_TAGGING},
+      "enableCleanupJob": ${ENABLE_FILE_CLEANUP_JOB},
+      "tempFileTTLDays": ${TEMP_FILE_TTL_DAYS},
+      "orphanGracePeriodDays": ${ORPHAN_GRACE_PERIOD_DAYS},
+      "batchSize": ${FILE_CLEANUP_BATCH_SIZE},
+      "dryRun": ${FILE_CLEANUP_DRY_RUN}
+    }
+  },
+  "wopi": {
+    "tokenSecret": "${WOPI_TOKEN_SECRET}",
+    "proofSecret": "${WOPI_PROOF_SECRET}",
+    "discoveryUrl": "${WOPI_DISCOVERY_URL}",
+    "publicBaseUrl": "${WOPI_PUBLIC_BASE_URL}",
+    "editActionUrl": "${WOPI_EDIT_ACTION_URL}",
+    "tokenTTL": "${WOPI_TOKEN_TTL}",
+    "maxBodyBytes": ${WOPI_MAX_BODY_BYTES},
+    "requireProof": ${WOPI_REQUIRE_PROOF}
+  }
+}
diff --git a/config/staging/config.json b/config/staging/config.json
new file mode 100644
index 0000000..6bfb938
--- /dev/null
+++ b/config/staging/config.json
@@ -0,0 +1,307 @@
+{
+  "env": "${APP_ENV}",
+  "http": {
+    "port": ${HTTP_PORT},
+    "bodyLimit": ${HTTP_BODY_LIMIT},
+    "timeouts": {
+      "read": "${HTTP_READ_TIMEOUT}",
+      "write": "${HTTP_WRITE_TIMEOUT}",
+      "idle": "${HTTP_IDLE_TIMEOUT}",
+      "request": "${HTTP_REQUEST_TIMEOUT}",
+      "requestOverrides": "${HTTP_REQUEST_TIMEOUT_OVERRIDES}",
+      "shutdown": "${HTTP_SHUTDOWN_TIMEOUT}"
+    },
+    "cors": {
+      "allowOrigins": "${HTTP_CORS_ALLOW_ORIGINS}",
+      "allowMethods": "${HTTP_CORS_ALLOW_METHODS}",
+      "allowHeaders": "${HTTP_CORS_ALLOW_HEADERS}",
+      "exposeHeaders": "${HTTP_CORS_EXPOSE_HEADERS}",
+      "allowCredentials": ${HTTP_CORS_ALLOW_CREDENTIALS},
+      "maxAge": ${HTTP_CORS_MAX_AGE}
+    },
+    "rateLimit": {
+      "max": ${HTTP_RATE_LIMIT_MAX},
+      "window": "${HTTP_RATE_LIMIT_WINDOW}",
+      "endpoints": "${HTTP_RATE_LIMIT_ENDPOINTS}"
+    },
+    "security": {
+      "hstsMaxAge": ${HTTP_SECURITY_HSTS_MAX_AGE}
+    }
+  },
+  "database": {
+    "mysql": {
+      "dsn": "${MYSQL_DSN}",
+      "maxOpenConns": ${MYSQL_MAX_OPEN_CONNS},
+      "maxIdleConns": ${MYSQL_MAX_IDLE_CONNS},
+      "connMaxLifetime": "${MYSQL_CONN_MAX_LIFETIME}",
+      "connMaxIdleTime": "${MYSQL_CONN_MAX_IDLE_TIME}"
+    }
+  },
+  "logging": {
+    "level": "${LOG_LEVEL}",
+    "format": "${LOG_FORMAT}"
+  },
+  "audit": {
+    "queueSize": ${AUDIT_LOG_QUEUE_SIZE},
+    "workers": ${AUDIT_LOG_WORKERS}
+  },
+  "email": {
+    "provider": "${EMAIL_PROVIDER}",
+    "mockDir": "${EMAIL_MOCK_DIR}"
+  },
+  "circuitBreaker": {
+    "default": {
+      "enabled": ${CB_DEFAULT_ENABLED},
+      "maxRequests": ${CB_DEFAULT_MAX_REQUESTS},
+      "interval": "${CB_DEFAULT_INTERVAL}",
+      "bucketPeriod": "${CB_DEFAULT_BUCKET_PERIOD}",
+      "timeout": "${CB_DEFAULT_TIMEOUT}",
+      "minRequests": ${CB_DEFAULT_MIN_REQUESTS},
+      "failureRatio": ${CB_DEFAULT_FAILURE_RATIO},
+      "consecutiveFailures": ${CB_DEFAULT_CONSECUTIVE_FAILURES}
+    },
+    "microsoftSSO": {
+      "enabled": ${CB_MICROSOFT_SSO_ENABLED},
+      "maxRequests": ${CB_MICROSOFT_SSO_MAX_REQUESTS},
+      "interval": "${CB_MICROSOFT_SSO_INTERVAL}",
+      "bucketPeriod": "${CB_MICROSOFT_SSO_BUCKET_PERIOD}",
+      "timeout": "${CB_MICROSOFT_SSO_TIMEOUT}",
+      "minRequests": ${CB_MICROSOFT_SSO_MIN_REQUESTS},
+      "failureRatio": ${CB_MICROSOFT_SSO_FAILURE_RATIO},
+      "consecutiveFailures": ${CB_MICROSOFT_SSO_CONSECUTIVE_FAILURES}
+    },
+    "ses": {
+      "enabled": ${CB_SES_ENABLED},
+      "maxRequests": ${CB_SES_MAX_REQUESTS},
+      "interval": "${CB_SES_INTERVAL}",
+      "bucketPeriod": "${CB_SES_BUCKET_PERIOD}",
+      "timeout": "${CB_SES_TIMEOUT}",
+      "minRequests": ${CB_SES_MIN_REQUESTS},
+      "failureRatio": ${CB_SES_FAILURE_RATIO},
+      "consecutiveFailures": ${CB_SES_CONSECUTIVE_FAILURES}
+    },
+    "sqs": {
+      "enabled": ${CB_SQS_ENABLED},
+      "maxRequests": ${CB_SQS_MAX_REQUESTS},
+      "interval": "${CB_SQS_INTERVAL}",
+      "bucketPeriod": "${CB_SQS_BUCKET_PERIOD}",
+      "timeout": "${CB_SQS_TIMEOUT}",
+      "minRequests": ${CB_SQS_MIN_REQUESTS},
+      "failureRatio": ${CB_SQS_FAILURE_RATIO},
+      "consecutiveFailures": ${CB_SQS_CONSECUTIVE_FAILURES}
+    }
+  },
+  "auth": {
+    "publicBaseURL": "${APP_PUBLIC_BASE_URL}",
+    "passwordPepper": "${AUTH_PASSWORD_PEPPER}",
+    "ipEncryptionKey": "${AUTH_IP_ENCRYPTION_KEY}",
+    "defaultRole": "${AUTH_DEFAULT_ROLE}",
+    "disableRegister": ${AUTH_DISABLE_REGISTER},
+    "hash": {
+      "time": ${AUTH_HASH_TIME},
+      "memoryKB": ${AUTH_HASH_MEMORY_KB},
+      "threads": ${AUTH_HASH_THREADS},
+      "keyLen": ${AUTH_HASH_KEY_LEN}
+    },
+    "email": {
+      "verifyTTL": "${AUTH_EMAIL_VERIFY_TTL}",
+      "verifyURL": "${AUTH_EMAIL_VERIFY_URL}",
+      "inviteTTL": "${AUTH_INVITE_TTL}"
+    },
+    "password": {
+      "setURL": "${AUTH_SET_PASSWORD_URL}",
+      "resetTTL": "${AUTH_PASSWORD_RESET_TTL}",
+      "resetURL": "${AUTH_PASSWORD_RESET_URL}",
+      "forgotEmailCooldown": "${AUTH_FORGOT_PASSWORD_EMAIL_COOLDOWN}",
+      "forgotMinDuration": "${AUTH_FORGOT_PASSWORD_MIN_DURATION}",
+      "forgotIPRateMax": ${AUTH_FORGOT_PASSWORD_IP_RATE_MAX},
+      "forgotIPRateWindow": "${AUTH_FORGOT_PASSWORD_IP_RATE_WINDOW}",
+      "loginIPRateMax": ${AUTH_LOGIN_IP_RATE_MAX},
+      "loginIPRateWindow": "${AUTH_LOGIN_IP_RATE_WINDOW}"
+    },
+    "securityPin": {
+      "resetTTL": "${AUTH_SECURITY_PIN_RESET_TTL}",
+      "resetURL": "${AUTH_SECURITY_PIN_RESET_URL}",
+      "forgotEmailCooldown": "${AUTH_FORGOT_SECURITY_PIN_EMAIL_COOLDOWN}",
+      "forgotMinDuration": "${AUTH_FORGOT_SECURITY_PIN_MIN_DURATION}",
+      "maxAttempts": ${AUTH_SECURITY_PIN_MAX_ATTEMPTS},
+      "lockDuration": "${AUTH_SECURITY_PIN_LOCK_DURATION}",
+      "actionTokenTTL": "${AUTH_SECURITY_PIN_ACTION_TOKEN_TTL}"
+    },
+    "jwt": {
+      "accessSecret": "${AUTH_JWT_ACCESS_SECRET}",
+      "refreshSecret": "${AUTH_JWT_REFRESH_SECRET}",
+      "accessTTL": "${AUTH_JWT_ACCESS_TTL}",
+      "refreshTTL": "${AUTH_JWT_REFRESH_TTL}",
+      "refreshTotpTTL": "${AUTH_JWT_REFRESH_TOTP_TTL}",
+      "cookie": {
+        "domain": "${AUTH_JWT_COOKIE_DOMAIN}",
+        "secure": ${AUTH_JWT_COOKIE_SECURE},
+        "sameSite": "${AUTH_JWT_COOKIE_SAMESITE}",
+        "accessName": "${AUTH_JWT_ACCESS_COOKIE}",
+        "refreshName": "${AUTH_JWT_REFRESH_COOKIE}"
+      }
+    },
+    "totp": {
+      "challengeTTL": "${AUTH_TOTP_CHALLENGE_TTL}"
+    },
+    "sso": {
+      "stateTTL": "${AUTH_SSO_STATE_TTL}",
+      "successRedirect": "${AUTH_SSO_SUCCESS_REDIRECT}"
+    },
+    "webauthn": {
+      "rpId": "${AUTH_WEBAUTHN_RP_ID}",
+      "rpDisplayName": "${AUTH_WEBAUTHN_RP_DISPLAY_NAME}",
+      "rpOrigins": "${AUTH_WEBAUTHN_RP_ORIGINS}",
+      "challengeTTL": "${AUTH_WEBAUTHN_CHALLENGE_TTL}"
+    }
+  },
+  "totp": {
+    "issuer": "${TOTP_ISSUER}",
+    "secretKey": "${TOTP_SECRET_KEY}"
+  },
+  "microsoftSSO": {
+    "tenantId": "${MS_ENTRA_TENANT_ID}",
+    "clientId": "${MS_ENTRA_CLIENT_ID}",
+    "clientSecret": "${MS_ENTRA_CLIENT_SECRET}",
+    "redirectUrl": "${MS_ENTRA_REDIRECT_URL}",
+    "authority": "${MS_ENTRA_AUTHORITY}",
+    "scopes": "${MS_ENTRA_SCOPES}"
+  },
+  "saml": {
+    "certFile": "${SAML_CERT_FILE}",
+    "keyFile": "${SAML_KEY_FILE}",
+    "metadataFile": "${SAML_METADATA_FILE}",
+    "rootUrl": "${SAML_ROOT_URL}",
+    "frontendUrl": "${FRONTEND_URL}",
+    "cookieDomain": "${COOKIE_DOMAIN}",
+    "cookieSecure": ${COOKIE_SECURE},
+    "sessionTTLHour": ${SESSION_TTL_HOUR}
+  },
+  "queue": {
+    "messageSchemaVersion": "${QUEUE_MESSAGE_SCHEMA_VERSION}",
+    "enableLegacyPayloadFallback": ${QUEUE_ENABLE_LEGACY_PAYLOAD_FALLBACK},
+    "idempotencyKeyPrefix": "${QUEUE_IDEMPOTENCY_KEY_PREFIX}",
+    "idempotencyTTL": "${QUEUE_IDEMPOTENCY_TTL}",
+    "processingTTL": "${QUEUE_PROCESSING_TTL}",
+    "worker": {
+      "concurrency": ${QUEUE_WORKER_CONCURRENCY},
+      "maxBatchSize": ${QUEUE_WORKER_MAX_BATCH_SIZE},
+      "processTimeout": "${QUEUE_WORKER_PROCESS_TIMEOUT}",
+      "shutdownTimeout": "${QUEUE_WORKER_SHUTDOWN_TIMEOUT}",
+      "backoffMin": "${QUEUE_WORKER_BACKOFF_MIN}",
+      "backoffMax": "${QUEUE_WORKER_BACKOFF_MAX}",
+      "permanentFailureDelay": "${QUEUE_WORKER_PERMANENT_FAILURE_DELAY}",
+      "monitorAddr": "${QUEUE_WORKER_MONITOR_ADDR}",
+      "healthErrorThreshold": ${QUEUE_WORKER_HEALTH_ERROR_THRESHOLD},
+      "depthPollInterval": "${QUEUE_WORKER_DEPTH_POLL_INTERVAL}"
+    },
+    "outbox": {
+      "enabled": ${QUEUE_OUTBOX_ENABLED},
+      "pollInterval": "${QUEUE_OUTBOX_POLL_INTERVAL}",
+      "batchSize": ${QUEUE_OUTBOX_BATCH_SIZE},
+      "dispatchTimeout": "${QUEUE_OUTBOX_DISPATCH_TIMEOUT}",
+      "lockTTL": "${QUEUE_OUTBOX_LOCK_TTL}",
+      "maxAttempts": ${QUEUE_OUTBOX_MAX_ATTEMPTS}
+    }
+  },
+  "fileQueue": {
+    "messageSchemaVersion": "${FILE_QUEUE_MESSAGE_SCHEMA_VERSION}",
+    "idempotencyKeyPrefix": "${FILE_QUEUE_IDEMPOTENCY_KEY_PREFIX}",
+    "idempotencyTTL": "${FILE_QUEUE_IDEMPOTENCY_TTL}",
+    "processingTTL": "${FILE_QUEUE_PROCESSING_TTL}",
+    "worker": {
+      "concurrency": ${FILE_QUEUE_WORKER_CONCURRENCY},
+      "maxBatchSize": ${FILE_QUEUE_WORKER_MAX_BATCH_SIZE},
+      "processTimeout": "${FILE_QUEUE_WORKER_PROCESS_TIMEOUT}",
+      "shutdownTimeout": "${FILE_QUEUE_WORKER_SHUTDOWN_TIMEOUT}",
+      "backoffMin": "${FILE_QUEUE_WORKER_BACKOFF_MIN}",
+      "backoffMax": "${FILE_QUEUE_WORKER_BACKOFF_MAX}",
+      "permanentFailureDelay": "${FILE_QUEUE_WORKER_PERMANENT_FAILURE_DELAY}",
+      "monitorAddr": "${FILE_QUEUE_WORKER_MONITOR_ADDR}",
+      "healthErrorThreshold": ${FILE_QUEUE_WORKER_HEALTH_ERROR_THRESHOLD},
+      "depthPollInterval": "${FILE_QUEUE_WORKER_DEPTH_POLL_INTERVAL}"
+    },
+    "outbox": {
+      "enabled": ${FILE_QUEUE_OUTBOX_ENABLED},
+      "pollInterval": "${FILE_QUEUE_OUTBOX_POLL_INTERVAL}",
+      "batchSize": ${FILE_QUEUE_OUTBOX_BATCH_SIZE},
+      "dispatchTimeout": "${FILE_QUEUE_OUTBOX_DISPATCH_TIMEOUT}",
+      "lockTTL": "${FILE_QUEUE_OUTBOX_LOCK_TTL}",
+      "maxAttempts": ${FILE_QUEUE_OUTBOX_MAX_ATTEMPTS}
+    }
+  },
+  "aws": {
+    "region": "${AWS_REGION}",
+    "accessKeyId": "${AWS_ACCESS_KEY_ID}",
+    "secretAccessKey": "${AWS_SECRET_ACCESS_KEY}",
+    "sqs": {
+      "endpoint": "${SQS_ENDPOINT}",
+      "allowInsecureEndpoint": ${SQS_ALLOW_INSECURE_ENDPOINT},
+      "queueUrl": "${SQS_QUEUE_URL}",
+      "queueType": "${SQS_QUEUE_TYPE}",
+      "messageGroupId": "${SQS_MESSAGE_GROUP_ID}",
+      "maxMessages": ${SQS_MAX_MESSAGES},
+      "waitTimeSeconds": ${SQS_WAIT_TIME_SECONDS},
+      "visibilityTimeout": "${SQS_VISIBILITY_TIMEOUT}"
+    },
+    "fileSqs": {
+      "region": "${FILE_SQS_REGION}",
+      "endpoint": "${FILE_SQS_ENDPOINT}",
+      "allowInsecureEndpoint": ${FILE_SQS_ALLOW_INSECURE_ENDPOINT},
+      "queueUrl": "${FILE_SQS_QUEUE_URL}",
+      "queueType": "${FILE_SQS_QUEUE_TYPE}",
+      "messageGroupId": "${FILE_SQS_MESSAGE_GROUP_ID}",
+      "maxMessages": ${FILE_SQS_MAX_MESSAGES},
+      "waitTimeSeconds": ${FILE_SQS_WAIT_TIME_SECONDS},
+      "visibilityTimeout": "${FILE_SQS_VISIBILITY_TIMEOUT}"
+    },
+    "ses": {
+      "region": "${SES_REGION}",
+      "from": "${SES_FROM}",
+      "configurationSet": "${SES_CONFIGURATION_SET}",
+      "sendTimeout": "${SES_SEND_TIMEOUT}",
+      "endpoint": "${SES_ENDPOINT}",
+      "allowInsecureEndpoint": ${SES_ALLOW_INSECURE_ENDPOINT}
+    }
+  },
+  "file": {
+    "provider": "${FILE_STORAGE_PROVIDER}",
+    "s3": {
+      "bucket": "${FILE_S3_BUCKET}",
+      "region": "${FILE_S3_REGION}",
+      "endpoint": "${FILE_S3_ENDPOINT}",
+      "forcePathStyle": ${FILE_S3_FORCE_PATH_STYLE},
+      "allowInsecureEndpoint": ${FILE_S3_ALLOW_INSECURE_ENDPOINT},
+      "autoCreateBucket": ${FILE_S3_AUTO_CREATE_BUCKET},
+      "objectKeyPrefix": "${FILE_OBJECT_KEY_PREFIX}",
+      "presignPutTTL": "${FILE_S3_PRESIGN_PUT_TTL}",
+      "presignGetTTL": "${FILE_S3_PRESIGN_GET_TTL}"
+    },
+    "upload": {
+      "maxSize": ${FILE_MANAGER_UPLOAD_MAX_FILE_SIZE_BYTES},
+      "allowedMimeTypes": "${FILE_MANAGER_UPLOAD_ALLOWED_MIME_TYPES}",
+      "allowedExtensions": "${FILE_MANAGER_UPLOAD_ALLOWED_EXTENSIONS}",
+      "allowEmptyFile": ${FILE_MANAGER_UPLOAD_ALLOW_EMPTY_FILE},
+      "maxFilenameLength": ${FILE_MANAGER_UPLOAD_MAX_FILENAME_LENGTH}
+    },
+    "cleanup": {
+      "enableS3Tagging": ${ENABLE_S3_TAGGING},
+      "enableCleanupJob": ${ENABLE_FILE_CLEANUP_JOB},
+      "tempFileTTLDays": ${TEMP_FILE_TTL_DAYS},
+      "orphanGracePeriodDays": ${ORPHAN_GRACE_PERIOD_DAYS},
+      "batchSize": ${FILE_CLEANUP_BATCH_SIZE},
+      "dryRun": ${FILE_CLEANUP_DRY_RUN}
+    }
+  },
+  "wopi": {
+    "tokenSecret": "${WOPI_TOKEN_SECRET}",
+    "proofSecret": "${WOPI_PROOF_SECRET}",
+    "discoveryUrl": "${WOPI_DISCOVERY_URL}",
+    "publicBaseUrl": "${WOPI_PUBLIC_BASE_URL}",
+    "editActionUrl": "${WOPI_EDIT_ACTION_URL}",
+    "tokenTTL": "${WOPI_TOKEN_TTL}",
+    "maxBodyBytes": ${WOPI_MAX_BODY_BYTES},
+    "requireProof": ${WOPI_REQUIRE_PROOF}
+  }
+}
diff --git a/configs/.gitignore b/configs/.gitignore
new file mode 100644
index 0000000..149d33c
--- /dev/null
+++ b/configs/.gitignore
@@ -0,0 +1,2 @@
+saml.key
+metadata.xml
diff --git a/configs/saml.crt b/configs/saml.crt
new file mode 100644
index 0000000..c01e614
--- /dev/null
+++ b/configs/saml.crt
@@ -0,0 +1,19 @@
+-----BEGIN CERTIFICATE-----
+MIIDJTCCAg2gAwIBAgIUIC8zX/OqMbovxzuzGOHr7UJVucQwDQYJKoZIhvcNAQEL
+BQAwIjEgMB4GA1UEAwwXYXBpLXdmbS1kZXYubXliaXQuY28uaWQwHhcNMjYwNTI1
+MDMxMjE5WhcNMzYwNTIyMDMxMjE5WjAiMSAwHgYDVQQDDBdhcGktd2ZtLWRldi5t
+eWJpdC5jby5pZDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMX3z2aC
+OO12ZwuNxxLf35m7rzIGB6J5O8EIgqihmg4ciy3BIkiDZAazAXaXR6ZDzLp63XMT
+9a6zEA3+U+LIovxcpgK2znrfxxFI0QehpTxzQj+GIkClyy5srewYHIWrQu+ShaXn
+btsjVwjELAGLzD8fLlIbmvrqr5zTCzq9Ep6ZZWCA8V8HAEXlR8lmC7vcu9bCCt5J
+7zTE5JODnxTFawJpcbpBgudL/0x44ed3aglLQsfdk7mB4FiUOXup8aOefZHRzayl
+n8jNSGH98kzw21vYV8bJUuwp9wNDqVNpM7LKIkdC4m+VgoTP/CM+GfRAnfpLhoP0
+oaxV6wUqmlxceQMCAwEAAaNTMFEwHQYDVR0OBBYEFHt5Aeik4E5BC6j0wc2IcfAa
+FlSpMB8GA1UdIwQYMBaAFHt5Aeik4E5BC6j0wc2IcfAaFlSpMA8GA1UdEwEB/wQF
+MAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHbt3T5iti9uguOqekecWCzti3bE41W/
+pfgT7Ub2XXU3m217tfl4EDEHf/FagNn3KtBufKsoV/57eFWb9wvCE4KAltUi0Qzn
+xQtCU/80TgNErnPhPR72LB4HxWFOA+k7WobY0+PYiedRJSf8vsrho/UgkvePPtp4
+3jfmN0By9/d+KqHNilPDx1AbJEboQckp/xIEfgAoCfsXSNYeWUuQlKu9eqXaz8Om
+lkUVcHfR5GBxSzqMvbbMe2EYNpB2Ap+ih/KzoBLEmbkUSeaSnUbhYYsMIHFl3usp
+7Z3sEBWCfeYZeLlvsNNMse7zkBB+TyOtPDlcPXhZAY9225S2q/sd/aY=
+-----END CERTIFICATE-----
diff --git a/coverage.html b/coverage.html
new file mode 100644
index 0000000..185acc0
--- /dev/null
+++ b/coverage.html
@@ -0,0 +1,5165 @@
+
+<!DOCTYPE html>
+<html>
+	<head>
+		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+		<title>api: Go Coverage Report</title>
+		<style>
+			body {
+				background: black;
+				color: rgb(80, 80, 80);
+			}
+			body, pre, #legend span {
+				font-family: Menlo, monospace;
+				font-weight: bold;
+			}
+			#topbar {
+				background: black;
+				position: fixed;
+				top: 0; left: 0; right: 0;
+				height: 42px;
+				border-bottom: 1px solid rgb(80, 80, 80);
+			}
+			#content {
+				margin-top: 50px;
+			}
+			#nav, #legend {
+				float: left;
+				margin-left: 10px;
+			}
+			#legend {
+				margin-top: 12px;
+			}
+			#nav {
+				margin-top: 10px;
+			}
+			#legend span {
+				margin: 0 5px;
+			}
+			.cov0 { color: rgb(192, 0, 0) }
+.cov1 { color: rgb(128, 128, 128) }
+.cov2 { color: rgb(116, 140, 131) }
+.cov3 { color: rgb(104, 152, 134) }
+.cov4 { color: rgb(92, 164, 137) }
+.cov5 { color: rgb(80, 176, 140) }
+.cov6 { color: rgb(68, 188, 143) }
+.cov7 { color: rgb(56, 200, 146) }
+.cov8 { color: rgb(44, 212, 149) }
+.cov9 { color: rgb(32, 224, 152) }
+.cov10 { color: rgb(20, 236, 155) }
+
+		</style>
+	</head>
+	<body>
+		<div id="topbar">
+			<div id="nav">
+				<select id="files">
+				
+				<option value="file0">wucher/cmd/api/main.go (0.0%)</option>
+				
+				<option value="file1">wucher/cmd/worker/main.go (0.0%)</option>
+				
+				<option value="file2">wucher/docs/docs.go (0.0%)</option>
+				
+				<option value="file3">wucher/internal/app/api/middleware.go (0.0%)</option>
+				
+				<option value="file4">wucher/internal/app/api/routes.go (0.0%)</option>
+				
+				<option value="file5">wucher/internal/app/api/routes_auth.go (0.0%)</option>
+				
+				<option value="file6">wucher/internal/app/api/routes_role.go (0.0%)</option>
+				
+				<option value="file7">wucher/internal/app/api/routes_swagger.go (0.0%)</option>
+				
+				<option value="file8">wucher/internal/app/api/routes_user.go (0.0%)</option>
+				
+				<option value="file9">wucher/internal/app/api/seed.go (0.0%)</option>
+				
+				<option value="file10">wucher/internal/app/api/server.go (0.0%)</option>
+				
+				<option value="file11">wucher/internal/app/worker/runner.go (0.0%)</option>
+				
+				<option value="file12">wucher/internal/config/config.go (0.0%)</option>
+				
+				<option value="file13">wucher/internal/domain/auth/identity.go (0.0%)</option>
+				
+				<option value="file14">wucher/internal/domain/auth/permission.go (0.0%)</option>
+				
+				<option value="file15">wucher/internal/domain/auth/role.go (0.0%)</option>
+				
+				<option value="file16">wucher/internal/domain/auth/role_permission.go (0.0%)</option>
+				
+				<option value="file17">wucher/internal/domain/auth/totp.go (0.0%)</option>
+				
+				<option value="file18">wucher/internal/domain/auth/user.go (0.0%)</option>
+				
+				<option value="file19">wucher/internal/pkg/logger/logger.go (0.0%)</option>
+				
+				<option value="file20">wucher/internal/pkg/uuidv7/uuidv7.go (0.0%)</option>
+				
+				<option value="file21">wucher/internal/repository/mysql/auth_repo.go (0.0%)</option>
+				
+				<option value="file22">wucher/internal/repository/mysql/db.go (0.0%)</option>
+				
+				<option value="file23">wucher/internal/repository/mysql/role_repo.go (0.0%)</option>
+				
+				<option value="file24">wucher/internal/repository/mysql/user_repo.go (0.0%)</option>
+				
+				<option value="file25">wucher/internal/repository/redis/email_queue.go (0.0%)</option>
+				
+				<option value="file26">wucher/internal/repository/redis/redis.go (0.0%)</option>
+				
+				<option value="file27">wucher/internal/repository/redis/token_store.go (0.0%)</option>
+				
+				<option value="file28">wucher/internal/service/auth_service.go (39.2%)</option>
+				
+				<option value="file29">wucher/internal/service/email_queue.go (0.0%)</option>
+				
+				<option value="file30">wucher/internal/service/microsoft_sso.go (0.0%)</option>
+				
+				<option value="file31">wucher/internal/service/role_service.go (0.0%)</option>
+				
+				<option value="file32">wucher/internal/service/secret_protector.go (70.0%)</option>
+				
+				<option value="file33">wucher/internal/service/smtp_sender.go (0.0%)</option>
+				
+				<option value="file34">wucher/internal/service/user_service.go (0.0%)</option>
+				
+				<option value="file35">wucher/internal/transport/http/handlers/auth_handler.go (6.0%)</option>
+				
+				<option value="file36">wucher/internal/transport/http/handlers/health_handler.go (0.0%)</option>
+				
+				<option value="file37">wucher/internal/transport/http/handlers/role_handler.go (0.0%)</option>
+				
+				<option value="file38">wucher/internal/transport/http/handlers/user_handler.go (0.0%)</option>
+				
+				<option value="file39">wucher/internal/transport/http/jsonapi/jsonapi.go (0.0%)</option>
+				
+				<option value="file40">wucher/internal/transport/http/middleware/auth_middleware.go (0.0%)</option>
+				
+				<option value="file41">wucher/internal/transport/http/validators/validator.go (0.0%)</option>
+				
+				</select>
+			</div>
+			<div id="legend">
+				<span>not tracked</span>
+			
+				<span class="cov0">not covered</span>
+				<span class="cov8">covered</span>
+			
+			</div>
+		</div>
+		<div id="content">
+		
+		<pre class="file" id="file0" style="display: none">package main
+
+import (
+        "log"
+        "os"
+
+        "github.com/gofiber/fiber/v2"
+        "github.com/joho/godotenv"
+
+        "wucher/internal/app/api"
+        "wucher/internal/config"
+        "wucher/internal/repository/mysql"
+        "wucher/internal/repository/redis"
+        "wucher/internal/service"
+        "wucher/internal/transport/http/handlers"
+
+        _ "wucher/docs"
+)
+
+// @title Wucher API
+// @version 1.0
+// @description Wucher backend API (JSON:API).
+// @description
+// @description Auth Flow (Email/Password):
+// @description 1) POST /api/v1/auth/register
+// @description 2) Check email, open verify link (GET /api/v1/auth/verify-email)
+// @description 3) POST /api/v1/auth/login
+// @description - If TOTP enabled: response 202 with challenge_token
+// @description 4) POST /api/v1/auth/totp/verify (challenge_token + code) -&gt; cookies
+// @description
+// @description Auth Flow (TOTP setup):
+// @description 1) POST /api/v1/auth/totp/setup -&gt; secret + otpauth_url (enabled=false)
+// @description 2) POST /api/v1/auth/totp/confirm -&gt; enabled=true
+// @description
+// @description Auth Flow (Microsoft Entra SSO):
+// @description 1) GET /api/v1/auth/microsoft/login -&gt; redirect to Microsoft
+// @description 2) Microsoft redirects to /api/v1/auth/microsoft/callback
+// @description 3) Backend sets cookies then redirects to AUTH_SSO_SUCCESS_REDIRECT
+// @BasePath /
+func main() <span class="cov0" title="0">{
+        _ = godotenv.Load()
+
+        cfg := config.LoadMySQLConfigFromEnv()
+        db, err := mysql.Connect(cfg)
+        if err != nil </span><span class="cov0" title="0">{
+                log.Fatal(err)
+        }</span>
+
+        <span class="cov0" title="0">if err := mysql.AutoMigrate(db); err != nil </span><span class="cov0" title="0">{
+                log.Fatal(err)
+        }</span>
+        <span class="cov0" title="0">if err := api.SeedRoles(db); err != nil </span><span class="cov0" title="0">{
+                log.Fatal(err)
+        }</span>
+
+        <span class="cov0" title="0">userRepo := mysql.NewUserRepository(db)
+        userSvc := service.NewUserService(userRepo)
+
+        roleRepo := mysql.NewRoleRepository(db)
+        roleSvc := service.NewRoleService(roleRepo)
+
+        authCfg := config.LoadAuthConfigFromEnv()
+        redisCfg := config.LoadRedisConfigFromEnv()
+        redisClient := redis.NewClient(redisCfg)
+        tokenStore := redis.NewTokenStore(redisClient)
+        smtpCfg := config.LoadSMTPConfigFromEnv()
+        mailer := service.NewSMTPSender(smtpCfg)
+        emailQueue := redis.NewEmailQueue(redisClient, authCfg.EmailQueueKey)
+
+        msCfg := config.LoadMicrosoftSSOConfigFromEnv()
+        var msSSO service.MicrosoftSSO
+        if msCfg.TenantID != "" &amp;&amp; msCfg.ClientID != "" &amp;&amp; msCfg.ClientSecret != "" &amp;&amp; msCfg.RedirectURL != "" </span><span class="cov0" title="0">{
+                msSSO = service.NewMicrosoftSSO(msCfg)
+        }</span>
+
+        <span class="cov0" title="0">authRepo := mysql.NewAuthRepository(db)
+        var protector service.SecretProtector
+        if p, err := service.NewAESGCMProtectorFromBase64(authCfg.TOTPSecretKeyB64); err == nil </span><span class="cov0" title="0">{
+                protector = p
+        }</span>
+        <span class="cov0" title="0">authSvc := service.NewAuthService(authRepo, roleRepo, tokenStore, emailQueue, mailer, msSSO, protector, authCfg)
+
+        app := fiber.New()
+        api.UseDefaultMiddlewares(app)
+        api.RegisterRoutes(
+                app,
+                handlers.NewUserHandler(userSvc),
+                handlers.NewHealthHandler(),
+                handlers.NewAuthHandler(authSvc),
+                authSvc,
+                handlers.NewRoleHandler(roleSvc),
+        )
+
+        addr := ":8080"
+        if v := os.Getenv("HTTP_PORT"); v != "" </span><span class="cov0" title="0">{
+                addr = ":" + v
+        }</span>
+
+        <span class="cov0" title="0">srv := api.NewServer(app)
+        log.Printf("API listening on %s", addr)
+        if err := srv.Start(addr); err != nil </span><span class="cov0" title="0">{
+                log.Fatal(err)
+        }</span>
+}
+</pre>
+		
+		<pre class="file" id="file1" style="display: none">package main
+
+import (
+        "context"
+        "log"
+        "os/signal"
+        "syscall"
+
+        "github.com/joho/godotenv"
+
+        "wucher/internal/config"
+        "wucher/internal/repository/redis"
+        "wucher/internal/service"
+)
+
+func main() <span class="cov0" title="0">{
+        _ = godotenv.Load()
+
+        ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+        defer stop()
+
+        authCfg := config.LoadAuthConfigFromEnv()
+        redisCfg := config.LoadRedisConfigFromEnv()
+        redisClient := redis.NewClient(redisCfg)
+        queue := redis.NewEmailQueue(redisClient, authCfg.EmailQueueKey)
+
+        smtpCfg := config.LoadSMTPConfigFromEnv()
+        mailer := service.NewSMTPSender(smtpCfg)
+
+        log.Println("worker started: email queue")
+        for </span><span class="cov0" title="0">{
+                select </span>{
+                case &lt;-ctx.Done():<span class="cov0" title="0">
+                        log.Println("worker stopped")
+                        return</span>
+                default:<span class="cov0" title="0">
+                        job, err := queue.Dequeue(ctx)
+                        if err != nil </span><span class="cov0" title="0">{
+                                log.Printf("queue error: %v", err)
+                                continue</span>
+                        }
+                        <span class="cov0" title="0">if job == nil </span><span class="cov0" title="0">{
+                                continue</span>
+                        }
+                        <span class="cov0" title="0">if err := mailer.Send(ctx, job.To, job.Subject, job.Body); err != nil </span><span class="cov0" title="0">{
+                                log.Printf("send email failed: %v", err)
+                        }</span>
+                }
+        }
+}
+</pre>
+		
+		<pre class="file" id="file2" style="display: none">// Package docs Code generated by swaggo/swag. DO NOT EDIT
+package docs
+
+import "github.com/swaggo/swag"
+
+const docTemplate = `{
+    "schemes": {{ marshal .Schemes }},
+    "swagger": "2.0",
+    "info": {
+        "description": "{{escape .Description}}",
+        "title": "{{.Title}}",
+        "contact": {},
+        "version": "{{.Version}}"
+    },
+    "host": "{{.Host}}",
+    "basePath": "{{.BasePath}}",
+    "paths": {
+        "/api/v1/auth/login": {
+            "post": {
+                "description": "If TOTP enabled, returns 202 + challenge_token. Then call /auth/totp/verify.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Login with email \u0026 password",
+                "parameters": [
+                    {
+                        "description": "JSON:API Login request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/dto.LoginRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.UserResponse"
+                        }
+                    },
+                    "202": {
+                        "description": "Accepted",
+                        "schema": {
+                            "$ref": "#/definitions/dto.LoginTOTPRequiredResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/logout": {
+            "post": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Logout (revoke refresh)",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.VerifyEmailResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/me": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Get current user",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.UserResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/callback": {
+            "get": {
+                "description": "Sets auth cookies and redirects to AUTH_SSO_SUCCESS_REDIRECT if configured.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Microsoft Entra SSO callback",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Authorization code",
+                        "name": "code",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "State",
+                        "name": "state",
+                        "in": "query",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.MicrosoftCallbackResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/login": {
+            "get": {
+                "description": "Returns the Microsoft authorization URL. Browser should redirect user to this URL.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Microsoft Entra SSO login",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.MicrosoftLoginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/refresh": {
+            "post": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Refresh access token",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.TokenResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/register": {
+            "post": {
+                "description": "Creates user (default role: admin) and sends verification link to email.\nNext: open verify link -\u003e then login.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Register user with email \u0026 password",
+                "parameters": [
+                    {
+                        "description": "JSON:API Register request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/dto.RegisterRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/dto.UserResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/confirm": {
+            "post": {
+                "description": "Validates initial TOTP code and enables TOTP for future logins.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Confirm TOTP setup",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP confirm request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/dto.TOTPConfirmRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.VerifyEmailResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/disable": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Disable TOTP",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP disable request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/dto.TOTPDisableRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.VerifyEmailResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/setup": {
+            "post": {
+                "description": "Generates secret and otpauth URL. TOTP is NOT enabled until confirmed.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Setup TOTP",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP setup request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/dto.TOTPSetupRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.TOTPSetupResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/verify": {
+            "post": {
+                "description": "Completes login when TOTP is enabled and returns auth cookies.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Verify TOTP code",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP verify request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/dto.TOTPVerifyRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.TokenResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/verify-email": {
+            "get": {
+                "description": "Confirms email verification after register.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Verify email",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Verification token",
+                        "name": "token",
+                        "in": "query",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.VerifyEmailResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "List roles",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Filter by name (contains)",
+                        "name": "filter[name]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.RoleListResponse"
+                        }
+                    }
+                }
+            },
+            "post": {
+                "description": "Create a new role. Name must be unique.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Create role",
+                "parameters": [
+                    {
+                        "description": "JSON:API Role create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/dto.RoleCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/dto.RoleResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/datatable": {
+            "get": {
+                "description": "DataTables-style params with JSON:API response. Use draw/start/length/search[value].",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "List roles (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Offset",
+                        "name": "start",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "length",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search[value]",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.RoleDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Get role by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.RoleResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            },
+            "put": {
+                "description": "Update role by ID. Name must be unique.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Update role",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API Role update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/dto.RoleUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.RoleResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Delete role",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/dto.VerifyEmailResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "dto.ErrorResponse": {
+            "type": "object",
+            "properties": {
+                "errors": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "detail": {
+                                "type": "string",
+                                "example": "email is required"
+                            },
+                            "source": {
+                                "type": "object",
+                                "properties": {
+                                    "pointer": {
+                                        "type": "string",
+                                        "example": "/data/attributes/email"
+                                    }
+                                }
+                            },
+                            "status": {
+                                "type": "string",
+                                "example": "422"
+                            },
+                            "title": {
+                                "type": "string",
+                                "example": "Validation error"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "dto.LoginAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "password"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "password": {
+                    "type": "string",
+                    "example": "StrongP@ssw0rd"
+                }
+            }
+        },
+        "dto.LoginData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/dto.LoginAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_login"
+                }
+            }
+        },
+        "dto.LoginRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/dto.LoginData"
+                }
+            }
+        },
+        "dto.LoginTOTPRequiredResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "challenge_token": {
+                                    "type": "string",
+                                    "example": "kP8k2..."
+                                },
+                                "requires_totp": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_totp_required"
+                        }
+                    }
+                }
+            }
+        },
+        "dto.MicrosoftCallbackResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "email": {
+                                    "type": "string",
+                                    "example": "user@example.com"
+                                },
+                                "provider": {
+                                    "type": "string",
+                                    "example": "microsoft"
+                                },
+                                "provider_subject": {
+                                    "type": "string",
+                                    "example": "00000000-0000-0000-0000-000000000000"
+                                }
+                            }
+                        },
+                        "id": {
+                            "type": "string",
+                            "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_identity"
+                        }
+                    }
+                }
+            }
+        },
+        "dto.MicrosoftLoginResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "url": {
+                                    "type": "string",
+                                    "example": "https://login.microsoftonline.com/..."
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_microsoft_url"
+                        }
+                    }
+                }
+            }
+        },
+        "dto.RegisterAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "first_name",
+                "last_name",
+                "password"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "password": {
+                    "type": "string",
+                    "minLength": 8,
+                    "example": "StrongP@ssw0rd"
+                }
+            }
+        },
+        "dto.RegisterData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/dto.RegisterAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_register"
+                }
+            }
+        },
+        "dto.RegisterRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/dto.RegisterData"
+                }
+            }
+        },
+        "dto.RoleAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                },
+                "description": {
+                    "type": "string",
+                    "example": "Full access to all resources."
+                },
+                "name": {
+                    "type": "string",
+                    "example": "admin"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                }
+            }
+        },
+        "dto.RoleCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "example": "Full access to all resources."
+                },
+                "name": {
+                    "type": "string",
+                    "example": "admin"
+                }
+            }
+        },
+        "dto.RoleCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/dto.RoleCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role"
+                }
+            }
+        },
+        "dto.RoleCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/dto.RoleCreateData"
+                }
+            }
+        },
+        "dto.RoleDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/dto.RoleResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "dto.RoleListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/dto.RoleResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "dto.RoleMini": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "example": "Full access to all resources."
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "admin"
+                }
+            }
+        },
+        "dto.RoleResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/dto.RoleAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role"
+                }
+            }
+        },
+        "dto.RoleResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/dto.RoleResource"
+                }
+            }
+        },
+        "dto.RoleUpdateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "example": "Full access to all resources."
+                },
+                "name": {
+                    "type": "string",
+                    "example": "admin"
+                }
+            }
+        },
+        "dto.RoleUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/dto.RoleUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role"
+                }
+            }
+        },
+        "dto.RoleUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/dto.RoleUpdateData"
+                }
+            }
+        },
+        "dto.TOTPConfirmAttributes": {
+            "type": "object",
+            "required": [
+                "code",
+                "user_id"
+            ],
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "123456"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "dto.TOTPConfirmData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/dto.TOTPConfirmAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_confirm"
+                }
+            }
+        },
+        "dto.TOTPConfirmRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/dto.TOTPConfirmData"
+                }
+            }
+        },
+        "dto.TOTPDisableAttributes": {
+            "type": "object",
+            "required": [
+                "user_id"
+            ],
+            "properties": {
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "dto.TOTPDisableData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/dto.TOTPDisableAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_disable"
+                }
+            }
+        },
+        "dto.TOTPDisableRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/dto.TOTPDisableData"
+                }
+            }
+        },
+        "dto.TOTPSetupAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "user_id"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "dto.TOTPSetupData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/dto.TOTPSetupAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_setup"
+                }
+            }
+        },
+        "dto.TOTPSetupRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/dto.TOTPSetupData"
+                }
+            }
+        },
+        "dto.TOTPSetupResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "issuer": {
+                                    "type": "string",
+                                    "example": "Wucher"
+                                },
+                                "otpauth_url": {
+                                    "type": "string",
+                                    "example": "otpauth://totp/Wucher:user@example.com?..."
+                                },
+                                "secret": {
+                                    "type": "string",
+                                    "example": "JBSWY3DPEHPK3PXP"
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_totp_setup"
+                        }
+                    }
+                }
+            }
+        },
+        "dto.TOTPVerifyAttributes": {
+            "type": "object",
+            "required": [
+                "challenge_token",
+                "code"
+            ],
+            "properties": {
+                "challenge_token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                },
+                "code": {
+                    "type": "string",
+                    "example": "123456"
+                }
+            }
+        },
+        "dto.TOTPVerifyData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/dto.TOTPVerifyAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_verify"
+                }
+            }
+        },
+        "dto.TOTPVerifyRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/dto.TOTPVerifyData"
+                }
+            }
+        },
+        "dto.TokenResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "access_expires_in": {
+                                    "type": "integer",
+                                    "example": 900
+                                },
+                                "refresh_expires_in": {
+                                    "type": "integer",
+                                    "example": 2592000
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_tokens"
+                        }
+                    }
+                }
+            }
+        },
+        "dto.UserAttributes": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "email_verified_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "role": {
+                    "$ref": "#/definitions/dto.RoleMini"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "dto.UserResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "$ref": "#/definitions/dto.UserAttributes"
+                        },
+                        "id": {
+                            "type": "string",
+                            "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "user"
+                        }
+                    }
+                }
+            }
+        },
+        "dto.VerifyEmailResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "verified": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_verify_email"
+                        }
+                    }
+                }
+            }
+        }
+    }
+}`
+
+// SwaggerInfo holds exported Swagger Info so clients can modify it
+var SwaggerInfo = &amp;swag.Spec{
+        Version:          "1.0",
+        Host:             "",
+        BasePath:         "/",
+        Schemes:          []string{},
+        Title:            "Wucher API",
+        Description:      "Wucher backend API (JSON:API).\n\nAuth Flow (Email/Password):\n1) POST /api/v1/auth/register\n2) Check email, open verify link (GET /api/v1/auth/verify-email)\n3) POST /api/v1/auth/login\n- If TOTP enabled: response 202 with challenge_token\n4) POST /api/v1/auth/totp/verify (challenge_token + code) -&gt; cookies\n\nAuth Flow (TOTP setup):\n1) POST /api/v1/auth/totp/setup -&gt; secret + otpauth_url (enabled=false)\n2) POST /api/v1/auth/totp/confirm -&gt; enabled=true\n\nAuth Flow (Microsoft Entra SSO):\n1) GET /api/v1/auth/microsoft/login -&gt; redirect to Microsoft\n2) Microsoft redirects to /api/v1/auth/microsoft/callback\n3) Backend sets cookies then redirects to AUTH_SSO_SUCCESS_REDIRECT",
+        InfoInstanceName: "swagger",
+        SwaggerTemplate:  docTemplate,
+        LeftDelim:        "{{",
+        RightDelim:       "}}",
+}
+
+func init() <span class="cov0" title="0">{
+        swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
+}</span>
+</pre>
+		
+		<pre class="file" id="file3" style="display: none">package api
+
+import (
+        "github.com/gofiber/fiber/v2"
+        "github.com/gofiber/fiber/v2/middleware/logger"
+        "github.com/gofiber/fiber/v2/middleware/recover"
+        "github.com/gofiber/fiber/v2/middleware/requestid"
+)
+
+// UseDefaultMiddlewares applies baseline best-practice middleware.
+func UseDefaultMiddlewares(app *fiber.App) <span class="cov0" title="0">{
+        app.Use(recover.New())
+        app.Use(requestid.New())
+        app.Use(logger.New())
+}</span>
+</pre>
+		
+		<pre class="file" id="file4" style="display: none">package api
+
+import (
+        "github.com/gofiber/fiber/v2"
+
+        "wucher/internal/service"
+        "wucher/internal/transport/http/handlers"
+        "wucher/internal/transport/http/middleware"
+)
+
+func RegisterRoutes(
+        app *fiber.App,
+        userHandler *handlers.UserHandler,
+        healthHandler *handlers.HealthHandler,
+        authHandler *handlers.AuthHandler,
+        authSvc *service.AuthService,
+        roleHandler *handlers.RoleHandler,
+) <span class="cov0" title="0">{
+        app.Get("/health", healthHandler.Handle)
+
+        api := app.Group("/api")
+        v1 := api.Group("/v1")
+
+        registerAuthRoutes(v1, authHandler, authSvc)
+        registerUserRoutes(v1, userHandler)
+        registerRoleRoutes(v1, roleHandler, middleware.AuthRequired(authSvc))
+        registerSwaggerRoutes(app)
+}</span>
+</pre>
+		
+		<pre class="file" id="file5" style="display: none">package api
+
+import (
+        "github.com/gofiber/fiber/v2"
+
+        "wucher/internal/service"
+        "wucher/internal/transport/http/handlers"
+        "wucher/internal/transport/http/middleware"
+)
+
+func registerAuthRoutes(v1 fiber.Router, authHandler *handlers.AuthHandler, authSvc *service.AuthService) <span class="cov0" title="0">{
+        auth := v1.Group("/auth")
+        auth.Post("/register", authHandler.Register)
+        auth.Post("/login", authHandler.Login)
+        auth.Post("/refresh", authHandler.Refresh)
+        auth.Post("/logout", authHandler.Logout)
+        auth.Get("/me", middleware.AuthRequired(authSvc), authHandler.Me)
+        auth.Get("/verify-email", authHandler.VerifyEmail)
+        auth.Get("/microsoft/login", authHandler.MicrosoftLogin)
+        auth.Get("/microsoft/callback", authHandler.MicrosoftCallback)
+        auth.Post("/totp/setup", authHandler.TOTPSetup)
+        auth.Post("/totp/confirm", authHandler.TOTPConfirm)
+        auth.Post("/totp/verify", authHandler.TOTPVerify)
+        auth.Post("/totp/disable", authHandler.TOTPDisable)
+}</span>
+</pre>
+		
+		<pre class="file" id="file6" style="display: none">package api
+
+import (
+        "github.com/gofiber/fiber/v2"
+
+        "wucher/internal/transport/http/handlers"
+)
+
+func registerRoleRoutes(v1 fiber.Router, roleHandler *handlers.RoleHandler, authMiddleware fiber.Handler) <span class="cov0" title="0">{
+        roles := v1.Group("/roles", authMiddleware)
+        roles.Post("/", roleHandler.Create)
+        roles.Get("/", roleHandler.List)
+        roles.Get("/datatable", roleHandler.ListDatatable)
+        roles.Get("/:id", roleHandler.GetByID)
+        roles.Put("/:id", roleHandler.Update)
+        roles.Delete("/:id", roleHandler.Delete)
+}</span>
+</pre>
+		
+		<pre class="file" id="file7" style="display: none">package api
+
+import (
+        "github.com/gofiber/fiber/v2"
+        "github.com/gofiber/swagger"
+)
+
+func registerSwaggerRoutes(app *fiber.App) <span class="cov0" title="0">{
+        app.Get("/swagger/*", swagger.HandlerDefault)
+}</span>
+</pre>
+		
+		<pre class="file" id="file8" style="display: none">package api
+
+import (
+        "github.com/gofiber/fiber/v2"
+
+        "wucher/internal/transport/http/handlers"
+)
+
+func registerUserRoutes(v1 fiber.Router, userHandler *handlers.UserHandler) <span class="cov0" title="0">{
+        users := v1.Group("/users")
+        users.Get("/", userHandler.List)
+        users.Get("/:id", userHandler.Get)
+}</span>
+</pre>
+		
+		<pre class="file" id="file9" style="display: none">package api
+
+import (
+        "gorm.io/gorm"
+        "gorm.io/gorm/clause"
+
+        "wucher/internal/domain/auth"
+)
+
+// SeedRoles inserts default roles if they don't exist.
+func SeedRoles(db *gorm.DB) error <span class="cov0" title="0">{
+        roles := []auth.Role{
+                {Name: "admin", Description: "Full access to all resources."},
+                {Name: "staff", Description: "Operational access with limited admin rights."},
+                {Name: "user", Description: "Regular end-user access."},
+        }
+
+        return db.Clauses(clause.OnConflict{
+                Columns:   []clause.Column{{Name: "name"}},
+                DoNothing: true,
+        }).Create(&amp;roles).Error
+}</span>
+</pre>
+		
+		<pre class="file" id="file10" style="display: none">package api
+
+import (
+        "context"
+        "time"
+
+        "github.com/gofiber/fiber/v2"
+)
+
+type Server struct {
+        app *fiber.App
+}
+
+func NewServer(app *fiber.App) *Server <span class="cov0" title="0">{
+        return &amp;Server{
+                app: app,
+        }
+}</span>
+
+func (s *Server) Start(addr string) error <span class="cov0" title="0">{
+        return s.app.Listen(addr)
+}</span>
+
+func (s *Server) Shutdown(ctx context.Context) error <span class="cov0" title="0">{
+        shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+        defer cancel()
+        return s.app.ShutdownWithContext(shutdownCtx)
+}</span>
+</pre>
+		
+		<pre class="file" id="file11" style="display: none">package worker
+
+type Runner struct{}
+
+func NewRunner() *Runner <span class="cov0" title="0">{
+        return &amp;Runner{}
+}</span>
+
+func (r *Runner) Start() error <span class="cov0" title="0">{
+        return nil
+}</span>
+</pre>
+		
+		<pre class="file" id="file12" style="display: none">package config
+
+import (
+        "os"
+        "strconv"
+        "strings"
+        "time"
+)
+
+type MySQLConfig struct {
+        DSN             string
+        MaxOpenConns    int
+        MaxIdleConns    int
+        ConnMaxLifetime time.Duration
+        ConnMaxIdleTime time.Duration
+}
+
+type AuthConfig struct {
+        PasswordPepper   string
+        HashTime         uint32
+        HashMemoryKB     uint32
+        HashThreads      uint8
+        HashKeyLen       uint32
+        EmailVerifyTTL   time.Duration
+        EmailVerifyURL   string
+        EmailQueueKey    string
+        TOTPChallengeTTL time.Duration
+        SSOStateTTL      time.Duration
+        TOTPIssuer       string
+        TOTPSecretKeyB64 string
+        JWTAccessSecret  string
+        JWTRefreshSecret string
+        JWTAccessTTL     time.Duration
+        JWTRefreshTTL    time.Duration
+        JWTCookieDomain  string
+        JWTCookieSecure  bool
+        JWTCookieSameSite string
+        JWTAccessCookieName  string
+        JWTRefreshCookieName string
+        SSOSuccessRedirectURL string
+        DefaultRoleName       string
+        DisableRegister       bool
+}
+
+type SMTPConfig struct {
+        Host     string
+        Port     int
+        Username string
+        Password string
+        From     string
+        InsecureSkipVerify bool
+}
+
+type MicrosoftSSOConfig struct {
+        TenantID     string
+        ClientID     string
+        ClientSecret string
+        RedirectURL  string
+        Authority    string
+        Scopes       []string
+}
+
+type RedisConfig struct {
+        Addr     string
+        Password string
+        DB       int
+}
+
+func LoadMySQLConfigFromEnv() MySQLConfig <span class="cov0" title="0">{
+        return MySQLConfig{
+                DSN:             getenv("MYSQL_DSN", ""),
+                MaxOpenConns:    getenvInt("MYSQL_MAX_OPEN_CONNS", 25),
+                MaxIdleConns:    getenvInt("MYSQL_MAX_IDLE_CONNS", 10),
+                ConnMaxLifetime: getenvDuration("MYSQL_CONN_MAX_LIFETIME", 5*time.Minute),
+                ConnMaxIdleTime: getenvDuration("MYSQL_CONN_MAX_IDLE_TIME", 2*time.Minute),
+        }
+}</span>
+
+func LoadAuthConfigFromEnv() AuthConfig <span class="cov0" title="0">{
+        return AuthConfig{
+                PasswordPepper:   getenv("AUTH_PASSWORD_PEPPER", ""),
+                HashTime:         uint32(getenvInt("AUTH_HASH_TIME", 1)),
+                HashMemoryKB:     uint32(getenvInt("AUTH_HASH_MEMORY_KB", 64*1024)),
+                HashThreads:      uint8(getenvInt("AUTH_HASH_THREADS", 4)),
+                HashKeyLen:       uint32(getenvInt("AUTH_HASH_KEY_LEN", 32)),
+                EmailVerifyTTL:   getenvDuration("AUTH_EMAIL_VERIFY_TTL", 24*time.Hour),
+                EmailVerifyURL:   getenv("AUTH_EMAIL_VERIFY_URL", ""),
+                EmailQueueKey:    getenv("AUTH_EMAIL_QUEUE_KEY", "queue:email"),
+                TOTPChallengeTTL: getenvDuration("AUTH_TOTP_CHALLENGE_TTL", 5*time.Minute),
+                SSOStateTTL:      getenvDuration("AUTH_SSO_STATE_TTL", 10*time.Minute),
+                TOTPIssuer:       getenv("TOTP_ISSUER", "Wucher"),
+                TOTPSecretKeyB64: getenv("TOTP_SECRET_KEY", ""),
+                JWTAccessSecret:  getenv("AUTH_JWT_ACCESS_SECRET", ""),
+                JWTRefreshSecret: getenv("AUTH_JWT_REFRESH_SECRET", ""),
+                JWTAccessTTL:     getenvDuration("AUTH_JWT_ACCESS_TTL", 15*time.Minute),
+                JWTRefreshTTL:    getenvDuration("AUTH_JWT_REFRESH_TTL", 30*24*time.Hour),
+                JWTCookieDomain:  getenv("AUTH_JWT_COOKIE_DOMAIN", ""),
+                JWTCookieSecure:  getenv("AUTH_JWT_COOKIE_SECURE", "false") == "true",
+                JWTCookieSameSite: getenv("AUTH_JWT_COOKIE_SAMESITE", "Lax"),
+                JWTAccessCookieName:  getenv("AUTH_JWT_ACCESS_COOKIE", "wucher_at"),
+                JWTRefreshCookieName: getenv("AUTH_JWT_REFRESH_COOKIE", "wucher_rt"),
+                SSOSuccessRedirectURL: getenv("AUTH_SSO_SUCCESS_REDIRECT", ""),
+                DefaultRoleName:       getenv("AUTH_DEFAULT_ROLE", "admin"),
+                DisableRegister:       getenv("AUTH_DISABLE_REGISTER", "false") == "true",
+        }
+}</span>
+
+func LoadSMTPConfigFromEnv() SMTPConfig <span class="cov0" title="0">{
+        return SMTPConfig{
+                Host:     getenv("SMTP_HOST", ""),
+                Port:     getenvInt("SMTP_PORT", 587),
+                Username: getenv("SMTP_USERNAME", ""),
+                Password: getenv("SMTP_PASSWORD", ""),
+                From:     getenv("SMTP_FROM", ""),
+                InsecureSkipVerify: getenv("SMTP_INSECURE_SKIP_VERIFY", "false") == "true",
+        }
+}</span>
+
+func LoadMicrosoftSSOConfigFromEnv() MicrosoftSSOConfig <span class="cov0" title="0">{
+        scopes := strings.Split(getenv("MS_ENTRA_SCOPES", "openid,profile,email"), ",")
+        for i := range scopes </span><span class="cov0" title="0">{
+                scopes[i] = strings.TrimSpace(scopes[i])
+        }</span>
+        <span class="cov0" title="0">return MicrosoftSSOConfig{
+                TenantID:     getenv("MS_ENTRA_TENANT_ID", ""),
+                ClientID:     getenv("MS_ENTRA_CLIENT_ID", ""),
+                ClientSecret: getenv("MS_ENTRA_CLIENT_SECRET", ""),
+                RedirectURL:  getenv("MS_ENTRA_REDIRECT_URL", ""),
+                Authority:    getenv("MS_ENTRA_AUTHORITY", "https://login.microsoftonline.com/"),
+                Scopes:       scopes,
+        }</span>
+}
+
+func LoadRedisConfigFromEnv() RedisConfig <span class="cov0" title="0">{
+        return RedisConfig{
+                Addr:     getenv("REDIS_ADDR", ""),
+                Password: getenv("REDIS_PASSWORD", ""),
+                DB:       getenvInt("REDIS_DB", 0),
+        }
+}</span>
+
+func getenv(key, def string) string <span class="cov0" title="0">{
+        if v := os.Getenv(key); v != "" </span><span class="cov0" title="0">{
+                return v
+        }</span>
+        <span class="cov0" title="0">return def</span>
+}
+
+func getenvInt(key string, def int) int <span class="cov0" title="0">{
+        if v := os.Getenv(key); v != "" </span><span class="cov0" title="0">{
+                if n, err := strconv.Atoi(v); err == nil </span><span class="cov0" title="0">{
+                        return n
+                }</span>
+        }
+        <span class="cov0" title="0">return def</span>
+}
+
+func getenvDuration(key string, def time.Duration) time.Duration <span class="cov0" title="0">{
+        if v := os.Getenv(key); v != "" </span><span class="cov0" title="0">{
+                if d, err := time.ParseDuration(v); err == nil </span><span class="cov0" title="0">{
+                        return d
+                }</span>
+        }
+        <span class="cov0" title="0">return def</span>
+}
+</pre>
+		
+		<pre class="file" id="file13" style="display: none">package auth
+
+import (
+        "time"
+
+        "gorm.io/gorm"
+
+        "wucher/internal/pkg/uuidv7"
+)
+
+type UserIdentity struct {
+        ID              []byte `gorm:"type:binary(16);primaryKey;column:id"`
+        UserID          []byte `gorm:"type:binary(16);index;not null;column:user_id"`
+        Provider        string `gorm:"type:varchar(32);uniqueIndex:ux_provider_subject;not null;column:provider"`
+        ProviderSubject string `gorm:"type:varchar(191);uniqueIndex:ux_provider_subject;not null;column:provider_subject"`
+        Email           string `gorm:"type:varchar(191);index;column:email"`
+        Metadata        []byte `gorm:"type:json;column:metadata"`
+        CreatedAt       time.Time
+        CreatedBy       []byte `gorm:"type:binary(16);column:created_by"`
+        UpdatedAt       time.Time
+        UpdatedBy       []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (UserIdentity) TableName() string <span class="cov0" title="0">{ return "user_identities" }</span>
+
+func (ui *UserIdentity) BeforeCreate(tx *gorm.DB) error <span class="cov0" title="0">{
+        if len(ui.ID) == 0 </span><span class="cov0" title="0">{
+                ui.ID = uuidv7.MustBytes()
+        }</span>
+        <span class="cov0" title="0">return nil</span>
+}
+</pre>
+		
+		<pre class="file" id="file14" style="display: none">package auth
+
+import (
+        "time"
+
+        "gorm.io/gorm"
+
+        "wucher/internal/pkg/uuidv7"
+)
+
+type Permission struct {
+        ID          []byte `gorm:"type:binary(16);primaryKey;column:id"`
+        Name        string `gorm:"type:varchar(64);uniqueIndex;not null;column:name"`
+        Key         string `gorm:"type:varchar(64);uniqueIndex;not null;column:key"`
+        Description string `gorm:"type:varchar(255);column:description"`
+        CreatedAt   time.Time
+        CreatedBy   []byte `gorm:"type:binary(16);column:created_by"`
+        UpdatedAt   time.Time
+        UpdatedBy   []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (Permission) TableName() string <span class="cov0" title="0">{ return "permissions" }</span>
+
+func (p *Permission) BeforeCreate(tx *gorm.DB) error <span class="cov0" title="0">{
+        if len(p.ID) == 0 </span><span class="cov0" title="0">{
+                p.ID = uuidv7.MustBytes()
+        }</span>
+        <span class="cov0" title="0">return nil</span>
+}
+</pre>
+		
+		<pre class="file" id="file15" style="display: none">package auth
+
+import (
+        "time"
+
+        "gorm.io/gorm"
+
+        "wucher/internal/pkg/uuidv7"
+)
+
+type Role struct {
+        ID          []byte `gorm:"type:binary(16);primaryKey;column:id"`
+        Name        string `gorm:"type:varchar(64);uniqueIndex;not null;column:name"`
+        Description string `gorm:"type:varchar(255);column:description"`
+        CreatedAt   time.Time
+        CreatedBy   []byte `gorm:"type:binary(16);column:created_by"`
+        UpdatedAt   time.Time
+        UpdatedBy   []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (Role) TableName() string <span class="cov0" title="0">{ return "roles" }</span>
+
+func (r *Role) BeforeCreate(tx *gorm.DB) error <span class="cov0" title="0">{
+        if len(r.ID) == 0 </span><span class="cov0" title="0">{
+                r.ID = uuidv7.MustBytes()
+        }</span>
+        <span class="cov0" title="0">return nil</span>
+}
+</pre>
+		
+		<pre class="file" id="file16" style="display: none">package auth
+
+import (
+        "time"
+
+        "gorm.io/gorm"
+
+        "wucher/internal/pkg/uuidv7"
+)
+
+type RolePermission struct {
+        ID           []byte `gorm:"type:binary(16);primaryKey;column:id"`
+        RoleID       []byte `gorm:"type:binary(16);index;uniqueIndex:ux_role_permission;not null;column:role_id"`
+        PermissionID []byte `gorm:"type:binary(16);index;uniqueIndex:ux_role_permission;not null;column:permission_id"`
+        CreatedAt    time.Time
+        CreatedBy    []byte `gorm:"type:binary(16);column:created_by"`
+        UpdatedAt    time.Time
+        UpdatedBy    []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (RolePermission) TableName() string <span class="cov0" title="0">{ return "role_permissions" }</span>
+
+func (rp *RolePermission) BeforeCreate(tx *gorm.DB) error <span class="cov0" title="0">{
+        if len(rp.ID) == 0 </span><span class="cov0" title="0">{
+                rp.ID = uuidv7.MustBytes()
+        }</span>
+        <span class="cov0" title="0">return nil</span>
+}
+</pre>
+		
+		<pre class="file" id="file17" style="display: none">package auth
+
+import (
+        "time"
+
+        "gorm.io/gorm"
+
+        "wucher/internal/pkg/uuidv7"
+)
+
+type UserTOTP struct {
+        ID              []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+        UserID          []byte     `gorm:"type:binary(16);uniqueIndex;not null;column:user_id"`
+        SecretEncrypted []byte     `gorm:"type:varbinary(512);not null;column:secret_encrypted"`
+        Enabled         bool       `gorm:"type:tinyint(1);not null;default:1;column:enabled"`
+        LastUsedAt      *time.Time `gorm:"column:last_used_at"`
+        CreatedAt       time.Time
+        CreatedBy       []byte `gorm:"type:binary(16);column:created_by"`
+        UpdatedAt       time.Time
+        UpdatedBy       []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (UserTOTP) TableName() string <span class="cov0" title="0">{ return "user_totp" }</span>
+
+func (ut *UserTOTP) BeforeCreate(tx *gorm.DB) error <span class="cov0" title="0">{
+        if len(ut.ID) == 0 </span><span class="cov0" title="0">{
+                ut.ID = uuidv7.MustBytes()
+        }</span>
+        <span class="cov0" title="0">return nil</span>
+}
+</pre>
+		
+		<pre class="file" id="file18" style="display: none">package auth
+
+import (
+        "time"
+
+        "gorm.io/gorm"
+
+        "wucher/internal/pkg/uuidv7"
+)
+
+// Note: UUIDv7 should be generated at application layer and stored as BINARY(16).
+type User struct {
+        ID           []byte `gorm:"type:binary(16);primaryKey;column:id"`
+        Email        string `gorm:"type:varchar(191);uniqueIndex;not null;column:email"`
+        FirstName    string `gorm:"type:varchar(100);not null;column:first_name"`
+        LastName     string `gorm:"type:varchar(100);not null;column:last_name"`
+        MobilePhone  string `gorm:"type:varchar(32);uniqueIndex;column:mobile_phone"`
+        RoleID       []byte `gorm:"type:binary(16);index;not null;column:role_id"`
+        PasswordHash []byte `gorm:"type:varbinary(255);column:password_hash"`
+        SaltValue    []byte `gorm:"type:varbinary(255);column:salt_value"`
+        EmailVerifiedAt *time.Time `gorm:"column:email_verified_at"`
+        CreatedAt    time.Time
+        CreatedBy    []byte `gorm:"type:binary(16);column:created_by"`
+        UpdatedAt    time.Time
+        UpdatedBy    []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (User) TableName() string <span class="cov0" title="0">{ return "users" }</span>
+
+func (u *User) BeforeCreate(tx *gorm.DB) error <span class="cov0" title="0">{
+        if len(u.ID) == 0 </span><span class="cov0" title="0">{
+                u.ID = uuidv7.MustBytes()
+        }</span>
+        <span class="cov0" title="0">return nil</span>
+}
+</pre>
+		
+		<pre class="file" id="file19" style="display: none">package logger
+
+import "log"
+
+func New() *log.Logger <span class="cov0" title="0">{
+        return log.Default()
+}</span>
+</pre>
+		
+		<pre class="file" id="file20" style="display: none">package uuidv7
+
+import (
+        "crypto/rand"
+        "encoding/hex"
+        "errors"
+        "time"
+)
+
+// New returns a UUIDv7 (RFC 9562) as a 16-byte array.
+func New() ([16]byte, error) <span class="cov0" title="0">{
+        var out [16]byte
+
+        var r [10]byte
+        if _, err := rand.Read(r[:]); err != nil </span><span class="cov0" title="0">{
+                return out, err
+        }</span>
+
+        // 48-bit Unix epoch milliseconds
+        <span class="cov0" title="0">ms := uint64(time.Now().UnixNano() / int64(time.Millisecond))
+        out[0] = byte(ms &gt;&gt; 40)
+        out[1] = byte(ms &gt;&gt; 32)
+        out[2] = byte(ms &gt;&gt; 24)
+        out[3] = byte(ms &gt;&gt; 16)
+        out[4] = byte(ms &gt;&gt; 8)
+        out[5] = byte(ms)
+
+        // Version (0111) in high 4 bits of byte 6
+        out[6] = (r[0] &amp; 0x0f) | 0x70
+        out[7] = r[1]
+
+        // Variant (10) in high 2 bits of byte 8
+        out[8] = (r[2] &amp; 0x3f) | 0x80
+        out[9] = r[3]
+        out[10] = r[4]
+        out[11] = r[5]
+        out[12] = r[6]
+        out[13] = r[7]
+        out[14] = r[8]
+        out[15] = r[9]
+
+        return out, nil</span>
+}
+
+// MustNew panics if UUID generation fails.
+func MustNew() [16]byte <span class="cov0" title="0">{
+        u, err := New()
+        if err != nil </span><span class="cov0" title="0">{
+                panic(err)</span>
+        }
+        <span class="cov0" title="0">return u</span>
+}
+
+// Bytes returns a new UUIDv7 as []byte for BINARY(16) columns.
+func Bytes() ([]byte, error) <span class="cov0" title="0">{
+        u, err := New()
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov0" title="0">b := make([]byte, 16)
+        copy(b, u[:])
+        return b, nil</span>
+}
+
+// MustBytes panics if UUID generation fails.
+func MustBytes() []byte <span class="cov0" title="0">{
+        u := MustNew()
+        b := make([]byte, 16)
+        copy(b, u[:])
+        return b
+}</span>
+
+// String formats a UUID as a canonical string (8-4-4-4-12).
+func String(u [16]byte) (string, error) <span class="cov0" title="0">{
+        if len(u) != 16 </span><span class="cov0" title="0">{
+                return "", errors.New("invalid uuid length")
+        }</span>
+        <span class="cov0" title="0">dst := make([]byte, 36)
+        hex.Encode(dst[0:8], u[0:4])
+        dst[8] = '-'
+        hex.Encode(dst[9:13], u[4:6])
+        dst[13] = '-'
+        hex.Encode(dst[14:18], u[6:8])
+        dst[18] = '-'
+        hex.Encode(dst[19:23], u[8:10])
+        dst[23] = '-'
+        hex.Encode(dst[24:36], u[10:16])
+        return string(dst), nil</span>
+}
+
+// BytesToString formats a UUID stored in []byte as a canonical string.
+func BytesToString(b []byte) (string, error) <span class="cov0" title="0">{
+        if len(b) != 16 </span><span class="cov0" title="0">{
+                return "", errors.New("invalid uuid length")
+        }</span>
+        <span class="cov0" title="0">var u [16]byte
+        copy(u[:], b)
+        return String(u)</span>
+}
+
+// ParseString parses a canonical UUID string into []byte (16 bytes).
+func ParseString(s string) ([]byte, error) <span class="cov0" title="0">{
+        if len(s) != 36 </span><span class="cov0" title="0">{
+                return nil, errors.New("invalid uuid string length")
+        }</span>
+        <span class="cov0" title="0">buf := make([]byte, 16)
+        _, err := hex.Decode(buf[0:4], []byte(s[0:8]))
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov0" title="0">_, err = hex.Decode(buf[4:6], []byte(s[9:13]))
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov0" title="0">_, err = hex.Decode(buf[6:8], []byte(s[14:18]))
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov0" title="0">_, err = hex.Decode(buf[8:10], []byte(s[19:23]))
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov0" title="0">_, err = hex.Decode(buf[10:16], []byte(s[24:36]))
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov0" title="0">return buf, nil</span>
+}
+</pre>
+		
+		<pre class="file" id="file21" style="display: none">package mysql
+
+import (
+        "context"
+        "errors"
+        "time"
+
+        "gorm.io/gorm"
+        "gorm.io/gorm/clause"
+
+        "wucher/internal/domain/auth"
+)
+
+type AuthRepository struct {
+        db *gorm.DB
+}
+
+func NewAuthRepository(db *gorm.DB) *AuthRepository <span class="cov0" title="0">{
+        return &amp;AuthRepository{db: db}
+}</span>
+
+// Users
+
+func (r *AuthRepository) CreateUser(ctx context.Context, user *auth.User) error <span class="cov0" title="0">{
+        return r.db.WithContext(ctx).Create(user).Error
+}</span>
+
+func (r *AuthRepository) GetUserByID(ctx context.Context, id []byte) (*auth.User, error) <span class="cov0" title="0">{
+        var user auth.User
+        err := r.db.WithContext(ctx).First(&amp;user, "id = ?", id).Error
+        if errors.Is(err, gorm.ErrRecordNotFound) </span><span class="cov0" title="0">{
+                return nil, nil
+        }</span>
+        <span class="cov0" title="0">return &amp;user, err</span>
+}
+
+func (r *AuthRepository) GetUserByEmail(ctx context.Context, email string) (*auth.User, error) <span class="cov0" title="0">{
+        var user auth.User
+        err := r.db.WithContext(ctx).Where("email = ?", email).First(&amp;user).Error
+        if errors.Is(err, gorm.ErrRecordNotFound) </span><span class="cov0" title="0">{
+                return nil, nil
+        }</span>
+        <span class="cov0" title="0">return &amp;user, err</span>
+}
+
+func (r *AuthRepository) MarkEmailVerified(ctx context.Context, id []byte) error <span class="cov0" title="0">{
+        now := time.Now()
+        return r.db.WithContext(ctx).
+                Model(&amp;auth.User{}).
+                Where("id = ?", id).
+                Update("email_verified_at", &amp;now).Error
+}</span>
+
+// Identities (SSO)
+
+func (r *AuthRepository) UpsertIdentity(ctx context.Context, identity *auth.UserIdentity) error <span class="cov0" title="0">{
+        // Ensure we keep a single row per provider+subject
+        return r.db.WithContext(ctx).
+                Clauses(clause.OnConflict{
+                        Columns:   []clause.Column{{Name: "provider"}, {Name: "provider_subject"}},
+                        DoUpdates: clause.AssignmentColumns([]string{"user_id", "email", "metadata", "updated_at", "updated_by"}),
+                }).
+                Create(identity).Error
+}</span>
+
+func (r *AuthRepository) GetIdentityByProviderSubject(ctx context.Context, provider, subject string) (*auth.UserIdentity, error) <span class="cov0" title="0">{
+        var identity auth.UserIdentity
+        err := r.db.WithContext(ctx).
+                Where("provider = ? AND provider_subject = ?", provider, subject).
+                First(&amp;identity).Error
+        if errors.Is(err, gorm.ErrRecordNotFound) </span><span class="cov0" title="0">{
+                return nil, nil
+        }</span>
+        <span class="cov0" title="0">return &amp;identity, err</span>
+}
+
+// TOTP
+
+func (r *AuthRepository) GetUserTOTP(ctx context.Context, userID []byte) (*auth.UserTOTP, error) <span class="cov0" title="0">{
+        var totp auth.UserTOTP
+        err := r.db.WithContext(ctx).Where("user_id = ?", userID).First(&amp;totp).Error
+        if errors.Is(err, gorm.ErrRecordNotFound) </span><span class="cov0" title="0">{
+                return nil, nil
+        }</span>
+        <span class="cov0" title="0">return &amp;totp, err</span>
+}
+
+func (r *AuthRepository) UpsertUserTOTP(ctx context.Context, totp *auth.UserTOTP) error <span class="cov0" title="0">{
+        return r.db.WithContext(ctx).
+                Clauses(clause.OnConflict{
+                        Columns:   []clause.Column{{Name: "user_id"}},
+                        DoUpdates: clause.AssignmentColumns([]string{"secret_encrypted", "enabled", "updated_at", "updated_by"}),
+                }).
+                Create(totp).Error
+}</span>
+
+func (r *AuthRepository) DisableUserTOTP(ctx context.Context, userID []byte) error <span class="cov0" title="0">{
+        return r.db.WithContext(ctx).
+                Model(&amp;auth.UserTOTP{}).
+                Where("user_id = ?", userID).
+                Updates(map[string]any{
+                        "enabled":    false,
+                        "updated_at": time.Now(),
+                }).Error
+}</span>
+
+func (r *AuthRepository) UpdateUserTOTPLastUsed(ctx context.Context, userID []byte) error <span class="cov0" title="0">{
+        return r.db.WithContext(ctx).
+                Model(&amp;auth.UserTOTP{}).
+                Where("user_id = ? AND enabled = 1", userID).
+                Update("last_used_at", time.Now()).Error
+}</span>
+</pre>
+		
+		<pre class="file" id="file22" style="display: none">package mysql
+
+import (
+        "errors"
+
+        "gorm.io/driver/mysql"
+        "gorm.io/gorm"
+        "gorm.io/gorm/logger"
+
+        "wucher/internal/config"
+        "wucher/internal/domain/auth"
+)
+
+func Connect(cfg config.MySQLConfig) (*gorm.DB, error) <span class="cov0" title="0">{
+        if cfg.DSN == "" </span><span class="cov0" title="0">{
+                return nil, errors.New("MYSQL_DSN is required")
+        }</span>
+
+        <span class="cov0" title="0">db, err := gorm.Open(mysql.Open(cfg.DSN), &amp;gorm.Config{
+                Logger: logger.Default.LogMode(logger.Warn),
+        })
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+
+        <span class="cov0" title="0">sqlDB, err := db.DB()
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov0" title="0">sqlDB.SetMaxOpenConns(cfg.MaxOpenConns)
+        sqlDB.SetMaxIdleConns(cfg.MaxIdleConns)
+        sqlDB.SetConnMaxLifetime(cfg.ConnMaxLifetime)
+        sqlDB.SetConnMaxIdleTime(cfg.ConnMaxIdleTime)
+
+        return db, nil</span>
+}
+
+func AutoMigrate(db *gorm.DB) error <span class="cov0" title="0">{
+        return db.AutoMigrate(
+                &amp;auth.Role{},
+                &amp;auth.Permission{},
+                &amp;auth.User{},
+                &amp;auth.RolePermission{},
+                &amp;auth.UserIdentity{},
+                &amp;auth.UserTOTP{},
+        )
+}</span>
+</pre>
+		
+		<pre class="file" id="file23" style="display: none">package mysql
+
+import (
+        "context"
+        "errors"
+        "strings"
+
+        "gorm.io/gorm"
+
+        "wucher/internal/domain/auth"
+)
+
+type RoleRepository struct {
+        db *gorm.DB
+}
+
+func NewRoleRepository(db *gorm.DB) *RoleRepository <span class="cov0" title="0">{
+        return &amp;RoleRepository{db: db}
+}</span>
+
+func (r *RoleRepository) CreateRole(ctx context.Context, role *auth.Role) error <span class="cov0" title="0">{
+        return r.db.WithContext(ctx).Create(role).Error
+}</span>
+
+func (r *RoleRepository) UpdateRole(ctx context.Context, role *auth.Role) error <span class="cov0" title="0">{
+        return r.db.WithContext(ctx).Save(role).Error
+}</span>
+
+func (r *RoleRepository) DeleteRole(ctx context.Context, id []byte) error <span class="cov0" title="0">{
+        return r.db.WithContext(ctx).Delete(&amp;auth.Role{}, "id = ?", id).Error
+}</span>
+
+func (r *RoleRepository) GetRoleByID(ctx context.Context, id []byte) (*auth.Role, error) <span class="cov0" title="0">{
+        var role auth.Role
+        err := r.db.WithContext(ctx).First(&amp;role, "id = ?", id).Error
+        if errors.Is(err, gorm.ErrRecordNotFound) </span><span class="cov0" title="0">{
+                return nil, nil
+        }</span>
+        <span class="cov0" title="0">return &amp;role, err</span>
+}
+
+func (r *RoleRepository) GetRoleByName(ctx context.Context, name string) (*auth.Role, error) <span class="cov0" title="0">{
+        var role auth.Role
+        err := r.db.WithContext(ctx).Where("name = ?", name).First(&amp;role).Error
+        if errors.Is(err, gorm.ErrRecordNotFound) </span><span class="cov0" title="0">{
+                return nil, nil
+        }</span>
+        <span class="cov0" title="0">return &amp;role, err</span>
+}
+
+func (r *RoleRepository) ListRoles(ctx context.Context, filterName, sort string, limit, offset int) ([]auth.Role, int64, error) <span class="cov0" title="0">{
+        var roles []auth.Role
+        var total int64
+
+        query := r.db.WithContext(ctx).Model(&amp;auth.Role{})
+
+        if filterName != "" </span><span class="cov0" title="0">{
+                query = query.Where("LOWER(name) LIKE ?", "%"+strings.ToLower(filterName)+"%")
+        }</span>
+
+        <span class="cov0" title="0">if err := query.Count(&amp;total).Error; err != nil </span><span class="cov0" title="0">{
+                return nil, 0, err
+        }</span>
+
+        <span class="cov0" title="0">if sort != "" </span><span class="cov0" title="0">{
+                query = query.Order(sort)
+        }</span> else<span class="cov0" title="0"> {
+                query = query.Order("created_at DESC")
+        }</span>
+
+        <span class="cov0" title="0">if limit &gt; 0 </span><span class="cov0" title="0">{
+                query = query.Limit(limit).Offset(offset)
+        }</span>
+
+        <span class="cov0" title="0">if err := query.Find(&amp;roles).Error; err != nil </span><span class="cov0" title="0">{
+                return nil, 0, err
+        }</span>
+
+        <span class="cov0" title="0">return roles, total, nil</span>
+}
+</pre>
+		
+		<pre class="file" id="file24" style="display: none">package mysql
+
+import (
+        "context"
+        "errors"
+
+        "gorm.io/gorm"
+
+        "wucher/internal/domain/user"
+)
+
+type UserRepository struct {
+        db *gorm.DB
+}
+
+func NewUserRepository(db *gorm.DB) *UserRepository <span class="cov0" title="0">{
+        return &amp;UserRepository{db: db}
+}</span>
+
+func (r *UserRepository) Create(ctx context.Context, u *user.User) error <span class="cov0" title="0">{
+        return r.db.WithContext(ctx).Create(u).Error
+}</span>
+
+func (r *UserRepository) GetByID(ctx context.Context, id []byte) (*user.User, error) <span class="cov0" title="0">{
+        var u user.User
+        err := r.db.WithContext(ctx).First(&amp;u, "id = ?", id).Error
+        if errors.Is(err, gorm.ErrRecordNotFound) </span><span class="cov0" title="0">{
+                return nil, nil
+        }</span>
+        <span class="cov0" title="0">return &amp;u, err</span>
+}
+
+func (r *UserRepository) GetByEmail(ctx context.Context, email string) (*user.User, error) <span class="cov0" title="0">{
+        var u user.User
+        err := r.db.WithContext(ctx).Where("email = ?", email).First(&amp;u).Error
+        if errors.Is(err, gorm.ErrRecordNotFound) </span><span class="cov0" title="0">{
+                return nil, nil
+        }</span>
+        <span class="cov0" title="0">return &amp;u, err</span>
+}
+</pre>
+		
+		<pre class="file" id="file25" style="display: none">package redis
+
+import (
+        "context"
+        "time"
+
+        "github.com/redis/go-redis/v9"
+
+        "wucher/internal/service"
+)
+
+type EmailQueue struct {
+        client *redis.Client
+        key    string
+}
+
+func NewEmailQueue(client *redis.Client, key string) *EmailQueue <span class="cov0" title="0">{
+        return &amp;EmailQueue{client: client, key: key}
+}</span>
+
+func (q *EmailQueue) Enqueue(ctx context.Context, job service.EmailJob) error <span class="cov0" title="0">{
+        b, err := service.EncodeEmailJob(job)
+        if err != nil </span><span class="cov0" title="0">{
+                return err
+        }</span>
+        <span class="cov0" title="0">return q.client.RPush(ctx, q.key, b).Err()</span>
+}
+
+func (q *EmailQueue) Dequeue(ctx context.Context) (*service.EmailJob, error) <span class="cov0" title="0">{
+        res, err := q.client.BLPop(ctx, 10*time.Second, q.key).Result()
+        if err == redis.Nil </span><span class="cov0" title="0">{
+                return nil, nil
+        }</span>
+        <span class="cov0" title="0">if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov0" title="0">if len(res) &lt; 2 </span><span class="cov0" title="0">{
+                return nil, nil
+        }</span>
+        <span class="cov0" title="0">return service.DecodeEmailJob([]byte(res[1]))</span>
+}
+</pre>
+		
+		<pre class="file" id="file26" style="display: none">package redis
+
+import (
+        "context"
+
+        "github.com/redis/go-redis/v9"
+
+        "wucher/internal/config"
+)
+
+func NewClient(cfg config.RedisConfig) *redis.Client <span class="cov0" title="0">{
+        return redis.NewClient(&amp;redis.Options{
+                Addr:     cfg.Addr,
+                Password: cfg.Password,
+                DB:       cfg.DB,
+        })
+}</span>
+
+func Ping(ctx context.Context, client *redis.Client) error <span class="cov0" title="0">{
+        return client.Ping(ctx).Err()
+}</span>
+</pre>
+		
+		<pre class="file" id="file27" style="display: none">package redis
+
+import (
+        "context"
+        "time"
+
+        "github.com/redis/go-redis/v9"
+)
+
+type TokenStore struct {
+        client *redis.Client
+}
+
+func NewTokenStore(client *redis.Client) *TokenStore <span class="cov0" title="0">{
+        return &amp;TokenStore{client: client}
+}</span>
+
+func (s *TokenStore) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error <span class="cov0" title="0">{
+        return s.client.Set(ctx, key, value, ttl).Err()
+}</span>
+
+func (s *TokenStore) Get(ctx context.Context, key string) ([]byte, error) <span class="cov0" title="0">{
+        val, err := s.client.Get(ctx, key).Bytes()
+        if err == redis.Nil </span><span class="cov0" title="0">{
+                return nil, nil
+        }</span>
+        <span class="cov0" title="0">return val, err</span>
+}
+
+func (s *TokenStore) Delete(ctx context.Context, key string) error <span class="cov0" title="0">{
+        return s.client.Del(ctx, key).Err()
+}</span>
+</pre>
+		
+		<pre class="file" id="file28" style="display: none">package service
+
+import (
+        "context"
+        "crypto/rand"
+        "encoding/base64"
+        "errors"
+        "strings"
+        "time"
+
+        "github.com/golang-jwt/jwt/v5"
+        "github.com/pquerna/otp"
+        "github.com/pquerna/otp/totp"
+        "golang.org/x/crypto/argon2"
+
+        "wucher/internal/config"
+        "wucher/internal/domain/auth"
+        "wucher/internal/pkg/uuidv7"
+)
+
+var (
+        ErrInvalidCredentials = errors.New("invalid credentials")
+        ErrEmailNotVerified   = errors.New("email not verified")
+        ErrInvalidToken       = errors.New("invalid or expired token")
+        ErrTOTPRequired       = errors.New("totp required")
+)
+
+type EmailSender interface {
+        Send(ctx context.Context, to, subject, body string) error
+}
+
+type TokenStore interface {
+        Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
+        Get(ctx context.Context, key string) ([]byte, error)
+        Delete(ctx context.Context, key string) error
+}
+
+type SecretProtector interface {
+        Encrypt(plain []byte) ([]byte, error)
+        Decrypt(cipher []byte) ([]byte, error)
+}
+
+type MicrosoftSSO interface {
+        AuthCodeURL(state string) string
+        ExchangeCode(ctx context.Context, code string) (MicrosoftClaims, error)
+}
+
+type MicrosoftClaims struct {
+        Subject string
+        Email   string
+        Name    string
+}
+
+type AuthService struct {
+        repo      auth.Repository
+        roleRepo  auth.RoleRepository
+        tokens    TokenStore
+        emailQueue EmailQueue
+        mailer    EmailSender
+        sso       MicrosoftSSO
+        protector SecretProtector
+        cfg       config.AuthConfig
+}
+
+func NewAuthService(
+        repo auth.Repository,
+        roleRepo auth.RoleRepository,
+        tokens TokenStore,
+        emailQueue EmailQueue,
+        mailer EmailSender,
+        sso MicrosoftSSO,
+        protector SecretProtector,
+        cfg config.AuthConfig,
+) *AuthService <span class="cov8" title="1">{
+        return &amp;AuthService{
+                repo:      repo,
+                roleRepo:  roleRepo,
+                tokens:    tokens,
+                emailQueue: emailQueue,
+                mailer:    mailer,
+                sso:       sso,
+                protector: protector,
+                cfg:       cfg,
+        }
+}</span>
+
+func (s *AuthService) BeginMicrosoftLogin(ctx context.Context) (string, error) <span class="cov0" title="0">{
+        if s.sso == nil || s.tokens == nil </span><span class="cov0" title="0">{
+                return "", errors.New("sso not configured")
+        }</span>
+        <span class="cov0" title="0">state, err := randomToken(32)
+        if err != nil </span><span class="cov0" title="0">{
+                return "", err
+        }</span>
+        <span class="cov0" title="0">if err := s.tokens.Set(ctx, ssoStateKey(state), []byte("1"), s.cfg.SSOStateTTL); err != nil </span><span class="cov0" title="0">{
+                return "", err
+        }</span>
+        <span class="cov0" title="0">return s.sso.AuthCodeURL(state), nil</span>
+}
+
+func (s *AuthService) CompleteMicrosoftLogin(ctx context.Context, code, state string) (*auth.UserIdentity, error) <span class="cov0" title="0">{
+        if s.sso == nil || s.tokens == nil </span><span class="cov0" title="0">{
+                return nil, errors.New("sso not configured")
+        }</span>
+        <span class="cov0" title="0">if state == "" </span><span class="cov0" title="0">{
+                return nil, ErrInvalidToken
+        }</span>
+        <span class="cov0" title="0">v, err := s.tokens.Get(ctx, ssoStateKey(state))
+        if err != nil || v == nil </span><span class="cov0" title="0">{
+                return nil, ErrInvalidToken
+        }</span>
+        <span class="cov0" title="0">_ = s.tokens.Delete(ctx, ssoStateKey(state))
+        return s.LoginWithMicrosoft(ctx, code)</span>
+}
+
+// RegisterWithEmail creates a user and sends a verification link.
+func (s *AuthService) RegisterWithEmail(ctx context.Context, email, firstName, lastName, mobilePhone, password string, roleID []byte) (*auth.User, error) <span class="cov8" title="1">{
+        email = strings.ToLower(strings.TrimSpace(email))
+        if email == "" || password == "" </span><span class="cov0" title="0">{
+                return nil, errors.New("email and password are required")
+        }</span>
+
+        <span class="cov8" title="1">hash, salt, err := s.hashPassword(password)
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+
+        <span class="cov8" title="1">user := &amp;auth.User{
+                ID:           uuidv7.MustBytes(),
+                Email:        email,
+                FirstName:    firstName,
+                LastName:     lastName,
+                MobilePhone:  mobilePhone,
+                RoleID:       roleID,
+                PasswordHash: hash,
+                SaltValue:    salt,
+        }
+
+        if err := s.repo.CreateUser(ctx, user); err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+
+        <span class="cov8" title="1">if err := s.sendEmailVerification(ctx, user); err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+
+        <span class="cov8" title="1">return user, nil</span>
+}
+
+func (s *AuthService) GetRoleIDByName(ctx context.Context, name string) ([]byte, error) <span class="cov0" title="0">{
+        if s.roleRepo == nil </span><span class="cov0" title="0">{
+                return nil, errors.New("role repo not configured")
+        }</span>
+        <span class="cov0" title="0">role, err := s.roleRepo.GetRoleByName(ctx, name)
+        if err != nil || role == nil </span><span class="cov0" title="0">{
+                return nil, errors.New("role not found")
+        }</span>
+        <span class="cov0" title="0">return role.ID, nil</span>
+}
+
+func (s *AuthService) DefaultRoleName() string <span class="cov0" title="0">{ return s.cfg.DefaultRoleName }</span>
+func (s *AuthService) RegisterDisabled() bool  <span class="cov0" title="0">{ return s.cfg.DisableRegister }</span>
+
+// LoginWithEmailPassword verifies email/password and returns the user.
+func (s *AuthService) LoginWithEmailPassword(ctx context.Context, email, password string) (*auth.User, error) <span class="cov8" title="1">{
+        email = strings.ToLower(strings.TrimSpace(email))
+        user, err := s.repo.GetUserByEmail(ctx, email)
+        if err != nil || user == nil </span><span class="cov0" title="0">{
+                return nil, ErrInvalidCredentials
+        }</span>
+
+        <span class="cov8" title="1">if !s.verifyPassword(password, user.PasswordHash, user.SaltValue) </span><span class="cov0" title="0">{
+                return nil, ErrInvalidCredentials
+        }</span>
+
+        <span class="cov8" title="1">if user.EmailVerifiedAt == nil </span><span class="cov8" title="1">{
+                return nil, ErrEmailNotVerified
+        }</span>
+
+        <span class="cov8" title="1">return user, nil</span>
+}
+
+func (s *AuthService) IsTOTPEnabled(ctx context.Context, userID []byte) (bool, error) <span class="cov8" title="1">{
+        record, err := s.repo.GetUserTOTP(ctx, userID)
+        if err != nil || record == nil </span><span class="cov0" title="0">{
+                return false, err
+        }</span>
+        <span class="cov8" title="1">return record.Enabled, nil</span>
+}
+
+type TokenPair struct {
+        AccessToken  string
+        RefreshToken string
+}
+
+func (s *AuthService) IssueTokens(ctx context.Context, user *auth.User) (TokenPair, error) <span class="cov8" title="1">{
+        if s.cfg.JWTAccessSecret == "" || s.cfg.JWTRefreshSecret == "" </span><span class="cov0" title="0">{
+                return TokenPair{}, errors.New("jwt secrets not configured")
+        }</span>
+
+        <span class="cov8" title="1">now := time.Now()
+        accessClaims := jwt.MapClaims{
+                "sub":  bytesToString(user.ID),
+                "iat":  now.Unix(),
+                "exp":  now.Add(s.cfg.JWTAccessTTL).Unix(),
+                "type": "access",
+        }
+        accessToken, err := jwt.NewWithClaims(jwt.SigningMethodHS256, accessClaims).SignedString([]byte(s.cfg.JWTAccessSecret))
+        if err != nil </span><span class="cov0" title="0">{
+                return TokenPair{}, err
+        }</span>
+
+        <span class="cov8" title="1">jti, err := randomToken(32)
+        if err != nil </span><span class="cov0" title="0">{
+                return TokenPair{}, err
+        }</span>
+
+        <span class="cov8" title="1">refreshClaims := jwt.MapClaims{
+                "sub":  bytesToString(user.ID),
+                "iat":  now.Unix(),
+                "exp":  now.Add(s.cfg.JWTRefreshTTL).Unix(),
+                "jti":  jti,
+                "type": "refresh",
+        }
+        refreshToken, err := jwt.NewWithClaims(jwt.SigningMethodHS256, refreshClaims).SignedString([]byte(s.cfg.JWTRefreshSecret))
+        if err != nil </span><span class="cov0" title="0">{
+                return TokenPair{}, err
+        }</span>
+
+        // Store refresh token jti to allow revoke
+        <span class="cov8" title="1">if s.tokens != nil </span><span class="cov8" title="1">{
+                _ = s.tokens.Set(ctx, refreshKey(jti), []byte("1"), s.cfg.JWTRefreshTTL)
+        }</span>
+
+        <span class="cov8" title="1">return TokenPair{AccessToken: accessToken, RefreshToken: refreshToken}, nil</span>
+}
+
+func (s *AuthService) RefreshTokens(ctx context.Context, refreshToken string) (TokenPair, error) <span class="cov8" title="1">{
+        if refreshToken == "" </span><span class="cov0" title="0">{
+                return TokenPair{}, ErrInvalidToken
+        }</span>
+        <span class="cov8" title="1">parsed, err := jwt.Parse(refreshToken, func(t *jwt.Token) (any, error) </span><span class="cov8" title="1">{
+                if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok </span><span class="cov0" title="0">{
+                        return nil, ErrInvalidToken
+                }</span>
+                <span class="cov8" title="1">return []byte(s.cfg.JWTRefreshSecret), nil</span>
+        })
+        <span class="cov8" title="1">if err != nil || !parsed.Valid </span><span class="cov0" title="0">{
+                return TokenPair{}, ErrInvalidToken
+        }</span>
+
+        <span class="cov8" title="1">claims, ok := parsed.Claims.(jwt.MapClaims)
+        if !ok </span><span class="cov0" title="0">{
+                return TokenPair{}, ErrInvalidToken
+        }</span>
+        <span class="cov8" title="1">if claims["type"] != "refresh" </span><span class="cov0" title="0">{
+                return TokenPair{}, ErrInvalidToken
+        }</span>
+        <span class="cov8" title="1">jti, _ := claims["jti"].(string)
+        sub, _ := claims["sub"].(string)
+        if jti == "" || sub == "" </span><span class="cov0" title="0">{
+                return TokenPair{}, ErrInvalidToken
+        }</span>
+        <span class="cov8" title="1">if s.tokens != nil </span><span class="cov8" title="1">{
+                v, err := s.tokens.Get(ctx, refreshKey(jti))
+                if err != nil || v == nil </span><span class="cov8" title="1">{
+                        return TokenPair{}, ErrInvalidToken
+                }</span>
+                <span class="cov8" title="1">_ = s.tokens.Delete(ctx, refreshKey(jti))</span>
+        }
+
+        <span class="cov8" title="1">userID, err := uuidv7.ParseString(sub)
+        if err != nil </span><span class="cov0" title="0">{
+                return TokenPair{}, ErrInvalidToken
+        }</span>
+        <span class="cov8" title="1">user, err := s.repo.GetUserByID(ctx, userID)
+        if err != nil || user == nil </span><span class="cov0" title="0">{
+                return TokenPair{}, ErrInvalidToken
+        }</span>
+        <span class="cov8" title="1">return s.IssueTokens(ctx, user)</span>
+}
+
+func (s *AuthService) RevokeRefreshToken(ctx context.Context, refreshToken string) error <span class="cov0" title="0">{
+        if refreshToken == "" </span><span class="cov0" title="0">{
+                return nil
+        }</span>
+        <span class="cov0" title="0">parsed, err := jwt.Parse(refreshToken, func(t *jwt.Token) (any, error) </span><span class="cov0" title="0">{
+                if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok </span><span class="cov0" title="0">{
+                        return nil, ErrInvalidToken
+                }</span>
+                <span class="cov0" title="0">return []byte(s.cfg.JWTRefreshSecret), nil</span>
+        })
+        <span class="cov0" title="0">if err != nil || !parsed.Valid </span><span class="cov0" title="0">{
+                return nil
+        }</span>
+        <span class="cov0" title="0">claims, ok := parsed.Claims.(jwt.MapClaims)
+        if !ok </span><span class="cov0" title="0">{
+                return nil
+        }</span>
+        <span class="cov0" title="0">jti, _ := claims["jti"].(string)
+        if jti != "" &amp;&amp; s.tokens != nil </span><span class="cov0" title="0">{
+                _ = s.tokens.Delete(ctx, refreshKey(jti))
+        }</span>
+        <span class="cov0" title="0">return nil</span>
+}
+
+func (s *AuthService) ParseAccessToken(ctx context.Context, accessToken string) ([]byte, error) <span class="cov0" title="0">{
+        if accessToken == "" </span><span class="cov0" title="0">{
+                return nil, ErrInvalidToken
+        }</span>
+        <span class="cov0" title="0">parsed, err := jwt.Parse(accessToken, func(t *jwt.Token) (any, error) </span><span class="cov0" title="0">{
+                if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok </span><span class="cov0" title="0">{
+                        return nil, ErrInvalidToken
+                }</span>
+                <span class="cov0" title="0">return []byte(s.cfg.JWTAccessSecret), nil</span>
+        })
+        <span class="cov0" title="0">if err != nil || !parsed.Valid </span><span class="cov0" title="0">{
+                return nil, ErrInvalidToken
+        }</span>
+        <span class="cov0" title="0">claims, ok := parsed.Claims.(jwt.MapClaims)
+        if !ok || claims["type"] != "access" </span><span class="cov0" title="0">{
+                return nil, ErrInvalidToken
+        }</span>
+        <span class="cov0" title="0">sub, _ := claims["sub"].(string)
+        if sub == "" </span><span class="cov0" title="0">{
+                return nil, ErrInvalidToken
+        }</span>
+        <span class="cov0" title="0">return uuidv7.ParseString(sub)</span>
+}
+
+func (s *AuthService) GetUserByID(ctx context.Context, id []byte) (*auth.User, error) <span class="cov0" title="0">{
+        return s.repo.GetUserByID(ctx, id)
+}</span>
+
+func (s *AuthService) GetRoleByID(ctx context.Context, id []byte) (*auth.Role, error) <span class="cov0" title="0">{
+        if s.roleRepo == nil </span><span class="cov0" title="0">{
+                return nil, errors.New("role repo not configured")
+        }</span>
+        <span class="cov0" title="0">return s.roleRepo.GetRoleByID(ctx, id)</span>
+}
+
+func (s *AuthService) AccessTTL() time.Duration  <span class="cov0" title="0">{ return s.cfg.JWTAccessTTL }</span>
+func (s *AuthService) RefreshTTL() time.Duration <span class="cov0" title="0">{ return s.cfg.JWTRefreshTTL }</span>
+func (s *AuthService) CookieDomain() string      <span class="cov0" title="0">{ return s.cfg.JWTCookieDomain }</span>
+func (s *AuthService) CookieSecure() bool        <span class="cov0" title="0">{ return s.cfg.JWTCookieSecure }</span>
+func (s *AuthService) CookieSameSite() string    <span class="cov0" title="0">{ return s.cfg.JWTCookieSameSite }</span>
+func (s *AuthService) AccessCookieName() string  <span class="cov0" title="0">{ return s.cfg.JWTAccessCookieName }</span>
+func (s *AuthService) RefreshCookieName() string <span class="cov0" title="0">{ return s.cfg.JWTRefreshCookieName }</span>
+func (s *AuthService) SSOSuccessRedirectURL() string <span class="cov0" title="0">{ return s.cfg.SSOSuccessRedirectURL }</span>
+
+// VerifyEmail verifies a token and marks the user as verified.
+func (s *AuthService) VerifyEmail(ctx context.Context, token string) error <span class="cov0" title="0">{
+        if token == "" </span><span class="cov0" title="0">{
+                return ErrInvalidToken
+        }</span>
+        <span class="cov0" title="0">key := emailVerifyKey(token)
+        data, err := s.tokens.Get(ctx, key)
+        if err != nil || len(data) != 16 </span><span class="cov0" title="0">{
+                return ErrInvalidToken
+        }</span>
+        <span class="cov0" title="0">_ = s.tokens.Delete(ctx, key)
+        return s.repo.MarkEmailVerified(ctx, data)</span>
+}
+
+// SSO Microsoft (Entra) login flow: exchange code -&gt; upsert identity -&gt; get user.
+func (s *AuthService) LoginWithMicrosoft(ctx context.Context, code string) (*auth.UserIdentity, error) <span class="cov0" title="0">{
+        claims, err := s.sso.ExchangeCode(ctx, code)
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+
+        // If identity already exists, return it.
+        <span class="cov0" title="0">existing, err := s.repo.GetIdentityByProviderSubject(ctx, "microsoft", claims.Subject)
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov0" title="0">if existing != nil &amp;&amp; len(existing.UserID) == 16 </span><span class="cov0" title="0">{
+                return existing, nil
+        }</span>
+
+        // Ensure user exists for this identity
+        <span class="cov0" title="0">roleID, err := s.GetRoleIDByName(ctx, "user")
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+
+        <span class="cov0" title="0">firstName, lastName := splitName(claims.Name)
+        user := &amp;auth.User{
+                ID:             uuidv7.MustBytes(),
+                Email:          strings.ToLower(strings.TrimSpace(claims.Email)),
+                FirstName:      firstName,
+                LastName:       lastName,
+                RoleID:         roleID,
+                EmailVerifiedAt: ptrTime(time.Now()),
+        }
+        if err := s.repo.CreateUser(ctx, user); err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+
+        <span class="cov0" title="0">identity := &amp;auth.UserIdentity{
+                ID:              uuidv7.MustBytes(),
+                UserID:          user.ID,
+                Provider:        "microsoft",
+                ProviderSubject: claims.Subject,
+                Email:           strings.ToLower(strings.TrimSpace(claims.Email)),
+        }
+
+        if err := s.repo.UpsertIdentity(ctx, identity); err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+
+        <span class="cov0" title="0">return identity, nil</span>
+}
+
+// TOTP verify: decrypt secret and verify code (6 digits).
+func (s *AuthService) VerifyTOTP(ctx context.Context, userID []byte, code string) (bool, error) <span class="cov0" title="0">{
+        record, err := s.repo.GetUserTOTP(ctx, userID)
+        if err != nil || record == nil || !record.Enabled </span><span class="cov0" title="0">{
+                return false, nil
+        }</span>
+
+        <span class="cov0" title="0">secret, err := s.protector.Decrypt(record.SecretEncrypted)
+        if err != nil </span><span class="cov0" title="0">{
+                return false, err
+        }</span>
+
+        <span class="cov0" title="0">ok := verifyTOTP(string(secret), code)
+        if ok </span><span class="cov0" title="0">{
+                _ = s.repo.UpdateUserTOTPLastUsed(ctx, userID)
+        }</span>
+        <span class="cov0" title="0">return ok, nil</span>
+}
+
+func (s *AuthService) CreateTOTPChallenge(ctx context.Context, userID []byte) (string, error) <span class="cov0" title="0">{
+        if s.tokens == nil </span><span class="cov0" title="0">{
+                return "", errors.New("token store not configured")
+        }</span>
+        <span class="cov0" title="0">token, err := randomToken(32)
+        if err != nil </span><span class="cov0" title="0">{
+                return "", err
+        }</span>
+        <span class="cov0" title="0">if err := s.tokens.Set(ctx, totpChallengeKey(token), userID, s.cfg.TOTPChallengeTTL); err != nil </span><span class="cov0" title="0">{
+                return "", err
+        }</span>
+        <span class="cov0" title="0">return token, nil</span>
+}
+
+func (s *AuthService) ConsumeTOTPChallenge(ctx context.Context, token string) ([]byte, error) <span class="cov0" title="0">{
+        if s.tokens == nil || token == "" </span><span class="cov0" title="0">{
+                return nil, ErrInvalidToken
+        }</span>
+        <span class="cov0" title="0">data, err := s.tokens.Get(ctx, totpChallengeKey(token))
+        if err != nil || data == nil </span><span class="cov0" title="0">{
+                return nil, ErrInvalidToken
+        }</span>
+        <span class="cov0" title="0">_ = s.tokens.Delete(ctx, totpChallengeKey(token))
+        return data, nil</span>
+}
+
+// SetupTOTP creates or replaces the user's TOTP secret and returns the provisioning URI.
+func (s *AuthService) SetupTOTP(ctx context.Context, userID []byte, accountName string) (secret, otpAuthURL, issuer string, err error) <span class="cov8" title="1">{
+        if s.protector == nil </span><span class="cov0" title="0">{
+                return "", "", "", errors.New("secret protector not configured")
+        }</span>
+
+        <span class="cov8" title="1">issuer = s.cfg.TOTPIssuer
+        key, err := totp.Generate(totp.GenerateOpts{
+                Issuer:      issuer,
+                AccountName: accountName,
+        })
+        if err != nil </span><span class="cov0" title="0">{
+                return "", "", "", err
+        }</span>
+
+        <span class="cov8" title="1">secret = key.Secret()
+        otpAuthURL = key.URL()
+
+        enc, err := s.protector.Encrypt([]byte(secret))
+        if err != nil </span><span class="cov0" title="0">{
+                return "", "", "", err
+        }</span>
+
+        <span class="cov8" title="1">record := &amp;auth.UserTOTP{
+                UserID:          userID,
+                SecretEncrypted: enc,
+                Enabled:         false,
+        }
+        if err := s.repo.UpsertUserTOTP(ctx, record); err != nil </span><span class="cov0" title="0">{
+                return "", "", "", err
+        }</span>
+
+        <span class="cov8" title="1">return secret, otpAuthURL, issuer, nil</span>
+}
+
+func (s *AuthService) DisableTOTP(ctx context.Context, userID []byte) error <span class="cov0" title="0">{
+        return s.repo.DisableUserTOTP(ctx, userID)
+}</span>
+
+func (s *AuthService) ConfirmTOTP(ctx context.Context, userID []byte, code string) (bool, error) <span class="cov8" title="1">{
+        record, err := s.repo.GetUserTOTP(ctx, userID)
+        if err != nil || record == nil </span><span class="cov0" title="0">{
+                return false, ErrInvalidToken
+        }</span>
+        <span class="cov8" title="1">secret, err := s.protector.Decrypt(record.SecretEncrypted)
+        if err != nil </span><span class="cov0" title="0">{
+                return false, err
+        }</span>
+        <span class="cov8" title="1">ok := verifyTOTP(string(secret), code)
+        if !ok </span><span class="cov0" title="0">{
+                return false, nil
+        }</span>
+        <span class="cov8" title="1">record.Enabled = true
+        if err := s.repo.UpsertUserTOTP(ctx, record); err != nil </span><span class="cov0" title="0">{
+                return false, err
+        }</span>
+        <span class="cov8" title="1">return true, nil</span>
+}
+
+func (s *AuthService) sendEmailVerification(ctx context.Context, user *auth.User) error <span class="cov8" title="1">{
+        if s.tokens == nil || s.cfg.EmailVerifyURL == "" </span><span class="cov0" title="0">{
+                return nil
+        }</span>
+
+        <span class="cov8" title="1">token, err := randomToken(32)
+        if err != nil </span><span class="cov0" title="0">{
+                return err
+        }</span>
+
+        <span class="cov8" title="1">if err := s.tokens.Set(ctx, emailVerifyKey(token), user.ID, s.cfg.EmailVerifyTTL); err != nil </span><span class="cov0" title="0">{
+                return err
+        }</span>
+
+        <span class="cov8" title="1">link := strings.TrimRight(s.cfg.EmailVerifyURL, "/") + "?token=" + token
+        subject := "Verify your email"
+        body := "Click this link to verify your email: " + link
+        if s.emailQueue != nil </span><span class="cov0" title="0">{
+                return s.emailQueue.Enqueue(ctx, EmailJob{
+                        To:      user.Email,
+                        Subject: subject,
+                        Body:    body,
+                })
+        }</span>
+        <span class="cov8" title="1">if s.mailer != nil </span><span class="cov0" title="0">{
+                return s.mailer.Send(ctx, user.Email, subject, body)
+        }</span>
+        <span class="cov8" title="1">return nil</span>
+}
+
+func (s *AuthService) hashPassword(password string) (hash []byte, salt []byte, err error) <span class="cov8" title="1">{
+        salt = make([]byte, 16)
+        if _, err = rand.Read(salt); err != nil </span><span class="cov0" title="0">{
+                return nil, nil, err
+        }</span>
+        <span class="cov8" title="1">peppered := []byte(password + s.cfg.PasswordPepper)
+        hash = argon2.IDKey(peppered, salt, s.cfg.HashTime, s.cfg.HashMemoryKB, s.cfg.HashThreads, s.cfg.HashKeyLen)
+        return hash, salt, nil</span>
+}
+
+func (s *AuthService) verifyPassword(password string, hash, salt []byte) bool <span class="cov8" title="1">{
+        if len(hash) == 0 || len(salt) == 0 </span><span class="cov0" title="0">{
+                return false
+        }</span>
+        <span class="cov8" title="1">peppered := []byte(password + s.cfg.PasswordPepper)
+        candidate := argon2.IDKey(peppered, salt, s.cfg.HashTime, s.cfg.HashMemoryKB, s.cfg.HashThreads, s.cfg.HashKeyLen)
+        return subtleConstantTimeCompare(hash, candidate)</span>
+}
+
+func randomToken(n int) (string, error) <span class="cov8" title="1">{
+        b := make([]byte, n)
+        if _, err := rand.Read(b); err != nil </span><span class="cov0" title="0">{
+                return "", err
+        }</span>
+        <span class="cov8" title="1">return base64.RawURLEncoding.EncodeToString(b), nil</span>
+}
+
+func emailVerifyKey(token string) string <span class="cov8" title="1">{
+        return "auth:email_verify:" + token
+}</span>
+
+func ssoStateKey(state string) string <span class="cov0" title="0">{
+        return "auth:sso_state:" + state
+}</span>
+
+func refreshKey(jti string) string <span class="cov8" title="1">{
+        return "auth:refresh:" + jti
+}</span>
+
+func totpChallengeKey(token string) string <span class="cov0" title="0">{
+        return "auth:totp_challenge:" + token
+}</span>
+
+func bytesToString(b []byte) string <span class="cov8" title="1">{
+        s, _ := uuidv7.BytesToString(b)
+        return s
+}</span>
+
+func splitName(full string) (string, string) <span class="cov0" title="0">{
+        full = strings.TrimSpace(full)
+        if full == "" </span><span class="cov0" title="0">{
+                return "User", ""
+        }</span>
+        <span class="cov0" title="0">parts := strings.Fields(full)
+        if len(parts) == 1 </span><span class="cov0" title="0">{
+                return parts[0], ""
+        }</span>
+        <span class="cov0" title="0">return parts[0], strings.Join(parts[1:], " ")</span>
+}
+
+func ptrTime(t time.Time) *time.Time <span class="cov0" title="0">{ return &amp;t }</span>
+
+func subtleConstantTimeCompare(a, b []byte) bool <span class="cov8" title="1">{
+        if len(a) != len(b) </span><span class="cov0" title="0">{
+                return false
+        }</span>
+        <span class="cov8" title="1">var v byte
+        for i := 0; i &lt; len(a); i++ </span><span class="cov8" title="1">{
+                v |= a[i] ^ b[i]
+        }</span>
+        <span class="cov8" title="1">return v == 0</span>
+}
+
+func verifyTOTP(secret, code string) bool <span class="cov8" title="1">{
+        code = strings.ReplaceAll(code, " ", "")
+        ok, _ := totp.ValidateCustom(code, secret, time.Now().UTC(), totp.ValidateOpts{
+                Period:    30,
+                Skew:      1,
+                Digits:    otp.DigitsSix,
+                Algorithm: otp.AlgorithmSHA1,
+        })
+        return ok
+}</span>
+</pre>
+		
+		<pre class="file" id="file29" style="display: none">package service
+
+import (
+        "context"
+        "encoding/json"
+)
+
+type EmailJob struct {
+        To      string `json:"to"`
+        Subject string `json:"subject"`
+        Body    string `json:"body"`
+}
+
+type EmailQueue interface {
+        Enqueue(ctx context.Context, job EmailJob) error
+        Dequeue(ctx context.Context) (*EmailJob, error)
+}
+
+func EncodeEmailJob(job EmailJob) ([]byte, error) <span class="cov0" title="0">{
+        return json.Marshal(job)
+}</span>
+
+func DecodeEmailJob(b []byte) (*EmailJob, error) <span class="cov0" title="0">{
+        var job EmailJob
+        if err := json.Unmarshal(b, &amp;job); err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov0" title="0">return &amp;job, nil</span>
+}
+</pre>
+		
+		<pre class="file" id="file30" style="display: none">package service
+
+import (
+        "context"
+        "encoding/base64"
+        "encoding/json"
+        "errors"
+        "fmt"
+        "io"
+        "net/http"
+        "net/url"
+        "strings"
+        "time"
+
+        "wucher/internal/config"
+)
+
+type MicrosoftSSOClient struct {
+        cfg    config.MicrosoftSSOConfig
+        client *http.Client
+}
+
+func NewMicrosoftSSO(cfg config.MicrosoftSSOConfig) *MicrosoftSSOClient <span class="cov0" title="0">{
+        return &amp;MicrosoftSSOClient{
+                cfg: cfg,
+                client: &amp;http.Client{
+                        Timeout: 10 * time.Second,
+                },
+        }
+}</span>
+
+func (m *MicrosoftSSOClient) AuthCodeURL(state string) string <span class="cov0" title="0">{
+        q := url.Values{}
+        q.Set("client_id", m.cfg.ClientID)
+        q.Set("response_type", "code")
+        q.Set("redirect_uri", m.cfg.RedirectURL)
+        q.Set("response_mode", "query")
+        q.Set("scope", strings.Join(m.cfg.Scopes, " "))
+        q.Set("state", state)
+        return fmt.Sprintf("%s%s/oauth2/v2.0/authorize?%s", m.cfg.Authority, m.cfg.TenantID, q.Encode())
+}</span>
+
+func (m *MicrosoftSSOClient) ExchangeCode(ctx context.Context, code string) (MicrosoftClaims, error) <span class="cov0" title="0">{
+        if code == "" </span><span class="cov0" title="0">{
+                return MicrosoftClaims{}, errors.New("missing code")
+        }</span>
+
+        <span class="cov0" title="0">form := url.Values{}
+        form.Set("client_id", m.cfg.ClientID)
+        form.Set("client_secret", m.cfg.ClientSecret)
+        form.Set("grant_type", "authorization_code")
+        form.Set("code", code)
+        form.Set("redirect_uri", m.cfg.RedirectURL)
+        form.Set("scope", strings.Join(m.cfg.Scopes, " "))
+
+        tokenURL := fmt.Sprintf("%s%s/oauth2/v2.0/token", m.cfg.Authority, m.cfg.TenantID)
+        req, err := http.NewRequestWithContext(ctx, http.MethodPost, tokenURL, strings.NewReader(form.Encode()))
+        if err != nil </span><span class="cov0" title="0">{
+                return MicrosoftClaims{}, err
+        }</span>
+        <span class="cov0" title="0">req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+        resp, err := m.client.Do(req)
+        if err != nil </span><span class="cov0" title="0">{
+                return MicrosoftClaims{}, err
+        }</span>
+        <span class="cov0" title="0">defer resp.Body.Close()
+
+        body, _ := io.ReadAll(resp.Body)
+        if resp.StatusCode &lt; 200 || resp.StatusCode &gt;= 300 </span><span class="cov0" title="0">{
+                return MicrosoftClaims{}, fmt.Errorf("token exchange failed: %s", string(body))
+        }</span>
+
+        <span class="cov0" title="0">var token struct {
+                IDToken string `json:"id_token"`
+        }
+        if err := json.Unmarshal(body, &amp;token); err != nil </span><span class="cov0" title="0">{
+                return MicrosoftClaims{}, err
+        }</span>
+        <span class="cov0" title="0">if token.IDToken == "" </span><span class="cov0" title="0">{
+                return MicrosoftClaims{}, errors.New("missing id_token")
+        }</span>
+
+        <span class="cov0" title="0">claims, err := parseJWTClaims(token.IDToken)
+        if err != nil </span><span class="cov0" title="0">{
+                return MicrosoftClaims{}, err
+        }</span>
+
+        <span class="cov0" title="0">sub, _ := claims["sub"].(string)
+        email, _ := claims["email"].(string)
+        name, _ := claims["name"].(string)
+        if email == "" </span><span class="cov0" title="0">{
+                // Some tenants use preferred_username
+                email, _ = claims["preferred_username"].(string)
+        }</span>
+
+        <span class="cov0" title="0">return MicrosoftClaims{
+                Subject: sub,
+                Email:   email,
+                Name:    name,
+        }, nil</span>
+}
+
+func parseJWTClaims(token string) (map[string]any, error) <span class="cov0" title="0">{
+        parts := strings.Split(token, ".")
+        if len(parts) &lt; 2 </span><span class="cov0" title="0">{
+                return nil, errors.New("invalid jwt")
+        }</span>
+        <span class="cov0" title="0">payload, err := decodeSegment(parts[1])
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov0" title="0">var claims map[string]any
+        if err := json.Unmarshal(payload, &amp;claims); err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov0" title="0">return claims, nil</span>
+}
+
+func decodeSegment(seg string) ([]byte, error) <span class="cov0" title="0">{
+        seg = strings.ReplaceAll(seg, "-", "+")
+        seg = strings.ReplaceAll(seg, "_", "/")
+        switch len(seg) % 4 </span>{
+        case 2:<span class="cov0" title="0">
+                seg += "=="</span>
+        case 3:<span class="cov0" title="0">
+                seg += "="</span>
+        }
+        <span class="cov0" title="0">return io.ReadAll(base64.NewDecoder(base64.StdEncoding, strings.NewReader(seg)))</span>
+}
+</pre>
+		
+		<pre class="file" id="file31" style="display: none">package service
+
+import (
+        "context"
+        "errors"
+        "strings"
+
+        "wucher/internal/domain/auth"
+)
+
+type RoleService struct {
+        repo auth.RoleRepository
+}
+
+func NewRoleService(repo auth.RoleRepository) *RoleService <span class="cov0" title="0">{
+        return &amp;RoleService{repo: repo}
+}</span>
+
+func (s *RoleService) Create(ctx context.Context, role *auth.Role) error <span class="cov0" title="0">{
+        if strings.TrimSpace(role.Name) == "" </span><span class="cov0" title="0">{
+                return errors.New("name is required")
+        }</span>
+        <span class="cov0" title="0">return s.repo.CreateRole(ctx, role)</span>
+}
+
+func (s *RoleService) Update(ctx context.Context, role *auth.Role) error <span class="cov0" title="0">{
+        if strings.TrimSpace(role.Name) == "" </span><span class="cov0" title="0">{
+                return errors.New("name is required")
+        }</span>
+        <span class="cov0" title="0">return s.repo.UpdateRole(ctx, role)</span>
+}
+
+func (s *RoleService) Delete(ctx context.Context, id []byte) error <span class="cov0" title="0">{
+        return s.repo.DeleteRole(ctx, id)
+}</span>
+
+func (s *RoleService) GetByID(ctx context.Context, id []byte) (*auth.Role, error) <span class="cov0" title="0">{
+        return s.repo.GetRoleByID(ctx, id)
+}</span>
+
+func (s *RoleService) GetByName(ctx context.Context, name string) (*auth.Role, error) <span class="cov0" title="0">{
+        return s.repo.GetRoleByName(ctx, name)
+}</span>
+
+func (s *RoleService) List(ctx context.Context, filterName, sort string, limit, offset int) ([]auth.Role, int64, error) <span class="cov0" title="0">{
+        return s.repo.ListRoles(ctx, filterName, normalizeSort(sort), limit, offset)
+}</span>
+
+func normalizeSort(sort string) string <span class="cov0" title="0">{
+        // Allow list: name, -name, created_at, -created_at, updated_at, -updated_at
+        switch sort </span>{
+        case "name":<span class="cov0" title="0">
+                return "name ASC"</span>
+        case "-name":<span class="cov0" title="0">
+                return "name DESC"</span>
+        case "created_at":<span class="cov0" title="0">
+                return "created_at ASC"</span>
+        case "-created_at":<span class="cov0" title="0">
+                return "created_at DESC"</span>
+        case "updated_at":<span class="cov0" title="0">
+                return "updated_at ASC"</span>
+        case "-updated_at":<span class="cov0" title="0">
+                return "updated_at DESC"</span>
+        default:<span class="cov0" title="0">
+                return ""</span>
+        }
+}
+</pre>
+		
+		<pre class="file" id="file32" style="display: none">package service
+
+import (
+        "crypto/aes"
+        "crypto/cipher"
+        "crypto/rand"
+        "encoding/base64"
+        "errors"
+        "io"
+)
+
+type AESGCMProtector struct {
+        key []byte
+}
+
+func NewAESGCMProtectorFromBase64(keyB64 string) (*AESGCMProtector, error) <span class="cov8" title="1">{
+        if keyB64 == "" </span><span class="cov0" title="0">{
+                return nil, errors.New("empty key")
+        }</span>
+        <span class="cov8" title="1">key, err := base64.StdEncoding.DecodeString(keyB64)
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov8" title="1">if len(key) != 32 </span><span class="cov0" title="0">{
+                return nil, errors.New("key must be 32 bytes (base64-encoded)")
+        }</span>
+        <span class="cov8" title="1">return &amp;AESGCMProtector{key: key}, nil</span>
+}
+
+func (p *AESGCMProtector) Encrypt(plain []byte) ([]byte, error) <span class="cov8" title="1">{
+        block, err := aes.NewCipher(p.key)
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov8" title="1">gcm, err := cipher.NewGCM(block)
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov8" title="1">nonce := make([]byte, gcm.NonceSize())
+        if _, err := io.ReadFull(rand.Reader, nonce); err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov8" title="1">ciphertext := gcm.Seal(nonce, nonce, plain, nil)
+        return ciphertext, nil</span>
+}
+
+func (p *AESGCMProtector) Decrypt(ciphertext []byte) ([]byte, error) <span class="cov8" title="1">{
+        block, err := aes.NewCipher(p.key)
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov8" title="1">gcm, err := cipher.NewGCM(block)
+        if err != nil </span><span class="cov0" title="0">{
+                return nil, err
+        }</span>
+        <span class="cov8" title="1">if len(ciphertext) &lt; gcm.NonceSize() </span><span class="cov0" title="0">{
+                return nil, errors.New("ciphertext too short")
+        }</span>
+        <span class="cov8" title="1">nonce := ciphertext[:gcm.NonceSize()]
+        data := ciphertext[gcm.NonceSize():]
+        return gcm.Open(nil, nonce, data, nil)</span>
+}
+</pre>
+		
+		<pre class="file" id="file33" style="display: none">package service
+
+import (
+        "context"
+        "crypto/tls"
+        "errors"
+        "fmt"
+        "net"
+        "net/mail"
+        "net/smtp"
+        "strings"
+        "time"
+
+        "wucher/internal/config"
+)
+
+type SMTPSender struct {
+        cfg config.SMTPConfig
+}
+
+func NewSMTPSender(cfg config.SMTPConfig) *SMTPSender <span class="cov0" title="0">{
+        return &amp;SMTPSender{cfg: cfg}
+}</span>
+
+func (s *SMTPSender) Send(ctx context.Context, to, subject, body string) error <span class="cov0" title="0">{
+        if s.cfg.Host == "" || s.cfg.From == "" </span><span class="cov0" title="0">{
+                return errors.New("smtp not configured")
+        }</span>
+        <span class="cov0" title="0">if to == "" </span><span class="cov0" title="0">{
+                return errors.New("recipient is required")
+        }</span>
+
+        <span class="cov0" title="0">addr := fmt.Sprintf("%s:%d", s.cfg.Host, s.cfg.Port)
+        fromAddr, err := mail.ParseAddress(s.cfg.From)
+        if err != nil </span><span class="cov0" title="0">{
+                return err
+        }</span>
+        <span class="cov0" title="0">toAddr, err := mail.ParseAddress(to)
+        if err != nil </span><span class="cov0" title="0">{
+                return err
+        }</span>
+
+        <span class="cov0" title="0">msg := buildMessage(s.cfg.From, to, subject, body)
+
+        var c *smtp.Client
+        var conn net.Conn
+
+        dialer := &amp;net.Dialer{Timeout: 10 * time.Second}
+        tlsCfg := &amp;tls.Config{
+                ServerName:         s.cfg.Host,
+                InsecureSkipVerify: s.cfg.InsecureSkipVerify,
+        }
+
+        if s.cfg.Port == 465 </span><span class="cov0" title="0">{
+                conn, err = tls.DialWithDialer(dialer, "tcp", addr, tlsCfg)
+                if err != nil </span><span class="cov0" title="0">{
+                        return err
+                }</span>
+                <span class="cov0" title="0">c, err = smtp.NewClient(conn, s.cfg.Host)
+                if err != nil </span><span class="cov0" title="0">{
+                        _ = conn.Close()
+                        return err
+                }</span>
+        } else<span class="cov0" title="0"> {
+                conn, err = dialer.DialContext(ctx, "tcp", addr)
+                if err != nil </span><span class="cov0" title="0">{
+                        return err
+                }</span>
+                <span class="cov0" title="0">c, err = smtp.NewClient(conn, s.cfg.Host)
+                if err != nil </span><span class="cov0" title="0">{
+                        _ = conn.Close()
+                        return err
+                }</span>
+
+                <span class="cov0" title="0">if ok, _ := c.Extension("STARTTLS"); ok </span><span class="cov0" title="0">{
+                        if err := c.StartTLS(tlsCfg); err != nil </span><span class="cov0" title="0">{
+                                _ = c.Close()
+                                return err
+                        }</span>
+                }
+        }
+        <span class="cov0" title="0">defer func() </span><span class="cov0" title="0">{ _ = c.Close() }</span>()
+
+        <span class="cov0" title="0">if s.cfg.Username != "" </span><span class="cov0" title="0">{
+                auth := smtp.PlainAuth("", s.cfg.Username, s.cfg.Password, s.cfg.Host)
+                if err := c.Auth(auth); err != nil </span><span class="cov0" title="0">{
+                        return err
+                }</span>
+        }
+
+        <span class="cov0" title="0">if err := c.Mail(fromAddr.Address); err != nil </span><span class="cov0" title="0">{
+                return err
+        }</span>
+        <span class="cov0" title="0">if err := c.Rcpt(toAddr.Address); err != nil </span><span class="cov0" title="0">{
+                return err
+        }</span>
+
+        <span class="cov0" title="0">w, err := c.Data()
+        if err != nil </span><span class="cov0" title="0">{
+                return err
+        }</span>
+        <span class="cov0" title="0">if _, err := w.Write([]byte(msg)); err != nil </span><span class="cov0" title="0">{
+                _ = w.Close()
+                return err
+        }</span>
+        <span class="cov0" title="0">if err := w.Close(); err != nil </span><span class="cov0" title="0">{
+                return err
+        }</span>
+
+        <span class="cov0" title="0">return c.Quit()</span>
+}
+
+func buildMessage(from, to, subject, body string) string <span class="cov0" title="0">{
+        subject = strings.ReplaceAll(subject, "\n", "")
+        subject = strings.ReplaceAll(subject, "\r", "")
+        return strings.Join([]string{
+                fmt.Sprintf("From: %s", from),
+                fmt.Sprintf("To: %s", to),
+                fmt.Sprintf("Subject: %s", subject),
+                "MIME-Version: 1.0",
+                `Content-Type: text/plain; charset="UTF-8"`,
+                "",
+                body,
+        }, "\r\n")
+}</span>
+</pre>
+		
+		<pre class="file" id="file34" style="display: none">package service
+
+import (
+        "context"
+
+        "wucher/internal/domain/user"
+)
+
+type UserService struct {
+        repo user.Repository
+}
+
+func NewUserService(repo user.Repository) *UserService <span class="cov0" title="0">{
+        return &amp;UserService{repo: repo}
+}</span>
+
+func (s *UserService) Create(ctx context.Context, u *user.User) error <span class="cov0" title="0">{
+        return s.repo.Create(ctx, u)
+}</span>
+
+func (s *UserService) GetByID(ctx context.Context, id []byte) (*user.User, error) <span class="cov0" title="0">{
+        return s.repo.GetByID(ctx, id)
+}</span>
+
+func (s *UserService) GetByEmail(ctx context.Context, email string) (*user.User, error) <span class="cov0" title="0">{
+        return s.repo.GetByEmail(ctx, email)
+}</span>
+</pre>
+		
+		<pre class="file" id="file35" style="display: none">package handlers
+
+import (
+        "strings"
+
+        "github.com/gofiber/fiber/v2"
+
+        "wucher/internal/pkg/uuidv7"
+        "wucher/internal/service"
+        "wucher/internal/transport/http/dto"
+        "wucher/internal/transport/http/jsonapi"
+        "wucher/internal/transport/http/response"
+        "wucher/internal/transport/http/validators"
+)
+
+type AuthHandler struct {
+        svc      *service.AuthService
+        validate *validators.Validator
+}
+
+func NewAuthHandler(svc *service.AuthService) *AuthHandler <span class="cov8" title="1">{
+        return &amp;AuthHandler{
+                svc:      svc,
+                validate: validators.New(),
+        }
+}</span>
+
+// Register godoc
+// @Summary Register user with email &amp; password
+// @Description Creates user (default role: admin) and sends verification link to email.
+// @Description Next: open verify link -&gt; then login.
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.RegisterRequest true "JSON:API Register request"
+// @Success 201 {object} dto.UserResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/register [post]
+func (h *AuthHandler) Register(c *fiber.Ctx) error <span class="cov0" title="0">{
+        if h.svc.RegisterDisabled() </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusForbidden, []jsonapi.ErrorObject{{
+                        Status: "403",
+                        Title:  "Registration disabled",
+                        Detail: "registration is disabled in this environment",
+                }})
+        }</span>
+
+        <span class="cov0" title="0">var req dto.RegisterRequest
+        if err := c.BodyParser(&amp;req); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Invalid JSON",
+                        Detail: err.Error(),
+                }})
+        }</span>
+
+        <span class="cov0" title="0">if errs := h.validate.ValidateStruct(req); errs != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+        }</span>
+
+        <span class="cov0" title="0">roleID, err := h.svc.GetRoleIDByName(c.Context(), h.svc.DefaultRoleName())
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Role not found",
+                        Detail: "default role not found",
+                }})
+        }</span>
+
+        <span class="cov0" title="0">user, err := h.svc.RegisterWithEmail(
+                c.Context(),
+                req.Data.Attributes.Email,
+                req.Data.Attributes.FirstName,
+                req.Data.Attributes.LastName,
+                strings.TrimSpace(req.Data.Attributes.MobilePhone),
+                req.Data.Attributes.Password,
+                roleID,
+        )
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Registration failed",
+                        Detail: err.Error(),
+                }})
+        }</span>
+
+        <span class="cov0" title="0">tokens, err := h.svc.IssueTokens(c.Context(), user)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Token issue failed",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov0" title="0">setAuthCookies(c, h.svc, tokens)
+
+        id, _ := uuidv7.BytesToString(user.ID)
+        resp := jsonapi.Resource{
+                Type: "user",
+                ID:   id,
+                Attributes: map[string]any{
+                        "email":       user.Email,
+                        "first_name":  user.FirstName,
+                        "last_name":   user.LastName,
+                        "role_id":     func() string </span><span class="cov0" title="0">{ s, _ := uuidv7.BytesToString(roleID); return s }</span>(),
+                        "mobile_phone": user.MobilePhone,
+                },
+        }
+        <span class="cov0" title="0">return response.Write(c, fiber.StatusCreated, resp)</span>
+}
+
+// Login godoc
+// @Summary Login with email &amp; password
+// @Description If TOTP enabled, returns 202 + challenge_token. Then call /auth/totp/verify.
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.LoginRequest true "JSON:API Login request"
+// @Success 200 {object} dto.UserResponse
+// @Success 202 {object} dto.LoginTOTPRequiredResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/login [post]
+func (h *AuthHandler) Login(c *fiber.Ctx) error <span class="cov8" title="1">{
+        var req dto.LoginRequest
+        if err := c.BodyParser(&amp;req); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Invalid JSON",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov8" title="1">if errs := h.validate.ValidateStruct(req); errs != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+        }</span>
+
+        <span class="cov8" title="1">user, err := h.svc.LoginWithEmailPassword(c.Context(), req.Data.Attributes.Email, req.Data.Attributes.Password)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+                        Status: "401",
+                        Title:  "Unauthorized",
+                        Detail: err.Error(),
+                }})
+        }</span>
+
+        <span class="cov8" title="1">if ok, _ := h.svc.IsTOTPEnabled(c.Context(), user.ID); ok </span><span class="cov8" title="1">{
+                token, err := h.svc.CreateTOTPChallenge(c.Context(), user.ID)
+                if err != nil </span><span class="cov0" title="0">{
+                        return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                                Status: "400",
+                                Title:  "TOTP challenge failed",
+                                Detail: err.Error(),
+                        }})
+                }</span>
+                <span class="cov8" title="1">return response.Write(c, fiber.StatusAccepted, jsonapi.Resource{
+                        Type: "auth_totp_required",
+                        Attributes: map[string]any{
+                                "requires_totp":  true,
+                                "challenge_token": token,
+                        },
+                })</span>
+        }
+
+        <span class="cov0" title="0">tokens, err := h.svc.IssueTokens(c.Context(), user)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Token issue failed",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov0" title="0">setAuthCookies(c, h.svc, tokens)
+
+        id, _ := uuidv7.BytesToString(user.ID)
+        roleID, _ := uuidv7.BytesToString(user.RoleID)
+        var emailVerifiedAt string
+        if user.EmailVerifiedAt != nil </span><span class="cov0" title="0">{
+                emailVerifiedAt = user.EmailVerifiedAt.UTC().Format("2006-01-02T15:04:05Z07:00")
+        }</span>
+        <span class="cov0" title="0">var roleAttrs any
+        role, _ := h.svc.GetRoleByID(c.Context(), user.RoleID)
+        if role != nil </span><span class="cov0" title="0">{
+                roleIDStr, _ := uuidv7.BytesToString(role.ID)
+                roleAttrs = map[string]any{
+                        "id":          roleIDStr,
+                        "name":        role.Name,
+                        "description": role.Description,
+                }
+        }</span>
+
+        <span class="cov0" title="0">resp := jsonapi.Resource{
+                Type: "user",
+                ID:   id,
+                Attributes: map[string]any{
+                        "email":             user.Email,
+                        "first_name":        user.FirstName,
+                        "last_name":         user.LastName,
+                        "mobile_phone":      user.MobilePhone,
+                        "role_id":           roleID,
+                        "email_verified_at": emailVerifiedAt,
+                        "role":              roleAttrs,
+                },
+        }
+        return response.Write(c, fiber.StatusOK, resp)</span>
+}
+
+// VerifyEmail godoc
+// @Summary Verify email
+// @Description Confirms email verification after register.
+// @Tags Auth
+// @Produce json
+// @Param token query string true "Verification token"
+// @Success 200 {object} dto.VerifyEmailResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/verify-email [get]
+func (h *AuthHandler) VerifyEmail(c *fiber.Ctx) error <span class="cov0" title="0">{
+        token := c.Query("token")
+        if token == "" </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Invalid token",
+                        Detail: "token is required",
+                        Source: &amp;jsonapi.ErrorSource{Pointer: "/query/token"},
+                }})
+        }</span>
+        <span class="cov0" title="0">if err := h.svc.VerifyEmail(c.Context(), token); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Invalid token",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov0" title="0">return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+                Type: "auth_verify_email",
+                Attributes: map[string]any{
+                        "verified": true,
+                },
+        })</span>
+}
+
+// MicrosoftLogin godoc
+// @Summary Microsoft Entra SSO login
+// @Description Returns the Microsoft authorization URL. Browser should redirect user to this URL.
+// @Tags Auth
+// @Produce json
+// @Success 200 {object} dto.MicrosoftLoginResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/microsoft/login [get]
+func (h *AuthHandler) MicrosoftLogin(c *fiber.Ctx) error <span class="cov0" title="0">{
+        urlStr, err := h.svc.BeginMicrosoftLogin(c.Context())
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "SSO not configured",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov0" title="0">return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+                Type: "auth_microsoft_url",
+                Attributes: map[string]any{
+                        "url": urlStr,
+                },
+        })</span>
+}
+
+// MicrosoftCallback godoc
+// @Summary Microsoft Entra SSO callback
+// @Description Sets auth cookies and redirects to AUTH_SSO_SUCCESS_REDIRECT if configured.
+// @Tags Auth
+// @Produce json
+// @Param code query string true "Authorization code"
+// @Param state query string true "State"
+// @Success 200 {object} dto.MicrosoftCallbackResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/microsoft/callback [get]
+func (h *AuthHandler) MicrosoftCallback(c *fiber.Ctx) error <span class="cov0" title="0">{
+        code := c.Query("code")
+        state := c.Query("state")
+        if code == "" || state == "" </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Invalid callback",
+                        Detail: "code and state are required",
+                }})
+        }</span>
+        <span class="cov0" title="0">identity, err := h.svc.CompleteMicrosoftLogin(c.Context(), code, state)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "SSO login failed",
+                        Detail: err.Error(),
+                }})
+        }</span>
+
+        // Issue cookies and redirect to FE if configured
+        <span class="cov0" title="0">user, err := h.svc.GetUserByID(c.Context(), identity.UserID)
+        if err == nil &amp;&amp; user != nil </span><span class="cov0" title="0">{
+                tokens, err := h.svc.IssueTokens(c.Context(), user)
+                if err == nil </span><span class="cov0" title="0">{
+                        setAuthCookies(c, h.svc, tokens)
+                }</span>
+        }
+
+        <span class="cov0" title="0">if redirect := h.svc.SSOSuccessRedirectURL(); redirect != "" </span><span class="cov0" title="0">{
+                return c.Redirect(redirect, fiber.StatusFound)
+        }</span>
+
+        <span class="cov0" title="0">id, _ := uuidv7.BytesToString(identity.ID)
+        return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+                Type: "auth_identity",
+                ID:   id,
+                Attributes: map[string]any{
+                        "provider":         identity.Provider,
+                        "provider_subject": identity.ProviderSubject,
+                        "email":            identity.Email,
+                },
+        })</span>
+}
+
+// Me godoc
+// @Summary Get current user
+// @Tags Auth
+// @Produce json
+// @Success 200 {object} dto.UserResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Router /api/v1/auth/me [get]
+func (h *AuthHandler) Me(c *fiber.Ctx) error <span class="cov0" title="0">{
+        userID, ok := c.Locals("user_id").([]byte)
+        if !ok || len(userID) == 0 </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+                        Status: "401",
+                        Title:  "Unauthorized",
+                        Detail: "missing auth context",
+                }})
+        }</span>
+
+        <span class="cov0" title="0">user, err := h.svc.GetUserByID(c.Context(), userID)
+        if err != nil || user == nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+                        Status: "401",
+                        Title:  "Unauthorized",
+                        Detail: "user not found",
+                }})
+        }</span>
+
+        <span class="cov0" title="0">id, _ := uuidv7.BytesToString(user.ID)
+        roleID, _ := uuidv7.BytesToString(user.RoleID)
+        var emailVerifiedAt string
+        if user.EmailVerifiedAt != nil </span><span class="cov0" title="0">{
+                emailVerifiedAt = user.EmailVerifiedAt.UTC().Format("2006-01-02T15:04:05Z07:00")
+        }</span>
+
+        <span class="cov0" title="0">var roleAttrs any
+        role, _ := h.svc.GetRoleByID(c.Context(), user.RoleID)
+        if role != nil </span><span class="cov0" title="0">{
+                roleIDStr, _ := uuidv7.BytesToString(role.ID)
+                roleAttrs = map[string]any{
+                        "id":          roleIDStr,
+                        "name":        role.Name,
+                        "description": role.Description,
+                }
+        }</span>
+
+        <span class="cov0" title="0">return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+                Type: "user",
+                ID:   id,
+                Attributes: map[string]any{
+                        "email":             user.Email,
+                        "first_name":        user.FirstName,
+                        "last_name":         user.LastName,
+                        "mobile_phone":      user.MobilePhone,
+                        "role_id":           roleID,
+                        "email_verified_at": emailVerifiedAt,
+                        "role":              roleAttrs,
+                },
+        })</span>
+}
+
+// Refresh godoc
+// @Summary Refresh access token
+// @Tags Auth
+// @Produce json
+// @Success 200 {object} dto.TokenResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Router /api/v1/auth/refresh [post]
+func (h *AuthHandler) Refresh(c *fiber.Ctx) error <span class="cov0" title="0">{
+        refreshToken := c.Cookies(h.svc.RefreshCookieName())
+        tokens, err := h.svc.RefreshTokens(c.Context(), refreshToken)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+                        Status: "401",
+                        Title:  "Unauthorized",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov0" title="0">setAuthCookies(c, h.svc, tokens)
+        return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+                Type: "auth_tokens",
+                Attributes: map[string]any{
+                        "access_expires_in":  int64(h.svc.AccessTTL().Seconds()),
+                        "refresh_expires_in": int64(h.svc.RefreshTTL().Seconds()),
+                },
+        })</span>
+}
+
+// Logout godoc
+// @Summary Logout (revoke refresh)
+// @Tags Auth
+// @Produce json
+// @Success 200 {object} dto.VerifyEmailResponse
+// @Router /api/v1/auth/logout [post]
+func (h *AuthHandler) Logout(c *fiber.Ctx) error <span class="cov0" title="0">{
+        refreshToken := c.Cookies(h.svc.RefreshCookieName())
+        _ = h.svc.RevokeRefreshToken(c.Context(), refreshToken)
+        clearAuthCookies(c, h.svc)
+        return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+                Type: "auth_logout",
+                Attributes: map[string]any{
+                        "logged_out": true,
+                },
+        })
+}</span>
+
+// TOTPSetup godoc
+// @Summary Setup TOTP
+// @Description Generates secret and otpauth URL. TOTP is NOT enabled until confirmed.
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.TOTPSetupRequest true "JSON:API TOTP setup request"
+// @Success 200 {object} dto.TOTPSetupResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/totp/setup [post]
+func (h *AuthHandler) TOTPSetup(c *fiber.Ctx) error <span class="cov0" title="0">{
+        var req dto.TOTPSetupRequest
+        if err := c.BodyParser(&amp;req); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Invalid JSON",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov0" title="0">if errs := h.validate.ValidateStruct(req); errs != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+        }</span>
+
+        <span class="cov0" title="0">userID, err := uuidv7.ParseString(req.Data.Attributes.UserID)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+                        Status: "422",
+                        Title:  "Validation error",
+                        Detail: "user_id is invalid UUID",
+                        Source: &amp;jsonapi.ErrorSource{Pointer: "/data/attributes/user_id"},
+                }})
+        }</span>
+
+        <span class="cov0" title="0">secret, otpURL, issuer, err := h.svc.SetupTOTP(c.Context(), userID, req.Data.Attributes.Email)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "TOTP setup failed",
+                        Detail: err.Error(),
+                }})
+        }</span>
+
+        <span class="cov0" title="0">return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+                Type: "auth_totp_setup",
+                Attributes: map[string]any{
+                        "secret":      secret,
+                        "otpauth_url": otpURL,
+                        "issuer":      issuer,
+                },
+        })</span>
+}
+
+// TOTPConfirm godoc
+// @Summary Confirm TOTP setup
+// @Description Validates initial TOTP code and enables TOTP for future logins.
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.TOTPConfirmRequest true "JSON:API TOTP confirm request"
+// @Success 200 {object} dto.VerifyEmailResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/totp/confirm [post]
+func (h *AuthHandler) TOTPConfirm(c *fiber.Ctx) error <span class="cov0" title="0">{
+        var req dto.TOTPConfirmRequest
+        if err := c.BodyParser(&amp;req); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Invalid JSON",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov0" title="0">if errs := h.validate.ValidateStruct(req); errs != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+        }</span>
+
+        <span class="cov0" title="0">userID, err := uuidv7.ParseString(req.Data.Attributes.UserID)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+                        Status: "422",
+                        Title:  "Validation error",
+                        Detail: "user_id is invalid UUID",
+                        Source: &amp;jsonapi.ErrorSource{Pointer: "/data/attributes/user_id"},
+                }})
+        }</span>
+
+        <span class="cov0" title="0">ok, err := h.svc.ConfirmTOTP(c.Context(), userID, strings.TrimSpace(req.Data.Attributes.Code))
+        if err != nil || !ok </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+                        Status: "401",
+                        Title:  "Invalid TOTP",
+                        Detail: "code is invalid or expired",
+                }})
+        }</span>
+
+        <span class="cov0" title="0">return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+                Type: "auth_totp_confirm",
+                Attributes: map[string]any{
+                        "confirmed": true,
+                },
+        })</span>
+}
+
+// TOTPVerify godoc
+// @Summary Verify TOTP code
+// @Description Completes login when TOTP is enabled and returns auth cookies.
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.TOTPVerifyRequest true "JSON:API TOTP verify request"
+// @Success 200 {object} dto.TokenResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/totp/verify [post]
+func (h *AuthHandler) TOTPVerify(c *fiber.Ctx) error <span class="cov0" title="0">{
+        var req dto.TOTPVerifyRequest
+        if err := c.BodyParser(&amp;req); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Invalid JSON",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov0" title="0">if errs := h.validate.ValidateStruct(req); errs != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+        }</span>
+
+        <span class="cov0" title="0">userID, err := h.svc.ConsumeTOTPChallenge(c.Context(), strings.TrimSpace(req.Data.Attributes.ChallengeToken))
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+                        Status: "401",
+                        Title:  "Invalid challenge",
+                        Detail: "challenge token is invalid or expired",
+                }})
+        }</span>
+
+        <span class="cov0" title="0">ok, err := h.svc.VerifyTOTP(c.Context(), userID, strings.TrimSpace(req.Data.Attributes.Code))
+        if err != nil || !ok </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+                        Status: "401",
+                        Title:  "Invalid TOTP",
+                        Detail: "code is invalid or expired",
+                }})
+        }</span>
+
+        <span class="cov0" title="0">user, err := h.svc.GetUserByID(c.Context(), userID)
+        if err != nil || user == nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+                        Status: "401",
+                        Title:  "Unauthorized",
+                        Detail: "user not found",
+                }})
+        }</span>
+
+        <span class="cov0" title="0">tokens, err := h.svc.IssueTokens(c.Context(), user)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Token issue failed",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov0" title="0">setAuthCookies(c, h.svc, tokens)
+
+        return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+                Type: "auth_tokens",
+                Attributes: map[string]any{
+                        "access_expires_in":  int64(h.svc.AccessTTL().Seconds()),
+                        "refresh_expires_in": int64(h.svc.RefreshTTL().Seconds()),
+                },
+        })</span>
+}
+
+// TOTPDisable godoc
+// @Summary Disable TOTP
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.TOTPDisableRequest true "JSON:API TOTP disable request"
+// @Success 200 {object} dto.VerifyEmailResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/totp/disable [post]
+func (h *AuthHandler) TOTPDisable(c *fiber.Ctx) error <span class="cov0" title="0">{
+        var req dto.TOTPDisableRequest
+        if err := c.BodyParser(&amp;req); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Invalid JSON",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov0" title="0">if errs := h.validate.ValidateStruct(req); errs != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+        }</span>
+
+        <span class="cov0" title="0">userID, err := uuidv7.ParseString(req.Data.Attributes.UserID)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+                        Status: "422",
+                        Title:  "Validation error",
+                        Detail: "user_id is invalid UUID",
+                        Source: &amp;jsonapi.ErrorSource{Pointer: "/data/attributes/user_id"},
+                }})
+        }</span>
+
+        <span class="cov0" title="0">if err := h.svc.DisableTOTP(c.Context(), userID); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Disable TOTP failed",
+                        Detail: err.Error(),
+                }})
+        }</span>
+
+        <span class="cov0" title="0">return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+                Type: "auth_totp_disable",
+                Attributes: map[string]any{
+                        "disabled": true,
+                },
+        })</span>
+}
+
+func setAuthCookies(c *fiber.Ctx, svc *service.AuthService, tokens service.TokenPair) <span class="cov0" title="0">{
+        c.Cookie(&amp;fiber.Cookie{
+                Name:     svc.AccessCookieName(),
+                Value:    tokens.AccessToken,
+                HTTPOnly: true,
+                Secure:   svc.CookieSecure(),
+                SameSite: parseSameSite(svc.CookieSameSite()),
+                Domain:   svc.CookieDomain(),
+                Path:     "/",
+                MaxAge:   int(svc.AccessTTL().Seconds()),
+        })
+        c.Cookie(&amp;fiber.Cookie{
+                Name:     svc.RefreshCookieName(),
+                Value:    tokens.RefreshToken,
+                HTTPOnly: true,
+                Secure:   svc.CookieSecure(),
+                SameSite: parseSameSite(svc.CookieSameSite()),
+                Domain:   svc.CookieDomain(),
+                Path:     "/api/v1/auth/refresh",
+                MaxAge:   int(svc.RefreshTTL().Seconds()),
+        })
+}</span>
+
+func clearAuthCookies(c *fiber.Ctx, svc *service.AuthService) <span class="cov0" title="0">{
+        c.Cookie(&amp;fiber.Cookie{
+                Name:     svc.AccessCookieName(),
+                Value:    "",
+                HTTPOnly: true,
+                Secure:   svc.CookieSecure(),
+                SameSite: parseSameSite(svc.CookieSameSite()),
+                Domain:   svc.CookieDomain(),
+                Path:     "/",
+                MaxAge:   -1,
+        })
+        c.Cookie(&amp;fiber.Cookie{
+                Name:     svc.RefreshCookieName(),
+                Value:    "",
+                HTTPOnly: true,
+                Secure:   svc.CookieSecure(),
+                SameSite: parseSameSite(svc.CookieSameSite()),
+                Domain:   svc.CookieDomain(),
+                Path:     "/api/v1/auth/refresh",
+                MaxAge:   -1,
+        })
+}</span>
+
+func parseSameSite(v string) string <span class="cov0" title="0">{
+        switch strings.ToLower(v) </span>{
+        case "strict":<span class="cov0" title="0">
+                return "Strict"</span>
+        case "none":<span class="cov0" title="0">
+                return "None"</span>
+        default:<span class="cov0" title="0">
+                return "Lax"</span>
+        }
+}
+</pre>
+		
+		<pre class="file" id="file36" style="display: none">package handlers
+
+import (
+        "github.com/gofiber/fiber/v2"
+        "wucher/internal/transport/http/response"
+        "wucher/internal/transport/http/jsonapi"
+)
+
+type HealthHandler struct{}
+
+func NewHealthHandler() *HealthHandler <span class="cov0" title="0">{
+        return &amp;HealthHandler{}
+}</span>
+
+func (h *HealthHandler) Handle(c *fiber.Ctx) error <span class="cov0" title="0">{
+        return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+                Type: "health",
+                Attributes: map[string]any{
+                        "status": "ok",
+                },
+        })
+}</span>
+</pre>
+		
+		<pre class="file" id="file37" style="display: none">package handlers
+
+import (
+        "strconv"
+        "strings"
+        "time"
+
+        "github.com/gofiber/fiber/v2"
+
+        "wucher/internal/domain/auth"
+        "wucher/internal/pkg/uuidv7"
+        "wucher/internal/service"
+        "wucher/internal/transport/http/dto"
+        "wucher/internal/transport/http/jsonapi"
+        "wucher/internal/transport/http/response"
+        "wucher/internal/transport/http/validators"
+)
+
+type RoleHandler struct {
+        svc      *service.RoleService
+        validate *validators.Validator
+}
+
+func NewRoleHandler(svc *service.RoleService) *RoleHandler <span class="cov0" title="0">{
+        return &amp;RoleHandler{
+                svc:      svc,
+                validate: validators.New(),
+        }
+}</span>
+
+// CreateRole godoc
+// @Summary Create role
+// @Description Create a new role. Name must be unique.
+// @Tags Roles
+// @Accept json
+// @Produce json
+// @Param request body dto.RoleCreateRequest true "JSON:API Role create request"
+// @Success 201 {object} dto.RoleResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/roles [post]
+func (h *RoleHandler) Create(c *fiber.Ctx) error <span class="cov0" title="0">{
+        var req dto.RoleCreateRequest
+        if err := c.BodyParser(&amp;req); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Invalid JSON",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov0" title="0">if errs := h.validate.ValidateStruct(req); errs != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+        }</span>
+
+        <span class="cov0" title="0">role := &amp;auth.Role{
+                Name:        strings.TrimSpace(req.Data.Attributes.Name),
+                Description: strings.TrimSpace(req.Data.Attributes.Description),
+        }
+
+        if err := h.svc.Create(c.Context(), role); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Create failed",
+                        Detail: err.Error(),
+                }})
+        }</span>
+
+        <span class="cov0" title="0">return response.Write(c, fiber.StatusCreated, roleResource(role))</span>
+}
+
+// UpdateRole godoc
+// @Summary Update role
+// @Description Update role by ID. Name must be unique.
+// @Tags Roles
+// @Accept json
+// @Produce json
+// @Param id path string true "Role ID (UUIDv7)"
+// @Param request body dto.RoleUpdateRequest true "JSON:API Role update request"
+// @Success 200 {object} dto.RoleResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/roles/{id} [put]
+func (h *RoleHandler) Update(c *fiber.Ctx) error <span class="cov0" title="0">{
+        idStr := c.Params("id")
+        roleID, err := uuidv7.ParseString(idStr)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+                        Status: "422",
+                        Title:  "Validation error",
+                        Detail: "id is invalid UUID",
+                        Source: &amp;jsonapi.ErrorSource{Pointer: "/path/id"},
+                }})
+        }</span>
+
+        <span class="cov0" title="0">var req dto.RoleUpdateRequest
+        if err := c.BodyParser(&amp;req); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Invalid JSON",
+                        Detail: err.Error(),
+                }})
+        }</span>
+        <span class="cov0" title="0">if errs := h.validate.ValidateStruct(req); errs != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+        }</span>
+
+        <span class="cov0" title="0">existing, err := h.svc.GetByID(c.Context(), roleID)
+        if err != nil || existing == nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+                        Status: "404",
+                        Title:  "Not found",
+                        Detail: "role not found",
+                }})
+        }</span>
+
+        <span class="cov0" title="0">existing.Name = strings.TrimSpace(req.Data.Attributes.Name)
+        existing.Description = strings.TrimSpace(req.Data.Attributes.Description)
+
+        if err := h.svc.Update(c.Context(), existing); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Update failed",
+                        Detail: err.Error(),
+                }})
+        }</span>
+
+        <span class="cov0" title="0">return response.Write(c, fiber.StatusOK, roleResource(existing))</span>
+}
+
+// DeleteRole godoc
+// @Summary Delete role
+// @Tags Roles
+// @Produce json
+// @Param id path string true "Role ID (UUIDv7)"
+// @Success 200 {object} dto.VerifyEmailResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/roles/{id} [delete]
+func (h *RoleHandler) Delete(c *fiber.Ctx) error <span class="cov0" title="0">{
+        idStr := c.Params("id")
+        roleID, err := uuidv7.ParseString(idStr)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+                        Status: "422",
+                        Title:  "Validation error",
+                        Detail: "id is invalid UUID",
+                        Source: &amp;jsonapi.ErrorSource{Pointer: "/path/id"},
+                }})
+        }</span>
+
+        <span class="cov0" title="0">if err := h.svc.Delete(c.Context(), roleID); err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Delete failed",
+                        Detail: err.Error(),
+                }})
+        }</span>
+
+        <span class="cov0" title="0">return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+                Type: "role_delete",
+                Attributes: map[string]any{
+                        "deleted": true,
+                },
+        })</span>
+}
+
+// GetRoleByID godoc
+// @Summary Get role by ID
+// @Tags Roles
+// @Produce json
+// @Param id path string true "Role ID (UUIDv7)"
+// @Success 200 {object} dto.RoleResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/roles/{id} [get]
+func (h *RoleHandler) GetByID(c *fiber.Ctx) error <span class="cov0" title="0">{
+        idStr := c.Params("id")
+        roleID, err := uuidv7.ParseString(idStr)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+                        Status: "422",
+                        Title:  "Validation error",
+                        Detail: "id is invalid UUID",
+                        Source: &amp;jsonapi.ErrorSource{Pointer: "/path/id"},
+                }})
+        }</span>
+
+        <span class="cov0" title="0">role, err := h.svc.GetByID(c.Context(), roleID)
+        if err != nil || role == nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+                        Status: "404",
+                        Title:  "Not found",
+                        Detail: "role not found",
+                }})
+        }</span>
+
+        <span class="cov0" title="0">return response.Write(c, fiber.StatusOK, roleResource(role))</span>
+}
+
+// ListRoles godoc
+// @Summary List roles
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: name, -name, created_at, -created_at, updated_at, -updated_at.
+// @Tags Roles
+// @Produce json
+// @Param filter[name] query string false "Filter by name (contains)"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.RoleListResponse
+// @Router /api/v1/roles [get]
+func (h *RoleHandler) List(c *fiber.Ctx) error <span class="cov0" title="0">{
+        filterName := c.Query("filter[name]")
+        pageNumber := parseIntDefault(c.Query("page[number]"), 1)
+        pageSize := parseIntDefault(c.Query("page[size]"), 20)
+        if pageSize &gt; 100 </span><span class="cov0" title="0">{
+                pageSize = 100
+        }</span>
+        <span class="cov0" title="0">if pageNumber &lt; 1 </span><span class="cov0" title="0">{
+                pageNumber = 1
+        }</span>
+
+        <span class="cov0" title="0">offset := (pageNumber - 1) * pageSize
+        sort := c.Query("sort")
+
+        roles, total, err := h.svc.List(c.Context(), filterName, sort, pageSize, offset)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "List failed",
+                        Detail: err.Error(),
+                }})
+        }</span>
+
+        <span class="cov0" title="0">data := make([]dto.RoleResource, 0, len(roles))
+        for i := range roles </span><span class="cov0" title="0">{
+                data = append(data, roleResource(&amp;roles[i]))
+        }</span>
+
+        <span class="cov0" title="0">meta := map[string]any{
+                "page_number": pageNumber,
+                "page_size":   pageSize,
+                "total":       total,
+        }
+
+        return response.WriteWithMeta(c, fiber.StatusOK, data, meta)</span>
+}
+
+// ListRolesDatatable godoc
+// @Summary List roles (datatable)
+// @Description DataTables-style params with JSON:API response. Use draw/start/length/search[value].
+// @Tags Roles
+// @Produce json
+// @Param draw query int false "Draw counter"
+// @Param start query int false "Offset"
+// @Param length query int false "Page size"
+// @Param search[value] query string false "Search term"
+// @Success 200 {object} dto.RoleDataTableResponse
+// @Router /api/v1/roles/datatable [get]
+func (h *RoleHandler) ListDatatable(c *fiber.Ctx) error <span class="cov0" title="0">{
+        draw := parseIntDefault(c.Query("draw"), 1)
+        start := parseIntDefault(c.Query("start"), 0)
+        length := parseIntDefault(c.Query("length"), 20)
+        if length &gt; 100 </span><span class="cov0" title="0">{
+                length = 100
+        }</span>
+        <span class="cov0" title="0">search := c.Query("search[value]")
+
+        roles, total, err := h.svc.List(c.Context(), search, "", length, start)
+        if err != nil </span><span class="cov0" title="0">{
+                return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "List failed",
+                        Detail: err.Error(),
+                }})
+        }</span>
+
+        <span class="cov0" title="0">data := make([]dto.RoleResource, 0, len(roles))
+        for i := range roles </span><span class="cov0" title="0">{
+                data = append(data, roleResource(&amp;roles[i]))
+        }</span>
+
+        <span class="cov0" title="0">meta := map[string]any{
+                "draw":             draw,
+                "records_total":    total,
+                "records_filtered": total,
+        }
+
+        return response.WriteWithMeta(c, fiber.StatusOK, data, meta)</span>
+}
+
+func roleResource(role *auth.Role) dto.RoleResource <span class="cov0" title="0">{
+        id, _ := uuidv7.BytesToString(role.ID)
+        return dto.RoleResource{
+                Type: "role",
+                ID:   id,
+                Attributes: dto.RoleAttributes{
+                        Name:        role.Name,
+                        Description: role.Description,
+                        CreatedAt:   role.CreatedAt.UTC().Format(time.RFC3339),
+                        UpdatedAt:   role.UpdatedAt.UTC().Format(time.RFC3339),
+                },
+        }
+}</span>
+
+func parseIntDefault(v string, def int) int <span class="cov0" title="0">{
+        if v == "" </span><span class="cov0" title="0">{
+                return def
+        }</span>
+        <span class="cov0" title="0">n, err := strconv.Atoi(v)
+        if err != nil </span><span class="cov0" title="0">{
+                return def
+        }</span>
+        <span class="cov0" title="0">return n</span>
+}
+</pre>
+		
+		<pre class="file" id="file38" style="display: none">package handlers
+
+import (
+        "github.com/gofiber/fiber/v2"
+        "wucher/internal/domain/user"
+        "wucher/internal/transport/http/response"
+        "wucher/internal/transport/http/jsonapi"
+)
+
+type UserHandler struct {
+        svc user.Service
+}
+
+func NewUserHandler(svc user.Service) *UserHandler <span class="cov0" title="0">{
+        return &amp;UserHandler{svc: svc}
+}</span>
+
+func (h *UserHandler) List(c *fiber.Ctx) error <span class="cov0" title="0">{
+        return response.WriteErrors(c, fiber.StatusNotImplemented, []jsonapi.ErrorObject{{
+                Status: "501",
+                Title:  "Not implemented",
+        }})
+}</span>
+
+func (h *UserHandler) Get(c *fiber.Ctx) error <span class="cov0" title="0">{
+        return response.WriteErrors(c, fiber.StatusNotImplemented, []jsonapi.ErrorObject{{
+                Status: "501",
+                Title:  "Not implemented",
+        }})
+}</span>
+</pre>
+		
+		<pre class="file" id="file39" style="display: none">package jsonapi
+
+import "github.com/gofiber/fiber/v2"
+
+type Resource struct {
+        Type       string         `json:"type"`
+        ID         string         `json:"id,omitempty"`
+        Attributes map[string]any `json:"attributes,omitempty"`
+}
+
+type Document struct {
+        Data any `json:"data"`
+        Meta any `json:"meta,omitempty"`
+}
+
+type ErrorSource struct {
+        Pointer string `json:"pointer,omitempty"`
+}
+
+type ErrorObject struct {
+        Status string       `json:"status"`
+        Code   string       `json:"code,omitempty"`
+        Title  string       `json:"title,omitempty"`
+        Detail string       `json:"detail,omitempty"`
+        Source *ErrorSource `json:"source,omitempty"`
+}
+
+type ErrorDocument struct {
+        Errors []ErrorObject `json:"errors"`
+}
+
+func Write(c *fiber.Ctx, status int, data any) error <span class="cov0" title="0">{
+        return c.Status(status).JSON(Document{Data: data})
+}</span>
+
+func WriteWithMeta(c *fiber.Ctx, status int, data any, meta any) error <span class="cov0" title="0">{
+        return c.Status(status).JSON(Document{Data: data, Meta: meta})
+}</span>
+
+func WriteErrors(c *fiber.Ctx, status int, errs []ErrorObject) error <span class="cov0" title="0">{
+        return c.Status(status).JSON(ErrorDocument{Errors: errs})
+}</span>
+</pre>
+		
+		<pre class="file" id="file40" style="display: none">package middleware
+
+import (
+        "github.com/gofiber/fiber/v2"
+
+        "wucher/internal/service"
+        "wucher/internal/transport/http/jsonapi"
+        "wucher/internal/transport/http/response"
+)
+
+func AuthRequired(svc *service.AuthService) fiber.Handler <span class="cov0" title="0">{
+        return func(c *fiber.Ctx) error </span><span class="cov0" title="0">{
+                if svc == nil </span><span class="cov0" title="0">{
+                        return response.WriteErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+                                Status: "401",
+                                Title:  "Unauthorized",
+                                Detail: "auth service not configured",
+                        }})
+                }</span>
+
+                <span class="cov0" title="0">token := c.Cookies(svc.AccessCookieName())
+                userID, err := svc.ParseAccessToken(c.Context(), token)
+                if err != nil </span><span class="cov0" title="0">{
+                        return response.WriteErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+                                Status: "401",
+                                Title:  "Unauthorized",
+                                Detail: "invalid or expired token",
+                        }})
+                }</span>
+
+                <span class="cov0" title="0">c.Locals("user_id", userID)
+                return c.Next()</span>
+        }
+}
+</pre>
+		
+		<pre class="file" id="file41" style="display: none">package validators
+
+import (
+        "fmt"
+        "reflect"
+        "strings"
+
+        "github.com/go-playground/validator/v10"
+
+        "wucher/internal/transport/http/jsonapi"
+)
+
+type Validator struct {
+        validate *validator.Validate
+}
+
+func New() *Validator <span class="cov0" title="0">{
+        v := validator.New()
+        v.RegisterTagNameFunc(func(fld reflect.StructField) string </span><span class="cov0" title="0">{
+                name := fld.Tag.Get("json")
+                if name == "" </span><span class="cov0" title="0">{
+                        return fld.Name
+                }</span>
+                <span class="cov0" title="0">if idx := strings.Index(name, ","); idx != -1 </span><span class="cov0" title="0">{
+                        return name[:idx]
+                }</span>
+                <span class="cov0" title="0">return name</span>
+        })
+        <span class="cov0" title="0">return &amp;Validator{validate: v}</span>
+}
+
+func (v *Validator) ValidateStruct(s any) []jsonapi.ErrorObject <span class="cov0" title="0">{
+        if err := v.validate.Struct(s); err != nil </span><span class="cov0" title="0">{
+                if ve, ok := err.(validator.ValidationErrors); ok </span><span class="cov0" title="0">{
+                        return toJSONAPIErrors(ve)
+                }</span>
+                <span class="cov0" title="0">return []jsonapi.ErrorObject{{
+                        Status: "400",
+                        Title:  "Invalid request",
+                        Detail: err.Error(),
+                }}</span>
+        }
+        <span class="cov0" title="0">return nil</span>
+}
+
+func toJSONAPIErrors(ve validator.ValidationErrors) []jsonapi.ErrorObject <span class="cov0" title="0">{
+        errs := make([]jsonapi.ErrorObject, 0, len(ve))
+        for _, fe := range ve </span><span class="cov0" title="0">{
+                field := fe.Field()
+                jsonPath := "/data/attributes/" + strings.ReplaceAll(field, ".", "/")
+                errs = append(errs, jsonapi.ErrorObject{
+                        Status: "422",
+                        Title:  "Validation error",
+                        Detail: fmt.Sprintf("%s is %s", field, fe.Tag()),
+                        Source: &amp;jsonapi.ErrorSource{Pointer: jsonPath},
+                })
+        }</span>
+        <span class="cov0" title="0">return errs</span>
+}
+</pre>
+		
+		</div>
+	</body>
+	<script>
+	(function() {
+		var files = document.getElementById('files');
+		var visible;
+		files.addEventListener('change', onChange, false);
+		function select(part) {
+			if (visible)
+				visible.style.display = 'none';
+			visible = document.getElementById(part);
+			if (!visible)
+				return;
+			files.value = part;
+			visible.style.display = 'block';
+			location.hash = part;
+		}
+		function onChange() {
+			select(files.value);
+			window.scrollTo(0, 0);
+		}
+		if (location.hash != "") {
+			select(location.hash.substr(1));
+		}
+		if (!visible) {
+			select("file0");
+		}
+	})();
+	</script>
+</html>
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
new file mode 100644
index 0000000..edcc3bb
--- /dev/null
+++ b/docker-compose.dev.yml
@@ -0,0 +1,114 @@
+services:
+  api:
+    image: mybitlab/wfm:be-dev
+    env_file:
+      - .env
+    environment:
+      HTTP_PORT: "8080"
+      APP_ENV: development
+      CONFIG_BASE_PATH: /opt/flight-manager/development
+    volumes:
+      - /opt/flight-manager/development/config.generated.json:/opt/flight-manager/development/config.generated.json:ro
+      - ./configs:/app/configs:ro
+    ports:
+      - 8086:8080
+    restart: unless-stopped
+    networks:
+      - wucher
+      - db_net
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test:
+        - CMD
+        - /app/healthcheck
+        - http://127.0.0.1:8080/health
+      interval: 30s
+      timeout: 3s
+      start_period: 20s
+      retries: 3
+    labels:
+      - "logging=enabled"
+  worker:
+    image: mybitlab/wfm:be-dev-worker
+    env_file:
+      - .env
+    environment:
+      QUEUE_WORKER_MONITOR_ADDR: 0.0.0.0:9090
+      WORKER_JOB: email
+      APP_ENV: development
+      CONFIG_BASE_PATH: /opt/flight-manager/development
+    volumes:
+      - /opt/flight-manager/development/config.generated.json:/opt/flight-manager/development/config.generated.json:ro
+    expose:
+      - 9090
+    # ports:
+    #   - 9092:9090
+    restart: unless-stopped
+    networks:
+      - wucher
+      - db_net
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test:
+        - CMD
+        - /app/healthcheck
+        - http://127.0.0.1:9090/health
+      interval: 30s
+      timeout: 3s
+      start_period: 20s
+      retries: 3
+    labels:
+      - "logging=enabled"
+
+  file-worker:
+    image: mybitlab/wfm:be-dev-file-worker
+    env_file:
+      - .env
+    environment:
+      QUEUE_WORKER_MONITOR_ADDR: 0.0.0.0:9091
+      WORKER_JOB: file_processing
+      APP_ENV: development
+      CONFIG_BASE_PATH: /opt/flight-manager/development
+    volumes:
+      - /opt/flight-manager/development/config.generated.json:/opt/flight-manager/development/config.generated.json:ro
+    expose:
+      - 9091
+    # ports:
+    #   - 9093:9091
+    restart: unless-stopped
+    networks:
+      - wucher
+      - db_net
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test:
+        - CMD
+        - /app/healthcheck
+        - http://127.0.0.1:9091/health
+      interval: 30s
+      timeout: 3s
+      start_period: 20s
+      retries: 3
+    labels:
+      - "logging=enabled"
+networks:
+  wucher:
+    name: wucher
+    driver: bridge
+  db_net:
+    external: true
diff --git a/docker-compose.staging.yml b/docker-compose.staging.yml
new file mode 100644
index 0000000..781ff11
--- /dev/null
+++ b/docker-compose.staging.yml
@@ -0,0 +1,110 @@
+services:
+  api:
+    image: mybitlab/wfm:be-staging
+    env_file:
+      - .env
+    environment:
+      HTTP_PORT: "8080"
+      APP_ENV: staging
+      CONFIG_BASE_PATH: /opt/flight-manager/staging
+    volumes:
+      - /opt/flight-manager/staging/config.generated.json:/opt/flight-manager/staging/config.generated.json:ro
+      - ./configs:/app/configs:ro
+    ports:
+      - 8087:8080
+    restart: unless-stopped
+    networks:
+      - fm-staging
+      - db_net
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test:
+        - CMD
+        - /app/healthcheck
+        - http://127.0.0.1:8080/health
+      interval: 30s
+      timeout: 3s
+      start_period: 20s
+      retries: 3
+    labels:
+      - "logging=enabled"
+  worker:
+    image: mybitlab/wfm:be-worker-staging
+    env_file:
+      - .env
+    environment:
+      QUEUE_WORKER_MONITOR_ADDR: 0.0.0.0:9090
+      WORKER_JOB: email
+      APP_ENV: staging
+      CONFIG_BASE_PATH: /opt/flight-manager/staging
+    volumes:
+      - /opt/flight-manager/staging/config.generated.json:/opt/flight-manager/staging/config.generated.json:ro
+    expose:
+      - 9090
+    restart: unless-stopped
+    networks:
+      - fm-staging
+      - db_net
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test:
+        - CMD
+        - /app/healthcheck
+        - http://127.0.0.1:9090/health
+      interval: 30s
+      timeout: 3s
+      start_period: 20s
+      retries: 3
+    labels:
+      - "logging=enabled"
+
+  file-worker:
+    image: mybitlab/wfm:be-staging-file-worker
+    env_file:
+      - .env
+    environment:
+      QUEUE_WORKER_MONITOR_ADDR: 0.0.0.0:9091
+      WORKER_JOB: file_processing
+      APP_ENV: staging
+      CONFIG_BASE_PATH: /opt/flight-manager/staging
+    volumes:
+      - /opt/flight-manager/staging/config.generated.json:/opt/flight-manager/staging/config.generated.json:ro
+    expose:
+      - 9091
+    restart: unless-stopped
+    networks:
+      - fm-staging
+      - db_net
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test:
+        - CMD
+        - /app/healthcheck
+        - http://127.0.0.1:9091/health
+      interval: 30s
+      timeout: 3s
+      start_period: 20s
+      retries: 3
+    labels:
+      - "logging=enabled"
+networks:
+  fm-staging:
+    external: true
+  db_net:
+    external: true
+
diff --git a/docker-compose.test.yml b/docker-compose.test.yml
new file mode 100644
index 0000000..1c41e0f
--- /dev/null
+++ b/docker-compose.test.yml
@@ -0,0 +1,110 @@
+services:
+  api:
+    # Reuses the staging image — test differs only by its .env + DB (managed at deploy)
+    image: mybitlab/wfm:be-staging
+    env_file:
+      - .env
+    environment:
+      HTTP_PORT: "8080"
+      APP_ENV: test
+      CONFIG_BASE_PATH: /opt/flight-manager/test
+    volumes:
+      - /opt/flight-manager/test/config.generated.json:/opt/flight-manager/test/config.generated.json:ro
+      - ./configs:/app/configs:ro
+    ports:
+      - 8092:8080
+    restart: unless-stopped
+    networks:
+      - fm-test
+      - db_net
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test:
+        - CMD
+        - /app/healthcheck
+        - http://127.0.0.1:8080/health
+      interval: 30s
+      timeout: 3s
+      start_period: 20s
+      retries: 3
+    labels:
+      - "logging=enabled"
+  worker:
+    image: mybitlab/wfm:be-worker-staging
+    env_file:
+      - .env
+    environment:
+      QUEUE_WORKER_MONITOR_ADDR: 0.0.0.0:9090
+      WORKER_JOB: email
+      APP_ENV: test
+      CONFIG_BASE_PATH: /opt/flight-manager/test
+    volumes:
+      - /opt/flight-manager/test/config.generated.json:/opt/flight-manager/test/config.generated.json:ro
+    expose:
+      - 9090
+    restart: unless-stopped
+    networks:
+      - fm-test
+      - db_net
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test:
+        - CMD
+        - /app/healthcheck
+        - http://127.0.0.1:9090/health
+      interval: 30s
+      timeout: 3s
+      start_period: 20s
+      retries: 3
+    labels:
+      - "logging=enabled"
+
+  file-worker:
+    image: mybitlab/wfm:be-staging-file-worker
+    env_file:
+      - .env
+    environment:
+      QUEUE_WORKER_MONITOR_ADDR: 0.0.0.0:9091
+      WORKER_JOB: file_processing
+      APP_ENV: test
+      CONFIG_BASE_PATH: /opt/flight-manager/test
+    volumes:
+      - /opt/flight-manager/test/config.generated.json:/opt/flight-manager/test/config.generated.json:ro
+    expose:
+      - 9091
+    restart: unless-stopped
+    networks:
+      - fm-test
+      - db_net
+    extra_hosts:
+      - host.docker.internal:host-gateway
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test:
+        - CMD
+        - /app/healthcheck
+        - http://127.0.0.1:9091/health
+      interval: 30s
+      timeout: 3s
+      start_period: 20s
+      retries: 3
+    labels:
+      - "logging=enabled"
+networks:
+  fm-test:
+    external: true
+  db_net:
+    external: true
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..b139dd1
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,86 @@
+# This stack runs API, email worker, and file worker containers.
+# Ensure envs in .env point to endpoints reachable from inside containers.
+# In particular, MYSQL_DSN/SQS/SES values using 127.0.0.1 will not work unless they are
+# changed to a host or service name that containers can reach.
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: api
+    image: localhost/wucher-api:dev
+    env_file:
+      - .env
+    environment:
+      HTTP_PORT: "8080"
+    ports:
+      - "8080:8080"
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test: ["CMD", "/app/healthcheck", "http://127.0.0.1:8080/health"]
+      interval: 30s
+      timeout: 3s
+      start_period: 20s
+      retries: 3
+
+  worker:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: worker
+    image: localhost/wucher-worker:dev
+    env_file:
+      - .env
+    environment:
+      # Bind to all interfaces so the monitor endpoint can be reached from the host.
+      QUEUE_WORKER_MONITOR_ADDR: "0.0.0.0:9090"
+      WORKER_JOB: "email"
+    ports:
+      - "9090:9090"
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test: ["CMD", "/app/healthcheck", "http://127.0.0.1:9090/health"]
+      interval: 30s
+      timeout: 3s
+      start_period: 20s
+      retries: 3
+
+  gotenberg:
+    image: gotenberg/gotenberg:8
+    ports:
+      - "3000:3000"
+    restart: unless-stopped
+
+  file-worker:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: file-worker
+    image: localhost/wucher-file-worker:dev
+    env_file:
+      - .env
+    environment:
+      # Bind to all interfaces so the monitor endpoint can be reached from the host.
+      QUEUE_WORKER_MONITOR_ADDR: "0.0.0.0:9091"
+      WORKER_JOB: "file_processing"
+    ports:
+      - "9091:9091"
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test: ["CMD", "/app/healthcheck", "http://127.0.0.1:9091/health"]
+      interval: 30s
+      timeout: 3s
+      start_period: 20s
+      retries: 3
diff --git a/docs/API_GUIDE.md b/docs/API_GUIDE.md
new file mode 100644
index 0000000..709747a
--- /dev/null
+++ b/docs/API_GUIDE.md
@@ -0,0 +1,423 @@
+# API Guide STEP 1 & STEP 2
+
+Dokumentasi ringkas untuk endpoint yang paling sering dipakai di backend ini.
+
+## Helicopter APIs
+
+### 1. Create helicopter
+- `POST /api/v1/helicopters/create`
+- Fungsi: membuat data helicopter baru.
+- Cara pakai: kirim payload create helicopter sesuai schema di Swagger.
+
+### 2. Update helicopter
+- `PATCH /api/v1/helicopters/update/{id}`
+- Fungsi: update sebagian field helicopter berdasarkan `id`.
+- Cara pakai: kirim field yang ingin diubah saja.
+
+### 3. Delete helicopter
+- `DELETE /api/v1/helicopters/delete/{id}`
+- Fungsi: soft delete helicopter.
+- Cara pakai: kirim `id` helicopter di path.
+
+### 4. Generate next report number
+- `POST /api/v1/helicopters/{id}/reports/next-number`
+- Fungsi: generate nomor report berikutnya dengan format `<identifier>-NNNN`.
+- Cara pakai: kirim `id` helicopter di path.
+
+### 5. Get helicopter by ID
+- `GET /api/v1/helicopters/get/{id}`
+- Fungsi: ambil detail helicopter berdasarkan `id`.
+- Cara pakai: kirim `id` helicopter di path.
+
+### 6. Get all helicopters
+- `GET /api/v1/helicopters/get-all`
+- Fungsi: list helicopter dengan filter, sort, dan pagination.
+- Cara pakai:
+  - `search` atau `filter[search]`
+  - `sort`
+  - `page[number]`, `page[size]`
+  - `page`, `size`, `limit`
+
+### 7. Get all helicopters (datatable)
+- `GET /api/v1/helicopters/get-all/dt`
+- Fungsi: list helicopter untuk datatable.
+- Cara pakai: gunakan parameter pagination datatable yang didukung backend.
+
+## Bases APIs
+
+### 1. Create base
+- `POST /api/v1/bases/create`
+- Fungsi: membuat base baru.
+- Cara pakai: kirim payload base create sesuai Swagger.
+
+### 2. Update base
+- `PATCH /api/v1/bases/update/{uuid}`
+- Fungsi: update sebagian field base.
+- Cara pakai: kirim `uuid` base di path, lalu field yang ingin diubah.
+
+### 3. Delete base
+- `DELETE /api/v1/bases/delete/{uuid}`
+- Fungsi: soft delete base.
+- Cara pakai: kirim `uuid` base di path.
+
+### 4. Get base by ID
+- `GET /api/v1/bases/get/{uuid}`
+- Fungsi: ambil detail base.
+- Cara pakai: kirim `uuid` base di path.
+
+### 5. Get all bases
+- `GET /api/v1/bases/get-all`
+- Fungsi: list base dengan filter, sort, dan pagination.
+- Cara pakai:
+  - `search` atau `filter[search]`
+  - `sort`
+  - `page[number]`, `page[size]`
+  - `page`, `size`, `limit`
+
+### 6. Get all bases (datatable)
+- `GET /api/v1/bases/get-all/dt`
+- Fungsi: list base untuk datatable.
+- Cara pakai: gunakan parameter pagination datatable yang didukung backend.
+
+## Contact APIs
+
+### 1. Create contact
+- `POST /api/v1/contacts/create`
+- Fungsi: membuat user contact baru beserta profile role-specific.
+- Cara pakai:
+  - `data.type` harus `contact_create`
+  - `role_ids` menentukan role
+  - setiap role yang dipilih harus punya object profile yang sesuai di `attributes`
+
+### 2. Update contact
+- `PATCH /api/v1/contacts/{user_id}`
+- Fungsi: update contact.
+- Cara pakai:
+  - `data.type` harus `contact_update`
+  - bisa update `role_id` dan `role_ids`
+  - `role_ids: []` akan menghapus semua role
+  - hanya satu profile role-specific boleh ada di `attributes`
+
+### 3. Get contact
+- `GET /api/v1/contacts/{user_id}`
+- Fungsi: ambil detail contact.
+- Cara pakai: kirim `user_id` di path.
+
+### 4. Get all contacts
+- `GET /api/v1/contacts/get-all`
+- Fungsi: list contact dengan filter role, pilot category, sort, dan pagination.
+- Cara pakai:
+  - filter role / pilot category sesuai kebutuhan frontend
+  - sort field seperti `name`, `email`, `is_active`, `created_at`, `updated_at`, dan lainnya
+
+### 5. Get all contacts (datatable)
+- `GET /api/v1/contacts/get-all/dt`
+- Fungsi: list contact untuk datatable.
+- Cara pakai: gunakan parameter pagination datatable yang didukung backend.
+
+### 6. Delete contact
+- `DELETE /api/v1/contacts/{user_id}`
+- Fungsi: soft delete contact.
+- Cara pakai: kirim `user_id` di path.
+
+### 7. Update contact active status
+- `PATCH /api/v1/contacts/{user_id}/status`
+- Fungsi: update status aktif contact.
+- Cara pakai: kirim `user_id` di path dan payload status.
+
+### 8. Update contact role
+- `PATCH /api/v1/contacts/{user_id}/role`
+- Fungsi: update role contact.
+- Cara pakai: kirim `user_id` di path dan payload role baru.
+
+### 9. Update pilot category
+- `PATCH /api/v1/contacts/{user_id}/pilot-category`
+- Fungsi: update pilot category.
+- Cara pakai: kirim `user_id` di path dan payload kategori.
+
+### 10. Update contact license fields
+- `PATCH /api/v1/contacts/{user_id}/license`
+- Fungsi: update data lisensi contact.
+- Cara pakai: kirim `user_id` di path dan payload field lisensi.
+
+### 11. Update chief flags
+- `PATCH /api/v1/contacts/{user_id}/chief-flags`
+- Fungsi: update flag chief.
+- Cara pakai: kirim `user_id` di path dan payload flag yang ingin diubah.
+
+### 12. Update responsible complaints flag
+- `PATCH /api/v1/contacts/{user_id}/responsible-complaints`
+- Fungsi: update flag responsible complaints.
+- Cara pakai: kirim `user_id` di path dan payload flag yang ingin diubah.
+
+### 13. Bulk update contacts status
+- `POST /api/v1/contacts/bulk-update`
+- Fungsi: update status banyak contact sekaligus.
+- Cara pakai: kirim daftar contact yang ingin diupdate.
+
+## Flights API
+
+### Get all flights
+- `GET /api/v1/flights/get-all`
+- Fungsi: list flight dengan pagination, filter, sort, dan step workflow.
+- Cara pakai:
+  - `search` atau `filter[search]`
+  - `date` atau `filter[date]` untuk filter tanggal flight
+  - `sort`
+  - `page[number]`, `page[size]`
+  - `page`, `size`, `limit`
+
+### Contoh response
+```json
+{
+  "data": [
+    {
+      "type": "flight",
+      "id": "019e8afa-e602-716c-8d2a-b6b11a89caf0",
+      "attributes": {
+        "status": "",
+        "mission_code": "M-060326-001",
+        "date": "2026-06-03",
+        "total_draft": 2,
+        "takeover": {
+          "id": "019e8afa-e5fe-7de0-ac5d-fb5ab95896b0",
+          "daily_inspection": {
+            "name": "test test",
+            "short_name": "",
+            "date": "05.06.2026",
+            "utc_time": "05:03"
+          }
+        },
+        "steps": [
+          {
+            "phase": "takeover",
+            "position": "takeover",
+            "step": 1,
+            "complete": true,
+            "id": "019e8afa-e5fe-7de0-ac5d-fb5ab95896b0",
+            "status": "completed",
+            "completed_at": "2026-06-03T00:55:59Z",
+            "completed_by": "test test"
+          },
+          {
+            "phase": "mission",
+            "step": 2,
+            "complete": true,
+            "status": "assigned",
+            "mission_type": [
+              {
+                "type": "CAT",
+                "draft": 2,
+                "completed": 0
+              }
+            ],
+            "completed_at": "",
+            "completed_by": ""
+          }
+        ],
+        "draft": [
+          {
+            "type": "CAT",
+            "items": [
+              {
+                "id": "019e9640-f7af-7940-80e8-1e9a83013afb",
+                "type": "CAT",
+                "status": "draft",
+                "flight_data_id": "019e9640-f7b0-7787-b43c-0b395ff2792a"
+              },
+              {
+                "id": "019e9640-f8cf-72b1-84dc-b50c1a3c2cc6",
+                "type": "CAT",
+                "status": "draft",
+                "flight_data_id": "019e9640-f8d0-7ea2-b250-a7e31bfba95f"
+              }
+            ]
+          }
+        ],
+        "created_at": "2026-06-03T00:55:59Z",
+        "created_by": "test test",
+        "updated_at": "2026-06-03T00:55:59Z",
+        "updated_by": "test test"
+      }
+    }
+  ],
+  "meta": {
+    "page_number": 1,
+    "page_size": 20,
+    "total": 3
+  }
+}
+```
+
+## Takeover APIs
+
+### 1. Create takeover
+- `POST /api/v1/takeovers/create`
+- Fungsi: membuat takeover secara atomik.
+- Cara pakai:
+  - `base_id`, `duty_date`, `helicopter_id`
+  - `inspection`
+  - `roster_detail`
+  - `notes`
+- Catatan:
+  - `shift_date` dan `shift_time` sudah tidak dipakai lagi di takeover request.
+  - shift diambil dari `base`.
+
+### 2. Update takeover
+- `PATCH /api/v1/takeovers/update/{id}`
+- Fungsi: replace takeover berdasarkan flight UUID.
+- Cara pakai:
+  - kirim `id` takeover / flight di path
+  - body mengikuti format takeover update yang sama dengan create
+
+### 3. Get takeover by ID
+- `GET /api/v1/takeovers/get/{id}`
+- Fungsi: ambil takeover detail.
+- Cara pakai: kirim `id` di path.
+
+### 4. Get all takeovers
+- `GET /api/v1/takeovers/get-all`
+- Fungsi: list takeover composite yang dibangun dari flight, reserve AC, duty roster, dan inspection.
+- Cara pakai: tidak ada parameter wajib.
+
+### 5. Delete takeover
+- `DELETE /api/v1/takeovers/delete/{id}`
+- Fungsi: delete takeover berdasarkan flight UUID.
+- Cara pakai: kirim `id` di path.
+
+### Payload create/update takeover
+```json
+{
+  "data": {
+    "attributes": {
+      "base_id": "string",
+      "duty_date": "string",
+      "helicopter_id": "string",
+      "inspection": {
+        "before": {
+          "file_checklist": [
+            {
+              "helicopter_file_id": "019d7000-aaaa-7bbb-8ccc-111111111111",
+              "is_done": true
+            }
+          ],
+          "fuel_added_amount": 0,
+          "fuel_amount": 0,
+          "fuel_unit": "string",
+          "hydraulic_lh_checked": true,
+          "hydraulic_rh_checked": true,
+          "note": "string",
+          "oil_engine_nr1_checked": true,
+          "oil_engine_nr2_checked": true,
+          "oil_transmission_igb_checked": true,
+          "oil_transmission_mgb_checked": true,
+          "oil_transmission_tgb_checked": true
+        },
+        "inspection_date": "2026-04-15",
+        "prepare": {
+          "file_checklist": [
+            {
+              "helicopter_file_id": "019d7000-aaaa-7bbb-8ccc-111111111111",
+              "is_done": true
+            }
+          ],
+          "notam_briefing": true,
+          "operational_flight_plan": true,
+          "weather_briefing": true
+        }
+      },
+      "notes": "string",
+      "roster_detail": {
+        "doctor": [
+          {
+            "id": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+          }
+        ],
+        "helper": [
+          {
+            "id": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+          }
+        ],
+        "other_person": [
+          {
+            "email": "guest@example.com",
+            "mobile_phone": "+43-1234",
+            "name": "Guest Person"
+          }
+        ],
+        "pilot": [
+          {
+            "co_pilot": true,
+            "crew_type": "main",
+            "examiner": true,
+            "flight_instructor": true,
+            "id": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d",
+            "line_checker": true,
+            "supervisor": true
+          }
+        ],
+        "rescuer": [
+          {
+            "id": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+          }
+        ]
+      }
+    },
+    "type": "takeover_create"
+  }
+}
+```
+
+### Response takeover detail
+```json
+{
+  "data": {
+    "type": "takeover",
+    "id": "019e8713-aa19-7fb7-a510-a0332dc69697",
+    "attributes": {
+      "id": "019e8713-aa19-7fb7-a510-a0332dc69697",
+      "flight_id": "019e8afa-e602-716c-8d2a-b6b11a89caf0",
+      "reserve_ac_id": "019e8713-aa19-7fb7-a510-a0332dc69698",
+      "flight_inspection_id": "019e8713-aa19-7fb7-a510-a0332dc69699",
+      "shift_start": "05:00:00",
+      "shift_end": "13:00:00",
+      "base_id": "019d61db-53c6-7280-87ec-e65f205c6d3b",
+      "base": {
+        "id": "019d61db-53c6-7280-87ec-e65f205c6d3b",
+        "name": "Base Name"
+      },
+      "duty_date": "2026-06-03",
+      "helicopter_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
+      "helicopter": {
+        "id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
+        "identifier": "D-HYAR",
+        "designation": "AIRBUS H145",
+        "type": "H145",
+        "aog": false,
+        "is_active": true
+      },
+      "notes": "string",
+      "roster_detail": {
+        "pilot": [],
+        "doctor": [],
+        "rescuer": [],
+        "helper": [],
+        "other_person": []
+      },
+      "inspection": {
+        "before": {},
+        "prepare": {},
+        "inspection_date": "2026-06-03"
+      }
+    }
+  }
+}
+```
+
+## Notes
+
+- `takeover` request tidak memakai `shift_date` dan `shift_time`.
+- `flights/get-all` menampilkan step `takeover`, `mission`, dan `after_flight_inspection` kalau record after inspection sudah ada.
+- `mission.step` ditampilkan sebagai `step: 2`.
+- `complete` selalu ada di response step; kalau belum selesai nilainya `false`.
+- `mission_type.completed` masih angka, karena itu hitungan draft/completed, bukan boolean.
diff --git a/docs/AUTH_SSO_FLOW.md b/docs/AUTH_SSO_FLOW.md
new file mode 100644
index 0000000..6dd05f0
--- /dev/null
+++ b/docs/AUTH_SSO_FLOW.md
@@ -0,0 +1,96 @@
+# AUTH SSO FLOW (Frontend)
+
+## 1) New SSO Login Flow
+1. Frontend calls `GET /api/v1/auth/microsoft/login`.
+2. Redirect user to `data.attributes.url`.
+3. Provider redirects to backend callback `GET /api/v1/auth/microsoft/callback?code=...&state=...`.
+4. Backend checks existing SSO mapping (`provider=microsoft` + `provider_subject`).
+5. Result:
+- Mapping + user exists: login success, cookies/session issued.
+- Mapping not found: login rejected (`401`).
+- Mapping exists but user missing: login rejected (`404`).
+
+## 2) Important Rule
+SSO **does not create new account automatically**. User must already exist and be linked first.
+
+## 3) Link SSO (for logged-in existing user)
+Endpoint: `POST /api/v1/auth/sso/link`
+
+Auth: required (same auth cookie/session as normal login).
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_sso_link",
+    "attributes": {
+      "provider": "microsoft",
+      "code": "<microsoft_authorization_code>"
+    }
+  }
+}
+```
+
+Success `200`:
+```json
+{
+  "data": {
+    "type": "auth_sso_link",
+    "attributes": {
+      "provider": "microsoft",
+      "provider_subject": "00000000-0000-0000-0000-000000000000",
+      "email": "user@example.com"
+    }
+  }
+}
+```
+
+## 4) Unlink SSO
+Endpoint: `DELETE /api/v1/auth/sso/unlink`
+
+Auth: required.
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_sso_unlink",
+    "attributes": {
+      "provider": "microsoft"
+    }
+  }
+}
+```
+
+Success `200`:
+```json
+{
+  "data": {
+    "type": "auth_sso_unlink",
+    "attributes": {
+      "provider": "microsoft",
+      "unlinked": true
+    }
+  }
+}
+```
+
+## 5) Endpoint Summary
+- `GET /api/v1/auth/microsoft/login`
+- `GET /api/v1/auth/microsoft/callback`
+- `POST /api/v1/auth/sso/link`
+- `DELETE /api/v1/auth/sso/unlink`
+
+## 6) Error Handling (Frontend)
+Handle these API errors explicitly:
+- `401 Unauthorized`
+- `403 Forbidden`
+- `404 user not found`
+- `401 sso not linked`
+- `409 sso already linked`
+- `409 sso linked to another user`
+
+Recommended behavior:
+- `401 sso not linked`: show message to login manually first, then link SSO in account settings.
+- `409` errors on link: inform user mapping conflict and stop retry loop.
+- `404 user not found`: force logout and ask user to re-authenticate.
diff --git a/docs/aog-mcf-nsr-flow.md b/docs/aog-mcf-nsr-flow.md
new file mode 100644
index 0000000..a5ddee4
--- /dev/null
+++ b/docs/aog-mcf-nsr-flow.md
@@ -0,0 +1,379 @@
+# Panduan Status Helikopter: AOG, MCF, NSR & Cara Menerbangkannya Lagi
+
+> Dokumen ini menjelaskan **kapan sebuah helikopter berhenti boleh terbang**, **kenapa**, dan **langkah apa yang harus dilakukan supaya boleh terbang lagi** — lengkap dengan endpoint yang dipakai di tiap langkah.
+>
+> Ditulis supaya bisa dimengerti baik oleh tim operasional maupun developer. Bagian teknis (endpoint, field) ada di tiap langkah, tapi alurnya diceritakan dulu dengan bahasa sederhana.
+>
+> Semua endpoint berawalan `/api/v1` dan butuh login.
+
+---
+
+## 1. Istilah Penting (versi gampang)
+
+Sebelum masuk alur, kenali dulu pemainnya:
+
+| Istilah | Bahasa gampangnya |
+|---|---|
+| **Complaint** | Laporan kerusakan/keluhan pada helikopter. "Ada yang rusak nih." |
+| **MEL** (Minimum Equipment List) | Aturan: kerusakan ini boleh ditunda berapa lama sebelum pesawat **wajib** berhenti. Ada kelas A/B/C/D (makin besar = makin lama boleh ditunda). |
+| **NON-MEL** | Kerusakan yang **tidak boleh ditunda sama sekali** → pesawat langsung berhenti. |
+| **AOG** (Aircraft On Ground) | Status "pesawat dikandangkan, **tidak boleh terbang**". |
+| **NSR** (Non-Safety Release) | Keputusan: "kerusakan ini aman ditunda, **boleh terbang dulu**" walau belum diperbaiki. |
+| **Action Taken** | Tindakan perbaikan sementara yang dicatat, supaya pesawat boleh terbang lagi — tapi **belum dianggap selesai resmi**. |
+| **EASA Release** (CRS Part-145) | Surat resmi "**pesawat sudah diperbaiki & layak terbang**". Inilah yang benar-benar **menutup** kerusakan. |
+| **MCF** (Maintenance Check Flight) | Penerbangan uji setelah perbaikan besar. Selama wajib MCF, pesawat berstatus khusus. |
+| **Fleet Status** | Data kondisi tiap helikopter: jadwal perawatan, jam terbang, status, dll. |
+
+**Inti yang paling sering bikin bingung** (akan diulang lagi nanti):
+> **Boleh terbang lagi** ≠ **kerusakan selesai.**
+> - Pesawat bisa **boleh terbang lagi** lewat *Action Taken* atau *NSR* — tapi laporannya **masih terbuka**.
+> - Kerusakan baru **benar-benar selesai (ditutup)** ketika **EASA Release ditandatangani (sign)** — bukan sekadar dibuat.
+
+---
+
+## 2. Status Helikopter & Urutannya
+
+Helikopter selalu ada di salah satu dari 4 status ini. Status **dihitung otomatis** dari kondisi data (bukan diisi manual):
+
+| Status | Artinya |
+|---|---|
+| `mcf` | Wajib penerbangan uji (Maintenance Check Flight) dulu |
+| `aog` | Dikandangkan, tidak boleh terbang |
+| `booked` | Sedang dipakai misi |
+| `available` | Sehat, siap terbang |
+
+**Kalau beberapa kondisi terjadi bersamaan, yang menang urutannya begini:**
+
+```
+MCF  >  AOG  >  Booked  >  Available
+```
+
+Contoh: helikopter yang sedang wajib MCF **dan** punya kerusakan AOG → tetap tampil `mcf` (karena MCF paling tinggi). Ini sama persis dengan sistem Wucher lama.
+
+---
+
+## 3. Gambaran Besar: 3 Jalan Sebuah Helikopter Berhenti Terbang
+
+Ada **3 sebab** helikopter jadi tidak boleh terbang. Tiap sebab punya cara keluar sendiri:
+
+| Sebab berhenti | Jadi status | Cara terbang lagi |
+|---|---|---|
+| **A. Ada kerusakan** (complaint) | `aog` | EASA Release disign (atau ditunda dulu via Action/NSR) |
+| **B. Jadwal perawatan jatuh tempo** (otomatis) | `aog` | Perbarui jadwal/selesai inspeksi → hitung ulang |
+| **C. Wajib penerbangan uji** (MCF) | `mcf` | Selesaikan MCF dengan hasil "passed" |
+
+Tiga sebab ini dibahas satu per satu di bawah.
+
+---
+
+## 4. JALAN A — Helikopter Rusak (Complaint → AOG → Perbaikan)
+
+Ini alur paling sering. Ceritanya berurutan:
+
+### Langkah 1 — Catat kerusakannya
+Begitu ada kerusakan, buat laporan (complaint).
+
+`POST /complaints/create` (permission `complaint.create`)
+
+```jsonc
+{
+  "data": {
+    "type": "complaint_create",
+    "attributes": {
+      "helicopter_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
+      "description": "Getaran di Engine 2 saat cruise",
+      "mel_severity": 0,                 // lihat tabel di Langkah 2
+      "aircraft_hours_at_report": "1245.3"
+    }
+  }
+}
+```
+
+### Langkah 2 — Tentukan seberapa parah (klasifikasi MEL)
+Field `mel_severity` menentukan **kapan pesawat harus berhenti**:
+
+| `mel_severity` | Kelas | Boleh terbang sampai kapan? |
+|---|---|---|
+| `0` | NON-MEL | **Tidak boleh sama sekali** → AOG seketika |
+| `1` | A | Maksimal **1 hari**, lewat itu → AOG |
+| `2` | B | Maksimal **3 hari** → AOG |
+| `3` | C | Maksimal **10 hari** → AOG |
+| `4` | D | Maksimal **120 hari** → AOG |
+| *(dikosongkan)* | belum diklasifikasi | Statusnya `pending_classification`, **belum bikin AOG** sampai diklasifikasi |
+
+> Klasifikasi bisa diisi belakangan lewat `PATCH /complaints/update/:id` (field `mel_severity`). Sistem mencatat siapa & kapan mengklasifikasi (audit `mel_classified_by/at`).
+
+Selama kerusakan ini bikin AOG, di Fleet Status detail helikopter akan **muncul** data `complaints` + `easa`. Kalau sudah tidak AOG, dua data itu hilang sendiri.
+
+### Langkah 3 (opsional) — Mau terbang dulu sebelum diperbaiki tuntas?
+Kadang pesawat perlu tetap operasi sambil menunggu perbaikan resmi. Ada **2 cara**, dan ini beda fungsi:
+
+**Cara 3a — Action Taken (tindakan sementara sudah dilakukan):**
+`PATCH /complaints/update/:id` isi `action_taken`.
+
+```jsonc
+{ "data": { "type": "complaint_update", "id": "<complaint_id>",
+    "attributes": {
+      "action_taken": "Kencangkan engine mount, cek torsi OK",
+      "aircraft_hours_at_fix": "1250.1"
+    } } }
+```
+→ Pesawat **boleh terbang lagi**, tapi laporan **masih terbuka**.
+
+**Cara 3b — NSR (kerusakan aman ditunda):**
+`PATCH /complaints/update/:id` isi `is_nsr: true` (**butuh permission khusus `complaint.nsr`**).
+
+```jsonc
+{ "data": { "type": "complaint_update", "id": "<complaint_id>",
+    "attributes": {
+      "is_nsr": true,
+      "nsr_reason": "Dirilis di bawah MEL, defect ditunda"
+    } } }
+```
+→ Pesawat **boleh terbang lagi**, laporan **masih terbuka**. Sistem mencatat siapa yang memutuskan NSR (`nsr_decided_by/at`).
+
+> **Beda Action Taken vs NSR:**
+> - *Action Taken* = "sudah saya tangani sementara".
+> - *NSR* = "belum ditangani, tapi memang **boleh ditunda** dengan aman".
+> Keduanya sama-sama bikin pesawat boleh terbang lagi, dan **sama-sama belum menutup laporan**.
+>
+> Membatalkan NSR: kirim `is_nsr: false` → aturan AOG berlaku lagi.
+
+### Langkah 4 — Tutup kerusakan secara resmi (EASA Release)
+Inilah langkah yang **benar-benar menyelesaikan** kerusakan. Tiga sub-langkah:
+
+**4a. Buat surat EASA-nya** (boleh draft / belum lengkap dulu):
+`POST /easa-releases/create` (permission `easa_release.create`)
+
+> ⚠️ **Syarat boleh membuat EASA:** semua complaint terbuka helikopter itu **harus sudah di-*Action Taken* atau di-NSR dulu** (Langkah 3). Kalau masih ada yang "mentah", create ditolak (`ErrEASAReleaseComplaintsPendingAction`). Jadi Langkah 3 itu **pintu masuk** ke Langkah 4.
+
+**4b. Lengkapi datanya** (kalau tadi masih draft):
+`PATCH /easa-releases/update/:id`
+
+**4c. TANDA TANGAN (sign) — ini momen kerusakan benar-benar ditutup:**
+`POST /easa-releases/sign/:id` (permission `easa_release.sign`, **tanpa body** — penandatangan = user yang sedang login).
+
+```bash
+POST /api/v1/easa-releases/sign/019d6772-471c-7b70-b42a-d94020ef61e4
+```
+
+**Sebelum bisa sign, 5 field ini WAJIB terisi:**
+
+| Field | Contoh |
+|---|---|
+| `easa_date` | `2026-06-16` |
+| `easa_ac_hours` | `1245.3` |
+| `easa_location` | `LOWI` |
+| `easa_wo_no` | `WO-2026-001` |
+| `easa_signer_id` | `145.A.50` |
+
+Kalau ada yang kosong → ditolak (`ErrEASAReleaseIncompleteForSign`) beserta daftar `missing_sign_fields`. Aturannya tegas: **EASA yang belum lengkap tidak boleh dianggap selesai.**
+
+> **Jalan pintas:** kalau datanya sudah lengkap dari awal, kamu bisa langsung sign **saat create** — tambahkan `"sign": true` di body create. (Catatan: flag `sign` ini **hanya ada di create**, tidak ada di update.)
+
+**Begitu sign berhasil, otomatis terjadi:**
+1. Surat EASA tercatat `signed_at` + `signed_by`.
+2. **Semua complaint terbuka** helikopter itu ditutup → statusnya jadi `serviced`.
+3. Karena tidak ada lagi kerusakan yang menggantung → **AOG hilang**, data `complaints`/`easa` di Fleet Status ikut hilang.
+4. Tercatat di riwayat (history): "Release to Service (EASA signed)".
+
+### Ringkasan Jalan A (urut)
+```
+Rusak → buat complaint → klasifikasi MEL
+   → (opsional) Action Taken / NSR  ➜ boleh terbang, laporan MASIH terbuka
+   → EASA create → EASA lengkapi → EASA SIGN  ✅ ➜ laporan DITUTUP, AOG hilang
+```
+
+---
+
+## 5. JALAN B — Jadwal Perawatan Jatuh Tempo (AOG Otomatis)
+
+### Apa ini?
+Tiap helikopter punya jadwal inspeksi di Fleet Status (mis. inspeksi tiap 100 jam, atau jatuh tempo di tanggal tertentu). Kalau **jam terbang** atau **tanggal** sudah melewati batas, sistem **otomatis** men-AOG-kan pesawat — tanpa perlu ada yang lapor.
+
+### Cara masuk AOG
+Diatur di Fleet Status, tiap jadwal punya:
+- `due` = batas normal (boleh berupa **jam**, mis. `1200`, atau **tanggal**, mis. `2026-09-01`)
+- `ext` = batas perpanjangan (kalau diisi, ini yang dipakai menggantikan `due`)
+
+Saat jam/tanggal aktual melewati batas → status jadi `aog` dengan keterangan otomatis (`AOG: ... next due reached`).
+
+> Engine yang tidak aktif di helikopter (flag `NR1`/`NR2` = false) **dilewati** — jadwal engine itu tidak ikut bikin AOG.
+
+### Kapan sistem menghitung ulang?
+AOG jenis ini **disimpan**, jadi perlu pemicu untuk berubah:
+- Saat data penerbangan (flight data) dibuat/diubah/dihapus.
+- Saat Fleet Status helikopter itu di-update.
+- **Otomatis tiap 1 jam** (cron) — supaya AOG berbasis tanggal tetap nyala walau tidak ada aktivitas.
+
+### Cara terbang lagi
+Perbarui jadwalnya supaya tidak lagi lewat tempo (mis. setelah inspeksi selesai, isi `due`/`ext` yang baru):
+
+`PATCH /fleet-status/update/:id`
+```jsonc
+{ "data": { "type": "fleet_status_update", "id": "<fleet_status_id>",
+    "attributes": { "maintenance_schedules": [
+      { "inspection_type": "100H", "due": "1400", "ext": "" }
+    ] } } }
+```
+Pada perhitungan ulang berikutnya, AOG otomatis ini dilepas. (Catatan: sistem hanya melepas AOG yang dibuatnya sendiri secara otomatis; AOG manual tidak disentuh.)
+
+---
+
+## 6. JALAN C — Wajib Penerbangan Uji (MCF)
+
+### Apa ini?
+Setelah pekerjaan perawatan besar, helikopter kadang wajib menjalani **penerbangan uji (MCF)** dulu sebelum dianggap normal. Selama wajib MCF, statusnya `mcf` (mengalahkan AOG).
+
+### Langkah 1 — Tandai wajib MCF (cukup minimal)
+`POST /mcf/create` (permission `mcf.create`) — body cukup `helicopter_id` saja (+ `notes` opsional). Tujuannya hanya menandai pesawat ini wajib MCF.
+
+```jsonc
+{ "data": { "type": "mcf_create",
+    "attributes": {
+      "helicopter_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
+      "notes": "Wajib MCF setelah kerja engine mount"
+    } } }
+```
+
+### Langkah 2 — Selesaikan MCF setelah terbang uji
+`POST /mcf/complete/:helicopter_id` (permission `mcf.complete`) — **pakai helicopter_id**, bukan id MCF. Wajib isi semua field hasil uji:
+
+```jsonc
+{ "data": { "type": "mcf_complete",
+    "attributes": {
+      "af_hours": "1245.3",
+      "landing_count": 3,
+      "utc_time": "2026-06-17T08:30:00Z",   // format RFC3339
+      "date": "2026-06-17",                  // format YYYY-MM-DD
+      "result": "passed",                    // passed atau failed
+      "notes": "Getaran dalam batas normal"
+    } } }
+```
+
+**Hasilnya menentukan:**
+
+| `result` | Yang terjadi |
+|---|---|
+| `passed` | MCF beres → pesawat **lepas dari status MCF** (kembali ke status lain sesuai kondisi) |
+| `failed` | Pesawat **tetap MCF**, hasil gagal dicatat ke riwayat → ulangi sampai `passed` |
+
+> Catatan: kalau tidak ada MCF terbuka untuk helikopter itu, complete ditolak (`409`).
+
+---
+
+## 7. Melihat Riwayat (History)
+
+Semua kejadian penting di atas — dari kerusakan dilaporkan, diklasifikasi, NSR, perbaikan, EASA disign, hasil MCF, sampai AOG otomatis nyala/mati — **tercatat otomatis** dalam satu garis waktu (timeline) per helikopter. Berguna untuk audit: *siapa* melakukan *apa* dan *kapan*.
+
+### Di mana lihatnya?
+`GET /fleet-status/history/:helicopter_id` (permission `flight.read`)
+
+```bash
+GET /api/v1/fleet-status/history/019d6771-5fb5-7337-837f-bc5ed85181a1?page=1&page_size=20
+```
+
+- Diurutkan **terbaru di atas**.
+- Mendukung halaman: `page` (default 1) & `page_size` (default 20).
+- Timeline ini **gabungan dua sumber**: catatan perawatan yang diselesaikan (service log) + semua kejadian aksi (complaint, EASA, MCF, AOG).
+
+### Kejadian apa saja yang tercatat?
+
+| `action` | Tercatat ketika… |
+|---|---|
+| `complaint_filed` | Laporan kerusakan dibuat |
+| `mel_classified` | Kerusakan diklasifikasi MEL (A/B/C/D atau NON-MEL) |
+| `nsr_done` | NSR diberikan (boleh terbang walau defect terbuka) |
+| `nsr_cancelled` | NSR dibatalkan |
+| `action_taken` | Tindakan perbaikan sementara dicatat |
+| `easa_created` | Surat EASA dibuat (draft) |
+| `easa_signed` | **EASA ditandatangani → kerusakan ditutup** |
+| `mcf_result` | Hasil MCF diisi (`passed`/`failed`) |
+| `aog_set` | AOG otomatis dinyalakan (jadwal jatuh tempo) |
+| `aog_cleared` | AOG otomatis dilepas |
+| `serviced` | Inspeksi/perawatan diselesaikan |
+
+### Bentuk responsnya
+
+Tiap baris timeline berisi: kapan, jenisnya, aksinya, pesan, dan **siapa pelakunya** (nama langsung tersedia di `actor_name`).
+
+```jsonc
+{
+  "data": [
+    {
+      "at": "2026-06-17T10:15:00Z",
+      "entity_type": "easa_release",
+      "entity_id": "019d6772-471c-7b70-b42a-d94020ef61e4",
+      "action": "easa_signed",
+      "message": "Release to Service (EASA signed)",
+      "actor": "019e91e6-2908-7f37-93e6-015ed1b7587d",
+      "actor_name": "John Doe"
+    },
+    {
+      "at": "2026-06-17T09:40:00Z",
+      "entity_type": "complaint",
+      "action": "action_taken",
+      "message": "Action taken — Kencangkan engine mount, cek torsi OK",
+      "actor_name": "Jane Tech"
+    }
+  ],
+  "meta": { "page_number": 1, "page_size": 20, "total": 12 }
+}
+```
+
+> Selain timeline ini, daftar **kerusakan per helikopter** (beserta status terkini, NSR, action, dan EASA terkait) bisa dilihat lewat `GET /complaints/get-by-helicopter/:helicopter_id`, dan kondisi terkini helikopter (status + complaint + EASA aktif) lewat `GET /fleet-status/get-by-helicopter/:helicopter_id`.
+
+---
+
+## 8. Tabel Endpoint Ringkas
+
+| Mau apa | Endpoint | Permission |
+|---|---|---|
+| Lapor kerusakan | `POST /complaints/create` | `complaint.create` |
+| Klasifikasi MEL / Action Taken / NSR | `PATCH /complaints/update/:id` | `complaint.update` (+`complaint.nsr` utk NSR) |
+| Lihat kerusakan per helikopter | `GET /complaints/get-by-helicopter/:helicopter_id` | `complaint.read` |
+| Buat surat EASA | `POST /easa-releases/create` | `easa_release.create` |
+| Lengkapi EASA | `PATCH /easa-releases/update/:id` | `easa_release.update` |
+| **Tanda tangan EASA (tutup kerusakan)** | `POST /easa-releases/sign/:id` | `easa_release.sign` |
+| Tandai wajib MCF | `POST /mcf/create` | `mcf.create` |
+| **Selesaikan MCF** | `POST /mcf/complete/:helicopter_id` | `mcf.complete` |
+| Atur jadwal perawatan & jam | `POST /fleet-status/create` · `PATCH /fleet-status/update/:id` | `flight.create` / `flight.update` |
+| Lihat status + complaint + EASA | `GET /fleet-status/get-by-helicopter/:helicopter_id` | `flight.read` |
+| Lihat riwayat helikopter | `GET /fleet-status/history/:helicopter_id` | `flight.read` |
+
+---
+
+## 9. Tanya–Jawab Cepat (FAQ)
+
+**T: Kerusakan dianggap selesai saat EASA dibuat atau saat disign?**
+J: Saat **disign**. Membuat (create) atau melengkapi (update) EASA **belum** menutup apa pun. Penutupan complaint terjadi tepat di endpoint `sign`.
+
+**T: Bedanya Action Taken, NSR, dan EASA Sign?**
+J:
+- **Action Taken** & **NSR** → bikin pesawat **boleh terbang lagi**, tapi laporan **masih terbuka**.
+- **EASA Sign** → **menutup** laporan secara resmi (status `serviced`).
+
+**T: Kalau cuma isi Action Taken, kapan laporannya hilang dari daftar AOG?**
+J: AOG-nya langsung hilang begitu Action Taken diisi (pesawat boleh terbang). Tapi laporannya **tetap tercatat terbuka** sampai EASA disign.
+
+**T: Kenapa saya tidak bisa membuat EASA?**
+J: Kemungkinan masih ada complaint yang belum di-Action/NSR. Selesaikan Langkah 3 dulu untuk tiap complaint terbuka.
+
+**T: Helikopter wajib MCF tapi juga ada kerusakan AOG, tampil yang mana?**
+J: Tampil `mcf`, karena MCF prioritas tertinggi.
+
+**T: AOG karena jadwal jatuh tempo kok tidak langsung hilang setelah saya update jadwal?**
+J: AOG jenis ini dihitung ulang saat ada flight data baru, update fleet status, atau otomatis tiap 1 jam. Tunggu pemicu berikutnya.
+
+**T: Di mana saya bisa lihat riwayat apa saja yang sudah terjadi pada satu helikopter?**
+J: Di `GET /fleet-status/history/:helicopter_id` — timeline lengkap (terbaru di atas) berisi siapa melakukan apa & kapan. Lihat §7.
+
+---
+
+## 10. Catatan untuk Developer
+
+- **AOG karena kerusakan** dihitung *saat dibaca* (real-time dari complaint terbuka) → berubah instan, tidak perlu job.
+- **AOG karena jadwal** *disimpan* di helikopter → perlu pemicu (flight data / update fleet / cron 1 jam). Hanya AOG otomatis yang dilepas otomatis; AOG manual tidak.
+- **MCF mengalahkan AOG** dalam prioritas status.
+- **Penutupan kerusakan hanya lewat EASA sign** — `action_taken` & `is_nsr` hanya mengangkat larangan terbang, tidak menutup laporan.
+- **Masa tenggang MEL dihitung dalam HARI** (A=1, B=3, C=10, D=120) di `internal/domain/complaint/model.go` fungsi `MELDeadline` (`* 24 * time.Hour`).
diff --git a/docs/audit-log.md b/docs/audit-log.md
new file mode 100644
index 0000000..3ed8d04
--- /dev/null
+++ b/docs/audit-log.md
@@ -0,0 +1,49 @@
+# Audit Log
+
+## Tujuan
+
+- Menyimpan jejak request API dan event penting service ke tabel `audit_logs`.
+- Bersifat append-only.
+- Tidak menyimpan secret sensitif (password, raw token).
+
+## Desain
+
+- Semua route di bawah `/api/*` dicatat otomatis oleh middleware `AuditMiddleware`.
+- Penyimpanan ke DB dilakukan async melalui `AuditLogService` (buffered queue + worker) agar request API tetap cepat.
+- Jika queue penuh, request tetap lanjut (fail-open) dan sistem menulis warning log.
+
+## Schema Ringkas (`audit_logs`)
+
+- `id` (BINARY(16), PK)
+- `request_id` (indexed)
+- `actor_user_id` (nullable, indexed)
+- `layer` (`api` / `service`)
+- `action` (indexed)
+- `method`, `path`, `status_code`, `success`
+- `ip`, `user_agent`
+- `message`
+- `metadata` (JSON)
+- `created_at`
+
+## Helper Pemakaian di Service
+
+Gunakan helper yang sudah ada di `AuthService`:
+
+```go
+s.logServiceAudit(ctx, "auth.reset_password.consume", userID, true, "password_reset_success", map[string]any{
+  "reason": "manual_reset",
+})
+```
+
+Untuk service lain, inject `*service.AuditLogService` lalu panggil:
+
+```go
+auditSvc.Log(ctx, service.AuditLogInput{
+  Layer: "service",
+  Action: "your.service.action",
+  ActorUserID: userID,
+  Success: true,
+  Message: "done",
+  Metadata: map[string]any{"key": "value"},
+})
+```
diff --git a/docs/auth-flow.md b/docs/auth-flow.md
new file mode 100644
index 0000000..55910db
--- /dev/null
+++ b/docs/auth-flow.md
@@ -0,0 +1,272 @@
+# Auth Flow
+
+This document describes the recommended authentication flows in Wucher. All API responses follow **JSON:API**.
+
+## 1) Email/Password Registration
+
+### 1.1 Register
+`POST /api/v1/auth/register`
+
+Notes:
+- The user role is assigned based on `AUTH_DEFAULT_ROLE`.
+- For production, you can disable this endpoint by setting `AUTH_DISABLE_REGISTER=true`.
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_register",
+    "attributes": {
+      "email": "user@example.com",
+      "password": "StrongP@ssw0rd",
+      "first_name": "John",
+      "last_name": "Doe",
+      "mobile_phone": ""
+    }
+  }
+}
+```
+
+Response: `201 Created` with user resource.
+
+### 1.2 Verify Email
+User receives a verification link in email:
+`GET /api/v1/auth/verify-email?token=...`
+
+Response: `200 OK` with `{ verified: true }`.
+
+### 1.3 Login
+`POST /api/v1/auth/login`
+
+If TOTP **is not enabled**, response is `200 OK` and cookies are set:
+- `wucher_at` (access)
+- `wucher_rt` (refresh)
+
+If TOTP **is enabled**, response is `202 Accepted` with `challenge_token`.
+
+### 1.4 Forgot Password
+`POST /api/v1/auth/forgot-password`
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_forgot_password",
+    "attributes": {
+      "email": "user@example.com"
+    }
+  }
+}
+```
+
+Response is always `200 OK` with a generic message:
+`If the account exists, a password reset link has been sent.`
+
+### 1.5 Reset Password
+`POST /api/v1/auth/reset-password`
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_reset_password",
+    "attributes": {
+      "token": "<token>",
+      "new_password": "StrongPassphrase123!",
+      "confirm_password": "StrongPassphrase123!"
+    }
+  }
+}
+```
+
+Success response: `200 OK` with message instructing the user to log in again.
+
+Invalid/expired/used token response: `400 Bad Request` with:
+`This reset link is invalid or expired.`
+
+### 1.6 Security PIN for Sensitive Actions
+
+Security PIN endpoints:
+- `POST /api/v1/auth/pin/setup`
+- `POST /api/v1/auth/pin/verify`
+- `POST /api/v1/auth/pin/change`
+- `POST /api/v1/auth/pin/forgot`
+- `POST /api/v1/auth/pin/reset`
+
+For `POST /api/v1/auth/pin/reset`:
+- If `method=password`, send the reset `token` from the email link plus `password`.
+- If `method=microsoft`, send only `reauth_token` from Microsoft re-auth.
+
+Sensitive actions require header:
+- `X-PIN-Verification-Token: <one-time-token>`
+
+`auth/pin/verify` menggunakan `action` berupa UUID opaque (transaction ID), bukan permission key seperti `user.delete`.
+
+Detailed flow + full payload examples:
+- See [docs/security-pin.md](security-pin.md)
+
+## 2) TOTP Setup (Enable 2FA)
+
+### 2.1 Setup
+`POST /api/v1/auth/totp/setup`
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_totp_setup",
+    "attributes": {
+      "user_id": "<uuid>",
+      "email": "user@example.com"
+    }
+  }
+}
+```
+
+Response: `200 OK` with `secret` and `otpauth_url`.
+> TOTP is **not** enabled yet (pending).
+
+### 2.2 Confirm
+`POST /api/v1/auth/totp/confirm`
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_totp_confirm",
+    "attributes": {
+      "user_id": "<uuid>",
+      "code": "123456"
+    }
+  }
+}
+```
+
+Response: `200 OK` and TOTP becomes **enabled**.
+
+## 3) TOTP Login (2FA)
+
+### 3.1 Login
+`POST /api/v1/auth/login`
+
+Response: `202 Accepted` with `challenge_token`.
+
+### 3.2 Verify
+`POST /api/v1/auth/totp/verify`
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_totp_verify",
+    "attributes": {
+      "challenge_token": "<token>",
+      "code": "123456"
+    }
+  }
+}
+```
+
+Response: `200 OK` and cookies are set.
+
+## 4) Microsoft Entra SSO
+
+### 4.1 Start Login
+`GET /api/v1/auth/microsoft/login`
+
+Response: `200 OK` with JSON:API body (`type: auth_microsoft_url`) containing `url` and `redirect_url`
+
+### 4.2 Callback
+Microsoft redirects to:
+`GET /api/v1/auth/microsoft/callback?code=...&state=...`
+
+Backend behavior:
+- If SSO mapping (`provider + provider_subject`) is linked to an existing user, login succeeds.
+- If mapping is missing, login is rejected (`401 SSO not linked`).
+- If mapping exists but user record is missing, login is rejected (`404 user not found`).
+- No auto-register on SSO callback.
+
+On success, backend sets cookies and may redirect to:
+`AUTH_SSO_SUCCESS_REDIRECT`
+
+### 4.3 Link SSO (authenticated user)
+`POST /api/v1/auth/sso/link`
+
+Body:
+```json
+{
+  "data": {
+    "type": "auth_sso_link",
+    "attributes": {
+      "provider": "microsoft",
+      "code": "<microsoft_authorization_code>"
+    }
+  }
+}
+```
+
+Rules:
+- 1 user only 1 SSO mapping.
+- Same SSO account cannot be linked to another user.
+
+### 4.4 Unlink SSO (authenticated user)
+`DELETE /api/v1/auth/sso/unlink`
+
+Body:
+```json
+{
+  "data": {
+    "type": "auth_sso_unlink",
+    "attributes": {
+      "provider": "microsoft"
+    }
+  }
+}
+```
+
+## 5) WebAuthn (Passkey)
+
+### 5.1 Register Credential (Authenticated User)
+1. `POST /api/v1/auth/webauthn/register/begin` (auth required)
+2. Browser executes `navigator.credentials.create(...)` using `public_key` from response
+3. `POST /api/v1/auth/webauthn/register/finish` with `challenge_token` + `credential`
+
+### 5.2 Login with WebAuthn
+1. `POST /api/v1/auth/webauthn/login/begin` with email
+2. Browser executes `navigator.credentials.get(...)` using `public_key` from response
+3. `POST /api/v1/auth/webauthn/login/finish` with `challenge_token` + `credential`
+4. On success, backend sets auth cookies.
+
+## 6) Refresh & Logout
+
+### Refresh
+`POST /api/v1/auth/refresh`
+
+Uses refresh cookie to issue new tokens.
+
+### Logout
+`POST /api/v1/auth/logout`
+
+Revokes refresh token and clears cookies.
+
+Frontend note:
+- Use `credentials: 'include'` on requests that depend on auth cookies.
+- Keep app logout local-only; do not redirect to Microsoft logout from this endpoint.
+- Microsoft front-channel logout is handled separately at `/api/v1/auth/microsoft/front-channel-logout` and is designed to work in an iframe.
+
+## Notes
+- Access token is stored in HttpOnly cookie: `AUTH_JWT_ACCESS_COOKIE`
+- Refresh token is stored in HttpOnly cookie: `AUTH_JWT_REFRESH_COOKIE`
+- Cookies are configured by `AUTH_JWT_COOKIE_*` envs
+- Microsoft SSO sessions use `SameSite=None; Secure` so front-channel iframe logout can receive cookies.
+- Access token TTL is controlled by `AUTH_JWT_ACCESS_TTL` (default `10m`)
+- Refresh token TTL is controlled by `AUTH_JWT_REFRESH_TTL` (default `1h`)
+- TOTP challenge tokens are stored server-side in MySQL-backed runtime storage for `AUTH_TOTP_CHALLENGE_TTL`
+- Password-reset tokens are stored in MySQL as SHA-256 hashes (raw token is never stored)
+- Password-reset tokens are single-use and expire by `AUTH_PASSWORD_RESET_TTL` (default 20m)
+- Forgot-password endpoint has per-IP and per-email throttling
+- Login (including SSO callback and post-TOTP token issue) bumps per-user session version, so a new login invalidates previous active sessions
+- Successful password reset revokes active sessions by bumping per-user session version
+- PIN can be blocked after max failed attempts; use `POST /api/v1/auth/pin/request-reset` (auth required) to request reset email for blocked accounts
+- WebAuthn challenge token is single-use, stored server-side, and expires by `AUTH_WEBAUTHN_CHALLENGE_TTL`.
+- WebAuthn credential verification enforces RP ID + RP origin checks from `AUTH_WEBAUTHN_RP_ID` and `AUTH_WEBAUTHN_RP_ORIGINS`.
diff --git a/docs/base-contact-roles-frontend-flow.md b/docs/base-contact-roles-frontend-flow.md
new file mode 100644
index 0000000..4a6fda5
--- /dev/null
+++ b/docs/base-contact-roles-frontend-flow.md
@@ -0,0 +1,146 @@
+# Base Contact Roles Frontend Flow (English)
+
+This document explains the frontend flow for contact assignment in the **Bases** module:
+- `responsible_flight_rescuer_contact_ids` (multi-contact)
+- `chief_physician_in_charge_contact_ids` (multi-contact)
+
+Contact source is always based on **contact id (`users.id`)**.
+
+## 1) Data Source for Contact Dropdowns
+
+Get contact candidates from contacts API:
+- `GET /api/v1/contacts/get-all?role=air_rescuer&limit=200`
+
+Minimum fields for FE:
+- `id` (resource id) => send this in base payload
+- `attributes.first_name`, `attributes.last_name`, `attributes.short_name` (display label)
+- optional: `attributes.is_active`
+
+UI suggestion:
+- Use 2 separate multi-select components:
+  - Responsible Flight Rescuer
+  - Chief Physician In Charge
+- The same person may exist in both lists if business rules allow it.
+
+## 2) Create Base Flow
+
+Endpoint:
+- `POST /api/v1/bases/create`
+
+Example payload:
+```json
+{
+  "data": {
+    "type": "base",
+    "attributes": {
+      "base": "Lude",
+      "base_category": "regular",
+      "responsible_flight_rescuer_contact_ids": [
+        "0196a111-1111-7abc-9def-111111111111",
+        "0196a222-2222-7abc-9def-222222222222"
+      ],
+      "chief_physician_in_charge_contact_ids": [
+        "0196a333-3333-7abc-9def-333333333333"
+      ]
+    }
+  }
+}
+```
+
+Backend behavior:
+- each id must be a valid UUID and exist in `users`
+- invalid UUID / missing user id => request fails (`4xx`)
+
+## 3) Update Base Flow
+
+Endpoint:
+- `PATCH /api/v1/bases/update/{uuid}`
+
+Payload to update assignment only:
+```json
+{
+  "data": {
+    "type": "base_update",
+    "attributes": {
+      "responsible_flight_rescuer_contact_ids": [
+        "0196a111-1111-7abc-9def-111111111111"
+      ],
+      "chief_physician_in_charge_contact_ids": []
+    }
+  }
+}
+```
+
+Important notes:
+- update uses **replace** semantics per base (not append)
+- always submit the final arrays from current UI state
+- send `[]` to clear all assignments for that role
+
+## 4) Load Base Detail into Edit Form
+
+Endpoint:
+- `GET /api/v1/bases/get/{uuid}`
+
+Response fields used by FE:
+- `data.attributes.responsible_flight_rescuer_contact_ids`
+- `data.attributes.chief_physician_in_charge_contact_ids`
+- `data.attributes.responsible_flight_rescuers` (id + first_name + last_name)
+- `data.attributes.chief_physicians_in_charge` (id + first_name + last_name)
+
+FE flow:
+1. Load base detail.
+2. Load contact options for dropdown.
+3. Map selected ids to option objects for selected state.
+4. Use detailed arrays to show human-readable names immediately.
+
+## 5) Show Base Roles in Contacts Module
+
+Contacts API now includes:
+- `attributes.base_roles` (array)
+
+Item format:
+```json
+{
+  "base_id": "0196b111-1111-7abc-9def-111111111111",
+  "base_name": "Lude",
+  "role_code": "responsible_flight_rescuer"
+}
+```
+
+Affected endpoints:
+- `GET /api/v1/contacts/get-all`
+- `GET /api/v1/contacts/get-all/dt`
+- `GET /api/v1/contacts/{user_id}`
+
+Suggested label mapping in UI:
+- `responsible_flight_rescuer` => `Responsible Flight Rescuer`
+- `chief_physician_in_charge` => `Chief Physician In Charge`
+
+## 6) UX Recommendations
+
+- In contact detail page, group `base_roles` by `base_name`.
+- In contact list, show compact chips, e.g.:
+  - `Lude (Responsible Flight Rescuer)`
+  - `Berlin (Chief Physician In Charge)`
+- For large lists, show only first N chips + `+X more`.
+
+## 7) Minimum Error Handling
+
+- If base submit fails because UUID validation fails:
+  - show general message: `Invalid contact assignment`.
+- If contact id no longer exists:
+  - show message: `Some contacts are no longer available, please refresh`.
+- After successful create/update:
+  - refresh base detail to keep assignment state synced with backend.
+
+## 8) Compatibility Note
+
+For backward compatibility, both ID arrays and detailed name arrays are returned:
+- `responsible_flight_rescuer_contact_ids`
+- `responsible_flight_rescuers`
+- `chief_physician_in_charge_contact_ids`
+- `chief_physicians_in_charge`
+
+Recommended FE usage:
+- Use `..._contact_ids` for submit payload.
+- Use detailed arrays for display names.
diff --git a/docs/collections/Wucher.json b/docs/collections/Wucher.json
new file mode 100644
index 0000000..eb93535
--- /dev/null
+++ b/docs/collections/Wucher.json
@@ -0,0 +1,980 @@
+{
+  "info": {
+    "name": "Wucher",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "item": [
+    {
+      "name": "Role",
+      "item": [
+        {
+          "name": "Create",
+          "request": {
+            "method": "POST",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/roles/create",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "roles",
+                "create"
+              ],
+              "query": [],
+              "variable": []
+            },
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"data\": {\n    \"attributes\": {\n      \"description\": \"Testing.\",\n      \"name\": \"role_test\"\n    },\n    \"type\": \"role\"\n  }\n}",
+              "options": {
+                "raw": {
+                  "language": "json"
+                }
+              }
+            }
+          }
+        },
+        {
+          "name": "Delete",
+          "request": {
+            "method": "DELETE",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/roles/delete/:uuid",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "roles",
+                "delete",
+                ":id"
+              ],
+              "query": [],
+              "variable": [
+                {
+                  "key": "id",
+                  "value": "019c31eb-5750-7c71-b6b9-042282c61bab"
+                }
+              ]
+            }
+          }
+        },
+        {
+          "name": "Get All DT",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/roles/get-all/dt?draw=1&length=5&start",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "roles",
+                "get-all",
+                "dt?draw=1&length=5&start"
+              ],
+              "query": [
+                {
+                  "key": "draw",
+                  "value": "1"
+                },
+                {
+                  "key": "length",
+                  "value": "5"
+                },
+                {
+                  "key": "start",
+                  "value": ""
+                },
+                {
+                  "key": "search",
+                  "value": "sta"
+                }
+              ],
+              "variable": []
+            }
+          }
+        },
+        {
+          "name": "Get All",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/roles/get-all",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "roles",
+                "get-all"
+              ],
+              "query": [],
+              "variable": []
+            }
+          }
+        },
+        {
+          "name": "Get By ID",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/roles/get/:uuid",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "roles",
+                "get",
+                ":id"
+              ],
+              "query": [],
+              "variable": [
+                {
+                  "key": "id",
+                  "value": "019c31eb-5750-7c71-b6b9-042282c61bab"
+                }
+              ]
+            }
+          }
+        },
+        {
+          "name": "Update",
+          "request": {
+            "method": "PATCH",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/roles/update/:uuid",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "roles",
+                "update",
+                ":id"
+              ],
+              "query": [],
+              "variable": [
+                {
+                  "key": "id",
+                  "value": "019c31eb-5750-7c71-b6b9-042282c61bab"
+                }
+              ]
+            },
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"data\": {\n    \"attributes\": {\n      \"description\": \"Testing update.\",\n      \"name\": \"test_role\"\n    },\n    \"id\": \"019c31eb-5750-7c71-b6b9-042282c61bab\",\n    \"type\": \"role\"\n  }\n}",
+              "options": {
+                "raw": {
+                  "language": "json"
+                }
+              }
+            }
+          }
+        },
+        {
+          "name": "Permission",
+          "item": [
+            {
+              "name": "Assign",
+              "request": {
+                "method": "POST",
+                "header": [],
+                "auth": {
+                  "type": "noauth"
+                },
+                "description": "",
+                "url": {
+                  "raw": "{{baseUrl}}/api/v1/roles/:uuid/permissions/assign-bulk",
+                  "protocol": "",
+                  "host": [
+                    "{{baseUrl}}"
+                  ],
+                  "path": [
+                    "api",
+                    "v1",
+                    "roles",
+                    ":uuid",
+                    "permissions",
+                    "assign-bulk"
+                  ],
+                  "query": [],
+                  "variable": [
+                    {
+                      "key": "uuid",
+                      "value": ""
+                    }
+                  ]
+                },
+                "body": {
+                  "mode": "raw",
+                  "raw": "{\n  \"data\": {\n    \"type\": \"role_assign_permission_bulk\",\n    \"attributes\": {\n      \"permission_ids\": [\n        \"019c79bd-c7a5-703d-8b7d-cd935e7e5316\",\n        \"019c79bd-c7a5-720e-ad50-989d8848e37c\"\n      ]\n    }\n  }\n}",
+                  "options": {
+                    "raw": {
+                      "language": "json"
+                    }
+                  }
+                }
+              }
+            },
+            {
+              "name": "Get All Permission",
+              "request": {
+                "method": "GET",
+                "header": [],
+                "auth": {
+                  "type": "noauth"
+                },
+                "description": "",
+                "url": {
+                  "raw": "{{baseUrl}}/api/v1/roles/permissions/get-all",
+                  "protocol": "",
+                  "host": [
+                    "{{baseUrl}}"
+                  ],
+                  "path": [
+                    "api",
+                    "v1",
+                    "roles",
+                    "permissions",
+                    "get-all"
+                  ],
+                  "query": [],
+                  "variable": []
+                }
+              }
+            },
+            {
+              "name": "Permission of Role",
+              "request": {
+                "method": "GET",
+                "header": [],
+                "auth": {
+                  "type": "noauth"
+                },
+                "description": "",
+                "url": {
+                  "raw": "{{baseUrl}}/api/v1/roles/:uuid/permissions",
+                  "protocol": "",
+                  "host": [
+                    "{{baseUrl}}"
+                  ],
+                  "path": [
+                    "api",
+                    "v1",
+                    "roles",
+                    ":uuid",
+                    "permissions"
+                  ],
+                  "query": [],
+                  "variable": [
+                    {
+                      "key": "uuid",
+                      "value": "019c30e6-1b8a-7714-898a-6e954e3dad33"
+                    }
+                  ]
+                }
+              }
+            },
+            {
+              "name": "Remove Permission",
+              "request": {
+                "method": "POST",
+                "header": [],
+                "auth": {
+                  "type": "noauth"
+                },
+                "description": "",
+                "url": {
+                  "raw": "{{baseUrl}}/api/v1/roles/:uuid/permissions/remove-bulk",
+                  "protocol": "",
+                  "host": [
+                    "{{baseUrl}}"
+                  ],
+                  "path": [
+                    "api",
+                    "v1",
+                    "roles",
+                    ":uuid",
+                    "permissions",
+                    "remove-bulk"
+                  ],
+                  "query": [],
+                  "variable": [
+                    {
+                      "key": "uuid",
+                      "value": "019c30e6-1b8a-7714-898a-6e954e3dad33"
+                    }
+                  ]
+                },
+                "body": {
+                  "mode": "raw",
+                  "raw": "{\n  \"data\": {\n    \"type\": \"role_remove_permission_bulk\",\n    \"attributes\": {\n      \"permission_ids\": [\n        \"019c79bd-c7a5-7974-ba89-69d52f0f3712\",\n        \"019c79bd-c7a5-7339-add2-5a1c900cf1c3\"\n      ]\n    }\n  }\n}",
+                  "options": {
+                    "raw": {
+                      "language": "json"
+                    }
+                  }
+                }
+              }
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "User",
+      "item": [
+        {
+          "name": "Create",
+          "request": {
+            "method": "POST",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/users/create",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "users",
+                "create"
+              ],
+              "query": [],
+              "variable": []
+            },
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"data\": {\n    \"type\": \"user\",\n    \"attributes\": {\n      \"email\": \"marcomelandri808@gmail.com\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"mobile_phone\": \"+628123456789\",\n      \"role_id\": \"019c30e6-1b8a-7714-898a-6e954e3dad33\"\n    }\n  }\n}",
+              "options": {
+                "raw": {
+                  "language": "json"
+                }
+              }
+            }
+          }
+        },
+        {
+          "name": "Delete",
+          "request": {
+            "method": "DELETE",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/users/delete/:uuid",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "users",
+                "delete",
+                ":uuid"
+              ],
+              "query": [],
+              "variable": [
+                {
+                  "key": "uuid",
+                  "value": "019c79da-8c32-785c-b547-beee3b321e9b"
+                }
+              ]
+            }
+          }
+        },
+        {
+          "name": "Get All DT",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/users/get-all/dt",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "users",
+                "get-all",
+                "dt"
+              ],
+              "query": [],
+              "variable": []
+            }
+          }
+        },
+        {
+          "name": "Get All",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/users/get-all",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "users",
+                "get-all"
+              ],
+              "query": [],
+              "variable": []
+            }
+          }
+        },
+        {
+          "name": "Get By UUID",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/users/get/:uuid",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "users",
+                "get",
+                ":uuid"
+              ],
+              "query": [],
+              "variable": [
+                {
+                  "key": "uuid",
+                  "value": "019c7940-c4c2-7fa4-ae0b-4eeb9e75295b"
+                }
+              ]
+            }
+          }
+        },
+        {
+          "name": "Update",
+          "request": {
+            "method": "PATCH",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/users/update/:uuid",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "users",
+                "update",
+                ":uuid"
+              ],
+              "query": [],
+              "variable": [
+                {
+                  "key": "uuid",
+                  "value": "019c7940-c4c2-7fa4-ae0b-4eeb9e75295b"
+                }
+              ]
+            },
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"data\": {\n    \"type\": \"user\",\n    \"id\": \"019c7940-c4c2-7fa4-ae0b-4eeb9e75295b\",\n    \"attributes\": {\n      \"first_name\": \"Johnny\",\n      \"last_name\": \"Doe\",\n      \"mobile_phone\": \"+628123456700\",\n      \"role_id\": \"019c30e6-1b8a-7714-898a-6e954e3dad33\"\n    }\n  }\n}\n",
+              "options": {
+                "raw": {
+                  "language": "json"
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    {
+      "name": "Auth",
+      "item": [
+        {
+          "name": "Auth Me",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/auth/me",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "auth",
+                "me"
+              ],
+              "query": [],
+              "variable": []
+            }
+          }
+        },
+        {
+          "name": "Invite",
+          "request": {
+            "method": "POST",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/auth/invite",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "auth",
+                "invite"
+              ],
+              "query": [],
+              "variable": []
+            },
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"data\": {\n    \"type\": \"auth_invite\",\n    \"attributes\": {\n      \"email\": \"marcomelandri808@gmail.com\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"mobile_phone\": \"+628123456789\",\n      \"role_id\": \"019c30e6-1b8a-7714-898a-6e954e3dad33\"\n    }\n  }\n}\n",
+              "options": {
+                "raw": {
+                  "language": "json"
+                }
+              }
+            }
+          }
+        },
+        {
+          "name": "Login",
+          "request": {
+            "method": "POST",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/auth/login",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "auth",
+                "login"
+              ],
+              "query": [],
+              "variable": []
+            },
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"data\": {\n    \"type\": \"auth_login\",\n    \"attributes\": {\n      \"email\": \"marcomelandri808@gmail.com\",\n      \"password\": \"StrongP@ssw0rd!\"\n    }\n  }\n}",
+              "options": {
+                "raw": {
+                  "language": "json"
+                }
+              }
+            }
+          }
+        },
+        {
+          "name": "Logout",
+          "request": {
+            "method": "POST",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/auth/logout",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "auth",
+                "logout"
+              ],
+              "query": [],
+              "variable": []
+            }
+          }
+        },
+        {
+          "name": "Refresh Token",
+          "request": {
+            "method": "POST",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/auth/refresh",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "auth",
+                "refresh"
+              ],
+              "query": [],
+              "variable": []
+            }
+          }
+        },
+        {
+          "name": "Register",
+          "request": {
+            "method": "POST",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/auth/register",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "auth",
+                "register"
+              ],
+              "query": [],
+              "variable": []
+            },
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"data\": {\n    \"type\": \"auth_register\",\n    \"attributes\": {\n      \"email\": \"innovatexsh@gmail.com\",\n      \"password\": \"securePass123\",\n      \"first_name\": \"John\",\n      \"last_name\": \"Doe\",\n      \"mobile_phone\": \"087782553442\"\n    }\n  }\n}",
+              "options": {
+                "raw": {
+                  "language": "json"
+                }
+              }
+            }
+          }
+        },
+        {
+          "name": "Set New Password",
+          "request": {
+            "method": "POST",
+            "header": [],
+            "auth": {
+              "type": "noauth"
+            },
+            "description": "",
+            "url": {
+              "raw": "{{baseUrl}}/api/v1/auth/set-password",
+              "protocol": "",
+              "host": [
+                "{{baseUrl}}"
+              ],
+              "path": [
+                "api",
+                "v1",
+                "auth",
+                "set-password"
+              ],
+              "query": [],
+              "variable": []
+            },
+            "body": {
+              "mode": "raw",
+              "raw": "{\n  \"data\": {\n    \"type\": \"auth_set_password\",\n    \"attributes\": {\n      \"token\": \"--TpCbfl1JEpEJq1jr2l1XeFggiAN7Z2k23pwMVrxac\",\n      \"password\": \"StrongP@ssw0rd!\"\n    }\n  }\n}\n",
+              "options": {
+                "raw": {
+                  "language": "json"
+                }
+              }
+            }
+          }
+        },
+        {
+          "name": "SSO",
+          "item": [
+            {
+              "name": "MS Login",
+              "request": {
+                "method": "GET",
+                "header": [],
+                "auth": {
+                  "type": "noauth"
+                },
+                "description": "",
+                "url": {
+                  "raw": "{{baseUrl}}/api/v1/auth/microsoft/login",
+                  "protocol": "",
+                  "host": [
+                    "{{baseUrl}}"
+                  ],
+                  "path": [
+                    "api",
+                    "v1",
+                    "auth",
+                    "microsoft",
+                    "login"
+                  ],
+                  "query": [],
+                  "variable": []
+                }
+              }
+            }
+          ]
+        },
+        {
+          "name": "TOTP",
+          "item": [
+            {
+              "name": "TOTP Disable",
+              "request": {
+                "method": "POST",
+                "header": [],
+                "auth": {
+                  "type": "noauth"
+                },
+                "description": "",
+                "url": {
+                  "raw": "{{baseUrl}}/api/v1/auth/totp/disable",
+                  "protocol": "",
+                  "host": [
+                    "{{baseUrl}}"
+                  ],
+                  "path": [
+                    "api",
+                    "v1",
+                    "auth",
+                    "totp",
+                    "disable"
+                  ],
+                  "query": [],
+                  "variable": []
+                },
+                "body": {
+                  "mode": "raw",
+                  "raw": "{\n  \"data\": {\n    \"attributes\": {\n      \"user_id\": \"019c2e21-d880-7b9a-89ac-3d3d8593502f\"\n    },\n    \"type\": \"auth_totp_disable\"\n  }\n}",
+                  "options": {
+                    "raw": {
+                      "language": "json"
+                    }
+                  }
+                }
+              }
+            },
+            {
+              "name": "TOTP Setup",
+              "request": {
+                "method": "POST",
+                "header": [],
+                "auth": {
+                  "type": "noauth"
+                },
+                "description": "",
+                "url": {
+                  "raw": "{{baseUrl}}/api/v1/auth/totp/setup",
+                  "protocol": "",
+                  "host": [
+                    "{{baseUrl}}"
+                  ],
+                  "path": [
+                    "api",
+                    "v1",
+                    "auth",
+                    "totp",
+                    "setup"
+                  ],
+                  "query": [],
+                  "variable": []
+                },
+                "body": {
+                  "mode": "raw",
+                  "raw": "{\n  \"data\": {\n    \"attributes\": {\n      \"email\": \"innovatexsh@gmail.com\",\n      \"user_id\": \"019c2e21-d880-7b9a-89ac-3d3d8593502f\"\n    },\n    \"type\": \"auth_totp_setup\"\n  }\n}",
+                  "options": {
+                    "raw": {
+                      "language": "json"
+                    }
+                  }
+                }
+              }
+            },
+            {
+              "name": "TOTP Verify Login",
+              "request": {
+                "method": "POST",
+                "header": [],
+                "auth": {
+                  "type": "noauth"
+                },
+                "description": "",
+                "url": {
+                  "raw": "{{baseUrl}}/api/v1/auth/totp/verify",
+                  "protocol": "",
+                  "host": [
+                    "{{baseUrl}}"
+                  ],
+                  "path": [
+                    "api",
+                    "v1",
+                    "auth",
+                    "totp",
+                    "verify"
+                  ],
+                  "query": [],
+                  "variable": []
+                },
+                "body": {
+                  "mode": "raw",
+                  "raw": "{\n  \"data\": {\n    \"attributes\": {\n      \"challenge_token\": \"Z_2A0lm5IekOiIBPbpiJzpuevFYW6oxEIgdMZjPkcpw\",\n      \"code\": \"568754\"\n    },\n    \"type\": \"auth_totp_verify\"\n  }\n}",
+                  "options": {
+                    "raw": {
+                      "language": "json"
+                    }
+                  }
+                }
+              }
+            },
+            {
+              "name": "TOTP Verify",
+              "request": {
+                "method": "POST",
+                "header": [],
+                "auth": {
+                  "type": "noauth"
+                },
+                "description": "",
+                "url": {
+                  "raw": "{{baseUrl}}/api/v1/auth/totp/confirm",
+                  "protocol": "",
+                  "host": [
+                    "{{baseUrl}}"
+                  ],
+                  "path": [
+                    "api",
+                    "v1",
+                    "auth",
+                    "totp",
+                    "confirm"
+                  ],
+                  "query": [],
+                  "variable": []
+                },
+                "body": {
+                  "mode": "raw",
+                  "raw": "{\n  \"data\": {\n    \"attributes\": {\n      \"code\": \"898427\",\n      \"user_id\": \"019c2e21-d880-7b9a-89ac-3d3d8593502f\"\n    },\n    \"type\": \"auth_totp_confirm\"\n  }\n}",
+                  "options": {
+                    "raw": {
+                      "language": "json"
+                    }
+                  }
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "variable": [
+    {
+      "key": "baseUrl",
+      "value": "",
+      "type": "default"
+    }
+  ]
+}
diff --git a/docs/contact-create-flow.md b/docs/contact-create-flow.md
new file mode 100644
index 0000000..cdc28f3
--- /dev/null
+++ b/docs/contact-create-flow.md
@@ -0,0 +1,359 @@
+# Contact Create Flow (Frontend Guide)
+
+This document explains the full flow to create a contact, send an automatic invite email, and let the invited user set their first password.
+
+## 1) Prerequisites
+
+1. Admin user is already logged in and has an `access token`.
+2. Admin user has already configured a Security PIN.
+3. Frontend knows the target `role_id` (fetch from `GET /api/v1/roles/get-all`).
+
+## 2) Endpoints Used
+
+1. `POST /api/v1/auth/pin/verify` to get a PIN `action_token`.
+2. `POST /api/v1/contacts/create` to create the contact (auto invite enabled).
+3. `POST /api/v1/auth/set-password` to set the first password from invite token.
+
+## 3) Detailed Flow
+
+### Step A - Verify PIN for contact create action
+
+Action ID for contact create:
+- `2a59e8b4-5a72-4be3-b8fc-4f49941181c3`
+
+Request:
+
+```json
+{
+  "data": {
+    "type": "auth_pin_verify",
+    "attributes": {
+      "pin": "123456",
+      "action": "2a59e8b4-5a72-4be3-b8fc-4f49941181c3"
+    }
+  }
+}
+```
+
+Success response:
+
+```json
+{
+  "data": {
+    "type": "auth_pin_verify",
+    "attributes": {
+      "verified": true,
+      "action_token": "<PIN_ACTION_TOKEN>",
+      "action_token_ttl_ms": 300000
+    }
+  }
+}
+```
+
+Store `action_token`, then pass it to contact create in header:
+- `X-PIN-Verification-Token: <PIN_ACTION_TOKEN>`
+
+### Step B - Create Contact (auto invite)
+
+Endpoint:
+- `POST /api/v1/contacts/create`
+
+Required headers:
+- `Authorization: Bearer <ACCESS_TOKEN>`
+- `X-PIN-Verification-Token: <PIN_ACTION_TOKEN>`
+- `Content-Type: application/json`
+
+Minimum required body:
+- `data.type = contact_<role>_create`
+- `attributes.role_id`
+- `attributes.email`
+- `attributes.first_name`
+- `attributes.last_name`
+
+Allowed create types:
+- `contact_pilot_create`
+- `contact_doctor_create`
+- `contact_air_rescuer_create`
+- `contact_technician_create`
+- `contact_flight_assistant_create`
+- `contact_staff_create`
+
+Rules:
+- `data.type` must match the role resolved from `attributes.role_id`.
+- Only one role-specific profile object is allowed, and it must match `data.type`.
+
+> Note: backend now **automatically sends an invite email** after successful contact creation.
+
+If PIN token is missing/invalid, API returns `202` with PIN verification required error.
+
+### Step C - User clicks invite link from email
+
+Invite email contains a link like:
+- `https://frontend-domain/set-password?token=<INVITE_TOKEN>`
+
+This token already carries user identity (email + user id claims) and is single-use.
+
+### Step D - Frontend submits set password
+
+Endpoint:
+- `POST /api/v1/auth/set-password`
+
+Request:
+
+```json
+{
+  "data": {
+    "type": "auth_set_password",
+    "attributes": {
+      "token": "<INVITE_TOKEN>",
+      "password": "StrongP@ssw0rd123"
+    }
+  }
+}
+```
+
+If successful, user can directly log in using `POST /api/v1/auth/login`.
+
+## 4) Contact Create Payloads by Role
+
+## Pilot
+
+```json
+{
+  "data": {
+    "type": "contact_pilot_create",
+    "attributes": {
+      "role_id": "<ROLE_ID_PILOT>",
+      "email": "pilot1@example.com",
+      "username": "pilot1",
+      "first_name": "Marco",
+      "last_name": "Melandri",
+      "mobile_phone": "+628123456789",
+      "timezone": "Asia/Jakarta",
+      "is_active": true,
+      "pilot": {
+        "pilot_category": "regular",
+        "short_name": "Marco",
+        "license_no": "PIL-001",
+        "license_issued_at": "2025-01-01T00:00:00Z",
+        "license_expired_at": "2028-01-01T00:00:00Z",
+        "technician_license_no": "TECH-001",
+        "has_ifr_qualification": true,
+        "is_chief_pilot": false,
+        "is_dul": false,
+        "total_flight_minutes": 12000,
+        "responsible_pilot_minutes": 5000,
+        "second_pilot_minutes": 3000,
+        "double_command_minutes": 1000,
+        "flight_instructor_minutes": 500,
+        "night_flight_minutes": 1200,
+        "ifr_flight_minutes": 800,
+        "location": "Jakarta",
+        "postcode": "12950",
+        "street_line": "Jl. Sudirman No. 1",
+        "weight_kg": 72.5,
+        "photo_file_id": "/uploads/contacts/pilot1.jpg"
+      }
+    }
+  }
+}
+```
+
+## Doctor
+
+```json
+{
+  "data": {
+    "type": "contact_doctor_create",
+    "attributes": {
+      "role_id": "<ROLE_ID_DOCTOR>",
+      "email": "doctor1@example.com",
+      "username": "doctor1",
+      "first_name": "Alicia",
+      "last_name": "Pratama",
+      "mobile_phone": "+628123450001",
+      "timezone": "Asia/Jakarta",
+      "is_active": true,
+      "doctor": {
+        "short_name": "Dr. Alicia",
+        "medical_license_no": "MED-DOCTOR-001",
+        "license_issued_at": "2024-01-01T00:00:00Z",
+        "license_expired_at": "2029-01-01T00:00:00Z",
+        "specialization": "Emergency Medicine",
+        "sub_specialization": "Trauma",
+        "is_chief_physician": false,
+        "location": "Jakarta",
+        "postcode": "12950",
+        "street_line": "Jl. Jenderal Sudirman No. 10",
+        "photo_file_id": "/uploads/contacts/doctor1.jpg"
+      }
+    }
+  }
+}
+```
+
+## Air Rescuer
+
+```json
+{
+  "data": {
+    "type": "contact_air_rescuer_create",
+    "attributes": {
+      "role_id": "<ROLE_ID_AIR_RESCUER>",
+      "email": "airrescuer1@example.com",
+      "username": "airrescuer1",
+      "first_name": "Raka",
+      "last_name": "Wijaya",
+      "mobile_phone": "+628123450002",
+      "timezone": "Asia/Jakarta",
+      "is_active": true,
+      "air_rescuer": {
+        "short_name": "Raka",
+        "is_chief_physician_in_charge": false,
+        "responsible_flight_rescuer": false,
+        "location": "Bandung",
+        "postcode": "40115",
+        "street_line": "Jl. Merdeka No. 20",
+        "photo_file_id": "/uploads/contacts/airrescuer1.jpg"
+      }
+    }
+  }
+}
+```
+
+## Technician
+
+```json
+{
+  "data": {
+    "type": "contact_technician_create",
+    "attributes": {
+      "role_id": "<ROLE_ID_TECHNICIAN>",
+      "email": "tech1@example.com",
+      "username": "tech1",
+      "first_name": "Bima",
+      "last_name": "Nugraha",
+      "mobile_phone": "+628123450003",
+      "timezone": "Asia/Jakarta",
+      "is_active": true,
+      "technician": {
+        "short_name": "Bima",
+        "license_no": "TECH-7788",
+        "is_chief_technician": false,
+        "is_responsible_complaints": true,
+        "location": "Surabaya",
+        "postcode": "60231",
+        "street_line": "Jl. Diponegoro No. 30",
+        "photo_file_id": "/uploads/contacts/tech1.jpg"
+      }
+    }
+  }
+}
+```
+
+## Flight Assistant
+
+```json
+{
+  "data": {
+    "type": "contact_flight_assistant_create",
+    "attributes": {
+      "role_id": "<ROLE_ID_FLIGHT_ASSISTANT>",
+      "email": "fa1@example.com",
+      "username": "fa1",
+      "first_name": "Nadia",
+      "last_name": "Putri",
+      "mobile_phone": "+628123450004",
+      "timezone": "Asia/Jakarta",
+      "is_active": true,
+      "flight_assistant": {
+        "short_name": "Nadia",
+        "location": "Yogyakarta",
+        "postcode": "55281",
+        "street_line": "Jl. Kaliurang No. 15",
+        "photo_file_id": "/uploads/contacts/fa1.jpg"
+      }
+    }
+  }
+}
+```
+
+## Staff
+
+```json
+{
+  "data": {
+    "type": "contact_staff_create",
+    "attributes": {
+      "role_id": "<ROLE_ID_STAFF>",
+      "email": "staff1@example.com",
+      "username": "staff1",
+      "first_name": "Dina",
+      "last_name": "Maharani",
+      "mobile_phone": "+628123450005",
+      "timezone": "Asia/Jakarta",
+      "is_active": true,
+      "staff": {
+        "short_name": "Dina",
+        "role_label": "Operations Staff",
+        "location": "Semarang",
+        "postcode": "50132",
+        "street_line": "Jl. Pandanaran No. 8",
+        "photo_file_id": "/uploads/contacts/staff1.jpg"
+      }
+    }
+  }
+}
+```
+
+## 5) Example Create Contact Response
+
+```json
+{
+  "data": {
+    "type": "contact",
+    "id": "019ce67e-9289-731d-ae4c-0156902aabbc",
+    "attributes": {
+      "role_code": "doctor",
+      "role_name": "doctor",
+      "email": "doctor1@example.com",
+      "first_name": "Alicia",
+      "last_name": "Pratama",
+      "is_active": true,
+      "doctor": {
+        "short_name": "Dr. Alicia",
+        "medical_license_no": "MED-DOCTOR-001"
+      },
+      "invite_sent": true,
+      "invite_error": ""
+    }
+  }
+}
+```
+
+If invite sending fails (for example SES/SQS config issue):
+- contact create is still successful,
+- `invite_sent = false`,
+- `invite_error` contains the error message.
+
+## 6) Error Cases Frontend Should Handle
+
+1. `202 PIN verification required` on contact create:
+   - call `/auth/pin/verify` again (Step A), then retry create with `X-PIN-Verification-Token`.
+2. `422 Validation error`:
+   - check payload fields (invalid role_id, invalid email, etc).
+3. `400` on create:
+   - typically business/constraint conflict.
+4. `400` on set-password:
+   - token invalid/expired/used or password does not meet rules.
+
+## 7) Frontend Integration Summary
+
+1. Admin logs in.
+2. Fetch `role_id` from roles list.
+3. Verify PIN (`/auth/pin/verify` with contact-create action ID).
+4. Create contact (`/contacts/create` + `X-PIN-Verification-Token`).
+5. Wait for invited user to open invite email.
+6. Set-password page reads `token` from query param.
+7. Submit `/auth/set-password` with `{ token, password }`.
+8. Redirect user to login page.
diff --git a/docs/contacts_module.md b/docs/contacts_module.md
new file mode 100644
index 0000000..bf52f2a
--- /dev/null
+++ b/docs/contacts_module.md
@@ -0,0 +1,129 @@
+# Contacts Module (HEMS)
+
+## Endpoint listing
+- `GET /api/v1/contacts?role=pilot`
+- `GET /api/v1/contacts?role=pilot&pilot_category=freelance`
+- `GET /api/v1/contacts?role=pilot&pilot_category=dry_lease`
+- `GET /api/v1/contacts?role=doctor`
+- `GET /api/v1/contacts?role=air_rescuer`
+- `GET /api/v1/contacts?role=technician`
+- `GET /api/v1/contacts?role=flight_assistant`
+- `GET /api/v1/contacts?role=staff`
+
+## Sensitive action flow (PIN)
+1. Client memanggil endpoint sensitif.
+2. API balas `202` dan memberi tahu `action` PIN yang dibutuhkan.
+3. Client verifikasi PIN ke `/api/v1/auth/pin/verify`.
+4. Backend mengembalikan token verifikasi singkat.
+5. Client kirim ulang request sensitif dengan header `X-PIN-Verification-Token`.
+
+## Contoh payload
+
+### 1) Create pilot
+```json
+{
+  "data": {
+    "type": "contact_pilot_create",
+    "attributes": {
+      "role_id": "<ROLE_ID_PILOT>",
+      "email": "pilot1@hems.local",
+      "username": "pilot1",
+      "first_name": "Marco",
+      "last_name": "Pilot",
+      "mobile_phone": "+62811111111",
+      "timezone": "Asia/Jakarta",
+      "pilot": {
+        "pilot_category": "freelance",
+        "short_name": "M. Pilot",
+        "license_no": "LIC-P-1001",
+        "has_ifr_qualification": true,
+        "total_flight_minutes": 12500,
+        "location": "Jakarta"
+      }
+    }
+  }
+}
+```
+
+### 2) Update doctor
+```json
+{
+  "data": {
+    "type": "contact_doctor_update",
+    "attributes": {
+      "is_active": true,
+      "doctor": {
+        "short_name": "dr. Ana",
+        "medical_license_no": "DOC-7788",
+        "specialization": "Anesthesiology",
+        "is_chief_physician": false
+      }
+    }
+  }
+}
+```
+
+Rule:
+- `data.type` wajib mengikuti role, mis. `contact_pilot_create`, `contact_air_rescuer_create`, `contact_staff_update`.
+- Hanya satu object profile role yang boleh dikirim, dan harus sesuai dengan `data.type`.
+
+### 3) PIN verify sebelum aksi sensitif
+```json
+{
+  "data": {
+    "type": "auth_pin_verify",
+    "attributes": {
+      "pin": "123456",
+      "action": "31f8bb88-a95f-43be-8fd8-129e1355d6a5"
+    }
+  }
+}
+```
+
+### 4) Response `202` saat PIN dibutuhkan
+```json
+{
+  "data": {
+    "type": "pin_verification_required",
+    "attributes": {
+      "required": true,
+      "action": "31f8bb88-a95f-43be-8fd8-129e1355d6a5",
+      "method": "pin",
+      "status": 202
+    }
+  }
+}
+```
+
+### 5) List response ringkas
+```json
+{
+  "data": {
+    "type": "contacts",
+    "attributes": {
+      "items": [
+        {
+          "id": "0195f43e-5030-7d2a-8b8a-020063f5ab03",
+          "role_code": "pilot",
+          "role_name": "pilot",
+          "pilot_category": "dry_lease",
+          "username": "pilot_dl_1",
+          "email": "pilot.dl1@hems.local",
+          "first_name": "Rama",
+          "last_name": "Wijaya",
+          "short_name": "R. Wijaya",
+          "license_no": "LIC-P-9988",
+          "location": "Surabaya",
+          "mobile_phone": "+62822222222",
+          "is_active": true
+        }
+      ],
+      "meta": {
+        "total": 1,
+        "limit": 20,
+        "offset": 0
+      }
+    }
+  }
+}
+```
diff --git a/docs/data-migration-wiki-ckeditor.html b/docs/data-migration-wiki-ckeditor.html
new file mode 100644
index 0000000..05a7947
--- /dev/null
+++ b/docs/data-migration-wiki-ckeditor.html
@@ -0,0 +1,187 @@
+<h1>Data Migration Wiki</h1>
+<p>
+  This page is the living technical document for migration scope, decisions, limitations, and open tasks.
+  Update it for every migration wave.
+</p>
+
+<h2>Scope</h2>
+<ul>
+  <li>Database schema migrations in <code>migrations/</code>.</li>
+  <li>Data migration SQL (legacy to current domain model).</li>
+  <li>Non-DB migration concerns: binary files (PDF/images), queue backlog, manual user actions.</li>
+</ul>
+
+<h2>Source of Truth</h2>
+<ul>
+  <li>Versioned DB migrations: <code>migrations/*.sql</code>.</li>
+  <li>Legacy helicopter import flow:
+    <ul>
+      <li><code>migrations/goose/20260414_helicopter_import_staging.sql</code></li>
+      <li><code>migrations/goose/20260415_helicopter_import_apply.sql</code></li>
+      <li><code>migrations/scripts/migration_helicopter.sql</code> (deprecated helper note)</li>
+    </ul>
+  </li>
+  <li>Queue migration notes: <code>docs/queue-sqs-migration.md</code>.</li>
+  <li>File manager APIs and attachment model:
+    <ul>
+      <li><code>docs/file-manager-upload.md</code></li>
+      <li><code>docs/file-manager-attachment.md</code></li>
+    </ul>
+  </li>
+</ul>
+
+<h2>Implemented Data Migrations</h2>
+<ol>
+  <li>
+    <strong>20260326_move_responsible_flight_rescuer_to_air_rescuer_profiles.sql</strong>
+    <ul>
+      <li>Copies <code>pilot_profiles.responsible_flight_rescuer</code> into <code>air_rescuer_profiles.responsible_flight_rescuer</code>.</li>
+      <li>Drops old column from <code>pilot_profiles</code>.</li>
+    </ul>
+  </li>
+  <li>
+    <strong>20260403_file_manager_file_lifecycle_phase1.sql</strong>
+    <ul>
+      <li>Normalizes legacy file lifecycle states (<code>pending/uploading</code>) into newer states (<code>validated/processing</code>).</li>
+      <li>Carries <code>upload_error</code> into <code>failure_reason</code>.</li>
+    </ul>
+  </li>
+  <li>
+    <strong>20260415_helicopter_import_apply.sql</strong>
+    <ul>
+      <li>Imports rows from <code>helicopter_old_import</code> into <code>helicopters</code>.</li>
+      <li>Maintains old-to-new ID mapping via <code>helicopter_old_id_map</code>.</li>
+      <li>Explicitly non-reversible (<code>Down</code> keeps data as audit trail).</li>
+    </ul>
+  </li>
+</ol>
+
+<h2>Known Migration Decisions and Gaps</h2>
+
+<h3>Confirmed "Will Not Migrate" (Current Decision)</h3>
+<ol>
+  <li>
+    Legacy helicopter columns intentionally ignored:
+    <ul>
+      <li><code>counter</code></li>
+      <li><code>service</code></li>
+      <li><code>disabled</code></li>
+      <li><code>visible</code></li>
+    </ul>
+    <p>Decision is documented in <code>migrations/scripts/migration_helicopter.sql</code>.</p>
+  </li>
+</ol>
+
+<h3>Confirmed "Not Migrated Yet" (Open)</h3>
+<ol>
+  <li>
+    Legacy SQS queue backlog
+    <ul>
+      <li>Current worker does not consume old SQS backlog.</li>
+      <li>Required action: drain/discard SQS backlog before/at cutover.</li>
+      <li>Source: <code>docs/queue-sqs-migration.md</code>.</li>
+    </ul>
+  </li>
+  <li>
+    Binary files (PDF/images) into new file manager storage
+    <ul>
+      <li>Current migrations create file manager tables and attachment relations, but no SQL migration imports binary objects or bulk-inserts legacy metadata into <code>file_files</code>/<code>attachments</code>.</li>
+      <li>This means legacy documents may need manual re-upload unless a dedicated import job is created.</li>
+    </ul>
+  </li>
+  <li>
+    Legacy <code>photo_file_id</code> references in contact profile tables
+    <ul>
+      <li>Contact profile schemas still include <code>photo_file_id</code> string columns.</li>
+      <li>No migration currently maps these into <code>attachments</code> + <code>image_attachment_id</code>/<code>foto_attachment_id</code>.</li>
+    </ul>
+  </li>
+</ol>
+
+<h2>Manual Actions Required at Cutover</h2>
+<ol>
+  <li>Validate which legacy PDFs/images must remain accessible on day 1.</li>
+  <li>For files without automated import, perform manual re-upload via file manager flow.</li>
+  <li>Re-link uploaded files to business references (attachments) and to entity-level attachment columns where relevant.</li>
+  <li>Obtain client sign-off for any files intentionally left unmigrated.</li>
+</ol>
+
+<h2>Migration TODO Register</h2>
+<table border="1" cellpadding="6" cellspacing="0">
+  <thead>
+    <tr>
+      <th>ID</th>
+      <th>Item</th>
+      <th>Type</th>
+      <th>Status</th>
+      <th>Owner</th>
+      <th>Notes</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>MIG-001</td>
+      <td>Decide final strategy for legacy PDFs/images: automated import vs manual re-upload</td>
+      <td>Decision</td>
+      <td>Open</td>
+      <td>TBD</td>
+      <td>Blocks final cutover checklist</td>
+    </tr>
+    <tr>
+      <td>MIG-002</td>
+      <td>Produce inventory of all legacy file references and classify critical/non-critical</td>
+      <td>Analysis</td>
+      <td>Open</td>
+      <td>TBD</td>
+      <td>Include PDFs + photos</td>
+    </tr>
+    <tr>
+      <td>MIG-003</td>
+      <td>If automation chosen, implement importer to populate <code>file_files</code> and <code>attachments</code> safely</td>
+      <td>Engineering</td>
+      <td>Open</td>
+      <td>TBD</td>
+      <td>Prefer idempotent batch import with audit log</td>
+    </tr>
+    <tr>
+      <td>MIG-004</td>
+      <td>Define mapping from legacy contact <code>photo_file_id</code> to new attachment model</td>
+      <td>Engineering</td>
+      <td>Open</td>
+      <td>TBD</td>
+      <td>Covers pilot/doctor/air rescuer/technician/FA/staff</td>
+    </tr>
+    <tr>
+      <td>MIG-005</td>
+      <td>Document and execute SQS backlog drain/discard plan before production cutover</td>
+      <td>Ops</td>
+      <td>Open</td>
+      <td>TBD</td>
+      <td>See queue migration doc</td>
+    </tr>
+    <tr>
+      <td>MIG-006</td>
+      <td>Create client-facing exception list for data that cannot/will not be migrated</td>
+      <td>Governance</td>
+      <td>Open</td>
+      <td>TBD</td>
+      <td>Must be approved before go-live</td>
+    </tr>
+  </tbody>
+</table>
+
+<h2>Cutover Validation Checklist</h2>
+<ol>
+  <li>Run DB migrations in target environment.</li>
+  <li>Run all required data migration scripts (including helicopter import flow if applicable).</li>
+  <li>Validate row counts and sample records for migrated domains.</li>
+  <li>Validate file accessibility for mandatory records (especially PDFs needed operationally).</li>
+  <li>Validate queue behavior post-cutover (<code>pending</code> to <code>published</code>, no legacy SQS dependency).</li>
+  <li>Record migration result, exceptions, and follow-up tickets on this page.</li>
+</ol>
+
+<h2>Change Log</h2>
+<ul>
+  <li>2026-04-17: Initial wiki created from current migration scripts and docs.</li>
+  <li>2026-04-17: Added CKEditor-ready HTML version.</li>
+</ul>
diff --git a/docs/data-migration-wiki.md b/docs/data-migration-wiki.md
new file mode 100644
index 0000000..787ffee
--- /dev/null
+++ b/docs/data-migration-wiki.md
@@ -0,0 +1,94 @@
+# Data Migration Wiki
+
+This page is the living technical document for migration scope, decisions, limitations, and open tasks.
+Update it for every migration wave.
+For CKEditor copy-paste, use the HTML version: `docs/data-migration-wiki-ckeditor.html`.
+
+## Scope
+
+- Database schema migrations in [`migrations/`](../migrations/).
+- Data migration SQL (legacy to current domain model).
+- Non-DB migration concerns: binary files (PDF/images), queue backlog, manual user actions.
+
+## Source of Truth
+
+- Versioned DB migrations: [`migrations/*.sql`](../migrations/).
+- Legacy helicopter import flow:
+  - [`migrations/goose/20260414_helicopter_import_staging.sql`](../migrations/goose/20260414_helicopter_import_staging.sql)
+  - [`migrations/goose/20260415_helicopter_import_apply.sql`](../migrations/goose/20260415_helicopter_import_apply.sql)
+  - Deprecated helper note: [`migrations/scripts/migration_helicopter.sql`](../migrations/scripts/migration_helicopter.sql)
+- Queue migration notes: [`docs/queue-sqs-migration.md`](./queue-sqs-migration.md)
+- File manager APIs and attachment model:
+  - [`docs/file-manager-upload.md`](./file-manager-upload.md)
+  - [`docs/file-manager-attachment.md`](./file-manager-attachment.md)
+
+## Implemented Data Migrations
+
+1. `20260326_move_responsible_flight_rescuer_to_air_rescuer_profiles.sql`
+- Copies `pilot_profiles.responsible_flight_rescuer` into `air_rescuer_profiles.responsible_flight_rescuer`.
+- Drops old column from `pilot_profiles`.
+
+2. `20260403_file_manager_file_lifecycle_phase1.sql`
+- Normalizes legacy file lifecycle states (`pending/uploading`) into newer states (`validated/processing`) and carries `upload_error` into `failure_reason`.
+
+3. `20260415_helicopter_import_apply.sql`
+- Imports rows from `helicopter_old_import` into `helicopters`.
+- Maintains old-to-new ID mapping via `helicopter_old_id_map`.
+- Explicitly non-reversible (`Down` keeps data as audit trail).
+
+## Known Migration Decisions and Gaps
+
+### Confirmed "Will Not Migrate" (Current Decision)
+
+1. Legacy helicopter columns intentionally ignored:
+- `counter`
+- `service`
+- `disabled`
+- `visible`
+- Decision is documented in [`migrations/scripts/migration_helicopter.sql`](../migrations/scripts/migration_helicopter.sql).
+
+### Confirmed "Not Migrated Yet" (Open)
+
+1. Legacy SQS queue backlog
+- Current worker does not consume old SQS backlog.
+- Required action: drain/discard SQS backlog before/at cutover.
+- Source: [`docs/queue-sqs-migration.md`](./queue-sqs-migration.md).
+
+2. Binary files (PDF/images) into new file manager storage
+- Current migrations create file manager tables and attachment relations, but no SQL migration imports binary objects or bulk-inserts legacy metadata into `file_files`/`attachments`.
+- This means legacy documents may need manual re-upload unless a dedicated import job is created.
+
+3. Legacy `photo_file_id` references in contact profile tables
+- Contact profile schemas still include `photo_file_id` string columns.
+- No migration currently maps these into `attachments` + `image_attachment_id`/`foto_attachment_id`.
+
+## Manual Actions Required at Cutover
+
+1. Validate which legacy PDFs/images must remain accessible on day 1.
+2. For files without automated import, perform manual re-upload via file manager flow.
+3. Re-link uploaded files to business references (attachments) and to entity-level attachment columns where relevant.
+4. Obtain client sign-off for any files intentionally left unmigrated.
+
+## Migration TODO Register
+
+| ID | Item | Type | Status | Owner | Notes |
+|---|---|---|---|---|---|
+| MIG-001 | Decide final strategy for legacy PDFs/images: automated import vs manual re-upload | Decision | Open | TBD | Blocks final cutover checklist |
+| MIG-002 | Produce inventory of all legacy file references and classify critical/non-critical | Analysis | Open | TBD | Include PDFs + photos |
+| MIG-003 | If automation chosen, implement importer to populate `file_files` and `attachments` safely | Engineering | Open | TBD | Prefer idempotent batch import with audit log |
+| MIG-004 | Define mapping from legacy contact `photo_file_id` to new attachment model | Engineering | Open | TBD | Covers pilot/doctor/air rescuer/technician/FA/staff |
+| MIG-005 | Document and execute Redis backlog drain/discard plan before production cutover | Ops | Open | TBD | See queue migration doc |
+| MIG-006 | Create client-facing exception list for data that cannot/will not be migrated | Governance | Open | TBD | Must be approved before go-live |
+
+## Cutover Validation Checklist
+
+1. Run DB migrations in target environment.
+2. Run all required data migration scripts (including helicopter import flow if applicable).
+3. Validate row counts and sample records for migrated domains.
+4. Validate file accessibility for mandatory records (especially PDFs needed operationally).
+5. Validate queue behavior post-cutover (`pending` to `published`, no legacy Redis dependency).
+6. Record migration result, exceptions, and follow-up tickets in this page.
+
+## Change Log
+
+- 2026-04-17: Initial wiki created from current migration scripts and docs.
diff --git a/docs/docs.go b/docs/docs.go
new file mode 100644
index 0000000..5073bc8
--- /dev/null
+++ b/docs/docs.go
@@ -0,0 +1,38390 @@
+// Package docs Code generated by swaggo/swag. DO NOT EDIT
+package docs
+
+import "github.com/swaggo/swag"
+
+const docTemplate = `{
+    "schemes": {{ marshal .Schemes }},
+    "swagger": "2.0",
+    "info": {
+        "description": "{{escape .Description}}",
+        "title": "{{.Title}}",
+        "contact": {},
+        "version": "{{.Version}}"
+    },
+    "host": "{{.Host}}",
+    "basePath": "{{.BasePath}}",
+    "paths": {
+        "/api/v1/action-signoffs/get-by-flight/{flight_id}": {
+            "get": {
+                "description": "Returns the fleet-level (complaint-independent) corrective-action sign-off state for a helicopter — ` + "`" + `signed` + "`" + `, ` + "`" + `signed_at` + "`" + `, ` + "`" + `signed_by` + "`" + `. When none exists yet it returns an unsigned placeholder. A signed sign-off is what gates the EASA maintenance release.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints - Sign Off"
+                ],
+                "summary": "Get the current corrective-action sign-off for a helicopter",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ActionSignoffResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/action-signoffs/sign/{helicopter_id}": {
+            "post": {
+                "description": "Toggles the corrective-action sign-off for a helicopter. ` + "`" + `sign` + "`" + ` (optional, default true) chooses the direction: true signs, false unsigns. Send ` + "`" + `complaint_id` + "`" + ` to target a specific complaint's sign-off — signing it requires ` + "`" + `action_taken` + "`" + ` recorded (else 422 ` + "`" + `ACTION_SIGNOFF_ACTION_REQUIRED` + "`" + `), and 404 ` + "`" + `ACTION_SIGNOFF_COMPLAINT_NOT_FOUND` + "`" + ` if the complaint does not exist. Omit ` + "`" + `complaint_id` + "`" + ` for a fleet-wide (complaint-independent) sign-off. A signed sign-off is what allows an EASA maintenance release to be created for the helicopter.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints - Sign Off"
+                ],
+                "summary": "Toggle the corrective-action sign-off (per complaint or fleet-wide)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Optional complaint_id + note",
+                        "name": "request",
+                        "in": "body",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ActionSignoffSignRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ActionSignoffResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/after-flight-inspection/create": {
+            "post": {
+                "description": "Create after-flight inspection and AFI file checklist for a flight inspection.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - After Flights Inspection"
+                ],
+                "summary": "Create last flights inspection",
+                "parameters": [
+                    {
+                        "description": "Create last flights inspection request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/after-flight-inspection/delete": {
+            "delete": {
+                "description": "Delete after-flight inspection and AFI checklist rows by ` + "`" + `flight_inspection_id` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - After Flights Inspection"
+                ],
+                "summary": "Delete last flights inspection",
+                "parameters": [
+                    {
+                        "description": "Delete last flights inspection request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/after-flight-inspection/get": {
+            "get": {
+                "description": "Get after-flight inspection detail and AFI file checklist by query ` + "`" + `inspection_id` + "`" + `.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - After Flights Inspection"
+                ],
+                "summary": "Get last flights inspection",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight Inspection UUID",
+                        "name": "inspection_id",
+                        "in": "query",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/after-flight-inspection/update": {
+            "patch": {
+                "description": "Update after-flight inspection and AFI file checklist for a flight inspection.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - After Flights Inspection"
+                ],
+                "summary": "Update last flights inspection",
+                "parameters": [
+                    {
+                        "description": "Update last flights inspection request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/create": {
+            "post": {
+                "description": "Create one or more checklist headers for a single base.\nRequest uses ` + "`" + `base_id` + "`" + `.\nEach checklist can be created with or without initial ` + "`" + `items` + "`" + `.\n` + "`" + `scope_code` + "`" + ` accepts persisted codes and English aliases. Stored codes remain: ` + "`" + `TA` + "`" + `, ` + "`" + `MO` + "`" + `, ` + "`" + `DI` + "`" + `, ` + "`" + `MI` + "`" + `, ` + "`" + `DO` + "`" + `, ` + "`" + `FR` + "`" + `, ` + "`" + `SA` + "`" + `, ` + "`" + `SO` + "`" + `, ` + "`" + `M10` + "`" + `, ` + "`" + `M15` + "`" + `, ` + "`" + `M20` + "`" + `, ` + "`" + `M25` + "`" + `, ` + "`" + `DS` + "`" + `.\nExample aliases: ` + "`" + `DAILY` + "`" + ` -\u003e ` + "`" + `TA` + "`" + `, ` + "`" + `TU/TUE/TUESDAY` + "`" + ` -\u003e ` + "`" + `DI` + "`" + `, ` + "`" + `WE/WED/WEDNESDAY` + "`" + ` -\u003e ` + "`" + `MI` + "`" + `, ` + "`" + `TH/THU/THURSDAY` + "`" + ` -\u003e ` + "`" + `DO` + "`" + `, ` + "`" + `SU/SUN/SUNDAY` + "`" + ` -\u003e ` + "`" + `SO` + "`" + `, ` + "`" + `DEADLINE` + "`" + ` -\u003e ` + "`" + `DS` + "`" + `.\n` + "`" + `CAT` + "`" + ` is a virtual overview tab and is not allowed for create/update payloads.\nDuplicate ` + "`" + `position` + "`" + ` is allowed for both checklist headers and checklist items.\nDisplay order is stable: checklist headers ` + "`" + `position ASC, title ASC` + "`" + `; checklist_items ` + "`" + `position ASC, name ASC` + "`" + `.\nRequest is transactional: if one checklist/item fails, the whole batch is rolled back.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Create air rescuer checklist (bulk)",
+                "parameters": [
+                    {
+                        "description": "Bulk checklist create payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/delete/{uuid}": {
+            "delete": {
+                "description": "Delete one checklist header by UUID.\nRelated checklist items are removed together following current implementation behavior.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Delete air rescuer checklist",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist UUID",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedListResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/get-all": {
+            "get": {
+                "description": "Grouped by base and returned in ` + "`" + `data[].attributes.bases` + "`" + `.\nResponse includes ` + "`" + `tabs[]` + "`" + ` with default tab order: ` + "`" + `CAT` + "`" + `, ` + "`" + `TA` + "`" + `, ` + "`" + `MO` + "`" + `, ` + "`" + `DI` + "`" + `, ` + "`" + `MI` + "`" + `, ` + "`" + `DO` + "`" + `, ` + "`" + `FR` + "`" + `, ` + "`" + `SA` + "`" + `, ` + "`" + `SO` + "`" + `, ` + "`" + `M10` + "`" + `, ` + "`" + `M15` + "`" + `, ` + "`" + `M20` + "`" + `, ` + "`" + `M25` + "`" + `, ` + "`" + `DS` + "`" + `.\n` + "`" + `CAT` + "`" + ` is a virtual overview tab (not persisted in DB).\n` + "`" + `CAT.groups[]` + "`" + ` only includes non-empty persisted scopes and does not include ` + "`" + `checklist_items` + "`" + `.\nNormal tabs are always present. Empty normal tabs are explicitly returned as ` + "`" + `checklists: []` + "`" + `.\nScope display names: ` + "`" + `CAT=Category` + "`" + `, ` + "`" + `TA=Daily` + "`" + `, ` + "`" + `MO=Monday` + "`" + `, ` + "`" + `DI=Tuesday` + "`" + `, ` + "`" + `MI=Wednesday` + "`" + `, ` + "`" + `DO=Thursday` + "`" + `, ` + "`" + `FR=Friday` + "`" + `, ` + "`" + `SA=Saturday` + "`" + `, ` + "`" + `SO=Sunday` + "`" + `, ` + "`" + `M10=M10` + "`" + `, ` + "`" + `M15=M15` + "`" + `, ` + "`" + `M20=M20` + "`" + `, ` + "`" + `M25=M25` + "`" + `, ` + "`" + `DS=Deadline` + "`" + `.\nDuplicate ` + "`" + `position` + "`" + ` is allowed. Display order is stable: checklist headers ` + "`" + `position ASC, title ASC` + "`" + `; checklist_items ` + "`" + `position ASC, name ASC` + "`" + `.\nOptional filters: ` + "`" + `base_id` + "`" + `, ` + "`" + `category_type` + "`" + ` (` + "`" + `regular|hems` + "`" + `), ` + "`" + `base_name` + "`" + `, ` + "`" + `base_abbreviation` + "`" + `, ` + "`" + `scope_code` + "`" + ` (` + "`" + `CAT` + "`" + `/` + "`" + `OVERVIEW` + "`" + ` or persisted scope / aliases).",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "List air rescuer checklist grouped by base",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Filter by base UUID",
+                        "name": "base_id",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "regular",
+                            "hems"
+                        ],
+                        "type": "string",
+                        "description": "Filter by base category",
+                        "name": "category_type",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by base name (contains, case-insensitive)",
+                        "name": "base_name",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by base abbreviation (contains, case-insensitive)",
+                        "name": "base_abbreviation",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by scope code. Allowed canonical: CAT, TA, MO, DI, MI, DO, FR, SA, SO, M10, M15, M20, M25, DS. English aliases are also accepted.",
+                        "name": "scope_code",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/get-all/dt": {
+            "get": {
+                "description": "Datatable variant for grouped air rescuer checklist data.\nSemantic data is the same as ` + "`" + `get-all` + "`" + `: grouped by base with ` + "`" + `tabs[]` + "`" + `, virtual ` + "`" + `CAT` + "`" + `, and normal tabs always present.\n` + "`" + `CAT.groups[]` + "`" + ` only includes non-empty persisted scopes and does not include ` + "`" + `checklist_items` + "`" + `.\nEmpty normal tabs are explicitly returned as ` + "`" + `checklists: []` + "`" + `.\nScope display names: ` + "`" + `CAT=Category` + "`" + `, ` + "`" + `TA=Daily` + "`" + `, ` + "`" + `MO=Monday` + "`" + `, ` + "`" + `DI=Tuesday` + "`" + `, ` + "`" + `MI=Wednesday` + "`" + `, ` + "`" + `DO=Thursday` + "`" + `, ` + "`" + `FR=Friday` + "`" + `, ` + "`" + `SA=Saturday` + "`" + `, ` + "`" + `SO=Sunday` + "`" + `, ` + "`" + `M10=M10` + "`" + `, ` + "`" + `M15=M15` + "`" + `, ` + "`" + `M20=M20` + "`" + `, ` + "`" + `M25=M25` + "`" + `, ` + "`" + `DS=Deadline` + "`" + `.\nDuplicate ` + "`" + `position` + "`" + ` is allowed. Display order is stable: checklist headers ` + "`" + `position ASC, title ASC` + "`" + `; checklist_items ` + "`" + `position ASC, name ASC` + "`" + `.\nOptional filters: ` + "`" + `base_id` + "`" + `, ` + "`" + `category_type` + "`" + ` (` + "`" + `regular|hems` + "`" + `), ` + "`" + `base_name` + "`" + `, ` + "`" + `base_abbreviation` + "`" + `, ` + "`" + `scope_code` + "`" + `.\nPagination/query controls: ` + "`" + `page` + "`" + `, ` + "`" + `size` + "`" + `, ` + "`" + `limit` + "`" + `, ` + "`" + `draw` + "`" + `.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "List air rescuer checklist grouped by base (datatable)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Filter by base UUID",
+                        "name": "base_id",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "regular",
+                            "hems"
+                        ],
+                        "type": "string",
+                        "description": "Filter by base category",
+                        "name": "category_type",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by base name (contains, case-insensitive)",
+                        "name": "base_name",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by base abbreviation (contains, case-insensitive)",
+                        "name": "base_abbreviation",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by scope code. Allowed canonical: CAT, TA, MO, DI, MI, DO, FR, SA, SO, M10, M15, M20, M25, DS. English aliases are also accepted.",
+                        "name": "scope_code",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (max 100)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Datatable draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/get/{uuid}": {
+            "get": {
+                "description": "Return one checklist detail by UUID.\nIncludes checklist header, base info, and ` + "`" + `items` + "`" + ` (` + "`" + `checklist_items` + "`" + `).",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Get air rescuer checklist by UUID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist UUID",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/items/delete/{item_uuid}": {
+            "delete": {
+                "description": "Delete one existing checklist item by ` + "`" + `item_uuid` + "`" + `.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Delete one checklist item",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist item UUID",
+                        "name": "item_uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/items/update/{item_uuid}": {
+            "patch": {
+                "description": "Update one existing checklist item by ` + "`" + `item_uuid` + "`" + `.\nThis endpoint only affects the selected item.\nDuplicate ` + "`" + `position` + "`" + ` is allowed.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Update one checklist item",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist item UUID",
+                        "name": "item_uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Checklist item update payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/update/{uuid}": {
+            "patch": {
+                "description": "Update checklist header fields (` + "`" + `scope_code` + "`" + `, ` + "`" + `title` + "`" + `, ` + "`" + `position` + "`" + `) and/or append ` + "`" + `new_items` + "`" + `.\n` + "`" + `new_items` + "`" + ` is append-only. Existing items are not updated/deleted by this endpoint.\nItem update/delete lifecycle must use dedicated item endpoints.\n` + "`" + `scope_code` + "`" + ` accepts persisted codes and English aliases, but ` + "`" + `CAT` + "`" + ` (or ` + "`" + `OVERVIEW` + "`" + `) is not allowed for update payload.\nDuplicate ` + "`" + `position` + "`" + ` is allowed.\nRequest is transactional.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Update air rescuer checklist header and append new items",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist UUID",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Checklist update payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/{uuid}/items/create": {
+            "post": {
+                "description": "Create one or more items for an existing checklist.\nParent checklist is taken from path ` + "`" + `uuid` + "`" + `.\nDuplicate ` + "`" + `position` + "`" + ` is allowed. Display order for checklist_items is ` + "`" + `position ASC, name ASC` + "`" + `.\nRequest is transactional: if one item fails, all item inserts in the batch are rolled back.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Create checklist items (bulk)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist UUID",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Bulk checklist item create payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/{uuid}/items/reorder": {
+            "patch": {
+                "description": "Reorder one or more checklist items for the checklist in path ` + "`" + `uuid` + "`" + `.\nUse this endpoint to swap or reorder positions with a single PIN validation.\nDuplicate ` + "`" + `position` + "`" + ` values remain allowed by domain rules.\nRequest is transactional: if one item fails, all position updates are rolled back.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Reorder checklist items in one request",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist UUID",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Checklist item reorder payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/audit-logs/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Audit Logs"
+                ],
+                "summary": "List audit logs",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by request_id/layer/action/method/path/message (contains)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "POST",
+                            "PUT",
+                            "PATCH",
+                            "DELETE",
+                            "UPDATE",
+                            "ALL",
+                            "*"
+                        ],
+                        "type": "string",
+                        "description": "Method filter; single/comma-separated values or ALL/*",
+                        "name": "filter[method]",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "POST",
+                            "PUT",
+                            "PATCH",
+                            "DELETE",
+                            "UPDATE",
+                            "ALL",
+                            "*"
+                        ],
+                        "type": "string",
+                        "description": "Alias for filter[method]",
+                        "name": "method",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "air_rescuer_checklist",
+                            "audit_log",
+                            "auth",
+                            "base",
+                            "base_regular",
+                            "base_hems",
+                            "base_roster",
+                            "branding",
+                            "contact",
+                            "duty_roster",
+                            "facility",
+                            "federal_state",
+                            "file_manager",
+                            "flight",
+                            "flight_data",
+                            "forces_present",
+                            "health_insurance_company",
+                            "helicopter",
+                            "helicopter_file",
+                            "hems_roster",
+                            "hospital",
+                            "icao",
+                            "insurance_patient_data",
+                            "land",
+                            "master_setting",
+                            "medicine",
+                            "mission",
+                            "opc",
+                            "patient_data",
+                            "reserve_ac",
+                            "role",
+                            "user",
+                            "vocation",
+                            "unknown",
+                            "ALL",
+                            "*"
+                        ],
+                        "type": "string",
+                        "description": "Module filter; single/comma-separated values or ALL/*",
+                        "name": "filter[module]",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "air_rescuer_checklist",
+                            "audit_log",
+                            "auth",
+                            "base",
+                            "base_regular",
+                            "base_hems",
+                            "base_roster",
+                            "branding",
+                            "contact",
+                            "duty_roster",
+                            "facility",
+                            "federal_state",
+                            "file_manager",
+                            "flight",
+                            "flight_data",
+                            "forces_present",
+                            "health_insurance_company",
+                            "helicopter",
+                            "helicopter_file",
+                            "hems_roster",
+                            "hospital",
+                            "icao",
+                            "insurance_patient_data",
+                            "land",
+                            "master_setting",
+                            "medicine",
+                            "mission",
+                            "opc",
+                            "patient_data",
+                            "reserve_ac",
+                            "role",
+                            "user",
+                            "vocation",
+                            "unknown",
+                            "ALL",
+                            "*"
+                        ],
+                        "type": "string",
+                        "description": "Alias for filter[module]",
+                        "name": "module",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "list",
+                            "get",
+                            "create",
+                            "update",
+                            "delete",
+                            "export",
+                            "custom",
+                            "ALL",
+                            "*"
+                        ],
+                        "type": "string",
+                        "description": "Action filter; single/comma-separated values or ALL/*",
+                        "name": "filter[action]",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "list",
+                            "get",
+                            "create",
+                            "update",
+                            "delete",
+                            "export",
+                            "custom",
+                            "ALL",
+                            "*"
+                        ],
+                        "type": "string",
+                        "description": "Alias for filter[action]",
+                        "name": "action",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 200)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "created_at",
+                            "-created_at",
+                            "module",
+                            "-module",
+                            "action",
+                            "-action",
+                            "layer",
+                            "-layer",
+                            "status_code",
+                            "-status_code",
+                            "success",
+                            "-success"
+                        ],
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/email-otp/send": {
+            "post": {
+                "description": "Sends a one-time 6-digit OTP to user email using login challenge token from /auth/login.\nSecurity controls: old OTP is invalidated, resend cooldown is enforced, and resend/hour quota is enforced.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Email OTP"
+                ],
+                "summary": "Send login OTP to email",
+                "parameters": [
+                    {
+                        "description": "JSON:API Email OTP send request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPSendRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPSendResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/email-otp/verify": {
+            "post": {
+                "description": "Verifies one-time OTP and completes login by issuing auth cookies.\nOTP is one-time use, expires automatically, and failed attempts are limited and audited.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Email OTP"
+                ],
+                "summary": "Verify login OTP from email",
+                "parameters": [
+                    {
+                        "description": "JSON:API Email OTP verify request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPVerifyRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPVerifyResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/exchange": {
+            "post": {
+                "description": "Accepts Microsoft token payload from frontend ssoSilent and issues backend auth cookies.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Exchange frontend Microsoft SSO token into backend session",
+                "parameters": [
+                    {
+                        "description": "JSON:API Exchange request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ExchangeRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TokenResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/forgot-password": {
+            "post": {
+                "description": "Always returns a generic success response.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Forgot Password"
+                ],
+                "summary": "Forgot password",
+                "parameters": [
+                    {
+                        "description": "JSON:API Forgot password request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForgotPasswordRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/invite": {
+            "post": {
+                "description": "Creates user without password and sends set-password link to email.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Invite user",
+                "parameters": [
+                    {
+                        "description": "JSON:API Invite request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InviteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/invite/resend-set-password": {
+            "post": {
+                "description": "Triggers a new set-password invite email for an invited user by user_id. Response is generic for security.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Resend set-password invite",
+                "parameters": [
+                    {
+                        "description": "JSON:API resend set-password invite request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ResendSetPasswordInviteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/login": {
+            "post": {
+                "description": "If TOTP enabled, returns 202 + challenge_token (use /auth/totp/verify).\nIf TOTP is not enabled, returns 202 + email OTP challenge_token (use /auth/email-otp/send then /auth/email-otp/verify).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Login with email \u0026 password",
+                "parameters": [
+                    {
+                        "description": "JSON:API Login request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LoginRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthCurrentUserResponse"
+                        }
+                    },
+                    "202": {
+                        "description": "Accepted",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LoginEmailOTPRequiredResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/logout": {
+            "post": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Refresh"
+                ],
+                "summary": "Logout (revoke refresh)",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/me": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Get current user",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthCurrentUserResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/me/timezone": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Update current user timezone",
+                "parameters": [
+                    {
+                        "description": "JSON:API timezone update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TimezoneUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthCurrentUserResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/callback": {
+            "get": {
+                "description": "Completes Microsoft SSO login. Login succeeds only when SSO identity is already linked to an existing user.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Microsoft Entra SSO callback",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Authorization code",
+                        "name": "code",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "State",
+                        "name": "state",
+                        "in": "query",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MicrosoftCallbackResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/front-channel-logout": {
+            "get": {
+                "description": "OIDC front-channel logout endpoint. Configure this URL as the \"Front-channel logout URL\" in Microsoft Entra. Microsoft loads it in a hidden iframe when the user signs out at the IdP (or from another RP). It clears local auth cookies and revokes the server-side session plus the stored Microsoft refresh token for the browser that owns the request. It never redirects and always returns 200 so the IdP logout flow can complete.",
+                "produces": [
+                    "text/html"
+                ],
+                "tags": [
+                    "Auth - SSO"
+                ],
+                "summary": "Microsoft front-channel logout callback",
+                "responses": {
+                    "200": {
+                        "description": "logged out",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/link": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Returns JSON:API payload containing Microsoft authorization URL for linking SSO to the current authenticated user.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Microsoft Entra SSO link URL",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MicrosoftLoginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/login": {
+            "get": {
+                "description": "Returns JSON:API payload containing Microsoft authorization URL.\nBackend starts with silent session-check (` + "`" + `prompt=none` + "`" + `). If Microsoft session is inactive, callback automatically falls back to interactive login.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Microsoft Entra SSO login",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MicrosoftLoginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/login-check": {
+            "get": {
+                "description": "Returns JSON:API payload containing Microsoft authorization URL with prompt=none for strict session check.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Microsoft Entra silent session check URL",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MicrosoftLoginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/logout": {
+            "post": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - SSO"
+                ],
+                "summary": "Logout Microsoft OAuth session",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/reauth": {
+            "get": {
+                "description": "Starts a Microsoft reauthentication flow for supported sensitive actions.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Microsoft Entra SSO reauth URL",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Supported values: pin_reset_request, pin_reset_confirm",
+                        "name": "purpose",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "Required when purpose=pin_reset_confirm",
+                        "name": "token",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MicrosoftLoginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/refresh": {
+            "post": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - SSO"
+                ],
+                "summary": "Refresh Microsoft access token",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TokenResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "428": {
+                        "description": "Precondition Required",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/pin/change": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - PIN"
+                ],
+                "summary": "Change security PIN",
+                "parameters": [
+                    {
+                        "description": "JSON:API security PIN change request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINChangeRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/pin/forgot": {
+            "post": {
+                "description": "Always returns a generic success response.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - PIN"
+                ],
+                "summary": "Forgot security PIN",
+                "parameters": [
+                    {
+                        "description": "JSON:API forgot security PIN request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForgotSecurityPINRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/pin/request-reset": {
+            "post": {
+                "description": "Verifies current account password, then sends PIN reset email to currently logged-in user when PIN is blocked.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - PIN"
+                ],
+                "summary": "Request security PIN reset email for blocked PIN",
+                "parameters": [
+                    {
+                        "description": "JSON:API request security PIN reset payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RequestSecurityPINRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RequestSecurityPINResetResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/pin/reset": {
+            "post": {
+                "description": "Resets security PIN using a re-auth method. For method=password, send the single-use reset token from the email link plus password. For method=microsoft, send only reauth_token from Microsoft re-auth.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - PIN"
+                ],
+                "summary": "Reset security PIN",
+                "parameters": [
+                    {
+                        "description": "JSON:API reset security PIN request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ResetSecurityPINRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/pin/setup": {
+            "post": {
+                "description": "Creates a 6-digit security PIN for sensitive actions.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - PIN"
+                ],
+                "summary": "Setup security PIN",
+                "parameters": [
+                    {
+                        "description": "JSON:API security PIN setup request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINSetupRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINSetupResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/pin/verify": {
+            "post": {
+                "description": "Verifies PIN and returns a short-lived one-time action token.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - PIN"
+                ],
+                "summary": "Verify security PIN for sensitive action",
+                "parameters": [
+                    {
+                        "description": "JSON:API security PIN verify request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINVerifyRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINVerifyResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/refresh": {
+            "post": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Refresh"
+                ],
+                "summary": "Refresh access token",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TokenResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/register": {
+            "post": {
+                "description": "Creates user (public role: from AUTH_DEFAULT_ROLE, fallback: user) and sends verification link to email without issuing an auth session.\nNext: open verify link -\u003e then login.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Register user with email \u0026 password",
+                "parameters": [
+                    {
+                        "description": "JSON:API Register request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RegisterRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/reset-password": {
+            "post": {
+                "description": "Resets password using a single-use reset token.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Forgot Password"
+                ],
+                "summary": "Reset password",
+                "parameters": [
+                    {
+                        "description": "JSON:API Reset password request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ResetPasswordRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/sessions": {
+            "get": {
+                "description": "Lists all active sessions/devices for current user.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Refresh"
+                ],
+                "summary": "List active sessions",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/sessions/{session_id}": {
+            "delete": {
+                "description": "Revokes one session/device immediately. Requires PIN action token (header X-PIN-Verification-Token) with action=3d7d1d5f-ec48-4eca-a7ea-37f4f7927d06.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Refresh"
+                ],
+                "summary": "Delete one session",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Session ID",
+                        "name": "session_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/set-password": {
+            "post": {
+                "description": "Sets first password for invited user and marks email as verified.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Set password from invite token",
+                "parameters": [
+                    {
+                        "description": "JSON:API Set password request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SetPasswordRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnResetSetupResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/sso/link": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Link Microsoft SSO identity to the authenticated user. SSO login will only work after successful link.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Link Microsoft SSO to current user",
+                "parameters": [
+                    {
+                        "description": "JSON:API SSO link request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOLinkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOLinkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/sso/unlink": {
+            "delete": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Remove Microsoft SSO mapping from authenticated user.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Unlink Microsoft SSO from current user",
+                "parameters": [
+                    {
+                        "description": "JSON:API SSO unlink request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOUnlinkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOUnlinkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/confirm": {
+            "post": {
+                "description": "Validates initial TOTP code and enables TOTP for future logins.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - TOTP"
+                ],
+                "summary": "Confirm TOTP setup",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP confirm request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPConfirmRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/disable": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - TOTP"
+                ],
+                "summary": "Disable TOTP",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP disable request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPDisableRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/reset-setup": {
+            "post": {
+                "description": "Removes TOTP setup so the user can re-setup authenticator.\nFor method=pin, obtain token from /auth/pin/verify with action=0b5409b5-94f3-4aab-9de2-44b0ad5858f1 and send it in X-PIN-Verification-Token header.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - TOTP"
+                ],
+                "summary": "Reset TOTP setup",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP reset setup request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPResetSetupRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/setup": {
+            "post": {
+                "description": "Generates secret and otpauth URL. TOTP is NOT enabled until confirmed.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - TOTP"
+                ],
+                "summary": "Setup TOTP",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP setup request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPSetupRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPSetupResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/verify": {
+            "post": {
+                "description": "Completes login when TOTP is enabled and returns auth cookies.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - TOTP"
+                ],
+                "summary": "Verify TOTP code",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP verify request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPVerifyRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TokenResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/verify-email": {
+            "get": {
+                "description": "Confirms email verification after register.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Verify email",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Verification token",
+                        "name": "token",
+                        "in": "query",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/webauthn/login/begin": {
+            "post": {
+                "description": "Creates WebAuthn assertion options for a user email.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - WebAuthn"
+                ],
+                "summary": "Begin WebAuthn login",
+                "parameters": [
+                    {
+                        "description": "JSON:API WebAuthn login begin request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginBeginRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnBeginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/webauthn/login/finish": {
+            "post": {
+                "description": "Verifies WebAuthn assertion and issues auth cookies.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - WebAuthn"
+                ],
+                "summary": "Finish WebAuthn login",
+                "parameters": [
+                    {
+                        "description": "JSON:API WebAuthn login finish request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginFinishRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TokenResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/webauthn/register/begin": {
+            "post": {
+                "description": "Creates WebAuthn registration options for the authenticated user.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - WebAuthn"
+                ],
+                "summary": "Begin WebAuthn registration",
+                "parameters": [
+                    {
+                        "description": "JSON:API WebAuthn register begin request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterBeginRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnBeginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/webauthn/register/finish": {
+            "post": {
+                "description": "Verifies WebAuthn registration response and stores the credential.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - WebAuthn"
+                ],
+                "summary": "Finish WebAuthn registration",
+                "parameters": [
+                    {
+                        "description": "JSON:API WebAuthn register finish request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterFinishRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/webauthn/reset-setup": {
+            "post": {
+                "description": "Removes all registered WebAuthn credentials so the user can re-setup passkeys.\nFor method=pin, obtain token from /auth/pin/verify with action=1f7d457e-0a19-4a36-8d9f-2c66fd2369ab and send it in X-PIN-Verification-Token header.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - WebAuthn"
+                ],
+                "summary": "Reset WebAuthn setup",
+                "parameters": [
+                    {
+                        "description": "JSON:API WebAuthn reset setup request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnResetSetupRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/bases/create": {
+            "post": {
+                "description": "Example request:\n{\"data\":{\"type\":\"base\",\"attributes\":{\"base\":\"Lude Testing 2\",\"base_abbreviation\":\"LOIG\",\"base_category\":\"regular\",\"address\":\"Lude Airfield\",\"latitude\":47.3769,\"longitude\":8.5417,\"sortkey\":1,\"sms_alert\":false,\"checklist\":false,\"leg_time\":\"00:20\",\"default_start_time_type\":\"FIXED\",\"default_end_time_type\":\"FIXED\",\"default_shift_start\":\"06:00\",\"default_shift_end\":\"21:00\",\"utc\":\"0\",\"notes\":\"Main base\",\"operational_shift_times\":[{\"date_start\":\"2026-06-15\",\"date_end\":\"2026-06-15\",\"start_time_type\":\"BMCT\",\"end_time_type\":\"ECET\"}]}}}",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Bases"
+                ],
+                "summary": "Create base",
+                "parameters": [
+                    {
+                        "description": "JSON:API base create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/bases/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Bases"
+                ],
+                "summary": "Delete base",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Base UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/bases/get-all": {
+            "get": {
+                "description": "JSON:API list with filtering and sorting. This endpoint returns all bases.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Bases"
+                ],
+                "summary": "List bases",
+                "parameters": [
+                    {
+                        "enum": [
+                            "regular",
+                            "hems"
+                        ],
+                        "type": "string",
+                        "description": "Base category",
+                        "name": "category_type",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "regular",
+                            "hems"
+                        ],
+                        "type": "string",
+                        "description": "Alias filter for base category",
+                        "name": "base_category",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search by base/base_abbreviation/address/email/phone",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter by DUL flag (true/false)",
+                        "name": "dul",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Ignored",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Ignored",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Ignored",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/bases/get-all/dt": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Bases"
+                ],
+                "summary": "List bases (datatable)",
+                "parameters": [
+                    {
+                        "enum": [
+                            "regular",
+                            "hems"
+                        ],
+                        "type": "string",
+                        "description": "Base category",
+                        "name": "category_type",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "regular",
+                            "hems"
+                        ],
+                        "type": "string",
+                        "description": "Alias filter for base category",
+                        "name": "base_category",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter by DUL flag (true/false)",
+                        "name": "dul",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/bases/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Bases"
+                ],
+                "summary": "Get base by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Base UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/bases/update/{uuid}": {
+            "patch": {
+                "description": "Example request:\n{\"data\":{\"type\":\"hems_base\",\"id\":\"\u003cuuid\u003e\",\"attributes\":{\"base\":\"Lude Testing 2\",\"base_abbreviation\":\"LOIG\",\"base_category\":\"regular\",\"address\":\"Lude Airfield\",\"latitude\":47.3769,\"longitude\":8.5417,\"sortkey\":1,\"sms_alert\":false,\"checklist\":false,\"leg_time\":\"00:20\",\"default_start_time_type\":\"FIXED\",\"default_end_time_type\":\"FIXED\",\"default_shift_start\":\"06:00\",\"default_shift_end\":\"21:00\",\"utc\":\"0\",\"notes\":\"Main base\",\"operational_shift_times\":[{\"date_start\":\"2026-06-15\",\"date_end\":\"2026-06-15\",\"start_time_type\":\"BMCT\",\"end_time_type\":\"ECET\"}]}}}",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Bases"
+                ],
+                "summary": "Update base",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Base UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API base update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/branding/login-content": {
+            "get": {
+                "description": "Return public stable login title and subtitle from active master settings with backend defaults.\nSupports conditional requests with ` + "`" + `If-None-Match` + "`" + ` / ` + "`" + `If-Modified-Since` + "`" + `.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Branding"
+                ],
+                "summary": "Get login content",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/internal_transport_http_handlers.loginBrandingContentDocument"
+                        }
+                    },
+                    "304": {
+                        "description": "Not Modified",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/branding/login-cover": {
+            "get": {
+                "description": "Return public stable login cover image for sign-in page.\nSupports conditional requests with ` + "`" + `If-None-Match` + "`" + ` / ` + "`" + `If-Modified-Since` + "`" + `.",
+                "produces": [
+                    "image/png",
+                    "image/jpeg",
+                    "image/webp",
+                    "image/svg+xml",
+                    "application/octet-stream"
+                ],
+                "tags": [
+                    "Branding"
+                ],
+                "summary": "Get login cover image",
+                "responses": {
+                    "200": {
+                        "description": "Login cover image binary",
+                        "schema": {
+                            "type": "file"
+                        }
+                    },
+                    "304": {
+                        "description": "Not Modified",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/branding/logo": {
+            "get": {
+                "description": "Return a stable company logo asset for frontend consumption.\nBackend resolves private object storage internally (no presigned URL exposure) and serves fallback logo when managed logo is unavailable.\nSupports conditional requests with ` + "`" + `If-None-Match` + "`" + ` / ` + "`" + `If-Modified-Since` + "`" + `.",
+                "produces": [
+                    "image/png",
+                    "image/jpeg",
+                    "image/webp",
+                    "image/svg+xml",
+                    "application/octet-stream"
+                ],
+                "tags": [
+                    "Branding"
+                ],
+                "summary": "Get branding logo",
+                "responses": {
+                    "200": {
+                        "description": "Branding logo binary",
+                        "schema": {
+                            "type": "file"
+                        }
+                    },
+                    "304": {
+                        "description": "Not Modified",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/action-taken/create/{id}": {
+            "post": {
+                "description": "Records the corrective action text taken for a complaint. Recording the action does NOT sign it and does NOT lift the AOG grounding: signing the action is a separate step at POST /api/v1/action-signoffs/sign/{helicopter_id} (send complaint_id), and returning the aircraft to service requires a formal release (a signed EASA release / CRS, or an NSR). The complaint stays open until an EASA release fixes it.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Record the corrective action for a complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Action taken payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintActionTakenRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/action-taken/update/{id}": {
+            "patch": {
+                "description": "Updates the previously-recorded corrective action text of a complaint. Recording/updating the action does NOT sign it — signing is a separate step at POST /api/v1/action-signoffs/sign/{helicopter_id} (send complaint_id).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Update the recorded corrective action for a complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Action taken payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintActionTakenRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/create": {
+            "post": {
+                "description": "Create a complaint (defect) for a flight inspection.\nMEL severity (mel_severity, OPTIONAL): omit it to file a \"pending_mel\" complaint and classify later (via PATCH /complaints/update/{id}); it MUST be classified before recording action taken. A pending complaint does NOT ground the aircraft — grounding starts at classification. Values: 0 = NON-MEL (grounds immediately); 1 = A (1 day grace); 2 = B (3 days); 3 = C (10 days); 4 = D (120 days). After the grace period passes without action the aircraft becomes AOG.\nNSR (Non-Safety Release) is its own flow — sign it at POST /api/v1/complaints/nsr/sign/{id} (cancel at /nsr/unsign/{id}); it is no longer set via create/update.\nOptional fields: aircraft_hours_at_report.\nTo record the corrective action, use POST /api/v1/complaints/action-taken/create/{id} (a separate, explicitly-signed step) — it is no longer part of create/update.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Create complaint",
+                "parameters": [
+                    {
+                        "description": "JSON:API complaint create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/delete/{id}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Delete complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/get-all": {
+            "get": {
+                "description": "Lists complaints grouped by helicopter. Filter by date range on the reported date, by the name of an involved person (reporter / MEL classifier / action signer / NSR decider — i.e. pilot/techniker), and by free-text search on the complaint description.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "List complaints",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search complaint description",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Reported date lower bound (YYYY-MM-DD)",
+                        "name": "date_from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Reported date upper bound (YYYY-MM-DD)",
+                        "name": "date_to",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Involved person name (pilot/techniker, partial match)",
+                        "name": "person",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort complaints",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 1,
+                        "description": "Page number",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 20,
+                        "description": "Page size",
+                        "name": "page_size",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/get-all/dt": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "List complaints grouped by helicopter (datatable)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search complaint description",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Reported date lower bound (YYYY-MM-DD)",
+                        "name": "date_from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Reported date upper bound (YYYY-MM-DD)",
+                        "name": "date_to",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Involved person name (pilot/techniker, partial match)",
+                        "name": "person",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort complaints",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 1,
+                        "description": "Datatable draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 0,
+                        "description": "Datatable start offset",
+                        "name": "start",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 10,
+                        "description": "Datatable page length",
+                        "name": "length",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/get-by-helicopter/{helicopter_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "List complaints by helicopter",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Get complaint by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/hold-items/get-all": {
+            "get": {
+                "description": "Returns the Hold Item List (HIL): complaints that are still OPEN (not yet fixed by an EASA release) AND MEL-deferred (mel_severity \u003e 0). Non-MEL defects (which ground the aircraft immediately) and already-serviced complaints are excluded. Same grouped shape and filters as get-all.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "List hold items (open MEL-deferred defects)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "From date — reported_at \u003e= (YYYY-MM-DD). Legacy 'Von'.",
+                        "name": "date_from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "To date — reported_at \u003c= (YYYY-MM-DD). Legacy 'bis'.",
+                        "name": "date_to",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Pilot/Technician name — matches reporter or action signer. Legacy 'Pilot/Techniker'.",
+                        "name": "person",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search complaint description / MEL. Legacy 'Complains'.",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20)",
+                        "name": "page_size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort expression (e.g. reported_at DESC)",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/hold-items/get-all/dt": {
+            "get": {
+                "description": "Datatable variant of the Hold Item List (open + MEL-deferred complaints). Same filters as /hold-items/get-all (date_from, date_to, person, search, helicopter_id) plus DataTables params (start, length, draw).",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "List hold items (open MEL-deferred defects) — datatable",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "From date — reported_at \u003e= (YYYY-MM-DD). Legacy 'Von'.",
+                        "name": "date_from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "To date — reported_at \u003c= (YYYY-MM-DD). Legacy 'bis'.",
+                        "name": "date_to",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Pilot/Technician name — matches reporter or action signer.",
+                        "name": "person",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search complaint description / MEL.",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "DataTables start offset",
+                        "name": "start",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "DataTables page length",
+                        "name": "length",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "DataTables draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/nsr/sign/{id}": {
+            "post": {
+                "description": "Records an NSR decision on its own flow (separate from complaint update): the aircraft is released to fly despite the open defect and is no longer grounded by it. MEL must be classified first — an unassessed (pending_mel) defect cannot be deferred, so a pending complaint returns 422. The complaint stays OPEN and is only closed by a signed EASA release. Requires the complaint.nsr permission.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Sign a Non-Safety Release (NSR / MEL deferral) for a complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Optional NSR reason",
+                        "name": "request",
+                        "in": "body",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintNSRSignRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/nsr/unsign/{id}": {
+            "post": {
+                "description": "Revokes the NSR decision: the deferral is lifted, so the still-open defect grounds the aircraft again (AOG is recomputed). Requires the complaint.nsr permission.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Cancel a Non-Safety Release for a complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/update/{id}": {
+            "patch": {
+                "description": "Update a complaint. All attributes optional; only provided fields change.\nmel_severity: 0 = NON-MEL (immediate AOG); 1 = A (1 day); 2 = B (3 days); 3 = C (10 days); 4 = D (120 days) — AOG after grace passes.\nNSR is not set here — it is its own flow: POST /api/v1/complaints/nsr/sign/{id} (and /nsr/unsign/{id}).\nNote: the corrective action is recorded via POST /api/v1/complaints/action-taken/create/{id} (a separate, signed step), not here.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Update complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API complaint update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contact/other": {
+            "get": {
+                "description": "Lists master other-people whose name/mobile_phone/email matches ` + "`" + `q` + "`" + ` (empty ` + "`" + `q` + "`" + ` = most recent). Pick one and pass its id as ` + "`" + `other_person_id` + "`" + ` in a takeover's other_person to reuse without re-entering the data.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contact - Other People"
+                ],
+                "summary": "Search reusable \"other people\" (non-staff) for the takeover picker",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text (name / mobile_phone / email)",
+                        "name": "q",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Max results (default 20)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Offset",
+                        "name": "offset",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contact/other/create": {
+            "post": {
+                "description": "Registers a person in the other-people master so it can be reused across takeovers. The (name, mobile_phone, email) identity must be unique.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contact - Other People"
+                ],
+                "summary": "Create a reusable \"other person\" (non-staff)",
+                "parameters": [
+                    {
+                        "description": "Other person",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.OtherPersonRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contact/other/delete/{id}": {
+            "delete": {
+                "description": "Soft-deletes a master person. Existing takeover snapshots keep their own copy of the data.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contact - Other People"
+                ],
+                "summary": "Delete a reusable \"other person\"",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Other person id",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contact/other/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contact - Other People"
+                ],
+                "summary": "Get one reusable \"other person\"",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Other person id",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contact/other/update/{id}": {
+            "patch": {
+                "description": "Replaces the name/mobile_phone/email of a master person. The new identity must not collide with another person.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contact - Other People"
+                ],
+                "summary": "Update a reusable \"other person\"",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Other person id",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Other person",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.OtherPersonRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/bulk-update": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Bulk update contacts status",
+                "parameters": [
+                    {
+                        "description": "JSON:API bulk update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactBulkUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactSimpleSuccessResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/create": {
+            "post": {
+                "description": "Create new contact user and role-specific profile.\n` + "`" + `data.type` + "`" + ` must be ` + "`" + `contact_create` + "`" + `.\n` + "`" + `role_ids` + "`" + ` determines roles (use ` + "`" + `role_id` + "`" + ` only for backward compatibility). Every selected role must include its matching role-specific profile object in ` + "`" + `attributes` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Create contact",
+                "parameters": [
+                    {
+                        "description": "JSON:API Contact create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/get-all": {
+            "get": {
+                "description": "Filter contacts by role and pilot_category. Sort values: name, -name, first_name, -first_name, last_name, -last_name, email, -email, sortkey, -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "List contacts",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role: pilot|doctor|air_rescuer|technician|flight_assistant|staff",
+                        "name": "role",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Pilot category: regular|freelance|dry_lease",
+                        "name": "pilot_category",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter doctor chief flag",
+                        "name": "chief_doctor",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter technician chief flag",
+                        "name": "chief_technician",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter responsible complaint flag",
+                        "name": "responsible_complaint",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter pilot chief flag",
+                        "name": "chief_pilot",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter IFR qualified flag",
+                        "name": "ifr_qualified",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search by username/email/name",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Limit (default 20)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Offset (default 0)",
+                        "name": "offset",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/get-all/dt": {
+            "get": {
+                "description": "Datatable response with pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "List contacts (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 1000)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Role filter",
+                        "name": "role",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Pilot category filter",
+                        "name": "pilot_category",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter doctor chief flag",
+                        "name": "chief_doctor",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter technician chief flag",
+                        "name": "chief_technician",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter responsible complaint flag",
+                        "name": "responsible_complaint",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter pilot chief flag",
+                        "name": "chief_pilot",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter IFR qualified flag",
+                        "name": "ifr_qualified",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/{user_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Get contact",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Delete contact",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            },
+            "patch": {
+                "description": "` + "`" + `data.type` + "`" + ` must be ` + "`" + `contact_update` + "`" + `.\nSupports updating ` + "`" + `role_id` + "`" + ` and ` + "`" + `role_ids` + "`" + ` (multiple roles) in the same request. Sending ` + "`" + `role_ids: []` + "`" + ` clears all assigned roles.\nOnly one role-specific profile object is allowed in ` + "`" + `attributes` + "`" + `. If provided, it must match one of the contact's assigned roles.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update contact",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API Contact update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/{user_id}/chief-flags": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update chief flags",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API chief flags request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactChiefFlagsUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/{user_id}/license": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update contact license fields",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API license update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactLicenseUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/{user_id}/pilot-category": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update pilot category",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API pilot category request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactPilotCategoryUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/{user_id}/role": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update contact role",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API role update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactRoleUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/{user_id}/status": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update contact active status",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API status update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactStatusUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactSimpleSuccessResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/dul/create": {
+            "post": {
+                "description": "Possible error code: DUL_INVALID_JSON, DUL_INVALID_UUID, DUL_DATE_INVALID, DUL_VALIDATION_FAILED, DUL_CREATE_FAILED.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "DUL"
+                ],
+                "summary": "Create DUL",
+                "parameters": [
+                    {
+                        "description": "DUL create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/dul/delete/{id}": {
+            "delete": {
+                "description": "Possible error code: DUL_INVALID_UUID, DUL_DELETE_FAILED.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "DUL"
+                ],
+                "summary": "Delete DUL",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "DUL ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/dul/get-all": {
+            "get": {
+                "description": "Possible error code: DUL_LIST_FAILED.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "DUL"
+                ],
+                "summary": "List DUL grouped by base",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/info",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number alias",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size alias",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size alias",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/dul/get-all/dt": {
+            "get": {
+                "description": "Possible error code: DUL_LIST_FAILED.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "DUL"
+                ],
+                "summary": "List DUL grouped by base (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search by name/info",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/dul/get/{id}": {
+            "get": {
+                "description": "Possible error code: DUL_INVALID_UUID, DUL_NOT_FOUND.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "DUL"
+                ],
+                "summary": "Get DUL by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "DUL ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/dul/update/{id}": {
+            "patch": {
+                "description": "Possible error code: DUL_INVALID_JSON, DUL_INVALID_UUID, DUL_DATE_INVALID, DUL_VALIDATION_FAILED, DUL_NOT_FOUND, DUL_UPDATE_FAILED.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "DUL"
+                ],
+                "summary": "Update DUL",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "DUL ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "DUL update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/duty-roster/create": {
+            "post": {
+                "description": "Unified endpoint for all base categories.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Duty Roster"
+                ],
+                "summary": "Create duty roster",
+                "parameters": [
+                    {
+                        "description": "Create request payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/duty-roster/crew": {
+            "delete": {
+                "description": "Unified crew delete endpoint by ` + "`" + `data.id` + "`" + ` and ` + "`" + `roster_detail` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Duty Roster"
+                ],
+                "summary": "Remove duty roster crew assignment",
+                "parameters": [
+                    {
+                        "description": "Crew delete request payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/duty-roster/delete": {
+            "delete": {
+                "description": "Unified delete endpoint by ` + "`" + `data.id` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Duty Roster"
+                ],
+                "summary": "Delete duty roster",
+                "parameters": [
+                    {
+                        "description": "Delete request payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterAnyDeleteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/duty-roster/get-all": {
+            "get": {
+                "description": "Combined roster list across HEMS and Base for date range and optional base filters.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Duty Roster"
+                ],
+                "summary": "List all rosters (HEMS + Base)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS base UUID",
+                        "name": "hems_base_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Base UUID",
+                        "name": "base_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by base name (contains, case-insensitive)",
+                        "name": "base_name",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Start date (YYYY-MM-DD)",
+                        "name": "from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "End date (YYYY-MM-DD)",
+                        "name": "to",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/duty-roster/get-all/dt": {
+            "get": {
+                "description": "Unified datatable endpoint. Optional ` + "`" + `base_type` + "`" + ` filter: ` + "`" + `hems` + "`" + ` or ` + "`" + `base` + "`" + `.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Duty Roster"
+                ],
+                "summary": "List duty roster (datatable)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Base type filter (hems|base)",
+                        "name": "base_type",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Base UUID",
+                        "name": "base_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by base name",
+                        "name": "base_name",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Start date (YYYY-MM-DD)",
+                        "name": "from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "End date (YYYY-MM-DD)",
+                        "name": "to",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterGroupedDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/duty-roster/update": {
+            "patch": {
+                "description": "Unified update endpoint by ` + "`" + `data.id` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Duty Roster"
+                ],
+                "summary": "Update duty roster (partial)",
+                "parameters": [
+                    {
+                        "description": "Update request payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/create": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Create EASA maintenance release (draft) for a helicopter",
+                "parameters": [
+                    {
+                        "description": "JSON:API EASA release create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/delete/{id}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Delete (void) an EASA release",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "EASA release ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseDeleteResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/get-by-complaint/{complaint_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Get the current EASA release for a complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "complaint_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/get-by-flight/{flight_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Get the current EASA release for a flight",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/get-by-helicopter/{helicopter_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "List EASA releases for a helicopter",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Get EASA release by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "EASA release ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/sign/{id}": {
+            "post": {
+                "description": "Signs the release and closes the helicopter's open complaints. The corrective-action sign-off is re-checked at sign time: if the sign-off was invalidated since the draft was created (e.g. its complaint was reopened) it returns 422 ` + "`" + `EASA_RELEASE_SIGNOFF_REQUIRED` + "`" + ` and does not sign.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Sign the EASA maintenance release (closes the helicopter's open complaints)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "EASA release ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/update/{id}": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Update EASA release (draft fields)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "EASA release ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API EASA release update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/facilities/create": {
+            "post": {
+                "description": "Create a facility row using one shared table. Flight-data SPO references now expect categories like ` + "`" + `heslo-rope-label` + "`" + `, ` + "`" + `heslo-rope-length` + "`" + `, ` + "`" + `heslo-hook` + "`" + `, ` + "`" + `hec-rope-label` + "`" + `, and ` + "`" + `hec-rope-length` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Facilities"
+                ],
+                "summary": "Create facility",
+                "parameters": [
+                    {
+                        "description": "JSON:API Facility create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/facilities/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Facilities"
+                ],
+                "summary": "Delete facility",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Facility UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/facilities/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Supports one shared table with category discriminator (e.g. ` + "`" + `heslo-rope-label` + "`" + `, ` + "`" + `heslo-hook` + "`" + `, ` + "`" + `hec-rope-label` + "`" + `).",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Facilities"
+                ],
+                "summary": "List facilities",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/type/length/weight",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by category (e.g. heslo-rope-label, heslo-hook, hec-rope-label)",
+                        "name": "category",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/facilities/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Facilities"
+                ],
+                "summary": "List facilities (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Facility category",
+                        "name": "category",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/facilities/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Facilities"
+                ],
+                "summary": "Get facility by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Facility UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/facilities/update/{uuid}": {
+            "patch": {
+                "description": "Patch facility by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Facilities"
+                ],
+                "summary": "Update facility (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Facility UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API Facility update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/federal-state/create": {
+            "post": {
+                "description": "Create a federal state row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Federal State"
+                ],
+                "summary": "Create federal state",
+                "parameters": [
+                    {
+                        "description": "JSON:API federal state create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/federal-state/delete/{id}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Federal State"
+                ],
+                "summary": "Delete federal state",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Federal State ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/federal-state/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Federal State"
+                ],
+                "summary": "List federal state",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter federal state by land UUID",
+                        "name": "land_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter federal state by land name",
+                        "name": "land_name",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/federal-state/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Federal State"
+                ],
+                "summary": "List federal state (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search by name",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter federal state by land UUID",
+                        "name": "land_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter federal state by land name",
+                        "name": "land_name",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/federal-state/update/{id}": {
+            "patch": {
+                "description": "Patch federal state by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Federal State"
+                ],
+                "summary": "Update federal state (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Federal State ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API federal state update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/attachments/create": {
+            "post": {
+                "description": "Create generic attachment relation between a file and business reference (ref_type/ref_id).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Attach file to business reference",
+                "operationId": "FileManagerCreateAttachment",
+                "parameters": [
+                    {
+                        "description": "JSON:API attachment create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/attachments/delete/{uuid}": {
+            "delete": {
+                "description": "Remove generic attachment relation by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Detach attachment relation",
+                "operationId": "FileManagerDeleteAttachment",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Attachment UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/attachments/get-all": {
+            "get": {
+                "description": "List generic attachment relations by ref_type and ref_id.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "List attachments by business reference",
+                "operationId": "FileManagerListAttachmentsByReference",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Business reference type, e.g. helicopter",
+                        "name": "ref_type",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "Business reference ID",
+                        "name": "ref_id",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "Optional attachment category",
+                        "name": "category",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort values: sort_order,-sort_order,created_at,-created_at,updated_at,-updated_at",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/attachments/get/{uuid}": {
+            "get": {
+                "description": "Get one generic attachment relation by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Get attachment detail",
+                "operationId": "FileManagerGetAttachment",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Attachment UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/delete": {
+            "delete": {
+                "description": "Soft-delete multiple nodes by UUID. UUID can be folder or file.\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Delete nodes (file/folder) in bulk",
+                "operationId": "FileManagerDeleteNodesBulk",
+                "parameters": [
+                    {
+                        "description": "Bulk delete request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodePurgeBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/cancel-upload": {
+            "delete": {
+                "description": "Cancel pending upload intents before file entity creation.\nThis endpoint is intended for pre-create cleanup when FE uploaded to object storage but user cancels flow.\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Cancel upload intent (bulk)",
+                "operationId": "FileManagerCancelUploadIntentBulk",
+                "parameters": [
+                    {
+                        "description": "Bulk cancel upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create": {
+            "post": {
+                "description": "Final public control-plane step after direct PUT upload to S3 (bulk contract).\nVerifies uploaded object per item from upload intent, then persists metadata+outbox durably and emits lifecycle status.\nThis endpoint does not upload binary data.\nPublic flow: POST /files/upload (intent+presign) -\u003e PUT to S3 -\u003e POST /files/create.\nfolder_id is optional; null/omitted means create in root folder.\nCanonical JSON:API data.type is \"file_manager_file_create\" (legacy \"file_manager_file\" remains accepted for backward compatibility).\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create file record from uploaded object",
+                "operationId": "FileManagerCreateFileFromUploadedObject",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for user profile image",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-aircraft-image": {
+            "post": {
+                "description": "Same as bulk create, but folder is resolved using hierarchy \"__system_root_files__\" -\u003e \"aircraft\" -\u003e \"\u003caircraft designation\u003e\".\naircraft_uuid is required per item to resolve designation.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create aircraft image file record from uploaded object",
+                "operationId": "FileManagerCreateAircraftImageFromUploadedObject",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for aircraft image",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileAircraftBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-base-image": {
+            "post": {
+                "description": "Same as bulk create, but folder is resolved using hierarchy \"__system_root_files__\" -\u003e \"bases\" -\u003e \"\u003cbase-type\u003e\" -\u003e \"\u003cbase-name\u003e\".\nbase_uuid is required per item.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create base image file record from uploaded object",
+                "operationId": "FileManagerCreateBaseImageFromUploadedObject",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for base image",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileBaseBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-dul-image": {
+            "post": {
+                "description": "Finalize uploaded DUL image file(s) from upload intent.\nIf dul_uuid is provided, file is created under DUL folder hierarchy.\nIf dul_uuid is omitted, file is still created (unassigned), then can be attached during /api/v1/dul/create via file_uuid.\nPossible status: 201 (all success), 207 (partial success), 400 (invalid json/create failed), 401 (unauthorized), 403 (forbidden), 404 (dul or file resources not found), 409 (upload-intent conflict), 422 (validation), 503 (DUL or file-manager service unavailable).\nPossible error code: INVALID_REQUEST, USER_UNAUTHORIZED, FORBIDDEN_ACCESS, FILE_MANAGER_VALIDATION_FAILED, FILE_MANAGER_FILE_NOT_FOUND, FILE_MANAGER_UPLOAD_INTENT_NOT_FOUND, FILE_MANAGER_UPLOAD_INTENT_CONFLICT, DUL_NOT_FOUND, FILE_MANAGER_STORAGE_UNAVAILABLE, FILE_MANAGER_QUEUE_UNAVAILABLE, FILE_MANAGER_ATTACHMENT_SERVICE_UNAVAILABLE, FILE_MANAGER_ACTION_FAILED.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create DUL image file record from uploaded object",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for DUL image",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileDULBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-from-template": {
+            "post": {
+                "description": "Copies a helicopter template file into a new draft file and returns a Collabora/WOPI write session for the newly created file.\nThis endpoint always marks the created file as ` + "`" + `is_template=false` + "`" + ` because the result is a normal working document, not a reusable template.\nThe source template must be a helicopter file that belongs to the same ` + "`" + `helicopter_id` + "`" + ` provided in the request.\n` + "`" + `template_uuid` + "`" + ` is the helicopter-file UUID, not the file UUID.\nRequest fields: ` + "`" + `template_uuid` + "`" + `, ` + "`" + `helicopter_id` + "`" + `, optional ` + "`" + `takeover_id` + "`" + `, and ` + "`" + `name` + "`" + `.\nSuccess response includes the new ` + "`" + `file_id` + "`" + `, Collabora editor action URL, an access token, and the token TTL in milliseconds.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create file from template and start a WOPI edit session",
+                "parameters": [
+                    {
+                        "description": "Create-from-template payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTemplateCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-mission-file": {
+            "post": {
+                "description": "Materializes uploaded objects into folder \"missions/\u003cmission-uuid\u003e\", creates attachments (ref_type=mission), and links them to the mission so they appear in GET mission.\nmission_uuid is required per item.\nPossible error code: MISSION_FILE_INVALID_JSON, MISSION_FILE_VALIDATION, MISSION_FILE_INVALID_MISSION_UUID, MISSION_FILE_MISSION_NOT_FOUND, MISSION_FILE_SERVICE_UNAVAILABLE, MISSION_FILE_ACTION_FAILED, FILE_MANAGER_UPLOAD_INTENT_NOT_FOUND, FILE_MANAGER_STORAGE_UNAVAILABLE, FILE_MANAGER_ACTION_FAILED.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create mission file record from uploaded object",
+                "operationId": "FileManagerCreateMissionFileFromUploadedObject",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for mission file",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileMissionBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-takeover-file": {
+            "post": {
+                "description": "Finalize uploaded takeover file(s) from upload intent. The takeover relation is attached later from file_id during takeover create/update.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create takeover file node from uploaded object",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for takeover file",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTakeoverBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-user-image": {
+            "post": {
+                "description": "Same as bulk create, but folder is resolved using hierarchy \"__system_root_files__\" -\u003e \"user\" -\u003e \"\u003cusername\u003e-\u003cuser-uuid\u003e\".\nuser_uuid is required per item to resolve target user folder.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create user profile image file record from uploaded object",
+                "operationId": "FileManagerCreateUserImageFromUploadedObject",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for user profile image",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/get/{uuid}": {
+            "get": {
+                "description": "Return file metadata by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Get file detail",
+                "operationId": "FileManagerGetFile",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "File UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileDetailResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/update/{uuid}": {
+            "patch": {
+                "description": "Update file metadata by UUID (rename and/or move folder).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Update file entity (rename and/or move)",
+                "operationId": "FileManagerUpdateFileEntity",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "File UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API file manager file update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload": {
+            "post": {
+                "description": "Control-plane endpoint to create upload intents and presigned PUT URLs for direct upload to S3 (bulk contract).\nBinary does not flow through backend upload endpoint.\nAfter successful PUT to S3, call POST /api/v1/file-manager/files/create with upload_intent_uuid.\nPresigned URL TTL is controlled by backend storage config.\nBulk payload accepts one or many items. Response is item-based and supports partial success.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents + presigned PUT URLs",
+                "operationId": "FileManagerRequestUploadIntent",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload-aircraft-image": {
+            "post": {
+                "description": "Same flow as file upload intent, but dedicated for aircraft image drag-drop flow.\nUse together with /api/v1/file-manager/files/create-aircraft-image to force target folder \"aircraft\".",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents for aircraft drag-drop images",
+                "operationId": "FileManagerRequestAircraftImageUploadIntent",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload-base-image": {
+            "post": {
+                "description": "Same flow as file upload intent, but dedicated for base image flow.\nUse together with /api/v1/file-manager/files/create-base-image to force target folder under bases hierarchy.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents for base images",
+                "operationId": "FileManagerRequestBaseImageUploadIntent",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload-dul-image": {
+            "post": {
+                "description": "Dedicated upload-intent endpoint for DUL image flow.\nPossible status: 201 (all success), 207 (partial success), 400 (invalid json), 401 (unauthorized), 403 (forbidden), 422 (validation), 503 (storage/queue/upload-intent service unavailable).\nPossible error code: INVALID_REQUEST, USER_UNAUTHORIZED, FORBIDDEN_ACCESS, FILE_MANAGER_VALIDATION_FAILED, FILE_MANAGER_STORAGE_UNAVAILABLE, FILE_MANAGER_QUEUE_UNAVAILABLE, FILE_MANAGER_UPLOAD_INTENT_UNAVAILABLE, FILE_MANAGER_ACTION_FAILED.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents for DUL images",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload-mission-file": {
+            "post": {
+                "description": "Dedicated upload-intent endpoint for mission file flow.\nUse together with /api/v1/file-manager/files/create-mission-file to attach the file to a mission.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents for mission files",
+                "operationId": "FileManagerRequestMissionFileUploadIntent",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload-takeover-file": {
+            "post": {
+                "description": "Dedicated upload-intent endpoint for takeover file flow.\nUse together with /api/v1/file-manager/files/create-takeover-file to persist the takeover file relation.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents for takeover files",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload-user-image": {
+            "post": {
+                "description": "Same flow as file upload intent, but dedicated for user profile image flow.\nUse together with /api/v1/file-manager/files/create-user-image to force target folder under user hierarchy.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents for user profile images",
+                "operationId": "FileManagerRequestUserImageUploadIntent",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/{fileId}/edit-session": {
+            "get": {
+                "description": "Returns a Collabora/WOPI write session for an already existing file that belongs to the authenticated user's takeover scope or to the authenticated user as an unattached draft.\nThis endpoint does not create or copy files. It only resolves the file, checks access, and mints a new access token.\nUse this when reopening an existing file for editing.\nPath param ` + "`" + `fileId` + "`" + ` must be a valid UUIDv7.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Start a WOPI edit session for an existing file",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "File UUID (UUIDv7)",
+                        "name": "fileId",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/folders/create": {
+            "post": {
+                "description": "Create one folder metadata node under root or under provided parent_id.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create folder node",
+                "operationId": "FileManagerCreateFolder",
+                "parameters": [
+                    {
+                        "description": "JSON:API file manager folder create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/folders/get/{uuid}": {
+            "get": {
+                "description": "Return folder metadata by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Get folder detail",
+                "operationId": "FileManagerGetFolder",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Folder UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderDetailResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/folders/update/{uuid}": {
+            "patch": {
+                "description": "Update folder metadata by UUID (rename and/or move parent).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Update folder node",
+                "operationId": "FileManagerUpdateFolder",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Folder UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API file manager folder update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/get-all": {
+            "get": {
+                "description": "Return merged direct children (folders + files) for optional parent_uuid (non-recursive).\nIf parent_uuid is omitted, response returns root level nodes.\nIf search is provided, performs a global name search across all folders and files (parent_uuid is ignored).",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "List merged explorer nodes",
+                "operationId": "FileManagerListMergedExplorerNodes",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Parent folder UUID",
+                        "name": "parent_uuid",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search keyword (global name search across all folders and files)",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerNodeListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/move": {
+            "patch": {
+                "description": "Unified move endpoint. Each item UUID can be either folder UUID or file UUID.\ndestination_folder_uuid null/empty means move to root.\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Move nodes (file/folder) in bulk",
+                "operationId": "FileManagerMoveNodesBulk",
+                "parameters": [
+                    {
+                        "description": "Bulk move request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodeMoveBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/purge-delete": {
+            "delete": {
+                "description": "Permanently delete multiple trashed nodes by UUID. UUID can be folder or file.\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Purge nodes (file/folder) from trash in bulk",
+                "operationId": "FileManagerPurgeNodesBulkFromTrash",
+                "parameters": [
+                    {
+                        "description": "Bulk purge request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodePurgeBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerPurgeNodeBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/restore": {
+            "patch": {
+                "description": "Restore multiple trashed nodes by UUID to original location.\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Restore nodes (file/folder) in bulk",
+                "operationId": "FileManagerRestoreNodesBulk",
+                "parameters": [
+                    {
+                        "description": "Bulk restore request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodePurgeBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/trash/get-all": {
+            "get": {
+                "description": "Return merged trashed nodes (folders + files) for trash explorer.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "List merged trash items",
+                "operationId": "FileManagerListMergedTrashItems",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort values: deleted_at,-deleted_at,name,-name,type,-type,size_bytes,-size_bytes",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerTrashListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/create": {
+            "post": {
+                "description": "Create fleet status with maintenance schedules and file attachments.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "Create fleet status",
+                "parameters": [
+                    {
+                        "description": "Fleet status create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/delete/{id}": {
+            "delete": {
+                "description": "Soft delete fleet status by ID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "Delete fleet status",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Fleet status ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/get-all": {
+            "get": {
+                "description": "Lists every helicopter from the master, each with its latest fleet status (or empty data when it has none). Paginated by helicopter.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "List fleet status",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "default": 1,
+                        "description": "Page number",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 20,
+                        "description": "Page size",
+                        "name": "page_size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search helicopters by designation/identifier/type",
+                        "name": "filter",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort helicopters, example: designation",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by operational status; comma-separated for multiple (e.g. available,booked). Values: available, booked, aog, mcf",
+                        "name": "status",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by helicopter ID (UUIDv7); combined with status uses AND logic",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/get-all/dt": {
+            "get": {
+                "description": "Lists every helicopter from the master, each with its latest fleet status (or empty data when it has none). Paginated by helicopter.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "List fleet status (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "default": 1,
+                        "description": "Datatable draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 0,
+                        "description": "Datatable start offset",
+                        "name": "start",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 10,
+                        "description": "Datatable page length",
+                        "name": "length",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search helicopters by designation/identifier/type",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort helicopters, example: designation",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by operational status; comma-separated for multiple (e.g. available,booked). Values: available, booked, aog, mcf",
+                        "name": "status",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by helicopter ID (UUIDv7); combined with status uses AND logic",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/get-by-helicopter/{helicopter_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "Get latest fleet status by helicopter ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "Get fleet status by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Fleet status ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/history/{helicopter_id}": {
+            "get": {
+                "description": "Unified timeline: maintenance servicing events merged with complaint/MEL/NSR/action/MCF/EASA/AOG action events, newest first.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "List fleet history (timeline) by helicopter",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "integer",
+                        "default": 1,
+                        "description": "Page number",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 20,
+                        "description": "Page size",
+                        "name": "page_size",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetHistoryListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/mark-serviced/{id}": {
+            "post": {
+                "description": "Move current maintenance schedules into service logs, then clear active schedules.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "Mark fleet status serviced",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Fleet status ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusMarkServicedResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/update/{id}": {
+            "patch": {
+                "description": "Update fleet status by ID with full replacement for schedules and files.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "Update fleet status",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Fleet status ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Fleet status update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flight-data/create": {
+            "post": {
+                "description": "Create a flight data row.\nRequired field: ` + "`" + `mission_id` + "`" + `. ` + "`" + `co_pilot_id` + "`" + ` is optional.\nSwagger request example shows the complete common payload for an ` + "`" + `SPO` + "`" + ` mission. ` + "`" + `SPO` + "`" + ` is the default example shape, and for other mission types (` + "`" + `CAT` + "`" + ` and ` + "`" + `NCO` + "`" + `) you do not need to send the ` + "`" + `hec` + "`" + `, ` + "`" + `heslo` + "`" + `, or ` + "`" + `logging` + "`" + ` blocks. ` + "`" + `rotor_brake_cycle` + "`" + ` is optional for ` + "`" + `SPO` + "`" + `, ` + "`" + `CAT` + "`" + `, and ` + "`" + `NCO` + "`" + `.\nSPO facility references must point to facilities with categories: ` + "`" + `heslo_rope_label_id -\u003e heslo-rope-label` + "`" + `, ` + "`" + `heslo.slings -\u003e heslo-rope-length` + "`" + `, ` + "`" + `logging.slings -\u003e heslo-hook` + "`" + `, ` + "`" + `hec.flights -\u003e hec-rope-label` + "`" + `, and ` + "`" + `hec.slings -\u003e hec-rope-length` + "`" + `.\nSPO-specific response fields (` + "`" + `heslo` + "`" + `, ` + "`" + `logging` + "`" + `, and ` + "`" + `hec` + "`" + `) are returned only when the related mission type is ` + "`" + `SPO` + "`" + `.\nExample request: {\"data\":{\"type\":\"flight_data_create\",\"attributes\":{\"mission_id\":\"019d6774-98e8-7fba-9ef4-3795c0da8a13\"}}}",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Mission - Flight Data"
+                ],
+                "summary": "Create flight data",
+                "parameters": [
+                    {
+                        "description": "JSON:API flight data create request. Example is for SPO; CAT/NCO can omit SPO-only blocks and other optional fields.",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flight-data/delete/{id}": {
+            "delete": {
+                "description": "Soft delete flight data by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Mission - Flight Data"
+                ],
+                "summary": "Delete flight data by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight Data UUID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flight-data/get-all": {
+            "get": {
+                "description": "List flight data rows. Supports ` + "`" + `date` + "`" + ` for exact flight take-off date filtering (` + "`" + `YYYY-MM-DD` + "`" + `), plus ` + "`" + `mission_id` + "`" + ` and ` + "`" + `flight_data_id` + "`" + ` filters.\nSPO-specific response fields (` + "`" + `heslo` + "`" + `, ` + "`" + `logging` + "`" + `, and ` + "`" + `hec` + "`" + `) are returned only when the related mission type is ` + "`" + `SPO` + "`" + `.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Mission - Flight Data"
+                ],
+                "summary": "List flight data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Filter by flight take-off date (YYYY-MM-DD)",
+                        "name": "date",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by mission UUID",
+                        "name": "mission_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight-data UUID",
+                        "name": "flight_data_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flight-data/get-all/dt": {
+            "get": {
+                "description": "Datatable-friendly list of flight data rows. Supports ` + "`" + `date` + "`" + ` for exact flight take-off date filtering (` + "`" + `YYYY-MM-DD` + "`" + `), plus ` + "`" + `mission_id` + "`" + ` and ` + "`" + `flight_data_id` + "`" + ` filters.\nSame payload shape as ` + "`" + `get-all` + "`" + `, but with DataTables paging params (` + "`" + `start` + "`" + `, ` + "`" + `length` + "`" + `, ` + "`" + `draw` + "`" + `).\nSPO-specific response fields (` + "`" + `heslo` + "`" + `, ` + "`" + `logging` + "`" + `, and ` + "`" + `hec` + "`" + `) are returned only when the related mission type is ` + "`" + `SPO` + "`" + `.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Mission - Flight Data"
+                ],
+                "summary": "List flight data (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "DataTables draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Paging start offset",
+                        "name": "start",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Paging length",
+                        "name": "length",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight take-off date (YYYY-MM-DD)",
+                        "name": "date",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by mission UUID",
+                        "name": "mission_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight-data UUID",
+                        "name": "flight_data_id",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flight-data/get/{id}": {
+            "get": {
+                "description": "Get flight data detail by ID. Path ` + "`" + `id` + "`" + ` can be mission UUID, flight-data UUID, or flight UUID.\nSPO-specific response fields (` + "`" + `heslo` + "`" + `, ` + "`" + `logging` + "`" + `, and ` + "`" + `hec` + "`" + `) are returned only when the related mission type is ` + "`" + `SPO` + "`" + `.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Mission - Flight Data"
+                ],
+                "summary": "Get flight data by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Mission UUID / Flight Data UUID / Flight UUID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flight-data/update/{id}": {
+            "patch": {
+                "description": "Update a flight data row by UUID.\nRequired field: ` + "`" + `mission_id` + "`" + `. ` + "`" + `co_pilot_id` + "`" + ` is optional.\nSwagger request example uses the same SPO-shaped payload as create, but this endpoint updates an existing flight-data row.\nSPO facility references must point to facilities with categories: ` + "`" + `heslo_rope_label_id -\u003e heslo-rope-label` + "`" + `, ` + "`" + `heslo.slings -\u003e heslo-rope-length` + "`" + `, ` + "`" + `logging.slings -\u003e heslo-hook` + "`" + `, ` + "`" + `hec.flights -\u003e hec-rope-label` + "`" + `, and ` + "`" + `hec.slings -\u003e hec-rope-length` + "`" + `.\nFor frontend usage, send only the fields that need to change; omitted fields stay unchanged. ` + "`" + `SPO` + "`" + ` is the default example shape, and for ` + "`" + `CAT` + "`" + `/` + "`" + `NCO` + "`" + ` you do not need to send the ` + "`" + `hec` + "`" + `, ` + "`" + `heslo` + "`" + `, or ` + "`" + `logging` + "`" + ` blocks. ` + "`" + `rotor_brake_cycle` + "`" + ` is optional for ` + "`" + `SPO` + "`" + `, ` + "`" + `CAT` + "`" + `, and ` + "`" + `NCO` + "`" + `.\nSPO-specific response fields (` + "`" + `heslo` + "`" + `, ` + "`" + `logging` + "`" + `, and ` + "`" + `hec` + "`" + `) are returned only when the related mission type is ` + "`" + `SPO` + "`" + `.\nExample request: {\"data\":{\"type\":\"flight_data_create\",\"attributes\":{\"mission_id\":\"019d6774-98e8-7fba-9ef4-3795c0da8a13\"}}}",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Mission - Flight Data"
+                ],
+                "summary": "Update flight data by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight Data UUID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API flight data update request. Send only fields you want to change; omit the rest.",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flights/get": {
+            "get": {
+                "description": "Returns flights assigned to current auth user, including workflow steps (` + "`" + `duty_roster` + "`" + `, ` + "`" + `reserve_ac` + "`" + `, ` + "`" + `mission` + "`" + `, ` + "`" + `after_flight_inspection` + "`" + `, ` + "`" + `fm_report` + "`" + `).\nEach step includes ` + "`" + `status` + "`" + `, ` + "`" + `completed_at` + "`" + `, and ` + "`" + `completed_by` + "`" + ` for consistent FE rendering.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight"
+                ],
+                "summary": "Get flights for current auth user (from duty roster assignment)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightListResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flights/get-all": {
+            "get": {
+                "description": "Supports ` + "`" + `search` + "`" + `, ` + "`" + `filter[search]` + "`" + `, ` + "`" + `sort` + "`" + `, ` + "`" + `page[number]` + "`" + `, ` + "`" + `page[size]` + "`" + `, ` + "`" + `page` + "`" + `, ` + "`" + `size` + "`" + `, and ` + "`" + `limit` + "`" + `.\nSupports ` + "`" + `date` + "`" + ` and ` + "`" + `filter[date]` + "`" + ` for exact flight date filtering (` + "`" + `YYYY-MM-DD` + "`" + `).\nReturns paginated flights with workflow steps (` + "`" + `takeover` + "`" + `, ` + "`" + `mission` + "`" + `, ` + "`" + `after_flight_inspection` + "`" + `, ` + "`" + `fm_report` + "`" + `).\nEach step includes ` + "`" + `status` + "`" + `, ` + "`" + `completed_at` + "`" + `, and ` + "`" + `completed_by` + "`" + ` for consistent FE rendering.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight"
+                ],
+                "summary": "List flights",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (JSON:API style)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight date (YYYY-MM-DD)",
+                        "name": "date",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight date (YYYY-MM-DD) (JSON:API style)",
+                        "name": "filter[date]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort field",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/complete/{flight_id}": {
+            "post": {
+                "description": "Mark an FM report as completed for a flight. Once completed, the report becomes read-only and flight data edits are locked. Requires a verified security PIN: send the one-time token from POST /auth/pin/verify (action 1a75135b-430a-4592-83e1-6d27814185af) in the X-PIN-Verification-Token header.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Complete FM report",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "One-time security-PIN action token",
+                        "name": "X-PIN-Verification-Token",
+                        "in": "header",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportResponse"
+                        }
+                    },
+                    "202": {
+                        "description": "PIN verification required",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/get-all": {
+            "get": {
+                "description": "Returns a paginated list of FM reports. Supports ` + "`" + `search` + "`" + `, ` + "`" + `filter[search]` + "`" + `, ` + "`" + `filter[flight_id]` + "`" + `, ` + "`" + `filter[takeover_id]` + "`" + `, ` + "`" + `filter[flight_inspection_id]` + "`" + `, ` + "`" + `filter[flight_date]` + "`" + `, ` + "`" + `filter[has_engine1_gpc_n1]` + "`" + `, ` + "`" + `filter[has_engine1_ptc_n2]` + "`" + `, ` + "`" + `filter[has_engine2_gpc_n1]` + "`" + `, ` + "`" + `filter[has_engine2_ptc_n2]` + "`" + `, ` + "`" + `sort` + "`" + `, ` + "`" + `page[number]` + "`" + `, ` + "`" + `page[size]` + "`" + `, ` + "`" + `page` + "`" + `, ` + "`" + `size` + "`" + `, and ` + "`" + `limit` + "`" + `.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "List FM reports",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (JSON:API style)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight ID",
+                        "name": "filter[flight_id]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by takeover ID",
+                        "name": "filter[takeover_id]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight inspection ID",
+                        "name": "filter[flight_inspection_id]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight date (YYYY-MM-DD)",
+                        "name": "filter[flight_date]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter reports with or without engine1_gpc_n1",
+                        "name": "filter[has_engine1_gpc_n1]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter reports with or without engine1_ptc_n2",
+                        "name": "filter[has_engine1_ptc_n2]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter reports with or without engine2_gpc_n1",
+                        "name": "filter[has_engine2_gpc_n1]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter reports with or without engine2_ptc_n2",
+                        "name": "filter[has_engine2_ptc_n2]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order: flight_date, -flight_date, created_at, -created_at, updated_at, -updated_at, engine1_gpc_n1, -engine1_gpc_n1, engine1_ptc_n2, -engine1_ptc_n2, engine2_gpc_n1, -engine2_gpc_n1, engine2_ptc_n2, -engine2_ptc_n2",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/get/{flight_id}": {
+            "get": {
+                "description": "Returns a complete FM report for a flight. The persisted table keeps only the report keys; the response preloads flight, missions, flight inspection, and after-flight inspection details. It also embeds ` + "`" + `fleet_status` + "`" + ` (next inspection / maintenance schedules + base hours, component summary, EASA maintenance release) — a snapshot frozen when the report was created at after-flight inspection, so later complaints / maintenance changes do not alter a historical report. ` + "`" + `fleet_status` + "`" + ` is omitted when the helicopter has no fleet status.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Get FM report by flight ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/update/{flight_id}": {
+            "patch": {
+                "description": "Update only the engine metric fields for an existing FM report. All other FM report fields stay read-only on this endpoint. The response mirrors the GET FM report and embeds the frozen ` + "`" + `fleet_status` + "`" + ` snapshot (next inspection / maintenance schedules + base hours, component summary, EASA maintenance release).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Update FM report metrics",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API FM report update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FMReportUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/{id}": {
+            "delete": {
+                "description": "Soft-delete an FM report by ID. Requires a verified security PIN.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Delete FM report",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "FM Report ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "One-time security-PIN action token",
+                        "name": "X-PIN-Verification-Token",
+                        "in": "header",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "204": {
+                        "description": "No Content"
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/{id}/attachments": {
+            "post": {
+                "description": "After uploading the file to the presigned URL (from /attachments/upload-intent), call this endpoint with the upload_intent_uuid, name, and category to create the file node and attach it to the FM report. Valid categories: additional_fm_report, briefing, weight_balance, ofp.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Create FM report attachment from upload intent",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "FM Report ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "body with upload_intent_uuid, name, and category",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "type": "object"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "type": "object"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/{id}/attachments/upload-intent": {
+            "post": {
+                "description": "Returns a presigned PUT URL and upload_intent_uuid. After uploading the file to the presigned URL, call POST /fm-reports/{id}/attachments with the upload_intent_uuid to create the file node and attach it to the report.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Request upload intent for FM report attachment",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "FM Report ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "body with name, content_type, size_bytes",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "type": "object"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "type": "object"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/{id}/attachments/{att_id}": {
+            "delete": {
+                "description": "Remove a specific attachment from an FM report. Verifies ownership before deletion.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Delete attachment from FM report",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "FM Report ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "Attachment ID (UUIDv7)",
+                        "name": "att_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "204": {
+                        "description": "No Content"
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/forces-present/create": {
+            "post": {
+                "description": "Create a forces present row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Forces Present"
+                ],
+                "summary": "Create forces present",
+                "parameters": [
+                    {
+                        "description": "JSON:API forces present create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/forces-present/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Forces Present"
+                ],
+                "summary": "Delete forces present",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Forces Present UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/forces-present/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Forces Present"
+                ],
+                "summary": "List forces present",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/note",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/forces-present/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Forces Present"
+                ],
+                "summary": "List forces present (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/forces-present/update/{uuid}": {
+            "patch": {
+                "description": "Patch forces present by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Forces Present"
+                ],
+                "summary": "Update forces present (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Forces Present UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API forces present update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/health-insurance-companies/create": {
+            "post": {
+                "description": "Create a health insurance company row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Health Insurance Companies"
+                ],
+                "summary": "Create health insurance company",
+                "parameters": [
+                    {
+                        "description": "JSON:API health insurance company create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/health-insurance-companies/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Health Insurance Companies"
+                ],
+                "summary": "Delete health insurance company",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Health Insurance Company UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/health-insurance-companies/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, state, -state, address, -address, mobile_number, -mobile_number, email, -email, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Health Insurance Companies"
+                ],
+                "summary": "List health insurance companies",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/state/address/mobile/email",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/health-insurance-companies/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Health Insurance Companies"
+                ],
+                "summary": "List health insurance companies (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/health-insurance-companies/update/{uuid}": {
+            "patch": {
+                "description": "Patch health insurance company by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Health Insurance Companies"
+                ],
+                "summary": "Update health insurance company (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Health Insurance Company UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API health insurance company update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/cancel-upload": {
+            "post": {
+                "description": "Cancel pending upload intents from helicopter file upload flow.\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "Cancel helicopter file upload intent (bulk)",
+                "parameters": [
+                    {
+                        "description": "Bulk helicopter file cancel upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/create": {
+            "post": {
+                "description": "Create helicopter file template record from upload intent.\nSection allowed values: ` + "`" + `bfi` + "`" + ` (Before First Flight Inspection), ` + "`" + `fpwb` + "`" + ` (Flight Preparation and WB), ` + "`" + `afi` + "`" + ` (After Last Flight Inspection).\nRequired attributes: ` + "`" + `section` + "`" + `, ` + "`" + `helicopter_id` + "`" + `, ` + "`" + `upload_intent_uuid` + "`" + `, ` + "`" + `file_name` + "`" + `.\nOptional attributes: ` + "`" + `position` + "`" + `, ` + "`" + `is_required` + "`" + `, ` + "`" + `folder_uuid` + "`" + ` (if omitted, file is created in root folder).\nWhen ` + "`" + `position` + "`" + ` is omitted (or \u003c= 0), backend auto-assigns next position per ` + "`" + `helicopter_id + section` + "`" + `.\nIf file name already exists in target folder, existing file is reused and attached.\nSupports single and bulk payload.\nSingle payload example: ` + "`" + `{\"data\":{\"type\":\"helicopter_file_create\",\"attributes\":{\"section\":\"bfi\",\"position\":1,\"is_required\":true,\"helicopter_id\":\"019d6771-5fb5-7337-837f-bc5ed85181a1\",\"upload_intent_uuid\":\"019d6d0d-2de2-7db1-80a2-2862d43af620\",\"file_name\":\"A.pdf\"}}}` + "`" + `\nBulk payload example: ` + "`" + `{\"data\":[{\"type\":\"helicopter_file_create\",\"attributes\":{\"section\":\"bfi\",\"position\":1,\"is_required\":true,\"helicopter_id\":\"019d6771-5fb5-7337-837f-bc5ed85181a1\",\"upload_intent_uuid\":\"019d6d0d-2de2-7db1-80a2-2862d43af620\",\"file_name\":\"A.pdf\"}}]}` + "`" + `\nNote: OpenAPI 2.0 cannot express object-or-array union in one schema; request schema below represents bulk envelope.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "Create helicopter file",
+                "parameters": [
+                    {
+                        "description": "JSON:API helicopter file create request (single object or bulk array)",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCreateBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/delete": {
+            "delete": {
+                "description": "Delete helicopter file template record",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "Delete helicopter file",
+                "parameters": [
+                    {
+                        "description": "JSON:API helicopter file delete request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileDeleteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/get-all": {
+            "get": {
+                "description": "List helicopter file template records grouped by helicopter.\nPagination is applied per helicopter group (not per file row), so one helicopter's files stay in the same page.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "List helicopter files",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (fallback)",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort field",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/get/{helicopter_id}": {
+            "get": {
+                "description": "Return helicopter file template collection for selected helicopter",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "Get helicopter files by helicopter ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/update": {
+            "patch": {
+                "description": "Update a helicopter file template record.\nSection allowed values: ` + "`" + `bfi` + "`" + ` (Before First Flight Inspection), ` + "`" + `fpwb` + "`" + ` (Flight Preparation and WB), ` + "`" + `afi` + "`" + ` (After Last Flight Inspection).\nOptional attributes: ` + "`" + `section` + "`" + `, ` + "`" + `position` + "`" + `, ` + "`" + `is_required` + "`" + `, ` + "`" + `helicopter_id` + "`" + `, ` + "`" + `file_name` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "Update helicopter file",
+                "parameters": [
+                    {
+                        "description": "JSON:API helicopter file update request (single object or bulk array)",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUpdateBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUpdateBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/upload": {
+            "post": {
+                "description": "Control-plane endpoint for helicopter file upload intent + presigned URL flow.\nPublic flow: POST /api/v1/helicopter-files/upload -\u003e PUT to presigned URL -\u003e POST /api/v1/helicopter-files/create.\nCanonical type is ` + "`" + `helicopter_file_upload` + "`" + `.\n` + "`" + `required_headers` + "`" + ` must be sent exactly as returned when doing PUT to ` + "`" + `upload_url` + "`" + `.\nExample ` + "`" + `required_headers` + "`" + `: ` + "`" + `{\"content-type\":\"application/pdf\",\"x-amz-acl\":\"private\"}` + "`" + `\nSupports single and bulk payload.\nSingle payload example: ` + "`" + `{\"data\":{\"type\":\"helicopter_file_upload\",\"attributes\":{\"name\":\"A.pdf\",\"content_type\":\"application/pdf\",\"size_bytes\":12345}}}` + "`" + `\nBulk payload example: ` + "`" + `{\"data\":[{\"type\":\"helicopter_file_upload\",\"attributes\":{\"name\":\"A.pdf\",\"content_type\":\"application/pdf\",\"size_bytes\":12345}}]}` + "`" + `\nNote: OpenAPI 2.0 cannot express object-or-array union in one schema; request schema below represents bulk envelope.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "Request upload intents + presigned PUT URLs (helicopter file)",
+                "parameters": [
+                    {
+                        "description": "Helicopter file upload intent request (single object or bulk array)",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUploadBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-usage/create": {
+            "post": {
+                "description": "Create helicopter usage counters for a helicopter.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Helicopter Usage"
+                ],
+                "summary": "Create helicopter usage",
+                "parameters": [
+                    {
+                        "description": "JSON:API helicopter usage create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-usage/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Helicopter Usage"
+                ],
+                "summary": "Delete helicopter usage",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter Usage UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-usage/get-all": {
+            "get": {
+                "description": "JSON:API list without pagination. Sort values: helicopter_id, -helicopter_id, total_landing, -total_landing, total_airframe_hours, -total_airframe_hours, total_airframe_cycles, -total_airframe_cycles, total_engine_1_hours, -total_engine_1_hours, total_engine_1_gpc_ng_n1, -total_engine_1_gpc_ng_n1, total_engine_1_ptc_nf_n2, -total_engine_1_ptc_nf_n2, total_engine_1_ccc, -total_engine_1_ccc, total_engine_2_hours, -total_engine_2_hours, total_engine_2_gpc_ng_n1, -total_engine_2_gpc_ng_n1, total_engine_2_ptc_nf_n2, -total_engine_2_ptc_nf_n2, total_engine_2_ccc, -total_engine_2_ccc, total_flight_report, -total_flight_report, total_hook_release, -total_hook_release, total_rotor_brake_cycle, -total_rotor_brake_cycle, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Helicopter Usage"
+                ],
+                "summary": "List helicopter usage",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by helicopter or usage ID",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-usage/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Helicopter Usage"
+                ],
+                "summary": "List helicopter usage (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-usage/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Helicopter Usage"
+                ],
+                "summary": "Get helicopter usage",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter Usage UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-usage/update/{uuid}": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Helicopter Usage"
+                ],
+                "summary": "Update helicopter usage (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter Usage UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API helicopter usage update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/create": {
+            "post": {
+                "description": "Create a helicopter configuration row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "Create helicopter",
+                "parameters": [
+                    {
+                        "description": "JSON:API Helicopter create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/delete/{id}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "Delete helicopter",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: designation, -designation, sortkey, -sortkey.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "List helicopters",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by designation/identifier/type",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by operational status; comma-separated for multiple (e.g. available,booked). Values: available, booked, aog, mcf",
+                        "name": "filter[status]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "List helicopters (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by operational status; comma-separated for multiple (e.g. available,booked). Values: available, booked, aog, mcf",
+                        "name": "status",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "Get helicopter by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/update/{id}": {
+            "patch": {
+                "description": "Patch helicopter by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "Update helicopter (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API Helicopter update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/{id}/reports/next-number": {
+            "post": {
+                "description": "Returns report number format \u003cidentifier\u003e-NNNN (example: SN0901-0001). The identifier is used as the report-code prefix and the numeric suffix is auto-incremented by backend per helicopter.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "Generate next helicopter report number",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterNextReportNumberResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation-category/create": {
+            "post": {
+                "description": "Create a HEMS operation category.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - Category"
+                ],
+                "summary": "Create HEMS operation category",
+                "parameters": [
+                    {
+                        "description": "JSON:API HEMS operation category create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation-category/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - Category"
+                ],
+                "summary": "Delete HEMS operation category",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operation category UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation-category/get-all": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - Category"
+                ],
+                "summary": "List HEMS operation categories",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/type",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation-category/get-all/dt": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - Category"
+                ],
+                "summary": "List HEMS operation categories (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation-category/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - Category"
+                ],
+                "summary": "Get HEMS operation category by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operation category UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation-category/update/{uuid}": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - Category"
+                ],
+                "summary": "Update HEMS operation category (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operation category UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API HEMS operation category update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation/create": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operation"
+                ],
+                "summary": "Create HEMS operation",
+                "parameters": [
+                    {
+                        "description": "JSON:API HEMS operation create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operation"
+                ],
+                "summary": "Delete HEMS operation",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operation UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation/get-all": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operation"
+                ],
+                "summary": "List HEMS operations",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by date",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation/get-all/dt": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operation"
+                ],
+                "summary": "List HEMS operations (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operation"
+                ],
+                "summary": "Get HEMS operation by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operation UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation/update/{uuid}": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operation"
+                ],
+                "summary": "Update HEMS operation (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operation UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API HEMS operation update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operational-data/create": {
+            "post": {
+                "description": "Create a HEMS operational data record.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operational Data"
+                ],
+                "summary": "Create HEMS operational data",
+                "parameters": [
+                    {
+                        "description": "JSON:API HEMS operational data create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operational-data/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operational Data"
+                ],
+                "summary": "Delete HEMS operational data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operational data UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operational-data/get-all": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operational Data"
+                ],
+                "summary": "List HEMS operational data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by location/notes/additional_info/terrain_index",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operational-data/get-all/dt": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operational Data"
+                ],
+                "summary": "List HEMS operational data (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operational-data/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operational Data"
+                ],
+                "summary": "Get HEMS operational data by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operational data UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operational-data/update/{uuid}": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operational Data"
+                ],
+                "summary": "Update HEMS operational data (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operational data UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API HEMS operational data update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hospital/create": {
+            "post": {
+                "description": "Create a hospital row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Hospital"
+                ],
+                "summary": "Create hospital",
+                "parameters": [
+                    {
+                        "description": "JSON:API hospital create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hospital/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Hospital"
+                ],
+                "summary": "Delete hospital",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Hospital UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hospital/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, hospital_name, -hospital_name, sortkey, -sortkey, address, -address, landline_number, -landline_number, mobile_number, -mobile_number, email, -email, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Hospital"
+                ],
+                "summary": "List hospital",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by hospital name/address/contact",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hospital/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Hospital"
+                ],
+                "summary": "List hospital (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hospital/update/{uuid}": {
+            "patch": {
+                "description": "Patch hospital by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Hospital"
+                ],
+                "summary": "Update hospital (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Hospital UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API hospital update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/icao/create": {
+            "post": {
+                "description": "Create an ICAO row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - ICAO"
+                ],
+                "summary": "Create ICAO",
+                "parameters": [
+                    {
+                        "description": "JSON:API ICAO create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/icao/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - ICAO"
+                ],
+                "summary": "Delete ICAO",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "ICAO UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/icao/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: icao_code, -icao_code, sortkey, -sortkey, address, -address, landline_number, -landline_number, mobile_number, -mobile_number, email, -email, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - ICAO"
+                ],
+                "summary": "List ICAO",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by icao_code/address/contact",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/icao/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - ICAO"
+                ],
+                "summary": "List ICAO (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAODataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/icao/update/{uuid}": {
+            "patch": {
+                "description": "Patch ICAO by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - ICAO"
+                ],
+                "summary": "Update ICAO (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "ICAO UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API ICAO update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/insurance-patient-data/create": {
+            "post": {
+                "description": "Create an InsurancePatientData record.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - InsurancePatientData"
+                ],
+                "summary": "Create insurance patient data",
+                "parameters": [
+                    {
+                        "description": "JSON:API InsurancePatientData create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/insurance-patient-data/delete/{uuid}": {
+            "delete": {
+                "description": "Soft delete InsurancePatientData by ID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - InsurancePatientData"
+                ],
+                "summary": "Delete insurance patient data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "InsurancePatientData UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/insurance-patient-data/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - InsurancePatientData"
+                ],
+                "summary": "List insurance patient data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/insurance-patient-data/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - InsurancePatientData"
+                ],
+                "summary": "List insurance patient data (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/insurance-patient-data/get/{uuid}": {
+            "get": {
+                "description": "Get a single InsurancePatientData record by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - InsurancePatientData"
+                ],
+                "summary": "Get insurance patient data by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "InsurancePatientData UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/insurance-patient-data/update/{uuid}": {
+            "patch": {
+                "description": "Patch InsurancePatientData by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - InsurancePatientData"
+                ],
+                "summary": "Update insurance patient data (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "InsurancePatientData UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API InsurancePatientData update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/land/create": {
+            "post": {
+                "description": "Create a land row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Land"
+                ],
+                "summary": "Create land",
+                "parameters": [
+                    {
+                        "description": "JSON:API land create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LandCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LandResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/land/delete/{id}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Land"
+                ],
+                "summary": "Delete land",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Land ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/land/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Land"
+                ],
+                "summary": "List land",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LandListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/land/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Land"
+                ],
+                "summary": "List land (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 1000)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LandDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/land/update/{id}": {
+            "patch": {
+                "description": "Patch land by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Land"
+                ],
+                "summary": "Update land (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Land ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API land update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LandUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LandResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/master-settings/create": {
+            "post": {
+                "description": "Create a master settings row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Master Settings"
+                ],
+                "summary": "Create master settings",
+                "parameters": [
+                    {
+                        "description": "JSON:API master settings create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/master-settings/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Master Settings"
+                ],
+                "summary": "Delete master settings",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Master Settings UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Resource"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/master-settings/get": {
+            "get": {
+                "description": "Return singleton master settings object (latest active row).",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Master Settings"
+                ],
+                "summary": "Get current master settings",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/master-settings/sso/microsoft": {
+            "get": {
+                "description": "Get Microsoft Entra SSO settings from master settings.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Master Settings"
+                ],
+                "summary": "Get Microsoft Entra SSO settings",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            },
+            "put": {
+                "description": "Create or update Microsoft Entra SSO settings as master settings.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Master Settings"
+                ],
+                "summary": "Upsert Microsoft Entra SSO settings",
+                "parameters": [
+                    {
+                        "description": "JSON:API Microsoft Entra SSO upsert request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/master-settings/update/{uuid}": {
+            "patch": {
+                "description": "Patch master settings by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Master Settings"
+                ],
+                "summary": "Update master settings (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Master Settings UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API master settings update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mcf/get-by-helicopter/{helicopter_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "MCF"
+                ],
+                "summary": "List MCFs for a helicopter",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mcf/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "MCF"
+                ],
+                "summary": "Get MCF by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "MCF ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mcf/set/{helicopter_id}": {
+            "post": {
+                "description": "Toggles and edits a helicopter's MCF. ` + "`" + `active:true` + "`" + ` (or omitted) ACTIVATES/EDITS it — creates the draft if none is open (201), or UPDATES the open draft with the provided check-flight fields (200; af_hours, landing_count, utc_time, date, result, notes — all optional, partial edits allowed). Finalize it via POST /mcf/sign/{id} (sign:true). ` + "`" + `active:false` + "`" + ` DEACTIVATES it — cancels the open (unsigned) draft (\"tidak jadi\") and releases the MCF status; the cancelled record stays in the list. A signed MCF is a real event and is not cancelled.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "MCF"
+                ],
+                "summary": "Set a helicopter's MCF Yes/No — draft work endpoint (create/update or cancel)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API MCF set request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MCFSetRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mcf/sign/{id}": {
+            "post": {
+                "description": "Finalizes an MCF's check-flight. ` + "`" + `sign` + "`" + ` (optional, default true): true FINALIZES it — af_hours, landing_count, utc_time, date, result required; \"passed\" clears the aircraft from MCF, \"failed\" keeps it grounded. false UNSIGNS it — reverts a signed MCF back to a draft (keeps the recorded data). Editing draft fields is done via /mcf/set; cancelling via /mcf/set (active:false).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "MCF"
+                ],
+                "summary": "Sign (finalize) or unsign an MCF — toggle by MCF id",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "MCF ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API MCF sign request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MCFCompleteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine-group/create": {
+            "post": {
+                "description": "Create a medicine group row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine Group"
+                ],
+                "summary": "Create medicine group",
+                "parameters": [
+                    {
+                        "description": "JSON:API medicine group create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine-group/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine Group"
+                ],
+                "summary": "Delete medicine group",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Medicine Group UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine-group/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine Group"
+                ],
+                "summary": "List medicine groups",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by group name",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine-group/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine Group"
+                ],
+                "summary": "List medicine groups (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine-group/update/{uuid}": {
+            "patch": {
+                "description": "Patch medicine group by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine Group"
+                ],
+                "summary": "Update medicine group (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Medicine Group UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API medicine group update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine/create": {
+            "post": {
+                "description": "Create a medicine row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine"
+                ],
+                "summary": "Create medicine",
+                "parameters": [
+                    {
+                        "description": "JSON:API medicine create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine"
+                ],
+                "summary": "Delete medicine",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Medicine UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Search covers name, note, pack, unit, and column. Sort values: name, -name, sortkey, -sortkey, note, -note, pack, -pack, unit, -unit, column, -column, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine"
+                ],
+                "summary": "List medicine",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/note/pack/unit/column",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine"
+                ],
+                "summary": "List medicine (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine/update/{uuid}": {
+            "patch": {
+                "description": "Patch medicine by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine"
+                ],
+                "summary": "Update medicine (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Medicine UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API medicine update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission-type/create": {
+            "post": {
+                "description": "Create a mission category master record for use in mission flow.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Create mission type",
+                "parameters": [
+                    {
+                        "description": "JSON:API mission type create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionTypeCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionTypeResource"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission-type/get-all": {
+            "get": {
+                "description": "Returns all mission categories and their available subtypes.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "List mission types with subtypes",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionTypeListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/create": {
+            "post": {
+                "description": "Create a mission and link it to a flight.\n` + "`" + `type` + "`" + ` must be one of: ` + "`" + `HEMS` + "`" + `, ` + "`" + `CAT` + "`" + `, ` + "`" + `SPO` + "`" + `, ` + "`" + `NCO` + "`" + `.\n` + "`" + `subtype_id` + "`" + ` is required when ` + "`" + `type=HEMS` + "`" + ` and must reference mission subcategory under ` + "`" + `HEMS` + "`" + ` category.\n` + "`" + `subtype_id` + "`" + ` must be empty when ` + "`" + `type` + "`" + ` is not ` + "`" + `HEMS` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Create mission",
+                "parameters": [
+                    {
+                        "description": "JSON:API mission create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/delete-by-id/{mission_id}": {
+            "delete": {
+                "description": "Soft delete mission by its mission UUID. This also soft deletes flight data rows linked to the mission.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Delete mission by mission ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Mission ID (UUIDv7)",
+                        "name": "mission_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/delete/{flight_id}": {
+            "delete": {
+                "description": "Soft delete mission by linked flight ID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Delete mission",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/file/{mission_id}/{attachment_id}": {
+            "delete": {
+                "description": "Detaches the file (by its attachment id) from the mission and deletes the attachment.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Remove a file from a mission",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Mission UUID",
+                        "name": "mission_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "Attachment UUID (the file's attachment_id)",
+                        "name": "attachment_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/get-all": {
+            "get": {
+                "description": "Supports ` + "`" + `search` + "`" + `, ` + "`" + `filter[search]` + "`" + `, ` + "`" + `flight_id` + "`" + `, ` + "`" + `sort` + "`" + `, ` + "`" + `page[number]` + "`" + `, ` + "`" + `page[size]` + "`" + `, ` + "`" + `page` + "`" + `, ` + "`" + `size` + "`" + `, and ` + "`" + `limit` + "`" + `.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "List missions",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (JSON:API style)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight UUID",
+                        "name": "flight_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter missions by flight data status: draft, in_progress, or completed",
+                        "name": "flight_data_status",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort field: type|-type|flight_date|-flight_date|created_at|-created_at|updated_at|-updated_at",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/get-all/dt": {
+            "get": {
+                "description": "Supports ` + "`" + `search` + "`" + `, ` + "`" + `filter[search]` + "`" + `, ` + "`" + `date_from` + "`" + `, ` + "`" + `date_to` + "`" + `, ` + "`" + `mission_type` + "`" + `, ` + "`" + `pilot_id` + "`" + `, ` + "`" + `helicopter_id` + "`" + `, ` + "`" + `sort` + "`" + `, ` + "`" + `start` + "`" + `, ` + "`" + `length` + "`" + `, ` + "`" + `draw` + "`" + `, ` + "`" + `page[number]` + "`" + `, ` + "`" + `page[size]` + "`" + `, ` + "`" + `page` + "`" + `, ` + "`" + `size` + "`" + `, and ` + "`" + `limit` + "`" + `.\n` + "`" + `date_from` + "`" + ` and ` + "`" + `date_to` + "`" + ` filter flights by their mission date range (` + "`" + `YYYY-MM-DD` + "`" + `).\n` + "`" + `mission_type` + "`" + ` accepts ` + "`" + `HEMS` + "`" + `, ` + "`" + `CAT` + "`" + `, ` + "`" + `SPO` + "`" + `, or ` + "`" + `NCO` + "`" + `.\n` + "`" + `pilot_id` + "`" + ` filters missions where the pilot is assigned on the linked flight roster.\n` + "`" + `helicopter_id` + "`" + ` filters missions by the helicopter used in the linked flight takeover.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "List missions (datatable)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (JSON:API style)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by linked flight UUID",
+                        "name": "flight_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Mission date lower bound (YYYY-MM-DD)",
+                        "name": "date_from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Mission date upper bound (YYYY-MM-DD)",
+                        "name": "date_to",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Mission type: HEMS|CAT|SPO|NCO",
+                        "name": "mission_type",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Pilot user UUID",
+                        "name": "pilot_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Helicopter UUID",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort field: type|-type|flight_date|-flight_date|created_at|-created_at|updated_at|-updated_at",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "DataTables start index",
+                        "name": "start",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "DataTables page size",
+                        "name": "length",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "DataTables draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/get/{flight_id}": {
+            "get": {
+                "description": "Get mission detail by linked flight ID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Get mission by flight ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/update/{mission_id}": {
+            "patch": {
+                "description": "Update mission type/subtype/note by mission ID, and optionally attach files already uploaded via ` + "`" + `upload-mission-file` + "`" + `.\n` + "`" + `type` + "`" + ` must be one of: ` + "`" + `HEMS` + "`" + `, ` + "`" + `CAT` + "`" + `, ` + "`" + `SPO` + "`" + `, ` + "`" + `NCO` + "`" + `.\n` + "`" + `subtype_id` + "`" + ` is required when ` + "`" + `type=HEMS` + "`" + ` and must reference mission subcategory under ` + "`" + `HEMS` + "`" + ` category.\n` + "`" + `subtype_id` + "`" + ` must be empty when ` + "`" + `type` + "`" + ` is not ` + "`" + `HEMS` + "`" + `.\n` + "`" + `files[]` + "`" + ` items reference an ` + "`" + `upload_intent_uuid` + "`" + ` (from ` + "`" + `upload-mission-file` + "`" + `) and an optional display ` + "`" + `name` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Update mission",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Mission ID (UUIDv7)",
+                        "name": "mission_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API mission update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/motor-reaction/create": {
+            "post": {
+                "description": "Create a motor reaction row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Motor Reaction"
+                ],
+                "summary": "Create motor reaction",
+                "parameters": [
+                    {
+                        "description": "JSON:API motor reaction create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/motor-reaction/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Motor Reaction"
+                ],
+                "summary": "Delete motor reaction",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Motor Reaction UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/motor-reaction/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, score, -score, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Motor Reaction"
+                ],
+                "summary": "List motor reactions",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by reaction name or score",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/motor-reaction/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Motor Reaction"
+                ],
+                "summary": "List motor reactions (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/motor-reaction/update/{uuid}": {
+            "patch": {
+                "description": "Patch motor reaction by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Motor Reaction"
+                ],
+                "summary": "Update motor reaction (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Motor Reaction UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API motor reaction update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/opc/create": {
+            "post": {
+                "description": "Create an OPC row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - OPC"
+                ],
+                "summary": "Create opc",
+                "parameters": [
+                    {
+                        "description": "JSON:API OPC create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/opc/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - OPC"
+                ],
+                "summary": "Delete opc",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "OPC UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/opc/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: title, -title, sortkey, -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - OPC"
+                ],
+                "summary": "List opc",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by title/note",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/opc/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - OPC"
+                ],
+                "summary": "List opc (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/opc/update/{uuid}": {
+            "patch": {
+                "description": "Patch opc by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - OPC"
+                ],
+                "summary": "Update opc (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "OPC UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API OPC update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/patient-data/create": {
+            "post": {
+                "description": "Create a PatientData record.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - PatientData"
+                ],
+                "summary": "Create patient data",
+                "parameters": [
+                    {
+                        "description": "JSON:API PatientData create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/patient-data/delete/{uuid}": {
+            "delete": {
+                "description": "Soft delete PatientData by ID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - PatientData"
+                ],
+                "summary": "Delete patient data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "PatientData UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/patient-data/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: family_name, -family_name, first_name, -first_name, birth_date, -birth_date, gender, -gender, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - PatientData"
+                ],
+                "summary": "List patient data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by family_name/first_name/svnr/email/phone/street",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/patient-data/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - PatientData"
+                ],
+                "summary": "List patient data (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search by family_name/first_name/svnr/email/phone/street",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/patient-data/get/{uuid}": {
+            "get": {
+                "description": "Get a single PatientData record by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - PatientData"
+                ],
+                "summary": "Get patient data by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "PatientData UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/patient-data/update/{uuid}": {
+            "patch": {
+                "description": "Patch PatientData by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - PatientData"
+                ],
+                "summary": "Update patient data (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "PatientData UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API PatientData update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/public/branding/email-logo": {
+            "get": {
+                "description": "Return a stable company logo optimized for email clients like Outlook.\nBackend prefers managed raster thumbnail/logo and falls back to backend-generated PNG when necessary.\nSupports conditional requests with ` + "`" + `If-None-Match` + "`" + ` / ` + "`" + `If-Modified-Since` + "`" + `.",
+                "produces": [
+                    "image/png",
+                    "image/jpeg",
+                    "image/gif",
+                    "application/octet-stream"
+                ],
+                "tags": [
+                    "Branding"
+                ],
+                "summary": "Get email-safe branding logo",
+                "responses": {
+                    "200": {
+                        "description": "Email-safe branding logo binary",
+                        "schema": {
+                            "type": "file"
+                        }
+                    },
+                    "304": {
+                        "description": "Not Modified",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/reserve-acs/create": {
+            "post": {
+                "description": "Create reserve AC, create draft inspection, fill before + prepare inspection payload, and assign to flight.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Reserve AC"
+                ],
+                "summary": "Create reserve aircraft assignment",
+                "parameters": [
+                    {
+                        "description": "Create reserve AC request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/reserve-acs/delete": {
+            "delete": {
+                "description": "Delete reserve AC by body ` + "`" + `data.id` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Reserve AC"
+                ],
+                "summary": "Delete reserve AC",
+                "parameters": [
+                    {
+                        "description": "Delete reserve AC request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcDeleteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/reserve-acs/get-all": {
+            "get": {
+                "description": "Supports ` + "`" + `search` + "`" + `, ` + "`" + `filter[search]` + "`" + `, ` + "`" + `sort` + "`" + `, ` + "`" + `page[number]` + "`" + `, ` + "`" + `page[size]` + "`" + `, ` + "`" + `page` + "`" + `, ` + "`" + `size` + "`" + `, and ` + "`" + `limit` + "`" + `.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Reserve AC"
+                ],
+                "summary": "List reserve AC",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (JSON:API style)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Reserve AC UUID (exact match)",
+                        "name": "id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Flight UUID (exact match)",
+                        "name": "flight_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort field",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/reserve-acs/get-all/dt": {
+            "get": {
+                "description": "Datatable list scoped by auth user. Admin can see all rows; non-admin only sees reserve AC linked to own flight assignments.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Reserve AC"
+                ],
+                "summary": "List reserve AC (datatable)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (JSON:API style)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Reserve AC UUID (exact match)",
+                        "name": "id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Flight UUID (exact match)",
+                        "name": "flight_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort field",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/reserve-acs/get/{uuid}": {
+            "get": {
+                "description": "Get reserve AC detail. Path ` + "`" + `uuid` + "`" + ` accepts reserve_ac id, and supports fallback to flight id.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Reserve AC"
+                ],
+                "summary": "Get reserve AC by UUID or flight UUID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Reserve AC UUID or Flight UUID",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/reserve-acs/update": {
+            "patch": {
+                "description": "Update reserve AC using body ` + "`" + `data.id` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Reserve AC"
+                ],
+                "summary": "Update reserve AC",
+                "parameters": [
+                    {
+                        "description": "Update reserve AC request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/create": {
+            "post": {
+                "description": "Create a new role. Name is required and must be unique.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Create role",
+                "parameters": [
+                    {
+                        "description": "JSON:API Role create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Delete role",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "List roles",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Filter by name (contains)",
+                        "name": "filter[name]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Set to 'permissions' to embed each role's assigned permissions",
+                        "name": "include",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "List roles (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Get role by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/permissions/get-all": {
+            "get": {
+                "description": "Returns every permission grouped by its module, ordered by the module registry. Optional filter[name] narrows by permission name/key.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "List permissions grouped by module",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Filter by name/key (contains)",
+                        "name": "filter[name]",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionGroupedResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/permissions/{permission_uuid}": {
+            "patch": {
+                "description": "Patch permission by ID. Currently supports updating requires_pin.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Update permission",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Permission UUID (UUIDv7)",
+                        "name": "permission_uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API permission update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionResource"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/update/{uuid}": {
+            "patch": {
+                "description": "Patch role by ID. Provide at least one of: name, description. Name must be unique if provided.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Update role (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API Role update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/{uuid}/permissions": {
+            "get": {
+                "description": "Returns the permissions currently assigned to the given role. Pair with /roles/permissions/get-all to pre-check a role-permission editor.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "List a role's assigned permissions",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionListResponse"
+                        }
+                    }
+                }
+            },
+            "post": {
+                "description": "Assign one permission to a role. Idempotent if already assigned.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Assign permission to role",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API role permission assign request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/{uuid}/permissions/assign-bulk": {
+            "post": {
+                "description": "Assign multiple permissions to role. Idempotent for duplicates/already assigned.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Assign permissions to role (bulk)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API role permission bulk request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionListResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/{uuid}/permissions/remove-bulk": {
+            "post": {
+                "description": "Remove multiple permissions from role.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Remove permissions from role (bulk)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API role permission bulk request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionRemoveBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionListResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/{uuid}/permissions/{permission_uuid}": {
+            "delete": {
+                "description": "Remove one permission from role.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Remove permission from role",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "Permission UUID (UUIDv7)",
+                        "name": "permission_uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/takeovers/create": {
+            "post": {
+                "description": "Atomic create for duty roster + crews + reserve AC + pre-flight inspection + flight. The takeover inspection payload also includes fleet status files under ` + "`" + `inspection.fleet_status_file` + "`" + `.\nOptional takeover file uploads can be included via ` + "`" + `data.attributes.files[*]` + "`" + ` using upload intent UUIDs.\nEdited template draft files created earlier can be linked by passing ` + "`" + `data.attributes.edited_template_file_ids[*]` + "`" + `.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight - Takeovers"
+                ],
+                "summary": "Create takeover in one request",
+                "parameters": [
+                    {
+                        "description": "Create takeover request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/takeovers/delete/{id}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight - Takeovers"
+                ],
+                "summary": "Delete takeover by flight UUID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight UUID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/takeovers/get-all": {
+            "get": {
+                "description": "Return composite takeover records built from flight, reserve AC, duty roster, and inspection. The inspection payload includes ` + "`" + `before` + "`" + `, ` + "`" + `prepare` + "`" + `, and ` + "`" + `fleet_status_file` + "`" + `.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight - Takeovers"
+                ],
+                "summary": "List takeovers",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/takeovers/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight - Takeovers"
+                ],
+                "summary": "Get takeover by flight UUID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight UUID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/takeovers/update/{id}": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight - Takeovers"
+                ],
+                "summary": "Replace takeover by flight UUID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight UUID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Update takeover request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/users/create": {
+            "post": {
+                "description": "Create a new user. Email, username, first name, last name and role_id are required. Use role_ids to assign additional roles.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "Create user",
+                "parameters": [
+                    {
+                        "description": "JSON:API User create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/users/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "Delete user",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/users/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: email, -email, first_name, -first_name, last_name, -last_name, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "List users",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by username/email/first_name/last_name (contains)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/users/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "List users (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/users/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "Get user by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/users/update/{uuid}": {
+            "patch": {
+                "description": "Patch user by ID. Provide at least one attribute to update.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "Update user (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API User update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/vocation/create": {
+            "post": {
+                "description": "Create a vocation row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Vocation"
+                ],
+                "summary": "Create vocation",
+                "parameters": [
+                    {
+                        "description": "JSON:API vocation create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/vocation/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Vocation"
+                ],
+                "summary": "Delete vocation",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Vocation UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/vocation/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Vocation"
+                ],
+                "summary": "List vocation",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/note",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/vocation/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Vocation"
+                ],
+                "summary": "List vocation (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/vocation/update/{uuid}": {
+            "patch": {
+                "description": "Patch vocation by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Vocation"
+                ],
+                "summary": "Update vocation (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Vocation UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API vocation update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "internal_transport_http_handlers.loginBrandingContentAttrsDTO": {
+            "type": "object",
+            "properties": {
+                "subtitle": {
+                    "type": "string"
+                },
+                "title": {
+                    "type": "string"
+                },
+                "updated_at": {
+                    "type": "string"
+                },
+                "version": {
+                    "type": "string"
+                }
+            }
+        },
+        "internal_transport_http_handlers.loginBrandingContentData": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/internal_transport_http_handlers.loginBrandingContentAttrsDTO"
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "internal_transport_http_handlers.loginBrandingContentDocument": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/internal_transport_http_handlers.loginBrandingContentData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionAttributes": {
+            "type": "object",
+            "properties": {
+                "completed": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-09T05:00:00Z"
+                },
+                "done_file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionFileChecklistItem"
+                    }
+                },
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionFileChecklistItem"
+                    }
+                },
+                "flight_data_count": {
+                    "type": "integer",
+                    "example": 2
+                },
+                "flight_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionResource"
+                },
+                "flight_inspection_id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "flight_time_seconds": {
+                    "type": "integer",
+                    "example": 9000
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResource"
+                },
+                "hydraulic_lh_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "hydraulic_rh_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "mission_code": {
+                    "type": "string",
+                    "example": "M-2026-001"
+                },
+                "mission_type": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "note": {
+                    "type": "string",
+                    "example": "All checks completed"
+                },
+                "oil_engine_nr1_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "oil_engine_nr2_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "oil_transmission_igb_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "oil_transmission_mgb_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "oil_transmission_tgb_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "route": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "total": {
+                    "type": "integer",
+                    "example": 3
+                },
+                "total_flight": {
+                    "type": "integer",
+                    "example": 3
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-09T05:00:00Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionFileChecklistItem": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "file_name": {
+                    "type": "string",
+                    "example": "After Flight Checklist.pdf"
+                },
+                "helicopter_file_id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-111111111111"
+                },
+                "is_done": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "after_flight_inspection"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionUpsertAttributes": {
+            "type": "object",
+            "properties": {
+                "hydraulic_lh_checked": {
+                    "type": "string"
+                },
+                "hydraulic_rh_checked": {
+                    "type": "string"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "oil_engine_nr1_checked": {
+                    "type": "string"
+                },
+                "oil_engine_nr2_checked": {
+                    "type": "string"
+                },
+                "oil_transmission_igb_checked": {
+                    "type": "string"
+                },
+                "oil_transmission_mgb_checked": {
+                    "type": "string"
+                },
+                "oil_transmission_tgb_checked": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionUpsertData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionUpsertAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "after_flight_inspection_upsert",
+                        "after_flight_inspection"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionUpsertRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionUpsertData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AirRescuerProfileAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "responsible_flight_rescuer": {
+                    "type": "boolean"
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AirRescuerProfileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "responsible_flight_rescuer": {
+                    "type": "boolean"
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AuthCurrentUserAttributes": {
+            "type": "object",
+            "properties": {
+                "auth_provider": {
+                    "type": "string",
+                    "example": "email"
+                },
+                "dul_bases": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULBase"
+                    }
+                },
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "email_sso": {
+                    "type": "string",
+                    "example": "user.sso@example.com"
+                },
+                "email_verified_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "foto": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserFoto"
+                },
+                "is_previously_configured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "linked_sso": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "login_method": {
+                    "type": "string",
+                    "example": "email"
+                },
+                "microsoft_scope": {
+                    "type": "string",
+                    "example": "openid profile email offline_access User.Read"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "permission_modules": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionGroupResource"
+                    }
+                },
+                "permissions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionMini"
+                    }
+                },
+                "pin_blocked": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "pin_configured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "roles": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleMini"
+                    }
+                },
+                "timezone": {
+                    "type": "string",
+                    "example": "Asia/Jakarta"
+                },
+                "totp_enabled": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "webauthn_configured": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AuthCurrentUserResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthCurrentUserAttributes"
+                        },
+                        "id": {
+                            "type": "string",
+                            "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "user"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AuthSessionDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "deleted": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_session_delete"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AuthSessionItem": {
+            "type": "object",
+            "properties": {
+                "active_now": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-13T12:00:00Z"
+                },
+                "device_name": {
+                    "type": "string",
+                    "example": "Chrome on macOS"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "ip_address": {
+                    "type": "string",
+                    "example": "127.0.0.1"
+                },
+                "last_active_at": {
+                    "type": "string",
+                    "example": "2026-03-13T12:10:00Z"
+                },
+                "user_agent": {
+                    "type": "string",
+                    "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AuthSessionsResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "sessions": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionItem"
+                                    }
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_sessions"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Lude Airfield"
+                },
+                "base": {
+                    "type": "string",
+                    "example": "Lude"
+                },
+                "base_abbreviation": {
+                    "type": "string",
+                    "example": "LOIG"
+                },
+                "base_category": {
+                    "type": "string",
+                    "enum": [
+                        "regular",
+                        "hems"
+                    ],
+                    "example": "regular"
+                },
+                "checklist": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "control_center": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "default_end_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "default_start_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "dry": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "dul": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "email": {
+                    "type": "string",
+                    "example": "lude@wucher.local"
+                },
+                "foto": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseFoto"
+                },
+                "hems_edc": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseContact"
+                    }
+                },
+                "hems_edc_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "+62-21-1234"
+                },
+                "latitude": {
+                    "type": "number",
+                    "example": 47.3769
+                },
+                "leg_time": {
+                    "type": "string",
+                    "example": "00:20"
+                },
+                "longitude": {
+                    "type": "number",
+                    "example": 8.5417
+                },
+                "med_pax": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseContact"
+                    }
+                },
+                "med_pax_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+62-812-1234"
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Main base"
+                },
+                "operational_shift_times": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseOperationalShiftTime"
+                    }
+                },
+                "responsible_pilot_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "responsible_pilots": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseContact"
+                    }
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseShiftTime"
+                },
+                "sms_alert": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "utc": {
+                    "type": "string",
+                    "example": "0"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseContact": {
+            "type": "object",
+            "properties": {
+                "first_name": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "last_name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseCreateAttributes": {
+            "type": "object",
+            "required": [
+                "base",
+                "latitude",
+                "longitude"
+            ],
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Lude Airfield"
+                },
+                "base": {
+                    "type": "string",
+                    "example": "Lude"
+                },
+                "base_abbreviation": {
+                    "type": "string",
+                    "example": "LOIG"
+                },
+                "base_category": {
+                    "type": "string",
+                    "enum": [
+                        "regular",
+                        "hems"
+                    ],
+                    "example": "regular"
+                },
+                "checklist": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "control_center": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "default_end_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "default_shift_end": {
+                    "type": "string",
+                    "example": "21:00:00"
+                },
+                "default_shift_start": {
+                    "type": "string",
+                    "example": "06:00:00"
+                },
+                "default_shift_time": {
+                    "type": "string",
+                    "example": "12:00"
+                },
+                "default_start_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "dry": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "dul": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "email": {
+                    "type": "string",
+                    "example": "lude@wucher.local"
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"
+                },
+                "hems_edc_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "+62-21-1234"
+                },
+                "latitude": {
+                    "type": "number",
+                    "maximum": 90,
+                    "minimum": -90,
+                    "example": 47.3769
+                },
+                "leg_time": {
+                    "type": "string",
+                    "example": "00:20"
+                },
+                "longitude": {
+                    "type": "number",
+                    "maximum": 180,
+                    "minimum": -180,
+                    "example": 8.5417
+                },
+                "med_pax_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+62-812-1234"
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Main base"
+                },
+                "operational_shift_times": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseOperationalShiftTime"
+                    }
+                },
+                "responsible_pilot_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseShiftTime"
+                },
+                "sms_alert": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "utc": {
+                    "type": "string",
+                    "example": "0"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "base"
+                    ],
+                    "example": "base"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseDeleteAttributes": {
+            "type": "object",
+            "properties": {
+                "deleted": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseDeleteResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseDeleteAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6b10-a385-7e9e-a553-8e892bcec0ef"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "base_delete"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseDeleteResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseFoto": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/base/lude.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Expires=900\u0026X-Amz-Signature=abc123"
+                },
+                "original_size_bytes": {
+                    "type": "integer",
+                    "example": 1024000
+                },
+                "thumbnail_download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/base/lude.thumb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Expires=900\u0026X-Amz-Signature=abc123"
+                },
+                "uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseOperationalShiftTime": {
+            "type": "object",
+            "properties": {
+                "date_end": {
+                    "type": "string",
+                    "example": "2026-04-12"
+                },
+                "date_start": {
+                    "type": "string",
+                    "example": "2026-04-12"
+                },
+                "end_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseShiftTime"
+                },
+                "start_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "base"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseShiftTime": {
+            "type": "object",
+            "properties": {
+                "end": {
+                    "type": "string",
+                    "example": "21:00"
+                },
+                "start": {
+                    "type": "string",
+                    "example": "06:00"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Lude Airfield"
+                },
+                "base": {
+                    "type": "string",
+                    "example": "Lude"
+                },
+                "base_abbreviation": {
+                    "type": "string",
+                    "example": "LOIG"
+                },
+                "base_category": {
+                    "type": "string",
+                    "enum": [
+                        "regular",
+                        "hems"
+                    ],
+                    "example": "regular"
+                },
+                "checklist": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "control_center": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "default_end_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "default_shift_end": {
+                    "type": "string",
+                    "example": "21:00:00"
+                },
+                "default_shift_start": {
+                    "type": "string",
+                    "example": "06:00:00"
+                },
+                "default_shift_time": {
+                    "type": "string",
+                    "example": "12:00"
+                },
+                "default_start_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "dry": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "dul": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "email": {
+                    "type": "string",
+                    "example": "lude@wucher.local"
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"
+                },
+                "hems_edc_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "+62-21-1234"
+                },
+                "latitude": {
+                    "type": "number",
+                    "maximum": 90,
+                    "minimum": -90,
+                    "example": 47.3769
+                },
+                "leg_time": {
+                    "type": "string",
+                    "example": "00:20"
+                },
+                "longitude": {
+                    "type": "number",
+                    "maximum": 180,
+                    "minimum": -180,
+                    "example": 8.5417
+                },
+                "med_pax_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+62-812-1234"
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Main base"
+                },
+                "operational_shift_times": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseOperationalShiftTime"
+                    }
+                },
+                "responsible_pilot_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseShiftTime"
+                },
+                "sms_alert": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "utc": {
+                    "type": "string",
+                    "example": "0"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "base_update"
+                    ],
+                    "example": "base_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactBaseRole": {
+            "type": "object",
+            "properties": {
+                "base_id": {
+                    "type": "string"
+                },
+                "base_name": {
+                    "type": "string"
+                },
+                "role_code": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactBulkUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "required": [
+                        "user_ids"
+                    ],
+                    "properties": {
+                        "is_active": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "user_ids": {
+                            "type": "array",
+                            "minItems": 1,
+                            "items": {
+                                "type": "string"
+                            },
+                            "example": [
+                                "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1"
+                            ]
+                        }
+                    }
+                },
+                "type": {
+                    "type": "string",
+                    "example": "contact_bulk_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactBulkUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactBulkUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactChiefFlagsUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "properties": {
+                        "is_chief_physician": {
+                            "type": "boolean"
+                        },
+                        "is_chief_pilot": {
+                            "type": "boolean"
+                        },
+                        "is_chief_technician": {
+                            "type": "boolean"
+                        }
+                    }
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactChiefFlagsUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactChiefFlagsUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactCreateAttributes": {
+            "type": "object",
+            "properties": {
+                "air_rescuer": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AirRescuerProfileAttributes"
+                },
+                "doctor": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DoctorProfileAttributes"
+                },
+                "email": {
+                    "type": "string"
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "maxLength": 64
+                },
+                "first_name": {
+                    "type": "string",
+                    "maxLength": 100
+                },
+                "flight_assistant": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightAssistantProfileAttributes"
+                },
+                "is_active": {
+                    "type": "boolean"
+                },
+                "is_admin": {
+                    "type": "boolean"
+                },
+                "last_name": {
+                    "type": "string",
+                    "maxLength": 100
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "pilot": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PilotProfileAttributes"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1"
+                },
+                "role_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1",
+                        "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d2"
+                    ]
+                },
+                "sortkey": {
+                    "type": "integer"
+                },
+                "sso_email": {
+                    "type": "string"
+                },
+                "staff": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.StaffProfileAttributes"
+                },
+                "technician": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TechnicianProfileAttributes"
+                },
+                "timezone": {
+                    "type": "string",
+                    "maxLength": 64
+                },
+                "username": {
+                    "type": "string",
+                    "maxLength": 100
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "contact_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactLicenseUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "properties": {
+                        "license_no": {
+                            "type": "string"
+                        }
+                    }
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactLicenseUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactLicenseUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactListAttributes": {
+            "type": "object",
+            "properties": {
+                "air_rescuer": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AirRescuerProfileAttributes"
+                },
+                "base_roles": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactBaseRole"
+                    }
+                },
+                "created_at": {
+                    "type": "string"
+                },
+                "created_by": {
+                    "type": "string"
+                },
+                "doctor": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DoctorProfileAttributes"
+                },
+                "email": {
+                    "type": "string"
+                },
+                "first_name": {
+                    "type": "string"
+                },
+                "flight_assistant": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightAssistantProfileAttributes"
+                },
+                "is_active": {
+                    "type": "boolean"
+                },
+                "is_admin": {
+                    "type": "boolean"
+                },
+                "last_name": {
+                    "type": "string"
+                },
+                "license_no": {
+                    "type": "string"
+                },
+                "location": {
+                    "type": "string"
+                },
+                "mobile_phone": {
+                    "type": "string"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "pilot": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PilotProfileAttributes"
+                },
+                "pilot_category": {
+                    "type": "string"
+                },
+                "role_code": {
+                    "type": "string"
+                },
+                "role_name": {
+                    "type": "string"
+                },
+                "roles": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactRole"
+                    }
+                },
+                "set_password": {
+                    "type": "boolean"
+                },
+                "short_name": {
+                    "type": "string"
+                },
+                "sortkey": {
+                    "type": "integer"
+                },
+                "sso_email": {
+                    "type": "string"
+                },
+                "staff": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.StaffProfileAttributes"
+                },
+                "technician": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TechnicianProfileAttributes"
+                },
+                "updated_at": {
+                    "type": "string"
+                },
+                "updated_by": {
+                    "type": "string"
+                },
+                "username": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactListItem": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string"
+                },
+                "created_by": {
+                    "type": "string"
+                },
+                "email": {
+                    "type": "string"
+                },
+                "first_name": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "is_active": {
+                    "type": "boolean"
+                },
+                "is_admin": {
+                    "type": "boolean"
+                },
+                "last_name": {
+                    "type": "string"
+                },
+                "license_no": {
+                    "type": "string"
+                },
+                "location": {
+                    "type": "string"
+                },
+                "mobile_phone": {
+                    "type": "string"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "pilot_category": {
+                    "type": "string"
+                },
+                "role_code": {
+                    "type": "string"
+                },
+                "role_name": {
+                    "type": "string"
+                },
+                "set_password": {
+                    "type": "boolean"
+                },
+                "short_name": {
+                    "type": "string"
+                },
+                "sortkey": {
+                    "type": "integer"
+                },
+                "updated_at": {
+                    "type": "string"
+                },
+                "updated_by": {
+                    "type": "string"
+                },
+                "username": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "attributes": {
+                                "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListAttributes"
+                            },
+                            "id": {
+                                "type": "string",
+                                "example": "019dcce4-f15e-7685-8e4c-76f8ad20594b"
+                            },
+                            "type": {
+                                "type": "string",
+                                "example": "contact"
+                            }
+                        }
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "limit": {
+                            "type": "integer"
+                        },
+                        "offset": {
+                            "type": "integer"
+                        },
+                        "total": {
+                            "type": "integer"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactPilotCategoryUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "required": [
+                        "pilot_category"
+                    ],
+                    "properties": {
+                        "pilot_category": {
+                            "type": "string",
+                            "enum": [
+                                "regular",
+                                "freelance",
+                                "dry_lease"
+                            ]
+                        }
+                    }
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactPilotCategoryUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactPilotCategoryUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactRole": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                },
+                "role_code": {
+                    "type": "string"
+                },
+                "role_name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactRoleUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "required": [
+                        "role_code"
+                    ],
+                    "properties": {
+                        "role_code": {
+                            "type": "string",
+                            "enum": [
+                                "pilot",
+                                "doctor",
+                                "air_rescuer",
+                                "technician",
+                                "flight_assistant",
+                                "staff"
+                            ]
+                        }
+                    }
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactRoleUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactRoleUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactSimpleSuccessResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "count": {
+                                    "type": "integer"
+                                },
+                                "deleted": {
+                                    "type": "boolean"
+                                },
+                                "updated": {
+                                    "type": "boolean"
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactStatusUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "properties": {
+                        "is_active": {
+                            "type": "boolean"
+                        }
+                    }
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactStatusUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactStatusUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "air_rescuer": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AirRescuerProfileUpdateAttributes"
+                },
+                "doctor": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DoctorProfileUpdateAttributes"
+                },
+                "email": {
+                    "type": "string"
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "maxLength": 64
+                },
+                "first_name": {
+                    "type": "string",
+                    "maxLength": 100
+                },
+                "flight_assistant": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightAssistantProfileUpdateAttributes"
+                },
+                "is_active": {
+                    "type": "boolean"
+                },
+                "is_admin": {
+                    "type": "boolean"
+                },
+                "last_name": {
+                    "type": "string",
+                    "maxLength": 100
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "pilot": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PilotProfileUpdateAttributes"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1"
+                },
+                "role_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1",
+                        "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d2"
+                    ]
+                },
+                "sortkey": {
+                    "type": "integer"
+                },
+                "sso_email": {
+                    "type": "string"
+                },
+                "staff": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.StaffProfileUpdateAttributes"
+                },
+                "technician": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TechnicianProfileUpdateAttributes"
+                },
+                "timezone": {
+                    "type": "string",
+                    "maxLength": 64
+                },
+                "username": {
+                    "type": "string",
+                    "maxLength": 100
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "contact_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULAttributes": {
+            "type": "object",
+            "properties": {
+                "base": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULBaseRef"
+                },
+                "created_at": {
+                    "type": "string"
+                },
+                "created_by": {
+                    "type": "string"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-05-25"
+                },
+                "images": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULImage"
+                    }
+                },
+                "info": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                },
+                "no": {
+                    "type": "integer"
+                },
+                "updated_at": {
+                    "type": "string"
+                },
+                "updated_by": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULBase": {
+            "type": "object",
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "example": "hems"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "0197f3b2-c4d8-4b12-a1f9-c1de23456789"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Halim Base"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULBaseRef": {
+            "type": "object",
+            "properties": {
+                "category": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULCreateAttributes": {
+            "type": "object",
+            "required": [
+                "base_id",
+                "date",
+                "name"
+            ],
+            "properties": {
+                "base_id": {
+                    "type": "string",
+                    "example": "019e3ec1-94f6-7b6b-9cc5-1b5d05f46d74"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-05-25"
+                },
+                "file_uuid": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "info": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string",
+                    "maxLength": 128
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "dul_create",
+                        "dul"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULGroup"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 120
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        },
+                        "total_bases": {
+                            "type": "integer",
+                            "example": 8
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "deleted": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "dul_delete"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULGroup": {
+            "type": "object",
+            "properties": {
+                "base": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULBaseRef"
+                },
+                "duls": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULImage": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string"
+                },
+                "original_size_bytes": {
+                    "type": "integer"
+                },
+                "thumbnail_download_url": {
+                    "type": "string"
+                },
+                "uuid": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULGroup"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        },
+                        "total_bases": {
+                            "type": "integer",
+                            "example": 8
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULAttributes"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "base_id": {
+                    "type": "string"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-05-25"
+                },
+                "file_uuid": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "info": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "dul_update",
+                        "dul"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DoctorProfileAttributes": {
+            "type": "object",
+            "properties": {
+                "is_chief_physician": {
+                    "type": "boolean"
+                },
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "specialization": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "sub_specialization": {
+                    "type": "string",
+                    "maxLength": 120
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DoctorProfileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "is_chief_physician": {
+                    "type": "boolean"
+                },
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "specialization": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "sub_specialization": {
+                    "type": "string",
+                    "maxLength": 120
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPSendAttributes": {
+            "type": "object",
+            "required": [
+                "challenge_token"
+            ],
+            "properties": {
+                "challenge_token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPSendData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPSendAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_email_otp_send"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPSendRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPSendData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPSendResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "sent": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_email_otp_send"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPVerifyAttributes": {
+            "type": "object",
+            "required": [
+                "challenge_token",
+                "code"
+            ],
+            "properties": {
+                "challenge_token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                },
+                "code": {
+                    "type": "string",
+                    "example": "123456"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPVerifyData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPVerifyAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_email_otp_verify"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPVerifyRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPVerifyData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPVerifyResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "requires_totp_setup": {
+                                    "type": "boolean",
+                                    "example": true
+                                },
+                                "verified": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_email_otp_verify"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ErrorResponse": {
+            "type": "object",
+            "properties": {
+                "errors": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "detail": {
+                                "type": "string",
+                                "example": "email is required"
+                            },
+                            "source": {
+                                "type": "object",
+                                "properties": {
+                                    "pointer": {
+                                        "type": "string",
+                                        "example": "/data/attributes/email"
+                                    }
+                                }
+                            },
+                            "status": {
+                                "type": "string",
+                                "example": "422"
+                            },
+                            "title": {
+                                "type": "string",
+                                "example": "Validation error"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ExchangeAttributes": {
+            "type": "object",
+            "required": [
+                "access_token",
+                "id_token"
+            ],
+            "properties": {
+                "access_token": {
+                    "type": "string",
+                    "example": "eyJ0eXAiOiJKV1Qi..."
+                },
+                "id_token": {
+                    "type": "string",
+                    "example": "eyJ0eXAiOiJKV1Qi..."
+                },
+                "id_token_claims": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ExchangeIDTokenClaims"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ExchangeData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ExchangeAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_exchange"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ExchangeIDTokenClaims": {
+            "type": "object",
+            "properties": {
+                "aud": {
+                    "type": "string",
+                    "example": "12345678-1234-1234-1234-123456789012"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "andrio@mybit-innovation.com"
+                },
+                "exp": {
+                    "type": "integer",
+                    "example": 1715603600
+                },
+                "iat": {
+                    "type": "integer",
+                    "example": 1715600000
+                },
+                "iss": {
+                    "type": "string",
+                    "example": "https://login.microsoftonline.com/abc-tenant-id/v2.0"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Andrio Effendi"
+                },
+                "nbf": {
+                    "type": "integer",
+                    "example": 1715600000
+                },
+                "oid": {
+                    "type": "string",
+                    "example": "00000000-0000-0000-1234-567890abcdef"
+                },
+                "preferred_username": {
+                    "type": "string",
+                    "example": "andrio@mybit-innovation.com"
+                },
+                "sub": {
+                    "type": "string",
+                    "example": "AbCdEfGhIjKlMnOpQrStUvWxYz"
+                },
+                "tid": {
+                    "type": "string",
+                    "example": "abc-tenant-id"
+                },
+                "ver": {
+                    "type": "string",
+                    "example": "2.0"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ExchangeRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ExchangeData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportAirframeValues": {
+            "type": "object",
+            "properties": {
+                "cycles": {
+                    "type": "number",
+                    "example": 320
+                },
+                "hours": {
+                    "type": "number",
+                    "example": 1523.5
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportAttachmentItem": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string"
+                },
+                "file_id": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportAttachments": {
+            "type": "object",
+            "properties": {
+                "additional_fm_report": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAttachmentItem"
+                    }
+                },
+                "briefing": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAttachmentItem"
+                    }
+                },
+                "ofp": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAttachmentItem"
+                    }
+                },
+                "weight_balance": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAttachmentItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportAttributes": {
+            "type": "object",
+            "properties": {
+                "after_flight_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResource"
+                },
+                "completed_at": {
+                    "type": "string",
+                    "example": "2026-04-20T10:15:00Z"
+                },
+                "completed_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "engine1_gpc_n1": {
+                    "type": "string",
+                    "example": "GPC/N1 63.2"
+                },
+                "engine1_ptc_n2": {
+                    "type": "string",
+                    "example": "PTC/N2 61.8"
+                },
+                "engine2_gpc_n1": {
+                    "type": "string",
+                    "example": "GPC/N1 62.9"
+                },
+                "engine2_ptc_n2": {
+                    "type": "string",
+                    "example": "PTC/N2 61.5"
+                },
+                "fleet_status": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResource"
+                },
+                "flight": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightResource"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "flight_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionResource"
+                },
+                "flight_inspection_id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "fm_report_attachments": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAttachments"
+                },
+                "helicopter_identifier": {
+                    "type": "string",
+                    "example": "OE-TEST"
+                },
+                "helicopter_usage": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResource"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "missions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResource"
+                    }
+                },
+                "pilot_name": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "report_code": {
+                    "type": "string",
+                    "example": "EC-135-1"
+                },
+                "takeover_files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverFileResource"
+                    }
+                },
+                "takeover_id": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "usage_breakdown": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportUsageBreakdown"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportCountersValues": {
+            "type": "object",
+            "properties": {
+                "flight_reports": {
+                    "type": "number",
+                    "example": 80
+                },
+                "hook_releases": {
+                    "type": "number",
+                    "example": 10
+                },
+                "landings": {
+                    "type": "number",
+                    "example": 120
+                },
+                "rotor_brake_cycles": {
+                    "type": "number",
+                    "example": 8
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportEngineValues": {
+            "type": "object",
+            "properties": {
+                "ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "gpc_ng_n1": {
+                    "type": "number",
+                    "example": 63.2
+                },
+                "hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "ptc_nf_n2": {
+                    "type": "number",
+                    "example": 61.8
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "fm_report"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportUsageBreakdown": {
+            "type": "object",
+            "properties": {
+                "prev": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportUsageSnapshot"
+                },
+                "today": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportUsageSnapshot"
+                },
+                "total": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportUsageSnapshot"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportUsageSnapshot": {
+            "type": "object",
+            "properties": {
+                "airframe": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAirframeValues"
+                },
+                "counters": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportCountersValues"
+                },
+                "engine_1": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportEngineValues"
+                },
+                "engine_2": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportEngineValues"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityAttributes": {
+            "type": "object",
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "example": "heslo-rope-label"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "electric": {
+                    "type": "string",
+                    "example": "available"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "length": {
+                    "type": "string",
+                    "example": "10m"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Fuel Truck Rope Label"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Dry lease fuel truck"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "type": {
+                    "type": "string",
+                    "example": "Sling"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "weight": {
+                    "type": "string",
+                    "example": "10kg"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityCreateAttributes": {
+            "type": "object",
+            "required": [
+                "category",
+                "name"
+            ],
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "example": "heslo-rope-label"
+                },
+                "electric": {
+                    "type": "string",
+                    "example": "available"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "length": {
+                    "type": "string",
+                    "example": "10m"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Fuel Truck Rope Label"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Dry lease fuel truck"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "type": {
+                    "type": "string",
+                    "example": "Sling"
+                },
+                "weight": {
+                    "type": "string",
+                    "example": "10kg"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "facility_create",
+                        "facility"
+                    ],
+                    "example": "facility_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "deleted": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "facility_delete"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "facility"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "example": "heslo-rope-label"
+                },
+                "electric": {
+                    "type": "string",
+                    "example": "available"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "length": {
+                    "type": "string",
+                    "example": "10m"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Fuel Truck Rope Label"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Dry lease fuel truck"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "type": {
+                    "type": "string",
+                    "example": "Sling"
+                },
+                "weight": {
+                    "type": "string",
+                    "example": "10kg"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "facility_update",
+                        "facility"
+                    ],
+                    "example": "facility_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "land_iso_code": {
+                    "type": "string",
+                    "example": "DE"
+                },
+                "land_name": {
+                    "type": "string",
+                    "example": "Germany"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Bayern"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Central region"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateCreateAttributes": {
+            "type": "object",
+            "required": [
+                "land_id",
+                "name"
+            ],
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Bayern"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Central region"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "federal_state_create",
+                        "federal_state"
+                    ],
+                    "example": "federal_state_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "deleted": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "federal_state_delete"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "federal_state"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Bayern"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Central region"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "federal_state_update",
+                        "federal_state"
+                    ],
+                    "example": "federal_state_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightAssistantProfileAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightAssistantProfileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-09T05:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "inspection_date": {
+                    "type": "string",
+                    "example": "2026-04-09"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "Draft"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-09T05:00:00Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionCreateAttributes": {
+            "type": "object",
+            "required": [
+                "inspection_date"
+            ],
+            "properties": {
+                "inspection_date": {
+                    "type": "string",
+                    "example": "2026-04-09"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "flight_inspection_create",
+                        "flight_inspection"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "flight_inspection"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "inspection_date": {
+                    "type": "string",
+                    "example": "2026-04-09"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "InProgress"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "flight_inspection_update",
+                        "flight_inspection"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Firefighter Team A"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "On-site responders"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Firefighter Team A"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "On-site responders"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "forces_present_create",
+                        "forces_present"
+                    ],
+                    "example": "forces_present_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "forces_present"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Firefighter Team A"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "On-site responders"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "forces_present_update",
+                        "forces_present"
+                    ],
+                    "example": "forces_present_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForgotPasswordAttributes": {
+            "type": "object",
+            "required": [
+                "email"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForgotPasswordData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForgotPasswordAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_forgot_password"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForgotPasswordRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForgotPasswordData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForgotSecurityPINAttributes": {
+            "type": "object",
+            "required": [
+                "email"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForgotSecurityPINData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForgotSecurityPINAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_forgot_pin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForgotSecurityPINRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForgotSecurityPINData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.GenericDeleteAttributes": {
+            "type": "object",
+            "properties": {
+                "deleted": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.GenericDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponseData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.GenericDeleteResponseData": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "delete_result"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "hems_operation_category": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryRef"
+                },
+                "hems_operation_category_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mission": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationMissionRef"
+                },
+                "mission_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "operational_data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationOperationalDataRef"
+                },
+                "operational_data_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Firefighting"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "first"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name",
+                "type"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Firefighting"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "first",
+                        "secondary",
+                        "misuse"
+                    ],
+                    "example": "first"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hems_operation_category_create",
+                        "hems_operation_category"
+                    ],
+                    "example": "hems_operation_category_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryRef": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Firefighting"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "first"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hems_operation_category"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Firefighting"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "first",
+                        "secondary",
+                        "misuse"
+                    ],
+                    "example": "first"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hems_operation_category_update",
+                        "hems_operation_category"
+                    ],
+                    "example": "hems_operation_category_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCreateAttributes": {
+            "type": "object",
+            "required": [
+                "date"
+            ],
+            "properties": {
+                "date": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "hems_operation_category_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mission_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "operational_data_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hems_operation_create",
+                        "hems_operation"
+                    ],
+                    "example": "hems_operation_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationMissionRef": {
+            "type": "object",
+            "properties": {
+                "flight_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationOperationalDataRef": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hems_operation"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "date": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "hems_operation_category_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mission_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "operational_data_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hems_operation_update",
+                        "hems_operation"
+                    ],
+                    "example": "hems_operation_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataAttributes": {
+            "type": "object",
+            "properties": {
+                "additional_info": {
+                    "type": "string",
+                    "example": "Additional information about the operational data"
+                },
+                "altitude": {
+                    "type": "number",
+                    "example": 5.2
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "darkness": {
+                    "type": "boolean"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "false_information": {
+                    "type": "boolean"
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataFileAttributes"
+                    }
+                },
+                "fog": {
+                    "type": "boolean"
+                },
+                "force_present_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                    ]
+                },
+                "instrument_flight": {
+                    "type": "boolean"
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "landing_site_search": {
+                    "type": "boolean"
+                },
+                "location": {
+                    "type": "string",
+                    "example": "123 Main St, Anytown, USA"
+                },
+                "mountain_use": {
+                    "type": "boolean"
+                },
+                "nfo_search": {
+                    "type": "boolean"
+                },
+                "night_flight": {
+                    "type": "boolean"
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Notes about the operational data"
+                },
+                "postcode": {
+                    "type": "string",
+                    "example": "12345"
+                },
+                "precipitation": {
+                    "type": "boolean"
+                },
+                "rope_recovery": {
+                    "type": "boolean"
+                },
+                "state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "temperature": {
+                    "type": "number",
+                    "example": 23.5
+                },
+                "terrain_index": {
+                    "type": "string",
+                    "example": "Only helicopter landing"
+                },
+                "time": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "vocation_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "wind": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataCreateAttributes": {
+            "type": "object",
+            "required": [
+                "location",
+                "time"
+            ],
+            "properties": {
+                "additional_info": {
+                    "type": "string",
+                    "example": "Additional information about the operational data"
+                },
+                "altitude": {
+                    "type": "number",
+                    "example": 5.2
+                },
+                "darkness": {
+                    "type": "boolean"
+                },
+                "false_information": {
+                    "type": "boolean"
+                },
+                "file_attachment_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                    ]
+                },
+                "fog": {
+                    "type": "boolean"
+                },
+                "force_present_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                    ]
+                },
+                "instrument_flight": {
+                    "type": "boolean"
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "landing_site_search": {
+                    "type": "boolean"
+                },
+                "location": {
+                    "type": "string",
+                    "example": "123 Main St, Anytown, USA"
+                },
+                "mountain_use": {
+                    "type": "boolean"
+                },
+                "nfo_search": {
+                    "type": "boolean"
+                },
+                "night_flight": {
+                    "type": "boolean"
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Notes about the operational data"
+                },
+                "postcode": {
+                    "type": "string",
+                    "example": "12345"
+                },
+                "precipitation": {
+                    "type": "boolean"
+                },
+                "rope_recovery": {
+                    "type": "boolean"
+                },
+                "state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "temperature": {
+                    "type": "number",
+                    "example": 23.5
+                },
+                "terrain_index": {
+                    "type": "string",
+                    "example": "Only helicopter landing"
+                },
+                "time": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "vocation_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "wind": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hems_operational_data_create",
+                        "hems_operational_data"
+                    ],
+                    "example": "hems_operational_data_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataFileAttributes": {
+            "type": "object",
+            "properties": {
+                "file_attachment_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hems_operational_data"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "additional_info": {
+                    "type": "string",
+                    "example": "Additional information about the operational data"
+                },
+                "altitude": {
+                    "type": "number",
+                    "example": 5.2
+                },
+                "darkness": {
+                    "type": "boolean"
+                },
+                "false_information": {
+                    "type": "boolean"
+                },
+                "file_attachment_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "fog": {
+                    "type": "boolean"
+                },
+                "force_present_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "instrument_flight": {
+                    "type": "boolean"
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "landing_site_search": {
+                    "type": "boolean"
+                },
+                "location": {
+                    "type": "string",
+                    "example": "123 Main St, Anytown, USA"
+                },
+                "mountain_use": {
+                    "type": "boolean"
+                },
+                "nfo_search": {
+                    "type": "boolean"
+                },
+                "night_flight": {
+                    "type": "boolean"
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Notes about the operational data"
+                },
+                "postcode": {
+                    "type": "string",
+                    "example": "12345"
+                },
+                "precipitation": {
+                    "type": "boolean"
+                },
+                "rope_recovery": {
+                    "type": "boolean"
+                },
+                "state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "temperature": {
+                    "type": "number",
+                    "example": 23.5
+                },
+                "terrain_index": {
+                    "type": "string",
+                    "example": "Only helicopter landing"
+                },
+                "time": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "vocation_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "wind": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hems_operational_data_update",
+                        "hems_operational_data"
+                    ],
+                    "example": "hems_operational_data_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Main Street 10"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@abc-insurance.local"
+                },
+                "federal_state": {
+                    "type": "string",
+                    "example": "Bayern"
+                },
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "land_iso_code": {
+                    "type": "string",
+                    "example": "DE"
+                },
+                "land_name": {
+                    "type": "string",
+                    "example": "Germany"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+4912345678"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "ABC Insurance"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Preferred insurance provider"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "state": {
+                    "type": "string",
+                    "example": "Berlin"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Main Street 10"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@abc-insurance.local"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+4912345678"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "ABC Insurance"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Preferred insurance provider"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "state": {
+                    "type": "string",
+                    "example": "Berlin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "health_insurance_company_create",
+                        "health_insurance_company"
+                    ],
+                    "example": "health_insurance_company_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "health_insurance_company"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Main Street 10"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@abc-insurance.local"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+4912345678"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "ABC Insurance"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Preferred insurance provider"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "state": {
+                    "type": "string",
+                    "example": "Berlin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "health_insurance_company_update",
+                        "health_insurance_company"
+                    ],
+                    "example": "health_insurance_company_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "total_airframe_cycles": {
+                    "type": "number",
+                    "example": 320
+                },
+                "total_airframe_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_1_ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "total_engine_1_gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "total_engine_1_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_1_ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                },
+                "total_engine_2_ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "total_engine_2_gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "total_engine_2_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_2_ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                },
+                "total_flight_report": {
+                    "type": "number",
+                    "example": 80
+                },
+                "total_hook_release": {
+                    "type": "number",
+                    "example": 10
+                },
+                "total_landing": {
+                    "type": "number",
+                    "example": 120
+                },
+                "total_rotor_brake_cycle": {
+                    "type": "number",
+                    "example": 8
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageCreateAttributes": {
+            "type": "object",
+            "required": [
+                "helicopter_id"
+            ],
+            "properties": {
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "total_airframe_cycles": {
+                    "type": "number",
+                    "example": 320
+                },
+                "total_airframe_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_1_ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "total_engine_1_gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "total_engine_1_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_1_ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                },
+                "total_engine_2_ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "total_engine_2_gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "total_engine_2_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_2_ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                },
+                "total_flight_report": {
+                    "type": "number",
+                    "example": 80
+                },
+                "total_hook_release": {
+                    "type": "number",
+                    "example": 10
+                },
+                "total_landing": {
+                    "type": "number",
+                    "example": 120
+                },
+                "total_rotor_brake_cycle": {
+                    "type": "number",
+                    "example": 8
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_usage_create",
+                        "helicopter_usage"
+                    ],
+                    "example": "helicopter_usage_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter_usage"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "total_airframe_cycles": {
+                    "type": "number",
+                    "example": 320
+                },
+                "total_airframe_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_1_ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "total_engine_1_gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "total_engine_1_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_1_ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                },
+                "total_engine_2_ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "total_engine_2_gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "total_engine_2_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_2_ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                },
+                "total_flight_report": {
+                    "type": "number",
+                    "example": 80
+                },
+                "total_hook_release": {
+                    "type": "number",
+                    "example": 10
+                },
+                "total_landing": {
+                    "type": "number",
+                    "example": 120
+                },
+                "total_rotor_brake_cycle": {
+                    "type": "number",
+                    "example": 8
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_usage_update",
+                        "helicopter_usage"
+                    ],
+                    "example": "helicopter_usage_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Jl. Merdeka No. 10"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@hospital.local"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "0211234567"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "08123456789"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "RSUD Kota"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Nearest trauma center"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Jl. Merdeka No. 10"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@hospital.local"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "0211234567"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "08123456789"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "RSUD Kota"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Nearest trauma center"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hospital_create",
+                        "hospital"
+                    ],
+                    "example": "hospital_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hospital"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Jl. Merdeka No. 10"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@hospital.local"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "0211234567"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "08123456789"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "RSUD Kota"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Nearest trauma center"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hospital_update",
+                        "hospital"
+                    ],
+                    "example": "hospital_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Muehlenstrasse 1"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "ops@example.local"
+                },
+                "federal_state": {
+                    "type": "string",
+                    "example": "Bayern"
+                },
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "icao_code": {
+                    "type": "string",
+                    "example": "EDDB"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "land_iso_code": {
+                    "type": "string",
+                    "example": "DE"
+                },
+                "land_name": {
+                    "type": "string",
+                    "example": "Germany"
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "030123456"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "0170123456"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Berlin Base"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Night operations supported"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOCreateAttributes": {
+            "type": "object",
+            "required": [
+                "icao_code"
+            ],
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Muehlenstrasse 1"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "ops@example.local"
+                },
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "icao_code": {
+                    "type": "string",
+                    "example": "EDDB"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "030123456"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "0170123456"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Berlin Base"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Night operations supported"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "icao_create",
+                        "icao"
+                    ],
+                    "example": "icao_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAODataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "icao"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Muehlenstrasse 1"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "ops@example.local"
+                },
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "icao_code": {
+                    "type": "string",
+                    "example": "EDDB"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "030123456"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "0170123456"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Berlin Base"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Night operations supported"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "icao_update",
+                        "icao"
+                    ],
+                    "example": "icao_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "federal_state": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataFederalState"
+                },
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "health_insurance_companies_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "health_insurance_company": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataHealthInsuranceCompany"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataCreateAttributes": {
+            "type": "object",
+            "required": [
+                "federal_state_id",
+                "health_insurance_companies_id"
+            ],
+            "properties": {
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "health_insurance_companies_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "insurance_patient_data_create",
+                        "insurance_patient_data"
+                    ],
+                    "example": "insurance_patient_data_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataFederalState": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Bayern"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataHealthInsuranceCompany": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Main Street 10"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@abc-insurance.local"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+4912345678"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "ABC Insurance"
+                },
+                "state": {
+                    "type": "string",
+                    "example": "Berlin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "insurance_patient_data"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "health_insurance_companies_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "insurance_patient_data_update",
+                        "insurance_patient_data"
+                    ],
+                    "example": "insurance_patient_data_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InviteAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "first_name",
+                "last_name",
+                "role_id",
+                "username"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "role_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "[\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d\"",
+                        "\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e\"]"
+                    ]
+                },
+                "username": {
+                    "type": "string",
+                    "maxLength": 100,
+                    "minLength": 3,
+                    "example": "john.doe"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InviteData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InviteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_invite"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InviteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InviteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandAttributes": {
+            "type": "object",
+            "properties": {
+                "bmd_export_id": {
+                    "type": "string",
+                    "example": "DE001"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "federal_state_list": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.LandFederalStateDTO"
+                    }
+                },
+                "federal_state_total": {
+                    "type": "integer",
+                    "example": 2
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "iso_code": {
+                    "type": "string",
+                    "example": "DE"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Germany"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Central Europe"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "bmd_export_id": {
+                    "type": "string",
+                    "example": "DE001"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "iso_code": {
+                    "type": "string",
+                    "example": "DE"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Germany"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Central Europe"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LandCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "land_create",
+                        "land"
+                    ],
+                    "example": "land_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LandCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.LandResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandFederalStateDTO": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Bayern"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.LandResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LandAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "land"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LandResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "bmd_export_id": {
+                    "type": "string",
+                    "example": "DE001"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "iso_code": {
+                    "type": "string",
+                    "example": "DE"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Germany"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Central Europe"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LandUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "land_update",
+                        "land"
+                    ],
+                    "example": "land_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LandUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LoginAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "password"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "password": {
+                    "type": "string",
+                    "example": "StrongP@ssw0rd"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LoginData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LoginAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_login"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LoginEmailOTPRequiredResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "challenge_token": {
+                                    "type": "string",
+                                    "example": "kP8k2..."
+                                },
+                                "linked_sso": {
+                                    "type": "boolean",
+                                    "example": false
+                                },
+                                "max_resend_per_hour": {
+                                    "type": "integer",
+                                    "example": 5
+                                },
+                                "pin_configured": {
+                                    "type": "boolean",
+                                    "example": false
+                                },
+                                "requires_email_otp": {
+                                    "type": "boolean",
+                                    "example": true
+                                },
+                                "requires_totp_setup": {
+                                    "type": "boolean",
+                                    "example": true
+                                },
+                                "resend_cooldown_seconds": {
+                                    "type": "integer",
+                                    "example": 60
+                                },
+                                "webauthn_configured": {
+                                    "type": "boolean",
+                                    "example": false
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_email_otp_required"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LoginRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LoginData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LoginTOTPRequiredResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "challenge_token": {
+                                    "type": "string",
+                                    "example": "kP8k2..."
+                                },
+                                "email_otp_challenge_token": {
+                                    "type": "string",
+                                    "example": "qA9j1..."
+                                },
+                                "email_otp_enabled": {
+                                    "type": "boolean",
+                                    "example": false
+                                },
+                                "email_otp_max_resend_per_hour": {
+                                    "type": "integer",
+                                    "example": 5
+                                },
+                                "email_otp_resend_cooldown_seconds": {
+                                    "type": "integer",
+                                    "example": 60
+                                },
+                                "linked_sso": {
+                                    "type": "boolean",
+                                    "example": false
+                                },
+                                "pin_configured": {
+                                    "type": "boolean",
+                                    "example": false
+                                },
+                                "requires_totp": {
+                                    "type": "boolean",
+                                    "example": true
+                                },
+                                "totp_enabled": {
+                                    "type": "boolean",
+                                    "example": true
+                                },
+                                "webauthn_configured": {
+                                    "type": "boolean",
+                                    "example": false
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_totp_required"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineAttributes": {
+            "type": "object",
+            "properties": {
+                "column": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "medicine_group": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupResource"
+                },
+                "medicine_group_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "motor_reaction": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResource"
+                },
+                "motor_reaction_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "motor_reaction_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                    ]
+                },
+                "motor_reactions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResource"
+                    }
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Paracetamol"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Main stock medicine"
+                },
+                "pack": {
+                    "type": "string",
+                    "example": "500mg"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "unit": {
+                    "type": "string",
+                    "example": "tablet"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "column": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "medicine_group_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "motor_reaction_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "motor_reaction_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                    ]
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Paracetamol"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Main stock medicine"
+                },
+                "pack": {
+                    "type": "string",
+                    "example": "500mg"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "unit": {
+                    "type": "string",
+                    "maxLength": 50,
+                    "example": "tablet"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "medicine_create",
+                        "medicine"
+                    ],
+                    "example": "medicine_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Spritze"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Spritze"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "medicine_group_create",
+                        "medicine_group"
+                    ],
+                    "example": "medicine_group_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "medicine_group"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Spritze"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "medicine_group_update",
+                        "medicine_group"
+                    ],
+                    "example": "medicine_group_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "medicine"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "column": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "medicine_group_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "motor_reaction_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "motor_reaction_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                    ]
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Paracetamol"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Main stock medicine"
+                },
+                "pack": {
+                    "type": "string",
+                    "example": "500mg"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "unit": {
+                    "type": "string",
+                    "maxLength": 50,
+                    "example": "tablet"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "medicine_update",
+                        "medicine"
+                    ],
+                    "example": "medicine_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MicrosoftCallbackResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "email": {
+                                    "type": "string",
+                                    "example": "user@example.com"
+                                },
+                                "provider": {
+                                    "type": "string",
+                                    "example": "microsoft"
+                                },
+                                "provider_subject": {
+                                    "type": "string",
+                                    "example": "00000000-0000-0000-0000-000000000000"
+                                }
+                            }
+                        },
+                        "id": {
+                            "type": "string",
+                            "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_identity"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MicrosoftLoginResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "redirect_url": {
+                                    "type": "string",
+                                    "example": "https://login.microsoftonline.com/..."
+                                },
+                                "url": {
+                                    "type": "string",
+                                    "example": "https://login.microsoftonline.com/..."
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_microsoft_url"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "gezielt auf Schmerzreiz"
+                },
+                "score": {
+                    "type": "integer",
+                    "example": 5
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "gezielt auf Schmerzreiz"
+                },
+                "score": {
+                    "type": "integer",
+                    "example": 5
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "motor_reaction_create",
+                        "motor_reaction"
+                    ],
+                    "example": "motor_reaction_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "motor_reaction"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "gezielt auf Schmerzreiz"
+                },
+                "score": {
+                    "type": "integer",
+                    "example": 5
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "motor_reaction_update",
+                        "motor_reaction"
+                    ],
+                    "example": "motor_reaction_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Primary operation control center"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Main OPC Base"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcCreateAttributes": {
+            "type": "object",
+            "required": [
+                "title"
+            ],
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Primary operation control center"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Main OPC Base"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "opc_create",
+                        "opc"
+                    ],
+                    "example": "opc_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "opc"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Primary operation control center"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Main OPC Base"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "opc_update",
+                        "opc"
+                    ],
+                    "example": "opc_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataAttributes": {
+            "type": "object",
+            "properties": {
+                "age": {
+                    "type": "integer",
+                    "example": 35
+                },
+                "birth_date": {
+                    "type": "string",
+                    "example": "1990-01-15"
+                },
+                "co_insured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "max.muster@example.com"
+                },
+                "family_name": {
+                    "type": "string",
+                    "example": "Muster"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "Max"
+                },
+                "gender": {
+                    "type": "string",
+                    "example": "male"
+                },
+                "insurance_patient_data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataInsuranceDetail"
+                },
+                "insurance_patient_data_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "opc": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataOPC"
+                },
+                "opc_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "phone": {
+                    "type": "string",
+                    "example": "+431234567"
+                },
+                "street": {
+                    "type": "string",
+                    "example": "Hauptstraße 1"
+                },
+                "svnr": {
+                    "type": "string",
+                    "example": "1234150190"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataCreateAttributes": {
+            "type": "object",
+            "required": [
+                "family_name",
+                "first_name",
+                "gender"
+            ],
+            "properties": {
+                "birth_date": {
+                    "type": "string",
+                    "example": "1990-01-15"
+                },
+                "co_insured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "email": {
+                    "type": "string",
+                    "example": "max.muster@example.com"
+                },
+                "family_name": {
+                    "type": "string",
+                    "example": "Muster"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "Max"
+                },
+                "gender": {
+                    "type": "string",
+                    "enum": [
+                        "male",
+                        "female"
+                    ],
+                    "example": "male"
+                },
+                "insurance_patient_data_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "opc_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "phone": {
+                    "type": "string",
+                    "example": "+431234567"
+                },
+                "street": {
+                    "type": "string",
+                    "example": "Hauptstraße 1"
+                },
+                "svnr": {
+                    "type": "string",
+                    "example": "1234150190"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "patient_data_create",
+                        "patient_data"
+                    ],
+                    "example": "patient_data_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataInsuranceDetail": {
+            "type": "object",
+            "properties": {
+                "federal_state": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataFederalState"
+                },
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "health_insurance_companies_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "health_insurance_company": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataHealthInsuranceCompany"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataOPC": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Primary OPC"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "patient_data"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "birth_date": {
+                    "type": "string",
+                    "example": "1990-01-15"
+                },
+                "co_insured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "email": {
+                    "type": "string",
+                    "example": "max.muster@example.com"
+                },
+                "family_name": {
+                    "type": "string",
+                    "example": "Muster"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "Max"
+                },
+                "gender": {
+                    "type": "string",
+                    "example": "male"
+                },
+                "insurance_patient_data_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "opc_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "phone": {
+                    "type": "string",
+                    "example": "+431234567"
+                },
+                "street": {
+                    "type": "string",
+                    "example": "Hauptstraße 1"
+                },
+                "svnr": {
+                    "type": "string",
+                    "example": "1234150190"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "patient_data_update",
+                        "patient_data"
+                    ],
+                    "example": "patient_data_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                },
+                "description": {
+                    "type": "string",
+                    "example": "Allows managing users."
+                },
+                "key": {
+                    "type": "string",
+                    "example": "user.manage"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "User Management"
+                },
+                "requires_pin": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionGroupResource": {
+            "type": "object",
+            "properties": {
+                "module": {
+                    "type": "string",
+                    "example": "dul"
+                },
+                "module_label": {
+                    "type": "string",
+                    "example": "DUL"
+                },
+                "permissions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionGroupedResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionGroupResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionMini": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "example": "Permission to view users."
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9a"
+                },
+                "key": {
+                    "type": "string",
+                    "example": "users.read"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "View Users"
+                },
+                "requires_pin": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "permission"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionUpdateAttributes": {
+            "type": "object",
+            "required": [
+                "requires_pin"
+            ],
+            "properties": {
+                "requires_pin": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "permission_update",
+                        "permission"
+                    ],
+                    "example": "permission_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PilotProfileAttributes": {
+            "type": "object",
+            "properties": {
+                "double_command_minutes": {
+                    "type": "integer"
+                },
+                "dul_base": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULBase"
+                    }
+                },
+                "flight_instructor_minutes": {
+                    "type": "integer"
+                },
+                "has_ifr_qualification": {
+                    "type": "boolean"
+                },
+                "ifr_flight_minutes": {
+                    "type": "integer"
+                },
+                "is_chief_pilot": {
+                    "type": "boolean"
+                },
+                "license_expired_at": {
+                    "type": "string"
+                },
+                "license_issued_at": {
+                    "type": "string"
+                },
+                "license_no": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "night_flight_minutes": {
+                    "type": "integer"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "pilot_category": {
+                    "type": "string",
+                    "enum": [
+                        "regular",
+                        "freelance",
+                        "dry_lease"
+                    ]
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "responsible_pilot_minutes": {
+                    "type": "integer"
+                },
+                "second_pilot_minutes": {
+                    "type": "integer"
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "technician_license_no": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "total_flight_minutes": {
+                    "type": "integer"
+                },
+                "weight_kg": {
+                    "type": "number"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PilotProfileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "double_command_minutes": {
+                    "type": "integer"
+                },
+                "dul_base": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULBase"
+                    }
+                },
+                "flight_instructor_minutes": {
+                    "type": "integer"
+                },
+                "has_ifr_qualification": {
+                    "type": "boolean"
+                },
+                "ifr_flight_minutes": {
+                    "type": "integer"
+                },
+                "is_chief_pilot": {
+                    "type": "boolean"
+                },
+                "license_expired_at": {
+                    "type": "string"
+                },
+                "license_issued_at": {
+                    "type": "string"
+                },
+                "license_no": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "night_flight_minutes": {
+                    "type": "integer"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "pilot_category": {
+                    "type": "string",
+                    "enum": [
+                        "regular",
+                        "freelance",
+                        "dry_lease"
+                    ]
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "responsible_pilot_minutes": {
+                    "type": "integer"
+                },
+                "second_pilot_minutes": {
+                    "type": "integer"
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "technician_license_no": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "total_flight_minutes": {
+                    "type": "integer"
+                },
+                "weight_kg": {
+                    "type": "number"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ReauthAttributes": {
+            "type": "object",
+            "required": [
+                "method"
+            ],
+            "properties": {
+                "method": {
+                    "type": "string",
+                    "enum": [
+                        "pin",
+                        "password"
+                    ],
+                    "example": "pin"
+                },
+                "password": {
+                    "type": "string",
+                    "minLength": 1,
+                    "example": "StrongP@ssw0rd"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RegisterAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "first_name",
+                "last_name",
+                "password",
+                "username"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "password": {
+                    "type": "string",
+                    "minLength": 8,
+                    "example": "StrongP@ssw0rd"
+                },
+                "username": {
+                    "type": "string",
+                    "maxLength": 100,
+                    "minLength": 3,
+                    "example": "john.doe"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RegisterData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RegisterAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_register"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RegisterRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RegisterData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RequestSecurityPINAttributes": {
+            "type": "object",
+            "properties": {
+                "method": {
+                    "type": "string",
+                    "example": "password"
+                },
+                "password": {
+                    "type": "string",
+                    "example": "StrongP@ssw0rd"
+                },
+                "reauth_token": {
+                    "type": "string",
+                    "example": "sso_reauth_1234567890abcdef"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RequestSecurityPINData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RequestSecurityPINAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_pin_request_reset"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RequestSecurityPINRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RequestSecurityPINData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RequestSecurityPINResetResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "message": {
+                                    "type": "string",
+                                    "example": "If allowed, a security PIN reset link has been sent to your email."
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_pin_request_reset"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResendSetPasswordInviteAttributes": {
+            "type": "object",
+            "required": [
+                "user_id"
+            ],
+            "properties": {
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResendSetPasswordInviteData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ResendSetPasswordInviteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_resend_set_password"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResendSetPasswordInviteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ResendSetPasswordInviteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResetPasswordAttributes": {
+            "type": "object",
+            "required": [
+                "confirm_password",
+                "new_password",
+                "token"
+            ],
+            "properties": {
+                "confirm_password": {
+                    "type": "string",
+                    "minLength": 8,
+                    "example": "StrongP@ssw0rd!LongPassphrase"
+                },
+                "new_password": {
+                    "type": "string",
+                    "minLength": 8,
+                    "example": "StrongP@ssw0rd!LongPassphrase"
+                },
+                "token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResetPasswordData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ResetPasswordAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_reset_password"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResetPasswordRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ResetPasswordData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResetSecurityPINAttributes": {
+            "type": "object",
+            "required": [
+                "confirm_pin",
+                "new_pin"
+            ],
+            "properties": {
+                "confirm_pin": {
+                    "type": "string",
+                    "example": "123456"
+                },
+                "method": {
+                    "type": "string",
+                    "example": "password"
+                },
+                "new_pin": {
+                    "type": "string",
+                    "example": "123456"
+                },
+                "password": {
+                    "type": "string",
+                    "example": "StrongP@ssw0rd"
+                },
+                "reauth_token": {
+                    "type": "string",
+                    "example": "sso_reauth_1234567890abcdef"
+                },
+                "token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResetSecurityPINData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ResetSecurityPINAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_reset_pin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResetSecurityPINRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ResetSecurityPINData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "description": {
+                    "type": "string",
+                    "example": "Full access to all resources."
+                },
+                "name": {
+                    "type": "string",
+                    "example": "admin"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "example": "Full access to all resources."
+                },
+                "name": {
+                    "type": "string",
+                    "example": "admin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "role_create",
+                        "role"
+                    ],
+                    "example": "role_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleMini": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "example": "Full access to all resources."
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "admin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionAssignAttributes": {
+            "type": "object",
+            "required": [
+                "permission_id"
+            ],
+            "properties": {
+                "permission_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionAssignBulkData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionBulkAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role_assign_permission_bulk"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionAssignBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignBulkData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionAssignData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role_permission"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionAssignRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionAttributes": {
+            "type": "object",
+            "properties": {
+                "permission_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionBulkAttributes": {
+            "type": "object",
+            "required": [
+                "permission_ids"
+            ],
+            "properties": {
+                "permission_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "[\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e\"",
+                        "\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f\"]"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionRemoveBulkData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionBulkAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role_remove_permission_bulk"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionRemoveBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionRemoveBulkData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role_permission"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "permissions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionResource"
+                    }
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "example": "Full access to all resources."
+                },
+                "name": {
+                    "type": "string",
+                    "example": "admin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "role_update",
+                        "role"
+                    ],
+                    "example": "role_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOLinkAttributes": {
+            "type": "object",
+            "required": [
+                "code",
+                "provider"
+            ],
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "0.AXkA..."
+                },
+                "provider": {
+                    "type": "string",
+                    "example": "microsoft"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOLinkData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOLinkAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_sso_link"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOLinkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOLinkData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOLinkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "email": {
+                                    "type": "string",
+                                    "example": "user@example.com"
+                                },
+                                "provider": {
+                                    "type": "string",
+                                    "example": "microsoft"
+                                },
+                                "provider_subject": {
+                                    "type": "string",
+                                    "example": "00000000-0000-0000-0000-000000000000"
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_sso_link"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOUnlinkAttributes": {
+            "type": "object",
+            "required": [
+                "provider"
+            ],
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "example": "microsoft"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOUnlinkData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOUnlinkAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_sso_unlink"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOUnlinkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOUnlinkData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOUnlinkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "provider": {
+                                    "type": "string",
+                                    "example": "microsoft"
+                                },
+                                "unlinked": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_sso_unlink"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINChangeAttributes": {
+            "type": "object",
+            "required": [
+                "confirm_pin",
+                "current_pin",
+                "new_pin"
+            ],
+            "properties": {
+                "confirm_pin": {
+                    "type": "string",
+                    "example": "654321"
+                },
+                "current_pin": {
+                    "type": "string",
+                    "example": "123456"
+                },
+                "new_pin": {
+                    "type": "string",
+                    "example": "654321"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINChangeData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINChangeAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_pin_change"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINChangeRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINChangeData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINSetupAttributes": {
+            "type": "object",
+            "required": [
+                "confirm_pin",
+                "pin"
+            ],
+            "properties": {
+                "confirm_pin": {
+                    "type": "string",
+                    "example": "123456"
+                },
+                "pin": {
+                    "type": "string",
+                    "example": "123456"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINSetupData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINSetupAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_pin_setup"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINSetupRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINSetupData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINSetupResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "configured": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_pin_setup"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINVerifyAttributes": {
+            "type": "object",
+            "required": [
+                "action",
+                "pin"
+            ],
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "example": "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"
+                },
+                "pin": {
+                    "type": "string",
+                    "example": "123456"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINVerifyData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINVerifyAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_pin_verify"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINVerifyRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINVerifyData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINVerifyResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "action_token": {
+                                    "type": "string",
+                                    "example": "pinv_1234567890abcdef"
+                                },
+                                "action_token_ttl_ms": {
+                                    "type": "integer",
+                                    "example": 900000
+                                },
+                                "verified": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_pin_verify"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SetPasswordAttributes": {
+            "type": "object",
+            "required": [
+                "password",
+                "token"
+            ],
+            "properties": {
+                "password": {
+                    "type": "string",
+                    "minLength": 8,
+                    "example": "StrongP@ssw0rd"
+                },
+                "token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SetPasswordData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SetPasswordAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_set_password"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SetPasswordRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SetPasswordData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.StaffProfileAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "role_label": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.StaffProfileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "role_label": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPConfirmAttributes": {
+            "type": "object",
+            "required": [
+                "code",
+                "user_id"
+            ],
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "123456"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPConfirmData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPConfirmAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_confirm"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPConfirmRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPConfirmData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPDisableAttributes": {
+            "type": "object",
+            "required": [
+                "user_id"
+            ],
+            "properties": {
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPDisableData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPDisableAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_disable"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPDisableRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPDisableData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPResetSetupData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ReauthAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_reset_setup"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPResetSetupRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPResetSetupData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPSetupAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "user_id"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPSetupData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPSetupAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_setup"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPSetupRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPSetupData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPSetupResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "issuer": {
+                                    "type": "string",
+                                    "example": "Wucher"
+                                },
+                                "otpauth_url": {
+                                    "type": "string",
+                                    "example": "otpauth://totp/Wucher:user@example.com?..."
+                                },
+                                "secret": {
+                                    "type": "string",
+                                    "example": "JBSWY3DPEHPK3PXP"
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_totp_setup"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPVerifyAttributes": {
+            "type": "object",
+            "required": [
+                "challenge_token",
+                "code"
+            ],
+            "properties": {
+                "challenge_token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                },
+                "code": {
+                    "type": "string",
+                    "example": "123456"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPVerifyData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPVerifyAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_verify"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPVerifyRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPVerifyData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TechnicianProfileAttributes": {
+            "type": "object",
+            "properties": {
+                "is_chief_technician": {
+                    "type": "boolean"
+                },
+                "is_responsible_complaints": {
+                    "type": "boolean"
+                },
+                "license_no": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TechnicianProfileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "is_chief_technician": {
+                    "type": "boolean"
+                },
+                "is_responsible_complaints": {
+                    "type": "boolean"
+                },
+                "license_no": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TimezoneUpdateAttributes": {
+            "type": "object",
+            "required": [
+                "timezone"
+            ],
+            "properties": {
+                "timezone": {
+                    "type": "string",
+                    "example": "Asia/Jakarta"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TimezoneUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TimezoneUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_timezone_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TimezoneUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TimezoneUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TokenResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "access_expires_in": {
+                                    "type": "integer",
+                                    "example": 900
+                                },
+                                "refresh_expires_in": {
+                                    "type": "integer",
+                                    "example": 2592000
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_tokens"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserAttributes": {
+            "type": "object",
+            "properties": {
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "email_verified_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "is_previously_configured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "linked_sso": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "pin_configured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "profile_picture": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserImage"
+                },
+                "role": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleMini"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "role_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "[\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d\"",
+                        "\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e\"]"
+                    ]
+                },
+                "roles": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleMini"
+                    }
+                },
+                "timezone": {
+                    "type": "string",
+                    "example": "Asia/Jakarta"
+                },
+                "totp_enabled": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "username": {
+                    "type": "string",
+                    "example": "john.doe"
+                },
+                "webauthn_configured": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserCreateAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "first_name",
+                "last_name",
+                "role_id",
+                "username"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "image_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "role_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "[\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d\"",
+                        "\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e\"]"
+                    ]
+                },
+                "timezone": {
+                    "type": "string",
+                    "example": "Asia/Jakarta"
+                },
+                "username": {
+                    "type": "string",
+                    "maxLength": 100,
+                    "minLength": 3,
+                    "example": "john.doe"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "user_create",
+                        "user"
+                    ],
+                    "example": "user_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserFoto": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/base/lude.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Expires=900\u0026X-Amz-Signature=abc123"
+                },
+                "original_size_bytes": {
+                    "type": "integer",
+                    "example": 1024000
+                },
+                "thumbnail_download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/base/lude.thumb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Expires=900\u0026X-Amz-Signature=abc123"
+                },
+                "uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserImage": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://example.com/presigned-url"
+                },
+                "original_size_bytes": {
+                    "type": "integer",
+                    "example": 1024000
+                },
+                "thumbnail_download_url": {
+                    "type": "string",
+                    "example": "https://example.com/presigned-thumb-url"
+                },
+                "uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "user"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserAttributes"
+                        },
+                        "id": {
+                            "type": "string",
+                            "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "user"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "image_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "timezone": {
+                    "type": "string",
+                    "example": "Asia/Jakarta"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "user_update",
+                        "user"
+                    ],
+                    "example": "user_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VerifyEmailResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "verified": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_verify_email"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Pilot"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Helicopter pilot vocation"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Pilot"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Helicopter pilot vocation"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "vocation_create",
+                        "vocation"
+                    ],
+                    "example": "vocation_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "vocation"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Pilot"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Helicopter pilot vocation"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "vocation_update",
+                        "vocation"
+                    ],
+                    "example": "vocation_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnBeginResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "challenge_token": {
+                                    "type": "string",
+                                    "example": "kP8k2..."
+                                },
+                                "challenge_ttl_ms": {
+                                    "type": "integer",
+                                    "example": 300000
+                                },
+                                "public_key": {
+                                    "type": "object",
+                                    "additionalProperties": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_webauthn_register_options"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnLoginBeginAttributes": {
+            "type": "object",
+            "required": [
+                "email"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnLoginBeginData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginBeginAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_webauthn_login_begin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnLoginBeginRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginBeginData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnLoginFinishAttributes": {
+            "type": "object",
+            "required": [
+                "challenge_token",
+                "credential"
+            ],
+            "properties": {
+                "challenge_token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                },
+                "credential": {
+                    "type": "array",
+                    "items": {
+                        "type": "integer"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnLoginFinishData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginFinishAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_webauthn_login_finish"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnLoginFinishRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginFinishData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnRegisterBeginData": {
+            "type": "object",
+            "required": [
+                "type"
+            ],
+            "properties": {
+                "type": {
+                    "type": "string",
+                    "example": "auth_webauthn_register_begin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnRegisterBeginRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterBeginData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnRegisterFinishAttributes": {
+            "type": "object",
+            "required": [
+                "challenge_token",
+                "credential"
+            ],
+            "properties": {
+                "challenge_token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                },
+                "credential": {
+                    "type": "array",
+                    "items": {
+                        "type": "integer"
+                    }
+                },
+                "name": {
+                    "type": "string",
+                    "maxLength": 100,
+                    "example": "MacBook Touch ID"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnRegisterFinishData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterFinishAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_webauthn_register_finish"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnRegisterFinishRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterFinishData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnResetSetupData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ReauthAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_webauthn_reset_setup"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnResetSetupRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnResetSetupData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnResetSetupResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "reset": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_webauthn_reset_setup"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ActionSignoffSignAttributes": {
+            "type": "object",
+            "properties": {
+                "complaint_id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "flight_id": {
+                    "description": "FlightID — REQUIRED for the fleet (complaint-independent) sign-off; scopes it to a\nflight so it no longer leaks across takeovers of the same aircraft. Ignored when\ncomplaint_id is set (that sign-off is keyed by the complaint).",
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "sign": {
+                    "description": "Sign toggles the sign-off: true (or omitted) signs it, false unsigns (clears the\nsignature). Combine with complaint_id to toggle a specific complaint's sign-off.",
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ActionSignoffSignData": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ActionSignoffSignAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "action_signoff"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ActionSignoffSignRequest": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ActionSignoffSignData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateAttributes": {
+            "type": "object",
+            "required": [
+                "base_id",
+                "checklists"
+            ],
+            "properties": {
+                "base_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "checklists": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateEntry"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "air_rescuer_checklist_create"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateEntry": {
+            "type": "object",
+            "required": [
+                "scope_code",
+                "title"
+            ],
+            "properties": {
+                "items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistItemInput"
+                    }
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "scope_code": {
+                    "type": "string",
+                    "example": "MO"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Monday Checklist"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateAttributes": {
+            "type": "object",
+            "required": [
+                "items"
+            ],
+            "properties": {
+                "items": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistItemInput"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "air_rescuer_checklist_item_create"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderAttributes": {
+            "type": "object",
+            "required": [
+                "items"
+            ],
+            "properties": {
+                "items": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderEntry"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "air_rescuer_checklist_item_reorder"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderEntry": {
+            "type": "object",
+            "required": [
+                "item_uuid",
+                "position"
+            ],
+            "properties": {
+                "item_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 2
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Check radio"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 2
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "air_rescuer_checklist_item_update"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "new_items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistItemInput"
+                    }
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "scope_code": {
+                    "type": "string",
+                    "example": "MO"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Monday Checklist Updated"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "air_rescuer_checklist_update"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintActionTakenAttributes": {
+            "type": "object",
+            "properties": {
+                "action_taken": {
+                    "description": "ActionTaken — corrective action text. Required when recording (create); on update an\nempty value clears it (allowed only while the action has not been signed off).",
+                    "type": "string",
+                    "example": "Tightened engine mount and rechecked torque"
+                },
+                "aircraft_hours_at_fix": {
+                    "type": "string",
+                    "example": "1250.1"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintActionTakenData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintActionTakenAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "complaint_action_taken",
+                        "complaint"
+                    ],
+                    "example": "complaint_action_taken"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintActionTakenRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintActionTakenData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintCreateAttributes": {
+            "type": "object",
+            "required": [
+                "description",
+                "helicopter_id"
+            ],
+            "properties": {
+                "aircraft_hours_at_report": {
+                    "description": "AircraftHoursAtReport — OPTIONAL airframe hours recorded when the defect was reported.",
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "description": {
+                    "description": "Description — the defect description. REQUIRED.",
+                    "type": "string",
+                    "example": "Engine 2 N2 vibration intermittent during cruise above 110 KIAS"
+                },
+                "flight_id": {
+                    "description": "FlightID — the flight/report this complaint was filed in (attribution). OPTIONAL;\nopen-defect tracking stays per-helicopter so defects carry forward across flights.",
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "helicopter_id": {
+                    "description": "HelicopterID — the helicopter this complaint is filed against. REQUIRED.",
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "mel_severity": {
+                    "description": "MELSeverity — MEL (Minimum Equipment List) classification. OPTIONAL at creation:\nomit it to file the complaint as \"pending_mel\" and classify later. It MUST be\nclassified (via update) before recording action taken. A pending complaint does\nNOT ground the aircraft — grounding starts at classification. Values: 0 = NON-MEL\n(grounds immediately), 1 = A (grace 1 day), 2 = B (3 days), 3 = C (10 days), 4 = D (120 days).",
+                    "type": "integer",
+                    "enum": [
+                        0,
+                        1,
+                        2,
+                        3,
+                        4
+                    ],
+                    "example": 2
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "complaint_create",
+                        "complaint"
+                    ],
+                    "example": "complaint_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintNSRSignAttributes": {
+            "type": "object",
+            "properties": {
+                "nsr_reason": {
+                    "description": "NSRReason — OPTIONAL free-text justification for the NSR (MEL deferral) decision.",
+                    "type": "string",
+                    "example": "Released under MEL A, defect deferred"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintNSRSignData": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintNSRSignAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "complaint_nsr_sign",
+                        "complaint_nsr"
+                    ],
+                    "example": "complaint_nsr_sign"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintNSRSignRequest": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintNSRSignData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "aircraft_hours_at_report": {
+                    "description": "AircraftHoursAtReport — airframe hours at report time.",
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "description": {
+                    "description": "Description — defect description.",
+                    "type": "string",
+                    "example": "Engine 2 vibration confirmed"
+                },
+                "mel_severity": {
+                    "description": "MELSeverity — MEL classification. 0 = NON-MEL (immediate AOG), 1 = A (1 day),\n2 = B (3 days), 3 = C (10 days), 4 = D (120 days). AOG after grace passes.",
+                    "type": "integer",
+                    "enum": [
+                        0,
+                        1,
+                        2,
+                        3,
+                        4
+                    ],
+                    "example": 2
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "id",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "complaint_update",
+                        "complaint"
+                    ],
+                    "example": "complaint_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterAnyDeleteData": {
+            "type": "object",
+            "required": [
+                "id"
+            ],
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterAnyDeleteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterAnyDeleteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterCreateAttributes": {
+            "type": "object",
+            "required": [
+                "base_id",
+                "duty_date"
+            ],
+            "properties": {
+                "base_id": {
+                    "type": "string"
+                },
+                "duty_date": {
+                    "type": "string"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDetailsInput"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterShiftTime"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "duty_roster_create",
+                        "duty_roster"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterCrewInput": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "shift_date": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterShiftDate"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewAttributes": {
+            "type": "object",
+            "properties": {
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDetailsInput"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDAttributes": {
+            "type": "object",
+            "required": [
+                "crew_id",
+                "roster_id"
+            ],
+            "properties": {
+                "crew_id": {
+                    "type": "string"
+                },
+                "roster_id": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "duty_roster_crew_delete",
+                        "duty_roster_update",
+                        "duty_roster"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "duty_roster_crew_delete",
+                        "duty_roster_update",
+                        "duty_roster"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDetailsInput": {
+            "type": "object",
+            "properties": {
+                "doctor": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCrewInput"
+                    }
+                },
+                "helper": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCrewInput"
+                    }
+                },
+                "other_person": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterOtherPersonInput"
+                    }
+                },
+                "pilot": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterPilotCrewInput"
+                    }
+                },
+                "rescuer": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCrewInput"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterOtherPersonInput": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "guest@example.com"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Guest Person"
+                },
+                "other_person_id": {
+                    "description": "OtherPersonID — OPTIONAL master person id to reuse (from GET /contact/other).\nWhen set, name/mobile_phone/email are snapshotted from the master (may be omitted).",
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterPilotCrewInput": {
+            "type": "object",
+            "properties": {
+                "co_pilot": {
+                    "type": "boolean"
+                },
+                "crew_type": {
+                    "type": "string",
+                    "enum": [
+                        "main",
+                        "additional"
+                    ],
+                    "example": "main"
+                },
+                "examiner": {
+                    "type": "boolean"
+                },
+                "flight_instructor": {
+                    "type": "boolean"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "line_checker": {
+                    "type": "boolean"
+                },
+                "shift_date": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterShiftDate"
+                },
+                "supervisor": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterShiftDate": {
+            "type": "object",
+            "properties": {
+                "date_end": {
+                    "type": "string",
+                    "example": "2026-03-16"
+                },
+                "date_start": {
+                    "type": "string",
+                    "example": "2026-03-16"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterShiftTime": {
+            "type": "object",
+            "properties": {
+                "shift_end": {
+                    "type": "string",
+                    "example": "21:00"
+                },
+                "shift_start": {
+                    "type": "string",
+                    "example": "06:00"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "base_id": {
+                    "type": "string"
+                },
+                "duty_date": {
+                    "type": "string"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDetailsInput"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterShiftTime"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterUpdateAttributes"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "duty_roster_update",
+                        "duty_roster"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.EASAReleaseCreateAttributes": {
+            "type": "object",
+            "required": [
+                "helicopter_id"
+            ],
+            "properties": {
+                "complaint_id": {
+                    "description": "ComplaintID — OPTIONAL complaint (UUIDv7) this release closes. Set it to scope the\nrelease to a specific defect; leave empty for a standalone (aircraft-clear) release.",
+                    "type": "string",
+                    "example": "019d6774-1111-7fba-9ef4-3795c0da8a13"
+                },
+                "easa_ac_hours": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "easa_date": {
+                    "type": "string",
+                    "example": "2026-06-16"
+                },
+                "easa_location": {
+                    "type": "string",
+                    "example": "LOWI"
+                },
+                "easa_maint_manual_rev_airframe": {
+                    "type": "string",
+                    "example": "Rev 12"
+                },
+                "easa_maint_manual_rev_engine": {
+                    "type": "string",
+                    "example": "Rev 8"
+                },
+                "easa_permit_no": {
+                    "type": "string",
+                    "example": "145.A.50"
+                },
+                "easa_signer_id": {
+                    "description": "EASASignerID — OPTIONAL contact id (UUIDv7) of the signer/technician. Required only to sign.",
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "easa_wo_no": {
+                    "type": "string",
+                    "example": "WO-2026-001"
+                },
+                "flight_id": {
+                    "description": "FlightID — OPTIONAL flight context. Used for the standalone (no-complaint) sign-off gate.",
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "sign": {
+                    "description": "Sign, when true, signs the release immediately at creation. Requires all\nrequired fields to be present; otherwise the request is rejected.",
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.EASAReleaseCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "easa_release_create",
+                        "easa_release"
+                    ],
+                    "example": "easa_release_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.EASAReleaseCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.EASAReleaseUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "easa_ac_hours": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "easa_date": {
+                    "type": "string",
+                    "example": "2026-06-16"
+                },
+                "easa_location": {
+                    "type": "string",
+                    "example": "LOWI"
+                },
+                "easa_maint_manual_rev_airframe": {
+                    "type": "string",
+                    "example": "Rev 12"
+                },
+                "easa_maint_manual_rev_engine": {
+                    "type": "string",
+                    "example": "Rev 8"
+                },
+                "easa_permit_no": {
+                    "type": "string",
+                    "example": "145.A.50"
+                },
+                "easa_signer_id": {
+                    "description": "EASASignerID — OPTIONAL contact id (UUIDv7) of the signer/technician. Required only to sign.",
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "easa_wo_no": {
+                    "type": "string",
+                    "example": "WO-2026-001"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.EASAReleaseUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "id",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "easa_release_update",
+                        "easa_release"
+                    ],
+                    "example": "easa_release_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.EASAReleaseUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FMReportUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "engine1_gpc_n1": {
+                    "description": "Engine1GpcN1 - GPC/N1 value for engine 1. Optional.",
+                    "type": "string",
+                    "example": "GPC/N1 63.2"
+                },
+                "engine1_ptc_n2": {
+                    "description": "Engine1PtcN2 - PTC/N2 value for engine 1. Optional.",
+                    "type": "string",
+                    "example": "PTC/N2 61.8"
+                },
+                "engine2_gpc_n1": {
+                    "description": "Engine2GpcN1 - GPC/N1 value for engine 2. Optional.",
+                    "type": "string",
+                    "example": "GPC/N1 63.2"
+                },
+                "engine2_ptc_n2": {
+                    "description": "Engine2PtcN2 - PTC/N2 value for engine 2. Optional.",
+                    "type": "string",
+                    "example": "PTC/N2 61.8"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FMReportUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FMReportUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "fm_report_update",
+                        "fm_report"
+                    ],
+                    "example": "fm_report_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FMReportUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FMReportUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateAttributes": {
+            "type": "object",
+            "required": [
+                "file_id",
+                "ref_id",
+                "ref_type"
+            ],
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "example": "document"
+                },
+                "file_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_primary": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "ref_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "ref_type": {
+                    "type": "string",
+                    "example": "helicopter"
+                },
+                "sort_order": {
+                    "type": "integer",
+                    "example": 0
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_attachment_create",
+                        "file_manager_attachment"
+                    ],
+                    "example": "file_manager_attachment_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileAircraftBulkCreateItem": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileAircraftCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_create",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileAircraftBulkCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileAircraftBulkCreateItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileAircraftCreateAttributes": {
+            "type": "object",
+            "required": [
+                "aircraft_uuid",
+                "name",
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "aircraft_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "aircraft.jpg"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileBaseBulkCreateItem": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileBaseCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_create",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileBaseBulkCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileBaseBulkCreateItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileBaseCreateAttributes": {
+            "type": "object",
+            "required": [
+                "base_uuid",
+                "name",
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "base_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "base.jpg"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadAttributes": {
+            "type": "object",
+            "required": [
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_cancel_upload"
+                    ],
+                    "example": "file_manager_file_cancel_upload"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileDULBulkCreateItem": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileDULCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_create",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileDULBulkCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileDULBulkCreateItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileDULCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name",
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "dul_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "dul.jpg"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileMissionBulkCreateItem": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileMissionCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_create",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileMissionBulkCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileMissionBulkCreateItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileMissionCreateAttributes": {
+            "type": "object",
+            "required": [
+                "mission_uuid",
+                "name",
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "mission_uuid": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "mission-brief.pdf"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileTakeoverBulkCreateItem": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTakeoverCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_create",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileTakeoverBulkCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTakeoverBulkCreateItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileTakeoverCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name",
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "takeover-report.pdf"
+                },
+                "takeover_uuid": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileTemplateCreateAttributes": {
+            "type": "object",
+            "required": [
+                "helicopter_id",
+                "name",
+                "template_uuid"
+            ],
+            "properties": {
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "collabora-draft.docx"
+                },
+                "takeover_id": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                },
+                "template_uuid": {
+                    "type": "string",
+                    "example": "019f0386-0a00-7a4a-a2d8-30afc0e0c3ad"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileTemplateCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "required": [
+                        "attributes",
+                        "type"
+                    ],
+                    "properties": {
+                        "attributes": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTemplateCreateAttributes"
+                        },
+                        "type": {
+                            "type": "string",
+                            "enum": [
+                                "file_manager_file_create_from_template",
+                                "file_manager_file_create"
+                            ]
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "folder_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "policy-v2.pdf"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_update",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentAttributes": {
+            "type": "object",
+            "required": [
+                "content_type",
+                "name",
+                "size_bytes"
+            ],
+            "properties": {
+                "content_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "policy-final.pdf"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "example": 1024
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_upload_intent"
+                    ],
+                    "example": "file_manager_file_upload_intent"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateItem": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUserCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_create",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUserCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name",
+                "upload_intent_uuid",
+                "user_uuid"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "profile.jpg"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "user_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFolderCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "operations"
+                },
+                "parent_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFolderCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_folder_create",
+                        "file_manager_folder"
+                    ],
+                    "example": "file_manager_folder_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFolderCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFolderUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "operations-updated"
+                },
+                "parent_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFolderUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_folder_update",
+                        "file_manager_folder"
+                    ],
+                    "example": "file_manager_folder_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFolderUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerNodeMoveBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodeMoveItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerNodeMoveItem": {
+            "type": "object",
+            "required": [
+                "uuid"
+            ],
+            "properties": {
+                "destination_folder_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerNodePurgeBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodePurgeItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerNodePurgeItem": {
+            "type": "object",
+            "required": [
+                "uuid"
+            ],
+            "properties": {
+                "uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusCreateAttributes": {
+            "type": "object",
+            "required": [
+                "helicopter_id"
+            ],
+            "properties": {
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusFileAttributes"
+                    }
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "maintenance_schedules": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "fleet_status_create",
+                        "fleet_status"
+                    ],
+                    "example": "fleet_status_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusSummaryAirframeUpdate": {
+            "type": "object",
+            "properties": {
+                "cycles": {
+                    "type": "number",
+                    "example": 320
+                },
+                "hours": {
+                    "type": "number",
+                    "example": 6610.5
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusSummaryEngineUpdate": {
+            "type": "object",
+            "properties": {
+                "ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "hours": {
+                    "type": "number",
+                    "example": 8001.7
+                },
+                "ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusSummaryUpdate": {
+            "type": "object",
+            "properties": {
+                "airframe": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusSummaryAirframeUpdate"
+                },
+                "engine_1": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusSummaryEngineUpdate"
+                },
+                "engine_2": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusSummaryEngineUpdate"
+                },
+                "flight_reports": {
+                    "type": "number",
+                    "example": 80
+                },
+                "hook_releases": {
+                    "type": "number",
+                    "example": 10
+                },
+                "landings": {
+                    "type": "number",
+                    "example": 120
+                },
+                "rotor_brake_cycles": {
+                    "type": "number",
+                    "example": 8
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusFileAttributes"
+                    }
+                },
+                "helicopter_id": {
+                    "type": "string"
+                },
+                "maintenance_schedules": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes"
+                    }
+                },
+                "summary": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusSummaryUpdate"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "fleet_status_update",
+                        "fleet_status"
+                    ],
+                    "example": "fleet_status_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateAttributes": {
+            "type": "object",
+            "required": [
+                "mission_id"
+            ],
+            "properties": {
+                "co_pilot_id": {
+                    "type": "string"
+                },
+                "customer_name": {
+                    "type": "string"
+                },
+                "delivery_note_number": {
+                    "type": "string"
+                },
+                "engine": {
+                    "type": "string"
+                },
+                "flight_duration_seconds": {
+                    "type": "integer"
+                },
+                "flight_landing": {
+                    "type": "string"
+                },
+                "flight_plan_distance": {
+                    "type": "number"
+                },
+                "flight_plan_time_seconds": {
+                    "type": "integer"
+                },
+                "flight_plan_true_course": {
+                    "type": "number"
+                },
+                "flight_positioning": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "flight_red_seconds": {
+                    "type": "integer"
+                },
+                "flight_take_off": {
+                    "type": "string"
+                },
+                "from_hospital_id": {
+                    "type": "string"
+                },
+                "from_icao_id": {
+                    "type": "string"
+                },
+                "fuel_after_flight": {
+                    "type": "number"
+                },
+                "fuel_before_flight": {
+                    "type": "number"
+                },
+                "fuel_planning": {
+                    "type": "number"
+                },
+                "fuel_upload": {
+                    "type": "number"
+                },
+                "hec": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECAttributes"
+                },
+                "heslo": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOAttributes"
+                },
+                "hook_releases": {
+                    "type": "integer"
+                },
+                "landing_count": {
+                    "type": "integer"
+                },
+                "logging": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOLoggingAttributes"
+                },
+                "max_n1": {
+                    "type": "number"
+                },
+                "max_n2": {
+                    "type": "number"
+                },
+                "mission_id": {
+                    "type": "string"
+                },
+                "other_information": {
+                    "type": "string"
+                },
+                "pax_count": {
+                    "type": "integer"
+                },
+                "rotor_brake_cycle": {
+                    "type": "integer"
+                },
+                "ticket_no": {
+                    "type": "string"
+                },
+                "to_hospital_id": {
+                    "type": "string"
+                },
+                "to_icao_id": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "flight_data_create",
+                        "flight_data"
+                    ],
+                    "example": "flight_data_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECAttributes": {
+            "type": "object",
+            "properties": {
+                "flights": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECFlight"
+                    }
+                },
+                "loads": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECLoad"
+                    }
+                },
+                "slings": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECSling"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECFlight": {
+            "type": "object",
+            "properties": {
+                "equipment_id": {
+                    "description": "Facility category: hec-rope-label.",
+                    "type": "string",
+                    "example": "string"
+                },
+                "equipment_name": {
+                    "type": "string",
+                    "example": "string"
+                },
+                "hec_cycle": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "rot": {
+                    "type": "integer",
+                    "example": 0
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECLoad": {
+            "type": "object",
+            "properties": {
+                "load_category": {
+                    "description": "Weight band for the HEC load, e.g. \"bis 199 kg\", \"200-600 kg\", \"600-800 kg\", \"800-1000 kg\".",
+                    "type": "string",
+                    "example": "200-600 kg"
+                },
+                "quantity": {
+                    "type": "integer",
+                    "example": 3
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECSling": {
+            "type": "object",
+            "properties": {
+                "sling_id": {
+                    "description": "Facility category: hec-rope-length.",
+                    "type": "string",
+                    "example": "string"
+                },
+                "sling_name": {
+                    "type": "string",
+                    "example": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOAttributes": {
+            "type": "object",
+            "properties": {
+                "flights": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOFlight"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOFlight": {
+            "type": "object",
+            "properties": {
+                "heslo_rope_label_id": {
+                    "description": "Facility category: heslo-rope-label.",
+                    "type": "string",
+                    "example": "string"
+                },
+                "heslo_rope_label_name": {
+                    "type": "string",
+                    "example": "string"
+                },
+                "rot": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "slings": {
+                    "description": "Facility category: heslo-rope-length.",
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOSling"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOSling": {
+            "type": "object",
+            "properties": {
+                "sling_id": {
+                    "description": "Facility category: heslo-rope-length.",
+                    "type": "string",
+                    "example": "string"
+                },
+                "sling_name": {
+                    "type": "string",
+                    "example": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOLoggingAttributes": {
+            "type": "object",
+            "properties": {
+                "slings": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOLoggingSling"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOLoggingSling": {
+            "type": "object",
+            "properties": {
+                "sling_id": {
+                    "description": "Facility category: heslo-hook.",
+                    "type": "string",
+                    "example": "string"
+                },
+                "sling_name": {
+                    "type": "string",
+                    "example": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "flight_data_update"
+                    ],
+                    "example": "flight_data_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterCreateAttributes": {
+            "type": "object",
+            "required": [
+                "designation",
+                "identifier",
+                "type"
+            ],
+            "properties": {
+                "aog": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "aog_reason": {
+                    "type": "string",
+                    "example": "Main rotor gearbox fault"
+                },
+                "consumption_lt_min": {
+                    "type": "number",
+                    "example": 4.1
+                },
+                "designation": {
+                    "type": "string",
+                    "example": "OE-XHZ"
+                },
+                "dry": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "engine_1": {
+                    "type": "string",
+                    "example": "TM"
+                },
+                "engine_2": {
+                    "type": "string",
+                    "example": "TM"
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "ABC"
+                },
+                "igb": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "lh": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "mgb": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Primary HEMS helicopter"
+                },
+                "nr1": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "nr2": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "rh": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 10
+                },
+                "tgb": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "type": {
+                    "type": "string",
+                    "example": "EC-135"
+                },
+                "utc_offset": {
+                    "type": "integer",
+                    "example": -1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_create",
+                        "helicopter"
+                    ],
+                    "example": "helicopter_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadAttributes": {
+            "type": "object",
+            "required": [
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "019d6d0d-2de2-7db1-80a2-2862d43af620"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_file_cancel_upload"
+                    ],
+                    "example": "helicopter_file_cancel_upload"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileCreateAttributes": {
+            "type": "object",
+            "required": [
+                "file_name",
+                "section",
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "file_name": {
+                    "type": "string",
+                    "example": "Before Flight Checklist.pdf"
+                },
+                "folder_uuid": {
+                    "type": "string",
+                    "example": "019d6d0d-8c24-72e3-9f58-c9ea0fbf0bb1"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "is_mandatory": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "section": {
+                    "type": "string",
+                    "enum": [
+                        "bfi",
+                        "fpwb",
+                        "afi"
+                    ],
+                    "example": "bfi"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "019d6d0d-2de2-7db1-80a2-2862d43af620"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileCreateBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCreateData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_file_create",
+                        "helicopter_file"
+                    ],
+                    "example": "helicopter_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileDeleteData": {
+            "type": "object",
+            "required": [
+                "id",
+                "type"
+            ],
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_file_delete",
+                        "helicopter_file"
+                    ],
+                    "example": "helicopter_file_delete"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileDeleteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileDeleteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "file_name": {
+                    "type": "string",
+                    "example": "Before Flight Checklist v2.pdf"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "is_mandatory": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "section": {
+                    "type": "string",
+                    "enum": [
+                        "bfi",
+                        "fpwb",
+                        "afi"
+                    ],
+                    "example": "fpwb"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileUpdateBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUpdateData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "id",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_file_update",
+                        "helicopter_file"
+                    ],
+                    "example": "helicopter_file_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileUploadAttributes": {
+            "type": "object",
+            "required": [
+                "content_type",
+                "name",
+                "size_bytes"
+            ],
+            "properties": {
+                "content_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Before Flight Checklist.pdf"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "example": 1024
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileUploadBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUploadData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileUploadData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUploadAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_file_upload"
+                    ],
+                    "example": "helicopter_file_upload"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "aog": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "aog_reason": {
+                    "type": "string",
+                    "example": "Main rotor gearbox fault"
+                },
+                "consumption_lt_min": {
+                    "type": "number",
+                    "example": 4.1
+                },
+                "designation": {
+                    "type": "string",
+                    "example": "OE-XHZ"
+                },
+                "dry": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "engine_1": {
+                    "type": "string",
+                    "example": "TM"
+                },
+                "engine_2": {
+                    "type": "string",
+                    "example": "TM"
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "ABC"
+                },
+                "igb": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "lh": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "mgb": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Primary HEMS helicopter"
+                },
+                "nr1": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "nr2": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "rh": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 10
+                },
+                "tgb": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "type": {
+                    "type": "string",
+                    "example": "EC-135"
+                },
+                "utc_offset": {
+                    "type": "integer",
+                    "example": -1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_update",
+                        "helicopter"
+                    ],
+                    "example": "helicopter_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionUpsertAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "last_flights_inspection_create",
+                        "last_flights_inspection"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteAttributes": {
+            "type": "object",
+            "required": [
+                "flight_inspection_id"
+            ],
+            "properties": {
+                "flight_inspection_id": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "last_flights_inspection_delete",
+                        "last_flights_inspection"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionUpsertAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "last_flights_inspection_update",
+                        "last_flights_inspection"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionUpsertAttributes": {
+            "type": "object",
+            "required": [
+                "flight_inspection_id"
+            ],
+            "properties": {
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem"
+                    }
+                },
+                "flight_inspection_id": {
+                    "type": "string"
+                },
+                "hydraulic_lh_checked": {
+                    "type": "string"
+                },
+                "hydraulic_rh_checked": {
+                    "type": "string"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "oil_engine_nr1_checked": {
+                    "type": "string"
+                },
+                "oil_engine_nr2_checked": {
+                    "type": "string"
+                },
+                "oil_transmission_igb_checked": {
+                    "type": "string"
+                },
+                "oil_transmission_mgb_checked": {
+                    "type": "string"
+                },
+                "oil_transmission_tgb_checked": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MCFCompleteAttributes": {
+            "type": "object",
+            "properties": {
+                "af_hours": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-06-17"
+                },
+                "landing_count": {
+                    "type": "integer",
+                    "example": 3
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Vibration within limits after check flight"
+                },
+                "result": {
+                    "type": "string",
+                    "enum": [
+                        "passed",
+                        "failed"
+                    ],
+                    "example": "passed"
+                },
+                "sign": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "utc_time": {
+                    "type": "string",
+                    "example": "2026-06-17T08:30:00Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MCFCompleteData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MCFCompleteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "mcf_complete",
+                        "mcf_sign",
+                        "mcf"
+                    ],
+                    "example": "mcf_sign"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MCFCompleteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MCFCompleteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MCFSetAttributes": {
+            "type": "object",
+            "properties": {
+                "active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "af_hours": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-06-17"
+                },
+                "flight_id": {
+                    "description": "FlightID — OPTIONAL flight this check flight is performed on (on activate).",
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "landing_count": {
+                    "type": "integer",
+                    "example": 3
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "MCF required after engine mount work"
+                },
+                "result": {
+                    "type": "string",
+                    "enum": [
+                        "passed",
+                        "failed"
+                    ],
+                    "example": "passed"
+                },
+                "utc_time": {
+                    "type": "string",
+                    "example": "2026-06-17T08:30:00Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MCFSetData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MCFSetAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "mcf_set",
+                        "mcf"
+                    ],
+                    "example": "mcf_set"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MCFSetRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MCFSetData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsCreateAttributes": {
+            "type": "object",
+            "required": [
+                "company_name"
+            ],
+            "properties": {
+                "company_name": {
+                    "type": "string",
+                    "example": "Wucher"
+                },
+                "cover_file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "logo_file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "subtitle": {
+                    "type": "string",
+                    "example": "Flight operations platform"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Welcome to Wucher"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "master_settings_create",
+                        "master_settings"
+                    ],
+                    "example": "master_settings_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertAttributes": {
+            "type": "object",
+            "required": [
+                "MS_ENTRA_AUTHORITY",
+                "MS_ENTRA_CLIENT_ID",
+                "MS_ENTRA_REDIRECT_URL",
+                "MS_ENTRA_SCOPES",
+                "MS_ENTRA_TENANT_ID"
+            ],
+            "properties": {
+                "MS_ENTRA_AUTHORITY": {
+                    "type": "string",
+                    "example": "https://login.microsoftonline.com/"
+                },
+                "MS_ENTRA_CLIENT_ID": {
+                    "type": "string",
+                    "example": "your-client-id"
+                },
+                "MS_ENTRA_CLIENT_SECRET": {
+                    "type": "string",
+                    "example": "********"
+                },
+                "MS_ENTRA_REDIRECT_URL": {
+                    "type": "string",
+                    "example": "https://example.com/api/v1/auth/microsoft/callback"
+                },
+                "MS_ENTRA_SCOPES": {
+                    "type": "string",
+                    "example": "openid,profile,email"
+                },
+                "MS_ENTRA_TENANT_ID": {
+                    "type": "string",
+                    "example": "your-tenant-id"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "master_settings_microsoft_entra_upsert",
+                        "master_settings"
+                    ],
+                    "example": "master_settings_microsoft_entra_upsert"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "company_name": {
+                    "type": "string",
+                    "example": "Wucher"
+                },
+                "cover_file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "logo_file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "subtitle": {
+                    "type": "string",
+                    "example": "Flight operations platform"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Welcome to Wucher"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "master_settings_update",
+                        "master_settings"
+                    ],
+                    "example": "master_settings_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionCreateAttributes": {
+            "type": "object",
+            "required": [
+                "flight_id",
+                "type"
+            ],
+            "properties": {
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionFileInput"
+                    }
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Mission note"
+                },
+                "subtype_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a99"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "mission_create",
+                        "mission"
+                    ],
+                    "example": "mission_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionFileInput": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "mission-brief.pdf"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionTypeCreateAttributes": {
+            "type": "object",
+            "required": [
+                "code_type",
+                "name"
+            ],
+            "properties": {
+                "code_type": {
+                    "type": "string",
+                    "example": "HEMS"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionTypeCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionTypeCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "mission_type_create",
+                        "mission_type"
+                    ],
+                    "example": "mission_type_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionTypeCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionTypeCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionUpdateAttributes": {
+            "type": "object",
+            "required": [
+                "type"
+            ],
+            "properties": {
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionFileInput"
+                    }
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Mission note"
+                },
+                "subtype_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a99"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "SPO"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "mission_update",
+                        "mission"
+                    ],
+                    "example": "mission_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.OtherPersonAttributesInput": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "guest@example.com"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Guest Person"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.OtherPersonRequest": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.OtherPersonRequestData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.OtherPersonRequestData": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.OtherPersonAttributesInput"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "other_person"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcBeforeInspectionAttributes": {
+            "type": "object",
+            "properties": {
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem"
+                    }
+                },
+                "fuel_added_amount": {
+                    "type": "number"
+                },
+                "fuel_amount": {
+                    "type": "number"
+                },
+                "fuel_unit": {
+                    "type": "string"
+                },
+                "hydraulic_lh_checked": {
+                    "type": "boolean"
+                },
+                "hydraulic_rh_checked": {
+                    "type": "boolean"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "oil_engine_nr1_checked": {
+                    "type": "boolean"
+                },
+                "oil_engine_nr2_checked": {
+                    "type": "boolean"
+                },
+                "oil_transmission_igb_checked": {
+                    "type": "boolean"
+                },
+                "oil_transmission_mgb_checked": {
+                    "type": "boolean"
+                },
+                "oil_transmission_tgb_checked": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcCreateAttributes": {
+            "type": "object",
+            "required": [
+                "flight_id",
+                "helicopter_id",
+                "inspection"
+            ],
+            "properties": {
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcInspectionCreateAttributes"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "reserve_ac_create",
+                        "reserve_ac"
+                    ],
+                    "example": "reserve_ac_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcDeleteData": {
+            "type": "object",
+            "required": [
+                "id"
+            ],
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcDeleteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcDeleteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem": {
+            "type": "object",
+            "required": [
+                "helicopter_file_id"
+            ],
+            "properties": {
+                "helicopter_file_id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-111111111111"
+                },
+                "is_done": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcFleetStatusFileAttributes": {
+            "type": "object",
+            "properties": {
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcInspectionCreateAttributes": {
+            "type": "object",
+            "required": [
+                "before",
+                "inspection_date",
+                "prepare"
+            ],
+            "properties": {
+                "before": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcBeforeInspectionAttributes"
+                },
+                "fleet_status_file": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFleetStatusFileAttributes"
+                },
+                "inspection_date": {
+                    "type": "string",
+                    "example": "2026-04-15"
+                },
+                "prepare": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcPrepareInspectionAttributes"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcInspectionUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "before": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcBeforeInspectionAttributes"
+                },
+                "inspection_date": {
+                    "type": "string",
+                    "example": "2026-04-15"
+                },
+                "prepare": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcPrepareInspectionAttributes"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcPrepareInspectionAttributes": {
+            "type": "object",
+            "properties": {
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem"
+                    }
+                },
+                "notam_briefing": {
+                    "type": "boolean"
+                },
+                "operational_flight_plan": {
+                    "type": "boolean"
+                },
+                "weather_briefing": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcInspectionUpdateAttributes"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "reserve_ac_update",
+                        "reserve_ac"
+                    ],
+                    "example": "reserve_ac_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverBaseRef": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverCreateAttributes": {
+            "type": "object",
+            "required": [
+                "duty_date"
+            ],
+            "properties": {
+                "base_id": {
+                    "type": "string"
+                },
+                "duty_date": {
+                    "type": "string"
+                },
+                "edited_template_file_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateFileInput"
+                    }
+                },
+                "helicopter_id": {
+                    "type": "string"
+                },
+                "inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcInspectionCreateAttributes"
+                },
+                "notes": {
+                    "type": "string"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterDetailsInput"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "takeover_create",
+                        "takeover"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverCreateFileInput": {
+            "type": "object",
+            "properties": {
+                "file_id": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "takeover-report.pdf"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverRosterCrewInput": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverRosterDetailsInput": {
+            "type": "object",
+            "properties": {
+                "doctor": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterCrewInput"
+                    }
+                },
+                "helper": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterCrewInput"
+                    }
+                },
+                "other_person": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterOtherPersonInput"
+                    }
+                },
+                "pilot": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterPilotInput"
+                    }
+                },
+                "rescuer": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterCrewInput"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverRosterOtherPersonInput": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "guest@example.com"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Guest Person"
+                },
+                "other_person_id": {
+                    "description": "OtherPersonID — OPTIONAL master person id to reuse (from GET /contact/other).",
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverRosterPilotInput": {
+            "type": "object",
+            "properties": {
+                "co_pilot": {
+                    "type": "boolean"
+                },
+                "crew_type": {
+                    "type": "string",
+                    "enum": [
+                        "main",
+                        "additional"
+                    ],
+                    "example": "main"
+                },
+                "examiner": {
+                    "type": "boolean"
+                },
+                "flight_instructor": {
+                    "type": "boolean"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "line_checker": {
+                    "type": "boolean"
+                },
+                "supervisor": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "base_id": {
+                    "type": "string"
+                },
+                "bases": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverBaseRef"
+                },
+                "duty_date": {
+                    "type": "string"
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateFileInput"
+                    }
+                },
+                "files_add": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateFileInput"
+                    }
+                },
+                "files_remove": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "files_replace": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateFileInput"
+                    }
+                },
+                "helicopter_id": {
+                    "type": "string"
+                },
+                "inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcInspectionCreateAttributes"
+                },
+                "notes": {
+                    "type": "string"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterDetailsInput"
+                },
+                "roster_details": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterDetailsInput"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverUpdateAttributes"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "takeover_update",
+                        "takeover"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ActionSignoffAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "signed": {
+                    "description": "Signed — true once checked; gates the maintenance release form.",
+                    "type": "boolean",
+                    "example": false
+                },
+                "signed_at": {
+                    "description": "SignedAt / SignedBy — when/who signed; empty until signed.",
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "signed_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "signed_by_name": {
+                    "description": "SignedByName / SignedByShort — resolved display name + 3-letter short of the signer.",
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "signed_by_short": {
+                    "type": "string",
+                    "example": "JDO"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ActionSignoffResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ActionSignoffAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "action_signoff"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ActionSignoffResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ActionSignoffResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistAttributes": {
+            "type": "object",
+            "properties": {
+                "bases": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistBaseInfo"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResource"
+                    }
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "scope_code": {
+                    "type": "string",
+                    "example": "TU"
+                },
+                "scope_code_de": {
+                    "type": "string",
+                    "example": "DI"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Monday Checklist"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupAttributes": {
+            "type": "object",
+            "properties": {
+                "bases": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistBaseInfo"
+                },
+                "tabs": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistTabResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "base-018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "air_rescuer_checklist_group"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistCATChecklistSummary": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Cockpit Flugretter"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistCATGroup": {
+            "type": "object",
+            "properties": {
+                "checklists": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistCATChecklistSummary"
+                    }
+                },
+                "scope_code": {
+                    "type": "string",
+                    "example": "DA"
+                },
+                "scope_code_de": {
+                    "type": "string",
+                    "example": "TA"
+                },
+                "scope_code_name": {
+                    "type": "string",
+                    "example": "Daily"
+                },
+                "scope_code_name_de": {
+                    "type": "string",
+                    "example": "Taeglich"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 8
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 8
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "total_bases": {
+                            "type": "integer",
+                            "example": 8
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistItemAttributes": {
+            "type": "object",
+            "properties": {
+                "checklist_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Check radio"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistItemBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistItemData": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "air_rescuer_checklist_item"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResource": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Oxygen supply check"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "air_rescuer_checklist"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistTabChecklistDetail": {
+            "type": "object",
+            "properties": {
+                "checklist_items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResource"
+                    }
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Monday Checklist"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistTabResource": {
+            "type": "object",
+            "properties": {
+                "checklists": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistTabChecklistDetail"
+                    }
+                },
+                "groups": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistCATGroup"
+                    }
+                },
+                "scope_code": {
+                    "type": "string",
+                    "example": "DA"
+                },
+                "scope_code_de": {
+                    "type": "string",
+                    "example": "TA"
+                },
+                "scope_code_name": {
+                    "type": "string",
+                    "example": "Daily"
+                },
+                "scope_code_name_de": {
+                    "type": "string",
+                    "example": "Taeglich"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintAttributes": {
+            "type": "object",
+            "properties": {
+                "action_signed": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "action_signed_at": {
+                    "type": "string",
+                    "example": "2026-06-15T03:04:05Z"
+                },
+                "action_signed_by_name": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "action_signed_by_short": {
+                    "type": "string",
+                    "example": "JDO"
+                },
+                "action_taken": {
+                    "type": "string",
+                    "example": "tightened mount"
+                },
+                "aircraft_hours_at_fix": {
+                    "type": "string",
+                    "example": "1250.1"
+                },
+                "aircraft_hours_at_report": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-06-15T03:04:05Z"
+                },
+                "description": {
+                    "type": "string",
+                    "example": "Engine 2 N2 vibration intermittent during cruise above 110 KIAS"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusHelicopter"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "mel": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintMEL"
+                },
+                "nsr": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintNSR"
+                },
+                "reported_at": {
+                    "type": "string",
+                    "example": "2026-06-15T03:04:05Z"
+                },
+                "reported_by": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "reported_by_short": {
+                    "type": "string",
+                    "example": "JDO"
+                },
+                "status": {
+                    "type": "string",
+                    "enum": [
+                        "active_non_mel",
+                        "active_mel",
+                        "serviced"
+                    ],
+                    "example": "active_mel"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-06-15T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintGroupedDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupAttributes": {
+            "type": "object",
+            "properties": {
+                "complaints": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResource"
+                    }
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusHelicopter"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "complaint_helicopter_group"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintMEL": {
+            "type": "object",
+            "properties": {
+                "classified_at": {
+                    "description": "ClassifiedAt / ClassifiedByName / ClassifiedByShort — when/who classified the MEL.",
+                    "type": "string",
+                    "example": "2026-06-15T03:04:05Z"
+                },
+                "classified_by_name": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "classified_by_short": {
+                    "type": "string",
+                    "example": "JDO"
+                },
+                "deadline": {
+                    "description": "Deadline — grace deadline; after this the aircraft is AOG. null for NON-MEL.",
+                    "type": "string",
+                    "example": "2026-06-18T03:04:05Z"
+                },
+                "severity": {
+                    "description": "Severity — MEL class: 0=NON-MEL, 1=A, 2=B, 3=C, 4=D. Always set (classification is required at creation).",
+                    "type": "integer",
+                    "enum": [
+                        0,
+                        1,
+                        2,
+                        3,
+                        4
+                    ],
+                    "example": 2
+                },
+                "severity_label": {
+                    "description": "SeverityLabel — human label of the severity (NON-MEL/A/B/C/D).",
+                    "type": "string",
+                    "example": "B"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintNSR": {
+            "type": "object",
+            "properties": {
+                "decided_at": {
+                    "description": "DecidedAt / DecidedByName / DecidedByShort — when/who decided NSR (may differ from the reporter).",
+                    "type": "string",
+                    "example": "2026-06-15T03:04:05Z"
+                },
+                "decided_by_name": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "decided_by_short": {
+                    "type": "string",
+                    "example": "JDO"
+                },
+                "is_nsr": {
+                    "description": "IsNSR — Non-Safety Release: true = aircraft released to fly despite the open defect.",
+                    "type": "boolean",
+                    "example": false
+                },
+                "reason": {
+                    "description": "Reason — optional justification for the NSR decision.",
+                    "type": "string",
+                    "example": "not required"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "complaint"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterAttributes": {
+            "type": "object",
+            "properties": {
+                "bases": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseInfo"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "duty_date": {
+                    "type": "string",
+                    "example": "2026-03-16"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterHelicopterSummary"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterDetailsResponse"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftTime"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterBaseGroupAttributes": {
+            "type": "object",
+            "properties": {
+                "bases": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseInfo"
+                },
+                "rosters": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterGroupRoster"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterBaseGroupResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseGroupAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hems_base_roster_group"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterBaseInfo": {
+            "type": "object",
+            "properties": {
+                "base_abbreviation": {
+                    "type": "string",
+                    "example": "G1"
+                },
+                "base_name": {
+                    "type": "string",
+                    "example": "Gallus 1 - Zurs Lech"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftTime"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hems"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterCrew": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "doctor@example.com"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Hunter Wolfgang"
+                },
+                "role": {
+                    "type": "string",
+                    "example": "doctor"
+                },
+                "shift_date": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftDate"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftTime"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteAttributes": {
+            "type": "object",
+            "properties": {
+                "deleted": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "deleted_count": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "deleted_items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterDeletedCrewItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "duty_roster_crew_delete"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterDeletedCrewItem": {
+            "type": "object",
+            "properties": {
+                "crew_type": {
+                    "type": "string",
+                    "example": "main"
+                },
+                "date_end": {
+                    "type": "string",
+                    "example": "2026-03-22"
+                },
+                "date_start": {
+                    "type": "string",
+                    "example": "2026-03-20"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Pilot One"
+                },
+                "role_code": {
+                    "type": "string",
+                    "example": "pilot"
+                },
+                "roster_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterDetailsResponse": {
+            "type": "object",
+            "properties": {
+                "doctor": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrew"
+                    }
+                },
+                "helper": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrew"
+                    }
+                },
+                "other_person": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrew"
+                    }
+                },
+                "pilot": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterPilotCrew"
+                    }
+                },
+                "rescuer": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrew"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterGroupRoster": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "duty_date": {
+                    "type": "string",
+                    "example": "2026-03-16"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterHelicopterSummary"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterDetailsResponse"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftTime"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterGroupedDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 8
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 8
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterGroupedListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "from": {
+                            "type": "string",
+                            "example": "2026-03-16"
+                        },
+                        "to": {
+                            "type": "string",
+                            "example": "2026-04-15"
+                        },
+                        "total_bases": {
+                            "type": "integer",
+                            "example": 8
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterHelicopterSummary": {
+            "type": "object",
+            "properties": {
+                "designation": {
+                    "type": "string",
+                    "example": "OE-XHZ"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "1234"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "EC-135"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterPilotCrew": {
+            "type": "object",
+            "properties": {
+                "co_pilot": {
+                    "type": "boolean"
+                },
+                "crew_type": {
+                    "type": "string",
+                    "example": "main"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "pilot@example.com"
+                },
+                "examiner": {
+                    "type": "boolean"
+                },
+                "flight_instructor": {
+                    "type": "boolean"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "line_checker": {
+                    "type": "boolean"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Hunter Wolfgang"
+                },
+                "role": {
+                    "type": "string",
+                    "example": "pilot"
+                },
+                "shift_date": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftDate"
+                },
+                "supervisor": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "duty_roster"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterShiftDate": {
+            "type": "object",
+            "properties": {
+                "date_end": {
+                    "type": "string",
+                    "example": "2026-03-16"
+                },
+                "date_start": {
+                    "type": "string",
+                    "example": "2026-03-16"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterShiftTime": {
+            "type": "object",
+            "properties": {
+                "shift_end": {
+                    "type": "string",
+                    "example": "21:00"
+                },
+                "shift_start": {
+                    "type": "string",
+                    "example": "06:00"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.EASAReleaseAttributes": {
+            "type": "object",
+            "properties": {
+                "complaint_id": {
+                    "type": "string",
+                    "example": "019d6774-1111-7fba-9ef4-3795c0da8a13"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "easa_ac_hours": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "easa_date": {
+                    "type": "string",
+                    "example": "2026-06-16"
+                },
+                "easa_location": {
+                    "type": "string",
+                    "example": "LOWI"
+                },
+                "easa_maint_manual_rev_airframe": {
+                    "type": "string",
+                    "example": "Rev 12"
+                },
+                "easa_maint_manual_rev_engine": {
+                    "type": "string",
+                    "example": "Rev 8"
+                },
+                "easa_permit_no": {
+                    "type": "string",
+                    "example": "145.A.50"
+                },
+                "easa_signer_id": {
+                    "description": "EASASignerID — contact id (UUIDv7) of the signer/technician.",
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "easa_signer_name": {
+                    "description": "EASASignerName / EASASignerShort — resolved display name + 3-letter short of the signer contact.",
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "easa_signer_short": {
+                    "type": "string",
+                    "example": "JDO"
+                },
+                "easa_wo_no": {
+                    "type": "string",
+                    "example": "WO-2026-001"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "is_signed": {
+                    "description": "IsSigned — true once the release is signed (Release to Service); then the complaint becomes fixed.",
+                    "type": "boolean",
+                    "example": false
+                },
+                "missing_sign_fields": {
+                    "description": "MissingSignFields — required fields still empty; must all be filled before it can be signed.",
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "signed_at": {
+                    "description": "SignedAt / SignedBy — when/who signed; empty until signed.",
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "signed_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.EASAReleaseDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "deleted": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "easa_release_delete"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.EASAReleaseListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.EASAReleaseResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "easa_release"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.EASAReleaseResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerActionBulkError": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "FILE_MANAGER_VALIDATION_FAILED"
+                },
+                "detail": {
+                    "type": "string",
+                    "example": "duplicate name in target folder"
+                },
+                "error_code": {
+                    "type": "string",
+                    "example": "4222111"
+                },
+                "status": {
+                    "type": "integer",
+                    "example": 422
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Validation error"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerActionLocation": {
+            "type": "object",
+            "properties": {
+                "folder_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerAttachmentListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerAttachmentResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerAttachmentAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_attachment"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerAttachmentResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerBreadcrumbItem": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "operations"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileBulkError": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "FILE_MANAGER_VALIDATION_FAILED"
+                },
+                "detail": {
+                    "type": "string",
+                    "example": "duplicate name in target folder"
+                },
+                "error_code": {
+                    "type": "string",
+                    "example": "4222111"
+                },
+                "status": {
+                    "type": "integer",
+                    "example": 422
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Validation error"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "message": {
+                    "type": "string",
+                    "example": "created"
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileResource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadResource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "properties": {
+                        "status": {
+                            "type": "string",
+                            "example": "canceled"
+                        }
+                    }
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_file_cancel_upload_result"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileDetailResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileDetailAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_file"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileDetailResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileDetailResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_file"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileAttributes"
+                        },
+                        "id": {
+                            "type": "string",
+                            "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "file_manager_file"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentResource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileUploadIntentAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_file_upload_intent"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionData": {
+            "type": "object",
+            "properties": {
+                "access_token": {
+                    "type": "string",
+                    "example": "eyJhbGciOiJIUzI1NiIs..."
+                },
+                "access_token_ttl": {
+                    "description": "AccessTokenTTL is the access token's absolute expiry time, in epoch\nmilliseconds (equal to the JWT exp claim), as required by WOPI/Collabora.",
+                    "type": "integer",
+                    "example": 1782971996000
+                },
+                "collabora_action": {
+                    "type": "string",
+                    "example": "https://collabora.example.com/browser/123?WOPISrc=..."
+                },
+                "file_id": {
+                    "type": "string",
+                    "example": "019f0386-0a00-7a4a-a2d8-30afc0e0c3ad"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFolderDetailResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFolderDetailAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_folder"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFolderDetailResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderDetailResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFolderResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFolderAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_folder"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFolderResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerActionBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeResultResource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerMoveNodeResultAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerActionLocation"
+                },
+                "node_type": {
+                    "type": "string",
+                    "example": "folder"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "moved"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerMoveNodeResultResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeResultAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_move_result"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerNodeAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "extension": {
+                    "type": "string",
+                    "example": "pdf"
+                },
+                "mime_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "operations"
+                },
+                "node_type": {
+                    "type": "string",
+                    "example": "folder"
+                },
+                "parent_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "path_cache": {
+                    "type": "string",
+                    "example": "/root/operations"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "example": 1024
+                },
+                "status": {
+                    "type": "string",
+                    "example": "ready"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerNodeListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerNodeResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "breadcrumb": {
+                            "type": "array",
+                            "items": {
+                                "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerBreadcrumbItem"
+                            }
+                        },
+                        "files": {
+                            "type": "integer",
+                            "example": 8
+                        },
+                        "folders": {
+                            "type": "integer",
+                            "example": 4
+                        },
+                        "is_root": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "parent_uuid": {
+                            "type": "string",
+                            "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 12
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerNodeResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerNodeAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_node"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerPurgeNodeBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerActionBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerPurgeNodeResultResource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerPurgeNodeBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerPurgeNodeBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerPurgeNodeResultAttributes": {
+            "type": "object",
+            "properties": {
+                "node_type": {
+                    "type": "string",
+                    "example": "folder"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "purged"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerPurgeNodeResultResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerPurgeNodeResultAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_purge_result"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerTrashListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerTrashNodeResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "files": {
+                            "type": "integer",
+                            "example": 70
+                        },
+                        "folders": {
+                            "type": "integer",
+                            "example": 50
+                        },
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerTrashNodeAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-31T08:52:03Z"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "extension": {
+                    "type": "string",
+                    "example": "pdf"
+                },
+                "mime_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Documents"
+                },
+                "node_type": {
+                    "type": "string",
+                    "example": "folder"
+                },
+                "path_cache": {
+                    "type": "string",
+                    "example": "/Documents"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "example": 123456
+                },
+                "trashed_at": {
+                    "type": "string",
+                    "example": "2026-04-01T10:00:00Z"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-31T08:52:03Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerTrashNodeResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerTrashNodeAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_trash_node"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetHistoryEntry": {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "example": "easa_signed"
+                },
+                "actor": {
+                    "type": "string",
+                    "example": "019e91e6-2908-7f37-93e6-015ed1b7587d"
+                },
+                "actor_name": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "at": {
+                    "type": "string",
+                    "example": "2026-06-17T10:15:00Z"
+                },
+                "entity_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "entity_type": {
+                    "type": "string",
+                    "example": "easa_release"
+                },
+                "message": {
+                    "type": "string",
+                    "example": "Release to Service (EASA signed)"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetHistoryListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetHistoryEntry"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusAttributes": {
+            "type": "object",
+            "properties": {
+                "complaints": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusComplaint"
+                    }
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-05-29T07:43:06Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "easa_release": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusEASARelease"
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusFile"
+                    }
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusHelicopter"
+                },
+                "maintenance_schedules": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes"
+                    }
+                },
+                "mcf": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusMCF"
+                },
+                "serviced_at": {
+                    "type": "string",
+                    "example": "2026-05-29T07:43:06Z"
+                },
+                "status": {
+                    "type": "string",
+                    "enum": [
+                        "active",
+                        "serviced"
+                    ],
+                    "example": "active"
+                },
+                "summary": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusSummary"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-05-29T07:43:06Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "John Doe"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 100
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "deleted": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "fleet_status_delete"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusFile": {
+            "type": "object",
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "example": "wb"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/fleet/wb.pdf?X-Amz-Signature=abc123"
+                },
+                "file_attachment_id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-111111111111"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "is_mandatory": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "weight_balance.pdf"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "example": 1024000
+                },
+                "thumbnail_download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/fleet/wb.thumb.jpg?X-Amz-Signature=abc123"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 100
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusMarkServicedResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "serviced": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "fleet_status_mark_serviced"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "fleet_status"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightAttributes": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "M-062226-001"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "created_by": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.UserRef"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-04-14"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "deleted_by": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.UserRef"
+                },
+                "draft": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDraftGroup"
+                    }
+                },
+                "mission_id": {
+                    "type": "string",
+                    "example": "019e9640-f7af-7940-80e8-1e9a83013afb"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "draft"
+                },
+                "steps": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightStepItem"
+                    }
+                },
+                "takeover": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightTakeoverSummary"
+                },
+                "total_draft": {
+                    "type": "integer",
+                    "example": 6
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "updated_by": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.UserRef"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDailyInspectionSummary": {
+            "type": "object",
+            "properties": {
+                "date": {
+                    "type": "string",
+                    "example": "17.04.2026"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Ganahl Stefan"
+                },
+                "short_name": {
+                    "type": "string",
+                    "example": "GAN"
+                },
+                "utc_time": {
+                    "type": "string",
+                    "example": "10:57"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataAttributes": {
+            "type": "object",
+            "properties": {
+                "co_pilot": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataCoPilotRef"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "customer_name": {
+                    "type": "string",
+                    "example": "Air Service"
+                },
+                "delivery_note_number": {
+                    "type": "string",
+                    "example": "DN-1001"
+                },
+                "engine": {
+                    "type": "string",
+                    "example": "PW207D1"
+                },
+                "flight_duration_seconds": {
+                    "type": "integer",
+                    "example": 4500
+                },
+                "flight_landing": {
+                    "type": "string",
+                    "example": "2026-04-20T09:15:00Z"
+                },
+                "flight_plan_distance": {
+                    "type": "number",
+                    "example": 120.5
+                },
+                "flight_plan_time_seconds": {
+                    "type": "integer",
+                    "example": 4200
+                },
+                "flight_plan_true_course": {
+                    "type": "number",
+                    "example": 182.3
+                },
+                "flight_positioning": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "flight_red_seconds": {
+                    "type": "integer",
+                    "example": 300
+                },
+                "flight_take_off": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "from": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataLocationRef"
+                },
+                "fuel_after_flight": {
+                    "type": "number",
+                    "example": 280
+                },
+                "fuel_before_flight": {
+                    "type": "number",
+                    "example": 420
+                },
+                "fuel_planning": {
+                    "type": "number",
+                    "example": 390
+                },
+                "fuel_upload": {
+                    "type": "number",
+                    "example": 100
+                },
+                "hec": {
+                    "allOf": [
+                        {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHECDetails"
+                        }
+                    ],
+                    "x-note": "Only returned for SPO missions"
+                },
+                "heslo": {
+                    "allOf": [
+                        {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHESLODetails"
+                        }
+                    ],
+                    "x-note": "Only returned for SPO missions"
+                },
+                "hook_releases": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "landing_count": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "logging": {
+                    "allOf": [
+                        {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOLoggingDetails"
+                        }
+                    ],
+                    "x-note": "Only returned for SPO missions"
+                },
+                "max_n1": {
+                    "type": "number",
+                    "example": 97.5
+                },
+                "max_n2": {
+                    "type": "number",
+                    "example": 98.1
+                },
+                "mission": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataMissionRef"
+                },
+                "other_information": {
+                    "type": "string"
+                },
+                "pax_count": {
+                    "type": "integer",
+                    "example": 4
+                },
+                "roster_details": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterDetailsResponse"
+                },
+                "rotor_brake_cycle": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "status": {
+                    "type": "string",
+                    "example": "in_progress"
+                },
+                "ticket_no": {
+                    "type": "string",
+                    "example": "TKT-001"
+                },
+                "to": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataLocationRef"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataCoPilotRef": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "john.doe@example.com"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataLocationRef": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "WIII"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "label": {
+                    "type": "string",
+                    "example": "WIII"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "General Hospital"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "icao"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataMissionRef": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "flight_data"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHECDetails": {
+            "type": "object",
+            "properties": {
+                "flights": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHECFlight"
+                    }
+                },
+                "loads": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHECLoad"
+                    }
+                },
+                "slings": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHECSling"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHECFlight": {
+            "type": "object",
+            "properties": {
+                "equipment_id": {
+                    "description": "Facility category: hec-rope-label.",
+                    "type": "string"
+                },
+                "equipment_name": {
+                    "type": "string"
+                },
+                "hec_cycle": {
+                    "type": "integer"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "rot": {
+                    "type": "integer"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHECLoad": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                },
+                "load_category": {
+                    "description": "Weight band for the HEC load, e.g. \"bis 199 kg\", \"200-600 kg\", \"600-800 kg\", \"800-1000 kg\".",
+                    "type": "string",
+                    "example": "200-600 kg"
+                },
+                "quantity": {
+                    "type": "integer",
+                    "example": 3
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHECSling": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                },
+                "sling_id": {
+                    "description": "Facility category: hec-rope-length.",
+                    "type": "string"
+                },
+                "sling_name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHESLODetails": {
+            "type": "object",
+            "properties": {
+                "flights": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHESLOFlight"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHESLOFlight": {
+            "type": "object",
+            "properties": {
+                "heslo_rope_label_id": {
+                    "description": "Facility category: heslo-rope-label.",
+                    "type": "string"
+                },
+                "heslo_rope_label_name": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "rot": {
+                    "type": "integer"
+                },
+                "slings": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHESLOSling"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHESLOSling": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                },
+                "sling_id": {
+                    "description": "Facility category: heslo-rope-length.",
+                    "type": "string"
+                },
+                "sling_name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOLoggingDetails": {
+            "type": "object",
+            "properties": {
+                "slings": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOLoggingSling"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOLoggingSling": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                },
+                "sling_id": {
+                    "description": "Facility category: heslo-hook.",
+                    "type": "string"
+                },
+                "sling_name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDraftGroup": {
+            "type": "object",
+            "properties": {
+                "items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDraftItem"
+                    }
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDraftItem": {
+            "type": "object",
+            "properties": {
+                "flight_data_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a55"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "draft"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightHelicopterSummary": {
+            "type": "object",
+            "properties": {
+                "aog": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "designation": {
+                    "type": "string",
+                    "example": "AIRBUS H145"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "D-HYAR"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "type": {
+                    "type": "string",
+                    "example": "H145"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightMissionTypeSummary": {
+            "type": "object",
+            "properties": {
+                "completed": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "draft": {
+                    "type": "integer",
+                    "example": 5
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "flight"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightStepItem": {
+            "type": "object",
+            "properties": {
+                "complete": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "completed_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "completed_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "mission_type": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightMissionTypeSummary"
+                    }
+                },
+                "phase": {
+                    "type": "string",
+                    "example": "duty_roster"
+                },
+                "position": {
+                    "type": "string",
+                    "example": "takeover"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "completed"
+                },
+                "step": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightTakeoverSummary": {
+            "type": "object",
+            "properties": {
+                "daily_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDailyInspectionSummary"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightHelicopterSummary"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterDetailsResponse"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterAttributes": {
+            "type": "object",
+            "properties": {
+                "aog": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "aog_reason": {
+                    "type": "string",
+                    "example": "Main rotor gearbox fault"
+                },
+                "consumption_lt_min": {
+                    "type": "number",
+                    "example": 4.1
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterAuditUser"
+                },
+                "designation": {
+                    "type": "string",
+                    "example": "OE-XHZ"
+                },
+                "dry": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "engine_1": {
+                    "type": "string",
+                    "example": "TM"
+                },
+                "engine_2": {
+                    "type": "string",
+                    "example": "TM"
+                },
+                "foto": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterFoto"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "ABC-0001"
+                },
+                "igb": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "is_in_use": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "last_daily_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspection"
+                },
+                "lh": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "maintenance_schedules": {
+                    "description": "MaintenanceSchedules mirrors the helicopter's latest fleet status. It\nalways lists every inspection type; entries without data are empty.",
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes"
+                    }
+                },
+                "mgb": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Primary HEMS helicopter"
+                },
+                "nr1": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "nr2": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "rh": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 10
+                },
+                "status": {
+                    "description": "Status is the operational status of the helicopter (read-time derived).\nValues: \"available\", \"booked\", \"aog\", \"mcf\". Precedence: mcf \u003e aog \u003e booked \u003e available.\n\"booked\" = active flight assignment; \"aog\" = air_on_ground flag OR an open complaint\ngrounding it (non-MEL, or MEL past its grace deadline); \"mcf\" = a pending maintenance\ncheck flight (MCF created, not yet passed).",
+                    "type": "string",
+                    "enum": [
+                        "available",
+                        "booked",
+                        "aog",
+                        "mcf"
+                    ],
+                    "example": "available"
+                },
+                "tgb": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "type": {
+                    "type": "string",
+                    "example": "EC-135"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterAuditUser"
+                },
+                "utc_offset": {
+                    "type": "integer",
+                    "example": -1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileBulkError": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "HELICOPTER_FILE_INVALID_PAYLOAD"
+                },
+                "detail": {
+                    "type": "string",
+                    "example": "helicopter_id is invalid UUID"
+                },
+                "error_code": {
+                    "type": "string",
+                    "example": "4220318"
+                },
+                "status": {
+                    "type": "integer",
+                    "example": 422
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Validation error"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionAttachment": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "file_name": {
+                    "type": "string",
+                    "example": "Before Flight Checklist.pdf"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionAttributes": {
+            "type": "object",
+            "properties": {
+                "files": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionSections"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionHelicopter"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionHelicopter": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "AIRBUS H145"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionItem": {
+            "type": "object",
+            "properties": {
+                "attachment": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionAttachment"
+                },
+                "attachment_pending": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "helicopter_file_id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "is_mandatory": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "is_template": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "section": {
+                    "type": "string",
+                    "example": "bfi"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionResponse"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionResponse": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter_file_collection"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionSections": {
+            "type": "object",
+            "properties": {
+                "after": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionItem"
+                    }
+                },
+                "before": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionItem"
+                    }
+                },
+                "prepare": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Resource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileDeleteAttributes": {
+            "type": "object",
+            "properties": {
+                "deleted": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileDeleteResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileDeleteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter_file_delete"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileDeleteResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterFileAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter_file"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileUpdateBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Resource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileUpdateBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUpdateBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileUploadIntentAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter_file_upload_intent"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterNextReportNumberAttributes": {
+            "type": "object",
+            "properties": {
+                "identifier": {
+                    "type": "string",
+                    "example": "ABC"
+                },
+                "report_number": {
+                    "type": "string",
+                    "example": "ABC-0001"
+                },
+                "sequence": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterNextReportNumberResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterNextReportNumberAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter_report_number"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterNextReportNumberResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterNextReportNumberResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MCFAttributes": {
+            "type": "object",
+            "properties": {
+                "af_hours": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "completed_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "completed_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-06-17"
+                },
+                "decided_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "decided_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "is_cleared": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "is_complete": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "is_pending": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landing_count": {
+                    "type": "integer",
+                    "example": 3
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Vibration within limits"
+                },
+                "result": {
+                    "type": "string",
+                    "enum": [
+                        "passed",
+                        "failed"
+                    ],
+                    "example": "passed"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "utc_time": {
+                    "type": "string",
+                    "example": "2026-06-17T08:30:00Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MCFListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MCFResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "mcf"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MCFResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MasterSettingsAttributes": {
+            "type": "object",
+            "properties": {
+                "company_name": {
+                    "type": "string",
+                    "example": "Wucher"
+                },
+                "cover_file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "cover_original_size_bytes": {
+                    "type": "integer",
+                    "example": 2048000
+                },
+                "cover_thumbnail_url": {
+                    "type": "string",
+                    "example": "https://cdn.example.com/cover.thumb.png"
+                },
+                "cover_url": {
+                    "type": "string",
+                    "example": "https://cdn.example.com/cover.png"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "logo_file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "logo_original_size_bytes": {
+                    "type": "integer",
+                    "example": 1024000
+                },
+                "logo_thumbnail_url": {
+                    "type": "string",
+                    "example": "https://cdn.example.com/logo.thumb.png"
+                },
+                "logo_url": {
+                    "type": "string",
+                    "example": "https://cdn.example.com/logo.png"
+                },
+                "subtitle": {
+                    "type": "string",
+                    "example": "Flight operations platform"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Welcome to Wucher"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraAttributes": {
+            "type": "object",
+            "properties": {
+                "MS_ENTRA_AUTHORITY": {
+                    "type": "string",
+                    "example": "https://login.microsoftonline.com/"
+                },
+                "MS_ENTRA_CLIENT_ID": {
+                    "type": "string",
+                    "example": "your-client-id"
+                },
+                "MS_ENTRA_CLIENT_SECRET": {
+                    "type": "string",
+                    "example": "********"
+                },
+                "MS_ENTRA_REDIRECT_URL": {
+                    "type": "string",
+                    "example": "https://example.com/api/v1/auth/microsoft/callback"
+                },
+                "MS_ENTRA_SCOPES": {
+                    "type": "string",
+                    "example": "openid,profile,email"
+                },
+                "MS_ENTRA_TENANT_ID": {
+                    "type": "string",
+                    "example": "your-tenant-id"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "master_settings_microsoft_entra_sso"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MasterSettingsResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "master_settings"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MasterSettingsResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "end_time": {
+                    "type": "string",
+                    "example": "22:05"
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionFileItem"
+                    }
+                },
+                "flight": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionFlightRef"
+                },
+                "forms": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionForms"
+                },
+                "mission_code": {
+                    "type": "string",
+                    "example": "HEMS-26-1"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Mission note"
+                },
+                "start_time": {
+                    "type": "string",
+                    "example": "04:49"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "completed"
+                },
+                "subtypes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionSubtypeRef"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 42
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionFileItem": {
+            "type": "object",
+            "properties": {
+                "attachment_id": {
+                    "type": "string",
+                    "example": "019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/brief.pdf?X-Amz-Signature=..."
+                },
+                "file_name": {
+                    "type": "string",
+                    "example": "mission-brief.pdf"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e"
+                },
+                "thumbnail_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/thumbnails/2026/04/05/brief.png?X-Amz-Signature=..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionFlightRef": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "M-062226-001"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-04-20"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionForms": {
+            "type": "object",
+            "properties": {
+                "flight_data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "mission"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionSubtypeRef": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a99"
+                },
+                "subtype": {
+                    "type": "string",
+                    "example": "PRIM"
+                },
+                "subtype_name": {
+                    "type": "string",
+                    "example": "Nicht transportfaehig"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionTypeAttributes": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "HEMS"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "HEMS"
+                },
+                "subtypes": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionTypeSubtypeItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionTypeListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionTypeResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionTypeResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionTypeAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a77"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "mission_type"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionTypeSubtypeItem": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "PRIM"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a99"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Primary"
+                },
+                "task_name": {
+                    "type": "string",
+                    "example": "Nicht transportfaehig"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.OtherPersonAttributes": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "guest@example.com"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Guest Person"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.OtherPersonListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.OtherPersonResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "other_person"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.OtherPersonResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ReserveAcListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ReserveAcResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "reserve_ac"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ReserveAcResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "doctor@example.com"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Hunter Wolfgang"
+                },
+                "role": {
+                    "type": "string",
+                    "example": "doctor"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverDutyRosterDetailsResponse": {
+            "type": "object",
+            "properties": {
+                "doctor": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew"
+                    }
+                },
+                "helper": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew"
+                    }
+                },
+                "other_person": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew"
+                    }
+                },
+                "pilot": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterPilotCrew"
+                    }
+                },
+                "rescuer": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverDutyRosterPilotCrew": {
+            "type": "object",
+            "properties": {
+                "co_pilot": {
+                    "type": "boolean"
+                },
+                "crew_type": {
+                    "type": "string",
+                    "example": "main"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "pilot@example.com"
+                },
+                "examiner": {
+                    "type": "boolean"
+                },
+                "flight_instructor": {
+                    "type": "boolean"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "line_checker": {
+                    "type": "boolean"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Hunter Wolfgang"
+                },
+                "role": {
+                    "type": "string",
+                    "example": "pilot"
+                },
+                "supervisor": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverFileAttributes": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/takeover-report.pdf?X-Amz-Signature=..."
+                },
+                "file_attachment_id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-222222222222"
+                },
+                "file_name": {
+                    "type": "string",
+                    "example": "takeover-report.pdf"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverFileResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverFileAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-111111111111"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "takeover_file"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverHelicopter": {
+            "type": "object",
+            "properties": {
+                "designation": {
+                    "type": "string",
+                    "example": "OE-XHZ"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "1234"
+                },
+                "last_daily_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspection"
+                },
+                "maintenance_schedules": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes"
+                    }
+                },
+                "type": {
+                    "type": "string",
+                    "example": "EC-135"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverResponseAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "takeover"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverResponseAttributes": {
+            "type": "object",
+            "properties": {
+                "base": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseInfo"
+                },
+                "base_id": {
+                    "type": "string"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "duty_date": {
+                    "type": "string"
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverFileResource"
+                    }
+                },
+                "flight_id": {
+                    "type": "string"
+                },
+                "flight_inspection_id": {
+                    "type": "string"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverHelicopter"
+                },
+                "helicopter_id": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcInspectionSummary"
+                },
+                "notes": {
+                    "type": "string"
+                },
+                "reserve_ac_id": {
+                    "type": "string"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterDetailsResponse"
+                },
+                "shift_end": {
+                    "type": "string"
+                },
+                "shift_start": {
+                    "type": "string"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.UserRef": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Ganahl Stefan"
+                },
+                "uuid": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.AirRescuerChecklistBaseInfo": {
+            "type": "object",
+            "properties": {
+                "base_abbreviation": {
+                    "type": "string",
+                    "example": "G1"
+                },
+                "base_category": {
+                    "type": "string",
+                    "example": "hems"
+                },
+                "base_name": {
+                    "type": "string",
+                    "example": "Gallus 1 - Zurs Lech"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.AirRescuerChecklistItemInput": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Oxygen supply check"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerAttachmentAttributes": {
+            "type": "object",
+            "properties": {
+                "attached_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "category": {
+                    "type": "string",
+                    "example": "document"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "file_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_primary": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "ref_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "ref_type": {
+                    "type": "string",
+                    "example": "helicopter"
+                },
+                "sort_order": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFileAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "extension": {
+                    "type": "string",
+                    "example": "pdf"
+                },
+                "failed_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "failure_reason": {
+                    "type": "string",
+                    "example": ""
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "folder_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_template": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "mime_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "policy.pdf"
+                },
+                "name_normalized": {
+                    "type": "string",
+                    "example": "policy.pdf"
+                },
+                "processed_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "processing_started_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "purge_at": {
+                    "type": "string",
+                    "example": "2026-04-12T03:04:05Z"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "example": 1024
+                },
+                "status": {
+                    "type": "string",
+                    "example": "validated"
+                },
+                "trashed_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "upload_error": {
+                    "type": "string",
+                    "example": ""
+                },
+                "validated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFileAuditAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFileDetailAttributes": {
+            "type": "object",
+            "properties": {
+                "audit": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileAuditAttributes"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "extension": {
+                    "type": "string",
+                    "example": "pdf"
+                },
+                "is_template": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "location": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileLocationAttributes"
+                },
+                "mime_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "policy.pdf"
+                },
+                "name_normalized": {
+                    "type": "string",
+                    "example": "policy.pdf"
+                },
+                "preview_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.preview.pdf?X-Amz-Signature=..."
+                },
+                "processing": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileProcessingAttributes"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "example": 1024
+                },
+                "status": {
+                    "type": "string",
+                    "example": "ready"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFileLocationAttributes": {
+            "type": "object",
+            "properties": {
+                "folder_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFileProcessingAttributes": {
+            "type": "object",
+            "properties": {
+                "failed_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "failure_reason": {
+                    "type": "string",
+                    "example": "processing validation failed"
+                },
+                "processed_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "processing_started_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "validated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFileUploadIntentAttributes": {
+            "type": "object",
+            "properties": {
+                "expires_at": {
+                    "type": "string",
+                    "example": "2026-04-05T07:29:34Z"
+                },
+                "expires_in_seconds": {
+                    "type": "integer",
+                    "example": 900
+                },
+                "file": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileUploadFile"
+                },
+                "method": {
+                    "type": "string",
+                    "example": "PUT"
+                },
+                "object": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileUploadObject"
+                },
+                "required_headers": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "upload_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFolderAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "depth": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "name": {
+                    "type": "string",
+                    "example": "operations"
+                },
+                "name_normalized": {
+                    "type": "string",
+                    "example": "operations"
+                },
+                "parent_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "path_cache": {
+                    "type": "string",
+                    "example": "/root/operations"
+                },
+                "purge_at": {
+                    "type": "string",
+                    "example": "2026-04-12T03:04:05Z"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFolderAuditAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFolderDetailAttributes": {
+            "type": "object",
+            "properties": {
+                "audit": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFolderAuditAttributes"
+                },
+                "depth": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "location": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFolderLocationAttributes"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "operations"
+                },
+                "name_normalized": {
+                    "type": "string",
+                    "example": "operations"
+                },
+                "path_cache": {
+                    "type": "string",
+                    "example": "/root/operations"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFolderLocationAttributes": {
+            "type": "object",
+            "properties": {
+                "parent_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileUploadFile": {
+            "type": "object",
+            "properties": {
+                "mime_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "policy-final.pdf"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "example": 1024
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileUploadObject": {
+            "type": "object",
+            "properties": {
+                "bucket": {
+                    "type": "string",
+                    "example": "wucher-file-dev"
+                },
+                "key": {
+                    "type": "string",
+                    "example": "files/2026/04/05/018f3a5c7a6f7c2a8d4a4b5b1f6c8e9d.pdf"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusComplaint": {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusComplaintAction"
+                },
+                "aircraft_hours_at_report": {
+                    "type": "string"
+                },
+                "description": {
+                    "type": "string"
+                },
+                "flight_id": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "mel": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusComplaintMEL"
+                },
+                "nsr": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusComplaintNSR"
+                },
+                "reported_at": {
+                    "type": "string"
+                },
+                "reported_by": {
+                    "type": "string"
+                },
+                "reported_by_name": {
+                    "type": "string"
+                },
+                "reported_by_short": {
+                    "type": "string"
+                },
+                "status": {
+                    "type": "string",
+                    "enum": [
+                        "active_non_mel",
+                        "active_mel",
+                        "serviced"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusComplaintAction": {
+            "type": "object",
+            "properties": {
+                "aircraft_hours_at_fix": {
+                    "type": "string"
+                },
+                "signed_at": {
+                    "type": "string"
+                },
+                "signed_by": {
+                    "type": "string"
+                },
+                "signed_by_name": {
+                    "type": "string"
+                },
+                "signed_by_short": {
+                    "type": "string"
+                },
+                "taken": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusComplaintMEL": {
+            "type": "object",
+            "properties": {
+                "classified_at": {
+                    "type": "string"
+                },
+                "classified_by": {
+                    "type": "string"
+                },
+                "classified_by_name": {
+                    "type": "string"
+                },
+                "classified_by_short": {
+                    "type": "string"
+                },
+                "deadline": {
+                    "type": "string"
+                },
+                "severity": {
+                    "type": "integer",
+                    "enum": [
+                        0,
+                        1,
+                        2,
+                        3,
+                        4
+                    ]
+                },
+                "severity_label": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusComplaintNSR": {
+            "type": "object",
+            "properties": {
+                "decided_at": {
+                    "type": "string"
+                },
+                "decided_by": {
+                    "type": "string"
+                },
+                "decided_by_name": {
+                    "type": "string"
+                },
+                "decided_by_short": {
+                    "type": "string"
+                },
+                "is_nsr": {
+                    "type": "boolean"
+                },
+                "reason": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusEASARelease": {
+            "type": "object",
+            "properties": {
+                "easa_ac_hours": {
+                    "type": "string"
+                },
+                "easa_date": {
+                    "type": "string"
+                },
+                "easa_location": {
+                    "type": "string"
+                },
+                "easa_maint_manual_rev_airframe": {
+                    "type": "string"
+                },
+                "easa_maint_manual_rev_engine": {
+                    "type": "string"
+                },
+                "easa_permit_no": {
+                    "type": "string"
+                },
+                "easa_signer_id": {
+                    "type": "string"
+                },
+                "easa_wo_no": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "is_signed": {
+                    "type": "boolean"
+                },
+                "missing_sign_fields": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "signed_at": {
+                    "type": "string"
+                },
+                "signed_by": {
+                    "type": "string"
+                },
+                "signed_by_name": {
+                    "type": "string"
+                },
+                "signed_by_short": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusFileAttributes": {
+            "type": "object",
+            "required": [
+                "category",
+                "file_id"
+            ],
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "enum": [
+                        "wb",
+                        "bfi"
+                    ],
+                    "example": "wb"
+                },
+                "file_id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "is_mandatory": {
+                    "description": "IsMandatory — when true, this file must be checked (is_done) during takeover.",
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusHelicopter": {
+            "type": "object",
+            "properties": {
+                "designation": {
+                    "type": "string",
+                    "example": "AIRBUS H145"
+                },
+                "flight_id": {
+                    "description": "FlightID — id of the aircraft's current active flight (present only when it is in\nuse / booked). The fleet page uses it to create an EASA release scoped to the flight.",
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "D-HEMS"
+                },
+                "status": {
+                    "type": "string",
+                    "enum": [
+                        "available",
+                        "booked",
+                        "aog",
+                        "mcf"
+                    ],
+                    "example": "available"
+                },
+                "status_reasons": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusHelicopterReason"
+                    }
+                },
+                "type": {
+                    "type": "string",
+                    "example": "EC-135"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusHelicopterReason": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "enum": [
+                        "manual_aog",
+                        "mel_expired",
+                        "non_mel_pending",
+                        "inspection_overdue"
+                    ]
+                },
+                "complaint_id": {
+                    "type": "string"
+                },
+                "detail": {
+                    "type": "string"
+                },
+                "schedule_id": {
+                    "type": "string"
+                },
+                "since": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusMCF": {
+            "type": "object",
+            "properties": {
+                "active": {
+                    "description": "Active — true when the helicopter is currently in MCF (an open draft, or a signed\nbut failed MCF still needing a re-flight); false when cleared/cancelled/none.",
+                    "type": "boolean"
+                },
+                "af_hours": {
+                    "description": "AFHours / LandingCount present only once the MCF is signed; omitted for none/draft/cancelled.",
+                    "type": "string"
+                },
+                "date": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "landing_count": {
+                    "type": "integer"
+                },
+                "sign": {
+                    "description": "Sign — true once the MCF is completed/signed; false while it is still a draft.",
+                    "type": "boolean"
+                },
+                "signed_by": {
+                    "description": "SignedBy / SignedByName / SignedByShort — who signed (completed) the MCF; empty while unsigned.",
+                    "type": "string"
+                },
+                "signed_by_name": {
+                    "type": "string"
+                },
+                "signed_by_short": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusSummary": {
+            "type": "object",
+            "properties": {
+                "airframe": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusSummaryAirframe"
+                },
+                "engine_1": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusSummaryEngine"
+                },
+                "engine_2": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusSummaryEngine"
+                },
+                "flight_reports": {
+                    "type": "number"
+                },
+                "hook_releases": {
+                    "type": "number"
+                },
+                "landings": {
+                    "type": "number"
+                },
+                "rotor_brake_cycles": {
+                    "type": "number"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusSummaryAirframe": {
+            "type": "object",
+            "properties": {
+                "cycles": {
+                    "type": "number"
+                },
+                "hours": {
+                    "type": "number"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusSummaryEngine": {
+            "type": "object",
+            "properties": {
+                "ccc": {
+                    "type": "number"
+                },
+                "gpc_ng_n1": {
+                    "type": "number"
+                },
+                "hours": {
+                    "type": "number"
+                },
+                "ptc_nf_n2": {
+                    "type": "number"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterAuditUser": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "John Doe"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterFileAttributes": {
+            "type": "object",
+            "properties": {
+                "attachment_pending": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "file_attachment_id": {
+                    "type": "string",
+                    "example": "019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e"
+                },
+                "file_name": {
+                    "type": "string",
+                    "example": "Before Flight Checklist.pdf"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "helicopter_name": {
+                    "type": "string",
+                    "example": "AIRBUS H145"
+                },
+                "is_mandatory": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "is_template": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "section": {
+                    "type": "string",
+                    "example": "bfi"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterFoto": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/helicopter/foto.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Expires=900\u0026X-Amz-Signature=abc123"
+                },
+                "original_size_bytes": {
+                    "type": "integer",
+                    "example": 1024000
+                },
+                "thumbnail_download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/helicopter/foto.thumb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Expires=900\u0026X-Amz-Signature=abc123"
+                },
+                "uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterInspectionFilesChecklist": {
+            "type": "object",
+            "properties": {
+                "completed": {
+                    "type": "integer",
+                    "example": 47
+                },
+                "total": {
+                    "type": "integer",
+                    "example": 47
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterLastDailyBase": {
+            "type": "object",
+            "properties": {
+                "base_abbreviation": {
+                    "type": "string",
+                    "example": "G1"
+                },
+                "base_name": {
+                    "type": "string",
+                    "example": "Gallus 1 - Zurs Lech"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hems"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspection": {
+            "type": "object",
+            "properties": {
+                "base": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterLastDailyBase"
+                },
+                "inspected_at": {
+                    "type": "string",
+                    "example": "2026-05-25T07:47:00Z"
+                },
+                "inspection_files_checklist": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterInspectionFilesChecklist"
+                },
+                "inspection_id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "inspector": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspector"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "inspected_cleared"
+                },
+                "utc_time": {
+                    "type": "string",
+                    "example": "07:47"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspector": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "license_no": {
+                    "type": "string",
+                    "example": "4521"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Teodora Lesmana"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes": {
+            "type": "object",
+            "properties": {
+                "due": {
+                    "type": "string",
+                    "example": "1200"
+                },
+                "ext": {
+                    "type": "string",
+                    "example": "1300"
+                },
+                "inspection_type": {
+                    "type": "string",
+                    "example": "A/F"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "100H"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcAircraftSummary": {
+            "type": "object",
+            "properties": {
+                "aog": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "designation": {
+                    "type": "string",
+                    "example": "AIRBUS H145"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "D-HYAR"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "type": {
+                    "type": "string",
+                    "example": "H145"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcAircraftSummary"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcInspectionSummary"
+                },
+                "last_daily_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcLastDailyInfo"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "pending"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcBeforeInspectionFields": {
+            "type": "object",
+            "properties": {
+                "fuel_added_amount": {
+                    "type": "number"
+                },
+                "fuel_amount": {
+                    "type": "number"
+                },
+                "fuel_unit": {
+                    "type": "string"
+                },
+                "hydraulic_lh_checked": {
+                    "type": "boolean"
+                },
+                "hydraulic_rh_checked": {
+                    "type": "boolean"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "oil_engine_nr1_checked": {
+                    "type": "boolean"
+                },
+                "oil_engine_nr2_checked": {
+                    "type": "boolean"
+                },
+                "oil_transmission_igb_checked": {
+                    "type": "boolean"
+                },
+                "oil_transmission_mgb_checked": {
+                    "type": "boolean"
+                },
+                "oil_transmission_tgb_checked": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcBeforeSectionDTO": {
+            "type": "object",
+            "properties": {
+                "completed": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "done_file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO"
+                    }
+                },
+                "fields": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcBeforeInspectionFields"
+                },
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO"
+                    }
+                },
+                "total": {
+                    "type": "integer",
+                    "example": 3
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "file_attachment_id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-222222222222"
+                },
+                "file_name": {
+                    "type": "string",
+                    "example": "Before Flight Checklist.pdf"
+                },
+                "helicopter_file_id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-111111111111"
+                },
+                "is_done": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "is_mandatory": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcFleetStatusFileSectionDTO": {
+            "type": "object",
+            "properties": {
+                "completed": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "done_file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO"
+                    }
+                },
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO"
+                    }
+                },
+                "total": {
+                    "type": "integer",
+                    "example": 2
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcInspectionSummary": {
+            "type": "object",
+            "properties": {
+                "before": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcBeforeSectionDTO"
+                },
+                "fleet_status_file": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFleetStatusFileSectionDTO"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "inspection_date": {
+                    "type": "string",
+                    "example": "2026-04-15"
+                },
+                "prepare": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcPrepareSectionDTO"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcLastDailyInfo": {
+            "type": "object",
+            "properties": {
+                "date": {
+                    "type": "string",
+                    "example": "17.04.2026"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Ganahl Stefan"
+                },
+                "short_name": {
+                    "type": "string",
+                    "example": "GAN"
+                },
+                "utc_time": {
+                    "type": "string",
+                    "example": "10:57"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcPrepareFields": {
+            "type": "object",
+            "properties": {
+                "notam_briefing": {
+                    "type": "boolean"
+                },
+                "operational_flight_plan": {
+                    "type": "boolean"
+                },
+                "weather_briefing": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcPrepareSectionDTO": {
+            "type": "object",
+            "properties": {
+                "completed": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "done_file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO"
+                    }
+                },
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO"
+                    }
+                },
+                "prepare_fields": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcPrepareFields"
+                },
+                "total": {
+                    "type": "integer",
+                    "example": 3
+                }
+            }
+        },
+        "wucher_internal_transport_http_jsonapi.Document": {
+            "type": "object",
+            "properties": {
+                "data": {},
+                "meta": {}
+            }
+        },
+        "wucher_internal_transport_http_jsonapi.ErrorDocument": {
+            "type": "object",
+            "properties": {
+                "errors": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorObject"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_jsonapi.ErrorObject": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string"
+                },
+                "detail": {
+                    "type": "string"
+                },
+                "error_code": {
+                    "type": "string"
+                },
+                "source": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorSource"
+                },
+                "status": {
+                    "type": "string"
+                },
+                "title": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_jsonapi.ErrorSource": {
+            "type": "object",
+            "properties": {
+                "pointer": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_jsonapi.Resource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "additionalProperties": {}
+                },
+                "id": {
+                    "type": "string"
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        }
+    },
+    "tags": [
+        {
+            "description": "Corrective-action sign-off for a helicopter. After a complaint's action_taken is recorded, it is signed off here (POST /action-signoffs/sign with complaint_id); a fleet-wide sign-off (no complaint_id) is also supported. A signed sign-off is the prerequisite for creating an EASA maintenance release.",
+            "name": "Complaints - Sign Off"
+        }
+    ]
+}`
+
+// SwaggerInfo holds exported Swagger Info so clients can modify it
+var SwaggerInfo = &swag.Spec{
+	Version:          "1.0",
+	Host:             "",
+	BasePath:         "/",
+	Schemes:          []string{},
+	Title:            "Wucher API",
+	Description:      "Wucher backend API (JSON:API).\n\nAuth Flow (Email/Password):\n1) POST /api/v1/auth/register\n2) Check email, open verify link (GET /api/v1/auth/verify-email)\n3) POST /api/v1/auth/login\n- If TOTP enabled: response 202 with challenge_token\n4) POST /api/v1/auth/totp/verify (challenge_token + code) -> cookies\n\nAuth Flow (TOTP setup):\n1) POST /api/v1/auth/totp/setup -> secret + otpauth_url (enabled=false)\n2) POST /api/v1/auth/totp/confirm -> enabled=true\n\nAuth Flow (Microsoft Entra SSO):\n1) GET /api/v1/auth/microsoft/login -> redirect to Microsoft\n2) Microsoft redirects to /api/v1/auth/microsoft/callback\n3) Backend checks existing SSO mapping (no auto-register)\n4) If linked user exists -> set cookies + optional redirect to AUTH_SSO_SUCCESS_REDIRECT\n5) If mapping not linked -> login rejected (401)\n6) Existing authenticated user can link/unlink via /api/v1/auth/sso/link and /api/v1/auth/sso/unlink",
+	InfoInstanceName: "swagger",
+	SwaggerTemplate:  docTemplate,
+	LeftDelim:        "{{",
+	RightDelim:       "}}",
+}
+
+func init() {
+	swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
+}
diff --git a/docs/docs_test.go b/docs/docs_test.go
new file mode 100644
index 0000000..6b9a857
--- /dev/null
+++ b/docs/docs_test.go
@@ -0,0 +1,17 @@
+package docs
+
+import (
+	"testing"
+
+	"github.com/swaggo/swag"
+)
+
+func TestInitRegistersSwaggerSpec(t *testing.T) {
+	registered := swag.GetSwagger(SwaggerInfo.InstanceName())
+	if registered == nil {
+		t.Fatalf("swagger spec %q was not registered", SwaggerInfo.InstanceName())
+	}
+	if registered.ReadDoc() == "" {
+		t.Fatalf("registered swagger doc is empty")
+	}
+}
diff --git a/docs/duty-roster-migrations.md b/docs/duty-roster-migrations.md
new file mode 100644
index 0000000..8ed551b
--- /dev/null
+++ b/docs/duty-roster-migrations.md
@@ -0,0 +1,74 @@
+# Duty Roster Migrations
+
+Catatan eksekusi 6 file migrasi duty roster di [`migrations/`](../migrations/).
+
+## Konfigurasi Tool Migrasi
+
+Tool migrasi yang dipakai project ini adalah `goose` ([Makefile:5](../Makefile#L5)) dengan direktori target:
+
+```makefile
+GOOSE_DIR ?= migrations/goose
+```
+
+**Konsekuensi:** `make migrate-up` hanya menjalankan file di [`migrations/goose/`](../migrations/goose/). Semua file `.sql` di root [`migrations/`](../migrations/) — termasuk 6 file duty roster — **tidak otomatis dieksekusi**. Mereka berfungsi sebagai script SQL ad-hoc / log historis dan harus dijalankan manual (`mysql < file.sql`) atau dipindahkan ke `migrations/goose/` dengan format `-- +goose Up` / `-- +goose Down`.
+
+## Urutan Eksekusi (by Timestamp)
+
+Goose mengurutkan file by filename ascending. Untuk dua file dengan timestamp sama (`20260502`), urutannya alfabetis: `duty` < `purge`.
+
+```
+1. 20260408_hems_duty_roster_crews_confirm_at.sql
+2. 20260429_rename_duty_roster_tables.sql
+3. 20260430_normalize_duty_roster_legacy.sql
+4. 20260502_duty_roster_permissions_unification.sql
+5. 20260502_purge_legacy_hems_duty_roster_permissions.sql
+6. 20260504_duty_roster_drop_unique_base_date.sql
+```
+
+## Efek per File
+
+| # | File | Efek di DB |
+|---|---|---|
+| 1 | [`20260408_hems_duty_roster_crews_confirm_at.sql`](../migrations/20260408_hems_duty_roster_crews_confirm_at.sql) | `ALTER TABLE hems_duty_roster_crews ADD COLUMN confirm_at DATETIME NULL` (nama tabel lama). Idempoten via `IF NOT EXISTS`. |
+| 2 | [`20260429_rename_duty_roster_tables.sql`](../migrations/20260429_rename_duty_roster_tables.sql) | `RENAME TABLE hems_duty_rosters → duty_rosters` dan `hems_duty_roster_crews → duty_roster_crews`. Pakai guard cek `information_schema.TABLES` jadi idempoten. |
+| 3 | [`20260430_normalize_duty_roster_legacy.sql`](../migrations/20260430_normalize_duty_roster_legacy.sql) | (a) Rename tabel **lagi** dengan guard sama (no-op kalau #2 sukses). (b) Rename kolom `hems_base_id → base_id` di `duty_rosters`. (c) Ensure `confirm_at` ada di `duty_roster_crews` baru (dan di tabel lama jika masih ada). (d) Rewire FK `roster_crews.roster_id` & `duty_roster_other_persons.roster_id` supaya reference `duty_rosters` (bukan `hems_duty_rosters`). |
+| 4 | [`20260502_duty_roster_permissions_unification.sql`](../migrations/20260502_duty_roster_permissions_unification.sql) | Insert 4 permission canonical: `duty_roster.{create,read,update,delete}` (skip via `WHERE NOT EXISTS`). Grant ke role yang punya legacy `hems_duty_roster.*` ke canonical baru, anti-duplikasi via `LEFT JOIN ... NOT EXISTS`. **Tidak menghapus legacy.** |
+| 5 | [`20260502_purge_legacy_hems_duty_roster_permissions.sql`](../migrations/20260502_purge_legacy_hems_duty_roster_permissions.sql) | (a) Re-insert canonical (no-op jika #4 sudah jalan). (b) Re-grant (no-op). (c) `DELETE FROM role_permissions WHERE permission.key IN (legacy)`. (d) `DELETE FROM permissions WHERE key IN (legacy)`. |
+| 6 | [`20260504_duty_roster_drop_unique_base_date.sql`](../migrations/20260504_duty_roster_drop_unique_base_date.sql) | `DROP INDEX idx_roster_base_date` (sebelumnya unique). `CREATE INDEX idx_roster_base_date ON duty_rosters(base_id, duty_date)` non-unique. **Konsekuensi aplikasi**: schema tidak lagi mencegah multiple roster di pasangan `(base_id, duty_date)` yang sama — kode handler harus mendukung skenario ini (lihat [`ensureRosterDates`](../internal/transport/http/handlers/duty_roster_handler.go) yang sebelumnya dedup-by-date). |
+
+## Overlap & Redundansi
+
+- **#2 ⊂ #3** — File `0430_normalize_legacy` sudah include semua rename dari `0429` dengan guard yang sama. File `0429` secara fungsional redundant; akan no-op jika dijalankan setelah `0430`.
+- **#4 ⊂ #5** — File `0502_purge_legacy` adalah superset dari `0502_unification`. Insert + grant identik, lalu tambah `DELETE`. File `0502_unification` redundant.
+
+## Idempotensi Re-run
+
+| File | Idempoten? | Catatan |
+|---|---|---|
+| #1 | Ya | `ADD COLUMN IF NOT EXISTS` |
+| #2 | Ya | Guard via `information_schema.TABLES` |
+| #3 | Ya | Setiap `ALTER` dibungkus prepared statement dengan kondisi |
+| #4 | Ya | `WHERE NOT EXISTS` untuk insert + `LEFT JOIN ... IS NULL` untuk grant |
+| #5 | Ya | Sama dengan #4, ditambah `DELETE` (idempoten karena hanya hapus key legacy) |
+| **#6** | **TIDAK** | `DROP INDEX idx_roster_base_date` tanpa guard. Re-run setelah index sudah di-drop + recreate (sebagai non-unique) akan **gagal** karena nama indexnya sama. Mestinya pakai prepared statement guard yang cek `information_schema.STATISTICS`. |
+
+## Versi Minimal yang Setara
+
+Dengan urutan dijalankan penuh, efek akhirnya cukup dicapai dengan 4 file:
+
+```
+0408_..._confirm_at        (kompat untuk env yang masih punya hems_duty_*)
+0430_normalize_legacy      (rename tabel + kolom + FK + confirm_at — superset dari 0429)
+0502_purge_legacy          (canonical perm + delete legacy — superset dari 0502_unification)
+0504_drop_unique_base_date (butuh tambah guard agar idempoten)
+```
+
+Untuk env yang sudah pasti **fresh** (tanpa sisa `hems_duty_*` apa pun), kelima file di atas bisa digabung jadi satu file goose-format dengan branch yang relevan saja. **Sebelum melakukan ini, pastikan tidak ada DB target yang masih nyangkut di mid-state** — file individual lebih aman selama transisi.
+
+## Bug yang Pernah Ditemukan Akibat #6
+
+Setelah `idx_roster_base_date` jadi non-unique, beberapa baris kode aplikasi yang asumsi unique (`base_id`, `duty_date`) jadi salah:
+
+- [`ensureRosterDates`](../internal/transport/http/handlers/duty_roster_handler.go) di handler GET `/duty-roster/get-all` & `/get-all/dt` sebelumnya pakai `map[string]R` keyed by date — multiple roster di tanggal sama di-overwrite, hanya 1 yang muncul. Sudah diperbaiki pakai `map[string][]R` (multi-value).
+
+Pastikan setiap kode baru yang query/iterasi roster per `(base_id, duty_date)` menyadari bahwa kombinasi ini tidak lagi unique.
diff --git a/docs/error-catalog.md b/docs/error-catalog.md
new file mode 100644
index 0000000..40f18b2
--- /dev/null
+++ b/docs/error-catalog.md
@@ -0,0 +1,735 @@
+# Error Catalog
+
+Dokumen ini berisi daftar lengkap kontrak error yang dikembalikan backend (`apperrorsx`). Single source of truth ada pada [internal/shared/pkg/apperrorsx/codes_defs.go](../internal/shared/pkg/apperrorsx/codes_defs.go).
+
+
+## Error Code Format
+
+Format `error_code`:
+
+```text
+[HTTP_STATUS(3)][MODULE_CODE(2)][CASE_CODE(2)]
+```
+
+Contoh:
+
+- `4010202` → status `401`, module `02` (PIN), case `02` (PIN blocked)
+- `4040302` → status `404`, module `03` (HELICOPTER), case `02` (Helicopter not found)
+
+## Module Code
+
+| Code | Module | Konstanta |
+|---:|---|---|
+| `00` | General | `ModuleGeneral` |
+| `01` | Auth | `ModuleAuth` |
+| `02` | PIN | `ModulePIN` |
+| `03` | Helicopter | `ModuleHelicopter` |
+| `04` | User | `ModuleUser` |
+| `05` | Master Data | `ModuleMasterData` |
+| `06` | Duty Roster | `ModuleDutyRoster` |
+| `07` | Flight | `ModuleFlight` |
+| `08` | Contact | `ModuleContact` |
+| `09` | HEMS / Mission Operations | `ModuleMissionOps` |
+| `10` | Facility | `ModuleFacility` |
+| `11` | No ICAO Code | `ModuleHospital` |
+| `12` | Federal State | `ModuleFederalState` |
+| `13` | Nationality | `ModuleNationality` |
+| `14` | ICAO | `ModuleICAO` |
+| `15` | Country | `ModuleLand` |
+| `16` | Base | `ModuleBase` |
+| `17` | Health Insurance Companies | `ModuleHealthInsuranceCompanies` |
+| `18` | Vocation | `ModuleVocation` |
+| `19` | Medicine | `ModuleMedicine` |
+| `20` | Master Settings | `ModuleMasterSettings` |
+| `21` | File Manager | `ModuleFileManager` |
+| `22` | OPC Data | `ModuleOPCData` |
+| `23` | Patient Data | `ModulePatientData` |
+| `24` | Insurance Patient Data | `ModuleInsurancePatientData` |
+| `25` | Role | `ModuleRole` |
+| `26` | Flight Data | `ModuleFlightData` |
+| `27` | Air Rescuer Checklist | `ModuleAirRescuerChecklist` |
+| `28` | Branding | `ModuleBranding` |
+| `29` | DUL | `ModuleDUL` |
+| `37` | After Flight Inspection | `ModuleAfterFlightInspection` |
+| `30` | Takeover | `ModuleTakeover` |
+| `31` | Fleet Status | `ModuleFleetStatus` |
+
+## Catalog
+
+### General (Module `00`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `INVALID_REQUEST` | `4000001` | 400 | Bad Request | invalid request |
+| `DATA_NOT_FOUND` | `4040002` | 404 | Not found | data not found |
+| `VALIDATION_ERROR` | `4220003` | 422 | Validation error | validation error |
+| `BUSINESS_RULE_FAILED` | `4220004` | 422 | Business rule failed | business rule validation failed |
+| `INTERNAL_SERVER_ERROR` | `5000005` | 500 | Internal server error | internal server error |
+
+### Auth (Module `01`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `SESSION_EXPIRED` | `4010101` | 401 | Unauthorized | session expired |
+| `TOKEN_INVALID` | `4010102` | 401 | Unauthorized | token is invalid |
+| `USER_UNAUTHORIZED` | `4010103` | 401 | Unauthorized | user is unauthorized |
+| `FORBIDDEN_ACCESS` | `4030104` | 403 | Forbidden | forbidden access |
+| `AUTH_INVALID_JSON` | `4000105` | 400 | Bad Request | invalid json |
+| `AUTH_REGISTRATION_DISABLED` | `4030106` | 403 | Forbidden | registration is disabled |
+| `AUTH_ROLE_NOT_FOUND` | `4000107` | 400 | Bad Request | public registration role not found |
+| `AUTH_REGISTRATION_FAILED` | `4000108` | 400 | Bad Request | registration failed |
+| `AUTH_INVITE_FAILED` | `4000109` | 400 | Bad Request | invite failed |
+| `AUTH_SET_PASSWORD_FAILED` | `4000110` | 400 | Bad Request | set password failed |
+| `AUTH_SET_PASSWORD_TOKEN_INVALID` | `4000111` | 400 | Bad Request | set password token invalid |
+| `AUTH_USERNAME_ALREADY_REGISTERED` | `4000112` | 400 | Bad Request | username already registered |
+| `AUTH_RESET_PASSWORD_INVALID_LINK` | `4000113` | 400 | Bad Request | reset password link invalid |
+| `AUTH_RESET_PASSWORD_FAILED` | `5000114` | 500 | Internal server error | reset password failed |
+
+### PIN (Module `02`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `PIN_INCORRECT` | `4010201` | 401 | Unauthorized | invalid security pin |
+| `PIN_BLOCKED` | `4230202` | 423 | Locked | PIN has been blocked |
+| `PIN_ATTEMPT_LIMIT_REACHED` | `4290203` | 429 | Too many requests | PIN attempt limit reached |
+| `PIN_NOT_SET` | `4090204` | 409 | PIN not configured | security PIN is not set |
+| `PIN_NOT_BLOCKED` | `4090207` | 409 | PIN not blocked | security PIN is not blocked |
+| `PIN_VALIDATION_FAILED` | `4220205` | 422 | Validation error | PIN validation failed |
+| `PIN_VERIFICATION_REQUIRED` | `2020206` | 202 | PIN verification required | valid PIN action token is required |
+
+### Helicopter (Module `03`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `HELICOPTER_DUPLICATE` | `4090301` | 409 | Conflict | helicopter identifier already exists |
+| `HELICOPTER_NOT_FOUND` | `4040302` | 404 | Not found | helicopter not found |
+| `HELICOPTER_RELATION_DELETE_ERROR` | `4090303` | 409 | Conflict | cannot delete helicopter due to active relations |
+| `HELICOPTER_INVALID_PAYLOAD` | `4220304` | 422 | Validation error | invalid helicopter payload |
+| `HELICOPTER_INVALID_JSON` | `4000305` | 400 | Bad Request | invalid json payload |
+| `HELICOPTER_INVALID_ID` | `4220306` | 422 | Validation error | helicopter id is invalid |
+| `HELICOPTER_ID_REQUIRED` | `4220307` | 422 | Validation error | helicopter id is required |
+| `HELICOPTER_ID_MISMATCH` | `4220308` | 422 | Validation error | helicopter id mismatch |
+| `HELICOPTER_ATTRIBUTES_REQUIRED` | `4220309` | 422 | Validation error | at least one attribute must be provided |
+| `HELICOPTER_CREATE_FAILED` | `4000310` | 400 | Bad Request | failed to create helicopter |
+| `HELICOPTER_UPDATE_FAILED` | `4000311` | 400 | Bad Request | failed to update helicopter |
+| `HELICOPTER_DELETE_FAILED` | `4000312` | 400 | Bad Request | failed to delete helicopter |
+| `HELICOPTER_GENERATE_FAILED` | `4000313` | 400 | Bad Request | failed to generate helicopter report number |
+| `HELICOPTER_LIST_FAILED` | `4000314` | 400 | Bad Request | failed to list helicopter data |
+| `HELICOPTER_PIN_VERIFICATION_REQUIRED` | `2020315` | 202 | PIN verification required | valid PIN action token is required |
+| `HELICOPTER_UNAUTHORIZED` | `4010316` | 401 | Unauthorized | helicopter action unauthorized |
+| `HELICOPTER_INVALID_TYPE` | `4220317` | 422 | Validation error | helicopter type is invalid |
+| `HELICOPTER_FILE_NOT_FOUND` | `4040318` | 404 | Not found | helicopter file not found |
+| `HELICOPTER_FILE_INVALID_PAYLOAD` | `4220319` | 422 | Validation error | invalid helicopter file payload |
+| `HELICOPTER_FILE_INVALID_JSON` | `4000320` | 400 | Bad Request | invalid json payload |
+| `HELICOPTER_FILE_INVALID_UUID` | `4220321` | 422 | Validation error | helicopter file uuid is invalid |
+| `HELICOPTER_FILE_SECTION_INVALID` | `4220322` | 422 | Validation error | section is invalid |
+| `HELICOPTER_FILE_FILE_NAME_REQUIRED` | `4220323` | 422 | Validation error | file_name is required |
+| `HELICOPTER_FILE_CREATE_FAILED` | `4000324` | 400 | Bad Request | failed to create helicopter file |
+| `HELICOPTER_FILE_UPDATE_FAILED` | `4000325` | 400 | Bad Request | failed to update helicopter file |
+| `HELICOPTER_FILE_DELETE_FAILED` | `4000326` | 400 | Bad Request | failed to delete helicopter file |
+| `HELICOPTER_FILE_GET_FAILED` | `4000327` | 400 | Bad Request | failed to get helicopter file |
+| `HELICOPTER_FILE_LIST_FAILED` | `4000328` | 400 | Bad Request | failed to list helicopter file data |
+
+### User (Module `04`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `USER_NOT_FOUND` | `4040401` | 404 | Not found | user not found |
+| `USER_INVALID_PAYLOAD` | `4220402` | 422 | Validation error | invalid user payload |
+| `USER_INVALID_JSON` | `4000403` | 400 | Bad Request | invalid json payload |
+| `USER_INVALID_UUID` | `4220404` | 422 | Validation error | user uuid is invalid |
+| `USER_VALIDATION_FAILED` | `4220405` | 422 | Validation error | user validation failed |
+| `USER_CREATE_FAILED` | `4000406` | 400 | Bad Request | failed to create user |
+| `USER_UPDATE_FAILED` | `4000407` | 400 | Bad Request | failed to update user |
+| `USER_DELETE_FAILED` | `4000408` | 400 | Bad Request | failed to delete user |
+| `USER_LIST_FAILED` | `4000409` | 400 | Bad Request | failed to list users |
+| `USER_TIMEZONE_INVALID` | `4220410` | 422 | Validation error | timezone is invalid |
+| `USER_ROLE_IDS_INVALID` | `4220411` | 422 | Validation error | role_ids contains invalid uuid |
+| `USER_ROLE_IDS_REQUIRED` | `4220412` | 422 | Validation error | role_ids must contain at least one role |
+| `USER_PRIMARY_ROLE_INVALID` | `4220413` | 422 | Validation error | primary role must be included in role_ids |
+
+### Master Data (Module `05`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `MASTER_DATA_NOT_FOUND` | `4040501` | 404 | Not found | master data not found |
+| `MASTER_DATA_INVALID_PAYLOAD` | `4220502` | 422 | Validation error | invalid master data payload |
+| `MASTER_DATA_INVALID_JSON` | `4000503` | 400 | Bad Request | invalid json payload |
+| `MASTER_DATA_VALIDATION_FAILED` | `4220504` | 422 | Validation error | master data validation failed |
+| `MASTER_DATA_CREATE_FAILED` | `4000505` | 400 | Bad Request | failed to create master data |
+| `MASTER_DATA_UPDATE_FAILED` | `4000506` | 400 | Bad Request | failed to update master data |
+| `MASTER_DATA_DELETE_FAILED` | `4000507` | 400 | Bad Request | failed to delete master data |
+| `MASTER_DATA_LIST_FAILED` | `4000508` | 400 | Bad Request | failed to list master data |
+
+### Duty Roster (Module `06`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `DUTY_ROSTER_NOT_FOUND` | `4040601` | 404 | Not found | duty roster not found |
+| `DUTY_ROSTER_INVALID_PAYLOAD` | `4220602` | 422 | Validation error | invalid duty roster payload |
+| `DUTY_ROSTER_INVALID_JSON` | `4000603` | 400 | Bad Request | invalid json payload |
+| `DUTY_ROSTER_INVALID_UUID` | `4220604` | 422 | Validation error | duty roster uuid is invalid |
+| `DUTY_ROSTER_VALIDATION_FAILED` | `4220605` | 422 | Validation error | duty roster validation failed |
+| `DUTY_ROSTER_CONFLICT` | `4090606` | 409 | Conflict | duty roster conflict |
+| `DUTY_ROSTER_CREATE_FAILED` | `4000607` | 400 | Bad Request | failed to create duty roster |
+| `DUTY_ROSTER_UPDATE_FAILED` | `4000608` | 400 | Bad Request | failed to update duty roster |
+| `DUTY_ROSTER_DELETE_FAILED` | `4000609` | 400 | Bad Request | failed to delete duty roster |
+| `DUTY_ROSTER_LIST_FAILED` | `4000610` | 400 | Bad Request | failed to list duty roster data |
+| `DUTY_ROSTER_UNAUTHORIZED` | `4010611` | 401 | Unauthorized | duty roster unauthorized |
+| `DUTY_ROSTER_BASE_TYPE_INVALID` | `4220612` | 422 | Validation error | duty roster base type is invalid |
+| `DUTY_ROSTER_RELATION_DELETE_ERROR` | `4090613` | 409 | Conflict | cannot delete duty roster due to active relations |
+
+### DUL (Module `29`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `DUL_NOT_FOUND` | `4042901` | 404 | Not found | dul not found |
+| `DUL_INVALID_PAYLOAD` | `4222902` | 422 | Validation error | invalid dul payload |
+| `DUL_INVALID_JSON` | `4002903` | 400 | Bad Request | invalid json payload |
+| `DUL_INVALID_UUID` | `4222904` | 422 | Validation error | dul uuid is invalid |
+| `DUL_VALIDATION_FAILED` | `4222905` | 422 | Validation error | dul validation failed |
+| `DUL_CREATE_FAILED` | `4002906` | 400 | Bad Request | failed to create dul |
+| `DUL_UPDATE_FAILED` | `4002907` | 400 | Bad Request | failed to update dul |
+| `DUL_DELETE_FAILED` | `4002908` | 400 | Bad Request | failed to delete dul |
+| `DUL_LIST_FAILED` | `4002909` | 400 | Bad Request | failed to list dul |
+| `DUL_DATE_INVALID` | `4222910` | 422 | Validation error | date must be YYYY-MM-DD |
+
+### Takeover (Module `30`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `TAKEOVER_NOT_FOUND` | `4043001` | 404 | Not found | takeover not found |
+| `TAKEOVER_INVALID_PAYLOAD` | `4223002` | 422 | Validation error | invalid takeover payload |
+| `TAKEOVER_INVALID_JSON` | `4003003` | 400 | Bad Request | invalid json payload |
+| `TAKEOVER_INVALID_UUID` | `4223004` | 422 | Validation error | takeover uuid is invalid |
+| `TAKEOVER_ID_REQUIRED` | `4223005` | 422 | Validation error | id is required |
+| `TAKEOVER_ID_MISMATCH` | `4223006` | 422 | Validation error | id does not match path uuid |
+| `TAKEOVER_FILE_SECTION_INVALID` | `4223007` | 422 | Validation error | helicopter_file_id does not belong to selected helicopter/section |
+| `TAKEOVER_CREATE_FAILED` | `4003007` | 400 | Bad Request | failed to create takeover |
+| `TAKEOVER_UPDATE_FAILED` | `4003008` | 400 | Bad Request | failed to update takeover |
+| `TAKEOVER_DELETE_FAILED` | `4003009` | 400 | Bad Request | failed to delete takeover |
+| `TAKEOVER_GET_FAILED` | `4003010` | 400 | Bad Request | failed to get takeover |
+| `TAKEOVER_LIST_FAILED` | `4003011` | 400 | Bad Request | failed to list takeover data |
+| `TAKEOVER_HELICOPTER_IN_USE` | `4093013` | 409 | Conflict | helicopter is already booked and cannot be used |
+
+### Fleet Status (Module `31`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `FLEET_STATUS_NOT_FOUND` | `4043101` | 404 | Not found | fleet status not found |
+| `FLEET_STATUS_INVALID_PAYLOAD` | `4223102` | 422 | Validation error | invalid fleet status payload |
+| `FLEET_STATUS_INVALID_JSON` | `4003103` | 400 | Bad Request | invalid json payload |
+| `FLEET_STATUS_INVALID_ID` | `4223104` | 422 | Validation error | fleet status id is invalid |
+| `FLEET_STATUS_ID_REQUIRED` | `4223105` | 422 | Validation error | id is required |
+| `FLEET_STATUS_ID_MISMATCH` | `4223106` | 422 | Validation error | id does not match path id |
+| `FLEET_STATUS_HELICOPTER_REQUIRED` | `4223107` | 422 | Validation error | helicopter_id is required |
+| `FLEET_STATUS_HELICOPTER_INVALID` | `4223108` | 422 | Validation error | referenced helicopter does not exist |
+| `FLEET_STATUS_DUPLICATE` | `4093109` | 409 | Conflict | fleet status already exists |
+| `FLEET_STATUS_RELATION_DELETE_ERROR` | `4093110` | 409 | Conflict | cannot delete fleet status due to active relations |
+| `FLEET_STATUS_CREATE_FAILED` | `4003111` | 400 | Bad Request | failed to create fleet status |
+| `FLEET_STATUS_UPDATE_FAILED` | `4003112` | 400 | Bad Request | failed to update fleet status |
+| `FLEET_STATUS_DELETE_FAILED` | `4003113` | 400 | Bad Request | failed to delete fleet status |
+| `FLEET_STATUS_LIST_FAILED` | `4003114` | 400 | Bad Request | failed to list fleet status data |
+| `FLEET_STATUS_MARK_SERVICED_FAILED` | `4003115` | 400 | Bad Request | failed to mark fleet status serviced |
+
+### Flight (Module `07`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `FLIGHT_NOT_FOUND` | `4040701` | 404 | Not found | flight not found |
+| `FLIGHT_INVALID_PAYLOAD` | `4220702` | 422 | Validation error | invalid flight payload |
+| `FLIGHT_INVALID_JSON` | `4000703` | 400 | Bad Request | invalid json payload |
+| `FLIGHT_INVALID_UUID` | `4220704` | 422 | Validation error | flight uuid is invalid |
+| `FLIGHT_VALIDATION_FAILED` | `4220705` | 422 | Validation error | flight validation failed |
+| `FLIGHT_CREATE_FAILED` | `4000706` | 400 | Bad Request | failed to create flight |
+| `FLIGHT_GET_FAILED` | `4000707` | 400 | Bad Request | failed to get flight |
+| `FLIGHT_LIST_FAILED` | `4000708` | 400 | Bad Request | failed to list flight data |
+| `FLIGHT_UNAUTHORIZED` | `4010709` | 401 | Unauthorized | flight action unauthorized |
+| `FLIGHT_DATE_INVALID` | `4220710` | 422 | Validation error | date must be YYYY-MM-DD |
+
+### Contact (Module `08`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `CONTACT_NOT_FOUND` | `4040801` | 404 | Not found | contact not found |
+| `CONTACT_INVALID_PAYLOAD` | `4220802` | 422 | Validation error | invalid contact payload |
+| `CONTACT_INVALID_JSON` | `4000803` | 400 | Bad Request | invalid json payload |
+| `CONTACT_INVALID_USER_ID` | `4220804` | 422 | Validation error | user_id is invalid uuid |
+| `CONTACT_VALIDATION_FAILED` | `4220805` | 422 | Validation error | contact validation failed |
+| `CONTACT_CREATE_FAILED` | `4000806` | 400 | Bad Request | failed to create contact |
+| `CONTACT_GET_FAILED` | `4000807` | 400 | Bad Request | failed to get contact |
+| `CONTACT_UPDATE_FAILED` | `4000808` | 400 | Bad Request | failed to update contact |
+| `CONTACT_USERNAME_CONFLICT` | `4090809` | 409 | Conflict | username already exists |
+| `CONTACT_DELETE_FAILED` | `4000810` | 400 | Bad Request | failed to delete contact |
+| `CONTACT_UPDATE_STATUS_FAILED` | `4000811` | 400 | Bad Request | failed to update contact status |
+| `CONTACT_UPDATE_ROLE_FAILED` | `4000812` | 400 | Bad Request | failed to update contact role |
+| `CONTACT_UPDATE_PILOT_CATEGORY_FAILED` | `4000813` | 400 | Bad Request | failed to update contact pilot category |
+| `CONTACT_UPDATE_LICENSE_FAILED` | `4000814` | 400 | Bad Request | failed to update contact license |
+| `CONTACT_UPDATE_CHIEF_FLAGS_FAILED` | `4000815` | 400 | Bad Request | failed to update contact chief flags |
+| `CONTACT_UPDATE_RESPONSIBLE_COMPLAINTS_FAILED` | `4000816` | 400 | Bad Request | failed to update contact responsible complaints |
+| `CONTACT_BULK_UPDATE_FAILED` | `4000817` | 400 | Bad Request | failed to bulk update contacts |
+| `CONTACT_LIST_FAILED` | `4000818` | 400 | Bad Request | failed to list contacts |
+
+### HEMS Operation / Mission Ops (Module `09`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `HEMS_OPERATION_NOT_FOUND` | `4040901` | 404 | Not found | hems operation not found |
+| `HEMS_OPERATION_INVALID_PAYLOAD` | `4220902` | 422 | Validation error | invalid hems operation payload |
+| `HEMS_OPERATION_INVALID_JSON` | `4000903` | 400 | Bad Request | invalid json payload |
+| `HEMS_OPERATION_INVALID_UUID` | `4220904` | 422 | Validation error | hems operation uuid is invalid |
+| `HEMS_OPERATION_ATTRIBUTES_REQUIRED` | `4220905` | 422 | Validation error | at least one hems operation attribute must be provided |
+| `HEMS_OPERATION_DATE_INVALID_RFC3339` | `4220906` | 422 | Validation error | date must be in RFC3339 format |
+| `HEMS_OPERATION_RELATION_REFERENCE_INVALID` | `4220907` | 422 | Validation error | relation reference is invalid |
+| `HEMS_OPERATION_CREATE_FAILED` | `4000908` | 400 | Bad Request | failed to create hems operation |
+| `HEMS_OPERATION_UPDATE_FAILED` | `4000909` | 400 | Bad Request | failed to update hems operation |
+| `HEMS_OPERATION_DELETE_FAILED` | `4000910` | 400 | Bad Request | failed to delete hems operation |
+| `HEMS_OPERATION_LIST_FAILED` | `4000911` | 400 | Bad Request | failed to list hems operation |
+
+### Forces Present (Module `09`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `FORCES_PRESENT_NOT_FOUND` | `4040912` | 404 | Not found | forces present not found |
+| `FORCES_PRESENT_RELATION_DELETE_ERROR` | `4090913` | 409 | Conflict | cannot delete forces present due to active relations |
+| `FORCES_PRESENT_INVALID_PAYLOAD` | `4220914` | 422 | Validation error | invalid forces present payload |
+| `FORCES_PRESENT_INVALID_JSON` | `4000915` | 400 | Bad Request | invalid json payload |
+| `FORCES_PRESENT_INVALID_UUID` | `4220916` | 422 | Validation error | forces present uuid is invalid |
+| `FORCES_PRESENT_ID_REQUIRED` | `4220917` | 422 | Validation error | forces present id is required |
+| `FORCES_PRESENT_ID_MISMATCH` | `4220918` | 422 | Validation error | forces present id mismatch |
+| `FORCES_PRESENT_ATTRIBUTES_REQUIRED` | `4220919` | 422 | Validation error | at least one forces present attribute must be provided |
+| `FORCES_PRESENT_NAME_REQUIRED` | `4220920` | 422 | Validation error | forces present name is required |
+| `FORCES_PRESENT_CREATE_FAILED` | `4000921` | 400 | Bad Request | failed to create forces present |
+| `FORCES_PRESENT_UPDATE_FAILED` | `4000922` | 400 | Bad Request | failed to update forces present |
+| `FORCES_PRESENT_DELETE_FAILED` | `4000923` | 400 | Bad Request | failed to delete forces present |
+| `FORCES_PRESENT_LIST_FAILED` | `4000924` | 400 | Bad Request | failed to list forces present data |
+
+### Mission (Module `09`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `MISSION_NOT_FOUND` | `4040925` | 404 | Not found | mission not found |
+| `MISSION_INVALID_PAYLOAD` | `4220926` | 422 | Validation error | invalid mission payload |
+| `MISSION_INVALID_JSON` | `4000927` | 400 | Bad Request | invalid json payload |
+| `MISSION_INVALID_FLIGHT_UUID` | `4220928` | 422 | Validation error | flight uuid is invalid |
+| `MISSION_FLIGHT_ID_REQUIRED` | `4220929` | 422 | Validation error | flight_id is required |
+| `MISSION_MISSION_ID_REQUIRED` | `4220930` | 422 | Validation error | mission_id is required |
+| `MISSION_TYPE_INVALID` | `4220931` | 422 | Validation error | mission type is invalid |
+| `MISSION_SUBTYPE_REQUIRED` | `4220932` | 422 | Validation error | subtype_id is required |
+| `MISSION_SUBTYPE_INVALID` | `4220933` | 422 | Validation error | subtype_id is invalid |
+| `MISSION_SUBTYPE_FORBIDDEN` | `4220934` | 422 | Validation error | subtype_id is forbidden |
+| `MISSION_DUPLICATE_FLIGHT` | `4090935` | 409 | Conflict | mission for this flight already exists |
+| `MISSION_CREATE_FAILED` | `4000936` | 400 | Bad Request | failed to create mission |
+| `MISSION_UPDATE_FAILED` | `4000937` | 400 | Bad Request | failed to update mission |
+| `MISSION_DELETE_FAILED` | `4000938` | 400 | Bad Request | failed to delete mission |
+| `MISSION_GET_FAILED` | `4000939` | 400 | Bad Request | failed to get mission |
+| `MISSION_INVALID_MISSION_UUID` | `4220940` | 422 | Validation error | mission uuid is invalid |
+| `MISSION_LIST_FAILED` | `4000941` | 400 | Bad Request | failed to list mission data |
+| `MISSION_AFTER_FLIGHT_LOCKED` | `4230942` | 423 | Locked | mission is locked because after flight inspection already exists |
+
+### Facility (Module `10`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `FACILITY_NOT_FOUND` | `4041001` | 404 | Not found | facility not found |
+| `FACILITY_RELATION_DELETE_ERROR` | `4091002` | 409 | Conflict | cannot delete facility due to active relations |
+| `FACILITY_INVALID_PAYLOAD` | `4221003` | 422 | Validation error | invalid facility payload |
+| `FACILITY_INVALID_JSON` | `4001004` | 400 | Bad Request | invalid json payload |
+| `FACILITY_INVALID_UUID` | `4221005` | 422 | Validation error | facility uuid is invalid |
+| `FACILITY_ATTRIBUTES_REQUIRED` | `4221006` | 422 | Validation error | at least one facility attribute must be provided |
+| `FACILITY_CATEGORY_REQUIRED` | `4221007` | 422 | Validation error | facility category is required |
+| `FACILITY_NAME_REQUIRED` | `4221008` | 422 | Validation error | facility name is required |
+| `FACILITY_TYPE_REQUIRED` | `4221009` | 422 | Validation error | facility type is required |
+| `FACILITY_CREATE_FAILED` | `4001010` | 400 | Bad Request | failed to create facility |
+| `FACILITY_UPDATE_FAILED` | `4001011` | 400 | Bad Request | failed to update facility |
+| `FACILITY_DELETE_FAILED` | `4001012` | 400 | Bad Request | failed to delete facility |
+| `FACILITY_LIST_FAILED` | `4001013` | 400 | Bad Request | failed to list facility data |
+
+### No ICAO Code (Module `11`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `NO_ICAO_CODE_NOT_FOUND` | `4041101` | 404 | Not found | no icao code not found |
+| `NO_ICAO_CODE_RELATION_DELETE_ERROR` | `4091102` | 409 | Conflict | cannot delete no icao code due to active relations |
+| `NO_ICAO_CODE_INVALID_PAYLOAD` | `4221103` | 422 | Validation error | invalid no icao code payload |
+| `NO_ICAO_CODE_INVALID_JSON` | `4001104` | 400 | Bad Request | invalid json payload |
+| `NO_ICAO_CODE_INVALID_UUID` | `4221105` | 422 | Validation error | no icao code uuid is invalid |
+| `NO_ICAO_CODE_ID_REQUIRED` | `4221106` | 422 | Validation error | no icao code id is required |
+| `NO_ICAO_CODE_ID_MISMATCH` | `4221107` | 422 | Validation error | no icao code id mismatch |
+| `NO_ICAO_CODE_ATTRIBUTES_REQUIRED` | `4221108` | 422 | Validation error | at least one no icao code attribute must be provided |
+| `NO_ICAO_CODE_NAME_REQUIRED` | `4221109` | 422 | Validation error | no icao code name is required |
+| `NO_ICAO_CODE_CREATE_FAILED` | `4001110` | 400 | Bad Request | failed to create no icao code |
+| `NO_ICAO_CODE_UPDATE_FAILED` | `4001111` | 400 | Bad Request | failed to update no icao code |
+| `NO_ICAO_CODE_DELETE_FAILED` | `4001112` | 400 | Bad Request | failed to delete no icao code |
+| `NO_ICAO_CODE_LIST_FAILED` | `4001113` | 400 | Bad Request | failed to list no icao code data |
+
+### Federal State (Module `12`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `FEDERAL_STATE_NOT_FOUND` | `4041201` | 404 | Not found | federal state not found |
+| `FEDERAL_STATE_RELATION_DELETE_ERROR` | `4091202` | 409 | Conflict | cannot delete federal state due to active relations |
+| `FEDERAL_STATE_INVALID_PAYLOAD` | `4221203` | 422 | Validation error | invalid federal state payload |
+| `FEDERAL_STATE_INVALID_JSON` | `4001204` | 400 | Bad Request | invalid json payload |
+| `FEDERAL_STATE_INVALID_ID` | `4221205` | 422 | Validation error | federal state id is invalid |
+| `FEDERAL_STATE_LAND_ID_INVALID` | `4221206` | 422 | Validation error | federal state land_id is invalid |
+| `FEDERAL_STATE_ID_REQUIRED` | `4221207` | 422 | Validation error | federal state id is required |
+| `FEDERAL_STATE_ID_MISMATCH` | `4221208` | 422 | Validation error | federal state id mismatch |
+| `FEDERAL_STATE_ATTRIBUTES_REQUIRED` | `4221209` | 422 | Validation error | at least one federal state attribute must be provided |
+| `FEDERAL_STATE_NAME_REQUIRED` | `4221210` | 422 | Validation error | federal state name is required |
+| `FEDERAL_STATE_CREATE_FAILED` | `4001211` | 400 | Bad Request | failed to create federal state |
+| `FEDERAL_STATE_UPDATE_FAILED` | `4001212` | 400 | Bad Request | failed to update federal state |
+| `FEDERAL_STATE_DELETE_FAILED` | `4001213` | 400 | Bad Request | failed to delete federal state |
+| `FEDERAL_STATE_LIST_FAILED` | `4001214` | 400 | Bad Request | failed to list federal state data |
+
+### Nationality (Module `13`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `NATIONALITY_NOT_FOUND` | `4041301` | 404 | Not found | nationality not found |
+| `NATIONALITY_RELATION_DELETE_ERROR` | `4091302` | 409 | Conflict | cannot delete nationality due to active relations |
+| `NATIONALITY_INVALID_PAYLOAD` | `4221303` | 422 | Validation error | invalid nationality payload |
+| `NATIONALITY_INVALID_JSON` | `4001304` | 400 | Bad Request | invalid json payload |
+| `NATIONALITY_INVALID_UUID` | `4221305` | 422 | Validation error | nationality uuid is invalid |
+| `NATIONALITY_ID_REQUIRED` | `4221306` | 422 | Validation error | nationality id is required |
+| `NATIONALITY_ID_MISMATCH` | `4221307` | 422 | Validation error | nationality id mismatch |
+| `NATIONALITY_ATTRIBUTES_REQUIRED` | `4221308` | 422 | Validation error | at least one nationality attribute must be provided |
+| `NATIONALITY_NAME_REQUIRED` | `4221309` | 422 | Validation error | nationality name is required |
+| `NATIONALITY_CREATE_FAILED` | `4001310` | 400 | Bad Request | failed to create nationality |
+| `NATIONALITY_UPDATE_FAILED` | `4001311` | 400 | Bad Request | failed to update nationality |
+| `NATIONALITY_DELETE_FAILED` | `4001312` | 400 | Bad Request | failed to delete nationality |
+| `NATIONALITY_LIST_FAILED` | `4001313` | 400 | Bad Request | failed to list nationality data |
+
+### ICAO (Module `14`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `ICAO_NOT_FOUND` | `4041401` | 404 | Not found | icao not found |
+| `ICAO_RELATION_DELETE_ERROR` | `4091402` | 409 | Conflict | cannot delete icao due to active relations |
+| `ICAO_INVALID_PAYLOAD` | `4221403` | 422 | Validation error | invalid icao payload |
+| `ICAO_INVALID_JSON` | `4001404` | 400 | Bad Request | invalid json payload |
+| `ICAO_INVALID_UUID` | `4221405` | 422 | Validation error | icao uuid is invalid |
+| `ICAO_ID_REQUIRED` | `4221406` | 422 | Validation error | icao id is required |
+| `ICAO_ID_MISMATCH` | `4221407` | 422 | Validation error | icao id mismatch |
+| `ICAO_ATTRIBUTES_REQUIRED` | `4221408` | 422 | Validation error | at least one icao attribute must be provided |
+| `ICAO_CODE_REQUIRED` | `4221409` | 422 | Validation error | icao code is required |
+| `ICAO_LAND_ID_INVALID` | `4221410` | 422 | Validation error | icao land_id is invalid |
+| `ICAO_FEDERAL_STATE_ID_INVALID` | `4221411` | 422 | Validation error | icao federal_state_id is invalid |
+| `ICAO_CREATE_FAILED` | `4001412` | 400 | Bad Request | failed to create icao |
+| `ICAO_UPDATE_FAILED` | `4001413` | 400 | Bad Request | failed to update icao |
+| `ICAO_DELETE_FAILED` | `4001414` | 400 | Bad Request | failed to delete icao |
+| `ICAO_LIST_FAILED` | `4001415` | 400 | Bad Request | failed to list icao data |
+
+### Country (Module `15`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `COUNTRY_NOT_FOUND` | `4041501` | 404 | Not found | country not found |
+| `COUNTRY_RELATION_DELETE_ERROR` | `4091502` | 409 | Conflict | cannot delete country due to active relations |
+| `COUNTRY_INVALID_PAYLOAD` | `4221503` | 422 | Validation error | invalid country payload |
+| `COUNTRY_INVALID_JSON` | `4001504` | 400 | Bad Request | invalid json payload |
+| `COUNTRY_INVALID_ID` | `4221505` | 422 | Validation error | country id is invalid |
+| `COUNTRY_ID_REQUIRED` | `4221506` | 422 | Validation error | country id is required |
+| `COUNTRY_ID_MISMATCH` | `4221507` | 422 | Validation error | country id mismatch |
+| `COUNTRY_ATTRIBUTES_REQUIRED` | `4221508` | 422 | Validation error | at least one country attribute must be provided |
+| `COUNTRY_NAME_REQUIRED` | `4221509` | 422 | Validation error | country name is required |
+| `COUNTRY_ISO_CODE_INVALID` | `4221510` | 422 | Validation error | country iso_code is invalid |
+| `COUNTRY_ISO_CODE_DUPLICATE` | `4091511` | 409 | Conflict | country iso_code already exists |
+| `COUNTRY_CREATE_FAILED` | `4001512` | 400 | Bad Request | failed to create country |
+| `COUNTRY_UPDATE_FAILED` | `4001513` | 400 | Bad Request | failed to update country |
+| `COUNTRY_DELETE_FAILED` | `4001514` | 400 | Bad Request | failed to delete country |
+| `COUNTRY_LIST_FAILED` | `4001515` | 400 | Bad Request | failed to list country data |
+
+### Base (Module `16`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `BASE_NOT_FOUND` | `4041601` | 404 | Not found | base not found |
+| `BASE_DELETE_CONFLICT` | `4091615` | 409 | Conflict | cannot delete base because it is referenced by another record |
+| `BASE_INVALID_PAYLOAD` | `4221603` | 422 | Validation error | invalid base payload |
+| `BASE_INVALID_JSON` | `4001604` | 400 | Bad Request | invalid json payload |
+| `BASE_INVALID_UUID` | `4221605` | 422 | Validation error | base uuid is invalid |
+| `BASE_INVALID_CATEGORY` | `4221606` | 422 | Validation error | base category is invalid |
+| `BASE_ATTRIBUTES_REQUIRED` | `4221607` | 422 | Validation error | at least one base attribute must be provided |
+| `BASE_NAME_REQUIRED` | `4221608` | 422 | Validation error | base name is required |
+| `BASE_DEFAULT_SHIFT_START_REQUIRED` | `4221616` | 422 | Validation error | default_shift_start is required |
+| `BASE_DEFAULT_SHIFT_END_REQUIRED` | `4221617` | 422 | Validation error | default_shift_end is required |
+| `BASE_CREATE_FAILED` | `4001609` | 400 | Bad Request | failed to create base |
+| `BASE_UPDATE_FAILED` | `4001610` | 400 | Bad Request | failed to update base |
+| `BASE_DELETE_FAILED` | `4001611` | 400 | Bad Request | failed to delete base |
+| `BASE_LIST_FAILED` | `4001612` | 400 | Bad Request | failed to list base data |
+| `BASE_INVALID_CONTACT_IDS` | `4221613` | 422 | Validation error | base contact ids are invalid |
+| `BASE_INVALID_TIME` | `4221614` | 422 | Validation error | base time format is invalid |
+
+Catatan:
+- `BASE_DELETE_CONFLICT` mengembalikan detail relasi yang masih mengacu ke base, misalnya `takeover`, `dul`, `base operational shift times`, atau `base contact roles`.
+- Detail pesan bisa berubah sesuai tabel relasi yang ditemukan saat delete.
+
+### Health Insurance Companies (Module `17`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `HEALTH_INSURANCE_COMPANY_NOT_FOUND` | `4041701` | 404 | Not found | health insurance company not found |
+| `HEALTH_INSURANCE_COMPANY_RELATION_DELETE_ERROR` | `4091702` | 409 | Conflict | cannot delete health insurance company due to active relations |
+| `HEALTH_INSURANCE_COMPANY_INVALID_PAYLOAD` | `4221703` | 422 | Validation error | invalid health insurance company payload |
+| `HEALTH_INSURANCE_COMPANY_INVALID_JSON` | `4001704` | 400 | Bad Request | invalid json payload |
+| `HEALTH_INSURANCE_COMPANY_INVALID_UUID` | `4221705` | 422 | Validation error | health insurance company uuid is invalid |
+| `HEALTH_INSURANCE_COMPANY_ID_REQUIRED` | `4221706` | 422 | Validation error | health insurance company id is required |
+| `HEALTH_INSURANCE_COMPANY_ID_MISMATCH` | `4221707` | 422 | Validation error | health insurance company id mismatch |
+| `HEALTH_INSURANCE_COMPANY_ATTRIBUTES_REQUIRED` | `4221708` | 422 | Validation error | at least one health insurance company attribute must be provided |
+| `HEALTH_INSURANCE_COMPANY_NAME_REQUIRED` | `4221709` | 422 | Validation error | health insurance company name is required |
+| `HEALTH_INSURANCE_COMPANY_LAND_ID_INVALID` | `4221710` | 422 | Validation error | health insurance company land_id is invalid |
+| `HEALTH_INSURANCE_COMPANY_CREATE_FAILED` | `4001711` | 400 | Bad Request | failed to create health insurance company |
+| `HEALTH_INSURANCE_COMPANY_UPDATE_FAILED` | `4001712` | 400 | Bad Request | failed to update health insurance company |
+| `HEALTH_INSURANCE_COMPANY_DELETE_FAILED` | `4001713` | 400 | Bad Request | failed to delete health insurance company |
+| `HEALTH_INSURANCE_COMPANY_LIST_FAILED` | `4001714` | 400 | Bad Request | failed to list health insurance company data |
+
+### Vocation (Module `18`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `VOCATION_NOT_FOUND` | `4041801` | 404 | Not found | vocation not found |
+| `VOCATION_RELATION_DELETE_ERROR` | `4091802` | 409 | Conflict | cannot delete vocation due to active relations |
+| `VOCATION_INVALID_PAYLOAD` | `4221803` | 422 | Validation error | invalid vocation payload |
+| `VOCATION_INVALID_JSON` | `4001804` | 400 | Bad Request | invalid json payload |
+| `VOCATION_INVALID_UUID` | `4221805` | 422 | Validation error | vocation uuid is invalid |
+| `VOCATION_ID_REQUIRED` | `4221806` | 422 | Validation error | vocation id is required |
+| `VOCATION_ID_MISMATCH` | `4221807` | 422 | Validation error | vocation id mismatch |
+| `VOCATION_ATTRIBUTES_REQUIRED` | `4221808` | 422 | Validation error | at least one vocation attribute must be provided |
+| `VOCATION_NAME_REQUIRED` | `4221809` | 422 | Validation error | vocation name is required |
+| `VOCATION_CREATE_FAILED` | `4001810` | 400 | Bad Request | failed to create vocation |
+| `VOCATION_UPDATE_FAILED` | `4001811` | 400 | Bad Request | failed to update vocation |
+| `VOCATION_DELETE_FAILED` | `4001812` | 400 | Bad Request | failed to delete vocation |
+| `VOCATION_LIST_FAILED` | `4001813` | 400 | Bad Request | failed to list vocation data |
+
+### Medicine (Module `19`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `MEDICINE_NOT_FOUND` | `4041901` | 404 | Not found | medicine not found |
+| `MEDICINE_RELATION_DELETE_ERROR` | `4091902` | 409 | Conflict | cannot delete medicine due to active relations |
+| `MEDICINE_INVALID_PAYLOAD` | `4221903` | 422 | Validation error | invalid medicine payload |
+| `MEDICINE_INVALID_JSON` | `4001904` | 400 | Bad Request | invalid json payload |
+| `MEDICINE_INVALID_UUID` | `4221905` | 422 | Validation error | medicine uuid is invalid |
+| `MEDICINE_ID_REQUIRED` | `4221906` | 422 | Validation error | medicine id is required |
+| `MEDICINE_ID_MISMATCH` | `4221907` | 422 | Validation error | medicine id mismatch |
+| `MEDICINE_ATTRIBUTES_REQUIRED` | `4221908` | 422 | Validation error | at least one medicine attribute must be provided |
+| `MEDICINE_NAME_REQUIRED` | `4221909` | 422 | Validation error | medicine name is required |
+| `MEDICINE_GROUP_ID_INVALID` | `4221910` | 422 | Validation error | medicine_group_id is invalid |
+| `MEDICINE_MOTOR_REACTION_ID_INVALID` | `4221911` | 422 | Validation error | motor_reaction_id is invalid |
+| `MEDICINE_MOTOR_REACTION_IDS_INVALID` | `4221912` | 422 | Validation error | motor_reaction_ids contains invalid uuid |
+| `MEDICINE_CREATE_FAILED` | `4001913` | 400 | Bad Request | failed to create medicine |
+| `MEDICINE_UPDATE_FAILED` | `4001914` | 400 | Bad Request | failed to update medicine |
+| `MEDICINE_DELETE_FAILED` | `4001915` | 400 | Bad Request | failed to delete medicine |
+| `MEDICINE_LIST_FAILED` | `4001916` | 400 | Bad Request | failed to list medicine data |
+
+### Master Settings (Module `20`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `MASTER_SETTINGS_NOT_FOUND` | `4042001` | 404 | Not found | master settings not found |
+| `MASTER_SETTINGS_INVALID_PAYLOAD` | `4222002` | 422 | Validation error | invalid master settings payload |
+| `MASTER_SETTINGS_INVALID_JSON` | `4002003` | 400 | Bad Request | invalid json payload |
+| `MASTER_SETTINGS_INVALID_UUID` | `4222004` | 422 | Validation error | master settings uuid is invalid |
+| `MASTER_SETTINGS_ID_REQUIRED` | `4222005` | 422 | Validation error | master settings id is required |
+| `MASTER_SETTINGS_ID_MISMATCH` | `4222006` | 422 | Validation error | master settings id mismatch |
+| `MASTER_SETTINGS_ATTRIBUTES_REQUIRED` | `4222007` | 422 | Validation error | at least one master settings attribute must be provided |
+| `MASTER_SETTINGS_COMPANY_NAME_REQUIRED` | `4222008` | 422 | Validation error | company_name is required |
+| `MASTER_SETTINGS_LOGO_FILE_INVALID` | `4222009` | 422 | Validation error | logo file uuid is invalid |
+| `MASTER_SETTINGS_COVER_FILE_INVALID` | `4222010` | 422 | Validation error | cover file uuid is invalid |
+| `MASTER_SETTINGS_CREATE_FAILED` | `4002011` | 400 | Bad Request | failed to create master settings |
+| `MASTER_SETTINGS_UPDATE_FAILED` | `4002012` | 400 | Bad Request | failed to update master settings |
+| `MASTER_SETTINGS_DELETE_FAILED` | `4002013` | 400 | Bad Request | failed to delete master settings |
+| `MASTER_SETTINGS_GET_FAILED` | `4002014` | 400 | Bad Request | failed to get master settings |
+| `MASTER_SETTINGS_MICROSOFT_ENTRA_UPSERT_FAILED` | `4002015` | 400 | Bad Request | failed to upsert microsoft entra sso settings |
+
+### Branding (Module `28`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `BRANDING_LOGO_FETCH_FAILED` | `4002801` | 400 | Bad Request | failed to fetch branding logo |
+| `BRANDING_COVER_FETCH_FAILED` | `4002802` | 400 | Bad Request | failed to fetch branding cover |
+| `BRANDING_EMAIL_LOGO_FETCH_FAILED` | `4002803` | 400 | Bad Request | failed to fetch branding email logo |
+| `BRANDING_CONTENT_FETCH_FAILED` | `4002804` | 400 | Bad Request | failed to fetch branding content |
+| `BRANDING_STORAGE_UNAVAILABLE` | `5032805` | 503 | Internal server error | branding storage service unavailable |
+| `BRANDING_FILE_MANAGER_UNAVAILABLE` | `5032806` | 503 | Internal server error | branding file manager service unavailable |
+
+### File Manager (Module `21`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `FILE_MANAGER_STORAGE_UNAVAILABLE` | `5032101` | 503 | Storage unavailable | storage service is unavailable |
+| `FILE_MANAGER_QUEUE_UNAVAILABLE` | `5032102` | 503 | Queue unavailable | queue service is unavailable |
+| `FILE_MANAGER_UPLOAD_INTENT_UNAVAILABLE` | `5032103` | 503 | Upload intent unavailable | upload intent service is unavailable |
+| `FILE_MANAGER_ATTACHMENT_SERVICE_UNAVAILABLE` | `5032104` | 503 | Attachment service unavailable | attachment service is unavailable |
+| `FILE_MANAGER_FOLDER_NOT_FOUND` | `4042105` | 404 | Not found | folder not found |
+| `FILE_MANAGER_FILE_NOT_FOUND` | `4042106` | 404 | Not found | file not found |
+| `FILE_MANAGER_ATTACHMENT_NOT_FOUND` | `4042107` | 404 | Not found | attachment not found |
+| `FILE_MANAGER_UPLOAD_INTENT_NOT_FOUND` | `4042108` | 404 | Not found | upload intent not found |
+| `FILE_MANAGER_STATUS_CONFLICT` | `4092109` | 409 | Conflict | file status conflict |
+| `FILE_MANAGER_UPLOAD_INTENT_CONFLICT` | `4092110` | 409 | Conflict | upload intent conflict |
+| `FILE_MANAGER_VALIDATION_FAILED` | `4222111` | 422 | Validation error | file manager validation failed |
+| `FILE_MANAGER_ACTION_FAILED` | `4002112` | 400 | Bad Request | file manager action failed |
+
+### OPC Data (Module `22`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `OPC_NOT_FOUND` | `4042201` | 404 | Not found | opc not found |
+| `OPC_RELATION_DELETE_ERROR` | `4092202` | 409 | Conflict | cannot delete opc due to active relations |
+| `OPC_INVALID_PAYLOAD` | `4222203` | 422 | Validation error | invalid opc payload |
+| `OPC_INVALID_JSON` | `4002204` | 400 | Bad Request | invalid json payload |
+| `OPC_INVALID_UUID` | `4222205` | 422 | Validation error | opc uuid is invalid |
+| `OPC_ID_REQUIRED` | `4222206` | 422 | Validation error | opc id is required |
+| `OPC_ID_MISMATCH` | `4222207` | 422 | Validation error | opc id mismatch |
+| `OPC_ATTRIBUTES_REQUIRED` | `4222208` | 422 | Validation error | at least one opc attribute must be provided |
+| `OPC_TITLE_REQUIRED` | `4222209` | 422 | Validation error | opc title is required |
+| `OPC_CREATE_FAILED` | `4002210` | 400 | Bad Request | failed to create opc |
+| `OPC_UPDATE_FAILED` | `4002211` | 400 | Bad Request | failed to update opc |
+| `OPC_DELETE_FAILED` | `4002212` | 400 | Bad Request | failed to delete opc |
+| `OPC_LIST_FAILED` | `4002213` | 400 | Bad Request | failed to list opc data |
+
+### Patient Data (Module `23`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `PATIENT_DATA_NOT_FOUND` | `4042301` | 404 | Not found | patient data not found |
+| `PATIENT_DATA_RELATION_DELETE_ERROR` | `4092302` | 409 | Conflict | cannot delete patient data due to active relations |
+| `PATIENT_DATA_INVALID_PAYLOAD` | `4222303` | 422 | Validation error | invalid patient data payload |
+| `PATIENT_DATA_INVALID_JSON` | `4002304` | 400 | Bad Request | invalid json payload |
+| `PATIENT_DATA_INVALID_UUID` | `4222305` | 422 | Validation error | patient data uuid is invalid |
+| `PATIENT_DATA_ID_REQUIRED` | `4222306` | 422 | Validation error | patient data id is required |
+| `PATIENT_DATA_ID_MISMATCH` | `4222307` | 422 | Validation error | patient data id mismatch |
+| `PATIENT_DATA_ATTRIBUTES_REQUIRED` | `4222308` | 422 | Validation error | at least one patient data attribute must be provided |
+| `PATIENT_DATA_FAMILY_NAME_REQUIRED` | `4222309` | 422 | Validation error | family_name is required |
+| `PATIENT_DATA_FIRST_NAME_REQUIRED` | `4222310` | 422 | Validation error | first_name is required |
+| `PATIENT_DATA_BIRTH_DATE_INVALID` | `4222311` | 422 | Validation error | birth_date is invalid |
+| `PATIENT_DATA_GENDER_INVALID` | `4222312` | 422 | Validation error | gender is invalid |
+| `PATIENT_DATA_OPC_ID_INVALID` | `4222313` | 422 | Validation error | opc_id is invalid |
+| `PATIENT_DATA_INSURANCE_PATIENT_DATA_ID_INVALID` | `4222314` | 422 | Validation error | insurance_patient_data_id is invalid |
+| `PATIENT_DATA_CREATE_FAILED` | `4002315` | 400 | Bad Request | failed to create patient data |
+| `PATIENT_DATA_UPDATE_FAILED` | `4002316` | 400 | Bad Request | failed to update patient data |
+| `PATIENT_DATA_DELETE_FAILED` | `4002317` | 400 | Bad Request | failed to delete patient data |
+| `PATIENT_DATA_LIST_FAILED` | `4002318` | 400 | Bad Request | failed to list patient data |
+
+### Insurance Patient Data (Module `24`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `INSURANCE_PATIENT_DATA_NOT_FOUND` | `4042401` | 404 | Not found | insurance patient data not found |
+| `INSURANCE_PATIENT_DATA_RELATION_DELETE_ERROR` | `4092402` | 409 | Conflict | cannot delete insurance patient data due to active relations |
+| `INSURANCE_PATIENT_DATA_INVALID_PAYLOAD` | `4222403` | 422 | Validation error | invalid insurance patient data payload |
+| `INSURANCE_PATIENT_DATA_INVALID_JSON` | `4002404` | 400 | Bad Request | invalid json payload |
+| `INSURANCE_PATIENT_DATA_INVALID_UUID` | `4222405` | 422 | Validation error | insurance patient data uuid is invalid |
+| `INSURANCE_PATIENT_DATA_ID_REQUIRED` | `4222406` | 422 | Validation error | insurance patient data id is required |
+| `INSURANCE_PATIENT_DATA_ID_MISMATCH` | `4222407` | 422 | Validation error | insurance patient data id mismatch |
+| `INSURANCE_PATIENT_DATA_ATTRIBUTES_REQUIRED` | `4222408` | 422 | Validation error | at least one insurance patient data attribute must be provided |
+| `INSURANCE_PATIENT_DATA_HEALTH_INSURANCE_ID_INVALID` | `4222409` | 422 | Validation error | health_insurance_companies_id is invalid |
+| `INSURANCE_PATIENT_DATA_FEDERAL_STATE_ID_INVALID` | `4222410` | 422 | Validation error | federal_state_id is invalid |
+| `INSURANCE_PATIENT_DATA_CREATE_FAILED` | `4002411` | 400 | Bad Request | failed to create insurance patient data |
+| `INSURANCE_PATIENT_DATA_UPDATE_FAILED` | `4002412` | 400 | Bad Request | failed to update insurance patient data |
+| `INSURANCE_PATIENT_DATA_DELETE_FAILED` | `4002413` | 400 | Bad Request | failed to delete insurance patient data |
+| `INSURANCE_PATIENT_DATA_LIST_FAILED` | `4002414` | 400 | Bad Request | failed to list insurance patient data |
+
+### Role (Module `25`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `ROLE_NOT_FOUND` | `4042501` | 404 | Not found | role not found |
+| `ROLE_PERMISSION_NOT_FOUND` | `4042502` | 404 | Not found | permission not found |
+| `ROLE_RELATION_DELETE_ERROR` | `4092503` | 409 | Conflict | cannot delete role due to active relations |
+| `ROLE_INVALID_PAYLOAD` | `4222504` | 422 | Validation error | invalid role payload |
+| `ROLE_INVALID_JSON` | `4002505` | 400 | Bad Request | invalid json payload |
+| `ROLE_INVALID_UUID` | `4222506` | 422 | Validation error | role uuid is invalid |
+| `ROLE_INVALID_PERMISSION_UUID` | `4222507` | 422 | Validation error | permission uuid is invalid |
+| `ROLE_ID_REQUIRED` | `4222508` | 422 | Validation error | role id is required |
+| `ROLE_ID_MISMATCH` | `4222509` | 422 | Validation error | role id mismatch |
+| `ROLE_ATTRIBUTES_REQUIRED` | `4222510` | 422 | Validation error | at least one role attribute must be provided |
+| `ROLE_NAME_REQUIRED` | `4222511` | 422 | Validation error | role name is required |
+| `ROLE_PERMISSION_ID_REQUIRED` | `4222512` | 422 | Validation error | permission_id is required |
+| `ROLE_PERMISSION_IDS_EMPTY` | `4222513` | 422 | Validation error | permission_ids must not be empty |
+| `ROLE_CREATE_FAILED` | `4002514` | 400 | Bad Request | failed to create role |
+| `ROLE_UPDATE_FAILED` | `4002515` | 400 | Bad Request | failed to update role |
+| `ROLE_DELETE_FAILED` | `4002516` | 400 | Bad Request | failed to delete role |
+| `ROLE_ASSIGN_FAILED` | `4002517` | 400 | Bad Request | failed to assign permission |
+| `ROLE_REMOVE_FAILED` | `4002518` | 400 | Bad Request | failed to remove permission |
+| `ROLE_LIST_FAILED` | `4002519` | 400 | Bad Request | failed to list role data |
+| `ROLE_PERMISSION_LIST_FAILED` | `4002520` | 400 | Bad Request | failed to list permission data |
+| `ROLE_PERMISSION_UPDATE_FAILED` | `4002521` | 400 | Bad Request | failed to update permission |
+| `ROLE_PERMISSION_REQUIRES_PIN_REQUIRED` | `4222522` | 422 | Validation error | requires_pin is required |
+
+### Flight Data (Module `26`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `FLIGHT_DATA_NOT_FOUND` | `4042601` | 404 | Not found | flight data not found |
+| `FLIGHT_DATA_INVALID_PAYLOAD` | `4222602` | 422 | Validation error | invalid flight data payload |
+| `FLIGHT_DATA_INVALID_JSON` | `4002603` | 400 | Bad Request | invalid json payload |
+| `FLIGHT_DATA_INVALID_PATH_UUID` | `4222604` | 422 | Validation error | path uuid is invalid |
+| `FLIGHT_DATA_MISSION_ID_REQUIRED` | `4222605` | 422 | Validation error | mission_id is required |
+| `FLIGHT_DATA_PILOT_ID_REQUIRED` | `4222606` | 422 | Validation error | pilot_id is required |
+| `FLIGHT_DATA_INVALID_UUID` | `4222607` | 422 | Validation error | uuid is invalid |
+| `FLIGHT_DATA_INVALID_RFC3339` | `4222608` | 422 | Validation error | datetime must be RFC3339 |
+| `FLIGHT_DATA_ORIGIN_LOCATION_REFERENCE` | `4222609` | 422 | Validation error | origin location reference is invalid |
+| `FLIGHT_DATA_DESTINATION_LOCATION_REFERENCE` | `4222610` | 422 | Validation error | destination location reference is invalid |
+| `FLIGHT_DATA_REQUIRED` | `4002611` | 400 | Bad Request | required flight data is missing |
+| `FLIGHT_DATA_CREATE_FAILED` | `4002612` | 400 | Bad Request | failed to create flight data |
+| `FLIGHT_DATA_GET_FAILED` | `4002613` | 400 | Bad Request | failed to get flight data |
+| `FLIGHT_DATA_AFTER_FLIGHT_INCOMPLETE` | `4222616` | 422 | Validation error | cannot submit after-flight: flight data is incomplete |
+| `FLIGHT_DATA_CREATE_BLOCKED` | `4092618` | 409 | Conflict | flight data cannot be created because fm report already exists for this flight |
+| `FLIGHT_DATA_AFTER_FLIGHT_LOCKED` | `4232618` | 423 | Locked | flight data is locked because after flight inspection already exists |
+| `FLIGHT_DATA_LOCKED` | `4232619` | 423 | Locked | flight data is locked because fm report is completed |
+
+### Air Rescuer Checklist (Module `27`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `AIR_RESCUER_CHECKLIST_NOT_FOUND` | `4042701` | 404 | Not found | air rescuer checklist not found |
+| `AIR_RESCUER_CHECKLIST_ITEM_NOT_FOUND` | `4042702` | 404 | Not found | air rescuer checklist item not found |
+| `AIR_RESCUER_CHECKLIST_INVALID_PAYLOAD` | `4222703` | 422 | Validation error | invalid air rescuer checklist payload |
+| `AIR_RESCUER_CHECKLIST_INVALID_JSON` | `4002704` | 400 | Bad Request | invalid json payload |
+| `AIR_RESCUER_CHECKLIST_INVALID_UUID` | `4222705` | 422 | Validation error | air rescuer checklist uuid is invalid |
+| `AIR_RESCUER_CHECKLIST_ID_MISMATCH` | `4222706` | 422 | Validation error | id does not match path uuid |
+| `AIR_RESCUER_CHECKLIST_SCOPE_INVALID` | `4222707` | 422 | Validation error | scope_code is invalid |
+| `AIR_RESCUER_CHECKLIST_SCOPE_REQUIRED` | `4222708` | 422 | Validation error | scope_code is required |
+| `AIR_RESCUER_CHECKLIST_TITLE_REQUIRED` | `4222709` | 422 | Validation error | title is required |
+| `AIR_RESCUER_CHECKLIST_NAME_REQUIRED` | `4222710` | 422 | Validation error | name is required |
+| `AIR_RESCUER_CHECKLIST_BASE_NOT_FOUND` | `4042711` | 404 | Not found | base not found |
+| `AIR_RESCUER_CHECKLIST_CREATE_FAILED` | `4002712` | 400 | Bad Request | failed to create air rescuer checklist |
+| `AIR_RESCUER_CHECKLIST_UPDATE_FAILED` | `4002713` | 400 | Bad Request | failed to update air rescuer checklist |
+| `AIR_RESCUER_CHECKLIST_DELETE_FAILED` | `4002714` | 400 | Bad Request | failed to delete air rescuer checklist |
+| `AIR_RESCUER_CHECKLIST_LIST_FAILED` | `4002715` | 400 | Bad Request | failed to list air rescuer checklist |
+| `AIR_RESCUER_CHECKLIST_REORDER_FAILED` | `4002716` | 400 | Bad Request | failed to reorder air rescuer checklist items |
+| `AIR_RESCUER_CHECKLIST_VALIDATION_FAILED` | `4222717` | 422 | Validation error | air rescuer checklist validation failed |
+
+### After Flight Inspection (Module `37`)
+
+| Code | Error Code | HTTP | Title | Message |
+|---|---:|---:|---|---|
+| `AFTER_FLIGHT_INVALID_ID` | `4223701` | 422 | Validation error | flight_inspection_id is invalid |
+| `AFTER_FLIGHT_FLIGHT_INSPECTION_NOT_FOUND` | `4043702` | 404 | Not found | flight inspection not found |
+| `AFTER_FLIGHT_INSPECTION_NOT_FOUND` | `4043703` | 404 | Not found | after flight inspection not found |
+| `AFTER_FLIGHT_CAPABILITIES_UNAVAILABLE` | `4223704` | 422 | Validation error | helicopter capabilities could not be resolved |
+| `AFTER_FLIGHT_NR1_REQUIRED` | `4223705` | 422 | Validation error | oil_engine_nr1_checked is required for this helicopter |
+| `AFTER_FLIGHT_NR1_NOT_AVAILABLE` | `4223706` | 422 | Validation error | NR1 capability not available on this helicopter |
+| `AFTER_FLIGHT_NR2_REQUIRED` | `4223707` | 422 | Validation error | oil_engine_nr2_checked is required for this helicopter |
+| `AFTER_FLIGHT_NR2_NOT_AVAILABLE` | `4223708` | 422 | Validation error | NR2 capability not available on this helicopter |
+| `AFTER_FLIGHT_LH_REQUIRED` | `4223709` | 422 | Validation error | hydraulic_lh_checked is required for this helicopter |
+| `AFTER_FLIGHT_LH_NOT_AVAILABLE` | `4223710` | 422 | Validation error | LH capability not available on this helicopter |
+| `AFTER_FLIGHT_RH_REQUIRED` | `4223711` | 422 | Validation error | hydraulic_rh_checked is required for this helicopter |
+| `AFTER_FLIGHT_RH_NOT_AVAILABLE` | `4223712` | 422 | Validation error | RH capability not available on this helicopter |
+| `AFTER_FLIGHT_MGB_REQUIRED` | `4223713` | 422 | Validation error | oil_transmission_mgb_checked is required for this helicopter |
+| `AFTER_FLIGHT_MGB_NOT_AVAILABLE` | `4223714` | 422 | Validation error | MGB capability not available on this helicopter |
+| `AFTER_FLIGHT_IGB_REQUIRED` | `4223715` | 422 | Validation error | oil_transmission_igb_checked is required for this helicopter |
+| `AFTER_FLIGHT_IGB_NOT_AVAILABLE` | `4223716` | 422 | Validation error | IGB capability not available on this helicopter |
+| `AFTER_FLIGHT_TGB_REQUIRED` | `4223717` | 422 | Validation error | oil_transmission_tgb_checked is required for this helicopter |
+| `AFTER_FLIGHT_TGB_NOT_AVAILABLE` | `4223718` | 422 | Validation error | TGB capability not available on this helicopter |
+| `AFTER_FLIGHT_INVALID_JSON` | `4003719` | 400 | Bad Request | invalid json payload |
+
+## Notes
+
+- `title` dan `detail` dapat berubah mengikuti copywriting; jangan dijadikan kontrak parsing.
+- `code` dan `error_code` harus dianggap stabil sebagai kontrak integrasi BE↔FE.
+- Uniqueness `code` dan `error_code` divalidasi lewat test registry di package [apperrorsx](../internal/shared/pkg/apperrorsx) (`registry_test.go`).
+- Sumber definisi tunggal: [codes_defs.go](../internal/shared/pkg/apperrorsx/codes_defs.go) (konstanta `Code*`, `Case*`, dan variable `Err*` + `Registry`).
+- Jika menambah error baru: daftarkan di `codes_defs.go` (konstanta + variable `Err*`) lalu masukkan ke `Registry`, kemudian update tabel di catalog ini.
diff --git a/docs/file-lifecycle-s3-cleanup.md b/docs/file-lifecycle-s3-cleanup.md
new file mode 100644
index 0000000..881c3d7
--- /dev/null
+++ b/docs/file-lifecycle-s3-cleanup.md
@@ -0,0 +1,124 @@
+# File Lifecycle and S3 Cleanup
+
+## Lifecycle States (DB source of truth)
+
+`file_files.lifecycle_status`:
+
+- `temp`: uploaded but not attached
+- `active`: referenced by one or more business entities
+- `orphan_pending`: currently unreferenced, waiting grace period
+- `deleted`: backend cleanup has deleted object(s) and marked terminal state
+
+Supporting timestamps:
+
+- `created_at`: existing file creation time
+- `attached_at`: set when file becomes active
+- `orphaned_at`: set when file becomes unreferenced
+- `lifecycle_deleted_at`: set when cleanup marks lifecycle `deleted`
+
+Notes:
+
+- Existing `status` column (`uploaded/processing/validated/ready/trashed`) remains for processing/trash flow.
+- `deleted_at` is still used by trash semantics. Cleanup lifecycle uses `lifecycle_deleted_at`.
+
+## S3 Tags
+
+Single tag key: `gc`
+
+- `gc=temp`: temporary uploads
+- `gc=keep`: active or protected files
+- `gc=delete`: optional marker immediately before backend delete
+
+S3 tags are markers only. DB lifecycle state and DB reference checks are authoritative.
+
+## Cleanup Job
+
+Scheduler: API process loop (`startFileManagerLifecycleCleanupLoop`).
+
+Behavior:
+
+1. Query DB for `orphan_pending` files where `orphaned_at <= now - ORPHAN_GRACE_PERIOD_DAYS`.
+2. Process in batches (`FILE_CLEANUP_BATCH_SIZE`).
+3. Re-check DB references per file before deletion.
+4. If referenced again: mark `active`, set/keep `gc=keep`.
+5. If still unreferenced:
+   - optional `gc=delete` tag
+   - delete original and thumbnail S3 objects
+   - mark lifecycle `deleted` and set `lifecycle_deleted_at`
+6. Per-file error handling; one failure does not stop the batch.
+
+The job is idempotent and retry-safe.
+
+## Environment Variables
+
+- `ENABLE_S3_TAGGING` (default `true`)
+- `ENABLE_FILE_CLEANUP_JOB` (default `false`)
+- `TEMP_FILE_TTL_DAYS` (default `7`)
+- `ORPHAN_GRACE_PERIOD_DAYS` (default `30`)
+- `FILE_CLEANUP_BATCH_SIZE` (default `100`)
+- `FILE_CLEANUP_DRY_RUN` (default `true`)
+
+## Backfill (Dry-Run First)
+
+Command:
+
+```bash
+go run ./cmd/file-lifecycle-backfill
+```
+
+Optional:
+
+- `BACKFILL_DRY_RUN=true|false` (default `true`)
+
+Output report includes:
+
+- active files
+- probable orphan files
+- missing S3 key
+- invalid references
+- skipped records
+
+## Required IAM Permissions
+
+Minimum required:
+
+- `s3:PutObjectTagging`
+- `s3:GetObjectTagging`
+- `s3:DeleteObject`
+- `s3:GetObject`
+- `s3:HeadObject`
+
+Only if infra automation updates lifecycle rules:
+
+- `s3:PutLifecycleConfiguration`
+
+## S3 Lifecycle Rules (Manual if no IaC)
+
+Because this repository does not define Terraform/CDK/CloudFormation for S3 bucket lifecycle, configure lifecycle rules in your infra/deployment stack:
+
+1. Rule `gc=temp`:
+   - Filter: object tag `gc=temp`
+   - Expire after `TEMP_FILE_TTL_DAYS` (recommended default 7 days)
+
+2. Optional rule `gc=delete`:
+   - Filter: object tag `gc=delete`
+   - Expire after 1 day
+
+Do not use lifecycle expiration as the orphan grace mechanism. Grace period is enforced by DB `orphaned_at`.
+
+## Rollout Plan
+
+1. Deploy schema + code with defaults (`cleanup job off`, `dry-run on`).
+2. Enable tagging for new uploads (`ENABLE_S3_TAGGING=true`).
+3. Validate attach/detach transitions in logs.
+4. Run backfill dry-run and review report.
+5. Enable cleanup job in dry-run mode.
+6. Switch cleanup dry-run off after validation.
+7. Apply S3 lifecycle rules for `gc=temp` (and optional `gc=delete`).
+
+## Rollback Plan
+
+1. Set `ENABLE_FILE_CLEANUP_JOB=false`.
+2. Set `FILE_CLEANUP_DRY_RUN=true`.
+3. Optionally set `ENABLE_S3_TAGGING=false`.
+4. Pause/remove lifecycle rule `gc=delete` if enabled.
diff --git a/docs/file-manager-aircraft-upload-create.md b/docs/file-manager-aircraft-upload-create.md
new file mode 100644
index 0000000..84efbf7
--- /dev/null
+++ b/docs/file-manager-aircraft-upload-create.md
@@ -0,0 +1,143 @@
+# File Manager Aircraft Image Flow
+
+This document explains the upload + create flow specifically for aircraft images.
+
+## Purpose
+
+This flow is used to upload aircraft images (drag-and-drop) and persist file metadata into a forced folder hierarchy based on the aircraft designation.
+
+Main differences compared to the regular file flow:
+- dedicated upload endpoint: `POST /api/v1/file-manager/files/upload-aircraft-image`
+- dedicated create endpoint: `POST /api/v1/file-manager/files/create-aircraft-image`
+- `content_type` must be `image/*`
+- target folder is forced to: `__system_root_files__ > aircraft > <aircraft designation>`
+- `aircraft_uuid` is required in the create request per item
+
+## Prerequisites
+
+1. User is logged in and has `file_manager.create` permission.
+2. Frontend has per-file data: `name`, `content_type`, `size_bytes`, and binary file.
+
+## Step 1 - Request Upload Intent (Aircraft)
+
+Endpoint:
+- `POST /api/v1/file-manager/files/upload-aircraft-image`
+
+Request body (bulk, minimum 1 item):
+
+```json
+{
+  "data": [
+    {
+      "type": "file_manager_file_upload_intent",
+      "attributes": {
+        "name": "aircraft-front.jpg",
+        "content_type": "image/jpeg",
+        "size_bytes": 42170
+      }
+    }
+  ]
+}
+```
+
+Important validation rules in this endpoint:
+- `data` must be an array
+- `type` must be `file_manager_file_upload_intent`
+- `name` is required
+- `content_type` is required and must start with `image/`
+- `size_bytes >= 0`
+
+Per-item response (partial success is possible), FE receives:
+- `upload_intent_uuid`
+- `upload_url`
+- `method` (`PUT`)
+- `required_headers`
+- object info (`bucket`, `key`)
+- `expires_at`, `expires_in_seconds`
+
+## Step 2 - Upload Binary Directly to Object Storage
+
+For each item with `success: true` from step 1:
+1. take `upload_url`
+2. perform `PUT` binary file to that URL
+3. send headers according to `required_headers`
+
+Example:
+
+```javascript
+await fetch(upload_url, {
+  method: "PUT",
+  headers: {
+    "Content-Type": file.type
+  },
+  body: file
+});
+```
+
+Notes:
+- 1 file = 1 `PUT` request
+- parallel upload is allowed with a concurrency limit
+- files that fail `PUT` must not be sent to the create step
+
+## Step 3 - Create File Record (Aircraft)
+
+Endpoint:
+- `POST /api/v1/file-manager/files/create-aircraft-image`
+
+Request body:
+
+```json
+{
+  "data": [
+    {
+      "type": "file_manager_file_create",
+      "attributes": {
+        "upload_intent_uuid": "019d8215-c622-7576-86bd-3ddeecaf4867",
+        "aircraft_uuid": "019d8215-c799-7209-9237-2e2f5d0f8709",
+        "name": "aircraft-front.jpg"
+      }
+    }
+  ]
+}
+```
+
+Important validation rules:
+- `data` must be an array
+- `type` must be `file_manager_file_create` or `file_manager_file`
+- `upload_intent_uuid` is required and must be a valid UUID
+- `aircraft_uuid` is required and must be a valid UUID
+- `name` is required
+
+Aircraft-specific behavior:
+- backend loads aircraft by `aircraft_uuid` and reads its `designation`
+- backend resolves/creates folder hierarchy:
+  - `__system_root_files__` (system root)
+  - `aircraft` under system root
+  - `<designation>` under `aircraft` (example: `OE-XHZ`)
+- final file is created inside `<designation>` folder
+- `folder_id` from payload is ignored in this endpoint because folder is derived from aircraft designation
+
+## Step 4 - Backend Process During Create
+
+For each valid item:
+1. backend validates and loads aircraft from `aircraft_uuid`
+2. backend resolves/creates `__system_root_files__ > aircraft > <designation>`
+3. backend validates uploaded object from `upload_intent_uuid`
+4. backend creates file node in `<designation>` folder
+5. file status enters normal file manager lifecycle (`uploaded -> processing -> validated -> ready` or failed)
+
+## Status Codes
+
+- `201`: all create items succeed
+- `207`: partial success (mixed success and failure)
+- `404`: aircraft not found (per-item in bulk response)
+- `422`: payload validation error
+- `400`: invalid JSON payload
+- `503`: aircraft service unavailable
+
+## FE Integration Summary
+
+1. call `upload-aircraft-image`
+2. upload binary to storage via presigned URL
+3. call `create-aircraft-image` only for items with successful `PUT`
+4. store resulting file `id` for reference in aircraft module
diff --git a/docs/file-manager-attachment.md b/docs/file-manager-attachment.md
new file mode 100644
index 0000000..43560f2
--- /dev/null
+++ b/docs/file-manager-attachment.md
@@ -0,0 +1,73 @@
+# File Manager
+
+# Attachment (Step by Step)
+
+## A. Tambah Attachment
+
+### Endpoint
+- `POST /api/v1/file-manager/attachments/create`
+
+### FE kirim request ini
+
+```json
+{
+  "data": {
+    "type": "file_manager_attachment_create",
+    "attributes": {
+      "file_id": "file-uuid",
+      "ref_type": "helicopter",
+      "ref_id": "business-entity-uuid",
+      "category": "document",
+      "sort_order": 0,
+      "is_primary": false
+    }
+  }
+}
+```
+
+Keterangan:
+- `file_id`, `ref_type`, `ref_id` wajib
+- `category` opsional
+- `sort_order` opsional (default 0)
+- `is_primary` opsional (default false)
+
+## B. Lihat Attachment by Reference
+
+### Endpoint
+- `GET /api/v1/file-manager/attachments/get-all?ref_type=<type>&ref_id=<id>`
+
+### Contoh
+- `GET /api/v1/file-manager/attachments/get-all?ref_type=helicopter&ref_id=business-entity-uuid`
+
+Catatan urutan default:
+- jika query `sort` tidak dikirim, urutan default adalah `sort_order ASC, created_at DESC`
+- artinya untuk `sort_order` yang sama, attachment terbaru tampil lebih dulu
+
+## C. Detail Attachment
+
+### Endpoint
+- `GET /api/v1/file-manager/attachments/get/:uuid`
+
+## D. Hapus Attachment (Detach)
+
+### Endpoint
+- `DELETE /api/v1/file-manager/attachments/delete/:uuid`
+
+### Contoh response
+
+```json
+{
+  "data": {
+    "type": "file_manager_attachment_delete",
+    "attributes": {
+      "detached": true
+    }
+  }
+}
+```
+
+## Ringkasan
+1. create relation file -> entity bisnis
+2. list by `ref_type + ref_id`
+3. get detail relation
+4. delete relation (detach)
diff --git a/docs/file-manager-base-upload-create.md b/docs/file-manager-base-upload-create.md
new file mode 100644
index 0000000..47b8b52
--- /dev/null
+++ b/docs/file-manager-base-upload-create.md
@@ -0,0 +1,62 @@
+# File Manager Base Image Flow
+
+This document explains upload + create flow specifically for base images.
+
+## Purpose
+
+This flow uploads base images and persists file metadata into a forced folder hierarchy:
+
+- `__system_root_files__ > bases > <base-type> > <base-name>`
+
+Main differences compared to regular file flow:
+
+- dedicated upload endpoint: `POST /api/v1/file-manager/files/upload-base-image`
+- dedicated create endpoint: `POST /api/v1/file-manager/files/create-base-image`
+- `content_type` must be `image/*`
+- `base_uuid` is required in the create request per item
+- create step performs hard replace of existing files in target folder before creating new file
+
+## Step 1 - Request Upload Intent (Base)
+
+Endpoint:
+
+- `POST /api/v1/file-manager/files/upload-base-image`
+
+Validation highlights:
+
+- `type` must be `file_manager_file_upload_intent`
+- `name` required
+- `content_type` required and must start with `image/`
+- `size_bytes >= 0`
+
+## Step 2 - Upload Binary to Object Storage
+
+For each successful intent, frontend uploads binary with `PUT` to `upload_url`.
+
+## Step 3 - Create File Record (Base)
+
+Endpoint:
+
+- `POST /api/v1/file-manager/files/create-base-image`
+
+Validation highlights:
+
+- `type` must be `file_manager_file_create` or `file_manager_file`
+- `upload_intent_uuid` required and valid UUID
+- `base_uuid` required and valid UUID
+- `name` required
+
+Backend behavior:
+
+1. load base from `base_uuid`
+2. resolve `base-type` from base category (e.g. `hems` or `regular`)
+3. resolve/create folder path `__system_root_files__ > bases > <base-type> > <base-name>`
+4. hard replace: delete + purge all existing files in that target folder
+5. create file node from upload intent
+
+Hard replace cleanup target:
+
+- file row in DB
+- original object in S3
+- thumbnail object in S3 (if exists)
+- related attachment metadata
diff --git a/docs/file-manager-collabora-wopi-flow.md b/docs/file-manager-collabora-wopi-flow.md
new file mode 100644
index 0000000..2bfdac2
--- /dev/null
+++ b/docs/file-manager-collabora-wopi-flow.md
@@ -0,0 +1,829 @@
+# File Manager Collabora / WOPI Flow
+
+Dokumen ini menjelaskan alur frontend untuk membuka editor Collabora lewat backend WOPI.
+
+Prinsip utama:
+
+1. Frontend hanya memanggil App API.
+2. Frontend tidak pernah memanggil endpoint `/wopi/...` secara langsung.
+3. Backend yang mengurus token, proof, S3, lock, autosave, dan finalisasi.
+
+Tambahan penting untuk flow helicopter template:
+
+1. hasil `create-from-template` akan dibuat sebagai file manager file biasa, bukan template
+2. backend juga akan memastikan file itu masuk ke `helicopter_files` section `fpwb`
+3. kalau frontend membuka template yang sama untuk `takeover_id` yang sama, backend akan reuse file existing bila sudah ada
+4. saat child `fpwb` baru berhasil dibuat, backend akan kirim SSE agar frontend bisa langsung append item baru ke list
+5. kalau file hasil template punya `takeover_id`, endpoint `GET /api/v1/helicopter-files/get/{helicopter_id}` dan `GET /api/v1/helicopter-files/list` akan menyembunyikan item itu dari user yang tidak punya akses takeover tersebut
+
+## Endpoint Yang Dipakai Frontend
+
+### 1) Buat file baru dari template
+
+`POST /api/v1/file-manager/files/create-from-template`
+
+Request:
+
+```json
+{
+  "data": {
+    "type": "file_manager_file_create_from_template",
+    "attributes": {
+      "template_uuid": "019f0386-0a00-7a4a-a2d8-30afc0e0c3ad",
+      "helicopter_id": "019e8713-aa19-7fb7-a510-a0332dc69697",
+      "takeover_id": "019f0386-0a00-7a4a-a2d8-30afc0e0c3af",
+      "name": "collabora-draft.docx"
+    }
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "data": {
+    "file_id": "019f0a12-1111-7abc-8def-222222222222",
+    "collabora_action": "https://collabora.example.com/.../WOPISrc=...",
+    "access_token": "eyJhbGciOiJIUzI1NiIs...",
+    "access_token_ttl": 1800000
+  }
+}
+```
+
+### 2) Buka editor untuk file existing
+
+`GET /api/v1/file-manager/files/{fileId}/edit-session`
+
+Response shape sama:
+
+```json
+{
+  "data": {
+    "file_id": "019f0a12-1111-7abc-8def-222222222222",
+    "collabora_action": "https://collabora.example.com/.../WOPISrc=...",
+    "access_token": "eyJhbGciOiJIUzI1NiIs...",
+    "access_token_ttl": 1800000
+  }
+}
+```
+
+### 3) Ambil daftar helicopter files
+
+`GET /api/v1/helicopter-files/get/{helicopter_id}`
+
+Endpoint ini yang dipakai frontend untuk melihat child file yang muncul di helicopter file collection.
+
+Untuk hasil `create-from-template`, item baru akan muncul di:
+
+1. `data.attributes.files.prepare`
+2. section backend = `fpwb`
+3. secara UI biasanya ditampilkan sebagai area Flight Preparation and WB
+
+### 4) Dengarkan event child baru
+
+`GET /api/v1/helicopter-files/events?helicopter_id={helicopter_id}`
+
+Stream ini dipakai supaya frontend bisa langsung append child baru tanpa reload penuh.
+
+Event name:
+
+`helicopter.file.created`
+
+### SSE dapet dari mana?
+
+SSE ini bukan datang dari Collabora, bukan dari browser local state, dan bukan dari endpoint `/wopi/...`.
+
+Sumbernya adalah backend App API:
+
+1. frontend subscribe ke `GET /api/v1/helicopter-files/events?helicopter_id={helicopter_id}`
+2. route ini masuk ke handler SSE backend
+3. backend hanya akan mengirim event ke user yang sedang subscribe
+4. event difilter lagi dengan `helicopter_id` query param
+
+Kapan event dipublish:
+
+1. frontend memanggil `POST /api/v1/file-manager/files/create-from-template`
+2. backend membuat atau reuse file manager file
+3. backend memastikan ada row `helicopter_files` di section `fpwb`
+4. kalau row `helicopter_files` itu baru dibuat saat request ini, backend publish event `helicopter.file.created`
+5. stream `/api/v1/helicopter-files/events` mengirim event itu ke frontend yang subscribe
+
+Artinya:
+
+1. kalau child `fpwb` sudah ada dari sebelumnya, backend tidak akan publish event create lagi
+2. kalau frontend telat subscribe, fallback paling aman tetap re-fetch `GET /api/v1/helicopter-files/get/{helicopter_id}`
+3. SSE ini hanya untuk sinkronisasi UI realtime, bukan source of truth utama
+
+## Flow Create From Template
+
+### Step 1 - Frontend minta editor session
+
+Frontend mengirim `template_uuid`, `helicopter_id`, `name`, dan boleh menambahkan `takeover_id`.
+`template_uuid` harus mengarah ke `helicopter_file.helicopter_file_id` dari helicopter yang sama dengan `helicopter_id`, bukan ke file takeover biasa.
+
+Backend akan menjalankan alur seperti ini:
+
+```text
+create-from-template
+  -> cek user session
+  -> cek template memang milik helicopter itu
+  -> jika ada takeover_id:
+       -> cek apakah kombinasi template + takeover sudah punya file existing
+       -> jika sudah ada:
+            -> reuse file existing
+            -> pastikan metadata template + takeover tersimpan
+            -> pastikan ada child helicopter_files di section fpwb
+            -> jika child baru dibuat, publish SSE helicopter.file.created
+            -> mint WOPI token
+            -> balikin Collabora action URL
+       -> jika belum ada:
+            -> buat draft file baru dari template
+            -> copy object template ke key final file baru
+            -> simpan metadata template + takeover
+            -> pastikan ada child helicopter_files di section fpwb
+            -> jika child baru dibuat, publish SSE helicopter.file.created
+            -> mint WOPI token
+            -> balikin Collabora action URL
+  -> jika takeover_id tidak ada:
+       -> buat draft file baru dari template
+       -> copy object template ke key final file baru
+       -> simpan metadata template
+       -> pastikan ada child helicopter_files di section fpwb
+       -> jika child baru dibuat, publish SSE helicopter.file.created
+       -> mint WOPI token
+       -> balikin Collabora action URL
+```
+
+Catatan untuk step 9:
+
+1. SSE dipublish oleh backend App API pada request `create-from-template`
+2. jadi FE yang sedang membuka halaman helicopter files bisa langsung menerima event tanpa menunggu save dari Collabora
+3. source of truth event tetap berasal dari proses create child row di backend
+
+### Step 2 - Frontend simpan response
+
+Frontend wajib menyimpan:
+
+1. `file_id`
+2. `collabora_action`
+3. `access_token`
+4. `access_token_ttl` dalam milidetik
+
+`file_id` dipakai sebagai join key untuk session berikutnya.
+`file_id` ini juga bisa dikirim lagi saat frontend create takeover lewat field `edited_template_file_ids`.
+
+Kalau tujuan frontend adalah menampilkan child di helicopter files:
+
+1. `file_id` adalah ID file manager file
+2. `helicopter_file_id` tidak ada di response create-from-template
+3. `helicopter_file_id` akan muncul lewat:
+   `GET /api/v1/helicopter-files/get/{helicopter_id}`
+   atau SSE `helicopter.file.created`
+
+### Step 3 - Frontend buka Collabora
+
+Frontend tidak boleh hanya redirect atau `window.open(collabora_action)` begitu saja.
+
+`collabora_action` harus dibuka dengan `POST` form yang ikut mengirim:
+
+1. `access_token`
+2. `access_token_ttl` dalam milidetik
+
+Ini penting karena backend WOPI membaca token dari query `access_token` atau header bearer pada request WOPI yang datang dari Collabora.
+Kalau frontend hanya membuka `collabora_action` tanpa token bootstrap, backend akan mengembalikan error seperti:
+
+1. `401 FILE_MANAGER_WOPI_INVALID_TOKEN`
+2. `token is malformed: token contains an invalid number of segments`
+
+Frontend membuka editor memakai:
+
+1. `collabora_action` sebagai `form action`
+2. `access_token` sebagai hidden input
+3. `access_token_ttl` sebagai hidden input
+
+Rule praktis:
+
+1. jangan pernah memanggil `/wopi/...` dari browser
+2. jangan pernah expose S3 URL atau credential ke frontend
+3. gunakan `collabora_action` sebagai base URL editor
+4. jangan buka `collabora_action` tanpa submit `access_token`
+
+## File Akan Muncul Di Mana
+
+Setelah `create-from-template` sukses, hasil akhirnya ada di dua tempat berbeda yang perlu dibedakan:
+
+### 1) File manager file
+
+Ini adalah object file utama yang dibuka oleh Collabora.
+
+Identifier utamanya:
+
+1. `file_id`
+
+Endpoint yang relevan:
+
+1. `GET /api/v1/file-manager/files/{fileId}/edit-session`
+2. WOPI internal backend `/wopi/files/{fileId}` dan `/wopi/files/{fileId}/contents`
+
+### 2) Helicopter file child
+
+Ini adalah row bisnis yang membuat file tadi muncul di halaman helicopter files.
+
+Lokasinya:
+
+1. `GET /api/v1/helicopter-files/get/{helicopter_id}`
+2. response path `data.attributes.files.prepare`
+3. section row = `fpwb`
+
+Field penting item collection:
+
+1. `helicopter_file_id`
+2. `attachment.id`
+3. `attachment.file_name`
+
+Catatan:
+
+1. child ini bukan parent folder file manager
+2. child ini adalah row di tabel `helicopter_files`
+3. relasinya menunjuk ke file hasil template lewat `source_file_id`
+
+## Contoh Integrasi Next.js
+
+Bagian ini menunjukkan contoh yang lengkap untuk Next.js App Router.
+
+Asumsi:
+
+1. user sudah login ke App API
+2. frontend memanggil backend App API, bukan endpoint `/wopi/...`
+3. backend mengembalikan `file_id`, `collabora_action`, `access_token`, dan `access_token_ttl`
+
+### Tipe response
+
+```ts
+export type CollaboraSessionResponse = {
+  data: {
+    file_id: string
+    collabora_action: string
+    access_token: string
+    access_token_ttl: number
+  }
+}
+```
+
+### Server action atau API helper
+
+Contoh helper untuk memanggil backend `create-from-template`.
+
+```ts
+// app/lib/file-manager.ts
+export type CreateFromTemplateInput = {
+  templateUuid: string
+  helicopterId: string
+  takeoverId?: string
+  name: string
+}
+
+export type CollaboraSessionResponse = {
+  data: {
+    file_id: string
+    collabora_action: string
+    access_token: string
+    access_token_ttl: number
+  }
+}
+
+export async function createFromTemplate(
+  input: CreateFromTemplateInput,
+  accessToken: string,
+): Promise<CollaboraSessionResponse> {
+  const response = await fetch(
+    `${process.env.NEXT_PUBLIC_API_BASE_URL}/api/v1/file-manager/files/create-from-template`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${accessToken}`,
+      },
+      body: JSON.stringify({
+        data: {
+          type: "file_manager_file_create_from_template",
+          attributes: {
+            template_uuid: input.templateUuid,
+            helicopter_id: input.helicopterId,
+            takeover_id: input.takeoverId,
+            name: input.name,
+          },
+        },
+      }),
+      cache: "no-store",
+    },
+  )
+
+  if (!response.ok) {
+    throw new Error(`Create from template failed with status ${response.status}`)
+  }
+
+  return response.json()
+}
+```
+
+Contoh helper untuk membuka file existing:
+
+```ts
+// app/lib/file-manager.ts
+export async function getEditSession(
+  fileId: string,
+  accessToken: string,
+): Promise<CollaboraSessionResponse> {
+  const response = await fetch(
+    `${process.env.NEXT_PUBLIC_API_BASE_URL}/api/v1/file-manager/files/${fileId}/edit-session`,
+    {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+      cache: "no-store",
+    },
+  )
+
+  if (!response.ok) {
+    throw new Error(`Edit session failed with status ${response.status}`)
+  }
+
+  return response.json()
+}
+```
+
+### Komponen client untuk bootstrap Collabora
+
+Komponen ini membuat form hidden dan auto-submit ke `collabora_action`.
+
+```tsx
+// app/components/collabora-launcher.tsx
+"use client"
+
+import { useEffect, useRef } from "react"
+
+type Props = {
+  collaboraAction: string
+  accessToken: string
+  accessTokenTTL: number // milliseconds
+  target?: string
+}
+
+export function CollaboraLauncher({
+  collaboraAction,
+  accessToken,
+  accessTokenTTL,
+  target = "collabora-editor",
+}: Props) {
+  const formRef = useRef<HTMLFormElement | null>(null)
+
+  useEffect(() => {
+    formRef.current?.submit()
+  }, [])
+
+  return (
+    <>
+      <form ref={formRef} action={collaboraAction} method="post" target={target}>
+        <input type="hidden" name="access_token" value={accessToken} />
+        <input type="hidden" name="access_token_ttl" value={String(accessTokenTTL)} />
+      </form>
+
+      <iframe
+        name={target}
+        title="Collabora Editor"
+        className="h-[calc(100vh-120px)] w-full border-0"
+      />
+    </>
+  )
+}
+```
+
+### Halaman Next.js untuk create from template
+
+Contoh berikut memakai App Router dan menampilkan editor setelah session berhasil dibuat.
+
+```tsx
+// app/file-manager/templates/[templateId]/open/page.tsx
+import { CollaboraLauncher } from "@/app/components/collabora-launcher"
+import { createFromTemplate } from "@/app/lib/file-manager"
+import { cookies } from "next/headers"
+
+type PageProps = {
+  params: Promise<{
+    templateId: string
+  }>
+  searchParams: Promise<{
+    helicopterId?: string
+    name?: string
+  }>
+}
+
+export default async function OpenTemplatePage({ params, searchParams }: PageProps) {
+  const { templateId } = await params
+  const { helicopterId, name } = await searchParams
+
+  if (!helicopterId || !name) {
+    throw new Error("helicopterId and name are required")
+  }
+
+  const cookieStore = await cookies()
+  const accessToken = cookieStore.get("access_token")?.value
+  if (!accessToken) {
+    throw new Error("Missing app access token")
+  }
+
+  const session = await createFromTemplate(
+    {
+      templateUuid: templateId,
+      helicopterId,
+      name,
+    },
+    accessToken,
+  )
+
+  return (
+    <CollaboraLauncher
+      collaboraAction={session.data.collabora_action}
+      accessToken={session.data.access_token}
+      accessTokenTTL={session.data.access_token_ttl}
+    />
+  )
+}
+```
+
+### Halaman Next.js untuk file existing
+
+```tsx
+// app/file-manager/files/[fileId]/edit/page.tsx
+import { CollaboraLauncher } from "@/app/components/collabora-launcher"
+import { getEditSession } from "@/app/lib/file-manager"
+import { cookies } from "next/headers"
+
+type PageProps = {
+  params: Promise<{
+    fileId: string
+  }>
+}
+
+export default async function EditFilePage({ params }: PageProps) {
+  const { fileId } = await params
+
+  const cookieStore = await cookies()
+  const accessToken = cookieStore.get("access_token")?.value
+  if (!accessToken) {
+    throw new Error("Missing app access token")
+  }
+
+  const session = await getEditSession(fileId, accessToken)
+
+  return (
+    <CollaboraLauncher
+      collaboraAction={session.data.collabora_action}
+      accessToken={session.data.access_token}
+      accessTokenTTL={session.data.access_token_ttl}
+    />
+  )
+}
+```
+
+### Kenapa tidak cukup pakai `window.open(collabora_action)`?
+
+Karena response backend memisahkan:
+
+1. `collabora_action`
+2. `access_token`
+3. `access_token_ttl`
+
+Sedangkan backend WOPI membutuhkan token valid saat Collabora mulai memanggil:
+
+1. `GET /wopi/files/{fileId}`
+2. `GET /wopi/files/{fileId}/contents`
+
+Kalau frontend hanya membuka URL editor tanpa mengirim hidden form fields di atas, Collabora akan tetap mencoba request WOPI, tetapi backend akan membaca token kosong atau malformed.
+
+### Contoh yang salah
+
+```tsx
+window.open(session.data.collabora_action, "_blank")
+```
+
+atau:
+
+```tsx
+<iframe src={session.data.collabora_action} />
+```
+
+Kedua contoh di atas tidak mengirim `access_token` bootstrap.
+
+### Contoh yang benar
+
+```tsx
+<form action={session.data.collabora_action} method="post" target="collabora-editor">
+  <input type="hidden" name="access_token" value={session.data.access_token} />
+  <input
+    type="hidden"
+    name="access_token_ttl"
+    value={String(session.data.access_token_ttl)}
+  />
+</form>
+```
+
+### Step 4 - Autosave berjalan di backend
+
+Setelah editor terbuka:
+
+1. Collabora memanggil `GET /wopi/files/{fileId}`
+2. Collabora memanggil `GET /wopi/files/{fileId}/contents`
+3. saat autosave, Collabora memanggil `POST /wopi/files/{fileId}/contents`
+4. saat close / exit save, Collabora mengirim lifecycle headers
+
+Frontend tidak perlu mengurus autosave secara manual.
+
+## Flow Tampilan Child Di Helicopter Files
+
+Kalau FE punya halaman detail helicopter files yang memanggil:
+
+`GET /api/v1/helicopter-files/get/{helicopter_id}`
+
+maka flow lengkapnya begini:
+
+### Step 1 - Load data awal
+
+Frontend fetch:
+
+`GET /api/v1/helicopter-files/get/{helicopter_id}`
+
+Lalu render:
+
+1. `data.attributes.files.before`
+2. `data.attributes.files.prepare`
+3. `data.attributes.files.after`
+
+Hasil `create-from-template` akan masuk ke array:
+
+`data.attributes.files.prepare`
+
+### Step 2 - Subscribe SSE
+
+Saat halaman helicopter files terbuka, frontend subscribe:
+
+`GET /api/v1/helicopter-files/events?helicopter_id={helicopter_id}`
+
+Event yang perlu didengar:
+
+`helicopter.file.created`
+
+Penjelasan singkat:
+
+1. endpoint ini adalah stream SSE dari backend App API
+2. backend akan keep connection tetap hidup dan mengirim heartbeat
+3. event akan dikirim ketika backend membuat child `helicopter_file` baru untuk helicopter itu
+4. event ini tidak tergantung pada autosave WOPI
+
+Contoh payload:
+
+```json
+{
+  "helicopter_id": "019dfb9e-db0c-7eaf-b701-8b4928e62d24",
+  "helicopter_file_id": "019f2000-aaaa-7bbb-8ccc-111111111111",
+  "file_id": "019f2000-dddd-7eee-8fff-222222222222",
+  "section": "fpwb",
+  "position": 3,
+  "is_mandatory": false,
+  "attachment_pending": true,
+  "name": "collabora-draft.docx",
+  "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "updated_at": "2026-07-01T08:30:00Z"
+}
+```
+
+### Step 3 - Append child baru ke state
+
+Kalau frontend menerima event:
+
+1. cocokkan `helicopter_id`
+2. cek `section === "fpwb"`
+3. append ke collection `prepare`
+4. hindari duplikasi dengan key `helicopter_file_id`
+
+Contoh Next.js client hook:
+
+```tsx
+"use client"
+
+import { useEffect } from "react"
+
+type HelicopterFileCreatedEvent = {
+  helicopter_id: string
+  helicopter_file_id: string
+  file_id: string
+  section: string
+  position: number
+  is_mandatory: boolean
+  attachment_pending: boolean
+  name: string
+  mime_type: string
+  updated_at: string
+}
+
+type PrepareItem = {
+  helicopter_file_id: string
+  section: string
+  position: number
+  is_mandatory: boolean
+  attachment_pending: boolean
+  attachment: {
+    id: string
+    file_name: string
+    download_url: string
+  }
+  created_at: string
+  updated_at: string
+}
+
+export function useHelicopterFileCreatedSSE(
+  helicopterId: string,
+  onCreated: (event: HelicopterFileCreatedEvent) => void,
+) {
+  useEffect(() => {
+    const url = new URL(
+      `${process.env.NEXT_PUBLIC_API_BASE_URL}/api/v1/helicopter-files/events`,
+    )
+    url.searchParams.set("helicopter_id", helicopterId)
+
+    const source = new EventSource(url.toString(), { withCredentials: true })
+
+    const handler = (raw: MessageEvent<string>) => {
+      const payload = JSON.parse(raw.data) as HelicopterFileCreatedEvent
+      onCreated(payload)
+    }
+
+    source.addEventListener("helicopter.file.created", handler as EventListener)
+
+    return () => {
+      source.removeEventListener(
+        "helicopter.file.created",
+        handler as EventListener,
+      )
+      source.close()
+    }
+  }, [helicopterId, onCreated])
+}
+```
+
+Contoh append ke state:
+
+```tsx
+setPrepareFiles((current) => {
+  if (current.some((item) => item.helicopter_file_id === event.helicopter_file_id)) {
+    return current
+  }
+
+  const nextItem = {
+    helicopter_file_id: event.helicopter_file_id,
+    section: event.section,
+    position: event.position,
+    is_mandatory: event.is_mandatory,
+    attachment_pending: event.attachment_pending,
+    attachment: {
+      id: event.file_id,
+      file_name: event.name,
+      download_url: "",
+    },
+    created_at: event.updated_at,
+    updated_at: event.updated_at,
+  }
+
+  return [...current, nextItem].sort((a, b) => a.position - b.position)
+})
+```
+
+Catatan:
+
+1. saat event baru datang, `attachment_pending` bisa masih `true`
+2. artinya child row sudah ada, tetapi attachment final mungkin belum ter-resolve penuh
+3. kalau FE butuh shape yang benar-benar final, aman juga untuk re-fetch sekali ke:
+   `GET /api/v1/helicopter-files/get/{helicopter_id}`
+
+### Step 5 - Refresh token saat TTL hampir habis
+
+Token WOPI bersifat short-lived.
+
+Saat token mendekati habis, frontend harus:
+
+1. memanggil ulang `GET /api/v1/file-manager/files/{fileId}/edit-session` untuk file yang sudah ada
+
+Lalu replace token yang dipakai untuk membuka editor.
+
+Catatan:
+
+1. setelah file pertama sukses dibuat, jangan panggil `create-from-template` lagi hanya untuk refresh token
+2. untuk reopen atau refresh editor, gunakan `edit-session`
+3. `create-from-template` dipakai untuk bootstrap file baru atau reuse by `template + takeover`
+
+## Flow Edit File Existing
+
+### Step 1 - Frontend minta edit session
+
+Frontend hanya mengirim `fileId`.
+
+Backend akan:
+
+1. load file node
+2. cari takeover asal file
+3. verifikasi user punya akses ke takeover
+4. mint access token baru
+5. balikin Collabora action URL
+
+### Step 2 - Frontend buka editor
+
+Frontend membuka editor pakai response yang sama seperti flow create-from-template.
+
+## Lifecycle Yang Perlu Dipahami Frontend
+
+### Saat editor dibuka
+
+Backend sudah membuat record file node.
+
+Artinya:
+
+1. tidak ada lagi langkah create file saat save
+2. Collabora tinggal overwrite file yang sama
+3. `fileId` tetap sama selama sesi itu
+
+### Saat user mengetik
+
+Collabora akan autosave ke backend melalui WOPI.
+
+Frontend tidak perlu memanggil endpoint save sendiri.
+
+### Saat user menutup editor
+
+Jika Collabora mengirim exit-save:
+
+1. backend menandai file `final`
+2. backend attach relasi takeover bila perlu saat create takeover menerima `edited_template_file_ids`
+3. frontend cukup refresh data list / detail
+4. child `fpwb` tetap berada di helicopter files karena row bisnisnya sudah dibuat sejak create-from-template
+
+### Jika user menutup tanpa perubahan
+
+File tetap berada di status draft dan bisa dibersihkan oleh job cleanup jika stale.
+
+## Permission Model
+
+### App API
+
+App API tetap memakai session auth normal.
+
+Frontend harus sudah login sebelum memanggil:
+
+1. `POST /api/v1/file-manager/files/create-from-template`
+2. `GET /api/v1/file-manager/files/{fileId}/edit-session`
+
+### WOPI API
+
+WOPI API memakai:
+
+1. `access_token`
+2. proof key validation
+3. permission claim `read` atau `write`
+
+Frontend tidak perlu menambahkan permission manual ke WOPI request. Itu sudah ditangani backend saat mint token.
+
+## Error Handling Singkat
+
+Semua error App API mengikuti envelope `apperrorsx` yang sudah dipakai backend:
+
+1. `status`
+2. `code`
+3. `error_code`
+4. `title`
+5. `message`
+
+Untuk frontend, patokan utamanya adalah `code` dan `error_code`, bukan hanya HTTP status.
+
+Mapping singkat yang dipakai di flow ini:
+
+1. `403` App API: `FORBIDDEN_ACCESS` / `USER_UNAUTHORIZED` saat user tidak boleh akses takeover atau file.
+2. `401/403` WOPI: `FILE_MANAGER_WOPI_INVALID_TOKEN`, `FILE_MANAGER_WOPI_INVALID_PROOF`, atau `FILE_MANAGER_WOPI_PERMISSION_DENIED`.
+3. `409` save WOPI: `FILE_MANAGER_WOPI_LOCK_CONFLICT` atau `FILE_MANAGER_WOPI_STALE_TIMESTAMP`.
+4. `422` input invalid: `VALIDATION_ERROR` atau `FILE_MANAGER_WOPI_VALIDATION_FAILED`.
+5. `404` file/takeover missing: `DATA_NOT_FOUND`, `FILE_MANAGER_FILE_NOT_FOUND`, atau `FILE_MANAGER_WOPI_FILE_NOT_FOUND`.
+
+Catatan:
+
+1. WOPI save conflict kadang tetap mengembalikan body protokol khusus seperti `COOLStatusCode: 1010`.
+2. Untuk WOPI, frontend tetap tidak memanggil endpoint tersebut langsung; yang perlu di-handle adalah response dari backend saat membuka editor.
+
+## Hal Yang Harus Dihindari
+
+1. Jangan panggil `/wopi/...` langsung dari frontend.
+2. Jangan kirim credential S3 ke browser.
+3. Jangan hardcode file path di frontend.
+4. Jangan anggap token WOPI berlaku lama.
+5. Jangan reuse token file A untuk file B.
+6. Jangan pakai `create-from-template` berulang-ulang hanya untuk refresh editor file yang sama.
diff --git a/docs/file-manager-delete-store.md b/docs/file-manager-delete-store.md
new file mode 100644
index 0000000..295ce25
--- /dev/null
+++ b/docs/file-manager-delete-store.md
@@ -0,0 +1,241 @@
+# File Manager
+
+# Delete, Restore, Purge 
+
+## Ringkasan Endpoint Utama
+
+1. `DELETE /api/v1/file-manager/delete` untuk soft delete bulk (file/folder)
+2. `PATCH /api/v1/file-manager/restore` untuk restore bulk (file/folder) ke lokasi asal
+3. `DELETE /api/v1/file-manager/purge-delete` untuk hard delete bulk (file/folder)
+4. `GET /api/v1/file-manager/trash/get-all` untuk list trash merged
+
+## Catatan Kontrak
+
+1. Tidak ada endpoint delete single.
+2. Tidak ada endpoint restore single.
+3. Gunakan endpoint bulk untuk delete/restore/purge.
+
+## Step 1 - Soft Delete Node (Bulk)
+
+### Endpoint
+- `DELETE /api/v1/file-manager/delete`
+
+### Tujuan
+- soft delete file/folder (masuk trash)
+- jika folder di-delete, subtree (child folder + child file) ikut ke-trash
+
+### Contoh request
+
+```json
+{
+  "data": [
+    { "uuid": "folder-uuid" },
+    { "uuid": "file-uuid" }
+  ]
+}
+```
+
+### Contoh response
+
+```json
+{
+  "data": [
+    {
+      "index": 0,
+      "success": true,
+      "resource": {
+        "type": "file_manager_delete_result",
+        "id": "folder-uuid",
+        "attributes": {
+          "node_type": "folder",
+          "status": "trashed"
+        }
+      }
+    },
+    {
+      "index": 1,
+      "success": true,
+      "resource": {
+        "type": "file_manager_delete_result",
+        "id": "file-uuid",
+        "attributes": {
+          "node_type": "file",
+          "status": "trashed"
+        }
+      }
+    }
+  ],
+  "meta": {
+    "total": 2,
+    "success": 2,
+    "failed": 0,
+    "partial_success": false
+  }
+}
+```
+
+## Step 3 - Lihat Trash
+
+### Endpoint
+- `GET /api/v1/file-manager/trash/get-all`
+
+### Tujuan
+- menampilkan data trash merged (folder + file)
+
+### Contoh response
+
+```json
+{
+  "data": [
+    {
+      "type": "file_manager_trash_node",
+      "id": "folder-uuid",
+      "attributes": {
+        "node_type": "folder",
+        "name": "Documents",
+        "path_cache": "/Documents",
+        "trashed_at": "2026-04-01T10:00:00Z"
+      }
+    },
+    {
+      "type": "file_manager_trash_node",
+      "id": "file-uuid",
+      "attributes": {
+        "node_type": "file",
+        "name": "LOGO.png",
+        "extension": "png",
+        "size_bytes": 100988,
+        "mime_type": "image/png",
+        "trashed_at": "2026-04-01T10:00:00Z"
+      }
+    }
+  ],
+  "meta": {
+    "page_number": 1,
+    "page_size": 20,
+    "folders": 1,
+    "files": 1,
+    "total": 2
+  }
+}
+```
+
+## Step 4 - Restore Node (Bulk, kembali ke lokasi asal)
+
+### Endpoint
+- `PATCH /api/v1/file-manager/restore`
+
+### Contoh request
+
+```json
+{
+  "data": [{ "uuid": "folder-uuid" }, { "uuid": "file-uuid" }]
+}
+```
+
+Aturan:
+- restore tidak menerima `destination_folder_uuid` lagi
+- node akan kembali ke lokasi asal (parent/folder saat sebelum di-trash)
+- jika lokasi asal root, field `location` tidak dimunculkan
+
+### Contoh response
+
+```json
+{
+  "data": [
+    {
+      "index": 0,
+      "success": true,
+      "resource": {
+        "type": "file_manager_restore_result",
+        "id": "folder-uuid",
+        "attributes": {
+          "node_type": "folder",
+          "status": "ready"
+        }
+      }
+    },
+    {
+      "index": 1,
+      "success": true,
+      "resource": {
+        "type": "file_manager_restore_result",
+        "id": "file-uuid",
+        "attributes": {
+          "node_type": "file",
+          "status": "ready",
+          "location": {
+            "folder_id": "folder-uuid-optional"
+          }
+        }
+      }
+    }
+  ],
+  "meta": {
+    "total": 2,
+    "success": 2,
+    "failed": 0,
+    "partial_success": false
+  }
+}
+```
+
+## Step 5 - Purge Node (Hard Delete)
+
+### Endpoint
+- `DELETE /api/v1/file-manager/purge-delete` (bulk)
+
+### Tujuan
+- hapus permanen file atau folder (UUID bisa keduanya)
+- kalau UUID folder: subtree ikut dihapus permanen
+- kalau UUID file: file dihapus permanen
+
+### Contoh request bulk
+
+```json
+{
+  "data": [
+    { "uuid": "folder-uuid" },
+    { "uuid": "file-uuid" }
+  ]
+}
+```
+
+### Contoh response
+
+```json
+{
+  "data": [
+    {
+      "index": 0,
+      "success": true,
+      "resource": {
+        "type": "file_manager_purge_result",
+        "id": "folder-uuid",
+        "attributes": {
+          "node_type": "folder",
+          "status": "purged"
+        }
+      }
+    },
+    {
+      "index": 1,
+      "success": true,
+      "resource": {
+        "type": "file_manager_purge_result",
+        "id": "file-uuid",
+        "attributes": {
+          "node_type": "file",
+          "status": "purged"
+        }
+      }
+    }
+  ],
+  "meta": {
+    "total": 2,
+    "success": 2,
+    "failed": 0,
+    "partial_success": false
+  }
+}
+```
diff --git a/docs/file-manager-get.md b/docs/file-manager-get.md
new file mode 100644
index 0000000..f2df17b
--- /dev/null
+++ b/docs/file-manager-get.md
@@ -0,0 +1,230 @@
+# File Manager - GET Data (Step by Step)
+
+# Daftar Endpoint
+## Ringkasan Endpoint Utama
+1. `GET /file-manager/get-all` untuk explorer merged (root/child)
+2. `GET /file-manager/trash/get-all` untuk trash merged
+3. `GET /file-manager/files/get/:uuid` untuk detail file
+4. `GET /file-manager/folders/get/:uuid` untuk detail folder
+
+## Endpoint Removed (tidak tersedia lagi)
+1. `GET /file-manager/files/get-all`
+2. `GET /file-manager/folders/get-all`
+3. `GET /file-manager/files/get-all-trash`
+4. `GET /file-manager/folders/get-all-trash`
+
+## Step 1 - Ambil Explorer Root
+
+### Endpoint
+- `GET /api/v1/file-manager/get-all`
+
+### Tujuan
+- menampilkan isi root explorer (merged folder + file).
+
+### Contoh response
+
+```json
+{
+  "data": [
+    {
+      "type": "file_manager_node",
+      "id": "folder-uuid",
+      "attributes": {
+        "node_type": "folder",
+        "name": "Documents",
+        "status": "ready",
+        "path_cache": "/Documents",
+        "created_at": "2026-03-31T08:52:03Z",
+        "updated_at": "2026-03-31T08:52:03Z"
+      }
+    },
+    {
+      "type": "file_manager_node",
+      "id": "file-uuid",
+      "attributes": {
+        "node_type": "file",
+        "name": "LOGO.png",
+        "extension": "png",
+        "size_bytes": 100988,
+        "mime_type": "image/png",
+        "download_url": "https://...",
+        "status": "ready",
+        "created_at": "2026-03-31T09:30:31Z",
+        "updated_at": "2026-03-31T09:30:31Z"
+      }
+    }
+  ],
+  "meta": {
+    "is_root": true,
+    "folders": 1,
+    "files": 1,
+    "total": 2
+  }
+}
+```
+
+## Step 2 - Buka Isi Folder
+
+### Endpoint
+- `GET /api/v1/file-manager/get-all?parent_uuid=<folder_uuid>`
+
+### Tujuan
+- menampilkan child langsung dari folder yang dipilih.
+
+
+### Contoh response
+
+```json
+{
+  "data": [
+    {
+      "type": "file_manager_node",
+      "id": "inside-file-uuid",
+      "attributes": {
+        "node_type": "file",
+        "parent_id": "folder-uuid",
+        "name": "inside-folder.png",
+        "extension": "png",
+        "size_bytes": 42170,
+        "mime_type": "image/png",
+        "download_url": "https://...",
+        "status": "ready",
+        "created_at": "2026-04-05T07:29:33Z",
+        "updated_at": "2026-04-05T07:33:44Z"
+      }
+    }
+  ],
+  "meta": {
+    "is_root": false,
+    "parent_uuid": "folder-uuid",
+    "breadcrumb": [
+      {
+        "id": "folder-uuid-level-1",
+        "name": "Documents"
+      },
+      {
+        "id": "folder-uuid",
+        "name": "Project A"
+      }
+    ],
+    "folders": 0,
+    "files": 1,
+    "total": 1
+  }
+}
+```
+
+## Step 2b - Ambil Data Trash (Merged)
+
+### Endpoint
+- `GET /api/v1/file-manager/trash/get-all`
+
+### Tujuan
+- menampilkan daftar node yang sedang trashed (folder + file).
+
+### Contoh response
+
+```json
+{
+  "data": [
+    {
+      "type": "file_manager_trash_node",
+      "id": "folder-uuid",
+      "attributes": {
+        "node_type": "folder",
+        "name": "Documents",
+        "path_cache": "/Documents",
+        "trashed_at": "2026-04-01T10:00:00Z"
+      }
+    },
+    {
+      "type": "file_manager_trash_node",
+      "id": "file-uuid",
+      "attributes": {
+        "node_type": "file",
+        "name": "logo.png",
+        "extension": "png",
+        "size_bytes": 42170,
+        "mime_type": "image/png",
+        "download_url": "https://...",
+        "trashed_at": "2026-04-01T10:00:00Z"
+      }
+    }
+  ],
+  "meta": {
+    "total": 2
+  }
+}
+```
+
+## Step 3 - Ambil Detail File
+
+### Endpoint
+- `GET /api/v1/file-manager/files/get/:uuid`
+
+### Tujuan
+- ambil detail information dari satu file untuk panel/detail page.
+
+### Contoh response
+
+```json
+{
+  "data": {
+    "type": "file_manager_file",
+    "id": "file-uuid",
+    "attributes": {
+      "name": "spidey.png",
+      "name_normalized": "spidey.png",
+      "extension": "png",
+      "size_bytes": 42170,
+      "mime_type": "image/png",
+      "download_url": "https://...",
+      "status": "ready",
+      "location": {
+        "folder_id": "folder-uuid"
+      },
+      "processing": {
+        "processing_started_at": "2026-04-05T07:29:34Z",
+        "processed_at": "2026-04-05T07:29:34Z",
+        "validated_at": "2026-04-05T07:29:34Z"
+      },
+      "audit": {
+        "created_at": "2026-04-05T07:29:33Z",
+        "created_by": "019d194e-f595-7d5f-a5bf-3609231ba43d",
+        "updated_at": "2026-04-05T07:33:44Z",
+        "updated_by": "019d194e-f595-7d5f-a5bf-3609231ba43d"
+      }
+    }
+  }
+}
+```
+
+## Step 4 - Ambil Detail Folder
+
+### Endpoint
+- `GET /api/v1/file-manager/folders/get/:uuid`
+
+### Tujuan
+- ambil detail satu folder (mis. untuk panel detail folder/breadcrumb context).
+
+### Contoh response
+
+```json
+{
+  "data": {
+    "type": "file_manager_folder",
+    "id": "folder-uuid",
+    "attributes": {
+      "name": "Documents",
+      "name_normalized": "documents",
+      "path_cache": "/Documents",
+      "audit": {
+        "created_at": "2026-03-31T08:52:03Z",
+        "created_by": "019d194e-f595-7d5f-a5bf-3609231ba43d",
+        "updated_at": "2026-03-31T08:52:03Z",
+        "updated_by": "019d194e-f595-7d5f-a5bf-3609231ba43d"
+      }
+    }
+  }
+}
+```
diff --git a/docs/file-manager-preview.md b/docs/file-manager-preview.md
new file mode 100644
index 0000000..d2021cc
--- /dev/null
+++ b/docs/file-manager-preview.md
@@ -0,0 +1,207 @@
+# File Manager — Document Preview
+
+Fitur ini memungkinkan FE untuk menampilkan preview dokumen (PDF, DOCX, XLSX, PPTX) secara inline tanpa user perlu mendownload file terlebih dahulu.
+
+---
+
+## Cara Kerja
+
+### Untuk File PDF
+
+PDF langsung dapat dirender oleh browser. Backend mengembalikan `preview_url` yang menunjuk ke file aslinya (sama dengan `download_url`). Tidak ada proses konversi.
+
+### Untuk File Office (DOCX, XLSX, PPTX, DOC, XLS, PPT)
+
+Dokumen dikonversi ke PDF secara otomatis oleh background worker saat file selesai diupload. Proses ini menggunakan **Gotenberg** (container yang menjalankan LibreOffice secara headless). Hasil konversi disimpan di S3 sebagai file terpisah (`.preview.pdf`).
+
+### Untuk File Lainnya (Image, Video, dll)
+
+`preview_url` tidak diisi (kosong). FE menangani preview image menggunakan `download_url` seperti sebelumnya.
+
+---
+
+## Flow Lengkap
+
+```
+1. FE upload file (existing flow — tidak berubah)
+
+2. Background worker memproses file:
+   - Image  → generate thumbnail (existing)
+   - PDF    → tidak perlu konversi, preview_url = original URL
+   - Office → konversi ke PDF via Gotenberg → simpan preview di S3 → update DB
+
+3. File status menjadi "ready"
+
+4. FE ambil detail file:
+   GET /api/v1/file-manager/files/get/{uuid}
+   → response berisi preview_url
+
+5. FE render preview_url di iframe/tab baru
+```
+
+---
+
+## Endpoint
+
+### GET /api/v1/file-manager/files/get/{uuid}
+
+Endpoint existing. Response sekarang memiliki field tambahan `preview_url` di dalam `attributes`.
+
+#### Contoh Response (PDF atau Office doc yang sudah diproses)
+
+```json
+{
+  "data": {
+    "type": "file_manager_file",
+    "id": "019d8215-c622-7576-86bd-3ddeecaf4867",
+    "attributes": {
+      "name": "laporan.docx",
+      "extension": "docx",
+      "size_bytes": 204800,
+      "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "status": "ready",
+      "download_url": "https://s3.../laporan.docx?X-Amz-Signature=...",
+      "preview_url": "https://s3.../laporan.preview.pdf?X-Amz-Signature=...",
+      "audit": {
+        "created_at": "2026-07-06T10:00:00Z",
+        "updated_at": "2026-07-06T10:00:05Z"
+      }
+    }
+  }
+}
+```
+
+#### Contoh Response (file masih diproses atau konversi gagal)
+
+```json
+{
+  "data": {
+    "type": "file_manager_file",
+    "id": "019d8215-c622-7576-86bd-3ddeecaf4867",
+    "attributes": {
+      "name": "laporan.docx",
+      "status": "processing",
+      "download_url": "https://s3.../laporan.docx?X-Amz-Signature=...",
+      "preview_url": ""
+    }
+  }
+}
+```
+
+---
+
+## Logika `preview_url` di Backend
+
+| Kondisi | `preview_url` |
+|---------|--------------|
+| File PDF | Sama dengan `download_url` |
+| File Office, sudah dikonversi | Presigned URL ke `.preview.pdf` di S3 |
+| File Office, belum/gagal dikonversi | Kosong (`""`) |
+| File image / tipe lainnya | Kosong (`""`) |
+
+---
+
+## Error Handling
+
+Jika konversi via Gotenberg gagal:
+
+- **Error 4xx dari Gotenberg** (dokumen tidak valid/tidak didukung): file status menjadi `failed`. FE harus handle kondisi ini dengan menampilkan pesan error atau fallback ke tombol download.
+- **Error jaringan atau 5xx dari Gotenberg** (Gotenberg sedang down): worker akan retry otomatis. File status tetap `processing` sampai berhasil atau melebihi batas retry.
+
+---
+
+## Panduan untuk FE
+
+```js
+const file = await api.getFile(uuid)
+const { preview_url, download_url, status, mime_type } = file.data.attributes
+
+if (preview_url) {
+  // Render preview di iframe
+  openPreviewModal(preview_url)
+} else if (status === 'processing') {
+  // Tampilkan loading / tunggu SSE event
+  showProcessingIndicator()
+} else if (status === 'failed') {
+  // Tampilkan error, tawarkan download langsung
+  showError('Preview tidak tersedia')
+  offerDownload(download_url)
+} else {
+  // File type tidak didukung preview (video, archive, dll)
+  offerDownload(download_url)
+}
+```
+
+---
+
+## Cara Test di Local (Tanpa Frontend)
+
+### Prasyarat
+
+1. Gotenberg harus jalan:
+   ```bash
+   docker-compose up gotenberg
+   ```
+
+2. File worker harus jalan:
+   ```bash
+   docker-compose up file-worker
+   ```
+
+3. Pastikan `.env.local` sudah ada `GOTENBERG_URL=http://localhost:3000`
+
+### Langkah Test
+
+```bash
+# 1. Upload file DOCX (step upload + create seperti biasa)
+
+# 2. Tunggu file status menjadi "ready" (cek via SSE atau polling GET)
+
+# 3. Ambil detail file
+curl -H "Authorization: Bearer <token>" \
+  http://localhost:8080/api/v1/file-manager/files/get/<uuid>
+
+# 4. Salin nilai preview_url dari response
+
+# 5. Buka preview_url di browser — PDF harus tampil
+```
+
+---
+
+## Konfigurasi
+
+### docker-compose.yml
+
+```yaml
+gotenberg:
+  image: gotenberg/gotenberg:8
+  ports:
+    - "3000:3000"
+  restart: unless-stopped
+```
+
+### .env.local
+
+```bash
+GOTENBERG_URL=http://localhost:3000        # local development
+# GOTENBERG_URL=http://gotenberg:3000      # dalam docker-compose network
+```
+
+---
+
+## File yang Diubah (OP-1273)
+
+| File | Perubahan |
+|------|-----------|
+| `migrations/20260706_file_preview_metadata.sql` | ALTER TABLE tambah kolom `preview_*` |
+| `docker-compose.yml` | Tambah service Gotenberg |
+| `.env.local.example` | Tambah `GOTENBERG_URL` |
+| `config/local/config.json` | Tambah section `gotenberg.url` |
+| `internal/config/config.go` | Tambah struct `GotenbergConfig` |
+| `internal/config/loader.go` | Mapping config Gotenberg |
+| `internal/domain/file_manager/model_file.go` | Tambah field `Preview*` di struct `File` |
+| `internal/service/file_processing_usecase.go` | Tambah fungsi `convertDocumentIfNeeded`, `callGotenberg`, helper |
+| `cmd/worker/file_worker.go` | Wire up `GotenbergURL` ke use case |
+| `internal/transport/http/dto/shared/file_manager_file_shared.go` | Tambah field `PreviewURL` di `FileManagerFileDetailAttributes` |
+| `internal/transport/http/handlers/file_manager_request_helpers.go` | Tambah `PreviewURL` ke `fileManagerDownloadURLs` dan logic presign |
+| `internal/transport/http/handlers/file_manager_file_handler.go` | Update `fileManagerFileDetailResource` untuk set `PreviewURL` |
diff --git a/docs/file-manager-update-move.md b/docs/file-manager-update-move.md
new file mode 100644
index 0000000..652c5b3
--- /dev/null
+++ b/docs/file-manager-update-move.md
@@ -0,0 +1,80 @@
+# File Manager
+
+# Update dan Move (Step by Step)
+
+## A. Update File
+
+### Endpoint
+- `PATCH /api/v1/file-manager/files/update/:uuid`
+
+### FE kirim request ini
+
+```json
+{
+  "data": {
+    "type": "file_manager_file_update",
+    "id": "file-uuid",
+    "attributes": {
+      "name": "spidey-v2.png",
+      "folder_id": "folder-uuid-optional"
+    }
+  }
+}
+```
+
+Aturan:
+- `data.id` harus sama dengan `:uuid` di path
+- minimal isi salah satu: `name` atau `folder_id`
+- `folder_id` null/kosong bisa dipakai untuk pindah ke root
+
+## B. Update Folder
+
+### Endpoint
+- `PATCH /api/v1/file-manager/folders/update/:uuid`
+
+### FE kirim request ini
+
+```json
+{
+  "data": {
+    "type": "file_manager_folder_update",
+    "id": "folder-uuid",
+    "attributes": {
+      "name": "Manuals Updated",
+      "parent_id": "parent-folder-uuid-optional"
+    }
+  }
+}
+```
+
+Aturan:
+- `data.id` harus sama dengan `:uuid`
+- minimal isi salah satu: `name` atau `parent_id`
+
+## C. Move Node (File/Folder) - Bulk
+
+### Endpoint
+- `PATCH /api/v1/file-manager/move`
+
+### FE kirim request ini
+
+```json
+{
+  "data": [
+    {
+      "uuid": "node-uuid-file-atau-folder",
+      "destination_folder_uuid": "folder-uuid-optional"
+    }
+  ]
+}
+```
+
+Aturan:
+- `destination_folder_uuid` null/kosong = pindah ke root
+- `uuid` bisa folder UUID atau file UUID
+- bisa kirim banyak item sekaligus (bulk)
+
+## Ringkasan
+1. `PATCH /files/update/:uuid` untuk rename/move umum file
+2. `PATCH /folders/update/:uuid` untuk rename/move umum folder
+3. `PATCH /file-manager/move` untuk move-only file/folder (bulk, boleh 1 item)
diff --git a/docs/file-manager-upload.md b/docs/file-manager-upload.md
new file mode 100644
index 0000000..113d29d
--- /dev/null
+++ b/docs/file-manager-upload.md
@@ -0,0 +1,288 @@
+# File Manager
+
+# Uploading New File
+Sebelum hit API, FE ambil data per file:
+- `name` (contoh: `spidey.png`)
+- `content_type` (contoh: `image/png`)
+- `size_bytes` (contoh: `42170`)
+
+## Step 1 - FE minta upload intent ke BE, lalu upload langsung ke storage
+
+## A. Minta Upload Intent ke Backend
+
+### Endpoint
+- `POST /api/v1/file-manager/files/upload`
+
+### FE kirim request ini
+- Single File
+
+```json
+{
+  "data": [
+    {
+      "type": "file_manager_file_upload_intent",
+      "attributes": {
+        "name": "image.png",
+        "content_type": "image/png",
+        "size_bytes": 123
+      }
+    }
+  ]
+}
+```
+
+- Bulk File
+
+```json
+{
+  "data": [
+    {
+      "type": "file_manager_file_upload_intent",
+      "attributes": {
+        "name": "image1.png",
+        "content_type": "image/png",
+        "size_bytes": 123
+      }
+    },
+    {
+      "type": "file_manager_file_upload_intent",
+      "attributes": {
+        "name": "image2.png",
+        "content_type": "image/png",
+        "size_bytes": 456
+      }
+    }
+  ]
+}
+```
+
+### Backend akan balas per file
+- `upload_intent_uuid`
+- `upload_url`
+- `method` (`PUT`)
+- `required_headers` 
+- `object.bucket`
+- `object.key`
+- `expires_at`
+- `expires_in_seconds`
+
+Contoh response:
+
+```json
+{
+  "data": [
+    {
+      "index": 0,
+      "success": true,
+      "resource": {
+        "type": "file_manager_file_upload_intent",
+        "id": "019d8215-c622-7576-86bd-3ddeecaf4867",
+        "attributes": {
+          "upload_intent_uuid": "019d8215-c622-7576-86bd-3ddeecaf4867",
+          "upload_url": "http://localhost:4566/...",
+          "method": "PUT",
+          "required_headers": {
+            "content-type": "image/png"
+          },
+          "object": {
+            "bucket": "wucher-file-dev",
+            "key": "fm/objects/files/2026/04/12/019d8215c6227a1aa20fc21f99f36584.png"
+          },
+          "file": {
+            "name": "spidey.png",
+            "mime_type": "image/png",
+            "size_bytes": 42170
+          },
+          "expires_at": "2026-04-12T14:40:58Z",
+          "expires_in_seconds": 899
+        }
+      }
+    }
+  ],
+  "meta": {
+    "total": 1,
+    "success": 1,
+    "failed": 0,
+    "partial_success": false
+  }
+}
+```
+
+## B. FE Handle langsung Upload Binary Langsung ke S3
+
+Untuk setiap item `success: true` dari step 1:
+1. Ambil `upload_url`
+2. Ambil `method`
+3. Ambil `required_headers` (jika ada)
+4. Lakukan request upload file ke S3
+
+Contoh yang akan dilakukan FE:
+
+```js
+  await fetch(upload_url, {
+    method: method, // "PUT"
+    headers: { "Content-Type": file.type },
+    body: file,
+  });
+```
+
+atau pseudo
+```js
+  const intents = await api.requestUploadIntents(files) // bulk
+  const readyToUpload = intents.data.filter(i => i.success)
+
+  const uploadResults = await parallelLimit(readyToUpload, 4, putToS3) // paralel
+  const succeeded = uploadResults.filter(r => r.success)
+
+  if (succeeded.length > 0) {
+    await api.createFilesBulk(succeeded.map(toCreatePayload))
+  }
+```
+
+
+Catatan penting:
+- **1 file = 1 PUT ke S3**
+- boleh paralel (disarankan pakai concurrency limit)
+- file yang gagal PUT **jangan** dikirim ke step create
+
+
+## Step 2 - Upload Cancel (opsional)
+
+### Endpoint 
+- `DELETE /api/v1/file-manager/files/cancel-upload`
+
+### FE kirim request ini
+
+```json
+{
+  "data": [
+    {
+      "type": "file_manager_file_cancel_upload",
+      "attributes": {
+        "upload_intent_uuid": "019d8215-c622-7576-86bd-3ddeecaf4867"
+      }
+    }
+  ]
+}
+```
+
+### Kapan dipakai
+- user sudah request upload intent
+- tapi user batal sebelum create
+- FE bisa cancel upload intent supaya flow lebih bersih
+
+### Contoh response
+
+```json
+{
+  "data": [
+    {
+      "index": 0,
+      "success": true,
+      "resource": {
+        "type": "file_manager_file_cancel_upload_result",
+        "id": "019d8215-c622-7576-86bd-3ddeecaf4867",
+        "attributes": {
+          "status": "canceled"
+        }
+      }
+    }
+  ],
+  "meta": {
+    "total": 1,
+    "success": 1,
+    "failed": 0,
+    "partial_success": false
+  }
+}
+```
+
+## Step 3 - FE Panggil Create ke Backend (Finalisasi)
+
+Setelah PUT S3 sukses, FE gunakan:
+
+### Endpoint
+
+- `POST /api/v1/file-manager/files/create`
+
+### FE kirim request ini
+
+```json
+{
+  "data": [
+    {
+      "type": "file_manager_file_create",
+      "attributes": {
+        "upload_intent_uuid": "019d8215-c622-7576-86bd-3ddeecaf4867",
+        "name": "spidey.png",
+        "folder_id": null
+      }
+    }
+  ]
+}
+```
+
+Aturan:
+
+- `upload_intent_uuid`: wajib
+- `name`: wajib
+- `folder_id`: opsional (kalau mau dimasukkan ke folder)
+- `null` atau tidak dikirim = root
+
+## Step 4 - Process Create (BE)
+
+Untuk setiap item:
+1. Ambil upload intent dari `upload_intent_uuid`
+2. Verify object benar-benar ada di storage
+3. Verify metadata object (size/content type) sesuai intent
+4. Simpan metadata file ke DB
+5. Simpan outbox durable
+6. Set status awal file menjadi `uploaded`
+
+## Step 5 - Proses Async Lanjutan (Backend)
+
+Setelah status `uploaded`, worker akan lanjut:
+
+- `uploaded -> processing -> validated -> ready`
+- atau `uploaded -> processing -> failed`
+
+## Step 6 - FE Handle Response Create
+
+Response create adalah bulk per item.
+
+- Kalau semua sukses: HTTP `201`
+- Kalau campuran sukses + gagal: HTTP `207` dengan `partial_success: true`
+
+Contoh sukses:
+
+```json
+{
+  "data": [
+    {
+      "index": 0,
+      "success": true,
+      "message": "created",
+      "resource": {
+        "type": "file_manager_file",
+        "id": "019d628a-8d92-7949-b355-95de506da3b7",
+        "attributes": {
+          "folder_id": "019d4309-4dc8-78be-bb0c-3ebb8f3056ba",
+          "name": "spidey01.png",
+          "extension": "png",
+          "size_bytes": 42170,
+          "mime_type": "image/png",
+          "status": "uploaded",
+          "created_at": "2026-04-06T11:25:40Z",
+          "updated_at": "2026-04-06T11:25:40Z"
+        }
+      }
+    }
+  ],
+  "meta": {
+    "total": 1,
+    "success": 1,
+    "failed": 0,
+    "partial_success": false
+  }
+}
+```
diff --git a/docs/flight-ops-locks-and-usage-sync.md b/docs/flight-ops-locks-and-usage-sync.md
new file mode 100644
index 0000000..df1ae87
--- /dev/null
+++ b/docs/flight-ops-locks-and-usage-sync.md
@@ -0,0 +1,260 @@
+# Flight Ops Locks and Helicopter Usage Sync
+
+Dokumen ini menjelaskan alur data untuk `takeover`, `mission`, `flight_data`, `after_flight_inspection`, `fm_report`, dan `helicopter_usage`.
+
+Tujuan utamanya:
+- mencegah perubahan data pada fase yang sudah final
+- menjaga `helicopter_usage` sebagai ringkasan yang dihitung dari data sumber
+- membuat perilaku backend konsisten untuk frontend dan integrasi lain
+
+## Ringkasan Aturan
+
+1. Saat `after_flight_inspection` sudah dibuat:
+   - `mission` untuk flight itu tidak boleh dibuat atau di-update lagi
+   - `flight_data` baru tidak boleh dibuat lagi
+   - `flight_data` yang sudah ada masih boleh diedit
+2. Saat `fm_report` di-complete:
+   - `flight_data` untuk flight itu terkunci
+   - `fm_report` menjadi read-only
+   - `helicopter_usage` baru dihitung ulang dari data sumber
+3. Saat `GET /api/v1/fm-reports/get/:flight_id`:
+   - backend tetap mengirim `helicopter_usage`
+   - jika row belum ada di database, response tetap mengirim nilai `0`
+
+## Alur Besar
+
+Urutan normalnya:
+
+1. `takeover` dibuat
+2. `mission` dibuat
+3. `flight_data` diisi dan masih bisa diubah
+4. `after_flight_inspection` dibuat
+5. `fm_report` draft otomatis tersedia
+6. user melengkapi `fm_report`
+7. `POST /api/v1/fm-reports/complete/:flight_id`
+8. backend menghitung ulang `helicopter_usage`
+
+## Detail Per Modul
+
+### 1) Mission
+
+Mission bisa dibuat dan di-update selama flight belum masuk fase after flight inspection.
+
+Begitu `after_flight_inspection` sudah ada untuk flight tersebut:
+- create mission ditolak
+- update mission ditolak
+
+Alasan bisnis:
+- setelah after flight masuk, mission dianggap sudah masuk fase final
+- mission tidak boleh berubah karena akan mempengaruhi rekonsiliasi data flight
+
+Error yang biasanya muncul:
+- `MISSION_AFTER_FLIGHT_LOCKED`
+
+Referensi:
+- lihat tabel `Mission` di [`docs/error-catalog.md`](./error-catalog.md)
+
+### 2) Flight Data
+
+`flight_data` adalah sumber utama untuk hitungan operasional seperti:
+- landing count
+- durasi flight
+- hook release
+- rotor brake cycle
+
+#### Sebelum after flight inspection
+
+- create flight data boleh
+- update flight data boleh
+- delete flight data boleh
+
+#### Setelah after flight inspection dibuat
+
+- create flight data baru ditolak
+- update flight data yang sudah ada masih boleh
+- delete flight data yang sudah ada ditolak
+
+#### Setelah FM report di-complete
+
+- update flight data ditolak
+- delete flight data ditolak
+- data dianggap final
+
+Error yang biasanya muncul:
+- `FLIGHT_DATA_CREATE_BLOCKED`
+- `FLIGHT_DATA_AFTER_FLIGHT_LOCKED`
+- `FLIGHT_DATA_LOCKED`
+
+Referensi:
+- lihat tabel `Flight Data` di [`docs/error-catalog.md`](./error-catalog.md)
+
+### 3) After Flight Inspection
+
+`after_flight_inspection` dipakai sebagai penanda bahwa flight sudah masuk fase akhir sebelum FM report di-complete.
+
+Catatan penting:
+- create / upsert after flight inspection tidak lagi memicu kalkulasi `helicopter_usage`
+- after flight inspection hanya menyimpan hasil inspeksi
+- kalkulasi usage dipindahkan ke langkah `fm_report complete`
+
+### 4) FM Report
+
+FM report dibuat sebagai draft setelah after flight inspection masuk ke flow.
+
+#### Sebelum complete
+
+- report masih bisa di-update
+- engine metric masih bisa diisi / diubah
+- `helicopter_usage` belum dihitung ulang oleh backend
+
+#### Setelah complete
+
+- report menjadi read-only
+- update FM report ditolak
+- `completed_at` dan `completed_by` disimpan
+- backend memicu refresh `helicopter_usage`
+
+Endpoint yang dipakai:
+- `POST /api/v1/fm-reports/complete/:flight_id`
+
+Error yang biasanya muncul:
+- `FM_REPORT_LOCKED`
+- `FM_REPORT_COMPLETE_FAILED`
+
+Referensi:
+- lihat tabel `FM Report` di [`docs/error-catalog.md`](./error-catalog.md)
+
+### 5) Helicopter Usage
+
+`helicopter_usage` sekarang diperlakukan sebagai summary record.
+
+Karakteristiknya:
+- dihitung dari data sumber
+- bukan angka yang diisi manual untuk flow normal
+- tetap bisa di-maintain manual lewat CRUD admin/backfill kalau diperlukan
+
+#### Sumber data kalkulasi
+
+- `total_landing` = sum `flight_data.landing_count`
+- `total_airframe_hours` = sum durasi flight
+- `total_airframe_cycles` = count flight data
+- `total_hook_release` = sum `flight_data.hook_releases`
+- `total_rotor_brake_cycle` = sum `flight_data.rotor_brake_cycle`
+- `total_flight_report` = count report yang punya helicopter terkait
+- metric engine diambil dari field FM report dan dijumlahkan
+
+#### Kapan dihitung
+
+Kalkulasi ulang dilakukan saat:
+- `fm_report` di-complete
+
+Kalkulasi tidak dilakukan lagi saat:
+- create / update after flight inspection
+- create / update / delete flight data
+- draft FM report di-upsert
+
+## Response `GET FM Report`
+
+Endpoint:
+- `GET /api/v1/fm-reports/get/:flight_id`
+
+Response akan selalu mengirim field `helicopter_usage`.
+
+Perilaku response:
+- jika row `helicopter_usage` ada di database, isi nilainya dari row tersebut
+- jika row belum ada, backend tetap mengirim object `helicopter_usage` dengan semua angka `0`
+
+Contoh bentuk response:
+
+```json
+{
+  "data": {
+    "type": "fm_report",
+    "id": "report-id",
+    "attributes": {
+      "flight_id": "flight-id",
+      "completed_at": null,
+      "helicopter_usage": {
+        "type": "helicopter_usage",
+        "id": "",
+        "attributes": {
+          "helicopter_id": "helicopter-id",
+          "total_landing": 0,
+          "total_airframe_hours": 0,
+          "total_airframe_cycles": 0,
+          "total_engine_1_hours": 0,
+          "total_engine_1_gpc_ng_n1": 0,
+          "total_engine_1_ptc_nf_n2": 0,
+          "total_engine_1_ccc": 0,
+          "total_engine_2_hours": 0,
+          "total_engine_2_gpc_ng_n1": 0,
+          "total_engine_2_ptc_nf_n2": 0,
+          "total_engine_2_ccc": 0,
+          "total_flight_report": 0,
+          "total_hook_release": 0,
+          "total_rotor_brake_cycle": 0
+        }
+      }
+    }
+  }
+}
+```
+
+## Status yang Perlu Diingat
+
+### Masih editable
+
+- mission sebelum after flight inspection ada
+- flight data sebelum FM report di-complete
+- FM report sebelum complete
+
+### Sudah locked
+
+- mission setelah after flight inspection ada
+- flight data setelah FM report di-complete
+- FM report setelah complete
+
+## Dampak ke Frontend
+
+Frontend sebaiknya mengikuti aturan ini:
+
+1. Jika after flight inspection sudah ada:
+   - sembunyikan atau disable aksi create mission
+   - sembunyikan atau disable aksi create flight data baru
+2. Jika FM report sudah complete:
+   - disable semua edit flight data
+   - disable edit FM report
+3. Saat menampilkan FM report:
+   - selalu render section helicopter usage
+   - jika angka semua `0`, itu berarti belum ada summary yang terhitung atau belum ada data sumber yang selesai
+
+## Error yang Relevan
+
+Lihat katalog lengkap di:
+- [`docs/error-catalog.md`](./error-catalog.md)
+
+Error yang paling sering dipakai di alur ini:
+- `MISSION_AFTER_FLIGHT_LOCKED`
+- `FLIGHT_DATA_CREATE_BLOCKED`
+- `FLIGHT_DATA_AFTER_FLIGHT_LOCKED`
+- `FLIGHT_DATA_LOCKED`
+- `FM_REPORT_LOCKED`
+
+## Catatan Implementasi
+
+- `after_flight_inspection` tidak lagi memicu refresh `helicopter_usage`
+- `flight_data` tidak lagi memicu refresh `helicopter_usage`
+- refresh `helicopter_usage` hanya terjadi saat `fm_report` di-complete
+- `GET FM Report` tetap aman walau row `helicopter_usage` belum ada
+
+## Referensi Endpoint
+
+- `POST /api/v1/mission/create`
+- `PATCH /api/v1/mission/update/{flight_id}`
+- `POST /api/v1/flight-data/create`
+- `PATCH /api/v1/flight-data/update/{id}`
+- `DELETE /api/v1/flight-data/delete/{id}`
+- `POST /api/v1/after-flight-inspection/create`
+- `PATCH /api/v1/after-flight-inspection/update`
+- `POST /api/v1/fm-reports/complete/{flight_id}`
+- `GET /api/v1/fm-reports/get/{flight_id}`
diff --git a/docs/frontend-sso-exchange-flow.md b/docs/frontend-sso-exchange-flow.md
new file mode 100644
index 0000000..477a804
--- /dev/null
+++ b/docs/frontend-sso-exchange-flow.md
@@ -0,0 +1,121 @@
+# Frontend Flow: Microsoft `ssoSilent` + Backend `/auth/exchange`
+
+This document describes the recommended frontend authentication flow when using:
+- Microsoft Entra `ssoSilent` on the frontend
+- Backend session tokens (`access` + `refresh`) issued by `/api/v1/auth/exchange`
+
+## Goal
+
+Use Microsoft silent SSO to re-establish identity, then exchange that identity for backend session cookies/tokens used by API requests.
+
+## Prerequisites
+
+- Frontend already integrated with MSAL and can call `ssoSilent`.
+- Backend has `POST /api/v1/auth/exchange`.
+- User account is already linked/recognized by backend SSO mapping.
+- Backend uses cookie-based auth session (`access` + `refresh` cookies).
+
+## High-Level Sequence
+
+1. Frontend attempts to call backend API with current backend access session.
+2. If backend responds `401`, frontend calls `POST /api/v1/auth/refresh` once.
+3. If refresh fails (`401`), frontend tries Microsoft `ssoSilent`.
+4. If `ssoSilent` succeeds, frontend calls `POST /api/v1/auth/exchange`.
+5. Backend issues fresh auth cookies. Frontend retries the original API request.
+6. If `ssoSilent` fails with `interaction_required`, frontend logs out local app session and redirects user to interactive login.
+
+## Detailed Frontend Logic
+
+## 1) App startup / route guard
+
+1. Try calling a lightweight authenticated endpoint (for example `/api/v1/auth/me`).
+2. If response is `200`, continue app normally.
+3. If response is `401`, run the recovery flow below.
+
+## 2) Recovery flow for backend `401`
+
+1. Call `POST /api/v1/auth/refresh` once.
+2. If refresh is successful (`200`), retry the original request and continue.
+3. If refresh fails (`401`), call Microsoft `ssoSilent`.
+
+## 3) On successful `ssoSilent`
+
+The frontend receives a Microsoft auth result (example fields):
+- `accessToken`
+- `idToken`
+- `idTokenClaims`
+
+Send them to backend exchange endpoint:
+
+```http
+POST /api/v1/auth/exchange
+Content-Type: application/json
+```
+
+```json
+{
+  "data": {
+    "type": "auth_exchange",
+    "attributes": {
+      "access_token": "<ms_access_token>",
+      "id_token": "<ms_id_token>",
+      "id_token_claims": {
+        "sub": "...",
+        "preferred_username": "user@company.com",
+        "name": "User Name",
+        "tid": "...",
+        "oid": "...",
+        "exp": 1715603600
+      }
+    }
+  }
+}
+```
+
+Expected behavior:
+- `200`: backend sets fresh session cookies -> frontend retries previous API call.
+- `401`: identity not linked / invalid token -> treat as not authenticated and move to login.
+
+## 4) On failed `ssoSilent`
+
+If frontend receives:
+- `errorCode = "interaction_required"` (or equivalent no-session/no-cookie condition)
+
+Then:
+1. Clear local app auth state (user store, cached flags, pending retries).
+2. Redirect to interactive login page/flow.
+
+Do not loop `ssoSilent` repeatedly.
+
+## Retry Rules (Important)
+
+- Only attempt each step once per failure chain:
+  - one `/auth/refresh`
+  - one `ssoSilent`
+  - one `/auth/exchange`
+- Use a request queue/lock to prevent multiple parallel refresh/exchange attempts.
+- If exchange fails, stop retries and force user to login interactively.
+
+## Suggested Error Handling Matrix
+
+- Backend API `401`:
+  - action: `/auth/refresh`
+- `/auth/refresh` `401`:
+  - action: `ssoSilent`
+- `ssoSilent` success:
+  - action: `/auth/exchange`
+- `ssoSilent` `interaction_required`:
+  - action: clear session + redirect login
+- `/auth/exchange` `401`:
+  - action: clear session + redirect login
+
+## Security Notes
+
+- Do not store backend refresh tokens in JavaScript storage.
+- Prefer `HttpOnly`, `Secure`, `SameSite` cookies from backend.
+- Avoid logging raw Microsoft tokens in browser console or monitoring payloads.
+
+## Optional UX Improvement
+
+When redirecting to login after `interaction_required`, preserve the intended route:
+- Save current path (`returnTo`) and restore it after successful login.
diff --git a/docs/mcf-flow.md b/docs/mcf-flow.md
new file mode 100644
index 0000000..8e9ba81
--- /dev/null
+++ b/docs/mcf-flow.md
@@ -0,0 +1,165 @@
+# Panduan MCF (Maintenance Check Flight): Cara Pakai & Apa yang Terjadi
+
+> Dokumen ini menjelaskan **cara mengelola MCF** sebuah helikopter — mengaktifkan, mengisi/edit draft, menandatangani (sign), membatalkan tanda tangan, dan membatalkan MCF — beserta **apa yang terjadi** di status helikopter, halaman fleet, dan log.
+>
+> Semua endpoint berawalan `/api/v1` dan butuh login. MCF adalah **entity per-helikopter** dengan lifecycle draft → signed.
+
+---
+
+## 1. Konsep singkat
+
+**MCF** = penerbangan uji (check flight) yang wajib dilakukan setelah perawatan tertentu. Selama helikopter "sedang MCF", statusnya `mcf` di fleet.
+
+Tiga pemain endpoint:
+
+| Endpoint | Tugasnya |
+|---|---|
+| **`set`** | Yes/No + **tempat kerja draft** (buat, isi, edit data check-flight) |
+| **`sign`** | **finalize** (tandatangani hasil) / **unsign** (balik ke draft) |
+| **`get` / `get-by-helicopter`** | baca satu MCF / daftar (log, termasuk yang cancelled & signed) |
+
+> **Tidak ada** endpoint `create`/`delete`/`unassign` lagi — semuanya lewat `set` & `sign`.
+
+---
+
+## 2. Status (state) sebuah MCF
+
+| State | Artinya | `completed_at` | `cancelled_at` | Status heli |
+|---|---|---|---|---|
+| **Draft** | Dibuat/diisi, belum ditandatangani | kosong | kosong | `mcf` |
+| **Signed – passed** | Sudah tanda tangan, hasil **lulus** | terisi | kosong | **clear** (keluar MCF) |
+| **Signed – failed** | Sudah tanda tangan, hasil **gagal** | terisi | kosong | `mcf` (perlu re-flight) |
+| **Cancelled** | Draft di-set No ("tidak jadi", tak pernah sign) | kosong | terisi | **lepas** (fleet placeholder) |
+
+**Aturan penting:**
+- **1 MCF terbuka (draft) per helikopter.** `set active:true` saat draft sudah ada → **meng-update** draft itu, bukan bikin baru.
+- **Cancelled hanya untuk draft** (yang belum pernah di-sign). MCF yang sudah signed = **event nyata**, tidak bisa di-cancel.
+- MCF yang cancelled/signed **tetap tersimpan** di list (`get-by-helicopter`) sebagai **log/history**.
+
+---
+
+## 3. Flow lengkap (langkah + apa yang terjadi)
+
+### Langkah 1 — Aktifkan / isi / edit draft
+`POST /mcf/set/{helicopter_id}`
+
+```json
+{
+  "data": {
+    "type": "mcf_set",
+    "attributes": {
+      "active": true,
+      "flight_id": "019d6774-98e8-7fba-9ef4-3795c0da8a13",
+      "af_hours": "1245.3",
+      "landing_count": 3,
+      "date": "2026-06-17",
+      "result": "passed",
+      "notes": "MCF setelah pekerjaan engine mount"
+    }
+  }
+}
+```
+
+**Apa yang terjadi:**
+- Belum ada draft → **buat draft baru** → **201**.
+- Sudah ada draft terbuka → **update draft itu** dengan data yang dikirim → **200**.
+- Semua field data **opsional** — boleh isi sebagian dulu, lengkapi bertahap dengan `set` lagi.
+- Helikopter masuk **status `mcf`**. Di fleet, object `mcf` muncul (`sign: false`, `af_hours`/`landing_count` pre-fill dari total pesawat kalau belum diisi).
+
+> `active` boleh diomit → dianggap `true`.
+
+### Langkah 2 — Finalize (tanda tangan)
+`POST /mcf/sign/{id}`
+
+```json
+{
+  "data": {
+    "type": "mcf_sign",
+    "attributes": {
+      "sign": true,
+      "af_hours": "1245.3",
+      "landing_count": 3,
+      "utc_time": "2026-06-17T08:30:00Z",
+      "date": "2026-06-17",
+      "result": "passed"
+    }
+  }
+}
+```
+
+**Apa yang terjadi:**
+- **Wajib lengkap**: `af_hours`, `landing_count`, `utc_time`, `date`, `result` (else **422**, pointer ke field yang kurang).
+- MCF jadi **signed/completed** (`completed_at` + `completed_by` terisi).
+- `result: passed` → **status MCF clear** (helikopter keluar dari MCF).
+- `result: failed` → helikopter **tetap `mcf`** (perlu re-flight — buat MCF baru lewat `set active:true`).
+
+### Langkah 3 — Batal tanda tangan (unsign)
+`POST /mcf/sign/{id}` dengan `{ "sign": false }`
+
+**Apa yang terjadi:**
+- MCF yang signed **balik jadi draft** (`completed_at` dikosongkan) — **datanya tetap**.
+- Bisa di-edit lagi lewat `set`, lalu di-`sign` ulang.
+
+### Langkah 4 — Nonaktifkan / batal (set No)
+`POST /mcf/set/{helicopter_id}` dengan `{ "active": false }`
+
+**Apa yang terjadi:**
+- Draft (belum sign) → ditandai **`cancelled`** ("tidak jadi") → **status MCF lepas** → fleet balik **placeholder**. Record **tetap di list** sebagai log cancelled.
+- **Sudah signed → BUKAN batal** (event nyata). MCF dibiarkan; response mengembalikan MCF signed itu apa adanya. Di fleet **datanya tetap muncul** (lihat §5): untuk `passed` helikopter sudah **keluar status MCF** ("active no") tapi data MCF sebelumnya **tetap tampil**; untuk `failed` helikopter tetap `mcf`.
+- Tidak ada MCF sama sekali → **no-op** (idempotent, sudah "No").
+
+---
+
+## 4. Contoh alur khas
+
+```
+set  {active:true, af_hours, result, ...}   → draft dibuat (201)
+set  {active:true, ...revisi...}            → draft di-update (200)
+sign {sign:true, ...lengkap...}             → signed  (passed=clear / failed=tetap)
+    ── kalau salah ──
+sign {sign:false}                           → balik draft (data tetap) → edit → sign lagi
+    ── kalau tidak jadi ──
+set  {active:false}                         → cancelled (lepas status, tetap jadi log)
+```
+
+---
+
+## 5. Efek ke Fleet Status
+
+Object `mcf` di response fleet (`GET /api/v1/fleet-status/...`) selalu mencerminkan **MCF terbaru** helikopter. Field **`active`** = apakah helikopter **sedang dalam MCF** (draft, atau signed-failed yang perlu re-flight); `false` kalau cleared/cancelled/tidak ada.
+
+| Kondisi MCF terbaru | `active` | Object `mcf` di fleet |
+|---|---|---|
+| Tidak ada / cancelled | `false` | **placeholder** — `id: ""`, `sign: false`, `af_hours`/`landing_count` dari total pesawat |
+| Draft (belum sign) | `true` | id draft, `sign: false`, data pre-fill dari pesawat kalau kosong |
+| Signed – passed | `false` | id, `sign: true`, snapshot MCF + `signed_by` (data tetap tampil walau status sudah clear) |
+| Signed – failed | `true` | id, `sign: true`, snapshot + `signed_by` (masih MCF, perlu re-flight) |
+
+Urutan status di fleet & hold list: **MCF → AOG → Booked → Available** (paling kritikal dulu).
+
+---
+
+## 6. Ringkasan endpoint
+
+| Method | Path | Fungsi |
+|---|---|---|
+| `POST` | `/api/v1/mcf/set/{helicopter_id}` | activate/edit draft (`active:true`) · cancel (`active:false`) |
+| `POST` | `/api/v1/mcf/sign/{id}` | finalize (`sign:true`) · unsign (`sign:false`) |
+| `GET` | `/api/v1/mcf/get/{id}` | baca satu MCF |
+| `GET` | `/api/v1/mcf/get-by-helicopter/{helicopter_id}` | daftar MCF helikopter (log) |
+
+**Permission:** `mcf.create` (untuk `set`), `mcf.complete` (untuk `sign`), `mcf.read` (untuk `get`).
+
+---
+
+## 7. Kode error umum
+
+| Kode | Kapan |
+|---|---|
+| `MCF_INVALID_UUID` | `helicopter_id` / `id` bukan UUID valid (422) |
+| `MCF_INVALID_JSON` | body JSON rusak (400) |
+| `INVALID_DATA_TYPE` | tipe field salah (mis. `flight_id` dikirim angka) (422) |
+| `MCF_INVALID_PAYLOAD` | field check-flight kurang/salah saat `sign:true` (422, pointer ke field) |
+| `MCF_NOT_FOUND` | MCF id tidak ada (404) |
+
+> **Catatan:** relasi MCF ke penerbangan lewat `flight_id` (opsional). Lihat juga [aog-mcf-nsr-flow.md](aog-mcf-nsr-flow.md) untuk gambaran status helikopter secara keseluruhan (AOG/MCF/NSR).
diff --git a/docs/password-reset.md b/docs/password-reset.md
new file mode 100644
index 0000000..944cc2c
--- /dev/null
+++ b/docs/password-reset.md
@@ -0,0 +1,91 @@
+# Password Reset
+
+## Endpoints
+
+### `POST /api/v1/auth/forgot-password`
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_forgot_password",
+    "attributes": {
+      "email": "user@example.com"
+    }
+  }
+}
+```
+
+Response (`200` always for valid payload):
+```json
+{
+  "data": {
+    "type": "auth_forgot_password",
+    "attributes": {
+      "message": "If the account exists, a password reset link has been sent."
+    }
+  }
+}
+```
+
+### `POST /api/v1/auth/reset-password`
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_reset_password",
+    "attributes": {
+      "token": "<raw-token>",
+      "new_password": "StrongPassphrase123!",
+      "confirm_password": "StrongPassphrase123!"
+    }
+  }
+}
+```
+
+Success response (`200`):
+```json
+{
+  "data": {
+    "type": "auth_reset_password",
+    "attributes": {
+      "message": "Password has been reset successfully. Please log in again."
+    }
+  }
+}
+```
+
+Invalid/expired/used token response (`400`):
+```json
+{
+  "errors": [
+    {
+      "status": "400",
+      "title": "Invalid reset link",
+      "detail": "This reset link is invalid or expired."
+    }
+  ]
+}
+```
+
+## Environment Variables
+
+- `AUTH_PASSWORD_RESET_URL` frontend reset page URL; backend appends `?token=...`
+- `AUTH_PASSWORD_RESET_TTL` reset token TTL (default `20m`, enforced 15-30m range)
+- `AUTH_FORGOT_PASSWORD_EMAIL_COOLDOWN` cooldown per email identifier (default `2m`)
+- `AUTH_FORGOT_PASSWORD_MIN_DURATION` minimum forgot-password response duration (default `150ms`)
+- `AUTH_FORGOT_PASSWORD_IP_RATE_MAX` per-IP max attempts in window (default `10`)
+- `AUTH_FORGOT_PASSWORD_IP_RATE_WINDOW` per-IP window duration (default `15m`)
+
+## Security Decisions
+
+- Uses `crypto/rand` for reset token entropy.
+- Stores only SHA-256 token hashes in DB (`password_reset_tokens.token_hash`).
+- Raw token is only delivered via email link.
+- Tokens are single-use (`used_at`) and expire (`expires_at`).
+- New forgot-password request invalidates previous active reset tokens for that user.
+- Successful reset invalidates all active reset tokens for the user.
+- Successful reset revokes active sessions by incrementing the MySQL-backed user session version used in JWT claims.
+- Forgot-password response is generic to prevent account enumeration.
+- Forgot-password throttling is applied per IP and per email identifier.
diff --git a/docs/queue-sqs-migration.md b/docs/queue-sqs-migration.md
new file mode 100644
index 0000000..3a63c7f
--- /dev/null
+++ b/docs/queue-sqs-migration.md
@@ -0,0 +1,157 @@
+# Queue Migration Notes
+
+This project no longer supports Redis as a runtime dependency. Queue publishing and consumption are SQS-only, while transient auth/runtime state is stored in MySQL.
+
+## Current Flow
+
+1. API writes business data to MySQL.
+2. If `QUEUE_OUTBOX_ENABLED=true`, email jobs are persisted to `email_outbox_messages`.
+3. Worker polls the outbox and publishes serialized messages to SQS.
+4. Worker consumes SQS messages with long polling and sends email through Amazon SES v2.
+5. Successful processing deletes the SQS message.
+6. Failed processing leaves the message unacked so SQS visibility timeout and DLQ redrive policy handle retries.
+
+## What Changed
+
+- Removed Redis producer, consumer, and Redis-backed idempotency paths.
+- Removed Redis token store used for:
+  - refresh/session bookkeeping
+  - SSO state
+  - TOTP/WebAuthn challenges
+  - security PIN lock/cooldown state
+- Added MySQL-backed transient stores:
+  - `auth_runtime_tokens`
+  - `queue_idempotency_records`
+- Simplified bootstrap:
+  - API uses MySQL + optional direct SQS publisher when outbox is disabled.
+  - Worker uses MySQL + SQS only.
+
+## Required Environment
+
+Queue and worker settings:
+
+```bash
+EMAIL_PROVIDER=mock
+EMAIL_MOCK_DIR=.local/emails
+
+QUEUE_MESSAGE_SCHEMA_VERSION=v2
+QUEUE_ENABLE_LEGACY_PAYLOAD_FALLBACK=true
+QUEUE_IDEMPOTENCY_KEY_PREFIX=queue:idempotency:email:
+QUEUE_IDEMPOTENCY_TTL=24h
+QUEUE_PROCESSING_TTL=15m
+QUEUE_WORKER_CONCURRENCY=4
+QUEUE_WORKER_MAX_BATCH_SIZE=10
+QUEUE_WORKER_PROCESS_TIMEOUT=30s
+QUEUE_WORKER_SHUTDOWN_TIMEOUT=30s
+QUEUE_WORKER_BACKOFF_MIN=1s
+QUEUE_WORKER_BACKOFF_MAX=5m
+QUEUE_WORKER_PERMANENT_FAILURE_DELAY=30s
+QUEUE_WORKER_MONITOR_ADDR=127.0.0.1:9090
+QUEUE_WORKER_HEALTH_ERROR_THRESHOLD=3
+QUEUE_WORKER_DEPTH_POLL_INTERVAL=30s
+QUEUE_OUTBOX_ENABLED=true
+QUEUE_OUTBOX_POLL_INTERVAL=1s
+QUEUE_OUTBOX_BATCH_SIZE=10
+QUEUE_OUTBOX_DISPATCH_TIMEOUT=10s
+QUEUE_OUTBOX_LOCK_TTL=1m
+QUEUE_OUTBOX_MAX_ATTEMPTS=20
+```
+
+SES settings:
+
+```bash
+AWS_REGION=ap-southeast-1
+SES_REGION=
+SES_FROM=no-reply@example.com
+SES_CONFIGURATION_SET=
+SES_SEND_TIMEOUT=10s
+SES_ENDPOINT=
+SES_ALLOW_INSECURE_ENDPOINT=false
+```
+
+Local/dev recommendation when you do not have AWS SES:
+
+- set `EMAIL_PROVIDER=mock`
+- keep SQS on LocalStack if needed
+- inspect delivered mock emails in `EMAIL_MOCK_DIR`
+
+AWS / SQS settings:
+
+```bash
+AWS_REGION=ap-southeast-1
+SQS_ENDPOINT=
+SQS_ALLOW_INSECURE_ENDPOINT=false
+SQS_QUEUE_URL=https://sqs.ap-southeast-1.amazonaws.com/123456789012/wucher-email
+SQS_QUEUE_TYPE=standard
+SQS_MESSAGE_GROUP_ID=email
+SQS_MAX_MESSAGES=10
+SQS_WAIT_TIME_SECONDS=20
+SQS_VISIBILITY_TIMEOUT=60s
+```
+
+## SQS Expectations
+
+Configure the queue outside the application with:
+
+- long polling enabled
+- sensible visibility timeout
+- DLQ redrive policy
+- `maxReceiveCount` aligned with retry tolerance
+
+Recommended baseline:
+
+- `ReceiveMessageWaitTimeSeconds=20`
+- `VisibilityTimeout=60`
+- `maxReceiveCount=5`
+
+## IAM
+
+API needs `sqs:SendMessage` only when `QUEUE_OUTBOX_ENABLED=false`.
+
+Worker needs:
+
+- `sqs:SendMessage` to the main queue when dispatching outbox messages
+- `sqs:ReceiveMessage`
+- `sqs:DeleteMessageBatch`
+- `sqs:ChangeMessageVisibility`
+- `sqs:GetQueueAttributes`
+- `ses:SendEmail`
+
+If SES event tracking is enabled, provision it separately with:
+
+- SES configuration set event destinations
+- SNS topic publish permissions
+- a dedicated SQS event queue and consumer policy
+
+## Breaking Changes
+
+- Remove these Redis env vars from deployment:
+  - `REDIS_ADDR`
+  - `REDIS_PASSWORD`
+  - `REDIS_DB`
+  - `QUEUE_PRIMARY_BACKEND`
+  - `QUEUE_SECONDARY_BACKEND`
+  - `QUEUE_SECONDARY_REQUIRED`
+  - `QUEUE_CONSUMER_BACKEND`
+  - `QUEUE_IDEMPOTENCY_BACKEND`
+  - `QUEUE_PRODUCER_MODE`
+  - `QUEUE_REDIS_DLQ_KEY`
+  - `AUTH_EMAIL_QUEUE_KEY`
+  - `SQS_DLQ_URL`
+- Worker now requires MySQL even when it is only consuming SQS, because idempotency state is persisted in MySQL.
+- Old Redis backlog is not consumed by this version. Drain or discard legacy Redis queues before deploy.
+
+## Deployment Checklist
+
+1. Ensure MySQL migration/AutoMigrate runs and creates `auth_runtime_tokens` and `queue_idempotency_records`.
+2. Create or verify the SQS queue and DLQ redrive policy.
+3. Verify the SES identity/domain and optional configuration set.
+4. Remove Redis and SMTP config from runtime manifests and secrets.
+5. Deploy API and worker.
+6. Verify:
+   - worker `/health`
+   - worker `/metrics`
+   - SQS queue depth
+   - outbox rows are progressing from `pending` to `published`
+   - SES send acceptance/message IDs in worker logs
+7. Manually delete Redis infrastructure after confirming there is no remaining backlog you still need.
diff --git a/docs/security-pin.md b/docs/security-pin.md
new file mode 100644
index 0000000..557b73e
--- /dev/null
+++ b/docs/security-pin.md
@@ -0,0 +1,349 @@
+# Security PIN Flow
+
+This document explains how to configure and use a per-user 6-digit Security PIN for sensitive actions.
+All API payloads follow **JSON:API**.
+
+## 1) Setup Security PIN (first time)
+
+Endpoint:
+`POST /api/v1/auth/pin/setup`
+
+Auth:
+- Requires logged-in session (`AUTH` cookie / access token cookie)
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_pin_setup",
+    "attributes": {
+      "pin": "123456",
+      "confirm_pin": "123456"
+    }
+  }
+}
+```
+
+Success (`200`):
+```json
+{
+  "data": {
+    "type": "auth_pin_setup",
+    "attributes": {
+      "configured": true
+    }
+  }
+}
+```
+
+If PIN already exists (`409`):
+```json
+{
+  "errors": [
+    {
+      "status": "409",
+      "title": "PIN already configured",
+      "detail": "security PIN is already set"
+    }
+  ]
+}
+```
+
+## 2) Verify PIN before sensitive action
+
+Endpoint:
+`POST /api/v1/auth/pin/verify`
+
+Auth:
+- Requires logged-in session
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_pin_verify",
+    "attributes": {
+      "pin": "123456",
+      "action": "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"
+    }
+  }
+}
+```
+
+Success (`200`):
+```json
+{
+  "data": {
+    "type": "auth_pin_verify",
+    "attributes": {
+      "verified": true,
+      "action_token": "<one-time-token>",
+      "action_token_ttl_ms": 300000
+    }
+  }
+}
+```
+
+Use the returned token on the sensitive API call:
+- Header: `X-PIN-Verification-Token: <one-time-token>`
+
+Example sensitive request:
+```http
+DELETE /api/v1/users/delete/{uuid}
+X-PIN-Verification-Token: <one-time-token>
+Cookie: wucher_at=...
+```
+
+Important:
+- Token is action-bound (`a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74` only for that action).
+- Token is one-time use.
+- Token expires by `AUTH_SECURITY_PIN_ACTION_TOKEN_TTL`.
+- Maximum failed attempts follow `AUTH_SECURITY_PIN_MAX_ATTEMPTS` (default `5`).
+- When max attempts are reached, API returns `429` and PIN becomes blocked.
+- Block is permanent until PIN reset succeeds (`AUTH_SECURITY_PIN_LOCK_DURATION=0` means no auto-unlock timeout).
+
+## 3) Change Security PIN
+
+Endpoint:
+`POST /api/v1/auth/pin/change`
+
+Auth:
+- Requires logged-in session
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_pin_change",
+    "attributes": {
+      "current_pin": "123456",
+      "new_pin": "654321",
+      "confirm_pin": "654321"
+    }
+  }
+}
+```
+
+Success (`200`):
+```json
+{
+  "data": {
+    "type": "auth_pin_change",
+    "attributes": {
+      "updated": true
+    }
+  }
+}
+```
+
+## 4) Reset Security PIN Flow
+
+### 4.1 Request reset link (blocked PIN button)
+Endpoint:
+`POST /api/v1/auth/pin/request-reset`
+
+Auth:
+- Requires logged-in session
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_pin_request_reset",
+    "attributes": {
+      "password": "<current-account-password>"
+    }
+  }
+}
+```
+
+Success (`200`):
+```json
+{
+  "data": {
+    "type": "auth_pin_request_reset",
+    "attributes": {
+      "message": "If allowed, a security PIN reset link has been sent to your email."
+    }
+  }
+}
+```
+
+If PIN not blocked (`409`):
+```json
+{
+  "errors": [
+    {
+      "status": "409",
+      "title": "PIN not blocked",
+      "detail": "security PIN is not blocked"
+    }
+  ]
+}
+```
+
+Invalid password (`401`):
+```json
+{
+  "errors": [
+    {
+      "status": "401",
+      "title": "Unauthorized",
+      "detail": "invalid password"
+    }
+  ]
+}
+```
+
+Rate limited (`429`):
+```json
+{
+  "errors": [
+    {
+      "status": "429",
+      "title": "Too many requests",
+      "detail": "please wait before requesting another reset link"
+    }
+  ]
+}
+```
+
+### 4.2 Request reset link (public forgot endpoint)
+Endpoint:
+`POST /api/v1/auth/pin/forgot`
+
+Request:
+```json
+{
+  "data": {
+    "type": "auth_forgot_pin",
+    "attributes": {
+      "email": "user@example.com"
+    }
+  }
+}
+```
+
+Response is always generic (`200`):
+```json
+{
+  "data": {
+    "type": "auth_forgot_pin",
+    "attributes": {
+      "message": "If the account exists, a security PIN reset link has been sent."
+    }
+  }
+}
+```
+
+### 4.3 Reset PIN with password or Microsoft re-auth
+Endpoint:
+`POST /api/v1/auth/pin/reset`
+
+Notes:
+- `method` is optional. Default is `password`.
+- For `method=password`, `token` is required and must be the raw single-use reset token from the email reset link, then send `password`.
+- For `method=microsoft`, `token` is not required. Send `reauth_token` from Microsoft re-auth directly.
+
+Request with password re-auth:
+```json
+{
+  "data": {
+    "type": "auth_reset_pin",
+    "attributes": {
+      "token": "<raw-token-from-email-link>",
+      "password": "<current-account-password>",
+      "new_pin": "123456",
+      "confirm_pin": "123456"
+    }
+  }
+}
+```
+
+Request with Microsoft re-auth:
+```json
+{
+  "data": {
+    "type": "auth_reset_pin",
+    "attributes": {
+      "method": "microsoft",
+      "reauth_token": "<reauth-token-from-/auth/microsoft/reauth?purpose=pin_reset_request>",
+      "new_pin": "123456",
+      "confirm_pin": "123456"
+    }
+  }
+}
+```
+
+Success (`200`):
+```json
+{
+  "data": {
+    "type": "auth_reset_pin",
+    "attributes": {
+      "message": "Security PIN has been reset successfully.",
+      "reset_success": true,
+      "redirect_url": "https://app.example.com"
+    }
+  }
+}
+```
+
+Invalid/expired token (`400`):
+```json
+{
+  "errors": [
+    {
+      "status": "400",
+      "title": "Invalid reset link",
+      "detail": "This reset link is invalid or expired."
+    }
+  ]
+}
+```
+
+Invalid password (`401`):
+```json
+{
+  "errors": [
+    {
+      "status": "401",
+      "title": "Unauthorized",
+      "detail": "invalid password"
+    }
+  ]
+}
+```
+
+## 5) Sensitive endpoints currently protected by PIN token
+
+The following routes require `X-PIN-Verification-Token`:
+- `POST /api/v1/auth/invite` (`action=2a59e8b4-5a72-4be3-b8fc-4f49941181c3`)
+- `POST /api/v1/users/create` (`action=2a59e8b4-5a72-4be3-b8fc-4f49941181c3`)
+- `PATCH /api/v1/users/update/:uuid` (`action=428fdf48-3f99-46ea-bc47-8fb2e312be08`)
+- `DELETE /api/v1/users/delete/:uuid` (`action=a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74`)
+- `POST /api/v1/roles/create` (`action=7fb1d693-8692-4e8f-be86-fd0e29e96bc3`)
+- `PATCH /api/v1/roles/update/:uuid` (`action=18ca5bbf-ce9d-4e24-8ace-793de56c1de0`)
+- `DELETE /api/v1/roles/delete/:uuid` (`action=b87fca76-783d-45e7-9022-b2d9c95f6da7`)
+- `POST /api/v1/roles/:uuid/permissions` (`action=48e523f8-d86f-4b24-b0e3-e213e4d33db4`)
+- `DELETE /api/v1/roles/:uuid/permissions/:permission_uuid` (`action=f2bf59f8-0783-40fc-94ce-a79e40f84c44`)
+- `POST /api/v1/roles/:uuid/permissions/assign-bulk` (`action=48e523f8-d86f-4b24-b0e3-e213e4d33db4`)
+- `POST /api/v1/roles/:uuid/permissions/remove-bulk` (`action=f2bf59f8-0783-40fc-94ce-a79e40f84c44`)
+
+## 6) Security controls
+
+- PIN must be exactly 6 digits.
+- PIN is encrypted at rest (`users.security_pin_encrypted`), not stored in plaintext.
+- Forgot/reset tokens are random, hashed, single-use, and expiring.
+- Verify attempts are rate-limited per user with lockout (`AUTH_SECURITY_PIN_MAX_ATTEMPTS`, `AUTH_SECURITY_PIN_LOCK_DURATION`).
+- Forgot endpoint response is generic to reduce account enumeration risk.
+
+## 7) Environment variables
+
+- `AUTH_SECURITY_PIN_RESET_URL`
+- `AUTH_SECURITY_PIN_RESET_TTL`
+- `AUTH_FORGOT_SECURITY_PIN_EMAIL_COOLDOWN`
+- `AUTH_FORGOT_SECURITY_PIN_MIN_DURATION`
+- `AUTH_SECURITY_PIN_MAX_ATTEMPTS`
+- `AUTH_SECURITY_PIN_LOCK_DURATION`
+- `AUTH_SECURITY_PIN_ACTION_TOKEN_TTL`
diff --git a/docs/swagger.json b/docs/swagger.json
new file mode 100644
index 0000000..85e6330
--- /dev/null
+++ b/docs/swagger.json
@@ -0,0 +1,38365 @@
+{
+    "swagger": "2.0",
+    "info": {
+        "description": "Wucher backend API (JSON:API).\n\nAuth Flow (Email/Password):\n1) POST /api/v1/auth/register\n2) Check email, open verify link (GET /api/v1/auth/verify-email)\n3) POST /api/v1/auth/login\n- If TOTP enabled: response 202 with challenge_token\n4) POST /api/v1/auth/totp/verify (challenge_token + code) -\u003e cookies\n\nAuth Flow (TOTP setup):\n1) POST /api/v1/auth/totp/setup -\u003e secret + otpauth_url (enabled=false)\n2) POST /api/v1/auth/totp/confirm -\u003e enabled=true\n\nAuth Flow (Microsoft Entra SSO):\n1) GET /api/v1/auth/microsoft/login -\u003e redirect to Microsoft\n2) Microsoft redirects to /api/v1/auth/microsoft/callback\n3) Backend checks existing SSO mapping (no auto-register)\n4) If linked user exists -\u003e set cookies + optional redirect to AUTH_SSO_SUCCESS_REDIRECT\n5) If mapping not linked -\u003e login rejected (401)\n6) Existing authenticated user can link/unlink via /api/v1/auth/sso/link and /api/v1/auth/sso/unlink",
+        "title": "Wucher API",
+        "contact": {},
+        "version": "1.0"
+    },
+    "basePath": "/",
+    "paths": {
+        "/api/v1/action-signoffs/get-by-flight/{flight_id}": {
+            "get": {
+                "description": "Returns the fleet-level (complaint-independent) corrective-action sign-off state for a helicopter — `signed`, `signed_at`, `signed_by`. When none exists yet it returns an unsigned placeholder. A signed sign-off is what gates the EASA maintenance release.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints - Sign Off"
+                ],
+                "summary": "Get the current corrective-action sign-off for a helicopter",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ActionSignoffResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/action-signoffs/sign/{helicopter_id}": {
+            "post": {
+                "description": "Toggles the corrective-action sign-off for a helicopter. `sign` (optional, default true) chooses the direction: true signs, false unsigns. Send `complaint_id` to target a specific complaint's sign-off — signing it requires `action_taken` recorded (else 422 `ACTION_SIGNOFF_ACTION_REQUIRED`), and 404 `ACTION_SIGNOFF_COMPLAINT_NOT_FOUND` if the complaint does not exist. Omit `complaint_id` for a fleet-wide (complaint-independent) sign-off. A signed sign-off is what allows an EASA maintenance release to be created for the helicopter.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints - Sign Off"
+                ],
+                "summary": "Toggle the corrective-action sign-off (per complaint or fleet-wide)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Optional complaint_id + note",
+                        "name": "request",
+                        "in": "body",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ActionSignoffSignRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ActionSignoffResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/after-flight-inspection/create": {
+            "post": {
+                "description": "Create after-flight inspection and AFI file checklist for a flight inspection.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - After Flights Inspection"
+                ],
+                "summary": "Create last flights inspection",
+                "parameters": [
+                    {
+                        "description": "Create last flights inspection request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/after-flight-inspection/delete": {
+            "delete": {
+                "description": "Delete after-flight inspection and AFI checklist rows by `flight_inspection_id`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - After Flights Inspection"
+                ],
+                "summary": "Delete last flights inspection",
+                "parameters": [
+                    {
+                        "description": "Delete last flights inspection request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/after-flight-inspection/get": {
+            "get": {
+                "description": "Get after-flight inspection detail and AFI file checklist by query `inspection_id`.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - After Flights Inspection"
+                ],
+                "summary": "Get last flights inspection",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight Inspection UUID",
+                        "name": "inspection_id",
+                        "in": "query",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/after-flight-inspection/update": {
+            "patch": {
+                "description": "Update after-flight inspection and AFI file checklist for a flight inspection.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - After Flights Inspection"
+                ],
+                "summary": "Update last flights inspection",
+                "parameters": [
+                    {
+                        "description": "Update last flights inspection request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/create": {
+            "post": {
+                "description": "Create one or more checklist headers for a single base.\nRequest uses `base_id`.\nEach checklist can be created with or without initial `items`.\n`scope_code` accepts persisted codes and English aliases. Stored codes remain: `TA`, `MO`, `DI`, `MI`, `DO`, `FR`, `SA`, `SO`, `M10`, `M15`, `M20`, `M25`, `DS`.\nExample aliases: `DAILY` -\u003e `TA`, `TU/TUE/TUESDAY` -\u003e `DI`, `WE/WED/WEDNESDAY` -\u003e `MI`, `TH/THU/THURSDAY` -\u003e `DO`, `SU/SUN/SUNDAY` -\u003e `SO`, `DEADLINE` -\u003e `DS`.\n`CAT` is a virtual overview tab and is not allowed for create/update payloads.\nDuplicate `position` is allowed for both checklist headers and checklist items.\nDisplay order is stable: checklist headers `position ASC, title ASC`; checklist_items `position ASC, name ASC`.\nRequest is transactional: if one checklist/item fails, the whole batch is rolled back.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Create air rescuer checklist (bulk)",
+                "parameters": [
+                    {
+                        "description": "Bulk checklist create payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/delete/{uuid}": {
+            "delete": {
+                "description": "Delete one checklist header by UUID.\nRelated checklist items are removed together following current implementation behavior.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Delete air rescuer checklist",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist UUID",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedListResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/get-all": {
+            "get": {
+                "description": "Grouped by base and returned in `data[].attributes.bases`.\nResponse includes `tabs[]` with default tab order: `CAT`, `TA`, `MO`, `DI`, `MI`, `DO`, `FR`, `SA`, `SO`, `M10`, `M15`, `M20`, `M25`, `DS`.\n`CAT` is a virtual overview tab (not persisted in DB).\n`CAT.groups[]` only includes non-empty persisted scopes and does not include `checklist_items`.\nNormal tabs are always present. Empty normal tabs are explicitly returned as `checklists: []`.\nScope display names: `CAT=Category`, `TA=Daily`, `MO=Monday`, `DI=Tuesday`, `MI=Wednesday`, `DO=Thursday`, `FR=Friday`, `SA=Saturday`, `SO=Sunday`, `M10=M10`, `M15=M15`, `M20=M20`, `M25=M25`, `DS=Deadline`.\nDuplicate `position` is allowed. Display order is stable: checklist headers `position ASC, title ASC`; checklist_items `position ASC, name ASC`.\nOptional filters: `base_id`, `category_type` (`regular|hems`), `base_name`, `base_abbreviation`, `scope_code` (`CAT`/`OVERVIEW` or persisted scope / aliases).",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "List air rescuer checklist grouped by base",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Filter by base UUID",
+                        "name": "base_id",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "regular",
+                            "hems"
+                        ],
+                        "type": "string",
+                        "description": "Filter by base category",
+                        "name": "category_type",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by base name (contains, case-insensitive)",
+                        "name": "base_name",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by base abbreviation (contains, case-insensitive)",
+                        "name": "base_abbreviation",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by scope code. Allowed canonical: CAT, TA, MO, DI, MI, DO, FR, SA, SO, M10, M15, M20, M25, DS. English aliases are also accepted.",
+                        "name": "scope_code",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/get-all/dt": {
+            "get": {
+                "description": "Datatable variant for grouped air rescuer checklist data.\nSemantic data is the same as `get-all`: grouped by base with `tabs[]`, virtual `CAT`, and normal tabs always present.\n`CAT.groups[]` only includes non-empty persisted scopes and does not include `checklist_items`.\nEmpty normal tabs are explicitly returned as `checklists: []`.\nScope display names: `CAT=Category`, `TA=Daily`, `MO=Monday`, `DI=Tuesday`, `MI=Wednesday`, `DO=Thursday`, `FR=Friday`, `SA=Saturday`, `SO=Sunday`, `M10=M10`, `M15=M15`, `M20=M20`, `M25=M25`, `DS=Deadline`.\nDuplicate `position` is allowed. Display order is stable: checklist headers `position ASC, title ASC`; checklist_items `position ASC, name ASC`.\nOptional filters: `base_id`, `category_type` (`regular|hems`), `base_name`, `base_abbreviation`, `scope_code`.\nPagination/query controls: `page`, `size`, `limit`, `draw`.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "List air rescuer checklist grouped by base (datatable)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Filter by base UUID",
+                        "name": "base_id",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "regular",
+                            "hems"
+                        ],
+                        "type": "string",
+                        "description": "Filter by base category",
+                        "name": "category_type",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by base name (contains, case-insensitive)",
+                        "name": "base_name",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by base abbreviation (contains, case-insensitive)",
+                        "name": "base_abbreviation",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by scope code. Allowed canonical: CAT, TA, MO, DI, MI, DO, FR, SA, SO, M10, M15, M20, M25, DS. English aliases are also accepted.",
+                        "name": "scope_code",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (max 100)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Datatable draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/get/{uuid}": {
+            "get": {
+                "description": "Return one checklist detail by UUID.\nIncludes checklist header, base info, and `items` (`checklist_items`).",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Get air rescuer checklist by UUID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist UUID",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/items/delete/{item_uuid}": {
+            "delete": {
+                "description": "Delete one existing checklist item by `item_uuid`.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Delete one checklist item",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist item UUID",
+                        "name": "item_uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/items/update/{item_uuid}": {
+            "patch": {
+                "description": "Update one existing checklist item by `item_uuid`.\nThis endpoint only affects the selected item.\nDuplicate `position` is allowed.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Update one checklist item",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist item UUID",
+                        "name": "item_uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Checklist item update payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/update/{uuid}": {
+            "patch": {
+                "description": "Update checklist header fields (`scope_code`, `title`, `position`) and/or append `new_items`.\n`new_items` is append-only. Existing items are not updated/deleted by this endpoint.\nItem update/delete lifecycle must use dedicated item endpoints.\n`scope_code` accepts persisted codes and English aliases, but `CAT` (or `OVERVIEW`) is not allowed for update payload.\nDuplicate `position` is allowed.\nRequest is transactional.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Update air rescuer checklist header and append new items",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist UUID",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Checklist update payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/{uuid}/items/create": {
+            "post": {
+                "description": "Create one or more items for an existing checklist.\nParent checklist is taken from path `uuid`.\nDuplicate `position` is allowed. Display order for checklist_items is `position ASC, name ASC`.\nRequest is transactional: if one item fails, all item inserts in the batch are rolled back.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Create checklist items (bulk)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist UUID",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Bulk checklist item create payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/air-rescuer-checklist/{uuid}/items/reorder": {
+            "patch": {
+                "description": "Reorder one or more checklist items for the checklist in path `uuid`.\nUse this endpoint to swap or reorder positions with a single PIN validation.\nDuplicate `position` values remain allowed by domain rules.\nRequest is transactional: if one item fails, all position updates are rolled back.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Air Rescuer Checklist"
+                ],
+                "summary": "Reorder checklist items in one request",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Checklist UUID",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Checklist item reorder payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/audit-logs/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Audit Logs"
+                ],
+                "summary": "List audit logs",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by request_id/layer/action/method/path/message (contains)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "POST",
+                            "PUT",
+                            "PATCH",
+                            "DELETE",
+                            "UPDATE",
+                            "ALL",
+                            "*"
+                        ],
+                        "type": "string",
+                        "description": "Method filter; single/comma-separated values or ALL/*",
+                        "name": "filter[method]",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "POST",
+                            "PUT",
+                            "PATCH",
+                            "DELETE",
+                            "UPDATE",
+                            "ALL",
+                            "*"
+                        ],
+                        "type": "string",
+                        "description": "Alias for filter[method]",
+                        "name": "method",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "air_rescuer_checklist",
+                            "audit_log",
+                            "auth",
+                            "base",
+                            "base_regular",
+                            "base_hems",
+                            "base_roster",
+                            "branding",
+                            "contact",
+                            "duty_roster",
+                            "facility",
+                            "federal_state",
+                            "file_manager",
+                            "flight",
+                            "flight_data",
+                            "forces_present",
+                            "health_insurance_company",
+                            "helicopter",
+                            "helicopter_file",
+                            "hems_roster",
+                            "hospital",
+                            "icao",
+                            "insurance_patient_data",
+                            "land",
+                            "master_setting",
+                            "medicine",
+                            "mission",
+                            "opc",
+                            "patient_data",
+                            "reserve_ac",
+                            "role",
+                            "user",
+                            "vocation",
+                            "unknown",
+                            "ALL",
+                            "*"
+                        ],
+                        "type": "string",
+                        "description": "Module filter; single/comma-separated values or ALL/*",
+                        "name": "filter[module]",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "air_rescuer_checklist",
+                            "audit_log",
+                            "auth",
+                            "base",
+                            "base_regular",
+                            "base_hems",
+                            "base_roster",
+                            "branding",
+                            "contact",
+                            "duty_roster",
+                            "facility",
+                            "federal_state",
+                            "file_manager",
+                            "flight",
+                            "flight_data",
+                            "forces_present",
+                            "health_insurance_company",
+                            "helicopter",
+                            "helicopter_file",
+                            "hems_roster",
+                            "hospital",
+                            "icao",
+                            "insurance_patient_data",
+                            "land",
+                            "master_setting",
+                            "medicine",
+                            "mission",
+                            "opc",
+                            "patient_data",
+                            "reserve_ac",
+                            "role",
+                            "user",
+                            "vocation",
+                            "unknown",
+                            "ALL",
+                            "*"
+                        ],
+                        "type": "string",
+                        "description": "Alias for filter[module]",
+                        "name": "module",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "list",
+                            "get",
+                            "create",
+                            "update",
+                            "delete",
+                            "export",
+                            "custom",
+                            "ALL",
+                            "*"
+                        ],
+                        "type": "string",
+                        "description": "Action filter; single/comma-separated values or ALL/*",
+                        "name": "filter[action]",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "list",
+                            "get",
+                            "create",
+                            "update",
+                            "delete",
+                            "export",
+                            "custom",
+                            "ALL",
+                            "*"
+                        ],
+                        "type": "string",
+                        "description": "Alias for filter[action]",
+                        "name": "action",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 200)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "created_at",
+                            "-created_at",
+                            "module",
+                            "-module",
+                            "action",
+                            "-action",
+                            "layer",
+                            "-layer",
+                            "status_code",
+                            "-status_code",
+                            "success",
+                            "-success"
+                        ],
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/email-otp/send": {
+            "post": {
+                "description": "Sends a one-time 6-digit OTP to user email using login challenge token from /auth/login.\nSecurity controls: old OTP is invalidated, resend cooldown is enforced, and resend/hour quota is enforced.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Email OTP"
+                ],
+                "summary": "Send login OTP to email",
+                "parameters": [
+                    {
+                        "description": "JSON:API Email OTP send request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPSendRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPSendResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/email-otp/verify": {
+            "post": {
+                "description": "Verifies one-time OTP and completes login by issuing auth cookies.\nOTP is one-time use, expires automatically, and failed attempts are limited and audited.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Email OTP"
+                ],
+                "summary": "Verify login OTP from email",
+                "parameters": [
+                    {
+                        "description": "JSON:API Email OTP verify request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPVerifyRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPVerifyResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/exchange": {
+            "post": {
+                "description": "Accepts Microsoft token payload from frontend ssoSilent and issues backend auth cookies.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Exchange frontend Microsoft SSO token into backend session",
+                "parameters": [
+                    {
+                        "description": "JSON:API Exchange request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ExchangeRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TokenResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/forgot-password": {
+            "post": {
+                "description": "Always returns a generic success response.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Forgot Password"
+                ],
+                "summary": "Forgot password",
+                "parameters": [
+                    {
+                        "description": "JSON:API Forgot password request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForgotPasswordRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/invite": {
+            "post": {
+                "description": "Creates user without password and sends set-password link to email.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Invite user",
+                "parameters": [
+                    {
+                        "description": "JSON:API Invite request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InviteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/invite/resend-set-password": {
+            "post": {
+                "description": "Triggers a new set-password invite email for an invited user by user_id. Response is generic for security.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Resend set-password invite",
+                "parameters": [
+                    {
+                        "description": "JSON:API resend set-password invite request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ResendSetPasswordInviteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/login": {
+            "post": {
+                "description": "If TOTP enabled, returns 202 + challenge_token (use /auth/totp/verify).\nIf TOTP is not enabled, returns 202 + email OTP challenge_token (use /auth/email-otp/send then /auth/email-otp/verify).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Login with email \u0026 password",
+                "parameters": [
+                    {
+                        "description": "JSON:API Login request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LoginRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthCurrentUserResponse"
+                        }
+                    },
+                    "202": {
+                        "description": "Accepted",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LoginEmailOTPRequiredResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/logout": {
+            "post": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Refresh"
+                ],
+                "summary": "Logout (revoke refresh)",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/me": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Get current user",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthCurrentUserResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/me/timezone": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Update current user timezone",
+                "parameters": [
+                    {
+                        "description": "JSON:API timezone update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TimezoneUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthCurrentUserResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/callback": {
+            "get": {
+                "description": "Completes Microsoft SSO login. Login succeeds only when SSO identity is already linked to an existing user.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Microsoft Entra SSO callback",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Authorization code",
+                        "name": "code",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "State",
+                        "name": "state",
+                        "in": "query",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MicrosoftCallbackResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/front-channel-logout": {
+            "get": {
+                "description": "OIDC front-channel logout endpoint. Configure this URL as the \"Front-channel logout URL\" in Microsoft Entra. Microsoft loads it in a hidden iframe when the user signs out at the IdP (or from another RP). It clears local auth cookies and revokes the server-side session plus the stored Microsoft refresh token for the browser that owns the request. It never redirects and always returns 200 so the IdP logout flow can complete.",
+                "produces": [
+                    "text/html"
+                ],
+                "tags": [
+                    "Auth - SSO"
+                ],
+                "summary": "Microsoft front-channel logout callback",
+                "responses": {
+                    "200": {
+                        "description": "logged out",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/link": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Returns JSON:API payload containing Microsoft authorization URL for linking SSO to the current authenticated user.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Microsoft Entra SSO link URL",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MicrosoftLoginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/login": {
+            "get": {
+                "description": "Returns JSON:API payload containing Microsoft authorization URL.\nBackend starts with silent session-check (`prompt=none`). If Microsoft session is inactive, callback automatically falls back to interactive login.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Microsoft Entra SSO login",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MicrosoftLoginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/login-check": {
+            "get": {
+                "description": "Returns JSON:API payload containing Microsoft authorization URL with prompt=none for strict session check.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Microsoft Entra silent session check URL",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MicrosoftLoginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/logout": {
+            "post": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - SSO"
+                ],
+                "summary": "Logout Microsoft OAuth session",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/reauth": {
+            "get": {
+                "description": "Starts a Microsoft reauthentication flow for supported sensitive actions.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Microsoft Entra SSO reauth URL",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Supported values: pin_reset_request, pin_reset_confirm",
+                        "name": "purpose",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "Required when purpose=pin_reset_confirm",
+                        "name": "token",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MicrosoftLoginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/microsoft/refresh": {
+            "post": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - SSO"
+                ],
+                "summary": "Refresh Microsoft access token",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TokenResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "428": {
+                        "description": "Precondition Required",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/pin/change": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - PIN"
+                ],
+                "summary": "Change security PIN",
+                "parameters": [
+                    {
+                        "description": "JSON:API security PIN change request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINChangeRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/pin/forgot": {
+            "post": {
+                "description": "Always returns a generic success response.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - PIN"
+                ],
+                "summary": "Forgot security PIN",
+                "parameters": [
+                    {
+                        "description": "JSON:API forgot security PIN request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForgotSecurityPINRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/pin/request-reset": {
+            "post": {
+                "description": "Verifies current account password, then sends PIN reset email to currently logged-in user when PIN is blocked.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - PIN"
+                ],
+                "summary": "Request security PIN reset email for blocked PIN",
+                "parameters": [
+                    {
+                        "description": "JSON:API request security PIN reset payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RequestSecurityPINRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RequestSecurityPINResetResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/pin/reset": {
+            "post": {
+                "description": "Resets security PIN using a re-auth method. For method=password, send the single-use reset token from the email link plus password. For method=microsoft, send only reauth_token from Microsoft re-auth.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - PIN"
+                ],
+                "summary": "Reset security PIN",
+                "parameters": [
+                    {
+                        "description": "JSON:API reset security PIN request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ResetSecurityPINRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/pin/setup": {
+            "post": {
+                "description": "Creates a 6-digit security PIN for sensitive actions.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - PIN"
+                ],
+                "summary": "Setup security PIN",
+                "parameters": [
+                    {
+                        "description": "JSON:API security PIN setup request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINSetupRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINSetupResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/pin/verify": {
+            "post": {
+                "description": "Verifies PIN and returns a short-lived one-time action token.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - PIN"
+                ],
+                "summary": "Verify security PIN for sensitive action",
+                "parameters": [
+                    {
+                        "description": "JSON:API security PIN verify request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINVerifyRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINVerifyResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/refresh": {
+            "post": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Refresh"
+                ],
+                "summary": "Refresh access token",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TokenResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/register": {
+            "post": {
+                "description": "Creates user (public role: from AUTH_DEFAULT_ROLE, fallback: user) and sends verification link to email without issuing an auth session.\nNext: open verify link -\u003e then login.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Register user with email \u0026 password",
+                "parameters": [
+                    {
+                        "description": "JSON:API Register request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RegisterRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/reset-password": {
+            "post": {
+                "description": "Resets password using a single-use reset token.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Forgot Password"
+                ],
+                "summary": "Reset password",
+                "parameters": [
+                    {
+                        "description": "JSON:API Reset password request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ResetPasswordRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/sessions": {
+            "get": {
+                "description": "Lists all active sessions/devices for current user.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Refresh"
+                ],
+                "summary": "List active sessions",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/sessions/{session_id}": {
+            "delete": {
+                "description": "Revokes one session/device immediately. Requires PIN action token (header X-PIN-Verification-Token) with action=3d7d1d5f-ec48-4eca-a7ea-37f4f7927d06.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - Refresh"
+                ],
+                "summary": "Delete one session",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Session ID",
+                        "name": "session_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/set-password": {
+            "post": {
+                "description": "Sets first password for invited user and marks email as verified.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Set password from invite token",
+                "parameters": [
+                    {
+                        "description": "JSON:API Set password request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SetPasswordRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnResetSetupResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/sso/link": {
+            "post": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Link Microsoft SSO identity to the authenticated user. SSO login will only work after successful link.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Link Microsoft SSO to current user",
+                "parameters": [
+                    {
+                        "description": "JSON:API SSO link request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOLinkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOLinkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/sso/unlink": {
+            "delete": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "description": "Remove Microsoft SSO mapping from authenticated user.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Unlink Microsoft SSO from current user",
+                "parameters": [
+                    {
+                        "description": "JSON:API SSO unlink request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOUnlinkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOUnlinkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/confirm": {
+            "post": {
+                "description": "Validates initial TOTP code and enables TOTP for future logins.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - TOTP"
+                ],
+                "summary": "Confirm TOTP setup",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP confirm request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPConfirmRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/disable": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - TOTP"
+                ],
+                "summary": "Disable TOTP",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP disable request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPDisableRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/reset-setup": {
+            "post": {
+                "description": "Removes TOTP setup so the user can re-setup authenticator.\nFor method=pin, obtain token from /auth/pin/verify with action=0b5409b5-94f3-4aab-9de2-44b0ad5858f1 and send it in X-PIN-Verification-Token header.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - TOTP"
+                ],
+                "summary": "Reset TOTP setup",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP reset setup request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPResetSetupRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/setup": {
+            "post": {
+                "description": "Generates secret and otpauth URL. TOTP is NOT enabled until confirmed.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - TOTP"
+                ],
+                "summary": "Setup TOTP",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP setup request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPSetupRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPSetupResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/totp/verify": {
+            "post": {
+                "description": "Completes login when TOTP is enabled and returns auth cookies.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - TOTP"
+                ],
+                "summary": "Verify TOTP code",
+                "parameters": [
+                    {
+                        "description": "JSON:API TOTP verify request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPVerifyRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TokenResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/verify-email": {
+            "get": {
+                "description": "Confirms email verification after register.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth"
+                ],
+                "summary": "Verify email",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Verification token",
+                        "name": "token",
+                        "in": "query",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/webauthn/login/begin": {
+            "post": {
+                "description": "Creates WebAuthn assertion options for a user email.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - WebAuthn"
+                ],
+                "summary": "Begin WebAuthn login",
+                "parameters": [
+                    {
+                        "description": "JSON:API WebAuthn login begin request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginBeginRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnBeginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/webauthn/login/finish": {
+            "post": {
+                "description": "Verifies WebAuthn assertion and issues auth cookies.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - WebAuthn"
+                ],
+                "summary": "Finish WebAuthn login",
+                "parameters": [
+                    {
+                        "description": "JSON:API WebAuthn login finish request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginFinishRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.TokenResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/webauthn/register/begin": {
+            "post": {
+                "description": "Creates WebAuthn registration options for the authenticated user.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - WebAuthn"
+                ],
+                "summary": "Begin WebAuthn registration",
+                "parameters": [
+                    {
+                        "description": "JSON:API WebAuthn register begin request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterBeginRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnBeginResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/webauthn/register/finish": {
+            "post": {
+                "description": "Verifies WebAuthn registration response and stores the credential.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - WebAuthn"
+                ],
+                "summary": "Finish WebAuthn registration",
+                "parameters": [
+                    {
+                        "description": "JSON:API WebAuthn register finish request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterFinishRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/auth/webauthn/reset-setup": {
+            "post": {
+                "description": "Removes all registered WebAuthn credentials so the user can re-setup passkeys.\nFor method=pin, obtain token from /auth/pin/verify with action=1f7d457e-0a19-4a36-8d9f-2c66fd2369ab and send it in X-PIN-Verification-Token header.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Auth - WebAuthn"
+                ],
+                "summary": "Reset WebAuthn setup",
+                "parameters": [
+                    {
+                        "description": "JSON:API WebAuthn reset setup request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnResetSetupRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "429": {
+                        "description": "Too Many Requests",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/bases/create": {
+            "post": {
+                "description": "Example request:\n{\"data\":{\"type\":\"base\",\"attributes\":{\"base\":\"Lude Testing 2\",\"base_abbreviation\":\"LOIG\",\"base_category\":\"regular\",\"address\":\"Lude Airfield\",\"latitude\":47.3769,\"longitude\":8.5417,\"sortkey\":1,\"sms_alert\":false,\"checklist\":false,\"leg_time\":\"00:20\",\"default_start_time_type\":\"FIXED\",\"default_end_time_type\":\"FIXED\",\"default_shift_start\":\"06:00\",\"default_shift_end\":\"21:00\",\"utc\":\"0\",\"notes\":\"Main base\",\"operational_shift_times\":[{\"date_start\":\"2026-06-15\",\"date_end\":\"2026-06-15\",\"start_time_type\":\"BMCT\",\"end_time_type\":\"ECET\"}]}}}",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Bases"
+                ],
+                "summary": "Create base",
+                "parameters": [
+                    {
+                        "description": "JSON:API base create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/bases/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Bases"
+                ],
+                "summary": "Delete base",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Base UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/bases/get-all": {
+            "get": {
+                "description": "JSON:API list with filtering and sorting. This endpoint returns all bases.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Bases"
+                ],
+                "summary": "List bases",
+                "parameters": [
+                    {
+                        "enum": [
+                            "regular",
+                            "hems"
+                        ],
+                        "type": "string",
+                        "description": "Base category",
+                        "name": "category_type",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "regular",
+                            "hems"
+                        ],
+                        "type": "string",
+                        "description": "Alias filter for base category",
+                        "name": "base_category",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search by base/base_abbreviation/address/email/phone",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter by DUL flag (true/false)",
+                        "name": "dul",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Ignored",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Ignored",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Ignored",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/bases/get-all/dt": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Bases"
+                ],
+                "summary": "List bases (datatable)",
+                "parameters": [
+                    {
+                        "enum": [
+                            "regular",
+                            "hems"
+                        ],
+                        "type": "string",
+                        "description": "Base category",
+                        "name": "category_type",
+                        "in": "query"
+                    },
+                    {
+                        "enum": [
+                            "regular",
+                            "hems"
+                        ],
+                        "type": "string",
+                        "description": "Alias filter for base category",
+                        "name": "base_category",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter by DUL flag (true/false)",
+                        "name": "dul",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/bases/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Bases"
+                ],
+                "summary": "Get base by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Base UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/bases/update/{uuid}": {
+            "patch": {
+                "description": "Example request:\n{\"data\":{\"type\":\"hems_base\",\"id\":\"\u003cuuid\u003e\",\"attributes\":{\"base\":\"Lude Testing 2\",\"base_abbreviation\":\"LOIG\",\"base_category\":\"regular\",\"address\":\"Lude Airfield\",\"latitude\":47.3769,\"longitude\":8.5417,\"sortkey\":1,\"sms_alert\":false,\"checklist\":false,\"leg_time\":\"00:20\",\"default_start_time_type\":\"FIXED\",\"default_end_time_type\":\"FIXED\",\"default_shift_start\":\"06:00\",\"default_shift_end\":\"21:00\",\"utc\":\"0\",\"notes\":\"Main base\",\"operational_shift_times\":[{\"date_start\":\"2026-06-15\",\"date_end\":\"2026-06-15\",\"start_time_type\":\"BMCT\",\"end_time_type\":\"ECET\"}]}}}",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Bases"
+                ],
+                "summary": "Update base",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Base UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API base update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/branding/login-content": {
+            "get": {
+                "description": "Return public stable login title and subtitle from active master settings with backend defaults.\nSupports conditional requests with `If-None-Match` / `If-Modified-Since`.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Branding"
+                ],
+                "summary": "Get login content",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/internal_transport_http_handlers.loginBrandingContentDocument"
+                        }
+                    },
+                    "304": {
+                        "description": "Not Modified",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/branding/login-cover": {
+            "get": {
+                "description": "Return public stable login cover image for sign-in page.\nSupports conditional requests with `If-None-Match` / `If-Modified-Since`.",
+                "produces": [
+                    "image/png",
+                    "image/jpeg",
+                    "image/webp",
+                    "image/svg+xml",
+                    "application/octet-stream"
+                ],
+                "tags": [
+                    "Branding"
+                ],
+                "summary": "Get login cover image",
+                "responses": {
+                    "200": {
+                        "description": "Login cover image binary",
+                        "schema": {
+                            "type": "file"
+                        }
+                    },
+                    "304": {
+                        "description": "Not Modified",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/branding/logo": {
+            "get": {
+                "description": "Return a stable company logo asset for frontend consumption.\nBackend resolves private object storage internally (no presigned URL exposure) and serves fallback logo when managed logo is unavailable.\nSupports conditional requests with `If-None-Match` / `If-Modified-Since`.",
+                "produces": [
+                    "image/png",
+                    "image/jpeg",
+                    "image/webp",
+                    "image/svg+xml",
+                    "application/octet-stream"
+                ],
+                "tags": [
+                    "Branding"
+                ],
+                "summary": "Get branding logo",
+                "responses": {
+                    "200": {
+                        "description": "Branding logo binary",
+                        "schema": {
+                            "type": "file"
+                        }
+                    },
+                    "304": {
+                        "description": "Not Modified",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/action-taken/create/{id}": {
+            "post": {
+                "description": "Records the corrective action text taken for a complaint. Recording the action does NOT sign it and does NOT lift the AOG grounding: signing the action is a separate step at POST /api/v1/action-signoffs/sign/{helicopter_id} (send complaint_id), and returning the aircraft to service requires a formal release (a signed EASA release / CRS, or an NSR). The complaint stays open until an EASA release fixes it.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Record the corrective action for a complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Action taken payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintActionTakenRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/action-taken/update/{id}": {
+            "patch": {
+                "description": "Updates the previously-recorded corrective action text of a complaint. Recording/updating the action does NOT sign it — signing is a separate step at POST /api/v1/action-signoffs/sign/{helicopter_id} (send complaint_id).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Update the recorded corrective action for a complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Action taken payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintActionTakenRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/create": {
+            "post": {
+                "description": "Create a complaint (defect) for a flight inspection.\nMEL severity (mel_severity, OPTIONAL): omit it to file a \"pending_mel\" complaint and classify later (via PATCH /complaints/update/{id}); it MUST be classified before recording action taken. A pending complaint does NOT ground the aircraft — grounding starts at classification. Values: 0 = NON-MEL (grounds immediately); 1 = A (1 day grace); 2 = B (3 days); 3 = C (10 days); 4 = D (120 days). After the grace period passes without action the aircraft becomes AOG.\nNSR (Non-Safety Release) is its own flow — sign it at POST /api/v1/complaints/nsr/sign/{id} (cancel at /nsr/unsign/{id}); it is no longer set via create/update.\nOptional fields: aircraft_hours_at_report.\nTo record the corrective action, use POST /api/v1/complaints/action-taken/create/{id} (a separate, explicitly-signed step) — it is no longer part of create/update.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Create complaint",
+                "parameters": [
+                    {
+                        "description": "JSON:API complaint create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/delete/{id}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Delete complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/get-all": {
+            "get": {
+                "description": "Lists complaints grouped by helicopter. Filter by date range on the reported date, by the name of an involved person (reporter / MEL classifier / action signer / NSR decider — i.e. pilot/techniker), and by free-text search on the complaint description.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "List complaints",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search complaint description",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Reported date lower bound (YYYY-MM-DD)",
+                        "name": "date_from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Reported date upper bound (YYYY-MM-DD)",
+                        "name": "date_to",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Involved person name (pilot/techniker, partial match)",
+                        "name": "person",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort complaints",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 1,
+                        "description": "Page number",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 20,
+                        "description": "Page size",
+                        "name": "page_size",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/get-all/dt": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "List complaints grouped by helicopter (datatable)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search complaint description",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Reported date lower bound (YYYY-MM-DD)",
+                        "name": "date_from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Reported date upper bound (YYYY-MM-DD)",
+                        "name": "date_to",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Involved person name (pilot/techniker, partial match)",
+                        "name": "person",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort complaints",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 1,
+                        "description": "Datatable draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 0,
+                        "description": "Datatable start offset",
+                        "name": "start",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 10,
+                        "description": "Datatable page length",
+                        "name": "length",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/get-by-helicopter/{helicopter_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "List complaints by helicopter",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Get complaint by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/hold-items/get-all": {
+            "get": {
+                "description": "Returns the Hold Item List (HIL): complaints that are still OPEN (not yet fixed by an EASA release) AND MEL-deferred (mel_severity \u003e 0). Non-MEL defects (which ground the aircraft immediately) and already-serviced complaints are excluded. Same grouped shape and filters as get-all.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "List hold items (open MEL-deferred defects)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "From date — reported_at \u003e= (YYYY-MM-DD). Legacy 'Von'.",
+                        "name": "date_from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "To date — reported_at \u003c= (YYYY-MM-DD). Legacy 'bis'.",
+                        "name": "date_to",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Pilot/Technician name — matches reporter or action signer. Legacy 'Pilot/Techniker'.",
+                        "name": "person",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search complaint description / MEL. Legacy 'Complains'.",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20)",
+                        "name": "page_size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort expression (e.g. reported_at DESC)",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/hold-items/get-all/dt": {
+            "get": {
+                "description": "Datatable variant of the Hold Item List (open + MEL-deferred complaints). Same filters as /hold-items/get-all (date_from, date_to, person, search, helicopter_id) plus DataTables params (start, length, draw).",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "List hold items (open MEL-deferred defects) — datatable",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "From date — reported_at \u003e= (YYYY-MM-DD). Legacy 'Von'.",
+                        "name": "date_from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "To date — reported_at \u003c= (YYYY-MM-DD). Legacy 'bis'.",
+                        "name": "date_to",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Pilot/Technician name — matches reporter or action signer.",
+                        "name": "person",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search complaint description / MEL.",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "DataTables start offset",
+                        "name": "start",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "DataTables page length",
+                        "name": "length",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "DataTables draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/nsr/sign/{id}": {
+            "post": {
+                "description": "Records an NSR decision on its own flow (separate from complaint update): the aircraft is released to fly despite the open defect and is no longer grounded by it. MEL must be classified first — an unassessed (pending_mel) defect cannot be deferred, so a pending complaint returns 422. The complaint stays OPEN and is only closed by a signed EASA release. Requires the complaint.nsr permission.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Sign a Non-Safety Release (NSR / MEL deferral) for a complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Optional NSR reason",
+                        "name": "request",
+                        "in": "body",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintNSRSignRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/nsr/unsign/{id}": {
+            "post": {
+                "description": "Revokes the NSR decision: the deferral is lifted, so the still-open defect grounds the aircraft again (AOG is recomputed). Requires the complaint.nsr permission.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Cancel a Non-Safety Release for a complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/complaints/update/{id}": {
+            "patch": {
+                "description": "Update a complaint. All attributes optional; only provided fields change.\nmel_severity: 0 = NON-MEL (immediate AOG); 1 = A (1 day); 2 = B (3 days); 3 = C (10 days); 4 = D (120 days) — AOG after grace passes.\nNSR is not set here — it is its own flow: POST /api/v1/complaints/nsr/sign/{id} (and /nsr/unsign/{id}).\nNote: the corrective action is recorded via POST /api/v1/complaints/action-taken/create/{id} (a separate, signed step), not here.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Complaints"
+                ],
+                "summary": "Update complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API complaint update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contact/other": {
+            "get": {
+                "description": "Lists master other-people whose name/mobile_phone/email matches `q` (empty `q` = most recent). Pick one and pass its id as `other_person_id` in a takeover's other_person to reuse without re-entering the data.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contact - Other People"
+                ],
+                "summary": "Search reusable \"other people\" (non-staff) for the takeover picker",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text (name / mobile_phone / email)",
+                        "name": "q",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Max results (default 20)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Offset",
+                        "name": "offset",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contact/other/create": {
+            "post": {
+                "description": "Registers a person in the other-people master so it can be reused across takeovers. The (name, mobile_phone, email) identity must be unique.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contact - Other People"
+                ],
+                "summary": "Create a reusable \"other person\" (non-staff)",
+                "parameters": [
+                    {
+                        "description": "Other person",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.OtherPersonRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contact/other/delete/{id}": {
+            "delete": {
+                "description": "Soft-deletes a master person. Existing takeover snapshots keep their own copy of the data.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contact - Other People"
+                ],
+                "summary": "Delete a reusable \"other person\"",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Other person id",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contact/other/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contact - Other People"
+                ],
+                "summary": "Get one reusable \"other person\"",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Other person id",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contact/other/update/{id}": {
+            "patch": {
+                "description": "Replaces the name/mobile_phone/email of a master person. The new identity must not collide with another person.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contact - Other People"
+                ],
+                "summary": "Update a reusable \"other person\"",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Other person id",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Other person",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.OtherPersonRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/bulk-update": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Bulk update contacts status",
+                "parameters": [
+                    {
+                        "description": "JSON:API bulk update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactBulkUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactSimpleSuccessResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/create": {
+            "post": {
+                "description": "Create new contact user and role-specific profile.\n`data.type` must be `contact_create`.\n`role_ids` determines roles (use `role_id` only for backward compatibility). Every selected role must include its matching role-specific profile object in `attributes`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Create contact",
+                "parameters": [
+                    {
+                        "description": "JSON:API Contact create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/get-all": {
+            "get": {
+                "description": "Filter contacts by role and pilot_category. Sort values: name, -name, first_name, -first_name, last_name, -last_name, email, -email, sortkey, -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "List contacts",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role: pilot|doctor|air_rescuer|technician|flight_assistant|staff",
+                        "name": "role",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Pilot category: regular|freelance|dry_lease",
+                        "name": "pilot_category",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter doctor chief flag",
+                        "name": "chief_doctor",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter technician chief flag",
+                        "name": "chief_technician",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter responsible complaint flag",
+                        "name": "responsible_complaint",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter pilot chief flag",
+                        "name": "chief_pilot",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter IFR qualified flag",
+                        "name": "ifr_qualified",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search by username/email/name",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Limit (default 20)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Offset (default 0)",
+                        "name": "offset",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/get-all/dt": {
+            "get": {
+                "description": "Datatable response with pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "List contacts (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 1000)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Role filter",
+                        "name": "role",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Pilot category filter",
+                        "name": "pilot_category",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter doctor chief flag",
+                        "name": "chief_doctor",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter technician chief flag",
+                        "name": "chief_technician",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter responsible complaint flag",
+                        "name": "responsible_complaint",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter pilot chief flag",
+                        "name": "chief_pilot",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter IFR qualified flag",
+                        "name": "ifr_qualified",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/{user_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Get contact",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            },
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Delete contact",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            },
+            "patch": {
+                "description": "`data.type` must be `contact_update`.\nSupports updating `role_id` and `role_ids` (multiple roles) in the same request. Sending `role_ids: []` clears all assigned roles.\nOnly one role-specific profile object is allowed in `attributes`. If provided, it must match one of the contact's assigned roles.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update contact",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API Contact update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/{user_id}/chief-flags": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update chief flags",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API chief flags request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactChiefFlagsUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/{user_id}/license": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update contact license fields",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API license update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactLicenseUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/{user_id}/pilot-category": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update pilot category",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API pilot category request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactPilotCategoryUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/{user_id}/role": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update contact role",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API role update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactRoleUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/contacts/{user_id}/status": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Contacts"
+                ],
+                "summary": "Update contact active status",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID",
+                        "name": "user_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API status update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactStatusUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactSimpleSuccessResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/dul/create": {
+            "post": {
+                "description": "Possible error code: DUL_INVALID_JSON, DUL_INVALID_UUID, DUL_DATE_INVALID, DUL_VALIDATION_FAILED, DUL_CREATE_FAILED.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "DUL"
+                ],
+                "summary": "Create DUL",
+                "parameters": [
+                    {
+                        "description": "DUL create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/dul/delete/{id}": {
+            "delete": {
+                "description": "Possible error code: DUL_INVALID_UUID, DUL_DELETE_FAILED.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "DUL"
+                ],
+                "summary": "Delete DUL",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "DUL ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/dul/get-all": {
+            "get": {
+                "description": "Possible error code: DUL_LIST_FAILED.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "DUL"
+                ],
+                "summary": "List DUL grouped by base",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/info",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number alias",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size alias",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size alias",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/dul/get-all/dt": {
+            "get": {
+                "description": "Possible error code: DUL_LIST_FAILED.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "DUL"
+                ],
+                "summary": "List DUL grouped by base (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search by name/info",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/dul/get/{id}": {
+            "get": {
+                "description": "Possible error code: DUL_INVALID_UUID, DUL_NOT_FOUND.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "DUL"
+                ],
+                "summary": "Get DUL by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "DUL ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/dul/update/{id}": {
+            "patch": {
+                "description": "Possible error code: DUL_INVALID_JSON, DUL_INVALID_UUID, DUL_DATE_INVALID, DUL_VALIDATION_FAILED, DUL_NOT_FOUND, DUL_UPDATE_FAILED.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "DUL"
+                ],
+                "summary": "Update DUL",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "DUL ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "DUL update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.DULResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/duty-roster/create": {
+            "post": {
+                "description": "Unified endpoint for all base categories.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Duty Roster"
+                ],
+                "summary": "Create duty roster",
+                "parameters": [
+                    {
+                        "description": "Create request payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/duty-roster/crew": {
+            "delete": {
+                "description": "Unified crew delete endpoint by `data.id` and `roster_detail`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Duty Roster"
+                ],
+                "summary": "Remove duty roster crew assignment",
+                "parameters": [
+                    {
+                        "description": "Crew delete request payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/duty-roster/delete": {
+            "delete": {
+                "description": "Unified delete endpoint by `data.id`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Duty Roster"
+                ],
+                "summary": "Delete duty roster",
+                "parameters": [
+                    {
+                        "description": "Delete request payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterAnyDeleteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/duty-roster/get-all": {
+            "get": {
+                "description": "Combined roster list across HEMS and Base for date range and optional base filters.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Duty Roster"
+                ],
+                "summary": "List all rosters (HEMS + Base)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS base UUID",
+                        "name": "hems_base_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Base UUID",
+                        "name": "base_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by base name (contains, case-insensitive)",
+                        "name": "base_name",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Start date (YYYY-MM-DD)",
+                        "name": "from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "End date (YYYY-MM-DD)",
+                        "name": "to",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/duty-roster/get-all/dt": {
+            "get": {
+                "description": "Unified datatable endpoint. Optional `base_type` filter: `hems` or `base`.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Duty Roster"
+                ],
+                "summary": "List duty roster (datatable)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Base type filter (hems|base)",
+                        "name": "base_type",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Base UUID",
+                        "name": "base_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by base name",
+                        "name": "base_name",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Start date (YYYY-MM-DD)",
+                        "name": "from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "End date (YYYY-MM-DD)",
+                        "name": "to",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterGroupedDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/duty-roster/update": {
+            "patch": {
+                "description": "Unified update endpoint by `data.id`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Duty Roster"
+                ],
+                "summary": "Update duty roster (partial)",
+                "parameters": [
+                    {
+                        "description": "Update request payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/create": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Create EASA maintenance release (draft) for a helicopter",
+                "parameters": [
+                    {
+                        "description": "JSON:API EASA release create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/delete/{id}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Delete (void) an EASA release",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "EASA release ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseDeleteResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/get-by-complaint/{complaint_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Get the current EASA release for a complaint",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Complaint ID (UUIDv7)",
+                        "name": "complaint_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/get-by-flight/{flight_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Get the current EASA release for a flight",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/get-by-helicopter/{helicopter_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "List EASA releases for a helicopter",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Get EASA release by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "EASA release ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/sign/{id}": {
+            "post": {
+                "description": "Signs the release and closes the helicopter's open complaints. The corrective-action sign-off is re-checked at sign time: if the sign-off was invalidated since the draft was created (e.g. its complaint was reopened) it returns 422 `EASA_RELEASE_SIGNOFF_REQUIRED` and does not sign.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Sign the EASA maintenance release (closes the helicopter's open complaints)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "EASA release ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/easa-releases/update/{id}": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "EASA Releases"
+                ],
+                "summary": "Update EASA release (draft fields)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "EASA release ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API EASA release update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/facilities/create": {
+            "post": {
+                "description": "Create a facility row using one shared table. Flight-data SPO references now expect categories like `heslo-rope-label`, `heslo-rope-length`, `heslo-hook`, `hec-rope-label`, and `hec-rope-length`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Facilities"
+                ],
+                "summary": "Create facility",
+                "parameters": [
+                    {
+                        "description": "JSON:API Facility create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/facilities/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Facilities"
+                ],
+                "summary": "Delete facility",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Facility UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/facilities/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Supports one shared table with category discriminator (e.g. `heslo-rope-label`, `heslo-hook`, `hec-rope-label`).",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Facilities"
+                ],
+                "summary": "List facilities",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/type/length/weight",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by category (e.g. heslo-rope-label, heslo-hook, hec-rope-label)",
+                        "name": "category",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/facilities/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Facilities"
+                ],
+                "summary": "List facilities (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Facility category",
+                        "name": "category",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/facilities/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Facilities"
+                ],
+                "summary": "Get facility by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Facility UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/facilities/update/{uuid}": {
+            "patch": {
+                "description": "Patch facility by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Facilities"
+                ],
+                "summary": "Update facility (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Facility UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API Facility update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/federal-state/create": {
+            "post": {
+                "description": "Create a federal state row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Federal State"
+                ],
+                "summary": "Create federal state",
+                "parameters": [
+                    {
+                        "description": "JSON:API federal state create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/federal-state/delete/{id}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Federal State"
+                ],
+                "summary": "Delete federal state",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Federal State ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/federal-state/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Federal State"
+                ],
+                "summary": "List federal state",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter federal state by land UUID",
+                        "name": "land_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter federal state by land name",
+                        "name": "land_name",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/federal-state/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Federal State"
+                ],
+                "summary": "List federal state (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search by name",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter federal state by land UUID",
+                        "name": "land_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter federal state by land name",
+                        "name": "land_name",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/federal-state/update/{id}": {
+            "patch": {
+                "description": "Patch federal state by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Federal State"
+                ],
+                "summary": "Update federal state (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Federal State ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API federal state update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/attachments/create": {
+            "post": {
+                "description": "Create generic attachment relation between a file and business reference (ref_type/ref_id).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Attach file to business reference",
+                "operationId": "FileManagerCreateAttachment",
+                "parameters": [
+                    {
+                        "description": "JSON:API attachment create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/attachments/delete/{uuid}": {
+            "delete": {
+                "description": "Remove generic attachment relation by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Detach attachment relation",
+                "operationId": "FileManagerDeleteAttachment",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Attachment UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/attachments/get-all": {
+            "get": {
+                "description": "List generic attachment relations by ref_type and ref_id.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "List attachments by business reference",
+                "operationId": "FileManagerListAttachmentsByReference",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Business reference type, e.g. helicopter",
+                        "name": "ref_type",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "Business reference ID",
+                        "name": "ref_id",
+                        "in": "query",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "Optional attachment category",
+                        "name": "category",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort values: sort_order,-sort_order,created_at,-created_at,updated_at,-updated_at",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/attachments/get/{uuid}": {
+            "get": {
+                "description": "Get one generic attachment relation by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Get attachment detail",
+                "operationId": "FileManagerGetAttachment",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Attachment UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/delete": {
+            "delete": {
+                "description": "Soft-delete multiple nodes by UUID. UUID can be folder or file.\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Delete nodes (file/folder) in bulk",
+                "operationId": "FileManagerDeleteNodesBulk",
+                "parameters": [
+                    {
+                        "description": "Bulk delete request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodePurgeBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/cancel-upload": {
+            "delete": {
+                "description": "Cancel pending upload intents before file entity creation.\nThis endpoint is intended for pre-create cleanup when FE uploaded to object storage but user cancels flow.\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Cancel upload intent (bulk)",
+                "operationId": "FileManagerCancelUploadIntentBulk",
+                "parameters": [
+                    {
+                        "description": "Bulk cancel upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create": {
+            "post": {
+                "description": "Final public control-plane step after direct PUT upload to S3 (bulk contract).\nVerifies uploaded object per item from upload intent, then persists metadata+outbox durably and emits lifecycle status.\nThis endpoint does not upload binary data.\nPublic flow: POST /files/upload (intent+presign) -\u003e PUT to S3 -\u003e POST /files/create.\nfolder_id is optional; null/omitted means create in root folder.\nCanonical JSON:API data.type is \"file_manager_file_create\" (legacy \"file_manager_file\" remains accepted for backward compatibility).\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create file record from uploaded object",
+                "operationId": "FileManagerCreateFileFromUploadedObject",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for user profile image",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-aircraft-image": {
+            "post": {
+                "description": "Same as bulk create, but folder is resolved using hierarchy \"__system_root_files__\" -\u003e \"aircraft\" -\u003e \"\u003caircraft designation\u003e\".\naircraft_uuid is required per item to resolve designation.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create aircraft image file record from uploaded object",
+                "operationId": "FileManagerCreateAircraftImageFromUploadedObject",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for aircraft image",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileAircraftBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-base-image": {
+            "post": {
+                "description": "Same as bulk create, but folder is resolved using hierarchy \"__system_root_files__\" -\u003e \"bases\" -\u003e \"\u003cbase-type\u003e\" -\u003e \"\u003cbase-name\u003e\".\nbase_uuid is required per item.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create base image file record from uploaded object",
+                "operationId": "FileManagerCreateBaseImageFromUploadedObject",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for base image",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileBaseBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-dul-image": {
+            "post": {
+                "description": "Finalize uploaded DUL image file(s) from upload intent.\nIf dul_uuid is provided, file is created under DUL folder hierarchy.\nIf dul_uuid is omitted, file is still created (unassigned), then can be attached during /api/v1/dul/create via file_uuid.\nPossible status: 201 (all success), 207 (partial success), 400 (invalid json/create failed), 401 (unauthorized), 403 (forbidden), 404 (dul or file resources not found), 409 (upload-intent conflict), 422 (validation), 503 (DUL or file-manager service unavailable).\nPossible error code: INVALID_REQUEST, USER_UNAUTHORIZED, FORBIDDEN_ACCESS, FILE_MANAGER_VALIDATION_FAILED, FILE_MANAGER_FILE_NOT_FOUND, FILE_MANAGER_UPLOAD_INTENT_NOT_FOUND, FILE_MANAGER_UPLOAD_INTENT_CONFLICT, DUL_NOT_FOUND, FILE_MANAGER_STORAGE_UNAVAILABLE, FILE_MANAGER_QUEUE_UNAVAILABLE, FILE_MANAGER_ATTACHMENT_SERVICE_UNAVAILABLE, FILE_MANAGER_ACTION_FAILED.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create DUL image file record from uploaded object",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for DUL image",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileDULBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-from-template": {
+            "post": {
+                "description": "Copies a helicopter template file into a new draft file and returns a Collabora/WOPI write session for the newly created file.\nThis endpoint always marks the created file as `is_template=false` because the result is a normal working document, not a reusable template.\nThe source template must be a helicopter file that belongs to the same `helicopter_id` provided in the request.\n`template_uuid` is the helicopter-file UUID, not the file UUID.\nRequest fields: `template_uuid`, `helicopter_id`, optional `takeover_id`, and `name`.\nSuccess response includes the new `file_id`, Collabora editor action URL, an access token, and the token TTL in milliseconds.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create file from template and start a WOPI edit session",
+                "parameters": [
+                    {
+                        "description": "Create-from-template payload",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTemplateCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-mission-file": {
+            "post": {
+                "description": "Materializes uploaded objects into folder \"missions/\u003cmission-uuid\u003e\", creates attachments (ref_type=mission), and links them to the mission so they appear in GET mission.\nmission_uuid is required per item.\nPossible error code: MISSION_FILE_INVALID_JSON, MISSION_FILE_VALIDATION, MISSION_FILE_INVALID_MISSION_UUID, MISSION_FILE_MISSION_NOT_FOUND, MISSION_FILE_SERVICE_UNAVAILABLE, MISSION_FILE_ACTION_FAILED, FILE_MANAGER_UPLOAD_INTENT_NOT_FOUND, FILE_MANAGER_STORAGE_UNAVAILABLE, FILE_MANAGER_ACTION_FAILED.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create mission file record from uploaded object",
+                "operationId": "FileManagerCreateMissionFileFromUploadedObject",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for mission file",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileMissionBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-takeover-file": {
+            "post": {
+                "description": "Finalize uploaded takeover file(s) from upload intent. The takeover relation is attached later from file_id during takeover create/update.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create takeover file node from uploaded object",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for takeover file",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTakeoverBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/create-user-image": {
+            "post": {
+                "description": "Same as bulk create, but folder is resolved using hierarchy \"__system_root_files__\" -\u003e \"user\" -\u003e \"\u003cusername\u003e-\u003cuser-uuid\u003e\".\nuser_uuid is required per item to resolve target user folder.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create user profile image file record from uploaded object",
+                "operationId": "FileManagerCreateUserImageFromUploadedObject",
+                "parameters": [
+                    {
+                        "description": "Bulk create payload for user profile image",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/get/{uuid}": {
+            "get": {
+                "description": "Return file metadata by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Get file detail",
+                "operationId": "FileManagerGetFile",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "File UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileDetailResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/update/{uuid}": {
+            "patch": {
+                "description": "Update file metadata by UUID (rename and/or move folder).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Update file entity (rename and/or move)",
+                "operationId": "FileManagerUpdateFileEntity",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "File UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API file manager file update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload": {
+            "post": {
+                "description": "Control-plane endpoint to create upload intents and presigned PUT URLs for direct upload to S3 (bulk contract).\nBinary does not flow through backend upload endpoint.\nAfter successful PUT to S3, call POST /api/v1/file-manager/files/create with upload_intent_uuid.\nPresigned URL TTL is controlled by backend storage config.\nBulk payload accepts one or many items. Response is item-based and supports partial success.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents + presigned PUT URLs",
+                "operationId": "FileManagerRequestUploadIntent",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload-aircraft-image": {
+            "post": {
+                "description": "Same flow as file upload intent, but dedicated for aircraft image drag-drop flow.\nUse together with /api/v1/file-manager/files/create-aircraft-image to force target folder \"aircraft\".",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents for aircraft drag-drop images",
+                "operationId": "FileManagerRequestAircraftImageUploadIntent",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload-base-image": {
+            "post": {
+                "description": "Same flow as file upload intent, but dedicated for base image flow.\nUse together with /api/v1/file-manager/files/create-base-image to force target folder under bases hierarchy.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents for base images",
+                "operationId": "FileManagerRequestBaseImageUploadIntent",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload-dul-image": {
+            "post": {
+                "description": "Dedicated upload-intent endpoint for DUL image flow.\nPossible status: 201 (all success), 207 (partial success), 400 (invalid json), 401 (unauthorized), 403 (forbidden), 422 (validation), 503 (storage/queue/upload-intent service unavailable).\nPossible error code: INVALID_REQUEST, USER_UNAUTHORIZED, FORBIDDEN_ACCESS, FILE_MANAGER_VALIDATION_FAILED, FILE_MANAGER_STORAGE_UNAVAILABLE, FILE_MANAGER_QUEUE_UNAVAILABLE, FILE_MANAGER_UPLOAD_INTENT_UNAVAILABLE, FILE_MANAGER_ACTION_FAILED.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents for DUL images",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload-mission-file": {
+            "post": {
+                "description": "Dedicated upload-intent endpoint for mission file flow.\nUse together with /api/v1/file-manager/files/create-mission-file to attach the file to a mission.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents for mission files",
+                "operationId": "FileManagerRequestMissionFileUploadIntent",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload-takeover-file": {
+            "post": {
+                "description": "Dedicated upload-intent endpoint for takeover file flow.\nUse together with /api/v1/file-manager/files/create-takeover-file to persist the takeover file relation.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents for takeover files",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/upload-user-image": {
+            "post": {
+                "description": "Same flow as file upload intent, but dedicated for user profile image flow.\nUse together with /api/v1/file-manager/files/create-user-image to force target folder under user hierarchy.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Request upload intents for user profile images",
+                "operationId": "FileManagerRequestUserImageUploadIntent",
+                "parameters": [
+                    {
+                        "description": "Bulk upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/files/{fileId}/edit-session": {
+            "get": {
+                "description": "Returns a Collabora/WOPI write session for an already existing file that belongs to the authenticated user's takeover scope or to the authenticated user as an unattached draft.\nThis endpoint does not create or copy files. It only resolves the file, checks access, and mints a new access token.\nUse this when reopening an existing file for editing.\nPath param `fileId` must be a valid UUIDv7.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Start a WOPI edit session for an existing file",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "File UUID (UUIDv7)",
+                        "name": "fileId",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "403": {
+                        "description": "Forbidden",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/folders/create": {
+            "post": {
+                "description": "Create one folder metadata node under root or under provided parent_id.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Create folder node",
+                "operationId": "FileManagerCreateFolder",
+                "parameters": [
+                    {
+                        "description": "JSON:API file manager folder create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/folders/get/{uuid}": {
+            "get": {
+                "description": "Return folder metadata by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Get folder detail",
+                "operationId": "FileManagerGetFolder",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Folder UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderDetailResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/folders/update/{uuid}": {
+            "patch": {
+                "description": "Update folder metadata by UUID (rename and/or move parent).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Update folder node",
+                "operationId": "FileManagerUpdateFolder",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Folder UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API file manager folder update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/get-all": {
+            "get": {
+                "description": "Return merged direct children (folders + files) for optional parent_uuid (non-recursive).\nIf parent_uuid is omitted, response returns root level nodes.\nIf search is provided, performs a global name search across all folders and files (parent_uuid is ignored).",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "List merged explorer nodes",
+                "operationId": "FileManagerListMergedExplorerNodes",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Parent folder UUID",
+                        "name": "parent_uuid",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search keyword (global name search across all folders and files)",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerNodeListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/move": {
+            "patch": {
+                "description": "Unified move endpoint. Each item UUID can be either folder UUID or file UUID.\ndestination_folder_uuid null/empty means move to root.\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Move nodes (file/folder) in bulk",
+                "operationId": "FileManagerMoveNodesBulk",
+                "parameters": [
+                    {
+                        "description": "Bulk move request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodeMoveBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/purge-delete": {
+            "delete": {
+                "description": "Permanently delete multiple trashed nodes by UUID. UUID can be folder or file.\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Purge nodes (file/folder) from trash in bulk",
+                "operationId": "FileManagerPurgeNodesBulkFromTrash",
+                "parameters": [
+                    {
+                        "description": "Bulk purge request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodePurgeBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerPurgeNodeBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/restore": {
+            "patch": {
+                "description": "Restore multiple trashed nodes by UUID to original location.\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "Restore nodes (file/folder) in bulk",
+                "operationId": "FileManagerRestoreNodesBulk",
+                "parameters": [
+                    {
+                        "description": "Bulk restore request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodePurgeBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/file-manager/trash/get-all": {
+            "get": {
+                "description": "Return merged trashed nodes (folders + files) for trash explorer.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "File Manager"
+                ],
+                "summary": "List merged trash items",
+                "operationId": "FileManagerListMergedTrashItems",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort values: deleted_at,-deleted_at,name,-name,type,-type,size_bytes,-size_bytes",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerTrashListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/create": {
+            "post": {
+                "description": "Create fleet status with maintenance schedules and file attachments.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "Create fleet status",
+                "parameters": [
+                    {
+                        "description": "Fleet status create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/delete/{id}": {
+            "delete": {
+                "description": "Soft delete fleet status by ID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "Delete fleet status",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Fleet status ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/get-all": {
+            "get": {
+                "description": "Lists every helicopter from the master, each with its latest fleet status (or empty data when it has none). Paginated by helicopter.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "List fleet status",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "default": 1,
+                        "description": "Page number",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 20,
+                        "description": "Page size",
+                        "name": "page_size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search helicopters by designation/identifier/type",
+                        "name": "filter",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort helicopters, example: designation",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by operational status; comma-separated for multiple (e.g. available,booked). Values: available, booked, aog, mcf",
+                        "name": "status",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by helicopter ID (UUIDv7); combined with status uses AND logic",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/get-all/dt": {
+            "get": {
+                "description": "Lists every helicopter from the master, each with its latest fleet status (or empty data when it has none). Paginated by helicopter.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "List fleet status (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "default": 1,
+                        "description": "Datatable draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 0,
+                        "description": "Datatable start offset",
+                        "name": "start",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 10,
+                        "description": "Datatable page length",
+                        "name": "length",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search helicopters by designation/identifier/type",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort helicopters, example: designation",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by operational status; comma-separated for multiple (e.g. available,booked). Values: available, booked, aog, mcf",
+                        "name": "status",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by helicopter ID (UUIDv7); combined with status uses AND logic",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/get-by-helicopter/{helicopter_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "Get latest fleet status by helicopter ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "Get fleet status by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Fleet status ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/history/{helicopter_id}": {
+            "get": {
+                "description": "Unified timeline: maintenance servicing events merged with complaint/MEL/NSR/action/MCF/EASA/AOG action events, newest first.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "List fleet history (timeline) by helicopter",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "integer",
+                        "default": 1,
+                        "description": "Page number",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "default": 20,
+                        "description": "Page size",
+                        "name": "page_size",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetHistoryListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/mark-serviced/{id}": {
+            "post": {
+                "description": "Move current maintenance schedules into service logs, then clear active schedules.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "Mark fleet status serviced",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Fleet status ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusMarkServicedResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fleet-status/update/{id}": {
+            "patch": {
+                "description": "Update fleet status by ID with full replacement for schedules and files.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Fleet Status"
+                ],
+                "summary": "Update fleet status",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Fleet status ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Fleet status update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flight-data/create": {
+            "post": {
+                "description": "Create a flight data row.\nRequired field: `mission_id`. `co_pilot_id` is optional.\nSwagger request example shows the complete common payload for an `SPO` mission. `SPO` is the default example shape, and for other mission types (`CAT` and `NCO`) you do not need to send the `hec`, `heslo`, or `logging` blocks. `rotor_brake_cycle` is optional for `SPO`, `CAT`, and `NCO`.\nSPO facility references must point to facilities with categories: `heslo_rope_label_id -\u003e heslo-rope-label`, `heslo.slings -\u003e heslo-rope-length`, `logging.slings -\u003e heslo-hook`, `hec.flights -\u003e hec-rope-label`, and `hec.slings -\u003e hec-rope-length`.\nSPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.\nExample request: {\"data\":{\"type\":\"flight_data_create\",\"attributes\":{\"mission_id\":\"019d6774-98e8-7fba-9ef4-3795c0da8a13\"}}}",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Mission - Flight Data"
+                ],
+                "summary": "Create flight data",
+                "parameters": [
+                    {
+                        "description": "JSON:API flight data create request. Example is for SPO; CAT/NCO can omit SPO-only blocks and other optional fields.",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flight-data/delete/{id}": {
+            "delete": {
+                "description": "Soft delete flight data by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Mission - Flight Data"
+                ],
+                "summary": "Delete flight data by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight Data UUID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flight-data/get-all": {
+            "get": {
+                "description": "List flight data rows. Supports `date` for exact flight take-off date filtering (`YYYY-MM-DD`), plus `mission_id` and `flight_data_id` filters.\nSPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Mission - Flight Data"
+                ],
+                "summary": "List flight data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Filter by flight take-off date (YYYY-MM-DD)",
+                        "name": "date",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by mission UUID",
+                        "name": "mission_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight-data UUID",
+                        "name": "flight_data_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flight-data/get-all/dt": {
+            "get": {
+                "description": "Datatable-friendly list of flight data rows. Supports `date` for exact flight take-off date filtering (`YYYY-MM-DD`), plus `mission_id` and `flight_data_id` filters.\nSame payload shape as `get-all`, but with DataTables paging params (`start`, `length`, `draw`).\nSPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Mission - Flight Data"
+                ],
+                "summary": "List flight data (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "DataTables draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Paging start offset",
+                        "name": "start",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Paging length",
+                        "name": "length",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight take-off date (YYYY-MM-DD)",
+                        "name": "date",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by mission UUID",
+                        "name": "mission_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight-data UUID",
+                        "name": "flight_data_id",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flight-data/get/{id}": {
+            "get": {
+                "description": "Get flight data detail by ID. Path `id` can be mission UUID, flight-data UUID, or flight UUID.\nSPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Mission - Flight Data"
+                ],
+                "summary": "Get flight data by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Mission UUID / Flight Data UUID / Flight UUID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flight-data/update/{id}": {
+            "patch": {
+                "description": "Update a flight data row by UUID.\nRequired field: `mission_id`. `co_pilot_id` is optional.\nSwagger request example uses the same SPO-shaped payload as create, but this endpoint updates an existing flight-data row.\nSPO facility references must point to facilities with categories: `heslo_rope_label_id -\u003e heslo-rope-label`, `heslo.slings -\u003e heslo-rope-length`, `logging.slings -\u003e heslo-hook`, `hec.flights -\u003e hec-rope-label`, and `hec.slings -\u003e hec-rope-length`.\nFor frontend usage, send only the fields that need to change; omitted fields stay unchanged. `SPO` is the default example shape, and for `CAT`/`NCO` you do not need to send the `hec`, `heslo`, or `logging` blocks. `rotor_brake_cycle` is optional for `SPO`, `CAT`, and `NCO`.\nSPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.\nExample request: {\"data\":{\"type\":\"flight_data_create\",\"attributes\":{\"mission_id\":\"019d6774-98e8-7fba-9ef4-3795c0da8a13\"}}}",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Mission - Flight Data"
+                ],
+                "summary": "Update flight data by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight Data UUID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API flight data update request. Send only fields you want to change; omit the rest.",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flights/get": {
+            "get": {
+                "description": "Returns flights assigned to current auth user, including workflow steps (`duty_roster`, `reserve_ac`, `mission`, `after_flight_inspection`, `fm_report`).\nEach step includes `status`, `completed_at`, and `completed_by` for consistent FE rendering.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight"
+                ],
+                "summary": "Get flights for current auth user (from duty roster assignment)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightListResponse"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/flights/get-all": {
+            "get": {
+                "description": "Supports `search`, `filter[search]`, `sort`, `page[number]`, `page[size]`, `page`, `size`, and `limit`.\nSupports `date` and `filter[date]` for exact flight date filtering (`YYYY-MM-DD`).\nReturns paginated flights with workflow steps (`takeover`, `mission`, `after_flight_inspection`, `fm_report`).\nEach step includes `status`, `completed_at`, and `completed_by` for consistent FE rendering.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight"
+                ],
+                "summary": "List flights",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (JSON:API style)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight date (YYYY-MM-DD)",
+                        "name": "date",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight date (YYYY-MM-DD) (JSON:API style)",
+                        "name": "filter[date]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort field",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/complete/{flight_id}": {
+            "post": {
+                "description": "Mark an FM report as completed for a flight. Once completed, the report becomes read-only and flight data edits are locked. Requires a verified security PIN: send the one-time token from POST /auth/pin/verify (action 1a75135b-430a-4592-83e1-6d27814185af) in the X-PIN-Verification-Token header.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Complete FM report",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "One-time security-PIN action token",
+                        "name": "X-PIN-Verification-Token",
+                        "in": "header",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportResponse"
+                        }
+                    },
+                    "202": {
+                        "description": "PIN verification required",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/get-all": {
+            "get": {
+                "description": "Returns a paginated list of FM reports. Supports `search`, `filter[search]`, `filter[flight_id]`, `filter[takeover_id]`, `filter[flight_inspection_id]`, `filter[flight_date]`, `filter[has_engine1_gpc_n1]`, `filter[has_engine1_ptc_n2]`, `filter[has_engine2_gpc_n1]`, `filter[has_engine2_ptc_n2]`, `sort`, `page[number]`, `page[size]`, `page`, `size`, and `limit`.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "List FM reports",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (JSON:API style)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight ID",
+                        "name": "filter[flight_id]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by takeover ID",
+                        "name": "filter[takeover_id]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight inspection ID",
+                        "name": "filter[flight_inspection_id]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight date (YYYY-MM-DD)",
+                        "name": "filter[flight_date]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter reports with or without engine1_gpc_n1",
+                        "name": "filter[has_engine1_gpc_n1]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter reports with or without engine1_ptc_n2",
+                        "name": "filter[has_engine1_ptc_n2]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter reports with or without engine2_gpc_n1",
+                        "name": "filter[has_engine2_gpc_n1]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "Filter reports with or without engine2_ptc_n2",
+                        "name": "filter[has_engine2_ptc_n2]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order: flight_date, -flight_date, created_at, -created_at, updated_at, -updated_at, engine1_gpc_n1, -engine1_gpc_n1, engine1_ptc_n2, -engine1_ptc_n2, engine2_gpc_n1, -engine2_gpc_n1, engine2_ptc_n2, -engine2_ptc_n2",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/get/{flight_id}": {
+            "get": {
+                "description": "Returns a complete FM report for a flight. The persisted table keeps only the report keys; the response preloads flight, missions, flight inspection, and after-flight inspection details. It also embeds `fleet_status` (next inspection / maintenance schedules + base hours, component summary, EASA maintenance release) — a snapshot frozen when the report was created at after-flight inspection, so later complaints / maintenance changes do not alter a historical report. `fleet_status` is omitted when the helicopter has no fleet status.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Get FM report by flight ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/update/{flight_id}": {
+            "patch": {
+                "description": "Update only the engine metric fields for an existing FM report. All other FM report fields stay read-only on this endpoint. The response mirrors the GET FM report and embeds the frozen `fleet_status` snapshot (next inspection / maintenance schedules + base hours, component summary, EASA maintenance release).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Update FM report metrics",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API FM report update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FMReportUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/{id}": {
+            "delete": {
+                "description": "Soft-delete an FM report by ID. Requires a verified security PIN.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Delete FM report",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "FM Report ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "One-time security-PIN action token",
+                        "name": "X-PIN-Verification-Token",
+                        "in": "header",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "204": {
+                        "description": "No Content"
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/{id}/attachments": {
+            "post": {
+                "description": "After uploading the file to the presigned URL (from /attachments/upload-intent), call this endpoint with the upload_intent_uuid, name, and category to create the file node and attach it to the FM report. Valid categories: additional_fm_report, briefing, weight_balance, ofp.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Create FM report attachment from upload intent",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "FM Report ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "body with upload_intent_uuid, name, and category",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "type": "object"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "type": "object"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/{id}/attachments/upload-intent": {
+            "post": {
+                "description": "Returns a presigned PUT URL and upload_intent_uuid. After uploading the file to the presigned URL, call POST /fm-reports/{id}/attachments with the upload_intent_uuid to create the file node and attach it to the report.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Request upload intent for FM report attachment",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "FM Report ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "body with name, content_type, size_bytes",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "type": "object"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "type": "object"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/fm-reports/{id}/attachments/{att_id}": {
+            "delete": {
+                "description": "Remove a specific attachment from an FM report. Verifies ownership before deletion.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight Report"
+                ],
+                "summary": "Delete attachment from FM report",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "FM Report ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "Attachment ID (UUIDv7)",
+                        "name": "att_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "204": {
+                        "description": "No Content"
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/forces-present/create": {
+            "post": {
+                "description": "Create a forces present row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Forces Present"
+                ],
+                "summary": "Create forces present",
+                "parameters": [
+                    {
+                        "description": "JSON:API forces present create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/forces-present/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Forces Present"
+                ],
+                "summary": "Delete forces present",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Forces Present UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/forces-present/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Forces Present"
+                ],
+                "summary": "List forces present",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/note",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/forces-present/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Forces Present"
+                ],
+                "summary": "List forces present (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/forces-present/update/{uuid}": {
+            "patch": {
+                "description": "Patch forces present by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Forces Present"
+                ],
+                "summary": "Update forces present (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Forces Present UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API forces present update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/health-insurance-companies/create": {
+            "post": {
+                "description": "Create a health insurance company row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Health Insurance Companies"
+                ],
+                "summary": "Create health insurance company",
+                "parameters": [
+                    {
+                        "description": "JSON:API health insurance company create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/health-insurance-companies/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Health Insurance Companies"
+                ],
+                "summary": "Delete health insurance company",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Health Insurance Company UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/health-insurance-companies/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, state, -state, address, -address, mobile_number, -mobile_number, email, -email, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Health Insurance Companies"
+                ],
+                "summary": "List health insurance companies",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/state/address/mobile/email",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/health-insurance-companies/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Health Insurance Companies"
+                ],
+                "summary": "List health insurance companies (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/health-insurance-companies/update/{uuid}": {
+            "patch": {
+                "description": "Patch health insurance company by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Health Insurance Companies"
+                ],
+                "summary": "Update health insurance company (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Health Insurance Company UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API health insurance company update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/cancel-upload": {
+            "post": {
+                "description": "Cancel pending upload intents from helicopter file upload flow.\nBulk payload accepts one or many items.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "Cancel helicopter file upload intent (bulk)",
+                "parameters": [
+                    {
+                        "description": "Bulk helicopter file cancel upload intent request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/create": {
+            "post": {
+                "description": "Create helicopter file template record from upload intent.\nSection allowed values: `bfi` (Before First Flight Inspection), `fpwb` (Flight Preparation and WB), `afi` (After Last Flight Inspection).\nRequired attributes: `section`, `helicopter_id`, `upload_intent_uuid`, `file_name`.\nOptional attributes: `position`, `is_required`, `folder_uuid` (if omitted, file is created in root folder).\nWhen `position` is omitted (or \u003c= 0), backend auto-assigns next position per `helicopter_id + section`.\nIf file name already exists in target folder, existing file is reused and attached.\nSupports single and bulk payload.\nSingle payload example: `{\"data\":{\"type\":\"helicopter_file_create\",\"attributes\":{\"section\":\"bfi\",\"position\":1,\"is_required\":true,\"helicopter_id\":\"019d6771-5fb5-7337-837f-bc5ed85181a1\",\"upload_intent_uuid\":\"019d6d0d-2de2-7db1-80a2-2862d43af620\",\"file_name\":\"A.pdf\"}}}`\nBulk payload example: `{\"data\":[{\"type\":\"helicopter_file_create\",\"attributes\":{\"section\":\"bfi\",\"position\":1,\"is_required\":true,\"helicopter_id\":\"019d6771-5fb5-7337-837f-bc5ed85181a1\",\"upload_intent_uuid\":\"019d6d0d-2de2-7db1-80a2-2862d43af620\",\"file_name\":\"A.pdf\"}}]}`\nNote: OpenAPI 2.0 cannot express object-or-array union in one schema; request schema below represents bulk envelope.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "Create helicopter file",
+                "parameters": [
+                    {
+                        "description": "JSON:API helicopter file create request (single object or bulk array)",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCreateBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/delete": {
+            "delete": {
+                "description": "Delete helicopter file template record",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "Delete helicopter file",
+                "parameters": [
+                    {
+                        "description": "JSON:API helicopter file delete request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileDeleteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/get-all": {
+            "get": {
+                "description": "List helicopter file template records grouped by helicopter.\nPagination is applied per helicopter group (not per file row), so one helicopter's files stay in the same page.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "List helicopter files",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (fallback)",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort field",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/get/{helicopter_id}": {
+            "get": {
+                "description": "Return helicopter file template collection for selected helicopter",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "Get helicopter files by helicopter ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/update": {
+            "patch": {
+                "description": "Update a helicopter file template record.\nSection allowed values: `bfi` (Before First Flight Inspection), `fpwb` (Flight Preparation and WB), `afi` (After Last Flight Inspection).\nOptional attributes: `section`, `position`, `is_required`, `helicopter_id`, `file_name`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "Update helicopter file",
+                "parameters": [
+                    {
+                        "description": "JSON:API helicopter file update request (single object or bulk array)",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUpdateBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUpdateBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-files/upload": {
+            "post": {
+                "description": "Control-plane endpoint for helicopter file upload intent + presigned URL flow.\nPublic flow: POST /api/v1/helicopter-files/upload -\u003e PUT to presigned URL -\u003e POST /api/v1/helicopter-files/create.\nCanonical type is `helicopter_file_upload`.\n`required_headers` must be sent exactly as returned when doing PUT to `upload_url`.\nExample `required_headers`: `{\"content-type\":\"application/pdf\",\"x-amz-acl\":\"private\"}`\nSupports single and bulk payload.\nSingle payload example: `{\"data\":{\"type\":\"helicopter_file_upload\",\"attributes\":{\"name\":\"A.pdf\",\"content_type\":\"application/pdf\",\"size_bytes\":12345}}}`\nBulk payload example: `{\"data\":[{\"type\":\"helicopter_file_upload\",\"attributes\":{\"name\":\"A.pdf\",\"content_type\":\"application/pdf\",\"size_bytes\":12345}}]}`\nNote: OpenAPI 2.0 cannot express object-or-array union in one schema; request schema below represents bulk envelope.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Master File"
+                ],
+                "summary": "Request upload intents + presigned PUT URLs (helicopter file)",
+                "parameters": [
+                    {
+                        "description": "Helicopter file upload intent request (single object or bulk array)",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUploadBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResponse"
+                        }
+                    },
+                    "207": {
+                        "description": "Multi-Status",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-usage/create": {
+            "post": {
+                "description": "Create helicopter usage counters for a helicopter.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Helicopter Usage"
+                ],
+                "summary": "Create helicopter usage",
+                "parameters": [
+                    {
+                        "description": "JSON:API helicopter usage create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-usage/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Helicopter Usage"
+                ],
+                "summary": "Delete helicopter usage",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter Usage UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-usage/get-all": {
+            "get": {
+                "description": "JSON:API list without pagination. Sort values: helicopter_id, -helicopter_id, total_landing, -total_landing, total_airframe_hours, -total_airframe_hours, total_airframe_cycles, -total_airframe_cycles, total_engine_1_hours, -total_engine_1_hours, total_engine_1_gpc_ng_n1, -total_engine_1_gpc_ng_n1, total_engine_1_ptc_nf_n2, -total_engine_1_ptc_nf_n2, total_engine_1_ccc, -total_engine_1_ccc, total_engine_2_hours, -total_engine_2_hours, total_engine_2_gpc_ng_n1, -total_engine_2_gpc_ng_n1, total_engine_2_ptc_nf_n2, -total_engine_2_ptc_nf_n2, total_engine_2_ccc, -total_engine_2_ccc, total_flight_report, -total_flight_report, total_hook_release, -total_hook_release, total_rotor_brake_cycle, -total_rotor_brake_cycle, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Helicopter Usage"
+                ],
+                "summary": "List helicopter usage",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by helicopter or usage ID",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-usage/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Helicopter Usage"
+                ],
+                "summary": "List helicopter usage (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-usage/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Helicopter Usage"
+                ],
+                "summary": "Get helicopter usage",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter Usage UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopter-usage/update/{uuid}": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Helicopter - Helicopter Usage"
+                ],
+                "summary": "Update helicopter usage (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter Usage UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API helicopter usage update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/create": {
+            "post": {
+                "description": "Create a helicopter configuration row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "Create helicopter",
+                "parameters": [
+                    {
+                        "description": "JSON:API Helicopter create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/delete/{id}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "Delete helicopter",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: designation, -designation, sortkey, -sortkey.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "List helicopters",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by designation/identifier/type",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by operational status; comma-separated for multiple (e.g. available,booked). Values: available, booked, aog, mcf",
+                        "name": "filter[status]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "List helicopters (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by operational status; comma-separated for multiple (e.g. available,booked). Values: available, booked, aog, mcf",
+                        "name": "status",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "Get helicopter by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/update/{id}": {
+            "patch": {
+                "description": "Patch helicopter by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "Update helicopter (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API Helicopter update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/helicopters/{id}/reports/next-number": {
+            "post": {
+                "description": "Returns report number format \u003cidentifier\u003e-NNNN (example: SN0901-0001). The identifier is used as the report-code prefix and the numeric suffix is auto-incremented by backend per helicopter.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Facility - Helicopters"
+                ],
+                "summary": "Generate next helicopter report number",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterNextReportNumberResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation-category/create": {
+            "post": {
+                "description": "Create a HEMS operation category.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - Category"
+                ],
+                "summary": "Create HEMS operation category",
+                "parameters": [
+                    {
+                        "description": "JSON:API HEMS operation category create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation-category/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - Category"
+                ],
+                "summary": "Delete HEMS operation category",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operation category UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation-category/get-all": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - Category"
+                ],
+                "summary": "List HEMS operation categories",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/type",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation-category/get-all/dt": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - Category"
+                ],
+                "summary": "List HEMS operation categories (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation-category/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - Category"
+                ],
+                "summary": "Get HEMS operation category by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operation category UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation-category/update/{uuid}": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - Category"
+                ],
+                "summary": "Update HEMS operation category (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operation category UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API HEMS operation category update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation/create": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operation"
+                ],
+                "summary": "Create HEMS operation",
+                "parameters": [
+                    {
+                        "description": "JSON:API HEMS operation create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operation"
+                ],
+                "summary": "Delete HEMS operation",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operation UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation/get-all": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operation"
+                ],
+                "summary": "List HEMS operations",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by date",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation/get-all/dt": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operation"
+                ],
+                "summary": "List HEMS operations (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operation"
+                ],
+                "summary": "Get HEMS operation by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operation UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operation/update/{uuid}": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operation"
+                ],
+                "summary": "Update HEMS operation (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operation UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API HEMS operation update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operational-data/create": {
+            "post": {
+                "description": "Create a HEMS operational data record.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operational Data"
+                ],
+                "summary": "Create HEMS operational data",
+                "parameters": [
+                    {
+                        "description": "JSON:API HEMS operational data create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operational-data/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operational Data"
+                ],
+                "summary": "Delete HEMS operational data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operational data UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operational-data/get-all": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operational Data"
+                ],
+                "summary": "List HEMS operational data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by location/notes/additional_info/terrain_index",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operational-data/get-all/dt": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operational Data"
+                ],
+                "summary": "List HEMS operational data (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operational-data/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operational Data"
+                ],
+                "summary": "Get HEMS operational data by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operational data UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hems-operational-data/update/{uuid}": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Operation - HEMS Operational Data"
+                ],
+                "summary": "Update HEMS operational data (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "HEMS operational data UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API HEMS operational data update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hospital/create": {
+            "post": {
+                "description": "Create a hospital row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Hospital"
+                ],
+                "summary": "Create hospital",
+                "parameters": [
+                    {
+                        "description": "JSON:API hospital create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hospital/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Hospital"
+                ],
+                "summary": "Delete hospital",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Hospital UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hospital/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, hospital_name, -hospital_name, sortkey, -sortkey, address, -address, landline_number, -landline_number, mobile_number, -mobile_number, email, -email, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Hospital"
+                ],
+                "summary": "List hospital",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by hospital name/address/contact",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hospital/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Hospital"
+                ],
+                "summary": "List hospital (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/hospital/update/{uuid}": {
+            "patch": {
+                "description": "Patch hospital by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Hospital"
+                ],
+                "summary": "Update hospital (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Hospital UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API hospital update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/icao/create": {
+            "post": {
+                "description": "Create an ICAO row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - ICAO"
+                ],
+                "summary": "Create ICAO",
+                "parameters": [
+                    {
+                        "description": "JSON:API ICAO create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/icao/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - ICAO"
+                ],
+                "summary": "Delete ICAO",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "ICAO UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/icao/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: icao_code, -icao_code, sortkey, -sortkey, address, -address, landline_number, -landline_number, mobile_number, -mobile_number, email, -email, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - ICAO"
+                ],
+                "summary": "List ICAO",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by icao_code/address/contact",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/icao/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - ICAO"
+                ],
+                "summary": "List ICAO (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAODataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/icao/update/{uuid}": {
+            "patch": {
+                "description": "Patch ICAO by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - ICAO"
+                ],
+                "summary": "Update ICAO (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "ICAO UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API ICAO update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/insurance-patient-data/create": {
+            "post": {
+                "description": "Create an InsurancePatientData record.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - InsurancePatientData"
+                ],
+                "summary": "Create insurance patient data",
+                "parameters": [
+                    {
+                        "description": "JSON:API InsurancePatientData create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/insurance-patient-data/delete/{uuid}": {
+            "delete": {
+                "description": "Soft delete InsurancePatientData by ID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - InsurancePatientData"
+                ],
+                "summary": "Delete insurance patient data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "InsurancePatientData UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/insurance-patient-data/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - InsurancePatientData"
+                ],
+                "summary": "List insurance patient data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/insurance-patient-data/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - InsurancePatientData"
+                ],
+                "summary": "List insurance patient data (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/insurance-patient-data/get/{uuid}": {
+            "get": {
+                "description": "Get a single InsurancePatientData record by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - InsurancePatientData"
+                ],
+                "summary": "Get insurance patient data by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "InsurancePatientData UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/insurance-patient-data/update/{uuid}": {
+            "patch": {
+                "description": "Patch InsurancePatientData by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - InsurancePatientData"
+                ],
+                "summary": "Update insurance patient data (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "InsurancePatientData UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API InsurancePatientData update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/land/create": {
+            "post": {
+                "description": "Create a land row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Land"
+                ],
+                "summary": "Create land",
+                "parameters": [
+                    {
+                        "description": "JSON:API land create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LandCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LandResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/land/delete/{id}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Land"
+                ],
+                "summary": "Delete land",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Land ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/land/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Land"
+                ],
+                "summary": "List land",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LandListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/land/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Land"
+                ],
+                "summary": "List land (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 1000)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LandDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/land/update/{id}": {
+            "patch": {
+                "description": "Patch land by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Hospital - Land"
+                ],
+                "summary": "Update land (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Land ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API land update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LandUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.LandResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/master-settings/create": {
+            "post": {
+                "description": "Create a master settings row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Master Settings"
+                ],
+                "summary": "Create master settings",
+                "parameters": [
+                    {
+                        "description": "JSON:API master settings create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/master-settings/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Master Settings"
+                ],
+                "summary": "Delete master settings",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Master Settings UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Resource"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/master-settings/get": {
+            "get": {
+                "description": "Return singleton master settings object (latest active row).",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Master Settings"
+                ],
+                "summary": "Get current master settings",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/master-settings/sso/microsoft": {
+            "get": {
+                "description": "Get Microsoft Entra SSO settings from master settings.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Master Settings"
+                ],
+                "summary": "Get Microsoft Entra SSO settings",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            },
+            "put": {
+                "description": "Create or update Microsoft Entra SSO settings as master settings.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Master Settings"
+                ],
+                "summary": "Upsert Microsoft Entra SSO settings",
+                "parameters": [
+                    {
+                        "description": "JSON:API Microsoft Entra SSO upsert request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/master-settings/update/{uuid}": {
+            "patch": {
+                "description": "Patch master settings by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Master Settings"
+                ],
+                "summary": "Update master settings (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Master Settings UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API master settings update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mcf/get-by-helicopter/{helicopter_id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "MCF"
+                ],
+                "summary": "List MCFs for a helicopter",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mcf/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "MCF"
+                ],
+                "summary": "Get MCF by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "MCF ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mcf/set/{helicopter_id}": {
+            "post": {
+                "description": "Toggles and edits a helicopter's MCF. `active:true` (or omitted) ACTIVATES/EDITS it — creates the draft if none is open (201), or UPDATES the open draft with the provided check-flight fields (200; af_hours, landing_count, utc_time, date, result, notes — all optional, partial edits allowed). Finalize it via POST /mcf/sign/{id} (sign:true). `active:false` DEACTIVATES it — cancels the open (unsigned) draft (\"tidak jadi\") and releases the MCF status; the cancelled record stays in the list. A signed MCF is a real event and is not cancelled.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "MCF"
+                ],
+                "summary": "Set a helicopter's MCF Yes/No — draft work endpoint (create/update or cancel)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Helicopter ID (UUIDv7)",
+                        "name": "helicopter_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API MCF set request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MCFSetRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFResponse"
+                        }
+                    },
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mcf/sign/{id}": {
+            "post": {
+                "description": "Finalizes an MCF's check-flight. `sign` (optional, default true): true FINALIZES it — af_hours, landing_count, utc_time, date, result required; \"passed\" clears the aircraft from MCF, \"failed\" keeps it grounded. false UNSIGNS it — reverts a signed MCF back to a draft (keeps the recorded data). Editing draft fields is done via /mcf/set; cancelling via /mcf/set (active:false).",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "MCF"
+                ],
+                "summary": "Sign (finalize) or unsign an MCF — toggle by MCF id",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "MCF ID (UUIDv7)",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API MCF sign request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MCFCompleteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine-group/create": {
+            "post": {
+                "description": "Create a medicine group row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine Group"
+                ],
+                "summary": "Create medicine group",
+                "parameters": [
+                    {
+                        "description": "JSON:API medicine group create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine-group/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine Group"
+                ],
+                "summary": "Delete medicine group",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Medicine Group UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine-group/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine Group"
+                ],
+                "summary": "List medicine groups",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by group name",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine-group/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine Group"
+                ],
+                "summary": "List medicine groups (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine-group/update/{uuid}": {
+            "patch": {
+                "description": "Patch medicine group by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine Group"
+                ],
+                "summary": "Update medicine group (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Medicine Group UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API medicine group update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine/create": {
+            "post": {
+                "description": "Create a medicine row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine"
+                ],
+                "summary": "Create medicine",
+                "parameters": [
+                    {
+                        "description": "JSON:API medicine create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine"
+                ],
+                "summary": "Delete medicine",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Medicine UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Search covers name, note, pack, unit, and column. Sort values: name, -name, sortkey, -sortkey, note, -note, pack, -pack, unit, -unit, column, -column, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine"
+                ],
+                "summary": "List medicine",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/note/pack/unit/column",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine"
+                ],
+                "summary": "List medicine (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/medicine/update/{uuid}": {
+            "patch": {
+                "description": "Patch medicine by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Medicine"
+                ],
+                "summary": "Update medicine (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Medicine UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API medicine update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission-type/create": {
+            "post": {
+                "description": "Create a mission category master record for use in mission flow.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Create mission type",
+                "parameters": [
+                    {
+                        "description": "JSON:API mission type create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionTypeCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionTypeResource"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission-type/get-all": {
+            "get": {
+                "description": "Returns all mission categories and their available subtypes.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "List mission types with subtypes",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionTypeListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/create": {
+            "post": {
+                "description": "Create a mission and link it to a flight.\n`type` must be one of: `HEMS`, `CAT`, `SPO`, `NCO`.\n`subtype_id` is required when `type=HEMS` and must reference mission subcategory under `HEMS` category.\n`subtype_id` must be empty when `type` is not `HEMS`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Create mission",
+                "parameters": [
+                    {
+                        "description": "JSON:API mission create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "409": {
+                        "description": "Conflict",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/delete-by-id/{mission_id}": {
+            "delete": {
+                "description": "Soft delete mission by its mission UUID. This also soft deletes flight data rows linked to the mission.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Delete mission by mission ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Mission ID (UUIDv7)",
+                        "name": "mission_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/delete/{flight_id}": {
+            "delete": {
+                "description": "Soft delete mission by linked flight ID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Delete mission",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/file/{mission_id}/{attachment_id}": {
+            "delete": {
+                "description": "Detaches the file (by its attachment id) from the mission and deletes the attachment.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Remove a file from a mission",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Mission UUID",
+                        "name": "mission_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "Attachment UUID (the file's attachment_id)",
+                        "name": "attachment_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/get-all": {
+            "get": {
+                "description": "Supports `search`, `filter[search]`, `flight_id`, `sort`, `page[number]`, `page[size]`, `page`, `size`, and `limit`.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "List missions",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (JSON:API style)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by flight UUID",
+                        "name": "flight_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter missions by flight data status: draft, in_progress, or completed",
+                        "name": "flight_data_status",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort field: type|-type|flight_date|-flight_date|created_at|-created_at|updated_at|-updated_at",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/get-all/dt": {
+            "get": {
+                "description": "Supports `search`, `filter[search]`, `date_from`, `date_to`, `mission_type`, `pilot_id`, `helicopter_id`, `sort`, `start`, `length`, `draw`, `page[number]`, `page[size]`, `page`, `size`, and `limit`.\n`date_from` and `date_to` filter flights by their mission date range (`YYYY-MM-DD`).\n`mission_type` accepts `HEMS`, `CAT`, `SPO`, or `NCO`.\n`pilot_id` filters missions where the pilot is assigned on the linked flight roster.\n`helicopter_id` filters missions by the helicopter used in the linked flight takeover.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "List missions (datatable)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (JSON:API style)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Filter by linked flight UUID",
+                        "name": "flight_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Mission date lower bound (YYYY-MM-DD)",
+                        "name": "date_from",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Mission date upper bound (YYYY-MM-DD)",
+                        "name": "date_to",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Mission type: HEMS|CAT|SPO|NCO",
+                        "name": "mission_type",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Pilot user UUID",
+                        "name": "pilot_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Helicopter UUID",
+                        "name": "helicopter_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort field: type|-type|flight_date|-flight_date|created_at|-created_at|updated_at|-updated_at",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "DataTables start index",
+                        "name": "start",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "DataTables page size",
+                        "name": "length",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "DataTables draw counter",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/get/{flight_id}": {
+            "get": {
+                "description": "Get mission detail by linked flight ID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Get mission by flight ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight ID (UUIDv7)",
+                        "name": "flight_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/mission/update/{mission_id}": {
+            "patch": {
+                "description": "Update mission type/subtype/note by mission ID, and optionally attach files already uploaded via `upload-mission-file`.\n`type` must be one of: `HEMS`, `CAT`, `SPO`, `NCO`.\n`subtype_id` is required when `type=HEMS` and must reference mission subcategory under `HEMS` category.\n`subtype_id` must be empty when `type` is not `HEMS`.\n`files[]` items reference an `upload_intent_uuid` (from `upload-mission-file`) and an optional display `name`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Mission"
+                ],
+                "summary": "Update mission",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Mission ID (UUIDv7)",
+                        "name": "mission_id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API mission update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/motor-reaction/create": {
+            "post": {
+                "description": "Create a motor reaction row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Motor Reaction"
+                ],
+                "summary": "Create motor reaction",
+                "parameters": [
+                    {
+                        "description": "JSON:API motor reaction create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/motor-reaction/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Motor Reaction"
+                ],
+                "summary": "Delete motor reaction",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Motor Reaction UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/motor-reaction/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, score, -score, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Motor Reaction"
+                ],
+                "summary": "List motor reactions",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by reaction name or score",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/motor-reaction/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Motor Reaction"
+                ],
+                "summary": "List motor reactions (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionDataTableResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/motor-reaction/update/{uuid}": {
+            "patch": {
+                "description": "Patch motor reaction by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Motor Reaction"
+                ],
+                "summary": "Update motor reaction (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Motor Reaction UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API motor reaction update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "503": {
+                        "description": "Service Unavailable",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/opc/create": {
+            "post": {
+                "description": "Create an OPC row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - OPC"
+                ],
+                "summary": "Create opc",
+                "parameters": [
+                    {
+                        "description": "JSON:API OPC create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/opc/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - OPC"
+                ],
+                "summary": "Delete opc",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "OPC UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/opc/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: title, -title, sortkey, -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - OPC"
+                ],
+                "summary": "List opc",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by title/note",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/opc/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - OPC"
+                ],
+                "summary": "List opc (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/opc/update/{uuid}": {
+            "patch": {
+                "description": "Patch opc by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - OPC"
+                ],
+                "summary": "Update opc (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "OPC UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API OPC update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/patient-data/create": {
+            "post": {
+                "description": "Create a PatientData record.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - PatientData"
+                ],
+                "summary": "Create patient data",
+                "parameters": [
+                    {
+                        "description": "JSON:API PatientData create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/patient-data/delete/{uuid}": {
+            "delete": {
+                "description": "Soft delete PatientData by ID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - PatientData"
+                ],
+                "summary": "Delete patient data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "PatientData UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/patient-data/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: family_name, -family_name, first_name, -first_name, birth_date, -birth_date, gender, -gender, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - PatientData"
+                ],
+                "summary": "List patient data",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by family_name/first_name/svnr/email/phone/street",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/patient-data/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - PatientData"
+                ],
+                "summary": "List patient data (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search by family_name/first_name/svnr/email/phone/street",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/patient-data/get/{uuid}": {
+            "get": {
+                "description": "Get a single PatientData record by UUID.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - PatientData"
+                ],
+                "summary": "Get patient data by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "PatientData UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/patient-data/update/{uuid}": {
+            "patch": {
+                "description": "Patch PatientData by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "PatientData - PatientData"
+                ],
+                "summary": "Update patient data (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "PatientData UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API PatientData update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/public/branding/email-logo": {
+            "get": {
+                "description": "Return a stable company logo optimized for email clients like Outlook.\nBackend prefers managed raster thumbnail/logo and falls back to backend-generated PNG when necessary.\nSupports conditional requests with `If-None-Match` / `If-Modified-Since`.",
+                "produces": [
+                    "image/png",
+                    "image/jpeg",
+                    "image/gif",
+                    "application/octet-stream"
+                ],
+                "tags": [
+                    "Branding"
+                ],
+                "summary": "Get email-safe branding logo",
+                "responses": {
+                    "200": {
+                        "description": "Email-safe branding logo binary",
+                        "schema": {
+                            "type": "file"
+                        }
+                    },
+                    "304": {
+                        "description": "Not Modified",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/reserve-acs/create": {
+            "post": {
+                "description": "Create reserve AC, create draft inspection, fill before + prepare inspection payload, and assign to flight.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Reserve AC"
+                ],
+                "summary": "Create reserve aircraft assignment",
+                "parameters": [
+                    {
+                        "description": "Create reserve AC request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/reserve-acs/delete": {
+            "delete": {
+                "description": "Delete reserve AC by body `data.id`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Reserve AC"
+                ],
+                "summary": "Delete reserve AC",
+                "parameters": [
+                    {
+                        "description": "Delete reserve AC request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcDeleteRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Document"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/reserve-acs/get-all": {
+            "get": {
+                "description": "Supports `search`, `filter[search]`, `sort`, `page[number]`, `page[size]`, `page`, `size`, and `limit`.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Reserve AC"
+                ],
+                "summary": "List reserve AC",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (JSON:API style)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Reserve AC UUID (exact match)",
+                        "name": "id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Flight UUID (exact match)",
+                        "name": "flight_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort field",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (fallback)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (fallback)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/reserve-acs/get-all/dt": {
+            "get": {
+                "description": "Datatable list scoped by auth user. Admin can see all rows; non-admin only sees reserve AC linked to own flight assignments.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Reserve AC"
+                ],
+                "summary": "List reserve AC (datatable)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search text",
+                        "name": "search",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search text (JSON:API style)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Reserve AC UUID (exact match)",
+                        "name": "id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Flight UUID (exact match)",
+                        "name": "flight_id",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort field",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcListResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/reserve-acs/get/{uuid}": {
+            "get": {
+                "description": "Get reserve AC detail. Path `uuid` accepts reserve_ac id, and supports fallback to flight id.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Reserve AC"
+                ],
+                "summary": "Get reserve AC by UUID or flight UUID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Reserve AC UUID or Flight UUID",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/reserve-acs/update": {
+            "patch": {
+                "description": "Update reserve AC using body `data.id`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flights - Reserve AC"
+                ],
+                "summary": "Update reserve AC",
+                "parameters": [
+                    {
+                        "description": "Update reserve AC request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/create": {
+            "post": {
+                "description": "Create a new role. Name is required and must be unique.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Create role",
+                "parameters": [
+                    {
+                        "description": "JSON:API Role create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Delete role",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "List roles",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Filter by name (contains)",
+                        "name": "filter[name]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Set to 'permissions' to embed each role's assigned permissions",
+                        "name": "include",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "List roles (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Get role by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/permissions/get-all": {
+            "get": {
+                "description": "Returns every permission grouped by its module, ordered by the module registry. Optional filter[name] narrows by permission name/key.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "List permissions grouped by module",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Filter by name/key (contains)",
+                        "name": "filter[name]",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionGroupedResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/permissions/{permission_uuid}": {
+            "patch": {
+                "description": "Patch permission by ID. Currently supports updating requires_pin.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Update permission",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Permission UUID (UUIDv7)",
+                        "name": "permission_uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API permission update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionResource"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/update/{uuid}": {
+            "patch": {
+                "description": "Patch role by ID. Provide at least one of: name, description. Name must be unique if provided.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Update role (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API Role update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/{uuid}/permissions": {
+            "get": {
+                "description": "Returns the permissions currently assigned to the given role. Pair with /roles/permissions/get-all to pre-check a role-permission editor.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "List a role's assigned permissions",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionListResponse"
+                        }
+                    }
+                }
+            },
+            "post": {
+                "description": "Assign one permission to a role. Idempotent if already assigned.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Assign permission to role",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API role permission assign request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/{uuid}/permissions/assign-bulk": {
+            "post": {
+                "description": "Assign multiple permissions to role. Idempotent for duplicates/already assigned.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Assign permissions to role (bulk)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API role permission bulk request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionListResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/{uuid}/permissions/remove-bulk": {
+            "post": {
+                "description": "Remove multiple permissions from role.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Remove permissions from role (bulk)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API role permission bulk request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionRemoveBulkRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionListResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/roles/{uuid}/permissions/{permission_uuid}": {
+            "delete": {
+                "description": "Remove one permission from role.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Roles"
+                ],
+                "summary": "Remove permission from role",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Role UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "Permission UUID (UUIDv7)",
+                        "name": "permission_uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/takeovers/create": {
+            "post": {
+                "description": "Atomic create for duty roster + crews + reserve AC + pre-flight inspection + flight. The takeover inspection payload also includes fleet status files under `inspection.fleet_status_file`.\nOptional takeover file uploads can be included via `data.attributes.files[*]` using upload intent UUIDs.\nEdited template draft files created earlier can be linked by passing `data.attributes.edited_template_file_ids[*]`.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight - Takeovers"
+                ],
+                "summary": "Create takeover in one request",
+                "parameters": [
+                    {
+                        "description": "Create takeover request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/takeovers/delete/{id}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight - Takeovers"
+                ],
+                "summary": "Delete takeover by flight UUID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight UUID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/takeovers/get-all": {
+            "get": {
+                "description": "Return composite takeover records built from flight, reserve AC, duty roster, and inspection. The inspection payload includes `before`, `prepare`, and `fleet_status_file`.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight - Takeovers"
+                ],
+                "summary": "List takeovers",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/takeovers/get/{id}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight - Takeovers"
+                ],
+                "summary": "Get takeover by flight UUID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight UUID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/takeovers/update/{id}": {
+            "patch": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Flight - Takeovers"
+                ],
+                "summary": "Replace takeover by flight UUID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Flight UUID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Update takeover request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/users/create": {
+            "post": {
+                "description": "Create a new user. Email, username, first name, last name and role_id are required. Use role_ids to assign additional roles.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "Create user",
+                "parameters": [
+                    {
+                        "description": "JSON:API User create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/users/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "Delete user",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/users/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: email, -email, first_name, -first_name, last_name, -last_name, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "List users",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by username/email/first_name/last_name (contains)",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/users/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "List users (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/users/get/{uuid}": {
+            "get": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "Get user by ID",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/users/update/{uuid}": {
+            "patch": {
+                "description": "Patch user by ID. Provide at least one attribute to update.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "Update user (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API User update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/vocation/create": {
+            "post": {
+                "description": "Create a vocation row.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Vocation"
+                ],
+                "summary": "Create vocation",
+                "parameters": [
+                    {
+                        "description": "JSON:API vocation create request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationCreateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "201": {
+                        "description": "Created",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationResponse"
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/vocation/delete/{uuid}": {
+            "delete": {
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Vocation"
+                ],
+                "summary": "Delete vocation",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Vocation UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/vocation/get-all": {
+            "get": {
+                "description": "JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Vocation"
+                ],
+                "summary": "List vocation",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Search by name/note",
+                        "name": "filter[search]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page[number]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "page[size]",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Sort order",
+                        "name": "sort",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationListResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/vocation/get-all/dt": {
+            "get": {
+                "description": "Datatable response with simple pagination params.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Vocation"
+                ],
+                "summary": "List vocation (datatable)",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Page number (default 1)",
+                        "name": "page",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size (default 20, max 100)",
+                        "name": "size",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Page size override (same as size)",
+                        "name": "limit",
+                        "in": "query"
+                    },
+                    {
+                        "type": "integer",
+                        "description": "Draw counter (optional)",
+                        "name": "draw",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Search term",
+                        "name": "search",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationDataTableResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v1/vocation/update/{uuid}": {
+            "patch": {
+                "description": "Patch vocation by ID.",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "OPC - Vocation"
+                ],
+                "summary": "Update vocation (partial)",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Vocation UUID (UUIDv7)",
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "JSON:API vocation update request",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationUpdateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationResponse"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    },
+                    "422": {
+                        "description": "Unprocessable Entity",
+                        "schema": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.ErrorResponse"
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "internal_transport_http_handlers.loginBrandingContentAttrsDTO": {
+            "type": "object",
+            "properties": {
+                "subtitle": {
+                    "type": "string"
+                },
+                "title": {
+                    "type": "string"
+                },
+                "updated_at": {
+                    "type": "string"
+                },
+                "version": {
+                    "type": "string"
+                }
+            }
+        },
+        "internal_transport_http_handlers.loginBrandingContentData": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/internal_transport_http_handlers.loginBrandingContentAttrsDTO"
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "internal_transport_http_handlers.loginBrandingContentDocument": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/internal_transport_http_handlers.loginBrandingContentData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionAttributes": {
+            "type": "object",
+            "properties": {
+                "completed": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-09T05:00:00Z"
+                },
+                "done_file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionFileChecklistItem"
+                    }
+                },
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionFileChecklistItem"
+                    }
+                },
+                "flight_data_count": {
+                    "type": "integer",
+                    "example": 2
+                },
+                "flight_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionResource"
+                },
+                "flight_inspection_id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "flight_time_seconds": {
+                    "type": "integer",
+                    "example": 9000
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResource"
+                },
+                "hydraulic_lh_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "hydraulic_rh_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "mission_code": {
+                    "type": "string",
+                    "example": "M-2026-001"
+                },
+                "mission_type": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "note": {
+                    "type": "string",
+                    "example": "All checks completed"
+                },
+                "oil_engine_nr1_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "oil_engine_nr2_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "oil_transmission_igb_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "oil_transmission_mgb_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "oil_transmission_tgb_checked": {
+                    "type": "string",
+                    "example": "1"
+                },
+                "route": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "total": {
+                    "type": "integer",
+                    "example": 3
+                },
+                "total_flight": {
+                    "type": "integer",
+                    "example": 3
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-09T05:00:00Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionFileChecklistItem": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "file_name": {
+                    "type": "string",
+                    "example": "After Flight Checklist.pdf"
+                },
+                "helicopter_file_id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-111111111111"
+                },
+                "is_done": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "after_flight_inspection"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionUpsertAttributes": {
+            "type": "object",
+            "properties": {
+                "hydraulic_lh_checked": {
+                    "type": "string"
+                },
+                "hydraulic_rh_checked": {
+                    "type": "string"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "oil_engine_nr1_checked": {
+                    "type": "string"
+                },
+                "oil_engine_nr2_checked": {
+                    "type": "string"
+                },
+                "oil_transmission_igb_checked": {
+                    "type": "string"
+                },
+                "oil_transmission_mgb_checked": {
+                    "type": "string"
+                },
+                "oil_transmission_tgb_checked": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionUpsertData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionUpsertAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "after_flight_inspection_upsert",
+                        "after_flight_inspection"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AfterFlightInspectionUpsertRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionUpsertData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AirRescuerProfileAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "responsible_flight_rescuer": {
+                    "type": "boolean"
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AirRescuerProfileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "responsible_flight_rescuer": {
+                    "type": "boolean"
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AuthCurrentUserAttributes": {
+            "type": "object",
+            "properties": {
+                "auth_provider": {
+                    "type": "string",
+                    "example": "email"
+                },
+                "dul_bases": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULBase"
+                    }
+                },
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "email_sso": {
+                    "type": "string",
+                    "example": "user.sso@example.com"
+                },
+                "email_verified_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "foto": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserFoto"
+                },
+                "is_previously_configured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "linked_sso": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "login_method": {
+                    "type": "string",
+                    "example": "email"
+                },
+                "microsoft_scope": {
+                    "type": "string",
+                    "example": "openid profile email offline_access User.Read"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "permission_modules": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionGroupResource"
+                    }
+                },
+                "permissions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionMini"
+                    }
+                },
+                "pin_blocked": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "pin_configured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "roles": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleMini"
+                    }
+                },
+                "timezone": {
+                    "type": "string",
+                    "example": "Asia/Jakarta"
+                },
+                "totp_enabled": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "webauthn_configured": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AuthCurrentUserResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthCurrentUserAttributes"
+                        },
+                        "id": {
+                            "type": "string",
+                            "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "user"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AuthSessionDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "deleted": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_session_delete"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AuthSessionItem": {
+            "type": "object",
+            "properties": {
+                "active_now": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-13T12:00:00Z"
+                },
+                "device_name": {
+                    "type": "string",
+                    "example": "Chrome on macOS"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "ip_address": {
+                    "type": "string",
+                    "example": "127.0.0.1"
+                },
+                "last_active_at": {
+                    "type": "string",
+                    "example": "2026-03-13T12:10:00Z"
+                },
+                "user_agent": {
+                    "type": "string",
+                    "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.AuthSessionsResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "sessions": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/definitions/wucher_internal_transport_http_dto.AuthSessionItem"
+                                    }
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_sessions"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Lude Airfield"
+                },
+                "base": {
+                    "type": "string",
+                    "example": "Lude"
+                },
+                "base_abbreviation": {
+                    "type": "string",
+                    "example": "LOIG"
+                },
+                "base_category": {
+                    "type": "string",
+                    "enum": [
+                        "regular",
+                        "hems"
+                    ],
+                    "example": "regular"
+                },
+                "checklist": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "control_center": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "default_end_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "default_start_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "dry": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "dul": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "email": {
+                    "type": "string",
+                    "example": "lude@wucher.local"
+                },
+                "foto": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseFoto"
+                },
+                "hems_edc": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseContact"
+                    }
+                },
+                "hems_edc_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "+62-21-1234"
+                },
+                "latitude": {
+                    "type": "number",
+                    "example": 47.3769
+                },
+                "leg_time": {
+                    "type": "string",
+                    "example": "00:20"
+                },
+                "longitude": {
+                    "type": "number",
+                    "example": 8.5417
+                },
+                "med_pax": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseContact"
+                    }
+                },
+                "med_pax_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+62-812-1234"
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Main base"
+                },
+                "operational_shift_times": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseOperationalShiftTime"
+                    }
+                },
+                "responsible_pilot_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "responsible_pilots": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseContact"
+                    }
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseShiftTime"
+                },
+                "sms_alert": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "utc": {
+                    "type": "string",
+                    "example": "0"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseContact": {
+            "type": "object",
+            "properties": {
+                "first_name": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "last_name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseCreateAttributes": {
+            "type": "object",
+            "required": [
+                "base",
+                "latitude",
+                "longitude"
+            ],
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Lude Airfield"
+                },
+                "base": {
+                    "type": "string",
+                    "example": "Lude"
+                },
+                "base_abbreviation": {
+                    "type": "string",
+                    "example": "LOIG"
+                },
+                "base_category": {
+                    "type": "string",
+                    "enum": [
+                        "regular",
+                        "hems"
+                    ],
+                    "example": "regular"
+                },
+                "checklist": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "control_center": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "default_end_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "default_shift_end": {
+                    "type": "string",
+                    "example": "21:00:00"
+                },
+                "default_shift_start": {
+                    "type": "string",
+                    "example": "06:00:00"
+                },
+                "default_shift_time": {
+                    "type": "string",
+                    "example": "12:00"
+                },
+                "default_start_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "dry": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "dul": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "email": {
+                    "type": "string",
+                    "example": "lude@wucher.local"
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"
+                },
+                "hems_edc_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "+62-21-1234"
+                },
+                "latitude": {
+                    "type": "number",
+                    "maximum": 90,
+                    "minimum": -90,
+                    "example": 47.3769
+                },
+                "leg_time": {
+                    "type": "string",
+                    "example": "00:20"
+                },
+                "longitude": {
+                    "type": "number",
+                    "maximum": 180,
+                    "minimum": -180,
+                    "example": 8.5417
+                },
+                "med_pax_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+62-812-1234"
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Main base"
+                },
+                "operational_shift_times": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseOperationalShiftTime"
+                    }
+                },
+                "responsible_pilot_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseShiftTime"
+                },
+                "sms_alert": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "utc": {
+                    "type": "string",
+                    "example": "0"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "base"
+                    ],
+                    "example": "base"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseDeleteAttributes": {
+            "type": "object",
+            "properties": {
+                "deleted": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseDeleteResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseDeleteAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6b10-a385-7e9e-a553-8e892bcec0ef"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "base_delete"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseDeleteResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseFoto": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/base/lude.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Expires=900\u0026X-Amz-Signature=abc123"
+                },
+                "original_size_bytes": {
+                    "type": "integer",
+                    "example": 1024000
+                },
+                "thumbnail_download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/base/lude.thumb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Expires=900\u0026X-Amz-Signature=abc123"
+                },
+                "uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseOperationalShiftTime": {
+            "type": "object",
+            "properties": {
+                "date_end": {
+                    "type": "string",
+                    "example": "2026-04-12"
+                },
+                "date_start": {
+                    "type": "string",
+                    "example": "2026-04-12"
+                },
+                "end_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseShiftTime"
+                },
+                "start_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "base"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseShiftTime": {
+            "type": "object",
+            "properties": {
+                "end": {
+                    "type": "string",
+                    "example": "21:00"
+                },
+                "start": {
+                    "type": "string",
+                    "example": "06:00"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Lude Airfield"
+                },
+                "base": {
+                    "type": "string",
+                    "example": "Lude"
+                },
+                "base_abbreviation": {
+                    "type": "string",
+                    "example": "LOIG"
+                },
+                "base_category": {
+                    "type": "string",
+                    "enum": [
+                        "regular",
+                        "hems"
+                    ],
+                    "example": "regular"
+                },
+                "checklist": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "control_center": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "default_end_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "default_shift_end": {
+                    "type": "string",
+                    "example": "21:00:00"
+                },
+                "default_shift_start": {
+                    "type": "string",
+                    "example": "06:00:00"
+                },
+                "default_shift_time": {
+                    "type": "string",
+                    "example": "12:00"
+                },
+                "default_start_time_type": {
+                    "type": "string",
+                    "enum": [
+                        "FIXED",
+                        "BMCT",
+                        "ECET"
+                    ],
+                    "example": "FIXED"
+                },
+                "dry": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "dul": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "email": {
+                    "type": "string",
+                    "example": "lude@wucher.local"
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"
+                },
+                "hems_edc_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "+62-21-1234"
+                },
+                "latitude": {
+                    "type": "number",
+                    "maximum": 90,
+                    "minimum": -90,
+                    "example": 47.3769
+                },
+                "leg_time": {
+                    "type": "string",
+                    "example": "00:20"
+                },
+                "longitude": {
+                    "type": "number",
+                    "maximum": 180,
+                    "minimum": -180,
+                    "example": 8.5417
+                },
+                "med_pax_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+62-812-1234"
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Main base"
+                },
+                "operational_shift_times": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseOperationalShiftTime"
+                    }
+                },
+                "responsible_pilot_contact_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseShiftTime"
+                },
+                "sms_alert": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "utc": {
+                    "type": "string",
+                    "example": "0"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "base_update"
+                    ],
+                    "example": "base_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.BaseUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.BaseUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactBaseRole": {
+            "type": "object",
+            "properties": {
+                "base_id": {
+                    "type": "string"
+                },
+                "base_name": {
+                    "type": "string"
+                },
+                "role_code": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactBulkUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "required": [
+                        "user_ids"
+                    ],
+                    "properties": {
+                        "is_active": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "user_ids": {
+                            "type": "array",
+                            "minItems": 1,
+                            "items": {
+                                "type": "string"
+                            },
+                            "example": [
+                                "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1"
+                            ]
+                        }
+                    }
+                },
+                "type": {
+                    "type": "string",
+                    "example": "contact_bulk_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactBulkUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactBulkUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactChiefFlagsUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "properties": {
+                        "is_chief_physician": {
+                            "type": "boolean"
+                        },
+                        "is_chief_pilot": {
+                            "type": "boolean"
+                        },
+                        "is_chief_technician": {
+                            "type": "boolean"
+                        }
+                    }
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactChiefFlagsUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactChiefFlagsUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactCreateAttributes": {
+            "type": "object",
+            "properties": {
+                "air_rescuer": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AirRescuerProfileAttributes"
+                },
+                "doctor": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DoctorProfileAttributes"
+                },
+                "email": {
+                    "type": "string"
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "maxLength": 64
+                },
+                "first_name": {
+                    "type": "string",
+                    "maxLength": 100
+                },
+                "flight_assistant": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightAssistantProfileAttributes"
+                },
+                "is_active": {
+                    "type": "boolean"
+                },
+                "is_admin": {
+                    "type": "boolean"
+                },
+                "last_name": {
+                    "type": "string",
+                    "maxLength": 100
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "pilot": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PilotProfileAttributes"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1"
+                },
+                "role_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1",
+                        "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d2"
+                    ]
+                },
+                "sortkey": {
+                    "type": "integer"
+                },
+                "sso_email": {
+                    "type": "string"
+                },
+                "staff": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.StaffProfileAttributes"
+                },
+                "technician": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TechnicianProfileAttributes"
+                },
+                "timezone": {
+                    "type": "string",
+                    "maxLength": 64
+                },
+                "username": {
+                    "type": "string",
+                    "maxLength": 100
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "contact_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactLicenseUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "properties": {
+                        "license_no": {
+                            "type": "string"
+                        }
+                    }
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactLicenseUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactLicenseUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactListAttributes": {
+            "type": "object",
+            "properties": {
+                "air_rescuer": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AirRescuerProfileAttributes"
+                },
+                "base_roles": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactBaseRole"
+                    }
+                },
+                "created_at": {
+                    "type": "string"
+                },
+                "created_by": {
+                    "type": "string"
+                },
+                "doctor": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DoctorProfileAttributes"
+                },
+                "email": {
+                    "type": "string"
+                },
+                "first_name": {
+                    "type": "string"
+                },
+                "flight_assistant": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightAssistantProfileAttributes"
+                },
+                "is_active": {
+                    "type": "boolean"
+                },
+                "is_admin": {
+                    "type": "boolean"
+                },
+                "last_name": {
+                    "type": "string"
+                },
+                "license_no": {
+                    "type": "string"
+                },
+                "location": {
+                    "type": "string"
+                },
+                "mobile_phone": {
+                    "type": "string"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "pilot": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PilotProfileAttributes"
+                },
+                "pilot_category": {
+                    "type": "string"
+                },
+                "role_code": {
+                    "type": "string"
+                },
+                "role_name": {
+                    "type": "string"
+                },
+                "roles": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactRole"
+                    }
+                },
+                "set_password": {
+                    "type": "boolean"
+                },
+                "short_name": {
+                    "type": "string"
+                },
+                "sortkey": {
+                    "type": "integer"
+                },
+                "sso_email": {
+                    "type": "string"
+                },
+                "staff": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.StaffProfileAttributes"
+                },
+                "technician": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TechnicianProfileAttributes"
+                },
+                "updated_at": {
+                    "type": "string"
+                },
+                "updated_by": {
+                    "type": "string"
+                },
+                "username": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactListItem": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string"
+                },
+                "created_by": {
+                    "type": "string"
+                },
+                "email": {
+                    "type": "string"
+                },
+                "first_name": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "is_active": {
+                    "type": "boolean"
+                },
+                "is_admin": {
+                    "type": "boolean"
+                },
+                "last_name": {
+                    "type": "string"
+                },
+                "license_no": {
+                    "type": "string"
+                },
+                "location": {
+                    "type": "string"
+                },
+                "mobile_phone": {
+                    "type": "string"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "pilot_category": {
+                    "type": "string"
+                },
+                "role_code": {
+                    "type": "string"
+                },
+                "role_name": {
+                    "type": "string"
+                },
+                "set_password": {
+                    "type": "boolean"
+                },
+                "short_name": {
+                    "type": "string"
+                },
+                "sortkey": {
+                    "type": "integer"
+                },
+                "updated_at": {
+                    "type": "string"
+                },
+                "updated_by": {
+                    "type": "string"
+                },
+                "username": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "attributes": {
+                                "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactListAttributes"
+                            },
+                            "id": {
+                                "type": "string",
+                                "example": "019dcce4-f15e-7685-8e4c-76f8ad20594b"
+                            },
+                            "type": {
+                                "type": "string",
+                                "example": "contact"
+                            }
+                        }
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "limit": {
+                            "type": "integer"
+                        },
+                        "offset": {
+                            "type": "integer"
+                        },
+                        "total": {
+                            "type": "integer"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactPilotCategoryUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "required": [
+                        "pilot_category"
+                    ],
+                    "properties": {
+                        "pilot_category": {
+                            "type": "string",
+                            "enum": [
+                                "regular",
+                                "freelance",
+                                "dry_lease"
+                            ]
+                        }
+                    }
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactPilotCategoryUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactPilotCategoryUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactRole": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                },
+                "role_code": {
+                    "type": "string"
+                },
+                "role_name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactRoleUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "required": [
+                        "role_code"
+                    ],
+                    "properties": {
+                        "role_code": {
+                            "type": "string",
+                            "enum": [
+                                "pilot",
+                                "doctor",
+                                "air_rescuer",
+                                "technician",
+                                "flight_assistant",
+                                "staff"
+                            ]
+                        }
+                    }
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactRoleUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactRoleUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactSimpleSuccessResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "count": {
+                                    "type": "integer"
+                                },
+                                "deleted": {
+                                    "type": "boolean"
+                                },
+                                "updated": {
+                                    "type": "boolean"
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactStatusUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "properties": {
+                        "is_active": {
+                            "type": "boolean"
+                        }
+                    }
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactStatusUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactStatusUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "air_rescuer": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AirRescuerProfileUpdateAttributes"
+                },
+                "doctor": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DoctorProfileUpdateAttributes"
+                },
+                "email": {
+                    "type": "string"
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "maxLength": 64
+                },
+                "first_name": {
+                    "type": "string",
+                    "maxLength": 100
+                },
+                "flight_assistant": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightAssistantProfileUpdateAttributes"
+                },
+                "is_active": {
+                    "type": "boolean"
+                },
+                "is_admin": {
+                    "type": "boolean"
+                },
+                "last_name": {
+                    "type": "string",
+                    "maxLength": 100
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "pilot": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PilotProfileUpdateAttributes"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1"
+                },
+                "role_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1",
+                        "0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d2"
+                    ]
+                },
+                "sortkey": {
+                    "type": "integer"
+                },
+                "sso_email": {
+                    "type": "string"
+                },
+                "staff": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.StaffProfileUpdateAttributes"
+                },
+                "technician": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TechnicianProfileUpdateAttributes"
+                },
+                "timezone": {
+                    "type": "string",
+                    "maxLength": 64
+                },
+                "username": {
+                    "type": "string",
+                    "maxLength": 100
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "contact_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ContactUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ContactUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULAttributes": {
+            "type": "object",
+            "properties": {
+                "base": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULBaseRef"
+                },
+                "created_at": {
+                    "type": "string"
+                },
+                "created_by": {
+                    "type": "string"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-05-25"
+                },
+                "images": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULImage"
+                    }
+                },
+                "info": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                },
+                "no": {
+                    "type": "integer"
+                },
+                "updated_at": {
+                    "type": "string"
+                },
+                "updated_by": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULBase": {
+            "type": "object",
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "example": "hems"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "0197f3b2-c4d8-4b12-a1f9-c1de23456789"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Halim Base"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULBaseRef": {
+            "type": "object",
+            "properties": {
+                "category": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULCreateAttributes": {
+            "type": "object",
+            "required": [
+                "base_id",
+                "date",
+                "name"
+            ],
+            "properties": {
+                "base_id": {
+                    "type": "string",
+                    "example": "019e3ec1-94f6-7b6b-9cc5-1b5d05f46d74"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-05-25"
+                },
+                "file_uuid": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "info": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string",
+                    "maxLength": 128
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "dul_create",
+                        "dul"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULGroup"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 120
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        },
+                        "total_bases": {
+                            "type": "integer",
+                            "example": 8
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "deleted": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "dul_delete"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULGroup": {
+            "type": "object",
+            "properties": {
+                "base": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULBaseRef"
+                },
+                "duls": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULImage": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string"
+                },
+                "original_size_bytes": {
+                    "type": "integer"
+                },
+                "thumbnail_download_url": {
+                    "type": "string"
+                },
+                "uuid": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULGroup"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        },
+                        "total_bases": {
+                            "type": "integer",
+                            "example": 8
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULAttributes"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "base_id": {
+                    "type": "string"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-05-25"
+                },
+                "file_uuid": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "info": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "dul_update",
+                        "dul"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DULUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.DULUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DoctorProfileAttributes": {
+            "type": "object",
+            "properties": {
+                "is_chief_physician": {
+                    "type": "boolean"
+                },
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "specialization": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "sub_specialization": {
+                    "type": "string",
+                    "maxLength": 120
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.DoctorProfileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "is_chief_physician": {
+                    "type": "boolean"
+                },
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "specialization": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "sub_specialization": {
+                    "type": "string",
+                    "maxLength": 120
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPSendAttributes": {
+            "type": "object",
+            "required": [
+                "challenge_token"
+            ],
+            "properties": {
+                "challenge_token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPSendData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPSendAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_email_otp_send"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPSendRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPSendData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPSendResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "sent": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_email_otp_send"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPVerifyAttributes": {
+            "type": "object",
+            "required": [
+                "challenge_token",
+                "code"
+            ],
+            "properties": {
+                "challenge_token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                },
+                "code": {
+                    "type": "string",
+                    "example": "123456"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPVerifyData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPVerifyAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_email_otp_verify"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPVerifyRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.EmailOTPVerifyData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.EmailOTPVerifyResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "requires_totp_setup": {
+                                    "type": "boolean",
+                                    "example": true
+                                },
+                                "verified": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_email_otp_verify"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ErrorResponse": {
+            "type": "object",
+            "properties": {
+                "errors": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "detail": {
+                                "type": "string",
+                                "example": "email is required"
+                            },
+                            "source": {
+                                "type": "object",
+                                "properties": {
+                                    "pointer": {
+                                        "type": "string",
+                                        "example": "/data/attributes/email"
+                                    }
+                                }
+                            },
+                            "status": {
+                                "type": "string",
+                                "example": "422"
+                            },
+                            "title": {
+                                "type": "string",
+                                "example": "Validation error"
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ExchangeAttributes": {
+            "type": "object",
+            "required": [
+                "access_token",
+                "id_token"
+            ],
+            "properties": {
+                "access_token": {
+                    "type": "string",
+                    "example": "eyJ0eXAiOiJKV1Qi..."
+                },
+                "id_token": {
+                    "type": "string",
+                    "example": "eyJ0eXAiOiJKV1Qi..."
+                },
+                "id_token_claims": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ExchangeIDTokenClaims"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ExchangeData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ExchangeAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_exchange"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ExchangeIDTokenClaims": {
+            "type": "object",
+            "properties": {
+                "aud": {
+                    "type": "string",
+                    "example": "12345678-1234-1234-1234-123456789012"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "andrio@mybit-innovation.com"
+                },
+                "exp": {
+                    "type": "integer",
+                    "example": 1715603600
+                },
+                "iat": {
+                    "type": "integer",
+                    "example": 1715600000
+                },
+                "iss": {
+                    "type": "string",
+                    "example": "https://login.microsoftonline.com/abc-tenant-id/v2.0"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Andrio Effendi"
+                },
+                "nbf": {
+                    "type": "integer",
+                    "example": 1715600000
+                },
+                "oid": {
+                    "type": "string",
+                    "example": "00000000-0000-0000-1234-567890abcdef"
+                },
+                "preferred_username": {
+                    "type": "string",
+                    "example": "andrio@mybit-innovation.com"
+                },
+                "sub": {
+                    "type": "string",
+                    "example": "AbCdEfGhIjKlMnOpQrStUvWxYz"
+                },
+                "tid": {
+                    "type": "string",
+                    "example": "abc-tenant-id"
+                },
+                "ver": {
+                    "type": "string",
+                    "example": "2.0"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ExchangeRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ExchangeData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportAirframeValues": {
+            "type": "object",
+            "properties": {
+                "cycles": {
+                    "type": "number",
+                    "example": 320
+                },
+                "hours": {
+                    "type": "number",
+                    "example": 1523.5
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportAttachmentItem": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string"
+                },
+                "file_id": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportAttachments": {
+            "type": "object",
+            "properties": {
+                "additional_fm_report": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAttachmentItem"
+                    }
+                },
+                "briefing": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAttachmentItem"
+                    }
+                },
+                "ofp": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAttachmentItem"
+                    }
+                },
+                "weight_balance": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAttachmentItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportAttributes": {
+            "type": "object",
+            "properties": {
+                "after_flight_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResource"
+                },
+                "completed_at": {
+                    "type": "string",
+                    "example": "2026-04-20T10:15:00Z"
+                },
+                "completed_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "engine1_gpc_n1": {
+                    "type": "string",
+                    "example": "GPC/N1 63.2"
+                },
+                "engine1_ptc_n2": {
+                    "type": "string",
+                    "example": "PTC/N2 61.8"
+                },
+                "engine2_gpc_n1": {
+                    "type": "string",
+                    "example": "GPC/N1 62.9"
+                },
+                "engine2_ptc_n2": {
+                    "type": "string",
+                    "example": "PTC/N2 61.5"
+                },
+                "fleet_status": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResource"
+                },
+                "flight": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightResource"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "flight_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionResource"
+                },
+                "flight_inspection_id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "fm_report_attachments": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAttachments"
+                },
+                "helicopter_identifier": {
+                    "type": "string",
+                    "example": "OE-TEST"
+                },
+                "helicopter_usage": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResource"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "missions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResource"
+                    }
+                },
+                "pilot_name": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "report_code": {
+                    "type": "string",
+                    "example": "EC-135-1"
+                },
+                "takeover_files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverFileResource"
+                    }
+                },
+                "takeover_id": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "usage_breakdown": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportUsageBreakdown"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportCountersValues": {
+            "type": "object",
+            "properties": {
+                "flight_reports": {
+                    "type": "number",
+                    "example": 80
+                },
+                "hook_releases": {
+                    "type": "number",
+                    "example": 10
+                },
+                "landings": {
+                    "type": "number",
+                    "example": 120
+                },
+                "rotor_brake_cycles": {
+                    "type": "number",
+                    "example": 8
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportEngineValues": {
+            "type": "object",
+            "properties": {
+                "ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "gpc_ng_n1": {
+                    "type": "number",
+                    "example": 63.2
+                },
+                "hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "ptc_nf_n2": {
+                    "type": "number",
+                    "example": 61.8
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "fm_report"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportUsageBreakdown": {
+            "type": "object",
+            "properties": {
+                "prev": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportUsageSnapshot"
+                },
+                "today": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportUsageSnapshot"
+                },
+                "total": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportUsageSnapshot"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FMReportUsageSnapshot": {
+            "type": "object",
+            "properties": {
+                "airframe": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportAirframeValues"
+                },
+                "counters": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportCountersValues"
+                },
+                "engine_1": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportEngineValues"
+                },
+                "engine_2": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FMReportEngineValues"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityAttributes": {
+            "type": "object",
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "example": "heslo-rope-label"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "electric": {
+                    "type": "string",
+                    "example": "available"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "length": {
+                    "type": "string",
+                    "example": "10m"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Fuel Truck Rope Label"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Dry lease fuel truck"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "type": {
+                    "type": "string",
+                    "example": "Sling"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "weight": {
+                    "type": "string",
+                    "example": "10kg"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityCreateAttributes": {
+            "type": "object",
+            "required": [
+                "category",
+                "name"
+            ],
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "example": "heslo-rope-label"
+                },
+                "electric": {
+                    "type": "string",
+                    "example": "available"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "length": {
+                    "type": "string",
+                    "example": "10m"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Fuel Truck Rope Label"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Dry lease fuel truck"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "type": {
+                    "type": "string",
+                    "example": "Sling"
+                },
+                "weight": {
+                    "type": "string",
+                    "example": "10kg"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "facility_create",
+                        "facility"
+                    ],
+                    "example": "facility_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "deleted": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "facility_delete"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "facility"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "example": "heslo-rope-label"
+                },
+                "electric": {
+                    "type": "string",
+                    "example": "available"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "length": {
+                    "type": "string",
+                    "example": "10m"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Fuel Truck Rope Label"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Dry lease fuel truck"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "type": {
+                    "type": "string",
+                    "example": "Sling"
+                },
+                "weight": {
+                    "type": "string",
+                    "example": "10kg"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "facility_update",
+                        "facility"
+                    ],
+                    "example": "facility_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FacilityUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FacilityUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "land_iso_code": {
+                    "type": "string",
+                    "example": "DE"
+                },
+                "land_name": {
+                    "type": "string",
+                    "example": "Germany"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Bayern"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Central region"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateCreateAttributes": {
+            "type": "object",
+            "required": [
+                "land_id",
+                "name"
+            ],
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Bayern"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Central region"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "federal_state_create",
+                        "federal_state"
+                    ],
+                    "example": "federal_state_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "deleted": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "federal_state_delete"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "federal_state"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Bayern"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Central region"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "federal_state_update",
+                        "federal_state"
+                    ],
+                    "example": "federal_state_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FederalStateUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FederalStateUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightAssistantProfileAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightAssistantProfileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-09T05:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "inspection_date": {
+                    "type": "string",
+                    "example": "2026-04-09"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "Draft"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-09T05:00:00Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionCreateAttributes": {
+            "type": "object",
+            "required": [
+                "inspection_date"
+            ],
+            "properties": {
+                "inspection_date": {
+                    "type": "string",
+                    "example": "2026-04-09"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "flight_inspection_create",
+                        "flight_inspection"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "flight_inspection"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "inspection_date": {
+                    "type": "string",
+                    "example": "2026-04-09"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "InProgress"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "flight_inspection_update",
+                        "flight_inspection"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.FlightInspectionUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.FlightInspectionUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Firefighter Team A"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "On-site responders"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Firefighter Team A"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "On-site responders"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "forces_present_create",
+                        "forces_present"
+                    ],
+                    "example": "forces_present_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "forces_present"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Firefighter Team A"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "On-site responders"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "forces_present_update",
+                        "forces_present"
+                    ],
+                    "example": "forces_present_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForcesPresentUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForcesPresentUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForgotPasswordAttributes": {
+            "type": "object",
+            "required": [
+                "email"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForgotPasswordData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForgotPasswordAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_forgot_password"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForgotPasswordRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForgotPasswordData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForgotSecurityPINAttributes": {
+            "type": "object",
+            "required": [
+                "email"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForgotSecurityPINData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForgotSecurityPINAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_forgot_pin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ForgotSecurityPINRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ForgotSecurityPINData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.GenericDeleteAttributes": {
+            "type": "object",
+            "properties": {
+                "deleted": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.GenericDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponseData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.GenericDeleteResponseData": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.GenericDeleteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "delete_result"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "hems_operation_category": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryRef"
+                },
+                "hems_operation_category_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mission": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationMissionRef"
+                },
+                "mission_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "operational_data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationOperationalDataRef"
+                },
+                "operational_data_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Firefighting"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "first"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name",
+                "type"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Firefighting"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "first",
+                        "secondary",
+                        "misuse"
+                    ],
+                    "example": "first"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hems_operation_category_create",
+                        "hems_operation_category"
+                    ],
+                    "example": "hems_operation_category_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryRef": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Firefighting"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "first"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hems_operation_category"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Firefighting"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "first",
+                        "secondary",
+                        "misuse"
+                    ],
+                    "example": "first"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hems_operation_category_update",
+                        "hems_operation_category"
+                    ],
+                    "example": "hems_operation_category_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCreateAttributes": {
+            "type": "object",
+            "required": [
+                "date"
+            ],
+            "properties": {
+                "date": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "hems_operation_category_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mission_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "operational_data_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hems_operation_create",
+                        "hems_operation"
+                    ],
+                    "example": "hems_operation_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationMissionRef": {
+            "type": "object",
+            "properties": {
+                "flight_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationOperationalDataRef": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hems_operation"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "date": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "hems_operation_category_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mission_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "operational_data_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hems_operation_update",
+                        "hems_operation"
+                    ],
+                    "example": "hems_operation_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataAttributes": {
+            "type": "object",
+            "properties": {
+                "additional_info": {
+                    "type": "string",
+                    "example": "Additional information about the operational data"
+                },
+                "altitude": {
+                    "type": "number",
+                    "example": 5.2
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "darkness": {
+                    "type": "boolean"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "false_information": {
+                    "type": "boolean"
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataFileAttributes"
+                    }
+                },
+                "fog": {
+                    "type": "boolean"
+                },
+                "force_present_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                    ]
+                },
+                "instrument_flight": {
+                    "type": "boolean"
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "landing_site_search": {
+                    "type": "boolean"
+                },
+                "location": {
+                    "type": "string",
+                    "example": "123 Main St, Anytown, USA"
+                },
+                "mountain_use": {
+                    "type": "boolean"
+                },
+                "nfo_search": {
+                    "type": "boolean"
+                },
+                "night_flight": {
+                    "type": "boolean"
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Notes about the operational data"
+                },
+                "postcode": {
+                    "type": "string",
+                    "example": "12345"
+                },
+                "precipitation": {
+                    "type": "boolean"
+                },
+                "rope_recovery": {
+                    "type": "boolean"
+                },
+                "state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "temperature": {
+                    "type": "number",
+                    "example": 23.5
+                },
+                "terrain_index": {
+                    "type": "string",
+                    "example": "Only helicopter landing"
+                },
+                "time": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "vocation_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "wind": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataCreateAttributes": {
+            "type": "object",
+            "required": [
+                "location",
+                "time"
+            ],
+            "properties": {
+                "additional_info": {
+                    "type": "string",
+                    "example": "Additional information about the operational data"
+                },
+                "altitude": {
+                    "type": "number",
+                    "example": 5.2
+                },
+                "darkness": {
+                    "type": "boolean"
+                },
+                "false_information": {
+                    "type": "boolean"
+                },
+                "file_attachment_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                    ]
+                },
+                "fog": {
+                    "type": "boolean"
+                },
+                "force_present_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                    ]
+                },
+                "instrument_flight": {
+                    "type": "boolean"
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "landing_site_search": {
+                    "type": "boolean"
+                },
+                "location": {
+                    "type": "string",
+                    "example": "123 Main St, Anytown, USA"
+                },
+                "mountain_use": {
+                    "type": "boolean"
+                },
+                "nfo_search": {
+                    "type": "boolean"
+                },
+                "night_flight": {
+                    "type": "boolean"
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Notes about the operational data"
+                },
+                "postcode": {
+                    "type": "string",
+                    "example": "12345"
+                },
+                "precipitation": {
+                    "type": "boolean"
+                },
+                "rope_recovery": {
+                    "type": "boolean"
+                },
+                "state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "temperature": {
+                    "type": "number",
+                    "example": 23.5
+                },
+                "terrain_index": {
+                    "type": "string",
+                    "example": "Only helicopter landing"
+                },
+                "time": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "vocation_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "wind": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hems_operational_data_create",
+                        "hems_operational_data"
+                    ],
+                    "example": "hems_operational_data_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataFileAttributes": {
+            "type": "object",
+            "properties": {
+                "file_attachment_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hems_operational_data"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "additional_info": {
+                    "type": "string",
+                    "example": "Additional information about the operational data"
+                },
+                "altitude": {
+                    "type": "number",
+                    "example": 5.2
+                },
+                "darkness": {
+                    "type": "boolean"
+                },
+                "false_information": {
+                    "type": "boolean"
+                },
+                "file_attachment_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "fog": {
+                    "type": "boolean"
+                },
+                "force_present_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "instrument_flight": {
+                    "type": "boolean"
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "landing_site_search": {
+                    "type": "boolean"
+                },
+                "location": {
+                    "type": "string",
+                    "example": "123 Main St, Anytown, USA"
+                },
+                "mountain_use": {
+                    "type": "boolean"
+                },
+                "nfo_search": {
+                    "type": "boolean"
+                },
+                "night_flight": {
+                    "type": "boolean"
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Notes about the operational data"
+                },
+                "postcode": {
+                    "type": "string",
+                    "example": "12345"
+                },
+                "precipitation": {
+                    "type": "boolean"
+                },
+                "rope_recovery": {
+                    "type": "boolean"
+                },
+                "state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "temperature": {
+                    "type": "number",
+                    "example": 23.5
+                },
+                "terrain_index": {
+                    "type": "string",
+                    "example": "Only helicopter landing"
+                },
+                "time": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "vocation_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "wind": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hems_operational_data_update",
+                        "hems_operational_data"
+                    ],
+                    "example": "hems_operational_data_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HEMSOperationalDataUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Main Street 10"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@abc-insurance.local"
+                },
+                "federal_state": {
+                    "type": "string",
+                    "example": "Bayern"
+                },
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "land_iso_code": {
+                    "type": "string",
+                    "example": "DE"
+                },
+                "land_name": {
+                    "type": "string",
+                    "example": "Germany"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+4912345678"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "ABC Insurance"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Preferred insurance provider"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "state": {
+                    "type": "string",
+                    "example": "Berlin"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Main Street 10"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@abc-insurance.local"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+4912345678"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "ABC Insurance"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Preferred insurance provider"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "state": {
+                    "type": "string",
+                    "example": "Berlin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "health_insurance_company_create",
+                        "health_insurance_company"
+                    ],
+                    "example": "health_insurance_company_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "health_insurance_company"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Main Street 10"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@abc-insurance.local"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+4912345678"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "ABC Insurance"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Preferred insurance provider"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "state": {
+                    "type": "string",
+                    "example": "Berlin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "health_insurance_company_update",
+                        "health_insurance_company"
+                    ],
+                    "example": "health_insurance_company_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "total_airframe_cycles": {
+                    "type": "number",
+                    "example": 320
+                },
+                "total_airframe_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_1_ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "total_engine_1_gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "total_engine_1_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_1_ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                },
+                "total_engine_2_ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "total_engine_2_gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "total_engine_2_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_2_ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                },
+                "total_flight_report": {
+                    "type": "number",
+                    "example": 80
+                },
+                "total_hook_release": {
+                    "type": "number",
+                    "example": 10
+                },
+                "total_landing": {
+                    "type": "number",
+                    "example": 120
+                },
+                "total_rotor_brake_cycle": {
+                    "type": "number",
+                    "example": 8
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageCreateAttributes": {
+            "type": "object",
+            "required": [
+                "helicopter_id"
+            ],
+            "properties": {
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "total_airframe_cycles": {
+                    "type": "number",
+                    "example": 320
+                },
+                "total_airframe_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_1_ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "total_engine_1_gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "total_engine_1_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_1_ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                },
+                "total_engine_2_ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "total_engine_2_gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "total_engine_2_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_2_ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                },
+                "total_flight_report": {
+                    "type": "number",
+                    "example": 80
+                },
+                "total_hook_release": {
+                    "type": "number",
+                    "example": 10
+                },
+                "total_landing": {
+                    "type": "number",
+                    "example": 120
+                },
+                "total_rotor_brake_cycle": {
+                    "type": "number",
+                    "example": 8
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_usage_create",
+                        "helicopter_usage"
+                    ],
+                    "example": "helicopter_usage_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter_usage"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "total_airframe_cycles": {
+                    "type": "number",
+                    "example": 320
+                },
+                "total_airframe_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_1_ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "total_engine_1_gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "total_engine_1_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_1_ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                },
+                "total_engine_2_ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "total_engine_2_gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "total_engine_2_hours": {
+                    "type": "number",
+                    "example": 1523.5
+                },
+                "total_engine_2_ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                },
+                "total_flight_report": {
+                    "type": "number",
+                    "example": 80
+                },
+                "total_hook_release": {
+                    "type": "number",
+                    "example": 10
+                },
+                "total_landing": {
+                    "type": "number",
+                    "example": 120
+                },
+                "total_rotor_brake_cycle": {
+                    "type": "number",
+                    "example": 8
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_usage_update",
+                        "helicopter_usage"
+                    ],
+                    "example": "helicopter_usage_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HelicopterUsageUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HelicopterUsageUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Jl. Merdeka No. 10"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@hospital.local"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "0211234567"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "08123456789"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "RSUD Kota"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Nearest trauma center"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Jl. Merdeka No. 10"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@hospital.local"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "0211234567"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "08123456789"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "RSUD Kota"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Nearest trauma center"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hospital_create",
+                        "hospital"
+                    ],
+                    "example": "hospital_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hospital"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Jl. Merdeka No. 10"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@hospital.local"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "0211234567"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "08123456789"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "RSUD Kota"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Nearest trauma center"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "hospital_update",
+                        "hospital"
+                    ],
+                    "example": "hospital_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.HospitalUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.HospitalUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Muehlenstrasse 1"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "ops@example.local"
+                },
+                "federal_state": {
+                    "type": "string",
+                    "example": "Bayern"
+                },
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "icao_code": {
+                    "type": "string",
+                    "example": "EDDB"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "land_iso_code": {
+                    "type": "string",
+                    "example": "DE"
+                },
+                "land_name": {
+                    "type": "string",
+                    "example": "Germany"
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "030123456"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "0170123456"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Berlin Base"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Night operations supported"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOCreateAttributes": {
+            "type": "object",
+            "required": [
+                "icao_code"
+            ],
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Muehlenstrasse 1"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "ops@example.local"
+                },
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "icao_code": {
+                    "type": "string",
+                    "example": "EDDB"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "030123456"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "0170123456"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Berlin Base"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Night operations supported"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "icao_create",
+                        "icao"
+                    ],
+                    "example": "icao_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAODataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "icao"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Muehlenstrasse 1"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "ops@example.local"
+                },
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "icao_code": {
+                    "type": "string",
+                    "example": "EDDB"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "land_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "landline_number": {
+                    "type": "string",
+                    "example": "030123456"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "0170123456"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Berlin Base"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Night operations supported"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "icao_update",
+                        "icao"
+                    ],
+                    "example": "icao_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ICAOUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ICAOUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "federal_state": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataFederalState"
+                },
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "health_insurance_companies_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "health_insurance_company": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataHealthInsuranceCompany"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataCreateAttributes": {
+            "type": "object",
+            "required": [
+                "federal_state_id",
+                "health_insurance_companies_id"
+            ],
+            "properties": {
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "health_insurance_companies_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "insurance_patient_data_create",
+                        "insurance_patient_data"
+                    ],
+                    "example": "insurance_patient_data_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataFederalState": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Bayern"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataHealthInsuranceCompany": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "example": "Main Street 10"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "info@abc-insurance.local"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mobile_number": {
+                    "type": "string",
+                    "example": "+4912345678"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "ABC Insurance"
+                },
+                "state": {
+                    "type": "string",
+                    "example": "Berlin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "insurance_patient_data"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "health_insurance_companies_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "insurance_patient_data_update",
+                        "insurance_patient_data"
+                    ],
+                    "example": "insurance_patient_data_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InsurancePatientDataUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InviteAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "first_name",
+                "last_name",
+                "role_id",
+                "username"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "role_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "[\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d\"",
+                        "\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e\"]"
+                    ]
+                },
+                "username": {
+                    "type": "string",
+                    "maxLength": 100,
+                    "minLength": 3,
+                    "example": "john.doe"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InviteData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InviteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_invite"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.InviteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InviteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandAttributes": {
+            "type": "object",
+            "properties": {
+                "bmd_export_id": {
+                    "type": "string",
+                    "example": "DE001"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "federal_state_list": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.LandFederalStateDTO"
+                    }
+                },
+                "federal_state_total": {
+                    "type": "integer",
+                    "example": 2
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "iso_code": {
+                    "type": "string",
+                    "example": "DE"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Germany"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Central Europe"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "bmd_export_id": {
+                    "type": "string",
+                    "example": "DE001"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "iso_code": {
+                    "type": "string",
+                    "example": "DE"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Germany"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Central Europe"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LandCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "land_create",
+                        "land"
+                    ],
+                    "example": "land_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LandCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.LandResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandFederalStateDTO": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Bayern"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.LandResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LandAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "land"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LandResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "bmd_export_id": {
+                    "type": "string",
+                    "example": "DE001"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "iso_code": {
+                    "type": "string",
+                    "example": "DE"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Germany"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Central Europe"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LandUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "land_update",
+                        "land"
+                    ],
+                    "example": "land_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LandUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LandUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LoginAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "password"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "password": {
+                    "type": "string",
+                    "example": "StrongP@ssw0rd"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LoginData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LoginAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_login"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LoginEmailOTPRequiredResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "challenge_token": {
+                                    "type": "string",
+                                    "example": "kP8k2..."
+                                },
+                                "linked_sso": {
+                                    "type": "boolean",
+                                    "example": false
+                                },
+                                "max_resend_per_hour": {
+                                    "type": "integer",
+                                    "example": 5
+                                },
+                                "pin_configured": {
+                                    "type": "boolean",
+                                    "example": false
+                                },
+                                "requires_email_otp": {
+                                    "type": "boolean",
+                                    "example": true
+                                },
+                                "requires_totp_setup": {
+                                    "type": "boolean",
+                                    "example": true
+                                },
+                                "resend_cooldown_seconds": {
+                                    "type": "integer",
+                                    "example": 60
+                                },
+                                "webauthn_configured": {
+                                    "type": "boolean",
+                                    "example": false
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_email_otp_required"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LoginRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.LoginData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.LoginTOTPRequiredResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "challenge_token": {
+                                    "type": "string",
+                                    "example": "kP8k2..."
+                                },
+                                "email_otp_challenge_token": {
+                                    "type": "string",
+                                    "example": "qA9j1..."
+                                },
+                                "email_otp_enabled": {
+                                    "type": "boolean",
+                                    "example": false
+                                },
+                                "email_otp_max_resend_per_hour": {
+                                    "type": "integer",
+                                    "example": 5
+                                },
+                                "email_otp_resend_cooldown_seconds": {
+                                    "type": "integer",
+                                    "example": 60
+                                },
+                                "linked_sso": {
+                                    "type": "boolean",
+                                    "example": false
+                                },
+                                "pin_configured": {
+                                    "type": "boolean",
+                                    "example": false
+                                },
+                                "requires_totp": {
+                                    "type": "boolean",
+                                    "example": true
+                                },
+                                "totp_enabled": {
+                                    "type": "boolean",
+                                    "example": true
+                                },
+                                "webauthn_configured": {
+                                    "type": "boolean",
+                                    "example": false
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_totp_required"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineAttributes": {
+            "type": "object",
+            "properties": {
+                "column": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "medicine_group": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupResource"
+                },
+                "medicine_group_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "motor_reaction": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResource"
+                },
+                "motor_reaction_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "motor_reaction_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                    ]
+                },
+                "motor_reactions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResource"
+                    }
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Paracetamol"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Main stock medicine"
+                },
+                "pack": {
+                    "type": "string",
+                    "example": "500mg"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "unit": {
+                    "type": "string",
+                    "example": "tablet"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "column": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "medicine_group_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "motor_reaction_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "motor_reaction_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                    ]
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Paracetamol"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Main stock medicine"
+                },
+                "pack": {
+                    "type": "string",
+                    "example": "500mg"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "unit": {
+                    "type": "string",
+                    "maxLength": 50,
+                    "example": "tablet"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "medicine_create",
+                        "medicine"
+                    ],
+                    "example": "medicine_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Spritze"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Spritze"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "medicine_group_create",
+                        "medicine_group"
+                    ],
+                    "example": "medicine_group_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "medicine_group"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Spritze"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "medicine_group_update",
+                        "medicine_group"
+                    ],
+                    "example": "medicine_group_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineGroupUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineGroupUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "medicine"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "column": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "medicine_group_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "motor_reaction_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "motor_reaction_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                    ]
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Paracetamol"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Main stock medicine"
+                },
+                "pack": {
+                    "type": "string",
+                    "example": "500mg"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "unit": {
+                    "type": "string",
+                    "maxLength": 50,
+                    "example": "tablet"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "medicine_update",
+                        "medicine"
+                    ],
+                    "example": "medicine_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MedicineUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MedicineUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MicrosoftCallbackResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "email": {
+                                    "type": "string",
+                                    "example": "user@example.com"
+                                },
+                                "provider": {
+                                    "type": "string",
+                                    "example": "microsoft"
+                                },
+                                "provider_subject": {
+                                    "type": "string",
+                                    "example": "00000000-0000-0000-0000-000000000000"
+                                }
+                            }
+                        },
+                        "id": {
+                            "type": "string",
+                            "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_identity"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MicrosoftLoginResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "redirect_url": {
+                                    "type": "string",
+                                    "example": "https://login.microsoftonline.com/..."
+                                },
+                                "url": {
+                                    "type": "string",
+                                    "example": "https://login.microsoftonline.com/..."
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_microsoft_url"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "gezielt auf Schmerzreiz"
+                },
+                "score": {
+                    "type": "integer",
+                    "example": 5
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "gezielt auf Schmerzreiz"
+                },
+                "score": {
+                    "type": "integer",
+                    "example": 5
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "motor_reaction_create",
+                        "motor_reaction"
+                    ],
+                    "example": "motor_reaction_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "motor_reaction"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "gezielt auf Schmerzreiz"
+                },
+                "score": {
+                    "type": "integer",
+                    "example": 5
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "motor_reaction_update",
+                        "motor_reaction"
+                    ],
+                    "example": "motor_reaction_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.MotorReactionUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.MotorReactionUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Primary operation control center"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Main OPC Base"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcCreateAttributes": {
+            "type": "object",
+            "required": [
+                "title"
+            ],
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Primary operation control center"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Main OPC Base"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "opc_create",
+                        "opc"
+                    ],
+                    "example": "opc_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "opc"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Primary operation control center"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Main OPC Base"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "opc_update",
+                        "opc"
+                    ],
+                    "example": "opc_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.OpcUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.OpcUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataAttributes": {
+            "type": "object",
+            "properties": {
+                "age": {
+                    "type": "integer",
+                    "example": 35
+                },
+                "birth_date": {
+                    "type": "string",
+                    "example": "1990-01-15"
+                },
+                "co_insured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "max.muster@example.com"
+                },
+                "family_name": {
+                    "type": "string",
+                    "example": "Muster"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "Max"
+                },
+                "gender": {
+                    "type": "string",
+                    "example": "male"
+                },
+                "insurance_patient_data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataInsuranceDetail"
+                },
+                "insurance_patient_data_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "opc": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataOPC"
+                },
+                "opc_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "phone": {
+                    "type": "string",
+                    "example": "+431234567"
+                },
+                "street": {
+                    "type": "string",
+                    "example": "Hauptstraße 1"
+                },
+                "svnr": {
+                    "type": "string",
+                    "example": "1234150190"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataCreateAttributes": {
+            "type": "object",
+            "required": [
+                "family_name",
+                "first_name",
+                "gender"
+            ],
+            "properties": {
+                "birth_date": {
+                    "type": "string",
+                    "example": "1990-01-15"
+                },
+                "co_insured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "email": {
+                    "type": "string",
+                    "example": "max.muster@example.com"
+                },
+                "family_name": {
+                    "type": "string",
+                    "example": "Muster"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "Max"
+                },
+                "gender": {
+                    "type": "string",
+                    "enum": [
+                        "male",
+                        "female"
+                    ],
+                    "example": "male"
+                },
+                "insurance_patient_data_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "opc_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "phone": {
+                    "type": "string",
+                    "example": "+431234567"
+                },
+                "street": {
+                    "type": "string",
+                    "example": "Hauptstraße 1"
+                },
+                "svnr": {
+                    "type": "string",
+                    "example": "1234150190"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "patient_data_create",
+                        "patient_data"
+                    ],
+                    "example": "patient_data_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataInsuranceDetail": {
+            "type": "object",
+            "properties": {
+                "federal_state": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataFederalState"
+                },
+                "federal_state_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "health_insurance_companies_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "health_insurance_company": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataHealthInsuranceCompany"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataOPC": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Primary OPC"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "patient_data"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "birth_date": {
+                    "type": "string",
+                    "example": "1990-01-15"
+                },
+                "co_insured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "email": {
+                    "type": "string",
+                    "example": "max.muster@example.com"
+                },
+                "family_name": {
+                    "type": "string",
+                    "example": "Muster"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "Max"
+                },
+                "gender": {
+                    "type": "string",
+                    "example": "male"
+                },
+                "insurance_patient_data_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "opc_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "phone": {
+                    "type": "string",
+                    "example": "+431234567"
+                },
+                "street": {
+                    "type": "string",
+                    "example": "Hauptstraße 1"
+                },
+                "svnr": {
+                    "type": "string",
+                    "example": "1234150190"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "patient_data_update",
+                        "patient_data"
+                    ],
+                    "example": "patient_data_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PatientDataUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PatientDataUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                },
+                "description": {
+                    "type": "string",
+                    "example": "Allows managing users."
+                },
+                "key": {
+                    "type": "string",
+                    "example": "user.manage"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "User Management"
+                },
+                "requires_pin": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionGroupResource": {
+            "type": "object",
+            "properties": {
+                "module": {
+                    "type": "string",
+                    "example": "dul"
+                },
+                "module_label": {
+                    "type": "string",
+                    "example": "DUL"
+                },
+                "permissions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionGroupedResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionGroupResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionMini": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "example": "Permission to view users."
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9a"
+                },
+                "key": {
+                    "type": "string",
+                    "example": "users.read"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "View Users"
+                },
+                "requires_pin": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "permission"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionUpdateAttributes": {
+            "type": "object",
+            "required": [
+                "requires_pin"
+            ],
+            "properties": {
+                "requires_pin": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "permission_update",
+                        "permission"
+                    ],
+                    "example": "permission_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PermissionUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PilotProfileAttributes": {
+            "type": "object",
+            "properties": {
+                "double_command_minutes": {
+                    "type": "integer"
+                },
+                "dul_base": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULBase"
+                    }
+                },
+                "flight_instructor_minutes": {
+                    "type": "integer"
+                },
+                "has_ifr_qualification": {
+                    "type": "boolean"
+                },
+                "ifr_flight_minutes": {
+                    "type": "integer"
+                },
+                "is_chief_pilot": {
+                    "type": "boolean"
+                },
+                "license_expired_at": {
+                    "type": "string"
+                },
+                "license_issued_at": {
+                    "type": "string"
+                },
+                "license_no": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "night_flight_minutes": {
+                    "type": "integer"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "pilot_category": {
+                    "type": "string",
+                    "enum": [
+                        "regular",
+                        "freelance",
+                        "dry_lease"
+                    ]
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "responsible_pilot_minutes": {
+                    "type": "integer"
+                },
+                "second_pilot_minutes": {
+                    "type": "integer"
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "technician_license_no": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "total_flight_minutes": {
+                    "type": "integer"
+                },
+                "weight_kg": {
+                    "type": "number"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.PilotProfileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "double_command_minutes": {
+                    "type": "integer"
+                },
+                "dul_base": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.DULBase"
+                    }
+                },
+                "flight_instructor_minutes": {
+                    "type": "integer"
+                },
+                "has_ifr_qualification": {
+                    "type": "boolean"
+                },
+                "ifr_flight_minutes": {
+                    "type": "integer"
+                },
+                "is_chief_pilot": {
+                    "type": "boolean"
+                },
+                "license_expired_at": {
+                    "type": "string"
+                },
+                "license_issued_at": {
+                    "type": "string"
+                },
+                "license_no": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "night_flight_minutes": {
+                    "type": "integer"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "pilot_category": {
+                    "type": "string",
+                    "enum": [
+                        "regular",
+                        "freelance",
+                        "dry_lease"
+                    ]
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "responsible_pilot_minutes": {
+                    "type": "integer"
+                },
+                "second_pilot_minutes": {
+                    "type": "integer"
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "technician_license_no": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "total_flight_minutes": {
+                    "type": "integer"
+                },
+                "weight_kg": {
+                    "type": "number"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ReauthAttributes": {
+            "type": "object",
+            "required": [
+                "method"
+            ],
+            "properties": {
+                "method": {
+                    "type": "string",
+                    "enum": [
+                        "pin",
+                        "password"
+                    ],
+                    "example": "pin"
+                },
+                "password": {
+                    "type": "string",
+                    "minLength": 1,
+                    "example": "StrongP@ssw0rd"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RegisterAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "first_name",
+                "last_name",
+                "password",
+                "username"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "password": {
+                    "type": "string",
+                    "minLength": 8,
+                    "example": "StrongP@ssw0rd"
+                },
+                "username": {
+                    "type": "string",
+                    "maxLength": 100,
+                    "minLength": 3,
+                    "example": "john.doe"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RegisterData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RegisterAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_register"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RegisterRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RegisterData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RequestSecurityPINAttributes": {
+            "type": "object",
+            "properties": {
+                "method": {
+                    "type": "string",
+                    "example": "password"
+                },
+                "password": {
+                    "type": "string",
+                    "example": "StrongP@ssw0rd"
+                },
+                "reauth_token": {
+                    "type": "string",
+                    "example": "sso_reauth_1234567890abcdef"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RequestSecurityPINData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RequestSecurityPINAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_pin_request_reset"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RequestSecurityPINRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RequestSecurityPINData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RequestSecurityPINResetResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "message": {
+                                    "type": "string",
+                                    "example": "If allowed, a security PIN reset link has been sent to your email."
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_pin_request_reset"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResendSetPasswordInviteAttributes": {
+            "type": "object",
+            "required": [
+                "user_id"
+            ],
+            "properties": {
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResendSetPasswordInviteData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ResendSetPasswordInviteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_resend_set_password"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResendSetPasswordInviteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ResendSetPasswordInviteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResetPasswordAttributes": {
+            "type": "object",
+            "required": [
+                "confirm_password",
+                "new_password",
+                "token"
+            ],
+            "properties": {
+                "confirm_password": {
+                    "type": "string",
+                    "minLength": 8,
+                    "example": "StrongP@ssw0rd!LongPassphrase"
+                },
+                "new_password": {
+                    "type": "string",
+                    "minLength": 8,
+                    "example": "StrongP@ssw0rd!LongPassphrase"
+                },
+                "token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResetPasswordData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ResetPasswordAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_reset_password"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResetPasswordRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ResetPasswordData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResetSecurityPINAttributes": {
+            "type": "object",
+            "required": [
+                "confirm_pin",
+                "new_pin"
+            ],
+            "properties": {
+                "confirm_pin": {
+                    "type": "string",
+                    "example": "123456"
+                },
+                "method": {
+                    "type": "string",
+                    "example": "password"
+                },
+                "new_pin": {
+                    "type": "string",
+                    "example": "123456"
+                },
+                "password": {
+                    "type": "string",
+                    "example": "StrongP@ssw0rd"
+                },
+                "reauth_token": {
+                    "type": "string",
+                    "example": "sso_reauth_1234567890abcdef"
+                },
+                "token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResetSecurityPINData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ResetSecurityPINAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_reset_pin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.ResetSecurityPINRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ResetSecurityPINData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "description": {
+                    "type": "string",
+                    "example": "Full access to all resources."
+                },
+                "name": {
+                    "type": "string",
+                    "example": "admin"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "example": "Full access to all resources."
+                },
+                "name": {
+                    "type": "string",
+                    "example": "admin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "role_create",
+                        "role"
+                    ],
+                    "example": "role_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleMini": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "example": "Full access to all resources."
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "admin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionAssignAttributes": {
+            "type": "object",
+            "required": [
+                "permission_id"
+            ],
+            "properties": {
+                "permission_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionAssignBulkData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionBulkAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role_assign_permission_bulk"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionAssignBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignBulkData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionAssignData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role_permission"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionAssignRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionAttributes": {
+            "type": "object",
+            "properties": {
+                "permission_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionBulkAttributes": {
+            "type": "object",
+            "required": [
+                "permission_ids"
+            ],
+            "properties": {
+                "permission_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "[\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e\"",
+                        "\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f\"]"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionRemoveBulkData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionBulkAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role_remove_permission_bulk"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionRemoveBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionRemoveBulkData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role_permission"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RolePermissionResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RolePermissionResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "permissions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.PermissionResource"
+                    }
+                },
+                "type": {
+                    "type": "string",
+                    "example": "role"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "example": "Full access to all resources."
+                },
+                "name": {
+                    "type": "string",
+                    "example": "admin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "role_update",
+                        "role"
+                    ],
+                    "example": "role_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.RoleUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOLinkAttributes": {
+            "type": "object",
+            "required": [
+                "code",
+                "provider"
+            ],
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "0.AXkA..."
+                },
+                "provider": {
+                    "type": "string",
+                    "example": "microsoft"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOLinkData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOLinkAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_sso_link"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOLinkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOLinkData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOLinkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "email": {
+                                    "type": "string",
+                                    "example": "user@example.com"
+                                },
+                                "provider": {
+                                    "type": "string",
+                                    "example": "microsoft"
+                                },
+                                "provider_subject": {
+                                    "type": "string",
+                                    "example": "00000000-0000-0000-0000-000000000000"
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_sso_link"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOUnlinkAttributes": {
+            "type": "object",
+            "required": [
+                "provider"
+            ],
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "example": "microsoft"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOUnlinkData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOUnlinkAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_sso_unlink"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOUnlinkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SSOUnlinkData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SSOUnlinkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "provider": {
+                                    "type": "string",
+                                    "example": "microsoft"
+                                },
+                                "unlinked": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_sso_unlink"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINChangeAttributes": {
+            "type": "object",
+            "required": [
+                "confirm_pin",
+                "current_pin",
+                "new_pin"
+            ],
+            "properties": {
+                "confirm_pin": {
+                    "type": "string",
+                    "example": "654321"
+                },
+                "current_pin": {
+                    "type": "string",
+                    "example": "123456"
+                },
+                "new_pin": {
+                    "type": "string",
+                    "example": "654321"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINChangeData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINChangeAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_pin_change"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINChangeRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINChangeData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINSetupAttributes": {
+            "type": "object",
+            "required": [
+                "confirm_pin",
+                "pin"
+            ],
+            "properties": {
+                "confirm_pin": {
+                    "type": "string",
+                    "example": "123456"
+                },
+                "pin": {
+                    "type": "string",
+                    "example": "123456"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINSetupData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINSetupAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_pin_setup"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINSetupRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINSetupData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINSetupResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "configured": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_pin_setup"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINVerifyAttributes": {
+            "type": "object",
+            "required": [
+                "action",
+                "pin"
+            ],
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "example": "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"
+                },
+                "pin": {
+                    "type": "string",
+                    "example": "123456"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINVerifyData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINVerifyAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_pin_verify"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINVerifyRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SecurityPINVerifyData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SecurityPINVerifyResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "action_token": {
+                                    "type": "string",
+                                    "example": "pinv_1234567890abcdef"
+                                },
+                                "action_token_ttl_ms": {
+                                    "type": "integer",
+                                    "example": 900000
+                                },
+                                "verified": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_pin_verify"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SetPasswordAttributes": {
+            "type": "object",
+            "required": [
+                "password",
+                "token"
+            ],
+            "properties": {
+                "password": {
+                    "type": "string",
+                    "minLength": 8,
+                    "example": "StrongP@ssw0rd"
+                },
+                "token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SetPasswordData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SetPasswordAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_set_password"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.SetPasswordRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.SetPasswordData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.StaffProfileAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "role_label": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.StaffProfileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "role_label": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPConfirmAttributes": {
+            "type": "object",
+            "required": [
+                "code",
+                "user_id"
+            ],
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "123456"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPConfirmData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPConfirmAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_confirm"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPConfirmRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPConfirmData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPDisableAttributes": {
+            "type": "object",
+            "required": [
+                "user_id"
+            ],
+            "properties": {
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPDisableData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPDisableAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_disable"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPDisableRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPDisableData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPResetSetupData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ReauthAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_reset_setup"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPResetSetupRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPResetSetupData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPSetupAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "user_id"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPSetupData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPSetupAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_setup"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPSetupRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPSetupData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPSetupResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "issuer": {
+                                    "type": "string",
+                                    "example": "Wucher"
+                                },
+                                "otpauth_url": {
+                                    "type": "string",
+                                    "example": "otpauth://totp/Wucher:user@example.com?..."
+                                },
+                                "secret": {
+                                    "type": "string",
+                                    "example": "JBSWY3DPEHPK3PXP"
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_totp_setup"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPVerifyAttributes": {
+            "type": "object",
+            "required": [
+                "challenge_token",
+                "code"
+            ],
+            "properties": {
+                "challenge_token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                },
+                "code": {
+                    "type": "string",
+                    "example": "123456"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPVerifyData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPVerifyAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_totp_verify"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TOTPVerifyRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TOTPVerifyData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TechnicianProfileAttributes": {
+            "type": "object",
+            "properties": {
+                "is_chief_technician": {
+                    "type": "boolean"
+                },
+                "is_responsible_complaints": {
+                    "type": "boolean"
+                },
+                "license_no": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TechnicianProfileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "is_chief_technician": {
+                    "type": "boolean"
+                },
+                "is_responsible_complaints": {
+                    "type": "boolean"
+                },
+                "license_no": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "location": {
+                    "type": "string",
+                    "maxLength": 255
+                },
+                "note": {
+                    "type": "string"
+                },
+                "postcode": {
+                    "type": "string",
+                    "maxLength": 32
+                },
+                "short_name": {
+                    "type": "string",
+                    "maxLength": 120
+                },
+                "street_line": {
+                    "type": "string",
+                    "maxLength": 255
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TimezoneUpdateAttributes": {
+            "type": "object",
+            "required": [
+                "timezone"
+            ],
+            "properties": {
+                "timezone": {
+                    "type": "string",
+                    "example": "Asia/Jakarta"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TimezoneUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TimezoneUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_timezone_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TimezoneUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.TimezoneUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.TokenResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "access_expires_in": {
+                                    "type": "integer",
+                                    "example": 900
+                                },
+                                "refresh_expires_in": {
+                                    "type": "integer",
+                                    "example": 2592000
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_tokens"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserAttributes": {
+            "type": "object",
+            "properties": {
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "email_verified_at": {
+                    "type": "string",
+                    "example": "2026-02-05T10:00:00Z"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "is_previously_configured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "linked_sso": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "pin_configured": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "profile_picture": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserImage"
+                },
+                "role": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleMini"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "role_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "[\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d\"",
+                        "\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e\"]"
+                    ]
+                },
+                "roles": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.RoleMini"
+                    }
+                },
+                "timezone": {
+                    "type": "string",
+                    "example": "Asia/Jakarta"
+                },
+                "totp_enabled": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "username": {
+                    "type": "string",
+                    "example": "john.doe"
+                },
+                "webauthn_configured": {
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserCreateAttributes": {
+            "type": "object",
+            "required": [
+                "email",
+                "first_name",
+                "last_name",
+                "role_id",
+                "username"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "image_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "role_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "role_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "[\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d\"",
+                        "\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e\"]"
+                    ]
+                },
+                "timezone": {
+                    "type": "string",
+                    "example": "Asia/Jakarta"
+                },
+                "username": {
+                    "type": "string",
+                    "maxLength": 100,
+                    "minLength": 3,
+                    "example": "john.doe"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "user_create",
+                        "user"
+                    ],
+                    "example": "user_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserFoto": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/base/lude.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Expires=900\u0026X-Amz-Signature=abc123"
+                },
+                "original_size_bytes": {
+                    "type": "integer",
+                    "example": 1024000
+                },
+                "thumbnail_download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/base/lude.thumb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Expires=900\u0026X-Amz-Signature=abc123"
+                },
+                "uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserImage": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://example.com/presigned-url"
+                },
+                "original_size_bytes": {
+                    "type": "integer",
+                    "example": 1024000
+                },
+                "thumbnail_download_url": {
+                    "type": "string",
+                    "example": "https://example.com/presigned-thumb-url"
+                },
+                "uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.UserResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "user"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto.UserAttributes"
+                        },
+                        "id": {
+                            "type": "string",
+                            "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "user"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "image_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+628123456789"
+                },
+                "timezone": {
+                    "type": "string",
+                    "example": "Asia/Jakarta"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "user_update",
+                        "user"
+                    ],
+                    "example": "user_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.UserUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.UserUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VerifyEmailResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "verified": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_verify_email"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Pilot"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Helicopter pilot vocation"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Pilot"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Helicopter pilot vocation"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "vocation_create",
+                        "vocation"
+                    ],
+                    "example": "vocation_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "vocation"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Pilot"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Helicopter pilot vocation"
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "vocation_update",
+                        "vocation"
+                    ],
+                    "example": "vocation_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.VocationUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.VocationUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnBeginResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "challenge_token": {
+                                    "type": "string",
+                                    "example": "kP8k2..."
+                                },
+                                "challenge_ttl_ms": {
+                                    "type": "integer",
+                                    "example": 300000
+                                },
+                                "public_key": {
+                                    "type": "object",
+                                    "additionalProperties": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_webauthn_register_options"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnLoginBeginAttributes": {
+            "type": "object",
+            "required": [
+                "email"
+            ],
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "user@example.com"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnLoginBeginData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginBeginAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_webauthn_login_begin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnLoginBeginRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginBeginData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnLoginFinishAttributes": {
+            "type": "object",
+            "required": [
+                "challenge_token",
+                "credential"
+            ],
+            "properties": {
+                "challenge_token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                },
+                "credential": {
+                    "type": "array",
+                    "items": {
+                        "type": "integer"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnLoginFinishData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginFinishAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_webauthn_login_finish"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnLoginFinishRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginFinishData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnRegisterBeginData": {
+            "type": "object",
+            "required": [
+                "type"
+            ],
+            "properties": {
+                "type": {
+                    "type": "string",
+                    "example": "auth_webauthn_register_begin"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnRegisterBeginRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterBeginData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnRegisterFinishAttributes": {
+            "type": "object",
+            "required": [
+                "challenge_token",
+                "credential"
+            ],
+            "properties": {
+                "challenge_token": {
+                    "type": "string",
+                    "example": "kP8k2..."
+                },
+                "credential": {
+                    "type": "array",
+                    "items": {
+                        "type": "integer"
+                    }
+                },
+                "name": {
+                    "type": "string",
+                    "maxLength": 100,
+                    "example": "MacBook Touch ID"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnRegisterFinishData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterFinishAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_webauthn_register_finish"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnRegisterFinishRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterFinishData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnResetSetupData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.ReauthAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "auth_webauthn_reset_setup"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnResetSetupRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto.WebAuthnResetSetupData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto.WebAuthnResetSetupResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "reset": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "auth_webauthn_reset_setup"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ActionSignoffSignAttributes": {
+            "type": "object",
+            "properties": {
+                "complaint_id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "flight_id": {
+                    "description": "FlightID — REQUIRED for the fleet (complaint-independent) sign-off; scopes it to a\nflight so it no longer leaks across takeovers of the same aircraft. Ignored when\ncomplaint_id is set (that sign-off is keyed by the complaint).",
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "sign": {
+                    "description": "Sign toggles the sign-off: true (or omitted) signs it, false unsigns (clears the\nsignature). Combine with complaint_id to toggle a specific complaint's sign-off.",
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ActionSignoffSignData": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ActionSignoffSignAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "action_signoff"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ActionSignoffSignRequest": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ActionSignoffSignData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateAttributes": {
+            "type": "object",
+            "required": [
+                "base_id",
+                "checklists"
+            ],
+            "properties": {
+                "base_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "checklists": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateEntry"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "air_rescuer_checklist_create"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateEntry": {
+            "type": "object",
+            "required": [
+                "scope_code",
+                "title"
+            ],
+            "properties": {
+                "items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistItemInput"
+                    }
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "scope_code": {
+                    "type": "string",
+                    "example": "MO"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Monday Checklist"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateAttributes": {
+            "type": "object",
+            "required": [
+                "items"
+            ],
+            "properties": {
+                "items": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistItemInput"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "air_rescuer_checklist_item_create"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderAttributes": {
+            "type": "object",
+            "required": [
+                "items"
+            ],
+            "properties": {
+                "items": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderEntry"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "air_rescuer_checklist_item_reorder"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderEntry": {
+            "type": "object",
+            "required": [
+                "item_uuid",
+                "position"
+            ],
+            "properties": {
+                "item_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 2
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Check radio"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 2
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "air_rescuer_checklist_item_update"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "new_items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistItemInput"
+                    }
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "scope_code": {
+                    "type": "string",
+                    "example": "MO"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Monday Checklist Updated"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "air_rescuer_checklist_update"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintActionTakenAttributes": {
+            "type": "object",
+            "properties": {
+                "action_taken": {
+                    "description": "ActionTaken — corrective action text. Required when recording (create); on update an\nempty value clears it (allowed only while the action has not been signed off).",
+                    "type": "string",
+                    "example": "Tightened engine mount and rechecked torque"
+                },
+                "aircraft_hours_at_fix": {
+                    "type": "string",
+                    "example": "1250.1"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintActionTakenData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintActionTakenAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "complaint_action_taken",
+                        "complaint"
+                    ],
+                    "example": "complaint_action_taken"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintActionTakenRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintActionTakenData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintCreateAttributes": {
+            "type": "object",
+            "required": [
+                "description",
+                "helicopter_id"
+            ],
+            "properties": {
+                "aircraft_hours_at_report": {
+                    "description": "AircraftHoursAtReport — OPTIONAL airframe hours recorded when the defect was reported.",
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "description": {
+                    "description": "Description — the defect description. REQUIRED.",
+                    "type": "string",
+                    "example": "Engine 2 N2 vibration intermittent during cruise above 110 KIAS"
+                },
+                "flight_id": {
+                    "description": "FlightID — the flight/report this complaint was filed in (attribution). OPTIONAL;\nopen-defect tracking stays per-helicopter so defects carry forward across flights.",
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "helicopter_id": {
+                    "description": "HelicopterID — the helicopter this complaint is filed against. REQUIRED.",
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "mel_severity": {
+                    "description": "MELSeverity — MEL (Minimum Equipment List) classification. OPTIONAL at creation:\nomit it to file the complaint as \"pending_mel\" and classify later. It MUST be\nclassified (via update) before recording action taken. A pending complaint does\nNOT ground the aircraft — grounding starts at classification. Values: 0 = NON-MEL\n(grounds immediately), 1 = A (grace 1 day), 2 = B (3 days), 3 = C (10 days), 4 = D (120 days).",
+                    "type": "integer",
+                    "enum": [
+                        0,
+                        1,
+                        2,
+                        3,
+                        4
+                    ],
+                    "example": 2
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "complaint_create",
+                        "complaint"
+                    ],
+                    "example": "complaint_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintNSRSignAttributes": {
+            "type": "object",
+            "properties": {
+                "nsr_reason": {
+                    "description": "NSRReason — OPTIONAL free-text justification for the NSR (MEL deferral) decision.",
+                    "type": "string",
+                    "example": "Released under MEL A, defect deferred"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintNSRSignData": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintNSRSignAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "complaint_nsr_sign",
+                        "complaint_nsr"
+                    ],
+                    "example": "complaint_nsr_sign"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintNSRSignRequest": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintNSRSignData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "aircraft_hours_at_report": {
+                    "description": "AircraftHoursAtReport — airframe hours at report time.",
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "description": {
+                    "description": "Description — defect description.",
+                    "type": "string",
+                    "example": "Engine 2 vibration confirmed"
+                },
+                "mel_severity": {
+                    "description": "MELSeverity — MEL classification. 0 = NON-MEL (immediate AOG), 1 = A (1 day),\n2 = B (3 days), 3 = C (10 days), 4 = D (120 days). AOG after grace passes.",
+                    "type": "integer",
+                    "enum": [
+                        0,
+                        1,
+                        2,
+                        3,
+                        4
+                    ],
+                    "example": 2
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "id",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "complaint_update",
+                        "complaint"
+                    ],
+                    "example": "complaint_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ComplaintUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ComplaintUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterAnyDeleteData": {
+            "type": "object",
+            "required": [
+                "id"
+            ],
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterAnyDeleteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterAnyDeleteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterCreateAttributes": {
+            "type": "object",
+            "required": [
+                "base_id",
+                "duty_date"
+            ],
+            "properties": {
+                "base_id": {
+                    "type": "string"
+                },
+                "duty_date": {
+                    "type": "string"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDetailsInput"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterShiftTime"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "duty_roster_create",
+                        "duty_roster"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterCrewInput": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "shift_date": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterShiftDate"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewAttributes": {
+            "type": "object",
+            "properties": {
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDetailsInput"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDAttributes": {
+            "type": "object",
+            "required": [
+                "crew_id",
+                "roster_id"
+            ],
+            "properties": {
+                "crew_id": {
+                    "type": "string"
+                },
+                "roster_id": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "duty_roster_crew_delete",
+                        "duty_roster_update",
+                        "duty_roster"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "duty_roster_crew_delete",
+                        "duty_roster_update",
+                        "duty_roster"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterDetailsInput": {
+            "type": "object",
+            "properties": {
+                "doctor": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCrewInput"
+                    }
+                },
+                "helper": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCrewInput"
+                    }
+                },
+                "other_person": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterOtherPersonInput"
+                    }
+                },
+                "pilot": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterPilotCrewInput"
+                    }
+                },
+                "rescuer": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCrewInput"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterOtherPersonInput": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "guest@example.com"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Guest Person"
+                },
+                "other_person_id": {
+                    "description": "OtherPersonID — OPTIONAL master person id to reuse (from GET /contact/other).\nWhen set, name/mobile_phone/email are snapshotted from the master (may be omitted).",
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterPilotCrewInput": {
+            "type": "object",
+            "properties": {
+                "co_pilot": {
+                    "type": "boolean"
+                },
+                "crew_type": {
+                    "type": "string",
+                    "enum": [
+                        "main",
+                        "additional"
+                    ],
+                    "example": "main"
+                },
+                "examiner": {
+                    "type": "boolean"
+                },
+                "flight_instructor": {
+                    "type": "boolean"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "line_checker": {
+                    "type": "boolean"
+                },
+                "shift_date": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterShiftDate"
+                },
+                "supervisor": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterShiftDate": {
+            "type": "object",
+            "properties": {
+                "date_end": {
+                    "type": "string",
+                    "example": "2026-03-16"
+                },
+                "date_start": {
+                    "type": "string",
+                    "example": "2026-03-16"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterShiftTime": {
+            "type": "object",
+            "properties": {
+                "shift_end": {
+                    "type": "string",
+                    "example": "21:00"
+                },
+                "shift_start": {
+                    "type": "string",
+                    "example": "06:00"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "base_id": {
+                    "type": "string"
+                },
+                "duty_date": {
+                    "type": "string"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDetailsInput"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterShiftTime"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterUpdateAttributes"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "duty_roster_update",
+                        "duty_roster"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.DutyRosterUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.DutyRosterUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.EASAReleaseCreateAttributes": {
+            "type": "object",
+            "required": [
+                "helicopter_id"
+            ],
+            "properties": {
+                "complaint_id": {
+                    "description": "ComplaintID — OPTIONAL complaint (UUIDv7) this release closes. Set it to scope the\nrelease to a specific defect; leave empty for a standalone (aircraft-clear) release.",
+                    "type": "string",
+                    "example": "019d6774-1111-7fba-9ef4-3795c0da8a13"
+                },
+                "easa_ac_hours": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "easa_date": {
+                    "type": "string",
+                    "example": "2026-06-16"
+                },
+                "easa_location": {
+                    "type": "string",
+                    "example": "LOWI"
+                },
+                "easa_maint_manual_rev_airframe": {
+                    "type": "string",
+                    "example": "Rev 12"
+                },
+                "easa_maint_manual_rev_engine": {
+                    "type": "string",
+                    "example": "Rev 8"
+                },
+                "easa_permit_no": {
+                    "type": "string",
+                    "example": "145.A.50"
+                },
+                "easa_signer_id": {
+                    "description": "EASASignerID — OPTIONAL contact id (UUIDv7) of the signer/technician. Required only to sign.",
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "easa_wo_no": {
+                    "type": "string",
+                    "example": "WO-2026-001"
+                },
+                "flight_id": {
+                    "description": "FlightID — OPTIONAL flight context. Used for the standalone (no-complaint) sign-off gate.",
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "sign": {
+                    "description": "Sign, when true, signs the release immediately at creation. Requires all\nrequired fields to be present; otherwise the request is rejected.",
+                    "type": "boolean",
+                    "example": false
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.EASAReleaseCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "easa_release_create",
+                        "easa_release"
+                    ],
+                    "example": "easa_release_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.EASAReleaseCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.EASAReleaseUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "easa_ac_hours": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "easa_date": {
+                    "type": "string",
+                    "example": "2026-06-16"
+                },
+                "easa_location": {
+                    "type": "string",
+                    "example": "LOWI"
+                },
+                "easa_maint_manual_rev_airframe": {
+                    "type": "string",
+                    "example": "Rev 12"
+                },
+                "easa_maint_manual_rev_engine": {
+                    "type": "string",
+                    "example": "Rev 8"
+                },
+                "easa_permit_no": {
+                    "type": "string",
+                    "example": "145.A.50"
+                },
+                "easa_signer_id": {
+                    "description": "EASASignerID — OPTIONAL contact id (UUIDv7) of the signer/technician. Required only to sign.",
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "easa_wo_no": {
+                    "type": "string",
+                    "example": "WO-2026-001"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.EASAReleaseUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "id",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "easa_release_update",
+                        "easa_release"
+                    ],
+                    "example": "easa_release_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.EASAReleaseUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FMReportUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "engine1_gpc_n1": {
+                    "description": "Engine1GpcN1 - GPC/N1 value for engine 1. Optional.",
+                    "type": "string",
+                    "example": "GPC/N1 63.2"
+                },
+                "engine1_ptc_n2": {
+                    "description": "Engine1PtcN2 - PTC/N2 value for engine 1. Optional.",
+                    "type": "string",
+                    "example": "PTC/N2 61.8"
+                },
+                "engine2_gpc_n1": {
+                    "description": "Engine2GpcN1 - GPC/N1 value for engine 2. Optional.",
+                    "type": "string",
+                    "example": "GPC/N1 63.2"
+                },
+                "engine2_ptc_n2": {
+                    "description": "Engine2PtcN2 - PTC/N2 value for engine 2. Optional.",
+                    "type": "string",
+                    "example": "PTC/N2 61.8"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FMReportUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FMReportUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "fm_report_update",
+                        "fm_report"
+                    ],
+                    "example": "fm_report_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FMReportUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FMReportUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateAttributes": {
+            "type": "object",
+            "required": [
+                "file_id",
+                "ref_id",
+                "ref_type"
+            ],
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "example": "document"
+                },
+                "file_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_primary": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "ref_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "ref_type": {
+                    "type": "string",
+                    "example": "helicopter"
+                },
+                "sort_order": {
+                    "type": "integer",
+                    "example": 0
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_attachment_create",
+                        "file_manager_attachment"
+                    ],
+                    "example": "file_manager_attachment_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileAircraftBulkCreateItem": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileAircraftCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_create",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileAircraftBulkCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileAircraftBulkCreateItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileAircraftCreateAttributes": {
+            "type": "object",
+            "required": [
+                "aircraft_uuid",
+                "name",
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "aircraft_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "aircraft.jpg"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileBaseBulkCreateItem": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileBaseCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_create",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileBaseBulkCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileBaseBulkCreateItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileBaseCreateAttributes": {
+            "type": "object",
+            "required": [
+                "base_uuid",
+                "name",
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "base_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "base.jpg"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadAttributes": {
+            "type": "object",
+            "required": [
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_cancel_upload"
+                    ],
+                    "example": "file_manager_file_cancel_upload"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileDULBulkCreateItem": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileDULCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_create",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileDULBulkCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileDULBulkCreateItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileDULCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name",
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "dul_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "dul.jpg"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileMissionBulkCreateItem": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileMissionCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_create",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileMissionBulkCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileMissionBulkCreateItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileMissionCreateAttributes": {
+            "type": "object",
+            "required": [
+                "mission_uuid",
+                "name",
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "mission_uuid": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "mission-brief.pdf"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileTakeoverBulkCreateItem": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTakeoverCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_create",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileTakeoverBulkCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTakeoverBulkCreateItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileTakeoverCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name",
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "takeover-report.pdf"
+                },
+                "takeover_uuid": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileTemplateCreateAttributes": {
+            "type": "object",
+            "required": [
+                "helicopter_id",
+                "name",
+                "template_uuid"
+            ],
+            "properties": {
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "collabora-draft.docx"
+                },
+                "takeover_id": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                },
+                "template_uuid": {
+                    "type": "string",
+                    "example": "019f0386-0a00-7a4a-a2d8-30afc0e0c3ad"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileTemplateCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "required": [
+                        "attributes",
+                        "type"
+                    ],
+                    "properties": {
+                        "attributes": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTemplateCreateAttributes"
+                        },
+                        "type": {
+                            "type": "string",
+                            "enum": [
+                                "file_manager_file_create_from_template",
+                                "file_manager_file_create"
+                            ]
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "folder_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "policy-v2.pdf"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_update",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentAttributes": {
+            "type": "object",
+            "required": [
+                "content_type",
+                "name",
+                "size_bytes"
+            ],
+            "properties": {
+                "content_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "policy-final.pdf"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "example": 1024
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_upload_intent"
+                    ],
+                    "example": "file_manager_file_upload_intent"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateItem": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUserCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_file_create",
+                        "file_manager_file"
+                    ],
+                    "example": "file_manager_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFileUserCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name",
+                "upload_intent_uuid",
+                "user_uuid"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "profile.jpg"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "user_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFolderCreateAttributes": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "operations"
+                },
+                "parent_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFolderCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_folder_create",
+                        "file_manager_folder"
+                    ],
+                    "example": "file_manager_folder_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFolderCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFolderUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "operations-updated"
+                },
+                "parent_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFolderUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "file_manager_folder_update",
+                        "file_manager_folder"
+                    ],
+                    "example": "file_manager_folder_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerFolderUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerNodeMoveBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodeMoveItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerNodeMoveItem": {
+            "type": "object",
+            "required": [
+                "uuid"
+            ],
+            "properties": {
+                "destination_folder_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerNodePurgeBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodePurgeItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FileManagerNodePurgeItem": {
+            "type": "object",
+            "required": [
+                "uuid"
+            ],
+            "properties": {
+                "uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusCreateAttributes": {
+            "type": "object",
+            "required": [
+                "helicopter_id"
+            ],
+            "properties": {
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusFileAttributes"
+                    }
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "maintenance_schedules": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "fleet_status_create",
+                        "fleet_status"
+                    ],
+                    "example": "fleet_status_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusSummaryAirframeUpdate": {
+            "type": "object",
+            "properties": {
+                "cycles": {
+                    "type": "number",
+                    "example": 320
+                },
+                "hours": {
+                    "type": "number",
+                    "example": 6610.5
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusSummaryEngineUpdate": {
+            "type": "object",
+            "properties": {
+                "ccc": {
+                    "type": "number",
+                    "example": 44
+                },
+                "gpc_ng_n1": {
+                    "type": "number",
+                    "example": 98.7
+                },
+                "hours": {
+                    "type": "number",
+                    "example": 8001.7
+                },
+                "ptc_nf_n2": {
+                    "type": "number",
+                    "example": 97.2
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusSummaryUpdate": {
+            "type": "object",
+            "properties": {
+                "airframe": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusSummaryAirframeUpdate"
+                },
+                "engine_1": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusSummaryEngineUpdate"
+                },
+                "engine_2": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusSummaryEngineUpdate"
+                },
+                "flight_reports": {
+                    "type": "number",
+                    "example": 80
+                },
+                "hook_releases": {
+                    "type": "number",
+                    "example": 10
+                },
+                "landings": {
+                    "type": "number",
+                    "example": 120
+                },
+                "rotor_brake_cycles": {
+                    "type": "number",
+                    "example": 8
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusFileAttributes"
+                    }
+                },
+                "helicopter_id": {
+                    "type": "string"
+                },
+                "maintenance_schedules": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes"
+                    }
+                },
+                "summary": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusSummaryUpdate"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "fleet_status_update",
+                        "fleet_status"
+                    ],
+                    "example": "fleet_status_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FleetStatusUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FleetStatusUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateAttributes": {
+            "type": "object",
+            "required": [
+                "mission_id"
+            ],
+            "properties": {
+                "co_pilot_id": {
+                    "type": "string"
+                },
+                "customer_name": {
+                    "type": "string"
+                },
+                "delivery_note_number": {
+                    "type": "string"
+                },
+                "engine": {
+                    "type": "string"
+                },
+                "flight_duration_seconds": {
+                    "type": "integer"
+                },
+                "flight_landing": {
+                    "type": "string"
+                },
+                "flight_plan_distance": {
+                    "type": "number"
+                },
+                "flight_plan_time_seconds": {
+                    "type": "integer"
+                },
+                "flight_plan_true_course": {
+                    "type": "number"
+                },
+                "flight_positioning": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "flight_red_seconds": {
+                    "type": "integer"
+                },
+                "flight_take_off": {
+                    "type": "string"
+                },
+                "from_hospital_id": {
+                    "type": "string"
+                },
+                "from_icao_id": {
+                    "type": "string"
+                },
+                "fuel_after_flight": {
+                    "type": "number"
+                },
+                "fuel_before_flight": {
+                    "type": "number"
+                },
+                "fuel_planning": {
+                    "type": "number"
+                },
+                "fuel_upload": {
+                    "type": "number"
+                },
+                "hec": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECAttributes"
+                },
+                "heslo": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOAttributes"
+                },
+                "hook_releases": {
+                    "type": "integer"
+                },
+                "landing_count": {
+                    "type": "integer"
+                },
+                "logging": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOLoggingAttributes"
+                },
+                "max_n1": {
+                    "type": "number"
+                },
+                "max_n2": {
+                    "type": "number"
+                },
+                "mission_id": {
+                    "type": "string"
+                },
+                "other_information": {
+                    "type": "string"
+                },
+                "pax_count": {
+                    "type": "integer"
+                },
+                "rotor_brake_cycle": {
+                    "type": "integer"
+                },
+                "ticket_no": {
+                    "type": "string"
+                },
+                "to_hospital_id": {
+                    "type": "string"
+                },
+                "to_icao_id": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "flight_data_create",
+                        "flight_data"
+                    ],
+                    "example": "flight_data_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECAttributes": {
+            "type": "object",
+            "properties": {
+                "flights": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECFlight"
+                    }
+                },
+                "loads": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECLoad"
+                    }
+                },
+                "slings": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECSling"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECFlight": {
+            "type": "object",
+            "properties": {
+                "equipment_id": {
+                    "description": "Facility category: hec-rope-label.",
+                    "type": "string",
+                    "example": "string"
+                },
+                "equipment_name": {
+                    "type": "string",
+                    "example": "string"
+                },
+                "hec_cycle": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "rot": {
+                    "type": "integer",
+                    "example": 0
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECLoad": {
+            "type": "object",
+            "properties": {
+                "load_category": {
+                    "description": "Weight band for the HEC load, e.g. \"bis 199 kg\", \"200-600 kg\", \"600-800 kg\", \"800-1000 kg\".",
+                    "type": "string",
+                    "example": "200-600 kg"
+                },
+                "quantity": {
+                    "type": "integer",
+                    "example": 3
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECSling": {
+            "type": "object",
+            "properties": {
+                "sling_id": {
+                    "description": "Facility category: hec-rope-length.",
+                    "type": "string",
+                    "example": "string"
+                },
+                "sling_name": {
+                    "type": "string",
+                    "example": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOAttributes": {
+            "type": "object",
+            "properties": {
+                "flights": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOFlight"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOFlight": {
+            "type": "object",
+            "properties": {
+                "heslo_rope_label_id": {
+                    "description": "Facility category: heslo-rope-label.",
+                    "type": "string",
+                    "example": "string"
+                },
+                "heslo_rope_label_name": {
+                    "type": "string",
+                    "example": "string"
+                },
+                "rot": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "slings": {
+                    "description": "Facility category: heslo-rope-length.",
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOSling"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOSling": {
+            "type": "object",
+            "properties": {
+                "sling_id": {
+                    "description": "Facility category: heslo-rope-length.",
+                    "type": "string",
+                    "example": "string"
+                },
+                "sling_name": {
+                    "type": "string",
+                    "example": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOLoggingAttributes": {
+            "type": "object",
+            "properties": {
+                "slings": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOLoggingSling"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataCreateSPOLoggingSling": {
+            "type": "object",
+            "properties": {
+                "sling_id": {
+                    "description": "Facility category: heslo-hook.",
+                    "type": "string",
+                    "example": "string"
+                },
+                "sling_name": {
+                    "type": "string",
+                    "example": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "flight_data_update"
+                    ],
+                    "example": "flight_data_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.FlightDataUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.FlightDataUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterCreateAttributes": {
+            "type": "object",
+            "required": [
+                "designation",
+                "identifier",
+                "type"
+            ],
+            "properties": {
+                "aog": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "aog_reason": {
+                    "type": "string",
+                    "example": "Main rotor gearbox fault"
+                },
+                "consumption_lt_min": {
+                    "type": "number",
+                    "example": 4.1
+                },
+                "designation": {
+                    "type": "string",
+                    "example": "OE-XHZ"
+                },
+                "dry": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "engine_1": {
+                    "type": "string",
+                    "example": "TM"
+                },
+                "engine_2": {
+                    "type": "string",
+                    "example": "TM"
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "ABC"
+                },
+                "igb": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "lh": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "mgb": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Primary HEMS helicopter"
+                },
+                "nr1": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "nr2": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "rh": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 10
+                },
+                "tgb": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "type": {
+                    "type": "string",
+                    "example": "EC-135"
+                },
+                "utc_offset": {
+                    "type": "integer",
+                    "example": -1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_create",
+                        "helicopter"
+                    ],
+                    "example": "helicopter_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadAttributes": {
+            "type": "object",
+            "required": [
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "019d6d0d-2de2-7db1-80a2-2862d43af620"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_file_cancel_upload"
+                    ],
+                    "example": "helicopter_file_cancel_upload"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileCreateAttributes": {
+            "type": "object",
+            "required": [
+                "file_name",
+                "section",
+                "upload_intent_uuid"
+            ],
+            "properties": {
+                "file_name": {
+                    "type": "string",
+                    "example": "Before Flight Checklist.pdf"
+                },
+                "folder_uuid": {
+                    "type": "string",
+                    "example": "019d6d0d-8c24-72e3-9f58-c9ea0fbf0bb1"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "is_mandatory": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "section": {
+                    "type": "string",
+                    "enum": [
+                        "bfi",
+                        "fpwb",
+                        "afi"
+                    ],
+                    "example": "bfi"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "019d6d0d-2de2-7db1-80a2-2862d43af620"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileCreateBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCreateData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_file_create",
+                        "helicopter_file"
+                    ],
+                    "example": "helicopter_file_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileDeleteData": {
+            "type": "object",
+            "required": [
+                "id",
+                "type"
+            ],
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_file_delete",
+                        "helicopter_file"
+                    ],
+                    "example": "helicopter_file_delete"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileDeleteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileDeleteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "file_name": {
+                    "type": "string",
+                    "example": "Before Flight Checklist v2.pdf"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "is_mandatory": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "section": {
+                    "type": "string",
+                    "enum": [
+                        "bfi",
+                        "fpwb",
+                        "afi"
+                    ],
+                    "example": "fpwb"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileUpdateBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUpdateData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "id",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_file_update",
+                        "helicopter_file"
+                    ],
+                    "example": "helicopter_file_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileUploadAttributes": {
+            "type": "object",
+            "required": [
+                "content_type",
+                "name",
+                "size_bytes"
+            ],
+            "properties": {
+                "content_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Before Flight Checklist.pdf"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "example": 1024
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileUploadBulkRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUploadData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterFileUploadData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUploadAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_file_upload"
+                    ],
+                    "example": "helicopter_file_upload"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "aog": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "aog_reason": {
+                    "type": "string",
+                    "example": "Main rotor gearbox fault"
+                },
+                "consumption_lt_min": {
+                    "type": "number",
+                    "example": 4.1
+                },
+                "designation": {
+                    "type": "string",
+                    "example": "OE-XHZ"
+                },
+                "dry": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "engine_1": {
+                    "type": "string",
+                    "example": "TM"
+                },
+                "engine_2": {
+                    "type": "string",
+                    "example": "TM"
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "ABC"
+                },
+                "igb": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "lh": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "mgb": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Primary HEMS helicopter"
+                },
+                "nr1": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "nr2": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "rh": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 10
+                },
+                "tgb": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "type": {
+                    "type": "string",
+                    "example": "EC-135"
+                },
+                "utc_offset": {
+                    "type": "integer",
+                    "example": -1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "helicopter_update",
+                        "helicopter"
+                    ],
+                    "example": "helicopter_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.HelicopterUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.HelicopterUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionUpsertAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "last_flights_inspection_create",
+                        "last_flights_inspection"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteAttributes": {
+            "type": "object",
+            "required": [
+                "flight_inspection_id"
+            ],
+            "properties": {
+                "flight_inspection_id": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "last_flights_inspection_delete",
+                        "last_flights_inspection"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionUpsertAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "last_flights_inspection_update",
+                        "last_flights_inspection"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.LastFlightsInspectionUpsertAttributes": {
+            "type": "object",
+            "required": [
+                "flight_inspection_id"
+            ],
+            "properties": {
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem"
+                    }
+                },
+                "flight_inspection_id": {
+                    "type": "string"
+                },
+                "hydraulic_lh_checked": {
+                    "type": "string"
+                },
+                "hydraulic_rh_checked": {
+                    "type": "string"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "oil_engine_nr1_checked": {
+                    "type": "string"
+                },
+                "oil_engine_nr2_checked": {
+                    "type": "string"
+                },
+                "oil_transmission_igb_checked": {
+                    "type": "string"
+                },
+                "oil_transmission_mgb_checked": {
+                    "type": "string"
+                },
+                "oil_transmission_tgb_checked": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MCFCompleteAttributes": {
+            "type": "object",
+            "properties": {
+                "af_hours": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-06-17"
+                },
+                "landing_count": {
+                    "type": "integer",
+                    "example": 3
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Vibration within limits after check flight"
+                },
+                "result": {
+                    "type": "string",
+                    "enum": [
+                        "passed",
+                        "failed"
+                    ],
+                    "example": "passed"
+                },
+                "sign": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "utc_time": {
+                    "type": "string",
+                    "example": "2026-06-17T08:30:00Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MCFCompleteData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MCFCompleteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "mcf_complete",
+                        "mcf_sign",
+                        "mcf"
+                    ],
+                    "example": "mcf_sign"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MCFCompleteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MCFCompleteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MCFSetAttributes": {
+            "type": "object",
+            "properties": {
+                "active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "af_hours": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-06-17"
+                },
+                "flight_id": {
+                    "description": "FlightID — OPTIONAL flight this check flight is performed on (on activate).",
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "landing_count": {
+                    "type": "integer",
+                    "example": 3
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "MCF required after engine mount work"
+                },
+                "result": {
+                    "type": "string",
+                    "enum": [
+                        "passed",
+                        "failed"
+                    ],
+                    "example": "passed"
+                },
+                "utc_time": {
+                    "type": "string",
+                    "example": "2026-06-17T08:30:00Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MCFSetData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MCFSetAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "mcf_set",
+                        "mcf"
+                    ],
+                    "example": "mcf_set"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MCFSetRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MCFSetData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsCreateAttributes": {
+            "type": "object",
+            "required": [
+                "company_name"
+            ],
+            "properties": {
+                "company_name": {
+                    "type": "string",
+                    "example": "Wucher"
+                },
+                "cover_file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "logo_file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "subtitle": {
+                    "type": "string",
+                    "example": "Flight operations platform"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Welcome to Wucher"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "master_settings_create",
+                        "master_settings"
+                    ],
+                    "example": "master_settings_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertAttributes": {
+            "type": "object",
+            "required": [
+                "MS_ENTRA_AUTHORITY",
+                "MS_ENTRA_CLIENT_ID",
+                "MS_ENTRA_REDIRECT_URL",
+                "MS_ENTRA_SCOPES",
+                "MS_ENTRA_TENANT_ID"
+            ],
+            "properties": {
+                "MS_ENTRA_AUTHORITY": {
+                    "type": "string",
+                    "example": "https://login.microsoftonline.com/"
+                },
+                "MS_ENTRA_CLIENT_ID": {
+                    "type": "string",
+                    "example": "your-client-id"
+                },
+                "MS_ENTRA_CLIENT_SECRET": {
+                    "type": "string",
+                    "example": "********"
+                },
+                "MS_ENTRA_REDIRECT_URL": {
+                    "type": "string",
+                    "example": "https://example.com/api/v1/auth/microsoft/callback"
+                },
+                "MS_ENTRA_SCOPES": {
+                    "type": "string",
+                    "example": "openid,profile,email"
+                },
+                "MS_ENTRA_TENANT_ID": {
+                    "type": "string",
+                    "example": "your-tenant-id"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "master_settings_microsoft_entra_upsert",
+                        "master_settings"
+                    ],
+                    "example": "master_settings_microsoft_entra_upsert"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "company_name": {
+                    "type": "string",
+                    "example": "Wucher"
+                },
+                "cover_file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "logo_file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "subtitle": {
+                    "type": "string",
+                    "example": "Flight operations platform"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Welcome to Wucher"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "master_settings_update",
+                        "master_settings"
+                    ],
+                    "example": "master_settings_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MasterSettingsUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionCreateAttributes": {
+            "type": "object",
+            "required": [
+                "flight_id",
+                "type"
+            ],
+            "properties": {
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionFileInput"
+                    }
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Mission note"
+                },
+                "subtype_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a99"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "mission_create",
+                        "mission"
+                    ],
+                    "example": "mission_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionFileInput": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "mission-brief.pdf"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionTypeCreateAttributes": {
+            "type": "object",
+            "required": [
+                "code_type",
+                "name"
+            ],
+            "properties": {
+                "code_type": {
+                    "type": "string",
+                    "example": "HEMS"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionTypeCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionTypeCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "mission_type_create",
+                        "mission_type"
+                    ],
+                    "example": "mission_type_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionTypeCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionTypeCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionUpdateAttributes": {
+            "type": "object",
+            "required": [
+                "type"
+            ],
+            "properties": {
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionFileInput"
+                    }
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Mission note"
+                },
+                "subtype_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a99"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "SPO"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionUpdateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "mission_update",
+                        "mission"
+                    ],
+                    "example": "mission_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.MissionUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.MissionUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.OtherPersonAttributesInput": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "guest@example.com"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Guest Person"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.OtherPersonRequest": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.OtherPersonRequestData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.OtherPersonRequestData": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.OtherPersonAttributesInput"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "other_person"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcBeforeInspectionAttributes": {
+            "type": "object",
+            "properties": {
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem"
+                    }
+                },
+                "fuel_added_amount": {
+                    "type": "number"
+                },
+                "fuel_amount": {
+                    "type": "number"
+                },
+                "fuel_unit": {
+                    "type": "string"
+                },
+                "hydraulic_lh_checked": {
+                    "type": "boolean"
+                },
+                "hydraulic_rh_checked": {
+                    "type": "boolean"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "oil_engine_nr1_checked": {
+                    "type": "boolean"
+                },
+                "oil_engine_nr2_checked": {
+                    "type": "boolean"
+                },
+                "oil_transmission_igb_checked": {
+                    "type": "boolean"
+                },
+                "oil_transmission_mgb_checked": {
+                    "type": "boolean"
+                },
+                "oil_transmission_tgb_checked": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcCreateAttributes": {
+            "type": "object",
+            "required": [
+                "flight_id",
+                "helicopter_id",
+                "inspection"
+            ],
+            "properties": {
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcInspectionCreateAttributes"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "reserve_ac_create",
+                        "reserve_ac"
+                    ],
+                    "example": "reserve_ac_create"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcDeleteData": {
+            "type": "object",
+            "required": [
+                "id"
+            ],
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcDeleteRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcDeleteData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem": {
+            "type": "object",
+            "required": [
+                "helicopter_file_id"
+            ],
+            "properties": {
+                "helicopter_file_id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-111111111111"
+                },
+                "is_done": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcFleetStatusFileAttributes": {
+            "type": "object",
+            "properties": {
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcInspectionCreateAttributes": {
+            "type": "object",
+            "required": [
+                "before",
+                "inspection_date",
+                "prepare"
+            ],
+            "properties": {
+                "before": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcBeforeInspectionAttributes"
+                },
+                "fleet_status_file": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFleetStatusFileAttributes"
+                },
+                "inspection_date": {
+                    "type": "string",
+                    "example": "2026-04-15"
+                },
+                "prepare": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcPrepareInspectionAttributes"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcInspectionUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "before": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcBeforeInspectionAttributes"
+                },
+                "inspection_date": {
+                    "type": "string",
+                    "example": "2026-04-15"
+                },
+                "prepare": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcPrepareInspectionAttributes"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcPrepareInspectionAttributes": {
+            "type": "object",
+            "properties": {
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem"
+                    }
+                },
+                "notam_briefing": {
+                    "type": "boolean"
+                },
+                "operational_flight_plan": {
+                    "type": "boolean"
+                },
+                "weather_briefing": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcInspectionUpdateAttributes"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcUpdateAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "reserve_ac_update",
+                        "reserve_ac"
+                    ],
+                    "example": "reserve_ac_update"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.ReserveAcUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverBaseRef": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverCreateAttributes": {
+            "type": "object",
+            "required": [
+                "duty_date"
+            ],
+            "properties": {
+                "base_id": {
+                    "type": "string"
+                },
+                "duty_date": {
+                    "type": "string"
+                },
+                "edited_template_file_ids": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateFileInput"
+                    }
+                },
+                "helicopter_id": {
+                    "type": "string"
+                },
+                "inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcInspectionCreateAttributes"
+                },
+                "notes": {
+                    "type": "string"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterDetailsInput"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverCreateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "takeover_create",
+                        "takeover"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverCreateFileInput": {
+            "type": "object",
+            "properties": {
+                "file_id": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "takeover-report.pdf"
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverCreateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverRosterCrewInput": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverRosterDetailsInput": {
+            "type": "object",
+            "properties": {
+                "doctor": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterCrewInput"
+                    }
+                },
+                "helper": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterCrewInput"
+                    }
+                },
+                "other_person": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterOtherPersonInput"
+                    }
+                },
+                "pilot": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterPilotInput"
+                    }
+                },
+                "rescuer": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterCrewInput"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverRosterOtherPersonInput": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "guest@example.com"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Guest Person"
+                },
+                "other_person_id": {
+                    "description": "OtherPersonID — OPTIONAL master person id to reuse (from GET /contact/other).",
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverRosterPilotInput": {
+            "type": "object",
+            "properties": {
+                "co_pilot": {
+                    "type": "boolean"
+                },
+                "crew_type": {
+                    "type": "string",
+                    "enum": [
+                        "main",
+                        "additional"
+                    ],
+                    "example": "main"
+                },
+                "examiner": {
+                    "type": "boolean"
+                },
+                "flight_instructor": {
+                    "type": "boolean"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "line_checker": {
+                    "type": "boolean"
+                },
+                "supervisor": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverUpdateAttributes": {
+            "type": "object",
+            "properties": {
+                "base_id": {
+                    "type": "string"
+                },
+                "bases": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverBaseRef"
+                },
+                "duty_date": {
+                    "type": "string"
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateFileInput"
+                    }
+                },
+                "files_add": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateFileInput"
+                    }
+                },
+                "files_remove": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "files_replace": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateFileInput"
+                    }
+                },
+                "helicopter_id": {
+                    "type": "string"
+                },
+                "inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.ReserveAcInspectionCreateAttributes"
+                },
+                "notes": {
+                    "type": "string"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterDetailsInput"
+                },
+                "roster_details": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterDetailsInput"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverUpdateData": {
+            "type": "object",
+            "required": [
+                "attributes",
+                "type"
+            ],
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverUpdateAttributes"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "takeover_update",
+                        "takeover"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_request.TakeoverUpdateRequest": {
+            "type": "object",
+            "required": [
+                "data"
+            ],
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_request.TakeoverUpdateData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ActionSignoffAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "signed": {
+                    "description": "Signed — true once checked; gates the maintenance release form.",
+                    "type": "boolean",
+                    "example": false
+                },
+                "signed_at": {
+                    "description": "SignedAt / SignedBy — when/who signed; empty until signed.",
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "signed_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "signed_by_name": {
+                    "description": "SignedByName / SignedByShort — resolved display name + 3-letter short of the signer.",
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "signed_by_short": {
+                    "type": "string",
+                    "example": "JDO"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ActionSignoffResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ActionSignoffAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "action_signoff"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ActionSignoffResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ActionSignoffResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistAttributes": {
+            "type": "object",
+            "properties": {
+                "bases": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistBaseInfo"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResource"
+                    }
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "scope_code": {
+                    "type": "string",
+                    "example": "TU"
+                },
+                "scope_code_de": {
+                    "type": "string",
+                    "example": "DI"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Monday Checklist"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupAttributes": {
+            "type": "object",
+            "properties": {
+                "bases": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistBaseInfo"
+                },
+                "tabs": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistTabResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "base-018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "air_rescuer_checklist_group"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistCATChecklistSummary": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Cockpit Flugretter"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistCATGroup": {
+            "type": "object",
+            "properties": {
+                "checklists": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistCATChecklistSummary"
+                    }
+                },
+                "scope_code": {
+                    "type": "string",
+                    "example": "DA"
+                },
+                "scope_code_de": {
+                    "type": "string",
+                    "example": "TA"
+                },
+                "scope_code_name": {
+                    "type": "string",
+                    "example": "Daily"
+                },
+                "scope_code_name_de": {
+                    "type": "string",
+                    "example": "Taeglich"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 8
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 8
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "total_bases": {
+                            "type": "integer",
+                            "example": 8
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistItemAttributes": {
+            "type": "object",
+            "properties": {
+                "checklist_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Check radio"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistItemBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemData"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistItemData": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "air_rescuer_checklist_item"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResource": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Oxygen supply check"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "air_rescuer_checklist"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistTabChecklistDetail": {
+            "type": "object",
+            "properties": {
+                "checklist_items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResource"
+                    }
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Monday Checklist"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.AirRescuerChecklistTabResource": {
+            "type": "object",
+            "properties": {
+                "checklists": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistTabChecklistDetail"
+                    }
+                },
+                "groups": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistCATGroup"
+                    }
+                },
+                "scope_code": {
+                    "type": "string",
+                    "example": "DA"
+                },
+                "scope_code_de": {
+                    "type": "string",
+                    "example": "TA"
+                },
+                "scope_code_name": {
+                    "type": "string",
+                    "example": "Daily"
+                },
+                "scope_code_name_de": {
+                    "type": "string",
+                    "example": "Taeglich"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintAttributes": {
+            "type": "object",
+            "properties": {
+                "action_signed": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "action_signed_at": {
+                    "type": "string",
+                    "example": "2026-06-15T03:04:05Z"
+                },
+                "action_signed_by_name": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "action_signed_by_short": {
+                    "type": "string",
+                    "example": "JDO"
+                },
+                "action_taken": {
+                    "type": "string",
+                    "example": "tightened mount"
+                },
+                "aircraft_hours_at_fix": {
+                    "type": "string",
+                    "example": "1250.1"
+                },
+                "aircraft_hours_at_report": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-06-15T03:04:05Z"
+                },
+                "description": {
+                    "type": "string",
+                    "example": "Engine 2 N2 vibration intermittent during cruise above 110 KIAS"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusHelicopter"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "mel": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintMEL"
+                },
+                "nsr": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintNSR"
+                },
+                "reported_at": {
+                    "type": "string",
+                    "example": "2026-06-15T03:04:05Z"
+                },
+                "reported_by": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "reported_by_short": {
+                    "type": "string",
+                    "example": "JDO"
+                },
+                "status": {
+                    "type": "string",
+                    "enum": [
+                        "active_non_mel",
+                        "active_mel",
+                        "serviced"
+                    ],
+                    "example": "active_mel"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-06-15T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintGroupedDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupAttributes": {
+            "type": "object",
+            "properties": {
+                "complaints": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResource"
+                    }
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusHelicopter"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "complaint_helicopter_group"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintMEL": {
+            "type": "object",
+            "properties": {
+                "classified_at": {
+                    "description": "ClassifiedAt / ClassifiedByName / ClassifiedByShort — when/who classified the MEL.",
+                    "type": "string",
+                    "example": "2026-06-15T03:04:05Z"
+                },
+                "classified_by_name": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "classified_by_short": {
+                    "type": "string",
+                    "example": "JDO"
+                },
+                "deadline": {
+                    "description": "Deadline — grace deadline; after this the aircraft is AOG. null for NON-MEL.",
+                    "type": "string",
+                    "example": "2026-06-18T03:04:05Z"
+                },
+                "severity": {
+                    "description": "Severity — MEL class: 0=NON-MEL, 1=A, 2=B, 3=C, 4=D. Always set (classification is required at creation).",
+                    "type": "integer",
+                    "enum": [
+                        0,
+                        1,
+                        2,
+                        3,
+                        4
+                    ],
+                    "example": 2
+                },
+                "severity_label": {
+                    "description": "SeverityLabel — human label of the severity (NON-MEL/A/B/C/D).",
+                    "type": "string",
+                    "example": "B"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintNSR": {
+            "type": "object",
+            "properties": {
+                "decided_at": {
+                    "description": "DecidedAt / DecidedByName / DecidedByShort — when/who decided NSR (may differ from the reporter).",
+                    "type": "string",
+                    "example": "2026-06-15T03:04:05Z"
+                },
+                "decided_by_name": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "decided_by_short": {
+                    "type": "string",
+                    "example": "JDO"
+                },
+                "is_nsr": {
+                    "description": "IsNSR — Non-Safety Release: true = aircraft released to fly despite the open defect.",
+                    "type": "boolean",
+                    "example": false
+                },
+                "reason": {
+                    "description": "Reason — optional justification for the NSR decision.",
+                    "type": "string",
+                    "example": "not required"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "complaint"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ComplaintResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ComplaintResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterAttributes": {
+            "type": "object",
+            "properties": {
+                "bases": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseInfo"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "duty_date": {
+                    "type": "string",
+                    "example": "2026-03-16"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterHelicopterSummary"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterDetailsResponse"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftTime"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterBaseGroupAttributes": {
+            "type": "object",
+            "properties": {
+                "bases": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseInfo"
+                },
+                "rosters": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterGroupRoster"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterBaseGroupResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseGroupAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hems_base_roster_group"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterBaseInfo": {
+            "type": "object",
+            "properties": {
+                "base_abbreviation": {
+                    "type": "string",
+                    "example": "G1"
+                },
+                "base_name": {
+                    "type": "string",
+                    "example": "Gallus 1 - Zurs Lech"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftTime"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hems"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterCrew": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "doctor@example.com"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Hunter Wolfgang"
+                },
+                "role": {
+                    "type": "string",
+                    "example": "doctor"
+                },
+                "shift_date": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftDate"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftTime"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteAttributes": {
+            "type": "object",
+            "properties": {
+                "deleted": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "deleted_count": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "deleted_items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterDeletedCrewItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "duty_roster_crew_delete"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterDeletedCrewItem": {
+            "type": "object",
+            "properties": {
+                "crew_type": {
+                    "type": "string",
+                    "example": "main"
+                },
+                "date_end": {
+                    "type": "string",
+                    "example": "2026-03-22"
+                },
+                "date_start": {
+                    "type": "string",
+                    "example": "2026-03-20"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Pilot One"
+                },
+                "role_code": {
+                    "type": "string",
+                    "example": "pilot"
+                },
+                "roster_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "user_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterDetailsResponse": {
+            "type": "object",
+            "properties": {
+                "doctor": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrew"
+                    }
+                },
+                "helper": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrew"
+                    }
+                },
+                "other_person": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrew"
+                    }
+                },
+                "pilot": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterPilotCrew"
+                    }
+                },
+                "rescuer": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrew"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterGroupRoster": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "duty_date": {
+                    "type": "string",
+                    "example": "2026-03-16"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterHelicopterSummary"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterDetailsResponse"
+                },
+                "shift_time": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftTime"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterGroupedDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 8
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 8
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterGroupedListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseGroupResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "from": {
+                            "type": "string",
+                            "example": "2026-03-16"
+                        },
+                        "to": {
+                            "type": "string",
+                            "example": "2026-04-15"
+                        },
+                        "total_bases": {
+                            "type": "integer",
+                            "example": 8
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterHelicopterSummary": {
+            "type": "object",
+            "properties": {
+                "designation": {
+                    "type": "string",
+                    "example": "OE-XHZ"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "1234"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "EC-135"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterPilotCrew": {
+            "type": "object",
+            "properties": {
+                "co_pilot": {
+                    "type": "boolean"
+                },
+                "crew_type": {
+                    "type": "string",
+                    "example": "main"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "pilot@example.com"
+                },
+                "examiner": {
+                    "type": "boolean"
+                },
+                "flight_instructor": {
+                    "type": "boolean"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "line_checker": {
+                    "type": "boolean"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Hunter Wolfgang"
+                },
+                "role": {
+                    "type": "string",
+                    "example": "pilot"
+                },
+                "shift_date": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftDate"
+                },
+                "supervisor": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "duty_roster"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterShiftDate": {
+            "type": "object",
+            "properties": {
+                "date_end": {
+                    "type": "string",
+                    "example": "2026-03-16"
+                },
+                "date_start": {
+                    "type": "string",
+                    "example": "2026-03-16"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.DutyRosterShiftTime": {
+            "type": "object",
+            "properties": {
+                "shift_end": {
+                    "type": "string",
+                    "example": "21:00"
+                },
+                "shift_start": {
+                    "type": "string",
+                    "example": "06:00"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.EASAReleaseAttributes": {
+            "type": "object",
+            "properties": {
+                "complaint_id": {
+                    "type": "string",
+                    "example": "019d6774-1111-7fba-9ef4-3795c0da8a13"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "easa_ac_hours": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "easa_date": {
+                    "type": "string",
+                    "example": "2026-06-16"
+                },
+                "easa_location": {
+                    "type": "string",
+                    "example": "LOWI"
+                },
+                "easa_maint_manual_rev_airframe": {
+                    "type": "string",
+                    "example": "Rev 12"
+                },
+                "easa_maint_manual_rev_engine": {
+                    "type": "string",
+                    "example": "Rev 8"
+                },
+                "easa_permit_no": {
+                    "type": "string",
+                    "example": "145.A.50"
+                },
+                "easa_signer_id": {
+                    "description": "EASASignerID — contact id (UUIDv7) of the signer/technician.",
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "easa_signer_name": {
+                    "description": "EASASignerName / EASASignerShort — resolved display name + 3-letter short of the signer contact.",
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "easa_signer_short": {
+                    "type": "string",
+                    "example": "JDO"
+                },
+                "easa_wo_no": {
+                    "type": "string",
+                    "example": "WO-2026-001"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "is_signed": {
+                    "description": "IsSigned — true once the release is signed (Release to Service); then the complaint becomes fixed.",
+                    "type": "boolean",
+                    "example": false
+                },
+                "missing_sign_fields": {
+                    "description": "MissingSignFields — required fields still empty; must all be filled before it can be signed.",
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "signed_at": {
+                    "description": "SignedAt / SignedBy — when/who signed; empty until signed.",
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "signed_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.EASAReleaseDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "deleted": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "easa_release_delete"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.EASAReleaseListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.EASAReleaseResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "easa_release"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.EASAReleaseResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerActionBulkError": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "FILE_MANAGER_VALIDATION_FAILED"
+                },
+                "detail": {
+                    "type": "string",
+                    "example": "duplicate name in target folder"
+                },
+                "error_code": {
+                    "type": "string",
+                    "example": "4222111"
+                },
+                "status": {
+                    "type": "integer",
+                    "example": 422
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Validation error"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerActionLocation": {
+            "type": "object",
+            "properties": {
+                "folder_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerAttachmentListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerAttachmentResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerAttachmentAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_attachment"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerAttachmentResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerBreadcrumbItem": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "operations"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileBulkError": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "FILE_MANAGER_VALIDATION_FAILED"
+                },
+                "detail": {
+                    "type": "string",
+                    "example": "duplicate name in target folder"
+                },
+                "error_code": {
+                    "type": "string",
+                    "example": "4222111"
+                },
+                "status": {
+                    "type": "integer",
+                    "example": 422
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Validation error"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "message": {
+                    "type": "string",
+                    "example": "created"
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileResource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadResource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "properties": {
+                        "status": {
+                            "type": "string",
+                            "example": "canceled"
+                        }
+                    }
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_file_cancel_upload_result"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileDetailResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileDetailAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_file"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileDetailResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileDetailResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_file"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileAttributes"
+                        },
+                        "id": {
+                            "type": "string",
+                            "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "file_manager_file"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentResource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileUploadIntentAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_file_upload_intent"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionData": {
+            "type": "object",
+            "properties": {
+                "access_token": {
+                    "type": "string",
+                    "example": "eyJhbGciOiJIUzI1NiIs..."
+                },
+                "access_token_ttl": {
+                    "description": "AccessTokenTTL is the access token's absolute expiry time, in epoch\nmilliseconds (equal to the JWT exp claim), as required by WOPI/Collabora.",
+                    "type": "integer",
+                    "example": 1782971996000
+                },
+                "collabora_action": {
+                    "type": "string",
+                    "example": "https://collabora.example.com/browser/123?WOPISrc=..."
+                },
+                "file_id": {
+                    "type": "string",
+                    "example": "019f0386-0a00-7a4a-a2d8-30afc0e0c3ad"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionData"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFolderDetailResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFolderDetailAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_folder"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFolderDetailResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderDetailResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFolderResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFolderAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_folder"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerFolderResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerActionBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeResultResource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerMoveNodeResultAttributes": {
+            "type": "object",
+            "properties": {
+                "location": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerActionLocation"
+                },
+                "node_type": {
+                    "type": "string",
+                    "example": "folder"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "moved"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerMoveNodeResultResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeResultAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_move_result"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerNodeAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "extension": {
+                    "type": "string",
+                    "example": "pdf"
+                },
+                "mime_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "operations"
+                },
+                "node_type": {
+                    "type": "string",
+                    "example": "folder"
+                },
+                "parent_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "path_cache": {
+                    "type": "string",
+                    "example": "/root/operations"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "example": 1024
+                },
+                "status": {
+                    "type": "string",
+                    "example": "ready"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerNodeListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerNodeResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "breadcrumb": {
+                            "type": "array",
+                            "items": {
+                                "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerBreadcrumbItem"
+                            }
+                        },
+                        "files": {
+                            "type": "integer",
+                            "example": 8
+                        },
+                        "folders": {
+                            "type": "integer",
+                            "example": 4
+                        },
+                        "is_root": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "parent_uuid": {
+                            "type": "string",
+                            "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 12
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerNodeResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerNodeAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_node"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerPurgeNodeBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerActionBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerPurgeNodeResultResource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerPurgeNodeBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerPurgeNodeBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerPurgeNodeResultAttributes": {
+            "type": "object",
+            "properties": {
+                "node_type": {
+                    "type": "string",
+                    "example": "folder"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "purged"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerPurgeNodeResultResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerPurgeNodeResultAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_purge_result"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerTrashListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerTrashNodeResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "files": {
+                            "type": "integer",
+                            "example": 70
+                        },
+                        "folders": {
+                            "type": "integer",
+                            "example": 50
+                        },
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerTrashNodeAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-31T08:52:03Z"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "extension": {
+                    "type": "string",
+                    "example": "pdf"
+                },
+                "mime_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Documents"
+                },
+                "node_type": {
+                    "type": "string",
+                    "example": "folder"
+                },
+                "path_cache": {
+                    "type": "string",
+                    "example": "/Documents"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "example": 123456
+                },
+                "trashed_at": {
+                    "type": "string",
+                    "example": "2026-04-01T10:00:00Z"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-31T08:52:03Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FileManagerTrashNodeResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FileManagerTrashNodeAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "file_manager_trash_node"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetHistoryEntry": {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "example": "easa_signed"
+                },
+                "actor": {
+                    "type": "string",
+                    "example": "019e91e6-2908-7f37-93e6-015ed1b7587d"
+                },
+                "actor_name": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "at": {
+                    "type": "string",
+                    "example": "2026-06-17T10:15:00Z"
+                },
+                "entity_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "entity_type": {
+                    "type": "string",
+                    "example": "easa_release"
+                },
+                "message": {
+                    "type": "string",
+                    "example": "Release to Service (EASA signed)"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetHistoryListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetHistoryEntry"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusAttributes": {
+            "type": "object",
+            "properties": {
+                "complaints": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusComplaint"
+                    }
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-05-29T07:43:06Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "John Doe"
+                },
+                "easa_release": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusEASARelease"
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusFile"
+                    }
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusHelicopter"
+                },
+                "maintenance_schedules": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes"
+                    }
+                },
+                "mcf": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusMCF"
+                },
+                "serviced_at": {
+                    "type": "string",
+                    "example": "2026-05-29T07:43:06Z"
+                },
+                "status": {
+                    "type": "string",
+                    "enum": [
+                        "active",
+                        "serviced"
+                    ],
+                    "example": "active"
+                },
+                "summary": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusSummary"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-05-29T07:43:06Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "John Doe"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 100
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "deleted": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "fleet_status_delete"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusFile": {
+            "type": "object",
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "example": "wb"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/fleet/wb.pdf?X-Amz-Signature=abc123"
+                },
+                "file_attachment_id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-111111111111"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "is_mandatory": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "name": {
+                    "type": "string",
+                    "example": "weight_balance.pdf"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "example": 1024000
+                },
+                "thumbnail_download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/fleet/wb.thumb.jpg?X-Amz-Signature=abc123"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 100
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusMarkServicedResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "attributes": {
+                            "type": "object",
+                            "properties": {
+                                "serviced": {
+                                    "type": "boolean",
+                                    "example": true
+                                }
+                            }
+                        },
+                        "type": {
+                            "type": "string",
+                            "example": "fleet_status_mark_serviced"
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "fleet_status"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FleetStatusResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightAttributes": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "M-062226-001"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "created_by": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.UserRef"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-04-14"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "deleted_by": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.UserRef"
+                },
+                "draft": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDraftGroup"
+                    }
+                },
+                "mission_id": {
+                    "type": "string",
+                    "example": "019e9640-f7af-7940-80e8-1e9a83013afb"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "draft"
+                },
+                "steps": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightStepItem"
+                    }
+                },
+                "takeover": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightTakeoverSummary"
+                },
+                "total_draft": {
+                    "type": "integer",
+                    "example": 6
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "updated_by": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.UserRef"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDailyInspectionSummary": {
+            "type": "object",
+            "properties": {
+                "date": {
+                    "type": "string",
+                    "example": "17.04.2026"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Ganahl Stefan"
+                },
+                "short_name": {
+                    "type": "string",
+                    "example": "GAN"
+                },
+                "utc_time": {
+                    "type": "string",
+                    "example": "10:57"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataAttributes": {
+            "type": "object",
+            "properties": {
+                "co_pilot": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataCoPilotRef"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "customer_name": {
+                    "type": "string",
+                    "example": "Air Service"
+                },
+                "delivery_note_number": {
+                    "type": "string",
+                    "example": "DN-1001"
+                },
+                "engine": {
+                    "type": "string",
+                    "example": "PW207D1"
+                },
+                "flight_duration_seconds": {
+                    "type": "integer",
+                    "example": 4500
+                },
+                "flight_landing": {
+                    "type": "string",
+                    "example": "2026-04-20T09:15:00Z"
+                },
+                "flight_plan_distance": {
+                    "type": "number",
+                    "example": 120.5
+                },
+                "flight_plan_time_seconds": {
+                    "type": "integer",
+                    "example": 4200
+                },
+                "flight_plan_true_course": {
+                    "type": "number",
+                    "example": 182.3
+                },
+                "flight_positioning": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "flight_red_seconds": {
+                    "type": "integer",
+                    "example": 300
+                },
+                "flight_take_off": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "from": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataLocationRef"
+                },
+                "fuel_after_flight": {
+                    "type": "number",
+                    "example": 280
+                },
+                "fuel_before_flight": {
+                    "type": "number",
+                    "example": 420
+                },
+                "fuel_planning": {
+                    "type": "number",
+                    "example": 390
+                },
+                "fuel_upload": {
+                    "type": "number",
+                    "example": 100
+                },
+                "hec": {
+                    "allOf": [
+                        {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHECDetails"
+                        }
+                    ],
+                    "x-note": "Only returned for SPO missions"
+                },
+                "heslo": {
+                    "allOf": [
+                        {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHESLODetails"
+                        }
+                    ],
+                    "x-note": "Only returned for SPO missions"
+                },
+                "hook_releases": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "landing_count": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "logging": {
+                    "allOf": [
+                        {
+                            "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOLoggingDetails"
+                        }
+                    ],
+                    "x-note": "Only returned for SPO missions"
+                },
+                "max_n1": {
+                    "type": "number",
+                    "example": 97.5
+                },
+                "max_n2": {
+                    "type": "number",
+                    "example": 98.1
+                },
+                "mission": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataMissionRef"
+                },
+                "other_information": {
+                    "type": "string"
+                },
+                "pax_count": {
+                    "type": "integer",
+                    "example": 4
+                },
+                "roster_details": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterDetailsResponse"
+                },
+                "rotor_brake_cycle": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "status": {
+                    "type": "string",
+                    "example": "in_progress"
+                },
+                "ticket_no": {
+                    "type": "string",
+                    "example": "TKT-001"
+                },
+                "to": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataLocationRef"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataCoPilotRef": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "john.doe@example.com"
+                },
+                "first_name": {
+                    "type": "string",
+                    "example": "John"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "last_name": {
+                    "type": "string",
+                    "example": "Doe"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataLocationRef": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "WIII"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "label": {
+                    "type": "string",
+                    "example": "WIII"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "General Hospital"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "icao"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataMissionRef": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "flight_data"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHECDetails": {
+            "type": "object",
+            "properties": {
+                "flights": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHECFlight"
+                    }
+                },
+                "loads": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHECLoad"
+                    }
+                },
+                "slings": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHECSling"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHECFlight": {
+            "type": "object",
+            "properties": {
+                "equipment_id": {
+                    "description": "Facility category: hec-rope-label.",
+                    "type": "string"
+                },
+                "equipment_name": {
+                    "type": "string"
+                },
+                "hec_cycle": {
+                    "type": "integer"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "rot": {
+                    "type": "integer"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHECLoad": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                },
+                "load_category": {
+                    "description": "Weight band for the HEC load, e.g. \"bis 199 kg\", \"200-600 kg\", \"600-800 kg\", \"800-1000 kg\".",
+                    "type": "string",
+                    "example": "200-600 kg"
+                },
+                "quantity": {
+                    "type": "integer",
+                    "example": 3
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHECSling": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                },
+                "sling_id": {
+                    "description": "Facility category: hec-rope-length.",
+                    "type": "string"
+                },
+                "sling_name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHESLODetails": {
+            "type": "object",
+            "properties": {
+                "flights": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHESLOFlight"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHESLOFlight": {
+            "type": "object",
+            "properties": {
+                "heslo_rope_label_id": {
+                    "description": "Facility category: heslo-rope-label.",
+                    "type": "string"
+                },
+                "heslo_rope_label_name": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "rot": {
+                    "type": "integer"
+                },
+                "slings": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHESLOSling"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOHESLOSling": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                },
+                "sling_id": {
+                    "description": "Facility category: heslo-rope-length.",
+                    "type": "string"
+                },
+                "sling_name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOLoggingDetails": {
+            "type": "object",
+            "properties": {
+                "slings": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOLoggingSling"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDataSPOLoggingSling": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string"
+                },
+                "sling_id": {
+                    "description": "Facility category: heslo-hook.",
+                    "type": "string"
+                },
+                "sling_name": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDraftGroup": {
+            "type": "object",
+            "properties": {
+                "items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDraftItem"
+                    }
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightDraftItem": {
+            "type": "object",
+            "properties": {
+                "flight_data_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a55"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "draft"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightHelicopterSummary": {
+            "type": "object",
+            "properties": {
+                "aog": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "designation": {
+                    "type": "string",
+                    "example": "AIRBUS H145"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "D-HYAR"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "type": {
+                    "type": "string",
+                    "example": "H145"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightMissionTypeSummary": {
+            "type": "object",
+            "properties": {
+                "completed": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "draft": {
+                    "type": "integer",
+                    "example": 5
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "flight"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightStepItem": {
+            "type": "object",
+            "properties": {
+                "complete": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "completed_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "completed_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "mission_type": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightMissionTypeSummary"
+                    }
+                },
+                "phase": {
+                    "type": "string",
+                    "example": "duty_roster"
+                },
+                "position": {
+                    "type": "string",
+                    "example": "takeover"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "completed"
+                },
+                "step": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.FlightTakeoverSummary": {
+            "type": "object",
+            "properties": {
+                "daily_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDailyInspectionSummary"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightHelicopterSummary"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019e8713-aa19-7fb7-a510-a0332dc69697"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterDetailsResponse"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterAttributes": {
+            "type": "object",
+            "properties": {
+                "aog": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "aog_reason": {
+                    "type": "string",
+                    "example": "Main rotor gearbox fault"
+                },
+                "consumption_lt_min": {
+                    "type": "number",
+                    "example": 4.1
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterAuditUser"
+                },
+                "designation": {
+                    "type": "string",
+                    "example": "OE-XHZ"
+                },
+                "dry": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "engine_1": {
+                    "type": "string",
+                    "example": "TM"
+                },
+                "engine_2": {
+                    "type": "string",
+                    "example": "TM"
+                },
+                "foto": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterFoto"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "ABC-0001"
+                },
+                "igb": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "is_in_use": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "last_daily_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspection"
+                },
+                "lh": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "maintenance_schedules": {
+                    "description": "MaintenanceSchedules mirrors the helicopter's latest fleet status. It\nalways lists every inspection type; entries without data are empty.",
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes"
+                    }
+                },
+                "mgb": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Primary HEMS helicopter"
+                },
+                "nr1": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "nr2": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "rh": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "sortkey": {
+                    "type": "integer",
+                    "example": 10
+                },
+                "status": {
+                    "description": "Status is the operational status of the helicopter (read-time derived).\nValues: \"available\", \"booked\", \"aog\", \"mcf\". Precedence: mcf \u003e aog \u003e booked \u003e available.\n\"booked\" = active flight assignment; \"aog\" = air_on_ground flag OR an open complaint\ngrounding it (non-MEL, or MEL past its grace deadline); \"mcf\" = a pending maintenance\ncheck flight (MCF created, not yet passed).",
+                    "type": "string",
+                    "enum": [
+                        "available",
+                        "booked",
+                        "aog",
+                        "mcf"
+                    ],
+                    "example": "available"
+                },
+                "tgb": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "type": {
+                    "type": "string",
+                    "example": "EC-135"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterAuditUser"
+                },
+                "utc_offset": {
+                    "type": "integer",
+                    "example": -1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 12
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileBulkError": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "HELICOPTER_FILE_INVALID_PAYLOAD"
+                },
+                "detail": {
+                    "type": "string",
+                    "example": "helicopter_id is invalid UUID"
+                },
+                "error_code": {
+                    "type": "string",
+                    "example": "4220318"
+                },
+                "status": {
+                    "type": "integer",
+                    "example": 422
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Validation error"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionAttachment": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "file_name": {
+                    "type": "string",
+                    "example": "Before Flight Checklist.pdf"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionAttributes": {
+            "type": "object",
+            "properties": {
+                "files": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionSections"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionHelicopter"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionHelicopter": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "AIRBUS H145"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionItem": {
+            "type": "object",
+            "properties": {
+                "attachment": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionAttachment"
+                },
+                "attachment_pending": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "helicopter_file_id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "is_mandatory": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "is_template": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "section": {
+                    "type": "string",
+                    "example": "bfi"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionResponse"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionResponse": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter_file_collection"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCollectionSections": {
+            "type": "object",
+            "properties": {
+                "after": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionItem"
+                    }
+                },
+                "before": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionItem"
+                    }
+                },
+                "prepare": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Resource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileDeleteAttributes": {
+            "type": "object",
+            "properties": {
+                "deleted": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileDeleteResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileDeleteAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter_file_delete"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileDeleteResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileDeleteResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterFileAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter_file"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileUpdateBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.Resource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileUpdateBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUpdateBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkItem": {
+            "type": "object",
+            "properties": {
+                "error": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileBulkError"
+                },
+                "index": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "resource": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResource"
+                },
+                "success": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkItem"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "failed": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "partial_success": {
+                            "type": "boolean",
+                            "example": true
+                        },
+                        "success": {
+                            "type": "integer",
+                            "example": 2
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 3
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileUploadIntentAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter_file_upload_intent"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterNextReportNumberAttributes": {
+            "type": "object",
+            "properties": {
+                "identifier": {
+                    "type": "string",
+                    "example": "ABC"
+                },
+                "report_number": {
+                    "type": "string",
+                    "example": "ABC-0001"
+                },
+                "sequence": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterNextReportNumberResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterNextReportNumberAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter_report_number"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterNextReportNumberResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterNextReportNumberResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "helicopter"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.HelicopterResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.HelicopterResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MCFAttributes": {
+            "type": "object",
+            "properties": {
+                "af_hours": {
+                    "type": "string",
+                    "example": "1245.3"
+                },
+                "completed_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "completed_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-06-17"
+                },
+                "decided_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "decided_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "is_cleared": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "is_complete": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "is_pending": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "landing_count": {
+                    "type": "integer",
+                    "example": 3
+                },
+                "notes": {
+                    "type": "string",
+                    "example": "Vibration within limits"
+                },
+                "result": {
+                    "type": "string",
+                    "enum": [
+                        "passed",
+                        "failed"
+                    ],
+                    "example": "passed"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-06-16T03:04:05Z"
+                },
+                "utc_time": {
+                    "type": "string",
+                    "example": "2026-06-17T08:30:00Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MCFListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MCFResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "mcf"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MCFResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MCFResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MasterSettingsAttributes": {
+            "type": "object",
+            "properties": {
+                "company_name": {
+                    "type": "string",
+                    "example": "Wucher"
+                },
+                "cover_file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "cover_original_size_bytes": {
+                    "type": "integer",
+                    "example": 2048000
+                },
+                "cover_thumbnail_url": {
+                    "type": "string",
+                    "example": "https://cdn.example.com/cover.thumb.png"
+                },
+                "cover_url": {
+                    "type": "string",
+                    "example": "https://cdn.example.com/cover.png"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "logo_file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "logo_original_size_bytes": {
+                    "type": "integer",
+                    "example": 1024000
+                },
+                "logo_thumbnail_url": {
+                    "type": "string",
+                    "example": "https://cdn.example.com/logo.thumb.png"
+                },
+                "logo_url": {
+                    "type": "string",
+                    "example": "https://cdn.example.com/logo.png"
+                },
+                "subtitle": {
+                    "type": "string",
+                    "example": "Flight operations platform"
+                },
+                "title": {
+                    "type": "string",
+                    "example": "Welcome to Wucher"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraAttributes": {
+            "type": "object",
+            "properties": {
+                "MS_ENTRA_AUTHORITY": {
+                    "type": "string",
+                    "example": "https://login.microsoftonline.com/"
+                },
+                "MS_ENTRA_CLIENT_ID": {
+                    "type": "string",
+                    "example": "your-client-id"
+                },
+                "MS_ENTRA_CLIENT_SECRET": {
+                    "type": "string",
+                    "example": "********"
+                },
+                "MS_ENTRA_REDIRECT_URL": {
+                    "type": "string",
+                    "example": "https://example.com/api/v1/auth/microsoft/callback"
+                },
+                "MS_ENTRA_SCOPES": {
+                    "type": "string",
+                    "example": "openid,profile,email"
+                },
+                "MS_ENTRA_TENANT_ID": {
+                    "type": "string",
+                    "example": "your-tenant-id"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "master_settings_microsoft_entra_sso"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MasterSettingsResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "master_settings"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MasterSettingsResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "end_time": {
+                    "type": "string",
+                    "example": "22:05"
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionFileItem"
+                    }
+                },
+                "flight": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionFlightRef"
+                },
+                "forms": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionForms"
+                },
+                "mission_code": {
+                    "type": "string",
+                    "example": "HEMS-26-1"
+                },
+                "note": {
+                    "type": "string",
+                    "example": "Mission note"
+                },
+                "start_time": {
+                    "type": "string",
+                    "example": "04:49"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "completed"
+                },
+                "subtypes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionSubtypeRef"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "HEMS"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-20T08:00:00Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionDataTableResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "draw": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "records_filtered": {
+                            "type": "integer",
+                            "example": 42
+                        },
+                        "records_total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionFileItem": {
+            "type": "object",
+            "properties": {
+                "attachment_id": {
+                    "type": "string",
+                    "example": "019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/brief.pdf?X-Amz-Signature=..."
+                },
+                "file_name": {
+                    "type": "string",
+                    "example": "mission-brief.pdf"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e"
+                },
+                "thumbnail_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/thumbnails/2026/04/05/brief.png?X-Amz-Signature=..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionFlightRef": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "M-062226-001"
+                },
+                "date": {
+                    "type": "string",
+                    "example": "2026-04-20"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionForms": {
+            "type": "object",
+            "properties": {
+                "flight_data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.FlightDataResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 120
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "mission"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionSubtypeRef": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a99"
+                },
+                "subtype": {
+                    "type": "string",
+                    "example": "PRIM"
+                },
+                "subtype_name": {
+                    "type": "string",
+                    "example": "Nicht transportfaehig"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionTypeAttributes": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "HEMS"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "HEMS"
+                },
+                "subtypes": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionTypeSubtypeItem"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionTypeListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionTypeResource"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionTypeResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.MissionTypeAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a77"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "mission_type"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.MissionTypeSubtypeItem": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "example": "PRIM"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a99"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Primary"
+                },
+                "task_name": {
+                    "type": "string",
+                    "example": "Nicht transportfaehig"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.OtherPersonAttributes": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "guest@example.com"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Guest Person"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.OtherPersonListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.OtherPersonResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "other_person"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.OtherPersonResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ReserveAcListResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResource"
+                    }
+                },
+                "meta": {
+                    "type": "object",
+                    "properties": {
+                        "page_number": {
+                            "type": "integer",
+                            "example": 1
+                        },
+                        "page_size": {
+                            "type": "integer",
+                            "example": 20
+                        },
+                        "total": {
+                            "type": "integer",
+                            "example": 1
+                        }
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ReserveAcResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "reserve_ac"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.ReserveAcResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "example": "doctor@example.com"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Hunter Wolfgang"
+                },
+                "role": {
+                    "type": "string",
+                    "example": "doctor"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverDutyRosterDetailsResponse": {
+            "type": "object",
+            "properties": {
+                "doctor": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew"
+                    }
+                },
+                "helper": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew"
+                    }
+                },
+                "other_person": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew"
+                    }
+                },
+                "pilot": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterPilotCrew"
+                    }
+                },
+                "rescuer": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverDutyRosterPilotCrew": {
+            "type": "object",
+            "properties": {
+                "co_pilot": {
+                    "type": "boolean"
+                },
+                "crew_type": {
+                    "type": "string",
+                    "example": "main"
+                },
+                "email": {
+                    "type": "string",
+                    "example": "pilot@example.com"
+                },
+                "examiner": {
+                    "type": "boolean"
+                },
+                "flight_instructor": {
+                    "type": "boolean"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "line_checker": {
+                    "type": "boolean"
+                },
+                "mobile_phone": {
+                    "type": "string",
+                    "example": "+43-1234"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Hunter Wolfgang"
+                },
+                "role": {
+                    "type": "string",
+                    "example": "pilot"
+                },
+                "supervisor": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverFileAttributes": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/takeover-report.pdf?X-Amz-Signature=..."
+                },
+                "file_attachment_id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-222222222222"
+                },
+                "file_name": {
+                    "type": "string",
+                    "example": "takeover-report.pdf"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverFileResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverFileAttributes"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-111111111111"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "takeover_file"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverHelicopter": {
+            "type": "object",
+            "properties": {
+                "designation": {
+                    "type": "string",
+                    "example": "OE-XHZ"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "1234"
+                },
+                "last_daily_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspection"
+                },
+                "maintenance_schedules": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes"
+                    }
+                },
+                "type": {
+                    "type": "string",
+                    "example": "EC-135"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverResource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverResponseAttributes"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "takeover"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverResponse": {
+            "type": "object",
+            "properties": {
+                "data": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverResource"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.TakeoverResponseAttributes": {
+            "type": "object",
+            "properties": {
+                "base": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseInfo"
+                },
+                "base_id": {
+                    "type": "string"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "duty_date": {
+                    "type": "string"
+                },
+                "files": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverFileResource"
+                    }
+                },
+                "flight_id": {
+                    "type": "string"
+                },
+                "flight_inspection_id": {
+                    "type": "string"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverHelicopter"
+                },
+                "helicopter_id": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcInspectionSummary"
+                },
+                "notes": {
+                    "type": "string"
+                },
+                "reserve_ac_id": {
+                    "type": "string"
+                },
+                "roster_detail": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterDetailsResponse"
+                },
+                "shift_end": {
+                    "type": "string"
+                },
+                "shift_start": {
+                    "type": "string"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_response.UserRef": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Ganahl Stefan"
+                },
+                "uuid": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.AirRescuerChecklistBaseInfo": {
+            "type": "object",
+            "properties": {
+                "base_abbreviation": {
+                    "type": "string",
+                    "example": "G1"
+                },
+                "base_category": {
+                    "type": "string",
+                    "example": "hems"
+                },
+                "base_name": {
+                    "type": "string",
+                    "example": "Gallus 1 - Zurs Lech"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.AirRescuerChecklistItemInput": {
+            "type": "object",
+            "required": [
+                "name"
+            ],
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "example": "Oxygen supply check"
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerAttachmentAttributes": {
+            "type": "object",
+            "properties": {
+                "attached_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "category": {
+                    "type": "string",
+                    "example": "document"
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "file_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_primary": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "ref_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "ref_type": {
+                    "type": "string",
+                    "example": "helicopter"
+                },
+                "sort_order": {
+                    "type": "integer",
+                    "example": 0
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFileAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "extension": {
+                    "type": "string",
+                    "example": "pdf"
+                },
+                "failed_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "failure_reason": {
+                    "type": "string",
+                    "example": ""
+                },
+                "file_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "folder_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "is_template": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "mime_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "policy.pdf"
+                },
+                "name_normalized": {
+                    "type": "string",
+                    "example": "policy.pdf"
+                },
+                "processed_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "processing_started_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "purge_at": {
+                    "type": "string",
+                    "example": "2026-04-12T03:04:05Z"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "example": 1024
+                },
+                "status": {
+                    "type": "string",
+                    "example": "validated"
+                },
+                "trashed_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "upload_error": {
+                    "type": "string",
+                    "example": ""
+                },
+                "validated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFileAuditAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFileDetailAttributes": {
+            "type": "object",
+            "properties": {
+                "audit": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileAuditAttributes"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "extension": {
+                    "type": "string",
+                    "example": "pdf"
+                },
+                "is_template": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "location": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileLocationAttributes"
+                },
+                "mime_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "policy.pdf"
+                },
+                "name_normalized": {
+                    "type": "string",
+                    "example": "policy.pdf"
+                },
+                "preview_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.preview.pdf?X-Amz-Signature=..."
+                },
+                "processing": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileProcessingAttributes"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "example": 1024
+                },
+                "status": {
+                    "type": "string",
+                    "example": "ready"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFileLocationAttributes": {
+            "type": "object",
+            "properties": {
+                "folder_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFileProcessingAttributes": {
+            "type": "object",
+            "properties": {
+                "failed_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "failure_reason": {
+                    "type": "string",
+                    "example": "processing validation failed"
+                },
+                "processed_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "processing_started_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "validated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFileUploadIntentAttributes": {
+            "type": "object",
+            "properties": {
+                "expires_at": {
+                    "type": "string",
+                    "example": "2026-04-05T07:29:34Z"
+                },
+                "expires_in_seconds": {
+                    "type": "integer",
+                    "example": 900
+                },
+                "file": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileUploadFile"
+                },
+                "method": {
+                    "type": "string",
+                    "example": "PUT"
+                },
+                "object": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileUploadObject"
+                },
+                "required_headers": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
+                },
+                "upload_intent_uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "upload_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/..."
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFolderAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "depth": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "name": {
+                    "type": "string",
+                    "example": "operations"
+                },
+                "name_normalized": {
+                    "type": "string",
+                    "example": "operations"
+                },
+                "parent_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "path_cache": {
+                    "type": "string",
+                    "example": "/root/operations"
+                },
+                "purge_at": {
+                    "type": "string",
+                    "example": "2026-04-12T03:04:05Z"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFolderAuditAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-03-12T03:04:05Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFolderDetailAttributes": {
+            "type": "object",
+            "properties": {
+                "audit": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFolderAuditAttributes"
+                },
+                "depth": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "location": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFolderLocationAttributes"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "operations"
+                },
+                "name_normalized": {
+                    "type": "string",
+                    "example": "operations"
+                },
+                "path_cache": {
+                    "type": "string",
+                    "example": "/root/operations"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileManagerFolderLocationAttributes": {
+            "type": "object",
+            "properties": {
+                "parent_id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileUploadFile": {
+            "type": "object",
+            "properties": {
+                "mime_type": {
+                    "type": "string",
+                    "example": "application/pdf"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "policy-final.pdf"
+                },
+                "size_bytes": {
+                    "type": "integer",
+                    "example": 1024
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FileUploadObject": {
+            "type": "object",
+            "properties": {
+                "bucket": {
+                    "type": "string",
+                    "example": "wucher-file-dev"
+                },
+                "key": {
+                    "type": "string",
+                    "example": "files/2026/04/05/018f3a5c7a6f7c2a8d4a4b5b1f6c8e9d.pdf"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusComplaint": {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusComplaintAction"
+                },
+                "aircraft_hours_at_report": {
+                    "type": "string"
+                },
+                "description": {
+                    "type": "string"
+                },
+                "flight_id": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "mel": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusComplaintMEL"
+                },
+                "nsr": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusComplaintNSR"
+                },
+                "reported_at": {
+                    "type": "string"
+                },
+                "reported_by": {
+                    "type": "string"
+                },
+                "reported_by_name": {
+                    "type": "string"
+                },
+                "reported_by_short": {
+                    "type": "string"
+                },
+                "status": {
+                    "type": "string",
+                    "enum": [
+                        "active_non_mel",
+                        "active_mel",
+                        "serviced"
+                    ]
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusComplaintAction": {
+            "type": "object",
+            "properties": {
+                "aircraft_hours_at_fix": {
+                    "type": "string"
+                },
+                "signed_at": {
+                    "type": "string"
+                },
+                "signed_by": {
+                    "type": "string"
+                },
+                "signed_by_name": {
+                    "type": "string"
+                },
+                "signed_by_short": {
+                    "type": "string"
+                },
+                "taken": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusComplaintMEL": {
+            "type": "object",
+            "properties": {
+                "classified_at": {
+                    "type": "string"
+                },
+                "classified_by": {
+                    "type": "string"
+                },
+                "classified_by_name": {
+                    "type": "string"
+                },
+                "classified_by_short": {
+                    "type": "string"
+                },
+                "deadline": {
+                    "type": "string"
+                },
+                "severity": {
+                    "type": "integer",
+                    "enum": [
+                        0,
+                        1,
+                        2,
+                        3,
+                        4
+                    ]
+                },
+                "severity_label": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusComplaintNSR": {
+            "type": "object",
+            "properties": {
+                "decided_at": {
+                    "type": "string"
+                },
+                "decided_by": {
+                    "type": "string"
+                },
+                "decided_by_name": {
+                    "type": "string"
+                },
+                "decided_by_short": {
+                    "type": "string"
+                },
+                "is_nsr": {
+                    "type": "boolean"
+                },
+                "reason": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusEASARelease": {
+            "type": "object",
+            "properties": {
+                "easa_ac_hours": {
+                    "type": "string"
+                },
+                "easa_date": {
+                    "type": "string"
+                },
+                "easa_location": {
+                    "type": "string"
+                },
+                "easa_maint_manual_rev_airframe": {
+                    "type": "string"
+                },
+                "easa_maint_manual_rev_engine": {
+                    "type": "string"
+                },
+                "easa_permit_no": {
+                    "type": "string"
+                },
+                "easa_signer_id": {
+                    "type": "string"
+                },
+                "easa_wo_no": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "is_signed": {
+                    "type": "boolean"
+                },
+                "missing_sign_fields": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "signed_at": {
+                    "type": "string"
+                },
+                "signed_by": {
+                    "type": "string"
+                },
+                "signed_by_name": {
+                    "type": "string"
+                },
+                "signed_by_short": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusFileAttributes": {
+            "type": "object",
+            "required": [
+                "category",
+                "file_id"
+            ],
+            "properties": {
+                "category": {
+                    "type": "string",
+                    "enum": [
+                        "wb",
+                        "bfi"
+                    ],
+                    "example": "wb"
+                },
+                "file_id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "is_mandatory": {
+                    "description": "IsMandatory — when true, this file must be checked (is_done) during takeover.",
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusHelicopter": {
+            "type": "object",
+            "properties": {
+                "designation": {
+                    "type": "string",
+                    "example": "AIRBUS H145"
+                },
+                "flight_id": {
+                    "description": "FlightID — id of the aircraft's current active flight (present only when it is in\nuse / booked). The fleet page uses it to create an EASA release scoped to the flight.",
+                    "type": "string",
+                    "example": "019d6774-98e8-7fba-9ef4-3795c0da8a13"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "D-HEMS"
+                },
+                "status": {
+                    "type": "string",
+                    "enum": [
+                        "available",
+                        "booked",
+                        "aog",
+                        "mcf"
+                    ],
+                    "example": "available"
+                },
+                "status_reasons": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusHelicopterReason"
+                    }
+                },
+                "type": {
+                    "type": "string",
+                    "example": "EC-135"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusHelicopterReason": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "enum": [
+                        "manual_aog",
+                        "mel_expired",
+                        "non_mel_pending",
+                        "inspection_overdue"
+                    ]
+                },
+                "complaint_id": {
+                    "type": "string"
+                },
+                "detail": {
+                    "type": "string"
+                },
+                "schedule_id": {
+                    "type": "string"
+                },
+                "since": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusMCF": {
+            "type": "object",
+            "properties": {
+                "active": {
+                    "description": "Active — true when the helicopter is currently in MCF (an open draft, or a signed\nbut failed MCF still needing a re-flight); false when cleared/cancelled/none.",
+                    "type": "boolean"
+                },
+                "af_hours": {
+                    "description": "AFHours / LandingCount present only once the MCF is signed; omitted for none/draft/cancelled.",
+                    "type": "string"
+                },
+                "date": {
+                    "type": "string"
+                },
+                "id": {
+                    "type": "string"
+                },
+                "landing_count": {
+                    "type": "integer"
+                },
+                "sign": {
+                    "description": "Sign — true once the MCF is completed/signed; false while it is still a draft.",
+                    "type": "boolean"
+                },
+                "signed_by": {
+                    "description": "SignedBy / SignedByName / SignedByShort — who signed (completed) the MCF; empty while unsigned.",
+                    "type": "string"
+                },
+                "signed_by_name": {
+                    "type": "string"
+                },
+                "signed_by_short": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusSummary": {
+            "type": "object",
+            "properties": {
+                "airframe": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusSummaryAirframe"
+                },
+                "engine_1": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusSummaryEngine"
+                },
+                "engine_2": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusSummaryEngine"
+                },
+                "flight_reports": {
+                    "type": "number"
+                },
+                "hook_releases": {
+                    "type": "number"
+                },
+                "landings": {
+                    "type": "number"
+                },
+                "rotor_brake_cycles": {
+                    "type": "number"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusSummaryAirframe": {
+            "type": "object",
+            "properties": {
+                "cycles": {
+                    "type": "number"
+                },
+                "hours": {
+                    "type": "number"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.FleetStatusSummaryEngine": {
+            "type": "object",
+            "properties": {
+                "ccc": {
+                    "type": "number"
+                },
+                "gpc_ng_n1": {
+                    "type": "number"
+                },
+                "hours": {
+                    "type": "number"
+                },
+                "ptc_nf_n2": {
+                    "type": "number"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterAuditUser": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "John Doe"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterFileAttributes": {
+            "type": "object",
+            "properties": {
+                "attachment_pending": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "file_attachment_id": {
+                    "type": "string",
+                    "example": "019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e"
+                },
+                "file_name": {
+                    "type": "string",
+                    "example": "Before Flight Checklist.pdf"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "helicopter_name": {
+                    "type": "string",
+                    "example": "AIRBUS H145"
+                },
+                "is_mandatory": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "is_template": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "position": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "section": {
+                    "type": "string",
+                    "example": "bfi"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterFoto": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/helicopter/foto.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Expires=900\u0026X-Amz-Signature=abc123"
+                },
+                "original_size_bytes": {
+                    "type": "integer",
+                    "example": 1024000
+                },
+                "thumbnail_download_url": {
+                    "type": "string",
+                    "example": "https://storage.example.com/helicopter/foto.thumb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Expires=900\u0026X-Amz-Signature=abc123"
+                },
+                "uuid": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterInspectionFilesChecklist": {
+            "type": "object",
+            "properties": {
+                "completed": {
+                    "type": "integer",
+                    "example": 47
+                },
+                "total": {
+                    "type": "integer",
+                    "example": 47
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterLastDailyBase": {
+            "type": "object",
+            "properties": {
+                "base_abbreviation": {
+                    "type": "string",
+                    "example": "G1"
+                },
+                "base_name": {
+                    "type": "string",
+                    "example": "Gallus 1 - Zurs Lech"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "hems"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspection": {
+            "type": "object",
+            "properties": {
+                "base": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterLastDailyBase"
+                },
+                "inspected_at": {
+                    "type": "string",
+                    "example": "2026-05-25T07:47:00Z"
+                },
+                "inspection_files_checklist": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterInspectionFilesChecklist"
+                },
+                "inspection_id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "inspector": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspector"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "inspected_cleared"
+                },
+                "utc_time": {
+                    "type": "string",
+                    "example": "07:47"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspector": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "license_no": {
+                    "type": "string",
+                    "example": "4521"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Teodora Lesmana"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes": {
+            "type": "object",
+            "properties": {
+                "due": {
+                    "type": "string",
+                    "example": "1200"
+                },
+                "ext": {
+                    "type": "string",
+                    "example": "1300"
+                },
+                "inspection_type": {
+                    "type": "string",
+                    "example": "A/F"
+                },
+                "type": {
+                    "type": "string",
+                    "example": "100H"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcAircraftSummary": {
+            "type": "object",
+            "properties": {
+                "aog": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "designation": {
+                    "type": "string",
+                    "example": "AIRBUS H145"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "identifier": {
+                    "type": "string",
+                    "example": "D-HYAR"
+                },
+                "is_active": {
+                    "type": "boolean",
+                    "example": true
+                },
+                "type": {
+                    "type": "string",
+                    "example": "H145"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcAttributes": {
+            "type": "object",
+            "properties": {
+                "created_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "created_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "deleted_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "deleted_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                },
+                "flight_id": {
+                    "type": "string",
+                    "example": "019d6773-ccca-71dd-b9c7-8e6f531deb90"
+                },
+                "helicopter": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcAircraftSummary"
+                },
+                "helicopter_id": {
+                    "type": "string",
+                    "example": "019d6771-5fb5-7337-837f-bc5ed85181a1"
+                },
+                "inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcInspectionSummary"
+                },
+                "last_daily_inspection": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcLastDailyInfo"
+                },
+                "status": {
+                    "type": "string",
+                    "example": "pending"
+                },
+                "updated_at": {
+                    "type": "string",
+                    "example": "2026-04-14T08:00:00Z"
+                },
+                "updated_by": {
+                    "type": "string",
+                    "example": "019d61db-53c6-7280-87ec-e65f205c6d3b"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcBeforeInspectionFields": {
+            "type": "object",
+            "properties": {
+                "fuel_added_amount": {
+                    "type": "number"
+                },
+                "fuel_amount": {
+                    "type": "number"
+                },
+                "fuel_unit": {
+                    "type": "string"
+                },
+                "hydraulic_lh_checked": {
+                    "type": "boolean"
+                },
+                "hydraulic_rh_checked": {
+                    "type": "boolean"
+                },
+                "note": {
+                    "type": "string"
+                },
+                "oil_engine_nr1_checked": {
+                    "type": "boolean"
+                },
+                "oil_engine_nr2_checked": {
+                    "type": "boolean"
+                },
+                "oil_transmission_igb_checked": {
+                    "type": "boolean"
+                },
+                "oil_transmission_mgb_checked": {
+                    "type": "boolean"
+                },
+                "oil_transmission_tgb_checked": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcBeforeSectionDTO": {
+            "type": "object",
+            "properties": {
+                "completed": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "done_file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO"
+                    }
+                },
+                "fields": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcBeforeInspectionFields"
+                },
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO"
+                    }
+                },
+                "total": {
+                    "type": "integer",
+                    "example": 3
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO": {
+            "type": "object",
+            "properties": {
+                "download_url": {
+                    "type": "string",
+                    "example": "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."
+                },
+                "file_attachment_id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-222222222222"
+                },
+                "file_name": {
+                    "type": "string",
+                    "example": "Before Flight Checklist.pdf"
+                },
+                "helicopter_file_id": {
+                    "type": "string",
+                    "example": "019d7000-aaaa-7bbb-8ccc-111111111111"
+                },
+                "is_done": {
+                    "type": "boolean",
+                    "example": false
+                },
+                "is_mandatory": {
+                    "type": "boolean",
+                    "example": true
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcFleetStatusFileSectionDTO": {
+            "type": "object",
+            "properties": {
+                "completed": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "done_file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO"
+                    }
+                },
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO"
+                    }
+                },
+                "total": {
+                    "type": "integer",
+                    "example": 2
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcInspectionSummary": {
+            "type": "object",
+            "properties": {
+                "before": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcBeforeSectionDTO"
+                },
+                "fleet_status_file": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFleetStatusFileSectionDTO"
+                },
+                "id": {
+                    "type": "string",
+                    "example": "019d6772-471c-7b70-b42a-d94020ef61e4"
+                },
+                "inspection_date": {
+                    "type": "string",
+                    "example": "2026-04-15"
+                },
+                "prepare": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcPrepareSectionDTO"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcLastDailyInfo": {
+            "type": "object",
+            "properties": {
+                "date": {
+                    "type": "string",
+                    "example": "17.04.2026"
+                },
+                "name": {
+                    "type": "string",
+                    "example": "Ganahl Stefan"
+                },
+                "short_name": {
+                    "type": "string",
+                    "example": "GAN"
+                },
+                "utc_time": {
+                    "type": "string",
+                    "example": "10:57"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcPrepareFields": {
+            "type": "object",
+            "properties": {
+                "notam_briefing": {
+                    "type": "boolean"
+                },
+                "operational_flight_plan": {
+                    "type": "boolean"
+                },
+                "weather_briefing": {
+                    "type": "boolean"
+                }
+            }
+        },
+        "wucher_internal_transport_http_dto_shared.ReserveAcPrepareSectionDTO": {
+            "type": "object",
+            "properties": {
+                "completed": {
+                    "type": "integer",
+                    "example": 1
+                },
+                "done_file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO"
+                    }
+                },
+                "file_checklist": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO"
+                    }
+                },
+                "prepare_fields": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcPrepareFields"
+                },
+                "total": {
+                    "type": "integer",
+                    "example": 3
+                }
+            }
+        },
+        "wucher_internal_transport_http_jsonapi.Document": {
+            "type": "object",
+            "properties": {
+                "data": {},
+                "meta": {}
+            }
+        },
+        "wucher_internal_transport_http_jsonapi.ErrorDocument": {
+            "type": "object",
+            "properties": {
+                "errors": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorObject"
+                    }
+                }
+            }
+        },
+        "wucher_internal_transport_http_jsonapi.ErrorObject": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string"
+                },
+                "detail": {
+                    "type": "string"
+                },
+                "error_code": {
+                    "type": "string"
+                },
+                "source": {
+                    "$ref": "#/definitions/wucher_internal_transport_http_jsonapi.ErrorSource"
+                },
+                "status": {
+                    "type": "string"
+                },
+                "title": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_jsonapi.ErrorSource": {
+            "type": "object",
+            "properties": {
+                "pointer": {
+                    "type": "string"
+                }
+            }
+        },
+        "wucher_internal_transport_http_jsonapi.Resource": {
+            "type": "object",
+            "properties": {
+                "attributes": {
+                    "type": "object",
+                    "additionalProperties": {}
+                },
+                "id": {
+                    "type": "string"
+                },
+                "type": {
+                    "type": "string"
+                }
+            }
+        }
+    },
+    "tags": [
+        {
+            "description": "Corrective-action sign-off for a helicopter. After a complaint's action_taken is recorded, it is signed off here (POST /action-signoffs/sign with complaint_id); a fleet-wide sign-off (no complaint_id) is also supported. A signed sign-off is the prerequisite for creating an EASA maintenance release.",
+            "name": "Complaints - Sign Off"
+        }
+    ]
+}
\ No newline at end of file
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
new file mode 100644
index 0000000..c5d27f0
--- /dev/null
+++ b/docs/swagger.yaml
@@ -0,0 +1,26515 @@
+basePath: /
+definitions:
+  internal_transport_http_handlers.loginBrandingContentAttrsDTO:
+    properties:
+      subtitle:
+        type: string
+      title:
+        type: string
+      updated_at:
+        type: string
+      version:
+        type: string
+    type: object
+  internal_transport_http_handlers.loginBrandingContentData:
+    properties:
+      attributes:
+        $ref: '#/definitions/internal_transport_http_handlers.loginBrandingContentAttrsDTO'
+      type:
+        type: string
+    type: object
+  internal_transport_http_handlers.loginBrandingContentDocument:
+    properties:
+      data:
+        $ref: '#/definitions/internal_transport_http_handlers.loginBrandingContentData'
+    type: object
+  wucher_internal_transport_http_dto.AfterFlightInspectionAttributes:
+    properties:
+      completed:
+        example: 1
+        type: integer
+      created_at:
+        example: "2026-04-09T05:00:00Z"
+        type: string
+      done_file_checklist:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionFileChecklistItem'
+        type: array
+      file_checklist:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionFileChecklistItem'
+        type: array
+      flight_data_count:
+        example: 2
+        type: integer
+      flight_inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FlightInspectionResource'
+      flight_inspection_id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      flight_time_seconds:
+        example: 9000
+        type: integer
+      helicopter:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterResource'
+      hydraulic_lh_checked:
+        example: "1"
+        type: string
+      hydraulic_rh_checked:
+        example: "1"
+        type: string
+      id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      mission_code:
+        example: M-2026-001
+        type: string
+      mission_type:
+        items:
+          type: string
+        type: array
+      note:
+        example: All checks completed
+        type: string
+      oil_engine_nr1_checked:
+        example: "1"
+        type: string
+      oil_engine_nr2_checked:
+        example: "1"
+        type: string
+      oil_transmission_igb_checked:
+        example: "1"
+        type: string
+      oil_transmission_mgb_checked:
+        example: "1"
+        type: string
+      oil_transmission_tgb_checked:
+        example: "1"
+        type: string
+      route:
+        items:
+          type: string
+        type: array
+      total:
+        example: 3
+        type: integer
+      total_flight:
+        example: 3
+        type: integer
+      updated_at:
+        example: "2026-04-09T05:00:00Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.AfterFlightInspectionFileChecklistItem:
+    properties:
+      download_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=...
+        type: string
+      file_name:
+        example: After Flight Checklist.pdf
+        type: string
+      helicopter_file_id:
+        example: 019d7000-aaaa-7bbb-8ccc-111111111111
+        type: string
+      is_done:
+        example: false
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto.AfterFlightInspectionResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionAttributes'
+      id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      type:
+        example: after_flight_inspection
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.AfterFlightInspectionResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResource'
+    type: object
+  wucher_internal_transport_http_dto.AfterFlightInspectionUpsertAttributes:
+    properties:
+      hydraulic_lh_checked:
+        type: string
+      hydraulic_rh_checked:
+        type: string
+      note:
+        type: string
+      oil_engine_nr1_checked:
+        type: string
+      oil_engine_nr2_checked:
+        type: string
+      oil_transmission_igb_checked:
+        type: string
+      oil_transmission_mgb_checked:
+        type: string
+      oil_transmission_tgb_checked:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.AfterFlightInspectionUpsertData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionUpsertAttributes'
+      type:
+        enum:
+        - after_flight_inspection_upsert
+        - after_flight_inspection
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.AfterFlightInspectionUpsertRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionUpsertData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.AirRescuerProfileAttributes:
+    properties:
+      location:
+        maxLength: 255
+        type: string
+      note:
+        type: string
+      postcode:
+        maxLength: 32
+        type: string
+      responsible_flight_rescuer:
+        type: boolean
+      short_name:
+        maxLength: 120
+        type: string
+      street_line:
+        maxLength: 255
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.AirRescuerProfileUpdateAttributes:
+    properties:
+      location:
+        maxLength: 255
+        type: string
+      note:
+        type: string
+      postcode:
+        maxLength: 32
+        type: string
+      responsible_flight_rescuer:
+        type: boolean
+      short_name:
+        maxLength: 120
+        type: string
+      street_line:
+        maxLength: 255
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.AuthCurrentUserAttributes:
+    properties:
+      auth_provider:
+        example: email
+        type: string
+      dul_bases:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.DULBase'
+        type: array
+      email:
+        example: user@example.com
+        type: string
+      email_sso:
+        example: user.sso@example.com
+        type: string
+      email_verified_at:
+        example: "2026-02-05T10:00:00Z"
+        type: string
+      first_name:
+        example: John
+        type: string
+      foto:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.UserFoto'
+      is_previously_configured:
+        example: false
+        type: boolean
+      last_name:
+        example: Doe
+        type: string
+      linked_sso:
+        example: false
+        type: boolean
+      login_method:
+        example: email
+        type: string
+      microsoft_scope:
+        example: openid profile email offline_access User.Read
+        type: string
+      mobile_phone:
+        example: "+628123456789"
+        type: string
+      permission_modules:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionGroupResource'
+        type: array
+      permissions:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionMini'
+        type: array
+      pin_blocked:
+        example: false
+        type: boolean
+      pin_configured:
+        example: false
+        type: boolean
+      roles:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.RoleMini'
+        type: array
+      timezone:
+        example: Asia/Jakarta
+        type: string
+      totp_enabled:
+        example: false
+        type: boolean
+      webauthn_configured:
+        example: false
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto.AuthCurrentUserResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthCurrentUserAttributes'
+          id:
+            example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+            type: string
+          type:
+            example: user
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.AuthSessionDeleteResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              deleted:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: auth_session_delete
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.AuthSessionItem:
+    properties:
+      active_now:
+        example: true
+        type: boolean
+      created_at:
+        example: "2026-03-13T12:00:00Z"
+        type: string
+      device_name:
+        example: Chrome on macOS
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      ip_address:
+        example: 127.0.0.1
+        type: string
+      last_active_at:
+        example: "2026-03-13T12:10:00Z"
+        type: string
+      user_agent:
+        example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.AuthSessionsResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              sessions:
+                items:
+                  $ref: '#/definitions/wucher_internal_transport_http_dto.AuthSessionItem'
+                type: array
+            type: object
+          type:
+            example: auth_sessions
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.BaseAttributes:
+    properties:
+      address:
+        example: Lude Airfield
+        type: string
+      base:
+        example: Lude
+        type: string
+      base_abbreviation:
+        example: LOIG
+        type: string
+      base_category:
+        enum:
+        - regular
+        - hems
+        example: regular
+        type: string
+      checklist:
+        example: false
+        type: boolean
+      control_center:
+        example: false
+        type: boolean
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      default_end_time_type:
+        enum:
+        - FIXED
+        - BMCT
+        - ECET
+        example: FIXED
+        type: string
+      default_start_time_type:
+        enum:
+        - FIXED
+        - BMCT
+        - ECET
+        example: FIXED
+        type: string
+      dry:
+        example: false
+        type: boolean
+      dul:
+        example: false
+        type: boolean
+      email:
+        example: lude@wucher.local
+        type: string
+      foto:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseFoto'
+      hems_edc:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.BaseContact'
+        type: array
+      hems_edc_contact_ids:
+        items:
+          type: string
+        type: array
+      is_active:
+        example: true
+        type: boolean
+      landline_number:
+        example: +62-21-1234
+        type: string
+      latitude:
+        example: 47.3769
+        type: number
+      leg_time:
+        example: "00:20"
+        type: string
+      longitude:
+        example: 8.5417
+        type: number
+      med_pax:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.BaseContact'
+        type: array
+      med_pax_contact_ids:
+        items:
+          type: string
+        type: array
+      mobile_number:
+        example: +62-812-1234
+        type: string
+      notes:
+        example: Main base
+        type: string
+      operational_shift_times:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.BaseOperationalShiftTime'
+        type: array
+      responsible_pilot_contact_ids:
+        items:
+          type: string
+        type: array
+      responsible_pilots:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.BaseContact'
+        type: array
+      shift_time:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseShiftTime'
+      sms_alert:
+        example: false
+        type: boolean
+      sortkey:
+        example: 1
+        type: integer
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      utc:
+        example: "0"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.BaseContact:
+    properties:
+      first_name:
+        type: string
+      id:
+        type: string
+      last_name:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.BaseCreateAttributes:
+    properties:
+      address:
+        example: Lude Airfield
+        type: string
+      base:
+        example: Lude
+        type: string
+      base_abbreviation:
+        example: LOIG
+        type: string
+      base_category:
+        enum:
+        - regular
+        - hems
+        example: regular
+        type: string
+      checklist:
+        example: false
+        type: boolean
+      control_center:
+        example: false
+        type: boolean
+      default_end_time_type:
+        enum:
+        - FIXED
+        - BMCT
+        - ECET
+        example: FIXED
+        type: string
+      default_shift_end:
+        example: "21:00:00"
+        type: string
+      default_shift_start:
+        example: "06:00:00"
+        type: string
+      default_shift_time:
+        example: "12:00"
+        type: string
+      default_start_time_type:
+        enum:
+        - FIXED
+        - BMCT
+        - ECET
+        example: FIXED
+        type: string
+      dry:
+        example: false
+        type: boolean
+      dul:
+        example: false
+        type: boolean
+      email:
+        example: lude@wucher.local
+        type: string
+      file_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90
+        type: string
+      hems_edc_contact_ids:
+        items:
+          type: string
+        type: array
+      is_active:
+        example: true
+        type: boolean
+      landline_number:
+        example: +62-21-1234
+        type: string
+      latitude:
+        example: 47.3769
+        maximum: 90
+        minimum: -90
+        type: number
+      leg_time:
+        example: "00:20"
+        type: string
+      longitude:
+        example: 8.5417
+        maximum: 180
+        minimum: -180
+        type: number
+      med_pax_contact_ids:
+        items:
+          type: string
+        type: array
+      mobile_number:
+        example: +62-812-1234
+        type: string
+      notes:
+        example: Main base
+        type: string
+      operational_shift_times:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.BaseOperationalShiftTime'
+        type: array
+      responsible_pilot_contact_ids:
+        items:
+          type: string
+        type: array
+      shift_time:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseShiftTime'
+      sms_alert:
+        example: false
+        type: boolean
+      sortkey:
+        example: 1
+        type: integer
+      utc:
+        example: "0"
+        type: string
+    required:
+    - base
+    - latitude
+    - longitude
+    type: object
+  wucher_internal_transport_http_dto.BaseCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseCreateAttributes'
+      type:
+        enum:
+        - base
+        example: base
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.BaseCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.BaseDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.BaseResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.BaseDeleteAttributes:
+    properties:
+      deleted:
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto.BaseDeleteResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseDeleteAttributes'
+      id:
+        example: 019d6b10-a385-7e9e-a553-8e892bcec0ef
+        type: string
+      type:
+        example: base_delete
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.BaseDeleteResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseDeleteResource'
+    type: object
+  wucher_internal_transport_http_dto.BaseFoto:
+    properties:
+      download_url:
+        example: https://storage.example.com/base/lude.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=abc123
+        type: string
+      original_size_bytes:
+        example: 1024000
+        type: integer
+      thumbnail_download_url:
+        example: https://storage.example.com/base/lude.thumb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=abc123
+        type: string
+      uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.BaseListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.BaseResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.BaseOperationalShiftTime:
+    properties:
+      date_end:
+        example: "2026-04-12"
+        type: string
+      date_start:
+        example: "2026-04-12"
+        type: string
+      end_time_type:
+        enum:
+        - FIXED
+        - BMCT
+        - ECET
+        example: FIXED
+        type: string
+      shift_time:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseShiftTime'
+      start_time_type:
+        enum:
+        - FIXED
+        - BMCT
+        - ECET
+        example: FIXED
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.BaseResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: base
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.BaseResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseResource'
+    type: object
+  wucher_internal_transport_http_dto.BaseShiftTime:
+    properties:
+      end:
+        example: "21:00"
+        type: string
+      start:
+        example: "06:00"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.BaseUpdateAttributes:
+    properties:
+      address:
+        example: Lude Airfield
+        type: string
+      base:
+        example: Lude
+        type: string
+      base_abbreviation:
+        example: LOIG
+        type: string
+      base_category:
+        enum:
+        - regular
+        - hems
+        example: regular
+        type: string
+      checklist:
+        example: false
+        type: boolean
+      control_center:
+        example: false
+        type: boolean
+      default_end_time_type:
+        enum:
+        - FIXED
+        - BMCT
+        - ECET
+        example: FIXED
+        type: string
+      default_shift_end:
+        example: "21:00:00"
+        type: string
+      default_shift_start:
+        example: "06:00:00"
+        type: string
+      default_shift_time:
+        example: "12:00"
+        type: string
+      default_start_time_type:
+        enum:
+        - FIXED
+        - BMCT
+        - ECET
+        example: FIXED
+        type: string
+      dry:
+        example: false
+        type: boolean
+      dul:
+        example: false
+        type: boolean
+      email:
+        example: lude@wucher.local
+        type: string
+      file_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90
+        type: string
+      hems_edc_contact_ids:
+        items:
+          type: string
+        type: array
+      is_active:
+        example: true
+        type: boolean
+      landline_number:
+        example: +62-21-1234
+        type: string
+      latitude:
+        example: 47.3769
+        maximum: 90
+        minimum: -90
+        type: number
+      leg_time:
+        example: "00:20"
+        type: string
+      longitude:
+        example: 8.5417
+        maximum: 180
+        minimum: -180
+        type: number
+      med_pax_contact_ids:
+        items:
+          type: string
+        type: array
+      mobile_number:
+        example: +62-812-1234
+        type: string
+      notes:
+        example: Main base
+        type: string
+      operational_shift_times:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.BaseOperationalShiftTime'
+        type: array
+      responsible_pilot_contact_ids:
+        items:
+          type: string
+        type: array
+      shift_time:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseShiftTime'
+      sms_alert:
+        example: false
+        type: boolean
+      sortkey:
+        example: 1
+        type: integer
+      utc:
+        example: "0"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.BaseUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - base_update
+        example: base_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.BaseUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.BaseUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ContactBaseRole:
+    properties:
+      base_id:
+        type: string
+      base_name:
+        type: string
+      role_code:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.ContactBulkUpdateData:
+    properties:
+      attributes:
+        properties:
+          is_active:
+            example: true
+            type: boolean
+          user_ids:
+            example:
+            - 0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1
+            items:
+              type: string
+            minItems: 1
+            type: array
+        required:
+        - user_ids
+        type: object
+      type:
+        example: contact_bulk_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ContactBulkUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ContactBulkUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ContactChiefFlagsUpdateData:
+    properties:
+      attributes:
+        properties:
+          is_chief_physician:
+            type: boolean
+          is_chief_pilot:
+            type: boolean
+          is_chief_technician:
+            type: boolean
+        type: object
+      type:
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ContactChiefFlagsUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ContactChiefFlagsUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ContactCreateAttributes:
+    properties:
+      air_rescuer:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.AirRescuerProfileAttributes'
+      doctor:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.DoctorProfileAttributes'
+      email:
+        type: string
+      file_uuid:
+        maxLength: 64
+        type: string
+      first_name:
+        maxLength: 100
+        type: string
+      flight_assistant:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FlightAssistantProfileAttributes'
+      is_active:
+        type: boolean
+      is_admin:
+        type: boolean
+      last_name:
+        maxLength: 100
+        type: string
+      mobile_phone:
+        maxLength: 32
+        type: string
+      pilot:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PilotProfileAttributes'
+      role_id:
+        example: 0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1
+        type: string
+      role_ids:
+        example:
+        - 0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1
+        - 0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d2
+        items:
+          type: string
+        type: array
+      sortkey:
+        type: integer
+      sso_email:
+        type: string
+      staff:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.StaffProfileAttributes'
+      technician:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TechnicianProfileAttributes'
+      timezone:
+        maxLength: 64
+        type: string
+      username:
+        maxLength: 100
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.ContactCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ContactCreateAttributes'
+      type:
+        example: contact_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ContactCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ContactCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ContactDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ContactListItem'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.ContactLicenseUpdateData:
+    properties:
+      attributes:
+        properties:
+          license_no:
+            type: string
+        type: object
+      type:
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ContactLicenseUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ContactLicenseUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ContactListAttributes:
+    properties:
+      air_rescuer:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.AirRescuerProfileAttributes'
+      base_roles:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ContactBaseRole'
+        type: array
+      created_at:
+        type: string
+      created_by:
+        type: string
+      doctor:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.DoctorProfileAttributes'
+      email:
+        type: string
+      first_name:
+        type: string
+      flight_assistant:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FlightAssistantProfileAttributes'
+      is_active:
+        type: boolean
+      is_admin:
+        type: boolean
+      last_name:
+        type: string
+      license_no:
+        type: string
+      location:
+        type: string
+      mobile_phone:
+        type: string
+      note:
+        type: string
+      pilot:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PilotProfileAttributes'
+      pilot_category:
+        type: string
+      role_code:
+        type: string
+      role_name:
+        type: string
+      roles:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ContactRole'
+        type: array
+      set_password:
+        type: boolean
+      short_name:
+        type: string
+      sortkey:
+        type: integer
+      sso_email:
+        type: string
+      staff:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.StaffProfileAttributes'
+      technician:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TechnicianProfileAttributes'
+      updated_at:
+        type: string
+      updated_by:
+        type: string
+      username:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.ContactListItem:
+    properties:
+      created_at:
+        type: string
+      created_by:
+        type: string
+      email:
+        type: string
+      first_name:
+        type: string
+      id:
+        type: string
+      is_active:
+        type: boolean
+      is_admin:
+        type: boolean
+      last_name:
+        type: string
+      license_no:
+        type: string
+      location:
+        type: string
+      mobile_phone:
+        type: string
+      note:
+        type: string
+      pilot_category:
+        type: string
+      role_code:
+        type: string
+      role_name:
+        type: string
+      set_password:
+        type: boolean
+      short_name:
+        type: string
+      sortkey:
+        type: integer
+      updated_at:
+        type: string
+      updated_by:
+        type: string
+      username:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.ContactListResponse:
+    properties:
+      data:
+        items:
+          properties:
+            attributes:
+              $ref: '#/definitions/wucher_internal_transport_http_dto.ContactListAttributes'
+            id:
+              example: 019dcce4-f15e-7685-8e4c-76f8ad20594b
+              type: string
+            type:
+              example: contact
+              type: string
+          type: object
+        type: array
+      meta:
+        properties:
+          limit:
+            type: integer
+          offset:
+            type: integer
+          total:
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.ContactPilotCategoryUpdateData:
+    properties:
+      attributes:
+        properties:
+          pilot_category:
+            enum:
+            - regular
+            - freelance
+            - dry_lease
+            type: string
+        required:
+        - pilot_category
+        type: object
+      type:
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ContactPilotCategoryUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ContactPilotCategoryUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ContactRole:
+    properties:
+      id:
+        type: string
+      role_code:
+        type: string
+      role_name:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.ContactRoleUpdateData:
+    properties:
+      attributes:
+        properties:
+          role_code:
+            enum:
+            - pilot
+            - doctor
+            - air_rescuer
+            - technician
+            - flight_assistant
+            - staff
+            type: string
+        required:
+        - role_code
+        type: object
+      type:
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ContactRoleUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ContactRoleUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ContactSimpleSuccessResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              count:
+                type: integer
+              deleted:
+                type: boolean
+              updated:
+                type: boolean
+            type: object
+          type:
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.ContactStatusUpdateData:
+    properties:
+      attributes:
+        properties:
+          is_active:
+            type: boolean
+        type: object
+      type:
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ContactStatusUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ContactStatusUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ContactUpdateAttributes:
+    properties:
+      air_rescuer:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.AirRescuerProfileUpdateAttributes'
+      doctor:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.DoctorProfileUpdateAttributes'
+      email:
+        type: string
+      file_uuid:
+        maxLength: 64
+        type: string
+      first_name:
+        maxLength: 100
+        type: string
+      flight_assistant:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FlightAssistantProfileUpdateAttributes'
+      is_active:
+        type: boolean
+      is_admin:
+        type: boolean
+      last_name:
+        maxLength: 100
+        type: string
+      mobile_phone:
+        maxLength: 32
+        type: string
+      pilot:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PilotProfileUpdateAttributes'
+      role_id:
+        example: 0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1
+        type: string
+      role_ids:
+        example:
+        - 0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1
+        - 0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d2
+        items:
+          type: string
+        type: array
+      sortkey:
+        type: integer
+      sso_email:
+        type: string
+      staff:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.StaffProfileUpdateAttributes'
+      technician:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TechnicianProfileUpdateAttributes'
+      timezone:
+        maxLength: 64
+        type: string
+      username:
+        maxLength: 100
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.ContactUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ContactUpdateAttributes'
+      type:
+        example: contact_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ContactUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ContactUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.DULAttributes:
+    properties:
+      base:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.DULBaseRef'
+      created_at:
+        type: string
+      created_by:
+        type: string
+      date:
+        example: "2026-05-25"
+        type: string
+      images:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.DULImage'
+        type: array
+      info:
+        type: string
+      name:
+        type: string
+      "no":
+        type: integer
+      updated_at:
+        type: string
+      updated_by:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.DULBase:
+    properties:
+      category:
+        example: hems
+        type: string
+      id:
+        example: 0197f3b2-c4d8-4b12-a1f9-c1de23456789
+        type: string
+      name:
+        example: Halim Base
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.DULBaseRef:
+    properties:
+      category:
+        type: string
+      id:
+        type: string
+      name:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.DULCreateAttributes:
+    properties:
+      base_id:
+        example: 019e3ec1-94f6-7b6b-9cc5-1b5d05f46d74
+        type: string
+      date:
+        example: "2026-05-25"
+        type: string
+      file_uuid:
+        items:
+          type: string
+        type: array
+      info:
+        type: string
+      name:
+        maxLength: 128
+        type: string
+    required:
+    - base_id
+    - date
+    - name
+    type: object
+  wucher_internal_transport_http_dto.DULCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.DULCreateAttributes'
+      type:
+        enum:
+        - dul_create
+        - dul
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.DULCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.DULCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.DULDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.DULGroup'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          records_filtered:
+            example: 120
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+          total:
+            example: 120
+            type: integer
+          total_bases:
+            example: 8
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.DULDeleteResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              deleted:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: dul_delete
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.DULGroup:
+    properties:
+      base:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.DULBaseRef'
+      duls:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.DULResource'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto.DULImage:
+    properties:
+      download_url:
+        type: string
+      original_size_bytes:
+        type: integer
+      thumbnail_download_url:
+        type: string
+      uuid:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.DULListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.DULGroup'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+          total_bases:
+            example: 8
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.DULResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.DULAttributes'
+      id:
+        type: string
+      type:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.DULResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.DULResource'
+    type: object
+  wucher_internal_transport_http_dto.DULUpdateAttributes:
+    properties:
+      base_id:
+        type: string
+      date:
+        example: "2026-05-25"
+        type: string
+      file_uuid:
+        items:
+          type: string
+        type: array
+      info:
+        type: string
+      name:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.DULUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.DULUpdateAttributes'
+      type:
+        enum:
+        - dul_update
+        - dul
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.DULUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.DULUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.DoctorProfileAttributes:
+    properties:
+      is_chief_physician:
+        type: boolean
+      location:
+        maxLength: 255
+        type: string
+      note:
+        type: string
+      postcode:
+        maxLength: 32
+        type: string
+      short_name:
+        maxLength: 120
+        type: string
+      specialization:
+        maxLength: 120
+        type: string
+      street_line:
+        maxLength: 255
+        type: string
+      sub_specialization:
+        maxLength: 120
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.DoctorProfileUpdateAttributes:
+    properties:
+      is_chief_physician:
+        type: boolean
+      location:
+        maxLength: 255
+        type: string
+      note:
+        type: string
+      postcode:
+        maxLength: 32
+        type: string
+      short_name:
+        maxLength: 120
+        type: string
+      specialization:
+        maxLength: 120
+        type: string
+      street_line:
+        maxLength: 255
+        type: string
+      sub_specialization:
+        maxLength: 120
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.EmailOTPSendAttributes:
+    properties:
+      challenge_token:
+        example: kP8k2...
+        type: string
+    required:
+    - challenge_token
+    type: object
+  wucher_internal_transport_http_dto.EmailOTPSendData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.EmailOTPSendAttributes'
+      type:
+        example: auth_email_otp_send
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.EmailOTPSendRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.EmailOTPSendData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.EmailOTPSendResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              sent:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: auth_email_otp_send
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.EmailOTPVerifyAttributes:
+    properties:
+      challenge_token:
+        example: kP8k2...
+        type: string
+      code:
+        example: "123456"
+        type: string
+    required:
+    - challenge_token
+    - code
+    type: object
+  wucher_internal_transport_http_dto.EmailOTPVerifyData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.EmailOTPVerifyAttributes'
+      type:
+        example: auth_email_otp_verify
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.EmailOTPVerifyRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.EmailOTPVerifyData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.EmailOTPVerifyResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              requires_totp_setup:
+                example: true
+                type: boolean
+              verified:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: auth_email_otp_verify
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.ErrorResponse:
+    properties:
+      errors:
+        items:
+          properties:
+            detail:
+              example: email is required
+              type: string
+            source:
+              properties:
+                pointer:
+                  example: /data/attributes/email
+                  type: string
+              type: object
+            status:
+              example: "422"
+              type: string
+            title:
+              example: Validation error
+              type: string
+          type: object
+        type: array
+    type: object
+  wucher_internal_transport_http_dto.ExchangeAttributes:
+    properties:
+      access_token:
+        example: eyJ0eXAiOiJKV1Qi...
+        type: string
+      id_token:
+        example: eyJ0eXAiOiJKV1Qi...
+        type: string
+      id_token_claims:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ExchangeIDTokenClaims'
+    required:
+    - access_token
+    - id_token
+    type: object
+  wucher_internal_transport_http_dto.ExchangeData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ExchangeAttributes'
+      type:
+        example: auth_exchange
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ExchangeIDTokenClaims:
+    properties:
+      aud:
+        example: 12345678-1234-1234-1234-123456789012
+        type: string
+      email:
+        example: andrio@mybit-innovation.com
+        type: string
+      exp:
+        example: 1715603600
+        type: integer
+      iat:
+        example: 1715600000
+        type: integer
+      iss:
+        example: https://login.microsoftonline.com/abc-tenant-id/v2.0
+        type: string
+      name:
+        example: Andrio Effendi
+        type: string
+      nbf:
+        example: 1715600000
+        type: integer
+      oid:
+        example: 00000000-0000-0000-1234-567890abcdef
+        type: string
+      preferred_username:
+        example: andrio@mybit-innovation.com
+        type: string
+      sub:
+        example: AbCdEfGhIjKlMnOpQrStUvWxYz
+        type: string
+      tid:
+        example: abc-tenant-id
+        type: string
+      ver:
+        example: "2.0"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.ExchangeRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ExchangeData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.FMReportAirframeValues:
+    properties:
+      cycles:
+        example: 320
+        type: number
+      hours:
+        example: 1523.5
+        type: number
+    type: object
+  wucher_internal_transport_http_dto.FMReportAttachmentItem:
+    properties:
+      download_url:
+        type: string
+      file_id:
+        type: string
+      id:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.FMReportAttachments:
+    properties:
+      additional_fm_report:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportAttachmentItem'
+        type: array
+      briefing:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportAttachmentItem'
+        type: array
+      ofp:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportAttachmentItem'
+        type: array
+      weight_balance:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportAttachmentItem'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto.FMReportAttributes:
+    properties:
+      after_flight_inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResource'
+      completed_at:
+        example: "2026-04-20T10:15:00Z"
+        type: string
+      completed_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      created_at:
+        example: "2026-04-20T08:00:00Z"
+        type: string
+      engine1_gpc_n1:
+        example: GPC/N1 63.2
+        type: string
+      engine1_ptc_n2:
+        example: PTC/N2 61.8
+        type: string
+      engine2_gpc_n1:
+        example: GPC/N1 62.9
+        type: string
+      engine2_ptc_n2:
+        example: PTC/N2 61.5
+        type: string
+      fleet_status:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResource'
+      flight:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightResource'
+      flight_id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      flight_inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FlightInspectionResource'
+      flight_inspection_id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      fm_report_attachments:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportAttachments'
+      helicopter_identifier:
+        example: OE-TEST
+        type: string
+      helicopter_usage:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResource'
+      id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      missions:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionResource'
+        type: array
+      pilot_name:
+        example: John Doe
+        type: string
+      report_code:
+        example: EC-135-1
+        type: string
+      takeover_files:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverFileResource'
+        type: array
+      takeover_id:
+        example: 019e8713-aa19-7fb7-a510-a0332dc69697
+        type: string
+      updated_at:
+        example: "2026-04-20T08:00:00Z"
+        type: string
+      usage_breakdown:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportUsageBreakdown'
+    type: object
+  wucher_internal_transport_http_dto.FMReportCountersValues:
+    properties:
+      flight_reports:
+        example: 80
+        type: number
+      hook_releases:
+        example: 10
+        type: number
+      landings:
+        example: 120
+        type: number
+      rotor_brake_cycles:
+        example: 8
+        type: number
+    type: object
+  wucher_internal_transport_http_dto.FMReportEngineValues:
+    properties:
+      ccc:
+        example: 44
+        type: number
+      gpc_ng_n1:
+        example: 63.2
+        type: number
+      hours:
+        example: 1523.5
+        type: number
+      ptc_nf_n2:
+        example: 61.8
+        type: number
+    type: object
+  wucher_internal_transport_http_dto.FMReportListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 1
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.FMReportResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportAttributes'
+      id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      type:
+        example: fm_report
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.FMReportResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportResource'
+    type: object
+  wucher_internal_transport_http_dto.FMReportUsageBreakdown:
+    properties:
+      prev:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportUsageSnapshot'
+      today:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportUsageSnapshot'
+      total:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportUsageSnapshot'
+    type: object
+  wucher_internal_transport_http_dto.FMReportUsageSnapshot:
+    properties:
+      airframe:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportAirframeValues'
+      counters:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportCountersValues'
+      engine_1:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportEngineValues'
+      engine_2:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportEngineValues'
+    type: object
+  wucher_internal_transport_http_dto.FacilityAttributes:
+    properties:
+      category:
+        example: heslo-rope-label
+        type: string
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      electric:
+        example: available
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      length:
+        example: 10m
+        type: string
+      name:
+        example: Fuel Truck Rope Label
+        type: string
+      note:
+        example: Dry lease fuel truck
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      type:
+        example: Sling
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      weight:
+        example: 10kg
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.FacilityCreateAttributes:
+    properties:
+      category:
+        example: heslo-rope-label
+        type: string
+      electric:
+        example: available
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      length:
+        example: 10m
+        type: string
+      name:
+        example: Fuel Truck Rope Label
+        type: string
+      note:
+        example: Dry lease fuel truck
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      type:
+        example: Sling
+        type: string
+      weight:
+        example: 10kg
+        type: string
+    required:
+    - category
+    - name
+    type: object
+  wucher_internal_transport_http_dto.FacilityCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityCreateAttributes'
+      type:
+        enum:
+        - facility_create
+        - facility
+        example: facility_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.FacilityCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.FacilityDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.FacilityDeleteResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              deleted:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: facility_delete
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.FacilityListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.FacilityResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: facility
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.FacilityResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityResource'
+    type: object
+  wucher_internal_transport_http_dto.FacilityUpdateAttributes:
+    properties:
+      category:
+        example: heslo-rope-label
+        type: string
+      electric:
+        example: available
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      length:
+        example: 10m
+        type: string
+      name:
+        example: Fuel Truck Rope Label
+        type: string
+      note:
+        example: Dry lease fuel truck
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      type:
+        example: Sling
+        type: string
+      weight:
+        example: 10kg
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.FacilityUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - facility_update
+        - facility
+        example: facility_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.FacilityUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.FederalStateAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      land_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      land_iso_code:
+        example: DE
+        type: string
+      land_name:
+        example: Germany
+        type: string
+      name:
+        example: Bayern
+        type: string
+      note:
+        example: Central region
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.FederalStateCreateAttributes:
+    properties:
+      is_active:
+        example: true
+        type: boolean
+      land_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: Bayern
+        type: string
+      note:
+        example: Central region
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+    required:
+    - land_id
+    - name
+    type: object
+  wucher_internal_transport_http_dto.FederalStateCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateCreateAttributes'
+      type:
+        enum:
+        - federal_state_create
+        - federal_state
+        example: federal_state_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.FederalStateCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.FederalStateDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.FederalStateDeleteResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              deleted:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: federal_state_delete
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.FederalStateListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.FederalStateResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: federal_state
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.FederalStateResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateResource'
+    type: object
+  wucher_internal_transport_http_dto.FederalStateUpdateAttributes:
+    properties:
+      is_active:
+        example: true
+        type: boolean
+      land_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: Bayern
+        type: string
+      note:
+        example: Central region
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto.FederalStateUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - federal_state_update
+        - federal_state
+        example: federal_state_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.FederalStateUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.FlightAssistantProfileAttributes:
+    properties:
+      location:
+        maxLength: 255
+        type: string
+      note:
+        type: string
+      postcode:
+        maxLength: 32
+        type: string
+      short_name:
+        maxLength: 120
+        type: string
+      street_line:
+        maxLength: 255
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.FlightAssistantProfileUpdateAttributes:
+    properties:
+      location:
+        maxLength: 255
+        type: string
+      note:
+        type: string
+      postcode:
+        maxLength: 32
+        type: string
+      short_name:
+        maxLength: 120
+        type: string
+      street_line:
+        maxLength: 255
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.FlightInspectionAttributes:
+    properties:
+      created_at:
+        example: "2026-04-09T05:00:00Z"
+        type: string
+      created_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      inspection_date:
+        example: "2026-04-09"
+        type: string
+      status:
+        example: Draft
+        type: string
+      updated_at:
+        example: "2026-04-09T05:00:00Z"
+        type: string
+      updated_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.FlightInspectionCreateAttributes:
+    properties:
+      inspection_date:
+        example: "2026-04-09"
+        type: string
+    required:
+    - inspection_date
+    type: object
+  wucher_internal_transport_http_dto.FlightInspectionCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FlightInspectionCreateAttributes'
+      type:
+        enum:
+        - flight_inspection_create
+        - flight_inspection
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.FlightInspectionCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FlightInspectionCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.FlightInspectionListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FlightInspectionResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 1
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.FlightInspectionResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FlightInspectionAttributes'
+      id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      type:
+        example: flight_inspection
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.FlightInspectionResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FlightInspectionResource'
+    type: object
+  wucher_internal_transport_http_dto.FlightInspectionUpdateAttributes:
+    properties:
+      inspection_date:
+        example: "2026-04-09"
+        type: string
+      status:
+        example: InProgress
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.FlightInspectionUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FlightInspectionUpdateAttributes'
+      id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      type:
+        enum:
+        - flight_inspection_update
+        - flight_inspection
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.FlightInspectionUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.FlightInspectionUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ForcesPresentAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      name:
+        example: Firefighter Team A
+        type: string
+      note:
+        example: On-site responders
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.ForcesPresentCreateAttributes:
+    properties:
+      is_active:
+        example: true
+        type: boolean
+      name:
+        example: Firefighter Team A
+        type: string
+      note:
+        example: On-site responders
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+    required:
+    - name
+    type: object
+  wucher_internal_transport_http_dto.ForcesPresentCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentCreateAttributes'
+      type:
+        enum:
+        - forces_present_create
+        - forces_present
+        example: forces_present_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ForcesPresentCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ForcesPresentDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.ForcesPresentListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.ForcesPresentResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: forces_present
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.ForcesPresentResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentResource'
+    type: object
+  wucher_internal_transport_http_dto.ForcesPresentUpdateAttributes:
+    properties:
+      is_active:
+        example: true
+        type: boolean
+      name:
+        example: Firefighter Team A
+        type: string
+      note:
+        example: On-site responders
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto.ForcesPresentUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - forces_present_update
+        - forces_present
+        example: forces_present_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ForcesPresentUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ForgotPasswordAttributes:
+    properties:
+      email:
+        example: user@example.com
+        type: string
+    required:
+    - email
+    type: object
+  wucher_internal_transport_http_dto.ForgotPasswordData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ForgotPasswordAttributes'
+      type:
+        example: auth_forgot_password
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ForgotPasswordRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ForgotPasswordData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ForgotSecurityPINAttributes:
+    properties:
+      email:
+        example: user@example.com
+        type: string
+    required:
+    - email
+    type: object
+  wucher_internal_transport_http_dto.ForgotSecurityPINData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ForgotSecurityPINAttributes'
+      type:
+        example: auth_forgot_pin
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ForgotSecurityPINRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ForgotSecurityPINData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.GenericDeleteAttributes:
+    properties:
+      deleted:
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto.GenericDeleteResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponseData'
+    type: object
+  wucher_internal_transport_http_dto.GenericDeleteResponseData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteAttributes'
+      type:
+        example: delete_result
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      date:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      hems_operation_category:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryRef'
+      hems_operation_category_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      mission:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationMissionRef'
+      mission_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      operational_data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationOperationalDataRef'
+      operational_data_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCategoryAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: Firefighting
+        type: string
+      type:
+        example: first
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCategoryCreateAttributes:
+    properties:
+      name:
+        example: Firefighting
+        type: string
+      type:
+        enum:
+        - first
+        - secondary
+        - misuse
+        example: first
+        type: string
+    required:
+    - name
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCategoryCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryCreateAttributes'
+      type:
+        enum:
+        - hems_operation_category_create
+        - hems_operation_category
+        example: hems_operation_category_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCategoryCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCategoryDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCategoryListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCategoryRef:
+    properties:
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: Firefighting
+        type: string
+      type:
+        example: first
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCategoryResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: hems_operation_category
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCategoryResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResource'
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateAttributes:
+    properties:
+      name:
+        example: Firefighting
+        type: string
+      type:
+        enum:
+        - first
+        - secondary
+        - misuse
+        example: first
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateAttributes'
+      type:
+        enum:
+        - hems_operation_category_update
+        - hems_operation_category
+        example: hems_operation_category_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCreateAttributes:
+    properties:
+      date:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      hems_operation_category_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      mission_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      operational_data_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - date
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCreateAttributes'
+      type:
+        enum:
+        - hems_operation_create
+        - hems_operation
+        example: hems_operation_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationMissionRef:
+    properties:
+      flight_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: HEMS
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationOperationalDataRef:
+    properties:
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: hems_operation
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationResource'
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationUpdateAttributes:
+    properties:
+      date:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      hems_operation_category_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      mission_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      operational_data_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationUpdateAttributes'
+      type:
+        enum:
+        - hems_operation_update
+        - hems_operation
+        example: hems_operation_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationalDataAttributes:
+    properties:
+      additional_info:
+        example: Additional information about the operational data
+        type: string
+      altitude:
+        example: 5.2
+        type: number
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      darkness:
+        type: boolean
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      false_information:
+        type: boolean
+      files:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataFileAttributes'
+        type: array
+      fog:
+        type: boolean
+      force_present_ids:
+        example:
+        - 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        items:
+          type: string
+        type: array
+      instrument_flight:
+        type: boolean
+      land_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      landing_site_search:
+        type: boolean
+      location:
+        example: 123 Main St, Anytown, USA
+        type: string
+      mountain_use:
+        type: boolean
+      nfo_search:
+        type: boolean
+      night_flight:
+        type: boolean
+      notes:
+        example: Notes about the operational data
+        type: string
+      postcode:
+        example: "12345"
+        type: string
+      precipitation:
+        type: boolean
+      rope_recovery:
+        type: boolean
+      state_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      temperature:
+        example: 23.5
+        type: number
+      terrain_index:
+        example: Only helicopter landing
+        type: string
+      time:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      vocation_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      wind:
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationalDataCreateAttributes:
+    properties:
+      additional_info:
+        example: Additional information about the operational data
+        type: string
+      altitude:
+        example: 5.2
+        type: number
+      darkness:
+        type: boolean
+      false_information:
+        type: boolean
+      file_attachment_ids:
+        example:
+        - 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        items:
+          type: string
+        type: array
+      fog:
+        type: boolean
+      force_present_ids:
+        example:
+        - 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        items:
+          type: string
+        type: array
+      instrument_flight:
+        type: boolean
+      land_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      landing_site_search:
+        type: boolean
+      location:
+        example: 123 Main St, Anytown, USA
+        type: string
+      mountain_use:
+        type: boolean
+      nfo_search:
+        type: boolean
+      night_flight:
+        type: boolean
+      notes:
+        example: Notes about the operational data
+        type: string
+      postcode:
+        example: "12345"
+        type: string
+      precipitation:
+        type: boolean
+      rope_recovery:
+        type: boolean
+      state_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      temperature:
+        example: 23.5
+        type: number
+      terrain_index:
+        example: Only helicopter landing
+        type: string
+      time:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      vocation_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      wind:
+        type: boolean
+    required:
+    - location
+    - time
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationalDataCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataCreateAttributes'
+      type:
+        enum:
+        - hems_operational_data_create
+        - hems_operational_data
+        example: hems_operational_data_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationalDataCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationalDataDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationalDataFileAttributes:
+    properties:
+      file_attachment_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationalDataListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationalDataResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: hems_operational_data
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationalDataResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResource'
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationalDataUpdateAttributes:
+    properties:
+      additional_info:
+        example: Additional information about the operational data
+        type: string
+      altitude:
+        example: 5.2
+        type: number
+      darkness:
+        type: boolean
+      false_information:
+        type: boolean
+      file_attachment_ids:
+        items:
+          type: string
+        type: array
+      fog:
+        type: boolean
+      force_present_ids:
+        items:
+          type: string
+        type: array
+      instrument_flight:
+        type: boolean
+      land_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      landing_site_search:
+        type: boolean
+      location:
+        example: 123 Main St, Anytown, USA
+        type: string
+      mountain_use:
+        type: boolean
+      nfo_search:
+        type: boolean
+      night_flight:
+        type: boolean
+      notes:
+        example: Notes about the operational data
+        type: string
+      postcode:
+        example: "12345"
+        type: string
+      precipitation:
+        type: boolean
+      rope_recovery:
+        type: boolean
+      state_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      temperature:
+        example: 23.5
+        type: number
+      terrain_index:
+        example: Only helicopter landing
+        type: string
+      time:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      vocation_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      wind:
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationalDataUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataUpdateAttributes'
+      type:
+        enum:
+        - hems_operational_data_update
+        - hems_operational_data
+        example: hems_operational_data_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HEMSOperationalDataUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.HealthInsuranceCompanyAttributes:
+    properties:
+      address:
+        example: Main Street 10
+        type: string
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      email:
+        example: info@abc-insurance.local
+        type: string
+      federal_state:
+        example: Bayern
+        type: string
+      federal_state_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      land_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      land_iso_code:
+        example: DE
+        type: string
+      land_name:
+        example: Germany
+        type: string
+      mobile_number:
+        example: "+4912345678"
+        type: string
+      name:
+        example: ABC Insurance
+        type: string
+      note:
+        example: Preferred insurance provider
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      state:
+        example: Berlin
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateAttributes:
+    properties:
+      address:
+        example: Main Street 10
+        type: string
+      email:
+        example: info@abc-insurance.local
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      land_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      mobile_number:
+        example: "+4912345678"
+        type: string
+      name:
+        example: ABC Insurance
+        type: string
+      note:
+        example: Preferred insurance provider
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      state:
+        example: Berlin
+        type: string
+    required:
+    - name
+    type: object
+  wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateAttributes'
+      type:
+        enum:
+        - health_insurance_company_create
+        - health_insurance_company
+        example: health_insurance_company_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.HealthInsuranceCompanyDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.HealthInsuranceCompanyListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.HealthInsuranceCompanyResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: health_insurance_company
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HealthInsuranceCompanyResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResource'
+    type: object
+  wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateAttributes:
+    properties:
+      address:
+        example: Main Street 10
+        type: string
+      email:
+        example: info@abc-insurance.local
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      land_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      mobile_number:
+        example: "+4912345678"
+        type: string
+      name:
+        example: ABC Insurance
+        type: string
+      note:
+        example: Preferred insurance provider
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      state:
+        example: Berlin
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - health_insurance_company_update
+        - health_insurance_company
+        example: health_insurance_company_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.HelicopterUsageAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      helicopter_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      total_airframe_cycles:
+        example: 320
+        type: number
+      total_airframe_hours:
+        example: 1523.5
+        type: number
+      total_engine_1_ccc:
+        example: 44
+        type: number
+      total_engine_1_gpc_ng_n1:
+        example: 98.7
+        type: number
+      total_engine_1_hours:
+        example: 1523.5
+        type: number
+      total_engine_1_ptc_nf_n2:
+        example: 97.2
+        type: number
+      total_engine_2_ccc:
+        example: 44
+        type: number
+      total_engine_2_gpc_ng_n1:
+        example: 98.7
+        type: number
+      total_engine_2_hours:
+        example: 1523.5
+        type: number
+      total_engine_2_ptc_nf_n2:
+        example: 97.2
+        type: number
+      total_flight_report:
+        example: 80
+        type: number
+      total_hook_release:
+        example: 10
+        type: number
+      total_landing:
+        example: 120
+        type: number
+      total_rotor_brake_cycle:
+        example: 8
+        type: number
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HelicopterUsageCreateAttributes:
+    properties:
+      helicopter_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      total_airframe_cycles:
+        example: 320
+        type: number
+      total_airframe_hours:
+        example: 1523.5
+        type: number
+      total_engine_1_ccc:
+        example: 44
+        type: number
+      total_engine_1_gpc_ng_n1:
+        example: 98.7
+        type: number
+      total_engine_1_hours:
+        example: 1523.5
+        type: number
+      total_engine_1_ptc_nf_n2:
+        example: 97.2
+        type: number
+      total_engine_2_ccc:
+        example: 44
+        type: number
+      total_engine_2_gpc_ng_n1:
+        example: 98.7
+        type: number
+      total_engine_2_hours:
+        example: 1523.5
+        type: number
+      total_engine_2_ptc_nf_n2:
+        example: 97.2
+        type: number
+      total_flight_report:
+        example: 80
+        type: number
+      total_hook_release:
+        example: 10
+        type: number
+      total_landing:
+        example: 120
+        type: number
+      total_rotor_brake_cycle:
+        example: 8
+        type: number
+    required:
+    - helicopter_id
+    type: object
+  wucher_internal_transport_http_dto.HelicopterUsageCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageCreateAttributes'
+      type:
+        enum:
+        - helicopter_usage_create
+        - helicopter_usage
+        example: helicopter_usage_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HelicopterUsageCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.HelicopterUsageListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.HelicopterUsageResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: helicopter_usage
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HelicopterUsageResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResource'
+    type: object
+  wucher_internal_transport_http_dto.HelicopterUsageUpdateAttributes:
+    properties:
+      helicopter_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      total_airframe_cycles:
+        example: 320
+        type: number
+      total_airframe_hours:
+        example: 1523.5
+        type: number
+      total_engine_1_ccc:
+        example: 44
+        type: number
+      total_engine_1_gpc_ng_n1:
+        example: 98.7
+        type: number
+      total_engine_1_hours:
+        example: 1523.5
+        type: number
+      total_engine_1_ptc_nf_n2:
+        example: 97.2
+        type: number
+      total_engine_2_ccc:
+        example: 44
+        type: number
+      total_engine_2_gpc_ng_n1:
+        example: 98.7
+        type: number
+      total_engine_2_hours:
+        example: 1523.5
+        type: number
+      total_engine_2_ptc_nf_n2:
+        example: 97.2
+        type: number
+      total_flight_report:
+        example: 80
+        type: number
+      total_hook_release:
+        example: 10
+        type: number
+      total_landing:
+        example: 120
+        type: number
+      total_rotor_brake_cycle:
+        example: 8
+        type: number
+    type: object
+  wucher_internal_transport_http_dto.HelicopterUsageUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - helicopter_usage_update
+        - helicopter_usage
+        example: helicopter_usage_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HelicopterUsageUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.HospitalAttributes:
+    properties:
+      address:
+        example: Jl. Merdeka No. 10
+        type: string
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      email:
+        example: info@hospital.local
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      landline_number:
+        example: "0211234567"
+        type: string
+      mobile_number:
+        example: "08123456789"
+        type: string
+      name:
+        example: RSUD Kota
+        type: string
+      note:
+        example: Nearest trauma center
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HospitalCreateAttributes:
+    properties:
+      address:
+        example: Jl. Merdeka No. 10
+        type: string
+      email:
+        example: info@hospital.local
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      landline_number:
+        example: "0211234567"
+        type: string
+      mobile_number:
+        example: "08123456789"
+        type: string
+      name:
+        example: RSUD Kota
+        type: string
+      note:
+        example: Nearest trauma center
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+    required:
+    - name
+    type: object
+  wucher_internal_transport_http_dto.HospitalCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalCreateAttributes'
+      type:
+        enum:
+        - hospital_create
+        - hospital
+        example: hospital_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HospitalCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.HospitalDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.HospitalListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.HospitalResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: hospital
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.HospitalResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalResource'
+    type: object
+  wucher_internal_transport_http_dto.HospitalUpdateAttributes:
+    properties:
+      address:
+        example: Jl. Merdeka No. 10
+        type: string
+      email:
+        example: info@hospital.local
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      landline_number:
+        example: "0211234567"
+        type: string
+      mobile_number:
+        example: "08123456789"
+        type: string
+      name:
+        example: RSUD Kota
+        type: string
+      note:
+        example: Nearest trauma center
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto.HospitalUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - hospital_update
+        - hospital
+        example: hospital_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.HospitalUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ICAOAttributes:
+    properties:
+      address:
+        example: Muehlenstrasse 1
+        type: string
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      email:
+        example: ops@example.local
+        type: string
+      federal_state:
+        example: Bayern
+        type: string
+      federal_state_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      icao_code:
+        example: EDDB
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      land_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      land_iso_code:
+        example: DE
+        type: string
+      land_name:
+        example: Germany
+        type: string
+      landline_number:
+        example: "030123456"
+        type: string
+      mobile_number:
+        example: "0170123456"
+        type: string
+      name:
+        example: Berlin Base
+        type: string
+      note:
+        example: Night operations supported
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.ICAOCreateAttributes:
+    properties:
+      address:
+        example: Muehlenstrasse 1
+        type: string
+      email:
+        example: ops@example.local
+        type: string
+      federal_state_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      icao_code:
+        example: EDDB
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      land_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      landline_number:
+        example: "030123456"
+        type: string
+      mobile_number:
+        example: "0170123456"
+        type: string
+      name:
+        example: Berlin Base
+        type: string
+      note:
+        example: Night operations supported
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+    required:
+    - icao_code
+    type: object
+  wucher_internal_transport_http_dto.ICAOCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOCreateAttributes'
+      type:
+        enum:
+        - icao_create
+        - icao
+        example: icao_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ICAOCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ICAODataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.ICAOListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.ICAOResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: icao
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.ICAOResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOResource'
+    type: object
+  wucher_internal_transport_http_dto.ICAOUpdateAttributes:
+    properties:
+      address:
+        example: Muehlenstrasse 1
+        type: string
+      email:
+        example: ops@example.local
+        type: string
+      federal_state_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      icao_code:
+        example: EDDB
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      land_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      landline_number:
+        example: "030123456"
+        type: string
+      mobile_number:
+        example: "0170123456"
+        type: string
+      name:
+        example: Berlin Base
+        type: string
+      note:
+        example: Night operations supported
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto.ICAOUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - icao_update
+        - icao
+        example: icao_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ICAOUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      federal_state:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataFederalState'
+      federal_state_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      health_insurance_companies_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      health_insurance_company:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataHealthInsuranceCompany'
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataCreateAttributes:
+    properties:
+      federal_state_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      health_insurance_companies_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - federal_state_id
+    - health_insurance_companies_id
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataCreateAttributes'
+      type:
+        enum:
+        - insurance_patient_data_create
+        - insurance_patient_data
+        example: insurance_patient_data_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataFederalState:
+    properties:
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: Bayern
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataHealthInsuranceCompany:
+    properties:
+      address:
+        example: Main Street 10
+        type: string
+      email:
+        example: info@abc-insurance.local
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      mobile_number:
+        example: "+4912345678"
+        type: string
+      name:
+        example: ABC Insurance
+        type: string
+      state:
+        example: Berlin
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: insurance_patient_data
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResource'
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataUpdateAttributes:
+    properties:
+      federal_state_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      health_insurance_companies_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - insurance_patient_data_update
+        - insurance_patient_data
+        example: insurance_patient_data_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.InsurancePatientDataUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.InviteAttributes:
+    properties:
+      email:
+        example: user@example.com
+        type: string
+      first_name:
+        example: John
+        type: string
+      last_name:
+        example: Doe
+        type: string
+      mobile_phone:
+        example: "+628123456789"
+        type: string
+      role_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      role_ids:
+        example:
+        - '["018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"'
+        - '"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e"]'
+        items:
+          type: string
+        type: array
+      username:
+        example: john.doe
+        maxLength: 100
+        minLength: 3
+        type: string
+    required:
+    - email
+    - first_name
+    - last_name
+    - role_id
+    - username
+    type: object
+  wucher_internal_transport_http_dto.InviteData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.InviteAttributes'
+      type:
+        example: auth_invite
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.InviteRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.InviteData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.LandAttributes:
+    properties:
+      bmd_export_id:
+        example: DE001
+        type: string
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      federal_state_list:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.LandFederalStateDTO'
+        type: array
+      federal_state_total:
+        example: 2
+        type: integer
+      is_active:
+        example: true
+        type: boolean
+      iso_code:
+        example: DE
+        type: string
+      name:
+        example: Germany
+        type: string
+      note:
+        example: Central Europe
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.LandCreateAttributes:
+    properties:
+      bmd_export_id:
+        example: DE001
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      iso_code:
+        example: DE
+        type: string
+      name:
+        example: Germany
+        type: string
+      note:
+        example: Central Europe
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+    required:
+    - name
+    type: object
+  wucher_internal_transport_http_dto.LandCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.LandCreateAttributes'
+      type:
+        enum:
+        - land_create
+        - land
+        example: land_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.LandCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.LandCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.LandDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.LandResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.LandFederalStateDTO:
+    properties:
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: Bayern
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.LandListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.LandResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.LandResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.LandAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: land
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.LandResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.LandResource'
+    type: object
+  wucher_internal_transport_http_dto.LandUpdateAttributes:
+    properties:
+      bmd_export_id:
+        example: DE001
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      iso_code:
+        example: DE
+        type: string
+      name:
+        example: Germany
+        type: string
+      note:
+        example: Central Europe
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto.LandUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.LandUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - land_update
+        - land
+        example: land_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.LandUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.LandUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.LoginAttributes:
+    properties:
+      email:
+        example: user@example.com
+        type: string
+      password:
+        example: StrongP@ssw0rd
+        type: string
+    required:
+    - email
+    - password
+    type: object
+  wucher_internal_transport_http_dto.LoginData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.LoginAttributes'
+      type:
+        example: auth_login
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.LoginEmailOTPRequiredResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              challenge_token:
+                example: kP8k2...
+                type: string
+              linked_sso:
+                example: false
+                type: boolean
+              max_resend_per_hour:
+                example: 5
+                type: integer
+              pin_configured:
+                example: false
+                type: boolean
+              requires_email_otp:
+                example: true
+                type: boolean
+              requires_totp_setup:
+                example: true
+                type: boolean
+              resend_cooldown_seconds:
+                example: 60
+                type: integer
+              webauthn_configured:
+                example: false
+                type: boolean
+            type: object
+          type:
+            example: auth_email_otp_required
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.LoginRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.LoginData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.LoginTOTPRequiredResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              challenge_token:
+                example: kP8k2...
+                type: string
+              email_otp_challenge_token:
+                example: qA9j1...
+                type: string
+              email_otp_enabled:
+                example: false
+                type: boolean
+              email_otp_max_resend_per_hour:
+                example: 5
+                type: integer
+              email_otp_resend_cooldown_seconds:
+                example: 60
+                type: integer
+              linked_sso:
+                example: false
+                type: boolean
+              pin_configured:
+                example: false
+                type: boolean
+              requires_totp:
+                example: true
+                type: boolean
+              totp_enabled:
+                example: true
+                type: boolean
+              webauthn_configured:
+                example: false
+                type: boolean
+            type: object
+          type:
+            example: auth_totp_required
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.MedicineAttributes:
+    properties:
+      column:
+        example: 1
+        type: integer
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      medicine_group:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupResource'
+      medicine_group_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      motor_reaction:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionResource'
+      motor_reaction_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      motor_reaction_ids:
+        example:
+        - 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        items:
+          type: string
+        type: array
+      motor_reactions:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionResource'
+        type: array
+      name:
+        example: Paracetamol
+        type: string
+      note:
+        example: Main stock medicine
+        type: string
+      pack:
+        example: 500mg
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      unit:
+        example: tablet
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.MedicineCreateAttributes:
+    properties:
+      column:
+        example: 1
+        type: integer
+      is_active:
+        example: true
+        type: boolean
+      medicine_group_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      motor_reaction_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      motor_reaction_ids:
+        example:
+        - 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        items:
+          type: string
+        type: array
+      name:
+        example: Paracetamol
+        type: string
+      note:
+        example: Main stock medicine
+        type: string
+      pack:
+        example: 500mg
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      unit:
+        example: tablet
+        maxLength: 50
+        type: string
+    required:
+    - name
+    type: object
+  wucher_internal_transport_http_dto.MedicineCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineCreateAttributes'
+      type:
+        enum:
+        - medicine_create
+        - medicine
+        example: medicine_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.MedicineCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.MedicineDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.MedicineGroupAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: Spritze
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.MedicineGroupCreateAttributes:
+    properties:
+      name:
+        example: Spritze
+        type: string
+    required:
+    - name
+    type: object
+  wucher_internal_transport_http_dto.MedicineGroupCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupCreateAttributes'
+      type:
+        enum:
+        - medicine_group_create
+        - medicine_group
+        example: medicine_group_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.MedicineGroupCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.MedicineGroupDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.MedicineGroupListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.MedicineGroupResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: medicine_group
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.MedicineGroupResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupResource'
+    type: object
+  wucher_internal_transport_http_dto.MedicineGroupUpdateAttributes:
+    properties:
+      name:
+        example: Spritze
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.MedicineGroupUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - medicine_group_update
+        - medicine_group
+        example: medicine_group_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.MedicineGroupUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.MedicineListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.MedicineResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: medicine
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.MedicineResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineResource'
+    type: object
+  wucher_internal_transport_http_dto.MedicineUpdateAttributes:
+    properties:
+      column:
+        example: 1
+        type: integer
+      is_active:
+        example: true
+        type: boolean
+      medicine_group_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      motor_reaction_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      motor_reaction_ids:
+        example:
+        - 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        items:
+          type: string
+        type: array
+      name:
+        example: Paracetamol
+        type: string
+      note:
+        example: Main stock medicine
+        type: string
+      pack:
+        example: 500mg
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      unit:
+        example: tablet
+        maxLength: 50
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.MedicineUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - medicine_update
+        - medicine
+        example: medicine_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.MedicineUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.MicrosoftCallbackResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              email:
+                example: user@example.com
+                type: string
+              provider:
+                example: microsoft
+                type: string
+              provider_subject:
+                example: 00000000-0000-0000-0000-000000000000
+                type: string
+            type: object
+          id:
+            example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+            type: string
+          type:
+            example: auth_identity
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.MicrosoftLoginResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              redirect_url:
+                example: https://login.microsoftonline.com/...
+                type: string
+              url:
+                example: https://login.microsoftonline.com/...
+                type: string
+            type: object
+          type:
+            example: auth_microsoft_url
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.MotorReactionAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: gezielt auf Schmerzreiz
+        type: string
+      score:
+        example: 5
+        type: integer
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.MotorReactionCreateAttributes:
+    properties:
+      name:
+        example: gezielt auf Schmerzreiz
+        type: string
+      score:
+        example: 5
+        type: integer
+    required:
+    - name
+    type: object
+  wucher_internal_transport_http_dto.MotorReactionCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionCreateAttributes'
+      type:
+        enum:
+        - motor_reaction_create
+        - motor_reaction
+        example: motor_reaction_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.MotorReactionCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.MotorReactionDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.MotorReactionListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.MotorReactionResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: motor_reaction
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.MotorReactionResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionResource'
+    type: object
+  wucher_internal_transport_http_dto.MotorReactionUpdateAttributes:
+    properties:
+      name:
+        example: gezielt auf Schmerzreiz
+        type: string
+      score:
+        example: 5
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto.MotorReactionUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - motor_reaction_update
+        - motor_reaction
+        example: motor_reaction_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.MotorReactionUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.OpcAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      note:
+        example: Primary operation control center
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      title:
+        example: Main OPC Base
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.OpcCreateAttributes:
+    properties:
+      is_active:
+        example: true
+        type: boolean
+      note:
+        example: Primary operation control center
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      title:
+        example: Main OPC Base
+        type: string
+    required:
+    - title
+    type: object
+  wucher_internal_transport_http_dto.OpcCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.OpcCreateAttributes'
+      type:
+        enum:
+        - opc_create
+        - opc
+        example: opc_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.OpcCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.OpcCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.OpcDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.OpcResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.OpcListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.OpcResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.OpcResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.OpcAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: opc
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.OpcResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.OpcResource'
+    type: object
+  wucher_internal_transport_http_dto.OpcUpdateAttributes:
+    properties:
+      is_active:
+        example: true
+        type: boolean
+      note:
+        example: Primary operation control center
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      title:
+        example: Main OPC Base
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.OpcUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.OpcUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - opc_update
+        - opc
+        example: opc_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.OpcUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.OpcUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.PatientDataAttributes:
+    properties:
+      age:
+        example: 35
+        type: integer
+      birth_date:
+        example: "1990-01-15"
+        type: string
+      co_insured:
+        example: false
+        type: boolean
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      email:
+        example: max.muster@example.com
+        type: string
+      family_name:
+        example: Muster
+        type: string
+      first_name:
+        example: Max
+        type: string
+      gender:
+        example: male
+        type: string
+      insurance_patient_data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataInsuranceDetail'
+      insurance_patient_data_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      opc:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataOPC'
+      opc_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      phone:
+        example: "+431234567"
+        type: string
+      street:
+        example: Hauptstraße 1
+        type: string
+      svnr:
+        example: "1234150190"
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.PatientDataCreateAttributes:
+    properties:
+      birth_date:
+        example: "1990-01-15"
+        type: string
+      co_insured:
+        example: false
+        type: boolean
+      email:
+        example: max.muster@example.com
+        type: string
+      family_name:
+        example: Muster
+        type: string
+      first_name:
+        example: Max
+        type: string
+      gender:
+        enum:
+        - male
+        - female
+        example: male
+        type: string
+      insurance_patient_data_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      opc_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      phone:
+        example: "+431234567"
+        type: string
+      street:
+        example: Hauptstraße 1
+        type: string
+      svnr:
+        example: "1234150190"
+        type: string
+    required:
+    - family_name
+    - first_name
+    - gender
+    type: object
+  wucher_internal_transport_http_dto.PatientDataCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataCreateAttributes'
+      type:
+        enum:
+        - patient_data_create
+        - patient_data
+        example: patient_data_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.PatientDataCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.PatientDataDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.PatientDataInsuranceDetail:
+    properties:
+      federal_state:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataFederalState'
+      federal_state_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      health_insurance_companies_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      health_insurance_company:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataHealthInsuranceCompany'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.PatientDataListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.PatientDataOPC:
+    properties:
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      title:
+        example: Primary OPC
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.PatientDataResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: patient_data
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.PatientDataResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataResource'
+    type: object
+  wucher_internal_transport_http_dto.PatientDataUpdateAttributes:
+    properties:
+      birth_date:
+        example: "1990-01-15"
+        type: string
+      co_insured:
+        example: false
+        type: boolean
+      email:
+        example: max.muster@example.com
+        type: string
+      family_name:
+        example: Muster
+        type: string
+      first_name:
+        example: Max
+        type: string
+      gender:
+        example: male
+        type: string
+      insurance_patient_data_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      opc_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      phone:
+        example: "+431234567"
+        type: string
+      street:
+        example: Hauptstraße 1
+        type: string
+      svnr:
+        example: "1234150190"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.PatientDataUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - patient_data_update
+        - patient_data
+        example: patient_data_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.PatientDataUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.PermissionAttributes:
+    properties:
+      created_at:
+        example: "2026-02-05T10:00:00Z"
+        type: string
+      description:
+        example: Allows managing users.
+        type: string
+      key:
+        example: user.manage
+        type: string
+      name:
+        example: User Management
+        type: string
+      requires_pin:
+        example: true
+        type: boolean
+      updated_at:
+        example: "2026-02-05T10:00:00Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.PermissionGroupResource:
+    properties:
+      module:
+        example: dul
+        type: string
+      module_label:
+        example: DUL
+        type: string
+      permissions:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionResource'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto.PermissionGroupedResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionGroupResource'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto.PermissionListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.PermissionMini:
+    properties:
+      description:
+        example: Permission to view users.
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9a
+        type: string
+      key:
+        example: users.read
+        type: string
+      name:
+        example: View Users
+        type: string
+      requires_pin:
+        example: false
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto.PermissionResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: permission
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.PermissionUpdateAttributes:
+    properties:
+      requires_pin:
+        example: true
+        type: boolean
+    required:
+    - requires_pin
+    type: object
+  wucher_internal_transport_http_dto.PermissionUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - permission_update
+        - permission
+        example: permission_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.PermissionUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.PilotProfileAttributes:
+    properties:
+      double_command_minutes:
+        type: integer
+      dul_base:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.DULBase'
+        type: array
+      flight_instructor_minutes:
+        type: integer
+      has_ifr_qualification:
+        type: boolean
+      ifr_flight_minutes:
+        type: integer
+      is_chief_pilot:
+        type: boolean
+      license_expired_at:
+        type: string
+      license_issued_at:
+        type: string
+      license_no:
+        maxLength: 120
+        type: string
+      location:
+        maxLength: 255
+        type: string
+      night_flight_minutes:
+        type: integer
+      note:
+        type: string
+      pilot_category:
+        enum:
+        - regular
+        - freelance
+        - dry_lease
+        type: string
+      postcode:
+        maxLength: 32
+        type: string
+      responsible_pilot_minutes:
+        type: integer
+      second_pilot_minutes:
+        type: integer
+      short_name:
+        maxLength: 120
+        type: string
+      street_line:
+        maxLength: 255
+        type: string
+      technician_license_no:
+        maxLength: 120
+        type: string
+      total_flight_minutes:
+        type: integer
+      weight_kg:
+        type: number
+    type: object
+  wucher_internal_transport_http_dto.PilotProfileUpdateAttributes:
+    properties:
+      double_command_minutes:
+        type: integer
+      dul_base:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.DULBase'
+        type: array
+      flight_instructor_minutes:
+        type: integer
+      has_ifr_qualification:
+        type: boolean
+      ifr_flight_minutes:
+        type: integer
+      is_chief_pilot:
+        type: boolean
+      license_expired_at:
+        type: string
+      license_issued_at:
+        type: string
+      license_no:
+        maxLength: 120
+        type: string
+      location:
+        maxLength: 255
+        type: string
+      night_flight_minutes:
+        type: integer
+      note:
+        type: string
+      pilot_category:
+        enum:
+        - regular
+        - freelance
+        - dry_lease
+        type: string
+      postcode:
+        maxLength: 32
+        type: string
+      responsible_pilot_minutes:
+        type: integer
+      second_pilot_minutes:
+        type: integer
+      short_name:
+        maxLength: 120
+        type: string
+      street_line:
+        maxLength: 255
+        type: string
+      technician_license_no:
+        maxLength: 120
+        type: string
+      total_flight_minutes:
+        type: integer
+      weight_kg:
+        type: number
+    type: object
+  wucher_internal_transport_http_dto.ReauthAttributes:
+    properties:
+      method:
+        enum:
+        - pin
+        - password
+        example: pin
+        type: string
+      password:
+        example: StrongP@ssw0rd
+        minLength: 1
+        type: string
+    required:
+    - method
+    type: object
+  wucher_internal_transport_http_dto.RegisterAttributes:
+    properties:
+      email:
+        example: user@example.com
+        type: string
+      first_name:
+        example: John
+        type: string
+      last_name:
+        example: Doe
+        type: string
+      mobile_phone:
+        example: "+628123456789"
+        type: string
+      password:
+        example: StrongP@ssw0rd
+        minLength: 8
+        type: string
+      username:
+        example: john.doe
+        maxLength: 100
+        minLength: 3
+        type: string
+    required:
+    - email
+    - first_name
+    - last_name
+    - password
+    - username
+    type: object
+  wucher_internal_transport_http_dto.RegisterData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RegisterAttributes'
+      type:
+        example: auth_register
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.RegisterRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RegisterData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.RequestSecurityPINAttributes:
+    properties:
+      method:
+        example: password
+        type: string
+      password:
+        example: StrongP@ssw0rd
+        type: string
+      reauth_token:
+        example: sso_reauth_1234567890abcdef
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.RequestSecurityPINData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RequestSecurityPINAttributes'
+      type:
+        example: auth_pin_request_reset
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.RequestSecurityPINRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RequestSecurityPINData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.RequestSecurityPINResetResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              message:
+                example: If allowed, a security PIN reset link has been sent to your
+                  email.
+                type: string
+            type: object
+          type:
+            example: auth_pin_request_reset
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.ResendSetPasswordInviteAttributes:
+    properties:
+      user_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - user_id
+    type: object
+  wucher_internal_transport_http_dto.ResendSetPasswordInviteData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ResendSetPasswordInviteAttributes'
+      type:
+        example: auth_resend_set_password
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ResendSetPasswordInviteRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ResendSetPasswordInviteData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ResetPasswordAttributes:
+    properties:
+      confirm_password:
+        example: StrongP@ssw0rd!LongPassphrase
+        minLength: 8
+        type: string
+      new_password:
+        example: StrongP@ssw0rd!LongPassphrase
+        minLength: 8
+        type: string
+      token:
+        example: kP8k2...
+        type: string
+    required:
+    - confirm_password
+    - new_password
+    - token
+    type: object
+  wucher_internal_transport_http_dto.ResetPasswordData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ResetPasswordAttributes'
+      type:
+        example: auth_reset_password
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ResetPasswordRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ResetPasswordData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.ResetSecurityPINAttributes:
+    properties:
+      confirm_pin:
+        example: "123456"
+        type: string
+      method:
+        example: password
+        type: string
+      new_pin:
+        example: "123456"
+        type: string
+      password:
+        example: StrongP@ssw0rd
+        type: string
+      reauth_token:
+        example: sso_reauth_1234567890abcdef
+        type: string
+      token:
+        example: kP8k2...
+        type: string
+    required:
+    - confirm_pin
+    - new_pin
+    type: object
+  wucher_internal_transport_http_dto.ResetSecurityPINData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ResetSecurityPINAttributes'
+      type:
+        example: auth_reset_pin
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.ResetSecurityPINRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ResetSecurityPINData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.RoleAttributes:
+    properties:
+      created_at:
+        example: "2026-02-05T10:00:00Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      description:
+        example: Full access to all resources.
+        type: string
+      name:
+        example: admin
+        type: string
+      updated_at:
+        example: "2026-02-05T10:00:00Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.RoleCreateAttributes:
+    properties:
+      description:
+        example: Full access to all resources.
+        type: string
+      name:
+        example: admin
+        type: string
+    required:
+    - name
+    type: object
+  wucher_internal_transport_http_dto.RoleCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RoleCreateAttributes'
+      type:
+        enum:
+        - role_create
+        - role
+        example: role_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.RoleCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RoleCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.RoleDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.RoleResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.RoleListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.RoleResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.RoleMini:
+    properties:
+      description:
+        example: Full access to all resources.
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: admin
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.RolePermissionAssignAttributes:
+    properties:
+      permission_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e
+        type: string
+    required:
+    - permission_id
+    type: object
+  wucher_internal_transport_http_dto.RolePermissionAssignBulkData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionBulkAttributes'
+      type:
+        example: role_assign_permission_bulk
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.RolePermissionAssignBulkRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignBulkData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.RolePermissionAssignData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignAttributes'
+      type:
+        example: role_permission
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.RolePermissionAssignRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.RolePermissionAttributes:
+    properties:
+      permission_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e
+        type: string
+      role_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.RolePermissionBulkAttributes:
+    properties:
+      permission_ids:
+        example:
+        - '["018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e"'
+        - '"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f"]'
+        items:
+          type: string
+        type: array
+    required:
+    - permission_ids
+    type: object
+  wucher_internal_transport_http_dto.RolePermissionListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionResource'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto.RolePermissionRemoveBulkData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionBulkAttributes'
+      type:
+        example: role_remove_permission_bulk
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.RolePermissionRemoveBulkRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionRemoveBulkData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.RolePermissionResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f
+        type: string
+      type:
+        example: role_permission
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.RolePermissionResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionResource'
+    type: object
+  wucher_internal_transport_http_dto.RoleResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RoleAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      permissions:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionResource'
+        type: array
+      type:
+        example: role
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.RoleResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RoleResource'
+    type: object
+  wucher_internal_transport_http_dto.RoleUpdateAttributes:
+    properties:
+      description:
+        example: Full access to all resources.
+        type: string
+      name:
+        example: admin
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.RoleUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RoleUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - role_update
+        - role
+        example: role_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.RoleUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RoleUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.SSOLinkAttributes:
+    properties:
+      code:
+        example: 0.AXkA...
+        type: string
+      provider:
+        example: microsoft
+        type: string
+    required:
+    - code
+    - provider
+    type: object
+  wucher_internal_transport_http_dto.SSOLinkData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.SSOLinkAttributes'
+      type:
+        example: auth_sso_link
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.SSOLinkRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.SSOLinkData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.SSOLinkResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              email:
+                example: user@example.com
+                type: string
+              provider:
+                example: microsoft
+                type: string
+              provider_subject:
+                example: 00000000-0000-0000-0000-000000000000
+                type: string
+            type: object
+          type:
+            example: auth_sso_link
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.SSOUnlinkAttributes:
+    properties:
+      provider:
+        example: microsoft
+        type: string
+    required:
+    - provider
+    type: object
+  wucher_internal_transport_http_dto.SSOUnlinkData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.SSOUnlinkAttributes'
+      type:
+        example: auth_sso_unlink
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.SSOUnlinkRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.SSOUnlinkData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.SSOUnlinkResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              provider:
+                example: microsoft
+                type: string
+              unlinked:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: auth_sso_unlink
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.SecurityPINChangeAttributes:
+    properties:
+      confirm_pin:
+        example: "654321"
+        type: string
+      current_pin:
+        example: "123456"
+        type: string
+      new_pin:
+        example: "654321"
+        type: string
+    required:
+    - confirm_pin
+    - current_pin
+    - new_pin
+    type: object
+  wucher_internal_transport_http_dto.SecurityPINChangeData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.SecurityPINChangeAttributes'
+      type:
+        example: auth_pin_change
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.SecurityPINChangeRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.SecurityPINChangeData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.SecurityPINSetupAttributes:
+    properties:
+      confirm_pin:
+        example: "123456"
+        type: string
+      pin:
+        example: "123456"
+        type: string
+    required:
+    - confirm_pin
+    - pin
+    type: object
+  wucher_internal_transport_http_dto.SecurityPINSetupData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.SecurityPINSetupAttributes'
+      type:
+        example: auth_pin_setup
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.SecurityPINSetupRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.SecurityPINSetupData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.SecurityPINSetupResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              configured:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: auth_pin_setup
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.SecurityPINVerifyAttributes:
+    properties:
+      action:
+        example: a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74
+        type: string
+      pin:
+        example: "123456"
+        type: string
+    required:
+    - action
+    - pin
+    type: object
+  wucher_internal_transport_http_dto.SecurityPINVerifyData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.SecurityPINVerifyAttributes'
+      type:
+        example: auth_pin_verify
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.SecurityPINVerifyRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.SecurityPINVerifyData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.SecurityPINVerifyResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              action_token:
+                example: pinv_1234567890abcdef
+                type: string
+              action_token_ttl_ms:
+                example: 900000
+                type: integer
+              verified:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: auth_pin_verify
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.SetPasswordAttributes:
+    properties:
+      password:
+        example: StrongP@ssw0rd
+        minLength: 8
+        type: string
+      token:
+        example: kP8k2...
+        type: string
+    required:
+    - password
+    - token
+    type: object
+  wucher_internal_transport_http_dto.SetPasswordData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.SetPasswordAttributes'
+      type:
+        example: auth_set_password
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.SetPasswordRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.SetPasswordData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.StaffProfileAttributes:
+    properties:
+      location:
+        maxLength: 255
+        type: string
+      note:
+        type: string
+      postcode:
+        maxLength: 32
+        type: string
+      role_label:
+        maxLength: 120
+        type: string
+      short_name:
+        maxLength: 120
+        type: string
+      street_line:
+        maxLength: 255
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.StaffProfileUpdateAttributes:
+    properties:
+      location:
+        maxLength: 255
+        type: string
+      note:
+        type: string
+      postcode:
+        maxLength: 32
+        type: string
+      role_label:
+        maxLength: 120
+        type: string
+      short_name:
+        maxLength: 120
+        type: string
+      street_line:
+        maxLength: 255
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.TOTPConfirmAttributes:
+    properties:
+      code:
+        example: "123456"
+        type: string
+      user_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - code
+    - user_id
+    type: object
+  wucher_internal_transport_http_dto.TOTPConfirmData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPConfirmAttributes'
+      type:
+        example: auth_totp_confirm
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.TOTPConfirmRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPConfirmData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.TOTPDisableAttributes:
+    properties:
+      user_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - user_id
+    type: object
+  wucher_internal_transport_http_dto.TOTPDisableData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPDisableAttributes'
+      type:
+        example: auth_totp_disable
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.TOTPDisableRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPDisableData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.TOTPResetSetupData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ReauthAttributes'
+      type:
+        example: auth_totp_reset_setup
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.TOTPResetSetupRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPResetSetupData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.TOTPSetupAttributes:
+    properties:
+      email:
+        example: user@example.com
+        type: string
+      user_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - email
+    - user_id
+    type: object
+  wucher_internal_transport_http_dto.TOTPSetupData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPSetupAttributes'
+      type:
+        example: auth_totp_setup
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.TOTPSetupRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPSetupData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.TOTPSetupResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              issuer:
+                example: Wucher
+                type: string
+              otpauth_url:
+                example: otpauth://totp/Wucher:user@example.com?...
+                type: string
+              secret:
+                example: JBSWY3DPEHPK3PXP
+                type: string
+            type: object
+          type:
+            example: auth_totp_setup
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.TOTPVerifyAttributes:
+    properties:
+      challenge_token:
+        example: kP8k2...
+        type: string
+      code:
+        example: "123456"
+        type: string
+    required:
+    - challenge_token
+    - code
+    type: object
+  wucher_internal_transport_http_dto.TOTPVerifyData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPVerifyAttributes'
+      type:
+        example: auth_totp_verify
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.TOTPVerifyRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPVerifyData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.TechnicianProfileAttributes:
+    properties:
+      is_chief_technician:
+        type: boolean
+      is_responsible_complaints:
+        type: boolean
+      license_no:
+        maxLength: 120
+        type: string
+      location:
+        maxLength: 255
+        type: string
+      note:
+        type: string
+      postcode:
+        maxLength: 32
+        type: string
+      short_name:
+        maxLength: 120
+        type: string
+      street_line:
+        maxLength: 255
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.TechnicianProfileUpdateAttributes:
+    properties:
+      is_chief_technician:
+        type: boolean
+      is_responsible_complaints:
+        type: boolean
+      license_no:
+        maxLength: 120
+        type: string
+      location:
+        maxLength: 255
+        type: string
+      note:
+        type: string
+      postcode:
+        maxLength: 32
+        type: string
+      short_name:
+        maxLength: 120
+        type: string
+      street_line:
+        maxLength: 255
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.TimezoneUpdateAttributes:
+    properties:
+      timezone:
+        example: Asia/Jakarta
+        type: string
+    required:
+    - timezone
+    type: object
+  wucher_internal_transport_http_dto.TimezoneUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TimezoneUpdateAttributes'
+      type:
+        example: auth_timezone_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.TimezoneUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.TimezoneUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.TokenResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              access_expires_in:
+                example: 900
+                type: integer
+              refresh_expires_in:
+                example: 2592000
+                type: integer
+            type: object
+          type:
+            example: auth_tokens
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.UserAttributes:
+    properties:
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      email:
+        example: user@example.com
+        type: string
+      email_verified_at:
+        example: "2026-02-05T10:00:00Z"
+        type: string
+      first_name:
+        example: John
+        type: string
+      is_previously_configured:
+        example: false
+        type: boolean
+      last_name:
+        example: Doe
+        type: string
+      linked_sso:
+        example: false
+        type: boolean
+      mobile_phone:
+        example: "+628123456789"
+        type: string
+      pin_configured:
+        example: false
+        type: boolean
+      profile_picture:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.UserImage'
+      role:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.RoleMini'
+      role_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      role_ids:
+        example:
+        - '["018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"'
+        - '"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e"]'
+        items:
+          type: string
+        type: array
+      roles:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.RoleMini'
+        type: array
+      timezone:
+        example: Asia/Jakarta
+        type: string
+      totp_enabled:
+        example: false
+        type: boolean
+      username:
+        example: john.doe
+        type: string
+      webauthn_configured:
+        example: false
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto.UserCreateAttributes:
+    properties:
+      email:
+        example: user@example.com
+        type: string
+      first_name:
+        example: John
+        type: string
+      image_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90
+        type: string
+      last_name:
+        example: Doe
+        type: string
+      mobile_phone:
+        example: "+628123456789"
+        type: string
+      role_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      role_ids:
+        example:
+        - '["018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"'
+        - '"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e"]'
+        items:
+          type: string
+        type: array
+      timezone:
+        example: Asia/Jakarta
+        type: string
+      username:
+        example: john.doe
+        maxLength: 100
+        minLength: 3
+        type: string
+    required:
+    - email
+    - first_name
+    - last_name
+    - role_id
+    - username
+    type: object
+  wucher_internal_transport_http_dto.UserCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.UserCreateAttributes'
+      type:
+        enum:
+        - user_create
+        - user
+        example: user_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.UserCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.UserCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.UserDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.UserResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.UserFoto:
+    properties:
+      download_url:
+        example: https://storage.example.com/base/lude.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=abc123
+        type: string
+      original_size_bytes:
+        example: 1024000
+        type: integer
+      thumbnail_download_url:
+        example: https://storage.example.com/base/lude.thumb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=abc123
+        type: string
+      uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.UserImage:
+    properties:
+      download_url:
+        example: https://example.com/presigned-url
+        type: string
+      original_size_bytes:
+        example: 1024000
+        type: integer
+      thumbnail_download_url:
+        example: https://example.com/presigned-thumb-url
+        type: string
+      uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.UserListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.UserResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.UserResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.UserAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: user
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.UserResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.UserAttributes'
+          id:
+            example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+            type: string
+          type:
+            example: user
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.UserUpdateAttributes:
+    properties:
+      email:
+        example: user@example.com
+        type: string
+      first_name:
+        example: John
+        type: string
+      image_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90
+        type: string
+      last_name:
+        example: Doe
+        type: string
+      mobile_phone:
+        example: "+628123456789"
+        type: string
+      timezone:
+        example: Asia/Jakarta
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.UserUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.UserUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - user_update
+        - user
+        example: user_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.UserUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.UserUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.VerifyEmailResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              verified:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: auth_verify_email
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.VocationAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      name:
+        example: Pilot
+        type: string
+      note:
+        example: Helicopter pilot vocation
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.VocationCreateAttributes:
+    properties:
+      is_active:
+        example: true
+        type: boolean
+      name:
+        example: Pilot
+        type: string
+      note:
+        example: Helicopter pilot vocation
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+    required:
+    - name
+    type: object
+  wucher_internal_transport_http_dto.VocationCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.VocationCreateAttributes'
+      type:
+        enum:
+        - vocation_create
+        - vocation
+        example: vocation_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.VocationCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.VocationCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.VocationDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.VocationResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.VocationListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.VocationResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.VocationResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.VocationAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: vocation
+        type: string
+    type: object
+  wucher_internal_transport_http_dto.VocationResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.VocationResource'
+    type: object
+  wucher_internal_transport_http_dto.VocationUpdateAttributes:
+    properties:
+      is_active:
+        example: true
+        type: boolean
+      name:
+        example: Pilot
+        type: string
+      note:
+        example: Helicopter pilot vocation
+        type: string
+      sortkey:
+        example: 1
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto.VocationUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.VocationUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - vocation_update
+        - vocation
+        example: vocation_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.VocationUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.VocationUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnBeginResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              challenge_token:
+                example: kP8k2...
+                type: string
+              challenge_ttl_ms:
+                example: 300000
+                type: integer
+              public_key:
+                additionalProperties: true
+                type: object
+            type: object
+          type:
+            example: auth_webauthn_register_options
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnLoginBeginAttributes:
+    properties:
+      email:
+        example: user@example.com
+        type: string
+    required:
+    - email
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnLoginBeginData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginBeginAttributes'
+      type:
+        example: auth_webauthn_login_begin
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnLoginBeginRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginBeginData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnLoginFinishAttributes:
+    properties:
+      challenge_token:
+        example: kP8k2...
+        type: string
+      credential:
+        items:
+          type: integer
+        type: array
+    required:
+    - challenge_token
+    - credential
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnLoginFinishData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginFinishAttributes'
+      type:
+        example: auth_webauthn_login_finish
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnLoginFinishRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginFinishData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnRegisterBeginData:
+    properties:
+      type:
+        example: auth_webauthn_register_begin
+        type: string
+    required:
+    - type
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnRegisterBeginRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterBeginData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnRegisterFinishAttributes:
+    properties:
+      challenge_token:
+        example: kP8k2...
+        type: string
+      credential:
+        items:
+          type: integer
+        type: array
+      name:
+        example: MacBook Touch ID
+        maxLength: 100
+        type: string
+    required:
+    - challenge_token
+    - credential
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnRegisterFinishData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterFinishAttributes'
+      type:
+        example: auth_webauthn_register_finish
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnRegisterFinishRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterFinishData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnResetSetupData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.ReauthAttributes'
+      type:
+        example: auth_webauthn_reset_setup
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnResetSetupRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnResetSetupData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto.WebAuthnResetSetupResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              reset:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: auth_webauthn_reset_setup
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_request.ActionSignoffSignAttributes:
+    properties:
+      complaint_id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      flight_id:
+        description: |-
+          FlightID — REQUIRED for the fleet (complaint-independent) sign-off; scopes it to a
+          flight so it no longer leaks across takeovers of the same aircraft. Ignored when
+          complaint_id is set (that sign-off is keyed by the complaint).
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      sign:
+        description: |-
+          Sign toggles the sign-off: true (or omitted) signs it, false unsigns (clears the
+          signature). Combine with complaint_id to toggle a specific complaint's sign-off.
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_request.ActionSignoffSignData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ActionSignoffSignAttributes'
+      type:
+        example: action_signoff
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.ActionSignoffSignRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ActionSignoffSignData'
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateAttributes:
+    properties:
+      base_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      checklists:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateEntry'
+        minItems: 1
+        type: array
+    required:
+    - base_id
+    - checklists
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateAttributes'
+      type:
+        enum:
+        - air_rescuer_checklist_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateEntry:
+    properties:
+      items:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistItemInput'
+        type: array
+      position:
+        example: 1
+        type: integer
+      scope_code:
+        example: MO
+        type: string
+      title:
+        example: Monday Checklist
+        type: string
+    required:
+    - scope_code
+    - title
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateAttributes:
+    properties:
+      items:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistItemInput'
+        minItems: 1
+        type: array
+    required:
+    - items
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateAttributes'
+      type:
+        enum:
+        - air_rescuer_checklist_item_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderAttributes:
+    properties:
+      items:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderEntry'
+        minItems: 1
+        type: array
+    required:
+    - items
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderAttributes'
+      type:
+        enum:
+        - air_rescuer_checklist_item_reorder
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderEntry:
+    properties:
+      item_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      position:
+        example: 2
+        type: integer
+    required:
+    - item_uuid
+    - position
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateAttributes:
+    properties:
+      name:
+        example: Check radio
+        type: string
+      position:
+        example: 2
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - air_rescuer_checklist_item_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateAttributes:
+    properties:
+      new_items:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistItemInput'
+        type: array
+      position:
+        example: 1
+        type: integer
+      scope_code:
+        example: MO
+        type: string
+      title:
+        example: Monday Checklist Updated
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - air_rescuer_checklist_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.ComplaintActionTakenAttributes:
+    properties:
+      action_taken:
+        description: |-
+          ActionTaken — corrective action text. Required when recording (create); on update an
+          empty value clears it (allowed only while the action has not been signed off).
+        example: Tightened engine mount and rechecked torque
+        type: string
+      aircraft_hours_at_fix:
+        example: "1250.1"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.ComplaintActionTakenData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintActionTakenAttributes'
+      type:
+        enum:
+        - complaint_action_taken
+        - complaint
+        example: complaint_action_taken
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.ComplaintActionTakenRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintActionTakenData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.ComplaintCreateAttributes:
+    properties:
+      aircraft_hours_at_report:
+        description: AircraftHoursAtReport — OPTIONAL airframe hours recorded when
+          the defect was reported.
+        example: "1245.3"
+        type: string
+      description:
+        description: Description — the defect description. REQUIRED.
+        example: Engine 2 N2 vibration intermittent during cruise above 110 KIAS
+        type: string
+      flight_id:
+        description: |-
+          FlightID — the flight/report this complaint was filed in (attribution). OPTIONAL;
+          open-defect tracking stays per-helicopter so defects carry forward across flights.
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      helicopter_id:
+        description: HelicopterID — the helicopter this complaint is filed against.
+          REQUIRED.
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      mel_severity:
+        description: |-
+          MELSeverity — MEL (Minimum Equipment List) classification. OPTIONAL at creation:
+          omit it to file the complaint as "pending_mel" and classify later. It MUST be
+          classified (via update) before recording action taken. A pending complaint does
+          NOT ground the aircraft — grounding starts at classification. Values: 0 = NON-MEL
+          (grounds immediately), 1 = A (grace 1 day), 2 = B (3 days), 3 = C (10 days), 4 = D (120 days).
+        enum:
+        - 0
+        - 1
+        - 2
+        - 3
+        - 4
+        example: 2
+        type: integer
+    required:
+    - description
+    - helicopter_id
+    type: object
+  wucher_internal_transport_http_dto_request.ComplaintCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintCreateAttributes'
+      type:
+        enum:
+        - complaint_create
+        - complaint
+        example: complaint_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.ComplaintCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.ComplaintNSRSignAttributes:
+    properties:
+      nsr_reason:
+        description: NSRReason — OPTIONAL free-text justification for the NSR (MEL
+          deferral) decision.
+        example: Released under MEL A, defect deferred
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.ComplaintNSRSignData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintNSRSignAttributes'
+      type:
+        enum:
+        - complaint_nsr_sign
+        - complaint_nsr
+        example: complaint_nsr_sign
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.ComplaintNSRSignRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintNSRSignData'
+    type: object
+  wucher_internal_transport_http_dto_request.ComplaintUpdateAttributes:
+    properties:
+      aircraft_hours_at_report:
+        description: AircraftHoursAtReport — airframe hours at report time.
+        example: "1245.3"
+        type: string
+      description:
+        description: Description — defect description.
+        example: Engine 2 vibration confirmed
+        type: string
+      mel_severity:
+        description: |-
+          MELSeverity — MEL classification. 0 = NON-MEL (immediate AOG), 1 = A (1 day),
+          2 = B (3 days), 3 = C (10 days), 4 = D (120 days). AOG after grace passes.
+        enum:
+        - 0
+        - 1
+        - 2
+        - 3
+        - 4
+        example: 2
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_request.ComplaintUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintUpdateAttributes'
+      id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      type:
+        enum:
+        - complaint_update
+        - complaint
+        example: complaint_update
+        type: string
+    required:
+    - attributes
+    - id
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.ComplaintUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterAnyDeleteData:
+    properties:
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - id
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterAnyDeleteRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterAnyDeleteData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterCreateAttributes:
+    properties:
+      base_id:
+        type: string
+      duty_date:
+        type: string
+      roster_detail:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDetailsInput'
+      shift_time:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterShiftTime'
+    required:
+    - base_id
+    - duty_date
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCreateAttributes'
+      type:
+        enum:
+        - duty_roster_create
+        - duty_roster
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterCrewInput:
+    properties:
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      shift_date:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterShiftDate'
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewAttributes:
+    properties:
+      roster_detail:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDetailsInput'
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDAttributes:
+    properties:
+      crew_id:
+        type: string
+      roster_id:
+        type: string
+    required:
+    - crew_id
+    - roster_id
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDAttributes'
+      type:
+        enum:
+        - duty_roster_crew_delete
+        - duty_roster_update
+        - duty_roster
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewAttributes'
+      type:
+        enum:
+        - duty_roster_crew_delete
+        - duty_roster_update
+        - duty_roster
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterDetailsInput:
+    properties:
+      doctor:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCrewInput'
+        type: array
+      helper:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCrewInput'
+        type: array
+      other_person:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterOtherPersonInput'
+        type: array
+      pilot:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterPilotCrewInput'
+        type: array
+      rescuer:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCrewInput'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterOtherPersonInput:
+    properties:
+      email:
+        example: guest@example.com
+        type: string
+      mobile_phone:
+        example: +43-1234
+        type: string
+      name:
+        example: Guest Person
+        type: string
+      other_person_id:
+        description: |-
+          OtherPersonID — OPTIONAL master person id to reuse (from GET /contact/other).
+          When set, name/mobile_phone/email are snapshotted from the master (may be omitted).
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterPilotCrewInput:
+    properties:
+      co_pilot:
+        type: boolean
+      crew_type:
+        enum:
+        - main
+        - additional
+        example: main
+        type: string
+      examiner:
+        type: boolean
+      flight_instructor:
+        type: boolean
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      line_checker:
+        type: boolean
+      shift_date:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterShiftDate'
+      supervisor:
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterShiftDate:
+    properties:
+      date_end:
+        example: "2026-03-16"
+        type: string
+      date_start:
+        example: "2026-03-16"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterShiftTime:
+    properties:
+      shift_end:
+        example: "21:00"
+        type: string
+      shift_start:
+        example: "06:00"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterUpdateAttributes:
+    properties:
+      base_id:
+        type: string
+      duty_date:
+        type: string
+      roster_detail:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDetailsInput'
+      shift_time:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterShiftTime'
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterUpdateAttributes'
+      id:
+        type: string
+      type:
+        enum:
+        - duty_roster_update
+        - duty_roster
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.DutyRosterUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.EASAReleaseCreateAttributes:
+    properties:
+      complaint_id:
+        description: |-
+          ComplaintID — OPTIONAL complaint (UUIDv7) this release closes. Set it to scope the
+          release to a specific defect; leave empty for a standalone (aircraft-clear) release.
+        example: 019d6774-1111-7fba-9ef4-3795c0da8a13
+        type: string
+      easa_ac_hours:
+        example: "1245.3"
+        type: string
+      easa_date:
+        example: "2026-06-16"
+        type: string
+      easa_location:
+        example: LOWI
+        type: string
+      easa_maint_manual_rev_airframe:
+        example: Rev 12
+        type: string
+      easa_maint_manual_rev_engine:
+        example: Rev 8
+        type: string
+      easa_permit_no:
+        example: 145.A.50
+        type: string
+      easa_signer_id:
+        description: EASASignerID — OPTIONAL contact id (UUIDv7) of the signer/technician.
+          Required only to sign.
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      easa_wo_no:
+        example: WO-2026-001
+        type: string
+      flight_id:
+        description: FlightID — OPTIONAL flight context. Used for the standalone (no-complaint)
+          sign-off gate.
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      helicopter_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      sign:
+        description: |-
+          Sign, when true, signs the release immediately at creation. Requires all
+          required fields to be present; otherwise the request is rejected.
+        example: false
+        type: boolean
+    required:
+    - helicopter_id
+    type: object
+  wucher_internal_transport_http_dto_request.EASAReleaseCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseCreateAttributes'
+      type:
+        enum:
+        - easa_release_create
+        - easa_release
+        example: easa_release_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.EASAReleaseCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.EASAReleaseUpdateAttributes:
+    properties:
+      easa_ac_hours:
+        example: "1245.3"
+        type: string
+      easa_date:
+        example: "2026-06-16"
+        type: string
+      easa_location:
+        example: LOWI
+        type: string
+      easa_maint_manual_rev_airframe:
+        example: Rev 12
+        type: string
+      easa_maint_manual_rev_engine:
+        example: Rev 8
+        type: string
+      easa_permit_no:
+        example: 145.A.50
+        type: string
+      easa_signer_id:
+        description: EASASignerID — OPTIONAL contact id (UUIDv7) of the signer/technician.
+          Required only to sign.
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      easa_wo_no:
+        example: WO-2026-001
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.EASAReleaseUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseUpdateAttributes'
+      id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      type:
+        enum:
+        - easa_release_update
+        - easa_release
+        example: easa_release_update
+        type: string
+    required:
+    - attributes
+    - id
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.EASAReleaseUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FMReportUpdateAttributes:
+    properties:
+      engine1_gpc_n1:
+        description: Engine1GpcN1 - GPC/N1 value for engine 1. Optional.
+        example: GPC/N1 63.2
+        type: string
+      engine1_ptc_n2:
+        description: Engine1PtcN2 - PTC/N2 value for engine 1. Optional.
+        example: PTC/N2 61.8
+        type: string
+      engine2_gpc_n1:
+        description: Engine2GpcN1 - GPC/N1 value for engine 2. Optional.
+        example: GPC/N1 63.2
+        type: string
+      engine2_ptc_n2:
+        description: Engine2PtcN2 - PTC/N2 value for engine 2. Optional.
+        example: PTC/N2 61.8
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.FMReportUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FMReportUpdateAttributes'
+      type:
+        enum:
+        - fm_report_update
+        - fm_report
+        example: fm_report_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FMReportUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FMReportUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateAttributes:
+    properties:
+      category:
+        example: document
+        type: string
+      file_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      is_primary:
+        example: false
+        type: boolean
+      ref_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      ref_type:
+        example: helicopter
+        type: string
+      sort_order:
+        example: 0
+        type: integer
+    required:
+    - file_id
+    - ref_id
+    - ref_type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateAttributes'
+      type:
+        enum:
+        - file_manager_attachment_create
+        - file_manager_attachment
+        example: file_manager_attachment_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileAircraftBulkCreateItem:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileAircraftCreateAttributes'
+      type:
+        enum:
+        - file_manager_file_create
+        - file_manager_file
+        example: file_manager_file_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileAircraftBulkCreateRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileAircraftBulkCreateItem'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileAircraftCreateAttributes:
+    properties:
+      aircraft_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: aircraft.jpg
+        type: string
+      upload_intent_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - aircraft_uuid
+    - name
+    - upload_intent_uuid
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileBaseBulkCreateItem:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileBaseCreateAttributes'
+      type:
+        enum:
+        - file_manager_file_create
+        - file_manager_file
+        example: file_manager_file_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileBaseBulkCreateRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileBaseBulkCreateItem'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileBaseCreateAttributes:
+    properties:
+      base_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: base.jpg
+        type: string
+      upload_intent_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - base_uuid
+    - name
+    - upload_intent_uuid
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadAttributes:
+    properties:
+      upload_intent_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - upload_intent_uuid
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadBulkRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadData'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadAttributes'
+      type:
+        enum:
+        - file_manager_file_cancel_upload
+        example: file_manager_file_cancel_upload
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileDULBulkCreateItem:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileDULCreateAttributes'
+      type:
+        enum:
+        - file_manager_file_create
+        - file_manager_file
+        example: file_manager_file_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileDULBulkCreateRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileDULBulkCreateItem'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileDULCreateAttributes:
+    properties:
+      dul_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: dul.jpg
+        type: string
+      upload_intent_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - name
+    - upload_intent_uuid
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileMissionBulkCreateItem:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileMissionCreateAttributes'
+      type:
+        enum:
+        - file_manager_file_create
+        - file_manager_file
+        example: file_manager_file_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileMissionBulkCreateRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileMissionBulkCreateItem'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileMissionCreateAttributes:
+    properties:
+      mission_uuid:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      name:
+        example: mission-brief.pdf
+        type: string
+      upload_intent_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - mission_uuid
+    - name
+    - upload_intent_uuid
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileTakeoverBulkCreateItem:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTakeoverCreateAttributes'
+      type:
+        enum:
+        - file_manager_file_create
+        - file_manager_file
+        example: file_manager_file_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileTakeoverBulkCreateRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTakeoverBulkCreateItem'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileTakeoverCreateAttributes:
+    properties:
+      name:
+        example: takeover-report.pdf
+        type: string
+      takeover_uuid:
+        example: 019e8713-aa19-7fb7-a510-a0332dc69697
+        type: string
+      upload_intent_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - name
+    - upload_intent_uuid
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileTemplateCreateAttributes:
+    properties:
+      helicopter_id:
+        example: 019e8713-aa19-7fb7-a510-a0332dc69697
+        type: string
+      name:
+        example: collabora-draft.docx
+        type: string
+      takeover_id:
+        example: 019e8713-aa19-7fb7-a510-a0332dc69697
+        type: string
+      template_uuid:
+        example: 019f0386-0a00-7a4a-a2d8-30afc0e0c3ad
+        type: string
+    required:
+    - helicopter_id
+    - name
+    - template_uuid
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileTemplateCreateRequest:
+    properties:
+      data:
+        properties:
+          attributes:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTemplateCreateAttributes'
+          type:
+            enum:
+            - file_manager_file_create_from_template
+            - file_manager_file_create
+            type: string
+        required:
+        - attributes
+        - type
+        type: object
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileUpdateAttributes:
+    properties:
+      folder_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: policy-v2.pdf
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - file_manager_file_update
+        - file_manager_file
+        example: file_manager_file_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentAttributes:
+    properties:
+      content_type:
+        example: application/pdf
+        type: string
+      name:
+        example: policy-final.pdf
+        type: string
+      size_bytes:
+        example: 1024
+        minimum: 0
+        type: integer
+    required:
+    - content_type
+    - name
+    - size_bytes
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentData'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentAttributes'
+      type:
+        enum:
+        - file_manager_file_upload_intent
+        example: file_manager_file_upload_intent
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateItem:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUserCreateAttributes'
+      type:
+        enum:
+        - file_manager_file_create
+        - file_manager_file
+        example: file_manager_file_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateItem'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFileUserCreateAttributes:
+    properties:
+      name:
+        example: profile.jpg
+        type: string
+      upload_intent_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      user_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - name
+    - upload_intent_uuid
+    - user_uuid
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFolderCreateAttributes:
+    properties:
+      name:
+        example: operations
+        type: string
+      parent_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - name
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFolderCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderCreateAttributes'
+      type:
+        enum:
+        - file_manager_folder_create
+        - file_manager_folder
+        example: file_manager_folder_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFolderCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFolderUpdateAttributes:
+    properties:
+      name:
+        example: operations-updated
+        type: string
+      parent_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFolderUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - file_manager_folder_update
+        - file_manager_folder
+        example: file_manager_folder_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerFolderUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerNodeMoveBulkRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodeMoveItem'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerNodeMoveItem:
+    properties:
+      destination_folder_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - uuid
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerNodePurgeBulkRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodePurgeItem'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FileManagerNodePurgeItem:
+    properties:
+      uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    required:
+    - uuid
+    type: object
+  wucher_internal_transport_http_dto_request.FleetStatusCreateAttributes:
+    properties:
+      files:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusFileAttributes'
+        type: array
+      helicopter_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      maintenance_schedules:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes'
+        type: array
+    required:
+    - helicopter_id
+    type: object
+  wucher_internal_transport_http_dto_request.FleetStatusCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FleetStatusCreateAttributes'
+      type:
+        enum:
+        - fleet_status_create
+        - fleet_status
+        example: fleet_status_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FleetStatusCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FleetStatusCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FleetStatusSummaryAirframeUpdate:
+    properties:
+      cycles:
+        example: 320
+        type: number
+      hours:
+        example: 6610.5
+        type: number
+    type: object
+  wucher_internal_transport_http_dto_request.FleetStatusSummaryEngineUpdate:
+    properties:
+      ccc:
+        example: 44
+        type: number
+      gpc_ng_n1:
+        example: 98.7
+        type: number
+      hours:
+        example: 8001.7
+        type: number
+      ptc_nf_n2:
+        example: 97.2
+        type: number
+    type: object
+  wucher_internal_transport_http_dto_request.FleetStatusSummaryUpdate:
+    properties:
+      airframe:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FleetStatusSummaryAirframeUpdate'
+      engine_1:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FleetStatusSummaryEngineUpdate'
+      engine_2:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FleetStatusSummaryEngineUpdate'
+      flight_reports:
+        example: 80
+        type: number
+      hook_releases:
+        example: 10
+        type: number
+      landings:
+        example: 120
+        type: number
+      rotor_brake_cycles:
+        example: 8
+        type: number
+    type: object
+  wucher_internal_transport_http_dto_request.FleetStatusUpdateAttributes:
+    properties:
+      files:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusFileAttributes'
+        type: array
+      helicopter_id:
+        type: string
+      maintenance_schedules:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes'
+        type: array
+      summary:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FleetStatusSummaryUpdate'
+    type: object
+  wucher_internal_transport_http_dto_request.FleetStatusUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FleetStatusUpdateAttributes'
+      id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      type:
+        enum:
+        - fleet_status_update
+        - fleet_status
+        example: fleet_status_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FleetStatusUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FleetStatusUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataCreateAttributes:
+    properties:
+      co_pilot_id:
+        type: string
+      customer_name:
+        type: string
+      delivery_note_number:
+        type: string
+      engine:
+        type: string
+      flight_duration_seconds:
+        type: integer
+      flight_landing:
+        type: string
+      flight_plan_distance:
+        type: number
+      flight_plan_time_seconds:
+        type: integer
+      flight_plan_true_course:
+        type: number
+      flight_positioning:
+        example: false
+        type: boolean
+      flight_red_seconds:
+        type: integer
+      flight_take_off:
+        type: string
+      from_hospital_id:
+        type: string
+      from_icao_id:
+        type: string
+      fuel_after_flight:
+        type: number
+      fuel_before_flight:
+        type: number
+      fuel_planning:
+        type: number
+      fuel_upload:
+        type: number
+      hec:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECAttributes'
+      heslo:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOAttributes'
+      hook_releases:
+        type: integer
+      landing_count:
+        type: integer
+      logging:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOLoggingAttributes'
+      max_n1:
+        type: number
+      max_n2:
+        type: number
+      mission_id:
+        type: string
+      other_information:
+        type: string
+      pax_count:
+        type: integer
+      rotor_brake_cycle:
+        type: integer
+      ticket_no:
+        type: string
+      to_hospital_id:
+        type: string
+      to_icao_id:
+        type: string
+    required:
+    - mission_id
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateAttributes'
+      type:
+        enum:
+        - flight_data_create
+        - flight_data
+        example: flight_data_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECAttributes:
+    properties:
+      flights:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECFlight'
+        type: array
+      loads:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECLoad'
+        type: array
+      slings:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECSling'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECFlight:
+    properties:
+      equipment_id:
+        description: 'Facility category: hec-rope-label.'
+        example: string
+        type: string
+      equipment_name:
+        example: string
+        type: string
+      hec_cycle:
+        example: 0
+        type: integer
+      rot:
+        example: 0
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECLoad:
+    properties:
+      load_category:
+        description: Weight band for the HEC load, e.g. "bis 199 kg", "200-600 kg",
+          "600-800 kg", "800-1000 kg".
+        example: 200-600 kg
+        type: string
+      quantity:
+        example: 3
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataCreateSPOHECSling:
+    properties:
+      sling_id:
+        description: 'Facility category: hec-rope-length.'
+        example: string
+        type: string
+      sling_name:
+        example: string
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOAttributes:
+    properties:
+      flights:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOFlight'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOFlight:
+    properties:
+      heslo_rope_label_id:
+        description: 'Facility category: heslo-rope-label.'
+        example: string
+        type: string
+      heslo_rope_label_name:
+        example: string
+        type: string
+      rot:
+        example: 0
+        type: integer
+      slings:
+        description: 'Facility category: heslo-rope-length.'
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOSling'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataCreateSPOHESLOSling:
+    properties:
+      sling_id:
+        description: 'Facility category: heslo-rope-length.'
+        example: string
+        type: string
+      sling_name:
+        example: string
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataCreateSPOLoggingAttributes:
+    properties:
+      slings:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateSPOLoggingSling'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataCreateSPOLoggingSling:
+    properties:
+      sling_id:
+        description: 'Facility category: heslo-hook.'
+        example: string
+        type: string
+      sling_name:
+        example: string
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateAttributes'
+      type:
+        enum:
+        - flight_data_update
+        example: flight_data_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.FlightDataUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterCreateAttributes:
+    properties:
+      aog:
+        example: false
+        type: boolean
+      aog_reason:
+        example: Main rotor gearbox fault
+        type: string
+      consumption_lt_min:
+        example: 4.1
+        type: number
+      designation:
+        example: OE-XHZ
+        type: string
+      dry:
+        example: false
+        type: boolean
+      engine_1:
+        example: TM
+        type: string
+      engine_2:
+        example: TM
+        type: string
+      file_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90
+        type: string
+      identifier:
+        example: ABC
+        type: string
+      igb:
+        example: false
+        type: boolean
+      is_active:
+        example: true
+        type: boolean
+      lh:
+        example: true
+        type: boolean
+      mgb:
+        example: true
+        type: boolean
+      note:
+        example: Primary HEMS helicopter
+        type: string
+      nr1:
+        example: true
+        type: boolean
+      nr2:
+        example: true
+        type: boolean
+      rh:
+        example: true
+        type: boolean
+      sortkey:
+        example: 10
+        type: integer
+      tgb:
+        example: true
+        type: boolean
+      type:
+        example: EC-135
+        type: string
+      utc_offset:
+        example: -1
+        type: integer
+    required:
+    - designation
+    - identifier
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterCreateAttributes'
+      type:
+        enum:
+        - helicopter_create
+        - helicopter
+        example: helicopter_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadAttributes:
+    properties:
+      upload_intent_uuid:
+        example: 019d6d0d-2de2-7db1-80a2-2862d43af620
+        type: string
+    required:
+    - upload_intent_uuid
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadBulkRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadData'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadAttributes'
+      type:
+        enum:
+        - helicopter_file_cancel_upload
+        example: helicopter_file_cancel_upload
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileCreateAttributes:
+    properties:
+      file_name:
+        example: Before Flight Checklist.pdf
+        type: string
+      folder_uuid:
+        example: 019d6d0d-8c24-72e3-9f58-c9ea0fbf0bb1
+        type: string
+      helicopter_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      is_mandatory:
+        example: true
+        type: boolean
+      position:
+        example: 1
+        type: integer
+      section:
+        enum:
+        - bfi
+        - fpwb
+        - afi
+        example: bfi
+        type: string
+      upload_intent_uuid:
+        example: 019d6d0d-2de2-7db1-80a2-2862d43af620
+        type: string
+    required:
+    - file_name
+    - section
+    - upload_intent_uuid
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileCreateBulkRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCreateData'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCreateAttributes'
+      type:
+        enum:
+        - helicopter_file_create
+        - helicopter_file
+        example: helicopter_file_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileDeleteData:
+    properties:
+      id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      type:
+        enum:
+        - helicopter_file_delete
+        - helicopter_file
+        example: helicopter_file_delete
+        type: string
+    required:
+    - id
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileDeleteRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileDeleteData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileUpdateAttributes:
+    properties:
+      file_name:
+        example: Before Flight Checklist v2.pdf
+        type: string
+      helicopter_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      is_mandatory:
+        example: true
+        type: boolean
+      position:
+        example: 1
+        type: integer
+      section:
+        enum:
+        - bfi
+        - fpwb
+        - afi
+        example: fpwb
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileUpdateBulkRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUpdateData'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUpdateAttributes'
+      id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      type:
+        enum:
+        - helicopter_file_update
+        - helicopter_file
+        example: helicopter_file_update
+        type: string
+    required:
+    - attributes
+    - id
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileUploadAttributes:
+    properties:
+      content_type:
+        example: application/pdf
+        type: string
+      name:
+        example: Before Flight Checklist.pdf
+        type: string
+      size_bytes:
+        example: 1024
+        minimum: 0
+        type: integer
+    required:
+    - content_type
+    - name
+    - size_bytes
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileUploadBulkRequest:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUploadData'
+        minItems: 1
+        type: array
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterFileUploadData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUploadAttributes'
+      type:
+        enum:
+        - helicopter_file_upload
+        example: helicopter_file_upload
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterUpdateAttributes:
+    properties:
+      aog:
+        example: false
+        type: boolean
+      aog_reason:
+        example: Main rotor gearbox fault
+        type: string
+      consumption_lt_min:
+        example: 4.1
+        type: number
+      designation:
+        example: OE-XHZ
+        type: string
+      dry:
+        example: false
+        type: boolean
+      engine_1:
+        example: TM
+        type: string
+      engine_2:
+        example: TM
+        type: string
+      file_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90
+        type: string
+      identifier:
+        example: ABC
+        type: string
+      igb:
+        example: false
+        type: boolean
+      is_active:
+        example: true
+        type: boolean
+      lh:
+        example: true
+        type: boolean
+      mgb:
+        example: true
+        type: boolean
+      note:
+        example: Primary HEMS helicopter
+        type: string
+      nr1:
+        example: true
+        type: boolean
+      nr2:
+        example: true
+        type: boolean
+      rh:
+        example: true
+        type: boolean
+      sortkey:
+        example: 10
+        type: integer
+      tgb:
+        example: true
+        type: boolean
+      type:
+        example: EC-135
+        type: string
+      utc_offset:
+        example: -1
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - helicopter_update
+        - helicopter
+        example: helicopter_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.HelicopterUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.LastFlightsInspectionCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionUpsertAttributes'
+      type:
+        enum:
+        - last_flights_inspection_create
+        - last_flights_inspection
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.LastFlightsInspectionCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteAttributes:
+    properties:
+      flight_inspection_id:
+        type: string
+    required:
+    - flight_inspection_id
+    type: object
+  wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteAttributes'
+      type:
+        enum:
+        - last_flights_inspection_delete
+        - last_flights_inspection
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.LastFlightsInspectionUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionUpsertAttributes'
+      type:
+        enum:
+        - last_flights_inspection_update
+        - last_flights_inspection
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.LastFlightsInspectionUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.LastFlightsInspectionUpsertAttributes:
+    properties:
+      file_checklist:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem'
+        type: array
+      flight_inspection_id:
+        type: string
+      hydraulic_lh_checked:
+        type: string
+      hydraulic_rh_checked:
+        type: string
+      note:
+        type: string
+      oil_engine_nr1_checked:
+        type: string
+      oil_engine_nr2_checked:
+        type: string
+      oil_transmission_igb_checked:
+        type: string
+      oil_transmission_mgb_checked:
+        type: string
+      oil_transmission_tgb_checked:
+        type: string
+    required:
+    - flight_inspection_id
+    type: object
+  wucher_internal_transport_http_dto_request.MCFCompleteAttributes:
+    properties:
+      af_hours:
+        example: "1245.3"
+        type: string
+      date:
+        example: "2026-06-17"
+        type: string
+      landing_count:
+        example: 3
+        type: integer
+      notes:
+        example: Vibration within limits after check flight
+        type: string
+      result:
+        enum:
+        - passed
+        - failed
+        example: passed
+        type: string
+      sign:
+        example: true
+        type: boolean
+      utc_time:
+        example: "2026-06-17T08:30:00Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.MCFCompleteData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MCFCompleteAttributes'
+      type:
+        enum:
+        - mcf_complete
+        - mcf_sign
+        - mcf
+        example: mcf_sign
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.MCFCompleteRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MCFCompleteData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.MCFSetAttributes:
+    properties:
+      active:
+        example: true
+        type: boolean
+      af_hours:
+        example: "1245.3"
+        type: string
+      date:
+        example: "2026-06-17"
+        type: string
+      flight_id:
+        description: FlightID — OPTIONAL flight this check flight is performed on
+          (on activate).
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      landing_count:
+        example: 3
+        type: integer
+      notes:
+        example: MCF required after engine mount work
+        type: string
+      result:
+        enum:
+        - passed
+        - failed
+        example: passed
+        type: string
+      utc_time:
+        example: "2026-06-17T08:30:00Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.MCFSetData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MCFSetAttributes'
+      type:
+        enum:
+        - mcf_set
+        - mcf
+        example: mcf_set
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.MCFSetRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MCFSetData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.MasterSettingsCreateAttributes:
+    properties:
+      company_name:
+        example: Wucher
+        type: string
+      cover_file_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      logo_file_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      subtitle:
+        example: Flight operations platform
+        type: string
+      title:
+        example: Welcome to Wucher
+        type: string
+    required:
+    - company_name
+    type: object
+  wucher_internal_transport_http_dto_request.MasterSettingsCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsCreateAttributes'
+      type:
+        enum:
+        - master_settings_create
+        - master_settings
+        example: master_settings_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.MasterSettingsCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertAttributes:
+    properties:
+      MS_ENTRA_AUTHORITY:
+        example: https://login.microsoftonline.com/
+        type: string
+      MS_ENTRA_CLIENT_ID:
+        example: your-client-id
+        type: string
+      MS_ENTRA_CLIENT_SECRET:
+        example: '********'
+        type: string
+      MS_ENTRA_REDIRECT_URL:
+        example: https://example.com/api/v1/auth/microsoft/callback
+        type: string
+      MS_ENTRA_SCOPES:
+        example: openid,profile,email
+        type: string
+      MS_ENTRA_TENANT_ID:
+        example: your-tenant-id
+        type: string
+    required:
+    - MS_ENTRA_AUTHORITY
+    - MS_ENTRA_CLIENT_ID
+    - MS_ENTRA_REDIRECT_URL
+    - MS_ENTRA_SCOPES
+    - MS_ENTRA_TENANT_ID
+    type: object
+  wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertAttributes'
+      type:
+        enum:
+        - master_settings_microsoft_entra_upsert
+        - master_settings
+        example: master_settings_microsoft_entra_upsert
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.MasterSettingsUpdateAttributes:
+    properties:
+      company_name:
+        example: Wucher
+        type: string
+      cover_file_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      logo_file_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      subtitle:
+        example: Flight operations platform
+        type: string
+      title:
+        example: Welcome to Wucher
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.MasterSettingsUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsUpdateAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        enum:
+        - master_settings_update
+        - master_settings
+        example: master_settings_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.MasterSettingsUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.MissionCreateAttributes:
+    properties:
+      files:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.MissionFileInput'
+        type: array
+      flight_id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      note:
+        example: Mission note
+        type: string
+      subtype_id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a99
+        type: string
+      type:
+        example: HEMS
+        type: string
+    required:
+    - flight_id
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.MissionCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MissionCreateAttributes'
+      type:
+        enum:
+        - mission_create
+        - mission
+        example: mission_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.MissionCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MissionCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.MissionFileInput:
+    properties:
+      name:
+        example: mission-brief.pdf
+        type: string
+      upload_intent_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.MissionTypeCreateAttributes:
+    properties:
+      code_type:
+        example: HEMS
+        type: string
+      name:
+        example: HEMS
+        type: string
+    required:
+    - code_type
+    - name
+    type: object
+  wucher_internal_transport_http_dto_request.MissionTypeCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MissionTypeCreateAttributes'
+      type:
+        enum:
+        - mission_type_create
+        - mission_type
+        example: mission_type_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.MissionTypeCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MissionTypeCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.MissionUpdateAttributes:
+    properties:
+      files:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.MissionFileInput'
+        type: array
+      note:
+        example: Mission note
+        type: string
+      subtype_id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a99
+        type: string
+      type:
+        example: SPO
+        type: string
+    required:
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.MissionUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MissionUpdateAttributes'
+      type:
+        enum:
+        - mission_update
+        - mission
+        example: mission_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.MissionUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.MissionUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.OtherPersonAttributesInput:
+    properties:
+      email:
+        example: guest@example.com
+        type: string
+      mobile_phone:
+        example: +43-1234
+        type: string
+      name:
+        example: Guest Person
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.OtherPersonRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.OtherPersonRequestData'
+    type: object
+  wucher_internal_transport_http_dto_request.OtherPersonRequestData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.OtherPersonAttributesInput'
+      type:
+        example: other_person
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcBeforeInspectionAttributes:
+    properties:
+      file_checklist:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem'
+        type: array
+      fuel_added_amount:
+        type: number
+      fuel_amount:
+        type: number
+      fuel_unit:
+        type: string
+      hydraulic_lh_checked:
+        type: boolean
+      hydraulic_rh_checked:
+        type: boolean
+      note:
+        type: string
+      oil_engine_nr1_checked:
+        type: boolean
+      oil_engine_nr2_checked:
+        type: boolean
+      oil_transmission_igb_checked:
+        type: boolean
+      oil_transmission_mgb_checked:
+        type: boolean
+      oil_transmission_tgb_checked:
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcCreateAttributes:
+    properties:
+      flight_id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      helicopter_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcInspectionCreateAttributes'
+    required:
+    - flight_id
+    - helicopter_id
+    - inspection
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcCreateAttributes'
+      type:
+        enum:
+        - reserve_ac_create
+        - reserve_ac
+        example: reserve_ac_create
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcDeleteData:
+    properties:
+      id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+    required:
+    - id
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcDeleteRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcDeleteData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem:
+    properties:
+      helicopter_file_id:
+        example: 019d7000-aaaa-7bbb-8ccc-111111111111
+        type: string
+      is_done:
+        example: true
+        type: boolean
+    required:
+    - helicopter_file_id
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcFleetStatusFileAttributes:
+    properties:
+      file_checklist:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcInspectionCreateAttributes:
+    properties:
+      before:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcBeforeInspectionAttributes'
+      fleet_status_file:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFleetStatusFileAttributes'
+      inspection_date:
+        example: "2026-04-15"
+        type: string
+      prepare:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcPrepareInspectionAttributes'
+    required:
+    - before
+    - inspection_date
+    - prepare
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcInspectionUpdateAttributes:
+    properties:
+      before:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcBeforeInspectionAttributes'
+      inspection_date:
+        example: "2026-04-15"
+        type: string
+      prepare:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcPrepareInspectionAttributes'
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcPrepareInspectionAttributes:
+    properties:
+      file_checklist:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcFileChecklistItem'
+        type: array
+      notam_briefing:
+        type: boolean
+      operational_flight_plan:
+        type: boolean
+      weather_briefing:
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcUpdateAttributes:
+    properties:
+      flight_id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      helicopter_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcInspectionUpdateAttributes'
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcUpdateAttributes'
+      id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      type:
+        enum:
+        - reserve_ac_update
+        - reserve_ac
+        example: reserve_ac_update
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.ReserveAcUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.TakeoverBaseRef:
+    properties:
+      id:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.TakeoverCreateAttributes:
+    properties:
+      base_id:
+        type: string
+      duty_date:
+        type: string
+      edited_template_file_ids:
+        items:
+          type: string
+        type: array
+      files:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateFileInput'
+        type: array
+      helicopter_id:
+        type: string
+      inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcInspectionCreateAttributes'
+      notes:
+        type: string
+      roster_detail:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterDetailsInput'
+    required:
+    - duty_date
+    type: object
+  wucher_internal_transport_http_dto_request.TakeoverCreateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateAttributes'
+      type:
+        enum:
+        - takeover_create
+        - takeover
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.TakeoverCreateFileInput:
+    properties:
+      file_id:
+        example: 019e8713-aa19-7fb7-a510-a0332dc69697
+        type: string
+      name:
+        example: takeover-report.pdf
+        type: string
+      upload_intent_uuid:
+        example: 019e8713-aa19-7fb7-a510-a0332dc69697
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.TakeoverCreateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_request.TakeoverRosterCrewInput:
+    properties:
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.TakeoverRosterDetailsInput:
+    properties:
+      doctor:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterCrewInput'
+        type: array
+      helper:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterCrewInput'
+        type: array
+      other_person:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterOtherPersonInput'
+        type: array
+      pilot:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterPilotInput'
+        type: array
+      rescuer:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterCrewInput'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_request.TakeoverRosterOtherPersonInput:
+    properties:
+      email:
+        example: guest@example.com
+        type: string
+      mobile_phone:
+        example: +43-1234
+        type: string
+      name:
+        example: Guest Person
+        type: string
+      other_person_id:
+        description: OtherPersonID — OPTIONAL master person id to reuse (from GET
+          /contact/other).
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_request.TakeoverRosterPilotInput:
+    properties:
+      co_pilot:
+        type: boolean
+      crew_type:
+        enum:
+        - main
+        - additional
+        example: main
+        type: string
+      examiner:
+        type: boolean
+      flight_instructor:
+        type: boolean
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      line_checker:
+        type: boolean
+      supervisor:
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_request.TakeoverUpdateAttributes:
+    properties:
+      base_id:
+        type: string
+      bases:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverBaseRef'
+      duty_date:
+        type: string
+      files:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateFileInput'
+        type: array
+      files_add:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateFileInput'
+        type: array
+      files_remove:
+        items:
+          type: string
+        type: array
+      files_replace:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateFileInput'
+        type: array
+      helicopter_id:
+        type: string
+      inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcInspectionCreateAttributes'
+      notes:
+        type: string
+      roster_detail:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterDetailsInput'
+      roster_details:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverRosterDetailsInput'
+    type: object
+  wucher_internal_transport_http_dto_request.TakeoverUpdateData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverUpdateAttributes'
+      id:
+        type: string
+      type:
+        enum:
+        - takeover_update
+        - takeover
+        type: string
+    required:
+    - attributes
+    - type
+    type: object
+  wucher_internal_transport_http_dto_request.TakeoverUpdateRequest:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverUpdateData'
+    required:
+    - data
+    type: object
+  wucher_internal_transport_http_dto_response.ActionSignoffAttributes:
+    properties:
+      created_at:
+        example: "2026-06-16T03:04:05Z"
+        type: string
+      flight_id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      helicopter_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      signed:
+        description: Signed — true once checked; gates the maintenance release form.
+        example: false
+        type: boolean
+      signed_at:
+        description: SignedAt / SignedBy — when/who signed; empty until signed.
+        example: "2026-06-16T03:04:05Z"
+        type: string
+      signed_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      signed_by_name:
+        description: SignedByName / SignedByShort — resolved display name + 3-letter
+          short of the signer.
+        example: John Doe
+        type: string
+      signed_by_short:
+        example: JDO
+        type: string
+      updated_at:
+        example: "2026-06-16T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.ActionSignoffResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.ActionSignoffAttributes'
+      id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      type:
+        example: action_signoff
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.ActionSignoffResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.ActionSignoffResource'
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistAttributes:
+    properties:
+      bases:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistBaseInfo'
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      items:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResource'
+        type: array
+      position:
+        example: 1
+        type: integer
+      scope_code:
+        example: TU
+        type: string
+      scope_code_de:
+        example: DI
+        type: string
+      title:
+        example: Monday Checklist
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupAttributes:
+    properties:
+      bases:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.AirRescuerChecklistBaseInfo'
+      tabs:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistTabResource'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupAttributes'
+      id:
+        example: base-018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: air_rescuer_checklist_group
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistBulkResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResource'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistCATChecklistSummary:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      position:
+        example: 1
+        type: integer
+      title:
+        example: Cockpit Flugretter
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistCATGroup:
+    properties:
+      checklists:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistCATChecklistSummary'
+        type: array
+      scope_code:
+        example: DA
+        type: string
+      scope_code_de:
+        example: TA
+        type: string
+      scope_code_name:
+        example: Daily
+        type: string
+      scope_code_name_de:
+        example: Taeglich
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 8
+            type: integer
+          records_total:
+            example: 8
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistBaseGroupResource'
+        type: array
+      meta:
+        properties:
+          total_bases:
+            example: 8
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistItemAttributes:
+    properties:
+      checklist_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: Check radio
+        type: string
+      position:
+        example: 1
+        type: integer
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistItemBulkResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemData'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistItemData:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: air_rescuer_checklist_item
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResource:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: Oxygen supply check
+        type: string
+      position:
+        example: 1
+        type: integer
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemData'
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: air_rescuer_checklist
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResource'
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistTabChecklistDetail:
+    properties:
+      checklist_items:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResource'
+        type: array
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      position:
+        example: 1
+        type: integer
+      title:
+        example: Monday Checklist
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.AirRescuerChecklistTabResource:
+    properties:
+      checklists:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistTabChecklistDetail'
+        type: array
+      groups:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistCATGroup'
+        type: array
+      scope_code:
+        example: DA
+        type: string
+      scope_code_de:
+        example: TA
+        type: string
+      scope_code_name:
+        example: Daily
+        type: string
+      scope_code_name_de:
+        example: Taeglich
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.ComplaintAttributes:
+    properties:
+      action_signed:
+        example: true
+        type: boolean
+      action_signed_at:
+        example: "2026-06-15T03:04:05Z"
+        type: string
+      action_signed_by_name:
+        example: John Doe
+        type: string
+      action_signed_by_short:
+        example: JDO
+        type: string
+      action_taken:
+        example: tightened mount
+        type: string
+      aircraft_hours_at_fix:
+        example: "1250.1"
+        type: string
+      aircraft_hours_at_report:
+        example: "1245.3"
+        type: string
+      created_at:
+        example: "2026-06-15T03:04:05Z"
+        type: string
+      description:
+        example: Engine 2 N2 vibration intermittent during cruise above 110 KIAS
+        type: string
+      flight_id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      helicopter:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusHelicopter'
+      helicopter_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      mel:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintMEL'
+      nsr:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintNSR'
+      reported_at:
+        example: "2026-06-15T03:04:05Z"
+        type: string
+      reported_by:
+        example: John Doe
+        type: string
+      reported_by_short:
+        example: JDO
+        type: string
+      status:
+        enum:
+        - active_non_mel
+        - active_mel
+        - serviced
+        example: active_mel
+        type: string
+      updated_at:
+        example: "2026-06-15T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.ComplaintGroupedDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 1
+            type: integer
+          records_total:
+            example: 1
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 1
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupAttributes:
+    properties:
+      complaints:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintResource'
+        type: array
+      helicopter:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusHelicopter'
+    type: object
+  wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintHelicopterGroupAttributes'
+      type:
+        example: complaint_helicopter_group
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.ComplaintMEL:
+    properties:
+      classified_at:
+        description: ClassifiedAt / ClassifiedByName / ClassifiedByShort — when/who
+          classified the MEL.
+        example: "2026-06-15T03:04:05Z"
+        type: string
+      classified_by_name:
+        example: John Doe
+        type: string
+      classified_by_short:
+        example: JDO
+        type: string
+      deadline:
+        description: Deadline — grace deadline; after this the aircraft is AOG. null
+          for NON-MEL.
+        example: "2026-06-18T03:04:05Z"
+        type: string
+      severity:
+        description: 'Severity — MEL class: 0=NON-MEL, 1=A, 2=B, 3=C, 4=D. Always
+          set (classification is required at creation).'
+        enum:
+        - 0
+        - 1
+        - 2
+        - 3
+        - 4
+        example: 2
+        type: integer
+      severity_label:
+        description: SeverityLabel — human label of the severity (NON-MEL/A/B/C/D).
+        example: B
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.ComplaintNSR:
+    properties:
+      decided_at:
+        description: DecidedAt / DecidedByName / DecidedByShort — when/who decided
+          NSR (may differ from the reporter).
+        example: "2026-06-15T03:04:05Z"
+        type: string
+      decided_by_name:
+        example: John Doe
+        type: string
+      decided_by_short:
+        example: JDO
+        type: string
+      is_nsr:
+        description: 'IsNSR — Non-Safety Release: true = aircraft released to fly
+          despite the open defect.'
+        example: false
+        type: boolean
+      reason:
+        description: Reason — optional justification for the NSR decision.
+        example: not required
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.ComplaintResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintAttributes'
+      id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      type:
+        example: complaint
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.ComplaintResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintResource'
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterAttributes:
+    properties:
+      bases:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseInfo'
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      duty_date:
+        example: "2026-03-16"
+        type: string
+      flight_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      helicopter:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterHelicopterSummary'
+      roster_detail:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterDetailsResponse'
+      shift_time:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftTime'
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterBaseGroupAttributes:
+    properties:
+      bases:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseInfo'
+      rosters:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterGroupRoster'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterBaseGroupResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseGroupAttributes'
+      type:
+        example: hems_base_roster_group
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterBaseInfo:
+    properties:
+      base_abbreviation:
+        example: G1
+        type: string
+      base_name:
+        example: Gallus 1 - Zurs Lech
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      shift_time:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftTime'
+      type:
+        example: hems
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterCrew:
+    properties:
+      email:
+        example: doctor@example.com
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      mobile_phone:
+        example: +43-1234
+        type: string
+      name:
+        example: Hunter Wolfgang
+        type: string
+      role:
+        example: doctor
+        type: string
+      shift_date:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftDate'
+      shift_time:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftTime'
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteAttributes:
+    properties:
+      deleted:
+        example: true
+        type: boolean
+      deleted_count:
+        example: 1
+        type: integer
+      deleted_items:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterDeletedCrewItem'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteAttributes'
+      type:
+        example: duty_roster_crew_delete
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteResource'
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterDeletedCrewItem:
+    properties:
+      crew_type:
+        example: main
+        type: string
+      date_end:
+        example: "2026-03-22"
+        type: string
+      date_start:
+        example: "2026-03-20"
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: Pilot One
+        type: string
+      role_code:
+        example: pilot
+        type: string
+      roster_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      user_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterDetailsResponse:
+    properties:
+      doctor:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrew'
+        type: array
+      helper:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrew'
+        type: array
+      other_person:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrew'
+        type: array
+      pilot:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterPilotCrew'
+        type: array
+      rescuer:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrew'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterGroupRoster:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      duty_date:
+        example: "2026-03-16"
+        type: string
+      flight_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      helicopter:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterHelicopterSummary'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      roster_detail:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterDetailsResponse'
+      shift_time:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftTime'
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterGroupedDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseGroupResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 8
+            type: integer
+          records_total:
+            example: 8
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterGroupedListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseGroupResource'
+        type: array
+      meta:
+        properties:
+          from:
+            example: "2026-03-16"
+            type: string
+          to:
+            example: "2026-04-15"
+            type: string
+          total_bases:
+            example: 8
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterHelicopterSummary:
+    properties:
+      designation:
+        example: OE-XHZ
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      identifier:
+        example: "1234"
+        type: string
+      type:
+        example: EC-135
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterPilotCrew:
+    properties:
+      co_pilot:
+        type: boolean
+      crew_type:
+        example: main
+        type: string
+      email:
+        example: pilot@example.com
+        type: string
+      examiner:
+        type: boolean
+      flight_instructor:
+        type: boolean
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      line_checker:
+        type: boolean
+      mobile_phone:
+        example: +43-1234
+        type: string
+      name:
+        example: Hunter Wolfgang
+        type: string
+      role:
+        example: pilot
+        type: string
+      shift_date:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterShiftDate'
+      supervisor:
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: duty_roster
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterResource'
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterShiftDate:
+    properties:
+      date_end:
+        example: "2026-03-16"
+        type: string
+      date_start:
+        example: "2026-03-16"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.DutyRosterShiftTime:
+    properties:
+      shift_end:
+        example: "21:00"
+        type: string
+      shift_start:
+        example: "06:00"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.EASAReleaseAttributes:
+    properties:
+      complaint_id:
+        example: 019d6774-1111-7fba-9ef4-3795c0da8a13
+        type: string
+      created_at:
+        example: "2026-06-16T03:04:05Z"
+        type: string
+      easa_ac_hours:
+        example: "1245.3"
+        type: string
+      easa_date:
+        example: "2026-06-16"
+        type: string
+      easa_location:
+        example: LOWI
+        type: string
+      easa_maint_manual_rev_airframe:
+        example: Rev 12
+        type: string
+      easa_maint_manual_rev_engine:
+        example: Rev 8
+        type: string
+      easa_permit_no:
+        example: 145.A.50
+        type: string
+      easa_signer_id:
+        description: EASASignerID — contact id (UUIDv7) of the signer/technician.
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      easa_signer_name:
+        description: EASASignerName / EASASignerShort — resolved display name + 3-letter
+          short of the signer contact.
+        example: John Doe
+        type: string
+      easa_signer_short:
+        example: JDO
+        type: string
+      easa_wo_no:
+        example: WO-2026-001
+        type: string
+      flight_id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      helicopter_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      is_signed:
+        description: IsSigned — true once the release is signed (Release to Service);
+          then the complaint becomes fixed.
+        example: false
+        type: boolean
+      missing_sign_fields:
+        description: MissingSignFields — required fields still empty; must all be
+          filled before it can be signed.
+        items:
+          type: string
+        type: array
+      signed_at:
+        description: SignedAt / SignedBy — when/who signed; empty until signed.
+        example: "2026-06-16T03:04:05Z"
+        type: string
+      signed_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      updated_at:
+        example: "2026-06-16T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.EASAReleaseDeleteResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              deleted:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: easa_release_delete
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.EASAReleaseListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResource'
+        type: array
+      meta:
+        properties:
+          total:
+            example: 1
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.EASAReleaseResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseAttributes'
+      id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      type:
+        example: easa_release
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.EASAReleaseResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResource'
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerActionBulkError:
+    properties:
+      code:
+        example: FILE_MANAGER_VALIDATION_FAILED
+        type: string
+      detail:
+        example: duplicate name in target folder
+        type: string
+      error_code:
+        example: "4222111"
+        type: string
+      status:
+        example: 422
+        type: integer
+      title:
+        example: Validation error
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerActionLocation:
+    properties:
+      folder_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerAttachmentListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerAttachmentResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerAttachmentAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: file_manager_attachment
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerAttachmentResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentResource'
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerBreadcrumbItem:
+    properties:
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: operations
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileBulkError:
+    properties:
+      code:
+        example: FILE_MANAGER_VALIDATION_FAILED
+        type: string
+      detail:
+        example: duplicate name in target folder
+        type: string
+      error_code:
+        example: "4222111"
+        type: string
+      status:
+        example: 422
+        type: integer
+      title:
+        example: Validation error
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileBulkItem:
+    properties:
+      error:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkError'
+      index:
+        example: 0
+        type: integer
+      message:
+        example: created
+        type: string
+      resource:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileResource'
+      success:
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkItem'
+        type: array
+      meta:
+        properties:
+          failed:
+            example: 1
+            type: integer
+          partial_success:
+            example: true
+            type: boolean
+          success:
+            example: 2
+            type: integer
+          total:
+            example: 3
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkItem:
+    properties:
+      error:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkError'
+      index:
+        example: 0
+        type: integer
+      resource:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadResource'
+      success:
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkItem'
+        type: array
+      meta:
+        properties:
+          failed:
+            example: 1
+            type: integer
+          partial_success:
+            example: true
+            type: boolean
+          success:
+            example: 2
+            type: integer
+          total:
+            example: 3
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadResource:
+    properties:
+      attributes:
+        properties:
+          status:
+            example: canceled
+            type: string
+        type: object
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: file_manager_file_cancel_upload_result
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileDetailResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileDetailAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: file_manager_file
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileDetailResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileDetailResource'
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: file_manager_file
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileAttributes'
+          id:
+            example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+            type: string
+          type:
+            example: file_manager_file
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkItem:
+    properties:
+      error:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkError'
+      index:
+        example: 0
+        type: integer
+      resource:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentResource'
+      success:
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkItem'
+        type: array
+      meta:
+        properties:
+          failed:
+            example: 1
+            type: integer
+          partial_success:
+            example: true
+            type: boolean
+          success:
+            example: 2
+            type: integer
+          total:
+            example: 3
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileUploadIntentAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: file_manager_file_upload_intent
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionData:
+    properties:
+      access_token:
+        example: eyJhbGciOiJIUzI1NiIs...
+        type: string
+      access_token_ttl:
+        description: |-
+          AccessTokenTTL is the access token's absolute expiry time, in epoch
+          milliseconds (equal to the JWT exp claim), as required by WOPI/Collabora.
+        example: 1782971996000
+        type: integer
+      collabora_action:
+        example: https://collabora.example.com/browser/123?WOPISrc=...
+        type: string
+      file_id:
+        example: 019f0386-0a00-7a4a-a2d8-30afc0e0c3ad
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionData'
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFolderDetailResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFolderDetailAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: file_manager_folder
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFolderDetailResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderDetailResource'
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFolderResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFolderAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: file_manager_folder
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerFolderResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderResource'
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkItem:
+    properties:
+      error:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerActionBulkError'
+      index:
+        example: 0
+        type: integer
+      resource:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeResultResource'
+      success:
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkItem'
+        type: array
+      meta:
+        properties:
+          failed:
+            example: 1
+            type: integer
+          partial_success:
+            example: true
+            type: boolean
+          success:
+            example: 2
+            type: integer
+          total:
+            example: 3
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerMoveNodeResultAttributes:
+    properties:
+      location:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerActionLocation'
+      node_type:
+        example: folder
+        type: string
+      status:
+        example: moved
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerMoveNodeResultResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeResultAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: file_manager_move_result
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerNodeAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      download_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=...
+        type: string
+      extension:
+        example: pdf
+        type: string
+      mime_type:
+        example: application/pdf
+        type: string
+      name:
+        example: operations
+        type: string
+      node_type:
+        example: folder
+        type: string
+      parent_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      path_cache:
+        example: /root/operations
+        type: string
+      size_bytes:
+        example: 1024
+        type: integer
+      status:
+        example: ready
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerNodeListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerNodeResource'
+        type: array
+      meta:
+        properties:
+          breadcrumb:
+            items:
+              $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerBreadcrumbItem'
+            type: array
+          files:
+            example: 8
+            type: integer
+          folders:
+            example: 4
+            type: integer
+          is_root:
+            example: true
+            type: boolean
+          parent_uuid:
+            example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+            type: string
+          total:
+            example: 12
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerNodeResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerNodeAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: file_manager_node
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerPurgeNodeBulkItem:
+    properties:
+      error:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerActionBulkError'
+      index:
+        example: 0
+        type: integer
+      resource:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerPurgeNodeResultResource'
+      success:
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerPurgeNodeBulkResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerPurgeNodeBulkItem'
+        type: array
+      meta:
+        properties:
+          failed:
+            example: 1
+            type: integer
+          partial_success:
+            example: true
+            type: boolean
+          success:
+            example: 2
+            type: integer
+          total:
+            example: 3
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerPurgeNodeResultAttributes:
+    properties:
+      node_type:
+        example: folder
+        type: string
+      status:
+        example: purged
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerPurgeNodeResultResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerPurgeNodeResultAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: file_manager_purge_result
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerTrashListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerTrashNodeResource'
+        type: array
+      meta:
+        properties:
+          files:
+            example: 70
+            type: integer
+          folders:
+            example: 50
+            type: integer
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerTrashNodeAttributes:
+    properties:
+      created_at:
+        example: "2026-03-31T08:52:03Z"
+        type: string
+      download_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=...
+        type: string
+      extension:
+        example: pdf
+        type: string
+      mime_type:
+        example: application/pdf
+        type: string
+      name:
+        example: Documents
+        type: string
+      node_type:
+        example: folder
+        type: string
+      path_cache:
+        example: /Documents
+        type: string
+      size_bytes:
+        example: 123456
+        type: integer
+      trashed_at:
+        example: "2026-04-01T10:00:00Z"
+        type: string
+      updated_at:
+        example: "2026-03-31T08:52:03Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FileManagerTrashNodeResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerTrashNodeAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: file_manager_trash_node
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FleetHistoryEntry:
+    properties:
+      action:
+        example: easa_signed
+        type: string
+      actor:
+        example: 019e91e6-2908-7f37-93e6-015ed1b7587d
+        type: string
+      actor_name:
+        example: John Doe
+        type: string
+      at:
+        example: "2026-06-17T10:15:00Z"
+        type: string
+      entity_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      entity_type:
+        example: easa_release
+        type: string
+      message:
+        example: Release to Service (EASA signed)
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FleetHistoryListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetHistoryEntry'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 1
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FleetStatusAttributes:
+    properties:
+      complaints:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusComplaint'
+        type: array
+      created_at:
+        example: "2026-05-29T07:43:06Z"
+        type: string
+      created_by:
+        example: John Doe
+        type: string
+      easa_release:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusEASARelease'
+      files:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusFile'
+        type: array
+      helicopter:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusHelicopter'
+      maintenance_schedules:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes'
+        type: array
+      mcf:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusMCF'
+      serviced_at:
+        example: "2026-05-29T07:43:06Z"
+        type: string
+      status:
+        enum:
+        - active
+        - serviced
+        example: active
+        type: string
+      summary:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusSummary'
+      updated_at:
+        example: "2026-05-29T07:43:06Z"
+        type: string
+      updated_by:
+        example: John Doe
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FleetStatusDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 20
+            type: integer
+          records_total:
+            example: 100
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FleetStatusDeleteResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              deleted:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: fleet_status_delete
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FleetStatusFile:
+    properties:
+      category:
+        example: wb
+        type: string
+      download_url:
+        example: https://storage.example.com/fleet/wb.pdf?X-Amz-Signature=abc123
+        type: string
+      file_attachment_id:
+        example: 019d7000-aaaa-7bbb-8ccc-111111111111
+        type: string
+      id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      is_mandatory:
+        example: true
+        type: boolean
+      name:
+        example: weight_balance.pdf
+        type: string
+      size_bytes:
+        example: 1024000
+        type: integer
+      thumbnail_download_url:
+        example: https://storage.example.com/fleet/wb.thumb.jpg?X-Amz-Signature=abc123
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FleetStatusListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 100
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FleetStatusMarkServicedResponse:
+    properties:
+      data:
+        properties:
+          attributes:
+            properties:
+              serviced:
+                example: true
+                type: boolean
+            type: object
+          type:
+            example: fleet_status_mark_serviced
+            type: string
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FleetStatusResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusAttributes'
+      id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      type:
+        example: fleet_status
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FleetStatusResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResource'
+    type: object
+  wucher_internal_transport_http_dto_response.FlightAttributes:
+    properties:
+      code:
+        example: M-062226-001
+        type: string
+      created_at:
+        example: "2026-04-14T08:00:00Z"
+        type: string
+      created_by:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.UserRef'
+      date:
+        example: "2026-04-14"
+        type: string
+      deleted_at:
+        example: "2026-04-14T08:00:00Z"
+        type: string
+      deleted_by:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.UserRef'
+      draft:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDraftGroup'
+        type: array
+      mission_id:
+        example: 019e9640-f7af-7940-80e8-1e9a83013afb
+        type: string
+      status:
+        example: draft
+        type: string
+      steps:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightStepItem'
+        type: array
+      takeover:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightTakeoverSummary'
+      total_draft:
+        example: 6
+        type: integer
+      updated_at:
+        example: "2026-04-14T08:00:00Z"
+        type: string
+      updated_by:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.UserRef'
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDailyInspectionSummary:
+    properties:
+      date:
+        example: 17.04.2026
+        type: string
+      id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      name:
+        example: Ganahl Stefan
+        type: string
+      short_name:
+        example: GAN
+        type: string
+      utc_time:
+        example: "10:57"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataAttributes:
+    properties:
+      co_pilot:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataCoPilotRef'
+      created_at:
+        example: "2026-04-20T08:00:00Z"
+        type: string
+      created_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      customer_name:
+        example: Air Service
+        type: string
+      delivery_note_number:
+        example: DN-1001
+        type: string
+      engine:
+        example: PW207D1
+        type: string
+      flight_duration_seconds:
+        example: 4500
+        type: integer
+      flight_landing:
+        example: "2026-04-20T09:15:00Z"
+        type: string
+      flight_plan_distance:
+        example: 120.5
+        type: number
+      flight_plan_time_seconds:
+        example: 4200
+        type: integer
+      flight_plan_true_course:
+        example: 182.3
+        type: number
+      flight_positioning:
+        example: false
+        type: boolean
+      flight_red_seconds:
+        example: 300
+        type: integer
+      flight_take_off:
+        example: "2026-04-20T08:00:00Z"
+        type: string
+      from:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataLocationRef'
+      fuel_after_flight:
+        example: 280
+        type: number
+      fuel_before_flight:
+        example: 420
+        type: number
+      fuel_planning:
+        example: 390
+        type: number
+      fuel_upload:
+        example: 100
+        type: number
+      hec:
+        allOf:
+        - $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHECDetails'
+        x-note: Only returned for SPO missions
+      heslo:
+        allOf:
+        - $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHESLODetails'
+        x-note: Only returned for SPO missions
+      hook_releases:
+        example: 0
+        type: integer
+      landing_count:
+        example: 1
+        type: integer
+      logging:
+        allOf:
+        - $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOLoggingDetails'
+        x-note: Only returned for SPO missions
+      max_n1:
+        example: 97.5
+        type: number
+      max_n2:
+        example: 98.1
+        type: number
+      mission:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataMissionRef'
+      other_information:
+        type: string
+      pax_count:
+        example: 4
+        type: integer
+      roster_details:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterDetailsResponse'
+      rotor_brake_cycle:
+        example: 1
+        type: integer
+      status:
+        example: in_progress
+        type: string
+      ticket_no:
+        example: TKT-001
+        type: string
+      to:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataLocationRef'
+      updated_at:
+        example: "2026-04-20T08:00:00Z"
+        type: string
+      updated_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataCoPilotRef:
+    properties:
+      email:
+        example: john.doe@example.com
+        type: string
+      first_name:
+        example: John
+        type: string
+      id:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      last_name:
+        example: Doe
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 1
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataLocationRef:
+    properties:
+      code:
+        example: WIII
+        type: string
+      id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      label:
+        example: WIII
+        type: string
+      name:
+        example: General Hospital
+        type: string
+      type:
+        example: icao
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataMissionRef:
+    properties:
+      id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      type:
+        example: HEMS
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataAttributes'
+      id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      type:
+        example: flight_data
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataResource'
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataSPOHECDetails:
+    properties:
+      flights:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHECFlight'
+        type: array
+      loads:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHECLoad'
+        type: array
+      slings:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHECSling'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataSPOHECFlight:
+    properties:
+      equipment_id:
+        description: 'Facility category: hec-rope-label.'
+        type: string
+      equipment_name:
+        type: string
+      hec_cycle:
+        type: integer
+      id:
+        type: string
+      rot:
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataSPOHECLoad:
+    properties:
+      id:
+        type: string
+      load_category:
+        description: Weight band for the HEC load, e.g. "bis 199 kg", "200-600 kg",
+          "600-800 kg", "800-1000 kg".
+        example: 200-600 kg
+        type: string
+      quantity:
+        example: 3
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataSPOHECSling:
+    properties:
+      id:
+        type: string
+      sling_id:
+        description: 'Facility category: hec-rope-length.'
+        type: string
+      sling_name:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataSPOHESLODetails:
+    properties:
+      flights:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHESLOFlight'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataSPOHESLOFlight:
+    properties:
+      heslo_rope_label_id:
+        description: 'Facility category: heslo-rope-label.'
+        type: string
+      heslo_rope_label_name:
+        type: string
+      id:
+        type: string
+      rot:
+        type: integer
+      slings:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOHESLOSling'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataSPOHESLOSling:
+    properties:
+      id:
+        type: string
+      sling_id:
+        description: 'Facility category: heslo-rope-length.'
+        type: string
+      sling_name:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataSPOLoggingDetails:
+    properties:
+      slings:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataSPOLoggingSling'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDataSPOLoggingSling:
+    properties:
+      id:
+        type: string
+      sling_id:
+        description: 'Facility category: heslo-hook.'
+        type: string
+      sling_name:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDraftGroup:
+    properties:
+      items:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDraftItem'
+        type: array
+      type:
+        example: HEMS
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightDraftItem:
+    properties:
+      flight_data_id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a55
+        type: string
+      id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      status:
+        example: draft
+        type: string
+      type:
+        example: HEMS
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightHelicopterSummary:
+    properties:
+      aog:
+        example: false
+        type: boolean
+      designation:
+        example: AIRBUS H145
+        type: string
+      id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      identifier:
+        example: D-HYAR
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      type:
+        example: H145
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 1
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.FlightMissionTypeSummary:
+    properties:
+      completed:
+        example: 0
+        type: integer
+      draft:
+        example: 5
+        type: integer
+      type:
+        example: HEMS
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightAttributes'
+      id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      type:
+        example: flight
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.FlightStepItem:
+    properties:
+      complete:
+        example: true
+        type: boolean
+      completed_at:
+        example: "2026-04-14T08:00:00Z"
+        type: string
+      completed_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      mission_type:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightMissionTypeSummary'
+        type: array
+      phase:
+        example: duty_roster
+        type: string
+      position:
+        example: takeover
+        type: string
+      status:
+        example: completed
+        type: string
+      step:
+        example: 1
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_response.FlightTakeoverSummary:
+    properties:
+      daily_inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDailyInspectionSummary'
+      helicopter:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightHelicopterSummary'
+      id:
+        example: 019e8713-aa19-7fb7-a510-a0332dc69697
+        type: string
+      roster_detail:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterDetailsResponse'
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterAttributes:
+    properties:
+      aog:
+        example: false
+        type: boolean
+      aog_reason:
+        example: Main rotor gearbox fault
+        type: string
+      consumption_lt_min:
+        example: 4.1
+        type: number
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.HelicopterAuditUser'
+      designation:
+        example: OE-XHZ
+        type: string
+      dry:
+        example: false
+        type: boolean
+      engine_1:
+        example: TM
+        type: string
+      engine_2:
+        example: TM
+        type: string
+      foto:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.HelicopterFoto'
+      identifier:
+        example: ABC-0001
+        type: string
+      igb:
+        example: false
+        type: boolean
+      is_active:
+        example: true
+        type: boolean
+      is_in_use:
+        example: false
+        type: boolean
+      last_daily_inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspection'
+      lh:
+        example: true
+        type: boolean
+      maintenance_schedules:
+        description: |-
+          MaintenanceSchedules mirrors the helicopter's latest fleet status. It
+          always lists every inspection type; entries without data are empty.
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes'
+        type: array
+      mgb:
+        example: true
+        type: boolean
+      note:
+        example: Primary HEMS helicopter
+        type: string
+      nr1:
+        example: true
+        type: boolean
+      nr2:
+        example: true
+        type: boolean
+      rh:
+        example: true
+        type: boolean
+      sortkey:
+        example: 10
+        type: integer
+      status:
+        description: |-
+          Status is the operational status of the helicopter (read-time derived).
+          Values: "available", "booked", "aog", "mcf". Precedence: mcf > aog > booked > available.
+          "booked" = active flight assignment; "aog" = air_on_ground flag OR an open complaint
+          grounding it (non-MEL, or MEL past its grace deadline); "mcf" = a pending maintenance
+          check flight (MCF created, not yet passed).
+        enum:
+        - available
+        - booked
+        - aog
+        - mcf
+        example: available
+        type: string
+      tgb:
+        example: true
+        type: boolean
+      type:
+        example: EC-135
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.HelicopterAuditUser'
+      utc_offset:
+        example: -1
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 12
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileBulkError:
+    properties:
+      code:
+        example: HELICOPTER_FILE_INVALID_PAYLOAD
+        type: string
+      detail:
+        example: helicopter_id is invalid UUID
+        type: string
+      error_code:
+        example: "4220318"
+        type: string
+      status:
+        example: 422
+        type: integer
+      title:
+        example: Validation error
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileCollectionAttachment:
+    properties:
+      download_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=...
+        type: string
+      file_name:
+        example: Before Flight Checklist.pdf
+        type: string
+      id:
+        example: 019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileCollectionAttributes:
+    properties:
+      files:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionSections'
+      helicopter:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionHelicopter'
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileCollectionHelicopter:
+    properties:
+      id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      name:
+        example: AIRBUS H145
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileCollectionItem:
+    properties:
+      attachment:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionAttachment'
+      attachment_pending:
+        example: true
+        type: boolean
+      created_at:
+        example: "2026-04-14T08:00:00Z"
+        type: string
+      created_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      helicopter_file_id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      is_mandatory:
+        example: true
+        type: boolean
+      is_template:
+        example: true
+        type: boolean
+      position:
+        example: 1
+        type: integer
+      section:
+        example: bfi
+        type: string
+      updated_at:
+        example: "2026-04-14T08:00:00Z"
+        type: string
+      updated_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileCollectionListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionResponse'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 1
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileCollectionResponse:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionAttributes'
+      type:
+        example: helicopter_file_collection
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileCollectionSections:
+    properties:
+      after:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionItem'
+        type: array
+      before:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionItem'
+        type: array
+      prepare:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionItem'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkItem:
+    properties:
+      error:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileBulkError'
+      index:
+        example: 0
+        type: integer
+      resource:
+        $ref: '#/definitions/wucher_internal_transport_http_jsonapi.Resource'
+      success:
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkItem'
+        type: array
+      meta:
+        properties:
+          failed:
+            example: 1
+            type: integer
+          partial_success:
+            example: true
+            type: boolean
+          success:
+            example: 2
+            type: integer
+          total:
+            example: 3
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileDeleteAttributes:
+    properties:
+      deleted:
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileDeleteResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileDeleteAttributes'
+      type:
+        example: helicopter_file_delete
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileDeleteResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileDeleteResource'
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.HelicopterFileAttributes'
+      id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      type:
+        example: helicopter_file
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileResource'
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileUpdateBulkItem:
+    properties:
+      error:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileBulkError'
+      index:
+        example: 0
+        type: integer
+      resource:
+        $ref: '#/definitions/wucher_internal_transport_http_jsonapi.Resource'
+      success:
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileUpdateBulkResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUpdateBulkItem'
+        type: array
+      meta:
+        properties:
+          failed:
+            example: 1
+            type: integer
+          partial_success:
+            example: true
+            type: boolean
+          success:
+            example: 2
+            type: integer
+          total:
+            example: 3
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkItem:
+    properties:
+      error:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileBulkError'
+      index:
+        example: 0
+        type: integer
+      resource:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResource'
+      success:
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkItem'
+        type: array
+      meta:
+        properties:
+          failed:
+            example: 1
+            type: integer
+          partial_success:
+            example: true
+            type: boolean
+          success:
+            example: 2
+            type: integer
+          total:
+            example: 3
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileUploadIntentAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: helicopter_file_upload_intent
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResource'
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterNextReportNumberAttributes:
+    properties:
+      identifier:
+        example: ABC
+        type: string
+      report_number:
+        example: ABC-0001
+        type: string
+      sequence:
+        example: 1
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterNextReportNumberResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterNextReportNumberAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: helicopter_report_number
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterNextReportNumberResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterNextReportNumberResource'
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: helicopter
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.HelicopterResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterResource'
+    type: object
+  wucher_internal_transport_http_dto_response.MCFAttributes:
+    properties:
+      af_hours:
+        example: "1245.3"
+        type: string
+      completed_at:
+        example: "2026-06-16T03:04:05Z"
+        type: string
+      completed_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      created_at:
+        example: "2026-06-16T03:04:05Z"
+        type: string
+      date:
+        example: "2026-06-17"
+        type: string
+      decided_at:
+        example: "2026-06-16T03:04:05Z"
+        type: string
+      decided_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      flight_id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      helicopter_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      is_cleared:
+        example: false
+        type: boolean
+      is_complete:
+        example: false
+        type: boolean
+      is_pending:
+        example: true
+        type: boolean
+      landing_count:
+        example: 3
+        type: integer
+      notes:
+        example: Vibration within limits
+        type: string
+      result:
+        enum:
+        - passed
+        - failed
+        example: passed
+        type: string
+      updated_at:
+        example: "2026-06-16T03:04:05Z"
+        type: string
+      utc_time:
+        example: "2026-06-17T08:30:00Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.MCFListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.MCFResource'
+        type: array
+      meta:
+        properties:
+          total:
+            example: 1
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.MCFResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.MCFAttributes'
+      id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      type:
+        example: mcf
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.MCFResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.MCFResource'
+    type: object
+  wucher_internal_transport_http_dto_response.MasterSettingsAttributes:
+    properties:
+      company_name:
+        example: Wucher
+        type: string
+      cover_file_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      cover_original_size_bytes:
+        example: 2048000
+        type: integer
+      cover_thumbnail_url:
+        example: https://cdn.example.com/cover.thumb.png
+        type: string
+      cover_url:
+        example: https://cdn.example.com/cover.png
+        type: string
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      logo_file_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      logo_original_size_bytes:
+        example: 1024000
+        type: integer
+      logo_thumbnail_url:
+        example: https://cdn.example.com/logo.thumb.png
+        type: string
+      logo_url:
+        example: https://cdn.example.com/logo.png
+        type: string
+      subtitle:
+        example: Flight operations platform
+        type: string
+      title:
+        example: Welcome to Wucher
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraAttributes:
+    properties:
+      MS_ENTRA_AUTHORITY:
+        example: https://login.microsoftonline.com/
+        type: string
+      MS_ENTRA_CLIENT_ID:
+        example: your-client-id
+        type: string
+      MS_ENTRA_CLIENT_SECRET:
+        example: '********'
+        type: string
+      MS_ENTRA_REDIRECT_URL:
+        example: https://example.com/api/v1/auth/microsoft/callback
+        type: string
+      MS_ENTRA_SCOPES:
+        example: openid,profile,email
+        type: string
+      MS_ENTRA_TENANT_ID:
+        example: your-tenant-id
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraAttributes'
+      type:
+        example: master_settings_microsoft_entra_sso
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResource'
+    type: object
+  wucher_internal_transport_http_dto_response.MasterSettingsResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsAttributes'
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: master_settings
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.MasterSettingsResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsResource'
+    type: object
+  wucher_internal_transport_http_dto_response.MissionAttributes:
+    properties:
+      created_at:
+        example: "2026-04-20T08:00:00Z"
+        type: string
+      created_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      end_time:
+        example: "22:05"
+        type: string
+      files:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionFileItem'
+        type: array
+      flight:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionFlightRef'
+      forms:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionForms'
+      mission_code:
+        example: HEMS-26-1
+        type: string
+      note:
+        example: Mission note
+        type: string
+      start_time:
+        example: "04:49"
+        type: string
+      status:
+        example: completed
+        type: string
+      subtypes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionSubtypeRef'
+      type:
+        example: HEMS
+        type: string
+      updated_at:
+        example: "2026-04-20T08:00:00Z"
+        type: string
+      updated_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.MissionDataTableResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionResource'
+        type: array
+      meta:
+        properties:
+          draw:
+            example: 1
+            type: integer
+          records_filtered:
+            example: 42
+            type: integer
+          records_total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.MissionFileItem:
+    properties:
+      attachment_id:
+        example: 019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e
+        type: string
+      download_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/brief.pdf?X-Amz-Signature=...
+        type: string
+      file_name:
+        example: mission-brief.pdf
+        type: string
+      id:
+        example: 019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e
+        type: string
+      thumbnail_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/thumbnails/2026/04/05/brief.png?X-Amz-Signature=...
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.MissionFlightRef:
+    properties:
+      code:
+        example: M-062226-001
+        type: string
+      date:
+        example: "2026-04-20"
+        type: string
+      id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.MissionForms:
+    properties:
+      flight_data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataResource'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.MissionListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 120
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.MissionResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionAttributes'
+      id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      type:
+        example: mission
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.MissionResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionResource'
+    type: object
+  wucher_internal_transport_http_dto_response.MissionSubtypeRef:
+    properties:
+      id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a99
+        type: string
+      subtype:
+        example: PRIM
+        type: string
+      subtype_name:
+        example: Nicht transportfaehig
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.MissionTypeAttributes:
+    properties:
+      code:
+        example: HEMS
+        type: string
+      name:
+        example: HEMS
+        type: string
+      subtypes:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionTypeSubtypeItem'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.MissionTypeListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionTypeResource'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.MissionTypeResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionTypeAttributes'
+      id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a77
+        type: string
+      type:
+        example: mission_type
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.MissionTypeSubtypeItem:
+    properties:
+      code:
+        example: PRIM
+        type: string
+      id:
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a99
+        type: string
+      name:
+        example: Primary
+        type: string
+      task_name:
+        example: Nicht transportfaehig
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.OtherPersonAttributes:
+    properties:
+      email:
+        example: guest@example.com
+        type: string
+      mobile_phone:
+        example: +43-1234
+        type: string
+      name:
+        example: Guest Person
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.OtherPersonListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResource'
+        type: array
+      meta:
+        properties:
+          total:
+            example: 1
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.OtherPersonResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.OtherPersonAttributes'
+      id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      type:
+        example: other_person
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.OtherPersonResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResource'
+    type: object
+  wucher_internal_transport_http_dto_response.ReserveAcListResponse:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResource'
+        type: array
+      meta:
+        properties:
+          page_number:
+            example: 1
+            type: integer
+          page_size:
+            example: 20
+            type: integer
+          total:
+            example: 1
+            type: integer
+        type: object
+    type: object
+  wucher_internal_transport_http_dto_response.ReserveAcResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcAttributes'
+      id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      type:
+        example: reserve_ac
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.ReserveAcResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResource'
+    type: object
+  wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew:
+    properties:
+      email:
+        example: doctor@example.com
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      mobile_phone:
+        example: +43-1234
+        type: string
+      name:
+        example: Hunter Wolfgang
+        type: string
+      role:
+        example: doctor
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.TakeoverDutyRosterDetailsResponse:
+    properties:
+      doctor:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew'
+        type: array
+      helper:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew'
+        type: array
+      other_person:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew'
+        type: array
+      pilot:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterPilotCrew'
+        type: array
+      rescuer:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterCrew'
+        type: array
+    type: object
+  wucher_internal_transport_http_dto_response.TakeoverDutyRosterPilotCrew:
+    properties:
+      co_pilot:
+        type: boolean
+      crew_type:
+        example: main
+        type: string
+      email:
+        example: pilot@example.com
+        type: string
+      examiner:
+        type: boolean
+      flight_instructor:
+        type: boolean
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      line_checker:
+        type: boolean
+      mobile_phone:
+        example: +43-1234
+        type: string
+      name:
+        example: Hunter Wolfgang
+        type: string
+      role:
+        example: pilot
+        type: string
+      supervisor:
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_response.TakeoverFileAttributes:
+    properties:
+      download_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/takeover-report.pdf?X-Amz-Signature=...
+        type: string
+      file_attachment_id:
+        example: 019d7000-aaaa-7bbb-8ccc-222222222222
+        type: string
+      file_name:
+        example: takeover-report.pdf
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.TakeoverFileResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverFileAttributes'
+      id:
+        example: 019d7000-aaaa-7bbb-8ccc-111111111111
+        type: string
+      type:
+        example: takeover_file
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.TakeoverHelicopter:
+    properties:
+      designation:
+        example: OE-XHZ
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      identifier:
+        example: "1234"
+        type: string
+      last_daily_inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspection'
+      maintenance_schedules:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes'
+        type: array
+      type:
+        example: EC-135
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.TakeoverResource:
+    properties:
+      attributes:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverResponseAttributes'
+      type:
+        example: takeover
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.TakeoverResponse:
+    properties:
+      data:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverResource'
+    type: object
+  wucher_internal_transport_http_dto_response.TakeoverResponseAttributes:
+    properties:
+      base:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterBaseInfo'
+      base_id:
+        type: string
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      duty_date:
+        type: string
+      files:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverFileResource'
+        type: array
+      flight_id:
+        type: string
+      flight_inspection_id:
+        type: string
+      helicopter:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverHelicopter'
+      helicopter_id:
+        type: string
+      id:
+        type: string
+      inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcInspectionSummary'
+      notes:
+        type: string
+      reserve_ac_id:
+        type: string
+      roster_detail:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverDutyRosterDetailsResponse'
+      shift_end:
+        type: string
+      shift_start:
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_response.UserRef:
+    properties:
+      name:
+        example: Ganahl Stefan
+        type: string
+      uuid:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.AirRescuerChecklistBaseInfo:
+    properties:
+      base_abbreviation:
+        example: G1
+        type: string
+      base_category:
+        example: hems
+        type: string
+      base_name:
+        example: Gallus 1 - Zurs Lech
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.AirRescuerChecklistItemInput:
+    properties:
+      name:
+        example: Oxygen supply check
+        type: string
+      position:
+        example: 1
+        type: integer
+    required:
+    - name
+    type: object
+  wucher_internal_transport_http_dto_shared.FileManagerAttachmentAttributes:
+    properties:
+      attached_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      category:
+        example: document
+        type: string
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      file_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      is_primary:
+        example: false
+        type: boolean
+      ref_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      ref_type:
+        example: helicopter
+        type: string
+      sort_order:
+        example: 0
+        type: integer
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FileManagerFileAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      download_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=...
+        type: string
+      extension:
+        example: pdf
+        type: string
+      failed_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      failure_reason:
+        example: ""
+        type: string
+      file_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      folder_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      is_template:
+        example: true
+        type: boolean
+      mime_type:
+        example: application/pdf
+        type: string
+      name:
+        example: policy.pdf
+        type: string
+      name_normalized:
+        example: policy.pdf
+        type: string
+      processed_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      processing_started_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      purge_at:
+        example: "2026-04-12T03:04:05Z"
+        type: string
+      size_bytes:
+        example: 1024
+        type: integer
+      status:
+        example: validated
+        type: string
+      trashed_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      upload_error:
+        example: ""
+        type: string
+      validated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FileManagerFileAuditAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FileManagerFileDetailAttributes:
+    properties:
+      audit:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileAuditAttributes'
+      download_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=...
+        type: string
+      extension:
+        example: pdf
+        type: string
+      is_template:
+        example: true
+        type: boolean
+      location:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileLocationAttributes'
+      mime_type:
+        example: application/pdf
+        type: string
+      name:
+        example: policy.pdf
+        type: string
+      name_normalized:
+        example: policy.pdf
+        type: string
+      preview_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.preview.pdf?X-Amz-Signature=...
+        type: string
+      processing:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFileProcessingAttributes'
+      size_bytes:
+        example: 1024
+        type: integer
+      status:
+        example: ready
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FileManagerFileLocationAttributes:
+    properties:
+      folder_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FileManagerFileProcessingAttributes:
+    properties:
+      failed_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      failure_reason:
+        example: processing validation failed
+        type: string
+      processed_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      processing_started_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      validated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FileManagerFileUploadIntentAttributes:
+    properties:
+      expires_at:
+        example: "2026-04-05T07:29:34Z"
+        type: string
+      expires_in_seconds:
+        example: 900
+        type: integer
+      file:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileUploadFile'
+      method:
+        example: PUT
+        type: string
+      object:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileUploadObject'
+      required_headers:
+        additionalProperties:
+          type: string
+        type: object
+      upload_intent_uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      upload_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/...
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FileManagerFolderAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      deleted_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      deleted_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      depth:
+        example: 1
+        type: integer
+      name:
+        example: operations
+        type: string
+      name_normalized:
+        example: operations
+        type: string
+      parent_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      path_cache:
+        example: /root/operations
+        type: string
+      purge_at:
+        example: "2026-04-12T03:04:05Z"
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FileManagerFolderAuditAttributes:
+    properties:
+      created_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      created_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      updated_at:
+        example: "2026-03-12T03:04:05Z"
+        type: string
+      updated_by:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FileManagerFolderDetailAttributes:
+    properties:
+      audit:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFolderAuditAttributes'
+      depth:
+        example: 1
+        type: integer
+      location:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FileManagerFolderLocationAttributes'
+      name:
+        example: operations
+        type: string
+      name_normalized:
+        example: operations
+        type: string
+      path_cache:
+        example: /root/operations
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FileManagerFolderLocationAttributes:
+    properties:
+      parent_id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FileUploadFile:
+    properties:
+      mime_type:
+        example: application/pdf
+        type: string
+      name:
+        example: policy-final.pdf
+        type: string
+      size_bytes:
+        example: 1024
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_shared.FileUploadObject:
+    properties:
+      bucket:
+        example: wucher-file-dev
+        type: string
+      key:
+        example: files/2026/04/05/018f3a5c7a6f7c2a8d4a4b5b1f6c8e9d.pdf
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FleetStatusComplaint:
+    properties:
+      action:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusComplaintAction'
+      aircraft_hours_at_report:
+        type: string
+      description:
+        type: string
+      flight_id:
+        type: string
+      id:
+        type: string
+      mel:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusComplaintMEL'
+      nsr:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusComplaintNSR'
+      reported_at:
+        type: string
+      reported_by:
+        type: string
+      reported_by_name:
+        type: string
+      reported_by_short:
+        type: string
+      status:
+        enum:
+        - active_non_mel
+        - active_mel
+        - serviced
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FleetStatusComplaintAction:
+    properties:
+      aircraft_hours_at_fix:
+        type: string
+      signed_at:
+        type: string
+      signed_by:
+        type: string
+      signed_by_name:
+        type: string
+      signed_by_short:
+        type: string
+      taken:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FleetStatusComplaintMEL:
+    properties:
+      classified_at:
+        type: string
+      classified_by:
+        type: string
+      classified_by_name:
+        type: string
+      classified_by_short:
+        type: string
+      deadline:
+        type: string
+      severity:
+        enum:
+        - 0
+        - 1
+        - 2
+        - 3
+        - 4
+        type: integer
+      severity_label:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FleetStatusComplaintNSR:
+    properties:
+      decided_at:
+        type: string
+      decided_by:
+        type: string
+      decided_by_name:
+        type: string
+      decided_by_short:
+        type: string
+      is_nsr:
+        type: boolean
+      reason:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FleetStatusEASARelease:
+    properties:
+      easa_ac_hours:
+        type: string
+      easa_date:
+        type: string
+      easa_location:
+        type: string
+      easa_maint_manual_rev_airframe:
+        type: string
+      easa_maint_manual_rev_engine:
+        type: string
+      easa_permit_no:
+        type: string
+      easa_signer_id:
+        type: string
+      easa_wo_no:
+        type: string
+      id:
+        type: string
+      is_signed:
+        type: boolean
+      missing_sign_fields:
+        items:
+          type: string
+        type: array
+      signed_at:
+        type: string
+      signed_by:
+        type: string
+      signed_by_name:
+        type: string
+      signed_by_short:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FleetStatusFileAttributes:
+    properties:
+      category:
+        enum:
+        - wb
+        - bfi
+        example: wb
+        type: string
+      file_id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      is_mandatory:
+        description: IsMandatory — when true, this file must be checked (is_done)
+          during takeover.
+        example: true
+        type: boolean
+    required:
+    - category
+    - file_id
+    type: object
+  wucher_internal_transport_http_dto_shared.FleetStatusHelicopter:
+    properties:
+      designation:
+        example: AIRBUS H145
+        type: string
+      flight_id:
+        description: |-
+          FlightID — id of the aircraft's current active flight (present only when it is in
+          use / booked). The fleet page uses it to create an EASA release scoped to the flight.
+        example: 019d6774-98e8-7fba-9ef4-3795c0da8a13
+        type: string
+      id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      identifier:
+        example: D-HEMS
+        type: string
+      status:
+        enum:
+        - available
+        - booked
+        - aog
+        - mcf
+        example: available
+        type: string
+      status_reasons:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusHelicopterReason'
+        type: array
+      type:
+        example: EC-135
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FleetStatusHelicopterReason:
+    properties:
+      code:
+        enum:
+        - manual_aog
+        - mel_expired
+        - non_mel_pending
+        - inspection_overdue
+        type: string
+      complaint_id:
+        type: string
+      detail:
+        type: string
+      schedule_id:
+        type: string
+      since:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FleetStatusMCF:
+    properties:
+      active:
+        description: |-
+          Active — true when the helicopter is currently in MCF (an open draft, or a signed
+          but failed MCF still needing a re-flight); false when cleared/cancelled/none.
+        type: boolean
+      af_hours:
+        description: AFHours / LandingCount present only once the MCF is signed; omitted
+          for none/draft/cancelled.
+        type: string
+      date:
+        type: string
+      id:
+        type: string
+      landing_count:
+        type: integer
+      sign:
+        description: Sign — true once the MCF is completed/signed; false while it
+          is still a draft.
+        type: boolean
+      signed_by:
+        description: SignedBy / SignedByName / SignedByShort — who signed (completed)
+          the MCF; empty while unsigned.
+        type: string
+      signed_by_name:
+        type: string
+      signed_by_short:
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.FleetStatusSummary:
+    properties:
+      airframe:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusSummaryAirframe'
+      engine_1:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusSummaryEngine'
+      engine_2:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.FleetStatusSummaryEngine'
+      flight_reports:
+        type: number
+      hook_releases:
+        type: number
+      landings:
+        type: number
+      rotor_brake_cycles:
+        type: number
+    type: object
+  wucher_internal_transport_http_dto_shared.FleetStatusSummaryAirframe:
+    properties:
+      cycles:
+        type: number
+      hours:
+        type: number
+    type: object
+  wucher_internal_transport_http_dto_shared.FleetStatusSummaryEngine:
+    properties:
+      ccc:
+        type: number
+      gpc_ng_n1:
+        type: number
+      hours:
+        type: number
+      ptc_nf_n2:
+        type: number
+    type: object
+  wucher_internal_transport_http_dto_shared.HelicopterAuditUser:
+    properties:
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      name:
+        example: John Doe
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.HelicopterFileAttributes:
+    properties:
+      attachment_pending:
+        example: true
+        type: boolean
+      created_at:
+        example: "2026-04-14T08:00:00Z"
+        type: string
+      created_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      download_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=...
+        type: string
+      file_attachment_id:
+        example: 019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e
+        type: string
+      file_name:
+        example: Before Flight Checklist.pdf
+        type: string
+      helicopter_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      helicopter_name:
+        example: AIRBUS H145
+        type: string
+      is_mandatory:
+        example: true
+        type: boolean
+      is_template:
+        example: true
+        type: boolean
+      position:
+        example: 1
+        type: integer
+      section:
+        example: bfi
+        type: string
+      updated_at:
+        example: "2026-04-14T08:00:00Z"
+        type: string
+      updated_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.HelicopterFoto:
+    properties:
+      download_url:
+        example: https://storage.example.com/helicopter/foto.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=abc123
+        type: string
+      original_size_bytes:
+        example: 1024000
+        type: integer
+      thumbnail_download_url:
+        example: https://storage.example.com/helicopter/foto.thumb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=abc123
+        type: string
+      uuid:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.HelicopterInspectionFilesChecklist:
+    properties:
+      completed:
+        example: 47
+        type: integer
+      total:
+        example: 47
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_shared.HelicopterLastDailyBase:
+    properties:
+      base_abbreviation:
+        example: G1
+        type: string
+      base_name:
+        example: Gallus 1 - Zurs Lech
+        type: string
+      id:
+        example: 018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d
+        type: string
+      type:
+        example: hems
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspection:
+    properties:
+      base:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.HelicopterLastDailyBase'
+      inspected_at:
+        example: "2026-05-25T07:47:00Z"
+        type: string
+      inspection_files_checklist:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.HelicopterInspectionFilesChecklist'
+      inspection_id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      inspector:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspector'
+      status:
+        example: inspected_cleared
+        type: string
+      utc_time:
+        example: "07:47"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.HelicopterLastDailyInspector:
+    properties:
+      id:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      license_no:
+        example: "4521"
+        type: string
+      name:
+        example: Teodora Lesmana
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.MaintenanceScheduleAttributes:
+    properties:
+      due:
+        example: "1200"
+        type: string
+      ext:
+        example: "1300"
+        type: string
+      inspection_type:
+        example: A/F
+        type: string
+      type:
+        example: 100H
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.ReserveAcAircraftSummary:
+    properties:
+      aog:
+        example: false
+        type: boolean
+      designation:
+        example: AIRBUS H145
+        type: string
+      id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      identifier:
+        example: D-HYAR
+        type: string
+      is_active:
+        example: true
+        type: boolean
+      type:
+        example: H145
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.ReserveAcAttributes:
+    properties:
+      created_at:
+        example: "2026-04-14T08:00:00Z"
+        type: string
+      created_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      deleted_at:
+        example: "2026-04-14T08:00:00Z"
+        type: string
+      deleted_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+      flight_id:
+        example: 019d6773-ccca-71dd-b9c7-8e6f531deb90
+        type: string
+      helicopter:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcAircraftSummary'
+      helicopter_id:
+        example: 019d6771-5fb5-7337-837f-bc5ed85181a1
+        type: string
+      inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcInspectionSummary'
+      last_daily_inspection:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcLastDailyInfo'
+      status:
+        example: pending
+        type: string
+      updated_at:
+        example: "2026-04-14T08:00:00Z"
+        type: string
+      updated_by:
+        example: 019d61db-53c6-7280-87ec-e65f205c6d3b
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.ReserveAcBeforeInspectionFields:
+    properties:
+      fuel_added_amount:
+        type: number
+      fuel_amount:
+        type: number
+      fuel_unit:
+        type: string
+      hydraulic_lh_checked:
+        type: boolean
+      hydraulic_rh_checked:
+        type: boolean
+      note:
+        type: string
+      oil_engine_nr1_checked:
+        type: boolean
+      oil_engine_nr2_checked:
+        type: boolean
+      oil_transmission_igb_checked:
+        type: boolean
+      oil_transmission_mgb_checked:
+        type: boolean
+      oil_transmission_tgb_checked:
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_shared.ReserveAcBeforeSectionDTO:
+    properties:
+      completed:
+        example: 1
+        type: integer
+      done_file_checklist:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO'
+        type: array
+      fields:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcBeforeInspectionFields'
+      file_checklist:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO'
+        type: array
+      total:
+        example: 3
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO:
+    properties:
+      download_url:
+        example: https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=...
+        type: string
+      file_attachment_id:
+        example: 019d7000-aaaa-7bbb-8ccc-222222222222
+        type: string
+      file_name:
+        example: Before Flight Checklist.pdf
+        type: string
+      helicopter_file_id:
+        example: 019d7000-aaaa-7bbb-8ccc-111111111111
+        type: string
+      is_done:
+        example: false
+        type: boolean
+      is_mandatory:
+        example: true
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_shared.ReserveAcFleetStatusFileSectionDTO:
+    properties:
+      completed:
+        example: 1
+        type: integer
+      done_file_checklist:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO'
+        type: array
+      file_checklist:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO'
+        type: array
+      total:
+        example: 2
+        type: integer
+    type: object
+  wucher_internal_transport_http_dto_shared.ReserveAcInspectionSummary:
+    properties:
+      before:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcBeforeSectionDTO'
+      fleet_status_file:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFleetStatusFileSectionDTO'
+      id:
+        example: 019d6772-471c-7b70-b42a-d94020ef61e4
+        type: string
+      inspection_date:
+        example: "2026-04-15"
+        type: string
+      prepare:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcPrepareSectionDTO'
+    type: object
+  wucher_internal_transport_http_dto_shared.ReserveAcLastDailyInfo:
+    properties:
+      date:
+        example: 17.04.2026
+        type: string
+      name:
+        example: Ganahl Stefan
+        type: string
+      short_name:
+        example: GAN
+        type: string
+      utc_time:
+        example: "10:57"
+        type: string
+    type: object
+  wucher_internal_transport_http_dto_shared.ReserveAcPrepareFields:
+    properties:
+      notam_briefing:
+        type: boolean
+      operational_flight_plan:
+        type: boolean
+      weather_briefing:
+        type: boolean
+    type: object
+  wucher_internal_transport_http_dto_shared.ReserveAcPrepareSectionDTO:
+    properties:
+      completed:
+        example: 1
+        type: integer
+      done_file_checklist:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO'
+        type: array
+      file_checklist:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcFileChecklistItemDTO'
+        type: array
+      prepare_fields:
+        $ref: '#/definitions/wucher_internal_transport_http_dto_shared.ReserveAcPrepareFields'
+      total:
+        example: 3
+        type: integer
+    type: object
+  wucher_internal_transport_http_jsonapi.Document:
+    properties:
+      data: {}
+      meta: {}
+    type: object
+  wucher_internal_transport_http_jsonapi.ErrorDocument:
+    properties:
+      errors:
+        items:
+          $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorObject'
+        type: array
+    type: object
+  wucher_internal_transport_http_jsonapi.ErrorObject:
+    properties:
+      code:
+        type: string
+      detail:
+        type: string
+      error_code:
+        type: string
+      source:
+        $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorSource'
+      status:
+        type: string
+      title:
+        type: string
+    type: object
+  wucher_internal_transport_http_jsonapi.ErrorSource:
+    properties:
+      pointer:
+        type: string
+    type: object
+  wucher_internal_transport_http_jsonapi.Resource:
+    properties:
+      attributes:
+        additionalProperties: {}
+        type: object
+      id:
+        type: string
+      type:
+        type: string
+    type: object
+info:
+  contact: {}
+  description: |-
+    Wucher backend API (JSON:API).
+
+    Auth Flow (Email/Password):
+    1) POST /api/v1/auth/register
+    2) Check email, open verify link (GET /api/v1/auth/verify-email)
+    3) POST /api/v1/auth/login
+    - If TOTP enabled: response 202 with challenge_token
+    4) POST /api/v1/auth/totp/verify (challenge_token + code) -> cookies
+
+    Auth Flow (TOTP setup):
+    1) POST /api/v1/auth/totp/setup -> secret + otpauth_url (enabled=false)
+    2) POST /api/v1/auth/totp/confirm -> enabled=true
+
+    Auth Flow (Microsoft Entra SSO):
+    1) GET /api/v1/auth/microsoft/login -> redirect to Microsoft
+    2) Microsoft redirects to /api/v1/auth/microsoft/callback
+    3) Backend checks existing SSO mapping (no auto-register)
+    4) If linked user exists -> set cookies + optional redirect to AUTH_SSO_SUCCESS_REDIRECT
+    5) If mapping not linked -> login rejected (401)
+    6) Existing authenticated user can link/unlink via /api/v1/auth/sso/link and /api/v1/auth/sso/unlink
+  title: Wucher API
+  version: "1.0"
+paths:
+  /api/v1/action-signoffs/get-by-flight/{flight_id}:
+    get:
+      description: Returns the fleet-level (complaint-independent) corrective-action
+        sign-off state for a helicopter — `signed`, `signed_at`, `signed_by`. When
+        none exists yet it returns an unsigned placeholder. A signed sign-off is what
+        gates the EASA maintenance release.
+      parameters:
+      - description: Flight ID (UUIDv7)
+        in: path
+        name: flight_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ActionSignoffResponse'
+      summary: Get the current corrective-action sign-off for a helicopter
+      tags:
+      - Complaints - Sign Off
+  /api/v1/action-signoffs/sign/{helicopter_id}:
+    post:
+      consumes:
+      - application/json
+      description: 'Toggles the corrective-action sign-off for a helicopter. `sign`
+        (optional, default true) chooses the direction: true signs, false unsigns.
+        Send `complaint_id` to target a specific complaint''s sign-off — signing it
+        requires `action_taken` recorded (else 422 `ACTION_SIGNOFF_ACTION_REQUIRED`),
+        and 404 `ACTION_SIGNOFF_COMPLAINT_NOT_FOUND` if the complaint does not exist.
+        Omit `complaint_id` for a fleet-wide (complaint-independent) sign-off. A signed
+        sign-off is what allows an EASA maintenance release to be created for the
+        helicopter.'
+      parameters:
+      - description: Helicopter ID (UUIDv7)
+        in: path
+        name: helicopter_id
+        required: true
+        type: string
+      - description: Optional complaint_id + note
+        in: body
+        name: request
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ActionSignoffSignRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ActionSignoffResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Toggle the corrective-action sign-off (per complaint or fleet-wide)
+      tags:
+      - Complaints - Sign Off
+  /api/v1/after-flight-inspection/create:
+    post:
+      consumes:
+      - application/json
+      description: Create after-flight inspection and AFI file checklist for a flight
+        inspection.
+      parameters:
+      - description: Create last flights inspection request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create last flights inspection
+      tags:
+      - Flights - After Flights Inspection
+  /api/v1/after-flight-inspection/delete:
+    delete:
+      consumes:
+      - application/json
+      description: Delete after-flight inspection and AFI checklist rows by `flight_inspection_id`.
+      parameters:
+      - description: Delete last flights inspection request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionDeleteRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.Document'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete last flights inspection
+      tags:
+      - Flights - After Flights Inspection
+  /api/v1/after-flight-inspection/get:
+    get:
+      description: Get after-flight inspection detail and AFI file checklist by query
+        `inspection_id`.
+      parameters:
+      - description: Flight Inspection UUID
+        in: query
+        name: inspection_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get last flights inspection
+      tags:
+      - Flights - After Flights Inspection
+  /api/v1/after-flight-inspection/update:
+    patch:
+      consumes:
+      - application/json
+      description: Update after-flight inspection and AFI file checklist for a flight
+        inspection.
+      parameters:
+      - description: Update last flights inspection request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.LastFlightsInspectionUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AfterFlightInspectionResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update last flights inspection
+      tags:
+      - Flights - After Flights Inspection
+  /api/v1/air-rescuer-checklist/{uuid}/items/create:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Create one or more items for an existing checklist.
+        Parent checklist is taken from path `uuid`.
+        Duplicate `position` is allowed. Display order for checklist_items is `position ASC, name ASC`.
+        Request is transactional: if one item fails, all item inserts in the batch are rolled back.
+      parameters:
+      - description: Checklist UUID
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: Bulk checklist item create payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create checklist items (bulk)
+      tags:
+      - Air Rescuer Checklist
+  /api/v1/air-rescuer-checklist/{uuid}/items/reorder:
+    patch:
+      consumes:
+      - application/json
+      description: |-
+        Reorder one or more checklist items for the checklist in path `uuid`.
+        Use this endpoint to swap or reorder positions with a single PIN validation.
+        Duplicate `position` values remain allowed by domain rules.
+        Request is transactional: if one item fails, all position updates are rolled back.
+      parameters:
+      - description: Checklist UUID
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: Checklist item reorder payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemReorderRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Reorder checklist items in one request
+      tags:
+      - Air Rescuer Checklist
+  /api/v1/air-rescuer-checklist/create:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Create one or more checklist headers for a single base.
+        Request uses `base_id`.
+        Each checklist can be created with or without initial `items`.
+        `scope_code` accepts persisted codes and English aliases. Stored codes remain: `TA`, `MO`, `DI`, `MI`, `DO`, `FR`, `SA`, `SO`, `M10`, `M15`, `M20`, `M25`, `DS`.
+        Example aliases: `DAILY` -> `TA`, `TU/TUE/TUESDAY` -> `DI`, `WE/WED/WEDNESDAY` -> `MI`, `TH/THU/THURSDAY` -> `DO`, `SU/SUN/SUNDAY` -> `SO`, `DEADLINE` -> `DS`.
+        `CAT` is a virtual overview tab and is not allowed for create/update payloads.
+        Duplicate `position` is allowed for both checklist headers and checklist items.
+        Display order is stable: checklist headers `position ASC, title ASC`; checklist_items `position ASC, name ASC`.
+        Request is transactional: if one checklist/item fails, the whole batch is rolled back.
+      parameters:
+      - description: Bulk checklist create payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create air rescuer checklist (bulk)
+      tags:
+      - Air Rescuer Checklist
+  /api/v1/air-rescuer-checklist/delete/{uuid}:
+    delete:
+      description: |-
+        Delete one checklist header by UUID.
+        Related checklist items are removed together following current implementation behavior.
+      parameters:
+      - description: Checklist UUID
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedListResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete air rescuer checklist
+      tags:
+      - Air Rescuer Checklist
+  /api/v1/air-rescuer-checklist/get-all:
+    get:
+      description: |-
+        Grouped by base and returned in `data[].attributes.bases`.
+        Response includes `tabs[]` with default tab order: `CAT`, `TA`, `MO`, `DI`, `MI`, `DO`, `FR`, `SA`, `SO`, `M10`, `M15`, `M20`, `M25`, `DS`.
+        `CAT` is a virtual overview tab (not persisted in DB).
+        `CAT.groups[]` only includes non-empty persisted scopes and does not include `checklist_items`.
+        Normal tabs are always present. Empty normal tabs are explicitly returned as `checklists: []`.
+        Scope display names: `CAT=Category`, `TA=Daily`, `MO=Monday`, `DI=Tuesday`, `MI=Wednesday`, `DO=Thursday`, `FR=Friday`, `SA=Saturday`, `SO=Sunday`, `M10=M10`, `M15=M15`, `M20=M20`, `M25=M25`, `DS=Deadline`.
+        Duplicate `position` is allowed. Display order is stable: checklist headers `position ASC, title ASC`; checklist_items `position ASC, name ASC`.
+        Optional filters: `base_id`, `category_type` (`regular|hems`), `base_name`, `base_abbreviation`, `scope_code` (`CAT`/`OVERVIEW` or persisted scope / aliases).
+      parameters:
+      - description: Filter by base UUID
+        in: query
+        name: base_id
+        type: string
+      - description: Filter by base category
+        enum:
+        - regular
+        - hems
+        in: query
+        name: category_type
+        type: string
+      - description: Filter by base name (contains, case-insensitive)
+        in: query
+        name: base_name
+        type: string
+      - description: Filter by base abbreviation (contains, case-insensitive)
+        in: query
+        name: base_abbreviation
+        type: string
+      - description: 'Filter by scope code. Allowed canonical: CAT, TA, MO, DI, MI,
+          DO, FR, SA, SO, M10, M15, M20, M25, DS. English aliases are also accepted.'
+        in: query
+        name: scope_code
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedDataTableResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List air rescuer checklist grouped by base
+      tags:
+      - Air Rescuer Checklist
+  /api/v1/air-rescuer-checklist/get-all/dt:
+    get:
+      description: |-
+        Datatable variant for grouped air rescuer checklist data.
+        Semantic data is the same as `get-all`: grouped by base with `tabs[]`, virtual `CAT`, and normal tabs always present.
+        `CAT.groups[]` only includes non-empty persisted scopes and does not include `checklist_items`.
+        Empty normal tabs are explicitly returned as `checklists: []`.
+        Scope display names: `CAT=Category`, `TA=Daily`, `MO=Monday`, `DI=Tuesday`, `MI=Wednesday`, `DO=Thursday`, `FR=Friday`, `SA=Saturday`, `SO=Sunday`, `M10=M10`, `M15=M15`, `M20=M20`, `M25=M25`, `DS=Deadline`.
+        Duplicate `position` is allowed. Display order is stable: checklist headers `position ASC, title ASC`; checklist_items `position ASC, name ASC`.
+        Optional filters: `base_id`, `category_type` (`regular|hems`), `base_name`, `base_abbreviation`, `scope_code`.
+        Pagination/query controls: `page`, `size`, `limit`, `draw`.
+      parameters:
+      - description: Filter by base UUID
+        in: query
+        name: base_id
+        type: string
+      - description: Filter by base category
+        enum:
+        - regular
+        - hems
+        in: query
+        name: category_type
+        type: string
+      - description: Filter by base name (contains, case-insensitive)
+        in: query
+        name: base_name
+        type: string
+      - description: Filter by base abbreviation (contains, case-insensitive)
+        in: query
+        name: base_abbreviation
+        type: string
+      - description: 'Filter by scope code. Allowed canonical: CAT, TA, MO, DI, MI,
+          DO, FR, SA, SO, M10, M15, M20, M25, DS. English aliases are also accepted.'
+        in: query
+        name: scope_code
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (max 100)
+        in: query
+        name: limit
+        type: integer
+      - description: Datatable draw counter
+        in: query
+        name: draw
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistGroupedDataTableResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List air rescuer checklist grouped by base (datatable)
+      tags:
+      - Air Rescuer Checklist
+  /api/v1/air-rescuer-checklist/get/{uuid}:
+    get:
+      description: |-
+        Return one checklist detail by UUID.
+        Includes checklist header, base info, and `items` (`checklist_items`).
+      parameters:
+      - description: Checklist UUID
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get air rescuer checklist by UUID
+      tags:
+      - Air Rescuer Checklist
+  /api/v1/air-rescuer-checklist/items/delete/{item_uuid}:
+    delete:
+      description: Delete one existing checklist item by `item_uuid`.
+      parameters:
+      - description: Checklist item UUID
+        in: path
+        name: item_uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.Document'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete one checklist item
+      tags:
+      - Air Rescuer Checklist
+  /api/v1/air-rescuer-checklist/items/update/{item_uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: |-
+        Update one existing checklist item by `item_uuid`.
+        This endpoint only affects the selected item.
+        Duplicate `position` is allowed.
+      parameters:
+      - description: Checklist item UUID
+        in: path
+        name: item_uuid
+        required: true
+        type: string
+      - description: Checklist item update payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistItemUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistItemResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update one checklist item
+      tags:
+      - Air Rescuer Checklist
+  /api/v1/air-rescuer-checklist/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: |-
+        Update checklist header fields (`scope_code`, `title`, `position`) and/or append `new_items`.
+        `new_items` is append-only. Existing items are not updated/deleted by this endpoint.
+        Item update/delete lifecycle must use dedicated item endpoints.
+        `scope_code` accepts persisted codes and English aliases, but `CAT` (or `OVERVIEW`) is not allowed for update payload.
+        Duplicate `position` is allowed.
+        Request is transactional.
+      parameters:
+      - description: Checklist UUID
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: Checklist update payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.AirRescuerChecklistUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.AirRescuerChecklistResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update air rescuer checklist header and append new items
+      tags:
+      - Air Rescuer Checklist
+  /api/v1/audit-logs/get-all:
+    get:
+      description: JSON:API list with pagination, filtering and sorting.
+      parameters:
+      - description: Search by request_id/layer/action/method/path/message (contains)
+        in: query
+        name: filter[search]
+        type: string
+      - description: Method filter; single/comma-separated values or ALL/*
+        enum:
+        - POST
+        - PUT
+        - PATCH
+        - DELETE
+        - UPDATE
+        - ALL
+        - '*'
+        in: query
+        name: filter[method]
+        type: string
+      - description: Alias for filter[method]
+        enum:
+        - POST
+        - PUT
+        - PATCH
+        - DELETE
+        - UPDATE
+        - ALL
+        - '*'
+        in: query
+        name: method
+        type: string
+      - description: Module filter; single/comma-separated values or ALL/*
+        enum:
+        - air_rescuer_checklist
+        - audit_log
+        - auth
+        - base
+        - base_regular
+        - base_hems
+        - base_roster
+        - branding
+        - contact
+        - duty_roster
+        - facility
+        - federal_state
+        - file_manager
+        - flight
+        - flight_data
+        - forces_present
+        - health_insurance_company
+        - helicopter
+        - helicopter_file
+        - hems_roster
+        - hospital
+        - icao
+        - insurance_patient_data
+        - land
+        - master_setting
+        - medicine
+        - mission
+        - opc
+        - patient_data
+        - reserve_ac
+        - role
+        - user
+        - vocation
+        - unknown
+        - ALL
+        - '*'
+        in: query
+        name: filter[module]
+        type: string
+      - description: Alias for filter[module]
+        enum:
+        - air_rescuer_checklist
+        - audit_log
+        - auth
+        - base
+        - base_regular
+        - base_hems
+        - base_roster
+        - branding
+        - contact
+        - duty_roster
+        - facility
+        - federal_state
+        - file_manager
+        - flight
+        - flight_data
+        - forces_present
+        - health_insurance_company
+        - helicopter
+        - helicopter_file
+        - hems_roster
+        - hospital
+        - icao
+        - insurance_patient_data
+        - land
+        - master_setting
+        - medicine
+        - mission
+        - opc
+        - patient_data
+        - reserve_ac
+        - role
+        - user
+        - vocation
+        - unknown
+        - ALL
+        - '*'
+        in: query
+        name: module
+        type: string
+      - description: Action filter; single/comma-separated values or ALL/*
+        enum:
+        - list
+        - get
+        - create
+        - update
+        - delete
+        - export
+        - custom
+        - ALL
+        - '*'
+        in: query
+        name: filter[action]
+        type: string
+      - description: Alias for filter[action]
+        enum:
+        - list
+        - get
+        - create
+        - update
+        - delete
+        - export
+        - custom
+        - ALL
+        - '*'
+        in: query
+        name: action
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 200)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        enum:
+        - created_at
+        - -created_at
+        - module
+        - -module
+        - action
+        - -action
+        - layer
+        - -layer
+        - status_code
+        - -status_code
+        - success
+        - -success
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.Document'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List audit logs
+      tags:
+      - Audit Logs
+  /api/v1/auth/email-otp/send:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Sends a one-time 6-digit OTP to user email using login challenge token from /auth/login.
+        Security controls: old OTP is invalidated, resend cooldown is enforced, and resend/hour quota is enforced.
+      parameters:
+      - description: JSON:API Email OTP send request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.EmailOTPSendRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.EmailOTPSendResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "429":
+          description: Too Many Requests
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Send login OTP to email
+      tags:
+      - Auth - Email OTP
+  /api/v1/auth/email-otp/verify:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Verifies one-time OTP and completes login by issuing auth cookies.
+        OTP is one-time use, expires automatically, and failed attempts are limited and audited.
+      parameters:
+      - description: JSON:API Email OTP verify request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.EmailOTPVerifyRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.EmailOTPVerifyResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Verify login OTP from email
+      tags:
+      - Auth - Email OTP
+  /api/v1/auth/exchange:
+    post:
+      consumes:
+      - application/json
+      description: Accepts Microsoft token payload from frontend ssoSilent and issues
+        backend auth cookies.
+      parameters:
+      - description: JSON:API Exchange request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ExchangeRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.TokenResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Exchange frontend Microsoft SSO token into backend session
+      tags:
+      - Auth
+  /api/v1/auth/forgot-password:
+    post:
+      consumes:
+      - application/json
+      description: Always returns a generic success response.
+      parameters:
+      - description: JSON:API Forgot password request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ForgotPasswordRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Forgot password
+      tags:
+      - Auth - Forgot Password
+  /api/v1/auth/invite:
+    post:
+      consumes:
+      - application/json
+      description: Creates user without password and sends set-password link to email.
+      parameters:
+      - description: JSON:API Invite request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.InviteRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.UserResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Invite user
+      tags:
+      - Auth
+  /api/v1/auth/invite/resend-set-password:
+    post:
+      consumes:
+      - application/json
+      description: Triggers a new set-password invite email for an invited user by
+        user_id. Response is generic for security.
+      parameters:
+      - description: JSON:API resend set-password invite request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ResendSetPasswordInviteRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Resend set-password invite
+      tags:
+      - Auth
+  /api/v1/auth/login:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        If TOTP enabled, returns 202 + challenge_token (use /auth/totp/verify).
+        If TOTP is not enabled, returns 202 + email OTP challenge_token (use /auth/email-otp/send then /auth/email-otp/verify).
+      parameters:
+      - description: JSON:API Login request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.LoginRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthCurrentUserResponse'
+        "202":
+          description: Accepted
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.LoginEmailOTPRequiredResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Login with email & password
+      tags:
+      - Auth
+  /api/v1/auth/logout:
+    post:
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse'
+      summary: Logout (revoke refresh)
+      tags:
+      - Auth - Refresh
+  /api/v1/auth/me:
+    get:
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthCurrentUserResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get current user
+      tags:
+      - Auth
+  /api/v1/auth/me/timezone:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: JSON:API timezone update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.TimezoneUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthCurrentUserResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update current user timezone
+      tags:
+      - Auth
+  /api/v1/auth/microsoft/callback:
+    get:
+      description: Completes Microsoft SSO login. Login succeeds only when SSO identity
+        is already linked to an existing user.
+      parameters:
+      - description: Authorization code
+        in: query
+        name: code
+        required: true
+        type: string
+      - description: State
+        in: query
+        name: state
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MicrosoftCallbackResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Microsoft Entra SSO callback
+      tags:
+      - Auth
+  /api/v1/auth/microsoft/front-channel-logout:
+    get:
+      description: OIDC front-channel logout endpoint. Configure this URL as the "Front-channel
+        logout URL" in Microsoft Entra. Microsoft loads it in a hidden iframe when
+        the user signs out at the IdP (or from another RP). It clears local auth cookies
+        and revokes the server-side session plus the stored Microsoft refresh token
+        for the browser that owns the request. It never redirects and always returns
+        200 so the IdP logout flow can complete.
+      produces:
+      - text/html
+      responses:
+        "200":
+          description: logged out
+          schema:
+            type: string
+      summary: Microsoft front-channel logout callback
+      tags:
+      - Auth - SSO
+  /api/v1/auth/microsoft/link:
+    get:
+      description: Returns JSON:API payload containing Microsoft authorization URL
+        for linking SSO to the current authenticated user.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MicrosoftLoginResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      security:
+      - BearerAuth: []
+      summary: Microsoft Entra SSO link URL
+      tags:
+      - Auth
+  /api/v1/auth/microsoft/login:
+    get:
+      description: |-
+        Returns JSON:API payload containing Microsoft authorization URL.
+        Backend starts with silent session-check (`prompt=none`). If Microsoft session is inactive, callback automatically falls back to interactive login.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MicrosoftLoginResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Microsoft Entra SSO login
+      tags:
+      - Auth
+  /api/v1/auth/microsoft/login-check:
+    get:
+      description: Returns JSON:API payload containing Microsoft authorization URL
+        with prompt=none for strict session check.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MicrosoftLoginResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Microsoft Entra silent session check URL
+      tags:
+      - Auth
+  /api/v1/auth/microsoft/logout:
+    post:
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Logout Microsoft OAuth session
+      tags:
+      - Auth - SSO
+  /api/v1/auth/microsoft/reauth:
+    get:
+      description: Starts a Microsoft reauthentication flow for supported sensitive
+        actions.
+      parameters:
+      - description: 'Supported values: pin_reset_request, pin_reset_confirm'
+        in: query
+        name: purpose
+        required: true
+        type: string
+      - description: Required when purpose=pin_reset_confirm
+        in: query
+        name: token
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MicrosoftLoginResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Microsoft Entra SSO reauth URL
+      tags:
+      - Auth
+  /api/v1/auth/microsoft/refresh:
+    post:
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.TokenResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "428":
+          description: Precondition Required
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Refresh Microsoft access token
+      tags:
+      - Auth - SSO
+  /api/v1/auth/pin/change:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - description: JSON:API security PIN change request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.SecurityPINChangeRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "429":
+          description: Too Many Requests
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Change security PIN
+      tags:
+      - Auth - PIN
+  /api/v1/auth/pin/forgot:
+    post:
+      consumes:
+      - application/json
+      description: Always returns a generic success response.
+      parameters:
+      - description: JSON:API forgot security PIN request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ForgotSecurityPINRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Forgot security PIN
+      tags:
+      - Auth - PIN
+  /api/v1/auth/pin/request-reset:
+    post:
+      consumes:
+      - application/json
+      description: Verifies current account password, then sends PIN reset email to
+        currently logged-in user when PIN is blocked.
+      parameters:
+      - description: JSON:API request security PIN reset payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.RequestSecurityPINRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.RequestSecurityPINResetResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "429":
+          description: Too Many Requests
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Request security PIN reset email for blocked PIN
+      tags:
+      - Auth - PIN
+  /api/v1/auth/pin/reset:
+    post:
+      consumes:
+      - application/json
+      description: Resets security PIN using a re-auth method. For method=password,
+        send the single-use reset token from the email link plus password. For method=microsoft,
+        send only reauth_token from Microsoft re-auth.
+      parameters:
+      - description: JSON:API reset security PIN request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ResetSecurityPINRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Reset security PIN
+      tags:
+      - Auth - PIN
+  /api/v1/auth/pin/setup:
+    post:
+      consumes:
+      - application/json
+      description: Creates a 6-digit security PIN for sensitive actions.
+      parameters:
+      - description: JSON:API security PIN setup request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.SecurityPINSetupRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.SecurityPINSetupResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Setup security PIN
+      tags:
+      - Auth - PIN
+  /api/v1/auth/pin/verify:
+    post:
+      consumes:
+      - application/json
+      description: Verifies PIN and returns a short-lived one-time action token.
+      parameters:
+      - description: JSON:API security PIN verify request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.SecurityPINVerifyRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.SecurityPINVerifyResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "429":
+          description: Too Many Requests
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Verify security PIN for sensitive action
+      tags:
+      - Auth - PIN
+  /api/v1/auth/refresh:
+    post:
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.TokenResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Refresh access token
+      tags:
+      - Auth - Refresh
+  /api/v1/auth/register:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Creates user (public role: from AUTH_DEFAULT_ROLE, fallback: user) and sends verification link to email without issuing an auth session.
+        Next: open verify link -> then login.
+      parameters:
+      - description: JSON:API Register request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.RegisterRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.UserResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Register user with email & password
+      tags:
+      - Auth
+  /api/v1/auth/reset-password:
+    post:
+      consumes:
+      - application/json
+      description: Resets password using a single-use reset token.
+      parameters:
+      - description: JSON:API Reset password request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ResetPasswordRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Reset password
+      tags:
+      - Auth - Forgot Password
+  /api/v1/auth/sessions:
+    get:
+      description: Lists all active sessions/devices for current user.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List active sessions
+      tags:
+      - Auth - Refresh
+  /api/v1/auth/sessions/{session_id}:
+    delete:
+      description: Revokes one session/device immediately. Requires PIN action token
+        (header X-PIN-Verification-Token) with action=3d7d1d5f-ec48-4eca-a7ea-37f4f7927d06.
+      parameters:
+      - description: Session ID
+        in: path
+        name: session_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete one session
+      tags:
+      - Auth - Refresh
+  /api/v1/auth/set-password:
+    post:
+      consumes:
+      - application/json
+      description: Sets first password for invited user and marks email as verified.
+      parameters:
+      - description: JSON:API Set password request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.SetPasswordRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnResetSetupResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Set password from invite token
+      tags:
+      - Auth
+  /api/v1/auth/sso/link:
+    post:
+      consumes:
+      - application/json
+      description: Link Microsoft SSO identity to the authenticated user. SSO login
+        will only work after successful link.
+      parameters:
+      - description: JSON:API SSO link request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.SSOLinkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.SSOLinkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      security:
+      - BearerAuth: []
+      summary: Link Microsoft SSO to current user
+      tags:
+      - Auth
+  /api/v1/auth/sso/unlink:
+    delete:
+      consumes:
+      - application/json
+      description: Remove Microsoft SSO mapping from authenticated user.
+      parameters:
+      - description: JSON:API SSO unlink request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.SSOUnlinkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.SSOUnlinkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      security:
+      - BearerAuth: []
+      summary: Unlink Microsoft SSO from current user
+      tags:
+      - Auth
+  /api/v1/auth/totp/confirm:
+    post:
+      consumes:
+      - application/json
+      description: Validates initial TOTP code and enables TOTP for future logins.
+      parameters:
+      - description: JSON:API TOTP confirm request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPConfirmRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Confirm TOTP setup
+      tags:
+      - Auth - TOTP
+  /api/v1/auth/totp/disable:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - description: JSON:API TOTP disable request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPDisableRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Disable TOTP
+      tags:
+      - Auth - TOTP
+  /api/v1/auth/totp/reset-setup:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Removes TOTP setup so the user can re-setup authenticator.
+        For method=pin, obtain token from /auth/pin/verify with action=0b5409b5-94f3-4aab-9de2-44b0ad5858f1 and send it in X-PIN-Verification-Token header.
+      parameters:
+      - description: JSON:API TOTP reset setup request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPResetSetupRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.VerifyEmailResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "429":
+          description: Too Many Requests
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Reset TOTP setup
+      tags:
+      - Auth - TOTP
+  /api/v1/auth/totp/setup:
+    post:
+      consumes:
+      - application/json
+      description: Generates secret and otpauth URL. TOTP is NOT enabled until confirmed.
+      parameters:
+      - description: JSON:API TOTP setup request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPSetupRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPSetupResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Setup TOTP
+      tags:
+      - Auth - TOTP
+  /api/v1/auth/totp/verify:
+    post:
+      consumes:
+      - application/json
+      description: Completes login when TOTP is enabled and returns auth cookies.
+      parameters:
+      - description: JSON:API TOTP verify request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.TOTPVerifyRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.TokenResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Verify TOTP code
+      tags:
+      - Auth - TOTP
+  /api/v1/auth/verify-email:
+    get:
+      description: Confirms email verification after register.
+      parameters:
+      - description: Verification token
+        in: query
+        name: token
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Verify email
+      tags:
+      - Auth
+  /api/v1/auth/webauthn/login/begin:
+    post:
+      consumes:
+      - application/json
+      description: Creates WebAuthn assertion options for a user email.
+      parameters:
+      - description: JSON:API WebAuthn login begin request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginBeginRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnBeginResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Begin WebAuthn login
+      tags:
+      - Auth - WebAuthn
+  /api/v1/auth/webauthn/login/finish:
+    post:
+      consumes:
+      - application/json
+      description: Verifies WebAuthn assertion and issues auth cookies.
+      parameters:
+      - description: JSON:API WebAuthn login finish request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnLoginFinishRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.TokenResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Finish WebAuthn login
+      tags:
+      - Auth - WebAuthn
+  /api/v1/auth/webauthn/register/begin:
+    post:
+      consumes:
+      - application/json
+      description: Creates WebAuthn registration options for the authenticated user.
+      parameters:
+      - description: JSON:API WebAuthn register begin request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterBeginRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnBeginResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Begin WebAuthn registration
+      tags:
+      - Auth - WebAuthn
+  /api/v1/auth/webauthn/register/finish:
+    post:
+      consumes:
+      - application/json
+      description: Verifies WebAuthn registration response and stores the credential.
+      parameters:
+      - description: JSON:API WebAuthn register finish request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnRegisterFinishRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthSessionsResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Finish WebAuthn registration
+      tags:
+      - Auth - WebAuthn
+  /api/v1/auth/webauthn/reset-setup:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Removes all registered WebAuthn credentials so the user can re-setup passkeys.
+        For method=pin, obtain token from /auth/pin/verify with action=1f7d457e-0a19-4a36-8d9f-2c66fd2369ab and send it in X-PIN-Verification-Token header.
+      parameters:
+      - description: JSON:API WebAuthn reset setup request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.WebAuthnResetSetupRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.AuthSessionDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "429":
+          description: Too Many Requests
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Reset WebAuthn setup
+      tags:
+      - Auth - WebAuthn
+  /api/v1/bases/create:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Example request:
+        {"data":{"type":"base","attributes":{"base":"Lude Testing 2","base_abbreviation":"LOIG","base_category":"regular","address":"Lude Airfield","latitude":47.3769,"longitude":8.5417,"sortkey":1,"sms_alert":false,"checklist":false,"leg_time":"00:20","default_start_time_type":"FIXED","default_end_time_type":"FIXED","default_shift_start":"06:00","default_shift_end":"21:00","utc":"0","notes":"Main base","operational_shift_times":[{"date_start":"2026-06-15","date_end":"2026-06-15","start_time_type":"BMCT","end_time_type":"ECET"}]}}}
+      parameters:
+      - description: JSON:API base create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.BaseCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.BaseResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create base
+      tags:
+      - Bases
+  /api/v1/bases/delete/{uuid}:
+    delete:
+      parameters:
+      - description: Base UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.BaseDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete base
+      tags:
+      - Bases
+  /api/v1/bases/get-all:
+    get:
+      description: JSON:API list with filtering and sorting. This endpoint returns
+        all bases.
+      parameters:
+      - description: Base category
+        enum:
+        - regular
+        - hems
+        in: query
+        name: category_type
+        type: string
+      - description: Alias filter for base category
+        enum:
+        - regular
+        - hems
+        in: query
+        name: base_category
+        type: string
+      - description: Search by base/base_abbreviation/address/email/phone
+        in: query
+        name: search
+        type: string
+      - description: Filter by DUL flag (true/false)
+        in: query
+        name: dul
+        type: boolean
+      - description: Ignored
+        in: query
+        name: page
+        type: integer
+      - description: Ignored
+        in: query
+        name: size
+        type: integer
+      - description: Ignored
+        in: query
+        name: limit
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.BaseListResponse'
+      summary: List bases
+      tags:
+      - Bases
+  /api/v1/bases/get-all/dt:
+    get:
+      parameters:
+      - description: Base category
+        enum:
+        - regular
+        - hems
+        in: query
+        name: category_type
+        type: string
+      - description: Alias filter for base category
+        enum:
+        - regular
+        - hems
+        in: query
+        name: base_category
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      - description: Filter by DUL flag (true/false)
+        in: query
+        name: dul
+        type: boolean
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.BaseDataTableResponse'
+      summary: List bases (datatable)
+      tags:
+      - Bases
+  /api/v1/bases/get/{uuid}:
+    get:
+      parameters:
+      - description: Base UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.BaseResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get base by ID
+      tags:
+      - Bases
+  /api/v1/bases/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: |-
+        Example request:
+        {"data":{"type":"hems_base","id":"<uuid>","attributes":{"base":"Lude Testing 2","base_abbreviation":"LOIG","base_category":"regular","address":"Lude Airfield","latitude":47.3769,"longitude":8.5417,"sortkey":1,"sms_alert":false,"checklist":false,"leg_time":"00:20","default_start_time_type":"FIXED","default_end_time_type":"FIXED","default_shift_start":"06:00","default_shift_end":"21:00","utc":"0","notes":"Main base","operational_shift_times":[{"date_start":"2026-06-15","date_end":"2026-06-15","start_time_type":"BMCT","end_time_type":"ECET"}]}}}
+      parameters:
+      - description: Base UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API base update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.BaseUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.BaseResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update base
+      tags:
+      - Bases
+  /api/v1/branding/login-content:
+    get:
+      description: |-
+        Return public stable login title and subtitle from active master settings with backend defaults.
+        Supports conditional requests with `If-None-Match` / `If-Modified-Since`.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/internal_transport_http_handlers.loginBrandingContentDocument'
+        "304":
+          description: Not Modified
+          schema:
+            type: string
+      summary: Get login content
+      tags:
+      - Branding
+  /api/v1/branding/login-cover:
+    get:
+      description: |-
+        Return public stable login cover image for sign-in page.
+        Supports conditional requests with `If-None-Match` / `If-Modified-Since`.
+      produces:
+      - image/png
+      - image/jpeg
+      - image/webp
+      - image/svg+xml
+      - application/octet-stream
+      responses:
+        "200":
+          description: Login cover image binary
+          schema:
+            type: file
+        "304":
+          description: Not Modified
+          schema:
+            type: string
+      summary: Get login cover image
+      tags:
+      - Branding
+  /api/v1/branding/logo:
+    get:
+      description: |-
+        Return a stable company logo asset for frontend consumption.
+        Backend resolves private object storage internally (no presigned URL exposure) and serves fallback logo when managed logo is unavailable.
+        Supports conditional requests with `If-None-Match` / `If-Modified-Since`.
+      produces:
+      - image/png
+      - image/jpeg
+      - image/webp
+      - image/svg+xml
+      - application/octet-stream
+      responses:
+        "200":
+          description: Branding logo binary
+          schema:
+            type: file
+        "304":
+          description: Not Modified
+          schema:
+            type: string
+      summary: Get branding logo
+      tags:
+      - Branding
+  /api/v1/complaints/action-taken/create/{id}:
+    post:
+      consumes:
+      - application/json
+      description: 'Records the corrective action text taken for a complaint. Recording
+        the action does NOT sign it and does NOT lift the AOG grounding: signing the
+        action is a separate step at POST /api/v1/action-signoffs/sign/{helicopter_id}
+        (send complaint_id), and returning the aircraft to service requires a formal
+        release (a signed EASA release / CRS, or an NSR). The complaint stays open
+        until an EASA release fixes it.'
+      parameters:
+      - description: Complaint ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Action taken payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintActionTakenRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Record the corrective action for a complaint
+      tags:
+      - Complaints
+  /api/v1/complaints/action-taken/update/{id}:
+    patch:
+      consumes:
+      - application/json
+      description: Updates the previously-recorded corrective action text of a complaint.
+        Recording/updating the action does NOT sign it — signing is a separate step
+        at POST /api/v1/action-signoffs/sign/{helicopter_id} (send complaint_id).
+      parameters:
+      - description: Complaint ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Action taken payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintActionTakenRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update the recorded corrective action for a complaint
+      tags:
+      - Complaints
+  /api/v1/complaints/create:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Create a complaint (defect) for a flight inspection.
+        MEL severity (mel_severity, OPTIONAL): omit it to file a "pending_mel" complaint and classify later (via PATCH /complaints/update/{id}); it MUST be classified before recording action taken. A pending complaint does NOT ground the aircraft — grounding starts at classification. Values: 0 = NON-MEL (grounds immediately); 1 = A (1 day grace); 2 = B (3 days); 3 = C (10 days); 4 = D (120 days). After the grace period passes without action the aircraft becomes AOG.
+        NSR (Non-Safety Release) is its own flow — sign it at POST /api/v1/complaints/nsr/sign/{id} (cancel at /nsr/unsign/{id}); it is no longer set via create/update.
+        Optional fields: aircraft_hours_at_report.
+        To record the corrective action, use POST /api/v1/complaints/action-taken/create/{id} (a separate, explicitly-signed step) — it is no longer part of create/update.
+      parameters:
+      - description: JSON:API complaint create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create complaint
+      tags:
+      - Complaints
+  /api/v1/complaints/delete/{id}:
+    delete:
+      parameters:
+      - description: Complaint ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.Document'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete complaint
+      tags:
+      - Complaints
+  /api/v1/complaints/get-all:
+    get:
+      description: Lists complaints grouped by helicopter. Filter by date range on
+        the reported date, by the name of an involved person (reporter / MEL classifier
+        / action signer / NSR decider — i.e. pilot/techniker), and by free-text search
+        on the complaint description.
+      parameters:
+      - description: Search complaint description
+        in: query
+        name: search
+        type: string
+      - description: Reported date lower bound (YYYY-MM-DD)
+        in: query
+        name: date_from
+        type: string
+      - description: Reported date upper bound (YYYY-MM-DD)
+        in: query
+        name: date_to
+        type: string
+      - description: Involved person name (pilot/techniker, partial match)
+        in: query
+        name: person
+        type: string
+      - description: Filter by helicopter ID (UUIDv7)
+        in: query
+        name: helicopter_id
+        type: string
+      - description: Sort complaints
+        in: query
+        name: sort
+        type: string
+      - default: 1
+        description: Page number
+        in: query
+        name: page
+        type: integer
+      - default: 20
+        description: Page size
+        in: query
+        name: page_size
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse'
+      summary: List complaints
+      tags:
+      - Complaints
+  /api/v1/complaints/get-all/dt:
+    get:
+      parameters:
+      - description: Search complaint description
+        in: query
+        name: search
+        type: string
+      - description: Reported date lower bound (YYYY-MM-DD)
+        in: query
+        name: date_from
+        type: string
+      - description: Reported date upper bound (YYYY-MM-DD)
+        in: query
+        name: date_to
+        type: string
+      - description: Involved person name (pilot/techniker, partial match)
+        in: query
+        name: person
+        type: string
+      - description: Filter by helicopter ID (UUIDv7)
+        in: query
+        name: helicopter_id
+        type: string
+      - description: Sort complaints
+        in: query
+        name: sort
+        type: string
+      - default: 1
+        description: Datatable draw counter
+        in: query
+        name: draw
+        type: integer
+      - default: 0
+        description: Datatable start offset
+        in: query
+        name: start
+        type: integer
+      - default: 10
+        description: Datatable page length
+        in: query
+        name: length
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedDataTableResponse'
+      summary: List complaints grouped by helicopter (datatable)
+      tags:
+      - Complaints
+  /api/v1/complaints/get-by-helicopter/{helicopter_id}:
+    get:
+      parameters:
+      - description: Helicopter ID
+        in: path
+        name: helicopter_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse'
+      summary: List complaints by helicopter
+      tags:
+      - Complaints
+  /api/v1/complaints/get/{id}:
+    get:
+      parameters:
+      - description: Complaint ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get complaint by ID
+      tags:
+      - Complaints
+  /api/v1/complaints/hold-items/get-all:
+    get:
+      description: 'Returns the Hold Item List (HIL): complaints that are still OPEN
+        (not yet fixed by an EASA release) AND MEL-deferred (mel_severity > 0). Non-MEL
+        defects (which ground the aircraft immediately) and already-serviced complaints
+        are excluded. Same grouped shape and filters as get-all.'
+      parameters:
+      - description: From date — reported_at >= (YYYY-MM-DD). Legacy 'Von'.
+        in: query
+        name: date_from
+        type: string
+      - description: To date — reported_at <= (YYYY-MM-DD). Legacy 'bis'.
+        in: query
+        name: date_to
+        type: string
+      - description: Pilot/Technician name — matches reporter or action signer. Legacy
+          'Pilot/Techniker'.
+        in: query
+        name: person
+        type: string
+      - description: Search complaint description / MEL. Legacy 'Complains'.
+        in: query
+        name: search
+        type: string
+      - description: Helicopter ID (UUIDv7)
+        in: query
+        name: helicopter_id
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20)
+        in: query
+        name: page_size
+        type: integer
+      - description: Sort expression (e.g. reported_at DESC)
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List hold items (open MEL-deferred defects)
+      tags:
+      - Complaints
+  /api/v1/complaints/hold-items/get-all/dt:
+    get:
+      description: Datatable variant of the Hold Item List (open + MEL-deferred complaints).
+        Same filters as /hold-items/get-all (date_from, date_to, person, search, helicopter_id)
+        plus DataTables params (start, length, draw).
+      parameters:
+      - description: From date — reported_at >= (YYYY-MM-DD). Legacy 'Von'.
+        in: query
+        name: date_from
+        type: string
+      - description: To date — reported_at <= (YYYY-MM-DD). Legacy 'bis'.
+        in: query
+        name: date_to
+        type: string
+      - description: Pilot/Technician name — matches reporter or action signer.
+        in: query
+        name: person
+        type: string
+      - description: Search complaint description / MEL.
+        in: query
+        name: search
+        type: string
+      - description: Helicopter ID (UUIDv7)
+        in: query
+        name: helicopter_id
+        type: string
+      - description: DataTables start offset
+        in: query
+        name: start
+        type: integer
+      - description: DataTables page length
+        in: query
+        name: length
+        type: integer
+      - description: DataTables draw counter
+        in: query
+        name: draw
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintGroupedListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List hold items (open MEL-deferred defects) — datatable
+      tags:
+      - Complaints
+  /api/v1/complaints/nsr/sign/{id}:
+    post:
+      consumes:
+      - application/json
+      description: 'Records an NSR decision on its own flow (separate from complaint
+        update): the aircraft is released to fly despite the open defect and is no
+        longer grounded by it. MEL must be classified first — an unassessed (pending_mel)
+        defect cannot be deferred, so a pending complaint returns 422. The complaint
+        stays OPEN and is only closed by a signed EASA release. Requires the complaint.nsr
+        permission.'
+      parameters:
+      - description: Complaint ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Optional NSR reason
+        in: body
+        name: request
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintNSRSignRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Sign a Non-Safety Release (NSR / MEL deferral) for a complaint
+      tags:
+      - Complaints
+  /api/v1/complaints/nsr/unsign/{id}:
+    post:
+      description: 'Revokes the NSR decision: the deferral is lifted, so the still-open
+        defect grounds the aircraft again (AOG is recomputed). Requires the complaint.nsr
+        permission.'
+      parameters:
+      - description: Complaint ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Cancel a Non-Safety Release for a complaint
+      tags:
+      - Complaints
+  /api/v1/complaints/update/{id}:
+    patch:
+      consumes:
+      - application/json
+      description: |-
+        Update a complaint. All attributes optional; only provided fields change.
+        mel_severity: 0 = NON-MEL (immediate AOG); 1 = A (1 day); 2 = B (3 days); 3 = C (10 days); 4 = D (120 days) — AOG after grace passes.
+        NSR is not set here — it is its own flow: POST /api/v1/complaints/nsr/sign/{id} (and /nsr/unsign/{id}).
+        Note: the corrective action is recorded via POST /api/v1/complaints/action-taken/create/{id} (a separate, signed step), not here.
+      parameters:
+      - description: Complaint ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: JSON:API complaint update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ComplaintUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ComplaintResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update complaint
+      tags:
+      - Complaints
+  /api/v1/contact/other:
+    get:
+      description: Lists master other-people whose name/mobile_phone/email matches
+        `q` (empty `q` = most recent). Pick one and pass its id as `other_person_id`
+        in a takeover's other_person to reuse without re-entering the data.
+      parameters:
+      - description: Search text (name / mobile_phone / email)
+        in: query
+        name: q
+        type: string
+      - description: Max results (default 20)
+        in: query
+        name: limit
+        type: integer
+      - description: Offset
+        in: query
+        name: offset
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.OtherPersonListResponse'
+      summary: Search reusable "other people" (non-staff) for the takeover picker
+      tags:
+      - Contact - Other People
+  /api/v1/contact/other/create:
+    post:
+      consumes:
+      - application/json
+      description: Registers a person in the other-people master so it can be reused
+        across takeovers. The (name, mobile_phone, email) identity must be unique.
+      parameters:
+      - description: Other person
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.OtherPersonRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResponse'
+      summary: Create a reusable "other person" (non-staff)
+      tags:
+      - Contact - Other People
+  /api/v1/contact/other/delete/{id}:
+    delete:
+      description: Soft-deletes a master person. Existing takeover snapshots keep
+        their own copy of the data.
+      parameters:
+      - description: Other person id
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+      summary: Delete a reusable "other person"
+      tags:
+      - Contact - Other People
+  /api/v1/contact/other/get/{id}:
+    get:
+      parameters:
+      - description: Other person id
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResponse'
+      summary: Get one reusable "other person"
+      tags:
+      - Contact - Other People
+  /api/v1/contact/other/update/{id}:
+    patch:
+      consumes:
+      - application/json
+      description: Replaces the name/mobile_phone/email of a master person. The new
+        identity must not collide with another person.
+      parameters:
+      - description: Other person id
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Other person
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.OtherPersonRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.OtherPersonResponse'
+      summary: Update a reusable "other person"
+      tags:
+      - Contact - Other People
+  /api/v1/contacts/{user_id}:
+    delete:
+      parameters:
+      - description: User UUID
+        in: path
+        name: user_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ContactListResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete contact
+      tags:
+      - Contacts
+    get:
+      parameters:
+      - description: User UUID
+        in: path
+        name: user_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ContactListResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get contact
+      tags:
+      - Contacts
+    patch:
+      consumes:
+      - application/json
+      description: |-
+        `data.type` must be `contact_update`.
+        Supports updating `role_id` and `role_ids` (multiple roles) in the same request. Sending `role_ids: []` clears all assigned roles.
+        Only one role-specific profile object is allowed in `attributes`. If provided, it must match one of the contact's assigned roles.
+      parameters:
+      - description: User UUID
+        in: path
+        name: user_id
+        required: true
+        type: string
+      - description: JSON:API Contact update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ContactUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ContactListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update contact
+      tags:
+      - Contacts
+  /api/v1/contacts/{user_id}/chief-flags:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: User UUID
+        in: path
+        name: user_id
+        required: true
+        type: string
+      - description: JSON:API chief flags request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ContactChiefFlagsUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ContactListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update chief flags
+      tags:
+      - Contacts
+  /api/v1/contacts/{user_id}/license:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: User UUID
+        in: path
+        name: user_id
+        required: true
+        type: string
+      - description: JSON:API license update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ContactLicenseUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ContactListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update contact license fields
+      tags:
+      - Contacts
+  /api/v1/contacts/{user_id}/pilot-category:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: User UUID
+        in: path
+        name: user_id
+        required: true
+        type: string
+      - description: JSON:API pilot category request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ContactPilotCategoryUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ContactListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update pilot category
+      tags:
+      - Contacts
+  /api/v1/contacts/{user_id}/role:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: User UUID
+        in: path
+        name: user_id
+        required: true
+        type: string
+      - description: JSON:API role update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ContactRoleUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ContactListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update contact role
+      tags:
+      - Contacts
+  /api/v1/contacts/{user_id}/status:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: User UUID
+        in: path
+        name: user_id
+        required: true
+        type: string
+      - description: JSON:API status update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ContactStatusUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ContactSimpleSuccessResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update contact active status
+      tags:
+      - Contacts
+  /api/v1/contacts/bulk-update:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - description: JSON:API bulk update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ContactBulkUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ContactSimpleSuccessResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Bulk update contacts status
+      tags:
+      - Contacts
+  /api/v1/contacts/create:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Create new contact user and role-specific profile.
+        `data.type` must be `contact_create`.
+        `role_ids` determines roles (use `role_id` only for backward compatibility). Every selected role must include its matching role-specific profile object in `attributes`.
+      parameters:
+      - description: JSON:API Contact create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ContactCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ContactListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create contact
+      tags:
+      - Contacts
+  /api/v1/contacts/get-all:
+    get:
+      description: 'Filter contacts by role and pilot_category. Sort values: name,
+        -name, first_name, -first_name, last_name, -last_name, email, -email, sortkey,
+        -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at,
+        -updated_at.'
+      parameters:
+      - description: 'Role: pilot|doctor|air_rescuer|technician|flight_assistant|staff'
+        in: query
+        name: role
+        type: string
+      - description: 'Pilot category: regular|freelance|dry_lease'
+        in: query
+        name: pilot_category
+        type: string
+      - description: Filter doctor chief flag
+        in: query
+        name: chief_doctor
+        type: boolean
+      - description: Filter technician chief flag
+        in: query
+        name: chief_technician
+        type: boolean
+      - description: Filter responsible complaint flag
+        in: query
+        name: responsible_complaint
+        type: boolean
+      - description: Filter pilot chief flag
+        in: query
+        name: chief_pilot
+        type: boolean
+      - description: Filter IFR qualified flag
+        in: query
+        name: ifr_qualified
+        type: boolean
+      - description: Search by username/email/name
+        in: query
+        name: search
+        type: string
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      - description: Limit (default 20)
+        in: query
+        name: limit
+        type: integer
+      - description: Offset (default 0)
+        in: query
+        name: offset
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ContactListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List contacts
+      tags:
+      - Contacts
+  /api/v1/contacts/get-all/dt:
+    get:
+      description: Datatable response with pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 1000)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      - description: Role filter
+        in: query
+        name: role
+        type: string
+      - description: Pilot category filter
+        in: query
+        name: pilot_category
+        type: string
+      - description: Filter doctor chief flag
+        in: query
+        name: chief_doctor
+        type: boolean
+      - description: Filter technician chief flag
+        in: query
+        name: chief_technician
+        type: boolean
+      - description: Filter responsible complaint flag
+        in: query
+        name: responsible_complaint
+        type: boolean
+      - description: Filter pilot chief flag
+        in: query
+        name: chief_pilot
+        type: boolean
+      - description: Filter IFR qualified flag
+        in: query
+        name: ifr_qualified
+        type: boolean
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ContactDataTableResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List contacts (datatable)
+      tags:
+      - Contacts
+  /api/v1/dul/create:
+    post:
+      consumes:
+      - application/json
+      description: 'Possible error code: DUL_INVALID_JSON, DUL_INVALID_UUID, DUL_DATE_INVALID,
+        DUL_VALIDATION_FAILED, DUL_CREATE_FAILED.'
+      parameters:
+      - description: DUL create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.DULCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.DULResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create DUL
+      tags:
+      - DUL
+  /api/v1/dul/delete/{id}:
+    delete:
+      description: 'Possible error code: DUL_INVALID_UUID, DUL_DELETE_FAILED.'
+      parameters:
+      - description: DUL ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.DULDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete DUL
+      tags:
+      - DUL
+  /api/v1/dul/get-all:
+    get:
+      description: 'Possible error code: DUL_LIST_FAILED.'
+      parameters:
+      - description: Search by name/info
+        in: query
+        name: search
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Page number alias
+        in: query
+        name: page
+        type: integer
+      - description: Page size alias
+        in: query
+        name: size
+        type: integer
+      - description: Page size alias
+        in: query
+        name: limit
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.DULListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List DUL grouped by base
+      tags:
+      - DUL
+  /api/v1/dul/get-all/dt:
+    get:
+      description: 'Possible error code: DUL_LIST_FAILED.'
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search by name/info
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.DULDataTableResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List DUL grouped by base (datatable)
+      tags:
+      - DUL
+  /api/v1/dul/get/{id}:
+    get:
+      description: 'Possible error code: DUL_INVALID_UUID, DUL_NOT_FOUND.'
+      parameters:
+      - description: DUL ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.DULResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get DUL by ID
+      tags:
+      - DUL
+  /api/v1/dul/update/{id}:
+    patch:
+      consumes:
+      - application/json
+      description: 'Possible error code: DUL_INVALID_JSON, DUL_INVALID_UUID, DUL_DATE_INVALID,
+        DUL_VALIDATION_FAILED, DUL_NOT_FOUND, DUL_UPDATE_FAILED.'
+      parameters:
+      - description: DUL ID
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: DUL update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.DULUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.DULResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update DUL
+      tags:
+      - DUL
+  /api/v1/duty-roster/create:
+    post:
+      consumes:
+      - application/json
+      description: Unified endpoint for all base categories.
+      parameters:
+      - description: Create request payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create duty roster
+      tags:
+      - Flights - Duty Roster
+  /api/v1/duty-roster/crew:
+    delete:
+      consumes:
+      - application/json
+      description: Unified crew delete endpoint by `data.id` and `roster_detail`.
+      parameters:
+      - description: Crew delete request payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterDeleteCrewByIDRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterCrewDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Remove duty roster crew assignment
+      tags:
+      - Flights - Duty Roster
+  /api/v1/duty-roster/delete:
+    delete:
+      consumes:
+      - application/json
+      description: Unified delete endpoint by `data.id`.
+      parameters:
+      - description: Delete request payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterAnyDeleteRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete duty roster
+      tags:
+      - Flights - Duty Roster
+  /api/v1/duty-roster/get-all:
+    get:
+      description: Combined roster list across HEMS and Base for date range and optional
+        base filters.
+      parameters:
+      - description: HEMS base UUID
+        in: query
+        name: hems_base_id
+        type: string
+      - description: Base UUID
+        in: query
+        name: base_id
+        type: string
+      - description: Filter by base name (contains, case-insensitive)
+        in: query
+        name: base_name
+        type: string
+      - description: Start date (YYYY-MM-DD)
+        in: query
+        name: from
+        type: string
+      - description: End date (YYYY-MM-DD)
+        in: query
+        name: to
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.Document'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List all rosters (HEMS + Base)
+      tags:
+      - Flights - Duty Roster
+  /api/v1/duty-roster/get-all/dt:
+    get:
+      description: 'Unified datatable endpoint. Optional `base_type` filter: `hems`
+        or `base`.'
+      parameters:
+      - description: Base type filter (hems|base)
+        in: query
+        name: base_type
+        type: string
+      - description: Base UUID
+        in: query
+        name: base_id
+        type: string
+      - description: Filter by base name
+        in: query
+        name: base_name
+        type: string
+      - description: Start date (YYYY-MM-DD)
+        in: query
+        name: from
+        type: string
+      - description: End date (YYYY-MM-DD)
+        in: query
+        name: to
+        type: string
+      - description: Page number
+        in: query
+        name: page
+        type: integer
+      - description: Page size
+        in: query
+        name: size
+        type: integer
+      - description: Page size override
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter
+        in: query
+        name: draw
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterGroupedDataTableResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List duty roster (datatable)
+      tags:
+      - Flights - Duty Roster
+  /api/v1/duty-roster/update:
+    patch:
+      consumes:
+      - application/json
+      description: Unified update endpoint by `data.id`.
+      parameters:
+      - description: Update request payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.DutyRosterUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.DutyRosterResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update duty roster (partial)
+      tags:
+      - Flights - Duty Roster
+  /api/v1/easa-releases/create:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - description: JSON:API EASA release create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse'
+      summary: Create EASA maintenance release (draft) for a helicopter
+      tags:
+      - EASA Releases
+  /api/v1/easa-releases/delete/{id}:
+    delete:
+      parameters:
+      - description: EASA release ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseDeleteResponse'
+      summary: Delete (void) an EASA release
+      tags:
+      - EASA Releases
+  /api/v1/easa-releases/get-by-complaint/{complaint_id}:
+    get:
+      parameters:
+      - description: Complaint ID (UUIDv7)
+        in: path
+        name: complaint_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse'
+      summary: Get the current EASA release for a complaint
+      tags:
+      - EASA Releases
+  /api/v1/easa-releases/get-by-flight/{flight_id}:
+    get:
+      parameters:
+      - description: Flight ID (UUIDv7)
+        in: path
+        name: flight_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse'
+      summary: Get the current EASA release for a flight
+      tags:
+      - EASA Releases
+  /api/v1/easa-releases/get-by-helicopter/{helicopter_id}:
+    get:
+      parameters:
+      - description: Helicopter ID (UUIDv7)
+        in: path
+        name: helicopter_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseListResponse'
+      summary: List EASA releases for a helicopter
+      tags:
+      - EASA Releases
+  /api/v1/easa-releases/get/{id}:
+    get:
+      parameters:
+      - description: EASA release ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse'
+      summary: Get EASA release by ID
+      tags:
+      - EASA Releases
+  /api/v1/easa-releases/sign/{id}:
+    post:
+      description: 'Signs the release and closes the helicopter''s open complaints.
+        The corrective-action sign-off is re-checked at sign time: if the sign-off
+        was invalidated since the draft was created (e.g. its complaint was reopened)
+        it returns 422 `EASA_RELEASE_SIGNOFF_REQUIRED` and does not sign.'
+      parameters:
+      - description: EASA release ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Sign the EASA maintenance release (closes the helicopter's open complaints)
+      tags:
+      - EASA Releases
+  /api/v1/easa-releases/update/{id}:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: EASA release ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: JSON:API EASA release update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.EASAReleaseUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.EASAReleaseResponse'
+      summary: Update EASA release (draft fields)
+      tags:
+      - EASA Releases
+  /api/v1/facilities/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a facility row using one shared table. Flight-data SPO references
+        now expect categories like `heslo-rope-label`, `heslo-rope-length`, `heslo-hook`,
+        `hec-rope-label`, and `hec-rope-length`.
+      parameters:
+      - description: JSON:API Facility create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create facility
+      tags:
+      - Facility - Facilities
+  /api/v1/facilities/delete/{uuid}:
+    delete:
+      parameters:
+      - description: Facility UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete facility
+      tags:
+      - Facility - Facilities
+  /api/v1/facilities/get-all:
+    get:
+      description: JSON:API list with pagination, filtering and sorting. Supports
+        one shared table with category discriminator (e.g. `heslo-rope-label`, `heslo-hook`,
+        `hec-rope-label`).
+      parameters:
+      - description: Search by name/type/length/weight
+        in: query
+        name: search
+        type: string
+      - description: Filter by category (e.g. heslo-rope-label, heslo-hook, hec-rope-label)
+        in: query
+        name: category
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityListResponse'
+      summary: List facilities
+      tags:
+      - Facility - Facilities
+  /api/v1/facilities/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      - description: Facility category
+        in: query
+        name: category
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityDataTableResponse'
+      summary: List facilities (datatable)
+      tags:
+      - Facility - Facilities
+  /api/v1/facilities/get/{uuid}:
+    get:
+      parameters:
+      - description: Facility UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get facility by ID
+      tags:
+      - Facility - Facilities
+  /api/v1/facilities/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch facility by ID.
+      parameters:
+      - description: Facility UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API Facility update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FacilityResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update facility (partial)
+      tags:
+      - Facility - Facilities
+  /api/v1/federal-state/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a federal state row.
+      parameters:
+      - description: JSON:API federal state create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create federal state
+      tags:
+      - Hospital - Federal State
+  /api/v1/federal-state/delete/{id}:
+    delete:
+      parameters:
+      - description: Federal State ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete federal state
+      tags:
+      - Hospital - Federal State
+  /api/v1/federal-state/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        name, -name, sortkey, -sortkey, is_active, -is_active, created_at, -created_at,
+        updated_at, -updated_at.'
+      parameters:
+      - description: Search by name
+        in: query
+        name: filter[search]
+        type: string
+      - description: Filter federal state by land UUID
+        in: query
+        name: land_id
+        type: string
+      - description: Filter federal state by land name
+        in: query
+        name: land_name
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateListResponse'
+      summary: List federal state
+      tags:
+      - Hospital - Federal State
+  /api/v1/federal-state/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      - description: Search by name
+        in: query
+        name: filter[search]
+        type: string
+      - description: Filter federal state by land UUID
+        in: query
+        name: land_id
+        type: string
+      - description: Filter federal state by land name
+        in: query
+        name: land_name
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateDataTableResponse'
+      summary: List federal state (datatable)
+      tags:
+      - Hospital - Federal State
+  /api/v1/federal-state/update/{id}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch federal state by ID.
+      parameters:
+      - description: Federal State ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: JSON:API federal state update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FederalStateResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update federal state (partial)
+      tags:
+      - Hospital - Federal State
+  /api/v1/file-manager/attachments/create:
+    post:
+      consumes:
+      - application/json
+      description: Create generic attachment relation between a file and business
+        reference (ref_type/ref_id).
+      operationId: FileManagerCreateAttachment
+      parameters:
+      - description: JSON:API attachment create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerAttachmentCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Attach file to business reference
+      tags:
+      - File Manager
+  /api/v1/file-manager/attachments/delete/{uuid}:
+    delete:
+      description: Remove generic attachment relation by UUID.
+      operationId: FileManagerDeleteAttachment
+      parameters:
+      - description: Attachment UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Detach attachment relation
+      tags:
+      - File Manager
+  /api/v1/file-manager/attachments/get-all:
+    get:
+      description: List generic attachment relations by ref_type and ref_id.
+      operationId: FileManagerListAttachmentsByReference
+      parameters:
+      - description: Business reference type, e.g. helicopter
+        in: query
+        name: ref_type
+        required: true
+        type: string
+      - description: Business reference ID
+        in: query
+        name: ref_id
+        required: true
+        type: string
+      - description: Optional attachment category
+        in: query
+        name: category
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: 'Sort values: sort_order,-sort_order,created_at,-created_at,updated_at,-updated_at'
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List attachments by business reference
+      tags:
+      - File Manager
+  /api/v1/file-manager/attachments/get/{uuid}:
+    get:
+      description: Get one generic attachment relation by UUID.
+      operationId: FileManagerGetAttachment
+      parameters:
+      - description: Attachment UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerAttachmentResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get attachment detail
+      tags:
+      - File Manager
+  /api/v1/file-manager/delete:
+    delete:
+      consumes:
+      - application/json
+      description: |-
+        Soft-delete multiple nodes by UUID. UUID can be folder or file.
+        Bulk payload accepts one or many items.
+      operationId: FileManagerDeleteNodesBulk
+      parameters:
+      - description: Bulk delete request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodePurgeBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete nodes (file/folder) in bulk
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/{fileId}/edit-session:
+    get:
+      consumes:
+      - application/json
+      description: |-
+        Returns a Collabora/WOPI write session for an already existing file that belongs to the authenticated user's takeover scope or to the authenticated user as an unattached draft.
+        This endpoint does not create or copy files. It only resolves the file, checks access, and mints a new access token.
+        Use this when reopening an existing file for editing.
+        Path param `fileId` must be a valid UUIDv7.
+      parameters:
+      - description: File UUID (UUIDv7)
+        in: path
+        name: fileId
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Start a WOPI edit session for an existing file
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/cancel-upload:
+    delete:
+      consumes:
+      - application/json
+      description: |-
+        Cancel pending upload intents before file entity creation.
+        This endpoint is intended for pre-create cleanup when FE uploaded to object storage but user cancels flow.
+        Bulk payload accepts one or many items.
+      operationId: FileManagerCancelUploadIntentBulk
+      parameters:
+      - description: Bulk cancel upload intent request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileCancelUploadBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Cancel upload intent (bulk)
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/create:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Final public control-plane step after direct PUT upload to S3 (bulk contract).
+        Verifies uploaded object per item from upload intent, then persists metadata+outbox durably and emits lifecycle status.
+        This endpoint does not upload binary data.
+        Public flow: POST /files/upload (intent+presign) -> PUT to S3 -> POST /files/create.
+        folder_id is optional; null/omitted means create in root folder.
+        Canonical JSON:API data.type is "file_manager_file_create" (legacy "file_manager_file" remains accepted for backward compatibility).
+        Bulk payload accepts one or many items.
+      operationId: FileManagerCreateFileFromUploadedObject
+      parameters:
+      - description: Bulk create payload for user profile image
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create file record from uploaded object
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/create-aircraft-image:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Same as bulk create, but folder is resolved using hierarchy "__system_root_files__" -> "aircraft" -> "<aircraft designation>".
+        aircraft_uuid is required per item to resolve designation.
+      operationId: FileManagerCreateAircraftImageFromUploadedObject
+      parameters:
+      - description: Bulk create payload for aircraft image
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileAircraftBulkCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create aircraft image file record from uploaded object
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/create-base-image:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Same as bulk create, but folder is resolved using hierarchy "__system_root_files__" -> "bases" -> "<base-type>" -> "<base-name>".
+        base_uuid is required per item.
+      operationId: FileManagerCreateBaseImageFromUploadedObject
+      parameters:
+      - description: Bulk create payload for base image
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileBaseBulkCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create base image file record from uploaded object
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/create-dul-image:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Finalize uploaded DUL image file(s) from upload intent.
+        If dul_uuid is provided, file is created under DUL folder hierarchy.
+        If dul_uuid is omitted, file is still created (unassigned), then can be attached during /api/v1/dul/create via file_uuid.
+        Possible status: 201 (all success), 207 (partial success), 400 (invalid json/create failed), 401 (unauthorized), 403 (forbidden), 404 (dul or file resources not found), 409 (upload-intent conflict), 422 (validation), 503 (DUL or file-manager service unavailable).
+        Possible error code: INVALID_REQUEST, USER_UNAUTHORIZED, FORBIDDEN_ACCESS, FILE_MANAGER_VALIDATION_FAILED, FILE_MANAGER_FILE_NOT_FOUND, FILE_MANAGER_UPLOAD_INTENT_NOT_FOUND, FILE_MANAGER_UPLOAD_INTENT_CONFLICT, DUL_NOT_FOUND, FILE_MANAGER_STORAGE_UNAVAILABLE, FILE_MANAGER_QUEUE_UNAVAILABLE, FILE_MANAGER_ATTACHMENT_SERVICE_UNAVAILABLE, FILE_MANAGER_ACTION_FAILED.
+      parameters:
+      - description: Bulk create payload for DUL image
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileDULBulkCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create DUL image file record from uploaded object
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/create-from-template:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Copies a helicopter template file into a new draft file and returns a Collabora/WOPI write session for the newly created file.
+        This endpoint always marks the created file as `is_template=false` because the result is a normal working document, not a reusable template.
+        The source template must be a helicopter file that belongs to the same `helicopter_id` provided in the request.
+        `template_uuid` is the helicopter-file UUID, not the file UUID.
+        Request fields: `template_uuid`, `helicopter_id`, optional `takeover_id`, and `name`.
+        Success response includes the new `file_id`, Collabora editor action URL, an access token, and the token TTL in milliseconds.
+      parameters:
+      - description: Create-from-template payload
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTemplateCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileWOPISessionResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create file from template and start a WOPI edit session
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/create-mission-file:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Materializes uploaded objects into folder "missions/<mission-uuid>", creates attachments (ref_type=mission), and links them to the mission so they appear in GET mission.
+        mission_uuid is required per item.
+        Possible error code: MISSION_FILE_INVALID_JSON, MISSION_FILE_VALIDATION, MISSION_FILE_INVALID_MISSION_UUID, MISSION_FILE_MISSION_NOT_FOUND, MISSION_FILE_SERVICE_UNAVAILABLE, MISSION_FILE_ACTION_FAILED, FILE_MANAGER_UPLOAD_INTENT_NOT_FOUND, FILE_MANAGER_STORAGE_UNAVAILABLE, FILE_MANAGER_ACTION_FAILED.
+      operationId: FileManagerCreateMissionFileFromUploadedObject
+      parameters:
+      - description: Bulk create payload for mission file
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileMissionBulkCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create mission file record from uploaded object
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/create-takeover-file:
+    post:
+      consumes:
+      - application/json
+      description: Finalize uploaded takeover file(s) from upload intent. The takeover
+        relation is attached later from file_id during takeover create/update.
+      parameters:
+      - description: Bulk create payload for takeover file
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileTakeoverBulkCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create takeover file node from uploaded object
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/create-user-image:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Same as bulk create, but folder is resolved using hierarchy "__system_root_files__" -> "user" -> "<username>-<user-uuid>".
+        user_uuid is required per item to resolve target user folder.
+      operationId: FileManagerCreateUserImageFromUploadedObject
+      parameters:
+      - description: Bulk create payload for user profile image
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUserBulkCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create user profile image file record from uploaded object
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/get/{uuid}:
+    get:
+      description: Return file metadata by UUID.
+      operationId: FileManagerGetFile
+      parameters:
+      - description: File UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileDetailResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get file detail
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Update file metadata by UUID (rename and/or move folder).
+      operationId: FileManagerUpdateFileEntity
+      parameters:
+      - description: File UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API file manager file update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update file entity (rename and/or move)
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/upload:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Control-plane endpoint to create upload intents and presigned PUT URLs for direct upload to S3 (bulk contract).
+        Binary does not flow through backend upload endpoint.
+        After successful PUT to S3, call POST /api/v1/file-manager/files/create with upload_intent_uuid.
+        Presigned URL TTL is controlled by backend storage config.
+        Bulk payload accepts one or many items. Response is item-based and supports partial success.
+      operationId: FileManagerRequestUploadIntent
+      parameters:
+      - description: Bulk upload intent request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Request upload intents + presigned PUT URLs
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/upload-aircraft-image:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Same flow as file upload intent, but dedicated for aircraft image drag-drop flow.
+        Use together with /api/v1/file-manager/files/create-aircraft-image to force target folder "aircraft".
+      operationId: FileManagerRequestAircraftImageUploadIntent
+      parameters:
+      - description: Bulk upload intent request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Request upload intents for aircraft drag-drop images
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/upload-base-image:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Same flow as file upload intent, but dedicated for base image flow.
+        Use together with /api/v1/file-manager/files/create-base-image to force target folder under bases hierarchy.
+      operationId: FileManagerRequestBaseImageUploadIntent
+      parameters:
+      - description: Bulk upload intent request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Request upload intents for base images
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/upload-dul-image:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Dedicated upload-intent endpoint for DUL image flow.
+        Possible status: 201 (all success), 207 (partial success), 400 (invalid json), 401 (unauthorized), 403 (forbidden), 422 (validation), 503 (storage/queue/upload-intent service unavailable).
+        Possible error code: INVALID_REQUEST, USER_UNAUTHORIZED, FORBIDDEN_ACCESS, FILE_MANAGER_VALIDATION_FAILED, FILE_MANAGER_STORAGE_UNAVAILABLE, FILE_MANAGER_QUEUE_UNAVAILABLE, FILE_MANAGER_UPLOAD_INTENT_UNAVAILABLE, FILE_MANAGER_ACTION_FAILED.
+      parameters:
+      - description: Bulk upload intent request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "403":
+          description: Forbidden
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Request upload intents for DUL images
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/upload-mission-file:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Dedicated upload-intent endpoint for mission file flow.
+        Use together with /api/v1/file-manager/files/create-mission-file to attach the file to a mission.
+      operationId: FileManagerRequestMissionFileUploadIntent
+      parameters:
+      - description: Bulk upload intent request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Request upload intents for mission files
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/upload-takeover-file:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Dedicated upload-intent endpoint for takeover file flow.
+        Use together with /api/v1/file-manager/files/create-takeover-file to persist the takeover file relation.
+      parameters:
+      - description: Bulk upload intent request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Request upload intents for takeover files
+      tags:
+      - File Manager
+  /api/v1/file-manager/files/upload-user-image:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Same flow as file upload intent, but dedicated for user profile image flow.
+        Use together with /api/v1/file-manager/files/create-user-image to force target folder under user hierarchy.
+      operationId: FileManagerRequestUserImageUploadIntent
+      parameters:
+      - description: Bulk upload intent request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFileUploadIntentBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileUploadIntentBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Request upload intents for user profile images
+      tags:
+      - File Manager
+  /api/v1/file-manager/folders/create:
+    post:
+      consumes:
+      - application/json
+      description: Create one folder metadata node under root or under provided parent_id.
+      operationId: FileManagerCreateFolder
+      parameters:
+      - description: JSON:API file manager folder create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create folder node
+      tags:
+      - File Manager
+  /api/v1/file-manager/folders/get/{uuid}:
+    get:
+      description: Return folder metadata by UUID.
+      operationId: FileManagerGetFolder
+      parameters:
+      - description: Folder UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderDetailResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get folder detail
+      tags:
+      - File Manager
+  /api/v1/file-manager/folders/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Update folder metadata by UUID (rename and/or move parent).
+      operationId: FileManagerUpdateFolder
+      parameters:
+      - description: Folder UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API file manager folder update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerFolderUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFolderResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update folder node
+      tags:
+      - File Manager
+  /api/v1/file-manager/get-all:
+    get:
+      description: |-
+        Return merged direct children (folders + files) for optional parent_uuid (non-recursive).
+        If parent_uuid is omitted, response returns root level nodes.
+        If search is provided, performs a global name search across all folders and files (parent_uuid is ignored).
+      operationId: FileManagerListMergedExplorerNodes
+      parameters:
+      - description: Parent folder UUID
+        in: query
+        name: parent_uuid
+        type: string
+      - description: Search keyword (global name search across all folders and files)
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerNodeListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List merged explorer nodes
+      tags:
+      - File Manager
+  /api/v1/file-manager/move:
+    patch:
+      consumes:
+      - application/json
+      description: |-
+        Unified move endpoint. Each item UUID can be either folder UUID or file UUID.
+        destination_folder_uuid null/empty means move to root.
+        Bulk payload accepts one or many items.
+      operationId: FileManagerMoveNodesBulk
+      parameters:
+      - description: Bulk move request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodeMoveBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Move nodes (file/folder) in bulk
+      tags:
+      - File Manager
+  /api/v1/file-manager/purge-delete:
+    delete:
+      consumes:
+      - application/json
+      description: |-
+        Permanently delete multiple trashed nodes by UUID. UUID can be folder or file.
+        Bulk payload accepts one or many items.
+      operationId: FileManagerPurgeNodesBulkFromTrash
+      parameters:
+      - description: Bulk purge request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodePurgeBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerPurgeNodeBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Purge nodes (file/folder) from trash in bulk
+      tags:
+      - File Manager
+  /api/v1/file-manager/restore:
+    patch:
+      consumes:
+      - application/json
+      description: |-
+        Restore multiple trashed nodes by UUID to original location.
+        Bulk payload accepts one or many items.
+      operationId: FileManagerRestoreNodesBulk
+      parameters:
+      - description: Bulk restore request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FileManagerNodePurgeBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerMoveNodeBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Restore nodes (file/folder) in bulk
+      tags:
+      - File Manager
+  /api/v1/file-manager/trash/get-all:
+    get:
+      description: Return merged trashed nodes (folders + files) for trash explorer.
+      operationId: FileManagerListMergedTrashItems
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: 'Sort values: deleted_at,-deleted_at,name,-name,type,-type,size_bytes,-size_bytes'
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerTrashListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List merged trash items
+      tags:
+      - File Manager
+  /api/v1/fleet-status/create:
+    post:
+      consumes:
+      - application/json
+      description: Create fleet status with maintenance schedules and file attachments.
+      parameters:
+      - description: Fleet status create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FleetStatusCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create fleet status
+      tags:
+      - Fleet Status
+  /api/v1/fleet-status/delete/{id}:
+    delete:
+      description: Soft delete fleet status by ID.
+      parameters:
+      - description: Fleet status ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete fleet status
+      tags:
+      - Fleet Status
+  /api/v1/fleet-status/get-all:
+    get:
+      description: Lists every helicopter from the master, each with its latest fleet
+        status (or empty data when it has none). Paginated by helicopter.
+      parameters:
+      - default: 1
+        description: Page number
+        in: query
+        name: page
+        type: integer
+      - default: 20
+        description: Page size
+        in: query
+        name: page_size
+        type: integer
+      - description: Search helicopters by designation/identifier/type
+        in: query
+        name: filter
+        type: string
+      - description: 'Sort helicopters, example: designation'
+        in: query
+        name: sort
+        type: string
+      - description: 'Filter by operational status; comma-separated for multiple (e.g.
+          available,booked). Values: available, booked, aog, mcf'
+        in: query
+        name: status
+        type: string
+      - description: Filter by helicopter ID (UUIDv7); combined with status uses AND
+          logic
+        in: query
+        name: helicopter_id
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List fleet status
+      tags:
+      - Fleet Status
+  /api/v1/fleet-status/get-all/dt:
+    get:
+      description: Lists every helicopter from the master, each with its latest fleet
+        status (or empty data when it has none). Paginated by helicopter.
+      parameters:
+      - default: 1
+        description: Datatable draw counter
+        in: query
+        name: draw
+        type: integer
+      - default: 0
+        description: Datatable start offset
+        in: query
+        name: start
+        type: integer
+      - default: 10
+        description: Datatable page length
+        in: query
+        name: length
+        type: integer
+      - description: Search helicopters by designation/identifier/type
+        in: query
+        name: search
+        type: string
+      - description: 'Sort helicopters, example: designation'
+        in: query
+        name: sort
+        type: string
+      - description: 'Filter by operational status; comma-separated for multiple (e.g.
+          available,booked). Values: available, booked, aog, mcf'
+        in: query
+        name: status
+        type: string
+      - description: Filter by helicopter ID (UUIDv7); combined with status uses AND
+          logic
+        in: query
+        name: helicopter_id
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusDataTableResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List fleet status (datatable)
+      tags:
+      - Fleet Status
+  /api/v1/fleet-status/get-by-helicopter/{helicopter_id}:
+    get:
+      parameters:
+      - description: Helicopter ID (UUIDv7)
+        in: path
+        name: helicopter_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get latest fleet status by helicopter ID
+      tags:
+      - Fleet Status
+  /api/v1/fleet-status/get/{id}:
+    get:
+      parameters:
+      - description: Fleet status ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get fleet status by ID
+      tags:
+      - Fleet Status
+  /api/v1/fleet-status/history/{helicopter_id}:
+    get:
+      description: 'Unified timeline: maintenance servicing events merged with complaint/MEL/NSR/action/MCF/EASA/AOG
+        action events, newest first.'
+      parameters:
+      - description: Helicopter ID (UUIDv7)
+        in: path
+        name: helicopter_id
+        required: true
+        type: string
+      - default: 1
+        description: Page number
+        in: query
+        name: page
+        type: integer
+      - default: 20
+        description: Page size
+        in: query
+        name: page_size
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetHistoryListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List fleet history (timeline) by helicopter
+      tags:
+      - Fleet Status
+  /api/v1/fleet-status/mark-serviced/{id}:
+    post:
+      description: Move current maintenance schedules into service logs, then clear
+        active schedules.
+      parameters:
+      - description: Fleet status ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusMarkServicedResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Mark fleet status serviced
+      tags:
+      - Fleet Status
+  /api/v1/fleet-status/update/{id}:
+    patch:
+      consumes:
+      - application/json
+      description: Update fleet status by ID with full replacement for schedules and
+        files.
+      parameters:
+      - description: Fleet status ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Fleet status update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FleetStatusUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FleetStatusResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update fleet status
+      tags:
+      - Fleet Status
+  /api/v1/flight-data/create:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Create a flight data row.
+        Required field: `mission_id`. `co_pilot_id` is optional.
+        Swagger request example shows the complete common payload for an `SPO` mission. `SPO` is the default example shape, and for other mission types (`CAT` and `NCO`) you do not need to send the `hec`, `heslo`, or `logging` blocks. `rotor_brake_cycle` is optional for `SPO`, `CAT`, and `NCO`.
+        SPO facility references must point to facilities with categories: `heslo_rope_label_id -> heslo-rope-label`, `heslo.slings -> heslo-rope-length`, `logging.slings -> heslo-hook`, `hec.flights -> hec-rope-label`, and `hec.slings -> hec-rope-length`.
+        SPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.
+        Example request: {"data":{"type":"flight_data_create","attributes":{"mission_id":"019d6774-98e8-7fba-9ef4-3795c0da8a13"}}}
+      parameters:
+      - description: JSON:API flight data create request. Example is for SPO; CAT/NCO
+          can omit SPO-only blocks and other optional fields.
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create flight data
+      tags:
+      - Mission - Flight Data
+  /api/v1/flight-data/delete/{id}:
+    delete:
+      description: Soft delete flight data by UUID.
+      parameters:
+      - description: Flight Data UUID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete flight data by ID
+      tags:
+      - Mission - Flight Data
+  /api/v1/flight-data/get-all:
+    get:
+      description: |-
+        List flight data rows. Supports `date` for exact flight take-off date filtering (`YYYY-MM-DD`), plus `mission_id` and `flight_data_id` filters.
+        SPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.
+      parameters:
+      - description: Filter by flight take-off date (YYYY-MM-DD)
+        in: query
+        name: date
+        type: string
+      - description: Filter by mission UUID
+        in: query
+        name: mission_id
+        type: string
+      - description: Filter by flight-data UUID
+        in: query
+        name: flight_data_id
+        type: string
+      - description: Page number
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size
+        in: query
+        name: page[size]
+        type: integer
+      - description: Page number (fallback)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (fallback)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override
+        in: query
+        name: limit
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List flight data
+      tags:
+      - Mission - Flight Data
+  /api/v1/flight-data/get-all/dt:
+    get:
+      description: |-
+        Datatable-friendly list of flight data rows. Supports `date` for exact flight take-off date filtering (`YYYY-MM-DD`), plus `mission_id` and `flight_data_id` filters.
+        Same payload shape as `get-all`, but with DataTables paging params (`start`, `length`, `draw`).
+        SPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.
+      parameters:
+      - description: DataTables draw counter
+        in: query
+        name: draw
+        type: integer
+      - description: Paging start offset
+        in: query
+        name: start
+        type: integer
+      - description: Paging length
+        in: query
+        name: length
+        type: integer
+      - description: Page number
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size
+        in: query
+        name: page[size]
+        type: integer
+      - description: Page number (fallback)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (fallback)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override
+        in: query
+        name: limit
+        type: integer
+      - description: Filter by flight take-off date (YYYY-MM-DD)
+        in: query
+        name: date
+        type: string
+      - description: Filter by mission UUID
+        in: query
+        name: mission_id
+        type: string
+      - description: Filter by flight-data UUID
+        in: query
+        name: flight_data_id
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List flight data (datatable)
+      tags:
+      - Mission - Flight Data
+  /api/v1/flight-data/get/{id}:
+    get:
+      description: |-
+        Get flight data detail by ID. Path `id` can be mission UUID, flight-data UUID, or flight UUID.
+        SPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.
+      parameters:
+      - description: Mission UUID / Flight Data UUID / Flight UUID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get flight data by ID
+      tags:
+      - Mission - Flight Data
+  /api/v1/flight-data/update/{id}:
+    patch:
+      consumes:
+      - application/json
+      description: |-
+        Update a flight data row by UUID.
+        Required field: `mission_id`. `co_pilot_id` is optional.
+        Swagger request example uses the same SPO-shaped payload as create, but this endpoint updates an existing flight-data row.
+        SPO facility references must point to facilities with categories: `heslo_rope_label_id -> heslo-rope-label`, `heslo.slings -> heslo-rope-length`, `logging.slings -> heslo-hook`, `hec.flights -> hec-rope-label`, and `hec.slings -> hec-rope-length`.
+        For frontend usage, send only the fields that need to change; omitted fields stay unchanged. `SPO` is the default example shape, and for `CAT`/`NCO` you do not need to send the `hec`, `heslo`, or `logging` blocks. `rotor_brake_cycle` is optional for `SPO`, `CAT`, and `NCO`.
+        SPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.
+        Example request: {"data":{"type":"flight_data_create","attributes":{"mission_id":"019d6774-98e8-7fba-9ef4-3795c0da8a13"}}}
+      parameters:
+      - description: Flight Data UUID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: JSON:API flight data update request. Send only fields you want
+          to change; omit the rest.
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FlightDataUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightDataResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update flight data by ID
+      tags:
+      - Mission - Flight Data
+  /api/v1/flights/get:
+    get:
+      description: |-
+        Returns flights assigned to current auth user, including workflow steps (`duty_roster`, `reserve_ac`, `mission`, `after_flight_inspection`, `fm_report`).
+        Each step includes `status`, `completed_at`, and `completed_by` for consistent FE rendering.
+      parameters:
+      - description: Page number
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size
+        in: query
+        name: page[size]
+        type: integer
+      - description: Page number (fallback)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (fallback)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override
+        in: query
+        name: limit
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightListResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get flights for current auth user (from duty roster assignment)
+      tags:
+      - Flight
+  /api/v1/flights/get-all:
+    get:
+      description: |-
+        Supports `search`, `filter[search]`, `sort`, `page[number]`, `page[size]`, `page`, `size`, and `limit`.
+        Supports `date` and `filter[date]` for exact flight date filtering (`YYYY-MM-DD`).
+        Returns paginated flights with workflow steps (`takeover`, `mission`, `after_flight_inspection`, `fm_report`).
+        Each step includes `status`, `completed_at`, and `completed_by` for consistent FE rendering.
+      parameters:
+      - description: Search text
+        in: query
+        name: search
+        type: string
+      - description: Search text (JSON:API style)
+        in: query
+        name: filter[search]
+        type: string
+      - description: Filter by flight date (YYYY-MM-DD)
+        in: query
+        name: date
+        type: string
+      - description: Filter by flight date (YYYY-MM-DD) (JSON:API style)
+        in: query
+        name: filter[date]
+        type: string
+      - description: Sort field
+        in: query
+        name: sort
+        type: string
+      - description: Page number
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size
+        in: query
+        name: page[size]
+        type: integer
+      - description: Page number (fallback)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (fallback)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override
+        in: query
+        name: limit
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FlightListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List flights
+      tags:
+      - Flight
+  /api/v1/fm-reports/{id}:
+    delete:
+      description: Soft-delete an FM report by ID. Requires a verified security PIN.
+      parameters:
+      - description: FM Report ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: One-time security-PIN action token
+        in: header
+        name: X-PIN-Verification-Token
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "204":
+          description: No Content
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete FM report
+      tags:
+      - Flight Report
+  /api/v1/fm-reports/{id}/attachments:
+    post:
+      consumes:
+      - application/json
+      description: 'After uploading the file to the presigned URL (from /attachments/upload-intent),
+        call this endpoint with the upload_intent_uuid, name, and category to create
+        the file node and attach it to the FM report. Valid categories: additional_fm_report,
+        briefing, weight_balance, ofp.'
+      parameters:
+      - description: FM Report ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: body with upload_intent_uuid, name, and category
+        in: body
+        name: request
+        required: true
+        schema:
+          type: object
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            type: object
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create FM report attachment from upload intent
+      tags:
+      - Flight Report
+  /api/v1/fm-reports/{id}/attachments/{att_id}:
+    delete:
+      description: Remove a specific attachment from an FM report. Verifies ownership
+        before deletion.
+      parameters:
+      - description: FM Report ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Attachment ID (UUIDv7)
+        in: path
+        name: att_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "204":
+          description: No Content
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete attachment from FM report
+      tags:
+      - Flight Report
+  /api/v1/fm-reports/{id}/attachments/upload-intent:
+    post:
+      consumes:
+      - application/json
+      description: Returns a presigned PUT URL and upload_intent_uuid. After uploading
+        the file to the presigned URL, call POST /fm-reports/{id}/attachments with
+        the upload_intent_uuid to create the file node and attach it to the report.
+      parameters:
+      - description: FM Report ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: body with name, content_type, size_bytes
+        in: body
+        name: request
+        required: true
+        schema:
+          type: object
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            type: object
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Request upload intent for FM report attachment
+      tags:
+      - Flight Report
+  /api/v1/fm-reports/complete/{flight_id}:
+    post:
+      description: 'Mark an FM report as completed for a flight. Once completed, the
+        report becomes read-only and flight data edits are locked. Requires a verified
+        security PIN: send the one-time token from POST /auth/pin/verify (action 1a75135b-430a-4592-83e1-6d27814185af)
+        in the X-PIN-Verification-Token header.'
+      parameters:
+      - description: Flight ID (UUIDv7)
+        in: path
+        name: flight_id
+        required: true
+        type: string
+      - description: One-time security-PIN action token
+        in: header
+        name: X-PIN-Verification-Token
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportResponse'
+        "202":
+          description: PIN verification required
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Complete FM report
+      tags:
+      - Flight Report
+  /api/v1/fm-reports/get-all:
+    get:
+      description: Returns a paginated list of FM reports. Supports `search`, `filter[search]`,
+        `filter[flight_id]`, `filter[takeover_id]`, `filter[flight_inspection_id]`,
+        `filter[flight_date]`, `filter[has_engine1_gpc_n1]`, `filter[has_engine1_ptc_n2]`,
+        `filter[has_engine2_gpc_n1]`, `filter[has_engine2_ptc_n2]`, `sort`, `page[number]`,
+        `page[size]`, `page`, `size`, and `limit`.
+      parameters:
+      - description: Search text
+        in: query
+        name: search
+        type: string
+      - description: Search text (JSON:API style)
+        in: query
+        name: filter[search]
+        type: string
+      - description: Filter by flight ID
+        in: query
+        name: filter[flight_id]
+        type: string
+      - description: Filter by takeover ID
+        in: query
+        name: filter[takeover_id]
+        type: string
+      - description: Filter by flight inspection ID
+        in: query
+        name: filter[flight_inspection_id]
+        type: string
+      - description: Filter by flight date (YYYY-MM-DD)
+        in: query
+        name: filter[flight_date]
+        type: string
+      - description: Filter reports with or without engine1_gpc_n1
+        in: query
+        name: filter[has_engine1_gpc_n1]
+        type: boolean
+      - description: Filter reports with or without engine1_ptc_n2
+        in: query
+        name: filter[has_engine1_ptc_n2]
+        type: boolean
+      - description: Filter reports with or without engine2_gpc_n1
+        in: query
+        name: filter[has_engine2_gpc_n1]
+        type: boolean
+      - description: Filter reports with or without engine2_ptc_n2
+        in: query
+        name: filter[has_engine2_ptc_n2]
+        type: boolean
+      - description: 'Sort order: flight_date, -flight_date, created_at, -created_at,
+          updated_at, -updated_at, engine1_gpc_n1, -engine1_gpc_n1, engine1_ptc_n2,
+          -engine1_ptc_n2, engine2_gpc_n1, -engine2_gpc_n1, engine2_ptc_n2, -engine2_ptc_n2'
+        in: query
+        name: sort
+        type: string
+      - description: Page number
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size
+        in: query
+        name: page[size]
+        type: integer
+      - description: Page number (fallback)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (fallback)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override
+        in: query
+        name: limit
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List FM reports
+      tags:
+      - Flight Report
+  /api/v1/fm-reports/get/{flight_id}:
+    get:
+      description: Returns a complete FM report for a flight. The persisted table
+        keeps only the report keys; the response preloads flight, missions, flight
+        inspection, and after-flight inspection details. It also embeds `fleet_status`
+        (next inspection / maintenance schedules + base hours, component summary,
+        EASA maintenance release) — a snapshot frozen when the report was created
+        at after-flight inspection, so later complaints / maintenance changes do not
+        alter a historical report. `fleet_status` is omitted when the helicopter has
+        no fleet status.
+      parameters:
+      - description: Flight ID (UUIDv7)
+        in: path
+        name: flight_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get FM report by flight ID
+      tags:
+      - Flight Report
+  /api/v1/fm-reports/update/{flight_id}:
+    patch:
+      consumes:
+      - application/json
+      description: Update only the engine metric fields for an existing FM report.
+        All other FM report fields stay read-only on this endpoint. The response mirrors
+        the GET FM report and embeds the frozen `fleet_status` snapshot (next inspection
+        / maintenance schedules + base hours, component summary, EASA maintenance
+        release).
+      parameters:
+      - description: Flight ID (UUIDv7)
+        in: path
+        name: flight_id
+        required: true
+        type: string
+      - description: JSON:API FM report update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.FMReportUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.FMReportResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update FM report metrics
+      tags:
+      - Flight Report
+  /api/v1/forces-present/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a forces present row.
+      parameters:
+      - description: JSON:API forces present create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create forces present
+      tags:
+      - OPC - Forces Present
+  /api/v1/forces-present/delete/{uuid}:
+    delete:
+      parameters:
+      - description: Forces Present UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete forces present
+      tags:
+      - OPC - Forces Present
+  /api/v1/forces-present/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        name, -name, sortkey, -sortkey, note, -note, is_active, -is_active, created_at,
+        -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Search by name/note
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentListResponse'
+      summary: List forces present
+      tags:
+      - OPC - Forces Present
+  /api/v1/forces-present/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentDataTableResponse'
+      summary: List forces present (datatable)
+      tags:
+      - OPC - Forces Present
+  /api/v1/forces-present/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch forces present by ID.
+      parameters:
+      - description: Forces Present UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API forces present update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ForcesPresentResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update forces present (partial)
+      tags:
+      - OPC - Forces Present
+  /api/v1/health-insurance-companies/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a health insurance company row.
+      parameters:
+      - description: JSON:API health insurance company create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create health insurance company
+      tags:
+      - Hospital - Health Insurance Companies
+  /api/v1/health-insurance-companies/delete/{uuid}:
+    delete:
+      parameters:
+      - description: Health Insurance Company UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete health insurance company
+      tags:
+      - Hospital - Health Insurance Companies
+  /api/v1/health-insurance-companies/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        name, -name, sortkey, -sortkey, state, -state, address, -address, mobile_number,
+        -mobile_number, email, -email, note, -note, is_active, -is_active, created_at,
+        -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Search by name/state/address/mobile/email
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyListResponse'
+      summary: List health insurance companies
+      tags:
+      - Hospital - Health Insurance Companies
+  /api/v1/health-insurance-companies/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyDataTableResponse'
+      summary: List health insurance companies (datatable)
+      tags:
+      - Hospital - Health Insurance Companies
+  /api/v1/health-insurance-companies/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch health insurance company by ID.
+      parameters:
+      - description: Health Insurance Company UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API health insurance company update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HealthInsuranceCompanyResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update health insurance company (partial)
+      tags:
+      - Hospital - Health Insurance Companies
+  /api/v1/helicopter-files/cancel-upload:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Cancel pending upload intents from helicopter file upload flow.
+        Bulk payload accepts one or many items.
+      parameters:
+      - description: Bulk helicopter file cancel upload intent request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCancelUploadBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.FileManagerFileCancelUploadBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Cancel helicopter file upload intent (bulk)
+      tags:
+      - Helicopter - Master File
+  /api/v1/helicopter-files/create:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Create helicopter file template record from upload intent.
+        Section allowed values: `bfi` (Before First Flight Inspection), `fpwb` (Flight Preparation and WB), `afi` (After Last Flight Inspection).
+        Required attributes: `section`, `helicopter_id`, `upload_intent_uuid`, `file_name`.
+        Optional attributes: `position`, `is_required`, `folder_uuid` (if omitted, file is created in root folder).
+        When `position` is omitted (or <= 0), backend auto-assigns next position per `helicopter_id + section`.
+        If file name already exists in target folder, existing file is reused and attached.
+        Supports single and bulk payload.
+        Single payload example: `{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","position":1,"is_required":true,"helicopter_id":"019d6771-5fb5-7337-837f-bc5ed85181a1","upload_intent_uuid":"019d6d0d-2de2-7db1-80a2-2862d43af620","file_name":"A.pdf"}}}`
+        Bulk payload example: `{"data":[{"type":"helicopter_file_create","attributes":{"section":"bfi","position":1,"is_required":true,"helicopter_id":"019d6771-5fb5-7337-837f-bc5ed85181a1","upload_intent_uuid":"019d6d0d-2de2-7db1-80a2-2862d43af620","file_name":"A.pdf"}}]}`
+        Note: OpenAPI 2.0 cannot express object-or-array union in one schema; request schema below represents bulk envelope.
+      parameters:
+      - description: JSON:API helicopter file create request (single object or bulk
+          array)
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileCreateBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCreateBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create helicopter file
+      tags:
+      - Helicopter - Master File
+  /api/v1/helicopter-files/delete:
+    delete:
+      consumes:
+      - application/json
+      description: Delete helicopter file template record
+      parameters:
+      - description: JSON:API helicopter file delete request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileDeleteRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete helicopter file
+      tags:
+      - Helicopter - Master File
+  /api/v1/helicopter-files/get-all:
+    get:
+      description: |-
+        List helicopter file template records grouped by helicopter.
+        Pagination is applied per helicopter group (not per file row), so one helicopter's files stay in the same page.
+      parameters:
+      - description: Search text
+        in: query
+        name: filter[search]
+        type: string
+      - description: Search text (fallback)
+        in: query
+        name: search
+        type: string
+      - description: Sort field
+        in: query
+        name: sort
+        type: string
+      - description: Page number
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size
+        in: query
+        name: page[size]
+        type: integer
+      - description: Page number (fallback)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (fallback)
+        in: query
+        name: size
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List helicopter files
+      tags:
+      - Helicopter - Master File
+  /api/v1/helicopter-files/get/{helicopter_id}:
+    get:
+      description: Return helicopter file template collection for selected helicopter
+      parameters:
+      - description: Helicopter ID
+        in: path
+        name: helicopter_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileCollectionResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get helicopter files by helicopter ID
+      tags:
+      - Helicopter - Master File
+  /api/v1/helicopter-files/update:
+    patch:
+      consumes:
+      - application/json
+      description: |-
+        Update a helicopter file template record.
+        Section allowed values: `bfi` (Before First Flight Inspection), `fpwb` (Flight Preparation and WB), `afi` (After Last Flight Inspection).
+        Optional attributes: `section`, `position`, `is_required`, `helicopter_id`, `file_name`.
+      parameters:
+      - description: JSON:API helicopter file update request (single object or bulk
+          array)
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUpdateBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUpdateBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update helicopter file
+      tags:
+      - Helicopter - Master File
+  /api/v1/helicopter-files/upload:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Control-plane endpoint for helicopter file upload intent + presigned URL flow.
+        Public flow: POST /api/v1/helicopter-files/upload -> PUT to presigned URL -> POST /api/v1/helicopter-files/create.
+        Canonical type is `helicopter_file_upload`.
+        `required_headers` must be sent exactly as returned when doing PUT to `upload_url`.
+        Example `required_headers`: `{"content-type":"application/pdf","x-amz-acl":"private"}`
+        Supports single and bulk payload.
+        Single payload example: `{"data":{"type":"helicopter_file_upload","attributes":{"name":"A.pdf","content_type":"application/pdf","size_bytes":12345}}}`
+        Bulk payload example: `{"data":[{"type":"helicopter_file_upload","attributes":{"name":"A.pdf","content_type":"application/pdf","size_bytes":12345}}]}`
+        Note: OpenAPI 2.0 cannot express object-or-array union in one schema; request schema below represents bulk envelope.
+      parameters:
+      - description: Helicopter file upload intent request (single object or bulk
+          array)
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterFileUploadBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentResponse'
+        "207":
+          description: Multi-Status
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterFileUploadIntentBulkResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Request upload intents + presigned PUT URLs (helicopter file)
+      tags:
+      - Helicopter - Master File
+  /api/v1/helicopter-usage/create:
+    post:
+      consumes:
+      - application/json
+      description: Create helicopter usage counters for a helicopter.
+      parameters:
+      - description: JSON:API helicopter usage create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create helicopter usage
+      tags:
+      - Helicopter - Helicopter Usage
+  /api/v1/helicopter-usage/delete/{uuid}:
+    delete:
+      parameters:
+      - description: Helicopter Usage UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete helicopter usage
+      tags:
+      - Helicopter - Helicopter Usage
+  /api/v1/helicopter-usage/get-all:
+    get:
+      description: 'JSON:API list without pagination. Sort values: helicopter_id,
+        -helicopter_id, total_landing, -total_landing, total_airframe_hours, -total_airframe_hours,
+        total_airframe_cycles, -total_airframe_cycles, total_engine_1_hours, -total_engine_1_hours,
+        total_engine_1_gpc_ng_n1, -total_engine_1_gpc_ng_n1, total_engine_1_ptc_nf_n2,
+        -total_engine_1_ptc_nf_n2, total_engine_1_ccc, -total_engine_1_ccc, total_engine_2_hours,
+        -total_engine_2_hours, total_engine_2_gpc_ng_n1, -total_engine_2_gpc_ng_n1,
+        total_engine_2_ptc_nf_n2, -total_engine_2_ptc_nf_n2, total_engine_2_ccc, -total_engine_2_ccc,
+        total_flight_report, -total_flight_report, total_hook_release, -total_hook_release,
+        total_rotor_brake_cycle, -total_rotor_brake_cycle, created_at, -created_at,
+        updated_at, -updated_at.'
+      parameters:
+      - description: Search by helicopter or usage ID
+        in: query
+        name: search
+        type: string
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageListResponse'
+      summary: List helicopter usage
+      tags:
+      - Helicopter - Helicopter Usage
+  /api/v1/helicopter-usage/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageListResponse'
+      summary: List helicopter usage (datatable)
+      tags:
+      - Helicopter - Helicopter Usage
+  /api/v1/helicopter-usage/get/{uuid}:
+    get:
+      parameters:
+      - description: Helicopter Usage UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get helicopter usage
+      tags:
+      - Helicopter - Helicopter Usage
+  /api/v1/helicopter-usage/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: Helicopter Usage UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API helicopter usage update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HelicopterUsageResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update helicopter usage (partial)
+      tags:
+      - Helicopter - Helicopter Usage
+  /api/v1/helicopters/{id}/reports/next-number:
+    post:
+      description: 'Returns report number format <identifier>-NNNN (example: SN0901-0001).
+        The identifier is used as the report-code prefix and the numeric suffix is
+        auto-incremented by backend per helicopter.'
+      parameters:
+      - description: Helicopter ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterNextReportNumberResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Generate next helicopter report number
+      tags:
+      - Facility - Helicopters
+  /api/v1/helicopters/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a helicopter configuration row.
+      parameters:
+      - description: JSON:API Helicopter create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create helicopter
+      tags:
+      - Facility - Helicopters
+  /api/v1/helicopters/delete/{id}:
+    delete:
+      parameters:
+      - description: Helicopter ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.Document'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete helicopter
+      tags:
+      - Facility - Helicopters
+  /api/v1/helicopters/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        designation, -designation, sortkey, -sortkey.'
+      parameters:
+      - description: Search by designation/identifier/type
+        in: query
+        name: filter[search]
+        type: string
+      - description: 'Filter by operational status; comma-separated for multiple (e.g.
+          available,booked). Values: available, booked, aog, mcf'
+        in: query
+        name: filter[status]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterListResponse'
+      summary: List helicopters
+      tags:
+      - Facility - Helicopters
+  /api/v1/helicopters/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      - description: 'Filter by operational status; comma-separated for multiple (e.g.
+          available,booked). Values: available, booked, aog, mcf'
+        in: query
+        name: status
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterDataTableResponse'
+      summary: List helicopters (datatable)
+      tags:
+      - Facility - Helicopters
+  /api/v1/helicopters/get/{id}:
+    get:
+      parameters:
+      - description: Helicopter ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get helicopter by ID
+      tags:
+      - Facility - Helicopters
+  /api/v1/helicopters/update/{id}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch helicopter by ID.
+      parameters:
+      - description: Helicopter ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: JSON:API Helicopter update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.HelicopterUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.HelicopterResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update helicopter (partial)
+      tags:
+      - Facility - Helicopters
+  /api/v1/hems-operation-category/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a HEMS operation category.
+      parameters:
+      - description: JSON:API HEMS operation category create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create HEMS operation category
+      tags:
+      - Operation - Category
+  /api/v1/hems-operation-category/delete/{uuid}:
+    delete:
+      parameters:
+      - description: HEMS operation category UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete HEMS operation category
+      tags:
+      - Operation - Category
+  /api/v1/hems-operation-category/get-all:
+    get:
+      parameters:
+      - description: Search by name/type
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryListResponse'
+      summary: List HEMS operation categories
+      tags:
+      - Operation - Category
+  /api/v1/hems-operation-category/get-all/dt:
+    get:
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryDataTableResponse'
+      summary: List HEMS operation categories (datatable)
+      tags:
+      - Operation - Category
+  /api/v1/hems-operation-category/get/{uuid}:
+    get:
+      parameters:
+      - description: HEMS operation category UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get HEMS operation category by ID
+      tags:
+      - Operation - Category
+  /api/v1/hems-operation-category/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: HEMS operation category UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API HEMS operation category update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCategoryResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update HEMS operation category (partial)
+      tags:
+      - Operation - Category
+  /api/v1/hems-operation/create:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - description: JSON:API HEMS operation create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create HEMS operation
+      tags:
+      - Operation - HEMS Operation
+  /api/v1/hems-operation/delete/{uuid}:
+    delete:
+      parameters:
+      - description: HEMS operation UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete HEMS operation
+      tags:
+      - Operation - HEMS Operation
+  /api/v1/hems-operation/get-all:
+    get:
+      parameters:
+      - description: Search by date
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationListResponse'
+      summary: List HEMS operations
+      tags:
+      - Operation - HEMS Operation
+  /api/v1/hems-operation/get-all/dt:
+    get:
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationDataTableResponse'
+      summary: List HEMS operations (datatable)
+      tags:
+      - Operation - HEMS Operation
+  /api/v1/hems-operation/get/{uuid}:
+    get:
+      parameters:
+      - description: HEMS operation UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get HEMS operation by ID
+      tags:
+      - Operation - HEMS Operation
+  /api/v1/hems-operation/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: HEMS operation UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API HEMS operation update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update HEMS operation (partial)
+      tags:
+      - Operation - HEMS Operation
+  /api/v1/hems-operational-data/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a HEMS operational data record.
+      parameters:
+      - description: JSON:API HEMS operational data create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create HEMS operational data
+      tags:
+      - Operation - HEMS Operational Data
+  /api/v1/hems-operational-data/delete/{uuid}:
+    delete:
+      parameters:
+      - description: HEMS operational data UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete HEMS operational data
+      tags:
+      - Operation - HEMS Operational Data
+  /api/v1/hems-operational-data/get-all:
+    get:
+      parameters:
+      - description: Search by location/notes/additional_info/terrain_index
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataListResponse'
+      summary: List HEMS operational data
+      tags:
+      - Operation - HEMS Operational Data
+  /api/v1/hems-operational-data/get-all/dt:
+    get:
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataDataTableResponse'
+      summary: List HEMS operational data (datatable)
+      tags:
+      - Operation - HEMS Operational Data
+  /api/v1/hems-operational-data/get/{uuid}:
+    get:
+      parameters:
+      - description: HEMS operational data UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get HEMS operational data by ID
+      tags:
+      - Operation - HEMS Operational Data
+  /api/v1/hems-operational-data/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: HEMS operational data UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API HEMS operational data update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HEMSOperationalDataResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update HEMS operational data (partial)
+      tags:
+      - Operation - HEMS Operational Data
+  /api/v1/hospital/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a hospital row.
+      parameters:
+      - description: JSON:API hospital create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create hospital
+      tags:
+      - Hospital - Hospital
+  /api/v1/hospital/delete/{uuid}:
+    delete:
+      parameters:
+      - description: Hospital UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete hospital
+      tags:
+      - Hospital - Hospital
+  /api/v1/hospital/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        name, -name, hospital_name, -hospital_name, sortkey, -sortkey, address, -address,
+        landline_number, -landline_number, mobile_number, -mobile_number, email, -email,
+        note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Search by hospital name/address/contact
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalListResponse'
+      summary: List hospital
+      tags:
+      - Hospital - Hospital
+  /api/v1/hospital/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalDataTableResponse'
+      summary: List hospital (datatable)
+      tags:
+      - Hospital - Hospital
+  /api/v1/hospital/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch hospital by ID.
+      parameters:
+      - description: Hospital UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API hospital update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.HospitalResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update hospital (partial)
+      tags:
+      - Hospital - Hospital
+  /api/v1/icao/create:
+    post:
+      consumes:
+      - application/json
+      description: Create an ICAO row.
+      parameters:
+      - description: JSON:API ICAO create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create ICAO
+      tags:
+      - Hospital - ICAO
+  /api/v1/icao/delete/{uuid}:
+    delete:
+      parameters:
+      - description: ICAO UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete ICAO
+      tags:
+      - Hospital - ICAO
+  /api/v1/icao/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        icao_code, -icao_code, sortkey, -sortkey, address, -address, landline_number,
+        -landline_number, mobile_number, -mobile_number, email, -email, note, -note,
+        is_active, -is_active, created_at, -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Search by icao_code/address/contact
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOListResponse'
+      summary: List ICAO
+      tags:
+      - Hospital - ICAO
+  /api/v1/icao/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ICAODataTableResponse'
+      summary: List ICAO (datatable)
+      tags:
+      - Hospital - ICAO
+  /api/v1/icao/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch ICAO by ID.
+      parameters:
+      - description: ICAO UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API ICAO update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ICAOResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update ICAO (partial)
+      tags:
+      - Hospital - ICAO
+  /api/v1/insurance-patient-data/create:
+    post:
+      consumes:
+      - application/json
+      description: Create an InsurancePatientData record.
+      parameters:
+      - description: JSON:API InsurancePatientData create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create insurance patient data
+      tags:
+      - PatientData - InsurancePatientData
+  /api/v1/insurance-patient-data/delete/{uuid}:
+    delete:
+      description: Soft delete InsurancePatientData by ID.
+      parameters:
+      - description: InsurancePatientData UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete insurance patient data
+      tags:
+      - PatientData - InsurancePatientData
+  /api/v1/insurance-patient-data/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        created_at, -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Search
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataListResponse'
+      summary: List insurance patient data
+      tags:
+      - PatientData - InsurancePatientData
+  /api/v1/insurance-patient-data/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataDataTableResponse'
+      summary: List insurance patient data (datatable)
+      tags:
+      - PatientData - InsurancePatientData
+  /api/v1/insurance-patient-data/get/{uuid}:
+    get:
+      description: Get a single InsurancePatientData record by UUID.
+      parameters:
+      - description: InsurancePatientData UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get insurance patient data by ID
+      tags:
+      - PatientData - InsurancePatientData
+  /api/v1/insurance-patient-data/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch InsurancePatientData by ID.
+      parameters:
+      - description: InsurancePatientData UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API InsurancePatientData update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.InsurancePatientDataResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update insurance patient data (partial)
+      tags:
+      - PatientData - InsurancePatientData
+  /api/v1/land/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a land row.
+      parameters:
+      - description: JSON:API land create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.LandCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.LandResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create land
+      tags:
+      - Hospital - Land
+  /api/v1/land/delete/{id}:
+    delete:
+      parameters:
+      - description: Land ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete land
+      tags:
+      - Hospital - Land
+  /api/v1/land/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        name, -name, sortkey, -sortkey, is_active, -is_active, created_at, -created_at,
+        updated_at, -updated_at.'
+      parameters:
+      - description: Search by name
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.LandListResponse'
+      summary: List land
+      tags:
+      - Hospital - Land
+  /api/v1/land/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 1000)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.LandDataTableResponse'
+      summary: List land (datatable)
+      tags:
+      - Hospital - Land
+  /api/v1/land/update/{id}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch land by ID.
+      parameters:
+      - description: Land ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: JSON:API land update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.LandUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.LandResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update land (partial)
+      tags:
+      - Hospital - Land
+  /api/v1/master-settings/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a master settings row.
+      parameters:
+      - description: JSON:API master settings create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create master settings
+      tags:
+      - Master Settings
+  /api/v1/master-settings/delete/{uuid}:
+    delete:
+      parameters:
+      - description: Master Settings UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.Resource'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete master settings
+      tags:
+      - Master Settings
+  /api/v1/master-settings/get:
+    get:
+      description: Return singleton master settings object (latest active row).
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get current master settings
+      tags:
+      - Master Settings
+  /api/v1/master-settings/sso/microsoft:
+    get:
+      description: Get Microsoft Entra SSO settings from master settings.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get Microsoft Entra SSO settings
+      tags:
+      - Master Settings
+    put:
+      consumes:
+      - application/json
+      description: Create or update Microsoft Entra SSO settings as master settings.
+      parameters:
+      - description: JSON:API Microsoft Entra SSO upsert request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsMicrosoftEntraUpsertRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsMicrosoftEntraResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Upsert Microsoft Entra SSO settings
+      tags:
+      - Master Settings
+  /api/v1/master-settings/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch master settings by ID.
+      parameters:
+      - description: Master Settings UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API master settings update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.MasterSettingsUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MasterSettingsResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update master settings (partial)
+      tags:
+      - Master Settings
+  /api/v1/mcf/get-by-helicopter/{helicopter_id}:
+    get:
+      parameters:
+      - description: Helicopter ID (UUIDv7)
+        in: path
+        name: helicopter_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MCFListResponse'
+      summary: List MCFs for a helicopter
+      tags:
+      - MCF
+  /api/v1/mcf/get/{id}:
+    get:
+      parameters:
+      - description: MCF ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MCFResponse'
+      summary: Get MCF by ID
+      tags:
+      - MCF
+  /api/v1/mcf/set/{helicopter_id}:
+    post:
+      consumes:
+      - application/json
+      description: Toggles and edits a helicopter's MCF. `active:true` (or omitted)
+        ACTIVATES/EDITS it — creates the draft if none is open (201), or UPDATES the
+        open draft with the provided check-flight fields (200; af_hours, landing_count,
+        utc_time, date, result, notes — all optional, partial edits allowed). Finalize
+        it via POST /mcf/sign/{id} (sign:true). `active:false` DEACTIVATES it — cancels
+        the open (unsigned) draft ("tidak jadi") and releases the MCF status; the
+        cancelled record stays in the list. A signed MCF is a real event and is not
+        cancelled.
+      parameters:
+      - description: Helicopter ID (UUIDv7)
+        in: path
+        name: helicopter_id
+        required: true
+        type: string
+      - description: JSON:API MCF set request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.MCFSetRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MCFResponse'
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MCFResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Set a helicopter's MCF Yes/No — draft work endpoint (create/update
+        or cancel)
+      tags:
+      - MCF
+  /api/v1/mcf/sign/{id}:
+    post:
+      consumes:
+      - application/json
+      description: 'Finalizes an MCF''s check-flight. `sign` (optional, default true):
+        true FINALIZES it — af_hours, landing_count, utc_time, date, result required;
+        "passed" clears the aircraft from MCF, "failed" keeps it grounded. false UNSIGNS
+        it — reverts a signed MCF back to a draft (keeps the recorded data). Editing
+        draft fields is done via /mcf/set; cancelling via /mcf/set (active:false).'
+      parameters:
+      - description: MCF ID (UUIDv7)
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: JSON:API MCF sign request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.MCFCompleteRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MCFResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Sign (finalize) or unsign an MCF — toggle by MCF id
+      tags:
+      - MCF
+  /api/v1/medicine-group/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a medicine group row.
+      parameters:
+      - description: JSON:API medicine group create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create medicine group
+      tags:
+      - OPC - Medicine Group
+  /api/v1/medicine-group/delete/{uuid}:
+    delete:
+      parameters:
+      - description: Medicine Group UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete medicine group
+      tags:
+      - OPC - Medicine Group
+  /api/v1/medicine-group/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        name, -name, created_at, -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Search by group name
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List medicine groups
+      tags:
+      - OPC - Medicine Group
+  /api/v1/medicine-group/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupDataTableResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List medicine groups (datatable)
+      tags:
+      - OPC - Medicine Group
+  /api/v1/medicine-group/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch medicine group by ID.
+      parameters:
+      - description: Medicine Group UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API medicine group update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineGroupResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update medicine group (partial)
+      tags:
+      - OPC - Medicine Group
+  /api/v1/medicine/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a medicine row.
+      parameters:
+      - description: JSON:API medicine create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create medicine
+      tags:
+      - OPC - Medicine
+  /api/v1/medicine/delete/{uuid}:
+    delete:
+      parameters:
+      - description: Medicine UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete medicine
+      tags:
+      - OPC - Medicine
+  /api/v1/medicine/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Search covers
+        name, note, pack, unit, and column. Sort values: name, -name, sortkey, -sortkey,
+        note, -note, pack, -pack, unit, -unit, column, -column, is_active, -is_active,
+        created_at, -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Search by name/note/pack/unit/column
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineListResponse'
+      summary: List medicine
+      tags:
+      - OPC - Medicine
+  /api/v1/medicine/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineDataTableResponse'
+      summary: List medicine (datatable)
+      tags:
+      - OPC - Medicine
+  /api/v1/medicine/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch medicine by ID.
+      parameters:
+      - description: Medicine UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API medicine update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MedicineResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update medicine (partial)
+      tags:
+      - OPC - Medicine
+  /api/v1/mission-type/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a mission category master record for use in mission flow.
+      parameters:
+      - description: JSON:API mission type create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.MissionTypeCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionTypeResource'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create mission type
+      tags:
+      - Flights - Mission
+  /api/v1/mission-type/get-all:
+    get:
+      description: Returns all mission categories and their available subtypes.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionTypeListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List mission types with subtypes
+      tags:
+      - Flights - Mission
+  /api/v1/mission/create:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Create a mission and link it to a flight.
+        `type` must be one of: `HEMS`, `CAT`, `SPO`, `NCO`.
+        `subtype_id` is required when `type=HEMS` and must reference mission subcategory under `HEMS` category.
+        `subtype_id` must be empty when `type` is not `HEMS`.
+      parameters:
+      - description: JSON:API mission create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.MissionCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "409":
+          description: Conflict
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create mission
+      tags:
+      - Flights - Mission
+  /api/v1/mission/delete-by-id/{mission_id}:
+    delete:
+      description: Soft delete mission by its mission UUID. This also soft deletes
+        flight data rows linked to the mission.
+      parameters:
+      - description: Mission ID (UUIDv7)
+        in: path
+        name: mission_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete mission by mission ID
+      tags:
+      - Flights - Mission
+  /api/v1/mission/delete/{flight_id}:
+    delete:
+      description: Soft delete mission by linked flight ID.
+      parameters:
+      - description: Flight ID (UUIDv7)
+        in: path
+        name: flight_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete mission
+      tags:
+      - Flights - Mission
+  /api/v1/mission/file/{mission_id}/{attachment_id}:
+    delete:
+      description: Detaches the file (by its attachment id) from the mission and deletes
+        the attachment.
+      parameters:
+      - description: Mission UUID
+        in: path
+        name: mission_id
+        required: true
+        type: string
+      - description: Attachment UUID (the file's attachment_id)
+        in: path
+        name: attachment_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Remove a file from a mission
+      tags:
+      - Flights - Mission
+  /api/v1/mission/get-all:
+    get:
+      description: Supports `search`, `filter[search]`, `flight_id`, `sort`, `page[number]`,
+        `page[size]`, `page`, `size`, and `limit`.
+      parameters:
+      - description: Search text
+        in: query
+        name: search
+        type: string
+      - description: Search text (JSON:API style)
+        in: query
+        name: filter[search]
+        type: string
+      - description: Filter by flight UUID
+        in: query
+        name: flight_id
+        type: string
+      - description: 'Filter missions by flight data status: draft, in_progress, or
+          completed'
+        in: query
+        name: flight_data_status
+        type: string
+      - description: 'Sort field: type|-type|flight_date|-flight_date|created_at|-created_at|updated_at|-updated_at'
+        in: query
+        name: sort
+        type: string
+      - description: Page number
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size
+        in: query
+        name: page[size]
+        type: integer
+      - description: Page number (fallback)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (fallback)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override
+        in: query
+        name: limit
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List missions
+      tags:
+      - Flights - Mission
+  /api/v1/mission/get-all/dt:
+    get:
+      description: |-
+        Supports `search`, `filter[search]`, `date_from`, `date_to`, `mission_type`, `pilot_id`, `helicopter_id`, `sort`, `start`, `length`, `draw`, `page[number]`, `page[size]`, `page`, `size`, and `limit`.
+        `date_from` and `date_to` filter flights by their mission date range (`YYYY-MM-DD`).
+        `mission_type` accepts `HEMS`, `CAT`, `SPO`, or `NCO`.
+        `pilot_id` filters missions where the pilot is assigned on the linked flight roster.
+        `helicopter_id` filters missions by the helicopter used in the linked flight takeover.
+      parameters:
+      - description: Search text
+        in: query
+        name: search
+        type: string
+      - description: Search text (JSON:API style)
+        in: query
+        name: filter[search]
+        type: string
+      - description: Filter by linked flight UUID
+        in: query
+        name: flight_id
+        type: string
+      - description: Mission date lower bound (YYYY-MM-DD)
+        in: query
+        name: date_from
+        type: string
+      - description: Mission date upper bound (YYYY-MM-DD)
+        in: query
+        name: date_to
+        type: string
+      - description: 'Mission type: HEMS|CAT|SPO|NCO'
+        in: query
+        name: mission_type
+        type: string
+      - description: Pilot user UUID
+        in: query
+        name: pilot_id
+        type: string
+      - description: Helicopter UUID
+        in: query
+        name: helicopter_id
+        type: string
+      - description: 'Sort field: type|-type|flight_date|-flight_date|created_at|-created_at|updated_at|-updated_at'
+        in: query
+        name: sort
+        type: string
+      - description: DataTables start index
+        in: query
+        name: start
+        type: integer
+      - description: DataTables page size
+        in: query
+        name: length
+        type: integer
+      - description: DataTables draw counter
+        in: query
+        name: draw
+        type: integer
+      - description: Page number
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size
+        in: query
+        name: page[size]
+        type: integer
+      - description: Page number (fallback)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (fallback)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override
+        in: query
+        name: limit
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionDataTableResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List missions (datatable)
+      tags:
+      - Flights - Mission
+  /api/v1/mission/get/{flight_id}:
+    get:
+      description: Get mission detail by linked flight ID.
+      parameters:
+      - description: Flight ID (UUIDv7)
+        in: path
+        name: flight_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get mission by flight ID
+      tags:
+      - Flights - Mission
+  /api/v1/mission/update/{mission_id}:
+    patch:
+      consumes:
+      - application/json
+      description: |-
+        Update mission type/subtype/note by mission ID, and optionally attach files already uploaded via `upload-mission-file`.
+        `type` must be one of: `HEMS`, `CAT`, `SPO`, `NCO`.
+        `subtype_id` is required when `type=HEMS` and must reference mission subcategory under `HEMS` category.
+        `subtype_id` must be empty when `type` is not `HEMS`.
+        `files[]` items reference an `upload_intent_uuid` (from `upload-mission-file`) and an optional display `name`.
+      parameters:
+      - description: Mission ID (UUIDv7)
+        in: path
+        name: mission_id
+        required: true
+        type: string
+      - description: JSON:API mission update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.MissionUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.MissionResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update mission
+      tags:
+      - Flights - Mission
+  /api/v1/motor-reaction/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a motor reaction row.
+      parameters:
+      - description: JSON:API motor reaction create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create motor reaction
+      tags:
+      - OPC - Motor Reaction
+  /api/v1/motor-reaction/delete/{uuid}:
+    delete:
+      parameters:
+      - description: Motor Reaction UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete motor reaction
+      tags:
+      - OPC - Motor Reaction
+  /api/v1/motor-reaction/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        name, -name, score, -score, created_at, -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Search by reaction name or score
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List motor reactions
+      tags:
+      - OPC - Motor Reaction
+  /api/v1/motor-reaction/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionDataTableResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: List motor reactions (datatable)
+      tags:
+      - OPC - Motor Reaction
+  /api/v1/motor-reaction/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch motor reaction by ID.
+      parameters:
+      - description: Motor Reaction UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API motor reaction update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.MotorReactionResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update motor reaction (partial)
+      tags:
+      - OPC - Motor Reaction
+  /api/v1/opc/create:
+    post:
+      consumes:
+      - application/json
+      description: Create an OPC row.
+      parameters:
+      - description: JSON:API OPC create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.OpcCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.OpcResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create opc
+      tags:
+      - OPC - OPC
+  /api/v1/opc/delete/{uuid}:
+    delete:
+      parameters:
+      - description: OPC UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete opc
+      tags:
+      - OPC - OPC
+  /api/v1/opc/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        title, -title, sortkey, -sortkey, note, -note, is_active, -is_active, created_at,
+        -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Search by title/note
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.OpcListResponse'
+      summary: List opc
+      tags:
+      - OPC - OPC
+  /api/v1/opc/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.OpcDataTableResponse'
+      summary: List opc (datatable)
+      tags:
+      - OPC - OPC
+  /api/v1/opc/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch opc by ID.
+      parameters:
+      - description: OPC UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API OPC update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.OpcUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.OpcResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update opc (partial)
+      tags:
+      - OPC - OPC
+  /api/v1/patient-data/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a PatientData record.
+      parameters:
+      - description: JSON:API PatientData create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create patient data
+      tags:
+      - PatientData - PatientData
+  /api/v1/patient-data/delete/{uuid}:
+    delete:
+      description: Soft delete PatientData by ID.
+      parameters:
+      - description: PatientData UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete patient data
+      tags:
+      - PatientData - PatientData
+  /api/v1/patient-data/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        family_name, -family_name, first_name, -first_name, birth_date, -birth_date,
+        gender, -gender, created_at, -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Search by family_name/first_name/svnr/email/phone/street
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataListResponse'
+      summary: List patient data
+      tags:
+      - PatientData - PatientData
+  /api/v1/patient-data/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search by family_name/first_name/svnr/email/phone/street
+        in: query
+        name: search
+        type: string
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataDataTableResponse'
+      summary: List patient data (datatable)
+      tags:
+      - PatientData - PatientData
+  /api/v1/patient-data/get/{uuid}:
+    get:
+      description: Get a single PatientData record by UUID.
+      parameters:
+      - description: PatientData UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get patient data by ID
+      tags:
+      - PatientData - PatientData
+  /api/v1/patient-data/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch PatientData by ID.
+      parameters:
+      - description: PatientData UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API PatientData update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.PatientDataResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update patient data (partial)
+      tags:
+      - PatientData - PatientData
+  /api/v1/public/branding/email-logo:
+    get:
+      description: |-
+        Return a stable company logo optimized for email clients like Outlook.
+        Backend prefers managed raster thumbnail/logo and falls back to backend-generated PNG when necessary.
+        Supports conditional requests with `If-None-Match` / `If-Modified-Since`.
+      produces:
+      - image/png
+      - image/jpeg
+      - image/gif
+      - application/octet-stream
+      responses:
+        "200":
+          description: Email-safe branding logo binary
+          schema:
+            type: file
+        "304":
+          description: Not Modified
+          schema:
+            type: string
+      summary: Get email-safe branding logo
+      tags:
+      - Branding
+  /api/v1/reserve-acs/create:
+    post:
+      consumes:
+      - application/json
+      description: Create reserve AC, create draft inspection, fill before + prepare
+        inspection payload, and assign to flight.
+      parameters:
+      - description: Create reserve AC request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create reserve aircraft assignment
+      tags:
+      - Flights - Reserve AC
+  /api/v1/reserve-acs/delete:
+    delete:
+      consumes:
+      - application/json
+      description: Delete reserve AC by body `data.id`.
+      parameters:
+      - description: Delete reserve AC request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcDeleteRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.Document'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete reserve AC
+      tags:
+      - Flights - Reserve AC
+  /api/v1/reserve-acs/get-all:
+    get:
+      description: Supports `search`, `filter[search]`, `sort`, `page[number]`, `page[size]`,
+        `page`, `size`, and `limit`.
+      parameters:
+      - description: Search text
+        in: query
+        name: search
+        type: string
+      - description: Search text (JSON:API style)
+        in: query
+        name: filter[search]
+        type: string
+      - description: Reserve AC UUID (exact match)
+        in: query
+        name: id
+        type: string
+      - description: Flight UUID (exact match)
+        in: query
+        name: flight_id
+        type: string
+      - description: Sort field
+        in: query
+        name: sort
+        type: string
+      - description: Page number
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size
+        in: query
+        name: page[size]
+        type: integer
+      - description: Page number (fallback)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (fallback)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override
+        in: query
+        name: limit
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ReserveAcListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List reserve AC
+      tags:
+      - Flights - Reserve AC
+  /api/v1/reserve-acs/get-all/dt:
+    get:
+      description: Datatable list scoped by auth user. Admin can see all rows; non-admin
+        only sees reserve AC linked to own flight assignments.
+      parameters:
+      - description: Search text
+        in: query
+        name: search
+        type: string
+      - description: Search text (JSON:API style)
+        in: query
+        name: filter[search]
+        type: string
+      - description: Reserve AC UUID (exact match)
+        in: query
+        name: id
+        type: string
+      - description: Flight UUID (exact match)
+        in: query
+        name: flight_id
+        type: string
+      - description: Sort field
+        in: query
+        name: sort
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ReserveAcListResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List reserve AC (datatable)
+      tags:
+      - Flights - Reserve AC
+  /api/v1/reserve-acs/get/{uuid}:
+    get:
+      description: Get reserve AC detail. Path `uuid` accepts reserve_ac id, and supports
+        fallback to flight id.
+      parameters:
+      - description: Reserve AC UUID or Flight UUID
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get reserve AC by UUID or flight UUID
+      tags:
+      - Flights - Reserve AC
+  /api/v1/reserve-acs/update:
+    patch:
+      consumes:
+      - application/json
+      description: Update reserve AC using body `data.id`.
+      parameters:
+      - description: Update reserve AC request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.ReserveAcUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.ReserveAcResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Update reserve AC
+      tags:
+      - Flights - Reserve AC
+  /api/v1/roles/{uuid}/permissions:
+    get:
+      description: Returns the permissions currently assigned to the given role. Pair
+        with /roles/permissions/get-all to pre-check a role-permission editor.
+      parameters:
+      - description: Role UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionListResponse'
+      summary: List a role's assigned permissions
+      tags:
+      - Roles
+    post:
+      consumes:
+      - application/json
+      description: Assign one permission to a role. Idempotent if already assigned.
+      parameters:
+      - description: Role UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API role permission assign request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Assign permission to role
+      tags:
+      - Roles
+  /api/v1/roles/{uuid}/permissions/{permission_uuid}:
+    delete:
+      description: Remove one permission from role.
+      parameters:
+      - description: Role UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: Permission UUID (UUIDv7)
+        in: path
+        name: permission_uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Remove permission from role
+      tags:
+      - Roles
+  /api/v1/roles/{uuid}/permissions/assign-bulk:
+    post:
+      consumes:
+      - application/json
+      description: Assign multiple permissions to role. Idempotent for duplicates/already
+        assigned.
+      parameters:
+      - description: Role UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API role permission bulk request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionAssignBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionListResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Assign permissions to role (bulk)
+      tags:
+      - Roles
+  /api/v1/roles/{uuid}/permissions/remove-bulk:
+    post:
+      consumes:
+      - application/json
+      description: Remove multiple permissions from role.
+      parameters:
+      - description: Role UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API role permission bulk request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionRemoveBulkRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.RolePermissionListResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Remove permissions from role (bulk)
+      tags:
+      - Roles
+  /api/v1/roles/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a new role. Name is required and must be unique.
+      parameters:
+      - description: JSON:API Role create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.RoleCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.RoleResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create role
+      tags:
+      - Roles
+  /api/v1/roles/delete/{uuid}:
+    delete:
+      parameters:
+      - description: Role UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete role
+      tags:
+      - Roles
+  /api/v1/roles/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        name, -name, created_at, -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Filter by name (contains)
+        in: query
+        name: filter[name]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      - description: Set to 'permissions' to embed each role's assigned permissions
+        in: query
+        name: include
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.RoleListResponse'
+      summary: List roles
+      tags:
+      - Roles
+  /api/v1/roles/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.RoleDataTableResponse'
+      summary: List roles (datatable)
+      tags:
+      - Roles
+  /api/v1/roles/get/{uuid}:
+    get:
+      parameters:
+      - description: Role UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.RoleResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get role by ID
+      tags:
+      - Roles
+  /api/v1/roles/permissions/{permission_uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch permission by ID. Currently supports updating requires_pin.
+      parameters:
+      - description: Permission UUID (UUIDv7)
+        in: path
+        name: permission_uuid
+        required: true
+        type: string
+      - description: JSON:API permission update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionResource'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update permission
+      tags:
+      - Roles
+  /api/v1/roles/permissions/get-all:
+    get:
+      description: Returns every permission grouped by its module, ordered by the
+        module registry. Optional filter[name] narrows by permission name/key.
+      parameters:
+      - description: Filter by name/key (contains)
+        in: query
+        name: filter[name]
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.PermissionGroupedResponse'
+      summary: List permissions grouped by module
+      tags:
+      - Roles
+  /api/v1/roles/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: 'Patch role by ID. Provide at least one of: name, description.
+        Name must be unique if provided.'
+      parameters:
+      - description: Role UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API Role update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.RoleUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.RoleResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update role (partial)
+      tags:
+      - Roles
+  /api/v1/takeovers/create:
+    post:
+      consumes:
+      - application/json
+      description: |-
+        Atomic create for duty roster + crews + reserve AC + pre-flight inspection + flight. The takeover inspection payload also includes fleet status files under `inspection.fleet_status_file`.
+        Optional takeover file uploads can be included via `data.attributes.files[*]` using upload intent UUIDs.
+        Edited template draft files created earlier can be linked by passing `data.attributes.edited_template_file_ids[*]`.
+      parameters:
+      - description: Create takeover request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Create takeover in one request
+      tags:
+      - Flight - Takeovers
+  /api/v1/takeovers/delete/{id}:
+    delete:
+      parameters:
+      - description: Flight UUID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Delete takeover by flight UUID
+      tags:
+      - Flight - Takeovers
+  /api/v1/takeovers/get-all:
+    get:
+      description: Return composite takeover records built from flight, reserve AC,
+        duty roster, and inspection. The inspection payload includes `before`, `prepare`,
+        and `fleet_status_file`.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            additionalProperties: true
+            type: object
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: List takeovers
+      tags:
+      - Flight - Takeovers
+  /api/v1/takeovers/get/{id}:
+    get:
+      parameters:
+      - description: Flight UUID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Get takeover by flight UUID
+      tags:
+      - Flight - Takeovers
+  /api/v1/takeovers/update/{id}:
+    patch:
+      consumes:
+      - application/json
+      parameters:
+      - description: Flight UUID
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: Update takeover request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto_request.TakeoverUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto_response.TakeoverResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_jsonapi.ErrorDocument'
+      summary: Replace takeover by flight UUID
+      tags:
+      - Flight - Takeovers
+  /api/v1/users/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a new user. Email, username, first name, last name and role_id
+        are required. Use role_ids to assign additional roles.
+      parameters:
+      - description: JSON:API User create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.UserCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.UserResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create user
+      tags:
+      - Users
+  /api/v1/users/delete/{uuid}:
+    delete:
+      parameters:
+      - description: User UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete user
+      tags:
+      - Users
+  /api/v1/users/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        email, -email, first_name, -first_name, last_name, -last_name, created_at,
+        -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Search by username/email/first_name/last_name (contains)
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.UserListResponse'
+      summary: List users
+      tags:
+      - Users
+  /api/v1/users/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.UserDataTableResponse'
+      summary: List users (datatable)
+      tags:
+      - Users
+  /api/v1/users/get/{uuid}:
+    get:
+      parameters:
+      - description: User UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.UserResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Get user by ID
+      tags:
+      - Users
+  /api/v1/users/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch user by ID. Provide at least one attribute to update.
+      parameters:
+      - description: User UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API User update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.UserUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.UserResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update user (partial)
+      tags:
+      - Users
+  /api/v1/vocation/create:
+    post:
+      consumes:
+      - application/json
+      description: Create a vocation row.
+      parameters:
+      - description: JSON:API vocation create request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.VocationCreateRequest'
+      produces:
+      - application/json
+      responses:
+        "201":
+          description: Created
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.VocationResponse'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Create vocation
+      tags:
+      - OPC - Vocation
+  /api/v1/vocation/delete/{uuid}:
+    delete:
+      parameters:
+      - description: Vocation UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.GenericDeleteResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Delete vocation
+      tags:
+      - OPC - Vocation
+  /api/v1/vocation/get-all:
+    get:
+      description: 'JSON:API list with pagination, filtering and sorting. Sort values:
+        name, -name, sortkey, -sortkey, note, -note, is_active, -is_active, created_at,
+        -created_at, updated_at, -updated_at.'
+      parameters:
+      - description: Search by name/note
+        in: query
+        name: filter[search]
+        type: string
+      - description: Page number (default 1)
+        in: query
+        name: page[number]
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: page[size]
+        type: integer
+      - description: Sort order
+        in: query
+        name: sort
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.VocationListResponse'
+      summary: List vocation
+      tags:
+      - OPC - Vocation
+  /api/v1/vocation/get-all/dt:
+    get:
+      description: Datatable response with simple pagination params.
+      parameters:
+      - description: Page number (default 1)
+        in: query
+        name: page
+        type: integer
+      - description: Page size (default 20, max 100)
+        in: query
+        name: size
+        type: integer
+      - description: Page size override (same as size)
+        in: query
+        name: limit
+        type: integer
+      - description: Draw counter (optional)
+        in: query
+        name: draw
+        type: integer
+      - description: Search term
+        in: query
+        name: search
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.VocationDataTableResponse'
+      summary: List vocation (datatable)
+      tags:
+      - OPC - Vocation
+  /api/v1/vocation/update/{uuid}:
+    patch:
+      consumes:
+      - application/json
+      description: Patch vocation by ID.
+      parameters:
+      - description: Vocation UUID (UUIDv7)
+        in: path
+        name: uuid
+        required: true
+        type: string
+      - description: JSON:API vocation update request
+        in: body
+        name: request
+        required: true
+        schema:
+          $ref: '#/definitions/wucher_internal_transport_http_dto.VocationUpdateRequest'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.VocationResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+        "422":
+          description: Unprocessable Entity
+          schema:
+            $ref: '#/definitions/wucher_internal_transport_http_dto.ErrorResponse'
+      summary: Update vocation (partial)
+      tags:
+      - OPC - Vocation
+swagger: "2.0"
+tags:
+- description: Corrective-action sign-off for a helicopter. After a complaint's action_taken
+    is recorded, it is signed off here (POST /action-signoffs/sign with complaint_id);
+    a fleet-wide sign-off (no complaint_id) is also supported. A signed sign-off is
+    the prerequisite for creating an EASA maintenance release.
+  name: Complaints - Sign Off
diff --git a/docs/takeover-file-api.md b/docs/takeover-file-api.md
new file mode 100644
index 0000000..bce50a5
--- /dev/null
+++ b/docs/takeover-file-api.md
@@ -0,0 +1,483 @@
+# Takeover File API
+
+Dokumen ini menjelaskan alur lengkap file pada `takeover`:
+
+1. upload intent file
+2. finalize upload menjadi file manager file tanpa parent takeover
+3. create takeover baru sambil menempelkan file pakai `file_id`
+4. update takeover dengan mode add, remove, atau replace file
+5. response takeover dan FM report yang menampilkan file
+6. SSE yang tetap dipakai dari file manager
+
+## Ringkasan Konsep
+
+Ada 3 objek yang perlu dibedakan:
+
+1. `file`
+   - file fisik di file manager
+2. `attachment`
+   - relasi file ke reference bisnis, misalnya `takeover`
+3. `takeover_file`
+   - relasi khusus takeover ke `file_attachment_id`
+
+Flow yang dipakai di sistem ini:
+
+1. FE minta upload intent ke file manager
+2. FE upload binary file ke storage
+3. FE finalize file lewat endpoint takeover file dan menerima `file_id`
+4. FE kirim `file_id` saat create/update takeover
+5. Backend membuat attachment `ref_type = takeover`
+6. Backend menyimpan relasi takeover file
+
+## Endpoint Yang Dipakai
+
+### File Manager
+
+#### Request upload intent untuk takeover
+
+`POST /api/v1/file-manager/files/upload-takeover-file`
+
+Fungsi:
+
+1. minta upload intent
+2. dapat `upload_intent_uuid`
+3. dapat `upload_url`
+
+#### Finalize file takeover
+
+`POST /api/v1/file-manager/files/create-takeover-file`
+
+Fungsi:
+
+1. finalize file dari upload intent
+2. membuat file manager file node
+3. mengembalikan `file_id` untuk dipakai di takeover create/update
+
+Endpoint ini tidak membuat `attachment` dan tidak membuat row `takeover_files`.
+
+Catatan:
+- `takeover_uuid` tidak wajib
+- file boleh sementara tanpa parent takeover
+- attachment takeover baru dibuat saat `POST /api/v1/takeovers/create` atau `PATCH /api/v1/takeovers/update/{id}`
+
+### Takeover
+
+#### Create takeover baru
+
+`POST /api/v1/takeovers/create`
+
+#### Update takeover
+
+`PATCH /api/v1/takeovers/update/{id}`
+
+## Flow Create Takeover Dengan File
+
+### 1. FE minta upload intent file
+
+Pakai endpoint:
+
+`POST /api/v1/file-manager/files/upload-takeover-file`
+
+Contoh payload:
+
+```json
+{
+  "data": [
+    {
+      "type": "file_manager_file_upload_intent",
+      "attributes": {
+        "name": "takeover-report.pdf",
+        "content_type": "application/pdf",
+        "size_bytes": 123456
+      }
+    }
+  ]
+}
+```
+
+Response akan mengembalikan:
+
+1. `upload_intent_uuid`
+2. `upload_url`
+3. `method`
+4. `required_headers`
+
+### 2. FE upload binary ke storage
+
+Gunakan `upload_url` dan `method` dari response upload intent.
+
+### 3. FE finalize upload menjadi file manager file
+
+Pakai endpoint:
+
+`POST /api/v1/file-manager/files/create-takeover-file`
+
+Contoh payload:
+
+```json
+{
+  "data": [
+    {
+      "type": "file_manager_file_create",
+      "attributes": {
+        "upload_intent_uuid": "019e8713-aa19-7fb7-a510-a0332dc69697",
+        "name": "takeover-report.pdf"
+      }
+    }
+  ]
+}
+```
+
+Response akan mengembalikan file manager resource. Ambil `data[0].resource.id` sebagai `file_id`.
+
+Contoh potongan response:
+
+```json
+{
+  "data": [
+    {
+      "index": 0,
+      "success": true,
+      "resource": {
+        "type": "file_manager_file",
+        "id": "019e8714-1111-7aaa-8bbb-222222222222",
+        "attributes": {
+          "name": "takeover-report.pdf"
+        }
+      }
+    }
+  ]
+}
+```
+
+### 4. FE kirim takeover create
+
+Pakai endpoint:
+
+`POST /api/v1/takeovers/create`
+
+Field file yang didukung:
+
+`data.attributes.files[]`
+
+Struktur item:
+
+```json
+{
+  "file_id": "019e8714-1111-7aaa-8bbb-222222222222"
+}
+```
+
+Contoh payload:
+
+```json
+{
+  "data": {
+    "type": "takeover_create",
+    "attributes": {
+      "base_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
+      "duty_date": "2026-06-22",
+      "notes": "Takeover baru dengan file",
+      "files": [
+        {
+          "file_id": "019e8714-1111-7aaa-8bbb-222222222222"
+        }
+      ]
+    }
+  }
+}
+```
+
+### 5. Backend attach file ke takeover
+
+Saat request create takeover diproses, backend akan:
+
+1. membuat takeover
+2. membaca `file_id` dari `data.attributes.files[]`
+3. create attachment dengan `ref_type = takeover`
+4. menyimpan relasi ke `takeover_files`
+
+Catatan kompatibilitas:
+- item lama dengan `upload_intent_uuid` masih didukung sebagai fallback
+- flow baru yang disarankan adalah kirim `file_id`
+
+## Flow Update Takeover Dengan File
+
+Pakai endpoint:
+
+`PATCH /api/v1/takeovers/update/{id}`
+
+Ada 3 mode yang disarankan.
+
+### Mode 1. Add file baru
+
+Gunakan:
+
+- `files`
+- atau `files_add`
+
+Keduanya menerima item yang sama:
+
+```json
+{
+  "file_id": "019e8714-3333-7aaa-8bbb-444444444444"
+}
+```
+
+Contoh:
+
+```json
+{
+  "data": {
+    "type": "takeover_update",
+    "id": "019eed5d-36c2-72d9-acab-388b4e41a949",
+    "attributes": {
+      "notes": "Tambah file baru",
+      "files_add": [
+        {
+          "file_id": "019e8714-3333-7aaa-8bbb-444444444444"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Mode 2. Remove file tertentu
+
+Gunakan:
+
+`files_remove`
+
+Isi field ini adalah `file_attachment_id`, bukan `takeover_file.id`.
+
+Contoh:
+
+```json
+{
+  "data": {
+    "type": "takeover_update",
+    "id": "019eed5d-36c2-72d9-acab-388b4e41a949",
+    "attributes": {
+      "files_remove": [
+        "019d7000-aaaa-7bbb-8ccc-222222222222"
+      ]
+    }
+  }
+}
+```
+
+Saat remove:
+
+1. relasi `takeover_files` dihapus
+2. attachment file-manager juga dihapus
+3. file lifecycle ikut direconcile oleh file manager
+
+### Mode 3. Replace semua file
+
+Gunakan:
+
+`files_replace`
+
+Mode ini:
+
+1. menghapus semua file lama dari takeover
+2. menambahkan daftar file baru
+
+Aturan:
+
+1. `files_replace` tidak boleh digabung dengan `files`
+2. `files_replace` tidak boleh digabung dengan `files_add`
+3. `files_replace` tidak boleh digabung dengan `files_remove`
+
+Contoh:
+
+```json
+{
+  "data": {
+    "type": "takeover_update",
+    "id": "019eed5d-36c2-72d9-acab-388b4e41a949",
+    "attributes": {
+      "files_replace": [
+        {
+          "file_id": "019e8714-5555-7aaa-8bbb-666666666666"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Mode campuran: add + remove
+
+Kalau kamu ingin menambah file baru sambil menghapus file lama, pakai:
+
+1. `files_add`
+2. `files_remove`
+
+Contoh:
+
+```json
+{
+  "data": {
+    "type": "takeover_update",
+    "id": "019eed5d-36c2-72d9-acab-388b4e41a949",
+    "attributes": {
+      "files_add": [
+        {
+          "file_id": "019e8714-7777-7aaa-8bbb-888888888888"
+        }
+      ],
+      "files_remove": [
+        "019d7000-aaaa-7bbb-8ccc-222222222222"
+      ]
+    }
+  }
+}
+```
+
+## Validation Rules
+
+### Create takeover
+
+Field yang wajib:
+
+1. `duty_date`
+
+Field file:
+
+1. `files[]` opsional
+2. untuk flow baru, setiap item file berisi:
+   - `file_id`
+
+Catatan:
+- `upload_intent_uuid` + `name` masih bisa dipakai sebagai fallback lama
+- untuk flow baru, gunakan `file_id` dari response `/create-takeover-file`
+
+### Update takeover
+
+Field file yang tersedia:
+
+1. `files`
+2. `files_add`
+3. `files_remove`
+4. `files_replace`
+
+Aturan kombinasi:
+
+1. `files_replace` eksklusif
+2. `files` dan `files_add` diperlakukan sebagai add file baru
+3. `files_remove` harus berisi UUID attachment yang masih terhubung ke takeover
+
+## Response Takeover
+
+Response takeover sekarang punya field:
+
+`data.attributes.files`
+
+Contoh item:
+
+```json
+{
+  "type": "takeover_file",
+  "id": "019d7000-aaaa-7bbb-8ccc-111111111111",
+  "attributes": {
+    "file_attachment_id": "019d7000-aaaa-7bbb-8ccc-222222222222",
+    "file_name": "takeover-report.pdf",
+    "download_url": "https://..."
+  }
+}
+```
+
+Arti field:
+
+1. `id`
+   - UUID relasi `takeover_file`
+2. `file_attachment_id`
+   - UUID attachment file-manager
+3. `file_name`
+   - nama file yang tersimpan
+4. `download_url`
+   - URL download file jika storage tersedia
+
+## Response FM Report
+
+Response `fm report` juga menampilkan file takeover melalui:
+
+`data.attributes.takeover_files`
+
+Isi resource sama seperti response takeover:
+
+1. `id`
+2. `file_attachment_id`
+3. `file_name`
+4. `download_url`
+
+## SSE
+
+Flow takeover file tetap memakai SSE file manager yang sudah ada.
+
+Event utama:
+
+`file.updated`
+
+Artinya saat file berhasil difinalisasi atau status file berubah, FE tetap bisa mendengarkan event realtime dari stream file manager.
+
+Endpoint stream:
+
+`GET /api/v1/file-manager/events`
+
+Catatan:
+
+1. belum ada stream SSE takeover-file khusus
+2. yang dipakai adalah stream file manager yang sudah eksisting
+
+## Migration dan Struktur Database
+
+Tabel baru:
+
+`takeover_files`
+
+Kolom:
+
+1. `id`
+2. `takeover_id`
+3. `file_attachment_id`
+
+Migration:
+
+`migrations/20260622_create_takeover_files.sql`
+
+## Best Practice Pemakaian
+
+1. Finalize upload dulu lewat `/api/v1/file-manager/files/create-takeover-file`
+2. Kalau takeover sudah ada, gunakan `PATCH /api/v1/takeovers/update/{id}`
+3. Pakai `files_replace` hanya kalau memang ingin mengganti semua file
+4. Pakai `files_add` dan `files_remove` kalau ingin perubahan parsial yang lebih aman
+5. Untuk menghapus file, gunakan `file_attachment_id` dari response takeover
+
+## Contoh Alur Yang Disarankan
+
+### Create takeover baru dengan 1 file
+
+1. request upload intent
+2. upload binary ke storage
+3. panggil `POST /api/v1/file-manager/files/create-takeover-file`
+4. ambil `file_id` dari response
+5. panggil `POST /api/v1/takeovers/create` dengan `files[].file_id`
+
+### Update takeover dan tambah file baru
+
+1. request upload intent
+2. upload binary ke storage
+3. panggil `POST /api/v1/file-manager/files/create-takeover-file`
+4. ambil `file_id` dari response
+5. panggil `PATCH /api/v1/takeovers/update/{id}` dengan `files_add[].file_id`
+
+### Update takeover dan replace semua file
+
+1. request upload intent baru untuk file pengganti
+2. upload binary ke storage
+3. panggil `POST /api/v1/file-manager/files/create-takeover-file`
+4. ambil `file_id` dari response
+5. panggil `PATCH /api/v1/takeovers/update/{id}` dengan `files_replace[].file_id`
diff --git a/docs/takeover-step-by-step.md b/docs/takeover-step-by-step.md
new file mode 100644
index 0000000..e224379
--- /dev/null
+++ b/docs/takeover-step-by-step.md
@@ -0,0 +1,578 @@
+# Takeover Flow Step by Step
+
+Dokumen ini menjelaskan flow `takeover` dari sisi frontend secara detail: endpoint yang dipakai, urutan request, payload yang wajib dan opsional, serta contoh request/response.
+
+Untuk detail khusus file takeover, lihat [docs/takeover-file-api.md](./takeover-file-api.md).
+
+## Ringkasan Singkat
+
+`Takeover` adalah endpoint atomic untuk membuat satu paket data sekaligus:
+
+1. `takeover_ac`
+2. `duty_roster`
+3. `reserve_ac`
+4. `flight_inspection`
+5. `before_flight_inspection`
+6. `flight_prep_check`
+7. `flight`
+
+Artinya frontend cukup kirim **1 request create takeover**, backend akan membuat seluruh record terkait dalam satu transaksi.
+
+## Endpoint Yang Tersedia
+
+Ada 1 route create takeover yang menuju handler yang sama:
+
+1. `POST /api/v1/takeovers/create`
+
+Keduanya memakai permission:
+
+`reserve_ac.create`
+
+Route lain yang tersedia:
+
+1. `GET /api/v1/takeovers/get-all`
+2. `GET /api/v1/takeovers/get/:id`
+3. `PATCH /api/v1/takeovers/update/:id`
+4. `DELETE /api/v1/takeovers/delete/:id`
+
+Untuk dokumentasi ini fokus utama ada pada flow `create takeover`.
+
+## Step by Step Flow
+
+### Step 1. Siapkan data master terlebih dahulu
+
+Sebelum hit create takeover, frontend harus sudah punya:
+
+1. `base_id`
+2. `helicopter_id`
+3. `duty_date`
+4. daftar crew untuk roster
+5. data inspeksi sebelum terbang
+6. data persiapan flight
+
+Kalau salah satu ID tidak valid atau tidak ditemukan, backend akan gagal.
+
+### Step 2. Susun payload utama
+
+Payload mengikuti format JSON:API sederhana:
+
+```json
+{
+  "data": {
+    "type": "takeover",
+    "attributes": {
+      ...
+    }
+  }
+}
+```
+
+Field `type` menerima:
+
+1. `takeover`
+2. `takeover_create`
+
+Frontend boleh kirim salah satu, tapi disarankan konsisten pakai `takeover_create` atau `takeover` sesuai standar proyek yang dipakai tim.
+
+### Step 3. Kirim request create
+
+Request create akan:
+
+1. validasi JSON
+2. validasi struktur payload
+3. validasi UUID `base_id`
+4. validasi UUID `helicopter_id`
+5. validasi tanggal `duty_date`
+6. membangun roster crew
+7. membuat seluruh data dalam 1 transaksi
+8. mengembalikan response takeover lengkap
+
+Kalau satu sub-step gagal, seluruh transaksi gagal.
+
+### Step 4. Terima response
+
+Response sukses akan mengembalikan struktur `takeover` lengkap berisi:
+
+1. `takeover_ac_id`
+2. `duty_roster_id`
+3. `flight_id`
+4. `reserve_ac_id`
+5. `flight_inspection_id`
+6. `shift_start`
+7. `shift_end`
+8. `base`
+9. `helicopter`
+10. `roster_detail`
+11. `inspection`
+12. `flight`
+13. `duty_roster`
+
+Frontend sebaiknya memakai response ini sebagai sumber data final, bukan mengasumsikan data lokal sama persis dengan hasil backend.
+
+## Request Detail
+
+### Endpoint
+
+`POST /api/v1/takeovers/create`
+
+atau
+
+`POST /api/v1/reserve-acs/takeovers/create`
+
+### Headers
+
+Gunakan header umum API proyek:
+
+```http
+Authorization: Bearer <token>
+Content-Type: application/json
+Accept: application/json
+```
+
+### Body
+
+```json
+{
+  "data": {
+    "type": "takeover",
+    "attributes": {
+      "base_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
+      "duty_date": "2026-04-15",
+      "notes": "Opsional catatan takeover",
+      "shift_time": {
+        "shift_start": "06:00",
+        "shift_end": "18:00"
+      },
+      "roster_detail": {
+        "pilot": [
+          {
+            "id": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d",
+            "crew_type": "main",
+            "flight_instructor": true,
+            "line_checker": false,
+            "supervisor": false,
+            "examiner": false,
+            "co_pilot": true,
+            "shift_date": {
+              "date_start": "2026-04-15",
+              "date_end": "2026-04-15"
+            },
+            "shift_time": {
+              "shift_start": "06:00",
+              "shift_end": "14:00"
+            }
+          }
+        ],
+        "doctor": [
+          {
+            "id": "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"
+          }
+        ],
+        "rescuer": [],
+        "helper": [],
+        "other_person": [
+          {
+            "name": "Guest Person",
+            "mobile_phone": "+43-1234",
+            "email": "guest@example.com"
+          }
+        ]
+      },
+      "helicopter_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
+      "inspection": {
+        "inspection_date": "2026-04-15",
+        "before": {
+          "oil_engine_nr1_checked": true,
+          "oil_engine_nr2_checked": false,
+          "hydraulic_lh_checked": true,
+          "hydraulic_rh_checked": true,
+          "oil_transmission_mgb_checked": true,
+          "oil_transmission_igb_checked": true,
+          "oil_transmission_tgb_checked": true,
+          "fuel_amount": 50.5,
+          "fuel_unit": "LT",
+          "fuel_added_amount": 10,
+          "note": "Opsional note inspeksi sebelum terbang",
+          "file_checklist": [
+            {
+              "helicopter_file_id": "019d7000-aaaa-7bbb-8ccc-111111111111",
+              "is_done": true
+            }
+          ]
+        },
+        "prepare": {
+          "notam_briefing": true,
+          "weather_briefing": true,
+          "operational_flight_plan": false,
+          "file_checklist": [
+            {
+              "helicopter_file_id": "019d7000-bbbb-7ccc-8ddd-222222222222",
+              "is_done": true
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+## Penjelasan Field
+
+### `data`
+
+Container utama request.
+
+### `data.type`
+
+Nilai yang diterima:
+
+1. `takeover`
+2. `takeover_create`
+
+### `data.attributes.base_id`
+
+Wajib. UUID base yang dipakai untuk takeover.
+
+Backend akan memvalidasi:
+
+1. format UUID
+2. base harus ada di database
+
+### `data.attributes.duty_date`
+
+Wajib. Format tanggal harus `YYYY-MM-DD`.
+
+Contoh:
+
+`2026-04-15`
+
+### `data.attributes.notes`
+
+Opsional.
+
+Gunakan untuk catatan tambahan takeover. Jika tidak ada, field ini boleh tidak dikirim atau dikirim `null`.
+
+### `data.attributes.shift_time`
+
+Secara schema tidak diberi `validate:"required"`, tetapi secara proses bisnis ini dianggap bagian penting dari takeover.
+
+Format:
+
+```json
+{
+  "shift_start": "06:00",
+  "shift_end": "18:00"
+}
+```
+
+Keterangan:
+
+1. `shift_start` adalah waktu mulai tugas.
+2. `shift_end` adalah waktu selesai tugas.
+
+Jika frontend ingin aman, selalu kirim kedua field ini.
+
+### `data.attributes.roster_detail`
+
+Wajib secara bisnis. Berisi daftar crew yang akan masuk ke `duty_roster`.
+
+Strukturnya terdiri dari:
+
+1. `pilot`
+2. `doctor`
+3. `rescuer`
+4. `helper`
+5. `other_person`
+
+### `data.attributes.helicopter_id`
+
+Wajib. UUID helicopter yang dipakai pada takeover.
+
+Backend akan memvalidasi:
+
+1. format UUID
+2. helicopter harus ada di database
+
+### `data.attributes.inspection`
+
+Wajib. Ini adalah paket inspeksi takeover.
+
+#### `inspection.inspection_date`
+
+Wajib. Format `YYYY-MM-DD`.
+
+#### `inspection.before`
+
+Wajib sebagai objek, tetapi isi field di dalamnya sebagian besar opsional.
+
+Field opsional:
+
+1. `oil_engine_nr1_checked`
+2. `oil_engine_nr2_checked`
+3. `hydraulic_lh_checked`
+4. `hydraulic_rh_checked`
+5. `oil_transmission_mgb_checked`
+6. `oil_transmission_igb_checked`
+7. `oil_transmission_tgb_checked`
+8. `fuel_amount`
+9. `fuel_unit`
+10. `fuel_added_amount`
+11. `note`
+12. `file_checklist`
+
+#### `inspection.before.fuel_unit`
+
+Jika dikirim, nilai yang diterima backend adalah:
+
+1. `LT`
+2. `KG`
+3. `POUND`
+
+Kalau nilainya tidak valid, request akan gagal.
+
+#### `inspection.before.file_checklist`
+
+Array opsional.
+
+Setiap item harus punya:
+
+1. `helicopter_file_id`
+2. `is_done`
+
+#### `inspection.prepare`
+
+Wajib sebagai objek, tetapi field di dalamnya opsional.
+
+Field opsional:
+
+1. `notam_briefing`
+2. `weather_briefing`
+3. `operational_flight_plan`
+4. `file_checklist`
+
+#### `inspection.prepare.file_checklist`
+
+Array opsional.
+
+Setiap item harus punya:
+
+1. `helicopter_file_id`
+2. `is_done`
+
+## Detail Roster
+
+### `roster_detail.pilot`
+
+Array pilot. Setiap item dapat berisi:
+
+1. `id` - UUID crew
+2. `crew_type` - biasanya `main` atau `additional`
+3. `flight_instructor` - boolean
+4. `line_checker` - boolean
+5. `supervisor` - boolean
+6. `examiner` - boolean
+7. `co_pilot` - boolean
+8. `shift_date` - opsional
+9. `shift_time` - opsional
+
+### `roster_detail.doctor`
+
+Array crew doctor.
+
+Setiap item:
+
+1. `id` - UUID crew
+2. `shift_date` - opsional
+3. `shift_time` - opsional
+
+### `roster_detail.rescuer`
+
+Array crew rescuer.
+
+Setiap item:
+
+1. `id` - UUID crew
+2. `shift_date` - opsional
+3. `shift_time` - opsional
+
+### `roster_detail.helper`
+
+Array crew helper.
+
+Setiap item:
+
+1. `id` - UUID crew
+2. `shift_date` - opsional
+3. `shift_time` - opsional
+
+### `roster_detail.other_person`
+
+Array orang tambahan yang bukan crew terdaftar.
+
+Setiap item:
+
+1. `name`
+2. `mobile_phone`
+3. `email`
+
+## Field Optional Yang Perlu Diperhatikan Frontend
+
+Ini yang paling penting supaya frontend tidak bingung:
+
+### Optional level 1
+
+1. `notes`
+
+### Optional level 2 di `inspection.before`
+
+1. Semua checkbox `*_checked`
+2. `fuel_amount`
+3. `fuel_unit`
+4. `fuel_added_amount`
+5. `note`
+6. `file_checklist`
+
+### Optional level 2 di `inspection.prepare`
+
+1. `notam_briefing`
+2. `weather_briefing`
+3. `operational_flight_plan`
+4. `file_checklist`
+
+### Optional level 2 di roster detail
+
+1. `shift_date`
+2. `shift_time`
+
+### Field yang tetap harus dianggap wajib oleh frontend
+
+Walaupun beberapa field di struct tidak pakai `validate:"required"`, frontend sebaiknya tetap menyiapkan:
+
+1. `base_id`
+2. `duty_date`
+3. `roster_detail`
+4. `helicopter_id`
+5. `inspection`
+6. `inspection.inspection_date`
+
+Alasannya:
+
+1. backend memakai data itu untuk membangun transaksi
+2. frontend akan lebih stabil jika payload selalu lengkap
+3. respons error dari backend akan lebih mudah dihindari
+
+## Contoh Request Minimal Yang Aman
+
+Kalau ingin payload ringkas tetapi masih aman, gunakan pola berikut:
+
+```json
+{
+  "data": {
+    "type": "takeover",
+    "attributes": {
+      "base_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
+      "duty_date": "2026-04-15",
+      "shift_time": {
+        "shift_start": "06:00",
+        "shift_end": "18:00"
+      },
+      "roster_detail": {
+        "pilot": [],
+        "doctor": [],
+        "rescuer": [],
+        "helper": [],
+        "other_person": []
+      },
+      "helicopter_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
+      "inspection": {
+        "inspection_date": "2026-04-15",
+        "before": {},
+        "prepare": {}
+      }
+    }
+  }
+}
+```
+
+Catatan:
+
+1. Ini minimal secara struktur.
+2. Secara bisnis, frontend biasanya tetap perlu mengisi roster dan checklist sesuai kebutuhan operasional.
+
+## Response Sukses
+
+HTTP status:
+
+`201 Created`
+
+Contoh bentuk response:
+
+```json
+{
+  "data": {
+    "type": "takeover",
+    "attributes": {
+      "takeover_ac_id": "019d8000-aaaa-7bbb-8ccc-333333333333",
+      "duty_roster_id": "019d8000-bbbb-7ccc-8ddd-444444444444",
+      "flight_id": "019d8000-cccc-7ddd-8eee-555555555555",
+      "reserve_ac_id": "019d8000-dddd-7eee-8fff-666666666666",
+      "flight_inspection_id": "019d8000-eeee-7fff-9000-777777777777",
+      "shift_start": "06:00",
+      "shift_end": "18:00",
+      "base_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
+      "duty_date": "2026-04-15",
+      "helicopter_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
+      "notes": "Opsional catatan takeover",
+      "roster_detail": {
+        "pilot": [],
+        "doctor": [],
+        "rescuer": [],
+        "helper": [],
+        "other_person": []
+      },
+      "inspection": {},
+      "flight": {},
+      "duty_roster": {}
+    }
+  }
+}
+```
+
+## Error Yang Umum
+
+### 400 Bad Request
+
+Biasanya terjadi karena:
+
+1. JSON tidak valid
+2. create gagal di service
+3. UUID tidak bisa diproses
+4. data referensi tidak ditemukan
+
+### 422 Unprocessable Entity
+
+Biasanya terjadi karena:
+
+1. `type` salah
+2. field wajib tidak ada
+3. format UUID salah
+4. tanggal bukan format `YYYY-MM-DD`
+5. `fuel_unit` tidak valid
+6. roster detail tidak valid
+
+## Saran Implementasi Frontend
+
+1. Selalu kirim payload lengkap dari form state.
+2. Jangan kirim field boolean sebagai string.
+3. Pastikan UUID sudah tervalidasi sebelum submit.
+4. Validasi tanggal di frontend dengan format `YYYY-MM-DD`.
+5. Jika user tidak isi field opsional, lebih baik field itu diomit daripada dikirim string kosong.
+6. Setelah request sukses, gunakan response backend untuk refresh state halaman.
+
+## Catatan Penting
+
+1. `takeover` ini bersifat atomic.
+2. Jika satu bagian gagal, semua data batal dibuat.
+3. `notes` adalah satu-satunya field tingkat atas yang jelas opsional.
+4. Banyak field di nested object yang secara schema terlihat opsional, tetapi secara flow bisnis tetap perlu diisi agar hasilnya masuk akal.
diff --git a/go.mod b/go.mod
new file mode 100644
index 0000000..370e3d6
--- /dev/null
+++ b/go.mod
@@ -0,0 +1,104 @@
+module wucher
+
+go 1.26.0
+
+toolchain go1.26.2
+
+require (
+	github.com/aws/aws-sdk-go-v2 v1.41.4
+	github.com/aws/aws-sdk-go-v2/config v1.32.12
+	github.com/aws/aws-sdk-go-v2/credentials v1.19.12
+	github.com/aws/aws-sdk-go-v2/service/s3 v1.72.0
+	github.com/aws/aws-sdk-go-v2/service/sesv2 v1.60.1
+	github.com/aws/aws-sdk-go-v2/service/sqs v1.42.24
+	github.com/aws/smithy-go v1.24.2
+	github.com/go-playground/validator/v10 v10.20.0
+	github.com/go-sql-driver/mysql v1.8.1
+	github.com/go-webauthn/webauthn v0.13.4
+	github.com/gofiber/fiber/v2 v2.52.12
+	github.com/gofiber/swagger v1.1.0
+	github.com/golang-jwt/jwt/v5 v5.3.1
+	github.com/mattn/go-sqlite3 v1.14.22
+	github.com/pquerna/otp v1.5.0
+	github.com/prometheus/client_golang v1.21.1
+	github.com/prometheus/client_model v0.6.1
+	github.com/sony/gobreaker/v2 v2.4.0
+	github.com/swaggo/swag v1.16.3
+	github.com/valyala/fasthttp v1.51.0
+	golang.org/x/crypto v0.49.0
+	golang.org/x/image v0.39.0
+	gorm.io/driver/mysql v1.6.0
+	gorm.io/driver/sqlite v1.6.0
+	gorm.io/gorm v1.31.1
+)
+
+require (
+	filippo.io/edwards25519 v1.1.1 // indirect
+	github.com/KyleBanks/depth v1.2.1 // indirect
+	github.com/PuerkitoBio/purell v1.1.1 // indirect
+	github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect
+	github.com/andybalholm/brotli v1.1.0 // indirect
+	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.6.7 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.20 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.20 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.20 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.21 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.4.7 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.20 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.18.7 // indirect
+	github.com/aws/aws-sdk-go-v2/service/signin v1.0.8 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.30.13 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.17 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.41.9 // indirect
+	github.com/beevik/etree v1.5.0 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/crewjam/saml v0.5.1 // indirect
+	github.com/fxamacker/cbor/v2 v2.9.0 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.3 // indirect
+	github.com/go-openapi/jsonpointer v0.19.5 // indirect
+	github.com/go-openapi/jsonreference v0.19.6 // indirect
+	github.com/go-openapi/spec v0.20.4 // indirect
+	github.com/go-openapi/swag v0.19.15 // indirect
+	github.com/go-playground/locales v0.14.1 // indirect
+	github.com/go-playground/universal-translator v0.18.1 // indirect
+	github.com/go-webauthn/x v0.1.23 // indirect
+	github.com/gofiber/adaptor/v2 v2.2.1 // indirect
+	github.com/golang-jwt/jwt/v4 v4.5.2 // indirect
+	github.com/google/go-tpm v0.9.5 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/jonboulle/clockwork v0.2.2 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/klauspost/compress v1.17.11 // indirect
+	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/mailru/easyjson v0.7.6 // indirect
+	github.com/mattermost/xml-roundtrip-validator v0.1.0 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-runewidth v0.0.16 // indirect
+	github.com/mitchellh/mapstructure v1.5.0 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/philhofer/fwd v1.1.3-0.20240916144458-20a13a1f6b7c // indirect
+	github.com/prometheus/common v0.62.0 // indirect
+	github.com/prometheus/procfs v0.15.1 // indirect
+	github.com/redis/go-redis/v9 v9.19.0 // indirect
+	github.com/rivo/uniseg v0.2.0 // indirect
+	github.com/russellhaering/goxmldsig v1.4.0 // indirect
+	github.com/swaggo/files/v2 v2.0.0 // indirect
+	github.com/tinylib/msgp v1.2.5 // indirect
+	github.com/valyala/bytebufferpool v1.0.0 // indirect
+	github.com/valyala/tcplisten v1.0.0 // indirect
+	github.com/x448/float16 v0.8.4 // indirect
+	go.uber.org/atomic v1.11.0 // indirect
+	golang.org/x/net v0.52.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
+	golang.org/x/text v0.36.0 // indirect
+	golang.org/x/tools v0.43.0 // indirect
+	google.golang.org/protobuf v1.36.1 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+)
diff --git a/go.sum b/go.sum
new file mode 100644
index 0000000..b500a41
--- /dev/null
+++ b/go.sum
@@ -0,0 +1,249 @@
+filippo.io/edwards25519 v1.1.1 h1:YpjwWWlNmGIDyXOn8zLzqiD+9TyIlPhGFG96P39uBpw=
+filippo.io/edwards25519 v1.1.1/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+github.com/KyleBanks/depth v1.2.1 h1:5h8fQADFrWtarTdtDudMmGsC7GPbOAu6RVB3ffsVFHc=
+github.com/KyleBanks/depth v1.2.1/go.mod h1:jzSb9d0L43HxTQfT+oSA1EEp2q+ne2uh6XgeJcm8brE=
+github.com/PuerkitoBio/purell v1.1.1 h1:WEQqlqaGbrPkxLJWfBwQmfEAE1Z7ONdDLqrN38tNFfI=
+github.com/PuerkitoBio/purell v1.1.1/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbtSwDGJws/X0=
+github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 h1:d+Bc7a5rLufV/sSk/8dngufqelfh6jnri85riMAaF/M=
+github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578/go.mod h1:uGdkoq3SwY9Y+13GIhn11/XLaGBb4BfwItxLd5jeuXE=
+github.com/andybalholm/brotli v1.1.0 h1:eLKJA0d02Lf0mVpIDgYnqXcUn0GqVmEFny3VuID1U3M=
+github.com/andybalholm/brotli v1.1.0/go.mod h1:sms7XGricyQI9K10gOSf56VKKWS4oLer58Q+mhRPtnY=
+github.com/aws/aws-sdk-go-v2 v1.41.4 h1:10f50G7WyU02T56ox1wWXq+zTX9I1zxG46HYuG1hH/k=
+github.com/aws/aws-sdk-go-v2 v1.41.4/go.mod h1:mwsPRE8ceUUpiTgF7QmQIJ7lgsKUPQOUl3o72QBrE1o=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.6.7 h1:lL7IfaFzngfx0ZwUGOZdsFFnQ5uLvR0hWqqhyE7Q9M8=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.6.7/go.mod h1:QraP0UcVlQJsmHfioCrveWOC1nbiWUl3ej08h4mXWoc=
+github.com/aws/aws-sdk-go-v2/config v1.32.12 h1:O3csC7HUGn2895eNrLytOJQdoL2xyJy0iYXhoZ1OmP0=
+github.com/aws/aws-sdk-go-v2/config v1.32.12/go.mod h1:96zTvoOFR4FURjI+/5wY1vc1ABceROO4lWgWJuxgy0g=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.12 h1:oqtA6v+y5fZg//tcTWahyN9PEn5eDU/Wpvc2+kJ4aY8=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.12/go.mod h1:U3R1RtSHx6NB0DvEQFGyf/0sbrpJrluENHdPy1j/3TE=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.20 h1:zOgq3uezl5nznfoK3ODuqbhVg1JzAGDUhXOsU0IDCAo=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.20/go.mod h1:z/MVwUARehy6GAg/yQ1GO2IMl0k++cu1ohP9zo887wE=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.20 h1:CNXO7mvgThFGqOFgbNAP2nol2qAWBOGfqR/7tQlvLmc=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.20/go.mod h1:oydPDJKcfMhgfcgBUZaG+toBbwy8yPWubJXBVERtI4o=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.20 h1:tN6W/hg+pkM+tf9XDkWUbDEjGLb+raoBMFsTodcoYKw=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.20/go.mod h1:YJ898MhD067hSHA6xYCx5ts/jEd8BSOLtQDL3iZsvbc=
+github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6 h1:qYQ4pzQ2Oz6WpQ8T3HvGHnZydA72MnLuFK9tJwmrbHw=
+github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6/go.mod h1:O3h0IK87yXci+kg6flUKzJnWeziQUKciKrLjcatSNcY=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.21 h1:SwGMTMLIlvDNyhMteQ6r8IJSBPlRdXX5d4idhIGbkXA=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.21/go.mod h1:UUxgWxofmOdAMuqEsSppbDtGKLfR04HGsD0HXzvhI1k=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 h1:5EniKhLZe4xzL7a+fU3C2tfUN4nWIqlLesfrjkuPFTY=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7/go.mod h1:x0nZssQ3qZSnIcePWLvcoFisRXJzcTVvYpAAdYX8+GI=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.4.7 h1:tB4tNw83KcajNAzaIMhkhVI2Nt8fAZd5A5ro113FEMY=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.4.7/go.mod h1:lvpyBGkZ3tZ9iSsUIcC2EWp+0ywa7aK3BLT+FwZi+mQ=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.20 h1:2HvVAIq+YqgGotK6EkMf+KIEqTISmTYh5zLpYyeTo1Y=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.20/go.mod h1:V4X406Y666khGa8ghKmphma/7C0DAtEQYhkq9z4vpbk=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.18.7 h1:Hi0KGbrnr57bEHWM0bJ1QcBzxLrL/k2DHvGYhb8+W1w=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.18.7/go.mod h1:wKNgWgExdjjrm4qvfbTorkvocEstaoDl4WCvGfeCy9c=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.72.0 h1:SAfh4pNx5LuTafKKWR02Y+hL3A+3TX8cTKG1OIAJaBk=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.72.0/go.mod h1:r+xl5yzMk9083rMR+sJ5TYj9Tihvf/l1oxzZXDgGj2Q=
+github.com/aws/aws-sdk-go-v2/service/sesv2 v1.60.1 h1:vcU2PQ6/w4/somGiLRh21oUR3XOo7siz7lfkVtCiRQs=
+github.com/aws/aws-sdk-go-v2/service/sesv2 v1.60.1/go.mod h1:nLnJ93FXJeFHnJZEbm473c1BFHkg/kuCk7PDpv7OnnI=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.8 h1:0GFOLzEbOyZABS3PhYfBIx2rNBACYcKty+XGkTgw1ow=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.8/go.mod h1:LXypKvk85AROkKhOG6/YEcHFPoX+prKTowKnVdcaIxE=
+github.com/aws/aws-sdk-go-v2/service/sqs v1.42.24 h1:JP2wjWGmUp8lTCZb13Dv0Eciyc1jbO8pd0HZVMHFlrc=
+github.com/aws/aws-sdk-go-v2/service/sqs v1.42.24/go.mod h1:Ql9ziDutk8ERAN9HMaYANCW3lop451ppebkxEJMLCTM=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.13 h1:kiIDLZ005EcKomYYITtfsjn7dtOwHDOFy7IbPXKek2o=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.13/go.mod h1:2h/xGEowcW/g38g06g3KpRWDlT+OTfxxI0o1KqayAB8=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.17 h1:jzKAXIlhZhJbnYwHbvUQZEB8KfgAEuG0dc08Bkda7NU=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.17/go.mod h1:Al9fFsXjv4KfbzQHGe6V4NZSZQXecFcvaIF4e70FoRA=
+github.com/aws/aws-sdk-go-v2/service/sts v1.41.9 h1:Cng+OOwCHmFljXIxpEVXAGMnBia8MSU6Ch5i9PgBkcU=
+github.com/aws/aws-sdk-go-v2/service/sts v1.41.9/go.mod h1:LrlIndBDdjA/EeXeyNBle+gyCwTlizzW5ycgWnvIxkk=
+github.com/aws/smithy-go v1.24.2 h1:FzA3bu/nt/vDvmnkg+R8Xl46gmzEDam6mZ1hzmwXFng=
+github.com/aws/smithy-go v1.24.2/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/beevik/etree v1.1.0/go.mod h1:r8Aw8JqVegEf0w2fDnATrX9VpkMcyFeM0FhwO62wh+A=
+github.com/beevik/etree v1.5.0 h1:iaQZFSDS+3kYZiGoc9uKeOkUY3nYMXOKLl6KIJxiJWs=
+github.com/beevik/etree v1.5.0/go.mod h1:gPNJNaBGVZ9AwsidazFZyygnd+0pAU38N4D+WemwKNs=
+github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
+github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc h1:biVzkmvwrH8WK8raXaxBx6fRVTlJILwEwQGL1I/ByEI=
+github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc/go.mod h1:paBWMcWSl3LHKBqUq+rly7CNSldXjb2rDl3JlRe0mD8=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/crewjam/saml v0.5.1 h1:g+mfp0CrLuLRZCK793PgJcZeg5dS/0CDwoeAX2zcwNI=
+github.com/crewjam/saml v0.5.1/go.mod h1:r0fDkmFe5URDgPrmtH0IYokva6fac3AUdstiPhyEolQ=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/fxamacker/cbor/v2 v2.9.0 h1:NpKPmjDBgUfBms6tr6JZkTHtfFGcMKsw3eGcmD/sapM=
+github.com/fxamacker/cbor/v2 v2.9.0/go.mod h1:vM4b+DJCtHn+zz7h3FFp/hDAI9WNWCsZj23V5ytsSxQ=
+github.com/gabriel-vasile/mimetype v1.4.3 h1:in2uUcidCuFcDKtdcBxlR0rJ1+fsokWf+uqxgUFjbI0=
+github.com/gabriel-vasile/mimetype v1.4.3/go.mod h1:d8uq/6HKRL6CGdk+aubisF/M5GcPfT7nKyLpA0lbSSk=
+github.com/go-openapi/jsonpointer v0.19.3/go.mod h1:Pl9vOtqEWErmShwVjC8pYs9cog34VGT37dQOVbmoatg=
+github.com/go-openapi/jsonpointer v0.19.5 h1:gZr+CIYByUqjcgeLXnQu2gHYQC9o73G2XUeOFYEICuY=
+github.com/go-openapi/jsonpointer v0.19.5/go.mod h1:Pl9vOtqEWErmShwVjC8pYs9cog34VGT37dQOVbmoatg=
+github.com/go-openapi/jsonreference v0.19.6 h1:UBIxjkht+AWIgYzCDSv2GN+E/togfwXUJFRTWhl2Jjs=
+github.com/go-openapi/jsonreference v0.19.6/go.mod h1:diGHMEHg2IqXZGKxqyvWdfWU/aim5Dprw5bqpKkTvns=
+github.com/go-openapi/spec v0.20.4 h1:O8hJrt0UMnhHcluhIdUgCLRWyM2x7QkBXRvOs7m+O1M=
+github.com/go-openapi/spec v0.20.4/go.mod h1:faYFR1CvsJZ0mNsmsphTMSoRrNV3TEDoAM7FOEWeq8I=
+github.com/go-openapi/swag v0.19.5/go.mod h1:POnQmlKehdgb5mhVOsnJFsivZCEZ/vjK9gh66Z9tfKk=
+github.com/go-openapi/swag v0.19.15 h1:D2NRCBzS9/pEY3gP9Nl8aDqGUcPFrwG2p+CNFrLyrCM=
+github.com/go-openapi/swag v0.19.15/go.mod h1:QYRuS/SOXUCsnplDa677K7+DxSOj6IPNl/eQntq43wQ=
+github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
+github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
+github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
+github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
+github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
+github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
+github.com/go-playground/validator/v10 v10.20.0 h1:K9ISHbSaI0lyB2eWMPJo+kOS/FBExVwjEviJTixqxL8=
+github.com/go-playground/validator/v10 v10.20.0/go.mod h1:dbuPbCMFw/DrkbEynArYaCwl3amGuJotoKCe95atGMM=
+github.com/go-sql-driver/mysql v1.8.1 h1:LedoTUt/eveggdHS9qUFC1EFSa8bU2+1pZjSRpvNJ1Y=
+github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=
+github.com/go-webauthn/webauthn v0.13.4 h1:q68qusWPcqHbg9STSxBLBHnsKaLxNO0RnVKaAqMuAuQ=
+github.com/go-webauthn/webauthn v0.13.4/go.mod h1:MglN6OH9ECxvhDqoq1wMoF6P6JRYDiQpC9nc5OomQmI=
+github.com/go-webauthn/x v0.1.23 h1:9lEO0s+g8iTyz5Vszlg/rXTGrx3CjcD0RZQ1GPZCaxI=
+github.com/go-webauthn/x v0.1.23/go.mod h1:AJd3hI7NfEp/4fI6T4CHD753u91l510lglU7/NMN6+E=
+github.com/gofiber/adaptor/v2 v2.2.1 h1:givE7iViQWlsTR4Jh7tB4iXzrlKBgiraB/yTdHs9Lv4=
+github.com/gofiber/adaptor/v2 v2.2.1/go.mod h1:AhR16dEqs25W2FY/l8gSj1b51Azg5dtPDmm+pruNOrc=
+github.com/gofiber/fiber/v2 v2.52.12 h1:0LdToKclcPOj8PktUdIKo9BUohjjwfnQl42Dhw8/WUw=
+github.com/gofiber/fiber/v2 v2.52.12/go.mod h1:YEcBbO/FB+5M1IZNBP9FO3J9281zgPAreiI1oqg8nDw=
+github.com/gofiber/swagger v1.1.0 h1:ff3rg1fB+Rp5JN/N8jfxTiZtMKe/9tB9QDc79fPiJKQ=
+github.com/gofiber/swagger v1.1.0/go.mod h1:pRZL0Np35sd+lTODTE5The0G+TMHfNY+oC4hM2/i5m8=
+github.com/golang-jwt/jwt/v4 v4.5.2 h1:YtQM7lnr8iZ+j5q71MGKkNw9Mn7AjHM68uc9g5fXeUI=
+github.com/golang-jwt/jwt/v4 v4.5.2/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0=
+github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
+github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-tpm v0.9.5 h1:ocUmnDebX54dnW+MQWGQRbdaAcJELsa6PqZhJ48KwVU=
+github.com/google/go-tpm v0.9.5/go.mod h1:h9jEsEECg7gtLis0upRBQU+GhYVH6jMjrFxI8u6bVUY=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
+github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
+github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
+github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
+github.com/jonboulle/clockwork v0.2.2 h1:UOGuzwb1PwsrDAObMuhUnj0p5ULPj8V/xJ7Kx9qUBdQ=
+github.com/jonboulle/clockwork v0.2.2/go.mod h1:Pkfl5aHPm1nk2H9h0bjmnJD/BcgbGXUBGnn1kMkgxc8=
+github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
+github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
+github.com/klauspost/compress v1.17.11 h1:In6xLpyWOi1+C7tXUUWv2ot1QvBjxevKAaI6IXrJmUc=
+github.com/klauspost/compress v1.17.11/go.mod h1:pMDklpSncoRMuLFrf1W9Ss9KT+0rH90U12bZKk7uwG0=
+github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
+github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
+github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/mailru/easyjson v0.0.0-20190614124828-94de47d64c63/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc=
+github.com/mailru/easyjson v0.0.0-20190626092158-b2ccc519800e/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc=
+github.com/mailru/easyjson v0.7.6 h1:8yTIVnZgCoiM1TgqoeTl+LfU5Jg6/xL3QhGQnimLYnA=
+github.com/mailru/easyjson v0.7.6/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
+github.com/mattermost/xml-roundtrip-validator v0.1.0 h1:RXbVD2UAl7A7nOTR4u7E3ILa4IbtvKBHw64LDsmu9hU=
+github.com/mattermost/xml-roundtrip-validator v0.1.0/go.mod h1:qccnGMcpgwcNaBnxqpJpWWUiPNr5H3O8eDgGV9gT5To=
+github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-runewidth v0.0.16 h1:E5ScNMtiwvlvB5paMFdw9p4kSQzbXFikJ5SQO6TULQc=
+github.com/mattn/go-runewidth v0.0.16/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
+github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU=
+github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
+github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
+github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
+github.com/philhofer/fwd v1.1.3-0.20240916144458-20a13a1f6b7c h1:dAMKvw0MlJT1GshSTtih8C2gDs04w8dReiOGXrGLNoY=
+github.com/philhofer/fwd v1.1.3-0.20240916144458-20a13a1f6b7c/go.mod h1:RqIHx9QI14HlwKwm98g9Re5prTQ6LdeRQn+gXJFxsJM=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/pquerna/otp v1.5.0 h1:NMMR+WrmaqXU4EzdGJEE1aUUI0AMRzsp96fFFWNPwxs=
+github.com/pquerna/otp v1.5.0/go.mod h1:dkJfzwRKNiegxyNb54X/3fLwhCynbMspSyWKnvi1AEg=
+github.com/prometheus/client_golang v1.21.1 h1:DOvXXTqVzvkIewV/CDPFdejpMCGeMcbGCQ8YOmu+Ibk=
+github.com/prometheus/client_golang v1.21.1/go.mod h1:U9NM32ykUErtVBxdvD3zfi+EuFkkaBvMb09mIfe0Zgg=
+github.com/prometheus/client_model v0.6.1 h1:ZKSh/rekM+n3CeS952MLRAdFwIKqeY8b62p8ais2e9E=
+github.com/prometheus/client_model v0.6.1/go.mod h1:OrxVMOVHjw3lKMa8+x6HeMGkHMQyHDk9E3jmP2AmGiY=
+github.com/prometheus/common v0.62.0 h1:xasJaQlnWAeyHdUBeGjXmutelfJHWMRr+Fg4QszZ2Io=
+github.com/prometheus/common v0.62.0/go.mod h1:vyBcEuLSvWos9B1+CyL7JZ2up+uFzXhkqml0W5zIY1I=
+github.com/prometheus/procfs v0.15.1 h1:YagwOFzUgYfKKHX6Dr+sHT7km/hxC76UB0learggepc=
+github.com/prometheus/procfs v0.15.1/go.mod h1:fB45yRUv8NstnjriLhBQLuOUt+WW4BsoGhij/e3PBqk=
+github.com/redis/go-redis/v9 v9.19.0 h1:XPVaaPSnG6RhYf7p+rmSa9zZfeVAnWsH5h3lxthOm/k=
+github.com/redis/go-redis/v9 v9.19.0/go.mod h1:v/M13XI1PVCDcm01VtPFOADfZtHf8YW3baQf57KlIkA=
+github.com/rivo/uniseg v0.2.0 h1:S1pD9weZBuJdFmowNwbpi7BJ8TNftyUImj/0WQi72jY=
+github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
+github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTEfhy4qGm1nDQc=
+github.com/rogpeppe/go-internal v1.8.0/go.mod h1:WmiCO8CzOY8rg0OYDC4/i/2WRWAB6poM+XZ2dLUbcbE=
+github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
+github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
+github.com/russellhaering/goxmldsig v1.4.0 h1:8UcDh/xGyQiyrW+Fq5t8f+l2DLB1+zlhYzkPUJ7Qhys=
+github.com/russellhaering/goxmldsig v1.4.0/go.mod h1:gM4MDENBQf7M+V824SGfyIUVFWydB7n0KkEubVJl+Tw=
+github.com/sony/gobreaker/v2 v2.4.0 h1:g2KJRW1Ubty3+ZOcSEUN7K+REQJdN6yo6XvaML+jptg=
+github.com/sony/gobreaker/v2 v2.4.0/go.mod h1:pTyFJgcZ3h2tdQVLZZruK2C0eoFL1fb/G83wK1ZQl+s=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/swaggo/files/v2 v2.0.0 h1:hmAt8Dkynw7Ssz46F6pn8ok6YmGZqHSVLZ+HQM7i0kw=
+github.com/swaggo/files/v2 v2.0.0/go.mod h1:24kk2Y9NYEJ5lHuCra6iVwkMjIekMCaFq/0JQj66kyM=
+github.com/swaggo/swag v1.16.3 h1:PnCYjPCah8FK4I26l2F/KQ4yz3sILcVUN3cTlBFA9Pg=
+github.com/swaggo/swag v1.16.3/go.mod h1:DImHIuOFXKpMFAQjcC7FG4m3Dg4+QuUgUzJmKjI/gRk=
+github.com/tinylib/msgp v1.2.5 h1:WeQg1whrXRFiZusidTQqzETkRpGjFjcIhW6uqWH09po=
+github.com/tinylib/msgp v1.2.5/go.mod h1:ykjzy2wzgrlvpDCRc4LA8UXy6D8bzMSuAF3WD57Gok0=
+github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
+github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
+github.com/valyala/fasthttp v1.51.0 h1:8b30A5JlZ6C7AS81RsWjYMQmrZG6feChmgAolCl1SqA=
+github.com/valyala/fasthttp v1.51.0/go.mod h1:oI2XroL+lI7vdXyYoQk03bXBThfFl2cVdIA3Xl7cH8g=
+github.com/valyala/tcplisten v1.0.0 h1:rBHj/Xf+E1tRGZyWIWwJDiRY0zc1Js+CV5DqwacVSA8=
+github.com/valyala/tcplisten v1.0.0/go.mod h1:T0xQ8SeCZGxckz9qRXTfG43PvQ/mcWh7FwZEA7Ioqkc=
+github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
+github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
+go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
+go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
+golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
+golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
+golang.org/x/image v0.39.0 h1:skVYidAEVKgn8lZ602XO75asgXBgLj9G/FE3RbuPFww=
+golang.org/x/image v0.39.0/go.mod h1:sIbmppfU+xFLPIG0FoVUTvyBMmgng1/XAMhQ2ft0hpA=
+golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
+golang.org/x/mod v0.34.0/go.mod h1:ykgH52iCZe79kzLLMhyCUzhMci+nQj+0XkbXpNYtVjY=
+golang.org/x/net v0.0.0-20210421230115-4e50805a0758/go.mod h1:72T/g9IO56b78aLF+1Kcs5dz7/ng1VjMUvfKvpfy+jM=
+golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
+golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210420072515-93ed5bcd2bfe/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
+golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
+golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
+golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
+google.golang.org/protobuf v1.36.1 h1:yBPeRvTftaleIgM3PZ/WBIZ7XM/eEYAaEyCwvyjq/gk=
+google.golang.org/protobuf v1.36.1/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gorm.io/driver/mysql v1.6.0 h1:eNbLmNTpPpTOVZi8MMxCi2aaIm0ZpInbORNXDwyLGvg=
+gorm.io/driver/mysql v1.6.0/go.mod h1:D/oCC2GWK3M/dqoLxnOlaNKmXz8WNTfcS9y5ovaSqKo=
+gorm.io/driver/sqlite v1.6.0 h1:WHRRrIiulaPiPFmDcod6prc4l2VGVWHz80KspNsxSfQ=
+gorm.io/driver/sqlite v1.6.0/go.mod h1:AO9V1qIQddBESngQUKWL9yoH93HIeA1X6V633rBwyT8=
+gorm.io/gorm v1.31.1 h1:7CA8FTFz/gRfgqgpeKIBcervUn3xSyPUmr6B2WXJ7kg=
+gorm.io/gorm v1.31.1/go.mod h1:XyQVbO2k6YkOis7C2437jSit3SsDK72s7n7rsSHd+Gs=
diff --git a/internal/app/api/audit_middleware.go b/internal/app/api/audit_middleware.go
new file mode 100644
index 0000000..2a45a05
--- /dev/null
+++ b/internal/app/api/audit_middleware.go
@@ -0,0 +1,219 @@
+package api
+
+import (
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	sharedconst "wucher/internal/shared/const"
+)
+
+func AuditMiddleware(auditSvc *service.AuditLogService) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		if auditSvc == nil {
+			return c.Next()
+		}
+		start := time.Now()
+		err := c.Next()
+		status := c.Response().StatusCode()
+		if status == 0 {
+			status = fiber.StatusOK
+		}
+
+		requestID := c.GetRespHeader(fiber.HeaderXRequestID)
+		if requestID == "" {
+			requestID = localString(c.Locals("requestid"))
+		}
+
+		meta := map[string]any{
+			"latency_ms": time.Since(start).Milliseconds(),
+		}
+		if err != nil {
+			meta["error"] = err.Error()
+		}
+
+		module, action := resolveAuditModuleAction(c)
+		if !shouldPersistAuditByMethod(c.Method()) {
+			return err
+		}
+
+		auditSvc.Log(c.UserContext(), service.AuditLogInput{
+			RequestID:   requestID,
+			ActorUserID: localUserID(c.Locals("user_id")),
+			Layer:       "api",
+			Module:      module,
+			Action:      action,
+			Method:      c.Method(),
+			Path:        c.Path(),
+			StatusCode:  status,
+			Success:     status >= 200 && status < 400 && err == nil,
+			IP:          c.IP(),
+			UserAgent:   c.Get(fiber.HeaderUserAgent),
+			Message:     "HTTP " + strconv.Itoa(status),
+			Metadata:    meta,
+		})
+
+		return err
+	}
+}
+
+func shouldPersistAuditByMethod(method string) bool {
+	switch strings.ToUpper(strings.TrimSpace(method)) {
+	case fiber.MethodPost, fiber.MethodPut, fiber.MethodPatch, fiber.MethodDelete:
+		return true
+	default:
+		return false
+	}
+}
+
+func resolveAuditModuleAction(c *fiber.Ctx) (string, string) {
+	method := c.Method()
+	path := c.Path()
+	normalized := strings.ToLower(strings.TrimSpace(path))
+	parts := strings.Split(strings.Trim(normalized, "/"), "/")
+	if len(parts) < 3 || parts[0] != "api" || parts[1] != "v1" {
+		return sharedconst.AuditModuleUnknown, actionFromMethod(method)
+	}
+	moduleSegment := strings.TrimSpace(parts[2])
+	module := moduleFromPathSegment(moduleSegment)
+	if moduleSegment == "bases" {
+		module = resolveBaseModuleVariant(c, module)
+	}
+	suffix := ""
+	if len(parts) > 3 {
+		suffix = strings.TrimSpace(parts[len(parts)-1])
+	}
+	switch suffix {
+	case "get-all", "dt":
+		return module, sharedconst.AuditActionList
+	case "get":
+		return module, sharedconst.AuditActionGet
+	case "create":
+		return module, sharedconst.AuditActionCreate
+	case "update":
+		return module, sharedconst.AuditActionUpdate
+	case "delete":
+		return module, sharedconst.AuditActionDelete
+	case "export":
+		return module, sharedconst.AuditActionExport
+	}
+	return module, actionFromMethod(method)
+}
+
+func resolveBaseModuleVariant(c *fiber.Ctx, fallback string) string {
+	raw := strings.TrimSpace(c.Query("category_type"))
+	if raw == "" {
+		raw = strings.TrimSpace(c.Query("base_category"))
+	}
+	if raw == "" {
+		raw = strings.TrimSpace(c.Query("category"))
+	}
+	switch strings.ToLower(raw) {
+	case "regular":
+		return sharedconst.AuditModuleBaseRegular
+	case "hems":
+		return sharedconst.AuditModuleBaseHEMS
+	default:
+		return fallback
+	}
+}
+
+func actionFromMethod(method string) string {
+	switch strings.ToUpper(strings.TrimSpace(method)) {
+	case fiber.MethodGet:
+		return sharedconst.AuditActionGet
+	case fiber.MethodPost:
+		return sharedconst.AuditActionCreate
+	case fiber.MethodPut, fiber.MethodPatch:
+		return sharedconst.AuditActionUpdate
+	case fiber.MethodDelete:
+		return sharedconst.AuditActionDelete
+	default:
+		return sharedconst.AuditActionCustom
+	}
+}
+
+func moduleFromPathSegment(segment string) string {
+	switch strings.ToLower(strings.TrimSpace(segment)) {
+	case "air-rescuer-checklist":
+		return sharedconst.AuditModuleAirRescuerChecklist
+	case "audit-logs":
+		return sharedconst.AuditModuleAuditLog
+	case "auth":
+		return sharedconst.AuditModuleAuth
+	case "bases":
+		return sharedconst.AuditModuleBase
+	case "branding", "public":
+		return sharedconst.AuditModuleBranding
+	case "contacts":
+		return sharedconst.AuditModuleContact
+	case "duty-roster":
+		return sharedconst.AuditModuleDutyRoster
+	case "dul":
+		return sharedconst.AuditModuleDUL
+	case "facilities":
+		return sharedconst.AuditModuleFacility
+	case "federal-state":
+		return sharedconst.AuditModuleFederalState
+	case "file-manager":
+		return sharedconst.AuditModuleFileManager
+	case "flight-data":
+		return sharedconst.AuditModuleFlightData
+	case "flights":
+		return sharedconst.AuditModuleFlight
+	case "forces-present":
+		return sharedconst.AuditModuleForcesPresent
+	case "health-insurance-companies":
+		return sharedconst.AuditModuleHealthInsuranceCompany
+	case "helicopter-files":
+		return sharedconst.AuditModuleHelicopterFile
+	case "helicopters":
+		return sharedconst.AuditModuleHelicopter
+	case "hems-operation", "hems-operation-category", "hems-operational-data":
+		return sharedconst.AuditModuleUnknown
+	case "hospital":
+		return sharedconst.AuditModuleHospital
+	case "icao":
+		return sharedconst.AuditModuleICAO
+	case "insurance-patient-data":
+		return sharedconst.AuditModuleInsurancePatientData
+	case "land":
+		return sharedconst.AuditModuleLand
+	case "master-settings":
+		return sharedconst.AuditModuleMasterSetting
+	case "medicine":
+		return sharedconst.AuditModuleMedicine
+	case "mission":
+		return sharedconst.AuditModuleMission
+	case "opc":
+		return sharedconst.AuditModuleOPC
+	case "patient-data":
+		return sharedconst.AuditModulePatientData
+	case "reserve-acs":
+		return sharedconst.AuditModuleReserveAC
+	case "roles":
+		return sharedconst.AuditModuleRole
+	case "users":
+		return sharedconst.AuditModuleUser
+	case "vocation":
+		return sharedconst.AuditModuleVocation
+	default:
+		return sharedconst.AuditModuleUnknown
+	}
+}
+
+func localString(v any) string {
+	s, _ := v.(string)
+	return s
+}
+
+func localUserID(v any) []byte {
+	id, _ := v.([]byte)
+	if len(id) != 16 {
+		return nil
+	}
+	return id
+}
diff --git a/internal/app/api/audit_middleware_test.go b/internal/app/api/audit_middleware_test.go
new file mode 100644
index 0000000..a94a230
--- /dev/null
+++ b/internal/app/api/audit_middleware_test.go
@@ -0,0 +1,208 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/audit"
+	"wucher/internal/service"
+	sharedconst "wucher/internal/shared/const"
+)
+
+type mockAuditMiddlewareRepo struct {
+	mu      sync.Mutex
+	entries []*audit.AuditLog
+}
+
+func (m *mockAuditMiddlewareRepo) Create(_ context.Context, entry *audit.AuditLog) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	cp := *entry
+	m.entries = append(m.entries, &cp)
+	return nil
+}
+
+func TestAuditMiddleware_SkipsGETRequests(t *testing.T) {
+	repo := &mockAuditMiddlewareRepo{}
+	auditSvc := service.NewAuditLogService(repo, service.AuditLogServiceDependencies{QueueSize: 16, Workers: 1})
+
+	app := fiber.New()
+	app.Use(AuditMiddleware(auditSvc))
+	app.Get("/api/v1/ping", func(c *fiber.Ctx) error {
+		return c.SendStatus(http.StatusCreated)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/ping", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201, got %d", resp.StatusCode)
+	}
+
+	deadline := time.Now().Add(500 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		repo.mu.Lock()
+		n := len(repo.entries)
+		repo.mu.Unlock()
+		if n > 0 {
+			break
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	repo.mu.Lock()
+	defer repo.mu.Unlock()
+	if len(repo.entries) != 0 {
+		t.Fatalf("expected no audit log entry for GET, got=%d", len(repo.entries))
+	}
+}
+
+func TestAuditMiddleware_LogsMutationRequests(t *testing.T) {
+	repo := &mockAuditMiddlewareRepo{}
+	auditSvc := service.NewAuditLogService(repo, service.AuditLogServiceDependencies{QueueSize: 16, Workers: 1})
+
+	app := fiber.New()
+	app.Use(AuditMiddleware(auditSvc))
+	app.Post("/api/v1/helicopters/create", func(c *fiber.Ctx) error {
+		return c.SendStatus(http.StatusCreated)
+	})
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201, got %d", resp.StatusCode)
+	}
+
+	deadline := time.Now().Add(500 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		repo.mu.Lock()
+		n := len(repo.entries)
+		repo.mu.Unlock()
+		if n > 0 {
+			break
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	repo.mu.Lock()
+	defer repo.mu.Unlock()
+	if len(repo.entries) == 0 {
+		t.Fatalf("expected audit log entry for mutation request")
+	}
+	got := repo.entries[0]
+	if got.Layer != "api" || got.Module != sharedconst.AuditModuleHelicopter || got.Action != sharedconst.AuditActionCreate {
+		t.Fatalf("unexpected audit entry: layer=%s module=%s action=%s", got.Layer, got.Module, got.Action)
+	}
+	if got.StatusCode != http.StatusCreated {
+		t.Fatalf("expected status 201, got %d", got.StatusCode)
+	}
+}
+
+func TestModuleFromPathSegment(t *testing.T) {
+	cases := []struct {
+		segment string
+		want    string
+	}{
+		{segment: "helicopters", want: sharedconst.AuditModuleHelicopter},
+		{segment: "bases", want: sharedconst.AuditModuleBase},
+		{segment: "health-insurance-companies", want: sharedconst.AuditModuleHealthInsuranceCompany},
+		{segment: "hems-roster", want: sharedconst.AuditModuleUnknown},
+		{segment: "dul", want: sharedconst.AuditModuleDUL},
+		{segment: "reserve-acs", want: sharedconst.AuditModuleReserveAC},
+		{segment: "not-registered", want: sharedconst.AuditModuleUnknown},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.segment, func(t *testing.T) {
+			got := moduleFromPathSegment(tc.segment)
+			if got != tc.want {
+				t.Fatalf("moduleFromPathSegment(%q) = %q, want %q", tc.segment, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestResolveAuditModuleAction(t *testing.T) {
+	cases := []struct {
+		name       string
+		method     string
+		target     string
+		wantModule string
+		wantAction string
+	}{
+		{
+			name:       "datatable list",
+			method:     http.MethodGet,
+			target:     "/api/v1/helicopters/get-all/dt",
+			wantModule: sharedconst.AuditModuleHelicopter,
+			wantAction: sharedconst.AuditActionList,
+		},
+		{
+			name:       "explicit create",
+			method:     http.MethodPost,
+			target:     "/api/v1/helicopters/create",
+			wantModule: sharedconst.AuditModuleHelicopter,
+			wantAction: sharedconst.AuditActionCreate,
+		},
+		{
+			name:       "fallback method update",
+			method:     http.MethodPatch,
+			target:     "/api/v1/helicopters/019dbeb6-4c37-7495-b0d0-e02ed134f87d",
+			wantModule: sharedconst.AuditModuleHelicopter,
+			wantAction: sharedconst.AuditActionUpdate,
+		},
+		{
+			name:       "base regular variant from query",
+			method:     http.MethodGet,
+			target:     "/api/v1/bases/get-all?category_type=regular",
+			wantModule: sharedconst.AuditModuleBaseRegular,
+			wantAction: sharedconst.AuditActionList,
+		},
+		{
+			name:       "base hems variant from query alias",
+			method:     http.MethodGet,
+			target:     "/api/v1/bases/get-all?base_category=hems",
+			wantModule: sharedconst.AuditModuleBaseHEMS,
+			wantAction: sharedconst.AuditActionList,
+		},
+		{
+			name:       "unknown module",
+			method:     http.MethodGet,
+			target:     "/api/v1/ping",
+			wantModule: sharedconst.AuditModuleUnknown,
+			wantAction: sharedconst.AuditActionGet,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			app := fiber.New()
+			app.All("/*", func(c *fiber.Ctx) error {
+				gotModule, gotAction := resolveAuditModuleAction(c)
+				if gotModule != tc.wantModule || gotAction != tc.wantAction {
+					t.Fatalf("resolveAuditModuleAction(%q, %q) = (%q, %q), want (%q, %q)",
+						tc.method, tc.target, gotModule, gotAction, tc.wantModule, tc.wantAction)
+				}
+				return c.SendStatus(http.StatusNoContent)
+			})
+			req, _ := http.NewRequest(tc.method, tc.target, nil)
+			resp, err := app.Test(req)
+			if err != nil {
+				t.Fatalf("app.Test: %v", err)
+			}
+			if resp.StatusCode != http.StatusNoContent {
+				t.Fatalf("expected 204, got %d", resp.StatusCode)
+			}
+		})
+	}
+}
diff --git a/internal/app/api/compress_wopi_test.go b/internal/app/api/compress_wopi_test.go
new file mode 100644
index 0000000..c4bae62
--- /dev/null
+++ b/internal/app/api/compress_wopi_test.go
@@ -0,0 +1,131 @@
+package api
+
+import (
+	"archive/zip"
+	"bytes"
+	"io"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gofiber/fiber/v2"
+	"github.com/gofiber/fiber/v2/middleware/compress"
+)
+
+// buildTinyXLSX returns a minimal but structurally valid .xlsx (ZIP) payload.
+func buildTinyXLSX(t *testing.T) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	zw := zip.NewWriter(&buf)
+	entries := map[string]string{
+		"[Content_Types].xml": `<?xml version="1.0"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/></Types>`,
+		"_rels/.rels":         `<?xml version="1.0"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/></Relationships>`,
+		"xl/workbook.xml":     `<?xml version="1.0"?><workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"><sheets><sheet name="Sheet1" sheetId="1" r:id="rId1"/></sheets></workbook>`,
+	}
+	for name, content := range entries {
+		w, err := zw.Create(name)
+		if err != nil {
+			t.Fatalf("zip create %s: %v", name, err)
+		}
+		if _, err := io.WriteString(w, content); err != nil {
+			t.Fatalf("zip write %s: %v", name, err)
+		}
+	}
+	if err := zw.Close(); err != nil {
+		t.Fatalf("zip close: %v", err)
+	}
+	return buf.Bytes()
+}
+
+func assertValidZip(t *testing.T, b []byte) {
+	t.Helper()
+	if _, err := zip.NewReader(bytes.NewReader(b), int64(len(b))); err != nil {
+		t.Fatalf("payload is not a valid zip: %v", err)
+	}
+}
+
+func TestIsWOPIRequest(t *testing.T) {
+	app := fiber.New()
+	cases := []struct {
+		path string
+		want bool
+	}{
+		{"/wopi/files/123/contents", true},
+		{"/wopi/files/123", true},
+		{"/api/file-manager/files", false},
+		{"/wopimirror/x", false},
+		{"/", false},
+	}
+	for _, tc := range cases {
+		app.Get(tc.path, func(c *fiber.Ctx) error {
+			if got := isWOPIRequest(c); got != tc.want {
+				t.Errorf("isWOPIRequest(%q) = %v, want %v", tc.path, got, tc.want)
+			}
+			return c.SendStatus(fiber.StatusOK)
+		})
+		resp, err := app.Test(httptest.NewRequest("GET", tc.path, nil), -1)
+		if err != nil {
+			t.Fatalf("app.Test(%q): %v", tc.path, err)
+		}
+		_ = resp.Body.Close()
+	}
+}
+
+// Regression for the "template .xlsx always corrupt via WOPI" bug: the global
+// gzip compress middleware must NOT compress WOPI file-content responses.
+// Collabora saves the response body verbatim as the document, so a gzip stream
+// there is a guaranteed-corrupt file.
+func TestCompressMiddleware_SkipsWOPIContents(t *testing.T) {
+	src := buildTinyXLSX(t)
+	assertValidZip(t, src)
+
+	app := fiber.New()
+	// Mirror the production compress wiring (UseDefaultMiddlewares).
+	app.Use(compress.New(compress.Config{
+		Level: compress.LevelBestSpeed,
+		Next: func(c *fiber.Ctx) bool {
+			return isEventStreamRequest(c) || isWOPIRequest(c)
+		},
+	}))
+
+	streamXLSX := func(c *fiber.Ctx) error {
+		c.Set(fiber.HeaderContentType, "application/octet-stream")
+		c.Status(fiber.StatusOK)
+		c.Context().Response.SetBodyStream(io.NopCloser(bytes.NewReader(src)), len(src))
+		return nil
+	}
+	app.Get("/wopi/files/:id/contents", streamXLSX)
+	// Negative control: a non-WOPI route with a compressible body must still gzip.
+	app.Get("/api/echo", func(c *fiber.Ctx) error {
+		c.Set(fiber.HeaderContentType, "application/octet-stream")
+		return c.Send(bytes.Repeat([]byte("A"), 4096))
+	})
+
+	// WOPI content download with gzip offered must come back raw + valid.
+	req := httptest.NewRequest("GET", "/wopi/files/abc/contents", nil)
+	req.Header.Set("Accept-Encoding", "gzip")
+	resp, err := app.Test(req, -1)
+	if err != nil {
+		t.Fatalf("app.Test wopi: %v", err)
+	}
+	if enc := resp.Header.Get("Content-Encoding"); enc != "" {
+		t.Fatalf("WOPI content unexpectedly encoded: Content-Encoding=%q", enc)
+	}
+	got, _ := io.ReadAll(resp.Body)
+	_ = resp.Body.Close()
+	assertValidZip(t, got)
+	if !bytes.Equal(got, src) {
+		t.Fatalf("WOPI content body mutated: got %d bytes, want %d", len(got), len(src))
+	}
+
+	// Sanity: prove compression is actually active for non-excluded routes.
+	req2 := httptest.NewRequest("GET", "/api/echo", nil)
+	req2.Header.Set("Accept-Encoding", "gzip")
+	resp2, err := app.Test(req2, -1)
+	if err != nil {
+		t.Fatalf("app.Test echo: %v", err)
+	}
+	if enc := resp2.Header.Get("Content-Encoding"); enc != "gzip" {
+		t.Fatalf("expected gzip on non-WOPI route, got Content-Encoding=%q (compress not active - test invalid)", enc)
+	}
+	_ = resp2.Body.Close()
+}
diff --git a/internal/app/api/middleware.go b/internal/app/api/middleware.go
new file mode 100644
index 0000000..dac3cdf
--- /dev/null
+++ b/internal/app/api/middleware.go
@@ -0,0 +1,471 @@
+package api
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"runtime/debug"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"github.com/gofiber/fiber/v2/middleware/compress"
+	"github.com/gofiber/fiber/v2/middleware/cors"
+	"github.com/gofiber/fiber/v2/middleware/helmet"
+	"github.com/gofiber/fiber/v2/middleware/limiter"
+	"github.com/gofiber/fiber/v2/middleware/recover"
+	"github.com/gofiber/fiber/v2/middleware/requestid"
+	"github.com/gofiber/fiber/v2/middleware/timeout"
+	"github.com/gofiber/fiber/v2/utils"
+	"github.com/prometheus/client_golang/prometheus"
+
+	"wucher/internal/config"
+	"wucher/internal/shared/pkg/apperrorsx"
+)
+
+var (
+	httpMetricsRegisterOnce = sync.Once{}
+	httpRequestsTotal       = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "http_requests_total",
+		Help: "Total number of HTTP requests.",
+	}, []string{"method", "path", "status"})
+	httpRequestDurationSeconds = prometheus.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "http_request_duration_seconds",
+		Help:    "HTTP request duration in seconds.",
+		Buckets: prometheus.DefBuckets,
+	}, []string{"method", "path", "status"})
+)
+
+// UseDefaultMiddlewares applies baseline best-practice middleware.
+func UseDefaultMiddlewares(app *fiber.App, cfg config.HTTPConfig) {
+	registerHTTPMetrics()
+
+	app.Use(recover.New(recover.Config{
+		EnableStackTrace: true,
+		StackTraceHandler: func(c *fiber.Ctx, err any) {
+			slog.Error("panic recovered", "method", c.Method(), "path", c.Path(), "error", err, "stack", string(debug.Stack()))
+		},
+	}))
+
+	app.Use(requestid.New(requestid.Config{
+		Header:     fiber.HeaderXRequestID,
+		ContextKey: "requestid",
+		Generator:  utils.UUIDv4,
+	}))
+
+	app.Use(func(c *fiber.Ctx) error {
+		// Use a request-scoped context that keeps request values but is not canceled
+		// as soon as fasthttp starts draining on server shutdown.
+		c.SetUserContext(context.WithoutCancel(c.Context()))
+		return c.Next()
+	})
+
+	app.Use(httpAccessLogMiddleware())
+
+	app.Use(compress.New(compress.Config{
+		Level: compress.LevelBestSpeed,
+		Next: func(c *fiber.Ctx) bool {
+			return isEventStreamRequest(c) || isWOPIRequest(c)
+		},
+	}))
+	app.Use(requestTimeoutMiddleware(cfg))
+	app.Use(httpMetricsMiddleware())
+
+	app.Use(helmet.New(helmet.Config{
+		XFrameOptions:      "DENY",
+		ReferrerPolicy:     "no-referrer",
+		PermissionPolicy:   "geolocation=(), microphone=(), camera=(), payment=(), usb=()",
+		HSTSMaxAge:         cfg.HSTSMaxAge,
+		HSTSPreloadEnabled: cfg.HSTSMaxAge > 0,
+	}))
+
+	app.Use(disallowUnsafeMethods())
+
+	corsAllowCredentials := cfg.CORSAllowCredentials && !containsWildcardOrigin(cfg.CORSAllowOrigins)
+	app.Use(cors.New(cors.Config{
+		AllowOrigins:     cfg.CORSAllowOrigins,
+		AllowMethods:     cfg.CORSAllowMethods,
+		AllowHeaders:     cfg.CORSAllowHeaders,
+		ExposeHeaders:    cfg.CORSExposeHeaders,
+		AllowCredentials: corsAllowCredentials,
+		MaxAge:           cfg.CORSMaxAge,
+	}))
+
+	app.Use(limiter.New(limiter.Config{
+		Max:        cfg.RateLimitMax,
+		Expiration: cfg.RateLimitWindow,
+		Next: func(c *fiber.Ctx) bool {
+			path := c.Path()
+			return c.Method() == fiber.MethodOptions ||
+				path == "/health" ||
+				strings.HasPrefix(path, "/swagger")
+		},
+		LimitReached: func(c *fiber.Ctx) error {
+			retryAfter := int(cfg.RateLimitWindow.Seconds())
+			if retryAfter < 1 {
+				retryAfter = 1
+			}
+			c.Set(fiber.HeaderRetryAfter, strconv.Itoa(retryAfter))
+			return c.Status(fiber.StatusTooManyRequests).JSON(fiber.Map{
+				"errors": []fiber.Map{{
+					"status": "429",
+					"title":  "Too Many Requests",
+					"detail": "rate limit exceeded",
+				}},
+			})
+		},
+	}))
+
+	// Per-endpoint limiter (exact method+path match), configured from env/config.
+	// Applied in addition to the global limiter above.
+	endpointKeys := make([]string, 0, len(cfg.RateLimitByEndpoint))
+	for key := range cfg.RateLimitByEndpoint {
+		endpointKeys = append(endpointKeys, key)
+	}
+	sort.Strings(endpointKeys)
+	for _, endpointKey := range endpointKeys {
+		rule := cfg.RateLimitByEndpoint[endpointKey]
+		currentEndpointKey := endpointKey
+		currentRule := rule
+
+		app.Use(limiter.New(limiter.Config{
+			Max:        currentRule.Max,
+			Expiration: currentRule.Window,
+			Next: func(c *fiber.Ctx) bool {
+				return methodPathKey(c.Method(), c.Path()) != currentEndpointKey
+			},
+			LimitReached: func(c *fiber.Ctx) error {
+				retryAfter := int(currentRule.Window.Seconds())
+				if retryAfter < 1 {
+					retryAfter = 1
+				}
+				c.Set(fiber.HeaderRetryAfter, strconv.Itoa(retryAfter))
+				return c.Status(fiber.StatusTooManyRequests).JSON(fiber.Map{
+					"errors": []fiber.Map{{
+						"status": "429",
+						"title":  "Too Many Requests",
+						"detail": fmt.Sprintf("rate limit exceeded for %s", currentEndpointKey),
+					}},
+				})
+			},
+		}))
+	}
+}
+
+func httpAccessLogMiddleware() fiber.Handler {
+	requestLogger := slog.Default()
+
+	return func(c *fiber.Ctx) error {
+		started := time.Now()
+		err := c.Next()
+
+		if c.Path() == "/health" {
+			return err
+		}
+
+		statusCode := c.Response().StatusCode()
+		level := slog.LevelInfo
+		if statusCode >= fiber.StatusInternalServerError || err != nil {
+			level = slog.LevelError
+		} else if statusCode >= fiber.StatusBadRequest {
+			level = slog.LevelWarn
+		}
+
+		requestID := strings.TrimSpace(fmt.Sprint(c.Locals("requestid")))
+		if requestID == "" || requestID == "<nil>" {
+			requestID = strings.TrimSpace(c.GetRespHeader(fiber.HeaderXRequestID))
+		}
+
+		args := []any{
+			slog.String("request_id", requestID),
+			slog.String("method", c.Method()),
+			slog.String("path", c.Path()),
+			slog.Int("status", statusCode),
+			slog.Duration("latency", time.Since(started)),
+			slog.String("ip", c.IP()),
+		}
+		if detail := strings.TrimSpace(fmt.Sprint(c.Locals(apperrorsx.ContextKeyHTTPErrorInternalDetail))); detail != "" && detail != "<nil>" {
+			args = append(args, slog.String("internal_detail", detail))
+		}
+		if detail := strings.TrimSpace(fmt.Sprint(c.Locals(apperrorsx.ContextKeyHTTPErrorDetail))); detail != "" && detail != "<nil>" {
+			args = append(args, slog.String("detail", detail))
+		}
+		if err != nil {
+			args = append(args, slog.Any("error", err))
+			args = append(args, slog.Any("error_chain", buildErrorChain(err)))
+		}
+		if statusCode >= fiber.StatusInternalServerError {
+			if body := strings.TrimSpace(string(c.Response().Body())); body != "" {
+				args = append(args, slog.String("response_body", truncateForLog(body, 1800)))
+			}
+		}
+
+		requestLogger.Log(c.UserContext(), level, "http request", args...)
+		return err
+	}
+}
+
+func buildErrorChain(err error) []string {
+	if err == nil {
+		return nil
+	}
+	chain := make([]string, 0, 8)
+	seen := map[string]struct{}{}
+	for current := err; current != nil; current = errors.Unwrap(current) {
+		msg := current.Error()
+		if msg == "" {
+			msg = fmt.Sprintf("%T", current)
+		}
+		key := fmt.Sprintf("%T:%s", current, msg)
+		if _, ok := seen[key]; ok {
+			break
+		}
+		seen[key] = struct{}{}
+		chain = append(chain, fmt.Sprintf("%T: %s", current, msg))
+	}
+	return chain
+}
+
+func truncateForLog(v string, max int) string {
+	if max <= 0 || len(v) <= max {
+		return v
+	}
+	if max <= 3 {
+		return v[:max]
+	}
+	return v[:max-3] + "..."
+}
+
+func httpMetricsMiddleware() fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		started := time.Now()
+		method := normalizeHTTPMethod(c.Method())
+		err := c.Next()
+
+		path := metricsPathLabel(c)
+		if shouldSkipHTTPMetrics(path) {
+			return err
+		}
+		status := strconv.Itoa(c.Response().StatusCode())
+
+		httpRequestsTotal.WithLabelValues(method, path, status).Inc()
+		httpRequestDurationSeconds.WithLabelValues(method, path, status).Observe(time.Since(started).Seconds())
+		return err
+	}
+}
+
+func registerHTTPMetrics() {
+	httpMetricsRegisterOnce.Do(func() {
+		registerHTTPCollector(httpRequestsTotal)
+		registerHTTPCollector(httpRequestDurationSeconds)
+	})
+}
+
+func registerHTTPCollector(collector prometheus.Collector) {
+	if err := prometheus.Register(collector); err != nil {
+		var alreadyRegistered prometheus.AlreadyRegisteredError
+		if errors.As(err, &alreadyRegistered) {
+			return
+		}
+		panic(err)
+	}
+}
+
+func shouldSkipHTTPMetrics(path string) bool {
+	return path == "/metrics" || path == "/health"
+}
+
+func metricsPathLabel(c *fiber.Ctx) string {
+	route := c.Route()
+	if route != nil {
+		if routePath := strings.TrimSpace(utils.CopyString(route.Path)); routePath != "" {
+			return routePath
+		}
+	}
+	return "unmatched"
+}
+
+func normalizeHTTPMethod(method string) string {
+	method = strings.ToUpper(strings.TrimSpace(utils.CopyString(method)))
+	if method == "" {
+		return "UNKNOWN"
+	}
+
+	switch method {
+	case fiber.MethodGet,
+		fiber.MethodHead,
+		fiber.MethodPost,
+		fiber.MethodPut,
+		fiber.MethodPatch,
+		fiber.MethodDelete,
+		fiber.MethodOptions,
+		fiber.MethodTrace,
+		fiber.MethodConnect:
+		return method
+	default:
+		return "OTHER"
+	}
+}
+
+func requestTimeoutMiddleware(cfg config.HTTPConfig) fiber.Handler {
+	defaultTimeout := cfg.RequestTimeout
+	overrides := cfg.RequestTimeoutByPath
+
+	if defaultTimeout <= 0 && len(overrides) == 0 {
+		return func(c *fiber.Ctx) error { return c.Next() }
+	}
+
+	return func(c *fiber.Ctx) error {
+		if isEventStreamRequest(c) {
+			return c.Next()
+		}
+
+		requestTimeout := defaultTimeout
+		if override, ok := timeoutForRequest(overrides, c.Method(), c.Path(), c.Route()); ok {
+			requestTimeout = override
+		}
+		if requestTimeout <= 0 {
+			return c.Next()
+		}
+		return timeout.NewWithContext(func(c *fiber.Ctx) error {
+			return c.Next()
+		}, requestTimeout)(c)
+	}
+}
+
+func isEventStreamRequest(c *fiber.Ctx) bool {
+	if c == nil {
+		return false
+	}
+	path := strings.TrimSpace(c.Path())
+	if strings.HasSuffix(path, "/file-manager/events") {
+		return true
+	}
+	accept := strings.ToLower(strings.TrimSpace(c.Get(fiber.HeaderAccept)))
+	return strings.Contains(accept, "text/event-stream")
+}
+
+// isWOPIRequest reports whether the request targets the Collabora/WOPI
+// endpoints. WOPI file-content responses carry raw office bytes (an .xlsx is a
+// ZIP container that is already compressed); gzipping them makes Collabora
+// store the compressed stream verbatim as the document, producing a file that
+// is consistently corrupt. Office/JSON WOPI payloads gain nothing from gzip, so
+// the whole group is excluded from the compress middleware.
+func isWOPIRequest(c *fiber.Ctx) bool {
+	if c == nil {
+		return false
+	}
+	return strings.HasPrefix(strings.TrimSpace(c.Path()), "/wopi/")
+}
+
+func timeoutForRequest(overrides map[string]time.Duration, method, path string, route *fiber.Route) (time.Duration, bool) {
+	if len(overrides) == 0 {
+		return 0, false
+	}
+	normalizedMethod := strings.ToUpper(strings.TrimSpace(method))
+	trimmedPath := strings.TrimSpace(path)
+
+	if route != nil {
+		registeredPath := strings.TrimSpace(route.Path)
+		if registeredPath != "" && registeredPath != "/" {
+			key := timeoutOverrideKey(normalizedMethod, registeredPath)
+			if v, ok := overrides[key]; ok {
+				return v, true
+			}
+		}
+	}
+
+	if v, ok := overrides[timeoutOverrideKey(normalizedMethod, trimmedPath)]; ok {
+		return v, true
+	}
+
+	for key, duration := range overrides {
+		parts := strings.SplitN(key, " ", 2)
+		if len(parts) != 2 {
+			continue
+		}
+		if strings.ToUpper(strings.TrimSpace(parts[0])) != normalizedMethod {
+			continue
+		}
+		if routePatternMatches(strings.TrimSpace(parts[1]), trimmedPath) {
+			return duration, true
+		}
+	}
+
+	return 0, false
+}
+
+func methodPathKey(method, path string) string {
+	return strings.ToUpper(strings.TrimSpace(method)) + " " + strings.TrimSpace(path)
+}
+
+func timeoutOverrideKey(method, path string) string {
+	return strings.ToUpper(strings.TrimSpace(method)) + " " + strings.TrimSpace(path)
+}
+
+func routePatternMatches(pattern, path string) bool {
+	if pattern == "" {
+		return false
+	}
+	if pattern == path {
+		return true
+	}
+
+	pSeg := splitPathSegments(pattern)
+	rSeg := splitPathSegments(path)
+
+	if len(pSeg) == 0 && len(rSeg) == 0 {
+		return true
+	}
+
+	i := 0
+	for ; i < len(pSeg); i++ {
+		segment := pSeg[i]
+		if segment == "*" || strings.HasPrefix(segment, "*") {
+			return true
+		}
+		if i >= len(rSeg) {
+			return false
+		}
+		if strings.HasPrefix(segment, ":") || strings.HasPrefix(segment, "+") {
+			continue
+		}
+		if segment != rSeg[i] {
+			return false
+		}
+	}
+
+	return i == len(rSeg)
+}
+
+func splitPathSegments(path string) []string {
+	trimmed := strings.TrimSpace(path)
+	trimmed = strings.TrimPrefix(trimmed, "/")
+	trimmed = strings.TrimSuffix(trimmed, "/")
+	if trimmed == "" {
+		return nil
+	}
+	return strings.Split(trimmed, "/")
+}
+
+func disallowUnsafeMethods() fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		if c.Method() == fiber.MethodTrace || c.Method() == "TRACK" {
+			return c.SendStatus(fiber.StatusMethodNotAllowed)
+		}
+		return c.Next()
+	}
+}
+
+func containsWildcardOrigin(origins string) bool {
+	for _, origin := range strings.Split(origins, ",") {
+		if strings.TrimSpace(origin) == "*" {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/app/api/middleware_test.go b/internal/app/api/middleware_test.go
new file mode 100644
index 0000000..c9397d6
--- /dev/null
+++ b/internal/app/api/middleware_test.go
@@ -0,0 +1,586 @@
+package api
+
+import (
+	"bytes"
+	"compress/gzip"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"github.com/prometheus/client_golang/prometheus"
+	dto "github.com/prometheus/client_model/go"
+
+	"wucher/internal/config"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+)
+
+func testHTTPConfig() config.HTTPConfig {
+	return config.HTTPConfig{
+		CORSAllowOrigins:     "http://localhost:3000",
+		CORSAllowMethods:     "GET,POST,PUT,PATCH,DELETE,OPTIONS",
+		CORSAllowHeaders:     "Origin,Content-Type,Accept,Authorization",
+		CORSExposeHeaders:    "X-Request-ID",
+		CORSAllowCredentials: true,
+		CORSMaxAge:           300,
+		RateLimitMax:         100,
+		RateLimitWindow:      time.Minute,
+		RequestTimeout:       0,
+		RequestTimeoutByPath: map[string]time.Duration{},
+		HSTSMaxAge:           0,
+	}
+}
+
+func TestUseDefaultMiddlewares_CORSHeaders(t *testing.T) {
+	cfg := testHTTPConfig()
+	app := fiber.New()
+	UseDefaultMiddlewares(app, cfg)
+	app.Get("/ping", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+	req, _ := http.NewRequest(http.MethodGet, "/ping", nil)
+	req.Header.Set("Origin", "http://localhost:3000")
+
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if got := resp.Header.Get("Access-Control-Allow-Origin"); got != "http://localhost:3000" {
+		t.Fatalf("expected allow-origin http://localhost:3000, got %q", got)
+	}
+	if got := resp.Header.Get("Access-Control-Allow-Credentials"); got != "true" {
+		t.Fatalf("expected allow-credentials true, got %q", got)
+	}
+	if got := resp.Header.Get("X-Frame-Options"); got != "DENY" {
+		t.Fatalf("expected X-Frame-Options DENY, got %q", got)
+	}
+	if got := resp.Header.Get("X-Request-Id"); got == "" {
+		t.Fatalf("expected request id header to be set")
+	}
+}
+
+func TestUseDefaultMiddlewares_BlockTrace(t *testing.T) {
+	cfg := testHTTPConfig()
+	app := fiber.New()
+	UseDefaultMiddlewares(app, cfg)
+	app.All("/ping", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+	req, _ := http.NewRequest(http.MethodTrace, "/ping", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusMethodNotAllowed {
+		t.Fatalf("expected 405, got %d", resp.StatusCode)
+	}
+}
+
+func TestUseDefaultMiddlewares_RateLimiter(t *testing.T) {
+	cfg := testHTTPConfig()
+	cfg.RateLimitMax = 1
+	cfg.RateLimitWindow = time.Minute
+
+	app := fiber.New()
+	UseDefaultMiddlewares(app, cfg)
+	app.Get("/limited", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+	firstReq, _ := http.NewRequest(http.MethodGet, "/limited", nil)
+	firstResp, err := app.Test(firstReq)
+	if err != nil {
+		t.Fatalf("first request app.Test: %v", err)
+	}
+	if firstResp.StatusCode != http.StatusOK {
+		t.Fatalf("expected first request 200, got %d", firstResp.StatusCode)
+	}
+
+	secondReq, _ := http.NewRequest(http.MethodGet, "/limited", nil)
+	secondResp, err := app.Test(secondReq)
+	if err != nil {
+		t.Fatalf("second request app.Test: %v", err)
+	}
+	if secondResp.StatusCode != http.StatusTooManyRequests {
+		t.Fatalf("expected second request 429, got %d", secondResp.StatusCode)
+	}
+	if got := secondResp.Header.Get("Retry-After"); got == "" {
+		t.Fatalf("expected Retry-After header on 429 response")
+	}
+}
+
+func TestUseDefaultMiddlewares_EndpointRateLimiter(t *testing.T) {
+	cfg := testHTTPConfig()
+	cfg.RateLimitMax = 100
+	cfg.RateLimitByEndpoint = map[string]config.RateLimitRule{
+		"POST /auth/login": {
+			Max:    1,
+			Window: time.Minute,
+		},
+	}
+
+	app := fiber.New()
+	UseDefaultMiddlewares(app, cfg)
+	app.Post("/auth/login", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+	app.Post("/auth/refresh", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+	req1, _ := http.NewRequest(http.MethodPost, "/auth/login", nil)
+	resp1, err := app.Test(req1)
+	if err != nil {
+		t.Fatalf("first login request app.Test: %v", err)
+	}
+	if resp1.StatusCode != http.StatusOK {
+		t.Fatalf("expected first login request 200, got %d", resp1.StatusCode)
+	}
+
+	req2, _ := http.NewRequest(http.MethodPost, "/auth/login", nil)
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("second login request app.Test: %v", err)
+	}
+	if resp2.StatusCode != http.StatusTooManyRequests {
+		t.Fatalf("expected second login request 429, got %d", resp2.StatusCode)
+	}
+
+	otherReq, _ := http.NewRequest(http.MethodPost, "/auth/refresh", nil)
+	otherResp, err := app.Test(otherReq)
+	if err != nil {
+		t.Fatalf("other endpoint request app.Test: %v", err)
+	}
+	if otherResp.StatusCode != http.StatusOK {
+		t.Fatalf("expected other endpoint request 200, got %d", otherResp.StatusCode)
+	}
+}
+
+func TestUseDefaultMiddlewares_WildcardOriginDisablesCredentials(t *testing.T) {
+	cfg := testHTTPConfig()
+	cfg.CORSAllowOrigins = "*"
+	cfg.CORSAllowCredentials = true
+
+	app := fiber.New()
+	UseDefaultMiddlewares(app, cfg)
+	app.Get("/ping", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+	req, _ := http.NewRequest(http.MethodGet, "/ping", nil)
+	req.Header.Set("Origin", "http://localhost:3000")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if got := resp.Header.Get("Access-Control-Allow-Origin"); got != "*" {
+		t.Fatalf("expected allow-origin *, got %q", got)
+	}
+	if got := resp.Header.Get("Access-Control-Allow-Credentials"); got != "" {
+		t.Fatalf("expected allow-credentials to be omitted, got %q", got)
+	}
+}
+
+func TestUseDefaultMiddlewares_RequestContextDetachedFromShutdown(t *testing.T) {
+	cfg := testHTTPConfig()
+	app := fiber.New()
+	UseDefaultMiddlewares(app, cfg)
+	app.Get("/ctx", func(c *fiber.Ctx) error {
+		if c.UserContext() == nil {
+			return c.SendStatus(http.StatusInternalServerError)
+		}
+		if c.UserContext().Done() != nil {
+			return c.SendStatus(http.StatusInternalServerError)
+		}
+		return c.SendStatus(http.StatusOK)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/ctx", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestUseDefaultMiddlewares_CompressesLargeJSONWhenGzipAccepted(t *testing.T) {
+	cfg := testHTTPConfig()
+	app := fiber.New()
+	UseDefaultMiddlewares(app, cfg)
+
+	largePayload := map[string]string{
+		"data": strings.Repeat("x", 8*1024),
+	}
+	app.Get("/large-json", func(c *fiber.Ctx) error {
+		return c.JSON(largePayload)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/large-json", nil)
+	req.Header.Set("Accept-Encoding", "gzip")
+
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if got := resp.Header.Get("Content-Encoding"); got != "gzip" {
+		t.Fatalf("expected Content-Encoding gzip, got %q", got)
+	}
+	gz, err := gzip.NewReader(resp.Body)
+	if err != nil {
+		t.Fatalf("gzip reader: %v", err)
+	}
+	defer gz.Close()
+
+	var payload map[string]string
+	if err := json.NewDecoder(gz).Decode(&payload); err != nil {
+		t.Fatalf("decode json: %v", err)
+	}
+	if payload["data"] != largePayload["data"] {
+		t.Fatalf("unexpected payload body")
+	}
+}
+
+func TestUseDefaultMiddlewares_RequestTimeoutExceeded(t *testing.T) {
+	cfg := testHTTPConfig()
+	cfg.RequestTimeout = 10 * time.Millisecond
+
+	app := fiber.New()
+	UseDefaultMiddlewares(app, cfg)
+	app.Get("/slow", func(c *fiber.Ctx) error {
+		select {
+		case <-time.After(50 * time.Millisecond):
+			return c.SendStatus(http.StatusOK)
+		case <-c.UserContext().Done():
+			return c.SendStatus(http.StatusRequestTimeout)
+		}
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/slow", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusRequestTimeout {
+		t.Fatalf("expected 408, got %d", resp.StatusCode)
+	}
+}
+
+func TestUseDefaultMiddlewares_RequestTimeoutNormalRequestUnaffected(t *testing.T) {
+	cfg := testHTTPConfig()
+	cfg.RequestTimeout = 200 * time.Millisecond
+
+	app := fiber.New()
+	UseDefaultMiddlewares(app, cfg)
+	app.Get("/fast", func(c *fiber.Ctx) error {
+		return c.SendStatus(http.StatusOK)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/fast", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestUseDefaultMiddlewares_RequestTimeoutPerEndpointOverride(t *testing.T) {
+	cfg := testHTTPConfig()
+	cfg.RequestTimeout = 10 * time.Millisecond
+	cfg.RequestTimeoutByPath = map[string]time.Duration{
+		"GET /slow": 120 * time.Millisecond,
+	}
+
+	app := fiber.New()
+	UseDefaultMiddlewares(app, cfg)
+	app.Get("/slow", func(c *fiber.Ctx) error {
+		select {
+		case <-time.After(40 * time.Millisecond):
+			return c.SendStatus(http.StatusOK)
+		case <-c.UserContext().Done():
+			return c.SendStatus(http.StatusRequestTimeout)
+		}
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/slow", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 with override timeout, got %d", resp.StatusCode)
+	}
+}
+
+func TestUseDefaultMiddlewares_RequestTimeoutPerEndpointOverrideDynamicRoute(t *testing.T) {
+	cfg := testHTTPConfig()
+	cfg.RequestTimeout = 10 * time.Millisecond
+	cfg.RequestTimeoutByPath = map[string]time.Duration{
+		"GET /users/:id": 120 * time.Millisecond,
+	}
+
+	app := fiber.New()
+	UseDefaultMiddlewares(app, cfg)
+	app.Get("/users/:id", func(c *fiber.Ctx) error {
+		select {
+		case <-time.After(40 * time.Millisecond):
+			return c.SendStatus(http.StatusOK)
+		case <-c.UserContext().Done():
+			return c.SendStatus(http.StatusRequestTimeout)
+		}
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/users/123", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 with dynamic route override timeout, got %d", resp.StatusCode)
+	}
+}
+
+func TestHTTPAccessLogMiddlewareIncludesErrorDetail(t *testing.T) {
+	var logBuf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewJSONHandler(&logBuf, &slog.HandlerOptions{})))
+	t.Cleanup(func() {
+		slog.SetDefault(prev)
+	})
+
+	app := fiber.New()
+	app.Use(httpAccessLogMiddleware())
+	app.Get("/bad", func(c *fiber.Ctx) error {
+		return response.WriteErrors(c, http.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Title:  "Validation error",
+			Detail: "name is required",
+		}})
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/bad", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if strings.Contains(string(body), "name is required") {
+		t.Fatalf("expected sanitized response detail, got %s", string(body))
+	}
+	if !strings.Contains(string(body), `"detail":"validation failed"`) {
+		t.Fatalf("expected generic response detail, got %s", string(body))
+	}
+	if !strings.Contains(logBuf.String(), "name is required") {
+		t.Fatalf("expected access log to include original detail, got %s", logBuf.String())
+	}
+}
+
+func TestHTTPAccessLogMiddlewareIncludesResponseBodyOnServerError(t *testing.T) {
+	var logBuf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewJSONHandler(&logBuf, &slog.HandlerOptions{})))
+	t.Cleanup(func() {
+		slog.SetDefault(prev)
+	})
+
+	app := fiber.New()
+	app.Use(httpAccessLogMiddleware())
+	app.Get("/boom", func(c *fiber.Ctx) error {
+		return c.Status(http.StatusInternalServerError).JSON(fiber.Map{
+			"errors": []fiber.Map{{
+				"status": "500",
+				"title":  "Update failed",
+				"detail": "db deadlock on takeover update",
+			}},
+		})
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/boom", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusInternalServerError {
+		t.Fatalf("expected 500, got %d", resp.StatusCode)
+	}
+	if !strings.Contains(logBuf.String(), "db deadlock on takeover update") {
+		t.Fatalf("expected access log to include response body detail, got %s", logBuf.String())
+	}
+	if !strings.Contains(logBuf.String(), "response_body") {
+		t.Fatalf("expected access log to include response_body field, got %s", logBuf.String())
+	}
+}
+
+func TestHTTPAccessLogMiddlewareIncludesInternalErrorDetail(t *testing.T) {
+	var logBuf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewJSONHandler(&logBuf, &slog.HandlerOptions{})))
+	t.Cleanup(func() {
+		slog.SetDefault(prev)
+	})
+
+	app := fiber.New()
+	app.Use(httpAccessLogMiddleware())
+	app.Get("/boom", func(c *fiber.Ctx) error {
+		c.Locals(apperrorsx.ContextKeyHTTPErrorInternalDetail, "action=UpdateTakeover | error=reserve update failed | chain=*errors.errorString: reserve update failed")
+		return c.Status(http.StatusInternalServerError).JSON(fiber.Map{
+			"errors": []fiber.Map{{
+				"status": "500",
+				"title":  "Update failed",
+				"detail": "internal server error",
+			}},
+		})
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/boom", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusInternalServerError {
+		t.Fatalf("expected 500, got %d", resp.StatusCode)
+	}
+	if !strings.Contains(logBuf.String(), "internal_detail") {
+		t.Fatalf("expected access log to include internal_detail field, got %s", logBuf.String())
+	}
+	if !strings.Contains(logBuf.String(), "reserve update failed") {
+		t.Fatalf("expected access log to include internal error detail, got %s", logBuf.String())
+	}
+}
+
+func TestUseDefaultMiddlewares_HTTPMetricsUsesRoutePatternLabels(t *testing.T) {
+	cfg := testHTTPConfig()
+	app := fiber.New()
+	UseDefaultMiddlewares(app, cfg)
+	app.Get("/users/:id", func(c *fiber.Ctx) error {
+		return c.SendStatus(http.StatusCreated)
+	})
+	app.Get("/metrics", func(c *fiber.Ctx) error {
+		metricsHandler(c.Context())
+		return nil
+	})
+
+	beforeCounter := metricCounterValue(t, httpRequestsTotal, "GET", "/users/:id", "201")
+	beforeHistogram := metricHistogramCount(t, httpRequestDurationSeconds, "GET", "/users/:id", "201")
+
+	req, _ := http.NewRequest(http.MethodGet, "/users/123", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201, got %d", resp.StatusCode)
+	}
+
+	afterCounter := metricCounterValue(t, httpRequestsTotal, "GET", "/users/:id", "201")
+	afterHistogram := metricHistogramCount(t, httpRequestDurationSeconds, "GET", "/users/:id", "201")
+	if afterCounter <= beforeCounter {
+		t.Fatalf("expected counter to increase, before=%v after=%v", beforeCounter, afterCounter)
+	}
+	if afterHistogram <= beforeHistogram {
+		t.Fatalf("expected histogram count to increase, before=%v after=%v", beforeHistogram, afterHistogram)
+	}
+
+	metricsReq, _ := http.NewRequest(http.MethodGet, "/metrics", nil)
+	metricsResp, err := app.Test(metricsReq)
+	if err != nil {
+		t.Fatalf("metrics app.Test: %v", err)
+	}
+	if metricsResp.StatusCode != http.StatusOK {
+		t.Fatalf("expected /metrics status 200, got %d", metricsResp.StatusCode)
+	}
+	body, err := io.ReadAll(metricsResp.Body)
+	if err != nil {
+		t.Fatalf("read /metrics body: %v", err)
+	}
+	metricsBody := string(body)
+	if !strings.Contains(metricsBody, "http_requests_total") {
+		t.Fatalf("expected http_requests_total in /metrics output")
+	}
+	if !strings.Contains(metricsBody, "http_request_duration_seconds") {
+		t.Fatalf("expected http_request_duration_seconds in /metrics output")
+	}
+	if !strings.Contains(metricsBody, "path=\"/users/:id\"") {
+		t.Fatalf("expected route-pattern path label in /metrics output")
+	}
+
+	beforeMetricsCounter := metricCounterValue(t, httpRequestsTotal, "GET", "/metrics", "200")
+	beforeMetricsHistogram := metricHistogramCount(t, httpRequestDurationSeconds, "GET", "/metrics", "200")
+	metricsReq2, _ := http.NewRequest(http.MethodGet, "/metrics", nil)
+	metricsResp2, err := app.Test(metricsReq2)
+	if err != nil {
+		t.Fatalf("metrics second app.Test: %v", err)
+	}
+	if metricsResp2.StatusCode != http.StatusOK {
+		t.Fatalf("expected second /metrics status 200, got %d", metricsResp2.StatusCode)
+	}
+	afterMetricsCounter := metricCounterValue(t, httpRequestsTotal, "GET", "/metrics", "200")
+	afterMetricsHistogram := metricHistogramCount(t, httpRequestDurationSeconds, "GET", "/metrics", "200")
+	if afterMetricsCounter != beforeMetricsCounter {
+		t.Fatalf("expected /metrics to be excluded from counter, before=%v after=%v", beforeMetricsCounter, afterMetricsCounter)
+	}
+	if afterMetricsHistogram != beforeMetricsHistogram {
+		t.Fatalf("expected /metrics to be excluded from histogram, before=%v after=%v", beforeMetricsHistogram, afterMetricsHistogram)
+	}
+}
+
+func TestNormalizeHTTPMethod(t *testing.T) {
+	tests := []struct {
+		name   string
+		input  string
+		output string
+	}{
+		{name: "get", input: "GET", output: "GET"},
+		{name: "lowercase", input: "post", output: "POST"},
+		{name: "trimmed", input: "  put  ", output: "PUT"},
+		{name: "empty", input: "", output: "UNKNOWN"},
+		{name: "custom", input: "GETT", output: "OTHER"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := normalizeHTTPMethod(tt.input); got != tt.output {
+				t.Fatalf("expected %q, got %q", tt.output, got)
+			}
+		})
+	}
+}
+
+func metricCounterValue(t *testing.T, vec *prometheus.CounterVec, labels ...string) float64 {
+	t.Helper()
+	m := &dto.Metric{}
+	if err := vec.WithLabelValues(labels...).Write(m); err != nil {
+		t.Fatalf("read counter metric: %v", err)
+	}
+	return m.GetCounter().GetValue()
+}
+
+func metricHistogramCount(t *testing.T, vec *prometheus.HistogramVec, labels ...string) uint64 {
+	t.Helper()
+	observer, err := vec.GetMetricWithLabelValues(labels...)
+	if err != nil {
+		t.Fatalf("load histogram metric: %v", err)
+	}
+	metric, ok := observer.(prometheus.Metric)
+	if !ok {
+		t.Fatalf("histogram observer does not implement prometheus.Metric")
+	}
+	m := &dto.Metric{}
+	if err := metric.Write(m); err != nil {
+		t.Fatalf("read histogram metric: %v", err)
+	}
+	if m.GetHistogram() == nil {
+		t.Fatalf("histogram metric not available for labels %v", labels)
+	}
+	return m.GetHistogram().GetSampleCount()
+}
diff --git a/internal/app/api/pin_actions.go b/internal/app/api/pin_actions.go
new file mode 100644
index 0000000..e8b0ed9
--- /dev/null
+++ b/internal/app/api/pin_actions.go
@@ -0,0 +1,9 @@
+package api
+
+type PinProtectedEndpoint struct {
+	Method string
+	Path   string
+	Action string
+}
+
+var PinProtectedEndpoints = []PinProtectedEndpoint{}
diff --git a/internal/app/api/pin_actions_test.go b/internal/app/api/pin_actions_test.go
new file mode 100644
index 0000000..b83364a
--- /dev/null
+++ b/internal/app/api/pin_actions_test.go
@@ -0,0 +1,64 @@
+package api
+
+import (
+	"net/http"
+	"testing"
+
+	"github.com/gofiber/fiber/v2"
+)
+
+func TestPinProtectedEndpoints_Definition(t *testing.T) {
+	seen := map[string]struct{}{}
+	for _, ep := range PinProtectedEndpoints {
+		if ep.Method == "" || ep.Path == "" || ep.Action == "" {
+			t.Fatalf("invalid pin-protected endpoint: %#v", ep)
+		}
+		key := ep.Method + " " + ep.Path
+		if _, ok := seen[key]; ok {
+			t.Fatalf("duplicate pin-protected endpoint %s", key)
+		}
+		seen[key] = struct{}{}
+	}
+}
+
+func TestPinProtectedEndpoints_RoutesHavePinMiddleware(t *testing.T) {
+	if len(PinProtectedEndpoints) == 0 {
+		return
+	}
+	app := fiber.New()
+	RegisterRoutes(app, buildRouteDependenciesForTest())
+
+	routes := app.GetRoutes(true)
+	for _, ep := range PinProtectedEndpoints {
+		route := findRoute(routes, ep.Method, ep.Path)
+		if route == nil {
+			t.Fatalf("pin-protected route %s %s is not registered", ep.Method, ep.Path)
+		}
+		minHandlers := 3 // pin + permission + handler
+		if ep.Path == "/api/v1/auth/invite" {
+			minHandlers = 4 // auth + pin + permission + handler (no group auth middleware)
+		}
+		if len(route.Handlers) < minHandlers {
+			t.Fatalf("route %s %s expected at least %d handlers, got %d", ep.Method, ep.Path, minHandlers, len(route.Handlers))
+		}
+	}
+}
+
+func findRoute(routes []fiber.Route, method, path string) *fiber.Route {
+	for i := range routes {
+		if routes[i].Method == method && routes[i].Path == path {
+			return &routes[i]
+		}
+	}
+	return nil
+}
+
+func TestPinProtectedEndpoints_ExpectedMethods(t *testing.T) {
+	for _, ep := range PinProtectedEndpoints {
+		switch ep.Method {
+		case http.MethodGet, http.MethodPost, http.MethodPatch, http.MethodDelete:
+		default:
+			t.Fatalf("unexpected method %q on pin-protected endpoint %s", ep.Method, ep.Path)
+		}
+	}
+}
diff --git a/internal/app/api/routes.go b/internal/app/api/routes.go
new file mode 100644
index 0000000..cca06cb
--- /dev/null
+++ b/internal/app/api/routes.go
@@ -0,0 +1,140 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+	"github.com/valyala/fasthttp/fasthttpadaptor"
+
+	samlauth "wucher/internal/auth"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/metrics"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+var metricsHandler = fasthttpadaptor.NewFastHTTPHandler(metrics.PromHTTPHandler())
+
+type RouteServices struct {
+	Auth  *service.AuthService
+	Audit *service.AuditLogService
+	WOPI  *service.WOPIService
+}
+
+type RouteHandlers struct {
+	User                     *handlers.UserHandler
+	Contact                  *handlers.ContactHandler
+	Health                   *handlers.HealthHandler
+	BuildInfo                *handlers.BuildInfoHandler
+	Auth                     *handlers.AuthHandler
+	Role                     *handlers.RoleHandler
+	Helicopter               *handlers.HelicopterHandler
+	HelicopterUsage          *handlers.HelicopterUsageHandler
+	HelicopterFile           *handlers.HelicopterFileHandler
+	Flight                   *handlers.FlightHandler
+	FlightData               *handlers.FlightDataHandler
+	Mission                  *handlers.MissionHandler
+	FMReport                 *handlers.FMReportHandler
+	ReserveAc                *handlers.ReserveAcHandler
+	Takeover                 *handlers.TakeoverHandler
+	OtherPerson              *handlers.OtherPersonHandler
+	Facility                 *handlers.FacilityHandler
+	Base                     *handlers.BaseHandler
+	Medicine                 *handlers.MedicineHandler
+	Vocation                 *handlers.VocationHandler
+	Opc                      *handlers.OpcHandler
+	ForcesPresent            *handlers.ForcesPresentHandler
+	Hospital                 *handlers.HospitalHandler
+	HealthInsuranceCompanies *handlers.HealthInsuranceCompaniesHandler
+	FederalState             *handlers.FederalStateHandler
+	ICAO                     *handlers.ICAOHandler
+	Land                     *handlers.LandHandler
+	MasterSettings           *handlers.MasterSettingsHandler
+	Branding                 *handlers.BrandingHandler
+	FileManagerFolder        *handlers.FileManagerFolderHandler
+	FileManagerFile          *handlers.FileManagerFileHandler
+	FileManagerAttachment    *handlers.FileManagerAttachmentHandler
+	FileManagerEvents        *handlers.FileManagerEventsHandler
+	HelicopterFileEvents     *handlers.HelicopterFileEventsHandler
+	DutyRoster               *handlers.DutyRosterHandler
+	AirRescuerChecklist      *handlers.AirRescuerChecklistHandler
+	InsurancePatientData     *handlers.InsurancePatientDataHandler
+	PatientData              *handlers.PatientDataHandler
+	HEMSOperationalData      *handlers.HEMSOperationalDataHandler
+	HEMSOperationCategory    *handlers.HEMSOperationCategoryHandler
+	HEMSOperation            *handlers.HEMSOperationHandler
+	Complaint                *handlers.ComplaintHandler
+	EASARelease              *handlers.EASAReleaseHandler
+	ActionSignoff            *handlers.ActionSignoffHandler
+	MCF                      *handlers.MCFHandler
+	DUL                      *handlers.DULHandler
+	FleetStatus              *handlers.FleetStatusHandler
+	SAMLAuth                 *samlauth.Handler
+}
+
+type RouteDependencies struct {
+	Handlers RouteHandlers
+	Services RouteServices
+}
+
+func RegisterRoutes(app *fiber.App, deps RouteDependencies) {
+	h := deps.Handlers
+	s := deps.Services
+
+	app.Get("/health", h.Health.Handle)
+	app.Get("/version", h.BuildInfo.Handle)
+	app.Get("/api/version", h.BuildInfo.Handle)
+	app.Get("/api/build-info", h.BuildInfo.Handle)
+	app.Get("/metrics", func(c *fiber.Ctx) error {
+		metricsHandler(c.Context())
+		return nil
+	})
+
+	api := app.Group("/api")
+	api.Use(AuditMiddleware(s.Audit))
+	v1 := api.Group("/v1")
+
+	registerAuthRoutes(v1, h.Auth, s.Auth, h.SAMLAuth)
+	registerUserRoutes(v1, h.User, h.FileManagerEvents, middleware.AuthRequired(s.Auth), s.Auth)
+	registerContactRoutes(v1, h.Contact, middleware.AuthRequired(s.Auth), s.Auth)
+	registerRoleRoutes(v1, h.Role, middleware.AuthRequired(s.Auth), s.Auth)
+	registerHelicopterRoutes(v1, h.Helicopter, middleware.AuthRequired(s.Auth), s.Auth)
+	registerHelicopterUsageRoutes(v1, h.HelicopterUsage, middleware.AuthRequired(s.Auth), s.Auth)
+	registerHelicopterFileRoutes(v1, h.HelicopterFile, h.HelicopterFileEvents, middleware.AuthRequired(s.Auth), s.Auth)
+	registerFlightRoutes(v1, h.Flight, middleware.AuthRequired(s.Auth), s.Auth)
+	registerFlightDataRoutes(v1, h.FlightData, middleware.AuthRequired(s.Auth), s.Auth)
+	registerMissionRoutes(v1, h.Mission, h.FileManagerEvents, middleware.AuthRequired(s.Auth), s.Auth)
+	registerFMReportRoutes(v1, h.FMReport, middleware.AuthRequired(s.Auth), s.Auth)
+	registerReserveAcRoutes(v1, h.ReserveAc, h.Takeover, middleware.AuthRequired(s.Auth), s.Auth)
+	registerTakeoverRoutes(v1, h.Takeover, middleware.AuthRequired(s.Auth), s.Auth)
+	registerOtherPersonRoutes(v1, h.OtherPerson, middleware.AuthRequired(s.Auth), s.Auth)
+	registerLastFlightsInspectionRoutes(v1, h.ReserveAc, middleware.AuthRequired(s.Auth), s.Auth)
+	registerFacilityRoutes(v1, h.Facility, middleware.AuthRequired(s.Auth), s.Auth)
+	registerBaseRoutes(v1, h.Base, h.FileManagerEvents, middleware.AuthRequired(s.Auth), s.Auth)
+	registerMedicineRoutes(v1, h.Medicine, middleware.AuthRequired(s.Auth), s.Auth)
+	registerVocationRoutes(v1, h.Vocation, middleware.AuthRequired(s.Auth), s.Auth)
+	registerOpcRoutes(v1, h.Opc, middleware.AuthRequired(s.Auth), s.Auth)
+	registerForcesPresentRoutes(v1, h.ForcesPresent, middleware.AuthRequired(s.Auth), s.Auth)
+	registerHospitalRoutes(v1, h.Hospital, middleware.AuthRequired(s.Auth), s.Auth)
+	registerHealthInsuranceCompaniesRoutes(v1, h.HealthInsuranceCompanies, middleware.AuthRequired(s.Auth), s.Auth)
+	registerFederalStateRoutes(v1, h.FederalState, middleware.AuthRequired(s.Auth), s.Auth)
+	registerICAORoutes(v1, h.ICAO, middleware.AuthRequired(s.Auth), s.Auth)
+	registerLandRoutes(v1, h.Land, middleware.AuthRequired(s.Auth), s.Auth)
+	registerMasterSettingsRoutes(v1, h.MasterSettings, middleware.AuthRequired(s.Auth), s.Auth)
+	registerBrandingRoutes(v1, h.Branding)
+	registerFileManagerRoutes(v1, h.FileManagerFolder, h.FileManagerFile, h.FileManagerAttachment, h.FileManagerEvents, middleware.AuthRequired(s.Auth), s.Auth)
+	registerWOPIRoutes(app, h.Takeover, s.WOPI)
+	registerDutyRosterRoutes(v1, h.DutyRoster, middleware.AuthRequired(s.Auth), s.Auth)
+	registerAirRescuerChecklistRoutes(v1, h.AirRescuerChecklist, middleware.AuthRequired(s.Auth), s.Auth)
+	registerInsurancePatientDataRoutes(v1, h.InsurancePatientData, middleware.AuthRequired(s.Auth), s.Auth)
+	registerPatientDataRoutes(v1, h.PatientData, middleware.AuthRequired(s.Auth), s.Auth)
+	registerHEMSOperationalDataRoutes(v1, h.HEMSOperationalData, middleware.AuthRequired(s.Auth), s.Auth)
+	registerHEMSOperationCategoryRoutes(v1, h.HEMSOperationCategory, middleware.AuthRequired(s.Auth), s.Auth)
+	registerHEMSOperationRoutes(v1, h.HEMSOperation, middleware.AuthRequired(s.Auth), s.Auth)
+	registerComplaintRoutes(v1, h.Complaint, middleware.AuthRequired(s.Auth), s.Auth)
+	registerEASAReleaseRoutes(v1, h.EASARelease, middleware.AuthRequired(s.Auth), s.Auth)
+	registerActionSignoffRoutes(v1, h.ActionSignoff, middleware.AuthRequired(s.Auth), s.Auth)
+	registerMCFRoutes(v1, h.MCF, middleware.AuthRequired(s.Auth), s.Auth)
+	registerDULRoutes(v1, h.DUL, h.FileManagerEvents, middleware.AuthRequired(s.Auth), s.Auth)
+	registerFleetStatusRoutes(v1, h.FleetStatus, middleware.AuthRequired(s.Auth), s.Auth)
+	registerAuditRoutes(v1, handlers.NewAuditHandler(s.Audit), middleware.AuthRequired(s.Auth), s.Auth)
+	registerSwaggerRoutes(app)
+}
diff --git a/internal/app/api/routes_action_signoff.go b/internal/app/api/routes_action_signoff.go
new file mode 100644
index 0000000..66972fa
--- /dev/null
+++ b/internal/app/api/routes_action_signoff.go
@@ -0,0 +1,15 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerActionSignoffRoutes(v1 fiber.Router, h *handlers.ActionSignoffHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	g := v1.Group("/action-signoffs", authMiddleware)
+	g.Get("/get-by-flight/:flight_id", middleware.PermissionRequired(authSvc, "action_signoff.read"), h.GetByFlight)
+	g.Post("/sign/:helicopter_id", middleware.PermissionRequired(authSvc, "action_signoff.sign"), h.Sign)
+}
diff --git a/internal/app/api/routes_air_rescuer_checklist.go b/internal/app/api/routes_air_rescuer_checklist.go
new file mode 100644
index 0000000..754eb93
--- /dev/null
+++ b/internal/app/api/routes_air_rescuer_checklist.go
@@ -0,0 +1,23 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerAirRescuerChecklistRoutes(v1 fiber.Router, checklistHandler *handlers.AirRescuerChecklistHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	checklists := v1.Group("/air-rescuer-checklist", authMiddleware)
+	checklists.Post("/create", middleware.PermissionRequired(authSvc, "air_rescuer_checklist.create"), checklistHandler.Create)
+	checklists.Get("/get-all", middleware.PermissionRequired(authSvc, "air_rescuer_checklist.read"), checklistHandler.List)
+	checklists.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "air_rescuer_checklist.read"), checklistHandler.ListDatatable)
+	checklists.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "air_rescuer_checklist.read"), checklistHandler.Get)
+	checklists.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "air_rescuer_checklist.update"), checklistHandler.Update)
+	checklists.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "air_rescuer_checklist.delete"), checklistHandler.Delete)
+	checklists.Post("/:uuid/items/create", middleware.PermissionRequired(authSvc, "air_rescuer_checklist.update"), checklistHandler.CreateItem)
+	checklists.Patch("/:uuid/items/reorder", middleware.PermissionRequired(authSvc, "air_rescuer_checklist.update"), checklistHandler.ReorderItems)
+	checklists.Patch("/items/update/:item_uuid", middleware.PermissionRequired(authSvc, "air_rescuer_checklist.update"), checklistHandler.UpdateItem)
+	checklists.Delete("/items/delete/:item_uuid", middleware.PermissionRequired(authSvc, "air_rescuer_checklist.delete"), checklistHandler.DeleteItem)
+}
diff --git a/internal/app/api/routes_audit.go b/internal/app/api/routes_audit.go
new file mode 100644
index 0000000..a6f6a50
--- /dev/null
+++ b/internal/app/api/routes_audit.go
@@ -0,0 +1,14 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerAuditRoutes(v1 fiber.Router, auditHandler *handlers.AuditHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	audits := v1.Group("/audit-logs", authMiddleware)
+	audits.Get("/get-all", middleware.PermissionRequiredReusable(authSvc, "audit.read"), auditHandler.List)
+}
diff --git a/internal/app/api/routes_auth.go b/internal/app/api/routes_auth.go
new file mode 100644
index 0000000..145bd90
--- /dev/null
+++ b/internal/app/api/routes_auth.go
@@ -0,0 +1,142 @@
+package api
+
+import (
+	"strconv"
+
+	"github.com/gofiber/fiber/v2"
+	"github.com/gofiber/fiber/v2/middleware/limiter"
+
+	samlauth "wucher/internal/auth"
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerAuthRoutes(v1 fiber.Router, authHandler *handlers.AuthHandler, authSvc *service.AuthService, samlHandler *samlauth.Handler) {
+	auth := v1.Group("/auth")
+	auth.Post("/register", authHandler.Register)
+	auth.Post("/invite", middleware.AuthRequired(authSvc), middleware.PermissionRequired(authSvc, "user.create"), authHandler.Invite)
+	auth.Post("/invite/resend-set-password", middleware.AuthRequired(authSvc), middleware.PermissionRequired(authSvc, "user.update"), forgotPasswordIPLimiter(authSvc), authHandler.ResendSetPasswordInvite)
+	auth.Post("/set-password", authHandler.SetPassword)
+	auth.Post("/forgot-password", forgotPasswordIPLimiter(authSvc), authHandler.ForgotPassword)
+	auth.Post("/reset-password", authHandler.ResetPassword)
+	auth.Post("/pin/setup", middleware.AuthRequired(authSvc), authHandler.SetupSecurityPIN)
+	auth.Post("/pin/verify", middleware.AuthRequired(authSvc), authHandler.VerifySecurityPIN)
+	auth.Post("/pin/change", middleware.AuthRequired(authSvc), authHandler.ChangeSecurityPIN)
+	auth.Post("/pin/request-reset", middleware.AuthRequired(authSvc), forgotPasswordIPLimiter(authSvc), authHandler.RequestSecurityPINReset)
+	auth.Post("/pin/forgot", forgotPasswordIPLimiter(authSvc), authHandler.ForgotSecurityPIN)
+	auth.Post("/pin/reset", authHandler.ResetSecurityPIN)
+	auth.Post("/login", loginIPLimiter(authSvc), authHandler.Login)
+	auth.Post("/exchange", authHandler.Exchange)
+	auth.Post("/webauthn/register/begin", middleware.AuthRequired(authSvc), authHandler.WebAuthnRegisterBegin)
+	auth.Post("/webauthn/register/finish", middleware.AuthRequired(authSvc), authHandler.WebAuthnRegisterFinish)
+	auth.Post("/webauthn/login/begin", authHandler.WebAuthnLoginBegin)
+	auth.Post("/webauthn/login/finish", authHandler.WebAuthnLoginFinish)
+	auth.Post("/webauthn/reset-setup", middleware.AuthRequired(authSvc), authHandler.WebAuthnResetSetup)
+	auth.Post("/refresh", authHandler.Refresh)
+	auth.Post("/logout", authHandler.Logout)
+	auth.Get("/sessions", middleware.AuthRequired(authSvc), authHandler.Sessions)
+	auth.Delete("/sessions/:session_id", middleware.AuthRequired(authSvc), authHandler.DeleteSession)
+	auth.Get("/me", middleware.AuthRequired(authSvc), authHandler.Me)
+	auth.Patch("/me/timezone", middleware.AuthRequired(authSvc), authHandler.UpdateTimezone)
+	auth.Get("/verify-email", authHandler.VerifyEmail)
+	if samlHandler != nil {
+		auth.Get("/microsoft/login", samlHandler.HandleLogin)
+		auth.Get("/microsoft/metadata", samlHandler.HandleMetadata)
+	} else {
+		auth.Get("/microsoft/login", authHandler.MicrosoftLogin)
+	}
+	auth.Get("/microsoft/login-check", authHandler.MicrosoftLoginCheck)
+	auth.Get("/microsoft/link", middleware.AuthRequired(authSvc), authHandler.MicrosoftLink)
+	auth.Get("/microsoft/reauth", middleware.AuthRequired(authSvc), authHandler.MicrosoftReauth)
+	if samlHandler != nil {
+		auth.Get("/microsoft/callback", samlHandler.HandleSAMLCallback)
+		auth.Post("/microsoft/callback", samlHandler.HandleSAMLCallback)
+		auth.Get("/microsoft/logout", func(c *fiber.Ctx) error {
+			if c.Query("SAMLRequest") != "" {
+				return samlHandler.HandleSAMLLogoutRequest(c)
+			}
+			if c.Query("SAMLResponse") != "" {
+				return samlHandler.HandleSAMLLogoutResponse(c)
+			}
+			return samlHandler.HandleBrowserLocalLogout(c)
+		})
+		auth.Post("/microsoft/logout", func(c *fiber.Ctx) error {
+			if c.FormValue("SAMLRequest") != "" {
+				return samlHandler.HandleSAMLLogoutRequest(c)
+			}
+			if c.FormValue("SAMLResponse") != "" {
+				return samlHandler.HandleSAMLLogoutResponse(c)
+			}
+			return samlHandler.HandleBrowserLocalLogout(c)
+		})
+	} else {
+		auth.Get("/microsoft/callback", authHandler.MicrosoftCallback)
+		auth.Post("/microsoft/logout", middleware.AuthRequired(authSvc), authHandler.MicrosoftLogout)
+	}
+	// OIDC front-channel logout: invoked by Microsoft Entra in a hidden iframe when the
+	// user signs out at the IdP. Must be public (the IdP has no app credentials) and
+	// available regardless of the active Microsoft auth mode.
+	auth.Get("/microsoft/front-channel-logout", authHandler.MicrosoftFrontChannelLogout)
+	auth.Post("/microsoft/front-channel-logout", authHandler.MicrosoftFrontChannelLogout)
+	auth.Post("/microsoft/refresh", middleware.AuthRequired(authSvc), authHandler.MicrosoftRefresh)
+	auth.Post("/sso/link", middleware.AuthRequired(authSvc), authHandler.SSOLink)
+	auth.Delete("/sso/unlink", middleware.AuthRequired(authSvc), authHandler.SSOUnlink)
+	auth.Post("/totp/setup", middleware.AuthRequired(authSvc), authHandler.TOTPSetup)
+	auth.Post("/totp/confirm", middleware.AuthRequired(authSvc), authHandler.TOTPConfirm)
+	auth.Post("/totp/verify", authHandler.TOTPVerify)
+	auth.Post("/email-otp/send", authHandler.SendEmailOTP)
+	auth.Post("/email-otp/verify", authHandler.VerifyEmailOTP)
+	auth.Post("/totp/disable", middleware.AuthRequired(authSvc), authHandler.TOTPDisable)
+	auth.Post("/totp/reset-setup", middleware.AuthRequired(authSvc), authHandler.TOTPResetSetup)
+}
+
+func forgotPasswordIPLimiter(authSvc *service.AuthService) fiber.Handler {
+	window := authSvc.ForgotPasswordIPRateWindow()
+	return limiter.New(limiter.Config{
+		Max:        authSvc.ForgotPasswordIPRateMax(),
+		Expiration: window,
+		KeyGenerator: func(c *fiber.Ctx) string {
+			return c.IP()
+		},
+		LimitReached: func(c *fiber.Ctx) error {
+			retryAfter := int(window.Seconds())
+			if retryAfter < 1 {
+				retryAfter = 1
+			}
+			c.Set(fiber.HeaderRetryAfter, strconv.Itoa(retryAfter))
+			return c.Status(fiber.StatusTooManyRequests).JSON(fiber.Map{
+				"errors": []fiber.Map{{
+					"status": "429",
+					"title":  "Too Many Requests",
+					"detail": "rate limit exceeded",
+				}},
+			})
+		},
+	})
+}
+
+func loginIPLimiter(authSvc *service.AuthService) fiber.Handler {
+	window := authSvc.LoginIPRateWindow()
+	return limiter.New(limiter.Config{
+		Max:        authSvc.LoginIPRateMax(),
+		Expiration: window,
+		KeyGenerator: func(c *fiber.Ctx) string {
+			return c.IP()
+		},
+		LimitReached: func(c *fiber.Ctx) error {
+			retryAfter := int(window.Seconds())
+			if retryAfter < 1 {
+				retryAfter = 1
+			}
+			c.Set(fiber.HeaderRetryAfter, strconv.Itoa(retryAfter))
+			return c.Status(fiber.StatusTooManyRequests).JSON(fiber.Map{
+				"errors": []fiber.Map{{
+					"status": "429",
+					"title":  "Too Many Requests",
+					"detail": "rate limit exceeded",
+				}},
+			})
+		},
+	})
+}
diff --git a/internal/app/api/routes_auth_test.go b/internal/app/api/routes_auth_test.go
new file mode 100644
index 0000000..27d7e3a
--- /dev/null
+++ b/internal/app/api/routes_auth_test.go
@@ -0,0 +1,154 @@
+package api
+
+import (
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/config"
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+)
+
+func TestForgotPasswordIPLimiter(t *testing.T) {
+	cfg := config.AuthConfig{
+		ForgotPasswordIPRateMax:    1,
+		ForgotPasswordIPRateWindow: time.Minute,
+	}
+	svc := service.NewAuthService(nil, nil, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	app := fiber.New()
+	app.Post("/forgot", forgotPasswordIPLimiter(svc), func(c *fiber.Ctx) error {
+		return c.SendStatus(http.StatusOK)
+	})
+
+	req1, _ := http.NewRequest(http.MethodPost, "/forgot", nil)
+	resp1, err := app.Test(req1)
+	if err != nil {
+		t.Fatalf("first request failed: %v", err)
+	}
+	if resp1.StatusCode != http.StatusOK {
+		t.Fatalf("expected first request 200, got %d", resp1.StatusCode)
+	}
+
+	req2, _ := http.NewRequest(http.MethodPost, "/forgot", nil)
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("second request failed: %v", err)
+	}
+	if resp2.StatusCode != http.StatusTooManyRequests {
+		t.Fatalf("expected second request 429, got %d", resp2.StatusCode)
+	}
+}
+
+func TestLoginIPLimiter(t *testing.T) {
+	cfg := config.AuthConfig{
+		LoginIPRateMax:    1,
+		LoginIPRateWindow: time.Minute,
+	}
+	svc := service.NewAuthService(nil, nil, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	app := fiber.New()
+	app.Post("/login", loginIPLimiter(svc), func(c *fiber.Ctx) error {
+		return c.SendStatus(http.StatusOK)
+	})
+
+	req1, _ := http.NewRequest(http.MethodPost, "/login", nil)
+	resp1, err := app.Test(req1)
+	if err != nil {
+		t.Fatalf("first request failed: %v", err)
+	}
+	if resp1.StatusCode != http.StatusOK {
+		t.Fatalf("expected first request 200, got %d", resp1.StatusCode)
+	}
+
+	req2, _ := http.NewRequest(http.MethodPost, "/login", nil)
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("second request failed: %v", err)
+	}
+	if resp2.StatusCode != http.StatusTooManyRequests {
+		t.Fatalf("expected second request 429, got %d", resp2.StatusCode)
+	}
+}
+
+func TestRegisterAuthRoutes(t *testing.T) {
+	app := fiber.New()
+	v1 := app.Group("/api/v1")
+
+	svc := service.NewAuthService(nil, nil, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	authHandler := handlers.NewAuthHandler(svc)
+	registerAuthRoutes(v1, authHandler, svc, nil)
+
+	routes := app.GetRoutes(true)
+	required := []struct {
+		method string
+		path   string
+	}{
+		{method: http.MethodPost, path: "/api/v1/auth/register"},
+		{method: http.MethodPost, path: "/api/v1/auth/invite"},
+		{method: http.MethodPost, path: "/api/v1/auth/invite/resend-set-password"},
+		{method: http.MethodPost, path: "/api/v1/auth/forgot-password"},
+		{method: http.MethodPost, path: "/api/v1/auth/reset-password"},
+		{method: http.MethodPost, path: "/api/v1/auth/pin/setup"},
+		{method: http.MethodPost, path: "/api/v1/auth/pin/verify"},
+		{method: http.MethodPost, path: "/api/v1/auth/pin/change"},
+		{method: http.MethodPost, path: "/api/v1/auth/pin/request-reset"},
+		{method: http.MethodPost, path: "/api/v1/auth/pin/forgot"},
+		{method: http.MethodPost, path: "/api/v1/auth/pin/reset"},
+		{method: http.MethodPost, path: "/api/v1/auth/login"},
+		{method: http.MethodPost, path: "/api/v1/auth/exchange"},
+		{method: http.MethodPost, path: "/api/v1/auth/webauthn/register/begin"},
+		{method: http.MethodPost, path: "/api/v1/auth/webauthn/register/finish"},
+		{method: http.MethodPost, path: "/api/v1/auth/webauthn/login/begin"},
+		{method: http.MethodPost, path: "/api/v1/auth/webauthn/login/finish"},
+		{method: http.MethodPost, path: "/api/v1/auth/webauthn/reset-setup"},
+		{method: http.MethodPost, path: "/api/v1/auth/refresh"},
+		{method: http.MethodGet, path: "/api/v1/auth/sessions"},
+		{method: http.MethodDelete, path: "/api/v1/auth/sessions/:session_id"},
+		{method: http.MethodGet, path: "/api/v1/auth/me"},
+		{method: http.MethodGet, path: "/api/v1/auth/microsoft/login"},
+		{method: http.MethodGet, path: "/api/v1/auth/microsoft/login-check"},
+		{method: http.MethodGet, path: "/api/v1/auth/microsoft/link"},
+		{method: http.MethodPost, path: "/api/v1/auth/sso/link"},
+		{method: http.MethodDelete, path: "/api/v1/auth/sso/unlink"},
+		{method: http.MethodPost, path: "/api/v1/auth/totp/verify"},
+		{method: http.MethodPost, path: "/api/v1/auth/totp/reset-setup"},
+	}
+
+	for _, tc := range required {
+		if !hasRoute(routes, tc.method, tc.path) {
+			t.Fatalf("route %s %s not registered", tc.method, tc.path)
+		}
+	}
+
+	var forgotRoute *fiber.Route
+	for i := range routes {
+		if routes[i].Method == http.MethodPost && routes[i].Path == "/api/v1/auth/forgot-password" {
+			forgotRoute = &routes[i]
+			break
+		}
+	}
+	if forgotRoute == nil {
+		t.Fatalf("forgot password route not found")
+	}
+	if len(forgotRoute.Handlers) < 2 {
+		t.Fatalf("expected forgot password route to have limiter and handler, got %d handlers", len(forgotRoute.Handlers))
+	}
+
+	var loginRoute *fiber.Route
+	for i := range routes {
+		if routes[i].Method == http.MethodPost && routes[i].Path == "/api/v1/auth/login" {
+			loginRoute = &routes[i]
+			break
+		}
+	}
+	if loginRoute == nil {
+		t.Fatalf("login route not found")
+	}
+	if len(loginRoute.Handlers) < 2 {
+		t.Fatalf("expected login route to have limiter and handler, got %d handlers", len(loginRoute.Handlers))
+	}
+}
diff --git a/internal/app/api/routes_base.go b/internal/app/api/routes_base.go
new file mode 100644
index 0000000..4677749
--- /dev/null
+++ b/internal/app/api/routes_base.go
@@ -0,0 +1,35 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerBaseRoutes(
+	v1 fiber.Router,
+	baseHandler *handlers.BaseHandler,
+	eventsHandler *handlers.FileManagerEventsHandler,
+	authMiddleware fiber.Handler,
+	authSvc *service.AuthService,
+) {
+	bases := v1.Group("/bases", authMiddleware)
+	bases.Get("/events", middleware.PermissionRequired(authSvc, "base.read"), eventsHandler.Stream)
+	bases.Post("/create",
+		middleware.PermissionRequired(authSvc, "base.create"),
+		baseHandler.CreateBase,
+	)
+	bases.Get("/get-all", middleware.PermissionRequired(authSvc, "base.read"), baseHandler.ListBases)
+	bases.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "base.read"), baseHandler.ListBasesDatatable)
+	bases.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "base.read"), baseHandler.GetBase)
+	bases.Patch("/update/:uuid",
+		middleware.PermissionRequired(authSvc, "base.update"),
+		baseHandler.UpdateBase,
+	)
+	bases.Delete("/delete/:uuid",
+		middleware.PermissionRequired(authSvc, "base.delete"),
+		baseHandler.DeleteBase,
+	)
+}
diff --git a/internal/app/api/routes_branding.go b/internal/app/api/routes_branding.go
new file mode 100644
index 0000000..d113b04
--- /dev/null
+++ b/internal/app/api/routes_branding.go
@@ -0,0 +1,20 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/transport/http/handlers"
+)
+
+func registerBrandingRoutes(v1 fiber.Router, brandingHandler *handlers.BrandingHandler) {
+	if brandingHandler == nil {
+		return
+	}
+	branding := v1.Group("/branding")
+	branding.Get("/logo", brandingHandler.GetLogo)
+	branding.Get("/login-cover", brandingHandler.GetLoginCover)
+	branding.Get("/login-content", brandingHandler.GetLoginContent)
+
+	publicBranding := v1.Group("/public/branding")
+	publicBranding.Get("/email-logo", brandingHandler.GetEmailLogo)
+}
diff --git a/internal/app/api/routes_complaint.go b/internal/app/api/routes_complaint.go
new file mode 100644
index 0000000..57c78f8
--- /dev/null
+++ b/internal/app/api/routes_complaint.go
@@ -0,0 +1,26 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerComplaintRoutes(v1 fiber.Router, h *handlers.ComplaintHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	complaints := v1.Group("/complaints", authMiddleware)
+	complaints.Post("/create", middleware.PermissionRequired(authSvc, "complaint.create"), h.Create)
+	complaints.Get("/get-all", middleware.PermissionRequired(authSvc, "complaint.read"), h.List)
+	complaints.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "complaint.read"), h.ListDatatable)
+	complaints.Get("/get-by-helicopter/:helicopter_id", middleware.PermissionRequired(authSvc, "complaint.read"), h.ListByHelicopter)
+	complaints.Get("/hold-items/get-all", middleware.PermissionRequired(authSvc, "complaint.read"), h.ListHoldItems)
+	complaints.Get("/hold-items/get-all/dt", middleware.PermissionRequired(authSvc, "complaint.read"), h.ListHoldItemsDatatable)
+	complaints.Get("/get/:id", middleware.PermissionRequired(authSvc, "complaint.read"), h.GetByID)
+	complaints.Patch("/update/:id", middleware.PermissionRequired(authSvc, "complaint.update"), h.Update)
+	complaints.Post("/action-taken/create/:id", middleware.PermissionRequired(authSvc, "complaint.update"), h.ActionTaken)
+	complaints.Patch("/action-taken/update/:id", middleware.PermissionRequired(authSvc, "complaint.update"), h.UpdateActionTaken)
+	complaints.Post("/nsr/sign/:id", middleware.PermissionRequired(authSvc, "complaint.nsr"), h.NSRSign)
+	complaints.Post("/nsr/unsign/:id", middleware.PermissionRequired(authSvc, "complaint.nsr"), h.NSRUnsign)
+	complaints.Delete("/delete/:id", middleware.PermissionRequired(authSvc, "complaint.delete"), h.Delete)
+}
diff --git a/internal/app/api/routes_contacts.go b/internal/app/api/routes_contacts.go
new file mode 100644
index 0000000..dc45659
--- /dev/null
+++ b/internal/app/api/routes_contacts.go
@@ -0,0 +1,26 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerContactRoutes(v1 fiber.Router, contactHandler *handlers.ContactHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	contacts := v1.Group("/contacts", authMiddleware)
+	contacts.Post("/create", middleware.PermissionRequired(authSvc, "user.create"), contactHandler.Create)
+	contacts.Get("/get-all", middleware.PermissionRequired(authSvc, "user.read"), contactHandler.List)
+	contacts.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "user.read"), contactHandler.ListDatatable)
+	contacts.Get("/:user_id", middleware.PermissionRequired(authSvc, "user.read"), contactHandler.Get)
+	contacts.Patch("/:user_id", middleware.PermissionRequired(authSvc, "user.update"), contactHandler.Update)
+	contacts.Delete("/:user_id", middleware.PermissionRequired(authSvc, "user.delete"), contactHandler.Delete)
+
+	contacts.Patch("/:user_id/status", middleware.PermissionRequired(authSvc, "user.update"), contactHandler.UpdateContactStatus)
+	contacts.Patch("/:user_id/role", middleware.PermissionRequired(authSvc, "user.update"), contactHandler.UpdateContactRole)
+	contacts.Patch("/:user_id/pilot-category", middleware.PermissionRequired(authSvc, "user.update"), contactHandler.UpdatePilotCategory)
+	contacts.Patch("/:user_id/license", middleware.PermissionRequired(authSvc, "user.update"), contactHandler.UpdateLicense)
+	contacts.Patch("/:user_id/chief-flags", middleware.PermissionRequired(authSvc, "user.update"), contactHandler.UpdateChiefFlags)
+	contacts.Post("/bulk-update", middleware.PermissionRequired(authSvc, "user.update"), contactHandler.BulkUpdate)
+}
diff --git a/internal/app/api/routes_dul.go b/internal/app/api/routes_dul.go
new file mode 100644
index 0000000..465049b
--- /dev/null
+++ b/internal/app/api/routes_dul.go
@@ -0,0 +1,26 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerDULRoutes(
+	v1 fiber.Router,
+	dulHandler *handlers.DULHandler,
+	eventsHandler *handlers.FileManagerEventsHandler,
+	authMiddleware fiber.Handler,
+	authSvc *service.AuthService,
+) {
+	dul := v1.Group("/dul", authMiddleware)
+	dul.Get("/events", middleware.PermissionRequired(authSvc, "dul.read"), eventsHandler.Stream)
+	dul.Post("/create", middleware.PermissionRequired(authSvc, "dul.create"), dulHandler.Create)
+	dul.Get("/get-all", middleware.PermissionRequired(authSvc, "dul.read"), dulHandler.List)
+	dul.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "dul.read"), dulHandler.ListDatatable)
+	dul.Get("/get/:id", middleware.PermissionRequired(authSvc, "dul.read"), dulHandler.Get)
+	dul.Patch("/update/:id", middleware.PermissionRequired(authSvc, "dul.update"), dulHandler.Update)
+	dul.Delete("/delete/:id", middleware.PermissionRequired(authSvc, "dul.delete"), dulHandler.Delete)
+}
diff --git a/internal/app/api/routes_duty_roster.go b/internal/app/api/routes_duty_roster.go
new file mode 100644
index 0000000..bb127b6
--- /dev/null
+++ b/internal/app/api/routes_duty_roster.go
@@ -0,0 +1,19 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerDutyRosterRoutes(v1 fiber.Router, rosterHandler *handlers.DutyRosterHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	dutyRosters := v1.Group("/duty-roster", authMiddleware)
+	dutyRosters.Post("/create", middleware.PermissionRequired(authSvc, "duty_roster.create"), rosterHandler.CreateAny)
+	dutyRosters.Get("/get-all", middleware.PermissionRequired(authSvc, "duty_roster.read"), rosterHandler.GetAllRosters)
+	dutyRosters.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "duty_roster.read"), rosterHandler.ListAnyDatatable)
+	dutyRosters.Patch("/update", middleware.PermissionRequired(authSvc, "duty_roster.update"), rosterHandler.UpdateAny)
+	dutyRosters.Delete("/delete", middleware.PermissionRequired(authSvc, "duty_roster.delete"), rosterHandler.DeleteAny)
+	dutyRosters.Delete("/crew", middleware.PermissionRequired(authSvc, "duty_roster.delete"), rosterHandler.DeleteAnyCrew)
+}
diff --git a/internal/app/api/routes_easa_release.go b/internal/app/api/routes_easa_release.go
new file mode 100644
index 0000000..dbcef64
--- /dev/null
+++ b/internal/app/api/routes_easa_release.go
@@ -0,0 +1,21 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerEASAReleaseRoutes(v1 fiber.Router, h *handlers.EASAReleaseHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	g := v1.Group("/easa-releases", authMiddleware)
+	g.Post("/create", middleware.PermissionRequired(authSvc, "easa_release.create"), h.Create)
+	g.Get("/get-by-helicopter/:helicopter_id", middleware.PermissionRequired(authSvc, "easa_release.read"), h.ListByHelicopter)
+	g.Get("/get-by-flight/:flight_id", middleware.PermissionRequired(authSvc, "easa_release.read"), h.GetByFlight)
+	g.Get("/get-by-complaint/:complaint_id", middleware.PermissionRequired(authSvc, "easa_release.read"), h.GetByComplaint)
+	g.Get("/get/:id", middleware.PermissionRequired(authSvc, "easa_release.read"), h.GetByID)
+	g.Patch("/update/:id", middleware.PermissionRequired(authSvc, "easa_release.update"), h.Update)
+	g.Post("/sign/:id", middleware.PermissionRequired(authSvc, "easa_release.sign"), h.Sign)
+	g.Delete("/delete/:id", middleware.PermissionRequired(authSvc, "easa_release.delete"), h.Delete)
+}
diff --git a/internal/app/api/routes_facility.go b/internal/app/api/routes_facility.go
new file mode 100644
index 0000000..4364f99
--- /dev/null
+++ b/internal/app/api/routes_facility.go
@@ -0,0 +1,19 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerFacilityRoutes(v1 fiber.Router, facilityHandler *handlers.FacilityHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	facilities := v1.Group("/facilities", authMiddleware)
+	facilities.Post("/create", middleware.PermissionRequired(authSvc, "facility.create"), facilityHandler.Create)
+	facilities.Get("/get-all", middleware.PermissionRequired(authSvc, "facility.read"), facilityHandler.List)
+	facilities.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "facility.read"), facilityHandler.ListDatatable)
+	facilities.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "facility.read"), facilityHandler.Get)
+	facilities.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "facility.update"), facilityHandler.Update)
+	facilities.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "facility.delete"), facilityHandler.Delete)
+}
diff --git a/internal/app/api/routes_federal_state.go b/internal/app/api/routes_federal_state.go
new file mode 100644
index 0000000..731dc89
--- /dev/null
+++ b/internal/app/api/routes_federal_state.go
@@ -0,0 +1,18 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerFederalStateRoutes(v1 fiber.Router, federalStateHandler *handlers.FederalStateHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	federalState := v1.Group("/federal-state", authMiddleware)
+	federalState.Post("/create", middleware.PermissionRequired(authSvc, "federal_state.create"), federalStateHandler.Create)
+	federalState.Get("/get-all", middleware.PermissionRequired(authSvc, "federal_state.read"), federalStateHandler.List)
+	federalState.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "federal_state.read"), federalStateHandler.ListDatatable)
+	federalState.Patch("/update/:id", middleware.PermissionRequired(authSvc, "federal_state.update"), federalStateHandler.Update)
+	federalState.Delete("/delete/:id", middleware.PermissionRequired(authSvc, "federal_state.delete"), federalStateHandler.Delete)
+}
diff --git a/internal/app/api/routes_file_manager.go b/internal/app/api/routes_file_manager.go
new file mode 100644
index 0000000..b9933ef
--- /dev/null
+++ b/internal/app/api/routes_file_manager.go
@@ -0,0 +1,62 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerFileManagerRoutes(
+	v1 fiber.Router,
+	folderHandler *handlers.FileManagerFolderHandler,
+	fileHandler *handlers.FileManagerFileHandler,
+	attachmentHandler *handlers.FileManagerAttachmentHandler,
+	eventsHandler *handlers.FileManagerEventsHandler,
+	authMiddleware fiber.Handler,
+	authSvc *service.AuthService,
+) {
+	fm := v1.Group("/file-manager", authMiddleware)
+	fm.Get("/get-all", middleware.PermissionRequired(authSvc, "file_manager.read"), folderHandler.ListAll)
+	fm.Get("/events", middleware.PermissionRequired(authSvc, "file_manager.read"), eventsHandler.Stream)
+	fm.Get("/trash/get-all", middleware.PermissionRequired(authSvc, "file_manager.read"), folderHandler.ListTrashItems)
+	fm.Patch("/move", middleware.PermissionRequired(authSvc, "file_manager.update"), folderHandler.MoveNodes)
+	fm.Delete("/delete", middleware.PermissionRequired(authSvc, "file_manager.delete"), folderHandler.DeleteNodesBulk)
+	fm.Patch("/restore", middleware.PermissionRequired(authSvc, "file_manager.update"), folderHandler.RestoreNodesBulk)
+	fm.Delete("/purge-delete", middleware.PermissionRequired(authSvc, "file_manager.delete"), folderHandler.PurgeNodesBulk)
+
+	folders := fm.Group("/folders")
+	folders.Post("/create", middleware.PermissionRequired(authSvc, "file_manager.create"), folderHandler.CreateFolder)
+	folders.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "file_manager.read"), folderHandler.GetFolder)
+	folders.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "file_manager.update"), folderHandler.UpdateFolder)
+
+	files := fm.Group("/files")
+	files.Post("/create", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.CreateFile)
+	files.Post("/create-from-template", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.CreateFromTemplate)
+	files.Post("/create-aircraft-image", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.CreateAircraftImage)
+	files.Post("/create-base-image", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.CreateBaseImage)
+	files.Post("/create-dul-image", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.CreateDULImage)
+	files.Post("/create-user-image", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.CreateUserImage)
+	files.Post("/create-takeover-file", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.CreateTakeoverFile)
+	files.Get("/:fileId/edit-session", middleware.PermissionRequired(authSvc, "file_manager.read"), fileHandler.EditSession)
+	files.Post("/create-mission-file", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.CreateMissionFile)
+	files.Post("/upload", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.UploadFile)
+	files.Post("/upload-aircraft-image", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.UploadAircraftImage)
+	files.Post("/upload-base-image", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.UploadBaseImage)
+	files.Post("/upload-dul-image", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.UploadDULImage)
+	files.Post("/upload-user-image", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.UploadUserImage)
+	files.Post("/upload-takeover-file", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.UploadTakeoverFile)
+	files.Post("/upload-mission-file", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.UploadMissionFile)
+	files.Post("/upload-fleet-status-file", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.UploadFleetStatusFile)
+	files.Post("/create-fleet-status-file", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.CreateFleetStatusFile)
+	files.Delete("/cancel-upload", middleware.PermissionRequired(authSvc, "file_manager.create"), fileHandler.CancelUpload)
+	files.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "file_manager.read"), fileHandler.GetFile)
+	files.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "file_manager.update"), fileHandler.UpdateFile)
+
+	attachments := fm.Group("/attachments")
+	attachments.Post("/create", middleware.PermissionRequired(authSvc, "file_manager.create"), attachmentHandler.CreateAttachment)
+	attachments.Get("/get-all", middleware.PermissionRequired(authSvc, "file_manager.read"), attachmentHandler.ListAttachments)
+	attachments.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "file_manager.read"), attachmentHandler.GetAttachment)
+	attachments.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "file_manager.delete"), attachmentHandler.DeleteAttachment)
+}
diff --git a/internal/app/api/routes_fleet_status.go b/internal/app/api/routes_fleet_status.go
new file mode 100644
index 0000000..3fdef3f
--- /dev/null
+++ b/internal/app/api/routes_fleet_status.go
@@ -0,0 +1,22 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerFleetStatusRoutes(v1 fiber.Router, h *handlers.FleetStatusHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	g := v1.Group("/fleet-status", authMiddleware)
+	g.Post("/create", middleware.PermissionRequired(authSvc, "flight.create"), h.Create)
+	g.Get("/get/:id", middleware.PermissionRequired(authSvc, "flight.read"), h.GetByID)
+	g.Get("/get-by-helicopter/:helicopter_id", middleware.PermissionRequired(authSvc, "flight.read"), h.GetByHelicopterID)
+	g.Get("/get-all", middleware.PermissionRequired(authSvc, "flight.read"), h.List)
+	g.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "flight.read"), h.ListDatatable)
+	g.Get("/history/:helicopter_id", middleware.PermissionRequired(authSvc, "flight.read"), h.ListHistoryByHelicopter)
+	g.Post("/mark-serviced/:id", middleware.PermissionRequired(authSvc, "flight.update"), h.MarkServiced)
+	g.Patch("/update/:id", middleware.PermissionRequired(authSvc, "flight.update"), h.Update)
+	g.Delete("/delete/:id", middleware.PermissionRequired(authSvc, "flight.delete"), h.Delete)
+}
diff --git a/internal/app/api/routes_flight.go b/internal/app/api/routes_flight.go
new file mode 100644
index 0000000..36e9108
--- /dev/null
+++ b/internal/app/api/routes_flight.go
@@ -0,0 +1,15 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerFlightRoutes(v1 fiber.Router, flightHandler *handlers.FlightHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	flights := v1.Group("/flights", authMiddleware)
+	flights.Get("/get-all", middleware.PermissionRequired(authSvc, "flight.read"), flightHandler.List)
+	flights.Get("/get", middleware.PermissionRequired(authSvc, "flight.read"), flightHandler.GetByAuthUser)
+}
diff --git a/internal/app/api/routes_flight_data.go b/internal/app/api/routes_flight_data.go
new file mode 100644
index 0000000..ca45a24
--- /dev/null
+++ b/internal/app/api/routes_flight_data.go
@@ -0,0 +1,24 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerFlightDataRoutes(v1 fiber.Router, flightDataHandler *handlers.FlightDataHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	flightData := v1.Group("/flight-data", authMiddleware)
+	flightData.Post("/create", middleware.PermissionRequired(authSvc, "flight.create"), flightDataHandler.Create)
+	flightData.Get("/get/:id", middleware.PermissionRequired(authSvc, "flight.read"), flightDataHandler.Get)
+	flightData.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "flight.read"), flightDataHandler.Get)
+	flightData.Get("/get-all", middleware.PermissionRequired(authSvc, "flight.read"), flightDataHandler.List)
+	flightData.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "flight.read"), flightDataHandler.ListDatatable)
+	flightData.Patch("/update/:id", middleware.PermissionRequired(authSvc, "flight.update"), flightDataHandler.Update)
+	flightData.Delete("/delete/:id", middleware.PermissionRequired(authSvc, "flight.delete"), flightDataHandler.Delete)
+
+	flightsData := v1.Group("/flights-data", authMiddleware)
+	flightsData.Get("/get-all", middleware.PermissionRequired(authSvc, "flight.read"), flightDataHandler.List)
+	flightsData.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "flight.read"), flightDataHandler.ListDatatable)
+}
diff --git a/internal/app/api/routes_fm_report.go b/internal/app/api/routes_fm_report.go
new file mode 100644
index 0000000..3fbd158
--- /dev/null
+++ b/internal/app/api/routes_fm_report.go
@@ -0,0 +1,22 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerFMReportRoutes(v1 fiber.Router, fmReportHandler *handlers.FMReportHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	fmReports := v1.Group("/fm-reports", authMiddleware)
+	fmReports.Get("/get-all", middleware.PermissionRequired(authSvc, "flight.read"), fmReportHandler.List)
+	fmReports.Get("/get/:flight_id", middleware.PermissionRequired(authSvc, "flight.read"), fmReportHandler.GetByFlightID)
+	fmReports.Patch("/update/:flight_id", middleware.PermissionRequired(authSvc, "flight.update"), fmReportHandler.UpdateByFlightID)
+	fmReports.Post("/complete/:flight_id", middleware.PermissionRequired(authSvc, "flight.complete"), fmReportHandler.Complete)
+	fmReports.Post("/:id/attachments/upload-intent", middleware.PermissionRequired(authSvc, "flight.update"), fmReportHandler.RequestAttachmentUploadIntent)
+	fmReports.Post("/:id/attachments", middleware.PermissionRequired(authSvc, "flight.update"), fmReportHandler.UploadAttachment)
+	fmReports.Delete("/:id/attachments/:att_id", middleware.PermissionRequired(authSvc, "flight.update"), fmReportHandler.DeleteAttachment)
+	fmReports.Delete("/:id", middleware.PermissionRequired(authSvc, "flight.delete"), middleware.PinRequired(authSvc, sharedconst.PinActionFmReportDelete), fmReportHandler.Delete)
+}
diff --git a/internal/app/api/routes_forces_present.go b/internal/app/api/routes_forces_present.go
new file mode 100644
index 0000000..5b6e3df
--- /dev/null
+++ b/internal/app/api/routes_forces_present.go
@@ -0,0 +1,18 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerForcesPresentRoutes(v1 fiber.Router, forcesPresentHandler *handlers.ForcesPresentHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	forcesPresent := v1.Group("/forces-present", authMiddleware)
+	forcesPresent.Post("/create", middleware.PermissionRequired(authSvc, "forces_present.create"), forcesPresentHandler.Create)
+	forcesPresent.Get("/get-all", middleware.PermissionRequired(authSvc, "forces_present.read"), forcesPresentHandler.List)
+	forcesPresent.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "forces_present.read"), forcesPresentHandler.ListDatatable)
+	forcesPresent.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "forces_present.update"), forcesPresentHandler.Update)
+	forcesPresent.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "forces_present.delete"), forcesPresentHandler.Delete)
+}
diff --git a/internal/app/api/routes_health_insurance_companies.go b/internal/app/api/routes_health_insurance_companies.go
new file mode 100644
index 0000000..4a043a9
--- /dev/null
+++ b/internal/app/api/routes_health_insurance_companies.go
@@ -0,0 +1,18 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerHealthInsuranceCompaniesRoutes(v1 fiber.Router, healthInsuranceCompaniesHandler *handlers.HealthInsuranceCompaniesHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	hic := v1.Group("/health-insurance-companies", authMiddleware)
+	hic.Post("/create", middleware.PermissionRequired(authSvc, "health_insurance_companies.create"), healthInsuranceCompaniesHandler.Create)
+	hic.Get("/get-all", middleware.PermissionRequired(authSvc, "health_insurance_companies.read"), healthInsuranceCompaniesHandler.List)
+	hic.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "health_insurance_companies.read"), healthInsuranceCompaniesHandler.ListDatatable)
+	hic.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "health_insurance_companies.update"), healthInsuranceCompaniesHandler.Update)
+	hic.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "health_insurance_companies.delete"), healthInsuranceCompaniesHandler.Delete)
+}
diff --git a/internal/app/api/routes_helicopter.go b/internal/app/api/routes_helicopter.go
new file mode 100644
index 0000000..02a695a
--- /dev/null
+++ b/internal/app/api/routes_helicopter.go
@@ -0,0 +1,20 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerHelicopterRoutes(v1 fiber.Router, helicopterHandler *handlers.HelicopterHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	helicopters := v1.Group("/helicopters", authMiddleware)
+	helicopters.Post("/create", middleware.PermissionRequired(authSvc, "helicopter.create"), helicopterHandler.Create)
+	helicopters.Post("/:id/reports/next-number", middleware.PermissionRequired(authSvc, "helicopter.report.generate"), helicopterHandler.NextReportNumber)
+	helicopters.Get("/get-all", middleware.PermissionRequired(authSvc, "helicopter.read"), helicopterHandler.List)
+	helicopters.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "helicopter.read"), helicopterHandler.ListDatatable)
+	helicopters.Get("/get/:id", middleware.PermissionRequired(authSvc, "helicopter.read"), helicopterHandler.Get)
+	helicopters.Patch("/update/:id", middleware.PermissionRequired(authSvc, "helicopter.update"), helicopterHandler.Update)
+	helicopters.Delete("/delete/:id", middleware.PermissionRequired(authSvc, "helicopter.delete"), helicopterHandler.Delete)
+}
diff --git a/internal/app/api/routes_helicopter_file.go b/internal/app/api/routes_helicopter_file.go
new file mode 100644
index 0000000..3582c3a
--- /dev/null
+++ b/internal/app/api/routes_helicopter_file.go
@@ -0,0 +1,27 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerHelicopterFileRoutes(
+	v1 fiber.Router,
+	handler *handlers.HelicopterFileHandler,
+	eventsHandler *handlers.HelicopterFileEventsHandler,
+	authMiddleware fiber.Handler,
+	authSvc *service.AuthService,
+) {
+	files := v1.Group("/helicopter-files", authMiddleware)
+	files.Get("/events", middleware.PermissionRequired(authSvc, "helicopter.read"), eventsHandler.Stream)
+	files.Post("/upload", middleware.PermissionRequired(authSvc, "helicopter.update"), handler.Upload)
+	files.Post("/cancel-upload", middleware.PermissionRequired(authSvc, "helicopter.update"), handler.CancelUpload)
+	files.Post("/create", middleware.PermissionRequired(authSvc, "helicopter.update"), handler.Create)
+	files.Get("/get-all", middleware.PermissionRequired(authSvc, "helicopter.read"), handler.List)
+	files.Get("/get/:helicopter_id", middleware.PermissionRequired(authSvc, "helicopter.read"), handler.Get)
+	files.Patch("/update", middleware.PermissionRequired(authSvc, "helicopter.update"), handler.Update)
+	files.Delete("/delete", middleware.PermissionRequired(authSvc, "helicopter.delete"), handler.Delete)
+}
diff --git a/internal/app/api/routes_helicopter_usage.go b/internal/app/api/routes_helicopter_usage.go
new file mode 100644
index 0000000..b0eac8f
--- /dev/null
+++ b/internal/app/api/routes_helicopter_usage.go
@@ -0,0 +1,19 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerHelicopterUsageRoutes(v1 fiber.Router, helicopterUsageHandler *handlers.HelicopterUsageHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	helicopterUsage := v1.Group("/helicopter-usage", authMiddleware)
+	helicopterUsage.Post("/create", middleware.PermissionRequired(authSvc, "helicopter_usage.create"), helicopterUsageHandler.Create)
+	helicopterUsage.Get("/get-all", middleware.PermissionRequired(authSvc, "helicopter_usage.read"), helicopterUsageHandler.List)
+	helicopterUsage.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "helicopter_usage.read"), helicopterUsageHandler.ListDatatable)
+	helicopterUsage.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "helicopter_usage.read"), helicopterUsageHandler.Get)
+	helicopterUsage.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "helicopter_usage.update"), helicopterUsageHandler.Update)
+	helicopterUsage.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "helicopter_usage.delete"), helicopterUsageHandler.Delete)
+}
diff --git a/internal/app/api/routes_hems_operation.go b/internal/app/api/routes_hems_operation.go
new file mode 100644
index 0000000..c797faf
--- /dev/null
+++ b/internal/app/api/routes_hems_operation.go
@@ -0,0 +1,19 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerHEMSOperationRoutes(v1 fiber.Router, h *handlers.HEMSOperationHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	r := v1.Group("/hems-operation", authMiddleware)
+	r.Post("/create", middleware.PermissionRequired(authSvc, "hems_operation.create"), h.Create)
+	r.Get("/get-all", middleware.PermissionRequired(authSvc, "hems_operation.read"), h.List)
+	r.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "hems_operation.read"), h.ListDatatable)
+	r.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "hems_operation.read"), h.Get)
+	r.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "hems_operation.update"), h.Update)
+	r.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "hems_operation.delete"), h.Delete)
+}
diff --git a/internal/app/api/routes_hems_operation_category.go b/internal/app/api/routes_hems_operation_category.go
new file mode 100644
index 0000000..a6322d3
--- /dev/null
+++ b/internal/app/api/routes_hems_operation_category.go
@@ -0,0 +1,19 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerHEMSOperationCategoryRoutes(v1 fiber.Router, h *handlers.HEMSOperationCategoryHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	r := v1.Group("/hems-operation-category", authMiddleware)
+	r.Post("/create", middleware.PermissionRequired(authSvc, "operation_category.create"), h.Create)
+	r.Get("/get-all", middleware.PermissionRequired(authSvc, "operation_category.read"), h.List)
+	r.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "operation_category.read"), h.ListDatatable)
+	r.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "operation_category.read"), h.Get)
+	r.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "operation_category.update"), h.Update)
+	r.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "operation_category.delete"), h.Delete)
+}
diff --git a/internal/app/api/routes_hems_operational_data.go b/internal/app/api/routes_hems_operational_data.go
new file mode 100644
index 0000000..b020a6b
--- /dev/null
+++ b/internal/app/api/routes_hems_operational_data.go
@@ -0,0 +1,19 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerHEMSOperationalDataRoutes(v1 fiber.Router, h *handlers.HEMSOperationalDataHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	r := v1.Group("/hems-operational-data", authMiddleware)
+	r.Post("/create", middleware.PermissionRequired(authSvc, "operation.create"), h.Create)
+	r.Get("/get-all", middleware.PermissionRequired(authSvc, "operation.read"), h.List)
+	r.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "operation.read"), h.ListDatatable)
+	r.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "operation.read"), h.Get)
+	r.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "operation.update"), h.Update)
+	r.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "operation.delete"), h.Delete)
+}
diff --git a/internal/app/api/routes_hospital.go b/internal/app/api/routes_hospital.go
new file mode 100644
index 0000000..61963d4
--- /dev/null
+++ b/internal/app/api/routes_hospital.go
@@ -0,0 +1,18 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerHospitalRoutes(v1 fiber.Router, hospitalHandler *handlers.HospitalHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	hospital := v1.Group("/hospital", authMiddleware)
+	hospital.Post("/create", middleware.PermissionRequired(authSvc, "no_icao_code.create"), hospitalHandler.Create)
+	hospital.Get("/get-all", middleware.PermissionRequired(authSvc, "no_icao_code.read"), hospitalHandler.List)
+	hospital.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "no_icao_code.read"), hospitalHandler.ListDatatable)
+	hospital.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "no_icao_code.update"), hospitalHandler.Update)
+	hospital.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "no_icao_code.delete"), hospitalHandler.Delete)
+}
diff --git a/internal/app/api/routes_icao.go b/internal/app/api/routes_icao.go
new file mode 100644
index 0000000..5400b4d
--- /dev/null
+++ b/internal/app/api/routes_icao.go
@@ -0,0 +1,18 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerICAORoutes(v1 fiber.Router, icaoHandler *handlers.ICAOHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	icao := v1.Group("/icao", authMiddleware)
+	icao.Post("/create", middleware.PermissionRequired(authSvc, "icao.create"), icaoHandler.Create)
+	icao.Get("/get-all", middleware.PermissionRequired(authSvc, "icao.read"), icaoHandler.List)
+	icao.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "icao.read"), icaoHandler.ListDatatable)
+	icao.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "icao.update"), icaoHandler.Update)
+	icao.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "icao.delete"), icaoHandler.Delete)
+}
diff --git a/internal/app/api/routes_land.go b/internal/app/api/routes_land.go
new file mode 100644
index 0000000..b27cdc6
--- /dev/null
+++ b/internal/app/api/routes_land.go
@@ -0,0 +1,18 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerLandRoutes(v1 fiber.Router, landHandler *handlers.LandHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	land := v1.Group("/land", authMiddleware)
+	land.Post("/create", middleware.PermissionRequired(authSvc, "country.create"), landHandler.Create)
+	land.Get("/get-all", middleware.PermissionRequired(authSvc, "country.read"), landHandler.List)
+	land.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "country.read"), landHandler.ListDatatable)
+	land.Patch("/update/:id", middleware.PermissionRequired(authSvc, "country.update"), landHandler.Update)
+	land.Delete("/delete/:id", middleware.PermissionRequired(authSvc, "country.delete"), landHandler.Delete)
+}
diff --git a/internal/app/api/routes_last_flights_inspection.go b/internal/app/api/routes_last_flights_inspection.go
new file mode 100644
index 0000000..2cbcc35
--- /dev/null
+++ b/internal/app/api/routes_last_flights_inspection.go
@@ -0,0 +1,17 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerLastFlightsInspectionRoutes(v1 fiber.Router, reserveAcHandler *handlers.ReserveAcHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	lastFlightsInspection := v1.Group("/after-flight-inspection", authMiddleware)
+	lastFlightsInspection.Get("/get", middleware.PermissionRequired(authSvc, "after_flight.read"), reserveAcHandler.GetLastFlightsInspection)
+	lastFlightsInspection.Post("/create", middleware.PermissionRequired(authSvc, "after_flight.create"), reserveAcHandler.CreateLastFlightsInspection)
+	lastFlightsInspection.Patch("/update", middleware.PermissionRequired(authSvc, "after_flight.update"), reserveAcHandler.UpdateLastFlightsInspection)
+	lastFlightsInspection.Delete("/delete", middleware.PermissionRequired(authSvc, "after_flight.delete"), reserveAcHandler.DeleteLastFlightsInspection)
+}
diff --git a/internal/app/api/routes_master_settings.go b/internal/app/api/routes_master_settings.go
new file mode 100644
index 0000000..25d3a82
--- /dev/null
+++ b/internal/app/api/routes_master_settings.go
@@ -0,0 +1,21 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerMasterSettingsRoutes(v1 fiber.Router, masterSettingsHandler *handlers.MasterSettingsHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	masterSettingsPublic := v1.Group("/master-settings")
+	masterSettingsPublic.Get("/get", masterSettingsHandler.Get)
+
+	masterSettings := v1.Group("/master-settings", authMiddleware)
+	masterSettings.Post("/create", middleware.PermissionRequired(authSvc, "master_settings.create"), masterSettingsHandler.Create)
+	masterSettings.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "master_settings.update"), masterSettingsHandler.Update)
+	masterSettings.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "master_settings.delete"), masterSettingsHandler.Delete)
+	masterSettings.Get("/sso/microsoft", middleware.PermissionRequired(authSvc, "master_settings.update"), masterSettingsHandler.GetMicrosoftEntraSSO)
+	masterSettings.Put("/sso/microsoft", middleware.PermissionRequired(authSvc, "master_settings.update"), masterSettingsHandler.UpsertMicrosoftEntraSSO)
+}
diff --git a/internal/app/api/routes_mcf.go b/internal/app/api/routes_mcf.go
new file mode 100644
index 0000000..b7d15ca
--- /dev/null
+++ b/internal/app/api/routes_mcf.go
@@ -0,0 +1,17 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerMCFRoutes(v1 fiber.Router, h *handlers.MCFHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	g := v1.Group("/mcf", authMiddleware)
+	g.Post("/set/:helicopter_id", middleware.PermissionRequired(authSvc, "mcf.create"), h.Set)
+	g.Get("/get-by-helicopter/:helicopter_id", middleware.PermissionRequired(authSvc, "mcf.read"), h.ListByHelicopter)
+	g.Get("/get/:id", middleware.PermissionRequired(authSvc, "mcf.read"), h.GetByID)
+	g.Post("/sign/:id", middleware.PermissionRequired(authSvc, "mcf.complete"), h.Sign)
+}
diff --git a/internal/app/api/routes_medicine.go b/internal/app/api/routes_medicine.go
new file mode 100644
index 0000000..2b9f629
--- /dev/null
+++ b/internal/app/api/routes_medicine.go
@@ -0,0 +1,32 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerMedicineRoutes(v1 fiber.Router, medicineHandler *handlers.MedicineHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	medicine := v1.Group("/medicine", authMiddleware)
+	medicine.Post("/create", middleware.PermissionRequired(authSvc, "medicine.create"), medicineHandler.Create)
+	medicine.Get("/get-all", middleware.PermissionRequired(authSvc, "medicine.read"), medicineHandler.List)
+	medicine.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "medicine.read"), medicineHandler.ListDatatable)
+	medicine.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "medicine.update"), medicineHandler.Update)
+	medicine.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "medicine.delete"), medicineHandler.Delete)
+
+	medicineGroup := v1.Group("/medicine-group", authMiddleware)
+	medicineGroup.Post("/create", middleware.PermissionRequired(authSvc, "medicine.create"), medicineHandler.CreateGroup)
+	medicineGroup.Get("/get-all", middleware.PermissionRequired(authSvc, "medicine.read"), medicineHandler.ListGroups)
+	medicineGroup.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "medicine.read"), medicineHandler.ListGroupsDatatable)
+	medicineGroup.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "medicine.update"), medicineHandler.UpdateGroup)
+	medicineGroup.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "medicine.delete"), medicineHandler.DeleteGroup)
+
+	motorReaction := v1.Group("/motor-reaction", authMiddleware)
+	motorReaction.Post("/create", middleware.PermissionRequired(authSvc, "medicine.create"), medicineHandler.CreateReaction)
+	motorReaction.Get("/get-all", middleware.PermissionRequired(authSvc, "medicine.read"), medicineHandler.ListReactions)
+	motorReaction.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "medicine.read"), medicineHandler.ListReactionsDatatable)
+	motorReaction.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "medicine.update"), medicineHandler.UpdateReaction)
+	motorReaction.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "medicine.delete"), medicineHandler.DeleteReaction)
+}
diff --git a/internal/app/api/routes_mission.go b/internal/app/api/routes_mission.go
new file mode 100644
index 0000000..283d410
--- /dev/null
+++ b/internal/app/api/routes_mission.go
@@ -0,0 +1,26 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerMissionRoutes(v1 fiber.Router, missionHandler *handlers.MissionHandler, eventsHandler *handlers.FileManagerEventsHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	mission := v1.Group("/mission", authMiddleware)
+	mission.Get("/events", middleware.PermissionRequired(authSvc, "flight.read"), eventsHandler.Stream)
+	mission.Post("/create", middleware.PermissionRequired(authSvc, "flight.create"), missionHandler.Create)
+	mission.Patch("/update/:mission_id", middleware.PermissionRequired(authSvc, "flight.update"), missionHandler.Update)
+	mission.Delete("/file/:mission_id/:attachment_id", middleware.PermissionRequired(authSvc, "flight.update"), missionHandler.RemoveFile)
+	mission.Delete("/delete/:flight_id", middleware.PermissionRequired(authSvc, "flight.delete"), missionHandler.Delete)
+	mission.Delete("/delete-by-id/:mission_id", middleware.PermissionRequired(authSvc, "flight.delete"), missionHandler.DeleteByID)
+	mission.Get("/get/:flight_id", middleware.PermissionRequired(authSvc, "flight.read"), missionHandler.GetByFlightID)
+	mission.Get("/get-all", middleware.PermissionRequired(authSvc, "flight.read"), missionHandler.List)
+	mission.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "flight.read"), missionHandler.ListDatatable)
+
+	missionType := v1.Group("/mission-type", authMiddleware)
+	missionType.Post("/create", middleware.PermissionRequired(authSvc, "flight.create"), missionHandler.CreateType)
+	missionType.Get("/get-all", middleware.PermissionRequired(authSvc, "flight.read"), missionHandler.ListTypes)
+}
diff --git a/internal/app/api/routes_opc.go b/internal/app/api/routes_opc.go
new file mode 100644
index 0000000..dff78b8
--- /dev/null
+++ b/internal/app/api/routes_opc.go
@@ -0,0 +1,18 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerOpcRoutes(v1 fiber.Router, opcHandler *handlers.OpcHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	opc := v1.Group("/opc", authMiddleware)
+	opc.Post("/create", middleware.PermissionRequired(authSvc, "opc.create"), opcHandler.Create)
+	opc.Get("/get-all", middleware.PermissionRequired(authSvc, "opc.read"), opcHandler.List)
+	opc.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "opc.read"), opcHandler.ListDatatable)
+	opc.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "opc.update"), opcHandler.Update)
+	opc.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "opc.delete"), opcHandler.Delete)
+}
diff --git a/internal/app/api/routes_other_person.go b/internal/app/api/routes_other_person.go
new file mode 100644
index 0000000..9a54b52
--- /dev/null
+++ b/internal/app/api/routes_other_person.go
@@ -0,0 +1,20 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+// registerOtherPersonRoutes exposes the reusable, NON-STAFF "other person" master under
+// /contact/other. It is kept separate from /contacts (staff) and /takeovers on purpose.
+func registerOtherPersonRoutes(v1 fiber.Router, otherPersonHandler *handlers.OtherPersonHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	other := v1.Group("/contact/other", authMiddleware)
+	other.Get("/", middleware.PermissionRequired(authSvc, "reserve_ac.read"), otherPersonHandler.Search)
+	other.Get("/get/:id", middleware.PermissionRequired(authSvc, "reserve_ac.read"), otherPersonHandler.Get)
+	other.Post("/create", middleware.PermissionRequired(authSvc, "reserve_ac.create"), otherPersonHandler.Create)
+	other.Patch("/update/:id", middleware.PermissionRequired(authSvc, "reserve_ac.update"), otherPersonHandler.Update)
+	other.Delete("/delete/:id", middleware.PermissionRequired(authSvc, "reserve_ac.delete"), otherPersonHandler.Delete)
+}
diff --git a/internal/app/api/routes_patient_data.go b/internal/app/api/routes_patient_data.go
new file mode 100644
index 0000000..8aaa942
--- /dev/null
+++ b/internal/app/api/routes_patient_data.go
@@ -0,0 +1,29 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerInsurancePatientDataRoutes(v1 fiber.Router, h *handlers.InsurancePatientDataHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	g := v1.Group("/insurance-patient-data", authMiddleware)
+	g.Post("/create", middleware.PermissionRequired(authSvc, "insurance_patient_data.create"), h.Create)
+	g.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "insurance_patient_data.read"), h.Get)
+	g.Get("/get-all", middleware.PermissionRequired(authSvc, "insurance_patient_data.read"), h.List)
+	g.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "insurance_patient_data.read"), h.ListDatatable)
+	g.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "insurance_patient_data.update"), h.Update)
+	g.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "insurance_patient_data.delete"), h.Delete)
+}
+
+func registerPatientDataRoutes(v1 fiber.Router, h *handlers.PatientDataHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	g := v1.Group("/patient-data", authMiddleware)
+	g.Post("/create", middleware.PermissionRequired(authSvc, "patient_data.create"), h.Create)
+	g.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "patient_data.read"), h.Get)
+	g.Get("/get-all", middleware.PermissionRequired(authSvc, "patient_data.read"), h.List)
+	g.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "patient_data.read"), h.ListDatatable)
+	g.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "patient_data.update"), h.Update)
+	g.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "patient_data.delete"), h.Delete)
+}
diff --git a/internal/app/api/routes_reserve_ac.go b/internal/app/api/routes_reserve_ac.go
new file mode 100644
index 0000000..9af01fd
--- /dev/null
+++ b/internal/app/api/routes_reserve_ac.go
@@ -0,0 +1,20 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerReserveAcRoutes(v1 fiber.Router, reserveAcHandler *handlers.ReserveAcHandler, takeoverHandler *handlers.TakeoverHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	reserveAcs := v1.Group("/reserve-acs", authMiddleware)
+	reserveAcs.Post("/takeovers/create", middleware.PermissionRequired(authSvc, "reserve_ac.create"), takeoverHandler.CreateTakeover)
+	reserveAcs.Post("/create", middleware.PermissionRequired(authSvc, "reserve_ac.create"), reserveAcHandler.Create)
+	reserveAcs.Get("/get-all", middleware.PermissionRequired(authSvc, "reserve_ac.read"), reserveAcHandler.List)
+	reserveAcs.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "reserve_ac.read"), reserveAcHandler.ListDatatable)
+	reserveAcs.Get("/get/:id", middleware.PermissionRequired(authSvc, "reserve_ac.read"), reserveAcHandler.Get)
+	reserveAcs.Patch("/update", middleware.PermissionRequired(authSvc, "reserve_ac.update"), reserveAcHandler.Update)
+	reserveAcs.Delete("/delete", middleware.PermissionRequired(authSvc, "reserve_ac.delete"), reserveAcHandler.Delete)
+}
diff --git a/internal/app/api/routes_role.go b/internal/app/api/routes_role.go
new file mode 100644
index 0000000..f583fd2
--- /dev/null
+++ b/internal/app/api/routes_role.go
@@ -0,0 +1,26 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerRoleRoutes(v1 fiber.Router, roleHandler *handlers.RoleHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	roles := v1.Group("/roles", authMiddleware)
+	roles.Post("/create", middleware.PermissionRequired(authSvc, "role.create"), roleHandler.Create)
+	roles.Get("/get-all", middleware.PermissionRequired(authSvc, "role.read"), roleHandler.List)
+	roles.Get("/permissions/get-all", middleware.PermissionRequired(authSvc, "role.permission.read"), roleHandler.ListPermissions)
+	roles.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "role.read"), roleHandler.ListDatatable)
+	roles.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "role.read"), roleHandler.GetByID)
+	roles.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "role.update"), roleHandler.Update)
+	roles.Patch("/permissions/:permission_uuid", middleware.PermissionRequired(authSvc, "role.permission.update"), roleHandler.UpdatePermission)
+	roles.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "role.delete"), roleHandler.Delete)
+	roles.Get("/:uuid/permissions", middleware.PermissionRequired(authSvc, "role.permission.read"), roleHandler.ListRolePermissions)
+	roles.Post("/:uuid/permissions", middleware.PermissionRequired(authSvc, "role.permission.assign"), roleHandler.AssignPermission)
+	roles.Delete("/:uuid/permissions/:permission_uuid", middleware.PermissionRequired(authSvc, "role.permission.remove"), roleHandler.RemovePermission)
+	roles.Post("/:uuid/permissions/assign-bulk", middleware.PermissionRequired(authSvc, "role.permission.assign"), roleHandler.AssignPermissionsBulk)
+	roles.Post("/:uuid/permissions/remove-bulk", middleware.PermissionRequired(authSvc, "role.permission.remove"), roleHandler.RemovePermissionsBulk)
+}
diff --git a/internal/app/api/routes_saml_auth.go b/internal/app/api/routes_saml_auth.go
new file mode 100644
index 0000000..2d7727c
--- /dev/null
+++ b/internal/app/api/routes_saml_auth.go
@@ -0,0 +1,21 @@
+package api
+
+import "github.com/gofiber/fiber/v2"
+
+func registerSAMLAuthRoutes(v1 fiber.Router, samlHandler interface {
+	HandleLogin(*fiber.Ctx) error
+	HandleSAMLCallback(*fiber.Ctx) error
+	HandleSLO(*fiber.Ctx) error
+	HandleMetadata(*fiber.Ctx) error
+	HandleLogout(*fiber.Ctx) error
+}) {
+	if samlHandler == nil {
+		return
+	}
+	auth := v1.Group("/auth")
+	auth.Get("/login", samlHandler.HandleLogin)
+	auth.Post("/saml/callback", samlHandler.HandleSAMLCallback)
+	auth.Post("/saml/logout", samlHandler.HandleSLO)
+	auth.Get("/saml/metadata", samlHandler.HandleMetadata)
+	auth.Post("/saml/app-logout", samlHandler.HandleLogout)
+}
diff --git a/internal/app/api/routes_swagger.go b/internal/app/api/routes_swagger.go
new file mode 100644
index 0000000..3defd22
--- /dev/null
+++ b/internal/app/api/routes_swagger.go
@@ -0,0 +1,10 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+	"github.com/gofiber/swagger"
+)
+
+func registerSwaggerRoutes(app *fiber.App) {
+	app.Get("/swagger/*", swagger.HandlerDefault)
+}
diff --git a/internal/app/api/routes_takeover.go b/internal/app/api/routes_takeover.go
new file mode 100644
index 0000000..7225813
--- /dev/null
+++ b/internal/app/api/routes_takeover.go
@@ -0,0 +1,18 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerTakeoverRoutes(v1 fiber.Router, takeoverHandler *handlers.TakeoverHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	takeovers := v1.Group("/takeovers", authMiddleware)
+	takeovers.Post("/create", middleware.PermissionRequired(authSvc, "reserve_ac.create"), takeoverHandler.CreateTakeover)
+	takeovers.Get("/get-all", middleware.PermissionRequired(authSvc, "reserve_ac.read"), takeoverHandler.ListTakeovers)
+	takeovers.Get("/get/:id", middleware.PermissionRequired(authSvc, "reserve_ac.read"), takeoverHandler.GetTakeover)
+	takeovers.Patch("/update/:id", middleware.PermissionRequired(authSvc, "reserve_ac.update"), takeoverHandler.UpdateTakeover)
+	takeovers.Delete("/delete/:id", middleware.PermissionRequired(authSvc, "reserve_ac.delete"), takeoverHandler.DeleteTakeover)
+}
diff --git a/internal/app/api/routes_test.go b/internal/app/api/routes_test.go
new file mode 100644
index 0000000..e1da8fb
--- /dev/null
+++ b/internal/app/api/routes_test.go
@@ -0,0 +1,243 @@
+package api
+
+import (
+	"net/http"
+	"testing"
+
+	"github.com/gofiber/fiber/v2"
+)
+
+func TestRegisterRoutes(t *testing.T) {
+	app := fiber.New()
+	RegisterRoutes(app, buildRouteDependenciesForTest())
+
+	routes := app.GetRoutes(true)
+	required := []struct {
+		method string
+		path   string
+	}{
+		{method: http.MethodGet, path: "/health"},
+		{method: http.MethodGet, path: "/version"},
+		{method: http.MethodGet, path: "/api/version"},
+		{method: http.MethodGet, path: "/api/build-info"},
+		{method: http.MethodGet, path: "/metrics"},
+		{method: http.MethodPost, path: "/api/v1/auth/register"},
+		{method: http.MethodPost, path: "/api/v1/auth/forgot-password"},
+		{method: http.MethodPost, path: "/api/v1/users/create"},
+		{method: http.MethodGet, path: "/api/v1/users/events"},
+		{method: http.MethodPost, path: "/api/v1/contacts/create"},
+		{method: http.MethodGet, path: "/api/v1/contacts/get-all"},
+		{method: http.MethodGet, path: "/api/v1/contacts/get-all/dt"},
+		{method: http.MethodPost, path: "/api/v1/roles/create"},
+		{method: http.MethodPost, path: "/api/v1/helicopters/create"},
+		{method: http.MethodPost, path: "/api/v1/helicopter-usage/create"},
+		{method: http.MethodGet, path: "/api/v1/helicopter-usage/get-all"},
+		{method: http.MethodGet, path: "/api/v1/helicopter-usage/get-all/dt"},
+		{method: http.MethodGet, path: "/api/v1/helicopter-usage/get/:uuid"},
+		{method: http.MethodPatch, path: "/api/v1/helicopter-usage/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/helicopter-usage/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/helicopters/:id/reports/next-number"},
+		{method: http.MethodPost, path: "/api/v1/helicopter-files/create"},
+		{method: http.MethodGet, path: "/api/v1/helicopter-files/events"},
+		{method: http.MethodPost, path: "/api/v1/helicopter-files/upload"},
+		{method: http.MethodPost, path: "/api/v1/helicopter-files/cancel-upload"},
+		{method: http.MethodGet, path: "/api/v1/helicopter-files/get-all"},
+		{method: http.MethodGet, path: "/api/v1/helicopter-files/get/:helicopter_id"},
+		{method: http.MethodPatch, path: "/api/v1/helicopter-files/update"},
+		{method: http.MethodDelete, path: "/api/v1/helicopter-files/delete"},
+		{method: http.MethodGet, path: "/api/v1/flights/get-all"},
+		{method: http.MethodGet, path: "/api/v1/flights/get"},
+		{method: http.MethodGet, path: "/api/v1/fm-reports/get-all"},
+		{method: http.MethodGet, path: "/api/v1/fm-reports/get/:flight_id"},
+		{method: http.MethodPatch, path: "/api/v1/fm-reports/update/:flight_id"},
+		{method: http.MethodPost, path: "/api/v1/fm-reports/complete/:flight_id"},
+		{method: http.MethodPost, path: "/api/v1/flight-data/create"},
+		{method: http.MethodGet, path: "/api/v1/flight-data/get/:uuid"},
+		{method: http.MethodGet, path: "/api/v1/flight-data/get-all"},
+		{method: http.MethodGet, path: "/api/v1/flight-data/get-all/dt"},
+		{method: http.MethodGet, path: "/api/v1/flights-data/get-all"},
+		{method: http.MethodGet, path: "/api/v1/flights-data/get-all/dt"},
+		{method: http.MethodGet, path: "/api/v1/mission-type/get-all"},
+		{method: http.MethodDelete, path: "/api/v1/mission/delete-by-id/:mission_id"},
+		{method: http.MethodPost, path: "/api/v1/reserve-acs/create"},
+		{method: http.MethodGet, path: "/api/v1/reserve-acs/get-all"},
+		{method: http.MethodGet, path: "/api/v1/reserve-acs/get-all/dt"},
+		{method: http.MethodGet, path: "/api/v1/reserve-acs/get/:id"},
+		{method: http.MethodPatch, path: "/api/v1/reserve-acs/update"},
+		{method: http.MethodDelete, path: "/api/v1/reserve-acs/delete"},
+		{method: http.MethodGet, path: "/api/v1/after-flight-inspection/get"},
+		{method: http.MethodPost, path: "/api/v1/after-flight-inspection/create"},
+		{method: http.MethodPatch, path: "/api/v1/after-flight-inspection/update"},
+		{method: http.MethodDelete, path: "/api/v1/after-flight-inspection/delete"},
+		{method: http.MethodPost, path: "/api/v1/facilities/create"},
+		{method: http.MethodPost, path: "/api/v1/bases/create"},
+		{method: http.MethodGet, path: "/api/v1/bases/events"},
+		{method: http.MethodPost, path: "/api/v1/medicine/create"},
+		{method: http.MethodGet, path: "/api/v1/medicine/get-all"},
+		{method: http.MethodGet, path: "/api/v1/medicine/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/medicine/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/medicine/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/medicine-group/create"},
+		{method: http.MethodGet, path: "/api/v1/medicine-group/get-all"},
+		{method: http.MethodGet, path: "/api/v1/medicine-group/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/medicine-group/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/medicine-group/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/motor-reaction/create"},
+		{method: http.MethodGet, path: "/api/v1/motor-reaction/get-all"},
+		{method: http.MethodGet, path: "/api/v1/motor-reaction/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/motor-reaction/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/motor-reaction/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/vocation/create"},
+		{method: http.MethodGet, path: "/api/v1/vocation/get-all"},
+		{method: http.MethodGet, path: "/api/v1/vocation/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/vocation/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/vocation/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/opc/create"},
+		{method: http.MethodGet, path: "/api/v1/opc/get-all"},
+		{method: http.MethodGet, path: "/api/v1/opc/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/opc/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/opc/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/forces-present/create"},
+		{method: http.MethodGet, path: "/api/v1/forces-present/get-all"},
+		{method: http.MethodGet, path: "/api/v1/forces-present/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/forces-present/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/forces-present/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/hospital/create"},
+		{method: http.MethodGet, path: "/api/v1/hospital/get-all"},
+		{method: http.MethodGet, path: "/api/v1/hospital/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/hospital/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/hospital/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/health-insurance-companies/create"},
+		{method: http.MethodGet, path: "/api/v1/health-insurance-companies/get-all"},
+		{method: http.MethodGet, path: "/api/v1/health-insurance-companies/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/health-insurance-companies/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/health-insurance-companies/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/federal-state/create"},
+		{method: http.MethodGet, path: "/api/v1/federal-state/get-all"},
+		{method: http.MethodGet, path: "/api/v1/federal-state/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/federal-state/update/:id"},
+		{method: http.MethodDelete, path: "/api/v1/federal-state/delete/:id"},
+		{method: http.MethodPost, path: "/api/v1/icao/create"},
+		{method: http.MethodGet, path: "/api/v1/icao/get-all"},
+		{method: http.MethodGet, path: "/api/v1/icao/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/icao/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/icao/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/land/create"},
+		{method: http.MethodGet, path: "/api/v1/land/get-all"},
+		{method: http.MethodGet, path: "/api/v1/land/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/land/update/:id"},
+		{method: http.MethodDelete, path: "/api/v1/land/delete/:id"},
+		{method: http.MethodPost, path: "/api/v1/master-settings/create"},
+		{method: http.MethodGet, path: "/api/v1/master-settings/get"},
+		{method: http.MethodPatch, path: "/api/v1/master-settings/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/master-settings/delete/:uuid"},
+		{method: http.MethodGet, path: "/api/v1/branding/logo"},
+		{method: http.MethodGet, path: "/api/v1/branding/login-cover"},
+		{method: http.MethodGet, path: "/api/v1/branding/login-content"},
+		{method: http.MethodGet, path: "/api/v1/file-manager/get-all"},
+		{method: http.MethodGet, path: "/api/v1/file-manager/events"},
+		{method: http.MethodGet, path: "/api/v1/file-manager/trash/get-all"},
+		{method: http.MethodPatch, path: "/api/v1/file-manager/move"},
+		{method: http.MethodDelete, path: "/api/v1/file-manager/delete"},
+		{method: http.MethodPatch, path: "/api/v1/file-manager/restore"},
+		{method: http.MethodDelete, path: "/api/v1/file-manager/purge-delete"},
+		{method: http.MethodPost, path: "/api/v1/file-manager/folders/create"},
+		{method: http.MethodGet, path: "/api/v1/file-manager/folders/get/:uuid"},
+		{method: http.MethodPatch, path: "/api/v1/file-manager/folders/update/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/file-manager/files/create"},
+		{method: http.MethodPost, path: "/api/v1/file-manager/files/upload"},
+		{method: http.MethodDelete, path: "/api/v1/file-manager/files/cancel-upload"},
+		{method: http.MethodGet, path: "/api/v1/file-manager/files/get/:uuid"},
+		{method: http.MethodPatch, path: "/api/v1/file-manager/files/update/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/file-manager/attachments/create"},
+		{method: http.MethodGet, path: "/api/v1/file-manager/attachments/get-all"},
+		{method: http.MethodGet, path: "/api/v1/file-manager/attachments/get/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/file-manager/attachments/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/duty-roster/create"},
+		{method: http.MethodGet, path: "/api/v1/duty-roster/get-all"},
+		{method: http.MethodGet, path: "/api/v1/duty-roster/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/duty-roster/update"},
+		{method: http.MethodDelete, path: "/api/v1/duty-roster/delete"},
+		{method: http.MethodDelete, path: "/api/v1/duty-roster/crew"},
+		{method: http.MethodPost, path: "/api/v1/air-rescuer-checklist/create"},
+		{method: http.MethodGet, path: "/api/v1/air-rescuer-checklist/get-all"},
+		{method: http.MethodGet, path: "/api/v1/air-rescuer-checklist/get-all/dt"},
+		{method: http.MethodGet, path: "/api/v1/air-rescuer-checklist/get/:uuid"},
+		{method: http.MethodPatch, path: "/api/v1/air-rescuer-checklist/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/air-rescuer-checklist/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/air-rescuer-checklist/:uuid/items/create"},
+		{method: http.MethodPatch, path: "/api/v1/air-rescuer-checklist/:uuid/items/reorder"},
+		{method: http.MethodPatch, path: "/api/v1/air-rescuer-checklist/items/update/:item_uuid"},
+		{method: http.MethodDelete, path: "/api/v1/air-rescuer-checklist/items/delete/:item_uuid"},
+		{method: http.MethodPost, path: "/api/v1/insurance-patient-data/create"},
+		{method: http.MethodGet, path: "/api/v1/insurance-patient-data/get/:uuid"},
+		{method: http.MethodGet, path: "/api/v1/insurance-patient-data/get-all"},
+		{method: http.MethodGet, path: "/api/v1/insurance-patient-data/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/insurance-patient-data/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/insurance-patient-data/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/patient-data/create"},
+		{method: http.MethodGet, path: "/api/v1/patient-data/get/:uuid"},
+		{method: http.MethodGet, path: "/api/v1/patient-data/get-all"},
+		{method: http.MethodGet, path: "/api/v1/patient-data/get-all/dt"},
+		{method: http.MethodPatch, path: "/api/v1/patient-data/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/patient-data/delete/:uuid"},
+		{method: http.MethodGet, path: "/api/v1/dul/events"},
+		{method: http.MethodPost, path: "/api/v1/hems-operational-data/create"},
+		{method: http.MethodGet, path: "/api/v1/hems-operational-data/get-all"},
+		{method: http.MethodGet, path: "/api/v1/hems-operational-data/get-all/dt"},
+		{method: http.MethodGet, path: "/api/v1/hems-operational-data/get/:uuid"},
+		{method: http.MethodPatch, path: "/api/v1/hems-operational-data/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/hems-operational-data/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/hems-operation-category/create"},
+		{method: http.MethodGet, path: "/api/v1/hems-operation-category/get-all"},
+		{method: http.MethodGet, path: "/api/v1/hems-operation-category/get-all/dt"},
+		{method: http.MethodGet, path: "/api/v1/hems-operation-category/get/:uuid"},
+		{method: http.MethodPatch, path: "/api/v1/hems-operation-category/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/hems-operation-category/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/hems-operation/create"},
+		{method: http.MethodGet, path: "/api/v1/hems-operation/get-all"},
+		{method: http.MethodGet, path: "/api/v1/hems-operation/get-all/dt"},
+		{method: http.MethodGet, path: "/api/v1/hems-operation/get/:uuid"},
+		{method: http.MethodPatch, path: "/api/v1/hems-operation/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/hems-operation/delete/:uuid"},
+		{method: http.MethodGet, path: "/swagger/*"},
+	}
+
+	for _, tc := range required {
+		if !hasRoute(routes, tc.method, tc.path) {
+			t.Fatalf("route %s %s not registered", tc.method, tc.path)
+		}
+	}
+
+	legacy := []struct {
+		method string
+		path   string
+	}{
+		{method: http.MethodPost, path: "/api/v1/crews/create"},
+		{method: http.MethodGet, path: "/api/v1/crews/get-all"},
+		{method: http.MethodGet, path: "/api/v1/crews/get-all/dt"},
+		{method: http.MethodGet, path: "/api/v1/crews/get/:uuid"},
+		{method: http.MethodPatch, path: "/api/v1/crews/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/crews/delete/:uuid"},
+		{method: http.MethodPost, path: "/api/v1/hems-bases/create"},
+		{method: http.MethodGet, path: "/api/v1/hems-bases/get-all"},
+		{method: http.MethodGet, path: "/api/v1/hems-bases/get-all/dt"},
+		{method: http.MethodGet, path: "/api/v1/hems-bases/get/:uuid"},
+		{method: http.MethodPatch, path: "/api/v1/hems-bases/update/:uuid"},
+		{method: http.MethodDelete, path: "/api/v1/hems-bases/delete/:uuid"},
+	}
+	for _, tc := range legacy {
+		if hasRoute(routes, tc.method, tc.path) {
+			t.Fatalf("legacy route %s %s should not be registered", tc.method, tc.path)
+		}
+	}
+}
+
+func hasRoute(routes []fiber.Route, method, path string) bool {
+	for _, route := range routes {
+		if route.Method == method && route.Path == path {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/app/api/routes_test_helpers_test.go b/internal/app/api/routes_test_helpers_test.go
new file mode 100644
index 0000000..5b5c6ed
--- /dev/null
+++ b/internal/app/api/routes_test_helpers_test.go
@@ -0,0 +1,58 @@
+package api
+
+import (
+	"wucher/internal/config"
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+)
+
+func buildRouteDependenciesForTest() RouteDependencies {
+	authSvc := service.NewAuthService(nil, nil, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	return RouteDependencies{
+		Handlers: RouteHandlers{
+			User:                     handlers.NewUserHandler(service.NewUserService(nil)),
+			Contact:                  handlers.NewContactHandler(service.NewContactService(nil, nil), nil),
+			Health:                   handlers.NewHealthHandler(),
+			BuildInfo:                handlers.NewBuildInfoHandler(),
+			Auth:                     handlers.NewAuthHandler(authSvc),
+			Role:                     handlers.NewRoleHandler(service.NewRoleService(nil)),
+			Helicopter:               handlers.NewHelicopterHandler(service.NewHelicopterService(nil)),
+			HelicopterUsage:          handlers.NewHelicopterUsageHandler(service.NewHelicopterUsageService(nil)),
+			HelicopterFile:           handlers.NewHelicopterFileHandler(service.NewHelicopterFileService(nil)),
+			Flight:                   handlers.NewFlightHandler(service.NewFlightService(nil)).WithMissionService(service.NewMissionService(nil)),
+			FMReport:                 handlers.NewFMReportHandler(service.NewFMReportService(nil)).WithTakeoverService(service.NewTakeoverService(nil)).WithHelicopterUsageService(service.NewHelicopterUsageService(nil)),
+			ReserveAc:                handlers.NewReserveAcHandler(service.NewReserveAcService(nil)),
+			Facility:                 handlers.NewFacilityHandler(service.NewFacilityService(nil)),
+			Base:                     handlers.NewBaseHandler(service.NewBaseService(nil)),
+			Medicine:                 handlers.NewMedicineHandler(service.NewMedicineService(nil)),
+			Vocation:                 handlers.NewVocationHandler(service.NewVocationService(nil)),
+			Opc:                      handlers.NewOpcHandler(service.NewOpcService(nil)),
+			ForcesPresent:            handlers.NewForcesPresentHandler(service.NewForcesPresentService(nil)),
+			Hospital:                 handlers.NewHospitalHandler(service.NewHospitalService(nil)),
+			HealthInsuranceCompanies: handlers.NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(nil)),
+			FederalState:             handlers.NewFederalStateHandler(service.NewFederalStateService(nil)),
+			ICAO:                     handlers.NewICAOHandler(service.NewICAOService(nil)),
+			Land:                     handlers.NewLandHandler(service.NewLandService(nil)),
+			MasterSettings:           handlers.NewMasterSettingsHandler(service.NewMasterSettingsService(nil, service.MasterSettingsServiceDependencies{}), service.NewFileManagerService(nil, nil, nil, service.FileManagerServiceDependencies{}), nil),
+			Branding:                 handlers.NewBrandingHandler(service.NewMasterSettingsService(nil, service.MasterSettingsServiceDependencies{}), service.NewFileManagerService(nil, nil, nil, service.FileManagerServiceDependencies{}), nil),
+			FileManagerFolder:        handlers.NewFileManagerFolderHandler(service.NewFileManagerService(nil, nil, nil, service.FileManagerServiceDependencies{}), nil),
+			FileManagerFile: handlers.NewFileManagerFileHandler(service.NewFileManagerService(nil, nil, nil, service.FileManagerServiceDependencies{}), nil).
+				WithAircraftService(service.NewHelicopterService(nil)).
+				WithBaseService(service.NewBaseService(nil)).
+				WithTakeoverService(service.NewTakeoverService(nil)),
+			FileManagerAttachment: handlers.NewFileManagerAttachmentHandler(service.NewFileManagerService(nil, nil, nil, service.FileManagerServiceDependencies{})),
+			FileManagerEvents:     handlers.NewFileManagerEventsHandler(nil),
+			DutyRoster:            handlers.NewDutyRosterHandler(service.NewDutyRosterService(nil)),
+			AirRescuerChecklist:   handlers.NewAirRescuerChecklistHandler(service.NewAirRescuerChecklistService(nil)),
+			InsurancePatientData:  handlers.NewInsurancePatientDataHandler(service.NewInsurancePatientDataService(nil)),
+			PatientData:           handlers.NewPatientDataHandler(service.NewPatientDataService(nil)),
+			HEMSOperationalData:   handlers.NewHEMSOperationalDataHandler(service.NewHEMSOperationalDataService(nil)),
+			HEMSOperationCategory: handlers.NewHEMSOperationCategoryHandler(service.NewHEMSOperationCategoryService(nil)),
+			HEMSOperation:         handlers.NewHEMSOperationHandler(service.NewHEMSOperationService(nil)),
+		},
+		Services: RouteServices{
+			Auth:  authSvc,
+			Audit: service.NewAuditLogService(nil, service.AuditLogServiceDependencies{QueueSize: 0, Workers: 0, IPEncryptionKey: ""}),
+		},
+	}
+}
diff --git a/internal/app/api/routes_user.go b/internal/app/api/routes_user.go
new file mode 100644
index 0000000..06de7fc
--- /dev/null
+++ b/internal/app/api/routes_user.go
@@ -0,0 +1,26 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerUserRoutes(
+	v1 fiber.Router,
+	userHandler *handlers.UserHandler,
+	eventsHandler *handlers.FileManagerEventsHandler,
+	authMiddleware fiber.Handler,
+	authSvc *service.AuthService,
+) {
+	users := v1.Group("/users", authMiddleware)
+	users.Get("/events", middleware.PermissionRequired(authSvc, "user.read"), eventsHandler.Stream)
+	users.Post("/create", middleware.PermissionRequired(authSvc, "user.create"), userHandler.Create)
+	users.Get("/get-all", middleware.PermissionRequired(authSvc, "user.read"), userHandler.List)
+	users.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "user.read"), userHandler.ListDatatable)
+	users.Get("/get/:uuid", middleware.PermissionRequired(authSvc, "user.read"), userHandler.Get)
+	users.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "user.update"), userHandler.Update)
+	users.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "user.delete"), userHandler.Delete)
+}
diff --git a/internal/app/api/routes_vocation.go b/internal/app/api/routes_vocation.go
new file mode 100644
index 0000000..ee47cce
--- /dev/null
+++ b/internal/app/api/routes_vocation.go
@@ -0,0 +1,18 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerVocationRoutes(v1 fiber.Router, vocationHandler *handlers.VocationHandler, authMiddleware fiber.Handler, authSvc *service.AuthService) {
+	vocation := v1.Group("/vocation", authMiddleware)
+	vocation.Post("/create", middleware.PermissionRequired(authSvc, "vocation.create"), vocationHandler.Create)
+	vocation.Get("/get-all", middleware.PermissionRequired(authSvc, "vocation.read"), vocationHandler.List)
+	vocation.Get("/get-all/dt", middleware.PermissionRequired(authSvc, "vocation.read"), vocationHandler.ListDatatable)
+	vocation.Patch("/update/:uuid", middleware.PermissionRequired(authSvc, "vocation.update"), vocationHandler.Update)
+	vocation.Delete("/delete/:uuid", middleware.PermissionRequired(authSvc, "vocation.delete"), vocationHandler.Delete)
+}
diff --git a/internal/app/api/routes_wopi.go b/internal/app/api/routes_wopi.go
new file mode 100644
index 0000000..cdbf4e7
--- /dev/null
+++ b/internal/app/api/routes_wopi.go
@@ -0,0 +1,23 @@
+package api
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/transport/http/handlers"
+	"wucher/internal/transport/http/middleware"
+)
+
+func registerWOPIRoutes(app fiber.Router, takeoverHandler *handlers.TakeoverHandler, wopiSvc *service.WOPIService) {
+	wopi := app.Group("/wopi", middleware.WOPIRequired(wopiSvc))
+	if wopiSvc != nil {
+		wopi.Use(middleware.WOPIRequestBodyLimit(wopiSvc.MaxBodyBytes()))
+	}
+	readOnly := wopi.Group("", middleware.WOPIPermissionRequired(service.WOPIPermissionRead))
+	writeOnly := wopi.Group("", middleware.WOPIPermissionRequired(service.WOPIPermissionWrite))
+
+	readOnly.Get("/files/:fileId", takeoverHandler.CheckWOPIFileInfo)
+	readOnly.Get("/files/:fileId/contents", takeoverHandler.GetWOPIContents)
+	writeOnly.Post("/files/:fileId/contents", takeoverHandler.PutWOPIContents)
+	writeOnly.Post("/files/:fileId", takeoverHandler.PostWOPIFile)
+}
diff --git a/internal/app/api/seed.go b/internal/app/api/seed.go
new file mode 100644
index 0000000..6603bda
--- /dev/null
+++ b/internal/app/api/seed.go
@@ -0,0 +1,423 @@
+package api
+
+import (
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/base"
+)
+
+// SeedRoles inserts default roles if they don't exist.
+func SeedRoles(db *gorm.DB) error {
+	roles := []auth.Role{
+		{Code: "admin", Name: "admin", Description: "Full access to all resources."},
+		{Code: auth.RoleCodeStaff, Name: auth.RoleCodeStaff, Description: "Operational access with limited admin rights."},
+		{Code: "user", Name: "user", Description: "Regular end-user access."},
+		{Code: auth.RoleCodePilot, Name: "pilot", Description: "HEMS pilot contact role."},
+		{Code: auth.RoleCodeDoctor, Name: "doctor", Description: "HEMS doctor contact role."},
+		{Code: auth.RoleCodeAirRescuer, Name: "air_rescuer", Description: "HEMS air rescuer contact role."},
+		{Code: auth.RoleCodeTechnician, Name: "technician", Description: "HEMS technician contact role."},
+		{Code: auth.RoleCodeFlightAssistant, Name: "flight_assistant", Description: "HEMS flight assistant contact role."},
+	}
+
+	return db.Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "name"}},
+		DoUpdates: clause.AssignmentColumns([]string{"code", "description"}),
+	}).Create(&roles).Error
+}
+
+// DefaultPermissions returns the canonical catalog of permissions seeded into the system.
+func DefaultPermissions() []auth.Permission {
+	return []auth.Permission{
+		{Name: "Create User", Key: "user.create", Description: "Create users"},
+		{Name: "Read User", Key: "user.read", Description: "Read users"},
+		{Name: "Update User", Key: "user.update", Description: "Update users"},
+		{Name: "Delete User", Key: "user.delete", Description: "Delete users"},
+		{Name: "Create Role", Key: "role.create", Description: "Create roles"},
+		{Name: "Read Role", Key: "role.read", Description: "Read roles"},
+		{Name: "Update Role", Key: "role.update", Description: "Update roles"},
+		{Name: "Delete Role", Key: "role.delete", Description: "Delete roles"},
+		{Name: "Read Permission", Key: "role.permission.read", Description: "Read permissions"},
+		{Name: "Assign Permission", Key: "role.permission.assign", Description: "Assign permissions to role"},
+		{Name: "Remove Permission", Key: "role.permission.remove", Description: "Remove permissions from role"},
+		{Name: "Update Permission", Key: "role.permission.update", Description: "Update permission configuration"},
+		{Name: "Read Filesystem", Key: "filesystem.read", Description: "Read filesystem structure"},
+		{Name: "Read File Manager", Key: "file_manager.read", Description: "Read file manager"},
+		{Name: "Create File Manager", Key: "file_manager.create", Description: "Create in file manager"},
+		{Name: "Update File Manager", Key: "file_manager.update", Description: "Update in file manager"},
+		{Name: "Delete File Manager", Key: "file_manager.delete", Description: "Delete in file manager"},
+		{Name: "Read Folders", Key: "file_manager.folder.read", Description: "Read folders"},
+		{Name: "Create Folders", Key: "file_manager.folder.create", Description: "Create folders"},
+		{Name: "Update Folders", Key: "file_manager.folder.update", Description: "Update folders"},
+		{Name: "Delete Folders", Key: "file_manager.folder.delete", Description: "Delete folders"},
+		{Name: "Read Files", Key: "file_manager.file.read", Description: "Read files"},
+		{Name: "Create Files", Key: "file_manager.file.create", Description: "Create files"},
+		{Name: "Update Files", Key: "file_manager.file.update", Description: "Update files"},
+		{Name: "Delete Files", Key: "file_manager.file.delete", Description: "Delete files"},
+		{Name: "Create Helicopter", Key: "helicopter.create", Description: "Create helicopter"},
+		{Name: "Generate Helicopter Report Number", Key: "helicopter.report.generate", Description: "Generate next helicopter report number"},
+		{Name: "Read Helicopter", Key: "helicopter.read", Description: "Read helicopter"},
+		{Name: "Update Helicopter", Key: "helicopter.update", Description: "Update helicopter"},
+		{Name: "Delete Helicopter", Key: "helicopter.delete", Description: "Delete helicopter"},
+		{Name: "Create Helicopter Usage", Key: "helicopter_usage.create", Description: "Create helicopter usage"},
+		{Name: "Read Helicopter Usage", Key: "helicopter_usage.read", Description: "Read helicopter usage"},
+		{Name: "Update Helicopter Usage", Key: "helicopter_usage.update", Description: "Update helicopter usage"},
+		{Name: "Delete Helicopter Usage", Key: "helicopter_usage.delete", Description: "Delete helicopter usage"},
+		{Name: "Create Flight Inspection", Key: "flight_inspection.create", Description: "Create flight inspection"},
+		{Name: "Read Flight Inspection", Key: "flight_inspection.read", Description: "Read flight inspection"},
+		{Name: "Update Flight Inspection", Key: "flight_inspection.update", Description: "Update flight inspection"},
+		{Name: "Create After Flight Inspection", Key: "after_flight.create", Description: "Create after flight inspection"},
+		{Name: "Read After Flight Inspection", Key: "after_flight.read", Description: "Read after flight inspection"},
+		{Name: "Update After Flight Inspection", Key: "after_flight.update", Description: "Update after flight inspection"},
+		{Name: "Delete After Flight Inspection", Key: "after_flight.delete", Description: "Delete after flight inspection"},
+		{Name: "Create Flight", Key: "flight.create", Description: "Create flight"},
+		{Name: "Read Flight", Key: "flight.read", Description: "Read flight"},
+		{Name: "Update Flight", Key: "flight.update", Description: "Update flight"},
+		{Name: "Complete Flight Report", Key: "flight.complete", Description: "Complete (finalize) flight report"},
+		{Name: "Delete Flight", Key: "flight.delete", Description: "Delete flight"},
+		{Name: "Create Reserve AC", Key: "reserve_ac.create", Description: "Create reserve AC"},
+		{Name: "Read Reserve AC", Key: "reserve_ac.read", Description: "Read reserve AC"},
+		{Name: "Update Reserve AC", Key: "reserve_ac.update", Description: "Update reserve AC"},
+		{Name: "Delete Reserve AC", Key: "reserve_ac.delete", Description: "Delete reserve AC"},
+		{Name: "Create Facility", Key: "facility.create", Description: "Create facility"},
+		{Name: "Read Facility", Key: "facility.read", Description: "Read facility"},
+		{Name: "Update Facility", Key: "facility.update", Description: "Update facility"},
+		{Name: "Delete Facility", Key: "facility.delete", Description: "Delete facility"},
+		{Name: "Create Base", Key: "base.create", Description: "Create base"},
+		{Name: "Read Base", Key: "base.read", Description: "Read base"},
+		{Name: "Update Base", Key: "base.update", Description: "Update base"},
+		{Name: "Delete Base", Key: "base.delete", Description: "Delete base"},
+		{Name: "Create HEMS Base", Key: "hems_base.create", Description: "Create HEMS base"},
+		{Name: "Read HEMS Base", Key: "hems_base.read", Description: "Read HEMS base"},
+		{Name: "Update HEMS Base", Key: "hems_base.update", Description: "Update HEMS base"},
+		{Name: "Delete HEMS Base", Key: "hems_base.delete", Description: "Delete HEMS base"},
+		{Name: "Create Medicine", Key: "medicine.create", Description: "Create medicine"},
+		{Name: "Read Medicine", Key: "medicine.read", Description: "Read medicine"},
+		{Name: "Update Medicine", Key: "medicine.update", Description: "Update medicine"},
+		{Name: "Delete Medicine", Key: "medicine.delete", Description: "Delete medicine"},
+		{Name: "Create Vocation", Key: "vocation.create", Description: "Create vocation"},
+		{Name: "Read Vocation", Key: "vocation.read", Description: "Read vocation"},
+		{Name: "Update Vocation", Key: "vocation.update", Description: "Update vocation"},
+		{Name: "Delete Vocation", Key: "vocation.delete", Description: "Delete vocation"},
+		{Name: "Create OPC", Key: "opc.create", Description: "Create opc"},
+		{Name: "Read OPC", Key: "opc.read", Description: "Read opc"},
+		{Name: "Update OPC", Key: "opc.update", Description: "Update opc"},
+		{Name: "Delete OPC", Key: "opc.delete", Description: "Delete opc"},
+		{Name: "Create Forces Present", Key: "forces_present.create", Description: "Create forces present"},
+		{Name: "Read Forces Present", Key: "forces_present.read", Description: "Read forces present"},
+		{Name: "Update Forces Present", Key: "forces_present.update", Description: "Update forces present"},
+		{Name: "Delete Forces Present", Key: "forces_present.delete", Description: "Delete forces present"},
+		{Name: "Create No ICAO Code", Key: "no_icao_code.create", Description: "Create no icao code"},
+		{Name: "Read No ICAO Code", Key: "no_icao_code.read", Description: "Read no icao code"},
+		{Name: "Update No ICAO Code", Key: "no_icao_code.update", Description: "Update no icao code"},
+		{Name: "Delete No ICAO Code", Key: "no_icao_code.delete", Description: "Delete no icao code"},
+		{Name: "Create Health Insurance Companies", Key: "health_insurance_companies.create", Description: "Create health insurance companies"},
+		{Name: "Read Health Insurance Companies", Key: "health_insurance_companies.read", Description: "Read health insurance companies"},
+		{Name: "Update Health Insurance Companies", Key: "health_insurance_companies.update", Description: "Update health insurance companies"},
+		{Name: "Delete Health Insurance Companies", Key: "health_insurance_companies.delete", Description: "Delete health insurance companies"},
+		{Name: "Create Federal State", Key: "federal_state.create", Description: "Create federal state"},
+		{Name: "Read Federal State", Key: "federal_state.read", Description: "Read federal state"},
+		{Name: "Update Federal State", Key: "federal_state.update", Description: "Update federal state"},
+		{Name: "Delete Federal State", Key: "federal_state.delete", Description: "Delete federal state"},
+		{Name: "Create ICAO", Key: "icao.create", Description: "Create ICAO"},
+		{Name: "Read ICAO", Key: "icao.read", Description: "Read ICAO"},
+		{Name: "Update ICAO", Key: "icao.update", Description: "Update ICAO"},
+		{Name: "Delete ICAO", Key: "icao.delete", Description: "Delete ICAO"},
+		{Name: "Create Country", Key: "country.create", Description: "Create country"},
+		{Name: "Read Country", Key: "country.read", Description: "Read country"},
+		{Name: "Update Country", Key: "country.update", Description: "Update country"},
+		{Name: "Delete Country", Key: "country.delete", Description: "Delete country"},
+		{Name: "Create Master Settings", Key: "master_settings.create", Description: "Create master settings"},
+		{Name: "Read Master Settings", Key: "master_settings.read", Description: "Read master settings"},
+		{Name: "Update Master Settings", Key: "master_settings.update", Description: "Update master settings"},
+		{Name: "Delete Master Settings", Key: "master_settings.delete", Description: "Delete master settings"},
+		{Name: "Create Duty Roster", Key: "duty_roster.create", Description: "Create duty roster"},
+		{Name: "Read Duty Roster", Key: "duty_roster.read", Description: "Read duty roster"},
+		{Name: "Update Duty Roster", Key: "duty_roster.update", Description: "Update duty roster"},
+		{Name: "Delete Duty Roster", Key: "duty_roster.delete", Description: "Delete duty roster"},
+		{Name: "Create Air Rescuer Checklist", Key: "air_rescuer_checklist.create", Description: "Create air rescuer checklist"},
+		{Name: "Read Air Rescuer Checklist", Key: "air_rescuer_checklist.read", Description: "Read air rescuer checklist"},
+		{Name: "Update Air Rescuer Checklist", Key: "air_rescuer_checklist.update", Description: "Update air rescuer checklist"},
+		{Name: "Delete Air Rescuer Checklist", Key: "air_rescuer_checklist.delete", Description: "Delete air rescuer checklist"},
+		{Name: "Create Flight Prep Check", Key: "flight_prep_check.create", Description: "Create flight prep check"},
+		{Name: "Read Flight Prep Check", Key: "flight_prep_check.read", Description: "Read flight prep check"},
+		{Name: "Update Flight Prep Check", Key: "flight_prep_check.update", Description: "Update flight prep check"},
+		{Name: "Read Audit Log", Key: "audit.read", Description: "Read audit logs"},
+		{Name: "Create Insurance Patient Data", Key: "insurance_patient_data.create", Description: "Create insurance patient data"},
+		{Name: "Read Insurance Patient Data", Key: "insurance_patient_data.read", Description: "Read insurance patient data"},
+		{Name: "Update Insurance Patient Data", Key: "insurance_patient_data.update", Description: "Update insurance patient data"},
+		{Name: "Delete Insurance Patient Data", Key: "insurance_patient_data.delete", Description: "Delete insurance patient data"},
+		{Name: "Create Patient Data", Key: "patient_data.create", Description: "Create patient data"},
+		{Name: "Read Patient Data", Key: "patient_data.read", Description: "Read patient data"},
+		{Name: "Update Patient Data", Key: "patient_data.update", Description: "Update patient data"},
+		{Name: "Delete Patient Data", Key: "patient_data.delete", Description: "Delete patient data"},
+		{Name: "Create Operation", Key: "operation.create", Description: "Create HEMS operational data"},
+		{Name: "Read Operation", Key: "operation.read", Description: "Read HEMS operational data"},
+		{Name: "Update Operation", Key: "operation.update", Description: "Update HEMS operational data"},
+		{Name: "Delete Operation", Key: "operation.delete", Description: "Delete HEMS operational data"},
+		{Name: "Create Operation Category", Key: "operation_category.create", Description: "Create HEMS operation category"},
+		{Name: "Read Operation Category", Key: "operation_category.read", Description: "Read HEMS operation category"},
+		{Name: "Update Operation Category", Key: "operation_category.update", Description: "Update HEMS operation category"},
+		{Name: "Delete Operation Category", Key: "operation_category.delete", Description: "Delete HEMS operation category"},
+		{Name: "Create HEMS Operation", Key: "hems_operation.create", Description: "Create HEMS operation"},
+		{Name: "Read HEMS Operation", Key: "hems_operation.read", Description: "Read HEMS operation"},
+		{Name: "Update HEMS Operation", Key: "hems_operation.update", Description: "Update HEMS operation"},
+		{Name: "Delete HEMS Operation", Key: "hems_operation.delete", Description: "Delete HEMS operation"},
+		{Name: "Create DUL", Key: "dul.create", Description: "Create DUL"},
+		{Name: "Read DUL", Key: "dul.read", Description: "Read DUL"},
+		{Name: "Update DUL", Key: "dul.update", Description: "Update DUL"},
+		{Name: "Delete DUL", Key: "dul.delete", Description: "Delete DUL"},
+		{Name: "Create Complaint", Key: "complaint.create", Description: "Create complaint"},
+		{Name: "Read Complaint", Key: "complaint.read", Description: "Read complaint"},
+		{Name: "Update Complaint", Key: "complaint.update", Description: "Update complaint"},
+		{Name: "Delete Complaint", Key: "complaint.delete", Description: "Delete complaint"},
+		{Name: "Decide Complaint NSR", Key: "complaint.nsr", Description: "Set or cancel complaint NSR (non-safety release)"},
+		{Name: "Create EASA Release", Key: "easa_release.create", Description: "Create EASA maintenance release"},
+		{Name: "Read EASA Release", Key: "easa_release.read", Description: "Read EASA maintenance release"},
+		{Name: "Update EASA Release", Key: "easa_release.update", Description: "Update EASA maintenance release"},
+		{Name: "Delete EASA Release", Key: "easa_release.delete", Description: "Delete EASA maintenance release"},
+		{Name: "Sign EASA Release", Key: "easa_release.sign", Description: "Sign EASA maintenance release (return to service)"},
+		{Name: "Read Action Sign-off", Key: "action_signoff.read", Description: "Read corrective-action sign-off"},
+		{Name: "Sign Action Sign-off", Key: "action_signoff.sign", Description: "Toggle (sign/unsign) corrective-action sign-off, per complaint or fleet-wide"},
+		{Name: "Create MCF", Key: "mcf.create", Description: "Create maintenance check flight"},
+		{Name: "Read MCF", Key: "mcf.read", Description: "Read maintenance check flight"},
+		{Name: "Complete MCF", Key: "mcf.complete", Description: "Complete (release) a helicopter's open maintenance check flight"},
+	}
+}
+
+// SeedPermissions inserts default permissions and keeps existing rows in sync.
+func SeedPermissions(db *gorm.DB) error {
+	perms := DefaultPermissions()
+
+	for i := range perms {
+		perms[i].Module = auth.ModuleForKey(perms[i].Key)
+		perms[i].RequiresPIN = auth.DefaultPermissionRequiresPIN(perms[i].Key)
+	}
+
+	return db.Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "key"}},
+		DoUpdates: clause.AssignmentColumns([]string{"name", "description", "module"}),
+	}).Create(&perms).Error
+}
+
+// SeedRolePermissions inserts default role-permission mappings and ensures admin has all permissions.
+func SeedRolePermissions(db *gorm.DB) error {
+	type rolePerm struct {
+		RoleName string
+		PermKey  string
+	}
+
+	mappings := []rolePerm{
+		// staff: read-only for users/roles/permissions
+		{RoleName: "staff", PermKey: "user.read"},
+		{RoleName: "staff", PermKey: "role.read"},
+		{RoleName: "staff", PermKey: "role.permission.read"},
+		{RoleName: "staff", PermKey: "helicopter.read"},
+		{RoleName: "staff", PermKey: "flight_inspection.read"},
+		{RoleName: "staff", PermKey: "flight.read"},
+		{RoleName: "staff", PermKey: "reserve_ac.read"},
+		{RoleName: "staff", PermKey: "facility.read"},
+		{RoleName: "staff", PermKey: "base.read"},
+		{RoleName: "staff", PermKey: "hems_base.read"},
+		{RoleName: "staff", PermKey: "medicine.read"},
+		{RoleName: "staff", PermKey: "vocation.read"},
+		{RoleName: "staff", PermKey: "opc.read"},
+		{RoleName: "staff", PermKey: "forces_present.read"},
+		{RoleName: "staff", PermKey: "no_icao_code.read"},
+		{RoleName: "staff", PermKey: "health_insurance_companies.read"},
+		{RoleName: "staff", PermKey: "federal_state.read"},
+		{RoleName: "staff", PermKey: "icao.read"},
+		{RoleName: "staff", PermKey: "country.read"},
+		{RoleName: "staff", PermKey: "master_settings.read"},
+		{RoleName: "staff", PermKey: "file_manager.read"},
+		{RoleName: "staff", PermKey: "duty_roster.read"},
+		{RoleName: "staff", PermKey: "air_rescuer_checklist.read"},
+		{RoleName: "staff", PermKey: "flight_prep_check.create"},
+		{RoleName: "staff", PermKey: "flight_prep_check.read"},
+		{RoleName: "staff", PermKey: "flight_prep_check.update"},
+		{RoleName: "staff", PermKey: "helicopter_usage.read"},
+		{RoleName: "staff", PermKey: "after_flight.read"},
+		{RoleName: "staff", PermKey: "audit.read"},
+		{RoleName: "staff", PermKey: "insurance_patient_data.read"},
+		{RoleName: "staff", PermKey: "patient_data.read"},
+		{RoleName: "staff", PermKey: "operation.read"},
+		{RoleName: "staff", PermKey: "operation_category.read"},
+		{RoleName: "staff", PermKey: "hems_operation.read"},
+		{RoleName: "pilot", PermKey: "flight.read"},
+		{RoleName: "pilot", PermKey: "duty_roster.read"},
+	}
+
+	if err := assignAllPermissionsToRole(db, "admin"); err != nil {
+		return err
+	}
+
+	for _, m := range mappings {
+		if err := assignPermissionToRole(db, m.RoleName, m.PermKey); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func assignAllPermissionsToRole(db *gorm.DB, roleName string) error {
+	var role auth.Role
+	if err := db.Where("name = ?", roleName).First(&role).Error; err != nil {
+		return err
+	}
+
+	var perms []auth.Permission
+	if err := db.Find(&perms).Error; err != nil {
+		return err
+	}
+
+	for _, perm := range perms {
+		rp := auth.RolePermission{RoleID: role.ID, PermissionID: perm.ID}
+		if err := db.Clauses(clause.OnConflict{
+			Columns:   []clause.Column{{Name: "role_id"}, {Name: "permission_id"}},
+			DoNothing: true,
+		}).Create(&rp).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func assignPermissionToRole(db *gorm.DB, roleName, permKey string) error {
+	var role auth.Role
+	if err := db.Where("name = ?", roleName).First(&role).Error; err != nil {
+		return err
+	}
+	var perm auth.Permission
+	if err := db.Where("`key` = ?", permKey).First(&perm).Error; err != nil {
+		return err
+	}
+	rp := auth.RolePermission{RoleID: role.ID, PermissionID: perm.ID}
+	return db.Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "role_id"}, {Name: "permission_id"}},
+		DoNothing: true,
+	}).Create(&rp).Error
+}
+
+// SeedBaseCategories inserts default base categories if they don't exist.
+func SeedBaseCategories(db *gorm.DB) error {
+	categories := []base.BaseCategory{
+		{Key: base.CategoryKeyRegular, Name: "Regular Base"},
+		{Key: base.CategoryKeyHEMS, Name: "HEMS Base"},
+	}
+
+	return db.Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "key"}},
+		DoUpdates: clause.AssignmentColumns([]string{"name"}),
+	}).Create(&categories).Error
+}
+
+// SeedRosterUsers inserts sample users for duty roster assignment in development.
+// This seed is idempotent by email and keeps role assignment synced via user_roles.
+func SeedRosterUsers(db *gorm.DB) error {
+	type rosterSeed struct {
+		Email       string
+		FirstName   string
+		LastName    string
+		MobilePhone string
+		RoleCode    string
+	}
+
+	seeds := []rosterSeed{
+		{Email: "pilot.main@wucher.local", FirstName: "Pilot", LastName: "Main", MobilePhone: "+620001", RoleCode: auth.RoleCodePilot},
+		{Email: "pilot.additional@wucher.local", FirstName: "Pilot", LastName: "Additional", MobilePhone: "+620002", RoleCode: auth.RoleCodePilot},
+		{Email: "doctor.main@wucher.local", FirstName: "Doctor", LastName: "Main", MobilePhone: "+620003", RoleCode: auth.RoleCodeDoctor},
+		{Email: "rescuer.main@wucher.local", FirstName: "Rescuer", LastName: "Main", MobilePhone: "+620004", RoleCode: auth.RoleCodeAirRescuer},
+		{Email: "helper.main@wucher.local", FirstName: "Helper", LastName: "Main", MobilePhone: "+620005", RoleCode: auth.RoleCodeFlightAssistant},
+	}
+
+	return db.Transaction(func(tx *gorm.DB) error {
+		roleKeys := make([]string, 0, len(seeds))
+		seenRole := make(map[string]struct{}, len(seeds))
+		for i := range seeds {
+			k := strings.ToLower(strings.TrimSpace(seeds[i].RoleCode))
+			if k == "" {
+				continue
+			}
+			if _, ok := seenRole[k]; ok {
+				continue
+			}
+			seenRole[k] = struct{}{}
+			roleKeys = append(roleKeys, k)
+		}
+
+		var roles []auth.Role
+		if err := tx.Where("LOWER(code) IN ? OR LOWER(name) IN ?", roleKeys, roleKeys).Find(&roles).Error; err != nil {
+			return err
+		}
+		roleIDByCode := make(map[string][]byte, len(roles))
+		for i := range roles {
+			code := strings.ToLower(strings.TrimSpace(roles[i].Code))
+			if code == "" {
+				code = strings.ToLower(strings.TrimSpace(roles[i].Name))
+			}
+			if code == "" {
+				continue
+			}
+			roleIDByCode[code] = append([]byte(nil), roles[i].ID...)
+		}
+
+		now := time.Now().UTC()
+		for i := range seeds {
+			roleCode := strings.ToLower(strings.TrimSpace(seeds[i].RoleCode))
+			roleID := roleIDByCode[roleCode]
+			if len(roleID) != 16 {
+				continue
+			}
+
+			row := auth.User{
+				Email:           strings.ToLower(strings.TrimSpace(seeds[i].Email)),
+				Username:        nil,
+				FirstName:       strings.TrimSpace(seeds[i].FirstName),
+				LastName:        strings.TrimSpace(seeds[i].LastName),
+				MobilePhone:     strings.TrimSpace(seeds[i].MobilePhone),
+				Timezone:        "UTC",
+				RoleID:          roleID,
+				IsActive:        true,
+				EmailVerifiedAt: &now,
+			}
+
+			if err := tx.Clauses(clause.OnConflict{
+				Columns: []clause.Column{{Name: "email"}},
+				DoUpdates: clause.Assignments(map[string]any{
+					"first_name":        row.FirstName,
+					"last_name":         row.LastName,
+					"mobile_phone":      row.MobilePhone,
+					"timezone":          row.Timezone,
+					"role_id":           row.RoleID,
+					"is_active":         row.IsActive,
+					"email_verified_at": row.EmailVerifiedAt,
+					"updated_at":        now,
+				}),
+			}).Create(&row).Error; err != nil {
+				return err
+			}
+
+			var created auth.User
+			if err := tx.Where("email = ?", row.Email).Take(&created).Error; err != nil {
+				return err
+			}
+
+			link := auth.UserRole{
+				UserID: created.ID,
+				RoleID: roleID,
+			}
+			if err := tx.Clauses(clause.OnConflict{
+				Columns:   []clause.Column{{Name: "user_id"}, {Name: "role_id"}},
+				DoNothing: true,
+			}).Create(&link).Error; err != nil {
+				return err
+			}
+		}
+
+		return nil
+	})
+}
diff --git a/internal/app/api/seed_permissions_test.go b/internal/app/api/seed_permissions_test.go
new file mode 100644
index 0000000..4baec98
--- /dev/null
+++ b/internal/app/api/seed_permissions_test.go
@@ -0,0 +1,34 @@
+package api
+
+import (
+	"testing"
+
+	"wucher/internal/domain/auth"
+)
+
+// TestDefaultPermissionsHaveRegisteredModule guards that every seeded permission
+// maps to a module declared in auth.ModuleRegistry. Adding a permission with a
+// new prefix without registering its module will fail this test.
+func TestDefaultPermissionsHaveRegisteredModule(t *testing.T) {
+	for _, p := range DefaultPermissions() {
+		module := auth.ModuleForKey(p.Key)
+		if !auth.IsRegisteredModule(module) {
+			t.Errorf("permission %q maps to module %q which is not in auth.ModuleRegistry", p.Key, module)
+		}
+	}
+}
+
+// TestDefaultPermissionsHaveUniqueKeys guards against accidental duplicate keys
+// in the catalog (the upsert is keyed on "key").
+func TestDefaultPermissionsHaveUniqueKeys(t *testing.T) {
+	seen := make(map[string]bool)
+	for _, p := range DefaultPermissions() {
+		if p.Key == "" {
+			t.Errorf("permission %q has an empty key", p.Name)
+		}
+		if seen[p.Key] {
+			t.Errorf("duplicate permission key %q in DefaultPermissions", p.Key)
+		}
+		seen[p.Key] = true
+	}
+}
diff --git a/internal/app/api/server.go b/internal/app/api/server.go
new file mode 100644
index 0000000..1d53490
--- /dev/null
+++ b/internal/app/api/server.go
@@ -0,0 +1,54 @@
+package api
+
+import (
+	"context"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+)
+
+type Server struct {
+	app             *fiber.App
+	shutdownTimeout time.Duration
+}
+
+type ServerOption func(*Server)
+
+const defaultShutdownTimeout = 30 * time.Second
+
+func WithShutdownTimeout(timeout time.Duration) ServerOption {
+	return func(s *Server) {
+		if timeout > 0 {
+			s.shutdownTimeout = timeout
+		}
+	}
+}
+
+func NewServer(app *fiber.App, opts ...ServerOption) *Server {
+	srv := &Server{
+		app:             app,
+		shutdownTimeout: defaultShutdownTimeout,
+	}
+	for _, opt := range opts {
+		if opt != nil {
+			opt(srv)
+		}
+	}
+	return srv
+}
+
+func (s *Server) Start(addr string) error {
+	return s.app.Listen(addr)
+}
+
+func (s *Server) Shutdown(ctx context.Context) error {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if s.shutdownTimeout > 0 {
+		shutdownCtx, cancel := context.WithTimeout(ctx, s.shutdownTimeout)
+		defer cancel()
+		ctx = shutdownCtx
+	}
+	return s.app.ShutdownWithContext(ctx)
+}
diff --git a/internal/app/api/server_test.go b/internal/app/api/server_test.go
new file mode 100644
index 0000000..45c71c8
--- /dev/null
+++ b/internal/app/api/server_test.go
@@ -0,0 +1,160 @@
+package api
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+)
+
+func TestServerShutdownDrainsInFlightRequestsAndRejectsNewRequests(t *testing.T) {
+	app := fiber.New(fiber.Config{
+		DisableStartupMessage: true,
+	})
+	UseDefaultMiddlewares(app, testHTTPConfig())
+
+	slowStarted := make(chan struct{})
+	app.Get("/slow", func(c *fiber.Ctx) error {
+		select {
+		case <-slowStarted:
+		default:
+			close(slowStarted)
+		}
+
+		select {
+		case <-time.After(300 * time.Millisecond):
+		case <-c.UserContext().Done():
+			return c.Status(http.StatusInternalServerError).SendString("user context canceled")
+		}
+
+		return c.SendString("slow done")
+	})
+	app.Get("/fast", func(c *fiber.Ctx) error {
+		return c.SendString("fast done")
+	})
+
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+
+	serveErrCh := make(chan error, 1)
+	go func() {
+		serveErrCh <- app.Listener(ln)
+	}()
+
+	t.Cleanup(func() {
+		_ = app.Shutdown()
+	})
+
+	baseURL := "http://" + ln.Addr().String()
+	fastClient := newTestHTTPClient()
+	slowClient := newTestHTTPClient()
+	defer fastClient.CloseIdleConnections()
+	defer slowClient.CloseIdleConnections()
+
+	if err := waitForHTTP200(fastClient, baseURL+"/fast", time.Second); err != nil {
+		t.Fatalf("wait for server ready: %v", err)
+	}
+
+	slowRespCh := make(chan httpCallResult, 1)
+	go func() {
+		resp, err := slowClient.Get(baseURL + "/slow")
+		if err != nil {
+			slowRespCh <- httpCallResult{err: err}
+			return
+		}
+		defer resp.Body.Close()
+
+		body, readErr := io.ReadAll(resp.Body)
+		slowRespCh <- httpCallResult{
+			statusCode: resp.StatusCode,
+			body:       string(body),
+			err:        readErr,
+		}
+	}()
+
+	select {
+	case <-slowStarted:
+	case <-time.After(time.Second):
+		t.Fatal("slow request did not start")
+	}
+
+	srv := NewServer(app, WithShutdownTimeout(2*time.Second))
+	shutdownErrCh := make(chan error, 1)
+	go func() {
+		shutdownErrCh <- srv.Shutdown(context.Background())
+	}()
+
+	if err := waitForRequestRejection(fastClient, baseURL+"/fast", time.Second); err == nil {
+		t.Fatal("expected new requests to be rejected during shutdown")
+	}
+
+	slowResult := <-slowRespCh
+	if slowResult.err != nil {
+		t.Fatalf("slow request failed: %v", slowResult.err)
+	}
+	if slowResult.statusCode != http.StatusOK {
+		t.Fatalf("expected slow request 200, got %d with body %q", slowResult.statusCode, slowResult.body)
+	}
+	if slowResult.body != "slow done" {
+		t.Fatalf("expected slow request body %q, got %q", "slow done", slowResult.body)
+	}
+
+	if err := <-shutdownErrCh; err != nil {
+		t.Fatalf("shutdown failed: %v", err)
+	}
+	if err := <-serveErrCh; err != nil {
+		t.Fatalf("listener exited with error: %v", err)
+	}
+}
+
+type httpCallResult struct {
+	statusCode int
+	body       string
+	err        error
+}
+
+func newTestHTTPClient() *http.Client {
+	return &http.Client{
+		Timeout: time.Second,
+		Transport: &http.Transport{
+			DisableKeepAlives: true,
+		},
+	}
+}
+
+func waitForHTTP200(client *http.Client, url string, timeout time.Duration) error {
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		resp, err := client.Get(url)
+		if err == nil {
+			resp.Body.Close()
+			if resp.StatusCode == http.StatusOK {
+				return nil
+			}
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	return errors.New("server did not become ready")
+}
+
+func waitForRequestRejection(client *http.Client, url string, timeout time.Duration) error {
+	deadline := time.Now().Add(timeout)
+	var lastErr error
+	for time.Now().Before(deadline) {
+		resp, err := client.Get(url)
+		if err != nil {
+			return err
+		}
+		lastErr = errors.New("request still accepted")
+		resp.Body.Close()
+		time.Sleep(10 * time.Millisecond)
+	}
+	return lastErr
+}
diff --git a/internal/app/queueing/builders.go b/internal/app/queueing/builders.go
new file mode 100644
index 0000000..09a8f4a
--- /dev/null
+++ b/internal/app/queueing/builders.go
@@ -0,0 +1,138 @@
+package queueing
+
+import (
+	"context"
+	"log/slog"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/config"
+	"wucher/internal/queue"
+	mysqlrepo "wucher/internal/repository/mysql"
+	sqsrepo "wucher/internal/repository/sqs"
+	"wucher/internal/resilience"
+)
+
+func NewEmailProducer(
+	ctx context.Context,
+	queueCfg config.QueueConfig,
+	sqsCfg config.SQSConfig,
+	executor *resilience.Executor,
+	logger *slog.Logger,
+) (queue.EmailJobProducer, error) {
+	producer, err := NewQueueProducer(ctx, sqsCfg, executor, "api")
+	if err != nil {
+		return nil, err
+	}
+	return queue.NewEmailEnqueuer(NewOutboxSerializer(queueCfg, sqsCfg), producer, logger), nil
+}
+
+func NewQueueProducer(ctx context.Context, sqsCfg config.SQSConfig, executor *resilience.Executor, component string) (queue.QueueProducer, error) {
+	client, err := sqsrepo.NewClient(ctx, sqsCfg)
+	if err != nil {
+		return nil, err
+	}
+	return sqsrepo.NewQueue(
+		sqsrepo.NewResilientAPI(client, executor),
+		sqsCfg,
+		sqsrepo.WithMetricsComponent(component),
+	)
+}
+
+func NewOutboxSerializer(queueCfg config.QueueConfig, sqsCfg config.SQSConfig) queue.MessageSerializer {
+	return queue.NewJSONSerializer(
+		queueCfg.MessageSchemaVersion,
+		queueCfg.EnableLegacyPayloadFallback,
+		sqsCfg.QueueType,
+		sqsCfg.MessageGroupID,
+	)
+}
+
+func NewEmailConsumer(
+	ctx context.Context,
+	queueCfg config.QueueConfig,
+	sqsCfg config.SQSConfig,
+	executor *resilience.Executor,
+) (queue.QueueConsumer, queue.MessageSerializer, error) {
+	client, err := sqsrepo.NewClient(ctx, sqsCfg)
+	if err != nil {
+		return nil, nil, err
+	}
+	consumer, err := sqsrepo.NewEmailQueue(
+		sqsrepo.NewResilientAPI(client, executor),
+		sqsCfg,
+		sqsrepo.WithMetricsComponent("email_worker"),
+	)
+	if err != nil {
+		return nil, nil, err
+	}
+	serializer := queue.NewJSONSerializer(
+		queueCfg.MessageSchemaVersion,
+		queueCfg.EnableLegacyPayloadFallback,
+		sqsCfg.QueueType,
+		sqsCfg.MessageGroupID,
+	)
+	return consumer, serializer, nil
+}
+
+func NewFileProcessingProducer(
+	ctx context.Context,
+	queueCfg config.FileQueueConfig,
+	sqsCfg config.SQSConfig,
+	executor *resilience.Executor,
+	logger *slog.Logger,
+) (queue.FileProcessingJobProducer, error) {
+	producer, err := NewQueueProducer(ctx, sqsCfg, executor, "api")
+	if err != nil {
+		return nil, err
+	}
+	return queue.NewFileProcessingEnqueuer(NewFileProcessingSerializer(queueCfg, sqsCfg), producer, logger), nil
+}
+
+func NewFileProcessingSerializer(queueCfg config.FileQueueConfig, sqsCfg config.SQSConfig) queue.FileProcessingMessageSerializer {
+	return queue.NewFileProcessingJSONSerializer(
+		queueCfg.MessageSchemaVersion,
+		sqsCfg.QueueType,
+		sqsCfg.MessageGroupID,
+	)
+}
+
+func NewFileProcessingConsumer(
+	ctx context.Context,
+	queueCfg config.FileQueueConfig,
+	sqsCfg config.SQSConfig,
+	executor *resilience.Executor,
+) (queue.QueueConsumer, queue.FileProcessingMessageSerializer, error) {
+	client, err := sqsrepo.NewClient(ctx, sqsCfg)
+	if err != nil {
+		return nil, nil, err
+	}
+	consumer, err := sqsrepo.NewQueue(
+		sqsrepo.NewResilientAPI(client, executor),
+		sqsCfg,
+		sqsrepo.WithMetricsComponent("file_worker"),
+	)
+	if err != nil {
+		return nil, nil, err
+	}
+	serializer := queue.NewFileProcessingJSONSerializer(
+		queueCfg.MessageSchemaVersion,
+		sqsCfg.QueueType,
+		sqsCfg.MessageGroupID,
+	)
+	return consumer, serializer, nil
+}
+
+func NewIdempotencyStore(db *gorm.DB, queueCfg config.QueueConfig) queue.IdempotencyStore {
+	if db == nil {
+		return queue.NewMemoryIdempotencyStore()
+	}
+	return mysqlrepo.NewQueueIdempotencyStore(db, queueCfg.IdempotencyKeyPrefix)
+}
+
+func NewIdempotencyStoreWithPrefix(db *gorm.DB, keyPrefix string) queue.IdempotencyStore {
+	if db == nil {
+		return queue.NewMemoryIdempotencyStore()
+	}
+	return mysqlrepo.NewQueueIdempotencyStore(db, keyPrefix)
+}
diff --git a/internal/app/worker/file_processing_outbox_dispatcher.go b/internal/app/worker/file_processing_outbox_dispatcher.go
new file mode 100644
index 0000000..bfbc539
--- /dev/null
+++ b/internal/app/worker/file_processing_outbox_dispatcher.go
@@ -0,0 +1,241 @@
+package worker
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"os"
+	"time"
+
+	"wucher/internal/config"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/queue"
+)
+
+type FileProcessingOutboxDispatcher struct {
+	repo            filemanager.FileProcessingOutboxRepository
+	producer        queue.QueueProducer
+	logger          *slog.Logger
+	retryPolicy     queue.RetryPolicy
+	pollInterval    time.Duration
+	dispatchTimeout time.Duration
+	lockTTL         time.Duration
+	maxAttempts     int
+	batchSize       int
+	workerID        string
+	metrics         *outboxMetrics
+}
+
+func NewFileProcessingOutboxDispatcher(
+	cfg config.FileQueueConfig,
+	repo filemanager.FileProcessingOutboxRepository,
+	producer queue.QueueProducer,
+	logger *slog.Logger,
+) *FileProcessingOutboxDispatcher {
+	if !cfg.OutboxEnabled || repo == nil || producer == nil {
+		return nil
+	}
+	if logger == nil {
+		logger = slog.Default()
+	}
+	workerID := fmt.Sprintf("%s-%d", hostname(), os.Getpid())
+	return &FileProcessingOutboxDispatcher{
+		repo:            repo,
+		producer:        producer,
+		logger:          logger.With("component", "file-outbox-dispatcher", "backend", producer.Backend()),
+		retryPolicy:     queue.NewExponentialBackoffPolicy(cfg.WorkerBackoffMin, cfg.WorkerBackoffMax, cfg.WorkerPermanentFailureDelay),
+		pollInterval:    cfg.OutboxPollInterval,
+		dispatchTimeout: cfg.OutboxDispatchTimeout,
+		lockTTL:         cfg.OutboxLockTTL,
+		maxAttempts:     cfg.OutboxMaxAttempts,
+		batchSize:       cfg.OutboxBatchSize,
+		workerID:        workerID,
+		metrics:         &outboxMetrics{},
+	}
+}
+
+func (d *FileProcessingOutboxDispatcher) Metrics() OutboxMetricsSnapshot {
+	if d == nil {
+		return OutboxMetricsSnapshot{}
+	}
+	return d.metrics.Snapshot()
+}
+
+func (d *FileProcessingOutboxDispatcher) Run(ctx context.Context) error {
+	if d == nil {
+		return nil
+	}
+	if d.pollInterval <= 0 {
+		d.pollInterval = time.Second
+	}
+	for {
+		processed, err := d.dispatchOnce(ctx)
+		if err != nil {
+			if ctx.Err() != nil {
+				return nil
+			}
+			d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+				snapshot.Failures++
+				snapshot.LastFailureAt = time.Now().UTC()
+				snapshot.LastError = err.Error()
+			})
+			d.logger.Error("file outbox dispatch cycle failed", slog.Any("error", err))
+		}
+		if ctx.Err() != nil {
+			return nil
+		}
+		if processed > 0 {
+			continue
+		}
+		select {
+		case <-ctx.Done():
+			return nil
+		case <-time.After(d.pollInterval):
+		}
+	}
+}
+
+func (d *FileProcessingOutboxDispatcher) dispatchOnce(ctx context.Context) (int, error) {
+	now := time.Now().UTC()
+	messages, err := d.repo.ClaimPendingFileProcessingOutboxMessages(ctx, d.batchSize, now, d.lockTTL, d.workerID)
+	if err != nil {
+		return 0, err
+	}
+	if len(messages) == 0 {
+		d.refreshPending(ctx, now)
+		return 0, nil
+	}
+	d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+		snapshot.Claimed += int64(len(messages))
+	})
+	for i := range messages {
+		d.dispatchMessage(ctx, &messages[i])
+	}
+	d.refreshPending(ctx, time.Now().UTC())
+	return len(messages), nil
+}
+
+func (d *FileProcessingOutboxDispatcher) dispatchMessage(ctx context.Context, message *filemanager.FileProcessingOutboxMessage) {
+	if message == nil {
+		return
+	}
+	outbound, err := message.OutboundMessage()
+	if err != nil {
+		d.failPermanently(ctx, message, err)
+		return
+	}
+	queueMessage := queue.OutboundMessage{
+		ID:              outbound.ID,
+		Body:            outbound.Body,
+		Attributes:      outbound.Attributes,
+		MessageGroupID:  outbound.MessageGroupID,
+		DeduplicationID: outbound.DeduplicationID,
+	}
+
+	dispatchCtx := ctx
+	cancel := func() {}
+	if d.dispatchTimeout > 0 {
+		dispatchCtx, cancel = context.WithTimeout(ctx, d.dispatchTimeout)
+	}
+	err = d.producer.Publish(dispatchCtx, queueMessage)
+	cancel()
+	if err == nil {
+		publishedAt := time.Now().UTC()
+		if markErr := d.repo.MarkFileProcessingOutboxMessagePublished(ctx, message.ID, publishedAt); markErr != nil {
+			d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+				snapshot.Failures++
+				snapshot.LastFailureAt = time.Now().UTC()
+				snapshot.LastError = markErr.Error()
+			})
+			d.logger.Error("file outbox publish marked failed",
+				slog.String("message_id", message.MessageID),
+				slog.Any("error", markErr),
+			)
+			return
+		}
+		d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+			snapshot.Published++
+			snapshot.LastSuccessAt = publishedAt
+			snapshot.LastError = ""
+		})
+		d.logger.Info("file outbox message published",
+			slog.String("message_id", message.MessageID),
+			slog.String("job_type", message.JobType),
+			slog.String("correlation_id", message.CorrelationID),
+			slog.Int("attempt", message.Attempts),
+		)
+		return
+	}
+
+	if message.Attempts >= d.maxAttempts {
+		d.failPermanently(ctx, message, err)
+		return
+	}
+
+	decision := d.retryPolicy.Decide(&queue.Delivery{ID: message.MessageID, ReceiveCount: message.Attempts}, nil, err)
+	nextAttemptAt := time.Now().UTC().Add(decision.Delay)
+	if retryErr := d.repo.MarkFileProcessingOutboxMessageRetry(ctx, message.ID, nextAttemptAt, err.Error()); retryErr != nil {
+		d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+			snapshot.Failures++
+			snapshot.LastFailureAt = time.Now().UTC()
+			snapshot.LastError = retryErr.Error()
+		})
+		d.logger.Error("file outbox retry scheduling failed",
+			slog.String("message_id", message.MessageID),
+			slog.Any("error", retryErr),
+		)
+		return
+	}
+	d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+		snapshot.Retried++
+		snapshot.LastFailureAt = time.Now().UTC()
+		snapshot.LastError = err.Error()
+	})
+	d.logger.Warn("file outbox publish failed; scheduled retry",
+		slog.String("message_id", message.MessageID),
+		slog.String("job_type", message.JobType),
+		slog.Duration("retry_in", decision.Delay),
+		slog.Int("attempt", message.Attempts),
+		slog.Any("error", err),
+	)
+}
+
+func (d *FileProcessingOutboxDispatcher) failPermanently(ctx context.Context, message *filemanager.FileProcessingOutboxMessage, err error) {
+	if message == nil || err == nil {
+		return
+	}
+	failedAt := time.Now().UTC()
+	if markErr := d.repo.MarkFileProcessingOutboxMessageDead(ctx, message.ID, failedAt, err.Error()); markErr != nil {
+		d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+			snapshot.Failures++
+			snapshot.LastFailureAt = failedAt
+			snapshot.LastError = markErr.Error()
+		})
+		d.logger.Error("file outbox dead-letter marking failed",
+			slog.String("message_id", message.MessageID),
+			slog.Any("error", markErr),
+		)
+		return
+	}
+	d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+		snapshot.Dead++
+		snapshot.LastFailureAt = failedAt
+		snapshot.LastError = err.Error()
+	})
+	d.logger.Error("file outbox message marked dead",
+		slog.String("message_id", message.MessageID),
+		slog.String("job_type", message.JobType),
+		slog.Int("attempt", message.Attempts),
+		slog.Any("error", err),
+	)
+}
+
+func (d *FileProcessingOutboxDispatcher) refreshPending(ctx context.Context, now time.Time) {
+	count, err := d.repo.CountPendingFileProcessingOutboxMessages(ctx, now)
+	if err != nil {
+		return
+	}
+	d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+		snapshot.ApproximatePending = count
+	})
+}
diff --git a/internal/app/worker/file_processing_outbox_dispatcher_test.go b/internal/app/worker/file_processing_outbox_dispatcher_test.go
new file mode 100644
index 0000000..40355ed
--- /dev/null
+++ b/internal/app/worker/file_processing_outbox_dispatcher_test.go
@@ -0,0 +1,219 @@
+package worker
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"wucher/internal/config"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/queue"
+)
+
+type stubFileOutboxRepo struct {
+	messages map[string]*filemanager.FileProcessingOutboxMessage
+}
+
+func newStubFileOutboxRepo(messages ...*filemanager.FileProcessingOutboxMessage) *stubFileOutboxRepo {
+	repo := &stubFileOutboxRepo{messages: map[string]*filemanager.FileProcessingOutboxMessage{}}
+	for _, message := range messages {
+		if message == nil {
+			continue
+		}
+		cp := *message
+		cp.ID = append([]byte(nil), message.ID...)
+		cp.Body = append([]byte(nil), message.Body...)
+		cp.Attributes = append([]byte(nil), message.Attributes...)
+		repo.messages[string(cp.ID)] = &cp
+	}
+	return repo
+}
+
+func (r *stubFileOutboxRepo) CreateFileProcessingOutboxMessage(_ context.Context, message *filemanager.FileProcessingOutboxMessage) error {
+	if message == nil {
+		return errors.New("nil message")
+	}
+	cp := *message
+	cp.ID = append([]byte(nil), message.ID...)
+	cp.Body = append([]byte(nil), message.Body...)
+	cp.Attributes = append([]byte(nil), message.Attributes...)
+	r.messages[string(cp.ID)] = &cp
+	return nil
+}
+
+func (r *stubFileOutboxRepo) ClaimPendingFileProcessingOutboxMessages(_ context.Context, limit int, now time.Time, lockTTL time.Duration, workerID string) ([]filemanager.FileProcessingOutboxMessage, error) {
+	if limit <= 0 {
+		limit = 1
+	}
+	if lockTTL <= 0 {
+		lockTTL = time.Minute
+	}
+	out := make([]filemanager.FileProcessingOutboxMessage, 0, limit)
+	staleBefore := now.Add(-lockTTL)
+	for _, message := range r.messages {
+		if len(out) >= limit {
+			break
+		}
+		switch {
+		case message.Status == filemanager.FileProcessingOutboxStatusPending && !message.AvailableAt.After(now):
+		case message.Status == filemanager.FileProcessingOutboxStatusProcessing && message.LockedAt != nil && message.LockedAt.Before(staleBefore):
+		default:
+			continue
+		}
+		message.Status = filemanager.FileProcessingOutboxStatusProcessing
+		message.Attempts++
+		ts := now
+		message.LockedAt = &ts
+		message.LockedBy = workerID
+		cp := *message
+		out = append(out, cp)
+	}
+	return out, nil
+}
+
+func (r *stubFileOutboxRepo) MarkFileProcessingOutboxMessagePublished(_ context.Context, id []byte, publishedAt time.Time) error {
+	message := r.messages[string(id)]
+	if message == nil {
+		return errors.New("not found")
+	}
+	message.Status = filemanager.FileProcessingOutboxStatusPublished
+	message.PublishedAt = &publishedAt
+	message.LockedAt = nil
+	message.LockedBy = ""
+	message.LastError = ""
+	return nil
+}
+
+func (r *stubFileOutboxRepo) MarkFileProcessingOutboxMessageRetry(_ context.Context, id []byte, availableAt time.Time, lastErr string) error {
+	message := r.messages[string(id)]
+	if message == nil {
+		return errors.New("not found")
+	}
+	message.Status = filemanager.FileProcessingOutboxStatusPending
+	message.AvailableAt = availableAt
+	message.LockedAt = nil
+	message.LockedBy = ""
+	message.LastError = lastErr
+	return nil
+}
+
+func (r *stubFileOutboxRepo) MarkFileProcessingOutboxMessageDead(_ context.Context, id []byte, failedAt time.Time, lastErr string) error {
+	message := r.messages[string(id)]
+	if message == nil {
+		return errors.New("not found")
+	}
+	message.Status = filemanager.FileProcessingOutboxStatusDead
+	message.AvailableAt = failedAt
+	message.LockedAt = nil
+	message.LockedBy = ""
+	message.LastError = lastErr
+	return nil
+}
+
+func (r *stubFileOutboxRepo) CountPendingFileProcessingOutboxMessages(_ context.Context, now time.Time) (int64, error) {
+	var count int64
+	for _, message := range r.messages {
+		if (message.Status == filemanager.FileProcessingOutboxStatusPending && !message.AvailableAt.After(now)) || message.Status == filemanager.FileProcessingOutboxStatusProcessing {
+			count++
+		}
+	}
+	return count, nil
+}
+
+func newFileOutboxRecord(t *testing.T, job queue.FileProcessingJob) *filemanager.FileProcessingOutboxMessage {
+	t.Helper()
+	serializer := queue.NewFileProcessingJSONSerializer("v1", queue.QueueTypeStandard, "")
+	message, err := serializer.Serialize(context.Background(), job)
+	if err != nil {
+		t.Fatalf("serialize: %v", err)
+	}
+	record, err := filemanager.NewFileProcessingOutboxMessage(time.Now().UTC(), &filemanager.FileProcessingOutboundMessage{
+		ID:              message.ID,
+		Body:            append([]byte(nil), message.Body...),
+		Attributes:      message.Attributes,
+		MessageGroupID:  message.MessageGroupID,
+		DeduplicationID: message.DeduplicationID,
+	})
+	if err != nil {
+		t.Fatalf("new outbox message: %v", err)
+	}
+	return record
+}
+
+func TestFileProcessingOutboxDispatcherPublishSuccess(t *testing.T) {
+	record := newFileOutboxRecord(t, queue.FileProcessingJob{
+		FileUUID:  "01961f5c-6471-7b81-9df5-2e2e1cf7e498",
+		Bucket:    "bucket-a",
+		ObjectKey: "files/2026/04/05/object.pdf",
+		SizeBytes: 128,
+	})
+	repo := newStubFileOutboxRepo(record)
+	producer := &stubQueueProducer{}
+	dispatcher := NewFileProcessingOutboxDispatcher(config.FileQueueConfig{
+		OutboxEnabled:         true,
+		OutboxBatchSize:       10,
+		OutboxDispatchTimeout: time.Second,
+		OutboxLockTTL:         time.Minute,
+		OutboxMaxAttempts:     3,
+		WorkerBackoffMin:      time.Second,
+		WorkerBackoffMax:      time.Minute,
+	}, repo, producer, nil)
+
+	processed, err := dispatcher.dispatchOnce(context.Background())
+	if err != nil {
+		t.Fatalf("dispatch once: %v", err)
+	}
+	if processed != 1 {
+		t.Fatalf("expected one processed message, got %d", processed)
+	}
+	if len(producer.published) != 1 {
+		t.Fatalf("expected one published message, got %d", len(producer.published))
+	}
+	if repo.messages[string(record.ID)].Status != filemanager.FileProcessingOutboxStatusPublished {
+		t.Fatalf("expected message published, got %s", repo.messages[string(record.ID)].Status)
+	}
+	if got := dispatcher.Metrics().Published; got != 1 {
+		t.Fatalf("expected published metric=1, got %d", got)
+	}
+}
+
+func TestFileProcessingOutboxDispatcherRetryOnPublishFailure(t *testing.T) {
+	record := newFileOutboxRecord(t, queue.FileProcessingJob{
+		FileUUID:  "01961f5c-6471-7b81-9df5-2e2e1cf7e499",
+		Bucket:    "bucket-a",
+		ObjectKey: "files/2026/04/05/object.pdf",
+		SizeBytes: 256,
+	})
+	repo := newStubFileOutboxRepo(record)
+	producer := &stubQueueProducer{err: errors.New("queue unavailable")}
+	dispatcher := NewFileProcessingOutboxDispatcher(config.FileQueueConfig{
+		OutboxEnabled:     true,
+		OutboxBatchSize:   10,
+		OutboxLockTTL:     time.Minute,
+		OutboxMaxAttempts: 3,
+		WorkerBackoffMin:  time.Second,
+		WorkerBackoffMax:  time.Minute,
+	}, repo, producer, nil)
+
+	processed, err := dispatcher.dispatchOnce(context.Background())
+	if err != nil {
+		t.Fatalf("dispatch once: %v", err)
+	}
+	if processed != 1 {
+		t.Fatalf("expected one processed message, got %d", processed)
+	}
+	got := repo.messages[string(record.ID)]
+	if got.Status != filemanager.FileProcessingOutboxStatusPending {
+		t.Fatalf("expected message returned to pending, got %s", got.Status)
+	}
+	if got.Attempts != 1 {
+		t.Fatalf("expected attempts=1, got %d", got.Attempts)
+	}
+	if !got.AvailableAt.After(time.Now().Add(-time.Second)) {
+		t.Fatalf("expected retry to schedule next attempt in the future")
+	}
+	if metrics := dispatcher.Metrics(); metrics.Retried != 1 {
+		t.Fatalf("expected retried metric=1, got %d", metrics.Retried)
+	}
+}
diff --git a/internal/app/worker/file_processing_runner.go b/internal/app/worker/file_processing_runner.go
new file mode 100644
index 0000000..4905f0b
--- /dev/null
+++ b/internal/app/worker/file_processing_runner.go
@@ -0,0 +1,193 @@
+package worker
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"time"
+
+	"wucher/internal/config"
+	"wucher/internal/shared/pkg/metrics"
+	"wucher/internal/queue"
+)
+
+type FileProcessingRunner struct {
+	worker            *queue.FileProcessingWorker
+	consumer          queue.QueueConsumer
+	dispatcher        *FileProcessingOutboxDispatcher
+	logger            *slog.Logger
+	monitorAddr       string
+	depthPollInterval time.Duration
+	shutdownTimeout   time.Duration
+	backend           string
+	monitorServer     *http.Server
+}
+
+func NewFileProcessingRunner(
+	cfg config.FileQueueConfig,
+	consumer queue.QueueConsumer,
+	serializer queue.FileProcessingMessageSerializer,
+	handler queue.FileProcessingJobHandler,
+	idempotency queue.IdempotencyStore,
+	dispatcher *FileProcessingOutboxDispatcher,
+	logger *slog.Logger,
+) *FileProcessingRunner {
+	if logger == nil {
+		logger = slog.Default()
+	}
+	metrics := queue.NewMetrics()
+	health := queue.NewHealthReporter(cfg.WorkerHealthErrorThreshold)
+	worker := queue.NewFileProcessingWorker(queue.WorkerConfig{
+		Concurrency:      cfg.WorkerConcurrency,
+		MaxBatchSize:     cfg.WorkerMaxBatchSize,
+		ProcessTimeout:   cfg.WorkerProcessTimeout,
+		ProcessingTTL:    cfg.ProcessingTTL,
+		IdempotencyTTL:   cfg.IdempotencyTTL,
+		PollErrorDelay:   cfg.WorkerBackoffMin,
+		MetricsComponent: "file_worker",
+	}, consumer, serializer, handler, queue.NewExponentialBackoffPolicy(cfg.WorkerBackoffMin, cfg.WorkerBackoffMax, cfg.WorkerPermanentFailureDelay), idempotency, metrics, health, logger)
+
+	backend := ""
+	if consumer != nil {
+		backend = consumer.Backend()
+	}
+	return &FileProcessingRunner{
+		worker:            worker,
+		consumer:          consumer,
+		dispatcher:        dispatcher,
+		logger:            logger,
+		monitorAddr:       cfg.WorkerMonitorAddr,
+		depthPollInterval: cfg.WorkerDepthPollInterval,
+		shutdownTimeout:   cfg.WorkerShutdownTimeout,
+		backend:           backend,
+	}
+}
+
+func (r *FileProcessingRunner) Start(ctx context.Context) error {
+	if r.worker == nil {
+		return errors.New("worker is required")
+	}
+	runCtx, cancelRun := context.WithCancel(ctx)
+	defer cancelRun()
+	if err := r.startMonitor(); err != nil {
+		return err
+	}
+	pollerDone := make(chan struct{})
+	go func() {
+		defer close(pollerDone)
+		r.runDepthPoller(runCtx)
+	}()
+
+	workerErrCh := make(chan error, 1)
+	go func() {
+		workerErrCh <- r.worker.Run(runCtx)
+	}()
+
+	var dispatcherErrCh chan error
+	if r.dispatcher != nil {
+		dispatcherErrCh = make(chan error, 1)
+		go func() {
+			dispatcherErrCh <- r.dispatcher.Run(runCtx)
+		}()
+	}
+
+	var err error
+	select {
+	case err = <-workerErrCh:
+		cancelRun()
+		if dispatcherErrCh != nil {
+			if dispatcherErr := <-dispatcherErrCh; err == nil {
+				err = dispatcherErr
+			}
+		}
+	case err = <-dispatcherErrCh:
+		cancelRun()
+		if workerErr := <-workerErrCh; err == nil {
+			err = workerErr
+		}
+	}
+
+	cancelRun()
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), r.shutdownTimeout)
+	defer cancel()
+	if r.monitorServer != nil {
+		_ = r.monitorServer.Shutdown(shutdownCtx)
+	}
+	if r.consumer != nil {
+		_ = r.consumer.Close()
+	}
+	<-pollerDone
+	return err
+}
+
+func (r *FileProcessingRunner) startMonitor() error {
+	if r.monitorAddr == "" {
+		return nil
+	}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/health", r.handleHealth)
+	mux.Handle("/metrics", metrics.PromHTTPHandler())
+	r.monitorServer = &http.Server{
+		Addr:              r.monitorAddr,
+		Handler:           mux,
+		ReadHeaderTimeout: 5 * time.Second,
+	}
+	go func() {
+		r.logger.Info("file worker monitor listening",
+			slog.String("addr", r.monitorAddr),
+			slog.String("backend", r.backend),
+		)
+		if err := r.monitorServer.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			r.logger.Error("file worker monitor failed", slog.Any("error", err))
+		}
+	}()
+	return nil
+}
+
+func (r *FileProcessingRunner) runDepthPoller(ctx context.Context) {
+	if r.depthPollInterval <= 0 {
+		return
+	}
+	ticker := time.NewTicker(r.depthPollInterval)
+	defer ticker.Stop()
+	for {
+		refreshCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+		_ = r.worker.RefreshQueueDepth(refreshCtx)
+		cancel()
+
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+		}
+	}
+}
+
+func (r *FileProcessingRunner) handleHealth(w http.ResponseWriter, _ *http.Request) {
+	snapshot := struct {
+		Backend string                 `json:"backend"`
+		Health  queue.HealthSnapshot   `json:"health"`
+		Metrics queue.MetricsSnapshot  `json:"metrics"`
+		Outbox  *OutboxMetricsSnapshot `json:"outbox,omitempty"`
+	}{
+		Backend: r.backend,
+		Health:  r.worker.Health().Snapshot(),
+		Metrics: r.worker.Metrics().Snapshot(),
+	}
+	if r.dispatcher != nil {
+		snapshot.Outbox = ptr(r.dispatcher.Metrics())
+	}
+	statusCode := http.StatusOK
+	if snapshot.Health.Status == "degraded" {
+		statusCode = http.StatusServiceUnavailable
+	}
+	writeFileWorkerJSON(w, statusCode, snapshot)
+}
+
+func writeFileWorkerJSON(w http.ResponseWriter, statusCode int, payload any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(statusCode)
+	_ = json.NewEncoder(w).Encode(payload)
+}
diff --git a/internal/app/worker/outbox_dispatcher.go b/internal/app/worker/outbox_dispatcher.go
new file mode 100644
index 0000000..fe9aee2
--- /dev/null
+++ b/internal/app/worker/outbox_dispatcher.go
@@ -0,0 +1,342 @@
+package worker
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"os"
+	"strings"
+	"sync"
+	"time"
+
+	"wucher/internal/config"
+	"wucher/internal/domain/auth"
+	"wucher/internal/queue"
+)
+
+type OutboxMetricsSnapshot struct {
+	Claimed            int64     `json:"claimed"`
+	Published          int64     `json:"published"`
+	Retried            int64     `json:"retried"`
+	Dead               int64     `json:"dead"`
+	Failures           int64     `json:"failures"`
+	ApproximatePending int64     `json:"approximate_pending"`
+	LastSuccessAt      time.Time `json:"last_success_at"`
+	LastFailureAt      time.Time `json:"last_failure_at"`
+	LastError          string    `json:"last_error,omitempty"`
+}
+
+type outboxMetrics struct {
+	mu       sync.Mutex
+	snapshot OutboxMetricsSnapshot
+}
+
+func (m *outboxMetrics) Snapshot() OutboxMetricsSnapshot {
+	if m == nil {
+		return OutboxMetricsSnapshot{}
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.snapshot
+}
+
+func (m *outboxMetrics) update(fn func(snapshot *OutboxMetricsSnapshot)) {
+	if m == nil || fn == nil {
+		return
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	fn(&m.snapshot)
+}
+
+type OutboxDispatcher struct {
+	repo            auth.EmailOutboxRepository
+	producer        queue.QueueProducer
+	logger          *slog.Logger
+	retryPolicy     queue.RetryPolicy
+	pollInterval    time.Duration
+	dispatchTimeout time.Duration
+	lockTTL         time.Duration
+	maxAttempts     int
+	batchSize       int
+	workerID        string
+	metrics         *outboxMetrics
+}
+
+func NewOutboxDispatcher(
+	cfg config.QueueConfig,
+	repo auth.EmailOutboxRepository,
+	producer queue.QueueProducer,
+	logger *slog.Logger,
+) *OutboxDispatcher {
+	if !cfg.OutboxEnabled || repo == nil || producer == nil {
+		return nil
+	}
+	if logger == nil {
+		logger = slog.Default()
+	}
+	workerID := fmt.Sprintf("%s-%d", hostname(), os.Getpid())
+	return &OutboxDispatcher{
+		repo:            repo,
+		producer:        producer,
+		logger:          logger.With("component", "outbox-dispatcher", "backend", producer.Backend()),
+		retryPolicy:     queue.NewExponentialBackoffPolicy(cfg.WorkerBackoffMin, cfg.WorkerBackoffMax, cfg.WorkerPermanentFailureDelay),
+		pollInterval:    cfg.OutboxPollInterval,
+		dispatchTimeout: cfg.OutboxDispatchTimeout,
+		lockTTL:         cfg.OutboxLockTTL,
+		maxAttempts:     cfg.OutboxMaxAttempts,
+		batchSize:       cfg.OutboxBatchSize,
+		workerID:        workerID,
+		metrics:         &outboxMetrics{},
+	}
+}
+
+func (d *OutboxDispatcher) Metrics() OutboxMetricsSnapshot {
+	if d == nil {
+		return OutboxMetricsSnapshot{}
+	}
+	return d.metrics.Snapshot()
+}
+
+func (d *OutboxDispatcher) Run(ctx context.Context) error {
+	if d == nil {
+		return nil
+	}
+	if d.pollInterval <= 0 {
+		d.pollInterval = time.Second
+	}
+	for {
+		processed, err := d.dispatchOnce(ctx)
+		if err != nil {
+			if ctx.Err() != nil {
+				return nil
+			}
+			d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+				snapshot.Failures++
+				snapshot.LastFailureAt = time.Now().UTC()
+				snapshot.LastError = err.Error()
+			})
+			d.logger.Error("outbox dispatch cycle failed", slog.Any("error", err))
+		}
+		if ctx.Err() != nil {
+			return nil
+		}
+		if processed > 0 {
+			continue
+		}
+		select {
+		case <-ctx.Done():
+			return nil
+		case <-time.After(d.pollInterval):
+		}
+	}
+}
+
+func (d *OutboxDispatcher) dispatchOnce(ctx context.Context) (int, error) {
+	now := time.Now().UTC()
+	messages, err := d.repo.ClaimPendingEmailOutboxMessages(ctx, d.batchSize, now, d.lockTTL, d.workerID)
+	if err != nil {
+		return 0, err
+	}
+	if len(messages) == 0 {
+		d.refreshPending(ctx, now)
+		return 0, nil
+	}
+	d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+		snapshot.Claimed += int64(len(messages))
+	})
+	for i := range messages {
+		d.dispatchMessage(ctx, &messages[i])
+	}
+	d.refreshPending(ctx, time.Now().UTC())
+	return len(messages), nil
+}
+
+func (d *OutboxDispatcher) dispatchMessage(ctx context.Context, message *auth.EmailOutboxMessage) {
+	if message == nil {
+		return
+	}
+	outbound, err := message.OutboundMessage()
+	if err != nil {
+		d.failPermanently(ctx, message, err)
+		return
+	}
+	if shouldSkipOutboxEmailPublish(outbound) {
+		publishedAt := time.Now().UTC()
+		if markErr := d.repo.MarkEmailOutboxMessagePublished(ctx, message.ID, publishedAt); markErr != nil {
+			d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+				snapshot.Failures++
+				snapshot.LastFailureAt = time.Now().UTC()
+				snapshot.LastError = markErr.Error()
+			})
+			d.logger.Error("outbox skip marked failed",
+				slog.String("message_id", message.MessageID),
+				slog.Any("error", markErr),
+			)
+			return
+		}
+		d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+			snapshot.Published++
+			snapshot.LastSuccessAt = publishedAt
+			snapshot.LastError = ""
+		})
+		d.logger.Info("outbox message skipped",
+			slog.String("message_id", message.MessageID),
+			slog.String("job_type", message.JobType),
+			slog.String("correlation_id", message.CorrelationID),
+		)
+		return
+	}
+
+	dispatchCtx := ctx
+	cancel := func() {}
+	if d.dispatchTimeout > 0 {
+		dispatchCtx, cancel = context.WithTimeout(ctx, d.dispatchTimeout)
+	}
+	err = d.producer.Publish(dispatchCtx, *outbound)
+	cancel()
+	if err == nil {
+		publishedAt := time.Now().UTC()
+		if markErr := d.repo.MarkEmailOutboxMessagePublished(ctx, message.ID, publishedAt); markErr != nil {
+			d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+				snapshot.Failures++
+				snapshot.LastFailureAt = time.Now().UTC()
+				snapshot.LastError = markErr.Error()
+			})
+			d.logger.Error("outbox publish marked failed",
+				slog.String("message_id", message.MessageID),
+				slog.Any("error", markErr),
+			)
+			return
+		}
+		d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+			snapshot.Published++
+			snapshot.LastSuccessAt = publishedAt
+			snapshot.LastError = ""
+		})
+		d.logger.Info("outbox message published",
+			slog.String("message_id", message.MessageID),
+			slog.String("job_type", message.JobType),
+			slog.String("correlation_id", message.CorrelationID),
+			slog.Int("attempt", message.Attempts),
+		)
+		return
+	}
+
+	if message.Attempts >= d.maxAttempts {
+		d.failPermanently(ctx, message, err)
+		return
+	}
+
+	decision := d.retryPolicy.Decide(&queue.Delivery{ID: message.MessageID, ReceiveCount: message.Attempts}, nil, err)
+	nextAttemptAt := time.Now().UTC().Add(decision.Delay)
+	if retryErr := d.repo.MarkEmailOutboxMessageRetry(ctx, message.ID, nextAttemptAt, err.Error()); retryErr != nil {
+		d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+			snapshot.Failures++
+			snapshot.LastFailureAt = time.Now().UTC()
+			snapshot.LastError = retryErr.Error()
+		})
+		d.logger.Error("outbox retry scheduling failed",
+			slog.String("message_id", message.MessageID),
+			slog.Any("error", retryErr),
+		)
+		return
+	}
+	d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+		snapshot.Retried++
+		snapshot.LastFailureAt = time.Now().UTC()
+		snapshot.LastError = err.Error()
+	})
+	d.logger.Warn("outbox publish failed; scheduled retry",
+		slog.String("message_id", message.MessageID),
+		slog.String("job_type", message.JobType),
+		slog.Duration("retry_in", decision.Delay),
+		slog.Int("attempt", message.Attempts),
+		slog.Any("error", err),
+	)
+}
+
+func shouldSkipOutboxEmailPublish(outbound *queue.OutboundMessage) bool {
+	if outbound == nil || len(outbound.Body) == 0 {
+		return false
+	}
+	var envelope struct {
+		Payload struct {
+			MessageType string            `json:"message_type"`
+			Metadata    map[string]string `json:"metadata"`
+			Tags        map[string]string `json:"tags"`
+		} `json:"payload"`
+	}
+	if err := json.Unmarshal(outbound.Body, &envelope); err == nil {
+		if strings.EqualFold(strings.TrimSpace(envelope.Payload.Metadata["skip_send"]), "true") {
+			return true
+		}
+		if strings.EqualFold(strings.TrimSpace(envelope.Payload.MessageType), "email_verify") &&
+			strings.EqualFold(strings.TrimSpace(envelope.Payload.Tags["source"]), "register") {
+			return true
+		}
+		return false
+	}
+	var legacyJob struct {
+		MessageType string            `json:"message_type"`
+		Metadata    map[string]string `json:"metadata"`
+		Tags        map[string]string `json:"tags"`
+	}
+	if err := json.Unmarshal(outbound.Body, &legacyJob); err != nil {
+		return false
+	}
+	if strings.EqualFold(strings.TrimSpace(legacyJob.Metadata["skip_send"]), "true") {
+		return true
+	}
+	return strings.EqualFold(strings.TrimSpace(legacyJob.MessageType), "email_verify") &&
+		strings.EqualFold(strings.TrimSpace(legacyJob.Tags["source"]), "register")
+}
+
+func (d *OutboxDispatcher) failPermanently(ctx context.Context, message *auth.EmailOutboxMessage, err error) {
+	if message == nil || err == nil {
+		return
+	}
+	failedAt := time.Now().UTC()
+	if markErr := d.repo.MarkEmailOutboxMessageDead(ctx, message.ID, failedAt, err.Error()); markErr != nil {
+		d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+			snapshot.Failures++
+			snapshot.LastFailureAt = failedAt
+			snapshot.LastError = markErr.Error()
+		})
+		d.logger.Error("outbox dead-letter marking failed",
+			slog.String("message_id", message.MessageID),
+			slog.Any("error", markErr),
+		)
+		return
+	}
+	d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+		snapshot.Dead++
+		snapshot.LastFailureAt = failedAt
+		snapshot.LastError = err.Error()
+	})
+	d.logger.Error("outbox message marked dead",
+		slog.String("message_id", message.MessageID),
+		slog.String("job_type", message.JobType),
+		slog.Int("attempt", message.Attempts),
+		slog.Any("error", err),
+	)
+}
+
+func (d *OutboxDispatcher) refreshPending(ctx context.Context, now time.Time) {
+	count, err := d.repo.CountPendingEmailOutboxMessages(ctx, now)
+	if err != nil {
+		return
+	}
+	d.metrics.update(func(snapshot *OutboxMetricsSnapshot) {
+		snapshot.ApproximatePending = count
+	})
+}
+
+func hostname() string {
+	name, err := os.Hostname()
+	if err != nil || strings.TrimSpace(name) == "" {
+		return "worker"
+	}
+	return strings.TrimSpace(name)
+}
diff --git a/internal/app/worker/outbox_dispatcher_test.go b/internal/app/worker/outbox_dispatcher_test.go
new file mode 100644
index 0000000..6bfef0a
--- /dev/null
+++ b/internal/app/worker/outbox_dispatcher_test.go
@@ -0,0 +1,304 @@
+package worker
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"wucher/internal/config"
+	"wucher/internal/domain/auth"
+	"wucher/internal/queue"
+)
+
+type stubOutboxRepo struct {
+	messages map[string]*auth.EmailOutboxMessage
+}
+
+func newStubOutboxRepo(messages ...*auth.EmailOutboxMessage) *stubOutboxRepo {
+	repo := &stubOutboxRepo{messages: map[string]*auth.EmailOutboxMessage{}}
+	for _, message := range messages {
+		if message == nil {
+			continue
+		}
+		cp := *message
+		cp.ID = append([]byte(nil), message.ID...)
+		cp.Body = append([]byte(nil), message.Body...)
+		cp.Attributes = append([]byte(nil), message.Attributes...)
+		repo.messages[string(cp.ID)] = &cp
+	}
+	return repo
+}
+
+func (r *stubOutboxRepo) CreateEmailOutboxMessage(_ context.Context, message *auth.EmailOutboxMessage) error {
+	if message == nil {
+		return errors.New("nil message")
+	}
+	cp := *message
+	cp.ID = append([]byte(nil), message.ID...)
+	cp.Body = append([]byte(nil), message.Body...)
+	cp.Attributes = append([]byte(nil), message.Attributes...)
+	r.messages[string(cp.ID)] = &cp
+	return nil
+}
+
+func (r *stubOutboxRepo) ClaimPendingEmailOutboxMessages(_ context.Context, limit int, now time.Time, lockTTL time.Duration, workerID string) ([]auth.EmailOutboxMessage, error) {
+	if limit <= 0 {
+		limit = 1
+	}
+	if lockTTL <= 0 {
+		lockTTL = time.Minute
+	}
+	out := make([]auth.EmailOutboxMessage, 0, limit)
+	staleBefore := now.Add(-lockTTL)
+	for _, message := range r.messages {
+		if len(out) >= limit {
+			break
+		}
+		switch {
+		case message.Status == auth.EmailOutboxStatusPending && !message.AvailableAt.After(now):
+		case message.Status == auth.EmailOutboxStatusProcessing && message.LockedAt != nil && message.LockedAt.Before(staleBefore):
+		default:
+			continue
+		}
+		message.Status = auth.EmailOutboxStatusProcessing
+		message.Attempts++
+		ts := now
+		message.LockedAt = &ts
+		message.LockedBy = workerID
+		cp := *message
+		out = append(out, cp)
+	}
+	return out, nil
+}
+
+func (r *stubOutboxRepo) MarkEmailOutboxMessagePublished(_ context.Context, id []byte, publishedAt time.Time) error {
+	message := r.messages[string(id)]
+	if message == nil {
+		return errors.New("not found")
+	}
+	message.Status = auth.EmailOutboxStatusPublished
+	message.PublishedAt = &publishedAt
+	message.LockedAt = nil
+	message.LockedBy = ""
+	message.LastError = ""
+	return nil
+}
+
+func (r *stubOutboxRepo) MarkEmailOutboxMessageRetry(_ context.Context, id []byte, availableAt time.Time, lastErr string) error {
+	message := r.messages[string(id)]
+	if message == nil {
+		return errors.New("not found")
+	}
+	message.Status = auth.EmailOutboxStatusPending
+	message.AvailableAt = availableAt
+	message.LockedAt = nil
+	message.LockedBy = ""
+	message.LastError = lastErr
+	return nil
+}
+
+func (r *stubOutboxRepo) MarkEmailOutboxMessageDead(_ context.Context, id []byte, failedAt time.Time, lastErr string) error {
+	message := r.messages[string(id)]
+	if message == nil {
+		return errors.New("not found")
+	}
+	message.Status = auth.EmailOutboxStatusDead
+	message.AvailableAt = failedAt
+	message.LockedAt = nil
+	message.LockedBy = ""
+	message.LastError = lastErr
+	return nil
+}
+
+func (r *stubOutboxRepo) CountPendingEmailOutboxMessages(_ context.Context, now time.Time) (int64, error) {
+	var count int64
+	for _, message := range r.messages {
+		if (message.Status == auth.EmailOutboxStatusPending && !message.AvailableAt.After(now)) || message.Status == auth.EmailOutboxStatusProcessing {
+			count++
+		}
+	}
+	return count, nil
+}
+
+type stubQueueProducer struct {
+	published []queue.OutboundMessage
+	err       error
+}
+
+func (p *stubQueueProducer) Backend() string {
+	return "stub"
+}
+
+func (p *stubQueueProducer) Publish(_ context.Context, message queue.OutboundMessage) error {
+	if p.err != nil {
+		return p.err
+	}
+	p.published = append(p.published, message)
+	return nil
+}
+
+func newOutboxRecord(t *testing.T, job queue.EmailJob) *auth.EmailOutboxMessage {
+	t.Helper()
+	serializer := queue.NewJSONSerializer("v1", true, queue.QueueTypeStandard, "")
+	message, err := serializer.Serialize(context.Background(), job)
+	if err != nil {
+		t.Fatalf("serialize: %v", err)
+	}
+	record, err := auth.NewEmailOutboxMessage(time.Now().UTC(), message)
+	if err != nil {
+		t.Fatalf("new outbox message: %v", err)
+	}
+	return record
+}
+
+func TestOutboxDispatcherPublishSuccess(t *testing.T) {
+	record := newOutboxRecord(t, queue.EmailJob{
+		Type:    "email_verify",
+		To:      "user@example.com",
+		Subject: "Verify",
+		Body:    "hello",
+	})
+	repo := newStubOutboxRepo(record)
+	producer := &stubQueueProducer{}
+	dispatcher := NewOutboxDispatcher(config.QueueConfig{
+		OutboxEnabled:         true,
+		OutboxBatchSize:       10,
+		OutboxDispatchTimeout: time.Second,
+		OutboxLockTTL:         time.Minute,
+		OutboxMaxAttempts:     3,
+		WorkerBackoffMin:      time.Second,
+		WorkerBackoffMax:      time.Minute,
+	}, repo, producer, nil)
+
+	processed, err := dispatcher.dispatchOnce(context.Background())
+	if err != nil {
+		t.Fatalf("dispatch once: %v", err)
+	}
+	if processed != 1 {
+		t.Fatalf("expected one processed message, got %d", processed)
+	}
+	if len(producer.published) != 1 {
+		t.Fatalf("expected one published message, got %d", len(producer.published))
+	}
+	if repo.messages[string(record.ID)].Status != auth.EmailOutboxStatusPublished {
+		t.Fatalf("expected message published, got %s", repo.messages[string(record.ID)].Status)
+	}
+	if got := dispatcher.Metrics().Published; got != 1 {
+		t.Fatalf("expected published metric=1, got %d", got)
+	}
+}
+
+func TestOutboxDispatcherSkipRegisterVerifyEmail(t *testing.T) {
+	record := newOutboxRecord(t, queue.EmailJob{
+		MessageType: "email_verify",
+		To:          "user@example.com",
+		Subject:     "Verify",
+		TextBody:    "hello",
+		Metadata: map[string]string{
+			"skip_send": "true",
+		},
+		Tags: map[string]string{
+			"source": "register",
+		},
+	})
+	repo := newStubOutboxRepo(record)
+	producer := &stubQueueProducer{}
+	dispatcher := NewOutboxDispatcher(config.QueueConfig{
+		OutboxEnabled:         true,
+		OutboxBatchSize:       10,
+		OutboxDispatchTimeout: time.Second,
+		OutboxLockTTL:         time.Minute,
+		OutboxMaxAttempts:     3,
+		WorkerBackoffMin:      time.Second,
+		WorkerBackoffMax:      time.Minute,
+	}, repo, producer, nil)
+
+	processed, err := dispatcher.dispatchOnce(context.Background())
+	if err != nil {
+		t.Fatalf("dispatch once: %v", err)
+	}
+	if processed != 1 {
+		t.Fatalf("expected one processed message, got %d", processed)
+	}
+	if len(producer.published) != 0 {
+		t.Fatalf("expected zero published message, got %d", len(producer.published))
+	}
+	if repo.messages[string(record.ID)].Status != auth.EmailOutboxStatusPublished {
+		t.Fatalf("expected message published status after skip, got %s", repo.messages[string(record.ID)].Status)
+	}
+}
+
+func TestOutboxDispatcherRetryOnPublishFailure(t *testing.T) {
+	record := newOutboxRecord(t, queue.EmailJob{
+		Type:    "password_reset",
+		To:      "user@example.com",
+		Subject: "Reset",
+		Body:    "reset",
+	})
+	repo := newStubOutboxRepo(record)
+	producer := &stubQueueProducer{err: errors.New("queue unavailable")}
+	dispatcher := NewOutboxDispatcher(config.QueueConfig{
+		OutboxEnabled:     true,
+		OutboxBatchSize:   10,
+		OutboxLockTTL:     time.Minute,
+		OutboxMaxAttempts: 3,
+		WorkerBackoffMin:  time.Second,
+		WorkerBackoffMax:  time.Minute,
+	}, repo, producer, nil)
+
+	processed, err := dispatcher.dispatchOnce(context.Background())
+	if err != nil {
+		t.Fatalf("dispatch once: %v", err)
+	}
+	if processed != 1 {
+		t.Fatalf("expected one processed message, got %d", processed)
+	}
+	got := repo.messages[string(record.ID)]
+	if got.Status != auth.EmailOutboxStatusPending {
+		t.Fatalf("expected message returned to pending, got %s", got.Status)
+	}
+	if got.Attempts != 1 {
+		t.Fatalf("expected attempts=1, got %d", got.Attempts)
+	}
+	if !got.AvailableAt.After(time.Now().Add(-time.Second)) {
+		t.Fatalf("expected retry to schedule next attempt in the future")
+	}
+	if metrics := dispatcher.Metrics(); metrics.Retried != 1 {
+		t.Fatalf("expected retried metric=1, got %d", metrics.Retried)
+	}
+}
+
+func TestOutboxDispatcherMarksDeadAfterMaxAttempts(t *testing.T) {
+	record := newOutboxRecord(t, queue.EmailJob{
+		Type:    "invite_set_password",
+		To:      "user@example.com",
+		Subject: "Invite",
+		Body:    "invite",
+	})
+	record.Attempts = 2
+	repo := newStubOutboxRepo(record)
+	producer := &stubQueueProducer{err: errors.New("queue unavailable")}
+	dispatcher := NewOutboxDispatcher(config.QueueConfig{
+		OutboxEnabled:     true,
+		OutboxBatchSize:   10,
+		OutboxLockTTL:     time.Minute,
+		OutboxMaxAttempts: 3,
+		WorkerBackoffMin:  time.Second,
+		WorkerBackoffMax:  time.Minute,
+	}, repo, producer, nil)
+
+	processed, err := dispatcher.dispatchOnce(context.Background())
+	if err != nil {
+		t.Fatalf("dispatch once: %v", err)
+	}
+	if processed != 1 {
+		t.Fatalf("expected one processed message, got %d", processed)
+	}
+	if got := repo.messages[string(record.ID)].Status; got != auth.EmailOutboxStatusDead {
+		t.Fatalf("expected dead status, got %s", got)
+	}
+	if got := dispatcher.Metrics().Dead; got != 1 {
+		t.Fatalf("expected dead metric=1, got %d", got)
+	}
+}
diff --git a/internal/app/worker/runner.go b/internal/app/worker/runner.go
new file mode 100644
index 0000000..d325643
--- /dev/null
+++ b/internal/app/worker/runner.go
@@ -0,0 +1,196 @@
+package worker
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"time"
+
+	"wucher/internal/config"
+	"wucher/internal/shared/pkg/metrics"
+	"wucher/internal/queue"
+)
+
+type Runner struct {
+	worker            *queue.Worker
+	consumer          queue.QueueConsumer
+	dispatcher        *OutboxDispatcher
+	logger            *slog.Logger
+	monitorAddr       string
+	depthPollInterval time.Duration
+	shutdownTimeout   time.Duration
+	backend           string
+	monitorServer     *http.Server
+}
+
+func NewRunner(
+	cfg config.QueueConfig,
+	consumer queue.QueueConsumer,
+	serializer queue.MessageSerializer,
+	handler queue.EmailJobHandler,
+	idempotency queue.IdempotencyStore,
+	dispatcher *OutboxDispatcher,
+	logger *slog.Logger,
+) *Runner {
+	if logger == nil {
+		logger = slog.Default()
+	}
+	metrics := queue.NewMetrics()
+	health := queue.NewHealthReporter(cfg.WorkerHealthErrorThreshold)
+	worker := queue.NewWorker(queue.WorkerConfig{
+		Concurrency:      cfg.WorkerConcurrency,
+		MaxBatchSize:     cfg.WorkerMaxBatchSize,
+		ProcessTimeout:   cfg.WorkerProcessTimeout,
+		ProcessingTTL:    cfg.ProcessingTTL,
+		IdempotencyTTL:   cfg.IdempotencyTTL,
+		PollErrorDelay:   cfg.WorkerBackoffMin,
+		MetricsComponent: "email_worker",
+	}, consumer, serializer, handler, queue.NewExponentialBackoffPolicy(cfg.WorkerBackoffMin, cfg.WorkerBackoffMax, cfg.WorkerPermanentFailureDelay), idempotency, metrics, health, logger)
+
+	backend := ""
+	if consumer != nil {
+		backend = consumer.Backend()
+	}
+	return &Runner{
+		worker:            worker,
+		consumer:          consumer,
+		dispatcher:        dispatcher,
+		logger:            logger,
+		monitorAddr:       cfg.WorkerMonitorAddr,
+		depthPollInterval: cfg.WorkerDepthPollInterval,
+		shutdownTimeout:   cfg.WorkerShutdownTimeout,
+		backend:           backend,
+	}
+}
+
+func (r *Runner) Start(ctx context.Context) error {
+	if r.worker == nil {
+		return errors.New("worker is required")
+	}
+	runCtx, cancelRun := context.WithCancel(ctx)
+	defer cancelRun()
+	if err := r.startMonitor(); err != nil {
+		return err
+	}
+	pollerDone := make(chan struct{})
+	go func() {
+		defer close(pollerDone)
+		r.runDepthPoller(runCtx)
+	}()
+
+	workerErrCh := make(chan error, 1)
+	go func() {
+		workerErrCh <- r.worker.Run(runCtx)
+	}()
+
+	var dispatcherErrCh chan error
+	if r.dispatcher != nil {
+		dispatcherErrCh = make(chan error, 1)
+		go func() {
+			dispatcherErrCh <- r.dispatcher.Run(runCtx)
+		}()
+	}
+
+	var err error
+	select {
+	case err = <-workerErrCh:
+		cancelRun()
+		if dispatcherErrCh != nil {
+			if dispatcherErr := <-dispatcherErrCh; err == nil {
+				err = dispatcherErr
+			}
+		}
+	case err = <-dispatcherErrCh:
+		cancelRun()
+		if workerErr := <-workerErrCh; err == nil {
+			err = workerErr
+		}
+	}
+
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), r.shutdownTimeout)
+	defer cancel()
+	if r.monitorServer != nil {
+		_ = r.monitorServer.Shutdown(shutdownCtx)
+	}
+	if r.consumer != nil {
+		_ = r.consumer.Close()
+	}
+	<-pollerDone
+	return err
+}
+
+func (r *Runner) startMonitor() error {
+	if r.monitorAddr == "" {
+		return nil
+	}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/health", r.handleHealth)
+	mux.Handle("/metrics", metrics.PromHTTPHandler())
+	r.monitorServer = &http.Server{
+		Addr:              r.monitorAddr,
+		Handler:           mux,
+		ReadHeaderTimeout: 5 * time.Second,
+	}
+	go func() {
+		r.logger.Info("worker monitor listening",
+			slog.String("addr", r.monitorAddr),
+			slog.String("backend", r.backend),
+		)
+		if err := r.monitorServer.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			r.logger.Error("worker monitor failed", slog.Any("error", err))
+		}
+	}()
+	return nil
+}
+
+func (r *Runner) runDepthPoller(ctx context.Context) {
+	if r.depthPollInterval <= 0 {
+		return
+	}
+	ticker := time.NewTicker(r.depthPollInterval)
+	defer ticker.Stop()
+	for {
+		refreshCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+		_ = r.worker.RefreshQueueDepth(refreshCtx)
+		cancel()
+
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+		}
+	}
+}
+
+func (r *Runner) handleHealth(w http.ResponseWriter, _ *http.Request) {
+	snapshot := struct {
+		Backend string                 `json:"backend"`
+		Health  queue.HealthSnapshot   `json:"health"`
+		Metrics queue.MetricsSnapshot  `json:"metrics"`
+		Outbox  *OutboxMetricsSnapshot `json:"outbox,omitempty"`
+	}{
+		Backend: r.backend,
+		Health:  r.worker.Health().Snapshot(),
+		Metrics: r.worker.Metrics().Snapshot(),
+	}
+	if r.dispatcher != nil {
+		snapshot.Outbox = ptr(r.dispatcher.Metrics())
+	}
+	statusCode := http.StatusOK
+	if snapshot.Health.Status == "degraded" {
+		statusCode = http.StatusServiceUnavailable
+	}
+	writeJSON(w, statusCode, snapshot)
+}
+
+func writeJSON(w http.ResponseWriter, statusCode int, payload any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(statusCode)
+	_ = json.NewEncoder(w).Encode(payload)
+}
+
+func ptr[T any](v T) *T {
+	return &v
+}
diff --git a/internal/auth/handler.go b/internal/auth/handler.go
new file mode 100644
index 0000000..b0df56d
--- /dev/null
+++ b/internal/auth/handler.go
@@ -0,0 +1,699 @@
+package auth
+
+import (
+	"bytes"
+	"compress/flate"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/rsa"
+	"crypto/sha1"
+	"crypto/sha256"
+	"crypto/sha512"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"log"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/beevik/etree"
+	"github.com/crewjam/saml"
+	"github.com/gofiber/fiber/v2"
+	dsig "github.com/russellhaering/goxmldsig"
+	"github.com/valyala/fasthttp/fasthttpadaptor"
+	"wucher/internal/config"
+	"wucher/internal/service"
+)
+
+type Handler struct {
+	cfg  config.Config
+	auth *service.AuthService
+}
+
+func NewHandler(cfg config.Config, authSvc *service.AuthService) *Handler {
+	return &Handler{cfg: cfg, auth: authSvc}
+}
+
+func (h *Handler) HandleSAMLCallback(c *fiber.Ctx) error {
+	if SAMLMiddleware == nil {
+		return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": "saml is not initialized"})
+	}
+	req, err := toHTTPRequest(c)
+	if err != nil {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "invalid request"})
+	}
+	if err := req.ParseForm(); err != nil {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "invalid form payload"})
+	}
+	assertion, err := SAMLMiddleware.ServiceProvider.ParseResponse(req, []string{""})
+	if err != nil {
+		resp := fiber.Map{"error": "invalid saml response"}
+		if strings.EqualFold(h.cfg.AppEnv, "development") || strings.EqualFold(h.cfg.AppEnv, "local") {
+			resp["detail"] = err.Error()
+			var invalidRespErr *saml.InvalidResponseError
+			if errors.As(err, &invalidRespErr) && invalidRespErr.PrivateErr != nil {
+				resp["private_detail"] = invalidRespErr.PrivateErr.Error()
+			}
+			if raw := c.FormValue("SAMLResponse"); raw != "" {
+				if statusCode, statusMessage := samlResponseStatus(raw); statusCode != "" || statusMessage != "" {
+					resp["status_code"] = statusCode
+					resp["status_message"] = statusMessage
+				}
+			}
+		}
+		return c.Status(fiber.StatusUnauthorized).JSON(resp)
+	}
+
+	nameID := ""
+	email := ""
+	givenName := ""
+	surname := ""
+	displayName := ""
+	if assertion.Subject != nil {
+		nameID = assertion.Subject.NameID.Value
+	}
+	for _, stmt := range assertion.AttributeStatements {
+		for _, attr := range stmt.Attributes {
+			if len(attr.Values) == 0 {
+				continue
+			}
+			val := attr.Values[0].Value
+			switch attr.Name {
+			case "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "emailaddress":
+				email = val
+			case "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname", "givenname":
+				givenName = val
+			case "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", "surname":
+				surname = val
+			case "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", "name":
+				displayName = val
+			}
+		}
+	}
+	if displayName == "" {
+		displayName = givenName + " " + surname
+	}
+
+	now := time.Now().UTC()
+	session := UserSession{
+		UserID:          nameID,
+		MicrosoftNameID: nameID,
+		Email:           email,
+		Name:            displayName,
+		LoggedInAt:      now,
+		ExpiresAt:       now.Add(time.Duration(h.cfg.SessionTTLHour) * time.Hour),
+	}
+	token, err := CreateSession(session)
+	if err != nil {
+		return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": "create session failed"})
+	}
+
+	if h.auth != nil {
+		claims := map[string]any{
+			"sub":   nameID,
+			"email": email,
+			"name":  displayName,
+			"oid":   nameID,
+			"exp":   time.Now().UTC().Add(5 * time.Minute).Unix(),
+		}
+		identity, err := h.auth.ExchangeMicrosoftToken(c.UserContext(), "saml_access", "saml_id", claims)
+		if err == nil && identity != nil {
+			user, userErr := h.auth.GetUserByID(c.UserContext(), identity.UserID)
+			if userErr == nil && user != nil {
+				tokens, tokenErr := h.auth.IssueTokensWithClientForProviderAndDeviceType(
+					c.UserContext(),
+					user,
+					c.Get(fiber.HeaderUserAgent),
+					c.IP(),
+					"microsoft",
+					readDeviceTypeHint(c),
+				)
+				if tokenErr == nil {
+					setAuthCookies(c, h.auth, tokens)
+				}
+			}
+		}
+	}
+
+	c.Cookie(&fiber.Cookie{
+		Name:     "session_token",
+		Value:    token,
+		HTTPOnly: true,
+		Secure:   h.cfg.CookieSecure,
+		SameSite: "lax",
+		Path:     "/",
+		Domain:   h.cfg.CookieDomain,
+		Expires:  session.ExpiresAt,
+	})
+	return c.Redirect(h.cfg.FrontendURL+"/dashboard", fiber.StatusFound)
+}
+
+func (h *Handler) HandleSLO(c *fiber.Ctx) error {
+	return h.HandleSAMLLogoutRequest(c)
+}
+
+func (h *Handler) HandleSAMLLogoutRequest(c *fiber.Ctx) error {
+	if SAMLMiddleware == nil {
+		return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": "saml is not initialized"})
+	}
+	log.Printf("saml logout request: has_saml_request=%t has_saml_response=%t method=%s", formOrQuery(c, "SAMLRequest") != "", formOrQuery(c, "SAMLResponse") != "", c.Method())
+	rawReq := formOrQuery(c, "SAMLRequest")
+	if rawReq == "" {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "missing SAMLRequest"})
+	}
+
+	xmlBytes, err := decodeSAMLMessage(rawReq)
+	if err != nil {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "invalid SAMLRequest encoding"})
+	}
+	if c.Method() == fiber.MethodGet {
+		if err := validateRedirectSAMLSignature(c); err != nil {
+			return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "invalid SAMLRequest signature"})
+		}
+	} else {
+		if err := validateLogoutRequestSignature(xmlBytes); err != nil {
+			return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "invalid SAMLRequest signature"})
+		}
+	}
+
+	var logoutReq saml.LogoutRequest
+	if err := xml.Unmarshal(xmlBytes, &logoutReq); err != nil {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "invalid LogoutRequest XML"})
+	}
+	if err := validateSAMLMessageIssuer(logoutReq.Issuer.Value); err != nil {
+		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "invalid SAMLRequest issuer"})
+	}
+	nameID := strings.TrimSpace(logoutReq.NameID.Value)
+	h.cleanupUserAuthSession(c, nameID)
+	log.Printf("saml logout request processed: name_id_present=%t", nameID != "")
+
+	relayState := formOrQuery(c, "RelayState")
+	redirectURL, err := SAMLMiddleware.ServiceProvider.MakeRedirectLogoutResponse(logoutReq.ID, relayState)
+	if err != nil {
+		return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": "failed to build LogoutResponse"})
+	}
+	return c.Redirect(redirectURL.String(), fiber.StatusFound)
+}
+
+func (h *Handler) HandleSAMLLogoutResponse(c *fiber.Ctx) error {
+	if SAMLMiddleware == nil {
+		return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": "saml is not initialized"})
+	}
+	rawQuery := c.Context().QueryArgs().String()
+	hasSAMLResponse := formOrQuery(c, "SAMLResponse") != ""
+	hasRelayState := formOrQuery(c, "RelayState") != ""
+	hasSigAlg := formOrQuery(c, "SigAlg") != ""
+	hasSignature := formOrQuery(c, "Signature") != ""
+	sigAlg := formOrQuery(c, "SigAlg")
+	log.Printf("saml logout response: method=%s path=%s hasSAMLResponse=%t hasRelayState=%t hasSigAlg=%t hasSignature=%t sigAlg=%q rawQueryLen=%d",
+		c.Method(), c.Path(), hasSAMLResponse, hasRelayState, hasSigAlg, hasSignature, sigAlg, len(rawQuery))
+	rawResp := formOrQuery(c, "SAMLResponse")
+	if rawResp == "" {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "missing SAMLResponse"})
+	}
+
+	if c.Method() == fiber.MethodGet && hasSigAlg && hasSignature {
+		if err := validateRedirectSAMLSignatureRaw(rawQuery, "SAMLResponse"); err != nil {
+			log.Printf("saml logout response: verification_result=failed mode=redirect reason=%v", err)
+			return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "invalid SAMLResponse signature"})
+		}
+		log.Printf("saml logout response: verification_result=ok mode=redirect")
+	}
+
+	xmlBytes, err := decodeSAMLMessage(rawResp)
+	if err != nil {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "invalid SAMLResponse encoding"})
+	}
+
+	if c.Method() == fiber.MethodGet && !(hasSigAlg && hasSignature) {
+		if hasSigAlg != hasSignature {
+			return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "missing SAMLResponse signature"})
+		}
+		if !hasXMLSignature(xmlBytes) {
+			return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "missing SAMLResponse signature"})
+		}
+		if err := validateLogoutResponseSignature(xmlBytes); err != nil {
+			return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "invalid SAMLResponse signature"})
+		}
+	} else if c.Method() != fiber.MethodGet {
+		if err := validateLogoutResponseSignature(xmlBytes); err != nil {
+			return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "invalid SAMLResponse signature"})
+		}
+	}
+
+	var logoutResp saml.LogoutResponse
+	if err := xml.Unmarshal(xmlBytes, &logoutResp); err != nil {
+		return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{"error": "invalid LogoutResponse XML"})
+	}
+	if err := validateSAMLMessageIssuer(logoutResp.Issuer.Value); err != nil {
+		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "invalid SAMLResponse issuer"})
+	}
+	if strings.TrimSpace(logoutResp.Status.StatusCode.Value) != saml.StatusSuccess {
+		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "invalid SAMLResponse status"})
+	}
+	h.cleanupUserAuthSession(c, "")
+	return c.Redirect(h.logoutRedirectURL(), fiber.StatusFound)
+}
+
+func (h *Handler) HandleMetadata(c *fiber.Ctx) error {
+	if SAMLMiddleware == nil {
+		return c.Status(fiber.StatusInternalServerError).SendString("saml is not initialized")
+	}
+	buf, err := xml.MarshalIndent(SAMLMiddleware.ServiceProvider.Metadata(), "", "  ")
+	if err != nil {
+		return c.Status(fiber.StatusInternalServerError).SendString("failed to marshal metadata")
+	}
+	c.Set(fiber.HeaderContentType, "application/samlmetadata+xml")
+	return c.Send(buf)
+}
+
+func (h *Handler) HandleLogin(c *fiber.Ctx) error {
+	if SAMLMiddleware == nil {
+		return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": "saml is not initialized"})
+	}
+	redirectURL, err := SAMLMiddleware.ServiceProvider.MakeRedirectAuthenticationRequest("")
+	if err != nil {
+		return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{"error": "failed to build authn request"})
+	}
+	if wantsJSON(c) {
+		return c.Status(fiber.StatusOK).JSON(fiber.Map{
+			"data": fiber.Map{
+				"type": "auth_microsoft_url",
+				"attributes": fiber.Map{
+					"url":          redirectURL.String(),
+					"redirect_url": redirectURL.String(),
+				},
+			},
+		})
+	}
+	return c.Redirect(redirectURL.String(), fiber.StatusFound)
+}
+
+func (h *Handler) HandleLogout(c *fiber.Ctx) error {
+	return h.HandleBrowserLocalLogout(c)
+}
+
+func (h *Handler) HandleBrowserLocalLogout(c *fiber.Ctx) error {
+	log.Printf("browser local logout: method=%s", c.Method())
+	var nameID string
+	if token := strings.TrimSpace(c.Cookies("session_token")); token != "" {
+		if sess, err := GetSession(token); err == nil {
+			nameID = strings.TrimSpace(sess.MicrosoftNameID)
+		}
+	}
+	h.cleanupUserAuthSession(c, nameID)
+	if nameID != "" && SAMLMiddleware != nil {
+		redirectURL, err := SAMLMiddleware.ServiceProvider.MakeRedirectLogoutRequest(nameID, "")
+		if err == nil {
+			return c.Redirect(redirectURL.String(), fiber.StatusFound)
+		}
+	}
+	return c.Redirect(h.logoutRedirectURL(), fiber.StatusFound)
+}
+
+func toHTTPRequest(c *fiber.Ctx) (*http.Request, error) {
+	r := new(http.Request)
+	if err := fasthttpadaptor.ConvertRequest(c.Context(), r, true); err != nil {
+		return nil, err
+	}
+	return r, nil
+}
+
+func validateLogoutRequestSignature(xmlBytes []byte) error {
+	certs, err := getIDPCertificates()
+	if err != nil {
+		return err
+	}
+	certStore := dsig.MemoryX509CertificateStore{Roots: certs}
+	validator := dsig.NewDefaultValidationContext(&certStore)
+
+	doc := etree.NewDocument()
+	if err := doc.ReadFromBytes(xmlBytes); err != nil {
+		return fmt.Errorf("parse xml: %w", err)
+	}
+	root := doc.Root()
+	if root == nil {
+		return fmt.Errorf("empty xml")
+	}
+	_, err = validator.Validate(root)
+	return err
+}
+
+func validateRedirectSAMLSignature(c *fiber.Ctx) error {
+	rawQuery := c.Context().QueryArgs().String()
+	return validateRedirectSAMLSignatureRaw(rawQuery, "")
+}
+
+func validateRedirectSAMLSignatureRaw(rawQuery, expectedMessageKey string) error {
+	params, err := url.ParseQuery(rawQuery)
+	if err != nil {
+		return fmt.Errorf("invalid query: %w", err)
+	}
+
+	sigAlg := params.Get("SigAlg")
+	signatureB64 := params.Get("Signature")
+	if sigAlg == "" || signatureB64 == "" {
+		return fmt.Errorf("missing SigAlg or Signature")
+	}
+
+	signedPayload, err := buildRedirectSignaturePayload(rawQuery, expectedMessageKey)
+	if err != nil {
+		return err
+	}
+	log.Printf("saml redirect signature: canonicalLen=%d", len(signedPayload))
+
+	signature, err := base64.StdEncoding.DecodeString(signatureB64)
+	if err != nil {
+		return fmt.Errorf("invalid signature encoding: %w", err)
+	}
+
+	certs, err := getIDPCertificates()
+	if err != nil {
+		return err
+	}
+	for _, cert := range certs {
+		log.Printf("saml redirect signature: certThumbprint=%s", certificateThumbprintSHA1(cert))
+		if err := verifyRedirectSignature(cert.PublicKey, sigAlg, signedPayload, signature); err == nil {
+			return nil
+		}
+	}
+	return fmt.Errorf("signature verification failed")
+}
+
+func buildRedirectSignaturePayload(rawQuery, expectedMessageKey string) ([]byte, error) {
+	var samlReq, samlResp, relay, sigAlg string
+	for _, part := range strings.Split(rawQuery, "&") {
+		if part == "" {
+			continue
+		}
+		key, val, found := strings.Cut(part, "=")
+		if !found {
+			continue
+		}
+		switch key {
+		case "SAMLRequest":
+			if samlReq == "" {
+				samlReq = val
+			}
+		case "SAMLResponse":
+			if samlResp == "" {
+				samlResp = val
+			}
+		case "RelayState":
+			if relay == "" {
+				relay = val
+			}
+		case "SigAlg":
+			if sigAlg == "" {
+				sigAlg = val
+			}
+		}
+	}
+
+	msgKey := "SAMLRequest"
+	msgVal := samlReq
+	if msgVal == "" {
+		msgKey = "SAMLResponse"
+		msgVal = samlResp
+	}
+	if expectedMessageKey != "" && msgKey != expectedMessageKey {
+		return nil, fmt.Errorf("missing %s", expectedMessageKey)
+	}
+	if msgVal == "" || sigAlg == "" {
+		return nil, fmt.Errorf("missing SAML payload or SigAlg")
+	}
+
+	payload := msgKey + "=" + msgVal
+	if relay != "" {
+		payload += "&RelayState=" + relay
+	}
+	payload += "&SigAlg=" + sigAlg
+	return []byte(payload), nil
+}
+
+func validateLogoutResponseSignature(xmlBytes []byte) error {
+	return validateLogoutRequestSignature(xmlBytes)
+}
+
+func hasXMLSignature(xmlBytes []byte) bool {
+	doc := etree.NewDocument()
+	if err := doc.ReadFromBytes(xmlBytes); err != nil {
+		return false
+	}
+	root := doc.Root()
+	if root == nil {
+		return false
+	}
+	for _, el := range root.FindElements(".//*") {
+		if strings.EqualFold(el.Tag, "Signature") || strings.HasSuffix(el.Tag, ":Signature") {
+			return true
+		}
+	}
+	return false
+}
+
+func certificateThumbprintSHA1(cert *x509.Certificate) string {
+	if cert == nil {
+		return ""
+	}
+	sum := sha1.Sum(cert.Raw)
+	return strings.ToUpper(hex.EncodeToString(sum[:]))
+}
+
+func validateSAMLMessageIssuer(issuer string) error {
+	issuer = strings.TrimSpace(issuer)
+	if issuer == "" {
+		return fmt.Errorf("missing issuer")
+	}
+	if SAMLMiddleware == nil || SAMLMiddleware.ServiceProvider.IDPMetadata == nil {
+		return fmt.Errorf("missing idp metadata")
+	}
+	expected := strings.TrimSpace(SAMLMiddleware.ServiceProvider.IDPMetadata.EntityID)
+	if expected == "" {
+		return fmt.Errorf("missing expected issuer")
+	}
+	if issuer != expected {
+		return fmt.Errorf("unexpected issuer")
+	}
+	return nil
+}
+
+func (h *Handler) cleanupUserAuthSession(c *fiber.Ctx, nameID string) {
+	if strings.TrimSpace(nameID) != "" {
+		_ = DeleteSessionByNameID(nameID)
+	}
+	if token := strings.TrimSpace(c.Cookies("session_token")); token != "" {
+		_ = DeleteSession(token)
+	}
+	clearSessionCookie(c, h.cfg.CookieDomain, h.cfg.CookieSecure)
+	if h.auth == nil {
+		return
+	}
+	accessToken := strings.TrimSpace(c.Cookies(h.auth.AccessCookieName()))
+	refreshToken := strings.TrimSpace(c.Cookies(h.auth.RefreshCookieName()))
+	if accessToken != "" {
+		if userID, err := h.auth.ParseAccessToken(c.UserContext(), accessToken); err == nil && len(userID) == 16 {
+			_ = h.auth.RevokeAllUserSessions(c.UserContext(), userID)
+			log.Printf("logout cleanup: revoked app sessions user_id=%x", userID)
+		}
+	}
+	if refreshToken != "" {
+		_ = h.auth.RevokeRefreshToken(c.UserContext(), refreshToken)
+	}
+	clearAuthCookies(c, h.auth)
+}
+
+func clearSessionCookie(c *fiber.Ctx, domain string, secure bool) {
+	c.Cookie(&fiber.Cookie{
+		Name:     "session_token",
+		Value:    "",
+		Path:     "/",
+		Domain:   domain,
+		HTTPOnly: true,
+		Secure:   secure,
+		SameSite: "lax",
+		MaxAge:   -1,
+		Expires:  time.Unix(0, 0),
+	})
+}
+
+func clearAuthCookies(c *fiber.Ctx, svc *service.AuthService) {
+	if svc == nil {
+		return
+	}
+	c.Cookie(&fiber.Cookie{
+		Name:     svc.AccessCookieName(),
+		Value:    "",
+		HTTPOnly: true,
+		Secure:   svc.CookieSecure(),
+		SameSite: parseSameSite(svc.CookieSameSite()),
+		Domain:   svc.CookieDomain(),
+		Path:     "/",
+		MaxAge:   -1,
+	})
+	c.Cookie(&fiber.Cookie{
+		Name:     svc.RefreshCookieName(),
+		Value:    "",
+		HTTPOnly: true,
+		Secure:   svc.CookieSecure(),
+		SameSite: parseSameSite(svc.CookieSameSite()),
+		Domain:   svc.CookieDomain(),
+		Path:     "/api/v1/auth/refresh",
+		MaxAge:   -1,
+	})
+}
+
+func (h *Handler) logoutRedirectURL() string {
+	base := strings.TrimRight(strings.TrimSpace(h.cfg.FrontendURL), "/")
+	if base == "" {
+		return "/signin?loggedOut=true"
+	}
+	return base + "/signin?loggedOut=true"
+}
+
+func verifyRedirectSignature(pub any, sigAlg string, payload, signature []byte) error {
+	switch sigAlg {
+	case "http://www.w3.org/2000/09/xmldsig#rsa-sha1":
+		sum := sha1.Sum(payload)
+		key, ok := pub.(*rsa.PublicKey)
+		if !ok {
+			return fmt.Errorf("unexpected key type %T", pub)
+		}
+		return rsa.VerifyPKCS1v15(key, crypto.SHA1, sum[:], signature)
+	case "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256":
+		sum := sha256.Sum256(payload)
+		key, ok := pub.(*rsa.PublicKey)
+		if !ok {
+			return fmt.Errorf("unexpected key type %T", pub)
+		}
+		return rsa.VerifyPKCS1v15(key, crypto.SHA256, sum[:], signature)
+	case "http://www.w3.org/2001/04/xmldsig-more#rsa-sha384":
+		sum := sha512.Sum384(payload)
+		key, ok := pub.(*rsa.PublicKey)
+		if !ok {
+			return fmt.Errorf("unexpected key type %T", pub)
+		}
+		return rsa.VerifyPKCS1v15(key, crypto.SHA384, sum[:], signature)
+	case "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512":
+		sum := sha512.Sum512(payload)
+		key, ok := pub.(*rsa.PublicKey)
+		if !ok {
+			return fmt.Errorf("unexpected key type %T", pub)
+		}
+		return rsa.VerifyPKCS1v15(key, crypto.SHA512, sum[:], signature)
+	case "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256":
+		sum := sha256.Sum256(payload)
+		key, ok := pub.(*ecdsa.PublicKey)
+		if !ok {
+			return fmt.Errorf("unexpected key type %T", pub)
+		}
+		if ecdsa.VerifyASN1(key, sum[:], signature) {
+			return nil
+		}
+		return fmt.Errorf("ecdsa verify failed")
+	default:
+		return fmt.Errorf("unsupported SigAlg %q", sigAlg)
+	}
+}
+
+func formOrQuery(c *fiber.Ctx, key string) string {
+	if v := strings.TrimSpace(c.FormValue(key)); v != "" {
+		return v
+	}
+	return strings.TrimSpace(c.Query(key))
+}
+
+func decodeSAMLMessage(raw string) ([]byte, error) {
+	decoded, err := base64.StdEncoding.DecodeString(raw)
+	if err != nil {
+		return nil, err
+	}
+	if bytes.Contains(decoded, []byte("<")) {
+		return decoded, nil
+	}
+
+	reader := flate.NewReader(bytes.NewReader(decoded))
+	defer reader.Close()
+	var out bytes.Buffer
+	if _, err := out.ReadFrom(reader); err != nil {
+		return nil, err
+	}
+	return out.Bytes(), nil
+}
+
+func samlResponseStatus(raw string) (string, string) {
+	decoded, err := base64.StdEncoding.DecodeString(raw)
+	if err != nil {
+		return "", ""
+	}
+
+	var resp saml.Response
+	if err := xml.Unmarshal(decoded, &resp); err != nil {
+		return "", ""
+	}
+
+	if resp.Status.StatusCode.Value == "" && resp.Status.StatusMessage == nil {
+		return "", ""
+	}
+
+	statusMessage := ""
+	if resp.Status.StatusMessage != nil {
+		statusMessage = strings.TrimSpace(resp.Status.StatusMessage.Value)
+	}
+	return resp.Status.StatusCode.Value, statusMessage
+}
+
+func readDeviceTypeHint(c *fiber.Ctx) string {
+	return strings.TrimSpace(c.Get("X-Device-Type"))
+}
+
+func setAuthCookies(c *fiber.Ctx, svc *service.AuthService, tokens service.TokenPair) {
+	if svc == nil {
+		return
+	}
+	refreshTTL := tokens.RefreshTTL
+	if refreshTTL <= 0 {
+		refreshTTL = svc.RefreshTTL()
+	}
+	c.Cookie(&fiber.Cookie{
+		Name:     svc.AccessCookieName(),
+		Value:    tokens.AccessToken,
+		HTTPOnly: true,
+		Secure:   svc.CookieSecure(),
+		SameSite: parseSameSite(svc.CookieSameSite()),
+		Domain:   svc.CookieDomain(),
+		Path:     "/",
+		MaxAge:   int(svc.AccessTTL().Seconds()),
+	})
+	c.Cookie(&fiber.Cookie{
+		Name:     svc.RefreshCookieName(),
+		Value:    tokens.RefreshToken,
+		HTTPOnly: true,
+		Secure:   svc.CookieSecure(),
+		SameSite: parseSameSite(svc.CookieSameSite()),
+		Domain:   svc.CookieDomain(),
+		Path:     "/api/v1/auth/refresh",
+		MaxAge:   int(refreshTTL.Seconds()),
+	})
+}
+
+func parseSameSite(v string) string {
+	switch strings.ToLower(strings.TrimSpace(v)) {
+	case "none":
+		return "none"
+	case "strict":
+		return "strict"
+	default:
+		return "lax"
+	}
+}
+
+func wantsJSON(c *fiber.Ctx) bool {
+	accept := strings.ToLower(strings.TrimSpace(c.Get(fiber.HeaderAccept)))
+	return strings.Contains(accept, "application/json") || strings.Contains(accept, "application/vnd.api+json")
+}
diff --git a/internal/auth/handler_logout_test.go b/internal/auth/handler_logout_test.go
new file mode 100644
index 0000000..614d7f5
--- /dev/null
+++ b/internal/auth/handler_logout_test.go
@@ -0,0 +1,257 @@
+package auth
+
+import (
+	"crypto"
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/sha1"
+	"crypto/sha256"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/base64"
+	"encoding/hex"
+	"fmt"
+	"math/big"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/crewjam/saml"
+	"github.com/crewjam/saml/samlsp"
+	"github.com/gofiber/fiber/v2"
+	"wucher/internal/config"
+)
+
+func TestHandleBrowserLocalLogout_RedirectAndClearSessionCookie(t *testing.T) {
+	prev := SAMLMiddleware
+	SAMLMiddleware = nil
+	t.Cleanup(func() { SAMLMiddleware = prev })
+
+	h := NewHandler(config.Config{
+		FrontendURL:  "https://wfm-dev.mybit.co.id",
+		CookieDomain: ".mybit.co.id",
+		CookieSecure: true,
+	}, nil)
+
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/logout", h.HandleBrowserLocalLogout)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/logout", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusFound {
+		t.Fatalf("expected 302, got %d", resp.StatusCode)
+	}
+	if got := resp.Header.Get("Location"); got != "https://wfm-dev.mybit.co.id/signin?loggedOut=true" {
+		t.Fatalf("unexpected redirect: %s", got)
+	}
+
+	setCookie := strings.Join(resp.Header.Values("Set-Cookie"), "\n")
+	if !strings.Contains(setCookie, "session_token=") {
+		t.Fatalf("expected session_token clear cookie, got %q", setCookie)
+	}
+	if !strings.Contains(strings.ToLower(setCookie), "domain=.mybit.co.id") {
+		t.Fatalf("expected cookie domain .mybit.co.id, got %q", setCookie)
+	}
+}
+
+func TestBuildRedirectSignaturePayload_PreservesRawEncoding(t *testing.T) {
+	raw := "SAMLResponse=abc%2B123%3D%3D&RelayState=x%2By%252Fz&SigAlg=http%3A%2F%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256&Signature=ignored"
+	got, err := buildRedirectSignaturePayload(raw, "SAMLResponse")
+	if err != nil {
+		t.Fatalf("build payload: %v", err)
+	}
+	want := "SAMLResponse=abc%2B123%3D%3D&RelayState=x%2By%252Fz&SigAlg=http%3A%2F%2Fwww.w3.org%2F2001%2F04%2Fxmldsig-more%23rsa-sha256"
+	if string(got) != want {
+		t.Fatalf("payload mismatch\nwant: %s\ngot:  %s", want, string(got))
+	}
+}
+
+func TestHandleSAMLLogoutResponse_GetRedirectSignature_Valid_WithRelayState(t *testing.T) {
+	runValidSAMLResponseRedirectTest(t, "relay-state-1", true)
+}
+
+func TestHandleSAMLLogoutResponse_GetRedirectSignature_Valid_WithoutRelayState(t *testing.T) {
+	runValidSAMLResponseRedirectTest(t, "", false)
+}
+
+func TestHandleSAMLLogoutResponse_GetRedirectSignature_Invalid(t *testing.T) {
+	priv, cert := testSigningCert(t)
+	setTestSAMLMiddlewareWithCert(t, cert, "https://sts.windows.net/tenant/")
+
+	xmlB64 := base64.StdEncoding.EncodeToString([]byte(testLogoutResponseXML("https://sts.windows.net/tenant/")))
+	sigAlg := "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
+	params := []string{
+		"SAMLResponse=" + url.QueryEscape(xmlB64),
+		"SigAlg=" + url.QueryEscape(sigAlg),
+	}
+	canonical := strings.Join(params, "&")
+	sig := signRedirectPayloadRSA256(t, priv, []byte(canonical))
+	// Break signature on purpose
+	sig = strings.TrimRight(sig, "=") + "A"
+
+	path := "/api/v1/auth/microsoft/logout?" + canonical + "&Signature=" + url.QueryEscape(sig)
+	h := NewHandler(config.Config{FrontendURL: "https://wfm-dev.mybit.co.id"}, nil)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/logout", h.HandleSAMLLogoutResponse)
+
+	req := httptest.NewRequest(http.MethodGet, path, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("expected 401, got %d", resp.StatusCode)
+	}
+}
+
+func TestHandleSAMLLogoutResponse_GetMissingSignature(t *testing.T) {
+	_, cert := testSigningCert(t)
+	setTestSAMLMiddlewareWithCert(t, cert, "https://sts.windows.net/tenant/")
+
+	xmlB64 := base64.StdEncoding.EncodeToString([]byte(testLogoutResponseXML("https://sts.windows.net/tenant/")))
+	path := "/api/v1/auth/microsoft/logout?SAMLResponse=" + url.QueryEscape(xmlB64)
+
+	h := NewHandler(config.Config{FrontendURL: "https://wfm-dev.mybit.co.id"}, nil)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/logout", h.HandleSAMLLogoutResponse)
+
+	req := httptest.NewRequest(http.MethodGet, path, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("expected 401, got %d", resp.StatusCode)
+	}
+}
+
+func runValidSAMLResponseRedirectTest(t *testing.T, relayState string, withRelay bool) {
+	t.Helper()
+	priv, cert := testSigningCert(t)
+	setTestSAMLMiddlewareWithCert(t, cert, "https://sts.windows.net/tenant/")
+
+	xmlB64 := base64.StdEncoding.EncodeToString([]byte(testLogoutResponseXML("https://sts.windows.net/tenant/")))
+	sigAlg := "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
+
+	parts := []string{"SAMLResponse=" + url.QueryEscape(xmlB64)}
+	if withRelay {
+		parts = append(parts, "RelayState="+url.QueryEscape(relayState))
+	}
+	parts = append(parts, "SigAlg="+url.QueryEscape(sigAlg))
+	canonical := strings.Join(parts, "&")
+	sig := signRedirectPayloadRSA256(t, priv, []byte(canonical))
+	rawQuery := canonical + "&Signature=" + url.QueryEscape(sig)
+
+	h := NewHandler(config.Config{FrontendURL: "https://wfm-dev.mybit.co.id"}, nil)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/logout", h.HandleSAMLLogoutResponse)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/logout?"+rawQuery, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusFound {
+		t.Fatalf("expected 302, got %d", resp.StatusCode)
+	}
+	if got := resp.Header.Get("Location"); got != "https://wfm-dev.mybit.co.id/signin?loggedOut=true" {
+		t.Fatalf("unexpected redirect: %s", got)
+	}
+}
+
+func signRedirectPayloadRSA256(t *testing.T, priv *rsa.PrivateKey, payload []byte) string {
+	t.Helper()
+	sum := sha256.Sum256(payload)
+	sig, err := rsa.SignPKCS1v15(rand.Reader, priv, crypto.SHA256, sum[:])
+	if err != nil {
+		t.Fatalf("sign payload: %v", err)
+	}
+	return base64.StdEncoding.EncodeToString(sig)
+}
+
+func testSigningCert(t *testing.T) (*rsa.PrivateKey, *x509.Certificate) {
+	t.Helper()
+	priv, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("gen key: %v", err)
+	}
+	serial, _ := rand.Int(rand.Reader, big.NewInt(1<<62))
+	tpl := &x509.Certificate{
+		SerialNumber: serial,
+		Subject:      pkix.Name{CommonName: "test-idp"},
+		NotBefore:    time.Now().Add(-time.Hour),
+		NotAfter:     time.Now().Add(24 * time.Hour),
+		KeyUsage:     x509.KeyUsageDigitalSignature,
+	}
+	der, err := x509.CreateCertificate(rand.Reader, tpl, tpl, &priv.PublicKey, priv)
+	if err != nil {
+		t.Fatalf("create cert: %v", err)
+	}
+	cert, err := x509.ParseCertificate(der)
+	if err != nil {
+		t.Fatalf("parse cert: %v", err)
+	}
+	return priv, cert
+}
+
+func setTestSAMLMiddlewareWithCert(t *testing.T, cert *x509.Certificate, entityID string) {
+	t.Helper()
+	prev := SAMLMiddleware
+	SAMLMiddleware = &samlsp.Middleware{}
+	SAMLMiddleware.ServiceProvider.IDPMetadata = &saml.EntityDescriptor{
+		EntityID: entityID,
+		IDPSSODescriptors: []saml.IDPSSODescriptor{
+			{
+				SSODescriptor: saml.SSODescriptor{
+					RoleDescriptor: saml.RoleDescriptor{
+						KeyDescriptors: []saml.KeyDescriptor{
+							{
+								KeyInfo: dsigKeyInfoFromCert(cert),
+							},
+						},
+					},
+				},
+			},
+		},
+	}
+	t.Cleanup(func() { SAMLMiddleware = prev })
+}
+
+func dsigKeyInfoFromCert(cert *x509.Certificate) saml.KeyInfo {
+	if cert == nil {
+		return saml.KeyInfo{}
+	}
+	return saml.KeyInfo{
+		X509Data: saml.X509Data{
+			X509Certificates: []saml.X509Certificate{
+				{Data: base64.StdEncoding.EncodeToString(cert.Raw)},
+			},
+		},
+	}
+}
+
+func testLogoutResponseXML(issuer string) string {
+	return fmt.Sprintf(
+		`<LogoutResponse xmlns="urn:oasis:names:tc:SAML:2.0:protocol" ID="_id123" Version="2.0" IssueInstant="2026-05-28T00:00:00Z"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">%s</Issuer><Status><StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></Status></LogoutResponse>`,
+		issuer,
+	)
+}
+
+func TestCertificateThumbprintSHA1(t *testing.T) {
+	_, cert := testSigningCert(t)
+	got := certificateThumbprintSHA1(cert)
+	if got == "" {
+		t.Fatal("thumbprint should not be empty")
+	}
+	sum := sha1.Sum(cert.Raw)
+	want := strings.ToUpper(hex.EncodeToString(sum[:]))
+	if got != want {
+		t.Fatalf("thumbprint mismatch: got=%s want=%s", got, want)
+	}
+}
diff --git a/internal/auth/saml.go b/internal/auth/saml.go
new file mode 100644
index 0000000..5f8f49d
--- /dev/null
+++ b/internal/auth/saml.go
@@ -0,0 +1,124 @@
+package auth
+
+import (
+	"crypto"
+	"crypto/tls"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/xml"
+	"fmt"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+
+	"github.com/crewjam/saml"
+	"github.com/crewjam/saml/samlsp"
+	"wucher/internal/config"
+)
+
+var SAMLMiddleware *samlsp.Middleware
+
+func InitSAML(cfg config.Config) error {
+	keyPair, err := tls.LoadX509KeyPair(cfg.SAMLCertFile, cfg.SAMLKeyFile)
+	if err != nil {
+		return fmt.Errorf("load saml keypair: %w", err)
+	}
+	cert, err := x509.ParseCertificate(keyPair.Certificate[0])
+	if err != nil {
+		return fmt.Errorf("parse saml certificate: %w", err)
+	}
+	signer, ok := keyPair.PrivateKey.(crypto.Signer)
+	if !ok {
+		return fmt.Errorf("saml private key is not a crypto.Signer")
+	}
+
+	idpMetadataBytes, err := os.ReadFile(cfg.SAMLMetadataFile)
+	if err != nil {
+		return fmt.Errorf("read idp metadata: %w", err)
+	}
+
+	var idpMetadata saml.EntityDescriptor
+	if err := xml.Unmarshal(idpMetadataBytes, &idpMetadata); err != nil {
+		return fmt.Errorf("parse idp metadata xml: %w", err)
+	}
+
+	rootURL, err := url.Parse(cfg.SAMLRootURL)
+	if err != nil {
+		return fmt.Errorf("invalid SAML_ROOT_URL: %w", err)
+	}
+
+	m, err := samlsp.New(samlsp.Options{
+		EntityID:           cfg.SAMLRootURL,
+		URL:                *rootURL,
+		Key:                signer,
+		Certificate:        cert,
+		IDPMetadata:        &idpMetadata,
+		AllowIDPInitiated:  true,
+		CookieSameSite:     http.SameSiteLaxMode,
+		DefaultRedirectURI: cfg.FrontendURL + "/dashboard",
+	})
+	if err != nil {
+		return fmt.Errorf("init saml middleware: %w", err)
+	}
+
+	m.ServiceProvider.MetadataURL.Path = "/api/v1/auth/saml/metadata"
+	m.ServiceProvider.AcsURL.Path = "/api/v1/auth/microsoft/callback"
+	m.ServiceProvider.SloURL.Path = "/api/v1/auth/microsoft/logout"
+	m.ServiceProvider.ValidateAudienceRestriction = func(assertion *saml.Assertion) error {
+		if assertion == nil || assertion.Conditions == nil || len(assertion.Conditions.AudienceRestrictions) == 0 {
+			return nil
+		}
+
+		expected := strings.TrimRight(firstNonEmpty(m.ServiceProvider.EntityID, m.ServiceProvider.MetadataURL.String()), "/")
+		for _, audienceRestriction := range assertion.Conditions.AudienceRestrictions {
+			if strings.TrimRight(audienceRestriction.Audience.Value, "/") == expected {
+				return nil
+			}
+		}
+		return fmt.Errorf("assertion Conditions AudienceRestriction does not contain %q", expected)
+	}
+	SAMLMiddleware = m
+	return nil
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, v := range values {
+		if strings.TrimSpace(v) != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+func getIDPCertificates() ([]*x509.Certificate, error) {
+	if SAMLMiddleware == nil || SAMLMiddleware.ServiceProvider.IDPMetadata == nil {
+		return nil, fmt.Errorf("saml middleware not initialized")
+	}
+
+	var certificates []*x509.Certificate
+	for _, idp := range SAMLMiddleware.ServiceProvider.IDPMetadata.IDPSSODescriptors {
+		for _, kd := range idp.KeyDescriptors {
+			for _, certData := range kd.KeyInfo.X509Data.X509Certificates {
+				raw := strings.TrimSpace(certData.Data)
+				if raw == "" {
+					continue
+				}
+				der, err := base64.StdEncoding.DecodeString(raw)
+				if err != nil {
+					continue
+				}
+				cert, err := x509.ParseCertificate(der)
+				if err != nil {
+					continue
+				}
+				certificates = append(certificates, cert)
+			}
+		}
+	}
+
+	if len(certificates) == 0 {
+		return nil, fmt.Errorf("no idp certificate in metadata")
+	}
+	return certificates, nil
+}
diff --git a/internal/auth/session.go b/internal/auth/session.go
new file mode 100644
index 0000000..09e690a
--- /dev/null
+++ b/internal/auth/session.go
@@ -0,0 +1,127 @@
+package auth
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"time"
+
+	"gorm.io/gorm"
+)
+
+type UserSession struct {
+	UserID          string    `json:"user_id"`
+	MicrosoftNameID string    `json:"microsoft_name_id"`
+	Email           string    `json:"email"`
+	Name            string    `json:"name"`
+	LoggedInAt      time.Time `json:"logged_in_at"`
+	ExpiresAt       time.Time `json:"expires_at"`
+}
+
+type SessionRecord struct {
+	Token           string    `gorm:"type:varchar(128);primaryKey;column:token"`
+	UserID          string    `gorm:"type:varchar(191);index;not null;column:user_id"`
+	MicrosoftNameID string    `gorm:"type:varchar(255);index;not null;column:microsoft_name_id"`
+	Email           string    `gorm:"type:varchar(191);index;not null;column:email"`
+	Name            string    `gorm:"type:varchar(191);not null;column:name"`
+	LoggedInAt      time.Time `gorm:"not null;column:logged_in_at"`
+	ExpiresAt       time.Time `gorm:"index;not null;column:expires_at"`
+	CreatedAt       time.Time `gorm:"column:created_at"`
+	UpdatedAt       time.Time `gorm:"column:updated_at"`
+}
+
+func (SessionRecord) TableName() string { return "saml_sessions" }
+
+var sessionDB *gorm.DB
+
+func InitSessionStoreDB(db *gorm.DB) error {
+	if db == nil {
+		return fmt.Errorf("database is required")
+	}
+	if err := db.AutoMigrate(&SessionRecord{}); err != nil {
+		return fmt.Errorf("auto migrate saml_sessions: %w", err)
+	}
+	sessionDB = db
+	return nil
+}
+
+func CreateSession(session UserSession) (string, error) {
+	if sessionDB == nil {
+		return "", fmt.Errorf("session store is not initialized")
+	}
+	token, err := generateToken()
+	if err != nil {
+		return "", err
+	}
+	if session.LoggedInAt.IsZero() {
+		session.LoggedInAt = time.Now().UTC()
+	}
+	if session.ExpiresAt.IsZero() {
+		session.ExpiresAt = session.LoggedInAt.Add(8 * time.Hour)
+	}
+
+	record := SessionRecord{
+		Token:           token,
+		UserID:          session.UserID,
+		MicrosoftNameID: session.MicrosoftNameID,
+		Email:           session.Email,
+		Name:            session.Name,
+		LoggedInAt:      session.LoggedInAt,
+		ExpiresAt:       session.ExpiresAt,
+	}
+	if err := sessionDB.Create(&record).Error; err != nil {
+		return "", fmt.Errorf("create session: %w", err)
+	}
+	return token, nil
+}
+
+func GetSession(token string) (*UserSession, error) {
+	if sessionDB == nil {
+		return nil, fmt.Errorf("session store is not initialized")
+	}
+	var record SessionRecord
+	err := sessionDB.Where("token = ?", token).First(&record).Error
+	if err != nil {
+		return nil, err
+	}
+	now := time.Now().UTC()
+	if !record.ExpiresAt.After(now) {
+		_ = sessionDB.Delete(&SessionRecord{}, "token = ?", token).Error
+		return nil, gorm.ErrRecordNotFound
+	}
+	return &UserSession{
+		UserID:          record.UserID,
+		MicrosoftNameID: record.MicrosoftNameID,
+		Email:           record.Email,
+		Name:            record.Name,
+		LoggedInAt:      record.LoggedInAt,
+		ExpiresAt:       record.ExpiresAt,
+	}, nil
+}
+
+func DeleteSession(token string) error {
+	if sessionDB == nil {
+		return fmt.Errorf("session store is not initialized")
+	}
+	return sessionDB.Delete(&SessionRecord{}, "token = ?", token).Error
+}
+
+func DeleteSessionByNameID(nameID string) error {
+	if sessionDB == nil {
+		return fmt.Errorf("session store is not initialized")
+	}
+	return sessionDB.Delete(&SessionRecord{}, "microsoft_name_id = ?", nameID).Error
+}
+
+func generateToken() (string, error) {
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		return "", fmt.Errorf("generate token: %w", err)
+	}
+	token := hex.EncodeToString(b)
+	if token == "" {
+		return "", errors.New("empty token")
+	}
+	return token, nil
+}
diff --git a/internal/buildinfo/buildinfo.go b/internal/buildinfo/buildinfo.go
new file mode 100644
index 0000000..83eef77
--- /dev/null
+++ b/internal/buildinfo/buildinfo.go
@@ -0,0 +1,7 @@
+package buildinfo
+
+var (
+	Version   = "dev"
+	Commit    = "unknown"
+	BuildTime = "unknown"
+)
diff --git a/internal/config/config.go b/internal/config/config.go
new file mode 100644
index 0000000..d491ea6
--- /dev/null
+++ b/internal/config/config.go
@@ -0,0 +1,928 @@
+package config
+
+import (
+	"fmt"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+)
+
+type Config struct {
+	AppPort string
+	AppEnv  string
+
+	SAMLCertFile     string
+	SAMLKeyFile      string
+	SAMLMetadataFile string
+	SAMLRootURL      string
+
+	RedisAddr     string
+	RedisPassword string
+	RedisDB       int
+
+	FrontendURL string
+
+	CookieDomain   string
+	CookieSecure   bool
+	SessionTTLHour int
+}
+
+type SAMLConfig struct {
+	CertFile     string
+	KeyFile      string
+	MetadataFile string
+	RootURL      string
+	FrontendURL  string
+	CookieDomain string
+	CookieSecure bool
+	SessionTTLHr int
+}
+
+func LoadEnvConfig() Config {
+	return Config{
+		AppPort:          envString("APP_PORT", "3000"),
+		AppEnv:           envString("APP_ENV", "development"),
+		SAMLCertFile:     envString("SAML_CERT_FILE", "configs/saml.crt"),
+		SAMLKeyFile:      envString("SAML_KEY_FILE", "configs/saml.key"),
+		SAMLMetadataFile: envString("SAML_METADATA_FILE", "configs/metadata.xml"),
+		SAMLRootURL:      envString("SAML_ROOT_URL", "https://api-wfm-dev.mybit.co.id"),
+		RedisAddr:        envString("REDIS_ADDR", "localhost:6379"),
+		RedisPassword:    envString("REDIS_PASSWORD", ""),
+		RedisDB:          envInt("REDIS_DB", 0),
+		FrontendURL:      envString("FRONTEND_URL", "https://wfm-dev.mybit.co.id"),
+		CookieDomain:     strings.TrimSpace(os.Getenv("COOKIE_DOMAIN")),
+		CookieSecure:     envBool("COOKIE_SECURE", true),
+		SessionTTLHour:   envInt("SESSION_TTL_HOUR", 8),
+	}
+}
+
+func envString(key, fallback string) string {
+	v := strings.TrimSpace(os.Getenv(key))
+	if v == "" {
+		return fallback
+	}
+	return v
+}
+
+func envInt(key string, fallback int) int {
+	v := strings.TrimSpace(os.Getenv(key))
+	if v == "" {
+		return fallback
+	}
+	n, err := strconv.Atoi(v)
+	if err != nil {
+		return fallback
+	}
+	return n
+}
+
+func envBool(key string, fallback bool) bool {
+	v := strings.TrimSpace(os.Getenv(key))
+	if v == "" {
+		return fallback
+	}
+	b, err := strconv.ParseBool(v)
+	if err != nil {
+		return fallback
+	}
+	return b
+}
+
+type MySQLConfig struct {
+	DSN             string
+	MaxOpenConns    int
+	MaxIdleConns    int
+	ConnMaxLifetime time.Duration
+	ConnMaxIdleTime time.Duration
+}
+
+type AuthConfig struct {
+	PublicBaseURL                string
+	PasswordPepper               string
+	IPEncryptionKey              string
+	HashTime                     uint32
+	HashMemoryKB                 uint32
+	HashThreads                  uint8
+	HashKeyLen                   uint32
+	EmailVerifyTTL               time.Duration
+	EmailVerifyURL               string
+	InviteTTL                    time.Duration
+	SetPasswordURL               string
+	PasswordResetTTL             time.Duration
+	PasswordResetURL             string
+	SecurityPINResetTTL          time.Duration
+	SecurityPINResetURL          string
+	ForgotSecurityPINCooldown    time.Duration
+	ForgotSecurityPINMinDuration time.Duration
+	SecurityPINMaxAttempts       int
+	SecurityPINLockDuration      time.Duration
+	SecurityPINActionTokenTTL    time.Duration
+	ForgotPasswordEmailCooldown  time.Duration
+	ForgotPasswordMinDuration    time.Duration
+	ForgotPasswordIPRateMax      int
+	ForgotPasswordIPRateWindow   time.Duration
+	LoginIPRateMax               int
+	LoginIPRateWindow            time.Duration
+	TOTPChallengeTTL             time.Duration
+	EmailOTPChallengeTTL         time.Duration
+	EmailOTPLength               int
+	EmailOTPExpiry               time.Duration
+	EmailOTPMaxAttempts          int
+	EmailOTPResendCooldown       time.Duration
+	EmailOTPMaxResendPerHour     int
+	SSOStateTTL                  time.Duration
+	TOTPIssuer                   string
+	TOTPSecretKeyB64             string
+	JWTAccessSecret              string
+	JWTRefreshSecret             string
+	JWTAccessTTL                 time.Duration
+	JWTRefreshTTL                time.Duration
+	JWTRefreshTOTPTTL            time.Duration
+	JWTLocalRefreshTTL           time.Duration
+	JWTSSORefreshTTL             time.Duration
+	SessionIdleTTL               time.Duration
+	JWTCookieDomain              string
+	JWTCookieSecure              bool
+	JWTCookieSameSite            string
+	JWTAccessCookieName          string
+	JWTRefreshCookieName         string
+	WebAuthnRPID                 string
+	WebAuthnRPDisplayName        string
+	WebAuthnRPOrigins            []string
+	WebAuthnChallengeTTL         time.Duration
+	SSOSuccessRedirectURL        string
+	DefaultRoleName              string
+	DisableRegister              bool
+}
+
+type SESConfig struct {
+	Region                string
+	Endpoint              string
+	From                  string
+	ConfigurationSetName  string
+	SendTimeout           time.Duration
+	AllowInsecureEndpoint bool
+}
+
+type EmailDeliveryConfig struct {
+	Provider string
+	MockDir  string
+}
+
+type MicrosoftSSOConfig struct {
+	TenantID     string
+	ClientID     string
+	ClientSecret string
+	RedirectURL  string
+	Authority    string
+	Scopes       []string
+}
+
+type HTTPConfig struct {
+	BodyLimit            int
+	ReadTimeout          time.Duration
+	WriteTimeout         time.Duration
+	IdleTimeout          time.Duration
+	RequestTimeout       time.Duration
+	RequestTimeoutByPath map[string]time.Duration
+	ShutdownTimeout      time.Duration
+	CORSAllowOrigins     string
+	CORSAllowMethods     string
+	CORSAllowHeaders     string
+	CORSExposeHeaders    string
+	CORSAllowCredentials bool
+	CORSMaxAge           int
+	RateLimitMax         int
+	RateLimitWindow      time.Duration
+	RateLimitByEndpoint  map[string]RateLimitRule
+	HSTSMaxAge           int
+}
+
+type RateLimitRule struct {
+	Max    int
+	Window time.Duration
+}
+
+type AuditConfig struct {
+	QueueSize int
+	Workers   int
+}
+
+type LoggingConfig struct {
+	Level  string
+	Format string
+}
+
+type CircuitBreakerPolicy struct {
+	Enabled             bool
+	MaxRequests         uint32
+	Interval            time.Duration
+	BucketPeriod        time.Duration
+	Timeout             time.Duration
+	MinRequests         uint32
+	FailureRatio        float64
+	ConsecutiveFailures uint32
+}
+
+type ResilienceConfig struct {
+	Default      CircuitBreakerPolicy
+	MicrosoftSSO CircuitBreakerPolicy
+	SES          CircuitBreakerPolicy
+	SQS          CircuitBreakerPolicy
+}
+
+type QueueConfig struct {
+	MessageSchemaVersion        string
+	EnableLegacyPayloadFallback bool
+	IdempotencyKeyPrefix        string
+	IdempotencyTTL              time.Duration
+	ProcessingTTL               time.Duration
+	WorkerConcurrency           int
+	WorkerMaxBatchSize          int
+	WorkerProcessTimeout        time.Duration
+	WorkerShutdownTimeout       time.Duration
+	WorkerBackoffMin            time.Duration
+	WorkerBackoffMax            time.Duration
+	WorkerPermanentFailureDelay time.Duration
+	WorkerMonitorAddr           string
+	WorkerHealthErrorThreshold  int
+	WorkerDepthPollInterval     time.Duration
+	OutboxEnabled               bool
+	OutboxPollInterval          time.Duration
+	OutboxBatchSize             int
+	OutboxDispatchTimeout       time.Duration
+	OutboxLockTTL               time.Duration
+	OutboxMaxAttempts           int
+}
+
+type FileQueueConfig struct {
+	MessageSchemaVersion        string
+	IdempotencyKeyPrefix        string
+	IdempotencyTTL              time.Duration
+	ProcessingTTL               time.Duration
+	WorkerConcurrency           int
+	WorkerMaxBatchSize          int
+	WorkerProcessTimeout        time.Duration
+	WorkerShutdownTimeout       time.Duration
+	WorkerBackoffMin            time.Duration
+	WorkerBackoffMax            time.Duration
+	WorkerPermanentFailureDelay time.Duration
+	WorkerMonitorAddr           string
+	WorkerHealthErrorThreshold  int
+	WorkerDepthPollInterval     time.Duration
+	OutboxEnabled               bool
+	OutboxPollInterval          time.Duration
+	OutboxBatchSize             int
+	OutboxDispatchTimeout       time.Duration
+	OutboxLockTTL               time.Duration
+	OutboxMaxAttempts           int
+}
+
+type SQSConfig struct {
+	Region                string
+	AccessKeyID           string
+	SecretAccessKey       string
+	Endpoint              string
+	QueueURL              string
+	QueueType             string
+	MessageGroupID        string
+	MaxMessages           int
+	WaitTimeSeconds       int32
+	VisibilityTimeout     time.Duration
+	AllowInsecureEndpoint bool
+}
+
+type FileStorageConfig struct {
+	Provider              string
+	Bucket                string
+	Region                string
+	Endpoint              string
+	AccessKeyID           string
+	SecretAccessKey       string
+	ForcePathStyle        bool
+	AllowInsecureEndpoint bool
+	AutoCreateBucket      bool
+	ObjectKeyPrefix       string
+	PresignPutTTL         time.Duration
+	PresignGetTTL         time.Duration
+}
+
+type FileManagerUploadPolicyConfig struct {
+	MaxFileSizeBytes  int64
+	AllowedMimeTypes  []string
+	AllowedExtensions []string
+	AllowEmptyFile    bool
+	MaxFilenameLength int
+}
+
+type FileManagerTrashPolicyConfig struct {
+	AutoPurgeEnabled   bool
+	Retention          time.Duration
+	AutoPurgeInterval  time.Duration
+	AutoPurgeBatchSize int
+}
+
+type FileManagerLifecycleConfig struct {
+	EnableS3Tagging      bool
+	EnableCleanupJob     bool
+	TempUploadGraceHours int
+	OrphanGraceDays      int
+	CleanupBatchSize     int
+	CleanupDryRun        bool
+}
+
+type WOPIConfig struct {
+	TokenSecret   string
+	ProofSecret   string
+	DiscoveryURL  string
+	PublicBaseURL string
+	EditActionURL string
+	TokenTTL      time.Duration
+	MaxBodyBytes  int
+	RequireProof  bool
+}
+
+type GotenbergConfig struct {
+	URL string
+}
+
+func LoadMySQLConfigFromEnv() MySQLConfig {
+	return MySQLConfig{
+		DSN:             getenv("MYSQL_DSN", ""),
+		MaxOpenConns:    getenvInt("MYSQL_MAX_OPEN_CONNS", 25),
+		MaxIdleConns:    getenvInt("MYSQL_MAX_IDLE_CONNS", 10),
+		ConnMaxLifetime: getenvDuration("MYSQL_CONN_MAX_LIFETIME", 5*time.Minute),
+		ConnMaxIdleTime: getenvDuration("MYSQL_CONN_MAX_IDLE_TIME", 2*time.Minute),
+	}
+}
+
+func LoadAuthConfigFromEnv() AuthConfig {
+	refreshTTL := getenvDuration("AUTH_JWT_REFRESH_TTL", time.Hour)
+	refreshTOTPTTL := getenvDuration("AUTH_JWT_REFRESH_TOTP_TTL", refreshTTL)
+	passwordPepper := getenv("AUTH_PASSWORD_PEPPER", "")
+	ipEncryptionKey := getenv("AUTH_IP_ENCRYPTION_KEY", getenv("AUTH_IP_HMAC_KEY", passwordPepper))
+
+	return AuthConfig{
+		PublicBaseURL:                getenv("APP_PUBLIC_BASE_URL", ""),
+		PasswordPepper:               passwordPepper,
+		IPEncryptionKey:              ipEncryptionKey,
+		HashTime:                     uint32(getenvInt("AUTH_HASH_TIME", 1)),
+		HashMemoryKB:                 uint32(getenvInt("AUTH_HASH_MEMORY_KB", 64*1024)),
+		HashThreads:                  uint8(getenvInt("AUTH_HASH_THREADS", 4)),
+		HashKeyLen:                   uint32(getenvInt("AUTH_HASH_KEY_LEN", 32)),
+		EmailVerifyTTL:               getenvDuration("AUTH_EMAIL_VERIFY_TTL", 24*time.Hour),
+		EmailVerifyURL:               getenv("AUTH_EMAIL_VERIFY_URL", ""),
+		InviteTTL:                    getenvDuration("AUTH_INVITE_TTL", 24*time.Hour),
+		SetPasswordURL:               getenv("AUTH_SET_PASSWORD_URL", getenv("AUTH_EMAIL_VERIFY_URL", "")),
+		PasswordResetTTL:             getenvDuration("AUTH_PASSWORD_RESET_TTL", 20*time.Minute),
+		PasswordResetURL:             getenv("AUTH_PASSWORD_RESET_URL", getenv("AUTH_SET_PASSWORD_URL", "")),
+		SecurityPINResetTTL:          getenvDuration("AUTH_SECURITY_PIN_RESET_TTL", 20*time.Minute),
+		SecurityPINResetURL:          getenv("AUTH_SECURITY_PIN_RESET_URL", getenv("AUTH_PASSWORD_RESET_URL", getenv("AUTH_SET_PASSWORD_URL", ""))),
+		ForgotSecurityPINCooldown:    getenvDuration("AUTH_FORGOT_SECURITY_PIN_EMAIL_COOLDOWN", 2*time.Minute),
+		ForgotSecurityPINMinDuration: getenvDuration("AUTH_FORGOT_SECURITY_PIN_MIN_DURATION", 150*time.Millisecond),
+		SecurityPINMaxAttempts:       getenvInt("AUTH_SECURITY_PIN_MAX_ATTEMPTS", 5),
+		SecurityPINLockDuration:      getenvDuration("AUTH_SECURITY_PIN_LOCK_DURATION", 0),
+		SecurityPINActionTokenTTL:    getenvDuration("AUTH_SECURITY_PIN_ACTION_TOKEN_TTL", 5*time.Minute),
+		ForgotPasswordEmailCooldown:  getenvDuration("AUTH_FORGOT_PASSWORD_EMAIL_COOLDOWN", 2*time.Minute),
+		ForgotPasswordMinDuration:    getenvDuration("AUTH_FORGOT_PASSWORD_MIN_DURATION", 150*time.Millisecond),
+		ForgotPasswordIPRateMax:      getenvInt("AUTH_FORGOT_PASSWORD_IP_RATE_MAX", 10),
+		ForgotPasswordIPRateWindow:   getenvDuration("AUTH_FORGOT_PASSWORD_IP_RATE_WINDOW", 15*time.Minute),
+		LoginIPRateMax:               getenvInt("AUTH_LOGIN_IP_RATE_MAX", 5),
+		LoginIPRateWindow:            getenvDuration("AUTH_LOGIN_IP_RATE_WINDOW", time.Minute),
+		TOTPChallengeTTL:             getenvDuration("AUTH_TOTP_CHALLENGE_TTL", 5*time.Minute),
+		EmailOTPChallengeTTL:         getenvDuration("AUTH_EMAIL_OTP_CHALLENGE_TTL", 10*time.Minute),
+		EmailOTPLength:               getenvInt("AUTH_EMAIL_OTP_LENGTH", 6),
+		EmailOTPExpiry:               getenvDuration("AUTH_EMAIL_OTP_EXPIRY", 10*time.Minute),
+		EmailOTPMaxAttempts:          getenvInt("AUTH_EMAIL_OTP_MAX_ATTEMPTS", 5),
+		EmailOTPResendCooldown:       getenvDuration("AUTH_EMAIL_OTP_RESEND_COOLDOWN", 60*time.Second),
+		EmailOTPMaxResendPerHour:     getenvInt("AUTH_EMAIL_OTP_MAX_RESEND_PER_HOUR", 5),
+		SSOStateTTL:                  getenvDuration("AUTH_SSO_STATE_TTL", 10*time.Minute),
+		TOTPIssuer:                   getenv("TOTP_ISSUER", "Wucher"),
+		TOTPSecretKeyB64:             getenv("TOTP_SECRET_KEY", ""),
+		JWTAccessSecret:              getenv("AUTH_JWT_ACCESS_SECRET", ""),
+		JWTRefreshSecret:             getenv("AUTH_JWT_REFRESH_SECRET", ""),
+		JWTAccessTTL:                 getenvDuration("AUTH_JWT_ACCESS_TTL", 10*time.Minute),
+		JWTRefreshTTL:                refreshTTL,
+		JWTRefreshTOTPTTL:            refreshTOTPTTL,
+		JWTLocalRefreshTTL:           getenvDuration("AUTH_JWT_LOCAL_REFRESH_TTL", 24*time.Hour),
+		// Fallback lifetime for Microsoft/SSO sessions when Microsoft does not
+		// report refresh_token_expires_in. Defaults to Microsoft's default
+		// refresh-token lifetime (90 days); the actual session follows the
+		// value Microsoft returns whenever it is present.
+		JWTSSORefreshTTL:      getenvDuration("AUTH_JWT_SSO_REFRESH_TTL", 90*24*time.Hour),
+		SessionIdleTTL:        getenvDuration("AUTH_SESSION_IDLE_TTL", 15*time.Minute),
+		JWTCookieDomain:       getenv("AUTH_JWT_COOKIE_DOMAIN", ""),
+		JWTCookieSecure:       getenvBool("AUTH_JWT_COOKIE_SECURE", false),
+		JWTCookieSameSite:     getenv("AUTH_JWT_COOKIE_SAMESITE", "Lax"),
+		JWTAccessCookieName:   getenv("AUTH_JWT_ACCESS_COOKIE", "wucher_at"),
+		JWTRefreshCookieName:  getenv("AUTH_JWT_REFRESH_COOKIE", "wucher_rt"),
+		WebAuthnRPID:          getenv("AUTH_WEBAUTHN_RP_ID", ""),
+		WebAuthnRPDisplayName: getenv("AUTH_WEBAUTHN_RP_DISPLAY_NAME", "Wucher"),
+		WebAuthnRPOrigins:     getenvCSV("AUTH_WEBAUTHN_RP_ORIGINS", ""),
+		WebAuthnChallengeTTL:  getenvDuration("AUTH_WEBAUTHN_CHALLENGE_TTL", 5*time.Minute),
+		SSOSuccessRedirectURL: getenv("AUTH_SSO_SUCCESS_REDIRECT", ""),
+		DefaultRoleName:       getenv("AUTH_DEFAULT_ROLE", "user"),
+		DisableRegister:       getenvBool("AUTH_DISABLE_REGISTER", false),
+	}
+}
+
+func LoadSESConfigFromEnv() SESConfig {
+	return SESConfig{
+		Region:                getenv("SES_REGION", getenv("AWS_REGION", "")),
+		Endpoint:              getenv("SES_ENDPOINT", ""),
+		From:                  getenv("SES_FROM", ""),
+		ConfigurationSetName:  getenv("SES_CONFIGURATION_SET", ""),
+		SendTimeout:           getenvDuration("SES_SEND_TIMEOUT", 10*time.Second),
+		AllowInsecureEndpoint: getenvBool("SES_ALLOW_INSECURE_ENDPOINT", false),
+	}
+}
+
+func LoadEmailDeliveryConfigFromEnv() EmailDeliveryConfig {
+	return EmailDeliveryConfig{
+		Provider: strings.ToLower(strings.TrimSpace(getenv("EMAIL_PROVIDER", "ses"))),
+		MockDir:  strings.TrimSpace(getenv("EMAIL_MOCK_DIR", ".local/emails")),
+	}
+}
+
+func LoadMicrosoftSSOConfigFromEnv() MicrosoftSSOConfig {
+	scopes := strings.Split(getenv("MS_ENTRA_SCOPES", "openid,profile,email,offline_access,User.Read"), ",")
+	for i := range scopes {
+		scopes[i] = strings.TrimSpace(scopes[i])
+	}
+	return MicrosoftSSOConfig{
+		TenantID:     getenv("MS_ENTRA_TENANT_ID", ""),
+		ClientID:     getenv("MS_ENTRA_CLIENT_ID", ""),
+		ClientSecret: getenv("MS_ENTRA_CLIENT_SECRET", ""),
+		RedirectURL:  getenv("MS_ENTRA_REDIRECT_URL", ""),
+		Authority:    getenv("MS_ENTRA_AUTHORITY", "https://login.microsoftonline.com/"),
+		Scopes:       scopes,
+	}
+}
+
+func LoadHTTPConfigFromEnv() HTTPConfig {
+	return HTTPConfig{
+		BodyLimit:            getenvInt("HTTP_BODY_LIMIT", 4*1024*1024),
+		ReadTimeout:          getenvDuration("HTTP_READ_TIMEOUT", 10*time.Second),
+		WriteTimeout:         getenvDuration("HTTP_WRITE_TIMEOUT", 15*time.Second),
+		IdleTimeout:          getenvDuration("HTTP_IDLE_TIMEOUT", 60*time.Second),
+		RequestTimeout:       getenvDuration("HTTP_REQUEST_TIMEOUT", 30*time.Second),
+		RequestTimeoutByPath: parseHTTPTimeoutOverrides(getenv("HTTP_REQUEST_TIMEOUT_OVERRIDES", "")),
+		ShutdownTimeout:      getenvDuration("HTTP_SHUTDOWN_TIMEOUT", 30*time.Second),
+		CORSAllowOrigins:     getenv("HTTP_CORS_ALLOW_ORIGINS", "http://localhost:3000,http://127.0.0.1:3000,http://localhost:5173,http://127.0.0.1:5173"),
+		CORSAllowMethods:     getenv("HTTP_CORS_ALLOW_METHODS", "GET,POST,PUT,PATCH,DELETE,OPTIONS,HEAD"),
+		CORSAllowHeaders:     getenv("HTTP_CORS_ALLOW_HEADERS", "Origin,Content-Type,Accept,Authorization,X-Requested-With,X-Pin-Verification-Token,X-Device-Type"),
+		CORSExposeHeaders:    getenv("HTTP_CORS_EXPOSE_HEADERS", "X-Request-ID"),
+		CORSAllowCredentials: getenvBool("HTTP_CORS_ALLOW_CREDENTIALS", true),
+		CORSMaxAge:           getenvInt("HTTP_CORS_MAX_AGE", 300),
+		RateLimitMax:         getenvInt("HTTP_RATE_LIMIT_MAX", 120),
+		RateLimitWindow:      getenvDuration("HTTP_RATE_LIMIT_WINDOW", time.Minute),
+		RateLimitByEndpoint:  parseHTTPEndpointRateLimitOverrides(getenv("HTTP_RATE_LIMIT_ENDPOINTS", "")),
+		HSTSMaxAge:           getenvInt("HTTP_SECURITY_HSTS_MAX_AGE", 0),
+	}
+}
+
+func parseHTTPTimeoutOverrides(raw string) map[string]time.Duration {
+	parsed := make(map[string]time.Duration)
+	if strings.TrimSpace(raw) == "" {
+		return parsed
+	}
+
+	entries := strings.Split(raw, ",")
+	for _, entry := range entries {
+		entry = strings.TrimSpace(entry)
+		if entry == "" {
+			continue
+		}
+
+		parts := strings.SplitN(entry, "=", 2)
+		if len(parts) != 2 {
+			continue
+		}
+
+		keyParts := strings.Fields(strings.TrimSpace(parts[0]))
+		if len(keyParts) < 2 {
+			continue
+		}
+		method := strings.ToUpper(strings.TrimSpace(keyParts[0]))
+		path := strings.Join(keyParts[1:], " ")
+		path = strings.TrimSpace(path)
+		if method == "" || path == "" {
+			continue
+		}
+		key := method + " " + path
+
+		duration, err := time.ParseDuration(strings.TrimSpace(parts[1]))
+		if err != nil || duration <= 0 {
+			continue
+		}
+		parsed[key] = duration
+	}
+
+	return parsed
+}
+
+func parseHTTPEndpointRateLimitOverrides(raw string) map[string]RateLimitRule {
+	parsed := make(map[string]RateLimitRule)
+	if strings.TrimSpace(raw) == "" {
+		return parsed
+	}
+
+	entries := strings.Split(raw, ";")
+	for _, entry := range entries {
+		entry = strings.TrimSpace(entry)
+		if entry == "" {
+			continue
+		}
+
+		parts := strings.SplitN(entry, "=", 2)
+		if len(parts) != 2 {
+			continue
+		}
+
+		keyParts := strings.Fields(strings.TrimSpace(parts[0]))
+		if len(keyParts) < 2 {
+			continue
+		}
+		method := strings.ToUpper(strings.TrimSpace(keyParts[0]))
+		path := strings.Join(keyParts[1:], " ")
+		path = strings.TrimSpace(path)
+		if method == "" || path == "" {
+			continue
+		}
+		key := method + " " + path
+
+		ruleParts := strings.SplitN(strings.TrimSpace(parts[1]), ",", 2)
+		if len(ruleParts) != 2 {
+			continue
+		}
+		max, err := strconv.Atoi(strings.TrimSpace(ruleParts[0]))
+		if err != nil || max <= 0 {
+			continue
+		}
+		window, err := time.ParseDuration(strings.TrimSpace(ruleParts[1]))
+		if err != nil || window <= 0 {
+			continue
+		}
+
+		parsed[key] = RateLimitRule{
+			Max:    max,
+			Window: window,
+		}
+	}
+
+	return parsed
+}
+
+func LoadAuditConfigFromEnv() AuditConfig {
+	return AuditConfig{
+		QueueSize: getenvInt("AUDIT_LOG_QUEUE_SIZE", 1024),
+		Workers:   getenvInt("AUDIT_LOG_WORKERS", 2),
+	}
+}
+
+func LoadLoggingConfigFromEnv() LoggingConfig {
+	return LoggingConfig{
+		Level:  getenv("LOG_LEVEL", "info"),
+		Format: getenv("LOG_FORMAT", "json"),
+	}
+}
+
+func LoadResilienceConfigFromEnv() ResilienceConfig {
+	defaults := loadCircuitBreakerPolicyFromEnv("CB_DEFAULT_", CircuitBreakerPolicy{
+		Enabled:             true,
+		MaxRequests:         1,
+		Interval:            time.Minute,
+		BucketPeriod:        10 * time.Second,
+		Timeout:             30 * time.Second,
+		MinRequests:         5,
+		FailureRatio:        0.6,
+		ConsecutiveFailures: 5,
+	})
+	return ResilienceConfig{
+		Default:      defaults,
+		MicrosoftSSO: loadCircuitBreakerPolicyFromEnv("CB_MICROSOFT_SSO_", defaults),
+		SES:          loadCircuitBreakerPolicyFromEnv("CB_SES_", defaults),
+		SQS:          loadCircuitBreakerPolicyFromEnv("CB_SQS_", defaults),
+	}
+}
+
+func LoadQueueConfigFromEnv() QueueConfig {
+	return QueueConfig{
+		MessageSchemaVersion:        getenv("QUEUE_MESSAGE_SCHEMA_VERSION", "v2"),
+		EnableLegacyPayloadFallback: getenvBool("QUEUE_ENABLE_LEGACY_PAYLOAD_FALLBACK", true),
+		IdempotencyKeyPrefix:        getenv("QUEUE_IDEMPOTENCY_KEY_PREFIX", "queue:idempotency:email:"),
+		IdempotencyTTL:              getenvDuration("QUEUE_IDEMPOTENCY_TTL", 24*time.Hour),
+		ProcessingTTL:               getenvDuration("QUEUE_PROCESSING_TTL", 15*time.Minute),
+		WorkerConcurrency:           getenvInt("QUEUE_WORKER_CONCURRENCY", 4),
+		WorkerMaxBatchSize:          getenvInt("QUEUE_WORKER_MAX_BATCH_SIZE", 10),
+		WorkerProcessTimeout:        getenvDuration("QUEUE_WORKER_PROCESS_TIMEOUT", 30*time.Second),
+		WorkerShutdownTimeout:       getenvDuration("QUEUE_WORKER_SHUTDOWN_TIMEOUT", 30*time.Second),
+		WorkerBackoffMin:            getenvDuration("QUEUE_WORKER_BACKOFF_MIN", time.Second),
+		WorkerBackoffMax:            getenvDuration("QUEUE_WORKER_BACKOFF_MAX", 5*time.Minute),
+		WorkerPermanentFailureDelay: getenvDuration("QUEUE_WORKER_PERMANENT_FAILURE_DELAY", 30*time.Second),
+		WorkerMonitorAddr:           getenv("QUEUE_WORKER_MONITOR_ADDR", "127.0.0.1:9090"),
+		WorkerHealthErrorThreshold:  getenvInt("QUEUE_WORKER_HEALTH_ERROR_THRESHOLD", 3),
+		WorkerDepthPollInterval:     getenvDuration("QUEUE_WORKER_DEPTH_POLL_INTERVAL", 30*time.Second),
+		OutboxEnabled:               getenvBool("QUEUE_OUTBOX_ENABLED", true),
+		OutboxPollInterval:          getenvDuration("QUEUE_OUTBOX_POLL_INTERVAL", time.Second),
+		OutboxBatchSize:             getenvInt("QUEUE_OUTBOX_BATCH_SIZE", 10),
+		OutboxDispatchTimeout:       getenvDuration("QUEUE_OUTBOX_DISPATCH_TIMEOUT", 10*time.Second),
+		OutboxLockTTL:               getenvDuration("QUEUE_OUTBOX_LOCK_TTL", time.Minute),
+		OutboxMaxAttempts:           getenvInt("QUEUE_OUTBOX_MAX_ATTEMPTS", 20),
+	}
+}
+
+func LoadFileQueueConfigFromEnv() FileQueueConfig {
+	return FileQueueConfig{
+		MessageSchemaVersion:        getenv("FILE_QUEUE_MESSAGE_SCHEMA_VERSION", "v1"),
+		IdempotencyKeyPrefix:        getenv("FILE_QUEUE_IDEMPOTENCY_KEY_PREFIX", "queue:idempotency:file:"),
+		IdempotencyTTL:              getenvDuration("FILE_QUEUE_IDEMPOTENCY_TTL", 24*time.Hour),
+		ProcessingTTL:               getenvDuration("FILE_QUEUE_PROCESSING_TTL", 15*time.Minute),
+		WorkerConcurrency:           getenvInt("FILE_QUEUE_WORKER_CONCURRENCY", 4),
+		WorkerMaxBatchSize:          getenvInt("FILE_QUEUE_WORKER_MAX_BATCH_SIZE", 10),
+		WorkerProcessTimeout:        getenvDuration("FILE_QUEUE_WORKER_PROCESS_TIMEOUT", 30*time.Second),
+		WorkerShutdownTimeout:       getenvDuration("FILE_QUEUE_WORKER_SHUTDOWN_TIMEOUT", 30*time.Second),
+		WorkerBackoffMin:            getenvDuration("FILE_QUEUE_WORKER_BACKOFF_MIN", time.Second),
+		WorkerBackoffMax:            getenvDuration("FILE_QUEUE_WORKER_BACKOFF_MAX", 5*time.Minute),
+		WorkerPermanentFailureDelay: getenvDuration("FILE_QUEUE_WORKER_PERMANENT_FAILURE_DELAY", 30*time.Second),
+		WorkerMonitorAddr:           getenv("FILE_QUEUE_WORKER_MONITOR_ADDR", "127.0.0.1:9091"),
+		WorkerHealthErrorThreshold:  getenvInt("FILE_QUEUE_WORKER_HEALTH_ERROR_THRESHOLD", 3),
+		WorkerDepthPollInterval:     getenvDuration("FILE_QUEUE_WORKER_DEPTH_POLL_INTERVAL", 30*time.Second),
+		OutboxEnabled:               getenvBool("FILE_QUEUE_OUTBOX_ENABLED", true),
+		OutboxPollInterval:          getenvDuration("FILE_QUEUE_OUTBOX_POLL_INTERVAL", time.Second),
+		OutboxBatchSize:             getenvInt("FILE_QUEUE_OUTBOX_BATCH_SIZE", 10),
+		OutboxDispatchTimeout:       getenvDuration("FILE_QUEUE_OUTBOX_DISPATCH_TIMEOUT", 10*time.Second),
+		OutboxLockTTL:               getenvDuration("FILE_QUEUE_OUTBOX_LOCK_TTL", time.Minute),
+		OutboxMaxAttempts:           getenvInt("FILE_QUEUE_OUTBOX_MAX_ATTEMPTS", 20),
+	}
+}
+
+func LoadSQSConfigFromEnv() SQSConfig {
+	return SQSConfig{
+		Region:                getenv("AWS_REGION", ""),
+		AccessKeyID:           getenv("AWS_ACCESS_KEY_ID", ""),
+		SecretAccessKey:       getenv("AWS_SECRET_ACCESS_KEY", ""),
+		Endpoint:              getenv("SQS_ENDPOINT", ""),
+		QueueURL:              getenv("SQS_QUEUE_URL", ""),
+		QueueType:             getenv("SQS_QUEUE_TYPE", "standard"),
+		MessageGroupID:        getenv("SQS_MESSAGE_GROUP_ID", "email"),
+		MaxMessages:           getenvInt("SQS_MAX_MESSAGES", 10),
+		WaitTimeSeconds:       int32(getenvInt("SQS_WAIT_TIME_SECONDS", 20)),
+		VisibilityTimeout:     getenvDuration("SQS_VISIBILITY_TIMEOUT", 60*time.Second),
+		AllowInsecureEndpoint: getenvBool("SQS_ALLOW_INSECURE_ENDPOINT", false),
+	}
+}
+
+func LoadFileSQSConfigFromEnv() SQSConfig {
+	return SQSConfig{
+		Region:                getenv("FILE_SQS_REGION", getenv("AWS_REGION", "")),
+		AccessKeyID:           getenv("AWS_ACCESS_KEY_ID", ""),
+		SecretAccessKey:       getenv("AWS_SECRET_ACCESS_KEY", ""),
+		Endpoint:              getenv("FILE_SQS_ENDPOINT", getenv("SQS_ENDPOINT", "")),
+		QueueURL:              getenv("FILE_SQS_QUEUE_URL", ""),
+		QueueType:             getenv("FILE_SQS_QUEUE_TYPE", "standard"),
+		MessageGroupID:        getenv("FILE_SQS_MESSAGE_GROUP_ID", "file-processing"),
+		MaxMessages:           getenvInt("FILE_SQS_MAX_MESSAGES", 10),
+		WaitTimeSeconds:       int32(getenvInt("FILE_SQS_WAIT_TIME_SECONDS", 20)),
+		VisibilityTimeout:     getenvDuration("FILE_SQS_VISIBILITY_TIMEOUT", 60*time.Second),
+		AllowInsecureEndpoint: getenvBool("FILE_SQS_ALLOW_INSECURE_ENDPOINT", getenvBool("SQS_ALLOW_INSECURE_ENDPOINT", false)),
+	}
+}
+
+func ValidateDistinctQueueURLs(emailCfg, fileCfg SQSConfig) error {
+	emailQueueURL := canonicalQueueURL(emailCfg.QueueURL)
+	fileQueueURL := canonicalQueueURL(fileCfg.QueueURL)
+
+	if emailQueueURL == "" || fileQueueURL == "" {
+		return nil
+	}
+	if emailQueueURL == fileQueueURL {
+		return fmt.Errorf("invalid queue configuration: FILE_SQS_QUEUE_URL must be different from SQS_QUEUE_URL")
+	}
+	return nil
+}
+
+func canonicalQueueURL(raw string) string {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" {
+		return ""
+	}
+
+	parsed, err := url.Parse(trimmed)
+	if err != nil {
+		return strings.TrimRight(strings.ToLower(trimmed), "/")
+	}
+	parsed.Host = strings.ToLower(parsed.Host)
+	parsed.Path = strings.TrimRight(parsed.Path, "/")
+	parsed.RawQuery = ""
+	parsed.Fragment = ""
+	return parsed.String()
+}
+
+func LoadFileStorageConfigFromEnv() FileStorageConfig {
+	provider := strings.ToLower(strings.TrimSpace(getenv("FILE_STORAGE_PROVIDER", "s3")))
+	return FileStorageConfig{
+		Provider:              provider,
+		Bucket:                strings.TrimSpace(getenv("FILE_S3_BUCKET", "")),
+		Region:                strings.TrimSpace(getenv("FILE_S3_REGION", getenv("AWS_REGION", ""))),
+		Endpoint:              strings.TrimSpace(getenv("FILE_S3_ENDPOINT", "")),
+		AccessKeyID:           strings.TrimSpace(getenv("FILE_S3_ACCESS_KEY_ID", getenv("AWS_ACCESS_KEY_ID", ""))),
+		SecretAccessKey:       strings.TrimSpace(getenv("FILE_S3_SECRET_ACCESS_KEY", getenv("AWS_SECRET_ACCESS_KEY", ""))),
+		ForcePathStyle:        getenvBool("FILE_S3_FORCE_PATH_STYLE", false),
+		AllowInsecureEndpoint: getenvBool("FILE_S3_ALLOW_INSECURE_ENDPOINT", false),
+		AutoCreateBucket:      getenvBool("FILE_S3_AUTO_CREATE_BUCKET", false),
+		ObjectKeyPrefix:       strings.TrimSpace(getenv("FILE_OBJECT_KEY_PREFIX", "fm/objects")),
+		PresignPutTTL:         getenvDuration("FILE_S3_PRESIGN_PUT_TTL", 15*time.Minute),
+		PresignGetTTL:         getenvDuration("FILE_S3_PRESIGN_GET_TTL", 15*time.Minute),
+	}
+}
+
+func LoadFileManagerUploadPolicyConfigFromEnv() FileManagerUploadPolicyConfig {
+	return FileManagerUploadPolicyConfig{
+		MaxFileSizeBytes:  int64(getenvInt("FILE_MANAGER_UPLOAD_MAX_FILE_SIZE_BYTES", 4*1024*1024)),
+		AllowedMimeTypes:  normalizeMimeTypes(getenvCSV("FILE_MANAGER_UPLOAD_ALLOWED_MIME_TYPES", "")),
+		AllowedExtensions: normalizeExtensions(getenvCSV("FILE_MANAGER_UPLOAD_ALLOWED_EXTENSIONS", "")),
+		AllowEmptyFile:    getenvBool("FILE_MANAGER_UPLOAD_ALLOW_EMPTY_FILE", false),
+		MaxFilenameLength: getenvInt("FILE_MANAGER_UPLOAD_MAX_FILENAME_LENGTH", 255),
+	}
+}
+
+func LoadFileManagerTrashPolicyConfigFromEnv() FileManagerTrashPolicyConfig {
+	retention := getenvDuration("FILE_MANAGER_TRASH_RETENTION", 30*24*time.Hour)
+	if retention < 0 {
+		retention = 0
+	}
+	interval := getenvDuration("FILE_MANAGER_TRASH_AUTO_PURGE_INTERVAL", time.Hour)
+	if interval <= 0 {
+		interval = time.Hour
+	}
+	batchSize := getenvInt("FILE_MANAGER_TRASH_AUTO_PURGE_BATCH_SIZE", 200)
+	if batchSize <= 0 {
+		batchSize = 200
+	}
+
+	return FileManagerTrashPolicyConfig{
+		AutoPurgeEnabled:   getenvBool("FILE_MANAGER_TRASH_AUTO_PURGE_ENABLED", true),
+		Retention:          retention,
+		AutoPurgeInterval:  interval,
+		AutoPurgeBatchSize: batchSize,
+	}
+}
+
+func LoadFileManagerLifecycleConfigFromEnv() FileManagerLifecycleConfig {
+	tempHours := getenvInt("TEMP_UPLOAD_GRACE_HOURS", 2)
+	if tempHours <= 0 {
+		tempHours = 2
+	}
+	orphanDays := getenvInt("ORPHAN_GRACE_PERIOD_DAYS", 30)
+	if orphanDays <= 0 {
+		orphanDays = 30
+	}
+	batchSize := getenvInt("FILE_CLEANUP_BATCH_SIZE", 100)
+	if batchSize <= 0 {
+		batchSize = 100
+	}
+	return FileManagerLifecycleConfig{
+		EnableS3Tagging:      getenvBool("ENABLE_S3_TAGGING", true),
+		EnableCleanupJob:     getenvBool("ENABLE_FILE_CLEANUP_JOB", false),
+		TempUploadGraceHours: tempHours,
+		OrphanGraceDays:      orphanDays,
+		CleanupBatchSize:     batchSize,
+		CleanupDryRun:        getenvBool("FILE_CLEANUP_DRY_RUN", true),
+	}
+}
+
+func getenv(key, def string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return def
+}
+
+func getenvInt(key string, def int) int {
+	if v := os.Getenv(key); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			return n
+		}
+	}
+	return def
+}
+
+func getenvUint32(key string, def uint32) uint32 {
+	if v := os.Getenv(key); v != "" {
+		if n, err := strconv.ParseUint(v, 10, 32); err == nil {
+			return uint32(n)
+		}
+	}
+	return def
+}
+
+func getenvFloat64(key string, def float64) float64 {
+	if v := os.Getenv(key); v != "" {
+		if n, err := strconv.ParseFloat(v, 64); err == nil {
+			return n
+		}
+	}
+	return def
+}
+
+func getenvDuration(key string, def time.Duration) time.Duration {
+	if v := os.Getenv(key); v != "" {
+		if d, err := time.ParseDuration(v); err == nil {
+			return d
+		}
+	}
+	return def
+}
+
+func getenvBool(key string, def bool) bool {
+	if v := os.Getenv(key); v != "" {
+		if b, err := strconv.ParseBool(v); err == nil {
+			return b
+		}
+	}
+	return def
+}
+
+func getenvCSV(key, def string) []string {
+	raw := os.Getenv(key)
+	if strings.TrimSpace(raw) == "" {
+		raw = def
+	}
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return nil
+	}
+
+	parts := strings.Split(raw, ",")
+	out := make([]string, 0, len(parts))
+	for i := range parts {
+		part := strings.TrimSpace(parts[i])
+		if part == "" {
+			continue
+		}
+		out = append(out, part)
+	}
+	return out
+}
+
+func normalizeMimeTypes(values []string) []string {
+	if len(values) == 0 {
+		return nil
+	}
+
+	out := make([]string, 0, len(values))
+	seen := make(map[string]struct{}, len(values))
+	for i := range values {
+		v := strings.ToLower(strings.TrimSpace(values[i]))
+		if idx := strings.Index(v, ";"); idx >= 0 {
+			v = strings.TrimSpace(v[:idx])
+		}
+		if v == "" {
+			continue
+		}
+		if _, ok := seen[v]; ok {
+			continue
+		}
+		seen[v] = struct{}{}
+		out = append(out, v)
+	}
+	return out
+}
+
+func normalizeExtensions(values []string) []string {
+	if len(values) == 0 {
+		return nil
+	}
+
+	out := make([]string, 0, len(values))
+	seen := make(map[string]struct{}, len(values))
+	for i := range values {
+		v := strings.ToLower(strings.TrimSpace(values[i]))
+		v = strings.TrimPrefix(v, ".")
+		if v == "" {
+			continue
+		}
+		if _, ok := seen[v]; ok {
+			continue
+		}
+		seen[v] = struct{}{}
+		out = append(out, v)
+	}
+	return out
+}
+
+func loadCircuitBreakerPolicyFromEnv(prefix string, defaults CircuitBreakerPolicy) CircuitBreakerPolicy {
+	return CircuitBreakerPolicy{
+		Enabled:             getenvBool(prefix+"ENABLED", defaults.Enabled),
+		MaxRequests:         getenvUint32(prefix+"MAX_REQUESTS", defaults.MaxRequests),
+		Interval:            getenvDuration(prefix+"INTERVAL", defaults.Interval),
+		BucketPeriod:        getenvDuration(prefix+"BUCKET_PERIOD", defaults.BucketPeriod),
+		Timeout:             getenvDuration(prefix+"TIMEOUT", defaults.Timeout),
+		MinRequests:         getenvUint32(prefix+"MIN_REQUESTS", defaults.MinRequests),
+		FailureRatio:        getenvFloat64(prefix+"FAILURE_RATIO", defaults.FailureRatio),
+		ConsecutiveFailures: getenvUint32(prefix+"CONSECUTIVE_FAILURES", defaults.ConsecutiveFailures),
+	}
+}
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
new file mode 100644
index 0000000..f8798d3
--- /dev/null
+++ b/internal/config/config_test.go
@@ -0,0 +1,340 @@
+package config
+
+import (
+	"testing"
+	"time"
+)
+
+func TestLoadFileManagerUploadPolicyConfigFromEnv_Defaults(t *testing.T) {
+	t.Setenv("FILE_MANAGER_UPLOAD_MAX_FILE_SIZE_BYTES", "")
+	t.Setenv("FILE_MANAGER_UPLOAD_ALLOWED_MIME_TYPES", "")
+	t.Setenv("FILE_MANAGER_UPLOAD_ALLOWED_EXTENSIONS", "")
+	t.Setenv("FILE_MANAGER_UPLOAD_ALLOW_EMPTY_FILE", "")
+	t.Setenv("FILE_MANAGER_UPLOAD_MAX_FILENAME_LENGTH", "")
+
+	cfg := LoadFileManagerUploadPolicyConfigFromEnv()
+
+	if cfg.MaxFileSizeBytes != 4*1024*1024 {
+		t.Fatalf("expected default max file size 4194304, got %d", cfg.MaxFileSizeBytes)
+	}
+	if cfg.AllowEmptyFile {
+		t.Fatalf("expected default allow empty file false")
+	}
+	if cfg.MaxFilenameLength != 255 {
+		t.Fatalf("expected default max filename length 255, got %d", cfg.MaxFilenameLength)
+	}
+	if len(cfg.AllowedMimeTypes) != 0 {
+		t.Fatalf("expected empty default allowed mime types, got %v", cfg.AllowedMimeTypes)
+	}
+	if len(cfg.AllowedExtensions) != 0 {
+		t.Fatalf("expected empty default allowed extensions, got %v", cfg.AllowedExtensions)
+	}
+}
+
+func TestLoadFileManagerUploadPolicyConfigFromEnv_Normalize(t *testing.T) {
+	t.Setenv("FILE_MANAGER_UPLOAD_MAX_FILE_SIZE_BYTES", "1048576")
+	t.Setenv("FILE_MANAGER_UPLOAD_ALLOWED_MIME_TYPES", " image/PNG ; charset=utf-8,application/pdf,IMAGE/PNG")
+	t.Setenv("FILE_MANAGER_UPLOAD_ALLOWED_EXTENSIONS", " .PDF, png ,PNG")
+	t.Setenv("FILE_MANAGER_UPLOAD_ALLOW_EMPTY_FILE", "true")
+	t.Setenv("FILE_MANAGER_UPLOAD_MAX_FILENAME_LENGTH", "120")
+
+	cfg := LoadFileManagerUploadPolicyConfigFromEnv()
+
+	if cfg.MaxFileSizeBytes != 1048576 {
+		t.Fatalf("expected max file size 1048576, got %d", cfg.MaxFileSizeBytes)
+	}
+	if !cfg.AllowEmptyFile {
+		t.Fatalf("expected allow empty file true")
+	}
+	if cfg.MaxFilenameLength != 120 {
+		t.Fatalf("expected max filename length 120, got %d", cfg.MaxFilenameLength)
+	}
+
+	if len(cfg.AllowedMimeTypes) != 2 || cfg.AllowedMimeTypes[0] != "image/png" || cfg.AllowedMimeTypes[1] != "application/pdf" {
+		t.Fatalf("unexpected normalized mime types: %v", cfg.AllowedMimeTypes)
+	}
+	if len(cfg.AllowedExtensions) != 2 || cfg.AllowedExtensions[0] != "pdf" || cfg.AllowedExtensions[1] != "png" {
+		t.Fatalf("unexpected normalized extensions: %v", cfg.AllowedExtensions)
+	}
+}
+
+func TestLoadFileManagerTrashPolicyConfigFromEnv_Defaults(t *testing.T) {
+	t.Setenv("FILE_MANAGER_TRASH_AUTO_PURGE_ENABLED", "")
+	t.Setenv("FILE_MANAGER_TRASH_RETENTION", "")
+	t.Setenv("FILE_MANAGER_TRASH_AUTO_PURGE_INTERVAL", "")
+	t.Setenv("FILE_MANAGER_TRASH_AUTO_PURGE_BATCH_SIZE", "")
+
+	cfg := LoadFileManagerTrashPolicyConfigFromEnv()
+	if !cfg.AutoPurgeEnabled {
+		t.Fatalf("expected default auto purge enabled")
+	}
+	if cfg.Retention != 30*24*time.Hour {
+		t.Fatalf("expected default retention 720h, got %s", cfg.Retention)
+	}
+	if cfg.AutoPurgeInterval != time.Hour {
+		t.Fatalf("expected default auto purge interval 1h, got %s", cfg.AutoPurgeInterval)
+	}
+	if cfg.AutoPurgeBatchSize != 200 {
+		t.Fatalf("expected default batch size 200, got %d", cfg.AutoPurgeBatchSize)
+	}
+}
+
+func TestLoadFileManagerTrashPolicyConfigFromEnv_Custom(t *testing.T) {
+	t.Setenv("FILE_MANAGER_TRASH_AUTO_PURGE_ENABLED", "false")
+	t.Setenv("FILE_MANAGER_TRASH_RETENTION", "168h")
+	t.Setenv("FILE_MANAGER_TRASH_AUTO_PURGE_INTERVAL", "15m")
+	t.Setenv("FILE_MANAGER_TRASH_AUTO_PURGE_BATCH_SIZE", "50")
+
+	cfg := LoadFileManagerTrashPolicyConfigFromEnv()
+	if cfg.AutoPurgeEnabled {
+		t.Fatalf("expected auto purge disabled")
+	}
+	if cfg.Retention != 168*time.Hour {
+		t.Fatalf("expected retention 168h, got %s", cfg.Retention)
+	}
+	if cfg.AutoPurgeInterval != 15*time.Minute {
+		t.Fatalf("expected auto purge interval 15m, got %s", cfg.AutoPurgeInterval)
+	}
+	if cfg.AutoPurgeBatchSize != 50 {
+		t.Fatalf("expected batch size 50, got %d", cfg.AutoPurgeBatchSize)
+	}
+}
+
+func TestLoadFileManagerLifecycleConfigFromEnv_Defaults(t *testing.T) {
+	t.Setenv("ENABLE_S3_TAGGING", "")
+	t.Setenv("ENABLE_FILE_CLEANUP_JOB", "")
+	t.Setenv("TEMP_UPLOAD_GRACE_HOURS", "")
+	t.Setenv("ORPHAN_GRACE_PERIOD_DAYS", "")
+	t.Setenv("FILE_CLEANUP_BATCH_SIZE", "")
+	t.Setenv("FILE_CLEANUP_DRY_RUN", "")
+
+	cfg := LoadFileManagerLifecycleConfigFromEnv()
+	if !cfg.EnableS3Tagging {
+		t.Fatalf("expected s3 tagging enabled by default")
+	}
+	if cfg.EnableCleanupJob {
+		t.Fatalf("expected cleanup job disabled by default")
+	}
+	if cfg.TempUploadGraceHours != 2 {
+		t.Fatalf("expected temp upload grace 2 hours, got %d", cfg.TempUploadGraceHours)
+	}
+	if cfg.OrphanGraceDays != 30 {
+		t.Fatalf("expected orphan grace 30 days, got %d", cfg.OrphanGraceDays)
+	}
+	if cfg.CleanupBatchSize != 100 {
+		t.Fatalf("expected cleanup batch size 100, got %d", cfg.CleanupBatchSize)
+	}
+	if !cfg.CleanupDryRun {
+		t.Fatalf("expected cleanup dry run enabled by default")
+	}
+}
+
+func TestLoadFileManagerLifecycleConfigFromEnv_Custom(t *testing.T) {
+	t.Setenv("ENABLE_S3_TAGGING", "false")
+	t.Setenv("ENABLE_FILE_CLEANUP_JOB", "true")
+	t.Setenv("TEMP_UPLOAD_GRACE_HOURS", "6")
+	t.Setenv("ORPHAN_GRACE_PERIOD_DAYS", "45")
+	t.Setenv("FILE_CLEANUP_BATCH_SIZE", "250")
+	t.Setenv("FILE_CLEANUP_DRY_RUN", "false")
+
+	cfg := LoadFileManagerLifecycleConfigFromEnv()
+	if cfg.EnableS3Tagging {
+		t.Fatalf("expected s3 tagging disabled")
+	}
+	if !cfg.EnableCleanupJob {
+		t.Fatalf("expected cleanup job enabled")
+	}
+	if cfg.TempUploadGraceHours != 6 {
+		t.Fatalf("expected temp upload grace 6 hours, got %d", cfg.TempUploadGraceHours)
+	}
+	if cfg.OrphanGraceDays != 45 {
+		t.Fatalf("expected orphan grace 45 days, got %d", cfg.OrphanGraceDays)
+	}
+	if cfg.CleanupBatchSize != 250 {
+		t.Fatalf("expected cleanup batch size 250, got %d", cfg.CleanupBatchSize)
+	}
+	if cfg.CleanupDryRun {
+		t.Fatalf("expected cleanup dry run disabled")
+	}
+}
+
+func TestLoadFileQueueConfigFromEnv_Defaults(t *testing.T) {
+	t.Setenv("FILE_QUEUE_MESSAGE_SCHEMA_VERSION", "")
+	t.Setenv("FILE_QUEUE_IDEMPOTENCY_KEY_PREFIX", "")
+	t.Setenv("FILE_QUEUE_WORKER_MONITOR_ADDR", "")
+	t.Setenv("FILE_QUEUE_OUTBOX_ENABLED", "")
+	t.Setenv("FILE_QUEUE_OUTBOX_POLL_INTERVAL", "")
+	t.Setenv("FILE_QUEUE_OUTBOX_BATCH_SIZE", "")
+	t.Setenv("FILE_QUEUE_OUTBOX_DISPATCH_TIMEOUT", "")
+	t.Setenv("FILE_QUEUE_OUTBOX_LOCK_TTL", "")
+	t.Setenv("FILE_QUEUE_OUTBOX_MAX_ATTEMPTS", "")
+
+	cfg := LoadFileQueueConfigFromEnv()
+	if cfg.MessageSchemaVersion != "v1" {
+		t.Fatalf("expected default schema version v1, got %q", cfg.MessageSchemaVersion)
+	}
+	if cfg.IdempotencyKeyPrefix != "queue:idempotency:file:" {
+		t.Fatalf("unexpected default idempotency prefix: %q", cfg.IdempotencyKeyPrefix)
+	}
+	if cfg.WorkerMonitorAddr != "127.0.0.1:9091" {
+		t.Fatalf("unexpected default monitor addr: %q", cfg.WorkerMonitorAddr)
+	}
+	if !cfg.OutboxEnabled {
+		t.Fatalf("expected default file outbox enabled")
+	}
+	if cfg.OutboxPollInterval != time.Second {
+		t.Fatalf("expected default outbox poll interval 1s, got %s", cfg.OutboxPollInterval)
+	}
+	if cfg.OutboxBatchSize != 10 {
+		t.Fatalf("expected default outbox batch size 10, got %d", cfg.OutboxBatchSize)
+	}
+	if cfg.OutboxDispatchTimeout != 10*time.Second {
+		t.Fatalf("expected default outbox dispatch timeout 10s, got %s", cfg.OutboxDispatchTimeout)
+	}
+	if cfg.OutboxLockTTL != time.Minute {
+		t.Fatalf("expected default outbox lock ttl 1m, got %s", cfg.OutboxLockTTL)
+	}
+	if cfg.OutboxMaxAttempts != 20 {
+		t.Fatalf("expected default outbox max attempts 20, got %d", cfg.OutboxMaxAttempts)
+	}
+}
+
+func TestLoadFileSQSConfigFromEnv(t *testing.T) {
+	t.Setenv("AWS_REGION", "ap-southeast-1")
+	t.Setenv("SQS_ENDPOINT", "http://localhost:4566")
+	t.Setenv("SQS_ALLOW_INSECURE_ENDPOINT", "true")
+	t.Setenv("FILE_SQS_REGION", "")
+	t.Setenv("FILE_SQS_ENDPOINT", "")
+	t.Setenv("FILE_SQS_QUEUE_URL", "http://localhost:4566/000000000000/app-file-queue")
+	t.Setenv("FILE_SQS_QUEUE_TYPE", "standard")
+	t.Setenv("FILE_SQS_MESSAGE_GROUP_ID", "file")
+	t.Setenv("FILE_SQS_MAX_MESSAGES", "8")
+	t.Setenv("FILE_SQS_WAIT_TIME_SECONDS", "15")
+	t.Setenv("FILE_SQS_VISIBILITY_TIMEOUT", "90s")
+	t.Setenv("FILE_SQS_ALLOW_INSECURE_ENDPOINT", "")
+
+	cfg := LoadFileSQSConfigFromEnv()
+	if cfg.Region != "ap-southeast-1" {
+		t.Fatalf("unexpected region: %q", cfg.Region)
+	}
+	if cfg.Endpoint != "http://localhost:4566" {
+		t.Fatalf("unexpected endpoint: %q", cfg.Endpoint)
+	}
+	if cfg.QueueURL == "" {
+		t.Fatalf("expected queue url")
+	}
+	if cfg.MaxMessages != 8 {
+		t.Fatalf("unexpected max messages: %d", cfg.MaxMessages)
+	}
+	if cfg.WaitTimeSeconds != 15 {
+		t.Fatalf("unexpected wait time seconds: %d", cfg.WaitTimeSeconds)
+	}
+	if !cfg.AllowInsecureEndpoint {
+		t.Fatalf("expected insecure endpoint allowed from fallback")
+	}
+}
+
+func TestValidateDistinctQueueURLs(t *testing.T) {
+	t.Run("different queue urls", func(t *testing.T) {
+		err := ValidateDistinctQueueURLs(
+			SQSConfig{QueueURL: "http://localhost:4566/000000000000/app-queue"},
+			SQSConfig{QueueURL: "http://localhost:4566/000000000000/app-file-queue"},
+		)
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+	})
+
+	t.Run("same queue urls with different case and slash", func(t *testing.T) {
+		err := ValidateDistinctQueueURLs(
+			SQSConfig{QueueURL: "HTTP://LOCALHOST:4566/000000000000/app-queue"},
+			SQSConfig{QueueURL: "http://localhost:4566/000000000000/app-queue/"},
+		)
+		if err == nil {
+			t.Fatalf("expected error for same queue urls")
+		}
+	})
+
+	t.Run("skip when one queue url empty", func(t *testing.T) {
+		err := ValidateDistinctQueueURLs(
+			SQSConfig{QueueURL: "http://localhost:4566/000000000000/app-queue"},
+			SQSConfig{QueueURL: ""},
+		)
+		if err != nil {
+			t.Fatalf("expected no error when file queue url is empty, got %v", err)
+		}
+	})
+}
+
+func TestParseHTTPTimeoutOverrides(t *testing.T) {
+	t.Run("invalid format ignored", func(t *testing.T) {
+		parsed := parseHTTPTimeoutOverrides("GET /users/:id 100ms,foo")
+		if len(parsed) != 0 {
+			t.Fatalf("expected no parsed entries, got %v", parsed)
+		}
+	})
+
+	t.Run("invalid duration ignored", func(t *testing.T) {
+		parsed := parseHTTPTimeoutOverrides("GET /users/:id=not-a-duration")
+		if len(parsed) != 0 {
+			t.Fatalf("expected no parsed entries, got %v", parsed)
+		}
+	})
+
+	t.Run("zero and negative duration ignored", func(t *testing.T) {
+		parsed := parseHTTPTimeoutOverrides("GET /users/:id=0s,POST /users=-1s")
+		if len(parsed) != 0 {
+			t.Fatalf("expected no parsed entries, got %v", parsed)
+		}
+	})
+
+	t.Run("valid entries parsed", func(t *testing.T) {
+		parsed := parseHTTPTimeoutOverrides("GET /users/:id=120ms, POST /auth/login = 2s")
+		if len(parsed) != 2 {
+			t.Fatalf("expected 2 parsed entries, got %d", len(parsed))
+		}
+		if parsed["GET /users/:id"] != 120*time.Millisecond {
+			t.Fatalf("unexpected GET /users/:id timeout: %s", parsed["GET /users/:id"])
+		}
+		if parsed["POST /auth/login"] != 2*time.Second {
+			t.Fatalf("unexpected POST /auth/login timeout: %s", parsed["POST /auth/login"])
+		}
+	})
+}
+
+func TestParseHTTPEndpointRateLimitOverrides(t *testing.T) {
+	t.Run("invalid entries ignored", func(t *testing.T) {
+		parsed := parseHTTPEndpointRateLimitOverrides("POST /auth/login=abc,1m;foo;GET /x=1")
+		if len(parsed) != 0 {
+			t.Fatalf("expected no parsed entries, got %v", parsed)
+		}
+	})
+
+	t.Run("zero or negative values ignored", func(t *testing.T) {
+		parsed := parseHTTPEndpointRateLimitOverrides("POST /auth/login=0,1m;POST /auth/totp/verify=5,0s")
+		if len(parsed) != 0 {
+			t.Fatalf("expected no parsed entries, got %v", parsed)
+		}
+	})
+
+	t.Run("valid entries parsed", func(t *testing.T) {
+		parsed := parseHTTPEndpointRateLimitOverrides("POST /auth/login=5,1m; POST /auth/totp/verify = 3,30s")
+		if len(parsed) != 2 {
+			t.Fatalf("expected 2 parsed entries, got %d", len(parsed))
+		}
+		login, ok := parsed["POST /auth/login"]
+		if !ok {
+			t.Fatalf("expected POST /auth/login to be parsed")
+		}
+		if login.Max != 5 || login.Window != time.Minute {
+			t.Fatalf("unexpected login rule: %+v", login)
+		}
+		totp, ok := parsed["POST /auth/totp/verify"]
+		if !ok {
+			t.Fatalf("expected POST /auth/totp/verify to be parsed")
+		}
+		if totp.Max != 3 || totp.Window != 30*time.Second {
+			t.Fatalf("unexpected totp rule: %+v", totp)
+		}
+	})
+}
diff --git a/internal/config/loader.go b/internal/config/loader.go
new file mode 100644
index 0000000..1c69b93
--- /dev/null
+++ b/internal/config/loader.go
@@ -0,0 +1,638 @@
+package config
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+)
+
+// Duration unmarshals a Go duration string (e.g. "30s", "5m", "150ms") from JSON.
+// An empty string is treated as zero duration.
+type Duration struct{ time.Duration }
+
+func (d *Duration) UnmarshalJSON(b []byte) error {
+	var s string
+	if err := json.Unmarshal(b, &s); err != nil {
+		return err
+	}
+	if s == "" {
+		d.Duration = 0
+		return nil
+	}
+	dur, err := time.ParseDuration(s)
+	if err != nil {
+		return fmt.Errorf("invalid duration %q: %w", s, err)
+	}
+	d.Duration = dur
+	return nil
+}
+
+// AppConfig is the unified config loaded from a JSON file.
+type AppConfig struct {
+	HTTPPort     int
+	MySQL        MySQLConfig
+	Logging      LoggingConfig
+	Audit        AuditConfig
+	Auth         AuthConfig
+	SES          SESConfig
+	Email        EmailDeliveryConfig
+	MicrosoftSSO MicrosoftSSOConfig
+	HTTP         HTTPConfig
+	Resilience   ResilienceConfig
+	Queue        QueueConfig
+	FileQueue    FileQueueConfig
+	SQS          SQSConfig
+	FileSQS      SQSConfig
+	FileStorage  FileStorageConfig
+	FileUpload   FileManagerUploadPolicyConfig
+	SAML         SAMLConfig
+	WOPI         WOPIConfig
+	Gotenberg    GotenbergConfig
+}
+
+// LoadFromFile reads path, parses it as JSON, and returns a populated AppConfig.
+// The file is typically produced by scripts/inject-secrets.sh.
+func LoadFromFile(path string) (AppConfig, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return AppConfig{}, fmt.Errorf("config: read %q: %w", path, err)
+	}
+	var raw jsonAppConfig
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return AppConfig{}, fmt.Errorf("config: parse %q: %w", path, err)
+	}
+	return raw.toAppConfig(), nil
+}
+
+// ── JSON intermediate types ───────────────────────────────────────────────────
+
+type jsonCircuitBreakerPolicy struct {
+	Enabled             bool     `json:"enabled"`
+	MaxRequests         uint32   `json:"maxRequests"`
+	Interval            Duration `json:"interval"`
+	BucketPeriod        Duration `json:"bucketPeriod"`
+	Timeout             Duration `json:"timeout"`
+	MinRequests         uint32   `json:"minRequests"`
+	FailureRatio        float64  `json:"failureRatio"`
+	ConsecutiveFailures uint32   `json:"consecutiveFailures"`
+}
+
+func (j jsonCircuitBreakerPolicy) toPolicy() CircuitBreakerPolicy {
+	return CircuitBreakerPolicy{
+		Enabled:             j.Enabled,
+		MaxRequests:         j.MaxRequests,
+		Interval:            j.Interval.Duration,
+		BucketPeriod:        j.BucketPeriod.Duration,
+		Timeout:             j.Timeout.Duration,
+		MinRequests:         j.MinRequests,
+		FailureRatio:        j.FailureRatio,
+		ConsecutiveFailures: j.ConsecutiveFailures,
+	}
+}
+
+type jsonWorker struct {
+	Concurrency           int      `json:"concurrency"`
+	MaxBatchSize          int      `json:"maxBatchSize"`
+	ProcessTimeout        Duration `json:"processTimeout"`
+	ShutdownTimeout       Duration `json:"shutdownTimeout"`
+	BackoffMin            Duration `json:"backoffMin"`
+	BackoffMax            Duration `json:"backoffMax"`
+	PermanentFailureDelay Duration `json:"permanentFailureDelay"`
+	MonitorAddr           string   `json:"monitorAddr"`
+	HealthErrorThreshold  int      `json:"healthErrorThreshold"`
+	DepthPollInterval     Duration `json:"depthPollInterval"`
+}
+
+type jsonOutbox struct {
+	Enabled         bool     `json:"enabled"`
+	PollInterval    Duration `json:"pollInterval"`
+	BatchSize       int      `json:"batchSize"`
+	DispatchTimeout Duration `json:"dispatchTimeout"`
+	LockTTL         Duration `json:"lockTTL"`
+	MaxAttempts     int      `json:"maxAttempts"`
+}
+
+type jsonSQS struct {
+	Region                string   `json:"region"`
+	Endpoint              string   `json:"endpoint"`
+	AllowInsecureEndpoint bool     `json:"allowInsecureEndpoint"`
+	QueueURL              string   `json:"queueUrl"`
+	QueueType             string   `json:"queueType"`
+	MessageGroupID        string   `json:"messageGroupId"`
+	MaxMessages           int      `json:"maxMessages"`
+	WaitTimeSeconds       int32    `json:"waitTimeSeconds"`
+	VisibilityTimeout     Duration `json:"visibilityTimeout"`
+}
+
+func (j jsonSQS) toSQSConfig(regionFallback, endpointFallback, accessKeyID, secretAccessKey string) SQSConfig {
+	region := j.Region
+	if region == "" {
+		region = regionFallback
+	}
+	endpoint := j.Endpoint
+	if endpoint == "" {
+		endpoint = endpointFallback
+	}
+	return SQSConfig{
+		Region:                region,
+		AccessKeyID:           strings.TrimSpace(accessKeyID),
+		SecretAccessKey:       strings.TrimSpace(secretAccessKey),
+		Endpoint:              endpoint,
+		QueueURL:              j.QueueURL,
+		QueueType:             j.QueueType,
+		MessageGroupID:        j.MessageGroupID,
+		MaxMessages:           j.MaxMessages,
+		WaitTimeSeconds:       j.WaitTimeSeconds,
+		VisibilityTimeout:     j.VisibilityTimeout.Duration,
+		AllowInsecureEndpoint: j.AllowInsecureEndpoint,
+	}
+}
+
+type jsonAppConfig struct {
+	HTTP struct {
+		Port      int `json:"port"`
+		BodyLimit int `json:"bodyLimit"`
+		Timeouts  struct {
+			Read             Duration `json:"read"`
+			Write            Duration `json:"write"`
+			Idle             Duration `json:"idle"`
+			Request          Duration `json:"request"`
+			RequestOverrides string   `json:"requestOverrides"`
+			Shutdown         Duration `json:"shutdown"`
+		} `json:"timeouts"`
+		CORS struct {
+			AllowOrigins     string `json:"allowOrigins"`
+			AllowMethods     string `json:"allowMethods"`
+			AllowHeaders     string `json:"allowHeaders"`
+			ExposeHeaders    string `json:"exposeHeaders"`
+			AllowCredentials bool   `json:"allowCredentials"`
+			MaxAge           int    `json:"maxAge"`
+		} `json:"cors"`
+		RateLimit struct {
+			Max       int      `json:"max"`
+			Window    Duration `json:"window"`
+			Endpoints string   `json:"endpoints"`
+		} `json:"rateLimit"`
+		Security struct {
+			HSTSMaxAge int `json:"hstsMaxAge"`
+		} `json:"security"`
+	} `json:"http"`
+
+	Database struct {
+		MySQL struct {
+			DSN             string   `json:"dsn"`
+			MaxOpenConns    int      `json:"maxOpenConns"`
+			MaxIdleConns    int      `json:"maxIdleConns"`
+			ConnMaxLifetime Duration `json:"connMaxLifetime"`
+			ConnMaxIdleTime Duration `json:"connMaxIdleTime"`
+		} `json:"mysql"`
+	} `json:"database"`
+
+	Logging struct {
+		Level  string `json:"level"`
+		Format string `json:"format"`
+	} `json:"logging"`
+
+	Audit struct {
+		QueueSize int `json:"queueSize"`
+		Workers   int `json:"workers"`
+	} `json:"audit"`
+
+	Email struct {
+		Provider string `json:"provider"`
+		MockDir  string `json:"mockDir"`
+	} `json:"email"`
+
+	CircuitBreaker struct {
+		Default      jsonCircuitBreakerPolicy `json:"default"`
+		MicrosoftSSO jsonCircuitBreakerPolicy `json:"microsoftSSO"`
+		SES          jsonCircuitBreakerPolicy `json:"ses"`
+		SQS          jsonCircuitBreakerPolicy `json:"sqs"`
+	} `json:"circuitBreaker"`
+
+	Auth struct {
+		PublicBaseURL   string `json:"publicBaseURL"`
+		PasswordPepper  string `json:"passwordPepper"`
+		IPEncryptionKey string `json:"ipEncryptionKey"`
+		DefaultRole     string `json:"defaultRole"`
+		DisableRegister bool   `json:"disableRegister"`
+		Hash            struct {
+			Time     uint32 `json:"time"`
+			MemoryKB uint32 `json:"memoryKB"`
+			Threads  uint8  `json:"threads"`
+			KeyLen   uint32 `json:"keyLen"`
+		} `json:"hash"`
+		Email struct {
+			VerifyTTL Duration `json:"verifyTTL"`
+			VerifyURL string   `json:"verifyURL"`
+			InviteTTL Duration `json:"inviteTTL"`
+		} `json:"email"`
+		Password struct {
+			SetURL              string   `json:"setURL"`
+			ResetTTL            Duration `json:"resetTTL"`
+			ResetURL            string   `json:"resetURL"`
+			ForgotEmailCooldown Duration `json:"forgotEmailCooldown"`
+			ForgotMinDuration   Duration `json:"forgotMinDuration"`
+			ForgotIPRateMax     int      `json:"forgotIPRateMax"`
+			ForgotIPRateWindow  Duration `json:"forgotIPRateWindow"`
+			LoginIPRateMax      int      `json:"loginIPRateMax"`
+			LoginIPRateWindow   Duration `json:"loginIPRateWindow"`
+		} `json:"password"`
+		SecurityPin struct {
+			ResetTTL            Duration `json:"resetTTL"`
+			ResetURL            string   `json:"resetURL"`
+			ForgotEmailCooldown Duration `json:"forgotEmailCooldown"`
+			ForgotMinDuration   Duration `json:"forgotMinDuration"`
+			MaxAttempts         int      `json:"maxAttempts"`
+			LockDuration        Duration `json:"lockDuration"`
+			ActionTokenTTL      Duration `json:"actionTokenTTL"`
+		} `json:"securityPin"`
+		JWT struct {
+			AccessSecret    string   `json:"accessSecret"`
+			RefreshSecret   string   `json:"refreshSecret"`
+			AccessTTL       Duration `json:"accessTTL"`
+			RefreshTTL      Duration `json:"refreshTTL"`
+			RefreshTotpTTL  Duration `json:"refreshTotpTTL"`
+			LocalRefreshTTL Duration `json:"localRefreshTTL"`
+			SessionIdleTTL  Duration `json:"sessionIdleTTL"`
+			Cookie          struct {
+				Domain      string `json:"domain"`
+				Secure      bool   `json:"secure"`
+				SameSite    string `json:"sameSite"`
+				AccessName  string `json:"accessName"`
+				RefreshName string `json:"refreshName"`
+			} `json:"cookie"`
+		} `json:"jwt"`
+		TOTP struct {
+			ChallengeTTL Duration `json:"challengeTTL"`
+		} `json:"totp"`
+		SSO struct {
+			StateTTL        Duration `json:"stateTTL"`
+			SuccessRedirect string   `json:"successRedirect"`
+		} `json:"sso"`
+		WebAuthn struct {
+			RPID          string   `json:"rpId"`
+			RPDisplayName string   `json:"rpDisplayName"`
+			RPOrigins     string   `json:"rpOrigins"`
+			ChallengeTTL  Duration `json:"challengeTTL"`
+		} `json:"webauthn"`
+	} `json:"auth"`
+
+	TOTP struct {
+		Issuer    string `json:"issuer"`
+		SecretKey string `json:"secretKey"`
+	} `json:"totp"`
+
+	MicrosoftSSO struct {
+		TenantID     string `json:"tenantId"`
+		ClientID     string `json:"clientId"`
+		ClientSecret string `json:"clientSecret"`
+		RedirectURL  string `json:"redirectUrl"`
+		Authority    string `json:"authority"`
+		Scopes       string `json:"scopes"`
+	} `json:"microsoftSSO"`
+	SAML struct {
+		CertFile     string `json:"certFile"`
+		KeyFile      string `json:"keyFile"`
+		MetadataFile string `json:"metadataFile"`
+		RootURL      string `json:"rootUrl"`
+		FrontendURL  string `json:"frontendUrl"`
+		CookieDomain string `json:"cookieDomain"`
+		CookieSecure bool   `json:"cookieSecure"`
+		SessionTTLHr int    `json:"sessionTTLHour"`
+	} `json:"saml"`
+
+	Queue struct {
+		MessageSchemaVersion        string     `json:"messageSchemaVersion"`
+		EnableLegacyPayloadFallback bool       `json:"enableLegacyPayloadFallback"`
+		IdempotencyKeyPrefix        string     `json:"idempotencyKeyPrefix"`
+		IdempotencyTTL              Duration   `json:"idempotencyTTL"`
+		ProcessingTTL               Duration   `json:"processingTTL"`
+		Worker                      jsonWorker `json:"worker"`
+		Outbox                      jsonOutbox `json:"outbox"`
+	} `json:"queue"`
+
+	FileQueue struct {
+		MessageSchemaVersion string     `json:"messageSchemaVersion"`
+		IdempotencyKeyPrefix string     `json:"idempotencyKeyPrefix"`
+		IdempotencyTTL       Duration   `json:"idempotencyTTL"`
+		ProcessingTTL        Duration   `json:"processingTTL"`
+		Worker               jsonWorker `json:"worker"`
+		Outbox               jsonOutbox `json:"outbox"`
+	} `json:"fileQueue"`
+
+	AWS struct {
+		Region          string  `json:"region"`
+		AccessKeyID     string  `json:"accessKeyId"`
+		SecretAccessKey string  `json:"secretAccessKey"`
+		SQS             jsonSQS `json:"sqs"`
+		FileSQS         jsonSQS `json:"fileSqs"`
+		SES             struct {
+			Region                string   `json:"region"`
+			Endpoint              string   `json:"endpoint"`
+			From                  string   `json:"from"`
+			ConfigurationSet      string   `json:"configurationSet"`
+			SendTimeout           Duration `json:"sendTimeout"`
+			AllowInsecureEndpoint bool     `json:"allowInsecureEndpoint"`
+		} `json:"ses"`
+	} `json:"aws"`
+
+	File struct {
+		Provider string `json:"provider"`
+		S3       struct {
+			Bucket                string   `json:"bucket"`
+			Region                string   `json:"region"`
+			Endpoint              string   `json:"endpoint"`
+			ForcePathStyle        bool     `json:"forcePathStyle"`
+			AllowInsecureEndpoint bool     `json:"allowInsecureEndpoint"`
+			AutoCreateBucket      bool     `json:"autoCreateBucket"`
+			ObjectKeyPrefix       string   `json:"objectKeyPrefix"`
+			PresignPutTTL         Duration `json:"presignPutTTL"`
+			PresignGetTTL         Duration `json:"presignGetTTL"`
+		} `json:"s3"`
+		Upload struct {
+			MaxSize           int64  `json:"maxSize"`
+			AllowedMimeTypes  string `json:"allowedMimeTypes"`
+			AllowedExtensions string `json:"allowedExtensions"`
+			AllowEmptyFile    bool   `json:"allowEmptyFile"`
+			MaxFilenameLength int    `json:"maxFilenameLength"`
+		} `json:"upload"`
+	} `json:"file"`
+
+	WOPI struct {
+		TokenSecret   string   `json:"tokenSecret"`
+		ProofSecret   string   `json:"proofSecret"`
+		DiscoveryURL  string   `json:"discoveryUrl"`
+		PublicBaseURL string   `json:"publicBaseUrl"`
+		EditActionURL string   `json:"editActionUrl"`
+		TokenTTL      Duration `json:"tokenTTL"`
+		MaxBodyBytes  int      `json:"maxBodyBytes"`
+		RequireProof  bool     `json:"requireProof"`
+	} `json:"wopi"`
+
+	Gotenberg struct {
+		URL string `json:"url"`
+	} `json:"gotenberg"`
+}
+
+func (r *jsonAppConfig) toAppConfig() AppConfig {
+	// IPEncryptionKey falls back to PasswordPepper when not set (mirrors env loader behaviour)
+	ipKey := r.Auth.IPEncryptionKey
+	if ipKey == "" {
+		ipKey = r.Auth.PasswordPepper
+	}
+
+	// RefreshTotpTTL falls back to RefreshTTL when not set
+	refreshTotpTTL := r.Auth.JWT.RefreshTotpTTL.Duration
+	if refreshTotpTTL == 0 {
+		refreshTotpTTL = r.Auth.JWT.RefreshTTL.Duration
+	}
+
+	// SES region falls back to aws.region
+	sesRegion := r.AWS.SES.Region
+	if sesRegion == "" {
+		sesRegion = r.AWS.Region
+	}
+
+	return AppConfig{
+		HTTPPort: r.HTTP.Port,
+
+		MySQL: MySQLConfig{
+			DSN:             r.Database.MySQL.DSN,
+			MaxOpenConns:    r.Database.MySQL.MaxOpenConns,
+			MaxIdleConns:    r.Database.MySQL.MaxIdleConns,
+			ConnMaxLifetime: r.Database.MySQL.ConnMaxLifetime.Duration,
+			ConnMaxIdleTime: r.Database.MySQL.ConnMaxIdleTime.Duration,
+		},
+
+		Logging: LoggingConfig{
+			Level:  r.Logging.Level,
+			Format: r.Logging.Format,
+		},
+
+		Audit: AuditConfig{
+			QueueSize: r.Audit.QueueSize,
+			Workers:   r.Audit.Workers,
+		},
+
+		Email: EmailDeliveryConfig{
+			Provider: strings.ToLower(strings.TrimSpace(r.Email.Provider)),
+			MockDir:  strings.TrimSpace(r.Email.MockDir),
+		},
+
+		SES: SESConfig{
+			Region:                sesRegion,
+			Endpoint:              r.AWS.SES.Endpoint,
+			From:                  r.AWS.SES.From,
+			ConfigurationSetName:  r.AWS.SES.ConfigurationSet,
+			SendTimeout:           r.AWS.SES.SendTimeout.Duration,
+			AllowInsecureEndpoint: r.AWS.SES.AllowInsecureEndpoint,
+		},
+
+		Auth: AuthConfig{
+			PublicBaseURL:                r.Auth.PublicBaseURL,
+			PasswordPepper:               r.Auth.PasswordPepper,
+			IPEncryptionKey:              ipKey,
+			HashTime:                     r.Auth.Hash.Time,
+			HashMemoryKB:                 r.Auth.Hash.MemoryKB,
+			HashThreads:                  r.Auth.Hash.Threads,
+			HashKeyLen:                   r.Auth.Hash.KeyLen,
+			EmailVerifyTTL:               r.Auth.Email.VerifyTTL.Duration,
+			EmailVerifyURL:               r.Auth.Email.VerifyURL,
+			InviteTTL:                    r.Auth.Email.InviteTTL.Duration,
+			SetPasswordURL:               r.Auth.Password.SetURL,
+			PasswordResetTTL:             r.Auth.Password.ResetTTL.Duration,
+			PasswordResetURL:             r.Auth.Password.ResetURL,
+			SecurityPINResetTTL:          r.Auth.SecurityPin.ResetTTL.Duration,
+			SecurityPINResetURL:          r.Auth.SecurityPin.ResetURL,
+			ForgotSecurityPINCooldown:    r.Auth.SecurityPin.ForgotEmailCooldown.Duration,
+			ForgotSecurityPINMinDuration: r.Auth.SecurityPin.ForgotMinDuration.Duration,
+			SecurityPINMaxAttempts:       r.Auth.SecurityPin.MaxAttempts,
+			SecurityPINLockDuration:      r.Auth.SecurityPin.LockDuration.Duration,
+			SecurityPINActionTokenTTL:    r.Auth.SecurityPin.ActionTokenTTL.Duration,
+			ForgotPasswordEmailCooldown:  r.Auth.Password.ForgotEmailCooldown.Duration,
+			ForgotPasswordMinDuration:    r.Auth.Password.ForgotMinDuration.Duration,
+			ForgotPasswordIPRateMax:      r.Auth.Password.ForgotIPRateMax,
+			ForgotPasswordIPRateWindow:   r.Auth.Password.ForgotIPRateWindow.Duration,
+			LoginIPRateMax:               r.Auth.Password.LoginIPRateMax,
+			LoginIPRateWindow:            r.Auth.Password.LoginIPRateWindow.Duration,
+			TOTPChallengeTTL:             r.Auth.TOTP.ChallengeTTL.Duration,
+			SSOStateTTL:                  r.Auth.SSO.StateTTL.Duration,
+			TOTPIssuer:                   r.TOTP.Issuer,
+			TOTPSecretKeyB64:             r.TOTP.SecretKey,
+			JWTAccessSecret:              r.Auth.JWT.AccessSecret,
+			JWTRefreshSecret:             r.Auth.JWT.RefreshSecret,
+			JWTAccessTTL:                 r.Auth.JWT.AccessTTL.Duration,
+			JWTRefreshTTL:                r.Auth.JWT.RefreshTTL.Duration,
+			JWTRefreshTOTPTTL:            refreshTotpTTL,
+			JWTLocalRefreshTTL:           r.Auth.JWT.LocalRefreshTTL.Duration,
+			SessionIdleTTL:               r.Auth.JWT.SessionIdleTTL.Duration,
+			JWTCookieDomain:              r.Auth.JWT.Cookie.Domain,
+			JWTCookieSecure:              r.Auth.JWT.Cookie.Secure,
+			JWTCookieSameSite:            r.Auth.JWT.Cookie.SameSite,
+			JWTAccessCookieName:          r.Auth.JWT.Cookie.AccessName,
+			JWTRefreshCookieName:         r.Auth.JWT.Cookie.RefreshName,
+			WebAuthnRPID:                 r.Auth.WebAuthn.RPID,
+			WebAuthnRPDisplayName:        r.Auth.WebAuthn.RPDisplayName,
+			WebAuthnRPOrigins:            splitCSV(r.Auth.WebAuthn.RPOrigins),
+			WebAuthnChallengeTTL:         r.Auth.WebAuthn.ChallengeTTL.Duration,
+			SSOSuccessRedirectURL:        r.Auth.SSO.SuccessRedirect,
+			DefaultRoleName:              r.Auth.DefaultRole,
+			DisableRegister:              r.Auth.DisableRegister,
+		},
+
+		MicrosoftSSO: MicrosoftSSOConfig{
+			TenantID:     r.MicrosoftSSO.TenantID,
+			ClientID:     r.MicrosoftSSO.ClientID,
+			ClientSecret: r.MicrosoftSSO.ClientSecret,
+			RedirectURL:  r.MicrosoftSSO.RedirectURL,
+			Authority:    r.MicrosoftSSO.Authority,
+			Scopes:       splitCSV(r.MicrosoftSSO.Scopes),
+		},
+		SAML: SAMLConfig{
+			CertFile:     strings.TrimSpace(r.SAML.CertFile),
+			KeyFile:      strings.TrimSpace(r.SAML.KeyFile),
+			MetadataFile: strings.TrimSpace(r.SAML.MetadataFile),
+			RootURL:      strings.TrimSpace(r.SAML.RootURL),
+			FrontendURL:  strings.TrimSpace(r.SAML.FrontendURL),
+			CookieDomain: strings.TrimSpace(r.SAML.CookieDomain),
+			CookieSecure: r.SAML.CookieSecure,
+			SessionTTLHr: r.SAML.SessionTTLHr,
+		},
+
+		HTTP: HTTPConfig{
+			BodyLimit:            r.HTTP.BodyLimit,
+			ReadTimeout:          r.HTTP.Timeouts.Read.Duration,
+			WriteTimeout:         r.HTTP.Timeouts.Write.Duration,
+			IdleTimeout:          r.HTTP.Timeouts.Idle.Duration,
+			RequestTimeout:       r.HTTP.Timeouts.Request.Duration,
+			RequestTimeoutByPath: parseHTTPTimeoutOverrides(r.HTTP.Timeouts.RequestOverrides),
+			ShutdownTimeout:      r.HTTP.Timeouts.Shutdown.Duration,
+			CORSAllowOrigins:     r.HTTP.CORS.AllowOrigins,
+			CORSAllowMethods:     r.HTTP.CORS.AllowMethods,
+			CORSAllowHeaders:     r.HTTP.CORS.AllowHeaders,
+			CORSExposeHeaders:    r.HTTP.CORS.ExposeHeaders,
+			CORSAllowCredentials: r.HTTP.CORS.AllowCredentials,
+			CORSMaxAge:           r.HTTP.CORS.MaxAge,
+			RateLimitMax:         r.HTTP.RateLimit.Max,
+			RateLimitWindow:      r.HTTP.RateLimit.Window.Duration,
+			RateLimitByEndpoint:  parseHTTPEndpointRateLimitOverrides(r.HTTP.RateLimit.Endpoints),
+			HSTSMaxAge:           r.HTTP.Security.HSTSMaxAge,
+		},
+
+		Resilience: ResilienceConfig{
+			Default:      r.CircuitBreaker.Default.toPolicy(),
+			MicrosoftSSO: r.CircuitBreaker.MicrosoftSSO.toPolicy(),
+			SES:          r.CircuitBreaker.SES.toPolicy(),
+			SQS:          r.CircuitBreaker.SQS.toPolicy(),
+		},
+
+		Queue: QueueConfig{
+			MessageSchemaVersion:        r.Queue.MessageSchemaVersion,
+			EnableLegacyPayloadFallback: r.Queue.EnableLegacyPayloadFallback,
+			IdempotencyKeyPrefix:        r.Queue.IdempotencyKeyPrefix,
+			IdempotencyTTL:              r.Queue.IdempotencyTTL.Duration,
+			ProcessingTTL:               r.Queue.ProcessingTTL.Duration,
+			WorkerConcurrency:           r.Queue.Worker.Concurrency,
+			WorkerMaxBatchSize:          r.Queue.Worker.MaxBatchSize,
+			WorkerProcessTimeout:        r.Queue.Worker.ProcessTimeout.Duration,
+			WorkerShutdownTimeout:       r.Queue.Worker.ShutdownTimeout.Duration,
+			WorkerBackoffMin:            r.Queue.Worker.BackoffMin.Duration,
+			WorkerBackoffMax:            r.Queue.Worker.BackoffMax.Duration,
+			WorkerPermanentFailureDelay: r.Queue.Worker.PermanentFailureDelay.Duration,
+			WorkerMonitorAddr:           r.Queue.Worker.MonitorAddr,
+			WorkerHealthErrorThreshold:  r.Queue.Worker.HealthErrorThreshold,
+			WorkerDepthPollInterval:     r.Queue.Worker.DepthPollInterval.Duration,
+			OutboxEnabled:               r.Queue.Outbox.Enabled,
+			OutboxPollInterval:          r.Queue.Outbox.PollInterval.Duration,
+			OutboxBatchSize:             r.Queue.Outbox.BatchSize,
+			OutboxDispatchTimeout:       r.Queue.Outbox.DispatchTimeout.Duration,
+			OutboxLockTTL:               r.Queue.Outbox.LockTTL.Duration,
+			OutboxMaxAttempts:           r.Queue.Outbox.MaxAttempts,
+		},
+
+		FileQueue: FileQueueConfig{
+			MessageSchemaVersion:        r.FileQueue.MessageSchemaVersion,
+			IdempotencyKeyPrefix:        r.FileQueue.IdempotencyKeyPrefix,
+			IdempotencyTTL:              r.FileQueue.IdempotencyTTL.Duration,
+			ProcessingTTL:               r.FileQueue.ProcessingTTL.Duration,
+			WorkerConcurrency:           r.FileQueue.Worker.Concurrency,
+			WorkerMaxBatchSize:          r.FileQueue.Worker.MaxBatchSize,
+			WorkerProcessTimeout:        r.FileQueue.Worker.ProcessTimeout.Duration,
+			WorkerShutdownTimeout:       r.FileQueue.Worker.ShutdownTimeout.Duration,
+			WorkerBackoffMin:            r.FileQueue.Worker.BackoffMin.Duration,
+			WorkerBackoffMax:            r.FileQueue.Worker.BackoffMax.Duration,
+			WorkerPermanentFailureDelay: r.FileQueue.Worker.PermanentFailureDelay.Duration,
+			WorkerMonitorAddr:           r.FileQueue.Worker.MonitorAddr,
+			WorkerHealthErrorThreshold:  r.FileQueue.Worker.HealthErrorThreshold,
+			WorkerDepthPollInterval:     r.FileQueue.Worker.DepthPollInterval.Duration,
+			OutboxEnabled:               r.FileQueue.Outbox.Enabled,
+			OutboxPollInterval:          r.FileQueue.Outbox.PollInterval.Duration,
+			OutboxBatchSize:             r.FileQueue.Outbox.BatchSize,
+			OutboxDispatchTimeout:       r.FileQueue.Outbox.DispatchTimeout.Duration,
+			OutboxLockTTL:               r.FileQueue.Outbox.LockTTL.Duration,
+			OutboxMaxAttempts:           r.FileQueue.Outbox.MaxAttempts,
+		},
+
+		// SQS email queue: region falls back to aws.region
+		SQS: r.AWS.SQS.toSQSConfig(r.AWS.Region, "", r.AWS.AccessKeyID, r.AWS.SecretAccessKey),
+
+		// FileSQS: region + endpoint fall back to aws.region / aws.sqs.endpoint
+		FileSQS: r.AWS.FileSQS.toSQSConfig(r.AWS.Region, r.AWS.SQS.Endpoint, r.AWS.AccessKeyID, r.AWS.SecretAccessKey),
+
+		FileStorage: FileStorageConfig{
+			Provider:              strings.ToLower(strings.TrimSpace(r.File.Provider)),
+			Bucket:                strings.TrimSpace(r.File.S3.Bucket),
+			Region:                strings.TrimSpace(r.File.S3.Region),
+			Endpoint:              strings.TrimSpace(r.File.S3.Endpoint),
+			AccessKeyID:           strings.TrimSpace(r.AWS.AccessKeyID),
+			SecretAccessKey:       strings.TrimSpace(r.AWS.SecretAccessKey),
+			ForcePathStyle:        r.File.S3.ForcePathStyle,
+			AllowInsecureEndpoint: r.File.S3.AllowInsecureEndpoint,
+			AutoCreateBucket:      r.File.S3.AutoCreateBucket,
+			ObjectKeyPrefix:       strings.TrimSpace(r.File.S3.ObjectKeyPrefix),
+			PresignPutTTL:         r.File.S3.PresignPutTTL.Duration,
+			PresignGetTTL:         r.File.S3.PresignGetTTL.Duration,
+		},
+
+		FileUpload: FileManagerUploadPolicyConfig{
+			MaxFileSizeBytes:  r.File.Upload.MaxSize,
+			AllowedMimeTypes:  normalizeMimeTypes(splitCSV(r.File.Upload.AllowedMimeTypes)),
+			AllowedExtensions: normalizeExtensions(splitCSV(r.File.Upload.AllowedExtensions)),
+			AllowEmptyFile:    r.File.Upload.AllowEmptyFile,
+			MaxFilenameLength: r.File.Upload.MaxFilenameLength,
+		},
+
+		WOPI: WOPIConfig{
+			TokenSecret:   strings.TrimSpace(r.WOPI.TokenSecret),
+			ProofSecret:   strings.TrimSpace(r.WOPI.ProofSecret),
+			DiscoveryURL:  strings.TrimSpace(r.WOPI.DiscoveryURL),
+			PublicBaseURL: strings.TrimSpace(r.WOPI.PublicBaseURL),
+			EditActionURL: strings.TrimSpace(r.WOPI.EditActionURL),
+			TokenTTL:      r.WOPI.TokenTTL.Duration,
+			MaxBodyBytes:  r.WOPI.MaxBodyBytes,
+			RequireProof:  r.WOPI.RequireProof,
+		},
+
+		Gotenberg: GotenbergConfig{
+			URL: strings.TrimSpace(r.Gotenberg.URL),
+		},
+	}
+}
+
+func splitCSV(s string) []string {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return nil
+	}
+	parts := strings.Split(s, ",")
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		if p = strings.TrimSpace(p); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
diff --git a/internal/domain/action_signoff/errors.go b/internal/domain/action_signoff/errors.go
new file mode 100644
index 0000000..6ebfddb
--- /dev/null
+++ b/internal/domain/action_signoff/errors.go
@@ -0,0 +1,5 @@
+package actionsignoff
+
+import "errors"
+
+var ErrNotFound = errors.New("action sign-off not found")
diff --git a/internal/domain/action_signoff/model.go b/internal/domain/action_signoff/model.go
new file mode 100644
index 0000000..e60a21a
--- /dev/null
+++ b/internal/domain/action_signoff/model.go
@@ -0,0 +1,49 @@
+package actionsignoff
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	flightdomain "wucher/internal/domain/flight"
+	helicopter "wucher/internal/domain/helicopter"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+// ActionSignoff is a corrective-action sign-off for a helicopter. When linked to a
+// complaint (ComplaintID set) it records that the complaint's corrective action was
+// signed off; when unlinked (ComplaintID nil) it is a complaint-independent duty
+// sign-off (gating the EASA maintenance release even without a complaint). There is
+// one row per complaint, and one current unlinked row per helicopter.
+type ActionSignoff struct {
+	ID           []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	HelicopterID []byte `gorm:"type:binary(16);not null;index;column:helicopter_id"`
+	// FlightID scopes the standalone (complaint-independent) sign-off to a flight,
+	// so it no longer leaks across takeovers of the same aircraft. Nullable; unset
+	// for complaint-linked rows (those are keyed by complaint_id).
+	FlightID []byte `gorm:"type:binary(16);index;column:flight_id"`
+	// ComplaintID unique (NULLs distinct in MySQL) → one sign-off per complaint;
+	// standalone rows (NULL) are unconstrained here and instead deduped per flight
+	// by the functional unique index uidx_action_signoffs_standalone_flight.
+	ComplaintID []byte `gorm:"type:binary(16);uniqueIndex:uidx_action_signoffs_complaint_id;column:complaint_id"`
+
+	SignedAt *time.Time `gorm:"type:datetime(3);column:signed_at"`
+	SignedBy []byte     `gorm:"type:binary(16);column:signed_by"`
+
+	Helicopter *helicopter.Helicopter `gorm:"foreignKey:HelicopterID;references:ID"`
+	Flight     *flightdomain.Flight   `gorm:"foreignKey:FlightID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+
+	CreatedAt time.Time `gorm:"type:datetime(3);column:created_at"`
+	UpdatedAt time.Time `gorm:"type:datetime(3);column:updated_at"`
+}
+
+func (ActionSignoff) TableName() string { return "action_signoffs" }
+
+func (a *ActionSignoff) BeforeCreate(_ *gorm.DB) error {
+	if len(a.ID) == 0 {
+		a.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+func (a *ActionSignoff) IsSigned() bool { return a != nil && a.SignedAt != nil }
diff --git a/internal/domain/action_signoff/repository.go b/internal/domain/action_signoff/repository.go
new file mode 100644
index 0000000..70785a6
--- /dev/null
+++ b/internal/domain/action_signoff/repository.go
@@ -0,0 +1,11 @@
+package actionsignoff
+
+import "context"
+
+type Repository interface {
+	GetByFlight(ctx context.Context, flightID []byte) (*ActionSignoff, error)
+	GetByComplaint(ctx context.Context, complaintID []byte) (*ActionSignoff, error)
+	GetByComplaintIDs(ctx context.Context, complaintIDs [][]byte) (map[string]*ActionSignoff, error)
+	Create(ctx context.Context, row *ActionSignoff) error
+	Update(ctx context.Context, row *ActionSignoff) error
+}
diff --git a/internal/domain/action_signoff/service.go b/internal/domain/action_signoff/service.go
new file mode 100644
index 0000000..ec6a442
--- /dev/null
+++ b/internal/domain/action_signoff/service.go
@@ -0,0 +1,16 @@
+package actionsignoff
+
+import "context"
+
+type Service interface {
+	GetByFlight(ctx context.Context, flightID []byte) (*ActionSignoff, error)
+	GetByComplaint(ctx context.Context, complaintID []byte) (*ActionSignoff, error)
+	GetByComplaintIDs(ctx context.Context, complaintIDs [][]byte) (map[string]*ActionSignoff, error)
+	Sign(ctx context.Context, flightID, helicopterID []byte, signer []byte) (*ActionSignoff, error)
+	SignForComplaint(ctx context.Context, complaintID, flightID, helicopterID []byte, signer []byte) (*ActionSignoff, error)
+	Unsign(ctx context.Context, flightID []byte, actor []byte) (*ActionSignoff, error)
+	// UnsignByComplaint clears the signature on a complaint-linked sign-off (no-op when
+	// there is none or it is already unsigned) — used when a closed complaint is reopened
+	// and to toggle a complaint sign-off off. Returns nil row when none exists.
+	UnsignByComplaint(ctx context.Context, complaintID []byte) (*ActionSignoff, error)
+}
diff --git a/internal/domain/after_flight_inspection/model.go b/internal/domain/after_flight_inspection/model.go
new file mode 100644
index 0000000..33d2778
--- /dev/null
+++ b/internal/domain/after_flight_inspection/model.go
@@ -0,0 +1,58 @@
+package afterflightinspection
+
+import (
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type AfterFlightInspection struct {
+	ID                        []byte  `gorm:"type:binary(16);primaryKey;column:id"`
+	FlightInspectionID        []byte  `gorm:"type:binary(16);not null;uniqueIndex;column:flight_inspection_id"`
+	OilEngineNR1Checked       *string `gorm:"type:varchar(255);null;column:oil_engine_nr1_checked"`
+	OilEngineNR2Checked       *string `gorm:"type:varchar(255);null;column:oil_engine_nr2_checked"`
+	HydraulicLHChecked        *string `gorm:"type:varchar(255);null;column:hydraulic_lh_checked"`
+	HydraulicRHChecked        *string `gorm:"type:varchar(255);null;column:hydraulic_rh_checked"`
+	OilTransmissionMGBChecked *string `gorm:"type:varchar(255);null;column:oil_transmission_mgb_checked"`
+	OilTransmissionIGBChecked *string `gorm:"type:varchar(255);null;column:oil_transmission_igb_checked"`
+	OilTransmissionTGBChecked *string `gorm:"type:varchar(255);null;column:oil_transmission_tgb_checked"`
+	Note                      *string `gorm:"type:text;column:note"`
+
+	CreatedAt time.Time `gorm:"column:created_at"`
+	CreatedBy []byte    `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time `gorm:"column:updated_at"`
+	UpdatedBy []byte    `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (AfterFlightInspection) TableName() string { return "after_flight_inspections" }
+
+func (a *AfterFlightInspection) BeforeCreate(tx *gorm.DB) error {
+	if len(a.ID) == 0 {
+		a.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+var (
+	ErrInvalidFlightInspectionID = errors.New("flight_inspection_id is invalid")
+	ErrFlightInspectionNotFound  = errors.New("flight inspection not found")
+	ErrCapabilitiesUnavailable   = errors.New("helicopter capabilities could not be resolved")
+
+	ErrNR1Required     = errors.New("oil_engine_nr1_checked is required for this helicopter")
+	ErrNR1NotAvailable = errors.New("NR1 capability not available on this helicopter")
+	ErrNR2Required     = errors.New("oil_engine_nr2_checked is required for this helicopter")
+	ErrNR2NotAvailable = errors.New("NR2 capability not available on this helicopter")
+	ErrLHRequired      = errors.New("hydraulic_lh_checked is required for this helicopter")
+	ErrLHNotAvailable  = errors.New("LH capability not available on this helicopter")
+	ErrRHRequired      = errors.New("hydraulic_rh_checked is required for this helicopter")
+	ErrRHNotAvailable  = errors.New("RH capability not available on this helicopter")
+	ErrMGBRequired     = errors.New("oil_transmission_mgb_checked is required for this helicopter")
+	ErrMGBNotAvailable = errors.New("MGB capability not available on this helicopter")
+	ErrIGBRequired     = errors.New("oil_transmission_igb_checked is required for this helicopter")
+	ErrIGBNotAvailable = errors.New("IGB capability not available on this helicopter")
+	ErrTGBRequired     = errors.New("oil_transmission_tgb_checked is required for this helicopter")
+	ErrTGBNotAvailable = errors.New("TGB capability not available on this helicopter")
+)
diff --git a/internal/domain/after_flight_inspection/repository.go b/internal/domain/after_flight_inspection/repository.go
new file mode 100644
index 0000000..2c0e40d
--- /dev/null
+++ b/internal/domain/after_flight_inspection/repository.go
@@ -0,0 +1,21 @@
+package afterflightinspection
+
+import "context"
+
+type Repository interface {
+	Upsert(ctx context.Context, row *AfterFlightInspection) error
+	GetByFlightInspectionID(ctx context.Context, flightInspectionID []byte) (*AfterFlightInspection, error)
+	DeleteByFlightInspectionID(ctx context.Context, flightInspectionID []byte) error
+	FlightInspectionExists(ctx context.Context, flightInspectionID []byte) (bool, error)
+	GetHelicopterCapabilities(ctx context.Context, flightInspectionID []byte) (*HelicopterCapabilities, error)
+}
+
+type HelicopterCapabilities struct {
+	NR1 bool
+	NR2 bool
+	LH  bool
+	RH  bool
+	MGB bool
+	IGB bool
+	TGB bool
+}
diff --git a/internal/domain/after_flight_inspection/service.go b/internal/domain/after_flight_inspection/service.go
new file mode 100644
index 0000000..4214eac
--- /dev/null
+++ b/internal/domain/after_flight_inspection/service.go
@@ -0,0 +1,20 @@
+package afterflightinspection
+
+import "context"
+
+type Service interface {
+	Upsert(ctx context.Context, flightInspectionID []byte, req *UpsertRequest) (*AfterFlightInspection, error)
+	GetByFlightInspectionID(ctx context.Context, flightInspectionID []byte) (*AfterFlightInspection, error)
+	DeleteByFlightInspectionID(ctx context.Context, flightInspectionID []byte) error
+}
+
+type UpsertRequest struct {
+	OilEngineNR1Checked       *string
+	OilEngineNR2Checked       *string
+	HydraulicLHChecked        *string
+	HydraulicRHChecked        *string
+	OilTransmissionMGBChecked *string
+	OilTransmissionIGBChecked *string
+	OilTransmissionTGBChecked *string
+	Note                      *string
+}
diff --git a/internal/domain/air_rescue_checklist/const.go b/internal/domain/air_rescue_checklist/const.go
new file mode 100644
index 0000000..3ce6035
--- /dev/null
+++ b/internal/domain/air_rescue_checklist/const.go
@@ -0,0 +1,230 @@
+package airrescuechecklist
+
+import "strings"
+
+const (
+	AirRescuerChecklistScopeCAT = "CAT"
+	AirRescuerChecklistScopeTA  = "TA"
+	AirRescuerChecklistScopeMO  = "MO"
+	AirRescuerChecklistScopeDI  = "DI"
+	AirRescuerChecklistScopeMI  = "MI"
+	AirRescuerChecklistScopeDO  = "DO"
+	AirRescuerChecklistScopeFR  = "FR"
+	AirRescuerChecklistScopeSA  = "SA"
+	AirRescuerChecklistScopeSO  = "SO"
+	AirRescuerChecklistScopeM10 = "M10"
+	AirRescuerChecklistScopeM15 = "M15"
+	AirRescuerChecklistScopeM20 = "M20"
+	AirRescuerChecklistScopeM25 = "M25"
+	AirRescuerChecklistScopeDS  = "DS"
+)
+
+const (
+	AirRescuerChecklistScopeOverview  = AirRescuerChecklistScopeCAT
+	AirRescuerChecklistScopeDaily     = AirRescuerChecklistScopeTA
+	AirRescuerChecklistScopeMonday    = AirRescuerChecklistScopeMO
+	AirRescuerChecklistScopeTuesday   = AirRescuerChecklistScopeDI
+	AirRescuerChecklistScopeWednesday = AirRescuerChecklistScopeMI
+	AirRescuerChecklistScopeThursday  = AirRescuerChecklistScopeDO
+	AirRescuerChecklistScopeFriday    = AirRescuerChecklistScopeFR
+	AirRescuerChecklistScopeSaturday  = AirRescuerChecklistScopeSA
+	AirRescuerChecklistScopeSunday    = AirRescuerChecklistScopeSO
+	AirRescuerChecklistScopeDeadline  = AirRescuerChecklistScopeDS
+)
+
+var airRescuerChecklistPersistedScopeOrder = []string{
+	AirRescuerChecklistScopeTA,
+	AirRescuerChecklistScopeMO,
+	AirRescuerChecklistScopeDI,
+	AirRescuerChecklistScopeMI,
+	AirRescuerChecklistScopeDO,
+	AirRescuerChecklistScopeFR,
+	AirRescuerChecklistScopeSA,
+	AirRescuerChecklistScopeSO,
+	AirRescuerChecklistScopeM10,
+	AirRescuerChecklistScopeM15,
+	AirRescuerChecklistScopeM20,
+	AirRescuerChecklistScopeM25,
+	AirRescuerChecklistScopeDS,
+}
+
+var airRescuerChecklistPersistedScopeSet = map[string]struct{}{
+	AirRescuerChecklistScopeTA:  {},
+	AirRescuerChecklistScopeMO:  {},
+	AirRescuerChecklistScopeDI:  {},
+	AirRescuerChecklistScopeMI:  {},
+	AirRescuerChecklistScopeDO:  {},
+	AirRescuerChecklistScopeFR:  {},
+	AirRescuerChecklistScopeSA:  {},
+	AirRescuerChecklistScopeSO:  {},
+	AirRescuerChecklistScopeM10: {},
+	AirRescuerChecklistScopeM15: {},
+	AirRescuerChecklistScopeM20: {},
+	AirRescuerChecklistScopeM25: {},
+	AirRescuerChecklistScopeDS:  {},
+}
+
+var airRescuerChecklistScopeDisplayNamesEN = map[string]string{
+	AirRescuerChecklistScopeCAT: "Category",
+	AirRescuerChecklistScopeTA:  "Daily",
+	AirRescuerChecklistScopeMO:  "Monday",
+	AirRescuerChecklistScopeDI:  "Tuesday",
+	AirRescuerChecklistScopeMI:  "Wednesday",
+	AirRescuerChecklistScopeDO:  "Thursday",
+	AirRescuerChecklistScopeFR:  "Friday",
+	AirRescuerChecklistScopeSA:  "Saturday",
+	AirRescuerChecklistScopeSO:  "Sunday",
+	AirRescuerChecklistScopeM10: "M10",
+	AirRescuerChecklistScopeM15: "M15",
+	AirRescuerChecklistScopeM20: "M20",
+	AirRescuerChecklistScopeM25: "M25",
+	AirRescuerChecklistScopeDS:  "Deadline",
+}
+
+var airRescuerChecklistScopeDisplayNamesDE = map[string]string{
+	AirRescuerChecklistScopeCAT: "Category",
+	AirRescuerChecklistScopeTA:  "Taeglich",
+	AirRescuerChecklistScopeMO:  "Montag",
+	AirRescuerChecklistScopeDI:  "Dienstag",
+	AirRescuerChecklistScopeMI:  "Mittwoch",
+	AirRescuerChecklistScopeDO:  "Donnerstag",
+	AirRescuerChecklistScopeFR:  "Freitag",
+	AirRescuerChecklistScopeSA:  "Samstag",
+	AirRescuerChecklistScopeSO:  "Sonntag",
+	AirRescuerChecklistScopeM10: "M10",
+	AirRescuerChecklistScopeM15: "M15",
+	AirRescuerChecklistScopeM20: "M20",
+	AirRescuerChecklistScopeM25: "M25",
+	AirRescuerChecklistScopeDS:  "Deadline",
+}
+
+var airRescuerChecklistScopeCodesEN = map[string]string{
+	AirRescuerChecklistScopeCAT: "CAT",
+	AirRescuerChecklistScopeTA:  "DA",
+	AirRescuerChecklistScopeMO:  "MO",
+	AirRescuerChecklistScopeDI:  "TU",
+	AirRescuerChecklistScopeMI:  "WE",
+	AirRescuerChecklistScopeDO:  "TH",
+	AirRescuerChecklistScopeFR:  "FR",
+	AirRescuerChecklistScopeSA:  "SA",
+	AirRescuerChecklistScopeSO:  "SU",
+	AirRescuerChecklistScopeM10: "M10",
+	AirRescuerChecklistScopeM15: "M15",
+	AirRescuerChecklistScopeM20: "M20",
+	AirRescuerChecklistScopeM25: "M25",
+	AirRescuerChecklistScopeDS:  "DL",
+}
+
+var airRescuerChecklistScopeAliases = map[string]string{
+	"CAT":      AirRescuerChecklistScopeCAT,
+	"OVERVIEW": AirRescuerChecklistScopeCAT,
+
+	"TA":    AirRescuerChecklistScopeTA,
+	"DA":    AirRescuerChecklistScopeTA,
+	"DAY":   AirRescuerChecklistScopeTA,
+	"DAILY": AirRescuerChecklistScopeTA,
+
+	"MO":     AirRescuerChecklistScopeMO,
+	"MON":    AirRescuerChecklistScopeMO,
+	"MONDAY": AirRescuerChecklistScopeMO,
+
+	"DI":      AirRescuerChecklistScopeDI,
+	"TU":      AirRescuerChecklistScopeDI,
+	"TUE":     AirRescuerChecklistScopeDI,
+	"TUESDAY": AirRescuerChecklistScopeDI,
+
+	"MI":        AirRescuerChecklistScopeMI,
+	"WE":        AirRescuerChecklistScopeMI,
+	"WED":       AirRescuerChecklistScopeMI,
+	"WEDNESDAY": AirRescuerChecklistScopeMI,
+
+	"DO":       AirRescuerChecklistScopeDO,
+	"TH":       AirRescuerChecklistScopeDO,
+	"THU":      AirRescuerChecklistScopeDO,
+	"THURSDAY": AirRescuerChecklistScopeDO,
+
+	"FR":     AirRescuerChecklistScopeFR,
+	"FRI":    AirRescuerChecklistScopeFR,
+	"FRIDAY": AirRescuerChecklistScopeFR,
+
+	"SA":       AirRescuerChecklistScopeSA,
+	"SAT":      AirRescuerChecklistScopeSA,
+	"SATURDAY": AirRescuerChecklistScopeSA,
+
+	"SO":     AirRescuerChecklistScopeSO,
+	"SU":     AirRescuerChecklistScopeSO,
+	"SUN":    AirRescuerChecklistScopeSO,
+	"SUNDAY": AirRescuerChecklistScopeSO,
+
+	"M10": AirRescuerChecklistScopeM10,
+	"M15": AirRescuerChecklistScopeM15,
+	"M20": AirRescuerChecklistScopeM20,
+	"M25": AirRescuerChecklistScopeM25,
+
+	"DS":       AirRescuerChecklistScopeDS,
+	"DL":       AirRescuerChecklistScopeDS,
+	"DEADLINE": AirRescuerChecklistScopeDS,
+}
+
+func CanonicalizeAirRescuerChecklistScope(scopeCode string) string {
+	return normalizeAirRescuerChecklistScope(scopeCode)
+}
+
+func IsAirRescuerChecklistPersistedScope(scopeCode string) bool {
+	_, ok := airRescuerChecklistPersistedScopeSet[normalizeAirRescuerChecklistScope(scopeCode)]
+	return ok
+}
+
+func IsAirRescuerChecklistQueryScope(scopeCode string) bool {
+	normalized := normalizeAirRescuerChecklistScope(scopeCode)
+	if normalized == AirRescuerChecklistScopeCAT {
+		return true
+	}
+	return IsAirRescuerChecklistPersistedScope(normalized)
+}
+
+func AirRescuerChecklistScopeDisplayName(scopeCode string) string {
+	normalized := normalizeAirRescuerChecklistScope(scopeCode)
+	if v, ok := airRescuerChecklistScopeDisplayNamesEN[normalized]; ok {
+		return v
+	}
+	return normalized
+}
+
+func AirRescuerChecklistScopeDisplayNameDE(scopeCode string) string {
+	normalized := normalizeAirRescuerChecklistScope(scopeCode)
+	if v, ok := airRescuerChecklistScopeDisplayNamesDE[normalized]; ok {
+		return v
+	}
+	return normalized
+}
+
+func AirRescuerChecklistScopeCodeEN(scopeCode string) string {
+	normalized := normalizeAirRescuerChecklistScope(scopeCode)
+	if v, ok := airRescuerChecklistScopeCodesEN[normalized]; ok {
+		return v
+	}
+	return normalized
+}
+
+func AirRescuerChecklistScopeCodeDE(scopeCode string) string {
+	return normalizeAirRescuerChecklistScope(scopeCode)
+}
+
+func AirRescuerChecklistPersistedScopeOrder() []string {
+	out := make([]string, 0, len(airRescuerChecklistPersistedScopeOrder))
+	out = append(out, airRescuerChecklistPersistedScopeOrder...)
+	return out
+}
+
+func IsAirRescuerChecklistScope(scopeCode string) bool {
+	return IsAirRescuerChecklistPersistedScope(scopeCode)
+}
+
+func normalizeAirRescuerChecklistScope(scopeCode string) string {
+	normalized := strings.ToUpper(strings.TrimSpace(scopeCode))
+	if canonical, ok := airRescuerChecklistScopeAliases[normalized]; ok {
+		return canonical
+	}
+	return normalized
+}
diff --git a/internal/domain/air_rescue_checklist/const_test.go b/internal/domain/air_rescue_checklist/const_test.go
new file mode 100644
index 0000000..fa7c15b
--- /dev/null
+++ b/internal/domain/air_rescue_checklist/const_test.go
@@ -0,0 +1,159 @@
+package airrescuechecklist
+
+import "testing"
+
+func TestAirRescuerChecklistScopeHelpers(t *testing.T) {
+	persistedScopes := []string{
+		AirRescuerChecklistScopeTA,
+		AirRescuerChecklistScopeMO,
+		AirRescuerChecklistScopeDI,
+		AirRescuerChecklistScopeMI,
+		AirRescuerChecklistScopeDO,
+		AirRescuerChecklistScopeFR,
+		AirRescuerChecklistScopeSA,
+		AirRescuerChecklistScopeSO,
+		AirRescuerChecklistScopeM10,
+		AirRescuerChecklistScopeM15,
+		AirRescuerChecklistScopeM20,
+		AirRescuerChecklistScopeM25,
+		AirRescuerChecklistScopeDS,
+	}
+
+	for _, scope := range persistedScopes {
+		if !IsAirRescuerChecklistPersistedScope(scope) {
+			t.Fatalf("expected persisted scope valid: %s", scope)
+		}
+		if !IsAirRescuerChecklistPersistedScope(" " + scope + " ") {
+			t.Fatalf("expected persisted scope valid with trim: %s", scope)
+		}
+		if !IsAirRescuerChecklistPersistedScope(lower(scope)) {
+			t.Fatalf("expected persisted scope valid with lowercase: %s", scope)
+		}
+		if !IsAirRescuerChecklistQueryScope(scope) {
+			t.Fatalf("expected query scope valid: %s", scope)
+		}
+		if !IsAirRescuerChecklistScope(scope) {
+			t.Fatalf("expected compatibility scope valid: %s", scope)
+		}
+	}
+
+	if IsAirRescuerChecklistPersistedScope(AirRescuerChecklistScopeCAT) {
+		t.Fatalf("expected CAT not persisted")
+	}
+	if !IsAirRescuerChecklistQueryScope(AirRescuerChecklistScopeCAT) {
+		t.Fatalf("expected CAT valid for query")
+	}
+	if IsAirRescuerChecklistQueryScope("UNKNOWN") {
+		t.Fatalf("expected unknown query scope invalid")
+	}
+	if IsAirRescuerChecklistScope("UNKNOWN") {
+		t.Fatalf("expected unknown compatibility scope invalid")
+	}
+
+	englishAliases := map[string]string{
+		"daily":     AirRescuerChecklistScopeTA,
+		"tuesday":   AirRescuerChecklistScopeDI,
+		"wednesday": AirRescuerChecklistScopeMI,
+		"thursday":  AirRescuerChecklistScopeDO,
+		"sunday":    AirRescuerChecklistScopeSO,
+		"deadline":  AirRescuerChecklistScopeDS,
+		"overview":  AirRescuerChecklistScopeCAT,
+		"tu":        AirRescuerChecklistScopeDI,
+		"we":        AirRescuerChecklistScopeMI,
+		"th":        AirRescuerChecklistScopeDO,
+		"su":        AirRescuerChecklistScopeSO,
+	}
+
+	for alias, expected := range englishAliases {
+		if got := CanonicalizeAirRescuerChecklistScope(alias); got != expected {
+			t.Fatalf("expected alias %s canonicalized to %s, got %s", alias, expected, got)
+		}
+	}
+
+	if !IsAirRescuerChecklistPersistedScope("tu") {
+		t.Fatalf("expected TU alias valid as persisted scope")
+	}
+	if !IsAirRescuerChecklistQueryScope("overview") {
+		t.Fatalf("expected OVERVIEW alias valid as query scope")
+	}
+}
+
+func TestAirRescuerChecklistScopeDisplayName(t *testing.T) {
+	if got := AirRescuerChecklistScopeDisplayName(AirRescuerChecklistScopeCAT); got != "Category" {
+		t.Fatalf("unexpected CAT display name: %s", got)
+	}
+	if got := AirRescuerChecklistScopeDisplayName(" mo "); got != "Monday" {
+		t.Fatalf("unexpected MO display name: %s", got)
+	}
+	if got := AirRescuerChecklistScopeDisplayName("x"); got != "X" {
+		t.Fatalf("unexpected fallback display name: %s", got)
+	}
+	if got := AirRescuerChecklistScopeDisplayName("tu"); got != "Tuesday" {
+		t.Fatalf("unexpected TU display name: %s", got)
+	}
+}
+
+func TestAirRescuerChecklistScopeDisplayNameDE(t *testing.T) {
+	if got := AirRescuerChecklistScopeDisplayNameDE(AirRescuerChecklistScopeCAT); got != "Category" {
+		t.Fatalf("unexpected CAT DE display name: %s", got)
+	}
+	if got := AirRescuerChecklistScopeDisplayNameDE(" mo "); got != "Montag" {
+		t.Fatalf("unexpected MO DE display name: %s", got)
+	}
+	if got := AirRescuerChecklistScopeDisplayNameDE("x"); got != "X" {
+		t.Fatalf("unexpected DE fallback display name: %s", got)
+	}
+	if got := AirRescuerChecklistScopeDisplayNameDE("thursday"); got != "Donnerstag" {
+		t.Fatalf("unexpected THURSDAY DE display name: %s", got)
+	}
+	if got := AirRescuerChecklistScopeDisplayNameDE(AirRescuerChecklistScopeDS); got != "Deadline" {
+		t.Fatalf("unexpected DS DE display name: %s", got)
+	}
+}
+
+func TestAirRescuerChecklistScopeCodes(t *testing.T) {
+	if got := AirRescuerChecklistScopeCodeEN(AirRescuerChecklistScopeTA); got != "DA" {
+		t.Fatalf("unexpected TA EN code: %s", got)
+	}
+	if got := AirRescuerChecklistScopeCodeEN("thursday"); got != "TH" {
+		t.Fatalf("unexpected THURSDAY EN code: %s", got)
+	}
+	if got := AirRescuerChecklistScopeCodeEN("x"); got != "X" {
+		t.Fatalf("unexpected EN fallback code: %s", got)
+	}
+
+	if got := AirRescuerChecklistScopeCodeDE(AirRescuerChecklistScopeDI); got != AirRescuerChecklistScopeDI {
+		t.Fatalf("unexpected DI DE code: %s", got)
+	}
+	if got := AirRescuerChecklistScopeCodeDE("tu"); got != AirRescuerChecklistScopeDI {
+		t.Fatalf("unexpected TU DE code: %s", got)
+	}
+}
+
+func TestAirRescuerChecklistPersistedScopeOrderReturnsCopy(t *testing.T) {
+	first := AirRescuerChecklistPersistedScopeOrder()
+	if len(first) != 13 {
+		t.Fatalf("unexpected persisted scope order size: %d", len(first))
+	}
+	if first[0] != AirRescuerChecklistScopeTA || first[len(first)-1] != AirRescuerChecklistScopeDS {
+		t.Fatalf("unexpected persisted scope order: %+v", first)
+	}
+
+	first[0] = "BROKEN"
+	second := AirRescuerChecklistPersistedScopeOrder()
+	if second[0] != AirRescuerChecklistScopeTA {
+		t.Fatalf("expected second call to return independent copy, got: %s", second[0])
+	}
+}
+
+func lower(s string) string {
+	out := make([]byte, 0, len(s))
+	for i := 0; i < len(s); i++ {
+		ch := s[i]
+		if ch >= 'A' && ch <= 'Z' {
+			ch = ch + ('a' - 'A')
+		}
+		out = append(out, ch)
+	}
+	return string(out)
+}
diff --git a/internal/domain/air_rescue_checklist/model.go b/internal/domain/air_rescue_checklist/model.go
new file mode 100644
index 0000000..6a4f22a
--- /dev/null
+++ b/internal/domain/air_rescue_checklist/model.go
@@ -0,0 +1,117 @@
+package airrescuechecklist
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type AirRescuerChecklist struct {
+	ID         []byte `gorm:"column:id;type:binary(16);primaryKey"`
+	HEMSBaseID []byte `gorm:"column:hems_base_id;type:binary(16);not null"`
+	ScopeCode  string `gorm:"column:scope_code;type:varchar(20);not null"`
+	Title      string `gorm:"column:title;type:varchar(150);not null"`
+	Position   int    `gorm:"column:position;not null;default:1"`
+
+	CreatedAt time.Time  `gorm:"column:created_at;autoCreateTime"`
+	CreatedBy []byte     `gorm:"column:created_by;type:binary(16)"`
+	UpdatedAt time.Time  `gorm:"column:updated_at;autoUpdateTime"`
+	UpdatedBy []byte     `gorm:"column:updated_by;type:binary(16)"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"column:deleted_by;type:binary(16)"`
+}
+
+func (AirRescuerChecklist) TableName() string {
+	return "air_rescuer_checklists"
+}
+
+func (h *AirRescuerChecklist) BeforeCreate(tx *gorm.DB) error {
+	if len(h.ID) == 0 {
+		h.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type AirRescuerChecklistItem struct {
+	ID          []byte `gorm:"column:id;type:binary(16);primaryKey"`
+	ChecklistID []byte `gorm:"column:checklist_id;type:binary(16);not null"`
+	Name        string `gorm:"column:name;type:varchar(255);not null"`
+	Position    int    `gorm:"column:position;not null;default:1"`
+
+	CreatedAt time.Time  `gorm:"column:created_at;autoCreateTime"`
+	CreatedBy []byte     `gorm:"column:created_by;type:binary(16)"`
+	UpdatedAt time.Time  `gorm:"column:updated_at;autoUpdateTime"`
+	UpdatedBy []byte     `gorm:"column:updated_by;type:binary(16)"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"column:deleted_by;type:binary(16)"`
+}
+
+func (AirRescuerChecklistItem) TableName() string {
+	return "air_rescuer_checklist_items"
+}
+
+func (h *AirRescuerChecklistItem) BeforeCreate(tx *gorm.DB) error {
+	if len(h.ID) == 0 {
+		h.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type HEMSBaseView struct {
+	ID               []byte
+	BaseName         string
+	BaseAbbreviation string
+	BaseCategory     string
+	Position         int
+}
+
+type ChecklistHeaderView struct {
+	ID               []byte
+	HEMSBaseID       []byte
+	BaseName         string
+	BaseAbbreviation string
+	BaseCategory     string
+	ScopeCode        string
+	Title            string
+	Position         int
+	CreatedAt        time.Time
+	CreatedBy        []byte
+	UpdatedAt        time.Time
+}
+
+type ChecklistItemView struct {
+	ID          []byte
+	ChecklistID []byte
+	Name        string
+	Position    int
+	CreatedAt   time.Time
+	CreatedBy   []byte
+	UpdatedAt   time.Time
+}
+
+type ChecklistHeaderFilter struct {
+	HEMSBaseID       []byte
+	BaseName         string
+	BaseAbbreviation string
+	ScopeCode        string
+	CategoryType     string
+}
+
+type HEMSBaseFilter struct {
+	HEMSBaseID       []byte
+	BaseName         string
+	BaseAbbreviation string
+	CategoryType     string
+}
+
+type ChecklistCreateInput struct {
+	Checklist AirRescuerChecklist
+	Items     []AirRescuerChecklistItem
+}
+
+type ChecklistItemReorderInput struct {
+	ID       []byte
+	Position int
+}
diff --git a/internal/domain/air_rescue_checklist/model_test.go b/internal/domain/air_rescue_checklist/model_test.go
new file mode 100644
index 0000000..bf87106
--- /dev/null
+++ b/internal/domain/air_rescue_checklist/model_test.go
@@ -0,0 +1,52 @@
+package airrescuechecklist
+
+import (
+	"bytes"
+	"testing"
+)
+
+func TestAirRescuerChecklistModelTableNameAndBeforeCreate(t *testing.T) {
+	var header AirRescuerChecklist
+	if got := header.TableName(); got != "air_rescuer_checklists" {
+		t.Fatalf("unexpected checklist table name: %s", got)
+	}
+
+	if err := header.BeforeCreate(nil); err != nil {
+		t.Fatalf("BeforeCreate checklist: %v", err)
+	}
+	if len(header.ID) == 0 {
+		t.Fatalf("expected checklist id generated")
+	}
+
+	existingID := []byte("1234567890123456")
+	header2 := AirRescuerChecklist{ID: append([]byte(nil), existingID...)}
+	if err := header2.BeforeCreate(nil); err != nil {
+		t.Fatalf("BeforeCreate checklist with existing id: %v", err)
+	}
+	if !bytes.Equal(header2.ID, existingID) {
+		t.Fatalf("expected existing checklist id preserved")
+	}
+}
+
+func TestAirRescuerChecklistItemModelTableNameAndBeforeCreate(t *testing.T) {
+	var item AirRescuerChecklistItem
+	if got := item.TableName(); got != "air_rescuer_checklist_items" {
+		t.Fatalf("unexpected checklist item table name: %s", got)
+	}
+
+	if err := item.BeforeCreate(nil); err != nil {
+		t.Fatalf("BeforeCreate checklist item: %v", err)
+	}
+	if len(item.ID) == 0 {
+		t.Fatalf("expected checklist item id generated")
+	}
+
+	existingID := []byte("abcdefghijklmnop")
+	item2 := AirRescuerChecklistItem{ID: append([]byte(nil), existingID...)}
+	if err := item2.BeforeCreate(nil); err != nil {
+		t.Fatalf("BeforeCreate checklist item with existing id: %v", err)
+	}
+	if !bytes.Equal(item2.ID, existingID) {
+		t.Fatalf("expected existing checklist item id preserved")
+	}
+}
diff --git a/internal/domain/air_rescue_checklist/repository.go b/internal/domain/air_rescue_checklist/repository.go
new file mode 100644
index 0000000..ae2dfa5
--- /dev/null
+++ b/internal/domain/air_rescue_checklist/repository.go
@@ -0,0 +1,28 @@
+package airrescuechecklist
+
+import "context"
+
+type TxRepository interface {
+	CreateChecklist(ctx context.Context, row *AirRescuerChecklist) error
+	NextChecklistPosition(ctx context.Context, hemsBaseID []byte, scopeCode string) (int, error)
+	LockChecklistByID(ctx context.Context, id []byte) (*AirRescuerChecklist, error)
+	UpdateChecklist(ctx context.Context, row *AirRescuerChecklist) error
+	SoftDeleteChecklist(ctx context.Context, id []byte, deletedBy []byte) error
+	SoftDeleteItemsByChecklistID(ctx context.Context, checklistID []byte, deletedBy []byte) error
+
+	CreateChecklistItem(ctx context.Context, row *AirRescuerChecklistItem) error
+	CreateChecklistItems(ctx context.Context, rows []AirRescuerChecklistItem) error
+	NextChecklistItemPosition(ctx context.Context, checklistID []byte) (int, error)
+	LockChecklistItemByID(ctx context.Context, id []byte) (*AirRescuerChecklistItem, error)
+	UpdateChecklistItem(ctx context.Context, row *AirRescuerChecklistItem) error
+	SoftDeleteChecklistItem(ctx context.Context, id []byte, deletedBy []byte) error
+}
+
+type Repository interface {
+	InTx(ctx context.Context, fn func(txRepo TxRepository) error) error
+	GetChecklistByID(ctx context.Context, id []byte) (*ChecklistHeaderView, error)
+	GetChecklistItemByID(ctx context.Context, id []byte) (*ChecklistItemView, error)
+	ListChecklistHeaders(ctx context.Context, filter ChecklistHeaderFilter) ([]ChecklistHeaderView, error)
+	ListChecklistItemsByChecklistIDs(ctx context.Context, checklistIDs [][]byte) ([]ChecklistItemView, error)
+	ListHEMSBases(ctx context.Context, filter HEMSBaseFilter) ([]HEMSBaseView, error)
+}
diff --git a/internal/domain/air_rescue_checklist/service.go b/internal/domain/air_rescue_checklist/service.go
new file mode 100644
index 0000000..3be9ed9
--- /dev/null
+++ b/internal/domain/air_rescue_checklist/service.go
@@ -0,0 +1,21 @@
+package airrescuechecklist
+
+import "context"
+
+type Service interface {
+	CreateBulk(ctx context.Context, rows []ChecklistCreateInput) error
+	UpdateChecklist(ctx context.Context, row *AirRescuerChecklist) error
+	UpdateChecklistWithNewItems(ctx context.Context, row *AirRescuerChecklist, newItems []AirRescuerChecklistItem) error
+	DeleteChecklist(ctx context.Context, id []byte, deletedBy []byte) error
+	CreateChecklistItem(ctx context.Context, row *AirRescuerChecklistItem) error
+	CreateChecklistItems(ctx context.Context, checklistID []byte, rows []AirRescuerChecklistItem) error
+	ReorderChecklistItems(ctx context.Context, checklistID []byte, rows []ChecklistItemReorderInput, updatedBy []byte) error
+	UpdateChecklistItem(ctx context.Context, row *AirRescuerChecklistItem) error
+	DeleteChecklistItem(ctx context.Context, id []byte, deletedBy []byte) error
+
+	GetChecklistByID(ctx context.Context, id []byte) (*ChecklistHeaderView, error)
+	GetChecklistItemByID(ctx context.Context, id []byte) (*ChecklistItemView, error)
+	ListChecklistHeaders(ctx context.Context, filter ChecklistHeaderFilter) ([]ChecklistHeaderView, error)
+	ListChecklistItemsByChecklistIDs(ctx context.Context, checklistIDs [][]byte) ([]ChecklistItemView, error)
+	ListHEMSBases(ctx context.Context, filter HEMSBaseFilter) ([]HEMSBaseView, error)
+}
diff --git a/internal/domain/audit/model.go b/internal/domain/audit/model.go
new file mode 100644
index 0000000..eaff8b8
--- /dev/null
+++ b/internal/domain/audit/model.go
@@ -0,0 +1,36 @@
+package audit
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type AuditLog struct {
+	ID          []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	RequestID   string `gorm:"type:varchar(64);index;column:request_id"`
+	ActorUserID []byte `gorm:"type:binary(16);index;column:actor_user_id"`
+	Layer       string `gorm:"type:varchar(32);index;not null;column:layer"`
+	Module      string `gorm:"type:varchar(64);index;column:module"`
+	Action      string `gorm:"type:varchar(128);index;not null;column:action"`
+	Method      string `gorm:"type:varchar(12);index;column:method"`
+	Path        string `gorm:"type:varchar(255);index;column:path"`
+	StatusCode  int    `gorm:"index;column:status_code"`
+	Success     bool   `gorm:"type:tinyint(1);index;not null;default:0;column:success"`
+	IP          string `gorm:"type:varchar(128);column:ip"`
+	UserAgent   string `gorm:"type:varchar(255);column:user_agent"`
+	Message     string `gorm:"type:varchar(512);column:message"`
+	Metadata    []byte `gorm:"type:json;column:metadata"`
+	CreatedAt   time.Time
+}
+
+func (AuditLog) TableName() string { return "audit_logs" }
+
+func (a *AuditLog) BeforeCreate(tx *gorm.DB) error {
+	if len(a.ID) == 0 {
+		a.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/audit/repository.go b/internal/domain/audit/repository.go
new file mode 100644
index 0000000..f9832de
--- /dev/null
+++ b/internal/domain/audit/repository.go
@@ -0,0 +1,7 @@
+package audit
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, entry *AuditLog) error
+}
diff --git a/internal/domain/auth/contact_constants.go b/internal/domain/auth/contact_constants.go
new file mode 100644
index 0000000..c90cf42
--- /dev/null
+++ b/internal/domain/auth/contact_constants.go
@@ -0,0 +1,16 @@
+package auth
+
+const (
+	RoleCodePilot           = "pilot"
+	RoleCodeDoctor          = "doctor"
+	RoleCodeAirRescuer      = "air_rescuer"
+	RoleCodeTechnician      = "technician"
+	RoleCodeFlightAssistant = "flight_assistant"
+	RoleCodeStaff           = "staff"
+)
+
+const (
+	PilotCategoryRegular   = "regular"
+	PilotCategoryFreelance = "freelance"
+	PilotCategoryDryLease  = "dry_lease"
+)
diff --git a/internal/domain/auth/contact_profiles.go b/internal/domain/auth/contact_profiles.go
new file mode 100644
index 0000000..d7b4bb6
--- /dev/null
+++ b/internal/domain/auth/contact_profiles.go
@@ -0,0 +1,141 @@
+package auth
+
+import "time"
+
+// PilotProfile stores role-specific data for role=pilot.
+type PilotProfile struct {
+	UserID                  []byte     `gorm:"type:binary(16);primaryKey;column:user_id"`
+	PilotCategory           string     `gorm:"type:varchar(16);not null;index;column:pilot_category"`
+	ShortName               string     `gorm:"type:varchar(120);column:short_name"`
+	LicenseNo               string     `gorm:"type:varchar(120);index;column:license_no"`
+	LicenseIssuedAt         *time.Time `gorm:"column:license_issued_at"`
+	LicenseExpiredAt        *time.Time `gorm:"column:license_expired_at"`
+	TechnicianLicenseNo     string     `gorm:"type:varchar(120);column:technician_license_no"`
+	HasIFRQualification     bool       `gorm:"not null;default:false;column:has_ifr_qualification"`
+	IsChiefPilot            bool       `gorm:"not null;default:false;column:is_chief_pilot"`
+	IsDUL                   bool       `gorm:"not null;default:false;column:is_dul"`
+	TotalFlightMinutes      int        `gorm:"not null;default:0;column:total_flight_minutes"`
+	ResponsiblePilotMinutes int        `gorm:"not null;default:0;column:responsible_pilot_minutes"`
+	SecondPilotMinutes      int        `gorm:"not null;default:0;column:second_pilot_minutes"`
+	DoubleCommandMinutes    int        `gorm:"not null;default:0;column:double_command_minutes"`
+	FlightInstructorMinutes int        `gorm:"not null;default:0;column:flight_instructor_minutes"`
+	NightFlightMinutes      int        `gorm:"not null;default:0;column:night_flight_minutes"`
+	IFRFlightMinutes        int        `gorm:"not null;default:0;column:ifr_flight_minutes"`
+	Location                string     `gorm:"type:varchar(255);column:location"`
+	Postcode                string     `gorm:"type:varchar(32);column:postcode"`
+	StreetLine              string     `gorm:"type:varchar(255);column:street_line"`
+	Note                    string     `gorm:"type:text;column:note"`
+	WeightKG                *float64   `gorm:"type:decimal(8,2);column:weight_kg"`
+	PhotoFileID             string     `gorm:"type:varchar(255);column:photo_file_id"`
+	CreatedAt               time.Time
+	CreatedBy               []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt               time.Time
+	UpdatedBy               []byte `gorm:"type:binary(16);column:updated_by"`
+
+	User User `gorm:"foreignKey:UserID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (PilotProfile) TableName() string { return "pilot_profiles" }
+
+// DoctorProfile stores role-specific data for role=doctor.
+type DoctorProfile struct {
+	UserID            []byte `gorm:"type:binary(16);primaryKey;column:user_id"`
+	ShortName         string `gorm:"type:varchar(120);column:short_name"`
+	Specialization    string `gorm:"type:varchar(120);column:specialization"`
+	SubSpecialization string `gorm:"type:varchar(120);column:sub_specialization"`
+	IsChiefPhysician  bool   `gorm:"not null;default:false;column:is_chief_physician"`
+	Location          string `gorm:"type:varchar(255);column:location"`
+	Postcode          string `gorm:"type:varchar(32);column:postcode"`
+	StreetLine        string `gorm:"type:varchar(255);column:street_line"`
+	Note              string `gorm:"type:text;column:note"`
+	PhotoFileID       string `gorm:"type:varchar(255);column:photo_file_id"`
+	CreatedAt         time.Time
+	CreatedBy         []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt         time.Time
+	UpdatedBy         []byte `gorm:"type:binary(16);column:updated_by"`
+
+	User User `gorm:"foreignKey:UserID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (DoctorProfile) TableName() string { return "doctor_profiles" }
+
+// AirRescuerProfile stores role-specific data for role=air_rescuer.
+type AirRescuerProfile struct {
+	UserID                   []byte `gorm:"type:binary(16);primaryKey;column:user_id"`
+	ShortName                string `gorm:"type:varchar(120);column:short_name"`
+	ResponsibleFlightRescuer bool   `gorm:"not null;default:false;column:responsible_flight_rescuer"`
+	Location                 string `gorm:"type:varchar(255);column:location"`
+	Postcode                 string `gorm:"type:varchar(32);column:postcode"`
+	StreetLine               string `gorm:"type:varchar(255);column:street_line"`
+	Note                     string `gorm:"type:text;column:note"`
+	PhotoFileID              string `gorm:"type:varchar(255);column:photo_file_id"`
+	CreatedAt                time.Time
+	CreatedBy                []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt                time.Time
+	UpdatedBy                []byte `gorm:"type:binary(16);column:updated_by"`
+
+	User User `gorm:"foreignKey:UserID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (AirRescuerProfile) TableName() string { return "air_rescuer_profiles" }
+
+// TechnicianProfile stores role-specific data for role=technician.
+type TechnicianProfile struct {
+	UserID                  []byte `gorm:"type:binary(16);primaryKey;column:user_id"`
+	ShortName               string `gorm:"type:varchar(120);column:short_name"`
+	LicenseNo               string `gorm:"type:varchar(120);index;column:license_no"`
+	IsChiefTechnician       bool   `gorm:"not null;default:false;column:is_chief_technician"`
+	IsResponsibleComplaints bool   `gorm:"not null;default:false;column:is_responsible_complaints"`
+	Location                string `gorm:"type:varchar(255);column:location"`
+	Postcode                string `gorm:"type:varchar(32);column:postcode"`
+	StreetLine              string `gorm:"type:varchar(255);column:street_line"`
+	Note                    string `gorm:"type:text;column:note"`
+	PhotoFileID             string `gorm:"type:varchar(255);column:photo_file_id"`
+	CreatedAt               time.Time
+	CreatedBy               []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt               time.Time
+	UpdatedBy               []byte `gorm:"type:binary(16);column:updated_by"`
+
+	User User `gorm:"foreignKey:UserID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (TechnicianProfile) TableName() string { return "technician_profiles" }
+
+// FlightAssistantProfile stores role-specific data for role=flight_assistant.
+type FlightAssistantProfile struct {
+	UserID      []byte `gorm:"type:binary(16);primaryKey;column:user_id"`
+	ShortName   string `gorm:"type:varchar(120);column:short_name"`
+	Location    string `gorm:"type:varchar(255);column:location"`
+	Postcode    string `gorm:"type:varchar(32);column:postcode"`
+	StreetLine  string `gorm:"type:varchar(255);column:street_line"`
+	Note        string `gorm:"type:text;column:note"`
+	PhotoFileID string `gorm:"type:varchar(255);column:photo_file_id"`
+	CreatedAt   time.Time
+	CreatedBy   []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt   time.Time
+	UpdatedBy   []byte `gorm:"type:binary(16);column:updated_by"`
+
+	User User `gorm:"foreignKey:UserID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (FlightAssistantProfile) TableName() string { return "flight_assistant_profiles" }
+
+// StaffProfile stores role-specific data for role=staff.
+type StaffProfile struct {
+	UserID      []byte `gorm:"type:binary(16);primaryKey;column:user_id"`
+	ShortName   string `gorm:"type:varchar(120);column:short_name"`
+	RoleLabel   string `gorm:"type:varchar(120);column:role_label"`
+	Location    string `gorm:"type:varchar(255);column:location"`
+	Postcode    string `gorm:"type:varchar(32);column:postcode"`
+	StreetLine  string `gorm:"type:varchar(255);column:street_line"`
+	Note        string `gorm:"type:text;column:note"`
+	PhotoFileID string `gorm:"type:varchar(255);column:photo_file_id"`
+	CreatedAt   time.Time
+	CreatedBy   []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt   time.Time
+	UpdatedBy   []byte `gorm:"type:binary(16);column:updated_by"`
+
+	User User `gorm:"foreignKey:UserID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (StaffProfile) TableName() string { return "staff_profiles" }
diff --git a/internal/domain/auth/email_login_otp.go b/internal/domain/auth/email_login_otp.go
new file mode 100644
index 0000000..b79340a
--- /dev/null
+++ b/internal/domain/auth/email_login_otp.go
@@ -0,0 +1,34 @@
+package auth
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type UserEmailLoginOTP struct {
+	ID           []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	UserID       []byte     `gorm:"type:binary(16);index;not null;column:user_id"`
+	OTPHash      []byte     `gorm:"type:binary(32);not null;column:otp_hash"`
+	ExpiresAt    time.Time  `gorm:"index;not null;column:expires_at"`
+	UsedAt       *time.Time `gorm:"index;column:used_at"`
+	AttemptCount int        `gorm:"not null;default:0;column:attempt_count"`
+	MaxAttempts  int        `gorm:"not null;default:5;column:max_attempts"`
+	ResendCount  int        `gorm:"not null;default:1;column:resend_count"`
+	LastSentAt   time.Time  `gorm:"index;not null;column:last_sent_at"`
+	CreatedAt    time.Time
+	CreatedBy    []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt    time.Time
+	UpdatedBy    []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (UserEmailLoginOTP) TableName() string { return "user_email_login_otps" }
+
+func (o *UserEmailLoginOTP) BeforeCreate(_ *gorm.DB) error {
+	if len(o.ID) == 0 {
+		o.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/auth/email_outbox.go b/internal/domain/auth/email_outbox.go
new file mode 100644
index 0000000..a433f4d
--- /dev/null
+++ b/internal/domain/auth/email_outbox.go
@@ -0,0 +1,143 @@
+package auth
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/queue"
+)
+
+const (
+	EmailOutboxStatusPending    = "pending"
+	EmailOutboxStatusProcessing = "processing"
+	EmailOutboxStatusPublished  = "published"
+	EmailOutboxStatusDead       = "dead"
+)
+
+type EmailOutboxMessage struct {
+	ID              []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	MessageID       string     `gorm:"type:varchar(64);uniqueIndex;not null;column:message_id"`
+	Kind            string     `gorm:"type:varchar(64);index;not null;column:kind"`
+	JobType         string     `gorm:"type:varchar(64);index;not null;column:job_type"`
+	Body            []byte     `gorm:"type:longblob;not null;column:body"`
+	Attributes      []byte     `gorm:"type:longblob;column:attributes"`
+	MessageGroupID  string     `gorm:"type:varchar(128);column:message_group_id"`
+	DeduplicationID string     `gorm:"type:varchar(128);column:deduplication_id"`
+	Status          string     `gorm:"type:varchar(32);index;not null;column:status"`
+	Attempts        int        `gorm:"not null;default:0;column:attempts"`
+	AvailableAt     time.Time  `gorm:"index;not null;column:available_at"`
+	LockedAt        *time.Time `gorm:"index;column:locked_at"`
+	LockedBy        string     `gorm:"type:varchar(64);column:locked_by"`
+	PublishedAt     *time.Time `gorm:"column:published_at"`
+	LastError       string     `gorm:"type:text;column:last_error"`
+	CorrelationID   string     `gorm:"type:varchar(64);index;column:correlation_id"`
+	TraceID         string     `gorm:"type:varchar(64);index;column:trace_id"`
+	CreatedAt       time.Time
+	UpdatedAt       time.Time
+}
+
+func (EmailOutboxMessage) TableName() string { return "email_outbox_messages" }
+
+func (m *EmailOutboxMessage) BeforeCreate(_ *gorm.DB) error {
+	if len(m.ID) == 0 {
+		m.ID = uuidv7.MustBytes()
+	}
+	if strings.TrimSpace(m.Status) == "" {
+		m.Status = EmailOutboxStatusPending
+	}
+	if m.AvailableAt.IsZero() {
+		m.AvailableAt = time.Now().UTC()
+	}
+	return nil
+}
+
+func NewEmailOutboxMessage(now time.Time, message *queue.OutboundMessage) (*EmailOutboxMessage, error) {
+	if message == nil {
+		return nil, errors.New("outbound message is required")
+	}
+	if strings.TrimSpace(message.ID) == "" {
+		return nil, errors.New("outbound message id is required")
+	}
+	if len(message.Body) == 0 {
+		return nil, errors.New("outbound message body is required")
+	}
+
+	attributes, err := json.Marshal(message.Attributes)
+	if err != nil {
+		return nil, err
+	}
+	if now.IsZero() {
+		now = time.Now().UTC()
+	}
+
+	kind := strings.TrimSpace(message.Attributes["message_kind"])
+	if kind == "" {
+		kind = queue.EmailKind
+	}
+	jobType := strings.TrimSpace(message.Attributes["job_type"])
+	if jobType == "" {
+		jobType = "generic"
+	}
+
+	return &EmailOutboxMessage{
+		MessageID:       strings.TrimSpace(message.ID),
+		Kind:            kind,
+		JobType:         jobType,
+		Body:            append([]byte(nil), message.Body...),
+		Attributes:      append([]byte(nil), attributes...),
+		MessageGroupID:  strings.TrimSpace(message.MessageGroupID),
+		DeduplicationID: strings.TrimSpace(message.DeduplicationID),
+		Status:          EmailOutboxStatusPending,
+		AvailableAt:     now.UTC(),
+		CorrelationID:   strings.TrimSpace(message.Attributes["correlation_id"]),
+		TraceID:         strings.TrimSpace(message.Attributes["trace_id"]),
+	}, nil
+}
+
+func (m *EmailOutboxMessage) OutboundMessage() (*queue.OutboundMessage, error) {
+	if m == nil {
+		return nil, errors.New("email outbox message is required")
+	}
+	attributes := map[string]string{}
+	if len(m.Attributes) > 0 {
+		if err := json.Unmarshal(m.Attributes, &attributes); err != nil {
+			return nil, err
+		}
+	}
+	if strings.TrimSpace(m.MessageID) == "" {
+		return nil, errors.New("message id is required")
+	}
+	if len(m.Body) == 0 {
+		return nil, errors.New("message body is required")
+	}
+	return &queue.OutboundMessage{
+		ID:              m.MessageID,
+		Body:            append([]byte(nil), m.Body...),
+		Attributes:      attributes,
+		MessageGroupID:  strings.TrimSpace(m.MessageGroupID),
+		DeduplicationID: strings.TrimSpace(m.DeduplicationID),
+	}, nil
+}
+
+type EmailOutboxWriter interface {
+	CreateEmailOutboxMessage(ctx context.Context, message *EmailOutboxMessage) error
+}
+
+type EmailOutboxRepository interface {
+	EmailOutboxWriter
+	ClaimPendingEmailOutboxMessages(ctx context.Context, limit int, now time.Time, lockTTL time.Duration, workerID string) ([]EmailOutboxMessage, error)
+	MarkEmailOutboxMessagePublished(ctx context.Context, id []byte, publishedAt time.Time) error
+	MarkEmailOutboxMessageRetry(ctx context.Context, id []byte, availableAt time.Time, lastErr string) error
+	MarkEmailOutboxMessageDead(ctx context.Context, id []byte, failedAt time.Time, lastErr string) error
+	CountPendingEmailOutboxMessages(ctx context.Context, now time.Time) (int64, error)
+}
+
+type TransactionalRepository interface {
+	WithTransaction(ctx context.Context, fn func(repo Repository, outbox EmailOutboxWriter) error) error
+}
diff --git a/internal/domain/auth/identity.go b/internal/domain/auth/identity.go
new file mode 100644
index 0000000..24d56d1
--- /dev/null
+++ b/internal/domain/auth/identity.go
@@ -0,0 +1,31 @@
+package auth
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type UserIdentity struct {
+	ID              []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	UserID          []byte `gorm:"type:binary(16);uniqueIndex:ux_user_identity_user;not null;column:user_id"`
+	Provider        string `gorm:"type:varchar(32);uniqueIndex:ux_provider_subject;not null;column:provider"`
+	ProviderSubject string `gorm:"type:varchar(191);uniqueIndex:ux_provider_subject;not null;column:provider_subject"`
+	Email           string `gorm:"type:varchar(191);index;column:email"`
+	Metadata        []byte `gorm:"type:json;column:metadata"`
+	CreatedAt       time.Time
+	CreatedBy       []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt       time.Time
+	UpdatedBy       []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (UserIdentity) TableName() string { return "user_identities" }
+
+func (ui *UserIdentity) BeforeCreate(tx *gorm.DB) error {
+	if len(ui.ID) == 0 {
+		ui.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/auth/microsoft_oauth_token.go b/internal/domain/auth/microsoft_oauth_token.go
new file mode 100644
index 0000000..dc10bb4
--- /dev/null
+++ b/internal/domain/auth/microsoft_oauth_token.go
@@ -0,0 +1,40 @@
+package auth
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type UserMicrosoftOAuthToken struct {
+	ID                    []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	UserID                []byte     `gorm:"type:binary(16);uniqueIndex:ux_user_ms_oauth_user_provider;not null;column:user_id"`
+	Provider              string     `gorm:"type:varchar(32);uniqueIndex:ux_user_ms_oauth_user_provider;not null;column:provider"`
+	TenantID              string     `gorm:"type:varchar(128);index;not null;column:tenant_id"`
+	MicrosoftObjectID     string     `gorm:"type:varchar(191);not null;column:microsoft_object_id"`
+	MicrosoftSubject      string     `gorm:"type:varchar(191);not null;column:microsoft_subject"`
+	MicrosoftSessionID    string     `gorm:"type:varchar(191);column:microsoft_session_id"`
+	RefreshTokenEncrypted []byte     `gorm:"type:blob;not null;column:refresh_token_encrypted"`
+	AccessTokenEncrypted  []byte     `gorm:"type:blob;column:access_token_encrypted"`
+	IDTokenEncrypted      []byte     `gorm:"type:blob;column:id_token_encrypted"`
+	Scope                 string     `gorm:"type:text;column:scope"`
+	TokenType             string     `gorm:"type:varchar(32);column:token_type"`
+	AccessTokenExpiresAt  *time.Time `gorm:"column:access_token_expires_at"`
+	RefreshTokenExpiresAt *time.Time `gorm:"column:refresh_token_expires_at"`
+	RefreshTokenRotatedAt *time.Time `gorm:"column:refresh_token_rotated_at"`
+	CreatedAt             time.Time
+	CreatedBy             []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt             time.Time
+	UpdatedBy             []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (UserMicrosoftOAuthToken) TableName() string { return "user_microsoft_oauth_tokens" }
+
+func (t *UserMicrosoftOAuthToken) BeforeCreate(tx *gorm.DB) error {
+	if len(t.ID) == 0 {
+		t.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/auth/password_reset_token.go b/internal/domain/auth/password_reset_token.go
new file mode 100644
index 0000000..76b12ea
--- /dev/null
+++ b/internal/domain/auth/password_reset_token.go
@@ -0,0 +1,32 @@
+package auth
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type PasswordResetToken struct {
+	ID          []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	UserID      []byte     `gorm:"type:binary(16);index;not null;column:user_id"`
+	TokenHash   []byte     `gorm:"type:varbinary(32);uniqueIndex;not null;column:token_hash"`
+	ExpiresAt   time.Time  `gorm:"index;not null;column:expires_at"`
+	UsedAt      *time.Time `gorm:"index;column:used_at"`
+	RequestedIP string     `gorm:"type:varchar(128);column:requested_ip"`
+	UserAgent   string     `gorm:"type:varchar(255);column:user_agent"`
+	CreatedAt   time.Time
+	CreatedBy   []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt   time.Time
+	UpdatedBy   []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (PasswordResetToken) TableName() string { return "password_reset_tokens" }
+
+func (prt *PasswordResetToken) BeforeCreate(tx *gorm.DB) error {
+	if len(prt.ID) == 0 {
+		prt.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/auth/permission.go b/internal/domain/auth/permission.go
new file mode 100644
index 0000000..f38f761
--- /dev/null
+++ b/internal/domain/auth/permission.go
@@ -0,0 +1,32 @@
+package auth
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type Permission struct {
+	ID          []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	Name        string `gorm:"type:varchar(64);uniqueIndex;not null;column:name"`
+	Key         string `gorm:"type:varchar(64);uniqueIndex;not null;column:key"`
+	Description string `gorm:"type:varchar(255);column:description"`
+	Module      string `gorm:"type:varchar(64);index;column:module"`
+	RequiresPIN bool   `gorm:"not null;default:false;column:requires_pin"`
+	
+	CreatedAt   time.Time
+	CreatedBy   []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt   time.Time
+	UpdatedBy   []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (Permission) TableName() string { return "permissions" }
+
+func (p *Permission) BeforeCreate(tx *gorm.DB) error {
+	if len(p.ID) == 0 {
+		p.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/auth/permission_module.go b/internal/domain/auth/permission_module.go
new file mode 100644
index 0000000..fe12b42
--- /dev/null
+++ b/internal/domain/auth/permission_module.go
@@ -0,0 +1,129 @@
+package auth
+
+import "strings"
+
+const (
+	ModuleUser                     = "user"
+	ModuleRole                     = "role"
+	ModuleHelicopter               = "helicopter"
+	ModuleHelicopterUsage          = "helicopter_usage"
+	ModuleReserveAC                = "reserve_ac"
+	ModuleComplaint                = "complaint"
+	ModuleActionSignoff            = "action_signoff"
+	ModuleMCF                      = "mcf"
+	ModuleEASARelease              = "easa_release"
+	ModuleFlightInspection         = "flight_inspection"
+	ModuleAfterFlight              = "after_flight"
+	ModuleFlight                   = "flight"
+	ModuleFlightPrepCheck          = "flight_prep_check"
+	ModuleDutyRoster               = "duty_roster"
+	ModuleDUL                      = "dul"
+	ModuleHEMSOperation            = "hems_operation"
+	ModuleHEMSBase                 = "hems_base"
+	ModuleOperation                = "operation"
+	ModuleOperationCategory        = "operation_category"
+	ModuleForcesPresent            = "forces_present"
+	ModuleAirRescuerChecklist      = "air_rescuer_checklist"
+	ModuleMedicine                 = "medicine"
+	ModulePatientData              = "patient_data"
+	ModuleInsurancePatientData     = "insurance_patient_data"
+	ModuleHealthInsuranceCompanies = "health_insurance_companies"
+	ModuleVocation                 = "vocation"
+	ModuleBase                     = "base"
+	ModuleFacility                 = "facility"
+	ModuleCountry                  = "country"
+	ModuleFederalState             = "federal_state"
+	ModuleICAO                     = "icao"
+	ModuleNoICAOCode               = "no_icao_code"
+	ModuleOPC                      = "opc"
+	ModuleMasterSettings           = "master_settings"
+	ModuleFileManager              = "file_manager"
+	ModuleFilesystem               = "filesystem"
+	ModuleAudit                    = "audit"
+)
+
+type ModuleInfo struct {
+	Key   string
+	Label string
+}
+
+var ModuleRegistry = []ModuleInfo{
+	{ModuleUser, "User"},
+	{ModuleRole, "Role"},
+	{ModuleHelicopter, "Helicopter"},
+	{ModuleHelicopterUsage, "Helicopter Usage"},
+	{ModuleReserveAC, "Reserve AC"},
+	{ModuleComplaint, "Complaint"},
+	{ModuleActionSignoff, "Action Sign-off"},
+	{ModuleMCF, "MCF"},
+	{ModuleEASARelease, "EASA Release"},
+	{ModuleFlightInspection, "Flight Inspection"},
+	{ModuleAfterFlight, "After Flight Inspection"},
+	{ModuleFlight, "Flight"},
+	{ModuleFlightPrepCheck, "Flight Prep Check"},
+	{ModuleDutyRoster, "Duty Roster"},
+	{ModuleDUL, "DUL"},
+	{ModuleHEMSOperation, "HEMS Operation"},
+	{ModuleHEMSBase, "HEMS Base"},
+	{ModuleOperation, "Operation"},
+	{ModuleOperationCategory, "Operation Category"},
+	{ModuleForcesPresent, "Forces Present"},
+	{ModuleAirRescuerChecklist, "Air Rescuer Checklist"},
+	{ModuleMedicine, "Medicine"},
+	{ModulePatientData, "Patient Data"},
+	{ModuleInsurancePatientData, "Insurance Patient Data"},
+	{ModuleHealthInsuranceCompanies, "Health Insurance Companies"},
+	{ModuleVocation, "Vocation"},
+	{ModuleBase, "Base"},
+	{ModuleFacility, "Facility"},
+	{ModuleCountry, "Country"},
+	{ModuleFederalState, "Federal State"},
+	{ModuleICAO, "ICAO"},
+	{ModuleNoICAOCode, "No ICAO Code"},
+	{ModuleOPC, "OPC"},
+	{ModuleMasterSettings, "Master Settings"},
+	{ModuleFileManager, "File Manager"},
+	{ModuleFilesystem, "Filesystem"},
+	{ModuleAudit, "Audit"},
+}
+
+var moduleOrder = func() map[string]int {
+	m := make(map[string]int, len(ModuleRegistry))
+	for i := range ModuleRegistry {
+		m[ModuleRegistry[i].Key] = i
+	}
+	return m
+}()
+
+// ModuleLabel returns the display label for a module key, falling back to the
+// key itself when the module is not registered.
+func ModuleLabel(key string) string {
+	if i, ok := moduleOrder[key]; ok {
+		return ModuleRegistry[i].Label
+	}
+	return key
+}
+
+// IsRegisteredModule reports whether key is a known module in ModuleRegistry.
+func IsRegisteredModule(key string) bool {
+	_, ok := moduleOrder[key]
+	return ok
+}
+
+// ModuleSortIndex returns a module's position in ModuleRegistry, or a large
+// value (sorting unknown modules last) when it is not registered.
+func ModuleSortIndex(key string) int {
+	if idx, ok := moduleOrder[key]; ok {
+		return idx
+	}
+	return len(ModuleRegistry)
+}
+
+// ModuleForKey derives the module from a permission key by taking the segment
+// before the first dot, e.g. "dul.create" -> "dul", "role.permission.read" -> "role".
+func ModuleForKey(permissionKey string) string {
+	if i := strings.Index(permissionKey, "."); i >= 0 {
+		return permissionKey[:i]
+	}
+	return permissionKey
+}
diff --git a/internal/domain/auth/permission_module_test.go b/internal/domain/auth/permission_module_test.go
new file mode 100644
index 0000000..e049a09
--- /dev/null
+++ b/internal/domain/auth/permission_module_test.go
@@ -0,0 +1,49 @@
+package auth
+
+import "testing"
+
+func TestModuleRegistryIsConsistent(t *testing.T) {
+	seen := make(map[string]bool, len(ModuleRegistry))
+	for _, m := range ModuleRegistry {
+		if m.Key == "" {
+			t.Errorf("registry has an entry with empty key (label %q)", m.Label)
+		}
+		if m.Label == "" {
+			t.Errorf("module %q has an empty label", m.Key)
+		}
+		if seen[m.Key] {
+			t.Errorf("duplicate module key %q in ModuleRegistry", m.Key)
+		}
+		seen[m.Key] = true
+	}
+}
+
+func TestModuleForKey(t *testing.T) {
+	cases := map[string]string{
+		"dul.create":           "dul",
+		"role.permission.read": "role",
+		"file_manager.file.read": "file_manager",
+		"audit.read":           "audit",
+		"filesystem":           "filesystem",
+	}
+	for in, want := range cases {
+		if got := ModuleForKey(in); got != want {
+			t.Errorf("ModuleForKey(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestModuleLabelAndRegistration(t *testing.T) {
+	if got := ModuleLabel(ModuleDUL); got != "DUL" {
+		t.Errorf("ModuleLabel(%q) = %q, want %q", ModuleDUL, got, "DUL")
+	}
+	if got := ModuleLabel("unknown_module"); got != "unknown_module" {
+		t.Errorf("ModuleLabel fallback = %q, want the key itself", got)
+	}
+	if !IsRegisteredModule(ModuleComplaint) {
+		t.Errorf("expected %q to be a registered module", ModuleComplaint)
+	}
+	if IsRegisteredModule("unknown_module") {
+		t.Errorf("did not expect %q to be registered", "unknown_module")
+	}
+}
diff --git a/internal/domain/auth/pin_policy.go b/internal/domain/auth/pin_policy.go
new file mode 100644
index 0000000..1c88dd2
--- /dev/null
+++ b/internal/domain/auth/pin_policy.go
@@ -0,0 +1,24 @@
+package auth
+
+import "strings"
+
+var defaultPINRequiredPermissionKeys = []string{
+	"audit.read",
+	"easa_release.sign",
+}
+
+func DefaultPINRequiredPermissionKeys() []string {
+	out := make([]string, len(defaultPINRequiredPermissionKeys))
+	copy(out, defaultPINRequiredPermissionKeys)
+	return out
+}
+
+func DefaultPermissionRequiresPIN(key string) bool {
+	key = strings.ToLower(strings.TrimSpace(key))
+	for i := range defaultPINRequiredPermissionKeys {
+		if defaultPINRequiredPermissionKeys[i] == key {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/domain/auth/repository.go b/internal/domain/auth/repository.go
new file mode 100644
index 0000000..5769741
--- /dev/null
+++ b/internal/domain/auth/repository.go
@@ -0,0 +1,57 @@
+package auth
+
+import (
+	"context"
+	"time"
+)
+
+type Repository interface {
+	// Users
+	CreateUser(ctx context.Context, user *User) error
+	GetUserByID(ctx context.Context, id []byte) (*User, error)
+	GetUserByEmail(ctx context.Context, email string) (*User, error)
+	GetUserBySSOEmail(ctx context.Context, ssoEmail string) (*User, error)
+	GetUserByUsername(ctx context.Context, username string) (*User, error)
+	UpdateUserTimezone(ctx context.Context, id []byte, timezone string) error
+	SetUserPassword(ctx context.Context, id []byte, passwordHash, salt []byte) error
+	SetUserSecurityPIN(ctx context.Context, id []byte, pinHash []byte, setAt time.Time) error
+	MarkEmailVerified(ctx context.Context, id []byte) error
+
+	// Password resets
+	CreatePasswordResetToken(ctx context.Context, token *PasswordResetToken) error
+	InvalidateActivePasswordResetTokensByUserID(ctx context.Context, userID []byte, usedAt time.Time) error
+	ConsumePasswordResetTokenAndSetPassword(ctx context.Context, tokenHash, passwordHash, salt []byte, usedAt time.Time) ([]byte, bool, error)
+
+	// Security PIN resets
+	CreateSecurityPINResetToken(ctx context.Context, token *SecurityPINResetToken) error
+	InvalidateActiveSecurityPINResetTokensByUserID(ctx context.Context, userID []byte, usedAt time.Time) error
+	GetActiveSecurityPINResetTokenUser(ctx context.Context, tokenHash []byte, now time.Time) (*User, error)
+	ConsumeSecurityPINResetTokenAndSetPIN(ctx context.Context, tokenHash, pinHash []byte, usedAt time.Time) ([]byte, bool, error)
+
+	// Identities (SSO)
+	UpsertIdentity(ctx context.Context, identity *UserIdentity) error
+	CreateIdentity(ctx context.Context, identity *UserIdentity) error
+	GetIdentityByProviderSubject(ctx context.Context, provider, subject string) (*UserIdentity, error)
+	GetIdentityByUserID(ctx context.Context, userID []byte) (*UserIdentity, error)
+	DeleteIdentityByUserIDProvider(ctx context.Context, userID []byte, provider string) (bool, error)
+
+	// TOTP
+	GetUserTOTP(ctx context.Context, userID []byte) (*UserTOTP, error)
+	UpsertUserTOTP(ctx context.Context, totp *UserTOTP) error
+	DisableUserTOTP(ctx context.Context, userID []byte) error
+	DeleteUserTOTPSetup(ctx context.Context, userID []byte) error
+	UpdateUserTOTPLastUsed(ctx context.Context, userID []byte) error
+
+	// Email login OTP
+	GetActiveUserEmailLoginOTP(ctx context.Context, userID []byte, now time.Time) (*UserEmailLoginOTP, error)
+	CountUserEmailLoginOTPSince(ctx context.Context, userID []byte, since time.Time) (int64, error)
+	CreateUserEmailLoginOTP(ctx context.Context, otp *UserEmailLoginOTP) error
+	InvalidateActiveUserEmailLoginOTPs(ctx context.Context, userID []byte, usedAt time.Time) error
+	ConsumeUserEmailLoginOTP(ctx context.Context, userID, otpHash []byte, now time.Time) (bool, int, error)
+
+	// WebAuthn
+	ListUserWebAuthnCredentials(ctx context.Context, userID []byte) ([]UserWebAuthnCredential, error)
+	CreateUserWebAuthnCredential(ctx context.Context, credential *UserWebAuthnCredential) error
+	UpdateUserWebAuthnCredential(ctx context.Context, userID, credentialID, credentialJSON []byte, usedAt time.Time) error
+	DeleteAllUserWebAuthnCredentials(ctx context.Context, userID []byte) error
+}
diff --git a/internal/domain/auth/role.go b/internal/domain/auth/role.go
new file mode 100644
index 0000000..7a908f8
--- /dev/null
+++ b/internal/domain/auth/role.go
@@ -0,0 +1,29 @@
+package auth
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type Role struct {
+	ID          []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	Code        string `gorm:"type:varchar(64);uniqueIndex;column:code"`
+	Name        string `gorm:"type:varchar(64);uniqueIndex;not null;column:name"`
+	Description string `gorm:"type:varchar(255);column:description"`
+	CreatedAt   time.Time
+	CreatedBy   []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt   time.Time
+	UpdatedBy   []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (Role) TableName() string { return "roles" }
+
+func (r *Role) BeforeCreate(tx *gorm.DB) error {
+	if len(r.ID) == 0 {
+		r.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/auth/role_permission.go b/internal/domain/auth/role_permission.go
new file mode 100644
index 0000000..5327f10
--- /dev/null
+++ b/internal/domain/auth/role_permission.go
@@ -0,0 +1,28 @@
+package auth
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type RolePermission struct {
+	ID           []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	RoleID       []byte `gorm:"type:binary(16);index;uniqueIndex:ux_role_permission;not null;column:role_id"`
+	PermissionID []byte `gorm:"type:binary(16);index;uniqueIndex:ux_role_permission;not null;column:permission_id"`
+	CreatedAt    time.Time
+	CreatedBy    []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt    time.Time
+	UpdatedBy    []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (RolePermission) TableName() string { return "role_permissions" }
+
+func (rp *RolePermission) BeforeCreate(tx *gorm.DB) error {
+	if len(rp.ID) == 0 {
+		rp.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/auth/role_repository.go b/internal/domain/auth/role_repository.go
new file mode 100644
index 0000000..58478b2
--- /dev/null
+++ b/internal/domain/auth/role_repository.go
@@ -0,0 +1,20 @@
+package auth
+
+import "context"
+
+type RoleRepository interface {
+	CreateRole(ctx context.Context, role *Role) error
+	UpdateRole(ctx context.Context, role *Role) error
+	DeleteRole(ctx context.Context, id []byte) error
+	GetRoleByID(ctx context.Context, id []byte) (*Role, error)
+	GetRoleByName(ctx context.Context, name string) (*Role, error)
+	HasRolePermission(ctx context.Context, roleID []byte, permissionKey string) (bool, error)
+	GetPermissionByID(ctx context.Context, id []byte) (*Permission, error)
+	GetPermissionByKey(ctx context.Context, key string) (*Permission, error)
+	UpdatePermission(ctx context.Context, permission *Permission) error
+	ListPermissionsByRoleID(ctx context.Context, roleID []byte) ([]Permission, error)
+	ListPermissions(ctx context.Context, filter string, sort string, limit, offset int) ([]Permission, int64, error)
+	AssignPermission(ctx context.Context, roleID, permissionID []byte) (*RolePermission, error)
+	RemovePermission(ctx context.Context, roleID, permissionID []byte) error
+	ListRoles(ctx context.Context, filterName string, sort string, limit, offset int) ([]Role, int64, error)
+}
diff --git a/internal/domain/auth/security_pin_reset_token.go b/internal/domain/auth/security_pin_reset_token.go
new file mode 100644
index 0000000..c4544be
--- /dev/null
+++ b/internal/domain/auth/security_pin_reset_token.go
@@ -0,0 +1,32 @@
+package auth
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type SecurityPINResetToken struct {
+	ID          []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	UserID      []byte     `gorm:"type:binary(16);index;not null;column:user_id"`
+	TokenHash   []byte     `gorm:"type:varbinary(32);uniqueIndex;not null;column:token_hash"`
+	ExpiresAt   time.Time  `gorm:"index;not null;column:expires_at"`
+	UsedAt      *time.Time `gorm:"index;column:used_at"`
+	RequestedIP string     `gorm:"type:varchar(128);column:requested_ip"`
+	UserAgent   string     `gorm:"type:varchar(255);column:user_agent"`
+	CreatedAt   time.Time
+	CreatedBy   []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt   time.Time
+	UpdatedBy   []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (SecurityPINResetToken) TableName() string { return "security_pin_reset_tokens" }
+
+func (prt *SecurityPINResetToken) BeforeCreate(tx *gorm.DB) error {
+	if len(prt.ID) == 0 {
+		prt.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/auth/totp.go b/internal/domain/auth/totp.go
new file mode 100644
index 0000000..63c0e2e
--- /dev/null
+++ b/internal/domain/auth/totp.go
@@ -0,0 +1,30 @@
+package auth
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type UserTOTP struct {
+	ID              []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	UserID          []byte     `gorm:"type:binary(16);uniqueIndex;not null;column:user_id"`
+	SecretEncrypted []byte     `gorm:"type:varbinary(512);not null;column:secret_encrypted"`
+	Enabled         bool       `gorm:"type:tinyint(1);not null;default:0;column:enabled"`
+	LastUsedAt      *time.Time `gorm:"column:last_used_at"`
+	CreatedAt       time.Time
+	CreatedBy       []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt       time.Time
+	UpdatedBy       []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (UserTOTP) TableName() string { return "user_totp" }
+
+func (ut *UserTOTP) BeforeCreate(tx *gorm.DB) error {
+	if len(ut.ID) == 0 {
+		ut.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/auth/user.go b/internal/domain/auth/user.go
new file mode 100644
index 0000000..a9bbde4
--- /dev/null
+++ b/internal/domain/auth/user.go
@@ -0,0 +1,58 @@
+package auth
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+// Note: UUIDv7 should be generated at application layer and stored as BINARY(16).
+type User struct {
+	ID                  []byte   `gorm:"type:binary(16);primaryKey;column:id"`
+	RoleID              []byte   `gorm:"type:binary(16);index;column:role_id"`
+	RoleIDs             [][]byte `gorm:"-"`
+	Roles               []Role   `gorm:"-"`
+	ImageAttachmentID   []byte   `gorm:"type:binary(16);index;column:image_attachment_id"`
+	ProfileAttachmentID []byte   `gorm:"type:binary(16);index;column:profile_attachment_id"`
+
+	Email        string  `gorm:"type:varchar(191);uniqueIndex;not null;column:email"`
+	SSOEmail     *string `gorm:"type:varchar(191);uniqueIndex;column:sso_email"`
+	Username     *string `gorm:"type:varchar(100);index;column:username"`
+	FirstName    string  `gorm:"type:varchar(100);not null;column:first_name"`
+	LastName     string  `gorm:"type:varchar(100);not null;column:last_name"`
+	MobilePhone  string  `gorm:"type:varchar(32);index;column:mobile_phone"`
+	Timezone     string  `gorm:"type:varchar(64);not null;default:UTC;column:timezone"`
+	SortKey      *int    `gorm:"index;column:sortkey"`
+	PasswordHash []byte  `gorm:"type:varbinary(255);column:password_hash"`
+	SaltValue    []byte  `gorm:"type:varbinary(255);column:salt_value"`
+	// Stores PIN hash records ("<salt_b64>$<hash_b64>"); legacy rows may still contain encrypted values.
+	SecurityPINHash  []byte     `gorm:"type:varbinary(512);column:security_pin_hash"`
+	SecurityPINSetAt *time.Time `gorm:"column:security_pin_set_at"`
+	EmailVerifiedAt  *time.Time `gorm:"column:email_verified_at"`
+	IsActive         bool       `gorm:"index;not null;default:true;column:is_active"`
+	CreatedAt        time.Time
+	CreatedBy        []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt        time.Time
+	UpdatedBy        []byte `gorm:"type:binary(16);column:updated_by"`
+
+	PilotProfile           *PilotProfile           `gorm:"foreignKey:UserID;references:ID"`
+	DoctorProfile          *DoctorProfile          `gorm:"foreignKey:UserID;references:ID"`
+	AirRescuerProfile      *AirRescuerProfile      `gorm:"foreignKey:UserID;references:ID"`
+	TechnicianProfile      *TechnicianProfile      `gorm:"foreignKey:UserID;references:ID"`
+	FlightAssistantProfile *FlightAssistantProfile `gorm:"foreignKey:UserID;references:ID"`
+	StaffProfile           *StaffProfile           `gorm:"foreignKey:UserID;references:ID"`
+	ImageAttachment        *filemanager.Attachment `gorm:"foreignKey:ImageAttachmentID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	ProfileAttachment      *filemanager.Attachment `gorm:"foreignKey:ProfileAttachmentID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+}
+
+func (User) TableName() string { return "users" }
+
+func (u *User) BeforeCreate(tx *gorm.DB) error {
+	if len(u.ID) == 0 {
+		u.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/auth/user_role.go b/internal/domain/auth/user_role.go
new file mode 100644
index 0000000..ff58795
--- /dev/null
+++ b/internal/domain/auth/user_role.go
@@ -0,0 +1,28 @@
+package auth
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type UserRole struct {
+	ID        []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	UserID    []byte `gorm:"type:binary(16);index;uniqueIndex:ux_user_role;not null;column:user_id"`
+	RoleID    []byte `gorm:"type:binary(16);index;uniqueIndex:ux_user_role;not null;column:role_id"`
+	CreatedAt time.Time
+	CreatedBy []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time
+	UpdatedBy []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (UserRole) TableName() string { return "user_roles" }
+
+func (ur *UserRole) BeforeCreate(tx *gorm.DB) error {
+	if len(ur.ID) == 0 {
+		ur.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/auth/webauthn_credential.go b/internal/domain/auth/webauthn_credential.go
new file mode 100644
index 0000000..df34054
--- /dev/null
+++ b/internal/domain/auth/webauthn_credential.go
@@ -0,0 +1,30 @@
+package auth
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+// UserWebAuthnCredential stores a passkey credential bound to a user.
+type UserWebAuthnCredential struct {
+	ID             []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	UserID         []byte     `gorm:"type:binary(16);index;not null;column:user_id"`
+	Name           string     `gorm:"type:varchar(100);column:name"`
+	CredentialID   []byte     `gorm:"type:varbinary(512);uniqueIndex;not null;column:credential_id"`
+	CredentialJSON []byte     `gorm:"type:mediumblob;not null;column:credential_json"`
+	LastUsedAt     *time.Time `gorm:"column:last_used_at"`
+	CreatedAt      time.Time
+	UpdatedAt      time.Time
+}
+
+func (UserWebAuthnCredential) TableName() string { return "user_webauthn_credentials" }
+
+func (c *UserWebAuthnCredential) BeforeCreate(tx *gorm.DB) error {
+	if len(c.ID) == 0 {
+		c.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/base/model.go b/internal/domain/base/model.go
new file mode 100644
index 0000000..6e42b0d
--- /dev/null
+++ b/internal/domain/base/model.go
@@ -0,0 +1,158 @@
+package base
+
+import (
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	CategoryKeyRegular                      = "regular"
+	CategoryKeyHEMS                         = "hems"
+	ShiftTimeTypeFixed                      = "FIXED"
+	ShiftTimeTypeBMCT                       = "BMCT"
+	ShiftTimeTypeECET                       = "ECET"
+	BaseContactRoleHEMSEDC          = "hems_edc"
+	BaseContactRoleMedPax           = "med_pax"
+	BaseContactRoleResponsiblePilot = "responsible_pilot"
+)
+
+func NormalizeCategoryType(raw string) (string, bool) {
+	switch strings.ToLower(strings.TrimSpace(raw)) {
+	case "", CategoryKeyRegular, "base":
+		return CategoryKeyRegular, true
+	case CategoryKeyHEMS, "hems-base", "hems_base":
+		return CategoryKeyHEMS, true
+	default:
+		return "", false
+	}
+}
+
+type BaseCategory struct {
+	ID        []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	Key       string    `gorm:"type:varchar(64);not null;uniqueIndex;column:key"`
+	Name      string    `gorm:"type:varchar(150);not null;column:name"`
+	CreatedAt time.Time `gorm:"column:created_at"`
+	UpdatedAt time.Time `gorm:"column:updated_at"`
+}
+
+func (BaseCategory) TableName() string { return "base_categories" }
+
+func (c *BaseCategory) BeforeCreate(tx *gorm.DB) error {
+	if len(c.ID) == 0 {
+		c.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type Base struct {
+	ID                                 []byte                     `gorm:"type:binary(16);primaryKey;column:id"`
+	BaseName                           string                     `gorm:"type:varchar(150);not null;column:base"`
+	BaseCategoryID                     []byte                     `gorm:"type:binary(16);index;column:base_category_id"`
+	FotoAttachmentID                   []byte                     `gorm:"type:binary(16);index;column:foto_attachment_id"`
+	BaseAbbreviation                   string                     `gorm:"type:varchar(64);column:base_abbreviation"`
+	Address                            string                     `gorm:"type:varchar(255);column:address"`
+	Latitude                           float64                    `gorm:"type:decimal(10,7);not null;default:0;column:latitude"`
+	Longitude                          float64                    `gorm:"type:decimal(10,7);not null;default:0;column:longitude"`
+	LandlineNumber                     string                     `gorm:"type:varchar(64);column:landline_number"`
+	MobileNumber                       string                     `gorm:"type:varchar(64);column:mobile_number"`
+	Email                              string                     `gorm:"type:varchar(191);column:email"`
+	SortKey                            *int                       `gorm:"column:sortkey"`
+	SMSAlert                           bool                       `gorm:"type:tinyint(1);not null;default:0;column:sms_alert"`
+	Checklist                          bool                       `gorm:"type:tinyint(1);not null;default:0;column:checklist"`
+	LegTime                            string                     `gorm:"type:varchar(64);column:leg_time"`
+	DefaultStartTimeType               string                     `gorm:"type:varchar(16);not null;default:'FIXED';column:default_start_time_type"`
+	DefaultEndTimeType                 string                     `gorm:"type:varchar(16);not null;default:'FIXED';column:default_end_time_type"`
+	DefaultShiftStart                  string                     `gorm:"type:time;column:default_shift_start"`
+	DefaultShiftEnd                    string                     `gorm:"type:time;column:default_shift_end"`
+	UTC                                string                     `gorm:"type:varchar(100);not null;default:'0';column:utc"`
+	Dry                                bool                       `gorm:"type:tinyint(1);not null;default:0;column:dry"`
+	ControlCenter                      bool                       `gorm:"type:tinyint(1);not null;default:0;column:control_center"`
+	DUL                                bool                       `gorm:"type:tinyint(1);not null;default:0;column:dul"`
+	Notes                              string                     `gorm:"type:text;column:notes"`
+	IsActive                           bool                       `gorm:"type:tinyint(1);index;not null;default:1;column:is_active"`
+	HEMSEDCContactIDs          [][]byte            `gorm:"-:all"`
+	MedPaxContactIDs           [][]byte            `gorm:"-:all"`
+	ResponsiblePilotContactIDs [][]byte            `gorm:"-:all"`
+	HEMSEDCs                   []BaseContactPerson `gorm:"-:all"`
+	MedPax                     []BaseContactPerson `gorm:"-:all"`
+	ResponsiblePilots          []BaseContactPerson `gorm:"-:all"`
+	OperationalShiftTimes              []BaseOperationalShiftTime `gorm:"foreignKey:BaseID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	BaseCategory                       BaseCategory               `gorm:"foreignKey:BaseCategoryID;references:ID"`
+	FotoAttachment                     *filemanager.Attachment    `gorm:"foreignKey:FotoAttachmentID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+
+	CreatedAt time.Time
+	CreatedBy []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (Base) TableName() string { return "bases" }
+
+type BaseOperationalShiftTime struct {
+	ID            []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	BaseID        []byte     `gorm:"type:binary(16);not null;index:idx_base_operational_shift_times_base_date,priority:1;column:base_id"`
+	DateStart     *time.Time `gorm:"type:date;index:idx_base_operational_shift_times_base_date,priority:2;column:date_start"`
+	DateEnd       *time.Time `gorm:"type:date;index:idx_base_operational_shift_times_base_date,priority:3;column:date_end"`
+	StartTimeType string     `gorm:"type:varchar(16);not null;default:'FIXED';column:start_time_type"`
+	EndTimeType   string     `gorm:"type:varchar(16);not null;default:'FIXED';column:end_time_type"`
+	ShiftStart    string     `gorm:"type:time;column:shift_start"`
+	ShiftEnd      string     `gorm:"type:time;column:shift_end"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at;index"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+
+	Base *Base `gorm:"foreignKey:BaseID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (BaseOperationalShiftTime) TableName() string { return "base_operational_shift_times" }
+
+func (b *BaseOperationalShiftTime) BeforeCreate(tx *gorm.DB) error {
+	if len(b.ID) == 0 {
+		b.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type BaseContactRole struct {
+	ID        []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	BaseID    []byte    `gorm:"type:binary(16);not null;index;column:base_id"`
+	ContactID []byte    `gorm:"type:binary(16);not null;index;column:contact_id"`
+	RoleCode  string    `gorm:"type:varchar(64);not null;index;column:role_code"`
+	CreatedBy []byte    `gorm:"type:binary(16);column:created_by"`
+	UpdatedBy []byte    `gorm:"type:binary(16);column:updated_by"`
+	CreatedAt time.Time `gorm:"column:created_at"`
+	UpdatedAt time.Time `gorm:"column:updated_at"`
+}
+
+type BaseContactPerson struct {
+	ContactID []byte
+	FirstName string
+	LastName  string
+}
+
+func (BaseContactRole) TableName() string { return "base_contact_roles" }
+
+func (r *BaseContactRole) BeforeCreate(tx *gorm.DB) error {
+	if len(r.ID) == 0 {
+		r.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+func (b *Base) BeforeCreate(tx *gorm.DB) error {
+	if len(b.ID) == 0 {
+		b.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/base/repository.go b/internal/domain/base/repository.go
new file mode 100644
index 0000000..2603916
--- /dev/null
+++ b/internal/domain/base/repository.go
@@ -0,0 +1,11 @@
+package base
+
+import "context"
+
+type Repository interface {
+	CreateBase(ctx context.Context, row *Base, categoryType string) error
+	UpdateBase(ctx context.Context, row *Base, categoryType string) error
+	DeleteBase(ctx context.Context, id []byte, categoryType string) error
+	GetBaseByID(ctx context.Context, id []byte, categoryType string) (*Base, error)
+	ListBases(ctx context.Context, filter, sort string, limit, offset int, categoryType string, dul *bool) ([]Base, int64, error)
+}
diff --git a/internal/domain/base/service.go b/internal/domain/base/service.go
new file mode 100644
index 0000000..038cedf
--- /dev/null
+++ b/internal/domain/base/service.go
@@ -0,0 +1,11 @@
+package base
+
+import "context"
+
+type Service interface {
+	CreateBase(ctx context.Context, row *Base, categoryType string) error
+	UpdateBase(ctx context.Context, row *Base, categoryType string) error
+	DeleteBase(ctx context.Context, id []byte, categoryType string) (*Base, error)
+	GetBaseByID(ctx context.Context, id []byte, categoryType string) (*Base, error)
+	ListBases(ctx context.Context, filter, sort string, limit, offset int, categoryType string, dul *bool) ([]Base, int64, error)
+}
diff --git a/internal/domain/before_flight_inspection/model.go b/internal/domain/before_flight_inspection/model.go
new file mode 100644
index 0000000..a40b500
--- /dev/null
+++ b/internal/domain/before_flight_inspection/model.go
@@ -0,0 +1,75 @@
+package beforeflightinspection
+
+import (
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	FuelUnitLT    = "LT"
+	FuelUnitKG    = "KG"
+	FuelUnitPOUND = "POUND"
+)
+
+type BeforeFlightInspection struct {
+	ID                        []byte   `gorm:"type:binary(16);primaryKey;column:id"`
+	FlightInspectionID        []byte   `gorm:"type:binary(16);not null;uniqueIndex;column:flight_inspection_id"`
+	OilEngineNR1Checked       *bool    `gorm:"type:tinyint(1);column:oil_engine_nr1_checked"`
+	OilEngineNR2Checked       *bool    `gorm:"type:tinyint(1);column:oil_engine_nr2_checked"`
+	HydraulicLHChecked        *bool    `gorm:"type:tinyint(1);column:hydraulic_lh_checked"`
+	HydraulicRHChecked        *bool    `gorm:"type:tinyint(1);column:hydraulic_rh_checked"`
+	OilTransmissionMGBChecked *bool    `gorm:"type:tinyint(1);column:oil_transmission_mgb_checked"`
+	OilTransmissionIGBChecked *bool    `gorm:"type:tinyint(1);column:oil_transmission_igb_checked"`
+	OilTransmissionTGBChecked *bool    `gorm:"type:tinyint(1);column:oil_transmission_tgb_checked"`
+	FuelAmount                *float64 `gorm:"type:decimal(10,2);column:fuel_amount"`
+	FuelUnit                  string   `gorm:"type:varchar(10);check:chk_before_flight_fuel_unit,fuel_unit IS NULL OR fuel_unit IN ('LT','KG','POUND');column:fuel_unit"`
+	FuelAddedAmount           *float64 `gorm:"type:decimal(10,2);column:fuel_added_amount"`
+	Note                      *string  `gorm:"type:text;column:note"`
+
+	CreatedAt time.Time `gorm:"column:created_at"`
+	CreatedBy []byte    `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time `gorm:"column:updated_at"`
+	UpdatedBy []byte    `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (BeforeFlightInspection) TableName() string { return "before_flight_inspections" }
+
+func (b *BeforeFlightInspection) BeforeCreate(tx *gorm.DB) error {
+	if len(b.ID) == 0 {
+		b.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+func NormalizeFuelUnit(raw string) (string, bool) {
+	switch strings.ToUpper(strings.TrimSpace(raw)) {
+	case "":
+		return "", true
+	case FuelUnitLT:
+		return FuelUnitLT, true
+	case FuelUnitKG:
+		return FuelUnitKG, true
+	case FuelUnitPOUND:
+		return FuelUnitPOUND, true
+	default:
+		return "", false
+	}
+}
+
+type ValidationError struct {
+	Status  int
+	Title   string
+	Pointer string
+	Detail  string
+}
+
+func (e *ValidationError) Error() string {
+	if e == nil {
+		return ""
+	}
+	return strings.TrimSpace(e.Detail)
+}
diff --git a/internal/domain/before_flight_inspection/repository.go b/internal/domain/before_flight_inspection/repository.go
new file mode 100644
index 0000000..f598ad1
--- /dev/null
+++ b/internal/domain/before_flight_inspection/repository.go
@@ -0,0 +1,20 @@
+package beforeflightinspection
+
+import "context"
+
+type Repository interface {
+	Upsert(ctx context.Context, row *BeforeFlightInspection) error
+	GetByFlightInspectionID(ctx context.Context, flightInspectionID []byte) (*BeforeFlightInspection, error)
+	FlightInspectionExists(ctx context.Context, flightInspectionID []byte) (bool, error)
+	GetHelicopterCapabilities(ctx context.Context, flightInspectionID []byte) (*HelicopterCapabilities, error)
+}
+
+type HelicopterCapabilities struct {
+	NR1 bool
+	NR2 bool
+	LH  bool
+	RH  bool
+	MGB bool
+	IGB bool
+	TGB bool
+}
diff --git a/internal/domain/before_flight_inspection/service.go b/internal/domain/before_flight_inspection/service.go
new file mode 100644
index 0000000..daea2c4
--- /dev/null
+++ b/internal/domain/before_flight_inspection/service.go
@@ -0,0 +1,22 @@
+package beforeflightinspection
+
+import "context"
+
+type Service interface {
+	Upsert(ctx context.Context, flightInspectionID []byte, req *UpsertRequest) (*BeforeFlightInspection, error)
+	GetByFlightInspectionID(ctx context.Context, flightInspectionID []byte) (*BeforeFlightInspection, error)
+}
+
+type UpsertRequest struct {
+	OilEngineNR1Checked       *bool    `json:"oil_engine_nr1_checked"`
+	OilEngineNR2Checked       *bool    `json:"oil_engine_nr2_checked"`
+	HydraulicLHChecked        *bool    `json:"hydraulic_lh_checked"`
+	HydraulicRHChecked        *bool    `json:"hydraulic_rh_checked"`
+	OilTransmissionMGBChecked *bool    `json:"oil_transmission_mgb_checked"`
+	OilTransmissionIGBChecked *bool    `json:"oil_transmission_igb_checked"`
+	OilTransmissionTGBChecked *bool    `json:"oil_transmission_tgb_checked"`
+	FuelAmount                *float64 `json:"fuel_amount"`
+	FuelUnit                  *string  `json:"fuel_unit"`
+	FuelAddedAmount           *float64 `json:"fuel_added_amount"`
+	Note                      *string  `json:"note"`
+}
diff --git a/internal/domain/complaint/model.go b/internal/domain/complaint/model.go
new file mode 100644
index 0000000..47f4ea2
--- /dev/null
+++ b/internal/domain/complaint/model.go
@@ -0,0 +1,153 @@
+package complaint
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	flightdomain "wucher/internal/domain/flight"
+	helicopter "wucher/internal/domain/helicopter"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	MELSeverityNonMEL int8 = 0
+	MELSeverityA      int8 = 1
+	MELSeverityB      int8 = 2
+	MELSeverityC      int8 = 3
+	MELSeverityD      int8 = 4
+)
+
+const (
+	StatusPendingMEL   = "pending_mel"
+	StatusActiveNonMEL = "active_non_mel"
+	StatusActiveMEL    = "active_mel"
+	StatusServiced     = "serviced"
+)
+
+var melGraceDays = map[int8]int{
+	MELSeverityA: 1,
+	MELSeverityB: 3,
+	MELSeverityC: 10,
+	MELSeverityD: 120,
+}
+
+type ListFilter struct {
+	Search        string
+	DateFrom      string
+	DateTo        string
+	Person        string
+	HelicopterID  []byte
+	FlightID      []byte
+	HoldItemsOnly bool
+}
+
+func MELGraceDays(severity int8) int { return melGraceDays[severity] }
+
+type Complaint struct {
+	ID           []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	HelicopterID []byte `gorm:"type:binary(16);not null;index;column:helicopter_id"`
+	FlightID     []byte `gorm:"type:binary(16);index;column:flight_id"`
+
+	Description           string    `gorm:"type:text;not null;column:description"`
+	ReportedBy            []byte    `gorm:"type:binary(16);not null;column:reported_by"`
+	ReportedAt            time.Time `gorm:"type:datetime(3);not null;column:reported_at"`
+	AircraftHoursAtReport *string   `gorm:"type:varchar(20);column:aircraft_hours_at_report"`
+
+	MELSeverity     int8       `gorm:"type:tinyint;not null;default:0;column:mel_severity"`
+	MELClassifiedAt *time.Time `gorm:"type:datetime(3);column:mel_classified_at"`
+	MELClassifiedBy []byte     `gorm:"type:binary(16);column:mel_classified_by"`
+
+	IsNSR        bool       `gorm:"type:boolean;not null;default:false;column:is_nsr"`
+	NSRDecidedAt *time.Time `gorm:"type:datetime(3);column:nsr_decided_at"`
+	NSRDecidedBy []byte     `gorm:"type:binary(16);column:nsr_decided_by"`
+	NSRReason    *string    `gorm:"type:text;column:nsr_reason"`
+
+	ActionTaken        *string `gorm:"type:text;column:action_taken"`
+	AircraftHoursAtFix *string `gorm:"type:varchar(20);column:aircraft_hours_at_fix"`
+
+	FixedAt       *time.Time `gorm:"type:datetime(3);column:fixed_at"`
+	FixedByEASAID []byte     `gorm:"type:binary(16);column:fixed_by_easa_id"`
+
+	Helicopter *helicopter.Helicopter `gorm:"foreignKey:HelicopterID;references:ID"`
+	Flight     *flightdomain.Flight   `gorm:"foreignKey:FlightID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+
+	CreatedAt time.Time  `gorm:"type:datetime(3);column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"type:datetime(3);column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"type:datetime(3);index;column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (Complaint) TableName() string { return "complaints" }
+
+func (c *Complaint) BeforeCreate(_ *gorm.DB) error {
+	if len(c.ID) == 0 {
+		c.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+func (c *Complaint) Status() string {
+	if c == nil {
+		return StatusActiveNonMEL
+	}
+	if c.FixedAt != nil {
+		return StatusServiced
+	}
+	// mel_severity is optional at creation; until it is classified (mel_classified_at set)
+	// the complaint is "pending_mel" — its severity value (0) is a default, not "Non-MEL".
+	if c.MELClassifiedAt == nil {
+		return StatusPendingMEL
+	}
+	if c.MELSeverity > 0 {
+		return StatusActiveMEL
+	}
+	return StatusActiveNonMEL
+}
+
+func (c *Complaint) MELDeadline() *time.Time {
+	if c == nil || c.MELSeverity <= 0 {
+		return nil
+	}
+	grace := MELGraceDays(c.MELSeverity)
+	if grace <= 0 || c.ReportedAt.IsZero() {
+		return nil
+	}
+	// MEL grace is measured in days: A=1, B=3, C=10, D=120 days from report.
+	deadline := c.ReportedAt.Add(time.Duration(grace) * 24 * time.Hour)
+	return &deadline
+}
+
+func (c *Complaint) IsMELAOG(now time.Time) bool {
+	if c == nil || c.IsNSR {
+		return false
+	}
+	deadline := c.MELDeadline()
+	if deadline == nil {
+		return false
+	}
+	return !now.Before(*deadline)
+}
+
+// IsGrounding reports whether this complaint currently grounds the aircraft (AOG).
+// Returning to service requires a formal release: only a Non-Safety Release (NSR /
+// MEL deferral) or a signed EASA release (CRS, sets FixedAt) lifts the grounding.
+// Recording action_taken alone does NOT lift it — corrective work is not a release.
+//
+// A pending (not-yet-classified) complaint does NOT ground: an unassessed report is not
+// yet a grounding defect. Grounding starts at classification — NON-MEL grounds
+// immediately, MEL A–D grounds once its grace deadline lapses.
+func (c *Complaint) IsGrounding(now time.Time) bool {
+	if c == nil || c.IsNSR || c.FixedAt != nil {
+		return false
+	}
+	if c.MELClassifiedAt == nil {
+		return false
+	}
+	if c.MELSeverity <= 0 {
+		return true
+	}
+	return c.IsMELAOG(now)
+}
diff --git a/internal/domain/complaint/model_test.go b/internal/domain/complaint/model_test.go
new file mode 100644
index 0000000..816db92
--- /dev/null
+++ b/internal/domain/complaint/model_test.go
@@ -0,0 +1,141 @@
+package complaint
+
+import (
+	"testing"
+	"time"
+)
+
+func TestComplaintStatus(t *testing.T) {
+	now := time.Now()
+	cases := []struct {
+		name string
+		row  *Complaint
+		want string
+	}{
+		{name: "nil complaint", row: nil, want: StatusActiveNonMEL},
+		{name: "unclassified is pending", row: &Complaint{}, want: StatusPendingMEL},
+		{name: "classified non-mel", row: &Complaint{MELSeverity: MELSeverityNonMEL, MELClassifiedAt: &now}, want: StatusActiveNonMEL},
+		{name: "classified mel A", row: &Complaint{MELSeverity: MELSeverityA, MELClassifiedAt: &now}, want: StatusActiveMEL},
+		{name: "fixed overrides mel", row: &Complaint{MELSeverity: MELSeverityA, MELClassifiedAt: &now, FixedAt: &now}, want: StatusServiced},
+		{name: "fixed overrides default", row: &Complaint{FixedAt: &now}, want: StatusServiced},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := tc.row.Status(); got != tc.want {
+				t.Fatalf("Status() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestComplaintMELDeadline(t *testing.T) {
+	base := time.Date(2026, 6, 17, 8, 0, 0, 0, time.UTC)
+	cases := []struct {
+		name     string
+		row      *Complaint
+		wantNil  bool
+		wantTime time.Time
+	}{
+		{name: "non-mel", row: &Complaint{MELSeverity: MELSeverityNonMEL, ReportedAt: base}, wantNil: true},
+		// Grace is counted in days: A=1, D=120.
+		{name: "mel A", row: &Complaint{MELSeverity: MELSeverityA, ReportedAt: base}, wantTime: base.Add(24 * time.Hour)},
+		{name: "mel D", row: &Complaint{MELSeverity: MELSeverityD, ReportedAt: base}, wantTime: base.Add(120 * 24 * time.Hour)},
+		{name: "zero reported_at", row: &Complaint{MELSeverity: MELSeverityA}, wantNil: true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := tc.row.MELDeadline()
+			if tc.wantNil {
+				if got != nil {
+					t.Fatalf("MELDeadline() = %v, want nil", got)
+				}
+				return
+			}
+			if got == nil || !got.Equal(tc.wantTime) {
+				t.Fatalf("MELDeadline() = %v, want %v", got, tc.wantTime)
+			}
+		})
+	}
+}
+
+func TestComplaintIsGrounding(t *testing.T) {
+	base := time.Date(2026, 6, 17, 8, 0, 0, 0, time.UTC)
+	fixed := base
+	classified := base
+	cases := []struct {
+		name string
+		row  *Complaint
+		now  time.Time
+		want bool
+	}{
+		{name: "nsr never grounds", row: &Complaint{MELSeverity: MELSeverityNonMEL, ReportedAt: base, MELClassifiedAt: &classified, IsNSR: true}, now: base, want: false},
+		{name: "fixed never grounds", row: &Complaint{MELSeverity: MELSeverityNonMEL, ReportedAt: base, MELClassifiedAt: &classified, FixedAt: &fixed}, now: base, want: false},
+		{name: "pending (unclassified) does not ground", row: &Complaint{MELSeverity: MELSeverityNonMEL, ReportedAt: base}, now: base, want: false},
+		{name: "action taken alone does not lift grounding (needs EASA release)", row: &Complaint{MELSeverity: MELSeverityNonMEL, ReportedAt: base, MELClassifiedAt: &classified, ActionTaken: ptr("tightened")}, now: base, want: true},
+		{name: "action taken with EASA fix lifts grounding", row: &Complaint{MELSeverity: MELSeverityNonMEL, ReportedAt: base, MELClassifiedAt: &classified, ActionTaken: ptr("tightened"), FixedAt: &fixed}, now: base, want: false},
+		{name: "non-mel grounds immediately", row: &Complaint{MELSeverity: MELSeverityNonMEL, ReportedAt: base, MELClassifiedAt: &classified}, now: base, want: true},
+		{name: "mel within grace not grounding", row: &Complaint{MELSeverity: MELSeverityA, ReportedAt: base, MELClassifiedAt: &classified}, now: base.Add(12 * time.Hour), want: false},
+		{name: "mel past grace grounds", row: &Complaint{MELSeverity: MELSeverityA, ReportedAt: base, MELClassifiedAt: &classified}, now: base.Add(2 * 24 * time.Hour), want: true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := tc.row.IsGrounding(tc.now); got != tc.want {
+				t.Fatalf("IsGrounding() = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestComplaintIsMELAOG(t *testing.T) {
+	base := time.Date(2026, 6, 17, 8, 0, 0, 0, time.UTC)
+	cases := []struct {
+		name string
+		row  *Complaint
+		now  time.Time
+		want bool
+	}{
+		{name: "nsr", row: &Complaint{MELSeverity: MELSeverityA, ReportedAt: base, IsNSR: true}, now: base.Add(time.Hour), want: false},
+		{name: "non-mel has no deadline", row: &Complaint{MELSeverity: MELSeverityNonMEL, ReportedAt: base}, now: base.Add(time.Hour), want: false},
+		{name: "before deadline", row: &Complaint{MELSeverity: MELSeverityA, ReportedAt: base}, now: base, want: false},
+		{name: "at deadline", row: &Complaint{MELSeverity: MELSeverityA, ReportedAt: base}, now: base.Add(24 * time.Hour), want: true},
+		{name: "after deadline", row: &Complaint{MELSeverity: MELSeverityA, ReportedAt: base}, now: base.Add(5 * 24 * time.Hour), want: true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := tc.row.IsMELAOG(tc.now); got != tc.want {
+				t.Fatalf("IsMELAOG() = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func ptr(s string) *string { return &s }
+
+func TestComplaintTableNameAndBeforeCreate(t *testing.T) {
+	if (Complaint{}).TableName() != "complaints" {
+		t.Fatalf("unexpected table name")
+	}
+	c := &Complaint{}
+	if err := c.BeforeCreate(nil); err != nil {
+		t.Fatalf("BeforeCreate err: %v", err)
+	}
+	if len(c.ID) == 0 {
+		t.Fatal("BeforeCreate should set ID")
+	}
+	prev := string(c.ID)
+	if err := c.BeforeCreate(nil); err != nil {
+		t.Fatalf("BeforeCreate err: %v", err)
+	}
+	if string(c.ID) != prev {
+		t.Fatal("BeforeCreate must not overwrite an existing ID")
+	}
+}
+
+func TestMELGraceDays(t *testing.T) {
+	if MELGraceDays(MELSeverityA) != 1 || MELGraceDays(MELSeverityD) != 120 {
+		t.Fatal("unexpected grace days")
+	}
+	if MELGraceDays(MELSeverityNonMEL) != 0 {
+		t.Fatal("non-mel has no grace")
+	}
+}
diff --git a/internal/domain/complaint/repository.go b/internal/domain/complaint/repository.go
new file mode 100644
index 0000000..a4abb4f
--- /dev/null
+++ b/internal/domain/complaint/repository.go
@@ -0,0 +1,19 @@
+package complaint
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *Complaint) error
+	Update(ctx context.Context, row *Complaint) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Complaint, error)
+	ListByHelicopter(ctx context.Context, helicopterID []byte, limit, offset int) ([]Complaint, int64, error)
+	List(ctx context.Context, filter ListFilter, sort string, limit, offset int) ([]Complaint, int64, error)
+	HelicopterHasOpenComplaint(ctx context.Context, helicopterID []byte) (bool, error)
+	ActiveGroundingByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) ([]Complaint, error)
+	OpenByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) ([]Complaint, error)
+	HelicopterHasUnactionedComplaint(ctx context.Context, helicopterID []byte) (bool, error)
+	MarkFixedByHelicopter(ctx context.Context, helicopterID []byte, easaID []byte, actor []byte) error
+	MarkFixedByComplaint(ctx context.Context, complaintID []byte, easaID []byte, actor []byte) error
+	MarkFixedByFlight(ctx context.Context, flightID []byte, easaID []byte, actor []byte) error
+}
diff --git a/internal/domain/complaint/service.go b/internal/domain/complaint/service.go
new file mode 100644
index 0000000..5403ffa
--- /dev/null
+++ b/internal/domain/complaint/service.go
@@ -0,0 +1,20 @@
+package complaint
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *Complaint) error
+	Update(ctx context.Context, row *Complaint) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Complaint, error)
+	ListByHelicopter(ctx context.Context, helicopterID []byte, limit, offset int) ([]Complaint, int64, error)
+	List(ctx context.Context, filter ListFilter, sort string, limit, offset int) ([]Complaint, int64, error)
+	HelicopterHasOpenComplaint(ctx context.Context, helicopterID []byte) (bool, error)
+	ActiveGroundingByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) ([]Complaint, error)
+	OpenByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) ([]Complaint, error)
+	HelicopterHasUnactionedComplaint(ctx context.Context, helicopterID []byte) (bool, error)
+	MarkFixedByHelicopter(ctx context.Context, helicopterID []byte, easaID []byte, actor []byte) error
+	MarkFixedByComplaint(ctx context.Context, complaintID []byte, easaID []byte, actor []byte) error
+	MarkFixedByFlight(ctx context.Context, flightID []byte, easaID []byte, actor []byte) error
+	ResolveUserNames(ctx context.Context, complaints []Complaint) (map[string]string, error)
+}
diff --git a/internal/domain/contact/errors.go b/internal/domain/contact/errors.go
new file mode 100644
index 0000000..750aaf9
--- /dev/null
+++ b/internal/domain/contact/errors.go
@@ -0,0 +1,5 @@
+package contact
+
+import "errors"
+
+var ErrUsernameAlreadyExists = errors.New("username already exists")
diff --git a/internal/domain/contact/model.go b/internal/domain/contact/model.go
new file mode 100644
index 0000000..b534535
--- /dev/null
+++ b/internal/domain/contact/model.go
@@ -0,0 +1,190 @@
+package contact
+
+import "time"
+
+type ListFilter struct {
+	Role                 string
+	PilotCategory        string
+	ChiefDoctor          *bool
+	ChiefTechnician      *bool
+	ResponsibleComplaint *bool
+	ChiefPilot           *bool
+	IFRQualified         *bool
+	Search               string
+	Sort                 string
+	Limit                int
+	Offset               int
+}
+
+type UserPatch struct {
+	Email               *string
+	SSOEmail            *string
+	IsAdmin             *bool
+	Username            *string
+	FirstName           *string
+	LastName            *string
+	MobilePhone         *string
+	Timezone            *string
+	SortKey             *int
+	SortKeySet          bool
+	IsActive            *bool
+	ProfileAttachmentID *[]byte
+}
+
+type ProfilePatch struct {
+	PilotCategory            *string
+	ShortName                *string
+	LicenseNo                *string
+	LicenseIssuedAt          *time.Time
+	LicenseExpiredAt         *time.Time
+	TechnicianLicenseNo      *string
+	HasIFRQualification      *bool
+	IsChiefPilot             *bool
+	IsDUL                    *bool
+	DULBaseIDs               [][]byte
+	DULBaseIDsSet            bool
+	ResponsibleFlightRescuer *bool
+	TotalFlightMinutes       *int
+	ResponsiblePilotMinutes  *int
+	SecondPilotMinutes       *int
+	DoubleCommandMinutes     *int
+	FlightInstructorMinutes  *int
+	NightFlightMinutes       *int
+	IFRFlightMinutes         *int
+	Specialization           *string
+	SubSpecialization        *string
+	IsChiefPhysician         *bool
+	IsChiefTechnician        *bool
+	IsResponsibleComplaints  *bool
+	RoleLabel                *string
+	Note                     *string
+	Location                 *string
+	Postcode                 *string
+	StreetLine               *string
+	WeightKG                 *float64
+	PhotoFileID              *string
+}
+
+type CreateInput struct {
+	RoleID   []byte
+	RoleIDs  [][]byte
+	User     UserPatch
+	Profile  ProfilePatch
+	Profiles []CreateRoleProfile
+}
+
+type CreateRoleProfile struct {
+	RoleCode string
+	Patch    ProfilePatch
+}
+
+type UpdateInput struct {
+	UserID            []byte
+	User              UserPatch
+	RoleID            []byte
+	RoleIDs           [][]byte
+	UpdateRoles       bool
+	Profile           ProfilePatch
+	Profiles          []CreateRoleProfile
+	TargetProfileRole string
+}
+
+type ContactListItem struct {
+	UserID              []byte     `gorm:"column:user_id"`
+	CreatedBy           []byte     `gorm:"column:created_by"`
+	UpdatedBy           []byte     `gorm:"column:updated_by"`
+	RoleCode            string     `gorm:"column:role_code"`
+	RoleName            string     `gorm:"column:role_name"`
+	PilotCategory       string     `gorm:"column:pilot_category"`
+	Username            string     `gorm:"column:username"`
+	Email               string     `gorm:"column:email"`
+	SSOEmail            *string    `gorm:"column:sso_email"`
+	IsAdmin             bool       `gorm:"column:is_admin"`
+	FirstName           string     `gorm:"column:first_name"`
+	LastName            string     `gorm:"column:last_name"`
+	ShortName           string     `gorm:"column:short_name"`
+	LicenseNo           string     `gorm:"column:license_no"`
+	Location            string     `gorm:"column:location"`
+	MobilePhone         string     `gorm:"column:mobile_phone"`
+	ProfileAttachmentID []byte     `gorm:"column:profile_attachment_id"`
+	HasPassword         bool       `gorm:"column:has_password"`
+	SortKey             *int       `gorm:"column:sortkey"`
+	Note                string     `gorm:"column:note"`
+	IsActive            bool       `gorm:"column:is_active"`
+	CreatedAt           time.Time  `gorm:"column:created_at"`
+	UpdatedAt           time.Time  `gorm:"column:updated_at"`
+	LastLoginAt         *time.Time `gorm:"column:last_login_at"`
+	BaseRolesRaw        *string    `gorm:"column:base_roles_raw"`
+	RolesRaw            *string    `gorm:"column:roles_raw"`
+
+	PilotShortName               *string    `gorm:"column:pilot_short_name"`
+	PilotLicenseNo               *string    `gorm:"column:pilot_license_no"`
+	PilotLicenseIssuedAt         *time.Time `gorm:"column:pilot_license_issued_at"`
+	PilotLicenseExpiredAt        *time.Time `gorm:"column:pilot_license_expired_at"`
+	PilotTechnicianLicenseNo     *string    `gorm:"column:pilot_technician_license_no"`
+	PilotHasIFRQualification     *bool      `gorm:"column:pilot_has_ifr_qualification"`
+	PilotIsChiefPilot            *bool      `gorm:"column:pilot_is_chief_pilot"`
+	PilotIsDUL                   *bool      `gorm:"column:pilot_is_dul"`
+	PilotTotalFlightMinutes      *int       `gorm:"column:pilot_total_flight_minutes"`
+	PilotResponsiblePilotMinutes *int       `gorm:"column:pilot_responsible_pilot_minutes"`
+	PilotSecondPilotMinutes      *int       `gorm:"column:pilot_second_pilot_minutes"`
+	PilotDoubleCommandMinutes    *int       `gorm:"column:pilot_double_command_minutes"`
+	PilotFlightInstructorMinutes *int       `gorm:"column:pilot_flight_instructor_minutes"`
+	PilotNightFlightMinutes      *int       `gorm:"column:pilot_night_flight_minutes"`
+	PilotIFRFlightMinutes        *int       `gorm:"column:pilot_ifr_flight_minutes"`
+	PilotLocation                *string    `gorm:"column:pilot_location"`
+	PilotPostcode                *string    `gorm:"column:pilot_postcode"`
+	PilotStreetLine              *string    `gorm:"column:pilot_street_line"`
+	PilotNote                    *string    `gorm:"column:pilot_note"`
+	PilotWeightKG                *float64   `gorm:"column:pilot_weight_kg"`
+	PilotPhotoFileID             *string    `gorm:"column:pilot_photo_file_id"`
+
+	DoctorShortName         *string `gorm:"column:doctor_short_name"`
+	DoctorSpecialization    *string `gorm:"column:doctor_specialization"`
+	DoctorSubSpecialization *string `gorm:"column:doctor_sub_specialization"`
+	DoctorIsChiefPhysician  *bool   `gorm:"column:doctor_is_chief_physician"`
+	DoctorLocation          *string `gorm:"column:doctor_location"`
+	DoctorPostcode          *string `gorm:"column:doctor_postcode"`
+	DoctorStreetLine        *string `gorm:"column:doctor_street_line"`
+	DoctorNote              *string `gorm:"column:doctor_note"`
+	DoctorPhotoFileID       *string `gorm:"column:doctor_photo_file_id"`
+
+	AirRescuerShortName                *string `gorm:"column:air_rescuer_short_name"`
+	AirRescuerResponsibleFlightRescuer *bool   `gorm:"column:air_rescuer_responsible_flight_rescuer"`
+	AirRescuerLocation                 *string `gorm:"column:air_rescuer_location"`
+	AirRescuerPostcode                 *string `gorm:"column:air_rescuer_postcode"`
+	AirRescuerStreetLine               *string `gorm:"column:air_rescuer_street_line"`
+	AirRescuerNote                     *string `gorm:"column:air_rescuer_note"`
+	AirRescuerPhotoFileID              *string `gorm:"column:air_rescuer_photo_file_id"`
+
+	TechnicianShortName               *string `gorm:"column:technician_short_name"`
+	TechnicianLicenseNo               *string `gorm:"column:technician_license_no"`
+	TechnicianIsChiefTechnician       *bool   `gorm:"column:technician_is_chief_technician"`
+	TechnicianIsResponsibleComplaints *bool   `gorm:"column:technician_is_responsible_complaints"`
+	TechnicianLocation                *string `gorm:"column:technician_location"`
+	TechnicianPostcode                *string `gorm:"column:technician_postcode"`
+	TechnicianStreetLine              *string `gorm:"column:technician_street_line"`
+	TechnicianNote                    *string `gorm:"column:technician_note"`
+	TechnicianPhotoFileID             *string `gorm:"column:technician_photo_file_id"`
+
+	FlightAssistantShortName   *string `gorm:"column:flight_assistant_short_name"`
+	FlightAssistantLocation    *string `gorm:"column:flight_assistant_location"`
+	FlightAssistantPostcode    *string `gorm:"column:flight_assistant_postcode"`
+	FlightAssistantStreetLine  *string `gorm:"column:flight_assistant_street_line"`
+	FlightAssistantNote        *string `gorm:"column:flight_assistant_note"`
+	FlightAssistantPhotoFileID *string `gorm:"column:flight_assistant_photo_file_id"`
+
+	StaffShortName   *string `gorm:"column:staff_short_name"`
+	StaffRoleLabel   *string `gorm:"column:staff_role_label"`
+	StaffLocation    *string `gorm:"column:staff_location"`
+	StaffPostcode    *string `gorm:"column:staff_postcode"`
+	StaffStreetLine  *string `gorm:"column:staff_street_line"`
+	StaffNote        *string `gorm:"column:staff_note"`
+	StaffPhotoFileID *string `gorm:"column:staff_photo_file_id"`
+}
+
+type ContactBaseRole struct {
+	BaseID   []byte
+	BaseName string
+	RoleCode string
+}
diff --git a/internal/domain/contact/repository.go b/internal/domain/contact/repository.go
new file mode 100644
index 0000000..17f13ff
--- /dev/null
+++ b/internal/domain/contact/repository.go
@@ -0,0 +1,20 @@
+package contact
+
+import "context"
+
+type Repository interface {
+	ListContacts(ctx context.Context, filter ListFilter) ([]ContactListItem, int64, error)
+	GetContactByID(ctx context.Context, userID []byte) (*ContactListItem, error)
+	IsActorAdmin(ctx context.Context) (bool, error)
+	ResolveRoleCodeByID(ctx context.Context, roleID []byte) (string, error)
+	CreateContact(ctx context.Context, in CreateInput) ([]byte, error)
+	UpdateContact(ctx context.Context, in UpdateInput) error
+	DeleteContact(ctx context.Context, userID []byte) error
+	UpdateContactStatus(ctx context.Context, userID []byte, isActive bool) error
+	UpdateContactRole(ctx context.Context, userID []byte, roleCode string) error
+	UpdatePilotCategory(ctx context.Context, userID []byte, category string) error
+	UpdateLicense(ctx context.Context, userID []byte, licenseNo *string) error
+	UpdateChiefFlags(ctx context.Context, userID []byte, patch ProfilePatch) error
+	UpdateResponsibleComplaints(ctx context.Context, userID []byte, value bool) error
+	BulkUpdateStatus(ctx context.Context, userIDs [][]byte, isActive bool) (int64, error)
+}
diff --git a/internal/domain/contact/service.go b/internal/domain/contact/service.go
new file mode 100644
index 0000000..a1c9bd8
--- /dev/null
+++ b/internal/domain/contact/service.go
@@ -0,0 +1,21 @@
+package contact
+
+import "context"
+
+type Service interface {
+	ListContacts(ctx context.Context, filter ListFilter) ([]ContactListItem, int64, error)
+	GetContactByID(ctx context.Context, userID []byte) (*ContactListItem, error)
+	IsActorAdmin(ctx context.Context) (bool, error)
+	ResolveRoleCodeByID(ctx context.Context, roleID []byte) (string, error)
+	CreateContact(ctx context.Context, in CreateInput) ([]byte, error)
+	UpdateContact(ctx context.Context, in UpdateInput) error
+	DeleteContact(ctx context.Context, userID []byte) error
+	UpdateContactStatus(ctx context.Context, userID []byte, isActive bool) error
+	UpdateContactRole(ctx context.Context, userID []byte, roleCode string) error
+	UpdatePilotCategory(ctx context.Context, userID []byte, category string) error
+	UpdateLicense(ctx context.Context, userID []byte, licenseNo *string) error
+	UpdateChiefFlags(ctx context.Context, userID []byte, patch ProfilePatch) error
+	UpdateResponsibleComplaints(ctx context.Context, userID []byte, value bool) error
+	BulkUpdateStatus(ctx context.Context, userIDs [][]byte, isActive bool) (int64, error)
+	CheckSensitiveAction(ctx context.Context, userID []byte, actionToken string, action string) error
+}
diff --git a/internal/domain/dul/model.go b/internal/domain/dul/model.go
new file mode 100644
index 0000000..be358fc
--- /dev/null
+++ b/internal/domain/dul/model.go
@@ -0,0 +1,40 @@
+package dul
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+	filemanager "wucher/internal/domain/file_manager"
+
+	"wucher/internal/domain/base"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type DUL struct {
+	ID   []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	No   uint64    `gorm:"type:bigint unsigned;not null;autoIncrement;uniqueIndex;column:no"`
+	Name string    `gorm:"type:varchar(128);not null;column:name"`
+	Date time.Time `gorm:"type:date;not null;column:date"`
+	Info string    `gorm:"type:text;column:info"`
+
+	BaseID []byte     `gorm:"type:binary(16);column:base_id"`
+	Base   *base.Base `gorm:"foreignKey:BaseID;references:ID"`
+
+	Images []*filemanager.Attachment `gorm:"-"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (DUL) TableName() string { return "duls" }
+
+func (f *DUL) BeforeCreate(tx *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/dul/repository.go b/internal/domain/dul/repository.go
new file mode 100644
index 0000000..2ccc22a
--- /dev/null
+++ b/internal/domain/dul/repository.go
@@ -0,0 +1,15 @@
+package dul
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *DUL) error
+	Update(ctx context.Context, row *DUL) error
+	Delete(ctx context.Context, id []byte) error
+	GetByID(ctx context.Context, id []byte) (*DUL, error)
+	List(ctx context.Context, filter, sort string, limit, offset int, baseIDs [][]byte) ([]DUL, int64, error)
+}
+
+type TransactionalRepository interface {
+	WithTransaction(ctx context.Context, fn func(repo Repository) error) error
+}
diff --git a/internal/domain/dul/service.go b/internal/domain/dul/service.go
new file mode 100644
index 0000000..64dbc33
--- /dev/null
+++ b/internal/domain/dul/service.go
@@ -0,0 +1,11 @@
+package dul
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *DUL) error
+	Update(ctx context.Context, row *DUL) error
+	Delete(ctx context.Context, id []byte, actorID []byte) error
+	GetByID(ctx context.Context, id []byte) (*DUL, error)
+	List(ctx context.Context, filter, sort string, limit, offset int, baseIDs [][]byte) ([]DUL, int64, error)
+}
diff --git a/internal/domain/duty_roster/model.go b/internal/domain/duty_roster/model.go
new file mode 100644
index 0000000..efa4c0a
--- /dev/null
+++ b/internal/domain/duty_roster/model.go
@@ -0,0 +1,142 @@
+package dutyroster
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/base"
+	"wucher/internal/domain/takeover"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+// DutyRoster stores roster header per base and duty date.
+type DutyRoster struct {
+	ID         []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	FlightID   []byte    `gorm:"type:binary(16);index:idx_roster_flight_id,unique;column:flight_id"`
+	BaseID     []byte    `gorm:"type:binary(16);not null;index:idx_roster_base_date;column:base_id"`
+	DutyDate   time.Time `gorm:"type:date;not null;index:idx_roster_base_date;column:duty_date"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+
+	Base  *base.Base       `gorm:"foreignKey:BaseID;references:ID;-:migration"`
+	Crews []DutyRosterCrew `gorm:"foreignKey:RosterID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (DutyRoster) TableName() string { return "duty_rosters" }
+
+func (h *DutyRoster) BeforeCreate(tx *gorm.DB) error {
+	if len(h.ID) == 0 {
+		h.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type DutyRosterCrew struct {
+	ID               []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	RosterID         []byte     `gorm:"type:binary(16);not null;index:idx_roster_crew_role;index:idx_roster_crew_unique,unique;column:roster_id"`
+	UserID           []byte     `gorm:"type:binary(16);index:idx_roster_crew_unique,unique;column:user_id"`
+	TakeoverAcID     []byte     `gorm:"type:binary(16);index;column:takeover_ac_id"`
+	RoleCode         string     `gorm:"type:varchar(64);not null;index:idx_roster_crew_role;index:idx_roster_crew_unique,unique;check:chk_roster_crew_role_code,role_code IN ('pilot','doctor','rescuer','helper','other_person','air_rescuer','flight_assistant');column:role_code"`
+	CrewType         string     `gorm:"type:varchar(32);not null;default:main;index:idx_roster_crew_unique,unique;check:chk_roster_crew_type,crew_type IN ('main','additional');column:crew_type"`
+	NameLabel        string     `gorm:"type:varchar(191);index:idx_roster_crew_unique,unique;column:name_label"`
+	MobilePhone      string     `gorm:"type:varchar(64);column:mobile_phone"`
+	Email            string     `gorm:"type:varchar(191);column:email"`
+	ConfirmAt        *time.Time `gorm:"column:confirm_at"`
+	DateStart        *time.Time `gorm:"type:date;index:idx_roster_crew_unique,unique;check:chk_roster_crew_date_range,date_start IS NULL OR date_end IS NULL OR date_start <= date_end;column:date_start"`
+	DateEnd          *time.Time `gorm:"type:date;index:idx_roster_crew_unique,unique;column:date_end"`
+	ShiftStart       string     `gorm:"type:time;index:idx_roster_crew_unique,unique;column:shift_start"`
+	ShiftEnd         string     `gorm:"type:time;index:idx_roster_crew_unique,unique;column:shift_end"`
+	FlightInstructor bool       `gorm:"type:tinyint(1);not null;default:0;column:flight_instructor"`
+	LineChecker      bool       `gorm:"type:tinyint(1);not null;default:0;column:line_checker"`
+	Supervisor       bool       `gorm:"type:tinyint(1);not null;default:0;column:supervisor"`
+	Examiner         bool       `gorm:"type:tinyint(1);not null;default:0;column:examiner"`
+	CoPilot          bool       `gorm:"type:tinyint(1);not null;default:0;column:co_pilot"`
+	
+	Roster *DutyRoster `gorm:"foreignKey:RosterID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	User   *auth.User  `gorm:"foreignKey:UserID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	TakeoverAc *takeover.TakeoverAc `gorm:"foreignKey:TakeoverAcID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+
+}
+
+func (DutyRosterCrew) TableName() string { return "duty_roster_crews" }
+
+func (h *DutyRosterCrew) BeforeCreate(tx *gorm.DB) error {
+	if len(h.ID) == 0 {
+		h.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+// HeaderView is a denormalized header row for list/get responses.
+type HeaderView struct {
+	ID                    []byte
+	BaseID                []byte
+	BaseName              string
+	BaseAbbreviation      string
+	DefaultShiftStart     string
+	DefaultShiftEnd       string
+	HelicopterID          []byte
+	HelicopterType        string
+	HelicopterDesignation string
+	HelicopterIdentifier  string
+	DutyDate              time.Time
+	ShiftStart            string
+	ShiftEnd              string
+	CreatedAt             time.Time
+	CreatedBy             []byte
+	UpdatedAt             time.Time
+}
+
+// BaseView is a lightweight base projection used in roster listing.
+type BaseView struct {
+	ID               []byte
+	BaseName         string
+	BaseAbbreviation string
+}
+
+// CrewView is a denormalized crew row for list/get responses.
+type CrewView struct {
+	ID               []byte
+	RosterID         []byte
+	UserID           []byte
+	Name             string
+	Role             string
+	RoleCode         string
+	CrewType         string
+	MobilePhone      string
+	Email            string
+	DateStart        *time.Time
+	DateEnd          *time.Time
+	ShiftStart       string
+	ShiftEnd         string
+	FlightInstructor bool
+	LineChecker      bool
+	Supervisor       bool
+	Examiner         bool
+	CoPilot          bool
+}
+
+type DeletedCrewResult struct {
+	ID        []byte
+	RosterID  []byte
+	UserID    []byte
+	Name      string
+	RoleCode  string
+	CrewType  string
+	DateStart *time.Time
+	DateEnd   *time.Time
+}
diff --git a/internal/domain/duty_roster/repository.go b/internal/domain/duty_roster/repository.go
new file mode 100644
index 0000000..7949edd
--- /dev/null
+++ b/internal/domain/duty_roster/repository.go
@@ -0,0 +1,38 @@
+package dutyroster
+
+import (
+	"context"
+	"time"
+)
+
+type TxRepository interface {
+	GetRosterByID(ctx context.Context, id []byte) (*DutyRoster, error)
+	LockRosterByID(ctx context.Context, id []byte) (*DutyRoster, error)
+	CreateHeader(ctx context.Context, row *DutyRoster) error
+	UpdateHeader(ctx context.Context, row *DutyRoster) error
+	SoftDeleteHeader(ctx context.Context, id []byte, deletedBy []byte) error
+	SoftDeleteCrewsByRosterID(ctx context.Context, rosterID []byte, deletedBy []byte) error
+	ListActiveCrewsByRosterID(ctx context.Context, rosterID []byte) ([]DutyRosterCrew, error)
+	InsertCrew(ctx context.Context, row *DutyRosterCrew) error
+	CrewExists(ctx context.Context, row DutyRosterCrew) (bool, error)
+	SoftDeleteCrewByUser(ctx context.Context, rosterID []byte, roleCode, crewType string, userID, updatedBy []byte) error
+	FindRosterIDByBaseDate(ctx context.Context, baseID []byte, dutyDate time.Time) ([]byte, error)
+	FindRosterIDsByBaseDate(ctx context.Context, baseID []byte, dutyDate time.Time) ([][]byte, error)
+	MatchCrewByFilter(ctx context.Context, rosterIDs [][]byte, crew DutyRosterCrew) ([]DeletedCrewResult, error)
+	SoftDeleteCrewRows(ctx context.Context, rows []DeletedCrewResult, deletedBy []byte) error
+	SoftDeleteCrewForDate(ctx context.Context, baseID []byte, dutyDate time.Time, crew DutyRosterCrew, updatedBy []byte) error
+	HardDeleteHeader(ctx context.Context, id []byte) error
+	HardDeleteCrewsByRosterID(ctx context.Context, rosterID []byte) error
+}
+
+type Repository interface {
+	InTx(ctx context.Context, fn func(txRepo TxRepository) error) error
+	GetBaseDefaultShift(ctx context.Context, baseID []byte, baseType string) (string, error)
+	GetHeaderByID(ctx context.Context, id []byte) (*HeaderView, error)
+	GetHeaderByIDByBaseType(ctx context.Context, id []byte, baseType string) (*HeaderView, error)
+	GetCrewsByRosterIDs(ctx context.Context, rosterIDs [][]byte) ([]CrewView, error)
+	ListHeadersByRange(ctx context.Context, baseID []byte, from, to time.Time) ([]HeaderView, error)
+	ListHeadersByRangeByBaseType(ctx context.Context, baseID []byte, from, to time.Time, baseType string) ([]HeaderView, error)
+	ListHEMSBases(ctx context.Context, baseID []byte) ([]BaseView, error)
+	ListBasesByType(ctx context.Context, baseID []byte, baseType string) ([]BaseView, error)
+}
diff --git a/internal/domain/duty_roster/service.go b/internal/domain/duty_roster/service.go
new file mode 100644
index 0000000..88a4db8
--- /dev/null
+++ b/internal/domain/duty_roster/service.go
@@ -0,0 +1,23 @@
+package dutyroster
+
+import (
+	"context"
+	"time"
+)
+
+type Service interface {
+	Create(ctx context.Context, row *DutyRoster, crews []DutyRosterCrew) error
+	Update(ctx context.Context, row *DutyRoster, crews []DutyRosterCrew) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	HardDelete(ctx context.Context, id []byte) error
+	DeleteCrews(ctx context.Context, id []byte, crews []DutyRosterCrew, deletedBy []byte) ([]DeletedCrewResult, error)
+	GetBaseDefaultShift(ctx context.Context, baseID []byte, baseType string) (string, error)
+	ResolveBaseDefaultShiftRange(ctx context.Context, baseID []byte, baseType string) (string, string, error)
+	GetHeaderByID(ctx context.Context, id []byte) (*HeaderView, error)
+	GetHeaderByIDByBaseType(ctx context.Context, id []byte, baseType string) (*HeaderView, error)
+	GetCrewsByRosterIDs(ctx context.Context, rosterIDs [][]byte) ([]CrewView, error)
+	ListHeadersByRange(ctx context.Context, baseID []byte, from, to time.Time) ([]HeaderView, error)
+	ListHeadersByRangeByBaseType(ctx context.Context, baseID []byte, from, to time.Time, baseType string) ([]HeaderView, error)
+	ListHEMSBases(ctx context.Context, baseID []byte) ([]BaseView, error)
+	ListBasesByType(ctx context.Context, baseID []byte, baseType string) ([]BaseView, error)
+}
diff --git a/internal/domain/easa_release/errors.go b/internal/domain/easa_release/errors.go
new file mode 100644
index 0000000..825bff8
--- /dev/null
+++ b/internal/domain/easa_release/errors.go
@@ -0,0 +1,9 @@
+package easarelease
+
+import "errors"
+
+var (
+	ErrNotFound          = errors.New("easa release not found")
+	ErrAlreadySigned     = errors.New("easa release already signed")
+	ErrIncompleteForSign = errors.New("easa release required fields are incomplete")
+)
diff --git a/internal/domain/easa_release/model.go b/internal/domain/easa_release/model.go
new file mode 100644
index 0000000..f9c7c8f
--- /dev/null
+++ b/internal/domain/easa_release/model.go
@@ -0,0 +1,77 @@
+package easarelease
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	complaint "wucher/internal/domain/complaint"
+	flightdomain "wucher/internal/domain/flight"
+	helicopter "wucher/internal/domain/helicopter"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type EASARelease struct {
+	ID           []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	HelicopterID []byte `gorm:"type:binary(16);not null;index;column:helicopter_id"`
+
+	// ComplaintID scopes the release to the specific complaint it closes (optional).
+	// When set, the release is fetched via get-by-complaint and closes that complaint.
+	// When NULL the release is standalone (aircraft cleared with no open defect).
+	ComplaintID []byte `gorm:"type:binary(16);index;column:complaint_id"`
+
+	// FlightID — optional flight context. Retained for the standalone (no-complaint)
+	// sign-off gate, which is still flight-scoped. Not required for complaint releases.
+	FlightID []byte `gorm:"type:binary(16);index;column:flight_id"`
+
+	EASADate                   *time.Time `gorm:"type:date;column:easa_date"`
+	EASAACHours                *string    `gorm:"type:varchar(20);column:easa_ac_hours"`
+	EASALocation               *string    `gorm:"type:varchar(255);column:easa_location"`
+	EASAWONo                   *string    `gorm:"type:varchar(100);column:easa_wo_no"`
+	EASAMaintManualRevAirframe *string    `gorm:"type:varchar(100);column:easa_maint_manual_rev_airframe"`
+	EASAMaintManualRevEngine   *string    `gorm:"type:varchar(100);column:easa_maint_manual_rev_engine"`
+	EASASignerID               *string    `gorm:"type:varchar(100);column:easa_signer_id"`
+	EASAPermitNo               *string    `gorm:"type:varchar(100);column:easa_permit_no"`
+
+	SignedAt *time.Time `gorm:"type:datetime(3);column:signed_at"`
+	SignedBy []byte     `gorm:"type:binary(16);column:signed_by"`
+
+	Helicopter *helicopter.Helicopter `gorm:"foreignKey:HelicopterID;references:ID"`
+	Flight     *flightdomain.Flight   `gorm:"foreignKey:FlightID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	Complaint  *complaint.Complaint   `gorm:"foreignKey:ComplaintID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+
+	CreatedAt time.Time  `gorm:"type:datetime(3);column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"type:datetime(3);column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"type:datetime(3);index;column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (EASARelease) TableName() string { return "easa_releases" }
+
+func (e *EASARelease) BeforeCreate(_ *gorm.DB) error {
+	if len(e.ID) == 0 {
+		e.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+func (e *EASARelease) IsSigned() bool { return e != nil && e.SignedAt != nil }
+
+func (e *EASARelease) IsActive() bool { return e.IsSigned() }
+
+// MissingSignFields reports which mandatory fields are still empty for signing.
+// Only the signer is required — it is auto-filled from the duty pilot. The other
+// document fields (date, A/C hours, location, WO no, manual revisions) are
+// adjustable free text and optional, so a release can be signed without them.
+func (e *EASARelease) MissingSignFields() []string {
+	if e == nil {
+		return []string{"easa_signer_id"}
+	}
+	var missing []string
+	if e.EASASignerID == nil || *e.EASASignerID == "" {
+		missing = append(missing, "easa_signer_id")
+	}
+	return missing
+}
diff --git a/internal/domain/easa_release/model_test.go b/internal/domain/easa_release/model_test.go
new file mode 100644
index 0000000..fb05473
--- /dev/null
+++ b/internal/domain/easa_release/model_test.go
@@ -0,0 +1,83 @@
+package easarelease
+
+import (
+	"reflect"
+	"testing"
+	"time"
+)
+
+func str(s string) *string { return &s }
+
+func TestEASAReleaseIsSigned(t *testing.T) {
+	now := time.Now()
+	if (&EASARelease{}).IsSigned() {
+		t.Fatal("unsigned release reported as signed")
+	}
+	if !(&EASARelease{SignedAt: &now}).IsSigned() {
+		t.Fatal("signed release reported as unsigned")
+	}
+	var nilRel *EASARelease
+	if nilRel.IsSigned() {
+		t.Fatal("nil release reported as signed")
+	}
+}
+
+func TestEASAReleaseMissingSignFields(t *testing.T) {
+	// Only the auto-filled signer is required to sign; the adjustable document
+	// fields (date, A/C hours, location, WO no, manual revisions) are optional.
+	onlySigner := []string{"easa_signer_id"}
+	now := time.Now()
+
+	cases := []struct {
+		name string
+		row  *EASARelease
+		want []string
+	}{
+		{name: "nil requires signer", row: nil, want: onlySigner},
+		{name: "empty requires signer", row: &EASARelease{}, want: onlySigner},
+		{name: "signer present lists none", row: &EASARelease{EASASignerID: str("019d61db-53c6-7280-87ec-e65f205c6d3b")}, want: nil},
+		{name: "other fields empty but signer set lists none", row: &EASARelease{EASASignerID: str("019d61db-53c6-7280-87ec-e65f205c6d3b"), EASADate: &now}, want: nil},
+		{name: "blank signer counts as missing", row: &EASARelease{EASASignerID: str("")}, want: onlySigner},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := tc.row.MissingSignFields()
+			if len(got) == 0 && len(tc.want) == 0 {
+				return
+			}
+			if !reflect.DeepEqual(got, tc.want) {
+				t.Fatalf("MissingSignFields() = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestEASAReleaseIsActiveAndTableName(t *testing.T) {
+	if (EASARelease{}).TableName() != "easa_releases" {
+		t.Fatalf("unexpected table name")
+	}
+	now := time.Now()
+	if (&EASARelease{}).IsActive() {
+		t.Fatal("unsigned release must not be active")
+	}
+	if !(&EASARelease{SignedAt: &now}).IsActive() {
+		t.Fatal("signed release must be active")
+	}
+}
+
+func TestEASAReleaseBeforeCreate(t *testing.T) {
+	e := &EASARelease{}
+	if err := e.BeforeCreate(nil); err != nil {
+		t.Fatalf("BeforeCreate err: %v", err)
+	}
+	if len(e.ID) == 0 {
+		t.Fatal("BeforeCreate should set ID")
+	}
+	prev := string(e.ID)
+	if err := e.BeforeCreate(nil); err != nil {
+		t.Fatalf("BeforeCreate err: %v", err)
+	}
+	if string(e.ID) != prev {
+		t.Fatal("BeforeCreate must not overwrite an existing ID")
+	}
+}
diff --git a/internal/domain/easa_release/repository.go b/internal/domain/easa_release/repository.go
new file mode 100644
index 0000000..396ba01
--- /dev/null
+++ b/internal/domain/easa_release/repository.go
@@ -0,0 +1,16 @@
+package easarelease
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *EASARelease) error
+	Update(ctx context.Context, row *EASARelease) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*EASARelease, error)
+	GetByFlightID(ctx context.Context, flightID []byte) (*EASARelease, error)
+	GetByComplaintID(ctx context.Context, complaintID []byte) (*EASARelease, error)
+	ListByHelicopter(ctx context.Context, helicopterID []byte) ([]EASARelease, error)
+	GetLatestByHelicopter(ctx context.Context, helicopterID []byte) (*EASARelease, error)
+	GetActiveByHelicopter(ctx context.Context, helicopterID []byte) (*EASARelease, error)
+	VoidByID(ctx context.Context, id []byte, reason string, actor []byte) error
+}
diff --git a/internal/domain/easa_release/service.go b/internal/domain/easa_release/service.go
new file mode 100644
index 0000000..87d866a
--- /dev/null
+++ b/internal/domain/easa_release/service.go
@@ -0,0 +1,16 @@
+package easarelease
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *EASARelease) error
+	Update(ctx context.Context, row *EASARelease) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*EASARelease, error)
+	GetByFlightID(ctx context.Context, flightID []byte) (*EASARelease, error)
+	GetByComplaintID(ctx context.Context, complaintID []byte) (*EASARelease, error)
+	ListByHelicopter(ctx context.Context, helicopterID []byte) ([]EASARelease, error)
+	GetActiveByHelicopter(ctx context.Context, helicopterID []byte) (*EASARelease, error)
+	Sign(ctx context.Context, id []byte, signerID []byte) error
+	Amend(ctx context.Context, currentID []byte, reason string, actor []byte) (newID []byte, err error)
+}
diff --git a/internal/domain/facility/model.go b/internal/domain/facility/model.go
new file mode 100644
index 0000000..d4b2097
--- /dev/null
+++ b/internal/domain/facility/model.go
@@ -0,0 +1,38 @@
+package facility
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+// Facility stores configurable HEMS / Dry Lease (and other) operational equipment rows.
+type Facility struct {
+	ID        []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	Category  string     `gorm:"type:varchar(64);index;not null;column:category"`
+	Name      string     `gorm:"type:varchar(150);not null;column:name"`
+	Type      string     `gorm:"type:varchar(100);not null;column:type"`
+	SortKey   *int       `gorm:"column:sortkey"`
+	Length    string     `gorm:"type:varchar(64);column:length"`
+	Weight    string     `gorm:"type:varchar(64);column:weight"`
+	Electric  string     `gorm:"type:varchar(255);not null;default:'';column:electric"`
+	Note      string     `gorm:"type:text;column:note"`
+	IsActive  bool       `gorm:"type:tinyint(1);index;not null;default:1;column:is_active"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+	CreatedAt time.Time
+	UpdatedAt time.Time
+	DeletedAt *time.Time `gorm:"column:deleted_at;index"`
+}
+
+func (Facility) TableName() string { return "facilities" }
+
+func (f *Facility) BeforeCreate(tx *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/facility/repository.go b/internal/domain/facility/repository.go
new file mode 100644
index 0000000..15e851a
--- /dev/null
+++ b/internal/domain/facility/repository.go
@@ -0,0 +1,11 @@
+package facility
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, facility *Facility) error
+	Update(ctx context.Context, facility *Facility) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Facility, error)
+	List(ctx context.Context, filter, category, sort string, limit, offset int) ([]Facility, int64, error)
+}
diff --git a/internal/domain/facility/service.go b/internal/domain/facility/service.go
new file mode 100644
index 0000000..18091d9
--- /dev/null
+++ b/internal/domain/facility/service.go
@@ -0,0 +1,11 @@
+package facility
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, facility *Facility) error
+	Update(ctx context.Context, facility *Facility) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Facility, error)
+	List(ctx context.Context, filter, category, sort string, limit, offset int) ([]Facility, int64, error)
+}
diff --git a/internal/domain/federal_state/model.go b/internal/domain/federal_state/model.go
new file mode 100644
index 0000000..1c70f18
--- /dev/null
+++ b/internal/domain/federal_state/model.go
@@ -0,0 +1,37 @@
+package federal_state
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/land"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type FederalState struct {
+	ID       []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	LandID   []byte `gorm:"type:binary(16);column:land_id"`
+	Name     string `gorm:"type:varchar(128);not null;column:name"`
+	Note     string `gorm:"type:text;column:note"`
+	SortKey  *int   `gorm:"column:sortkey"`
+	IsActive bool   `gorm:"type:tinyint(1);index;not null;default:1;column:is_active"`
+
+	Land *land.Land `gorm:"foreignKey:LandID;references:ID"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (FederalState) TableName() string { return "federal_states" }
+
+func (f *FederalState) BeforeCreate(tx *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/federal_state/model_test.go b/internal/domain/federal_state/model_test.go
new file mode 100644
index 0000000..8ebda3e
--- /dev/null
+++ b/internal/domain/federal_state/model_test.go
@@ -0,0 +1,37 @@
+package federal_state
+
+import (
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func TestFederalStateTableName(t *testing.T) {
+	var m FederalState
+	if got := m.TableName(); got != "federal_states" {
+		t.Fatalf("expected table name federal_states, got %q", got)
+	}
+}
+
+func TestFederalStateBeforeCreate(t *testing.T) {
+	t.Run("generates id when empty", func(t *testing.T) {
+		m := &FederalState{}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(m.ID) == 0 {
+			t.Fatalf("expected id to be generated")
+		}
+	})
+
+	t.Run("keeps existing id", func(t *testing.T) {
+		existing := []byte("already-set-id")
+		m := &FederalState{ID: append([]byte(nil), existing...)}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if string(m.ID) != string(existing) {
+			t.Fatalf("expected existing id to stay unchanged")
+		}
+	})
+}
diff --git a/internal/domain/federal_state/repository.go b/internal/domain/federal_state/repository.go
new file mode 100644
index 0000000..8922276
--- /dev/null
+++ b/internal/domain/federal_state/repository.go
@@ -0,0 +1,11 @@
+package federal_state
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *FederalState) error
+	Update(ctx context.Context, row *FederalState) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*FederalState, error)
+	List(ctx context.Context, filter, sort string, limit, offset int, landID []byte, landName string) ([]FederalState, int64, error)
+}
diff --git a/internal/domain/federal_state/service.go b/internal/domain/federal_state/service.go
new file mode 100644
index 0000000..699ac2f
--- /dev/null
+++ b/internal/domain/federal_state/service.go
@@ -0,0 +1,11 @@
+package federal_state
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *FederalState) error
+	Update(ctx context.Context, row *FederalState) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*FederalState, error)
+	List(ctx context.Context, filter, sort string, limit, offset int, landID []byte, landName string) ([]FederalState, int64, error)
+}
diff --git a/internal/domain/file_manager/file_processing_outbox.go b/internal/domain/file_manager/file_processing_outbox.go
new file mode 100644
index 0000000..95e07f3
--- /dev/null
+++ b/internal/domain/file_manager/file_processing_outbox.go
@@ -0,0 +1,152 @@
+package filemanager
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	FileProcessingOutboxStatusPending    = "pending"
+	FileProcessingOutboxStatusProcessing = "processing"
+	FileProcessingOutboxStatusPublished  = "published"
+	FileProcessingOutboxStatusDead       = "dead"
+	FileProcessingOutboxKind             = "file_manager.processing"
+)
+
+type FileProcessingOutboundMessage struct {
+	ID              string
+	Body            []byte
+	Attributes      map[string]string
+	MessageGroupID  string
+	DeduplicationID string
+}
+
+type FileProcessingOutboxMessage struct {
+	ID              []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	MessageID       string     `gorm:"type:varchar(64);uniqueIndex;not null;column:message_id"`
+	Kind            string     `gorm:"type:varchar(64);index;not null;column:kind"`
+	JobType         string     `gorm:"type:varchar(64);index;not null;column:job_type"`
+	Body            []byte     `gorm:"type:longblob;not null;column:body"`
+	Attributes      []byte     `gorm:"type:longblob;column:attributes"`
+	MessageGroupID  string     `gorm:"type:varchar(128);column:message_group_id"`
+	DeduplicationID string     `gorm:"type:varchar(128);column:deduplication_id"`
+	Status          string     `gorm:"type:varchar(32);index;not null;column:status"`
+	Attempts        int        `gorm:"not null;default:0;column:attempts"`
+	AvailableAt     time.Time  `gorm:"index;not null;column:available_at"`
+	LockedAt        *time.Time `gorm:"index;column:locked_at"`
+	LockedBy        string     `gorm:"type:varchar(64);column:locked_by"`
+	PublishedAt     *time.Time `gorm:"column:published_at"`
+	LastError       string     `gorm:"type:text;column:last_error"`
+	CorrelationID   string     `gorm:"type:varchar(64);index;column:correlation_id"`
+	TraceID         string     `gorm:"type:varchar(64);index;column:trace_id"`
+	CreatedAt       time.Time
+	UpdatedAt       time.Time
+}
+
+func (FileProcessingOutboxMessage) TableName() string {
+	return "file_processing_outbox_messages"
+}
+
+func (m *FileProcessingOutboxMessage) BeforeCreate(_ *gorm.DB) error {
+	if len(m.ID) == 0 {
+		m.ID = uuidv7.MustBytes()
+	}
+	if strings.TrimSpace(m.Status) == "" {
+		m.Status = FileProcessingOutboxStatusPending
+	}
+	if m.AvailableAt.IsZero() {
+		m.AvailableAt = time.Now().UTC()
+	}
+	return nil
+}
+
+func NewFileProcessingOutboxMessage(now time.Time, message *FileProcessingOutboundMessage) (*FileProcessingOutboxMessage, error) {
+	if message == nil {
+		return nil, errors.New("outbound message is required")
+	}
+	if strings.TrimSpace(message.ID) == "" {
+		return nil, errors.New("outbound message id is required")
+	}
+	if len(message.Body) == 0 {
+		return nil, errors.New("outbound message body is required")
+	}
+	attributes, err := json.Marshal(message.Attributes)
+	if err != nil {
+		return nil, err
+	}
+	if now.IsZero() {
+		now = time.Now().UTC()
+	}
+
+	kind := strings.TrimSpace(message.Attributes["message_kind"])
+	if kind == "" {
+		kind = FileProcessingOutboxKind
+	}
+	jobType := strings.TrimSpace(message.Attributes["job_type"])
+	if jobType == "" {
+		jobType = "file_processing"
+	}
+
+	return &FileProcessingOutboxMessage{
+		MessageID:       strings.TrimSpace(message.ID),
+		Kind:            kind,
+		JobType:         jobType,
+		Body:            append([]byte(nil), message.Body...),
+		Attributes:      append([]byte(nil), attributes...),
+		MessageGroupID:  strings.TrimSpace(message.MessageGroupID),
+		DeduplicationID: strings.TrimSpace(message.DeduplicationID),
+		Status:          FileProcessingOutboxStatusPending,
+		AvailableAt:     now.UTC(),
+		CorrelationID:   strings.TrimSpace(message.Attributes["correlation_id"]),
+		TraceID:         strings.TrimSpace(message.Attributes["trace_id"]),
+	}, nil
+}
+
+func (m *FileProcessingOutboxMessage) OutboundMessage() (*FileProcessingOutboundMessage, error) {
+	if m == nil {
+		return nil, errors.New("file processing outbox message is required")
+	}
+	attributes := map[string]string{}
+	if len(m.Attributes) > 0 {
+		if err := json.Unmarshal(m.Attributes, &attributes); err != nil {
+			return nil, err
+		}
+	}
+	if strings.TrimSpace(m.MessageID) == "" {
+		return nil, errors.New("message id is required")
+	}
+	if len(m.Body) == 0 {
+		return nil, errors.New("message body is required")
+	}
+	return &FileProcessingOutboundMessage{
+		ID:              m.MessageID,
+		Body:            append([]byte(nil), m.Body...),
+		Attributes:      attributes,
+		MessageGroupID:  strings.TrimSpace(m.MessageGroupID),
+		DeduplicationID: strings.TrimSpace(m.DeduplicationID),
+	}, nil
+}
+
+type FileProcessingOutboxWriter interface {
+	CreateFileProcessingOutboxMessage(ctx context.Context, message *FileProcessingOutboxMessage) error
+}
+
+type FileProcessingOutboxRepository interface {
+	FileProcessingOutboxWriter
+	ClaimPendingFileProcessingOutboxMessages(ctx context.Context, limit int, now time.Time, lockTTL time.Duration, workerID string) ([]FileProcessingOutboxMessage, error)
+	MarkFileProcessingOutboxMessagePublished(ctx context.Context, id []byte, publishedAt time.Time) error
+	MarkFileProcessingOutboxMessageRetry(ctx context.Context, id []byte, availableAt time.Time, lastErr string) error
+	MarkFileProcessingOutboxMessageDead(ctx context.Context, id []byte, failedAt time.Time, lastErr string) error
+	CountPendingFileProcessingOutboxMessages(ctx context.Context, now time.Time) (int64, error)
+}
+
+type FileTransactionalRepository interface {
+	WithTransaction(ctx context.Context, fn func(repo FileRepository, outbox FileProcessingOutboxWriter) error) error
+}
diff --git a/internal/domain/file_manager/model_attachment.go b/internal/domain/file_manager/model_attachment.go
new file mode 100644
index 0000000..50f8b79
--- /dev/null
+++ b/internal/domain/file_manager/model_attachment.go
@@ -0,0 +1,47 @@
+package filemanager
+
+import (
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type Attachment struct {
+	ID         []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	FileID     []byte    `gorm:"type:binary(16);not null;column:file_id;index:idx_attachments_file_id;uniqueIndex:uq_attachments_ref_file,priority:3"`
+	RefType    string    `gorm:"type:varchar(64);not null;column:ref_type;index:idx_attachments_ref_sort,priority:1;index:idx_attachments_ref_category,priority:1;uniqueIndex:uq_attachments_ref_file,priority:1"`
+	RefID      string    `gorm:"type:varchar(191);not null;column:ref_id;index:idx_attachments_ref_sort,priority:2;index:idx_attachments_ref_category,priority:2;uniqueIndex:uq_attachments_ref_file,priority:2"`
+	Category   *string   `gorm:"type:varchar(64);column:category;index:idx_attachments_ref_category,priority:3"`
+	SortOrder  int       `gorm:"type:int;not null;default:0;column:sort_order;index:idx_attachments_ref_sort,priority:3"`
+	IsPrimary  bool      `gorm:"type:boolean;not null;default:false;column:is_primary"`
+	AttachedBy []byte    `gorm:"type:binary(16);column:attached_by"`
+	CreatedAt  time.Time `gorm:"column:created_at;index:idx_attachments_ref_sort,priority:4"`
+	UpdatedAt  time.Time `gorm:"column:updated_at"`
+	File       *File     `gorm:"foreignKey:FileID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (Attachment) TableName() string { return "attachments" }
+
+func (a *Attachment) BeforeCreate(_ *gorm.DB) error {
+	if len(a.ID) == 0 {
+		a.ID = uuidv7.MustBytes()
+	}
+	if trimmed := strings.TrimSpace(a.RefType); trimmed != "" {
+		a.RefType = trimmed
+	}
+	if trimmed := strings.TrimSpace(a.RefID); trimmed != "" {
+		a.RefID = trimmed
+	}
+	if a.Category != nil {
+		value := strings.TrimSpace(*a.Category)
+		if value == "" {
+			a.Category = nil
+		} else {
+			a.Category = &value
+		}
+	}
+	return nil
+}
diff --git a/internal/domain/file_manager/model_file.go b/internal/domain/file_manager/model_file.go
new file mode 100644
index 0000000..ceb7022
--- /dev/null
+++ b/internal/domain/file_manager/model_file.go
@@ -0,0 +1,149 @@
+package filemanager
+
+import (
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	FileStatusUploaded   = "uploaded"
+	FileStatusProcessing = "processing"
+	FileStatusValidated  = "validated"
+	FileStatusFailed     = "failed"
+	FileStatusReady      = "ready"
+	FileStatusTrashed    = "trashed"
+
+	FileLifecycleStatusTemp          = "temp"
+	FileLifecycleStatusDraft         = "draft"
+	FileLifecycleStatusActive        = "active"
+	FileLifecycleStatusFinal         = "final"
+	FileLifecycleStatusOrphanPending = "orphan_pending"
+	FileLifecycleStatusDeleted       = "deleted"
+)
+
+type File struct {
+	ID                     []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	FolderID               []byte     `gorm:"type:binary(16);not null;column:folder_id;index:idx_file_files_folder_active,priority:1;index:uq_file_files_folder_name_slot,priority:1"`
+	Name                   string     `gorm:"type:varchar(255);not null;column:name"`
+	NameNormalized         string     `gorm:"type:varchar(255);not null;column:name_normalized;index:uq_file_files_folder_name_slot,priority:2"`
+	Extension              string     `gorm:"type:varchar(32);column:extension"`
+	SizeBytes              int64      `gorm:"type:bigint unsigned;not null;default:0;column:size_bytes"`
+	MimeType               string     `gorm:"type:varchar(255);not null;column:mime_type"`
+	Bucket                 string     `gorm:"type:varchar(128);not null;column:bucket"`
+	ObjectKey              string     `gorm:"type:varchar(512);not null;column:object_key;uniqueIndex:uq_file_files_object_key"`
+	ObjectVersion          string     `gorm:"type:varchar(128);column:object_version"`
+	ETag                   string     `gorm:"type:varchar(128);column:etag"`
+	ThumbnailMimeType      *string    `gorm:"type:varchar(255);column:thumbnail_mime_type"`
+	ThumbnailSizeBytes     int64      `gorm:"type:bigint unsigned;column:thumbnail_size_bytes"`
+	ThumbnailBucket        *string    `gorm:"type:varchar(128);column:thumbnail_bucket"`
+	ThumbnailObjectKey     *string    `gorm:"type:varchar(512);column:thumbnail_object_key;uniqueIndex:uq_file_files_thumbnail_object_key"`
+	ThumbnailObjectVersion *string    `gorm:"type:varchar(128);column:thumbnail_object_version"`
+	ThumbnailETag          *string    `gorm:"type:varchar(128);column:thumbnail_etag"`
+	PreviewMimeType        *string    `gorm:"type:varchar(255);column:preview_mime_type"`
+	PreviewSizeBytes       int64      `gorm:"type:bigint unsigned;column:preview_size_bytes"`
+	PreviewBucket          *string    `gorm:"type:varchar(128);column:preview_bucket"`
+	PreviewObjectKey       *string    `gorm:"type:varchar(512);column:preview_object_key;uniqueIndex:uq_file_files_preview_object_key"`
+	PreviewObjectVersion   *string    `gorm:"type:varchar(128);column:preview_object_version"`
+	PreviewETag            *string    `gorm:"type:varchar(128);column:preview_etag"`
+	ChecksumSHA256         string     `gorm:"type:char(64);column:checksum_sha256"`
+	IsTemplate             bool       `gorm:"column:is_template;not null;default:false"`
+	TemplateUUID           []byte     `gorm:"type:binary(16);column:template_uuid;index:idx_file_files_template_takeover,priority:1"`
+	TakeoverID             []byte     `gorm:"type:binary(16);column:takeover_id;index:idx_file_files_template_takeover,priority:2"`
+	Status                 string     `gorm:"type:varchar(32);not null;default:'uploaded';column:status;index:idx_file_files_status_updated,priority:1"`
+	ProcessingStartedAt    *time.Time `gorm:"column:processing_started_at"`
+	ProcessedAt            *time.Time `gorm:"column:processed_at"`
+	ValidatedAt            *time.Time `gorm:"column:validated_at"`
+	FailedAt               *time.Time `gorm:"column:failed_at"`
+	FailureReason          string     `gorm:"type:text;column:failure_reason"`
+	UploadError            string     `gorm:"type:text;column:upload_error"`
+	NameSlot               string     `gorm:"type:char(36);not null;default:'live';column:name_slot;index:uq_file_files_folder_name_slot,priority:3"`
+	CreatedAt              time.Time  `gorm:"column:created_at"`
+	CreatedBy              []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt              time.Time  `gorm:"column:updated_at;index:idx_file_files_status_updated,priority:2"`
+	UpdatedBy              []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt              *time.Time `gorm:"column:deleted_at;index:idx_file_files_folder_active,priority:2"`
+	DeletedBy              []byte     `gorm:"type:binary(16);column:deleted_by"`
+	TrashedAt              *time.Time `gorm:"column:trashed_at"`
+	PurgeAt                *time.Time `gorm:"column:purge_at;index:idx_file_files_purge_at"`
+	LifecycleStatus        string     `gorm:"type:varchar(32);not null;default:'temp';column:lifecycle_status;index:idx_file_files_lifecycle_status_orphaned,priority:1"`
+	AttachedAt             *time.Time `gorm:"column:attached_at"`
+	OrphanedAt             *time.Time `gorm:"column:orphaned_at;index:idx_file_files_lifecycle_status_orphaned,priority:2"`
+	LifecycleDeletedAt     *time.Time `gorm:"column:lifecycle_deleted_at"`
+	WOPILockID             string     `gorm:"type:varchar(128);column:wopi_lock_id"`
+	WOPILockJTI            string     `gorm:"type:varchar(128);column:wopi_lock_jti"`
+	WOPILockedAt           *time.Time `gorm:"column:wopi_locked_at"`
+	WOPILockExpiresAt      *time.Time `gorm:"column:wopi_lock_expires_at"`
+
+	Folder *Folder `gorm:"foreignKey:FolderID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:RESTRICT"`
+}
+
+func (File) TableName() string { return "file_files" }
+
+func (f *File) BeforeCreate(tx *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+func NormalizeFileStatus(status string) string {
+	s := strings.ToLower(strings.TrimSpace(status))
+	switch s {
+	case "pending":
+		return FileStatusUploaded
+	case "uploading":
+		return FileStatusProcessing
+	default:
+		return s
+	}
+}
+
+func IsKnownFileStatus(status string) bool {
+	switch NormalizeFileStatus(status) {
+	case FileStatusUploaded, FileStatusProcessing, FileStatusValidated, FileStatusFailed, FileStatusReady, FileStatusTrashed:
+		return true
+	default:
+		return false
+	}
+}
+
+func CanTransitionFileStatus(fromStatus, toStatus string) bool {
+	from := NormalizeFileStatus(fromStatus)
+	to := NormalizeFileStatus(toStatus)
+
+	switch from {
+	case FileStatusUploaded:
+		return to == FileStatusProcessing || to == FileStatusFailed
+	case FileStatusProcessing:
+		return to == FileStatusValidated || to == FileStatusFailed
+	case FileStatusValidated:
+		return to == FileStatusReady || to == FileStatusFailed
+	case FileStatusReady:
+		return to == FileStatusTrashed
+	default:
+		return false
+	}
+}
+
+func NormalizeFileLifecycleStatus(status string) string {
+	s := strings.ToLower(strings.TrimSpace(status))
+	switch s {
+	case "":
+		return FileLifecycleStatusTemp
+	default:
+		return s
+	}
+}
+
+func IsKnownFileLifecycleStatus(status string) bool {
+	switch NormalizeFileLifecycleStatus(status) {
+	case FileLifecycleStatusTemp, FileLifecycleStatusDraft, FileLifecycleStatusActive, FileLifecycleStatusFinal, FileLifecycleStatusOrphanPending, FileLifecycleStatusDeleted:
+		return true
+	default:
+		return false
+	}
+}
diff --git a/internal/domain/file_manager/model_file_test.go b/internal/domain/file_manager/model_file_test.go
new file mode 100644
index 0000000..bb6277e
--- /dev/null
+++ b/internal/domain/file_manager/model_file_test.go
@@ -0,0 +1,123 @@
+package filemanager
+
+import (
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func TestFileTableName(t *testing.T) {
+	var m File
+	if got := m.TableName(); got != "file_files" {
+		t.Fatalf("table name mismatch: got %s", got)
+	}
+}
+
+func TestFileBeforeCreate(t *testing.T) {
+	t.Run("assigns uuid when missing", func(t *testing.T) {
+		m := &File{}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("before create error: %v", err)
+		}
+		if len(m.ID) != 16 {
+			t.Fatalf("expected 16-byte id, got %d", len(m.ID))
+		}
+	})
+
+	t.Run("keeps existing id", func(t *testing.T) {
+		id := make([]byte, 16)
+		for i := range id {
+			id[i] = byte(i + 1)
+		}
+		m := &File{ID: append([]byte(nil), id...)}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("before create error: %v", err)
+		}
+		for i := range id {
+			if m.ID[i] != id[i] {
+				t.Fatalf("id changed at %d: got %d want %d", i, m.ID[i], id[i])
+			}
+		}
+	})
+}
+
+func TestNormalizeFileStatus(t *testing.T) {
+	cases := map[string]string{
+		"uploaded":   FileStatusUploaded,
+		"processing": FileStatusProcessing,
+		"validated":  FileStatusValidated,
+		"failed":     FileStatusFailed,
+		"ready":      FileStatusReady,
+		"trashed":    FileStatusTrashed,
+		" pending ":  FileStatusUploaded,
+		"UPLOADING":  FileStatusProcessing,
+		"":           "",
+	}
+
+	for in, want := range cases {
+		if got := NormalizeFileStatus(in); got != want {
+			t.Fatalf("NormalizeFileStatus(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestCanTransitionFileStatus(t *testing.T) {
+	valid := [][2]string{
+		{FileStatusUploaded, FileStatusProcessing},
+		{FileStatusUploaded, FileStatusFailed},
+		{FileStatusProcessing, FileStatusValidated},
+		{FileStatusProcessing, FileStatusFailed},
+		{FileStatusValidated, FileStatusReady},
+		{FileStatusValidated, FileStatusFailed},
+		{FileStatusReady, FileStatusTrashed},
+	}
+	for i := range valid {
+		if !CanTransitionFileStatus(valid[i][0], valid[i][1]) {
+			t.Fatalf("expected valid transition %s -> %s", valid[i][0], valid[i][1])
+		}
+	}
+
+	invalid := [][2]string{
+		{FileStatusUploaded, FileStatusReady},
+		{FileStatusFailed, FileStatusReady},
+		{FileStatusTrashed, FileStatusProcessing},
+		{FileStatusReady, FileStatusValidated},
+	}
+	for i := range invalid {
+		if CanTransitionFileStatus(invalid[i][0], invalid[i][1]) {
+			t.Fatalf("expected invalid transition %s -> %s", invalid[i][0], invalid[i][1])
+		}
+	}
+}
+
+func TestNormalizeFileLifecycleStatus(t *testing.T) {
+	cases := map[string]string{
+		"":               FileLifecycleStatusTemp,
+		" temp ":         FileLifecycleStatusTemp,
+		"ACTIVE":         FileLifecycleStatusActive,
+		"orphan_pending": FileLifecycleStatusOrphanPending,
+		"deleted":        FileLifecycleStatusDeleted,
+	}
+	for in, want := range cases {
+		if got := NormalizeFileLifecycleStatus(in); got != want {
+			t.Fatalf("NormalizeFileLifecycleStatus(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestIsKnownFileLifecycleStatus(t *testing.T) {
+	known := []string{
+		FileLifecycleStatusTemp,
+		FileLifecycleStatusActive,
+		FileLifecycleStatusOrphanPending,
+		FileLifecycleStatusDeleted,
+	}
+	for i := range known {
+		if !IsKnownFileLifecycleStatus(known[i]) {
+			t.Fatalf("expected known lifecycle status %q", known[i])
+		}
+	}
+	if IsKnownFileLifecycleStatus("unknown") {
+		t.Fatalf("expected unknown lifecycle status to be false")
+	}
+}
diff --git a/internal/domain/file_manager/model_folder.go b/internal/domain/file_manager/model_folder.go
new file mode 100644
index 0000000..852d818
--- /dev/null
+++ b/internal/domain/file_manager/model_folder.go
@@ -0,0 +1,37 @@
+package filemanager
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type Folder struct {
+	ID             []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	ParentID       []byte     `gorm:"type:binary(16);column:parent_id;index:idx_file_folders_parent_active,priority:1;index:uq_file_folders_parent_name_slot,priority:1"`
+	Name           string     `gorm:"type:varchar(128);not null;column:name"`
+	NameNormalized string     `gorm:"type:varchar(128);not null;column:name_normalized;index:uq_file_folders_parent_name_slot,priority:2"`
+	Depth          int        `gorm:"type:smallint unsigned;not null;default:0;column:depth"`
+	PathCache      string     `gorm:"type:varchar(2048);column:path_cache"`
+	NameSlot       string     `gorm:"type:char(36);not null;default:'live';column:name_slot;index:uq_file_folders_parent_name_slot,priority:3"`
+	CreatedAt      time.Time  `gorm:"column:created_at"`
+	CreatedBy      []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt      time.Time  `gorm:"column:updated_at"`
+	UpdatedBy      []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt      *time.Time `gorm:"column:deleted_at;index:idx_file_folders_parent_active,priority:2;index:idx_file_folders_deleted_at"`
+	DeletedBy      []byte     `gorm:"type:binary(16);column:deleted_by"`
+	PurgeAt        *time.Time `gorm:"column:purge_at;index:idx_file_folders_purge_at"`
+
+	Parent *Folder `gorm:"foreignKey:ParentID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:RESTRICT"`
+}
+
+func (Folder) TableName() string { return "file_folders" }
+
+func (f *Folder) BeforeCreate(tx *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/file_manager/model_folder_test.go b/internal/domain/file_manager/model_folder_test.go
new file mode 100644
index 0000000..6d0a9cc
--- /dev/null
+++ b/internal/domain/file_manager/model_folder_test.go
@@ -0,0 +1,42 @@
+package filemanager
+
+import (
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func TestFolderTableName(t *testing.T) {
+	var m Folder
+	if got := m.TableName(); got != "file_folders" {
+		t.Fatalf("table name mismatch: got %s", got)
+	}
+}
+
+func TestFolderBeforeCreate(t *testing.T) {
+	t.Run("assigns uuid when missing", func(t *testing.T) {
+		m := &Folder{}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("before create error: %v", err)
+		}
+		if len(m.ID) != 16 {
+			t.Fatalf("expected 16-byte id, got %d", len(m.ID))
+		}
+	})
+
+	t.Run("keeps existing id", func(t *testing.T) {
+		id := make([]byte, 16)
+		for i := range id {
+			id[i] = byte(i + 1)
+		}
+		m := &Folder{ID: append([]byte(nil), id...)}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("before create error: %v", err)
+		}
+		for i := range id {
+			if m.ID[i] != id[i] {
+				t.Fatalf("id changed at %d: got %d want %d", i, m.ID[i], id[i])
+			}
+		}
+	})
+}
diff --git a/internal/domain/file_manager/realtime_event.go b/internal/domain/file_manager/realtime_event.go
new file mode 100644
index 0000000..dcaa748
--- /dev/null
+++ b/internal/domain/file_manager/realtime_event.go
@@ -0,0 +1,77 @@
+package filemanager
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type FileStatusRealtimeEventInput struct {
+	FileID        []byte
+	UserID        []byte
+	Status        string
+	Name          string
+	FailureReason string
+	OccurredAt    time.Time
+}
+
+type FileStatusRealtimeEventWriter interface {
+	CreateFileStatusRealtimeEvent(ctx context.Context, input FileStatusRealtimeEventInput) error
+}
+
+type FileStatusRealtimeEvent struct {
+	ID            []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	FileID        []byte     `gorm:"type:binary(16);index;not null;column:file_id"`
+	UserID        []byte     `gorm:"type:binary(16);index;not null;column:user_id"`
+	Status        string     `gorm:"type:varchar(32);index;not null;column:status"`
+	Name          string     `gorm:"type:varchar(255);not null;column:name"`
+	FailureReason string     `gorm:"type:text;column:failure_reason"`
+	OccurredAt    time.Time  `gorm:"index;not null;column:occurred_at"`
+	DeliveredAt   *time.Time `gorm:"index;column:delivered_at"`
+	CreatedAt     time.Time  `gorm:"column:created_at"`
+	UpdatedAt     time.Time  `gorm:"column:updated_at"`
+}
+
+func (FileStatusRealtimeEvent) TableName() string {
+	return "file_status_realtime_events"
+}
+
+func (e *FileStatusRealtimeEvent) BeforeCreate(_ *gorm.DB) error {
+	if len(e.ID) == 0 {
+		e.ID = uuidv7.MustBytes()
+	}
+	if e.OccurredAt.IsZero() {
+		e.OccurredAt = time.Now().UTC()
+	}
+	return nil
+}
+
+func NewFileStatusRealtimeEvent(input FileStatusRealtimeEventInput) (*FileStatusRealtimeEvent, error) {
+	if len(input.FileID) != 16 {
+		return nil, errors.New("file id must be uuid bytes")
+	}
+	if len(input.UserID) != 16 {
+		return nil, errors.New("user id must be uuid bytes")
+	}
+	status := NormalizeFileStatus(input.Status)
+	if !IsKnownFileStatus(status) {
+		return nil, errors.New("invalid status")
+	}
+	occurredAt := input.OccurredAt.UTC()
+	if input.OccurredAt.IsZero() {
+		occurredAt = time.Now().UTC()
+	}
+	return &FileStatusRealtimeEvent{
+		FileID:        append([]byte(nil), input.FileID...),
+		UserID:        append([]byte(nil), input.UserID...),
+		Status:        status,
+		Name:          strings.TrimSpace(input.Name),
+		FailureReason: strings.TrimSpace(input.FailureReason),
+		OccurredAt:    occurredAt,
+	}, nil
+}
diff --git a/internal/domain/file_manager/repository.go b/internal/domain/file_manager/repository.go
new file mode 100644
index 0000000..310fb0b
--- /dev/null
+++ b/internal/domain/file_manager/repository.go
@@ -0,0 +1,131 @@
+package filemanager
+
+import (
+	"context"
+	"time"
+)
+
+type FolderRepository interface {
+	Create(ctx context.Context, row *Folder) error
+	Update(ctx context.Context, row *Folder) error
+	MoveSubtree(ctx context.Context, id []byte, targetParentID []byte, targetName string, targetNameNormalized string, updatedBy []byte) (*Folder, error)
+	Delete(ctx context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error
+	Restore(ctx context.Context, id []byte, restoredBy []byte) error
+	Purge(ctx context.Context, id []byte) error
+	GetByID(ctx context.Context, id []byte) (*Folder, error)
+	GetByIDAny(ctx context.Context, id []byte) (*Folder, error)
+	GetByParentAndName(ctx context.Context, parentID []byte, nameNormalized string) (*Folder, error)
+	ListByParent(ctx context.Context, parentID []byte, sort string, limit, offset int) ([]Folder, int64, error)
+	SearchByName(ctx context.Context, name string, sort string, limit, offset int) ([]Folder, int64, error)
+	ListTrash(ctx context.Context, sort string, limit, offset int) ([]Folder, int64, error)
+	ListTrashByParent(ctx context.Context, parentID []byte, sort string, limit, offset int) ([]Folder, int64, error)
+}
+
+type FileFinalizeParams struct {
+	ID             []byte
+	ExpectedFrom   string
+	FolderID       []byte
+	Name           string
+	NameNormalized string
+	Extension      string
+	UpdatedBy      []byte
+}
+
+type FileStatusTransitionParams struct {
+	ID                  []byte
+	ExpectedFrom        string
+	To                  string
+	UpdatedBy           []byte
+	ProcessingStartedAt *time.Time
+	ProcessedAt         *time.Time
+	ValidatedAt         *time.Time
+	FailedAt            *time.Time
+	FailureReason       *string
+}
+
+type FileRepository interface {
+	Create(ctx context.Context, row *File) error
+	Update(ctx context.Context, row *File) error
+	TransitionStatus(ctx context.Context, params FileStatusTransitionParams) error
+	Finalize(ctx context.Context, params FileFinalizeParams) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error
+	Restore(ctx context.Context, id []byte, restoredBy []byte) error
+	Purge(ctx context.Context, id []byte) error
+	GetByID(ctx context.Context, id []byte) (*File, error)
+	GetByIDAny(ctx context.Context, id []byte) (*File, error)
+	GetByObjectKey(ctx context.Context, objectKey string) (*File, error)
+	GetByFolderAndName(ctx context.Context, folderID []byte, nameNormalized string) (*File, error)
+	GetByTemplateAndTakeover(ctx context.Context, templateUUID, takeoverID []byte) (*File, error)
+	ListEditedTemplatesByTakeoverID(ctx context.Context, takeoverID []byte) ([]File, error)
+	ListByFolder(ctx context.Context, folderID []byte, sort string, limit, offset int) ([]File, int64, error)
+	SearchByName(ctx context.Context, name string, sort string, limit, offset int) ([]File, int64, error)
+	ListTrashByFolder(ctx context.Context, folderID []byte, sort string, limit, offset int) ([]File, int64, error)
+}
+
+type FileLifecycleTransitionParams struct {
+	ID              []byte
+	Status          string
+	UpdatedBy       []byte
+	AttachedAt      *time.Time
+	OrphanedAt      *time.Time
+	LifecycleDelete *time.Time
+	ClearOrphanedAt bool
+}
+
+type FileLifecycleListFilter struct {
+	Status                  string
+	OrphanedBeforeEq        *time.Time
+	CreatedBeforeEq         *time.Time
+	ExcludeInTrash          bool
+	ExcludeLifecycleDeleted bool
+	Limit                   int
+}
+
+type FileLifecycleRepository interface {
+	UpdateLifecycle(ctx context.Context, params FileLifecycleTransitionParams) error
+	IsFileReferenced(ctx context.Context, fileID []byte) (bool, error)
+	ListFilesByLifecycle(ctx context.Context, filter FileLifecycleListFilter) ([]File, error)
+}
+
+type FileUploadIntentCompleteParams struct {
+	ID          []byte
+	UpdatedBy   []byte
+	CompletedAt time.Time
+}
+
+type FileUploadIntentExpireParams struct {
+	ID        []byte
+	UpdatedBy []byte
+	ExpiredAt time.Time
+}
+
+type FileUploadIntentSizeUpdateParams struct {
+	ID        []byte
+	SizeBytes int64
+	UpdatedBy []byte
+}
+
+type FileUploadIntentRepository interface {
+	CreateUploadIntent(ctx context.Context, row *FileUploadIntent) error
+	GetUploadIntentByID(ctx context.Context, id []byte) (*FileUploadIntent, error)
+	GetUploadIntentByIDForUpdate(ctx context.Context, id []byte) (*FileUploadIntent, error)
+	MarkUploadIntentCompleted(ctx context.Context, params FileUploadIntentCompleteParams) error
+	MarkUploadIntentExpired(ctx context.Context, params FileUploadIntentExpireParams) error
+}
+
+type AttachmentListFilter struct {
+	RefType  string
+	RefID    string
+	Category *string
+	Sort     string
+	Limit    int
+	Offset   int
+}
+
+type AttachmentRepository interface {
+	Create(ctx context.Context, row *Attachment) error
+	Delete(ctx context.Context, id []byte) error
+	GetByID(ctx context.Context, id []byte) (*Attachment, error)
+	GetByRefAndFile(ctx context.Context, refType, refID string, fileID []byte) (*Attachment, error)
+	ListByReference(ctx context.Context, filter AttachmentListFilter) ([]Attachment, int64, error)
+}
diff --git a/internal/domain/file_manager/service.go b/internal/domain/file_manager/service.go
new file mode 100644
index 0000000..53138f2
--- /dev/null
+++ b/internal/domain/file_manager/service.go
@@ -0,0 +1,242 @@
+package filemanager
+
+import (
+	"context"
+	"errors"
+	"io"
+	"time"
+)
+
+const (
+	SystemRootFolderName = "__system_root_files__"
+)
+
+var (
+	ErrDuplicateName                  = errors.New("duplicate name in target folder")
+	ErrInvalidMove                    = errors.New("invalid folder move")
+	ErrFolderNotFound                 = errors.New("folder not found")
+	ErrFileNotFound                   = errors.New("file not found")
+	ErrFileAlreadyFinalized           = errors.New("file already finalized")
+	ErrFileNotEligibleForFinalize     = errors.New("file is not eligible for finalize")
+	ErrInvalidFileStatusTransition    = errors.New("invalid file status transition")
+	ErrFileStatusConflict             = errors.New("file status conflict")
+	ErrStorageUnavailable             = errors.New("storage unavailable")
+	ErrFolderNotEmpty                 = errors.New("folder is not empty")
+	ErrFolderNotInTrash               = errors.New("folder is not in trash")
+	ErrFileNotInTrash                 = errors.New("file is not in trash")
+	ErrInvalidName                    = errors.New("invalid name")
+	ErrReservedName                   = errors.New("reserved name")
+	ErrFileTooLarge                   = errors.New("file too large")
+	ErrFileMimeTypeNotAllowed         = errors.New("file mime type is not allowed")
+	ErrFileExtensionNotAllowed        = errors.New("file extension is not allowed")
+	ErrEmptyFileNotAllowed            = errors.New("empty file is not allowed")
+	ErrFileNameTooLong                = errors.New("file name exceeds maximum length")
+	ErrFileProcessingQueueDisabled    = errors.New("file processing queue is not configured")
+	ErrUploadIntentRepositoryDisabled = errors.New("file upload intent repository is not configured")
+	ErrUploadIntentNotFound           = errors.New("upload intent not found")
+	ErrUploadIntentExpired            = errors.New("upload intent is expired")
+	ErrUploadIntentAlreadyComplete    = errors.New("upload intent already completed")
+	ErrUploadIntentStatusConflict     = errors.New("upload intent status conflict")
+	ErrUploadObjectNotFound           = errors.New("uploaded object not found in storage")
+	ErrUploadObjectMismatch           = errors.New("uploaded object does not match upload intent")
+	ErrAttachmentRepositoryDisabled   = errors.New("attachment repository is not configured")
+	ErrAttachmentNotFound             = errors.New("attachment not found")
+	ErrAttachmentAlreadyExists        = errors.New("attachment already exists for this reference")
+	ErrAttachmentRefRequired          = errors.New("attachment ref_type and ref_id are required")
+	ErrFileNotReadyForAttachment      = errors.New("file is not ready for attachment")
+)
+
+type FileUploadPolicy struct {
+	MaxFileSizeBytes  int64
+	AllowedMimeTypes  []string
+	AllowedExtensions []string
+	AllowEmptyFile    bool
+	MaxFilenameLength int
+}
+
+type FileProcessingJob struct {
+	JobID      string
+	FileUUID   string
+	Bucket     string
+	ObjectKey  string
+	UploadedBy string
+	MimeType   string
+	SizeBytes  int64
+	TraceID    string
+	RequestID  string
+}
+
+type FileProcessingQueue interface {
+	Enqueue(ctx context.Context, job FileProcessingJob) error
+}
+
+type CreateFolderParams struct {
+	Name     string
+	ParentID []byte
+	ActorID  []byte
+}
+
+type MoveFolderParams struct {
+	Name           *string
+	ParentID       []byte
+	ParentProvided bool
+	ActorID        []byte
+}
+
+type UploadFileParams struct {
+	Name        string
+	ContentType string
+	SizeBytes   int64
+	Body        io.Reader
+	ActorID     []byte
+	IsTemplate  bool
+}
+
+type RequestFileUploadIntentParams struct {
+	Name        string
+	ContentType string
+	SizeBytes   int64
+	ActorID     []byte
+}
+
+type FileUploadIntentGrant struct {
+	UploadIntentID []byte
+	Bucket         string
+	ObjectKey      string
+	Name           string
+	MimeType       string
+	SizeBytes      int64
+	Method         string
+	UploadURL      string
+	Headers        map[string]string
+	ExpiresAt      time.Time
+}
+
+type CompleteFileUploadIntentParams struct {
+	UploadIntentID []byte
+	ActorID        []byte
+}
+
+type CancelFileUploadIntentParams struct {
+	UploadIntentID []byte
+	ActorID        []byte
+}
+
+type CreateFileFromUploadParams struct {
+	UploadFileID   []byte
+	FolderID       []byte
+	FolderProvided bool
+	Name           *string
+	ActorID        []byte
+	IsTemplate     bool
+}
+
+type CreateFileFromUploadIntentParams struct {
+	UploadIntentID []byte
+	FolderID       []byte
+	FolderProvided bool
+	Name           string
+	ActorID        []byte
+	IsTemplate     bool
+}
+
+type BulkFileNodeResult struct {
+	Index int
+	File  *File
+	Err   error
+}
+
+type MoveFileParams struct {
+	Name           *string
+	FolderID       []byte
+	FolderProvided bool
+	ActorID        []byte
+}
+
+type CreateAttachmentParams struct {
+	FileID    []byte
+	RefType   string
+	RefID     string
+	Category  *string
+	SortOrder int
+	IsPrimary bool
+	ActorID   []byte
+}
+
+type ListAttachmentsParams struct {
+	RefType  string
+	RefID    string
+	Category *string
+	Sort     string
+	Limit    int
+	Offset   int
+}
+
+type FileCleanupStats struct {
+	Scanned int
+	Deleted int
+	Skipped int
+	Failed  int
+	DryRun  bool
+}
+
+// LifecycleManager is an optional extension implemented by concrete services
+// to expose file lifecycle transitions without widening the base Service
+// interface used by existing handlers/tests.
+type LifecycleManager interface {
+	MarkFileActive(ctx context.Context, fileID []byte, actorID []byte) error
+	ReconcileFileLifecycle(ctx context.Context, fileID []byte, actorID []byte) error
+	CleanupOrphanPendingFiles(ctx context.Context, now time.Time, gracePeriod time.Duration, limit int, dryRun bool) (FileCleanupStats, error)
+}
+
+type Service interface {
+	SetObjectStorage(storage ObjectStorage)
+	SetUploadPolicy(policy FileUploadPolicy)
+	SetFileProcessingQueue(fileQueue FileProcessingQueue)
+	SetFileUploadIntentRepository(repo FileUploadIntentRepository)
+	RequestFileUploadIntent(ctx context.Context, params RequestFileUploadIntentParams) (*FileUploadIntentGrant, error)
+	CompleteFileUploadIntent(ctx context.Context, params CompleteFileUploadIntentParams) (*File, error)
+	CancelFileUploadIntent(ctx context.Context, params CancelFileUploadIntentParams) error
+	CreateFileNodeFromUploadIntent(ctx context.Context, params CreateFileFromUploadIntentParams) (*File, error)
+	GetOrCreateSystemRootFolder(ctx context.Context) (*Folder, error)
+	CreateFolderNode(ctx context.Context, params CreateFolderParams) (*Folder, error)
+	MoveFolderNode(ctx context.Context, id []byte, params MoveFolderParams) (*Folder, error)
+	UploadFileNode(ctx context.Context, params UploadFileParams) (*File, error)
+	CreateFileNodeFromUpload(ctx context.Context, params CreateFileFromUploadParams) (*File, error)
+	UploadFileNodesBulk(ctx context.Context, params []UploadFileParams) []BulkFileNodeResult
+	CreateFileNodesFromUploadBulk(ctx context.Context, params []CreateFileFromUploadParams) []BulkFileNodeResult
+	MoveFileNode(ctx context.Context, id []byte, params MoveFileParams) (*File, error)
+	PurgeFolderNode(ctx context.Context, id []byte) error
+	PurgeFileNode(ctx context.Context, id []byte) error
+	ListNodesByParent(ctx context.Context, parentID []byte) ([]Folder, []File, error)
+	SearchNodes(ctx context.Context, query string) ([]Folder, []File, error)
+	ListTrashNodes(ctx context.Context) ([]Folder, []File, error)
+
+	CreateFolder(ctx context.Context, row *Folder) error
+	UpdateFolder(ctx context.Context, row *Folder) error
+	DeleteFolder(ctx context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error
+	RestoreFolder(ctx context.Context, id []byte, targetParentID []byte, targetProvided bool, restoredBy []byte) error
+	PurgeFolder(ctx context.Context, id []byte) error
+	GetFolderByID(ctx context.Context, id []byte) (*Folder, error)
+	GetFolderByIDAny(ctx context.Context, id []byte) (*Folder, error)
+	GetFolderByParentAndName(ctx context.Context, parentID []byte, nameNormalized string) (*Folder, error)
+	ListFoldersByParent(ctx context.Context, parentID []byte, sort string, limit, offset int) ([]Folder, int64, error)
+	ListTrashFoldersByParent(ctx context.Context, parentID []byte, sort string, limit, offset int) ([]Folder, int64, error)
+
+	CreateFile(ctx context.Context, row *File) error
+	UpdateFile(ctx context.Context, row *File) error
+	DeleteFile(ctx context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error
+	RestoreFile(ctx context.Context, id []byte, targetFolderID []byte, targetProvided bool, restoredBy []byte) error
+	PurgeFile(ctx context.Context, id []byte) error
+	GetFileByID(ctx context.Context, id []byte) (*File, error)
+	GetFileByIDAny(ctx context.Context, id []byte) (*File, error)
+	GetFileByObjectKey(ctx context.Context, objectKey string) (*File, error)
+	GetFileByFolderAndName(ctx context.Context, folderID []byte, nameNormalized string) (*File, error)
+	ListFilesByFolder(ctx context.Context, folderID []byte, sort string, limit, offset int) ([]File, int64, error)
+	ListTrashFilesByFolder(ctx context.Context, folderID []byte, sort string, limit, offset int) ([]File, int64, error)
+	CreateAttachment(ctx context.Context, params CreateAttachmentParams) (*Attachment, error)
+	GetAttachmentByID(ctx context.Context, id []byte) (*Attachment, error)
+	ListAttachmentsByReference(ctx context.Context, params ListAttachmentsParams) ([]Attachment, int64, error)
+	DeleteAttachment(ctx context.Context, id []byte) error
+	ListEditedWBFilesByTakeoverID(ctx context.Context, takeoverID []byte) ([]File, error)
+}
diff --git a/internal/domain/file_manager/storage.go b/internal/domain/file_manager/storage.go
new file mode 100644
index 0000000..f62f89e
--- /dev/null
+++ b/internal/domain/file_manager/storage.go
@@ -0,0 +1,56 @@
+package filemanager
+
+import (
+	"context"
+	"io"
+	"time"
+)
+
+type PutObjectInput struct {
+	ObjectKey   string
+	ContentType string
+	SizeBytes   int64
+	Body        io.Reader
+	Metadata    map[string]string
+}
+
+type PresignPutObjectInput struct {
+	ObjectKey   string
+	ContentType string
+	SizeBytes   int64
+	Metadata    map[string]string
+	TTL         time.Duration
+}
+
+type PresignedPutObject struct {
+	Bucket    string
+	ObjectKey string
+	Method    string
+	URL       string
+	Headers   map[string]string
+	ExpiresAt time.Time
+}
+
+type ObjectMetadata struct {
+	Bucket       string
+	ObjectKey    string
+	ETag         string
+	VersionID    string
+	SizeBytes    int64
+	LastModified *time.Time
+	ContentType  string
+}
+
+type ObjectStorage interface {
+	EnsureBucket(ctx context.Context) error
+	PutObject(ctx context.Context, input PutObjectInput) (ObjectMetadata, error)
+	DeleteObject(ctx context.Context, objectKey string) error
+	HeadObject(ctx context.Context, objectKey string) (ObjectMetadata, error)
+	PresignPutObject(ctx context.Context, input PresignPutObjectInput) (PresignedPutObject, error)
+	PresignGetObject(ctx context.Context, objectKey string, ttl time.Duration) (string, error)
+}
+
+type ObjectTaggingStorage interface {
+	PutObjectTagging(ctx context.Context, objectKey string, tags map[string]string) error
+	DeleteObjectTaggingKeys(ctx context.Context, objectKey string, keys []string) error
+}
diff --git a/internal/domain/file_manager/upload_intent.go b/internal/domain/file_manager/upload_intent.go
new file mode 100644
index 0000000..7328d01
--- /dev/null
+++ b/internal/domain/file_manager/upload_intent.go
@@ -0,0 +1,52 @@
+package filemanager
+
+import (
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	FileUploadIntentStatusPending   = "pending"
+	FileUploadIntentStatusCompleted = "completed"
+	FileUploadIntentStatusExpired   = "expired"
+)
+
+type FileUploadIntent struct {
+	ID             []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	Name           string     `gorm:"type:varchar(255);not null;column:name"`
+	NameNormalized string     `gorm:"type:varchar(255);not null;column:name_normalized"`
+	Extension      string     `gorm:"type:varchar(32);column:extension"`
+	SizeBytes      int64      `gorm:"type:bigint unsigned;not null;default:0;column:size_bytes"`
+	MimeType       string     `gorm:"type:varchar(255);not null;column:mime_type"`
+	Bucket         string     `gorm:"type:varchar(128);not null;column:bucket"`
+	ObjectKey      string     `gorm:"type:varchar(512);not null;uniqueIndex:uq_file_upload_intents_object_key"`
+	Status         string     `gorm:"type:varchar(32);index;not null;default:'pending';column:status"`
+	ExpiresAt      time.Time  `gorm:"index;not null;column:expires_at"`
+	CompletedAt    *time.Time `gorm:"column:completed_at"`
+	CreatedAt      time.Time  `gorm:"column:created_at"`
+	CreatedBy      []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt      time.Time  `gorm:"column:updated_at"`
+	UpdatedBy      []byte     `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (FileUploadIntent) TableName() string {
+	return "file_upload_intents"
+}
+
+func (m *FileUploadIntent) BeforeCreate(_ *gorm.DB) error {
+	if len(m.ID) == 0 {
+		m.ID = uuidv7.MustBytes()
+	}
+	if strings.TrimSpace(m.Status) == "" {
+		m.Status = FileUploadIntentStatusPending
+	}
+	return nil
+}
+
+func NormalizeFileUploadIntentStatus(status string) string {
+	return strings.ToLower(strings.TrimSpace(status))
+}
diff --git a/internal/domain/fleet_history/model.go b/internal/domain/fleet_history/model.go
new file mode 100644
index 0000000..50117a2
--- /dev/null
+++ b/internal/domain/fleet_history/model.go
@@ -0,0 +1,55 @@
+package fleethistory
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+// Entity types a history event can refer to.
+const (
+	EntityComplaint   = "complaint"
+	EntityEASARelease = "easa_release"
+	EntityMCF         = "mcf"
+	EntityHelicopter  = "helicopter"
+)
+
+// Action kinds recorded in the fleet history timeline.
+const (
+	ActionComplaintFiled = "complaint_filed"
+	ActionMELClassified  = "mel_classified"
+	ActionNSRDone        = "nsr_done"
+	ActionNSRCancelled   = "nsr_cancelled"
+	ActionActionTaken    = "action_taken"
+	ActionMCFResult      = "mcf_result"
+	ActionEASACreated    = "easa_created"
+	ActionEASASigned     = "easa_signed"
+	ActionAOGSet         = "aog_set"
+	ActionAOGCleared     = "aog_cleared"
+)
+
+// FleetHistory is an append-only event in a helicopter's timeline. It records who
+// did what and when across the complaint / MEL / NSR / action / MCF / EASA / AOG
+// flows, forming the per-aircraft history (servicing events live in their own
+// service-log table and are merged at read time).
+type FleetHistory struct {
+	ID           []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	HelicopterID []byte    `gorm:"type:binary(16);not null;index;column:helicopter_id"`
+	EntityType   string    `gorm:"type:varchar(32);not null;column:entity_type"`
+	EntityID     []byte    `gorm:"type:binary(16);column:entity_id"`
+	Action       string    `gorm:"type:varchar(48);not null;column:action"`
+	Message      string    `gorm:"type:text;column:message"`
+	Actor        []byte    `gorm:"type:binary(16);column:actor"`
+	CreatedAt    time.Time `gorm:"type:datetime(3);index;column:created_at"`
+}
+
+func (FleetHistory) TableName() string { return "fleet_histories" }
+
+func (f *FleetHistory) BeforeCreate(_ *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/fleet_history/repository.go b/internal/domain/fleet_history/repository.go
new file mode 100644
index 0000000..7c7debb
--- /dev/null
+++ b/internal/domain/fleet_history/repository.go
@@ -0,0 +1,11 @@
+package fleethistory
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *FleetHistory) error
+	ListByHelicopter(ctx context.Context, helicopterID []byte, limit, offset int) ([]FleetHistory, int64, error)
+	// HelicopterIDByInspection resolves the helicopter linked to a flight inspection
+	// via its reserve_ac, returning nil bytes when none is found.
+	HelicopterIDByInspection(ctx context.Context, inspectionID []byte) ([]byte, error)
+}
diff --git a/internal/domain/fleet_status/const.go b/internal/domain/fleet_status/const.go
new file mode 100644
index 0000000..9f94524
--- /dev/null
+++ b/internal/domain/fleet_status/const.go
@@ -0,0 +1,33 @@
+package fleetstatus
+
+const (
+	InspectionTypeAF       = "A/F"
+	InspectionTypeENG1     = "ENG1"
+	InspectionTypeENG2     = "ENG2"
+	InspectionTypeMAIN1    = "MAIN1"
+	InspectionTypeMAIN2    = "MAIN2"
+	
+	FleetStatusFileRefType = "fleet_status"
+
+	StatusActive    = "active"
+	StatusServiced  = "serviced"
+	FileCategoryWB  = "wb"
+	FileCategoryBFI = "bfi"
+)
+
+func IsValidFileCategory(s string) bool {
+	switch s {
+	case FileCategoryWB, FileCategoryBFI:
+		return true
+	default:
+		return false
+	}
+}
+
+var InspectionTypeOrder = []string{
+	InspectionTypeAF,
+	InspectionTypeENG1,
+	InspectionTypeENG2,
+	InspectionTypeMAIN1,
+	InspectionTypeMAIN2,
+}
diff --git a/internal/domain/fleet_status/model.go b/internal/domain/fleet_status/model.go
new file mode 100644
index 0000000..f71e2ce
--- /dev/null
+++ b/internal/domain/fleet_status/model.go
@@ -0,0 +1,107 @@
+package fleetstatus
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/helicopter"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type FleetStatus struct {
+	ID           []byte                 `gorm:"type:binary(16);primaryKey;column:id"`
+	HelicopterID []byte                 `gorm:"type:binary(16);not null;index;column:helicopter_id"`
+	Helicopter   *helicopter.Helicopter `gorm:"foreignKey:HelicopterID;references:ID"`
+	Status       string                 `gorm:"type:varchar(16);not null;default:active;index;column:status"`
+	ServicedAt   *time.Time             `gorm:"column:serviced_at;index"`
+
+	MaintenanceSchedules []MaintenanceSchedule `gorm:"foreignKey:FleetStatusID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	Files                []FleetStatusFile     `gorm:"foreignKey:FleetStatusID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at;index"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (FleetStatus) TableName() string { return "fleet_statuses" }
+
+func (f *FleetStatus) BeforeCreate(_ *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	if f.Status == "" {
+		f.Status = StatusActive
+	}
+	return nil
+}
+
+type MaintenanceSchedule struct {
+	ID             []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	FleetStatusID  []byte `gorm:"type:binary(16);not null;index;column:fleet_status_id"`
+	InspectionType string `gorm:"type:varchar(16);not null;column:inspection_type"`
+	Type           string `gorm:"type:varchar(255);not null;column:type"`
+	Due            string `gorm:"type:varchar(255);column:due"`
+	Ext            string `gorm:"type:varchar(255);column:ext"`
+
+	FleetStatus *FleetStatus `gorm:"foreignKey:FleetStatusID;references:ID"`
+}
+
+func (MaintenanceSchedule) TableName() string { return "maintenance_schedules" }
+
+func (m *MaintenanceSchedule) BeforeCreate(_ *gorm.DB) error {
+	if len(m.ID) == 0 {
+		m.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type FleetStatusFile struct {
+	ID               []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	IsMandatory      bool   `gorm:"not null;default:false;column:is_mandatory"`
+	FleetStatusID    []byte `gorm:"type:binary(16);not null;index;column:fleet_status_id"`
+	FileAttachmentID []byte `gorm:"type:binary(16);not null;index;column:file_attachment_id"`
+	Category         string `gorm:"type:varchar(64);index;column:category"`
+
+	FileID []byte `gorm:"-"`
+
+	FleetStatus *FleetStatus            `gorm:"foreignKey:FleetStatusID;references:ID"`
+	Attachment  *filemanager.Attachment `gorm:"foreignKey:FileAttachmentID;references:ID"`
+}
+
+func (FleetStatusFile) TableName() string { return "fleet_status_files" }
+
+func (f *FleetStatusFile) BeforeCreate(_ *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type FleetStatusServiceLog struct {
+	ID             []byte                 `gorm:"type:binary(16);primaryKey;column:id"`
+	FleetStatusID  []byte                 `gorm:"type:binary(16);not null;index;column:fleet_status_id"`
+	HelicopterID   []byte                 `gorm:"type:binary(16);not null;index;column:helicopter_id"`
+	Helicopter     *helicopter.Helicopter `gorm:"foreignKey:HelicopterID;references:ID"`
+	InspectionType string                 `gorm:"type:varchar(16);not null;column:inspection_type"`
+	Type           string                 `gorm:"type:varchar(255);not null;column:type"`
+	Due            string                 `gorm:"type:varchar(255);column:due"`
+	Ext            string                 `gorm:"type:varchar(255);column:ext"`
+	ServicedAt     time.Time              `gorm:"column:serviced_at;index"`
+	CreatedAt      time.Time              `gorm:"column:created_at"`
+	CreatedBy      []byte                 `gorm:"type:binary(16);column:created_by"`
+}
+
+func (FleetStatusServiceLog) TableName() string { return "fleet_status_service_logs" }
+
+func (f *FleetStatusServiceLog) BeforeCreate(_ *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
diff --git a/internal/domain/fleet_status/model_test.go b/internal/domain/fleet_status/model_test.go
new file mode 100644
index 0000000..65c7949
--- /dev/null
+++ b/internal/domain/fleet_status/model_test.go
@@ -0,0 +1,68 @@
+package fleetstatus
+
+import "testing"
+
+func TestTableNames(t *testing.T) {
+	if (FleetStatus{}).TableName() != "fleet_statuses" {
+		t.Error("FleetStatus table name")
+	}
+	if (MaintenanceSchedule{}).TableName() != "maintenance_schedules" {
+		t.Error("MaintenanceSchedule table name")
+	}
+	if (FleetStatusFile{}).TableName() != "fleet_status_files" {
+		t.Error("FleetStatusFile table name")
+	}
+	if (FleetStatusServiceLog{}).TableName() != "fleet_status_service_logs" {
+		t.Error("FleetStatusServiceLog table name")
+	}
+}
+
+func TestFleetStatusBeforeCreate(t *testing.T) {
+	f := &FleetStatus{}
+	if err := f.BeforeCreate(nil); err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	if len(f.ID) == 0 {
+		t.Fatal("ID should be set")
+	}
+	if f.Status != StatusActive {
+		t.Fatalf("Status default = %q, want %q", f.Status, StatusActive)
+	}
+	// existing ID + status preserved
+	f2 := &FleetStatus{Status: "serviced"}
+	_ = f2.BeforeCreate(nil)
+	if f2.Status != "serviced" {
+		t.Fatal("BeforeCreate must not overwrite an existing status")
+	}
+}
+
+func TestChildBeforeCreate(t *testing.T) {
+	m := &MaintenanceSchedule{}
+	_ = m.BeforeCreate(nil)
+	if len(m.ID) == 0 {
+		t.Error("MaintenanceSchedule ID not set")
+	}
+	fsf := &FleetStatusFile{}
+	_ = fsf.BeforeCreate(nil)
+	if len(fsf.ID) == 0 {
+		t.Error("FleetStatusFile ID not set")
+	}
+	sl := &FleetStatusServiceLog{}
+	_ = sl.BeforeCreate(nil)
+	if len(sl.ID) == 0 {
+		t.Error("FleetStatusServiceLog ID not set")
+	}
+}
+
+func TestIsValidFileCategory(t *testing.T) {
+	for _, c := range []string{FileCategoryWB, FileCategoryBFI} {
+		if !IsValidFileCategory(c) {
+			t.Fatalf("%q should be valid", c)
+		}
+	}
+	for _, c := range []string{"WB", "", "nope"} {
+		if IsValidFileCategory(c) {
+			t.Fatalf("%q should be invalid", c)
+		}
+	}
+}
diff --git a/internal/domain/fleet_status/repository.go b/internal/domain/fleet_status/repository.go
new file mode 100644
index 0000000..8b36e35
--- /dev/null
+++ b/internal/domain/fleet_status/repository.go
@@ -0,0 +1,19 @@
+package fleetstatus
+
+import (
+	"context"
+	"time"
+)
+
+type Repository interface {
+	Create(ctx context.Context, row *FleetStatus) error
+	Update(ctx context.Context, row *FleetStatus) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*FleetStatus, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]FleetStatus, int64, error)
+	LatestByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]*FleetStatus, error)
+	MarkServiced(ctx context.Context, id []byte, servicedAt time.Time, actorID []byte) error
+	ListServiceHistoryByHelicopterID(ctx context.Context, helicopterID []byte, limit, offset int) ([]FleetStatusServiceLog, int64, error)
+	HelicopterIDByMissionID(ctx context.Context, missionID []byte) ([]byte, error)
+	HelicopterIDsWithFleetStatus(ctx context.Context) ([][]byte, error)
+}
diff --git a/internal/domain/fleet_status/service.go b/internal/domain/fleet_status/service.go
new file mode 100644
index 0000000..e411973
--- /dev/null
+++ b/internal/domain/fleet_status/service.go
@@ -0,0 +1,28 @@
+package fleetstatus
+
+import (
+	"context"
+	"time"
+
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+	shareddto "wucher/internal/transport/http/dto/shared"
+)
+
+type OverdueInspection struct {
+	InspectionType string
+	Detail         string
+}
+
+type Service interface {
+	Create(ctx context.Context, row *FleetStatus) error
+	Update(ctx context.Context, row *FleetStatus) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*FleetStatus, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]FleetStatus, int64, error)
+	LatestByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]*FleetStatus, error)
+	MarkServiced(ctx context.Context, id []byte, servicedAt time.Time, actorID []byte) error
+	ListServiceHistoryByHelicopterID(ctx context.Context, helicopterID []byte, limit, offset int) ([]FleetStatusServiceLog, int64, error)
+	GetSummaryByHelicopterID(ctx context.Context, helicopterID []byte) (*shareddto.FleetStatusSummary, error)
+	ReviseSummary(ctx context.Context, helicopterID []byte, in helicopterusage.ManualSummaryInput, actor []byte) error
+	OverdueInspections(ctx context.Context, helicopterID []byte) ([]OverdueInspection, error)
+}
diff --git a/internal/domain/flight/model.go b/internal/domain/flight/model.go
new file mode 100644
index 0000000..4ac136a
--- /dev/null
+++ b/internal/domain/flight/model.go
@@ -0,0 +1,39 @@
+package flight
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/takeover"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type Flight struct {
+	ID                 []byte               `gorm:"type:binary(16);primaryKey;column:id"`
+	Status             string               `gorm:"type:varchar(20);not null;default:draft;column:status"`
+	Date               time.Time            `gorm:"type:date;not null;index;column:date"`
+	MissionCode        *string              `gorm:"type:varchar(64);index;column:mission_code"`
+	DutyRosterID       []byte               `gorm:"type:binary(16);->;column:duty_roster_id"`
+	ReserveAcID        []byte               `gorm:"type:binary(16);->;column:reserve_ac_id"`
+	TakeoverAcID       []byte               `gorm:"type:binary(16);index;column:takeover_ac_id"`
+	Takeover           *takeover.TakeoverAc `gorm:"foreignKey:TakeoverAcID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+
+	CreatedAt     time.Time  `gorm:"column:created_at"`
+	CreatedBy     []byte     `gorm:"type:binary(16);column:created_by"`
+	CreatedByName string     `gorm:"->;column:created_by_name"`
+	UpdatedAt     time.Time  `gorm:"column:updated_at"`
+	UpdatedBy     []byte     `gorm:"type:binary(16);column:updated_by"`
+	UpdatedByName string     `gorm:"->;column:updated_by_name"`
+	DeletedAt     *time.Time `gorm:"column:deleted_at;index"`
+	DeletedBy     []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (Flight) TableName() string { return "flights" }
+
+func (f *Flight) BeforeCreate(tx *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/flight/repository.go b/internal/domain/flight/repository.go
new file mode 100644
index 0000000..64f5b96
--- /dev/null
+++ b/internal/domain/flight/repository.go
@@ -0,0 +1,20 @@
+package flight
+
+import "context"
+
+type FlightRepository interface {
+	Create(ctx context.Context, row *Flight) error
+	GetLatestMissionCodeByPrefix(ctx context.Context, prefix string) (string, error)
+	Update(ctx context.Context, row *Flight) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Flight, error)
+	ListByUserID(ctx context.Context, userID []byte, limit, offset int) ([]Flight, int64, error)
+	ListByCreatedBy(ctx context.Context, createdBy []byte, filter string, date string, sort string, limit, offset int) ([]Flight, int64, error)
+	GetByReserveAcID(ctx context.Context, reserveAcID []byte) (*Flight, error)
+	ListByReserveAcID(ctx context.Context, reserveAcID []byte) ([]Flight, error)
+	GetByTakeoverAcID(ctx context.Context, takeoverAcID []byte) (*Flight, error)
+	ListByTakeoverAcIDs(ctx context.Context, takeoverAcIDs [][]byte) ([]Flight, error)
+	GetByDutyRosterID(ctx context.Context, dutyRosterID []byte) (*Flight, error)
+	ListByDutyRosterIDs(ctx context.Context, dutyRosterIDs [][]byte) ([]Flight, error)
+	List(ctx context.Context, filter string, date string, sort string, limit, offset int) ([]Flight, int64, error)
+}
diff --git a/internal/domain/flight/service.go b/internal/domain/flight/service.go
new file mode 100644
index 0000000..97a11eb
--- /dev/null
+++ b/internal/domain/flight/service.go
@@ -0,0 +1,19 @@
+package flight
+
+import "context"
+
+type FlightService interface {
+	Create(ctx context.Context, row *Flight) error
+	Update(ctx context.Context, row *Flight) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Flight, error)
+	ListByUserID(ctx context.Context, userID []byte, limit, offset int) ([]Flight, int64, error)
+	ListByCreatedBy(ctx context.Context, createdBy []byte, filter string, date string, sort string, limit, offset int) ([]Flight, int64, error)
+	GetByReserveAcID(ctx context.Context, reserveAcID []byte) (*Flight, error)
+	ListByReserveAcID(ctx context.Context, reserveAcID []byte) ([]Flight, error)
+	GetByTakeoverAcID(ctx context.Context, takeoverAcID []byte) (*Flight, error)
+	ListByTakeoverAcIDs(ctx context.Context, takeoverAcIDs [][]byte) ([]Flight, error)
+	GetByDutyRosterID(ctx context.Context, dutyRosterID []byte) (*Flight, error)
+	ListByDutyRosterIDs(ctx context.Context, dutyRosterIDs [][]byte) ([]Flight, error)
+	List(ctx context.Context, filter string, date string, sort string, limit, offset int) ([]Flight, int64, error)
+}
diff --git a/internal/domain/flight_data/completion.go b/internal/domain/flight_data/completion.go
new file mode 100644
index 0000000..ffd44a3
--- /dev/null
+++ b/internal/domain/flight_data/completion.go
@@ -0,0 +1,121 @@
+package flightdata
+
+import (
+	"strings"
+
+	sharedconst "wucher/internal/shared/const"
+)
+
+const (
+	StatusInProgress = "in_progress"
+	StatusCompleted  = "completed"
+)
+
+// IsComplete reports whether the persisted flight-data status is complete.
+func IsComplete(row *FlightData) bool {
+	if row == nil {
+		return false
+	}
+
+	return strings.EqualFold(strings.TrimSpace(row.Status), StatusCompleted)
+}
+
+func DeriveStatus(row *FlightData, details *SPODetails) string {
+	if !isBaseComplete(row) {
+		return StatusInProgress
+	}
+
+	switch missionType(row) {
+	case sharedconst.MissionTypeCAT, sharedconst.MissionTypeNCO, sharedconst.MissionTypeSPO:
+		return StatusCompleted
+	case sharedconst.MissionTypeHEMS:
+		return StatusCompleted
+	}
+
+	return StatusInProgress
+}
+
+func hasExactlyOneLocation(a, b []byte) bool {
+	hasA := len(a) == 16
+	hasB := len(b) == 16
+	return hasA != hasB
+}
+
+func missionType(row *FlightData) string {
+	if row == nil || row.Mission == nil {
+		return ""
+	}
+	return strings.ToUpper(strings.TrimSpace(row.Mission.Type))
+}
+
+func isBaseComplete(row *FlightData) bool {
+	if row == nil {
+		return false
+	}
+
+	requiresRotorBrakeCycle := true
+	switch missionType(row) {
+	case sharedconst.MissionTypeCAT, sharedconst.MissionTypeNCO, sharedconst.MissionTypeSPO:
+		requiresRotorBrakeCycle = false
+	}
+
+	return len(row.MissionID) == 16 &&
+		hasExactlyOneLocation(row.FromICAOID, row.FromHospitalID) &&
+		hasExactlyOneLocation(row.ToICAOID, row.ToHospitalID) &&
+		!row.FlightTakeOff.IsZero() &&
+		!row.FlightLanding.IsZero() &&
+		row.FlightDuration > 0 &&
+		row.LandingCount > 0 &&
+		(!requiresRotorBrakeCycle || row.RotorBrakeCycle > 0)
+}
+
+func isHESLOComplete(details SPOHESLODetails) bool {
+	if len(details.Flights) == 0 || len(details.Slings) == 0 {
+		return false
+	}
+	for i := range details.Flights {
+		if details.Flights[i].ROT <= 0 || len(details.Flights[i].FuelTruckID) != 16 || len(details.Flights[i].LoggingSlingID) != 16 {
+			return false
+		}
+	}
+	for i := range details.Slings {
+		if len(details.Slings[i].HESLOFlightID) != 16 || len(details.Slings[i].SlingID) != 16 {
+			return false
+		}
+	}
+	return true
+}
+
+func isLoggingComplete(details SPOLoggingDetails) bool {
+	if len(details.Slings) == 0 {
+		return false
+	}
+	for i := range details.Slings {
+		if len(details.Slings[i].SlingID) != 16 {
+			return false
+		}
+	}
+	return true
+}
+
+func isHECComplete(details SPOHECDetails) bool {
+	if len(details.Flights) == 0 || len(details.Slings) == 0 || len(details.Loads) == 0 {
+		return false
+	}
+	for i := range details.Flights {
+		if details.Flights[i].ROT <= 0 || details.Flights[i].HECCycle <= 0 || len(details.Flights[i].EquipmentID) != 16 {
+			return false
+		}
+	}
+	for i := range details.Slings {
+		if len(details.Slings[i].SlingID) != 16 {
+			return false
+		}
+	}
+	for i := range details.Loads {
+		if strings.TrimSpace(details.Loads[i].LoadCategory) == "" || details.Loads[i].Quantity <= 0 {
+			return false
+		}
+	}
+	return true
+}
diff --git a/internal/domain/flight_data/completion_test.go b/internal/domain/flight_data/completion_test.go
new file mode 100644
index 0000000..ff50e8d
--- /dev/null
+++ b/internal/domain/flight_data/completion_test.go
@@ -0,0 +1,123 @@
+package flightdata
+
+import (
+	"testing"
+	"time"
+
+	missiondomain "wucher/internal/domain/mission"
+)
+
+func TestIsComplete(t *testing.T) {
+	if IsComplete(nil) {
+		t.Fatal("expected nil row to be incomplete")
+	}
+	if IsComplete(&FlightData{Status: StatusInProgress}) {
+		t.Fatal("expected on_progress status to be incomplete")
+	}
+	if !IsComplete(&FlightData{Status: StatusCompleted}) {
+		t.Fatal("expected complete status to be complete")
+	}
+}
+
+func TestDeriveStatus(t *testing.T) {
+	now := time.Now().UTC()
+	base := &FlightData{
+		MissionID:          []byte("1234567890123456"),
+		FromICAOID:         []byte("3456789012345678"),
+		ToHospitalID:       []byte("4567890123456789"),
+		FlightTakeOff:      now,
+		FlightLanding:      now,
+		FlightDuration:     time.Hour,
+		LandingCount:       1,
+		DeliveryNoteNumber: "DN-1",
+		CustomerName:       "Customer",
+	}
+
+	t.Run("cat complete", func(t *testing.T) {
+		base.Mission = &missiondomain.Mission{Type: "CAT"}
+		if got := DeriveStatus(base, nil); got != StatusCompleted {
+			t.Fatalf("expected complete, got %q", got)
+		}
+	})
+
+	t.Run("nco complete without rotor brake cycle", func(t *testing.T) {
+		base.Mission = &missiondomain.Mission{Type: "NCO"}
+		if got := DeriveStatus(base, nil); got != StatusCompleted {
+			t.Fatalf("expected complete, got %q", got)
+		}
+	})
+
+	t.Run("hems requires rotor brake cycle", func(t *testing.T) {
+		base.Mission = &missiondomain.Mission{Type: "HEMS"}
+		if got := DeriveStatus(base, nil); got != StatusInProgress {
+			t.Fatalf("expected on_progress, got %q", got)
+		}
+		base.RotorBrakeCycle = 1
+		if got := DeriveStatus(base, nil); got != StatusCompleted {
+			t.Fatalf("expected complete after rotor brake cycle is set, got %q", got)
+		}
+		base.RotorBrakeCycle = 0
+	})
+
+	t.Run("spo complete without details", func(t *testing.T) {
+		base.Mission = &missiondomain.Mission{Type: "SPO"}
+		if got := DeriveStatus(base, nil); got != StatusCompleted {
+			t.Fatalf("expected complete, got %q", got)
+		}
+	})
+
+	t.Run("spo complete with details", func(t *testing.T) {
+		base.Mission = &missiondomain.Mission{Type: "SPO"}
+		details := &SPODetails{
+			HESLO: SPOHESLODetails{
+				Flights: []SPOHESLOFlight{{
+					ROT:            1,
+					FuelTruckID:    []byte("5678901234567890"),
+					LoggingSlingID: []byte("6789012345678901"),
+				}},
+				Slings: []SPOHESLOSling{{
+					HESLOFlightID: []byte("5678901234567890"),
+					SlingID:       []byte("7890123456789012"),
+				}},
+			},
+			Logging: SPOLoggingDetails{
+				Slings: []SPOLoggingSling{{
+					SlingID: []byte("8901234567890123"),
+				}},
+			},
+			HEC: SPOHECDetails{
+				Flights: []SPOHECFlight{{
+					ROT:         1,
+					HECCycle:    1,
+					EquipmentID: []byte("9012345678901234"),
+				}},
+				Slings: []SPOHECSling{{
+					SlingID: []byte("0123456789012345"),
+				}},
+				Loads: []SPOHECLoad{{
+					LoadCategory: "LT200",
+					Quantity:     1,
+				}},
+			},
+		}
+		if got := DeriveStatus(base, details); got != StatusCompleted {
+			t.Fatalf("expected complete, got %q", got)
+		}
+	})
+
+	t.Run("spo missing section still complete", func(t *testing.T) {
+		base.Mission = &missiondomain.Mission{Type: "SPO"}
+		details := &SPODetails{
+			HESLO: SPOHESLODetails{
+				Flights: []SPOHESLOFlight{{
+					ROT:            1,
+					FuelTruckID:    []byte("5678901234567890"),
+					LoggingSlingID: []byte("6789012345678901"),
+				}},
+			},
+		}
+		if got := DeriveStatus(base, details); got != StatusCompleted {
+			t.Fatalf("expected complete, got %q", got)
+		}
+	})
+}
diff --git a/internal/domain/flight_data/errors.go b/internal/domain/flight_data/errors.go
new file mode 100644
index 0000000..4ece339
--- /dev/null
+++ b/internal/domain/flight_data/errors.go
@@ -0,0 +1,32 @@
+package flightdata
+
+import "errors"
+
+var (
+	ErrRequired                     = errors.New("flight_data required")
+	ErrMissionReference             = errors.New("flight_data mission reference invalid")
+	ErrCoPilotReference             = errors.New("flight_data co_pilot reference invalid")
+	ErrOriginLocationReference      = errors.New("flight_data origin location reference invalid")
+	ErrDestinationLocationReference = errors.New("flight_data destination location reference invalid")
+	ErrFacilityReference            = errors.New("flight_data facility reference invalid")
+	ErrCreateBlocked                = errors.New("flight_data create blocked")
+	ErrLocked                       = errors.New("flight_data locked")
+	ErrLockedAfterFlightInspection  = errors.New("flight_data locked by after_flight_inspection")
+)
+
+const (
+	ErrorMessageRequired                     = "flight data is required"
+	ErrorMessageMissionReference             = "mission must reference an existing mission"
+	ErrorMessageCoPilotReference             = "co_pilot must reference an existing user"
+	ErrorMessageOriginLocationReference      = "origin must reference exactly one location type"
+	ErrorMessageDestinationLocationReference = "destination must reference exactly one location type"
+	ErrorMessageFacilityReference            = "facility reference is invalid"
+	ErrorMessageFieldRequired                = "field is required"
+	ErrorMessageInvalidUUID                  = "invalid UUID"
+	ErrorMessageInvalidRFC3339               = "invalid RFC3339 datetime"
+	ErrorMessageInvalidPathUUID              = "uuid is invalid UUID"
+	ErrorMessageNotFound                     = "flight data not found"
+	ErrorMessageCreateBlocked                = "flight data cannot be created because fm report already exists for this flight"
+	ErrorMessageLocked                       = "flight data is locked because fm report is completed"
+	ErrorMessageLockedAfterFlightInspection  = "flight data is locked because after flight inspection already exists"
+)
diff --git a/internal/domain/flight_data/flight_data.go b/internal/domain/flight_data/flight_data.go
new file mode 100644
index 0000000..36db125
--- /dev/null
+++ b/internal/domain/flight_data/flight_data.go
@@ -0,0 +1,281 @@
+package flightdata
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	facilitydomain "wucher/internal/domain/facility"
+	filemanager "wucher/internal/domain/file_manager"
+	hospitaldomain "wucher/internal/domain/hospital"
+	icaodomain "wucher/internal/domain/icao"
+	missiondomain "wucher/internal/domain/mission"
+	userdomain "wucher/internal/domain/user"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type FlightData struct {
+	ID        []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	MissionID []byte `gorm:"type:binary(16);index;not null;column:mission_id"`
+	CoPilotID []byte `gorm:"type:binary(16);index;column:co_pilot_id"`
+
+	FromICAOID     []byte `gorm:"type:binary(16);index;column:from_icao_id"`
+	FromHospitalID []byte `gorm:"type:binary(16);index;column:from_hospital_id"`
+
+	ToICAOID     []byte `gorm:"type:binary(16);index;column:to_icao_id"`
+	ToHospitalID []byte `gorm:"type:binary(16);index;column:to_hospital_id"`
+
+	FlightTakeOff        time.Time     `gorm:"column:take_off"`
+	FlightLanding        time.Time     `gorm:"column:landing"`
+	FlightDuration       time.Duration `gorm:"column:duration"`
+	FlightType           string        `gorm:"type:varchar(255);column:flight_type"`
+	FlightRED            time.Duration `gorm:"column:red"`
+	MaxN1                float64       `gorm:"column:max_n1"`
+	MaxN2                float64       `gorm:"column:max_n2"`
+	PaxCount             int           `gorm:"column:pax_count"`
+	TicketNo             string        `gorm:"type:varchar(255);column:ticket_no"`
+	Engine               string        `gorm:"type:varchar(255);column:engine"`
+	LandingCount         int           `gorm:"column:landing_count"`
+	RotorBrakeCycle      int           `gorm:"column:rotor_brake_cycle"`
+	HookReleases         int           `gorm:"column:hook_releases"`
+	DeliveryNoteNumber   string        `gorm:"type:varchar(255);column:delivery_note_number"`
+	CustomerName         string        `gorm:"type:varchar(255);column:customer_name"`
+	FlightPlanDistance   float64       `gorm:"column:flight_plan_distance"`
+	FlightPlanTime       time.Duration `gorm:"column:flight_plan_time"`
+	FlightPlanTrueCourse float64       `gorm:"column:flight_plan_true_course"`
+	FuelBeforeFlight     float64       `gorm:"column:fuel_before_flight"`
+	FuelUpload           float64       `gorm:"column:fuel_upload"`
+	FuelAfterFlight      float64       `gorm:"column:fuel_after_flight"`
+	FuelPlanning         float64       `gorm:"column:fuel_planning"`
+	FlightPositioning    bool          `gorm:"type:boolean;not null;default:false;column:flight_position"`
+	OtherInformation     string        `gorm:"type:text;column:other_information"`
+	Status               string        `gorm:"type:varchar(20);not null;default:on_progress;column:status"`
+
+	Mission      *missiondomain.Mission   `gorm:"foreignKey:MissionID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	TypeOfFlight *TypeOfFlight            `gorm:"foreignKey:FlightDataID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	CoPilot      *userdomain.User         `gorm:"foreignKey:CoPilotID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	FromICAO     *icaodomain.ICAO         `gorm:"foreignKey:FromICAOID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	FromHospital *hospitaldomain.Hospital `gorm:"foreignKey:FromHospitalID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	ToICAO       *icaodomain.ICAO         `gorm:"foreignKey:ToICAOID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	ToHospital   *hospitaldomain.Hospital `gorm:"foreignKey:ToHospitalID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+
+	Attachments []filemanager.Attachment `gorm:"-"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"index;column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (FlightData) TableName() string { return "flight_data" }
+
+func (f *FlightData) BeforeCreate(_ *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type TypeOfFlight struct {
+	ID           []byte        `gorm:"type:binary(16);primaryKey;column:id"`
+	FlightDataID []byte        `gorm:"type:binary(16);index;not null;column:flight_data_id"`
+	Category     string        `gorm:"type:enum('ZNO', 'ANO', 'ZTZ', 'ZSP');not null;column:category"`
+	Quantity     int           `gorm:"not null;column:quantity"`
+	DurationTime time.Duration `gorm:"not null;column:duration"`
+
+	FlightData *FlightData `gorm:"foreignKey:FlightDataID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+type HESLOFlight struct {
+	ID                  []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	FlightDataID        []byte    `gorm:"type:binary(16);index;not null;column:flight_data_id"`
+	ROT                 int       `gorm:"not null;column:rot"`
+	FacilityFuelTruckID []byte    `gorm:"type:binary(16);column:fuel_truck_id"`
+	LoggingSlingID      []byte    `gorm:"type:binary(16);column:logging_sling_id"`
+	CreatedAt           time.Time `gorm:"column:created_at"`
+
+	FlightData        *FlightData              `gorm:"foreignKey:FlightDataID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	FacilityFuelTruck *facilitydomain.Facility `gorm:"foreignKey:FacilityFuelTruckID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	LoggingSling      *facilitydomain.Facility `gorm:"foreignKey:LoggingSlingID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+}
+
+func (HESLOFlight) TableName() string { return "heslo_flights" }
+
+type HESLOSling struct {
+	ID              []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	FacilitySlingID []byte    `gorm:"type:binary(16);column:facility_sling_id"`
+	HESLOFlightID   []byte    `gorm:"type:binary(16);index;not null;column:heslo_flight_id"`
+	CreatedAt       time.Time `gorm:"column:created_at"`
+
+	HESLOFlight   *HESLOFlight             `gorm:"foreignKey:HESLOFlightID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	FacilitySling *facilitydomain.Facility `gorm:"foreignKey:FacilitySlingID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+}
+
+func (HESLOSling) TableName() string { return "heslo_slings" }
+
+type LoggingSling struct {
+	ID              []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	FlightDataID    []byte    `gorm:"type:binary(16);index;not null;column:flight_data_id"`
+	FacilitySlingID []byte    `gorm:"type:binary(16);index;column:facility_sling_id"`
+	CreatedAt       time.Time `gorm:"column:created_at"`
+
+	FacilitySling *facilitydomain.Facility `gorm:"foreignKey:FacilitySlingID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	FlightData    *FlightData              `gorm:"foreignKey:FlightDataID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (LoggingSling) TableName() string { return "logging_slings" }
+
+type HECFlight struct {
+	ID           []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	FlightDataID []byte    `gorm:"type:binary(16);index;not null;column:flight_data_id"`
+	ROT          int       `gorm:"not null;column:rot"`
+	HECCycle     int       `gorm:"not null;column:hec_cycle"`
+	EquipmentID  []byte    `gorm:"type:binary(16);column:equipment_id"`
+	CreatedAt    time.Time `gorm:"column:created_at"`
+
+	FlightData *FlightData              `gorm:"foreignKey:FlightDataID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	Equipment  *facilitydomain.Facility `gorm:"foreignKey:EquipmentID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+}
+
+func (HECFlight) TableName() string { return "hec_flights" }
+
+type HECSling struct {
+	ID           []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	FlightDataID []byte    `gorm:"type:binary(16);index;not null;column:flight_data_id"`
+	HECSlingID   []byte    `gorm:"type:binary(16);column:hec_sling_id"`
+	CreatedAt    time.Time `gorm:"column:created_at"`
+
+	FlightData *FlightData              `gorm:"foreignKey:FlightDataID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	HECSling   *facilitydomain.Facility `gorm:"foreignKey:HECSlingID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+}
+
+func (HECSling) TableName() string { return "hec_slings" }
+
+type HECLoads struct {
+	ID           []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	FlightDataID []byte    `gorm:"type:binary(16);index;not null;column:flight_data_id"`
+	LoadCategory string    `gorm:"type:varchar(20);not null;column:load_category"`
+	Quantity     int       `gorm:"not null;column:quantity"`
+	CreatedAt    time.Time `gorm:"column:created_at"`
+
+	FlightData *FlightData `gorm:"foreignKey:FlightDataID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (HECLoads) TableName() string { return "hec_loads" }
+
+type SPODetails struct {
+	HESLO   SPOHESLODetails
+	Logging SPOLoggingDetails
+	HEC     SPOHECDetails
+}
+
+type SPOHESLODetails struct {
+	Flights []SPOHESLOFlight
+	Slings  []SPOHESLOSling
+}
+
+type SPOHESLOFlight struct {
+	ID               []byte
+	ROT              int
+	FuelTruckID      []byte
+	FuelTruckName    string
+	LoggingSlingID   []byte
+	LoggingSlingName string
+}
+
+type SPOHESLOSling struct {
+	ID            []byte
+	HESLOFlightID []byte
+	SlingID       []byte
+	SlingName     string
+}
+
+type SPOLoggingDetails struct {
+	Slings []SPOLoggingSling
+}
+
+type SPOLoggingSling struct {
+	ID        []byte
+	SlingID   []byte
+	SlingName string
+}
+
+type SPOHECDetails struct {
+	Flights []SPOHECFlight
+	Slings  []SPOHECSling
+	Loads   []SPOHECLoad
+}
+
+type SPOHECFlight struct {
+	ID            []byte
+	ROT           int
+	HECCycle      int
+	EquipmentID   []byte
+	EquipmentName string
+}
+
+type SPOHECSling struct {
+	ID        []byte
+	SlingID   []byte
+	SlingName string
+}
+
+type SPOHECLoad struct {
+	ID           []byte
+	LoadCategory string
+	Quantity     int
+}
+
+// SPO upsert input types (write path)
+
+type SPOUpsertData struct {
+	HESLO   *SPOHESLOUpsert
+	Logging *SPOLoggingUpsert
+	HEC     *SPOHECUpsert
+}
+
+type SPOHESLOUpsert struct {
+	Flights []SPOHESLOFlightUpsert
+}
+
+type SPOHESLOFlightUpsert struct {
+	ROT            int
+	FuelTruckID    []byte
+	LoggingSlingID []byte
+	Slings         []SPOHESLOSlingUpsert
+}
+
+type SPOHESLOSlingUpsert struct {
+	SlingID []byte
+}
+
+type SPOLoggingUpsert struct {
+	Slings []SPOLoggingSlingUpsert
+}
+
+type SPOLoggingSlingUpsert struct {
+	SlingID []byte
+}
+
+type SPOHECUpsert struct {
+	Flights []SPOHECFlightUpsert
+	Slings  []SPOHECSlingUpsert
+	Loads   []SPOHECLoadUpsert
+}
+
+type SPOHECFlightUpsert struct {
+	ROT         int
+	HECCycle    int
+	EquipmentID []byte
+}
+
+type SPOHECSlingUpsert struct {
+	SlingID []byte
+}
+
+type SPOHECLoadUpsert struct {
+	LoadCategory string
+	Quantity     int
+}
diff --git a/internal/domain/flight_data/repository.go b/internal/domain/flight_data/repository.go
new file mode 100644
index 0000000..7446bf7
--- /dev/null
+++ b/internal/domain/flight_data/repository.go
@@ -0,0 +1,18 @@
+package flightdata
+
+import (
+	"context"
+)
+
+type Repository interface {
+	Create(ctx context.Context, row *FlightData) error
+	Update(ctx context.Context, row *FlightData) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*FlightData, error)
+	GetByFlightID(ctx context.Context, flightID []byte) (*FlightData, error)
+	GetByMissionID(ctx context.Context, missionID []byte) (*FlightData, error)
+	ListByMissionID(ctx context.Context, missionID []byte) ([]FlightData, error)
+	List(ctx context.Context, date string, missionID, flightDataID []byte, limit, offset int) ([]FlightData, int64, error)
+	GetSPODetailsByFlightDataID(ctx context.Context, flightDataID []byte) (*SPODetails, error)
+	UpsertSPODetails(ctx context.Context, flightDataID []byte, data *SPOUpsertData) error
+}
diff --git a/internal/domain/flight_data/service.go b/internal/domain/flight_data/service.go
new file mode 100644
index 0000000..dbe9b97
--- /dev/null
+++ b/internal/domain/flight_data/service.go
@@ -0,0 +1,19 @@
+package flightdata
+
+import (
+	"context"
+)
+
+type Service interface {
+	Create(ctx context.Context, row *FlightData) error
+	CreatePlaceholder(ctx context.Context, row *FlightData) error
+	Update(ctx context.Context, row *FlightData) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*FlightData, error)
+	GetByFlightID(ctx context.Context, flightID []byte) (*FlightData, error)
+	GetByMissionID(ctx context.Context, missionID []byte) (*FlightData, error)
+	ListByMissionID(ctx context.Context, missionID []byte) ([]FlightData, error)
+	List(ctx context.Context, date string, missionID, flightDataID []byte, limit, offset int) ([]FlightData, int64, error)
+	GetSPODetailsByFlightDataID(ctx context.Context, flightDataID []byte) (*SPODetails, error)
+	UpsertSPODetails(ctx context.Context, flightDataID []byte, data *SPOUpsertData) error
+}
diff --git a/internal/domain/flight_inspection/model.go b/internal/domain/flight_inspection/model.go
new file mode 100644
index 0000000..2ac1c86
--- /dev/null
+++ b/internal/domain/flight_inspection/model.go
@@ -0,0 +1,35 @@
+package flightinspection
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	StatusDraft      = "Draft"
+	StatusInProgress = "InProgress"
+	StatusCompleted  = "Completed"
+)
+
+type FlightInspection struct {
+	ID             []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	InspectionDate time.Time `gorm:"type:date;not null;index;column:inspection_date"`
+	Status         string    `gorm:"type:varchar(20);not null;default:Draft;index;check:chk_flight_inspection_status,status IN ('Draft','InProgress','Completed');column:status"`
+
+	CreatedAt time.Time `gorm:"column:created_at"`
+	CreatedBy []byte    `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time `gorm:"column:updated_at"`
+	UpdatedBy []byte    `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (FlightInspection) TableName() string { return "flight_inspections" }
+
+func (f *FlightInspection) BeforeCreate(tx *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/flight_inspection/repository.go b/internal/domain/flight_inspection/repository.go
new file mode 100644
index 0000000..0e4cb49
--- /dev/null
+++ b/internal/domain/flight_inspection/repository.go
@@ -0,0 +1,13 @@
+package flightinspection
+
+import "context"
+
+type FlightInspectionRepository interface {
+	Create(ctx context.Context, row *FlightInspection) error
+	Update(ctx context.Context, row *FlightInspection) error
+	GetByID(ctx context.Context, id []byte) (*FlightInspection, error)
+	List(ctx context.Context, sort string, limit, offset int) ([]FlightInspection, int64, error)
+}
+
+// Repository is kept as backward-compatible alias for older services/wirings.
+type Repository = FlightInspectionRepository
diff --git a/internal/domain/flight_inspection/service.go b/internal/domain/flight_inspection/service.go
new file mode 100644
index 0000000..782345c
--- /dev/null
+++ b/internal/domain/flight_inspection/service.go
@@ -0,0 +1,10 @@
+package flightinspection
+
+import "context"
+
+type FlightInspectionService interface {
+	CreateDraft(ctx context.Context, row *FlightInspection) error
+	Update(ctx context.Context, row *FlightInspection) error
+	GetByID(ctx context.Context, id []byte) (*FlightInspection, error)
+	List(ctx context.Context, sort string, limit, offset int) ([]FlightInspection, int64, error)
+}
diff --git a/internal/domain/flight_inspection_file_checklist/model.go b/internal/domain/flight_inspection_file_checklist/model.go
new file mode 100644
index 0000000..8b27e8c
--- /dev/null
+++ b/internal/domain/flight_inspection_file_checklist/model.go
@@ -0,0 +1,37 @@
+package flightinspectionfilechecklist
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	flightinspection "wucher/internal/domain/flight_inspection"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type FlightInspectionFileChecklist struct {
+	ID []byte `gorm:"type:binary(16);primaryKey;column:id"`
+
+	IsDone bool `gorm:"type:tinyint(1);not null;default:0;index:idx_flight_inspection_file_checklists_inspection_sorted;column:is_done"`
+
+	HelicopterFileID   []byte `gorm:"type:binary(16);not null;index:idx_flight_inspection_file_checklists_file;uniqueIndex:uidx_flight_inspection_file_checklists_inspection_file,priority:2;column:helicopter_file_id"`
+	FlightInspectionID []byte `gorm:"type:binary(16);not null;index:idx_flight_inspection_file_checklists_inspection;index:idx_flight_inspection_file_checklists_inspection_sorted;uniqueIndex:uidx_flight_inspection_file_checklists_inspection_file,priority:1;column:flight_inspection_id"`
+
+	CreatedAt time.Time `gorm:"column:created_at"`
+	CreatedBy []byte    `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time `gorm:"column:updated_at"`
+	UpdatedBy []byte    `gorm:"type:binary(16);column:updated_by"`
+
+	HelicopterFile   *helicopterfile.HelicopterFile     `gorm:"foreignKey:HelicopterFileID;references:ID"`
+	FlightInspection *flightinspection.FlightInspection `gorm:"foreignKey:FlightInspectionID;references:ID"`
+}
+
+func (FlightInspectionFileChecklist) TableName() string { return "flight_inspection_file_checklists" }
+
+func (m *FlightInspectionFileChecklist) BeforeCreate(_ *gorm.DB) error {
+	if len(m.ID) == 0 {
+		m.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/flight_inspection_file_checklist/repository.go b/internal/domain/flight_inspection_file_checklist/repository.go
new file mode 100644
index 0000000..82364ce
--- /dev/null
+++ b/internal/domain/flight_inspection_file_checklist/repository.go
@@ -0,0 +1,14 @@
+package flightinspectionfilechecklist
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *FlightInspectionFileChecklist) error
+	Update(ctx context.Context, row *FlightInspectionFileChecklist) error
+	Delete(ctx context.Context, id []byte) error
+	GetByID(ctx context.Context, id []byte) (*FlightInspectionFileChecklist, error)
+	List(ctx context.Context, filter string, sort string, limit, offset int) ([]FlightInspectionFileChecklist, int64, error)
+	ListByInspectionID(ctx context.Context, inspectionID []byte) ([]FlightInspectionFileChecklist, error)
+	FlightInspectionExists(ctx context.Context, inspectionID []byte) (bool, error)
+	HelicopterFileExists(ctx context.Context, helicopterFileID []byte) (bool, error)
+}
diff --git a/internal/domain/flight_inspection_file_checklist/service.go b/internal/domain/flight_inspection_file_checklist/service.go
new file mode 100644
index 0000000..10d8421
--- /dev/null
+++ b/internal/domain/flight_inspection_file_checklist/service.go
@@ -0,0 +1,14 @@
+package flightinspectionfilechecklist
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *FlightInspectionFileChecklist) error
+	Update(ctx context.Context, row *FlightInspectionFileChecklist) error
+	Delete(ctx context.Context, id []byte) error
+	GetByID(ctx context.Context, id []byte) (*FlightInspectionFileChecklist, error)
+	List(ctx context.Context, filter string, sort string, limit, offset int) ([]FlightInspectionFileChecklist, int64, error)
+	ListByInspectionID(ctx context.Context, inspectionID []byte) ([]FlightInspectionFileChecklist, error)
+	FlightInspectionExists(ctx context.Context, inspectionID []byte) (bool, error)
+	HelicopterFileExists(ctx context.Context, helicopterFileID []byte) (bool, error)
+}
diff --git a/internal/domain/flight_prep_check/model.go b/internal/domain/flight_prep_check/model.go
new file mode 100644
index 0000000..2cf7521
--- /dev/null
+++ b/internal/domain/flight_prep_check/model.go
@@ -0,0 +1,50 @@
+package flightprepcheck
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type FlightPrepCheck struct {
+	ID                    []byte    `gorm:"type:binary(16);primaryKey;column:id"`
+	NOTAMBriefing         bool      `gorm:"type:tinyint(1);not null;default:0;column:notam_briefing"`
+	WeatherBriefing       bool      `gorm:"type:tinyint(1);not null;default:0;column:weather_briefing"`
+	OperationalFlightPlan bool      `gorm:"type:tinyint(1);not null;default:0;column:operational_flight_plan"`
+	FlightInspectionID    []byte    `gorm:"type:binary(16);not null;uniqueIndex:uk_flight_prep_checks_inspection;column:flight_inspection_id"`
+	CreatedAt             time.Time `gorm:"column:created_at"`
+	CreatedBy             []byte    `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt             time.Time `gorm:"column:updated_at"`
+	UpdatedBy             []byte    `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (FlightPrepCheck) TableName() string { return "flight_prep_checks" }
+
+func (f *FlightPrepCheck) BeforeCreate(tx *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type ValidationError struct {
+	Status  int
+	Title   string
+	Pointer string
+	Detail  string
+}
+
+func (e *ValidationError) Error() string {
+	if e == nil {
+		return ""
+	}
+	return e.Detail
+}
+
+type UpsertRequest struct {
+	NOTAMBriefing         *bool `json:"notam_briefing,omitempty"`
+	WeatherBriefing       *bool `json:"weather_briefing,omitempty"`
+	OperationalFlightPlan *bool `json:"operational_flight_plan,omitempty"`
+}
diff --git a/internal/domain/flight_prep_check/repository.go b/internal/domain/flight_prep_check/repository.go
new file mode 100644
index 0000000..cb0f8d5
--- /dev/null
+++ b/internal/domain/flight_prep_check/repository.go
@@ -0,0 +1,10 @@
+package flightprepcheck
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, check *FlightPrepCheck) error
+	Update(ctx context.Context, check *FlightPrepCheck) error
+	GetByID(ctx context.Context, id []byte) (*FlightPrepCheck, error)
+	GetByFlightInspectionID(ctx context.Context, flightInspectionID []byte) (*FlightPrepCheck, error)
+}
diff --git a/internal/domain/flight_prep_check/service.go b/internal/domain/flight_prep_check/service.go
new file mode 100644
index 0000000..13e7507
--- /dev/null
+++ b/internal/domain/flight_prep_check/service.go
@@ -0,0 +1,10 @@
+package flightprepcheck
+
+import "context"
+
+type Service interface {
+	InitializeChecks(ctx context.Context, flightInspectionID []byte) (int, error)
+	GetByFlightInspection(ctx context.Context, flightInspectionID []byte) (*FlightPrepCheck, error)
+	UpdateCheck(ctx context.Context, checkID []byte, req *UpsertRequest) (*FlightPrepCheck, error)
+	UpsertByFlightInspection(ctx context.Context, flightInspectionID []byte, req *UpsertRequest) (*FlightPrepCheck, error)
+}
diff --git a/internal/domain/fm_report/errors.go b/internal/domain/fm_report/errors.go
new file mode 100644
index 0000000..338b16a
--- /dev/null
+++ b/internal/domain/fm_report/errors.go
@@ -0,0 +1,8 @@
+package fmreport
+
+import "errors"
+
+var (
+	ErrNotFound  = errors.New("fm report not found")
+	ErrCompleted = errors.New("fm report already completed")
+)
diff --git a/internal/domain/fm_report/fleet_history.go b/internal/domain/fm_report/fleet_history.go
new file mode 100644
index 0000000..483dac8
--- /dev/null
+++ b/internal/domain/fm_report/fleet_history.go
@@ -0,0 +1,79 @@
+package fmreport
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+// FleetHistory is the 1:1 snapshot of the flown helicopter's fleet status, frozen
+// when an FM report is created at after-flight inspection. It is read-only
+// afterwards so later complaints / maintenance changes do not alter a historical
+// report. Next-inspection rows use fixed columns (A/F, ENG1, ENG2, MAIN1, MAIN2)
+// mirroring the report layout.
+type FleetHistory struct {
+	ID         []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	FMReportID []byte `gorm:"type:binary(16);not null;uniqueIndex:uidx_fm_report_fleet_history_fm_report_id;column:fm_report_id"`
+
+	HelicopterStatus string `gorm:"type:varchar(16);column:helicopter_status"`
+
+	AirframeHours float64 `gorm:"type:decimal(12,2);not null;default:0;column:airframe_hours"`
+	Engine1Hours      float64 `gorm:"type:decimal(12,2);not null;default:0;column:engine1_hours"`
+	Engine2Hours      float64 `gorm:"type:decimal(12,2);not null;default:0;column:engine2_hours"`
+
+	AFType    string `gorm:"type:varchar(255);column:af_type"`
+	AFDue     string `gorm:"type:varchar(255);column:af_due"`
+	AFExt     string `gorm:"type:varchar(255);column:af_ext"`
+	Eng1Type  string `gorm:"type:varchar(255);column:eng1_type"`
+	Eng1Due   string `gorm:"type:varchar(255);column:eng1_due"`
+	Eng1Ext   string `gorm:"type:varchar(255);column:eng1_ext"`
+	Eng2Type  string `gorm:"type:varchar(255);column:eng2_type"`
+	Eng2Due   string `gorm:"type:varchar(255);column:eng2_due"`
+	Eng2Ext   string `gorm:"type:varchar(255);column:eng2_ext"`
+	Main1Type string `gorm:"type:varchar(255);column:main1_type"`
+	Main1Due  string `gorm:"type:varchar(255);column:main1_due"`
+	Main1Ext  string `gorm:"type:varchar(255);column:main1_ext"`
+	Main2Type string `gorm:"type:varchar(255);column:main2_type"`
+	Main2Due  string `gorm:"type:varchar(255);column:main2_due"`
+	Main2Ext  string `gorm:"type:varchar(255);column:main2_ext"`
+
+	EASAReleaseID              []byte     `gorm:"type:binary(16);column:easa_release_id"`
+	EASAIsSigned               bool       `gorm:"not null;default:false;column:easa_is_signed"`
+	EASADate                   *time.Time `gorm:"type:date;column:easa_date"`
+	EASAACHours                *string    `gorm:"type:varchar(20);column:easa_ac_hours"`
+	EASALocation               *string    `gorm:"type:varchar(255);column:easa_location"`
+	EASAWONo                   *string    `gorm:"type:varchar(100);column:easa_wo_no"`
+	EASAMaintManualRevAirframe *string    `gorm:"type:varchar(100);column:easa_maint_manual_rev_airframe"`
+	EASAMaintManualRevEngine   *string    `gorm:"type:varchar(100);column:easa_maint_manual_rev_engine"`
+	EASASignerID               *string    `gorm:"type:varchar(100);column:easa_signer_id"`
+	EASAPermitNo               *string    `gorm:"type:varchar(100);column:easa_permit_no"`
+	EASASignedAt               *time.Time `gorm:"type:datetime(3);column:easa_signed_at"`
+	EASASignedBy               []byte     `gorm:"type:binary(16);column:easa_signed_by"`
+
+	MCFID           []byte     `gorm:"type:binary(16);column:mcf_id"`
+	MCFIsSigned     bool       `gorm:"not null;default:false;column:mcf_is_signed"`
+	MCFDate         *time.Time `gorm:"type:date;column:mcf_date"`
+	MCFAFHours      *string    `gorm:"type:varchar(20);column:mcf_af_hours"`
+	MCFLandingCount *int       `gorm:"column:mcf_landing_count"`
+	MCFSignedBy     []byte     `gorm:"type:binary(16);column:mcf_signed_by"`
+	MCFSignedByName string     `gorm:"type:varchar(255);column:mcf_signed_by_name"`
+
+	CreatedAt time.Time `gorm:"column:created_at"`
+}
+
+func (FleetHistory) TableName() string { return "fm_report_fleet_history" }
+
+func (f *FleetHistory) BeforeCreate(_ *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+// HasEASA reports whether an EASA release was captured in this snapshot.
+func (f *FleetHistory) HasEASA() bool { return f != nil && len(f.EASAReleaseID) == 16 }
+
+// HasMCF reports whether an MCF was captured in this snapshot.
+func (f *FleetHistory) HasMCF() bool { return f != nil && len(f.MCFID) == 16 }
diff --git a/internal/domain/fm_report/model.go b/internal/domain/fm_report/model.go
new file mode 100644
index 0000000..bbff734
--- /dev/null
+++ b/internal/domain/fm_report/model.go
@@ -0,0 +1,41 @@
+package fmreport
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type Report struct {
+	ID                 []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	TakeoverID         []byte `gorm:"type:binary(16);not null;uniqueIndex:uidx_fm_reports_takeover_id;index;column:takeover_id"`
+	FlightID           []byte `gorm:"type:binary(16);not null;uniqueIndex:uidx_fm_reports_flight_id;index;column:flight_id"`
+	FlightInspectionID []byte `gorm:"type:binary(16);not null;uniqueIndex:uidx_fm_reports_flight_inspection_id;index;column:flight_inspection_id"`
+
+	HelicopterID []byte     `gorm:"type:binary(16);uniqueIndex:uidx_fm_reports_helicopter_report_code,priority:1;column:helicopter_id"`
+	ReportCode   *string    `gorm:"type:varchar(32);uniqueIndex:uidx_fm_reports_helicopter_report_code,priority:2;column:report_code"`
+	Engine1GpcN1 *string    `gorm:"type:varchar(255);null;column:engine1_gpc_n1"`
+	Engine1PtcN2 *string    `gorm:"type:varchar(255);null;column:engine1_ptc_n2"`
+	Engine2GpcN1 *string    `gorm:"type:varchar(255);null;column:engine2_gpc_n1"`
+	Engine2PtcN2 *string    `gorm:"type:varchar(255);null;column:engine2_ptc_n2"`
+	CompletedAt  *time.Time `gorm:"type:datetime(3);column:completed_at"`
+	CompletedBy  []byte     `gorm:"type:binary(16);column:completed_by"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at;index"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (Report) TableName() string { return "fm_reports" }
+
+func (r *Report) BeforeCreate(tx *gorm.DB) error {
+	if len(r.ID) == 0 {
+		r.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/fm_report/repository.go b/internal/domain/fm_report/repository.go
new file mode 100644
index 0000000..c38d0fb
--- /dev/null
+++ b/internal/domain/fm_report/repository.go
@@ -0,0 +1,37 @@
+package fmreport
+
+import (
+	"context"
+	"errors"
+)
+
+var ErrDuplicateReportCode = errors.New("duplicate report code")
+
+type ListFilter struct {
+	Search               string
+	FlightID             []byte
+	TakeoverID           []byte
+	FlightInspectionID   []byte
+	FlightDate           string
+	HasEngine1GpcN1      *bool
+	HasEngine1PtcN2      *bool
+	HasEngine2GpcN1      *bool
+	HasEngine2PtcN2      *bool
+	Sort                 string
+	FromDate             string
+	ToDate               string
+	HelicopterIdentifier string
+	PilotName            string
+}
+
+type Repository interface {
+	Upsert(ctx context.Context, row *Report) error
+	GetByFlightID(ctx context.Context, flightID []byte) (*Report, error)
+	GetByID(ctx context.Context, id []byte) (*Report, error)
+	MaxReportSeqByHelicopter(ctx context.Context, helicopterID []byte) (int, error)
+	SetReportCode(ctx context.Context, id []byte, code string) error
+	List(ctx context.Context, filter ListFilter, limit, offset int) ([]Report, int64, error)
+	Delete(ctx context.Context, id, deletedBy []byte) error
+	CreateFleetHistory(ctx context.Context, row *FleetHistory) error
+	GetFleetHistoryByReportID(ctx context.Context, reportID []byte) (*FleetHistory, error)
+}
diff --git a/internal/domain/fm_report/service.go b/internal/domain/fm_report/service.go
new file mode 100644
index 0000000..96a7ba8
--- /dev/null
+++ b/internal/domain/fm_report/service.go
@@ -0,0 +1,25 @@
+package fmreport
+
+import (
+	"context"
+
+	"wucher/internal/domain/flight"
+)
+
+type Service interface {
+	UpsertForFlight(ctx context.Context, flightRow *flight.Flight, flightInspectionID []byte) (*Report, error)
+	UpdateForFlight(ctx context.Context, flightID []byte, engine1GpcN1, engine1PtcN2, engine2GpcN1, engine2PtcN2 *string) (*Report, error)
+	GetByID(ctx context.Context, id []byte) (*Report, error)
+	GetByFlightID(ctx context.Context, flightID []byte) (*Report, error)
+	List(ctx context.Context, filter ListFilter, limit, offset int) ([]Report, int64, error)
+	GetFleetHistory(ctx context.Context, reportID []byte) (*FleetHistory, error)
+	Delete(ctx context.Context, id []byte) error
+}
+
+type FleetHistoryBuilder interface {
+	BuildFleetHistory(ctx context.Context, takeoverID []byte) *FleetHistory
+}
+
+type ReportCodeResolver interface {
+	ResolveHelicopterForReportCode(ctx context.Context, takeoverID []byte) (helicopterID []byte, reportPrefix string)
+}
diff --git a/internal/domain/forces_present/model.go b/internal/domain/forces_present/model.go
new file mode 100644
index 0000000..3b576a1
--- /dev/null
+++ b/internal/domain/forces_present/model.go
@@ -0,0 +1,32 @@
+package forces_present
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type ForcesPresent struct {
+	ID          []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	Name        string     `gorm:"type:varchar(128);not null;column:name"`
+	SortKey     *int       `gorm:"column:sortkey"`
+	Note        string     `gorm:"type:varchar(255);column:note"`
+	IsActive    bool       `gorm:"type:tinyint(1);index;not null;default:1;column:is_active"`
+	CreatedAt   time.Time  `gorm:"column:created_at"`
+	CreatedBy   []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt   time.Time  `gorm:"column:updated_at"`
+	UpdatedBy   []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt   *time.Time `gorm:"column:deleted_at"`
+	DeletedBy   []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (ForcesPresent) TableName() string { return "forces_present" }
+
+func (f *ForcesPresent) BeforeCreate(tx *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/forces_present/model_test.go b/internal/domain/forces_present/model_test.go
new file mode 100644
index 0000000..7a5e684
--- /dev/null
+++ b/internal/domain/forces_present/model_test.go
@@ -0,0 +1,37 @@
+package forces_present
+
+import (
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func TestForcesPresentTableName(t *testing.T) {
+	var m ForcesPresent
+	if got := m.TableName(); got != "forces_present" {
+		t.Fatalf("expected table name forces_present, got %q", got)
+	}
+}
+
+func TestForcesPresentBeforeCreate(t *testing.T) {
+	t.Run("generates id when empty", func(t *testing.T) {
+		m := &ForcesPresent{}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(m.ID) == 0 {
+			t.Fatalf("expected id to be generated")
+		}
+	})
+
+	t.Run("keeps existing id", func(t *testing.T) {
+		existing := []byte("already-set-id")
+		m := &ForcesPresent{ID: append([]byte(nil), existing...)}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if string(m.ID) != string(existing) {
+			t.Fatalf("expected existing id to stay unchanged")
+		}
+	})
+}
diff --git a/internal/domain/forces_present/repository.go b/internal/domain/forces_present/repository.go
new file mode 100644
index 0000000..e2ab19a
--- /dev/null
+++ b/internal/domain/forces_present/repository.go
@@ -0,0 +1,11 @@
+package forces_present
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *ForcesPresent) error
+	Update(ctx context.Context, row *ForcesPresent) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*ForcesPresent, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]ForcesPresent, int64, error)
+}
diff --git a/internal/domain/forces_present/service.go b/internal/domain/forces_present/service.go
new file mode 100644
index 0000000..6ae68e1
--- /dev/null
+++ b/internal/domain/forces_present/service.go
@@ -0,0 +1,11 @@
+package forces_present
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *ForcesPresent) error
+	Update(ctx context.Context, row *ForcesPresent) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*ForcesPresent, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]ForcesPresent, int64, error)
+}
diff --git a/internal/domain/health_insurance_companies/model.go b/internal/domain/health_insurance_companies/model.go
new file mode 100644
index 0000000..813f0b7
--- /dev/null
+++ b/internal/domain/health_insurance_companies/model.go
@@ -0,0 +1,52 @@
+package health_insurance_companies
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type HealthInsuranceCompany struct {
+	ID           []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	Name         string     `gorm:"type:varchar(128);not null;column:name"`
+	SortKey      *int       `gorm:"column:sortkey"`
+	LandID       []byte     `gorm:"type:binary(16);index;column:land_id"`
+	State        string     `gorm:"type:varchar(128);column:state"`
+	Address      string     `gorm:"type:varchar(256);column:address"`
+	MobileNumber string     `gorm:"type:varchar(20);column:mobile_number"`
+	Email        string     `gorm:"type:varchar(128);column:email"`
+	Note         string     `gorm:"type:text;column:note"`
+	IsActive     bool       `gorm:"type:tinyint(1);index;not null;default:1;column:is_active"`
+	CreatedAt    time.Time  `gorm:"column:created_at"`
+	CreatedBy    []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt    time.Time  `gorm:"column:updated_at"`
+	UpdatedBy    []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt    *time.Time `gorm:"column:deleted_at"`
+	DeletedBy    []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (HealthInsuranceCompany) TableName() string { return "health_insurance_companies" }
+
+type StateDetail struct {
+	LandID         string
+	FederalStateID string
+	FederalState   string
+	LandName       string
+	LandISOCode    string
+}
+
+// LandDetail is used to enrich health insurance company responses from land_id.
+type LandDetail struct {
+	LandID      string
+	LandName    string
+	LandISOCode string
+}
+
+func (h *HealthInsuranceCompany) BeforeCreate(tx *gorm.DB) error {
+	if len(h.ID) == 0 {
+		h.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/health_insurance_companies/model_test.go b/internal/domain/health_insurance_companies/model_test.go
new file mode 100644
index 0000000..c553043
--- /dev/null
+++ b/internal/domain/health_insurance_companies/model_test.go
@@ -0,0 +1,37 @@
+package health_insurance_companies
+
+import (
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func TestHealthInsuranceCompanyTableName(t *testing.T) {
+	var m HealthInsuranceCompany
+	if got := m.TableName(); got != "health_insurance_companies" {
+		t.Fatalf("expected table name health_insurance_companies, got %q", got)
+	}
+}
+
+func TestHealthInsuranceCompanyBeforeCreate(t *testing.T) {
+	t.Run("generates id when empty", func(t *testing.T) {
+		m := &HealthInsuranceCompany{}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(m.ID) == 0 {
+			t.Fatalf("expected id to be generated")
+		}
+	})
+
+	t.Run("keeps existing id", func(t *testing.T) {
+		existing := []byte("already-set-id")
+		m := &HealthInsuranceCompany{ID: append([]byte(nil), existing...)}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if string(m.ID) != string(existing) {
+			t.Fatalf("expected existing id to stay unchanged")
+		}
+	})
+}
diff --git a/internal/domain/health_insurance_companies/repository.go b/internal/domain/health_insurance_companies/repository.go
new file mode 100644
index 0000000..bb1b523
--- /dev/null
+++ b/internal/domain/health_insurance_companies/repository.go
@@ -0,0 +1,13 @@
+package health_insurance_companies
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *HealthInsuranceCompany) error
+	Update(ctx context.Context, row *HealthInsuranceCompany) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*HealthInsuranceCompany, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]HealthInsuranceCompany, int64, error)
+	ResolveStateDetails(ctx context.Context, stateNames []string) (map[string]StateDetail, error)
+	ResolveLandDetails(ctx context.Context, landIDs []string) (map[string]LandDetail, error)
+}
diff --git a/internal/domain/health_insurance_companies/service.go b/internal/domain/health_insurance_companies/service.go
new file mode 100644
index 0000000..58dd1f1
--- /dev/null
+++ b/internal/domain/health_insurance_companies/service.go
@@ -0,0 +1,13 @@
+package health_insurance_companies
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *HealthInsuranceCompany) error
+	Update(ctx context.Context, row *HealthInsuranceCompany) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*HealthInsuranceCompany, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]HealthInsuranceCompany, int64, error)
+	ResolveStateDetails(ctx context.Context, stateNames []string) (map[string]StateDetail, error)
+	ResolveLandDetails(ctx context.Context, landIDs []string) (map[string]LandDetail, error)
+}
diff --git a/internal/domain/helicopter/model.go b/internal/domain/helicopter/model.go
new file mode 100644
index 0000000..43ce34a
--- /dev/null
+++ b/internal/domain/helicopter/model.go
@@ -0,0 +1,128 @@
+package helicopter
+
+import (
+	"gorm.io/gorm"
+	"time"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	StatusAvailable = "available"
+	StatusBooked    = "booked"
+	StatusAOG       = "aog"
+	StatusMCF       = "mcf"
+)
+
+const (
+	AOGSourceUnknown   = ""
+	AOGSourceManual    = "manual"
+	AOGSourceAuto      = "auto"
+	AOGSourceComplaint = "complaint"
+)
+
+// StatusRank is the display order for fleet and hold/defect listings — most critical
+// first: MCF, then AOG, then Booked, then Available (any unknown status sorts last).
+func StatusRank(status string) int {
+	switch status {
+	case StatusMCF:
+		return 0
+	case StatusAOG:
+		return 1
+	case StatusBooked:
+		return 2
+	case StatusAvailable:
+		return 3
+	default:
+		return 4
+	}
+}
+
+func IsValidStatus(s string) bool {
+	switch s {
+	case StatusAvailable, StatusBooked, StatusAOG, StatusMCF:
+		return true
+	default:
+		return false
+	}
+}
+
+type StatusInput struct {
+	IsBook            bool
+	IsMCF             bool
+	ComplaintGrounded bool
+}
+
+func (h *Helicopter) DeriveStatus(in StatusInput) string {
+	switch {
+	case in.IsMCF:
+		return StatusMCF
+	case h.AirOnGround || in.ComplaintGrounded:
+		return StatusAOG
+	case in.IsBook:
+		return StatusBooked
+	default:
+		return StatusAvailable
+	}
+}
+
+func (h *Helicopter) EnforceAOGInactive() {
+	if h.AirOnGround {
+		h.IsActive = false
+	}
+}
+
+func (h *Helicopter) EnforceMCFInactive(mcf bool) {
+	if mcf {
+		h.IsActive = false
+	}
+}
+
+type SortKeyPatch struct {
+	Set   bool
+	Value *int
+}
+
+type Helicopter struct {
+	ID               []byte                  `gorm:"type:binary(16);primaryKey;column:id"`
+	Designation      string                  `gorm:"type:varchar(100);not null;column:designation"`
+	Identifier       string                  `gorm:"type:varchar(100);uniqueIndex;not null;column:identifier"`
+	ReportSequence   int                     `gorm:"not null;default:0;column:report_sequence"`
+	Type             string                  `gorm:"type:varchar(100);not null;column:type"`
+	SortKey          *int                    `gorm:"column:sortkey"`
+	Engine1          string                  `gorm:"type:varchar(100);column:engine_1"`
+	Engine2          string                  `gorm:"type:varchar(100);column:engine_2"`
+	Consumption      float64                 `gorm:"type:decimal(10,2);not null;default:0;column:consumption_lt_min"`
+	NR1              bool                    `gorm:"type:tinyint(1);not null;default:0;column:nr1"`
+	NR2              bool                    `gorm:"type:tinyint(1);not null;default:0;column:nr2"`
+	LH               bool                    `gorm:"type:tinyint(1);not null;default:0;column:lh"`
+	RH               bool                    `gorm:"type:tinyint(1);not null;default:0;column:rh"`
+	MGB              bool                    `gorm:"type:tinyint(1);not null;default:0;column:mgb"`
+	IGB              bool                    `gorm:"type:tinyint(1);not null;default:0;column:igb"`
+	TGB              bool                    `gorm:"type:tinyint(1);not null;default:0;column:tgb"`
+	UTCOffset        int                     `gorm:"not null;default:0;column:utc_offset"`
+	FotoAttachmentID []byte                  `gorm:"type:binary(16);index;column:foto_attachment_id"`
+	Dry              bool                    `gorm:"type:tinyint(1);not null;default:0;column:dry"`
+	AirOnGround      bool                    `gorm:"type:tinyint(1);not null;default:0;column:air_on_ground"`
+	AOGReason        string                  `gorm:"type:text;column:aog_reason"`
+	AOGSource        string                  `gorm:"type:varchar(16);not null;default:'';column:aog_source"`
+	Note             string                  `gorm:"type:text;column:note"`
+	IsActive         bool                    `gorm:"type:tinyint(1);index;not null;default:1;column:is_active"`
+	CreatedBy        []byte                  `gorm:"type:binary(16);column:created_by"`
+	UpdatedBy        []byte                  `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt        *time.Time              `gorm:"column:deleted_at"`
+	CreatedByName    string                  `gorm:"->;column:created_by_name"`
+	UpdatedByName    string                  `gorm:"->;column:updated_by_name"`
+	FotoAttachment   *filemanager.Attachment `gorm:"foreignKey:FotoAttachmentID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	CreatedAt        time.Time
+	UpdatedAt        time.Time
+}
+
+func (Helicopter) TableName() string { return "helicopters" }
+
+func (h *Helicopter) BeforeCreate(tx *gorm.DB) error {
+	if len(h.ID) == 0 {
+		h.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/helicopter/model_test.go b/internal/domain/helicopter/model_test.go
new file mode 100644
index 0000000..aab0801
--- /dev/null
+++ b/internal/domain/helicopter/model_test.go
@@ -0,0 +1,53 @@
+package helicopter
+
+import "testing"
+
+func TestHelicopterEnforceAOGInactive(t *testing.T) {
+	cases := []struct {
+		name        string
+		airOnGround bool
+		initActive  bool
+		want        bool
+	}{
+		{name: "aog forces inactive", airOnGround: true, initActive: true, want: false},
+		{name: "aog stays inactive", airOnGround: true, initActive: false, want: false},
+		{name: "not aog keeps manual active", airOnGround: false, initActive: true, want: true},
+		{name: "not aog keeps manual inactive", airOnGround: false, initActive: false, want: false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			h := Helicopter{AirOnGround: tc.airOnGround, IsActive: tc.initActive}
+			h.EnforceAOGInactive()
+			if h.IsActive != tc.want {
+				t.Fatalf("IsActive = %v, want %v", h.IsActive, tc.want)
+			}
+		})
+	}
+}
+
+func TestHelicopterDeriveStatus(t *testing.T) {
+	cases := []struct {
+		name        string
+		airOnGround bool
+		mcf         bool
+		isInUse     bool
+		want        string
+	}{
+		{name: "available when idle", airOnGround: false, mcf: false, isInUse: false, want: StatusAvailable},
+		{name: "booked when in use", airOnGround: false, mcf: false, isInUse: true, want: StatusBooked},
+		{name: "mcf when mcf flagged", airOnGround: false, mcf: true, isInUse: false, want: StatusMCF},
+		{name: "mcf outranks booked", airOnGround: false, mcf: true, isInUse: true, want: StatusMCF},
+		{name: "aog when on ground", airOnGround: true, mcf: false, isInUse: false, want: StatusAOG},
+		{name: "aog outranks booked", airOnGround: true, mcf: false, isInUse: true, want: StatusAOG},
+		{name: "mcf outranks aog", airOnGround: true, mcf: true, isInUse: false, want: StatusMCF},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			h := Helicopter{AirOnGround: tc.airOnGround}
+			if got := h.DeriveStatus(StatusInput{IsBook: tc.isInUse, IsMCF: tc.mcf}); got != tc.want {
+				t.Fatalf("DeriveStatus() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
diff --git a/internal/domain/helicopter/repository.go b/internal/domain/helicopter/repository.go
new file mode 100644
index 0000000..4fa8f67
--- /dev/null
+++ b/internal/domain/helicopter/repository.go
@@ -0,0 +1,16 @@
+package helicopter
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, helicopter *Helicopter) error
+	Update(ctx context.Context, helicopter *Helicopter) error
+	ExistsByIdentifier(ctx context.Context, identifier string, excludeID []byte) (bool, error)
+	Delete(ctx context.Context, id []byte) error
+	GetByID(ctx context.Context, id []byte) (*Helicopter, error)
+	List(ctx context.Context, filter string, statuses []string, sort string, limit, offset int, groundedIDs [][]byte) ([]Helicopter, int64, error)
+	NextReportNumber(ctx context.Context, id []byte) (string, int, error)
+	IsInUse(ctx context.Context, id []byte) (bool, error)
+	InUseByAircraftIDs(ctx context.Context, ids [][]byte) (map[string]bool, error)
+	ActiveFlightIDByAircraftIDs(ctx context.Context, ids [][]byte) (map[string][]byte, error)
+}
diff --git a/internal/domain/helicopter/service.go b/internal/domain/helicopter/service.go
new file mode 100644
index 0000000..8448802
--- /dev/null
+++ b/internal/domain/helicopter/service.go
@@ -0,0 +1,17 @@
+package helicopter
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, helicopter *Helicopter) error
+	Update(ctx context.Context, helicopter *Helicopter) error
+	ExistsByIdentifier(ctx context.Context, identifier string, excludeID []byte) (bool, error)
+	ApplySortKeyPatch(helicopter *Helicopter, patch SortKeyPatch)
+	Delete(ctx context.Context, id []byte) error
+	GetByID(ctx context.Context, id []byte) (*Helicopter, error)
+	List(ctx context.Context, filter string, statuses []string, sort string, limit, offset int, groundedIDs [][]byte) ([]Helicopter, int64, error)
+	NextReportNumber(ctx context.Context, id []byte) (string, int, error)
+	IsInUse(ctx context.Context, id []byte) (bool, error)
+	InUseByAircraftIDs(ctx context.Context, ids [][]byte) (map[string]bool, error)
+	ActiveFlightIDByAircraftIDs(ctx context.Context, ids [][]byte) (map[string][]byte, error)
+}
diff --git a/internal/domain/helicopter_file/model.go b/internal/domain/helicopter_file/model.go
new file mode 100644
index 0000000..a79b652
--- /dev/null
+++ b/internal/domain/helicopter_file/model.go
@@ -0,0 +1,46 @@
+package helicopterfile
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/helicopter"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	SectionBeforeFirstFlightInspection = "bfi"
+	SectionFlightPreparationAndWB      = "fpwb"
+	SectionAfterLastFlightInspection   = "afi"
+)
+
+type HelicopterFile struct {
+	ID          []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	Section     string `gorm:"type:varchar(64);not null;index;check:chk_helicopter_files_section,section IN ('bfi','fpwb','afi');column:section"`
+	Position    int    `gorm:"column:position;not null;default:1"`
+	IsMandatory bool   `gorm:"column:is_mandatory;not null;default:false"`
+
+	HelicopterID     []byte `gorm:"type:binary(16);not null;index;column:helicopter_id"`
+	FileAttachmentID []byte `gorm:"type:binary(16);index;column:file_attachment_id"`
+	SourceFileID     []byte `gorm:"type:binary(16);index;column:source_file_id"`
+
+	CreatedAt time.Time `gorm:"column:created_at"`
+	CreatedBy []byte    `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time `gorm:"column:updated_at"`
+	UpdatedBy []byte    `gorm:"type:binary(16);column:updated_by"`
+
+	Helicopter     *helicopter.Helicopter  `gorm:"foreignKey:HelicopterID;references:ID"`
+	FileAttachment *filemanager.Attachment `gorm:"foreignKey:FileAttachmentID;references:ID"`
+	SourceFile     *filemanager.File       `gorm:"foreignKey:SourceFileID;references:ID"`
+}
+
+func (HelicopterFile) TableName() string { return "helicopter_files" }
+
+func (m *HelicopterFile) BeforeCreate(_ *gorm.DB) error {
+	if len(m.ID) == 0 {
+		m.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/helicopter_file/repository.go b/internal/domain/helicopter_file/repository.go
new file mode 100644
index 0000000..cd22aae
--- /dev/null
+++ b/internal/domain/helicopter_file/repository.go
@@ -0,0 +1,17 @@
+package helicopterfile
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *HelicopterFile) error
+	Update(ctx context.Context, row *HelicopterFile) error
+	Delete(ctx context.Context, id []byte) error
+	GetByID(ctx context.Context, id []byte) (*HelicopterFile, error)
+	List(ctx context.Context, filter string, sort string, limit, offset int) ([]HelicopterFile, int64, error)
+	ListPendingAttachments(ctx context.Context, limit int) ([]HelicopterFile, error)
+	ListPendingAttachmentsBySourceFileID(ctx context.Context, sourceFileID []byte, limit int) ([]HelicopterFile, error)
+	ListByHelicopter(ctx context.Context, helicopterID []byte) ([]HelicopterFile, error)
+	ListByHelicopterAndSection(ctx context.Context, helicopterID []byte, section string) ([]HelicopterFile, error)
+	HelicopterExists(ctx context.Context, helicopterID []byte) (bool, error)
+	AttachmentExists(ctx context.Context, attachmentID []byte) (bool, error)
+}
diff --git a/internal/domain/helicopter_file/service.go b/internal/domain/helicopter_file/service.go
new file mode 100644
index 0000000..c724c3d
--- /dev/null
+++ b/internal/domain/helicopter_file/service.go
@@ -0,0 +1,59 @@
+package helicopterfile
+
+import (
+	"context"
+
+	filemanager "wucher/internal/domain/file_manager"
+)
+
+type BulkItemError struct {
+	Status int
+	Title  string
+	Detail string
+}
+
+type UploadIntentBulkInput struct {
+	Type        string
+	Name        string
+	ContentType string
+	SizeBytes   int64
+}
+
+type UploadIntentBulkItemResult struct {
+	Index   int
+	Success bool
+	Grant   *filemanager.FileUploadIntentGrant
+	Error   *BulkItemError
+}
+
+type CreateBulkInput struct {
+	Type             string
+	Section          string
+	Position         *int
+	IsMandatory      *bool
+	HelicopterID     string
+	UploadIntentUUID string
+	FileName         string
+	FolderUUID       *string
+}
+
+type CreateBulkItemResult struct {
+	Index   int
+	Success bool
+	Row     *HelicopterFile
+	Error   *BulkItemError
+}
+
+type Service interface {
+	Create(ctx context.Context, row *HelicopterFile) error
+	Update(ctx context.Context, row *HelicopterFile) error
+	Delete(ctx context.Context, id []byte) error
+	GetByID(ctx context.Context, id []byte) (*HelicopterFile, error)
+	List(ctx context.Context, filter string, sort string, limit, offset int) ([]HelicopterFile, int64, error)
+	ListByHelicopter(ctx context.Context, helicopterID []byte) ([]HelicopterFile, error)
+	ListByHelicopterAndSection(ctx context.Context, helicopterID []byte, section string) ([]HelicopterFile, error)
+	HelicopterExists(ctx context.Context, helicopterID []byte) (bool, error)
+	AttachmentExists(ctx context.Context, attachmentID []byte) (bool, error)
+	RequestUploadIntentsBulk(ctx context.Context, inputs []UploadIntentBulkInput, actorID []byte) []UploadIntentBulkItemResult
+	CreateFromUploadIntentsBulk(ctx context.Context, inputs []CreateBulkInput, actorID []byte) []CreateBulkItemResult
+}
diff --git a/internal/domain/helicopter_usage/flight_day_stats.go b/internal/domain/helicopter_usage/flight_day_stats.go
new file mode 100644
index 0000000..0be1c5d
--- /dev/null
+++ b/internal/domain/helicopter_usage/flight_day_stats.go
@@ -0,0 +1,12 @@
+package helicopter_usage
+
+// FlightDayStats is the flight-derived contribution of a single flight ("today") — the same
+// quantities that feed the cumulative totals, but scoped to one flight. Engine hours mirror
+// airframe hours; engine GPC/PTC/CCC are not flight-derived and are resolved elsewhere.
+type FlightDayStats struct {
+	AirframeHours   float64
+	AirframeCycles  float64
+	Landing         float64
+	HookRelease     float64
+	RotorBrakeCycle float64
+}
diff --git a/internal/domain/helicopter_usage/model.go b/internal/domain/helicopter_usage/model.go
new file mode 100644
index 0000000..8a1c379
--- /dev/null
+++ b/internal/domain/helicopter_usage/model.go
@@ -0,0 +1,105 @@
+package helicopter_usage
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	helicopterdomain "wucher/internal/domain/helicopter"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type HelicopterUsage struct {
+	ID                   []byte                       `gorm:"type:binary(16);primaryKey;column:id"`
+	HelicopterID         []byte                       `gorm:"type:binary(16);not null;uniqueIndex:uidx_helicopter_usage_helicopter_id;index;column:helicopter_id"`
+	Helicopter           *helicopterdomain.Helicopter `gorm:"foreignKey:HelicopterID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:RESTRICT"`
+	TotalLanding         float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_landing"`
+	TotalAirframeHours   float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_airframe_hours"`
+	TotalAirframeCycles  float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_airframe_cycles"`
+	TotalEngine1Hours    float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_engine_1_hours"`
+	TotalEngine1GpcNgN1  float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_engine_1_gpc_ng_n1"`
+	TotalEngine1PtcNfN2  float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_engine_1_ptc_nf_n2"`
+	TotalEngine1Ccc      float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_engine_1_ccc"`
+	TotalEngine2Hours    float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_engine_2_hours"`
+	TotalEngine2GpcNgN1  float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_engine_2_gpc_ng_n1"`
+	TotalEngine2PtcNfN2  float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_engine_2_ptc_nf_n2"`
+	TotalEngine2Ccc      float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_engine_2_ccc"`
+	TotalFlightReport    float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_flight_report"`
+	TotalHookRelease     float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_hook_release"`
+	TotalRotorBrakeCycle float64                      `gorm:"type:decimal(12,2);not null;default:0;column:total_rotor_brake_cycle"`
+
+	ManualAirframeHours   float64 `gorm:"type:decimal(12,2);not null;default:0;column:manual_airframe_hours"`
+	ManualAirframeCycles  float64 `gorm:"type:decimal(12,2);not null;default:0;column:manual_airframe_cycles"`
+	ManualEngine1Hours    float64 `gorm:"type:decimal(12,2);not null;default:0;column:manual_engine_1_hours"`
+	ManualEngine1GpcNgN1  float64 `gorm:"type:decimal(12,2);not null;default:0;column:manual_engine_1_gpc_ng_n1"`
+	ManualEngine1PtcNfN2  float64 `gorm:"type:decimal(12,2);not null;default:0;column:manual_engine_1_ptc_nf_n2"`
+	ManualEngine2Hours    float64 `gorm:"type:decimal(12,2);not null;default:0;column:manual_engine_2_hours"`
+	ManualEngine2GpcNgN1  float64 `gorm:"type:decimal(12,2);not null;default:0;column:manual_engine_2_gpc_ng_n1"`
+	ManualEngine2PtcNfN2  float64 `gorm:"type:decimal(12,2);not null;default:0;column:manual_engine_2_ptc_nf_n2"`
+	ManualLanding         float64 `gorm:"type:decimal(12,2);not null;default:0;column:manual_landing"`
+	ManualFlightReport    float64 `gorm:"type:decimal(12,2);not null;default:0;column:manual_flight_report"`
+	ManualHookRelease     float64 `gorm:"type:decimal(12,2);not null;default:0;column:manual_hook_release"`
+	ManualRotorBrakeCycle float64 `gorm:"type:decimal(12,2);not null;default:0;column:manual_rotor_brake_cycle"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at;index"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (HelicopterUsage) TableName() string { return "helicopter_usage" }
+
+func (h *HelicopterUsage) BeforeCreate(_ *gorm.DB) error {
+	if len(h.ID) == 0 {
+		h.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type ManualSummaryInput struct {
+	AirframeHours   *float64
+	AirframeCycles  *float64
+	Engine1Hours    *float64
+	Engine1GpcNgN1  *float64
+	Engine1PtcNfN2  *float64
+	Engine1Ccc      *float64
+	Engine2Hours    *float64
+	Engine2GpcNgN1  *float64
+	Engine2PtcNfN2  *float64
+	Engine2Ccc      *float64
+	Landing         *float64
+	FlightReport    *float64
+	HookRelease     *float64
+	RotorBrakeCycle *float64
+}
+
+func (h *HelicopterUsage) ApplyManualSummary(in ManualSummaryInput) {
+	reviseFloatTotal(&h.TotalAirframeHours, &h.ManualAirframeHours, in.AirframeHours)
+	reviseFloatTotal(&h.TotalAirframeCycles, &h.ManualAirframeCycles, in.AirframeCycles)
+	reviseFloatTotal(&h.TotalEngine1Hours, &h.ManualEngine1Hours, in.Engine1Hours)
+	reviseFloatTotal(&h.TotalEngine1GpcNgN1, &h.ManualEngine1GpcNgN1, in.Engine1GpcNgN1)
+	reviseFloatTotal(&h.TotalEngine1PtcNfN2, &h.ManualEngine1PtcNfN2, in.Engine1PtcNfN2)
+	reviseFloatTotal(&h.TotalEngine2Hours, &h.ManualEngine2Hours, in.Engine2Hours)
+	reviseFloatTotal(&h.TotalEngine2GpcNgN1, &h.ManualEngine2GpcNgN1, in.Engine2GpcNgN1)
+	reviseFloatTotal(&h.TotalEngine2PtcNfN2, &h.ManualEngine2PtcNfN2, in.Engine2PtcNfN2)
+	reviseFloatTotal(&h.TotalLanding, &h.ManualLanding, in.Landing)
+	reviseFloatTotal(&h.TotalFlightReport, &h.ManualFlightReport, in.FlightReport)
+	reviseFloatTotal(&h.TotalHookRelease, &h.ManualHookRelease, in.HookRelease)
+	reviseFloatTotal(&h.TotalRotorBrakeCycle, &h.ManualRotorBrakeCycle, in.RotorBrakeCycle)
+	if in.Engine1Ccc != nil {
+		h.TotalEngine1Ccc = *in.Engine1Ccc
+	}
+	if in.Engine2Ccc != nil {
+		h.TotalEngine2Ccc = *in.Engine2Ccc
+	}
+}
+
+func reviseFloatTotal(total, manual, desired *float64) {
+	if desired == nil {
+		return
+	}
+	*manual += *desired - *total
+	*total = *desired
+}
diff --git a/internal/domain/helicopter_usage/model_test.go b/internal/domain/helicopter_usage/model_test.go
new file mode 100644
index 0000000..87bbb07
--- /dev/null
+++ b/internal/domain/helicopter_usage/model_test.go
@@ -0,0 +1,36 @@
+package helicopter_usage
+
+import "testing"
+
+func f64(v float64) *float64 { return &v }
+
+func TestApplyManualSummary_SeedBackComputed(t *testing.T) {
+	h := &HelicopterUsage{TotalAirframeHours: 5} // aggregated 5, manual 0
+	h.ApplyManualSummary(ManualSummaryInput{AirframeHours: f64(6000)})
+	if h.TotalAirframeHours != 6000 {
+		t.Fatalf("total = %v, want 6000", h.TotalAirframeHours)
+	}
+	if h.ManualAirframeHours != 5995 {
+		t.Fatalf("manual = %v, want 5995 (6000-5)", h.ManualAirframeHours)
+	}
+}
+
+func TestApplyManualSummary_NewFlightAccumulates(t *testing.T) {
+	h := &HelicopterUsage{TotalAirframeHours: 5}
+	h.ApplyManualSummary(ManualSummaryInput{AirframeHours: f64(6000)})
+	// a new +10h flight raises aggregated from 5 to 15; RefreshAll recomputes Total = aggregated + manual.
+	if got := 15.0 + h.ManualAirframeHours; got != 6010 {
+		t.Fatalf("post-flight total = %v, want 6010", got)
+	}
+}
+
+func TestApplyManualSummary_CccDirectAndNilUntouched(t *testing.T) {
+	h := &HelicopterUsage{TotalEngine1Ccc: 2, TotalLanding: 100}
+	h.ApplyManualSummary(ManualSummaryInput{Engine1Ccc: f64(44)})
+	if h.TotalEngine1Ccc != 44 {
+		t.Fatalf("ccc = %v, want 44", h.TotalEngine1Ccc)
+	}
+	if h.ManualEngine1GpcNgN1 != 0 || h.TotalLanding != 100 {
+		t.Fatal("nil inputs must leave fields untouched")
+	}
+}
diff --git a/internal/domain/helicopter_usage/repository.go b/internal/domain/helicopter_usage/repository.go
new file mode 100644
index 0000000..d1c8fce
--- /dev/null
+++ b/internal/domain/helicopter_usage/repository.go
@@ -0,0 +1,13 @@
+package helicopter_usage
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *HelicopterUsage) error
+	Update(ctx context.Context, row *HelicopterUsage) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*HelicopterUsage, error)
+	GetByHelicopterID(ctx context.Context, helicopterID []byte) (*HelicopterUsage, error)
+	FlightStatsByFlightID(ctx context.Context, flightID []byte) (FlightDayStats, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]HelicopterUsage, int64, error)
+}
diff --git a/internal/domain/helicopter_usage/service.go b/internal/domain/helicopter_usage/service.go
new file mode 100644
index 0000000..4af1d0b
--- /dev/null
+++ b/internal/domain/helicopter_usage/service.go
@@ -0,0 +1,13 @@
+package helicopter_usage
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *HelicopterUsage) error
+	Update(ctx context.Context, row *HelicopterUsage) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*HelicopterUsage, error)
+	GetByHelicopterID(ctx context.Context, helicopterID []byte) (*HelicopterUsage, error)
+	FlightStatsByFlightID(ctx context.Context, flightID []byte) (FlightDayStats, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]HelicopterUsage, int64, error)
+}
diff --git a/internal/domain/hospital/model.go b/internal/domain/hospital/model.go
new file mode 100644
index 0000000..b49f07a
--- /dev/null
+++ b/internal/domain/hospital/model.go
@@ -0,0 +1,36 @@
+package hospital
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type Hospital struct {
+	ID             []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	Name           string     `gorm:"type:varchar(128);not null;column:hospital_name"`
+	SortKey        *int       `gorm:"column:sortkey"`
+	Address        string     `gorm:"type:varchar(256);column:address"`
+	LandlineNumber string     `gorm:"type:varchar(20);column:landline_number"`
+	MobileNumber   string     `gorm:"type:varchar(20);column:mobile_number"`
+	Email          string     `gorm:"type:varchar(128);column:email"`
+	Note           string     `gorm:"type:text;column:note"`
+	IsActive       bool       `gorm:"type:tinyint(1);index;not null;default:1;column:is_active"`
+	CreatedAt      time.Time  `gorm:"column:created_at"`
+	CreatedBy      []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt      time.Time  `gorm:"column:updated_at"`
+	UpdatedBy      []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt      *time.Time `gorm:"column:deleted_at"`
+	DeletedBy      []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (Hospital) TableName() string { return "no_icao_codes" }
+
+func (h *Hospital) BeforeCreate(tx *gorm.DB) error {
+	if len(h.ID) == 0 {
+		h.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/hospital/model_test.go b/internal/domain/hospital/model_test.go
new file mode 100644
index 0000000..0518df2
--- /dev/null
+++ b/internal/domain/hospital/model_test.go
@@ -0,0 +1,37 @@
+package hospital
+
+import (
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func TestHospitalTableName(t *testing.T) {
+	var m Hospital
+	if got := m.TableName(); got != "no_icao_codes" {
+		t.Fatalf("expected table name no_icao_codes, got %q", got)
+	}
+}
+
+func TestHospitalBeforeCreate(t *testing.T) {
+	t.Run("generates id when empty", func(t *testing.T) {
+		m := &Hospital{}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(m.ID) == 0 {
+			t.Fatalf("expected id to be generated")
+		}
+	})
+
+	t.Run("keeps existing id", func(t *testing.T) {
+		existing := []byte("already-set-id")
+		m := &Hospital{ID: append([]byte(nil), existing...)}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if string(m.ID) != string(existing) {
+			t.Fatalf("expected existing id to stay unchanged")
+		}
+	})
+}
diff --git a/internal/domain/hospital/repository.go b/internal/domain/hospital/repository.go
new file mode 100644
index 0000000..d82ef27
--- /dev/null
+++ b/internal/domain/hospital/repository.go
@@ -0,0 +1,11 @@
+package hospital
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, hospital *Hospital) error
+	Update(ctx context.Context, hospital *Hospital) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Hospital, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]Hospital, int64, error)
+}
diff --git a/internal/domain/hospital/service.go b/internal/domain/hospital/service.go
new file mode 100644
index 0000000..d5e674a
--- /dev/null
+++ b/internal/domain/hospital/service.go
@@ -0,0 +1,11 @@
+package hospital
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, hospital *Hospital) error
+	Update(ctx context.Context, hospital *Hospital) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Hospital, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]Hospital, int64, error)
+}
diff --git a/internal/domain/icao/model.go b/internal/domain/icao/model.go
new file mode 100644
index 0000000..e55137f
--- /dev/null
+++ b/internal/domain/icao/model.go
@@ -0,0 +1,45 @@
+package icao
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/federal_state"
+	"wucher/internal/domain/land"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type ICAO struct {
+	ID             []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	FederalStateID []byte `gorm:"type:binary(16);index;column:federal_state_id"`
+	LandID         []byte `gorm:"type:binary(16);index;column:land_id"`
+	ICAOCode       string `gorm:"type:varchar(16);not null;column:icao_code"`
+	Name           string `gorm:"type:varchar(150);not null;column:name"`
+	SortKey        *int   `gorm:"column:sortkey"`
+	Address        string `gorm:"type:varchar(256);column:address"`
+	LandlineNumber string `gorm:"type:varchar(20);column:landline_number"`
+	MobileNumber   string `gorm:"type:varchar(20);column:mobile_number"`
+	Email          string `gorm:"type:varchar(128);column:email"`
+	Note           string `gorm:"type:text;column:note"`
+	IsActive       bool   `gorm:"type:tinyint(1);index;not null;default:1;column:is_active"`
+
+	FederalState *federal_state.FederalState `gorm:"foreignKey:FederalStateID;references:ID"`
+	Land         *land.Land                  `gorm:"foreignKey:LandID;references:ID"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (ICAO) TableName() string { return "icaos" }
+
+func (i *ICAO) BeforeCreate(tx *gorm.DB) error {
+	if len(i.ID) == 0 {
+		i.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/icao/model_test.go b/internal/domain/icao/model_test.go
new file mode 100644
index 0000000..db19b6c
--- /dev/null
+++ b/internal/domain/icao/model_test.go
@@ -0,0 +1,37 @@
+package icao
+
+import (
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func TestICAOTableName(t *testing.T) {
+	var m ICAO
+	if got := m.TableName(); got != "icaos" {
+		t.Fatalf("expected table name icaos, got %q", got)
+	}
+}
+
+func TestICAOBeforeCreate(t *testing.T) {
+	t.Run("generates id when empty", func(t *testing.T) {
+		m := &ICAO{}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(m.ID) == 0 {
+			t.Fatalf("expected id to be generated")
+		}
+	})
+
+	t.Run("keeps existing id", func(t *testing.T) {
+		existing := []byte("already-set-id")
+		m := &ICAO{ID: append([]byte(nil), existing...)}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if string(m.ID) != string(existing) {
+			t.Fatalf("expected existing id to stay unchanged")
+		}
+	})
+}
diff --git a/internal/domain/icao/repository.go b/internal/domain/icao/repository.go
new file mode 100644
index 0000000..078c71b
--- /dev/null
+++ b/internal/domain/icao/repository.go
@@ -0,0 +1,11 @@
+package icao
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *ICAO) error
+	Update(ctx context.Context, row *ICAO) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*ICAO, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]ICAO, int64, error)
+}
diff --git a/internal/domain/icao/service.go b/internal/domain/icao/service.go
new file mode 100644
index 0000000..69cd5ed
--- /dev/null
+++ b/internal/domain/icao/service.go
@@ -0,0 +1,11 @@
+package icao
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *ICAO) error
+	Update(ctx context.Context, row *ICAO) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*ICAO, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]ICAO, int64, error)
+}
diff --git a/internal/domain/insurance_patient_data/model.go b/internal/domain/insurance_patient_data/model.go
new file mode 100644
index 0000000..f2aa116
--- /dev/null
+++ b/internal/domain/insurance_patient_data/model.go
@@ -0,0 +1,35 @@
+package insurance_patient_data
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/federal_state"
+	"wucher/internal/domain/health_insurance_companies"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type InsurancePatientData struct {
+	ID                         []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	HealthInsuranceCompaniesId []byte `gorm:"type:binary(16);index;column:health_insurance_companies_id"`
+	FederalStateId             []byte `gorm:"type:binary(16);index;column:federal_state_id"`
+
+	HealthInsuranceCompanies *health_insurance_companies.HealthInsuranceCompany `gorm:"foreignKey:HealthInsuranceCompaniesId;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	FederalState             *federal_state.FederalState                        `gorm:"foreignKey:FederalStateId;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	CreatedAt                time.Time                                          `gorm:"column:created_at"`
+	CreatedBy                []byte                                             `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt                time.Time                                          `gorm:"column:updated_at"`
+	UpdatedBy                []byte                                             `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt                *time.Time                                         `gorm:"column:deleted_at"`
+	DeletedBy                []byte                                             `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (InsurancePatientData) TableName() string { return "insurance_patient_data" }
+
+func (i *InsurancePatientData) BeforeCreate(tx *gorm.DB) error {
+	if len(i.ID) == 0 {
+		i.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/insurance_patient_data/repository.go b/internal/domain/insurance_patient_data/repository.go
new file mode 100644
index 0000000..32baf73
--- /dev/null
+++ b/internal/domain/insurance_patient_data/repository.go
@@ -0,0 +1,11 @@
+package insurance_patient_data
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *InsurancePatientData) error
+	Update(ctx context.Context, row *InsurancePatientData) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*InsurancePatientData, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]InsurancePatientData, int64, error)
+}
diff --git a/internal/domain/insurance_patient_data/service.go b/internal/domain/insurance_patient_data/service.go
new file mode 100644
index 0000000..7d50765
--- /dev/null
+++ b/internal/domain/insurance_patient_data/service.go
@@ -0,0 +1,11 @@
+package insurance_patient_data
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *InsurancePatientData) error
+	Update(ctx context.Context, row *InsurancePatientData) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*InsurancePatientData, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]InsurancePatientData, int64, error)
+}
diff --git a/internal/domain/land/model.go b/internal/domain/land/model.go
new file mode 100644
index 0000000..adad4a9
--- /dev/null
+++ b/internal/domain/land/model.go
@@ -0,0 +1,34 @@
+package land
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type Land struct {
+	ID          []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	Name        string     `gorm:"type:varchar(128);not null;column:name"`
+	Note        string     `gorm:"type:text;column:note"`
+	LandISOCode string     `gorm:"type:varchar(8);not null;default:'';uniqueIndex:uq_lands_land_iso_code;column:land_iso_code"`
+	BMDExportID *string    `gorm:"type:varchar(10);column:bmd_export_id"`
+	SortKey     *int       `gorm:"column:sortkey"`
+	IsActive    bool       `gorm:"type:tinyint(1);index;not null;default:1;column:is_active"`
+	CreatedAt   time.Time  `gorm:"column:created_at"`
+	CreatedBy   []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt   time.Time  `gorm:"column:updated_at"`
+	UpdatedBy   []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt   *time.Time `gorm:"column:deleted_at"`
+	DeletedBy   []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (Land) TableName() string { return "lands" }
+
+func (l *Land) BeforeCreate(tx *gorm.DB) error {
+	if len(l.ID) == 0 {
+		l.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/land/model_test.go b/internal/domain/land/model_test.go
new file mode 100644
index 0000000..4b91e8f
--- /dev/null
+++ b/internal/domain/land/model_test.go
@@ -0,0 +1,37 @@
+package land
+
+import (
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func TestLandTableName(t *testing.T) {
+	var m Land
+	if got := m.TableName(); got != "lands" {
+		t.Fatalf("expected table name lands, got %q", got)
+	}
+}
+
+func TestLandBeforeCreate(t *testing.T) {
+	t.Run("generates id when empty", func(t *testing.T) {
+		m := &Land{}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(m.ID) == 0 {
+			t.Fatalf("expected id to be generated")
+		}
+	})
+
+	t.Run("keeps existing id", func(t *testing.T) {
+		existing := []byte("already-set-id")
+		m := &Land{ID: append([]byte(nil), existing...)}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if string(m.ID) != string(existing) {
+			t.Fatalf("expected existing id to stay unchanged")
+		}
+	})
+}
diff --git a/internal/domain/land/repository.go b/internal/domain/land/repository.go
new file mode 100644
index 0000000..ffc2619
--- /dev/null
+++ b/internal/domain/land/repository.go
@@ -0,0 +1,11 @@
+package land
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *Land) error
+	Update(ctx context.Context, row *Land) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Land, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]Land, int64, error)
+}
diff --git a/internal/domain/land/service.go b/internal/domain/land/service.go
new file mode 100644
index 0000000..c6f52b3
--- /dev/null
+++ b/internal/domain/land/service.go
@@ -0,0 +1,11 @@
+package land
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *Land) error
+	Update(ctx context.Context, row *Land) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Land, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]Land, int64, error)
+}
diff --git a/internal/domain/master_settings/model_master_settings.go b/internal/domain/master_settings/model_master_settings.go
new file mode 100644
index 0000000..ecf2ecb
--- /dev/null
+++ b/internal/domain/master_settings/model_master_settings.go
@@ -0,0 +1,65 @@
+package mastersettings
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type MasterSettings struct {
+	ID          []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	CompanyName string     `gorm:"type:varchar(255);not null;column:company_name"`
+	Title       string     `gorm:"type:varchar(255);column:title"`
+	Subtitle    string     `gorm:"type:varchar(255);column:subtitle"`
+	LogoFileID  []byte     `gorm:"type:binary(16);column:logo_file_id"`
+	LogoURL     *string    `gorm:"type:varchar(512);column:logo_url"`
+	CoverFileID []byte     `gorm:"type:binary(16);column:cover_file_id"`
+	CreatedAt   time.Time  `gorm:"column:created_at"`
+	CreatedBy   []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt   time.Time  `gorm:"column:updated_at"`
+	UpdatedBy   []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt   *time.Time `gorm:"column:deleted_at"`
+	DeletedBy   []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (MasterSettings) TableName() string { return "master_settings" }
+
+type MasterSettingValue struct {
+	SettingKey  string    `gorm:"type:varchar(120);primaryKey;column:setting_key"`
+	Value       string    `gorm:"type:text;not null;column:value"`
+	IsEncrypted bool      `gorm:"type:tinyint(1);not null;default:0;column:is_encrypted"`
+	CreatedAt   time.Time `gorm:"column:created_at"`
+	CreatedBy   []byte    `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt   time.Time `gorm:"column:updated_at"`
+	UpdatedBy   []byte    `gorm:"type:binary(16);column:updated_by"`
+}
+
+func (MasterSettingValue) TableName() string { return "master_setting_values" }
+
+const (
+	SettingMicrosoftEntraTenantID     = "MS_ENTRA_TENANT_ID"
+	SettingMicrosoftEntraClientID     = "MS_ENTRA_CLIENT_ID"
+	SettingMicrosoftEntraClientSecret = "MS_ENTRA_CLIENT_SECRET"
+	SettingMicrosoftEntraRedirectURL  = "MS_ENTRA_REDIRECT_URL"
+	SettingMicrosoftEntraAuthority    = "MS_ENTRA_AUTHORITY"
+	SettingMicrosoftEntraScopes       = "MS_ENTRA_SCOPES"
+	SettingAuthLoginEmailOTPEnabled   = "AUTH_LOGIN_EMAIL_OTP_ENABLED"
+)
+
+var MicrosoftEntraSettingKeys = []string{
+	SettingMicrosoftEntraTenantID,
+	SettingMicrosoftEntraClientID,
+	SettingMicrosoftEntraClientSecret,
+	SettingMicrosoftEntraRedirectURL,
+	SettingMicrosoftEntraAuthority,
+	SettingMicrosoftEntraScopes,
+}
+
+func (m *MasterSettings) BeforeCreate(tx *gorm.DB) error {
+	if len(m.ID) == 0 {
+		m.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/master_settings/repository.go b/internal/domain/master_settings/repository.go
new file mode 100644
index 0000000..5c8a1f4
--- /dev/null
+++ b/internal/domain/master_settings/repository.go
@@ -0,0 +1,13 @@
+package mastersettings
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *MasterSettings) error
+	Update(ctx context.Context, row *MasterSettings) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*MasterSettings, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]MasterSettings, int64, error)
+	UpsertSettingValues(ctx context.Context, rows []MasterSettingValue) error
+	GetSettingValuesByKeys(ctx context.Context, keys []string) ([]MasterSettingValue, error)
+}
diff --git a/internal/domain/master_settings/service.go b/internal/domain/master_settings/service.go
new file mode 100644
index 0000000..9c4cfd9
--- /dev/null
+++ b/internal/domain/master_settings/service.go
@@ -0,0 +1,31 @@
+package mastersettings
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *MasterSettings) error
+	Update(ctx context.Context, row *MasterSettings) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*MasterSettings, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]MasterSettings, int64, error)
+	UpsertMicrosoftEntraConfig(ctx context.Context, input MicrosoftEntraConfigInput, actor []byte) (*MicrosoftEntraConfigView, error)
+	GetMicrosoftEntraConfig(ctx context.Context) (*MicrosoftEntraConfigView, error)
+}
+
+type MicrosoftEntraConfigInput struct {
+	TenantID     string
+	ClientID     string
+	ClientSecret string
+	RedirectURL  string
+	Authority    string
+	Scopes       string
+}
+
+type MicrosoftEntraConfigView struct {
+	TenantID           string
+	ClientID           string
+	ClientSecretMasked string
+	RedirectURL        string
+	Authority          string
+	Scopes             string
+}
diff --git a/internal/domain/mcf/errors.go b/internal/domain/mcf/errors.go
new file mode 100644
index 0000000..be4dcd6
--- /dev/null
+++ b/internal/domain/mcf/errors.go
@@ -0,0 +1,5 @@
+package mcf
+
+import "errors"
+
+var ErrNotFound = errors.New("maintenance check flight not found")
diff --git a/internal/domain/mcf/model.go b/internal/domain/mcf/model.go
new file mode 100644
index 0000000..105bea5
--- /dev/null
+++ b/internal/domain/mcf/model.go
@@ -0,0 +1,89 @@
+package mcf
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	ResultPassed = "passed"
+	ResultFailed = "failed"
+)
+
+type MaintenanceCheckFlight struct {
+	ID           []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	HelicopterID []byte `gorm:"type:binary(16);not null;index;column:helicopter_id"`
+	FlightID []byte `gorm:"type:binary(16);index;column:flight_id"`
+
+	Date         *time.Time `gorm:"type:date;column:date"`
+	AFHours      string     `gorm:"type:varchar(20);column:af_hours"`
+	LandingCount int        `gorm:"type:int;column:landing_count"`
+	UTCtime      *time.Time `gorm:"type:datetime(3);column:utc_time"`
+
+	DecidedBy []byte     `gorm:"type:binary(16);column:decided_by"`
+	DecidedAt *time.Time `gorm:"type:datetime(3);column:decided_at"`
+
+	Result      *string    `gorm:"type:varchar(20);column:result"`
+	Notes       *string    `gorm:"type:text;column:notes"`
+	CompletedAt *time.Time `gorm:"type:datetime(3);column:completed_at"`
+	CompletedBy []byte     `gorm:"type:binary(16);column:completed_by"`
+
+	// Cancelled marks a DRAFT MCF that was set to "No" without ever being signed — the
+	// check flight never happened ("tidak jadi"). It releases the MCF status but the row
+	// is kept as a cancelled record in the list. A signed MCF is a real event, not cancellable.
+	CancelledAt *time.Time `gorm:"type:datetime(3);column:cancelled_at"`
+	CancelledBy []byte     `gorm:"type:binary(16);column:cancelled_by"`
+
+	CreatedAt time.Time  `gorm:"type:datetime(3);column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"type:datetime(3);column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"type:datetime(3);index;column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (MaintenanceCheckFlight) TableName() string { return "maintenance_check_flights" }
+
+func (m *MaintenanceCheckFlight) BeforeCreate(_ *gorm.DB) error {
+	if len(m.ID) == 0 {
+		m.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+func (m *MaintenanceCheckFlight) IsComplete() bool {
+	return m != nil && m.CompletedAt != nil
+}
+
+func (m *MaintenanceCheckFlight) IsCancelled() bool {
+	return m != nil && m.CancelledAt != nil
+}
+
+// IsOpen reports whether the MCF is an active (open) draft: not signed, not cancelled.
+func (m *MaintenanceCheckFlight) IsOpen() bool {
+	return m != nil && m.CompletedAt == nil && m.CancelledAt == nil
+}
+
+// IsCleared reports whether the MCF is done, releasing the aircraft from MCF status. Once
+// the MCF is SIGNED (completed) it is considered done regardless of pass/fail — the result
+// is recorded, but signing itself takes the helicopter out of MCF. A draft (not yet signed)
+// is NOT cleared.
+func (m *MaintenanceCheckFlight) IsCleared() bool {
+	return m != nil && m.CompletedAt != nil
+}
+
+func (m *MaintenanceCheckFlight) IsPending() bool {
+	return m != nil && !m.IsCleared()
+}
+
+func IsValidResult(s string) bool {
+	switch s {
+	case ResultPassed, ResultFailed:
+		return true
+	default:
+		return false
+	}
+}
diff --git a/internal/domain/mcf/model_test.go b/internal/domain/mcf/model_test.go
new file mode 100644
index 0000000..777dd20
--- /dev/null
+++ b/internal/domain/mcf/model_test.go
@@ -0,0 +1,81 @@
+package mcf
+
+import (
+	"testing"
+	"time"
+)
+
+func result(v string) *string { return &v }
+
+func TestMaintenanceCheckFlightState(t *testing.T) {
+	now := time.Now()
+	cases := []struct {
+		name         string
+		row          *MaintenanceCheckFlight
+		wantComplete bool
+		wantCleared  bool
+		wantPending  bool
+	}{
+		{name: "nil", row: nil, wantComplete: false, wantCleared: false, wantPending: false},
+		{name: "draft (not flown)", row: &MaintenanceCheckFlight{}, wantComplete: false, wantCleared: false, wantPending: true},
+		// Once signed the MCF is done regardless of result — signing clears MCF status.
+		{name: "signed failed is done", row: &MaintenanceCheckFlight{CompletedAt: &now, Result: result(ResultFailed)}, wantComplete: true, wantCleared: true, wantPending: false},
+		{name: "signed passed is done", row: &MaintenanceCheckFlight{CompletedAt: &now, Result: result(ResultPassed)}, wantComplete: true, wantCleared: true, wantPending: false},
+		{name: "result set without completedAt still pending", row: &MaintenanceCheckFlight{Result: result(ResultFailed)}, wantComplete: false, wantCleared: false, wantPending: true},
+		// A draft edited with result=passed but NOT yet signed must NOT clear the aircraft.
+		{name: "passed result on unsigned draft is NOT cleared", row: &MaintenanceCheckFlight{Result: result(ResultPassed)}, wantComplete: false, wantCleared: false, wantPending: true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := tc.row.IsComplete(); got != tc.wantComplete {
+				t.Errorf("IsComplete() = %v, want %v", got, tc.wantComplete)
+			}
+			if got := tc.row.IsCleared(); got != tc.wantCleared {
+				t.Errorf("IsCleared() = %v, want %v", got, tc.wantCleared)
+			}
+			if got := tc.row.IsPending(); got != tc.wantPending {
+				t.Errorf("IsPending() = %v, want %v", got, tc.wantPending)
+			}
+		})
+	}
+}
+
+func TestIsValidResult(t *testing.T) {
+	cases := []struct {
+		in   string
+		want bool
+	}{
+		{ResultPassed, true},
+		{ResultFailed, true},
+		{"partial", false},
+		{"", false},
+		{"PASSED", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.in, func(t *testing.T) {
+			if got := IsValidResult(tc.in); got != tc.want {
+				t.Fatalf("IsValidResult(%q) = %v, want %v", tc.in, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestMCFTableNameAndBeforeCreate(t *testing.T) {
+	if (MaintenanceCheckFlight{}).TableName() != "maintenance_check_flights" {
+		t.Fatalf("unexpected table name")
+	}
+	m := &MaintenanceCheckFlight{}
+	if err := m.BeforeCreate(nil); err != nil {
+		t.Fatalf("BeforeCreate err: %v", err)
+	}
+	if len(m.ID) == 0 {
+		t.Fatal("BeforeCreate should set ID")
+	}
+	prev := string(m.ID)
+	if err := m.BeforeCreate(nil); err != nil {
+		t.Fatalf("BeforeCreate err: %v", err)
+	}
+	if string(m.ID) != prev {
+		t.Fatal("BeforeCreate must not overwrite an existing ID")
+	}
+}
diff --git a/internal/domain/mcf/repository.go b/internal/domain/mcf/repository.go
new file mode 100644
index 0000000..672938d
--- /dev/null
+++ b/internal/domain/mcf/repository.go
@@ -0,0 +1,17 @@
+package mcf
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *MaintenanceCheckFlight) error
+	Update(ctx context.Context, row *MaintenanceCheckFlight) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*MaintenanceCheckFlight, error)
+	ListByHelicopter(ctx context.Context, helicopterID []byte) ([]MaintenanceCheckFlight, error)
+	GetLatestByHelicopter(ctx context.Context, helicopterID []byte) (*MaintenanceCheckFlight, error)
+	LatestByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]*MaintenanceCheckFlight, error)
+	PendingHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]bool, error)
+	// HelicopterHasOpenMCF reports whether the helicopter has a draft (not yet
+	// completed/signed) MCF — used to enforce one open MCF per helicopter.
+	HelicopterHasOpenMCF(ctx context.Context, helicopterID []byte) (bool, error)
+}
diff --git a/internal/domain/mcf/service.go b/internal/domain/mcf/service.go
new file mode 100644
index 0000000..d3161a4
--- /dev/null
+++ b/internal/domain/mcf/service.go
@@ -0,0 +1,15 @@
+package mcf
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *MaintenanceCheckFlight) error
+	Update(ctx context.Context, row *MaintenanceCheckFlight) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*MaintenanceCheckFlight, error)
+	ListByHelicopter(ctx context.Context, helicopterID []byte) ([]MaintenanceCheckFlight, error)
+	GetLatestByHelicopter(ctx context.Context, helicopterID []byte) (*MaintenanceCheckFlight, error)
+	LatestByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]*MaintenanceCheckFlight, error)
+	PendingHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]bool, error)
+	HelicopterHasOpenMCF(ctx context.Context, helicopterID []byte) (bool, error)
+}
diff --git a/internal/domain/medicine/model.go b/internal/domain/medicine/model.go
new file mode 100644
index 0000000..9787a1d
--- /dev/null
+++ b/internal/domain/medicine/model.go
@@ -0,0 +1,89 @@
+package medicine
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type Medicine struct {
+	ID              []byte          `gorm:"type:binary(16);primaryKey;column:id"`
+	Name            string          `gorm:"type:varchar(128);not null;column:name"`
+	SortKey         *int            `gorm:"column:sortkey"`
+	Note            string          `gorm:"type:varchar(255);column:note"`
+	Pack            string          `gorm:"type:varchar(128);column:pack"`
+	Unit            string          `gorm:"type:varchar(50);column:unit"`
+	Weight          *int64          `gorm:"type:bigint;column:weight"`
+	Column          int64           `gorm:"type:bigint;column:column"`
+	MedicineGroupID []byte          `gorm:"type:binary(16);index;column:medicine_group_id"`
+	MotorReactionID []byte          `gorm:"type:binary(16);index;column:motor_reaction_id"`
+	IsActive        bool            `gorm:"type:tinyint(1);index;not null;default:1;column:is_active"`
+	CreatedAt       time.Time       `gorm:"column:created_at"`
+	CreatedBy       []byte          `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt       time.Time       `gorm:"column:updated_at"`
+	UpdatedBy       []byte          `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt       *time.Time      `gorm:"column:deleted_at"`
+	DeletedBy       []byte          `gorm:"type:binary(16);column:deleted_by"`
+	MedicineGroup   *MedicineGroup  `gorm:"foreignKey:MedicineGroupID;references:ID"`
+	MotorReaction   *MotorReaction  `gorm:"foreignKey:MotorReactionID;references:ID"`
+	MotorReactions  []MotorReaction `gorm:"many2many:medicine_motor_reactions;joinForeignKey:MedicineID;joinReferences:MotorReactionID"`
+}
+
+func (Medicine) TableName() string { return "medicines" }
+
+func (m *Medicine) BeforeCreate(tx *gorm.DB) error {
+	if len(m.ID) == 0 {
+		m.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type MedicineGroup struct {
+	ID        []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	Name      string     `gorm:"type:varchar(255);not null;column:name"`
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (MedicineGroup) TableName() string { return "medicine_groups" }
+
+func (g *MedicineGroup) BeforeCreate(tx *gorm.DB) error {
+	if len(g.ID) == 0 {
+		g.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type MotorReaction struct {
+	ID        []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	Name      string     `gorm:"type:varchar(255);not null;column:name"`
+	Score     *int64     `gorm:"type:bigint;column:score"`
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (MotorReaction) TableName() string { return "motor_reactions" }
+
+func (r *MotorReaction) BeforeCreate(tx *gorm.DB) error {
+	if len(r.ID) == 0 {
+		r.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type MedicineMotorReaction struct {
+	MedicineID      []byte `gorm:"type:binary(16);primaryKey;column:medicine_id"`
+	MotorReactionID []byte `gorm:"type:binary(16);primaryKey;column:motor_reaction_id"`
+}
+
+func (MedicineMotorReaction) TableName() string { return "medicine_motor_reactions" }
diff --git a/internal/domain/medicine/model_test.go b/internal/domain/medicine/model_test.go
new file mode 100644
index 0000000..78aa5d4
--- /dev/null
+++ b/internal/domain/medicine/model_test.go
@@ -0,0 +1,37 @@
+package medicine
+
+import (
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func TestMedicineTableName(t *testing.T) {
+	var m Medicine
+	if got := m.TableName(); got != "medicines" {
+		t.Fatalf("expected table name medicines, got %q", got)
+	}
+}
+
+func TestMedicineBeforeCreate(t *testing.T) {
+	t.Run("generates id when empty", func(t *testing.T) {
+		m := &Medicine{}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(m.ID) == 0 {
+			t.Fatalf("expected id to be generated")
+		}
+	})
+
+	t.Run("keeps existing id", func(t *testing.T) {
+		existing := []byte("already-set-id")
+		m := &Medicine{ID: append([]byte(nil), existing...)}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if string(m.ID) != string(existing) {
+			t.Fatalf("expected existing id to stay unchanged")
+		}
+	})
+}
diff --git a/internal/domain/medicine/repository.go b/internal/domain/medicine/repository.go
new file mode 100644
index 0000000..68f54ed
--- /dev/null
+++ b/internal/domain/medicine/repository.go
@@ -0,0 +1,11 @@
+package medicine
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, medicine *Medicine) error
+	Update(ctx context.Context, medicine *Medicine) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Medicine, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]Medicine, int64, error)
+}
diff --git a/internal/domain/medicine/service.go b/internal/domain/medicine/service.go
new file mode 100644
index 0000000..1a98529
--- /dev/null
+++ b/internal/domain/medicine/service.go
@@ -0,0 +1,11 @@
+package medicine
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, medicine *Medicine) error
+	Update(ctx context.Context, medicine *Medicine) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Medicine, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]Medicine, int64, error)
+}
diff --git a/internal/domain/mission/errors.go b/internal/domain/mission/errors.go
new file mode 100644
index 0000000..5ae8c24
--- /dev/null
+++ b/internal/domain/mission/errors.go
@@ -0,0 +1,40 @@
+package mission
+
+import "errors"
+
+var (
+	ErrRequired                    = errors.New("mission required")
+	ErrMissionIDRequired           = errors.New("mission id required")
+	ErrFileAttachmentIDRequired    = errors.New("mission file_attachment_id required")
+	ErrFlightIDRequired            = errors.New("mission flight_id required")
+	ErrTypeInvalid                 = errors.New("mission type invalid")
+	ErrSubtypeInvalid              = errors.New("mission subtype invalid")
+	ErrSubtypeRequired             = errors.New("mission subtype required")
+	ErrSubtypeForbidden            = errors.New("mission subtype forbidden")
+	ErrDuplicateFlight             = errors.New("mission duplicate flight")
+	ErrScheduleMissing             = errors.New("mission schedule not found")
+	ErrBaseMissing                 = errors.New("mission base not found")
+	ErrTwilightMissing             = errors.New("mission twilight time not available")
+	ErrCoordinatesInvalid          = errors.New("base coordinates invalid")
+	ErrLockedAfterFlightInspection = errors.New("mission locked by after_flight_inspection")
+)
+
+const (
+	ErrorMessageRequired                    = "mission is required"
+	ErrorMessageMissionIDRequired           = "mission_id is required"
+	ErrorMessageFlightIDRequired            = "flight_id is required"
+	ErrorMessageTypeInvalid                 = "type is invalid or not found in mission category"
+	ErrorMessageSubtypeRequired             = "subtype_id is required when type is HEMS"
+	ErrorMessageSubtypeInvalid              = "subtype_id is invalid or not found"
+	ErrorMessageSubtypeForbidden            = "subtype_id is only allowed when type is HEMS"
+	ErrorMessageDuplicateFlight             = "mission for this flight already exists"
+	ErrorMessageNotFound                    = "mission not found"
+	ErrorMessageInvalidMissionID            = "mission_id is invalid UUID"
+	ErrorMessageInvalidFlightID             = "flight_id is invalid UUID"
+	ErrorMessageInvalidFlight               = "flight_uuid is invalid UUID"
+	ErrorMessageScheduleMissing             = "mission schedule not found for the mission date"
+	ErrorMessageBaseMissing                 = "mission base not found"
+	ErrorMessageTwilightMissing             = "civil twilight time could not be calculated for this base and date"
+	ErrorMessageCoordinatesInvalid          = "base coordinates are invalid"
+	ErrorMessageLockedAfterFlightInspection = "mission is locked because after flight inspection already exists"
+)
diff --git a/internal/domain/mission/model.go b/internal/domain/mission/model.go
new file mode 100644
index 0000000..7cdf54a
--- /dev/null
+++ b/internal/domain/mission/model.go
@@ -0,0 +1,118 @@
+package mission
+
+import (
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/flight"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type Mission struct {
+	ID                []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	FlightID          []byte `gorm:"type:binary(16);not null;index;column:flight_id"`
+	FlightDataID      []byte `gorm:"type:binary(16);index;column:flight_data_id"`
+	MissionCategoryID []byte `gorm:"type:binary(16);index;column:mission_category_id"`
+	SubtypeID         []byte `gorm:"type:binary(16);index;column:subtype_id"`
+	Type             string `gorm:"type:varchar(20);not null;index;column:type"`
+	Code             string `gorm:"type:varchar(32);index;column:code"`
+	Note             string `gorm:"type:varchar(255);column:note"`
+	StartTime        string `gorm:"type:time;column:start_time"`
+	EndTime          string `gorm:"type:time;column:end_time"`
+	FlightDataStatus string `gorm:"->;column:flight_data_status"`
+
+	Flight             *flight.Flight      `gorm:"foreignKey:FlightID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	MissionCategory    *MissionCategory    `gorm:"foreignKey:MissionCategoryID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	MissionSubCategory *MissionSubCategory `gorm:"foreignKey:SubtypeID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	Files              []MissionFile       `gorm:"foreignKey:MissionID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at;index"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (Mission) TableName() string { return "missions" }
+
+type ListFilter struct {
+	Search           string
+	Sort             string
+	FlightID         []byte
+	FlightDataStatus string
+	StartDate        *time.Time
+	EndDate          *time.Time
+	MissionType      string
+	PilotID          []byte
+	HelicopterID     []byte
+}
+
+type MissionFile struct {
+	ID               []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	MissionID        []byte `gorm:"type:binary(16);not null;index;column:mission_id"`
+	FileAttachmentID []byte `gorm:"type:binary(16);not null;index;column:file_attachment_id"`
+
+	Mission        *Mission                `gorm:"foreignKey:MissionID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	FileAttachment *filemanager.Attachment `gorm:"foreignKey:FileAttachmentID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (MissionFile) TableName() string { return "mission_files" }
+
+func (m *MissionFile) BeforeCreate(_ *gorm.DB) error {
+	if len(m.ID) == 0 {
+		m.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+func (m *Mission) BeforeCreate(_ *gorm.DB) error {
+	if len(m.ID) == 0 {
+		m.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type MissionCategory struct {
+	ID       []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	CodeType string `gorm:"type:varchar(20);not null;uniqueIndex:uidx_mission_categories_code;column:code_type"`
+	TypeName string `gorm:"type:varchar(128);not null;column:name"`
+
+	SubCategory []MissionSubCategory `gorm:"foreignKey:MissionCategoryID;references:ID"`
+}
+
+func (MissionCategory) TableName() string { return "mission_categories" }
+
+func (c *MissionCategory) BeforeCreate(_ *gorm.DB) error {
+	if len(c.ID) == 0 {
+		c.ID = uuidv7.MustBytes()
+	}
+	c.CodeType = strings.ToUpper(strings.TrimSpace(c.CodeType))
+	c.TypeName = strings.TrimSpace(c.TypeName)
+	return nil
+}
+
+type MissionSubCategory struct {
+	ID                []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	MissionCategoryID []byte `gorm:"type:binary(16);not null;index;column:mission_category_id"`
+	SubCodeType       string `gorm:"type:varchar(32);not null;index;column:sub_type"`
+	SubTypeName       string `gorm:"type:varchar(128);not null;column:name"`
+	TaskName          string `gorm:"type:varchar(255);not null;column:task_name"`
+
+	MissionCategory *MissionCategory `gorm:"foreignKey:MissionCategoryID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (MissionSubCategory) TableName() string { return "mission_subcategories" }
+
+func (s *MissionSubCategory) BeforeCreate(_ *gorm.DB) error {
+	if len(s.ID) == 0 {
+		s.ID = uuidv7.MustBytes()
+	}
+	s.SubCodeType = strings.ToUpper(strings.TrimSpace(s.SubCodeType))
+	s.SubTypeName = strings.TrimSpace(s.SubTypeName)
+	s.TaskName = strings.TrimSpace(s.TaskName)
+	return nil
+}
diff --git a/internal/domain/mission/repository.go b/internal/domain/mission/repository.go
new file mode 100644
index 0000000..4c63da8
--- /dev/null
+++ b/internal/domain/mission/repository.go
@@ -0,0 +1,25 @@
+package mission
+
+import "context"
+
+type Repository interface {
+	WithTransaction(ctx context.Context, fn func(ctx context.Context) error) error
+	Create(ctx context.Context, row *Mission) error
+	CreateCategory(ctx context.Context, row *MissionCategory) error
+	UpdateFlightDataIDByID(ctx context.Context, missionID, flightDataID, updatedBy []byte) error
+	UpdateByID(ctx context.Context, missionID []byte, missionType string, missionCategoryID []byte, subtypeID []byte, note string, updatedBy []byte) error
+	DeleteByID(ctx context.Context, missionID []byte, deletedBy []byte) error
+	DeleteByFlightID(ctx context.Context, flightID []byte, deletedBy []byte) error
+	ListByFlightID(ctx context.Context, flightID []byte) ([]Mission, error)
+	ListByFlightIDs(ctx context.Context, flightIDs [][]byte) ([]Mission, error)
+	GetByID(ctx context.Context, missionID []byte) (*Mission, error)
+	GetByFlightID(ctx context.Context, flightID []byte) (*Mission, error)
+	List(ctx context.Context, filter, sort string, flightID []byte, flightDataStatus string, limit, offset int) ([]Mission, int64, error)
+	ListDatatable(ctx context.Context, filter ListFilter, limit, offset int) ([]Mission, int64, int64, error)
+	ListCategoriesWithSubCategories(ctx context.Context) ([]MissionCategory, error)
+	FindCategoryByCode(ctx context.Context, code string) (*MissionCategory, error)
+	SubCategoryBelongsToCategory(ctx context.Context, subCategoryID, categoryID []byte) (bool, error)
+	MaxCodeSeqByPrefix(ctx context.Context, prefix string) (int, error)
+	AttachFile(ctx context.Context, missionID []byte, fileAttachmentID []byte) error
+	DetachFile(ctx context.Context, missionID []byte, fileAttachmentID []byte) error
+}
diff --git a/internal/domain/mission/service.go b/internal/domain/mission/service.go
new file mode 100644
index 0000000..0ba00b5
--- /dev/null
+++ b/internal/domain/mission/service.go
@@ -0,0 +1,20 @@
+package mission
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *Mission) error
+	CreateType(ctx context.Context, row *MissionCategory) error
+	UpdateByID(ctx context.Context, missionID []byte, missionType string, subtypeID []byte, note string, updatedBy []byte) error
+	DeleteByID(ctx context.Context, missionID []byte, deletedBy []byte) error
+	DeleteByFlightID(ctx context.Context, flightID []byte, deletedBy []byte) error
+	ListByFlightID(ctx context.Context, flightID []byte) ([]Mission, error)
+	ListByFlightIDs(ctx context.Context, flightIDs [][]byte) ([]Mission, error)
+	GetByID(ctx context.Context, missionID []byte) (*Mission, error)
+	GetByFlightID(ctx context.Context, flightID []byte) (*Mission, error)
+	List(ctx context.Context, filter, sort string, flightID []byte, flightDataStatus string, limit, offset int) ([]Mission, int64, error)
+	ListDatatable(ctx context.Context, filter ListFilter, limit, offset int) ([]Mission, int64, int64, error)
+	AttachFile(ctx context.Context, missionID []byte, fileAttachmentID []byte) error
+	DetachFile(ctx context.Context, missionID []byte, fileAttachmentID []byte) error
+	ListTypes(ctx context.Context) ([]MissionCategory, error)
+}
diff --git a/internal/domain/mission/status.go b/internal/domain/mission/status.go
new file mode 100644
index 0000000..e437022
--- /dev/null
+++ b/internal/domain/mission/status.go
@@ -0,0 +1,115 @@
+package mission
+
+import (
+	"sort"
+	"strings"
+
+	sharedconst "wucher/internal/shared/const"
+)
+
+const (
+	StatusDraft      = "draft"
+	StatusInProgress = "in_progress"
+	StatusCompleted  = "completed"
+)
+
+const (
+	FormKeyFlightData  = "flight_data"
+	FormKeyPatientData = "patient_data"
+)
+
+var missionTypeForms = map[string][]string{
+	sharedconst.MissionTypeHEMS: []string{FormKeyFlightData, FormKeyPatientData},
+	sharedconst.MissionTypeCAT:  []string{FormKeyFlightData},
+	sharedconst.MissionTypeSPO:  []string{FormKeyFlightData},
+	sharedconst.MissionTypeNCO:  []string{FormKeyFlightData},
+}
+
+type FormFacts map[string]string
+
+type FormStatus struct {
+	Key    string
+	Status string
+}
+
+func BuildForms(missionType string, facts FormFacts) []FormStatus {
+	keys := missionFormsForType(missionType)
+	if len(keys) == 0 {
+		keys = sortedFactKeys(facts)
+	}
+	out := make([]FormStatus, 0, len(keys))
+	if len(keys) == 0 {
+		return out
+	}
+
+	for _, key := range keys {
+		out = append(out, formStatus(key, facts[key]))
+	}
+	return out
+}
+
+func missionFormsForType(missionType string) []string {
+	missionType = strings.ToUpper(strings.TrimSpace(missionType))
+	if forms, ok := missionTypeForms[missionType]; ok && len(forms) > 0 {
+		out := make([]string, len(forms))
+		copy(out, forms)
+		return out
+	}
+
+	return nil
+}
+
+func sortedFactKeys(facts FormFacts) []string {
+	keys := make([]string, 0, len(facts))
+	for key := range facts {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+// ComputeStatus derives the mission state from its forms so new forms can be
+// added later without reworking mission-level branching.
+func ComputeStatus(forms []FormStatus) string {
+	if len(forms) == 0 {
+		return StatusDraft
+	}
+
+	completed := 0
+	inProgress := 0
+	for i := range forms {
+		switch forms[i].Status {
+		case StatusCompleted:
+			completed++
+		case StatusInProgress:
+			inProgress++
+		}
+	}
+
+	switch {
+	case completed == 0:
+		if inProgress > 0 {
+			return StatusInProgress
+		}
+		return StatusDraft
+	case completed == len(forms):
+		return StatusCompleted
+	default:
+		return StatusInProgress
+	}
+}
+
+func formStatus(key, status string) FormStatus {
+	return FormStatus{Key: key, Status: normalizeFormStatus(status)}
+}
+
+func normalizeFormStatus(status string) string {
+	switch strings.ToLower(strings.TrimSpace(status)) {
+	case StatusCompleted:
+		return StatusCompleted
+	case StatusInProgress:
+		return StatusInProgress
+	default:
+		return StatusDraft
+	}
+}
diff --git a/internal/domain/mission/status_test.go b/internal/domain/mission/status_test.go
new file mode 100644
index 0000000..2b7e792
--- /dev/null
+++ b/internal/domain/mission/status_test.go
@@ -0,0 +1,94 @@
+package mission
+
+import "testing"
+
+func TestComputeStatus(t *testing.T) {
+	tests := []struct {
+		name  string
+		forms []FormStatus
+		want  string
+	}{
+		{name: "no completed form is draft", forms: BuildForms("", FormFacts{FormKeyFlightData: StatusDraft}), want: StatusDraft},
+		{name: "single in progress form is in progress", forms: BuildForms("", FormFacts{FormKeyFlightData: StatusInProgress}), want: StatusInProgress},
+		{name: "all forms complete is complete", forms: BuildForms("", FormFacts{FormKeyFlightData: StatusCompleted}), want: StatusCompleted},
+		{name: "partial completion is on progress", forms: []FormStatus{{Key: FormKeyFlightData, Status: StatusCompleted}, {Key: "patient_data", Status: StatusDraft}}, want: StatusInProgress},
+		{name: "no forms defaults to draft", forms: nil, want: StatusDraft},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := ComputeStatus(tc.forms); got != tc.want {
+				t.Fatalf("ComputeStatus(%+v) = %q, want %q", tc.forms, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestBuildForms(t *testing.T) {
+	tests := []struct {
+		name      string
+		missionTy string
+		facts     FormFacts
+		want      []FormStatus
+	}{
+		{
+			name:      "hems has flight data and patient data",
+			missionTy: "HEMS",
+			facts:     FormFacts{FormKeyFlightData: StatusCompleted},
+			want: []FormStatus{
+				{Key: FormKeyFlightData, Status: StatusCompleted},
+				{Key: FormKeyPatientData, Status: StatusDraft},
+			},
+		},
+		{
+			name:      "cat has flight data only",
+			missionTy: "CAT",
+			facts:     FormFacts{FormKeyFlightData: StatusDraft},
+			want:      []FormStatus{{Key: FormKeyFlightData, Status: StatusDraft}},
+		},
+		{
+			name:      "spo has flight data only",
+			missionTy: "SPO",
+			facts:     FormFacts{FormKeyFlightData: StatusCompleted},
+			want:      []FormStatus{{Key: FormKeyFlightData, Status: StatusCompleted}},
+		},
+		{
+			name:      "nco has flight data only",
+			missionTy: "NCO",
+			facts:     FormFacts{FormKeyFlightData: StatusDraft},
+			want:      []FormStatus{{Key: FormKeyFlightData, Status: StatusDraft}},
+		},
+		{
+			name:      "unknown mission type falls back to provided facts",
+			missionTy: "UNKNOWN",
+			facts:     FormFacts{FormKeyFlightData: StatusCompleted, FormKeyPatientData: StatusDraft},
+			want: []FormStatus{
+				{Key: FormKeyFlightData, Status: StatusCompleted},
+				{Key: FormKeyPatientData, Status: StatusDraft},
+			},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			forms := BuildForms(tc.missionTy, tc.facts)
+			if len(forms) != len(tc.want) {
+				t.Fatalf("expected %d forms, got %d", len(tc.want), len(forms))
+			}
+			for i := range tc.want {
+				if forms[i].Key != tc.want[i].Key || forms[i].Status != tc.want[i].Status {
+					t.Fatalf("form %d = %+v, want %+v", i, forms[i], tc.want[i])
+				}
+			}
+		})
+	}
+}
+
+func TestFormStatus(t *testing.T) {
+	if got := formStatus(FormKeyFlightData, StatusCompleted); got.Status != StatusCompleted || got.Key != FormKeyFlightData {
+		t.Fatalf("unexpected completed form: %+v", got)
+	}
+	if got := formStatus(FormKeyFlightData, StatusDraft); got.Status != StatusDraft {
+		t.Fatalf("unexpected draft form: %+v", got)
+	}
+}
diff --git a/internal/domain/opc/model.go b/internal/domain/opc/model.go
new file mode 100644
index 0000000..d9c8263
--- /dev/null
+++ b/internal/domain/opc/model.go
@@ -0,0 +1,32 @@
+package opc
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type Opc struct {
+	ID        []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	Title     string `gorm:"type:varchar(64);uniqueIndex;not null;column:name"`
+	SortKey   *int   `gorm:"column:sortkey"`
+	Note      string `gorm:"type:varchar(255);column:note"`
+	IsActive  bool   `gorm:"type:tinyint(1);index;not null;default:1;column:is_active"`
+	CreatedAt time.Time
+	CreatedBy []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (Opc) TableName() string { return "hems_opcs" }
+
+func (o *Opc) BeforeCreate(tx *gorm.DB) error {
+	if len(o.ID) == 0 {
+		o.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/opc/model_test.go b/internal/domain/opc/model_test.go
new file mode 100644
index 0000000..9ec6710
--- /dev/null
+++ b/internal/domain/opc/model_test.go
@@ -0,0 +1,37 @@
+package opc
+
+import (
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func TestOpcTableName(t *testing.T) {
+	var m Opc
+	if got := m.TableName(); got != "hems_opcs" {
+		t.Fatalf("expected table name hems_opcs, got %q", got)
+	}
+}
+
+func TestOpcBeforeCreate(t *testing.T) {
+	t.Run("generates id when empty", func(t *testing.T) {
+		m := &Opc{}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(m.ID) == 0 {
+			t.Fatalf("expected id to be generated")
+		}
+	})
+
+	t.Run("keeps existing id", func(t *testing.T) {
+		existing := []byte("already-set-id")
+		m := &Opc{ID: append([]byte(nil), existing...)}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if string(m.ID) != string(existing) {
+			t.Fatalf("expected existing id to stay unchanged")
+		}
+	})
+}
diff --git a/internal/domain/opc/repository.go b/internal/domain/opc/repository.go
new file mode 100644
index 0000000..b94e92b
--- /dev/null
+++ b/internal/domain/opc/repository.go
@@ -0,0 +1,11 @@
+package opc
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, opc *Opc) error
+	Update(ctx context.Context, opc *Opc) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Opc, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]Opc, int64, error)
+}
diff --git a/internal/domain/opc/service.go b/internal/domain/opc/service.go
new file mode 100644
index 0000000..40f1ad4
--- /dev/null
+++ b/internal/domain/opc/service.go
@@ -0,0 +1,11 @@
+package opc
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, opc *Opc) error
+	Update(ctx context.Context, opc *Opc) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Opc, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]Opc, int64, error)
+}
diff --git a/internal/domain/operation/hems_operation.go b/internal/domain/operation/hems_operation.go
new file mode 100644
index 0000000..70717f3
--- /dev/null
+++ b/internal/domain/operation/hems_operation.go
@@ -0,0 +1,70 @@
+package operation
+
+import (
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/mission"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type HEMSOperation struct {
+	ID                      []byte    `json:"id" gorm:"type:binary(16);primaryKey;column:id"`
+	Date                    time.Time `json:"date" gorm:"column:date;not null" example:"2026-03-12T03:04:05Z"`
+	HEMSOperationCategoryID []byte    `json:"hems_operation_category_id,omitempty" gorm:"type:binary(16);column:hems_operation_category_id;index" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	MissionID               []byte    `json:"mission_id,omitempty" gorm:"type:binary(16);column:mission_id;index;uniqueIndex:uidx_hems_operations_mission_id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	OperationalDataID       []byte    `json:"operational_data_id,omitempty" gorm:"type:binary(16);column:operational_data_id;index" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+
+	OperationalData       *HEMSOperationalData   `json:"operational_data,omitempty" gorm:"foreignKey:OperationalDataID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	Mission               *mission.Mission       `json:"mission,omitempty" gorm:"foreignKey:MissionID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	HEMSOperationCategory *HEMSOperationCategory `json:"hems_operation_category,omitempty" gorm:"foreignKey:HEMSOperationCategoryID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+
+	CreatedAt time.Time  `json:"created_at,omitempty" gorm:"column:created_at"`
+	CreatedBy []byte     `json:"created_by,omitempty" gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `json:"updated_at,omitempty" gorm:"column:updated_at"`
+	UpdatedBy []byte     `json:"updated_by,omitempty" gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `json:"deleted_at,omitempty" gorm:"column:deleted_at"`
+	DeletedBy []byte     `json:"deleted_by,omitempty" gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (HEMSOperation) TableName() string { return "hems_operations" }
+
+func (o *HEMSOperation) BeforeCreate(_ *gorm.DB) error {
+	if len(o.ID) == 0 {
+		o.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type HEMSOperationCategory struct {
+	ID        []byte     `json:"id" gorm:"type:binary(16);primaryKey;column:id"`
+	Name      string     `json:"name" gorm:"type:varchar(128);not null;column:name" example:"firefighting"`
+	Type      string     `json:"type" gorm:"type:varchar(32);not null;column:type" enum:"first, secondary, misuse"`
+	CreatedAt time.Time  `json:"created_at,omitempty" gorm:"column:created_at"`
+	CreatedBy []byte     `json:"created_by,omitempty" gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `json:"updated_at,omitempty" gorm:"column:updated_at"`
+	UpdatedBy []byte     `json:"updated_by,omitempty" gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `json:"deleted_at,omitempty" gorm:"column:deleted_at"`
+	DeletedBy []byte     `json:"deleted_by,omitempty" gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (HEMSOperationCategory) TableName() string { return "hems_operation_categories" }
+
+func (c *HEMSOperationCategory) BeforeCreate(_ *gorm.DB) error {
+	if len(c.ID) == 0 {
+		c.ID = uuidv7.MustBytes()
+	}
+	c.Type = strings.ToLower(strings.TrimSpace(c.Type))
+	return nil
+}
+
+func IsValidHEMSOperationCategoryType(value string) bool {
+	switch strings.ToLower(strings.TrimSpace(value)) {
+	case "first", "secondary", "misuse":
+		return true
+	default:
+		return false
+	}
+}
diff --git a/internal/domain/operation/hems_operational_data.go b/internal/domain/operation/hems_operational_data.go
new file mode 100644
index 0000000..58e2de8
--- /dev/null
+++ b/internal/domain/operation/hems_operational_data.go
@@ -0,0 +1,107 @@
+package operation
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/federal_state"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/forces_present"
+	"wucher/internal/domain/land"
+	"wucher/internal/domain/vocation"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type HEMSOperationalData struct {
+	ID   []byte    `json:"id" gorm:"type:binary(16);primaryKey;column:id"`
+	Time time.Time `json:"time" gorm:"column:time;not null" example:"2026-03-12T03:04:05Z"`
+
+	// Place of Appeal
+	LandID     []byte `json:"land_id,omitempty" gorm:"type:binary(16);column:land_id;index"`
+	VocationID []byte `json:"vocation_id,omitempty" gorm:"type:binary(16);column:vocation_id;index"`
+	StateID    []byte `json:"state_id,omitempty" gorm:"type:binary(16);column:state_id;index"`
+	Location   string `json:"location" gorm:"type:varchar(255);not null;column:location" example:"123 Main St, Anytown, USA"`
+	Postcode   string `json:"postcode,omitempty" gorm:"type:varchar(32);column:postcode" example:"12345"`
+	Notes      string `json:"notes" gorm:"type:text;column:notes" example:"Notes about the operational data"`
+
+	// Difficulties
+	Darkness          bool `json:"darkness" gorm:"type:boolean;not null;default:false;column:darkness"`
+	FalseInformation  bool `json:"false_information" gorm:"type:boolean;not null;default:false;column:false_information"`
+	Fog               bool `json:"fog" gorm:"type:boolean;not null;default:false;column:fog"`
+	Precipitation     bool `json:"precipitation" gorm:"type:boolean;not null;default:false;column:precipitation"`
+	MountainUse       bool `json:"mountain_use" gorm:"type:boolean;not null;default:false;column:mountain_use"`
+	Wind              bool `json:"wind" gorm:"type:boolean;not null;default:false;column:wind"`
+	NFOSearch         bool `json:"nfo_search" gorm:"type:boolean;not null;default:false;column:nfo_search"`
+	LandingSiteSearch bool `json:"landing_site_search" gorm:"type:boolean;not null;default:false;column:landing_site_search"`
+
+	// Emergency Location Features
+	Temperature      float64 `json:"temperature" gorm:"type:double;not null;default:0;column:temperature" example:"23.5"`
+	Altitude         float64 `json:"altitude" gorm:"type:double;not null;default:0;column:altitude" example:"5.2"`
+	TerrainIndex     string  `json:"terrain_index" gorm:"type:varchar(255);column:terrain_index" enum:"Only helicopter landing | Paved road | Unpaved road | Direct access not possible | Hospitals | Landing impossible | Winches or rope recovery | Extreme salvage operation"`
+	RopeRecovery     bool    `json:"rope_recovery" gorm:"type:boolean;not null;default:false;column:rope_recovery"`
+	NightFlight      bool    `json:"night_flight" gorm:"type:boolean;not null;default:false;column:night_flight"`
+	InstrumentFlight bool    `json:"instrument_flight" gorm:"type:boolean;not null;default:false;column:instrument_flight"`
+
+	AdditionalInfo string `json:"additional_info" gorm:"type:text;column:additional_info" example:"Additional information about the operational data"`
+
+	Land          *land.Land                    `json:"land,omitempty" gorm:"foreignKey:LandID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	Vocation      *vocation.Vocation            `json:"vocation,omitempty" gorm:"foreignKey:VocationID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	ForcePresents []OperationalDataForcePresent `json:"force_presents,omitempty" gorm:"foreignKey:OperationalDataID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	State         *federal_state.FederalState   `json:"state,omitempty" gorm:"foreignKey:StateID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	Files         []OperationalFile             `json:"files,omitempty" gorm:"foreignKey:OperationalDataID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+
+	CreatedAt time.Time  `json:"created_at,omitempty" gorm:"column:created_at"`
+	CreatedBy []byte     `json:"created_by,omitempty" gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `json:"updated_at,omitempty" gorm:"column:updated_at"`
+	UpdatedBy []byte     `json:"updated_by,omitempty" gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `json:"deleted_at,omitempty" gorm:"column:deleted_at"`
+	DeletedBy []byte     `json:"deleted_by,omitempty" gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (HEMSOperationalData) TableName() string { return "hems_operational_data" }
+
+func (d *HEMSOperationalData) BeforeCreate(_ *gorm.DB) error {
+	if len(d.ID) == 0 {
+		d.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type OperationalDataForcePresent struct {
+	ID                []byte                        `json:"id" gorm:"type:binary(16);primaryKey;column:id"`
+	OperationalDataID []byte                        `json:"operational_data_id" gorm:"type:binary(16);not null;column:operational_data_id;index:idx_hems_operational_force_present_data_id;uniqueIndex:uq_hems_operational_force_present,priority:1"`
+	ForcePresentID    []byte                        `json:"force_present_id" gorm:"type:binary(16);not null;column:force_present_id;index:idx_hems_operational_force_present_fp_id;uniqueIndex:uq_hems_operational_force_present,priority:2"`
+	OperationalData   *HEMSOperationalData          `json:"operational_data,omitempty" gorm:"foreignKey:OperationalDataID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	ForcePresent      *forces_present.ForcesPresent `json:"force_present,omitempty" gorm:"foreignKey:ForcePresentID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	CreatedAt         time.Time                     `json:"created_at,omitempty" gorm:"column:created_at"`
+	UpdatedAt         time.Time                     `json:"updated_at,omitempty" gorm:"column:updated_at"`
+}
+
+func (OperationalDataForcePresent) TableName() string { return "hems_operational_data_forces_present" }
+
+func (f *OperationalDataForcePresent) BeforeCreate(_ *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type OperationalFile struct {
+	ID                []byte                  `json:"id" gorm:"type:binary(16);primaryKey;column:id"`
+	OperationalDataID []byte                  `json:"operational_data_id" gorm:"type:binary(16);not null;column:operational_data_id;index:idx_hems_operational_files_data_id;uniqueIndex:uq_hems_operational_file,priority:1"`
+	FileAttachmentID  []byte                  `json:"file_attachment_id" gorm:"type:binary(16);not null;column:file_attachment_id;index:idx_hems_operational_files_attachment_id;uniqueIndex:uq_hems_operational_file,priority:2"`
+	OperationalData   *HEMSOperationalData    `json:"operational_data,omitempty" gorm:"foreignKey:OperationalDataID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	FileAttachment    *filemanager.Attachment `json:"file_attachment,omitempty" gorm:"foreignKey:FileAttachmentID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	CreatedAt         time.Time               `json:"created_at,omitempty" gorm:"column:created_at"`
+	UpdatedAt         time.Time               `json:"updated_at,omitempty" gorm:"column:updated_at"`
+}
+
+func (OperationalFile) TableName() string { return "hems_operational_files" }
+
+func (f *OperationalFile) BeforeCreate(_ *gorm.DB) error {
+	if len(f.ID) == 0 {
+		f.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/operation/repository.go b/internal/domain/operation/repository.go
new file mode 100644
index 0000000..b57ed59
--- /dev/null
+++ b/internal/domain/operation/repository.go
@@ -0,0 +1,27 @@
+package operation
+
+import "context"
+
+type HEMSOperationRepository interface {
+	Create(ctx context.Context, operation *HEMSOperation) error
+	Update(ctx context.Context, operation *HEMSOperation) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*HEMSOperation, error)
+	List(ctx context.Context, filter string, sort string, limit, offset int) ([]HEMSOperation, int64, error)
+}
+
+type HEMSOperationCategoryRepository interface {
+	Create(ctx context.Context, category *HEMSOperationCategory) error
+	Update(ctx context.Context, category *HEMSOperationCategory) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*HEMSOperationCategory, error)
+	List(ctx context.Context, filter string, sort string, limit, offset int) ([]HEMSOperationCategory, int64, error)
+}
+
+type HEMSOperationalDataRepository interface {
+	Create(ctx context.Context, row *HEMSOperationalData) error
+	Update(ctx context.Context, row *HEMSOperationalData) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*HEMSOperationalData, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]HEMSOperationalData, int64, error)
+}
diff --git a/internal/domain/operation/service.go b/internal/domain/operation/service.go
new file mode 100644
index 0000000..6233c47
--- /dev/null
+++ b/internal/domain/operation/service.go
@@ -0,0 +1,27 @@
+package operation
+
+import "context"
+
+type HEMSOperationService interface {
+	Create(ctx context.Context, operation *HEMSOperation) error
+	Update(ctx context.Context, operation *HEMSOperation) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*HEMSOperation, error)
+	List(ctx context.Context, filter string, sort string, limit, offset int) ([]HEMSOperation, int64, error)
+}
+
+type HEMSOperationCategoryService interface {
+	Create(ctx context.Context, category *HEMSOperationCategory) error
+	Update(ctx context.Context, category *HEMSOperationCategory) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*HEMSOperationCategory, error)
+	List(ctx context.Context, filter string, sort string, limit, offset int) ([]HEMSOperationCategory, int64, error)
+}
+
+type HEMSOperationalDataService interface {
+	Create(ctx context.Context, row *HEMSOperationalData) error
+	Update(ctx context.Context, row *HEMSOperationalData) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*HEMSOperationalData, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]HEMSOperationalData, int64, error)
+}
diff --git a/internal/domain/other_person/model.go b/internal/domain/other_person/model.go
new file mode 100644
index 0000000..e079628
--- /dev/null
+++ b/internal/domain/other_person/model.go
@@ -0,0 +1,32 @@
+package otherperson
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type OtherPerson struct {
+	ID          []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	Name        string `gorm:"type:varchar(191);column:name"`
+	MobilePhone string `gorm:"type:varchar(64);column:mobile_phone"`
+	Email       string `gorm:"type:varchar(191);column:email"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at;index"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (OtherPerson) TableName() string { return "other_people" }
+
+func (p *OtherPerson) BeforeCreate(_ *gorm.DB) error {
+	if len(p.ID) == 0 {
+		p.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/other_person/repository.go b/internal/domain/other_person/repository.go
new file mode 100644
index 0000000..7fa1cc9
--- /dev/null
+++ b/internal/domain/other_person/repository.go
@@ -0,0 +1,13 @@
+package otherperson
+
+import "context"
+
+type Repository interface {
+	Upsert(ctx context.Context, p *OtherPerson) error
+	Create(ctx context.Context, p *OtherPerson) error
+	Update(ctx context.Context, p *OtherPerson) error
+	Delete(ctx context.Context, id, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*OtherPerson, error)
+	FindByIdentity(ctx context.Context, name, phone, email string) (*OtherPerson, error)
+	Search(ctx context.Context, q string, limit, offset int) ([]OtherPerson, int64, error)
+}
diff --git a/internal/domain/other_person/service.go b/internal/domain/other_person/service.go
new file mode 100644
index 0000000..5e3b138
--- /dev/null
+++ b/internal/domain/other_person/service.go
@@ -0,0 +1,23 @@
+package otherperson
+
+import (
+	"context"
+	"errors"
+)
+
+// Sentinel errors returned by the service so the transport layer can map them to the
+// right HTTP status without depending on GORM internals.
+var (
+	ErrNameRequired = errors.New("name is required")
+	ErrNotFound     = errors.New("other person not found")
+	ErrDuplicate    = errors.New("another other person with the same name, mobile phone and email already exists")
+)
+
+type Service interface {
+	Create(ctx context.Context, p *OtherPerson) error
+	Update(ctx context.Context, p *OtherPerson) error
+	Delete(ctx context.Context, id, actor []byte) error
+	GetByID(ctx context.Context, id []byte) (*OtherPerson, error)
+	Search(ctx context.Context, q string, limit, offset int) ([]OtherPerson, int64, error)
+	Upsert(ctx context.Context, p *OtherPerson) error
+}
diff --git a/internal/domain/patient_data/model.go b/internal/domain/patient_data/model.go
new file mode 100644
index 0000000..7a683ed
--- /dev/null
+++ b/internal/domain/patient_data/model.go
@@ -0,0 +1,54 @@
+package patient_data
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	insurancepatientdata "wucher/internal/domain/insurance_patient_data"
+	"wucher/internal/domain/opc"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	GenderMale   = "male"
+	GenderFemale = "female"
+)
+
+func IsValidGender(g string) bool {
+	return g == GenderMale || g == GenderFemale
+}
+
+type PatientData struct {
+	ID                     []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	FamilyName             string     `gorm:"type:varchar(128);not null;column:family_name"`
+	FirstName              string     `gorm:"type:varchar(128);not null;column:first_name"`
+	OPCId                  []byte     `gorm:"type:binary(16);index;column:opc_id"`
+	BirthDate              *time.Time `gorm:"type:date;column:birth_date"`
+	Gender                 string     `gorm:"type:varchar(16);not null;column:gender"`
+	Street                 string     `gorm:"type:varchar(255);column:street"`
+	SVNR                   string     `gorm:"type:varchar(64);column:svnr"`
+	Email                  string     `gorm:"type:varchar(191);column:email"`
+	Phone                  string     `gorm:"type:varchar(64);column:phone"`
+	CoInsured              bool       `gorm:"type:tinyint(1);not null;default:0;column:co_insured"`
+	InsurancePatientDataId []byte     `gorm:"type:binary(16);index;column:insurance_patient_data_id"`
+
+	OPC                  *opc.Opc                                   `gorm:"foreignKey:OPCId;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	InsurancePatientData *insurancepatientdata.InsurancePatientData `gorm:"foreignKey:InsurancePatientDataId;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (PatientData) TableName() string { return "patient_data" }
+
+func (p *PatientData) BeforeCreate(tx *gorm.DB) error {
+	if len(p.ID) == 0 {
+		p.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/patient_data/repository.go b/internal/domain/patient_data/repository.go
new file mode 100644
index 0000000..9e8a9a9
--- /dev/null
+++ b/internal/domain/patient_data/repository.go
@@ -0,0 +1,11 @@
+package patient_data
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *PatientData) error
+	Update(ctx context.Context, row *PatientData) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*PatientData, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]PatientData, int64, error)
+}
diff --git a/internal/domain/patient_data/service.go b/internal/domain/patient_data/service.go
new file mode 100644
index 0000000..8cdc209
--- /dev/null
+++ b/internal/domain/patient_data/service.go
@@ -0,0 +1,11 @@
+package patient_data
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *PatientData) error
+	Update(ctx context.Context, row *PatientData) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*PatientData, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]PatientData, int64, error)
+}
diff --git a/internal/domain/reserve_ac/model.go b/internal/domain/reserve_ac/model.go
new file mode 100644
index 0000000..9d77e8b
--- /dev/null
+++ b/internal/domain/reserve_ac/model.go
@@ -0,0 +1,47 @@
+package reserveac
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	flightinspection "wucher/internal/domain/flight_inspection"
+	helicopter "wucher/internal/domain/helicopter"
+	"wucher/internal/shared/pkg/reserveacutil"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	StatusPending    = reserveacutil.StatusPending
+	StatusApproved   = reserveacutil.StatusApproved
+	StatusOnProgress = reserveacutil.StatusOnProgress
+)
+
+type ReserveAc struct {
+	ID           []byte  `gorm:"type:binary(16);primaryKey;column:id"`
+	Status       string  `gorm:"type:varchar(20);not null;default:pending;index;check:chk_reserve_ac_status,status IN ('pending','approved','onprogress');column:status"`
+	BaseID       []byte  `gorm:"type:binary(16);index;column:base_id"`
+	AircraftID   []byte  `gorm:"type:binary(16);not null;index;column:helicopter_id"`
+	InspectionID []byte  `gorm:"type:binary(16);not null;uniqueIndex:uidx_reserve_acs_inspection_id;column:inspection_id"`
+	Notes        *string `gorm:"type:text;column:notes"`
+
+	Aircraft   *helicopter.Helicopter             `gorm:"foreignKey:AircraftID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	Inspection *flightinspection.FlightInspection `gorm:"foreignKey:InspectionID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at;index"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (ReserveAc) TableName() string { return "reserve_acs" }
+
+func (o *ReserveAc) BeforeCreate(_ *gorm.DB) error {
+	if len(o.ID) == 0 {
+		o.ID = uuidv7.MustBytes()
+	}
+	o.Status = reserveacutil.NormalizeStatus(o.Status)
+	return nil
+}
diff --git a/internal/domain/reserve_ac/repository.go b/internal/domain/reserve_ac/repository.go
new file mode 100644
index 0000000..6122bf9
--- /dev/null
+++ b/internal/domain/reserve_ac/repository.go
@@ -0,0 +1,20 @@
+package reserveac
+
+import (
+	"context"
+
+	shareddto "wucher/internal/transport/http/dto/shared"
+)
+
+type ReserveAcRepository interface {
+	Create(ctx context.Context, row *ReserveAc) error
+	Update(ctx context.Context, row *ReserveAc) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*ReserveAc, error)
+	GetActiveByInspectionID(ctx context.Context, inspectionID []byte) (*ReserveAc, error)
+	List(ctx context.Context, filter string, sort string, limit, offset int) ([]ReserveAc, int64, error)
+	AircraftExists(ctx context.Context, helicopterID []byte) (bool, error)
+	FlightInspectionExists(ctx context.Context, inspectionID []byte) (bool, error)
+	ExistsActiveByInspectionID(ctx context.Context, inspectionID []byte, excludeID []byte) (bool, error)
+	GetLastDailyInspectionByHelicopterID(ctx context.Context, helicopterID []byte) (*shareddto.LastDailyInspection, error)
+}
diff --git a/internal/domain/reserve_ac/service.go b/internal/domain/reserve_ac/service.go
new file mode 100644
index 0000000..3a96398
--- /dev/null
+++ b/internal/domain/reserve_ac/service.go
@@ -0,0 +1,20 @@
+package reserveac
+
+import (
+	"context"
+
+	shareddto "wucher/internal/transport/http/dto/shared"
+)
+
+type ReserveAcService interface {
+	Create(ctx context.Context, row *ReserveAc) error
+	Update(ctx context.Context, row *ReserveAc) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*ReserveAc, error)
+	GetActiveByInspectionID(ctx context.Context, inspectionID []byte) (*ReserveAc, error)
+	List(ctx context.Context, filter string, sort string, limit, offset int) ([]ReserveAc, int64, error)
+	AircraftExists(ctx context.Context, helicopterID []byte) (bool, error)
+	FlightInspectionExists(ctx context.Context, inspectionID []byte) (bool, error)
+	ExistsActiveByInspectionID(ctx context.Context, inspectionID []byte, excludeID []byte) (bool, error)
+	GetLastDailyInspectionByHelicopterID(ctx context.Context, helicopterID []byte) (*shareddto.LastDailyInspection, error)
+}
diff --git a/internal/domain/takeover/errors.go b/internal/domain/takeover/errors.go
new file mode 100644
index 0000000..31345eb
--- /dev/null
+++ b/internal/domain/takeover/errors.go
@@ -0,0 +1,18 @@
+package takeover
+
+import "errors"
+
+var (
+	ErrRequired       = errors.New("takeover required")
+	ErrIDRequired     = errors.New("takeover id required")
+	ErrInvalidUUID    = errors.New("takeover uuid invalid")
+	ErrIDMismatch     = errors.New("takeover id mismatch")
+	ErrNotFound       = errors.New("takeover not found")
+	ErrInvalidPayload = errors.New("takeover invalid payload")
+	ErrInvalidJSON    = errors.New("takeover invalid json")
+	ErrCreateFailed   = errors.New("takeover create failed")
+	ErrUpdateFailed   = errors.New("takeover update failed")
+	ErrDeleteFailed   = errors.New("takeover delete failed")
+	ErrGetFailed      = errors.New("takeover get failed")
+	ErrListFailed     = errors.New("takeover list failed")
+)
diff --git a/internal/domain/takeover/model.go b/internal/domain/takeover/model.go
new file mode 100644
index 0000000..4d80988
--- /dev/null
+++ b/internal/domain/takeover/model.go
@@ -0,0 +1,122 @@
+package takeover
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	basedomain "wucher/internal/domain/base"
+	filemanager "wucher/internal/domain/file_manager"
+	reserveac "wucher/internal/domain/reserve_ac"
+	userdomain "wucher/internal/domain/user"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type TakeoverAc struct {
+	ID          []byte  `gorm:"type:binary(16);primaryKey;column:id"`
+	BaseID      []byte  `gorm:"type:binary(16);column:base_id"`
+	ReserveAcID []byte  `gorm:"type:binary(16);index;column:reserve_ac_id"`
+	Notes       *string `gorm:"type:text;column:notes"`
+
+	Base        *basedomain.Base      `gorm:"foreignKey:BaseID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	ReserveAc   *reserveac.ReserveAc  `gorm:"foreignKey:ReserveAcID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	RosterCrews []TakeoverRosterCrew  `gorm:"foreignKey:TakeoverID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	OtherPeople []TakeoverOtherPerson `gorm:"foreignKey:TakeoverID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	Files       []TakeoverFile        `gorm:"foreignKey:TakeoverID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at;index"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (TakeoverAc) TableName() string { return "takeover_acs" }
+
+func (t *TakeoverAc) BeforeCreate(_ *gorm.DB) error {
+	if len(t.ID) == 0 {
+		t.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type TakeoverRosterCrew struct {
+	ID               []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	TakeoverID       []byte     `gorm:"type:binary(16);index:idx_takeover_roster_crews_takeover_id;column:takeover_id"`
+	ConfirmAt        *time.Time `gorm:"column:confirm_at"`
+	RoleCode         string     `gorm:"type:varchar(64);not null;index:idx_takeover_roster_crews_unique,unique;column:role_code"`
+	CrewType         string     `gorm:"type:varchar(32);not null;default:main;index:idx_takeover_roster_crews_unique,unique;column:crew_type"`
+	UserID           []byte     `gorm:"type:binary(16);index:idx_takeover_roster_crews_unique,unique;column:user_id"`
+	User             *userdomain.User `gorm:"foreignKey:UserID;references:ID;constraint:-" json:"user,omitempty"`
+	NameLabel        string     `gorm:"type:varchar(191);index:idx_takeover_roster_crews_unique,unique;column:name_label" json:"name"`
+	MobilePhone      string     `gorm:"type:varchar(64);column:mobile_phone"`
+	Email            string     `gorm:"type:varchar(191);column:email"`
+	DateStart        *time.Time `gorm:"type:date;index:idx_takeover_roster_crews_unique,unique;column:date_start"`
+	DateEnd          *time.Time `gorm:"type:date;index:idx_takeover_roster_crews_unique,unique;column:date_end"`
+	ShiftStart       *string    `gorm:"type:time;index:idx_takeover_roster_crews_unique,unique;column:shift_start"`
+	ShiftEnd         *string    `gorm:"type:time;index:idx_takeover_roster_crews_unique,unique;column:shift_end"`
+	FlightInstructor bool       `gorm:"type:tinyint(1);not null;default:0;column:flight_instructor"`
+	LineChecker      bool       `gorm:"type:tinyint(1);not null;default:0;column:line_checker"`
+	Supervisor       bool       `gorm:"type:tinyint(1);not null;default:0;column:supervisor"`
+	Examiner         bool       `gorm:"type:tinyint(1);not null;default:0;column:examiner"`
+	CoPilot          bool       `gorm:"type:tinyint(1);not null;default:0;column:co_pilot"`
+
+	CreatedAt time.Time  `gorm:"column:created_at"`
+	CreatedBy []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time  `gorm:"column:updated_at"`
+	UpdatedBy []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt *time.Time `gorm:"column:deleted_at"`
+	DeletedBy []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (TakeoverRosterCrew) TableName() string { return "takeover_roster_crews" }
+
+func (h *TakeoverRosterCrew) BeforeCreate(tx *gorm.DB) error {
+	if len(h.ID) == 0 {
+		h.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type TakeoverOtherPerson struct {
+	ID          []byte     `gorm:"type:binary(16);primaryKey;column:id"`
+	TakeoverID  []byte     `gorm:"type:binary(16);index:idx_takeover_other_people_takeover_id;column:takeover_id"`
+	OtherPersonID []byte   `gorm:"type:binary(16);index;column:other_person_id"`
+	Name        string     `gorm:"type:varchar(191);column:name"`
+	MobilePhone string     `gorm:"type:varchar(64);column:mobile_phone"`
+	Email       string     `gorm:"type:varchar(191);column:email"`
+	CreatedAt   time.Time  `gorm:"column:created_at"`
+	CreatedBy   []byte     `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt   time.Time  `gorm:"column:updated_at"`
+	UpdatedBy   []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt   *time.Time `gorm:"column:deleted_at"`
+	DeletedBy   []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (TakeoverOtherPerson) TableName() string { return "takeover_other_people" }
+
+func (h *TakeoverOtherPerson) BeforeCreate(tx *gorm.DB) error {
+	if len(h.ID) == 0 {
+		h.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+type TakeoverFile struct {
+	ID               []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	TakeoverID       []byte `gorm:"type:binary(16);not null;index;column:takeover_id"`
+	FileAttachmentID []byte `gorm:"type:binary(16);not null;index;column:file_attachment_id"`
+
+	Takeover       *TakeoverAc             `gorm:"foreignKey:TakeoverID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+	FileAttachment *filemanager.Attachment `gorm:"foreignKey:FileAttachmentID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE"`
+}
+
+func (TakeoverFile) TableName() string { return "takeover_files" }
+
+func (h *TakeoverFile) BeforeCreate(tx *gorm.DB) error {
+	if len(h.ID) == 0 {
+		h.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/takeover/repository.go b/internal/domain/takeover/repository.go
new file mode 100644
index 0000000..6141a08
--- /dev/null
+++ b/internal/domain/takeover/repository.go
@@ -0,0 +1,11 @@
+package takeover
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, row *TakeoverAc) error
+	Update(ctx context.Context, row *TakeoverAc) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*TakeoverAc, error)
+	List(ctx context.Context, limit, offset int) ([]TakeoverAc, int64, error)
+}
diff --git a/internal/domain/takeover/service.go b/internal/domain/takeover/service.go
new file mode 100644
index 0000000..e326182
--- /dev/null
+++ b/internal/domain/takeover/service.go
@@ -0,0 +1,12 @@
+package takeover
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, row *TakeoverAc) error
+	Update(ctx context.Context, row *TakeoverAc) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*TakeoverAc, error)
+	List(ctx context.Context, limit, offset int) ([]TakeoverAc, int64, error)
+	AttachFile(ctx context.Context, takeoverID []byte, fileAttachmentID []byte) error
+}
diff --git a/internal/domain/transient/queue_idempotency.go b/internal/domain/transient/queue_idempotency.go
new file mode 100644
index 0000000..31d300e
--- /dev/null
+++ b/internal/domain/transient/queue_idempotency.go
@@ -0,0 +1,13 @@
+package transient
+
+import "time"
+
+type QueueIdempotencyRecord struct {
+	IdempotencyKey string    `gorm:"type:varchar(191);primaryKey;column:idempotency_key"`
+	State          string    `gorm:"type:varchar(32);index;not null;column:state"`
+	ExpiresAt      time.Time `gorm:"index;not null;column:expires_at"`
+	CreatedAt      time.Time
+	UpdatedAt      time.Time
+}
+
+func (QueueIdempotencyRecord) TableName() string { return "queue_idempotency_records" }
diff --git a/internal/domain/transient/token_entry.go b/internal/domain/transient/token_entry.go
new file mode 100644
index 0000000..87c7599
--- /dev/null
+++ b/internal/domain/transient/token_entry.go
@@ -0,0 +1,13 @@
+package transient
+
+import "time"
+
+type TokenEntry struct {
+	StoreKey  string     `gorm:"type:varchar(255);primaryKey;column:store_key"`
+	Value     []byte     `gorm:"type:longblob;not null;column:value"`
+	ExpiresAt *time.Time `gorm:"index;column:expires_at"`
+	CreatedAt time.Time
+	UpdatedAt time.Time
+}
+
+func (TokenEntry) TableName() string { return "auth_runtime_tokens" }
diff --git a/internal/domain/user/model.go b/internal/domain/user/model.go
new file mode 100644
index 0000000..d580b40
--- /dev/null
+++ b/internal/domain/user/model.go
@@ -0,0 +1,55 @@
+package user
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+// User maps to the "users" table (shared with auth).
+type User struct {
+	ID                  []byte        `gorm:"type:binary(16);primaryKey;column:id"`
+	RoleID              []byte        `gorm:"type:binary(16);index;not null;column:role_id"`
+	RoleIDs             [][]byte      `gorm:"-"`
+	ImageAttachmentID   []byte        `gorm:"type:binary(16);index;column:image_attachment_id"`
+	ProfileAttachmentID []byte        `gorm:"type:binary(16);index;column:profile_attachment_id"`
+	Email               string        `gorm:"type:varchar(191);uniqueIndex;not null;column:email"`
+	SSOEmail            *string       `gorm:"type:varchar(191);uniqueIndex;column:sso_email"`
+	Username            string        `gorm:"type:varchar(100);index;column:username"`
+	FirstName           string        `gorm:"type:varchar(100);not null;column:first_name"`
+	LastName            string        `gorm:"type:varchar(100);not null;column:last_name"`
+	MobilePhone         string        `gorm:"type:varchar(32);index;column:mobile_phone"`
+	Timezone            string        `gorm:"type:varchar(64);not null;default:UTC;column:timezone"`
+	Roles               []RoleSummary `gorm:"-"`
+	RoleName            string        `gorm:"->;column:role_name"`
+	RoleDescription     string        `gorm:"->;column:role_description"`
+	EmailVerifiedAt     *time.Time    `gorm:"column:email_verified_at"`
+	IsActive            bool          `gorm:"not null;default:true;column:is_active"`
+
+	ImageAttachment           *filemanager.Attachment `gorm:"foreignKey:ImageAttachmentID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	ProfileAttachment         *filemanager.Attachment `gorm:"foreignKey:ProfileAttachmentID;references:ID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL"`
+	ProfileAttachmentPatchSet bool                    `gorm:"-"`
+
+	CreatedAt time.Time
+	CreatedBy []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt time.Time
+	UpdatedBy []byte `gorm:"type:binary(16);column:updated_by"`
+}
+
+type RoleSummary struct {
+	ID          []byte `gorm:"column:id"`
+	Name        string `gorm:"column:name"`
+	Description string `gorm:"column:description"`
+}
+
+func (User) TableName() string { return "users" }
+
+func (u *User) BeforeCreate(tx *gorm.DB) error {
+	if len(u.ID) == 0 {
+		u.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/user/model_test.go b/internal/domain/user/model_test.go
new file mode 100644
index 0000000..3acd47e
--- /dev/null
+++ b/internal/domain/user/model_test.go
@@ -0,0 +1,37 @@
+package user
+
+import (
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func TestUserTableName(t *testing.T) {
+	var u User
+	if got := u.TableName(); got != "users" {
+		t.Fatalf("unexpected table name: %s", got)
+	}
+}
+
+func TestUserBeforeCreate(t *testing.T) {
+	t.Run("generates id when empty", func(t *testing.T) {
+		u := &User{}
+		if err := u.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("BeforeCreate error: %v", err)
+		}
+		if len(u.ID) != 16 {
+			t.Fatalf("expected generated 16-byte ID, got %d", len(u.ID))
+		}
+	})
+
+	t.Run("keeps existing id", func(t *testing.T) {
+		existing := []byte("1234567890abcdef")
+		u := &User{ID: append([]byte(nil), existing...)}
+		if err := u.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("BeforeCreate error: %v", err)
+		}
+		if string(u.ID) != string(existing) {
+			t.Fatalf("expected existing id to stay unchanged")
+		}
+	})
+}
diff --git a/internal/domain/user/repository.go b/internal/domain/user/repository.go
new file mode 100644
index 0000000..8b2b958
--- /dev/null
+++ b/internal/domain/user/repository.go
@@ -0,0 +1,14 @@
+package user
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, user *User) error
+	Update(ctx context.Context, user *User) error
+	Delete(ctx context.Context, id []byte) error
+	GetByID(ctx context.Context, id []byte) (*User, error)
+	GetByEmail(ctx context.Context, email string) (*User, error)
+	GetByUsername(ctx context.Context, username string) (*User, error)
+	List(ctx context.Context, filter string, sort string, limit, offset int) ([]User, int64, error)
+	GetLastNameByID(ctx context.Context, id []byte) (string, error)
+}
diff --git a/internal/domain/user/service.go b/internal/domain/user/service.go
new file mode 100644
index 0000000..f2b29e7
--- /dev/null
+++ b/internal/domain/user/service.go
@@ -0,0 +1,13 @@
+package user
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, user *User) error
+	Update(ctx context.Context, user *User) error
+	Delete(ctx context.Context, id []byte) error
+	GetByID(ctx context.Context, id []byte) (*User, error)
+	GetByEmail(ctx context.Context, email string) (*User, error)
+	GetByUsername(ctx context.Context, username string) (*User, error)
+	List(ctx context.Context, filter string, sort string, limit, offset int) ([]User, int64, error)
+}
diff --git a/internal/domain/vocation/model.go b/internal/domain/vocation/model.go
new file mode 100644
index 0000000..4ee6cf9
--- /dev/null
+++ b/internal/domain/vocation/model.go
@@ -0,0 +1,32 @@
+package vocation
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type Vocation struct {
+	ID          []byte `gorm:"type:binary(16);primaryKey;column:id"`
+	Name        string `gorm:"type:varchar(64);uniqueIndex;not null;column:name"`
+	SortKey     *int   `gorm:"column:sortkey"`
+	Note        string `gorm:"type:varchar(255);column:note"`
+	IsActive    bool   `gorm:"type:tinyint(1);index;not null;default:1;column:is_active"`
+	CreatedAt   time.Time
+	CreatedBy   []byte `gorm:"type:binary(16);column:created_by"`
+	UpdatedAt   time.Time
+	UpdatedBy   []byte     `gorm:"type:binary(16);column:updated_by"`
+	DeletedAt   *time.Time `gorm:"column:deleted_at"`
+	DeletedBy   []byte     `gorm:"type:binary(16);column:deleted_by"`
+}
+
+func (Vocation) TableName() string { return "vocations" }
+
+func (v *Vocation) BeforeCreate(tx *gorm.DB) error {
+	if len(v.ID) == 0 {
+		v.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
diff --git a/internal/domain/vocation/model_test.go b/internal/domain/vocation/model_test.go
new file mode 100644
index 0000000..32b87b2
--- /dev/null
+++ b/internal/domain/vocation/model_test.go
@@ -0,0 +1,37 @@
+package vocation
+
+import (
+	"testing"
+
+	"gorm.io/gorm"
+)
+
+func TestVocationTableName(t *testing.T) {
+	var m Vocation
+	if got := m.TableName(); got != "vocations" {
+		t.Fatalf("expected table name vocations, got %q", got)
+	}
+}
+
+func TestVocationBeforeCreate(t *testing.T) {
+	t.Run("generates id when empty", func(t *testing.T) {
+		m := &Vocation{}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(m.ID) == 0 {
+			t.Fatalf("expected id to be generated")
+		}
+	})
+
+	t.Run("keeps existing id", func(t *testing.T) {
+		existing := []byte("already-set-id")
+		m := &Vocation{ID: append([]byte(nil), existing...)}
+		if err := m.BeforeCreate(&gorm.DB{}); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if string(m.ID) != string(existing) {
+			t.Fatalf("expected existing id to stay unchanged")
+		}
+	})
+}
diff --git a/internal/domain/vocation/repository.go b/internal/domain/vocation/repository.go
new file mode 100644
index 0000000..c466e41
--- /dev/null
+++ b/internal/domain/vocation/repository.go
@@ -0,0 +1,11 @@
+package vocation
+
+import "context"
+
+type Repository interface {
+	Create(ctx context.Context, vocation *Vocation) error
+	Update(ctx context.Context, vocation *Vocation) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Vocation, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]Vocation, int64, error)
+}
diff --git a/internal/domain/vocation/service.go b/internal/domain/vocation/service.go
new file mode 100644
index 0000000..10f7226
--- /dev/null
+++ b/internal/domain/vocation/service.go
@@ -0,0 +1,11 @@
+package vocation
+
+import "context"
+
+type Service interface {
+	Create(ctx context.Context, vocation *Vocation) error
+	Update(ctx context.Context, vocation *Vocation) error
+	Delete(ctx context.Context, id []byte, deletedBy []byte) error
+	GetByID(ctx context.Context, id []byte) (*Vocation, error)
+	List(ctx context.Context, filter, sort string, limit, offset int) ([]Vocation, int64, error)
+}
diff --git a/internal/middleware/auth.go b/internal/middleware/auth.go
new file mode 100644
index 0000000..a28bb0a
--- /dev/null
+++ b/internal/middleware/auth.go
@@ -0,0 +1,25 @@
+package middleware
+
+import (
+	"errors"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+	samlauth "wucher/internal/auth"
+)
+
+func RequireAuth(c *fiber.Ctx) error {
+	token := c.Cookies("session_token")
+	if token == "" {
+		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "unauthorized"})
+	}
+	session, err := samlauth.GetSession(token)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "unauthorized"})
+		}
+		return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{"error": "unauthorized"})
+	}
+	c.Locals("user", session)
+	return c.Next()
+}
diff --git a/internal/queue/context.go b/internal/queue/context.go
new file mode 100644
index 0000000..180a2d7
--- /dev/null
+++ b/internal/queue/context.go
@@ -0,0 +1,45 @@
+package queue
+
+import (
+	"context"
+	"strings"
+)
+
+type contextKey string
+
+const (
+	correlationIDKey contextKey = "queue-correlation-id"
+	traceIDKey       contextKey = "queue-trace-id"
+)
+
+func WithCorrelationID(ctx context.Context, correlationID string) context.Context {
+	correlationID = strings.TrimSpace(correlationID)
+	if correlationID == "" {
+		return ctx
+	}
+	return context.WithValue(ctx, correlationIDKey, correlationID)
+}
+
+func CorrelationIDFromContext(ctx context.Context) string {
+	if ctx == nil {
+		return ""
+	}
+	value, _ := ctx.Value(correlationIDKey).(string)
+	return strings.TrimSpace(value)
+}
+
+func WithTraceID(ctx context.Context, traceID string) context.Context {
+	traceID = strings.TrimSpace(traceID)
+	if traceID == "" {
+		return ctx
+	}
+	return context.WithValue(ctx, traceIDKey, traceID)
+}
+
+func TraceIDFromContext(ctx context.Context) string {
+	if ctx == nil {
+		return ""
+	}
+	value, _ := ctx.Value(traceIDKey).(string)
+	return strings.TrimSpace(value)
+}
diff --git a/internal/queue/enqueuer.go b/internal/queue/enqueuer.go
new file mode 100644
index 0000000..9352265
--- /dev/null
+++ b/internal/queue/enqueuer.go
@@ -0,0 +1,145 @@
+package queue
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+)
+
+type ProducerMetrics struct {
+	published         int64
+	publishFailures   int64
+	secondaryFailures int64
+}
+
+type EmailEnqueuer struct {
+	serializer MessageSerializer
+	producer   QueueProducer
+	logger     *slog.Logger
+}
+
+func NewEmailEnqueuer(serializer MessageSerializer, producer QueueProducer, logger *slog.Logger) *EmailEnqueuer {
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &EmailEnqueuer{
+		serializer: serializer,
+		producer:   producer,
+		logger:     logger,
+	}
+}
+
+func (e *EmailEnqueuer) Enqueue(ctx context.Context, job EmailJob) error {
+	message, err := e.serializer.Serialize(ctx, job)
+	if err != nil {
+		return err
+	}
+	if err := e.producer.Publish(ctx, *message); err != nil {
+		e.logger.Error("queue publish failed",
+			slog.String("backend", e.producer.Backend()),
+			slog.String("message_id", message.ID),
+			slog.String("job_type", job.NormalizedType()),
+			slog.String("recipient_hash", job.RecipientHash()),
+			slog.String("correlation_id", message.Attributes["correlation_id"]),
+			slog.Any("error", err),
+		)
+		return err
+	}
+	e.logger.Info("queue published",
+		slog.String("backend", e.producer.Backend()),
+		slog.String("message_id", message.ID),
+		slog.String("job_type", job.NormalizedType()),
+		slog.String("recipient_hash", job.RecipientHash()),
+		slog.String("correlation_id", message.Attributes["correlation_id"]),
+	)
+	return nil
+}
+
+type DualProducer struct {
+	primary           QueueProducer
+	secondary         QueueProducer
+	secondaryRequired bool
+	logger            *slog.Logger
+}
+
+func NewDualProducer(primary, secondary QueueProducer, secondaryRequired bool, logger *slog.Logger) *DualProducer {
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &DualProducer{
+		primary:           primary,
+		secondary:         secondary,
+		secondaryRequired: secondaryRequired,
+		logger:            logger,
+	}
+}
+
+func (p *DualProducer) Backend() string {
+	return "dual"
+}
+
+func (p *DualProducer) Publish(ctx context.Context, message OutboundMessage) error {
+	if p.primary == nil {
+		return errors.New("primary producer is required")
+	}
+	if err := p.primary.Publish(ctx, message); err != nil {
+		return err
+	}
+	if p.secondary == nil {
+		return nil
+	}
+	if err := p.secondary.Publish(ctx, message); err != nil {
+		p.logger.Error("queue secondary publish failed",
+			slog.String("primary_backend", p.primary.Backend()),
+			slog.String("secondary_backend", p.secondary.Backend()),
+			slog.String("message_id", message.ID),
+			slog.Any("error", err),
+		)
+		if p.secondaryRequired {
+			return err
+		}
+	}
+	return nil
+}
+
+type DualEmailJobProducer struct {
+	primary           EmailJobProducer
+	secondary         EmailJobProducer
+	secondaryRequired bool
+	logger            *slog.Logger
+}
+
+func NewDualEmailJobProducer(primary, secondary EmailJobProducer, secondaryRequired bool, logger *slog.Logger) *DualEmailJobProducer {
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &DualEmailJobProducer{
+		primary:           primary,
+		secondary:         secondary,
+		secondaryRequired: secondaryRequired,
+		logger:            logger,
+	}
+}
+
+func (p *DualEmailJobProducer) Enqueue(ctx context.Context, job EmailJob) error {
+	if p.primary == nil {
+		return errors.New("primary email producer is required")
+	}
+	if err := p.primary.Enqueue(ctx, job); err != nil {
+		return err
+	}
+	if p.secondary == nil {
+		return nil
+	}
+	if err := p.secondary.Enqueue(ctx, job); err != nil {
+		p.logger.Error("queue secondary enqueue failed",
+			slog.String("job_type", job.NormalizedType()),
+			slog.String("recipient_hash", job.RecipientHash()),
+			slog.Any("error", err),
+		)
+		if p.secondaryRequired {
+			return err
+		}
+	}
+	return nil
+}
diff --git a/internal/queue/errors.go b/internal/queue/errors.go
new file mode 100644
index 0000000..ff8fc4f
--- /dev/null
+++ b/internal/queue/errors.go
@@ -0,0 +1,51 @@
+package queue
+
+import "errors"
+
+type permanentError struct {
+	err error
+}
+
+func (e permanentError) Error() string {
+	return e.err.Error()
+}
+
+func (e permanentError) Unwrap() error {
+	return e.err
+}
+
+type transientError struct {
+	err error
+}
+
+func (e transientError) Error() string {
+	return e.err.Error()
+}
+
+func (e transientError) Unwrap() error {
+	return e.err
+}
+
+func Permanent(err error) error {
+	if err == nil {
+		return nil
+	}
+	return permanentError{err: err}
+}
+
+func Transient(err error) error {
+	if err == nil {
+		return nil
+	}
+	return transientError{err: err}
+}
+
+func IsPermanent(err error) bool {
+	var target permanentError
+	return errors.As(err, &target)
+}
+
+func IsTransient(err error) bool {
+	var target transientError
+	return errors.As(err, &target)
+}
diff --git a/internal/queue/file_processing_enqueuer.go b/internal/queue/file_processing_enqueuer.go
new file mode 100644
index 0000000..6e6dd7a
--- /dev/null
+++ b/internal/queue/file_processing_enqueuer.go
@@ -0,0 +1,47 @@
+package queue
+
+import (
+	"context"
+	"log/slog"
+)
+
+type FileProcessingEnqueuer struct {
+	serializer FileProcessingMessageSerializer
+	producer   QueueProducer
+	logger     *slog.Logger
+}
+
+func NewFileProcessingEnqueuer(serializer FileProcessingMessageSerializer, producer QueueProducer, logger *slog.Logger) *FileProcessingEnqueuer {
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &FileProcessingEnqueuer{
+		serializer: serializer,
+		producer:   producer,
+		logger:     logger,
+	}
+}
+
+func (e *FileProcessingEnqueuer) Enqueue(ctx context.Context, job FileProcessingJob) error {
+	message, err := e.serializer.Serialize(ctx, job)
+	if err != nil {
+		return err
+	}
+	if err := e.producer.Publish(ctx, *message); err != nil {
+		e.logger.Error("file queue publish failed",
+			slog.String("backend", e.producer.Backend()),
+			slog.String("message_id", message.ID),
+			slog.String("file_uuid", job.Canonical().FileUUID),
+			slog.String("correlation_id", message.Attributes["correlation_id"]),
+			slog.Any("error", err),
+		)
+		return err
+	}
+	e.logger.Info("file queue published",
+		slog.String("backend", e.producer.Backend()),
+		slog.String("message_id", message.ID),
+		slog.String("file_uuid", job.Canonical().FileUUID),
+		slog.String("correlation_id", message.Attributes["correlation_id"]),
+	)
+	return nil
+}
diff --git a/internal/queue/file_processing_job_handler.go b/internal/queue/file_processing_job_handler.go
new file mode 100644
index 0000000..5caf09d
--- /dev/null
+++ b/internal/queue/file_processing_job_handler.go
@@ -0,0 +1,62 @@
+package queue
+
+import (
+	"context"
+	"errors"
+
+	filemanager "wucher/internal/domain/file_manager"
+)
+
+type FileProcessingJobProcessor interface {
+	Process(ctx context.Context, job filemanager.FileProcessingJob, correlationID string) error
+}
+
+type FileProcessingPermanentClassifier func(error) bool
+
+type FileProcessingJobQueueHandler struct {
+	processor   FileProcessingJobProcessor
+	isPermanent FileProcessingPermanentClassifier
+}
+
+func NewFileProcessingJobQueueHandler(
+	processor FileProcessingJobProcessor,
+	isPermanent FileProcessingPermanentClassifier,
+) *FileProcessingJobQueueHandler {
+	return &FileProcessingJobQueueHandler{
+		processor:   processor,
+		isPermanent: isPermanent,
+	}
+}
+
+func (h *FileProcessingJobQueueHandler) Handle(ctx context.Context, envelope *FileProcessingEnvelope) error {
+	if envelope == nil {
+		return Permanent(errors.New("file processing envelope is required"))
+	}
+	if h.processor == nil {
+		return Permanent(errors.New("file processing processor is required"))
+	}
+
+	job := envelope.Payload.Canonical()
+	if err := job.Validate(); err != nil {
+		return Permanent(err)
+	}
+
+	err := h.processor.Process(ctx, filemanager.FileProcessingJob{
+		JobID:      job.JobID,
+		FileUUID:   job.FileUUID,
+		Bucket:     job.Bucket,
+		ObjectKey:  job.ObjectKey,
+		UploadedBy: job.UploadedBy,
+		MimeType:   job.MimeType,
+		SizeBytes:  job.SizeBytes,
+		TraceID:    job.TraceID,
+		RequestID:  job.RequestID,
+	}, envelope.CorrelationID)
+	if err == nil {
+		return nil
+	}
+	if h.isPermanent != nil && h.isPermanent(err) {
+		return Permanent(err)
+	}
+	return Transient(err)
+}
diff --git a/internal/queue/file_processing_job_handler_test.go b/internal/queue/file_processing_job_handler_test.go
new file mode 100644
index 0000000..4f4bd63
--- /dev/null
+++ b/internal/queue/file_processing_job_handler_test.go
@@ -0,0 +1,122 @@
+package queue
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type stubFileProcessingProcessor struct {
+	err error
+}
+
+func (p stubFileProcessingProcessor) Process(context.Context, filemanager.FileProcessingJob, string) error {
+	return p.err
+}
+
+func TestFileProcessingJobQueueHandlerHandleSuccess(t *testing.T) {
+	fileUUID, err := uuidv7.String(uuidv7.MustNew())
+	if err != nil {
+		t.Fatalf("uuid string: %v", err)
+	}
+	handler := NewFileProcessingJobQueueHandler(stubFileProcessingProcessor{}, nil)
+
+	err = handler.Handle(context.Background(), &FileProcessingEnvelope{
+		MessageID: "msg-1",
+		Payload: FileProcessingJob{
+			FileUUID:  fileUUID,
+			Bucket:    "bucket-a",
+			ObjectKey: "files/a.pdf",
+			SizeBytes: 12,
+		},
+	})
+	if err != nil {
+		t.Fatalf("handle: %v", err)
+	}
+}
+
+func TestFileProcessingJobQueueHandlerHandleNilEnvelopePermanent(t *testing.T) {
+	handler := NewFileProcessingJobQueueHandler(stubFileProcessingProcessor{}, nil)
+	err := handler.Handle(context.Background(), nil)
+	if err == nil {
+		t.Fatalf("expected error")
+	}
+	if !IsPermanent(err) {
+		t.Fatalf("expected permanent error")
+	}
+}
+
+func TestFileProcessingJobQueueHandlerHandleInvalidPayloadPermanent(t *testing.T) {
+	handler := NewFileProcessingJobQueueHandler(stubFileProcessingProcessor{}, nil)
+	err := handler.Handle(context.Background(), &FileProcessingEnvelope{
+		MessageID: "msg-2",
+		Payload: FileProcessingJob{
+			FileUUID: "not-a-uuid",
+			Bucket:   "bucket-a",
+		},
+	})
+	if err == nil {
+		t.Fatalf("expected error")
+	}
+	if !IsPermanent(err) {
+		t.Fatalf("expected permanent error")
+	}
+}
+
+func TestFileProcessingJobQueueHandlerHandleTransientError(t *testing.T) {
+	fileUUID, err := uuidv7.String(uuidv7.MustNew())
+	if err != nil {
+		t.Fatalf("uuid string: %v", err)
+	}
+	handler := NewFileProcessingJobQueueHandler(stubFileProcessingProcessor{
+		err: errors.New("temporary timeout"),
+	}, nil)
+
+	err = handler.Handle(context.Background(), &FileProcessingEnvelope{
+		MessageID: "msg-3",
+		Payload: FileProcessingJob{
+			FileUUID:  fileUUID,
+			Bucket:    "bucket-a",
+			ObjectKey: "files/a.pdf",
+			SizeBytes: 12,
+		},
+	})
+	if err == nil {
+		t.Fatalf("expected error")
+	}
+	if !IsTransient(err) {
+		t.Fatalf("expected transient error")
+	}
+}
+
+func TestFileProcessingJobQueueHandlerHandlePermanentClassification(t *testing.T) {
+	fileUUID, err := uuidv7.String(uuidv7.MustNew())
+	if err != nil {
+		t.Fatalf("uuid string: %v", err)
+	}
+	permanentErr := errors.New("not found")
+	handler := NewFileProcessingJobQueueHandler(stubFileProcessingProcessor{
+		err: permanentErr,
+	}, func(err error) bool {
+		return errors.Is(err, permanentErr)
+	})
+
+	err = handler.Handle(context.Background(), &FileProcessingEnvelope{
+		MessageID: "msg-4",
+		Payload: FileProcessingJob{
+			FileUUID:  fileUUID,
+			Bucket:    "bucket-a",
+			ObjectKey: "files/a.pdf",
+			SizeBytes: 12,
+		},
+	})
+	if err == nil {
+		t.Fatalf("expected error")
+	}
+	if !IsPermanent(err) {
+		t.Fatalf("expected permanent error")
+	}
+}
diff --git a/internal/queue/file_processing_serializer.go b/internal/queue/file_processing_serializer.go
new file mode 100644
index 0000000..15bd602
--- /dev/null
+++ b/internal/queue/file_processing_serializer.go
@@ -0,0 +1,112 @@
+package queue
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"time"
+)
+
+type FileProcessingJSONSerializer struct {
+	version        string
+	queueType      string
+	messageGroupID string
+}
+
+func NewFileProcessingJSONSerializer(version, queueType, messageGroupID string) *FileProcessingJSONSerializer {
+	version = strings.TrimSpace(version)
+	if version == "" {
+		version = "v1"
+	}
+	queueType = strings.ToLower(strings.TrimSpace(queueType))
+	if queueType == "" {
+		queueType = QueueTypeStandard
+	}
+	return &FileProcessingJSONSerializer{
+		version:        version,
+		queueType:      queueType,
+		messageGroupID: strings.TrimSpace(messageGroupID),
+	}
+}
+
+func (s *FileProcessingJSONSerializer) Serialize(ctx context.Context, job FileProcessingJob) (*OutboundMessage, error) {
+	envelope, err := NewFileProcessingEnvelope(ctx, s.version, job)
+	if err != nil {
+		return nil, err
+	}
+	body, err := json.Marshal(envelope)
+	if err != nil {
+		return nil, err
+	}
+	message := &OutboundMessage{
+		ID:   envelope.MessageID,
+		Body: body,
+		Attributes: map[string]string{
+			"message_kind":   envelope.Kind,
+			"message_id":     envelope.MessageID,
+			"correlation_id": envelope.CorrelationID,
+			"trace_id":       envelope.TraceID,
+			"schema_version": envelope.Version,
+			"job_type":       "file_processing",
+			"file_uuid":      envelope.Payload.FileUUID,
+		},
+	}
+	if s.queueType == QueueTypeFIFO {
+		message.MessageGroupID = s.messageGroupID
+		if message.MessageGroupID == "" {
+			message.MessageGroupID = "file-processing"
+		}
+		message.DeduplicationID = envelope.DeduplicationKey()
+	}
+	return message, nil
+}
+
+func (s *FileProcessingJSONSerializer) Deserialize(body []byte, _ map[string]string) (*FileProcessingEnvelope, error) {
+	var envelope FileProcessingEnvelope
+	if err := json.Unmarshal(body, &envelope); err != nil {
+		return nil, errors.Join(ErrInvalidFileProcessingEnvelope, err)
+	}
+	if err := validateFileProcessingEnvelope(&envelope); err != nil {
+		return nil, err
+	}
+	return &envelope, nil
+}
+
+func validateFileProcessingEnvelope(envelope *FileProcessingEnvelope) error {
+	if envelope == nil {
+		return ErrInvalidFileProcessingEnvelope
+	}
+	if strings.TrimSpace(envelope.Version) == "" {
+		return errors.Join(ErrInvalidFileProcessingEnvelope, errors.New("version is required"))
+	}
+	if strings.TrimSpace(envelope.MessageID) == "" {
+		return errors.Join(ErrInvalidFileProcessingEnvelope, errors.New("message id is required"))
+	}
+	if strings.TrimSpace(envelope.Kind) == "" {
+		return errors.Join(ErrInvalidFileProcessingEnvelope, errors.New("kind is required"))
+	}
+	if !strings.EqualFold(strings.TrimSpace(envelope.Kind), FileProcessingKind) {
+		return errors.Join(ErrInvalidFileProcessingEnvelope, errors.New("unsupported message kind"))
+	}
+	if envelope.OccurredAt.IsZero() {
+		return errors.Join(ErrInvalidFileProcessingEnvelope, errors.New("occurred at is required"))
+	}
+	envelope.Payload = envelope.Payload.Canonical()
+	if err := envelope.Payload.Validate(); err != nil {
+		return errors.Join(ErrInvalidFileProcessingEnvelope, err)
+	}
+	if strings.TrimSpace(envelope.CorrelationID) == "" {
+		envelope.CorrelationID = envelope.MessageID
+	}
+	if strings.TrimSpace(envelope.TraceID) == "" {
+		envelope.TraceID = envelope.CorrelationID
+	}
+	if strings.TrimSpace(envelope.IdempotencyKey) == "" {
+		envelope.IdempotencyKey = envelope.MessageID
+	}
+	if envelope.Payload.CreatedAt.IsZero() {
+		envelope.Payload.CreatedAt = time.Now().UTC()
+	}
+	return nil
+}
diff --git a/internal/queue/file_processing_serializer_test.go b/internal/queue/file_processing_serializer_test.go
new file mode 100644
index 0000000..8b9e0a0
--- /dev/null
+++ b/internal/queue/file_processing_serializer_test.go
@@ -0,0 +1,53 @@
+package queue
+
+import (
+	"context"
+	"testing"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func TestFileProcessingJSONSerializerRoundTrip(t *testing.T) {
+	serializer := NewFileProcessingJSONSerializer("v1", QueueTypeStandard, "")
+	fileUUID, err := uuidv7.String(uuidv7.MustNew())
+	if err != nil {
+		t.Fatalf("uuid string: %v", err)
+	}
+
+	ctx := WithCorrelationID(context.Background(), "upload-req-1")
+	message, err := serializer.Serialize(ctx, FileProcessingJob{
+		FileUUID:  fileUUID,
+		Bucket:    "wucher-file-dev",
+		ObjectKey: "files/2026/04/03/a.pdf",
+		MimeType:  "application/pdf",
+		SizeBytes: 1234,
+	})
+	if err != nil {
+		t.Fatalf("serialize: %v", err)
+	}
+
+	envelope, err := serializer.Deserialize(message.Body, message.Attributes)
+	if err != nil {
+		t.Fatalf("deserialize: %v", err)
+	}
+	if envelope.MessageID == "" {
+		t.Fatalf("expected message id")
+	}
+	if envelope.CorrelationID != "upload-req-1" {
+		t.Fatalf("unexpected correlation id: %q", envelope.CorrelationID)
+	}
+	if envelope.Payload.FileUUID != fileUUID {
+		t.Fatalf("unexpected file uuid: %q", envelope.Payload.FileUUID)
+	}
+	if envelope.Payload.ObjectKey != "files/2026/04/03/a.pdf" {
+		t.Fatalf("unexpected object key: %q", envelope.Payload.ObjectKey)
+	}
+}
+
+func TestFileProcessingJSONSerializerRejectsInvalidPayload(t *testing.T) {
+	serializer := NewFileProcessingJSONSerializer("v1", QueueTypeStandard, "")
+	_, err := serializer.Deserialize([]byte(`{"version":"v1","message_id":"m1","kind":"file_manager.processing","occurred_at":"2026-04-03T00:00:00Z","payload":{"bucket":"b","object_key":"k","size_bytes":1}}`), nil)
+	if err == nil {
+		t.Fatalf("expected invalid payload error")
+	}
+}
diff --git a/internal/queue/file_processing_types.go b/internal/queue/file_processing_types.go
new file mode 100644
index 0000000..a003d17
--- /dev/null
+++ b/internal/queue/file_processing_types.go
@@ -0,0 +1,141 @@
+package queue
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	FileProcessingKind = "file_manager.processing"
+)
+
+var (
+	ErrInvalidFileProcessingJob      = errors.New("invalid file processing job")
+	ErrInvalidFileProcessingEnvelope = errors.New("invalid file processing envelope")
+)
+
+type FileProcessingJob struct {
+	JobID      string    `json:"job_id,omitempty"`
+	FileUUID   string    `json:"file_uuid"`
+	Bucket     string    `json:"bucket"`
+	ObjectKey  string    `json:"object_key"`
+	UploadedBy string    `json:"uploaded_by,omitempty"`
+	MimeType   string    `json:"mime_type,omitempty"`
+	SizeBytes  int64     `json:"size_bytes"`
+	CreatedAt  time.Time `json:"created_at,omitempty"`
+	TraceID    string    `json:"trace_id,omitempty"`
+	RequestID  string    `json:"request_id,omitempty"`
+}
+
+func (j FileProcessingJob) Canonical() FileProcessingJob {
+	job := j
+	job.JobID = strings.TrimSpace(job.JobID)
+	job.FileUUID = strings.TrimSpace(job.FileUUID)
+	job.Bucket = strings.TrimSpace(job.Bucket)
+	job.ObjectKey = strings.TrimSpace(job.ObjectKey)
+	job.UploadedBy = strings.TrimSpace(job.UploadedBy)
+	job.MimeType = strings.ToLower(strings.TrimSpace(job.MimeType))
+	job.TraceID = strings.TrimSpace(job.TraceID)
+	job.RequestID = strings.TrimSpace(job.RequestID)
+	return job
+}
+
+func (j FileProcessingJob) Validate() error {
+	job := j.Canonical()
+	if job.FileUUID == "" {
+		return errors.Join(ErrInvalidFileProcessingJob, errors.New("file uuid is required"))
+	}
+	if _, err := uuidv7.ParseString(job.FileUUID); err != nil {
+		return errors.Join(ErrInvalidFileProcessingJob, errors.New("file uuid is invalid"))
+	}
+	if job.Bucket == "" {
+		return errors.Join(ErrInvalidFileProcessingJob, errors.New("bucket is required"))
+	}
+	if job.ObjectKey == "" {
+		return errors.Join(ErrInvalidFileProcessingJob, errors.New("object key is required"))
+	}
+	if job.SizeBytes < 0 {
+		return errors.Join(ErrInvalidFileProcessingJob, errors.New("size bytes must be non-negative"))
+	}
+	return nil
+}
+
+type FileProcessingEnvelope struct {
+	Version        string            `json:"version"`
+	MessageID      string            `json:"message_id"`
+	Kind           string            `json:"kind"`
+	OccurredAt     time.Time         `json:"occurred_at"`
+	CorrelationID  string            `json:"correlation_id,omitempty"`
+	TraceID        string            `json:"trace_id,omitempty"`
+	IdempotencyKey string            `json:"idempotency_key,omitempty"`
+	Payload        FileProcessingJob `json:"payload"`
+}
+
+func NewFileProcessingEnvelope(ctx context.Context, version string, job FileProcessingJob) (*FileProcessingEnvelope, error) {
+	job = job.Canonical()
+	if err := job.Validate(); err != nil {
+		return nil, err
+	}
+	messageID, err := newMessageID()
+	if err != nil {
+		return nil, err
+	}
+	correlationID := CorrelationIDFromContext(ctx)
+	if correlationID == "" {
+		correlationID = messageID
+	}
+	traceID := TraceIDFromContext(ctx)
+	if traceID == "" {
+		traceID = correlationID
+	}
+	now := time.Now().UTC()
+	if strings.TrimSpace(version) == "" {
+		version = "v1"
+	}
+	if job.JobID == "" {
+		job.JobID = messageID
+	}
+	if job.CreatedAt.IsZero() {
+		job.CreatedAt = now
+	}
+	if job.TraceID == "" {
+		job.TraceID = traceID
+	}
+	if job.RequestID == "" {
+		job.RequestID = correlationID
+	}
+	return &FileProcessingEnvelope{
+		Version:        version,
+		MessageID:      messageID,
+		Kind:           FileProcessingKind,
+		OccurredAt:     now,
+		CorrelationID:  correlationID,
+		TraceID:        traceID,
+		IdempotencyKey: job.JobID,
+		Payload:        job,
+	}, nil
+}
+
+func (e FileProcessingEnvelope) DeduplicationKey() string {
+	if v := strings.TrimSpace(e.IdempotencyKey); v != "" {
+		return v
+	}
+	return strings.TrimSpace(e.MessageID)
+}
+
+type FileProcessingMessageSerializer interface {
+	Serialize(ctx context.Context, job FileProcessingJob) (*OutboundMessage, error)
+	Deserialize(body []byte, attributes map[string]string) (*FileProcessingEnvelope, error)
+}
+
+type FileProcessingJobProducer interface {
+	Enqueue(ctx context.Context, job FileProcessingJob) error
+}
+
+type FileProcessingJobHandler interface {
+	Handle(ctx context.Context, envelope *FileProcessingEnvelope) error
+}
diff --git a/internal/queue/file_processing_worker.go b/internal/queue/file_processing_worker.go
new file mode 100644
index 0000000..03484f3
--- /dev/null
+++ b/internal/queue/file_processing_worker.go
@@ -0,0 +1,299 @@
+package queue
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"time"
+
+	"wucher/internal/shared/pkg/metrics"
+)
+
+type FileProcessingWorker struct {
+	cfg        WorkerConfig
+	consumer   QueueConsumer
+	serializer FileProcessingMessageSerializer
+	handler    FileProcessingJobHandler
+	retry      RetryPolicy
+	idem       IdempotencyStore
+	metrics    *Metrics
+	health     *HealthReporter
+	logger     *slog.Logger
+	component  string
+}
+
+type fileProcessResult struct {
+	delivery *Delivery
+	envelope *FileProcessingEnvelope
+	decision RetryDecision
+	err      error
+}
+
+func NewFileProcessingWorker(
+	cfg WorkerConfig,
+	consumer QueueConsumer,
+	serializer FileProcessingMessageSerializer,
+	handler FileProcessingJobHandler,
+	retry RetryPolicy,
+	idem IdempotencyStore,
+	metrics *Metrics,
+	health *HealthReporter,
+	logger *slog.Logger,
+) *FileProcessingWorker {
+	if cfg.Concurrency <= 0 {
+		cfg.Concurrency = 1
+	}
+	if cfg.MaxBatchSize <= 0 || cfg.MaxBatchSize > cfg.Concurrency {
+		cfg.MaxBatchSize = cfg.Concurrency
+	}
+	if cfg.ProcessTimeout <= 0 {
+		cfg.ProcessTimeout = 30 * time.Second
+	}
+	if cfg.ProcessingTTL <= 0 {
+		cfg.ProcessingTTL = 15 * time.Minute
+	}
+	if cfg.IdempotencyTTL <= 0 {
+		cfg.IdempotencyTTL = 24 * time.Hour
+	}
+	if cfg.PollErrorDelay <= 0 {
+		cfg.PollErrorDelay = time.Second
+	}
+	if retry == nil {
+		retry = NewExponentialBackoffPolicy(time.Second, 5*time.Minute, 30*time.Second)
+	}
+	if idem == nil {
+		idem = NoopIdempotencyStore{}
+	}
+	if metrics == nil {
+		metrics = NewMetrics()
+	}
+	if health == nil {
+		health = NewHealthReporter(3)
+	}
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &FileProcessingWorker{
+		cfg:        cfg,
+		consumer:   consumer,
+		serializer: serializer,
+		handler:    handler,
+		retry:      retry,
+		idem:       idem,
+		metrics:    metrics,
+		health:     health,
+		logger:     logger,
+		component:  normalizeWorkerMetricsComponent(cfg.MetricsComponent),
+	}
+}
+
+func (w *FileProcessingWorker) Run(ctx context.Context) error {
+	if w.consumer == nil {
+		return errors.New("queue consumer is required")
+	}
+	if w.serializer == nil {
+		return errors.New("file message serializer is required")
+	}
+	if w.handler == nil {
+		return errors.New("file message handler is required")
+	}
+	for {
+		select {
+		case <-ctx.Done():
+			w.health.MarkDraining()
+			return nil
+		default:
+		}
+
+		deliveries, err := w.consumer.Receive(ctx, w.cfg.MaxBatchSize)
+		if err != nil {
+			if ctx.Err() != nil {
+				w.health.MarkDraining()
+				return nil
+			}
+			w.health.MarkPollFailure(err)
+			w.logger.Error("file queue receive failed",
+				slog.String("backend", w.consumer.Backend()),
+				slog.Any("error", err),
+			)
+			select {
+			case <-ctx.Done():
+				w.health.MarkDraining()
+				return nil
+			case <-time.After(w.cfg.PollErrorDelay):
+			}
+			continue
+		}
+		w.health.MarkPollSuccess()
+		if len(deliveries) == 0 {
+			continue
+		}
+
+		w.metrics.RecordReceive(len(deliveries))
+		results := make(chan fileProcessResult, len(deliveries))
+		for _, delivery := range deliveries {
+			delivery := delivery
+			go func() {
+				results <- w.processDelivery(ctx, delivery)
+			}()
+		}
+
+		acks := make([]*Delivery, 0, len(deliveries))
+		for range deliveries {
+			result := <-results
+			switch result.decision.Action {
+			case RetryActionAck:
+				acks = append(acks, result.delivery)
+			case RetryActionRetry:
+				if err := w.consumer.Retry(ctx, result.delivery, result.decision.Delay); err != nil {
+					w.metrics.RecordRetryFailure()
+					w.logger.Error("file queue retry scheduling failed",
+						slog.String("backend", w.consumer.Backend()),
+						slog.String("message_id", result.delivery.ID),
+						slog.Any("error", err),
+					)
+				} else {
+					w.metrics.RecordRetry()
+				}
+			case RetryActionDeadLetter:
+				if err := w.consumer.DeadLetter(ctx, result.delivery, result.decision.Reason, result.err); err != nil {
+					w.metrics.RecordDeadLetterFailure()
+					w.logger.Error("file queue dead-letter failed",
+						slog.String("backend", w.consumer.Backend()),
+						slog.String("message_id", result.delivery.ID),
+						slog.Any("error", err),
+					)
+				} else {
+					w.metrics.RecordDeadLetter()
+				}
+			}
+		}
+
+		if len(acks) > 0 {
+			if err := w.consumer.Ack(ctx, acks); err != nil {
+				w.metrics.RecordAckFailure()
+				w.logger.Error("file queue ack failed",
+					slog.String("backend", w.consumer.Backend()),
+					slog.Int("count", len(acks)),
+					slog.Any("error", err),
+				)
+			}
+		}
+	}
+}
+
+func (w *FileProcessingWorker) RefreshQueueDepth(ctx context.Context) error {
+	if w.consumer == nil {
+		return errors.New("queue consumer is required")
+	}
+	depth, err := w.consumer.ApproximateDepth(ctx)
+	if err != nil {
+		return err
+	}
+	w.metrics.SetQueueDepth(depth)
+	return nil
+}
+
+func (w *FileProcessingWorker) Metrics() *Metrics {
+	return w.metrics
+}
+
+func (w *FileProcessingWorker) Health() *HealthReporter {
+	return w.health
+}
+
+func (w *FileProcessingWorker) processDelivery(ctx context.Context, delivery *Delivery) (result fileProcessResult) {
+	started := time.Now()
+	var jobErr error
+	defer func() {
+		metrics.ObserveWorkerJob(w.component, "file_processing", jobErr, started)
+	}()
+
+	envelope, err := w.serializer.Deserialize(delivery.Body, delivery.Attributes)
+	if err != nil {
+		w.metrics.RecordMalformed()
+		w.metrics.RecordFailure()
+		jobErr = err
+		return fileProcessResult{
+			delivery: delivery,
+			decision: w.retry.Decide(delivery, nil, Permanent(err)),
+			err:      err,
+		}
+	}
+
+	idempotencyKey := envelope.DeduplicationKey()
+	state, err := w.idem.Acquire(ctx, idempotencyKey, w.cfg.ProcessingTTL)
+	if err != nil {
+		w.metrics.RecordFailure()
+		jobErr = err
+		return fileProcessResult{
+			delivery: delivery,
+			envelope: envelope,
+			decision: w.retry.Decide(delivery, nil, Transient(err)),
+			err:      err,
+		}
+	}
+	switch state {
+	case IdempotencyStateDuplicate:
+		w.metrics.RecordDuplicate()
+		w.logger.Info("file queue duplicate skipped",
+			slog.String("message_id", envelope.MessageID),
+			slog.String("file_uuid", envelope.Payload.FileUUID),
+			slog.String("correlation_id", envelope.CorrelationID),
+		)
+		return fileProcessResult{
+			delivery: delivery,
+			envelope: envelope,
+			decision: RetryDecision{Action: RetryActionAck},
+		}
+	case IdempotencyStateInProgress:
+		inProgressErr := Transient(errors.New("message already in progress"))
+		jobErr = inProgressErr
+		return fileProcessResult{
+			delivery: delivery,
+			envelope: envelope,
+			decision: w.retry.Decide(delivery, nil, inProgressErr),
+			err:      inProgressErr,
+		}
+	}
+
+	processCtx, cancel := context.WithTimeout(ctx, w.cfg.ProcessTimeout)
+	defer cancel()
+
+	if err := w.handler.Handle(processCtx, envelope); err != nil {
+		_ = w.idem.Release(ctx, idempotencyKey)
+		w.metrics.RecordFailure()
+		jobErr = err
+		return fileProcessResult{
+			delivery: delivery,
+			envelope: envelope,
+			decision: w.retry.Decide(delivery, nil, err),
+			err:      err,
+		}
+	}
+
+	if err := w.idem.MarkCompleted(ctx, idempotencyKey, w.cfg.IdempotencyTTL); err != nil {
+		w.metrics.RecordFailure()
+		w.logger.Error("file queue idempotency completion failed",
+			slog.String("message_id", envelope.MessageID),
+			slog.String("file_uuid", envelope.Payload.FileUUID),
+			slog.String("correlation_id", envelope.CorrelationID),
+			slog.Any("error", err),
+		)
+		jobErr = err
+		return fileProcessResult{
+			delivery: delivery,
+			envelope: envelope,
+			decision: w.retry.Decide(delivery, nil, Transient(err)),
+			err:      err,
+		}
+	}
+
+	w.metrics.RecordProcessed(time.Since(started))
+	jobErr = nil
+	return fileProcessResult{
+		delivery: delivery,
+		envelope: envelope,
+		decision: RetryDecision{Action: RetryActionAck},
+	}
+}
diff --git a/internal/queue/file_processing_worker_test.go b/internal/queue/file_processing_worker_test.go
new file mode 100644
index 0000000..7490931
--- /dev/null
+++ b/internal/queue/file_processing_worker_test.go
@@ -0,0 +1,74 @@
+package queue
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/config"
+	"wucher/internal/shared/pkg/logger"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type stubFileProcessingHandler struct {
+	err error
+}
+
+func (h stubFileProcessingHandler) Handle(context.Context, *FileProcessingEnvelope) error {
+	return h.err
+}
+
+func TestFileProcessingWorkerProcessDeliveryDuplicate(t *testing.T) {
+	worker := NewFileProcessingWorker(WorkerConfig{}, nil, NewFileProcessingJSONSerializer("v1", QueueTypeStandard, ""), stubFileProcessingHandler{}, nil, stubIdempotencyStore{state: IdempotencyStateDuplicate}, nil, nil, logger.New(config.LoggingConfig{Format: "json"}))
+	fileUUID, _ := uuidv7.String(uuidv7.MustNew())
+	message, err := NewFileProcessingJSONSerializer("v1", QueueTypeStandard, "").Serialize(context.Background(), FileProcessingJob{
+		FileUUID:  fileUUID,
+		Bucket:    "bucket",
+		ObjectKey: "files/doc.pdf",
+		SizeBytes: 10,
+	})
+	if err != nil {
+		t.Fatalf("serialize: %v", err)
+	}
+
+	result := worker.processDelivery(context.Background(), &Delivery{ID: message.ID, Body: message.Body, Attributes: message.Attributes, ReceiveCount: 1})
+	if result.decision.Action != RetryActionAck {
+		t.Fatalf("expected ack decision, got %s", result.decision.Action)
+	}
+	if worker.Metrics().Snapshot().Duplicates != 1 {
+		t.Fatalf("expected duplicate metric to increment")
+	}
+}
+
+func TestFileProcessingWorkerProcessDeliveryMalformedPayload(t *testing.T) {
+	worker := NewFileProcessingWorker(WorkerConfig{}, nil, NewFileProcessingJSONSerializer("v1", QueueTypeStandard, ""), stubFileProcessingHandler{}, nil, stubIdempotencyStore{}, nil, nil, logger.New(config.LoggingConfig{Format: "json"}))
+	result := worker.processDelivery(context.Background(), &Delivery{ID: "msg-1", Body: []byte(`{"bad":true}`), ReceiveCount: 1})
+	if result.decision.Action != RetryActionDeadLetter {
+		t.Fatalf("expected dead-letter decision, got %s", result.decision.Action)
+	}
+	if worker.Metrics().Snapshot().Malformed != 1 {
+		t.Fatalf("expected malformed metric to increment")
+	}
+}
+
+func TestFileProcessingWorkerProcessDeliveryTransientError(t *testing.T) {
+	worker := NewFileProcessingWorker(WorkerConfig{}, nil, NewFileProcessingJSONSerializer("v1", QueueTypeStandard, ""), stubFileProcessingHandler{err: Transient(errors.New("db timeout"))}, nil, stubIdempotencyStore{}, nil, nil, logger.New(config.LoggingConfig{Format: "json"}))
+	fileUUID, _ := uuidv7.String(uuidv7.MustNew())
+	message, err := NewFileProcessingJSONSerializer("v1", QueueTypeStandard, "").Serialize(context.Background(), FileProcessingJob{
+		FileUUID:  fileUUID,
+		Bucket:    "bucket",
+		ObjectKey: "files/doc.pdf",
+		SizeBytes: 10,
+	})
+	if err != nil {
+		t.Fatalf("serialize: %v", err)
+	}
+
+	result := worker.processDelivery(context.Background(), &Delivery{ID: message.ID, Body: message.Body, Attributes: message.Attributes, ReceiveCount: 2})
+	if result.decision.Action != RetryActionRetry {
+		t.Fatalf("expected retry decision, got %s", result.decision.Action)
+	}
+	if result.decision.Delay <= 0 {
+		t.Fatalf("expected positive retry delay")
+	}
+}
diff --git a/internal/queue/health.go b/internal/queue/health.go
new file mode 100644
index 0000000..5b5a328
--- /dev/null
+++ b/internal/queue/health.go
@@ -0,0 +1,90 @@
+package queue
+
+import (
+	"sync"
+	"time"
+)
+
+type HealthReporter struct {
+	mu                      sync.RWMutex
+	startedAt               time.Time
+	lastPollAt              time.Time
+	lastSuccessAt           time.Time
+	lastFailureAt           time.Time
+	lastError               string
+	consecutivePollFailures int
+	errorThreshold          int
+	draining                bool
+}
+
+type HealthSnapshot struct {
+	Status                 string    `json:"status"`
+	StartedAt              time.Time `json:"started_at"`
+	LastPollAt             time.Time `json:"last_poll_at,omitempty"`
+	LastSuccessAt          time.Time `json:"last_success_at,omitempty"`
+	LastFailureAt          time.Time `json:"last_failure_at,omitempty"`
+	LastError              string    `json:"last_error,omitempty"`
+	ConsecutivePollFailure int       `json:"consecutive_poll_failures"`
+	Draining               bool      `json:"draining"`
+}
+
+func NewHealthReporter(errorThreshold int) *HealthReporter {
+	if errorThreshold <= 0 {
+		errorThreshold = 3
+	}
+	now := time.Now().UTC()
+	return &HealthReporter{
+		startedAt:      now,
+		lastPollAt:     now,
+		errorThreshold: errorThreshold,
+	}
+}
+
+func (r *HealthReporter) MarkPollSuccess() {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	now := time.Now().UTC()
+	r.lastPollAt = now
+	r.lastSuccessAt = now
+	r.consecutivePollFailures = 0
+	r.lastError = ""
+}
+
+func (r *HealthReporter) MarkPollFailure(err error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	now := time.Now().UTC()
+	r.lastPollAt = now
+	r.lastFailureAt = now
+	r.consecutivePollFailures++
+	if err != nil {
+		r.lastError = err.Error()
+	}
+}
+
+func (r *HealthReporter) MarkDraining() {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.draining = true
+}
+
+func (r *HealthReporter) Snapshot() HealthSnapshot {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	status := "ok"
+	if r.draining {
+		status = "draining"
+	} else if r.consecutivePollFailures >= r.errorThreshold {
+		status = "degraded"
+	}
+	return HealthSnapshot{
+		Status:                 status,
+		StartedAt:              r.startedAt,
+		LastPollAt:             r.lastPollAt,
+		LastSuccessAt:          r.lastSuccessAt,
+		LastFailureAt:          r.lastFailureAt,
+		LastError:              r.lastError,
+		ConsecutivePollFailure: r.consecutivePollFailures,
+		Draining:               r.draining,
+	}
+}
diff --git a/internal/queue/idempotency.go b/internal/queue/idempotency.go
new file mode 100644
index 0000000..6fbdd26
--- /dev/null
+++ b/internal/queue/idempotency.go
@@ -0,0 +1,95 @@
+package queue
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+type IdempotencyState string
+
+const (
+	IdempotencyStateAcquired   IdempotencyState = "acquired"
+	IdempotencyStateDuplicate  IdempotencyState = "duplicate"
+	IdempotencyStateInProgress IdempotencyState = "in_progress"
+)
+
+type IdempotencyStore interface {
+	Acquire(ctx context.Context, key string, processingTTL time.Duration) (IdempotencyState, error)
+	MarkCompleted(ctx context.Context, key string, ttl time.Duration) error
+	Release(ctx context.Context, key string) error
+}
+
+type NoopIdempotencyStore struct{}
+
+func (NoopIdempotencyStore) Acquire(context.Context, string, time.Duration) (IdempotencyState, error) {
+	return IdempotencyStateAcquired, nil
+}
+
+func (NoopIdempotencyStore) MarkCompleted(context.Context, string, time.Duration) error {
+	return nil
+}
+
+func (NoopIdempotencyStore) Release(context.Context, string) error {
+	return nil
+}
+
+type MemoryIdempotencyStore struct {
+	mu      sync.Mutex
+	records map[string]memoryIdempotencyRecord
+	now     func() time.Time
+}
+
+type memoryIdempotencyRecord struct {
+	state     IdempotencyState
+	expiresAt time.Time
+}
+
+func NewMemoryIdempotencyStore() *MemoryIdempotencyStore {
+	return &MemoryIdempotencyStore{
+		records: make(map[string]memoryIdempotencyRecord),
+		now:     func() time.Time { return time.Now().UTC() },
+	}
+}
+
+func (s *MemoryIdempotencyStore) Acquire(_ context.Context, key string, processingTTL time.Duration) (IdempotencyState, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.cleanupExpiredLocked()
+	if record, ok := s.records[key]; ok {
+		return record.state, nil
+	}
+	s.records[key] = memoryIdempotencyRecord{
+		state:     IdempotencyStateInProgress,
+		expiresAt: s.now().Add(processingTTL),
+	}
+	return IdempotencyStateAcquired, nil
+}
+
+func (s *MemoryIdempotencyStore) MarkCompleted(_ context.Context, key string, ttl time.Duration) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.records[key] = memoryIdempotencyRecord{
+		state:     IdempotencyStateDuplicate,
+		expiresAt: s.now().Add(ttl),
+	}
+	return nil
+}
+
+func (s *MemoryIdempotencyStore) Release(_ context.Context, key string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	delete(s.records, key)
+	return nil
+}
+
+func (s *MemoryIdempotencyStore) cleanupExpiredLocked() {
+	now := s.now()
+	for key, record := range s.records {
+		if !record.expiresAt.IsZero() && now.After(record.expiresAt) {
+			delete(s.records, key)
+		}
+	}
+}
diff --git a/internal/queue/metrics.go b/internal/queue/metrics.go
new file mode 100644
index 0000000..7a5c989
--- /dev/null
+++ b/internal/queue/metrics.go
@@ -0,0 +1,112 @@
+package queue
+
+import (
+	"sync/atomic"
+	"time"
+)
+
+type Metrics struct {
+	received             atomic.Int64
+	processed            atomic.Int64
+	retried              atomic.Int64
+	failed               atomic.Int64
+	deadLettered         atomic.Int64
+	duplicates           atomic.Int64
+	malformed            atomic.Int64
+	ackFailures          atomic.Int64
+	retryFailures        atomic.Int64
+	deadLetterFailures   atomic.Int64
+	lastQueueDepth       atomic.Int64
+	totalProcessingNanos atomic.Int64
+	lastProcessingNanos  atomic.Int64
+}
+
+type MetricsSnapshot struct {
+	Received                 int64         `json:"received"`
+	Processed                int64         `json:"processed"`
+	Retried                  int64         `json:"retried"`
+	Failed                   int64         `json:"failed"`
+	DeadLettered             int64         `json:"dead_lettered"`
+	Duplicates               int64         `json:"duplicates"`
+	Malformed                int64         `json:"malformed"`
+	AckFailures              int64         `json:"ack_failures"`
+	RetryFailures            int64         `json:"retry_failures"`
+	DeadLetterFailures       int64         `json:"dead_letter_failures"`
+	ApproximateQueueDepth    int64         `json:"approximate_queue_depth"`
+	LastProcessingLatency    time.Duration `json:"last_processing_latency"`
+	AverageProcessingLatency time.Duration `json:"average_processing_latency"`
+}
+
+func NewMetrics() *Metrics {
+	return &Metrics{}
+}
+
+func (m *Metrics) RecordReceive(n int) {
+	m.received.Add(int64(n))
+}
+
+func (m *Metrics) RecordProcessed(duration time.Duration) {
+	m.processed.Add(1)
+	m.lastProcessingNanos.Store(duration.Nanoseconds())
+	m.totalProcessingNanos.Add(duration.Nanoseconds())
+}
+
+func (m *Metrics) RecordRetry() {
+	m.retried.Add(1)
+}
+
+func (m *Metrics) RecordFailure() {
+	m.failed.Add(1)
+}
+
+func (m *Metrics) RecordDeadLetter() {
+	m.deadLettered.Add(1)
+}
+
+func (m *Metrics) RecordDuplicate() {
+	m.duplicates.Add(1)
+}
+
+func (m *Metrics) RecordMalformed() {
+	m.malformed.Add(1)
+}
+
+func (m *Metrics) RecordAckFailure() {
+	m.ackFailures.Add(1)
+}
+
+func (m *Metrics) RecordRetryFailure() {
+	m.retryFailures.Add(1)
+}
+
+func (m *Metrics) RecordDeadLetterFailure() {
+	m.deadLetterFailures.Add(1)
+}
+
+func (m *Metrics) SetQueueDepth(depth int64) {
+	m.lastQueueDepth.Store(depth)
+}
+
+func (m *Metrics) Snapshot() MetricsSnapshot {
+	processed := m.processed.Load()
+	total := m.totalProcessingNanos.Load()
+	avg := time.Duration(0)
+	if processed > 0 {
+		avg = time.Duration(total / processed)
+	}
+	return MetricsSnapshot{
+		Received:                 m.received.Load(),
+		Processed:                processed,
+		Retried:                  m.retried.Load(),
+		Failed:                   m.failed.Load(),
+		DeadLettered:             m.deadLettered.Load(),
+		Duplicates:               m.duplicates.Load(),
+		Malformed:                m.malformed.Load(),
+		AckFailures:              m.ackFailures.Load(),
+		RetryFailures:            m.retryFailures.Load(),
+		DeadLetterFailures:       m.deadLetterFailures.Load(),
+		ApproximateQueueDepth:    m.lastQueueDepth.Load(),
+		LastProcessingLatency:    time.Duration(m.lastProcessingNanos.Load()),
+		AverageProcessingLatency: avg,
+	}
+}
diff --git a/internal/queue/retry.go b/internal/queue/retry.go
new file mode 100644
index 0000000..f71dd99
--- /dev/null
+++ b/internal/queue/retry.go
@@ -0,0 +1,106 @@
+package queue
+
+import (
+	"hash/fnv"
+	"math"
+	"time"
+)
+
+type RetryAction string
+
+const (
+	RetryActionRetry      RetryAction = "retry"
+	RetryActionDeadLetter RetryAction = "dead_letter"
+	RetryActionAck        RetryAction = "ack"
+)
+
+type RetryDecision struct {
+	Action RetryAction
+	Delay  time.Duration
+	Reason string
+}
+
+type RetryPolicy interface {
+	Decide(delivery *Delivery, envelope *Envelope, err error) RetryDecision
+}
+
+type ExponentialBackoffPolicy struct {
+	minDelay              time.Duration
+	maxDelay              time.Duration
+	permanentFailureDelay time.Duration
+}
+
+func NewExponentialBackoffPolicy(minDelay, maxDelay, permanentFailureDelay time.Duration) *ExponentialBackoffPolicy {
+	if minDelay <= 0 {
+		minDelay = time.Second
+	}
+	if maxDelay < minDelay {
+		maxDelay = minDelay
+	}
+	if permanentFailureDelay <= 0 {
+		permanentFailureDelay = 30 * time.Second
+	}
+	return &ExponentialBackoffPolicy{
+		minDelay:              minDelay,
+		maxDelay:              maxDelay,
+		permanentFailureDelay: permanentFailureDelay,
+	}
+}
+
+func (p *ExponentialBackoffPolicy) Decide(delivery *Delivery, _ *Envelope, err error) RetryDecision {
+	if err == nil {
+		return RetryDecision{Action: RetryActionAck}
+	}
+	if IsPermanent(err) {
+		return RetryDecision{
+			Action: RetryActionDeadLetter,
+			Delay:  p.permanentFailureDelay,
+			Reason: err.Error(),
+		}
+	}
+	attempt := 1
+	if delivery != nil && delivery.ReceiveCount > 0 {
+		attempt = delivery.ReceiveCount
+	}
+	delay := p.backoffWithJitter(deliveryID(delivery), attempt)
+	return RetryDecision{
+		Action: RetryActionRetry,
+		Delay:  delay,
+		Reason: err.Error(),
+	}
+}
+
+func (p *ExponentialBackoffPolicy) backoffWithJitter(seed string, attempt int) time.Duration {
+	if attempt < 1 {
+		attempt = 1
+	}
+	power := math.Pow(2, float64(attempt-1))
+	delay := time.Duration(float64(p.minDelay) * power)
+	if delay > p.maxDelay {
+		delay = p.maxDelay
+	}
+	if delay <= 0 {
+		return p.minDelay
+	}
+	jitter := deterministicJitter(seed, delay/2)
+	return delay/2 + jitter
+}
+
+func deterministicJitter(seed string, max time.Duration) time.Duration {
+	if max <= 0 {
+		return 0
+	}
+	h := fnv.New64a()
+	_, _ = h.Write([]byte(seed))
+	return time.Duration(h.Sum64() % uint64(max))
+}
+
+func deliveryID(delivery *Delivery) string {
+	if delivery == nil {
+		return "unknown"
+	}
+	if delivery.ID != "" {
+		return delivery.ID
+	}
+	return "unknown"
+}
diff --git a/internal/queue/serializer.go b/internal/queue/serializer.go
new file mode 100644
index 0000000..b735968
--- /dev/null
+++ b/internal/queue/serializer.go
@@ -0,0 +1,185 @@
+package queue
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"strings"
+	"time"
+)
+
+var ErrInvalidEnvelope = errors.New("invalid queue envelope")
+
+type JSONSerializer struct {
+	version              string
+	enableLegacyFallback bool
+	queueType            string
+	messageGroupID       string
+}
+
+type LegacyJSONSerializer struct{}
+
+func NewJSONSerializer(version string, enableLegacyFallback bool, queueType, messageGroupID string) *JSONSerializer {
+	version = strings.TrimSpace(version)
+	if version == "" {
+		version = "v1"
+	}
+	queueType = strings.ToLower(strings.TrimSpace(queueType))
+	if queueType == "" {
+		queueType = QueueTypeStandard
+	}
+	return &JSONSerializer{
+		version:              version,
+		enableLegacyFallback: enableLegacyFallback,
+		queueType:            queueType,
+		messageGroupID:       strings.TrimSpace(messageGroupID),
+	}
+}
+
+func (s *JSONSerializer) Serialize(ctx context.Context, job EmailJob) (*OutboundMessage, error) {
+	envelope, err := NewEnvelope(ctx, s.version, job)
+	if err != nil {
+		return nil, err
+	}
+	body, err := json.Marshal(envelope)
+	if err != nil {
+		return nil, err
+	}
+	msg := &OutboundMessage{
+		ID:   envelope.MessageID,
+		Body: body,
+		Attributes: map[string]string{
+			"message_kind":   envelope.Kind,
+			"message_id":     envelope.MessageID,
+			"correlation_id": envelope.CorrelationID,
+			"trace_id":       envelope.TraceID,
+			"schema_version": envelope.Version,
+			"job_type":       envelope.Payload.NormalizedType(),
+		},
+	}
+	if s.queueType == QueueTypeFIFO {
+		msg.MessageGroupID = s.messageGroupID
+		if msg.MessageGroupID == "" {
+			msg.MessageGroupID = "default"
+		}
+		msg.DeduplicationID = envelope.DeduplicationKey()
+	}
+	return msg, nil
+}
+
+func (s *JSONSerializer) Deserialize(body []byte, attributes map[string]string) (*Envelope, error) {
+	var envelope Envelope
+	if err := json.Unmarshal(body, &envelope); err == nil {
+		if err := validateEnvelope(&envelope); err == nil {
+			return &envelope, nil
+		}
+	}
+
+	if !s.enableLegacyFallback {
+		return nil, ErrInvalidEnvelope
+	}
+
+	var job EmailJob
+	if err := json.Unmarshal(body, &job); err != nil {
+		return nil, errors.Join(ErrInvalidEnvelope, err)
+	}
+	job = job.Canonical()
+	if err := job.Validate(); err != nil {
+		return nil, errors.Join(ErrInvalidEnvelope, err)
+	}
+
+	id := messageHash(body)
+	correlationID := strings.TrimSpace(attributes["correlation_id"])
+	if correlationID == "" {
+		correlationID = id
+	}
+	traceID := strings.TrimSpace(attributes["trace_id"])
+	if traceID == "" {
+		traceID = correlationID
+	}
+	return &Envelope{
+		Version:        "legacy",
+		MessageID:      id,
+		Kind:           EmailKind,
+		OccurredAt:     time.Now().UTC(),
+		CorrelationID:  correlationID,
+		TraceID:        traceID,
+		IdempotencyKey: id,
+		Payload:        job,
+	}, nil
+}
+
+func (LegacyJSONSerializer) Serialize(ctx context.Context, job EmailJob) (*OutboundMessage, error) {
+	job = job.Canonical()
+	if err := job.Validate(); err != nil {
+		return nil, err
+	}
+	body, err := json.Marshal(job)
+	if err != nil {
+		return nil, err
+	}
+	id := messageHash(body)
+	correlationID := CorrelationIDFromContext(ctx)
+	if correlationID == "" {
+		correlationID = id
+	}
+	traceID := TraceIDFromContext(ctx)
+	if traceID == "" {
+		traceID = correlationID
+	}
+	return &OutboundMessage{
+		ID:   id,
+		Body: body,
+		Attributes: map[string]string{
+			"message_kind":   EmailKind,
+			"message_id":     id,
+			"correlation_id": correlationID,
+			"trace_id":       traceID,
+			"schema_version": "legacy",
+			"job_type":       job.NormalizedType(),
+		},
+	}, nil
+}
+
+func (LegacyJSONSerializer) Deserialize(body []byte, attributes map[string]string) (*Envelope, error) {
+	return NewJSONSerializer("v1", true, QueueTypeStandard, "").Deserialize(body, attributes)
+}
+
+func validateEnvelope(envelope *Envelope) error {
+	if envelope == nil {
+		return ErrInvalidEnvelope
+	}
+	if strings.TrimSpace(envelope.Version) == "" {
+		return errors.Join(ErrInvalidEnvelope, errors.New("version is required"))
+	}
+	if strings.TrimSpace(envelope.MessageID) == "" {
+		return errors.Join(ErrInvalidEnvelope, errors.New("message id is required"))
+	}
+	if strings.TrimSpace(envelope.Kind) == "" {
+		return errors.Join(ErrInvalidEnvelope, errors.New("kind is required"))
+	}
+	if envelope.OccurredAt.IsZero() {
+		return errors.Join(ErrInvalidEnvelope, errors.New("occurred at is required"))
+	}
+	if err := envelope.Payload.Validate(); err != nil {
+		return errors.Join(ErrInvalidEnvelope, err)
+	}
+	envelope.Payload = envelope.Payload.Canonical()
+	if strings.TrimSpace(envelope.CorrelationID) == "" {
+		envelope.CorrelationID = envelope.MessageID
+	}
+	if strings.TrimSpace(envelope.TraceID) == "" {
+		envelope.TraceID = envelope.CorrelationID
+	}
+	if strings.TrimSpace(envelope.IdempotencyKey) == "" {
+		envelope.IdempotencyKey = envelope.MessageID
+	}
+	return nil
+}
+
+func messageHash(body []byte) string {
+	sum := sha256.Sum256(body)
+	return hex.EncodeToString(sum[:16])
+}
diff --git a/internal/queue/serializer_test.go b/internal/queue/serializer_test.go
new file mode 100644
index 0000000..fa0cfe7
--- /dev/null
+++ b/internal/queue/serializer_test.go
@@ -0,0 +1,54 @@
+package queue
+
+import (
+	"context"
+	"testing"
+)
+
+func TestJSONSerializerRoundTrip(t *testing.T) {
+	serializer := NewJSONSerializer("v1", true, QueueTypeStandard, "")
+	ctx := WithCorrelationID(context.Background(), "req-123")
+	message, err := serializer.Serialize(ctx, EmailJob{
+		Type:     "invite_set_password",
+		To:       "user@example.com",
+		Subject:  "Welcome",
+		Body:     "hello",
+		HTMLBody: "<b>hello</b>",
+	})
+	if err != nil {
+		t.Fatalf("serialize: %v", err)
+	}
+
+	envelope, err := serializer.Deserialize(message.Body, message.Attributes)
+	if err != nil {
+		t.Fatalf("deserialize: %v", err)
+	}
+	if envelope.MessageID == "" {
+		t.Fatalf("expected message id")
+	}
+	if envelope.CorrelationID != "req-123" {
+		t.Fatalf("expected correlation id req-123, got %q", envelope.CorrelationID)
+	}
+	if envelope.Payload.NormalizedType() != "invite_set_password" {
+		t.Fatalf("unexpected job type: %q", envelope.Payload.NormalizedType())
+	}
+}
+
+func TestJSONSerializerLegacyFallback(t *testing.T) {
+	serializer := NewJSONSerializer("v1", true, QueueTypeStandard, "")
+	envelope, err := serializer.Deserialize([]byte(`{"to":"user@example.com","subject":"Reset","body":"hello"}`), map[string]string{
+		"correlation_id": "legacy-1",
+	})
+	if err != nil {
+		t.Fatalf("deserialize legacy: %v", err)
+	}
+	if envelope.Version != "legacy" {
+		t.Fatalf("expected legacy version, got %q", envelope.Version)
+	}
+	if envelope.CorrelationID != "legacy-1" {
+		t.Fatalf("unexpected correlation id: %q", envelope.CorrelationID)
+	}
+	if envelope.Payload.To != "user@example.com" {
+		t.Fatalf("unexpected payload: %+v", envelope.Payload)
+	}
+}
diff --git a/internal/queue/types.go b/internal/queue/types.go
new file mode 100644
index 0000000..4501d67
--- /dev/null
+++ b/internal/queue/types.go
@@ -0,0 +1,330 @@
+package queue
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"net/mail"
+	"strings"
+	"time"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	BackendSQS = "sqs"
+
+	QueueTypeStandard = "standard"
+	QueueTypeFIFO     = "fifo"
+
+	EmailKind = "email.dispatch"
+)
+
+var (
+	ErrInvalidEmailJob = errors.New("invalid email job")
+)
+
+type EmailJob struct {
+	JobID        string            `json:"job_id,omitempty"`
+	MessageType  string            `json:"message_type,omitempty"`
+	To           string            `json:"to"`
+	CC           []string          `json:"cc,omitempty"`
+	BCC          []string          `json:"bcc,omitempty"`
+	Subject      string            `json:"subject"`
+	TemplateName string            `json:"template_name,omitempty"`
+	TemplateData map[string]any    `json:"template_data,omitempty"`
+	TextBody     string            `json:"text_body,omitempty"`
+	HTMLBody     string            `json:"html_body,omitempty"`
+	Attachments  []EmailAttachment `json:"attachments,omitempty"`
+	ReplyTo      []string          `json:"reply_to,omitempty"`
+	Tags         map[string]string `json:"tags,omitempty"`
+	Metadata     map[string]string `json:"metadata,omitempty"`
+	CreatedAt    time.Time         `json:"created_at,omitempty"`
+	TraceID      string            `json:"trace_id,omitempty"`
+	RequestID    string            `json:"request_id,omitempty"`
+
+	// Legacy aliases kept for backward-compatible decoding and tests.
+	Type string `json:"type,omitempty"`
+	Body string `json:"body,omitempty"`
+}
+
+type EmailAttachment struct {
+	Filename    string `json:"filename,omitempty"`
+	ContentType string `json:"content_type,omitempty"`
+	ContentID   string `json:"content_id,omitempty"`
+	Content     []byte `json:"content,omitempty"`
+	Inline      bool   `json:"inline,omitempty"`
+}
+
+func (j EmailJob) Validate() error {
+	job := j.Canonical()
+	if strings.TrimSpace(job.To) == "" {
+		return errors.Join(ErrInvalidEmailJob, errors.New("recipient is required"))
+	}
+	if err := validateEmailAddress(job.To); err != nil {
+		return errors.Join(ErrInvalidEmailJob, err)
+	}
+	if err := validateEmailAddresses(job.CC); err != nil {
+		return errors.Join(ErrInvalidEmailJob, err)
+	}
+	if err := validateEmailAddresses(job.BCC); err != nil {
+		return errors.Join(ErrInvalidEmailJob, err)
+	}
+	if err := validateEmailAddresses(job.ReplyTo); err != nil {
+		return errors.Join(ErrInvalidEmailJob, err)
+	}
+	hasBody := strings.TrimSpace(job.TextBody) != "" || strings.TrimSpace(job.HTMLBody) != ""
+	if strings.TrimSpace(job.Subject) == "" && (strings.TrimSpace(job.TemplateName) == "" || hasBody) {
+		return errors.Join(ErrInvalidEmailJob, errors.New("subject is required"))
+	}
+	if !hasBody && strings.TrimSpace(job.TemplateName) == "" {
+		return errors.Join(ErrInvalidEmailJob, errors.New("body is required"))
+	}
+	for i := range job.Attachments {
+		attachment := job.Attachments[i]
+		if len(attachment.Content) == 0 {
+			return errors.Join(ErrInvalidEmailJob, errors.New("attachment content is required"))
+		}
+		if strings.TrimSpace(attachment.ContentType) == "" {
+			return errors.Join(ErrInvalidEmailJob, errors.New("attachment content type is required"))
+		}
+		if attachment.Inline && strings.TrimSpace(attachment.ContentID) == "" {
+			return errors.Join(ErrInvalidEmailJob, errors.New("inline attachment content id is required"))
+		}
+	}
+	return nil
+}
+
+func (j EmailJob) RecipientHash() string {
+	sum := sha256.Sum256([]byte(strings.ToLower(strings.TrimSpace(j.Canonical().To))))
+	return hex.EncodeToString(sum[:8])
+}
+
+func (j EmailJob) NormalizedType() string {
+	if v := strings.TrimSpace(j.Canonical().MessageType); v != "" {
+		return v
+	}
+	return "generic"
+}
+
+func (j EmailJob) TextBodyValue() string {
+	return j.Canonical().TextBody
+}
+
+func (j EmailJob) Canonical() EmailJob {
+	job := j
+	job.To = strings.TrimSpace(job.To)
+	job.Subject = strings.TrimSpace(job.Subject)
+	job.TemplateName = strings.TrimSpace(job.TemplateName)
+	job.JobID = strings.TrimSpace(job.JobID)
+	job.TraceID = strings.TrimSpace(job.TraceID)
+	job.RequestID = strings.TrimSpace(job.RequestID)
+	if strings.TrimSpace(job.MessageType) == "" {
+		job.MessageType = strings.TrimSpace(job.Type)
+	}
+	if strings.TrimSpace(job.TextBody) == "" {
+		job.TextBody = job.Body
+	}
+	job.Type = ""
+	job.Body = ""
+	job.CC = cleanStrings(job.CC)
+	job.BCC = cleanStrings(job.BCC)
+	job.ReplyTo = cleanStrings(job.ReplyTo)
+	job.Tags = cleanStringMap(job.Tags)
+	job.Metadata = cleanStringMap(job.Metadata)
+	job.Attachments = canonicalEmailAttachments(job.Attachments)
+	return job
+}
+
+func canonicalEmailAttachments(values []EmailAttachment) []EmailAttachment {
+	if len(values) == 0 {
+		return nil
+	}
+	out := make([]EmailAttachment, 0, len(values))
+	for i := range values {
+		item := values[i]
+		item.Filename = strings.TrimSpace(item.Filename)
+		item.ContentType = strings.TrimSpace(item.ContentType)
+		item.ContentID = strings.Trim(strings.TrimSpace(item.ContentID), "<>")
+		if len(item.Content) == 0 {
+			continue
+		}
+		item.Content = append([]byte(nil), item.Content...)
+		out = append(out, item)
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+type Envelope struct {
+	Version        string    `json:"version"`
+	MessageID      string    `json:"message_id"`
+	Kind           string    `json:"kind"`
+	OccurredAt     time.Time `json:"occurred_at"`
+	CorrelationID  string    `json:"correlation_id,omitempty"`
+	TraceID        string    `json:"trace_id,omitempty"`
+	IdempotencyKey string    `json:"idempotency_key,omitempty"`
+	Payload        EmailJob  `json:"payload"`
+}
+
+func NewEnvelope(ctx context.Context, version string, job EmailJob) (*Envelope, error) {
+	job = job.Canonical()
+	if err := job.Validate(); err != nil {
+		return nil, err
+	}
+	id, err := newMessageID()
+	if err != nil {
+		return nil, err
+	}
+	correlationID := CorrelationIDFromContext(ctx)
+	if correlationID == "" {
+		correlationID = id
+	}
+	traceID := TraceIDFromContext(ctx)
+	if traceID == "" {
+		traceID = correlationID
+	}
+	now := time.Now().UTC()
+	if job.JobID == "" {
+		job.JobID = id
+	}
+	if job.CreatedAt.IsZero() {
+		job.CreatedAt = now
+	}
+	if job.TraceID == "" {
+		job.TraceID = traceID
+	}
+	if job.RequestID == "" {
+		job.RequestID = correlationID
+	}
+	return &Envelope{
+		Version:        strings.TrimSpace(version),
+		MessageID:      id,
+		Kind:           EmailKind,
+		OccurredAt:     now,
+		CorrelationID:  correlationID,
+		TraceID:        traceID,
+		IdempotencyKey: job.JobID,
+		Payload:        job,
+	}, nil
+}
+
+func (e Envelope) DeduplicationKey() string {
+	if v := strings.TrimSpace(e.IdempotencyKey); v != "" {
+		return v
+	}
+	return strings.TrimSpace(e.MessageID)
+}
+
+type OutboundMessage struct {
+	ID              string
+	Body            []byte
+	Attributes      map[string]string
+	MessageGroupID  string
+	DeduplicationID string
+}
+
+type Delivery struct {
+	ID            string
+	ReceiptHandle string
+	Body          []byte
+	Attributes    map[string]string
+	ReceiveCount  int
+	EnqueuedAt    time.Time
+}
+
+type MessageSerializer interface {
+	Serialize(ctx context.Context, job EmailJob) (*OutboundMessage, error)
+	Deserialize(body []byte, attributes map[string]string) (*Envelope, error)
+}
+
+type QueueProducer interface {
+	Backend() string
+	Publish(ctx context.Context, message OutboundMessage) error
+}
+
+type QueueConsumer interface {
+	Backend() string
+	Receive(ctx context.Context, maxMessages int) ([]*Delivery, error)
+	Ack(ctx context.Context, deliveries []*Delivery) error
+	Retry(ctx context.Context, delivery *Delivery, delay time.Duration) error
+	DeadLetter(ctx context.Context, delivery *Delivery, reason string, cause error) error
+	ApproximateDepth(ctx context.Context) (int64, error)
+	Close() error
+}
+
+type EmailJobProducer interface {
+	Enqueue(ctx context.Context, job EmailJob) error
+}
+
+type EmailJobHandler interface {
+	Handle(ctx context.Context, envelope *Envelope) error
+}
+
+func newMessageID() (string, error) {
+	id, err := uuidv7.String(uuidv7.MustNew())
+	if err != nil {
+		return "", err
+	}
+	return id, nil
+}
+
+func cleanStrings(values []string) []string {
+	if len(values) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(values))
+	for _, value := range values {
+		value = strings.TrimSpace(value)
+		if value == "" {
+			continue
+		}
+		out = append(out, value)
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func cleanStringMap(values map[string]string) map[string]string {
+	if len(values) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(values))
+	for key, value := range values {
+		key = strings.TrimSpace(key)
+		value = strings.TrimSpace(value)
+		if key == "" || value == "" {
+			continue
+		}
+		out[key] = value
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func validateEmailAddresses(addresses []string) error {
+	for _, address := range addresses {
+		if err := validateEmailAddress(address); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func validateEmailAddress(address string) error {
+	address = strings.TrimSpace(address)
+	if address == "" {
+		return nil
+	}
+	if _, err := mail.ParseAddress(address); err != nil {
+		return err
+	}
+	return nil
+}
diff --git a/internal/queue/worker.go b/internal/queue/worker.go
new file mode 100644
index 0000000..0ffbb56
--- /dev/null
+++ b/internal/queue/worker.go
@@ -0,0 +1,320 @@
+package queue
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"strings"
+	"time"
+
+	"wucher/internal/shared/pkg/metrics"
+)
+
+type WorkerConfig struct {
+	Concurrency      int
+	MaxBatchSize     int
+	ProcessTimeout   time.Duration
+	ProcessingTTL    time.Duration
+	IdempotencyTTL   time.Duration
+	PollErrorDelay   time.Duration
+	MetricsComponent string
+}
+
+type Worker struct {
+	cfg        WorkerConfig
+	consumer   QueueConsumer
+	serializer MessageSerializer
+	handler    EmailJobHandler
+	retry      RetryPolicy
+	idem       IdempotencyStore
+	metrics    *Metrics
+	health     *HealthReporter
+	logger     *slog.Logger
+	component  string
+}
+
+type processResult struct {
+	delivery *Delivery
+	envelope *Envelope
+	decision RetryDecision
+	err      error
+}
+
+func NewWorker(
+	cfg WorkerConfig,
+	consumer QueueConsumer,
+	serializer MessageSerializer,
+	handler EmailJobHandler,
+	retry RetryPolicy,
+	idem IdempotencyStore,
+	metrics *Metrics,
+	health *HealthReporter,
+	logger *slog.Logger,
+) *Worker {
+	if cfg.Concurrency <= 0 {
+		cfg.Concurrency = 1
+	}
+	if cfg.MaxBatchSize <= 0 || cfg.MaxBatchSize > cfg.Concurrency {
+		cfg.MaxBatchSize = cfg.Concurrency
+	}
+	if cfg.ProcessTimeout <= 0 {
+		cfg.ProcessTimeout = 30 * time.Second
+	}
+	if cfg.ProcessingTTL <= 0 {
+		cfg.ProcessingTTL = 15 * time.Minute
+	}
+	if cfg.IdempotencyTTL <= 0 {
+		cfg.IdempotencyTTL = 24 * time.Hour
+	}
+	if cfg.PollErrorDelay <= 0 {
+		cfg.PollErrorDelay = time.Second
+	}
+	if retry == nil {
+		retry = NewExponentialBackoffPolicy(time.Second, 5*time.Minute, 30*time.Second)
+	}
+	if idem == nil {
+		idem = NoopIdempotencyStore{}
+	}
+	if metrics == nil {
+		metrics = NewMetrics()
+	}
+	if health == nil {
+		health = NewHealthReporter(3)
+	}
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &Worker{
+		cfg:        cfg,
+		consumer:   consumer,
+		serializer: serializer,
+		handler:    handler,
+		retry:      retry,
+		idem:       idem,
+		metrics:    metrics,
+		health:     health,
+		logger:     logger,
+		component:  normalizeWorkerMetricsComponent(cfg.MetricsComponent),
+	}
+}
+
+func (w *Worker) Run(ctx context.Context) error {
+	if w.consumer == nil {
+		return errors.New("queue consumer is required")
+	}
+	if w.serializer == nil {
+		return errors.New("message serializer is required")
+	}
+	if w.handler == nil {
+		return errors.New("message handler is required")
+	}
+	for {
+		select {
+		case <-ctx.Done():
+			w.health.MarkDraining()
+			return nil
+		default:
+		}
+
+		deliveries, err := w.consumer.Receive(ctx, w.cfg.MaxBatchSize)
+		if err != nil {
+			if ctx.Err() != nil {
+				w.health.MarkDraining()
+				return nil
+			}
+			w.health.MarkPollFailure(err)
+			w.logger.Error("queue receive failed",
+				slog.String("backend", w.consumer.Backend()),
+				slog.Any("error", err),
+			)
+			select {
+			case <-ctx.Done():
+				w.health.MarkDraining()
+				return nil
+			case <-time.After(w.cfg.PollErrorDelay):
+			}
+			continue
+		}
+		w.health.MarkPollSuccess()
+		if len(deliveries) == 0 {
+			continue
+		}
+
+		w.metrics.RecordReceive(len(deliveries))
+		results := make(chan processResult, len(deliveries))
+		for _, delivery := range deliveries {
+			delivery := delivery
+			go func() {
+				results <- w.processDelivery(ctx, delivery)
+			}()
+		}
+
+		acks := make([]*Delivery, 0, len(deliveries))
+		for range deliveries {
+			result := <-results
+			switch result.decision.Action {
+			case RetryActionAck:
+				acks = append(acks, result.delivery)
+			case RetryActionRetry:
+				if err := w.consumer.Retry(ctx, result.delivery, result.decision.Delay); err != nil {
+					w.metrics.RecordRetryFailure()
+					w.logger.Error("queue retry scheduling failed",
+						slog.String("backend", w.consumer.Backend()),
+						slog.String("message_id", result.delivery.ID),
+						slog.Any("error", err),
+					)
+				} else {
+					w.metrics.RecordRetry()
+				}
+			case RetryActionDeadLetter:
+				if err := w.consumer.DeadLetter(ctx, result.delivery, result.decision.Reason, result.err); err != nil {
+					w.metrics.RecordDeadLetterFailure()
+					w.logger.Error("queue dead-letter failed",
+						slog.String("backend", w.consumer.Backend()),
+						slog.String("message_id", result.delivery.ID),
+						slog.Any("error", err),
+					)
+				} else {
+					w.metrics.RecordDeadLetter()
+				}
+			}
+		}
+
+		if len(acks) > 0 {
+			if err := w.consumer.Ack(ctx, acks); err != nil {
+				w.metrics.RecordAckFailure()
+				w.logger.Error("queue ack failed",
+					slog.String("backend", w.consumer.Backend()),
+					slog.Int("count", len(acks)),
+					slog.Any("error", err),
+				)
+			}
+		}
+	}
+}
+
+func (w *Worker) RefreshQueueDepth(ctx context.Context) error {
+	if w.consumer == nil {
+		return errors.New("queue consumer is required")
+	}
+	depth, err := w.consumer.ApproximateDepth(ctx)
+	if err != nil {
+		return err
+	}
+	w.metrics.SetQueueDepth(depth)
+	return nil
+}
+
+func (w *Worker) Metrics() *Metrics {
+	return w.metrics
+}
+
+func (w *Worker) Health() *HealthReporter {
+	return w.health
+}
+
+func (w *Worker) processDelivery(ctx context.Context, delivery *Delivery) (result processResult) {
+	started := time.Now()
+	jobType := "unknown"
+	var jobErr error
+	defer func() {
+		metrics.ObserveWorkerJob(w.component, jobType, jobErr, started)
+	}()
+
+	envelope, err := w.serializer.Deserialize(delivery.Body, delivery.Attributes)
+	if err != nil {
+		w.metrics.RecordMalformed()
+		w.metrics.RecordFailure()
+		jobErr = err
+		return processResult{
+			delivery: delivery,
+			decision: w.retry.Decide(delivery, nil, Permanent(err)),
+			err:      err,
+		}
+	}
+	jobType = strings.TrimSpace(envelope.Payload.NormalizedType())
+
+	idempotencyKey := envelope.DeduplicationKey()
+	state, err := w.idem.Acquire(ctx, idempotencyKey, w.cfg.ProcessingTTL)
+	if err != nil {
+		w.metrics.RecordFailure()
+		jobErr = err
+		return processResult{
+			delivery: delivery,
+			envelope: envelope,
+			decision: w.retry.Decide(delivery, envelope, Transient(err)),
+			err:      err,
+		}
+	}
+	switch state {
+	case IdempotencyStateDuplicate:
+		w.metrics.RecordDuplicate()
+		w.logger.Info("queue duplicate skipped",
+			slog.String("message_id", envelope.MessageID),
+			slog.String("job_type", envelope.Payload.NormalizedType()),
+			slog.String("recipient_hash", envelope.Payload.RecipientHash()),
+			slog.String("correlation_id", envelope.CorrelationID),
+		)
+		return processResult{
+			delivery: delivery,
+			envelope: envelope,
+			decision: RetryDecision{Action: RetryActionAck},
+		}
+	case IdempotencyStateInProgress:
+		inProgressErr := Transient(errors.New("message already in progress"))
+		jobErr = inProgressErr
+		return processResult{
+			delivery: delivery,
+			envelope: envelope,
+			decision: w.retry.Decide(delivery, envelope, inProgressErr),
+			err:      inProgressErr,
+		}
+	}
+
+	processCtx, cancel := context.WithTimeout(ctx, w.cfg.ProcessTimeout)
+	defer cancel()
+
+	if err := w.handler.Handle(processCtx, envelope); err != nil {
+		_ = w.idem.Release(ctx, idempotencyKey)
+		w.metrics.RecordFailure()
+		jobErr = err
+		return processResult{
+			delivery: delivery,
+			envelope: envelope,
+			decision: w.retry.Decide(delivery, envelope, err),
+			err:      err,
+		}
+	}
+
+	if err := w.idem.MarkCompleted(ctx, idempotencyKey, w.cfg.IdempotencyTTL); err != nil {
+		w.metrics.RecordFailure()
+		w.logger.Error("queue idempotency completion failed",
+			slog.String("message_id", envelope.MessageID),
+			slog.String("correlation_id", envelope.CorrelationID),
+			slog.Any("error", err),
+		)
+		jobErr = err
+		return processResult{
+			delivery: delivery,
+			envelope: envelope,
+			decision: w.retry.Decide(delivery, envelope, Transient(err)),
+			err:      err,
+		}
+	}
+
+	w.metrics.RecordProcessed(time.Since(started))
+	jobErr = nil
+	return processResult{
+		delivery: delivery,
+		envelope: envelope,
+		decision: RetryDecision{Action: RetryActionAck},
+	}
+}
+
+func normalizeWorkerMetricsComponent(component string) string {
+	component = strings.ToLower(strings.TrimSpace(component))
+	if component == "" {
+		return "worker"
+	}
+	return component
+}
diff --git a/internal/queue/worker_test.go b/internal/queue/worker_test.go
new file mode 100644
index 0000000..c5de3d2
--- /dev/null
+++ b/internal/queue/worker_test.go
@@ -0,0 +1,93 @@
+package queue
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"wucher/internal/config"
+	"wucher/internal/shared/pkg/logger"
+)
+
+type stubHandler struct {
+	err error
+}
+
+func (h stubHandler) Handle(context.Context, *Envelope) error {
+	return h.err
+}
+
+type stubIdempotencyStore struct {
+	state IdempotencyState
+	err   error
+}
+
+func (s stubIdempotencyStore) Acquire(context.Context, string, time.Duration) (IdempotencyState, error) {
+	if s.err != nil {
+		return "", s.err
+	}
+	if s.state != "" {
+		return s.state, nil
+	}
+	return IdempotencyStateAcquired, nil
+}
+
+func (s stubIdempotencyStore) MarkCompleted(context.Context, string, time.Duration) error {
+	return nil
+}
+
+func (s stubIdempotencyStore) Release(context.Context, string) error {
+	return nil
+}
+
+func TestWorkerProcessDeliveryDuplicate(t *testing.T) {
+	worker := NewWorker(WorkerConfig{}, nil, NewJSONSerializer("v1", true, QueueTypeStandard, ""), stubHandler{}, nil, stubIdempotencyStore{state: IdempotencyStateDuplicate}, nil, nil, logger.New(config.LoggingConfig{Format: "json"}))
+	message, err := NewJSONSerializer("v1", true, QueueTypeStandard, "").Serialize(context.Background(), EmailJob{
+		To:      "user@example.com",
+		Subject: "Hello",
+		Body:    "World",
+	})
+	if err != nil {
+		t.Fatalf("serialize: %v", err)
+	}
+
+	result := worker.processDelivery(context.Background(), &Delivery{ID: message.ID, Body: message.Body, Attributes: message.Attributes, ReceiveCount: 1})
+	if result.decision.Action != RetryActionAck {
+		t.Fatalf("expected ack decision, got %s", result.decision.Action)
+	}
+	if worker.Metrics().Snapshot().Duplicates != 1 {
+		t.Fatalf("expected duplicate metric to increment")
+	}
+}
+
+func TestWorkerProcessDeliveryMalformedPayload(t *testing.T) {
+	worker := NewWorker(WorkerConfig{}, nil, NewJSONSerializer("v1", false, QueueTypeStandard, ""), stubHandler{}, nil, stubIdempotencyStore{}, nil, nil, logger.New(config.LoggingConfig{Format: "json"}))
+	result := worker.processDelivery(context.Background(), &Delivery{ID: "msg-1", Body: []byte(`{"bad":true}`), ReceiveCount: 1})
+	if result.decision.Action != RetryActionDeadLetter {
+		t.Fatalf("expected dead-letter decision, got %s", result.decision.Action)
+	}
+	if worker.Metrics().Snapshot().Malformed != 1 {
+		t.Fatalf("expected malformed metric to increment")
+	}
+}
+
+func TestWorkerProcessDeliveryTransientError(t *testing.T) {
+	worker := NewWorker(WorkerConfig{}, nil, NewJSONSerializer("v1", true, QueueTypeStandard, ""), stubHandler{err: Transient(errors.New("ses timeout"))}, nil, stubIdempotencyStore{}, nil, nil, logger.New(config.LoggingConfig{Format: "json"}))
+	message, err := NewJSONSerializer("v1", true, QueueTypeStandard, "").Serialize(context.Background(), EmailJob{
+		To:      "user@example.com",
+		Subject: "Hello",
+		Body:    "World",
+	})
+	if err != nil {
+		t.Fatalf("serialize: %v", err)
+	}
+
+	result := worker.processDelivery(context.Background(), &Delivery{ID: message.ID, Body: message.Body, Attributes: message.Attributes, ReceiveCount: 2})
+	if result.decision.Action != RetryActionRetry {
+		t.Fatalf("expected retry decision, got %s", result.decision.Action)
+	}
+	if result.decision.Delay <= 0 {
+		t.Fatalf("expected positive retry delay")
+	}
+}
diff --git a/internal/realtime/filemanager/status_hub.go b/internal/realtime/filemanager/status_hub.go
new file mode 100644
index 0000000..df30da7
--- /dev/null
+++ b/internal/realtime/filemanager/status_hub.go
@@ -0,0 +1,272 @@
+package filemanagerrealtime
+
+import (
+	"errors"
+	"log/slog"
+	"strings"
+	"sync"
+)
+
+const (
+	FileStatusChangedEventType = "file_status_changed"
+	defaultSubscriberBuffer    = 32
+)
+
+type FileStatusEvent struct {
+	EventType     string  `json:"event_type"`
+	FileUUID      string  `json:"file_uuid"`
+	FolderUUID    *string `json:"folder_uuid,omitempty"`
+	Status        string  `json:"status"`
+	Name          string  `json:"name"`
+	MimeType      string  `json:"mime_type,omitempty"`
+	FailureReason *string `json:"failure_reason"`
+	UpdatedAt     string  `json:"updated_at"`
+}
+
+type Subscription struct {
+	events  <-chan FileStatusEvent
+	done    <-chan struct{}
+	closeFn func()
+}
+
+func (s *Subscription) Events() <-chan FileStatusEvent {
+	if s == nil {
+		return nil
+	}
+	return s.events
+}
+
+func (s *Subscription) Done() <-chan struct{} {
+	if s == nil {
+		return nil
+	}
+	return s.done
+}
+
+func (s *Subscription) Close() {
+	if s == nil || s.closeFn == nil {
+		return
+	}
+	s.closeFn()
+}
+
+type statusSubscriber struct {
+	events    chan FileStatusEvent
+	done      chan struct{}
+	match     func(FileStatusEvent) bool
+	closeOnce sync.Once
+}
+
+func (s *statusSubscriber) close() {
+	if s == nil {
+		return
+	}
+	s.closeOnce.Do(func() {
+		close(s.done)
+	})
+}
+
+type Hub struct {
+	mu           sync.RWMutex
+	subscribers  map[string]map[uint64]*statusSubscriber
+	recentByUser map[string][]FileStatusEvent
+	nextID       uint64
+	buffer       int
+	replayLimit  int
+	logger       *slog.Logger
+}
+
+func NewHub(buffer int, logger *slog.Logger) *Hub {
+	if buffer <= 0 {
+		buffer = defaultSubscriberBuffer
+	}
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &Hub{
+		subscribers:  make(map[string]map[uint64]*statusSubscriber),
+		recentByUser: make(map[string][]FileStatusEvent),
+		buffer:       buffer,
+		replayLimit:  maxInt(buffer*4, defaultSubscriberBuffer),
+		logger:       logger.With("component", "file-status-hub"),
+	}
+}
+
+func (h *Hub) Subscribe(userUUID string) (*Subscription, error) {
+	return h.SubscribeWithFilter(userUUID, nil)
+}
+
+func (h *Hub) SubscribeWithFilter(userUUID string, match func(FileStatusEvent) bool) (*Subscription, error) {
+	if h == nil {
+		return nil, errors.New("status hub is not configured")
+	}
+	userUUID = canonicalUserID(userUUID)
+	if userUUID == "" {
+		return nil, errors.New("user uuid is required")
+	}
+
+	sub := &statusSubscriber{
+		events: make(chan FileStatusEvent, h.buffer),
+		done:   make(chan struct{}),
+		match:  match,
+	}
+
+	h.mu.Lock()
+	h.nextID++
+	subID := h.nextID
+	if h.subscribers[userUUID] == nil {
+		h.subscribers[userUUID] = make(map[uint64]*statusSubscriber)
+	}
+	h.subscribers[userUUID][subID] = sub
+	backlog := append([]FileStatusEvent(nil), h.recentByUser[userUUID]...)
+	h.mu.Unlock()
+
+	for i := range backlog {
+		if sub.match != nil && !sub.match(backlog[i]) {
+			continue
+		}
+		enqueueSubscriberEvent(sub, backlog[i])
+	}
+
+	var closeOnce sync.Once
+	closeFn := func() {
+		closeOnce.Do(func() {
+			h.mu.Lock()
+			defer h.mu.Unlock()
+
+			if byUser, ok := h.subscribers[userUUID]; ok {
+				delete(byUser, subID)
+				if len(byUser) == 0 {
+					delete(h.subscribers, userUUID)
+				}
+			}
+			sub.close()
+		})
+	}
+
+	return &Subscription{
+		events:  sub.events,
+		done:    sub.done,
+		closeFn: closeFn,
+	}, nil
+}
+
+func (h *Hub) PublishToUsers(userUUIDs []string, event FileStatusEvent) int {
+	if h == nil {
+		return 0
+	}
+	if strings.TrimSpace(event.EventType) == "" {
+		event.EventType = FileStatusChangedEventType
+	}
+	if strings.TrimSpace(event.FileUUID) == "" || strings.TrimSpace(event.Status) == "" {
+		return 0
+	}
+
+	uniqueUsers := make(map[string]struct{}, len(userUUIDs))
+	for i := range userUUIDs {
+		userID := canonicalUserID(userUUIDs[i])
+		if userID == "" {
+			continue
+		}
+		uniqueUsers[userID] = struct{}{}
+	}
+	if len(uniqueUsers) == 0 {
+		return 0
+	}
+
+	delivered := 0
+	for userID := range uniqueUsers {
+		h.mu.Lock()
+		h.recentByUser[userID] = appendRecentEvents(h.recentByUser[userID], event, h.replayLimit)
+		h.mu.Unlock()
+
+		h.mu.RLock()
+		byUser := h.subscribers[userID]
+		if len(byUser) == 0 {
+			h.mu.RUnlock()
+			continue
+		}
+
+		for _, sub := range byUser {
+			select {
+			case <-sub.done:
+				continue
+			default:
+			}
+			if sub.match != nil && !sub.match(event) {
+				continue
+			}
+
+			if enqueueSubscriberEvent(sub, event) {
+				delivered++
+			}
+		}
+		h.mu.RUnlock()
+	}
+	return delivered
+}
+
+func (h *Hub) SubscriberCount(userUUID string) int {
+	if h == nil {
+		return 0
+	}
+	userUUID = canonicalUserID(userUUID)
+	if userUUID == "" {
+		return 0
+	}
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	return len(h.subscribers[userUUID])
+}
+
+func canonicalUserID(raw string) string {
+	return strings.ToLower(strings.TrimSpace(raw))
+}
+
+func enqueueSubscriberEvent(sub *statusSubscriber, event FileStatusEvent) bool {
+	if sub == nil {
+		return false
+	}
+	select {
+	case <-sub.done:
+		return false
+	default:
+	}
+
+	select {
+	case sub.events <- event:
+		return true
+	default:
+		// Drop the oldest buffered event to prioritize fresh status changes.
+		select {
+		case <-sub.events:
+		default:
+		}
+		select {
+		case sub.events <- event:
+			return true
+		default:
+			return false
+		}
+	}
+}
+
+func appendRecentEvents(current []FileStatusEvent, event FileStatusEvent, limit int) []FileStatusEvent {
+	if limit <= 0 {
+		return current[:0]
+	}
+	current = append(current, event)
+	if len(current) <= limit {
+		return current
+	}
+	overflow := len(current) - limit
+	copy(current, current[overflow:])
+	return current[:limit]
+}
+
+func maxInt(a, b int) int {
+	if a >= b {
+		return a
+	}
+	return b
+}
diff --git a/internal/realtime/filemanager/status_hub_test.go b/internal/realtime/filemanager/status_hub_test.go
new file mode 100644
index 0000000..71a7e39
--- /dev/null
+++ b/internal/realtime/filemanager/status_hub_test.go
@@ -0,0 +1,167 @@
+package filemanagerrealtime
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+)
+
+func TestHubSubscribePublishAndClose(t *testing.T) {
+	hub := NewHub(4, nil)
+
+	sub, err := hub.Subscribe("01961f5c-6471-7b81-9df5-2e2e1cf7e498")
+	if err != nil {
+		t.Fatalf("subscribe: %v", err)
+	}
+	if got := hub.SubscriberCount("01961f5c-6471-7b81-9df5-2e2e1cf7e498"); got != 1 {
+		t.Fatalf("expected subscriber count 1, got %d", got)
+	}
+
+	delivered := hub.PublishToUsers([]string{"01961f5c-6471-7b81-9df5-2e2e1cf7e498"}, FileStatusEvent{
+		EventType: FileStatusChangedEventType,
+		FileUUID:  "01961f5c-6471-7b81-9df5-2e2e1cf7e499",
+		Status:    "processing",
+		Name:      "report.pdf",
+		UpdatedAt: time.Now().UTC().Format(time.RFC3339),
+	})
+	if delivered != 1 {
+		t.Fatalf("expected one delivered event, got %d", delivered)
+	}
+
+	select {
+	case event := <-sub.Events():
+		if event.Status != "processing" {
+			t.Fatalf("expected processing status, got %q", event.Status)
+		}
+	case <-time.After(time.Second):
+		t.Fatalf("timed out waiting for event")
+	}
+
+	sub.Close()
+	if got := hub.SubscriberCount("01961f5c-6471-7b81-9df5-2e2e1cf7e498"); got != 0 {
+		t.Fatalf("expected subscriber count 0 after close, got %d", got)
+	}
+
+	delivered = hub.PublishToUsers([]string{"01961f5c-6471-7b81-9df5-2e2e1cf7e498"}, FileStatusEvent{
+		EventType: FileStatusChangedEventType,
+		FileUUID:  "01961f5c-6471-7b81-9df5-2e2e1cf7e499",
+		Status:    "validated",
+		Name:      "report.pdf",
+		UpdatedAt: time.Now().UTC().Format(time.RFC3339),
+	})
+	if delivered != 0 {
+		t.Fatalf("expected no delivered event after close, got %d", delivered)
+	}
+}
+
+func TestFileStatusEventJSONPayload(t *testing.T) {
+	reason := "file bucket mismatch"
+	event := FileStatusEvent{
+		EventType:     FileStatusChangedEventType,
+		FileUUID:      "01961f5c-6471-7b81-9df5-2e2e1cf7e499",
+		Status:        "failed",
+		Name:          "report.pdf",
+		FailureReason: &reason,
+		UpdatedAt:     "2026-04-05T07:29:34Z",
+	}
+
+	raw, err := json.Marshal(event)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+
+	var decoded map[string]any
+	if err := json.Unmarshal(raw, &decoded); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if decoded["event_type"] != FileStatusChangedEventType {
+		t.Fatalf("unexpected event_type: %#v", decoded["event_type"])
+	}
+	if decoded["status"] != "failed" {
+		t.Fatalf("unexpected status: %#v", decoded["status"])
+	}
+	if decoded["failure_reason"] != reason {
+		t.Fatalf("unexpected failure_reason: %#v", decoded["failure_reason"])
+	}
+}
+
+func TestHubReplaysRecentEventsOnSubscribe(t *testing.T) {
+	hub := NewHub(2, nil)
+	userID := "01961f5c-6471-7b81-9df5-2e2e1cf7e498"
+
+	// Publish without active subscribers.
+	if delivered := hub.PublishToUsers([]string{userID}, FileStatusEvent{
+		EventType: FileStatusChangedEventType,
+		FileUUID:  "01961f5c-6471-7b81-9df5-2e2e1cf7e499",
+		Status:    "processing",
+		Name:      "report.pdf",
+		UpdatedAt: time.Now().UTC().Format(time.RFC3339),
+	}); delivered != 0 {
+		t.Fatalf("expected zero delivered before subscription, got %d", delivered)
+	}
+
+	sub, err := hub.Subscribe(userID)
+	if err != nil {
+		t.Fatalf("subscribe: %v", err)
+	}
+	defer sub.Close()
+
+	select {
+	case event := <-sub.Events():
+		if event.Status != "processing" {
+			t.Fatalf("expected replayed processing status, got %q", event.Status)
+		}
+	case <-time.After(time.Second):
+		t.Fatalf("timed out waiting for replayed event")
+	}
+}
+
+func TestHubSubscribeWithFilterSkipsUnmatchedEvents(t *testing.T) {
+	hub := NewHub(2, nil)
+	userID := "01961f5c-6471-7b81-9df5-2e2e1cf7e498"
+	keepFileID := "01961f5c-6471-7b81-9df5-2e2e1cf7e499"
+	skipFileID := "01961f5c-6471-7b81-9df5-2e2e1cf7e500"
+
+	sub, err := hub.SubscribeWithFilter(userID, func(event FileStatusEvent) bool {
+		return event.FileUUID == keepFileID
+	})
+	if err != nil {
+		t.Fatalf("subscribe with filter: %v", err)
+	}
+	defer sub.Close()
+
+	if delivered := hub.PublishToUsers([]string{userID}, FileStatusEvent{
+		EventType: FileStatusChangedEventType,
+		FileUUID:  skipFileID,
+		Status:    "processing",
+		Name:      "skip.pdf",
+		UpdatedAt: time.Now().UTC().Format(time.RFC3339),
+	}); delivered != 0 {
+		t.Fatalf("expected unmatched event to be skipped, got %d delivered", delivered)
+	}
+
+	if delivered := hub.PublishToUsers([]string{userID}, FileStatusEvent{
+		EventType: FileStatusChangedEventType,
+		FileUUID:  keepFileID,
+		Status:    "ready",
+		Name:      "keep.pdf",
+		UpdatedAt: time.Now().UTC().Format(time.RFC3339),
+	}); delivered != 1 {
+		t.Fatalf("expected matched event to be delivered, got %d", delivered)
+	}
+
+	select {
+	case event := <-sub.Events():
+		if event.FileUUID != keepFileID {
+			t.Fatalf("expected filtered event, got %q", event.FileUUID)
+		}
+	case <-time.After(time.Second):
+		t.Fatalf("timed out waiting for filtered event")
+	}
+
+	select {
+	case event := <-sub.Events():
+		t.Fatalf("unexpected extra event delivered: %#v", event)
+	case <-time.After(50 * time.Millisecond):
+	}
+}
diff --git a/internal/realtime/filemanager/status_poller.go b/internal/realtime/filemanager/status_poller.go
new file mode 100644
index 0000000..67a21c4
--- /dev/null
+++ b/internal/realtime/filemanager/status_poller.go
@@ -0,0 +1,292 @@
+package filemanagerrealtime
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type StatusPollerConfig struct {
+	PollInterval time.Duration
+	BatchSize    int
+	OnPublished  func(context.Context, FileStatusEvent) error
+}
+
+type StatusPoller struct {
+	db     *gorm.DB
+	hub    *Hub
+	logger *slog.Logger
+	config StatusPollerConfig
+}
+
+func NewStatusPoller(db *gorm.DB, hub *Hub, logger *slog.Logger, cfg StatusPollerConfig) *StatusPoller {
+	if cfg.PollInterval <= 0 {
+		cfg.PollInterval = time.Second
+	}
+	if cfg.BatchSize <= 0 {
+		cfg.BatchSize = 100
+	}
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &StatusPoller{
+		db:     db,
+		hub:    hub,
+		logger: logger.With("component", "file-status-poller"),
+		config: cfg,
+	}
+}
+
+func (p *StatusPoller) Run(ctx context.Context) error {
+	if p == nil {
+		return nil
+	}
+	if p.db == nil {
+		return errors.New("status poller requires database")
+	}
+	if p.hub == nil {
+		return errors.New("status poller requires hub")
+	}
+
+	ticker := time.NewTicker(p.config.PollInterval)
+	defer ticker.Stop()
+
+	for {
+		processed, err := p.PollOnce(ctx)
+		if err != nil {
+			if ctx.Err() != nil {
+				return nil
+			}
+			p.logger.Error("file status poll failed", slog.Any("error", err))
+		}
+		if ctx.Err() != nil {
+			return nil
+		}
+		if processed > 0 {
+			continue
+		}
+		select {
+		case <-ctx.Done():
+			return nil
+		case <-ticker.C:
+		}
+	}
+}
+
+func (p *StatusPoller) PollOnce(ctx context.Context) (int, error) {
+	if p == nil {
+		return 0, nil
+	}
+	if p.db == nil {
+		return 0, errors.New("status poller requires database")
+	}
+	if p.hub == nil {
+		return 0, errors.New("status poller requires hub")
+	}
+
+	totalPublished := 0
+	for {
+		rows, err := p.listPendingEvents(ctx)
+		if err != nil {
+			return totalPublished, err
+		}
+		if len(rows) == 0 {
+			return totalPublished, nil
+		}
+
+		deliveredAt := time.Now().UTC()
+		ids := make([][]byte, 0, len(rows))
+		metadataByFileID, metadataErr := p.loadFileMetadata(ctx, rows)
+		if metadataErr != nil {
+			p.logger.Warn("file status metadata enrich failed", slog.Any("error", metadataErr))
+		}
+		for i := range rows {
+			ids = append(ids, cloneBytes(rows[i].ID))
+
+			meta := metadataByFileID[string(rows[i].FileID)]
+			event, recipient, ok := buildFileStatusEventFromRealtimeEvent(&rows[i], meta)
+			if !ok {
+				continue
+			}
+			if p.hub.PublishToUsers([]string{recipient}, event) > 0 {
+				totalPublished++
+			}
+			if p.config.OnPublished != nil {
+				if err := p.config.OnPublished(ctx, event); err != nil {
+					p.logger.Warn("file status post-publish callback failed", slog.Any("error", err), slog.String("file_uuid", event.FileUUID), slog.String("status", event.Status))
+				}
+			}
+		}
+		if err := p.markDelivered(ctx, ids, deliveredAt); err != nil {
+			return totalPublished, err
+		}
+		if len(rows) < p.config.BatchSize {
+			return totalPublished, nil
+		}
+	}
+}
+
+type fileStatusEventFileMetadata struct {
+	FolderUUID *string
+	MimeType   string
+}
+
+func (p *StatusPoller) loadFileMetadata(ctx context.Context, events []filemanager.FileStatusRealtimeEvent) (map[string]fileStatusEventFileMetadata, error) {
+	result := make(map[string]fileStatusEventFileMetadata, len(events))
+	if p == nil || p.db == nil || len(events) == 0 {
+		return result, nil
+	}
+
+	fileIDs := make([][]byte, 0, len(events))
+	seen := make(map[string]struct{}, len(events))
+	for i := range events {
+		key := string(events[i].FileID)
+		if key == "" {
+			continue
+		}
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		fileIDs = append(fileIDs, cloneBytes(events[i].FileID))
+	}
+	if len(fileIDs) == 0 {
+		return result, nil
+	}
+
+	type fileRow struct {
+		ID       []byte `gorm:"column:id"`
+		FolderID []byte `gorm:"column:folder_id"`
+		MimeType string `gorm:"column:mime_type"`
+	}
+	rows := make([]fileRow, 0, len(fileIDs))
+	if err := p.db.WithContext(ctx).
+		Model(&filemanager.File{}).
+		Select("id, folder_id, mime_type").
+		Where("id IN ?", fileIDs).
+		Find(&rows).Error; err != nil {
+		return result, err
+	}
+
+	for i := range rows {
+		meta := fileStatusEventFileMetadata{
+			MimeType: strings.TrimSpace(rows[i].MimeType),
+		}
+		if len(rows[i].FolderID) == 16 {
+			if folderUUID, err := uuidv7.BytesToString(rows[i].FolderID); err == nil {
+				folderUUID = strings.ToLower(strings.TrimSpace(folderUUID))
+				if folderUUID != "" {
+					meta.FolderUUID = &folderUUID
+				}
+			}
+		}
+		result[string(rows[i].ID)] = meta
+	}
+
+	return result, nil
+}
+
+func (p *StatusPoller) listPendingEvents(ctx context.Context) ([]filemanager.FileStatusRealtimeEvent, error) {
+	rows := make([]filemanager.FileStatusRealtimeEvent, 0, p.config.BatchSize)
+	err := p.db.WithContext(ctx).
+		Model(&filemanager.FileStatusRealtimeEvent{}).
+		Where("delivered_at IS NULL").
+		Order("occurred_at ASC").
+		Order("id ASC").
+		Limit(p.config.BatchSize).
+		Find(&rows).Error
+	return rows, err
+}
+
+func (p *StatusPoller) markDelivered(ctx context.Context, ids [][]byte, deliveredAt time.Time) error {
+	if len(ids) == 0 {
+		return nil
+	}
+	deliveredAt = deliveredAt.UTC()
+	return p.db.WithContext(ctx).
+		Model(&filemanager.FileStatusRealtimeEvent{}).
+		Where("id IN ?", ids).
+		Where("delivered_at IS NULL").
+		Updates(map[string]any{
+			"delivered_at": deliveredAt,
+			"updated_at":   deliveredAt,
+		}).Error
+}
+
+func buildFileStatusEventFromRealtimeEvent(row *filemanager.FileStatusRealtimeEvent, meta fileStatusEventFileMetadata) (FileStatusEvent, string, bool) {
+	if row == nil {
+		return FileStatusEvent{}, "", false
+	}
+
+	status := filemanager.NormalizeFileStatus(row.Status)
+	if !isRealtimeStatus(status) {
+		return FileStatusEvent{}, "", false
+	}
+
+	fileUUID, err := uuidv7.BytesToString(row.FileID)
+	if err != nil || strings.TrimSpace(fileUUID) == "" {
+		return FileStatusEvent{}, "", false
+	}
+
+	userUUID, err := uuidv7.BytesToString(row.UserID)
+	if err != nil {
+		return FileStatusEvent{}, "", false
+	}
+	userUUID = strings.ToLower(strings.TrimSpace(userUUID))
+	if userUUID == "" {
+		return FileStatusEvent{}, "", false
+	}
+
+	reason := strings.TrimSpace(row.FailureReason)
+	var failureReason *string
+	if reason != "" {
+		failureReason = &reason
+	}
+
+	updatedAt := row.OccurredAt.UTC()
+	if updatedAt.IsZero() {
+		updatedAt = row.UpdatedAt.UTC()
+	}
+	if updatedAt.IsZero() {
+		updatedAt = time.Now().UTC()
+	}
+
+	return FileStatusEvent{
+		EventType:     FileStatusChangedEventType,
+		FileUUID:      fileUUID,
+		FolderUUID:    meta.FolderUUID,
+		Status:        status,
+		Name:          row.Name,
+		MimeType:      meta.MimeType,
+		FailureReason: failureReason,
+		UpdatedAt:     updatedAt.Format(time.RFC3339),
+	}, userUUID, true
+}
+
+func isRealtimeStatus(status string) bool {
+	switch filemanager.NormalizeFileStatus(status) {
+	case filemanager.FileStatusUploaded,
+		filemanager.FileStatusProcessing,
+		filemanager.FileStatusValidated,
+		filemanager.FileStatusFailed,
+		filemanager.FileStatusReady,
+		filemanager.FileStatusTrashed:
+		return true
+	default:
+		return false
+	}
+}
+
+func cloneBytes(raw []byte) []byte {
+	if len(raw) == 0 {
+		return nil
+	}
+	return append([]byte(nil), raw...)
+}
diff --git a/internal/realtime/filemanager/status_poller_test.go b/internal/realtime/filemanager/status_poller_test.go
new file mode 100644
index 0000000..4f9255a
--- /dev/null
+++ b/internal/realtime/filemanager/status_poller_test.go
@@ -0,0 +1,321 @@
+package filemanagerrealtime
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openStatusPollerTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:file_status_poller_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&filemanager.FileStatusRealtimeEvent{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	if err := db.AutoMigrate(&filemanager.File{}); err != nil {
+		t.Fatalf("auto migrate file: %v", err)
+	}
+	return db
+}
+
+func waitStatusEvent(t *testing.T, sub *Subscription) FileStatusEvent {
+	t.Helper()
+	select {
+	case event := <-sub.Events():
+		return event
+	case <-time.After(time.Second):
+		t.Fatalf("timed out waiting for status event")
+	}
+	return FileStatusEvent{}
+}
+
+func insertRealtimeEventForPollerTest(
+	t *testing.T,
+	db *gorm.DB,
+	fileID []byte,
+	userID []byte,
+	status string,
+	name string,
+	reason string,
+	occurredAt time.Time,
+) {
+	t.Helper()
+	row := &filemanager.FileStatusRealtimeEvent{
+		ID:            uuidv7.MustBytes(),
+		FileID:        append([]byte(nil), fileID...),
+		UserID:        append([]byte(nil), userID...),
+		Status:        status,
+		Name:          name,
+		FailureReason: reason,
+		OccurredAt:    occurredAt.UTC(),
+		CreatedAt:     occurredAt.UTC(),
+		UpdatedAt:     occurredAt.UTC(),
+	}
+	if err := db.WithContext(context.Background()).Create(row).Error; err != nil {
+		t.Fatalf("insert realtime event: %v", err)
+	}
+}
+
+func insertFileForPollerTest(t *testing.T, db *gorm.DB, fileID []byte, folderID []byte, mimeType string, name string) {
+	t.Helper()
+	now := time.Now().UTC()
+	row := &filemanager.File{
+		ID:             append([]byte(nil), fileID...),
+		FolderID:       append([]byte(nil), folderID...),
+		Name:           name,
+		NameNormalized: strings.ToLower(strings.TrimSpace(name)),
+		Extension:      "pdf",
+		SizeBytes:      1,
+		MimeType:       mimeType,
+		Bucket:         "bucket",
+		ObjectKey:      "obj-" + name,
+		Status:         filemanager.FileStatusUploaded,
+		NameSlot:       "live",
+		CreatedAt:      now,
+		UpdatedAt:      now,
+	}
+	if err := db.WithContext(context.Background()).Create(row).Error; err != nil {
+		t.Fatalf("insert file: %v", err)
+	}
+}
+
+func TestStatusPollerEmitsLifecycleEvents(t *testing.T) {
+	db := openStatusPollerTestDB(t)
+	fileID := uuidv7.MustBytes()
+	fileUUID, err := uuidv7.BytesToString(fileID)
+	if err != nil {
+		t.Fatalf("file uuid: %v", err)
+	}
+	ownerID := uuidv7.MustBytes()
+	ownerUUID, err := uuidv7.BytesToString(ownerID)
+	if err != nil {
+		t.Fatalf("owner uuid: %v", err)
+	}
+	folderID := uuidv7.MustBytes()
+	folderUUID, err := uuidv7.BytesToString(folderID)
+	if err != nil {
+		t.Fatalf("folder uuid: %v", err)
+	}
+	insertFileForPollerTest(t, db, fileID, folderID, "application/pdf", "report.pdf")
+
+	hub := NewHub(8, nil)
+	sub, err := hub.Subscribe(ownerUUID)
+	if err != nil {
+		t.Fatalf("subscribe: %v", err)
+	}
+	defer sub.Close()
+
+	poller := NewStatusPoller(db, hub, nil, StatusPollerConfig{
+		PollInterval: time.Second,
+		BatchSize:    50,
+	})
+
+	baseAt := time.Now().UTC().Add(20 * time.Millisecond)
+	insertRealtimeEventForPollerTest(t, db, fileID, ownerID, filemanager.FileStatusUploaded, "report.pdf", "", baseAt)
+	insertRealtimeEventForPollerTest(t, db, fileID, ownerID, filemanager.FileStatusProcessing, "report.pdf", "", baseAt.Add(time.Second))
+	insertRealtimeEventForPollerTest(t, db, fileID, ownerID, filemanager.FileStatusValidated, "report.pdf", "", baseAt.Add(2*time.Second))
+	insertRealtimeEventForPollerTest(t, db, fileID, ownerID, filemanager.FileStatusReady, "report.pdf", "", baseAt.Add(3*time.Second))
+
+	processed, err := poller.PollOnce(context.Background())
+	if err != nil {
+		t.Fatalf("poll once: %v", err)
+	}
+	if processed != 4 {
+		t.Fatalf("expected 4 published events, got %d", processed)
+	}
+
+	event := waitStatusEvent(t, sub)
+	if event.Status != filemanager.FileStatusUploaded {
+		t.Fatalf("expected uploaded status, got %s", event.Status)
+	}
+	if event.FileUUID != fileUUID {
+		t.Fatalf("expected file uuid %s, got %s", fileUUID, event.FileUUID)
+	}
+	if event.FolderUUID == nil || !strings.EqualFold(*event.FolderUUID, folderUUID) {
+		t.Fatalf("expected folder uuid %s, got %#v", folderUUID, event.FolderUUID)
+	}
+	if event.MimeType != "application/pdf" {
+		t.Fatalf("expected mime type application/pdf, got %q", event.MimeType)
+	}
+	event = waitStatusEvent(t, sub)
+	if event.Status != filemanager.FileStatusProcessing {
+		t.Fatalf("expected processing status, got %s", event.Status)
+	}
+	event = waitStatusEvent(t, sub)
+	if event.Status != filemanager.FileStatusValidated {
+		t.Fatalf("expected validated status, got %s", event.Status)
+	}
+	event = waitStatusEvent(t, sub)
+	if event.Status != filemanager.FileStatusReady {
+		t.Fatalf("expected ready status, got %s", event.Status)
+	}
+
+	var deliveredCount int64
+	if err := db.WithContext(context.Background()).
+		Model(&filemanager.FileStatusRealtimeEvent{}).
+		Where("delivered_at IS NOT NULL").
+		Count(&deliveredCount).Error; err != nil {
+		t.Fatalf("count delivered rows: %v", err)
+	}
+	if deliveredCount != 4 {
+		t.Fatalf("expected 4 delivered rows, got %d", deliveredCount)
+	}
+}
+
+func TestStatusPollerInvokesOnPublishedCallback(t *testing.T) {
+	db := openStatusPollerTestDB(t)
+	fileID := uuidv7.MustBytes()
+	fileUUID, err := uuidv7.BytesToString(fileID)
+	if err != nil {
+		t.Fatalf("file uuid: %v", err)
+	}
+	userID := uuidv7.MustBytes()
+	userUUID, err := uuidv7.BytesToString(userID)
+	if err != nil {
+		t.Fatalf("user uuid: %v", err)
+	}
+	folderID := uuidv7.MustBytes()
+	insertFileForPollerTest(t, db, fileID, folderID, "application/pdf", "report.pdf")
+	insertRealtimeEventForPollerTest(t, db, fileID, userID, filemanager.FileStatusReady, "report.pdf", "", time.Now().UTC().Add(20*time.Millisecond))
+
+	hub := NewHub(4, nil)
+	sub, err := hub.Subscribe(userUUID)
+	if err != nil {
+		t.Fatalf("subscribe: %v", err)
+	}
+	defer sub.Close()
+
+	var callbackCount int
+	var callbackEvent FileStatusEvent
+	poller := NewStatusPoller(db, hub, nil, StatusPollerConfig{
+		PollInterval: time.Second,
+		BatchSize:    50,
+		OnPublished: func(_ context.Context, event FileStatusEvent) error {
+			callbackCount++
+			callbackEvent = event
+			return nil
+		},
+	})
+
+	processed, err := poller.PollOnce(context.Background())
+	if err != nil {
+		t.Fatalf("poll once failed: %v", err)
+	}
+	if processed != 1 {
+		t.Fatalf("expected one published event, got %d", processed)
+	}
+	if callbackCount != 1 {
+		t.Fatalf("expected callback to run once, got %d", callbackCount)
+	}
+	if callbackEvent.Status != filemanager.FileStatusReady {
+		t.Fatalf("expected ready callback event, got %s", callbackEvent.Status)
+	}
+	if callbackEvent.FileUUID != fileUUID {
+		t.Fatalf("expected callback file uuid %s, got %s", fileUUID, callbackEvent.FileUUID)
+	}
+	_ = waitStatusEvent(t, sub)
+}
+
+func TestStatusPollerEmitsFailedReason(t *testing.T) {
+	db := openStatusPollerTestDB(t)
+	fileID := uuidv7.MustBytes()
+	ownerID := uuidv7.MustBytes()
+	ownerUUID, err := uuidv7.BytesToString(ownerID)
+	if err != nil {
+		t.Fatalf("owner uuid: %v", err)
+	}
+
+	hub := NewHub(4, nil)
+	sub, err := hub.Subscribe(ownerUUID)
+	if err != nil {
+		t.Fatalf("subscribe: %v", err)
+	}
+	defer sub.Close()
+
+	poller := NewStatusPoller(db, hub, nil, StatusPollerConfig{
+		PollInterval: time.Second,
+		BatchSize:    50,
+	})
+
+	insertRealtimeEventForPollerTest(
+		t,
+		db,
+		fileID,
+		ownerID,
+		filemanager.FileStatusFailed,
+		"invalid.pdf",
+		"file bucket mismatch",
+		time.Now().UTC().Add(20*time.Millisecond),
+	)
+
+	processed, err := poller.PollOnce(context.Background())
+	if err != nil {
+		t.Fatalf("poll once failed: %v", err)
+	}
+	if processed != 1 {
+		t.Fatalf("expected one processed failed row, got %d", processed)
+	}
+	event := waitStatusEvent(t, sub)
+	if event.Status != filemanager.FileStatusFailed {
+		t.Fatalf("expected failed status event, got %s", event.Status)
+	}
+	if event.FailureReason == nil || *event.FailureReason == "" {
+		t.Fatalf("expected failure reason on failed event")
+	}
+}
+
+func TestStatusPollerSkipsRowsWithoutValidRecipient(t *testing.T) {
+	db := openStatusPollerTestDB(t)
+	fileID := uuidv7.MustBytes()
+	invalidUserID := []byte{1, 2, 3}
+
+	insertRealtimeEventForPollerTest(
+		t,
+		db,
+		fileID,
+		invalidUserID,
+		filemanager.FileStatusUploaded,
+		"nobody.pdf",
+		"",
+		time.Now().UTC().Add(20*time.Millisecond),
+	)
+
+	hub := NewHub(4, nil)
+	poller := NewStatusPoller(db, hub, nil, StatusPollerConfig{
+		PollInterval: time.Second,
+		BatchSize:    50,
+	})
+
+	processed, err := poller.PollOnce(context.Background())
+	if err != nil {
+		t.Fatalf("poll once: %v", err)
+	}
+	if processed != 0 {
+		t.Fatalf("expected zero emitted events for row without valid recipient, got %d", processed)
+	}
+
+	var deliveredCount int64
+	if err := db.WithContext(context.Background()).
+		Model(&filemanager.FileStatusRealtimeEvent{}).
+		Where("delivered_at IS NOT NULL").
+		Count(&deliveredCount).Error; err != nil {
+		t.Fatalf("count delivered rows: %v", err)
+	}
+	if deliveredCount != 1 {
+		t.Fatalf("expected skipped row to be marked delivered, got %d", deliveredCount)
+	}
+}
diff --git a/internal/realtime/helicopterfile/hub.go b/internal/realtime/helicopterfile/hub.go
new file mode 100644
index 0000000..5bc39c8
--- /dev/null
+++ b/internal/realtime/helicopterfile/hub.go
@@ -0,0 +1,261 @@
+package helicopterfilerealtime
+
+import (
+	"errors"
+	"log/slog"
+	"strings"
+	"sync"
+)
+
+const (
+	DefaultEventType      = "helicopter_file_changed"
+	DefaultSubscriberSize = 32
+)
+
+type Event struct {
+	EventType         string `json:"event_type"`
+	HelicopterID      string `json:"helicopter_id"`
+	HelicopterFileID  string `json:"helicopter_file_id"`
+	FileID            string `json:"file_id,omitempty"`
+	Section           string `json:"section,omitempty"`
+	Name              string `json:"name,omitempty"`
+	MimeType          string `json:"mime_type,omitempty"`
+	AttachmentPending bool   `json:"attachment_pending"`
+	Position          int    `json:"position,omitempty"`
+	IsMandatory       bool   `json:"is_mandatory,omitempty"`
+	UpdatedAt         string `json:"updated_at,omitempty"`
+}
+
+type Subscription struct {
+	events  <-chan Event
+	done    <-chan struct{}
+	closeFn func()
+}
+
+func (s *Subscription) Events() <-chan Event {
+	if s == nil {
+		return nil
+	}
+	return s.events
+}
+
+func (s *Subscription) Done() <-chan struct{} {
+	if s == nil {
+		return nil
+	}
+	return s.done
+}
+
+func (s *Subscription) Close() {
+	if s == nil || s.closeFn == nil {
+		return
+	}
+	s.closeFn()
+}
+
+type subscriber struct {
+	events    chan Event
+	done      chan struct{}
+	match     func(Event) bool
+	closeOnce sync.Once
+}
+
+func (s *subscriber) close() {
+	if s == nil {
+		return
+	}
+	s.closeOnce.Do(func() {
+		close(s.done)
+	})
+}
+
+type Hub struct {
+	mu           sync.RWMutex
+	subscribers  map[string]map[uint64]*subscriber
+	recentByUser map[string][]Event
+	nextID       uint64
+	buffer       int
+	replayLimit  int
+	logger       *slog.Logger
+}
+
+func NewHub(buffer int, logger *slog.Logger) *Hub {
+	if buffer <= 0 {
+		buffer = DefaultSubscriberSize
+	}
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &Hub{
+		subscribers:  make(map[string]map[uint64]*subscriber),
+		recentByUser: make(map[string][]Event),
+		buffer:       buffer,
+		replayLimit:  maxInt(buffer*4, DefaultSubscriberSize),
+		logger:       logger.With("component", "helicopter-file-hub"),
+	}
+}
+
+func (h *Hub) Subscribe(userUUID string) (*Subscription, error) {
+	return h.SubscribeWithFilter(userUUID, nil)
+}
+
+func (h *Hub) SubscribeWithFilter(userUUID string, match func(Event) bool) (*Subscription, error) {
+	if h == nil {
+		return nil, errors.New("helicopter file hub is not configured")
+	}
+	userUUID = canonicalUserID(userUUID)
+	if userUUID == "" {
+		return nil, errors.New("user uuid is required")
+	}
+
+	sub := &subscriber{
+		events: make(chan Event, h.buffer),
+		done:   make(chan struct{}),
+		match:  match,
+	}
+
+	h.mu.Lock()
+	h.nextID++
+	subID := h.nextID
+	if h.subscribers[userUUID] == nil {
+		h.subscribers[userUUID] = make(map[uint64]*subscriber)
+	}
+	h.subscribers[userUUID][subID] = sub
+	backlog := append([]Event(nil), h.recentByUser[userUUID]...)
+	h.mu.Unlock()
+
+	for i := range backlog {
+		if sub.match != nil && !sub.match(backlog[i]) {
+			continue
+		}
+		enqueueSubscriberEvent(sub, backlog[i])
+	}
+
+	var closeOnce sync.Once
+	closeFn := func() {
+		closeOnce.Do(func() {
+			h.mu.Lock()
+			defer h.mu.Unlock()
+
+			if byUser, ok := h.subscribers[userUUID]; ok {
+				delete(byUser, subID)
+				if len(byUser) == 0 {
+					delete(h.subscribers, userUUID)
+				}
+			}
+			sub.close()
+		})
+	}
+
+	return &Subscription{
+		events:  sub.events,
+		done:    sub.done,
+		closeFn: closeFn,
+	}, nil
+}
+
+func (h *Hub) PublishToUsers(userUUIDs []string, event Event) int {
+	if h == nil {
+		return 0
+	}
+	if strings.TrimSpace(event.EventType) == "" {
+		event.EventType = DefaultEventType
+	}
+	if strings.TrimSpace(event.HelicopterID) == "" || strings.TrimSpace(event.HelicopterFileID) == "" {
+		return 0
+	}
+
+	uniqueUsers := make(map[string]struct{}, len(userUUIDs))
+	for i := range userUUIDs {
+		userID := canonicalUserID(userUUIDs[i])
+		if userID == "" {
+			continue
+		}
+		uniqueUsers[userID] = struct{}{}
+	}
+	if len(uniqueUsers) == 0 {
+		return 0
+	}
+
+	delivered := 0
+	for userID := range uniqueUsers {
+		h.mu.Lock()
+		h.recentByUser[userID] = appendRecentEvents(h.recentByUser[userID], event, h.replayLimit)
+		h.mu.Unlock()
+
+		h.mu.RLock()
+		byUser := h.subscribers[userID]
+		if len(byUser) == 0 {
+			h.mu.RUnlock()
+			continue
+		}
+
+		for _, sub := range byUser {
+			select {
+			case <-sub.done:
+				continue
+			default:
+			}
+			if sub.match != nil && !sub.match(event) {
+				continue
+			}
+
+			if enqueueSubscriberEvent(sub, event) {
+				delivered++
+			}
+		}
+		h.mu.RUnlock()
+	}
+	return delivered
+}
+
+func canonicalUserID(raw string) string {
+	return strings.ToLower(strings.TrimSpace(raw))
+}
+
+func enqueueSubscriberEvent(sub *subscriber, event Event) bool {
+	if sub == nil {
+		return false
+	}
+	select {
+	case <-sub.done:
+		return false
+	default:
+	}
+
+	select {
+	case sub.events <- event:
+		return true
+	default:
+		select {
+		case <-sub.events:
+		default:
+		}
+		select {
+		case sub.events <- event:
+			return true
+		default:
+			return false
+		}
+	}
+}
+
+func appendRecentEvents(current []Event, event Event, limit int) []Event {
+	if limit <= 0 {
+		return current[:0]
+	}
+	current = append(current, event)
+	if len(current) <= limit {
+		return current
+	}
+	start := len(current) - limit
+	copy(current, current[start:])
+	return current[:limit]
+}
+
+func maxInt(a, b int) int {
+	if a > b {
+		return a
+	}
+	return b
+}
diff --git a/internal/repository/mysql/action_signoff_repo.go b/internal/repository/mysql/action_signoff_repo.go
new file mode 100644
index 0000000..02f16c7
--- /dev/null
+++ b/internal/repository/mysql/action_signoff_repo.go
@@ -0,0 +1,70 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	actionsignoff "wucher/internal/domain/action_signoff"
+)
+
+type ActionSignoffRepository struct{ db *gorm.DB }
+
+func NewActionSignoffRepository(db *gorm.DB) *ActionSignoffRepository {
+	return &ActionSignoffRepository{db: db}
+}
+
+func (r *ActionSignoffRepository) GetByFlight(ctx context.Context, flightID []byte) (*actionsignoff.ActionSignoff, error) {
+	var row actionsignoff.ActionSignoff
+	err := r.db.WithContext(ctx).
+		Where("flight_id = ? AND complaint_id IS NULL", flightID).
+		Order("created_at DESC").
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *ActionSignoffRepository) GetByComplaint(ctx context.Context, complaintID []byte) (*actionsignoff.ActionSignoff, error) {
+	var row actionsignoff.ActionSignoff
+	err := r.db.WithContext(ctx).
+		Where("complaint_id = ?", complaintID).
+		Order("created_at DESC").
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *ActionSignoffRepository) GetByComplaintIDs(ctx context.Context, complaintIDs [][]byte) (map[string]*actionsignoff.ActionSignoff, error) {
+	out := make(map[string]*actionsignoff.ActionSignoff, len(complaintIDs))
+	if len(complaintIDs) == 0 {
+		return out, nil
+	}
+	var rows []actionsignoff.ActionSignoff
+	err := r.db.WithContext(ctx).
+		Where("complaint_id IN ?", complaintIDs).
+		Order("created_at DESC").
+		Find(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	for i := range rows {
+		key := string(rows[i].ComplaintID)
+		if _, ok := out[key]; !ok {
+			out[key] = &rows[i]
+		}
+	}
+	return out, nil
+}
+
+func (r *ActionSignoffRepository) Create(ctx context.Context, row *actionsignoff.ActionSignoff) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *ActionSignoffRepository) Update(ctx context.Context, row *actionsignoff.ActionSignoff) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
diff --git a/internal/repository/mysql/actor_user.go b/internal/repository/mysql/actor_user.go
new file mode 100644
index 0000000..518039e
--- /dev/null
+++ b/internal/repository/mysql/actor_user.go
@@ -0,0 +1,11 @@
+package mysql
+
+import (
+	"context"
+
+	"wucher/internal/shared/pkg/appctx"
+)
+
+func actorUserIDFromContext(ctx context.Context) []byte {
+	return appctx.GetUserID(ctx)
+}
diff --git a/internal/repository/mysql/after_flight_inspection_repo.go b/internal/repository/mysql/after_flight_inspection_repo.go
new file mode 100644
index 0000000..7890261
--- /dev/null
+++ b/internal/repository/mysql/after_flight_inspection_repo.go
@@ -0,0 +1,72 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	"wucher/internal/domain/helicopter"
+)
+
+type AfterFlightInspectionRepository struct {
+	db *gorm.DB
+}
+
+func NewAfterFlightInspectionRepository(db *gorm.DB) *AfterFlightInspectionRepository {
+	return &AfterFlightInspectionRepository{db: db}
+}
+
+func (r *AfterFlightInspectionRepository) Upsert(ctx context.Context, row *afterflightinspection.AfterFlightInspection) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *AfterFlightInspectionRepository) GetByFlightInspectionID(ctx context.Context, flightInspectionID []byte) (*afterflightinspection.AfterFlightInspection, error) {
+	var rows []afterflightinspection.AfterFlightInspection
+	err := r.db.WithContext(ctx).Where("flight_inspection_id = ?", flightInspectionID).Limit(1).Find(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	if len(rows) == 0 {
+		return nil, nil
+	}
+	return &rows[0], nil
+}
+
+func (r *AfterFlightInspectionRepository) DeleteByFlightInspectionID(ctx context.Context, flightInspectionID []byte) error {
+	return r.db.WithContext(ctx).
+		Where("flight_inspection_id = ?", flightInspectionID).
+		Delete(&afterflightinspection.AfterFlightInspection{}).Error
+}
+
+func (r *AfterFlightInspectionRepository) FlightInspectionExists(ctx context.Context, flightInspectionID []byte) (bool, error) {
+	if len(flightInspectionID) != 16 {
+		return false, nil
+	}
+	var total int64
+	err := r.db.WithContext(ctx).
+		Model(&flightinspection.FlightInspection{}).
+		Where("id = ?", flightInspectionID).
+		Count(&total).Error
+	return total > 0, err
+}
+
+func (r *AfterFlightInspectionRepository) GetHelicopterCapabilities(ctx context.Context, flightInspectionID []byte) (*afterflightinspection.HelicopterCapabilities, error) {
+	var caps afterflightinspection.HelicopterCapabilities
+	tx := r.db.WithContext(ctx).
+		Model(&helicopter.Helicopter{}).
+		Joins("JOIN reserve_acs ra ON ra.helicopter_id = helicopters.id").
+		Where("ra.inspection_id = ? AND ra.deleted_at IS NULL", flightInspectionID).
+		Select("helicopters.nr1, helicopters.nr2, helicopters.lh, helicopters.rh, helicopters.mgb, helicopters.igb, helicopters.tgb").
+		Limit(1).
+		Scan(&caps)
+	if tx.Error != nil {
+		return nil, tx.Error
+	}
+	if tx.RowsAffected == 0 {
+		return nil, errors.New("helicopter not found for flight inspection")
+	}
+	return &caps, nil
+}
diff --git a/internal/repository/mysql/air_rescuer_checklist_repo.go b/internal/repository/mysql/air_rescuer_checklist_repo.go
new file mode 100644
index 0000000..03e40d6
--- /dev/null
+++ b/internal/repository/mysql/air_rescuer_checklist_repo.go
@@ -0,0 +1,325 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	airrescuechecklist "wucher/internal/domain/air_rescue_checklist"
+	basedomain "wucher/internal/domain/base"
+)
+
+type AirRescuerChecklistRepository struct {
+	db *gorm.DB
+}
+
+func NewAirRescuerChecklistRepository(db *gorm.DB) *AirRescuerChecklistRepository {
+	return &AirRescuerChecklistRepository{db: db}
+}
+
+func (r *AirRescuerChecklistRepository) InTx(ctx context.Context, fn func(txRepo airrescuechecklist.TxRepository) error) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		return fn(&AirRescuerChecklistRepository{db: tx})
+	})
+}
+
+func (r *AirRescuerChecklistRepository) CreateChecklist(ctx context.Context, row *airrescuechecklist.AirRescuerChecklist) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *AirRescuerChecklistRepository) NextChecklistPosition(ctx context.Context, hemsBaseID []byte, scopeCode string) (int, error) {
+	var maxPos int
+	err := r.db.WithContext(ctx).
+		Table("air_rescuer_checklists").
+		Select("COALESCE(MAX(position), 0)").
+		Where("hems_base_id = ? AND scope_code = ? AND deleted_at IS NULL", hemsBaseID, scopeCode).
+		Scan(&maxPos).Error
+	if err != nil {
+		return 0, err
+	}
+	return maxPos + 1, nil
+}
+
+func (r *AirRescuerChecklistRepository) LockChecklistByID(ctx context.Context, id []byte) (*airrescuechecklist.AirRescuerChecklist, error) {
+	row := &airrescuechecklist.AirRescuerChecklist{}
+	if err := r.db.WithContext(ctx).
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Take(row).Error; err != nil {
+		return nil, err
+	}
+	return row, nil
+}
+
+func (r *AirRescuerChecklistRepository) UpdateChecklist(ctx context.Context, row *airrescuechecklist.AirRescuerChecklist) error {
+	updates := map[string]any{
+		"scope_code": row.ScopeCode,
+		"title":      row.Title,
+		"position":   row.Position,
+		"updated_by": row.UpdatedBy,
+	}
+	res := r.db.WithContext(ctx).Model(&airrescuechecklist.AirRescuerChecklist{}).
+		Where("id = ? AND deleted_at IS NULL", row.ID).
+		Updates(updates)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *AirRescuerChecklistRepository) SoftDeleteChecklist(ctx context.Context, id []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	res := r.db.WithContext(ctx).Model(&airrescuechecklist.AirRescuerChecklist{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(map[string]any{"deleted_at": now, "deleted_by": deletedBy, "updated_by": deletedBy})
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *AirRescuerChecklistRepository) SoftDeleteItemsByChecklistID(ctx context.Context, checklistID []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	return r.db.WithContext(ctx).Model(&airrescuechecklist.AirRescuerChecklistItem{}).
+		Where("checklist_id = ? AND deleted_at IS NULL", checklistID).
+		Updates(map[string]any{"deleted_at": now, "deleted_by": deletedBy, "updated_by": deletedBy}).Error
+}
+
+func (r *AirRescuerChecklistRepository) CreateChecklistItem(ctx context.Context, row *airrescuechecklist.AirRescuerChecklistItem) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *AirRescuerChecklistRepository) CreateChecklistItems(ctx context.Context, rows []airrescuechecklist.AirRescuerChecklistItem) error {
+	if len(rows) == 0 {
+		return nil
+	}
+	return r.db.WithContext(ctx).Create(&rows).Error
+}
+
+func (r *AirRescuerChecklistRepository) NextChecklistItemPosition(ctx context.Context, checklistID []byte) (int, error) {
+	var maxPos int
+	err := r.db.WithContext(ctx).
+		Table("air_rescuer_checklist_items").
+		Select("COALESCE(MAX(position), 0)").
+		Where("checklist_id = ? AND deleted_at IS NULL", checklistID).
+		Scan(&maxPos).Error
+	if err != nil {
+		return 0, err
+	}
+	return maxPos + 1, nil
+}
+
+func (r *AirRescuerChecklistRepository) LockChecklistItemByID(ctx context.Context, id []byte) (*airrescuechecklist.AirRescuerChecklistItem, error) {
+	row := &airrescuechecklist.AirRescuerChecklistItem{}
+	if err := r.db.WithContext(ctx).
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Take(row).Error; err != nil {
+		return nil, err
+	}
+	return row, nil
+}
+
+func (r *AirRescuerChecklistRepository) UpdateChecklistItem(ctx context.Context, row *airrescuechecklist.AirRescuerChecklistItem) error {
+	updates := map[string]any{
+		"name":       row.Name,
+		"position":   row.Position,
+		"updated_by": row.UpdatedBy,
+	}
+	res := r.db.WithContext(ctx).Model(&airrescuechecklist.AirRescuerChecklistItem{}).
+		Where("id = ? AND deleted_at IS NULL", row.ID).
+		Updates(updates)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *AirRescuerChecklistRepository) SoftDeleteChecklistItem(ctx context.Context, id []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	res := r.db.WithContext(ctx).Model(&airrescuechecklist.AirRescuerChecklistItem{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(map[string]any{"deleted_at": now, "deleted_by": deletedBy, "updated_by": deletedBy})
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *AirRescuerChecklistRepository) GetChecklistByID(ctx context.Context, id []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+	out := &airrescuechecklist.ChecklistHeaderView{}
+	err := r.db.WithContext(ctx).
+		Table("air_rescuer_checklists c").
+		Select(`
+			c.id,
+			c.hems_base_id,
+			hb.base AS base_name,
+			hb.base_abbreviation,
+			bc.key AS base_category,
+			c.scope_code,
+			c.title,
+			c.position,
+			c.created_at,
+			c.created_by,
+			c.updated_at`).
+		Joins("LEFT JOIN bases hb ON hb.id = c.hems_base_id").
+		Joins("LEFT JOIN base_categories bc ON bc.id = hb.base_category_id").
+		Where("c.id = ? AND c.deleted_at IS NULL", id).
+		Where("hb.id IS NOT NULL").
+		Take(out).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (r *AirRescuerChecklistRepository) GetChecklistItemByID(ctx context.Context, id []byte) (*airrescuechecklist.ChecklistItemView, error) {
+	out := &airrescuechecklist.ChecklistItemView{}
+	err := r.db.WithContext(ctx).
+		Table("air_rescuer_checklist_items i").
+		Select(`
+			i.id,
+			i.checklist_id,
+			i.name,
+			i.position,
+			i.created_at,
+			i.created_by,
+			i.updated_at`).
+		Joins("JOIN air_rescuer_checklists c ON c.id = i.checklist_id AND c.deleted_at IS NULL").
+		Where("i.id = ? AND i.deleted_at IS NULL", id).
+		Take(out).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (r *AirRescuerChecklistRepository) ListChecklistHeaders(ctx context.Context, filter airrescuechecklist.ChecklistHeaderFilter) ([]airrescuechecklist.ChecklistHeaderView, error) {
+	rows := make([]airrescuechecklist.ChecklistHeaderView, 0)
+	q := r.db.WithContext(ctx).
+		Table("air_rescuer_checklists c").
+		Select(`
+			c.id,
+			c.hems_base_id,
+			hb.base AS base_name,
+			hb.base_abbreviation,
+			bc.key AS base_category,
+			c.scope_code,
+			c.title,
+			c.position,
+			c.created_at,
+			c.created_by,
+			c.updated_at`).
+		Joins("LEFT JOIN bases hb ON hb.id = c.hems_base_id").
+		Joins("LEFT JOIN base_categories bc ON bc.id = hb.base_category_id").
+		Where("c.deleted_at IS NULL").
+		Where("hb.id IS NOT NULL")
+
+	if len(filter.HEMSBaseID) == 16 {
+		q = q.Where("c.hems_base_id = ?", filter.HEMSBaseID)
+	}
+	if scopeCode := airrescuechecklist.CanonicalizeAirRescuerChecklistScope(filter.ScopeCode); scopeCode != "" {
+		q = q.Where("UPPER(c.scope_code) = ?", scopeCode)
+	}
+	if categoryType, ok := basedomain.NormalizeCategoryType(filter.CategoryType); ok && strings.TrimSpace(filter.CategoryType) != "" {
+		q = q.Where("bc.key = ?", categoryType)
+	}
+	q = applyChecklistBaseFilters(q, "hb", filter.BaseName, filter.BaseAbbreviation)
+
+	err := q.Order("CASE WHEN hb.sortkey IS NULL THEN 1 ELSE 0 END ASC, hb.sortkey ASC, hb.base ASC, c.position ASC, c.title ASC").Scan(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *AirRescuerChecklistRepository) ListChecklistItemsByChecklistIDs(ctx context.Context, checklistIDs [][]byte) ([]airrescuechecklist.ChecklistItemView, error) {
+	if len(checklistIDs) == 0 {
+		return []airrescuechecklist.ChecklistItemView{}, nil
+	}
+	rows := make([]airrescuechecklist.ChecklistItemView, 0)
+	err := r.db.WithContext(ctx).
+		Table("air_rescuer_checklist_items i").
+		Select(`
+			i.id,
+			i.checklist_id,
+			i.name,
+			i.position,
+			i.created_at,
+			i.created_by,
+			i.updated_at`).
+		Joins("JOIN air_rescuer_checklists c ON c.id = i.checklist_id AND c.deleted_at IS NULL").
+		Where("i.deleted_at IS NULL AND i.checklist_id IN ?", checklistIDs).
+		Order("i.checklist_id ASC, i.position ASC, i.name ASC").
+		Scan(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *AirRescuerChecklistRepository) ListHEMSBases(ctx context.Context, filter airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+	rows := make([]airrescuechecklist.HEMSBaseView, 0)
+	q := r.db.WithContext(ctx).
+		Table("bases b").
+		Select(`
+			b.id,
+			b.base AS base_name,
+			b.base_abbreviation,
+			bc.key AS base_category,
+			COALESCE(b.sortkey, 0) AS position`).
+		Joins("JOIN base_categories bc ON bc.id = b.base_category_id").
+		Where("b.is_active = ?", true).
+		Where("b.checklist = ?", true)
+
+	if len(filter.HEMSBaseID) == 16 {
+		q = q.Where("b.id = ?", filter.HEMSBaseID)
+	}
+	if categoryType, ok := basedomain.NormalizeCategoryType(filter.CategoryType); ok && strings.TrimSpace(filter.CategoryType) != "" {
+		q = q.Where("bc.key = ?", categoryType)
+	}
+	q = applyChecklistBaseFilters(q, "b", filter.BaseName, filter.BaseAbbreviation)
+
+	if err := q.Order("CASE WHEN b.sortkey IS NULL THEN 1 ELSE 0 END ASC, b.sortkey ASC, b.base ASC").Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func applyChecklistBaseFilters(q *gorm.DB, alias, baseName, baseAbbreviation string) *gorm.DB {
+	baseCol := "base"
+	abbrCol := "base_abbreviation"
+	if strings.TrimSpace(alias) != "" {
+		baseCol = strings.TrimSpace(alias) + ".base"
+		abbrCol = strings.TrimSpace(alias) + ".base_abbreviation"
+	}
+	if needle := strings.ToLower(strings.TrimSpace(baseName)); needle != "" {
+		q = q.Where("LOWER("+baseCol+") LIKE ?", "%"+needle+"%")
+	}
+	if needle := strings.ToLower(strings.TrimSpace(baseAbbreviation)); needle != "" {
+		q = q.Where("LOWER("+abbrCol+") LIKE ?", "%"+needle+"%")
+	}
+	return q
+}
diff --git a/internal/repository/mysql/air_rescuer_checklist_repo_test.go b/internal/repository/mysql/air_rescuer_checklist_repo_test.go
new file mode 100644
index 0000000..47e63c9
--- /dev/null
+++ b/internal/repository/mysql/air_rescuer_checklist_repo_test.go
@@ -0,0 +1,660 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	airrescuechecklist "wucher/internal/domain/air_rescue_checklist"
+	basedomain "wucher/internal/domain/base"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openAirRescuerChecklistRepoTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:air_rescuer_checklist_repo_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+
+	createBaseCategory := "CREATE TABLE base_categories (\n\tid BLOB PRIMARY KEY,\n\t`key` TEXT UNIQUE,\n\tname TEXT NOT NULL\n);"
+	if err := db.Exec(createBaseCategory).Error; err != nil {
+		t.Fatalf("create base_categories: %v", err)
+	}
+
+	createBase := `
+CREATE TABLE bases (
+	id BLOB PRIMARY KEY,
+	base_category_id BLOB NOT NULL,
+	base TEXT NOT NULL,
+	base_abbreviation TEXT NULL,
+	sortkey INTEGER NULL,
+	checklist INTEGER NOT NULL DEFAULT 0,
+	is_active INTEGER NOT NULL DEFAULT 1
+);`
+	if err := db.Exec(createBase).Error; err != nil {
+		t.Fatalf("create bases: %v", err)
+	}
+
+	createChecklist := `
+CREATE TABLE air_rescuer_checklists (
+	id BLOB PRIMARY KEY,
+	hems_base_id BLOB NOT NULL,
+	scope_code TEXT NOT NULL,
+	title TEXT NOT NULL,
+	position INTEGER NOT NULL DEFAULT 1,
+	created_at DATETIME NULL,
+	created_by BLOB NULL,
+	updated_at DATETIME NULL,
+	updated_by BLOB NULL,
+	deleted_at DATETIME NULL,
+	deleted_by BLOB NULL
+);`
+	if err := db.Exec(createChecklist).Error; err != nil {
+		t.Fatalf("create air_rescuer_checklists: %v", err)
+	}
+
+	createItems := `
+CREATE TABLE air_rescuer_checklist_items (
+	id BLOB PRIMARY KEY,
+	checklist_id BLOB NOT NULL,
+	name TEXT NOT NULL,
+	position INTEGER NOT NULL DEFAULT 1,
+	created_at DATETIME NULL,
+	created_by BLOB NULL,
+	updated_at DATETIME NULL,
+	updated_by BLOB NULL,
+	deleted_at DATETIME NULL,
+	deleted_by BLOB NULL
+);`
+	if err := db.Exec(createItems).Error; err != nil {
+		t.Fatalf("create air_rescuer_checklist_items: %v", err)
+	}
+	regularCategoryID, hemsCategoryID := airRescuerChecklistCategoryIDs()
+	toBlob := func(b []byte) string { return fmt.Sprintf("X'%x'", b) }
+	if err := db.Exec(
+		fmt.Sprintf(
+			"INSERT INTO base_categories(id, `key`, name) VALUES(%s, 'regular', 'Regular'),(%s, 'hems', 'HEMS')",
+			toBlob(regularCategoryID),
+			toBlob(hemsCategoryID),
+		),
+	).Error; err != nil {
+		t.Fatalf("seed base_categories: %v", err)
+	}
+
+	return db
+}
+
+func airRescuerChecklistCategoryIDs() (regularID, hemsID []byte) {
+	return []byte("catregular000001"), []byte("cathems000000001")
+}
+
+func TestAirRescuerChecklistRepositoryListChecklistHeaders_SortsByPositionThenTitle(t *testing.T) {
+	db := openAirRescuerChecklistRepoTestDB(t)
+	repo := NewAirRescuerChecklistRepository(db)
+	ctx := context.Background()
+
+	baseID := uuidv7.MustBytes()
+	now := time.Now().UTC()
+	asBlob := func(b []byte) string { return fmt.Sprintf("X'%x'", b) }
+	_, hemsCategoryID := airRescuerChecklistCategoryIDs()
+	if err := db.Exec(
+		fmt.Sprintf(`INSERT INTO bases(id, base_category_id, base, base_abbreviation, sortkey, checklist, is_active) VALUES(%s, %s, ?, ?, ?, 1, ?)`, asBlob(baseID), asBlob(hemsCategoryID)),
+		"Gallus 1 - Zurs Lech", "G1", 1, 1,
+	).Error; err != nil {
+		t.Fatalf("insert bases: %v", err)
+	}
+
+	// Seed deliberately out of desired display order. Duplicate position=1 is allowed.
+	rows := []struct {
+		id       []byte
+		scope    string
+		title    string
+		position int
+	}{
+		{id: uuidv7.MustBytes(), scope: airrescuechecklist.AirRescuerChecklistScopeTA, title: "Zulu", position: 2},
+		{id: uuidv7.MustBytes(), scope: airrescuechecklist.AirRescuerChecklistScopeTA, title: "Bravo", position: 1},
+		{id: uuidv7.MustBytes(), scope: airrescuechecklist.AirRescuerChecklistScopeTA, title: "Alpha", position: 1},
+	}
+	for i := range rows {
+		if err := db.Exec(
+			fmt.Sprintf(`INSERT INTO air_rescuer_checklists(id, hems_base_id, scope_code, title, position, created_at, updated_at, deleted_at) VALUES (%s, %s, ?, ?, ?, ?, ?, NULL)`,
+				asBlob(rows[i].id), asBlob(baseID)),
+			rows[i].scope, rows[i].title, rows[i].position, now, now,
+		).Error; err != nil {
+			t.Fatalf("insert checklist[%d]: %v", i, err)
+		}
+	}
+
+	got, err := repo.ListChecklistHeaders(ctx, airrescuechecklist.ChecklistHeaderFilter{
+		HEMSBaseID: baseID,
+		ScopeCode:  airrescuechecklist.AirRescuerChecklistScopeTA,
+	})
+	if err != nil {
+		t.Fatalf("ListChecklistHeaders: %v", err)
+	}
+	if len(got) != 3 {
+		t.Fatalf("expected 3 rows, got %d", len(got))
+	}
+
+	wantTitles := []string{"Alpha", "Bravo", "Zulu"}
+	wantPos := []int{1, 1, 2}
+	for i := range got {
+		if got[i].Title != wantTitles[i] || got[i].Position != wantPos[i] {
+			t.Fatalf("unexpected row[%d]: got title=%q pos=%d, want title=%q pos=%d", i, got[i].Title, got[i].Position, wantTitles[i], wantPos[i])
+		}
+	}
+}
+
+func TestAirRescuerChecklistRepositoryListChecklistItemsByChecklistIDs_SortsByPositionThenName(t *testing.T) {
+	db := openAirRescuerChecklistRepoTestDB(t)
+	repo := NewAirRescuerChecklistRepository(db)
+	ctx := context.Background()
+
+	baseID := uuidv7.MustBytes()
+	checklistID := uuidv7.MustBytes()
+	now := time.Now().UTC()
+	asBlob := func(b []byte) string { return fmt.Sprintf("X'%x'", b) }
+	_, hemsCategoryID := airRescuerChecklistCategoryIDs()
+
+	if err := db.Exec(
+		fmt.Sprintf(`INSERT INTO bases(id, base_category_id, base, base_abbreviation, sortkey, checklist, is_active) VALUES(%s, %s, ?, ?, ?, 1, ?)`, asBlob(baseID), asBlob(hemsCategoryID)),
+		"Gallus 1 - Zurs Lech", "G1", 1, 1,
+	).Error; err != nil {
+		t.Fatalf("insert bases: %v", err)
+	}
+	if err := db.Exec(
+		fmt.Sprintf(`INSERT INTO air_rescuer_checklists(id, hems_base_id, scope_code, title, position, created_at, updated_at, deleted_at) VALUES (%s, %s, ?, ?, ?, ?, ?, NULL)`,
+			asBlob(checklistID), asBlob(baseID)),
+		airrescuechecklist.AirRescuerChecklistScopeTA, "Daily Checks", 1, now, now,
+	).Error; err != nil {
+		t.Fatalf("insert checklist: %v", err)
+	}
+
+	// Seed deliberately out of display order. Duplicate position=2 is allowed.
+	items := []struct {
+		id       []byte
+		name     string
+		position int
+	}{
+		{id: uuidv7.MustBytes(), name: "Radio", position: 2},
+		{id: uuidv7.MustBytes(), name: "Battery", position: 2},
+		{id: uuidv7.MustBytes(), name: "Oxygen", position: 1},
+	}
+	for i := range items {
+		if err := db.Exec(
+			fmt.Sprintf(`INSERT INTO air_rescuer_checklist_items(id, checklist_id, name, position, created_at, updated_at, deleted_at) VALUES (%s, %s, ?, ?, ?, ?, NULL)`,
+				asBlob(items[i].id), asBlob(checklistID)),
+			items[i].name, items[i].position, now, now,
+		).Error; err != nil {
+			t.Fatalf("insert item[%d]: %v", i, err)
+		}
+	}
+
+	got, err := repo.ListChecklistItemsByChecklistIDs(ctx, [][]byte{checklistID})
+	if err != nil {
+		t.Fatalf("ListChecklistItemsByChecklistIDs: %v", err)
+	}
+	if len(got) != 3 {
+		t.Fatalf("expected 3 rows, got %d", len(got))
+	}
+
+	wantNames := []string{"Oxygen", "Battery", "Radio"}
+	wantPos := []int{1, 2, 2}
+	for i := range got {
+		if got[i].Name != wantNames[i] || got[i].Position != wantPos[i] {
+			t.Fatalf("unexpected row[%d]: got name=%q pos=%d, want name=%q pos=%d", i, got[i].Name, got[i].Position, wantNames[i], wantPos[i])
+		}
+	}
+}
+
+func TestAirRescuerChecklistRepositoryInTxCommitAndRollback(t *testing.T) {
+	db := openAirRescuerChecklistRepoTestDB(t)
+	repo := NewAirRescuerChecklistRepository(db)
+	ctx := context.Background()
+
+	baseID := uuidv7.MustBytes()
+	mustInsertHEMSBase(t, db, baseID, "Gallus 1 - Zurs Lech", "G1", 1, true)
+
+	checklistID := uuidv7.MustBytes()
+	if err := repo.InTx(ctx, func(txRepo airrescuechecklist.TxRepository) error {
+		return txRepo.CreateChecklist(ctx, &airrescuechecklist.AirRescuerChecklist{
+			ID:         append([]byte(nil), checklistID...),
+			HEMSBaseID: append([]byte(nil), baseID...),
+			ScopeCode:  airrescuechecklist.AirRescuerChecklistScopeTA,
+			Title:      "Daily Tasks",
+			Position:   1,
+		})
+	}); err != nil {
+		t.Fatalf("InTx commit: %v", err)
+	}
+
+	if _, err := repo.LockChecklistByID(ctx, checklistID); err != nil {
+		t.Fatalf("expected committed checklist to exist: %v", err)
+	}
+
+	rollbackID := uuidv7.MustBytes()
+	rollbackErr := errors.New("rollback me")
+	err := repo.InTx(ctx, func(txRepo airrescuechecklist.TxRepository) error {
+		if err := txRepo.CreateChecklist(ctx, &airrescuechecklist.AirRescuerChecklist{
+			ID:         append([]byte(nil), rollbackID...),
+			HEMSBaseID: append([]byte(nil), baseID...),
+			ScopeCode:  airrescuechecklist.AirRescuerChecklistScopeMO,
+			Title:      "Monday Tasks",
+			Position:   1,
+		}); err != nil {
+			return err
+		}
+		return rollbackErr
+	})
+	if !errors.Is(err, rollbackErr) {
+		t.Fatalf("expected rollback error, got %v", err)
+	}
+
+	if _, err := repo.LockChecklistByID(ctx, rollbackID); !errors.Is(err, gorm.ErrRecordNotFound) {
+		t.Fatalf("expected rolled back checklist missing, got %v", err)
+	}
+}
+
+func TestAirRescuerChecklistRepositoryChecklistCRUD(t *testing.T) {
+	db := openAirRescuerChecklistRepoTestDB(t)
+	repo := NewAirRescuerChecklistRepository(db)
+	ctx := context.Background()
+	now := time.Now().UTC()
+
+	baseID := uuidv7.MustBytes()
+	mustInsertHEMSBase(t, db, baseID, "Gallus 1 - Zurs Lech", "G1", 1, true)
+
+	checklistID := uuidv7.MustBytes()
+	if err := repo.CreateChecklist(ctx, &airrescuechecklist.AirRescuerChecklist{
+		ID:         append([]byte(nil), checklistID...),
+		HEMSBaseID: append([]byte(nil), baseID...),
+		ScopeCode:  airrescuechecklist.AirRescuerChecklistScopeTA,
+		Title:      "Original",
+		Position:   2,
+		CreatedAt:  now,
+		UpdatedAt:  now,
+	}); err != nil {
+		t.Fatalf("CreateChecklist: %v", err)
+	}
+
+	locked, err := repo.LockChecklistByID(ctx, checklistID)
+	if err != nil {
+		t.Fatalf("LockChecklistByID: %v", err)
+	}
+	if locked.Title != "Original" {
+		t.Fatalf("unexpected title after lock: %s", locked.Title)
+	}
+
+	updatedBy := uuidv7.MustBytes()
+	if err := repo.UpdateChecklist(ctx, &airrescuechecklist.AirRescuerChecklist{
+		ID:        append([]byte(nil), checklistID...),
+		ScopeCode: airrescuechecklist.AirRescuerChecklistScopeMO,
+		Title:     "Updated",
+		Position:  1,
+		UpdatedBy: updatedBy,
+	}); err != nil {
+		t.Fatalf("UpdateChecklist: %v", err)
+	}
+
+	afterUpdate, err := repo.GetChecklistByID(ctx, checklistID)
+	if err != nil {
+		t.Fatalf("GetChecklistByID after update: %v", err)
+	}
+	if afterUpdate == nil || afterUpdate.ScopeCode != airrescuechecklist.AirRescuerChecklistScopeMO || afterUpdate.Title != "Updated" || afterUpdate.Position != 1 {
+		t.Fatalf("unexpected checklist after update: %+v", afterUpdate)
+	}
+
+	notFoundID := uuidv7.MustBytes()
+	if err := repo.UpdateChecklist(ctx, &airrescuechecklist.AirRescuerChecklist{ID: notFoundID}); !errors.Is(err, gorm.ErrRecordNotFound) {
+		t.Fatalf("expected not found on update, got %v", err)
+	}
+
+	deletedBy := uuidv7.MustBytes()
+	if err := repo.SoftDeleteChecklist(ctx, checklistID, deletedBy); err != nil {
+		t.Fatalf("SoftDeleteChecklist: %v", err)
+	}
+	if err := repo.SoftDeleteChecklist(ctx, checklistID, deletedBy); !errors.Is(err, gorm.ErrRecordNotFound) {
+		t.Fatalf("expected not found on double delete, got %v", err)
+	}
+	if _, err := repo.LockChecklistByID(ctx, checklistID); !errors.Is(err, gorm.ErrRecordNotFound) {
+		t.Fatalf("expected deleted checklist cannot be locked, got %v", err)
+	}
+}
+
+func TestAirRescuerChecklistRepositoryChecklistItemCRUD(t *testing.T) {
+	db := openAirRescuerChecklistRepoTestDB(t)
+	repo := NewAirRescuerChecklistRepository(db)
+	ctx := context.Background()
+	now := time.Now().UTC()
+
+	baseID := uuidv7.MustBytes()
+	checklistID := uuidv7.MustBytes()
+	mustInsertHEMSBase(t, db, baseID, "Gallus 1 - Zurs Lech", "G1", 1, true)
+	mustInsertChecklist(t, db, checklistID, baseID, airrescuechecklist.AirRescuerChecklistScopeTA, "Daily", 1, now)
+
+	itemID := uuidv7.MustBytes()
+	if err := repo.CreateChecklistItem(ctx, &airrescuechecklist.AirRescuerChecklistItem{
+		ID:          append([]byte(nil), itemID...),
+		ChecklistID: append([]byte(nil), checklistID...),
+		Name:        "Radio",
+		Position:    2,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	}); err != nil {
+		t.Fatalf("CreateChecklistItem: %v", err)
+	}
+
+	if err := repo.CreateChecklistItems(ctx, nil); err != nil {
+		t.Fatalf("CreateChecklistItems empty: %v", err)
+	}
+
+	secondID := uuidv7.MustBytes()
+	thirdID := uuidv7.MustBytes()
+	if err := repo.CreateChecklistItems(ctx, []airrescuechecklist.AirRescuerChecklistItem{
+		{ID: append([]byte(nil), secondID...), ChecklistID: append([]byte(nil), checklistID...), Name: "Battery", Position: 1, CreatedAt: now, UpdatedAt: now},
+		{ID: append([]byte(nil), thirdID...), ChecklistID: append([]byte(nil), checklistID...), Name: "Oxygen", Position: 3, CreatedAt: now, UpdatedAt: now},
+	}); err != nil {
+		t.Fatalf("CreateChecklistItems: %v", err)
+	}
+
+	locked, err := repo.LockChecklistItemByID(ctx, itemID)
+	if err != nil {
+		t.Fatalf("LockChecklistItemByID: %v", err)
+	}
+	if locked.Name != "Radio" {
+		t.Fatalf("unexpected locked item: %+v", locked)
+	}
+
+	if err := repo.UpdateChecklistItem(ctx, &airrescuechecklist.AirRescuerChecklistItem{
+		ID:       append([]byte(nil), itemID...),
+		Name:     "Radio Updated",
+		Position: 5,
+	}); err != nil {
+		t.Fatalf("UpdateChecklistItem: %v", err)
+	}
+	gotItem, err := repo.GetChecklistItemByID(ctx, itemID)
+	if err != nil {
+		t.Fatalf("GetChecklistItemByID after update: %v", err)
+	}
+	if gotItem == nil || gotItem.Name != "Radio Updated" || gotItem.Position != 5 {
+		t.Fatalf("unexpected item after update: %+v", gotItem)
+	}
+
+	notFoundID := uuidv7.MustBytes()
+	if err := repo.UpdateChecklistItem(ctx, &airrescuechecklist.AirRescuerChecklistItem{ID: notFoundID}); !errors.Is(err, gorm.ErrRecordNotFound) {
+		t.Fatalf("expected not found on update item, got %v", err)
+	}
+
+	deletedBy := uuidv7.MustBytes()
+	if err := repo.SoftDeleteChecklistItem(ctx, itemID, deletedBy); err != nil {
+		t.Fatalf("SoftDeleteChecklistItem: %v", err)
+	}
+	if err := repo.SoftDeleteChecklistItem(ctx, itemID, deletedBy); !errors.Is(err, gorm.ErrRecordNotFound) {
+		t.Fatalf("expected not found on double item delete, got %v", err)
+	}
+	if _, err := repo.LockChecklistItemByID(ctx, itemID); !errors.Is(err, gorm.ErrRecordNotFound) {
+		t.Fatalf("expected deleted item cannot be locked, got %v", err)
+	}
+
+	if err := repo.SoftDeleteItemsByChecklistID(ctx, checklistID, deletedBy); err != nil {
+		t.Fatalf("SoftDeleteItemsByChecklistID: %v", err)
+	}
+	remaining, err := repo.ListChecklistItemsByChecklistIDs(ctx, [][]byte{checklistID})
+	if err != nil {
+		t.Fatalf("ListChecklistItemsByChecklistIDs after soft delete all: %v", err)
+	}
+	if len(remaining) != 0 {
+		t.Fatalf("expected no active items after bulk soft delete, got %d", len(remaining))
+	}
+}
+
+func TestAirRescuerChecklistRepositoryGetAndListFilters(t *testing.T) {
+	db := openAirRescuerChecklistRepoTestDB(t)
+	repo := NewAirRescuerChecklistRepository(db)
+	ctx := context.Background()
+	now := time.Now().UTC()
+
+	baseA := uuidv7.MustBytes()
+	baseB := uuidv7.MustBytes()
+	baseRegular := uuidv7.MustBytes()
+	baseInactive := uuidv7.MustBytes()
+	mustInsertHEMSBase(t, db, baseA, "Gallus 1 - Zurs Lech", "G1", 2, true)
+	mustInsertHEMSBase(t, db, baseB, "Gallus 2 - Innsbruck", "G2", 1, true)
+	mustInsertRegularBase(t, db, baseRegular, "Regular Base", "RB", 4, true, true)
+	mustInsertHEMSBase(t, db, baseInactive, "Inactive Base", "IN", 3, false)
+
+	checklistA1 := uuidv7.MustBytes()
+	checklistA2 := uuidv7.MustBytes()
+	checklistB := uuidv7.MustBytes()
+	checklistRegular := uuidv7.MustBytes()
+	mustInsertChecklist(t, db, checklistA1, baseA, airrescuechecklist.AirRescuerChecklistScopeTA, "Alpha", 1, now)
+	mustInsertChecklist(t, db, checklistA2, baseA, airrescuechecklist.AirRescuerChecklistScopeTA, "Bravo", 2, now)
+	mustInsertChecklist(t, db, checklistB, baseB, airrescuechecklist.AirRescuerChecklistScopeMO, "Monday", 1, now)
+	mustInsertChecklist(t, db, checklistRegular, baseRegular, airrescuechecklist.AirRescuerChecklistScopeTA, "Regular Daily", 1, now)
+
+	itemA := uuidv7.MustBytes()
+	itemB := uuidv7.MustBytes()
+	mustInsertChecklistItem(t, db, itemA, checklistA1, "Battery", 1, now)
+	mustInsertChecklistItem(t, db, itemB, checklistA1, "Radio", 2, now)
+
+	got, err := repo.GetChecklistByID(ctx, checklistA1)
+	if err != nil {
+		t.Fatalf("GetChecklistByID: %v", err)
+	}
+	if got == nil || got.BaseName != "Gallus 1 - Zurs Lech" {
+		t.Fatalf("unexpected checklist header view: %+v", got)
+	}
+	missingChecklist, err := repo.GetChecklistByID(ctx, uuidv7.MustBytes())
+	if err != nil {
+		t.Fatalf("GetChecklistByID missing: %v", err)
+	}
+	if missingChecklist != nil {
+		t.Fatalf("expected nil for missing checklist, got %+v", missingChecklist)
+	}
+
+	gotItem, err := repo.GetChecklistItemByID(ctx, itemA)
+	if err != nil {
+		t.Fatalf("GetChecklistItemByID: %v", err)
+	}
+	if gotItem == nil || gotItem.Name != "Battery" {
+		t.Fatalf("unexpected checklist item view: %+v", gotItem)
+	}
+	missingItem, err := repo.GetChecklistItemByID(ctx, uuidv7.MustBytes())
+	if err != nil {
+		t.Fatalf("GetChecklistItemByID missing: %v", err)
+	}
+	if missingItem != nil {
+		t.Fatalf("expected nil for missing item, got %+v", missingItem)
+	}
+
+	headersByScope, err := repo.ListChecklistHeaders(ctx, airrescuechecklist.ChecklistHeaderFilter{
+		HEMSBaseID:       append([]byte(nil), baseA...),
+		ScopeCode:        strings.ToLower(airrescuechecklist.AirRescuerChecklistScopeTA),
+		BaseName:         "zurs",
+		BaseAbbreviation: "g1",
+	})
+	if err != nil {
+		t.Fatalf("ListChecklistHeaders by scope/base filters: %v", err)
+	}
+	if len(headersByScope) != 2 {
+		t.Fatalf("expected 2 TA headers for baseA, got %d", len(headersByScope))
+	}
+
+	headersRegular, err := repo.ListChecklistHeaders(ctx, airrescuechecklist.ChecklistHeaderFilter{
+		CategoryType: basedomain.CategoryKeyRegular,
+		ScopeCode:    airrescuechecklist.AirRescuerChecklistScopeTA,
+	})
+	if err != nil {
+		t.Fatalf("ListChecklistHeaders regular category: %v", err)
+	}
+	if len(headersRegular) != 1 || headersRegular[0].Title != "Regular Daily" {
+		t.Fatalf("expected regular checklist header only, got %+v", headersRegular)
+	}
+
+	orderedBases, err := repo.ListHEMSBases(ctx, airrescuechecklist.HEMSBaseFilter{})
+	if err != nil {
+		t.Fatalf("ListHEMSBases all: %v", err)
+	}
+	if len(orderedBases) != 3 {
+		t.Fatalf("expected only active bases, got %d", len(orderedBases))
+	}
+	if orderedBases[0].BaseName != "Gallus 2 - Innsbruck" || orderedBases[1].BaseName != "Gallus 1 - Zurs Lech" || orderedBases[2].BaseName != "Regular Base" {
+		t.Fatalf("unexpected base ordering: %+v", orderedBases)
+	}
+
+	hemsOnly, err := repo.ListHEMSBases(ctx, airrescuechecklist.HEMSBaseFilter{CategoryType: basedomain.CategoryKeyHEMS})
+	if err != nil {
+		t.Fatalf("ListHEMSBases hems only: %v", err)
+	}
+	if len(hemsOnly) != 2 {
+		t.Fatalf("expected 2 hems bases, got %d", len(hemsOnly))
+	}
+
+	regularOnly, err := repo.ListHEMSBases(ctx, airrescuechecklist.HEMSBaseFilter{CategoryType: basedomain.CategoryKeyRegular})
+	if err != nil {
+		t.Fatalf("ListHEMSBases regular only: %v", err)
+	}
+	if len(regularOnly) != 1 || regularOnly[0].BaseName != "Regular Base" {
+		t.Fatalf("expected 1 regular base, got %+v", regularOnly)
+	}
+
+	filteredBase, err := repo.ListHEMSBases(ctx, airrescuechecklist.HEMSBaseFilter{
+		HEMSBaseID:       append([]byte(nil), baseA...),
+		BaseName:         "zurs",
+		BaseAbbreviation: "g1",
+	})
+	if err != nil {
+		t.Fatalf("ListHEMSBases filtered: %v", err)
+	}
+	if len(filteredBase) != 1 || filteredBase[0].ID == nil {
+		t.Fatalf("unexpected filtered base rows: %+v", filteredBase)
+	}
+
+	emptyItems, err := repo.ListChecklistItemsByChecklistIDs(ctx, nil)
+	if err != nil {
+		t.Fatalf("ListChecklistItemsByChecklistIDs empty ids: %v", err)
+	}
+	if len(emptyItems) != 0 {
+		t.Fatalf("expected empty items for empty checklist ids, got %d", len(emptyItems))
+	}
+}
+
+func TestAirRescuerChecklistRepositoryDatabaseErrorBranches(t *testing.T) {
+	ctx := context.Background()
+	id := uuidv7.MustBytes()
+
+	t.Run("update checklist db error", func(t *testing.T) {
+		db := openAirRescuerChecklistRepoTestDB(t)
+		repo := NewAirRescuerChecklistRepository(db)
+		if err := db.Exec(`DROP TABLE air_rescuer_checklists`).Error; err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+		if err := repo.UpdateChecklist(ctx, &airrescuechecklist.AirRescuerChecklist{ID: id, Title: "x"}); err == nil {
+			t.Fatalf("expected db error")
+		}
+		if err := repo.SoftDeleteChecklist(ctx, id, uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected db error")
+		}
+		if _, err := repo.GetChecklistByID(ctx, id); err == nil {
+			t.Fatalf("expected db error")
+		}
+		if _, err := repo.ListChecklistHeaders(ctx, airrescuechecklist.ChecklistHeaderFilter{}); err == nil {
+			t.Fatalf("expected db error")
+		}
+	})
+
+	t.Run("item db error", func(t *testing.T) {
+		db := openAirRescuerChecklistRepoTestDB(t)
+		repo := NewAirRescuerChecklistRepository(db)
+		if err := db.Exec(`DROP TABLE air_rescuer_checklist_items`).Error; err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+		if err := repo.UpdateChecklistItem(ctx, &airrescuechecklist.AirRescuerChecklistItem{ID: id, Name: "x"}); err == nil {
+			t.Fatalf("expected db error")
+		}
+		if err := repo.SoftDeleteChecklistItem(ctx, id, uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected db error")
+		}
+		if _, err := repo.GetChecklistItemByID(ctx, id); err == nil {
+			t.Fatalf("expected db error")
+		}
+		if _, err := repo.ListChecklistItemsByChecklistIDs(ctx, [][]byte{id}); err == nil {
+			t.Fatalf("expected db error")
+		}
+	})
+
+	t.Run("list hems bases db error", func(t *testing.T) {
+		db := openAirRescuerChecklistRepoTestDB(t)
+		repo := NewAirRescuerChecklistRepository(db)
+		if err := db.Exec(`DROP TABLE bases`).Error; err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+		if _, err := repo.ListHEMSBases(ctx, airrescuechecklist.HEMSBaseFilter{}); err == nil {
+			t.Fatalf("expected db error")
+		}
+	})
+}
+
+func mustInsertHEMSBase(t *testing.T, db *gorm.DB, id []byte, name, abbr string, position int, active bool) {
+	t.Helper()
+	toBlob := func(b []byte) string { return fmt.Sprintf("X'%x'", b) }
+	_, hemsCategoryID := airRescuerChecklistCategoryIDs()
+	if err := db.Exec(
+		fmt.Sprintf(`INSERT INTO bases(id, base_category_id, base, base_abbreviation, sortkey, checklist, is_active) VALUES (%s, %s, ?, ?, ?, 1, ?)`, toBlob(id), toBlob(hemsCategoryID)),
+		name, abbr, position, active,
+	).Error; err != nil {
+		t.Fatalf("insert hems base: %v", err)
+	}
+}
+
+func mustInsertRegularBase(t *testing.T, db *gorm.DB, id []byte, name, abbr string, position int, active bool, checklist bool) {
+	t.Helper()
+	toBlob := func(b []byte) string { return fmt.Sprintf("X'%x'", b) }
+	regularCategoryID, _ := airRescuerChecklistCategoryIDs()
+	checklistVal := 0
+	if checklist {
+		checklistVal = 1
+	}
+	activeVal := 0
+	if active {
+		activeVal = 1
+	}
+	if err := db.Exec(
+		fmt.Sprintf(`INSERT INTO bases(id, base_category_id, base, base_abbreviation, sortkey, checklist, is_active) VALUES (%s, %s, ?, ?, ?, ?, ?)`, toBlob(id), toBlob(regularCategoryID)),
+		name, abbr, position, checklistVal, activeVal,
+	).Error; err != nil {
+		t.Fatalf("insert regular base: %v", err)
+	}
+}
+
+func mustInsertChecklist(t *testing.T, db *gorm.DB, id, baseID []byte, scopeCode, title string, position int, now time.Time) {
+	t.Helper()
+	toBlob := func(b []byte) string { return fmt.Sprintf("X'%x'", b) }
+	if err := db.Exec(
+		fmt.Sprintf(`INSERT INTO air_rescuer_checklists(id, hems_base_id, scope_code, title, position, created_at, updated_at, deleted_at) VALUES (%s, %s, ?, ?, ?, ?, ?, NULL)`, toBlob(id), toBlob(baseID)),
+		scopeCode, title, position, now, now,
+	).Error; err != nil {
+		t.Fatalf("insert checklist: %v", err)
+	}
+}
+
+func mustInsertChecklistItem(t *testing.T, db *gorm.DB, id, checklistID []byte, name string, position int, now time.Time) {
+	t.Helper()
+	toBlob := func(b []byte) string { return fmt.Sprintf("X'%x'", b) }
+	if err := db.Exec(
+		fmt.Sprintf(`INSERT INTO air_rescuer_checklist_items(id, checklist_id, name, position, created_at, updated_at, deleted_at) VALUES (%s, %s, ?, ?, ?, ?, NULL)`, toBlob(id), toBlob(checklistID)),
+		name, position, now, now,
+	).Error; err != nil {
+		t.Fatalf("insert checklist item: %v", err)
+	}
+}
diff --git a/internal/repository/mysql/audit_repo.go b/internal/repository/mysql/audit_repo.go
new file mode 100644
index 0000000..0fec165
--- /dev/null
+++ b/internal/repository/mysql/audit_repo.go
@@ -0,0 +1,166 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/audit"
+)
+
+type AuditRepository struct {
+	db *gorm.DB
+}
+
+func NewAuditRepository(db *gorm.DB) *AuditRepository {
+	return &AuditRepository{db: db}
+}
+
+func (r *AuditRepository) Create(ctx context.Context, entry *audit.AuditLog) error {
+	return r.db.WithContext(ctx).Create(entry).Error
+}
+
+func (r *AuditRepository) List(ctx context.Context, filter string, methods []string, modules []string, actions []string, sort string, limit, offset int) ([]audit.AuditLog, int64, error) {
+	q := r.db.WithContext(ctx).Model(&audit.AuditLog{})
+	filter = strings.TrimSpace(filter)
+	if filter != "" {
+		like := "%" + strings.ToLower(filter) + "%"
+		q = q.Where(
+			`LOWER(request_id) LIKE ? OR LOWER(layer) LIKE ? OR LOWER(action) LIKE ? OR LOWER(method) LIKE ? OR LOWER(path) LIKE ? OR LOWER(message) LIKE ?`,
+			like, like, like, like, like, like,
+		)
+	}
+	if len(methods) > 0 {
+		q = q.Where("UPPER(method) IN ?", methods)
+	}
+	if len(modules) > 0 {
+		pathPrefixes := modulePathPrefixes(modules)
+		if len(pathPrefixes) == 0 {
+			q = q.Where("LOWER(module) IN ?", modules)
+		} else {
+			pathConds := make([]string, 0, len(pathPrefixes))
+			pathArgs := make([]any, 0, len(pathPrefixes))
+			for _, prefix := range pathPrefixes {
+				pathConds = append(pathConds, "LOWER(path) LIKE ?")
+				pathArgs = append(pathArgs, strings.ToLower(prefix)+"%")
+			}
+			cond := fmt.Sprintf("(LOWER(module) IN ? OR ((module IS NULL OR module = '') AND (%s)))", strings.Join(pathConds, " OR "))
+			args := make([]any, 0, 2+len(pathArgs))
+			args = append(args, modules)
+			args = append(args, pathArgs...)
+			q = q.Where(cond, args...)
+		}
+	}
+	if len(actions) > 0 {
+		q = q.Where("LOWER(action) IN ?", actions)
+	}
+
+	var total int64
+	if err := q.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	if strings.TrimSpace(sort) == "" {
+		sort = "created_at DESC"
+	}
+	if limit < 0 {
+		limit = 0
+	}
+	if limit > 200 {
+		limit = 200
+	}
+	if offset < 0 {
+		offset = 0
+	}
+
+	var out []audit.AuditLog
+	query := q.Order(sort)
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&out).Error; err != nil {
+		return nil, 0, err
+	}
+	return out, total, nil
+}
+
+func modulePathPrefixes(modules []string) []string {
+	seen := map[string]struct{}{}
+	out := make([]string, 0, len(modules))
+	for _, module := range modules {
+		var prefix string
+		switch strings.ToLower(strings.TrimSpace(module)) {
+		case "air_rescuer_checklist":
+			prefix = "/api/v1/air-rescuer-checklist/"
+		case "audit_log":
+			prefix = "/api/v1/audit-logs/"
+		case "auth":
+			prefix = "/api/v1/auth/"
+		case "base":
+			prefix = "/api/v1/bases/"
+		case "branding":
+			prefix = "/api/v1/branding/"
+		case "contact":
+			prefix = "/api/v1/contacts/"
+		case "duty_roster":
+			prefix = "/api/v1/duty-roster/"
+		case "dul":
+			prefix = "/api/v1/dul/"
+		case "facility":
+			prefix = "/api/v1/facilities/"
+		case "federal_state":
+			prefix = "/api/v1/federal-state/"
+		case "file_manager":
+			prefix = "/api/v1/file-manager/"
+		case "flight_data":
+			prefix = "/api/v1/flight-data/"
+		case "flight":
+			prefix = "/api/v1/flights/"
+		case "forces_present":
+			prefix = "/api/v1/forces-present/"
+		case "health_insurance_company":
+			prefix = "/api/v1/health-insurance-companies/"
+		case "helicopter_file":
+			prefix = "/api/v1/helicopter-files/"
+		case "helicopter":
+			prefix = "/api/v1/helicopters/"
+		case "hospital":
+			prefix = "/api/v1/hospital/"
+		case "icao":
+			prefix = "/api/v1/icao/"
+		case "insurance_patient_data":
+			prefix = "/api/v1/insurance-patient-data/"
+		case "land":
+			prefix = "/api/v1/land/"
+		case "master_setting":
+			prefix = "/api/v1/master-settings/"
+		case "medicine":
+			prefix = "/api/v1/medicine/"
+		case "mission":
+			prefix = "/api/v1/mission/"
+		case "opc":
+			prefix = "/api/v1/opc/"
+		case "patient_data":
+			prefix = "/api/v1/patient-data/"
+		case "reserve_ac":
+			prefix = "/api/v1/reserve-acs/"
+		case "role":
+			prefix = "/api/v1/roles/"
+		case "user":
+			prefix = "/api/v1/users/"
+		case "vocation":
+			prefix = "/api/v1/vocation/"
+		}
+		if prefix == "" {
+			continue
+		}
+		if _, ok := seen[prefix]; ok {
+			continue
+		}
+		seen[prefix] = struct{}{}
+		out = append(out, prefix)
+	}
+	return out
+}
diff --git a/internal/repository/mysql/auth_repo.go b/internal/repository/mysql/auth_repo.go
new file mode 100644
index 0000000..a1029d3
--- /dev/null
+++ b/internal/repository/mysql/auth_repo.go
@@ -0,0 +1,595 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"wucher/internal/domain/auth"
+)
+
+type AuthRepository struct {
+	db *gorm.DB
+}
+
+func NewAuthRepository(db *gorm.DB) *AuthRepository {
+	return &AuthRepository{db: db}
+}
+
+// Users
+
+func (r *AuthRepository) CreateUser(ctx context.Context, user *auth.User) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+			user.CreatedBy = actor
+			user.UpdatedBy = actor
+		}
+		if err := tx.Create(user).Error; err != nil {
+			return err
+		}
+		return replaceUserRolesTx(ctx, tx, user.ID, user.RoleID, user.RoleIDs)
+	})
+}
+
+func (r *AuthRepository) GetUserByID(ctx context.Context, id []byte) (*auth.User, error) {
+	var user auth.User
+	err := r.db.WithContext(ctx).
+		Preload("ProfileAttachment").
+		Preload("ProfileAttachment.File").
+		First(&user, "id = ?", id).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	if err := attachAuthUserRoles(ctx, r.db, &user); err != nil {
+		return nil, err
+	}
+	return &user, nil
+}
+
+func (r *AuthRepository) GetUserByEmail(ctx context.Context, email string) (*auth.User, error) {
+	var user auth.User
+	err := r.db.WithContext(ctx).
+		Preload("ProfileAttachment").
+		Preload("ProfileAttachment.File").
+		Where("email = ?", email).
+		First(&user).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	if err := attachAuthUserRoles(ctx, r.db, &user); err != nil {
+		return nil, err
+	}
+	return &user, nil
+}
+
+func (r *AuthRepository) GetUserBySSOEmail(ctx context.Context, ssoEmail string) (*auth.User, error) {
+	var user auth.User
+	err := r.db.WithContext(ctx).
+		Preload("ProfileAttachment").
+		Preload("ProfileAttachment.File").
+		Where("sso_email = ?", ssoEmail).
+		First(&user).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	if err := attachAuthUserRoles(ctx, r.db, &user); err != nil {
+		return nil, err
+	}
+	return &user, nil
+}
+
+func (r *AuthRepository) GetUserByUsername(ctx context.Context, username string) (*auth.User, error) {
+	var user auth.User
+	err := r.db.WithContext(ctx).
+		Preload("ProfileAttachment").
+		Preload("ProfileAttachment.File").
+		Where("username = ?", username).
+		First(&user).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	if err := attachAuthUserRoles(ctx, r.db, &user); err != nil {
+		return nil, err
+	}
+	return &user, nil
+}
+
+func (r *AuthRepository) UpdateUserTimezone(ctx context.Context, id []byte, timezone string) error {
+	return r.db.WithContext(ctx).
+		Model(&auth.User{}).
+		Where("id = ?", id).
+		Updates(map[string]any{
+			"timezone":   timezone,
+			"updated_at": time.Now().UTC(),
+		}).Error
+}
+
+func (r *AuthRepository) SetUserPassword(ctx context.Context, id []byte, passwordHash, salt []byte) error {
+	return r.db.WithContext(ctx).
+		Model(&auth.User{}).
+		Where("id = ?", id).
+		Updates(map[string]any{
+			"password_hash": passwordHash,
+			"salt_value":    salt,
+			"updated_at":    time.Now().UTC(),
+		}).Error
+}
+
+func (r *AuthRepository) SetUserSecurityPIN(ctx context.Context, id []byte, pinHash []byte, setAt time.Time) error {
+	return r.db.WithContext(ctx).
+		Model(&auth.User{}).
+		Where("id = ?", id).
+		Updates(map[string]any{
+			"security_pin_hash":   pinHash,
+			"security_pin_set_at": setAt,
+			"updated_at":          setAt,
+		}).Error
+}
+
+func (r *AuthRepository) MarkEmailVerified(ctx context.Context, id []byte) error {
+	now := time.Now().UTC()
+	return r.db.WithContext(ctx).
+		Model(&auth.User{}).
+		Where("id = ?", id).
+		Update("email_verified_at", &now).Error
+}
+
+func (r *AuthRepository) CreatePasswordResetToken(ctx context.Context, token *auth.PasswordResetToken) error {
+	return r.db.WithContext(ctx).Create(token).Error
+}
+
+func (r *AuthRepository) InvalidateActivePasswordResetTokensByUserID(ctx context.Context, userID []byte, usedAt time.Time) error {
+	return r.db.WithContext(ctx).
+		Model(&auth.PasswordResetToken{}).
+		Where("user_id = ? AND used_at IS NULL AND expires_at > ?", userID, usedAt).
+		Updates(map[string]any{
+			"used_at":    usedAt,
+			"updated_at": usedAt,
+		}).Error
+}
+
+func (r *AuthRepository) ConsumePasswordResetTokenAndSetPassword(
+	ctx context.Context,
+	tokenHash, passwordHash, salt []byte,
+	usedAt time.Time,
+) ([]byte, bool, error) {
+	var token auth.PasswordResetToken
+	consumed := false
+
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		err := tx.
+			Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("token_hash = ? AND used_at IS NULL AND expires_at > ?", tokenHash, usedAt).
+			First(&token).Error
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil
+		}
+		if err != nil {
+			return err
+		}
+		consumed = true
+
+		res := tx.Model(&auth.User{}).
+			Where("id = ?", token.UserID).
+			Updates(map[string]any{
+				"password_hash": passwordHash,
+				"salt_value":    salt,
+				"updated_at":    usedAt,
+			})
+		if res.Error != nil {
+			return res.Error
+		}
+		if res.RowsAffected == 0 {
+			return gorm.ErrRecordNotFound
+		}
+
+		if err := tx.Model(&auth.PasswordResetToken{}).
+			Where("id = ?", token.ID).
+			Updates(map[string]any{
+				"used_at":    usedAt,
+				"updated_at": usedAt,
+			}).Error; err != nil {
+			return err
+		}
+
+		return tx.Model(&auth.PasswordResetToken{}).
+			Where("user_id = ? AND id <> ? AND used_at IS NULL AND expires_at > ?", token.UserID, token.ID, usedAt).
+			Updates(map[string]any{
+				"used_at":    usedAt,
+				"updated_at": usedAt,
+			}).Error
+	})
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, false, nil
+		}
+		return nil, false, err
+	}
+	if !consumed {
+		return nil, false, nil
+	}
+	return token.UserID, true, nil
+}
+
+func (r *AuthRepository) CreateSecurityPINResetToken(ctx context.Context, token *auth.SecurityPINResetToken) error {
+	return r.db.WithContext(ctx).Create(token).Error
+}
+
+func (r *AuthRepository) InvalidateActiveSecurityPINResetTokensByUserID(ctx context.Context, userID []byte, usedAt time.Time) error {
+	return r.db.WithContext(ctx).
+		Model(&auth.SecurityPINResetToken{}).
+		Where("user_id = ? AND used_at IS NULL AND expires_at > ?", userID, usedAt).
+		Updates(map[string]any{
+			"used_at":    usedAt,
+			"updated_at": usedAt,
+		}).Error
+}
+
+func (r *AuthRepository) GetActiveSecurityPINResetTokenUser(ctx context.Context, tokenHash []byte, now time.Time) (*auth.User, error) {
+	var user auth.User
+	err := r.db.WithContext(ctx).
+		Table("security_pin_reset_tokens AS token").
+		Select("users.*").
+		Joins("JOIN users ON users.id = token.user_id").
+		Where("token.token_hash = ? AND token.used_at IS NULL AND token.expires_at > ?", tokenHash, now).
+		First(&user).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &user, err
+}
+
+func (r *AuthRepository) ConsumeSecurityPINResetTokenAndSetPIN(
+	ctx context.Context,
+	tokenHash, pinHash []byte,
+	usedAt time.Time,
+) ([]byte, bool, error) {
+	var token auth.SecurityPINResetToken
+	consumed := false
+
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		err := tx.
+			Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("token_hash = ? AND used_at IS NULL AND expires_at > ?", tokenHash, usedAt).
+			First(&token).Error
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil
+		}
+		if err != nil {
+			return err
+		}
+		consumed = true
+
+		res := tx.Model(&auth.User{}).
+			Where("id = ?", token.UserID).
+			Updates(map[string]any{
+				"security_pin_hash":   pinHash,
+				"security_pin_set_at": usedAt,
+				"updated_at":          usedAt,
+			})
+		if res.Error != nil {
+			return res.Error
+		}
+		if res.RowsAffected == 0 {
+			return gorm.ErrRecordNotFound
+		}
+
+		if err := tx.Model(&auth.SecurityPINResetToken{}).
+			Where("id = ?", token.ID).
+			Updates(map[string]any{
+				"used_at":    usedAt,
+				"updated_at": usedAt,
+			}).Error; err != nil {
+			return err
+		}
+
+		return tx.Model(&auth.SecurityPINResetToken{}).
+			Where("user_id = ? AND id <> ? AND used_at IS NULL AND expires_at > ?", token.UserID, token.ID, usedAt).
+			Updates(map[string]any{
+				"used_at":    usedAt,
+				"updated_at": usedAt,
+			}).Error
+	})
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, false, nil
+		}
+		return nil, false, err
+	}
+	if !consumed {
+		return nil, false, nil
+	}
+	return token.UserID, true, nil
+}
+
+// Identities (SSO)
+
+func (r *AuthRepository) UpsertIdentity(ctx context.Context, identity *auth.UserIdentity) error {
+	// Ensure we keep a single row per provider+subject
+	return r.db.WithContext(ctx).
+		Clauses(clause.OnConflict{
+			Columns:   []clause.Column{{Name: "provider"}, {Name: "provider_subject"}},
+			DoUpdates: clause.AssignmentColumns([]string{"user_id", "email", "metadata", "updated_at", "updated_by"}),
+		}).
+		Create(identity).Error
+}
+
+func (r *AuthRepository) CreateIdentity(ctx context.Context, identity *auth.UserIdentity) error {
+	return r.db.WithContext(ctx).Create(identity).Error
+}
+
+func (r *AuthRepository) GetIdentityByProviderSubject(ctx context.Context, provider, subject string) (*auth.UserIdentity, error) {
+	var identity auth.UserIdentity
+	tx := r.db.WithContext(ctx).
+		Where("provider = ? AND provider_subject = ?", provider, subject).
+		Limit(1).
+		Find(&identity)
+	if tx.Error != nil {
+		return nil, tx.Error
+	}
+	if tx.RowsAffected == 0 {
+		return nil, nil
+	}
+	return &identity, nil
+}
+
+func (r *AuthRepository) GetIdentityByUserID(ctx context.Context, userID []byte) (*auth.UserIdentity, error) {
+	var identity auth.UserIdentity
+	tx := r.db.WithContext(ctx).
+		Where("user_id = ?", userID).
+		Limit(1).
+		Find(&identity)
+	if tx.Error != nil {
+		return nil, tx.Error
+	}
+	if tx.RowsAffected == 0 {
+		return nil, nil
+	}
+	return &identity, nil
+}
+
+func (r *AuthRepository) DeleteIdentityByUserIDProvider(ctx context.Context, userID []byte, provider string) (bool, error) {
+	tx := r.db.WithContext(ctx).
+		Where("user_id = ? AND provider = ?", userID, provider).
+		Delete(&auth.UserIdentity{})
+	if tx.Error != nil {
+		return false, tx.Error
+	}
+	return tx.RowsAffected > 0, nil
+}
+
+func (r *AuthRepository) UpsertMicrosoftOAuthToken(ctx context.Context, token *auth.UserMicrosoftOAuthToken) error {
+	return r.db.WithContext(ctx).
+		Clauses(clause.OnConflict{
+			Columns: []clause.Column{{Name: "user_id"}, {Name: "provider"}},
+			DoUpdates: clause.AssignmentColumns([]string{
+				"tenant_id",
+				"microsoft_object_id",
+				"microsoft_subject",
+				"refresh_token_encrypted",
+				"access_token_encrypted",
+				"id_token_encrypted",
+				"scope",
+				"token_type",
+				"access_token_expires_at",
+				"refresh_token_expires_at",
+				"refresh_token_rotated_at",
+				"updated_at",
+				"updated_by",
+			}),
+		}).
+		Create(token).Error
+}
+
+func (r *AuthRepository) GetMicrosoftOAuthTokenByUserIDProvider(ctx context.Context, userID []byte, provider string) (*auth.UserMicrosoftOAuthToken, error) {
+	var token auth.UserMicrosoftOAuthToken
+	tx := r.db.WithContext(ctx).
+		Where("user_id = ? AND provider = ?", userID, provider).
+		Limit(1).
+		Find(&token)
+	if tx.Error != nil {
+		return nil, tx.Error
+	}
+	if tx.RowsAffected == 0 {
+		return nil, nil
+	}
+	return &token, nil
+}
+
+func (r *AuthRepository) DeleteMicrosoftOAuthTokenByUserIDProvider(ctx context.Context, userID []byte, provider string) (bool, error) {
+	tx := r.db.WithContext(ctx).
+		Where("user_id = ? AND provider = ?", userID, provider).
+		Delete(&auth.UserMicrosoftOAuthToken{})
+	if tx.Error != nil {
+		return false, tx.Error
+	}
+	return tx.RowsAffected > 0, nil
+}
+
+// TOTP
+
+func (r *AuthRepository) GetUserTOTP(ctx context.Context, userID []byte) (*auth.UserTOTP, error) {
+	var totp auth.UserTOTP
+	tx := r.db.WithContext(ctx).Where("user_id = ?", userID).Limit(1).Find(&totp)
+	if tx.Error != nil {
+		return nil, tx.Error
+	}
+	if tx.RowsAffected == 0 {
+		return nil, nil
+	}
+	return &totp, nil
+}
+
+func (r *AuthRepository) UpsertUserTOTP(ctx context.Context, totp *auth.UserTOTP) error {
+	return r.db.WithContext(ctx).
+		Clauses(clause.OnConflict{
+			Columns:   []clause.Column{{Name: "user_id"}},
+			DoUpdates: clause.AssignmentColumns([]string{"secret_encrypted", "enabled", "updated_at", "updated_by"}),
+		}).
+		Create(totp).Error
+}
+
+func (r *AuthRepository) DisableUserTOTP(ctx context.Context, userID []byte) error {
+	return r.db.WithContext(ctx).
+		Model(&auth.UserTOTP{}).
+		Where("user_id = ?", userID).
+		Updates(map[string]any{
+			"enabled":    false,
+			"updated_at": time.Now().UTC(),
+		}).Error
+}
+
+func (r *AuthRepository) DeleteUserTOTPSetup(ctx context.Context, userID []byte) error {
+	return r.db.WithContext(ctx).
+		Where("user_id = ?", userID).
+		Delete(&auth.UserTOTP{}).Error
+}
+
+func (r *AuthRepository) UpdateUserTOTPLastUsed(ctx context.Context, userID []byte) error {
+	return r.db.WithContext(ctx).
+		Model(&auth.UserTOTP{}).
+		Where("user_id = ? AND enabled = 1", userID).
+		Update("last_used_at", time.Now().UTC()).Error
+}
+
+// Email login OTP
+
+func (r *AuthRepository) GetActiveUserEmailLoginOTP(ctx context.Context, userID []byte, now time.Time) (*auth.UserEmailLoginOTP, error) {
+	var row auth.UserEmailLoginOTP
+	tx := r.db.WithContext(ctx).
+		Where("user_id = ? AND used_at IS NULL AND expires_at > ?", userID, now.UTC()).
+		Order("created_at DESC").
+		Limit(1).
+		Find(&row)
+	if tx.Error != nil {
+		return nil, tx.Error
+	}
+	if tx.RowsAffected == 0 {
+		return nil, nil
+	}
+	return &row, nil
+}
+
+func (r *AuthRepository) CountUserEmailLoginOTPSince(ctx context.Context, userID []byte, since time.Time) (int64, error) {
+	var count int64
+	err := r.db.WithContext(ctx).
+		Model(&auth.UserEmailLoginOTP{}).
+		Where("user_id = ? AND created_at >= ?", userID, since.UTC()).
+		Count(&count).Error
+	return count, err
+}
+
+func (r *AuthRepository) CreateUserEmailLoginOTP(ctx context.Context, otp *auth.UserEmailLoginOTP) error {
+	return r.db.WithContext(ctx).Create(otp).Error
+}
+
+func (r *AuthRepository) InvalidateActiveUserEmailLoginOTPs(ctx context.Context, userID []byte, usedAt time.Time) error {
+	return r.db.WithContext(ctx).
+		Model(&auth.UserEmailLoginOTP{}).
+		Where("user_id = ? AND used_at IS NULL AND expires_at > ?", userID, usedAt.UTC()).
+		Updates(map[string]any{
+			"used_at":    usedAt.UTC(),
+			"updated_at": usedAt.UTC(),
+		}).Error
+}
+
+func (r *AuthRepository) ConsumeUserEmailLoginOTP(ctx context.Context, userID, otpHash []byte, now time.Time) (bool, int, error) {
+	success := false
+	attemptsLeft := 0
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var row auth.UserEmailLoginOTP
+		err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("user_id = ? AND used_at IS NULL AND expires_at > ?", userID, now.UTC()).
+			Order("created_at DESC").
+			Limit(1).
+			First(&row).Error
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil
+		}
+		if err != nil {
+			return err
+		}
+
+		if string(row.OTPHash) == string(otpHash) {
+			success = true
+			attemptsLeft = max(0, row.MaxAttempts-row.AttemptCount)
+			if err := tx.Model(&auth.UserEmailLoginOTP{}).
+				Where("id = ?", row.ID).
+				Updates(map[string]any{
+					"used_at":    now.UTC(),
+					"updated_at": now.UTC(),
+				}).Error; err != nil {
+				return err
+			}
+			return tx.Model(&auth.UserEmailLoginOTP{}).
+				Where("user_id = ? AND id <> ? AND used_at IS NULL AND expires_at > ?", userID, row.ID, now.UTC()).
+				Updates(map[string]any{
+					"used_at":    now.UTC(),
+					"updated_at": now.UTC(),
+				}).Error
+		}
+
+		nextAttempts := row.AttemptCount + 1
+		attemptsLeft = max(0, row.MaxAttempts-nextAttempts)
+		updates := map[string]any{
+			"attempt_count": nextAttempts,
+			"updated_at":    now.UTC(),
+		}
+		if nextAttempts >= row.MaxAttempts {
+			updates["used_at"] = now.UTC()
+		}
+		return tx.Model(&auth.UserEmailLoginOTP{}).
+			Where("id = ?", row.ID).
+			Updates(updates).Error
+	})
+	return success, attemptsLeft, err
+}
+
+// WebAuthn
+
+func (r *AuthRepository) ListUserWebAuthnCredentials(ctx context.Context, userID []byte) ([]auth.UserWebAuthnCredential, error) {
+	var credentials []auth.UserWebAuthnCredential
+	if err := r.db.WithContext(ctx).
+		Where("user_id = ?", userID).
+		Order("created_at ASC").
+		Find(&credentials).Error; err != nil {
+		return nil, err
+	}
+	return credentials, nil
+}
+
+func (r *AuthRepository) CreateUserWebAuthnCredential(ctx context.Context, credential *auth.UserWebAuthnCredential) error {
+	return r.db.WithContext(ctx).Create(credential).Error
+}
+
+func (r *AuthRepository) UpdateUserWebAuthnCredential(ctx context.Context, userID, credentialID, credentialJSON []byte, usedAt time.Time) error {
+	return r.db.WithContext(ctx).
+		Model(&auth.UserWebAuthnCredential{}).
+		Where("user_id = ? AND credential_id = ?", userID, credentialID).
+		Updates(map[string]any{
+			"credential_json": credentialJSON,
+			"last_used_at":    usedAt,
+			"updated_at":      usedAt,
+		}).Error
+}
+
+func (r *AuthRepository) DeleteAllUserWebAuthnCredentials(ctx context.Context, userID []byte) error {
+	return r.db.WithContext(ctx).
+		Where("user_id = ?", userID).
+		Delete(&auth.UserWebAuthnCredential{}).Error
+}
diff --git a/internal/repository/mysql/base_repo.go b/internal/repository/mysql/base_repo.go
new file mode 100644
index 0000000..49461f9
--- /dev/null
+++ b/internal/repository/mysql/base_repo.go
@@ -0,0 +1,642 @@
+package mysql
+
+import (
+	"context"
+	"database/sql/driver"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"wucher/internal/domain/base"
+	"wucher/internal/shared/pkg/sortkey"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type BaseRepository struct {
+	db *gorm.DB
+}
+
+type binaryValue struct {
+	data []byte
+}
+
+func (b binaryValue) Value() (driver.Value, error) {
+	if len(b.data) == 0 {
+		return nil, nil
+	}
+	return append([]byte(nil), b.data...), nil
+}
+
+func NewBaseRepository(db *gorm.DB) *BaseRepository {
+	return &BaseRepository{db: db}
+}
+
+func (r *BaseRepository) CreateBase(ctx context.Context, row *base.Base, categoryType string) error {
+	categoryID, err := r.categoryIDByType(ctx, categoryType)
+	if err != nil {
+		return err
+	}
+	row.BaseCategoryID = categoryID
+	if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+		row.CreatedBy = actor
+		row.UpdatedBy = actor
+	}
+	row.DefaultStartTimeType = normalizeBaseShiftTimeType(row.DefaultStartTimeType)
+	row.DefaultEndTimeType = normalizeBaseShiftTimeType(row.DefaultEndTimeType)
+	row.DefaultShiftStart = baseClockStorageValue(row.DefaultShiftStart)
+	row.DefaultShiftEnd = baseClockStorageValue(row.DefaultShiftEnd)
+	requestedIsActive := row.IsActive
+	operationalShiftTimes := row.OperationalShiftTimes
+	row.OperationalShiftTimes = nil
+	db := r.db.WithContext(ctx)
+	return db.Transaction(func(tx *gorm.DB) error {
+		if err := tx.Omit(clause.Associations).Create(row).Error; err != nil {
+			return err
+		}
+		if err := tx.Model(&base.Base{}).Where("id = ?", row.ID).UpdateColumn("is_active", requestedIsActive).Error; err != nil {
+			return err
+		}
+		if err := r.replaceBaseContactRolesTx(ctx, tx, row.ID, row.HEMSEDCContactIDs, row.MedPaxContactIDs, row.ResponsiblePilotContactIDs); err != nil {
+			return err
+		}
+		return r.replaceBaseOperationalShiftTimesTx(ctx, tx, row.ID, operationalShiftTimes)
+	})
+}
+
+func (r *BaseRepository) UpdateBase(ctx context.Context, row *base.Base, categoryType string) error {
+	categoryID, err := r.categoryIDByType(ctx, categoryType)
+	if err != nil {
+		return err
+	}
+	row.BaseCategoryID = categoryID
+	if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+		row.UpdatedBy = actor
+	}
+	row.DefaultStartTimeType = normalizeBaseShiftTimeType(row.DefaultStartTimeType)
+	row.DefaultEndTimeType = normalizeBaseShiftTimeType(row.DefaultEndTimeType)
+	row.DefaultShiftStart = baseClockStorageValue(row.DefaultShiftStart)
+	row.DefaultShiftEnd = baseClockStorageValue(row.DefaultShiftEnd)
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// Use an explicit UPDATE statement so the base shift columns are stored
+		// in the same datetime shape that exists in the local schema while still
+		// accepting clock-only inputs from the API layer.
+		if err := tx.Exec(
+			fmt.Sprintf(`UPDATE bases
+			 SET base = ?,
+			     base_category_id = ?,
+			     foto_attachment_id = ?,
+			     base_abbreviation = ?,
+			     address = ?,
+			     latitude = ?,
+			     longitude = ?,
+			     landline_number = ?,
+			     mobile_number = ?,
+			     email = ?,
+			     sortkey = ?,
+			     sms_alert = ?,
+			     checklist = ?,
+			     leg_time = ?,
+			     default_start_time_type = ?,
+			     default_end_time_type = ?,
+			     default_shift_start = ?,
+			     default_shift_end = ?,
+			     utc = ?,
+			     dry = ?,
+			     control_center = ?,
+			     dul = ?,
+			     notes = ?,
+			     is_active = ?,
+			     updated_by = ?,
+			     updated_at = ?
+			 WHERE id = ? AND deleted_at IS NULL`),
+			row.BaseName,
+			binaryValue{data: row.BaseCategoryID},
+			binaryValue{data: row.FotoAttachmentID},
+			row.BaseAbbreviation,
+			row.Address,
+			row.Latitude,
+			row.Longitude,
+			row.LandlineNumber,
+			row.MobileNumber,
+			row.Email,
+			row.SortKey,
+			row.SMSAlert,
+			row.Checklist,
+			row.LegTime,
+			row.DefaultStartTimeType,
+			row.DefaultEndTimeType,
+			row.DefaultShiftStart,
+			row.DefaultShiftEnd,
+			row.UTC,
+			row.Dry,
+			row.ControlCenter,
+			row.DUL,
+			row.Notes,
+			row.IsActive,
+			binaryValue{data: row.UpdatedBy},
+			time.Now().UTC(),
+			binaryValue{data: row.ID},
+		).Error; err != nil {
+			return err
+		}
+		if err := r.replaceBaseContactRolesTx(ctx, tx, row.ID, row.HEMSEDCContactIDs, row.MedPaxContactIDs, row.ResponsiblePilotContactIDs); err != nil {
+			return err
+		}
+		if row.OperationalShiftTimes == nil {
+			return nil
+		}
+		return r.replaceBaseOperationalShiftTimesTx(ctx, tx, row.ID, row.OperationalShiftTimes)
+	})
+}
+
+func (r *BaseRepository) DeleteBase(ctx context.Context, id []byte, categoryType string) error {
+	categoryID, err := r.categoryIDByType(ctx, categoryType)
+	if err != nil {
+		return err
+	}
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "bases", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+	}
+	if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+		updates["deleted_by"] = actor
+		updates["updated_by"] = actor
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&base.Base{}).
+		Where("id = ? AND base_category_id = ? AND deleted_at IS NULL", id, categoryID).
+		Updates(updates).Error)
+}
+
+func (r *BaseRepository) GetBaseByID(ctx context.Context, id []byte, categoryType string) (*base.Base, error) {
+	categoryID, err := r.categoryIDByType(ctx, categoryType)
+	if err != nil {
+		return nil, err
+	}
+
+	var row base.Base
+	err = r.db.WithContext(ctx).
+		Preload("FotoAttachment").
+		Preload("FotoAttachment.File").
+		Preload("OperationalShiftTimes", preloadBaseOperationalShiftTimes).
+		Where("id = ? AND base_category_id = ? AND deleted_at IS NULL", id, categoryID).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err == nil {
+		if loadErr := r.loadBaseContactRoles(ctx, []*base.Base{&row}); loadErr != nil {
+			return nil, loadErr
+		}
+	}
+	return &row, err
+}
+
+func (r *BaseRepository) ListBases(ctx context.Context, filter, sort string, limit, offset int, categoryType string, dul *bool) ([]base.Base, int64, error) {
+	var rows []base.Base
+	var total int64
+
+	baseQuery := r.db.WithContext(ctx).
+		Model(&base.Base{}).
+		Where("deleted_at IS NULL")
+	if strings.TrimSpace(categoryType) != "" {
+		categoryID, err := r.categoryIDByType(ctx, categoryType)
+		if err != nil {
+			return nil, 0, err
+		}
+		baseQuery = baseQuery.Where("base_category_id = ?", categoryID)
+	}
+	if filter != "" {
+		like := "%" + filter + "%"
+		baseQuery = baseQuery.Where(
+			"base LIKE ? OR base_abbreviation LIKE ? OR address LIKE ? OR email LIKE ? OR landline_number LIKE ? OR mobile_number LIKE ?",
+			like,
+			like,
+			like,
+			like,
+			like,
+			like,
+		)
+	}
+	if dul != nil {
+		baseQuery = baseQuery.Where("dul = ?", *dul)
+	}
+
+	query := baseQuery
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("bases", "is_active", "sortkey", "base", false) {
+			query = query.Order(clause)
+		}
+	}
+	if err := baseQuery.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	query = query.Preload("BaseCategory")
+	query = query.Preload("FotoAttachment").Preload("FotoAttachment.File")
+	query = query.Preload("OperationalShiftTimes", preloadBaseOperationalShiftTimes)
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	ptrs := make([]*base.Base, 0, len(rows))
+	for i := range rows {
+		ptrs = append(ptrs, &rows[i])
+	}
+	if err := r.loadBaseContactRoles(ctx, ptrs); err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func preloadBaseOperationalShiftTimes(db *gorm.DB) *gorm.DB {
+	if db == nil {
+		return db
+	}
+	q := db.Where("deleted_at IS NULL").Order("date_start ASC, date_end ASC")
+	if db.Dialector != nil && strings.EqualFold(db.Dialector.Name(), "mysql") {
+		q = q.Select(`
+			id,
+			base_id,
+			date_start,
+			date_end,
+			start_time_type,
+			end_time_type,
+			CASE WHEN shift_start IS NULL THEN '' ELSE TIME_FORMAT(shift_start, '%H:%i:%s') END AS shift_start,
+			CASE WHEN shift_end IS NULL THEN '' ELSE TIME_FORMAT(shift_end, '%H:%i:%s') END AS shift_end,
+			created_at,
+			created_by,
+			updated_at,
+			updated_by,
+			deleted_at,
+			deleted_by
+		`)
+	}
+	return q
+}
+
+func (r *BaseRepository) replaceBaseContactRolesTx(
+	ctx context.Context,
+	tx *gorm.DB,
+	baseID []byte,
+	hemsEDCIDs [][]byte,
+	medPaxIDs [][]byte,
+	pilotIDs [][]byte,
+) error {
+	if len(baseID) != 16 {
+		return errors.New("invalid base id")
+	}
+	all := append(copyIDs(hemsEDCIDs), medPaxIDs...)
+	all = append(all, pilotIDs...)
+	if err := ensureContactsExistTx(tx, all); err != nil {
+		return err
+	}
+	if err := tx.Where("base_id = ?", baseID).Delete(&base.BaseContactRole{}).Error; err != nil {
+		return err
+	}
+	rows := make([]base.BaseContactRole, 0, len(hemsEDCIDs)+len(medPaxIDs)+len(pilotIDs))
+	actor := actorUserIDFromContext(ctx)
+	for _, contactID := range hemsEDCIDs {
+		if len(contactID) != 16 {
+			return fmt.Errorf("invalid hems_edc contact id")
+		}
+		rows = append(rows, base.BaseContactRole{
+			BaseID:    baseID,
+			ContactID: contactID,
+			RoleCode:  base.BaseContactRoleHEMSEDC,
+			CreatedBy: actor,
+			UpdatedBy: actor,
+		})
+	}
+	for _, contactID := range medPaxIDs {
+		if len(contactID) != 16 {
+			return fmt.Errorf("invalid med_pax contact id")
+		}
+		rows = append(rows, base.BaseContactRole{
+			BaseID:    baseID,
+			ContactID: contactID,
+			RoleCode:  base.BaseContactRoleMedPax,
+			CreatedBy: actor,
+			UpdatedBy: actor,
+		})
+	}
+	for _, contactID := range pilotIDs {
+		if len(contactID) != 16 {
+			return fmt.Errorf("invalid responsible_pilot contact id")
+		}
+		rows = append(rows, base.BaseContactRole{
+			BaseID:    baseID,
+			ContactID: contactID,
+			RoleCode:  base.BaseContactRoleResponsiblePilot,
+			CreatedBy: actor,
+			UpdatedBy: actor,
+		})
+	}
+	if len(rows) == 0 {
+		return nil
+	}
+	return tx.Create(&rows).Error
+}
+
+func (r *BaseRepository) replaceBaseOperationalShiftTimesTx(ctx context.Context, tx *gorm.DB, baseID []byte, items []base.BaseOperationalShiftTime) error {
+	if len(baseID) != 16 {
+		return errors.New("invalid base id")
+	}
+	if items == nil {
+		return nil
+	}
+	actor := actorUserIDFromContext(ctx)
+	if err := tx.Where("base_id = ?", baseID).Delete(&base.BaseOperationalShiftTime{}).Error; err != nil {
+		return err
+	}
+	if len(items) == 0 {
+		return nil
+	}
+	now := time.Now().UTC()
+	for i := range items {
+		row := items[i]
+		if row.DateStart == nil || row.DateEnd == nil || row.DateStart.IsZero() || row.DateEnd.IsZero() {
+			return errors.New("invalid operational shift date range")
+		}
+		if row.DateEnd.Before(*row.DateStart) {
+			return errors.New("operational shift date_end must be >= date_start")
+		}
+		if len(row.ID) == 0 {
+			row.ID = uuidv7.MustBytes()
+		}
+		dateStart := row.DateStart.UTC().Format("2006-01-02")
+		dateEnd := row.DateEnd.UTC().Format("2006-01-02")
+		var createdBy any
+		var updatedBy any
+		if len(actor) > 0 {
+			createdBy = binaryValue{data: actor}
+			updatedBy = binaryValue{data: actor}
+		}
+		shiftStart := shiftTimeValue(row.ShiftStart)
+		shiftEnd := shiftTimeValue(row.ShiftEnd)
+		if err := tx.Exec(
+			`INSERT INTO base_operational_shift_times
+			(id, base_id, date_start, date_end, start_time_type, end_time_type, shift_start, shift_end, created_at, created_by, updated_at, updated_by, deleted_at, deleted_by)
+			VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+			binaryValue{data: row.ID},
+			binaryValue{data: baseID},
+			dateStart,
+			dateEnd,
+			row.StartTimeType,
+			row.EndTimeType,
+			shiftStart,
+			shiftEnd,
+			now,
+			createdBy,
+			now,
+			updatedBy,
+			nil,
+			nil,
+		).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func shiftTimeValue(raw string) any {
+	clock, ok := extractClockValue(raw)
+	if !ok {
+		return nil
+	}
+	return clock
+}
+
+func baseClockStorageValue(raw string) string {
+	clock, ok := extractClockValue(raw)
+	if !ok {
+		return strings.TrimSpace(raw)
+	}
+	return "2000-01-01 " + clock
+}
+
+func normalizeBaseShiftTimeType(raw string) string {
+	switch strings.ToUpper(strings.TrimSpace(raw)) {
+	case "", base.ShiftTimeTypeFixed:
+		return base.ShiftTimeTypeFixed
+	case base.ShiftTimeTypeBMCT:
+		return base.ShiftTimeTypeBMCT
+	case base.ShiftTimeTypeECET:
+		return base.ShiftTimeTypeECET
+	default:
+		return strings.ToUpper(strings.TrimSpace(raw))
+	}
+}
+
+func extractClockValue(raw string) (string, bool) {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return "", false
+	}
+	layouts := []string{
+		"15:04:05",
+		"15:04",
+		"2006-01-02 15:04:05",
+		"2006-01-02 15:04",
+		time.RFC3339,
+		time.RFC3339Nano,
+	}
+	for _, layout := range layouts {
+		if parsed, err := time.Parse(layout, s); err == nil {
+			return parsed.UTC().Format("15:04:05"), true
+		}
+	}
+	return "", false
+}
+
+func ensureContactsExistTx(tx *gorm.DB, ids [][]byte) error {
+	valid := make([][]byte, 0, len(ids))
+	seen := map[string]struct{}{}
+	for _, id := range ids {
+		if len(id) != 16 {
+			return errors.New("invalid contact id")
+		}
+		key := string(id)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		valid = append(valid, id)
+	}
+	if len(valid) == 0 {
+		return nil
+	}
+	var count int64
+	if err := tx.Table("users").Where("id IN ?", valid).Count(&count).Error; err != nil {
+		return err
+	}
+	if count != int64(len(valid)) {
+		return errors.New("one or more contact ids not found")
+	}
+	return nil
+}
+
+func (r *BaseRepository) loadBaseContactRoles(ctx context.Context, bases []*base.Base) error {
+	if len(bases) == 0 {
+		return nil
+	}
+	baseIDs := make([][]byte, 0, len(bases))
+	index := make(map[string]*base.Base, len(bases))
+	for _, b := range bases {
+		if b == nil || len(b.ID) != 16 {
+			continue
+		}
+		baseIDs = append(baseIDs, b.ID)
+		index[string(b.ID)] = b
+		b.HEMSEDCContactIDs = nil
+		b.MedPaxContactIDs = nil
+		b.ResponsiblePilotContactIDs = nil
+		b.HEMSEDCs = nil
+		b.MedPax = nil
+		b.ResponsiblePilots = nil
+	}
+	if len(baseIDs) == 0 {
+		return nil
+	}
+	var rels []base.BaseContactRole
+	if err := r.db.WithContext(ctx).
+		Where("base_id IN ?", baseIDs).
+		Order("created_at ASC").
+		Find(&rels).Error; err != nil {
+		return err
+	}
+	for i := range rels {
+		b := index[string(rels[i].BaseID)]
+		if b == nil {
+			continue
+		}
+		switch rels[i].RoleCode {
+		case base.BaseContactRoleHEMSEDC:
+			b.HEMSEDCContactIDs = append(b.HEMSEDCContactIDs, append([]byte(nil), rels[i].ContactID...))
+		case base.BaseContactRoleMedPax:
+			b.MedPaxContactIDs = append(b.MedPaxContactIDs, append([]byte(nil), rels[i].ContactID...))
+		case base.BaseContactRoleResponsiblePilot:
+			b.ResponsiblePilotContactIDs = append(b.ResponsiblePilotContactIDs, append([]byte(nil), rels[i].ContactID...))
+		}
+	}
+	var hemsEDCContactIDs [][]byte
+	var medPaxContactIDs [][]byte
+	var pilotContactIDs [][]byte
+	for _, b := range bases {
+		for i := range b.HEMSEDCContactIDs {
+			hemsEDCContactIDs = append(hemsEDCContactIDs, b.HEMSEDCContactIDs[i])
+		}
+		for i := range b.MedPaxContactIDs {
+			medPaxContactIDs = append(medPaxContactIDs, b.MedPaxContactIDs[i])
+		}
+		for i := range b.ResponsiblePilotContactIDs {
+			pilotContactIDs = append(pilotContactIDs, b.ResponsiblePilotContactIDs[i])
+		}
+	}
+	allContactIDs := append(append(hemsEDCContactIDs, medPaxContactIDs...), pilotContactIDs...)
+	contactMap, err := r.contactNameMap(ctx, allContactIDs)
+	if err != nil {
+		return err
+	}
+	for _, b := range bases {
+		for i := range b.HEMSEDCContactIDs {
+			id := b.HEMSEDCContactIDs[i]
+			p := contactMap[string(id)]
+			p.ContactID = append([]byte(nil), id...)
+			b.HEMSEDCs = append(b.HEMSEDCs, p)
+		}
+		for i := range b.MedPaxContactIDs {
+			id := b.MedPaxContactIDs[i]
+			p := contactMap[string(id)]
+			p.ContactID = append([]byte(nil), id...)
+			b.MedPax = append(b.MedPax, p)
+		}
+		for i := range b.ResponsiblePilotContactIDs {
+			id := b.ResponsiblePilotContactIDs[i]
+			p := contactMap[string(id)]
+			p.ContactID = append([]byte(nil), id...)
+			b.ResponsiblePilots = append(b.ResponsiblePilots, p)
+		}
+	}
+	return nil
+}
+
+func (r *BaseRepository) contactNameMap(ctx context.Context, contactIDs [][]byte) (map[string]base.BaseContactPerson, error) {
+	uniq := make([][]byte, 0, len(contactIDs))
+	seen := map[string]struct{}{}
+	for _, id := range contactIDs {
+		if len(id) != 16 {
+			continue
+		}
+		key := string(id)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		uniq = append(uniq, id)
+	}
+	if len(uniq) == 0 {
+		return map[string]base.BaseContactPerson{}, nil
+	}
+	var rows []struct {
+		ID        []byte `gorm:"column:id"`
+		FirstName string `gorm:"column:first_name"`
+		LastName  string `gorm:"column:last_name"`
+	}
+	if err := r.db.WithContext(ctx).
+		Table("users").
+		Select("id, first_name, last_name").
+		Where("id IN ?", uniq).
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	out := make(map[string]base.BaseContactPerson, len(rows))
+	for i := range rows {
+		out[string(rows[i].ID)] = base.BaseContactPerson{
+			FirstName: rows[i].FirstName,
+			LastName:  rows[i].LastName,
+		}
+	}
+	return out, nil
+}
+
+func copyIDs(src [][]byte) [][]byte {
+	out := make([][]byte, 0, len(src))
+	for _, id := range src {
+		out = append(out, id)
+	}
+	return out
+}
+
+func (r *BaseRepository) categoryIDByType(ctx context.Context, categoryType string) ([]byte, error) {
+	normalized, ok := base.NormalizeCategoryType(categoryType)
+	if !ok {
+		return nil, errors.New("invalid base category type")
+	}
+	return r.categoryIDByKey(ctx, normalized)
+}
+
+func (r *BaseRepository) categoryIDByKey(ctx context.Context, categoryKey string) ([]byte, error) {
+	var row struct {
+		ID []byte `gorm:"column:id"`
+	}
+	if err := r.db.WithContext(ctx).
+		Table("base_categories").
+		Select("id").
+		Where("`key` = ?", strings.ToLower(strings.TrimSpace(categoryKey))).
+		Take(&row).Error; err != nil {
+		return nil, err
+	}
+	return append([]byte(nil), row.ID...), nil
+}
diff --git a/internal/repository/mysql/base_repo_test.go b/internal/repository/mysql/base_repo_test.go
new file mode 100644
index 0000000..f8f38a4
--- /dev/null
+++ b/internal/repository/mysql/base_repo_test.go
@@ -0,0 +1,375 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/base"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openBaseTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:base_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&base.BaseCategory{}, &filemanager.Folder{}, &filemanager.File{}, &filemanager.Attachment{}, &base.Base{}, &base.BaseContactRole{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	if err := db.AutoMigrate(&base.BaseOperationalShiftTime{}); err != nil {
+		t.Fatalf("auto migrate base operational shift time: %v", err)
+	}
+	return db
+}
+
+func TestBaseRepositoryUpdateBase_ReplacesFotoAttachmentID(t *testing.T) {
+	db := openBaseTestDB(t)
+	repo := NewBaseRepository(db)
+	now := time.Now().UTC()
+
+	category := &base.BaseCategory{
+		ID:        uuidv7.MustBytes(),
+		Key:       base.CategoryKeyRegular,
+		Name:      "Regular",
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	if err := db.Create(category).Error; err != nil {
+		t.Fatalf("create category: %v", err)
+	}
+
+	folder := &filemanager.Folder{
+		ID:             uuidv7.MustBytes(),
+		Name:           "photos",
+		NameNormalized: "photos",
+		Depth:          0,
+		PathCache:      "/photos",
+		NameSlot:       "live",
+		CreatedAt:      now,
+		UpdatedAt:      now,
+	}
+	if err := db.Create(folder).Error; err != nil {
+		t.Fatalf("create folder: %v", err)
+	}
+
+	makeFile := func(name, key string) *filemanager.File {
+		return &filemanager.File{
+			ID:             uuidv7.MustBytes(),
+			FolderID:       folder.ID,
+			Name:           name,
+			NameNormalized: strings.ToLower(name),
+			Extension:      "webp",
+			SizeBytes:      1234,
+			MimeType:       "image/webp",
+			Bucket:         "bucket",
+			ObjectKey:      key,
+			Status:         filemanager.FileStatusReady,
+			NameSlot:       "live",
+			CreatedAt:      now,
+			UpdatedAt:      now,
+		}
+	}
+	oldFile := makeFile("old.webp", "objects/old.webp")
+	newFile := makeFile("new.webp", "objects/new.webp")
+	if err := db.Create(oldFile).Error; err != nil {
+		t.Fatalf("create old file: %v", err)
+	}
+	if err := db.Create(newFile).Error; err != nil {
+		t.Fatalf("create new file: %v", err)
+	}
+
+	oldAttachment := &filemanager.Attachment{
+		ID:        uuidv7.MustBytes(),
+		FileID:    oldFile.ID,
+		RefType:   "base_photo",
+		RefID:     "base-1",
+		IsPrimary: true,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	newAttachment := &filemanager.Attachment{
+		ID:        uuidv7.MustBytes(),
+		FileID:    newFile.ID,
+		RefType:   "base_photo",
+		RefID:     "base-1",
+		IsPrimary: true,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	if err := db.Create(oldAttachment).Error; err != nil {
+		t.Fatalf("create old attachment: %v", err)
+	}
+	if err := db.Create(newAttachment).Error; err != nil {
+		t.Fatalf("create new attachment: %v", err)
+	}
+
+	row := &base.Base{
+		ID:               uuidv7.MustBytes(),
+		BaseCategoryID:   category.ID,
+		BaseName:         "Base Old",
+		FotoAttachmentID: oldAttachment.ID,
+		FotoAttachment:   oldAttachment,
+		CreatedAt:        now,
+		UpdatedAt:        now,
+	}
+	if err := db.Create(row).Error; err != nil {
+		t.Fatalf("seed create base: %v", err)
+	}
+
+	row.FotoAttachmentID = newAttachment.ID
+	row.FotoAttachment = oldAttachment
+	if err := repo.UpdateBase(context.Background(), row, base.CategoryKeyRegular); err != nil {
+		t.Fatalf("update base: %v", err)
+	}
+
+	loaded, err := repo.GetBaseByID(context.Background(), row.ID, base.CategoryKeyRegular)
+	if err != nil {
+		t.Fatalf("get by id after update: %v", err)
+	}
+	if loaded == nil {
+		t.Fatalf("expected updated row")
+	}
+	if string(loaded.FotoAttachmentID) != string(newAttachment.ID) {
+		t.Fatalf("expected foto_attachment_id replaced")
+	}
+}
+
+func TestBaseRepositoryListBases_DefaultOrderActiveSortkey(t *testing.T) {
+	db := openBaseTestDB(t)
+	repo := NewBaseRepository(db)
+	now := time.Now().UTC()
+
+	category := &base.BaseCategory{
+		ID:        uuidv7.MustBytes(),
+		Key:       base.CategoryKeyRegular,
+		Name:      "Regular",
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	if err := db.Create(category).Error; err != nil {
+		t.Fatalf("create category: %v", err)
+	}
+
+	seed := []base.Base{
+		{ID: uuidv7.MustBytes(), BaseName: "Gamma", IsActive: true},
+		{ID: uuidv7.MustBytes(), BaseName: "Beta", SortKey: intPtrBaseRepo(0), IsActive: true},
+		{ID: uuidv7.MustBytes(), BaseName: "Charlie", SortKey: intPtrBaseRepo(2), IsActive: true},
+		{ID: uuidv7.MustBytes(), BaseName: "Alpha", SortKey: intPtrBaseRepo(1), IsActive: true},
+		{ID: uuidv7.MustBytes(), BaseName: "Zulu", IsActive: false},
+		{ID: uuidv7.MustBytes(), BaseName: "Bravo", SortKey: intPtrBaseRepo(9), IsActive: false},
+	}
+	for i := range seed {
+		if err := repo.CreateBase(context.Background(), &seed[i], base.CategoryKeyRegular); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+	}
+
+	rows, total, err := repo.ListBases(context.Background(), "", "", 0, 0, "", nil)
+	if err != nil {
+		t.Fatalf("list bases: %v", err)
+	}
+	if total != 6 || len(rows) != 6 {
+		t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+	}
+
+	gotOrder := []string{rows[0].BaseName, rows[1].BaseName, rows[2].BaseName, rows[3].BaseName, rows[4].BaseName, rows[5].BaseName}
+	wantOrder := []string{"Beta", "Alpha", "Charlie", "Gamma", "Bravo", "Zulu"}
+	for i := range wantOrder {
+		if gotOrder[i] != wantOrder[i] {
+			t.Fatalf("unexpected default order: got=%v want=%v", gotOrder, wantOrder)
+		}
+	}
+}
+
+func TestBaseRepositoryCreateAndGetOperationalShiftTimes(t *testing.T) {
+	db := openBaseTestDB(t)
+	repo := NewBaseRepository(db)
+	now := time.Now().UTC()
+
+	category := &base.BaseCategory{
+		ID:        uuidv7.MustBytes(),
+		Key:       base.CategoryKeyRegular,
+		Name:      "Regular",
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	if err := db.Create(category).Error; err != nil {
+		t.Fatalf("create category: %v", err)
+	}
+	start := time.Date(1900, 1, 1, 9, 0, 0, 0, time.UTC)
+	end := time.Date(1900, 1, 1, 18, 0, 0, 0, time.UTC)
+	date := time.Date(2026, 4, 12, 0, 0, 0, 0, time.UTC)
+	row := &base.Base{
+		ID:             uuidv7.MustBytes(),
+		BaseCategoryID: category.ID,
+		BaseName:       "Base Ops",
+		OperationalShiftTimes: []base.BaseOperationalShiftTime{
+			{
+				DateStart:     &date,
+				DateEnd:       &date,
+				StartTimeType: base.ShiftTimeTypeFixed,
+				EndTimeType:   base.ShiftTimeTypeFixed,
+				ShiftStart:    start.Format("15:04:05"),
+				ShiftEnd:      end.Format("15:04:05"),
+			},
+		},
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	if err := repo.CreateBase(context.Background(), row, base.CategoryKeyRegular); err != nil {
+		t.Fatalf("create base: %v", err)
+	}
+	loaded, err := repo.GetBaseByID(context.Background(), row.ID, base.CategoryKeyRegular)
+	if err != nil {
+		t.Fatalf("get base: %v", err)
+	}
+	if loaded == nil || len(loaded.OperationalShiftTimes) != 1 {
+		t.Fatalf("expected operational shift time to preload")
+	}
+	if got := loaded.OperationalShiftTimes[0].DateStart.Format("2006-01-02"); got != "2026-04-12" {
+		t.Fatalf("unexpected date start: %s", got)
+	}
+	if got := loaded.OperationalShiftTimes[0].DateEnd.Format("2006-01-02"); got != "2026-04-12" {
+		t.Fatalf("unexpected date end: %s", got)
+	}
+	if got := loaded.OperationalShiftTimes[0].ShiftStart; got != "09:00:00" {
+		t.Fatalf("unexpected shift start: %#v", got)
+	}
+	if got := loaded.OperationalShiftTimes[0].StartTimeType; got != base.ShiftTimeTypeFixed {
+		t.Fatalf("unexpected start_time_type: %#v", got)
+	}
+}
+
+func TestBaseRepositoryCreateOperationalShiftTimes_AllowsNilShiftForNonFixedTypes(t *testing.T) {
+	db := openBaseTestDB(t)
+	repo := NewBaseRepository(db)
+	now := time.Now().UTC()
+
+	category := &base.BaseCategory{
+		ID:        uuidv7.MustBytes(),
+		Key:       base.CategoryKeyRegular,
+		Name:      "Regular",
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	if err := db.Create(category).Error; err != nil {
+		t.Fatalf("create category: %v", err)
+	}
+
+	date := time.Date(2026, 4, 12, 0, 0, 0, 0, time.UTC)
+	row := &base.Base{
+		ID:             uuidv7.MustBytes(),
+		BaseCategoryID: category.ID,
+		BaseName:       "Base Ops Empty Shift",
+		OperationalShiftTimes: []base.BaseOperationalShiftTime{
+			{
+				DateStart:     &date,
+				DateEnd:       &date,
+				StartTimeType: base.ShiftTimeTypeBMCT,
+				EndTimeType:   base.ShiftTimeTypeECET,
+			},
+		},
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	if err := repo.CreateBase(context.Background(), row, base.CategoryKeyRegular); err != nil {
+		t.Fatalf("create base: %v", err)
+	}
+
+	loaded, err := repo.GetBaseByID(context.Background(), row.ID, base.CategoryKeyRegular)
+	if err != nil {
+		t.Fatalf("get base: %v", err)
+	}
+	if loaded == nil || len(loaded.OperationalShiftTimes) != 1 {
+		t.Fatalf("expected operational shift time to preload")
+	}
+	if got := loaded.OperationalShiftTimes[0].StartTimeType; got != base.ShiftTimeTypeBMCT {
+		t.Fatalf("unexpected start_time_type: %#v", got)
+	}
+	if got := loaded.OperationalShiftTimes[0].EndTimeType; got != base.ShiftTimeTypeECET {
+		t.Fatalf("unexpected end_time_type: %#v", got)
+	}
+	if got := loaded.OperationalShiftTimes[0].ShiftStart; got != "" {
+		t.Fatalf("expected empty shift start for non-fixed type, got %#v", got)
+	}
+	if got := loaded.OperationalShiftTimes[0].ShiftEnd; got != "" {
+		t.Fatalf("expected empty shift end for non-fixed type, got %#v", got)
+	}
+}
+
+func TestBaseServiceCreateDetailed_PersistsFixedOperationalShiftTimes(t *testing.T) {
+	db := openBaseTestDB(t)
+	repo := NewBaseRepository(db)
+	svc := service.NewBaseService(repo)
+	now := time.Now().UTC()
+
+	category := &base.BaseCategory{
+		ID:        uuidv7.MustBytes(),
+		Key:       base.CategoryKeyRegular,
+		Name:      "Regular",
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	if err := db.Create(category).Error; err != nil {
+		t.Fatalf("create category: %v", err)
+	}
+
+	start := time.Date(2000, 1, 1, 3, 0, 0, 0, time.UTC)
+	end := time.Date(2000, 1, 1, 5, 0, 0, 0, time.UTC)
+	date := time.Date(2026, 6, 15, 0, 0, 0, 0, time.UTC)
+	res, err := svc.CreateDetailed(context.Background(), service.BaseCreateInput{
+		ID:                   uuidv7.MustBytes(),
+		CategoryType:         base.CategoryKeyRegular,
+		BaseName:             "Base Ops Fixed",
+		Latitude:             47.3769,
+		Longitude:            8.5417,
+		DefaultStartTimeType: base.ShiftTimeTypeFixed,
+		DefaultEndTimeType:   base.ShiftTimeTypeFixed,
+		DefaultShiftStart:    &start,
+		DefaultShiftEnd:      &end,
+		OperationalShiftTimes: []service.BaseOperationalShiftTimeInput{
+			{
+				DateStart:     date,
+				DateEnd:       date,
+				StartTimeType: base.ShiftTimeTypeFixed,
+				EndTimeType:   base.ShiftTimeTypeFixed,
+				ShiftStart:    &start,
+				ShiftEnd:      &end,
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("create detailed: %v", err)
+	}
+	if res == nil || res.Row == nil {
+		t.Fatalf("expected create detailed result row")
+	}
+
+	loaded, err := repo.GetBaseByID(context.Background(), res.Row.ID, base.CategoryKeyRegular)
+	if err != nil {
+		t.Fatalf("get base: %v", err)
+	}
+	if loaded == nil || len(loaded.OperationalShiftTimes) != 1 {
+		t.Fatalf("expected operational shift time to preload")
+	}
+	if got := loaded.OperationalShiftTimes[0].ShiftStart; got != "03:00:00" {
+		t.Fatalf("unexpected shift start stored: %#v", got)
+	}
+	if got := loaded.OperationalShiftTimes[0].ShiftEnd; got != "05:00:00" {
+		t.Fatalf("unexpected shift end stored: %#v", got)
+	}
+}
+
+func intPtrBaseRepo(v int) *int { return &v }
diff --git a/internal/repository/mysql/before_flight_inspection_repo.go b/internal/repository/mysql/before_flight_inspection_repo.go
new file mode 100644
index 0000000..f4ad727
--- /dev/null
+++ b/internal/repository/mysql/before_flight_inspection_repo.go
@@ -0,0 +1,66 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	beforeflightinspection "wucher/internal/domain/before_flight_inspection"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	"wucher/internal/domain/helicopter"
+)
+
+type BeforeFlightInspectionRepository struct {
+	db *gorm.DB
+}
+
+func NewBeforeFlightInspectionRepository(db *gorm.DB) *BeforeFlightInspectionRepository {
+	return &BeforeFlightInspectionRepository{db: db}
+}
+
+func (r *BeforeFlightInspectionRepository) Upsert(ctx context.Context, row *beforeflightinspection.BeforeFlightInspection) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *BeforeFlightInspectionRepository) GetByFlightInspectionID(ctx context.Context, flightInspectionID []byte) (*beforeflightinspection.BeforeFlightInspection, error) {
+	var rows []beforeflightinspection.BeforeFlightInspection
+	err := r.db.WithContext(ctx).Where("flight_inspection_id = ?", flightInspectionID).Limit(1).Find(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	if len(rows) == 0 {
+		return nil, nil
+	}
+	return &rows[0], nil
+}
+
+func (r *BeforeFlightInspectionRepository) FlightInspectionExists(ctx context.Context, flightInspectionID []byte) (bool, error) {
+	if len(flightInspectionID) != 16 {
+		return false, nil
+	}
+	var total int64
+	err := r.db.WithContext(ctx).
+		Model(&flightinspection.FlightInspection{}).
+		Where("id = ?", flightInspectionID).
+		Count(&total).Error
+	return total > 0, err
+}
+
+func (r *BeforeFlightInspectionRepository) GetHelicopterCapabilities(ctx context.Context, flightInspectionID []byte) (*beforeflightinspection.HelicopterCapabilities, error) {
+	var caps beforeflightinspection.HelicopterCapabilities
+	tx := r.db.WithContext(ctx).
+		Model(&helicopter.Helicopter{}).
+		Joins("JOIN reserve_acs ra ON ra.helicopter_id = helicopters.id").
+		Where("ra.inspection_id = ? AND ra.deleted_at IS NULL", flightInspectionID).
+		Select("helicopters.nr1, helicopters.nr2, helicopters.lh, helicopters.rh, helicopters.mgb, helicopters.igb, helicopters.tgb").
+		Limit(1).
+		Scan(&caps)
+	if tx.Error != nil {
+		return nil, tx.Error
+	}
+	if tx.RowsAffected == 0 {
+		return nil, errors.New("helicopter not found for flight inspection")
+	}
+	return &caps, nil
+}
diff --git a/internal/repository/mysql/complaint_fleet_visible_test.go b/internal/repository/mysql/complaint_fleet_visible_test.go
new file mode 100644
index 0000000..4890c6b
--- /dev/null
+++ b/internal/repository/mysql/complaint_fleet_visible_test.go
@@ -0,0 +1,99 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/complaint"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+// TestOpenByHelicopterIDsKeepsLatestFlightFixed verifies the fleet rule: every OPEN defect
+// plus FIXED defects from the helicopter's latest flight; fixed defects from older flights
+// drop off.
+func TestOpenByHelicopterIDsKeepsLatestFlightFixed(t *testing.T) {
+	dsn := fmt.Sprintf("file:complaint_fleet_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{NowFunc: func() time.Time { return time.Now().UTC() }})
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	if err := db.AutoMigrate(&complaint.Complaint{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	ctx := context.Background()
+
+	heli := uuidv7.MustBytes()
+	flightOld := uuidv7.MustBytes()
+	flightNew := uuidv7.MustBytes()
+	reporter := uuidv7.MustBytes()
+	now := time.Now().UTC()
+	fixedAt := now
+
+	seed := func(desc string, flightID []byte, reportedAt time.Time, fixed bool) []byte {
+		id := uuidv7.MustBytes()
+		row := &complaint.Complaint{
+			ID:           id,
+			HelicopterID: heli,
+			FlightID:     flightID,
+			Description:  desc,
+			ReportedBy:   reporter,
+			ReportedAt:   reportedAt,
+		}
+		if fixed {
+			row.FixedAt = &fixedAt
+		}
+		if err := db.Create(row).Error; err != nil {
+			t.Fatalf("seed %s: %v", desc, err)
+		}
+		return id
+	}
+
+	// Older flight: one fixed (must drop off), one open (must stay).
+	oldFixed := seed("old-fixed", flightOld, now.Add(-2*time.Hour), true)
+	oldOpen := seed("old-open", flightOld, now.Add(-2*time.Hour), false)
+	// Latest flight: one fixed (must stay), one open (must stay).
+	newFixed := seed("new-fixed", flightNew, now.Add(-1*time.Minute), true)
+	newOpen := seed("new-open", flightNew, now, false)
+
+	// NOTE: mattn-sqlite can't scan the model's datetime(3) columns back into time.Time
+	// (MySQL handles datetime(3) fine), so exercise the exact fleet predicate selecting ids
+	// only. This validates the WHERE that OpenByHelicopterIDs uses.
+	_ = ctx
+	latestFlightSub := "flight_id = (SELECT c2.flight_id FROM complaints c2 WHERE c2.helicopter_id = complaints.helicopter_id AND c2.deleted_at IS NULL AND c2.flight_id IS NOT NULL ORDER BY c2.reported_at DESC, c2.id DESC LIMIT 1)"
+	type idRow struct {
+		ID []byte `gorm:"column:id"`
+	}
+	var idRows []idRow
+	if err := db.Model(&complaint.Complaint{}).
+		Select("id").
+		Where("deleted_at IS NULL AND helicopter_id = ?", heli).
+		Where("fixed_at IS NULL OR " + latestFlightSub).
+		Scan(&idRows).Error; err != nil {
+		t.Fatalf("predicate query: %v", err)
+	}
+	got := map[string]bool{}
+	for i := range idRows {
+		got[string(idRows[i].ID)] = true
+	}
+	rows := idRows
+	if !got[string(oldOpen)] {
+		t.Errorf("old-open should be visible (open always shows)")
+	}
+	if !got[string(newOpen)] {
+		t.Errorf("new-open should be visible")
+	}
+	if !got[string(newFixed)] {
+		t.Errorf("new-fixed should be visible (fixed from latest flight)")
+	}
+	if got[string(oldFixed)] {
+		t.Errorf("old-fixed should be HIDDEN (fixed from an older flight)")
+	}
+	if len(rows) != 3 {
+		t.Fatalf("expected 3 visible complaints, got %d", len(rows))
+	}
+}
diff --git a/internal/repository/mysql/complaint_repo.go b/internal/repository/mysql/complaint_repo.go
new file mode 100644
index 0000000..7fa2815
--- /dev/null
+++ b/internal/repository/mysql/complaint_repo.go
@@ -0,0 +1,194 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	complaint "wucher/internal/domain/complaint"
+)
+
+type ComplaintRepository struct {
+	db *gorm.DB
+}
+
+func NewComplaintRepository(db *gorm.DB) *ComplaintRepository { return &ComplaintRepository{db: db} }
+
+func (r *ComplaintRepository) Create(ctx context.Context, row *complaint.Complaint) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *ComplaintRepository) Update(ctx context.Context, row *complaint.Complaint) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *ComplaintRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return r.db.WithContext(ctx).Model(&complaint.Complaint{}).Where("id = ? AND deleted_at IS NULL", id).Updates(map[string]any{"deleted_at": gorm.Expr("NOW(3)"), "deleted_by": deletedBy, "updated_by": deletedBy}).Error
+}
+
+func (r *ComplaintRepository) GetByID(ctx context.Context, id []byte) (*complaint.Complaint, error) {
+	var row complaint.Complaint
+	err := r.db.WithContext(ctx).
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *ComplaintRepository) ListByHelicopter(ctx context.Context, helicopterID []byte, limit, offset int) ([]complaint.Complaint, int64, error) {
+	rows := make([]complaint.Complaint, 0)
+	var total int64
+	base := r.db.WithContext(ctx).
+		Model(&complaint.Complaint{}).
+		Where("helicopter_id = ? AND deleted_at IS NULL", helicopterID)
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	q := base.Order("reported_at DESC, created_at DESC")
+	if limit > 0 {
+		q = q.Limit(limit).Offset(offset)
+	}
+	err := q.Find(&rows).Error
+	return rows, total, err
+}
+
+func (r *ComplaintRepository) List(ctx context.Context, filter complaint.ListFilter, sort string, limit, offset int) ([]complaint.Complaint, int64, error) {
+	rows := make([]complaint.Complaint, 0)
+	var total int64
+	base := r.db.WithContext(ctx).
+		Model(&complaint.Complaint{}).
+		Where("complaints.deleted_at IS NULL")
+	if len(filter.HelicopterID) == 16 {
+		base = base.Where("complaints.helicopter_id = ?", filter.HelicopterID)
+	}
+	if len(filter.FlightID) == 16 {
+		base = base.Where("complaints.flight_id = ?", filter.FlightID)
+	}
+	if filter.HoldItemsOnly {
+		base = base.Where("complaints.fixed_at IS NULL AND complaints.mel_severity > ?", 0)
+	}
+	if filter.Search != "" {
+		like := "%" + filter.Search + "%"
+		base = base.Where("complaints.description LIKE ? OR CAST(complaints.mel_severity AS CHAR) LIKE ?", like, like)
+	}
+	if filter.DateFrom != "" {
+		base = base.Where("complaints.reported_at >= ?", filter.DateFrom+" 00:00:00")
+	}
+	if filter.DateTo != "" {
+		base = base.Where("complaints.reported_at <= ?", filter.DateTo+" 23:59:59.999")
+	}
+	if filter.Person != "" {
+		like := "%" + filter.Person + "%"
+		base = base.Where(
+			"EXISTS (SELECT 1 FROM users u WHERE u.id IN (complaints.reported_by, complaints.mel_classified_by, complaints.nsr_decided_by) "+
+				"AND TRIM(CONCAT(COALESCE(u.first_name, ''), ' ', COALESCE(u.last_name, ''))) LIKE ?)",
+			like,
+		)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	q := base
+	if sort != "" {
+		q = q.Order(sort)
+	} else {
+		q = q.Order("reported_at DESC, created_at DESC")
+	}
+	if limit > 0 {
+		q = q.Limit(limit).Offset(offset)
+	}
+	if err := q.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func (r *ComplaintRepository) HelicopterHasOpenComplaint(ctx context.Context, helicopterID []byte) (bool, error) {
+	var count int64
+	err := r.db.WithContext(ctx).
+		Model(&complaint.Complaint{}).
+		Where("helicopter_id = ? AND deleted_at IS NULL AND fixed_at IS NULL", helicopterID).
+		Count(&count).Error
+	if err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+// OpenByHelicopterIDs returns the complaints the fleet-status Complaints column shows for
+// the given helicopters, in one query (no N+1). That is every OPEN defect (fixed_at IS
+// NULL) — including NSR-deferred and MEL-within-grace items, which are still open hold
+// items — PLUS the FIXED defects from each helicopter's latest flight (the flight of its
+// most recently reported complaint), so a just-resolved defect stays visible as the last
+// state until a newer flight reports. Fixed defects from older flights drop off here but
+// remain retrievable via the complaint history. A nil/empty helicopterIDs means "all".
+func (r *ComplaintRepository) OpenByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) ([]complaint.Complaint, error) {
+	rows := make([]complaint.Complaint, 0)
+	q := r.db.WithContext(ctx).
+		Model(&complaint.Complaint{}).
+		Where("deleted_at IS NULL").
+		Where("fixed_at IS NULL OR flight_id = (SELECT c2.flight_id FROM complaints c2 WHERE c2.helicopter_id = complaints.helicopter_id AND c2.deleted_at IS NULL AND c2.flight_id IS NOT NULL ORDER BY c2.reported_at DESC, c2.id DESC LIMIT 1)")
+	if len(helicopterIDs) > 0 {
+		q = q.Where("helicopter_id IN ?", helicopterIDs)
+	}
+	err := q.Order("reported_at DESC, created_at DESC").Find(&rows).Error
+	return rows, err
+}
+
+func (r *ComplaintRepository) ActiveGroundingByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) ([]complaint.Complaint, error) {
+	rows := make([]complaint.Complaint, 0)
+	// Grounding candidates: open (not fixed), not released (not NSR), and already
+	// classified (mel_classified_at set). A pending complaint is not yet a grounding
+	// defect — it neither grounds the aircraft nor blocks the EASA release gate until it
+	// is classified. action_taken is intentionally NOT excluded — recording corrective
+	// action no longer lifts the grounding (only an NSR or a signed EASA release does),
+	// so IsGrounding decides. A nil/empty helicopterIDs means "all helicopters".
+	q := r.db.WithContext(ctx).
+		Model(&complaint.Complaint{}).
+		Where("deleted_at IS NULL AND is_nsr = 0 AND fixed_at IS NULL AND mel_classified_at IS NOT NULL")
+	if len(helicopterIDs) > 0 {
+		q = q.Where("helicopter_id IN ?", helicopterIDs)
+	}
+	err := q.Find(&rows).Error
+	return rows, err
+}
+
+func (r *ComplaintRepository) HelicopterHasUnactionedComplaint(ctx context.Context, helicopterID []byte) (bool, error) {
+	var count int64
+	err := r.db.WithContext(ctx).
+		Model(&complaint.Complaint{}).
+		Where("helicopter_id = ? AND deleted_at IS NULL AND fixed_at IS NULL AND is_nsr = 0 AND (action_taken IS NULL OR action_taken = '')", helicopterID).
+		Count(&count).Error
+	if err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+func (r *ComplaintRepository) MarkFixedByHelicopter(ctx context.Context, helicopterID []byte, easaID []byte, actor []byte) error {
+	return r.db.WithContext(ctx).
+		Model(&complaint.Complaint{}).
+		Where("helicopter_id = ? AND deleted_at IS NULL AND fixed_at IS NULL", helicopterID).
+		Updates(map[string]any{"fixed_at": gorm.Expr("NOW(3)"), "fixed_by_easa_id": easaID, "updated_by": actor}).Error
+}
+
+// MarkFixedByComplaint closes a single complaint (by id) — used when a release is
+// scoped to one specific defect via complaint_id. No-op if already fixed/deleted.
+func (r *ComplaintRepository) MarkFixedByComplaint(ctx context.Context, complaintID []byte, easaID []byte, actor []byte) error {
+	return r.db.WithContext(ctx).
+		Model(&complaint.Complaint{}).
+		Where("id = ? AND deleted_at IS NULL AND fixed_at IS NULL", complaintID).
+		Updates(map[string]any{"fixed_at": gorm.Expr("NOW(3)"), "fixed_by_easa_id": easaID, "updated_by": actor}).Error
+}
+
+// MarkFixedByFlight closes every open complaint reported on a flight — used when a
+// release is scoped to a flight via flight_id. No-op for already fixed/deleted rows.
+func (r *ComplaintRepository) MarkFixedByFlight(ctx context.Context, flightID []byte, easaID []byte, actor []byte) error {
+	return r.db.WithContext(ctx).
+		Model(&complaint.Complaint{}).
+		Where("flight_id = ? AND deleted_at IS NULL AND fixed_at IS NULL", flightID).
+		Updates(map[string]any{"fixed_at": gorm.Expr("NOW(3)"), "fixed_by_easa_id": easaID, "updated_by": actor}).Error
+}
diff --git a/internal/repository/mysql/contact_repo.go b/internal/repository/mysql/contact_repo.go
new file mode 100644
index 0000000..97b53d3
--- /dev/null
+++ b/internal/repository/mysql/contact_repo.go
@@ -0,0 +1,1309 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/base"
+	"wucher/internal/domain/contact"
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type ContactRepository struct {
+	db                           *gorm.DB
+	hasBaseContactRolesTable     bool
+	baseContactRolesHasContactID bool
+	baseContactRolesHasDeletedAt bool
+}
+
+const contactBaseRoleDUL = "dul" 
+
+const microsoftIdentityProvider = "microsoft"
+
+var contactProfileTables = []string{
+	"pilot_profiles",
+	"doctor_profiles",
+	"air_rescuer_profiles",
+	"technician_profiles",
+	"flight_assistant_profiles",
+	"staff_profiles",
+}
+
+func NewContactRepository(db *gorm.DB) *ContactRepository {
+	schema := newSchemaCache(db)
+	hasBaseContactRolesTable := schema.HasTable("base_contact_roles")
+	return &ContactRepository{
+		db:                           db,
+		hasBaseContactRolesTable:     hasBaseContactRolesTable,
+		baseContactRolesHasContactID: hasBaseContactRolesTable && schema.HasColumn("base_contact_roles", "contact_id"),
+		baseContactRolesHasDeletedAt: hasBaseContactRolesTable && schema.HasColumn("base_contact_roles", "deleted_at"),
+	}
+}
+
+func copyByteSlices(in [][]byte) [][]byte {
+	out := make([][]byte, 0, len(in))
+	for i := range in {
+		if len(in[i]) == 0 {
+			continue
+		}
+		out = append(out, append([]byte(nil), in[i]...))
+	}
+	return out
+}
+
+func (r *ContactRepository) ListContacts(ctx context.Context, filter contact.ListFilter) ([]contact.ContactListItem, int64, error) {
+	items := make([]contact.ContactListItem, 0)
+	var total int64
+
+	base := r.baseListQuery(ctx)
+	base = applyContactFilters(base, filter)
+
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	query := base.Select(contactDetailSelectSQL())
+	if strings.TrimSpace(filter.Sort) != "" {
+		query = query.Order(filter.Sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("users", "is_active", "sortkey", "first_name", false) {
+			query = query.Order(clause)
+		}
+	}
+
+	if filter.Limit > 0 {
+		query = query.Limit(filter.Limit).Offset(filter.Offset)
+	}
+
+	if err := query.Scan(&items).Error; err != nil {
+		return nil, 0, err
+	}
+	return items, total, nil
+}
+
+func (r *ContactRepository) GetContactByID(ctx context.Context, userID []byte) (*contact.ContactListItem, error) {
+	item := &contact.ContactListItem{}
+	q := r.baseListQuery(ctx).Where("users.id = ?", userID)
+	if err := q.Select(contactDetailSelectSQL()).Take(item).Error; err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	return item, nil
+}
+
+func (r *ContactRepository) IsActorAdmin(ctx context.Context) (bool, error) {
+	return r.isActorAdmin(ctx, r.db.WithContext(ctx))
+}
+
+func (r *ContactRepository) ResolveRoleCodeByID(ctx context.Context, roleID []byte) (string, error) {
+	_, roleCode, err := r.resolveRoleByID(r.db.WithContext(ctx), roleID)
+	if err != nil {
+		return "", err
+	}
+	return roleCode, nil
+}
+
+func (r *ContactRepository) CreateContact(ctx context.Context, in contact.CreateInput) ([]byte, error) {
+	var outID []byte
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if in.User.SSOEmail != nil {
+			isAdmin, err := r.isActorAdmin(ctx, tx)
+			if err != nil {
+				return err
+			}
+			if !isAdmin {
+				return errors.New("only admin can set sso_email")
+			}
+		}
+		assignedRoleIDs := make([][]byte, 0, len(in.RoleIDs))
+		assignedRoleCodes := make([]string, 0, len(in.RoleIDs))
+		switch {
+		case len(in.RoleIDs) > 0:
+			for i := range in.RoleIDs {
+				resolvedID, resolvedCode, err := r.resolveRoleByID(tx, in.RoleIDs[i])
+				if err != nil {
+					return err
+				}
+				assignedRoleIDs = append(assignedRoleIDs, resolvedID)
+				assignedRoleCodes = append(assignedRoleCodes, resolvedCode)
+			}
+		case len(in.RoleID) == 16:
+			resolvedID, resolvedCode, err := r.resolveRoleByID(tx, in.RoleID)
+			if err != nil {
+				return err
+			}
+			assignedRoleIDs = append(assignedRoleIDs, resolvedID)
+			assignedRoleCodes = append(assignedRoleCodes, resolvedCode)
+		case len(in.Profiles) > 0:
+			seen := make(map[string]struct{}, len(in.Profiles))
+			for i := range in.Profiles {
+				resolvedID, resolvedCode, err := r.resolveRoleID(tx, in.Profiles[i].RoleCode)
+				if err != nil {
+					return err
+				}
+				key := string(resolvedID)
+				if _, ok := seen[key]; ok {
+					continue
+				}
+				seen[key] = struct{}{}
+				assignedRoleIDs = append(assignedRoleIDs, resolvedID)
+				assignedRoleCodes = append(assignedRoleCodes, resolvedCode)
+			}
+		default:
+			// Role assignment is optional for contact creation.
+		}
+		var roleID []byte
+		normalizedRoleCode := ""
+		if len(assignedRoleIDs) > 0 {
+			roleID = assignedRoleIDs[0]
+			normalizedRoleCode = assignedRoleCodes[0]
+		}
+		var adminRoleIDs [][]byte
+		if in.User.IsAdmin != nil && *in.User.IsAdmin {
+			adminRoleID, _, err := r.resolveRoleID(tx, "admin")
+			if err != nil {
+				return err
+			}
+			adminRoleIDs = append(adminRoleIDs, adminRoleID)
+		}
+
+		email := strings.TrimSpace(valueOrEmpty(in.User.Email))
+		ssoEmail := normalizedEmailPtr(in.User.SSOEmail)
+		firstName := strings.TrimSpace(valueOrEmpty(in.User.FirstName))
+		lastName := strings.TrimSpace(valueOrEmpty(in.User.LastName))
+		if email == "" || firstName == "" || lastName == "" {
+			return errors.New("email, first_name, and last_name are required")
+		}
+		if err := ensureUniqueSSOEmailTx(tx, ssoEmail, nil); err != nil {
+			return err
+		}
+
+		tz := "UTC"
+		if in.User.Timezone != nil && strings.TrimSpace(*in.User.Timezone) != "" {
+			tz = strings.TrimSpace(*in.User.Timezone)
+		}
+		isActive := true
+		if in.User.IsActive != nil {
+			isActive = *in.User.IsActive
+		}
+		username := trimmedPtr(in.User.Username)
+		if username != nil {
+			exists, err := usernameExistsTx(tx, *username, nil)
+			if err != nil {
+				return err
+			}
+			if exists {
+				return contact.ErrUsernameAlreadyExists
+			}
+		}
+
+		u := &auth.User{
+			Email:       email,
+			SSOEmail:    ssoEmail,
+			Username:    username,
+			FirstName:   firstName,
+			LastName:    lastName,
+			MobilePhone: strings.TrimSpace(valueOrEmpty(in.User.MobilePhone)),
+			Timezone:    tz,
+			SortKey:     in.User.SortKey,
+			RoleID:      roleID,
+			RoleIDs:     append(copyByteSlices(assignedRoleIDs), adminRoleIDs...),
+			IsActive:    isActive,
+		}
+		if in.User.ProfileAttachmentID != nil {
+			u.ProfileAttachmentID = append([]byte(nil), (*in.User.ProfileAttachmentID)...)
+		}
+		if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+			u.CreatedBy = actor
+			u.UpdatedBy = actor
+		}
+		if err := tx.Create(u).Error; err != nil {
+			return err
+		}
+		if err := tx.Model(&auth.User{}).Where("id = ?", u.ID).UpdateColumn("is_active", isActive).Error; err != nil {
+			return err
+		}
+		if err := replaceUserRolesTx(ctx, tx, u.ID, u.RoleID, u.RoleIDs); err != nil {
+			return err
+		}
+		if len(in.Profiles) > 0 {
+			for i := range in.Profiles {
+				if err := r.upsertProfileTx(ctx, tx, u.ID, in.Profiles[i].RoleCode, in.Profiles[i].Patch, true); err != nil {
+					return err
+				}
+			}
+		} else if normalizedRoleCode != "" && hasAnyProfilePatch(in.Profile) {
+			if err := r.upsertProfileTx(ctx, tx, u.ID, normalizedRoleCode, in.Profile, true); err != nil {
+				return err
+			}
+		}
+		outID = append([]byte(nil), u.ID...)
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return outID, nil
+}
+
+func (r *ContactRepository) UpdateContact(ctx context.Context, in contact.UpdateInput) error {
+	if len(in.UserID) != 16 {
+		return errors.New("invalid user id")
+	}
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		exists, err := r.userExistsTx(tx, in.UserID)
+		if err != nil {
+			return err
+		}
+		if !exists {
+			return gorm.ErrRecordNotFound
+		}
+
+		updates := map[string]any{}
+		ssoEmailUpdated := false
+		ssoEmailCleared := false
+		if in.User.SSOEmail != nil {
+			isAdmin, err := r.isActorAdmin(ctx, tx)
+			if err != nil {
+				return err
+			}
+			if !isAdmin {
+				return errors.New("only admin can update sso_email")
+			}
+			normalizedSSO := normalizedEmailPtr(in.User.SSOEmail)
+			if err := ensureUniqueSSOEmailTx(tx, normalizedSSO, in.UserID); err != nil {
+				return err
+			}
+			updates["sso_email"] = normalizedSSO
+			ssoEmailUpdated = true
+			ssoEmailCleared = normalizedSSO == nil
+		}
+		if in.User.Email != nil {
+			updates["email"] = strings.TrimSpace(*in.User.Email)
+		}
+		if in.User.Username != nil {
+			username := trimmedPtr(in.User.Username)
+			if username != nil {
+				exists, err := usernameExistsTx(tx, *username, in.UserID)
+				if err != nil {
+					return err
+				}
+				if exists {
+					return contact.ErrUsernameAlreadyExists
+				}
+			}
+			updates["username"] = username
+		}
+		if in.User.FirstName != nil {
+			updates["first_name"] = strings.TrimSpace(*in.User.FirstName)
+		}
+		if in.User.LastName != nil {
+			updates["last_name"] = strings.TrimSpace(*in.User.LastName)
+		}
+		if in.User.MobilePhone != nil {
+			updates["mobile_phone"] = strings.TrimSpace(*in.User.MobilePhone)
+		}
+		if in.User.Timezone != nil {
+			updates["timezone"] = strings.TrimSpace(*in.User.Timezone)
+		}
+		if in.User.SortKeySet {
+			if in.User.SortKey == nil {
+				updates["sortkey"] = nil
+			} else {
+				updates["sortkey"] = *in.User.SortKey
+			}
+		}
+		if in.User.IsActive != nil {
+			updates["is_active"] = *in.User.IsActive
+		}
+		if in.User.ProfileAttachmentID != nil {
+			updates["profile_attachment_id"] = *in.User.ProfileAttachmentID
+		}
+		if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+			updates["updated_by"] = actor
+		}
+		if len(updates) > 0 {
+			if err := tx.Table("users").Where("id = ?", in.UserID).Updates(updates).Error; err != nil {
+				return err
+			}
+		}
+		if ssoEmailUpdated && ssoEmailCleared {
+			if err := tx.Where("user_id = ? AND provider = ?", in.UserID, microsoftIdentityProvider).
+				Delete(&auth.UserIdentity{}).Error; err != nil {
+				return err
+			}
+		}
+		if in.UpdateRoles {
+			if len(in.RoleID) != 0 && len(in.RoleID) != 16 {
+				return errors.New("invalid role_id")
+			}
+			if err := tx.Table("users").Where("id = ?", in.UserID).Update("role_id", in.RoleID).Error; err != nil {
+				return err
+			}
+			if err := replaceUserRolesTx(ctx, tx, in.UserID, in.RoleID, in.RoleIDs); err != nil {
+				return err
+			}
+		}
+		if in.User.IsAdmin != nil {
+			if err := r.syncAdminRoleTx(ctx, tx, in.UserID, *in.User.IsAdmin); err != nil {
+				return err
+			}
+		}
+
+		if len(in.Profiles) > 0 {
+			for i := range in.Profiles {
+				if err := r.upsertProfileTx(ctx, tx, in.UserID, in.Profiles[i].RoleCode, in.Profiles[i].Patch, false); err != nil {
+					return err
+				}
+			}
+			if err := r.touchUserUpdatedByTx(ctx, tx, in.UserID); err != nil {
+				return err
+			}
+		} else if hasAnyProfilePatch(in.Profile) {
+			roleCode := strings.TrimSpace(in.TargetProfileRole)
+			if roleCode == "" {
+				resolvedRoleCode, err := r.roleCodeForUser(tx, in.UserID)
+				if err != nil {
+					if errors.Is(err, gorm.ErrRecordNotFound) {
+						// Contact can now have no role. If profile payload still comes from FE
+						// while no role is assigned, skip profile upsert and keep user update successful.
+						return nil
+					}
+					return err
+				}
+				roleCode = resolvedRoleCode
+			}
+			if err := r.upsertProfileTx(ctx, tx, in.UserID, roleCode, in.Profile, false); err != nil {
+				return err
+			}
+			if err := r.touchUserUpdatedByTx(ctx, tx, in.UserID); err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+}
+
+func (r *ContactRepository) DeleteContact(ctx context.Context, userID []byte) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		exists, err := r.userExistsTx(tx, userID)
+		if err != nil {
+			return err
+		}
+		if !exists {
+			return gorm.ErrRecordNotFound
+		}
+		if r.hasBaseContactRolesTable && r.baseContactRolesHasContactID {
+			query := tx.Table("base_contact_roles").Where("contact_id = ?", userID)
+			if r.baseContactRolesHasDeletedAt {
+				query = query.Where("deleted_at IS NULL")
+			}
+			var count int64
+			if err := query.Count(&count).Error; err != nil {
+				return err
+			}
+			if count > 0 {
+				return apperrors.NewDeleteConflictError("bases")
+			}
+		}
+		if err := r.deleteContactProfilesTx(tx, userID); err != nil {
+			return err
+		}
+		if err := tx.Where("user_id = ?", userID).Delete(&auth.UserRole{}).Error; err != nil {
+			return err
+		}
+		return tx.Where("id = ?", userID).Delete(&auth.User{}).Error
+	})
+}
+
+func (r *ContactRepository) UpdateContactStatus(ctx context.Context, userID []byte, isActive bool) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		exists, err := r.userExistsTx(tx, userID)
+		if err != nil {
+			return err
+		}
+		if !exists {
+			return gorm.ErrRecordNotFound
+		}
+		updates := map[string]any{"is_active": isActive}
+		if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+			updates["updated_by"] = actor
+		}
+		return tx.Table("users").Where("id = ?", userID).Updates(updates).Error
+	})
+}
+
+func (r *ContactRepository) UpdateContactRole(ctx context.Context, userID []byte, roleCode string) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		exists, err := r.userExistsTx(tx, userID)
+		if err != nil {
+			return err
+		}
+		if !exists {
+			return gorm.ErrRecordNotFound
+		}
+
+		currentRoleID, err := r.primaryRoleIDForUserTx(tx, userID)
+		if err != nil {
+			return err
+		}
+		roleID, normalizedRoleCode, err := r.resolveRoleID(tx, roleCode)
+		if err != nil {
+			return err
+		}
+		userUpdates := map[string]any{"role_id": roleID}
+		if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+			userUpdates["updated_by"] = actor
+		}
+		if err := tx.Table("users").Where("id = ?", userID).Updates(userUpdates).Error; err != nil {
+			return err
+		}
+		if err := replacePrimaryUserRoleTx(ctx, tx, userID, currentRoleID, roleID); err != nil {
+			return err
+		}
+		// Ensure profile row exists for the new role.
+		return r.upsertProfileTx(ctx, tx, userID, normalizedRoleCode, contact.ProfilePatch{}, false)
+	})
+}
+
+func (r *ContactRepository) userExistsTx(tx *gorm.DB, userID []byte) (bool, error) {
+	var count int64
+	if err := tx.Table("users").Where("id = ?", userID).Limit(1).Count(&count).Error; err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+func (r *ContactRepository) deleteContactProfilesTx(tx *gorm.DB, userID []byte) error {
+	for i := range contactProfileTables {
+		if err := tx.Exec("DELETE FROM "+contactProfileTables[i]+" WHERE user_id = ?", userID).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (r *ContactRepository) UpdatePilotCategory(ctx context.Context, userID []byte, category string) error {
+	category = strings.ToLower(strings.TrimSpace(category))
+	if category == "" {
+		return errors.New("pilot_category is required")
+	}
+	patch := contact.ProfilePatch{PilotCategory: &category}
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := r.upsertProfileTx(ctx, tx, userID, auth.RoleCodePilot, patch, false); err != nil {
+			return err
+		}
+		return r.touchUserUpdatedByTx(ctx, tx, userID)
+	})
+}
+
+func (r *ContactRepository) UpdateLicense(ctx context.Context, userID []byte, licenseNo *string) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		roleCode, err := r.roleCodeForUser(tx, userID)
+		if err != nil {
+			return err
+		}
+		patch := contact.ProfilePatch{LicenseNo: licenseNo}
+		if err := r.upsertProfileTx(ctx, tx, userID, roleCode, patch, false); err != nil {
+			return err
+		}
+		return r.touchUserUpdatedByTx(ctx, tx, userID)
+	})
+}
+
+func (r *ContactRepository) UpdateChiefFlags(ctx context.Context, userID []byte, patch contact.ProfilePatch) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		roleCode, err := r.roleCodeForUser(tx, userID)
+		if err != nil {
+			return err
+		}
+		if err := r.upsertProfileTx(ctx, tx, userID, roleCode, patch, false); err != nil {
+			return err
+		}
+		return r.touchUserUpdatedByTx(ctx, tx, userID)
+	})
+}
+
+func (r *ContactRepository) UpdateResponsibleComplaints(ctx context.Context, userID []byte, value bool) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		patch := contact.ProfilePatch{IsResponsibleComplaints: &value}
+		if err := r.upsertProfileTx(ctx, tx, userID, auth.RoleCodeTechnician, patch, false); err != nil {
+			return err
+		}
+		return r.touchUserUpdatedByTx(ctx, tx, userID)
+	})
+}
+
+func (r *ContactRepository) BulkUpdateStatus(ctx context.Context, userIDs [][]byte, isActive bool) (int64, error) {
+	if len(userIDs) == 0 {
+		return 0, nil
+	}
+	updates := map[string]any{"is_active": isActive}
+	if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+		updates["updated_by"] = actor
+	}
+	res := r.db.WithContext(ctx).Table("users").Where("id IN ?", userIDs).Updates(updates)
+	if res.Error != nil {
+		return 0, res.Error
+	}
+	return res.RowsAffected, nil
+}
+
+func (r *ContactRepository) touchUserUpdatedByTx(ctx context.Context, tx *gorm.DB, userID []byte) error {
+	actor := actorUserIDFromContext(ctx)
+	if len(actor) == 0 {
+		return nil
+	}
+	return tx.Table("users").Where("id = ?", userID).Update("updated_by", actor).Error
+}
+
+func (r *ContactRepository) baseListQuery(ctx context.Context) *gorm.DB {
+	return r.db.WithContext(ctx).
+		Table("users").
+		Joins("LEFT JOIN roles ON roles.id = users.role_id").
+		Joins("LEFT JOIN pilot_profiles pp ON pp.user_id = users.id").
+		Joins("LEFT JOIN doctor_profiles dp ON dp.user_id = users.id").
+		Joins("LEFT JOIN air_rescuer_profiles arp ON arp.user_id = users.id").
+		Joins("LEFT JOIN technician_profiles tp ON tp.user_id = users.id").
+		Joins("LEFT JOIN flight_assistant_profiles fap ON fap.user_id = users.id").
+		Joins("LEFT JOIN staff_profiles sp ON sp.user_id = users.id")
+}
+
+func (r *ContactRepository) isActorAdmin(ctx context.Context, tx *gorm.DB) (bool, error) {
+	actor := actorUserIDFromContext(ctx)
+	if len(actor) != 16 {
+		return false, nil
+	}
+	var count int64
+	err := tx.Table("users AS actor_users").
+		Joins("LEFT JOIN user_roles ur ON ur.user_id = actor_users.id").
+		Joins("LEFT JOIN roles role_primary ON role_primary.id = actor_users.role_id").
+		Joins("LEFT JOIN roles role_assigned ON role_assigned.id = ur.role_id").
+		Where("actor_users.id = ?", actor).
+		Where(`(
+			LOWER(COALESCE(NULLIF(role_primary.code, ''), role_primary.name)) = ? OR
+			LOWER(COALESCE(NULLIF(role_assigned.code, ''), role_assigned.name)) = ?
+		)`, "admin", "admin").
+		Count(&count).Error
+	if err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+func applyContactFilters(q *gorm.DB, filter contact.ListFilter) *gorm.DB {
+	role := strings.ToLower(strings.TrimSpace(filter.Role))
+	if role != "" {
+		q = q.Where(`(
+			LOWER(COALESCE(NULLIF(roles.code, ''), roles.name)) = ?
+			OR
+			EXISTS (
+				SELECT 1
+				FROM user_roles ur_filter
+				JOIN roles r_filter ON r_filter.id = ur_filter.role_id
+				WHERE ur_filter.user_id = users.id
+				  AND LOWER(COALESCE(NULLIF(r_filter.code, ''), r_filter.name)) = ?
+			)
+		)`, role, role)
+	}
+
+	pilotCategory := strings.ToLower(strings.TrimSpace(filter.PilotCategory))
+	if pilotCategory != "" {
+		q = q.Where(`(
+			LOWER(COALESCE(NULLIF(roles.code, ''), roles.name)) = ?
+			OR
+			EXISTS (
+				SELECT 1
+				FROM user_roles ur_pilot
+				JOIN roles r_pilot ON r_pilot.id = ur_pilot.role_id
+				WHERE ur_pilot.user_id = users.id
+				  AND LOWER(COALESCE(NULLIF(r_pilot.code, ''), r_pilot.name)) = ?
+			)
+		)`, auth.RoleCodePilot, auth.RoleCodePilot).Where("pp.pilot_category = ?", pilotCategory)
+	}
+	if filter.ChiefDoctor != nil {
+		q = q.Where("COALESCE(dp.is_chief_physician, 0) = ?", *filter.ChiefDoctor)
+	}
+	if filter.ChiefTechnician != nil {
+		q = q.Where("COALESCE(tp.is_chief_technician, 0) = ?", *filter.ChiefTechnician)
+	}
+	if filter.ResponsibleComplaint != nil {
+		q = q.Where("COALESCE(tp.is_responsible_complaints, 0) = ?", *filter.ResponsibleComplaint)
+	}
+	if filter.ChiefPilot != nil {
+		q = q.Where("COALESCE(pp.is_chief_pilot, 0) = ?", *filter.ChiefPilot)
+	}
+	if filter.IFRQualified != nil {
+		q = q.Where("COALESCE(pp.has_ifr_qualification, 0) = ?", *filter.IFRQualified)
+	}
+
+	search := strings.TrimSpace(filter.Search)
+	if search != "" {
+		like := "%" + search + "%"
+		q = q.Where(`
+			users.username LIKE ? OR
+			users.email LIKE ? OR
+			users.first_name LIKE ? OR
+			users.last_name LIKE ? OR
+			pp.note LIKE ? OR
+			dp.note LIKE ? OR
+			arp.note LIKE ? OR
+			tp.note LIKE ? OR
+			fap.note LIKE ? OR
+			sp.note LIKE ? OR
+			pp.short_name LIKE ? OR
+			dp.short_name LIKE ? OR
+			arp.short_name LIKE ? OR
+			tp.short_name LIKE ? OR
+			fap.short_name LIKE ? OR
+			sp.short_name LIKE ?
+		`, like, like, like, like, like, like, like, like, like, like, like, like, like, like, like, like)
+	}
+	return q
+}
+
+func contactListSelectSQL() string {
+	return `
+		users.id AS user_id,
+		users.created_by AS created_by,
+		users.updated_by AS updated_by,
+		COALESCE(NULLIF(roles.code, ''), roles.name) AS role_code,
+		roles.name AS role_name,
+		pp.pilot_category AS pilot_category,
+		users.username AS username,
+		users.email AS email,
+		users.sso_email AS sso_email,
+		EXISTS (
+			SELECT 1
+			FROM user_roles ur_admin
+			JOIN roles r_admin ON r_admin.id = ur_admin.role_id
+			WHERE ur_admin.user_id = users.id
+			  AND LOWER(COALESCE(NULLIF(r_admin.code, ''), r_admin.name)) = 'admin'
+		) AS is_admin,
+		users.first_name AS first_name,
+		users.last_name AS last_name,
+		COALESCE(pp.short_name, dp.short_name, arp.short_name, tp.short_name, fap.short_name, sp.short_name) AS short_name,
+		COALESCE(pp.license_no, tp.license_no) AS license_no,
+		COALESCE(pp.location, dp.location, arp.location, tp.location, fap.location, sp.location) AS location,
+		users.mobile_phone AS mobile_phone,
+		users.profile_attachment_id AS profile_attachment_id,
+		(COALESCE(OCTET_LENGTH(users.password_hash), 0) > 0) AS has_password,
+		users.sortkey AS sortkey,
+		COALESCE(pp.note, dp.note, arp.note, tp.note, fap.note, sp.note, '') AS note,
+		users.is_active AS is_active,
+		users.created_at AS created_at,
+		users.updated_at AS updated_at
+	`
+}
+
+func contactDetailSelectSQL() string {
+	return `
+		users.id AS user_id,
+		users.created_by AS created_by,
+		users.updated_by AS updated_by,
+		COALESCE(NULLIF(roles.code, ''), roles.name) AS role_code,
+		roles.name AS role_name,
+		pp.pilot_category AS pilot_category,
+		users.username AS username,
+		users.email AS email,
+		users.sso_email AS sso_email,
+		EXISTS (
+			SELECT 1
+			FROM user_roles ur_admin
+			JOIN roles r_admin ON r_admin.id = ur_admin.role_id
+			WHERE ur_admin.user_id = users.id
+			  AND LOWER(COALESCE(NULLIF(r_admin.code, ''), r_admin.name)) = 'admin'
+		) AS is_admin,
+		users.first_name AS first_name,
+		users.last_name AS last_name,
+		COALESCE(pp.short_name, dp.short_name, arp.short_name, tp.short_name, fap.short_name, sp.short_name) AS short_name,
+		COALESCE(pp.license_no, tp.license_no) AS license_no,
+		COALESCE(pp.location, dp.location, arp.location, tp.location, fap.location, sp.location) AS location,
+		users.mobile_phone AS mobile_phone,
+		users.profile_attachment_id AS profile_attachment_id,
+		(COALESCE(OCTET_LENGTH(users.password_hash), 0) > 0) AS has_password,
+		users.sortkey AS sortkey,
+		COALESCE(pp.note, dp.note, arp.note, tp.note, fap.note, sp.note, '') AS note,
+			(
+				SELECT GROUP_CONCAT(CONCAT(LOWER(HEX(bcr.base_id)), '|', LOWER(HEX(b.base)), '|', bcr.role_code, '|', LOWER(HEX(COALESCE(bc.name, '')))))
+				FROM base_contact_roles bcr
+				JOIN bases b ON b.id = bcr.base_id AND b.deleted_at IS NULL
+				LEFT JOIN base_categories bc ON bc.id = b.base_category_id
+				WHERE bcr.contact_id = users.id
+			) AS base_roles_raw,
+		(
+			SELECT GROUP_CONCAT(CONCAT(LOWER(HEX(r_all.id)), '|', LOWER(HEX(r_all.name)), '|', LOWER(COALESCE(NULLIF(r_all.code, ''), r_all.name))))
+			FROM user_roles ur_all
+			JOIN roles r_all ON r_all.id = ur_all.role_id
+			WHERE ur_all.user_id = users.id
+		) AS roles_raw,
+		users.is_active AS is_active,
+		users.created_at AS created_at,
+		users.updated_at AS updated_at,
+		pp.short_name AS pilot_short_name,
+		pp.license_no AS pilot_license_no,
+		pp.license_issued_at AS pilot_license_issued_at,
+		pp.license_expired_at AS pilot_license_expired_at,
+		pp.technician_license_no AS pilot_technician_license_no,
+		pp.has_ifr_qualification AS pilot_has_ifr_qualification,
+		pp.is_chief_pilot AS pilot_is_chief_pilot,
+		(
+			EXISTS (
+				SELECT 1
+				FROM base_contact_roles bcr_dul
+				JOIN bases b_dul ON b_dul.id = bcr_dul.base_id AND b_dul.deleted_at IS NULL
+				WHERE bcr_dul.contact_id = users.id
+				  AND LOWER(bcr_dul.role_code) = 'dul'
+				  AND b_dul.dul = 1
+			)
+		) AS pilot_is_dul,
+		pp.total_flight_minutes AS pilot_total_flight_minutes,
+		pp.responsible_pilot_minutes AS pilot_responsible_pilot_minutes,
+		pp.second_pilot_minutes AS pilot_second_pilot_minutes,
+		pp.double_command_minutes AS pilot_double_command_minutes,
+		pp.flight_instructor_minutes AS pilot_flight_instructor_minutes,
+		pp.night_flight_minutes AS pilot_night_flight_minutes,
+		pp.ifr_flight_minutes AS pilot_ifr_flight_minutes,
+		pp.location AS pilot_location,
+		pp.postcode AS pilot_postcode,
+		pp.street_line AS pilot_street_line,
+		pp.note AS pilot_note,
+		pp.weight_kg AS pilot_weight_kg,
+		dp.short_name AS doctor_short_name,
+		dp.specialization AS doctor_specialization,
+		dp.sub_specialization AS doctor_sub_specialization,
+		dp.is_chief_physician AS doctor_is_chief_physician,
+		dp.location AS doctor_location,
+		dp.postcode AS doctor_postcode,
+		dp.street_line AS doctor_street_line,
+		dp.note AS doctor_note,
+		arp.short_name AS air_rescuer_short_name,
+		arp.responsible_flight_rescuer AS air_rescuer_responsible_flight_rescuer,
+		arp.location AS air_rescuer_location,
+		arp.postcode AS air_rescuer_postcode,
+		arp.street_line AS air_rescuer_street_line,
+		arp.note AS air_rescuer_note,
+		tp.short_name AS technician_short_name,
+		tp.license_no AS technician_license_no,
+		tp.is_chief_technician AS technician_is_chief_technician,
+		tp.is_responsible_complaints AS technician_is_responsible_complaints,
+		tp.location AS technician_location,
+		tp.postcode AS technician_postcode,
+		tp.street_line AS technician_street_line,
+		tp.note AS technician_note,
+		fap.short_name AS flight_assistant_short_name,
+		fap.location AS flight_assistant_location,
+		fap.postcode AS flight_assistant_postcode,
+		fap.street_line AS flight_assistant_street_line,
+		fap.note AS flight_assistant_note,
+		sp.short_name AS staff_short_name,
+		sp.role_label AS staff_role_label,
+		sp.location AS staff_location,
+		sp.postcode AS staff_postcode,
+		sp.street_line AS staff_street_line,
+		sp.note AS staff_note
+	`
+}
+
+func (r *ContactRepository) roleCodeForUser(tx *gorm.DB, userID []byte) (string, error) {
+	var out struct{ RoleCode string }
+	err := tx.Table("users").
+		Select("LOWER(COALESCE(NULLIF(roles.code, ''), roles.name)) AS role_code").
+		Joins("JOIN roles ON roles.id = users.role_id").
+		Where("users.id = ?", userID).
+		Take(&out).Error
+	if err != nil {
+		return "", err
+	}
+	return strings.TrimSpace(out.RoleCode), nil
+}
+
+func (r *ContactRepository) resolveRoleID(tx *gorm.DB, roleCode string) ([]byte, string, error) {
+	roleCode = strings.ToLower(strings.TrimSpace(roleCode))
+	if roleCode == "" {
+		return nil, "", errors.New("role is required")
+	}
+	var role auth.Role
+	err := tx.Where("LOWER(code) = ? OR LOWER(name) = ?", roleCode, roleCode).Take(&role).Error
+	if err != nil {
+		return nil, "", err
+	}
+	normalized := strings.ToLower(strings.TrimSpace(role.Code))
+	if normalized == "" {
+		normalized = strings.ToLower(strings.TrimSpace(role.Name))
+	}
+	return role.ID, normalized, nil
+}
+
+func (r *ContactRepository) resolveRoleByID(tx *gorm.DB, roleID []byte) ([]byte, string, error) {
+	if len(roleID) != 16 {
+		return nil, "", errors.New("role_id is invalid")
+	}
+	var role auth.Role
+	if err := tx.Where("id = ?", roleID).Take(&role).Error; err != nil {
+		return nil, "", err
+	}
+	normalized := strings.ToLower(strings.TrimSpace(role.Code))
+	if normalized == "" {
+		normalized = strings.ToLower(strings.TrimSpace(role.Name))
+	}
+	return role.ID, normalized, nil
+}
+
+func (r *ContactRepository) upsertProfileTx(ctx context.Context, tx *gorm.DB, userID []byte, roleCode string, patch contact.ProfilePatch, isCreate bool) error {
+	now := time.Now().UTC()
+	actor := actorUserIDFromContext(ctx)
+
+	switch strings.ToLower(strings.TrimSpace(roleCode)) {
+	case auth.RoleCodePilot:
+		updates := map[string]any{}
+		if patch.PilotCategory != nil {
+			updates["pilot_category"] = strings.ToLower(strings.TrimSpace(*patch.PilotCategory))
+		}
+		if v := patch.ShortName; v != nil {
+			updates["short_name"] = strings.TrimSpace(*v)
+		}
+		if v := patch.LicenseNo; v != nil {
+			updates["license_no"] = strings.TrimSpace(*v)
+		}
+		if v := patch.LicenseIssuedAt; v != nil {
+			updates["license_issued_at"] = v
+		}
+		if v := patch.LicenseExpiredAt; v != nil {
+			updates["license_expired_at"] = v
+		}
+		if v := patch.TechnicianLicenseNo; v != nil {
+			updates["technician_license_no"] = strings.TrimSpace(*v)
+		}
+		if v := patch.HasIFRQualification; v != nil {
+			updates["has_ifr_qualification"] = *v
+		}
+		if v := patch.IsChiefPilot; v != nil {
+			updates["is_chief_pilot"] = *v
+		}
+		if v := patch.TotalFlightMinutes; v != nil {
+			updates["total_flight_minutes"] = *v
+		}
+		if v := patch.ResponsiblePilotMinutes; v != nil {
+			updates["responsible_pilot_minutes"] = *v
+		}
+		if v := patch.SecondPilotMinutes; v != nil {
+			updates["second_pilot_minutes"] = *v
+		}
+		if v := patch.DoubleCommandMinutes; v != nil {
+			updates["double_command_minutes"] = *v
+		}
+		if v := patch.FlightInstructorMinutes; v != nil {
+			updates["flight_instructor_minutes"] = *v
+		}
+		if v := patch.NightFlightMinutes; v != nil {
+			updates["night_flight_minutes"] = *v
+		}
+		if v := patch.IFRFlightMinutes; v != nil {
+			updates["ifr_flight_minutes"] = *v
+		}
+		if v := patch.Location; v != nil {
+			updates["location"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Postcode; v != nil {
+			updates["postcode"] = strings.TrimSpace(*v)
+		}
+		if v := patch.StreetLine; v != nil {
+			updates["street_line"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Note; v != nil {
+			updates["note"] = strings.TrimSpace(*v)
+		}
+		if v := patch.WeightKG; v != nil {
+			updates["weight_kg"] = *v
+		}
+		if isCreate && patch.PilotCategory == nil {
+			updates["pilot_category"] = auth.PilotCategoryRegular
+		}
+		if err := r.upsertByUserID(tx, "pilot_profiles", userID, updates, actor, now); err != nil {
+			return err
+		}
+		if patch.DULBaseIDsSet {
+			if err := r.syncContactDULBasesTx(ctx, tx, userID, patch.DULBaseIDs); err != nil {
+				return err
+			}
+		}
+		return nil
+
+	case auth.RoleCodeDoctor:
+		updates := map[string]any{}
+		if v := patch.ShortName; v != nil {
+			updates["short_name"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Specialization; v != nil {
+			updates["specialization"] = strings.TrimSpace(*v)
+		}
+		if v := patch.SubSpecialization; v != nil {
+			updates["sub_specialization"] = strings.TrimSpace(*v)
+		}
+		if v := patch.IsChiefPhysician; v != nil {
+			updates["is_chief_physician"] = *v
+		}
+		if v := patch.Location; v != nil {
+			updates["location"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Postcode; v != nil {
+			updates["postcode"] = strings.TrimSpace(*v)
+		}
+		if v := patch.StreetLine; v != nil {
+			updates["street_line"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Note; v != nil {
+			updates["note"] = strings.TrimSpace(*v)
+		}
+		return r.upsertByUserID(tx, "doctor_profiles", userID, updates, actor, now)
+
+	case auth.RoleCodeAirRescuer:
+		updates := map[string]any{}
+		if v := patch.ShortName; v != nil {
+			updates["short_name"] = strings.TrimSpace(*v)
+		}
+		if v := patch.ResponsibleFlightRescuer; v != nil {
+			updates["responsible_flight_rescuer"] = *v
+		}
+		if v := patch.Location; v != nil {
+			updates["location"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Postcode; v != nil {
+			updates["postcode"] = strings.TrimSpace(*v)
+		}
+		if v := patch.StreetLine; v != nil {
+			updates["street_line"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Note; v != nil {
+			updates["note"] = strings.TrimSpace(*v)
+		}
+		return r.upsertByUserID(tx, "air_rescuer_profiles", userID, updates, actor, now)
+
+	case auth.RoleCodeTechnician:
+		updates := map[string]any{}
+		if v := patch.ShortName; v != nil {
+			updates["short_name"] = strings.TrimSpace(*v)
+		}
+		if v := patch.LicenseNo; v != nil {
+			updates["license_no"] = strings.TrimSpace(*v)
+		}
+		if v := patch.IsChiefTechnician; v != nil {
+			updates["is_chief_technician"] = *v
+		}
+		if v := patch.IsResponsibleComplaints; v != nil {
+			updates["is_responsible_complaints"] = *v
+		}
+		if v := patch.Location; v != nil {
+			updates["location"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Postcode; v != nil {
+			updates["postcode"] = strings.TrimSpace(*v)
+		}
+		if v := patch.StreetLine; v != nil {
+			updates["street_line"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Note; v != nil {
+			updates["note"] = strings.TrimSpace(*v)
+		}
+		return r.upsertByUserID(tx, "technician_profiles", userID, updates, actor, now)
+
+	case auth.RoleCodeFlightAssistant:
+		updates := map[string]any{}
+		if v := patch.ShortName; v != nil {
+			updates["short_name"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Location; v != nil {
+			updates["location"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Postcode; v != nil {
+			updates["postcode"] = strings.TrimSpace(*v)
+		}
+		if v := patch.StreetLine; v != nil {
+			updates["street_line"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Note; v != nil {
+			updates["note"] = strings.TrimSpace(*v)
+		}
+		return r.upsertByUserID(tx, "flight_assistant_profiles", userID, updates, actor, now)
+
+	case auth.RoleCodeStaff:
+		updates := map[string]any{}
+		if v := patch.ShortName; v != nil {
+			updates["short_name"] = strings.TrimSpace(*v)
+		}
+		if v := patch.RoleLabel; v != nil {
+			updates["role_label"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Location; v != nil {
+			updates["location"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Postcode; v != nil {
+			updates["postcode"] = strings.TrimSpace(*v)
+		}
+		if v := patch.StreetLine; v != nil {
+			updates["street_line"] = strings.TrimSpace(*v)
+		}
+		if v := patch.Note; v != nil {
+			updates["note"] = strings.TrimSpace(*v)
+		}
+		return r.upsertByUserID(tx, "staff_profiles", userID, updates, actor, now)
+	}
+	return nil
+}
+
+func (r *ContactRepository) upsertByUserID(tx *gorm.DB, table string, userID []byte, updates map[string]any, actor []byte, now time.Time) error {
+	if updates == nil {
+		updates = map[string]any{}
+	}
+	exists, err := r.profileExistsTx(tx, table, userID)
+	if err != nil {
+		return err
+	}
+
+	updates["updated_at"] = now
+	if len(actor) > 0 {
+		updates["updated_by"] = actor
+	}
+	if exists {
+		return tx.Table(table).Where("user_id = ?", userID).Updates(updates).Error
+	}
+
+	insert := map[string]any{"user_id": userID, "created_at": now, "updated_at": now}
+	if len(actor) > 0 {
+		insert["created_by"] = actor
+		insert["updated_by"] = actor
+	}
+	for k, v := range updates {
+		if k == "updated_at" || k == "updated_by" {
+			continue
+		}
+		insert[k] = v
+	}
+	return tx.Table(table).Create(insert).Error
+}
+
+func (r *ContactRepository) profileExistsTx(tx *gorm.DB, table string, userID []byte) (bool, error) {
+	var count int64
+	if err := tx.Table(table).Where("user_id = ?", userID).Limit(1).Count(&count).Error; err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+func valueOrEmpty(v *string) string {
+	if v == nil {
+		return ""
+	}
+	return *v
+}
+
+func trimmedPtr(v *string) *string {
+	trimmed := strings.TrimSpace(valueOrEmpty(v))
+	if trimmed == "" {
+		return nil
+	}
+	return &trimmed
+}
+
+func normalizedEmailPtr(v *string) *string {
+	trimmed := strings.ToLower(strings.TrimSpace(valueOrEmpty(v)))
+	if trimmed == "" {
+		return nil
+	}
+	return &trimmed
+}
+
+func ensureUniqueSSOEmailTx(tx *gorm.DB, ssoEmail *string, currentUserID []byte) error {
+	if ssoEmail == nil {
+		return nil
+	}
+	q := tx.Table("users").Where("sso_email = ?", *ssoEmail)
+	if len(currentUserID) == 16 {
+		q = q.Where("id <> ?", currentUserID)
+	}
+	var count int64
+	if err := q.Limit(1).Count(&count).Error; err != nil {
+		return err
+	}
+	if count > 0 {
+		return errors.New("sso_email already exists")
+	}
+	return nil
+}
+
+func usernameExistsTx(tx *gorm.DB, username string, currentUserID []byte) (bool, error) {
+	username = strings.TrimSpace(username)
+	if username == "" {
+		return false, nil
+	}
+
+	q := tx.Table("users").Select("id").Where("username = ?", username)
+	if len(currentUserID) == 16 {
+		q = q.Where("id <> ?", currentUserID)
+	}
+
+	var row struct {
+		ID []byte `gorm:"column:id"`
+	}
+	err := q.Limit(1).Take(&row).Error
+	switch {
+	case err == nil:
+		return true, nil
+	case errors.Is(err, gorm.ErrRecordNotFound):
+		return false, nil
+	default:
+		return false, err
+	}
+}
+
+func (r *ContactRepository) syncAdminRoleTx(ctx context.Context, tx *gorm.DB, userID []byte, wantAdmin bool) error {
+	if len(userID) != 16 {
+		return errors.New("invalid user id")
+	}
+	primaryRoleID, err := r.primaryRoleIDForUserTx(tx, userID)
+	if err != nil {
+		return err
+	}
+	roleIDs, err := listUserRoleIDsTx(tx, userID)
+	if err != nil {
+		return err
+	}
+	adminRoleID, _, err := r.resolveRoleID(tx, "admin")
+	if err != nil {
+		return err
+	}
+	adminKey := string(adminRoleID)
+
+	adjusted := make([][]byte, 0, len(roleIDs)+1)
+	for i := range roleIDs {
+		if len(roleIDs[i]) != 16 {
+			continue
+		}
+		if string(roleIDs[i]) == adminKey {
+			continue
+		}
+		adjusted = append(adjusted, roleIDs[i])
+	}
+	if wantAdmin {
+		adjusted = append(adjusted, adminRoleID)
+	}
+	return replaceUserRolesTx(ctx, tx, userID, primaryRoleID, adjusted)
+}
+
+func (r *ContactRepository) primaryRoleIDForUserTx(tx *gorm.DB, userID []byte) ([]byte, error) {
+	var row struct {
+		RoleID []byte `gorm:"column:role_id"`
+	}
+	if err := tx.Table("users").Select("role_id").Where("id = ?", userID).Take(&row).Error; err != nil {
+		return nil, err
+	}
+	if len(row.RoleID) != 16 {
+		return nil, nil
+	}
+	return row.RoleID, nil
+}
+
+func hasAnyProfilePatch(p contact.ProfilePatch) bool {
+	return p.PilotCategory != nil ||
+		p.ShortName != nil ||
+		p.LicenseNo != nil ||
+		p.LicenseIssuedAt != nil ||
+		p.LicenseExpiredAt != nil ||
+		p.TechnicianLicenseNo != nil ||
+		p.HasIFRQualification != nil ||
+		p.IsChiefPilot != nil ||
+		p.IsDUL != nil ||
+		p.DULBaseIDsSet ||
+		p.ResponsibleFlightRescuer != nil ||
+		p.TotalFlightMinutes != nil ||
+		p.ResponsiblePilotMinutes != nil ||
+		p.SecondPilotMinutes != nil ||
+		p.DoubleCommandMinutes != nil ||
+		p.FlightInstructorMinutes != nil ||
+		p.NightFlightMinutes != nil ||
+		p.IFRFlightMinutes != nil ||
+		p.Specialization != nil ||
+		p.SubSpecialization != nil ||
+		p.IsChiefPhysician != nil ||
+		p.IsChiefTechnician != nil ||
+		p.IsResponsibleComplaints != nil ||
+		p.RoleLabel != nil ||
+		p.Note != nil ||
+		p.Location != nil ||
+		p.Postcode != nil ||
+		p.StreetLine != nil ||
+		p.WeightKG != nil
+}
+
+func (r *ContactRepository) syncContactDULBasesTx(ctx context.Context, tx *gorm.DB, userID []byte, baseIDs [][]byte) error {
+	if len(userID) != 16 {
+		return errors.New("invalid user id")
+	}
+
+	if err := tx.Where("contact_id = ? AND LOWER(role_code) = ?", userID, contactBaseRoleDUL).Delete(&base.BaseContactRole{}).Error; err != nil {
+		return err
+	}
+	if len(baseIDs) == 0 {
+		return nil
+	}
+
+	validIDs := dedupeBinaryIDs(baseIDs)
+	if err := ensureDULBasesTx(tx, validIDs); err != nil {
+		return err
+	}
+
+	rows := make([]base.BaseContactRole, 0, len(validIDs))
+	actor := actorUserIDFromContext(ctx)
+	for i := range validIDs {
+		rows = append(rows, base.BaseContactRole{
+			BaseID:    validIDs[i],
+			ContactID: userID,
+			RoleCode:  contactBaseRoleDUL,
+			CreatedBy: actor,
+			UpdatedBy: actor,
+		})
+	}
+	return tx.Create(&rows).Error
+}
+
+func dedupeBinaryIDs(ids [][]byte) [][]byte {
+	out := make([][]byte, 0, len(ids))
+	seen := map[string]struct{}{}
+	for i := range ids {
+		if len(ids[i]) != 16 {
+			continue
+		}
+		key := string(ids[i])
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		copyID := make([]byte, 16)
+		copy(copyID, ids[i])
+		out = append(out, copyID)
+	}
+	return out
+}
+
+func ensureDULBasesTx(tx *gorm.DB, ids [][]byte) error {
+	if len(ids) == 0 {
+		return nil
+	}
+	var count int64
+	if err := tx.Table("bases").Where("id IN ? AND deleted_at IS NULL AND dul = 1", ids).Count(&count).Error; err != nil {
+		return err
+	}
+	if int(count) != len(ids) {
+		return errors.New("all dul_base_ids must reference existing base with dul=true")
+	}
+	return nil
+}
diff --git a/internal/repository/mysql/contact_repo_test.go b/internal/repository/mysql/contact_repo_test.go
new file mode 100644
index 0000000..49527e9
--- /dev/null
+++ b/internal/repository/mysql/contact_repo_test.go
@@ -0,0 +1,967 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/contact"
+	"wucher/internal/shared/pkg/appctx"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func TestContactDetailSelectSQL_IncludesProfileAttachmentID(t *testing.T) {
+	sql := contactDetailSelectSQL()
+	if !strings.Contains(sql, "users.profile_attachment_id AS profile_attachment_id") {
+		t.Fatalf("expected detail select to include users.profile_attachment_id alias")
+	}
+}
+
+func TestContactListSelectSQL_IncludesProfileAttachmentID(t *testing.T) {
+	sql := contactListSelectSQL()
+	if !strings.Contains(sql, "users.profile_attachment_id AS profile_attachment_id") {
+		t.Fatalf("expected list select to include users.profile_attachment_id alias")
+	}
+}
+
+func TestContactRepositoryUpdateContactClearSSOEmailUnlinksMicrosoftIdentity(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	repo := NewContactRepository(db)
+
+	adminRoleID := uuidv7.MustBytes()
+	pilotRoleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: adminRoleID, Code: "admin", Name: "Admin"}).Error; err != nil {
+		t.Fatalf("create admin role: %v", err)
+	}
+	if err := db.Create(&auth.Role{ID: pilotRoleID, Code: auth.RoleCodePilot, Name: "Pilot"}).Error; err != nil {
+		t.Fatalf("create pilot role: %v", err)
+	}
+
+	adminUser := &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "admin3@example.com",
+		FirstName: "Admin",
+		LastName:  "User",
+		Timezone:  "UTC",
+		RoleID:    adminRoleID,
+		IsActive:  true,
+	}
+	if err := db.Create(adminUser).Error; err != nil {
+		t.Fatalf("create admin user: %v", err)
+	}
+	ctx := appctx.WithUserID(context.Background(), adminUser.ID)
+
+	sso := "a@microsoft.com"
+	target := &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "target@example.com",
+		SSOEmail:  &sso,
+		FirstName: "Target",
+		LastName:  "User",
+		Timezone:  "UTC",
+		RoleID:    pilotRoleID,
+		IsActive:  true,
+	}
+	if err := db.Create(target).Error; err != nil {
+		t.Fatalf("create target user: %v", err)
+	}
+	if err := db.Create(&auth.UserIdentity{
+		ID:              uuidv7.MustBytes(),
+		UserID:          target.ID,
+		Provider:        "microsoft",
+		ProviderSubject: "subject-a",
+		Email:           "a@microsoft.com",
+	}).Error; err != nil {
+		t.Fatalf("create identity: %v", err)
+	}
+
+	empty := "   "
+	if err := repo.UpdateContact(ctx, contact.UpdateInput{
+		UserID: target.ID,
+		User: contact.UserPatch{
+			SSOEmail: &empty,
+		},
+	}); err != nil {
+		t.Fatalf("update contact clear sso email: %v", err)
+	}
+
+	var refreshed auth.User
+	if err := db.Where("id = ?", target.ID).Take(&refreshed).Error; err != nil {
+		t.Fatalf("reload user: %v", err)
+	}
+	if refreshed.SSOEmail != nil {
+		t.Fatalf("expected user sso_email NULL, got %v", *refreshed.SSOEmail)
+	}
+
+	var count int64
+	if err := db.Table("user_identities").
+		Where("user_id = ? AND provider = ?", target.ID, "microsoft").
+		Count(&count).Error; err != nil {
+		t.Fatalf("count identities: %v", err)
+	}
+	if count != 0 {
+		t.Fatalf("expected microsoft identity unlinked, got %d rows", count)
+	}
+}
+
+func TestContactRepositoryDeleteContactRemovesUserAndProfiles(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	roleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: roleID, Code: auth.RoleCodePilot, Name: "Pilot"}).Error; err != nil {
+		t.Fatalf("create role: %v", err)
+	}
+
+	username := "pilot.delete"
+	user := &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "pilot-delete@example.com",
+		Username:  &username,
+		FirstName: "Pilot",
+		LastName:  "Delete",
+		Timezone:  "Asia/Jakarta",
+		RoleID:    roleID,
+		IsActive:  true,
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}
+	if err := db.Create(user).Error; err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	if err := db.Create(&auth.PilotProfile{
+		UserID:        user.ID,
+		PilotCategory: auth.PilotCategoryRegular,
+		ShortName:     "PD",
+	}).Error; err != nil {
+		t.Fatalf("create pilot profile: %v", err)
+	}
+	if err := db.Create(&auth.DoctorProfile{
+		UserID:    user.ID,
+		ShortName: "Dr PD",
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}).Error; err != nil {
+		t.Fatalf("create extra profile: %v", err)
+	}
+
+	if err := repo.DeleteContact(context.Background(), user.ID); err != nil {
+		t.Fatalf("delete contact: %v", err)
+	}
+
+	var userCount int64
+	if err := db.Table("users").Where("id = ?", user.ID).Count(&userCount).Error; err != nil {
+		t.Fatalf("count users: %v", err)
+	}
+	if userCount != 0 {
+		t.Fatalf("expected user deleted, got %d rows", userCount)
+	}
+
+	for _, table := range contactProfileTables {
+		var count int64
+		if err := db.Table(table).Where("user_id = ?", user.ID).Count(&count).Error; err != nil {
+			t.Fatalf("count %s: %v", table, err)
+		}
+		if count != 0 {
+			t.Fatalf("expected %s deleted, got %d rows", table, count)
+		}
+	}
+}
+
+func TestContactRepositoryDeleteContactBlockedWhenUsedByBase(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	roleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: roleID, Code: auth.RoleCodePilot, Name: "Pilot"}).Error; err != nil {
+		t.Fatalf("create role: %v", err)
+	}
+
+	user := &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "pilot-base-ref@example.com",
+		FirstName: "Pilot",
+		LastName:  "Ref",
+		Timezone:  "UTC",
+		RoleID:    roleID,
+		IsActive:  true,
+	}
+	if err := db.Create(user).Error; err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	if err := db.Exec(`CREATE TABLE IF NOT EXISTS base_contact_roles (
+		id BLOB PRIMARY KEY,
+		base_id BLOB NOT NULL,
+		contact_id BLOB NOT NULL,
+		role_code TEXT NOT NULL
+	)`).Error; err != nil {
+		t.Fatalf("create base_contact_roles: %v", err)
+	}
+	repo := NewContactRepository(db)
+	if err := db.Table("base_contact_roles").Create(map[string]any{
+		"id":         uuidv7.MustBytes(),
+		"base_id":    uuidv7.MustBytes(),
+		"contact_id": user.ID,
+		"role_code":  "responsible_flight_rescuer",
+	}).Error; err != nil {
+		t.Fatalf("seed base_contact_roles: %v", err)
+	}
+
+	err := repo.DeleteContact(context.Background(), user.ID)
+	if err == nil {
+		t.Fatalf("expected delete to be blocked")
+	}
+	if !strings.Contains(strings.ToLower(err.Error()), "bases") {
+		t.Fatalf("expected bases dependency in error, got: %v", err)
+	}
+}
+
+func TestContactRepositoryUpdateContactSameValuesDoesNotReturnNotFound(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	roleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: roleID, Code: auth.RoleCodePilot, Name: "Pilot"}).Error; err != nil {
+		t.Fatalf("create role: %v", err)
+	}
+
+	issuedAt := time.Date(2004, 10, 3, 0, 0, 0, 0, time.UTC)
+	expiredAt := time.Date(2029, 3, 27, 0, 0, 0, 0, time.UTC)
+	weight := 0.0
+	username := "pilot_test_2"
+	user := &auth.User{
+		ID:          uuidv7.MustBytes(),
+		Email:       "pilot2@test.com",
+		Username:    &username,
+		FirstName:   "a",
+		LastName:    "a",
+		MobilePhone: "2",
+		Timezone:    "Asia/Jakarta",
+		RoleID:      roleID,
+		IsActive:    true,
+		CreatedAt:   time.Now().UTC(),
+		UpdatedAt:   time.Now().UTC(),
+	}
+	if err := db.Create(user).Error; err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	if err := db.Create(&auth.PilotProfile{
+		UserID:                  user.ID,
+		PilotCategory:           auth.PilotCategoryRegular,
+		ShortName:               "a",
+		LicenseNo:               "a",
+		LicenseIssuedAt:         &issuedAt,
+		LicenseExpiredAt:        &expiredAt,
+		TechnicianLicenseNo:     "",
+		HasIFRQualification:     true,
+		IsChiefPilot:            false,
+		IsDUL:                   true,
+		TotalFlightMinutes:      2,
+		ResponsiblePilotMinutes: 2,
+		SecondPilotMinutes:      2,
+		DoubleCommandMinutes:    2,
+		FlightInstructorMinutes: 0,
+		NightFlightMinutes:      2,
+		IFRFlightMinutes:        2,
+		Location:                "string",
+		Postcode:                "2",
+		StreetLine:              "2",
+		WeightKG:                &weight,
+		PhotoFileID:             "a",
+		CreatedAt:               time.Now().UTC(),
+		UpdatedAt:               time.Now().UTC(),
+	}).Error; err != nil {
+		t.Fatalf("create pilot profile: %v", err)
+	}
+
+	email := "pilot2@test.com"
+	firstName := "a"
+	lastName := "a"
+	mobilePhone := "2"
+	timezone := "Asia/Jakarta"
+	isActive := true
+	pilotCategory := auth.PilotCategoryRegular
+	shortName := "a"
+	licenseNo := "a"
+	technicianLicenseNo := ""
+	hasIFRQualification := true
+	isChiefPilot := false
+	isDUL := true
+	totalFlightMinutes := 2
+	responsiblePilotMinutes := 2
+	secondPilotMinutes := 2
+	doubleCommandMinutes := 2
+	flightInstructorMinutes := 0
+	nightFlightMinutes := 2
+	ifrFlightMinutes := 2
+	location := "string"
+	postcode := "2"
+	streetLine := "2"
+	photoFileID := "a"
+
+	err := repo.UpdateContact(context.Background(), contact.UpdateInput{
+		UserID: user.ID,
+		User: contact.UserPatch{
+			Email:       &email,
+			Username:    &username,
+			FirstName:   &firstName,
+			LastName:    &lastName,
+			MobilePhone: &mobilePhone,
+			Timezone:    &timezone,
+			IsActive:    &isActive,
+		},
+		Profile: contact.ProfilePatch{
+			PilotCategory:           &pilotCategory,
+			ShortName:               &shortName,
+			LicenseNo:               &licenseNo,
+			LicenseIssuedAt:         &issuedAt,
+			LicenseExpiredAt:        &expiredAt,
+			TechnicianLicenseNo:     &technicianLicenseNo,
+			HasIFRQualification:     &hasIFRQualification,
+			IsChiefPilot:            &isChiefPilot,
+			IsDUL:                   &isDUL,
+			TotalFlightMinutes:      &totalFlightMinutes,
+			ResponsiblePilotMinutes: &responsiblePilotMinutes,
+			SecondPilotMinutes:      &secondPilotMinutes,
+			DoubleCommandMinutes:    &doubleCommandMinutes,
+			FlightInstructorMinutes: &flightInstructorMinutes,
+			NightFlightMinutes:      &nightFlightMinutes,
+			IFRFlightMinutes:        &ifrFlightMinutes,
+			Location:                &location,
+			Postcode:                &postcode,
+			StreetLine:              &streetLine,
+			WeightKG:                &weight,
+			PhotoFileID:             &photoFileID,
+		},
+	})
+	if err != nil {
+		t.Fatalf("update contact with same values: %v", err)
+	}
+
+	var pilotProfileCount int64
+	if err := db.Table("pilot_profiles").Where("user_id = ?", user.ID).Count(&pilotProfileCount).Error; err != nil {
+		t.Fatalf("count pilot profiles: %v", err)
+	}
+	if pilotProfileCount != 1 {
+		t.Fatalf("expected single pilot profile row after update, got %d", pilotProfileCount)
+	}
+
+	got, err := repo.GetContactByID(context.Background(), user.ID)
+	if err != nil {
+		t.Fatalf("get contact after update: %v", err)
+	}
+	if got == nil || got.RoleCode != auth.RoleCodePilot {
+		t.Fatalf("expected pilot contact after update, got %#v", got)
+	}
+}
+
+func TestContactRepositoryUpdateContactClearsAirRescuerProfileStringFields(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	roleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: roleID, Code: auth.RoleCodeAirRescuer, Name: "Air Rescuer"}).Error; err != nil {
+		t.Fatalf("create role: %v", err)
+	}
+
+	user := &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "air-rescuer@test.com",
+		FirstName: "Air",
+		LastName:  "Rescuer",
+		Timezone:  "UTC",
+		RoleID:    roleID,
+		IsActive:  true,
+	}
+	if err := db.Create(user).Error; err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	if err := db.Create(&auth.AirRescuerProfile{
+		UserID:                   user.ID,
+		ShortName:                "CINDY",
+		Location:                 "12",
+		Postcode:                 "12",
+		StreetLine:               "12",
+		Note:                     "12",
+		ResponsibleFlightRescuer: false,
+		CreatedAt:                time.Now().UTC(),
+		UpdatedAt:                time.Now().UTC(),
+	}).Error; err != nil {
+		t.Fatalf("create air rescuer profile: %v", err)
+	}
+
+	empty := ""
+	if err := repo.UpdateContact(context.Background(), contact.UpdateInput{
+		UserID: user.ID,
+		Profile: contact.ProfilePatch{
+			ShortName:  &empty,
+			Location:   &empty,
+			Postcode:   &empty,
+			StreetLine: &empty,
+			Note:       &empty,
+		},
+	}); err != nil {
+		t.Fatalf("update contact clear profile strings: %v", err)
+	}
+
+	var profile auth.AirRescuerProfile
+	if err := db.Where("user_id = ?", user.ID).Take(&profile).Error; err != nil {
+		t.Fatalf("reload air rescuer profile: %v", err)
+	}
+	if profile.ShortName != "" || profile.Location != "" || profile.Postcode != "" || profile.StreetLine != "" || profile.Note != "" {
+		t.Fatalf("expected cleared string fields, got %#v", profile)
+	}
+}
+
+func TestContactRepositoryCreateContactRejectsDuplicateUsername(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	roleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: roleID, Code: auth.RoleCodePilot, Name: "Pilot"}).Error; err != nil {
+		t.Fatalf("create role: %v", err)
+	}
+
+	username := "pilot.duplicate"
+	first, err := repo.CreateContact(context.Background(), contact.CreateInput{
+		RoleID: roleID,
+		User: contact.UserPatch{
+			Email:     strPtrContactRepo("first@example.com"),
+			Username:  &username,
+			FirstName: strPtrContactRepo("First"),
+			LastName:  strPtrContactRepo("User"),
+		},
+	})
+	if err != nil {
+		t.Fatalf("create first contact: %v", err)
+	}
+	if len(first) != 16 {
+		t.Fatalf("expected first user id, got len=%d", len(first))
+	}
+
+	secondUsername := "pilot.duplicate"
+	_, err = repo.CreateContact(context.Background(), contact.CreateInput{
+		RoleID: roleID,
+		User: contact.UserPatch{
+			Email:     strPtrContactRepo("second@example.com"),
+			Username:  &secondUsername,
+			FirstName: strPtrContactRepo("Second"),
+			LastName:  strPtrContactRepo("User"),
+		},
+	})
+	if !errors.Is(err, contact.ErrUsernameAlreadyExists) {
+		t.Fatalf("expected duplicate username error, got %v", err)
+	}
+}
+
+func TestContactRepositoryUpdateContactRejectsDuplicateUsername(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	roleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: roleID, Code: auth.RoleCodePilot, Name: "Pilot"}).Error; err != nil {
+		t.Fatalf("create role: %v", err)
+	}
+
+	firstUsername := "pilot.update.1"
+	firstID, err := repo.CreateContact(context.Background(), contact.CreateInput{
+		RoleID: roleID,
+		User: contact.UserPatch{
+			Email:     strPtrContactRepo("first-update@example.com"),
+			Username:  &firstUsername,
+			FirstName: strPtrContactRepo("First"),
+			LastName:  strPtrContactRepo("User"),
+		},
+	})
+	if err != nil {
+		t.Fatalf("create first contact: %v", err)
+	}
+
+	secondUsername := "pilot.update.2"
+	secondID, err := repo.CreateContact(context.Background(), contact.CreateInput{
+		RoleID: roleID,
+		User: contact.UserPatch{
+			Email:     strPtrContactRepo("second-update@example.com"),
+			Username:  &secondUsername,
+			FirstName: strPtrContactRepo("Second"),
+			LastName:  strPtrContactRepo("User"),
+		},
+	})
+	if err != nil {
+		t.Fatalf("create second contact: %v", err)
+	}
+
+	newUsername := firstUsername
+	err = repo.UpdateContact(context.Background(), contact.UpdateInput{
+		UserID: secondID,
+		User: contact.UserPatch{
+			Username: &newUsername,
+		},
+	})
+	if !errors.Is(err, contact.ErrUsernameAlreadyExists) {
+		t.Fatalf("expected duplicate username error on update, got %v", err)
+	}
+
+	got, err := repo.GetContactByID(context.Background(), firstID)
+	if err != nil {
+		t.Fatalf("get first contact: %v", err)
+	}
+	if got == nil || got.Username != firstUsername {
+		t.Fatalf("unexpected first contact after duplicate update: %#v", got)
+	}
+}
+
+func TestContactRepositoryListContactsDefaultSortByActiveAndSortKey(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	roleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: roleID, Code: auth.RoleCodeStaff, Name: "Staff"}).Error; err != nil {
+		t.Fatalf("create role: %v", err)
+	}
+
+	seedContactStaffUser(t, db, roleID, "Gamma", nil, true, "g-note")
+	seedContactStaffUser(t, db, roleID, "Beta", intPtrContactRepo(0), true, "b-note")
+	seedContactStaffUser(t, db, roleID, "Charlie", intPtrContactRepo(2), true, "c-note")
+	seedContactStaffUser(t, db, roleID, "Alpha", intPtrContactRepo(1), true, "a-note")
+	seedContactStaffUser(t, db, roleID, "Zulu", nil, false, "z-note")
+	seedContactStaffUser(t, db, roleID, "Bravo", intPtrContactRepo(9), false, "br-note")
+
+	rows, total, err := repo.ListContacts(context.Background(), contact.ListFilter{})
+	if err != nil {
+		t.Fatalf("list contacts: %v", err)
+	}
+	if total != 6 || len(rows) != 6 {
+		t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+	}
+
+	got := []string{rows[0].FirstName, rows[1].FirstName, rows[2].FirstName, rows[3].FirstName, rows[4].FirstName, rows[5].FirstName}
+	want := []string{"Beta", "Alpha", "Charlie", "Gamma", "Bravo", "Zulu"}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("unexpected order got=%v want=%v", got, want)
+		}
+	}
+}
+
+func TestContactRepositoryListContactsSearchByNote(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	roleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: roleID, Code: auth.RoleCodeStaff, Name: "Staff"}).Error; err != nil {
+		t.Fatalf("create role: %v", err)
+	}
+
+	seedContactStaffUser(t, db, roleID, "Alpha", nil, true, "dispatcher")
+	seedContactStaffUser(t, db, roleID, "Bravo", nil, true, "maintenance")
+
+	rows, total, err := repo.ListContacts(context.Background(), contact.ListFilter{Search: "dispatch"})
+	if err != nil {
+		t.Fatalf("list contacts: %v", err)
+	}
+	if total != 1 || len(rows) != 1 {
+		t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+	}
+	if rows[0].FirstName != "Alpha" || rows[0].Note != "dispatcher" {
+		t.Fatalf("unexpected row %+v", rows[0])
+	}
+}
+
+func TestContactRepositoryListContactsIncludesPilotProfileFields(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	roleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: roleID, Code: auth.RoleCodePilot, Name: "Pilot"}).Error; err != nil {
+		t.Fatalf("create role: %v", err)
+	}
+
+	userID := uuidv7.MustBytes()
+	username := "pilot_list_detail"
+	issuedAt := time.Date(2026, 4, 20, 0, 0, 0, 0, time.UTC)
+	expiredAt := time.Date(2029, 4, 20, 0, 0, 0, 0, time.UTC)
+	user := &auth.User{
+		ID:        userID,
+		Email:     "pilot.list@example.com",
+		Username:  &username,
+		FirstName: "Pilot",
+		LastName:  "List",
+		Timezone:  "UTC",
+		RoleID:    roleID,
+		IsActive:  true,
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}
+	if err := db.Create(user).Error; err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	if err := db.Create(&auth.PilotProfile{
+		UserID:           userID,
+		PilotCategory:    auth.PilotCategoryFreelance,
+		LicenseIssuedAt:  &issuedAt,
+		LicenseExpiredAt: &expiredAt,
+		CreatedAt:        time.Now().UTC(),
+		UpdatedAt:        time.Now().UTC(),
+	}).Error; err != nil {
+		t.Fatalf("create pilot profile: %v", err)
+	}
+
+	rows, total, err := repo.ListContacts(context.Background(), contact.ListFilter{Role: auth.RoleCodePilot})
+	if err != nil {
+		t.Fatalf("list contacts: %v", err)
+	}
+	if total != 1 || len(rows) != 1 {
+		t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+	}
+	if rows[0].PilotLicenseIssuedAt == nil || !rows[0].PilotLicenseIssuedAt.Equal(issuedAt) {
+		t.Fatalf("expected pilot license_issued_at returned, got %#v", rows[0].PilotLicenseIssuedAt)
+	}
+	if rows[0].PilotLicenseExpiredAt == nil || !rows[0].PilotLicenseExpiredAt.Equal(expiredAt) {
+		t.Fatalf("expected pilot license_expired_at returned, got %#v", rows[0].PilotLicenseExpiredAt)
+	}
+	if rows[0].PilotCategory != auth.PilotCategoryFreelance {
+		t.Fatalf("expected pilot category returned, got %q", rows[0].PilotCategory)
+	}
+}
+
+func TestContactRepositoryUpdateContactRoleAssignsRoleWhenCurrentRoleIsEmpty(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	staffRoleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: staffRoleID, Code: auth.RoleCodeStaff, Name: "Staff"}).Error; err != nil {
+		t.Fatalf("create role: %v", err)
+	}
+
+	userID := uuidv7.MustBytes()
+	user := &auth.User{
+		ID:        userID,
+		Email:     "no-role@example.com",
+		FirstName: "No",
+		LastName:  "Role",
+		Timezone:  "UTC",
+		IsActive:  true,
+	}
+	if err := db.Create(user).Error; err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	if err := repo.UpdateContactRole(context.Background(), userID, auth.RoleCodeStaff); err != nil {
+		t.Fatalf("update contact role: %v", err)
+	}
+
+	var refreshed auth.User
+	if err := db.Where("id = ?", userID).Take(&refreshed).Error; err != nil {
+		t.Fatalf("reload user: %v", err)
+	}
+	if len(refreshed.RoleID) != 16 || string(refreshed.RoleID) != string(staffRoleID) {
+		t.Fatalf("expected role_id updated to staff, got %x", refreshed.RoleID)
+	}
+
+	roleIDs, err := listUserRoleIDsTx(db, userID)
+	if err != nil {
+		t.Fatalf("list user roles: %v", err)
+	}
+	if len(roleIDs) != 1 || string(roleIDs[0]) != string(staffRoleID) {
+		t.Fatalf("expected user_roles to contain only staff role, got %d rows", len(roleIDs))
+	}
+}
+
+func TestContactRepositoryUpdateContact_IsAdminTruePersistsAdminRoleWhenUpdatingRoles(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	adminRoleID := uuidv7.MustBytes()
+	pilotRoleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: adminRoleID, Code: "admin", Name: "Admin"}).Error; err != nil {
+		t.Fatalf("create admin role: %v", err)
+	}
+	if err := db.Create(&auth.Role{ID: pilotRoleID, Code: auth.RoleCodePilot, Name: "Pilot"}).Error; err != nil {
+		t.Fatalf("create pilot role: %v", err)
+	}
+
+	user := &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "admin-sync@example.com",
+		FirstName: "Admin",
+		LastName:  "Sync",
+		Timezone:  "UTC",
+		RoleID:    pilotRoleID,
+		IsActive:  true,
+	}
+	if err := db.Create(user).Error; err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	if err := replaceUserRolesTx(context.Background(), db, user.ID, pilotRoleID, [][]byte{pilotRoleID}); err != nil {
+		t.Fatalf("seed user roles: %v", err)
+	}
+
+	trueVal := true
+	if err := repo.UpdateContact(context.Background(), contact.UpdateInput{
+		UserID:      user.ID,
+		UpdateRoles: true,
+		RoleID:      pilotRoleID,
+		RoleIDs:     [][]byte{pilotRoleID},
+		User: contact.UserPatch{
+			IsAdmin: &trueVal,
+		},
+	}); err != nil {
+		t.Fatalf("update contact: %v", err)
+	}
+
+	roleIDs, err := listUserRoleIDsTx(db, user.ID)
+	if err != nil {
+		t.Fatalf("list user roles: %v", err)
+	}
+	if len(roleIDs) != 2 {
+		t.Fatalf("expected 2 roles (pilot + admin), got %d", len(roleIDs))
+	}
+	foundAdmin := false
+	for i := range roleIDs {
+		if string(roleIDs[i]) == string(adminRoleID) {
+			foundAdmin = true
+			break
+		}
+	}
+	if !foundAdmin {
+		t.Fatalf("expected admin role assigned")
+	}
+}
+
+func TestContactRepositoryUpdateContact_StaffCanBeAdmin(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	adminRoleID := uuidv7.MustBytes()
+	staffRoleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: adminRoleID, Code: "admin", Name: "Admin"}).Error; err != nil {
+		t.Fatalf("create admin role: %v", err)
+	}
+	if err := db.Create(&auth.Role{ID: staffRoleID, Code: auth.RoleCodeStaff, Name: "Staff"}).Error; err != nil {
+		t.Fatalf("create staff role: %v", err)
+	}
+
+	user := &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "staff-admin@example.com",
+		FirstName: "Staff",
+		LastName:  "Admin",
+		Timezone:  "UTC",
+		RoleID:    staffRoleID,
+		IsActive:  true,
+	}
+	if err := db.Create(user).Error; err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	if err := replaceUserRolesTx(context.Background(), db, user.ID, staffRoleID, [][]byte{staffRoleID}); err != nil {
+		t.Fatalf("seed user roles: %v", err)
+	}
+
+	trueVal := true
+	if err := repo.UpdateContact(context.Background(), contact.UpdateInput{
+		UserID: user.ID,
+		User: contact.UserPatch{
+			IsAdmin: &trueVal,
+		},
+	}); err != nil {
+		t.Fatalf("update contact: %v", err)
+	}
+
+	roleIDs, err := listUserRoleIDsTx(db, user.ID)
+	if err != nil {
+		t.Fatalf("list user roles: %v", err)
+	}
+	if len(roleIDs) != 2 {
+		t.Fatalf("expected 2 roles (staff + admin), got %d", len(roleIDs))
+	}
+	foundAdmin := false
+	for i := range roleIDs {
+		if string(roleIDs[i]) == string(adminRoleID) {
+			foundAdmin = true
+			break
+		}
+	}
+	if !foundAdmin {
+		t.Fatalf("expected admin role assigned")
+	}
+}
+
+func TestContactRepositoryUpdateContactNilSortKeyDoesNotClearWithoutSetFlag(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	roleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: roleID, Code: auth.RoleCodeStaff, Name: "Staff"}).Error; err != nil {
+		t.Fatalf("create role: %v", err)
+	}
+
+	sortKey := 7
+	user := &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "sortkey-clear@example.com",
+		FirstName: "Sort",
+		LastName:  "Key",
+		Timezone:  "UTC",
+		RoleID:    roleID,
+		SortKey:   &sortKey,
+		IsActive:  true,
+	}
+	if err := db.Create(user).Error; err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	firstName := "Sorted"
+	if err := repo.UpdateContact(context.Background(), contact.UpdateInput{
+		UserID: user.ID,
+		User: contact.UserPatch{
+			FirstName:  &firstName,
+			SortKey:    nil,
+			SortKeySet: false,
+		},
+	}); err != nil {
+		t.Fatalf("update contact: %v", err)
+	}
+
+	var refreshed auth.User
+	if err := db.Where("id = ?", user.ID).Take(&refreshed).Error; err != nil {
+		t.Fatalf("reload user: %v", err)
+	}
+	if refreshed.SortKey == nil || *refreshed.SortKey != 7 {
+		t.Fatalf("expected sortkey to remain 7, got %#v", refreshed.SortKey)
+	}
+}
+
+func TestContactRepositoryUpdateContactNullSortKeyClearsValue(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	repo := NewContactRepository(db)
+	roleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{ID: roleID, Code: auth.RoleCodeStaff, Name: "Staff"}).Error; err != nil {
+		t.Fatalf("create role: %v", err)
+	}
+
+	sortKey := 7
+	user := &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "sortkey-null@example.com",
+		FirstName: "Sort",
+		LastName:  "Key",
+		Timezone:  "UTC",
+		RoleID:    roleID,
+		SortKey:   &sortKey,
+		IsActive:  true,
+	}
+	if err := db.Create(user).Error; err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	if err := repo.UpdateContact(context.Background(), contact.UpdateInput{
+		UserID: user.ID,
+		User: contact.UserPatch{
+			SortKey:    nil,
+			SortKeySet: true,
+		},
+	}); err != nil {
+		t.Fatalf("update contact: %v", err)
+	}
+
+	var refreshed auth.User
+	if err := db.Where("id = ?", user.ID).Take(&refreshed).Error; err != nil {
+		t.Fatalf("reload user: %v", err)
+	}
+	if refreshed.SortKey != nil {
+		t.Fatalf("expected sortkey NULL, got %d", *refreshed.SortKey)
+	}
+}
+
+func seedContactStaffUser(t *testing.T, db *gorm.DB, roleID []byte, firstName string, sortKey *int, isActive bool, note string) []byte {
+	t.Helper()
+
+	userID := uuidv7.MustBytes()
+	username := fmt.Sprintf("%s_user_%d", firstName, time.Now().UnixNano())
+	user := &auth.User{
+		ID:        userID,
+		Email:     fmt.Sprintf("%s@example.com", username),
+		Username:  &username,
+		FirstName: firstName,
+		LastName:  "Contact",
+		Timezone:  "UTC",
+		RoleID:    roleID,
+		SortKey:   sortKey,
+		IsActive:  isActive,
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}
+	if err := db.Create(user).Error; err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	if err := db.Model(&auth.User{}).Where("id = ?", userID).UpdateColumn("is_active", isActive).Error; err != nil {
+		t.Fatalf("sync user is_active: %v", err)
+	}
+	if err := db.Create(&auth.StaffProfile{
+		UserID:    userID,
+		ShortName: firstName,
+		Note:      note,
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}).Error; err != nil {
+		t.Fatalf("create staff profile: %v", err)
+	}
+
+	return userID
+}
+
+func intPtrContactRepo(v int) *int { return &v }
+
+func strPtrContactRepo(v string) *string { return &v }
diff --git a/internal/repository/mysql/db.go b/internal/repository/mysql/db.go
new file mode 100644
index 0000000..f9d9ae7
--- /dev/null
+++ b/internal/repository/mysql/db.go
@@ -0,0 +1,828 @@
+package mysql
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"strings"
+	"time"
+
+	"gorm.io/driver/mysql"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+	"gorm.io/gorm/logger"
+
+	"wucher/internal/config"
+	actionsignoff "wucher/internal/domain/action_signoff"
+	otherperson "wucher/internal/domain/other_person"
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	airrescuechecklist "wucher/internal/domain/air_rescue_checklist"
+	"wucher/internal/domain/audit"
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/base"
+	beforeflightinspection "wucher/internal/domain/before_flight_inspection"
+	complaint "wucher/internal/domain/complaint"
+	"wucher/internal/domain/dul"
+	dutyroster "wucher/internal/domain/duty_roster"
+	easarelease "wucher/internal/domain/easa_release"
+	"wucher/internal/domain/facility"
+	"wucher/internal/domain/federal_state"
+	filemanager "wucher/internal/domain/file_manager"
+	fleethistory "wucher/internal/domain/fleet_history"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	"wucher/internal/domain/flight"
+	flightdata "wucher/internal/domain/flight_data"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	flightinspectionfilechecklist "wucher/internal/domain/flight_inspection_file_checklist"
+	flightprepcheck "wucher/internal/domain/flight_prep_check"
+	fmreport "wucher/internal/domain/fm_report"
+	"wucher/internal/domain/forces_present"
+	"wucher/internal/domain/health_insurance_companies"
+	"wucher/internal/domain/helicopter"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+	"wucher/internal/domain/hospital"
+	"wucher/internal/domain/icao"
+	insurancepatientdata "wucher/internal/domain/insurance_patient_data"
+	"wucher/internal/domain/land"
+	mastersettings "wucher/internal/domain/master_settings"
+	"wucher/internal/domain/mcf"
+	"wucher/internal/domain/medicine"
+	"wucher/internal/domain/mission"
+	"wucher/internal/domain/opc"
+	"wucher/internal/domain/operation"
+	patientdata "wucher/internal/domain/patient_data"
+	reserveac "wucher/internal/domain/reserve_ac"
+	takeover "wucher/internal/domain/takeover"
+	"wucher/internal/domain/transient"
+	"wucher/internal/domain/vocation"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func Connect(cfg config.MySQLConfig) (*gorm.DB, error) {
+	if cfg.DSN == "" {
+		return nil, errors.New("MYSQL_DSN is required")
+	}
+
+	db, err := gorm.Open(mysql.Open(cfg.DSN), &gorm.Config{
+		Logger: logger.New(
+			log.New(os.Stdout, "\r\n", log.LstdFlags),
+			logger.Config{
+				SlowThreshold:             200 * time.Millisecond,
+				LogLevel:                  logger.Warn,
+				IgnoreRecordNotFoundError: true,
+				Colorful:                  true,
+			},
+		),
+		NowFunc: func() time.Time {
+			return time.Now().UTC()
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return nil, err
+	}
+	sqlDB.SetMaxOpenConns(cfg.MaxOpenConns)
+	sqlDB.SetMaxIdleConns(cfg.MaxIdleConns)
+	sqlDB.SetConnMaxLifetime(cfg.ConnMaxLifetime)
+	sqlDB.SetConnMaxIdleTime(cfg.ConnMaxIdleTime)
+
+	return db, nil
+}
+
+func AutoMigrate(db *gorm.DB) error {
+	probe := newSchemaCache(db)
+
+	if db.Dialector.Name() == "mysql" &&
+		db.Migrator().HasColumn("flight_data", "hook_realeases") &&
+		!db.Migrator().HasColumn("flight_data", "hook_releases") {
+		if err := db.Exec("ALTER TABLE flight_data RENAME COLUMN hook_realeases TO hook_releases").Error; err != nil {
+			return err
+		}
+	}
+
+	if err := db.AutoMigrate(
+		&auth.Role{},
+		&auth.Permission{},
+		&auth.User{},
+		&auth.UserRole{},
+		&auth.EmailOutboxMessage{},
+		&auth.PilotProfile{},
+		&auth.DoctorProfile{},
+		&auth.AirRescuerProfile{},
+		&auth.TechnicianProfile{},
+		&auth.FlightAssistantProfile{},
+		&auth.StaffProfile{},
+		&auth.RolePermission{},
+		&auth.UserIdentity{},
+		&auth.UserMicrosoftOAuthToken{},
+		&auth.UserTOTP{},
+		&auth.UserEmailLoginOTP{},
+		&auth.UserWebAuthnCredential{},
+		&auth.PasswordResetToken{},
+		&auth.SecurityPINResetToken{},
+		&transient.TokenEntry{},
+		&transient.QueueIdempotencyRecord{},
+		&helicopter.Helicopter{},
+		&helicopterusage.HelicopterUsage{},
+		&flightinspection.FlightInspection{},
+		&flight.Flight{},
+		&flightdata.FlightData{},
+		&flightdata.HESLOFlight{},
+		&flightdata.HESLOSling{},
+		&flightdata.LoggingSling{},
+		&flightdata.HECFlight{},
+		&flightdata.HECSling{},
+		&flightdata.HECLoads{},
+		&mission.Mission{},
+		&mission.MissionFile{},
+		&reserveac.ReserveAc{},
+		&helicopterfile.HelicopterFile{},
+		&beforeflightinspection.BeforeFlightInspection{},
+		&afterflightinspection.AfterFlightInspection{},
+		&fmreport.Report{},
+		&fmreport.FleetHistory{},
+		&flightprepcheck.FlightPrepCheck{},
+		&flightinspectionfilechecklist.FlightInspectionFileChecklist{},
+		&takeover.TakeoverAc{},
+		&takeover.TakeoverRosterCrew{},
+		&takeover.TakeoverOtherPerson{},
+		&otherperson.OtherPerson{},
+		&takeover.TakeoverFile{},
+		&complaint.Complaint{},
+		&easarelease.EASARelease{},
+		&actionsignoff.ActionSignoff{},
+		&mcf.MaintenanceCheckFlight{},
+		&fleethistory.FleetHistory{},
+		&fleetstatus.FleetStatus{},
+		&fleetstatus.MaintenanceSchedule{},
+		&fleetstatus.FleetStatusFile{},
+		&fleetstatus.FleetStatusServiceLog{},
+		&facility.Facility{},
+		&filemanager.Folder{},
+		&filemanager.File{},
+		&filemanager.Attachment{},
+		&filemanager.FileUploadIntent{},
+		&filemanager.FileProcessingOutboxMessage{},
+		&filemanager.FileStatusRealtimeEvent{},
+		&base.BaseCategory{},
+		&base.Base{},
+		&base.BaseOperationalShiftTime{},
+		&base.BaseContactRole{},
+		&dul.DUL{},
+		&medicine.MedicineGroup{},
+		&medicine.MotorReaction{},
+		&medicine.MedicineMotorReaction{},
+		&medicine.Medicine{},
+		&vocation.Vocation{},
+		&opc.Opc{},
+		&forces_present.ForcesPresent{},
+		&hospital.Hospital{},
+		&health_insurance_companies.HealthInsuranceCompany{},
+		&federal_state.FederalState{},
+		&icao.ICAO{},
+		&land.Land{},
+		&operation.HEMSOperationalData{},
+		&operation.OperationalDataForcePresent{},
+		&operation.OperationalFile{},
+		&operation.HEMSOperationCategory{},
+		&operation.HEMSOperation{},
+		&mastersettings.MasterSettings{},
+		&mastersettings.MasterSettingValue{},
+		&dutyroster.DutyRoster{},
+		&dutyroster.DutyRosterCrew{},
+		&airrescuechecklist.AirRescuerChecklist{},
+		&airrescuechecklist.AirRescuerChecklistItem{},
+		&audit.AuditLog{},
+		&insurancepatientdata.InsurancePatientData{},
+		&patientdata.PatientData{},
+	); err != nil {
+		return err
+	}
+
+	if db.Dialector.Name() == "mysql" {
+		if err := ensureBaseOperationalShiftTimeColumns(db); err != nil {
+			return err
+		}
+		if err := ensureBaseDefaultShiftColumns(db); err != nil {
+			return err
+		}
+		if err := ensureHelicopterColumns(db); err != nil {
+			return err
+		}
+		if err := ensureHelicopterFileAttachmentColumns(db); err != nil {
+			return err
+		}
+		if err := ensureActionSignoffStandaloneFlightUnique(db); err != nil {
+			return err
+		}
+	}
+	if err := backfillFacilityCategories(db); err != nil {
+		return err
+	}
+
+	// AutoMigrate won't remove columns; explicitly drop deprecated columns.
+	deprecatedColumns := []struct {
+		model  any
+		column string
+	}{
+		{model: &helicopter.Helicopter{}, column: "maintenance"},
+		{model: &helicopter.Helicopter{}, column: "counter"},
+		{model: &flightinspection.FlightInspection{}, column: "helicopter_id"},
+		{model: &flightinspection.FlightInspection{}, column: "operation_id"},
+		{model: "flights", column: "mission_type"},
+		{model: &complaint.Complaint{}, column: "mcf_required"},
+		{model: &complaint.Complaint{}, column: "mcf_decided_at"},
+		{model: &complaint.Complaint{}, column: "mcf_decided_by"},
+		{model: &complaint.Complaint{}, column: "mcf_completed_at"},
+		{model: &complaint.Complaint{}, column: "mcf_result"},
+		{model: &complaint.Complaint{}, column: "mcf_notes"},
+		{model: &mcf.MaintenanceCheckFlight{}, column: "flight_inspection_id"},
+		{model: &complaint.Complaint{}, column: "flight_inspection_id"},
+		{model: &easarelease.EASARelease{}, column: "flight_inspection_id"},
+		{model: &complaint.Complaint{}, column: "action_signed_at"},
+		{model: &complaint.Complaint{}, column: "action_signed_by"},
+		{model: &actionsignoff.ActionSignoff{}, column: "action_taken"},
+		{model: &actionsignoff.ActionSignoff{}, column: "created_by"},
+		{model: &actionsignoff.ActionSignoff{}, column: "updated_by"},
+		{model: &actionsignoff.ActionSignoff{}, column: "deleted_at"},
+		{model: &actionsignoff.ActionSignoff{}, column: "deleted_by"},
+		// EASA maintenance program field removed from the release + its fm-report snapshot.
+		{model: &easarelease.EASARelease{}, column: "easa_maintenance_program"},
+		{model: &fmreport.FleetHistory{}, column: "easa_maintenance_program"},
+		// medical_license_no, license_issued_at, and license_expired_at removed from doctor_profiles;
+		// is_chief_physician_in_charge removed from air_rescuer_profiles.
+		{model: &auth.DoctorProfile{}, column: "medical_license_no"},
+		{model: &auth.DoctorProfile{}, column: "license_issued_at"},
+		{model: &auth.DoctorProfile{}, column: "license_expired_at"},
+		{model: &auth.AirRescuerProfile{}, column: "is_chief_physician_in_charge"},
+	}
+	if db.Dialector.Name() == "mysql" {
+
+		deprecatedConstraints := []struct{ table, name string }{
+			{"complaints", "fk_complaints_flight_inspection"},
+			{"easa_releases", "fk_easa_releases_flight_inspection"},
+			{"maintenance_check_flights", "fk_maintenance_check_flights_flight_inspection"},
+		}
+		for _, fc := range deprecatedConstraints {
+			if db.Migrator().HasConstraint(fc.table, fc.name) {
+				if err := db.Migrator().DropConstraint(fc.table, fc.name); err != nil {
+					return err
+				}
+			}
+		}
+		for _, item := range deprecatedColumns {
+			if !probe.HasColumn(item.model, item.column) {
+				continue
+			}
+			if err := db.Migrator().DropColumn(item.model, item.column); err != nil {
+				return err
+			}
+		}
+		if db.Migrator().HasConstraint("patient_data", "fk_patient_data_place") {
+			if err := db.Migrator().DropConstraint("patient_data", "fk_patient_data_place"); err != nil {
+				return err
+			}
+		}
+		if probe.HasColumn("patient_data", "place_id") {
+			if err := db.Migrator().DropColumn("patient_data", "place_id"); err != nil {
+				return err
+			}
+		}
+	}
+	if probe.HasTable("places") {
+		if err := db.Migrator().DropTable("places"); err != nil {
+			return err
+		}
+	}
+
+	// Flight prep checks refactor: move from dynamic item rows to static boolean fields.
+	if db.Migrator().HasConstraint(&flightprepcheck.FlightPrepCheck{}, "fk_flight_prep_checks_flight_prep_item") {
+		if err := db.Migrator().DropConstraint(&flightprepcheck.FlightPrepCheck{}, "fk_flight_prep_checks_flight_prep_item"); err != nil {
+			return err
+		}
+	}
+	if db.Migrator().HasIndex(&flightprepcheck.FlightPrepCheck{}, "uk_flight_prep_checks_inspection_item") {
+		if err := db.Migrator().DropIndex(&flightprepcheck.FlightPrepCheck{}, "uk_flight_prep_checks_inspection_item"); err != nil {
+			return err
+		}
+	}
+	if db.Migrator().HasIndex(&flightprepcheck.FlightPrepCheck{}, "idx_flight_prep_checks_flight_inspection_sorted") {
+		if err := db.Migrator().DropIndex(&flightprepcheck.FlightPrepCheck{}, "idx_flight_prep_checks_flight_inspection_sorted"); err != nil {
+			return err
+		}
+	}
+	if probe.HasColumn(&flightprepcheck.FlightPrepCheck{}, "flight_prep_item_id") {
+		if err := db.Migrator().DropColumn(&flightprepcheck.FlightPrepCheck{}, "flight_prep_item_id"); err != nil {
+			return err
+		}
+	}
+	if probe.HasColumn(&flightprepcheck.FlightPrepCheck{}, "is_done") {
+		if err := db.Migrator().DropColumn(&flightprepcheck.FlightPrepCheck{}, "is_done"); err != nil {
+			return err
+		}
+	}
+	if probe.HasColumn(&flightprepcheck.FlightPrepCheck{}, "note") {
+		if err := db.Migrator().DropColumn(&flightprepcheck.FlightPrepCheck{}, "note"); err != nil {
+			return err
+		}
+	}
+	if !probe.HasColumn(&flightprepcheck.FlightPrepCheck{}, "notam_briefing") {
+		if err := db.Migrator().AddColumn(&flightprepcheck.FlightPrepCheck{}, "NOTAMBriefing"); err != nil {
+			return err
+		}
+	}
+	if !probe.HasColumn(&flightprepcheck.FlightPrepCheck{}, "weather_briefing") {
+		if err := db.Migrator().AddColumn(&flightprepcheck.FlightPrepCheck{}, "WeatherBriefing"); err != nil {
+			return err
+		}
+	}
+	if !probe.HasColumn(&flightprepcheck.FlightPrepCheck{}, "operational_flight_plan") {
+		if err := db.Migrator().AddColumn(&flightprepcheck.FlightPrepCheck{}, "OperationalFlightPlan"); err != nil {
+			return err
+		}
+	}
+	if !db.Migrator().HasIndex(&flightprepcheck.FlightPrepCheck{}, "uk_flight_prep_checks_inspection") {
+		if err := db.Migrator().CreateIndex(&flightprepcheck.FlightPrepCheck{}, "uk_flight_prep_checks_inspection"); err != nil {
+			return err
+		}
+	}
+
+	// Rename legacy duty roster tables to neutral names.
+	if probe.HasTable("hems_duty_rosters") && !probe.HasTable("duty_rosters") {
+		if err := db.Exec("RENAME TABLE hems_duty_rosters TO duty_rosters").Error; err != nil {
+			return err
+		}
+	}
+	if probe.HasTable("hems_duty_roster_crews") && !probe.HasTable("duty_roster_crews") {
+		if err := db.Exec("RENAME TABLE hems_duty_roster_crews TO duty_roster_crews").Error; err != nil {
+			return err
+		}
+	}
+
+	// Rename legacy duty roster base column to general name.
+	if probe.HasColumn(&dutyroster.DutyRoster{}, "hems_base_id") && !probe.HasColumn(&dutyroster.DutyRoster{}, "base_id") {
+		if err := db.Exec("ALTER TABLE duty_rosters RENAME COLUMN hems_base_id TO base_id").Error; err != nil {
+			return err
+		}
+	}
+
+	if err := db.Exec("UPDATE users SET username = NULL WHERE username IS NOT NULL AND TRIM(username) = ''").Error; err != nil {
+		return err
+	}
+	if db.Dialector.Name() == "mysql" && probe.HasColumn(&auth.User{}, "username") {
+		if err := db.Exec("ALTER TABLE users MODIFY COLUMN username varchar(100) NULL").Error; err != nil {
+			return err
+		}
+	}
+
+	if err := backfillUserRoles(db); err != nil {
+		return err
+	}
+	if err := backfillBaseCategories(db); err != nil {
+		return err
+	}
+	if err := backfillMissionTypes(db); err != nil {
+		return err
+	}
+	if err := backfillPermissionRequiresPIN(db); err != nil {
+		return err
+	}
+	if err := alignFlightDataHospitalConstraints(db); err != nil {
+		return err
+	}
+	if err := ensureFlightDataPilotNullable(db); err != nil {
+		return err
+	}
+	if err := ensureFlightDataStatusColumn(db); err != nil {
+		return err
+	}
+	if err := ensureMissionTimeColumns(db); err != nil {
+		return err
+	}
+	if db.Dialector.Name() == "mysql" {
+		if err := db.Exec("ALTER TABLE flights MODIFY COLUMN mission_code varchar(64) NULL").Error; err != nil {
+			return err
+		}
+		if err := db.Exec("UPDATE flights SET mission_code = NULL WHERE mission_code IS NOT NULL AND TRIM(mission_code) = ''").Error; err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// ensureActionSignoffStandaloneFlightUnique enforces one standalone (complaint-independent)
+// sign-off per flight via a functional unique index: the key is flight_id for standalone
+// rows (complaint_id IS NULL) and NULL for complaint-linked rows (which are deduped by
+// uidx_action_signoffs_complaint_id instead). Requires MySQL 8.0.13+ (functional index).
+func ensureActionSignoffStandaloneFlightUnique(db *gorm.DB) error {
+	if !db.Migrator().HasTable(&actionsignoff.ActionSignoff{}) {
+		return nil
+	}
+	if db.Migrator().HasIndex(&actionsignoff.ActionSignoff{}, "uidx_action_signoffs_standalone_flight") {
+		return nil
+	}
+	return db.Exec(
+		"CREATE UNIQUE INDEX uidx_action_signoffs_standalone_flight " +
+			"ON action_signoffs ((IF(complaint_id IS NULL, flight_id, NULL)))",
+	).Error
+}
+
+func ensureBaseOperationalShiftTimeColumns(db *gorm.DB) error {
+	if !db.Migrator().HasTable(&base.BaseOperationalShiftTime{}) {
+		return nil
+	}
+	if !db.Migrator().HasColumn(&base.BaseOperationalShiftTime{}, "DateStart") {
+		if err := db.Exec(`ALTER TABLE base_operational_shift_times ADD COLUMN date_start DATE NULL`).Error; err != nil {
+			return err
+		}
+	}
+	if !db.Migrator().HasColumn(&base.BaseOperationalShiftTime{}, "DateEnd") {
+		if err := db.Exec(`ALTER TABLE base_operational_shift_times ADD COLUMN date_end DATE NULL`).Error; err != nil {
+			return err
+		}
+	}
+	if db.Migrator().HasColumn("base_operational_shift_times", "operation_date") {
+		if err := db.Exec(`
+			UPDATE base_operational_shift_times
+			SET date_start = COALESCE(date_start, operation_date),
+			    date_end = COALESCE(date_end, operation_date)
+			WHERE deleted_at IS NULL
+		`).Error; err != nil {
+			return err
+		}
+		if db.Migrator().HasConstraint(&base.BaseOperationalShiftTime{}, "fk_base_operational_shift_times_base") {
+			if err := db.Exec(`ALTER TABLE base_operational_shift_times DROP FOREIGN KEY fk_base_operational_shift_times_base`).Error; err != nil {
+				return err
+			}
+		}
+		if db.Migrator().HasIndex(&base.BaseOperationalShiftTime{}, "idx_base_operational_shift_times_base_date") {
+			if err := db.Migrator().DropIndex(&base.BaseOperationalShiftTime{}, "idx_base_operational_shift_times_base_date"); err != nil {
+				return err
+			}
+		}
+		if err := db.Exec(`ALTER TABLE base_operational_shift_times DROP COLUMN operation_date`).Error; err != nil {
+			return err
+		}
+		if err := db.Migrator().CreateIndex(&base.BaseOperationalShiftTime{}, "idx_base_operational_shift_times_base_date"); err != nil {
+			return err
+		}
+		if err := db.Exec(`
+			ALTER TABLE base_operational_shift_times
+			ADD CONSTRAINT fk_base_operational_shift_times_base
+			FOREIGN KEY (base_id) REFERENCES bases(id)
+			ON UPDATE CASCADE
+			ON DELETE CASCADE
+		`).Error; err != nil {
+			return err
+		}
+	}
+	return db.Exec(`
+		ALTER TABLE base_operational_shift_times
+			MODIFY COLUMN date_start DATE NULL,
+			MODIFY COLUMN date_end DATE NULL,
+			MODIFY COLUMN shift_start TIME NULL,
+			MODIFY COLUMN shift_end TIME NULL
+	`).Error
+}
+
+func ensureBaseDefaultShiftColumns(db *gorm.DB) error {
+	if !db.Migrator().HasTable(&base.Base{}) {
+		return nil
+	}
+	if !db.Migrator().HasColumn(&base.Base{}, "DefaultStartTimeType") {
+		if err := db.Exec(`ALTER TABLE bases ADD COLUMN default_start_time_type VARCHAR(16) NOT NULL DEFAULT 'FIXED'`).Error; err != nil {
+			return err
+		}
+	}
+	if !db.Migrator().HasColumn(&base.Base{}, "DefaultEndTimeType") {
+		if err := db.Exec(`ALTER TABLE bases ADD COLUMN default_end_time_type VARCHAR(16) NOT NULL DEFAULT 'FIXED'`).Error; err != nil {
+			return err
+		}
+	}
+	return db.Exec(`
+		ALTER TABLE bases
+			MODIFY COLUMN default_shift_start TIME NULL,
+			MODIFY COLUMN default_shift_end TIME NULL
+	`).Error
+}
+
+func alignFlightDataHospitalConstraints(db *gorm.DB) error {
+	if db == nil || db.Dialector.Name() != "mysql" {
+		return nil
+	}
+	if err := alignFlightDataHospitalConstraint(db, "from_hospital_id", "FromHospital", "fk_flight_data_from_hospital"); err != nil {
+		return err
+	}
+	if err := alignFlightDataHospitalConstraint(db, "to_hospital_id", "ToHospital", "fk_flight_data_to_hospital"); err != nil {
+		return err
+	}
+	return nil
+}
+
+func alignFlightDataHospitalConstraint(db *gorm.DB, column, association, constraintName string) error {
+	type foreignKeyInfo struct {
+		ConstraintName      string `gorm:"column:constraint_name"`
+		ReferencedTableName string `gorm:"column:referenced_table_name"`
+	}
+
+	var info foreignKeyInfo
+	err := db.Table("information_schema.key_column_usage").
+		Select("constraint_name, referenced_table_name").
+		Where("table_schema = DATABASE() AND table_name = ? AND column_name = ? AND referenced_table_name IS NOT NULL", "flight_data", column).
+		Order("ordinal_position ASC").
+		Limit(1).
+		Scan(&info).Error
+	if err != nil {
+		return err
+	}
+
+	if info.ReferencedTableName == "no_icao_codes" {
+		return nil
+	}
+
+	if info.ConstraintName != "" {
+		if err := db.Exec("ALTER TABLE `flight_data` DROP FOREIGN KEY `" + info.ConstraintName + "`").Error; err != nil {
+			return err
+		}
+	}
+
+	return db.Migrator().CreateConstraint(&flightdata.FlightData{}, association)
+}
+
+func ensureFlightDataPilotNullable(db *gorm.DB) error {
+	if db == nil || db.Dialector.Name() != "mysql" {
+		return nil
+	}
+	if !db.Migrator().HasTable(&flightdata.FlightData{}) {
+		return nil
+	}
+	type columnInfo struct {
+		IsNullable string `gorm:"column:is_nullable"`
+	}
+	var info columnInfo
+	if err := db.Table("information_schema.columns").
+		Select("is_nullable").
+		Where("table_schema = DATABASE() AND table_name = ? AND column_name = ?", "flight_data", "co_pilot_id").
+		Limit(1).
+		Scan(&info).Error; err != nil {
+		return err
+	}
+	// Column missing (e.g. not yet created by migrations) or already nullable: nothing to do.
+	if strings.TrimSpace(info.IsNullable) == "" || strings.EqualFold(strings.TrimSpace(info.IsNullable), "YES") {
+		return nil
+	}
+	return db.Exec("ALTER TABLE flight_data MODIFY COLUMN co_pilot_id binary(16) NULL").Error
+}
+
+func ensureFlightDataStatusColumn(db *gorm.DB) error {
+	if db == nil {
+		return nil
+	}
+	if !db.Migrator().HasTable(&flightdata.FlightData{}) {
+		return nil
+	}
+	if !db.Migrator().HasColumn(&flightdata.FlightData{}, "status") {
+		addColumnSQL := "ALTER TABLE flight_data ADD COLUMN status varchar(20) NOT NULL DEFAULT 'in_progress'"
+		if db.Dialector.Name() == "mysql" {
+			addColumnSQL = "ALTER TABLE flight_data ADD COLUMN status varchar(20) NOT NULL DEFAULT 'in_progress' AFTER id"
+		}
+		if err := db.Exec(addColumnSQL).Error; err != nil {
+			return err
+		}
+	}
+	if err := db.Exec("UPDATE flight_data SET status = 'in_progress' WHERE status IS NULL OR TRIM(status) = '' OR status IN ('on_going', 'on_progress')").Error; err != nil {
+		return err
+	}
+	return db.Exec("UPDATE flight_data SET status = 'completed' WHERE status = 'complete'").Error
+}
+
+func ensureMissionTimeColumns(db *gorm.DB) error {
+	if db == nil {
+		return nil
+	}
+	if !db.Migrator().HasTable(&mission.Mission{}) {
+		return nil
+	}
+	if db.Dialector.Name() != "mysql" {
+		return nil
+	}
+	return db.Exec(`
+		ALTER TABLE missions
+			MODIFY COLUMN start_time TIME NULL,
+			MODIFY COLUMN end_time TIME NULL
+	`).Error
+}
+
+func ensureHelicopterColumns(db *gorm.DB) error {
+	if !db.Migrator().HasTable(&helicopter.Helicopter{}) {
+		return nil
+	}
+	if !db.Migrator().HasColumn(&helicopter.Helicopter{}, "DeletedAt") {
+		if err := db.Exec(`ALTER TABLE helicopters ADD COLUMN deleted_at DATETIME(6) NULL AFTER updated_at`).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func ensureHelicopterFileAttachmentColumns(db *gorm.DB) error {
+	if db == nil || db.Dialector.Name() != "mysql" {
+		return nil
+	}
+	if !db.Migrator().HasTable(&helicopterfile.HelicopterFile{}) {
+		return nil
+	}
+	if !db.Migrator().HasColumn(&helicopterfile.HelicopterFile{}, "SourceFileID") {
+		if err := db.Exec("ALTER TABLE helicopter_files ADD COLUMN source_file_id binary(16) NULL AFTER file_attachment_id").Error; err != nil {
+			return err
+		}
+	}
+	return db.Exec("ALTER TABLE helicopter_files MODIFY COLUMN file_attachment_id binary(16) NULL").Error
+}
+
+func backfillBaseCategories(db *gorm.DB) error {
+	now := time.Now().UTC()
+	seeds := []struct {
+		key  string
+		name string
+	}{
+		{key: base.CategoryKeyRegular, name: "Regular"},
+		{key: base.CategoryKeyHEMS, name: "HEMS"},
+	}
+	for _, seed := range seeds {
+		if err := db.Exec(
+			`INSERT INTO base_categories (id, `+"`key`"+`, name, created_at, updated_at)
+			 SELECT ?, ?, ?, ?, ?
+			 WHERE NOT EXISTS (
+				 SELECT 1 FROM base_categories WHERE `+"`key`"+` = ?
+			 )`,
+			uuidv7.MustBytes(),
+			seed.key,
+			seed.name,
+			now,
+			now,
+			seed.key,
+		).Error; err != nil {
+			return fmt.Errorf("seed base category %q: %w", seed.key, err)
+		}
+	}
+
+	var regular struct {
+		ID []byte `gorm:"column:id"`
+	}
+	if err := db.Table("base_categories").
+		Select("id").
+		Where("`key` = ?", base.CategoryKeyRegular).
+		Take(&regular).Error; err != nil {
+		return err
+	}
+
+	return db.Exec(
+		"UPDATE bases SET base_category_id = ? WHERE base_category_id IS NULL OR LENGTH(base_category_id) = 0",
+		regular.ID,
+	).Error
+}
+
+func backfillFacilityCategories(db *gorm.DB) error {
+	if db == nil {
+		return nil
+	}
+
+	mappings := map[string]string{
+		"fuel-truck":     "heslo-rope-label",
+		"heslo-sling":    "heslo-rope-length",
+		"logging-sling":  "heslo-hook",
+		"hec-sling":      "hec-rope-label",
+		"hems-hec-sling": "hec-rope-length",
+	}
+
+	for oldValue, newValue := range mappings {
+		if err := db.Exec(
+			"UPDATE facilities SET category = ? WHERE LOWER(TRIM(category)) = ?",
+			newValue,
+			oldValue,
+		).Error; err != nil {
+			return fmt.Errorf("backfill facility category %q -> %q: %w", oldValue, newValue, err)
+		}
+	}
+
+	return nil
+}
+
+func backfillUserRoles(db *gorm.DB) error {
+	var users []struct {
+		ID     []byte `gorm:"column:id"`
+		RoleID []byte `gorm:"column:role_id"`
+	}
+	if err := db.Table("users").
+		Select("id, role_id").
+		Where("role_id IS NOT NULL").
+		Find(&users).Error; err != nil {
+		return err
+	}
+	if len(users) == 0 {
+		return nil
+	}
+
+	items := make([]auth.UserRole, 0, len(users))
+	for i := range users {
+		if len(users[i].ID) != 16 || len(users[i].RoleID) != 16 {
+			continue
+		}
+		items = append(items, auth.UserRole{
+			UserID: append([]byte(nil), users[i].ID...),
+			RoleID: append([]byte(nil), users[i].RoleID...),
+		})
+	}
+	if len(items) == 0 {
+		return nil
+	}
+
+	return db.Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "user_id"}, {Name: "role_id"}},
+		DoNothing: true,
+	}).Create(&items).Error
+}
+
+func backfillPermissionRequiresPIN(db *gorm.DB) error {
+	// Intentionally no-op.
+	// Do not override existing permissions.requires_pin values on startup.
+	// Source of truth for requires_pin is the database row itself.
+	_ = db
+	return nil
+}
+
+func backfillMissionTypes(db *gorm.DB) error {
+	categories := []struct {
+		key  string
+		name string
+		id   []byte
+	}{
+		{key: "HEMS", name: "HEMS", id: uuidv7.MustBytes()},
+		{key: "CAT", name: "CAT", id: uuidv7.MustBytes()},
+		{key: "SPO", name: "SPO", id: uuidv7.MustBytes()},
+		{key: "NCO", name: "NCO", id: uuidv7.MustBytes()},
+	}
+
+	for i := range categories {
+		if err := db.Exec(
+			`INSERT INTO mission_categories (id, code_type, name)
+			 SELECT ?, ?, ?
+			 WHERE NOT EXISTS (
+				 SELECT 1 FROM mission_categories WHERE code_type = ?
+			 )`,
+			categories[i].id,
+			categories[i].key,
+			categories[i].name,
+			categories[i].key,
+		).Error; err != nil {
+			return fmt.Errorf("seed mission category %q: %w", categories[i].key, err)
+		}
+	}
+
+	var hems struct {
+		ID []byte `gorm:"column:id"`
+	}
+	if err := db.Table("mission_categories").
+		Select("id").
+		Where("code_type = ?", "HEMS").
+		Take(&hems).Error; err != nil {
+		return err
+	}
+
+	subtypes := []struct {
+		code     string
+		name     string
+		taskName string
+		id       []byte
+	}{
+		{code: "PRIM", name: "Primary mission", taskName: "Primary mission task", id: uuidv7.MustBytes()},
+		{code: "SECONDARY", name: "Secondary mission", taskName: "Secondary mission task", id: uuidv7.MustBytes()},
+	}
+	for i := range subtypes {
+		if err := db.Exec(
+			`INSERT INTO mission_subcategories (id, mission_category_id, sub_type, name, task_name)
+			 SELECT ?, ?, ?, ?, ?
+			 WHERE NOT EXISTS (
+				 SELECT 1 FROM mission_subcategories WHERE mission_category_id = ? AND sub_type = ?
+			 )`,
+			subtypes[i].id,
+			hems.ID,
+			subtypes[i].code,
+			subtypes[i].name,
+			subtypes[i].taskName,
+			hems.ID,
+			subtypes[i].code,
+		).Error; err != nil {
+			return fmt.Errorf("seed mission subtype %q: %w", subtypes[i].code, err)
+		}
+	}
+	return nil
+}
diff --git a/internal/repository/mysql/db_test.go b/internal/repository/mysql/db_test.go
new file mode 100644
index 0000000..21dca9a
--- /dev/null
+++ b/internal/repository/mysql/db_test.go
@@ -0,0 +1,332 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/config"
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/base"
+	facility "wucher/internal/domain/facility"
+	filemanager "wucher/internal/domain/file_manager"
+	flightdata "wucher/internal/domain/flight_data"
+	"wucher/internal/domain/helicopter"
+	"wucher/internal/domain/mission"
+	"wucher/internal/domain/transient"
+)
+
+func findMySQLDSNForTest() (string, bool) {
+	if v := strings.TrimSpace(os.Getenv("MYSQL_DSN")); v != "" {
+		return v, true
+	}
+
+	dir, err := os.Getwd()
+	if err != nil {
+		return "", false
+	}
+	for i := 0; i < 8; i++ {
+		envPath := filepath.Join(dir, ".env")
+		raw, err := os.ReadFile(envPath)
+		if err == nil {
+			lines := strings.Split(string(raw), "\n")
+			for _, line := range lines {
+				line = strings.TrimSpace(line)
+				if line == "" || strings.HasPrefix(line, "#") {
+					continue
+				}
+				if strings.HasPrefix(line, "MYSQL_DSN=") {
+					v := strings.TrimSpace(strings.TrimPrefix(line, "MYSQL_DSN="))
+					v = strings.Trim(v, `"'`)
+					if v != "" {
+						return v, true
+					}
+				}
+			}
+		}
+
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			break
+		}
+		dir = parent
+	}
+	return "", false
+}
+
+func openDBTestSQLite(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:db_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	return db
+}
+
+func TestConnect(t *testing.T) {
+	t.Run("missing dsn", func(t *testing.T) {
+		if _, err := Connect(config.MySQLConfig{}); err == nil {
+			t.Fatalf("expected missing dsn error")
+		}
+	})
+
+	t.Run("invalid dsn", func(t *testing.T) {
+		_, err := Connect(config.MySQLConfig{
+			DSN: "root:pass@tcp(127.0.0.1:1)/wucher?loc=%",
+		})
+		if err == nil {
+			t.Fatalf("expected connect error for invalid DSN")
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		dsn, ok := findMySQLDSNForTest()
+		if !ok {
+			t.Skip("MYSQL_DSN not found in env or .env")
+		}
+
+		cfg := config.MySQLConfig{
+			DSN:             dsn,
+			MaxOpenConns:    7,
+			MaxIdleConns:    5,
+			ConnMaxLifetime: 2 * time.Minute,
+			ConnMaxIdleTime: time.Minute,
+		}
+		db, err := Connect(cfg)
+		if err != nil {
+			t.Skipf("skip connect success branch (mysql unavailable): %v", err)
+		}
+		sqlDB, err := db.DB()
+		if err != nil {
+			t.Fatalf("db.DB error: %v", err)
+		}
+		defer sqlDB.Close()
+
+		if err := sqlDB.PingContext(context.Background()); err != nil {
+			t.Fatalf("ping mysql: %v", err)
+		}
+		if got := sqlDB.Stats().MaxOpenConnections; got != cfg.MaxOpenConns {
+			t.Fatalf("unexpected max open conns, got=%d want=%d", got, cfg.MaxOpenConns)
+		}
+	})
+}
+
+func TestAutoMigrate(t *testing.T) {
+	t.Run("success and base category backfill", func(t *testing.T) {
+		db := openDBTestSQLite(t)
+
+		if err := db.Exec(`CREATE TABLE helicopters (
+			id BLOB PRIMARY KEY,
+			designation TEXT,
+			identifier TEXT,
+			report_sequence INTEGER DEFAULT 0,
+			type TEXT,
+			counter INTEGER DEFAULT 0,
+			maintenance TEXT
+		)`).Error; err != nil {
+			t.Fatalf("create legacy helicopters table: %v", err)
+		}
+		if err := db.Exec(`CREATE TABLE bases (
+			id BLOB PRIMARY KEY,
+			base TEXT
+		)`).Error; err != nil {
+			t.Fatalf("create legacy bases table: %v", err)
+		}
+		if err := db.Exec(`INSERT INTO bases(id, base) VALUES (X'00112233445566778899aabbccddeeff', 'Legacy Base')`).Error; err != nil {
+			t.Fatalf("seed legacy bases row: %v", err)
+		}
+		if err := AutoMigrate(db); err != nil {
+			t.Fatalf("auto migrate: %v", err)
+		}
+		if db.Migrator().HasColumn(&helicopter.Helicopter{}, "maintenance") {
+			t.Fatalf("expected deprecated helicopters.maintenance dropped")
+		}
+		if db.Migrator().HasColumn(&helicopter.Helicopter{}, "counter") {
+			t.Fatalf("expected deprecated helicopters.counter dropped")
+		}
+		if !db.Migrator().HasColumn(&helicopter.Helicopter{}, "foto_attachment_id") {
+			t.Fatalf("expected helicopters.foto_attachment_id migrated")
+		}
+		if !db.Migrator().HasTable(&base.BaseCategory{}) {
+			t.Fatalf("expected base_categories table migrated")
+		}
+		if !db.Migrator().HasColumn(&base.Base{}, "base_category_id") {
+			t.Fatalf("expected bases.base_category_id migrated")
+		}
+		if !db.Migrator().HasColumn(&base.Base{}, "latitude") {
+			t.Fatalf("expected bases.latitude migrated")
+		}
+		if !db.Migrator().HasColumn(&base.Base{}, "longitude") {
+			t.Fatalf("expected bases.longitude migrated")
+		}
+		if !db.Migrator().HasColumn(&base.Base{}, "default_shift_start") {
+			t.Fatalf("expected bases.default_shift_start migrated")
+		}
+		if !db.Migrator().HasColumn(&base.Base{}, "default_shift_end") {
+			t.Fatalf("expected bases.default_shift_end migrated")
+		}
+		if !db.Migrator().HasColumn(&base.Base{}, "foto_attachment_id") {
+			t.Fatalf("expected bases.foto_attachment_id migrated")
+		}
+		if !db.Migrator().HasColumn(&base.Base{}, "deleted_at") {
+			t.Fatalf("expected bases.deleted_at migrated")
+		}
+		if !db.Migrator().HasColumn(&base.Base{}, "deleted_by") {
+			t.Fatalf("expected bases.deleted_by migrated")
+		}
+		if !db.Migrator().HasTable(&base.BaseOperationalShiftTime{}) {
+			t.Fatalf("expected base_operational_shift_times table migrated")
+		}
+		if !db.Migrator().HasColumn(&base.BaseOperationalShiftTime{}, "base_id") {
+			t.Fatalf("expected base_operational_shift_times.base_id migrated")
+		}
+		if !db.Migrator().HasColumn(&base.BaseOperationalShiftTime{}, "date_start") {
+			t.Fatalf("expected base_operational_shift_times.date_start migrated")
+		}
+		if !db.Migrator().HasColumn(&base.BaseOperationalShiftTime{}, "date_end") {
+			t.Fatalf("expected base_operational_shift_times.date_end migrated")
+		}
+		if !db.Migrator().HasColumn(&base.BaseOperationalShiftTime{}, "start_time_type") {
+			t.Fatalf("expected base_operational_shift_times.start_time_type migrated")
+		}
+		if !db.Migrator().HasColumn(&base.BaseOperationalShiftTime{}, "end_time_type") {
+			t.Fatalf("expected base_operational_shift_times.end_time_type migrated")
+		}
+		if !db.Migrator().HasColumn(&mission.Mission{}, "start_time") {
+			t.Fatalf("expected missions.start_time migrated")
+		}
+		if !db.Migrator().HasColumn(&mission.Mission{}, "end_time") {
+			t.Fatalf("expected missions.end_time migrated")
+		}
+		var missingCategory int64
+		if err := db.Table("bases").
+			Where("base_category_id IS NULL OR LENGTH(base_category_id) = 0").
+			Count(&missingCategory).Error; err != nil {
+			t.Fatalf("count missing base category: %v", err)
+		}
+		if missingCategory != 0 {
+			t.Fatalf("expected all bases to have category, missing=%d", missingCategory)
+		}
+		var seededCategories int64
+		if err := db.Table("base_categories").
+			Where("`key` IN (?, ?)", base.CategoryKeyRegular, base.CategoryKeyHEMS).
+			Count(&seededCategories).Error; err != nil {
+			t.Fatalf("count seeded categories: %v", err)
+		}
+		if seededCategories != 2 {
+			t.Fatalf("expected regular+hems seeded categories, got=%d", seededCategories)
+		}
+		if !db.Migrator().HasTable(&auth.User{}) {
+			t.Fatalf("expected core tables migrated")
+		}
+		if !db.Migrator().HasTable(&auth.UserRole{}) {
+			t.Fatalf("expected user_roles table migrated")
+		}
+		if !db.Migrator().HasTable(&transient.TokenEntry{}) || !db.Migrator().HasTable(&transient.QueueIdempotencyRecord{}) {
+			t.Fatalf("expected transient runtime tables migrated")
+		}
+		if !db.Migrator().HasTable(&filemanager.Folder{}) || !db.Migrator().HasTable(&filemanager.File{}) {
+			t.Fatalf("expected file manager tables migrated")
+		}
+		if !db.Migrator().HasColumn(&auth.Permission{}, "requires_pin") {
+			t.Fatalf("expected permissions.requires_pin migrated")
+		}
+	})
+
+	t.Run("facility category backfill", func(t *testing.T) {
+		db := openDBTestSQLite(t)
+		if err := db.AutoMigrate(&facility.Facility{}); err != nil {
+			t.Fatalf("auto migrate facilities: %v", err)
+		}
+		for _, category := range []string{
+			"fuel-truck",
+			"heslo-sling",
+			"logging-sling",
+			"hec-sling",
+			"hems-hec-sling",
+		} {
+			if err := db.Create(&facility.Facility{Category: category, Name: category, Type: "Sling"}).Error; err != nil {
+				t.Fatalf("seed facility category %q: %v", category, err)
+			}
+		}
+		if err := backfillFacilityCategories(db); err != nil {
+			t.Fatalf("backfillFacilityCategories: %v", err)
+		}
+		expected := []string{
+			"heslo-rope-label",
+			"heslo-rope-length",
+			"heslo-hook",
+			"hec-rope-label",
+			"hec-rope-length",
+		}
+		for _, category := range expected {
+			var count int64
+			if err := db.Table("facilities").Where("category = ?", category).Count(&count).Error; err != nil {
+				t.Fatalf("count category %q: %v", category, err)
+			}
+			if count != 1 {
+				t.Fatalf("expected one row for category %q, got %d", category, count)
+			}
+		}
+	})
+
+	t.Run("auto migrate error when db closed", func(t *testing.T) {
+		db := openDBTestSQLite(t)
+		sqlDB, err := db.DB()
+		if err != nil {
+			t.Fatalf("db.DB: %v", err)
+		}
+		_ = sqlDB.Close()
+
+		if err := AutoMigrate(db); err == nil {
+			t.Fatalf("expected auto migrate error on closed DB")
+		}
+	})
+
+	t.Run("drop deprecated maintenance from legacy composite key schema", func(t *testing.T) {
+		db := openDBTestSQLite(t)
+
+		// Keep maintenance as part of PK to force drop-column failure on SQLite.
+		if err := db.Exec(`CREATE TABLE helicopters (
+			id BLOB NOT NULL,
+			maintenance TEXT NOT NULL,
+			designation TEXT,
+			identifier TEXT,
+			type TEXT,
+			report_sequence INTEGER DEFAULT 0,
+			PRIMARY KEY (id, maintenance)
+		)`).Error; err != nil {
+			t.Fatalf("create legacy helicopters table: %v", err)
+		}
+
+		if err := AutoMigrate(db); err != nil {
+			t.Fatalf("unexpected auto migrate error: %v", err)
+		}
+	})
+
+	t.Run("ensure flight data status column on legacy table", func(t *testing.T) {
+		db := openDBTestSQLite(t)
+		if err := db.Exec(`CREATE TABLE flight_data (
+			id BLOB PRIMARY KEY
+		)`).Error; err != nil {
+			t.Fatalf("create legacy flight_data table: %v", err)
+		}
+		if err := ensureFlightDataStatusColumn(db); err != nil {
+			t.Fatalf("ensure status column: %v", err)
+		}
+		if !db.Migrator().HasColumn(&flightdata.FlightData{}, "status") {
+			t.Fatal("expected flight_data.status column to exist")
+		}
+	})
+
+}
diff --git a/internal/repository/mysql/delete_guard.go b/internal/repository/mysql/delete_guard.go
new file mode 100644
index 0000000..56d462a
--- /dev/null
+++ b/internal/repository/mysql/delete_guard.go
@@ -0,0 +1,106 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"regexp"
+	"strings"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/apperrors"
+)
+
+type fkReferenceRow struct {
+	TableName  string `gorm:"column:table_name"`
+	ColumnName string `gorm:"column:column_name"`
+}
+
+var mysqlDeleteRefTableRegexp = regexp.MustCompile("fails \\(`[^`]+`\\.`([^`]+)`")
+
+func ensureNoReferenceBeforeDelete(ctx context.Context, db *gorm.DB, tableName string, id []byte) error {
+	if db == nil || db.Dialector == nil || db.Dialector.Name() != "mysql" {
+		return nil
+	}
+	if len(id) != 16 || strings.TrimSpace(tableName) == "" {
+		return nil
+	}
+
+	refs := make([]fkReferenceRow, 0)
+	err := db.WithContext(ctx).Raw(`
+SELECT kcu.TABLE_NAME AS table_name, kcu.COLUMN_NAME AS column_name
+FROM information_schema.KEY_COLUMN_USAGE kcu
+WHERE kcu.TABLE_SCHEMA = DATABASE()
+  AND kcu.REFERENCED_TABLE_SCHEMA = DATABASE()
+  AND kcu.REFERENCED_TABLE_NAME = ?
+  AND kcu.REFERENCED_COLUMN_NAME = 'id'
+`, tableName).Scan(&refs).Error
+	if err != nil {
+		return err
+	}
+
+	related := make([]string, 0)
+	for i := range refs {
+		query := fmt.Sprintf("SELECT 1 FROM `%s` WHERE `%s` = ? LIMIT 1", refs[i].TableName, refs[i].ColumnName)
+		var one int
+		rowErr := db.WithContext(ctx).Raw(query, id).Scan(&one).Error
+		if rowErr != nil {
+			return rowErr
+		}
+		if one == 1 {
+			related = append(related, moduleNameFromTable(refs[i].TableName))
+		}
+	}
+
+	if len(related) > 0 {
+		return apperrors.NewDeleteConflictError(related...)
+	}
+	return nil
+}
+
+func mapDeleteConstraintError(err error) error {
+	if err == nil {
+		return nil
+	}
+	if apperrors.IsDeleteConflict(err) {
+		return err
+	}
+	var mysqlErr *mysqldriver.MySQLError
+	if !strings.Contains(strings.ToLower(err.Error()), "foreign key") && !strings.Contains(strings.ToLower(err.Error()), "referenced") && !strings.Contains(strings.ToLower(err.Error()), "constraint") && !strings.Contains(strings.ToLower(err.Error()), "delete") {
+		return err
+	}
+	if !asMySQLError(err, &mysqlErr) || mysqlErr.Number != 1451 {
+		return err
+	}
+	if matches := mysqlDeleteRefTableRegexp.FindStringSubmatch(mysqlErr.Message); len(matches) > 1 {
+		return apperrors.NewDeleteConflictError(moduleNameFromTable(matches[1]))
+	}
+	return apperrors.NewDeleteConflictError()
+}
+
+func asMySQLError(err error, target **mysqldriver.MySQLError) bool {
+	if err == nil {
+		return false
+	}
+	return errors.As(err, target)
+}
+
+func moduleNameFromTable(tableName string) string {
+	tableName = strings.TrimSpace(tableName)
+	if tableName == "" {
+		return "another module"
+	}
+	switch tableName {
+	case "takeover_acs":
+		return "takeover"
+	case "base_operational_shift_times":
+		return "base operational shift times"
+	case "base_contact_roles":
+		return "base contact roles"
+	case "duls":
+		return "dul"
+	}
+	return strings.ReplaceAll(tableName, "_", " ")
+}
diff --git a/internal/repository/mysql/delete_guard_test.go b/internal/repository/mysql/delete_guard_test.go
new file mode 100644
index 0000000..7bcfcdf
--- /dev/null
+++ b/internal/repository/mysql/delete_guard_test.go
@@ -0,0 +1,22 @@
+package mysql
+
+import "testing"
+
+func TestModuleNameFromTable(t *testing.T) {
+	tests := []struct {
+		table string
+		want  string
+	}{
+		{table: "takeover_acs", want: "takeover"},
+		{table: "base_operational_shift_times", want: "base operational shift times"},
+		{table: "base_contact_roles", want: "base contact roles"},
+		{table: "duls", want: "dul"},
+		{table: "takeover_other_people", want: "takeover other people"},
+	}
+
+	for _, tc := range tests {
+		if got := moduleNameFromTable(tc.table); got != tc.want {
+			t.Fatalf("moduleNameFromTable(%q) = %q, want %q", tc.table, got, tc.want)
+		}
+	}
+}
diff --git a/internal/repository/mysql/dul_repo.go b/internal/repository/mysql/dul_repo.go
new file mode 100644
index 0000000..0cd4f21
--- /dev/null
+++ b/internal/repository/mysql/dul_repo.go
@@ -0,0 +1,145 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"wucher/internal/domain/dul"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type DULRepository struct {
+	db *gorm.DB
+}
+
+func NewDULRepository(db *gorm.DB) *DULRepository {
+	return &DULRepository{db: db}
+}
+
+func (r *DULRepository) WithTransaction(ctx context.Context, fn func(repo dul.Repository) error) error {
+	if fn == nil {
+		return nil
+	}
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		return fn(&DULRepository{db: tx})
+	})
+}
+
+func (r *DULRepository) Create(ctx context.Context, row *dul.DUL) error {
+	if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+		row.CreatedBy = actor
+		row.UpdatedBy = actor
+	}
+	return r.db.WithContext(ctx).Omit(clause.Associations).Create(row).Error
+}
+
+func (r *DULRepository) Update(ctx context.Context, row *dul.DUL) error {
+	if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+		row.UpdatedBy = actor
+	}
+	return r.db.WithContext(ctx).Omit(clause.Associations).Save(row).Error
+}
+
+func (r *DULRepository) Delete(ctx context.Context, id []byte) error {
+	updates := map[string]any{"deleted_at": time.Now().UTC()}
+	if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+		updates["deleted_by"] = actor
+		updates["updated_by"] = actor
+	}
+	return r.db.WithContext(ctx).Model(&dul.DUL{}).Where("id = ? AND deleted_at IS NULL", id).Updates(updates).Error
+}
+
+func (r *DULRepository) GetByID(ctx context.Context, id []byte) (*dul.DUL, error) {
+	var row dul.DUL
+	err := r.db.WithContext(ctx).
+		Preload("Base").
+		Preload("Base.BaseCategory").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	_ = r.loadImages(ctx, []*dul.DUL{&row})
+	return &row, nil
+}
+
+func (r *DULRepository) List(ctx context.Context, filter, sort string, limit, offset int, baseIDs [][]byte) ([]dul.DUL, int64, error) {
+	var rows []dul.DUL
+	var total int64
+
+	query := r.db.WithContext(ctx).Model(&dul.DUL{}).Where("deleted_at IS NULL")
+	if len(baseIDs) > 0 {
+		query = query.Where("base_id IN ?", baseIDs)
+	}
+	if s := strings.TrimSpace(filter); s != "" {
+		like := "%" + s + "%"
+		query = query.Where("name LIKE ? OR info LIKE ?", like, like)
+	}
+	if err := query.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if strings.TrimSpace(sort) != "" {
+		query = query.Order(sort)
+	} else {
+		query = query.Order("base_id ASC").Order("no ASC")
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Preload("Base").Preload("Base.BaseCategory").Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	ptrs := make([]*dul.DUL, 0, len(rows))
+	for i := range rows {
+		ptrs = append(ptrs, &rows[i])
+	}
+	_ = r.loadImages(ctx, ptrs)
+	return rows, total, nil
+}
+
+func (r *DULRepository) loadImages(ctx context.Context, rows []*dul.DUL) error {
+	if len(rows) == 0 {
+		return nil
+	}
+	refIDs := make([]string, 0, len(rows))
+	byRef := map[string]*dul.DUL{}
+	for _, row := range rows {
+		if row == nil || len(row.ID) != 16 {
+			continue
+		}
+		refID, _ := uuidv7.BytesToString(row.ID)
+		refIDs = append(refIDs, refID)
+		byRef[refID] = row
+		row.Images = nil
+	}
+	if len(refIDs) == 0 {
+		return nil
+	}
+	var attachments []filemanager.Attachment
+	if err := r.db.WithContext(ctx).
+		Preload("File").
+		Where("ref_type = ? AND ref_id IN ?", "dul", refIDs).
+		Order("sort_order ASC, created_at ASC").
+		Find(&attachments).Error; err != nil {
+		return err
+	}
+	for i := range attachments {
+		att := attachments[i]
+		row := byRef[att.RefID]
+		if row == nil {
+			continue
+		}
+		clone := att
+		row.Images = append(row.Images, &clone)
+	}
+	return nil
+}
diff --git a/internal/repository/mysql/duty_roster_repo.go b/internal/repository/mysql/duty_roster_repo.go
new file mode 100644
index 0000000..b9b94eb
--- /dev/null
+++ b/internal/repository/mysql/duty_roster_repo.go
@@ -0,0 +1,631 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	basedomain "wucher/internal/domain/base"
+	dutyroster "wucher/internal/domain/duty_roster"
+)
+
+type DutyRosterRepository struct {
+	db *gorm.DB
+}
+
+func NewDutyRosterRepository(db *gorm.DB) *DutyRosterRepository {
+	return &DutyRosterRepository{db: db}
+}
+
+func (r *DutyRosterRepository) InTx(ctx context.Context, fn func(txRepo dutyroster.TxRepository) error) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		return fn(&DutyRosterRepository{db: tx})
+	})
+}
+
+func (r *DutyRosterRepository) GetRosterByID(ctx context.Context, id []byte) (*dutyroster.DutyRoster, error) {
+	row := &dutyroster.DutyRoster{}
+	if err := r.db.WithContext(ctx).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Take(row).Error; err != nil {
+		return nil, err
+	}
+	return row, nil
+}
+
+func (r *DutyRosterRepository) LockRosterByID(ctx context.Context, id []byte) (*dutyroster.DutyRoster, error) {
+	row := &dutyroster.DutyRoster{}
+	if err := r.db.WithContext(ctx).
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Take(row).Error; err != nil {
+		return nil, err
+	}
+	return row, nil
+}
+
+func (r *DutyRosterRepository) CreateHeader(ctx context.Context, row *dutyroster.DutyRoster) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *DutyRosterRepository) UpdateHeader(ctx context.Context, row *dutyroster.DutyRoster) error {
+	updates := map[string]any{
+		"base_id":    row.BaseID,
+		"duty_date":  row.DutyDate,
+		"updated_by": row.UpdatedBy,
+	}
+	res := r.db.WithContext(ctx).Model(&dutyroster.DutyRoster{}).
+		Where("id = ? AND deleted_at IS NULL", row.ID).
+		Updates(updates)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *DutyRosterRepository) SoftDeleteHeader(ctx context.Context, id []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	res := r.db.WithContext(ctx).Model(&dutyroster.DutyRoster{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(map[string]any{"deleted_at": now, "deleted_by": deletedBy, "updated_by": deletedBy})
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *DutyRosterRepository) SoftDeleteCrewsByRosterID(ctx context.Context, rosterID []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	return r.db.WithContext(ctx).Model(&dutyroster.DutyRosterCrew{}).
+		Where("roster_id = ? AND deleted_at IS NULL", rosterID).
+		Updates(map[string]any{"deleted_at": now, "deleted_by": deletedBy, "updated_by": deletedBy}).Error
+}
+
+func (r *DutyRosterRepository) HardDeleteHeader(ctx context.Context, id []byte) error {
+	return r.db.WithContext(ctx).
+		Where("id = ?", id).
+		Delete(&dutyroster.DutyRoster{}).Error
+}
+
+func (r *DutyRosterRepository) HardDeleteCrewsByRosterID(ctx context.Context, rosterID []byte) error {
+	return r.db.WithContext(ctx).
+		Where("roster_id = ?", rosterID).
+		Delete(&dutyroster.DutyRosterCrew{}).Error
+}
+
+func (r *DutyRosterRepository) ListActiveCrewsByRosterID(ctx context.Context, rosterID []byte) ([]dutyroster.DutyRosterCrew, error) {
+	rows := make([]dutyroster.DutyRosterCrew, 0)
+	if err := r.db.WithContext(ctx).
+		Where("roster_id = ? AND deleted_at IS NULL", rosterID).
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *DutyRosterRepository) InsertCrew(ctx context.Context, row *dutyroster.DutyRosterCrew) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *DutyRosterRepository) CrewExists(ctx context.Context, row dutyroster.DutyRosterCrew) (bool, error) {
+	return crewExists(r.db.WithContext(ctx), row)
+}
+
+func (r *DutyRosterRepository) SoftDeleteCrewByUser(ctx context.Context, rosterID []byte, roleCode, crewType string, userID, updatedBy []byte) error {
+	return softReplaceCrewByUser(r.db.WithContext(ctx), rosterID, roleCode, crewType, userID, updatedBy)
+}
+
+func (r *DutyRosterRepository) FindRosterIDByBaseDate(ctx context.Context, baseID []byte, dutyDate time.Time) ([]byte, error) {
+	date := dateOnlyUTC(dutyDate)
+	var row dutyroster.DutyRoster
+	err := r.db.WithContext(ctx).
+		Where("base_id = ? AND duty_date = ? AND deleted_at IS NULL", baseID, date).
+		Take(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return row.ID, nil
+}
+
+func (r *DutyRosterRepository) FindRosterIDsByBaseDate(ctx context.Context, baseID []byte, dutyDate time.Time) ([][]byte, error) {
+	return findRosterIDsByBaseAndDate(r.db.WithContext(ctx), baseID, dutyDate)
+}
+
+func (r *DutyRosterRepository) MatchCrewByFilter(ctx context.Context, rosterIDs [][]byte, crew dutyroster.DutyRosterCrew) ([]dutyroster.DeletedCrewResult, error) {
+	return matchCrewByFilter(r.db.WithContext(ctx), rosterIDs, crew)
+}
+
+func (r *DutyRosterRepository) SoftDeleteCrewRows(ctx context.Context, rows []dutyroster.DeletedCrewResult, deletedBy []byte) error {
+	return softDeleteCrewByIDs(r.db.WithContext(ctx), rows, time.Now().UTC(), deletedBy)
+}
+
+func (r *DutyRosterRepository) SoftDeleteCrewForDate(ctx context.Context, baseID []byte, dutyDate time.Time, crew dutyroster.DutyRosterCrew, updatedBy []byte) error {
+	return softDeleteCrewForDate(r.db.WithContext(ctx), baseID, dutyDate, crew, time.Now().UTC(), updatedBy)
+}
+
+func (r *DutyRosterRepository) GetBaseDefaultShift(ctx context.Context, baseID []byte, baseType string) (string, error) {
+	hasDefaultShiftTypes := r.hasBaseDefaultShiftTypeColumns()
+	q := r.db.WithContext(ctx).
+		Table("bases b").
+		Where("b.id = ?", baseID)
+	if hasDefaultShiftTypes {
+		q = q.Select("b.default_start_time_type, b.default_end_time_type, b.default_shift_start, b.default_shift_end")
+	} else {
+		q = q.Select("b.default_shift_start, b.default_shift_end")
+	}
+	if strings.TrimSpace(baseType) != "" {
+		q = q.Joins("JOIN base_categories bc ON bc.id = b.base_category_id").
+			Where("bc.key = ?", rosterBaseCategoryKey(baseType))
+	}
+	var out struct {
+		DefaultStartTimeType string
+		DefaultEndTimeType   string
+		DefaultShiftStart    string
+		DefaultShiftEnd      string
+	}
+	err := q.Take(&out).Error
+	if err != nil {
+		return "", err
+	}
+	start := ""
+	end := ""
+	if !hasDefaultShiftTypes || normalizeBaseShiftTimeType(out.DefaultStartTimeType) == basedomain.ShiftTimeTypeFixed {
+		start = strings.TrimSpace(out.DefaultShiftStart)
+	}
+	if !hasDefaultShiftTypes || normalizeBaseShiftTimeType(out.DefaultEndTimeType) == basedomain.ShiftTimeTypeFixed {
+		end = strings.TrimSpace(out.DefaultShiftEnd)
+	}
+	if start != "" || end != "" {
+		switch {
+		case start != "" && end != "":
+			return start + "-" + end, nil
+		case start != "":
+			return start, nil
+		default:
+			return end, nil
+		}
+	}
+	return "", nil
+}
+
+func (r *DutyRosterRepository) GetHeaderByID(ctx context.Context, id []byte) (*dutyroster.HeaderView, error) {
+	return r.GetHeaderByIDByBaseType(ctx, id, "hems")
+}
+
+func (r *DutyRosterRepository) GetHeaderByIDByBaseType(ctx context.Context, id []byte, baseType string) (*dutyroster.HeaderView, error) {
+	categoryKey := rosterBaseCategoryKey(baseType)
+	out := &dutyroster.HeaderView{}
+	defaultShiftStartExpr := r.baseDefaultShiftDisplayExpr("hb", "default_shift_start", "default_start_time_type")
+	defaultShiftEndExpr := r.baseDefaultShiftDisplayExpr("hb", "default_shift_end", "default_end_time_type")
+	query := r.db.WithContext(ctx).
+		Table("duty_rosters hdr").
+		Select(`
+				hdr.id,
+				hdr.base_id AS base_id,
+				hb.base AS base_name,
+				hb.base_abbreviation,
+				`+defaultShiftStartExpr+` AS default_shift_start,
+				`+defaultShiftEndExpr+` AS default_shift_end,
+				'' AS helicopter_id,
+				'' AS helicopter_type,
+				'' AS helicopter_designation,
+				'' AS helicopter_identifier,
+			hdr.duty_date,
+			TIME_FORMAT(hdr.shift_start, '%H:%i:%s') AS shift_start,
+			TIME_FORMAT(hdr.shift_end, '%H:%i:%s') AS shift_end,
+				hdr.created_at,
+				hdr.created_by,
+				hdr.updated_at`).
+		Joins("LEFT JOIN bases hb ON hb.id = hdr.base_id").
+		Joins("LEFT JOIN base_categories bc ON bc.id = hb.base_category_id").
+		Where("hdr.id = ? AND hdr.deleted_at IS NULL", id)
+	err := query.Where("bc.key = ?", categoryKey).
+		Where("hb.id IS NOT NULL").
+		Take(out).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) || len(out.ID) == 0 {
+		out = &dutyroster.HeaderView{}
+		err = r.db.WithContext(ctx).
+			Table("duty_rosters hdr").
+			Select(`
+				hdr.id,
+				hdr.base_id AS base_id,
+				hb.base AS base_name,
+				hb.base_abbreviation,
+				`+defaultShiftStartExpr+` AS default_shift_start,
+				`+defaultShiftEndExpr+` AS default_shift_end,
+				'' AS helicopter_id,
+				'' AS helicopter_type,
+				'' AS helicopter_designation,
+				'' AS helicopter_identifier,
+			hdr.duty_date,
+			TIME_FORMAT(hdr.shift_start, '%H:%i:%s') AS shift_start,
+			TIME_FORMAT(hdr.shift_end, '%H:%i:%s') AS shift_end,
+			hdr.created_at,
+			hdr.created_by,
+			hdr.updated_at`).
+			Joins("LEFT JOIN bases hb ON hb.id = hdr.base_id").
+			Where("hdr.id = ? AND hdr.deleted_at IS NULL", id).
+			Where("hb.id IS NOT NULL").
+			Take(out).Error
+	}
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (r *DutyRosterRepository) hasBaseDefaultShiftTypeColumns() bool {
+	if r == nil || r.db == nil {
+		return false
+	}
+	return r.db.Migrator().HasColumn("bases", "default_start_time_type") &&
+		r.db.Migrator().HasColumn("bases", "default_end_time_type")
+}
+
+func (r *DutyRosterRepository) baseDefaultShiftDisplayExpr(alias, shiftColumn, typeColumn string) string {
+	qualifiedShift := alias + "." + shiftColumn
+	if !r.hasBaseDefaultShiftTypeColumns() {
+		return "CASE WHEN " + qualifiedShift + " IS NULL THEN '' ELSE TIME_FORMAT(" + qualifiedShift + ", '%H:%i:%s') END"
+	}
+	qualifiedType := alias + "." + typeColumn
+	return "CASE WHEN COALESCE(" + qualifiedType + ", 'FIXED') <> 'FIXED' OR " + qualifiedShift + " IS NULL THEN '' ELSE TIME_FORMAT(" + qualifiedShift + ", '%H:%i:%s') END"
+}
+
+func (r *DutyRosterRepository) GetCrewsByRosterIDs(ctx context.Context, rosterIDs [][]byte) ([]dutyroster.CrewView, error) {
+	if len(rosterIDs) == 0 {
+		return []dutyroster.CrewView{}, nil
+	}
+	rows := make([]dutyroster.CrewView, 0)
+	err := r.db.WithContext(ctx).
+		Table("duty_roster_crews c").
+		Select(`
+			c.id,
+			c.roster_id,
+			c.user_id,
+			COALESCE(NULLIF(c.name_label, ''), TRIM(CONCAT(COALESCE(u.first_name, ''), ' ', COALESCE(u.last_name, ''))), '') AS name,
+			COALESCE(NULLIF(r.name, ''), c.role_code) AS role,
+			c.role_code,
+			c.crew_type,
+			COALESCE(NULLIF(c.mobile_phone, ''), u.mobile_phone, '') AS mobile_phone,
+			COALESCE(NULLIF(c.email, ''), u.email, '') AS email,
+			c.date_start,
+			c.date_end,
+			CASE
+				WHEN c.shift_start IS NULL OR TIME_FORMAT(c.shift_start, '%H:%i:%s') = '00:00:00' THEN ''
+				ELSE TIME_FORMAT(c.shift_start, '%H:%i:%s')
+			END AS shift_start,
+			CASE
+				WHEN c.shift_end IS NULL OR TIME_FORMAT(c.shift_end, '%H:%i:%s') = '00:00:00' THEN ''
+				ELSE TIME_FORMAT(c.shift_end, '%H:%i:%s')
+			END AS shift_end,
+			c.flight_instructor,
+			c.line_checker,
+			c.supervisor,
+			c.examiner,
+			c.co_pilot`).
+		Joins("LEFT JOIN users u ON u.id = c.user_id").
+		Joins("LEFT JOIN roles r ON r.id = u.role_id").
+		Where("c.roster_id IN ? AND c.deleted_at IS NULL", rosterIDs).
+		Order("c.role_code ASC, c.crew_type ASC, c.created_at ASC").
+		Scan(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *DutyRosterRepository) ListHeadersByRange(ctx context.Context, baseID []byte, from, to time.Time) ([]dutyroster.HeaderView, error) {
+	return r.ListHeadersByRangeByBaseType(ctx, baseID, from, to, "hems")
+}
+
+func (r *DutyRosterRepository) ListHeadersByRangeByBaseType(ctx context.Context, baseID []byte, from, to time.Time, baseType string) ([]dutyroster.HeaderView, error) {
+	categoryKey := rosterBaseCategoryKey(baseType)
+	rows := make([]dutyroster.HeaderView, 0)
+	q := r.db.WithContext(ctx).
+		Table("duty_rosters hdr").
+		Select(`
+				hdr.id,
+				hdr.base_id AS base_id,
+				hb.base AS base_name,
+				hb.base_abbreviation,
+				'' AS helicopter_id,
+				'' AS helicopter_type,
+				'' AS helicopter_designation,
+				'' AS helicopter_identifier,
+			hdr.duty_date,
+			TIME_FORMAT(hdr.shift_start, '%H:%i:%s') AS shift_start,
+			TIME_FORMAT(hdr.shift_end, '%H:%i:%s') AS shift_end,
+			hdr.created_at,
+			hdr.created_by,
+			hdr.updated_at`).
+		Joins("LEFT JOIN bases hb ON hb.id = hdr.base_id").
+		Joins("LEFT JOIN base_categories bc ON bc.id = hb.base_category_id").
+		Where("hdr.deleted_at IS NULL AND hdr.duty_date BETWEEN ? AND ?", from, to).
+		Where("bc.key = ?", categoryKey).
+		Where("hb.id IS NOT NULL")
+	if len(baseID) == 16 {
+		q = q.Where("hdr.base_id = ?", baseID)
+	}
+	err := q.Order("hb.base ASC, hdr.duty_date ASC").Scan(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *DutyRosterRepository) ListHEMSBases(ctx context.Context, baseID []byte) ([]dutyroster.BaseView, error) {
+	return r.ListBasesByType(ctx, baseID, "hems")
+}
+
+func (r *DutyRosterRepository) ListBasesByType(ctx context.Context, baseID []byte, baseType string) ([]dutyroster.BaseView, error) {
+	categoryKey := rosterBaseCategoryKey(baseType)
+	rows := make([]dutyroster.BaseView, 0)
+	q := r.db.WithContext(ctx).
+		Table("bases b").
+		Select(`
+			b.id,
+			b.base AS base_name,
+			b.base_abbreviation`).
+		Joins("JOIN base_categories bc ON bc.id = b.base_category_id").
+		Where("b.is_active = ?", true).
+		Where("bc.key = ?", categoryKey)
+
+	if len(baseID) == 16 {
+		q = q.Where("b.id = ?", baseID)
+	}
+
+	if err := q.Order("CASE WHEN b.sortkey IS NULL THEN 1 ELSE 0 END ASC, b.sortkey ASC, b.base ASC").Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func rosterBaseCategoryKey(baseType string) string {
+	switch strings.ToLower(strings.TrimSpace(baseType)) {
+	case "base":
+		return basedomain.CategoryKeyRegular
+	default:
+		return basedomain.CategoryKeyHEMS
+	}
+}
+
+func dateOnlyUTC(t time.Time) time.Time {
+	return time.Date(t.UTC().Year(), t.UTC().Month(), t.UTC().Day(), 0, 0, 0, 0, time.UTC)
+}
+
+func softReplaceCrewByUser(tx *gorm.DB, rosterID []byte, roleCode, crewType string, userID []byte, updatedBy []byte) error {
+	if len(rosterID) == 0 || len(userID) == 0 {
+		return nil
+	}
+	now := time.Now().UTC()
+	return tx.Model(&dutyroster.DutyRosterCrew{}).
+		Where("roster_id = ? AND role_code = ? AND crew_type = ? AND user_id = ? AND deleted_at IS NULL", rosterID, roleCode, crewType, userID).
+		Updates(map[string]any{
+			"deleted_at": now,
+			"deleted_by": updatedBy,
+			"updated_by": updatedBy,
+		}).Error
+}
+
+func crewExists(tx *gorm.DB, row dutyroster.DutyRosterCrew) (bool, error) {
+	q := tx.Model(&dutyroster.DutyRosterCrew{}).
+		Where("roster_id = ? AND role_code = ? AND crew_type = ? AND deleted_at IS NULL", row.RosterID, row.RoleCode, row.CrewType).
+		Where("name_label = ? AND mobile_phone = ? AND email = ?", row.NameLabel, row.MobilePhone, row.Email).
+		Where("shift_start = ? AND shift_end = ?", row.ShiftStart, row.ShiftEnd)
+
+	if len(row.UserID) == 0 {
+		q = q.Where("user_id IS NULL")
+	} else {
+		q = q.Where("user_id = ?", row.UserID)
+	}
+	if row.DateStart == nil {
+		q = q.Where("date_start IS NULL")
+	} else {
+		q = q.Where("date_start = ?", dateOnlyUTC(*row.DateStart))
+	}
+	if row.DateEnd == nil {
+		q = q.Where("date_end IS NULL")
+	} else {
+		q = q.Where("date_end = ?", dateOnlyUTC(*row.DateEnd))
+	}
+
+	var count int64
+	if err := q.Count(&count).Error; err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+func softDeleteCrewForDate(
+	tx *gorm.DB,
+	baseID []byte,
+	dutyDate time.Time,
+	crew dutyroster.DutyRosterCrew,
+	now time.Time,
+	updatedBy []byte,
+) error {
+	date := dateOnlyUTC(dutyDate)
+	var rosterIDs [][]byte
+	if err := tx.
+		Table("duty_rosters").
+		Select("id").
+		Where("base_id = ? AND duty_date = ? AND deleted_at IS NULL", baseID, date).
+		Scan(&rosterIDs).Error; err != nil {
+		return err
+	}
+	if len(rosterIDs) == 0 {
+		return nil
+	}
+
+	q := tx.Model(&dutyroster.DutyRosterCrew{}).
+		Where("roster_id IN ? AND role_code = ? AND crew_type = ? AND deleted_at IS NULL", rosterIDs, crew.RoleCode, crew.CrewType).
+		Where("name_label = ? AND mobile_phone = ? AND email = ? AND shift_start = ? AND shift_end = ?",
+			crew.NameLabel,
+			crew.MobilePhone,
+			crew.Email,
+			crew.ShiftStart,
+			crew.ShiftEnd,
+		)
+	if len(crew.UserID) == 0 {
+		q = q.Where("user_id IS NULL")
+	} else {
+		q = q.Where("user_id = ?", crew.UserID)
+	}
+	if crew.DateStart == nil {
+		q = q.Where("date_start IS NULL")
+	} else {
+		q = q.Where("date_start = ?", dateOnlyUTC(*crew.DateStart))
+	}
+	if crew.DateEnd == nil {
+		q = q.Where("date_end IS NULL")
+	} else {
+		q = q.Where("date_end = ?", dateOnlyUTC(*crew.DateEnd))
+	}
+
+	return q.Updates(map[string]any{
+		"deleted_at": now,
+		"deleted_by": updatedBy,
+		"updated_by": updatedBy,
+	}).Error
+}
+
+func findRosterIDsByBaseAndDate(tx *gorm.DB, baseID []byte, dutyDate time.Time) ([][]byte, error) {
+	type rowID struct {
+		ID []byte `gorm:"column:id"`
+	}
+	date := dateOnlyUTC(dutyDate)
+	rows := make([]rowID, 0)
+	if err := tx.
+		Table("duty_rosters").
+		Select("id").
+		Where("base_id = ? AND duty_date = ? AND deleted_at IS NULL", baseID, date).
+		Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	out := make([][]byte, 0, len(rows))
+	for i := range rows {
+		out = append(out, rows[i].ID)
+	}
+	return out, nil
+}
+
+func softDeleteCrewByFilter(
+	tx *gorm.DB,
+	rosterIDs [][]byte,
+	crew dutyroster.DutyRosterCrew,
+	now time.Time,
+	updatedBy []byte,
+) error {
+	if len(rosterIDs) == 0 {
+		return nil
+	}
+	q := tx.Model(&dutyroster.DutyRosterCrew{}).
+		Table("duty_roster_crews c").
+		Where("c.roster_id IN ? AND c.role_code = ? AND c.deleted_at IS NULL", rosterIDs, crew.RoleCode)
+
+	if strings.TrimSpace(crew.CrewType) != "" {
+		q = q.Where("c.crew_type = ?", crew.CrewType)
+	}
+	if len(crew.UserID) > 0 {
+		q = q.Where("c.user_id = ?", crew.UserID)
+	} else if strings.TrimSpace(crew.NameLabel) != "" {
+		q = q.Where("c.name_label = ?", crew.NameLabel)
+	}
+	if crew.DateStart != nil {
+		q = q.Where("c.date_start = ?", dateOnlyUTC(*crew.DateStart))
+	}
+	if crew.DateEnd != nil {
+		q = q.Where("c.date_end = ?", dateOnlyUTC(*crew.DateEnd))
+	}
+	if strings.TrimSpace(crew.ShiftStart) != "" {
+		q = q.Where("c.shift_start = ?", crew.ShiftStart)
+	}
+	if strings.TrimSpace(crew.ShiftEnd) != "" {
+		q = q.Where("c.shift_end = ?", crew.ShiftEnd)
+	}
+
+	return q.Updates(map[string]any{
+		"deleted_at": now,
+		"deleted_by": updatedBy,
+		"updated_by": updatedBy,
+	}).Error
+}
+
+func matchCrewByFilter(tx *gorm.DB, rosterIDs [][]byte, crew dutyroster.DutyRosterCrew) ([]dutyroster.DeletedCrewResult, error) {
+	if len(rosterIDs) == 0 {
+		return []dutyroster.DeletedCrewResult{}, nil
+	}
+	q := tx.Model(&dutyroster.DutyRosterCrew{}).
+		Select(`
+			c.id,
+			c.roster_id,
+			c.user_id,
+			COALESCE(NULLIF(c.name_label, ''), TRIM(CONCAT(COALESCE(u.first_name, ''), ' ', COALESCE(u.last_name, ''))), '') AS name,
+			c.role_code,
+			c.crew_type,
+			c.date_start,
+			c.date_end`).
+		Table("duty_roster_crews c").
+		Joins("LEFT JOIN users u ON u.id = c.user_id").
+		Where("roster_id IN ? AND role_code = ? AND deleted_at IS NULL", rosterIDs, crew.RoleCode)
+
+	if strings.TrimSpace(crew.CrewType) != "" {
+		q = q.Where("crew_type = ?", crew.CrewType)
+	}
+	if len(crew.UserID) > 0 {
+		q = q.Where("user_id = ?", crew.UserID)
+	} else if strings.TrimSpace(crew.NameLabel) != "" {
+		q = q.Where("name_label = ?", crew.NameLabel)
+	}
+	if crew.DateStart != nil {
+		q = q.Where("date_start = ?", dateOnlyUTC(*crew.DateStart))
+	}
+	if crew.DateEnd != nil {
+		q = q.Where("date_end = ?", dateOnlyUTC(*crew.DateEnd))
+	}
+	if strings.TrimSpace(crew.ShiftStart) != "" {
+		q = q.Where("shift_start = ?", crew.ShiftStart)
+	}
+	if strings.TrimSpace(crew.ShiftEnd) != "" {
+		q = q.Where("shift_end = ?", crew.ShiftEnd)
+	}
+
+	out := make([]dutyroster.DeletedCrewResult, 0)
+	if err := q.Scan(&out).Error; err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func softDeleteCrewByIDs(tx *gorm.DB, rows []dutyroster.DeletedCrewResult, now time.Time, updatedBy []byte) error {
+	if len(rows) == 0 {
+		return nil
+	}
+	ids := make([][]byte, 0, len(rows))
+	for i := range rows {
+		ids = append(ids, rows[i].ID)
+	}
+	return tx.Model(&dutyroster.DutyRosterCrew{}).
+		Where("id IN ? AND deleted_at IS NULL", ids).
+		Updates(map[string]any{
+			"deleted_at": now,
+			"deleted_by": updatedBy,
+			"updated_by": updatedBy,
+		}).Error
+}
diff --git a/internal/repository/mysql/duty_roster_repo_test.go b/internal/repository/mysql/duty_roster_repo_test.go
new file mode 100644
index 0000000..36d5628
--- /dev/null
+++ b/internal/repository/mysql/duty_roster_repo_test.go
@@ -0,0 +1,749 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	sqlite3 "github.com/mattn/go-sqlite3"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	dutyroster "wucher/internal/domain/duty_roster"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openDutyRosterRepoTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:duty_roster_repo_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+
+	createRoster := `
+CREATE TABLE duty_rosters (
+	id BLOB PRIMARY KEY,
+	flight_id BLOB NULL,
+	base_id BLOB NOT NULL,
+	duty_date DATETIME NOT NULL,
+	shift_start DATETIME NULL,
+	shift_end DATETIME NULL,
+	helicopter_id BLOB NULL,
+	created_at DATETIME NULL,
+	created_by BLOB NULL,
+	updated_at DATETIME NULL,
+	updated_by BLOB NULL,
+	deleted_at DATETIME NULL,
+	deleted_by BLOB NULL
+);`
+	if err := db.Exec(createRoster).Error; err != nil {
+		t.Fatalf("create duty_rosters: %v", err)
+	}
+	if err := db.Exec("CREATE UNIQUE INDEX idx_roster_base_date ON duty_rosters(base_id, duty_date)").Error; err != nil {
+		t.Fatalf("create idx_roster_base_date: %v", err)
+	}
+
+	createCrew := `
+CREATE TABLE duty_roster_crews (
+	id BLOB PRIMARY KEY,
+	roster_id BLOB NOT NULL,
+	takeover_ac_id BLOB NULL,
+	user_id BLOB NULL,
+	role_code TEXT NOT NULL,
+	crew_type TEXT NOT NULL,
+	name_label TEXT NULL,
+	mobile_phone TEXT NULL,
+	email TEXT NULL,
+	confirm_at DATETIME NULL,
+	date_start DATE NULL,
+	date_end DATE NULL,
+	shift_start DATETIME NULL,
+	shift_end DATETIME NULL,
+	flight_instructor INTEGER NOT NULL DEFAULT 0,
+	line_checker INTEGER NOT NULL DEFAULT 0,
+	supervisor INTEGER NOT NULL DEFAULT 0,
+	examiner INTEGER NOT NULL DEFAULT 0,
+	co_pilot INTEGER NOT NULL DEFAULT 0,
+	created_at DATETIME NULL,
+	created_by BLOB NULL,
+	updated_at DATETIME NULL,
+	updated_by BLOB NULL,
+	deleted_at DATETIME NULL,
+	deleted_by BLOB NULL
+);`
+	if err := db.Exec(createCrew).Error; err != nil {
+		t.Fatalf("create duty_roster_crews: %v", err)
+	}
+	registerSQLiteTimeFormatCompat(t, db)
+
+	return db
+}
+
+func registerSQLiteTimeFormatCompat(t *testing.T, db *gorm.DB) {
+	t.Helper()
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("db.DB: %v", err)
+	}
+	conn, err := sqlDB.Conn(context.Background())
+	if err != nil {
+		t.Fatalf("sqlDB.Conn: %v", err)
+	}
+	defer conn.Close()
+
+	if err := conn.Raw(func(driverConn any) error {
+		raw, ok := driverConn.(*sqlite3.SQLiteConn)
+		if !ok {
+			return fmt.Errorf("unexpected sqlite conn type %T", driverConn)
+		}
+		return raw.RegisterFunc("TIME_FORMAT", func(v any, pattern string) string {
+			if pattern != "%H:%i:%s" {
+				return ""
+			}
+			var rawVal string
+			switch x := v.(type) {
+			case time.Time:
+				return x.UTC().Format("15:04:05")
+			case []byte:
+				rawVal = string(x)
+			case string:
+				rawVal = x
+			default:
+				rawVal = fmt.Sprint(x)
+			}
+			rawVal = strings.TrimSpace(rawVal)
+			if rawVal == "" {
+				return ""
+			}
+			layouts := []string{
+				"2006-01-02 15:04:05.999999999-07:00",
+				"2006-01-02 15:04:05.999999999",
+				"2006-01-02 15:04:05",
+				time.RFC3339,
+				"15:04:05",
+			}
+			for _, layout := range layouts {
+				if tm, err := time.Parse(layout, rawVal); err == nil {
+					return tm.UTC().Format("15:04:05")
+				}
+			}
+			if len(rawVal) >= 8 {
+				return rawVal[len(rawVal)-8:]
+			}
+			return ""
+		}, true)
+	}); err != nil {
+		t.Fatalf("register TIME_FORMAT: %v", err)
+	}
+}
+
+func dutyRosterTestCategoryIDs() (regularID, hemsID []byte) {
+	return []byte("catregular000001"), []byte("cathems000000001")
+}
+
+func TestDutyRosterRepositoryUpdate_ReplaceSameUserAppendDifferentUser(t *testing.T) {
+	db := openDutyRosterRepoTestDB(t)
+	repo := NewDutyRosterRepository(db)
+	svc := service.NewDutyRosterService(repo)
+	ctx := context.Background()
+	baseID := uuidv7.MustBytes()
+	actor := uuidv7.MustBytes()
+	userMain := uuidv7.MustBytes()
+	userAdditional := uuidv7.MustBytes()
+	date := time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)
+
+	row := &dutyroster.DutyRoster{
+		BaseID:    baseID,
+		DutyDate:  date,
+		CreatedBy: actor,
+		UpdatedBy: actor,
+	}
+	if err := svc.Create(ctx, row, nil); err != nil {
+		t.Fatalf("seed create roster: %v", err)
+	}
+	if err := db.Create(&dutyroster.DutyRosterCrew{
+		RosterID:  row.ID,
+		UserID:    userMain,
+		RoleCode:  "pilot",
+		CrewType:  "main",
+		CreatedBy: actor,
+		UpdatedBy: actor,
+	}).Error; err != nil {
+		t.Fatalf("seed old crew: %v", err)
+	}
+
+	updateRow := &dutyroster.DutyRoster{
+		ID:        row.ID,
+		BaseID:    baseID,
+		DutyDate:  date,
+		UpdatedBy: actor,
+	}
+	updateCrews := []dutyroster.DutyRosterCrew{
+		{
+			UserID:   userMain,
+			RoleCode: "pilot",
+			CrewType: "main",
+		},
+		{
+			UserID:   userAdditional,
+			RoleCode: "pilot",
+			CrewType: "additional",
+		},
+	}
+	if err := svc.Update(ctx, updateRow, updateCrews); err != nil {
+		t.Fatalf("update roster: %v", err)
+	}
+
+	var activeMain []dutyroster.DutyRosterCrew
+	if err := db.Where("roster_id = ? AND user_id = ? AND role_code = 'pilot' AND crew_type = 'main' AND deleted_at IS NULL", row.ID, userMain).
+		Find(&activeMain).Error; err != nil {
+		t.Fatalf("query active main: %v", err)
+	}
+	if len(activeMain) != 1 {
+		t.Fatalf("expected 1 active main crew, got %d", len(activeMain))
+	}
+
+	var historicalMain int64
+	if err := db.Model(&dutyroster.DutyRosterCrew{}).
+		Where("roster_id = ? AND user_id = ? AND role_code = 'pilot' AND crew_type = 'main'", row.ID, userMain).
+		Count(&historicalMain).Error; err != nil {
+		t.Fatalf("count main history: %v", err)
+	}
+	if historicalMain != 2 {
+		t.Fatalf("expected 2 historical main rows (old deleted + new active), got %d", historicalMain)
+	}
+
+	var activeAdditional int64
+	if err := db.Model(&dutyroster.DutyRosterCrew{}).
+		Where("roster_id = ? AND user_id = ? AND role_code = 'pilot' AND crew_type = 'additional' AND deleted_at IS NULL", row.ID, userAdditional).
+		Count(&activeAdditional).Error; err != nil {
+		t.Fatalf("count active additional: %v", err)
+	}
+	if activeAdditional != 1 {
+		t.Fatalf("expected appended additional crew, got %d", activeAdditional)
+	}
+}
+
+func TestDutyRosterRepositoryUpdate_RangeShrinkRemovesOutOfRangeAssignments(t *testing.T) {
+	db := openDutyRosterRepoTestDB(t)
+	repo := NewDutyRosterRepository(db)
+	svc := service.NewDutyRosterService(repo)
+	ctx := context.Background()
+	baseID := uuidv7.MustBytes()
+	actor := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+	d20 := time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)
+	d21 := time.Date(2026, 3, 21, 0, 0, 0, 0, time.UTC)
+	d22 := time.Date(2026, 3, 22, 0, 0, 0, 0, time.UTC)
+
+	row20 := &dutyroster.DutyRoster{BaseID: baseID, DutyDate: d20, CreatedBy: actor, UpdatedBy: actor}
+	row21 := &dutyroster.DutyRoster{BaseID: baseID, DutyDate: d21, CreatedBy: actor, UpdatedBy: actor}
+	row22 := &dutyroster.DutyRoster{BaseID: baseID, DutyDate: d22, CreatedBy: actor, UpdatedBy: actor}
+	if err := svc.Create(ctx, row20, nil); err != nil {
+		t.Fatalf("create roster d20: %v", err)
+	}
+	if err := svc.Create(ctx, row21, nil); err != nil {
+		t.Fatalf("create roster d21: %v", err)
+	}
+	if err := svc.Create(ctx, row22, nil); err != nil {
+		t.Fatalf("create roster d22: %v", err)
+	}
+
+	startOld := d20
+	endOld := d22
+	seedCrew := func(rosterID []byte) {
+		if err := db.Create(&dutyroster.DutyRosterCrew{
+			RosterID:  rosterID,
+			UserID:    userID,
+			RoleCode:  "pilot",
+			CrewType:  "main",
+			DateStart: &startOld,
+			DateEnd:   &endOld,
+			CreatedBy: actor,
+			UpdatedBy: actor,
+		}).Error; err != nil {
+			t.Fatalf("seed crew: %v", err)
+		}
+	}
+	seedCrew(row20.ID)
+	seedCrew(row21.ID)
+	seedCrew(row22.ID)
+
+	startNew := d20
+	endNew := d21
+	updateRow := &dutyroster.DutyRoster{
+		ID:        row20.ID,
+		BaseID:    baseID,
+		DutyDate:  d20,
+		UpdatedBy: actor,
+	}
+	updateCrews := []dutyroster.DutyRosterCrew{
+		{
+			UserID:    userID,
+			RoleCode:  "pilot",
+			CrewType:  "main",
+			DateStart: &startNew,
+			DateEnd:   &endNew,
+		},
+	}
+	if err := svc.Update(ctx, updateRow, updateCrews); err != nil {
+		t.Fatalf("update range shrink: %v", err)
+	}
+
+	var active22 int64
+	if err := db.Model(&dutyroster.DutyRosterCrew{}).
+		Where("roster_id = ? AND user_id = ? AND role_code = 'pilot' AND crew_type = 'main' AND deleted_at IS NULL", row22.ID, userID).
+		Count(&active22).Error; err != nil {
+		t.Fatalf("count active d22: %v", err)
+	}
+	if active22 != 1 {
+		t.Fatalf("expected active assignment to remain on 2026-03-22 after shrink, got %d", active22)
+	}
+
+	var active21 int64
+	if err := db.Model(&dutyroster.DutyRosterCrew{}).
+		Where("roster_id = ? AND user_id = ? AND role_code = 'pilot' AND crew_type = 'main' AND deleted_at IS NULL", row21.ID, userID).
+		Count(&active21).Error; err != nil {
+		t.Fatalf("count active d21: %v", err)
+	}
+	if active21 != 1 {
+		t.Fatalf("expected active assignment remains on 2026-03-21, got %d", active21)
+	}
+}
+
+func openDutyRosterRepoCoverageDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:duty_roster_repo_cov_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+
+	stmts := []string{
+		`CREATE TABLE duty_rosters (
+			id BLOB PRIMARY KEY,
+			base_id BLOB NOT NULL,
+			duty_date DATETIME NOT NULL,
+			shift_start DATETIME NULL,
+			shift_end DATETIME NULL,
+			helicopter_id BLOB NULL,
+			created_at DATETIME NULL,
+			created_by BLOB NULL,
+			updated_at DATETIME NULL,
+			updated_by BLOB NULL,
+			deleted_at DATETIME NULL,
+			deleted_by BLOB NULL
+		);`,
+		`CREATE UNIQUE INDEX idx_roster_base_date ON duty_rosters(base_id, duty_date);`,
+		`CREATE TABLE duty_roster_crews (
+			id BLOB PRIMARY KEY,
+			roster_id BLOB NOT NULL,
+			takeover_ac_id BLOB NULL,
+			user_id BLOB NULL,
+			role_code TEXT NOT NULL,
+			crew_type TEXT NOT NULL,
+			name_label TEXT NULL,
+			mobile_phone TEXT NULL,
+			email TEXT NULL,
+			confirm_at DATETIME NULL,
+			date_start DATE NULL,
+			date_end DATE NULL,
+			shift_start DATETIME NULL,
+			shift_end DATETIME NULL,
+			flight_instructor INTEGER NOT NULL DEFAULT 0,
+			line_checker INTEGER NOT NULL DEFAULT 0,
+			supervisor INTEGER NOT NULL DEFAULT 0,
+			examiner INTEGER NOT NULL DEFAULT 0,
+			co_pilot INTEGER NOT NULL DEFAULT 0,
+			created_at DATETIME NULL,
+			created_by BLOB NULL,
+			updated_at DATETIME NULL,
+			updated_by BLOB NULL,
+			deleted_at DATETIME NULL,
+			deleted_by BLOB NULL
+		);`,
+		"CREATE TABLE base_categories (\n\t\t\tid BLOB PRIMARY KEY,\n\t\t\t`key` TEXT UNIQUE,\n\t\t\tname TEXT\n\t\t);",
+		`CREATE TABLE bases (
+			id BLOB PRIMARY KEY,
+			base_category_id BLOB NOT NULL,
+			base TEXT,
+			base_abbreviation TEXT,
+			sortkey INTEGER NULL,
+			is_active BOOLEAN DEFAULT 1,
+			default_shift_start TEXT NULL,
+			default_shift_end TEXT NULL,
+			default_shift_time TEXT
+		);`,
+		`CREATE TABLE helicopters (
+			id BLOB PRIMARY KEY,
+			identifier TEXT,
+			designation TEXT
+		);`,
+		`CREATE TABLE roles (
+			id BLOB PRIMARY KEY,
+			name TEXT
+		);`,
+		`CREATE TABLE users (
+			id BLOB PRIMARY KEY,
+			first_name TEXT,
+			last_name TEXT,
+			mobile_phone TEXT,
+			email TEXT,
+			role_id BLOB NULL
+		);`,
+	}
+	for _, stmt := range stmts {
+		if err := db.Exec(stmt).Error; err != nil {
+			t.Fatalf("create stmt failed: %v\nsql=%s", err, stmt)
+		}
+	}
+	regularCategoryID, hemsCategoryID := dutyRosterTestCategoryIDs()
+	asBlob := func(b []byte) string { return fmt.Sprintf("X'%x'", b) }
+	if err := db.Exec(
+		fmt.Sprintf(
+			"INSERT INTO base_categories(id, `key`, name) VALUES(%s, 'regular', 'Regular'),(%s, 'hems', 'HEMS')",
+			asBlob(regularCategoryID),
+			asBlob(hemsCategoryID),
+		),
+	).Error; err != nil {
+		t.Fatalf("seed base_categories: %v", err)
+	}
+	registerSQLiteTimeFormatCompat(t, db)
+	return db
+}
+
+func TestDutyRosterRepository_ReadListAndDeleteFlows(t *testing.T) {
+	db := openDutyRosterRepoCoverageDB(t)
+	repo := NewDutyRosterRepository(db)
+	ctx := context.Background()
+
+	hemsBaseID := []byte("hemsbase00000001")
+	baseID := []byte("basebase00000001")
+	regularCategoryID, hemsCategoryID := dutyRosterTestCategoryIDs()
+	heliID := []byte("heliheli00000001")
+	roleID := []byte("rolerole00000001")
+	userID := []byte("useruser00000001")
+	rosterID := []byte("rosterro00000001")
+	crewID := []byte("crewcrew00000001")
+	now := time.Now().UTC()
+	dutyDate := time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)
+
+	mustExec := func(sql string, args ...any) {
+		if err := db.Exec(sql, args...).Error; err != nil {
+			t.Fatalf("exec failed: %v, sql=%s", err, sql)
+		}
+	}
+	asBlob := func(b []byte) string { return fmt.Sprintf("X'%x'", b) }
+	mustExec(fmt.Sprintf(`INSERT INTO bases(id, base_category_id, base, base_abbreviation, sortkey, is_active, default_shift_time) VALUES(%s, %s, ?, ?, 1, 1, ?)`, asBlob(hemsBaseID), asBlob(hemsCategoryID)),
+		"HEMS A", "HA", "06:00-21:00")
+	mustExec(fmt.Sprintf(`INSERT INTO bases(id, base_category_id, base, base_abbreviation, sortkey, is_active, default_shift_time) VALUES(%s, %s, ?, ?, 1, 1, ?)`, asBlob(baseID), asBlob(regularCategoryID)),
+		"BASE A", "BA", "07:00-19:00")
+	mustExec(fmt.Sprintf(`INSERT INTO helicopters(id, identifier, designation) VALUES(%s, ?, ?)`, asBlob(heliID)), "H145", "H145")
+	mustExec(fmt.Sprintf(`INSERT INTO roles(id, name) VALUES(%s, ?)`, asBlob(roleID)), "pilot")
+	mustExec(fmt.Sprintf(`INSERT INTO users(id, first_name, last_name, mobile_phone, email, role_id) VALUES(%s, ?, ?, ?, ?, %s)`, asBlob(userID), asBlob(roleID)),
+		"Pilot", "One", "+62000", "pilot@example.com")
+	mustExec(fmt.Sprintf(`INSERT INTO duty_rosters(id, base_id, duty_date, shift_start, shift_end, helicopter_id, created_at, updated_at) VALUES(%s, %s, ?, ?, ?, %s, ?, ?)`,
+		asBlob(rosterID), asBlob(hemsBaseID), asBlob(heliID)),
+		dutyDate, "2000-01-01 06:00:00", "2000-01-01 21:00:00", now, now)
+	mustExec(fmt.Sprintf(`INSERT INTO duty_roster_crews(id, roster_id, user_id, role_code, crew_type, name_label, mobile_phone, email, date_start, date_end, shift_start, shift_end, created_at, updated_at)
+			VALUES(%s, %s, %s, 'pilot', 'main', '', '', '', ?, ?, ?, ?, ?, ?)`, asBlob(crewID), asBlob(rosterID), asBlob(userID)),
+		dutyDate, dutyDate, "2000-01-01 06:00:00", "2000-01-01 21:00:00", now, now)
+
+	if _, err := repo.GetRosterByID(ctx, rosterID); err != nil {
+		t.Fatalf("GetRosterByID: %v", err)
+	}
+	if _, err := repo.LockRosterByID(ctx, rosterID); err != nil {
+		t.Fatalf("LockRosterByID: %v", err)
+	}
+	if _, err := repo.ListActiveCrewsByRosterID(ctx, rosterID); err != nil {
+		t.Fatalf("ListActiveCrewsByRosterID: %v", err)
+	}
+
+	if _, err := repo.FindRosterIDsByBaseDate(ctx, hemsBaseID, dutyDate); err != nil {
+		t.Fatalf("FindRosterIDsByBaseDate: %v", err)
+	}
+	rows, err := repo.MatchCrewByFilter(ctx, [][]byte{rosterID}, dutyroster.DutyRosterCrew{
+		RoleCode: "pilot",
+		CrewType: "main",
+		UserID:   userID,
+	})
+	if err != nil {
+		t.Fatalf("MatchCrewByFilter: %v", err)
+	}
+	if len(rows) == 0 {
+		t.Fatalf("expected matched rows")
+	}
+	if err := repo.SoftDeleteCrewRows(ctx, rows, uuidv7.MustBytes()); err != nil {
+		t.Fatalf("SoftDeleteCrewRows: %v", err)
+	}
+
+	if _, err := repo.GetBaseDefaultShift(ctx, hemsBaseID, "hems"); err != nil {
+		t.Fatalf("GetBaseDefaultShift hems: %v", err)
+	}
+	if _, err := repo.GetBaseDefaultShift(ctx, baseID, "base"); err != nil {
+		t.Fatalf("GetBaseDefaultShift base: %v", err)
+	}
+
+	if _, err := repo.GetHeaderByID(ctx, rosterID); err != nil {
+		t.Fatalf("GetHeaderByID: %v", err)
+	}
+	if _, err := repo.GetHeaderByIDByBaseType(ctx, rosterID, "base"); err != nil {
+		t.Fatalf("GetHeaderByIDByBaseType base: %v", err)
+	}
+	if _, err := repo.GetCrewsByRosterIDs(ctx, [][]byte{rosterID}); err != nil {
+		t.Fatalf("GetCrewsByRosterIDs: %v", err)
+	}
+	if _, err := repo.ListHeadersByRange(ctx, hemsBaseID, dutyDate.AddDate(0, 0, -1), dutyDate.AddDate(0, 0, 1)); err != nil {
+		t.Fatalf("ListHeadersByRange: %v", err)
+	}
+	if _, err := repo.ListHeadersByRangeByBaseType(ctx, baseID, dutyDate.AddDate(0, 0, -1), dutyDate.AddDate(0, 0, 1), "base"); err != nil {
+		t.Fatalf("ListHeadersByRangeByBaseType: %v", err)
+	}
+	if _, err := repo.ListHEMSBases(ctx, nil); err != nil {
+		t.Fatalf("ListHEMSBases: %v", err)
+	}
+	if _, err := repo.ListBasesByType(ctx, nil, "base"); err != nil {
+		t.Fatalf("ListBasesByType: %v", err)
+	}
+
+	if err := repo.SoftDeleteCrewsByRosterID(ctx, rosterID, uuidv7.MustBytes()); err != nil {
+		t.Fatalf("SoftDeleteCrewsByRosterID: %v", err)
+	}
+	if err := repo.SoftDeleteHeader(ctx, rosterID, uuidv7.MustBytes()); err != nil {
+		t.Fatalf("SoftDeleteHeader: %v", err)
+	}
+}
+
+func TestDutyRosterRepository_HelperCoverage(t *testing.T) {
+	if key := rosterBaseCategoryKey("base"); key != "regular" {
+		t.Fatalf("unexpected base category key")
+	}
+	if key := rosterBaseCategoryKey("hems"); key != "hems" {
+		t.Fatalf("unexpected hems category key")
+	}
+	if got := dateOnlyUTC(time.Date(2026, 3, 20, 9, 10, 11, 0, time.FixedZone("X", 7*3600))); got.Hour() != 0 {
+		t.Fatalf("expected date only UTC, got %v", got)
+	}
+	if err := softDeleteCrewByIDs(nil, nil, time.Now().UTC(), nil); err != nil {
+		t.Fatalf("softDeleteCrewByIDs empty should be nil, got %v", err)
+	}
+}
+
+func TestDutyRosterRepository_HelperCoverageExtra(t *testing.T) {
+	db := openDutyRosterRepoCoverageDB(t)
+	repo := NewDutyRosterRepository(db)
+	ctx := context.Background()
+
+	if _, err := repo.GetCrewsByRosterIDs(ctx, nil); err != nil {
+		t.Fatalf("GetCrewsByRosterIDs empty should not error: %v", err)
+	}
+	if _, err := repo.ListBasesByType(ctx, nil, "unknown"); err != nil {
+		t.Fatalf("ListBasesByType unknown should not error: %v", err)
+	}
+	if _, err := repo.FindRosterIDByBaseDate(ctx, []byte("base-does-not-exist"), time.Date(2026, 3, 1, 0, 0, 0, 0, time.UTC)); err != nil {
+		t.Fatalf("FindRosterIDByBaseDate empty should not error: %v", err)
+	}
+	if _, err := repo.MatchCrewByFilter(ctx, nil, dutyroster.DutyRosterCrew{RoleCode: "pilot"}); err != nil {
+		t.Fatalf("MatchCrewByFilter empty rosterIDs should not error: %v", err)
+	}
+
+	if err := softDeleteCrewByFilter(db, nil, dutyroster.DutyRosterCrew{RoleCode: "pilot"}, time.Now().UTC(), uuidv7.MustBytes()); err != nil {
+		t.Fatalf("softDeleteCrewByFilter empty rosterIDs should not error: %v", err)
+	}
+
+	rosterID := []byte("roster-softdel-01")
+	userID := []byte("user-softdel-001")
+	now := time.Now().UTC()
+	asBlob := func(b []byte) string { return fmt.Sprintf("X'%x'", b) }
+	if err := db.Exec(fmt.Sprintf(`INSERT INTO duty_rosters(id, base_id, duty_date, shift_start, shift_end, created_at, updated_at) VALUES(%s, %s, ?, ?, ?, ?, ?)`,
+		asBlob(rosterID), asBlob([]byte("hems-base-softdel"))),
+		time.Date(2026, 3, 21, 0, 0, 0, 0, time.UTC), "2000-01-01 06:00:00", "2000-01-01 21:00:00", now, now).Error; err != nil {
+		t.Fatalf("seed roster for softDeleteCrewByFilter: %v", err)
+	}
+	if err := db.Exec(fmt.Sprintf(`INSERT INTO duty_roster_crews(id, roster_id, user_id, role_code, crew_type, date_start, date_end, shift_start, shift_end, created_at, updated_at)
+		VALUES(%s, %s, %s, 'pilot', 'main', ?, ?, ?, ?, ?, ?)`,
+		asBlob([]byte("crew-softdel-001")), asBlob(rosterID), asBlob(userID)),
+		time.Date(2026, 3, 21, 0, 0, 0, 0, time.UTC),
+		time.Date(2026, 3, 21, 0, 0, 0, 0, time.UTC),
+		"2000-01-01 08:00:00", "2000-01-01 22:00:00",
+		now, now).Error; err != nil {
+		t.Fatalf("seed crew for softDeleteCrewByFilter: %v", err)
+	}
+	filterDate := time.Date(2026, 3, 21, 0, 0, 0, 0, time.UTC)
+	err := softDeleteCrewByFilter(db, [][]byte{rosterID}, dutyroster.DutyRosterCrew{
+		RoleCode:  "pilot",
+		CrewType:  "main",
+		UserID:    userID,
+		DateStart: &filterDate,
+		DateEnd:   &filterDate,
+	}, now, uuidv7.MustBytes())
+	if err == nil {
+		t.Fatalf("expected sqlite dialect error for UPDATE alias query")
+	}
+}
+
+func TestDutyRosterRepository_NotFoundAndRowsAffectedBranches(t *testing.T) {
+	db := openDutyRosterRepoCoverageDB(t)
+	repo := NewDutyRosterRepository(db)
+	ctx := context.Background()
+
+	missingID := []byte("missing-roster-01")
+	baseID := []byte("base-not-found-1")
+	dutyDate := time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)
+
+	if _, err := repo.GetRosterByID(ctx, missingID); err == nil {
+		t.Fatalf("expected GetRosterByID not found error")
+	}
+	if _, err := repo.LockRosterByID(ctx, missingID); err == nil {
+		t.Fatalf("expected LockRosterByID not found error")
+	}
+
+	if err := repo.UpdateHeader(ctx, &dutyroster.DutyRoster{
+		ID:        missingID,
+		BaseID:    baseID,
+		DutyDate:  dutyDate,
+		UpdatedBy: uuidv7.MustBytes(),
+	}); err == nil {
+		t.Fatalf("expected UpdateHeader not found error")
+	}
+
+	if err := repo.SoftDeleteHeader(ctx, missingID, uuidv7.MustBytes()); err == nil {
+		t.Fatalf("expected SoftDeleteHeader not found error")
+	}
+	if _, err := repo.GetBaseDefaultShift(ctx, baseID, "base"); err == nil {
+		t.Fatalf("expected GetBaseDefaultShift not found error")
+	}
+
+	// with non-empty baseID filter branch on list bases
+	if rows, err := repo.ListHEMSBases(ctx, baseID); err != nil || len(rows) != 0 {
+		t.Fatalf("expected empty ListHEMSBases filtered result, got len=%d err=%v", len(rows), err)
+	}
+	if rows, err := repo.ListBasesByType(ctx, baseID, "base"); err != nil || len(rows) != 0 {
+		t.Fatalf("expected empty ListBasesByType filtered result, got len=%d err=%v", len(rows), err)
+	}
+
+	if err := db.Exec("DROP TABLE duty_rosters").Error; err != nil {
+		t.Fatalf("drop duty_rosters: %v", err)
+	}
+	if _, err := repo.FindRosterIDByBaseDate(ctx, baseID, dutyDate); err == nil {
+		t.Fatalf("expected query error after dropping roster table")
+	}
+}
+
+func TestDutyRosterRepository_LowLevelHelperBranches(t *testing.T) {
+	db := openDutyRosterRepoCoverageDB(t)
+	now := time.Now().UTC()
+	asBlob := func(b []byte) string { return fmt.Sprintf("X'%x'", b) }
+
+	baseID := []byte("hems-base-helper01")
+	_, hemsCategoryID := dutyRosterTestCategoryIDs()
+	rosterID := []byte("roster-helper-001")
+	userID := []byte("user-helper-0001")
+	crewIDUser := []byte("crew-helper-user1")
+	crewIDGuest := []byte("crew-helper-guest")
+	dutyDate := time.Date(2026, 3, 22, 0, 0, 0, 0, time.UTC)
+
+	if err := db.Exec(fmt.Sprintf(`INSERT INTO bases(id, base_category_id, base, base_abbreviation, sortkey, is_active, default_shift_time) VALUES(%s, %s, ?, ?, 1, 1, ?)`, asBlob(baseID), asBlob(hemsCategoryID)),
+		"HEMS H", "HH", "06:00-21:00").Error; err != nil {
+		t.Fatalf("seed base: %v", err)
+	}
+	if err := db.Exec(fmt.Sprintf(`INSERT INTO duty_rosters(id, base_id, duty_date, shift_start, shift_end, created_at, updated_at) VALUES(%s, %s, ?, ?, ?, ?, ?)`,
+		asBlob(rosterID), asBlob(baseID)),
+		dutyDate, "2000-01-01 06:00:00", "2000-01-01 21:00:00", now, now).Error; err != nil {
+		t.Fatalf("seed roster: %v", err)
+	}
+	if err := db.Exec(fmt.Sprintf(`INSERT INTO duty_roster_crews(id, roster_id, user_id, role_code, crew_type, name_label, mobile_phone, email, date_start, date_end, shift_start, shift_end, created_at, updated_at)
+		VALUES(%s, %s, %s, 'pilot', 'main', '', '', '', ?, ?, ?, ?, ?, ?)`,
+		asBlob(crewIDUser), asBlob(rosterID), asBlob(userID)),
+		dutyDate, dutyDate, "2000-01-01 08:00:00", "2000-01-01 22:00:00", now, now).Error; err != nil {
+		t.Fatalf("seed user crew: %v", err)
+	}
+	if err := db.Exec(fmt.Sprintf(`INSERT INTO duty_roster_crews(id, roster_id, user_id, role_code, crew_type, name_label, mobile_phone, email, shift_start, shift_end, created_at, updated_at)
+		VALUES(%s, %s, NULL, 'other_person', 'main', 'Guest', '+62000', 'g@example.com', ?, ?, ?, ?)`,
+		asBlob(crewIDGuest), asBlob(rosterID)),
+		"2000-01-01 09:00:00", "2000-01-01 18:00:00", now, now).Error; err != nil {
+		t.Fatalf("seed guest crew: %v", err)
+	}
+
+	// softReplaceCrewByUser branches
+	if err := softReplaceCrewByUser(db, nil, "pilot", "main", userID, uuidv7.MustBytes()); err != nil {
+		t.Fatalf("softReplaceCrewByUser empty roster should be nil: %v", err)
+	}
+	if err := softReplaceCrewByUser(db, rosterID, "pilot", "main", userID, uuidv7.MustBytes()); err != nil {
+		t.Fatalf("softReplaceCrewByUser update branch failed: %v", err)
+	}
+
+	// crewExists branches (user/date nil and set)
+	existsGuest, err := crewExists(db, dutyroster.DutyRosterCrew{
+		RosterID:    rosterID,
+		RoleCode:    "other_person",
+		CrewType:    "main",
+		NameLabel:   "Guest",
+		MobilePhone: "+62000",
+		Email:       "g@example.com",
+		ShiftStart:  "2000-01-01 09:00:00",
+		ShiftEnd:    "2000-01-01 18:00:00",
+	})
+	if err != nil || !existsGuest {
+		t.Fatalf("expected guest crew exists, got exists=%v err=%v", existsGuest, err)
+	}
+
+	start := dutyDate
+	end := dutyDate
+	existsUser, err := crewExists(db, dutyroster.DutyRosterCrew{
+		RosterID:  rosterID,
+		UserID:    userID,
+		RoleCode:  "pilot",
+		CrewType:  "main",
+		DateStart: &start,
+		DateEnd:   &end,
+	})
+	if err != nil {
+		t.Fatalf("crewExists user branch err: %v", err)
+	}
+	if existsUser {
+		t.Fatalf("expected false after softReplaceCrewByUser (row should be deleted)")
+	}
+
+	// softDeleteCrewForDate branches
+	if err := softDeleteCrewForDate(db, []byte("base-not-exist"), dutyDate, dutyroster.DutyRosterCrew{
+		RoleCode: "pilot", CrewType: "main",
+	}, now, uuidv7.MustBytes()); err != nil {
+		t.Fatalf("softDeleteCrewForDate no roster branch should be nil: %v", err)
+	}
+	if err := softDeleteCrewForDate(db, baseID, dutyDate, dutyroster.DutyRosterCrew{
+		RoleCode:    "other_person",
+		CrewType:    "main",
+		NameLabel:   "Guest",
+		MobilePhone: "+62000",
+		Email:       "g@example.com",
+	}, now, uuidv7.MustBytes()); err != nil {
+		t.Fatalf("softDeleteCrewForDate guest branch failed: %v", err)
+	}
+
+	// matchCrewByFilter name_label/date/shift filter branch
+	if err := db.Exec(fmt.Sprintf(`INSERT INTO duty_roster_crews(id, roster_id, user_id, role_code, crew_type, name_label, mobile_phone, email, shift_start, shift_end, created_at, updated_at)
+		VALUES(%s, %s, NULL, 'other_person', 'main', 'Guest', '+62000', 'g@example.com', ?, ?, ?, ?)`,
+		asBlob([]byte("crew-helper-guest2")), asBlob(rosterID)),
+		"2000-01-01 09:00:00", "2000-01-01 18:00:00", now, now).Error; err != nil {
+		t.Fatalf("seed guest2 crew: %v", err)
+	}
+	rows, err := matchCrewByFilter(db, [][]byte{rosterID}, dutyroster.DutyRosterCrew{
+		RoleCode:    "other_person",
+		CrewType:    "main",
+		NameLabel:   "Guest",
+		MobilePhone: "+62000",
+		Email:       "g@example.com",
+	})
+	if err != nil || len(rows) == 0 {
+		t.Fatalf("expected matchCrewByFilter by name_label branch, got len=%d err=%v", len(rows), err)
+	}
+}
diff --git a/internal/repository/mysql/easa_release_repo.go b/internal/repository/mysql/easa_release_repo.go
new file mode 100644
index 0000000..b424eef
--- /dev/null
+++ b/internal/repository/mysql/easa_release_repo.go
@@ -0,0 +1,104 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	easarelease "wucher/internal/domain/easa_release"
+)
+
+type EASAReleaseRepository struct{ db *gorm.DB }
+
+func NewEASAReleaseRepository(db *gorm.DB) *EASAReleaseRepository {
+	return &EASAReleaseRepository{db: db}
+}
+
+func (r *EASAReleaseRepository) Create(ctx context.Context, row *easarelease.EASARelease) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *EASAReleaseRepository) Update(ctx context.Context, row *easarelease.EASARelease) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *EASAReleaseRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return r.db.WithContext(ctx).Model(&easarelease.EASARelease{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(map[string]any{"deleted_at": gorm.Expr("NOW(3)"), "deleted_by": deletedBy, "updated_by": deletedBy}).Error
+}
+
+func (r *EASAReleaseRepository) GetByID(ctx context.Context, id []byte) (*easarelease.EASARelease, error) {
+	var row easarelease.EASARelease
+	err := r.db.WithContext(ctx).
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *EASAReleaseRepository) GetByFlightID(ctx context.Context, flightID []byte) (*easarelease.EASARelease, error) {
+	var row easarelease.EASARelease
+	err := r.db.WithContext(ctx).
+		Where("flight_id = ? AND deleted_at IS NULL", flightID).
+		Order("created_at DESC").
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *EASAReleaseRepository) GetByComplaintID(ctx context.Context, complaintID []byte) (*easarelease.EASARelease, error) {
+	var row easarelease.EASARelease
+	err := r.db.WithContext(ctx).
+		Where("complaint_id = ? AND deleted_at IS NULL", complaintID).
+		Order("created_at DESC").
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *EASAReleaseRepository) ListByHelicopter(ctx context.Context, helicopterID []byte) ([]easarelease.EASARelease, error) {
+	rows := make([]easarelease.EASARelease, 0)
+	err := r.db.WithContext(ctx).
+		Where("helicopter_id = ? AND deleted_at IS NULL", helicopterID).
+		Order("created_at DESC").
+		Find(&rows).Error
+	return rows, err
+}
+
+func (r *EASAReleaseRepository) GetLatestByHelicopter(ctx context.Context, helicopterID []byte) (*easarelease.EASARelease, error) {
+	var row easarelease.EASARelease
+	err := r.db.WithContext(ctx).
+		Where("helicopter_id = ? AND deleted_at IS NULL", helicopterID).
+		Order("created_at DESC").
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *EASAReleaseRepository) GetActiveByHelicopter(ctx context.Context, helicopterID []byte) (*easarelease.EASARelease, error) {
+	var row easarelease.EASARelease
+	err := r.db.WithContext(ctx).
+		Where("helicopter_id = ? AND signed_at IS NOT NULL AND deleted_at IS NULL", helicopterID).
+		Order("signed_at DESC").
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *EASAReleaseRepository) VoidByID(ctx context.Context, id []byte, reason string, actor []byte) error {
+	return r.db.WithContext(ctx).Model(&easarelease.EASARelease{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(map[string]any{"deleted_at": gorm.Expr("NOW(3)"), "deleted_by": actor, "updated_by": actor}).Error
+}
diff --git a/internal/repository/mysql/email_outbox_repo.go b/internal/repository/mysql/email_outbox_repo.go
new file mode 100644
index 0000000..60da517
--- /dev/null
+++ b/internal/repository/mysql/email_outbox_repo.go
@@ -0,0 +1,165 @@
+package mysql
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"wucher/internal/domain/auth"
+)
+
+func (r *AuthRepository) WithTransaction(ctx context.Context, fn func(repo auth.Repository, outbox auth.EmailOutboxWriter) error) error {
+	if fn == nil {
+		return nil
+	}
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		txRepo := &AuthRepository{db: tx}
+		return fn(txRepo, txRepo)
+	})
+}
+
+func (r *AuthRepository) CreateEmailOutboxMessage(ctx context.Context, message *auth.EmailOutboxMessage) error {
+	if message == nil {
+		return gorm.ErrInvalidData
+	}
+	return r.db.WithContext(ctx).Create(message).Error
+}
+
+func (r *AuthRepository) ClaimPendingEmailOutboxMessages(
+	ctx context.Context,
+	limit int,
+	now time.Time,
+	lockTTL time.Duration,
+	workerID string,
+) ([]auth.EmailOutboxMessage, error) {
+	if limit <= 0 {
+		limit = 1
+	}
+	if lockTTL <= 0 {
+		lockTTL = time.Minute
+	}
+	now = now.UTC()
+	staleBefore := now.Add(-lockTTL)
+	workerID = strings.TrimSpace(workerID)
+	if workerID == "" {
+		workerID = "worker"
+	}
+
+	var messages []auth.EmailOutboxMessage
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.
+			Clauses(clause.Locking{Strength: "UPDATE", Options: "SKIP LOCKED"}).
+			Where(
+				"((status = ? AND available_at <= ?) OR (status = ? AND locked_at IS NOT NULL AND locked_at < ?))",
+				auth.EmailOutboxStatusPending,
+				now,
+				auth.EmailOutboxStatusProcessing,
+				staleBefore,
+			).
+			Order("available_at ASC, created_at ASC").
+			Limit(limit).
+			Find(&messages).Error; err != nil {
+			return err
+		}
+		if len(messages) == 0 {
+			return nil
+		}
+
+		ids := make([][]byte, 0, len(messages))
+		for i := range messages {
+			ids = append(ids, messages[i].ID)
+		}
+
+		if err := tx.Model(&auth.EmailOutboxMessage{}).
+			Where("id IN ?", ids).
+			Updates(map[string]any{
+				"status":     auth.EmailOutboxStatusProcessing,
+				"locked_at":  now,
+				"locked_by":  workerID,
+				"updated_at": now,
+				"attempts":   gorm.Expr("attempts + ?", 1),
+			}).Error; err != nil {
+			return err
+		}
+
+		for i := range messages {
+			messages[i].Status = auth.EmailOutboxStatusProcessing
+			messages[i].Attempts++
+			ts := now
+			messages[i].LockedAt = &ts
+			messages[i].LockedBy = workerID
+			messages[i].UpdatedAt = now
+		}
+		return nil
+	})
+	return messages, err
+}
+
+func (r *AuthRepository) MarkEmailOutboxMessagePublished(ctx context.Context, id []byte, publishedAt time.Time) error {
+	publishedAt = publishedAt.UTC()
+	return r.db.WithContext(ctx).
+		Model(&auth.EmailOutboxMessage{}).
+		Where("id = ?", id).
+		Updates(map[string]any{
+			"status":       auth.EmailOutboxStatusPublished,
+			"published_at": publishedAt,
+			"locked_at":    nil,
+			"locked_by":    "",
+			"last_error":   "",
+			"updated_at":   publishedAt,
+		}).Error
+}
+
+func (r *AuthRepository) MarkEmailOutboxMessageRetry(ctx context.Context, id []byte, availableAt time.Time, lastErr string) error {
+	availableAt = availableAt.UTC()
+	return r.db.WithContext(ctx).
+		Model(&auth.EmailOutboxMessage{}).
+		Where("id = ?", id).
+		Updates(map[string]any{
+			"status":       auth.EmailOutboxStatusPending,
+			"available_at": availableAt,
+			"locked_at":    nil,
+			"locked_by":    "",
+			"last_error":   truncateOutboxError(strings.TrimSpace(lastErr), 4096),
+			"updated_at":   time.Now().UTC(),
+		}).Error
+}
+
+func (r *AuthRepository) MarkEmailOutboxMessageDead(ctx context.Context, id []byte, failedAt time.Time, lastErr string) error {
+	failedAt = failedAt.UTC()
+	return r.db.WithContext(ctx).
+		Model(&auth.EmailOutboxMessage{}).
+		Where("id = ?", id).
+		Updates(map[string]any{
+			"status":       auth.EmailOutboxStatusDead,
+			"available_at": failedAt,
+			"locked_at":    nil,
+			"locked_by":    "",
+			"last_error":   truncateOutboxError(strings.TrimSpace(lastErr), 4096),
+			"updated_at":   failedAt,
+		}).Error
+}
+
+func (r *AuthRepository) CountPendingEmailOutboxMessages(ctx context.Context, now time.Time) (int64, error) {
+	var count int64
+	err := r.db.WithContext(ctx).
+		Model(&auth.EmailOutboxMessage{}).
+		Where(
+			"(status = ? AND available_at <= ?) OR status = ?",
+			auth.EmailOutboxStatusPending,
+			now.UTC(),
+			auth.EmailOutboxStatusProcessing,
+		).
+		Count(&count).Error
+	return count, err
+}
+
+func truncateOutboxError(v string, max int) string {
+	if max <= 0 || len(v) <= max {
+		return v
+	}
+	return v[:max]
+}
diff --git a/internal/repository/mysql/facility_repo.go b/internal/repository/mysql/facility_repo.go
new file mode 100644
index 0000000..ccaf4b3
--- /dev/null
+++ b/internal/repository/mysql/facility_repo.go
@@ -0,0 +1,91 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/facility"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type FacilityRepository struct {
+	db *gorm.DB
+}
+
+func NewFacilityRepository(db *gorm.DB) *FacilityRepository {
+	return &FacilityRepository{db: db}
+}
+
+func (r *FacilityRepository) Create(ctx context.Context, f *facility.Facility) error {
+	requestedIsActive := f.IsActive
+	db := r.db.WithContext(ctx)
+	if err := db.Create(f).Error; err != nil {
+		return err
+	}
+	return db.Model(&facility.Facility{}).Where("id = ?", f.ID).UpdateColumn("is_active", requestedIsActive).Error
+}
+
+func (r *FacilityRepository) Update(ctx context.Context, f *facility.Facility) error {
+	return r.db.WithContext(ctx).Save(f).Error
+}
+
+func (r *FacilityRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "facilities", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&facility.Facility{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error)
+}
+
+func (r *FacilityRepository) GetByID(ctx context.Context, id []byte) (*facility.Facility, error) {
+	var f facility.Facility
+	err := r.db.WithContext(ctx).Where("id = ? AND deleted_at IS NULL", id).First(&f).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &f, err
+}
+
+func (r *FacilityRepository) List(ctx context.Context, filter, category, sort string, limit, offset int) ([]facility.Facility, int64, error) {
+	var facilities []facility.Facility
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&facility.Facility{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("name LIKE ? OR type LIKE ? OR length LIKE ? OR weight LIKE ?", like, like, like, like)
+	}
+	if category != "" {
+		base = base.Where("category = ?", category)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("facilities", "is_active", "sortkey", "name", false) {
+			query = query.Order(clause)
+		}
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&facilities).Error; err != nil {
+		return nil, 0, err
+	}
+	return facilities, total, nil
+}
diff --git a/internal/repository/mysql/facility_repo_test.go b/internal/repository/mysql/facility_repo_test.go
new file mode 100644
index 0000000..0aebee4
--- /dev/null
+++ b/internal/repository/mysql/facility_repo_test.go
@@ -0,0 +1,252 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/facility"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openFacilityTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:facility_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&facility.Facility{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestNewFacilityRepository(t *testing.T) {
+	db := openFacilityTestDB(t)
+	repo := NewFacilityRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestFacilityRepositoryCreate(t *testing.T) {
+	db := openFacilityTestDB(t)
+	repo := NewFacilityRepository(db)
+	row := &facility.Facility{Category: "HEMS", Name: "Stretcher", Type: "Cabin", Length: "2m", Weight: "5kg"}
+
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(row.ID) == 0 {
+		t.Fatalf("expected id set")
+	}
+	inactive := &facility.Facility{Category: "HEMS", Name: "Inactive", Type: "Cabin", IsActive: false}
+	if err := repo.Create(context.Background(), inactive); err != nil {
+		t.Fatalf("create inactive: %v", err)
+	}
+	gotInactive, err := repo.GetByID(context.Background(), inactive.ID)
+	if err != nil {
+		t.Fatalf("get inactive: %v", err)
+	}
+	if gotInactive == nil || gotInactive.IsActive {
+		t.Fatalf("expected inactive facility persisted as false")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Create(context.Background(), &facility.Facility{Category: "HEMS", Name: "AfterClose", Type: "X"}); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestFacilityRepositoryUpdate(t *testing.T) {
+	db := openFacilityTestDB(t)
+	repo := NewFacilityRepository(db)
+	row := &facility.Facility{Category: "HEMS", Name: "Old", Type: "Cabin"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Name = "New"
+	row.Type = "External"
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil || loaded == nil || loaded.Name != "New" || loaded.Type != "External" {
+		t.Fatalf("expected updated row")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestFacilityRepositoryDelete(t *testing.T) {
+	db := openFacilityTestDB(t)
+	repo := NewFacilityRepository(db)
+	row := &facility.Facility{Category: "HEMS", Name: "DeleteMe", Type: "Cabin"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	if err := repo.Delete(context.Background(), row.ID, nil); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected row deleted")
+	}
+}
+
+func TestFacilityRepositoryGetByID(t *testing.T) {
+	t.Run("found", func(t *testing.T) {
+		db := openFacilityTestDB(t)
+		repo := NewFacilityRepository(db)
+		row := &facility.Facility{Category: "HEMS", Name: "Found", Type: "Cabin"}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		got, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.Name != "Found" {
+			t.Fatalf("expected row found")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openFacilityTestDB(t)
+		repo := NewFacilityRepository(db)
+		got, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil for not found")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openFacilityTestDB(t)
+		repo := NewFacilityRepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, err := repo.GetByID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
+
+func TestFacilityRepositoryList(t *testing.T) {
+	t.Run("success without limit", func(t *testing.T) {
+		db := openFacilityTestDB(t)
+		repo := NewFacilityRepository(db)
+		_ = repo.Create(context.Background(), &facility.Facility{Category: "HEMS", Name: "A", Type: "Cabin", Length: "1m", Weight: "1kg"})
+		_ = repo.Create(context.Background(), &facility.Facility{Category: "Dry", Name: "B", Type: "External", Length: "2m", Weight: "2kg"})
+
+		rows, total, err := repo.List(context.Background(), "", "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("expected 2 rows, total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("success with filter category sort and limit", func(t *testing.T) {
+		db := openFacilityTestDB(t)
+		repo := NewFacilityRepository(db)
+		_ = repo.Create(context.Background(), &facility.Facility{Category: "HEMS", Name: "Main Basket", Type: "Basket", Length: "12", Weight: "30"})
+		_ = repo.Create(context.Background(), &facility.Facility{Category: "Dry", Name: "Dry Basket", Type: "Basket", Length: "10", Weight: "20"})
+
+		rows, total, err := repo.List(context.Background(), "Main", "HEMS", "name DESC", 1, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].Name != "Main Basket" {
+			t.Fatalf("unexpected list result")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openFacilityTestDB(t)
+		repo := NewFacilityRepository(db)
+		if err := db.Migrator().DropTable(&facility.Facility{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+
+		if _, _, err := repo.List(context.Background(), "", "", "", 10, 0); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openFacilityTestDB(t)
+		repo := NewFacilityRepository(db)
+		_ = repo.Create(context.Background(), &facility.Facility{Category: "HEMS", Name: "Main", Type: "Basket"})
+
+		if _, _, err := repo.List(context.Background(), "", "", "name ASC, )", 10, 0); err == nil {
+			t.Fatalf("expected find error from invalid sort")
+		}
+	})
+
+	t.Run("default order active sortkey first and inactive last", func(t *testing.T) {
+		db := openFacilityTestDB(t)
+		repo := NewFacilityRepository(db)
+		_ = repo.Create(context.Background(), &facility.Facility{Category: "HEMS", Name: "Gamma", Type: "A", IsActive: true})
+		_ = repo.Create(context.Background(), &facility.Facility{Category: "HEMS", Name: "Beta", Type: "A", SortKey: intPtrFacility(0), IsActive: true})
+		_ = repo.Create(context.Background(), &facility.Facility{Category: "HEMS", Name: "Charlie", Type: "A", SortKey: intPtrFacility(2), IsActive: true})
+		_ = repo.Create(context.Background(), &facility.Facility{Category: "HEMS", Name: "Alpha", Type: "A", SortKey: intPtrFacility(1), IsActive: true})
+		_ = repo.Create(context.Background(), &facility.Facility{Category: "HEMS", Name: "Zulu", Type: "A", IsActive: false})
+		_ = repo.Create(context.Background(), &facility.Facility{Category: "HEMS", Name: "Bravo", Type: "A", SortKey: intPtrFacility(9), IsActive: false})
+
+		rows, total, err := repo.List(context.Background(), "", "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 6 || len(rows) != 6 {
+			t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+		}
+
+		gotOrder := []string{
+			rows[0].Name,
+			rows[1].Name,
+			rows[2].Name,
+			rows[3].Name,
+			rows[4].Name,
+			rows[5].Name,
+		}
+		wantOrder := []string{
+			"Beta",
+			"Alpha",
+			"Charlie",
+			"Gamma",
+			"Bravo",
+			"Zulu",
+		}
+		for i := range wantOrder {
+			if gotOrder[i] != wantOrder[i] {
+				t.Fatalf("unexpected default order: got=%v want=%v", gotOrder, wantOrder)
+			}
+		}
+	})
+}
+
+func intPtrFacility(v int) *int { return &v }
diff --git a/internal/repository/mysql/federal_state_repo.go b/internal/repository/mysql/federal_state_repo.go
new file mode 100644
index 0000000..08ac25d
--- /dev/null
+++ b/internal/repository/mysql/federal_state_repo.go
@@ -0,0 +1,241 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/federal_state"
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type FederalStateRepository struct {
+	db     *gorm.DB
+	schema federalStateSchema
+}
+
+func NewFederalStateRepository(db *gorm.DB) *FederalStateRepository {
+	probe := newSchemaCache(db)
+	schema := federalStateSchema{}
+
+	schema.hasFederalStatesTable = probe.HasTable("federal_states")
+	schema.federalStatesHasName = schema.hasFederalStatesTable && probe.HasColumn("federal_states", "name")
+
+	schema.hasInsurancePatientDataTable = probe.HasTable("insurance_patient_data")
+	if schema.hasInsurancePatientDataTable {
+		schema.insurancePatientDataHasFederalStateID = probe.HasColumn("insurance_patient_data", "federal_state_id")
+		schema.insurancePatientDataHasState = probe.HasColumn("insurance_patient_data", "state")
+		schema.insurancePatientDataHasDeletedAt = probe.HasColumn("insurance_patient_data", "deleted_at")
+	}
+
+	schema.hasHealthInsuranceCompaniesTable = probe.HasTable("health_insurance_companies")
+	if schema.hasHealthInsuranceCompaniesTable {
+		schema.healthInsuranceCompaniesHasFederalStateID = probe.HasColumn("health_insurance_companies", "federal_state_id")
+		schema.healthInsuranceCompaniesHasState = probe.HasColumn("health_insurance_companies", "state")
+		schema.healthInsuranceCompaniesHasDeletedAt = probe.HasColumn("health_insurance_companies", "deleted_at")
+	}
+
+	schema.hasIcaosTable = probe.HasTable("icaos")
+	if schema.hasIcaosTable {
+		schema.icaosHasFederalStateID = probe.HasColumn("icaos", "federal_state_id")
+		schema.icaosHasDeletedAt = probe.HasColumn("icaos", "deleted_at")
+	}
+
+	return &FederalStateRepository{db: db, schema: schema}
+}
+
+func (r *FederalStateRepository) Create(ctx context.Context, row *federal_state.FederalState) error {
+	requestedIsActive := row.IsActive
+	db := r.db.WithContext(ctx)
+	if err := db.Create(row).Error; err != nil {
+		return err
+	}
+	return db.Model(&federal_state.FederalState{}).Where("id = ?", row.ID).UpdateColumn("is_active", requestedIsActive).Error
+}
+
+func (r *FederalStateRepository) Update(ctx context.Context, row *federal_state.FederalState) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *FederalStateRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "federal_states", id); err != nil {
+		return err
+	}
+	if err := r.ensureNoFederalStateUsage(ctx, id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&federal_state.FederalState{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error)
+}
+
+func (r *FederalStateRepository) ensureNoFederalStateUsage(ctx context.Context, id []byte) error {
+	if len(id) != 16 {
+		return nil
+	}
+	related := make([]string, 0, 3)
+	db := r.db.WithContext(ctx)
+	stateName := ""
+	if r.schema.hasFederalStatesTable && r.schema.federalStatesHasName {
+		_ = db.Table("federal_states").Select("name").Where("id = ?", id).Limit(1).Scan(&stateName).Error
+	}
+	stateName = strings.TrimSpace(stateName)
+
+	if r.schema.hasInsurancePatientDataTable {
+		conditions := make([]string, 0, 2)
+		args := make([]any, 0, 2)
+		if r.schema.insurancePatientDataHasFederalStateID {
+			conditions = append(conditions, "federal_state_id = ?")
+			args = append(args, id)
+		}
+		if stateName != "" && r.schema.insurancePatientDataHasState {
+			conditions = append(conditions, "LOWER(TRIM(state)) = LOWER(TRIM(?))")
+			args = append(args, stateName)
+		}
+		if len(conditions) == 0 {
+			goto checkHealthInsuranceCompanies
+		}
+		query := db.Table("insurance_patient_data").Where("("+strings.Join(conditions, " OR ")+")", args...)
+		if r.schema.insurancePatientDataHasDeletedAt {
+			query = query.Where("deleted_at IS NULL")
+		}
+		var count int64
+		if err := query.Count(&count).Error; err != nil {
+			return err
+		}
+		if count > 0 {
+			related = append(related, "insurance patient data")
+		}
+	}
+
+checkHealthInsuranceCompanies:
+	if r.schema.hasHealthInsuranceCompaniesTable {
+		conditions := make([]string, 0, 2)
+		args := make([]any, 0, 2)
+		if r.schema.healthInsuranceCompaniesHasFederalStateID {
+			conditions = append(conditions, "federal_state_id = ?")
+			args = append(args, id)
+		}
+		if stateName != "" && r.schema.healthInsuranceCompaniesHasState {
+			conditions = append(conditions, "LOWER(TRIM(state)) = LOWER(TRIM(?))")
+			args = append(args, stateName)
+		}
+		if len(conditions) == 0 {
+			goto checkICAOs
+		}
+		query := db.Table("health_insurance_companies").Where("("+strings.Join(conditions, " OR ")+")", args...)
+		if r.schema.healthInsuranceCompaniesHasDeletedAt {
+			query = query.Where("deleted_at IS NULL")
+		}
+		var count int64
+		if err := query.Count(&count).Error; err != nil {
+			return err
+		}
+		if count > 0 {
+			related = append(related, "health insurance companies")
+		}
+	}
+
+checkICAOs:
+	if r.schema.hasIcaosTable {
+		if !r.schema.icaosHasFederalStateID {
+			goto finalize
+		}
+		var count int64
+		query := db.Table("icaos").Where("federal_state_id = ?", id)
+		if r.schema.icaosHasDeletedAt {
+			query = query.Where("deleted_at IS NULL")
+		}
+		if err := query.Count(&count).Error; err != nil {
+			return err
+		}
+		if count > 0 {
+			related = append(related, "icaos")
+		}
+	}
+
+finalize:
+	if len(related) > 0 {
+		return apperrors.NewDeleteConflictError(related...)
+	}
+	return nil
+}
+
+type federalStateSchema struct {
+	hasFederalStatesTable                     bool
+	federalStatesHasName                      bool
+	hasInsurancePatientDataTable              bool
+	insurancePatientDataHasFederalStateID     bool
+	insurancePatientDataHasState              bool
+	insurancePatientDataHasDeletedAt          bool
+	hasHealthInsuranceCompaniesTable          bool
+	healthInsuranceCompaniesHasFederalStateID bool
+	healthInsuranceCompaniesHasState          bool
+	healthInsuranceCompaniesHasDeletedAt      bool
+	hasIcaosTable                             bool
+	icaosHasFederalStateID                    bool
+	icaosHasDeletedAt                         bool
+}
+
+func (r *FederalStateRepository) GetByID(ctx context.Context, id []byte) (*federal_state.FederalState, error) {
+	var row federal_state.FederalState
+	err := r.db.WithContext(ctx).
+		Preload("Land", "deleted_at IS NULL").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FederalStateRepository) List(ctx context.Context, filter, sort string, limit, offset int, landID []byte, landName string) ([]federal_state.FederalState, int64, error) {
+	var rows []federal_state.FederalState
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&federal_state.FederalState{}).Where("federal_states.deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("federal_states.name LIKE ?", like)
+	}
+	if len(landID) > 0 {
+		base = base.Where("federal_states.land_id = ?", landID)
+	}
+	if trimmedLandName := strings.TrimSpace(landName); trimmedLandName != "" {
+		likeLandName := "%" + trimmedLandName + "%"
+		base = base.Joins("JOIN lands ON lands.id = federal_states.land_id AND lands.deleted_at IS NULL").
+			Where("lands.name LIKE ?", likeLandName)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("federal_states", "is_active", "sortkey", "name", false) {
+			query = query.Order(clause)
+		}
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	query = query.Preload("Land", "deleted_at IS NULL")
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/federal_state_repo_test.go b/internal/repository/mysql/federal_state_repo_test.go
new file mode 100644
index 0000000..a3f1a7b
--- /dev/null
+++ b/internal/repository/mysql/federal_state_repo_test.go
@@ -0,0 +1,372 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/federal_state"
+	"wucher/internal/domain/land"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openFederalStateTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:federal_state_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&land.Land{}); err != nil {
+		t.Fatalf("auto migrate land: %v", err)
+	}
+	if err := db.AutoMigrate(&federal_state.FederalState{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestNewFederalStateRepository(t *testing.T) {
+	db := openFederalStateTestDB(t)
+	repo := NewFederalStateRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestFederalStateRepositoryCreate(t *testing.T) {
+	db := openFederalStateTestDB(t)
+	repo := NewFederalStateRepository(db)
+	row := &federal_state.FederalState{Name: "Main"}
+
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(row.ID) == 0 {
+		t.Fatalf("expected id set")
+	}
+	inactive := &federal_state.FederalState{Name: "Inactive", IsActive: false}
+	if err := repo.Create(context.Background(), inactive); err != nil {
+		t.Fatalf("create inactive: %v", err)
+	}
+	gotInactive, err := repo.GetByID(context.Background(), inactive.ID)
+	if err != nil {
+		t.Fatalf("get inactive: %v", err)
+	}
+	if gotInactive == nil || gotInactive.IsActive {
+		t.Fatalf("expected inactive federal state persisted as false")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Create(context.Background(), &federal_state.FederalState{Name: "AfterClose"}); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestFederalStateRepositoryUpdate(t *testing.T) {
+	db := openFederalStateTestDB(t)
+	repo := NewFederalStateRepository(db)
+	row := &federal_state.FederalState{Name: "Old"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Name = "New"
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil || loaded == nil || loaded.Name != "New" {
+		t.Fatalf("expected updated row")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestFederalStateRepositoryDelete(t *testing.T) {
+	db := openFederalStateTestDB(t)
+	repo := NewFederalStateRepository(db)
+	row := &federal_state.FederalState{Name: "DeleteMe"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	deletedBy := uuidv7.MustBytes()
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected soft deleted row hidden from GetByID")
+	}
+}
+
+func TestFederalStateRepositoryDelete_BlockedWhenUsedByInsurancePatientData(t *testing.T) {
+	db := openFederalStateTestDB(t)
+
+	if err := db.Exec(`CREATE TABLE IF NOT EXISTS insurance_patient_data (
+		id BLOB PRIMARY KEY,
+		federal_state_id BLOB NULL,
+		deleted_at DATETIME NULL
+	)`).Error; err != nil {
+		t.Fatalf("create insurance_patient_data table: %v", err)
+	}
+	repo := NewFederalStateRepository(db)
+
+	row := &federal_state.FederalState{Name: "InUse"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	if err := db.Table("insurance_patient_data").Create(map[string]any{
+		"id":               uuidv7.MustBytes(),
+		"federal_state_id": row.ID,
+		"deleted_at":       nil,
+	}).Error; err != nil {
+		t.Fatalf("seed insurance_patient_data: %v", err)
+	}
+
+	err := repo.Delete(context.Background(), row.ID, uuidv7.MustBytes())
+	if err == nil {
+		t.Fatalf("expected delete to be blocked")
+	}
+	if !strings.Contains(strings.ToLower(err.Error()), "insurance patient data") {
+		t.Fatalf("expected dependency detail in error, got: %v", err)
+	}
+}
+
+func TestFederalStateRepositoryDelete_BlockedWhenUsedByICAO(t *testing.T) {
+	db := openFederalStateTestDB(t)
+
+	if err := db.Exec(`CREATE TABLE IF NOT EXISTS icaos (
+		id BLOB PRIMARY KEY,
+		federal_state_id BLOB NULL,
+		deleted_at DATETIME NULL
+	)`).Error; err != nil {
+		t.Fatalf("create icaos table: %v", err)
+	}
+	repo := NewFederalStateRepository(db)
+
+	row := &federal_state.FederalState{Name: "InUseByICAO"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	if err := db.Table("icaos").Create(map[string]any{
+		"id":               uuidv7.MustBytes(),
+		"federal_state_id": row.ID,
+		"deleted_at":       nil,
+	}).Error; err != nil {
+		t.Fatalf("seed icaos: %v", err)
+	}
+
+	err := repo.Delete(context.Background(), row.ID, uuidv7.MustBytes())
+	if err == nil {
+		t.Fatalf("expected delete to be blocked")
+	}
+	if !strings.Contains(strings.ToLower(err.Error()), "icaos") {
+		t.Fatalf("expected dependency detail in error, got: %v", err)
+	}
+}
+
+func TestFederalStateRepositoryDelete_BlockedWhenUsedByLegacyStateColumn(t *testing.T) {
+	db := openFederalStateTestDB(t)
+
+	if err := db.Exec(`CREATE TABLE IF NOT EXISTS health_insurance_companies (
+		id BLOB PRIMARY KEY,
+		state TEXT NULL,
+		deleted_at DATETIME NULL
+	)`).Error; err != nil {
+		t.Fatalf("create health_insurance_companies table: %v", err)
+	}
+	repo := NewFederalStateRepository(db)
+
+	row := &federal_state.FederalState{Name: "Bayern"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	if err := db.Table("health_insurance_companies").Create(map[string]any{
+		"id":         uuidv7.MustBytes(),
+		"state":      "Bayern",
+		"deleted_at": nil,
+	}).Error; err != nil {
+		t.Fatalf("seed health_insurance_companies: %v", err)
+	}
+
+	err := repo.Delete(context.Background(), row.ID, uuidv7.MustBytes())
+	if err == nil {
+		t.Fatalf("expected delete to be blocked")
+	}
+	if !strings.Contains(strings.ToLower(err.Error()), "health insurance companies") {
+		t.Fatalf("expected dependency detail in error, got: %v", err)
+	}
+}
+
+func TestFederalStateRepositoryGetByID(t *testing.T) {
+	t.Run("found", func(t *testing.T) {
+		db := openFederalStateTestDB(t)
+		repo := NewFederalStateRepository(db)
+		row := &federal_state.FederalState{Name: "Found"}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		got, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.Name != "Found" {
+			t.Fatalf("expected row found")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openFederalStateTestDB(t)
+		repo := NewFederalStateRepository(db)
+		got, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil for not found")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openFederalStateTestDB(t)
+		repo := NewFederalStateRepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, err := repo.GetByID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
+
+func TestFederalStateRepositoryList(t *testing.T) {
+	t.Run("success without limit", func(t *testing.T) {
+		db := openFederalStateTestDB(t)
+		repo := NewFederalStateRepository(db)
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "C"})
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "A"})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0, nil, "")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("expected 2 rows, total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("success with filter sort and limit", func(t *testing.T) {
+		db := openFederalStateTestDB(t)
+		repo := NewFederalStateRepository(db)
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "Main Base"})
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "Backup"})
+
+		rows, total, err := repo.List(context.Background(), "Main", "name DESC", 1, 0, nil, "")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].Name != "Main Base" {
+			t.Fatalf("unexpected list result")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openFederalStateTestDB(t)
+		repo := NewFederalStateRepository(db)
+		if err := db.Migrator().DropTable(&federal_state.FederalState{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+
+		if _, _, err := repo.List(context.Background(), "", "", 10, 0, nil, ""); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openFederalStateTestDB(t)
+		repo := NewFederalStateRepository(db)
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "Main"})
+
+		if _, _, err := repo.List(context.Background(), "", "name ASC, )", 10, 0, nil, ""); err == nil {
+			t.Fatalf("expected find error from invalid sort")
+		}
+	})
+
+	t.Run("default order active sortkey first and inactive last", func(t *testing.T) {
+		db := openFederalStateTestDB(t)
+		repo := NewFederalStateRepository(db)
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "Gamma", IsActive: true})
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "Beta", SortKey: intPtrFederalStateRepo(0), IsActive: true})
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "Charlie", SortKey: intPtrFederalStateRepo(2), IsActive: true})
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "Alpha", SortKey: intPtrFederalStateRepo(1), IsActive: true})
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "Zulu", IsActive: false})
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "Bravo", SortKey: intPtrFederalStateRepo(9), IsActive: false})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0, nil, "")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 6 || len(rows) != 6 {
+			t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+		}
+
+		gotOrder := []string{rows[0].Name, rows[1].Name, rows[2].Name, rows[3].Name, rows[4].Name, rows[5].Name}
+		wantOrder := []string{"Beta", "Alpha", "Charlie", "Gamma", "Bravo", "Zulu"}
+		for i := range wantOrder {
+			if gotOrder[i] != wantOrder[i] {
+				t.Fatalf("unexpected default order: got=%v want=%v", gotOrder, wantOrder)
+			}
+		}
+	})
+
+	t.Run("success with land_id and land_name filter", func(t *testing.T) {
+		db := openFederalStateTestDB(t)
+		repo := NewFederalStateRepository(db)
+		deLand := &land.Land{Name: "Germany", LandISOCode: "DE"}
+		frLand := &land.Land{Name: "France", LandISOCode: "FR"}
+		if err := db.Create(deLand).Error; err != nil {
+			t.Fatalf("create de land: %v", err)
+		}
+		if err := db.Create(frLand).Error; err != nil {
+			t.Fatalf("create fr land: %v", err)
+		}
+
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "Bayern", LandID: deLand.ID})
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "Berlin", LandID: deLand.ID})
+		_ = repo.Create(context.Background(), &federal_state.FederalState{Name: "Paris", LandID: frLand.ID})
+
+		rows, total, err := repo.List(context.Background(), "", "federal_states.name ASC", 10, 0, deLand.ID, "Ger")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("unexpected filtered result total=%d len=%d", total, len(rows))
+		}
+		for _, row := range rows {
+			if row.Name == "Paris" {
+				t.Fatalf("expected france row excluded")
+			}
+		}
+	})
+}
+
+func intPtrFederalStateRepo(v int) *int { return &v }
diff --git a/internal/repository/mysql/file_manager_attachment_repo.go b/internal/repository/mysql/file_manager_attachment_repo.go
new file mode 100644
index 0000000..d75b293
--- /dev/null
+++ b/internal/repository/mysql/file_manager_attachment_repo.go
@@ -0,0 +1,104 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+)
+
+type FileManagerAttachmentRepository struct {
+	db *gorm.DB
+}
+
+func NewFileManagerAttachmentRepository(db *gorm.DB) *FileManagerAttachmentRepository {
+	return &FileManagerAttachmentRepository{db: db}
+}
+
+func (r *FileManagerAttachmentRepository) Create(ctx context.Context, row *filemanager.Attachment) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *FileManagerAttachmentRepository) Delete(ctx context.Context, id []byte) error {
+	res := r.db.WithContext(ctx).Where("id = ?", id).Delete(&filemanager.Attachment{})
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *FileManagerAttachmentRepository) GetByID(ctx context.Context, id []byte) (*filemanager.Attachment, error) {
+	var row filemanager.Attachment
+	err := r.db.WithContext(ctx).
+		Preload("File").
+		Where("id = ?", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FileManagerAttachmentRepository) GetByRefAndFile(ctx context.Context, refType, refID string, fileID []byte) (*filemanager.Attachment, error) {
+	refType = strings.ToLower(strings.TrimSpace(refType))
+	refID = strings.TrimSpace(refID)
+	if refType == "" || refID == "" || len(fileID) == 0 {
+		return nil, nil
+	}
+
+	var row filemanager.Attachment
+	err := r.db.WithContext(ctx).
+		Where("ref_type = ? AND ref_id = ? AND file_id = ?", refType, refID, fileID).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FileManagerAttachmentRepository) ListByReference(ctx context.Context, filter filemanager.AttachmentListFilter) ([]filemanager.Attachment, int64, error) {
+	refType := strings.ToLower(strings.TrimSpace(filter.RefType))
+	refID := strings.TrimSpace(filter.RefID)
+	if refType == "" || refID == "" {
+		return []filemanager.Attachment{}, 0, nil
+	}
+
+	var rows []filemanager.Attachment
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&filemanager.Attachment{}).
+		Preload("File").
+		Where("ref_type = ? AND ref_id = ?", refType, refID)
+
+	if filter.Category != nil {
+		category := strings.TrimSpace(*filter.Category)
+		if category == "" {
+			base = base.Where("category IS NULL")
+		} else {
+			base = base.Where("category = ?", category)
+		}
+	}
+
+	query := base
+	if strings.TrimSpace(filter.Sort) != "" {
+		query = query.Order(filter.Sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if filter.Limit > 0 {
+		query = query.Limit(filter.Limit).Offset(filter.Offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/file_manager_file_repo.go b/internal/repository/mysql/file_manager_file_repo.go
new file mode 100644
index 0000000..a1d493a
--- /dev/null
+++ b/internal/repository/mysql/file_manager_file_repo.go
@@ -0,0 +1,492 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type FileManagerFileRepository struct {
+	db *gorm.DB
+}
+
+func NewFileManagerFileRepository(db *gorm.DB) *FileManagerFileRepository {
+	return &FileManagerFileRepository{db: db}
+}
+
+func (r *FileManagerFileRepository) Create(ctx context.Context, row *filemanager.File) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *FileManagerFileRepository) Update(ctx context.Context, row *filemanager.File) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *FileManagerFileRepository) TransitionStatus(ctx context.Context, params filemanager.FileStatusTransitionParams) error {
+	expectedFrom := filemanager.NormalizeFileStatus(params.ExpectedFrom)
+	toStatus := filemanager.NormalizeFileStatus(params.To)
+	if expectedFrom == "" || toStatus == "" {
+		return filemanager.ErrInvalidFileStatusTransition
+	}
+	if !filemanager.CanTransitionFileStatus(expectedFrom, toStatus) {
+		return filemanager.ErrInvalidFileStatusTransition
+	}
+
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"status":     toStatus,
+		"updated_by": params.UpdatedBy,
+	}
+	switch toStatus {
+	case filemanager.FileStatusProcessing:
+		startedAt := now
+		if params.ProcessingStartedAt != nil {
+			startedAt = params.ProcessingStartedAt.UTC()
+		}
+		updates["processing_started_at"] = startedAt
+		updates["processed_at"] = nil
+		updates["validated_at"] = nil
+		updates["failed_at"] = nil
+		updates["failure_reason"] = nil
+		updates["upload_error"] = ""
+	case filemanager.FileStatusValidated:
+		processedAt := now
+		if params.ProcessedAt != nil {
+			processedAt = params.ProcessedAt.UTC()
+		}
+		validatedAt := processedAt
+		if params.ValidatedAt != nil {
+			validatedAt = params.ValidatedAt.UTC()
+		}
+		updates["processed_at"] = processedAt
+		updates["validated_at"] = validatedAt
+		updates["failed_at"] = nil
+		updates["failure_reason"] = nil
+		updates["upload_error"] = ""
+	case filemanager.FileStatusFailed:
+		processedAt := now
+		if params.ProcessedAt != nil {
+			processedAt = params.ProcessedAt.UTC()
+		}
+		failedAt := now
+		if params.FailedAt != nil {
+			failedAt = params.FailedAt.UTC()
+		}
+		reason := "file processing failed"
+		if params.FailureReason != nil {
+			clean := strings.TrimSpace(*params.FailureReason)
+			if clean != "" {
+				reason = clean
+			}
+		}
+		updates["processed_at"] = processedAt
+		updates["failed_at"] = failedAt
+		updates["validated_at"] = nil
+		updates["failure_reason"] = reason
+		updates["upload_error"] = reason
+	}
+
+	res := r.db.WithContext(ctx).
+		Model(&filemanager.File{}).
+		Where("id = ? AND deleted_at IS NULL AND status = ?", params.ID, expectedFrom).
+		Updates(updates)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *FileManagerFileRepository) Finalize(ctx context.Context, params filemanager.FileFinalizeParams) error {
+	expectedFrom := filemanager.NormalizeFileStatus(params.ExpectedFrom)
+	if expectedFrom == "" {
+		expectedFrom = filemanager.FileStatusValidated
+	}
+
+	updates := map[string]any{
+		"folder_id":       params.FolderID,
+		"name":            params.Name,
+		"name_normalized": params.NameNormalized,
+		"extension":       params.Extension,
+		"status":          filemanager.FileStatusReady,
+		"name_slot":       "live",
+		"upload_error":    "",
+		"failure_reason":  nil,
+		"updated_by":      params.UpdatedBy,
+	}
+
+	res := r.db.WithContext(ctx).
+		Model(&filemanager.File{}).
+		Where("id = ? AND deleted_at IS NULL AND status = ?", params.ID, expectedFrom).
+		Updates(updates)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *FileManagerFileRepository) Delete(ctx context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error {
+	now := time.Now().UTC()
+	nameSlot := deletedNameSlot(id)
+	updates := map[string]any{
+		"status":     filemanager.FileStatusTrashed,
+		"trashed_at": now,
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+		"name_slot":  nameSlot,
+	}
+	if purgeAt != nil {
+		v := purgeAt.UTC()
+		updates["purge_at"] = v
+	}
+
+	res := r.db.WithContext(ctx).
+		Model(&filemanager.File{}).
+		Where("id = ? AND deleted_at IS NULL AND status = ?", id, filemanager.FileStatusReady).
+		Updates(updates)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *FileManagerFileRepository) Restore(ctx context.Context, id []byte, restoredBy []byte) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var row filemanager.File
+		if err := tx.Model(&filemanager.File{}).Where("id = ?", id).First(&row).Error; err != nil {
+			return err
+		}
+		if row.DeletedAt == nil {
+			return gorm.ErrRecordNotFound
+		}
+
+		var total int64
+		if err := tx.Model(&filemanager.File{}).
+			Where("folder_id = ? AND name_normalized = ? AND name_slot = 'live' AND deleted_at IS NULL", row.FolderID, row.NameNormalized).
+			Count(&total).Error; err != nil {
+			return err
+		}
+		if total > 0 {
+			return gorm.ErrDuplicatedKey
+		}
+
+		updates := map[string]any{
+			"status":     filemanager.FileStatusReady,
+			"trashed_at": nil,
+			"deleted_at": nil,
+			"deleted_by": nil,
+			"purge_at":   nil,
+			"updated_by": restoredBy,
+			"name_slot":  "live",
+		}
+		res := tx.Model(&filemanager.File{}).
+			Where("id = ? AND deleted_at IS NOT NULL AND status = ?", id, filemanager.FileStatusTrashed).
+			Updates(updates)
+		if res.Error != nil {
+			return res.Error
+		}
+		if res.RowsAffected == 0 {
+			return gorm.ErrRecordNotFound
+		}
+		return nil
+	})
+}
+
+func (r *FileManagerFileRepository) Purge(ctx context.Context, id []byte) error {
+	res := r.db.WithContext(ctx).
+		Where("id = ?", id).
+		Delete(&filemanager.File{})
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *FileManagerFileRepository) GetByID(ctx context.Context, id []byte) (*filemanager.File, error) {
+	var row filemanager.File
+	err := r.db.WithContext(ctx).
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FileManagerFileRepository) GetByIDAny(ctx context.Context, id []byte) (*filemanager.File, error) {
+	var row filemanager.File
+	err := r.db.WithContext(ctx).
+		Where("id = ?", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FileManagerFileRepository) GetByObjectKey(ctx context.Context, objectKey string) (*filemanager.File, error) {
+	objectKey = strings.TrimSpace(objectKey)
+	if objectKey == "" {
+		return nil, nil
+	}
+
+	var row filemanager.File
+	err := r.db.WithContext(ctx).
+		Where("object_key = ? AND deleted_at IS NULL", objectKey).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FileManagerFileRepository) GetByFolderAndName(ctx context.Context, folderID []byte, nameNormalized string) (*filemanager.File, error) {
+	var row filemanager.File
+	err := r.db.WithContext(ctx).
+		Where("folder_id = ? AND name_normalized = ? AND name_slot = 'live' AND deleted_at IS NULL", folderID, nameNormalized).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FileManagerFileRepository) GetByTemplateAndTakeover(ctx context.Context, templateUUID, takeoverID []byte) (*filemanager.File, error) {
+	if len(templateUUID) != 16 || len(takeoverID) != 16 {
+		return nil, nil
+	}
+
+	var row filemanager.File
+	err := r.db.WithContext(ctx).
+		Where("template_uuid = ? AND takeover_id = ? AND deleted_at IS NULL", templateUUID, takeoverID).
+		Order("updated_at DESC, created_at DESC, id DESC").
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FileManagerFileRepository) ListEditedTemplatesByTakeoverID(ctx context.Context, takeoverID []byte) ([]filemanager.File, error) {
+	if len(takeoverID) != 16 {
+		return nil, nil
+	}
+	rows := make([]filemanager.File, 0)
+	err := r.db.WithContext(ctx).
+		Where("takeover_id = ? AND template_uuid IS NOT NULL AND deleted_at IS NULL AND lifecycle_deleted_at IS NULL AND status != ?", takeoverID, filemanager.FileStatusTrashed).
+		Order("created_at ASC, id ASC").
+		Find(&rows).Error
+	return rows, err
+}
+
+func (r *FileManagerFileRepository) ListByFolder(ctx context.Context, folderID []byte, sort string, limit, offset int) ([]filemanager.File, int64, error) {
+	var rows []filemanager.File
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&filemanager.File{}).
+		Where("folder_id = ? AND deleted_at IS NULL AND name_slot = 'live'", folderID)
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func (r *FileManagerFileRepository) SearchByName(ctx context.Context, name string, sort string, limit, offset int) ([]filemanager.File, int64, error) {
+	var rows []filemanager.File
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&filemanager.File{}).
+		Where("deleted_at IS NULL AND name_slot = 'live' AND name LIKE ?", "%"+name+"%")
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func (r *FileManagerFileRepository) ListTrashByFolder(ctx context.Context, folderID []byte, sort string, limit, offset int) ([]filemanager.File, int64, error) {
+	var rows []filemanager.File
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&filemanager.File{}).
+		Where("deleted_at IS NOT NULL")
+	if len(folderID) != 0 {
+		base = base.Where("folder_id = ?", folderID)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func (r *FileManagerFileRepository) UpdateLifecycle(ctx context.Context, params filemanager.FileLifecycleTransitionParams) error {
+	status := filemanager.NormalizeFileLifecycleStatus(params.Status)
+	if !filemanager.IsKnownFileLifecycleStatus(status) {
+		return fmt.Errorf("invalid file lifecycle status: %s", params.Status)
+	}
+	updates := map[string]any{
+		"lifecycle_status": status,
+		"updated_by":       params.UpdatedBy,
+	}
+	if params.AttachedAt != nil {
+		updates["attached_at"] = params.AttachedAt.UTC()
+	}
+	if params.OrphanedAt != nil {
+		updates["orphaned_at"] = params.OrphanedAt.UTC()
+	}
+	if params.ClearOrphanedAt {
+		updates["orphaned_at"] = nil
+	}
+	if params.LifecycleDelete != nil {
+		updates["lifecycle_deleted_at"] = params.LifecycleDelete.UTC()
+	}
+	res := r.db.WithContext(ctx).
+		Model(&filemanager.File{}).
+		Where("id = ?", params.ID).
+		Updates(updates)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *FileManagerFileRepository) ListFilesByLifecycle(ctx context.Context, filter filemanager.FileLifecycleListFilter) ([]filemanager.File, error) {
+	status := filemanager.NormalizeFileLifecycleStatus(filter.Status)
+	if !filemanager.IsKnownFileLifecycleStatus(status) {
+		return []filemanager.File{}, nil
+	}
+	query := r.db.WithContext(ctx).
+		Model(&filemanager.File{}).
+		Where("lifecycle_status = ?", status)
+	if filter.OrphanedBeforeEq != nil {
+		query = query.Where("orphaned_at IS NOT NULL AND orphaned_at <= ?", filter.OrphanedBeforeEq.UTC())
+	}
+	if filter.CreatedBeforeEq != nil {
+		query = query.Where("created_at <= ?", filter.CreatedBeforeEq.UTC())
+	}
+	if filter.ExcludeInTrash {
+		query = query.Where("deleted_at IS NULL")
+	}
+	if filter.ExcludeLifecycleDeleted {
+		query = query.Where("lifecycle_deleted_at IS NULL")
+	}
+	if filter.Limit > 0 {
+		query = query.Limit(filter.Limit)
+	}
+	rows := make([]filemanager.File, 0)
+	if err := query.Order("orphaned_at ASC, id ASC").Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *FileManagerFileRepository) IsFileReferenced(ctx context.Context, fileID []byte) (bool, error) {
+	if len(fileID) != 16 {
+		return false, nil
+	}
+	var total int64
+	queries := []struct {
+		sql  string
+		args []any
+	}{
+		{sql: "SELECT COUNT(1) FROM attachments WHERE file_id = ?", args: []any{fileID}},
+		{sql: "SELECT COUNT(1) FROM users u JOIN attachments a ON a.id = u.image_attachment_id WHERE a.file_id = ?", args: []any{fileID}},
+		{sql: "SELECT COUNT(1) FROM bases b JOIN attachments a ON a.id = b.foto_attachment_id WHERE a.file_id = ? AND b.deleted_at IS NULL", args: []any{fileID}},
+		{sql: "SELECT COUNT(1) FROM helicopters h JOIN attachments a ON a.id = h.foto_attachment_id WHERE a.file_id = ?", args: []any{fileID}},
+		{sql: "SELECT COUNT(1) FROM helicopter_files hf JOIN attachments a ON a.id = hf.file_attachment_id WHERE a.file_id = ?", args: []any{fileID}},
+		{sql: "SELECT COUNT(1) FROM hems_operational_files hof JOIN attachments a ON a.id = hof.file_attachment_id JOIN hems_operational_data hod ON hod.id = hof.operational_data_id WHERE a.file_id = ? AND hod.deleted_at IS NULL", args: []any{fileID}},
+		{sql: "SELECT COUNT(1) FROM master_settings ms JOIN file_files f ON f.id = ms.logo_file_id WHERE f.id = ? AND ms.deleted_at IS NULL", args: []any{fileID}},
+		{sql: "SELECT COUNT(1) FROM master_settings ms JOIN file_files f ON f.id = ms.cover_file_id WHERE f.id = ? AND ms.deleted_at IS NULL", args: []any{fileID}},
+	}
+	for i := range queries {
+		total = 0
+		if err := r.db.WithContext(ctx).Raw(queries[i].sql, queries[i].args...).Scan(&total).Error; err != nil {
+			return false, err
+		}
+		if total > 0 {
+			return true, nil
+		}
+	}
+
+	fileUUID, err := uuidv7.BytesToString(fileID)
+	if err == nil && strings.TrimSpace(fileUUID) != "" {
+		legacyQueries := []string{
+			"SELECT COUNT(1) FROM pilot_profiles WHERE TRIM(photo_file_id) = ?",
+			"SELECT COUNT(1) FROM doctor_profiles WHERE TRIM(photo_file_id) = ?",
+			"SELECT COUNT(1) FROM air_rescuer_profiles WHERE TRIM(photo_file_id) = ?",
+			"SELECT COUNT(1) FROM technician_profiles WHERE TRIM(photo_file_id) = ?",
+			"SELECT COUNT(1) FROM flight_assistant_profiles WHERE TRIM(photo_file_id) = ?",
+			"SELECT COUNT(1) FROM staff_profiles WHERE TRIM(photo_file_id) = ?",
+		}
+		for i := range legacyQueries {
+			total = 0
+			if err := r.db.WithContext(ctx).Raw(legacyQueries[i], fileUUID).Scan(&total).Error; err != nil {
+				return false, err
+			}
+			if total > 0 {
+				return true, nil
+			}
+		}
+	}
+	return false, nil
+}
diff --git a/internal/repository/mysql/file_manager_file_repo_test.go b/internal/repository/mysql/file_manager_file_repo_test.go
new file mode 100644
index 0000000..49bae6d
--- /dev/null
+++ b/internal/repository/mysql/file_manager_file_repo_test.go
@@ -0,0 +1,982 @@
+package mysql
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/queue"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openFileManagerFileRepoTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:file_manager_file_repo_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(
+		&filemanager.Folder{},
+		&filemanager.File{},
+		&filemanager.FileUploadIntent{},
+		&filemanager.FileProcessingOutboxMessage{},
+		&filemanager.FileStatusRealtimeEvent{},
+	); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func newFileProcessingOutboxRecordForRepoTest(t *testing.T, fileID []byte, bucket, objectKey string, sizeBytes int64) *filemanager.FileProcessingOutboxMessage {
+	t.Helper()
+	fileUUID, err := uuidv7.BytesToString(fileID)
+	if err != nil {
+		t.Fatalf("file uuid: %v", err)
+	}
+	serializer := queue.NewFileProcessingJSONSerializer("v1", queue.QueueTypeStandard, "")
+	message, err := serializer.Serialize(context.Background(), queue.FileProcessingJob{
+		FileUUID:  fileUUID,
+		Bucket:    bucket,
+		ObjectKey: objectKey,
+		SizeBytes: sizeBytes,
+	})
+	if err != nil {
+		t.Fatalf("serialize outbox message: %v", err)
+	}
+	record, err := filemanager.NewFileProcessingOutboxMessage(time.Now().UTC(), &filemanager.FileProcessingOutboundMessage{
+		ID:              message.ID,
+		Body:            append([]byte(nil), message.Body...),
+		Attributes:      message.Attributes,
+		MessageGroupID:  message.MessageGroupID,
+		DeduplicationID: message.DeduplicationID,
+	})
+	if err == nil {
+		return record
+	}
+	t.Fatalf("new outbox message: %v", err)
+	return nil
+}
+
+func seedFolderForFileRepo(t *testing.T, db *gorm.DB, name string) *filemanager.Folder {
+	t.Helper()
+	row := &filemanager.Folder{Name: name, NameNormalized: name, NameSlot: "live"}
+	if err := db.WithContext(context.Background()).Create(row).Error; err != nil {
+		t.Fatalf("seed folder: %v", err)
+	}
+	return row
+}
+
+func TestNewFileManagerFileRepository(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestFileManagerFileRepositoryCreateFileStatusRealtimeEvent(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+
+	fileID := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+	occurredAt := time.Now().UTC()
+	err := repo.CreateFileStatusRealtimeEvent(context.Background(), filemanager.FileStatusRealtimeEventInput{
+		FileID:     fileID,
+		UserID:     userID,
+		Status:     filemanager.FileStatusUploaded,
+		Name:       "report.pdf",
+		OccurredAt: occurredAt,
+	})
+	if err != nil {
+		t.Fatalf("create realtime event: %v", err)
+	}
+
+	var rows []filemanager.FileStatusRealtimeEvent
+	if err := db.WithContext(context.Background()).
+		Where("file_id = ? AND user_id = ? AND status = ?", fileID, userID, filemanager.FileStatusUploaded).
+		Find(&rows).Error; err != nil {
+		t.Fatalf("query realtime events: %v", err)
+	}
+	if len(rows) != 1 {
+		t.Fatalf("expected one realtime event row, got %d", len(rows))
+	}
+	if rows[0].DeliveredAt != nil {
+		t.Fatalf("expected new realtime event as undelivered")
+	}
+}
+
+func TestFileManagerFileRepositoryUploadIntentLifecycle(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+
+	intent := &filemanager.FileUploadIntent{
+		ID:             uuidv7.MustBytes(),
+		Name:           "report.pdf",
+		NameNormalized: "report.pdf",
+		Extension:      "pdf",
+		SizeBytes:      1024,
+		MimeType:       "application/pdf",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		Status:         filemanager.FileUploadIntentStatusPending,
+		ExpiresAt:      time.Now().UTC().Add(10 * time.Minute),
+		CreatedBy:      uuidv7.MustBytes(),
+		UpdatedBy:      uuidv7.MustBytes(),
+	}
+	if err := repo.CreateUploadIntent(context.Background(), intent); err != nil {
+		t.Fatalf("create upload intent: %v", err)
+	}
+
+	found, err := repo.GetUploadIntentByID(context.Background(), intent.ID)
+	if err != nil {
+		t.Fatalf("get upload intent: %v", err)
+	}
+	if found == nil {
+		t.Fatalf("expected upload intent")
+	}
+	if found.ObjectKey != intent.ObjectKey {
+		t.Fatalf("unexpected object key, got %q want %q", found.ObjectKey, intent.ObjectKey)
+	}
+
+	locked, err := repo.GetUploadIntentByIDForUpdate(context.Background(), intent.ID)
+	if err != nil {
+		t.Fatalf("get upload intent for update: %v", err)
+	}
+	if locked == nil {
+		t.Fatalf("expected locked upload intent")
+	}
+
+	completedAt := time.Now().UTC()
+	if err := repo.MarkUploadIntentCompleted(context.Background(), filemanager.FileUploadIntentCompleteParams{
+		ID:          intent.ID,
+		UpdatedBy:   intent.UpdatedBy,
+		CompletedAt: completedAt,
+	}); err != nil {
+		t.Fatalf("mark upload intent completed: %v", err)
+	}
+
+	done, err := repo.GetUploadIntentByID(context.Background(), intent.ID)
+	if err != nil {
+		t.Fatalf("get completed upload intent: %v", err)
+	}
+	if done == nil {
+		t.Fatalf("expected completed upload intent")
+	}
+	if filemanager.NormalizeFileUploadIntentStatus(done.Status) != filemanager.FileUploadIntentStatusCompleted {
+		t.Fatalf("expected completed status, got %q", done.Status)
+	}
+	if done.CompletedAt == nil {
+		t.Fatalf("expected completed_at set")
+	}
+}
+
+func TestFileManagerFileRepositoryMarkUploadIntentExpired(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+
+	intent := &filemanager.FileUploadIntent{
+		ID:             uuidv7.MustBytes(),
+		Name:           "expired.pdf",
+		NameNormalized: "expired.pdf",
+		Extension:      "pdf",
+		SizeBytes:      12,
+		MimeType:       "application/pdf",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		Status:         filemanager.FileUploadIntentStatusPending,
+		ExpiresAt:      time.Now().UTC().Add(-time.Minute),
+	}
+	if err := repo.CreateUploadIntent(context.Background(), intent); err != nil {
+		t.Fatalf("create upload intent: %v", err)
+	}
+
+	if err := repo.MarkUploadIntentExpired(context.Background(), filemanager.FileUploadIntentExpireParams{
+		ID:        intent.ID,
+		UpdatedBy: uuidv7.MustBytes(),
+		ExpiredAt: time.Now().UTC(),
+	}); err != nil {
+		t.Fatalf("mark upload intent expired: %v", err)
+	}
+
+	expired, err := repo.GetUploadIntentByID(context.Background(), intent.ID)
+	if err != nil {
+		t.Fatalf("get expired upload intent: %v", err)
+	}
+	if expired == nil {
+		t.Fatalf("expected expired upload intent")
+	}
+	if filemanager.NormalizeFileUploadIntentStatus(expired.Status) != filemanager.FileUploadIntentStatusExpired {
+		t.Fatalf("expected expired status, got %q", expired.Status)
+	}
+}
+
+func TestFileManagerFileRepositoryUpdateUploadIntentSize(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+
+	intent := &filemanager.FileUploadIntent{
+		ID:             uuidv7.MustBytes(),
+		Name:           "draft.xlsx",
+		NameNormalized: "draft.xlsx",
+		Extension:      "xlsx",
+		SizeBytes:      100,
+		MimeType:       "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		Status:         filemanager.FileUploadIntentStatusPending,
+		ExpiresAt:      time.Now().UTC().Add(10 * time.Minute),
+	}
+	if err := repo.CreateUploadIntent(context.Background(), intent); err != nil {
+		t.Fatalf("create upload intent: %v", err)
+	}
+
+	if err := repo.UpdateUploadIntentSize(context.Background(), filemanager.FileUploadIntentSizeUpdateParams{
+		ID:        intent.ID,
+		SizeBytes: 64,
+		UpdatedBy: uuidv7.MustBytes(),
+	}); err != nil {
+		t.Fatalf("update upload intent size: %v", err)
+	}
+
+	updated, err := repo.GetUploadIntentByID(context.Background(), intent.ID)
+	if err != nil {
+		t.Fatalf("get updated upload intent: %v", err)
+	}
+	if updated == nil {
+		t.Fatalf("expected upload intent")
+	}
+	if updated.SizeBytes != 64 {
+		t.Fatalf("expected size_bytes 64, got %d", updated.SizeBytes)
+	}
+}
+
+func TestFileManagerFileRepositoryWithTransaction_PersistFileAndOutbox(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "docs")
+
+	row := &filemanager.File{
+		ID:             uuidv7.MustBytes(),
+		FolderID:       folder.ID,
+		Name:           "upload.pdf",
+		NameNormalized: "upload.pdf",
+		Extension:      "pdf",
+		SizeBytes:      1024,
+		MimeType:       "application/pdf",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		NameSlot:       "tmp-slot",
+		Status:         filemanager.FileStatusUploaded,
+	}
+	outbox := newFileProcessingOutboxRecordForRepoTest(t, row.ID, row.Bucket, row.ObjectKey, row.SizeBytes)
+
+	err := repo.WithTransaction(context.Background(), func(fileRepo filemanager.FileRepository, outboxWriter filemanager.FileProcessingOutboxWriter) error {
+		if err := fileRepo.Create(context.Background(), row); err != nil {
+			return err
+		}
+		return outboxWriter.CreateFileProcessingOutboxMessage(context.Background(), outbox)
+	})
+	if err != nil {
+		t.Fatalf("with transaction: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id: %v", err)
+	}
+	if got == nil {
+		t.Fatalf("expected uploaded file persisted")
+	}
+
+	var total int64
+	if err := db.Model(&filemanager.FileProcessingOutboxMessage{}).Where("message_id = ?", outbox.MessageID).Count(&total).Error; err != nil {
+		t.Fatalf("count outbox: %v", err)
+	}
+	if total != 1 {
+		t.Fatalf("expected one outbox row, got %d", total)
+	}
+}
+
+func TestFileManagerFileRepositoryWithTransaction_Rollback(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "docs")
+
+	row := &filemanager.File{
+		ID:             uuidv7.MustBytes(),
+		FolderID:       folder.ID,
+		Name:           "upload.pdf",
+		NameNormalized: "upload.pdf",
+		Extension:      "pdf",
+		SizeBytes:      1024,
+		MimeType:       "application/pdf",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		NameSlot:       "tmp-slot",
+		Status:         filemanager.FileStatusUploaded,
+	}
+	outbox := newFileProcessingOutboxRecordForRepoTest(t, row.ID, row.Bucket, row.ObjectKey, row.SizeBytes)
+	rollbackErr := errors.New("force rollback")
+
+	err := repo.WithTransaction(context.Background(), func(fileRepo filemanager.FileRepository, outboxWriter filemanager.FileProcessingOutboxWriter) error {
+		if err := fileRepo.Create(context.Background(), row); err != nil {
+			return err
+		}
+		if err := outboxWriter.CreateFileProcessingOutboxMessage(context.Background(), outbox); err != nil {
+			return err
+		}
+		return rollbackErr
+	})
+	if !errors.Is(err, rollbackErr) {
+		t.Fatalf("expected rollback error, got %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected file insert rolled back")
+	}
+
+	var total int64
+	if err := db.Model(&filemanager.FileProcessingOutboxMessage{}).Where("message_id = ?", outbox.MessageID).Count(&total).Error; err != nil {
+		t.Fatalf("count outbox: %v", err)
+	}
+	if total != 0 {
+		t.Fatalf("expected outbox insert rolled back, got %d", total)
+	}
+}
+
+func TestFileManagerFileRepositoryCreate_AllowsMultipleNullThumbnailObjectKeys(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "images")
+
+	first := &filemanager.File{
+		ID:             uuidv7.MustBytes(),
+		FolderID:       folder.ID,
+		Name:           "one.jpg",
+		NameNormalized: "one.jpg",
+		Extension:      "jpg",
+		SizeBytes:      10,
+		MimeType:       "image/jpeg",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d-one", time.Now().UnixNano()),
+		NameSlot:       "tmp-one",
+		Status:         filemanager.FileStatusUploaded,
+	}
+	second := &filemanager.File{
+		ID:             uuidv7.MustBytes(),
+		FolderID:       folder.ID,
+		Name:           "two.jpg",
+		NameNormalized: "two.jpg",
+		Extension:      "jpg",
+		SizeBytes:      20,
+		MimeType:       "image/jpeg",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d-two", time.Now().UnixNano()),
+		NameSlot:       "tmp-two",
+		Status:         filemanager.FileStatusUploaded,
+	}
+
+	if err := repo.Create(context.Background(), first); err != nil {
+		t.Fatalf("create first file: %v", err)
+	}
+	if err := repo.Create(context.Background(), second); err != nil {
+		t.Fatalf("create second file with nil thumbnail object key: %v", err)
+	}
+}
+
+func TestFileManagerFileRepositoryCreateAndGetters(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "docs")
+	templateUUID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+
+	objectKey := fmt.Sprintf("fm/objects/%d", time.Now().UnixNano())
+	row := &filemanager.File{
+		FolderID:       folder.ID,
+		Name:           "Policy.pdf",
+		NameNormalized: "policy.pdf",
+		Extension:      "pdf",
+		SizeBytes:      1024,
+		MimeType:       "application/pdf",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      objectKey,
+		NameSlot:       "live",
+		Status:         filemanager.FileStatusReady,
+		TemplateUUID:   templateUUID,
+		TakeoverID:     takeoverID,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("create file: %v", err)
+	}
+	if len(row.ID) != 16 {
+		t.Fatalf("expected generated id")
+	}
+
+	byID, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id: %v", err)
+	}
+	if byID == nil || byID.Name != "Policy.pdf" {
+		t.Fatalf("expected by id result")
+	}
+
+	byKey, err := repo.GetByObjectKey(context.Background(), objectKey)
+	if err != nil {
+		t.Fatalf("get by object key: %v", err)
+	}
+	if byKey == nil || !bytes.Equal(byKey.ID, row.ID) {
+		t.Fatalf("expected by object key result")
+	}
+
+	byName, err := repo.GetByFolderAndName(context.Background(), folder.ID, "policy.pdf")
+	if err != nil {
+		t.Fatalf("get by folder/name: %v", err)
+	}
+	if byName == nil || !bytes.Equal(byName.ID, row.ID) {
+		t.Fatalf("expected by folder/name result")
+	}
+
+	byTemplateTakeover, err := repo.GetByTemplateAndTakeover(context.Background(), templateUUID, takeoverID)
+	if err != nil {
+		t.Fatalf("get by template/takeover: %v", err)
+	}
+	if byTemplateTakeover == nil || !bytes.Equal(byTemplateTakeover.ID, row.ID) {
+		t.Fatalf("expected by template/takeover result")
+	}
+
+	blankKey, err := repo.GetByObjectKey(context.Background(), "   ")
+	if err != nil {
+		t.Fatalf("get blank object key: %v", err)
+	}
+	if blankKey != nil {
+		t.Fatalf("expected nil for blank object key")
+	}
+}
+
+func TestFileManagerFileRepositoryGetByTemplateAndTakeoverReturnsDraftRows(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "docs")
+	templateUUID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+
+	row := &filemanager.File{
+		FolderID:       folder.ID,
+		Name:           "Draft.docx",
+		NameNormalized: "draft.docx",
+		Extension:      "docx",
+		SizeBytes:      2048,
+		MimeType:       "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d-draft", time.Now().UnixNano()),
+		NameSlot:       "draft",
+		Status:         filemanager.FileStatusReady,
+		TemplateUUID:   templateUUID,
+		TakeoverID:     takeoverID,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("create draft file: %v", err)
+	}
+
+	got, err := repo.GetByTemplateAndTakeover(context.Background(), templateUUID, takeoverID)
+	if err != nil {
+		t.Fatalf("get by template/takeover: %v", err)
+	}
+	if got == nil || !bytes.Equal(got.ID, row.ID) {
+		t.Fatalf("expected draft row to be returned, got %#v", got)
+	}
+}
+
+func TestFileManagerFileRepositoryUpdate(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "docs")
+
+	row := &filemanager.File{
+		FolderID:       folder.ID,
+		Name:           "Old.txt",
+		NameNormalized: "old.txt",
+		MimeType:       "text/plain",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		NameSlot:       "live",
+		Status:         filemanager.FileStatusReady,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Name = "New.txt"
+	row.NameNormalized = "new.txt"
+	row.SizeBytes = 88
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("update file: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get after update: %v", err)
+	}
+	if got == nil || got.Name != "New.txt" || got.SizeBytes != 88 {
+		t.Fatalf("unexpected updated row: %+v", got)
+	}
+}
+
+func TestFileManagerFileRepositoryTransitionStatus(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "docs")
+
+	row := &filemanager.File{
+		FolderID:       folder.ID,
+		Name:           "upload.pdf",
+		NameNormalized: "upload.pdf",
+		MimeType:       "application/pdf",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		NameSlot:       "tmp-slot",
+		Status:         filemanager.FileStatusUploaded,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	startedAt := time.Now().UTC().Truncate(time.Second)
+	if err := repo.TransitionStatus(context.Background(), filemanager.FileStatusTransitionParams{
+		ID:                  row.ID,
+		ExpectedFrom:        filemanager.FileStatusUploaded,
+		To:                  filemanager.FileStatusProcessing,
+		ProcessingStartedAt: &startedAt,
+	}); err != nil {
+		t.Fatalf("to processing: %v", err)
+	}
+
+	mid, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get after processing: %v", err)
+	}
+	if mid == nil || mid.Status != filemanager.FileStatusProcessing {
+		t.Fatalf("expected processing status")
+	}
+	if mid.ProcessingStartedAt == nil || !mid.ProcessingStartedAt.Equal(startedAt) {
+		t.Fatalf("expected processing_started_at set")
+	}
+
+	processedAt := time.Now().UTC().Truncate(time.Second)
+	validatedAt := processedAt.Add(2 * time.Second)
+	if err := repo.TransitionStatus(context.Background(), filemanager.FileStatusTransitionParams{
+		ID:           row.ID,
+		ExpectedFrom: filemanager.FileStatusProcessing,
+		To:           filemanager.FileStatusValidated,
+		ProcessedAt:  &processedAt,
+		ValidatedAt:  &validatedAt,
+	}); err != nil {
+		t.Fatalf("to validated: %v", err)
+	}
+
+	if err := repo.TransitionStatus(context.Background(), filemanager.FileStatusTransitionParams{
+		ID:           row.ID,
+		ExpectedFrom: filemanager.FileStatusUploaded,
+		To:           filemanager.FileStatusReady,
+	}); !errors.Is(err, filemanager.ErrInvalidFileStatusTransition) {
+		t.Fatalf("expected invalid transition for uploaded->ready via transition api, got %v", err)
+	}
+}
+
+func TestFileManagerFileRepositoryTransitionStatus_FailedAndMismatch(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "docs")
+
+	row := &filemanager.File{
+		FolderID:       folder.ID,
+		Name:           "processing.pdf",
+		NameNormalized: "processing.pdf",
+		MimeType:       "application/pdf",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		NameSlot:       "tmp-slot",
+		Status:         filemanager.FileStatusProcessing,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	reason := "invalid payload"
+	if err := repo.TransitionStatus(context.Background(), filemanager.FileStatusTransitionParams{
+		ID:            row.ID,
+		ExpectedFrom:  filemanager.FileStatusProcessing,
+		To:            filemanager.FileStatusFailed,
+		FailureReason: &reason,
+	}); err != nil {
+		t.Fatalf("to failed: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get after failed: %v", err)
+	}
+	if got == nil || got.Status != filemanager.FileStatusFailed {
+		t.Fatalf("expected failed status")
+	}
+	if got.FailedAt == nil {
+		t.Fatalf("expected failed_at set")
+	}
+	if got.FailureReason != reason {
+		t.Fatalf("expected failure reason %q, got %q", reason, got.FailureReason)
+	}
+
+	err = repo.TransitionStatus(context.Background(), filemanager.FileStatusTransitionParams{
+		ID:           row.ID,
+		ExpectedFrom: filemanager.FileStatusProcessing,
+		To:           filemanager.FileStatusValidated,
+	})
+	if !errors.Is(err, gorm.ErrRecordNotFound) {
+		t.Fatalf("expected gorm.ErrRecordNotFound for status mismatch, got %v", err)
+	}
+}
+
+func TestFileManagerFileRepositoryFinalize(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	rootFolder := seedFolderForFileRepo(t, db, "root")
+	targetFolder := seedFolderForFileRepo(t, db, "target")
+
+	row := &filemanager.File{
+		FolderID:       rootFolder.ID,
+		Name:           "upload.tmp",
+		NameNormalized: "upload.tmp",
+		Extension:      "tmp",
+		MimeType:       "application/octet-stream",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		NameSlot:       "tmp-slot",
+		Status:         filemanager.FileStatusValidated,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	if err := repo.Finalize(context.Background(), filemanager.FileFinalizeParams{
+		ID:             row.ID,
+		ExpectedFrom:   filemanager.FileStatusValidated,
+		FolderID:       targetFolder.ID,
+		Name:           "Final.pdf",
+		NameNormalized: "final.pdf",
+		Extension:      "pdf",
+		UpdatedBy:      uuidv7.MustBytes(),
+	}); err != nil {
+		t.Fatalf("finalize file: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get after finalize: %v", err)
+	}
+	if got == nil {
+		t.Fatalf("expected finalized row")
+	}
+	if got.Status != filemanager.FileStatusReady {
+		t.Fatalf("expected status ready, got %s", got.Status)
+	}
+	if got.NameSlot != "live" {
+		t.Fatalf("expected name slot live, got %s", got.NameSlot)
+	}
+	if !bytes.Equal(got.FolderID, targetFolder.ID) {
+		t.Fatalf("expected folder updated")
+	}
+	if got.Name != "Final.pdf" || got.NameNormalized != "final.pdf" || got.Extension != "pdf" {
+		t.Fatalf("expected naming fields updated")
+	}
+}
+
+func TestFileManagerFileRepositoryFinalize_StatusMismatch(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "docs")
+
+	row := &filemanager.File{
+		FolderID:       folder.ID,
+		Name:           "ready.txt",
+		NameNormalized: "ready.txt",
+		MimeType:       "text/plain",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		NameSlot:       "live",
+		Status:         filemanager.FileStatusReady,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	err := repo.Finalize(context.Background(), filemanager.FileFinalizeParams{
+		ID:             row.ID,
+		ExpectedFrom:   filemanager.FileStatusValidated,
+		FolderID:       folder.ID,
+		Name:           "ready.txt",
+		NameNormalized: "ready.txt",
+		Extension:      "txt",
+		UpdatedBy:      uuidv7.MustBytes(),
+	})
+	if !errors.Is(err, gorm.ErrRecordNotFound) {
+		t.Fatalf("expected gorm.ErrRecordNotFound for status mismatch, got %v", err)
+	}
+}
+
+func TestFileManagerFileRepositoryDelete(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "docs")
+
+	row := &filemanager.File{
+		FolderID:       folder.ID,
+		Name:           "Delete.bin",
+		NameNormalized: "delete.bin",
+		MimeType:       "application/octet-stream",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		NameSlot:       "live",
+		Status:         filemanager.FileStatusReady,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	deletedBy := uuidv7.MustBytes()
+	purgeAt := time.Now().UTC().Add(72 * time.Hour).Truncate(time.Second)
+	if err := repo.Delete(context.Background(), row.ID, deletedBy, &purgeAt); err != nil {
+		t.Fatalf("delete file: %v", err)
+	}
+
+	active, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get after delete: %v", err)
+	}
+	if active != nil {
+		t.Fatalf("expected deleted row hidden from GetByID")
+	}
+
+	var stored filemanager.File
+	if err := db.WithContext(context.Background()).Unscoped().Where("id = ?", row.ID).First(&stored).Error; err != nil {
+		t.Fatalf("unscoped find: %v", err)
+	}
+	if stored.DeletedAt == nil || stored.TrashedAt == nil {
+		t.Fatalf("expected deleted_at and trashed_at populated")
+	}
+	if stored.Status != filemanager.FileStatusTrashed {
+		t.Fatalf("expected status trashed, got %s", stored.Status)
+	}
+	if stored.PurgeAt == nil || !stored.PurgeAt.Equal(purgeAt) {
+		t.Fatalf("expected purge_at set")
+	}
+	if !bytes.Equal(stored.DeletedBy, deletedBy) {
+		t.Fatalf("expected deleted_by set")
+	}
+	if stored.NameSlot == "live" {
+		t.Fatalf("expected name_slot switched from live on delete")
+	}
+}
+
+func TestFileManagerFileRepositoryDelete_OnlyReadyAllowed(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "docs")
+
+	row := &filemanager.File{
+		FolderID:       folder.ID,
+		Name:           "NotReady.bin",
+		NameNormalized: "notready.bin",
+		MimeType:       "application/octet-stream",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		NameSlot:       "tmp-slot",
+		Status:         filemanager.FileStatusValidated,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	err := repo.Delete(context.Background(), row.ID, uuidv7.MustBytes(), nil)
+	if !errors.Is(err, gorm.ErrRecordNotFound) {
+		t.Fatalf("expected gorm.ErrRecordNotFound for non-ready delete, got %v", err)
+	}
+}
+
+func TestFileManagerFileRepositoryRestorePurgeAndTrashQueries(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "archive")
+
+	row := &filemanager.File{
+		FolderID:       folder.ID,
+		Name:           "Archive.txt",
+		NameNormalized: "archive.txt",
+		MimeType:       "text/plain",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		NameSlot:       "live",
+		Status:         filemanager.FileStatusReady,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("create file: %v", err)
+	}
+	deletedBy := uuidv7.MustBytes()
+	if err := repo.Delete(context.Background(), row.ID, deletedBy, nil); err != nil {
+		t.Fatalf("delete file: %v", err)
+	}
+
+	anyRow, err := repo.GetByIDAny(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id any: %v", err)
+	}
+	if anyRow == nil || anyRow.DeletedAt == nil {
+		t.Fatalf("expected deleted row from GetByIDAny")
+	}
+
+	trashRows, trashTotal, err := repo.ListTrashByFolder(context.Background(), folder.ID, "", 10, 0)
+	if err != nil {
+		t.Fatalf("list trash by folder: %v", err)
+	}
+	if trashTotal != 1 || len(trashRows) != 1 {
+		t.Fatalf("expected one trashed file")
+	}
+
+	restoreBy := uuidv7.MustBytes()
+	if err := repo.Restore(context.Background(), row.ID, restoreBy); err != nil {
+		t.Fatalf("restore file: %v", err)
+	}
+	restored, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get restored file: %v", err)
+	}
+	if restored == nil || restored.DeletedAt != nil || restored.NameSlot != "live" {
+		t.Fatalf("expected restored live file")
+	}
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy, nil); err != nil {
+		t.Fatalf("delete file 2: %v", err)
+	}
+	if err := repo.Purge(context.Background(), row.ID); err != nil {
+		t.Fatalf("purge file: %v", err)
+	}
+	if got, err := repo.GetByIDAny(context.Background(), row.ID); err != nil || got != nil {
+		t.Fatalf("expected purged file gone, got=%v err=%v", got, err)
+	}
+	if err := repo.Purge(context.Background(), row.ID); err == nil {
+		t.Fatalf("expected purge not found on second call")
+	}
+}
+
+func TestFileManagerFileRepositoryPurge_DeletesActiveFileRow(t *testing.T) {
+	db := openFileManagerFileRepoTestDB(t)
+	repo := NewFileManagerFileRepository(db)
+	folder := seedFolderForFileRepo(t, db, "active")
+
+	row := &filemanager.File{
+		FolderID:       folder.ID,
+		Name:           "InProgress.txt",
+		NameNormalized: "inprogress.txt",
+		MimeType:       "text/plain",
+		Bucket:         "wucher-file-dev",
+		ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+		NameSlot:       "live",
+		Status:         filemanager.FileStatusValidated,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("create file: %v", err)
+	}
+
+	if err := repo.Purge(context.Background(), row.ID); err != nil {
+		t.Fatalf("purge active file: %v", err)
+	}
+	if got, err := repo.GetByIDAny(context.Background(), row.ID); err != nil || got != nil {
+		t.Fatalf("expected purged active file gone, got=%v err=%v", got, err)
+	}
+}
+
+func TestFileManagerFileRepositoryListByFolder(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		db := openFileManagerFileRepoTestDB(t)
+		repo := NewFileManagerFileRepository(db)
+		folder := seedFolderForFileRepo(t, db, "docs")
+
+		_ = repo.Create(context.Background(), &filemanager.File{
+			FolderID:       folder.ID,
+			Name:           "B.txt",
+			NameNormalized: "b.txt",
+			MimeType:       "text/plain",
+			Bucket:         "wucher-file-dev",
+			ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+			NameSlot:       "live",
+			Status:         filemanager.FileStatusReady,
+		})
+		_ = repo.Create(context.Background(), &filemanager.File{
+			FolderID:       folder.ID,
+			Name:           "A.txt",
+			NameNormalized: "a.txt",
+			MimeType:       "text/plain",
+			Bucket:         "wucher-file-dev",
+			ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()+1),
+			NameSlot:       "live",
+			Status:         filemanager.FileStatusReady,
+		})
+
+		rows, total, err := repo.ListByFolder(context.Background(), folder.ID, "name ASC", 1, 0)
+		if err != nil {
+			t.Fatalf("list files: %v", err)
+		}
+		if total != 2 {
+			t.Fatalf("expected total 2, got %d", total)
+		}
+		if len(rows) != 1 || rows[0].Name != "A.txt" {
+			t.Fatalf("expected sorted+limited list")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openFileManagerFileRepoTestDB(t)
+		repo := NewFileManagerFileRepository(db)
+		folder := seedFolderForFileRepo(t, db, "docs")
+		if err := db.Migrator().DropTable(&filemanager.File{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+		if _, _, err := repo.ListByFolder(context.Background(), folder.ID, "", 10, 0); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openFileManagerFileRepoTestDB(t)
+		repo := NewFileManagerFileRepository(db)
+		folder := seedFolderForFileRepo(t, db, "docs")
+		_ = repo.Create(context.Background(), &filemanager.File{
+			FolderID:       folder.ID,
+			Name:           "X.txt",
+			NameNormalized: "x.txt",
+			MimeType:       "text/plain",
+			Bucket:         "wucher-file-dev",
+			ObjectKey:      fmt.Sprintf("fm/objects/%d", time.Now().UnixNano()),
+			NameSlot:       "live",
+			Status:         filemanager.FileStatusReady,
+		})
+		if _, _, err := repo.ListByFolder(context.Background(), folder.ID, "name ASC, )", 10, 0); err == nil {
+			t.Fatalf("expected find error")
+		}
+	})
+}
diff --git a/internal/repository/mysql/file_manager_folder_repo.go b/internal/repository/mysql/file_manager_folder_repo.go
new file mode 100644
index 0000000..71d35eb
--- /dev/null
+++ b/internal/repository/mysql/file_manager_folder_repo.go
@@ -0,0 +1,460 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type FileManagerFolderRepository struct {
+	db *gorm.DB
+}
+
+func NewFileManagerFolderRepository(db *gorm.DB) *FileManagerFolderRepository {
+	return &FileManagerFolderRepository{db: db}
+}
+
+func (r *FileManagerFolderRepository) Create(ctx context.Context, row *filemanager.Folder) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *FileManagerFolderRepository) Update(ctx context.Context, row *filemanager.Folder) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *FileManagerFolderRepository) MoveSubtree(ctx context.Context, id []byte, targetParentID []byte, targetName string, targetNameNormalized string, updatedBy []byte) (*filemanager.Folder, error) {
+	var moved filemanager.Folder
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var current filemanager.Folder
+		if err := tx.Model(&filemanager.Folder{}).
+			Where("id = ? AND deleted_at IS NULL", id).
+			First(&current).Error; err != nil {
+			return err
+		}
+
+		targetDepth := 0
+		targetParentPath := ""
+		if len(targetParentID) != 0 {
+			if folderRepoBytesEqual16(targetParentID, current.ID) {
+				return filemanager.ErrInvalidMove
+			}
+
+			var parent filemanager.Folder
+			if err := tx.Model(&filemanager.Folder{}).
+				Where("id = ? AND deleted_at IS NULL", targetParentID).
+				First(&parent).Error; err != nil {
+				return err
+			}
+
+			isDescendant, err := folderRepoIsDescendantFolder(tx, targetParentID, current.ID)
+			if err != nil {
+				return err
+			}
+			if isDescendant {
+				return filemanager.ErrInvalidMove
+			}
+
+			targetDepth = parent.Depth + 1
+			targetParentPath = parent.PathCache
+		}
+
+		var dupTotal int64
+		if err := folderParentScope(
+			tx.Model(&filemanager.Folder{}),
+			targetParentID,
+		).Where("name_normalized = ? AND name_slot = 'live' AND deleted_at IS NULL AND id <> ?", targetNameNormalized, id).Count(&dupTotal).Error; err != nil {
+			return err
+		}
+		if dupTotal > 0 {
+			return gorm.ErrDuplicatedKey
+		}
+
+		oldPath := current.PathCache
+		oldDepth := current.Depth
+		newPath := folderRepoBuildPathCache(targetParentPath, targetName)
+
+		res := tx.Model(&filemanager.Folder{}).
+			Where("id = ? AND deleted_at IS NULL", id).
+			Updates(map[string]any{
+				"parent_id":       targetParentID,
+				"name":            targetName,
+				"name_normalized": targetNameNormalized,
+				"depth":           targetDepth,
+				"path_cache":      newPath,
+				"updated_by":      updatedBy,
+				"updated_at":      time.Now().UTC(),
+			})
+		if res.Error != nil {
+			return res.Error
+		}
+		if res.RowsAffected == 0 {
+			return gorm.ErrRecordNotFound
+		}
+
+		depthDelta := targetDepth - oldDepth
+		if oldPath != newPath || depthDelta != 0 {
+			if err := folderRepoRewriteDescendantTree(tx, current.ID, oldPath, newPath, depthDelta, updatedBy); err != nil {
+				return err
+			}
+		}
+
+		current.ParentID = targetParentID
+		current.Name = targetName
+		current.NameNormalized = targetNameNormalized
+		current.Depth = targetDepth
+		current.PathCache = newPath
+		current.UpdatedBy = updatedBy
+		moved = current
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &moved, nil
+}
+
+func (r *FileManagerFolderRepository) Delete(ctx context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error {
+	now := time.Now().UTC()
+	nameSlot := deletedNameSlot(id)
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+		"name_slot":  nameSlot,
+	}
+	if purgeAt != nil {
+		v := purgeAt.UTC()
+		updates["purge_at"] = v
+	}
+
+	res := r.db.WithContext(ctx).
+		Model(&filemanager.Folder{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *FileManagerFolderRepository) Restore(ctx context.Context, id []byte, restoredBy []byte) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var row filemanager.Folder
+		if err := tx.Model(&filemanager.Folder{}).Where("id = ?", id).First(&row).Error; err != nil {
+			return err
+		}
+		if row.DeletedAt == nil {
+			return gorm.ErrRecordNotFound
+		}
+
+		var total int64
+		if err := folderParentScope(
+			tx.Model(&filemanager.Folder{}),
+			row.ParentID,
+		).Where("name_normalized = ? AND name_slot = 'live' AND deleted_at IS NULL", row.NameNormalized).Count(&total).Error; err != nil {
+			return err
+		}
+		if total > 0 {
+			return gorm.ErrDuplicatedKey
+		}
+
+		updates := map[string]any{
+			"deleted_at": nil,
+			"deleted_by": nil,
+			"purge_at":   nil,
+			"updated_by": restoredBy,
+			"name_slot":  "live",
+		}
+		res := tx.Model(&filemanager.Folder{}).
+			Where("id = ? AND deleted_at IS NOT NULL", id).
+			Updates(updates)
+		if res.Error != nil {
+			return res.Error
+		}
+		if res.RowsAffected == 0 {
+			return gorm.ErrRecordNotFound
+		}
+		return nil
+	})
+}
+
+func (r *FileManagerFolderRepository) Purge(ctx context.Context, id []byte) error {
+	res := r.db.WithContext(ctx).
+		Where("id = ? AND deleted_at IS NOT NULL", id).
+		Delete(&filemanager.Folder{})
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *FileManagerFolderRepository) GetByID(ctx context.Context, id []byte) (*filemanager.Folder, error) {
+	var row filemanager.Folder
+	err := r.db.WithContext(ctx).
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FileManagerFolderRepository) GetByIDAny(ctx context.Context, id []byte) (*filemanager.Folder, error) {
+	var row filemanager.Folder
+	err := r.db.WithContext(ctx).
+		Where("id = ?", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FileManagerFolderRepository) GetByParentAndName(ctx context.Context, parentID []byte, nameNormalized string) (*filemanager.Folder, error) {
+	var row filemanager.Folder
+	q := folderParentScope(r.db.WithContext(ctx).Model(&filemanager.Folder{}), parentID).
+		Where("name_normalized = ? AND name_slot = 'live' AND deleted_at IS NULL", nameNormalized)
+
+	err := q.First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FileManagerFolderRepository) ListByParent(ctx context.Context, parentID []byte, sort string, limit, offset int) ([]filemanager.Folder, int64, error) {
+	var rows []filemanager.Folder
+	var total int64
+
+	base := folderParentScope(
+		r.db.WithContext(ctx).
+			Model(&filemanager.Folder{}).
+			Where("deleted_at IS NULL AND name_slot = 'live'"),
+		parentID,
+	)
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func (r *FileManagerFolderRepository) SearchByName(ctx context.Context, name string, sort string, limit, offset int) ([]filemanager.Folder, int64, error) {
+	var rows []filemanager.Folder
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&filemanager.Folder{}).
+		Where("deleted_at IS NULL AND name_slot = 'live' AND name LIKE ?", "%"+name+"%")
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func (r *FileManagerFolderRepository) ListTrash(ctx context.Context, sort string, limit, offset int) ([]filemanager.Folder, int64, error) {
+	var rows []filemanager.Folder
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&filemanager.Folder{}).
+		Where("deleted_at IS NOT NULL")
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func (r *FileManagerFolderRepository) ListTrashByParent(ctx context.Context, parentID []byte, sort string, limit, offset int) ([]filemanager.Folder, int64, error) {
+	var rows []filemanager.Folder
+	var total int64
+
+	base := folderParentScope(
+		r.db.WithContext(ctx).
+			Model(&filemanager.Folder{}).
+			Where("deleted_at IS NOT NULL"),
+		parentID,
+	)
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func folderParentScope(tx *gorm.DB, parentID []byte) *gorm.DB {
+	if len(parentID) == 0 {
+		return tx.Where("parent_id IS NULL")
+	}
+	return tx.Where("parent_id = ?", parentID)
+}
+
+func deletedNameSlot(id []byte) string {
+	if len(id) == 16 {
+		if v, err := uuidv7.BytesToString(id); err == nil {
+			return v
+		}
+	}
+	if v, err := uuidv7.BytesToString(uuidv7.MustBytes()); err == nil {
+		return v
+	}
+	return "deleted"
+}
+
+func folderRepoIsDescendantFolder(tx *gorm.DB, candidateID []byte, ancestorID []byte) (bool, error) {
+	currentID := append([]byte(nil), candidateID...)
+	for len(currentID) != 0 {
+		if folderRepoBytesEqual16(currentID, ancestorID) {
+			return true, nil
+		}
+
+		var current filemanager.Folder
+		err := tx.Model(&filemanager.Folder{}).
+			Where("id = ? AND deleted_at IS NULL", currentID).
+			First(&current).Error
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return false, nil
+		}
+		if err != nil {
+			return false, err
+		}
+		if len(current.ParentID) == 0 {
+			return false, nil
+		}
+		currentID = append([]byte(nil), current.ParentID...)
+	}
+	return false, nil
+}
+
+func folderRepoRewriteDescendantTree(tx *gorm.DB, rootID []byte, oldPrefix string, newPrefix string, depthDelta int, updatedBy []byte) error {
+	queue := [][]byte{append([]byte(nil), rootID...)}
+	for len(queue) > 0 {
+		parentID := queue[0]
+		queue = queue[1:]
+
+		var children []filemanager.Folder
+		if err := tx.Model(&filemanager.Folder{}).
+			Where("parent_id = ?", parentID).
+			Find(&children).Error; err != nil {
+			return err
+		}
+
+		for i := range children {
+			child := children[i]
+			pathCache := child.PathCache
+			if pathCache != "" {
+				pathCache = folderRepoReplacePathPrefix(pathCache, oldPrefix, newPrefix)
+			}
+			depth := child.Depth + depthDelta
+			if depth < 0 {
+				depth = 0
+			}
+
+			if err := tx.Model(&filemanager.Folder{}).
+				Where("id = ?", child.ID).
+				Updates(map[string]any{
+					"path_cache": pathCache,
+					"depth":      depth,
+					"updated_by": updatedBy,
+					"updated_at": time.Now().UTC(),
+				}).Error; err != nil {
+				return err
+			}
+			queue = append(queue, append([]byte(nil), child.ID...))
+		}
+	}
+	return nil
+}
+
+func folderRepoReplacePathPrefix(pathCache string, oldPrefix string, newPrefix string) string {
+	if oldPrefix == "" {
+		return pathCache
+	}
+	if pathCache == oldPrefix {
+		return newPrefix
+	}
+	prefixWithSlash := oldPrefix + "/"
+	if strings.HasPrefix(pathCache, prefixWithSlash) {
+		return newPrefix + strings.TrimPrefix(pathCache, oldPrefix)
+	}
+	return pathCache
+}
+
+func folderRepoBuildPathCache(parentPath, name string) string {
+	parentPath = strings.TrimSpace(parentPath)
+	if parentPath == "" {
+		return "/" + name
+	}
+	parentPath = strings.TrimRight(parentPath, "/")
+	return parentPath + "/" + name
+}
+
+func folderRepoBytesEqual16(a, b []byte) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
diff --git a/internal/repository/mysql/file_manager_folder_repo_test.go b/internal/repository/mysql/file_manager_folder_repo_test.go
new file mode 100644
index 0000000..ac7a4a7
--- /dev/null
+++ b/internal/repository/mysql/file_manager_folder_repo_test.go
@@ -0,0 +1,296 @@
+package mysql
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openFileManagerFolderRepoTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:file_manager_folder_repo_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&filemanager.Folder{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestNewFileManagerFolderRepository(t *testing.T) {
+	db := openFileManagerFolderRepoTestDB(t)
+	repo := NewFileManagerFolderRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestFileManagerFolderRepositoryCreateAndGetByID(t *testing.T) {
+	db := openFileManagerFolderRepoTestDB(t)
+	repo := NewFileManagerFolderRepository(db)
+
+	row := &filemanager.Folder{
+		Name:           "Operations",
+		NameNormalized: "operations",
+		NameSlot:       "live",
+		Depth:          0,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("create folder: %v", err)
+	}
+	if len(row.ID) != 16 {
+		t.Fatalf("expected generated id")
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id: %v", err)
+	}
+	if got == nil || got.Name != "Operations" {
+		t.Fatalf("expected created folder")
+	}
+
+	missing, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+	if err != nil {
+		t.Fatalf("get missing by id: %v", err)
+	}
+	if missing != nil {
+		t.Fatalf("expected nil for missing folder")
+	}
+}
+
+func TestFileManagerFolderRepositoryUpdate(t *testing.T) {
+	db := openFileManagerFolderRepoTestDB(t)
+	repo := NewFileManagerFolderRepository(db)
+
+	row := &filemanager.Folder{
+		Name:           "Old Name",
+		NameNormalized: "old name",
+		NameSlot:       "live",
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Name = "New Name"
+	row.NameNormalized = "new name"
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("update folder: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get after update: %v", err)
+	}
+	if got == nil || got.Name != "New Name" || got.NameNormalized != "new name" {
+		t.Fatalf("unexpected updated row: %+v", got)
+	}
+}
+
+func TestFileManagerFolderRepositoryDelete(t *testing.T) {
+	db := openFileManagerFolderRepoTestDB(t)
+	repo := NewFileManagerFolderRepository(db)
+
+	row := &filemanager.Folder{
+		Name:           "Delete Me",
+		NameNormalized: "delete me",
+		NameSlot:       "live",
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	deletedBy := uuidv7.MustBytes()
+	purgeAt := time.Now().UTC().Add(24 * time.Hour).Truncate(time.Second)
+	if err := repo.Delete(context.Background(), row.ID, deletedBy, &purgeAt); err != nil {
+		t.Fatalf("delete folder: %v", err)
+	}
+
+	active, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get after delete: %v", err)
+	}
+	if active != nil {
+		t.Fatalf("expected deleted row hidden from GetByID")
+	}
+
+	var stored filemanager.Folder
+	if err := db.WithContext(context.Background()).Unscoped().Where("id = ?", row.ID).First(&stored).Error; err != nil {
+		t.Fatalf("unscoped find: %v", err)
+	}
+	if stored.DeletedAt == nil {
+		t.Fatalf("expected deleted_at populated")
+	}
+	if stored.PurgeAt == nil || !stored.PurgeAt.Equal(purgeAt) {
+		t.Fatalf("expected purge_at set")
+	}
+	if !bytes.Equal(stored.DeletedBy, deletedBy) {
+		t.Fatalf("expected deleted_by set")
+	}
+	if stored.NameSlot == "live" {
+		t.Fatalf("expected name_slot switched from live on delete")
+	}
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy, nil); err == nil {
+		t.Fatalf("expected record not found on second delete")
+	}
+}
+
+func TestFileManagerFolderRepositoryRestorePurgeAndTrashQueries(t *testing.T) {
+	db := openFileManagerFolderRepoTestDB(t)
+	repo := NewFileManagerFolderRepository(db)
+
+	row := &filemanager.Folder{
+		Name:           "Archive",
+		NameNormalized: "archive",
+		NameSlot:       "live",
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("create folder: %v", err)
+	}
+	deletedBy := uuidv7.MustBytes()
+	if err := repo.Delete(context.Background(), row.ID, deletedBy, nil); err != nil {
+		t.Fatalf("delete folder: %v", err)
+	}
+
+	anyRow, err := repo.GetByIDAny(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id any: %v", err)
+	}
+	if anyRow == nil || anyRow.DeletedAt == nil {
+		t.Fatalf("expected deleted row from GetByIDAny")
+	}
+
+	trashRows, trashTotal, err := repo.ListTrashByParent(context.Background(), nil, "", 10, 0)
+	if err != nil {
+		t.Fatalf("list trash by parent: %v", err)
+	}
+	if trashTotal != 1 || len(trashRows) != 1 {
+		t.Fatalf("expected one trashed folder")
+	}
+
+	restoreBy := uuidv7.MustBytes()
+	if err := repo.Restore(context.Background(), row.ID, restoreBy); err != nil {
+		t.Fatalf("restore folder: %v", err)
+	}
+	restored, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get restored folder: %v", err)
+	}
+	if restored == nil || restored.DeletedAt != nil || restored.NameSlot != "live" {
+		t.Fatalf("expected restored live folder")
+	}
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy, nil); err != nil {
+		t.Fatalf("delete folder 2: %v", err)
+	}
+	if err := repo.Purge(context.Background(), row.ID); err != nil {
+		t.Fatalf("purge folder: %v", err)
+	}
+	if got, err := repo.GetByIDAny(context.Background(), row.ID); err != nil || got != nil {
+		t.Fatalf("expected purged folder gone, got=%v err=%v", got, err)
+	}
+	if err := repo.Purge(context.Background(), row.ID); err == nil {
+		t.Fatalf("expected purge not found on second call")
+	}
+}
+
+func TestFileManagerFolderRepositoryGetByParentAndName(t *testing.T) {
+	db := openFileManagerFolderRepoTestDB(t)
+	repo := NewFileManagerFolderRepository(db)
+
+	root := &filemanager.Folder{Name: "Root", NameNormalized: "root", NameSlot: "live"}
+	if err := repo.Create(context.Background(), root); err != nil {
+		t.Fatalf("create root: %v", err)
+	}
+
+	child := &filemanager.Folder{
+		ParentID:       root.ID,
+		Name:           "Child",
+		NameNormalized: "child",
+		NameSlot:       "live",
+		Depth:          1,
+	}
+	if err := repo.Create(context.Background(), child); err != nil {
+		t.Fatalf("create child: %v", err)
+	}
+
+	gotRoot, err := repo.GetByParentAndName(context.Background(), nil, "root")
+	if err != nil {
+		t.Fatalf("get root by parent/name: %v", err)
+	}
+	if gotRoot == nil || !bytes.Equal(gotRoot.ID, root.ID) {
+		t.Fatalf("expected root by nil parent")
+	}
+
+	gotChild, err := repo.GetByParentAndName(context.Background(), root.ID, "child")
+	if err != nil {
+		t.Fatalf("get child by parent/name: %v", err)
+	}
+	if gotChild == nil || !bytes.Equal(gotChild.ID, child.ID) {
+		t.Fatalf("expected child by parent/name")
+	}
+
+	notFound, err := repo.GetByParentAndName(context.Background(), root.ID, "missing")
+	if err != nil {
+		t.Fatalf("get missing by parent/name: %v", err)
+	}
+	if notFound != nil {
+		t.Fatalf("expected nil on missing folder")
+	}
+}
+
+func TestFileManagerFolderRepositoryListByParent(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		db := openFileManagerFolderRepoTestDB(t)
+		repo := NewFileManagerFolderRepository(db)
+
+		rootA := &filemanager.Folder{Name: "B", NameNormalized: "b", NameSlot: "live"}
+		rootB := &filemanager.Folder{Name: "A", NameNormalized: "a", NameSlot: "live"}
+		_ = repo.Create(context.Background(), rootA)
+		_ = repo.Create(context.Background(), rootB)
+
+		rows, total, err := repo.ListByParent(context.Background(), nil, "name ASC", 1, 0)
+		if err != nil {
+			t.Fatalf("list root folders: %v", err)
+		}
+		if total != 2 {
+			t.Fatalf("expected total 2, got %d", total)
+		}
+		if len(rows) != 1 || rows[0].Name != "A" {
+			t.Fatalf("expected sorted+limited list")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openFileManagerFolderRepoTestDB(t)
+		repo := NewFileManagerFolderRepository(db)
+		if err := db.Migrator().DropTable(&filemanager.Folder{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+		if _, _, err := repo.ListByParent(context.Background(), nil, "", 10, 0); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openFileManagerFolderRepoTestDB(t)
+		repo := NewFileManagerFolderRepository(db)
+		_ = repo.Create(context.Background(), &filemanager.Folder{Name: "X", NameNormalized: "x", NameSlot: "live"})
+		if _, _, err := repo.ListByParent(context.Background(), nil, "name ASC, )", 10, 0); err == nil {
+			t.Fatalf("expected find error")
+		}
+	})
+}
diff --git a/internal/repository/mysql/file_processing_outbox_repo.go b/internal/repository/mysql/file_processing_outbox_repo.go
new file mode 100644
index 0000000..9b7d430
--- /dev/null
+++ b/internal/repository/mysql/file_processing_outbox_repo.go
@@ -0,0 +1,161 @@
+package mysql
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	filemanager "wucher/internal/domain/file_manager"
+)
+
+func (r *FileManagerFileRepository) WithTransaction(
+	ctx context.Context,
+	fn func(repo filemanager.FileRepository, outbox filemanager.FileProcessingOutboxWriter) error,
+) error {
+	if fn == nil {
+		return nil
+	}
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		txRepo := &FileManagerFileRepository{db: tx}
+		return fn(txRepo, txRepo)
+	})
+}
+
+func (r *FileManagerFileRepository) CreateFileProcessingOutboxMessage(ctx context.Context, message *filemanager.FileProcessingOutboxMessage) error {
+	if message == nil {
+		return gorm.ErrInvalidData
+	}
+	return r.db.WithContext(ctx).Create(message).Error
+}
+
+func (r *FileManagerFileRepository) ClaimPendingFileProcessingOutboxMessages(
+	ctx context.Context,
+	limit int,
+	now time.Time,
+	lockTTL time.Duration,
+	workerID string,
+) ([]filemanager.FileProcessingOutboxMessage, error) {
+	if limit <= 0 {
+		limit = 1
+	}
+	if lockTTL <= 0 {
+		lockTTL = time.Minute
+	}
+	now = now.UTC()
+	staleBefore := now.Add(-lockTTL)
+	workerID = strings.TrimSpace(workerID)
+	if workerID == "" {
+		workerID = "worker"
+	}
+
+	var messages []filemanager.FileProcessingOutboxMessage
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.
+			Clauses(clause.Locking{Strength: "UPDATE", Options: "SKIP LOCKED"}).
+			Where(
+				"((status = ? AND available_at <= ?) OR (status = ? AND locked_at IS NOT NULL AND locked_at < ?))",
+				filemanager.FileProcessingOutboxStatusPending,
+				now,
+				filemanager.FileProcessingOutboxStatusProcessing,
+				staleBefore,
+			).
+			Order("available_at ASC, created_at ASC").
+			Limit(limit).
+			Find(&messages).Error; err != nil {
+			return err
+		}
+		if len(messages) == 0 {
+			return nil
+		}
+
+		ids := make([][]byte, 0, len(messages))
+		for i := range messages {
+			ids = append(ids, messages[i].ID)
+		}
+
+		if err := tx.Model(&filemanager.FileProcessingOutboxMessage{}).
+			Where("id IN ?", ids).
+			Updates(map[string]any{
+				"status":     filemanager.FileProcessingOutboxStatusProcessing,
+				"locked_at":  now,
+				"locked_by":  workerID,
+				"updated_at": now,
+				"attempts":   gorm.Expr("attempts + ?", 1),
+			}).Error; err != nil {
+			return err
+		}
+
+		for i := range messages {
+			messages[i].Status = filemanager.FileProcessingOutboxStatusProcessing
+			messages[i].Attempts++
+			ts := now
+			messages[i].LockedAt = &ts
+			messages[i].LockedBy = workerID
+			messages[i].UpdatedAt = now
+		}
+		return nil
+	})
+	return messages, err
+}
+
+func (r *FileManagerFileRepository) MarkFileProcessingOutboxMessagePublished(ctx context.Context, id []byte, publishedAt time.Time) error {
+	publishedAt = publishedAt.UTC()
+	return r.db.WithContext(ctx).
+		Model(&filemanager.FileProcessingOutboxMessage{}).
+		Where("id = ?", id).
+		Updates(map[string]any{
+			"status":       filemanager.FileProcessingOutboxStatusPublished,
+			"published_at": publishedAt,
+			"locked_at":    nil,
+			"locked_by":    "",
+			"last_error":   "",
+			"updated_at":   publishedAt,
+		}).Error
+}
+
+func (r *FileManagerFileRepository) MarkFileProcessingOutboxMessageRetry(ctx context.Context, id []byte, availableAt time.Time, lastErr string) error {
+	availableAt = availableAt.UTC()
+	return r.db.WithContext(ctx).
+		Model(&filemanager.FileProcessingOutboxMessage{}).
+		Where("id = ?", id).
+		Updates(map[string]any{
+			"status":       filemanager.FileProcessingOutboxStatusPending,
+			"available_at": availableAt,
+			"locked_at":    nil,
+			"locked_by":    "",
+			"last_error":   truncateOutboxError(strings.TrimSpace(lastErr), 4096),
+			"updated_at":   time.Now().UTC(),
+		}).Error
+}
+
+func (r *FileManagerFileRepository) MarkFileProcessingOutboxMessageDead(ctx context.Context, id []byte, failedAt time.Time, lastErr string) error {
+	failedAt = failedAt.UTC()
+	return r.db.WithContext(ctx).
+		Model(&filemanager.FileProcessingOutboxMessage{}).
+		Where("id = ?", id).
+		Updates(map[string]any{
+			"status":       filemanager.FileProcessingOutboxStatusDead,
+			"available_at": failedAt,
+			"locked_at":    nil,
+			"locked_by":    "",
+			"last_error":   truncateOutboxError(strings.TrimSpace(lastErr), 4096),
+			"updated_at":   failedAt,
+		}).Error
+}
+
+func (r *FileManagerFileRepository) CountPendingFileProcessingOutboxMessages(ctx context.Context, now time.Time) (int64, error) {
+	var count int64
+	err := r.db.WithContext(ctx).
+		Model(&filemanager.FileProcessingOutboxMessage{}).
+		Where(
+			"(status = ? AND available_at <= ?) OR status = ?",
+			filemanager.FileProcessingOutboxStatusPending,
+			now.UTC(),
+			filemanager.FileProcessingOutboxStatusProcessing,
+		).
+		Count(&count).Error
+	return count, err
+}
diff --git a/internal/repository/mysql/file_status_realtime_event_repo.go b/internal/repository/mysql/file_status_realtime_event_repo.go
new file mode 100644
index 0000000..c12cc35
--- /dev/null
+++ b/internal/repository/mysql/file_status_realtime_event_repo.go
@@ -0,0 +1,24 @@
+package mysql
+
+import (
+	"context"
+	"time"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+)
+
+func (r *FileManagerFileRepository) CreateFileStatusRealtimeEvent(ctx context.Context, input filemanager.FileStatusRealtimeEventInput) error {
+	if r == nil || r.db == nil {
+		return gorm.ErrInvalidDB
+	}
+	if input.OccurredAt.IsZero() {
+		input.OccurredAt = time.Now().UTC()
+	}
+	row, err := filemanager.NewFileStatusRealtimeEvent(input)
+	if err != nil {
+		return err
+	}
+	return r.db.WithContext(ctx).Create(row).Error
+}
diff --git a/internal/repository/mysql/file_upload_intent_repo.go b/internal/repository/mysql/file_upload_intent_repo.go
new file mode 100644
index 0000000..a57467f
--- /dev/null
+++ b/internal/repository/mysql/file_upload_intent_repo.go
@@ -0,0 +1,107 @@
+package mysql
+
+import (
+	"context"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	filemanager "wucher/internal/domain/file_manager"
+)
+
+func (r *FileManagerFileRepository) CreateUploadIntent(ctx context.Context, row *filemanager.FileUploadIntent) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *FileManagerFileRepository) GetUploadIntentByID(ctx context.Context, id []byte) (*filemanager.FileUploadIntent, error) {
+	var row filemanager.FileUploadIntent
+	err := r.db.WithContext(ctx).Where("id = ?", id).First(&row).Error
+	if err == nil {
+		return &row, nil
+	}
+	if err == gorm.ErrRecordNotFound {
+		return nil, nil
+	}
+	return nil, err
+}
+
+func (r *FileManagerFileRepository) GetUploadIntentByIDForUpdate(ctx context.Context, id []byte) (*filemanager.FileUploadIntent, error) {
+	var row filemanager.FileUploadIntent
+	err := r.db.WithContext(ctx).
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("id = ?", id).
+		First(&row).Error
+	if err == nil {
+		return &row, nil
+	}
+	if err == gorm.ErrRecordNotFound {
+		return nil, nil
+	}
+	return nil, err
+}
+
+func (r *FileManagerFileRepository) MarkUploadIntentCompleted(ctx context.Context, params filemanager.FileUploadIntentCompleteParams) error {
+	completedAt := params.CompletedAt
+	if completedAt.IsZero() {
+		completedAt = time.Now().UTC()
+	}
+
+	res := r.db.WithContext(ctx).
+		Model(&filemanager.FileUploadIntent{}).
+		Where("id = ? AND status = ?", params.ID, filemanager.FileUploadIntentStatusPending).
+		Updates(map[string]any{
+			"status":       filemanager.FileUploadIntentStatusCompleted,
+			"completed_at": completedAt.UTC(),
+			"updated_by":   params.UpdatedBy,
+			"updated_at":   completedAt.UTC(),
+		})
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *FileManagerFileRepository) MarkUploadIntentExpired(ctx context.Context, params filemanager.FileUploadIntentExpireParams) error {
+	expiredAt := params.ExpiredAt
+	if expiredAt.IsZero() {
+		expiredAt = time.Now().UTC()
+	}
+
+	res := r.db.WithContext(ctx).
+		Model(&filemanager.FileUploadIntent{}).
+		Where("id = ? AND status = ?", params.ID, filemanager.FileUploadIntentStatusPending).
+		Updates(map[string]any{
+			"status":     filemanager.FileUploadIntentStatusExpired,
+			"updated_by": params.UpdatedBy,
+			"updated_at": expiredAt.UTC(),
+		})
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *FileManagerFileRepository) UpdateUploadIntentSize(ctx context.Context, params filemanager.FileUploadIntentSizeUpdateParams) error {
+	res := r.db.WithContext(ctx).
+		Model(&filemanager.FileUploadIntent{}).
+		Where("id = ? AND status = ?", params.ID, filemanager.FileUploadIntentStatusPending).
+		Updates(map[string]any{
+			"size_bytes": params.SizeBytes,
+			"updated_by": params.UpdatedBy,
+			"updated_at": time.Now().UTC(),
+		})
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
diff --git a/internal/repository/mysql/fleet_history_repo.go b/internal/repository/mysql/fleet_history_repo.go
new file mode 100644
index 0000000..4e6a219
--- /dev/null
+++ b/internal/repository/mysql/fleet_history_repo.go
@@ -0,0 +1,51 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	fleethistory "wucher/internal/domain/fleet_history"
+)
+
+type FleetHistoryRepository struct{ db *gorm.DB }
+
+func NewFleetHistoryRepository(db *gorm.DB) *FleetHistoryRepository {
+	return &FleetHistoryRepository{db: db}
+}
+
+func (r *FleetHistoryRepository) Create(ctx context.Context, row *fleethistory.FleetHistory) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *FleetHistoryRepository) ListByHelicopter(ctx context.Context, helicopterID []byte, limit, offset int) ([]fleethistory.FleetHistory, int64, error) {
+	rows := make([]fleethistory.FleetHistory, 0)
+	var total int64
+	base := r.db.WithContext(ctx).
+		Model(&fleethistory.FleetHistory{}).
+		Where("helicopter_id = ?", helicopterID)
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	q := base.Order("created_at DESC")
+	if limit > 0 {
+		q = q.Limit(limit).Offset(offset)
+	}
+	err := q.Find(&rows).Error
+	return rows, total, err
+}
+
+func (r *FleetHistoryRepository) HelicopterIDByInspection(ctx context.Context, inspectionID []byte) ([]byte, error) {
+	var out []byte
+	err := r.db.WithContext(ctx).
+		Table("reserve_acs").
+		Select("helicopter_id").
+		Where("inspection_id = ?", inspectionID).
+		Limit(1).
+		Scan(&out).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return out, err
+}
diff --git a/internal/repository/mysql/fleet_status_repo.go b/internal/repository/mysql/fleet_status_repo.go
new file mode 100644
index 0000000..c163728
--- /dev/null
+++ b/internal/repository/mysql/fleet_status_repo.go
@@ -0,0 +1,278 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	fleetstatus "wucher/internal/domain/fleet_status"
+)
+
+type FleetStatusRepository struct {
+	db *gorm.DB
+}
+
+func NewFleetStatusRepository(db *gorm.DB) *FleetStatusRepository {
+	return &FleetStatusRepository{db: db}
+}
+
+func (r *FleetStatusRepository) Create(ctx context.Context, row *fleetstatus.FleetStatus) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *FleetStatusRepository) CreateWithDB(ctx context.Context, db *gorm.DB, row *fleetstatus.FleetStatus) error {
+	return db.WithContext(ctx).Create(row).Error
+}
+
+func (r *FleetStatusRepository) Update(ctx context.Context, row *fleetstatus.FleetStatus) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Model(&fleetstatus.FleetStatus{}).
+			Where("id = ? AND deleted_at IS NULL", row.ID).
+			Updates(map[string]any{
+				"helicopter_id": row.HelicopterID,
+				"status":        row.Status,
+				"serviced_at":   row.ServicedAt,
+				"updated_by":    row.UpdatedBy,
+			}).Error; err != nil {
+			return err
+		}
+		if err := tx.Where("fleet_status_id = ?", row.ID).Delete(&fleetstatus.MaintenanceSchedule{}).Error; err != nil {
+			return err
+		}
+		if len(row.MaintenanceSchedules) > 0 {
+			for i := range row.MaintenanceSchedules {
+				row.MaintenanceSchedules[i].FleetStatusID = row.ID
+			}
+			if err := tx.Create(&row.MaintenanceSchedules).Error; err != nil {
+				return err
+			}
+		}
+		if err := tx.Where("fleet_status_id = ?", row.ID).Delete(&fleetstatus.FleetStatusFile{}).Error; err != nil {
+			return err
+		}
+		if len(row.Files) > 0 {
+			for i := range row.Files {
+				row.Files[i].FleetStatusID = row.ID
+			}
+			if err := tx.Create(&row.Files).Error; err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+}
+
+func (r *FleetStatusRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	return r.db.WithContext(ctx).
+		Model(&fleetstatus.FleetStatus{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(map[string]any{"deleted_at": now, "deleted_by": deletedBy, "updated_by": deletedBy}).Error
+}
+
+func (r *FleetStatusRepository) GetByID(ctx context.Context, id []byte) (*fleetstatus.FleetStatus, error) {
+	var row fleetstatus.FleetStatus
+	err := r.db.WithContext(ctx).
+		Preload("Helicopter").
+		Preload("MaintenanceSchedules").
+		Preload("Files").
+		Preload("Files.Attachment").
+		Preload("Files.Attachment.File").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FleetStatusRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]fleetstatus.FleetStatus, int64, error) {
+	rows := make([]fleetstatus.FleetStatus, 0)
+	var total int64
+	base := r.db.WithContext(ctx).
+		Model(&fleetstatus.FleetStatus{}).
+		Where("deleted_at IS NULL")
+	if strings.TrimSpace(filter) != "" {
+		like := "%" + strings.ToLower(strings.TrimSpace(filter)) + "%"
+		base = base.Where("LOWER(HEX(id)) LIKE ? OR LOWER(HEX(helicopter_id)) LIKE ?", like, like)
+	}
+	query := base
+	if strings.TrimSpace(sort) != "" {
+		query = query.Order(sort)
+	} else {
+		query = query.Order("created_at DESC")
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Preload("Helicopter").
+		Preload("MaintenanceSchedules").
+		Preload("Files").
+		Preload("Files.Attachment").
+		Preload("Files.Attachment.File").
+		Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func (r *FleetStatusRepository) MarkServiced(ctx context.Context, id []byte, servicedAt time.Time, actorID []byte) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var row fleetstatus.FleetStatus
+		if err := tx.Preload("Helicopter").
+			Preload("MaintenanceSchedules").
+			Where("id = ? AND deleted_at IS NULL", id).
+			First(&row).Error; err != nil {
+			return err
+		}
+
+		if len(row.MaintenanceSchedules) > 0 {
+			logs := make([]fleetstatus.FleetStatusServiceLog, 0, len(row.MaintenanceSchedules))
+			for i := range row.MaintenanceSchedules {
+				item := row.MaintenanceSchedules[i]
+				logs = append(logs, fleetstatus.FleetStatusServiceLog{
+					FleetStatusID:  row.ID,
+					HelicopterID:   row.HelicopterID,
+					InspectionType: item.InspectionType,
+					Type:           item.Type,
+					Due:            item.Due,
+					Ext:            item.Ext,
+					ServicedAt:     servicedAt,
+					CreatedBy:      actorID,
+				})
+			}
+			if err := tx.Create(&logs).Error; err != nil {
+				return err
+			}
+		}
+
+		if err := tx.Where("fleet_status_id = ?", row.ID).Delete(&fleetstatus.MaintenanceSchedule{}).Error; err != nil {
+			return err
+		}
+
+		return tx.Model(&fleetstatus.FleetStatus{}).
+			Where("id = ? AND deleted_at IS NULL", row.ID).
+			Updates(map[string]any{
+				"status":      fleetstatus.StatusServiced,
+				"serviced_at": servicedAt,
+				"updated_by":  actorID,
+			}).
+			Error
+	})
+}
+
+func (r *FleetStatusRepository) LatestByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]*fleetstatus.FleetStatus, error) {
+	out := make(map[string]*fleetstatus.FleetStatus)
+
+	filtered := make([][]byte, 0, len(helicopterIDs))
+	seen := make(map[string]struct{}, len(helicopterIDs))
+	for _, id := range helicopterIDs {
+		if len(id) != 16 {
+			continue
+		}
+		key := string(id)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		filtered = append(filtered, append([]byte(nil), id...))
+	}
+	if len(filtered) == 0 {
+		return out, nil
+	}
+
+	rows := make([]fleetstatus.FleetStatus, 0)
+	// Ordered newest-first so the first row seen per helicopter is its latest.
+	if err := r.db.WithContext(ctx).
+		Where("deleted_at IS NULL").
+		Where("helicopter_id IN ?", filtered).
+		Order("created_at DESC, id DESC").
+		Preload("Helicopter").
+		Preload("MaintenanceSchedules").
+		Preload("Files").
+		Preload("Files.Attachment").
+		Preload("Files.Attachment.File").
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	for i := range rows {
+		key := string(rows[i].HelicopterID)
+		if _, ok := out[key]; ok {
+			continue
+		}
+		row := rows[i]
+		out[key] = &row
+	}
+	return out, nil
+}
+
+func (r *FleetStatusRepository) ListServiceHistoryByHelicopterID(ctx context.Context, helicopterID []byte, limit, offset int) ([]fleetstatus.FleetStatusServiceLog, int64, error) {
+	rows := make([]fleetstatus.FleetStatusServiceLog, 0)
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&fleetstatus.FleetStatusServiceLog{}).
+		Where("helicopter_id = ?", helicopterID)
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	query := base.Order("serviced_at DESC, created_at DESC")
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Preload("Helicopter").Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func (r *FleetStatusRepository) HelicopterIDsWithFleetStatus(ctx context.Context) ([][]byte, error) {
+	type rowT struct {
+		HelicopterID []byte `gorm:"column:helicopter_id"`
+	}
+	rows := make([]rowT, 0)
+	err := r.db.WithContext(ctx).
+		Table("fleet_statuses").
+		Select("DISTINCT helicopter_id").
+		Where("deleted_at IS NULL").
+		Scan(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	out := make([][]byte, 0, len(rows))
+	for i := range rows {
+		if len(rows[i].HelicopterID) == 16 {
+			out = append(out, rows[i].HelicopterID)
+		}
+	}
+	return out, nil
+}
+
+func (r *FleetStatusRepository) HelicopterIDByMissionID(ctx context.Context, missionID []byte) ([]byte, error) {
+	if len(missionID) != 16 {
+		return nil, nil
+	}
+	var out struct {
+		HelicopterID []byte `gorm:"column:helicopter_id"`
+	}
+	err := r.db.WithContext(ctx).
+		Table("missions m").
+		Select("ra.helicopter_id AS helicopter_id").
+		Joins("JOIN flights f ON f.id = m.flight_id AND f.deleted_at IS NULL").
+		Joins("JOIN takeover_acs ta ON ta.id = f.takeover_ac_id AND ta.deleted_at IS NULL").
+		Joins("JOIN reserve_acs ra ON ra.id = ta.reserve_ac_id AND ra.deleted_at IS NULL").
+		Where("m.id = ? AND m.deleted_at IS NULL", missionID).
+		Limit(1).
+		Scan(&out).Error
+	if err != nil {
+		return nil, err
+	}
+	return out.HelicopterID, nil
+}
+
diff --git a/internal/repository/mysql/fleet_status_repo_test.go b/internal/repository/mysql/fleet_status_repo_test.go
new file mode 100644
index 0000000..2baca48
--- /dev/null
+++ b/internal/repository/mysql/fleet_status_repo_test.go
@@ -0,0 +1,91 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	"wucher/internal/domain/helicopter"
+)
+
+func openFleetStatusTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:fleet_status_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(
+		&filemanager.Folder{}, &filemanager.File{}, &filemanager.Attachment{},
+		&helicopter.Helicopter{},
+		&fleetstatus.FleetStatus{}, &fleetstatus.MaintenanceSchedule{}, &fleetstatus.FleetStatusFile{},
+	); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestFleetStatusRepositoryLatestByHelicopterIDs(t *testing.T) {
+	db := openFleetStatusTestDB(t)
+	repo := NewFleetStatusRepository(db)
+	ctx := context.Background()
+
+	heliRepo := NewHelicopterRepository(db)
+	h1 := &helicopter.Helicopter{Designation: "H1", Identifier: "PK-H1", Type: "Twin"}
+	h2 := &helicopter.Helicopter{Designation: "H2", Identifier: "PK-H2", Type: "Twin"}
+	h3 := &helicopter.Helicopter{Designation: "H3", Identifier: "PK-H3", Type: "Twin"} // no fleet status
+	for _, h := range []*helicopter.Helicopter{h1, h2, h3} {
+		if err := heliRepo.Create(ctx, h); err != nil {
+			t.Fatalf("create helicopter: %v", err)
+		}
+	}
+
+	// h1: older then newer (newer = created last = latest). Plus a deleted row
+	// created last, which must be ignored.
+	if err := repo.Create(ctx, &fleetstatus.FleetStatus{HelicopterID: h1.ID, Status: fleetstatus.StatusActive}); err != nil {
+		t.Fatalf("create fs1a: %v", err)
+	}
+	fs1bNewer := &fleetstatus.FleetStatus{HelicopterID: h1.ID, Status: fleetstatus.StatusServiced}
+	if err := repo.Create(ctx, fs1bNewer); err != nil {
+		t.Fatalf("create fs1b: %v", err)
+	}
+	deleted := &fleetstatus.FleetStatus{HelicopterID: h1.ID, Status: fleetstatus.StatusActive}
+	if err := repo.Create(ctx, deleted); err != nil {
+		t.Fatalf("create deleted: %v", err)
+	}
+	if err := repo.Delete(ctx, deleted.ID, nil); err != nil {
+		t.Fatalf("delete fs: %v", err)
+	}
+
+	// h2: single record.
+	fs2 := &fleetstatus.FleetStatus{HelicopterID: h2.ID, Status: fleetstatus.StatusActive}
+	if err := repo.Create(ctx, fs2); err != nil {
+		t.Fatalf("create fs2: %v", err)
+	}
+
+	out, err := repo.LatestByHelicopterIDs(ctx, [][]byte{h1.ID, h2.ID, h3.ID})
+	if err != nil {
+		t.Fatalf("LatestByHelicopterIDs: %v", err)
+	}
+
+	if got := out[string(h1.ID)]; got == nil || string(got.ID) != string(fs1bNewer.ID) {
+		t.Fatalf("h1 latest mismatch: got %+v, want fs1b (status served, not deleted)", got)
+	}
+	if got := out[string(h1.ID)]; got != nil && got.Status != fleetstatus.StatusServiced {
+		t.Fatalf("h1 latest should be the serviced row, got status %q", got.Status)
+	}
+	if got := out[string(h2.ID)]; got == nil || string(got.ID) != string(fs2.ID) {
+		t.Fatalf("h2 latest mismatch: got %+v", got)
+	}
+	if _, ok := out[string(h3.ID)]; ok {
+		t.Fatalf("h3 has no fleet status and must be absent from the map")
+	}
+}
diff --git a/internal/repository/mysql/flight_data_repo.go b/internal/repository/mysql/flight_data_repo.go
new file mode 100644
index 0000000..5ddc6cc
--- /dev/null
+++ b/internal/repository/mysql/flight_data_repo.go
@@ -0,0 +1,594 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"log"
+	"time"
+
+	"gorm.io/gorm"
+
+	flightdata "wucher/internal/domain/flight_data"
+	"wucher/internal/shared/pkg/txctx"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type FlightDataRepository struct {
+	db                    *gorm.DB
+	hasHesloFlightsTable  bool
+	hasHesloSlingsTable   bool
+	hasLoggingSlingsTable bool
+	hasHecFlightsTable    bool
+	hasHecSlingsTable     bool
+	hasHecLoadsTable      bool
+}
+
+func NewFlightDataRepository(db *gorm.DB) *FlightDataRepository {
+	schema := newSchemaCache(db)
+	return &FlightDataRepository{
+		db:                    db,
+		hasHesloFlightsTable:  schema.HasTable("heslo_flights"),
+		hasHesloSlingsTable:   schema.HasTable("heslo_slings"),
+		hasLoggingSlingsTable: schema.HasTable("logging_slings"),
+		hasHecFlightsTable:    schema.HasTable("hec_flights"),
+		hasHecSlingsTable:     schema.HasTable("hec_slings"),
+		hasHecLoadsTable:      schema.HasTable("hec_loads"),
+	}
+}
+
+func (r *FlightDataRepository) Create(ctx context.Context, row *flightdata.FlightData) error {
+	if row == nil {
+		return nil
+	}
+	now := time.Now().UTC()
+	if len(row.ID) != 16 {
+		row.ID = uuidv7.MustBytes()
+	}
+	if row.CreatedAt.IsZero() {
+		row.CreatedAt = now
+	}
+	if row.UpdatedAt.IsZero() {
+		row.UpdatedAt = row.CreatedAt
+	}
+	return txctx.DB(ctx, r.db).Table("flight_data").Create(flightDataPersistenceValues(row)).Error
+}
+
+func (r *FlightDataRepository) Update(ctx context.Context, row *flightdata.FlightData) error {
+	if row == nil {
+		return nil
+	}
+	row.UpdatedAt = time.Now().UTC()
+	updates := flightDataPersistenceValues(row)
+	delete(updates, "id")
+	delete(updates, "created_at")
+	delete(updates, "created_by")
+	return r.db.WithContext(ctx).
+		Model(&flightdata.FlightData{}).
+		Where("id = ?", row.ID).
+		Updates(updates).Error
+}
+
+func (r *FlightDataRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return r.db.WithContext(ctx).
+		Model(&flightdata.FlightData{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error
+}
+
+func (r *FlightDataRepository) GetByID(ctx context.Context, id []byte) (*flightdata.FlightData, error) {
+	var row flightdata.FlightData
+	err := r.db.WithContext(ctx).
+		Preload("Mission").
+		Preload("Mission.Flight").
+		Preload("Mission.Flight.Takeover").
+		Preload("Mission.Flight.Takeover.RosterCrews").
+		Preload("Mission.Flight.Takeover.OtherPeople").
+		Preload("CoPilot").
+		Preload("FromICAO").
+		Preload("FromHospital").
+		Preload("ToICAO").
+		Preload("ToHospital").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FlightDataRepository) GetByMissionID(ctx context.Context, missionID []byte) (*flightdata.FlightData, error) {
+	var row flightdata.FlightData
+	err := r.db.WithContext(ctx).
+		Preload("Mission").
+		Preload("Mission.Flight").
+		Preload("Mission.Flight.Takeover").
+		Preload("Mission.Flight.Takeover.RosterCrews").
+		Preload("Mission.Flight.Takeover.OtherPeople").
+		Preload("CoPilot").
+		Preload("FromICAO").
+		Preload("FromHospital").
+		Preload("ToICAO").
+		Preload("ToHospital").
+		Where("mission_id = ? AND deleted_at IS NULL", missionID).
+		Order("created_at DESC").
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FlightDataRepository) ListByMissionID(ctx context.Context, missionID []byte) ([]flightdata.FlightData, error) {
+	rows := make([]flightdata.FlightData, 0)
+	err := r.db.WithContext(ctx).
+		Preload("Mission").
+		Preload("Mission.Flight").
+		Preload("Mission.Flight.Takeover").
+		Preload("Mission.Flight.Takeover.RosterCrews").
+		Preload("Mission.Flight.Takeover.OtherPeople").
+		Preload("CoPilot").
+		Preload("FromICAO").
+		Preload("FromHospital").
+		Preload("ToICAO").
+		Preload("ToHospital").
+		Where("mission_id = ? AND deleted_at IS NULL", missionID).
+		Order("created_at ASC, id ASC").
+		Find(&rows).Error
+	return rows, err
+}
+
+func (r *FlightDataRepository) GetByFlightID(ctx context.Context, flightID []byte) (*flightdata.FlightData, error) {
+	var row flightdata.FlightData
+	err := r.db.WithContext(ctx).
+		Preload("Mission").
+		Preload("CoPilot").
+		Preload("FromICAO").
+		Preload("FromHospital").
+		Preload("ToICAO").
+		Preload("ToHospital").
+		Where("mission_id IN (SELECT id FROM missions WHERE flight_id = ? AND deleted_at IS NULL) AND deleted_at IS NULL", flightID).
+		Order("created_at DESC").
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FlightDataRepository) List(ctx context.Context, date string, missionID, flightDataID []byte, limit, offset int) ([]flightdata.FlightData, int64, error) {
+	rows := make([]flightdata.FlightData, 0)
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&flightdata.FlightData{}).
+		Preload("Mission").
+		Preload("Mission.Flight").
+		Preload("Mission.Flight.Takeover").
+		Preload("Mission.Flight.Takeover.RosterCrews").
+		Preload("Mission.Flight.Takeover.OtherPeople").
+		Preload("CoPilot").
+		Preload("FromICAO").
+		Preload("FromHospital").
+		Preload("ToICAO").
+		Preload("ToHospital").
+		Where("deleted_at IS NULL")
+	if date != "" {
+		base = base.Where("DATE(take_off) = ?", date)
+	}
+	if len(missionID) == 16 {
+		base = base.Where("mission_id = ?", missionID)
+	}
+	if len(flightDataID) == 16 {
+		base = base.Where("id = ?", flightDataID)
+	}
+
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	query := base.Order("take_off DESC, created_at DESC")
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func (r *FlightDataRepository) GetSPODetailsByFlightDataID(ctx context.Context, flightDataID []byte) (*flightdata.SPODetails, error) {
+	details := &flightdata.SPODetails{
+		HESLO: flightdata.SPOHESLODetails{
+			Flights: make([]flightdata.SPOHESLOFlight, 0),
+			Slings:  make([]flightdata.SPOHESLOSling, 0),
+		},
+		Logging: flightdata.SPOLoggingDetails{
+			Slings: make([]flightdata.SPOLoggingSling, 0),
+		},
+		HEC: flightdata.SPOHECDetails{
+			Flights: make([]flightdata.SPOHECFlight, 0),
+			Slings:  make([]flightdata.SPOHECSling, 0),
+			Loads:   make([]flightdata.SPOHECLoad, 0),
+		},
+	}
+
+	if len(flightDataID) != 16 {
+		return details, nil
+	}
+
+	db := r.db.WithContext(ctx)
+
+	if r.hasHesloFlightsTable {
+		type hesloFlightRow struct {
+			ID               []byte `gorm:"column:id"`
+			ROT              int    `gorm:"column:rot"`
+			FuelTruckID      []byte `gorm:"column:fuel_truck_id"`
+			FuelTruckName    string `gorm:"column:fuel_truck_name"`
+			LoggingSlingID   []byte `gorm:"column:logging_sling_id"`
+			LoggingSlingName string `gorm:"column:logging_sling_name"`
+		}
+		rows := make([]hesloFlightRow, 0)
+		if err := db.Table("heslo_flights hf").
+			Select("hf.id, hf.rot, hf.fuel_truck_id, fuel.name AS fuel_truck_name, hf.logging_sling_id, log.name AS logging_sling_name").
+			Joins("LEFT JOIN facilities fuel ON fuel.id = hf.fuel_truck_id").
+			Joins("LEFT JOIN facilities log ON log.id = hf.logging_sling_id").
+			Where("hf.flight_data_id = ?", flightDataID).
+			Order("hf.created_at ASC").
+			Scan(&rows).Error; err != nil {
+			return nil, err
+		}
+		for i := range rows {
+			details.HESLO.Flights = append(details.HESLO.Flights, flightdata.SPOHESLOFlight{
+				ID:               rows[i].ID,
+				ROT:              rows[i].ROT,
+				FuelTruckID:      rows[i].FuelTruckID,
+				FuelTruckName:    rows[i].FuelTruckName,
+				LoggingSlingID:   rows[i].LoggingSlingID,
+				LoggingSlingName: rows[i].LoggingSlingName,
+			})
+		}
+	}
+
+	if r.hasHesloSlingsTable && r.hasHesloFlightsTable {
+		type hesloSlingRow struct {
+			ID            []byte `gorm:"column:id"`
+			HESLOFlightID []byte `gorm:"column:heslo_flight_id"`
+			SlingID       []byte `gorm:"column:facility_sling_id"`
+			SlingName     string `gorm:"column:sling_name"`
+		}
+		rows := make([]hesloSlingRow, 0)
+		if err := db.Table("heslo_slings hs").
+			Select("hs.id, hs.heslo_flight_id, hs.facility_sling_id, sling.name AS sling_name").
+			Joins("JOIN heslo_flights hf ON hf.id = hs.heslo_flight_id").
+			Joins("LEFT JOIN facilities sling ON sling.id = hs.facility_sling_id").
+			Where("hf.flight_data_id = ?", flightDataID).
+			Order("hs.created_at ASC").
+			Scan(&rows).Error; err != nil {
+			return nil, err
+		}
+		for i := range rows {
+			details.HESLO.Slings = append(details.HESLO.Slings, flightdata.SPOHESLOSling{
+				ID:            rows[i].ID,
+				HESLOFlightID: rows[i].HESLOFlightID,
+				SlingID:       rows[i].SlingID,
+				SlingName:     rows[i].SlingName,
+			})
+		}
+	}
+
+	if r.hasLoggingSlingsTable {
+		type loggingSlingRow struct {
+			ID        []byte `gorm:"column:id"`
+			SlingID   []byte `gorm:"column:facility_sling_id"`
+			SlingName string `gorm:"column:sling_name"`
+		}
+		rows := make([]loggingSlingRow, 0)
+		if err := db.Table("logging_slings ls").
+			Select("ls.id, ls.facility_sling_id, sling.name AS sling_name").
+			Joins("LEFT JOIN facilities sling ON sling.id = ls.facility_sling_id").
+			Where("ls.flight_data_id = ?", flightDataID).
+			Order("ls.created_at ASC").
+			Scan(&rows).Error; err != nil {
+			return nil, err
+		}
+		for i := range rows {
+			details.Logging.Slings = append(details.Logging.Slings, flightdata.SPOLoggingSling{
+				ID:        rows[i].ID,
+				SlingID:   rows[i].SlingID,
+				SlingName: rows[i].SlingName,
+			})
+		}
+	}
+
+	if r.hasHecFlightsTable {
+		type hecFlightRow struct {
+			ID            []byte `gorm:"column:id"`
+			ROT           int    `gorm:"column:rot"`
+			HECCycle      int    `gorm:"column:hec_cycle"`
+			EquipmentID   []byte `gorm:"column:equipment_id"`
+			EquipmentName string `gorm:"column:equipment_name"`
+		}
+		rows := make([]hecFlightRow, 0)
+		if err := db.Table("hec_flights hf").
+			Select("hf.id, hf.rot, hf.hec_cycle, hf.equipment_id, eq.name AS equipment_name").
+			Joins("LEFT JOIN facilities eq ON eq.id = hf.equipment_id").
+			Where("hf.flight_data_id = ?", flightDataID).
+			Order("hf.created_at ASC").
+			Scan(&rows).Error; err != nil {
+			return nil, err
+		}
+		for i := range rows {
+			details.HEC.Flights = append(details.HEC.Flights, flightdata.SPOHECFlight{
+				ID:            rows[i].ID,
+				ROT:           rows[i].ROT,
+				HECCycle:      rows[i].HECCycle,
+				EquipmentID:   rows[i].EquipmentID,
+				EquipmentName: rows[i].EquipmentName,
+			})
+		}
+	}
+
+	if r.hasHecSlingsTable {
+		type hecSlingRow struct {
+			ID        []byte `gorm:"column:id"`
+			SlingID   []byte `gorm:"column:hec_sling_id"`
+			SlingName string `gorm:"column:sling_name"`
+		}
+		rows := make([]hecSlingRow, 0)
+		if err := db.Table("hec_slings hs").
+			Select("hs.id, hs.hec_sling_id, sling.name AS sling_name").
+			Joins("LEFT JOIN facilities sling ON sling.id = hs.hec_sling_id").
+			Where("hs.flight_data_id = ?", flightDataID).
+			Order("hs.created_at ASC").
+			Scan(&rows).Error; err != nil {
+			return nil, err
+		}
+		for i := range rows {
+			details.HEC.Slings = append(details.HEC.Slings, flightdata.SPOHECSling{
+				ID:        rows[i].ID,
+				SlingID:   rows[i].SlingID,
+				SlingName: rows[i].SlingName,
+			})
+		}
+	}
+
+	if r.hasHecLoadsTable {
+		type hecLoadRow struct {
+			ID           []byte `gorm:"column:id"`
+			LoadCategory string `gorm:"column:load_category"`
+			Quantity     int    `gorm:"column:quantity"`
+		}
+		rows := make([]hecLoadRow, 0)
+		if err := db.Table("hec_loads").
+			Select("id, load_category, quantity").
+			Where("flight_data_id = ?", flightDataID).
+			Order("created_at ASC").
+			Scan(&rows).Error; err != nil {
+			return nil, err
+		}
+		for i := range rows {
+			details.HEC.Loads = append(details.HEC.Loads, flightdata.SPOHECLoad{
+				ID:           rows[i].ID,
+				LoadCategory: rows[i].LoadCategory,
+				Quantity:     rows[i].Quantity,
+			})
+		}
+	}
+
+	return details, nil
+}
+
+func (r *FlightDataRepository) UpsertSPODetails(ctx context.Context, flightDataID []byte, data *flightdata.SPOUpsertData) error {
+	if len(flightDataID) != 16 || data == nil {
+		return nil
+	}
+	log.Printf("[UpsertSPODetails] start: heslo=%v logging=%v hec=%v hasHesloFlights=%v hasLogging=%v hasHecFlights=%v",
+		data.HESLO != nil, data.Logging != nil, data.HEC != nil,
+		r.hasHesloFlightsTable, r.hasLoggingSlingsTable, r.hasHecFlightsTable)
+
+	txErr := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		now := time.Now().UTC()
+
+		if data.HESLO != nil && r.hasHesloFlightsTable {
+			if r.hasHesloSlingsTable {
+				if err := tx.Exec(
+					"DELETE hs FROM heslo_slings hs JOIN heslo_flights hf ON hf.id = hs.heslo_flight_id WHERE hf.flight_data_id = ?",
+					flightDataID,
+				).Error; err != nil {
+					return err
+				}
+			}
+			if err := tx.Exec("DELETE FROM heslo_flights WHERE flight_data_id = ?", flightDataID).Error; err != nil {
+				return err
+			}
+			for _, f := range data.HESLO.Flights {
+				hf := &flightdata.HESLOFlight{
+					ID:                  uuidv7.MustBytes(),
+					FlightDataID:        flightDataID,
+					ROT:                 f.ROT,
+					FacilityFuelTruckID: f.FuelTruckID,
+					LoggingSlingID:      f.LoggingSlingID,
+					CreatedAt:           now,
+				}
+				if err := tx.Omit("FlightData", "FacilityFuelTruck", "LoggingSling").Create(hf).Error; err != nil {
+					return err
+				}
+				if r.hasHesloSlingsTable {
+					for _, s := range f.Slings {
+						if len(s.SlingID) != 16 {
+							continue
+						}
+						hs := &flightdata.HESLOSling{
+							ID:              uuidv7.MustBytes(),
+							HESLOFlightID:   hf.ID,
+							FacilitySlingID: s.SlingID,
+							CreatedAt:       now,
+						}
+						if err := tx.Omit("HESLOFlight", "FacilitySling").Create(hs).Error; err != nil {
+							return err
+						}
+					}
+				}
+			}
+		}
+
+		if data.Logging != nil && r.hasLoggingSlingsTable {
+			if err := tx.Exec("DELETE FROM logging_slings WHERE flight_data_id = ?", flightDataID).Error; err != nil {
+				return err
+			}
+			for _, s := range data.Logging.Slings {
+				if len(s.SlingID) != 16 {
+					continue
+				}
+				ls := &flightdata.LoggingSling{
+					ID:              uuidv7.MustBytes(),
+					FlightDataID:    flightDataID,
+					FacilitySlingID: s.SlingID,
+					CreatedAt:       now,
+				}
+				if err := tx.Omit("FlightData", "FacilitySling").Create(ls).Error; err != nil {
+					return err
+				}
+			}
+		}
+
+		if data.HEC != nil {
+			if r.hasHecSlingsTable {
+				if err := tx.Exec("DELETE FROM hec_slings WHERE flight_data_id = ?", flightDataID).Error; err != nil {
+					return err
+				}
+			}
+			if r.hasHecLoadsTable {
+				if err := tx.Exec("DELETE FROM hec_loads WHERE flight_data_id = ?", flightDataID).Error; err != nil {
+					return err
+				}
+			}
+			if r.hasHecFlightsTable {
+				if err := tx.Exec("DELETE FROM hec_flights WHERE flight_data_id = ?", flightDataID).Error; err != nil {
+					return err
+				}
+				for _, f := range data.HEC.Flights {
+					hf := &flightdata.HECFlight{
+						ID:           uuidv7.MustBytes(),
+						FlightDataID: flightDataID,
+						ROT:          f.ROT,
+						HECCycle:     f.HECCycle,
+						EquipmentID:  f.EquipmentID,
+						CreatedAt:    now,
+					}
+					if err := tx.Omit("FlightData", "Equipment").Create(hf).Error; err != nil {
+						return err
+					}
+				}
+			}
+			if r.hasHecSlingsTable {
+				for _, s := range data.HEC.Slings {
+					if len(s.SlingID) != 16 {
+						continue
+					}
+					hs := &flightdata.HECSling{
+						ID:           uuidv7.MustBytes(),
+						FlightDataID: flightDataID,
+						HECSlingID:   s.SlingID,
+						CreatedAt:    now,
+					}
+					if err := tx.Omit("FlightData", "HECSling").Create(hs).Error; err != nil {
+						return err
+					}
+				}
+			}
+			if r.hasHecLoadsTable {
+				for _, l := range data.HEC.Loads {
+					hl := &flightdata.HECLoads{
+						ID:           uuidv7.MustBytes(),
+						FlightDataID: flightDataID,
+						LoadCategory: l.LoadCategory,
+						Quantity:     l.Quantity,
+						CreatedAt:    now,
+					}
+					if err := tx.Omit("FlightData").Create(hl).Error; err != nil {
+						return err
+					}
+				}
+			}
+		}
+
+		return nil
+	})
+	log.Printf("[UpsertSPODetails] done: err=%v", txErr)
+	return txErr
+}
+
+func flightDataPersistenceValues(row *flightdata.FlightData) map[string]any {
+	if row == nil {
+		return map[string]any{}
+	}
+	return map[string]any{
+		"id":                      nullableBytesValue(row.ID),
+		"mission_id":              nullableBytesValue(row.MissionID),
+		"co_pilot_id":             nullableBytesValue(row.CoPilotID),
+		"from_icao_id":            nullableBytesValue(row.FromICAOID),
+		"from_hospital_id":        nullableBytesValue(row.FromHospitalID),
+		"to_icao_id":              nullableBytesValue(row.ToICAOID),
+		"to_hospital_id":          nullableBytesValue(row.ToHospitalID),
+		"take_off":                nullableTimeValue(row.FlightTakeOff),
+		"landing":                 nullableTimeValue(row.FlightLanding),
+		"duration":                row.FlightDuration,
+		"flight_type":             row.FlightType,
+		"red":                     row.FlightRED,
+		"max_n1":                  row.MaxN1,
+		"max_n2":                  row.MaxN2,
+		"pax_count":               row.PaxCount,
+		"ticket_no":               row.TicketNo,
+		"engine":                  row.Engine,
+		"landing_count":           row.LandingCount,
+		"rotor_brake_cycle":       row.RotorBrakeCycle,
+		"hook_releases":           row.HookReleases,
+		"delivery_note_number":    row.DeliveryNoteNumber,
+		"customer_name":           row.CustomerName,
+		"flight_plan_distance":    row.FlightPlanDistance,
+		"flight_plan_time":        row.FlightPlanTime,
+		"flight_plan_true_course": row.FlightPlanTrueCourse,
+		"fuel_before_flight":      row.FuelBeforeFlight,
+		"fuel_upload":             row.FuelUpload,
+		"fuel_after_flight":       row.FuelAfterFlight,
+		"fuel_planning":           row.FuelPlanning,
+		"flight_position":         row.FlightPositioning,
+		"other_information":       row.OtherInformation,
+		"status":                  row.Status,
+		"created_at":              row.CreatedAt,
+		"created_by":              nullableBytesValue(row.CreatedBy),
+		"updated_at":              row.UpdatedAt,
+		"updated_by":              nullableBytesValue(row.UpdatedBy),
+		"deleted_at":              nullableTimePtrValue(row.DeletedAt),
+		"deleted_by":              nullableBytesValue(row.DeletedBy),
+	}
+}
+
+func nullableBytesValue(v []byte) any {
+	if len(v) == 0 {
+		return nil
+	}
+	return v
+}
+
+func nullableTimeValue(v time.Time) any {
+	if v.IsZero() {
+		return nil
+	}
+	return v
+}
+
+func nullableTimePtrValue(v *time.Time) any {
+	if v == nil {
+		return nil
+	}
+	return *v
+}
diff --git a/internal/repository/mysql/flight_data_repo_test.go b/internal/repository/mysql/flight_data_repo_test.go
new file mode 100644
index 0000000..c354a46
--- /dev/null
+++ b/internal/repository/mysql/flight_data_repo_test.go
@@ -0,0 +1,110 @@
+package mysql
+
+import (
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	flightdata "wucher/internal/domain/flight_data"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openFlightDataTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:flight_data_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	return db
+}
+
+func TestFlightDataPersistenceValues_AllowsNullableLocationFields(t *testing.T) {
+	row := &flightdata.FlightData{
+		ID:                   uuidv7.MustBytes(),
+		MissionID:            uuidv7.MustBytes(),
+		CoPilotID:            uuidv7.MustBytes(),
+		FromHospitalID:       uuidv7.MustBytes(),
+		ToICAOID:             uuidv7.MustBytes(),
+		CreatedAt:            time.Now().UTC(),
+		UpdatedAt:            time.Now().UTC(),
+		CreatedBy:            uuidv7.MustBytes(),
+		UpdatedBy:            uuidv7.MustBytes(),
+		Status:               flightdata.StatusInProgress,
+		FlightTakeOff:        time.Now().UTC(),
+		FlightLanding:        time.Now().UTC(),
+		FlightDuration:       4 * time.Second,
+		FlightRED:            10 * time.Second,
+		FlightPlanTime:       10 * time.Second,
+		FlightPlanDistance:   10,
+		FlightPlanTrueCourse: 10,
+		FuelBeforeFlight:     10,
+		FuelUpload:           10,
+		FuelAfterFlight:      10,
+		FuelPlanning:         10,
+	}
+
+	values := flightDataPersistenceValues(row)
+	if values["from_icao_id"] != nil {
+		t.Fatalf("expected from_icao_id to be nil, got %#v", values["from_icao_id"])
+	}
+	if values["to_hospital_id"] != nil {
+		t.Fatalf("expected to_hospital_id to be nil, got %#v", values["to_hospital_id"])
+	}
+	if values["from_hospital_id"] == nil {
+		t.Fatal("expected from_hospital_id to be populated")
+	}
+	if values["to_icao_id"] == nil {
+		t.Fatal("expected to_icao_id to be populated")
+	}
+	if values["status"] != flightdata.StatusInProgress {
+		t.Fatalf("expected status to be on_progress, got %#v", values["status"])
+	}
+}
+
+func TestFlightDataPersistenceValues_ZeroTimesBecomeNull(t *testing.T) {
+	row := &flightdata.FlightData{
+		ID:        uuidv7.MustBytes(),
+		MissionID: uuidv7.MustBytes(),
+		CoPilotID: uuidv7.MustBytes(),
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+		CreatedBy: uuidv7.MustBytes(),
+		UpdatedBy: uuidv7.MustBytes(),
+	}
+
+	values := flightDataPersistenceValues(row)
+	if values["take_off"] != nil {
+		t.Fatalf("expected take_off to be nil, got %#v", values["take_off"])
+	}
+	if values["landing"] != nil {
+		t.Fatalf("expected landing to be nil, got %#v", values["landing"])
+	}
+}
+
+func TestNewFlightDataRepositoryCachesOptionalTables(t *testing.T) {
+	db := openFlightDataTestDB(t)
+	for _, stmt := range []string{
+		`CREATE TABLE heslo_flights (id BLOB PRIMARY KEY, flight_data_id BLOB, created_at DATETIME)`,
+		`CREATE TABLE heslo_slings (id BLOB PRIMARY KEY, heslo_flight_id BLOB, created_at DATETIME)`,
+		`CREATE TABLE logging_slings (id BLOB PRIMARY KEY, flight_data_id BLOB, created_at DATETIME)`,
+		`CREATE TABLE hec_flights (id BLOB PRIMARY KEY, flight_data_id BLOB, created_at DATETIME)`,
+		`CREATE TABLE hec_slings (id BLOB PRIMARY KEY, flight_data_id BLOB, created_at DATETIME)`,
+		`CREATE TABLE hec_loads (id BLOB PRIMARY KEY, flight_data_id BLOB, created_at DATETIME)`,
+	} {
+		if err := db.Exec(stmt).Error; err != nil {
+			t.Fatalf("create table: %v", err)
+		}
+	}
+
+	repo := NewFlightDataRepository(db)
+	if !repo.hasHesloFlightsTable || !repo.hasHesloSlingsTable || !repo.hasLoggingSlingsTable ||
+		!repo.hasHecFlightsTable || !repo.hasHecSlingsTable || !repo.hasHecLoadsTable {
+		t.Fatalf("expected all optional table flags to be cached as true")
+	}
+}
diff --git a/internal/repository/mysql/flight_inspection_file_checklist_repo.go b/internal/repository/mysql/flight_inspection_file_checklist_repo.go
new file mode 100644
index 0000000..0360eb2
--- /dev/null
+++ b/internal/repository/mysql/flight_inspection_file_checklist_repo.go
@@ -0,0 +1,110 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"gorm.io/gorm"
+
+	flightinspection "wucher/internal/domain/flight_inspection"
+	flightinspectionfilechecklist "wucher/internal/domain/flight_inspection_file_checklist"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+)
+
+type FlightInspectionFileChecklistRepository struct {
+	db *gorm.DB
+}
+
+func NewFlightInspectionFileChecklistRepository(db *gorm.DB) *FlightInspectionFileChecklistRepository {
+	return &FlightInspectionFileChecklistRepository{db: db}
+}
+
+func (r *FlightInspectionFileChecklistRepository) Create(ctx context.Context, row *flightinspectionfilechecklist.FlightInspectionFileChecklist) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *FlightInspectionFileChecklistRepository) Update(ctx context.Context, row *flightinspectionfilechecklist.FlightInspectionFileChecklist) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *FlightInspectionFileChecklistRepository) Delete(ctx context.Context, id []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "flight_inspection_file_checklists", id); err != nil {
+		return err
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).Delete(&flightinspectionfilechecklist.FlightInspectionFileChecklist{}, "id = ?", id).Error)
+}
+
+func (r *FlightInspectionFileChecklistRepository) GetByID(ctx context.Context, id []byte) (*flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+	var row flightinspectionfilechecklist.FlightInspectionFileChecklist
+	err := r.db.WithContext(ctx).Where("id = ?", id).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FlightInspectionFileChecklistRepository) List(ctx context.Context, filter string, sort string, limit, offset int) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, int64, error) {
+	rows := make([]flightinspectionfilechecklist.FlightInspectionFileChecklist, 0)
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&flightinspectionfilechecklist.FlightInspectionFileChecklist{})
+	if strings.TrimSpace(filter) != "" {
+		like := "%" + strings.ToLower(strings.TrimSpace(filter)) + "%"
+		base = base.Where(
+			"LOWER(HEX(id)) LIKE ? OR LOWER(HEX(flight_inspection_id)) LIKE ? OR LOWER(HEX(helicopter_file_id)) LIKE ? OR CAST(is_done AS CHAR) LIKE ?",
+			like, like, like, like,
+		)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func (r *FlightInspectionFileChecklistRepository) ListByInspectionID(ctx context.Context, inspectionID []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+	rows := make([]flightinspectionfilechecklist.FlightInspectionFileChecklist, 0)
+	if len(inspectionID) != 16 {
+		return rows, nil
+	}
+	err := r.db.WithContext(ctx).
+		Where("flight_inspection_id = ?", inspectionID).
+		Order("is_done ASC, created_at ASC").
+		Find(&rows).Error
+	return rows, err
+}
+
+func (r *FlightInspectionFileChecklistRepository) FlightInspectionExists(ctx context.Context, inspectionID []byte) (bool, error) {
+	if len(inspectionID) != 16 {
+		return false, nil
+	}
+	var total int64
+	err := r.db.WithContext(ctx).
+		Model(&flightinspection.FlightInspection{}).
+		Where("id = ?", inspectionID).
+		Count(&total).Error
+	return total > 0, err
+}
+
+func (r *FlightInspectionFileChecklistRepository) HelicopterFileExists(ctx context.Context, helicopterFileID []byte) (bool, error) {
+	if len(helicopterFileID) != 16 {
+		return false, nil
+	}
+	var total int64
+	err := r.db.WithContext(ctx).
+		Model(&helicopterfile.HelicopterFile{}).
+		Where("id = ?", helicopterFileID).
+		Count(&total).Error
+	return total > 0, err
+}
diff --git a/internal/repository/mysql/flight_inspection_repo.go b/internal/repository/mysql/flight_inspection_repo.go
new file mode 100644
index 0000000..7b75773
--- /dev/null
+++ b/internal/repository/mysql/flight_inspection_repo.go
@@ -0,0 +1,60 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	flightinspection "wucher/internal/domain/flight_inspection"
+)
+
+type FlightInspectionRepository struct {
+	db *gorm.DB
+}
+
+func NewFlightInspectionRepository(db *gorm.DB) *FlightInspectionRepository {
+	return &FlightInspectionRepository{db: db}
+}
+
+func (r *FlightInspectionRepository) Create(ctx context.Context, row *flightinspection.FlightInspection) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *FlightInspectionRepository) Update(ctx context.Context, row *flightinspection.FlightInspection) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *FlightInspectionRepository) GetByID(ctx context.Context, id []byte) (*flightinspection.FlightInspection, error) {
+	var row flightinspection.FlightInspection
+	err := r.db.WithContext(ctx).Where("id = ?", id).Take(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &row, nil
+}
+
+func (r *FlightInspectionRepository) List(ctx context.Context, sort string, limit, offset int) ([]flightinspection.FlightInspection, int64, error) {
+	rows := make([]flightinspection.FlightInspection, 0)
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&flightinspection.FlightInspection{})
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/flight_prep_check_repo.go b/internal/repository/mysql/flight_prep_check_repo.go
new file mode 100644
index 0000000..57aeb80
--- /dev/null
+++ b/internal/repository/mysql/flight_prep_check_repo.go
@@ -0,0 +1,44 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	flightprepcheck "wucher/internal/domain/flight_prep_check"
+)
+
+type FlightPrepCheckRepository struct {
+	db *gorm.DB
+}
+
+func NewFlightPrepCheckRepository(db *gorm.DB) *FlightPrepCheckRepository {
+	return &FlightPrepCheckRepository{db: db}
+}
+
+func (r *FlightPrepCheckRepository) Create(ctx context.Context, check *flightprepcheck.FlightPrepCheck) error {
+	return r.db.WithContext(ctx).Create(check).Error
+}
+
+func (r *FlightPrepCheckRepository) Update(ctx context.Context, check *flightprepcheck.FlightPrepCheck) error {
+	return r.db.WithContext(ctx).Save(check).Error
+}
+
+func (r *FlightPrepCheckRepository) GetByID(ctx context.Context, id []byte) (*flightprepcheck.FlightPrepCheck, error) {
+	var check flightprepcheck.FlightPrepCheck
+	err := r.db.WithContext(ctx).Where("id = ?", id).First(&check).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &check, err
+}
+
+func (r *FlightPrepCheckRepository) GetByFlightInspectionID(ctx context.Context, flightInspectionID []byte) (*flightprepcheck.FlightPrepCheck, error) {
+	var check flightprepcheck.FlightPrepCheck
+	err := r.db.WithContext(ctx).Where("flight_inspection_id = ?", flightInspectionID).First(&check).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &check, err
+}
diff --git a/internal/repository/mysql/flight_repo.go b/internal/repository/mysql/flight_repo.go
new file mode 100644
index 0000000..01ed862
--- /dev/null
+++ b/internal/repository/mysql/flight_repo.go
@@ -0,0 +1,385 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/flight"
+)
+
+type FlightRepository struct {
+	db *gorm.DB
+}
+
+func preloadTakeoverRelations(q *gorm.DB) *gorm.DB {
+	return q.
+		Preload("Takeover").
+		Preload("Takeover.Base").
+		Preload("Takeover.Base.OperationalShiftTimes").
+		Preload("Takeover.ReserveAc").
+		Preload("Takeover.ReserveAc.Aircraft").
+		Preload("Takeover.ReserveAc.Inspection").
+		Preload("Takeover.RosterCrews").
+		Preload("Takeover.OtherPeople")
+}
+
+func NewFlightRepository(db *gorm.DB) *FlightRepository {
+	return &FlightRepository{db: db}
+}
+
+func (r *FlightRepository) Create(ctx context.Context, row *flight.Flight) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *FlightRepository) GetLatestMissionCodeByPrefix(ctx context.Context, prefix string) (string, error) {
+	var out struct {
+		MissionCode string `gorm:"column:mission_code"`
+	}
+	err := r.db.WithContext(ctx).
+		Table("flights").
+		Select("mission_code").
+		Where("mission_code LIKE ? AND deleted_at IS NULL", prefix+"%").
+		Order("mission_code DESC").
+		Limit(1).
+		Scan(&out).Error
+	if err != nil {
+		return "", err
+	}
+	return out.MissionCode, nil
+}
+
+func (r *FlightRepository) Update(ctx context.Context, row *flight.Flight) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *FlightRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return r.db.WithContext(ctx).
+		Model(&flight.Flight{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error
+}
+
+func (r *FlightRepository) GetByID(ctx context.Context, id []byte) (*flight.Flight, error) {
+	var row flight.Flight
+	err := r.db.WithContext(ctx).
+		Model(&flight.Flight{}).
+		Select(flightReadSelectSQL()).
+		Preload("Takeover").
+		Preload("Takeover.Base").
+		Preload("Takeover.Base.OperationalShiftTimes").
+		Preload("Takeover.ReserveAc").
+		Preload("Takeover.ReserveAc.Aircraft").
+		Preload("Takeover.ReserveAc.Inspection").
+		Preload("Takeover.RosterCrews").
+		Preload("Takeover.OtherPeople").
+		Joins("LEFT JOIN users cu ON cu.id = flights.created_by").
+		Joins("LEFT JOIN users uu ON uu.id = flights.updated_by").
+		Where("flights.id = ? AND flights.deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FlightRepository) ListByUserID(ctx context.Context, userID []byte, limit, offset int) ([]flight.Flight, int64, error) {
+	rows := make([]flight.Flight, 0)
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&flight.Flight{}).
+		Select(flightReadSelectSQL()).
+		Preload("Takeover").
+		Preload("Takeover.Base").
+		Preload("Takeover.ReserveAc").
+		Preload("Takeover.ReserveAc.Aircraft").
+		Preload("Takeover.ReserveAc.Inspection").
+		Preload("Takeover.RosterCrews").
+		Preload("Takeover.OtherPeople").
+		Joins("LEFT JOIN users cu ON cu.id = flights.created_by").
+		Joins("LEFT JOIN users uu ON uu.id = flights.updated_by").
+		Where("flights.deleted_at IS NULL").
+		Where(
+			`EXISTS (
+				SELECT 1
+				FROM duty_roster_crews c
+				JOIN duty_rosters r ON r.id = c.roster_id
+				WHERE c.user_id = ?
+					AND c.deleted_at IS NULL
+					AND r.deleted_at IS NULL
+					AND r.flight_id = flights.id
+			)`,
+			userID,
+		)
+
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	query := base.Order("flights.date DESC, flights.created_at DESC")
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func (r *FlightRepository) ListByCreatedBy(ctx context.Context, createdBy []byte, filter string, date string, sort string, limit, offset int) ([]flight.Flight, int64, error) {
+	rows := make([]flight.Flight, 0)
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&flight.Flight{}).
+		Select(flightReadSelectSQL()).
+		Preload("Takeover").
+		Preload("Takeover.Base").
+		Preload("Takeover.ReserveAc").
+		Preload("Takeover.ReserveAc.Aircraft").
+		Preload("Takeover.ReserveAc.Inspection").
+		Preload("Takeover.RosterCrews").
+		Preload("Takeover.OtherPeople").
+		Joins("LEFT JOIN users cu ON cu.id = flights.created_by").
+		Joins("LEFT JOIN users uu ON uu.id = flights.updated_by").
+		Where("flights.deleted_at IS NULL").
+		Where("flights.created_by = ?", createdBy)
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("flights.mission_code LIKE ?", like)
+	}
+	if date != "" {
+		base = base.Where("flights.date = ?", date)
+	}
+
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		query = query.Order("flights.date DESC, flights.created_at DESC")
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func (r *FlightRepository) GetByReserveAcID(ctx context.Context, reserveAcID []byte) (*flight.Flight, error) {
+	var row flight.Flight
+	err := r.db.WithContext(ctx).
+		Model(&flight.Flight{}).
+		Select(flightReadSelectSQL()).
+		Preload("Takeover").
+		Preload("Takeover.Base").
+		Preload("Takeover.ReserveAc").
+		Preload("Takeover.ReserveAc.Aircraft").
+		Preload("Takeover.ReserveAc.Inspection").
+		Preload("Takeover.RosterCrews").
+		Preload("Takeover.OtherPeople").
+		Joins("LEFT JOIN users cu ON cu.id = flights.created_by").
+		Joins("LEFT JOIN users uu ON uu.id = flights.updated_by").
+		Joins("JOIN takeover_acs ta ON ta.id = flights.takeover_ac_id AND ta.deleted_at IS NULL").
+		Where("ta.reserve_ac_id = ? AND flights.deleted_at IS NULL", reserveAcID).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FlightRepository) ListByReserveAcID(ctx context.Context, reserveAcID []byte) ([]flight.Flight, error) {
+	rows := make([]flight.Flight, 0)
+	err := r.db.WithContext(ctx).
+		Model(&flight.Flight{}).
+		Select(flightReadSelectSQL()).
+		Preload("Takeover").
+		Preload("Takeover.Base").
+		Preload("Takeover.ReserveAc").
+		Preload("Takeover.ReserveAc.Aircraft").
+		Preload("Takeover.ReserveAc.Inspection").
+		Preload("Takeover.RosterCrews").
+		Preload("Takeover.OtherPeople").
+		Joins("LEFT JOIN users cu ON cu.id = flights.created_by").
+		Joins("LEFT JOIN users uu ON uu.id = flights.updated_by").
+		Joins("JOIN takeover_acs ta ON ta.id = flights.takeover_ac_id AND ta.deleted_at IS NULL").
+		Where("ta.reserve_ac_id = ? AND flights.deleted_at IS NULL", reserveAcID).
+		Order("flights.created_at ASC, flights.id ASC").
+		Find(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *FlightRepository) GetByTakeoverAcID(ctx context.Context, takeoverAcID []byte) (*flight.Flight, error) {
+	var row flight.Flight
+	err := r.db.WithContext(ctx).
+		Model(&flight.Flight{}).
+		Select(flightReadSelectSQL()).
+		Preload("Takeover").
+		Preload("Takeover.Base").
+		Preload("Takeover.ReserveAc").
+		Preload("Takeover.ReserveAc.Aircraft").
+		Preload("Takeover.ReserveAc.Inspection").
+		Preload("Takeover.RosterCrews").
+		Preload("Takeover.OtherPeople").
+		Joins("LEFT JOIN users cu ON cu.id = flights.created_by").
+		Joins("LEFT JOIN users uu ON uu.id = flights.updated_by").
+		Where("flights.takeover_ac_id = ? AND flights.deleted_at IS NULL", takeoverAcID).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FlightRepository) ListByTakeoverAcIDs(ctx context.Context, takeoverAcIDs [][]byte) ([]flight.Flight, error) {
+	if len(takeoverAcIDs) == 0 {
+		return []flight.Flight{}, nil
+	}
+	rows := make([]flight.Flight, 0)
+	err := r.db.WithContext(ctx).
+		Model(&flight.Flight{}).
+		Select(flightListSelectSQL()).
+		Preload("Takeover").
+		Preload("Takeover.Base").
+		Preload("Takeover.ReserveAc").
+		Preload("Takeover.ReserveAc.Aircraft").
+		Preload("Takeover.ReserveAc.Inspection").
+		Preload("Takeover.RosterCrews").
+		Preload("Takeover.OtherPeople").
+		Where("flights.takeover_ac_id IN ? AND flights.deleted_at IS NULL", takeoverAcIDs).
+		Find(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *FlightRepository) GetByDutyRosterID(ctx context.Context, dutyRosterID []byte) (*flight.Flight, error) {
+	var row flight.Flight
+	err := r.db.WithContext(ctx).
+		Model(&flight.Flight{}).
+		Select(flightListSelectSQL()).
+		Preload("Takeover").
+		Preload("Takeover.Base").
+		Preload("Takeover.ReserveAc").
+		Preload("Takeover.ReserveAc.Aircraft").
+		Preload("Takeover.ReserveAc.Inspection").
+		Preload("Takeover.RosterCrews").
+		Preload("Takeover.OtherPeople").
+		Joins("JOIN duty_rosters dr ON dr.flight_id = flights.id AND dr.deleted_at IS NULL").
+		Where("dr.id = ? AND flights.deleted_at IS NULL", dutyRosterID).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FlightRepository) ListByDutyRosterIDs(ctx context.Context, dutyRosterIDs [][]byte) ([]flight.Flight, error) {
+	if len(dutyRosterIDs) == 0 {
+		return []flight.Flight{}, nil
+	}
+	rows := make([]flight.Flight, 0)
+	err := r.db.WithContext(ctx).
+		Model(&flight.Flight{}).
+		Select(flightListSelectSQL()).
+		Preload("Takeover").
+		Preload("Takeover.ReserveAc").
+		Preload("Takeover.ReserveAc.Aircraft").
+		Preload("Takeover.ReserveAc.Inspection").
+		Joins("JOIN duty_rosters dr ON dr.flight_id = flights.id AND dr.deleted_at IS NULL").
+		Where("dr.id IN ? AND flights.deleted_at IS NULL", dutyRosterIDs).
+		Find(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *FlightRepository) List(ctx context.Context, filter string, date string, sort string, limit, offset int) ([]flight.Flight, int64, error) {
+	rows := make([]flight.Flight, 0)
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&flight.Flight{}).
+		Select(flightReadSelectSQL()).
+		Preload("Takeover").
+		Preload("Takeover.Base").
+		Preload("Takeover.ReserveAc").
+		Preload("Takeover.ReserveAc.Aircraft").
+		Preload("Takeover.ReserveAc.Inspection").
+		Preload("Takeover.RosterCrews").
+		Preload("Takeover.OtherPeople").
+		Joins("LEFT JOIN users cu ON cu.id = flights.created_by").
+		Joins("LEFT JOIN users uu ON uu.id = flights.updated_by").
+		Where("flights.deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("flights.mission_code LIKE ?", like)
+	}
+	if date != "" {
+		base = base.Where("flights.date = ?", date)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func flightListSelectSQL() string {
+	// created_by_name / updated_by_name are resolved via correlated subqueries so the list
+	// queries carry the auditor display names without needing extra user JOINs (the read
+	// query joins users; the list variants don't). Keeps get-all in parity with get-by-id.
+	return `flights.*,
+		(SELECT dr.id FROM duty_rosters dr WHERE dr.flight_id = flights.id AND dr.deleted_at IS NULL LIMIT 1) AS duty_roster_id,
+		(SELECT ta.reserve_ac_id FROM takeover_acs ta WHERE ta.id = flights.takeover_ac_id AND ta.deleted_at IS NULL LIMIT 1) AS reserve_ac_id,
+		COALESCE((SELECT NULLIF(TRIM(CONCAT(COALESCE(cu.first_name, ''), ' ', COALESCE(cu.last_name, ''))), '')
+			FROM users cu WHERE cu.id = flights.created_by), '') AS created_by_name,
+		COALESCE((SELECT NULLIF(TRIM(CONCAT(COALESCE(uu.first_name, ''), ' ', COALESCE(uu.last_name, ''))), '')
+			FROM users uu WHERE uu.id = flights.updated_by), '') AS updated_by_name`
+}
+
+func flightReadSelectSQL() string {
+	return `flights.*,
+		(SELECT dr.id FROM duty_rosters dr WHERE dr.flight_id = flights.id AND dr.deleted_at IS NULL LIMIT 1) AS duty_roster_id,
+		(SELECT ta.reserve_ac_id FROM takeover_acs ta WHERE ta.id = flights.takeover_ac_id AND ta.deleted_at IS NULL LIMIT 1) AS reserve_ac_id,
+		COALESCE(
+			NULLIF(TRIM(CONCAT(COALESCE(cu.first_name, ''), ' ', COALESCE(cu.last_name, ''))), ''),
+			''
+		) AS created_by_name,
+		COALESCE(
+			NULLIF(TRIM(CONCAT(COALESCE(uu.first_name, ''), ' ', COALESCE(uu.last_name, ''))), ''),
+			''
+		) AS updated_by_name`
+}
diff --git a/internal/repository/mysql/flight_repo_test.go b/internal/repository/mysql/flight_repo_test.go
new file mode 100644
index 0000000..89cd324
--- /dev/null
+++ b/internal/repository/mysql/flight_repo_test.go
@@ -0,0 +1,126 @@
+package mysql
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"wucher/internal/domain/base"
+	"wucher/internal/domain/flight"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	"wucher/internal/domain/helicopter"
+	reserveac "wucher/internal/domain/reserve_ac"
+	takeoverdomain "wucher/internal/domain/takeover"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func TestFlightRepository_ListByCreatedBy_PreloadsTakeoverCompletionRelations(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := db.AutoMigrate(
+		&base.Base{},
+		&helicopter.Helicopter{},
+		&flightinspection.FlightInspection{},
+		&reserveac.ReserveAc{},
+		&takeoverdomain.TakeoverAc{},
+		&takeoverdomain.TakeoverRosterCrew{},
+		&takeoverdomain.TakeoverOtherPerson{},
+		&flight.Flight{},
+	); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	if err := db.Exec(`CREATE TABLE users (
+		id BLOB PRIMARY KEY,
+		first_name TEXT,
+		last_name TEXT
+	)`).Error; err != nil {
+		t.Fatalf("create users table: %v", err)
+	}
+	if err := db.Exec(`CREATE TABLE duty_rosters (
+		id BLOB PRIMARY KEY,
+		flight_id BLOB,
+		deleted_at DATETIME NULL
+	)`).Error; err != nil {
+		t.Fatalf("create duty_rosters table: %v", err)
+	}
+
+	now := time.Now().UTC()
+	baseID := uuidv7.MustBytes()
+	heliID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	reserveID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	creatorID := uuidv7.MustBytes()
+
+	if err := db.Create(&base.Base{ID: baseID, BaseName: "Base A", CreatedAt: now, UpdatedAt: now}).Error; err != nil {
+		t.Fatalf("create base: %v", err)
+	}
+	if err := db.Create(&helicopter.Helicopter{ID: heliID, Designation: "H145", Identifier: "D-TEST", Type: "H145", CreatedAt: now, UpdatedAt: now}).Error; err != nil {
+		t.Fatalf("create helicopter: %v", err)
+	}
+	if err := db.Create(&flightinspection.FlightInspection{ID: inspectionID, InspectionDate: now, Status: flightinspection.StatusDraft, CreatedAt: now, UpdatedAt: now}).Error; err != nil {
+		t.Fatalf("create flight inspection: %v", err)
+	}
+	if err := db.Create(&reserveac.ReserveAc{
+		ID:           reserveID,
+		BaseID:       baseID,
+		AircraftID:   heliID,
+		InspectionID: inspectionID,
+		Status:       reserveac.StatusApproved,
+		CreatedAt:    now,
+		UpdatedAt:    now,
+	}).Error; err != nil {
+		t.Fatalf("create reserve ac: %v", err)
+	}
+	if err := db.Create(&takeoverdomain.TakeoverAc{
+		ID:          takeoverID,
+		BaseID:      baseID,
+		ReserveAcID: reserveID,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+		CreatedBy:   creatorID,
+		UpdatedBy:   creatorID,
+	}).Error; err != nil {
+		t.Fatalf("create takeover: %v", err)
+	}
+	if err := db.Create(&takeoverdomain.TakeoverRosterCrew{
+		ID:         uuidv7.MustBytes(),
+		TakeoverID: takeoverID,
+		RoleCode:   "pilot",
+		CrewType:   "main",
+		UserID:     uuidv7.MustBytes(),
+		NameLabel:  "Pilot A",
+		CreatedAt:  now,
+		UpdatedAt:  now,
+	}).Error; err != nil {
+		t.Fatalf("create takeover crew: %v", err)
+	}
+	if err := db.Create(&flight.Flight{
+		ID:           flightID,
+		TakeoverAcID: takeoverID,
+		Status:       "draft",
+		Date:         now,
+		CreatedAt:    now,
+		CreatedBy:    creatorID,
+		UpdatedAt:    now,
+		UpdatedBy:    creatorID,
+	}).Error; err != nil {
+		t.Fatalf("create flight: %v", err)
+	}
+
+	repo := NewFlightRepository(db)
+	rows, total, err := repo.ListByCreatedBy(context.Background(), creatorID, "", "", "", 10, 0)
+	if err != nil {
+		t.Fatalf("list by created by: %v", err)
+	}
+	if total != 1 || len(rows) != 1 {
+		t.Fatalf("unexpected result size total=%d len=%d", total, len(rows))
+	}
+	row := rows[0]
+	if row.Takeover == nil || row.Takeover.Base == nil || row.Takeover.ReserveAc == nil || row.Takeover.ReserveAc.Aircraft == nil || row.Takeover.ReserveAc.Inspection == nil {
+		t.Fatalf("expected takeover relations to be preloaded: %#v", row.Takeover)
+	}
+	if len(row.Takeover.RosterCrews) == 0 {
+		t.Fatalf("expected takeover roster crews to be preloaded")
+	}
+}
diff --git a/internal/repository/mysql/fm_report_repo.go b/internal/repository/mysql/fm_report_repo.go
new file mode 100644
index 0000000..b05c873
--- /dev/null
+++ b/internal/repository/mysql/fm_report_repo.go
@@ -0,0 +1,283 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	fmreport "wucher/internal/domain/fm_report"
+)
+
+type FMReportRepository struct {
+	db *gorm.DB
+}
+
+func NewFMReportRepository(db *gorm.DB) *FMReportRepository {
+	return &FMReportRepository{db: db}
+}
+
+func (r *FMReportRepository) MaxReportSeqByHelicopter(ctx context.Context, helicopterID []byte) (int, error) {
+	if len(helicopterID) != 16 {
+		return 0, nil
+	}
+	var maxSeq *int
+	err := r.db.WithContext(ctx).
+		Model(&fmreport.Report{}).
+		Where("helicopter_id = ? AND report_code IS NOT NULL AND report_code <> '' AND deleted_at IS NULL", helicopterID).
+		Select("MAX(CAST(SUBSTRING_INDEX(report_code, '-', -1) AS UNSIGNED))").
+		Scan(&maxSeq).Error
+	if err != nil {
+		return 0, err
+	}
+	if maxSeq == nil {
+		return 0, nil
+	}
+	return *maxSeq, nil
+}
+
+func (r *FMReportRepository) SetReportCode(ctx context.Context, id []byte, code string) error {
+	if len(id) != 16 {
+		return nil
+	}
+	err := r.db.WithContext(ctx).
+		Model(&fmreport.Report{}).
+		Where("id = ?", id).
+		Update("report_code", code).Error
+	if isDuplicateKeyError(err) {
+		return fmreport.ErrDuplicateReportCode
+	}
+	return err
+}
+
+func isDuplicateKeyError(err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, gorm.ErrDuplicatedKey) {
+		return true
+	}
+	var mysqlErr *mysqldriver.MySQLError
+	return errors.As(err, &mysqlErr) && mysqlErr.Number == 1062
+}
+
+func (r *FMReportRepository) Upsert(ctx context.Context, row *fmreport.Report) error {
+	if row == nil {
+		return nil
+	}
+	return r.db.WithContext(ctx).
+		Clauses(clause.OnConflict{
+			Columns: []clause.Column{{Name: "flight_id"}},
+			DoUpdates: clause.AssignmentColumns([]string{
+				"takeover_id",
+				"flight_inspection_id",
+				"engine1_gpc_n1",
+				"engine1_ptc_n2",
+				"engine2_gpc_n1",
+				"engine2_ptc_n2",
+				"completed_at",
+				"completed_by",
+				"updated_at",
+				"updated_by",
+			}),
+		}).Create(row).Error
+}
+
+func (r *FMReportRepository) GetByFlightID(ctx context.Context, flightID []byte) (*fmreport.Report, error) {
+	var row fmreport.Report
+	err := r.db.WithContext(ctx).
+		Where("flight_id = ? AND deleted_at IS NULL", flightID).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FMReportRepository) List(ctx context.Context, filter fmreport.ListFilter, limit, offset int) ([]fmreport.Report, int64, error) {
+	rows := make([]fmreport.Report, 0)
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&fmreport.Report{}).
+		Joins("JOIN flights f ON f.id = fm_reports.flight_id AND f.deleted_at IS NULL").
+		Where("fm_reports.deleted_at IS NULL")
+
+	if len(filter.FlightID) == 16 {
+		base = base.Where("fm_reports.flight_id = ?", filter.FlightID)
+	}
+	if len(filter.TakeoverID) == 16 {
+		base = base.Where("fm_reports.takeover_id = ?", filter.TakeoverID)
+	}
+	if len(filter.FlightInspectionID) == 16 {
+		base = base.Where("fm_reports.flight_inspection_id = ?", filter.FlightInspectionID)
+	}
+	if strings.TrimSpace(filter.FlightDate) != "" {
+		base = base.Where("f.date = ?", strings.TrimSpace(filter.FlightDate))
+	}
+	if strings.TrimSpace(filter.FromDate) != "" {
+		base = base.Where("f.date >= ?", strings.TrimSpace(filter.FromDate))
+	}
+	if strings.TrimSpace(filter.ToDate) != "" {
+		base = base.Where("f.date <= ?", strings.TrimSpace(filter.ToDate))
+	}
+	if strings.TrimSpace(filter.HelicopterIdentifier) != "" {
+		base = base.
+			Joins("LEFT JOIN takeover_acs ta ON ta.id = fm_reports.takeover_id AND ta.deleted_at IS NULL").
+			Joins("LEFT JOIN reserve_acs ra ON ra.id = ta.reserve_ac_id AND ra.deleted_at IS NULL").
+			Joins("LEFT JOIN helicopters heli ON heli.id = ra.helicopter_id AND heli.deleted_at IS NULL").
+			Where("heli.identifier LIKE ?", "%"+strings.TrimSpace(filter.HelicopterIdentifier)+"%")
+	}
+	if strings.TrimSpace(filter.PilotName) != "" {
+		like := "%" + strings.TrimSpace(filter.PilotName) + "%"
+		base = base.Where(
+			"EXISTS (SELECT 1 FROM takeover_roster_crews trc LEFT JOIN users trc_u ON trc_u.id = trc.user_id WHERE trc.takeover_id = fm_reports.takeover_id AND trc.role_code = 'PILOT' AND trc.deleted_at IS NULL AND (trc.name_label LIKE ? OR CONCAT(trc_u.first_name, ' ', trc_u.last_name) LIKE ?))",
+			like, like,
+		)
+	}
+	if strings.TrimSpace(filter.Search) != "" {
+		like := "%" + strings.TrimSpace(filter.Search) + "%"
+		base = base.Where("(f.mission_code LIKE ? OR COALESCE(fm_reports.engine1_gpc_n1, '') LIKE ? OR COALESCE(fm_reports.engine1_ptc_n2, '') LIKE ? OR COALESCE(fm_reports.engine2_gpc_n1, '') LIKE ? OR COALESCE(fm_reports.engine2_ptc_n2, '') LIKE ?)", like, like, like, like, like)
+	}
+	if filter.HasEngine1GpcN1 != nil {
+		if *filter.HasEngine1GpcN1 {
+			base = base.Where("fm_reports.engine1_gpc_n1 IS NOT NULL AND fm_reports.engine1_gpc_n1 <> ''")
+		} else {
+			base = base.Where("(fm_reports.engine1_gpc_n1 IS NULL OR fm_reports.engine1_gpc_n1 = '')")
+		}
+	}
+	if filter.HasEngine1PtcN2 != nil {
+		if *filter.HasEngine1PtcN2 {
+			base = base.Where("fm_reports.engine1_ptc_n2 IS NOT NULL AND fm_reports.engine1_ptc_n2 <> ''")
+		} else {
+			base = base.Where("(fm_reports.engine1_ptc_n2 IS NULL OR fm_reports.engine1_ptc_n2 = '')")
+		}
+	}
+	if filter.HasEngine2GpcN1 != nil {
+		if *filter.HasEngine2GpcN1 {
+			base = base.Where("fm_reports.engine2_gpc_n1 IS NOT NULL AND fm_reports.engine2_gpc_n1 <> ''")
+		} else {
+			base = base.Where("(fm_reports.engine2_gpc_n1 IS NULL OR fm_reports.engine2_gpc_n1 = '')")
+		}
+	}
+	if filter.HasEngine2PtcN2 != nil {
+		if *filter.HasEngine2PtcN2 {
+			base = base.Where("fm_reports.engine2_ptc_n2 IS NOT NULL AND fm_reports.engine2_ptc_n2 <> ''")
+		} else {
+			base = base.Where("(fm_reports.engine2_ptc_n2 IS NULL OR fm_reports.engine2_ptc_n2 = '')")
+		}
+	}
+
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	query := base.Order(fmReportListSortClause(filter.Sort))
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func fmReportListSortClause(sort string) string {
+	switch strings.ToLower(strings.TrimSpace(sort)) {
+	case "flight_id":
+		return "fm_reports.flight_id ASC"
+	case "-flight_id":
+		return "fm_reports.flight_id DESC"
+	case "takeover_id":
+		return "fm_reports.takeover_id ASC"
+	case "-takeover_id":
+		return "fm_reports.takeover_id DESC"
+	case "flight_inspection_id":
+		return "fm_reports.flight_inspection_id ASC"
+	case "-flight_inspection_id":
+		return "fm_reports.flight_inspection_id DESC"
+	case "flight_date":
+		return "f.date ASC"
+	case "-flight_date":
+		return "f.date DESC"
+	case "created_at":
+		return "fm_reports.created_at ASC"
+	case "-created_at":
+		return "fm_reports.created_at DESC"
+	case "updated_at":
+		return "fm_reports.updated_at ASC"
+	case "-updated_at":
+		return "fm_reports.updated_at DESC"
+	case "engine1_gpc_n1":
+		return "fm_reports.engine1_gpc_n1 ASC"
+	case "-engine1_gpc_n1":
+		return "fm_reports.engine1_gpc_n1 DESC"
+	case "engine1_ptc_n2":
+		return "fm_reports.engine1_ptc_n2 ASC"
+	case "-engine1_ptc_n2":
+		return "fm_reports.engine1_ptc_n2 DESC"
+	case "engine2_gpc_n1":
+		return "fm_reports.engine2_gpc_n1 ASC"
+	case "-engine2_gpc_n1":
+		return "fm_reports.engine2_gpc_n1 DESC"
+	case "engine2_ptc_n2":
+		return "fm_reports.engine2_ptc_n2 ASC"
+	case "-engine2_ptc_n2":
+		return "fm_reports.engine2_ptc_n2 DESC"
+	default:
+		return "f.date DESC, fm_reports.created_at DESC"
+	}
+}
+
+func (r *FMReportRepository) GetByID(ctx context.Context, id []byte) (*fmreport.Report, error) {
+	if len(id) != 16 {
+		return nil, nil
+	}
+	var row fmreport.Report
+	err := r.db.WithContext(ctx).
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *FMReportRepository) Delete(ctx context.Context, id, deletedBy []byte) error {
+	if len(id) != 16 {
+		return nil
+	}
+	return r.db.WithContext(ctx).
+		Model(&fmreport.Report{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(map[string]any{
+			"deleted_at": gorm.Expr("NOW(3)"),
+			"deleted_by": deletedBy,
+			"updated_by": deletedBy,
+		}).Error
+}
+
+func (r *FMReportRepository) CreateFleetHistory(ctx context.Context, row *fmreport.FleetHistory) error {
+	if row == nil {
+		return nil
+	}
+	return r.db.WithContext(ctx).
+		Clauses(clause.OnConflict{
+			Columns:   []clause.Column{{Name: "fm_report_id"}},
+			DoNothing: true,
+		}).Create(row).Error
+}
+
+func (r *FMReportRepository) GetFleetHistoryByReportID(ctx context.Context, reportID []byte) (*fmreport.FleetHistory, error) {
+	var row fmreport.FleetHistory
+	err := r.db.WithContext(ctx).
+		Where("fm_report_id = ?", reportID).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
diff --git a/internal/repository/mysql/fm_report_update_test.go b/internal/repository/mysql/fm_report_update_test.go
new file mode 100644
index 0000000..d8f8f02
--- /dev/null
+++ b/internal/repository/mysql/fm_report_update_test.go
@@ -0,0 +1,68 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	fmreport "wucher/internal/domain/fm_report"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+// TestFMReportUpdatePersistsEngineFields drives the repo Upsert path used by
+// PATCH /fm-reports/update with the exact (correct) engine field names and asserts they
+// persist through a read-back.
+func TestFMReportUpdatePersistsEngineFields(t *testing.T) {
+	dsn := fmt.Sprintf("file:fmreport_update_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{NowFunc: func() time.Time { return time.Now().UTC() }})
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	if err := db.AutoMigrate(&fmreport.Report{}); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	repo := NewFMReportRepository(db)
+	ctx := context.Background()
+
+	flightID := uuidv7.MustBytes()
+	// Seed an in-progress report with no engine values (like the user's).
+	if err := repo.Upsert(ctx, &fmreport.Report{
+		FlightID:           flightID,
+		TakeoverID:         uuidv7.MustBytes(),
+		FlightInspectionID: uuidv7.MustBytes(),
+	}); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	// Apply the user's exact payload values.
+	row, err := repo.GetByFlightID(ctx, flightID)
+	if err != nil || row == nil {
+		t.Fatalf("get seeded: %v row=%v", err, row)
+	}
+	e1g, e1p := "GPC/N1 63.2", "PTC/N2 61.8"
+	e2g, e2p := "GPC/N1 63.2", "PTC/N2 61.8"
+	row.Engine1GpcN1, row.Engine1PtcN2 = &e1g, &e1p
+	row.Engine2GpcN1, row.Engine2PtcN2 = &e2g, &e2p
+	if err := repo.Upsert(ctx, row); err != nil {
+		t.Fatalf("update upsert: %v", err)
+	}
+
+	got, err := repo.GetByFlightID(ctx, flightID)
+	if err != nil || got == nil {
+		t.Fatalf("get after update: %v row=%v", err, got)
+	}
+	if got.Engine1GpcN1 == nil || *got.Engine1GpcN1 != "GPC/N1 63.2" {
+		t.Fatalf("engine1_gpc_n1 = %v, want 'GPC/N1 63.2' (not persisted)", got.Engine1GpcN1)
+	}
+	if got.Engine1PtcN2 == nil || *got.Engine1PtcN2 != "PTC/N2 61.8" {
+		t.Fatalf("engine1_ptc_n2 = %v, want 'PTC/N2 61.8'", got.Engine1PtcN2)
+	}
+	if got.Engine2GpcN1 == nil || *got.Engine2GpcN1 != "GPC/N1 63.2" {
+		t.Fatalf("engine2_gpc_n1 = %v, want 'GPC/N1 63.2'", got.Engine2GpcN1)
+	}
+	t.Logf("engine fields persisted: e1_gpc=%q e1_ptc=%q e2_gpc=%q", *got.Engine1GpcN1, *got.Engine1PtcN2, *got.Engine2GpcN1)
+}
diff --git a/internal/repository/mysql/forces_present_repo.go b/internal/repository/mysql/forces_present_repo.go
new file mode 100644
index 0000000..ad039ce
--- /dev/null
+++ b/internal/repository/mysql/forces_present_repo.go
@@ -0,0 +1,88 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/forces_present"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type ForcesPresentRepository struct {
+	db *gorm.DB
+}
+
+func NewForcesPresentRepository(db *gorm.DB) *ForcesPresentRepository {
+	return &ForcesPresentRepository{db: db}
+}
+
+func (r *ForcesPresentRepository) Create(ctx context.Context, row *forces_present.ForcesPresent) error {
+	requestedIsActive := row.IsActive
+	db := r.db.WithContext(ctx)
+	if err := db.Create(row).Error; err != nil {
+		return err
+	}
+	return db.Model(&forces_present.ForcesPresent{}).Where("id = ?", row.ID).UpdateColumn("is_active", requestedIsActive).Error
+}
+
+func (r *ForcesPresentRepository) Update(ctx context.Context, row *forces_present.ForcesPresent) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *ForcesPresentRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "forces_present", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&forces_present.ForcesPresent{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error)
+}
+
+func (r *ForcesPresentRepository) GetByID(ctx context.Context, id []byte) (*forces_present.ForcesPresent, error) {
+	var row forces_present.ForcesPresent
+	err := r.db.WithContext(ctx).Where("id = ? AND deleted_at IS NULL", id).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *ForcesPresentRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]forces_present.ForcesPresent, int64, error) {
+	var rows []forces_present.ForcesPresent
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&forces_present.ForcesPresent{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("name LIKE ? OR note LIKE ?", like, like)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("forces_present", "is_active", "sortkey", "name", false) {
+			query = query.Order(clause)
+		}
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/forces_present_repo_test.go b/internal/repository/mysql/forces_present_repo_test.go
new file mode 100644
index 0000000..3cf19cc
--- /dev/null
+++ b/internal/repository/mysql/forces_present_repo_test.go
@@ -0,0 +1,238 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/forces_present"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openForcesPresentTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:forces_present_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&forces_present.ForcesPresent{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestNewForcesPresentRepository(t *testing.T) {
+	db := openForcesPresentTestDB(t)
+	repo := NewForcesPresentRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestForcesPresentRepositoryCreate(t *testing.T) {
+	db := openForcesPresentTestDB(t)
+	repo := NewForcesPresentRepository(db)
+	row := &forces_present.ForcesPresent{Name: "Team A"}
+
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(row.ID) == 0 {
+		t.Fatalf("expected id set")
+	}
+	inactive := &forces_present.ForcesPresent{Name: "Team Inactive", IsActive: false}
+	if err := repo.Create(context.Background(), inactive); err != nil {
+		t.Fatalf("create inactive: %v", err)
+	}
+	gotInactive, err := repo.GetByID(context.Background(), inactive.ID)
+	if err != nil {
+		t.Fatalf("get inactive: %v", err)
+	}
+	if gotInactive == nil || gotInactive.IsActive {
+		t.Fatalf("expected inactive forces present persisted as false")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Create(context.Background(), &forces_present.ForcesPresent{Name: "AfterClose"}); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestForcesPresentRepositoryUpdate(t *testing.T) {
+	db := openForcesPresentTestDB(t)
+	repo := NewForcesPresentRepository(db)
+	row := &forces_present.ForcesPresent{Name: "Old"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Name = "New"
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil || loaded == nil || loaded.Name != "New" {
+		t.Fatalf("expected updated row")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestForcesPresentRepositoryDelete(t *testing.T) {
+	db := openForcesPresentTestDB(t)
+	repo := NewForcesPresentRepository(db)
+	row := &forces_present.ForcesPresent{Name: "DeleteMe"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	deletedBy := uuidv7.MustBytes()
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected soft deleted row hidden from GetByID")
+	}
+}
+
+func TestForcesPresentRepositoryGetByID(t *testing.T) {
+	t.Run("found", func(t *testing.T) {
+		db := openForcesPresentTestDB(t)
+		repo := NewForcesPresentRepository(db)
+		row := &forces_present.ForcesPresent{Name: "Found"}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		got, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.Name != "Found" {
+			t.Fatalf("expected row found")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openForcesPresentTestDB(t)
+		repo := NewForcesPresentRepository(db)
+		got, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil for not found")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openForcesPresentTestDB(t)
+		repo := NewForcesPresentRepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, err := repo.GetByID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
+
+func TestForcesPresentRepositoryList(t *testing.T) {
+	t.Run("success without limit", func(t *testing.T) {
+		db := openForcesPresentTestDB(t)
+		repo := NewForcesPresentRepository(db)
+		_ = repo.Create(context.Background(), &forces_present.ForcesPresent{Name: "Charlie"})
+		_ = repo.Create(context.Background(), &forces_present.ForcesPresent{Name: "Alpha"})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("expected 2 rows, total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("success with filter sort and limit", func(t *testing.T) {
+		db := openForcesPresentTestDB(t)
+		repo := NewForcesPresentRepository(db)
+		_ = repo.Create(context.Background(), &forces_present.ForcesPresent{Name: "Main Team"})
+		_ = repo.Create(context.Background(), &forces_present.ForcesPresent{Name: "Backup"})
+
+		rows, total, err := repo.List(context.Background(), "Main", "name DESC", 1, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].Name != "Main Team" {
+			t.Fatalf("unexpected list result")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openForcesPresentTestDB(t)
+		repo := NewForcesPresentRepository(db)
+		if err := db.Migrator().DropTable(&forces_present.ForcesPresent{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+
+		if _, _, err := repo.List(context.Background(), "", "", 10, 0); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openForcesPresentTestDB(t)
+		repo := NewForcesPresentRepository(db)
+		_ = repo.Create(context.Background(), &forces_present.ForcesPresent{Name: "Main"})
+
+		if _, _, err := repo.List(context.Background(), "", "name ASC, )", 10, 0); err == nil {
+			t.Fatalf("expected find error from invalid sort")
+		}
+	})
+
+	t.Run("default order active sortkey first and inactive last", func(t *testing.T) {
+		db := openForcesPresentTestDB(t)
+		repo := NewForcesPresentRepository(db)
+		_ = repo.Create(context.Background(), &forces_present.ForcesPresent{Name: "Gamma", IsActive: true})
+		_ = repo.Create(context.Background(), &forces_present.ForcesPresent{Name: "Beta", SortKey: intPtrForcesPresentRepo(0), IsActive: true})
+		_ = repo.Create(context.Background(), &forces_present.ForcesPresent{Name: "Charlie", SortKey: intPtrForcesPresentRepo(2), IsActive: true})
+		_ = repo.Create(context.Background(), &forces_present.ForcesPresent{Name: "Alpha", SortKey: intPtrForcesPresentRepo(1), IsActive: true})
+		_ = repo.Create(context.Background(), &forces_present.ForcesPresent{Name: "Zulu", IsActive: false})
+		_ = repo.Create(context.Background(), &forces_present.ForcesPresent{Name: "Bravo", SortKey: intPtrForcesPresentRepo(9), IsActive: false})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 6 || len(rows) != 6 {
+			t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+		}
+
+		gotOrder := []string{rows[0].Name, rows[1].Name, rows[2].Name, rows[3].Name, rows[4].Name, rows[5].Name}
+		wantOrder := []string{"Beta", "Alpha", "Charlie", "Gamma", "Bravo", "Zulu"}
+		for i := range wantOrder {
+			if gotOrder[i] != wantOrder[i] {
+				t.Fatalf("unexpected default order: got=%v want=%v", gotOrder, wantOrder)
+			}
+		}
+	})
+}
+
+func intPtrForcesPresentRepo(v int) *int { return &v }
diff --git a/internal/repository/mysql/health_insurance_companies_repo.go b/internal/repository/mysql/health_insurance_companies_repo.go
new file mode 100644
index 0000000..376932f
--- /dev/null
+++ b/internal/repository/mysql/health_insurance_companies_repo.go
@@ -0,0 +1,206 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/health_insurance_companies"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type HealthInsuranceCompaniesRepository struct {
+	db *gorm.DB
+}
+
+func NewHealthInsuranceCompaniesRepository(db *gorm.DB) *HealthInsuranceCompaniesRepository {
+	return &HealthInsuranceCompaniesRepository{db: db}
+}
+
+func (r *HealthInsuranceCompaniesRepository) Create(ctx context.Context, row *health_insurance_companies.HealthInsuranceCompany) error {
+	requestedIsActive := row.IsActive
+	db := r.db.WithContext(ctx)
+	if err := db.Create(row).Error; err != nil {
+		return err
+	}
+	return db.Model(&health_insurance_companies.HealthInsuranceCompany{}).Where("id = ?", row.ID).UpdateColumn("is_active", requestedIsActive).Error
+}
+
+func (r *HealthInsuranceCompaniesRepository) Update(ctx context.Context, row *health_insurance_companies.HealthInsuranceCompany) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *HealthInsuranceCompaniesRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "health_insurance_companies", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&health_insurance_companies.HealthInsuranceCompany{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error)
+}
+
+func (r *HealthInsuranceCompaniesRepository) GetByID(ctx context.Context, id []byte) (*health_insurance_companies.HealthInsuranceCompany, error) {
+	var row health_insurance_companies.HealthInsuranceCompany
+	err := r.db.WithContext(ctx).Where("id = ? AND deleted_at IS NULL", id).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *HealthInsuranceCompaniesRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]health_insurance_companies.HealthInsuranceCompany, int64, error) {
+	var rows []health_insurance_companies.HealthInsuranceCompany
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&health_insurance_companies.HealthInsuranceCompany{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("name LIKE ? OR state LIKE ? OR address LIKE ? OR mobile_number LIKE ? OR email LIKE ? OR note LIKE ?", like, like, like, like, like, like)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("health_insurance_companies", "is_active", "sortkey", "name", false) {
+			query = query.Order(clause)
+		}
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func (r *HealthInsuranceCompaniesRepository) ResolveStateDetails(ctx context.Context, stateNames []string) (map[string]health_insurance_companies.StateDetail, error) {
+	normalized := make([]string, 0, len(stateNames))
+	seen := map[string]struct{}{}
+	for _, stateName := range stateNames {
+		key := strings.ToLower(strings.TrimSpace(stateName))
+		if key == "" {
+			continue
+		}
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		normalized = append(normalized, key)
+	}
+	if len(normalized) == 0 {
+		return map[string]health_insurance_companies.StateDetail{}, nil
+	}
+
+	type row struct {
+		LandID         string `gorm:"column:land_id"`
+		FederalStateID string `gorm:"column:federal_state_id"`
+		FederalState   string `gorm:"column:federal_state"`
+		LandName       string `gorm:"column:land_name"`
+		LandISOCode    string `gorm:"column:land_iso_code"`
+		StateKey       string `gorm:"column:state_key"`
+	}
+
+	var rows []row
+	err := r.db.WithContext(ctx).
+		Table("federal_states").
+		Select("LOWER(TRIM(federal_states.name)) AS state_key, LOWER(HEX(lands.id)) AS land_id, LOWER(HEX(federal_states.id)) AS federal_state_id, federal_states.name AS federal_state, lands.name AS land_name, lands.land_iso_code AS land_iso_code").
+		Joins("JOIN lands ON lands.id = federal_states.land_id AND lands.deleted_at IS NULL").
+		Where("federal_states.deleted_at IS NULL").
+		Where("LOWER(TRIM(federal_states.name)) IN ?", normalized).
+		Scan(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+
+	out := make(map[string]health_insurance_companies.StateDetail, len(rows))
+	for i := range rows {
+		if rows[i].StateKey == "" {
+			continue
+		}
+		if _, exists := out[rows[i].StateKey]; exists {
+			continue
+		}
+		out[rows[i].StateKey] = health_insurance_companies.StateDetail{
+			LandID:         rows[i].LandID,
+			FederalStateID: rows[i].FederalStateID,
+			FederalState:   rows[i].FederalState,
+			LandName:       rows[i].LandName,
+			LandISOCode:    rows[i].LandISOCode,
+		}
+	}
+	return out, nil
+}
+
+func (r *HealthInsuranceCompaniesRepository) ResolveLandDetails(ctx context.Context, landIDs []string) (map[string]health_insurance_companies.LandDetail, error) {
+	normalized := make([]string, 0, len(landIDs))
+	seen := map[string]struct{}{}
+	for _, landID := range landIDs {
+		key := normalizeLandKey(landID)
+		if key == "" {
+			continue
+		}
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		normalized = append(normalized, key)
+	}
+	if len(normalized) == 0 {
+		return map[string]health_insurance_companies.LandDetail{}, nil
+	}
+
+	type row struct {
+		LandID      string `gorm:"column:land_id"`
+		LandName    string `gorm:"column:land_name"`
+		LandISOCode string `gorm:"column:land_iso_code"`
+	}
+
+	var rows []row
+	err := r.db.WithContext(ctx).
+		Table("lands").
+		Select("LOWER(HEX(lands.id)) AS land_id, lands.name AS land_name, lands.land_iso_code AS land_iso_code").
+		Where("lands.deleted_at IS NULL").
+		Where("LOWER(HEX(lands.id)) IN ?", normalized).
+		Scan(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+
+	out := make(map[string]health_insurance_companies.LandDetail, len(rows))
+	for i := range rows {
+		if rows[i].LandID == "" {
+			continue
+		}
+		if _, exists := out[rows[i].LandID]; exists {
+			continue
+		}
+		out[rows[i].LandID] = health_insurance_companies.LandDetail{
+			LandID:      rows[i].LandID,
+			LandName:    rows[i].LandName,
+			LandISOCode: rows[i].LandISOCode,
+		}
+	}
+	return out, nil
+}
+
+func normalizeLandKey(raw string) string {
+	key := strings.ToLower(strings.TrimSpace(raw))
+	key = strings.ReplaceAll(key, "-", "")
+	return key
+}
diff --git a/internal/repository/mysql/health_insurance_companies_repo_test.go b/internal/repository/mysql/health_insurance_companies_repo_test.go
new file mode 100644
index 0000000..80b68a9
--- /dev/null
+++ b/internal/repository/mysql/health_insurance_companies_repo_test.go
@@ -0,0 +1,238 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/health_insurance_companies"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openHealthInsuranceCompaniesTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:health_insurance_companies_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&health_insurance_companies.HealthInsuranceCompany{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestNewHealthInsuranceCompaniesRepository(t *testing.T) {
+	db := openHealthInsuranceCompaniesTestDB(t)
+	repo := NewHealthInsuranceCompaniesRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestHealthInsuranceCompaniesRepositoryCreate(t *testing.T) {
+	db := openHealthInsuranceCompaniesTestDB(t)
+	repo := NewHealthInsuranceCompaniesRepository(db)
+	row := &health_insurance_companies.HealthInsuranceCompany{Name: "Main", State: "Berlin"}
+
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(row.ID) == 0 {
+		t.Fatalf("expected id set")
+	}
+	inactive := &health_insurance_companies.HealthInsuranceCompany{Name: "Inactive", IsActive: false}
+	if err := repo.Create(context.Background(), inactive); err != nil {
+		t.Fatalf("create inactive: %v", err)
+	}
+	gotInactive, err := repo.GetByID(context.Background(), inactive.ID)
+	if err != nil {
+		t.Fatalf("get inactive: %v", err)
+	}
+	if gotInactive == nil || gotInactive.IsActive {
+		t.Fatalf("expected inactive hic persisted as false")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Create(context.Background(), &health_insurance_companies.HealthInsuranceCompany{Name: "AfterClose"}); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestHealthInsuranceCompaniesRepositoryUpdate(t *testing.T) {
+	db := openHealthInsuranceCompaniesTestDB(t)
+	repo := NewHealthInsuranceCompaniesRepository(db)
+	row := &health_insurance_companies.HealthInsuranceCompany{Name: "Old", State: "Old"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Name = "New"
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil || loaded == nil || loaded.Name != "New" {
+		t.Fatalf("expected updated row")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestHealthInsuranceCompaniesRepositoryDelete(t *testing.T) {
+	db := openHealthInsuranceCompaniesTestDB(t)
+	repo := NewHealthInsuranceCompaniesRepository(db)
+	row := &health_insurance_companies.HealthInsuranceCompany{Name: "DeleteMe"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	deletedBy := uuidv7.MustBytes()
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected soft deleted row hidden from GetByID")
+	}
+}
+
+func TestHealthInsuranceCompaniesRepositoryGetByID(t *testing.T) {
+	t.Run("found", func(t *testing.T) {
+		db := openHealthInsuranceCompaniesTestDB(t)
+		repo := NewHealthInsuranceCompaniesRepository(db)
+		row := &health_insurance_companies.HealthInsuranceCompany{Name: "Found"}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		got, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.Name != "Found" {
+			t.Fatalf("expected row found")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openHealthInsuranceCompaniesTestDB(t)
+		repo := NewHealthInsuranceCompaniesRepository(db)
+		got, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil for not found")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openHealthInsuranceCompaniesTestDB(t)
+		repo := NewHealthInsuranceCompaniesRepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, err := repo.GetByID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
+
+func TestHealthInsuranceCompaniesRepositoryList(t *testing.T) {
+	t.Run("success without limit", func(t *testing.T) {
+		db := openHealthInsuranceCompaniesTestDB(t)
+		repo := NewHealthInsuranceCompaniesRepository(db)
+		_ = repo.Create(context.Background(), &health_insurance_companies.HealthInsuranceCompany{Name: "C", State: "Gamma"})
+		_ = repo.Create(context.Background(), &health_insurance_companies.HealthInsuranceCompany{Name: "A", State: "Alpha"})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("expected 2 rows, total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("success with filter sort and limit", func(t *testing.T) {
+		db := openHealthInsuranceCompaniesTestDB(t)
+		repo := NewHealthInsuranceCompaniesRepository(db)
+		_ = repo.Create(context.Background(), &health_insurance_companies.HealthInsuranceCompany{Name: "Main Base", State: "Center"})
+		_ = repo.Create(context.Background(), &health_insurance_companies.HealthInsuranceCompany{Name: "Backup", State: "Secondary"})
+
+		rows, total, err := repo.List(context.Background(), "Main", "name DESC", 1, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].Name != "Main Base" {
+			t.Fatalf("unexpected list result")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openHealthInsuranceCompaniesTestDB(t)
+		repo := NewHealthInsuranceCompaniesRepository(db)
+		if err := db.Migrator().DropTable(&health_insurance_companies.HealthInsuranceCompany{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+
+		if _, _, err := repo.List(context.Background(), "", "", 10, 0); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openHealthInsuranceCompaniesTestDB(t)
+		repo := NewHealthInsuranceCompaniesRepository(db)
+		_ = repo.Create(context.Background(), &health_insurance_companies.HealthInsuranceCompany{Name: "Main"})
+
+		if _, _, err := repo.List(context.Background(), "", "name ASC, )", 10, 0); err == nil {
+			t.Fatalf("expected find error from invalid sort")
+		}
+	})
+
+	t.Run("default order active sortkey first and inactive last", func(t *testing.T) {
+		db := openHealthInsuranceCompaniesTestDB(t)
+		repo := NewHealthInsuranceCompaniesRepository(db)
+		_ = repo.Create(context.Background(), &health_insurance_companies.HealthInsuranceCompany{Name: "Gamma", IsActive: true})
+		_ = repo.Create(context.Background(), &health_insurance_companies.HealthInsuranceCompany{Name: "Beta", SortKey: intPtrHICRepo(0), IsActive: true})
+		_ = repo.Create(context.Background(), &health_insurance_companies.HealthInsuranceCompany{Name: "Charlie", SortKey: intPtrHICRepo(2), IsActive: true})
+		_ = repo.Create(context.Background(), &health_insurance_companies.HealthInsuranceCompany{Name: "Alpha", SortKey: intPtrHICRepo(1), IsActive: true})
+		_ = repo.Create(context.Background(), &health_insurance_companies.HealthInsuranceCompany{Name: "Zulu", IsActive: false})
+		_ = repo.Create(context.Background(), &health_insurance_companies.HealthInsuranceCompany{Name: "Bravo", SortKey: intPtrHICRepo(9), IsActive: false})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 6 || len(rows) != 6 {
+			t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+		}
+
+		gotOrder := []string{rows[0].Name, rows[1].Name, rows[2].Name, rows[3].Name, rows[4].Name, rows[5].Name}
+		wantOrder := []string{"Beta", "Alpha", "Charlie", "Gamma", "Bravo", "Zulu"}
+		for i := range wantOrder {
+			if gotOrder[i] != wantOrder[i] {
+				t.Fatalf("unexpected default order: got=%v want=%v", gotOrder, wantOrder)
+			}
+		}
+	})
+}
+
+func intPtrHICRepo(v int) *int { return &v }
diff --git a/internal/repository/mysql/helicopter_file_repo.go b/internal/repository/mysql/helicopter_file_repo.go
new file mode 100644
index 0000000..de5954e
--- /dev/null
+++ b/internal/repository/mysql/helicopter_file_repo.go
@@ -0,0 +1,176 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/helicopter"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+)
+
+type HelicopterFileRepository struct {
+	db *gorm.DB
+}
+
+func NewHelicopterFileRepository(db *gorm.DB) *HelicopterFileRepository {
+	return &HelicopterFileRepository{db: db}
+}
+
+func (r *HelicopterFileRepository) Create(ctx context.Context, row *helicopterfile.HelicopterFile) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *HelicopterFileRepository) Update(ctx context.Context, row *helicopterfile.HelicopterFile) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *HelicopterFileRepository) Delete(ctx context.Context, id []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "helicopter_files", id); err != nil {
+		return err
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).Delete(&helicopterfile.HelicopterFile{}, "id = ?", id).Error)
+}
+
+func (r *HelicopterFileRepository) GetByID(ctx context.Context, id []byte) (*helicopterfile.HelicopterFile, error) {
+	var row helicopterfile.HelicopterFile
+	err := r.db.WithContext(ctx).
+		Preload("Helicopter").
+		Preload("FileAttachment").
+		Preload("FileAttachment.File").
+		Preload("SourceFile").
+		Where("id = ?", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *HelicopterFileRepository) List(ctx context.Context, filter string, sort string, limit, offset int) ([]helicopterfile.HelicopterFile, int64, error) {
+	rows := make([]helicopterfile.HelicopterFile, 0)
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&helicopterfile.HelicopterFile{})
+	if strings.TrimSpace(filter) != "" {
+		like := "%" + strings.ToLower(strings.TrimSpace(filter)) + "%"
+		base = base.Where(
+			"LOWER(section) LIKE ? OR LOWER(HEX(id)) LIKE ? OR LOWER(HEX(helicopter_id)) LIKE ? OR LOWER(HEX(file_attachment_id)) LIKE ? OR LOWER(HEX(source_file_id)) LIKE ? OR CAST(is_mandatory AS CHAR) LIKE ?",
+			like, like, like, like, like, like,
+		)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.
+		Preload("Helicopter").
+		Preload("FileAttachment").
+		Preload("FileAttachment.File").
+		Preload("SourceFile").
+		Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func (r *HelicopterFileRepository) ListPendingAttachments(ctx context.Context, limit int) ([]helicopterfile.HelicopterFile, error) {
+	rows := make([]helicopterfile.HelicopterFile, 0)
+	query := r.db.WithContext(ctx).
+		Preload("Helicopter").
+		Preload("SourceFile").
+		Where("source_file_id IS NOT NULL AND file_attachment_id IS NULL").
+		Order("created_at ASC")
+	if limit > 0 {
+		query = query.Limit(limit)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *HelicopterFileRepository) ListPendingAttachmentsBySourceFileID(ctx context.Context, sourceFileID []byte, limit int) ([]helicopterfile.HelicopterFile, error) {
+	rows := make([]helicopterfile.HelicopterFile, 0)
+	if len(sourceFileID) != 16 {
+		return rows, nil
+	}
+	query := r.db.WithContext(ctx).
+		Preload("Helicopter").
+		Preload("SourceFile").
+		Where("source_file_id = ? AND file_attachment_id IS NULL", sourceFileID).
+		Order("created_at ASC")
+	if limit > 0 {
+		query = query.Limit(limit)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *HelicopterFileRepository) ListByHelicopter(ctx context.Context, helicopterID []byte) ([]helicopterfile.HelicopterFile, error) {
+	rows := make([]helicopterfile.HelicopterFile, 0)
+	if len(helicopterID) != 16 {
+		return rows, nil
+	}
+	err := r.db.WithContext(ctx).
+		Preload("Helicopter").
+		Preload("FileAttachment").
+		Preload("FileAttachment.File").
+		Preload("SourceFile").
+		Where("helicopter_id = ?", helicopterID).
+		Order("section ASC, position ASC, created_at ASC").
+		Find(&rows).Error
+	return rows, err
+}
+
+func (r *HelicopterFileRepository) ListByHelicopterAndSection(ctx context.Context, helicopterID []byte, section string) ([]helicopterfile.HelicopterFile, error) {
+	rows := make([]helicopterfile.HelicopterFile, 0)
+	if len(helicopterID) != 16 || strings.TrimSpace(section) == "" {
+		return rows, nil
+	}
+	err := r.db.WithContext(ctx).
+		Preload("Helicopter").
+		Preload("FileAttachment").
+		Preload("FileAttachment.File").
+		Preload("SourceFile").
+		Where("helicopter_id = ? AND section = ?", helicopterID, strings.TrimSpace(section)).
+		Order("position ASC, created_at ASC").
+		Find(&rows).Error
+	return rows, err
+}
+
+func (r *HelicopterFileRepository) HelicopterExists(ctx context.Context, helicopterID []byte) (bool, error) {
+	if len(helicopterID) != 16 {
+		return false, nil
+	}
+	var total int64
+	err := r.db.WithContext(ctx).
+		Model(&helicopter.Helicopter{}).
+		Where("id = ?", helicopterID).
+		Count(&total).Error
+	return total > 0, err
+}
+
+func (r *HelicopterFileRepository) AttachmentExists(ctx context.Context, attachmentID []byte) (bool, error) {
+	if len(attachmentID) != 16 {
+		return false, nil
+	}
+	var total int64
+	err := r.db.WithContext(ctx).
+		Model(&filemanager.Attachment{}).
+		Where("id = ?", attachmentID).
+		Count(&total).Error
+	return total > 0, err
+}
diff --git a/internal/repository/mysql/helicopter_repo.go b/internal/repository/mysql/helicopter_repo.go
new file mode 100644
index 0000000..8e28675
--- /dev/null
+++ b/internal/repository/mysql/helicopter_repo.go
@@ -0,0 +1,373 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"wucher/internal/domain/helicopter"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type HelicopterRepository struct {
+	db            *gorm.DB
+	hasUsersTable bool
+}
+
+func NewHelicopterRepository(db *gorm.DB) *HelicopterRepository {
+	schema := newSchemaCache(db)
+	return &HelicopterRepository{
+		db:            db,
+		hasUsersTable: schema.HasTable("users"),
+	}
+}
+
+func (r *HelicopterRepository) Create(ctx context.Context, h *helicopter.Helicopter) error {
+	requestedIsActive := h.IsActive
+	db := r.db.WithContext(ctx)
+	if err := db.Create(h).Error; err != nil {
+		return err
+	}
+	return db.Model(&helicopter.Helicopter{}).Where("id = ?", h.ID).UpdateColumn("is_active", requestedIsActive).Error
+}
+
+func (r *HelicopterRepository) CreateWithDB(ctx context.Context, db *gorm.DB, h *helicopter.Helicopter) error {
+	requestedIsActive := h.IsActive
+	if err := db.WithContext(ctx).Create(h).Error; err != nil {
+		return err
+	}
+	return db.WithContext(ctx).Model(&helicopter.Helicopter{}).Where("id = ?", h.ID).UpdateColumn("is_active", requestedIsActive).Error
+}
+
+func (r *HelicopterRepository) Transaction(ctx context.Context, fn func(tx *gorm.DB) error) error {
+	return r.db.WithContext(ctx).Transaction(fn)
+}
+
+func (r *HelicopterRepository) Update(ctx context.Context, h *helicopter.Helicopter) error {
+	// Persist only helicopter columns; avoid association auto-save side effects
+	// when handler payload carries preloaded FotoAttachment relation.
+	return r.db.WithContext(ctx).Omit(clause.Associations).Save(h).Error
+}
+
+func (r *HelicopterRepository) ExistsByIdentifier(ctx context.Context, identifier string, excludeID []byte) (bool, error) {
+	db := r.db.WithContext(ctx).Model(&helicopter.Helicopter{}).
+		Where("UPPER(TRIM(identifier)) = ?", strings.ToUpper(strings.TrimSpace(identifier)))
+	if len(excludeID) == 16 {
+		db = db.Where("id <> ?", excludeID)
+	}
+	var total int64
+	if err := db.Count(&total).Error; err != nil {
+		return false, err
+	}
+	return total > 0, nil
+}
+
+func (r *HelicopterRepository) Delete(ctx context.Context, id []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "helicopters", id); err != nil {
+		return err
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).Delete(&helicopter.Helicopter{}, "id = ?", id).Error)
+}
+
+func (r *HelicopterRepository) GetByID(ctx context.Context, id []byte) (*helicopter.Helicopter, error) {
+	var h helicopter.Helicopter
+	err := r.withAuditUsers(r.db.WithContext(ctx)).
+		Preload("FotoAttachment").
+		Preload("FotoAttachment.File").
+		Where("helicopters.id = ?", id).
+		First(&h).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &h, err
+}
+
+func (r *HelicopterRepository) List(ctx context.Context, filter string, statuses []string, sort string, limit, offset int, groundedIDs [][]byte) ([]helicopter.Helicopter, int64, error) {
+	var helicopters []helicopter.Helicopter
+	var total int64
+
+	base := r.withAuditUsers(r.db.WithContext(ctx))
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("helicopters.designation LIKE ? OR helicopters.identifier LIKE ? OR helicopters.type LIKE ?", like, like, like)
+	}
+	base = r.applyStatusFilter(base, statuses, groundedIDs)
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("helicopters", "is_active", "sortkey", "designation", false) {
+			query = query.Order(clause)
+		}
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	query = query.Preload("FotoAttachment").Preload("FotoAttachment.File")
+	if err := query.Find(&helicopters).Error; err != nil {
+		return nil, 0, err
+	}
+	return helicopters, total, nil
+}
+
+// applyStatusFilter restricts query to helicopters whose derived operational
+// status is in statuses. The conditions mirror helicopter.DeriveStatus: AOG
+// (air_on_ground) outranks an active flight assignment ("booked"), and
+// "available" means neither; "mcf" has no data source yet, so it matches
+// nothing. Multiple statuses are OR-ed together. Returns query unchanged when
+// no status filter applies.
+func (r *HelicopterRepository) applyStatusFilter(query *gorm.DB, statuses []string, groundedIDs [][]byte) *gorm.DB {
+	if len(statuses) == 0 {
+		return query
+	}
+
+	// inUse mirrors IsInUse: the helicopter has a non-deleted flight assignment
+	// reachable through takeover_acs.reserve_ac_id. A fresh subquery is built
+	// per use to avoid sharing builder state.
+	inUse := func() *gorm.DB {
+		return r.db.
+			Table("reserve_acs ra").
+			Select("1").
+			Joins("JOIN takeover_acs ta ON ta.reserve_ac_id = ra.id AND ta.deleted_at IS NULL").
+			Joins("JOIN flights f ON f.takeover_ac_id = ta.id").
+			Joins("LEFT JOIN after_flight_inspections afi ON afi.flight_inspection_id = ra.inspection_id").
+			Where("ra.helicopter_id = helicopters.id").
+			Where("ra.deleted_at IS NULL AND f.deleted_at IS NULL AND afi.id IS NULL")
+	}
+
+	// A helicopter is AOG when its persisted air_on_ground flag is set OR it is
+	// grounded by an open complaint (computed in Go from IsGrounding and passed in via
+	// groundedIDs, since the read-time grounding is not persisted in air_on_ground).
+	hasGrounded := len(groundedIDs) > 0
+
+	group := r.db.Session(&gorm.Session{NewDB: true})
+	seen := make(map[string]struct{}, len(statuses))
+	for _, status := range statuses {
+		if _, ok := seen[status]; ok {
+			continue
+		}
+		seen[status] = struct{}{}
+		switch status {
+		case helicopter.StatusAOG:
+			aog := r.db.Where("helicopters.air_on_ground = ?", true)
+			if hasGrounded {
+				aog = aog.Or("helicopters.id IN ?", groundedIDs)
+			}
+			group = group.Or(aog)
+		case helicopter.StatusBooked:
+			booked := r.db.Where("helicopters.air_on_ground = ?", false).Where("EXISTS (?)", inUse())
+			if hasGrounded {
+				booked = booked.Where("helicopters.id NOT IN ?", groundedIDs)
+			}
+			group = group.Or(booked)
+		case helicopter.StatusAvailable:
+			avail := r.db.Where("helicopters.air_on_ground = ?", false).Where("NOT EXISTS (?)", inUse())
+			if hasGrounded {
+				avail = avail.Where("helicopters.id NOT IN ?", groundedIDs)
+			}
+			group = group.Or(avail)
+		case helicopter.StatusMCF:
+			group = group.Or("1 = 0") // no data source yet
+		}
+	}
+	return query.Where(group)
+}
+
+func (r *HelicopterRepository) NextReportNumber(ctx context.Context, id []byte) (string, int, error) {
+	var reportNumber string
+	var sequence int
+
+	err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var h helicopter.Helicopter
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Where("id = ?", id).First(&h).Error; err != nil {
+			return err
+		}
+
+		identifier := strings.TrimSpace(h.Identifier)
+		if identifier == "" {
+			return errors.New("helicopter identifier is empty")
+		}
+		if base, _, ok := splitIdentifierBase(identifier); ok {
+			identifier = base
+		}
+
+		next := h.ReportSequence + 1
+		if err := tx.Model(&helicopter.Helicopter{}).Where("id = ?", h.ID).Update("report_sequence", next).Error; err != nil {
+			return err
+		}
+
+		sequence = next
+		reportNumber = fmt.Sprintf("%s-%04d", identifier, next)
+		return nil
+	})
+	if err != nil {
+		return "", 0, err
+	}
+
+	return reportNumber, sequence, nil
+}
+
+func (r *HelicopterRepository) IsInUse(ctx context.Context, id []byte) (bool, error) {
+	if len(id) != 16 {
+		return false, nil
+	}
+	var total int64
+	err := r.db.WithContext(ctx).
+		Table("reserve_acs ra").
+		Joins("JOIN takeover_acs ta ON ta.reserve_ac_id = ra.id AND ta.deleted_at IS NULL").
+		Joins("JOIN flights f ON f.takeover_ac_id = ta.id").
+		Joins("LEFT JOIN after_flight_inspections afi ON afi.flight_inspection_id = ra.inspection_id").
+		Where("ra.helicopter_id = ? AND ra.deleted_at IS NULL AND f.deleted_at IS NULL AND afi.id IS NULL", id).
+		Count(&total).Error
+	return total > 0, err
+}
+
+func (r *HelicopterRepository) InUseByAircraftIDs(ctx context.Context, ids [][]byte) (map[string]bool, error) {
+	out := make(map[string]bool)
+	if len(ids) == 0 {
+		return out, nil
+	}
+
+	filtered := make([][]byte, 0, len(ids))
+	seen := make(map[string]struct{}, len(ids))
+	for _, id := range ids {
+		if len(id) != 16 {
+			continue
+		}
+		key := string(id)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		filtered = append(filtered, append([]byte(nil), id...))
+	}
+	if len(filtered) == 0 {
+		return out, nil
+	}
+
+	type row struct {
+		HelicopterID []byte `gorm:"column:helicopter_id"`
+	}
+	rows := make([]row, 0)
+	if err := r.db.WithContext(ctx).
+		Table("reserve_acs ra").
+		Select("DISTINCT ra.helicopter_id").
+		Joins("JOIN takeover_acs ta ON ta.reserve_ac_id = ra.id AND ta.deleted_at IS NULL").
+		Joins("JOIN flights f ON f.takeover_ac_id = ta.id").
+		Joins("LEFT JOIN after_flight_inspections afi ON afi.flight_inspection_id = ra.inspection_id").
+		Where("ra.deleted_at IS NULL AND f.deleted_at IS NULL AND afi.id IS NULL").
+		Where("ra.helicopter_id IN ?", filtered).
+		Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+
+	for i := range rows {
+		out[string(rows[i].HelicopterID)] = true
+	}
+	return out, nil
+}
+
+// ActiveFlightIDByAircraftIDs returns, per helicopter, the id of its current active flight
+// (a takeover flight with no after-flight inspection yet). Mirrors the InUseByAircraftIDs
+// join so "in use" and "which flight" stay consistent. Only in-use helicopters appear in
+// the map; the newest flight wins if several are open. Used by the fleet status page to
+// create an EASA release scoped to the flight.
+func (r *HelicopterRepository) ActiveFlightIDByAircraftIDs(ctx context.Context, ids [][]byte) (map[string][]byte, error) {
+	out := make(map[string][]byte)
+	if len(ids) == 0 {
+		return out, nil
+	}
+	filtered := make([][]byte, 0, len(ids))
+	seen := make(map[string]struct{}, len(ids))
+	for _, id := range ids {
+		if len(id) != 16 {
+			continue
+		}
+		key := string(id)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		filtered = append(filtered, append([]byte(nil), id...))
+	}
+	if len(filtered) == 0 {
+		return out, nil
+	}
+
+	type row struct {
+		HelicopterID []byte `gorm:"column:helicopter_id"`
+		FlightID     []byte `gorm:"column:flight_id"`
+	}
+	rows := make([]row, 0)
+	if err := r.db.WithContext(ctx).
+		Table("reserve_acs ra").
+		Select("ra.helicopter_id AS helicopter_id, f.id AS flight_id").
+		Joins("JOIN takeover_acs ta ON ta.reserve_ac_id = ra.id AND ta.deleted_at IS NULL").
+		Joins("JOIN flights f ON f.takeover_ac_id = ta.id").
+		Joins("LEFT JOIN after_flight_inspections afi ON afi.flight_inspection_id = ra.inspection_id").
+		Where("ra.deleted_at IS NULL AND f.deleted_at IS NULL AND afi.id IS NULL").
+		Where("ra.helicopter_id IN ?", filtered).
+		Order("f.created_at DESC").
+		Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+
+	for i := range rows {
+		k := string(rows[i].HelicopterID)
+		if _, ok := out[k]; !ok && len(rows[i].FlightID) == 16 {
+			out[k] = rows[i].FlightID
+		}
+	}
+	return out, nil
+}
+
+func splitIdentifierBase(raw string) (string, int, bool) {
+	s := strings.TrimSpace(raw)
+	idx := strings.LastIndex(s, "-")
+	if idx <= 0 || idx+5 != len(s) {
+		return "", 0, false
+	}
+	base := strings.TrimSpace(s[:idx])
+	if base == "" {
+		return "", 0, false
+	}
+	seq, err := strconv.Atoi(s[idx+1:])
+	if err != nil || seq <= 0 {
+		return "", 0, false
+	}
+	return base, seq, true
+}
+
+func (r *HelicopterRepository) withAuditUsers(db *gorm.DB) *gorm.DB {
+	base := db.Model(&helicopter.Helicopter{})
+	if !r.hasUsersTable {
+		return base.Select("helicopters.*, '' AS created_by_name, '' AS updated_by_name")
+	}
+	return base.
+		Select(`
+				helicopters.*,
+				COALESCE(
+					NULLIF(TRIM(CONCAT(COALESCE(cu.first_name, ''), ' ', COALESCE(cu.last_name, ''))), ''),
+					NULLIF(TRIM(cu.username), ''),
+					NULLIF(TRIM(cu.email), ''),
+					''
+				) AS created_by_name,
+				COALESCE(
+					NULLIF(TRIM(CONCAT(COALESCE(uu.first_name, ''), ' ', COALESCE(uu.last_name, ''))), ''),
+					NULLIF(TRIM(uu.username), ''),
+					NULLIF(TRIM(uu.email), ''),
+					''
+				) AS updated_by_name
+			`).
+		Joins("LEFT JOIN users cu ON cu.id = helicopters.created_by").
+		Joins("LEFT JOIN users uu ON uu.id = helicopters.updated_by")
+}
diff --git a/internal/repository/mysql/helicopter_repo_test.go b/internal/repository/mysql/helicopter_repo_test.go
new file mode 100644
index 0000000..5ae5d89
--- /dev/null
+++ b/internal/repository/mysql/helicopter_repo_test.go
@@ -0,0 +1,587 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/helicopter"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func intPtr(v int) *int {
+	return &v
+}
+
+func openHelicopterTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:helicopter_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&filemanager.Folder{}, &filemanager.File{}, &filemanager.Attachment{}, &helicopter.Helicopter{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestNewHelicopterRepository(t *testing.T) {
+	db := openHelicopterTestDB(t)
+	repo := NewHelicopterRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+	if repo.hasUsersTable {
+		t.Fatalf("expected users table cache to be false in base helicopter test db")
+	}
+}
+
+func TestHelicopterRepositoryCachesUsersTablePresence(t *testing.T) {
+	db := openHelicopterTestDB(t)
+	if err := db.Exec(`CREATE TABLE users (
+		id BLOB PRIMARY KEY,
+		first_name TEXT,
+		last_name TEXT,
+		username TEXT,
+		email TEXT
+	)`).Error; err != nil {
+		t.Fatalf("create users table: %v", err)
+	}
+
+	repo := NewHelicopterRepository(db)
+	if !repo.hasUsersTable {
+		t.Fatalf("expected users table cache to be true")
+	}
+
+	creatorID := uuidv7.MustBytes()
+	updaterID := uuidv7.MustBytes()
+	if err := db.Table("users").Create([]map[string]any{
+		{
+			"id":         creatorID,
+			"first_name": "Ada",
+			"last_name":  "Lovelace",
+			"username":   "ada",
+			"email":      "ada@example.com",
+		},
+		{
+			"id":         updaterID,
+			"first_name": "Grace",
+			"last_name":  "Hopper",
+			"username":   "grace",
+			"email":      "grace@example.com",
+		},
+	}).Error; err != nil {
+		t.Fatalf("seed users: %v", err)
+	}
+
+	row := &helicopter.Helicopter{
+		Designation: "H145",
+		Identifier:  "PK-AUDIT",
+		Type:        "Twin",
+		CreatedBy:   creatorID,
+		UpdatedBy:   updaterID,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed helicopter: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get helicopter: %v", err)
+	}
+	if got == nil {
+		t.Fatalf("expected helicopter row")
+	}
+	if got.CreatedByName != "Ada Lovelace" {
+		t.Fatalf("unexpected created_by_name: %q", got.CreatedByName)
+	}
+	if got.UpdatedByName != "Grace Hopper" {
+		t.Fatalf("unexpected updated_by_name: %q", got.UpdatedByName)
+	}
+}
+
+func TestHelicopterRepositoryCreate(t *testing.T) {
+	db := openHelicopterTestDB(t)
+	repo := NewHelicopterRepository(db)
+	row := &helicopter.Helicopter{Designation: "H145", Identifier: "PK-ABC", Type: "Twin"}
+
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(row.ID) == 0 {
+		t.Fatalf("expected id set")
+	}
+	inactive := &helicopter.Helicopter{Designation: "Inactive", Identifier: "PK-INACTIVE", Type: "Single", IsActive: false}
+	if err := repo.Create(context.Background(), inactive); err != nil {
+		t.Fatalf("create inactive: %v", err)
+	}
+	gotInactive, err := repo.GetByID(context.Background(), inactive.ID)
+	if err != nil {
+		t.Fatalf("get inactive: %v", err)
+	}
+	if gotInactive == nil || gotInactive.IsActive {
+		t.Fatalf("expected inactive helicopter persisted as false")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Create(context.Background(), &helicopter.Helicopter{Designation: "AfterClose", Identifier: "PK-CLOSE", Type: "Twin"}); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestHelicopterRepositoryUpdate(t *testing.T) {
+	db := openHelicopterTestDB(t)
+	repo := NewHelicopterRepository(db)
+	row := &helicopter.Helicopter{Designation: "Old", Identifier: "PK-OLD", Type: "Single"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Designation = "New"
+	row.Type = "Twin"
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil || loaded == nil || loaded.Designation != "New" || loaded.Type != "Twin" {
+		t.Fatalf("expected updated row")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestHelicopterRepositoryUpdate_ReplacesFotoAttachmentID(t *testing.T) {
+	db := openHelicopterTestDB(t)
+	repo := NewHelicopterRepository(db)
+	now := time.Now().UTC()
+
+	folder := &filemanager.Folder{
+		ID:             uuidv7.MustBytes(),
+		Name:           "photos",
+		NameNormalized: "photos",
+		Depth:          0,
+		PathCache:      "/photos",
+		NameSlot:       "live",
+		CreatedAt:      now,
+		UpdatedAt:      now,
+	}
+	if err := db.Create(folder).Error; err != nil {
+		t.Fatalf("create folder: %v", err)
+	}
+
+	makeFile := func(name, key string) *filemanager.File {
+		return &filemanager.File{
+			ID:             uuidv7.MustBytes(),
+			FolderID:       folder.ID,
+			Name:           name,
+			NameNormalized: strings.ToLower(name),
+			Extension:      "webp",
+			SizeBytes:      1234,
+			MimeType:       "image/webp",
+			Bucket:         "bucket",
+			ObjectKey:      key,
+			Status:         filemanager.FileStatusReady,
+			NameSlot:       "live",
+			CreatedAt:      now,
+			UpdatedAt:      now,
+		}
+	}
+	oldFile := makeFile("old.webp", "objects/old.webp")
+	newFile := makeFile("new.webp", "objects/new.webp")
+	if err := db.Create(oldFile).Error; err != nil {
+		t.Fatalf("create old file: %v", err)
+	}
+	if err := db.Create(newFile).Error; err != nil {
+		t.Fatalf("create new file: %v", err)
+	}
+
+	oldAttachment := &filemanager.Attachment{
+		ID:        uuidv7.MustBytes(),
+		FileID:    oldFile.ID,
+		RefType:   "helicopter_photo",
+		RefID:     "helicopter-1",
+		IsPrimary: true,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	newAttachment := &filemanager.Attachment{
+		ID:        uuidv7.MustBytes(),
+		FileID:    newFile.ID,
+		RefType:   "helicopter_photo",
+		RefID:     "helicopter-1",
+		IsPrimary: true,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	if err := db.Create(oldAttachment).Error; err != nil {
+		t.Fatalf("create old attachment: %v", err)
+	}
+	if err := db.Create(newAttachment).Error; err != nil {
+		t.Fatalf("create new attachment: %v", err)
+	}
+
+	row := &helicopter.Helicopter{
+		ID:               uuidv7.MustBytes(),
+		Designation:      "Old",
+		Identifier:       "PK-OLD-ATT",
+		Type:             "Single",
+		FotoAttachmentID: oldAttachment.ID,
+		FotoAttachment:   oldAttachment,
+		CreatedAt:        now,
+		UpdatedAt:        now,
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create helicopter: %v", err)
+	}
+
+	row.FotoAttachmentID = newAttachment.ID
+	row.FotoAttachment = oldAttachment
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("update helicopter: %v", err)
+	}
+
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after update: %v", err)
+	}
+	if loaded == nil {
+		t.Fatalf("expected updated row")
+	}
+	if string(loaded.FotoAttachmentID) != string(newAttachment.ID) {
+		t.Fatalf("expected foto_attachment_id replaced")
+	}
+}
+
+func TestHelicopterRepositoryDelete(t *testing.T) {
+	db := openHelicopterTestDB(t)
+	repo := NewHelicopterRepository(db)
+	row := &helicopter.Helicopter{Designation: "DeleteMe", Identifier: "PK-DEL", Type: "Twin"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	if err := repo.Delete(context.Background(), row.ID); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected row deleted")
+	}
+}
+
+func TestHelicopterRepositoryGetByID(t *testing.T) {
+	t.Run("found", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+		row := &helicopter.Helicopter{Designation: "Found", Identifier: "PK-FND", Type: "Twin"}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		got, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.Identifier != "PK-FND" {
+			t.Fatalf("expected row found")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+		got, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil for not found")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, err := repo.GetByID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
+
+func TestHelicopterRepositoryList(t *testing.T) {
+	t.Run("success without limit", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+		_ = repo.Create(context.Background(), &helicopter.Helicopter{Designation: "H145", Identifier: "PK-A", Type: "Twin"})
+		_ = repo.Create(context.Background(), &helicopter.Helicopter{Designation: "H125", Identifier: "PK-B", Type: "Single"})
+
+		rows, total, err := repo.List(context.Background(), "", nil, "", 0, 0, nil)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("expected 2 rows, total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("success with filter sort and limit", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+		_ = repo.Create(context.Background(), &helicopter.Helicopter{Designation: "Main", Identifier: "PK-MAIN", Type: "Twin"})
+		_ = repo.Create(context.Background(), &helicopter.Helicopter{Designation: "Backup", Identifier: "PK-BACK", Type: "Single"})
+
+		rows, total, err := repo.List(context.Background(), "MAIN", nil, "identifier DESC", 1, 0, nil)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].Identifier != "PK-MAIN" {
+			t.Fatalf("unexpected list result")
+		}
+	})
+
+	t.Run("default order active sortkey first and inactive last", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+		_ = repo.Create(context.Background(), &helicopter.Helicopter{Designation: "Gamma", Identifier: "PK-G", Type: "Twin", IsActive: true})
+		_ = repo.Create(context.Background(), &helicopter.Helicopter{Designation: "Beta", Identifier: "PK-B0", Type: "Twin", SortKey: intPtr(0), IsActive: true})
+		_ = repo.Create(context.Background(), &helicopter.Helicopter{Designation: "Charlie", Identifier: "PK-C", Type: "Twin", SortKey: intPtr(2), IsActive: true})
+		_ = repo.Create(context.Background(), &helicopter.Helicopter{Designation: "Alpha", Identifier: "PK-A1", Type: "Twin", IsActive: true})
+		_ = repo.Create(context.Background(), &helicopter.Helicopter{Designation: "Alpha", Identifier: "PK-A2", Type: "Twin", SortKey: intPtr(1), IsActive: true})
+		_ = repo.Create(context.Background(), &helicopter.Helicopter{Designation: "Zulu", Identifier: "PK-Z", Type: "Twin", IsActive: false})
+		_ = repo.Create(context.Background(), &helicopter.Helicopter{Designation: "Bravo", Identifier: "PK-B", Type: "Twin", IsActive: false, SortKey: intPtr(9)})
+
+		rows, total, err := repo.List(context.Background(), "", nil, "", 0, 0, nil)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 7 || len(rows) != 7 {
+			t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+		}
+
+		gotOrder := []string{
+			rows[0].Designation + "|" + rows[0].Identifier,
+			rows[1].Designation + "|" + rows[1].Identifier,
+			rows[2].Designation + "|" + rows[2].Identifier,
+			rows[3].Designation + "|" + rows[3].Identifier,
+			rows[4].Designation + "|" + rows[4].Identifier,
+			rows[5].Designation + "|" + rows[5].Identifier,
+			rows[6].Designation + "|" + rows[6].Identifier,
+		}
+		wantOrder := []string{
+			"Beta|PK-B0",
+			"Alpha|PK-A2",
+			"Charlie|PK-C",
+			"Alpha|PK-A1",
+			"Gamma|PK-G",
+			"Bravo|PK-B",
+			"Zulu|PK-Z",
+		}
+		for i := range wantOrder {
+			if gotOrder[i] != wantOrder[i] {
+				t.Fatalf("unexpected default order: got=%v want=%v", gotOrder, wantOrder)
+			}
+		}
+	})
+
+	t.Run("status filter", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+
+		// Minimal schema for the booked/available EXISTS subquery.
+		if err := db.Exec(`CREATE TABLE reserve_acs (id BLOB PRIMARY KEY, helicopter_id BLOB, inspection_id BLOB, deleted_at DATETIME)`).Error; err != nil {
+			t.Fatalf("create reserve_acs: %v", err)
+		}
+		if err := db.Exec(`CREATE TABLE takeover_acs (id BLOB PRIMARY KEY, reserve_ac_id BLOB, deleted_at DATETIME)`).Error; err != nil {
+			t.Fatalf("create takeover_acs: %v", err)
+		}
+		if err := db.Exec(`CREATE TABLE flights (id BLOB PRIMARY KEY, reserve_ac_id BLOB, takeover_ac_id BLOB, deleted_at DATETIME)`).Error; err != nil {
+			t.Fatalf("create flights: %v", err)
+		}
+		if err := db.AutoMigrate(&afterflightinspection.AfterFlightInspection{}); err != nil {
+			t.Fatalf("auto migrate after flight inspection: %v", err)
+		}
+
+		aog := &helicopter.Helicopter{Designation: "AOG", Identifier: "PK-AOG", Type: "Twin", AirOnGround: true}
+		booked := &helicopter.Helicopter{Designation: "Booked", Identifier: "PK-BKD", Type: "Twin"}
+		closed := &helicopter.Helicopter{Designation: "Closed", Identifier: "PK-CLS", Type: "Twin"}
+		available := &helicopter.Helicopter{Designation: "Avail", Identifier: "PK-AVL", Type: "Twin"}
+		for _, h := range []*helicopter.Helicopter{aog, booked, closed, available} {
+			if err := repo.Create(context.Background(), h); err != nil {
+				t.Fatalf("create helicopter: %v", err)
+			}
+		}
+
+		// Give "booked" an active (non-deleted) flight assignment.
+		raID := uuidv7.MustBytes()
+		takeoverID := uuidv7.MustBytes()
+		if err := db.Table("reserve_acs").Create(map[string]any{"id": raID, "helicopter_id": booked.ID}).Error; err != nil {
+			t.Fatalf("insert reserve_ac: %v", err)
+		}
+		if err := db.Table("takeover_acs").Create(map[string]any{"id": takeoverID, "reserve_ac_id": raID}).Error; err != nil {
+			t.Fatalf("insert takeover_ac: %v", err)
+		}
+		if err := db.Table("flights").Create(map[string]any{"id": uuidv7.MustBytes(), "takeover_ac_id": takeoverID}).Error; err != nil {
+			t.Fatalf("insert flight: %v", err)
+		}
+		closedRAID := uuidv7.MustBytes()
+		closedTakeoverID := uuidv7.MustBytes()
+		closedInspectionID := uuidv7.MustBytes()
+		if err := db.Table("reserve_acs").Create(map[string]any{"id": closedRAID, "helicopter_id": closed.ID, "inspection_id": closedInspectionID}).Error; err != nil {
+			t.Fatalf("insert closed reserve_ac: %v", err)
+		}
+		if err := db.Table("takeover_acs").Create(map[string]any{"id": closedTakeoverID, "reserve_ac_id": closedRAID}).Error; err != nil {
+			t.Fatalf("insert closed takeover_ac: %v", err)
+		}
+		if err := db.Table("flights").Create(map[string]any{"id": uuidv7.MustBytes(), "takeover_ac_id": closedTakeoverID}).Error; err != nil {
+			t.Fatalf("insert closed flight: %v", err)
+		}
+		if err := db.Create(&afterflightinspection.AfterFlightInspection{FlightInspectionID: closedInspectionID, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}).Error; err != nil {
+			t.Fatalf("insert after flight inspection: %v", err)
+		}
+
+		cases := []struct {
+			name        string
+			statuses    []string
+			groundedIDs [][]byte
+			want        []string
+		}{
+			{name: "aog only", statuses: []string{"aog"}, want: []string{"PK-AOG"}},
+			{name: "booked only", statuses: []string{"booked"}, want: []string{"PK-BKD"}},
+			{name: "available only", statuses: []string{"available"}, want: []string{"PK-AVL", "PK-CLS"}},
+			{name: "available and booked", statuses: []string{"available", "booked"}, want: []string{"PK-AVL", "PK-BKD", "PK-CLS"}},
+			{name: "mcf matches nothing", statuses: []string{"mcf"}, want: []string{}},
+			{name: "no filter returns all", statuses: nil, want: []string{"PK-AOG", "PK-AVL", "PK-BKD", "PK-CLS"}},
+			{name: "complaint-grounded excluded from available", statuses: []string{"available"}, groundedIDs: [][]byte{available.ID}, want: []string{"PK-CLS"}},
+			{name: "complaint-grounded appears as aog", statuses: []string{"aog"}, groundedIDs: [][]byte{available.ID}, want: []string{"PK-AOG", "PK-AVL"}},
+		}
+
+		for _, tc := range cases {
+			t.Run(tc.name, func(t *testing.T) {
+				rows, total, err := repo.List(context.Background(), "", tc.statuses, "identifier ASC", 0, 0, tc.groundedIDs)
+				if err != nil {
+					t.Fatalf("list: %v", err)
+				}
+				if int(total) != len(tc.want) || len(rows) != len(tc.want) {
+					t.Fatalf("count mismatch: total=%d len=%d want=%d", total, len(rows), len(tc.want))
+				}
+				got := make([]string, len(rows))
+				for i := range rows {
+					got[i] = rows[i].Identifier
+				}
+				for i := range tc.want {
+					if got[i] != tc.want[i] {
+						t.Fatalf("unexpected rows: got=%v want=%v", got, tc.want)
+					}
+				}
+			})
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+		if err := db.Migrator().DropTable(&helicopter.Helicopter{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+
+		if _, _, err := repo.List(context.Background(), "", nil, "", 10, 0, nil); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+		_ = repo.Create(context.Background(), &helicopter.Helicopter{Designation: "Main", Identifier: "PK-ERR", Type: "Twin"})
+
+		if _, _, err := repo.List(context.Background(), "", nil, "designation ASC, )", 10, 0, nil); err == nil {
+			t.Fatalf("expected find error from invalid sort")
+		}
+	})
+}
+
+func TestHelicopterRepositoryNextReportNumber(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+		row := &helicopter.Helicopter{
+			Designation:    "H145",
+			Identifier:     " PK-ABC ",
+			Type:           "Twin",
+			ReportSequence: 7,
+		}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		reportNumber, sequence, err := repo.NextReportNumber(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if reportNumber != "PK-ABC-0008" || sequence != 8 {
+			t.Fatalf("unexpected report number/sequence: %q %d", reportNumber, sequence)
+		}
+		loaded, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil || loaded == nil || loaded.ReportSequence != 8 {
+			t.Fatalf("expected report_sequence updated")
+		}
+	})
+
+	t.Run("identifier empty", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+		row := &helicopter.Helicopter{
+			Designation: "H145",
+			Identifier:  "   ",
+			Type:        "Twin",
+		}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		if _, _, err := repo.NextReportNumber(context.Background(), row.ID); err == nil {
+			t.Fatalf("expected identifier empty error")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+		if _, _, err := repo.NextReportNumber(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected not found error")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openHelicopterTestDB(t)
+		repo := NewHelicopterRepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, _, err := repo.NextReportNumber(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
diff --git a/internal/repository/mysql/helicopter_usage_repo.go b/internal/repository/mysql/helicopter_usage_repo.go
new file mode 100644
index 0000000..15b618a
--- /dev/null
+++ b/internal/repository/mysql/helicopter_usage_repo.go
@@ -0,0 +1,399 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	flightdata "wucher/internal/domain/flight_data"
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+	"wucher/internal/shared/pkg/metricparse"
+)
+
+type HelicopterUsageRepository struct {
+	db *gorm.DB
+}
+
+func NewHelicopterUsageRepository(db *gorm.DB) *HelicopterUsageRepository {
+	return &HelicopterUsageRepository{db: db}
+}
+
+func (r *HelicopterUsageRepository) Create(ctx context.Context, row *helicopterusage.HelicopterUsage) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *HelicopterUsageRepository) Update(ctx context.Context, row *helicopterusage.HelicopterUsage) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *HelicopterUsageRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "helicopter_usage", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&helicopterusage.HelicopterUsage{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error)
+}
+
+func (r *HelicopterUsageRepository) RefreshAll(ctx context.Context) error {
+	now := time.Now().UTC()
+	existing := map[string]helicopterusage.HelicopterUsage{}
+	{
+		var rows []helicopterusage.HelicopterUsage
+		if err := r.db.WithContext(ctx).
+			Select("helicopter_usage.*").
+			Where("helicopter_usage.deleted_at IS NULL").
+			Find(&rows).Error; err != nil {
+			return err
+		}
+		for i := range rows {
+			key, err := helicopterUsageKey(rows[i].HelicopterID)
+			if err != nil {
+				continue
+			}
+			existing[key] = rows[i]
+		}
+	}
+
+	helicopterIDs, err := r.listActiveHelicopterIDs(ctx)
+	if err != nil {
+		return err
+	}
+	if len(helicopterIDs) == 0 {
+		return nil
+	}
+
+	flightStats, err := r.flightStatsByHelicopter(ctx)
+	if err != nil {
+		return err
+	}
+	reportStats, err := r.reportStatsByHelicopter(ctx)
+	if err != nil {
+		return err
+	}
+
+	for _, helicopterID := range helicopterIDs {
+		key, _ := helicopterUsageKey(helicopterID)
+		row := &helicopterusage.HelicopterUsage{
+			HelicopterID:         append([]byte(nil), helicopterID...),
+			TotalLanding:         flightStats[key].TotalLanding,
+			TotalAirframeHours:   flightStats[key].TotalAirframeHours,
+			TotalAirframeCycles:  flightStats[key].TotalAirframeCycles,
+			TotalEngine1Hours:    flightStats[key].TotalAirframeHours,
+			TotalEngine2Hours:    flightStats[key].TotalAirframeHours,
+			TotalEngine1GpcNgN1:  reportStats[key].TotalEngine1GpcNgN1,
+			TotalEngine1PtcNfN2:  reportStats[key].TotalEngine1PtcNfN2,
+			TotalEngine2GpcNgN1:  reportStats[key].TotalEngine2GpcNgN1,
+			TotalEngine2PtcNfN2:  reportStats[key].TotalEngine2PtcNfN2,
+			TotalFlightReport:    reportStats[key].TotalFlightReport,
+			TotalHookRelease:     flightStats[key].TotalHookRelease,
+			TotalRotorBrakeCycle: flightStats[key].TotalRotorBrakeCycle,
+		}
+		if ex, ok := existing[key]; ok {
+			row.ID = ex.ID
+			row.CreatedAt = ex.CreatedAt
+			row.CreatedBy = ex.CreatedBy
+			row.UpdatedBy = ex.UpdatedBy
+			row.TotalEngine1Ccc = ex.TotalEngine1Ccc
+			row.TotalEngine2Ccc = ex.TotalEngine2Ccc
+
+			row.ManualAirframeHours = ex.ManualAirframeHours
+			row.ManualAirframeCycles = ex.ManualAirframeCycles
+			row.ManualEngine1Hours = ex.ManualEngine1Hours
+			row.ManualEngine1GpcNgN1 = ex.ManualEngine1GpcNgN1
+			row.ManualEngine1PtcNfN2 = ex.ManualEngine1PtcNfN2
+			row.ManualEngine2Hours = ex.ManualEngine2Hours
+			row.ManualEngine2GpcNgN1 = ex.ManualEngine2GpcNgN1
+			row.ManualEngine2PtcNfN2 = ex.ManualEngine2PtcNfN2
+			row.ManualLanding = ex.ManualLanding
+			row.ManualFlightReport = ex.ManualFlightReport
+			row.ManualHookRelease = ex.ManualHookRelease
+			row.ManualRotorBrakeCycle = ex.ManualRotorBrakeCycle
+
+			row.TotalAirframeHours += ex.ManualAirframeHours
+			row.TotalAirframeCycles += ex.ManualAirframeCycles
+			row.TotalEngine1Hours += ex.ManualEngine1Hours
+			row.TotalEngine1GpcNgN1 += ex.ManualEngine1GpcNgN1
+			row.TotalEngine1PtcNfN2 += ex.ManualEngine1PtcNfN2
+			row.TotalEngine2Hours += ex.ManualEngine2Hours
+			row.TotalEngine2GpcNgN1 += ex.ManualEngine2GpcNgN1
+			row.TotalEngine2PtcNfN2 += ex.ManualEngine2PtcNfN2
+			row.TotalLanding += ex.ManualLanding
+			row.TotalFlightReport += ex.ManualFlightReport
+			row.TotalHookRelease += ex.ManualHookRelease
+			row.TotalRotorBrakeCycle += ex.ManualRotorBrakeCycle
+		} else {
+			row.CreatedAt = now
+		}
+		row.UpdatedAt = now
+		if err := r.upsertByHelicopterID(ctx, row); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (r *HelicopterUsageRepository) GetByID(ctx context.Context, id []byte) (*helicopterusage.HelicopterUsage, error) {
+	var row helicopterusage.HelicopterUsage
+	err := r.db.WithContext(ctx).
+		Preload("Helicopter").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *HelicopterUsageRepository) GetByHelicopterID(ctx context.Context, helicopterID []byte) (*helicopterusage.HelicopterUsage, error) {
+	var row helicopterusage.HelicopterUsage
+	err := r.db.WithContext(ctx).
+		Preload("Helicopter").
+		Where("helicopter_id = ? AND deleted_at IS NULL", helicopterID).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+type helicopterUsageFlightStats struct {
+	TotalLanding         float64
+	TotalAirframeHours   float64
+	TotalAirframeCycles  float64
+	TotalHookRelease     float64
+	TotalRotorBrakeCycle float64
+}
+
+type helicopterUsageReportStats struct {
+	TotalFlightReport   float64
+	TotalEngine1GpcNgN1 float64
+	TotalEngine1PtcNfN2 float64
+	TotalEngine2GpcNgN1 float64
+	TotalEngine2PtcNfN2 float64
+}
+
+func (r *HelicopterUsageRepository) listActiveHelicopterIDs(ctx context.Context) ([][]byte, error) {
+	type row struct {
+		ID []byte `gorm:"column:id"`
+	}
+	rows := make([]row, 0)
+	if err := r.db.WithContext(ctx).
+		Table("helicopters").
+		Select("id").
+		Where("is_active = ?", true).
+		Order("created_at ASC, id ASC").
+		Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	out := make([][]byte, 0, len(rows))
+	for i := range rows {
+		if len(rows[i].ID) != 16 {
+			continue
+		}
+		out = append(out, append([]byte(nil), rows[i].ID...))
+	}
+	return out, nil
+}
+
+func (r *HelicopterUsageRepository) flightStatsByHelicopter(ctx context.Context) (map[string]helicopterUsageFlightStats, error) {
+	type row struct {
+		HelicopterID         []byte `gorm:"column:helicopter_id"`
+		TotalLanding         int64  `gorm:"column:total_landing"`
+		TotalAirframeNS      int64  `gorm:"column:total_airframe_ns"`
+		TotalAirframeCycles  int64  `gorm:"column:total_airframe_cycles"`
+		TotalHookRelease     int64  `gorm:"column:total_hook_release"`
+		TotalRotorBrakeCycle int64  `gorm:"column:total_rotor_brake_cycle"`
+	}
+	rows := make([]row, 0)
+	err := r.db.WithContext(ctx).
+		Table("flight_data fd").
+		Select(`
+			ra.helicopter_id,
+			COALESCE(SUM(fd.landing_count), 0) AS total_landing,
+			COALESCE(SUM(fd.duration), 0) AS total_airframe_ns,
+			COUNT(fd.id) AS total_airframe_cycles,
+			COALESCE(SUM(fd.hook_releases), 0) AS total_hook_release,
+			COALESCE(SUM(fd.rotor_brake_cycle), 0) AS total_rotor_brake_cycle
+		`).
+		Joins("JOIN missions m ON m.id = fd.mission_id AND m.deleted_at IS NULL").
+		Joins("JOIN flights f ON f.id = m.flight_id AND f.deleted_at IS NULL").
+		Joins("JOIN takeover_acs ta ON ta.id = f.takeover_ac_id AND ta.deleted_at IS NULL").
+		Joins("JOIN reserve_acs ra ON ra.id = ta.reserve_ac_id AND ra.deleted_at IS NULL").
+		Where("fd.deleted_at IS NULL AND fd.status = ?", flightdata.StatusCompleted).
+		Group("ra.helicopter_id").
+		Scan(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	out := make(map[string]helicopterUsageFlightStats, len(rows))
+	for i := range rows {
+		key, err := helicopterUsageKey(rows[i].HelicopterID)
+		if err != nil {
+			continue
+		}
+		out[key] = helicopterUsageFlightStats{
+			TotalLanding:         float64(rows[i].TotalLanding),
+			TotalAirframeHours:   float64(rows[i].TotalAirframeNS) / float64(time.Hour),
+			TotalAirframeCycles:  float64(rows[i].TotalAirframeCycles),
+			TotalHookRelease:     float64(rows[i].TotalHookRelease),
+			TotalRotorBrakeCycle: float64(rows[i].TotalRotorBrakeCycle),
+		}
+	}
+	return out, nil
+}
+
+func (r *HelicopterUsageRepository) reportStatsByHelicopter(ctx context.Context) (map[string]helicopterUsageReportStats, error) {
+	type row struct {
+		HelicopterID []byte  `gorm:"column:helicopter_id"`
+		Engine1GpcN1 *string `gorm:"column:engine1_gpc_n1"`
+		Engine1PtcN2 *string `gorm:"column:engine1_ptc_n2"`
+		Engine2GpcN1 *string `gorm:"column:engine2_gpc_n1"`
+		Engine2PtcN2 *string `gorm:"column:engine2_ptc_n2"`
+	}
+	rows := make([]row, 0)
+	if err := r.db.WithContext(ctx).
+		Table("fm_reports").
+		Select("helicopter_id, engine1_gpc_n1, engine1_ptc_n2, engine2_gpc_n1, engine2_ptc_n2").
+		Where("deleted_at IS NULL AND helicopter_id IS NOT NULL").
+		Order("helicopter_id ASC, created_at ASC, id ASC").
+		Scan(&rows).Error; err != nil {
+		return nil, err
+	}
+	out := make(map[string]helicopterUsageReportStats)
+	for i := range rows {
+		key, err := helicopterUsageKey(rows[i].HelicopterID)
+		if err != nil {
+			continue
+		}
+		acc := out[key]
+		acc.TotalFlightReport++
+		acc.TotalEngine1GpcNgN1 += parseNumericMetric(rows[i].Engine1GpcN1)
+		acc.TotalEngine1PtcNfN2 += parseNumericMetric(rows[i].Engine1PtcN2)
+		acc.TotalEngine2GpcNgN1 += parseNumericMetric(rows[i].Engine2GpcN1)
+		acc.TotalEngine2PtcNfN2 += parseNumericMetric(rows[i].Engine2PtcN2)
+		out[key] = acc
+	}
+	return out, nil
+}
+
+func (r *HelicopterUsageRepository) upsertByHelicopterID(ctx context.Context, row *helicopterusage.HelicopterUsage) error {
+	return r.db.WithContext(ctx).
+		Clauses(clause.OnConflict{
+			Columns: []clause.Column{{Name: "helicopter_id"}},
+			DoUpdates: clause.AssignmentColumns([]string{
+				"total_landing",
+				"total_airframe_hours",
+				"total_airframe_cycles",
+				"total_engine_1_hours",
+				"total_engine_1_gpc_ng_n1",
+				"total_engine_1_ptc_nf_n2",
+				"total_engine_2_hours",
+				"total_engine_2_gpc_ng_n1",
+				"total_engine_2_ptc_nf_n2",
+				"total_flight_report",
+				"total_hook_release",
+				"total_rotor_brake_cycle",
+				"updated_at",
+				"updated_by",
+			}),
+		}).
+		Create(row).Error
+}
+
+func helicopterUsageKey(id []byte) (string, error) {
+	if len(id) != 16 {
+		return "", fmt.Errorf("invalid helicopter id")
+	}
+	return string(id), nil
+}
+
+func parseNumericMetric(v *string) float64 {
+	return metricparse.Parse(v)
+}
+
+// FlightStatsByFlightID aggregates one flight's completed flight_data — the "today"
+// contribution of an FM report. Uses the same SUM/COUNT definitions as the cumulative
+// totals so prev = total - today reconciles exactly.
+func (r *HelicopterUsageRepository) FlightStatsByFlightID(ctx context.Context, flightID []byte) (helicopterusage.FlightDayStats, error) {
+	if len(flightID) != 16 {
+		return helicopterusage.FlightDayStats{}, nil
+	}
+	var row struct {
+		TotalLanding         int64 `gorm:"column:total_landing"`
+		TotalAirframeNS      int64 `gorm:"column:total_airframe_ns"`
+		TotalAirframeCycles  int64 `gorm:"column:total_airframe_cycles"`
+		TotalHookRelease     int64 `gorm:"column:total_hook_release"`
+		TotalRotorBrakeCycle int64 `gorm:"column:total_rotor_brake_cycle"`
+	}
+	err := r.db.WithContext(ctx).
+		Table("flight_data fd").
+		Select(`
+			COALESCE(SUM(fd.landing_count), 0) AS total_landing,
+			COALESCE(SUM(fd.duration), 0) AS total_airframe_ns,
+			COUNT(fd.id) AS total_airframe_cycles,
+			COALESCE(SUM(fd.hook_releases), 0) AS total_hook_release,
+			COALESCE(SUM(fd.rotor_brake_cycle), 0) AS total_rotor_brake_cycle
+		`).
+		Joins("JOIN missions m ON m.id = fd.mission_id AND m.deleted_at IS NULL").
+		Where("fd.deleted_at IS NULL AND fd.status = ? AND m.flight_id = ?", flightdata.StatusCompleted, flightID).
+		Scan(&row).Error
+	if err != nil {
+		return helicopterusage.FlightDayStats{}, err
+	}
+	return helicopterusage.FlightDayStats{
+		AirframeHours:   float64(row.TotalAirframeNS) / float64(time.Hour),
+		AirframeCycles:  float64(row.TotalAirframeCycles),
+		Landing:         float64(row.TotalLanding),
+		HookRelease:     float64(row.TotalHookRelease),
+		RotorBrakeCycle: float64(row.TotalRotorBrakeCycle),
+	}, nil
+}
+
+func (r *HelicopterUsageRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]helicopterusage.HelicopterUsage, int64, error) {
+	rows := make([]helicopterusage.HelicopterUsage, 0)
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&helicopterusage.HelicopterUsage{}).
+		Joins("LEFT JOIN helicopters h ON h.id = helicopter_usage.helicopter_id AND h.deleted_at IS NULL").
+		Where("helicopter_usage.deleted_at IS NULL")
+
+	if strings.TrimSpace(filter) != "" {
+		like := "%" + strings.ToLower(strings.TrimSpace(filter)) + "%"
+		base = base.Where(
+			"LOWER(HEX(helicopter_usage.id)) LIKE ? OR LOWER(HEX(helicopter_usage.helicopter_id)) LIKE ? OR LOWER(h.designation) LIKE ? OR LOWER(h.identifier) LIKE ?",
+			like, like, like, like,
+		)
+	}
+
+	query := base
+	if strings.TrimSpace(sort) != "" {
+		query = query.Order(sort)
+	} else {
+		query = query.Order("helicopter_usage.created_at DESC")
+	}
+
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Preload("Helicopter").Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/helicopter_usage_repo_test.go b/internal/repository/mysql/helicopter_usage_repo_test.go
new file mode 100644
index 0000000..576d322
--- /dev/null
+++ b/internal/repository/mysql/helicopter_usage_repo_test.go
@@ -0,0 +1,81 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openHelicopterUsageTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:helicopter_usage_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc:                                  func() time.Time { return time.Now().UTC() },
+		DisableForeignKeyConstraintWhenMigrating: true,
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&helicopterusage.HelicopterUsage{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+// TestHelicopterUsageRepositoryDecimalRoundTrip guards that the formerly-int counters
+// (landing, cycles, ccc, flight report, hook release, rotor brake) keep 2 decimals through
+// a persist -> read cycle.
+func TestHelicopterUsageRepositoryDecimalRoundTrip(t *testing.T) {
+	db := openHelicopterUsageTestDB(t)
+	repo := NewHelicopterUsageRepository(db)
+	ctx := context.Background()
+
+	helID := uuidv7.MustBytes()
+	row := &helicopterusage.HelicopterUsage{HelicopterID: helID}
+	row.ApplyManualSummary(helicopterusage.ManualSummaryInput{
+		Landing:         usageF64(123.45),
+		AirframeCycles:  usageF64(12.30),
+		Engine1Ccc:      usageF64(44.25),
+		FlightReport:    usageF64(80.10),
+		HookRelease:     usageF64(10.75),
+		RotorBrakeCycle: usageF64(8.99),
+	})
+	if err := repo.Create(ctx, row); err != nil {
+		t.Fatalf("create: %v", err)
+	}
+
+	got, err := repo.GetByHelicopterID(ctx, helID)
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if got == nil {
+		t.Fatalf("expected row")
+	}
+	cases := []struct {
+		name string
+		got  float64
+		want float64
+	}{
+		{"total_landing", got.TotalLanding, 123.45},
+		{"total_airframe_cycles", got.TotalAirframeCycles, 12.30},
+		{"total_engine_1_ccc", got.TotalEngine1Ccc, 44.25},
+		{"total_flight_report", got.TotalFlightReport, 80.10},
+		{"total_hook_release", got.TotalHookRelease, 10.75},
+		{"total_rotor_brake_cycle", got.TotalRotorBrakeCycle, 8.99},
+		{"manual_landing", got.ManualLanding, 123.45},
+	}
+	for _, c := range cases {
+		if c.got != c.want {
+			t.Fatalf("%s = %v, want %v (decimal truncated?)", c.name, c.got, c.want)
+		}
+	}
+}
+
+func usageF64(v float64) *float64 { return &v }
diff --git a/internal/repository/mysql/hems_operation_category_repo.go b/internal/repository/mysql/hems_operation_category_repo.go
new file mode 100644
index 0000000..95a0644
--- /dev/null
+++ b/internal/repository/mysql/hems_operation_category_repo.go
@@ -0,0 +1,84 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/operation"
+)
+
+type HEMSOperationCategoryRepository struct {
+	db *gorm.DB
+}
+
+func NewHEMSOperationCategoryRepository(db *gorm.DB) *HEMSOperationCategoryRepository {
+	return &HEMSOperationCategoryRepository{db: db}
+}
+
+func (r *HEMSOperationCategoryRepository) Create(ctx context.Context, row *operation.HEMSOperationCategory) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *HEMSOperationCategoryRepository) Update(ctx context.Context, row *operation.HEMSOperationCategory) error {
+	return r.db.WithContext(ctx).
+		Model(&operation.HEMSOperationCategory{}).
+		Where("id = ? AND deleted_at IS NULL", row.ID).
+		Updates(map[string]any{
+			"name":       row.Name,
+			"type":       row.Type,
+			"updated_by": row.UpdatedBy,
+			"updated_at": time.Now().UTC(),
+		}).Error
+}
+
+func (r *HEMSOperationCategoryRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+		"updated_at": now,
+	}
+	return r.db.WithContext(ctx).
+		Model(&operation.HEMSOperationCategory{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error
+}
+
+func (r *HEMSOperationCategoryRepository) GetByID(ctx context.Context, id []byte) (*operation.HEMSOperationCategory, error) {
+	var row operation.HEMSOperationCategory
+	err := r.db.WithContext(ctx).Where("id = ? AND deleted_at IS NULL", id).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *HEMSOperationCategoryRepository) List(ctx context.Context, filter string, sort string, limit, offset int) ([]operation.HEMSOperationCategory, int64, error) {
+	var rows []operation.HEMSOperationCategory
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&operation.HEMSOperationCategory{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("name LIKE ? OR type LIKE ?", like, like)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/hems_operation_repo.go b/internal/repository/mysql/hems_operation_repo.go
new file mode 100644
index 0000000..f8a2435
--- /dev/null
+++ b/internal/repository/mysql/hems_operation_repo.go
@@ -0,0 +1,91 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/operation"
+)
+
+type HEMSOperationRepository struct {
+	db *gorm.DB
+}
+
+func NewHEMSOperationRepository(db *gorm.DB) *HEMSOperationRepository {
+	return &HEMSOperationRepository{db: db}
+}
+
+func (r *HEMSOperationRepository) Create(ctx context.Context, row *operation.HEMSOperation) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *HEMSOperationRepository) Update(ctx context.Context, row *operation.HEMSOperation) error {
+	return r.db.WithContext(ctx).
+		Model(&operation.HEMSOperation{}).
+		Where("id = ? AND deleted_at IS NULL", row.ID).
+		Updates(map[string]any{
+			"date":                       row.Date,
+			"operational_data_id":        nullableBytes(row.OperationalDataID),
+			"mission_id":                 nullableBytes(row.MissionID),
+			"hems_operation_category_id": nullableBytes(row.HEMSOperationCategoryID),
+			"updated_by":                 row.UpdatedBy,
+			"updated_at":                 time.Now().UTC(),
+		}).Error
+}
+
+func (r *HEMSOperationRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+		"updated_at": now,
+	}
+	return r.db.WithContext(ctx).
+		Model(&operation.HEMSOperation{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error
+}
+
+func (r *HEMSOperationRepository) GetByID(ctx context.Context, id []byte) (*operation.HEMSOperation, error) {
+	var row operation.HEMSOperation
+	err := r.db.WithContext(ctx).
+		Preload("OperationalData").
+		Preload("Mission").
+		Preload("HEMSOperationCategory").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *HEMSOperationRepository) List(ctx context.Context, filter string, sort string, limit, offset int) ([]operation.HEMSOperation, int64, error) {
+	var rows []operation.HEMSOperation
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&operation.HEMSOperation{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("DATE_FORMAT(date, '%Y-%m-%dT%H:%i:%sZ') LIKE ?", like)
+	}
+
+	query := base.Preload("OperationalData").Preload("Mission").Preload("HEMSOperationCategory")
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/hems_operational_data_repo.go b/internal/repository/mysql/hems_operational_data_repo.go
new file mode 100644
index 0000000..9318a90
--- /dev/null
+++ b/internal/repository/mysql/hems_operational_data_repo.go
@@ -0,0 +1,170 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/operation"
+)
+
+type HEMSOperationalDataRepository struct {
+	db *gorm.DB
+}
+
+func NewHEMSOperationalDataRepository(db *gorm.DB) *HEMSOperationalDataRepository {
+	return &HEMSOperationalDataRepository{db: db}
+}
+
+func (r *HEMSOperationalDataRepository) Create(ctx context.Context, row *operation.HEMSOperationalData) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		forcePresents := append([]operation.OperationalDataForcePresent(nil), row.ForcePresents...)
+		files := append([]operation.OperationalFile(nil), row.Files...)
+		row.ForcePresents = nil
+		row.Files = nil
+
+		if err := tx.Create(row).Error; err != nil {
+			return err
+		}
+
+		for i := range forcePresents {
+			forcePresents[i].OperationalDataID = row.ID
+			if err := tx.Create(&forcePresents[i]).Error; err != nil {
+				return err
+			}
+		}
+		for i := range files {
+			files[i].OperationalDataID = row.ID
+			if err := tx.Create(&files[i]).Error; err != nil {
+				return err
+			}
+		}
+		row.ForcePresents = forcePresents
+		row.Files = files
+		return nil
+	})
+}
+
+func (r *HEMSOperationalDataRepository) GetByID(ctx context.Context, id []byte) (*operation.HEMSOperationalData, error) {
+	var row operation.HEMSOperationalData
+	err := r.db.WithContext(ctx).
+		Preload("ForcePresents").
+		Preload("Files").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *HEMSOperationalDataRepository) Update(ctx context.Context, row *operation.HEMSOperationalData) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		forcePresents := append([]operation.OperationalDataForcePresent(nil), row.ForcePresents...)
+		files := append([]operation.OperationalFile(nil), row.Files...)
+		row.ForcePresents = nil
+		row.Files = nil
+
+		if err := tx.Model(&operation.HEMSOperationalData{}).
+			Where("id = ? AND deleted_at IS NULL", row.ID).
+			Updates(map[string]any{
+				"time":                row.Time,
+				"land_id":             nullableBytes(row.LandID),
+				"vocation_id":         nullableBytes(row.VocationID),
+				"state_id":            nullableBytes(row.StateID),
+				"location":            row.Location,
+				"postcode":            row.Postcode,
+				"notes":               row.Notes,
+				"darkness":            row.Darkness,
+				"false_information":   row.FalseInformation,
+				"fog":                 row.Fog,
+				"precipitation":       row.Precipitation,
+				"mountain_use":        row.MountainUse,
+				"wind":                row.Wind,
+				"nfo_search":          row.NFOSearch,
+				"landing_site_search": row.LandingSiteSearch,
+				"temperature":         row.Temperature,
+				"altitude":            row.Altitude,
+				"terrain_index":       row.TerrainIndex,
+				"rope_recovery":       row.RopeRecovery,
+				"night_flight":        row.NightFlight,
+				"instrument_flight":   row.InstrumentFlight,
+				"additional_info":     row.AdditionalInfo,
+				"updated_by":          row.UpdatedBy,
+				"updated_at":          time.Now().UTC(),
+			}).Error; err != nil {
+			return err
+		}
+
+		if err := tx.Where("operational_data_id = ?", row.ID).Delete(&operation.OperationalDataForcePresent{}).Error; err != nil {
+			return err
+		}
+		for i := range forcePresents {
+			forcePresents[i].OperationalDataID = row.ID
+			if err := tx.Create(&forcePresents[i]).Error; err != nil {
+				return err
+			}
+		}
+		if err := tx.Where("operational_data_id = ?", row.ID).Delete(&operation.OperationalFile{}).Error; err != nil {
+			return err
+		}
+		for i := range files {
+			files[i].OperationalDataID = row.ID
+			if err := tx.Create(&files[i]).Error; err != nil {
+				return err
+			}
+		}
+		row.ForcePresents = forcePresents
+		row.Files = files
+		return nil
+	})
+}
+
+func (r *HEMSOperationalDataRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+		"updated_at": now,
+	}
+	return r.db.WithContext(ctx).
+		Model(&operation.HEMSOperationalData{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error
+}
+
+func (r *HEMSOperationalDataRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]operation.HEMSOperationalData, int64, error) {
+	var rows []operation.HEMSOperationalData
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&operation.HEMSOperationalData{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("location LIKE ? OR notes LIKE ? OR additional_info LIKE ? OR terrain_index LIKE ?", like, like, like, like)
+	}
+
+	query := base.Preload("ForcePresents").Preload("Files")
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func nullableBytes(raw []byte) any {
+	if len(raw) == 0 {
+		return nil
+	}
+	return raw
+}
diff --git a/internal/repository/mysql/hospital_repo.go b/internal/repository/mysql/hospital_repo.go
new file mode 100644
index 0000000..f64087a
--- /dev/null
+++ b/internal/repository/mysql/hospital_repo.go
@@ -0,0 +1,97 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/hospital"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type HospitalRepository struct {
+	db *gorm.DB
+}
+
+func NewHospitalRepository(db *gorm.DB) *HospitalRepository {
+	return &HospitalRepository{db: db}
+}
+
+func (r *HospitalRepository) Create(ctx context.Context, row *hospital.Hospital) error {
+	requestedIsActive := row.IsActive
+	db := r.db.WithContext(ctx)
+	if err := db.Create(row).Error; err != nil {
+		return err
+	}
+	return db.Model(&hospital.Hospital{}).Where("id = ?", row.ID).UpdateColumn("is_active", requestedIsActive).Error
+}
+
+func (r *HospitalRepository) Update(ctx context.Context, row *hospital.Hospital) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *HospitalRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "no_icao_codes", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&hospital.Hospital{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error)
+}
+
+func (r *HospitalRepository) GetByID(ctx context.Context, id []byte) (*hospital.Hospital, error) {
+	var row hospital.Hospital
+	err := r.db.WithContext(ctx).Where("id = ? AND deleted_at IS NULL", id).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *HospitalRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]hospital.Hospital, int64, error) {
+	var rows []hospital.Hospital
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&hospital.Hospital{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where(
+			"hospital_name LIKE ? OR address LIKE ? OR landline_number LIKE ? OR mobile_number LIKE ? OR email LIKE ? OR note LIKE ?",
+			like,
+			like,
+			like,
+			like,
+			like,
+			like,
+		)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("no_icao_codes", "is_active", "sortkey", "hospital_name", false) {
+			query = query.Order(clause)
+		}
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/hospital_repo_test.go b/internal/repository/mysql/hospital_repo_test.go
new file mode 100644
index 0000000..1036a32
--- /dev/null
+++ b/internal/repository/mysql/hospital_repo_test.go
@@ -0,0 +1,243 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/hospital"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openHospitalTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:hospital_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&hospital.Hospital{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestNewHospitalRepository(t *testing.T) {
+	db := openHospitalTestDB(t)
+	repo := NewHospitalRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestHospitalRepositoryCreate(t *testing.T) {
+	db := openHospitalTestDB(t)
+	repo := NewHospitalRepository(db)
+	row := &hospital.Hospital{Name: "RSUD Kota", Address: "Jl. Merdeka", LandlineNumber: "021123", MobileNumber: "08123", Email: "a@b.c"}
+
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(row.ID) == 0 {
+		t.Fatalf("expected id set")
+	}
+
+	inactive := &hospital.Hospital{Name: "RS Inactive", IsActive: false}
+	if err := repo.Create(context.Background(), inactive); err != nil {
+		t.Fatalf("create inactive: %v", err)
+	}
+	loadedInactive, err := repo.GetByID(context.Background(), inactive.ID)
+	if err != nil || loadedInactive == nil {
+		t.Fatalf("expected inactive row loadable")
+	}
+	if loadedInactive.IsActive {
+		t.Fatalf("expected inactive row persisted with is_active=false")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Create(context.Background(), &hospital.Hospital{Name: "AfterClose"}); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestHospitalRepositoryUpdate(t *testing.T) {
+	db := openHospitalTestDB(t)
+	repo := NewHospitalRepository(db)
+	row := &hospital.Hospital{Name: "Old", Address: "Old Addr"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Name = "New"
+	row.Address = "New Addr"
+	row.LandlineNumber = "021999"
+	row.MobileNumber = "08999"
+	row.Email = "new@hospital.local"
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil || loaded == nil || loaded.Name != "New" || loaded.Address != "New Addr" || loaded.LandlineNumber != "021999" || loaded.MobileNumber != "08999" || loaded.Email != "new@hospital.local" {
+		t.Fatalf("expected updated row")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestHospitalRepositoryDelete(t *testing.T) {
+	db := openHospitalTestDB(t)
+	repo := NewHospitalRepository(db)
+	row := &hospital.Hospital{Name: "DeleteMe", Address: "A"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	deletedBy := uuidv7.MustBytes()
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected soft deleted row hidden from GetByID")
+	}
+}
+
+func TestHospitalRepositoryGetByID(t *testing.T) {
+	t.Run("found", func(t *testing.T) {
+		db := openHospitalTestDB(t)
+		repo := NewHospitalRepository(db)
+		row := &hospital.Hospital{Name: "Found", Address: "Address", Email: "found@hospital.local"}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		got, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.Name != "Found" || got.Address != "Address" || got.Email != "found@hospital.local" {
+			t.Fatalf("expected row found")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openHospitalTestDB(t)
+		repo := NewHospitalRepository(db)
+		got, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil for not found")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openHospitalTestDB(t)
+		repo := NewHospitalRepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, err := repo.GetByID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
+
+func TestHospitalRepositoryList(t *testing.T) {
+	t.Run("success without limit", func(t *testing.T) {
+		db := openHospitalTestDB(t)
+		repo := NewHospitalRepository(db)
+		_ = repo.Create(context.Background(), &hospital.Hospital{Name: "Charlie Hospital", Address: "Gamma"})
+		_ = repo.Create(context.Background(), &hospital.Hospital{Name: "Alpha Hospital", Address: "Beta"})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("expected 2 rows, total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("success with filter sort and limit", func(t *testing.T) {
+		db := openHospitalTestDB(t)
+		repo := NewHospitalRepository(db)
+		_ = repo.Create(context.Background(), &hospital.Hospital{Name: "Main Hospital", Address: "Center"})
+		_ = repo.Create(context.Background(), &hospital.Hospital{Name: "Backup", Address: "Secondary"})
+
+		rows, total, err := repo.List(context.Background(), "Main", "hospital_name DESC", 1, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].Name != "Main Hospital" {
+			t.Fatalf("unexpected list result")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openHospitalTestDB(t)
+		repo := NewHospitalRepository(db)
+		if err := db.Migrator().DropTable(&hospital.Hospital{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+
+		if _, _, err := repo.List(context.Background(), "", "", 10, 0); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openHospitalTestDB(t)
+		repo := NewHospitalRepository(db)
+		_ = repo.Create(context.Background(), &hospital.Hospital{Name: "Main"})
+
+		if _, _, err := repo.List(context.Background(), "", "hospital_name ASC, )", 10, 0); err == nil {
+			t.Fatalf("expected find error from invalid sort")
+		}
+	})
+
+	t.Run("default order active sortkey first and inactive last", func(t *testing.T) {
+		db := openHospitalTestDB(t)
+		repo := NewHospitalRepository(db)
+		_ = repo.Create(context.Background(), &hospital.Hospital{Name: "Gamma", IsActive: true})
+		_ = repo.Create(context.Background(), &hospital.Hospital{Name: "Beta", SortKey: intPtrHospitalRepo(0), IsActive: true})
+		_ = repo.Create(context.Background(), &hospital.Hospital{Name: "Charlie", SortKey: intPtrHospitalRepo(2), IsActive: true})
+		_ = repo.Create(context.Background(), &hospital.Hospital{Name: "Alpha", SortKey: intPtrHospitalRepo(1), IsActive: true})
+		_ = repo.Create(context.Background(), &hospital.Hospital{Name: "Zulu", IsActive: false})
+		_ = repo.Create(context.Background(), &hospital.Hospital{Name: "Bravo", SortKey: intPtrHospitalRepo(9), IsActive: false})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 6 || len(rows) != 6 {
+			t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+		}
+
+		gotOrder := []string{rows[0].Name, rows[1].Name, rows[2].Name, rows[3].Name, rows[4].Name, rows[5].Name}
+		wantOrder := []string{"Beta", "Alpha", "Charlie", "Gamma", "Bravo", "Zulu"}
+		for i := range wantOrder {
+			if gotOrder[i] != wantOrder[i] {
+				t.Fatalf("unexpected default order: got=%v want=%v", gotOrder, wantOrder)
+			}
+		}
+	})
+}
+
+func intPtrHospitalRepo(v int) *int { return &v }
diff --git a/internal/repository/mysql/icao_repo.go b/internal/repository/mysql/icao_repo.go
new file mode 100644
index 0000000..d845eb8
--- /dev/null
+++ b/internal/repository/mysql/icao_repo.go
@@ -0,0 +1,104 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/icao"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type ICAORepository struct {
+	db *gorm.DB
+}
+
+func NewICAORepository(db *gorm.DB) *ICAORepository {
+	return &ICAORepository{db: db}
+}
+
+func (r *ICAORepository) Create(ctx context.Context, row *icao.ICAO) error {
+	requestedIsActive := row.IsActive
+	db := r.db.WithContext(ctx)
+	if err := db.Create(row).Error; err != nil {
+		return err
+	}
+	return db.Model(&icao.ICAO{}).
+		Where("id = ?", row.ID).
+		UpdateColumn("is_active", requestedIsActive).Error
+}
+
+func (r *ICAORepository) Update(ctx context.Context, row *icao.ICAO) error {
+	return r.db.WithContext(ctx).
+		Omit("FederalState", "Land").
+		Save(row).Error
+}
+
+func (r *ICAORepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "icaos", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&icao.ICAO{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error)
+}
+
+func (r *ICAORepository) GetByID(ctx context.Context, id []byte) (*icao.ICAO, error) {
+	var row icao.ICAO
+	err := r.db.WithContext(ctx).
+		Preload("Land").
+		Preload("FederalState").
+		Preload("FederalState.Land").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *ICAORepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]icao.ICAO, int64, error) {
+	var rows []icao.ICAO
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&icao.ICAO{}).
+		Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("icao_code LIKE ? OR name LIKE ? OR address LIKE ? OR landline_number LIKE ? OR mobile_number LIKE ? OR email LIKE ? OR note LIKE ?", like, like, like, like, like, like, like)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("icaos", "is_active", "sortkey", "icao_code", false) {
+			query = query.Order(clause)
+		}
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.
+		Preload("Land").
+		Preload("FederalState").
+		Preload("FederalState.Land").
+		Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/icao_repo_test.go b/internal/repository/mysql/icao_repo_test.go
new file mode 100644
index 0000000..1cd9545
--- /dev/null
+++ b/internal/repository/mysql/icao_repo_test.go
@@ -0,0 +1,272 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/federal_state"
+	"wucher/internal/domain/icao"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openICAOTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:icao_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&icao.ICAO{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestNewICAORepository(t *testing.T) {
+	db := openICAOTestDB(t)
+	repo := NewICAORepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestICAORepositoryCreate(t *testing.T) {
+	db := openICAOTestDB(t)
+	repo := NewICAORepository(db)
+	row := &icao.ICAO{ICAOCode: "EDDB", Address: "Berlin"}
+
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(row.ID) == 0 {
+		t.Fatalf("expected id set")
+	}
+	inactive := &icao.ICAO{ICAOCode: "EDIN", IsActive: false}
+	if err := repo.Create(context.Background(), inactive); err != nil {
+		t.Fatalf("create inactive: %v", err)
+	}
+	gotInactive, err := repo.GetByID(context.Background(), inactive.ID)
+	if err != nil {
+		t.Fatalf("get inactive: %v", err)
+	}
+	if gotInactive == nil || gotInactive.IsActive {
+		t.Fatalf("expected inactive icao persisted as false")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Create(context.Background(), &icao.ICAO{ICAOCode: "EDDM"}); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestICAORepositoryUpdate(t *testing.T) {
+	db := openICAOTestDB(t)
+	repo := NewICAORepository(db)
+	row := &icao.ICAO{ICAOCode: "EDDF", Address: "Old"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.ICAOCode = "EDDH"
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil || loaded == nil || loaded.ICAOCode != "EDDH" {
+		t.Fatalf("expected updated row")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestICAORepositoryUpdateOmitsFederalStateAssociation(t *testing.T) {
+	db := openICAOTestDB(t)
+	repo := NewICAORepository(db)
+	row := &icao.ICAO{
+		ICAOCode:       "EDDF",
+		FederalStateID: uuidv7.MustBytes(),
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	newFederalStateID := uuidv7.MustBytes()
+	row.FederalStateID = newFederalStateID
+	row.FederalState = &federal_state.FederalState{
+		ID:   uuidv7.MustBytes(),
+		Name: "stale preload relation",
+	}
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected update error with stale relation: %v", err)
+	}
+
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("reload: %v", err)
+	}
+	if loaded == nil {
+		t.Fatalf("expected row")
+	}
+	if string(loaded.FederalStateID) != string(newFederalStateID) {
+		t.Fatalf("expected federal_state_id updated")
+	}
+}
+
+func TestICAORepositoryDelete(t *testing.T) {
+	db := openICAOTestDB(t)
+	repo := NewICAORepository(db)
+	row := &icao.ICAO{ICAOCode: "EDDK"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	deletedBy := uuidv7.MustBytes()
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected soft deleted row hidden from GetByID")
+	}
+}
+
+func TestICAORepositoryGetByID(t *testing.T) {
+	t.Run("found", func(t *testing.T) {
+		db := openICAOTestDB(t)
+		repo := NewICAORepository(db)
+		row := &icao.ICAO{ICAOCode: "EDDL"}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		got, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.ICAOCode != "EDDL" {
+			t.Fatalf("expected row found")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openICAOTestDB(t)
+		repo := NewICAORepository(db)
+		got, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil for not found")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openICAOTestDB(t)
+		repo := NewICAORepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, err := repo.GetByID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
+
+func TestICAORepositoryList(t *testing.T) {
+	t.Run("success without limit", func(t *testing.T) {
+		db := openICAOTestDB(t)
+		repo := NewICAORepository(db)
+		_ = repo.Create(context.Background(), &icao.ICAO{ICAOCode: "C", Address: "Gamma"})
+		_ = repo.Create(context.Background(), &icao.ICAO{ICAOCode: "A", Address: "Alpha"})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("expected 2 rows, total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("success with filter sort and limit", func(t *testing.T) {
+		db := openICAOTestDB(t)
+		repo := NewICAORepository(db)
+		_ = repo.Create(context.Background(), &icao.ICAO{ICAOCode: "Main Base", Address: "Center"})
+		_ = repo.Create(context.Background(), &icao.ICAO{ICAOCode: "Backup", Address: "Secondary"})
+
+		rows, total, err := repo.List(context.Background(), "Main", "icao_code DESC", 1, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].ICAOCode != "Main Base" {
+			t.Fatalf("unexpected list result")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openICAOTestDB(t)
+		repo := NewICAORepository(db)
+		if err := db.Migrator().DropTable(&icao.ICAO{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+
+		if _, _, err := repo.List(context.Background(), "", "", 10, 0); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openICAOTestDB(t)
+		repo := NewICAORepository(db)
+		_ = repo.Create(context.Background(), &icao.ICAO{ICAOCode: "Main"})
+
+		if _, _, err := repo.List(context.Background(), "", "icao_code ASC, )", 10, 0); err == nil {
+			t.Fatalf("expected find error from invalid sort")
+		}
+	})
+
+	t.Run("default order active sortkey first and inactive last", func(t *testing.T) {
+		db := openICAOTestDB(t)
+		repo := NewICAORepository(db)
+		_ = repo.Create(context.Background(), &icao.ICAO{ICAOCode: "Gamma", IsActive: true})
+		_ = repo.Create(context.Background(), &icao.ICAO{ICAOCode: "Beta", SortKey: intPtrICAORepo(0), IsActive: true})
+		_ = repo.Create(context.Background(), &icao.ICAO{ICAOCode: "Charlie", SortKey: intPtrICAORepo(2), IsActive: true})
+		_ = repo.Create(context.Background(), &icao.ICAO{ICAOCode: "Alpha", SortKey: intPtrICAORepo(1), IsActive: true})
+		_ = repo.Create(context.Background(), &icao.ICAO{ICAOCode: "Zulu", IsActive: false})
+		_ = repo.Create(context.Background(), &icao.ICAO{ICAOCode: "Bravo", SortKey: intPtrICAORepo(9), IsActive: false})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 6 || len(rows) != 6 {
+			t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+		}
+
+		gotOrder := []string{rows[0].ICAOCode, rows[1].ICAOCode, rows[2].ICAOCode, rows[3].ICAOCode, rows[4].ICAOCode, rows[5].ICAOCode}
+		wantOrder := []string{"Beta", "Alpha", "Charlie", "Gamma", "Bravo", "Zulu"}
+		for i := range wantOrder {
+			if gotOrder[i] != wantOrder[i] {
+				t.Fatalf("unexpected default order: got=%v want=%v", gotOrder, wantOrder)
+			}
+		}
+	})
+}
+
+func intPtrICAORepo(v int) *int { return &v }
diff --git a/internal/repository/mysql/idempotency_store.go b/internal/repository/mysql/idempotency_store.go
new file mode 100644
index 0000000..62a69bc
--- /dev/null
+++ b/internal/repository/mysql/idempotency_store.go
@@ -0,0 +1,159 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"wucher/internal/domain/transient"
+	"wucher/internal/queue"
+)
+
+const (
+	idempotencyStateProcessing = "processing"
+	idempotencyStateDone       = "done"
+)
+
+type QueueIdempotencyStore struct {
+	db     *gorm.DB
+	prefix string
+	now    func() time.Time
+}
+
+func NewQueueIdempotencyStore(db *gorm.DB, prefix string) *QueueIdempotencyStore {
+	return &QueueIdempotencyStore{
+		db:     db,
+		prefix: strings.TrimSpace(prefix),
+		now:    func() time.Time { return time.Now().UTC() },
+	}
+}
+
+func (s *QueueIdempotencyStore) Acquire(ctx context.Context, key string, processingTTL time.Duration) (queue.IdempotencyState, error) {
+	if s == nil || s.db == nil {
+		return queue.IdempotencyStateAcquired, errors.New("queue idempotency db is required")
+	}
+	storeKey := s.key(key)
+	if storeKey == "" {
+		return "", errors.New("queue idempotency key is required")
+	}
+	if processingTTL <= 0 {
+		processingTTL = 15 * time.Minute
+	}
+
+	now := s.now().UTC()
+	expiresAt := now.Add(processingTTL)
+	record := transient.QueueIdempotencyRecord{
+		IdempotencyKey: storeKey,
+		State:          idempotencyStateProcessing,
+		ExpiresAt:      expiresAt,
+	}
+	create := s.db.WithContext(ctx).Clauses(clause.OnConflict{DoNothing: true}).Create(&record)
+	if create.Error != nil {
+		return "", create.Error
+	}
+	if create.RowsAffected == 1 {
+		return queue.IdempotencyStateAcquired, nil
+	}
+
+	existing, err := s.load(ctx, storeKey)
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		retry := s.db.WithContext(ctx).Clauses(clause.OnConflict{DoNothing: true}).Create(&record)
+		if retry.Error != nil {
+			return "", retry.Error
+		}
+		if retry.RowsAffected == 1 {
+			return queue.IdempotencyStateAcquired, nil
+		}
+		return queue.IdempotencyStateInProgress, nil
+	}
+	if err != nil {
+		return "", err
+	}
+
+	if !existing.ExpiresAt.After(now) {
+		update := s.db.WithContext(ctx).
+			Model(&transient.QueueIdempotencyRecord{}).
+			Where("idempotency_key = ? AND expires_at <= ?", storeKey, now).
+			Updates(map[string]any{
+				"state":      idempotencyStateProcessing,
+				"expires_at": expiresAt,
+				"updated_at": now,
+			})
+		if update.Error != nil {
+			return "", update.Error
+		}
+		if update.RowsAffected == 1 {
+			return queue.IdempotencyStateAcquired, nil
+		}
+		existing, err = s.load(ctx, storeKey)
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return queue.IdempotencyStateAcquired, nil
+		}
+		if err != nil {
+			return "", err
+		}
+	}
+
+	if existing.State == idempotencyStateDone {
+		return queue.IdempotencyStateDuplicate, nil
+	}
+	return queue.IdempotencyStateInProgress, nil
+}
+
+func (s *QueueIdempotencyStore) MarkCompleted(ctx context.Context, key string, ttl time.Duration) error {
+	if s == nil || s.db == nil {
+		return errors.New("queue idempotency db is required")
+	}
+	storeKey := s.key(key)
+	if storeKey == "" {
+		return errors.New("queue idempotency key is required")
+	}
+	if ttl <= 0 {
+		ttl = 24 * time.Hour
+	}
+	now := s.now().UTC()
+	record := transient.QueueIdempotencyRecord{
+		IdempotencyKey: storeKey,
+		State:          idempotencyStateDone,
+		ExpiresAt:      now.Add(ttl),
+	}
+	return s.db.WithContext(ctx).Clauses(clause.OnConflict{
+		Columns: []clause.Column{{Name: "idempotency_key"}},
+		DoUpdates: clause.Assignments(map[string]any{
+			"state":      record.State,
+			"expires_at": record.ExpiresAt,
+			"updated_at": now,
+		}),
+	}).Create(&record).Error
+}
+
+func (s *QueueIdempotencyStore) Release(ctx context.Context, key string) error {
+	if s == nil || s.db == nil {
+		return errors.New("queue idempotency db is required")
+	}
+	storeKey := s.key(key)
+	if storeKey == "" {
+		return nil
+	}
+	return s.db.WithContext(ctx).Delete(&transient.QueueIdempotencyRecord{}, "idempotency_key = ?", storeKey).Error
+}
+
+func (s *QueueIdempotencyStore) load(ctx context.Context, key string) (*transient.QueueIdempotencyRecord, error) {
+	var record transient.QueueIdempotencyRecord
+	if err := s.db.WithContext(ctx).Where("idempotency_key = ?", key).First(&record).Error; err != nil {
+		return nil, err
+	}
+	return &record, nil
+}
+
+func (s *QueueIdempotencyStore) key(key string) string {
+	key = strings.TrimSpace(key)
+	if key == "" {
+		return ""
+	}
+	return s.prefix + key
+}
diff --git a/internal/repository/mysql/idempotency_store_test.go b/internal/repository/mysql/idempotency_store_test.go
new file mode 100644
index 0000000..d0ca4da
--- /dev/null
+++ b/internal/repository/mysql/idempotency_store_test.go
@@ -0,0 +1,88 @@
+package mysql
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"wucher/internal/queue"
+)
+
+func TestQueueIdempotencyStore_AcquireMarkCompletedRelease(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	baseTime := time.Date(2026, 3, 20, 10, 0, 0, 0, time.UTC)
+	store := NewQueueIdempotencyStore(db, "queue:idempotency:")
+	store.now = func() time.Time { return baseTime }
+
+	ctx := context.Background()
+	state, err := store.Acquire(ctx, "msg-1", time.Minute)
+	if err != nil {
+		t.Fatalf("acquire first: %v", err)
+	}
+	if state != queue.IdempotencyStateAcquired {
+		t.Fatalf("expected acquired, got %s", state)
+	}
+
+	state, err = store.Acquire(ctx, "msg-1", time.Minute)
+	if err != nil {
+		t.Fatalf("acquire in-progress: %v", err)
+	}
+	if state != queue.IdempotencyStateInProgress {
+		t.Fatalf("expected in progress, got %s", state)
+	}
+
+	if err := store.MarkCompleted(ctx, "msg-1", time.Hour); err != nil {
+		t.Fatalf("mark completed: %v", err)
+	}
+	state, err = store.Acquire(ctx, "msg-1", time.Minute)
+	if err != nil {
+		t.Fatalf("acquire duplicate: %v", err)
+	}
+	if state != queue.IdempotencyStateDuplicate {
+		t.Fatalf("expected duplicate, got %s", state)
+	}
+
+	if err := store.Release(ctx, "msg-1"); err != nil {
+		t.Fatalf("release: %v", err)
+	}
+	state, err = store.Acquire(ctx, "msg-1", time.Minute)
+	if err != nil {
+		t.Fatalf("acquire after release: %v", err)
+	}
+	if state != queue.IdempotencyStateAcquired {
+		t.Fatalf("expected acquired after release, got %s", state)
+	}
+}
+
+func TestQueueIdempotencyStore_ReacquiresExpiredProcessingRecord(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	baseTime := time.Date(2026, 3, 20, 10, 0, 0, 0, time.UTC)
+	store := NewQueueIdempotencyStore(db, "queue:idempotency:")
+	store.now = func() time.Time { return baseTime }
+
+	ctx := context.Background()
+	state, err := store.Acquire(ctx, "msg-expired", time.Minute)
+	if err != nil {
+		t.Fatalf("acquire first: %v", err)
+	}
+	if state != queue.IdempotencyStateAcquired {
+		t.Fatalf("expected acquired, got %s", state)
+	}
+
+	store.now = func() time.Time { return baseTime.Add(2 * time.Minute) }
+	state, err = store.Acquire(ctx, "msg-expired", time.Minute)
+	if err != nil {
+		t.Fatalf("reacquire expired: %v", err)
+	}
+	if state != queue.IdempotencyStateAcquired {
+		t.Fatalf("expected reacquired state, got %s", state)
+	}
+}
diff --git a/internal/repository/mysql/insurance_patient_data_repo.go b/internal/repository/mysql/insurance_patient_data_repo.go
new file mode 100644
index 0000000..7aac988
--- /dev/null
+++ b/internal/repository/mysql/insurance_patient_data_repo.go
@@ -0,0 +1,84 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	insurancepatientdata "wucher/internal/domain/insurance_patient_data"
+)
+
+type InsurancePatientDataRepository struct {
+	db *gorm.DB
+}
+
+func NewInsurancePatientDataRepository(db *gorm.DB) *InsurancePatientDataRepository {
+	return &InsurancePatientDataRepository{db: db}
+}
+
+func (r *InsurancePatientDataRepository) Create(ctx context.Context, row *insurancepatientdata.InsurancePatientData) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *InsurancePatientDataRepository) Update(ctx context.Context, row *insurancepatientdata.InsurancePatientData) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *InsurancePatientDataRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "insurance_patient_data", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&insurancepatientdata.InsurancePatientData{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error)
+}
+
+func (r *InsurancePatientDataRepository) GetByID(ctx context.Context, id []byte) (*insurancepatientdata.InsurancePatientData, error) {
+	var row insurancepatientdata.InsurancePatientData
+	err := r.db.WithContext(ctx).
+		Preload("HealthInsuranceCompanies", "deleted_at IS NULL").
+		Preload("FederalState", "deleted_at IS NULL").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *InsurancePatientDataRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]insurancepatientdata.InsurancePatientData, int64, error) {
+	var rows []insurancepatientdata.InsurancePatientData
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&insurancepatientdata.InsurancePatientData{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("HEX(health_insurance_companies_id) LIKE ? OR HEX(federal_state_id) LIKE ?", like, like)
+	}
+
+	query := base.
+		Preload("HealthInsuranceCompanies", "deleted_at IS NULL").
+		Preload("FederalState", "deleted_at IS NULL")
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/land_repo.go b/internal/repository/mysql/land_repo.go
new file mode 100644
index 0000000..b57b159
--- /dev/null
+++ b/internal/repository/mysql/land_repo.go
@@ -0,0 +1,183 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/land"
+	"wucher/internal/shared/pkg/sortkey"
+	"wucher/internal/transport/http/dto"
+)
+
+type LandRepository struct {
+	db *gorm.DB
+}
+
+func NewLandRepository(db *gorm.DB) *LandRepository {
+	return &LandRepository{db: db}
+}
+
+func (r *LandRepository) Create(ctx context.Context, row *land.Land) error {
+	requestedIsActive := row.IsActive
+	db := r.db.WithContext(ctx)
+	if err := db.Create(row).Error; err != nil {
+		return err
+	}
+	return db.Model(&land.Land{}).Where("id = ?", row.ID).UpdateColumn("is_active", requestedIsActive).Error
+}
+
+func (r *LandRepository) Update(ctx context.Context, row *land.Land) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *LandRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "lands", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&land.Land{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error)
+}
+
+func (r *LandRepository) GetByID(ctx context.Context, id []byte) (*land.Land, error) {
+	var row land.Land
+	err := r.db.WithContext(ctx).Where("id = ? AND deleted_at IS NULL", id).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *LandRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]land.Land, int64, error) {
+	var rows []land.Land
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&land.Land{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("(name LIKE ? OR land_iso_code LIKE ?)", like, like)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("lands", "is_active", "sortkey", "name", false) {
+			query = query.Order(clause)
+		}
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func (r *LandRepository) GetByIDView(ctx context.Context, id []byte) (*dto.LandView, error) {
+	row, err := r.GetByID(ctx, id)
+	if err != nil || row == nil {
+		return nil, err
+	}
+	views, err := r.buildViews(ctx, []land.Land{*row})
+	if err != nil {
+		return nil, err
+	}
+	if len(views) == 0 {
+		return nil, nil
+	}
+	return &views[0], nil
+}
+
+func (r *LandRepository) ListView(ctx context.Context, filter, sort string, limit, offset int) ([]dto.LandView, int64, error) {
+	rows, total, err := r.List(ctx, filter, sort, limit, offset)
+	if err != nil {
+		return nil, 0, err
+	}
+	views, err := r.buildViews(ctx, rows)
+	if err != nil {
+		return nil, 0, err
+	}
+	return views, total, nil
+}
+
+type landFederalStateRow struct {
+	ID     []byte `gorm:"column:id"`
+	Name   string `gorm:"column:name"`
+	LandID []byte `gorm:"column:land_id"`
+}
+
+func (r *LandRepository) attachFederalStates(ctx context.Context, rows []land.Land) (map[string][]dto.LandFederalStateView, error) {
+	if len(rows) == 0 {
+		return map[string][]dto.LandFederalStateView{}, nil
+	}
+
+	landIDs := make([][]byte, 0, len(rows))
+	for i := range rows {
+		if len(rows[i].ID) == 0 {
+			continue
+		}
+		landIDs = append(landIDs, rows[i].ID)
+	}
+	if len(landIDs) == 0 {
+		return map[string][]dto.LandFederalStateView{}, nil
+	}
+
+	var states []landFederalStateRow
+	if err := r.db.WithContext(ctx).
+		Table("federal_states").
+		Select("id, name, land_id").
+		Where("deleted_at IS NULL AND land_id IN ?", landIDs).
+		Order("name ASC").
+		Find(&states).Error; err != nil {
+		return nil, err
+	}
+
+	grouped := make(map[string][]dto.LandFederalStateView, len(landIDs))
+	for i := range states {
+		s := states[i]
+		key := string(s.LandID)
+		grouped[key] = append(grouped[key], dto.LandFederalStateView{
+			ID:   append([]byte(nil), s.ID...),
+			Name: s.Name,
+		})
+	}
+	return grouped, nil
+}
+
+func (r *LandRepository) buildViews(ctx context.Context, rows []land.Land) ([]dto.LandView, error) {
+	if len(rows) == 0 {
+		return []dto.LandView{}, nil
+	}
+	federalStatesByLandID, err := r.attachFederalStates(ctx, rows)
+	if err != nil {
+		return nil, err
+	}
+
+	views := make([]dto.LandView, 0, len(rows))
+	for i := range rows {
+		key := string(rows[i].ID)
+		list := federalStatesByLandID[key]
+		views = append(views, dto.LandView{
+			Row:               rows[i],
+			FederalStateTotal: len(list),
+			FederalStateList:  list,
+		})
+	}
+	return views, nil
+}
diff --git a/internal/repository/mysql/land_repo_test.go b/internal/repository/mysql/land_repo_test.go
new file mode 100644
index 0000000..2fe05aa
--- /dev/null
+++ b/internal/repository/mysql/land_repo_test.go
@@ -0,0 +1,304 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/land"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openLandTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:land_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&land.Land{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	if err := db.Exec(`CREATE TABLE IF NOT EXISTS federal_states (
+		id BLOB PRIMARY KEY,
+		name TEXT NOT NULL,
+		land_id BLOB NOT NULL,
+		deleted_at DATETIME
+	)`).Error; err != nil {
+		t.Fatalf("create federal_states table: %v", err)
+	}
+	return db
+}
+
+func TestNewLandRepository(t *testing.T) {
+	db := openLandTestDB(t)
+	repo := NewLandRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestLandRepositoryCreate(t *testing.T) {
+	db := openLandTestDB(t)
+	repo := NewLandRepository(db)
+	row := &land.Land{Name: "Germany", LandISOCode: "DE"}
+
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(row.ID) == 0 {
+		t.Fatalf("expected id set")
+	}
+	exportID := "DE001"
+	withExport := &land.Land{Name: "WithExport", LandISOCode: "DX", BMDExportID: &exportID}
+	if err := repo.Create(context.Background(), withExport); err != nil {
+		t.Fatalf("create with export id: %v", err)
+	}
+	gotWithExport, err := repo.GetByID(context.Background(), withExport.ID)
+	if err != nil {
+		t.Fatalf("get with export id: %v", err)
+	}
+	if gotWithExport == nil || gotWithExport.BMDExportID == nil || *gotWithExport.BMDExportID != "DE001" {
+		t.Fatalf("expected bmd_export_id persisted")
+	}
+	inactive := &land.Land{Name: "Inactive", LandISOCode: "IN", IsActive: false}
+	if err := repo.Create(context.Background(), inactive); err != nil {
+		t.Fatalf("create inactive: %v", err)
+	}
+	gotInactive, err := repo.GetByID(context.Background(), inactive.ID)
+	if err != nil {
+		t.Fatalf("get inactive: %v", err)
+	}
+	if gotInactive == nil || gotInactive.IsActive {
+		t.Fatalf("expected inactive land persisted as false")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Create(context.Background(), &land.Land{Name: "AfterClose", LandISOCode: "AF"}); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestLandRepositoryUpdate(t *testing.T) {
+	db := openLandTestDB(t)
+	repo := NewLandRepository(db)
+	row := &land.Land{Name: "Old", LandISOCode: "OL"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Name = "New"
+	updatedExportID := "DE999"
+	row.BMDExportID = &updatedExportID
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil || loaded == nil || loaded.Name != "New" {
+		t.Fatalf("expected updated row")
+	}
+	if loaded.BMDExportID == nil || *loaded.BMDExportID != "DE999" {
+		t.Fatalf("expected updated bmd_export_id")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestLandRepositoryDelete(t *testing.T) {
+	db := openLandTestDB(t)
+	repo := NewLandRepository(db)
+	row := &land.Land{Name: "DeleteMe", LandISOCode: "DM"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	deletedBy := uuidv7.MustBytes()
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected soft deleted row hidden from GetByID")
+	}
+}
+
+func TestLandRepositoryGetByID(t *testing.T) {
+	t.Run("found", func(t *testing.T) {
+		db := openLandTestDB(t)
+		repo := NewLandRepository(db)
+		row := &land.Land{Name: "Found", LandISOCode: "FO"}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		got, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.Name != "Found" {
+			t.Fatalf("expected row found")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openLandTestDB(t)
+		repo := NewLandRepository(db)
+		got, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil for not found")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openLandTestDB(t)
+		repo := NewLandRepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, err := repo.GetByID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
+
+func TestLandRepositoryList(t *testing.T) {
+	t.Run("success without limit", func(t *testing.T) {
+		db := openLandTestDB(t)
+		repo := NewLandRepository(db)
+		_ = repo.Create(context.Background(), &land.Land{Name: "C", LandISOCode: "CC"})
+		_ = repo.Create(context.Background(), &land.Land{Name: "A", LandISOCode: "AA"})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("expected 2 rows, total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("success with filter sort and limit", func(t *testing.T) {
+		db := openLandTestDB(t)
+		repo := NewLandRepository(db)
+		_ = repo.Create(context.Background(), &land.Land{Name: "Main Base", LandISOCode: "MB"})
+		_ = repo.Create(context.Background(), &land.Land{Name: "Backup", LandISOCode: "BK"})
+
+		rows, total, err := repo.List(context.Background(), "Main", "name DESC", 1, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].Name != "Main Base" {
+			t.Fatalf("unexpected list result")
+		}
+	})
+
+	t.Run("success filter by land iso code", func(t *testing.T) {
+		db := openLandTestDB(t)
+		repo := NewLandRepository(db)
+		_ = repo.Create(context.Background(), &land.Land{Name: "Germany", LandISOCode: "DE"})
+		_ = repo.Create(context.Background(), &land.Land{Name: "Indonesia", LandISOCode: "ID"})
+
+		rows, total, err := repo.List(context.Background(), "DE", "name ASC", 10, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].LandISOCode != "DE" {
+			t.Fatalf("expected filter to match land_iso_code, got total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("includes federal state aggregate fields in view", func(t *testing.T) {
+		db := openLandTestDB(t)
+		repo := NewLandRepository(db)
+		row := &land.Land{Name: "Germany", LandISOCode: "DE"}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+		if err := db.Table("federal_states").Create([]map[string]any{
+			{"id": uuidv7.MustBytes(), "name": "Bayern", "land_id": row.ID, "deleted_at": nil},
+			{"id": uuidv7.MustBytes(), "name": "Berlin", "land_id": row.ID, "deleted_at": nil},
+		}).Error; err != nil {
+			t.Fatalf("seed federal_states: %v", err)
+		}
+
+		rows, total, err := repo.ListView(context.Background(), "Germany", "", 10, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 {
+			t.Fatalf("unexpected rows: total=%d len=%d", total, len(rows))
+		}
+		if rows[0].FederalStateTotal != 2 || len(rows[0].FederalStateList) != 2 {
+			t.Fatalf("expected federal states attached in list result")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openLandTestDB(t)
+		repo := NewLandRepository(db)
+		if err := db.Migrator().DropTable(&land.Land{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+
+		if _, _, err := repo.List(context.Background(), "", "", 10, 0); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openLandTestDB(t)
+		repo := NewLandRepository(db)
+		_ = repo.Create(context.Background(), &land.Land{Name: "Main", LandISOCode: "MN"})
+
+		if _, _, err := repo.List(context.Background(), "", "name ASC, )", 10, 0); err == nil {
+			t.Fatalf("expected find error from invalid sort")
+		}
+	})
+
+	t.Run("default order active sortkey first and inactive last", func(t *testing.T) {
+		db := openLandTestDB(t)
+		repo := NewLandRepository(db)
+		_ = repo.Create(context.Background(), &land.Land{Name: "Gamma", LandISOCode: "GA", IsActive: true})
+		_ = repo.Create(context.Background(), &land.Land{Name: "Beta", LandISOCode: "BT", SortKey: intPtrLandRepo(0), IsActive: true})
+		_ = repo.Create(context.Background(), &land.Land{Name: "Charlie", LandISOCode: "CH", SortKey: intPtrLandRepo(2), IsActive: true})
+		_ = repo.Create(context.Background(), &land.Land{Name: "Alpha", LandISOCode: "AL", SortKey: intPtrLandRepo(1), IsActive: true})
+		_ = repo.Create(context.Background(), &land.Land{Name: "Zulu", LandISOCode: "ZU", IsActive: false})
+		_ = repo.Create(context.Background(), &land.Land{Name: "Bravo", LandISOCode: "BR", SortKey: intPtrLandRepo(9), IsActive: false})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 6 || len(rows) != 6 {
+			t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+		}
+
+		gotOrder := []string{rows[0].Name, rows[1].Name, rows[2].Name, rows[3].Name, rows[4].Name, rows[5].Name}
+		wantOrder := []string{"Beta", "Alpha", "Charlie", "Gamma", "Bravo", "Zulu"}
+		for i := range wantOrder {
+			if gotOrder[i] != wantOrder[i] {
+				t.Fatalf("unexpected default order: got=%v want=%v", gotOrder, wantOrder)
+			}
+		}
+	})
+}
+
+func intPtrLandRepo(v int) *int { return &v }
diff --git a/internal/repository/mysql/master_settings_repo.go b/internal/repository/mysql/master_settings_repo.go
new file mode 100644
index 0000000..5570a01
--- /dev/null
+++ b/internal/repository/mysql/master_settings_repo.go
@@ -0,0 +1,135 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	mastersettings "wucher/internal/domain/master_settings"
+)
+
+type MasterSettingsRepository struct {
+	db *gorm.DB
+}
+
+func NewMasterSettingsRepository(db *gorm.DB) *MasterSettingsRepository {
+	return &MasterSettingsRepository{db: db}
+}
+
+func (r *MasterSettingsRepository) Create(ctx context.Context, row *mastersettings.MasterSettings) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *MasterSettingsRepository) Update(ctx context.Context, row *mastersettings.MasterSettings) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *MasterSettingsRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "master_settings", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&mastersettings.MasterSettings{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error)
+}
+
+func (r *MasterSettingsRepository) GetByID(ctx context.Context, id []byte) (*mastersettings.MasterSettings, error) {
+	var row mastersettings.MasterSettings
+	err := r.db.WithContext(ctx).Where("id = ? AND deleted_at IS NULL", id).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *MasterSettingsRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]mastersettings.MasterSettings, int64, error) {
+	var rows []mastersettings.MasterSettings
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&mastersettings.MasterSettings{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("company_name LIKE ? OR logo_url LIKE ? OR title LIKE ? OR subtitle LIKE ?", like, like, like, like)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return rows, total, nil
+}
+
+func (r *MasterSettingsRepository) UpsertSettingValues(ctx context.Context, rows []mastersettings.MasterSettingValue) error {
+	if len(rows) == 0 {
+		return nil
+	}
+	now := time.Now().UTC()
+	items := make([]mastersettings.MasterSettingValue, 0, len(rows))
+	for i := range rows {
+		key := strings.TrimSpace(rows[i].SettingKey)
+		if key == "" {
+			continue
+		}
+		item := rows[i]
+		item.SettingKey = key
+		item.UpdatedAt = now
+		if item.CreatedAt.IsZero() {
+			item.CreatedAt = now
+		}
+		items = append(items, item)
+	}
+	if len(items) == 0 {
+		return nil
+	}
+	return r.db.WithContext(ctx).Clauses(clause.OnConflict{
+		Columns: []clause.Column{{Name: "setting_key"}},
+		DoUpdates: clause.AssignmentColumns([]string{
+			"value",
+			"is_encrypted",
+			"updated_at",
+			"updated_by",
+		}),
+	}).Create(&items).Error
+}
+
+func (r *MasterSettingsRepository) GetSettingValuesByKeys(ctx context.Context, keys []string) ([]mastersettings.MasterSettingValue, error) {
+	trimmed := make([]string, 0, len(keys))
+	for _, key := range keys {
+		key = strings.TrimSpace(key)
+		if key == "" {
+			continue
+		}
+		trimmed = append(trimmed, key)
+	}
+	if len(trimmed) == 0 {
+		return []mastersettings.MasterSettingValue{}, nil
+	}
+	var rows []mastersettings.MasterSettingValue
+	if err := r.db.WithContext(ctx).
+		Where("setting_key IN ?", trimmed).
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
diff --git a/internal/repository/mysql/master_settings_repo_test.go b/internal/repository/mysql/master_settings_repo_test.go
new file mode 100644
index 0000000..eb056e5
--- /dev/null
+++ b/internal/repository/mysql/master_settings_repo_test.go
@@ -0,0 +1,274 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	mastersettings "wucher/internal/domain/master_settings"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openMasterSettingsTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:master_settings_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&mastersettings.MasterSettings{}, &mastersettings.MasterSettingValue{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestNewMasterSettingsRepository(t *testing.T) {
+	db := openMasterSettingsTestDB(t)
+	repo := NewMasterSettingsRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestMasterSettingsRepositoryCreate(t *testing.T) {
+	db := openMasterSettingsTestDB(t)
+	repo := NewMasterSettingsRepository(db)
+	row := &mastersettings.MasterSettings{
+		CompanyName: "Wucher",
+		Title:       "Welcome",
+		Subtitle:    "Flight ops",
+	}
+
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(row.ID) == 0 {
+		t.Fatalf("expected id set")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Create(context.Background(), &mastersettings.MasterSettings{CompanyName: "AfterClose"}); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestMasterSettingsRepositoryUpdate(t *testing.T) {
+	db := openMasterSettingsTestDB(t)
+	repo := NewMasterSettingsRepository(db)
+	row := &mastersettings.MasterSettings{
+		CompanyName: "Wucher",
+		Title:       "Old",
+		Subtitle:    "Old subtitle",
+	}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Title = "New"
+	row.Subtitle = "New subtitle"
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected update error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get after update: %v", err)
+	}
+	if got == nil || got.Title != "New" || got.Subtitle != "New subtitle" {
+		t.Fatalf("expected updated values persisted")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestMasterSettingsRepositoryDelete(t *testing.T) {
+	db := openMasterSettingsTestDB(t)
+	repo := NewMasterSettingsRepository(db)
+	row := &mastersettings.MasterSettings{CompanyName: "Delete Me"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	deletedBy := uuidv7.MustBytes()
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy); err != nil {
+		t.Fatalf("unexpected delete error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected soft deleted row hidden from GetByID")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Delete(context.Background(), row.ID, deletedBy); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestMasterSettingsRepositoryGetByID(t *testing.T) {
+	t.Run("found", func(t *testing.T) {
+		db := openMasterSettingsTestDB(t)
+		repo := NewMasterSettingsRepository(db)
+		row := &mastersettings.MasterSettings{CompanyName: "Wucher"}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		got, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.CompanyName != "Wucher" {
+			t.Fatalf("expected row found")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openMasterSettingsTestDB(t)
+		repo := NewMasterSettingsRepository(db)
+		got, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil for not found")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openMasterSettingsTestDB(t)
+		repo := NewMasterSettingsRepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, err := repo.GetByID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
+
+func TestMasterSettingsRepositoryList(t *testing.T) {
+	t.Run("success without limit", func(t *testing.T) {
+		db := openMasterSettingsTestDB(t)
+		repo := NewMasterSettingsRepository(db)
+		_ = repo.Create(context.Background(), &mastersettings.MasterSettings{CompanyName: "Beta", Title: "T1"})
+		_ = repo.Create(context.Background(), &mastersettings.MasterSettings{CompanyName: "Alpha", Title: "T2"})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("expected 2 rows, total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("success with filter sort and limit", func(t *testing.T) {
+		db := openMasterSettingsTestDB(t)
+		repo := NewMasterSettingsRepository(db)
+		_ = repo.Create(context.Background(), &mastersettings.MasterSettings{CompanyName: "Wucher", Title: "Primary"})
+		_ = repo.Create(context.Background(), &mastersettings.MasterSettings{CompanyName: "Other", Title: "Secondary"})
+
+		rows, total, err := repo.List(context.Background(), "Wuc", "company_name DESC", 1, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].CompanyName != "Wucher" {
+			t.Fatalf("unexpected list result")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openMasterSettingsTestDB(t)
+		repo := NewMasterSettingsRepository(db)
+		if err := db.Migrator().DropTable(&mastersettings.MasterSettings{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+
+		if _, _, err := repo.List(context.Background(), "", "", 10, 0); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openMasterSettingsTestDB(t)
+		repo := NewMasterSettingsRepository(db)
+		_ = repo.Create(context.Background(), &mastersettings.MasterSettings{CompanyName: "Wucher"})
+
+		if _, _, err := repo.List(context.Background(), "", "company_name ASC, )", 10, 0); err == nil {
+			t.Fatalf("expected find error from invalid sort")
+		}
+	})
+}
+
+func TestMasterSettingsRepositorySettingValues(t *testing.T) {
+	db := openMasterSettingsTestDB(t)
+	repo := NewMasterSettingsRepository(db)
+	actor := []byte("abcdefghijklmnop")
+
+	rows := []mastersettings.MasterSettingValue{
+		{
+			SettingKey:  mastersettings.SettingMicrosoftEntraTenantID,
+			Value:       "tenant-a",
+			CreatedBy:   actor,
+			UpdatedBy:   actor,
+			IsEncrypted: false,
+		},
+		{
+			SettingKey:  mastersettings.SettingMicrosoftEntraClientSecret,
+			Value:       "ciphertext",
+			CreatedBy:   actor,
+			UpdatedBy:   actor,
+			IsEncrypted: true,
+		},
+	}
+	if err := repo.UpsertSettingValues(context.Background(), rows); err != nil {
+		t.Fatalf("upsert setting values: %v", err)
+	}
+
+	got, err := repo.GetSettingValuesByKeys(context.Background(), []string{
+		mastersettings.SettingMicrosoftEntraTenantID,
+		mastersettings.SettingMicrosoftEntraClientSecret,
+	})
+	if err != nil {
+		t.Fatalf("get setting values: %v", err)
+	}
+	if len(got) != 2 {
+		t.Fatalf("expected 2 rows, got %d", len(got))
+	}
+
+	if err := repo.UpsertSettingValues(context.Background(), []mastersettings.MasterSettingValue{
+		{
+			SettingKey:  mastersettings.SettingMicrosoftEntraTenantID,
+			Value:       "tenant-b",
+			UpdatedBy:   actor,
+			IsEncrypted: false,
+		},
+	}); err != nil {
+		t.Fatalf("upsert update row: %v", err)
+	}
+	got, err = repo.GetSettingValuesByKeys(context.Background(), []string{
+		mastersettings.SettingMicrosoftEntraTenantID,
+	})
+	if err != nil {
+		t.Fatalf("get updated value: %v", err)
+	}
+	if len(got) != 1 || got[0].Value != "tenant-b" {
+		t.Fatalf("expected updated value tenant-b, got %#v", got)
+	}
+}
diff --git a/internal/repository/mysql/mcf_repo.go b/internal/repository/mysql/mcf_repo.go
new file mode 100644
index 0000000..dcbec50
--- /dev/null
+++ b/internal/repository/mysql/mcf_repo.go
@@ -0,0 +1,116 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/mcf"
+)
+
+type MCFRepository struct{ db *gorm.DB }
+
+func NewMCFRepository(db *gorm.DB) *MCFRepository { return &MCFRepository{db: db} }
+
+func (r *MCFRepository) Create(ctx context.Context, row *mcf.MaintenanceCheckFlight) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *MCFRepository) Update(ctx context.Context, row *mcf.MaintenanceCheckFlight) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *MCFRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return r.db.WithContext(ctx).Model(&mcf.MaintenanceCheckFlight{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(map[string]any{"deleted_at": gorm.Expr("NOW(3)"), "deleted_by": deletedBy, "updated_by": deletedBy}).Error
+}
+
+func (r *MCFRepository) GetByID(ctx context.Context, id []byte) (*mcf.MaintenanceCheckFlight, error) {
+	var row mcf.MaintenanceCheckFlight
+	err := r.db.WithContext(ctx).
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *MCFRepository) GetLatestByHelicopter(ctx context.Context, helicopterID []byte) (*mcf.MaintenanceCheckFlight, error) {
+	var row mcf.MaintenanceCheckFlight
+	err := r.db.WithContext(ctx).
+		Where("helicopter_id = ? AND deleted_at IS NULL", helicopterID).
+		Order("created_at DESC").
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *MCFRepository) ListByHelicopter(ctx context.Context, helicopterID []byte) ([]mcf.MaintenanceCheckFlight, error) {
+	rows := make([]mcf.MaintenanceCheckFlight, 0)
+	err := r.db.WithContext(ctx).
+		Where("helicopter_id = ? AND deleted_at IS NULL", helicopterID).
+		Order("created_at DESC").
+		Find(&rows).Error
+	return rows, err
+}
+
+// LatestByHelicopterIDs returns the latest (non-deleted) MCF per helicopter, keyed by
+// helicopter id (raw bytes as string). Helicopters without an MCF are simply absent.
+func (r *MCFRepository) LatestByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]*mcf.MaintenanceCheckFlight, error) {
+	out := make(map[string]*mcf.MaintenanceCheckFlight, len(helicopterIDs))
+	if len(helicopterIDs) == 0 {
+		return out, nil
+	}
+	rows := make([]mcf.MaintenanceCheckFlight, 0)
+	err := r.db.WithContext(ctx).
+		Where("helicopter_id IN ? AND deleted_at IS NULL AND id = (SELECT m2.id FROM maintenance_check_flights m2 WHERE m2.helicopter_id = maintenance_check_flights.helicopter_id AND m2.deleted_at IS NULL ORDER BY m2.created_at DESC, m2.id DESC LIMIT 1)", helicopterIDs).
+		Find(&rows).Error
+	if err != nil {
+		return out, err
+	}
+	for i := range rows {
+		out[string(rows[i].HelicopterID)] = &rows[i]
+	}
+	return out, nil
+}
+
+// HelicopterHasOpenMCF reports whether the helicopter has a draft MCF (created but not
+// yet completed/signed). Enforces one open MCF per helicopter.
+func (r *MCFRepository) HelicopterHasOpenMCF(ctx context.Context, helicopterID []byte) (bool, error) {
+	var count int64
+	err := r.db.WithContext(ctx).Model(&mcf.MaintenanceCheckFlight{}).
+		Where("helicopter_id = ? AND deleted_at IS NULL AND completed_at IS NULL AND cancelled_at IS NULL", helicopterID).
+		Count(&count).Error
+	if err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+func (r *MCFRepository) PendingHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]bool, error) {
+	out := make(map[string]bool)
+	if len(helicopterIDs) == 0 {
+		return out, nil
+	}
+	type rowT struct {
+		HelicopterID []byte `gorm:"column:helicopter_id"`
+	}
+	rows := make([]rowT, 0)
+	err := r.db.WithContext(ctx).
+		Table("maintenance_check_flights m").
+		Select("m.helicopter_id").
+		Where("m.deleted_at IS NULL AND m.cancelled_at IS NULL AND m.helicopter_id IN ? AND m.id = (SELECT m2.id FROM maintenance_check_flights m2 WHERE m2.helicopter_id = m.helicopter_id AND m2.deleted_at IS NULL AND m2.cancelled_at IS NULL ORDER BY m2.created_at DESC, m2.id DESC LIMIT 1) AND m.completed_at IS NULL", helicopterIDs).
+		Scan(&rows).Error
+	if err != nil {
+		return out, err
+	}
+	for i := range rows {
+		out[string(rows[i].HelicopterID)] = true
+	}
+	return out, nil
+}
diff --git a/internal/repository/mysql/medicine_repo.go b/internal/repository/mysql/medicine_repo.go
new file mode 100644
index 0000000..4dfad83
--- /dev/null
+++ b/internal/repository/mysql/medicine_repo.go
@@ -0,0 +1,235 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/medicine"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type MedicineRepository struct {
+	db *gorm.DB
+}
+
+func NewMedicineRepository(db *gorm.DB) *MedicineRepository {
+	return &MedicineRepository{db: db}
+}
+
+func (r *MedicineRepository) Create(ctx context.Context, row *medicine.Medicine) error {
+	requestedIsActive := row.IsActive
+	db := r.db.WithContext(ctx)
+	if err := db.Create(row).Error; err != nil {
+		return err
+	}
+	if err := db.Model(row).Association("MotorReactions").Replace(row.MotorReactions); err != nil {
+		return err
+	}
+	return db.Model(&medicine.Medicine{}).Where("id = ?", row.ID).UpdateColumn("is_active", requestedIsActive).Error
+}
+
+func (r *MedicineRepository) Update(ctx context.Context, row *medicine.Medicine) error {
+	db := r.db.WithContext(ctx)
+	if err := db.Save(row).Error; err != nil {
+		return err
+	}
+	if row.MotorReactions != nil {
+		if err := db.Model(row).Association("MotorReactions").Replace(row.MotorReactions); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (r *MedicineRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// Allow medicine delete even when it still has reaction links by detaching M:N rows first.
+		if err := tx.Where("medicine_id = ?", id).Delete(&medicine.MedicineMotorReaction{}).Error; err != nil {
+			return err
+		}
+
+		if err := ensureNoReferenceBeforeDelete(ctx, tx, "medicines", id); err != nil {
+			return err
+		}
+
+		now := time.Now().UTC()
+		updates := map[string]any{
+			"deleted_at": now,
+			"deleted_by": deletedBy,
+			"updated_by": deletedBy,
+		}
+		return mapDeleteConstraintError(tx.
+			Model(&medicine.Medicine{}).
+			Where("id = ? AND deleted_at IS NULL", id).
+			Updates(updates).Error)
+	})
+}
+
+func (r *MedicineRepository) GetByID(ctx context.Context, id []byte) (*medicine.Medicine, error) {
+	var row medicine.Medicine
+	err := r.db.WithContext(ctx).
+		Preload("MedicineGroup", "deleted_at IS NULL").
+		Preload("MotorReaction", "deleted_at IS NULL").
+		Preload("MotorReactions", "deleted_at IS NULL").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *MedicineRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]medicine.Medicine, int64, error) {
+	var rows []medicine.Medicine
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&medicine.Medicine{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("name LIKE ? OR note LIKE ? OR pack LIKE ? OR unit LIKE ? OR CAST(`column` AS CHAR) LIKE ?", like, like, like, like, like)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("medicines", "is_active", "sortkey", "name", false) {
+			query = query.Order(clause)
+		}
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	query = query.
+		Preload("MedicineGroup", "deleted_at IS NULL").
+		Preload("MotorReaction", "deleted_at IS NULL").
+		Preload("MotorReactions", "deleted_at IS NULL")
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func (r *MedicineRepository) CreateGroup(ctx context.Context, row *medicine.MedicineGroup) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *MedicineRepository) UpdateGroup(ctx context.Context, row *medicine.MedicineGroup) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *MedicineRepository) DeleteGroup(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "medicine_groups", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&medicine.MedicineGroup{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(map[string]any{
+			"deleted_at": now,
+			"deleted_by": deletedBy,
+			"updated_by": deletedBy,
+		}).Error)
+}
+
+func (r *MedicineRepository) GetGroupByID(ctx context.Context, id []byte) (*medicine.MedicineGroup, error) {
+	var row medicine.MedicineGroup
+	err := r.db.WithContext(ctx).Where("id = ? AND deleted_at IS NULL", id).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *MedicineRepository) ListGroups(ctx context.Context, filter, sort string, limit, offset int) ([]medicine.MedicineGroup, int64, error) {
+	var rows []medicine.MedicineGroup
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&medicine.MedicineGroup{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("name LIKE ?", like)
+	}
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		query = query.Order("name ASC")
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func (r *MedicineRepository) CreateReaction(ctx context.Context, row *medicine.MotorReaction) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *MedicineRepository) UpdateReaction(ctx context.Context, row *medicine.MotorReaction) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *MedicineRepository) DeleteReaction(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "motor_reactions", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&medicine.MotorReaction{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(map[string]any{
+			"deleted_at": now,
+			"deleted_by": deletedBy,
+			"updated_by": deletedBy,
+		}).Error)
+}
+
+func (r *MedicineRepository) GetReactionByID(ctx context.Context, id []byte) (*medicine.MotorReaction, error) {
+	var row medicine.MotorReaction
+	err := r.db.WithContext(ctx).Where("id = ? AND deleted_at IS NULL", id).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *MedicineRepository) ListReactions(ctx context.Context, filter, sort string, limit, offset int) ([]medicine.MotorReaction, int64, error) {
+	var rows []medicine.MotorReaction
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&medicine.MotorReaction{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("name LIKE ? OR CAST(score AS CHAR) LIKE ?", like, like)
+	}
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		query = query.Order("name ASC")
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/medicine_repo_test.go b/internal/repository/mysql/medicine_repo_test.go
new file mode 100644
index 0000000..8135fc7
--- /dev/null
+++ b/internal/repository/mysql/medicine_repo_test.go
@@ -0,0 +1,263 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/medicine"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openMedicineTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:medicine_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&medicine.Medicine{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestNewMedicineRepository(t *testing.T) {
+	db := openMedicineTestDB(t)
+	repo := NewMedicineRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestMedicineRepositoryCreate(t *testing.T) {
+	db := openMedicineTestDB(t)
+	repo := NewMedicineRepository(db)
+	row := &medicine.Medicine{Name: "Paracetamol", Pack:"500mg", Unit: "tablet", Column: 1}
+
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(row.ID) == 0 {
+		t.Fatalf("expected id set")
+	}
+	inactive := &medicine.Medicine{Name: "Ibuprofen", Pack: "200mg", Unit: "capsule", IsActive: false}
+	if err := repo.Create(context.Background(), inactive); err != nil {
+		t.Fatalf("create inactive: %v", err)
+	}
+	gotInactive, err := repo.GetByID(context.Background(), inactive.ID)
+	if err != nil {
+		t.Fatalf("get inactive: %v", err)
+	}
+	if gotInactive == nil || gotInactive.IsActive || gotInactive.Unit != "capsule" {
+		t.Fatalf("expected inactive medicine persisted as false")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Create(context.Background(), &medicine.Medicine{Name: "AfterClose", Pack: "10mg", Column: 2}); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestMedicineRepositoryUpdate(t *testing.T) {
+	db := openMedicineTestDB(t)
+	repo := NewMedicineRepository(db)
+	row := &medicine.Medicine{Name: "Old", Pack: "100mg", Column: 1}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Name = "New"
+	row.Pack = "250mg"
+	row.Unit = "solution"
+	row.Column = 3
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil || loaded == nil || loaded.Name != "New" || loaded.Pack != "250mg" || loaded.Column != 3 {
+		t.Fatalf("expected updated row")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestMedicineRepositoryDelete(t *testing.T) {
+	db := openMedicineTestDB(t)
+	repo := NewMedicineRepository(db)
+	row := &medicine.Medicine{Name: "DeleteMe", Pack: "500mg", Unit: "tablet", Column: 2}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	deletedBy := uuidv7.MustBytes()
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected soft deleted row hidden from GetByID")
+	}
+}
+
+func TestMedicineRepositoryGetByID(t *testing.T) {
+	t.Run("found", func(t *testing.T) {
+		db := openMedicineTestDB(t)
+		repo := NewMedicineRepository(db)
+		row := &medicine.Medicine{Name: "Found", Pack: "10mg", Unit: "tablet", Column: 8}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		got, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.Name != "Found" || got.Pack != "10mg" || got.Unit != "tablet" || got.Column != 8 {
+			t.Fatalf("expected row found")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openMedicineTestDB(t)
+		repo := NewMedicineRepository(db)
+		got, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil for not found")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openMedicineTestDB(t)
+		repo := NewMedicineRepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, err := repo.GetByID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
+
+func TestMedicineRepositoryList(t *testing.T) {
+	t.Run("success without limit", func(t *testing.T) {
+		db := openMedicineTestDB(t)
+		repo := NewMedicineRepository(db)
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "C", Pack:"1mg", Unit: "tablet", Column: 11})
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "A", Pack:"2mg", Unit: "capsule", Column: 12})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("expected 2 rows, total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("success with filter sort and limit", func(t *testing.T) {
+		db := openMedicineTestDB(t)
+		repo := NewMedicineRepository(db)
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "Main", Pack:"500mg", Unit: "tablet", Column: 77})
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "Backup", Pack:"200mg", Unit: "capsule", Column: 10})
+
+		rows, total, err := repo.List(context.Background(), "77", "`column` DESC", 1, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].Column != 77 {
+			t.Fatalf("unexpected list result")
+		}
+	})
+
+	t.Run("success filtering by unit field", func(t *testing.T) {
+		db := openMedicineTestDB(t)
+		repo := NewMedicineRepository(db)
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "Tablet A", Pack: "100mg", Unit: "tablet", Column: 1})
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "Capsule B", Pack: "200mg", Unit: "capsule", Column: 2})
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "Spray C", Pack: "50mg", Unit: "spray", Column: 3})
+
+		rows, total, err := repo.List(context.Background(), "spray", "", 10, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].Unit != "spray" {
+			t.Fatalf("unexpected filtered result by unit")
+		}
+
+		rows, total, err = repo.List(context.Background(), "capsule", "", 10, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].Unit != "capsule" {
+			t.Fatalf("unexpected filtered result by unit")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openMedicineTestDB(t)
+		repo := NewMedicineRepository(db)
+		if err := db.Migrator().DropTable(&medicine.Medicine{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+
+		if _, _, err := repo.List(context.Background(), "", "", 10, 0); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openMedicineTestDB(t)
+		repo := NewMedicineRepository(db)
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "Main", Pack:"100mg", Unit: "tablet", Column: 2})
+
+		if _, _, err := repo.List(context.Background(), "", "name ASC, )", 10, 0); err == nil {
+			t.Fatalf("expected find error from invalid sort")
+		}
+	})
+
+	t.Run("default order active then name ascending", func(t *testing.T) {
+		db := openMedicineTestDB(t)
+		repo := NewMedicineRepository(db)
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "Gamma", Unit: "tablet", IsActive: true})
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "Beta", Unit: "tablet", IsActive: true})
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "Charlie", Unit: "tablet", IsActive: true})
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "Alpha", Unit: "tablet", IsActive: true})
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "Zulu", Unit: "tablet", IsActive: false})
+		_ = repo.Create(context.Background(), &medicine.Medicine{Name: "Bravo", Unit: "tablet", IsActive: false})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 6 || len(rows) != 6 {
+			t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+		}
+
+		gotOrder := []string{rows[0].Name, rows[1].Name, rows[2].Name, rows[3].Name, rows[4].Name, rows[5].Name}
+		wantOrder := []string{"Alpha", "Beta", "Charlie", "Gamma", "Bravo", "Zulu"}
+		for i := range wantOrder {
+			if gotOrder[i] != wantOrder[i] {
+				t.Fatalf("unexpected default order: got=%v want=%v", gotOrder, wantOrder)
+			}
+		}
+	})
+}
diff --git a/internal/repository/mysql/mission_repo.go b/internal/repository/mysql/mission_repo.go
new file mode 100644
index 0000000..ed0e51b
--- /dev/null
+++ b/internal/repository/mysql/mission_repo.go
@@ -0,0 +1,528 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	flightdata "wucher/internal/domain/flight_data"
+	"wucher/internal/domain/mission"
+	"wucher/internal/shared/pkg/txctx"
+)
+
+type MissionRepository struct {
+	db *gorm.DB
+}
+
+func NewMissionRepository(db *gorm.DB) *MissionRepository {
+	return &MissionRepository{db: db}
+}
+
+func (r *MissionRepository) Create(ctx context.Context, row *mission.Mission) error {
+	normalizeMissionTimeForDB(row)
+	if err := txctx.DB(ctx, r.db).Create(row).Error; err != nil {
+		if errors.Is(err, gorm.ErrDuplicatedKey) {
+			return mission.ErrDuplicateFlight
+		}
+		return err
+	}
+	return nil
+}
+
+func (r *MissionRepository) WithTransaction(ctx context.Context, fn func(context.Context) error) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		return fn(txctx.With(ctx, tx))
+	})
+}
+
+// MaxCodeSeqByPrefix returns the highest numeric suffix among mission codes that
+// start with prefix (e.g. "HEMS-26-"), or 0 when none exist. Used to compute the
+// next per-type, per-year sequence number.
+func (r *MissionRepository) MaxCodeSeqByPrefix(ctx context.Context, prefix string) (int, error) {
+	var maxSeq *int
+	err := txctx.DB(ctx, r.db).
+		Model(&mission.Mission{}).
+		Where("code LIKE ? AND deleted_at IS NULL", prefix+"%").
+		Select("MAX(CAST(SUBSTRING_INDEX(code, '-', -1) AS UNSIGNED))").
+		Scan(&maxSeq).Error
+	if err != nil {
+		return 0, err
+	}
+	if maxSeq == nil {
+		return 0, nil
+	}
+	return *maxSeq, nil
+}
+
+func (r *MissionRepository) AttachFile(ctx context.Context, missionID []byte, fileAttachmentID []byte) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var missionRow mission.Mission
+		if err := tx.Where("id = ? AND deleted_at IS NULL", missionID).
+			Take(&missionRow).Error; err != nil {
+			return err
+		}
+		var existing mission.MissionFile
+		err := tx.Where("mission_id = ? AND file_attachment_id = ?", missionID, fileAttachmentID).
+			Take(&existing).Error
+		if err == nil {
+			return nil
+		}
+		if !errors.Is(err, gorm.ErrRecordNotFound) {
+			return err
+		}
+		return tx.Create(&mission.MissionFile{
+			MissionID:        append([]byte(nil), missionID...),
+			FileAttachmentID: append([]byte(nil), fileAttachmentID...),
+		}).Error
+	})
+}
+
+func (r *MissionRepository) DetachFile(ctx context.Context, missionID []byte, fileAttachmentID []byte) error {
+	return r.db.WithContext(ctx).
+		Where("mission_id = ? AND file_attachment_id = ?", missionID, fileAttachmentID).
+		Delete(&mission.MissionFile{}).Error
+}
+
+func (r *MissionRepository) CreateCategory(ctx context.Context, row *mission.MissionCategory) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *MissionRepository) UpdateFlightDataIDByID(ctx context.Context, missionID, flightDataID, updatedBy []byte) error {
+	patch := map[string]any{
+		"flight_data_id": flightDataID,
+	}
+	if len(updatedBy) == 16 {
+		patch["updated_by"] = updatedBy
+	}
+	res := txctx.DB(ctx, r.db).
+		Model(&mission.Mission{}).
+		Where("id = ? AND deleted_at IS NULL", missionID).
+		Updates(patch)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *MissionRepository) UpdateByID(ctx context.Context, missionID []byte, missionType string, missionCategoryID []byte, subtypeID []byte, note string, updatedBy []byte) error {
+	patch := map[string]any{
+		"type":                missionType,
+		"mission_category_id": missionCategoryID,
+		"subtype_id":          nil,
+		"note":                strings.TrimSpace(note),
+	}
+	if len(subtypeID) == 16 {
+		patch["subtype_id"] = subtypeID
+	}
+	if len(updatedBy) == 16 {
+		patch["updated_by"] = updatedBy
+	}
+
+	res := r.db.WithContext(ctx).
+		Model(&mission.Mission{}).
+		Where("id = ? AND deleted_at IS NULL", missionID).
+		Updates(patch)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *MissionRepository) DeleteByID(ctx context.Context, missionID []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		patch := map[string]any{
+			"deleted_at": now,
+			"deleted_by": deletedBy,
+		}
+		if len(deletedBy) == 16 {
+			patch["updated_by"] = deletedBy
+		}
+
+		res := tx.Model(&mission.Mission{}).
+			Where("id = ? AND deleted_at IS NULL", missionID).
+			Updates(patch)
+		if res.Error != nil {
+			return res.Error
+		}
+		if res.RowsAffected == 0 {
+			return gorm.ErrRecordNotFound
+		}
+
+		fdPatch := map[string]any{
+			"deleted_at": now,
+			"deleted_by": deletedBy,
+		}
+		if len(deletedBy) == 16 {
+			fdPatch["updated_by"] = deletedBy
+		}
+
+		if err := tx.Model(&flightdata.FlightData{}).
+			Where("mission_id = ? AND deleted_at IS NULL", missionID).
+			Updates(fdPatch).Error; err != nil {
+			return err
+		}
+
+		return nil
+	})
+}
+
+func (r *MissionRepository) DeleteByFlightID(ctx context.Context, flightID []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	patch := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+	}
+	if len(deletedBy) == 16 {
+		patch["updated_by"] = deletedBy
+	}
+
+	res := r.db.WithContext(ctx).
+		Model(&mission.Mission{}).
+		Where("flight_id = ? AND deleted_at IS NULL", flightID).
+		Updates(patch)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *MissionRepository) ListByFlightID(ctx context.Context, flightID []byte) ([]mission.Mission, error) {
+	rows := make([]mission.Mission, 0)
+	err := r.db.WithContext(ctx).
+		Select(r.statusSelectSQL()).
+		Joins("LEFT JOIN mission_subcategories msc ON msc.id = missions.subtype_id").
+		Preload("MissionSubCategory").
+		Preload("Flight").
+		Preload("Files").
+		Preload("Files.FileAttachment").
+		Preload("Files.FileAttachment.File").
+		Where("missions.flight_id = ? AND missions.deleted_at IS NULL", flightID).
+		Order("missions.created_at ASC, missions.id ASC").
+		Find(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *MissionRepository) ListByFlightIDs(ctx context.Context, flightIDs [][]byte) ([]mission.Mission, error) {
+	if len(flightIDs) == 0 {
+		return []mission.Mission{}, nil
+	}
+	rows := make([]mission.Mission, 0)
+	err := r.db.WithContext(ctx).
+		Select(r.statusSelectSQL()).
+		Joins("LEFT JOIN mission_subcategories msc ON msc.id = missions.subtype_id").
+		Preload("MissionSubCategory").
+		Preload("Flight").
+		Preload("Files").
+		Preload("Files.FileAttachment").
+		Preload("Files.FileAttachment.File").
+		Where("missions.flight_id IN ? AND missions.deleted_at IS NULL", flightIDs).
+		Order("missions.flight_id ASC, missions.created_at ASC, missions.id ASC").
+		Find(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (r *MissionRepository) GetByID(ctx context.Context, missionID []byte) (*mission.Mission, error) {
+	var row mission.Mission
+	err := r.db.WithContext(ctx).
+		Select(r.statusSelectSQL()).
+		Joins("LEFT JOIN mission_subcategories msc ON msc.id = missions.subtype_id").
+		Preload("MissionSubCategory").
+		Preload("Flight").
+		Preload("Files").
+		Preload("Files.FileAttachment").
+		Preload("Files.FileAttachment.File").
+		Where("missions.id = ? AND missions.deleted_at IS NULL", missionID).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &row, nil
+}
+
+func (r *MissionRepository) GetByFlightID(ctx context.Context, flightID []byte) (*mission.Mission, error) {
+	var row mission.Mission
+	err := r.db.WithContext(ctx).
+		Select(r.statusSelectSQL()).
+		Joins("LEFT JOIN mission_subcategories msc ON msc.id = missions.subtype_id").
+		Preload("MissionSubCategory").
+		Preload("Flight").
+		Preload("Files").
+		Preload("Files.FileAttachment").
+		Preload("Files.FileAttachment.File").
+		Where("missions.flight_id = ? AND missions.deleted_at IS NULL", flightID).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &row, nil
+}
+
+func (r *MissionRepository) List(ctx context.Context, filter, sort string, flightID []byte, flightDataStatus string, limit, offset int) ([]mission.Mission, int64, error) {
+	rows, total, _, err := r.listWithFilter(ctx, mission.ListFilter{
+		Search:           filter,
+		Sort:             sort,
+		FlightID:         flightID,
+		FlightDataStatus: flightDataStatus,
+	}, limit, offset, false)
+	return rows, total, err
+}
+
+func (r *MissionRepository) ListDatatable(ctx context.Context, filter mission.ListFilter, limit, offset int) ([]mission.Mission, int64, int64, error) {
+	return r.listWithFilter(ctx, filter, limit, offset, true)
+}
+
+func (r *MissionRepository) statusSelectSQL() string {
+	return `missions.*,
+		COALESCE((
+			SELECT flight_data.id
+			FROM flight_data
+			WHERE flight_data.mission_id = missions.id
+				AND flight_data.deleted_at IS NULL
+			ORDER BY flight_data.created_at DESC, flight_data.id DESC
+			LIMIT 1
+		), missions.flight_data_id) AS flight_data_id,
+		` + r.flightDataStatusExprSQL() + ` AS flight_data_status`
+}
+
+func (r *MissionRepository) flightDataStatusExprSQL() string {
+	completeCondition := `(
+		flight_data.take_off IS NOT NULL
+		AND flight_data.landing IS NOT NULL
+		AND flight_data.duration > 0
+		AND flight_data.red > 0
+		AND flight_data.max_n1 > 0
+		AND flight_data.max_n2 > 0
+		AND flight_data.pax_count > 0
+		AND flight_data.landing_count > 0
+		AND flight_data.rotor_brake_cycle > 0
+		AND COALESCE(flight_data.ticket_no, '') <> ''
+		AND COALESCE(flight_data.engine, '') <> ''
+		AND COALESCE(flight_data.delivery_note_number, '') <> ''
+		AND COALESCE(flight_data.customer_name, '') <> ''
+		AND flight_data.flight_plan_distance > 0
+		AND flight_data.flight_plan_time > 0
+		AND flight_data.flight_plan_true_course > 0
+		AND flight_data.fuel_before_flight > 0
+		AND flight_data.fuel_upload > 0
+		AND flight_data.fuel_after_flight > 0
+		AND flight_data.fuel_planning > 0
+		AND COALESCE(flight_data.other_information, '') <> ''
+	)`
+	return `COALESCE((
+		SELECT CASE
+			WHEN COUNT(flight_data.id) = 0 THEN 'draft'
+			WHEN SUM(CASE WHEN ` + completeCondition + ` THEN 1 ELSE 0 END) = 0 THEN 'draft'
+			WHEN SUM(CASE WHEN ` + completeCondition + ` THEN 1 ELSE 0 END) = COUNT(flight_data.id) THEN 'completed'
+			ELSE 'in_progress'
+		END
+		FROM flight_data
+		WHERE flight_data.mission_id = missions.id
+			AND flight_data.deleted_at IS NULL
+	), 'draft')`
+}
+
+func (r *MissionRepository) listWithFilter(ctx context.Context, filter mission.ListFilter, limit, offset int, includeUnfilteredTotal bool) ([]mission.Mission, int64, int64, error) {
+	rows := make([]mission.Mission, 0)
+	var total int64
+	var filteredTotal int64
+
+	base := r.db.WithContext(ctx).
+		Model(&mission.Mission{}).
+		Joins("LEFT JOIN flights ON flights.id = missions.flight_id").
+		Joins("LEFT JOIN mission_subcategories msc ON msc.id = missions.subtype_id").
+		Where("missions.deleted_at IS NULL")
+
+	if includeUnfilteredTotal {
+		if err := base.Session(&gorm.Session{}).Count(&total).Error; err != nil {
+			return nil, 0, 0, err
+		}
+	} else {
+		total = 0
+	}
+
+	base = r.applyMissionListFilter(base, filter)
+
+	countQuery := base.Session(&gorm.Session{})
+	if err := countQuery.Count(&filteredTotal).Error; err != nil {
+		return nil, 0, 0, err
+	}
+
+	query := base.Session(&gorm.Session{}).
+		Select(r.statusSelectSQL()).
+		Preload("MissionSubCategory").
+		Preload("Flight").
+		Preload("Files").
+		Preload("Files.FileAttachment").
+		Preload("Files.FileAttachment.File")
+	if filter.Sort != "" {
+		query = query.Order(filter.Sort)
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, 0, err
+	}
+
+	if !includeUnfilteredTotal {
+		total = filteredTotal
+	}
+	return rows, total, filteredTotal, nil
+}
+
+func (r *MissionRepository) applyMissionListFilter(query *gorm.DB, filter mission.ListFilter) *gorm.DB {
+	if filter.Search != "" {
+		like := "%" + filter.Search + "%"
+		query = query.Where(
+			"missions.type LIKE ? OR flights.mission_code LIKE ? OR DATE_FORMAT(flights.date, '%Y-%m-%d') LIKE ?",
+			like, like, like,
+		)
+	}
+	if len(filter.FlightID) == 16 {
+		query = query.Where("missions.flight_id = ?", filter.FlightID)
+	}
+	if filter.FlightDataStatus != "" {
+		query = query.Where(r.flightDataStatusExprSQL()+" = ?", filter.FlightDataStatus)
+	}
+	if filter.MissionType != "" {
+		query = query.Where("missions.type = ?", strings.ToUpper(strings.TrimSpace(filter.MissionType)))
+	}
+	if filter.StartDate != nil {
+		query = query.Where("flights.date >= ?", filter.StartDate.UTC().Format("2006-01-02"))
+	}
+	if filter.EndDate != nil {
+		query = query.Where("flights.date <= ?", filter.EndDate.UTC().Format("2006-01-02"))
+	}
+	if len(filter.PilotID) == 16 {
+		query = query.Where(`
+			EXISTS (
+				SELECT 1
+				FROM duty_rosters dr
+				JOIN duty_roster_crews c ON c.roster_id = dr.id
+				WHERE dr.flight_id = missions.flight_id
+					AND dr.deleted_at IS NULL
+					AND c.deleted_at IS NULL
+					AND c.role_code = 'pilot'
+					AND c.user_id = ?
+			)`, filter.PilotID)
+	}
+	if len(filter.HelicopterID) == 16 {
+		query = query.Where(`
+			EXISTS (
+				SELECT 1
+				FROM takeover_acs ta
+				JOIN reserve_acs ra ON ra.id = ta.reserve_ac_id
+					WHERE ta.id = flights.takeover_ac_id
+						AND ta.deleted_at IS NULL
+						AND ra.deleted_at IS NULL
+						AND ra.helicopter_id = ?
+			)`, filter.HelicopterID)
+	}
+	return query
+}
+
+func normalizeMissionTimeForDB(row *mission.Mission) {
+	if row == nil {
+		return
+	}
+	row.StartTime = normalizeMissionDBClock(row.StartTime)
+	row.EndTime = normalizeMissionDBClock(row.EndTime)
+}
+
+func normalizeMissionDBClock(raw string) string {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" {
+		return ""
+	}
+	if len(trimmed) == 5 {
+		return trimmed + ":00"
+	}
+	if len(trimmed) == 8 {
+		return trimmed
+	}
+	if parsed, err := time.Parse("15:04", trimmed); err == nil {
+		return parsed.Format("15:04:05")
+	}
+	if parsed, err := time.Parse("15:04:05", trimmed); err == nil {
+		return parsed.Format("15:04:05")
+	}
+	return trimmed
+}
+
+func (r *MissionRepository) ListCategoriesWithSubCategories(ctx context.Context) ([]mission.MissionCategory, error) {
+	var rows []mission.MissionCategory
+	if err := r.db.WithContext(ctx).
+		Preload("SubCategory", func(db *gorm.DB) *gorm.DB {
+			return db.Order("sub_type ASC")
+		}).
+		Order("code_type ASC").
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+
+	for i := range rows {
+		rows[i].CodeType = strings.TrimSpace(rows[i].CodeType)
+		rows[i].TypeName = strings.TrimSpace(rows[i].TypeName)
+		for j := range rows[i].SubCategory {
+			rows[i].SubCategory[j].SubCodeType = strings.TrimSpace(rows[i].SubCategory[j].SubCodeType)
+			rows[i].SubCategory[j].SubTypeName = strings.TrimSpace(rows[i].SubCategory[j].SubTypeName)
+			rows[i].SubCategory[j].TaskName = strings.TrimSpace(rows[i].SubCategory[j].TaskName)
+		}
+	}
+
+	return rows, nil
+}
+
+func (r *MissionRepository) FindCategoryByCode(ctx context.Context, code string) (*mission.MissionCategory, error) {
+	var row mission.MissionCategory
+	err := r.db.WithContext(ctx).
+		Where("code_type = ?", code).
+		Take(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &row, nil
+}
+
+func (r *MissionRepository) SubCategoryBelongsToCategory(ctx context.Context, subCategoryID, categoryID []byte) (bool, error) {
+	if len(subCategoryID) != 16 || len(categoryID) != 16 {
+		return false, nil
+	}
+	var cnt int64
+	if err := r.db.WithContext(ctx).
+		Table("mission_subcategories").
+		Where("id = ? AND mission_category_id = ?", subCategoryID, categoryID).
+		Count(&cnt).Error; err != nil {
+		return false, err
+	}
+	return cnt > 0, nil
+}
diff --git a/internal/repository/mysql/opc_repo.go b/internal/repository/mysql/opc_repo.go
new file mode 100644
index 0000000..3289448
--- /dev/null
+++ b/internal/repository/mysql/opc_repo.go
@@ -0,0 +1,88 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/opc"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type OpcRepository struct {
+	db *gorm.DB
+}
+
+func NewOpcRepository(db *gorm.DB) *OpcRepository {
+	return &OpcRepository{db: db}
+}
+
+func (r *OpcRepository) Create(ctx context.Context, o *opc.Opc) error {
+	requestedIsActive := o.IsActive
+	db := r.db.WithContext(ctx)
+	if err := db.Create(o).Error; err != nil {
+		return err
+	}
+	return db.Model(&opc.Opc{}).Where("id = ?", o.ID).UpdateColumn("is_active", requestedIsActive).Error
+}
+
+func (r *OpcRepository) Update(ctx context.Context, o *opc.Opc) error {
+	return r.db.WithContext(ctx).Save(o).Error
+}
+
+func (r *OpcRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "hems_opcs", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&opc.Opc{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error)
+}
+
+func (r *OpcRepository) GetByID(ctx context.Context, id []byte) (*opc.Opc, error) {
+	var row opc.Opc
+	err := r.db.WithContext(ctx).Where("id = ? AND deleted_at IS NULL", id).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *OpcRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]opc.Opc, int64, error) {
+	var rows []opc.Opc
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&opc.Opc{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("name LIKE ? OR note LIKE ?", like, like)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("hems_opcs", "is_active", "sortkey", "name", false) {
+			query = query.Order(clause)
+		}
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/opc_repo_test.go b/internal/repository/mysql/opc_repo_test.go
new file mode 100644
index 0000000..6d763d5
--- /dev/null
+++ b/internal/repository/mysql/opc_repo_test.go
@@ -0,0 +1,238 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/opc"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openOpcTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:opc_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&opc.Opc{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestNewOpcRepository(t *testing.T) {
+	db := openOpcTestDB(t)
+	repo := NewOpcRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestOpcRepositoryCreate(t *testing.T) {
+	db := openOpcTestDB(t)
+	repo := NewOpcRepository(db)
+	row := &opc.Opc{Title: "Main"}
+
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(row.ID) == 0 {
+		t.Fatalf("expected id set")
+	}
+	inactive := &opc.Opc{Title: "Inactive", IsActive: false}
+	if err := repo.Create(context.Background(), inactive); err != nil {
+		t.Fatalf("create inactive: %v", err)
+	}
+	gotInactive, err := repo.GetByID(context.Background(), inactive.ID)
+	if err != nil {
+		t.Fatalf("get inactive: %v", err)
+	}
+	if gotInactive == nil || gotInactive.IsActive {
+		t.Fatalf("expected inactive opc persisted as false")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Create(context.Background(), &opc.Opc{Title: "AfterClose"}); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestOpcRepositoryUpdate(t *testing.T) {
+	db := openOpcTestDB(t)
+	repo := NewOpcRepository(db)
+	row := &opc.Opc{Title: "Old"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Title = "New"
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil || loaded == nil || loaded.Title != "New" {
+		t.Fatalf("expected updated row")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestOpcRepositoryDelete(t *testing.T) {
+	db := openOpcTestDB(t)
+	repo := NewOpcRepository(db)
+	row := &opc.Opc{Title: "DeleteMe"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	deletedBy := uuidv7.MustBytes()
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected soft deleted row hidden from GetByID")
+	}
+}
+
+func TestOpcRepositoryGetByID(t *testing.T) {
+	t.Run("found", func(t *testing.T) {
+		db := openOpcTestDB(t)
+		repo := NewOpcRepository(db)
+		row := &opc.Opc{Title: "Found"}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		got, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.Title != "Found" {
+			t.Fatalf("expected row found")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openOpcTestDB(t)
+		repo := NewOpcRepository(db)
+		got, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil for not found")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openOpcTestDB(t)
+		repo := NewOpcRepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, err := repo.GetByID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
+
+func TestOpcRepositoryList(t *testing.T) {
+	t.Run("success without limit", func(t *testing.T) {
+		db := openOpcTestDB(t)
+		repo := NewOpcRepository(db)
+		_ = repo.Create(context.Background(), &opc.Opc{Title: "C"})
+		_ = repo.Create(context.Background(), &opc.Opc{Title: "A"})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("expected 2 rows, total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("success with filter sort and limit", func(t *testing.T) {
+		db := openOpcTestDB(t)
+		repo := NewOpcRepository(db)
+		_ = repo.Create(context.Background(), &opc.Opc{Title: "Main Base"})
+		_ = repo.Create(context.Background(), &opc.Opc{Title: "Backup"})
+
+		rows, total, err := repo.List(context.Background(), "Main", "name DESC", 1, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].Title != "Main Base" {
+			t.Fatalf("unexpected list result")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openOpcTestDB(t)
+		repo := NewOpcRepository(db)
+		if err := db.Migrator().DropTable(&opc.Opc{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+
+		if _, _, err := repo.List(context.Background(), "", "", 10, 0); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openOpcTestDB(t)
+		repo := NewOpcRepository(db)
+		_ = repo.Create(context.Background(), &opc.Opc{Title: "Main"})
+
+		if _, _, err := repo.List(context.Background(), "", "name ASC, )", 10, 0); err == nil {
+			t.Fatalf("expected find error from invalid sort")
+		}
+	})
+
+	t.Run("default order active sortkey first and inactive last", func(t *testing.T) {
+		db := openOpcTestDB(t)
+		repo := NewOpcRepository(db)
+		_ = repo.Create(context.Background(), &opc.Opc{Title: "Gamma", IsActive: true})
+		_ = repo.Create(context.Background(), &opc.Opc{Title: "Beta", SortKey: intPtrOpcRepo(0), IsActive: true})
+		_ = repo.Create(context.Background(), &opc.Opc{Title: "Charlie", SortKey: intPtrOpcRepo(2), IsActive: true})
+		_ = repo.Create(context.Background(), &opc.Opc{Title: "Alpha", SortKey: intPtrOpcRepo(1), IsActive: true})
+		_ = repo.Create(context.Background(), &opc.Opc{Title: "Zulu", IsActive: false})
+		_ = repo.Create(context.Background(), &opc.Opc{Title: "Bravo", SortKey: intPtrOpcRepo(9), IsActive: false})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 6 || len(rows) != 6 {
+			t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+		}
+
+		gotOrder := []string{rows[0].Title, rows[1].Title, rows[2].Title, rows[3].Title, rows[4].Title, rows[5].Title}
+		wantOrder := []string{"Beta", "Alpha", "Charlie", "Gamma", "Bravo", "Zulu"}
+		for i := range wantOrder {
+			if gotOrder[i] != wantOrder[i] {
+				t.Fatalf("unexpected default order: got=%v want=%v", gotOrder, wantOrder)
+			}
+		}
+	})
+}
+
+func intPtrOpcRepo(v int) *int { return &v }
diff --git a/internal/repository/mysql/other_person_repo.go b/internal/repository/mysql/other_person_repo.go
new file mode 100644
index 0000000..ff08c0d
--- /dev/null
+++ b/internal/repository/mysql/other_person_repo.go
@@ -0,0 +1,114 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	otherperson "wucher/internal/domain/other_person"
+)
+
+type OtherPersonRepository struct{ db *gorm.DB }
+
+func NewOtherPersonRepository(db *gorm.DB) *OtherPersonRepository {
+	return &OtherPersonRepository{db: db}
+}
+
+func (r *OtherPersonRepository) Create(ctx context.Context, p *otherperson.OtherPerson) error {
+	p.Name = strings.TrimSpace(p.Name)
+	p.MobilePhone = strings.TrimSpace(p.MobilePhone)
+	p.Email = strings.TrimSpace(p.Email)
+	return r.db.WithContext(ctx).Create(p).Error
+}
+
+func (r *OtherPersonRepository) Update(ctx context.Context, p *otherperson.OtherPerson) error {
+	return r.db.WithContext(ctx).
+		Model(&otherperson.OtherPerson{}).
+		Where("id = ? AND deleted_at IS NULL", p.ID).
+		Updates(map[string]any{
+			"name":         strings.TrimSpace(p.Name),
+			"mobile_phone": strings.TrimSpace(p.MobilePhone),
+			"email":        strings.TrimSpace(p.Email),
+			"updated_by":   p.UpdatedBy,
+		}).Error
+}
+
+func (r *OtherPersonRepository) Delete(ctx context.Context, id, deletedBy []byte) error {
+	return r.db.WithContext(ctx).
+		Model(&otherperson.OtherPerson{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(map[string]any{
+			"deleted_at": time.Now().UTC(),
+			"deleted_by": deletedBy,
+		}).Error
+}
+
+func (r *OtherPersonRepository) FindByIdentity(ctx context.Context, name, phone, email string) (*otherperson.OtherPerson, error) {
+	var row otherperson.OtherPerson
+	err := r.db.WithContext(ctx).
+		Where("name = ? AND mobile_phone = ? AND email = ? AND deleted_at IS NULL",
+			strings.TrimSpace(name), strings.TrimSpace(phone), strings.TrimSpace(email)).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *OtherPersonRepository) Upsert(ctx context.Context, p *otherperson.OtherPerson) error {
+	name := strings.TrimSpace(p.Name)
+	phone := strings.TrimSpace(p.MobilePhone)
+	email := strings.TrimSpace(p.Email)
+
+	var existing otherperson.OtherPerson
+	err := r.db.WithContext(ctx).
+		Where("name = ? AND mobile_phone = ? AND email = ? AND deleted_at IS NULL", name, phone, email).
+		First(&existing).Error
+	if err == nil {
+		p.ID = existing.ID
+		p.Name, p.MobilePhone, p.Email = existing.Name, existing.MobilePhone, existing.Email
+		return nil
+	}
+	if !errors.Is(err, gorm.ErrRecordNotFound) {
+		return err
+	}
+	p.Name, p.MobilePhone, p.Email = name, phone, email
+	return r.db.WithContext(ctx).Create(p).Error
+}
+
+func (r *OtherPersonRepository) GetByID(ctx context.Context, id []byte) (*otherperson.OtherPerson, error) {
+	var row otherperson.OtherPerson
+	err := r.db.WithContext(ctx).
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *OtherPersonRepository) Search(ctx context.Context, q string, limit, offset int) ([]otherperson.OtherPerson, int64, error) {
+	rows := make([]otherperson.OtherPerson, 0)
+	base := r.db.WithContext(ctx).
+		Model(&otherperson.OtherPerson{}).
+		Where("deleted_at IS NULL")
+	if s := strings.TrimSpace(q); s != "" {
+		like := "%" + s + "%"
+		base = base.Where("name LIKE ? OR mobile_phone LIKE ? OR email LIKE ?", like, like, like)
+	}
+	var total int64
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit <= 0 {
+		limit = 20
+	}
+	err := base.Order("created_at DESC").
+		Limit(limit).
+		Offset(offset).
+		Find(&rows).Error
+	return rows, total, err
+}
diff --git a/internal/repository/mysql/other_person_repo_test.go b/internal/repository/mysql/other_person_repo_test.go
new file mode 100644
index 0000000..e378f45
--- /dev/null
+++ b/internal/repository/mysql/other_person_repo_test.go
@@ -0,0 +1,176 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	otherperson "wucher/internal/domain/other_person"
+)
+
+func openOtherPersonTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:other_person_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&otherperson.OtherPerson{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestOtherPersonRepositoryUpsertDedup(t *testing.T) {
+	db := openOtherPersonTestDB(t)
+	repo := NewOtherPersonRepository(db)
+	ctx := context.Background()
+
+	first := &otherperson.OtherPerson{Name: "  Guest One ", MobilePhone: " +43-1 ", Email: " a@x.io "}
+	if err := repo.Upsert(ctx, first); err != nil {
+		t.Fatalf("first upsert: %v", err)
+	}
+	if len(first.ID) == 0 {
+		t.Fatalf("expected id set on create")
+	}
+	// values should be trimmed on create.
+	if first.Name != "Guest One" || first.MobilePhone != "+43-1" || first.Email != "a@x.io" {
+		t.Fatalf("expected trimmed values, got %q/%q/%q", first.Name, first.MobilePhone, first.Email)
+	}
+
+	// Same identity (even with different whitespace) must reuse the existing row, not create a new one.
+	second := &otherperson.OtherPerson{Name: "Guest One", MobilePhone: "+43-1", Email: "a@x.io"}
+	if err := repo.Upsert(ctx, second); err != nil {
+		t.Fatalf("second upsert: %v", err)
+	}
+	if string(second.ID) != string(first.ID) {
+		t.Fatalf("expected reuse of existing id")
+	}
+
+	// A different identity creates a new row.
+	third := &otherperson.OtherPerson{Name: "Guest Two", MobilePhone: "+43-2", Email: "b@x.io"}
+	if err := repo.Upsert(ctx, third); err != nil {
+		t.Fatalf("third upsert: %v", err)
+	}
+	if string(third.ID) == string(first.ID) {
+		t.Fatalf("expected new id for distinct identity")
+	}
+
+	_, total, err := repo.Search(ctx, "", 0, 0)
+	if err != nil {
+		t.Fatalf("search: %v", err)
+	}
+	if total != 2 {
+		t.Fatalf("expected 2 master rows, got %d", total)
+	}
+}
+
+func TestOtherPersonRepositorySearch(t *testing.T) {
+	db := openOtherPersonTestDB(t)
+	repo := NewOtherPersonRepository(db)
+	ctx := context.Background()
+
+	for _, p := range []*otherperson.OtherPerson{
+		{Name: "Alice Anderson", MobilePhone: "111", Email: "alice@x.io"},
+		{Name: "Bob Brown", MobilePhone: "222", Email: "bob@x.io"},
+	} {
+		if err := repo.Upsert(ctx, p); err != nil {
+			t.Fatalf("seed: %v", err)
+		}
+	}
+
+	rows, total, err := repo.Search(ctx, "alice", 0, 0)
+	if err != nil {
+		t.Fatalf("search by name: %v", err)
+	}
+	if total != 1 || len(rows) != 1 || rows[0].Name != "Alice Anderson" {
+		t.Fatalf("expected only Alice, got total=%d rows=%d", total, len(rows))
+	}
+
+	// Match on email fragment too.
+	rows, total, err = repo.Search(ctx, "bob@", 0, 0)
+	if err != nil {
+		t.Fatalf("search by email: %v", err)
+	}
+	if total != 1 || len(rows) != 1 || rows[0].Name != "Bob Brown" {
+		t.Fatalf("expected only Bob, got total=%d rows=%d", total, len(rows))
+	}
+
+	// Empty query returns everything.
+	_, total, err = repo.Search(ctx, "  ", 0, 0)
+	if err != nil {
+		t.Fatalf("search empty: %v", err)
+	}
+	if total != 2 {
+		t.Fatalf("expected 2 rows for empty query, got %d", total)
+	}
+}
+
+func TestOtherPersonRepositoryCreateUpdateDelete(t *testing.T) {
+	db := openOtherPersonTestDB(t)
+	repo := NewOtherPersonRepository(db)
+	ctx := context.Background()
+
+	row := &otherperson.OtherPerson{Name: "  Carol  ", MobilePhone: " 333 ", Email: " carol@x.io "}
+	if err := repo.Create(ctx, row); err != nil {
+		t.Fatalf("create: %v", err)
+	}
+	if len(row.ID) == 0 || row.Name != "Carol" {
+		t.Fatalf("expected trimmed create with id, got %q id=%d", row.Name, len(row.ID))
+	}
+
+	// FindByIdentity trims and matches.
+	found, err := repo.FindByIdentity(ctx, "Carol", "333", "carol@x.io")
+	if err != nil {
+		t.Fatalf("find identity: %v", err)
+	}
+	if found == nil || string(found.ID) != string(row.ID) {
+		t.Fatalf("expected to find created row")
+	}
+	miss, err := repo.FindByIdentity(ctx, "Nobody", "", "")
+	if err != nil {
+		t.Fatalf("find miss: %v", err)
+	}
+	if miss != nil {
+		t.Fatalf("expected nil for missing identity")
+	}
+
+	// Update replaces identity fields.
+	row.Name = "Caroline"
+	row.Email = "caroline@x.io"
+	if err := repo.Update(ctx, row); err != nil {
+		t.Fatalf("update: %v", err)
+	}
+	got, err := repo.GetByID(ctx, row.ID)
+	if err != nil {
+		t.Fatalf("get after update: %v", err)
+	}
+	if got == nil || got.Name != "Caroline" || got.Email != "caroline@x.io" {
+		t.Fatalf("update not persisted: %+v", got)
+	}
+
+	// Delete soft-deletes: GetByID/Search no longer return it.
+	if err := repo.Delete(ctx, row.ID, nil); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+	got, err = repo.GetByID(ctx, row.ID)
+	if err != nil {
+		t.Fatalf("get after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected soft-deleted row to be hidden")
+	}
+	_, total, err := repo.Search(ctx, "", 0, 0)
+	if err != nil {
+		t.Fatalf("search after delete: %v", err)
+	}
+	if total != 0 {
+		t.Fatalf("expected 0 live rows after delete, got %d", total)
+	}
+}
diff --git a/internal/repository/mysql/patient_data_repo.go b/internal/repository/mysql/patient_data_repo.go
new file mode 100644
index 0000000..b2ca750
--- /dev/null
+++ b/internal/repository/mysql/patient_data_repo.go
@@ -0,0 +1,89 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	patientdata "wucher/internal/domain/patient_data"
+)
+
+type PatientDataRepository struct {
+	db *gorm.DB
+}
+
+func NewPatientDataRepository(db *gorm.DB) *PatientDataRepository {
+	return &PatientDataRepository{db: db}
+}
+
+func (r *PatientDataRepository) Create(ctx context.Context, row *patientdata.PatientData) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *PatientDataRepository) Update(ctx context.Context, row *patientdata.PatientData) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *PatientDataRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return r.db.WithContext(ctx).
+		Model(&patientdata.PatientData{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error
+}
+
+func (r *PatientDataRepository) GetByID(ctx context.Context, id []byte) (*patientdata.PatientData, error) {
+	var row patientdata.PatientData
+	err := r.db.WithContext(ctx).
+		Preload("OPC", "deleted_at IS NULL").
+		Preload("InsurancePatientData", "deleted_at IS NULL").
+		Preload("InsurancePatientData.HealthInsuranceCompanies", "deleted_at IS NULL").
+		Preload("InsurancePatientData.FederalState", "deleted_at IS NULL").
+		Where("patient_data.id = ? AND patient_data.deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *PatientDataRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]patientdata.PatientData, int64, error) {
+	var rows []patientdata.PatientData
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&patientdata.PatientData{}).Where("patient_data.deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where(
+			"family_name LIKE ? OR first_name LIKE ? OR svnr LIKE ? OR email LIKE ? OR phone LIKE ? OR street LIKE ?",
+			like, like, like, like, like, like,
+		)
+	}
+
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	query := base.
+		Preload("OPC", "deleted_at IS NULL").
+		Preload("InsurancePatientData", "deleted_at IS NULL").
+		Preload("InsurancePatientData.HealthInsuranceCompanies", "deleted_at IS NULL").
+		Preload("InsurancePatientData.FederalState", "deleted_at IS NULL")
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/reserve_ac_repo.go b/internal/repository/mysql/reserve_ac_repo.go
new file mode 100644
index 0000000..f85943b
--- /dev/null
+++ b/internal/repository/mysql/reserve_ac_repo.go
@@ -0,0 +1,300 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	flightinspection "wucher/internal/domain/flight_inspection"
+	"wucher/internal/domain/helicopter"
+	reserveac "wucher/internal/domain/reserve_ac"
+	"wucher/internal/shared/pkg/uuidv7"
+	shareddto "wucher/internal/transport/http/dto/shared"
+)
+
+type ReserveAcRepository struct {
+	db *gorm.DB
+}
+
+func NewReserveAcRepository(db *gorm.DB) *ReserveAcRepository {
+	return &ReserveAcRepository{db: db}
+}
+
+func (r *ReserveAcRepository) Create(ctx context.Context, row *reserveac.ReserveAc) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *ReserveAcRepository) Update(ctx context.Context, row *reserveac.ReserveAc) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *ReserveAcRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	res := r.db.WithContext(ctx).
+		Model(&reserveac.ReserveAc{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates)
+	if res.Error != nil {
+		return res.Error
+	}
+	if res.RowsAffected == 0 {
+		return gorm.ErrRecordNotFound
+	}
+	return nil
+}
+
+func (r *ReserveAcRepository) GetByID(ctx context.Context, id []byte) (*reserveac.ReserveAc, error) {
+	var row reserveac.ReserveAc
+	err := r.db.WithContext(ctx).
+		Preload("Aircraft").
+		Preload("Inspection").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *ReserveAcRepository) GetActiveByInspectionID(ctx context.Context, inspectionID []byte) (*reserveac.ReserveAc, error) {
+	if len(inspectionID) != 16 {
+		return nil, nil
+	}
+	var row reserveac.ReserveAc
+	err := r.db.WithContext(ctx).
+		Preload("Aircraft").
+		Preload("Inspection").
+		Where("inspection_id = ? AND deleted_at IS NULL", inspectionID).
+		Limit(1).
+		Find(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	if len(row.ID) == 0 {
+		return nil, nil
+	}
+	return &row, nil
+}
+
+func (r *ReserveAcRepository) List(ctx context.Context, filter string, sort string, limit, offset int) ([]reserveac.ReserveAc, int64, error) {
+	rows := make([]reserveac.ReserveAc, 0)
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&reserveac.ReserveAc{}).Where("deleted_at IS NULL")
+	if strings.TrimSpace(filter) != "" {
+		like := "%" + strings.ToLower(strings.TrimSpace(filter)) + "%"
+		base = base.Where(
+			"LOWER(status) LIKE ? OR LOWER(HEX(id)) LIKE ? OR LOWER(HEX(helicopter_id)) LIKE ? OR LOWER(HEX(inspection_id)) LIKE ?",
+			like, like, like, like,
+		)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func (r *ReserveAcRepository) AircraftExists(ctx context.Context, helicopterID []byte) (bool, error) {
+	if len(helicopterID) != 16 {
+		return false, nil
+	}
+	var total int64
+	err := r.db.WithContext(ctx).
+		Model(&helicopter.Helicopter{}).
+		Where("id = ?", helicopterID).
+		Count(&total).Error
+	return total > 0, err
+}
+
+func (r *ReserveAcRepository) FlightInspectionExists(ctx context.Context, inspectionID []byte) (bool, error) {
+	if len(inspectionID) != 16 {
+		return false, nil
+	}
+	var total int64
+	err := r.db.WithContext(ctx).
+		Model(&flightinspection.FlightInspection{}).
+		Where("id = ?", inspectionID).
+		Count(&total).Error
+	return total > 0, err
+}
+
+func (r *ReserveAcRepository) ExistsActiveByInspectionID(ctx context.Context, inspectionID []byte, excludeID []byte) (bool, error) {
+	if len(inspectionID) != 16 {
+		return false, nil
+	}
+	var total int64
+	q := r.db.WithContext(ctx).
+		Model(&reserveac.ReserveAc{}).
+		Where("inspection_id = ? AND deleted_at IS NULL", inspectionID)
+	if len(excludeID) == 16 {
+		q = q.Where("id <> ?", excludeID)
+	}
+	if err := q.Count(&total).Error; err != nil {
+		return false, err
+	}
+	return total > 0, nil
+}
+
+func (r *ReserveAcRepository) GetLastDailyInspectionByHelicopterID(ctx context.Context, helicopterID []byte) (*shareddto.LastDailyInspection, error) {
+	if len(helicopterID) != 16 {
+		return nil, nil
+	}
+
+	type row struct {
+		ID        []byte    `gorm:"column:id"`
+		Name      string    `gorm:"column:name"`
+		ShortName string    `gorm:"column:short_name"`
+		At        time.Time `gorm:"column:inspected_at"`
+	}
+	var out row
+	err := r.db.WithContext(ctx).
+		Table("reserve_acs ra").
+		Select(`
+			fi.id AS id,
+			TRIM(CONCAT(COALESCE(u.first_name, ''), ' ', COALESCE(u.last_name, ''))) AS name,
+			COALESCE(NULLIF(pp.short_name, ''), NULLIF(tp.short_name, ''), '') AS short_name,
+			COALESCE(afi.updated_at, fpc.updated_at, bfi.updated_at) AS inspected_at`).
+		Joins("JOIN flight_inspections fi ON fi.id = ra.inspection_id").
+		Joins("LEFT JOIN before_flight_inspections bfi ON bfi.flight_inspection_id = fi.id").
+		Joins("LEFT JOIN flight_prep_checks fpc ON fpc.flight_inspection_id = fi.id").
+		Joins("LEFT JOIN after_flight_inspections afi ON afi.flight_inspection_id = fi.id").
+		Joins(`JOIN users u ON u.id = CASE
+			WHEN afi.updated_at IS NOT NULL THEN afi.updated_by
+			WHEN fpc.updated_at IS NOT NULL THEN fpc.updated_by
+			WHEN bfi.updated_at IS NOT NULL THEN bfi.updated_by
+			ELSE NULL
+		END`).
+		Joins("LEFT JOIN pilot_profiles pp ON pp.user_id = u.id").
+		Joins("LEFT JOIN technician_profiles tp ON tp.user_id = u.id").
+		Where("ra.helicopter_id = ? AND ra.deleted_at IS NULL", helicopterID).
+		Where("COALESCE(afi.updated_at, fpc.updated_at, bfi.updated_at) IS NOT NULL").
+		Order("fi.inspection_date DESC").
+		Order("COALESCE(afi.updated_at, fpc.updated_at, bfi.updated_at) DESC").
+		Limit(1).
+		Take(&out).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &shareddto.LastDailyInspection{
+		ID:        out.ID,
+		Name:      strings.TrimSpace(out.Name),
+		ShortName: strings.TrimSpace(out.ShortName),
+		At:        out.At.UTC(),
+	}, nil
+}
+
+func (r *ReserveAcRepository) GetLastDailyInspectionSummaryByHelicopterID(ctx context.Context, helicopterID []byte) (*shareddto.LastDailyInspectionSummary, error) {
+	if len(helicopterID) != 16 {
+		return nil, nil
+	}
+
+	type row struct {
+		InspectionID       []byte    `gorm:"column:inspection_id"`
+		InspectorID        []byte    `gorm:"column:inspector_id"`
+		InspectorName      string    `gorm:"column:inspector_name"`
+		InspectorLicenseNo string    `gorm:"column:inspector_license_no"`
+		BaseID             []byte    `gorm:"column:base_id"`
+		BaseName           string    `gorm:"column:base_name"`
+		BaseAbbreviation   string    `gorm:"column:base_abbreviation"`
+		BaseType           string    `gorm:"column:base_type"`
+		InspectedAt        time.Time `gorm:"column:inspected_at"`
+		CompletedCount     int       `gorm:"column:completed_count"`
+		TotalCount         int       `gorm:"column:total_count"`
+	}
+	var out row
+	err := r.db.WithContext(ctx).
+		Table("reserve_acs ra").
+		Select(`
+			ra.inspection_id AS inspection_id,
+			COALESCE(u.id, ra.updated_by) AS inspector_id,
+			COALESCE(
+				NULLIF(TRIM(CONCAT(COALESCE(u.first_name, ''), ' ', COALESCE(u.last_name, ''))), ''),
+				NULLIF(TRIM(u.username), ''),
+				NULLIF(TRIM(u.email), ''),
+				''
+			) AS inspector_name,
+			COALESCE(NULLIF(pp.license_no, ''), NULLIF(tp.license_no, ''), '') AS inspector_license_no,
+			ra.base_id AS base_id,
+			COALESCE(TRIM(b.base), '') AS base_name,
+			COALESCE(TRIM(b.base_abbreviation), '') AS base_abbreviation,
+			COALESCE(NULLIF(LOWER(bc.key), ''), 'base') AS base_type,
+			COALESCE(afi.updated_at, fpc.updated_at, bfi.updated_at, ra.updated_at) AS inspected_at,
+			(
+				SELECT COUNT(*)
+				FROM flight_inspection_file_checklists fic
+				WHERE fic.flight_inspection_id = fi.id
+			) AS total_count,
+			(
+				SELECT COUNT(*)
+				FROM flight_inspection_file_checklists fic
+				WHERE fic.flight_inspection_id = fi.id AND fic.is_done = 1
+			) AS completed_count
+		`).
+		Joins("JOIN flight_inspections fi ON fi.id = ra.inspection_id").
+		Joins("LEFT JOIN before_flight_inspections bfi ON bfi.flight_inspection_id = fi.id").
+		Joins("LEFT JOIN flight_prep_checks fpc ON fpc.flight_inspection_id = fi.id").
+		Joins("LEFT JOIN after_flight_inspections afi ON afi.flight_inspection_id = fi.id").
+		Joins(`LEFT JOIN users u ON u.id = CASE
+			WHEN afi.updated_at IS NOT NULL THEN afi.updated_by
+			WHEN fpc.updated_at IS NOT NULL THEN fpc.updated_by
+			WHEN bfi.updated_at IS NOT NULL THEN bfi.updated_by
+			ELSE ra.updated_by
+		END`).
+		Joins("LEFT JOIN pilot_profiles pp ON pp.user_id = u.id").
+		Joins("LEFT JOIN technician_profiles tp ON tp.user_id = u.id").
+		Joins("LEFT JOIN bases b ON b.id = ra.base_id AND b.deleted_at IS NULL").
+		Joins("LEFT JOIN base_categories bc ON bc.id = b.base_category_id").
+		Where("ra.helicopter_id = ? AND ra.deleted_at IS NULL", helicopterID).
+		Where("COALESCE(afi.updated_at, fpc.updated_at, bfi.updated_at, ra.updated_at) IS NOT NULL").
+		Order("fi.inspection_date DESC, COALESCE(afi.updated_at, fpc.updated_at, bfi.updated_at, ra.updated_at) DESC").
+		Limit(1).
+		Take(&out).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	inspectionID, _ := uuidv7.BytesToString(out.InspectionID)
+	inspectorID, _ := uuidv7.BytesToString(out.InspectorID)
+	baseID, _ := uuidv7.BytesToString(out.BaseID)
+	return &shareddto.LastDailyInspectionSummary{
+		InspectionID:                      inspectionID,
+		Status:                            "inspected_cleared",
+		InspectorID:                       inspectorID,
+		InspectorName:                     strings.TrimSpace(out.InspectorName),
+		InspectorLicenseNo:                strings.TrimSpace(out.InspectorLicenseNo),
+		BaseID:                            baseID,
+		BaseName:                          strings.TrimSpace(out.BaseName),
+		BaseAbbreviation:                  strings.TrimSpace(out.BaseAbbreviation),
+		BaseType:                          strings.TrimSpace(out.BaseType),
+		InspectedAt:                       out.InspectedAt.UTC(),
+		InspectionFilesChecklistCompleted: out.CompletedCount,
+		InspectionFilesChecklistTotal:     out.TotalCount,
+	}, nil
+}
diff --git a/internal/repository/mysql/role_repo.go b/internal/repository/mysql/role_repo.go
new file mode 100644
index 0000000..c8a61b6
--- /dev/null
+++ b/internal/repository/mysql/role_repo.go
@@ -0,0 +1,202 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"wucher/internal/domain/auth"
+)
+
+type RoleRepository struct {
+	db *gorm.DB
+}
+
+func NewRoleRepository(db *gorm.DB) *RoleRepository {
+	return &RoleRepository{db: db}
+}
+
+func (r *RoleRepository) CreateRole(ctx context.Context, role *auth.Role) error {
+	if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+		role.CreatedBy = actor
+		role.UpdatedBy = actor
+	}
+	return r.db.WithContext(ctx).Create(role).Error
+}
+
+func (r *RoleRepository) UpdateRole(ctx context.Context, role *auth.Role) error {
+	if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+		role.UpdatedBy = actor
+	}
+	return r.db.WithContext(ctx).Save(role).Error
+}
+
+func (r *RoleRepository) DeleteRole(ctx context.Context, id []byte) error {
+	return r.db.WithContext(ctx).Delete(&auth.Role{}, "id = ?", id).Error
+}
+
+func (r *RoleRepository) GetRoleByID(ctx context.Context, id []byte) (*auth.Role, error) {
+	var role auth.Role
+	err := r.db.WithContext(ctx).First(&role, "id = ?", id).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &role, err
+}
+
+func (r *RoleRepository) GetRoleByName(ctx context.Context, name string) (*auth.Role, error) {
+	var role auth.Role
+	err := r.db.WithContext(ctx).Where("name = ?", name).First(&role).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &role, err
+}
+
+func (r *RoleRepository) HasRolePermission(ctx context.Context, roleID []byte, permissionKey string) (bool, error) {
+	var count int64
+	err := r.db.WithContext(ctx).
+		Table("role_permissions rp").
+		Joins("JOIN permissions p ON p.id = rp.permission_id").
+		Where("rp.role_id = ? AND p.`key` = ?", roleID, permissionKey).
+		Count(&count).Error
+	if err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+func (r *RoleRepository) GetPermissionByID(ctx context.Context, id []byte) (*auth.Permission, error) {
+	var perm auth.Permission
+	err := r.db.WithContext(ctx).First(&perm, "id = ?", id).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &perm, err
+}
+
+func (r *RoleRepository) GetPermissionByKey(ctx context.Context, key string) (*auth.Permission, error) {
+	var perm auth.Permission
+	err := r.db.WithContext(ctx).Where("`key` = ?", strings.ToLower(strings.TrimSpace(key))).First(&perm).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &perm, err
+}
+
+func (r *RoleRepository) UpdatePermission(ctx context.Context, permission *auth.Permission) error {
+	if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+		permission.UpdatedBy = actor
+	}
+	return r.db.WithContext(ctx).Save(permission).Error
+}
+
+func (r *RoleRepository) ListPermissionsByRoleID(ctx context.Context, roleID []byte) ([]auth.Permission, error) {
+	var perms []auth.Permission
+	err := r.db.WithContext(ctx).
+		Table("permissions p").
+		Select("p.*").
+		Joins("JOIN role_permissions rp ON rp.permission_id = p.id").
+		Where("rp.role_id = ?", roleID).
+		Order("p.name ASC").
+		Find(&perms).Error
+	if err != nil {
+		return nil, err
+	}
+	return perms, nil
+}
+
+func (r *RoleRepository) AssignPermission(ctx context.Context, roleID, permissionID []byte) (*auth.RolePermission, error) {
+	rp := &auth.RolePermission{RoleID: roleID, PermissionID: permissionID}
+	if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+		rp.CreatedBy = actor
+		rp.UpdatedBy = actor
+	}
+	err := r.db.WithContext(ctx).
+		Clauses(clause.OnConflict{
+			Columns:   []clause.Column{{Name: "role_id"}, {Name: "permission_id"}},
+			DoNothing: true,
+		}).
+		Create(rp).Error
+	if err != nil {
+		return nil, err
+	}
+
+	// Already exists, return current row.
+	if len(rp.ID) == 0 {
+		var existing auth.RolePermission
+		if err := r.db.WithContext(ctx).
+			Where("role_id = ? AND permission_id = ?", roleID, permissionID).
+			First(&existing).Error; err != nil {
+			return nil, err
+		}
+		return &existing, nil
+	}
+	return rp, nil
+}
+
+func (r *RoleRepository) RemovePermission(ctx context.Context, roleID, permissionID []byte) error {
+	return r.db.WithContext(ctx).
+		Delete(&auth.RolePermission{}, "role_id = ? AND permission_id = ?", roleID, permissionID).
+		Error
+}
+
+func (r *RoleRepository) ListPermissions(ctx context.Context, filter string, sort string, limit, offset int) ([]auth.Permission, int64, error) {
+	var perms []auth.Permission
+	var total int64
+
+	query := r.db.WithContext(ctx).Model(&auth.Permission{})
+	if filter != "" {
+		like := "%" + strings.ToLower(filter) + "%"
+		query = query.Where("LOWER(name) LIKE ? OR LOWER(`key`) LIKE ?", like, like)
+	}
+	if err := query.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		query = query.Order("created_at DESC")
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&perms).Error; err != nil {
+		return nil, 0, err
+	}
+	return perms, total, nil
+}
+
+func (r *RoleRepository) ListRoles(ctx context.Context, filterName, sort string, limit, offset int) ([]auth.Role, int64, error) {
+	var roles []auth.Role
+	var total int64
+
+	query := r.db.WithContext(ctx).Model(&auth.Role{})
+
+	if filterName != "" {
+		query = query.Where("LOWER(name) LIKE ?", "%"+strings.ToLower(filterName)+"%")
+	}
+
+	if err := query.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		query = query.Order("created_at DESC")
+	}
+
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+
+	if err := query.Find(&roles).Error; err != nil {
+		return nil, 0, err
+	}
+
+	return roles, total, nil
+}
diff --git a/internal/repository/mysql/schema_cache.go b/internal/repository/mysql/schema_cache.go
new file mode 100644
index 0000000..53e70ad
--- /dev/null
+++ b/internal/repository/mysql/schema_cache.go
@@ -0,0 +1,58 @@
+package mysql
+
+import (
+	"fmt"
+	"reflect"
+
+	"gorm.io/gorm"
+)
+
+// schemaCache memoizes table/column existence checks for a single DB handle.
+// It is intended for startup-time feature detection, not per-request probing.
+type schemaCache struct {
+	db           *gorm.DB
+	tableExists  map[string]bool
+	columnExists map[string]bool
+}
+
+func newSchemaCache(db *gorm.DB) *schemaCache {
+	return &schemaCache{
+		db:           db,
+		tableExists:  make(map[string]bool),
+		columnExists: make(map[string]bool),
+	}
+}
+
+func (s *schemaCache) HasTable(dst any) bool {
+	key := schemaKey(dst)
+	if ok, found := s.tableExists[key]; found {
+		return ok
+	}
+	ok := s.db.Migrator().HasTable(dst)
+	s.tableExists[key] = ok
+	return ok
+}
+
+func (s *schemaCache) HasColumn(dst any, column string) bool {
+	key := schemaKey(dst) + "\x00" + column
+	if ok, found := s.columnExists[key]; found {
+		return ok
+	}
+	ok := s.db.Migrator().HasColumn(dst, column)
+	s.columnExists[key] = ok
+	return ok
+}
+
+func schemaKey(dst any) string {
+	if dst == nil {
+		return "<nil>"
+	}
+	if s, ok := dst.(string); ok {
+		return "table:" + s
+	}
+	t := reflect.TypeOf(dst)
+	if t.Kind() == reflect.Ptr {
+		t = t.Elem()
+	}
+	return fmt.Sprintf("type:%s.%s", t.PkgPath(), t.Name())
+}
diff --git a/internal/repository/mysql/takeover_repo.go b/internal/repository/mysql/takeover_repo.go
new file mode 100644
index 0000000..041b5d7
--- /dev/null
+++ b/internal/repository/mysql/takeover_repo.go
@@ -0,0 +1,154 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	takeover "wucher/internal/domain/takeover"
+)
+
+type TakeoverRepository struct {
+	db *gorm.DB
+}
+
+func NewTakeoverRepository(db *gorm.DB) *TakeoverRepository {
+	return &TakeoverRepository{db: db}
+}
+
+func (r *TakeoverRepository) Create(ctx context.Context, row *takeover.TakeoverAc) error {
+	return r.db.WithContext(ctx).Create(row).Error
+}
+
+func (r *TakeoverRepository) Update(ctx context.Context, row *takeover.TakeoverAc) error {
+	return r.db.WithContext(ctx).Save(row).Error
+}
+
+func (r *TakeoverRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	return r.db.WithContext(ctx).Model(&takeover.TakeoverAc{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(map[string]any{"deleted_at": now, "deleted_by": deletedBy, "updated_by": deletedBy}).Error
+}
+
+// ListActiveEditedTemplateUUIDs returns template UUIDs for takeover-linked files
+// that are still active. Trashed or lifecycle-deleted files are ignored.
+func (r *TakeoverRepository) ListActiveEditedTemplateUUIDs(tx *gorm.DB, takeoverID []byte) ([][]byte, error) {
+	if len(takeoverID) != 16 {
+		return nil, nil
+	}
+	db := tx
+	if db == nil {
+		db = r.db
+	}
+	var editedTemplateUUIDs [][]byte
+	if err := db.Table("file_files").
+		Where(
+			"takeover_id = ? AND template_uuid IS NOT NULL AND deleted_at IS NULL AND lifecycle_deleted_at IS NULL AND status <> ?",
+			takeoverID,
+			filemanager.FileStatusTrashed,
+		).
+		Distinct().
+		Pluck("template_uuid", &editedTemplateUUIDs).Error; err != nil {
+		return nil, err
+	}
+	return editedTemplateUUIDs, nil
+}
+
+// ListChecklistTemplateFiles returns the helicopter files that make up a section's
+// inspection checklist. Documents created from a template (via create-from-template)
+// are stored as helicopter_files rows for takeover/WOPI editing but are not checklist
+// items, so they are excluded here. Pass the active transaction handle to run within
+// an ongoing transaction; when tx is nil the repository's own connection is used.
+func (r *TakeoverRepository) ListChecklistTemplateFiles(tx *gorm.DB, helicopterID []byte, section string) ([]helicopterfile.HelicopterFile, error) {
+	db := tx
+	if db == nil {
+		db = r.db
+	}
+	var rows []helicopterfile.HelicopterFile
+	if err := db.
+		Model(&helicopterfile.HelicopterFile{}).
+		Preload("SourceFile").
+		Preload("FileAttachment").
+		Preload("FileAttachment.File").
+		Where("helicopter_id = ? AND section = ?", helicopterID, section).
+		Order("position ASC, id ASC").
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	filtered := rows[:0]
+	for i := range rows {
+		if helicopterFileRowCreatedFromTemplate(&rows[i]) {
+			continue
+		}
+		filtered = append(filtered, rows[i])
+	}
+	return filtered, nil
+}
+
+// helicopterFileRowCreatedFromTemplate reports whether a helicopter file row points to a
+// document instantiated from a template (non-empty template_uuid on the underlying file).
+func helicopterFileRowCreatedFromTemplate(row *helicopterfile.HelicopterFile) bool {
+	if row == nil {
+		return false
+	}
+	if row.SourceFile != nil {
+		return len(row.SourceFile.TemplateUUID) == 16
+	}
+	if row.FileAttachment != nil && row.FileAttachment.File != nil {
+		return len(row.FileAttachment.File.TemplateUUID) == 16
+	}
+	return false
+}
+
+func (r *TakeoverRepository) GetByID(ctx context.Context, id []byte) (*takeover.TakeoverAc, error) {
+	var row takeover.TakeoverAc
+	err := r.db.WithContext(ctx).
+		Preload("Base").
+		Preload("ReserveAc").
+		Preload("ReserveAc.Aircraft").
+		Preload("ReserveAc.Inspection").
+		Preload("RosterCrews").
+		Preload("OtherPeople").
+		Preload("Files").
+		Preload("Files.FileAttachment").
+		Preload("Files.FileAttachment.File").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *TakeoverRepository) List(ctx context.Context, limit, offset int) ([]takeover.TakeoverAc, int64, error) {
+	rows := make([]takeover.TakeoverAc, 0)
+	var total int64
+	base := r.db.WithContext(ctx).
+		Model(&takeover.TakeoverAc{}).
+		Preload("Base").
+		Preload("ReserveAc").
+		Preload("ReserveAc.Aircraft").
+		Preload("ReserveAc.Inspection").
+		Preload("RosterCrews").
+		Preload("OtherPeople").
+		Preload("Files").
+		Preload("Files.FileAttachment").
+		Preload("Files.FileAttachment.File").
+		Where("deleted_at IS NULL")
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	q := base.Order("created_at DESC")
+	if limit > 0 {
+		q = q.Limit(limit).Offset(offset)
+	}
+	if err := q.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/token_store.go b/internal/repository/mysql/token_store.go
new file mode 100644
index 0000000..0a4c1a6
--- /dev/null
+++ b/internal/repository/mysql/token_store.go
@@ -0,0 +1,126 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"wucher/internal/domain/transient"
+)
+
+type TokenStore struct {
+	db  *gorm.DB
+	now func() time.Time
+}
+
+func NewTokenStore(db *gorm.DB) *TokenStore {
+	return &TokenStore{
+		db:  db,
+		now: func() time.Time { return time.Now().UTC() },
+	}
+}
+
+func (s *TokenStore) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error {
+	if s == nil || s.db == nil {
+		return errors.New("token store db is required")
+	}
+	key = strings.TrimSpace(key)
+	if key == "" {
+		return errors.New("token store key is required")
+	}
+
+	now := s.now().UTC()
+	var expiresAt *time.Time
+	if ttl > 0 {
+		ts := now.Add(ttl)
+		expiresAt = &ts
+	}
+
+	entry := transient.TokenEntry{
+		StoreKey:  key,
+		Value:     append([]byte(nil), value...),
+		ExpiresAt: expiresAt,
+	}
+	return s.db.WithContext(ctx).Clauses(clause.OnConflict{
+		Columns: []clause.Column{{Name: "store_key"}},
+		DoUpdates: clause.Assignments(map[string]any{
+			"value":      entry.Value,
+			"expires_at": entry.ExpiresAt,
+			"updated_at": now,
+		}),
+	}).Create(&entry).Error
+}
+
+func (s *TokenStore) SetIfNotExists(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error) {
+	if s == nil || s.db == nil {
+		return false, errors.New("token store db is required")
+	}
+	key = strings.TrimSpace(key)
+	if key == "" {
+		return false, errors.New("token store key is required")
+	}
+
+	now := s.now().UTC()
+	var expiresAt *time.Time
+	if ttl > 0 {
+		ts := now.Add(ttl)
+		expiresAt = &ts
+		if err := s.db.WithContext(ctx).
+			Delete(&transient.TokenEntry{}, "store_key = ? AND expires_at IS NOT NULL AND expires_at <= ?", key, now).Error; err != nil {
+			return false, err
+		}
+	}
+
+	entry := transient.TokenEntry{
+		StoreKey:  key,
+		Value:     append([]byte(nil), value...),
+		ExpiresAt: expiresAt,
+	}
+	tx := s.db.WithContext(ctx).Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "store_key"}},
+		DoNothing: true,
+	}).Create(&entry)
+	if tx.Error != nil {
+		return false, tx.Error
+	}
+	return tx.RowsAffected > 0, nil
+}
+
+func (s *TokenStore) Get(ctx context.Context, key string) ([]byte, error) {
+	if s == nil || s.db == nil {
+		return nil, errors.New("token store db is required")
+	}
+	key = strings.TrimSpace(key)
+	if key == "" {
+		return nil, nil
+	}
+
+	var entry transient.TokenEntry
+	tx := s.db.WithContext(ctx).Where("store_key = ?", key).Limit(1).Find(&entry)
+	if tx.Error != nil {
+		return nil, tx.Error
+	}
+	if tx.RowsAffected == 0 {
+		return nil, nil
+	}
+	if entry.ExpiresAt != nil && !entry.ExpiresAt.After(s.now().UTC()) {
+		_ = s.Delete(ctx, key)
+		return nil, nil
+	}
+	return append([]byte(nil), entry.Value...), nil
+}
+
+func (s *TokenStore) Delete(ctx context.Context, key string) error {
+	if s == nil || s.db == nil {
+		return errors.New("token store db is required")
+	}
+	key = strings.TrimSpace(key)
+	if key == "" {
+		return nil
+	}
+	return s.db.WithContext(ctx).Delete(&transient.TokenEntry{}, "store_key = ?", key).Error
+}
diff --git a/internal/repository/mysql/token_store_test.go b/internal/repository/mysql/token_store_test.go
new file mode 100644
index 0000000..041b5b9
--- /dev/null
+++ b/internal/repository/mysql/token_store_test.go
@@ -0,0 +1,82 @@
+package mysql
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"wucher/internal/domain/transient"
+)
+
+func TestTokenStore_SetGetDelete(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	baseTime := time.Date(2026, 3, 20, 10, 0, 0, 0, time.UTC)
+	store := NewTokenStore(db)
+	store.now = func() time.Time { return baseTime }
+
+	ctx := context.Background()
+	if err := store.Set(ctx, "auth:test", []byte("value"), time.Minute); err != nil {
+		t.Fatalf("set: %v", err)
+	}
+
+	got, err := store.Get(ctx, "auth:test")
+	if err != nil {
+		t.Fatalf("get: %v", err)
+	}
+	if string(got) != "value" {
+		t.Fatalf("unexpected value %q", got)
+	}
+
+	store.now = func() time.Time { return baseTime.Add(2 * time.Minute) }
+	got, err = store.Get(ctx, "auth:test")
+	if err != nil {
+		t.Fatalf("get expired: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected expired value to be cleared, got %q", got)
+	}
+
+	var count int64
+	if err := db.Model(&transient.TokenEntry{}).Where("store_key = ?", "auth:test").Count(&count).Error; err != nil {
+		t.Fatalf("count expired token: %v", err)
+	}
+	if count != 0 {
+		t.Fatalf("expected expired token deleted, got %d rows", count)
+	}
+
+	store.now = func() time.Time { return baseTime }
+	if err := store.Set(ctx, "auth:persistent", []byte("keep"), 0); err != nil {
+		t.Fatalf("set persistent: %v", err)
+	}
+	store.now = func() time.Time { return baseTime.Add(24 * time.Hour) }
+	got, err = store.Get(ctx, "auth:persistent")
+	if err != nil {
+		t.Fatalf("get persistent: %v", err)
+	}
+	if string(got) != "keep" {
+		t.Fatalf("unexpected persistent value %q", got)
+	}
+
+	if err := store.Delete(ctx, "auth:persistent"); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+	got, err = store.Get(ctx, "auth:persistent")
+	if err != nil {
+		t.Fatalf("get after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected deleted value to be nil, got %q", got)
+	}
+
+	got, err = store.Get(ctx, "auth:missing")
+	if err != nil {
+		t.Fatalf("get missing: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected missing value to be nil, got %q", got)
+	}
+}
diff --git a/internal/repository/mysql/user_repo.go b/internal/repository/mysql/user_repo.go
new file mode 100644
index 0000000..edd90bd
--- /dev/null
+++ b/internal/repository/mysql/user_repo.go
@@ -0,0 +1,226 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/user"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type UserRepository struct {
+	db *gorm.DB
+}
+
+func NewUserRepository(db *gorm.DB) *UserRepository {
+	return &UserRepository{db: db}
+}
+
+func (r *UserRepository) Create(ctx context.Context, u *user.User) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+			u.CreatedBy = actor
+			u.UpdatedBy = actor
+		}
+		if err := tx.Create(u).Error; err != nil {
+			return err
+		}
+		return replaceUserRolesTx(ctx, tx, u.ID, u.RoleID, u.RoleIDs)
+	})
+}
+
+func (r *UserRepository) Update(ctx context.Context, u *user.User) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if actor := actorUserIDFromContext(ctx); len(actor) > 0 {
+			u.UpdatedBy = actor
+		}
+		// Persist only user columns and avoid relation side-effects from preloaded structs.
+		if err := tx.Omit(clause.Associations).Save(u).Error; err != nil {
+			return err
+		}
+		// Keep legacy and current image columns in sync when image patch is requested.
+		if u.ProfileAttachmentPatchSet {
+			updates := map[string]any{
+				"profile_attachment_id": nil,
+				"image_attachment_id":   nil,
+			}
+			if len(u.ProfileAttachmentID) == 16 {
+				updates["profile_attachment_id"] = append([]byte(nil), u.ProfileAttachmentID...)
+				updates["image_attachment_id"] = append([]byte(nil), u.ProfileAttachmentID...)
+			}
+			if err := tx.Model(&user.User{}).Where("id = ?", u.ID).Updates(updates).Error; err != nil {
+				return err
+			}
+		}
+		if u.RoleIDs == nil {
+			return nil
+		}
+		return replaceUserRolesTx(ctx, tx, u.ID, u.RoleID, u.RoleIDs)
+	})
+}
+
+func (r *UserRepository) Delete(ctx context.Context, id []byte) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Model(&user.User{}).
+			Where("id = ?", id).
+			Updates(map[string]any{
+				"image_attachment_id":   nil,
+				"profile_attachment_id": nil,
+			}).Error; err != nil {
+			return err
+		}
+		if idStr, err := uuidv7.BytesToString(id); err == nil && idStr != "" {
+			if err := tx.Exec("DELETE FROM attachments WHERE ref_type = ? AND ref_id = ?", "user_profile", idStr).Error; err != nil {
+				return err
+			}
+		}
+		if err := tx.Where("user_id = ?", id).Delete(&auth.UserRole{}).Error; err != nil {
+			return err
+		}
+		return tx.Delete(&user.User{}, "id = ?", id).Error
+	})
+}
+
+func (r *UserRepository) GetByID(ctx context.Context, id []byte) (*user.User, error) {
+	var u user.User
+	err := r.db.WithContext(ctx).
+		Model(&user.User{}).
+		Select("users.*, roles.name AS role_name, roles.description AS role_description").
+		Joins("LEFT JOIN roles ON roles.id = users.role_id").
+		Preload("ProfileAttachment").
+		Preload("ProfileAttachment.File").
+		Where("users.id = ?", id).
+		First(&u).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	if err := attachUserDomainRoles(ctx, r.db, &u); err != nil {
+		return nil, err
+	}
+	return &u, nil
+}
+
+func (r *UserRepository) GetByEmail(ctx context.Context, email string) (*user.User, error) {
+	var u user.User
+	err := r.db.WithContext(ctx).
+		Model(&user.User{}).
+		Select("users.*, roles.name AS role_name, roles.description AS role_description").
+		Joins("LEFT JOIN roles ON roles.id = users.role_id").
+		Preload("ProfileAttachment").
+		Preload("ProfileAttachment.File").
+		Where("users.email = ?", email).
+		First(&u).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	if err := attachUserDomainRoles(ctx, r.db, &u); err != nil {
+		return nil, err
+	}
+	return &u, nil
+}
+
+func (r *UserRepository) GetByUsername(ctx context.Context, username string) (*user.User, error) {
+	var u user.User
+	err := r.db.WithContext(ctx).
+		Model(&user.User{}).
+		Select("users.*, roles.name AS role_name, roles.description AS role_description").
+		Joins("LEFT JOIN roles ON roles.id = users.role_id").
+		Preload("ProfileAttachment").
+		Preload("ProfileAttachment.File").
+		Where("users.username = ?", username).
+		First(&u).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	if err := attachUserDomainRoles(ctx, r.db, &u); err != nil {
+		return nil, err
+	}
+	return &u, nil
+}
+
+func (r *UserRepository) GetLastNameByID(ctx context.Context, id []byte) (string, error) {
+	var u user.User
+	err := r.db.WithContext(ctx).
+		Table("users").
+		Select("last_name").
+		Where("id = ?", id).
+		First(&u).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return "", nil
+	}
+	if err != nil {
+		return "", err
+	}
+	return u.LastName, nil
+}
+
+// GetShortNameByID returns the user's profile short name (pilot or technician
+// 3-letter code, e.g. "GAN"), or an empty string when the user has no profile
+// short name set. Callers apply their own fallback (e.g. initials).
+func (r *UserRepository) GetShortNameByID(ctx context.Context, id []byte) (string, error) {
+	var out struct {
+		ShortName string `gorm:"column:short_name"`
+	}
+	err := r.db.WithContext(ctx).
+		Table("users u").
+		Select("COALESCE(NULLIF(pp.short_name, ''), NULLIF(tp.short_name, ''), '') AS short_name").
+		Joins("LEFT JOIN pilot_profiles pp ON pp.user_id = u.id").
+		Joins("LEFT JOIN technician_profiles tp ON tp.user_id = u.id").
+		Where("u.id = ?", id).
+		Take(&out).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return "", nil
+	}
+	if err != nil {
+		return "", err
+	}
+	return out.ShortName, nil
+}
+
+func (r *UserRepository) List(ctx context.Context, filter string, sort string, limit, offset int) ([]user.User, int64, error) {
+	var users []user.User
+	var total int64
+
+	base := r.db.WithContext(ctx).
+		Model(&user.User{}).
+		Joins("LEFT JOIN roles ON roles.id = users.role_id")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("users.email LIKE ? OR users.username LIKE ? OR users.first_name LIKE ? OR users.last_name LIKE ?", like, like, like, like)
+	}
+	query := base.Select("users.*, roles.name AS role_name, roles.description AS role_description")
+	query = query.Preload("ProfileAttachment").Preload("ProfileAttachment.File")
+	if sort != "" {
+		query = query.Order(sort)
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&users).Error; err != nil {
+		return nil, 0, err
+	}
+	ptrs := make([]*user.User, 0, len(users))
+	for i := range users {
+		ptrs = append(ptrs, &users[i])
+	}
+	if err := attachUserDomainRoles(ctx, r.db, ptrs...); err != nil {
+		return nil, 0, err
+	}
+	return users, total, nil
+}
diff --git a/internal/repository/mysql/user_repo_test.go b/internal/repository/mysql/user_repo_test.go
new file mode 100644
index 0000000..0c331b6
--- /dev/null
+++ b/internal/repository/mysql/user_repo_test.go
@@ -0,0 +1,205 @@
+package mysql
+
+import (
+	"context"
+	"testing"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/user"
+	"wucher/internal/shared/pkg/appctx"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func setupUserRepoFixture(t *testing.T) (*UserRepository, context.Context, []byte) {
+	t.Helper()
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	repo := NewUserRepository(db)
+	roleID := uuidv7.MustBytes()
+	if err := db.Create(&auth.Role{
+		ID:          roleID,
+		Code:        "admin",
+		Name:        "admin",
+		Description: "admin role",
+	}).Error; err != nil {
+		t.Fatalf("seed role: %v", err)
+	}
+	return repo, context.Background(), roleID
+}
+
+func TestUserRepository_CRUDAndLookupBranches(t *testing.T) {
+	repo, baseCtx, roleID := setupUserRepoFixture(t)
+	actorID := uuidv7.MustBytes()
+	ctx := appctx.WithUserID(baseCtx, actorID)
+
+	u := &user.User{
+		Email:     "john@example.com",
+		Username:  "john",
+		FirstName: "John",
+		LastName:  "Doe",
+		Timezone:  "UTC",
+		RoleID:    roleID,
+	}
+	if err := repo.Create(ctx, u); err != nil {
+		t.Fatalf("create: %v", err)
+	}
+	if len(u.CreatedBy) != 16 || len(u.UpdatedBy) != 16 {
+		t.Fatalf("expected created_by and updated_by set by actor")
+	}
+
+	byEmail, err := repo.GetByEmail(ctx, u.Email)
+	if err != nil || byEmail == nil {
+		t.Fatalf("get by email failed: user=%v err=%v", byEmail, err)
+	}
+	byUsername, err := repo.GetByUsername(ctx, u.Username)
+	if err != nil || byUsername == nil {
+		t.Fatalf("get by username failed: user=%v err=%v", byUsername, err)
+	}
+	lastName, err := repo.GetLastNameByID(ctx, u.ID)
+	if err != nil || lastName != "Doe" {
+		t.Fatalf("get last name failed: lastName=%q err=%v", lastName, err)
+	}
+
+	// Update branch: RoleIDs nil should skip role-replacement path.
+	byEmail.FirstName = "Johnny"
+	byEmail.RoleIDs = nil
+	if err := repo.Update(ctx, byEmail); err != nil {
+		t.Fatalf("update (roleIDs nil): %v", err)
+	}
+
+	// Update branch: RoleIDs provided should execute role-replacement path.
+	byEmail.LastName = "Doe-Updated"
+	byEmail.RoleIDs = [][]byte{roleID}
+	if err := repo.Update(ctx, byEmail); err != nil {
+		t.Fatalf("update (roleIDs set): %v", err)
+	}
+
+	// List branches: with/without filter, sort, and limit.
+	list, total, err := repo.List(ctx, "john", "users.email ASC", 1, 0)
+	if err != nil {
+		t.Fatalf("list with filter: %v", err)
+	}
+	if total < 1 || len(list) != 1 {
+		t.Fatalf("expected one filtered result, total=%d len=%d", total, len(list))
+	}
+	list, total, err = repo.List(ctx, "", "", 0, 0)
+	if err != nil {
+		t.Fatalf("list without limit: %v", err)
+	}
+	if total < 1 || len(list) < 1 {
+		t.Fatalf("expected at least one user, total=%d len=%d", total, len(list))
+	}
+
+	// Not found branches.
+	if got, err := repo.GetByID(ctx, uuidv7.MustBytes()); err != nil || got != nil {
+		t.Fatalf("expected not found by id => nil,nil; got=%v err=%v", got, err)
+	}
+	if got, err := repo.GetByEmail(ctx, "missing@example.com"); err != nil || got != nil {
+		t.Fatalf("expected not found by email => nil,nil; got=%v err=%v", got, err)
+	}
+	if got, err := repo.GetByUsername(ctx, "missing-user"); err != nil || got != nil {
+		t.Fatalf("expected not found by username => nil,nil; got=%v err=%v", got, err)
+	}
+	if got, err := repo.GetLastNameByID(ctx, uuidv7.MustBytes()); err != nil || got != "" {
+		t.Fatalf("expected not found last_name => empty,nil; got=%q err=%v", got, err)
+	}
+
+	if err := repo.Delete(ctx, u.ID); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+	// Delete branch with invalid uuid bytes (skip attachment cleanup query branch).
+	if err := repo.Delete(ctx, []byte("short")); err != nil {
+		t.Fatalf("delete short id should be noop-success, err=%v", err)
+	}
+}
+
+func TestUserRepository_ErrorBranchesWhenDatabaseClosed(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	repo := NewUserRepository(db)
+	sqlDB, err := db.DB()
+	if err != nil {
+		t.Fatalf("db.DB: %v", err)
+	}
+	if err := sqlDB.Close(); err != nil {
+		t.Fatalf("close db: %v", err)
+	}
+
+	ctx := context.Background()
+	roleID := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+	u := &user.User{
+		ID:        userID,
+		Email:     "closed@example.com",
+		Username:  "closed",
+		FirstName: "Closed",
+		LastName:  "DB",
+		Timezone:  "UTC",
+		RoleID:    roleID,
+	}
+
+	if err := repo.Create(ctx, u); err == nil {
+		t.Fatalf("expected create error on closed db")
+	}
+	if err := repo.Update(ctx, u); err == nil {
+		t.Fatalf("expected update error on closed db")
+	}
+	if err := repo.Delete(ctx, userID); err == nil {
+		t.Fatalf("expected delete error on closed db")
+	}
+	if _, err := repo.GetByID(ctx, userID); err == nil {
+		t.Fatalf("expected get by id error on closed db")
+	}
+	if _, err := repo.GetByEmail(ctx, u.Email); err == nil {
+		t.Fatalf("expected get by email error on closed db")
+	}
+	if _, err := repo.GetByUsername(ctx, u.Username); err == nil {
+		t.Fatalf("expected get by username error on closed db")
+	}
+	if _, err := repo.GetLastNameByID(ctx, userID); err == nil {
+		t.Fatalf("expected get last name error on closed db")
+	}
+	if _, _, err := repo.List(ctx, "", "", 10, 0); err == nil {
+		t.Fatalf("expected list error on closed db")
+	}
+}
+
+func TestUserRepository_CreateDuplicateAndDeleteAttachmentCleanupError(t *testing.T) {
+	repo, ctx, roleID := setupUserRepoFixture(t)
+
+	u := &user.User{
+		Email:     "dup@example.com",
+		Username:  "dup-user",
+		FirstName: "Dup",
+		LastName:  "User",
+		Timezone:  "UTC",
+		RoleID:    roleID,
+	}
+	if err := repo.Create(ctx, u); err != nil {
+		t.Fatalf("create first user: %v", err)
+	}
+
+	dup := &user.User{
+		Email:     "dup@example.com",
+		Username:  "dup-user-2",
+		FirstName: "Dup2",
+		LastName:  "User2",
+		Timezone:  "UTC",
+		RoleID:    roleID,
+	}
+	if err := repo.Create(ctx, dup); err == nil {
+		t.Fatalf("expected duplicate-email create error")
+	}
+
+	// Force attachment cleanup statement to fail so delete returns error branch.
+	if err := repo.db.Exec("DROP TABLE attachments").Error; err != nil {
+		t.Fatalf("drop attachments table: %v", err)
+	}
+	if err := repo.Delete(ctx, u.ID); err == nil {
+		t.Fatalf("expected delete error when attachments table missing")
+	}
+}
diff --git a/internal/repository/mysql/user_roles.go b/internal/repository/mysql/user_roles.go
new file mode 100644
index 0000000..5e757f4
--- /dev/null
+++ b/internal/repository/mysql/user_roles.go
@@ -0,0 +1,286 @@
+package mysql
+
+import (
+	"context"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/user"
+)
+
+type userRoleJoinRow struct {
+	UserID          []byte `gorm:"column:user_id"`
+	RoleID          []byte `gorm:"column:role_id"`
+	RoleName        string `gorm:"column:role_name"`
+	RoleDescription string `gorm:"column:role_description"`
+}
+
+func normalizeAssignedRoleIDs(primaryRoleID []byte, roleIDs [][]byte) [][]byte {
+	out := make([][]byte, 0, len(roleIDs)+1)
+	seen := make(map[string]struct{}, len(roleIDs)+1)
+
+	appendRole := func(roleID []byte) {
+		if len(roleID) != 16 {
+			return
+		}
+		key := string(roleID)
+		if _, exists := seen[key]; exists {
+			return
+		}
+		seen[key] = struct{}{}
+		out = append(out, append([]byte(nil), roleID...))
+	}
+
+	appendRole(primaryRoleID)
+	for i := range roleIDs {
+		appendRole(roleIDs[i])
+	}
+
+	return out
+}
+
+func replaceUserRolesTx(ctx context.Context, tx *gorm.DB, userID, primaryRoleID []byte, roleIDs [][]byte) error {
+	normalized := normalizeAssignedRoleIDs(primaryRoleID, roleIDs)
+	if len(userID) != 16 {
+		return nil
+	}
+
+	if err := tx.Where("user_id = ?", userID).Delete(&auth.UserRole{}).Error; err != nil {
+		return err
+	}
+	if len(normalized) == 0 {
+		return nil
+	}
+
+	actor := actorUserIDFromContext(ctx)
+	items := make([]auth.UserRole, 0, len(normalized))
+	for i := range normalized {
+		item := auth.UserRole{
+			UserID: userID,
+			RoleID: normalized[i],
+		}
+		if len(actor) > 0 {
+			item.CreatedBy = actor
+			item.UpdatedBy = actor
+		}
+		items = append(items, item)
+	}
+
+	return tx.Create(&items).Error
+}
+
+func listUserRoleIDsTx(tx *gorm.DB, userID []byte) ([][]byte, error) {
+	var rows []struct {
+		RoleID []byte `gorm:"column:role_id"`
+	}
+	if err := tx.Table("user_roles").
+		Select("role_id").
+		Where("user_id = ?", userID).
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+
+	roleIDs := make([][]byte, 0, len(rows))
+	for i := range rows {
+		if len(rows[i].RoleID) != 16 {
+			continue
+		}
+		roleIDs = append(roleIDs, append([]byte(nil), rows[i].RoleID...))
+	}
+	return roleIDs, nil
+}
+
+func replacePrimaryUserRoleTx(ctx context.Context, tx *gorm.DB, userID, currentPrimaryRoleID, newPrimaryRoleID []byte) error {
+	roleIDs, err := listUserRoleIDsTx(tx, userID)
+	if err != nil {
+		return err
+	}
+
+	filtered := make([][]byte, 0, len(roleIDs))
+	currentPrimaryKey := string(currentPrimaryRoleID)
+	newPrimaryKey := string(newPrimaryRoleID)
+	for i := range roleIDs {
+		key := string(roleIDs[i])
+		if key == currentPrimaryKey || key == newPrimaryKey {
+			continue
+		}
+		filtered = append(filtered, roleIDs[i])
+	}
+
+	return replaceUserRolesTx(ctx, tx, userID, newPrimaryRoleID, filtered)
+}
+
+func loadUserRoleRows(ctx context.Context, db *gorm.DB, userIDs [][]byte) (map[string][]userRoleJoinRow, error) {
+	rowsByUserID := make(map[string][]userRoleJoinRow, len(userIDs))
+	if len(userIDs) == 0 {
+		return rowsByUserID, nil
+	}
+
+	var rows []userRoleJoinRow
+	if err := db.WithContext(ctx).
+		Table("user_roles ur").
+		Select("ur.user_id, roles.id AS role_id, roles.name AS role_name, roles.description AS role_description").
+		Joins("JOIN roles ON roles.id = ur.role_id").
+		Where("ur.user_id IN ?", userIDs).
+		Order("roles.name ASC").
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+
+	for i := range rows {
+		key := string(rows[i].UserID)
+		rowsByUserID[key] = append(rowsByUserID[key], userRoleJoinRow{
+			UserID:          append([]byte(nil), rows[i].UserID...),
+			RoleID:          append([]byte(nil), rows[i].RoleID...),
+			RoleName:        rows[i].RoleName,
+			RoleDescription: rows[i].RoleDescription,
+		})
+	}
+
+	return rowsByUserID, nil
+}
+
+func orderUserRoleRows(primaryRoleID []byte, rows []userRoleJoinRow) []userRoleJoinRow {
+	if len(rows) < 2 || len(primaryRoleID) != 16 {
+		return rows
+	}
+
+	primaryKey := string(primaryRoleID)
+	ordered := make([]userRoleJoinRow, 0, len(rows))
+	for i := range rows {
+		if string(rows[i].RoleID) == primaryKey {
+			ordered = append(ordered, rows[i])
+			break
+		}
+	}
+	for i := range rows {
+		if string(rows[i].RoleID) == primaryKey {
+			continue
+		}
+		ordered = append(ordered, rows[i])
+	}
+	return ordered
+}
+
+func loadRoleRowsByID(ctx context.Context, db *gorm.DB, roleIDs [][]byte) (map[string]userRoleJoinRow, error) {
+	out := make(map[string]userRoleJoinRow, len(roleIDs))
+	if len(roleIDs) == 0 {
+		return out, nil
+	}
+
+	var rows []struct {
+		ID          []byte `gorm:"column:id"`
+		Name        string `gorm:"column:name"`
+		Description string `gorm:"column:description"`
+	}
+	if err := db.WithContext(ctx).
+		Table("roles").
+		Select("id, name, description").
+		Where("id IN ?", roleIDs).
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+
+	for i := range rows {
+		out[string(rows[i].ID)] = userRoleJoinRow{
+			RoleID:          append([]byte(nil), rows[i].ID...),
+			RoleName:        rows[i].Name,
+			RoleDescription: rows[i].Description,
+		}
+	}
+
+	return out, nil
+}
+
+func attachAuthUserRoles(ctx context.Context, db *gorm.DB, users ...*auth.User) error {
+	userIDs := make([][]byte, 0, len(users))
+	missingPrimaryRoleIDs := make([][]byte, 0, len(users))
+	for i := range users {
+		if users[i] == nil || len(users[i].ID) != 16 {
+			continue
+		}
+		userIDs = append(userIDs, users[i].ID)
+		if len(users[i].RoleID) == 16 {
+			missingPrimaryRoleIDs = append(missingPrimaryRoleIDs, users[i].RoleID)
+		}
+	}
+
+	rowsByUserID, err := loadUserRoleRows(ctx, db, userIDs)
+	if err != nil {
+		return err
+	}
+	roleRowsByID, err := loadRoleRowsByID(ctx, db, missingPrimaryRoleIDs)
+	if err != nil {
+		return err
+	}
+
+	for i := range users {
+		if users[i] == nil {
+			continue
+		}
+
+		rows := orderUserRoleRows(users[i].RoleID, rowsByUserID[string(users[i].ID)])
+		if len(rows) == 0 && len(users[i].RoleID) == 16 {
+			if roleRow, ok := roleRowsByID[string(users[i].RoleID)]; ok {
+				rows = []userRoleJoinRow{roleRow}
+			}
+		}
+
+		users[i].RoleIDs = make([][]byte, 0, len(rows))
+		users[i].Roles = make([]auth.Role, 0, len(rows))
+		for j := range rows {
+			users[i].RoleIDs = append(users[i].RoleIDs, append([]byte(nil), rows[j].RoleID...))
+			users[i].Roles = append(users[i].Roles, auth.Role{
+				ID:          append([]byte(nil), rows[j].RoleID...),
+				Name:        rows[j].RoleName,
+				Description: rows[j].RoleDescription,
+			})
+		}
+	}
+
+	return nil
+}
+
+func attachUserDomainRoles(ctx context.Context, db *gorm.DB, users ...*user.User) error {
+	userIDs := make([][]byte, 0, len(users))
+	for i := range users {
+		if users[i] == nil || len(users[i].ID) != 16 {
+			continue
+		}
+		userIDs = append(userIDs, users[i].ID)
+	}
+
+	rowsByUserID, err := loadUserRoleRows(ctx, db, userIDs)
+	if err != nil {
+		return err
+	}
+
+	for i := range users {
+		if users[i] == nil {
+			continue
+		}
+
+		rows := orderUserRoleRows(users[i].RoleID, rowsByUserID[string(users[i].ID)])
+		if len(rows) == 0 && len(users[i].RoleID) == 16 {
+			rows = []userRoleJoinRow{{
+				RoleID:          append([]byte(nil), users[i].RoleID...),
+				RoleName:        users[i].RoleName,
+				RoleDescription: users[i].RoleDescription,
+			}}
+		}
+
+		users[i].RoleIDs = make([][]byte, 0, len(rows))
+		users[i].Roles = make([]user.RoleSummary, 0, len(rows))
+		for j := range rows {
+			users[i].RoleIDs = append(users[i].RoleIDs, append([]byte(nil), rows[j].RoleID...))
+			users[i].Roles = append(users[i].Roles, user.RoleSummary{
+				ID:          append([]byte(nil), rows[j].RoleID...),
+				Name:        rows[j].RoleName,
+				Description: rows[j].RoleDescription,
+			})
+		}
+	}
+
+	return nil
+}
diff --git a/internal/repository/mysql/user_roles_test.go b/internal/repository/mysql/user_roles_test.go
new file mode 100644
index 0000000..cfe4d55
--- /dev/null
+++ b/internal/repository/mysql/user_roles_test.go
@@ -0,0 +1,101 @@
+package mysql
+
+import (
+	"context"
+	"testing"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/user"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func TestUserRepository_SyncsAndLoadsUserRoles(t *testing.T) {
+	db := openDBTestSQLite(t)
+	if err := AutoMigrate(db); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	pilotRoleID := uuidv7.MustBytes()
+	chiefPilotRoleID := uuidv7.MustBytes()
+	staffRoleID := uuidv7.MustBytes()
+	roles := []auth.Role{
+		{ID: pilotRoleID, Code: "pilot", Name: "pilot", Description: "Pilot"},
+		{ID: chiefPilotRoleID, Code: "chief_pilot", Name: "chief_pilot", Description: "Chief Pilot"},
+		{ID: staffRoleID, Code: "staff", Name: "staff", Description: "Staff"},
+	}
+	if err := db.Create(&roles).Error; err != nil {
+		t.Fatalf("create roles: %v", err)
+	}
+
+	repo := NewUserRepository(db)
+	ctx := context.Background()
+	u := &user.User{
+		Email:     "multi-role@example.com",
+		Username:  "multi.role",
+		FirstName: "Multi",
+		LastName:  "Role",
+		Timezone:  "UTC",
+		RoleID:    pilotRoleID,
+		RoleIDs:   [][]byte{pilotRoleID, chiefPilotRoleID},
+	}
+	if err := repo.Create(ctx, u); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	var count int64
+	if err := db.Model(&auth.UserRole{}).Where("user_id = ?", u.ID).Count(&count).Error; err != nil {
+		t.Fatalf("count user_roles: %v", err)
+	}
+	if count != 2 {
+		t.Fatalf("expected 2 user_roles rows, got %d", count)
+	}
+
+	got, err := repo.GetByID(ctx, u.ID)
+	if err != nil {
+		t.Fatalf("get by id: %v", err)
+	}
+	if got == nil {
+		t.Fatalf("expected user")
+	}
+	if len(got.RoleIDs) != 2 || len(got.Roles) != 2 {
+		t.Fatalf("expected two roles loaded, got roleIDs=%d roles=%d", len(got.RoleIDs), len(got.Roles))
+	}
+	if got.Roles[0].Name != "pilot" {
+		t.Fatalf("expected primary role first, got %q", got.Roles[0].Name)
+	}
+
+	list, total, err := repo.List(ctx, "", "", 10, 0)
+	if err != nil {
+		t.Fatalf("list users: %v", err)
+	}
+	if total != 1 || len(list) != 1 || len(list[0].Roles) != 2 {
+		t.Fatalf("expected list to include two roles, total=%d len=%d roles=%d", total, len(list), len(list[0].Roles))
+	}
+
+	got.RoleID = staffRoleID
+	got.RoleIDs = [][]byte{staffRoleID}
+	if err := repo.Update(ctx, got); err != nil {
+		t.Fatalf("update user roles: %v", err)
+	}
+
+	got, err = repo.GetByID(ctx, u.ID)
+	if err != nil {
+		t.Fatalf("get by id after update: %v", err)
+	}
+	if got == nil {
+		t.Fatalf("expected user after update")
+	}
+	if len(got.Roles) != 1 || got.Roles[0].Name != "staff" {
+		t.Fatalf("expected roles replaced with staff, got %+v", got.Roles)
+	}
+
+	if err := repo.Delete(ctx, u.ID); err != nil {
+		t.Fatalf("delete user: %v", err)
+	}
+	if err := db.Model(&auth.UserRole{}).Where("user_id = ?", u.ID).Count(&count).Error; err != nil {
+		t.Fatalf("count user_roles after delete: %v", err)
+	}
+	if count != 0 {
+		t.Fatalf("expected user_roles deleted, got %d", count)
+	}
+}
diff --git a/internal/repository/mysql/vocation_repo.go b/internal/repository/mysql/vocation_repo.go
new file mode 100644
index 0000000..6b17c28
--- /dev/null
+++ b/internal/repository/mysql/vocation_repo.go
@@ -0,0 +1,88 @@
+package mysql
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/vocation"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type VocationRepository struct {
+	db *gorm.DB
+}
+
+func NewVocationRepository(db *gorm.DB) *VocationRepository {
+	return &VocationRepository{db: db}
+}
+
+func (r *VocationRepository) Create(ctx context.Context, v *vocation.Vocation) error {
+	requestedIsActive := v.IsActive
+	db := r.db.WithContext(ctx)
+	if err := db.Create(v).Error; err != nil {
+		return err
+	}
+	return db.Model(&vocation.Vocation{}).Where("id = ?", v.ID).UpdateColumn("is_active", requestedIsActive).Error
+}
+
+func (r *VocationRepository) Update(ctx context.Context, v *vocation.Vocation) error {
+	return r.db.WithContext(ctx).Save(v).Error
+}
+
+func (r *VocationRepository) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if err := ensureNoReferenceBeforeDelete(ctx, r.db, "vocations", id); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	updates := map[string]any{
+		"deleted_at": now,
+		"deleted_by": deletedBy,
+		"updated_by": deletedBy,
+	}
+	return mapDeleteConstraintError(r.db.WithContext(ctx).
+		Model(&vocation.Vocation{}).
+		Where("id = ? AND deleted_at IS NULL", id).
+		Updates(updates).Error)
+}
+
+func (r *VocationRepository) GetByID(ctx context.Context, id []byte) (*vocation.Vocation, error) {
+	var row vocation.Vocation
+	err := r.db.WithContext(ctx).Where("id = ? AND deleted_at IS NULL", id).First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (r *VocationRepository) List(ctx context.Context, filter, sort string, limit, offset int) ([]vocation.Vocation, int64, error) {
+	var rows []vocation.Vocation
+	var total int64
+
+	base := r.db.WithContext(ctx).Model(&vocation.Vocation{}).Where("deleted_at IS NULL")
+	if filter != "" {
+		like := "%" + filter + "%"
+		base = base.Where("name LIKE ? OR note LIKE ?", like, like)
+	}
+
+	query := base
+	if sort != "" {
+		query = query.Order(sort)
+	} else {
+		for _, clause := range sortkey.ActivePositiveSortClauses("vocations", "is_active", "sortkey", "name", false) {
+			query = query.Order(clause)
+		}
+	}
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	if limit > 0 {
+		query = query.Limit(limit).Offset(offset)
+	}
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
diff --git a/internal/repository/mysql/vocation_repo_test.go b/internal/repository/mysql/vocation_repo_test.go
new file mode 100644
index 0000000..13421f8
--- /dev/null
+++ b/internal/repository/mysql/vocation_repo_test.go
@@ -0,0 +1,238 @@
+package mysql
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/vocation"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func openVocationTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:vocation_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{
+		NowFunc: func() time.Time { return time.Now().UTC() },
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&vocation.Vocation{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
+
+func TestNewVocationRepository(t *testing.T) {
+	db := openVocationTestDB(t)
+	repo := NewVocationRepository(db)
+	if repo == nil || repo.db == nil {
+		t.Fatalf("expected repository initialized")
+	}
+}
+
+func TestVocationRepositoryCreate(t *testing.T) {
+	db := openVocationTestDB(t)
+	repo := NewVocationRepository(db)
+	row := &vocation.Vocation{Name: "Main"}
+
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(row.ID) == 0 {
+		t.Fatalf("expected id set")
+	}
+	inactive := &vocation.Vocation{Name: "Inactive", IsActive: false}
+	if err := repo.Create(context.Background(), inactive); err != nil {
+		t.Fatalf("create inactive: %v", err)
+	}
+	gotInactive, err := repo.GetByID(context.Background(), inactive.ID)
+	if err != nil {
+		t.Fatalf("get inactive: %v", err)
+	}
+	if gotInactive == nil || gotInactive.IsActive {
+		t.Fatalf("expected inactive vocation persisted as false")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Create(context.Background(), &vocation.Vocation{Name: "AfterClose"}); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestVocationRepositoryUpdate(t *testing.T) {
+	db := openVocationTestDB(t)
+	repo := NewVocationRepository(db)
+	row := &vocation.Vocation{Name: "Old"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+
+	row.Name = "New"
+	if err := repo.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	loaded, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil || loaded == nil || loaded.Name != "New" {
+		t.Fatalf("expected updated row")
+	}
+
+	sqlDB, _ := db.DB()
+	_ = sqlDB.Close()
+	if err := repo.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error on closed DB")
+	}
+}
+
+func TestVocationRepositoryDelete(t *testing.T) {
+	db := openVocationTestDB(t)
+	repo := NewVocationRepository(db)
+	row := &vocation.Vocation{Name: "DeleteMe"}
+	if err := repo.Create(context.Background(), row); err != nil {
+		t.Fatalf("seed create: %v", err)
+	}
+	deletedBy := uuidv7.MustBytes()
+
+	if err := repo.Delete(context.Background(), row.ID, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	got, err := repo.GetByID(context.Background(), row.ID)
+	if err != nil {
+		t.Fatalf("get by id after delete: %v", err)
+	}
+	if got != nil {
+		t.Fatalf("expected soft deleted row hidden from GetByID")
+	}
+}
+
+func TestVocationRepositoryGetByID(t *testing.T) {
+	t.Run("found", func(t *testing.T) {
+		db := openVocationTestDB(t)
+		repo := NewVocationRepository(db)
+		row := &vocation.Vocation{Name: "Found"}
+		if err := repo.Create(context.Background(), row); err != nil {
+			t.Fatalf("seed create: %v", err)
+		}
+
+		got, err := repo.GetByID(context.Background(), row.ID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.Name != "Found" {
+			t.Fatalf("expected row found")
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		db := openVocationTestDB(t)
+		repo := NewVocationRepository(db)
+		got, err := repo.GetByID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil for not found")
+		}
+	})
+
+	t.Run("db error", func(t *testing.T) {
+		db := openVocationTestDB(t)
+		repo := NewVocationRepository(db)
+		sqlDB, _ := db.DB()
+		_ = sqlDB.Close()
+
+		if _, err := repo.GetByID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error on closed DB")
+		}
+	})
+}
+
+func TestVocationRepositoryList(t *testing.T) {
+	t.Run("success without limit", func(t *testing.T) {
+		db := openVocationTestDB(t)
+		repo := NewVocationRepository(db)
+		_ = repo.Create(context.Background(), &vocation.Vocation{Name: "C"})
+		_ = repo.Create(context.Background(), &vocation.Vocation{Name: "A"})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 2 || len(rows) != 2 {
+			t.Fatalf("expected 2 rows, total=%d len=%d", total, len(rows))
+		}
+	})
+
+	t.Run("success with filter sort and limit", func(t *testing.T) {
+		db := openVocationTestDB(t)
+		repo := NewVocationRepository(db)
+		_ = repo.Create(context.Background(), &vocation.Vocation{Name: "Main Base"})
+		_ = repo.Create(context.Background(), &vocation.Vocation{Name: "Backup"})
+
+		rows, total, err := repo.List(context.Background(), "Main", "name DESC", 1, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 1 || len(rows) != 1 || rows[0].Name != "Main Base" {
+			t.Fatalf("unexpected list result")
+		}
+	})
+
+	t.Run("count error", func(t *testing.T) {
+		db := openVocationTestDB(t)
+		repo := NewVocationRepository(db)
+		if err := db.Migrator().DropTable(&vocation.Vocation{}); err != nil {
+			t.Fatalf("drop table: %v", err)
+		}
+
+		if _, _, err := repo.List(context.Background(), "", "", 10, 0); err == nil {
+			t.Fatalf("expected count error")
+		}
+	})
+
+	t.Run("find error", func(t *testing.T) {
+		db := openVocationTestDB(t)
+		repo := NewVocationRepository(db)
+		_ = repo.Create(context.Background(), &vocation.Vocation{Name: "Main"})
+
+		if _, _, err := repo.List(context.Background(), "", "name ASC, )", 10, 0); err == nil {
+			t.Fatalf("expected find error from invalid sort")
+		}
+	})
+
+	t.Run("default order active sortkey first and inactive last", func(t *testing.T) {
+		db := openVocationTestDB(t)
+		repo := NewVocationRepository(db)
+		_ = repo.Create(context.Background(), &vocation.Vocation{Name: "Gamma", IsActive: true})
+		_ = repo.Create(context.Background(), &vocation.Vocation{Name: "Beta", SortKey: intPtrVocationRepo(0), IsActive: true})
+		_ = repo.Create(context.Background(), &vocation.Vocation{Name: "Charlie", SortKey: intPtrVocationRepo(2), IsActive: true})
+		_ = repo.Create(context.Background(), &vocation.Vocation{Name: "Alpha", SortKey: intPtrVocationRepo(1), IsActive: true})
+		_ = repo.Create(context.Background(), &vocation.Vocation{Name: "Zulu", IsActive: false})
+		_ = repo.Create(context.Background(), &vocation.Vocation{Name: "Bravo", SortKey: intPtrVocationRepo(9), IsActive: false})
+
+		rows, total, err := repo.List(context.Background(), "", "", 0, 0)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if total != 6 || len(rows) != 6 {
+			t.Fatalf("unexpected total/len total=%d len=%d", total, len(rows))
+		}
+
+		gotOrder := []string{rows[0].Name, rows[1].Name, rows[2].Name, rows[3].Name, rows[4].Name, rows[5].Name}
+		wantOrder := []string{"Beta", "Alpha", "Charlie", "Gamma", "Bravo", "Zulu"}
+		for i := range wantOrder {
+			if gotOrder[i] != wantOrder[i] {
+				t.Fatalf("unexpected default order: got=%v want=%v", gotOrder, wantOrder)
+			}
+		}
+	})
+}
+
+func intPtrVocationRepo(v int) *int { return &v }
diff --git a/internal/repository/s3/file_object_storage.go b/internal/repository/s3/file_object_storage.go
new file mode 100644
index 0000000..49d5dc3
--- /dev/null
+++ b/internal/repository/s3/file_object_storage.go
@@ -0,0 +1,430 @@
+package s3
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	awsv2 "github.com/aws/aws-sdk-go-v2/aws"
+	awsconfig "github.com/aws/aws-sdk-go-v2/config"
+	"github.com/aws/aws-sdk-go-v2/credentials"
+	awss3 "github.com/aws/aws-sdk-go-v2/service/s3"
+	"github.com/aws/aws-sdk-go-v2/service/s3/types"
+	"github.com/aws/smithy-go"
+
+	"wucher/internal/config"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/metrics"
+)
+
+type FileObjectStorage struct {
+	cfg       config.FileStorageConfig
+	client    *awss3.Client
+	presigner *awss3.PresignClient
+	component string
+}
+
+func NewFileObjectStorage(ctx context.Context, cfg config.FileStorageConfig) (*FileObjectStorage, error) {
+	if err := validateConfig(cfg); err != nil {
+		return nil, err
+	}
+
+	loadOptions := make([]func(*awsconfig.LoadOptions) error, 0, 3)
+	if cfg.Region != "" {
+		loadOptions = append(loadOptions, awsconfig.WithRegion(cfg.Region))
+	}
+	if strings.TrimSpace(cfg.Endpoint) != "" &&
+		strings.TrimSpace(cfg.AccessKeyID) != "" &&
+		strings.TrimSpace(cfg.SecretAccessKey) != "" {
+		loadOptions = append(loadOptions, awsconfig.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(
+			strings.TrimSpace(cfg.AccessKeyID),
+			strings.TrimSpace(cfg.SecretAccessKey),
+			"",
+		)))
+	}
+	awsCfg, err := awsconfig.LoadDefaultConfig(ctx, loadOptions...)
+	if err != nil {
+		return nil, err
+	}
+
+	client := awss3.NewFromConfig(awsCfg, func(options *awss3.Options) {
+		options.UsePathStyle = cfg.ForcePathStyle
+		if endpoint := strings.TrimSpace(cfg.Endpoint); endpoint != "" {
+			options.BaseEndpoint = awsv2.String(endpoint)
+		}
+	})
+
+	storage := &FileObjectStorage{
+		cfg:       cfg,
+		client:    client,
+		presigner: awss3.NewPresignClient(client),
+		component: "api",
+	}
+
+	if cfg.AutoCreateBucket {
+		if err := storage.EnsureBucket(ctx); err != nil {
+			return nil, err
+		}
+	}
+
+	return storage, nil
+}
+
+func (s *FileObjectStorage) EnsureBucket(ctx context.Context) error {
+	headStarted := time.Now()
+	if _, err := s.client.HeadBucket(ctx, &awss3.HeadBucketInput{
+		Bucket: awsv2.String(s.cfg.Bucket),
+	}); err == nil {
+		metrics.ObserveAWSRequest(s.component, "s3", "HeadBucket", nil, headStarted)
+		return nil
+	} else {
+		metrics.ObserveAWSRequest(s.component, "s3", "HeadBucket", err, headStarted)
+	}
+
+	input := &awss3.CreateBucketInput{
+		Bucket: awsv2.String(s.cfg.Bucket),
+	}
+	if s.cfg.Region != "" && s.cfg.Region != "us-east-1" {
+		input.CreateBucketConfiguration = &types.CreateBucketConfiguration{
+			LocationConstraint: types.BucketLocationConstraint(s.cfg.Region),
+		}
+	}
+
+	createStarted := time.Now()
+	_, err := s.client.CreateBucket(ctx, input)
+	metrics.ObserveAWSRequest(s.component, "s3", "CreateBucket", err, createStarted)
+	if err == nil {
+		return nil
+	}
+	if isBucketAlreadyOwnedByYou(err) {
+		return nil
+	}
+	return err
+}
+
+func (s *FileObjectStorage) PutObject(ctx context.Context, input filemanager.PutObjectInput) (filemanager.ObjectMetadata, error) {
+	objectKey := buildObjectKey(s.cfg.ObjectKeyPrefix, input.ObjectKey)
+
+	started := time.Now()
+	output, err := s.client.PutObject(ctx, &awss3.PutObjectInput{
+		Bucket:      awsv2.String(s.cfg.Bucket),
+		Key:         awsv2.String(objectKey),
+		Body:        input.Body,
+		ContentType: optionalString(input.ContentType),
+		Metadata:    input.Metadata,
+	})
+	metrics.ObserveAWSRequest(s.component, "s3", "PutObject", err, started)
+	metrics.ObserveFileUpload(s.component, err)
+	if err == nil {
+		metrics.ObserveAWSTransferredBytes(s.component, "s3", "PutObject", "upload", input.SizeBytes)
+	}
+	if err != nil {
+		return filemanager.ObjectMetadata{}, err
+	}
+
+	return filemanager.ObjectMetadata{
+		Bucket:    s.cfg.Bucket,
+		ObjectKey: objectKey,
+		ETag:      awsv2.ToString(output.ETag),
+		VersionID: awsv2.ToString(output.VersionId),
+	}, nil
+}
+
+func (s *FileObjectStorage) CopyObject(ctx context.Context, sourceObjectKey, destinationObjectKey string) (filemanager.ObjectMetadata, error) {
+	sourceKey := buildObjectKey(s.cfg.ObjectKeyPrefix, sourceObjectKey)
+	destinationKey := buildObjectKey(s.cfg.ObjectKeyPrefix, destinationObjectKey)
+
+	started := time.Now()
+	_, err := s.client.CopyObject(ctx, &awss3.CopyObjectInput{
+		Bucket:            awsv2.String(s.cfg.Bucket),
+		CopySource:        awsv2.String(url.PathEscape(s.cfg.Bucket + "/" + sourceKey)),
+		Key:               awsv2.String(destinationKey),
+		MetadataDirective: types.MetadataDirectiveCopy,
+	})
+	metrics.ObserveAWSRequest(s.component, "s3", "CopyObject", err, started)
+	if err != nil {
+		return filemanager.ObjectMetadata{}, err
+	}
+	return s.HeadObject(ctx, destinationObjectKey)
+}
+
+func (s *FileObjectStorage) DeleteObject(ctx context.Context, objectKey string) error {
+	started := time.Now()
+	_, err := s.client.DeleteObject(ctx, &awss3.DeleteObjectInput{
+		Bucket: awsv2.String(s.cfg.Bucket),
+		Key:    awsv2.String(buildObjectKey(s.cfg.ObjectKeyPrefix, objectKey)),
+	})
+	metrics.ObserveAWSRequest(s.component, "s3", "DeleteObject", err, started)
+	metrics.ObserveFileDelete(s.component, err)
+	return err
+}
+
+func (s *FileObjectStorage) PutObjectTagging(ctx context.Context, objectKey string, tags map[string]string) error {
+	if len(tags) == 0 {
+		return nil
+	}
+	key := buildObjectKey(s.cfg.ObjectKeyPrefix, objectKey)
+	tagSet := make([]types.Tag, 0, len(tags))
+	for k, v := range tags {
+		keyTag := strings.TrimSpace(k)
+		valueTag := strings.TrimSpace(v)
+		if keyTag == "" || valueTag == "" {
+			continue
+		}
+		tagSet = append(tagSet, types.Tag{
+			Key:   awsv2.String(keyTag),
+			Value: awsv2.String(valueTag),
+		})
+	}
+	if len(tagSet) == 0 {
+		return nil
+	}
+
+	started := time.Now()
+	_, err := s.client.PutObjectTagging(ctx, &awss3.PutObjectTaggingInput{
+		Bucket:  awsv2.String(s.cfg.Bucket),
+		Key:     awsv2.String(key),
+		Tagging: &types.Tagging{TagSet: tagSet},
+	})
+	metrics.ObserveAWSRequest(s.component, "s3", "PutObjectTagging", err, started)
+	return err
+}
+
+func (s *FileObjectStorage) DeleteObjectTaggingKeys(ctx context.Context, objectKey string, keys []string) error {
+	if len(keys) == 0 {
+		return nil
+	}
+	key := buildObjectKey(s.cfg.ObjectKeyPrefix, objectKey)
+
+	started := time.Now()
+	existing, err := s.client.GetObjectTagging(ctx, &awss3.GetObjectTaggingInput{
+		Bucket: awsv2.String(s.cfg.Bucket),
+		Key:    awsv2.String(key),
+	})
+	metrics.ObserveAWSRequest(s.component, "s3", "GetObjectTagging", err, started)
+	if err != nil {
+		return err
+	}
+	removed := make(map[string]struct{}, len(keys))
+	for i := range keys {
+		k := strings.TrimSpace(keys[i])
+		if k == "" {
+			continue
+		}
+		removed[k] = struct{}{}
+	}
+	tagSet := make([]types.Tag, 0, len(existing.TagSet))
+	for i := range existing.TagSet {
+		tagKey := strings.TrimSpace(awsv2.ToString(existing.TagSet[i].Key))
+		if _, drop := removed[tagKey]; drop {
+			continue
+		}
+		tagSet = append(tagSet, existing.TagSet[i])
+	}
+
+	started = time.Now()
+	_, err = s.client.PutObjectTagging(ctx, &awss3.PutObjectTaggingInput{
+		Bucket:  awsv2.String(s.cfg.Bucket),
+		Key:     awsv2.String(key),
+		Tagging: &types.Tagging{TagSet: tagSet},
+	})
+	metrics.ObserveAWSRequest(s.component, "s3", "PutObjectTagging", err, started)
+	return err
+}
+
+func (s *FileObjectStorage) HeadObject(ctx context.Context, objectKey string) (filemanager.ObjectMetadata, error) {
+	key := buildObjectKey(s.cfg.ObjectKeyPrefix, objectKey)
+	started := time.Now()
+	output, err := s.client.HeadObject(ctx, &awss3.HeadObjectInput{
+		Bucket: awsv2.String(s.cfg.Bucket),
+		Key:    awsv2.String(key),
+	})
+	metrics.ObserveAWSRequest(s.component, "s3", "HeadObject", err, started)
+	metrics.ObserveFileHead(s.component, err)
+	if err != nil {
+		if isObjectNotFoundError(err) {
+			return filemanager.ObjectMetadata{}, filemanager.ErrUploadObjectNotFound
+		}
+		return filemanager.ObjectMetadata{}, err
+	}
+
+	return filemanager.ObjectMetadata{
+		Bucket:       s.cfg.Bucket,
+		ObjectKey:    key,
+		ETag:         awsv2.ToString(output.ETag),
+		VersionID:    awsv2.ToString(output.VersionId),
+		SizeBytes:    awsv2.ToInt64(output.ContentLength),
+		LastModified: output.LastModified,
+		ContentType:  awsv2.ToString(output.ContentType),
+	}, nil
+}
+
+func (s *FileObjectStorage) GetObject(ctx context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+	key := buildObjectKey(s.cfg.ObjectKeyPrefix, objectKey)
+	started := time.Now()
+	output, err := s.client.GetObject(ctx, &awss3.GetObjectInput{
+		Bucket: awsv2.String(s.cfg.Bucket),
+		Key:    awsv2.String(key),
+	})
+	metrics.ObserveAWSRequest(s.component, "s3", "GetObject", err, started)
+	if err != nil {
+		if isObjectNotFoundError(err) {
+			return nil, filemanager.ObjectMetadata{}, filemanager.ErrUploadObjectNotFound
+		}
+		return nil, filemanager.ObjectMetadata{}, err
+	}
+
+	metrics.ObserveAWSTransferredBytes(s.component, "s3", "GetObject", "download", awsv2.ToInt64(output.ContentLength))
+	return output.Body, filemanager.ObjectMetadata{
+		Bucket:       s.cfg.Bucket,
+		ObjectKey:    key,
+		ETag:         awsv2.ToString(output.ETag),
+		VersionID:    awsv2.ToString(output.VersionId),
+		SizeBytes:    awsv2.ToInt64(output.ContentLength),
+		LastModified: output.LastModified,
+		ContentType:  awsv2.ToString(output.ContentType),
+	}, nil
+}
+
+func (s *FileObjectStorage) PresignPutObject(ctx context.Context, input filemanager.PresignPutObjectInput) (filemanager.PresignedPutObject, error) {
+	key := buildObjectKey(s.cfg.ObjectKeyPrefix, input.ObjectKey)
+	ttl := input.TTL
+	if ttl <= 0 {
+		ttl = s.cfg.PresignPutTTL
+	}
+	if ttl <= 0 {
+		ttl = 15 * time.Minute
+	}
+
+	putInput := &awss3.PutObjectInput{
+		Bucket:      awsv2.String(s.cfg.Bucket),
+		Key:         awsv2.String(key),
+		ContentType: optionalString(input.ContentType),
+		Metadata:    input.Metadata,
+	}
+
+	output, err := s.presigner.PresignPutObject(ctx, putInput, func(options *awss3.PresignOptions) {
+		options.Expires = ttl
+	})
+	if err != nil {
+		return filemanager.PresignedPutObject{}, err
+	}
+
+	return filemanager.PresignedPutObject{
+		Bucket:    s.cfg.Bucket,
+		ObjectKey: key,
+		Method:    output.Method,
+		URL:       output.URL,
+		Headers:   canonicalSignedHeaders(output.SignedHeader),
+		ExpiresAt: time.Now().UTC().Add(ttl),
+	}, nil
+}
+
+func (s *FileObjectStorage) PresignGetObject(ctx context.Context, objectKey string, ttl time.Duration) (string, error) {
+	if ttl <= 0 {
+		ttl = s.cfg.PresignGetTTL
+	}
+
+	started := time.Now()
+	output, err := s.presigner.PresignGetObject(ctx, &awss3.GetObjectInput{
+		Bucket: awsv2.String(s.cfg.Bucket),
+		Key:    awsv2.String(buildObjectKey(s.cfg.ObjectKeyPrefix, objectKey)),
+	}, func(options *awss3.PresignOptions) {
+		options.Expires = ttl
+	})
+	metrics.ObserveAWSRequest(s.component, "s3", "GetObject", err, started)
+	metrics.ObserveFilePresignDownload(s.component, err)
+	if err != nil {
+		return "", err
+	}
+	return output.URL, nil
+}
+
+func validateConfig(cfg config.FileStorageConfig) error {
+	if strings.ToLower(strings.TrimSpace(cfg.Provider)) != "s3" {
+		return errors.New("unsupported file storage provider")
+	}
+	if strings.TrimSpace(cfg.Bucket) == "" {
+		return errors.New("file storage bucket is required")
+	}
+	if strings.TrimSpace(cfg.Region) == "" {
+		return errors.New("file storage region is required")
+	}
+	if endpoint := strings.TrimSpace(cfg.Endpoint); endpoint != "" {
+		parsed, err := url.Parse(endpoint)
+		if err != nil {
+			return err
+		}
+		if parsed.Scheme != "https" && !cfg.AllowInsecureEndpoint {
+			return errors.New("insecure file storage endpoint is disabled")
+		}
+	}
+	return nil
+}
+
+func buildObjectKey(prefix, objectKey string) string {
+	objectKey = strings.TrimSpace(objectKey)
+	objectKey = strings.TrimPrefix(objectKey, "/")
+	objectKey = strings.TrimPrefix(objectKey, "./")
+	if objectKey == "" {
+		return objectKey
+	}
+
+	prefix = strings.TrimSpace(prefix)
+	prefix = strings.Trim(prefix, "/")
+	if prefix == "" {
+		return objectKey
+	}
+	if objectKey == prefix || strings.HasPrefix(objectKey, prefix+"/") {
+		return objectKey
+	}
+	return prefix + "/" + objectKey
+}
+
+func optionalString(value string) *string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return nil
+	}
+	return awsv2.String(value)
+}
+
+func isBucketAlreadyOwnedByYou(err error) bool {
+	var apiErr smithy.APIError
+	if !errors.As(err, &apiErr) {
+		return false
+	}
+	return apiErr.ErrorCode() == "BucketAlreadyOwnedByYou" || apiErr.ErrorCode() == "BucketAlreadyExists"
+}
+
+func isObjectNotFoundError(err error) bool {
+	var apiErr smithy.APIError
+	if !errors.As(err, &apiErr) {
+		return false
+	}
+	switch strings.TrimSpace(apiErr.ErrorCode()) {
+	case "NotFound", "NoSuchKey", "404":
+		return true
+	default:
+		return false
+	}
+}
+
+func canonicalSignedHeaders(header http.Header) map[string]string {
+	if len(header) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(header))
+	for key, values := range header {
+		k := strings.TrimSpace(strings.ToLower(key))
+		if k == "" || len(values) == 0 {
+			continue
+		}
+		out[k] = strings.TrimSpace(values[0])
+	}
+	return out
+}
diff --git a/internal/repository/s3/file_object_storage_test.go b/internal/repository/s3/file_object_storage_test.go
new file mode 100644
index 0000000..58a6546
--- /dev/null
+++ b/internal/repository/s3/file_object_storage_test.go
@@ -0,0 +1,76 @@
+package s3
+
+import (
+	"net/http"
+	"testing"
+
+	"wucher/internal/config"
+)
+
+func TestValidateConfig(t *testing.T) {
+	valid := config.FileStorageConfig{
+		Provider:              "s3",
+		Bucket:                "wucher-file-dev",
+		Region:                "ap-southeast-1",
+		Endpoint:              "http://localhost:4566",
+		AllowInsecureEndpoint: true,
+	}
+
+	if err := validateConfig(valid); err != nil {
+		t.Fatalf("expected valid config, got %v", err)
+	}
+
+	invalidProvider := valid
+	invalidProvider.Provider = "local"
+	if err := validateConfig(invalidProvider); err == nil {
+		t.Fatalf("expected invalid provider error")
+	}
+
+	missingBucket := valid
+	missingBucket.Bucket = ""
+	if err := validateConfig(missingBucket); err == nil {
+		t.Fatalf("expected missing bucket error")
+	}
+
+	invalidEndpoint := valid
+	invalidEndpoint.Endpoint = "://bad-url"
+	if err := validateConfig(invalidEndpoint); err == nil {
+		t.Fatalf("expected invalid endpoint error")
+	}
+
+	httpEndpointBlocked := valid
+	httpEndpointBlocked.AllowInsecureEndpoint = false
+	if err := validateConfig(httpEndpointBlocked); err == nil {
+		t.Fatalf("expected insecure endpoint error")
+	}
+}
+
+func TestBuildObjectKey(t *testing.T) {
+	if got := buildObjectKey("fm/objects", "abc/123"); got != "fm/objects/abc/123" {
+		t.Fatalf("unexpected key: %q", got)
+	}
+	if got := buildObjectKey("fm/objects/", "/abc/123"); got != "fm/objects/abc/123" {
+		t.Fatalf("unexpected key with slashes: %q", got)
+	}
+	if got := buildObjectKey("fm/objects", "fm/objects/abc/123"); got != "fm/objects/abc/123" {
+		t.Fatalf("unexpected key with existing prefix: %q", got)
+	}
+	if got := buildObjectKey("", "abc/123"); got != "abc/123" {
+		t.Fatalf("unexpected key without prefix: %q", got)
+	}
+}
+
+func TestCanonicalSignedHeaders(t *testing.T) {
+	headers := http.Header{
+		"Content-Type": []string{"application/pdf"},
+		"X-Amz-Date":   []string{"20260405T000000Z"},
+	}
+
+	got := canonicalSignedHeaders(headers)
+	if got["content-type"] != "application/pdf" {
+		t.Fatalf("unexpected content-type header: %q", got["content-type"])
+	}
+	if got["x-amz-date"] != "20260405T000000Z" {
+		t.Fatalf("unexpected x-amz-date header: %q", got["x-amz-date"])
+	}
+}
diff --git a/internal/repository/sqs/email_queue.go b/internal/repository/sqs/email_queue.go
new file mode 100644
index 0000000..5893677
--- /dev/null
+++ b/internal/repository/sqs/email_queue.go
@@ -0,0 +1,356 @@
+package sqs
+
+import (
+	"context"
+	"errors"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	awsv2 "github.com/aws/aws-sdk-go-v2/aws"
+	awsconfig "github.com/aws/aws-sdk-go-v2/config"
+	"github.com/aws/aws-sdk-go-v2/credentials"
+	"github.com/aws/aws-sdk-go-v2/service/sqs"
+	sqstypes "github.com/aws/aws-sdk-go-v2/service/sqs/types"
+
+	appconfig "wucher/internal/config"
+	"wucher/internal/shared/pkg/metrics"
+	"wucher/internal/queue"
+)
+
+type API interface {
+	SendMessage(ctx context.Context, params *sqs.SendMessageInput, optFns ...func(*sqs.Options)) (*sqs.SendMessageOutput, error)
+	ReceiveMessage(ctx context.Context, params *sqs.ReceiveMessageInput, optFns ...func(*sqs.Options)) (*sqs.ReceiveMessageOutput, error)
+	DeleteMessageBatch(ctx context.Context, params *sqs.DeleteMessageBatchInput, optFns ...func(*sqs.Options)) (*sqs.DeleteMessageBatchOutput, error)
+	ChangeMessageVisibility(ctx context.Context, params *sqs.ChangeMessageVisibilityInput, optFns ...func(*sqs.Options)) (*sqs.ChangeMessageVisibilityOutput, error)
+	GetQueueAttributes(ctx context.Context, params *sqs.GetQueueAttributesInput, optFns ...func(*sqs.Options)) (*sqs.GetQueueAttributesOutput, error)
+}
+
+type EmailQueue struct {
+	api               API
+	queueURL          string
+	queueName         string
+	component         string
+	queueType         string
+	messageGroupID    string
+	maxMessages       int
+	waitTimeSeconds   int32
+	visibilityTimeout int32
+}
+
+type QueueOption func(*EmailQueue)
+
+func WithMetricsComponent(component string) QueueOption {
+	return func(q *EmailQueue) {
+		if q == nil {
+			return
+		}
+		component = strings.TrimSpace(component)
+		if component == "" {
+			return
+		}
+		q.component = component
+	}
+}
+
+func NewClient(ctx context.Context, cfg appconfig.SQSConfig) (*sqs.Client, error) {
+	if err := validateConfig(cfg); err != nil {
+		return nil, err
+	}
+	loadOptions := make([]func(*awsconfig.LoadOptions) error, 0, 1)
+	if strings.TrimSpace(cfg.Region) != "" {
+		loadOptions = append(loadOptions, awsconfig.WithRegion(strings.TrimSpace(cfg.Region)))
+	}
+	if key := strings.TrimSpace(cfg.AccessKeyID); key != "" {
+		secret := strings.TrimSpace(cfg.SecretAccessKey)
+		loadOptions = append(loadOptions, awsconfig.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(key, secret, "")))
+	}
+	awsCfg, err := awsconfig.LoadDefaultConfig(ctx, loadOptions...)
+	if err != nil {
+		return nil, err
+	}
+	client := sqs.NewFromConfig(awsCfg, func(options *sqs.Options) {
+		if endpoint := strings.TrimSpace(cfg.Endpoint); endpoint != "" {
+			options.EndpointResolver = sqs.EndpointResolverFromURL(endpoint)
+		}
+	})
+	return client, nil
+}
+
+func NewEmailQueue(api API, cfg appconfig.SQSConfig, opts ...QueueOption) (*EmailQueue, error) {
+	return NewQueue(api, cfg, opts...)
+}
+
+func NewQueue(api API, cfg appconfig.SQSConfig, opts ...QueueOption) (*EmailQueue, error) {
+	if err := validateConfig(cfg); err != nil {
+		return nil, err
+	}
+	if api == nil {
+		return nil, errors.New("sqs client is required")
+	}
+	waitTimeSeconds := cfg.WaitTimeSeconds
+	if waitTimeSeconds <= 0 {
+		waitTimeSeconds = 20
+	}
+	if waitTimeSeconds > 20 {
+		waitTimeSeconds = 20
+	}
+	maxMessages := cfg.MaxMessages
+	if maxMessages <= 0 {
+		maxMessages = 10
+	}
+	if maxMessages > 10 {
+		maxMessages = 10
+	}
+	visibilityTimeout := int32(cfg.VisibilityTimeout.Seconds())
+	if visibilityTimeout <= 0 {
+		visibilityTimeout = 60
+	}
+	if visibilityTimeout > 43200 {
+		visibilityTimeout = 43200
+	}
+	queueType := strings.ToLower(strings.TrimSpace(cfg.QueueType))
+	if queueType == "" {
+		queueType = queue.QueueTypeStandard
+	}
+	queue := &EmailQueue{
+		api:               api,
+		queueURL:          strings.TrimSpace(cfg.QueueURL),
+		queueName:         metrics.QueueNameFromURL(cfg.QueueURL),
+		component:         "worker",
+		queueType:         queueType,
+		messageGroupID:    strings.TrimSpace(cfg.MessageGroupID),
+		maxMessages:       maxMessages,
+		waitTimeSeconds:   waitTimeSeconds,
+		visibilityTimeout: visibilityTimeout,
+	}
+	for _, opt := range opts {
+		if opt != nil {
+			opt(queue)
+		}
+	}
+	metrics.InitializeQueueSeries(queue.component, queue.queueName)
+	return queue, nil
+}
+
+func (q *EmailQueue) Backend() string {
+	return queue.BackendSQS
+}
+
+func (q *EmailQueue) Publish(ctx context.Context, message queue.OutboundMessage) error {
+	input := &sqs.SendMessageInput{
+		QueueUrl:    awsv2.String(q.queueURL),
+		MessageBody: awsv2.String(string(message.Body)),
+	}
+	if len(message.Attributes) > 0 {
+		input.MessageAttributes = make(map[string]sqstypes.MessageAttributeValue, len(message.Attributes))
+		for key, value := range message.Attributes {
+			v := value
+			input.MessageAttributes[key] = sqstypes.MessageAttributeValue{
+				DataType:    awsv2.String("String"),
+				StringValue: awsv2.String(v),
+			}
+		}
+	}
+	if q.queueType == queue.QueueTypeFIFO {
+		groupID := strings.TrimSpace(message.MessageGroupID)
+		if groupID == "" {
+			groupID = q.messageGroupID
+		}
+		if groupID == "" {
+			groupID = "default"
+		}
+		deduplicationID := strings.TrimSpace(message.DeduplicationID)
+		if deduplicationID == "" {
+			deduplicationID = message.ID
+		}
+		input.MessageGroupId = awsv2.String(groupID)
+		input.MessageDeduplicationId = awsv2.String(deduplicationID)
+	}
+	started := time.Now()
+	_, err := q.api.SendMessage(ctx, input)
+	metrics.ObserveQueueSend(q.component, q.queueName, int64(len(message.Body)), err, started)
+	return err
+}
+
+func (q *EmailQueue) Receive(ctx context.Context, maxMessages int) ([]*queue.Delivery, error) {
+	if maxMessages <= 0 {
+		maxMessages = 1
+	}
+	if q.maxMessages > 0 && maxMessages > q.maxMessages {
+		maxMessages = q.maxMessages
+	}
+	if maxMessages > 10 {
+		maxMessages = 10
+	}
+	started := time.Now()
+	output, err := q.api.ReceiveMessage(ctx, &sqs.ReceiveMessageInput{
+		QueueUrl:            awsv2.String(q.queueURL),
+		MaxNumberOfMessages: int32(maxMessages),
+		WaitTimeSeconds:     q.waitTimeSeconds,
+		VisibilityTimeout:   q.visibilityTimeout,
+		MessageSystemAttributeNames: []sqstypes.MessageSystemAttributeName{
+			sqstypes.MessageSystemAttributeNameApproximateReceiveCount,
+			sqstypes.MessageSystemAttributeNameSentTimestamp,
+		},
+		MessageAttributeNames: []string{"All"},
+	})
+	if err != nil {
+		metrics.ObserveQueueReceive(q.component, q.queueName, 0, 0, err, started)
+		return nil, err
+	}
+	var totalMessageBytes int64
+	for i := range output.Messages {
+		totalMessageBytes += int64(len(awsv2.ToString(output.Messages[i].Body)))
+	}
+	metrics.ObserveQueueReceive(q.component, q.queueName, len(output.Messages), totalMessageBytes, nil, started)
+
+	deliveries := make([]*queue.Delivery, 0, len(output.Messages))
+	for _, message := range output.Messages {
+		attributes := make(map[string]string, len(message.MessageAttributes))
+		for key, value := range message.MessageAttributes {
+			if value.StringValue != nil {
+				attributes[key] = *value.StringValue
+			}
+		}
+		receiveCount, _ := strconv.Atoi(message.Attributes[string(sqstypes.MessageSystemAttributeNameApproximateReceiveCount)])
+		sentAt := time.Now().UTC()
+		if raw := message.Attributes[string(sqstypes.MessageSystemAttributeNameSentTimestamp)]; raw != "" {
+			if millis, convErr := strconv.ParseInt(raw, 10, 64); convErr == nil {
+				sentAt = time.UnixMilli(millis).UTC()
+			}
+		}
+		body := awsv2.ToString(message.Body)
+		deliveries = append(deliveries, &queue.Delivery{
+			ID:            awsv2.ToString(message.MessageId),
+			ReceiptHandle: awsv2.ToString(message.ReceiptHandle),
+			Body:          []byte(body),
+			Attributes:    attributes,
+			ReceiveCount:  receiveCount,
+			EnqueuedAt:    sentAt,
+		})
+	}
+	return deliveries, nil
+}
+
+func (q *EmailQueue) Ack(ctx context.Context, deliveries []*queue.Delivery) error {
+	if len(deliveries) == 0 {
+		return nil
+	}
+	entries := make([]sqstypes.DeleteMessageBatchRequestEntry, 0, len(deliveries))
+	for i, delivery := range deliveries {
+		if delivery == nil || strings.TrimSpace(delivery.ReceiptHandle) == "" {
+			continue
+		}
+		entries = append(entries, sqstypes.DeleteMessageBatchRequestEntry{
+			Id:            awsv2.String(strconv.Itoa(i)),
+			ReceiptHandle: awsv2.String(delivery.ReceiptHandle),
+		})
+	}
+	if len(entries) == 0 {
+		return nil
+	}
+	started := time.Now()
+	output, err := q.api.DeleteMessageBatch(ctx, &sqs.DeleteMessageBatchInput{
+		QueueUrl: awsv2.String(q.queueURL),
+		Entries:  entries,
+	})
+	if err != nil {
+		metrics.ObserveQueueDeleteBatch(q.component, q.queueName, 0, err, started)
+		return err
+	}
+	if len(output.Failed) > 0 {
+		batchErr := errors.New("sqs batch delete reported failures")
+		metrics.ObserveQueueDeleteBatch(q.component, q.queueName, len(output.Successful), batchErr, started)
+		return batchErr
+	}
+	metrics.ObserveQueueDeleteBatch(q.component, q.queueName, len(output.Successful), nil, started)
+	return nil
+}
+
+func (q *EmailQueue) Retry(ctx context.Context, delivery *queue.Delivery, delay time.Duration) error {
+	if delivery == nil {
+		return nil
+	}
+	seconds := int32(delay.Seconds())
+	if seconds < 0 {
+		seconds = 0
+	}
+	if seconds > 43200 {
+		seconds = 43200
+	}
+	started := time.Now()
+	_, err := q.api.ChangeMessageVisibility(ctx, &sqs.ChangeMessageVisibilityInput{
+		QueueUrl:          awsv2.String(q.queueURL),
+		ReceiptHandle:     awsv2.String(delivery.ReceiptHandle),
+		VisibilityTimeout: seconds,
+	})
+	metrics.ObserveQueueVisibilityChange(q.component, q.queueName, err, started)
+	return err
+}
+
+func (q *EmailQueue) DeadLetter(ctx context.Context, delivery *queue.Delivery, reason string, cause error) error {
+	// Leave the message unacked so SQS redrive policy can move it to the queue DLQ.
+	_ = ctx
+	_ = delivery
+	_ = reason
+	_ = cause
+	return nil
+}
+
+func (q *EmailQueue) ApproximateDepth(ctx context.Context) (int64, error) {
+	started := time.Now()
+	output, err := q.api.GetQueueAttributes(ctx, &sqs.GetQueueAttributesInput{
+		QueueUrl: awsv2.String(q.queueURL),
+		AttributeNames: []sqstypes.QueueAttributeName{
+			sqstypes.QueueAttributeNameApproximateNumberOfMessages,
+			sqstypes.QueueAttributeNameApproximateNumberOfMessagesNotVisible,
+		},
+	})
+	if err != nil {
+		metrics.ObserveQueueDepth(q.component, q.queueName, 0, err, started)
+		return 0, err
+	}
+	visible, _ := strconv.ParseInt(output.Attributes[string(sqstypes.QueueAttributeNameApproximateNumberOfMessages)], 10, 64)
+	inFlight, _ := strconv.ParseInt(output.Attributes[string(sqstypes.QueueAttributeNameApproximateNumberOfMessagesNotVisible)], 10, 64)
+	depth := visible + inFlight
+	metrics.ObserveQueueDepth(q.component, q.queueName, depth, nil, started)
+	return depth, nil
+}
+
+func (q *EmailQueue) Close() error {
+	return nil
+}
+
+func validateConfig(cfg appconfig.SQSConfig) error {
+	if strings.TrimSpace(cfg.QueueURL) == "" {
+		return errors.New("sqs queue url is required")
+	}
+	if strings.TrimSpace(cfg.Region) == "" {
+		return errors.New("aws region is required")
+	}
+	if endpoint := strings.TrimSpace(cfg.Endpoint); endpoint != "" {
+		parsed, err := url.Parse(endpoint)
+		if err != nil {
+			return err
+		}
+		if parsed.Scheme != "https" && !cfg.AllowInsecureEndpoint {
+			return errors.New("insecure sqs endpoint is disabled")
+		}
+	}
+	queueType := strings.ToLower(strings.TrimSpace(cfg.QueueType))
+	if queueType == "" {
+		queueType = queue.QueueTypeStandard
+	}
+	switch queueType {
+	case queue.QueueTypeStandard:
+	case queue.QueueTypeFIFO:
+		if strings.TrimSpace(cfg.MessageGroupID) == "" {
+			return errors.New("sqs message group id is required for fifo queues")
+		}
+	default:
+		return errors.New("unsupported sqs queue type")
+	}
+	return nil
+}
diff --git a/internal/repository/sqs/email_queue_test.go b/internal/repository/sqs/email_queue_test.go
new file mode 100644
index 0000000..8291def
--- /dev/null
+++ b/internal/repository/sqs/email_queue_test.go
@@ -0,0 +1,236 @@
+package sqs
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"testing"
+	"time"
+
+	awsv2 "github.com/aws/aws-sdk-go-v2/aws"
+	"github.com/aws/aws-sdk-go-v2/service/sqs"
+	sqstypes "github.com/aws/aws-sdk-go-v2/service/sqs/types"
+	"github.com/aws/smithy-go"
+
+	"wucher/internal/config"
+	"wucher/internal/queue"
+	"wucher/internal/resilience"
+)
+
+type mockAPI struct {
+	sendInput             *sqs.SendMessageInput
+	receiveInput          *sqs.ReceiveMessageInput
+	deleteBatchInput      *sqs.DeleteMessageBatchInput
+	changeVisibilityInput *sqs.ChangeMessageVisibilityInput
+	getAttributesInput    *sqs.GetQueueAttributesInput
+	sendErr               error
+	receiveErr            error
+	deleteBatchErr        error
+	changeVisibilityErr   error
+	getAttributesErr      error
+	sendCalls             int
+	receiveCalls          int
+}
+
+func (m *mockAPI) SendMessage(_ context.Context, params *sqs.SendMessageInput, _ ...func(*sqs.Options)) (*sqs.SendMessageOutput, error) {
+	m.sendCalls++
+	m.sendInput = params
+	if m.sendErr != nil {
+		return nil, m.sendErr
+	}
+	return &sqs.SendMessageOutput{}, nil
+}
+
+func (m *mockAPI) ReceiveMessage(_ context.Context, params *sqs.ReceiveMessageInput, _ ...func(*sqs.Options)) (*sqs.ReceiveMessageOutput, error) {
+	m.receiveCalls++
+	m.receiveInput = params
+	if m.receiveErr != nil {
+		return nil, m.receiveErr
+	}
+	return &sqs.ReceiveMessageOutput{
+		Messages: []sqstypes.Message{{
+			MessageId:     awsv2.String("msg-1"),
+			ReceiptHandle: awsv2.String("receipt-1"),
+			Body:          awsv2.String(`{"version":"v1","message_id":"msg-1","kind":"email.dispatch","occurred_at":"2026-03-19T00:00:00Z","payload":{"to":"user@example.com","subject":"Hello","body":"World"}}`),
+			MessageAttributes: map[string]sqstypes.MessageAttributeValue{
+				"correlation_id": {DataType: awsv2.String("String"), StringValue: awsv2.String("req-1")},
+			},
+			Attributes: map[string]string{
+				string(sqstypes.MessageSystemAttributeNameApproximateReceiveCount): "3",
+				string(sqstypes.MessageSystemAttributeNameSentTimestamp):           "1710806400000",
+			},
+		}},
+	}, nil
+}
+
+func (m *mockAPI) DeleteMessageBatch(_ context.Context, params *sqs.DeleteMessageBatchInput, _ ...func(*sqs.Options)) (*sqs.DeleteMessageBatchOutput, error) {
+	m.deleteBatchInput = params
+	if m.deleteBatchErr != nil {
+		return nil, m.deleteBatchErr
+	}
+	return &sqs.DeleteMessageBatchOutput{}, nil
+}
+
+func (m *mockAPI) ChangeMessageVisibility(_ context.Context, params *sqs.ChangeMessageVisibilityInput, _ ...func(*sqs.Options)) (*sqs.ChangeMessageVisibilityOutput, error) {
+	m.changeVisibilityInput = params
+	if m.changeVisibilityErr != nil {
+		return nil, m.changeVisibilityErr
+	}
+	return &sqs.ChangeMessageVisibilityOutput{}, nil
+}
+
+func (m *mockAPI) GetQueueAttributes(_ context.Context, params *sqs.GetQueueAttributesInput, _ ...func(*sqs.Options)) (*sqs.GetQueueAttributesOutput, error) {
+	m.getAttributesInput = params
+	if m.getAttributesErr != nil {
+		return nil, m.getAttributesErr
+	}
+	return &sqs.GetQueueAttributesOutput{
+		Attributes: map[string]string{
+			string(sqstypes.QueueAttributeNameApproximateNumberOfMessages):           "5",
+			string(sqstypes.QueueAttributeNameApproximateNumberOfMessagesNotVisible): "2",
+		},
+	}, nil
+}
+
+func TestEmailQueuePublishReceiveAckRetryDeadLetter(t *testing.T) {
+	api := &mockAPI{}
+	cfg := config.SQSConfig{
+		Region:            "ap-southeast-1",
+		QueueURL:          "https://sqs.ap-southeast-1.amazonaws.com/123/test",
+		QueueType:         queue.QueueTypeFIFO,
+		MessageGroupID:    "email",
+		VisibilityTimeout: 30 * time.Second,
+		WaitTimeSeconds:   20,
+	}
+	q, err := NewEmailQueue(api, cfg)
+	if err != nil {
+		t.Fatalf("new queue: %v", err)
+	}
+
+	err = q.Publish(context.Background(), queue.OutboundMessage{
+		ID:              "msg-1",
+		Body:            []byte(`{"hello":"world"}`),
+		Attributes:      map[string]string{"correlation_id": "req-1"},
+		MessageGroupID:  "email",
+		DeduplicationID: "dedup-1",
+	})
+	if err != nil {
+		t.Fatalf("publish: %v", err)
+	}
+	if api.sendInput == nil || awsv2.ToString(api.sendInput.MessageGroupId) != "email" {
+		t.Fatalf("expected fifo publish settings")
+	}
+
+	deliveries, err := q.Receive(context.Background(), 5)
+	if err != nil {
+		t.Fatalf("receive: %v", err)
+	}
+	if len(deliveries) != 1 || deliveries[0].ReceiveCount != 3 {
+		t.Fatalf("unexpected deliveries: %+v", deliveries)
+	}
+
+	if err := q.Ack(context.Background(), deliveries); err != nil {
+		t.Fatalf("ack: %v", err)
+	}
+	if api.deleteBatchInput == nil || len(api.deleteBatchInput.Entries) != 1 {
+		t.Fatalf("expected batch delete")
+	}
+
+	if err := q.Retry(context.Background(), deliveries[0], 45*time.Second); err != nil {
+		t.Fatalf("retry: %v", err)
+	}
+	if api.changeVisibilityInput == nil || api.changeVisibilityInput.VisibilityTimeout != 45 {
+		t.Fatalf("expected retry visibility timeout 45")
+	}
+
+	if err := q.DeadLetter(context.Background(), deliveries[0], "permanent failure", nil); err != nil {
+		t.Fatalf("dead-letter: %v", err)
+	}
+	if got := awsv2.ToString(api.sendInput.MessageBody); got != `{"hello":"world"}` {
+		t.Fatalf("expected dead-letter path to leave message managed by SQS redrive, got send body %q", got)
+	}
+
+	depth, err := q.ApproximateDepth(context.Background())
+	if err != nil {
+		t.Fatalf("depth: %v", err)
+	}
+	if depth != 7 {
+		t.Fatalf("expected depth 7, got %d", depth)
+	}
+}
+
+func TestValidateConfigRejectsInsecureEndpoint(t *testing.T) {
+	err := validateConfig(config.SQSConfig{
+		Region:   "ap-southeast-1",
+		QueueURL: "https://sqs.ap-southeast-1.amazonaws.com/123/test",
+		Endpoint: "http://localhost:4566",
+	})
+	if err == nil {
+		t.Fatalf("expected insecure endpoint validation error")
+	}
+}
+
+func TestResilientAPI_CircuitBreaker(t *testing.T) {
+	newExecutor := func() *resilience.Executor {
+		return resilience.NewExecutor("sqs", config.CircuitBreakerPolicy{
+			Enabled:             true,
+			Timeout:             time.Second,
+			MinRequests:         2,
+			FailureRatio:        0.5,
+			ConsecutiveFailures: 2,
+		}, slog.New(slog.NewJSONHandler(io.Discard, nil)), resilience.ClassifySQSError)
+	}
+
+	t.Run("client faults are excluded", func(t *testing.T) {
+		api := &mockAPI{
+			sendErr: sqsAPIError{code: "AccessDenied", fault: smithy.FaultClient},
+		}
+		wrapped := NewResilientAPI(api, newExecutor())
+
+		for range 3 {
+			_, err := wrapped.SendMessage(context.Background(), &sqs.SendMessageInput{})
+			if err == nil {
+				t.Fatalf("expected access denied error")
+			}
+			var openErr *resilience.OpenError
+			if errors.As(err, &openErr) {
+				t.Fatalf("expected excluded error to keep breaker closed, got %v", err)
+			}
+		}
+		if api.sendCalls != 3 {
+			t.Fatalf("expected all excluded calls to reach API, got %d", api.sendCalls)
+		}
+	})
+
+	t.Run("server faults open the breaker", func(t *testing.T) {
+		api := &mockAPI{
+			receiveErr: sqsAPIError{code: "InternalError", fault: smithy.FaultServer},
+		}
+		wrapped := NewResilientAPI(api, newExecutor())
+
+		for range 2 {
+			if _, err := wrapped.ReceiveMessage(context.Background(), &sqs.ReceiveMessageInput{}); err == nil {
+				t.Fatalf("expected receive error")
+			}
+		}
+		_, err := wrapped.ReceiveMessage(context.Background(), &sqs.ReceiveMessageInput{})
+		var openErr *resilience.OpenError
+		if !errors.As(err, &openErr) {
+			t.Fatalf("expected circuit open error, got %v", err)
+		}
+		if api.receiveCalls != 2 {
+			t.Fatalf("expected breaker to fail fast after opening, got %d receive calls", api.receiveCalls)
+		}
+	})
+}
+
+type sqsAPIError struct {
+	code  string
+	fault smithy.ErrorFault
+}
+
+func (e sqsAPIError) Error() string                 { return e.code }
+func (e sqsAPIError) ErrorCode() string             { return e.code }
+func (e sqsAPIError) ErrorMessage() string          { return e.code }
+func (e sqsAPIError) ErrorFault() smithy.ErrorFault { return e.fault }
diff --git a/internal/repository/sqs/integration_test.go b/internal/repository/sqs/integration_test.go
new file mode 100644
index 0000000..d24a0dc
--- /dev/null
+++ b/internal/repository/sqs/integration_test.go
@@ -0,0 +1,89 @@
+package sqs
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"wucher/internal/config"
+	"wucher/internal/queue"
+)
+
+func TestEmailQueueIntegration(t *testing.T) {
+	queueURL := os.Getenv("SQS_INTEGRATION_QUEUE_URL")
+	if queueURL == "" {
+		t.Skip("SQS_INTEGRATION_QUEUE_URL is not set")
+	}
+
+	cfg := config.SQSConfig{
+		Region:                getenv("SQS_INTEGRATION_REGION", os.Getenv("AWS_REGION")),
+		Endpoint:              getenv("SQS_INTEGRATION_ENDPOINT", os.Getenv("SQS_ENDPOINT")),
+		QueueURL:              queueURL,
+		QueueType:             getenv("SQS_INTEGRATION_QUEUE_TYPE", queue.QueueTypeStandard),
+		MessageGroupID:        getenv("SQS_INTEGRATION_MESSAGE_GROUP_ID", "integration"),
+		MaxMessages:           1,
+		WaitTimeSeconds:       5,
+		VisibilityTimeout:     30 * time.Second,
+		AllowInsecureEndpoint: os.Getenv("SQS_INTEGRATION_ALLOW_INSECURE_ENDPOINT") == "true",
+	}
+	client, err := NewClient(context.Background(), cfg)
+	if err != nil {
+		t.Fatalf("new client: %v", err)
+	}
+	adapter, err := NewEmailQueue(client, cfg)
+	if err != nil {
+		t.Fatalf("new queue: %v", err)
+	}
+
+	serializer := queue.NewJSONSerializer("v1", true, cfg.QueueType, cfg.MessageGroupID)
+	outbound, err := serializer.Serialize(context.Background(), queue.EmailJob{
+		Type:    "integration",
+		To:      "integration@example.com",
+		Subject: "integration-" + time.Now().UTC().Format(time.RFC3339Nano),
+		Body:    "hello",
+	})
+	if err != nil {
+		t.Fatalf("serialize: %v", err)
+	}
+	if err := adapter.Publish(context.Background(), *outbound); err != nil {
+		t.Fatalf("publish: %v", err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+
+	for {
+		deliveries, err := adapter.Receive(ctx, 1)
+		if err != nil {
+			t.Fatalf("receive: %v", err)
+		}
+		if len(deliveries) == 0 {
+			if ctx.Err() != nil {
+				t.Fatalf("timed out waiting for message")
+			}
+			continue
+		}
+		envelope, err := serializer.Deserialize(deliveries[0].Body, deliveries[0].Attributes)
+		if err != nil {
+			t.Fatalf("deserialize: %v", err)
+		}
+		if envelope.MessageID != outbound.ID {
+			if err := adapter.Retry(context.Background(), deliveries[0], 0); err != nil {
+				t.Fatalf("retry unrelated message: %v", err)
+			}
+			continue
+		}
+		if err := adapter.Ack(context.Background(), deliveries); err != nil {
+			t.Fatalf("ack: %v", err)
+		}
+		return
+	}
+}
+
+func getenv(key, fallback string) string {
+	if value := os.Getenv(key); value != "" {
+		return value
+	}
+	return fallback
+}
diff --git a/internal/repository/sqs/resilient_api.go b/internal/repository/sqs/resilient_api.go
new file mode 100644
index 0000000..a22e65b
--- /dev/null
+++ b/internal/repository/sqs/resilient_api.go
@@ -0,0 +1,54 @@
+package sqs
+
+import (
+	"context"
+
+	"github.com/aws/aws-sdk-go-v2/service/sqs"
+
+	"wucher/internal/resilience"
+)
+
+type resilientAPI struct {
+	next     API
+	executor *resilience.Executor
+}
+
+func NewResilientAPI(next API, executor *resilience.Executor) API {
+	if next == nil || executor == nil || !executor.Enabled() {
+		return next
+	}
+	return &resilientAPI{
+		next:     next,
+		executor: executor,
+	}
+}
+
+func (r *resilientAPI) SendMessage(ctx context.Context, params *sqs.SendMessageInput, optFns ...func(*sqs.Options)) (*sqs.SendMessageOutput, error) {
+	return resilience.Do(ctx, r.executor, func(ctx context.Context) (*sqs.SendMessageOutput, error) {
+		return r.next.SendMessage(ctx, params, optFns...)
+	})
+}
+
+func (r *resilientAPI) ReceiveMessage(ctx context.Context, params *sqs.ReceiveMessageInput, optFns ...func(*sqs.Options)) (*sqs.ReceiveMessageOutput, error) {
+	return resilience.Do(ctx, r.executor, func(ctx context.Context) (*sqs.ReceiveMessageOutput, error) {
+		return r.next.ReceiveMessage(ctx, params, optFns...)
+	})
+}
+
+func (r *resilientAPI) DeleteMessageBatch(ctx context.Context, params *sqs.DeleteMessageBatchInput, optFns ...func(*sqs.Options)) (*sqs.DeleteMessageBatchOutput, error) {
+	return resilience.Do(ctx, r.executor, func(ctx context.Context) (*sqs.DeleteMessageBatchOutput, error) {
+		return r.next.DeleteMessageBatch(ctx, params, optFns...)
+	})
+}
+
+func (r *resilientAPI) ChangeMessageVisibility(ctx context.Context, params *sqs.ChangeMessageVisibilityInput, optFns ...func(*sqs.Options)) (*sqs.ChangeMessageVisibilityOutput, error) {
+	return resilience.Do(ctx, r.executor, func(ctx context.Context) (*sqs.ChangeMessageVisibilityOutput, error) {
+		return r.next.ChangeMessageVisibility(ctx, params, optFns...)
+	})
+}
+
+func (r *resilientAPI) GetQueueAttributes(ctx context.Context, params *sqs.GetQueueAttributesInput, optFns ...func(*sqs.Options)) (*sqs.GetQueueAttributesOutput, error) {
+	return resilience.Do(ctx, r.executor, func(ctx context.Context) (*sqs.GetQueueAttributesOutput, error) {
+		return r.next.GetQueueAttributes(ctx, params, optFns...)
+	})
+}
diff --git a/internal/resilience/breaker.go b/internal/resilience/breaker.go
new file mode 100644
index 0000000..2594905
--- /dev/null
+++ b/internal/resilience/breaker.go
@@ -0,0 +1,310 @@
+package resilience
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net"
+	"strings"
+	"time"
+
+	"github.com/aws/smithy-go"
+	"github.com/sony/gobreaker/v2"
+
+	"wucher/internal/config"
+)
+
+type Classification int
+
+const (
+	ClassificationFailure Classification = iota
+	ClassificationExcluded
+)
+
+type ErrorClassifier func(error) Classification
+
+type Executor struct {
+	name       string
+	breaker    *gobreaker.CircuitBreaker[any]
+	classifier ErrorClassifier
+}
+
+type OpenError struct {
+	Dependency string
+	Err        error
+}
+
+func (e *OpenError) Error() string {
+	if e == nil {
+		return ""
+	}
+	return fmt.Sprintf("%s circuit breaker: %v", e.Dependency, e.Err)
+}
+
+func (e *OpenError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Err
+}
+
+type HTTPStatusError struct {
+	Operation  string
+	StatusCode int
+	Body       string
+}
+
+func (e *HTTPStatusError) Error() string {
+	if e == nil {
+		return ""
+	}
+	body := strings.TrimSpace(e.Body)
+	if len(body) > 256 {
+		body = body[:256]
+	}
+	if body == "" {
+		return fmt.Sprintf("%s: status=%d", e.Operation, e.StatusCode)
+	}
+	return fmt.Sprintf("%s: status=%d body=%s", e.Operation, e.StatusCode, body)
+}
+
+type classifiedError struct {
+	err      error
+	excluded bool
+}
+
+func (e *classifiedError) Error() string {
+	if e == nil || e.err == nil {
+		return ""
+	}
+	return e.err.Error()
+}
+
+func (e *classifiedError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.err
+}
+
+func NewExecutor(name string, policy config.CircuitBreakerPolicy, logger *slog.Logger, classifier ErrorClassifier) *Executor {
+	policy = normalizePolicy(policy)
+	if strings.TrimSpace(name) == "" {
+		name = "dependency"
+	}
+	executor := &Executor{
+		name:       name,
+		classifier: classifier,
+	}
+	if !policy.Enabled {
+		return executor
+	}
+	if logger == nil {
+		logger = slog.Default()
+	}
+	cbLogger := logger.With("component", "circuit_breaker", "dependency", name)
+	settings := gobreaker.Settings{
+		Name:         name,
+		MaxRequests:  policy.MaxRequests,
+		Interval:     policy.Interval,
+		BucketPeriod: policy.BucketPeriod,
+		Timeout:      policy.Timeout,
+		ReadyToTrip: func(counts gobreaker.Counts) bool {
+			if policy.ConsecutiveFailures > 0 && counts.ConsecutiveFailures >= policy.ConsecutiveFailures {
+				return true
+			}
+			total := counts.TotalSuccesses + counts.TotalFailures
+			if total < policy.MinRequests || policy.FailureRatio <= 0 {
+				return false
+			}
+			return float64(counts.TotalFailures)/float64(total) >= policy.FailureRatio
+		},
+		OnStateChange: func(name string, from, to gobreaker.State) {
+			level := slog.LevelInfo
+			if to == gobreaker.StateOpen {
+				level = slog.LevelWarn
+			}
+			cbLogger.Log(context.Background(), level, "state changed",
+				"from", from.String(),
+				"to", to.String(),
+			)
+		},
+		IsSuccessful: func(err error) bool {
+			return err == nil
+		},
+		IsExcluded: func(err error) bool {
+			var classified *classifiedError
+			return errors.As(err, &classified) && classified.excluded
+		},
+	}
+	executor.breaker = gobreaker.NewCircuitBreaker[any](settings)
+	return executor
+}
+
+func (e *Executor) Enabled() bool {
+	return e != nil && e.breaker != nil
+}
+
+func (e *Executor) Counts() gobreaker.Counts {
+	if e == nil || e.breaker == nil {
+		return gobreaker.Counts{}
+	}
+	return e.breaker.Counts()
+}
+
+func (e *Executor) Execute(ctx context.Context, fn func(context.Context) error) error {
+	_, err := Do(ctx, e, func(ctx context.Context) (struct{}, error) {
+		return struct{}{}, fn(ctx)
+	})
+	return err
+}
+
+func Do[T any](ctx context.Context, executor *Executor, fn func(context.Context) (T, error)) (T, error) {
+	var zero T
+	if executor == nil || executor.breaker == nil {
+		return fn(ctx)
+	}
+	value, err := executor.breaker.Execute(func() (any, error) {
+		result, err := fn(ctx)
+		if err != nil {
+			if executor.classifier != nil && executor.classifier(err) == ClassificationExcluded {
+				return nil, &classifiedError{err: err, excluded: true}
+			}
+			return nil, &classifiedError{err: err}
+		}
+		return any(result), nil
+	})
+	if err != nil {
+		if errors.Is(err, gobreaker.ErrOpenState) || errors.Is(err, gobreaker.ErrTooManyRequests) {
+			return zero, &OpenError{Dependency: executor.name, Err: err}
+		}
+		var classified *classifiedError
+		if errors.As(err, &classified) {
+			return zero, classified.err
+		}
+		return zero, err
+	}
+	if value == nil {
+		return zero, nil
+	}
+	typed, ok := value.(T)
+	if !ok {
+		return zero, fmt.Errorf("%s circuit breaker returned unexpected type %T", executor.name, value)
+	}
+	return typed, nil
+}
+
+func ClassifyMicrosoftSSOError(err error) Classification {
+	switch {
+	case err == nil:
+		return ClassificationExcluded
+	case errors.Is(err, context.Canceled):
+		return ClassificationExcluded
+	case errors.Is(err, context.DeadlineExceeded):
+		return ClassificationFailure
+	}
+	var netErr net.Error
+	if errors.As(err, &netErr) {
+		return ClassificationFailure
+	}
+	var statusErr *HTTPStatusError
+	if errors.As(err, &statusErr) {
+		if statusErr.StatusCode == 429 || statusErr.StatusCode >= 500 {
+			return ClassificationFailure
+		}
+		return ClassificationExcluded
+	}
+	return ClassificationFailure
+}
+
+func ClassifySESError(err error) Classification {
+	switch {
+	case err == nil:
+		return ClassificationExcluded
+	case errors.Is(err, context.Canceled):
+		return ClassificationExcluded
+	case errors.Is(err, context.DeadlineExceeded):
+		return ClassificationFailure
+	}
+	var netErr net.Error
+	if errors.As(err, &netErr) {
+		return ClassificationFailure
+	}
+	var apiErr smithy.APIError
+	if errors.As(err, &apiErr) {
+		code := strings.ToLower(strings.TrimSpace(apiErr.ErrorCode()))
+		if apiErr.ErrorFault() == smithy.FaultServer || isThrottleCode(code) {
+			return ClassificationFailure
+		}
+		return ClassificationExcluded
+	}
+	message := strings.ToLower(strings.TrimSpace(err.Error()))
+	if strings.Contains(message, "ses is not configured") ||
+		strings.Contains(message, "recipient is required") ||
+		strings.Contains(message, "invalid email job") {
+		return ClassificationExcluded
+	}
+	if strings.Contains(message, "eof") {
+		return ClassificationFailure
+	}
+	return ClassificationExcluded
+}
+
+func ClassifySQSError(err error) Classification {
+	switch {
+	case err == nil:
+		return ClassificationExcluded
+	case errors.Is(err, context.Canceled):
+		return ClassificationExcluded
+	case errors.Is(err, context.DeadlineExceeded):
+		return ClassificationFailure
+	}
+	var netErr net.Error
+	if errors.As(err, &netErr) {
+		return ClassificationFailure
+	}
+	var apiErr smithy.APIError
+	if errors.As(err, &apiErr) {
+		code := strings.ToLower(strings.TrimSpace(apiErr.ErrorCode()))
+		if apiErr.ErrorFault() == smithy.FaultServer || isThrottleCode(code) {
+			return ClassificationFailure
+		}
+		return ClassificationExcluded
+	}
+	return ClassificationFailure
+}
+
+func normalizePolicy(policy config.CircuitBreakerPolicy) config.CircuitBreakerPolicy {
+	if policy.MaxRequests == 0 {
+		policy.MaxRequests = 1
+	}
+	if policy.Interval <= 0 {
+		policy.Interval = time.Minute
+	}
+	if policy.BucketPeriod <= 0 {
+		policy.BucketPeriod = 10 * time.Second
+	}
+	if policy.Timeout <= 0 {
+		policy.Timeout = 30 * time.Second
+	}
+	if policy.MinRequests == 0 {
+		policy.MinRequests = 5
+	}
+	if policy.FailureRatio <= 0 || policy.FailureRatio > 1 {
+		policy.FailureRatio = 0.6
+	}
+	if policy.ConsecutiveFailures == 0 {
+		policy.ConsecutiveFailures = 5
+	}
+	return policy
+}
+
+func isThrottleCode(code string) bool {
+	switch code {
+	case "throttling", "throttlingexception", "requestthrottled", "toomanyrequestsexception", "slowdown":
+		return true
+	default:
+		return false
+	}
+}
diff --git a/internal/resilience/breaker_test.go b/internal/resilience/breaker_test.go
new file mode 100644
index 0000000..b61e8ff
--- /dev/null
+++ b/internal/resilience/breaker_test.go
@@ -0,0 +1,92 @@
+package resilience
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"testing"
+	"time"
+
+	"github.com/aws/smithy-go"
+
+	"wucher/internal/config"
+)
+
+func TestExecutor_ExcludedErrorsDoNotTrip(t *testing.T) {
+	executor := NewExecutor("ses", config.CircuitBreakerPolicy{
+		Enabled:             true,
+		Timeout:             time.Second,
+		MinRequests:         2,
+		FailureRatio:        0.5,
+		ConsecutiveFailures: 2,
+	}, slog.New(slog.NewJSONHandler(io.Discard, nil)), func(error) Classification {
+		return ClassificationExcluded
+	})
+
+	for range 2 {
+		err := executor.Execute(context.Background(), func(context.Context) error {
+			return errors.New("validation error")
+		})
+		if err == nil {
+			t.Fatalf("expected original error")
+		}
+	}
+
+	counts := executor.Counts()
+	if counts.TotalExclusions != 2 {
+		t.Fatalf("expected 2 exclusions, got %+v", counts)
+	}
+	if counts.TotalFailures != 0 {
+		t.Fatalf("expected 0 failures, got %+v", counts)
+	}
+}
+
+func TestExecutor_FailuresTripBreaker(t *testing.T) {
+	executor := NewExecutor("sqs", config.CircuitBreakerPolicy{
+		Enabled:             true,
+		Timeout:             time.Second,
+		MinRequests:         1,
+		FailureRatio:        0.5,
+		ConsecutiveFailures: 2,
+	}, slog.New(slog.NewJSONHandler(io.Discard, nil)), nil)
+
+	for range 2 {
+		err := executor.Execute(context.Background(), func(context.Context) error {
+			return errors.New("dependency down")
+		})
+		if err == nil {
+			t.Fatalf("expected dependency error")
+		}
+	}
+
+	err := executor.Execute(context.Background(), func(context.Context) error {
+		return nil
+	})
+	var openErr *OpenError
+	if !errors.As(err, &openErr) {
+		t.Fatalf("expected breaker open error, got %v", err)
+	}
+}
+
+func TestClassifySQSError(t *testing.T) {
+	if got := ClassifySQSError(apiError{code: "AccessDenied", fault: smithy.FaultClient}); got != ClassificationExcluded {
+		t.Fatalf("expected client fault excluded, got %v", got)
+	}
+	if got := ClassifySQSError(apiError{code: "InternalError", fault: smithy.FaultServer}); got != ClassificationFailure {
+		t.Fatalf("expected server fault failure, got %v", got)
+	}
+	if got := ClassifySQSError(apiError{code: "ThrottlingException", fault: smithy.FaultClient}); got != ClassificationFailure {
+		t.Fatalf("expected throttling failure, got %v", got)
+	}
+}
+
+type apiError struct {
+	code  string
+	fault smithy.ErrorFault
+}
+
+func (e apiError) Error() string                 { return e.code }
+func (e apiError) ErrorCode() string             { return e.code }
+func (e apiError) ErrorMessage() string          { return e.code }
+func (e apiError) ErrorFault() smithy.ErrorFault { return e.fault }
diff --git a/internal/routes/routes.go b/internal/routes/routes.go
new file mode 100644
index 0000000..82559e6
--- /dev/null
+++ b/internal/routes/routes.go
@@ -0,0 +1,18 @@
+package routes
+
+import (
+	"github.com/gofiber/fiber/v2"
+	samlauth "wucher/internal/auth"
+	authmw "wucher/internal/middleware"
+)
+
+func Register(app *fiber.App, authHandler *samlauth.Handler, profileHandler fiber.Handler) {
+	app.Get("/auth/login", authHandler.HandleLogin)
+	app.Post("/auth/saml/callback", authHandler.HandleSAMLCallback)
+	app.Post("/auth/saml/logout", authHandler.HandleSLO)
+	app.Get("/auth/saml/metadata", authHandler.HandleMetadata)
+	app.Post("/auth/logout", authHandler.HandleLogout)
+
+	api := app.Group("/api", authmw.RequireAuth)
+	api.Get("/profile", profileHandler)
+}
diff --git a/internal/service/action_signoff_service.go b/internal/service/action_signoff_service.go
new file mode 100644
index 0000000..3574284
--- /dev/null
+++ b/internal/service/action_signoff_service.go
@@ -0,0 +1,124 @@
+package service
+
+import (
+	"context"
+	"time"
+
+	actionsignoff "wucher/internal/domain/action_signoff"
+)
+
+type ActionSignoffService struct{ repo actionsignoff.Repository }
+
+func NewActionSignoffService(repo actionsignoff.Repository) *ActionSignoffService {
+	return &ActionSignoffService{repo: repo}
+}
+
+func (s *ActionSignoffService) GetByFlight(ctx context.Context, flightID []byte) (*actionsignoff.ActionSignoff, error) {
+	return s.repo.GetByFlight(ctx, flightID)
+}
+
+func (s *ActionSignoffService) GetByComplaint(ctx context.Context, complaintID []byte) (*actionsignoff.ActionSignoff, error) {
+	return s.repo.GetByComplaint(ctx, complaintID)
+}
+
+func (s *ActionSignoffService) GetByComplaintIDs(ctx context.Context, complaintIDs [][]byte) (map[string]*actionsignoff.ActionSignoff, error) {
+	return s.repo.GetByComplaintIDs(ctx, complaintIDs)
+}
+
+// UnsignByComplaint clears the signature on the complaint-linked sign-off. No-op when
+// there is no sign-off for the complaint or it is already unsigned.
+func (s *ActionSignoffService) UnsignByComplaint(ctx context.Context, complaintID []byte) (*actionsignoff.ActionSignoff, error) {
+	row, err := s.repo.GetByComplaint(ctx, complaintID)
+	if err != nil {
+		return nil, err
+	}
+	if row == nil {
+		return nil, nil
+	}
+	if row.SignedAt == nil {
+		return row, nil
+	}
+	row.SignedAt = nil
+	row.SignedBy = nil
+	if err := s.repo.Update(ctx, row); err != nil {
+		return nil, err
+	}
+	return row, nil
+}
+
+// SignForComplaint records (or re-stamps) the action sign-off linked to a specific
+// complaint — i.e. "this complaint's corrective action was signed off". Upsert by
+// complaint: creates the row on first sign, otherwise re-stamps signer/time.
+func (s *ActionSignoffService) SignForComplaint(ctx context.Context, complaintID, flightID, helicopterID []byte, signer []byte) (*actionsignoff.ActionSignoff, error) {
+	row, err := s.repo.GetByComplaint(ctx, complaintID)
+	if err != nil {
+		return nil, err
+	}
+	now := time.Now().UTC()
+	if row == nil {
+		row = &actionsignoff.ActionSignoff{
+			HelicopterID: append([]byte(nil), helicopterID...),
+			FlightID:     append([]byte(nil), flightID...),
+			ComplaintID:  append([]byte(nil), complaintID...),
+			SignedAt:     &now,
+			SignedBy:     append([]byte(nil), signer...),
+		}
+		if err := s.repo.Create(ctx, row); err != nil {
+			return nil, err
+		}
+		return row, nil
+	}
+	row.FlightID = append([]byte(nil), flightID...)
+	row.SignedAt = &now
+	row.SignedBy = append([]byte(nil), signer...)
+	if err := s.repo.Update(ctx, row); err != nil {
+		return nil, err
+	}
+	return row, nil
+}
+
+// Sign records (or re-stamps) the helicopter's action sign-off as signed by the
+
+func (s *ActionSignoffService) Sign(ctx context.Context, flightID, helicopterID []byte, signer []byte) (*actionsignoff.ActionSignoff, error) {
+	row, err := s.repo.GetByFlight(ctx, flightID)
+	if err != nil {
+		return nil, err
+	}
+	now := time.Now().UTC()
+	if row == nil {
+		row = &actionsignoff.ActionSignoff{
+			HelicopterID: append([]byte(nil), helicopterID...),
+			FlightID:     append([]byte(nil), flightID...),
+			SignedAt:     &now,
+			SignedBy:     append([]byte(nil), signer...),
+		}
+		if err := s.repo.Create(ctx, row); err != nil {
+			return nil, err
+		}
+		return row, nil
+	}
+	row.SignedAt = &now
+	row.SignedBy = append([]byte(nil), signer...)
+	if err := s.repo.Update(ctx, row); err != nil {
+		return nil, err
+	}
+	return row, nil
+}
+
+// Unsign clears the signature (check → uncheck). Returns ErrNotFound when there
+// is nothing to unsign.
+func (s *ActionSignoffService) Unsign(ctx context.Context, flightID []byte, _ []byte) (*actionsignoff.ActionSignoff, error) {
+	row, err := s.repo.GetByFlight(ctx, flightID)
+	if err != nil {
+		return nil, err
+	}
+	if row == nil {
+		return nil, actionsignoff.ErrNotFound
+	}
+	row.SignedAt = nil
+	row.SignedBy = nil
+	if err := s.repo.Update(ctx, row); err != nil {
+		return nil, err
+	}
+	return row, nil
+}
diff --git a/internal/service/after_flight_inspection_service.go b/internal/service/after_flight_inspection_service.go
new file mode 100644
index 0000000..7a4d995
--- /dev/null
+++ b/internal/service/after_flight_inspection_service.go
@@ -0,0 +1,168 @@
+package service
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	"wucher/internal/shared/pkg/appctx"
+)
+
+type AfterFlightInspectionService struct {
+	repo  afterflightinspection.Repository
+}
+
+func NewAfterFlightInspectionService(repo afterflightinspection.Repository) *AfterFlightInspectionService {
+	return &AfterFlightInspectionService{repo: repo}
+}
+
+func (s *AfterFlightInspectionService) Upsert(ctx context.Context, flightInspectionID []byte, req *afterflightinspection.UpsertRequest) (*afterflightinspection.AfterFlightInspection, error) {
+	if err := s.ensureFlightInspection(ctx, flightInspectionID); err != nil {
+		return nil, err
+	}
+
+	caps, err := s.repo.GetHelicopterCapabilities(ctx, flightInspectionID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get helicopter capabilities: %w", err)
+	}
+
+	if err := s.validateRequest(req, caps); err != nil {
+		return nil, err
+	}
+
+	row := &afterflightinspection.AfterFlightInspection{
+		FlightInspectionID:        flightInspectionID,
+		OilEngineNR1Checked:       req.OilEngineNR1Checked,
+		OilEngineNR2Checked:       req.OilEngineNR2Checked,
+		HydraulicLHChecked:        req.HydraulicLHChecked,
+		HydraulicRHChecked:        req.HydraulicRHChecked,
+		OilTransmissionMGBChecked: req.OilTransmissionMGBChecked,
+		OilTransmissionIGBChecked: req.OilTransmissionIGBChecked,
+		OilTransmissionTGBChecked: req.OilTransmissionTGBChecked,
+		Note:                      req.Note,
+	}
+
+	existing, err := s.repo.GetByFlightInspectionID(ctx, flightInspectionID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to load after flight inspection: %w", err)
+	}
+
+	userID := appctx.GetUserID(ctx)
+	if existing != nil {
+		row.ID = existing.ID
+		row.CreatedAt = existing.CreatedAt
+		row.CreatedBy = existing.CreatedBy
+		if userID != nil {
+			row.UpdatedBy = userID
+		} else {
+			row.UpdatedBy = existing.UpdatedBy
+		}
+	} else if userID != nil {
+		row.CreatedBy = userID
+		row.UpdatedBy = userID
+	}
+
+	if err := s.repo.Upsert(ctx, row); err != nil {
+		return nil, fmt.Errorf("failed to upsert after flight inspection: %w", err)
+	}
+
+	return row, nil
+}
+
+func (s *AfterFlightInspectionService) GetByFlightInspectionID(ctx context.Context, flightInspectionID []byte) (*afterflightinspection.AfterFlightInspection, error) {
+	if err := s.ensureFlightInspection(ctx, flightInspectionID); err != nil {
+		return nil, err
+	}
+
+	row, err := s.repo.GetByFlightInspectionID(ctx, flightInspectionID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get after flight inspection: %w", err)
+	}
+
+	return row, nil
+}
+
+func (s *AfterFlightInspectionService) DeleteByFlightInspectionID(ctx context.Context, flightInspectionID []byte) error {
+	if err := s.ensureFlightInspection(ctx, flightInspectionID); err != nil {
+		return err
+	}
+
+	if err := s.repo.DeleteByFlightInspectionID(ctx, flightInspectionID); err != nil {
+		return fmt.Errorf("failed to delete after flight inspection: %w", err)
+	}
+	return nil
+}
+
+// ensureFlightInspection validates the identifier and confirms the referenced
+// flight inspection exists. It returns domain sentinel errors so the transport
+// layer can map them to apperrorsx definitions.
+func (s *AfterFlightInspectionService) ensureFlightInspection(ctx context.Context, flightInspectionID []byte) error {
+	if len(flightInspectionID) != 16 {
+		return afterflightinspection.ErrInvalidFlightInspectionID
+	}
+
+	exists, err := s.repo.FlightInspectionExists(ctx, flightInspectionID)
+	if err != nil {
+		return fmt.Errorf("failed to check flight inspection: %w", err)
+	}
+	if !exists {
+		return afterflightinspection.ErrFlightInspectionNotFound
+	}
+	return nil
+}
+
+func (s *AfterFlightInspectionService) validateRequest(req *afterflightinspection.UpsertRequest, caps *afterflightinspection.HelicopterCapabilities) error {
+	if caps == nil {
+		return afterflightinspection.ErrCapabilitiesUnavailable
+	}
+
+	if caps.NR1 && !hasNonEmptyString(req.OilEngineNR1Checked) {
+		return afterflightinspection.ErrNR1Required
+	}
+	if hasNonEmptyString(req.OilEngineNR1Checked) && !caps.NR1 {
+		return afterflightinspection.ErrNR1NotAvailable
+	}
+	if caps.NR2 && !hasNonEmptyString(req.OilEngineNR2Checked) {
+		return afterflightinspection.ErrNR2Required
+	}
+	if hasNonEmptyString(req.OilEngineNR2Checked) && !caps.NR2 {
+		return afterflightinspection.ErrNR2NotAvailable
+	}
+	if caps.LH && !hasNonEmptyString(req.HydraulicLHChecked) {
+		return afterflightinspection.ErrLHRequired
+	}
+	if hasNonEmptyString(req.HydraulicLHChecked) && !caps.LH {
+		return afterflightinspection.ErrLHNotAvailable
+	}
+	if caps.RH && !hasNonEmptyString(req.HydraulicRHChecked) {
+		return afterflightinspection.ErrRHRequired
+	}
+	if hasNonEmptyString(req.HydraulicRHChecked) && !caps.RH {
+		return afterflightinspection.ErrRHNotAvailable
+	}
+	if caps.MGB && !hasNonEmptyString(req.OilTransmissionMGBChecked) {
+		return afterflightinspection.ErrMGBRequired
+	}
+	if hasNonEmptyString(req.OilTransmissionMGBChecked) && !caps.MGB {
+		return afterflightinspection.ErrMGBNotAvailable
+	}
+	if caps.IGB && !hasNonEmptyString(req.OilTransmissionIGBChecked) {
+		return afterflightinspection.ErrIGBRequired
+	}
+	if hasNonEmptyString(req.OilTransmissionIGBChecked) && !caps.IGB {
+		return afterflightinspection.ErrIGBNotAvailable
+	}
+	if caps.TGB && !hasNonEmptyString(req.OilTransmissionTGBChecked) {
+		return afterflightinspection.ErrTGBRequired
+	}
+	if hasNonEmptyString(req.OilTransmissionTGBChecked) && !caps.TGB {
+		return afterflightinspection.ErrTGBNotAvailable
+	}
+
+	return nil
+}
+
+func hasNonEmptyString(v *string) bool {
+	return v != nil && strings.TrimSpace(*v) != ""
+}
diff --git a/internal/service/after_flight_inspection_service_test.go b/internal/service/after_flight_inspection_service_test.go
new file mode 100644
index 0000000..cf64fa4
--- /dev/null
+++ b/internal/service/after_flight_inspection_service_test.go
@@ -0,0 +1,168 @@
+package service
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+)
+
+type afterFlightInspectionRepoStub struct {
+	exists        bool
+	caps          *afterflightinspection.HelicopterCapabilities
+	existing      *afterflightinspection.AfterFlightInspection
+	upserted      *afterflightinspection.AfterFlightInspection
+	upsertErr     error
+	existsErr     error
+	capErr        error
+	flightChecked int
+}
+
+func (r *afterFlightInspectionRepoStub) Upsert(_ context.Context, row *afterflightinspection.AfterFlightInspection) error {
+	r.upserted = row
+	return r.upsertErr
+}
+
+func (r *afterFlightInspectionRepoStub) GetByFlightInspectionID(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+	return r.existing, nil
+}
+
+func (r *afterFlightInspectionRepoStub) DeleteByFlightInspectionID(context.Context, []byte) error {
+	return nil
+}
+
+func (r *afterFlightInspectionRepoStub) FlightInspectionExists(context.Context, []byte) (bool, error) {
+	if r.existsErr != nil {
+		return false, r.existsErr
+	}
+	return r.exists, nil
+}
+
+func (r *afterFlightInspectionRepoStub) GetHelicopterCapabilities(context.Context, []byte) (*afterflightinspection.HelicopterCapabilities, error) {
+	if r.capErr != nil {
+		return nil, r.capErr
+	}
+	r.flightChecked++
+	return r.caps, nil
+}
+
+func TestAfterFlightInspectionServiceValidateRequestRequiresCapabilityChecks(t *testing.T) {
+	svc := NewAfterFlightInspectionService(&afterFlightInspectionRepoStub{})
+
+	nr1 := "checked"
+	nr2 := "checked"
+	lh := "checked"
+	rh := "checked"
+	mgb := "checked"
+	igb := "checked"
+	tgb := "checked"
+	req := &afterflightinspection.UpsertRequest{
+		OilEngineNR1Checked:       &nr1,
+		OilEngineNR2Checked:       &nr2,
+		HydraulicLHChecked:        &lh,
+		HydraulicRHChecked:        &rh,
+		OilTransmissionMGBChecked: &mgb,
+		OilTransmissionIGBChecked: &igb,
+		OilTransmissionTGBChecked: &tgb,
+	}
+	caps := &afterflightinspection.HelicopterCapabilities{
+		NR1: true, NR2: true, LH: true, RH: true, MGB: true, IGB: true, TGB: true,
+	}
+	if err := svc.validateRequest(req, caps); err != nil {
+		t.Fatalf("expected request to be valid, got %v", err)
+	}
+
+	req.OilEngineNR2Checked = nil
+	if err := svc.validateRequest(req, caps); err == nil {
+		t.Fatal("expected missing required nr2 check to be rejected")
+	}
+}
+
+func TestAfterFlightInspectionServiceUpsertUpdatesExistingRow(t *testing.T) {
+	existingID := make([]byte, 16)
+	for i := range existingID {
+		existingID[i] = byte(i + 1)
+	}
+	createdBy := []byte("creator123456789")
+	createdAt := time.Date(2026, 1, 1, 8, 0, 0, 0, time.UTC)
+
+	repo := &afterFlightInspectionRepoStub{
+		exists: true,
+		caps:   &afterflightinspection.HelicopterCapabilities{NR1: true},
+		existing: &afterflightinspection.AfterFlightInspection{
+			ID:        existingID,
+			CreatedAt: createdAt,
+			CreatedBy: createdBy,
+		},
+	}
+	svc := NewAfterFlightInspectionService(repo)
+
+	flightInspectionID := make([]byte, 16)
+	for i := range flightInspectionID {
+		flightInspectionID[i] = byte(100 + i)
+	}
+	nr1 := "400"
+	row, err := svc.Upsert(context.Background(), flightInspectionID, &afterflightinspection.UpsertRequest{
+		OilEngineNR1Checked: &nr1,
+	})
+	if err != nil {
+		t.Fatalf("Upsert returned error: %v", err)
+	}
+
+	// The saved row must reuse the existing identity so GORM performs an UPDATE
+	// instead of inserting a duplicate flight_inspection_id (the original bug).
+	if string(repo.upserted.ID) != string(existingID) {
+		t.Fatalf("expected upsert to reuse existing ID %x, got %x", existingID, repo.upserted.ID)
+	}
+	if !repo.upserted.CreatedAt.Equal(createdAt) {
+		t.Fatalf("expected created_at to be preserved, got %v", repo.upserted.CreatedAt)
+	}
+	if string(repo.upserted.CreatedBy) != string(createdBy) {
+		t.Fatalf("expected created_by to be preserved, got %x", repo.upserted.CreatedBy)
+	}
+	if row == nil || string(row.ID) != string(existingID) {
+		t.Fatal("expected returned row to carry existing ID")
+	}
+}
+
+func TestAfterFlightInspectionServiceUpsertInsertsWhenAbsent(t *testing.T) {
+	repo := &afterFlightInspectionRepoStub{
+		exists: true,
+		caps:   &afterflightinspection.HelicopterCapabilities{NR1: true},
+	}
+	svc := NewAfterFlightInspectionService(repo)
+
+	flightInspectionID := make([]byte, 16)
+	for i := range flightInspectionID {
+		flightInspectionID[i] = byte(50 + i)
+	}
+	nr1 := "400"
+	if _, err := svc.Upsert(context.Background(), flightInspectionID, &afterflightinspection.UpsertRequest{
+		OilEngineNR1Checked: &nr1,
+	}); err != nil {
+		t.Fatalf("Upsert returned error: %v", err)
+	}
+
+	// No existing row: a new INSERT (empty ID, BeforeCreate mints a UUID).
+	if len(repo.upserted.ID) != 0 {
+		t.Fatalf("expected empty ID for new row, got %x", repo.upserted.ID)
+	}
+	if string(repo.upserted.FlightInspectionID) != string(flightInspectionID) {
+		t.Fatal("expected flight_inspection_id to be set")
+	}
+}
+
+func TestAfterFlightInspectionServiceValidateRequestRejectsUnsupportedChecks(t *testing.T) {
+	svc := NewAfterFlightInspectionService(&afterFlightInspectionRepoStub{})
+
+	yes := "checked"
+	req := &afterflightinspection.UpsertRequest{
+		OilEngineNR1Checked: &yes,
+	}
+	caps := &afterflightinspection.HelicopterCapabilities{}
+
+	if err := svc.validateRequest(req, caps); err == nil {
+		t.Fatal("expected unsupported nr1 check to be rejected")
+	}
+}
diff --git a/internal/service/air_rescuer_checklist_service.go b/internal/service/air_rescuer_checklist_service.go
new file mode 100644
index 0000000..3f6e051
--- /dev/null
+++ b/internal/service/air_rescuer_checklist_service.go
@@ -0,0 +1,289 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	airrescuechecklist "wucher/internal/domain/air_rescue_checklist"
+)
+
+type AirRescuerChecklistService struct {
+	repo airrescuechecklist.Repository
+}
+
+func NewAirRescuerChecklistService(repo airrescuechecklist.Repository) *AirRescuerChecklistService {
+	return &AirRescuerChecklistService{repo: repo}
+}
+
+func (s *AirRescuerChecklistService) CreateBulk(ctx context.Context, rows []airrescuechecklist.ChecklistCreateInput) error {
+	if len(rows) == 0 {
+		return nil
+	}
+	return s.repo.InTx(ctx, func(txRepo airrescuechecklist.TxRepository) error {
+		for i := range rows {
+			header := &rows[i].Checklist
+			if header.Position <= 0 {
+				nextPos, err := txRepo.NextChecklistPosition(ctx, header.HEMSBaseID, header.ScopeCode)
+				if err != nil {
+					return err
+				}
+				header.Position = nextPos
+			}
+			if err := txRepo.CreateChecklist(ctx, header); err != nil {
+				return err
+			}
+
+			var nextItemPos int
+			itemNextInitialized := false
+			for j := range rows[i].Items {
+				item := &rows[i].Items[j]
+				item.ChecklistID = append([]byte(nil), header.ID...)
+				if item.Position <= 0 {
+					if !itemNextInitialized {
+						pos, err := txRepo.NextChecklistItemPosition(ctx, header.ID)
+						if err != nil {
+							return err
+						}
+						nextItemPos = pos
+						itemNextInitialized = true
+					}
+					item.Position = nextItemPos
+					nextItemPos++
+				}
+				if err := txRepo.CreateChecklistItem(ctx, item); err != nil {
+					return err
+				}
+			}
+		}
+		return nil
+	})
+}
+
+func (s *AirRescuerChecklistService) UpdateChecklist(ctx context.Context, row *airrescuechecklist.AirRescuerChecklist) error {
+	if row == nil {
+		return gorm.ErrInvalidData
+	}
+	row.Position = normalizeChecklistPosition(row.Position)
+	return s.repo.InTx(ctx, func(txRepo airrescuechecklist.TxRepository) error {
+		if _, err := txRepo.LockChecklistByID(ctx, row.ID); err != nil {
+			return err
+		}
+		return txRepo.UpdateChecklist(ctx, row)
+	})
+}
+
+func (s *AirRescuerChecklistService) UpdateChecklistWithNewItems(
+	ctx context.Context,
+	row *airrescuechecklist.AirRescuerChecklist,
+	newItems []airrescuechecklist.AirRescuerChecklistItem,
+) error {
+	if row == nil && len(newItems) == 0 {
+		return gorm.ErrInvalidData
+	}
+
+	checklistID := []byte(nil)
+	if row != nil {
+		row.Position = normalizeChecklistPosition(row.Position)
+		checklistID = append([]byte(nil), row.ID...)
+	}
+	if len(checklistID) == 0 && len(newItems) > 0 {
+		checklistID = append([]byte(nil), newItems[0].ChecklistID...)
+	}
+	if len(checklistID) == 0 {
+		return gorm.ErrInvalidData
+	}
+
+	return s.repo.InTx(ctx, func(txRepo airrescuechecklist.TxRepository) error {
+		if _, err := txRepo.LockChecklistByID(ctx, checklistID); err != nil {
+			return err
+		}
+
+		if row != nil {
+			if err := txRepo.UpdateChecklist(ctx, row); err != nil {
+				return err
+			}
+		}
+
+		if len(newItems) == 0 {
+			return nil
+		}
+		nextItemPos := 0
+		itemNextInitialized := false
+		for i := range newItems {
+			newItems[i].ChecklistID = append([]byte(nil), checklistID...)
+			if newItems[i].Position <= 0 {
+				if !itemNextInitialized {
+					pos, err := txRepo.NextChecklistItemPosition(ctx, checklistID)
+					if err != nil {
+						return err
+					}
+					nextItemPos = pos
+					itemNextInitialized = true
+				}
+				newItems[i].Position = nextItemPos
+				nextItemPos++
+			}
+		}
+		return txRepo.CreateChecklistItems(ctx, newItems)
+	})
+}
+
+func (s *AirRescuerChecklistService) DeleteChecklist(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.InTx(ctx, func(txRepo airrescuechecklist.TxRepository) error {
+		if _, err := txRepo.LockChecklistByID(ctx, id); err != nil {
+			return err
+		}
+		if err := txRepo.SoftDeleteChecklist(ctx, id, deletedBy); err != nil {
+			return err
+		}
+		return txRepo.SoftDeleteItemsByChecklistID(ctx, id, deletedBy)
+	})
+}
+
+func (s *AirRescuerChecklistService) CreateChecklistItem(ctx context.Context, row *airrescuechecklist.AirRescuerChecklistItem) error {
+	if row == nil {
+		return gorm.ErrInvalidData
+	}
+	return s.repo.InTx(ctx, func(txRepo airrescuechecklist.TxRepository) error {
+		if _, err := txRepo.LockChecklistByID(ctx, row.ChecklistID); err != nil {
+			return err
+		}
+		if row.Position <= 0 {
+			nextPos, err := txRepo.NextChecklistItemPosition(ctx, row.ChecklistID)
+			if err != nil {
+				return err
+			}
+			row.Position = nextPos
+		}
+		return txRepo.CreateChecklistItem(ctx, row)
+	})
+}
+
+func (s *AirRescuerChecklistService) CreateChecklistItems(ctx context.Context, checklistID []byte, rows []airrescuechecklist.AirRescuerChecklistItem) error {
+	if len(rows) == 0 {
+		return nil
+	}
+	return s.repo.InTx(ctx, func(txRepo airrescuechecklist.TxRepository) error {
+		if _, err := txRepo.LockChecklistByID(ctx, checklistID); err != nil {
+			return err
+		}
+		nextItemPos := 0
+		itemNextInitialized := false
+		for i := range rows {
+			rows[i].ChecklistID = append([]byte(nil), checklistID...)
+			if rows[i].Position <= 0 {
+				if !itemNextInitialized {
+					pos, err := txRepo.NextChecklistItemPosition(ctx, checklistID)
+					if err != nil {
+						return err
+					}
+					nextItemPos = pos
+					itemNextInitialized = true
+				}
+				rows[i].Position = nextItemPos
+				nextItemPos++
+			}
+		}
+		return txRepo.CreateChecklistItems(ctx, rows)
+	})
+}
+
+func (s *AirRescuerChecklistService) ReorderChecklistItems(
+	ctx context.Context,
+	checklistID []byte,
+	rows []airrescuechecklist.ChecklistItemReorderInput,
+	updatedBy []byte,
+) error {
+	if len(rows) == 0 {
+		return gorm.ErrInvalidData
+	}
+
+	return s.repo.InTx(ctx, func(txRepo airrescuechecklist.TxRepository) error {
+		if _, err := txRepo.LockChecklistByID(ctx, checklistID); err != nil {
+			return err
+		}
+
+		seenItemIDs := make(map[string]struct{}, len(rows))
+		for i := range rows {
+			itemID := rows[i].ID
+			if len(itemID) == 0 {
+				return gorm.ErrInvalidData
+			}
+			itemKey := string(itemID)
+			if _, exists := seenItemIDs[itemKey]; exists {
+				return errors.New("duplicate item_uuid in reorder payload")
+			}
+			seenItemIDs[itemKey] = struct{}{}
+
+			current, err := txRepo.LockChecklistItemByID(ctx, itemID)
+			if err != nil {
+				return err
+			}
+			if !bytes.Equal(current.ChecklistID, checklistID) {
+				return gorm.ErrRecordNotFound
+			}
+
+			if err := txRepo.UpdateChecklistItem(ctx, &airrescuechecklist.AirRescuerChecklistItem{
+				ID:        append([]byte(nil), itemID...),
+				Name:      current.Name,
+				Position:  normalizeChecklistPosition(rows[i].Position),
+				UpdatedBy: append([]byte(nil), updatedBy...),
+			}); err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+}
+
+func (s *AirRescuerChecklistService) UpdateChecklistItem(ctx context.Context, row *airrescuechecklist.AirRescuerChecklistItem) error {
+	if row == nil {
+		return gorm.ErrInvalidData
+	}
+	row.Position = normalizeChecklistPosition(row.Position)
+	return s.repo.InTx(ctx, func(txRepo airrescuechecklist.TxRepository) error {
+		if _, err := txRepo.LockChecklistItemByID(ctx, row.ID); err != nil {
+			return err
+		}
+		return txRepo.UpdateChecklistItem(ctx, row)
+	})
+}
+
+func (s *AirRescuerChecklistService) DeleteChecklistItem(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.InTx(ctx, func(txRepo airrescuechecklist.TxRepository) error {
+		if _, err := txRepo.LockChecklistItemByID(ctx, id); err != nil {
+			return err
+		}
+		return txRepo.SoftDeleteChecklistItem(ctx, id, deletedBy)
+	})
+}
+
+func (s *AirRescuerChecklistService) GetChecklistByID(ctx context.Context, id []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+	return s.repo.GetChecklistByID(ctx, id)
+}
+
+func (s *AirRescuerChecklistService) GetChecklistItemByID(ctx context.Context, id []byte) (*airrescuechecklist.ChecklistItemView, error) {
+	return s.repo.GetChecklistItemByID(ctx, id)
+}
+
+func (s *AirRescuerChecklistService) ListChecklistHeaders(ctx context.Context, filter airrescuechecklist.ChecklistHeaderFilter) ([]airrescuechecklist.ChecklistHeaderView, error) {
+	return s.repo.ListChecklistHeaders(ctx, filter)
+}
+
+func (s *AirRescuerChecklistService) ListChecklistItemsByChecklistIDs(ctx context.Context, checklistIDs [][]byte) ([]airrescuechecklist.ChecklistItemView, error) {
+	return s.repo.ListChecklistItemsByChecklistIDs(ctx, checklistIDs)
+}
+
+func (s *AirRescuerChecklistService) ListHEMSBases(ctx context.Context, filter airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+	return s.repo.ListHEMSBases(ctx, filter)
+}
+
+func normalizeChecklistPosition(v int) int {
+	if v <= 0 {
+		return 1
+	}
+	return v
+}
diff --git a/internal/service/air_rescuer_checklist_service_test.go b/internal/service/air_rescuer_checklist_service_test.go
new file mode 100644
index 0000000..706b6cd
--- /dev/null
+++ b/internal/service/air_rescuer_checklist_service_test.go
@@ -0,0 +1,986 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"testing"
+
+	"gorm.io/gorm"
+
+	airrescuechecklist "wucher/internal/domain/air_rescue_checklist"
+)
+
+type airRescuerChecklistTxRepoMock struct {
+	createChecklistCalled bool
+	createChecklistRow    *airrescuechecklist.AirRescuerChecklist
+	createChecklistErr    error
+	nextChecklistPosition int
+	nextChecklistPosErr   error
+	nextChecklistPosCalls int
+
+	lockChecklistByIDCalled bool
+	lockChecklistID         []byte
+	lockChecklistByIDErr    error
+
+	updateChecklistCalled bool
+	updateChecklistRow    *airrescuechecklist.AirRescuerChecklist
+	updateChecklistErr    error
+
+	softDeleteChecklistCalled bool
+	softDeleteChecklistID     []byte
+	softDeleteChecklistBy     []byte
+	softDeleteChecklistErr    error
+
+	softDeleteItemsByChecklistCalled bool
+	softDeleteItemsByChecklistID     []byte
+	softDeleteItemsByChecklistBy     []byte
+	softDeleteItemsByChecklistErr    error
+
+	createChecklistItemCalled bool
+	createChecklistItemRow    *airrescuechecklist.AirRescuerChecklistItem
+	createChecklistItemErr    error
+
+	createChecklistItemsCalled bool
+	createChecklistItemsRows   []airrescuechecklist.AirRescuerChecklistItem
+	createChecklistItemsErr    error
+	nextChecklistItemPosition  int
+	nextChecklistItemPosErr    error
+	nextChecklistItemPosCalls  int
+
+	lockChecklistItemByIDCalled bool
+	lockChecklistItemID         []byte
+	lockChecklistItemIDs        [][]byte
+	lockChecklistItemRows       map[string]*airrescuechecklist.AirRescuerChecklistItem
+	lockChecklistItemByIDErr    error
+
+	updateChecklistItemCalled bool
+	updateChecklistItemRow    *airrescuechecklist.AirRescuerChecklistItem
+	updateChecklistItemErr    error
+
+	softDeleteChecklistItemCalled bool
+	softDeleteChecklistItemID     []byte
+	softDeleteChecklistItemBy     []byte
+	softDeleteChecklistItemErr    error
+}
+
+func (m *airRescuerChecklistTxRepoMock) CreateChecklist(_ context.Context, row *airrescuechecklist.AirRescuerChecklist) error {
+	m.createChecklistCalled = true
+	m.createChecklistRow = row
+	return m.createChecklistErr
+}
+
+func (m *airRescuerChecklistTxRepoMock) NextChecklistPosition(_ context.Context, _ []byte, _ string) (int, error) {
+	m.nextChecklistPosCalls++
+	if m.nextChecklistPosErr != nil {
+		return 0, m.nextChecklistPosErr
+	}
+	if m.nextChecklistPosition > 0 {
+		return m.nextChecklistPosition, nil
+	}
+	return 1, nil
+}
+
+func (m *airRescuerChecklistTxRepoMock) LockChecklistByID(_ context.Context, id []byte) (*airrescuechecklist.AirRescuerChecklist, error) {
+	m.lockChecklistByIDCalled = true
+	m.lockChecklistID = append([]byte(nil), id...)
+	if m.lockChecklistByIDErr != nil {
+		return nil, m.lockChecklistByIDErr
+	}
+	return &airrescuechecklist.AirRescuerChecklist{ID: append([]byte(nil), id...)}, nil
+}
+
+func (m *airRescuerChecklistTxRepoMock) UpdateChecklist(_ context.Context, row *airrescuechecklist.AirRescuerChecklist) error {
+	m.updateChecklistCalled = true
+	m.updateChecklistRow = row
+	return m.updateChecklistErr
+}
+
+func (m *airRescuerChecklistTxRepoMock) SoftDeleteChecklist(_ context.Context, id []byte, deletedBy []byte) error {
+	m.softDeleteChecklistCalled = true
+	m.softDeleteChecklistID = append([]byte(nil), id...)
+	m.softDeleteChecklistBy = append([]byte(nil), deletedBy...)
+	return m.softDeleteChecklistErr
+}
+
+func (m *airRescuerChecklistTxRepoMock) SoftDeleteItemsByChecklistID(_ context.Context, checklistID []byte, deletedBy []byte) error {
+	m.softDeleteItemsByChecklistCalled = true
+	m.softDeleteItemsByChecklistID = append([]byte(nil), checklistID...)
+	m.softDeleteItemsByChecklistBy = append([]byte(nil), deletedBy...)
+	return m.softDeleteItemsByChecklistErr
+}
+
+func (m *airRescuerChecklistTxRepoMock) CreateChecklistItem(_ context.Context, row *airrescuechecklist.AirRescuerChecklistItem) error {
+	m.createChecklistItemCalled = true
+	m.createChecklistItemRow = row
+	return m.createChecklistItemErr
+}
+
+func (m *airRescuerChecklistTxRepoMock) CreateChecklistItems(_ context.Context, rows []airrescuechecklist.AirRescuerChecklistItem) error {
+	m.createChecklistItemsCalled = true
+	m.createChecklistItemsRows = append([]airrescuechecklist.AirRescuerChecklistItem(nil), rows...)
+	return m.createChecklistItemsErr
+}
+
+func (m *airRescuerChecklistTxRepoMock) NextChecklistItemPosition(_ context.Context, _ []byte) (int, error) {
+	m.nextChecklistItemPosCalls++
+	if m.nextChecklistItemPosErr != nil {
+		return 0, m.nextChecklistItemPosErr
+	}
+	if m.nextChecklistItemPosition > 0 {
+		return m.nextChecklistItemPosition, nil
+	}
+	return 1, nil
+}
+
+func (m *airRescuerChecklistTxRepoMock) LockChecklistItemByID(_ context.Context, id []byte) (*airrescuechecklist.AirRescuerChecklistItem, error) {
+	m.lockChecklistItemByIDCalled = true
+	m.lockChecklistItemID = append([]byte(nil), id...)
+	m.lockChecklistItemIDs = append(m.lockChecklistItemIDs, append([]byte(nil), id...))
+	if m.lockChecklistItemByIDErr != nil {
+		return nil, m.lockChecklistItemByIDErr
+	}
+	if m.lockChecklistItemRows != nil {
+		if row, ok := m.lockChecklistItemRows[string(id)]; ok {
+			dup := *row
+			dup.ID = append([]byte(nil), row.ID...)
+			dup.ChecklistID = append([]byte(nil), row.ChecklistID...)
+			return &dup, nil
+		}
+	}
+	return &airrescuechecklist.AirRescuerChecklistItem{ID: append([]byte(nil), id...)}, nil
+}
+
+func (m *airRescuerChecklistTxRepoMock) UpdateChecklistItem(_ context.Context, row *airrescuechecklist.AirRescuerChecklistItem) error {
+	m.updateChecklistItemCalled = true
+	m.updateChecklistItemRow = row
+	return m.updateChecklistItemErr
+}
+
+func (m *airRescuerChecklistTxRepoMock) SoftDeleteChecklistItem(_ context.Context, id []byte, deletedBy []byte) error {
+	m.softDeleteChecklistItemCalled = true
+	m.softDeleteChecklistItemID = append([]byte(nil), id...)
+	m.softDeleteChecklistItemBy = append([]byte(nil), deletedBy...)
+	return m.softDeleteChecklistItemErr
+}
+
+type airRescuerChecklistRepoMock struct {
+	txRepo     *airRescuerChecklistTxRepoMock
+	inTxCalled bool
+
+	getChecklistByIDCalled bool
+	getChecklistByIDID     []byte
+	getChecklistByIDRow    *airrescuechecklist.ChecklistHeaderView
+	getChecklistByIDErr    error
+
+	getChecklistItemByIDCalled bool
+	getChecklistItemByIDID     []byte
+	getChecklistItemByIDRow    *airrescuechecklist.ChecklistItemView
+	getChecklistItemByIDErr    error
+
+	listChecklistHeadersCalled bool
+	listChecklistHeadersFilter airrescuechecklist.ChecklistHeaderFilter
+	listChecklistHeadersRows   []airrescuechecklist.ChecklistHeaderView
+	listChecklistHeadersErr    error
+
+	listChecklistItemsByIDsCalled bool
+	listChecklistItemsByIDsArg    [][]byte
+	listChecklistItemsByIDsRows   []airrescuechecklist.ChecklistItemView
+	listChecklistItemsByIDsErr    error
+
+	listHEMSBasesCalled bool
+	listHEMSBasesFilter airrescuechecklist.HEMSBaseFilter
+	listHEMSBasesRows   []airrescuechecklist.HEMSBaseView
+	listHEMSBasesErr    error
+}
+
+func (m *airRescuerChecklistRepoMock) InTx(ctx context.Context, fn func(txRepo airrescuechecklist.TxRepository) error) error {
+	m.inTxCalled = true
+	return fn(m.txRepo)
+}
+
+func (m *airRescuerChecklistRepoMock) GetChecklistByID(_ context.Context, id []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+	m.getChecklistByIDCalled = true
+	m.getChecklistByIDID = append([]byte(nil), id...)
+	return m.getChecklistByIDRow, m.getChecklistByIDErr
+}
+
+func (m *airRescuerChecklistRepoMock) GetChecklistItemByID(_ context.Context, id []byte) (*airrescuechecklist.ChecklistItemView, error) {
+	m.getChecklistItemByIDCalled = true
+	m.getChecklistItemByIDID = append([]byte(nil), id...)
+	return m.getChecklistItemByIDRow, m.getChecklistItemByIDErr
+}
+
+func (m *airRescuerChecklistRepoMock) ListChecklistHeaders(_ context.Context, filter airrescuechecklist.ChecklistHeaderFilter) ([]airrescuechecklist.ChecklistHeaderView, error) {
+	m.listChecklistHeadersCalled = true
+	m.listChecklistHeadersFilter = filter
+	return m.listChecklistHeadersRows, m.listChecklistHeadersErr
+}
+
+func (m *airRescuerChecklistRepoMock) ListChecklistItemsByChecklistIDs(_ context.Context, checklistIDs [][]byte) ([]airrescuechecklist.ChecklistItemView, error) {
+	m.listChecklistItemsByIDsCalled = true
+	m.listChecklistItemsByIDsArg = append([][]byte(nil), checklistIDs...)
+	return m.listChecklistItemsByIDsRows, m.listChecklistItemsByIDsErr
+}
+
+func (m *airRescuerChecklistRepoMock) ListHEMSBases(_ context.Context, filter airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+	m.listHEMSBasesCalled = true
+	m.listHEMSBasesFilter = filter
+	return m.listHEMSBasesRows, m.listHEMSBasesErr
+}
+
+func TestAirRescuerChecklistServiceCreateChecklistItems(t *testing.T) {
+	checklistID := []byte("1234567890123456")
+	txRepo := &airRescuerChecklistTxRepoMock{nextChecklistItemPosition: 7}
+	repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+	svc := NewAirRescuerChecklistService(repo)
+
+	rows := []airrescuechecklist.AirRescuerChecklistItem{
+		{Name: "Check oxygen", Position: 0},
+		{Name: "Check radio", Position: 2},
+	}
+
+	if err := svc.CreateChecklistItems(context.Background(), checklistID, rows); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.inTxCalled {
+		t.Fatalf("expected CreateChecklistItems to run in transaction")
+	}
+	if !txRepo.lockChecklistByIDCalled {
+		t.Fatalf("expected checklist lock before create")
+	}
+	if !bytes.Equal(txRepo.lockChecklistID, checklistID) {
+		t.Fatalf("expected lock checklist id forwarded from path param")
+	}
+	if !txRepo.createChecklistItemsCalled {
+		t.Fatalf("expected bulk create items called")
+	}
+	if len(txRepo.createChecklistItemsRows) != 2 {
+		t.Fatalf("expected 2 rows, got %d", len(txRepo.createChecklistItemsRows))
+	}
+	if !bytes.Equal(txRepo.createChecklistItemsRows[0].ChecklistID, checklistID) || !bytes.Equal(txRepo.createChecklistItemsRows[1].ChecklistID, checklistID) {
+		t.Fatalf("expected checklist_id derived from path for all rows")
+	}
+	if txRepo.createChecklistItemsRows[0].Position != 7 {
+		t.Fatalf("expected first position auto-assigned to 7, got %d", txRepo.createChecklistItemsRows[0].Position)
+	}
+	if txRepo.createChecklistItemsRows[1].Position != 2 {
+		t.Fatalf("expected second position stay 2, got %d", txRepo.createChecklistItemsRows[1].Position)
+	}
+	if txRepo.nextChecklistItemPosCalls != 1 {
+		t.Fatalf("expected next checklist item position to be read once, got %d", txRepo.nextChecklistItemPosCalls)
+	}
+}
+
+func TestAirRescuerChecklistServiceCreateChecklistItems_AllowsDuplicatePosition(t *testing.T) {
+	checklistID := []byte("1234567890123456")
+	txRepo := &airRescuerChecklistTxRepoMock{}
+	repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+	svc := NewAirRescuerChecklistService(repo)
+
+	rows := []airrescuechecklist.AirRescuerChecklistItem{
+		{Name: "Battery", Position: 2},
+		{Name: "Radio", Position: 2},
+	}
+
+	if err := svc.CreateChecklistItems(context.Background(), checklistID, rows); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !txRepo.createChecklistItemsCalled {
+		t.Fatalf("expected bulk create called")
+	}
+	if len(txRepo.createChecklistItemsRows) != 2 {
+		t.Fatalf("expected 2 rows, got %d", len(txRepo.createChecklistItemsRows))
+	}
+	if txRepo.createChecklistItemsRows[0].Position != 2 || txRepo.createChecklistItemsRows[1].Position != 2 {
+		t.Fatalf("expected duplicate position to be preserved, got %d and %d", txRepo.createChecklistItemsRows[0].Position, txRepo.createChecklistItemsRows[1].Position)
+	}
+	if txRepo.nextChecklistItemPosCalls != 0 {
+		t.Fatalf("expected no auto position query when all positions are provided")
+	}
+}
+
+func TestAirRescuerChecklistServiceCreateChecklistItemsErrorBranches(t *testing.T) {
+	checklistID := []byte("1234567890123456")
+
+	t.Run("empty rows", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		if err := svc.CreateChecklistItems(context.Background(), checklistID, nil); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if repo.inTxCalled {
+			t.Fatalf("expected no transaction when rows are empty")
+		}
+	})
+
+	t.Run("lock checklist failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{lockChecklistByIDErr: errors.New("lock failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		err := svc.CreateChecklistItems(context.Background(), checklistID, []airrescuechecklist.AirRescuerChecklistItem{{Name: "A"}})
+		if err == nil || err.Error() != "lock failed" {
+			t.Fatalf("expected lock error, got %v", err)
+		}
+		if txRepo.createChecklistItemsCalled {
+			t.Fatalf("expected create items not called when lock fails")
+		}
+	})
+
+	t.Run("create bulk failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{createChecklistItemsErr: errors.New("create failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		err := svc.CreateChecklistItems(context.Background(), checklistID, []airrescuechecklist.AirRescuerChecklistItem{{Name: "A"}})
+		if err == nil || err.Error() != "create failed" {
+			t.Fatalf("expected create error, got %v", err)
+		}
+	})
+}
+
+func TestAirRescuerChecklistServiceReorderChecklistItems(t *testing.T) {
+	checklistID := []byte("1234567890123456")
+	itemA := []byte("1111111111111111")
+	itemB := []byte("2222222222222222")
+	updatedBy := []byte("aaaaaaaaaaaaaaaa")
+
+	txRepo := &airRescuerChecklistTxRepoMock{
+		lockChecklistItemRows: map[string]*airrescuechecklist.AirRescuerChecklistItem{
+			string(itemA): {ID: append([]byte(nil), itemA...), ChecklistID: append([]byte(nil), checklistID...), Name: "Item A", Position: 1},
+			string(itemB): {ID: append([]byte(nil), itemB...), ChecklistID: append([]byte(nil), checklistID...), Name: "Item B", Position: 2},
+		},
+	}
+	repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+	svc := NewAirRescuerChecklistService(repo)
+
+	err := svc.ReorderChecklistItems(context.Background(), checklistID, []airrescuechecklist.ChecklistItemReorderInput{
+		{ID: append([]byte(nil), itemA...), Position: 2},
+		{ID: append([]byte(nil), itemB...), Position: 1},
+	}, updatedBy)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.inTxCalled {
+		t.Fatalf("expected transaction for reorder")
+	}
+	if !txRepo.lockChecklistByIDCalled {
+		t.Fatalf("expected checklist lock for reorder")
+	}
+	if len(txRepo.lockChecklistItemIDs) != 2 {
+		t.Fatalf("expected two item locks, got %d", len(txRepo.lockChecklistItemIDs))
+	}
+	if !txRepo.updateChecklistItemCalled {
+		t.Fatalf("expected item updates to be executed")
+	}
+	if txRepo.updateChecklistItemRow == nil {
+		t.Fatalf("expected update row to be set")
+	}
+	if txRepo.updateChecklistItemRow.Position != 1 {
+		t.Fatalf("expected last update position to be 1, got %d", txRepo.updateChecklistItemRow.Position)
+	}
+	if !bytes.Equal(txRepo.updateChecklistItemRow.UpdatedBy, updatedBy) {
+		t.Fatalf("expected updated_by to be propagated")
+	}
+}
+
+func TestAirRescuerChecklistServiceReorderChecklistItemsBranches(t *testing.T) {
+	checklistID := []byte("1234567890123456")
+	itemID := []byte("1111111111111111")
+	otherChecklistID := []byte("2222222222222222")
+
+	t.Run("empty rows", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		err := svc.ReorderChecklistItems(context.Background(), checklistID, nil, nil)
+		if !errors.Is(err, gorm.ErrInvalidData) {
+			t.Fatalf("expected invalid data, got %v", err)
+		}
+		if repo.inTxCalled {
+			t.Fatalf("expected no transaction when rows are empty")
+		}
+	})
+
+	t.Run("lock checklist failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{lockChecklistByIDErr: errors.New("lock checklist failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		err := svc.ReorderChecklistItems(context.Background(), checklistID, []airrescuechecklist.ChecklistItemReorderInput{{ID: itemID, Position: 1}}, nil)
+		if err == nil || err.Error() != "lock checklist failed" {
+			t.Fatalf("expected checklist lock error, got %v", err)
+		}
+	})
+
+	t.Run("duplicate item ids in payload", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{
+			lockChecklistItemRows: map[string]*airrescuechecklist.AirRescuerChecklistItem{
+				string(itemID): {ID: append([]byte(nil), itemID...), ChecklistID: append([]byte(nil), checklistID...), Name: "Item", Position: 1},
+			},
+		}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		err := svc.ReorderChecklistItems(context.Background(), checklistID, []airrescuechecklist.ChecklistItemReorderInput{
+			{ID: append([]byte(nil), itemID...), Position: 1},
+			{ID: append([]byte(nil), itemID...), Position: 2},
+		}, nil)
+		if err == nil || err.Error() != "duplicate item_uuid in reorder payload" {
+			t.Fatalf("expected duplicate item error, got %v", err)
+		}
+	})
+
+	t.Run("item belongs to different checklist", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{
+			lockChecklistItemRows: map[string]*airrescuechecklist.AirRescuerChecklistItem{
+				string(itemID): {ID: append([]byte(nil), itemID...), ChecklistID: append([]byte(nil), otherChecklistID...), Name: "Item", Position: 1},
+			},
+		}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		err := svc.ReorderChecklistItems(context.Background(), checklistID, []airrescuechecklist.ChecklistItemReorderInput{{ID: itemID, Position: 3}}, nil)
+		if !errors.Is(err, gorm.ErrRecordNotFound) {
+			t.Fatalf("expected not found for different checklist item, got %v", err)
+		}
+	})
+
+	t.Run("update item failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{
+			lockChecklistItemRows: map[string]*airrescuechecklist.AirRescuerChecklistItem{
+				string(itemID): {ID: append([]byte(nil), itemID...), ChecklistID: append([]byte(nil), checklistID...), Name: "Item", Position: 1},
+			},
+			updateChecklistItemErr: errors.New("update failed"),
+		}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		err := svc.ReorderChecklistItems(context.Background(), checklistID, []airrescuechecklist.ChecklistItemReorderInput{{ID: itemID, Position: 1}}, nil)
+		if err == nil || err.Error() != "update failed" {
+			t.Fatalf("expected update failure, got %v", err)
+		}
+	})
+}
+
+func TestAirRescuerChecklistServiceUpdateChecklistWithNewItems(t *testing.T) {
+	checklistID := []byte("1234567890123456")
+	txRepo := &airRescuerChecklistTxRepoMock{nextChecklistItemPosition: 8}
+	repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+	svc := NewAirRescuerChecklistService(repo)
+
+	row := &airrescuechecklist.AirRescuerChecklist{
+		ID:       append([]byte(nil), checklistID...),
+		Position: 0,
+	}
+	newItems := []airrescuechecklist.AirRescuerChecklistItem{
+		{Name: "Check battery", Position: 0},
+		{Name: "Check stretcher lock", Position: 4},
+	}
+
+	if err := svc.UpdateChecklistWithNewItems(context.Background(), row, newItems); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.inTxCalled {
+		t.Fatalf("expected update flow to run in transaction")
+	}
+	if !txRepo.lockChecklistByIDCalled {
+		t.Fatalf("expected checklist lock")
+	}
+	if !bytes.Equal(txRepo.lockChecklistID, checklistID) {
+		t.Fatalf("expected lock ID from checklist")
+	}
+	if !txRepo.updateChecklistCalled {
+		t.Fatalf("expected header update called")
+	}
+	if txRepo.updateChecklistRow == nil || txRepo.updateChecklistRow.Position != 1 {
+		t.Fatalf("expected header position normalized to 1")
+	}
+	if !txRepo.createChecklistItemsCalled {
+		t.Fatalf("expected new items append called")
+	}
+	if len(txRepo.createChecklistItemsRows) != 2 {
+		t.Fatalf("expected 2 appended items")
+	}
+	if !bytes.Equal(txRepo.createChecklistItemsRows[0].ChecklistID, checklistID) || !bytes.Equal(txRepo.createChecklistItemsRows[1].ChecklistID, checklistID) {
+		t.Fatalf("expected all new_items to use checklist ID")
+	}
+	if txRepo.createChecklistItemsRows[0].Position != 8 {
+		t.Fatalf("expected first new item position auto-assigned to 8")
+	}
+	if txRepo.createChecklistItemsRows[1].Position != 4 {
+		t.Fatalf("expected second new item position remains 4")
+	}
+	if txRepo.nextChecklistItemPosCalls != 1 {
+		t.Fatalf("expected next checklist item position to be read once, got %d", txRepo.nextChecklistItemPosCalls)
+	}
+}
+
+func TestAirRescuerChecklistServiceUpdateChecklistWithNewItemsBranches(t *testing.T) {
+	checklistID := []byte("1234567890123456")
+
+	t.Run("new-items-only", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		err := svc.UpdateChecklistWithNewItems(
+			context.Background(),
+			nil,
+			[]airrescuechecklist.AirRescuerChecklistItem{{ChecklistID: append([]byte(nil), checklistID...), Name: "A"}},
+		)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if txRepo.updateChecklistCalled {
+			t.Fatalf("expected no header update when row is nil")
+		}
+		if !txRepo.createChecklistItemsCalled {
+			t.Fatalf("expected append items called")
+		}
+	})
+
+	t.Run("header-only", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		err := svc.UpdateChecklistWithNewItems(
+			context.Background(),
+			&airrescuechecklist.AirRescuerChecklist{ID: append([]byte(nil), checklistID...), Position: 2},
+			nil,
+		)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if !txRepo.updateChecklistCalled {
+			t.Fatalf("expected header update called")
+		}
+		if txRepo.createChecklistItemsCalled {
+			t.Fatalf("expected no append items when new_items empty")
+		}
+	})
+
+	t.Run("invalid payload", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		if err := svc.UpdateChecklistWithNewItems(context.Background(), nil, nil); err == nil {
+			t.Fatalf("expected invalid data error")
+		}
+	})
+
+	t.Run("lock failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{lockChecklistByIDErr: errors.New("lock failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		err := svc.UpdateChecklistWithNewItems(context.Background(), &airrescuechecklist.AirRescuerChecklist{ID: append([]byte(nil), checklistID...), Position: 1}, nil)
+		if err == nil || err.Error() != "lock failed" {
+			t.Fatalf("expected lock error, got %v", err)
+		}
+	})
+
+	t.Run("update failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{updateChecklistErr: errors.New("update failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		err := svc.UpdateChecklistWithNewItems(context.Background(), &airrescuechecklist.AirRescuerChecklist{ID: append([]byte(nil), checklistID...), Position: 1}, nil)
+		if err == nil || err.Error() != "update failed" {
+			t.Fatalf("expected update error, got %v", err)
+		}
+		if txRepo.createChecklistItemsCalled {
+			t.Fatalf("expected append not called when update failed")
+		}
+	})
+
+	t.Run("append failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{createChecklistItemsErr: errors.New("append failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+
+		err := svc.UpdateChecklistWithNewItems(
+			context.Background(),
+			&airrescuechecklist.AirRescuerChecklist{ID: append([]byte(nil), checklistID...), Position: 1},
+			[]airrescuechecklist.AirRescuerChecklistItem{{Name: "A"}},
+		)
+		if err == nil || err.Error() != "append failed" {
+			t.Fatalf("expected append error, got %v", err)
+		}
+	})
+}
+
+func TestAirRescuerChecklistServiceUpdateChecklistWithNewItemsInvalidChecklistIDFromItems(t *testing.T) {
+	txRepo := &airRescuerChecklistTxRepoMock{nextChecklistPosition: 5, nextChecklistItemPosition: 9}
+	repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+	svc := NewAirRescuerChecklistService(repo)
+
+	err := svc.UpdateChecklistWithNewItems(context.Background(), nil, []airrescuechecklist.AirRescuerChecklistItem{{Name: "A"}})
+	if err == nil {
+		t.Fatalf("expected invalid data error when new_items checklist id is empty")
+	}
+}
+
+func TestAirRescuerChecklistServiceCreateBulk(t *testing.T) {
+	checklistID := []byte("1234567890123456")
+	txRepo := &airRescuerChecklistTxRepoMock{nextChecklistPosition: 5, nextChecklistItemPosition: 9}
+	repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+	svc := NewAirRescuerChecklistService(repo)
+
+	rows := []airrescuechecklist.ChecklistCreateInput{
+		{
+			Checklist: airrescuechecklist.AirRescuerChecklist{
+				ID:       append([]byte(nil), checklistID...),
+				Position: 0,
+			},
+			Items: []airrescuechecklist.AirRescuerChecklistItem{
+				{Name: "Oxygen", Position: 0},
+			},
+		},
+	}
+	if err := svc.CreateBulk(context.Background(), rows); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.inTxCalled || !txRepo.createChecklistCalled || !txRepo.createChecklistItemCalled {
+		t.Fatalf("expected checklist and item created in transaction")
+	}
+	if txRepo.createChecklistRow == nil || txRepo.createChecklistRow.Position != 5 {
+		t.Fatalf("expected checklist position auto-assigned to 5")
+	}
+	if txRepo.createChecklistItemRow == nil || txRepo.createChecklistItemRow.Position != 9 {
+		t.Fatalf("expected item position auto-assigned to 9")
+	}
+	if !bytes.Equal(txRepo.createChecklistItemRow.ChecklistID, checklistID) {
+		t.Fatalf("expected item checklist id copied from created checklist")
+	}
+	if txRepo.nextChecklistPosCalls != 1 {
+		t.Fatalf("expected next checklist position to be read once, got %d", txRepo.nextChecklistPosCalls)
+	}
+	if txRepo.nextChecklistItemPosCalls != 1 {
+		t.Fatalf("expected next checklist item position to be read once, got %d", txRepo.nextChecklistItemPosCalls)
+	}
+}
+
+func TestAirRescuerChecklistServiceCreateBulkBranches(t *testing.T) {
+	t.Run("empty rows", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		if err := svc.CreateBulk(context.Background(), nil); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if repo.inTxCalled {
+			t.Fatalf("expected no transaction for empty rows")
+		}
+	})
+
+	t.Run("create checklist failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{createChecklistErr: errors.New("create checklist failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.CreateBulk(context.Background(), []airrescuechecklist.ChecklistCreateInput{{Checklist: airrescuechecklist.AirRescuerChecklist{}}})
+		if err == nil || err.Error() != "create checklist failed" {
+			t.Fatalf("expected create checklist error, got %v", err)
+		}
+	})
+
+	t.Run("create item failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{createChecklistItemErr: errors.New("create item failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.CreateBulk(context.Background(), []airrescuechecklist.ChecklistCreateInput{{
+			Checklist: airrescuechecklist.AirRescuerChecklist{},
+			Items:     []airrescuechecklist.AirRescuerChecklistItem{{Name: "A"}},
+		}})
+		if err == nil || err.Error() != "create item failed" {
+			t.Fatalf("expected create item error, got %v", err)
+		}
+	})
+}
+
+func TestAirRescuerChecklistServiceUpdateChecklist(t *testing.T) {
+	checklistID := []byte("1234567890123456")
+	txRepo := &airRescuerChecklistTxRepoMock{nextChecklistItemPosition: 6}
+	repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+	svc := NewAirRescuerChecklistService(repo)
+
+	row := &airrescuechecklist.AirRescuerChecklist{ID: append([]byte(nil), checklistID...), Position: 0}
+	if err := svc.UpdateChecklist(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if row.Position != 1 {
+		t.Fatalf("expected position normalized to 1")
+	}
+	if !txRepo.lockChecklistByIDCalled || !txRepo.updateChecklistCalled {
+		t.Fatalf("expected lock + update executed")
+	}
+}
+
+func TestAirRescuerChecklistServiceUpdateChecklistBranches(t *testing.T) {
+	t.Run("nil row", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		if err := svc.UpdateChecklist(context.Background(), nil); err == nil {
+			t.Fatalf("expected invalid data error")
+		}
+	})
+
+	t.Run("lock failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{lockChecklistByIDErr: errors.New("lock failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.UpdateChecklist(context.Background(), &airrescuechecklist.AirRescuerChecklist{ID: []byte("1234567890123456"), Position: 1})
+		if err == nil || err.Error() != "lock failed" {
+			t.Fatalf("expected lock error, got %v", err)
+		}
+	})
+
+	t.Run("update failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{updateChecklistErr: errors.New("update failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.UpdateChecklist(context.Background(), &airrescuechecklist.AirRescuerChecklist{ID: []byte("1234567890123456"), Position: 1})
+		if err == nil || err.Error() != "update failed" {
+			t.Fatalf("expected update error, got %v", err)
+		}
+	})
+}
+
+func TestAirRescuerChecklistServiceDeleteChecklist(t *testing.T) {
+	id := []byte("1234567890123456")
+	deletedBy := []byte("abcdefghijklmnop")
+	txRepo := &airRescuerChecklistTxRepoMock{}
+	repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+	svc := NewAirRescuerChecklistService(repo)
+
+	if err := svc.DeleteChecklist(context.Background(), id, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !txRepo.lockChecklistByIDCalled || !txRepo.softDeleteChecklistCalled || !txRepo.softDeleteItemsByChecklistCalled {
+		t.Fatalf("expected lock + soft delete header + soft delete items")
+	}
+	if !bytes.Equal(txRepo.softDeleteChecklistID, id) || !bytes.Equal(txRepo.softDeleteItemsByChecklistID, id) {
+		t.Fatalf("expected delete id propagated")
+	}
+}
+
+func TestAirRescuerChecklistServiceDeleteChecklistBranches(t *testing.T) {
+	id := []byte("1234567890123456")
+	deletedBy := []byte("abcdefghijklmnop")
+
+	t.Run("lock failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{lockChecklistByIDErr: errors.New("lock failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.DeleteChecklist(context.Background(), id, deletedBy)
+		if err == nil || err.Error() != "lock failed" {
+			t.Fatalf("expected lock error, got %v", err)
+		}
+	})
+
+	t.Run("soft delete header failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{softDeleteChecklistErr: errors.New("delete header failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.DeleteChecklist(context.Background(), id, deletedBy)
+		if err == nil || err.Error() != "delete header failed" {
+			t.Fatalf("expected header delete error, got %v", err)
+		}
+	})
+
+	t.Run("soft delete items failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{softDeleteItemsByChecklistErr: errors.New("delete items failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.DeleteChecklist(context.Background(), id, deletedBy)
+		if err == nil || err.Error() != "delete items failed" {
+			t.Fatalf("expected items delete error, got %v", err)
+		}
+	})
+}
+
+func TestAirRescuerChecklistServiceCreateChecklistItem(t *testing.T) {
+	checklistID := []byte("1234567890123456")
+	txRepo := &airRescuerChecklistTxRepoMock{nextChecklistItemPosition: 6}
+	repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+	svc := NewAirRescuerChecklistService(repo)
+
+	row := &airrescuechecklist.AirRescuerChecklistItem{ChecklistID: append([]byte(nil), checklistID...), Position: 0}
+	if err := svc.CreateChecklistItem(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !txRepo.lockChecklistByIDCalled || !txRepo.createChecklistItemCalled {
+		t.Fatalf("expected lock + create item")
+	}
+	if row.Position != 6 {
+		t.Fatalf("expected position auto-assigned")
+	}
+}
+
+func TestAirRescuerChecklistServiceCreateChecklistItemBranches(t *testing.T) {
+	t.Run("nil row", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		if err := svc.CreateChecklistItem(context.Background(), nil); err == nil {
+			t.Fatalf("expected invalid data error")
+		}
+	})
+
+	t.Run("lock failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{lockChecklistByIDErr: errors.New("lock failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.CreateChecklistItem(context.Background(), &airrescuechecklist.AirRescuerChecklistItem{ChecklistID: []byte("1234567890123456")})
+		if err == nil || err.Error() != "lock failed" {
+			t.Fatalf("expected lock error, got %v", err)
+		}
+	})
+
+	t.Run("create failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{createChecklistItemErr: errors.New("create failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.CreateChecklistItem(context.Background(), &airrescuechecklist.AirRescuerChecklistItem{ChecklistID: []byte("1234567890123456")})
+		if err == nil || err.Error() != "create failed" {
+			t.Fatalf("expected create error, got %v", err)
+		}
+	})
+}
+
+func TestAirRescuerChecklistServiceUpdateChecklistItem(t *testing.T) {
+	itemID := []byte("1234567890123456")
+	txRepo := &airRescuerChecklistTxRepoMock{}
+	repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+	svc := NewAirRescuerChecklistService(repo)
+
+	row := &airrescuechecklist.AirRescuerChecklistItem{ID: append([]byte(nil), itemID...), Position: 0}
+	if err := svc.UpdateChecklistItem(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !txRepo.lockChecklistItemByIDCalled || !txRepo.updateChecklistItemCalled {
+		t.Fatalf("expected lock + update item")
+	}
+	if row.Position != 1 {
+		t.Fatalf("expected position normalized")
+	}
+}
+
+func TestAirRescuerChecklistServiceUpdateChecklistItemBranches(t *testing.T) {
+	t.Run("nil row", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		if err := svc.UpdateChecklistItem(context.Background(), nil); err == nil {
+			t.Fatalf("expected invalid data error")
+		}
+	})
+
+	t.Run("lock failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{lockChecklistItemByIDErr: errors.New("lock item failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.UpdateChecklistItem(context.Background(), &airrescuechecklist.AirRescuerChecklistItem{ID: []byte("1234567890123456")})
+		if err == nil || err.Error() != "lock item failed" {
+			t.Fatalf("expected lock item error, got %v", err)
+		}
+	})
+
+	t.Run("update failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{updateChecklistItemErr: errors.New("update item failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.UpdateChecklistItem(context.Background(), &airrescuechecklist.AirRescuerChecklistItem{ID: []byte("1234567890123456")})
+		if err == nil || err.Error() != "update item failed" {
+			t.Fatalf("expected update item error, got %v", err)
+		}
+	})
+}
+
+func TestAirRescuerChecklistServiceDeleteChecklistItem(t *testing.T) {
+	itemID := []byte("1234567890123456")
+	deletedBy := []byte("abcdefghijklmnop")
+	txRepo := &airRescuerChecklistTxRepoMock{}
+	repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+	svc := NewAirRescuerChecklistService(repo)
+
+	if err := svc.DeleteChecklistItem(context.Background(), itemID, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !txRepo.lockChecklistItemByIDCalled || !txRepo.softDeleteChecklistItemCalled {
+		t.Fatalf("expected lock + soft delete item")
+	}
+	if !bytes.Equal(txRepo.softDeleteChecklistItemID, itemID) {
+		t.Fatalf("expected deleted item id propagated")
+	}
+}
+
+func TestAirRescuerChecklistServiceDeleteChecklistItemBranches(t *testing.T) {
+	itemID := []byte("1234567890123456")
+	deletedBy := []byte("abcdefghijklmnop")
+
+	t.Run("lock failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{lockChecklistItemByIDErr: errors.New("lock item failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.DeleteChecklistItem(context.Background(), itemID, deletedBy)
+		if err == nil || err.Error() != "lock item failed" {
+			t.Fatalf("expected lock item error, got %v", err)
+		}
+	})
+
+	t.Run("delete failed", func(t *testing.T) {
+		txRepo := &airRescuerChecklistTxRepoMock{softDeleteChecklistItemErr: errors.New("delete item failed")}
+		repo := &airRescuerChecklistRepoMock{txRepo: txRepo}
+		svc := NewAirRescuerChecklistService(repo)
+		err := svc.DeleteChecklistItem(context.Background(), itemID, deletedBy)
+		if err == nil || err.Error() != "delete item failed" {
+			t.Fatalf("expected delete item error, got %v", err)
+		}
+	})
+}
+
+func TestAirRescuerChecklistServiceReadWrappers(t *testing.T) {
+	checklistID := []byte("1234567890123456")
+	itemID := []byte("abcdefghijklmnop")
+	headers := []airrescuechecklist.ChecklistHeaderView{{Title: "A"}}
+	items := []airrescuechecklist.ChecklistItemView{{Name: "I"}}
+	bases := []airrescuechecklist.HEMSBaseView{{BaseName: "B"}}
+
+	repo := &airRescuerChecklistRepoMock{
+		txRepo:                      &airRescuerChecklistTxRepoMock{},
+		getChecklistByIDRow:         &airrescuechecklist.ChecklistHeaderView{ID: checklistID},
+		getChecklistItemByIDRow:     &airrescuechecklist.ChecklistItemView{ID: itemID},
+		listChecklistHeadersRows:    headers,
+		listChecklistItemsByIDsRows: items,
+		listHEMSBasesRows:           bases,
+	}
+	svc := NewAirRescuerChecklistService(repo)
+
+	if _, err := svc.GetChecklistByID(context.Background(), checklistID); err != nil {
+		t.Fatalf("GetChecklistByID error: %v", err)
+	}
+	if _, err := svc.GetChecklistItemByID(context.Background(), itemID); err != nil {
+		t.Fatalf("GetChecklistItemByID error: %v", err)
+	}
+	if _, err := svc.ListChecklistHeaders(context.Background(), airrescuechecklist.ChecklistHeaderFilter{ScopeCode: "TA"}); err != nil {
+		t.Fatalf("ListChecklistHeaders error: %v", err)
+	}
+	if _, err := svc.ListChecklistItemsByChecklistIDs(context.Background(), [][]byte{checklistID}); err != nil {
+		t.Fatalf("ListChecklistItemsByChecklistIDs error: %v", err)
+	}
+	if _, err := svc.ListHEMSBases(context.Background(), airrescuechecklist.HEMSBaseFilter{HEMSBaseID: checklistID}); err != nil {
+		t.Fatalf("ListHEMSBases error: %v", err)
+	}
+
+	if !repo.getChecklistByIDCalled || !repo.getChecklistItemByIDCalled || !repo.listChecklistHeadersCalled || !repo.listChecklistItemsByIDsCalled || !repo.listHEMSBasesCalled {
+		t.Fatalf("expected all read wrappers to delegate to repository")
+	}
+}
diff --git a/internal/service/audit_log_service.go b/internal/service/audit_log_service.go
new file mode 100644
index 0000000..90ea469
--- /dev/null
+++ b/internal/service/audit_log_service.go
@@ -0,0 +1,315 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log"
+	"strings"
+	"time"
+
+	"wucher/internal/domain/audit"
+)
+
+type AuditLogInput struct {
+	RequestID   string
+	ActorUserID []byte
+	Layer       string
+	Module      string
+	Action      string
+	Method      string
+	Path        string
+	StatusCode  int
+	Success     bool
+	IP          string
+	UserAgent   string
+	Message     string
+	Metadata    map[string]any
+}
+
+type AuditLogService struct {
+	repo        audit.Repository
+	queue       chan *audit.AuditLog
+	ipProtector SecretProtector
+}
+
+type AuditLogServiceDependencies struct {
+	QueueSize       int
+	Workers         int
+	IPEncryptionKey string
+}
+
+type auditLogListRepository interface {
+	List(ctx context.Context, filter string, methods []string, modules []string, actions []string, sort string, limit, offset int) ([]audit.AuditLog, int64, error)
+}
+
+func NewAuditLogService(repo audit.Repository, deps AuditLogServiceDependencies) *AuditLogService {
+	queueSize := deps.QueueSize
+	workers := deps.Workers
+	if queueSize <= 0 {
+		queueSize = 1024
+	}
+	if workers <= 0 {
+		workers = 2
+	}
+	key := strings.TrimSpace(deps.IPEncryptionKey)
+	svc := &AuditLogService{
+		repo:        repo,
+		queue:       make(chan *audit.AuditLog, queueSize),
+		ipProtector: newIPSecretProtector(key),
+	}
+	for i := 0; i < workers; i++ {
+		go svc.runWorker()
+	}
+	return svc
+}
+
+func (s *AuditLogService) Log(ctx context.Context, in AuditLogInput) {
+	if s == nil || s.repo == nil {
+		return
+	}
+	entry := &audit.AuditLog{
+		RequestID:   truncate(strings.TrimSpace(in.RequestID), 64),
+		ActorUserID: safeUserID(in.ActorUserID),
+		Layer:       truncate(strings.TrimSpace(in.Layer), 32),
+		Module:      truncate(strings.TrimSpace(in.Module), 64),
+		Action:      truncate(strings.TrimSpace(in.Action), 128),
+		Method:      truncate(strings.TrimSpace(in.Method), 12),
+		Path:        truncate(strings.TrimSpace(in.Path), 255),
+		StatusCode:  in.StatusCode,
+		Success:     in.Success,
+		IP:          sanitizeIP(in.IP, s.ipProtector),
+		UserAgent:   truncate(strings.TrimSpace(in.UserAgent), 255),
+		Message:     truncate(strings.TrimSpace(in.Message), 512),
+		CreatedAt:   time.Now().UTC(),
+	}
+	if len(in.Metadata) > 0 {
+		if b, err := json.Marshal(in.Metadata); err == nil {
+			entry.Metadata = truncateBytes(b, 8192)
+		}
+	}
+
+	select {
+	case s.queue <- entry:
+	default:
+		log.Printf("audit queue_full layer=%s action=%s", entry.Layer, entry.Action)
+	}
+}
+
+func (s *AuditLogService) List(ctx context.Context, filter string, methods []string, modules []string, actions []string, sort string, limit, offset int) ([]audit.AuditLog, int64, error) {
+	if s == nil || s.repo == nil {
+		return nil, 0, errors.New("audit service not configured")
+	}
+	lister, ok := s.repo.(auditLogListRepository)
+	if !ok {
+		return nil, 0, errors.New("audit listing not supported by repository")
+	}
+	if limit < 0 {
+		limit = 0
+	}
+	if limit > 200 {
+		limit = 200
+	}
+	if offset < 0 {
+		offset = 0
+	}
+	methods, actions = enforceAuditMutationFilters(methods, actions)
+	rows, total, err := lister.List(
+		ctx,
+		strings.TrimSpace(filter),
+		normalizeAuditMethods(methods),
+		normalizeAuditTokens(modules),
+		normalizeAuditTokens(actions),
+		normalizeAuditSort(sort),
+		limit,
+		offset,
+	)
+	if err != nil {
+		return nil, 0, err
+	}
+	for i := range rows {
+		rows[i].IP = decryptStoredIP(rows[i].IP, s.ipProtector)
+	}
+	return rows, total, nil
+}
+
+func enforceAuditMutationFilters(methods, actions []string) ([]string, []string) {
+	allowedMethods := []string{"POST", "PUT", "PATCH", "DELETE"}
+	allowedActions := []string{"create", "update", "delete"}
+
+	methods = enforceAllowedMethods(methods, allowedMethods)
+	actions = enforceAllowedTokens(actions, allowedActions)
+	return methods, actions
+}
+
+func enforceAllowedMethods(values []string, allowed []string) []string {
+	if len(values) == 0 {
+		return append([]string(nil), allowed...)
+	}
+	allowedSet := make(map[string]struct{}, len(allowed))
+	for _, value := range allowed {
+		allowedSet[strings.ToUpper(strings.TrimSpace(value))] = struct{}{}
+	}
+	out := make([]string, 0, len(values))
+	seen := make(map[string]struct{}, len(values))
+	for _, value := range values {
+		v := strings.ToUpper(strings.TrimSpace(value))
+		if v == "UPDATE" {
+			if _, ok := allowedSet["PUT"]; ok {
+				if _, exists := seen["PUT"]; !exists {
+					seen["PUT"] = struct{}{}
+					out = append(out, "PUT")
+				}
+			}
+			if _, ok := allowedSet["PATCH"]; ok {
+				if _, exists := seen["PATCH"]; !exists {
+					seen["PATCH"] = struct{}{}
+					out = append(out, "PATCH")
+				}
+			}
+			continue
+		}
+		if _, ok := allowedSet[v]; !ok {
+			continue
+		}
+		if _, exists := seen[v]; exists {
+			continue
+		}
+		seen[v] = struct{}{}
+		out = append(out, v)
+	}
+	if len(out) == 0 {
+		return append([]string(nil), allowed...)
+	}
+	return out
+}
+
+func enforceAllowedTokens(values []string, allowed []string) []string {
+	if len(values) == 0 {
+		return append([]string(nil), allowed...)
+	}
+	allowedSet := make(map[string]struct{}, len(allowed))
+	for _, value := range allowed {
+		allowedSet[strings.ToLower(strings.TrimSpace(value))] = struct{}{}
+	}
+	out := make([]string, 0, len(values))
+	seen := make(map[string]struct{}, len(values))
+	for _, value := range values {
+		v := strings.ToLower(strings.TrimSpace(value))
+		if _, ok := allowedSet[v]; !ok {
+			continue
+		}
+		if _, exists := seen[v]; exists {
+			continue
+		}
+		seen[v] = struct{}{}
+		out = append(out, v)
+	}
+	if len(out) == 0 {
+		return append([]string(nil), allowed...)
+	}
+	return out
+}
+
+func (s *AuditLogService) runWorker() {
+	for entry := range s.queue {
+		if entry == nil {
+			continue
+		}
+		ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+		err := s.repo.Create(ctx, entry)
+		cancel()
+		if err != nil {
+			log.Printf("audit persist_failed layer=%s action=%s err=%v", entry.Layer, entry.Action, err)
+		}
+	}
+}
+
+func safeUserID(id []byte) []byte {
+	if len(id) != 16 {
+		return nil
+	}
+	dst := make([]byte, 16)
+	copy(dst, id)
+	return dst
+}
+
+func truncateBytes(v []byte, max int) []byte {
+	if max <= 0 || len(v) <= max {
+		return v
+	}
+	out := make([]byte, max)
+	copy(out, v[:max])
+	return out
+}
+
+func normalizeAuditSort(sort string) string {
+	if normalized := normalizeSortByRules(strings.TrimSpace(sort),
+		sortField("created_at"),
+		sortField("action"),
+		sortField("module"),
+		sortField("layer"),
+		sortField("status_code"),
+		sortField("success"),
+	); normalized != "" {
+		return normalized
+	}
+	return "created_at DESC"
+}
+
+func normalizeAuditTokens(values []string) []string {
+	if len(values) == 0 {
+		return nil
+	}
+	seen := make(map[string]struct{}, len(values))
+	out := make([]string, 0, len(values))
+	for _, value := range values {
+		v := strings.ToLower(strings.TrimSpace(value))
+		switch v {
+		case "", "all", "*":
+			return nil
+		default:
+			if _, ok := seen[v]; !ok {
+				seen[v] = struct{}{}
+				out = append(out, v)
+			}
+		}
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func normalizeAuditMethods(methods []string) []string {
+	if len(methods) == 0 {
+		return nil
+	}
+	seen := make(map[string]struct{}, len(methods))
+	out := make([]string, 0, len(methods))
+	for _, method := range methods {
+		v := strings.ToUpper(strings.TrimSpace(method))
+		switch v {
+		case "", "ALL", "*":
+			return nil
+		case "GET", "POST", "PUT", "PATCH", "DELETE":
+			if _, ok := seen[v]; !ok {
+				seen[v] = struct{}{}
+				out = append(out, v)
+			}
+		case "UPDATE":
+			if _, ok := seen["PUT"]; !ok {
+				seen["PUT"] = struct{}{}
+				out = append(out, "PUT")
+			}
+			if _, ok := seen["PATCH"]; !ok {
+				seen["PATCH"] = struct{}{}
+				out = append(out, "PATCH")
+			}
+		}
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
diff --git a/internal/service/audit_log_service_test.go b/internal/service/audit_log_service_test.go
new file mode 100644
index 0000000..6c950ff
--- /dev/null
+++ b/internal/service/audit_log_service_test.go
@@ -0,0 +1,288 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	"wucher/internal/domain/audit"
+)
+
+type mockAuditRepo struct {
+	mu          sync.Mutex
+	entries     []*audit.AuditLog
+	createCalls int
+	createErr   error
+	listRows    []audit.AuditLog
+	listTotal   int64
+	listErr     error
+	lastFilter  string
+	lastMethods []string
+	lastModules []string
+	lastActions []string
+	lastSort    string
+	lastLimit   int
+	lastOffset  int
+}
+
+func (m *mockAuditRepo) Create(_ context.Context, entry *audit.AuditLog) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.createCalls++
+	cp := *entry
+	m.entries = append(m.entries, &cp)
+	return m.createErr
+}
+
+func (m *mockAuditRepo) List(_ context.Context, filter string, methods []string, modules []string, actions []string, sort string, limit, offset int) ([]audit.AuditLog, int64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.lastFilter = filter
+	m.lastMethods = append([]string(nil), methods...)
+	m.lastModules = append([]string(nil), modules...)
+	m.lastActions = append([]string(nil), actions...)
+	m.lastSort = sort
+	m.lastLimit = limit
+	m.lastOffset = offset
+	if m.listErr != nil {
+		return nil, 0, m.listErr
+	}
+	out := make([]audit.AuditLog, len(m.listRows))
+	copy(out, m.listRows)
+	return out, m.listTotal, nil
+}
+
+func TestAuditLogService_LogAsync(t *testing.T) {
+	repo := &mockAuditRepo{}
+	svc := NewAuditLogService(repo, AuditLogServiceDependencies{QueueSize: 8, Workers: 1, IPEncryptionKey: "pepper"})
+	defer close(svc.queue)
+
+	svc.Log(context.Background(), AuditLogInput{
+		RequestID:  "req-1",
+		Layer:      "service",
+		Action:     "auth.reset_password.consume",
+		Success:    true,
+		StatusCode: 200,
+		IP:         "127.0.0.1",
+		Message:    "ok",
+		Metadata: map[string]any{
+			"k": "v",
+		},
+	})
+
+	deadline := time.Now().Add(500 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		repo.mu.Lock()
+		n := len(repo.entries)
+		repo.mu.Unlock()
+		if n > 0 {
+			break
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	repo.mu.Lock()
+	defer repo.mu.Unlock()
+	if len(repo.entries) != 1 {
+		t.Fatalf("expected 1 audit entry, got %d", len(repo.entries))
+	}
+	if repo.entries[0].Action != "auth.reset_password.consume" {
+		t.Fatalf("unexpected action: %s", repo.entries[0].Action)
+	}
+	if repo.entries[0].IP == "127.0.0.1" {
+		t.Fatalf("expected encrypted ip to be persisted")
+	}
+	if plain := decryptStoredIP(repo.entries[0].IP, newIPSecretProtector("pepper")); plain != "127.0.0.1" {
+		t.Fatalf("unexpected decrypted ip: %s", plain)
+	}
+}
+
+func TestAuditLogService_NewAuditLogService_Defaults(t *testing.T) {
+	repo := &mockAuditRepo{}
+	svc := NewAuditLogService(repo, AuditLogServiceDependencies{QueueSize: 0, Workers: 0})
+	defer close(svc.queue)
+
+	if cap(svc.queue) != 1024 {
+		t.Fatalf("expected default queue size 1024, got %d", cap(svc.queue))
+	}
+
+	svc.Log(context.Background(), AuditLogInput{
+		Layer:  "service",
+		Action: "audit.defaults",
+	})
+
+	deadline := time.Now().Add(500 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		repo.mu.Lock()
+		n := len(repo.entries)
+		repo.mu.Unlock()
+		if n > 0 {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	t.Fatalf("expected default workers to process queued entry")
+}
+
+func TestAuditLogService_Log_NoopAndQueueBehavior(t *testing.T) {
+	t.Run("no-op when receiver is nil", func(t *testing.T) {
+		var svc *AuditLogService
+		svc.Log(context.Background(), AuditLogInput{Layer: "service", Action: "noop"})
+	})
+
+	t.Run("no-op when repo is nil", func(t *testing.T) {
+		svc := &AuditLogService{repo: nil, queue: make(chan *audit.AuditLog, 1)}
+		svc.Log(context.Background(), AuditLogInput{Layer: "service", Action: "noop"})
+		if len(svc.queue) != 0 {
+			t.Fatalf("expected no queued entries when repo is nil")
+		}
+	})
+
+	t.Run("metadata marshal failure does not panic and leaves metadata empty", func(t *testing.T) {
+		svc := &AuditLogService{
+			repo:  &mockAuditRepo{},
+			queue: make(chan *audit.AuditLog, 1),
+		}
+		svc.Log(context.Background(), AuditLogInput{
+			Layer:    "service",
+			Action:   "audit.bad_metadata",
+			Metadata: map[string]any{"bad": func() {}},
+		})
+
+		if len(svc.queue) != 1 {
+			t.Fatalf("expected one queued entry")
+		}
+		entry := <-svc.queue
+		if len(entry.Metadata) != 0 {
+			t.Fatalf("expected metadata to be empty when marshal fails")
+		}
+	})
+
+	t.Run("queue full branch drops extra entry", func(t *testing.T) {
+		svc := &AuditLogService{
+			repo:  &mockAuditRepo{},
+			queue: make(chan *audit.AuditLog, 1),
+		}
+		svc.Log(context.Background(), AuditLogInput{Layer: "service", Action: "first"})
+		svc.Log(context.Background(), AuditLogInput{Layer: "service", Action: "second"})
+
+		if len(svc.queue) != 1 {
+			t.Fatalf("expected queue to contain only first entry, got %d", len(svc.queue))
+		}
+		entry := <-svc.queue
+		if entry.Action != "first" {
+			t.Fatalf("expected first entry to be retained, got %q", entry.Action)
+		}
+	})
+}
+
+func TestAuditLogService_runWorker_NilEntryAndPersistError(t *testing.T) {
+	repo := &mockAuditRepo{createErr: errors.New("persist failed")}
+	svc := &AuditLogService{
+		repo:  repo,
+		queue: make(chan *audit.AuditLog, 2),
+	}
+
+	done := make(chan struct{})
+	go func() {
+		svc.runWorker()
+		close(done)
+	}()
+
+	svc.queue <- nil
+	svc.queue <- &audit.AuditLog{
+		Layer:  "service",
+		Action: "audit.persist_error",
+	}
+	close(svc.queue)
+
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatalf("worker did not stop after queue close")
+	}
+
+	repo.mu.Lock()
+	defer repo.mu.Unlock()
+	if repo.createCalls != 1 {
+		t.Fatalf("expected exactly one repo.Create call for non-nil entry, got %d", repo.createCalls)
+	}
+	if len(repo.entries) != 1 {
+		t.Fatalf("expected one persisted entry attempt, got %d", len(repo.entries))
+	}
+	if repo.entries[0].Action != "audit.persist_error" {
+		t.Fatalf("unexpected persisted action: %s", repo.entries[0].Action)
+	}
+}
+
+func TestTruncateBytes(t *testing.T) {
+	original := []byte("abcdef")
+
+	t.Run("max less than or equal zero returns original bytes", func(t *testing.T) {
+		got := truncateBytes(original, 0)
+		if string(got) != string(original) {
+			t.Fatalf("expected %q, got %q", string(original), string(got))
+		}
+	})
+
+	t.Run("len less than or equal max returns original bytes", func(t *testing.T) {
+		got := truncateBytes(original, len(original))
+		if string(got) != string(original) {
+			t.Fatalf("expected %q, got %q", string(original), string(got))
+		}
+	})
+
+	t.Run("len greater than max returns truncated bytes", func(t *testing.T) {
+		got := truncateBytes(original, 3)
+		if string(got) != "abc" {
+			t.Fatalf("expected %q, got %q", "abc", string(got))
+		}
+		if len(got) != 3 {
+			t.Fatalf("expected len 3, got %d", len(got))
+		}
+	})
+}
+
+func TestAuditLogService_List(t *testing.T) {
+	encIP := sanitizeIP("127.0.0.1", newIPSecretProtector("pepper"))
+	repo := &mockAuditRepo{
+		listRows: []audit.AuditLog{
+			{Layer: "api", Action: "http.request", IP: encIP},
+		},
+		listTotal: 1,
+	}
+	svc := NewAuditLogService(repo, AuditLogServiceDependencies{QueueSize: 8, Workers: 1, IPEncryptionKey: "pepper"})
+	defer close(svc.queue)
+
+	rows, total, err := svc.List(context.Background(), "http", []string{"GET", "update"}, []string{"helicopters"}, []string{"list"}, "-created_at", 20, 0)
+	if err != nil {
+		t.Fatalf("List returned error: %v", err)
+	}
+	if total != 1 || len(rows) != 1 {
+		t.Fatalf("unexpected list result total=%d len=%d", total, len(rows))
+	}
+	if rows[0].IP != "127.0.0.1" {
+		t.Fatalf("expected decrypted ip in list response, got %q", rows[0].IP)
+	}
+
+	repo.mu.Lock()
+	defer repo.mu.Unlock()
+	if repo.lastSort != "created_at DESC" {
+		t.Fatalf("expected normalized sort created_at DESC, got %q", repo.lastSort)
+	}
+	if repo.lastFilter != "http" {
+		t.Fatalf("expected filter propagated, got %q", repo.lastFilter)
+	}
+	if len(repo.lastMethods) != 2 || repo.lastMethods[0] != "PUT" || repo.lastMethods[1] != "PATCH" {
+		t.Fatalf("expected normalized methods [PUT PATCH], got %#v", repo.lastMethods)
+	}
+	if len(repo.lastModules) != 1 || repo.lastModules[0] != "helicopters" {
+		t.Fatalf("expected modules [helicopters], got %#v", repo.lastModules)
+	}
+	if len(repo.lastActions) != 3 || repo.lastActions[0] != "create" || repo.lastActions[1] != "update" || repo.lastActions[2] != "delete" {
+		t.Fatalf("expected actions [create update delete], got %#v", repo.lastActions)
+	}
+}
diff --git a/internal/service/auth_email_template.go b/internal/service/auth_email_template.go
new file mode 100644
index 0000000..dcf5e95
--- /dev/null
+++ b/internal/service/auth_email_template.go
@@ -0,0 +1,559 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"html"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	filemanager "wucher/internal/domain/file_manager"
+	mastersettings "wucher/internal/domain/master_settings"
+	"wucher/internal/queue"
+)
+
+const (
+	defaultEmailBrandingCompanyName = "Wucher"
+	authEmailLogoCID                = "branding-email-logo"
+	authEmailLogoFilename           = "email-logo.png"
+	authEmailLogoFetchTimeout       = 10 * time.Second
+	authEmailLogoMaxBytes           = 5 << 20
+	authEmailLogoPresignTTL         = time.Minute
+)
+
+type AuthEmailBranding struct {
+	CompanyName    string
+	LogoContentID  string
+	LogoAttachment *queue.EmailAttachment
+}
+
+type BuiltAuthEmail struct {
+	Subject     string
+	TextBody    string
+	HTMLBody    string
+	Attachments []queue.EmailAttachment
+}
+
+type AuthEmailBrandingResolver interface {
+	ResolveEmailBranding(ctx context.Context) AuthEmailBranding
+}
+
+type authEmailBrandingResolver struct {
+	masterSvc  mastersettings.Service
+	fileSvc    filemanager.Service
+	storage    filemanager.ObjectStorage
+	httpClient *http.Client
+}
+
+func NewAuthEmailBrandingResolver(masterSvc mastersettings.Service, fileSvc filemanager.Service, storage filemanager.ObjectStorage) AuthEmailBrandingResolver {
+	return &authEmailBrandingResolver{
+		masterSvc: masterSvc,
+		fileSvc:   fileSvc,
+		storage:   storage,
+		httpClient: &http.Client{
+			Timeout: authEmailLogoFetchTimeout,
+		},
+	}
+}
+
+func (r *authEmailBrandingResolver) ResolveEmailBranding(ctx context.Context) AuthEmailBranding {
+	branding := AuthEmailBranding{
+		CompanyName: defaultEmailBrandingCompanyName,
+	}
+	if r == nil || r.masterSvc == nil {
+		return branding
+	}
+
+	rows, _, err := r.masterSvc.List(ctx, "", "-updated_at", 1, 0)
+	if err != nil || len(rows) == 0 {
+		return branding
+	}
+	row := rows[0]
+	if companyName := strings.TrimSpace(row.CompanyName); companyName != "" {
+		branding.CompanyName = companyName
+	}
+	if len(row.LogoFileID) == 0 {
+		return branding
+	}
+
+	attachment, err := r.resolveInlineLogoAttachment(ctx, row.LogoFileID)
+	if err != nil || attachment == nil {
+		return branding
+	}
+	branding.LogoContentID = attachment.ContentID
+	branding.LogoAttachment = attachment
+	return branding
+}
+
+func (r *authEmailBrandingResolver) resolveInlineLogoAttachment(ctx context.Context, fileID []byte) (*queue.EmailAttachment, error) {
+	if r == nil || r.fileSvc == nil {
+		return nil, errors.New("file manager service is not configured")
+	}
+	if r.storage == nil {
+		return nil, errors.New("object storage is not configured")
+	}
+
+	fileRow, err := r.fileSvc.GetFileByID(ctx, fileID)
+	if err != nil {
+		return nil, fmt.Errorf("get managed branding file: %w", err)
+	}
+	if fileRow == nil {
+		return nil, errors.New("managed branding file not found")
+	}
+	if !strings.EqualFold(strings.TrimSpace(fileRow.Status), filemanager.FileStatusReady) {
+		return nil, errors.New("managed branding file is not ready")
+	}
+
+	objectKey, declaredContentType, err := selectAuthEmailLogoVariant(fileRow)
+	if err != nil {
+		return nil, err
+	}
+	presigned, err := r.storage.PresignGetObject(ctx, objectKey, authEmailLogoPresignTTL)
+	if err != nil {
+		return nil, fmt.Errorf("presign managed branding object: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, presigned, nil)
+	if err != nil {
+		return nil, fmt.Errorf("build object request: %w", err)
+	}
+	resp, err := r.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("download logo object: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("object storage returned status %d", resp.StatusCode)
+	}
+
+	limited := io.LimitReader(resp.Body, authEmailLogoMaxBytes+1)
+	body, err := io.ReadAll(limited)
+	if err != nil {
+		return nil, fmt.Errorf("read logo object body: %w", err)
+	}
+	if len(body) == 0 {
+		return nil, errors.New("logo object body is empty")
+	}
+	if len(body) > authEmailLogoMaxBytes {
+		return nil, errors.New("logo object exceeds max allowed size")
+	}
+
+	contentType := strings.TrimSpace(resp.Header.Get("Content-Type"))
+	if contentType == "" {
+		contentType = declaredContentType
+	}
+	if !isAuthEmailSafeImageContentType(contentType) {
+		return nil, errors.New("managed branding asset is not email-safe")
+	}
+
+	return &queue.EmailAttachment{
+		Filename:    authEmailLogoFilename,
+		ContentType: normalizeAuthEmailImageContentType(contentType),
+		ContentID:   authEmailLogoCID,
+		Content:     body,
+		Inline:      true,
+	}, nil
+}
+
+func selectAuthEmailLogoVariant(fileRow *filemanager.File) (string, string, error) {
+	if fileRow == nil {
+		return "", "", errors.New("managed branding file is missing")
+	}
+	if fileRow.ThumbnailObjectKey != nil {
+		thumbKey := strings.TrimSpace(*fileRow.ThumbnailObjectKey)
+		thumbType := strings.TrimSpace(authEmailPtrStringValue(fileRow.ThumbnailMimeType))
+		if thumbKey != "" && isAuthEmailSafeImageContentType(thumbType) {
+			return thumbKey, thumbType, nil
+		}
+	}
+	originalKey := strings.TrimSpace(fileRow.ObjectKey)
+	originalType := strings.TrimSpace(fileRow.MimeType)
+	if originalKey != "" && isAuthEmailSafeImageContentType(originalType) {
+		return originalKey, originalType, nil
+	}
+	return "", "", errors.New("managed branding file has no email-safe variant")
+}
+
+func isAuthEmailSafeImageContentType(contentType string) bool {
+	contentType = normalizeAuthEmailImageContentType(contentType)
+	switch contentType {
+	case "image/png", "image/jpeg", "image/gif":
+		return true
+	default:
+		return false
+	}
+}
+
+func normalizeAuthEmailImageContentType(contentType string) string {
+	contentType = strings.ToLower(strings.TrimSpace(contentType))
+	if idx := strings.Index(contentType, ";"); idx >= 0 {
+		contentType = strings.TrimSpace(contentType[:idx])
+	}
+	if contentType == "image/jpg" {
+		return "image/jpeg"
+	}
+	return contentType
+}
+
+func authEmailPtrStringValue(v *string) string {
+	if v == nil {
+		return ""
+	}
+	return *v
+}
+
+type AuthEmailTemplateContent struct {
+	Subject    string
+	Greeting   string
+	Title      string
+	Message    []string
+	Code       string
+	CTALabel   string
+	CTAURL     string
+	HelpText   string
+	FooterText string
+}
+
+func buildAuthEmailTemplate(ctx context.Context, resolver AuthEmailBrandingResolver, content AuthEmailTemplateContent) BuiltAuthEmail {
+	subject := strings.TrimSpace(content.Subject)
+	greeting := strings.TrimSpace(content.Greeting)
+	title := strings.TrimSpace(content.Title)
+	ctaLabel := strings.TrimSpace(content.CTALabel)
+	ctaURL := strings.TrimSpace(content.CTAURL)
+	helpText := strings.TrimSpace(content.HelpText)
+	footerText := strings.TrimSpace(content.FooterText)
+	code := strings.TrimSpace(content.Code)
+
+	messageParts := make([]string, 0, len(content.Message))
+	for i := range content.Message {
+		part := strings.TrimSpace(content.Message[i])
+		if part == "" {
+			continue
+		}
+		messageParts = append(messageParts, part)
+	}
+
+	textLines := make([]string, 0, len(messageParts)+10)
+	if greeting != "" {
+		textLines = append(textLines, greeting, "")
+	}
+	textLines = append(textLines, title, "")
+	textLines = append(textLines, messageParts...)
+	if code != "" {
+		textLines = append(textLines, code)
+	}
+	if ctaURL != "" {
+		textLines = append(textLines, "", ctaLabel+":", ctaURL)
+	}
+	if helpText != "" {
+		textLines = append(textLines, "", helpText)
+	}
+	if footerText != "" {
+		textLines = append(textLines, "", footerText)
+	}
+
+	branding := AuthEmailBranding{CompanyName: defaultEmailBrandingCompanyName}
+	if resolver != nil {
+		branding = resolver.ResolveEmailBranding(ctx)
+		if strings.TrimSpace(branding.CompanyName) == "" {
+			branding.CompanyName = defaultEmailBrandingCompanyName
+		}
+	}
+
+	var attachments []queue.EmailAttachment
+	if branding.LogoAttachment != nil {
+		attachments = append(attachments, cloneAuthEmailAttachment(*branding.LogoAttachment))
+	}
+
+	return BuiltAuthEmail{
+		Subject:     subject,
+		TextBody:    strings.Join(textLines, "\n"),
+		HTMLBody:    renderAuthEmailHTML(branding, AuthEmailTemplateContent{Subject: subject, Greeting: greeting, Title: title, Message: messageParts, Code: code, CTALabel: ctaLabel, CTAURL: ctaURL, HelpText: helpText, FooterText: footerText}),
+		Attachments: attachments,
+	}
+}
+
+func cloneAuthEmailAttachment(attachment queue.EmailAttachment) queue.EmailAttachment {
+	attachment.Content = append([]byte(nil), attachment.Content...)
+	return attachment
+}
+
+// emailFontStack is the cross-client system font stack used in all email cells.
+const emailFontStack = `-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif`
+
+// emailCell writes an opening <tr><td> with the given inline style.
+func emailCell(b *strings.Builder, style string) {
+	b.WriteString(`<tr><td style="`)
+	b.WriteString(style)
+	b.WriteString(`">`)
+}
+
+func emailCellClose(b *strings.Builder) {
+	b.WriteString(`</td></tr>`)
+}
+
+// emailSpacer writes a zero-content spacer row.
+func emailSpacer(b *strings.Builder, height string) {
+	b.WriteString(`<tr><td style="height:`)
+	b.WriteString(height)
+	b.WriteString(`;font-size:0;line-height:0;">&nbsp;</td></tr>`)
+}
+
+// emailDivider writes a 1px horizontal rule as a nested table (Outlook-safe).
+func emailDivider(b *strings.Builder) {
+	b.WriteString(`<tr><td style="padding:0 32px;">`)
+	b.WriteString(`<table role="presentation" width="100%" cellspacing="0" cellpadding="0">`)
+	b.WriteString(`<tr><td style="height:1px;background-color:#e4e4e7;font-size:0;line-height:0;">&nbsp;</td></tr>`)
+	b.WriteString(`</table></td></tr>`)
+}
+
+func renderAuthEmailHTML(branding AuthEmailBranding, content AuthEmailTemplateContent) string {
+	subject := html.EscapeString(strings.TrimSpace(content.Subject))
+	greeting := html.EscapeString(strings.TrimSpace(content.Greeting))
+	title := html.EscapeString(strings.TrimSpace(content.Title))
+	ctaLabel := html.EscapeString(strings.TrimSpace(content.CTALabel))
+	ctaURL := html.EscapeString(strings.TrimSpace(content.CTAURL))
+	helpText := html.EscapeString(strings.TrimSpace(content.HelpText))
+	footerText := html.EscapeString(strings.TrimSpace(content.FooterText))
+	code := html.EscapeString(strings.TrimSpace(content.Code))
+	companyName := html.EscapeString(strings.TrimSpace(branding.CompanyName))
+	logoContentID := html.EscapeString(strings.TrimSpace(branding.LogoContentID))
+
+	var b strings.Builder
+
+	b.WriteString(`<!DOCTYPE html><html lang="en">`)
+	b.WriteString(`<head>`)
+	b.WriteString(`<meta charset="UTF-8">`)
+	b.WriteString(`<meta name="viewport" content="width=device-width,initial-scale=1.0">`)
+	b.WriteString(`<meta http-equiv="X-UA-Compatible" content="IE=edge">`)
+	b.WriteString(`<title>`)
+	b.WriteString(subject)
+	b.WriteString(`</title>`)
+	b.WriteString(`<style>`)
+	b.WriteString(`@media only screen and (max-width:620px){`)
+	b.WriteString(`.em-cell{padding-left:20px!important;padding-right:20px!important;}`)
+	b.WriteString(`.em-cta a{display:block!important;text-align:center!important;}`)
+	b.WriteString(`}`)
+	b.WriteString(`</style>`)
+	b.WriteString(`</head>`)
+
+	b.WriteString(`<body style="margin:0;padding:0;background-color:#ffffff;`)
+	b.WriteString(`-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;">`)
+
+	b.WriteString(`<div style="display:none;max-height:0;overflow:hidden;mso-hide:all;font-size:1px;color:#ffffff;">`)
+	b.WriteString(subject)
+	b.WriteString(strings.Repeat(" &zwnj;&nbsp;", 50))
+	b.WriteString(`</div>`)
+
+	b.WriteString(`<table role="presentation" width="100%" cellspacing="0" cellpadding="0" bgcolor="#ffffff">`)
+	b.WriteString(`<tr><td align="center" style="padding:0;">`)
+
+	b.WriteString(`<table role="presentation" cellspacing="0" cellpadding="0" style="width:100%;max-width:600px;">`)
+	b.WriteString(`<tr><td style="height:4px;background-color:#18181b;font-size:0;line-height:0;">&nbsp;</td></tr>`)
+	b.WriteString(`</table>`)
+
+	b.WriteString(`<table role="presentation" cellspacing="0" cellpadding="0" style="width:100%;max-width:600px;">`)
+
+	emailSpacer(&b, "44px")
+
+	b.WriteString(`<tr><td class="em-cell" align="left" style="padding:0 32px 36px;">`)
+	if logoContentID != "" {
+		b.WriteString(`<img src="cid:`)
+		b.WriteString(logoContentID)
+		b.WriteString(`" alt="`)
+		b.WriteString(companyName)
+		b.WriteString(`" height="36" style="display:block;height:36px;width:auto;max-width:200px;border:0;outline:none;text-decoration:none;">`)
+	} else {
+		b.WriteString(`<span style="font-size:16px;font-weight:700;color:#18181b;font-family:`)
+		b.WriteString(emailFontStack)
+		b.WriteString(`;letter-spacing:-0.3px;">`)
+		b.WriteString(companyName)
+		b.WriteString(`</span>`)
+	}
+	b.WriteString(`</td></tr>`)
+
+	emailDivider(&b)
+	emailSpacer(&b, "40px")
+
+	if greeting != "" {
+		b.WriteString(`<tr><td class="em-cell" style="padding:0 32px 6px;font-size:14px;line-height:1.6;color:#71717a;font-family:`)
+		b.WriteString(emailFontStack)
+		b.WriteString(`;">`)
+		b.WriteString(greeting)
+		b.WriteString(`</td></tr>`)
+	}
+
+	b.WriteString(`<tr><td class="em-cell" style="padding:0 32px 20px;font-size:26px;line-height:1.25;font-weight:700;`)
+	b.WriteString(`letter-spacing:-0.5px;color:#18181b;font-family:`)
+	b.WriteString(emailFontStack)
+	b.WriteString(`;">`)
+	b.WriteString(title)
+	b.WriteString(`</td></tr>`)
+
+	for i := range content.Message {
+		msg := html.EscapeString(strings.TrimSpace(content.Message[i]))
+		if msg == "" {
+			continue
+		}
+		b.WriteString(`<tr><td class="em-cell" style="padding:0 32px 12px;font-size:15px;line-height:1.75;color:#3f3f46;font-family:`)
+		b.WriteString(emailFontStack)
+		b.WriteString(`;">`)
+		b.WriteString(msg)
+		b.WriteString(`</td></tr>`)
+	}
+	if code != "" {
+		b.WriteString(`<tr><td class="em-cell" style="padding:4px 32px 16px;">`)
+		b.WriteString(`<span style="display:inline-block;background-color:#f4f4f5;border:1px solid #e4e4e7;`)
+		b.WriteString(`border-radius:10px;padding:12px 16px;font-size:28px;line-height:1;letter-spacing:6px;`)
+		b.WriteString(`color:#111827;font-weight:700;font-family:`)
+		b.WriteString(emailFontStack)
+		b.WriteString(`;">`)
+		b.WriteString(code)
+		b.WriteString(`</span></td></tr>`)
+	}
+
+	if ctaURL != "" && ctaLabel != "" {
+		emailSpacer(&b, "20px")
+
+		b.WriteString(`<tr><td class="em-cell em-cta" align="left" style="padding:0 32px 16px;">`)
+		b.WriteString(`<!--[if mso]>`)
+		b.WriteString(`<v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w="urn:schemas-microsoft-com:office:word"`)
+		b.WriteString(` href="`)
+		b.WriteString(ctaURL)
+		b.WriteString(`" style="height:44px;v-text-anchor:middle;width:180px;" arcsize="18%" stroke="f" fillcolor="#18181b">`)
+		b.WriteString(`<w:anchorlock/>`)
+		b.WriteString(`<center style="color:#ffffff;font-family:sans-serif;font-size:14px;font-weight:700;">`)
+		b.WriteString(ctaLabel)
+		b.WriteString(`</center></v:roundrect><![endif]-->`)
+		b.WriteString(`<!--[if !mso]><!-->`)
+		b.WriteString(`<a href="`)
+		b.WriteString(ctaURL)
+		b.WriteString(`" target="_blank" style="display:inline-block;background-color:#18181b;color:#ffffff;`)
+		b.WriteString(`font-family:`)
+		b.WriteString(emailFontStack)
+		b.WriteString(`;font-size:14px;font-weight:600;letter-spacing:0.1px;line-height:1;`)
+		b.WriteString(`text-decoration:none;padding:13px 26px;border-radius:8px;`)
+		b.WriteString(`-webkit-text-size-adjust:none;">`)
+		b.WriteString(ctaLabel)
+		b.WriteString(`</a>`)
+		b.WriteString(`<!--<![endif]-->`)
+		b.WriteString(`</td></tr>`)
+
+		b.WriteString(`<tr><td class="em-cell" style="padding:0 32px 4px;font-size:12px;line-height:1.6;color:#a1a1aa;font-family:`)
+		b.WriteString(emailFontStack)
+		b.WriteString(`;">Or copy and paste this link:</td></tr>`)
+		b.WriteString(`<tr><td class="em-cell" style="padding:0 32px 36px;font-size:12px;line-height:1.6;color:#71717a;`)
+		b.WriteString(`word-break:break-all;font-family:`)
+		b.WriteString(emailFontStack)
+		b.WriteString(`;">`)
+		b.WriteString(ctaURL)
+		b.WriteString(`</td></tr>`)
+	}
+
+	emailDivider(&b)
+	emailSpacer(&b, "24px")
+
+	if helpText != "" {
+		b.WriteString(`<tr><td class="em-cell" style="padding:0 32px 32px;font-size:13px;line-height:1.7;color:#71717a;font-family:`)
+		b.WriteString(emailFontStack)
+		b.WriteString(`;">`)
+		b.WriteString(helpText)
+		b.WriteString(`</td></tr>`)
+	}
+
+	b.WriteString(`<tr><td class="em-cell" style="padding:20px 32px 0;border-top:1px solid #e4e4e7;">`)
+	b.WriteString(`<span style="font-size:12px;line-height:1.7;color:#a1a1aa;font-family:`)
+	b.WriteString(emailFontStack)
+	b.WriteString(`;">`)
+	b.WriteString(companyName)
+	b.WriteString(`</span>`)
+	if footerText != "" {
+		b.WriteString(`<br><span style="font-size:12px;line-height:1.7;color:#a1a1aa;font-family:`)
+		b.WriteString(emailFontStack)
+		b.WriteString(`;">`)
+		b.WriteString(footerText)
+		b.WriteString(`</span>`)
+	}
+	b.WriteString(`</td></tr>`)
+
+	emailSpacer(&b, "48px")
+	b.WriteString(`</table>`)
+	b.WriteString(`</td></tr>`)
+	b.WriteString(`</table>`)
+	b.WriteString(`</body></html>`)
+	return b.String()
+}
+
+func formatEmailTTLMinutes(ttl time.Duration, fallback int) int {
+	minutes := int(ttl.Minutes())
+	if minutes < 1 {
+		return fallback
+	}
+	return minutes
+}
+
+func buildPasswordResetEmail(ctx context.Context, resolver AuthEmailBrandingResolver, userName string, link string, ttl time.Duration) BuiltAuthEmail {
+	minutes := formatEmailTTLMinutes(ttl, 20)
+	greeting := ""
+	if name := strings.TrimSpace(userName); name != "" {
+		greeting = "Hi " + name + ","
+	}
+	return buildAuthEmailTemplate(ctx, resolver, AuthEmailTemplateContent{
+		Subject:  "Reset your password",
+		Greeting: greeting,
+		Title:    "Reset your password",
+		Message: []string{
+			"We received a request to reset your password.",
+			"Click the button below to choose a new password. This link expires in " + strconv.Itoa(minutes) + " minutes and can only be used once.",
+		},
+		CTALabel:   "Reset Password",
+		CTAURL:     link,
+		HelpText:   "If you did not request this, you can safely ignore this email. Your password will remain unchanged.",
+		FooterText: "For your security, never share this link with anyone.",
+	})
+}
+
+func buildSecurityPINResetEmail(ctx context.Context, resolver AuthEmailBrandingResolver, userName string, link string, ttl time.Duration) BuiltAuthEmail {
+	minutes := formatEmailTTLMinutes(ttl, 20)
+	greeting := ""
+	if name := strings.TrimSpace(userName); name != "" {
+		greeting = "Hi " + name + ","
+	}
+	return buildAuthEmailTemplate(ctx, resolver, AuthEmailTemplateContent{
+		Subject:  "Reset your security PIN",
+		Greeting: greeting,
+		Title:    "Reset your security PIN",
+		Message: []string{
+			"We received a request to reset your security PIN.",
+			"Click the button below to set a new 6-digit PIN. This link expires in " + strconv.Itoa(minutes) + " minutes and can only be used once.",
+		},
+		CTALabel:   "Reset Security PIN",
+		CTAURL:     link,
+		HelpText:   "If you did not request this, you can safely ignore this email. Your PIN will remain unchanged.",
+		FooterText: "For your security, never share this link or your PIN with anyone.",
+	})
+}
+
+func buildLoginOTPEmail(ctx context.Context, resolver AuthEmailBrandingResolver, userName, otpCode string, ttl time.Duration) BuiltAuthEmail {
+	minutes := formatEmailTTLMinutes(ttl, 10)
+	greeting := ""
+	if name := strings.TrimSpace(userName); name != "" {
+		greeting = "Hi " + name + ","
+	}
+	return buildAuthEmailTemplate(ctx, resolver, AuthEmailTemplateContent{
+		Subject:  "Your login verification code",
+		Greeting: greeting,
+		Title:    "Verify your login",
+		Message: []string{
+			"Use this one-time code to complete your login:",
+			"This code expires in " + strconv.Itoa(minutes) + " minutes.",
+		},
+		Code:       strings.TrimSpace(otpCode),
+		HelpText:   "If this wasn't you, change your password immediately and contact support.",
+		FooterText: "For your security, never share this code with anyone.",
+	})
+}
diff --git a/internal/service/auth_service.go b/internal/service/auth_service.go
new file mode 100644
index 0000000..29690a5
--- /dev/null
+++ b/internal/service/auth_service.go
@@ -0,0 +1,3592 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"html"
+	"io"
+	"log"
+	"net"
+	"net/url"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+	"github.com/pquerna/otp"
+	"github.com/pquerna/otp/totp"
+	"golang.org/x/crypto/argon2"
+
+	"wucher/internal/config"
+	"wucher/internal/domain/auth"
+	"wucher/internal/queue"
+	"wucher/internal/shared/pkg/timezone"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+var (
+	ErrInvalidCredentials        = errors.New("invalid credentials")
+	ErrEmailNotVerified          = errors.New("email not verified")
+	ErrInvalidToken              = errors.New("invalid or expired token")
+	ErrInvalidSSOState           = errors.New("invalid or expired sso state")
+	ErrInvalidSSOReauth          = errors.New("invalid or expired sso reauth")
+	ErrSSONotLinked              = errors.New("sso not linked")
+	ErrSSOEmailNotFound          = errors.New("sso email not found")
+	ErrSSOAlreadyLinked          = errors.New("sso already linked")
+	ErrSSOLinkedToAnotherUser    = errors.New("sso linked to another user")
+	ErrUserNotFound              = errors.New("user not found")
+	ErrUnsupportedSSOProvider    = errors.New("unsupported sso provider")
+	ErrTOTPRequired              = errors.New("totp required")
+	ErrTOTPChallengeAttemptLimit = errors.New("totp challenge attempt limit reached")
+	ErrEmailOTPRequired          = errors.New("email otp required")
+	ErrInvalidEmailOTP           = errors.New("invalid email otp")
+	ErrEmailOTPRateLimited       = errors.New("email otp resend is rate limited")
+	ErrEmailOTPResendExceeded    = errors.New("email otp resend limit exceeded")
+	ErrInvalidResetLink          = errors.New("invalid or expired reset link")
+	ErrInvalidSecurityPIN        = errors.New("invalid security pin")
+	ErrSecurityPINAlreadySet     = errors.New("security pin is already set")
+	ErrSecurityPINNotSet         = errors.New("security pin is not set")
+	ErrSecurityPINLocked         = errors.New("security pin is blocked")
+	ErrSecurityPINNotBlocked     = errors.New("security pin is not blocked")
+	ErrSecurityPINResetRatelimit = errors.New("security pin reset request rate limited")
+	ErrSecurityPINResetRequired  = errors.New("security pin reset required")
+	ErrSecurityPINAttemptLimit   = errors.New("security pin attempt limit reached")
+	ErrInvalidPINResetPassword   = errors.New("invalid password for pin reset")
+	ErrInvalidPINAction          = errors.New("invalid or expired pin verification token")
+	ErrInvalidReauthMethod       = errors.New("invalid reauth method")
+	ErrSessionNotFound           = errors.New("session not found")
+	ErrMicrosoftReauthRequired   = errors.New("microsoft reauth required")
+)
+
+type TokenStore interface {
+	Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
+	SetIfNotExists(ctx context.Context, key string, value []byte, ttl time.Duration) (bool, error)
+	Get(ctx context.Context, key string) ([]byte, error)
+	Delete(ctx context.Context, key string) error
+}
+
+type SecretProtector interface {
+	Encrypt(plain []byte) ([]byte, error)
+	Decrypt(cipher []byte) ([]byte, error)
+}
+
+type MicrosoftSSO interface {
+	AuthCodeURL(state string) string
+	LogoutURL(postLogoutRedirectURL string) string
+	ExchangeCode(ctx context.Context, code string) (MicrosoftClaims, error)
+}
+
+type MicrosoftClaims struct {
+	Subject  string
+	Email    string
+	Name     string
+	TenantID string
+	ObjectID string
+	SessionID string
+}
+
+const totpChallengeMaxAttempts = 5
+
+type microsoftTokenExchanger interface {
+	ExchangeCodeAndTokens(ctx context.Context, code, codeVerifier string) (MicrosoftTokenSet, MicrosoftClaims, error)
+	RefreshAccessToken(ctx context.Context, refreshToken, codeVerifier string) (MicrosoftTokenSet, error)
+}
+
+type microsoftOAuthTokenStore interface {
+	UpsertMicrosoftOAuthToken(ctx context.Context, token *auth.UserMicrosoftOAuthToken) error
+	GetMicrosoftOAuthTokenByUserIDProvider(ctx context.Context, userID []byte, provider string) (*auth.UserMicrosoftOAuthToken, error)
+	DeleteMicrosoftOAuthTokenByUserIDProvider(ctx context.Context, userID []byte, provider string) (bool, error)
+}
+
+type microsoftStatePayload struct {
+	Flow         string `json:"flow"`
+	UserID       string `json:"user_id,omitempty"`
+	Purpose      string `json:"purpose,omitempty"`
+	CodeVerifier string `json:"code_verifier,omitempty"`
+}
+
+type AuthService struct {
+	repo            auth.Repository
+	roleRepo        auth.RoleRepository
+	tokens          TokenStore
+	emailQueue      EmailQueue
+	emailOutbox     auth.EmailOutboxWriter
+	emailSerializer queue.MessageSerializer
+	audit           *AuditLogService
+	sso             MicrosoftSSO
+	protector       SecretProtector
+	ipProtector     SecretProtector
+	emailBranding   AuthEmailBrandingResolver
+	emailOTPEnabled func(context.Context) (bool, error)
+	cfg             config.AuthConfig
+}
+
+type AuthServiceDependencies struct {
+	SSO             MicrosoftSSO
+	Protector       SecretProtector
+	Config          config.AuthConfig
+	Audit           *AuditLogService
+	EmailOutbox     auth.EmailOutboxWriter
+	EmailSerializer queue.MessageSerializer
+	EmailBranding   AuthEmailBrandingResolver
+	EmailOTPEnabled func(context.Context) (bool, error)
+	// Disable legacy behavior that swaps nil email queue with noop queue.
+	DisableLegacyNoopEmailQueue bool
+}
+
+func NewAuthService(
+	repo auth.Repository,
+	roleRepo auth.RoleRepository,
+	tokens TokenStore,
+	emailQueue EmailQueue,
+	deps AuthServiceDependencies,
+) *AuthService {
+	if emailQueue == nil && !deps.DisableLegacyNoopEmailQueue {
+		emailQueue = noopEmailQueue{}
+	}
+	cfg := normalizeAuthConfig(deps.Config)
+	return &AuthService{
+		repo:            repo,
+		roleRepo:        roleRepo,
+		tokens:          tokens,
+		emailQueue:      emailQueue,
+		emailOutbox:     deps.EmailOutbox,
+		emailSerializer: deps.EmailSerializer,
+		audit:           deps.Audit,
+		sso:             deps.SSO,
+		protector:       deps.Protector,
+		ipProtector:     newIPSecretProtector(cfg.IPEncryptionKey),
+		emailBranding:   deps.EmailBranding,
+		emailOTPEnabled: deps.EmailOTPEnabled,
+		cfg:             cfg,
+	}
+}
+
+type noopEmailQueue struct{}
+
+func (noopEmailQueue) Enqueue(context.Context, EmailJob) error {
+	return nil
+}
+
+func (s *AuthService) SetAuditLogger(audit *AuditLogService) {
+	s.audit = audit
+}
+
+func (s *AuthService) SetEmailOutbox(outbox auth.EmailOutboxWriter, serializer queue.MessageSerializer) {
+	s.emailOutbox = outbox
+	s.emailSerializer = serializer
+}
+
+func (s *AuthService) BeginMicrosoftLogin(ctx context.Context) (string, error) {
+	return s.beginMicrosoftLoginWithFlowAndPrompt(ctx, microsoftStateFlowLogin, "select_account")
+}
+
+func (s *AuthService) BeginMicrosoftSessionCheck(ctx context.Context) (string, error) {
+	return s.beginMicrosoftLoginWithFlowAndPrompt(ctx, microsoftStateFlowLoginCheck, "none")
+}
+
+func (s *AuthService) BeginMicrosoftSessionCheckStrict(ctx context.Context) (string, error) {
+	return s.beginMicrosoftLoginWithFlowAndPrompt(ctx, microsoftStateFlowLoginCheckStrict, "none")
+}
+
+func (s *AuthService) beginMicrosoftLoginWithFlowAndPrompt(ctx context.Context, flow, prompt string) (string, error) {
+	if s.sso == nil || s.tokens == nil {
+		return "", errors.New("sso not configured")
+	}
+	state, err := randomToken(32)
+	if err != nil {
+		return "", err
+	}
+	codeVerifier, err := randomToken(64)
+	if err != nil {
+		return "", err
+	}
+	payload, err := encodeMicrosoftStatePayload(microsoftStatePayload{Flow: flow, CodeVerifier: codeVerifier})
+	if err != nil {
+		return "", err
+	}
+	authURL := strings.TrimSpace(s.sso.AuthCodeURL(state))
+	if _, ok := s.sso.(microsoftTokenExchanger); ok {
+		authURL = withMicrosoftPKCE(authURL, codeVerifier)
+	}
+	authURL = withMicrosoftAuthPrompt(authURL, prompt)
+	if authURL == "" {
+		return "", errors.New("sso not configured")
+	}
+	if err := s.tokens.Set(ctx, ssoStateKey(state), payload, s.cfg.SSOStateTTL); err != nil {
+		return "", err
+	}
+	return authURL, nil
+}
+
+func (s *AuthService) BeginMicrosoftLink(ctx context.Context, userID []byte) (string, error) {
+	if s.sso == nil || s.tokens == nil {
+		return "", errors.New("sso not configured")
+	}
+	if len(userID) != 16 {
+		return "", ErrUserNotFound
+	}
+	userIDStr, err := uuidv7.BytesToString(userID)
+	if err != nil {
+		return "", ErrUserNotFound
+	}
+	state, err := randomToken(32)
+	if err != nil {
+		return "", err
+	}
+	codeVerifier, err := randomToken(64)
+	if err != nil {
+		return "", err
+	}
+	payload, err := encodeMicrosoftStatePayload(microsoftStatePayload{
+		Flow:         microsoftStateFlowLink,
+		UserID:       userIDStr,
+		CodeVerifier: codeVerifier,
+	})
+	if err != nil {
+		return "", err
+	}
+	authURL := strings.TrimSpace(s.sso.AuthCodeURL(state))
+	if _, ok := s.sso.(microsoftTokenExchanger); ok {
+		authURL = withMicrosoftPKCE(authURL, codeVerifier)
+	}
+	if authURL == "" {
+		return "", errors.New("sso not configured")
+	}
+	if err := s.tokens.Set(ctx, ssoStateKey(state), payload, s.cfg.SSOStateTTL); err != nil {
+		return "", err
+	}
+	return authURL, nil
+}
+
+func (s *AuthService) BeginMicrosoftReauth(ctx context.Context, userID []byte, purpose string) (string, error) {
+	if s.sso == nil || s.tokens == nil {
+		return "", errors.New("sso not configured")
+	}
+	if len(userID) != 16 || !isSupportedMicrosoftReauthPurpose(purpose) {
+		return "", ErrInvalidToken
+	}
+	userIDStr, err := uuidv7.BytesToString(userID)
+	if err != nil {
+		return "", ErrInvalidToken
+	}
+	state, err := randomToken(32)
+	if err != nil {
+		return "", err
+	}
+	codeVerifier, err := randomToken(64)
+	if err != nil {
+		return "", err
+	}
+	payload, err := encodeMicrosoftStatePayload(microsoftStatePayload{
+		Flow:         microsoftStateFlowReauth,
+		UserID:       userIDStr,
+		Purpose:      purpose,
+		CodeVerifier: codeVerifier,
+	})
+	if err != nil {
+		return "", err
+	}
+	authURL := strings.TrimSpace(s.sso.AuthCodeURL(state))
+	if _, ok := s.sso.(microsoftTokenExchanger); ok {
+		authURL = withMicrosoftPKCE(authURL, codeVerifier)
+	}
+	if authURL == "" {
+		return "", errors.New("sso not configured")
+	}
+	if err := s.tokens.Set(ctx, ssoStateKey(state), payload, s.cfg.SSOStateTTL); err != nil {
+		return "", err
+	}
+	return authURL, nil
+}
+
+func (s *AuthService) BeginMicrosoftPINResetReauth(ctx context.Context, rawResetToken string) (string, error) {
+	rawResetToken = strings.TrimSpace(rawResetToken)
+	if rawResetToken == "" {
+		return "", ErrInvalidResetLink
+	}
+	now := time.Now().UTC()
+	user, err := s.repo.GetActiveSecurityPINResetTokenUser(ctx, hashToken(rawResetToken), now)
+	if err != nil {
+		return "", err
+	}
+	if user == nil || len(user.ID) != 16 {
+		return "", ErrInvalidResetLink
+	}
+	return s.BeginMicrosoftReauth(ctx, user.ID, microsoftReauthPurposePINResetConfirm)
+}
+
+func (s *AuthService) MicrosoftStateMode(ctx context.Context, state string) (string, error) {
+	payload, err := s.loadMicrosoftStatePayload(ctx, state)
+	if err != nil {
+		return "", err
+	}
+	return payload.Flow, nil
+}
+
+func (s *AuthService) CompleteMicrosoftLogin(ctx context.Context, code, state string) (*auth.UserIdentity, string, error) {
+	if s.sso == nil || s.tokens == nil {
+		return nil, "", errors.New("sso not configured")
+	}
+	payload, err := s.loadMicrosoftStatePayload(ctx, state)
+	if err != nil {
+		return nil, "", err
+	}
+	if payload.Flow != microsoftStateFlowLogin && payload.Flow != microsoftStateFlowLoginCheck && payload.Flow != microsoftStateFlowLoginCheckStrict {
+		return nil, "", ErrInvalidSSOState
+	}
+	// Consume SSO state exactly once to avoid replay with the same OAuth code.
+	defer func() {
+		_ = s.tokens.Delete(ctx, ssoStateKey(state))
+	}()
+	identity, microsoftSessionID, err := s.LoginWithMicrosoft(ctx, code, payload.CodeVerifier)
+	if err != nil {
+		return nil, "", err
+	}
+	return identity, microsoftSessionID, nil
+}
+
+func (s *AuthService) ClearMicrosoftState(ctx context.Context, state string) {
+	if s == nil || s.tokens == nil {
+		return
+	}
+	state = strings.TrimSpace(state)
+	if state == "" {
+		return
+	}
+	_ = s.tokens.Delete(ctx, ssoStateKey(state))
+}
+
+func (s *AuthService) CompleteMicrosoftReauth(ctx context.Context, code, state string) (string, string, error) {
+	if s.sso == nil || s.tokens == nil {
+		return "", "", errors.New("sso not configured")
+	}
+	payload, err := s.loadMicrosoftStatePayload(ctx, state)
+	if err != nil {
+		return "", "", err
+	}
+	if payload.Flow != microsoftStateFlowReauth || payload.UserID == "" || !isSupportedMicrosoftReauthPurpose(payload.Purpose) {
+		return "", "", ErrInvalidSSOState
+	}
+	// Consume SSO state exactly once to avoid replay with the same OAuth code.
+	defer func() {
+		_ = s.tokens.Delete(ctx, ssoStateKey(state))
+	}()
+
+	claims, _, err := s.exchangeMicrosoftCode(ctx, code, payload.CodeVerifier)
+	if err != nil {
+		return "", "", err
+	}
+	identity, err := s.repo.GetIdentityByProviderSubject(ctx, "microsoft", claims.Subject)
+	if err != nil {
+		return "", "", err
+	}
+	if identity == nil || len(identity.UserID) != 16 || bytesToString(identity.UserID) != payload.UserID {
+		return "", "", ErrInvalidSSOReauth
+	}
+
+	token, err := randomToken(32)
+	if err != nil {
+		return "", "", err
+	}
+	if err := s.tokens.Set(ctx, microsoftReauthKey(token), []byte(payload.UserID+"|"+payload.Purpose), s.microsoftReauthTTL()); err != nil {
+		return "", "", err
+	}
+	return token, payload.Purpose, nil
+}
+
+func (s *AuthService) CompleteMicrosoftLink(ctx context.Context, code, state string) (*auth.UserIdentity, error) {
+	if s.sso == nil || s.tokens == nil {
+		return nil, errors.New("sso not configured")
+	}
+	payload, err := s.loadMicrosoftStatePayload(ctx, state)
+	if err != nil {
+		return nil, err
+	}
+	if payload.Flow != microsoftStateFlowLink || payload.UserID == "" {
+		return nil, ErrInvalidSSOState
+	}
+	parsedUserID, err := uuidv7.ParseString(payload.UserID)
+	if err != nil || len(parsedUserID) != 16 {
+		return nil, ErrInvalidSSOState
+	}
+	// Consume SSO state exactly once to avoid replay with the same OAuth code.
+	defer func() {
+		_ = s.tokens.Delete(ctx, ssoStateKey(state))
+	}()
+	return s.LinkSSOForUser(ctx, parsedUserID, ssoProviderMicrosoft, code, payload.CodeVerifier)
+}
+
+// RegisterWithEmail creates a user and records verification email intent in outbox.
+func (s *AuthService) RegisterWithEmail(ctx context.Context, email, username, firstName, lastName, mobilePhone, password string, roleID []byte) (*auth.User, error) {
+	email = strings.ToLower(strings.TrimSpace(email))
+	username, err := normalizeUsername(username)
+	if err != nil {
+		return nil, err
+	}
+	if email == "" || password == "" {
+		return nil, errors.New("email, username, and password are required")
+	}
+	existingByUsername, err := s.repo.GetUserByUsername(ctx, username)
+	if err != nil {
+		return nil, err
+	}
+	if existingByUsername != nil {
+		return nil, errors.New("username already registered")
+	}
+
+	hash, salt, err := s.hashPassword(password)
+	if err != nil {
+		return nil, err
+	}
+
+	user := &auth.User{
+		ID:           uuidv7.MustBytes(),
+		Email:        email,
+		Username:     ptrString(username),
+		FirstName:    firstName,
+		LastName:     lastName,
+		MobilePhone:  mobilePhone,
+		Timezone:     timezone.Default,
+		RoleID:       roleID,
+		RoleIDs:      normalizeAuthServiceRoleIDs(roleID, nil),
+		IsActive:     true,
+		PasswordHash: hash,
+		SaltValue:    salt,
+	}
+
+	job, err := s.buildEmailVerificationJob(ctx, user)
+	if err != nil {
+		return nil, err
+	}
+	if job.Metadata == nil {
+		job.Metadata = map[string]string{}
+	}
+	// Keep outbox record for auditing/workflow, but suppress actual delivery.
+	job.Metadata["skip_send"] = "true"
+	if job.Tags == nil {
+		job.Tags = map[string]string{}
+	}
+	job.Tags["source"] = "register"
+
+	if err := s.createUserAndDispatchEmail(ctx, user, job); err != nil {
+		return nil, err
+	}
+
+	return user, nil
+}
+
+// InviteUser creates a user without password and sends set-password link.
+func (s *AuthService) InviteUser(ctx context.Context, email, username, firstName, lastName, mobilePhone string, roleID []byte) (*auth.User, error) {
+	return s.InviteUserWithRoles(ctx, email, username, firstName, lastName, mobilePhone, roleID, nil)
+}
+
+func (s *AuthService) InviteUserWithRoles(
+	ctx context.Context,
+	email, username, firstName, lastName, mobilePhone string,
+	roleID []byte,
+	roleIDs [][]byte,
+) (*auth.User, error) {
+	email = strings.ToLower(strings.TrimSpace(email))
+	username, err := normalizeUsername(username)
+	if err != nil {
+		return nil, err
+	}
+	if email == "" {
+		return nil, errors.New("email and username are required")
+	}
+	existing, err := s.repo.GetUserByEmail(ctx, email)
+	if err != nil {
+		return nil, err
+	}
+	if existing != nil {
+		return nil, errors.New("email already registered")
+	}
+	existingByUsername, err := s.repo.GetUserByUsername(ctx, username)
+	if err != nil {
+		return nil, err
+	}
+	if existingByUsername != nil {
+		return nil, errors.New("username already registered")
+	}
+
+	user := &auth.User{
+		ID:          uuidv7.MustBytes(),
+		Email:       email,
+		Username:    ptrString(username),
+		FirstName:   firstName,
+		LastName:    lastName,
+		MobilePhone: mobilePhone,
+		Timezone:    timezone.Default,
+		RoleID:      roleID,
+		RoleIDs:     normalizeAuthServiceRoleIDs(roleID, roleIDs),
+		IsActive:    true,
+	}
+	job, err := s.buildInviteSetPasswordJob(ctx, user)
+	if err != nil {
+		return nil, err
+	}
+	if err := s.createUserAndDispatchEmail(ctx, user, job); err != nil {
+		return nil, err
+	}
+	return user, nil
+}
+
+// SendInviteSetPasswordForUser sends invite set-password email for an existing user.
+func (s *AuthService) SendInviteSetPasswordForUser(ctx context.Context, userID []byte) error {
+	if s.tokens == nil || strings.TrimSpace(s.cfg.SetPasswordURL) == "" {
+		return errors.New("invite set-password is not configured")
+	}
+	if len(userID) != 16 {
+		return errors.New("invalid user id")
+	}
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return err
+	}
+	if user == nil {
+		return errors.New("user not found")
+	}
+	if strings.TrimSpace(user.Email) == "" {
+		return errors.New("user email is empty")
+	}
+	return s.sendInviteSetPassword(ctx, user)
+}
+
+// ResendInviteSetPassword triggers invite set-password email for invited users.
+// This method intentionally keeps behavior generic and returns no error.
+func (s *AuthService) ResendInviteSetPassword(ctx context.Context, userID []byte) {
+	start := time.Now()
+	defer sleepRemaining(start, s.cfg.ForgotPasswordMinDuration)
+
+	if s.tokens == nil || strings.TrimSpace(s.cfg.SetPasswordURL) == "" || len(userID) != 16 {
+		return
+	}
+
+	cooldownKey := inviteSetPasswordResendCooldownKey(userID)
+	if s.isInviteSetPasswordResendCooldownActive(ctx, cooldownKey) {
+		return
+	}
+
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil || user == nil {
+		return
+	}
+	if !user.IsActive || strings.TrimSpace(user.Email) == "" {
+		return
+	}
+	// Only resend for users that still have no password set.
+	if len(user.PasswordHash) > 0 {
+		return
+	}
+
+	if err := s.sendInviteSetPassword(ctx, user); err != nil {
+		return
+	}
+	_ = s.markInviteSetPasswordResendCooldown(ctx, cooldownKey)
+}
+
+// ForgotPassword always returns without exposing whether an account exists.
+func (s *AuthService) ForgotPassword(ctx context.Context, email, requestedIP, userAgent string) {
+	start := time.Now()
+	defer sleepRemaining(start, s.cfg.ForgotPasswordMinDuration)
+
+	email = strings.ToLower(strings.TrimSpace(email))
+	if email == "" {
+		s.logServiceAudit(ctx, "auth.forgot_password.request", nil, false, "empty_email", map[string]any{
+			"email_sha256": shortEmailHash(email),
+		})
+		return
+	}
+
+	cooldownKey := forgotPasswordCooldownKey(email)
+	if s.isForgotPasswordCooldownActive(ctx, cooldownKey, email, requestedIP) {
+		s.logServiceAudit(ctx, "auth.forgot_password.cooldown", nil, true, "cooldown_active", map[string]any{
+			"email_sha256": shortEmailHash(email),
+		})
+		return
+	}
+
+	user, err := s.repo.GetUserByEmail(ctx, email)
+	if err != nil {
+		s.auditForgotPasswordAnomaly(email, requestedIP, "lookup_failed")
+		_ = s.markForgotPasswordCooldown(ctx, cooldownKey)
+		s.logServiceAudit(ctx, "auth.forgot_password.lookup", nil, false, "lookup_failed", map[string]any{
+			"email_sha256": shortEmailHash(email),
+		})
+		return
+	}
+
+	if user != nil {
+		if err := s.createAndSendPasswordReset(ctx, user, requestedIP, userAgent); err != nil {
+			s.auditForgotPasswordAnomaly(email, requestedIP, "issue_failed")
+			s.logServiceAudit(ctx, "auth.forgot_password.issue", user.ID, false, "issue_failed", map[string]any{
+				"email_sha256": shortEmailHash(email),
+			})
+		} else {
+			s.logServiceAudit(ctx, "auth.forgot_password.issue", user.ID, true, "enqueued", map[string]any{
+				"email_sha256": shortEmailHash(email),
+			})
+		}
+	} else {
+		s.logServiceAudit(ctx, "auth.forgot_password.request", nil, true, "account_not_found_hidden", map[string]any{
+			"email_sha256": shortEmailHash(email),
+		})
+	}
+
+	_ = s.markForgotPasswordCooldown(ctx, cooldownKey)
+}
+
+func (s *AuthService) ResetPassword(ctx context.Context, rawToken, newPassword string) error {
+	rawToken = strings.TrimSpace(rawToken)
+	if rawToken == "" || newPassword == "" {
+		s.logServiceAudit(ctx, "auth.reset_password.consume", nil, false, "missing_token_or_password", nil)
+		return ErrInvalidResetLink
+	}
+
+	passwordHash, salt, err := s.hashPassword(newPassword)
+	if err != nil {
+		return err
+	}
+
+	userID, consumed, err := s.repo.ConsumePasswordResetTokenAndSetPassword(ctx, hashToken(rawToken), passwordHash, salt, time.Now().UTC())
+	if err != nil {
+		s.logServiceAudit(ctx, "auth.reset_password.consume", nil, false, "consume_failed", nil)
+		return err
+	}
+	if !consumed || len(userID) != 16 {
+		s.logServiceAudit(ctx, "auth.reset_password.consume", nil, false, "invalid_or_expired", nil)
+		return ErrInvalidResetLink
+	}
+
+	if err := s.bumpSessionVersion(ctx, userID); err != nil {
+		log.Printf("auth reset-password session_revocation_failed user=%s", shortIdentifier(userID))
+		s.logServiceAudit(ctx, "auth.reset_password.revoke_sessions", userID, false, "session_revocation_failed", nil)
+	} else {
+		s.logServiceAudit(ctx, "auth.reset_password.revoke_sessions", userID, true, "session_revoked", nil)
+	}
+	s.logServiceAudit(ctx, "auth.reset_password.consume", userID, true, "password_reset_success", nil)
+	return nil
+}
+
+func (s *AuthService) GetRoleIDByName(ctx context.Context, name string) ([]byte, error) {
+	if s.roleRepo == nil {
+		return nil, errors.New("role repo not configured")
+	}
+	role, err := s.roleRepo.GetRoleByName(ctx, name)
+	if err != nil || role == nil {
+		return nil, errors.New("role not found")
+	}
+	return role.ID, nil
+}
+
+func (s *AuthService) DefaultRoleName() string { return s.cfg.DefaultRoleName }
+func (s *AuthService) RegisterDisabled() bool  { return s.cfg.DisableRegister }
+
+// LoginWithEmailPassword verifies email/password and returns the user.
+func (s *AuthService) LoginWithEmailPassword(ctx context.Context, email, password string) (*auth.User, error) {
+	email = strings.ToLower(strings.TrimSpace(email))
+	user, err := s.repo.GetUserByEmail(ctx, email)
+	if err != nil || user == nil {
+		return nil, ErrInvalidCredentials
+	}
+
+	if !s.verifyPassword(password, user.PasswordHash, user.SaltValue) {
+		return nil, ErrInvalidCredentials
+	}
+	if !user.IsActive {
+		return nil, ErrInvalidCredentials
+	}
+
+	if user.EmailVerifiedAt == nil {
+		return nil, ErrEmailNotVerified
+	}
+
+	return user, nil
+}
+
+func (s *AuthService) IsTOTPEnabled(ctx context.Context, userID []byte) (bool, error) {
+	record, err := s.repo.GetUserTOTP(ctx, userID)
+	if err != nil || record == nil {
+		return false, err
+	}
+	return record.Enabled, nil
+}
+
+func (s *AuthService) IsTOTPPreviouslyConfigured(ctx context.Context, userID []byte) (bool, error) {
+	record, err := s.repo.GetUserTOTP(ctx, userID)
+	if err != nil || record == nil {
+		return false, err
+	}
+	return !record.Enabled, nil
+}
+
+type TokenPair struct {
+	AccessToken  string
+	RefreshToken string
+	RefreshTTL   time.Duration
+	SessionID    string
+}
+
+func (s *AuthService) IssueTokens(ctx context.Context, user *auth.User) (TokenPair, error) {
+	return s.IssueTokensWithClient(ctx, user, "", "")
+}
+
+func (s *AuthService) IssueTokensAfterTOTP(ctx context.Context, user *auth.User) (TokenPair, error) {
+	return s.IssueTokensAfterTOTPWithClient(ctx, user, "", "")
+}
+
+func (s *AuthService) issueLoginTokensWithRefreshTTL(ctx context.Context, user *auth.User, refreshTTL time.Duration, longLived bool) (TokenPair, error) {
+	if user == nil || len(user.ID) != 16 {
+		return TokenPair{}, ErrInvalidToken
+	}
+	return s.issueTokensWithRefreshTTL(ctx, user, refreshTTL, longLived)
+}
+
+func (s *AuthService) issueTokensWithRefreshTTL(ctx context.Context, user *auth.User, refreshTTL time.Duration, longLived bool) (TokenPair, error) {
+	return s.issueTokensWithRefreshTTLAndClient(ctx, user, refreshTTL, longLived, "", "", "", "", "", "")
+}
+
+func (s *AuthService) RefreshTokens(ctx context.Context, refreshToken string) (TokenPair, error) {
+	return s.RefreshTokensWithClient(ctx, refreshToken, "", "")
+}
+
+func (s *AuthService) RevokeRefreshToken(ctx context.Context, refreshToken string) error {
+	return s.revokeRefreshTokenWithSession(ctx, refreshToken)
+}
+
+func (s *AuthService) ParseAccessToken(ctx context.Context, accessToken string) ([]byte, error) {
+	userID, _, err := s.parseAccessTokenWithSession(ctx, accessToken)
+	if err != nil {
+		return nil, err
+	}
+	return userID, nil
+}
+
+func (s *AuthService) parseAccessTokenWithSession(ctx context.Context, accessToken string) ([]byte, string, error) {
+	if s.cfg.JWTAccessSecret == "" || s.cfg.JWTRefreshSecret == "" {
+		return nil, "", errors.New("jwt secrets not configured")
+	}
+	if accessToken == "" {
+		return nil, "", ErrInvalidToken
+	}
+
+	parsed, err := jwt.Parse(accessToken, func(t *jwt.Token) (any, error) {
+		if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, ErrInvalidToken
+		}
+		return []byte(s.cfg.JWTAccessSecret), nil
+	})
+	if err != nil || !parsed.Valid {
+		return nil, "", ErrInvalidToken
+	}
+
+	claims, ok := parsed.Claims.(jwt.MapClaims)
+	if !ok {
+		return nil, "", ErrInvalidToken
+	}
+	if claims["type"] != "access" {
+		return nil, "", ErrInvalidToken
+	}
+	sub, _ := claims["sub"].(string)
+	sid, _ := claims["sid"].(string)
+	if sub == "" || sid == "" {
+		return nil, "", ErrInvalidToken
+	}
+	userID, err := uuidv7.ParseString(sub)
+	if err != nil {
+		return nil, "", ErrInvalidToken
+	}
+	if !s.validSessionVersion(ctx, userID, claims["sv"]) {
+		return nil, "", ErrInvalidToken
+	}
+	if !s.isSessionActive(ctx, userID, sid) {
+		return nil, "", ErrInvalidToken
+	}
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil || user == nil || !user.IsActive {
+		return nil, "", ErrInvalidToken
+	}
+	record, err := s.loadSessionRecord(ctx, sid)
+	if err != nil || record == nil {
+		return nil, "", ErrInvalidToken
+	}
+	if s.isSessionIdleExpired(record) {
+		// Local/email sessions expire at idle boundary.
+		if !s.canRecoverSSOSessionOnIdle(ctx, userID, record) {
+			_ = s.RevokeUserSession(ctx, userID, sid)
+			return nil, "", ErrInvalidToken
+		}
+	}
+	s.touchSessionActivity(ctx, userID, sid)
+	return userID, sid, nil
+}
+
+func (s *AuthService) GetUserByID(ctx context.Context, id []byte) (*auth.User, error) {
+	return s.repo.GetUserByID(ctx, id)
+}
+
+func (s *AuthService) IsSSOLinked(ctx context.Context, userID []byte) (bool, error) {
+	if len(userID) != 16 {
+		return false, nil
+	}
+	identity, err := s.repo.GetIdentityByUserID(ctx, userID)
+	if err != nil {
+		return false, err
+	}
+	return identity != nil, nil
+}
+
+func (s *AuthService) GetMicrosoftScopeByUserID(ctx context.Context, userID []byte) (string, error) {
+	if len(userID) != 16 {
+		return "", nil
+	}
+	repo, ok := s.repo.(microsoftOAuthTokenStore)
+	if !ok {
+		return "", nil
+	}
+	record, err := repo.GetMicrosoftOAuthTokenByUserIDProvider(ctx, userID, ssoProviderMicrosoft)
+	if err != nil {
+		return "", err
+	}
+	if record == nil {
+		return "", nil
+	}
+	return normalizeMicrosoftScopeCSV(record.Scope), nil
+}
+
+func normalizeMicrosoftScopeCSV(scope string) string {
+	parts := strings.Fields(strings.TrimSpace(scope))
+	if len(parts) == 0 {
+		return ""
+	}
+	return strings.Join(parts, ", ")
+}
+
+func (s *AuthService) UpdateUserTimezone(ctx context.Context, userID []byte, timezoneName string) (string, error) {
+	if len(userID) == 0 {
+		return "", errors.New("user_id is required")
+	}
+	normalized, err := timezone.Normalize(timezoneName)
+	if err != nil {
+		return "", err
+	}
+	if err := s.repo.UpdateUserTimezone(ctx, userID, normalized); err != nil {
+		return "", err
+	}
+	return normalized, nil
+}
+
+func (s *AuthService) SetSecurityPIN(ctx context.Context, userID []byte, pin string) error {
+	if len(userID) != 16 {
+		return ErrInvalidSecurityPIN
+	}
+	pin = strings.TrimSpace(pin)
+	if err := validateSecurityPIN(pin); err != nil {
+		return err
+	}
+
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return err
+	}
+	if user == nil {
+		return ErrInvalidToken
+	}
+	if len(user.SecurityPINHash) > 0 {
+		return ErrSecurityPINAlreadySet
+	}
+
+	pinRecord, err := s.hashSecurityPIN(pin)
+	if err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	if err := s.repo.SetUserSecurityPIN(ctx, userID, pinRecord, now); err != nil {
+		return err
+	}
+	_ = s.clearSecurityPINLockState(ctx, userID)
+	s.logServiceAudit(ctx, "auth.pin.set", userID, true, "pin_set", nil)
+	return nil
+}
+
+func (s *AuthService) ChangeSecurityPIN(ctx context.Context, userID []byte, currentPIN, newPIN string) error {
+	if len(userID) != 16 {
+		return ErrInvalidSecurityPIN
+	}
+	currentPIN = strings.TrimSpace(currentPIN)
+	newPIN = strings.TrimSpace(newPIN)
+
+	if err := validateSecurityPIN(currentPIN); err != nil {
+		return err
+	}
+	if err := validateSecurityPIN(newPIN); err != nil {
+		return err
+	}
+
+	if err := s.verifySecurityPIN(ctx, userID, currentPIN); err != nil {
+		return err
+	}
+
+	pinRecord, err := s.hashSecurityPIN(newPIN)
+	if err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	if err := s.repo.SetUserSecurityPIN(ctx, userID, pinRecord, now); err != nil {
+		return err
+	}
+	_ = s.clearSecurityPINLockState(ctx, userID)
+	s.logServiceAudit(ctx, "auth.pin.change", userID, true, "pin_changed", nil)
+	return nil
+}
+
+func (s *AuthService) VerifySecurityPINForAction(ctx context.Context, userID []byte, pin, action string) (string, error) {
+	return s.verifySecurityPINForAction(ctx, userID, pin, action, "")
+}
+
+func (s *AuthService) VerifySecurityPINForActionInSession(ctx context.Context, userID []byte, pin, action, sessionID string) (string, error) {
+	return s.verifySecurityPINForAction(ctx, userID, pin, action, sessionID)
+}
+
+func (s *AuthService) verifySecurityPINForAction(ctx context.Context, userID []byte, pin, action, sessionID string) (string, error) {
+	if len(userID) != 16 {
+		return "", ErrInvalidSecurityPIN
+	}
+	if err := s.verifySecurityPIN(ctx, userID, strings.TrimSpace(pin)); err != nil {
+		return "", err
+	}
+
+	action = normalizeSensitiveAction(action)
+	if action == "" {
+		return "", errors.New("action is required")
+	}
+	if s.tokens == nil {
+		return "", errors.New("token store not configured")
+	}
+
+	token, err := randomToken(24)
+	if err != nil {
+		return "", err
+	}
+
+	payload := bytesToString(userID) + "|" + action
+	if strings.TrimSpace(sessionID) != "" {
+		payload += "|" + strings.TrimSpace(sessionID)
+	}
+	if err := s.tokens.Set(ctx, pinActionKey(token), []byte(payload), s.cfg.SecurityPINActionTokenTTL); err != nil {
+		return "", err
+	}
+	s.logServiceAudit(ctx, "auth.pin.verify", userID, true, "pin_verified", map[string]any{
+		"action": action,
+	})
+	return token, nil
+}
+
+func (s *AuthService) ConsumeSecurityPINActionToken(ctx context.Context, userID []byte, action, token string) error {
+	return s.validateSecurityPINActionToken(ctx, userID, action, token, "", true)
+}
+
+func (s *AuthService) ValidateSecurityPINActionToken(ctx context.Context, userID []byte, action, token string) error {
+	return s.validateSecurityPINActionToken(ctx, userID, action, token, "", false)
+}
+
+func (s *AuthService) ConsumeSecurityPINActionTokenInSession(ctx context.Context, userID []byte, action, token, sessionID string) error {
+	return s.validateSecurityPINActionToken(ctx, userID, action, token, sessionID, true)
+}
+
+func (s *AuthService) ValidateSecurityPINActionTokenInSession(ctx context.Context, userID []byte, action, token, sessionID string) error {
+	return s.validateSecurityPINActionToken(ctx, userID, action, token, sessionID, false)
+}
+
+func (s *AuthService) validateSecurityPINActionToken(ctx context.Context, userID []byte, action, token, sessionID string, consume bool) error {
+	if len(userID) != 16 {
+		return ErrInvalidPINAction
+	}
+	action = normalizeSensitiveAction(action)
+	token = strings.TrimSpace(token)
+	if action == "" || token == "" || s.tokens == nil {
+		return ErrInvalidPINAction
+	}
+
+	raw, err := s.tokens.Get(ctx, pinActionKey(token))
+	if err != nil || raw == nil {
+		return ErrInvalidPINAction
+	}
+
+	parts := strings.Split(string(raw), "|")
+	if len(parts) != 2 && len(parts) != 3 {
+		return ErrInvalidPINAction
+	}
+	if !subtleConstantTimeCompare([]byte(parts[0]), []byte(bytesToString(userID))) {
+		return ErrInvalidPINAction
+	}
+	if !subtleConstantTimeCompare([]byte(parts[1]), []byte(action)) {
+		return ErrInvalidPINAction
+	}
+	if len(parts) == 3 {
+		if !subtleConstantTimeCompare([]byte(parts[2]), []byte(strings.TrimSpace(sessionID))) {
+			return ErrInvalidPINAction
+		}
+	}
+	if consume {
+		_ = s.tokens.Delete(ctx, pinActionKey(token))
+	}
+	return nil
+}
+
+// ForgotSecurityPIN always returns without exposing whether an account exists.
+func (s *AuthService) ForgotSecurityPIN(ctx context.Context, email, requestedIP, userAgent string) {
+	start := time.Now()
+	defer sleepRemaining(start, s.cfg.ForgotSecurityPINMinDuration)
+
+	email = strings.ToLower(strings.TrimSpace(email))
+	if email == "" {
+		s.logServiceAudit(ctx, "auth.pin.forgot.request", nil, false, "empty_email", map[string]any{
+			"email_sha256": shortEmailHash(email),
+		})
+		return
+	}
+
+	cooldownKey := forgotSecurityPINCooldownKey(email)
+	if s.isForgotSecurityPINCooldownActive(ctx, cooldownKey) {
+		s.logServiceAudit(ctx, "auth.pin.forgot.cooldown", nil, true, "cooldown_active", map[string]any{
+			"email_sha256": shortEmailHash(email),
+		})
+		return
+	}
+
+	user, err := s.repo.GetUserByEmail(ctx, email)
+	if err != nil {
+		_ = s.markForgotSecurityPINCooldown(ctx, cooldownKey)
+		s.logServiceAudit(ctx, "auth.pin.forgot.lookup", nil, false, "lookup_failed", map[string]any{
+			"email_sha256": shortEmailHash(email),
+		})
+		return
+	}
+
+	if user != nil {
+		if err := s.createAndSendSecurityPINReset(ctx, user, requestedIP, userAgent); err != nil {
+			s.logServiceAudit(ctx, "auth.pin.forgot.issue", user.ID, false, "issue_failed", map[string]any{
+				"email_sha256": shortEmailHash(email),
+			})
+		} else {
+			s.logServiceAudit(ctx, "auth.pin.forgot.issue", user.ID, true, "enqueued", map[string]any{
+				"email_sha256": shortEmailHash(email),
+			})
+		}
+	} else {
+		s.logServiceAudit(ctx, "auth.pin.forgot.request", nil, true, "account_not_found_hidden", map[string]any{
+			"email_sha256": shortEmailHash(email),
+		})
+	}
+
+	_ = s.markForgotSecurityPINCooldown(ctx, cooldownKey)
+}
+
+func (s *AuthService) RequestSecurityPINReset(ctx context.Context, userID []byte, method, password, reauthToken, requestedIP, userAgent string) error {
+	if len(userID) != 16 {
+		return ErrInvalidToken
+	}
+	method = normalizePINResetMethod(method)
+	if !s.isSecurityPINLocked(ctx, userID) {
+		return ErrSecurityPINNotBlocked
+	}
+
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return err
+	}
+	if user == nil {
+		return ErrInvalidToken
+	}
+	switch method {
+	case pinResetMethodPassword:
+		password = strings.TrimSpace(password)
+		if password == "" {
+			return ErrInvalidPINResetPassword
+		}
+		if !s.verifyPassword(password, user.PasswordHash, user.SaltValue) {
+			s.logServiceAudit(ctx, "auth.pin.reset.issue", userID, false, "invalid_password", map[string]any{
+				"trigger": "blocked_reset_button",
+			})
+			return ErrInvalidPINResetPassword
+		}
+	case pinResetMethodMicrosoft:
+		if err := s.consumeMicrosoftReauthToken(ctx, userID, microsoftReauthPurposePINResetRequest, reauthToken); err != nil {
+			s.logServiceAudit(ctx, "auth.pin.reset.issue", userID, false, "invalid_sso_reauth", map[string]any{
+				"trigger": "blocked_reset_button",
+			})
+			return err
+		}
+	default:
+		return ErrInvalidReauthMethod
+	}
+
+	cooldownKey := forgotSecurityPINCooldownKey(user.Email)
+	if s.isForgotSecurityPINCooldownActive(ctx, cooldownKey) {
+		return ErrSecurityPINResetRatelimit
+	}
+	if err := s.createAndSendSecurityPINReset(ctx, user, requestedIP, userAgent); err != nil {
+		return err
+	}
+	_ = s.markForgotSecurityPINCooldown(ctx, cooldownKey)
+	s.logServiceAudit(ctx, "auth.pin.reset.issue", userID, true, "requested_by_user", map[string]any{
+		"trigger": "blocked_reset_button",
+	})
+	return nil
+}
+
+func (s *AuthService) ResetSecurityPIN(ctx context.Context, rawToken, method, password, reauthToken, newPIN string) error {
+	method = normalizePINResetMethod(method)
+	rawToken = strings.TrimSpace(rawToken)
+	password = strings.TrimSpace(password)
+	newPIN = strings.TrimSpace(newPIN)
+	if err := validateSecurityPIN(newPIN); err != nil {
+		return err
+	}
+
+	now := time.Now().UTC()
+	switch method {
+	case pinResetMethodPassword:
+		if rawToken == "" {
+			return ErrInvalidResetLink
+		}
+		tokenHash := hashToken(rawToken)
+		user, err := s.repo.GetActiveSecurityPINResetTokenUser(ctx, tokenHash, now)
+		if err != nil {
+			s.logServiceAudit(ctx, "auth.pin.reset.lookup", nil, false, "lookup_failed", nil)
+			return err
+		}
+		if user == nil || len(user.ID) != 16 {
+			s.logServiceAudit(ctx, "auth.pin.reset.lookup", nil, false, "invalid_or_expired", nil)
+			return ErrInvalidResetLink
+		}
+		if password == "" {
+			return ErrInvalidPINResetPassword
+		}
+		if !s.verifyPassword(password, user.PasswordHash, user.SaltValue) {
+			s.logServiceAudit(ctx, "auth.pin.reset.password", user.ID, false, "invalid_password", nil)
+			return ErrInvalidPINResetPassword
+		}
+		pinRecord, err := s.hashSecurityPIN(newPIN)
+		if err != nil {
+			return err
+		}
+
+		userID, consumed, err := s.repo.ConsumeSecurityPINResetTokenAndSetPIN(ctx, tokenHash, pinRecord, now)
+		if err != nil {
+			s.logServiceAudit(ctx, "auth.pin.reset.consume", nil, false, "consume_failed", nil)
+			return err
+		}
+		if !consumed || len(userID) != 16 {
+			s.logServiceAudit(ctx, "auth.pin.reset.consume", nil, false, "invalid_or_expired", nil)
+			return ErrInvalidResetLink
+		}
+		_ = s.clearSecurityPINLockState(ctx, userID)
+		s.logServiceAudit(ctx, "auth.pin.reset.consume", userID, true, "pin_reset_success", nil)
+		return nil
+	case pinResetMethodMicrosoft:
+		userID, err := s.consumeMicrosoftReauthTokenForPurposes(ctx, []string{
+			microsoftReauthPurposePINResetRequest,
+			microsoftReauthPurposePINResetConfirm,
+		}, reauthToken)
+		if err != nil {
+			s.logServiceAudit(ctx, "auth.pin.reset.microsoft", nil, false, "invalid_sso_reauth", nil)
+			return err
+		}
+		user, err := s.repo.GetUserByID(ctx, userID)
+		if err != nil {
+			return err
+		}
+		if user == nil || len(user.ID) != 16 {
+			return ErrInvalidToken
+		}
+		pinRecord, err := s.hashSecurityPIN(newPIN)
+		if err != nil {
+			return err
+		}
+		if err := s.repo.SetUserSecurityPIN(ctx, user.ID, pinRecord, now); err != nil {
+			return err
+		}
+		if err := s.repo.InvalidateActiveSecurityPINResetTokensByUserID(ctx, user.ID, now); err != nil {
+			return err
+		}
+		_ = s.clearSecurityPINLockState(ctx, user.ID)
+		s.logServiceAudit(ctx, "auth.pin.reset.microsoft", user.ID, true, "pin_reset_success", nil)
+		return nil
+	default:
+		return ErrInvalidReauthMethod
+	}
+}
+
+func (s *AuthService) GetRoleByID(ctx context.Context, id []byte) (*auth.Role, error) {
+	if s.roleRepo == nil {
+		return nil, errors.New("role repo not configured")
+	}
+	return s.roleRepo.GetRoleByID(ctx, id)
+}
+
+func (s *AuthService) PermissionRequiresPIN(ctx context.Context, permissionKey string) (bool, error) {
+	if s.roleRepo == nil {
+		return false, errors.New("role repo not configured")
+	}
+
+	perm, err := s.roleRepo.GetPermissionByKey(ctx, permissionKey)
+	if err != nil {
+		return false, err
+	}
+	if perm == nil {
+		return false, nil
+	}
+	return perm.RequiresPIN, nil
+}
+
+func (s *AuthService) HasPermission(ctx context.Context, userID []byte, permissionKey string) (bool, error) {
+	if s.repo == nil {
+		return false, errors.New("auth repo not configured")
+	}
+	if s.roleRepo == nil {
+		return false, errors.New("role repo not configured")
+	}
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return false, err
+	}
+	if user == nil {
+		return false, nil
+	}
+
+	for _, roleID := range collectAuthUserRoleIDs(user) {
+		allowed, err := s.roleRepo.HasRolePermission(ctx, roleID, permissionKey)
+		if err != nil {
+			return false, err
+		}
+		if allowed {
+			return true, nil
+		}
+	}
+
+	return false, nil
+}
+
+func (s *AuthService) GetPermissionsByRoleID(ctx context.Context, roleID []byte) ([]auth.Permission, error) {
+	if s.roleRepo == nil {
+		return nil, errors.New("role repo not configured")
+	}
+	return s.roleRepo.ListPermissionsByRoleID(ctx, roleID)
+}
+
+func (s *AuthService) GetPermissionsByUserID(ctx context.Context, userID []byte) ([]auth.Permission, error) {
+	if s.repo == nil {
+		return nil, errors.New("auth repo not configured")
+	}
+	if s.roleRepo == nil {
+		return nil, errors.New("role repo not configured")
+	}
+
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+	if user == nil {
+		return []auth.Permission{}, nil
+	}
+
+	permsByKey := make(map[string]auth.Permission)
+	for _, roleID := range collectAuthUserRoleIDs(user) {
+		perms, err := s.roleRepo.ListPermissionsByRoleID(ctx, roleID)
+		if err != nil {
+			return nil, err
+		}
+		for i := range perms {
+			key := strings.TrimSpace(perms[i].Key)
+			if key == "" {
+				key = string(perms[i].ID)
+			}
+			if _, exists := permsByKey[key]; exists {
+				continue
+			}
+			permsByKey[key] = perms[i]
+		}
+	}
+
+	out := make([]auth.Permission, 0, len(permsByKey))
+	for _, perm := range permsByKey {
+		out = append(out, perm)
+	}
+	sort.Slice(out, func(i, j int) bool {
+		leftName := strings.ToLower(strings.TrimSpace(out[i].Name))
+		rightName := strings.ToLower(strings.TrimSpace(out[j].Name))
+		if leftName == rightName {
+			return strings.ToLower(strings.TrimSpace(out[i].Key)) < strings.ToLower(strings.TrimSpace(out[j].Key))
+		}
+		return leftName < rightName
+	})
+
+	return out, nil
+}
+
+func (s *AuthService) AccessTTL() time.Duration  { return s.cfg.JWTAccessTTL }
+func (s *AuthService) RefreshTTL() time.Duration { return s.cfg.JWTRefreshTTL }
+func (s *AuthService) RefreshTOTPTTL() time.Duration {
+	return s.cfg.JWTRefreshTOTPTTL
+}
+func (s *AuthService) EmailOTPResendCooldown() time.Duration { return s.cfg.EmailOTPResendCooldown }
+func (s *AuthService) EmailOTPMaxResendPerHour() int         { return s.cfg.EmailOTPMaxResendPerHour }
+func (s *AuthService) IsLoginEmailOTPEnabled(ctx context.Context) bool {
+	if s == nil || s.emailOTPEnabled == nil {
+		return true
+	}
+	enabled, err := s.emailOTPEnabled(ctx)
+	if err != nil {
+		return true
+	}
+	return enabled
+}
+func (s *AuthService) SecurityPINTokenTTL() time.Duration {
+	return s.cfg.SecurityPINActionTokenTTL
+}
+func (s *AuthService) IsSecurityPINBlocked(ctx context.Context, userID []byte) bool {
+	return s.isSecurityPINLocked(ctx, userID)
+}
+func (s *AuthService) CookieDomain() string          { return s.cfg.JWTCookieDomain }
+func (s *AuthService) CookieSecure() bool            { return s.cfg.JWTCookieSecure }
+func (s *AuthService) CookieSameSite() string        { return s.cfg.JWTCookieSameSite }
+func (s *AuthService) AccessCookieName() string      { return s.cfg.JWTAccessCookieName }
+func (s *AuthService) RefreshCookieName() string     { return s.cfg.JWTRefreshCookieName }
+func (s *AuthService) SSOSuccessRedirectURL() string { return s.cfg.SSOSuccessRedirectURL }
+func (s *AuthService) MicrosoftLogoutURL() string {
+	if s == nil || s.sso == nil {
+		return ""
+	}
+	return strings.TrimSpace(s.sso.LogoutURL(s.cfg.SSOSuccessRedirectURL))
+}
+func (s *AuthService) ForgotPasswordIPRateMax() int { return s.cfg.ForgotPasswordIPRateMax }
+func (s *AuthService) LoginIPRateMax() int          { return s.cfg.LoginIPRateMax }
+
+func collectAuthUserRoleIDs(user *auth.User) [][]byte {
+	if user == nil {
+		return nil
+	}
+
+	roleIDs := make([][]byte, 0, len(user.RoleIDs)+1)
+	seen := make(map[string]struct{}, len(user.RoleIDs)+1)
+
+	appendRole := func(roleID []byte) {
+		if len(roleID) != 16 {
+			return
+		}
+		key := string(roleID)
+		if _, exists := seen[key]; exists {
+			return
+		}
+		seen[key] = struct{}{}
+		roleIDs = append(roleIDs, append([]byte(nil), roleID...))
+	}
+
+	appendRole(user.RoleID)
+	for i := range user.RoleIDs {
+		appendRole(user.RoleIDs[i])
+	}
+
+	return roleIDs
+}
+
+func normalizeAuthServiceRoleIDs(primaryRoleID []byte, roleIDs [][]byte) [][]byte {
+	roleSet := &auth.User{
+		RoleID:  primaryRoleID,
+		RoleIDs: roleIDs,
+	}
+	return collectAuthUserRoleIDs(roleSet)
+}
+func (s *AuthService) ForgotPasswordIPRateWindow() time.Duration {
+	return s.cfg.ForgotPasswordIPRateWindow
+}
+
+func (s *AuthService) LoginIPRateWindow() time.Duration {
+	return s.cfg.LoginIPRateWindow
+}
+
+// VerifyEmail verifies a token and marks the user as verified.
+func (s *AuthService) VerifyEmail(ctx context.Context, token string) error {
+	if token == "" {
+		return ErrInvalidToken
+	}
+	if s.tokens == nil {
+		return ErrInvalidToken
+	}
+	key := emailVerifyKey(token)
+	data, err := s.tokens.Get(ctx, key)
+	if err != nil || len(data) != 16 {
+		return ErrInvalidToken
+	}
+	_ = s.tokens.Delete(ctx, key)
+	return s.repo.MarkEmailVerified(ctx, data)
+}
+
+func (s *AuthService) SetPasswordWithInviteToken(ctx context.Context, token, password string) error {
+	if token == "" || password == "" {
+		return errors.New("token and password are required")
+	}
+	if s.tokens == nil {
+		return ErrInvalidToken
+	}
+	var (
+		data      []byte
+		key       string
+		err       error
+		parsedUID []byte
+	)
+	if uid, jti, _, parseErr := s.parseInviteJWT(token); parseErr == nil {
+		key = inviteKey(jti)
+		data, err = s.tokens.Get(ctx, key)
+		if err != nil || len(data) != 16 || !bytes.Equal(data, uid) {
+			return ErrInvalidToken
+		}
+		parsedUID = uid
+	} else {
+		// Backward compatibility for legacy invite token format.
+		key = inviteKey(token)
+		data, err = s.tokens.Get(ctx, key)
+		if err != nil || len(data) != 16 {
+			return ErrInvalidToken
+		}
+		parsedUID = data
+	}
+
+	hash, salt, err := s.hashPassword(password)
+	if err != nil {
+		return err
+	}
+	if err := s.repo.SetUserPassword(ctx, parsedUID, hash, salt); err != nil {
+		return err
+	}
+	if err := s.repo.MarkEmailVerified(ctx, parsedUID); err != nil {
+		return err
+	}
+	_ = s.tokens.Delete(ctx, key)
+	return nil
+}
+
+// SSO Microsoft (Entra) login flow: exchange code -> resolve existing identity -> get user.
+func (s *AuthService) LoginWithMicrosoft(ctx context.Context, code string, codeVerifier ...string) (*auth.UserIdentity, string, error) {
+	claims, tokenSet, err := s.exchangeMicrosoftCode(ctx, code, msFirstNonEmpty(codeVerifier...))
+	if err != nil {
+		return nil, "", err
+	}
+	identity, err := s.resolveOrSyncMicrosoftIdentityByClaims(ctx, claims)
+	if err != nil {
+		return nil, "", err
+	}
+	if tokenSet != nil {
+		if err := s.storeMicrosoftOAuthToken(ctx, identity.UserID, claims, *tokenSet); err != nil {
+			return nil, "", err
+		}
+	}
+	return identity, claims.SessionID, nil
+}
+
+// ExchangeMicrosoftToken resolves a Microsoft identity from frontend-provided tokens.
+// This flow is intended for SPA silent SSO (ssoSilent) where backend receives id_token/access_token directly.
+func (s *AuthService) ExchangeMicrosoftToken(ctx context.Context, accessToken, idToken string, idTokenClaims map[string]any) (*auth.UserIdentity, error) {
+	accessToken = strings.TrimSpace(accessToken)
+	idToken = strings.TrimSpace(idToken)
+	if accessToken == "" {
+		return nil, errors.New("access token is required")
+	}
+	if idToken == "" {
+		return nil, errors.New("id token is required")
+	}
+
+	claimsMap := idTokenClaims
+	if len(claimsMap) == 0 {
+		var err error
+		claimsMap, err = parseJWTClaims(idToken)
+		if err != nil {
+			return nil, errors.New("invalid id token claims")
+		}
+	}
+
+	exp := parseJWTUnixClaim(claimsMap["exp"])
+	if exp <= 0 || time.Unix(exp, 0).Before(time.Now().UTC()) {
+		return nil, ErrInvalidToken
+	}
+
+	claims := MicrosoftClaims{
+		Subject:   strings.TrimSpace(parseJWTStringClaim(claimsMap, "sub")),
+		Email:     strings.TrimSpace(parseJWTStringClaim(claimsMap, "email")),
+		Name:      strings.TrimSpace(parseJWTStringClaim(claimsMap, "name")),
+		TenantID:  strings.TrimSpace(parseJWTStringClaim(claimsMap, "tid")),
+		ObjectID:  strings.TrimSpace(parseJWTStringClaim(claimsMap, "oid")),
+		SessionID: strings.TrimSpace(parseJWTStringClaim(claimsMap, "sid")),
+	}
+	if claims.Email == "" {
+		claims.Email = strings.TrimSpace(parseJWTStringClaim(claimsMap, "preferred_username"))
+	}
+
+	return s.resolveOrSyncMicrosoftIdentityByClaims(ctx, claims)
+}
+
+func (s *AuthService) LinkSSOForUser(ctx context.Context, userID []byte, provider, code string, codeVerifier ...string) (*auth.UserIdentity, error) {
+	if s.sso == nil {
+		return nil, errors.New("sso not configured")
+	}
+	if len(userID) != 16 {
+		return nil, ErrUserNotFound
+	}
+	provider = strings.ToLower(strings.TrimSpace(provider))
+	if provider != ssoProviderMicrosoft {
+		return nil, ErrUnsupportedSSOProvider
+	}
+	code = strings.TrimSpace(code)
+	if code == "" {
+		return nil, errors.New("authorization code is required")
+	}
+
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+	if user == nil || len(user.ID) != 16 {
+		return nil, ErrUserNotFound
+	}
+
+	claims, tokenSet, err := s.exchangeMicrosoftCode(ctx, code, msFirstNonEmpty(codeVerifier...))
+	if err != nil {
+		return nil, err
+	}
+	if !strings.EqualFold(strings.TrimSpace(user.Email), strings.TrimSpace(claims.Email)) {
+		return nil, ErrSSONotLinked
+	}
+	subject := strings.TrimSpace(claims.Subject)
+	if subject == "" {
+		return nil, errors.New("microsoft subject is empty")
+	}
+
+	existingBySubject, err := s.repo.GetIdentityByProviderSubject(ctx, provider, subject)
+	if err != nil {
+		return nil, err
+	}
+	if existingBySubject != nil {
+		if bytes.Equal(existingBySubject.UserID, userID) {
+			return nil, ErrSSOAlreadyLinked
+		}
+		return nil, ErrSSOLinkedToAnotherUser
+	}
+
+	existingByUser, err := s.repo.GetIdentityByUserID(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+	if existingByUser != nil {
+		return nil, ErrSSOAlreadyLinked
+	}
+
+	identity := &auth.UserIdentity{
+		ID:              uuidv7.MustBytes(),
+		UserID:          userID,
+		Provider:        provider,
+		ProviderSubject: subject,
+		Email:           strings.ToLower(strings.TrimSpace(claims.Email)),
+	}
+	if err := s.repo.CreateIdentity(ctx, identity); err != nil {
+		return nil, err
+	}
+	if tokenSet != nil {
+		if err := s.storeMicrosoftOAuthToken(ctx, userID, claims, *tokenSet); err != nil {
+			return nil, err
+		}
+	}
+	return identity, nil
+}
+
+func (s *AuthService) resolveOrSyncMicrosoftIdentityByClaims(ctx context.Context, claims MicrosoftClaims) (*auth.UserIdentity, error) {
+	subject := strings.TrimSpace(claims.Subject)
+	if subject == "" {
+		return nil, errors.New("microsoft subject is empty")
+	}
+
+	email := strings.ToLower(strings.TrimSpace(claims.Email))
+	if email == "" {
+		return nil, ErrSSOEmailNotFound
+	}
+
+	user, err := s.repo.GetUserBySSOEmail(ctx, email)
+	if err != nil {
+		return nil, err
+	}
+	if user == nil || len(user.ID) != 16 {
+		return nil, ErrSSONotLinked
+	}
+
+	existingBySubject, err := s.repo.GetIdentityByProviderSubject(ctx, ssoProviderMicrosoft, subject)
+	if err != nil {
+		return nil, err
+	}
+	if existingBySubject != nil && len(existingBySubject.UserID) == 16 && !bytes.Equal(existingBySubject.UserID, user.ID) {
+		return nil, ErrSSOLinkedToAnotherUser
+	}
+
+	existingByUser, err := s.repo.GetIdentityByUserID(ctx, user.ID)
+	if err != nil {
+		return nil, err
+	}
+	if existingByUser != nil && existingByUser.Provider == ssoProviderMicrosoft && strings.TrimSpace(existingByUser.ProviderSubject) != "" && !strings.EqualFold(existingByUser.ProviderSubject, subject) {
+		if _, err := s.repo.DeleteIdentityByUserIDProvider(ctx, user.ID, ssoProviderMicrosoft); err != nil {
+			return nil, err
+		}
+	}
+
+	identity := &auth.UserIdentity{
+		UserID:          append([]byte(nil), user.ID...),
+		Provider:        ssoProviderMicrosoft,
+		ProviderSubject: subject,
+		Email:           email,
+	}
+	if name := strings.TrimSpace(claims.Name); name != "" {
+		metadata, _ := json.Marshal(map[string]string{"name": name})
+		identity.Metadata = metadata
+	}
+	if existingBySubject != nil && len(existingBySubject.ID) == 16 {
+		identity.ID = append([]byte(nil), existingBySubject.ID...)
+	}
+	if err := s.repo.UpsertIdentity(ctx, identity); err != nil {
+		return nil, err
+	}
+
+	createdIdentity, err := s.repo.GetIdentityByProviderSubject(ctx, ssoProviderMicrosoft, subject)
+	if err != nil {
+		return nil, err
+	}
+	if createdIdentity != nil {
+		return createdIdentity, nil
+	}
+	return identity, nil
+}
+
+func (s *AuthService) UnlinkSSOForUser(ctx context.Context, userID []byte, provider string) error {
+	if len(userID) != 16 {
+		return ErrUserNotFound
+	}
+	provider = strings.ToLower(strings.TrimSpace(provider))
+	if provider != ssoProviderMicrosoft {
+		return ErrUnsupportedSSOProvider
+	}
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return err
+	}
+	if user == nil || len(user.ID) != 16 {
+		return ErrUserNotFound
+	}
+	identity, err := s.repo.GetIdentityByUserID(ctx, userID)
+	if err != nil {
+		return err
+	}
+	if identity == nil || !strings.EqualFold(identity.Provider, provider) {
+		return ErrSSONotLinked
+	}
+	deleted, err := s.repo.DeleteIdentityByUserIDProvider(ctx, userID, provider)
+	if err != nil {
+		return err
+	}
+	if !deleted {
+		return ErrSSONotLinked
+	}
+	return nil
+}
+
+// TOTP verify: decrypt secret and verify code (6 digits).
+func (s *AuthService) VerifyTOTP(ctx context.Context, userID []byte, code string) (bool, error) {
+	record, err := s.repo.GetUserTOTP(ctx, userID)
+	if err != nil || record == nil || !record.Enabled {
+		return false, nil
+	}
+
+	secret, err := s.protector.Decrypt(record.SecretEncrypted)
+	if err != nil {
+		return false, err
+	}
+
+	ok := verifyTOTP(string(secret), code)
+	if ok {
+		_ = s.repo.UpdateUserTOTPLastUsed(ctx, userID)
+	}
+	return ok, nil
+}
+
+func (s *AuthService) CreateTOTPChallenge(ctx context.Context, userID []byte) (string, error) {
+	if s.tokens == nil {
+		return "", errors.New("token store not configured")
+	}
+	token, err := randomToken(32)
+	if err != nil {
+		return "", err
+	}
+	if err := s.tokens.Set(ctx, totpChallengeKey(token), userID, s.cfg.TOTPChallengeTTL); err != nil {
+		return "", err
+	}
+	return token, nil
+}
+
+func (s *AuthService) ConsumeTOTPChallenge(ctx context.Context, token string) ([]byte, error) {
+	if s.tokens == nil || token == "" {
+		return nil, ErrInvalidToken
+	}
+	data, err := s.tokens.Get(ctx, totpChallengeKey(token))
+	if err != nil || data == nil {
+		return nil, ErrInvalidToken
+	}
+	_ = s.tokens.Delete(ctx, totpChallengeKey(token))
+	_ = s.tokens.Delete(ctx, totpChallengeAttemptKey(token))
+	return data, nil
+}
+
+func (s *AuthService) ResolveTOTPChallenge(ctx context.Context, token string) ([]byte, error) {
+	token = strings.TrimSpace(token)
+	if s.tokens == nil || token == "" {
+		return nil, ErrInvalidToken
+	}
+	data, err := s.tokens.Get(ctx, totpChallengeKey(token))
+	if err != nil || data == nil {
+		return nil, ErrInvalidToken
+	}
+	return data, nil
+}
+
+func (s *AuthService) InvalidateTOTPChallenge(ctx context.Context, token string) {
+	token = strings.TrimSpace(token)
+	if s.tokens == nil || token == "" {
+		return
+	}
+	_ = s.tokens.Delete(ctx, totpChallengeKey(token))
+	_ = s.tokens.Delete(ctx, totpChallengeAttemptKey(token))
+}
+
+func (s *AuthService) RegisterFailedTOTPChallengeAttempt(ctx context.Context, token string) (int, error) {
+	token = strings.TrimSpace(token)
+	if s.tokens == nil || token == "" {
+		return 0, ErrInvalidToken
+	}
+	key := totpChallengeAttemptKey(token)
+	raw, err := s.tokens.Get(ctx, key)
+	if err != nil {
+		return 0, err
+	}
+	attempts := 0
+	if len(raw) > 0 {
+		attempts, _ = strconv.Atoi(strings.TrimSpace(string(raw)))
+	}
+	attempts++
+	if attempts >= totpChallengeMaxAttempts {
+		s.InvalidateTOTPChallenge(ctx, token)
+		return 0, ErrTOTPChallengeAttemptLimit
+	}
+	remaining := totpChallengeMaxAttempts - attempts
+	if setErr := s.tokens.Set(ctx, key, []byte(strconv.Itoa(attempts)), s.cfg.TOTPChallengeTTL); setErr != nil {
+		return 0, setErr
+	}
+	return remaining, nil
+}
+
+func (s *AuthService) TOTPChallengeMaxAttempts() int {
+	return totpChallengeMaxAttempts
+}
+
+func (s *AuthService) CreateEmailOTPChallenge(ctx context.Context, userID []byte) (string, error) {
+	if s.tokens == nil {
+		return "", errors.New("token store not configured")
+	}
+	if len(userID) != 16 {
+		return "", ErrUserNotFound
+	}
+	token, err := randomToken(32)
+	if err != nil {
+		return "", err
+	}
+	if err := s.tokens.Set(ctx, emailOTPChallengeKey(token), userID, s.cfg.EmailOTPChallengeTTL); err != nil {
+		return "", err
+	}
+	return token, nil
+}
+
+func (s *AuthService) ResolveEmailOTPChallenge(ctx context.Context, token string) ([]byte, error) {
+	token = strings.TrimSpace(token)
+	if token == "" || s.tokens == nil {
+		return nil, ErrInvalidToken
+	}
+	data, err := s.tokens.Get(ctx, emailOTPChallengeKey(token))
+	if err != nil || len(data) != 16 {
+		return nil, ErrInvalidToken
+	}
+	return data, nil
+}
+
+func (s *AuthService) SendLoginEmailOTP(ctx context.Context, challengeToken string) error {
+	userID, err := s.ResolveEmailOTPChallenge(ctx, challengeToken)
+	if err != nil {
+		return ErrInvalidToken
+	}
+	now := time.Now().UTC()
+	active, err := s.repo.GetActiveUserEmailLoginOTP(ctx, userID, now)
+	if err != nil {
+		return err
+	}
+	if active != nil && now.Sub(active.LastSentAt) < s.cfg.EmailOTPResendCooldown {
+		s.logServiceAudit(ctx, "auth.email_otp.send", userID, false, "resend_cooldown", nil)
+		return ErrEmailOTPRateLimited
+	}
+	count, err := s.repo.CountUserEmailLoginOTPSince(ctx, userID, now.Add(-5*time.Minute))
+	if err != nil {
+		return err
+	}
+	if count >= int64(s.cfg.EmailOTPMaxResendPerHour) {
+		s.logServiceAudit(ctx, "auth.email_otp.send", userID, false, "resend_limit_exceeded", nil)
+		return ErrEmailOTPResendExceeded
+	}
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return err
+	}
+	if user == nil || !user.IsActive || strings.TrimSpace(user.Email) == "" {
+		return ErrUserNotFound
+	}
+	otpCode, err := randomNumericCode(s.cfg.EmailOTPLength)
+	if err != nil {
+		return err
+	}
+	if err := s.repo.InvalidateActiveUserEmailLoginOTPs(ctx, userID, now); err != nil {
+		return err
+	}
+	row := &auth.UserEmailLoginOTP{
+		UserID:       append([]byte(nil), userID...),
+		OTPHash:      hashEmailOTPCode(userID, otpCode, s.cfg.PasswordPepper),
+		ExpiresAt:    now.Add(s.cfg.EmailOTPExpiry),
+		MaxAttempts:  s.cfg.EmailOTPMaxAttempts,
+		ResendCount:  int(count) + 1,
+		LastSentAt:   now,
+		AttemptCount: 0,
+	}
+	if err := s.repo.CreateUserEmailLoginOTP(ctx, row); err != nil {
+		return err
+	}
+	job := s.buildLoginEmailOTPJob(ctx, user, otpCode)
+	if err := s.dispatchPreparedEmailJob(ctx, job); err != nil {
+		return err
+	}
+	s.logServiceAudit(ctx, "auth.email_otp.send", userID, true, "otp_sent", map[string]any{
+		"resend_count": row.ResendCount,
+	})
+	return nil
+}
+
+func (s *AuthService) VerifyLoginEmailOTP(ctx context.Context, challengeToken, code string) (*auth.User, error) {
+	userID, err := s.ResolveEmailOTPChallenge(ctx, challengeToken)
+	if err != nil {
+		return nil, ErrInvalidToken
+	}
+	code = strings.TrimSpace(code)
+	if len(code) != s.cfg.EmailOTPLength {
+		s.logServiceAudit(ctx, "auth.email_otp.verify", userID, false, "invalid_format", nil)
+		return nil, ErrInvalidEmailOTP
+	}
+	for i := 0; i < len(code); i++ {
+		if code[i] < '0' || code[i] > '9' {
+			s.logServiceAudit(ctx, "auth.email_otp.verify", userID, false, "invalid_format", nil)
+			return nil, ErrInvalidEmailOTP
+		}
+	}
+	ok, attemptsLeft, err := s.repo.ConsumeUserEmailLoginOTP(ctx, userID, hashEmailOTPCode(userID, code, s.cfg.PasswordPepper), time.Now().UTC())
+	if err != nil {
+		return nil, err
+	}
+	if !ok {
+		s.logServiceAudit(ctx, "auth.email_otp.verify", userID, false, "invalid_otp", map[string]any{
+			"attempts_left": attemptsLeft,
+		})
+		return nil, ErrInvalidEmailOTP
+	}
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil || user == nil {
+		return nil, ErrUserNotFound
+	}
+	_ = s.tokens.Delete(ctx, emailOTPChallengeKey(strings.TrimSpace(challengeToken)))
+	s.logServiceAudit(ctx, "auth.email_otp.verify", userID, true, "otp_verified", nil)
+	return user, nil
+}
+
+// SetupTOTP creates or replaces the user's TOTP secret and returns the provisioning URI.
+func (s *AuthService) SetupTOTP(ctx context.Context, userID []byte, accountName string) (secret, otpAuthURL, issuer string, err error) {
+	if s.protector == nil {
+		return "", "", "", errors.New("secret protector not configured")
+	}
+
+	issuer = s.cfg.TOTPIssuer
+	existing, err := s.repo.GetUserTOTP(ctx, userID)
+	if err != nil {
+		return "", "", "", err
+	}
+	if existing != nil && len(existing.SecretEncrypted) > 0 {
+		secretBytes, err := s.protector.Decrypt(existing.SecretEncrypted)
+		if err != nil {
+			return "", "", "", err
+		}
+		secret = string(secretBytes)
+		return secret, buildTOTPAuthURL(issuer, accountName, secret), issuer, nil
+	}
+
+	key, err := totp.Generate(totp.GenerateOpts{
+		Issuer:      issuer,
+		AccountName: accountName,
+	})
+	if err != nil {
+		return "", "", "", err
+	}
+
+	secret = key.Secret()
+	otpAuthURL = key.URL()
+
+	enc, err := s.protector.Encrypt([]byte(secret))
+	if err != nil {
+		return "", "", "", err
+	}
+
+	record := &auth.UserTOTP{
+		UserID:          userID,
+		SecretEncrypted: enc,
+		Enabled:         false,
+	}
+	if err := s.repo.UpsertUserTOTP(ctx, record); err != nil {
+		return "", "", "", err
+	}
+
+	return secret, otpAuthURL, issuer, nil
+}
+
+func (s *AuthService) DisableTOTP(ctx context.Context, userID []byte) error {
+	return s.repo.DisableUserTOTP(ctx, userID)
+}
+
+func (s *AuthService) ResetTOTPSetup(ctx context.Context, userID []byte, method, pin, password string) error {
+	if len(userID) != 16 {
+		return ErrInvalidToken
+	}
+	if err := s.authorizeWithPINOrPassword(ctx, userID, method, pin, password); err != nil {
+		return err
+	}
+	return s.DeleteTOTPSetup(ctx, userID)
+}
+
+func (s *AuthService) ResetWebAuthnSetup(ctx context.Context, userID []byte, method, pin, password string) error {
+	if len(userID) != 16 {
+		return ErrInvalidToken
+	}
+	if err := s.authorizeWithPINOrPassword(ctx, userID, method, pin, password); err != nil {
+		return err
+	}
+	return s.DeleteWebAuthnSetup(ctx, userID)
+}
+
+func (s *AuthService) DeleteTOTPSetup(ctx context.Context, userID []byte) error {
+	if len(userID) != 16 {
+		return ErrInvalidToken
+	}
+	if err := s.repo.DeleteUserTOTPSetup(ctx, userID); err != nil {
+		return err
+	}
+	s.logServiceAudit(ctx, "auth.totp.reset_setup", userID, true, "totp_setup_deleted", nil)
+	return nil
+}
+
+func (s *AuthService) DeleteWebAuthnSetup(ctx context.Context, userID []byte) error {
+	if len(userID) != 16 {
+		return ErrInvalidToken
+	}
+	if err := s.repo.DeleteAllUserWebAuthnCredentials(ctx, userID); err != nil {
+		return err
+	}
+	s.logServiceAudit(ctx, "auth.webauthn.reset_setup", userID, true, "webauthn_credentials_deleted", nil)
+	return nil
+}
+
+func (s *AuthService) authorizeWithPINOrPassword(ctx context.Context, userID []byte, method, pin, password string) error {
+	switch strings.ToLower(strings.TrimSpace(method)) {
+	case "pin":
+		return s.verifySecurityPIN(ctx, userID, strings.TrimSpace(pin))
+	case "password":
+		user, err := s.repo.GetUserByID(ctx, userID)
+		if err != nil {
+			return err
+		}
+		if user == nil {
+			return ErrInvalidToken
+		}
+		if !s.verifyPassword(password, user.PasswordHash, user.SaltValue) {
+			return ErrInvalidCredentials
+		}
+		return nil
+	default:
+		return ErrInvalidReauthMethod
+	}
+}
+
+func (s *AuthService) consumeMicrosoftReauthToken(ctx context.Context, userID []byte, purpose, token string) error {
+	userIDFromToken, err := s.consumeMicrosoftReauthTokenForPurposes(ctx, []string{purpose}, token)
+	if err != nil {
+		return ErrInvalidSSOReauth
+	}
+	if !subtleConstantTimeCompare(userIDFromToken, userID) {
+		return ErrInvalidSSOReauth
+	}
+	return nil
+}
+
+func (s *AuthService) consumeMicrosoftReauthTokenForPurposes(ctx context.Context, purposes []string, token string) ([]byte, error) {
+	if s.tokens == nil || len(purposes) == 0 {
+		return nil, ErrInvalidSSOReauth
+	}
+	validPurposes := make([]string, 0, len(purposes))
+	for _, purpose := range purposes {
+		purpose = strings.TrimSpace(purpose)
+		if !isSupportedMicrosoftReauthPurpose(purpose) {
+			return nil, ErrInvalidSSOReauth
+		}
+		validPurposes = append(validPurposes, purpose)
+	}
+	token = strings.TrimSpace(token)
+	if token == "" {
+		return nil, ErrInvalidSSOReauth
+	}
+	raw, err := s.tokens.Get(ctx, microsoftReauthKey(token))
+	if err != nil || raw == nil {
+		return nil, ErrInvalidSSOReauth
+	}
+	_ = s.tokens.Delete(ctx, microsoftReauthKey(token))
+	parts := strings.SplitN(string(raw), "|", 2)
+	if len(parts) != 2 {
+		return nil, ErrInvalidSSOReauth
+	}
+	userID, err := uuidv7.ParseString(parts[0])
+	if err != nil || len(userID) != 16 {
+		return nil, ErrInvalidSSOReauth
+	}
+	for _, purpose := range validPurposes {
+		expected := parts[0] + "|" + purpose
+		if subtleConstantTimeCompare(raw, []byte(expected)) {
+			return userID, nil
+		}
+	}
+	return nil, ErrInvalidSSOReauth
+}
+
+func (s *AuthService) ConfirmTOTP(ctx context.Context, userID []byte, code string) (bool, error) {
+	record, err := s.repo.GetUserTOTP(ctx, userID)
+	if err != nil || record == nil {
+		return false, ErrInvalidToken
+	}
+	secret, err := s.protector.Decrypt(record.SecretEncrypted)
+	if err != nil {
+		return false, err
+	}
+	ok := verifyTOTP(string(secret), code)
+	if !ok {
+		return false, nil
+	}
+	record.Enabled = true
+	if err := s.repo.UpsertUserTOTP(ctx, record); err != nil {
+		return false, err
+	}
+	return true, nil
+}
+
+func (s *AuthService) sendEmailVerification(ctx context.Context, user *auth.User) error {
+	job, err := s.buildEmailVerificationJob(ctx, user)
+	if err != nil {
+		return err
+	}
+	return s.dispatchPreparedEmailJob(ctx, job)
+}
+
+func (s *AuthService) buildEmailVerificationJob(ctx context.Context, user *auth.User) (EmailJob, error) {
+	if s.tokens == nil || s.cfg.EmailVerifyURL == "" {
+		return EmailJob{}, nil
+	}
+
+	token, err := randomToken(32)
+	if err != nil {
+		return EmailJob{}, err
+	}
+
+	if err := s.tokens.Set(ctx, emailVerifyKey(token), user.ID, s.cfg.EmailVerifyTTL); err != nil {
+		return EmailJob{}, err
+	}
+
+	link := strings.TrimRight(s.cfg.EmailVerifyURL, "/") + "?token=" + token
+	return EmailJob{
+		MessageType:  "email_verify",
+		TemplateName: "auth.email_verify",
+		To:           user.Email,
+		Subject:      "Verify your email",
+		TextBody:     "Click this link to verify your email: " + link,
+		Tags: map[string]string{
+			"message_type": "email_verify",
+			"template":     "auth_email_verify",
+		},
+	}, nil
+}
+
+func (s *AuthService) sendInviteSetPassword(ctx context.Context, user *auth.User) error {
+	job, err := s.buildInviteSetPasswordJob(ctx, user)
+	if err != nil {
+		return err
+	}
+	return s.dispatchPreparedEmailJob(ctx, job)
+}
+
+func (s *AuthService) buildInviteSetPasswordJob(ctx context.Context, user *auth.User) (EmailJob, error) {
+	if s.tokens == nil || s.cfg.SetPasswordURL == "" {
+		return EmailJob{}, nil
+	}
+	token := ""
+	storeKey := ""
+	if s.cfg.JWTAccessSecret != "" {
+		var jti string
+		var err error
+		token, jti, err = s.issueInviteJWT(user)
+		if err != nil {
+			return EmailJob{}, err
+		}
+		storeKey = inviteKey(jti)
+		if err := s.tokens.Set(ctx, storeKey, user.ID, s.cfg.InviteTTL); err != nil {
+			return EmailJob{}, err
+		}
+	} else {
+		// Backward compatibility when JWT secret isn't configured.
+		var err error
+		token, err = randomToken(32)
+		if err != nil {
+			return EmailJob{}, err
+		}
+		storeKey = inviteKey(token)
+		if err := s.tokens.Set(ctx, storeKey, user.ID, s.cfg.InviteTTL); err != nil {
+			return EmailJob{}, err
+		}
+	}
+
+	link := strings.TrimRight(s.cfg.SetPasswordURL, "/") + "?token=" + token
+	subject, textBody, htmlBody := buildInviteSetPasswordEmail(user, link, s.cfg.InviteTTL)
+	return EmailJob{
+		MessageType:  "invite_set_password",
+		TemplateName: "auth.invite_set_password",
+		To:           user.Email,
+		Subject:      subject,
+		TextBody:     textBody,
+		HTMLBody:     htmlBody,
+		Tags: map[string]string{
+			"message_type": "invite_set_password",
+			"template":     "auth_invite_set_password",
+		},
+	}, nil
+}
+
+func (s *AuthService) buildLoginEmailOTPJob(ctx context.Context, user *auth.User, code string) EmailJob {
+	email := buildLoginOTPEmail(ctx, s.emailBranding, user.FirstName, code, s.cfg.EmailOTPExpiry)
+	return EmailJob{
+		To:           user.Email,
+		MessageType:  "login_email_otp",
+		TemplateName: "auth.login_email_otp",
+		TemplateData: map[string]any{"otp_code": code},
+		Subject:      email.Subject,
+		TextBody:     email.TextBody,
+		HTMLBody:     email.HTMLBody,
+		Attachments:  email.Attachments,
+		Tags: map[string]string{
+			"message_type": "login_email_otp",
+			"template":     "auth_login_email_otp",
+		},
+	}
+}
+
+func (s *AuthService) issueInviteJWT(user *auth.User) (token, jti string, err error) {
+	if user == nil || len(user.ID) != 16 {
+		return "", "", ErrInvalidToken
+	}
+	userID, convErr := uuidv7.BytesToString(user.ID)
+	if convErr != nil {
+		return "", "", convErr
+	}
+	jti, err = randomToken(24)
+	if err != nil {
+		return "", "", err
+	}
+	now := time.Now().UTC()
+	claims := jwt.MapClaims{
+		"type":  "invite_set_password",
+		"sub":   userID,
+		"email": strings.ToLower(strings.TrimSpace(user.Email)),
+		"jti":   jti,
+		"iat":   now.Unix(),
+		"exp":   now.Add(s.cfg.InviteTTL).Unix(),
+	}
+	token, err = jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(s.cfg.JWTAccessSecret))
+	if err != nil {
+		return "", "", err
+	}
+	return token, jti, nil
+}
+
+func (s *AuthService) parseInviteJWT(token string) (userID []byte, jti, email string, err error) {
+	if strings.TrimSpace(token) == "" || s.cfg.JWTAccessSecret == "" {
+		return nil, "", "", ErrInvalidToken
+	}
+	parsed, parseErr := jwt.Parse(token, func(t *jwt.Token) (any, error) {
+		if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, ErrInvalidToken
+		}
+		return []byte(s.cfg.JWTAccessSecret), nil
+	})
+	if parseErr != nil || !parsed.Valid {
+		return nil, "", "", ErrInvalidToken
+	}
+	claims, ok := parsed.Claims.(jwt.MapClaims)
+	if !ok {
+		return nil, "", "", ErrInvalidToken
+	}
+	if claims["type"] != "invite_set_password" {
+		return nil, "", "", ErrInvalidToken
+	}
+	sub, _ := claims["sub"].(string)
+	email, _ = claims["email"].(string)
+	jti, _ = claims["jti"].(string)
+	if sub == "" || strings.TrimSpace(email) == "" || strings.TrimSpace(jti) == "" {
+		return nil, "", "", ErrInvalidToken
+	}
+	userID, err = uuidv7.ParseString(sub)
+	if err != nil {
+		return nil, "", "", ErrInvalidToken
+	}
+	return userID, jti, strings.ToLower(strings.TrimSpace(email)), nil
+}
+
+func (s *AuthService) createAndSendPasswordReset(ctx context.Context, user *auth.User, requestedIP, userAgent string) error {
+	if strings.TrimSpace(s.cfg.PasswordResetURL) == "" {
+		log.Printf("auth forgot-password email skipped: AUTH_PASSWORD_RESET_URL is empty")
+		return nil
+	}
+
+	rawToken, err := randomToken(32)
+	if err != nil {
+		return err
+	}
+
+	now := time.Now().UTC()
+	expiresAt := now.Add(s.cfg.PasswordResetTTL)
+	record := &auth.PasswordResetToken{
+		UserID:      user.ID,
+		TokenHash:   hashToken(rawToken),
+		ExpiresAt:   expiresAt,
+		RequestedIP: sanitizeIP(requestedIP, s.ipProtector),
+		UserAgent:   truncate(strings.TrimSpace(userAgent), 255),
+	}
+
+	link := buildResetLink(s.cfg.PasswordResetURL, rawToken)
+	if link == "" {
+		return errors.New("invalid password reset url")
+	}
+	email := buildPasswordResetEmail(ctx, s.emailBranding, user.FirstName, link, s.cfg.PasswordResetTTL)
+	job := EmailJob{
+		MessageType:  "password_reset",
+		TemplateName: "auth.password_reset",
+		To:           user.Email,
+		Subject:      email.Subject,
+		TextBody:     email.TextBody,
+		HTMLBody:     email.HTMLBody,
+		Attachments:  email.Attachments,
+		Tags: map[string]string{
+			"message_type": "password_reset",
+			"template":     "auth_password_reset",
+		},
+	}
+
+	if txRepo, ok := s.repo.(auth.TransactionalRepository); ok && s.emailOutboxReady() {
+		return txRepo.WithTransaction(ctx, func(repo auth.Repository, outbox auth.EmailOutboxWriter) error {
+			if err := repo.InvalidateActivePasswordResetTokensByUserID(ctx, user.ID, now); err != nil {
+				return err
+			}
+			if err := repo.CreatePasswordResetToken(ctx, record); err != nil {
+				return err
+			}
+			return s.persistEmailOutbox(ctx, outbox, job)
+		})
+	}
+
+	if err := s.repo.InvalidateActivePasswordResetTokensByUserID(ctx, user.ID, now); err != nil {
+		return err
+	}
+	if err := s.repo.CreatePasswordResetToken(ctx, record); err != nil {
+		return err
+	}
+	return s.dispatchPreparedEmailJob(ctx, job)
+}
+
+func (s *AuthService) createAndSendSecurityPINReset(ctx context.Context, user *auth.User, requestedIP, userAgent string) error {
+	if strings.TrimSpace(s.cfg.SecurityPINResetURL) == "" {
+		log.Printf("auth pin-reset email skipped: AUTH_SECURITY_PIN_RESET_URL is empty")
+		return nil
+	}
+
+	rawToken, err := randomToken(32)
+	if err != nil {
+		return err
+	}
+
+	now := time.Now().UTC()
+	expiresAt := now.Add(s.cfg.SecurityPINResetTTL)
+	record := &auth.SecurityPINResetToken{
+		UserID:      user.ID,
+		TokenHash:   hashToken(rawToken),
+		ExpiresAt:   expiresAt,
+		RequestedIP: sanitizeIP(requestedIP, s.ipProtector),
+		UserAgent:   truncate(strings.TrimSpace(userAgent), 255),
+	}
+
+	link := buildResetLink(s.cfg.SecurityPINResetURL, rawToken)
+	if link == "" {
+		return errors.New("invalid security pin reset url")
+	}
+	email := buildSecurityPINResetEmail(ctx, s.emailBranding, user.FirstName, link, s.cfg.SecurityPINResetTTL)
+	job := EmailJob{
+		MessageType:  "security_pin_reset",
+		TemplateName: "auth.security_pin_reset",
+		To:           user.Email,
+		Subject:      email.Subject,
+		TextBody:     email.TextBody,
+		HTMLBody:     email.HTMLBody,
+		Attachments:  email.Attachments,
+		Tags: map[string]string{
+			"message_type": "security_pin_reset",
+			"template":     "auth_security_pin_reset",
+		},
+	}
+
+	if txRepo, ok := s.repo.(auth.TransactionalRepository); ok && s.emailOutboxReady() {
+		return txRepo.WithTransaction(ctx, func(repo auth.Repository, outbox auth.EmailOutboxWriter) error {
+			if err := repo.InvalidateActiveSecurityPINResetTokensByUserID(ctx, user.ID, now); err != nil {
+				return err
+			}
+			if err := repo.CreateSecurityPINResetToken(ctx, record); err != nil {
+				return err
+			}
+			return s.persistEmailOutbox(ctx, outbox, job)
+		})
+	}
+
+	if err := s.repo.InvalidateActiveSecurityPINResetTokensByUserID(ctx, user.ID, now); err != nil {
+		return err
+	}
+	if err := s.repo.CreateSecurityPINResetToken(ctx, record); err != nil {
+		return err
+	}
+	return s.dispatchPreparedEmailJob(ctx, job)
+}
+
+func (s *AuthService) isForgotPasswordCooldownActive(ctx context.Context, key, email, requestedIP string) bool {
+	if s.tokens == nil || s.cfg.ForgotPasswordEmailCooldown <= 0 {
+		return false
+	}
+	v, err := s.tokens.Get(ctx, key)
+	if err != nil {
+		return false
+	}
+	if v != nil {
+		s.auditForgotPasswordAnomaly(email, requestedIP, "cooldown_hit")
+		return true
+	}
+	return false
+}
+
+func (s *AuthService) markForgotPasswordCooldown(ctx context.Context, key string) error {
+	if s.tokens == nil || s.cfg.ForgotPasswordEmailCooldown <= 0 {
+		return nil
+	}
+	return s.tokens.Set(ctx, key, []byte("1"), s.cfg.ForgotPasswordEmailCooldown)
+}
+
+func (s *AuthService) isForgotSecurityPINCooldownActive(ctx context.Context, key string) bool {
+	if s.tokens == nil || s.cfg.ForgotSecurityPINCooldown <= 0 {
+		return false
+	}
+	v, err := s.tokens.Get(ctx, key)
+	if err != nil {
+		return false
+	}
+	return v != nil
+}
+
+func (s *AuthService) markForgotSecurityPINCooldown(ctx context.Context, key string) error {
+	if s.tokens == nil || s.cfg.ForgotSecurityPINCooldown <= 0 {
+		return nil
+	}
+	return s.tokens.Set(ctx, key, []byte("1"), s.cfg.ForgotSecurityPINCooldown)
+}
+
+func (s *AuthService) isInviteSetPasswordResendCooldownActive(ctx context.Context, key string) bool {
+	if s.tokens == nil || s.cfg.ForgotPasswordEmailCooldown <= 0 {
+		return false
+	}
+	v, err := s.tokens.Get(ctx, key)
+	if err != nil {
+		return false
+	}
+	return v != nil
+}
+
+func (s *AuthService) markInviteSetPasswordResendCooldown(ctx context.Context, key string) error {
+	if s.tokens == nil || s.cfg.ForgotPasswordEmailCooldown <= 0 {
+		return nil
+	}
+	return s.tokens.Set(ctx, key, []byte("1"), s.cfg.ForgotPasswordEmailCooldown)
+}
+
+func (s *AuthService) verifySecurityPIN(ctx context.Context, userID []byte, pin string) error {
+	if len(userID) != 16 {
+		return ErrInvalidSecurityPIN
+	}
+	if err := validateSecurityPIN(pin); err != nil {
+		return err
+	}
+	if s.isSecurityPINLocked(ctx, userID) {
+		s.logServiceAudit(ctx, "auth.pin.verify", userID, false, "blocked", nil)
+		return ErrSecurityPINLocked
+	}
+
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return err
+	}
+	if user == nil {
+		return ErrInvalidToken
+	}
+	if len(user.SecurityPINHash) == 0 {
+		return ErrSecurityPINNotSet
+	}
+
+	pinVerified := false
+	if hash, salt, ok := decodeSecurityPINRecord(user.SecurityPINHash); ok {
+		pinVerified = s.verifyPassword(pin, hash, salt)
+	} else {
+		// Backward-compatibility path for legacy encrypted PIN values.
+		if s.protector == nil {
+			return errors.New("secret protector not configured")
+		}
+		storedPIN, err := s.protector.Decrypt(user.SecurityPINHash)
+		if err != nil {
+			return err
+		}
+		pinVerified = subtleConstantTimeCompare(storedPIN, []byte(pin))
+	}
+	if pinVerified {
+		_ = s.clearSecurityPINLockState(ctx, userID)
+		return nil
+	}
+
+	reachedLimit, _ := s.increaseSecurityPINFailedAttempt(ctx, userID)
+	if reachedLimit {
+		s.logServiceAudit(ctx, "auth.pin.verify", userID, false, "max_attempts_reached_blocked", nil)
+		return ErrSecurityPINAttemptLimit
+	}
+	s.logServiceAudit(ctx, "auth.pin.verify", userID, false, "invalid_pin", nil)
+	return ErrInvalidSecurityPIN
+}
+
+func (s *AuthService) isSecurityPINLocked(ctx context.Context, userID []byte) bool {
+	if s.tokens == nil {
+		return false
+	}
+	v, err := s.tokens.Get(ctx, securityPINLockKey(userID))
+	if err != nil {
+		return false
+	}
+	return v != nil
+}
+
+func (s *AuthService) increaseSecurityPINFailedAttempt(ctx context.Context, userID []byte) (bool, error) {
+	if s.tokens == nil || s.cfg.SecurityPINMaxAttempts <= 0 {
+		return false, nil
+	}
+
+	key := securityPINAttemptKey(userID)
+	current := 0
+	raw, err := s.tokens.Get(ctx, key)
+	if err == nil && raw != nil {
+		if parsed, parseErr := strconv.Atoi(string(raw)); parseErr == nil && parsed >= 0 {
+			current = parsed
+		}
+	}
+	current++
+	if current >= s.cfg.SecurityPINMaxAttempts {
+		lockTTL := s.cfg.SecurityPINLockDuration
+		if lockTTL < 0 {
+			lockTTL = 0
+		}
+		_ = s.tokens.Set(ctx, securityPINLockKey(userID), []byte("1"), lockTTL)
+		current = 0
+		if err := s.tokens.Set(ctx, key, []byte(strconv.Itoa(current)), lockTTL); err != nil {
+			return true, err
+		}
+		return true, nil
+	}
+	lockTTL := s.cfg.SecurityPINLockDuration
+	if lockTTL < 0 {
+		lockTTL = 0
+	}
+	return false, s.tokens.Set(ctx, key, []byte(strconv.Itoa(current)), lockTTL)
+}
+
+func (s *AuthService) clearSecurityPINLockState(ctx context.Context, userID []byte) error {
+	if s.tokens == nil {
+		return nil
+	}
+	_ = s.tokens.Delete(ctx, securityPINAttemptKey(userID))
+	_ = s.tokens.Delete(ctx, securityPINLockKey(userID))
+	return nil
+}
+
+func (s *AuthService) sessionVersion(ctx context.Context, userID []byte) (int64, error) {
+	if s.tokens == nil || len(userID) == 0 {
+		return 0, nil
+	}
+	raw, err := s.tokens.Get(ctx, sessionVersionKey(userID))
+	if err != nil || len(raw) == 0 {
+		return 0, err
+	}
+	n, err := strconv.ParseInt(string(raw), 10, 64)
+	if err != nil || n < 0 {
+		return 0, ErrInvalidToken
+	}
+	return n, nil
+}
+
+func (s *AuthService) bumpSessionVersion(ctx context.Context, userID []byte) error {
+	if s.tokens == nil || len(userID) == 0 {
+		return nil
+	}
+	current, err := s.sessionVersion(ctx, userID)
+	if err != nil {
+		return err
+	}
+	next := strconv.FormatInt(current+1, 10)
+	return s.tokens.Set(ctx, sessionVersionKey(userID), []byte(next), 0)
+}
+
+func (s *AuthService) validSessionVersion(ctx context.Context, userID []byte, claim any) bool {
+	if s.tokens == nil || len(userID) == 0 {
+		return false
+	}
+	current, err := s.sessionVersion(ctx, userID)
+	if err != nil {
+		return false
+	}
+	return current == int64Claim(claim)
+}
+
+func (s *AuthService) auditForgotPasswordAnomaly(email, requestedIP, reason string) {
+	log.Printf("auth forgot-password %s email_sha256=%s ip=%s", reason, shortEmailHash(email), sanitizeIP(requestedIP, s.ipProtector))
+}
+
+func (s *AuthService) logServiceAudit(ctx context.Context, action string, userID []byte, success bool, message string, metadata map[string]any) {
+	if s.audit == nil {
+		return
+	}
+	s.audit.Log(ctx, AuditLogInput{
+		Layer:       "service",
+		Module:      "auth",
+		Action:      action,
+		ActorUserID: userID,
+		Success:     success,
+		Message:     message,
+		Metadata:    metadata,
+	})
+}
+
+func (s *AuthService) hashPassword(password string) (hash []byte, salt []byte, err error) {
+	salt = make([]byte, 16)
+	if _, err = rand.Read(salt); err != nil {
+		return nil, nil, err
+	}
+	peppered := []byte(password + s.cfg.PasswordPepper)
+	hash = argon2.IDKey(peppered, salt, s.cfg.HashTime, s.cfg.HashMemoryKB, s.cfg.HashThreads, s.cfg.HashKeyLen)
+	return hash, salt, nil
+}
+
+func (s *AuthService) verifyPassword(password string, hash, salt []byte) bool {
+	if len(hash) == 0 || len(salt) == 0 {
+		return false
+	}
+	peppered := []byte(password + s.cfg.PasswordPepper)
+	candidate := argon2.IDKey(peppered, salt, s.cfg.HashTime, s.cfg.HashMemoryKB, s.cfg.HashThreads, s.cfg.HashKeyLen)
+	return subtleConstantTimeCompare(hash, candidate)
+}
+
+func (s *AuthService) hashSecurityPIN(pin string) ([]byte, error) {
+	hash, salt, err := s.hashPassword(pin)
+	if err != nil {
+		return nil, err
+	}
+	return encodeSecurityPINRecord(hash, salt), nil
+}
+
+func encodeSecurityPINRecord(hash, salt []byte) []byte {
+	if len(hash) == 0 || len(salt) == 0 {
+		return nil
+	}
+	return []byte(
+		base64.RawURLEncoding.EncodeToString(salt) +
+			"$" +
+			base64.RawURLEncoding.EncodeToString(hash),
+	)
+}
+
+func decodeSecurityPINRecord(v []byte) (hash, salt []byte, ok bool) {
+	raw := strings.TrimSpace(string(v))
+	if raw == "" {
+		return nil, nil, false
+	}
+	parts := strings.Split(raw, "$")
+	var saltPart, hashPart string
+	switch {
+	case len(parts) == 2:
+		saltPart = parts[0]
+		hashPart = parts[1]
+	case len(parts) == 3 && parts[0] == "v1":
+		// Backward compatibility for older records.
+		saltPart = parts[1]
+		hashPart = parts[2]
+	default:
+		return nil, nil, false
+	}
+	salt, err := base64.RawURLEncoding.DecodeString(saltPart)
+	if err != nil || len(salt) == 0 {
+		return nil, nil, false
+	}
+	hash, err = base64.RawURLEncoding.DecodeString(hashPart)
+	if err != nil || len(hash) == 0 {
+		return nil, nil, false
+	}
+	return hash, salt, true
+}
+
+func randomToken(n int) (string, error) {
+	b := make([]byte, n)
+	if _, err := io.ReadFull(rand.Reader, b); err != nil {
+		return "", err
+	}
+	return base64.RawURLEncoding.EncodeToString(b), nil
+}
+
+func hashToken(raw string) []byte {
+	sum := sha256.Sum256([]byte(raw))
+	return sum[:]
+}
+
+func hashEmailOTPCode(userID []byte, code, pepper string) []byte {
+	payload := bytes.NewBuffer(nil)
+	payload.Write(userID)
+	payload.WriteString(":")
+	payload.WriteString(strings.TrimSpace(code))
+	payload.WriteString(":")
+	payload.WriteString(strings.TrimSpace(pepper))
+	sum := sha256.Sum256(payload.Bytes())
+	return sum[:]
+}
+
+func randomNumericCode(length int) (string, error) {
+	if length <= 0 {
+		length = 6
+	}
+	buf := make([]byte, length)
+	if _, err := io.ReadFull(rand.Reader, buf); err != nil {
+		return "", err
+	}
+	for i := range buf {
+		buf[i] = '0' + (buf[i] % 10)
+	}
+	return string(buf), nil
+}
+
+func hashIdentifier(raw string) string {
+	sum := sha256.Sum256([]byte(strings.ToLower(strings.TrimSpace(raw))))
+	return hex.EncodeToString(sum[:])
+}
+
+func emailVerifyKey(token string) string {
+	return "auth:email_verify:" + token
+}
+
+const (
+	ssoProviderMicrosoft                  = "microsoft"
+	microsoftStateFlowLogin               = "login"
+	microsoftStateFlowLoginCheck          = "login_check"
+	microsoftStateFlowLoginCheckStrict    = "login_check_strict"
+	microsoftStateFlowLink                = "link"
+	microsoftStateFlowReauth              = "reauth"
+	pinResetMethodPassword                = "password"
+	pinResetMethodMicrosoft               = "microsoft"
+	microsoftReauthPurposePINResetRequest = "pin_reset_request"
+	microsoftReauthPurposePINResetConfirm = "pin_reset_confirm"
+)
+
+func withMicrosoftAuthPrompt(rawURL, prompt string) string {
+	rawURL = strings.TrimSpace(rawURL)
+	prompt = strings.TrimSpace(prompt)
+	if rawURL == "" || prompt == "" {
+		return rawURL
+	}
+	parsed, err := url.Parse(rawURL)
+	if err != nil {
+		return rawURL
+	}
+	q := parsed.Query()
+	q.Set("prompt", prompt)
+	parsed.RawQuery = q.Encode()
+	return parsed.String()
+}
+
+func withMicrosoftPKCE(rawURL, codeVerifier string) string {
+	rawURL = strings.TrimSpace(rawURL)
+	codeVerifier = strings.TrimSpace(codeVerifier)
+	if rawURL == "" || codeVerifier == "" {
+		return rawURL
+	}
+	parsed, err := url.Parse(rawURL)
+	if err != nil {
+		return rawURL
+	}
+	q := parsed.Query()
+	q.Set("code_challenge_method", "S256")
+	q.Set("code_challenge", microsoftPKCEChallengeS256(codeVerifier))
+	parsed.RawQuery = q.Encode()
+	return parsed.String()
+}
+
+func ssoStateKey(state string) string {
+	return "auth:sso_state:" + state
+}
+
+func microsoftReauthKey(token string) string {
+	return "auth:microsoft_reauth:" + token
+}
+
+func refreshKey(jti string) string {
+	return "auth:refresh:" + jti
+}
+
+func refreshReplayKey(jti string) string {
+	return "auth:refresh:replay:" + jti
+}
+
+func refreshLockKey(sessionID string) string {
+	return "auth:refresh:lock:" + sessionID
+}
+
+func totpChallengeKey(token string) string {
+	return "auth:totp_challenge:" + token
+}
+
+func totpChallengeAttemptKey(token string) string {
+	return "auth:totp_challenge_attempt:" + token
+}
+
+func emailOTPChallengeKey(token string) string {
+	return "auth:email_otp_challenge:" + token
+}
+
+func inviteKey(token string) string {
+	return "auth:invite:" + token
+}
+
+func forgotPasswordCooldownKey(email string) string {
+	return "auth:forgot_password:cooldown:" + hashIdentifier(email)
+}
+
+func forgotSecurityPINCooldownKey(email string) string {
+	return "auth:security_pin:cooldown:" + hashIdentifier(email)
+}
+
+func inviteSetPasswordResendCooldownKey(userID []byte) string {
+	return "auth:invite:resend:cooldown:" + bytesToString(userID)
+}
+
+func sessionVersionKey(userID []byte) string {
+	return "auth:session_version:" + bytesToString(userID)
+}
+
+func pinActionKey(token string) string {
+	return "auth:pin_action:" + token
+}
+
+func securityPINAttemptKey(userID []byte) string {
+	return "auth:security_pin:attempt:" + bytesToString(userID)
+}
+
+func securityPINLockKey(userID []byte) string {
+	return "auth:security_pin:lock:" + bytesToString(userID)
+}
+
+func encodeMicrosoftStatePayload(payload microsoftStatePayload) ([]byte, error) {
+	return json.Marshal(payload)
+}
+
+func decodeMicrosoftStatePayload(raw []byte) (microsoftStatePayload, error) {
+	if len(raw) == 1 && raw[0] == '1' {
+		return microsoftStatePayload{Flow: microsoftStateFlowLogin}, nil
+	}
+	var payload microsoftStatePayload
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		return microsoftStatePayload{}, err
+	}
+	if payload.Flow == "" {
+		return microsoftStatePayload{}, ErrInvalidSSOState
+	}
+	return payload, nil
+}
+
+func (s *AuthService) loadMicrosoftStatePayload(ctx context.Context, state string) (microsoftStatePayload, error) {
+	state = strings.TrimSpace(state)
+	if state == "" || s.tokens == nil {
+		return microsoftStatePayload{}, ErrInvalidSSOState
+	}
+	raw, err := s.tokens.Get(ctx, ssoStateKey(state))
+	if err != nil || raw == nil {
+		return microsoftStatePayload{}, ErrInvalidSSOState
+	}
+	payload, err := decodeMicrosoftStatePayload(raw)
+	if err != nil {
+		return microsoftStatePayload{}, ErrInvalidSSOState
+	}
+	return payload, nil
+}
+
+func isSupportedMicrosoftReauthPurpose(purpose string) bool {
+	switch strings.TrimSpace(purpose) {
+	case microsoftReauthPurposePINResetRequest, microsoftReauthPurposePINResetConfirm:
+		return true
+	default:
+		return false
+	}
+}
+
+func normalizePINResetMethod(method string) string {
+	method = strings.ToLower(strings.TrimSpace(method))
+	if method == "" {
+		return pinResetMethodPassword
+	}
+	return method
+}
+
+func (s *AuthService) microsoftReauthTTL() time.Duration {
+	if s.cfg.SSOStateTTL > 0 {
+		return s.cfg.SSOStateTTL
+	}
+	return 5 * time.Minute
+}
+
+func (s *AuthService) exchangeMicrosoftCode(ctx context.Context, code, codeVerifier string) (MicrosoftClaims, *MicrosoftTokenSet, error) {
+	if advanced, ok := s.sso.(microsoftTokenExchanger); ok {
+		set, claims, err := advanced.ExchangeCodeAndTokens(ctx, code, codeVerifier)
+		if err != nil {
+			return MicrosoftClaims{}, nil, err
+		}
+		return claims, &set, nil
+	}
+	claims, err := s.sso.ExchangeCode(ctx, code)
+	if err != nil {
+		return MicrosoftClaims{}, nil, err
+	}
+	return claims, nil, nil
+}
+
+func (s *AuthService) storeMicrosoftOAuthToken(ctx context.Context, userID []byte, claims MicrosoftClaims, tokenSet MicrosoftTokenSet) error {
+	repo, ok := s.repo.(microsoftOAuthTokenStore)
+	if !ok {
+		return errors.New("microsoft oauth token store is not configured")
+	}
+	if s.protector == nil {
+		return errors.New("secret protector not configured")
+	}
+	tenantID := strings.TrimSpace(claims.TenantID)
+	if tenantID == "" {
+		return errors.New("missing microsoft tenant id")
+	}
+	objectID := strings.TrimSpace(claims.ObjectID)
+	if objectID == "" {
+		return errors.New("missing microsoft object id")
+	}
+	refreshToken := strings.TrimSpace(tokenSet.RefreshToken)
+	if refreshToken == "" {
+		return errors.New("missing refresh token")
+	}
+	encRefresh, err := s.protector.Encrypt([]byte(refreshToken))
+	if err != nil {
+		return err
+	}
+	var encAccess []byte
+	if strings.TrimSpace(tokenSet.AccessToken) != "" {
+		encAccess, err = s.protector.Encrypt([]byte(strings.TrimSpace(tokenSet.AccessToken)))
+		if err != nil {
+			return err
+		}
+	}
+	var encID []byte
+	if strings.TrimSpace(tokenSet.IDToken) != "" {
+		encID, err = s.protector.Encrypt([]byte(strings.TrimSpace(tokenSet.IDToken)))
+		if err != nil {
+			return err
+		}
+	}
+	now := time.Now().UTC()
+	var expAt *time.Time
+	if tokenSet.ExpiresIn > 0 {
+		t := now.Add(time.Duration(tokenSet.ExpiresIn) * time.Second)
+		expAt = &t
+	}
+	var refreshExpAt *time.Time
+	if tokenSet.RefreshTokenExpiresIn > 0 {
+		t := now.Add(time.Duration(tokenSet.RefreshTokenExpiresIn) * time.Second)
+		refreshExpAt = &t
+	}
+	return repo.UpsertMicrosoftOAuthToken(ctx, &auth.UserMicrosoftOAuthToken{
+		UserID:                append([]byte(nil), userID...),
+		Provider:              ssoProviderMicrosoft,
+		TenantID:              tenantID,
+		MicrosoftObjectID:     objectID,
+		MicrosoftSubject:      strings.TrimSpace(claims.Subject),
+		MicrosoftSessionID:    strings.TrimSpace(claims.SessionID),
+		RefreshTokenEncrypted: encRefresh,
+		AccessTokenEncrypted:  encAccess,
+		IDTokenEncrypted:      encID,
+		Scope:                 strings.TrimSpace(tokenSet.Scope),
+		TokenType:             strings.TrimSpace(tokenSet.TokenType),
+		AccessTokenExpiresAt:  expAt,
+		RefreshTokenExpiresAt: refreshExpAt,
+		RefreshTokenRotatedAt: &now,
+	})
+}
+
+func (s *AuthService) RefreshMicrosoftAccessToken(ctx context.Context, userID []byte) (MicrosoftTokenSet, error) {
+	if len(userID) != 16 {
+		return MicrosoftTokenSet{}, ErrInvalidToken
+	}
+	advanced, ok := s.sso.(microsoftTokenExchanger)
+	if !ok {
+		return MicrosoftTokenSet{}, errors.New("microsoft refresh is not supported")
+	}
+	if s.protector == nil {
+		return MicrosoftTokenSet{}, errors.New("secret protector not configured")
+	}
+	repo, ok := s.repo.(microsoftOAuthTokenStore)
+	if !ok {
+		return MicrosoftTokenSet{}, errors.New("microsoft oauth token store is not configured")
+	}
+	record, err := repo.GetMicrosoftOAuthTokenByUserIDProvider(ctx, userID, ssoProviderMicrosoft)
+	if err != nil {
+		return MicrosoftTokenSet{}, err
+	}
+	if record == nil || len(record.RefreshTokenEncrypted) == 0 {
+		return MicrosoftTokenSet{}, ErrMicrosoftReauthRequired
+	}
+	rawRefresh, err := s.protector.Decrypt(record.RefreshTokenEncrypted)
+	if err != nil || len(rawRefresh) == 0 {
+		return MicrosoftTokenSet{}, ErrMicrosoftReauthRequired
+	}
+	set, err := advanced.RefreshAccessToken(ctx, string(rawRefresh), "")
+	if err != nil {
+		msg := strings.ToLower(strings.TrimSpace(err.Error()))
+		if strings.Contains(msg, "invalid_grant") || strings.Contains(msg, "interaction_required") || strings.Contains(msg, "consent_required") {
+			_, _ = repo.DeleteMicrosoftOAuthTokenByUserIDProvider(ctx, userID, ssoProviderMicrosoft)
+			return MicrosoftTokenSet{}, ErrMicrosoftReauthRequired
+		}
+		return MicrosoftTokenSet{}, err
+	}
+	claims, parseErr := parseMicrosoftClaimsFromIDToken(set.IDToken)
+	if parseErr != nil {
+		return MicrosoftTokenSet{}, parseErr
+	}
+	if claims.Subject == "" {
+		claims.Subject = record.MicrosoftSubject
+	}
+	if claims.TenantID == "" {
+		claims.TenantID = record.TenantID
+	}
+	if claims.ObjectID == "" {
+		claims.ObjectID = record.MicrosoftObjectID
+	}
+	if set.RefreshToken == "" {
+		// Microsoft may not always rotate refresh token in response.
+		set.RefreshToken = string(rawRefresh)
+	}
+	if err := s.storeMicrosoftOAuthToken(ctx, userID, claims, set); err != nil {
+		return MicrosoftTokenSet{}, err
+	}
+	return set, nil
+}
+
+func (s *AuthService) LogoutMicrosoft(ctx context.Context, userID []byte) error {
+	if len(userID) != 16 {
+		return ErrInvalidToken
+	}
+	repo, ok := s.repo.(microsoftOAuthTokenStore)
+	if !ok {
+		return errors.New("microsoft oauth token store is not configured")
+	}
+	if _, err := repo.DeleteMicrosoftOAuthTokenByUserIDProvider(ctx, userID, ssoProviderMicrosoft); err != nil {
+		return err
+	}
+	return s.RevokeAllUserSessions(ctx, userID)
+}
+
+func (s *AuthService) MicrosoftSessionIDForUser(ctx context.Context, userID []byte) (string, error) {
+	if len(userID) != 16 {
+		return "", ErrInvalidToken
+	}
+	repo, ok := s.repo.(microsoftOAuthTokenStore)
+	if !ok {
+		return "", errors.New("microsoft oauth token store is not configured")
+	}
+	record, err := repo.GetMicrosoftOAuthTokenByUserIDProvider(ctx, userID, ssoProviderMicrosoft)
+	if err != nil || record == nil {
+		return "", err
+	}
+	return strings.TrimSpace(record.MicrosoftSessionID), nil
+}
+
+func msFirstNonEmpty(values ...string) string {
+	for i := range values {
+		if strings.TrimSpace(values[i]) != "" {
+			return strings.TrimSpace(values[i])
+		}
+	}
+	return ""
+}
+
+func parseJWTStringClaim(claims map[string]any, key string) string {
+	if claims == nil {
+		return ""
+	}
+	v, _ := claims[key].(string)
+	return strings.TrimSpace(v)
+}
+
+func parseJWTUnixClaim(value any) int64 {
+	switch v := value.(type) {
+	case int64:
+		return v
+	case int:
+		return int64(v)
+	case float64:
+		return int64(v)
+	case json.Number:
+		i, _ := v.Int64()
+		return i
+	default:
+		return 0
+	}
+}
+
+func bytesToString(b []byte) string {
+	s, _ := uuidv7.BytesToString(b)
+	return s
+}
+
+func splitName(full string) (string, string) {
+	full = strings.TrimSpace(full)
+	if full == "" {
+		return "User", ""
+	}
+	parts := strings.Fields(full)
+	if len(parts) == 1 {
+		return parts[0], ""
+	}
+	return parts[0], strings.Join(parts[1:], " ")
+}
+
+func normalizeUsername(username string) (string, error) {
+	username = strings.TrimSpace(username)
+	if username == "" {
+		return "", errors.New("username is required")
+	}
+	return username, nil
+}
+
+func (s *AuthService) nextAvailableUsernameFromEmail(ctx context.Context, email string) (string, error) {
+	base := usernameBaseFromEmail(email)
+	if base == "" {
+		return "", errors.New("username is required")
+	}
+	for i := 1; i <= 999; i++ {
+		candidate := base
+		if i > 1 {
+			suffix := strconv.Itoa(i)
+			candidate = truncate(base, 100-len(suffix)) + suffix
+		}
+		existing, err := s.repo.GetUserByUsername(ctx, candidate)
+		if err != nil {
+			return "", err
+		}
+		if existing == nil {
+			return candidate, nil
+		}
+	}
+	return "", errors.New("unable to allocate username")
+}
+
+func usernameBaseFromEmail(email string) string {
+	email = strings.ToLower(strings.TrimSpace(email))
+	localPart, _, found := strings.Cut(email, "@")
+	if !found {
+		localPart = email
+	}
+	localPart = strings.Trim(localPart, ".")
+	if localPart == "" {
+		localPart = "user"
+	}
+	return truncate(localPart, 100)
+}
+
+func ptrString(v string) *string {
+	if strings.TrimSpace(v) == "" {
+		return nil
+	}
+	out := strings.TrimSpace(v)
+	return &out
+}
+
+func ptrTime(t time.Time) *time.Time { return &t }
+
+func subtleConstantTimeCompare(a, b []byte) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	var v byte
+	for i := 0; i < len(a); i++ {
+		v |= a[i] ^ b[i]
+	}
+	return v == 0
+}
+
+func verifyTOTP(secret, code string) bool {
+	code = strings.ReplaceAll(code, " ", "")
+	ok, _ := totp.ValidateCustom(code, secret, time.Now().UTC(), totp.ValidateOpts{
+		Period:    30,
+		Skew:      1,
+		Digits:    otp.DigitsSix,
+		Algorithm: otp.AlgorithmSHA1,
+	})
+	return ok
+}
+
+func buildTOTPAuthURL(issuer, accountName, secret string) string {
+	label := url.PathEscape(strings.TrimSpace(issuer) + ":" + strings.TrimSpace(accountName))
+	q := url.Values{}
+	q.Set("secret", strings.TrimSpace(secret))
+	q.Set("issuer", strings.TrimSpace(issuer))
+	return "otpauth://totp/" + label + "?" + q.Encode()
+}
+
+func int64Claim(v any) int64 {
+	switch n := v.(type) {
+	case nil:
+		return 0
+	case float64:
+		return int64(n)
+	case float32:
+		return int64(n)
+	case int:
+		return int64(n)
+	case int64:
+		return n
+	case int32:
+		return int64(n)
+	case uint:
+		return int64(n)
+	case uint64:
+		return int64(n)
+	case uint32:
+		return int64(n)
+	case string:
+		parsed, err := strconv.ParseInt(n, 10, 64)
+		if err != nil {
+			return 0
+		}
+		return parsed
+	default:
+		return 0
+	}
+}
+
+func boolClaim(v any) bool {
+	switch b := v.(type) {
+	case bool:
+		return b
+	case string:
+		return strings.EqualFold(strings.TrimSpace(b), "true")
+	default:
+		return false
+	}
+}
+
+func buildResetLink(baseURL, token string) string {
+	u, err := url.Parse(strings.TrimSpace(baseURL))
+	if err != nil || u.Scheme == "" || u.Host == "" {
+		return ""
+	}
+	q := u.Query()
+	q.Set("token", token)
+	u.RawQuery = q.Encode()
+	return u.String()
+}
+
+func buildInviteSetPasswordEmail(user *auth.User, link string, ttl time.Duration) (string, string, string) {
+	minutes := int(ttl.Minutes())
+	if minutes < 1 {
+		minutes = 1440
+	}
+	displayName := strings.TrimSpace(strings.TrimSpace(user.FirstName + " " + user.LastName))
+	if displayName == "" {
+		displayName = "there"
+	}
+	subject := "Welcome to Wucher - set your password"
+	textBody := strings.Join([]string{
+		"Hi " + displayName + ",",
+		"",
+		"You've been invited to Wucher.",
+		"Set your password using the link below:",
+		link,
+		"",
+		"This invitation link expires in " + strconv.Itoa(minutes) + " minutes and can only be used once.",
+		"If you did not expect this invitation, you can ignore this email.",
+	}, "\n")
+	escapedLink := html.EscapeString(link)
+	escapedName := html.EscapeString(displayName)
+	htmlBody := strings.Join([]string{
+		"<!DOCTYPE html>",
+		`<html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">`,
+		"<title>Set your password</title></head>",
+		`<body style="margin:0;padding:0;background:#eef2f7;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;color:#111827;">`,
+		`<table role="presentation" width="100%" cellspacing="0" cellpadding="0" style="background:#eef2f7;padding:28px 12px;">`,
+		`<tr><td align="center">`,
+		`<table role="presentation" width="100%" cellspacing="0" cellpadding="0" style="max-width:680px;background:#ffffff;border:1px solid #e5e7eb;border-radius:16px;overflow:hidden;">`,
+		`<tr><td style="padding:22px 28px;background:linear-gradient(135deg,#0f172a,#1f2937);">`,
+		`<div style="font-size:20px;line-height:1.2;font-weight:700;color:#ffffff;">Wucher</div>`,
+		`<div style="margin-top:6px;font-size:13px;line-height:1.5;color:#cbd5e1;">Account Invitation</div>`,
+		`</td></tr>`,
+		`<tr><td style="padding:30px 28px 8px;font-size:24px;line-height:1.3;font-weight:700;color:#0f172a;">Set your password to activate your account</td></tr>`,
+		`<tr><td style="padding:0 28px 8px;font-size:15px;line-height:1.7;color:#334155;">Hi ` + escapedName + `, you've been invited to access Wucher. Click the button below to create your password and complete account activation.</td></tr>`,
+		`<tr><td style="padding:20px 28px 10px;">`,
+		`<a href="` + escapedLink + `" style="display:inline-block;background:#0f172a;color:#ffffff;text-decoration:none;font-weight:700;font-size:14px;letter-spacing:0.2px;padding:13px 22px;border-radius:10px;">Set Password</a>`,
+		`</td></tr>`,
+		`<tr><td style="padding:4px 28px 0;font-size:13px;line-height:1.7;color:#475569;">This invitation link expires in ` + strconv.Itoa(minutes) + ` minutes and can be used only once.</td></tr>`,
+		`<tr><td style="padding:6px 28px 0;font-size:13px;line-height:1.7;color:#475569;">If the button does not work, copy this URL into your browser:</td></tr>`,
+		`<tr><td style="padding:6px 28px 18px;word-break:break-all;font-size:12px;line-height:1.6;color:#0f172a;">` + escapedLink + `</td></tr>`,
+		`<tr><td style="padding:14px 28px 24px;border-top:1px solid #e5e7eb;font-size:12px;line-height:1.7;color:#64748b;">For security reasons, never forward this email or share this link.</td></tr>`,
+		`</table>`,
+		`</td></tr></table>`,
+		`</body></html>`,
+	}, "")
+	return subject, textBody, htmlBody
+}
+
+func shortEmailHash(email string) string {
+	return hashIdentifier(email)[:12]
+}
+
+func shortIdentifier(id []byte) string {
+	sum := sha256.Sum256(id)
+	encoded := hex.EncodeToString(sum[:])
+	if len(encoded) < 12 {
+		return encoded
+	}
+	return encoded[:12]
+}
+
+func sanitizeIP(v string, protector SecretProtector) string {
+	v = strings.TrimSpace(v)
+	if v == "" {
+		return ""
+	}
+
+	normalized := v
+	if ip := net.ParseIP(v); ip != nil {
+		normalized = ip.String()
+	} else {
+		normalized = truncate(v, 45)
+	}
+
+	if protector == nil {
+		return ""
+	}
+	enc, err := protector.Encrypt([]byte(normalized))
+	if err != nil {
+		return ""
+	}
+	return base64.RawURLEncoding.EncodeToString(enc)
+}
+
+func decryptStoredIP(v string, protector SecretProtector) string {
+	v = strings.TrimSpace(v)
+	if v == "" {
+		return ""
+	}
+	raw, err := base64.RawURLEncoding.DecodeString(v)
+	if err != nil {
+		// Backward compatibility: existing rows may still contain non-encrypted values.
+		return truncate(v, 45)
+	}
+	if protector == nil {
+		return truncate(v, 45)
+	}
+	plain, err := protector.Decrypt(raw)
+	if err != nil {
+		// Backward compatibility: existing rows may still contain non-encrypted values.
+		return truncate(v, 45)
+	}
+	return truncate(strings.TrimSpace(string(plain)), 45)
+}
+
+func deriveIPEncryptionKey(secret string) []byte {
+	sum := sha256.Sum256([]byte(secret))
+	key := make([]byte, len(sum))
+	copy(key, sum[:])
+	return key
+}
+
+func (s *AuthService) emailOutboxReady() bool {
+	return s.emailOutbox != nil && s.emailSerializer != nil
+}
+
+func (s *AuthService) createUserAndDispatchEmail(ctx context.Context, user *auth.User, job EmailJob) error {
+	if emailJobEmpty(job) {
+		return s.repo.CreateUser(ctx, user)
+	}
+	if txRepo, ok := s.repo.(auth.TransactionalRepository); ok && s.emailOutboxReady() {
+		return txRepo.WithTransaction(ctx, func(repo auth.Repository, outbox auth.EmailOutboxWriter) error {
+			if err := repo.CreateUser(ctx, user); err != nil {
+				return err
+			}
+			return s.persistEmailOutbox(ctx, outbox, job)
+		})
+	}
+	if err := s.repo.CreateUser(ctx, user); err != nil {
+		return err
+	}
+	return s.dispatchPreparedEmailJob(ctx, job)
+}
+
+func (s *AuthService) persistEmailOutbox(ctx context.Context, outbox auth.EmailOutboxWriter, job EmailJob) error {
+	if outbox == nil || !s.emailOutboxReady() {
+		return errors.New("email outbox is not configured")
+	}
+	if err := job.Validate(); err != nil {
+		return err
+	}
+	message, err := s.emailSerializer.Serialize(ctx, queue.EmailJob(job))
+	if err != nil {
+		return err
+	}
+	record, err := auth.NewEmailOutboxMessage(time.Now().UTC(), message)
+	if err != nil {
+		return err
+	}
+	if err := outbox.CreateEmailOutboxMessage(ctx, record); err != nil {
+		log.Printf("auth email outbox_persist_failed type=%s email_sha256=%s err=%v", job.NormalizedType(), job.RecipientHash(), err)
+		return err
+	}
+	log.Printf("auth email outbox_persisted type=%s message_id=%s email_sha256=%s correlation_id=%s", job.NormalizedType(), record.MessageID, job.RecipientHash(), record.CorrelationID)
+	return nil
+}
+
+func (s *AuthService) dispatchPreparedEmailJob(ctx context.Context, job EmailJob) error {
+	if emailJobEmpty(job) {
+		return nil
+	}
+	if s.emailOutboxReady() {
+		return s.persistEmailOutbox(ctx, s.emailOutbox, job)
+	}
+	if s.emailQueue != nil {
+		if err := s.emailQueue.Enqueue(ctx, job); err != nil {
+			log.Printf("auth email enqueue_failed type=%s email_sha256=%s err=%v", job.NormalizedType(), job.RecipientHash(), err)
+			return err
+		}
+		log.Printf("auth email enqueued type=%s email_sha256=%s", job.NormalizedType(), job.RecipientHash())
+		return nil
+	}
+	return errors.New("email queue is not configured")
+}
+
+func emailJobEmpty(job EmailJob) bool {
+	job = job.Canonical()
+	return strings.TrimSpace(job.To) == "" &&
+		strings.TrimSpace(job.Subject) == "" &&
+		strings.TrimSpace(job.TemplateName) == "" &&
+		strings.TrimSpace(job.TextBody) == "" &&
+		strings.TrimSpace(job.HTMLBody) == ""
+}
+
+func newIPSecretProtector(secret string) SecretProtector {
+	secret = strings.TrimSpace(secret)
+	if secret == "" {
+		return nil
+	}
+	if p, err := NewAESGCMProtectorFromBase64(secret); err == nil {
+		return p
+	}
+	// Backward compatibility for non-base64 secrets already used in environments/tests.
+	return &AESGCMProtector{key: deriveIPEncryptionKey(secret)}
+}
+
+func truncate(v string, max int) string {
+	if max <= 0 || len(v) <= max {
+		return v
+	}
+	return v[:max]
+}
+
+func sleepRemaining(start time.Time, min time.Duration) {
+	if min <= 0 {
+		return
+	}
+	elapsed := time.Since(start)
+	if elapsed < min {
+		time.Sleep(min - elapsed)
+	}
+}
+
+func validateSecurityPIN(pin string) error {
+	if len(pin) != 6 {
+		return ErrInvalidSecurityPIN
+	}
+	for i := 0; i < len(pin); i++ {
+		if pin[i] < '0' || pin[i] > '9' {
+			return ErrInvalidSecurityPIN
+		}
+	}
+	return nil
+}
+
+func normalizeSensitiveAction(action string) string {
+	action = strings.TrimSpace(strings.ToLower(action))
+	if !isCanonicalUUID(action) {
+		return ""
+	}
+	return action
+}
+
+func isCanonicalUUID(v string) bool {
+	if len(v) != 36 {
+		return false
+	}
+	if v[8] != '-' || v[13] != '-' || v[18] != '-' || v[23] != '-' {
+		return false
+	}
+	_, err := uuidv7.ParseString(v)
+	return err == nil
+}
+
+func normalizeAuthConfig(cfg config.AuthConfig) config.AuthConfig {
+	if strings.TrimSpace(cfg.IPEncryptionKey) == "" {
+		cfg.IPEncryptionKey = cfg.PasswordPepper
+	}
+	if cfg.HashTime == 0 {
+		cfg.HashTime = 1
+	}
+	if cfg.HashMemoryKB == 0 {
+		cfg.HashMemoryKB = 64 * 1024
+	}
+	if cfg.HashThreads == 0 {
+		cfg.HashThreads = 4
+	}
+	if cfg.HashKeyLen == 0 {
+		cfg.HashKeyLen = 32
+	}
+	if cfg.PasswordResetTTL < 15*time.Minute || cfg.PasswordResetTTL > 30*time.Minute {
+		cfg.PasswordResetTTL = 20 * time.Minute
+	}
+	if cfg.SecurityPINResetTTL < 15*time.Minute || cfg.SecurityPINResetTTL > 30*time.Minute {
+		cfg.SecurityPINResetTTL = 20 * time.Minute
+	}
+	if cfg.ForgotSecurityPINCooldown < 0 {
+		cfg.ForgotSecurityPINCooldown = 2 * time.Minute
+	}
+	if cfg.ForgotSecurityPINMinDuration < 0 {
+		cfg.ForgotSecurityPINMinDuration = 0
+	}
+	if cfg.SecurityPINMaxAttempts <= 0 {
+		cfg.SecurityPINMaxAttempts = 5
+	}
+	if cfg.SecurityPINLockDuration < 0 {
+		cfg.SecurityPINLockDuration = 0
+	}
+	if cfg.SecurityPINActionTokenTTL <= 0 {
+		cfg.SecurityPINActionTokenTTL = 5 * time.Minute
+	}
+	if cfg.JWTAccessTTL <= 0 {
+		cfg.JWTAccessTTL = 10 * time.Minute
+	}
+	if cfg.JWTRefreshTTL <= 0 {
+		cfg.JWTRefreshTTL = time.Hour
+	}
+	if cfg.JWTRefreshTOTPTTL <= 0 {
+		cfg.JWTRefreshTOTPTTL = cfg.JWTRefreshTTL
+	}
+	if cfg.JWTLocalRefreshTTL <= 0 {
+		cfg.JWTLocalRefreshTTL = 24 * time.Hour
+	}
+	if cfg.SessionIdleTTL <= 0 {
+		cfg.SessionIdleTTL = 15 * time.Minute
+	}
+	if cfg.ForgotPasswordEmailCooldown < 0 {
+		cfg.ForgotPasswordEmailCooldown = 2 * time.Minute
+	}
+	if cfg.ForgotPasswordMinDuration < 0 {
+		cfg.ForgotPasswordMinDuration = 0
+	}
+	if cfg.ForgotPasswordIPRateMax <= 0 {
+		cfg.ForgotPasswordIPRateMax = 10
+	}
+	if cfg.ForgotPasswordIPRateWindow <= 0 {
+		cfg.ForgotPasswordIPRateWindow = 15 * time.Minute
+	}
+	if cfg.LoginIPRateMax <= 0 {
+		cfg.LoginIPRateMax = 5
+	}
+	if cfg.LoginIPRateWindow <= 0 {
+		cfg.LoginIPRateWindow = time.Minute
+	}
+	if cfg.EmailOTPChallengeTTL <= 0 {
+		cfg.EmailOTPChallengeTTL = 10 * time.Minute
+	}
+	if cfg.EmailOTPLength < 6 || cfg.EmailOTPLength > 8 {
+		cfg.EmailOTPLength = 6
+	}
+	if cfg.EmailOTPExpiry < 5*time.Minute || cfg.EmailOTPExpiry > 10*time.Minute {
+		cfg.EmailOTPExpiry = 10 * time.Minute
+	}
+	if cfg.EmailOTPMaxAttempts < 3 || cfg.EmailOTPMaxAttempts > 5 {
+		cfg.EmailOTPMaxAttempts = 5
+	}
+	if cfg.EmailOTPResendCooldown <= 0 {
+		cfg.EmailOTPResendCooldown = 60 * time.Second
+	}
+	if cfg.EmailOTPMaxResendPerHour <= 0 {
+		cfg.EmailOTPMaxResendPerHour = 5
+	}
+	return cfg
+}
diff --git a/internal/service/auth_service_test.go b/internal/service/auth_service_test.go
new file mode 100644
index 0000000..e92f5b0
--- /dev/null
+++ b/internal/service/auth_service_test.go
@@ -0,0 +1,5617 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"io"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+	"github.com/pquerna/otp/totp"
+
+	"wucher/internal/config"
+	"wucher/internal/domain/auth"
+	"wucher/internal/queue"
+	tzpkg "wucher/internal/shared/pkg/timezone"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type authEmailBrandingResolverMock struct {
+	branding AuthEmailBranding
+}
+
+func (m authEmailBrandingResolverMock) ResolveEmailBranding(context.Context) AuthEmailBranding {
+	return m.branding
+}
+
+type mockTokenStore struct {
+	store    map[string][]byte
+	lastKey  string
+	setErr   error
+	getErr   error
+	setCount int
+	setDelay time.Duration
+}
+
+func newMockTokenStore() *mockTokenStore {
+	return &mockTokenStore{store: map[string][]byte{}}
+}
+
+func (m *mockTokenStore) Set(_ context.Context, key string, value []byte, _ time.Duration) error {
+	if m.setErr != nil {
+		return m.setErr
+	}
+	if m.setDelay > 0 {
+		time.Sleep(m.setDelay)
+	}
+	m.store[key] = value
+	m.lastKey = key
+	m.setCount++
+	return nil
+}
+
+func (m *mockTokenStore) SetIfNotExists(_ context.Context, key string, value []byte, _ time.Duration) (bool, error) {
+	if m.setErr != nil {
+		return false, m.setErr
+	}
+	if _, ok := m.store[key]; ok {
+		return false, nil
+	}
+	m.store[key] = value
+	m.lastKey = key
+	m.setCount++
+	return true, nil
+}
+
+func (m *mockTokenStore) Get(_ context.Context, key string) ([]byte, error) {
+	if m.getErr != nil {
+		return nil, m.getErr
+	}
+	v, ok := m.store[key]
+	if !ok {
+		return nil, nil
+	}
+	return v, nil
+}
+
+func (m *mockTokenStore) Delete(_ context.Context, key string) error {
+	delete(m.store, key)
+	return nil
+}
+
+type mockAuthRepo struct {
+	users                       map[string]*auth.User
+	usersByMail                 map[string]*auth.User
+	usersByUsername             map[string]*auth.User
+	identities                  map[string]*auth.UserIdentity
+	totp                        map[string]*auth.UserTOTP
+	webauthnCredentials         map[string][]auth.UserWebAuthnCredential
+	resetTokens                 map[string]*auth.PasswordResetToken
+	securityPINResetTokens      map[string]*auth.SecurityPINResetToken
+	emailLoginOTPs              map[string]*auth.UserEmailLoginOTP
+	lastResetToken              *auth.PasswordResetToken
+	lastSecurityPINResetToken   *auth.SecurityPINResetToken
+	emailOutboxMessages         []*auth.EmailOutboxMessage
+	lastUpdateTimezoneUserID    []byte
+	lastUpdateTimezone          string
+	createErr                   error
+	getByIDErr                  error
+	getByMailErr                error
+	updateTimezoneErr           error
+	setPasswordErr              error
+	markVerifiedErr             error
+	createResetTokenErr         error
+	invalidateResetTokensErr    error
+	consumeResetErr             error
+	createPINResetTokenErr      error
+	invalidatePINResetTokensErr error
+	consumePINResetErr          error
+	deleteTOTPErr               error
+	deleteWebAuthnErr           error
+	outboxErr                   error
+	msOAuthTokens               map[string]*auth.UserMicrosoftOAuthToken
+}
+
+func newMockAuthRepo() *mockAuthRepo {
+	return &mockAuthRepo{
+		users:                  map[string]*auth.User{},
+		usersByMail:            map[string]*auth.User{},
+		usersByUsername:        map[string]*auth.User{},
+		identities:             map[string]*auth.UserIdentity{},
+		totp:                   map[string]*auth.UserTOTP{},
+		webauthnCredentials:    map[string][]auth.UserWebAuthnCredential{},
+		resetTokens:            map[string]*auth.PasswordResetToken{},
+		securityPINResetTokens: map[string]*auth.SecurityPINResetToken{},
+		emailLoginOTPs:         map[string]*auth.UserEmailLoginOTP{},
+		msOAuthTokens:          map[string]*auth.UserMicrosoftOAuthToken{},
+	}
+}
+
+func (r *mockAuthRepo) CreateUser(_ context.Context, user *auth.User) error {
+	if user == nil {
+		return errors.New("nil user")
+	}
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if !user.IsActive {
+		user.IsActive = true
+	}
+	key := string(user.ID)
+	r.users[key] = user
+	if user.Email != "" {
+		r.usersByMail[user.Email] = user
+	}
+	if user.Username != nil && strings.TrimSpace(*user.Username) != "" {
+		r.usersByUsername[strings.TrimSpace(*user.Username)] = user
+	}
+	return nil
+}
+
+func (r *mockAuthRepo) WithTransaction(ctx context.Context, fn func(repo auth.Repository, outbox auth.EmailOutboxWriter) error) error {
+	if fn == nil {
+		return nil
+	}
+	return fn(r, r)
+}
+
+func (r *mockAuthRepo) CreateEmailOutboxMessage(_ context.Context, message *auth.EmailOutboxMessage) error {
+	if r.outboxErr != nil {
+		return r.outboxErr
+	}
+	if message == nil {
+		return errors.New("nil outbox message")
+	}
+	cp := *message
+	cp.ID = append([]byte(nil), message.ID...)
+	cp.Body = append([]byte(nil), message.Body...)
+	cp.Attributes = append([]byte(nil), message.Attributes...)
+	r.emailOutboxMessages = append(r.emailOutboxMessages, &cp)
+	return nil
+}
+
+func (r *mockAuthRepo) GetUserByID(_ context.Context, id []byte) (*auth.User, error) {
+	if r.getByIDErr != nil {
+		return nil, r.getByIDErr
+	}
+	return r.users[string(id)], nil
+}
+
+func (r *mockAuthRepo) GetUserByEmail(_ context.Context, email string) (*auth.User, error) {
+	if r.getByMailErr != nil {
+		return nil, r.getByMailErr
+	}
+	return r.usersByMail[email], nil
+}
+
+func (r *mockAuthRepo) GetUserBySSOEmail(_ context.Context, ssoEmail string) (*auth.User, error) {
+	if r.getByMailErr != nil {
+		return nil, r.getByMailErr
+	}
+	return r.usersByMail[ssoEmail], nil
+}
+
+func (r *mockAuthRepo) GetUserByUsername(_ context.Context, username string) (*auth.User, error) {
+	if r.getByMailErr != nil {
+		return nil, r.getByMailErr
+	}
+	return r.usersByUsername[username], nil
+}
+
+func (r *mockAuthRepo) UpdateUserTimezone(_ context.Context, id []byte, timezoneName string) error {
+	if r.updateTimezoneErr != nil {
+		return r.updateTimezoneErr
+	}
+	u := r.users[string(id)]
+	if u == nil {
+		return errors.New("not found")
+	}
+	u.Timezone = timezoneName
+	r.lastUpdateTimezoneUserID = append([]byte(nil), id...)
+	r.lastUpdateTimezone = timezoneName
+	return nil
+}
+
+func (r *mockAuthRepo) SetUserPassword(_ context.Context, id []byte, passwordHash, salt []byte) error {
+	if r.setPasswordErr != nil {
+		return r.setPasswordErr
+	}
+	u := r.users[string(id)]
+	if u == nil {
+		return errors.New("not found")
+	}
+	u.PasswordHash = passwordHash
+	u.SaltValue = salt
+	return nil
+}
+
+func (r *mockAuthRepo) SetUserSecurityPIN(_ context.Context, id []byte, pinHash []byte, setAt time.Time) error {
+	u := r.users[string(id)]
+	if u == nil {
+		return errors.New("not found")
+	}
+	u.SecurityPINHash = append([]byte(nil), pinHash...)
+	ts := setAt
+	u.SecurityPINSetAt = &ts
+	return nil
+}
+
+func (r *mockAuthRepo) MarkEmailVerified(_ context.Context, id []byte) error {
+	if r.markVerifiedErr != nil {
+		return r.markVerifiedErr
+	}
+	u := r.users[string(id)]
+	if u == nil {
+		return errors.New("not found")
+	}
+	now := time.Now().UTC()
+	u.EmailVerifiedAt = &now
+	return nil
+}
+
+func (r *mockAuthRepo) CreatePasswordResetToken(_ context.Context, token *auth.PasswordResetToken) error {
+	if r.createResetTokenErr != nil {
+		return r.createResetTokenErr
+	}
+	if token == nil {
+		return errors.New("nil token")
+	}
+	cp := *token
+	if len(cp.ID) == 0 {
+		cp.ID = uuidv7.MustBytes()
+	}
+	r.resetTokens[string(cp.TokenHash)] = &cp
+	r.lastResetToken = &cp
+	return nil
+}
+
+func (r *mockAuthRepo) InvalidateActivePasswordResetTokensByUserID(_ context.Context, userID []byte, usedAt time.Time) error {
+	if r.invalidateResetTokensErr != nil {
+		return r.invalidateResetTokensErr
+	}
+	for _, rec := range r.resetTokens {
+		if string(rec.UserID) == string(userID) && rec.UsedAt == nil && rec.ExpiresAt.After(usedAt) {
+			ts := usedAt
+			rec.UsedAt = &ts
+		}
+	}
+	return nil
+}
+
+func (r *mockAuthRepo) ConsumePasswordResetTokenAndSetPassword(_ context.Context, tokenHash, passwordHash, salt []byte, usedAt time.Time) ([]byte, bool, error) {
+	if r.consumeResetErr != nil {
+		return nil, false, r.consumeResetErr
+	}
+	rec := r.resetTokens[string(tokenHash)]
+	if rec == nil || rec.UsedAt != nil || !rec.ExpiresAt.After(usedAt) {
+		return nil, false, nil
+	}
+	u := r.users[string(rec.UserID)]
+	if u == nil {
+		return nil, false, nil
+	}
+	if r.setPasswordErr != nil {
+		return nil, false, r.setPasswordErr
+	}
+	u.PasswordHash = passwordHash
+	u.SaltValue = salt
+
+	ts := usedAt
+	rec.UsedAt = &ts
+	for _, other := range r.resetTokens {
+		if string(other.UserID) == string(rec.UserID) && string(other.ID) != string(rec.ID) && other.UsedAt == nil && other.ExpiresAt.After(usedAt) {
+			otherTS := usedAt
+			other.UsedAt = &otherTS
+		}
+	}
+	return rec.UserID, true, nil
+}
+
+func (r *mockAuthRepo) CreateSecurityPINResetToken(_ context.Context, token *auth.SecurityPINResetToken) error {
+	if r.createPINResetTokenErr != nil {
+		return r.createPINResetTokenErr
+	}
+	if token == nil {
+		return errors.New("nil token")
+	}
+	cp := *token
+	if len(cp.ID) == 0 {
+		cp.ID = uuidv7.MustBytes()
+	}
+	r.securityPINResetTokens[string(cp.TokenHash)] = &cp
+	r.lastSecurityPINResetToken = &cp
+	return nil
+}
+
+func (r *mockAuthRepo) InvalidateActiveSecurityPINResetTokensByUserID(_ context.Context, userID []byte, usedAt time.Time) error {
+	if r.invalidatePINResetTokensErr != nil {
+		return r.invalidatePINResetTokensErr
+	}
+	for _, rec := range r.securityPINResetTokens {
+		if string(rec.UserID) == string(userID) && rec.UsedAt == nil && rec.ExpiresAt.After(usedAt) {
+			ts := usedAt
+			rec.UsedAt = &ts
+		}
+	}
+	return nil
+}
+
+func (r *mockAuthRepo) GetActiveSecurityPINResetTokenUser(_ context.Context, tokenHash []byte, now time.Time) (*auth.User, error) {
+	rec := r.securityPINResetTokens[string(tokenHash)]
+	if rec == nil || rec.UsedAt != nil || !rec.ExpiresAt.After(now) {
+		return nil, nil
+	}
+	return r.users[string(rec.UserID)], nil
+}
+
+func (r *mockAuthRepo) ConsumeSecurityPINResetTokenAndSetPIN(_ context.Context, tokenHash, pinHash []byte, usedAt time.Time) ([]byte, bool, error) {
+	if r.consumePINResetErr != nil {
+		return nil, false, r.consumePINResetErr
+	}
+	rec := r.securityPINResetTokens[string(tokenHash)]
+	if rec == nil || rec.UsedAt != nil || !rec.ExpiresAt.After(usedAt) {
+		return nil, false, nil
+	}
+	u := r.users[string(rec.UserID)]
+	if u == nil {
+		return nil, false, nil
+	}
+	u.SecurityPINHash = append([]byte(nil), pinHash...)
+	tsSet := usedAt
+	u.SecurityPINSetAt = &tsSet
+
+	ts := usedAt
+	rec.UsedAt = &ts
+	for _, other := range r.securityPINResetTokens {
+		if string(other.UserID) == string(rec.UserID) && string(other.ID) != string(rec.ID) && other.UsedAt == nil && other.ExpiresAt.After(usedAt) {
+			otherTS := usedAt
+			other.UsedAt = &otherTS
+		}
+	}
+	return rec.UserID, true, nil
+}
+
+func (r *mockAuthRepo) UpsertIdentity(_ context.Context, identity *auth.UserIdentity) error {
+	key := identity.Provider + ":" + identity.ProviderSubject
+	r.identities[key] = identity
+	return nil
+}
+
+func (r *mockAuthRepo) CreateIdentity(_ context.Context, identity *auth.UserIdentity) error {
+	key := identity.Provider + ":" + identity.ProviderSubject
+	r.identities[key] = identity
+	return nil
+}
+
+func (r *mockAuthRepo) GetIdentityByProviderSubject(_ context.Context, provider, subject string) (*auth.UserIdentity, error) {
+	return r.identities[provider+":"+subject], nil
+}
+
+func (r *mockAuthRepo) GetIdentityByUserID(_ context.Context, userID []byte) (*auth.UserIdentity, error) {
+	for _, identity := range r.identities {
+		if bytes.Equal(identity.UserID, userID) {
+			return identity, nil
+		}
+	}
+	return nil, nil
+}
+
+func (r *mockAuthRepo) DeleteIdentityByUserIDProvider(_ context.Context, userID []byte, provider string) (bool, error) {
+	for key, identity := range r.identities {
+		if bytes.Equal(identity.UserID, userID) && identity.Provider == provider {
+			delete(r.identities, key)
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+func (r *mockAuthRepo) GetUserTOTP(_ context.Context, userID []byte) (*auth.UserTOTP, error) {
+	return r.totp[string(userID)], nil
+}
+
+func (r *mockAuthRepo) UpsertUserTOTP(_ context.Context, totpRec *auth.UserTOTP) error {
+	r.totp[string(totpRec.UserID)] = totpRec
+	return nil
+}
+
+func (r *mockAuthRepo) DisableUserTOTP(_ context.Context, userID []byte) error {
+	rec := r.totp[string(userID)]
+	if rec == nil {
+		return nil
+	}
+	rec.Enabled = false
+	return nil
+}
+
+func (r *mockAuthRepo) DeleteUserTOTPSetup(_ context.Context, userID []byte) error {
+	if r.deleteTOTPErr != nil {
+		return r.deleteTOTPErr
+	}
+	delete(r.totp, string(userID))
+	return nil
+}
+
+func (r *mockAuthRepo) UpdateUserTOTPLastUsed(_ context.Context, userID []byte) error {
+	rec := r.totp[string(userID)]
+	if rec == nil {
+		return nil
+	}
+	now := time.Now().UTC()
+	rec.LastUsedAt = &now
+	return nil
+}
+
+func (r *mockAuthRepo) GetActiveUserEmailLoginOTP(_ context.Context, userID []byte, now time.Time) (*auth.UserEmailLoginOTP, error) {
+	rec := r.emailLoginOTPs[string(userID)]
+	if rec == nil || rec.UsedAt != nil || !rec.ExpiresAt.After(now) {
+		return nil, nil
+	}
+	return rec, nil
+}
+
+func (r *mockAuthRepo) CountUserEmailLoginOTPSince(_ context.Context, userID []byte, since time.Time) (int64, error) {
+	rec := r.emailLoginOTPs[string(userID)]
+	if rec == nil || rec.CreatedAt.Before(since) {
+		return 0, nil
+	}
+	return 1, nil
+}
+
+func (r *mockAuthRepo) CreateUserEmailLoginOTP(_ context.Context, otp *auth.UserEmailLoginOTP) error {
+	if otp == nil {
+		return errors.New("nil otp")
+	}
+	cp := *otp
+	if len(cp.ID) == 0 {
+		cp.ID = uuidv7.MustBytes()
+	}
+	if cp.CreatedAt.IsZero() {
+		cp.CreatedAt = time.Now().UTC()
+	}
+	r.emailLoginOTPs[string(cp.UserID)] = &cp
+	return nil
+}
+
+func (r *mockAuthRepo) InvalidateActiveUserEmailLoginOTPs(_ context.Context, userID []byte, usedAt time.Time) error {
+	rec := r.emailLoginOTPs[string(userID)]
+	if rec == nil || rec.UsedAt != nil || !rec.ExpiresAt.After(usedAt) {
+		return nil
+	}
+	ts := usedAt
+	rec.UsedAt = &ts
+	return nil
+}
+
+func (r *mockAuthRepo) ConsumeUserEmailLoginOTP(_ context.Context, userID, otpHash []byte, now time.Time) (bool, int, error) {
+	rec := r.emailLoginOTPs[string(userID)]
+	if rec == nil || rec.UsedAt != nil || !rec.ExpiresAt.After(now) {
+		return false, 0, nil
+	}
+	if bytes.Equal(rec.OTPHash, otpHash) {
+		ts := now
+		rec.UsedAt = &ts
+		return true, max(0, rec.MaxAttempts-rec.AttemptCount), nil
+	}
+	rec.AttemptCount++
+	left := max(0, rec.MaxAttempts-rec.AttemptCount)
+	if rec.AttemptCount >= rec.MaxAttempts {
+		ts := now
+		rec.UsedAt = &ts
+	}
+	return false, left, nil
+}
+
+func (r *mockAuthRepo) ListUserWebAuthnCredentials(_ context.Context, userID []byte) ([]auth.UserWebAuthnCredential, error) {
+	list := r.webauthnCredentials[string(userID)]
+	out := make([]auth.UserWebAuthnCredential, len(list))
+	copy(out, list)
+	return out, nil
+}
+
+func (r *mockAuthRepo) CreateUserWebAuthnCredential(_ context.Context, credential *auth.UserWebAuthnCredential) error {
+	if credential == nil {
+		return errors.New("nil credential")
+	}
+	cp := *credential
+	if len(cp.ID) == 0 {
+		cp.ID = uuidv7.MustBytes()
+	}
+	key := string(cp.UserID)
+	r.webauthnCredentials[key] = append(r.webauthnCredentials[key], cp)
+	return nil
+}
+
+func (r *mockAuthRepo) UpdateUserWebAuthnCredential(_ context.Context, userID, credentialID, credentialJSON []byte, usedAt time.Time) error {
+	key := string(userID)
+	list := r.webauthnCredentials[key]
+	for i := range list {
+		if bytes.Equal(list[i].CredentialID, credentialID) {
+			list[i].CredentialJSON = append([]byte(nil), credentialJSON...)
+			ts := usedAt
+			list[i].LastUsedAt = &ts
+			r.webauthnCredentials[key] = list
+			return nil
+		}
+	}
+	return nil
+}
+
+func (r *mockAuthRepo) DeleteAllUserWebAuthnCredentials(_ context.Context, userID []byte) error {
+	if r.deleteWebAuthnErr != nil {
+		return r.deleteWebAuthnErr
+	}
+	delete(r.webauthnCredentials, string(userID))
+	return nil
+}
+
+func (r *mockAuthRepo) UpsertMicrosoftOAuthToken(_ context.Context, token *auth.UserMicrosoftOAuthToken) error {
+	if token == nil {
+		return errors.New("nil microsoft oauth token")
+	}
+	key := string(token.UserID) + ":" + strings.ToLower(strings.TrimSpace(token.Provider))
+	cp := *token
+	cp.UserID = append([]byte(nil), token.UserID...)
+	cp.RefreshTokenEncrypted = append([]byte(nil), token.RefreshTokenEncrypted...)
+	cp.AccessTokenEncrypted = append([]byte(nil), token.AccessTokenEncrypted...)
+	cp.IDTokenEncrypted = append([]byte(nil), token.IDTokenEncrypted...)
+	r.msOAuthTokens[key] = &cp
+	return nil
+}
+
+func (r *mockAuthRepo) GetMicrosoftOAuthTokenByUserIDProvider(_ context.Context, userID []byte, provider string) (*auth.UserMicrosoftOAuthToken, error) {
+	key := string(userID) + ":" + strings.ToLower(strings.TrimSpace(provider))
+	rec := r.msOAuthTokens[key]
+	if rec == nil {
+		return nil, nil
+	}
+	cp := *rec
+	cp.UserID = append([]byte(nil), rec.UserID...)
+	cp.RefreshTokenEncrypted = append([]byte(nil), rec.RefreshTokenEncrypted...)
+	cp.AccessTokenEncrypted = append([]byte(nil), rec.AccessTokenEncrypted...)
+	cp.IDTokenEncrypted = append([]byte(nil), rec.IDTokenEncrypted...)
+	return &cp, nil
+}
+
+func (r *mockAuthRepo) DeleteMicrosoftOAuthTokenByUserIDProvider(_ context.Context, userID []byte, provider string) (bool, error) {
+	key := string(userID) + ":" + strings.ToLower(strings.TrimSpace(provider))
+	if _, ok := r.msOAuthTokens[key]; !ok {
+		return false, nil
+	}
+	delete(r.msOAuthTokens, key)
+	return true, nil
+}
+
+type mockRoleRepo struct {
+	rolesByName                map[string]*auth.Role
+	rolesByID                  map[string]*auth.Role
+	hasRolePermissionRet       bool
+	hasRolePermissionByRole    map[string]bool
+	hasRolePermissionErr       error
+	permissionByKey            map[string]*auth.Permission
+	getPermissionByKeyErr      error
+	updatePermissionErr        error
+	listPermissionsByRoleIDRet []auth.Permission
+	listPermissionsByRole      map[string][]auth.Permission
+	listPermissionsByRoleIDErr error
+}
+
+func newMockRoleRepo() *mockRoleRepo {
+	return &mockRoleRepo{
+		rolesByName:                map[string]*auth.Role{},
+		rolesByID:                  map[string]*auth.Role{},
+		hasRolePermissionRet:       true,
+		hasRolePermissionByRole:    map[string]bool{},
+		permissionByKey:            map[string]*auth.Permission{},
+		listPermissionsByRoleIDRet: []auth.Permission{},
+		listPermissionsByRole:      map[string][]auth.Permission{},
+	}
+}
+
+func (r *mockRoleRepo) CreateRole(_ context.Context, role *auth.Role) error {
+	return nil
+}
+
+func (r *mockRoleRepo) UpdateRole(_ context.Context, role *auth.Role) error {
+	return nil
+}
+
+func (r *mockRoleRepo) DeleteRole(_ context.Context, id []byte) error {
+	return nil
+}
+
+func (r *mockRoleRepo) GetRoleByID(_ context.Context, id []byte) (*auth.Role, error) {
+	return r.rolesByID[string(id)], nil
+}
+
+func (r *mockRoleRepo) GetRoleByName(_ context.Context, name string) (*auth.Role, error) {
+	return r.rolesByName[name], nil
+}
+
+func (r *mockRoleRepo) ListRoles(_ context.Context, _ string, _ string, _ int, _ int) ([]auth.Role, int64, error) {
+	return nil, 0, nil
+}
+func (r *mockRoleRepo) ListPermissions(_ context.Context, _ string, _ string, _ int, _ int) ([]auth.Permission, int64, error) {
+	return nil, 0, nil
+}
+func (r *mockRoleRepo) ListPermissionsByRoleID(_ context.Context, roleID []byte) ([]auth.Permission, error) {
+	if r.listPermissionsByRoleIDErr != nil {
+		return nil, r.listPermissionsByRoleIDErr
+	}
+	if perms, ok := r.listPermissionsByRole[string(roleID)]; ok {
+		return perms, nil
+	}
+	return r.listPermissionsByRoleIDRet, nil
+}
+func (r *mockRoleRepo) HasRolePermission(_ context.Context, roleID []byte, _ string) (bool, error) {
+	if r.hasRolePermissionErr != nil {
+		return false, r.hasRolePermissionErr
+	}
+	if allowed, ok := r.hasRolePermissionByRole[string(roleID)]; ok {
+		return allowed, nil
+	}
+	return r.hasRolePermissionRet, nil
+}
+func (r *mockRoleRepo) GetPermissionByID(_ context.Context, _ []byte) (*auth.Permission, error) {
+	return nil, nil
+}
+func (r *mockRoleRepo) GetPermissionByKey(_ context.Context, key string) (*auth.Permission, error) {
+	if r.getPermissionByKeyErr != nil {
+		return nil, r.getPermissionByKeyErr
+	}
+	return r.permissionByKey[key], nil
+}
+func (r *mockRoleRepo) UpdatePermission(_ context.Context, _ *auth.Permission) error {
+	return r.updatePermissionErr
+}
+func (r *mockRoleRepo) AssignPermission(_ context.Context, roleID, permissionID []byte) (*auth.RolePermission, error) {
+	return &auth.RolePermission{RoleID: roleID, PermissionID: permissionID}, nil
+}
+func (r *mockRoleRepo) RemovePermission(_ context.Context, _ []byte, _ []byte) error { return nil }
+
+type mockEmailQueue struct {
+	last *EmailJob
+	err  error
+}
+
+func (q *mockEmailQueue) Enqueue(_ context.Context, job EmailJob) error {
+	if q.err != nil {
+		return q.err
+	}
+	normalized := job.Canonical()
+	normalized.Body = normalized.TextBody
+	q.last = &normalized
+	return nil
+}
+
+func (q *mockEmailQueue) Dequeue(_ context.Context) (*EmailJob, error) {
+	return nil, nil
+}
+
+func queueTestSerializer() queue.MessageSerializer {
+	return queue.NewJSONSerializer("v1", true, queue.QueueTypeStandard, "")
+}
+
+type errorProtector struct {
+	encryptErr error
+	decryptErr error
+}
+
+func (p *errorProtector) Encrypt(_ []byte) ([]byte, error) {
+	if p.encryptErr != nil {
+		return nil, p.encryptErr
+	}
+	return []byte("cipher"), nil
+}
+
+func (p *errorProtector) Decrypt(_ []byte) ([]byte, error) {
+	if p.decryptErr != nil {
+		return nil, p.decryptErr
+	}
+	return []byte("123456"), nil
+}
+
+func TestAuthService_RegisterAndLogin(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	adminID := uuidv7.MustBytes()
+	roles.rolesByName["admin"] = &auth.Role{ID: adminID, Name: "admin"}
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		EmailVerifyTTL:   time.Hour,
+		EmailVerifyURL:   "http://localhost/verify",
+		SSOStateTTL:      time.Minute,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+		DefaultRoleName:  "admin",
+	}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	user, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", adminID)
+	if err != nil {
+		t.Fatalf("register failed: %v", err)
+	}
+	if user.RoleID == nil || string(user.RoleID) != string(adminID) {
+		t.Fatalf("expected role admin")
+	}
+	if user.Username == nil || *user.Username != "john.doe" {
+		t.Fatalf("expected username john.doe")
+	}
+	if len(user.PasswordHash) == 0 || len(user.SaltValue) == 0 {
+		t.Fatalf("password not hashed")
+	}
+	if user.Timezone != tzpkg.Default {
+		t.Fatalf("expected default timezone %q, got %q", tzpkg.Default, user.Timezone)
+	}
+	if !user.IsActive {
+		t.Fatalf("expected registered user to be active")
+	}
+
+	// not verified yet
+	if _, err := svc.LoginWithEmailPassword(context.Background(), "user@example.com", "Password123!"); err != ErrEmailNotVerified {
+		t.Fatalf("expected ErrEmailNotVerified")
+	}
+
+	// verify email
+	if err := repo.MarkEmailVerified(context.Background(), user.ID); err != nil {
+		t.Fatalf("mark verified: %v", err)
+	}
+
+	if _, err := svc.LoginWithEmailPassword(context.Background(), "user@example.com", "Password123!"); err != nil {
+		t.Fatalf("login failed: %v", err)
+	}
+}
+
+func TestAuthService_Register_ErrorCases(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		PasswordPepper: "pepper",
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	if _, err := svc.RegisterWithEmail(context.Background(), "", "john.doe", "John", "Doe", "", "Password123!", []byte{1}); err == nil {
+		t.Fatalf("expected error for empty email")
+	}
+	if _, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "", []byte{1}); err == nil {
+		t.Fatalf("expected error for empty password")
+	}
+	if _, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "   ", "John", "Doe", "", "Password123!", []byte{1}); err == nil {
+		t.Fatalf("expected error for empty username")
+	}
+}
+
+func TestAuthService_InviteUser(t *testing.T) {
+	t.Run("success normalizes email and stores invite token", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		cfg := config.AuthConfig{
+			InviteTTL:      time.Minute,
+			SetPasswordURL: "http://localhost/set-password",
+		}
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+		roleID := uuidv7.MustBytes()
+		user, err := svc.InviteUser(context.Background(), "  Invitee@Example.COM  ", "invitee", "John", "Doe", "08123", roleID)
+		if err != nil {
+			t.Fatalf("invite failed: %v", err)
+		}
+		if user == nil {
+			t.Fatalf("expected user")
+		}
+		if user.Email != "invitee@example.com" {
+			t.Fatalf("expected normalized email, got %q", user.Email)
+		}
+		if user.Username == nil || *user.Username != "invitee" {
+			t.Fatalf("expected username invitee")
+		}
+		if len(user.PasswordHash) != 0 || len(user.SaltValue) != 0 {
+			t.Fatalf("invite should not set password hash/salt")
+		}
+		if string(user.RoleID) != string(roleID) {
+			t.Fatalf("unexpected role id")
+		}
+		if user.Timezone != tzpkg.Default {
+			t.Fatalf("expected default timezone %q, got %q", tzpkg.Default, user.Timezone)
+		}
+		if tokens.lastKey == "" || !strings.HasPrefix(tokens.lastKey, "auth:invite:") {
+			t.Fatalf("expected invite token stored, got key=%q", tokens.lastKey)
+		}
+		if string(tokens.store[tokens.lastKey]) != string(user.ID) {
+			t.Fatalf("token payload should contain invited user id")
+		}
+		if repo.usersByMail["invitee@example.com"] == nil {
+			t.Fatalf("user should be persisted by normalized email")
+		}
+	})
+
+	t.Run("empty email", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		if _, err := svc.InviteUser(context.Background(), "   ", "invitee", "John", "Doe", "", uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error for empty email")
+		}
+	})
+
+	t.Run("get by email error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.getByMailErr = errors.New("lookup failed")
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		_, err := svc.InviteUser(context.Background(), "invitee@example.com", "invitee", "John", "Doe", "", uuidv7.MustBytes())
+		if !errors.Is(err, repo.getByMailErr) {
+			t.Fatalf("expected get by email error, got %v", err)
+		}
+	})
+
+	t.Run("email already registered", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.usersByMail["invitee@example.com"] = &auth.User{ID: uuidv7.MustBytes(), Email: "invitee@example.com"}
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		if _, err := svc.InviteUser(context.Background(), "INVITEE@EXAMPLE.COM", "invitee", "John", "Doe", "", uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected duplicate email error")
+		}
+		if len(repo.users) != 0 {
+			t.Fatalf("create user should not be called for duplicate email")
+		}
+	})
+
+	t.Run("username already registered", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		username := "invitee"
+		repo.usersByUsername[username] = &auth.User{ID: uuidv7.MustBytes(), Username: &username}
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		if _, err := svc.InviteUser(context.Background(), "invitee@example.com", username, "John", "Doe", "", uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected duplicate username error")
+		}
+	})
+
+	t.Run("create user error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.createErr = errors.New("db error")
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		_, err := svc.InviteUser(context.Background(), "invitee@example.com", "invitee", "John", "Doe", "", uuidv7.MustBytes())
+		if !errors.Is(err, repo.createErr) {
+			t.Fatalf("expected create user error, got %v", err)
+		}
+		if tokens.lastKey != "" {
+			t.Fatalf("invite token should not be stored when create fails")
+		}
+	})
+
+	t.Run("invite token storage error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		tokens.setErr = errors.New("token store error")
+		cfg := config.AuthConfig{
+			InviteTTL:      time.Minute,
+			SetPasswordURL: "http://localhost/set-password",
+		}
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+		_, err := svc.InviteUser(context.Background(), "invitee@example.com", "invitee", "John", "Doe", "", uuidv7.MustBytes())
+		if !errors.Is(err, tokens.setErr) {
+			t.Fatalf("expected token store error, got %v", err)
+		}
+		if repo.usersByMail["invitee@example.com"] != nil {
+			t.Fatalf("user should not be created when invite token generation fails")
+		}
+	})
+}
+
+func TestAuthService_UpdateUserTimezone(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	user := &auth.User{
+		ID:       uuidv7.MustBytes(),
+		Email:    "user@example.com",
+		Timezone: tzpkg.Default,
+	}
+	repo.users[string(user.ID)] = user
+	repo.usersByMail[user.Email] = user
+
+	t.Run("success normalizes timezone", func(t *testing.T) {
+		got, err := svc.UpdateUserTimezone(context.Background(), user.ID, "Asia/Jakarta")
+		if err != nil {
+			t.Fatalf("UpdateUserTimezone failed: %v", err)
+		}
+		if got != "Asia/Jakarta" {
+			t.Fatalf("unexpected normalized timezone: %q", got)
+		}
+		if user.Timezone != "Asia/Jakarta" {
+			t.Fatalf("expected timezone updated on user, got %q", user.Timezone)
+		}
+	})
+
+	t.Run("reject invalid timezone", func(t *testing.T) {
+		_, err := svc.UpdateUserTimezone(context.Background(), user.ID, "UTC+7")
+		if !errors.Is(err, tzpkg.ErrInvalid) {
+			t.Fatalf("expected invalid timezone error, got %v", err)
+		}
+	})
+
+	t.Run("reject empty timezone", func(t *testing.T) {
+		_, err := svc.UpdateUserTimezone(context.Background(), user.ID, "   ")
+		if !errors.Is(err, tzpkg.ErrEmpty) {
+			t.Fatalf("expected empty timezone error, got %v", err)
+		}
+	})
+
+	t.Run("reject empty user id", func(t *testing.T) {
+		_, err := svc.UpdateUserTimezone(context.Background(), nil, "Asia/Jakarta")
+		if err == nil {
+			t.Fatalf("expected error for empty user id")
+		}
+	})
+
+	t.Run("repo update timezone error", func(t *testing.T) {
+		repo.updateTimezoneErr = errors.New("update failed")
+		_, err := svc.UpdateUserTimezone(context.Background(), user.ID, "Asia/Jakarta")
+		if !errors.Is(err, repo.updateTimezoneErr) {
+			t.Fatalf("expected update timezone error, got %v", err)
+		}
+	})
+}
+
+func TestAuthService_SetPasswordWithInviteToken(t *testing.T) {
+	baseCfg := config.AuthConfig{
+		PasswordPepper: "pepper",
+		HashTime:       1,
+		HashMemoryKB:   64 * 1024,
+		HashThreads:    4,
+		HashKeyLen:     32,
+	}
+
+	t.Run("success sets password verifies email and consumes token", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		user := &auth.User{ID: uuidv7.MustBytes(), Email: "invitee@example.com"}
+		repo.users[string(user.ID)] = user
+		token := "invite-token"
+		key := inviteKey(token)
+		tokens.store[key] = user.ID
+
+		if err := svc.SetPasswordWithInviteToken(context.Background(), token, "Password123!"); err != nil {
+			t.Fatalf("set password failed: %v", err)
+		}
+		if len(user.PasswordHash) == 0 || len(user.SaltValue) == 0 {
+			t.Fatalf("expected password hash and salt to be stored")
+		}
+		if user.EmailVerifiedAt == nil {
+			t.Fatalf("expected invited user email to be marked verified")
+		}
+		if _, ok := tokens.store[key]; ok {
+			t.Fatalf("invite token should be deleted after success")
+		}
+	})
+
+	t.Run("token and password are required", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		if err := svc.SetPasswordWithInviteToken(context.Background(), "", "Password123!"); err == nil {
+			t.Fatalf("expected error for empty token")
+		}
+		if err := svc.SetPasswordWithInviteToken(context.Background(), "token", ""); err == nil {
+			t.Fatalf("expected error for empty password")
+		}
+	})
+
+	t.Run("token store not configured", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+		if err := svc.SetPasswordWithInviteToken(context.Background(), "token", "Password123!"); err != ErrInvalidToken {
+			t.Fatalf("expected ErrInvalidToken, got %v", err)
+		}
+	})
+
+	t.Run("invalid invite token from store error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		tokens.getErr = errors.New("token store get failed")
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+		if err := svc.SetPasswordWithInviteToken(context.Background(), "token", "Password123!"); err != ErrInvalidToken {
+			t.Fatalf("expected ErrInvalidToken, got %v", err)
+		}
+	})
+
+	t.Run("invalid invite token payload length", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		tokens.store[inviteKey("token")] = []byte("short")
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+		if err := svc.SetPasswordWithInviteToken(context.Background(), "token", "Password123!"); err != ErrInvalidToken {
+			t.Fatalf("expected ErrInvalidToken, got %v", err)
+		}
+	})
+
+	t.Run("set password repo error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		tokens.store[inviteKey("token")] = uuidv7.MustBytes()
+		if err := svc.SetPasswordWithInviteToken(context.Background(), "token", "Password123!"); err == nil {
+			t.Fatalf("expected set password error")
+		}
+	})
+
+	t.Run("mark email verified error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.markVerifiedErr = errors.New("mark verify failed")
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		user := &auth.User{ID: uuidv7.MustBytes(), Email: "invitee@example.com"}
+		repo.users[string(user.ID)] = user
+		key := inviteKey("token")
+		tokens.store[key] = user.ID
+
+		if err := svc.SetPasswordWithInviteToken(context.Background(), "token", "Password123!"); !errors.Is(err, repo.markVerifiedErr) {
+			t.Fatalf("expected mark verify error, got %v", err)
+		}
+		if _, ok := tokens.store[key]; !ok {
+			t.Fatalf("token should remain when mark email verified fails")
+		}
+	})
+
+	t.Run("jwt invite success", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		cfg := baseCfg
+		cfg.JWTAccessSecret = "access"
+		cfg.InviteTTL = time.Minute
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+		user := &auth.User{ID: uuidv7.MustBytes(), Email: "invitee@example.com"}
+		repo.users[string(user.ID)] = user
+		repo.usersByMail[user.Email] = user
+
+		token, jti, err := svc.issueInviteJWT(user)
+		if err != nil {
+			t.Fatalf("issue invite jwt: %v", err)
+		}
+		tokens.store[inviteKey(jti)] = user.ID
+
+		if err := svc.SetPasswordWithInviteToken(context.Background(), token, "Password123!"); err != nil {
+			t.Fatalf("set password with jwt invite failed: %v", err)
+		}
+		if len(user.PasswordHash) == 0 || user.EmailVerifiedAt == nil {
+			t.Fatalf("expected password and email verification updated")
+		}
+		if _, ok := tokens.store[inviteKey(jti)]; ok {
+			t.Fatalf("jwt invite token should be deleted after success")
+		}
+	})
+
+	t.Run("jwt invite token store mismatch", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		cfg := baseCfg
+		cfg.JWTAccessSecret = "access"
+		cfg.InviteTTL = time.Minute
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+		user := &auth.User{ID: uuidv7.MustBytes(), Email: "invitee@example.com"}
+		repo.users[string(user.ID)] = user
+		token, jti, err := svc.issueInviteJWT(user)
+		if err != nil {
+			t.Fatalf("issue invite jwt: %v", err)
+		}
+		tokens.store[inviteKey(jti)] = uuidv7.MustBytes()
+
+		if err := svc.SetPasswordWithInviteToken(context.Background(), token, "Password123!"); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token on jwt store mismatch, got %v", err)
+		}
+	})
+}
+
+func TestAuthServiceDurationGetters(t *testing.T) {
+	cfg := config.AuthConfig{
+		JWTRefreshTOTPTTL:         2 * time.Hour,
+		SecurityPINActionTokenTTL: 15 * time.Minute,
+	}
+	svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), newMockTokenStore(), nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if svc.RefreshTOTPTTL() != 2*time.Hour {
+		t.Fatalf("expected RefreshTOTPTTL getter to return configured ttl")
+	}
+	if svc.SecurityPINTokenTTL() != 15*time.Minute {
+		t.Fatalf("expected SecurityPINTokenTTL getter to return configured ttl")
+	}
+}
+
+func TestAuthService_GetRoleIDByName_NotFound(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	if _, err := svc.GetRoleIDByName(context.Background(), "missing"); err == nil {
+		t.Fatalf("expected error when role not found")
+	}
+}
+
+func TestAuthService_Login_InvalidPassword(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	roles.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+
+	cfg := config.AuthConfig{
+		PasswordPepper:  "pepper",
+		HashTime:        1,
+		HashMemoryKB:    64 * 1024,
+		HashThreads:     4,
+		HashKeyLen:      32,
+		DefaultRoleName: "admin",
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user, _ := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+	repo.MarkEmailVerified(context.Background(), user.ID)
+
+	if _, err := svc.LoginWithEmailPassword(context.Background(), "user@example.com", "WrongPass"); err != ErrInvalidCredentials {
+		t.Fatalf("expected invalid credentials")
+	}
+}
+
+func TestAuthService_IssueTokens_ConfigMissing(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	repo.CreateUser(context.Background(), user)
+	if _, err := svc.IssueTokens(context.Background(), user); err == nil {
+		t.Fatalf("expected error without jwt secrets")
+	}
+}
+
+func TestAuthService_Register_CreateUserError(t *testing.T) {
+	repo := newMockAuthRepo()
+	repo.createErr = errors.New("db error")
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	adminID := uuidv7.MustBytes()
+	roles.rolesByName["admin"] = &auth.Role{ID: adminID, Name: "admin"}
+
+	cfg := config.AuthConfig{
+		PasswordPepper:  "pepper",
+		HashTime:        1,
+		HashMemoryKB:    64 * 1024,
+		HashThreads:     4,
+		HashKeyLen:      32,
+		DefaultRoleName: "admin",
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if _, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", adminID); err == nil {
+		t.Fatalf("expected create user error")
+	}
+}
+
+func TestAuthService_Login_UserNotFound(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if _, err := svc.LoginWithEmailPassword(context.Background(), "missing@example.com", "pass"); err != ErrInvalidCredentials {
+		t.Fatalf("expected invalid credentials")
+	}
+}
+
+func TestAuthService_Login_InactiveUser(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{
+		PasswordPepper: "pepper",
+		HashTime:       1,
+		HashMemoryKB:   64 * 1024,
+		HashThreads:    4,
+		HashKeyLen:     32,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	user := &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "inactive@example.com",
+		FirstName: "Jane",
+		LastName:  "Doe",
+		RoleID:    uuidv7.MustBytes(),
+		IsActive:  true,
+	}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	hash, salt, err := svc.hashPassword("Password123!")
+	if err != nil {
+		t.Fatalf("hash password: %v", err)
+	}
+	user.PasswordHash = hash
+	user.SaltValue = salt
+	now := time.Now().UTC()
+	user.EmailVerifiedAt = &now
+	user.IsActive = false
+
+	if _, err := svc.LoginWithEmailPassword(context.Background(), user.Email, "Password123!"); err != ErrInvalidCredentials {
+		t.Fatalf("expected invalid credentials for inactive user, got %v", err)
+	}
+}
+
+func TestAuthService_ParseAccessToken_Invalid(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{JWTAccessSecret: "access"}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	if _, err := svc.ParseAccessToken(context.Background(), "bad"); err == nil {
+		t.Fatalf("expected invalid token error")
+	}
+}
+
+func TestAuthService_ParseAccessToken_WrongType(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	repo.CreateUser(context.Background(), user)
+	pair, _ := svc.IssueTokens(context.Background(), user)
+
+	if _, err := svc.ParseAccessToken(context.Background(), pair.RefreshToken); err == nil {
+		t.Fatalf("expected invalid token type")
+	}
+}
+
+func TestAuthService_ParseAccessToken_Empty(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{JWTAccessSecret: "access"}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if _, err := svc.ParseAccessToken(context.Background(), ""); err == nil {
+		t.Fatalf("expected error for empty token")
+	}
+}
+
+func TestAuthService_CreateConsumeTOTPChallenge_Invalid(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	if _, err := svc.ConsumeTOTPChallenge(context.Background(), "missing"); err == nil {
+		t.Fatalf("expected invalid challenge")
+	}
+}
+
+func TestAuthService_CreateTOTPChallenge_TokenStoreError(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	tokens.setErr = errors.New("store error")
+	cfg := config.AuthConfig{TOTPChallengeTTL: time.Minute}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if _, err := svc.CreateTOTPChallenge(context.Background(), uuidv7.MustBytes()); err == nil {
+		t.Fatalf("expected token store error")
+	}
+}
+
+func TestAuthService_IsTOTPEnabled_NoRecord(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	enabled, err := svc.IsTOTPEnabled(context.Background(), uuidv7.MustBytes())
+	if err != nil || enabled {
+		t.Fatalf("expected disabled without error")
+	}
+}
+
+func TestAuthService_VerifyEmail_InvalidToken(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	if err := svc.VerifyEmail(context.Background(), "bad"); err == nil {
+		t.Fatalf("expected invalid token")
+	}
+}
+
+func TestAuthService_VerifyEmail_NoTokenStore(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	cfg := config.AuthConfig{}
+	svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if err := svc.VerifyEmail(context.Background(), "token"); err == nil {
+		t.Fatalf("expected invalid token without store")
+	}
+}
+
+func TestAuthService_VerifyEmail_EmptyToken(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	if err := svc.VerifyEmail(context.Background(), ""); err == nil {
+		t.Fatalf("expected invalid token")
+	}
+}
+
+func TestAuthService_SSOConfigMissing(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	if _, err := svc.BeginMicrosoftLogin(context.Background()); err == nil {
+		t.Fatalf("expected sso not configured")
+	}
+}
+
+func TestAuthService_BeginMicrosoftLogin_NoTokenStore(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub", Email: "u@e.com", Name: "Jane"}}
+
+	cfg := config.AuthConfig{SSOStateTTL: time.Minute}
+	svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+	if _, err := svc.BeginMicrosoftLogin(context.Background()); err == nil {
+		t.Fatalf("expected error without token store")
+	}
+}
+
+func TestAuthService_CompleteMicrosoftLogin_SSOServerError(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	sso := &mockSSO{err: errors.New("exchange failed")}
+
+	cfg := config.AuthConfig{SSOStateTTL: time.Minute}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+	state := "state1"
+	_ = tokens.Set(context.Background(), "auth:sso_state:"+state, []byte("1"), time.Minute)
+	if _, _, err := svc.CompleteMicrosoftLogin(context.Background(), "code", state); err == nil {
+		t.Fatalf("expected exchange error")
+	}
+}
+
+func TestAuthService_CompleteMicrosoftLogin_ConsumesStateOnFailure(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub", Email: "u@e.com", Name: "Jane"}}
+
+	cfg := config.AuthConfig{SSOStateTTL: time.Minute}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+	state := "state1"
+	_ = tokens.Set(context.Background(), "auth:sso_state:"+state, []byte("1"), time.Minute)
+	if _, _, err := svc.CompleteMicrosoftLogin(context.Background(), "code", state); !errors.Is(err, ErrSSONotLinked) {
+		t.Fatalf("expected ErrSSONotLinked, got %v", err)
+	}
+	if _, ok := tokens.store["auth:sso_state:"+state]; ok {
+		t.Fatalf("expected state token to be consumed on failure")
+	}
+}
+
+func TestAuthService_LoginWithMicrosoft_EmailNotFound(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub", Email: "u@e.com", Name: "Jane"}}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: config.AuthConfig{}})
+	if _, _, err := svc.LoginWithMicrosoft(context.Background(), "code"); !errors.Is(err, ErrSSONotLinked) {
+		t.Fatalf("expected ErrSSONotLinked, got %v", err)
+	}
+}
+
+func TestAuthService_BeginMicrosoftLogin_TokenStoreError(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	tokens.setErr = errors.New("store error")
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub", Email: "u@e.com", Name: "Jane"}}
+
+	cfg := config.AuthConfig{SSOStateTTL: time.Minute}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+	if _, err := svc.BeginMicrosoftLogin(context.Background()); err == nil {
+		t.Fatalf("expected token store error")
+	}
+}
+
+func TestAuthService_BeginMicrosoftSessionCheck(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	sso := &mockSSO{authURL: "http://example.com?state=%s&prompt=select_account"}
+
+	cfg := config.AuthConfig{SSOStateTTL: time.Minute}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+	urlStr, err := svc.BeginMicrosoftSessionCheck(context.Background())
+	if err != nil {
+		t.Fatalf("begin microsoft session check: %v", err)
+	}
+	if !strings.Contains(urlStr, "prompt=none") {
+		t.Fatalf("expected prompt=none in url, got %s", urlStr)
+	}
+	if !strings.HasPrefix(tokens.lastKey, "auth:sso_state:") {
+		t.Fatalf("expected sso state stored, got key %s", tokens.lastKey)
+	}
+	state := strings.TrimPrefix(tokens.lastKey, "auth:sso_state:")
+	if state == "" {
+		t.Fatalf("expected state in key")
+	}
+	mode, err := svc.MicrosoftStateMode(context.Background(), state)
+	if err != nil {
+		t.Fatalf("microsoft state mode: %v", err)
+	}
+	if mode != "login_check" {
+		t.Fatalf("expected login_check mode, got %s", mode)
+	}
+}
+
+func TestAuthService_BeginMicrosoftLogin_UsesPromptSelectAccount(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	sso := &mockSSO{authURL: "http://example.com?state=%s&prompt=select_account"}
+
+	cfg := config.AuthConfig{SSOStateTTL: time.Minute}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+	urlStr, err := svc.BeginMicrosoftLogin(context.Background())
+	if err != nil {
+		t.Fatalf("begin microsoft login: %v", err)
+	}
+	if !strings.Contains(urlStr, "prompt=select_account") {
+		t.Fatalf("expected prompt=select_account in url, got %s", urlStr)
+	}
+}
+
+func TestAuthService_CompleteMicrosoftLogin_StateNotFound(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub", Email: "u@e.com", Name: "Jane"}}
+
+	cfg := config.AuthConfig{SSOStateTTL: time.Minute}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+	if _, _, err := svc.CompleteMicrosoftLogin(context.Background(), "code", "missing"); !errors.Is(err, ErrInvalidSSOState) {
+		t.Fatalf("expected ErrInvalidSSOState, got %v", err)
+	}
+}
+
+func TestAuthService_CompleteMicrosoftLogin_InvalidState(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub", Email: "u@e.com", Name: "Jane"}}
+
+	cfg := config.AuthConfig{SSOStateTTL: time.Minute}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+	if _, _, err := svc.CompleteMicrosoftLogin(context.Background(), "code", ""); !errors.Is(err, ErrInvalidSSOState) {
+		t.Fatalf("expected ErrInvalidSSOState, got %v", err)
+	}
+}
+
+func TestAuthService_LoginWithMicrosoft_ExistingIdentity(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	existing := &auth.UserIdentity{
+		ID:              uuidv7.MustBytes(),
+		UserID:          uuidv7.MustBytes(),
+		Provider:        "microsoft",
+		ProviderSubject: "sub",
+		Email:           "user@example.com",
+	}
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       existing.UserID,
+		Email:    "user@example.com",
+		RoleID:   roleID,
+		Timezone: tzpkg.WithDefault(""),
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	repo.UpsertIdentity(context.Background(), existing)
+
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane Doe"}}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: config.AuthConfig{}})
+
+	identity, _, err := svc.LoginWithMicrosoft(context.Background(), "code")
+	if err != nil || identity == nil {
+		t.Fatalf("expected existing identity")
+	}
+	if string(identity.UserID) != string(existing.UserID) {
+		t.Fatalf("should return existing identity")
+	}
+}
+
+func TestAuthService_LoginWithMicrosoft_MatchesUserByEmailAndCreatesIdentity(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       userID,
+		Email:    "marco@micro.com",
+		RoleID:   roleID,
+		Timezone: tzpkg.WithDefault(""),
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub-new", Email: "marco@micro.com", Name: "Marco"}}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: config.AuthConfig{}})
+
+	identity, _, err := svc.LoginWithMicrosoft(context.Background(), "code")
+	if err != nil || identity == nil {
+		t.Fatalf("expected identity, got err=%v", err)
+	}
+	if string(identity.UserID) != string(userID) {
+		t.Fatalf("expected login matched by email to existing user")
+	}
+	saved, _ := repo.GetIdentityByProviderSubject(context.Background(), "microsoft", "sub-new")
+	if saved == nil || string(saved.UserID) != string(userID) {
+		t.Fatalf("expected identity to be upserted")
+	}
+}
+
+func TestAuthService_LoginWithMicrosoft_RejectsSubjectLinkedToAnotherUser(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+	otherUserID := uuidv7.MustBytes()
+	_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "marco@micro.com", RoleID: roleID, Timezone: tzpkg.WithDefault("")})
+	_ = repo.CreateUser(context.Background(), &auth.User{ID: otherUserID, Email: "other@micro.com", RoleID: roleID, Timezone: tzpkg.WithDefault("")})
+	_ = repo.CreateIdentity(context.Background(), &auth.UserIdentity{
+		ID:              uuidv7.MustBytes(),
+		UserID:          otherUserID,
+		Provider:        "microsoft",
+		ProviderSubject: "sub-conflict",
+		Email:           "other@micro.com",
+	})
+
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub-conflict", Email: "marco@micro.com", Name: "Marco"}}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: config.AuthConfig{}})
+
+	if _, _, err := svc.LoginWithMicrosoft(context.Background(), "code"); !errors.Is(err, ErrSSOLinkedToAnotherUser) {
+		t.Fatalf("expected ErrSSOLinkedToAnotherUser, got %v", err)
+	}
+}
+
+func TestAuthService_SSORedirectGetter(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{SSOSuccessRedirectURL: "http://localhost/cb"}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if svc.SSOSuccessRedirectURL() == "" {
+		t.Fatalf("expected redirect url")
+	}
+}
+
+func TestAuthService_MicrosoftLogoutURL(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{SSOSuccessRedirectURL: "http://localhost/after-logout"}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: &mockSSO{}, Protector: nil, Config: cfg})
+	got := svc.MicrosoftLogoutURL()
+	if !strings.Contains(got, "http://example.com/logout") || !strings.Contains(got, "post_logout_redirect_uri=") {
+		t.Fatalf("unexpected microsoft logout url: %q", got)
+	}
+}
+
+func TestAuthService_ConfirmTOTP_InvalidCode(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	cfg := config.AuthConfig{TOTPIssuer: "Wucher"}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+
+	userID := uuidv7.MustBytes()
+	_, _, _, _ = svc.SetupTOTP(context.Background(), userID, "user@example.com")
+	ok, err := svc.ConfirmTOTP(context.Background(), userID, "000000")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if ok {
+		t.Fatalf("expected confirm false")
+	}
+}
+
+func TestAuthService_ConfirmTOTP_NoRecord(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if ok, err := svc.ConfirmTOTP(context.Background(), uuidv7.MustBytes(), "123456"); err == nil || ok {
+		t.Fatalf("expected error when record missing")
+	}
+}
+
+func TestAuthService_SetupTOTP_NoProtector(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if _, _, _, err := svc.SetupTOTP(context.Background(), uuidv7.MustBytes(), "user@example.com"); err == nil {
+		t.Fatalf("expected error without protector")
+	}
+}
+
+func TestAuthService_EmailQueuePath(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	queue := &mockEmailQueue{}
+
+	adminID := uuidv7.MustBytes()
+	roles.rolesByName["admin"] = &auth.Role{ID: adminID, Name: "admin"}
+
+	cfg := config.AuthConfig{
+		PasswordPepper:  "pepper",
+		HashTime:        1,
+		HashMemoryKB:    64 * 1024,
+		HashThreads:     4,
+		HashKeyLen:      32,
+		EmailVerifyURL:  "http://localhost/verify",
+		EmailVerifyTTL:  time.Minute,
+		DefaultRoleName: "admin",
+	}
+	svc := NewAuthService(repo, roles, tokens, queue, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	_, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", adminID)
+	if err != nil {
+		t.Fatalf("register failed: %v", err)
+	}
+	if queue.last == nil {
+		t.Fatalf("expected email queued")
+	}
+}
+
+func TestAuthService_RegisterWithEmail_OutboxPath(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	queue := &mockEmailQueue{err: errors.New("queue failed")}
+
+	adminID := uuidv7.MustBytes()
+	roles.rolesByName["admin"] = &auth.Role{ID: adminID, Name: "admin"}
+
+	cfg := config.AuthConfig{
+		PasswordPepper:  "pepper",
+		HashTime:        1,
+		HashMemoryKB:    64 * 1024,
+		HashThreads:     4,
+		HashKeyLen:      32,
+		EmailVerifyURL:  "http://localhost/verify",
+		EmailVerifyTTL:  time.Minute,
+		DefaultRoleName: "admin",
+	}
+	svc := NewAuthService(repo, roles, tokens, queue, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	svc.SetEmailOutbox(repo, queueTestSerializer())
+
+	user, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", adminID)
+	if err != nil {
+		t.Fatalf("register failed: %v", err)
+	}
+	if user == nil {
+		t.Fatalf("expected user")
+	}
+	if queue.last != nil {
+		t.Fatalf("direct queue should not be used when outbox is configured")
+	}
+	if len(repo.emailOutboxMessages) != 1 {
+		t.Fatalf("expected one outbox message, got %d", len(repo.emailOutboxMessages))
+	}
+}
+
+func TestAuthService_LegacyConstructorWithoutQueue(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	adminID := uuidv7.MustBytes()
+	roles.rolesByName["admin"] = &auth.Role{ID: adminID, Name: "admin"}
+
+	cfg := config.AuthConfig{
+		PasswordPepper:  "pepper",
+		HashTime:        1,
+		HashMemoryKB:    64 * 1024,
+		HashThreads:     4,
+		HashKeyLen:      32,
+		EmailVerifyURL:  "http://localhost/verify",
+		EmailVerifyTTL:  time.Minute,
+		DefaultRoleName: "admin",
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", adminID)
+	if err != nil {
+		t.Fatalf("register failed: %v", err)
+	}
+	if user == nil {
+		t.Fatalf("expected registered user")
+	}
+}
+
+func TestAuthService_GetRoleByID_NoRepo(t *testing.T) {
+	repo := newMockAuthRepo()
+	tokens := newMockTokenStore()
+	svc := NewAuthService(repo, nil, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	if _, err := svc.GetRoleByID(context.Background(), uuidv7.MustBytes()); err == nil {
+		t.Fatalf("expected error when role repo nil")
+	}
+}
+
+func TestAuthService_HasPermission(t *testing.T) {
+	t.Run("auth repo not configured", func(t *testing.T) {
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(nil, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if allowed, err := svc.HasPermission(context.Background(), uuidv7.MustBytes(), "users.read"); err == nil || allowed {
+			t.Fatalf("expected auth repo not configured error")
+		}
+	})
+
+	t.Run("role repo not configured", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, nil, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if allowed, err := svc.HasPermission(context.Background(), uuidv7.MustBytes(), "users.read"); err == nil || allowed {
+			t.Fatalf("expected role repo not configured error")
+		}
+	})
+
+	t.Run("get user error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.getByIDErr = errors.New("db error")
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		_, err := svc.HasPermission(context.Background(), uuidv7.MustBytes(), "users.read")
+		if !errors.Is(err, repo.getByIDErr) {
+			t.Fatalf("expected get user error, got %v", err)
+		}
+	})
+
+	t.Run("user not found", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		roles.hasRolePermissionErr = errors.New("should not be called")
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		allowed, err := svc.HasPermission(context.Background(), uuidv7.MustBytes(), "users.read")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if allowed {
+			t.Fatalf("expected no permission when user not found")
+		}
+	})
+
+	t.Run("delegates to role repo", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		userID := uuidv7.MustBytes()
+		roleID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID}
+
+		roles := newMockRoleRepo()
+		roles.hasRolePermissionRet = true
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		allowed, err := svc.HasPermission(context.Background(), userID, "users.read")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if !allowed {
+			t.Fatalf("expected permission allowed")
+		}
+	})
+
+	t.Run("role repo returns error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		userID := uuidv7.MustBytes()
+		roleID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID}
+
+		roles := newMockRoleRepo()
+		roles.hasRolePermissionErr = errors.New("role repo error")
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		if _, err := svc.HasPermission(context.Background(), userID, "users.read"); !errors.Is(err, roles.hasRolePermissionErr) {
+			t.Fatalf("expected role repo error, got %v", err)
+		}
+	})
+
+	t.Run("allows permission from additional role", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		userID := uuidv7.MustBytes()
+		primaryRoleID := uuidv7.MustBytes()
+		extraRoleID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{
+			ID:      userID,
+			RoleID:  primaryRoleID,
+			RoleIDs: [][]byte{primaryRoleID, extraRoleID},
+		}
+
+		roles := newMockRoleRepo()
+		roles.hasRolePermissionByRole[string(primaryRoleID)] = false
+		roles.hasRolePermissionByRole[string(extraRoleID)] = true
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		allowed, err := svc.HasPermission(context.Background(), userID, "users.read")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if !allowed {
+			t.Fatalf("expected permission allowed from additional role")
+		}
+	})
+}
+
+func TestAuthService_GetPermissionsByRoleID(t *testing.T) {
+	t.Run("role repo not configured", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, nil, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if _, err := svc.GetPermissionsByRoleID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected role repo not configured error")
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		roles.listPermissionsByRoleIDRet = []auth.Permission{
+			{
+				ID:   uuidv7.MustBytes(),
+				Name: "Users Read",
+				Key:  "users.read",
+			},
+		}
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		perms, err := svc.GetPermissionsByRoleID(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(perms) != 1 || perms[0].Key != "users.read" {
+			t.Fatalf("unexpected permissions result: %+v", perms)
+		}
+	})
+
+	t.Run("role repo error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		roles.listPermissionsByRoleIDErr = errors.New("list permissions error")
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		if _, err := svc.GetPermissionsByRoleID(context.Background(), uuidv7.MustBytes()); !errors.Is(err, roles.listPermissionsByRoleIDErr) {
+			t.Fatalf("expected list permissions error, got %v", err)
+		}
+	})
+}
+
+func TestAuthService_GetPermissionsByUserID(t *testing.T) {
+	t.Run("auth repo not configured", func(t *testing.T) {
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(nil, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if _, err := svc.GetPermissionsByUserID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected auth repo not configured error")
+		}
+	})
+
+	t.Run("role repo not configured", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, nil, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if _, err := svc.GetPermissionsByUserID(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected role repo not configured error")
+		}
+	})
+
+	t.Run("deduplicates permissions across roles", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		userID := uuidv7.MustBytes()
+		primaryRoleID := uuidv7.MustBytes()
+		extraRoleID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{
+			ID:      userID,
+			RoleID:  primaryRoleID,
+			RoleIDs: [][]byte{primaryRoleID, extraRoleID},
+		}
+
+		readPerm := auth.Permission{ID: uuidv7.MustBytes(), Name: "Read User", Key: "user.read"}
+		updatePerm := auth.Permission{ID: uuidv7.MustBytes(), Name: "Update User", Key: "user.update"}
+
+		roles := newMockRoleRepo()
+		roles.listPermissionsByRole[string(primaryRoleID)] = []auth.Permission{readPerm}
+		roles.listPermissionsByRole[string(extraRoleID)] = []auth.Permission{readPerm, updatePerm}
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		perms, err := svc.GetPermissionsByUserID(context.Background(), userID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(perms) != 2 {
+			t.Fatalf("expected 2 merged permissions, got %d", len(perms))
+		}
+		if perms[0].Key != "user.read" || perms[1].Key != "user.update" {
+			t.Fatalf("unexpected permissions order/content: %+v", perms)
+		}
+	})
+
+	t.Run("role repo error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		userID := uuidv7.MustBytes()
+		roleID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID, RoleIDs: [][]byte{roleID}}
+
+		roles := newMockRoleRepo()
+		roles.listPermissionsByRoleIDErr = errors.New("list permissions error")
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		if _, err := svc.GetPermissionsByUserID(context.Background(), userID); !errors.Is(err, roles.listPermissionsByRoleIDErr) {
+			t.Fatalf("expected list permissions error, got %v", err)
+		}
+	})
+}
+
+func TestAuthService_CreateChallenge_NoTokenStore(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	if _, err := svc.CreateTOTPChallenge(context.Background(), uuidv7.MustBytes()); err == nil {
+		t.Fatalf("expected error when token store nil")
+	}
+}
+
+func TestAuthService_SplitName(t *testing.T) {
+	if a, b := splitName(""); a != "User" || b != "" {
+		t.Fatalf("unexpected split for empty")
+	}
+	if a, b := splitName("John"); a != "John" || b != "" {
+		t.Fatalf("unexpected split for single")
+	}
+	if a, b := splitName("John Doe"); a != "John" || b != "Doe" {
+		t.Fatalf("unexpected split for two")
+	}
+}
+func TestAuthService_TOTPFlow(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, err := NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+	if err != nil {
+		t.Fatalf("protector: %v", err)
+	}
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+		TOTPChallengeTTL: time.Minute,
+		TOTPIssuer:       "Wucher",
+	}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+
+	userID := uuidv7.MustBytes()
+	secret, _, _, err := svc.SetupTOTP(context.Background(), userID, "user@example.com")
+	if err != nil {
+		t.Fatalf("setup totp: %v", err)
+	}
+
+	code, err := totp.GenerateCode(secret, time.Now().UTC())
+	if err != nil {
+		t.Fatalf("generate code: %v", err)
+	}
+	ok, err := svc.ConfirmTOTP(context.Background(), userID, code)
+	if err != nil || !ok {
+		t.Fatalf("confirm totp failed")
+	}
+
+	enabled, _ := svc.IsTOTPEnabled(context.Background(), userID)
+	if !enabled {
+		t.Fatalf("expected totp enabled")
+	}
+}
+
+func TestAuthService_TOTPChallenge_InvalidEmpty(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if _, err := svc.ConsumeTOTPChallenge(context.Background(), ""); err == nil {
+		t.Fatalf("expected error for empty challenge")
+	}
+}
+
+func TestAuthService_TOTPChallenge_RetryAndAttemptLimit(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{TOTPChallengeTTL: time.Minute}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	userID := uuidv7.MustBytes()
+	token, err := svc.CreateTOTPChallenge(context.Background(), userID)
+	if err != nil {
+		t.Fatalf("create challenge failed: %v", err)
+	}
+
+	got, err := svc.ResolveTOTPChallenge(context.Background(), token)
+	if err != nil || string(got) != string(userID) {
+		t.Fatalf("resolve challenge failed: %v", err)
+	}
+
+	for i := 1; i < svc.TOTPChallengeMaxAttempts(); i++ {
+		remaining, regErr := svc.RegisterFailedTOTPChallengeAttempt(context.Background(), token)
+		if regErr != nil {
+			t.Fatalf("unexpected attempt err at #%d: %v", i, regErr)
+		}
+		if remaining != svc.TOTPChallengeMaxAttempts()-i {
+			t.Fatalf("unexpected remaining attempts at #%d: got %d", i, remaining)
+		}
+	}
+
+	if _, regErr := svc.RegisterFailedTOTPChallengeAttempt(context.Background(), token); !errors.Is(regErr, ErrTOTPChallengeAttemptLimit) {
+		t.Fatalf("expected attempt limit error, got %v", regErr)
+	}
+	if _, err := svc.ResolveTOTPChallenge(context.Background(), token); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected invalid token after attempt limit, got %v", err)
+	}
+}
+
+func TestAuthService_IssueTokens_NoTokenStore(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	repo.CreateUser(context.Background(), user)
+
+	if _, err := svc.IssueTokens(context.Background(), user); err != nil {
+		t.Fatalf("issue tokens should not require token store: %v", err)
+	}
+}
+
+func TestAuthService_TokenRefresh(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	repo.CreateUser(context.Background(), user)
+
+	pair, err := svc.IssueTokens(context.Background(), user)
+	if err != nil {
+		t.Fatalf("issue tokens: %v", err)
+	}
+
+	refreshed, err := svc.RefreshTokens(context.Background(), pair.RefreshToken)
+	if err != nil {
+		t.Fatalf("refresh tokens: %v", err)
+	}
+
+	duplicate, err := svc.RefreshTokens(context.Background(), pair.RefreshToken)
+	if err != nil {
+		t.Fatalf("duplicate refresh tokens: %v", err)
+	}
+	if duplicate.AccessToken != refreshed.AccessToken || duplicate.RefreshToken != refreshed.RefreshToken {
+		t.Fatalf("expected duplicate refresh to return same token pair")
+	}
+
+	// the refreshed token must remain usable after the replay window handles the stale one
+	if _, err := svc.RefreshTokens(context.Background(), refreshed.RefreshToken); err != nil {
+		t.Fatalf("expected refreshed token to remain valid, got %v", err)
+	}
+}
+
+func TestAuthService_TokenRefresh_WaitsForReplayDuringSlowRotation(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "slow-replay@example.com"}
+	repo.CreateUser(context.Background(), user)
+
+	pair, err := svc.IssueTokens(context.Background(), user)
+	if err != nil {
+		t.Fatalf("issue tokens: %v", err)
+	}
+
+	tokens.setDelay = 1500 * time.Millisecond
+	defer func() { tokens.setDelay = 0 }()
+
+	type refreshResult struct {
+		pair TokenPair
+		err  error
+	}
+	firstCh := make(chan refreshResult, 1)
+	secondCh := make(chan refreshResult, 1)
+
+	go func() {
+		p, err := svc.RefreshTokens(context.Background(), pair.RefreshToken)
+		firstCh <- refreshResult{pair: p, err: err}
+	}()
+	time.Sleep(50 * time.Millisecond)
+	go func() {
+		p, err := svc.RefreshTokens(context.Background(), pair.RefreshToken)
+		secondCh <- refreshResult{pair: p, err: err}
+	}()
+
+	first := <-firstCh
+	if first.err != nil {
+		t.Fatalf("first refresh: %v", first.err)
+	}
+	second := <-secondCh
+	if second.err != nil {
+		t.Fatalf("second refresh: %v", second.err)
+	}
+	if second.pair.AccessToken != first.pair.AccessToken || second.pair.RefreshToken != first.pair.RefreshToken {
+		t.Fatalf("expected replayed refresh pair to match first refresh")
+	}
+}
+
+func TestAuthService_ReplaceSessionForSameDeviceType(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     10 * time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	first, err := svc.IssueTokensWithClient(context.Background(), user, "Mozilla/5.0 (Macintosh; Intel Mac OS X)", "127.0.0.1")
+	if err != nil {
+		t.Fatalf("first issue tokens: %v", err)
+	}
+	if _, err := svc.ParseAccessToken(context.Background(), first.AccessToken); err != nil {
+		t.Fatalf("first access token should be valid, got %v", err)
+	}
+
+	second, err := svc.IssueTokensWithClient(context.Background(), user, "Mozilla/5.0 (Windows NT 10.0; Win64; x64)", "127.0.0.2")
+	if err != nil {
+		t.Fatalf("second issue tokens: %v", err)
+	}
+
+	if _, err := svc.ParseAccessToken(context.Background(), first.AccessToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected first access token invalid after second login, got %v", err)
+	}
+	if _, err := svc.RefreshTokens(context.Background(), first.RefreshToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected first refresh token invalid after second login, got %v", err)
+	}
+	if _, err := svc.ParseAccessToken(context.Background(), second.AccessToken); err != nil {
+		t.Fatalf("second access token should remain valid, got %v", err)
+	}
+	if _, err := svc.RefreshTokens(context.Background(), second.RefreshToken); err != nil {
+		t.Fatalf("expected second refresh token to stay valid, got %v", err)
+	}
+
+	sessions, err := svc.ListUserSessions(context.Background(), user.ID, second.SessionID)
+	if err != nil {
+		t.Fatalf("list sessions: %v", err)
+	}
+	if len(sessions) != 1 || sessions[0].ID != second.SessionID || !sessions[0].ActiveNow {
+		t.Fatalf("expected only latest session to remain active, got %#v", sessions)
+	}
+}
+
+func TestAuthService_SessionListAndRevoke(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     10 * time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	pair, err := svc.IssueTokensWithClient(context.Background(), user, "Mozilla/5.0 (Macintosh; Intel Mac OS X)", "127.0.0.1")
+	if err != nil {
+		t.Fatalf("issue tokens: %v", err)
+	}
+
+	sessions, err := svc.ListUserSessions(context.Background(), user.ID, pair.SessionID)
+	if err != nil {
+		t.Fatalf("list sessions: %v", err)
+	}
+	if len(sessions) != 1 || sessions[0].ID != pair.SessionID || !sessions[0].ActiveNow {
+		t.Fatalf("expected current session only, got %#v", sessions)
+	}
+
+	if err := svc.RevokeUserSession(context.Background(), user.ID, pair.SessionID); err != nil {
+		t.Fatalf("revoke session: %v", err)
+	}
+	if _, err := svc.RefreshTokens(context.Background(), pair.RefreshToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected refresh token invalid after session revoke, got %v", err)
+	}
+	if _, err := svc.ParseAccessToken(context.Background(), pair.AccessToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected access token invalid after current session revoke, got %v", err)
+	}
+
+	sessions, err = svc.ListUserSessions(context.Background(), user.ID, "")
+	if err != nil {
+		t.Fatalf("list sessions after revoke: %v", err)
+	}
+	if len(sessions) != 0 {
+		t.Fatalf("expected no sessions after revoke, got %#v", sessions)
+	}
+}
+
+func TestAuthService_RevokeAllUserSessions(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     10 * time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	first, err := svc.IssueTokens(context.Background(), user)
+	if err != nil {
+		t.Fatalf("issue first tokens: %v", err)
+	}
+	second, err := svc.IssueTokens(context.Background(), user)
+	if err != nil {
+		t.Fatalf("issue second tokens: %v", err)
+	}
+
+	if err := svc.RevokeAllUserSessions(context.Background(), user.ID); err != nil {
+		t.Fatalf("revoke all sessions: %v", err)
+	}
+	if _, err := svc.ParseAccessToken(context.Background(), first.AccessToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected first access invalid after revoke all, got %v", err)
+	}
+	if _, err := svc.ParseAccessToken(context.Background(), second.AccessToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected second access invalid after revoke all, got %v", err)
+	}
+	if _, err := svc.RefreshTokens(context.Background(), first.RefreshToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected first refresh invalid after revoke all, got %v", err)
+	}
+	if _, err := svc.RefreshTokens(context.Background(), second.RefreshToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected second refresh invalid after revoke all, got %v", err)
+	}
+}
+
+func TestAuthService_DeviceSlotPolicy_ReplacePerType(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     10 * time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	desktop1, err := svc.IssueTokensWithClient(context.Background(), user, "Mozilla/5.0 (Macintosh; Intel Mac OS X)", "127.0.0.1")
+	if err != nil {
+		t.Fatalf("issue desktop1: %v", err)
+	}
+	mobile1, err := svc.IssueTokensWithClient(context.Background(), user, "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) Mobile", "127.0.0.2")
+	if err != nil {
+		t.Fatalf("issue mobile1: %v", err)
+	}
+
+	// second desktop login replaces previous desktop only.
+	desktop2, err := svc.IssueTokensWithClient(context.Background(), user, "Mozilla/5.0 (Windows NT 10.0; Win64; x64)", "127.0.0.3")
+	if err != nil {
+		t.Fatalf("issue desktop2: %v", err)
+	}
+
+	if _, err := svc.ParseAccessToken(context.Background(), desktop1.AccessToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected first desktop access invalid after replacement, got %v", err)
+	}
+	if _, err := svc.ParseAccessToken(context.Background(), mobile1.AccessToken); err != nil {
+		t.Fatalf("expected mobile session to remain valid, got %v", err)
+	}
+	if _, err := svc.ParseAccessToken(context.Background(), desktop2.AccessToken); err != nil {
+		t.Fatalf("expected second desktop session valid, got %v", err)
+	}
+
+	sessions, err := svc.ListUserSessions(context.Background(), user.ID, desktop2.SessionID)
+	if err != nil {
+		t.Fatalf("list sessions: %v", err)
+	}
+	if len(sessions) != 2 {
+		t.Fatalf("expected exactly 2 sessions (desktop+mobile), got %d", len(sessions))
+	}
+}
+
+func TestAuthService_SessionHelpersAndBranches(t *testing.T) {
+	newSessionService := func() (*mockAuthRepo, *mockTokenStore, *AuthService, *auth.User) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		cfg := config.AuthConfig{
+			JWTAccessSecret:   "access",
+			JWTRefreshSecret:  "refresh",
+			JWTAccessTTL:      10 * time.Minute,
+			JWTRefreshTTL:     time.Hour,
+			JWTRefreshTOTPTTL: 2 * time.Hour,
+		}
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+		user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+		_ = repo.CreateUser(context.Background(), user)
+		return repo, tokens, svc, user
+	}
+
+	t.Run("issue tokens after totp success and invalid user", func(t *testing.T) {
+		_, _, svc, user := newSessionService()
+		pair, err := svc.IssueTokensAfterTOTPWithClient(context.Background(), user, "Mozilla/5.0 (X11; Linux) Firefox/120.0", "127.0.0.1")
+		if err != nil {
+			t.Fatalf("issue after totp: %v", err)
+		}
+		if pair.RefreshTTL != 2*time.Hour {
+			t.Fatalf("expected refresh ttl from totp config, got %v", pair.RefreshTTL)
+		}
+		if _, err := svc.IssueTokensAfterTOTPWithClient(context.Background(), &auth.User{}, "", ""); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for invalid user, got %v", err)
+		}
+	})
+
+	t.Run("issue login tokens helper invalid user", func(t *testing.T) {
+		_, _, svc, _ := newSessionService()
+		if _, err := svc.issueLoginTokensWithRefreshTTLAndClient(context.Background(), &auth.User{}, time.Hour, false, "", "", "", "", ""); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token, got %v", err)
+		}
+	})
+
+	t.Run("parse access token session id success and error", func(t *testing.T) {
+		_, _, svc, user := newSessionService()
+		pair, err := svc.IssueTokens(context.Background(), user)
+		if err != nil {
+			t.Fatalf("issue tokens: %v", err)
+		}
+		sid, err := svc.ParseAccessTokenSessionID(context.Background(), pair.AccessToken)
+		if err != nil || sid != pair.SessionID {
+			t.Fatalf("expected session id %q, got %q err=%v", pair.SessionID, sid, err)
+		}
+		if _, err := svc.ParseAccessTokenSessionID(context.Background(), "bad"); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token, got %v", err)
+		}
+	})
+
+	t.Run("refresh tokens branches", func(t *testing.T) {
+		repo, tokens, svc, user := newSessionService()
+		pair, err := svc.IssueTokensAfterTOTPWithClient(context.Background(), user, "Mozilla/5.0 (Windows NT 10.0) Edg/120", "127.0.0.1")
+		if err != nil {
+			t.Fatalf("issue tokens: %v", err)
+		}
+		refreshed, err := svc.RefreshTokensWithClient(context.Background(), pair.RefreshToken, "", "")
+		if err != nil {
+			t.Fatalf("refresh tokens: %v", err)
+		}
+		if refreshed.RefreshTTL != svc.cfg.JWTRefreshTOTPTTL {
+			t.Fatalf("expected totp refresh ttl preserved, got %v", refreshed.RefreshTTL)
+		}
+
+		sub, err := uuidv7.BytesToString(user.ID)
+		if err != nil {
+			t.Fatalf("uuid to string: %v", err)
+		}
+		claims := jwt.MapClaims{
+			"sub":  sub,
+			"iat":  time.Now().Unix(),
+			"exp":  time.Now().Add(time.Hour).Unix(),
+			"type": "refresh",
+			"sid":  pair.SessionID,
+		}
+		tokenMissingJTI, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(svc.cfg.JWTRefreshSecret))
+		if _, err := svc.RefreshTokensWithClient(context.Background(), tokenMissingJTI, "", ""); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for missing jti, got %v", err)
+		}
+
+		pair2, err := svc.IssueTokens(context.Background(), user)
+		if err != nil {
+			t.Fatalf("issue second token: %v", err)
+		}
+		tokens.store[sessionKey(pair2.SessionID)] = []byte("not-json")
+		if _, err := svc.RefreshTokensWithClient(context.Background(), pair2.RefreshToken, "", ""); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for bad session payload, got %v", err)
+		}
+
+		pair3, err := svc.IssueTokens(context.Background(), user)
+		if err != nil {
+			t.Fatalf("issue third token: %v", err)
+		}
+		delete(repo.users, string(user.ID))
+		delete(repo.usersByMail, user.Email)
+		if _, err := svc.RefreshTokensWithClient(context.Background(), pair3.RefreshToken, "", ""); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token when user missing, got %v", err)
+		}
+	})
+
+	t.Run("refresh microsoft session validates provider connectivity", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		ms := &mockTokenSSO{
+			mockSSO: mockSSO{
+				claims: MicrosoftClaims{
+					Subject:  "sub",
+					Email:    "user@example.com",
+					TenantID: "tenant",
+					ObjectID: "oid",
+				},
+			},
+		}
+
+		cfg := config.AuthConfig{
+			PasswordPepper:   "pepper",
+			HashTime:         1,
+			HashMemoryKB:     64 * 1024,
+			HashThreads:      1,
+			HashKeyLen:       32,
+			JWTAccessSecret:  "access",
+			JWTRefreshSecret: "refresh",
+			JWTAccessTTL:     time.Minute,
+			JWTRefreshTTL:    time.Hour,
+		}
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{
+			SSO:       ms,
+			Protector: &errorProtector{},
+			Config:    cfg,
+		})
+
+		user := &auth.User{ID: uuidv7.MustBytes(), Email: "user@example.com", IsActive: true}
+		if err := repo.CreateUser(context.Background(), user); err != nil {
+			t.Fatalf("create user: %v", err)
+		}
+		if err := repo.MarkEmailVerified(context.Background(), user.ID); err != nil {
+			t.Fatalf("mark email verified: %v", err)
+		}
+		if err := svc.storeMicrosoftOAuthToken(context.Background(), user.ID, ms.claims, MicrosoftTokenSet{
+			AccessToken:  "old_access",
+			RefreshToken: "old_refresh",
+			IDToken:      testMicrosoftIDToken("user@example.com", "sub", "tenant", "oid"),
+			TokenType:    "Bearer",
+			Scope:        "openid profile email",
+			ExpiresIn:    3600,
+		}); err != nil {
+			t.Fatalf("store ms token: %v", err)
+		}
+
+		pair, err := svc.IssueTokensWithClientForProvider(context.Background(), user, "Mozilla/5.0", "127.0.0.1", ssoProviderMicrosoft)
+		if err != nil {
+			t.Fatalf("issue provider token: %v", err)
+		}
+
+		ms.refreshSet = MicrosoftTokenSet{
+			AccessToken:  "new_access",
+			RefreshToken: "new_refresh",
+			IDToken:      testMicrosoftIDToken("user@example.com", "sub", "tenant", "oid"),
+			TokenType:    "Bearer",
+			Scope:        "openid profile email",
+			ExpiresIn:    3600,
+		}
+		if _, err := svc.RefreshTokensWithClient(context.Background(), pair.RefreshToken, "", ""); err != nil {
+			t.Fatalf("expected microsoft session refresh success, got %v", err)
+		}
+
+		pair2, err := svc.IssueTokensWithClientForProvider(context.Background(), user, "Mozilla/5.0", "127.0.0.1", ssoProviderMicrosoft)
+		if err != nil {
+			t.Fatalf("issue provider token second: %v", err)
+		}
+		ms.refreshErr = errors.New("token exchange failed: invalid_grant")
+		if _, err := svc.RefreshTokensWithClient(context.Background(), pair2.RefreshToken, "", ""); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token when microsoft disconnected, got %v", err)
+		}
+	})
+
+	t.Run("refresh microsoft session survives transient provider errors", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		ms := &mockTokenSSO{
+			mockSSO: mockSSO{
+				claims: MicrosoftClaims{
+					Subject:  "sub",
+					Email:    "user@example.com",
+					TenantID: "tenant",
+					ObjectID: "oid",
+				},
+			},
+		}
+
+		cfg := config.AuthConfig{
+			PasswordPepper:   "pepper",
+			HashTime:         1,
+			HashMemoryKB:     64 * 1024,
+			HashThreads:      1,
+			HashKeyLen:       32,
+			JWTAccessSecret:  "access",
+			JWTRefreshSecret: "refresh",
+			JWTAccessTTL:     time.Minute,
+			JWTRefreshTTL:    time.Hour,
+		}
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{
+			SSO:       ms,
+			Protector: &errorProtector{},
+			Config:    cfg,
+		})
+
+		user := &auth.User{ID: uuidv7.MustBytes(), Email: "user@example.com", IsActive: true}
+		if err := repo.CreateUser(context.Background(), user); err != nil {
+			t.Fatalf("create user: %v", err)
+		}
+		if err := repo.MarkEmailVerified(context.Background(), user.ID); err != nil {
+			t.Fatalf("mark email verified: %v", err)
+		}
+		if err := svc.storeMicrosoftOAuthToken(context.Background(), user.ID, ms.claims, MicrosoftTokenSet{
+			AccessToken:  "old_access",
+			RefreshToken: "old_refresh",
+			IDToken:      testMicrosoftIDToken("user@example.com", "sub", "tenant", "oid"),
+			TokenType:    "Bearer",
+			Scope:        "openid profile email",
+			ExpiresIn:    3600,
+		}); err != nil {
+			t.Fatalf("store ms token: %v", err)
+		}
+
+		pair, err := svc.IssueTokensWithClientForProvider(context.Background(), user, "Mozilla/5.0", "127.0.0.1", ssoProviderMicrosoft)
+		if err != nil {
+			t.Fatalf("issue provider token: %v", err)
+		}
+
+		// A transient Microsoft failure (network/5xx/throttle/circuit breaker)
+		// must NOT revoke the app session: the user stays logged in and we
+		// retry Microsoft on the next refresh.
+		ms.refreshErr = errors.New("microsoft sso unavailable: server_error (503)")
+		if _, err := svc.RefreshTokensWithClient(context.Background(), pair.RefreshToken, "", ""); err != nil {
+			t.Fatalf("expected transient microsoft error to keep the session, got %v", err)
+		}
+
+		// The session must still be usable: once Microsoft recovers, a normal
+		// refresh succeeds.
+		ms.refreshErr = nil
+		ms.refreshSet = MicrosoftTokenSet{
+			AccessToken:  "new_access",
+			RefreshToken: "new_refresh",
+			IDToken:      testMicrosoftIDToken("user@example.com", "sub", "tenant", "oid"),
+			TokenType:    "Bearer",
+			Scope:        "openid profile email",
+			ExpiresIn:    3600,
+		}
+		pair2, err := svc.IssueTokensWithClientForProvider(context.Background(), user, "Mozilla/5.0", "127.0.0.1", ssoProviderMicrosoft)
+		if err != nil {
+			t.Fatalf("issue provider token second: %v", err)
+		}
+		if _, err := svc.RefreshTokensWithClient(context.Background(), pair2.RefreshToken, "", ""); err != nil {
+			t.Fatalf("expected refresh success after microsoft recovery, got %v", err)
+		}
+	})
+
+	t.Run("microsoft session refresh ttl follows microsoft refresh token", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		ms := &mockTokenSSO{
+			mockSSO: mockSSO{
+				claims: MicrosoftClaims{Subject: "sub", Email: "user@example.com", TenantID: "tenant", ObjectID: "oid"},
+			},
+		}
+
+		cfg := config.AuthConfig{
+			PasswordPepper:   "pepper",
+			HashTime:         1,
+			HashMemoryKB:     64 * 1024,
+			HashThreads:      1,
+			HashKeyLen:       32,
+			JWTAccessSecret:  "access",
+			JWTRefreshSecret: "refresh",
+			JWTAccessTTL:     time.Minute,
+			JWTRefreshTTL:    time.Hour,           // short baseline that must be overridden for SSO
+			JWTSSORefreshTTL: 90 * 24 * time.Hour, // fallback when microsoft omits the expiry
+		}
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{
+			SSO:       ms,
+			Protector: &errorProtector{},
+			Config:    cfg,
+		})
+
+		user := &auth.User{ID: uuidv7.MustBytes(), Email: "user@example.com", IsActive: true}
+		if err := repo.CreateUser(context.Background(), user); err != nil {
+			t.Fatalf("create user: %v", err)
+		}
+		if err := repo.MarkEmailVerified(context.Background(), user.ID); err != nil {
+			t.Fatalf("mark email verified: %v", err)
+		}
+
+		// Microsoft reports a 30-day refresh token lifetime: the app session
+		// must follow it, not the 1h JWTRefreshTTL baseline.
+		const msRefreshTTL = 30 * 24 * time.Hour
+		if err := svc.storeMicrosoftOAuthToken(context.Background(), user.ID, ms.claims, MicrosoftTokenSet{
+			AccessToken:           "access",
+			RefreshToken:          "refresh",
+			IDToken:               testMicrosoftIDToken("user@example.com", "sub", "tenant", "oid"),
+			TokenType:             "Bearer",
+			Scope:                 "openid profile email",
+			ExpiresIn:             3600,
+			RefreshTokenExpiresIn: int64(msRefreshTTL.Seconds()),
+		}); err != nil {
+			t.Fatalf("store ms token: %v", err)
+		}
+
+		pair, err := svc.IssueTokensWithClientForProvider(context.Background(), user, "Mozilla/5.0", "127.0.0.1", ssoProviderMicrosoft)
+		if err != nil {
+			t.Fatalf("issue provider token: %v", err)
+		}
+		if pair.RefreshTTL <= time.Hour {
+			t.Fatalf("expected sso refresh ttl to follow microsoft (~30d), got %s", pair.RefreshTTL)
+		}
+		if diff := msRefreshTTL - pair.RefreshTTL; diff < 0 || diff > 5*time.Minute {
+			t.Fatalf("expected refresh ttl ~= microsoft 30d, got %s (diff %s)", pair.RefreshTTL, diff)
+		}
+
+		// When Microsoft does not report an expiry, fall back to the SSO default.
+		repo2 := newMockAuthRepo()
+		svc2 := NewAuthService(repo2, roles, newMockTokenStore(), nil, AuthServiceDependencies{
+			SSO:       ms,
+			Protector: &errorProtector{},
+			Config:    cfg,
+		})
+		user2 := &auth.User{ID: uuidv7.MustBytes(), Email: "user2@example.com", IsActive: true}
+		if err := repo2.CreateUser(context.Background(), user2); err != nil {
+			t.Fatalf("create user2: %v", err)
+		}
+		if err := repo2.MarkEmailVerified(context.Background(), user2.ID); err != nil {
+			t.Fatalf("mark email verified user2: %v", err)
+		}
+		if err := svc2.storeMicrosoftOAuthToken(context.Background(), user2.ID, ms.claims, MicrosoftTokenSet{
+			AccessToken:  "access",
+			RefreshToken: "refresh",
+			IDToken:      testMicrosoftIDToken("user2@example.com", "sub", "tenant", "oid"),
+			TokenType:    "Bearer",
+			Scope:        "openid profile email",
+			ExpiresIn:    3600,
+		}); err != nil {
+			t.Fatalf("store ms token user2: %v", err)
+		}
+		pair2, err := svc2.IssueTokensWithClientForProvider(context.Background(), user2, "Mozilla/5.0", "127.0.0.1", ssoProviderMicrosoft)
+		if err != nil {
+			t.Fatalf("issue provider token user2: %v", err)
+		}
+		if diff := cfg.JWTSSORefreshTTL - pair2.RefreshTTL; diff < 0 || diff > 5*time.Minute {
+			t.Fatalf("expected fallback ttl ~= sso default (90d), got %s", pair2.RefreshTTL)
+		}
+	})
+
+	t.Run("revoke refresh token with session branches", func(t *testing.T) {
+		_, tokens, svc, user := newSessionService()
+		if err := svc.revokeRefreshTokenWithSession(context.Background(), ""); err != nil {
+			t.Fatalf("expected nil for empty token, got %v", err)
+		}
+		if err := svc.revokeRefreshTokenWithSession(context.Background(), "bad"); err != nil {
+			t.Fatalf("expected nil for invalid token parse, got %v", err)
+		}
+
+		claims := jwt.MapClaims{
+			"sub":  "not-a-uuid",
+			"iat":  time.Now().Unix(),
+			"exp":  time.Now().Add(time.Hour).Unix(),
+			"jti":  "jti-1",
+			"type": "refresh",
+			"sid":  "sid-1",
+		}
+		tokenBadSub, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(svc.cfg.JWTRefreshSecret))
+		tokens.store[refreshKey("jti-1")] = []byte("sid-1")
+		if err := svc.revokeRefreshTokenWithSession(context.Background(), tokenBadSub); err != nil {
+			t.Fatalf("expected nil for bad sub revoke, got %v", err)
+		}
+		if _, ok := tokens.store[refreshKey("jti-1")]; ok {
+			t.Fatalf("expected fallback delete when sub is invalid")
+		}
+
+		sub, err := uuidv7.BytesToString(user.ID)
+		if err != nil {
+			t.Fatalf("uuid to string: %v", err)
+		}
+		claimsNoSID := jwt.MapClaims{
+			"sub":  sub,
+			"iat":  time.Now().Unix(),
+			"exp":  time.Now().Add(time.Hour).Unix(),
+			"jti":  "jti-2",
+			"type": "refresh",
+		}
+		tokenNoSID, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claimsNoSID).SignedString([]byte(svc.cfg.JWTRefreshSecret))
+		tokens.store[refreshKey("jti-2")] = []byte("sid-2")
+		if err := svc.revokeRefreshTokenWithSession(context.Background(), tokenNoSID); err != nil {
+			t.Fatalf("expected nil for fallback delete, got %v", err)
+		}
+		if _, ok := tokens.store[refreshKey("jti-2")]; ok {
+			t.Fatalf("expected refresh key deleted")
+		}
+	})
+
+	t.Run("list user sessions branches", func(t *testing.T) {
+		_, tokens, svc, user := newSessionService()
+		if _, err := svc.ListUserSessions(context.Background(), []byte("short"), ""); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for invalid user id, got %v", err)
+		}
+
+		svcNoTokens := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		sessions, err := svcNoTokens.ListUserSessions(context.Background(), uuidv7.MustBytes(), "")
+		if err != nil || len(sessions) != 0 {
+			t.Fatalf("expected empty sessions without token store, got len=%d err=%v", len(sessions), err)
+		}
+
+		tokens.getErr = errors.New("get failed")
+		if _, err := svc.ListUserSessions(context.Background(), user.ID, ""); !errors.Is(err, tokens.getErr) {
+			t.Fatalf("expected get err, got %v", err)
+		}
+		tokens.getErr = nil
+
+		tokens.store[userSessionsKey(user.ID)] = []byte(`["sid-a","sid-b","sid-c"]`)
+		tokens.store[sessionKey("sid-a")] = []byte("not-json")
+		otherUserID := uuidv7.MustBytes()
+		recordB := &authSessionRecord{SessionID: "sid-b", UserID: bytesToString(otherUserID), LastActiveAt: time.Now()}
+		recordC := &authSessionRecord{SessionID: "sid-c", UserID: bytesToString(user.ID), DeviceName: "Chrome on macOS", LastActiveAt: time.Now().Add(time.Minute)}
+		_ = svc.saveSessionRecord(context.Background(), recordB, time.Hour)
+		_ = svc.saveSessionRecord(context.Background(), recordC, time.Hour)
+		list, err := svc.ListUserSessions(context.Background(), user.ID, "sid-c")
+		if err != nil {
+			t.Fatalf("list sessions: %v", err)
+		}
+		if len(list) != 1 || list[0].ID != "sid-c" || !list[0].ActiveNow {
+			t.Fatalf("expected only valid matching session, got %#v", list)
+		}
+	})
+
+	t.Run("revoke user session branches", func(t *testing.T) {
+		_, _, svc, user := newSessionService()
+		if err := svc.RevokeUserSession(context.Background(), []byte("short"), "sid"); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for bad user id, got %v", err)
+		}
+		if err := svc.RevokeUserSession(context.Background(), user.ID, "   "); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for empty session id, got %v", err)
+		}
+
+		svcNoTokens := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if err := svcNoTokens.RevokeUserSession(context.Background(), user.ID, "sid"); err != nil {
+			t.Fatalf("expected nil without token store, got %v", err)
+		}
+
+		_, tokens, svc2, user2 := newSessionService()
+		tokens.getErr = errors.New("get failed")
+		if err := svc2.RevokeUserSession(context.Background(), user2.ID, "sid"); !errors.Is(err, tokens.getErr) {
+			t.Fatalf("expected get err, got %v", err)
+		}
+		tokens.getErr = nil
+		if err := svc2.RevokeUserSession(context.Background(), user2.ID, "sid"); !errors.Is(err, ErrSessionNotFound) {
+			t.Fatalf("expected session not found, got %v", err)
+		}
+
+		record := &authSessionRecord{SessionID: "sid", UserID: bytesToString(uuidv7.MustBytes()), CurrentJTI: "jti"}
+		_ = svc2.saveSessionRecord(context.Background(), record, time.Hour)
+		if err := svc2.RevokeUserSession(context.Background(), user2.ID, "sid"); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for other user session, got %v", err)
+		}
+	})
+
+	t.Run("is session active branches", func(t *testing.T) {
+		_, _, _, user := newSessionService()
+		svcNoTokens := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if svcNoTokens.isSessionActive(context.Background(), user.ID, "sid") {
+			t.Fatalf("expected inactive when token store unavailable")
+		}
+
+		_, tokens, svc2, user2 := newSessionService()
+		tokens.getErr = errors.New("get failed")
+		if svc2.isSessionActive(context.Background(), user2.ID, "sid") {
+			t.Fatalf("expected inactive on token store error")
+		}
+		tokens.getErr = nil
+		if svc2.isSessionActive(context.Background(), user2.ID, "missing") {
+			t.Fatalf("expected inactive when no record")
+		}
+		record := &authSessionRecord{SessionID: "sid", UserID: bytesToString(uuidv7.MustBytes())}
+		_ = svc2.saveSessionRecord(context.Background(), record, time.Hour)
+		if svc2.isSessionActive(context.Background(), user2.ID, "sid") {
+			t.Fatalf("expected inactive for other user session")
+		}
+		record.UserID = bytesToString(user2.ID)
+		_ = svc2.saveSessionRecord(context.Background(), record, time.Hour)
+		_ = svc2.replaceUserSessionIDs(context.Background(), user2.ID, []string{"sid"})
+		if !svc2.isSessionActive(context.Background(), user2.ID, "sid") {
+			t.Fatalf("expected active for matching session")
+		}
+	})
+
+	t.Run("save session record branches", func(t *testing.T) {
+		_, _, svc, _ := newSessionService()
+		if err := svc.saveSessionRecord(context.Background(), nil, time.Hour); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for nil session, got %v", err)
+		}
+		if err := svc.saveSessionRecord(context.Background(), &authSessionRecord{}, time.Hour); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for empty session id, got %v", err)
+		}
+
+		_, tokens, svc2, user := newSessionService()
+		record := &authSessionRecord{SessionID: "sid", UserID: bytesToString(user.ID)}
+		if err := svc2.saveSessionRecord(context.Background(), record, time.Hour); err != nil {
+			t.Fatalf("unexpected save error: %v", err)
+		}
+		if _, ok := tokens.store[sessionKey("sid")]; !ok {
+			t.Fatalf("expected session payload saved")
+		}
+	})
+
+	t.Run("add user session id branches", func(t *testing.T) {
+		_, _, svc, user := newSessionService()
+		if err := svc.addUserSessionID(context.Background(), user.ID, "   "); err != nil {
+			t.Fatalf("expected nil for empty session id, got %v", err)
+		}
+
+		_, tokens, svc2, user2 := newSessionService()
+		tokens.getErr = errors.New("get failed")
+		if err := svc2.addUserSessionID(context.Background(), user2.ID, "sid"); !errors.Is(err, tokens.getErr) {
+			t.Fatalf("expected get err, got %v", err)
+		}
+		tokens.getErr = nil
+		tokens.store[userSessionsKey(user2.ID)] = []byte(`["sid"]`)
+		setCountBefore := tokens.setCount
+		if err := svc2.addUserSessionID(context.Background(), user2.ID, "sid"); err != nil {
+			t.Fatalf("unexpected duplicate add error: %v", err)
+		}
+		if tokens.setCount != setCountBefore {
+			t.Fatalf("expected duplicate session id not to be written again")
+		}
+		if err := svc2.addUserSessionID(context.Background(), user2.ID, "sid-2"); err != nil {
+			t.Fatalf("unexpected add error: %v", err)
+		}
+		ids, err := svc2.loadUserSessionIDs(context.Background(), user2.ID)
+		if err != nil || len(ids) != 2 {
+			t.Fatalf("expected two session ids, got %#v err=%v", ids, err)
+		}
+	})
+
+	t.Run("derive device name variants", func(t *testing.T) {
+		cases := map[string]string{
+			"":                                  "Unknown device",
+			"Mozilla/5.0 (iPhone) Safari/605.1": "Safari on iPhone",
+			"Mozilla/5.0 (iPad) Safari/605.1":   "Safari on iPad",
+			"Mozilla/5.0 (Linux; Android 14) Chrome/120.0":          "Chrome on Android",
+			"Mozilla/5.0 (Macintosh; Intel Mac OS X) Firefox/120.0": "Firefox on macOS",
+			"Mozilla/5.0 (Windows NT 10.0; Win64; x64) Edg/120.0":   "Edge on Windows",
+			"Mozilla/5.0 (X11; Linux x86_64)":                       "Unknown browser on Linux",
+		}
+		for ua, want := range cases {
+			if got := deriveDeviceName(ua); got != want {
+				t.Fatalf("deriveDeviceName(%q) = %q, want %q", ua, got, want)
+			}
+		}
+	})
+}
+
+func TestAuthService_RefreshTokens_InvalidToken(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{
+		JWTRefreshSecret: "refresh",
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if _, err := svc.RefreshTokens(context.Background(), "bad"); err == nil {
+		t.Fatalf("expected invalid token")
+	}
+}
+
+func TestAuthService_RefreshTokens_NoTokenStore(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	repo.CreateUser(context.Background(), user)
+	pair, _ := svc.IssueTokens(context.Background(), user)
+	if _, err := svc.RefreshTokens(context.Background(), pair.RefreshToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected invalid token without token store, got %v", err)
+	}
+}
+
+func TestAuthService_RefreshTokens_MissingJTI(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{
+		JWTRefreshSecret: "refresh",
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{
+
+		// create token without jti
+		SSO: nil, Protector: nil, Config: cfg})
+
+	claims := map[string]any{
+		"sub":  "invalid",
+		"iat":  time.Now().Unix(),
+		"exp":  time.Now().Add(time.Hour).Unix(),
+		"type": "refresh",
+	}
+	tok, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims(claims)).SignedString([]byte(cfg.JWTRefreshSecret))
+	if _, err := svc.RefreshTokens(context.Background(), tok); err == nil {
+		t.Fatalf("expected invalid token (missing jti)")
+	}
+}
+
+func TestAuthService_RefreshTokens_MissingSub(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{
+		JWTRefreshSecret: "refresh",
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	claims := map[string]any{
+		"jti":  "jti1",
+		"iat":  time.Now().Unix(),
+		"exp":  time.Now().Add(time.Hour).Unix(),
+		"type": "refresh",
+	}
+	tok, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims(claims)).SignedString([]byte(cfg.JWTRefreshSecret))
+	if _, err := svc.RefreshTokens(context.Background(), tok); err == nil {
+		t.Fatalf("expected invalid token (missing sub)")
+	}
+}
+
+func TestAuthService_RefreshTokens_TokenStoreMissing(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	repo.CreateUser(context.Background(), user)
+	pair, _ := svc.IssueTokens(context.Background(), user)
+
+	// clear token store to simulate missing jti
+	tokens.store = map[string][]byte{}
+
+	if _, err := svc.RefreshTokens(context.Background(), pair.RefreshToken); err == nil {
+		t.Fatalf("expected invalid token when jti missing in store")
+	}
+}
+
+func TestAuthService_RefreshTokens_UserNotFound(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{
+
+		// Create token with valid jti stored but user missing
+		SSO: nil, Protector: nil, Config: cfg})
+
+	jti := "jti2"
+	_ = tokens.Set(context.Background(), "auth:refresh:"+jti, []byte("1"), time.Hour)
+	claims := map[string]any{
+		"jti":  jti,
+		"sub":  "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d",
+		"iat":  time.Now().Unix(),
+		"exp":  time.Now().Add(time.Hour).Unix(),
+		"type": "refresh",
+	}
+	tok, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims(claims)).SignedString([]byte(cfg.JWTRefreshSecret))
+	if _, err := svc.RefreshTokens(context.Background(), tok); err == nil {
+		t.Fatalf("expected invalid token when user not found")
+	}
+}
+
+func TestAuthService_VerifyEmail(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	adminID := uuidv7.MustBytes()
+	roles.rolesByName["admin"] = &auth.Role{ID: adminID, Name: "admin"}
+
+	cfg := config.AuthConfig{
+		PasswordPepper:  "pepper",
+		HashTime:        1,
+		HashMemoryKB:    64 * 1024,
+		HashThreads:     4,
+		HashKeyLen:      32,
+		EmailVerifyTTL:  time.Hour,
+		EmailVerifyURL:  "http://localhost/verify",
+		DefaultRoleName: "admin",
+	}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", adminID)
+	if err != nil {
+		t.Fatalf("register failed: %v", err)
+	}
+
+	if tokens.lastKey == "" {
+		t.Fatalf("expected email verify token in store")
+	}
+
+	token := tokens.lastKey[len("auth:email_verify:"):]
+	if err := svc.VerifyEmail(context.Background(), token); err != nil {
+		t.Fatalf("verify email failed: %v", err)
+	}
+	if user.EmailVerifiedAt == nil {
+		t.Fatalf("email not verified")
+	}
+}
+
+func TestAuthService_TOTPChallenge(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		TOTPChallengeTTL: time.Minute,
+	}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	userID := uuidv7.MustBytes()
+	token, err := svc.CreateTOTPChallenge(context.Background(), userID)
+	if err != nil || token == "" {
+		t.Fatalf("create challenge failed")
+	}
+
+	got, err := svc.ConsumeTOTPChallenge(context.Background(), token)
+	if err != nil {
+		t.Fatalf("consume challenge failed: %v", err)
+	}
+	if string(got) != string(userID) {
+		t.Fatalf("unexpected user id")
+	}
+}
+
+func TestAuthService_RandomToken_Uniqueness(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		TOTPChallengeTTL: time.Minute,
+	}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	userID := uuidv7.MustBytes()
+	token1, err := svc.CreateTOTPChallenge(context.Background(), userID)
+	if err != nil || token1 == "" {
+		t.Fatalf("create challenge 1 failed")
+	}
+	token2, err := svc.CreateTOTPChallenge(context.Background(), userID)
+	if err != nil || token2 == "" {
+		t.Fatalf("create challenge 2 failed")
+	}
+	if token1 == token2 {
+		t.Fatalf("expected different tokens")
+	}
+	if tokens.setCount < 2 {
+		t.Fatalf("expected token store set twice")
+	}
+}
+
+func TestAuthService_RandomToken_Error(t *testing.T) {
+	orig := rand.Reader
+	rand.Reader = errReader{}
+	defer func() { rand.Reader = orig }()
+
+	if _, err := randomToken(16); err == nil {
+		t.Fatalf("expected randomToken error")
+	}
+}
+
+type errReader struct{}
+
+func (e errReader) Read(p []byte) (int, error) {
+	return 0, io.ErrUnexpectedEOF
+}
+
+func TestAuthService_ParseAccessToken(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	repo.CreateUser(context.Background(), user)
+	pair, err := svc.IssueTokens(context.Background(), user)
+	if err != nil {
+		t.Fatalf("issue tokens: %v", err)
+	}
+
+	id, err := svc.ParseAccessToken(context.Background(), pair.AccessToken)
+	if err != nil || string(id) != string(user.ID) {
+		t.Fatalf("parse access token failed")
+	}
+
+	user.IsActive = false
+	if _, err := svc.ParseAccessToken(context.Background(), pair.AccessToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected inactive user access token to be rejected, got %v", err)
+	}
+}
+
+type mockSSO struct {
+	claims  MicrosoftClaims
+	err     error
+	authURL string
+}
+
+type mockTokenSSO struct {
+	mockSSO
+	refreshSet MicrosoftTokenSet
+	refreshErr error
+}
+
+func (m *mockSSO) AuthCodeURL(state string) string {
+	if strings.TrimSpace(m.authURL) != "" {
+		return fmt.Sprintf(m.authURL, state)
+	}
+	return "http://example.com?state=" + state
+}
+func (m *mockSSO) LogoutURL(postLogoutRedirectURL string) string {
+	if strings.TrimSpace(postLogoutRedirectURL) == "" {
+		return "http://example.com/logout"
+	}
+	return "http://example.com/logout?post_logout_redirect_uri=" + url.QueryEscape(postLogoutRedirectURL)
+}
+func (m *mockSSO) ExchangeCode(ctx context.Context, code string) (MicrosoftClaims, error) {
+	if m.err != nil {
+		return MicrosoftClaims{}, m.err
+	}
+	return m.claims, nil
+}
+
+func (m *mockTokenSSO) ExchangeCodeAndTokens(ctx context.Context, code, codeVerifier string) (MicrosoftTokenSet, MicrosoftClaims, error) {
+	if m.err != nil {
+		return MicrosoftTokenSet{}, MicrosoftClaims{}, m.err
+	}
+	return MicrosoftTokenSet{
+		AccessToken:  "ms_access",
+		RefreshToken: "ms_refresh",
+		IDToken:      testMicrosoftIDToken("user@example.com", "sub", "tenant", "oid"),
+		TokenType:    "Bearer",
+		Scope:        "openid profile email",
+		ExpiresIn:    3600,
+	}, m.claims, nil
+}
+
+func (m *mockTokenSSO) RefreshAccessToken(ctx context.Context, refreshToken, codeVerifier string) (MicrosoftTokenSet, error) {
+	if m.refreshErr != nil {
+		return MicrosoftTokenSet{}, m.refreshErr
+	}
+	if m.refreshSet.IDToken == "" {
+		m.refreshSet.IDToken = testMicrosoftIDToken("user@example.com", "sub", "tenant", "oid")
+	}
+	if m.refreshSet.AccessToken == "" {
+		m.refreshSet.AccessToken = "ms_access_refreshed"
+	}
+	return m.refreshSet, nil
+}
+
+func testMicrosoftIDToken(email, sub, tid, oid string) string {
+	header := base64.RawURLEncoding.EncodeToString([]byte(`{"alg":"none","typ":"JWT"}`))
+	payload := fmt.Sprintf(`{"sub":"%s","tid":"%s","oid":"%s","email":"%s","upn":"%s"}`, sub, tid, oid, email, email)
+	body := base64.RawURLEncoding.EncodeToString([]byte(payload))
+	return header + "." + body + "."
+}
+
+func TestAuthService_LinkSSOForUser(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	userID := uuidv7.MustBytes()
+	userRoleID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       userID,
+		Email:    "marco@example.com",
+		Timezone: tzpkg.WithDefault(""),
+		RoleID:   userRoleID,
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub", Email: "marco@example.com", Name: "Jane Doe"}}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: config.AuthConfig{}})
+	identity, err := svc.LinkSSOForUser(context.Background(), userID, "microsoft", "code")
+	if err != nil || identity == nil {
+		t.Fatalf("link sso failed: %v", err)
+	}
+	if !bytes.Equal(identity.UserID, userID) {
+		t.Fatalf("expected identity linked to user")
+	}
+}
+
+func TestAuthService_LinkSSOForUser_RejectWhenLinkedToAnotherUser(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	userRoleID := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+	otherUserID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       userID,
+		Email:    "user@example.com",
+		Timezone: tzpkg.WithDefault(""),
+		RoleID:   userRoleID,
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       otherUserID,
+		Email:    "other@example.com",
+		Timezone: tzpkg.WithDefault(""),
+		RoleID:   userRoleID,
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	_ = repo.CreateIdentity(context.Background(), &auth.UserIdentity{
+		ID:              uuidv7.MustBytes(),
+		UserID:          otherUserID,
+		Provider:        "microsoft",
+		ProviderSubject: "sub",
+		Email:           "other@example.com",
+	})
+
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane Doe"}}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: config.AuthConfig{}})
+
+	if _, err := svc.LinkSSOForUser(context.Background(), userID, "microsoft", "code"); !errors.Is(err, ErrSSOLinkedToAnotherUser) {
+		t.Fatalf("expected ErrSSOLinkedToAnotherUser, got %v", err)
+	}
+}
+
+func TestAuthService_BeginCompleteMicrosoftLogin(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	userRoleID := uuidv7.MustBytes()
+	roles.rolesByName["user"] = &auth.Role{ID: userRoleID, Name: "user"}
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       userID,
+		Email:    "user@example.com",
+		Timezone: tzpkg.WithDefault(""),
+		RoleID:   userRoleID,
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	_ = repo.CreateIdentity(context.Background(), &auth.UserIdentity{
+		ID:              uuidv7.MustBytes(),
+		UserID:          userID,
+		Provider:        "microsoft",
+		ProviderSubject: "sub",
+		Email:           "user@example.com",
+	})
+
+	cfg := config.AuthConfig{
+		SSOStateTTL: time.Minute,
+	}
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane Doe"}}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+	authURL, err := svc.BeginMicrosoftLogin(context.Background())
+	if err != nil || authURL == "" {
+		t.Fatalf("expected auth url")
+	}
+
+	// extract state from mock url
+	parsedURL, parseErr := url.Parse(authURL)
+	if parseErr != nil {
+		t.Fatalf("parse auth url: %v", parseErr)
+	}
+	state := parsedURL.Query().Get("state")
+	identity, _, err := svc.CompleteMicrosoftLogin(context.Background(), "code", state)
+	if err != nil || identity == nil {
+		t.Fatalf("complete login failed: %v", err)
+	}
+}
+
+func TestAuthService_BeginCompleteMicrosoftLink(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	userRoleID := uuidv7.MustBytes()
+	roles.rolesByName["user"] = &auth.Role{ID: userRoleID, Name: "user"}
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       userID,
+		Email:    "user@example.com",
+		Timezone: tzpkg.WithDefault(""),
+		RoleID:   userRoleID,
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	cfg := config.AuthConfig{
+		SSOStateTTL: time.Minute,
+	}
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub-link", Email: "user@example.com", Name: "Jane Doe"}}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+	authURL, err := svc.BeginMicrosoftLink(context.Background(), userID)
+	if err != nil || authURL == "" {
+		t.Fatalf("expected auth url")
+	}
+
+	parsedURL, parseErr := url.Parse(authURL)
+	if parseErr != nil {
+		t.Fatalf("parse auth url: %v", parseErr)
+	}
+	state := parsedURL.Query().Get("state")
+	identity, err := svc.CompleteMicrosoftLink(context.Background(), "code", state)
+	if err != nil || identity == nil {
+		t.Fatalf("complete link failed: %v", err)
+	}
+	if identity.Provider != "microsoft" || identity.ProviderSubject != "sub-link" {
+		t.Fatalf("unexpected linked identity: %+v", identity)
+	}
+}
+
+func TestAuthService_RevokeRefreshToken(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	repo.CreateUser(context.Background(), user)
+
+	pair, err := svc.IssueTokens(context.Background(), user)
+	if err != nil {
+		t.Fatalf("issue tokens: %v", err)
+	}
+
+	if err := svc.RevokeRefreshToken(context.Background(), pair.RefreshToken); err != nil {
+		t.Fatalf("revoke failed: %v", err)
+	}
+	if _, err := svc.RefreshTokens(context.Background(), pair.RefreshToken); err == nil {
+		t.Fatalf("expected refresh to fail after revoke")
+	}
+}
+
+func TestAuthService_RevokeRefreshToken_Invalid(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	cfg := config.AuthConfig{JWTRefreshSecret: "refresh"}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if err := svc.RevokeRefreshToken(context.Background(), "bad"); err != nil {
+		t.Fatalf("expected nil error")
+	}
+}
+
+func TestAuthService_VerifyAndDisableTOTP(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, err := NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+	if err != nil {
+		t.Fatalf("protector: %v", err)
+	}
+
+	cfg := config.AuthConfig{
+		TOTPChallengeTTL: time.Minute,
+		TOTPIssuer:       "Wucher",
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+
+	userID := uuidv7.MustBytes()
+	secret, _, _, err := svc.SetupTOTP(context.Background(), userID, "user@example.com")
+	if err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	code, _ := totp.GenerateCode(secret, time.Now().UTC())
+	ok, err := svc.ConfirmTOTP(context.Background(), userID, code)
+	if err != nil || !ok {
+		t.Fatalf("confirm failed")
+	}
+
+	ok, err = svc.VerifyTOTP(context.Background(), userID, code)
+	if err != nil || !ok {
+		t.Fatalf("verify failed")
+	}
+	rec, _ := repo.GetUserTOTP(context.Background(), userID)
+	if rec == nil || rec.LastUsedAt == nil {
+		t.Fatalf("last_used_at not updated")
+	}
+
+	if err := svc.DisableTOTP(context.Background(), userID); err != nil {
+		t.Fatalf("disable failed: %v", err)
+	}
+	enabled, _ := svc.IsTOTPEnabled(context.Background(), userID)
+	if enabled {
+		t.Fatalf("expected disabled")
+	}
+
+	secretAgain, _, _, err := svc.SetupTOTP(context.Background(), userID, "user@example.com")
+	if err != nil {
+		t.Fatalf("setup again: %v", err)
+	}
+	if secretAgain != secret {
+		t.Fatalf("expected existing secret to be reused after disable")
+	}
+
+	code2, _ := totp.GenerateCode(secretAgain, time.Now().UTC())
+	ok, err = svc.ConfirmTOTP(context.Background(), userID, code2)
+	if err != nil || !ok {
+		t.Fatalf("confirm after disable failed")
+	}
+	enabled, _ = svc.IsTOTPEnabled(context.Background(), userID)
+	if !enabled {
+		t.Fatalf("expected enabled after reconfirm")
+	}
+}
+
+func TestAuthService_SetAuditLogger(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	if svc.audit != nil {
+		t.Fatalf("expected nil audit logger by default")
+	}
+
+	auditSvc := &AuditLogService{}
+	svc.SetAuditLogger(auditSvc)
+	if svc.audit != auditSvc {
+		t.Fatalf("expected audit logger to be set")
+	}
+
+	svc.SetAuditLogger(nil)
+	if svc.audit != nil {
+		t.Fatalf("expected audit logger to be cleared")
+	}
+}
+
+func TestAuthService_logServiceAudit(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	// Should no-op when audit logger is not configured.
+	svc.logServiceAudit(context.Background(), "auth.test.noop", nil, false, "noop", nil)
+
+	auditRepo := &mockAuditRepo{}
+	auditSvc := NewAuditLogService(auditRepo, AuditLogServiceDependencies{QueueSize: 8, Workers: 1})
+	svc.SetAuditLogger(auditSvc)
+
+	userID := uuidv7.MustBytes()
+	svc.logServiceAudit(context.Background(), "auth.test.action", userID, true, "ok", map[string]any{
+		"source": "unit-test",
+	})
+
+	deadline := time.Now().Add(500 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		auditRepo.mu.Lock()
+		n := len(auditRepo.entries)
+		auditRepo.mu.Unlock()
+		if n > 0 {
+			break
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	auditRepo.mu.Lock()
+	defer auditRepo.mu.Unlock()
+	if len(auditRepo.entries) != 1 {
+		t.Fatalf("expected 1 audit entry, got %d", len(auditRepo.entries))
+	}
+	entry := auditRepo.entries[0]
+	if entry.Layer != "service" {
+		t.Fatalf("expected layer service, got %q", entry.Layer)
+	}
+	if entry.Action != "auth.test.action" {
+		t.Fatalf("expected action auth.test.action, got %q", entry.Action)
+	}
+	if !entry.Success {
+		t.Fatalf("expected success=true")
+	}
+	if entry.Message != "ok" {
+		t.Fatalf("expected message ok, got %q", entry.Message)
+	}
+	if string(entry.ActorUserID) != string(userID) {
+		t.Fatalf("expected actor user id to match")
+	}
+}
+
+func TestAuthService_Getters(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	roles.rolesByID[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	cfg := config.AuthConfig{
+		JWTAccessTTL:               time.Minute,
+		JWTRefreshTTL:              time.Hour,
+		JWTCookieDomain:            "example.com",
+		JWTCookieSecure:            true,
+		JWTCookieSameSite:          "Lax",
+		JWTAccessCookieName:        "at",
+		JWTRefreshCookieName:       "rt",
+		ForgotPasswordIPRateMax:    7,
+		ForgotPasswordIPRateWindow: 2 * time.Minute,
+		DefaultRoleName:            "admin",
+		DisableRegister:            true,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	_ = svc.AccessTTL()
+	_ = svc.RefreshTTL()
+	_ = svc.CookieDomain()
+	_ = svc.CookieSecure()
+	_ = svc.CookieSameSite()
+	_ = svc.AccessCookieName()
+	_ = svc.RefreshCookieName()
+	_ = svc.DefaultRoleName()
+	_ = svc.RegisterDisabled()
+	if got := svc.ForgotPasswordIPRateMax(); got != cfg.ForgotPasswordIPRateMax {
+		t.Fatalf("expected ForgotPasswordIPRateMax=%d, got %d", cfg.ForgotPasswordIPRateMax, got)
+	}
+	if got := svc.ForgotPasswordIPRateWindow(); got != cfg.ForgotPasswordIPRateWindow {
+		t.Fatalf("expected ForgotPasswordIPRateWindow=%s, got %s", cfg.ForgotPasswordIPRateWindow, got)
+	}
+
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com"}
+	repo.CreateUser(context.Background(), user)
+	if u, _ := svc.GetUserByID(context.Background(), user.ID); u == nil {
+		t.Fatalf("get user failed")
+	}
+	if r, _ := svc.GetRoleByID(context.Background(), roleID); r == nil {
+		t.Fatalf("get role failed")
+	}
+}
+
+func TestAuthService_ForgotPassword_StoresOnlyTokenHash(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	emailQueue := &mockEmailQueue{}
+
+	user := &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "user@example.com",
+		FirstName: "John",
+		LastName:  "Doe",
+		RoleID:    uuidv7.MustBytes(),
+	}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	cfg := config.AuthConfig{
+		PasswordResetURL:            "https://app.example.com/reset-password",
+		PasswordResetTTL:            20 * time.Minute,
+		ForgotPasswordEmailCooldown: 0,
+		ForgotPasswordMinDuration:   0,
+	}
+	svc := NewAuthService(repo, roles, nil, emailQueue, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	svc.ForgotPassword(context.Background(), user.Email, "127.0.0.1", "test-agent")
+
+	if repo.lastResetToken == nil {
+		t.Fatalf("expected password reset token to be persisted")
+	}
+	if len(repo.lastResetToken.TokenHash) != sha256.Size {
+		t.Fatalf("expected token hash length %d, got %d", sha256.Size, len(repo.lastResetToken.TokenHash))
+	}
+	if emailQueue.last == nil {
+		t.Fatalf("expected reset email to be enqueued")
+	}
+
+	rawToken := extractTokenValue(emailQueue.last.Body)
+	if rawToken == "" {
+		t.Fatalf("expected raw token in email body")
+	}
+	if bytes.Equal([]byte(rawToken), repo.lastResetToken.TokenHash) {
+		t.Fatalf("raw token must not be stored in DB")
+	}
+	if !bytes.Equal(hashToken(rawToken), repo.lastResetToken.TokenHash) {
+		t.Fatalf("stored hash does not match hashed raw token")
+	}
+}
+
+func TestAuthService_ResetPassword_ExpiredTokenRejected(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "user@example.com"}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	token := "expired-token"
+	tokenHash := hashToken(token)
+	repo.resetTokens[string(tokenHash)] = &auth.PasswordResetToken{
+		ID:        uuidv7.MustBytes(),
+		UserID:    user.ID,
+		TokenHash: tokenHash,
+		ExpiresAt: time.Now().UTC().Add(-time.Minute),
+	}
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		PasswordResetTTL: 20 * time.Minute,
+	}
+	svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if err := svc.ResetPassword(context.Background(), token, "NewPassword123!"); !errors.Is(err, ErrInvalidResetLink) {
+		t.Fatalf("expected ErrInvalidResetLink, got %v", err)
+	}
+}
+
+func TestAuthService_ResetPassword_SingleUseAndSessionInvalidation(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+		PasswordResetTTL: 20 * time.Minute,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	origHash, origSalt, err := svc.hashPassword("OldPassword123!")
+	if err != nil {
+		t.Fatalf("hash password: %v", err)
+	}
+	user := &auth.User{
+		ID:           uuidv7.MustBytes(),
+		Email:        "user@example.com",
+		PasswordHash: origHash,
+		SaltValue:    origSalt,
+		RoleID:       uuidv7.MustBytes(),
+	}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	pair, err := svc.IssueTokens(context.Background(), user)
+	if err != nil {
+		t.Fatalf("issue tokens: %v", err)
+	}
+
+	tokenA := "reset-token-a"
+	tokenB := "reset-token-b"
+	hashA := hashToken(tokenA)
+	hashB := hashToken(tokenB)
+	repo.resetTokens[string(hashA)] = &auth.PasswordResetToken{
+		ID:        uuidv7.MustBytes(),
+		UserID:    user.ID,
+		TokenHash: hashA,
+		ExpiresAt: time.Now().UTC().Add(20 * time.Minute),
+	}
+	repo.resetTokens[string(hashB)] = &auth.PasswordResetToken{
+		ID:        uuidv7.MustBytes(),
+		UserID:    user.ID,
+		TokenHash: hashB,
+		ExpiresAt: time.Now().UTC().Add(20 * time.Minute),
+	}
+
+	if err := svc.ResetPassword(context.Background(), tokenA, "NewPassword123!Long"); err != nil {
+		t.Fatalf("reset password: %v", err)
+	}
+	if bytes.Equal(user.PasswordHash, origHash) {
+		t.Fatalf("expected password hash to change")
+	}
+	if !svc.verifyPassword("NewPassword123!Long", user.PasswordHash, user.SaltValue) {
+		t.Fatalf("expected new password to verify")
+	}
+	if repo.resetTokens[string(hashA)].UsedAt == nil {
+		t.Fatalf("used token should be marked used")
+	}
+	if repo.resetTokens[string(hashB)].UsedAt == nil {
+		t.Fatalf("other active tokens should be invalidated")
+	}
+
+	if _, err := svc.ParseAccessToken(context.Background(), pair.AccessToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected old access token to be invalid after reset, got %v", err)
+	}
+	if _, err := svc.RefreshTokens(context.Background(), pair.RefreshToken); !errors.Is(err, ErrInvalidToken) {
+		t.Fatalf("expected old refresh token to be invalid after reset, got %v", err)
+	}
+	if err := svc.ResetPassword(context.Background(), tokenA, "AnotherPassword123!"); !errors.Is(err, ErrInvalidResetLink) {
+		t.Fatalf("expected token reuse to fail, got %v", err)
+	}
+}
+
+func TestAuthService_ForgotPassword_InvalidatesPreviousTokensAndAppliesCooldown(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	user := &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "user@example.com",
+		FirstName: "John",
+		LastName:  "Doe",
+		RoleID:    uuidv7.MustBytes(),
+	}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	cfgNoCooldown := config.AuthConfig{
+		PasswordResetURL:            "https://app.example.com/reset-password",
+		PasswordResetTTL:            20 * time.Minute,
+		ForgotPasswordEmailCooldown: 0,
+		ForgotPasswordMinDuration:   0,
+	}
+	svcNoCooldown := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfgNoCooldown})
+	svcNoCooldown.ForgotPassword(context.Background(), user.Email, "127.0.0.1", "ua-1")
+	first := repo.lastResetToken
+	if first == nil {
+		t.Fatalf("expected first token")
+	}
+	svcNoCooldown.ForgotPassword(context.Background(), user.Email, "127.0.0.1", "ua-2")
+	second := repo.lastResetToken
+	if second == nil || bytes.Equal(first.TokenHash, second.TokenHash) {
+		t.Fatalf("expected second distinct token")
+	}
+	if rec := repo.resetTokens[string(first.TokenHash)]; rec == nil || rec.UsedAt == nil {
+		t.Fatalf("previous active token should be invalidated by new request")
+	}
+
+	cfgCooldown := config.AuthConfig{
+		PasswordResetURL:            "https://app.example.com/reset-password",
+		PasswordResetTTL:            20 * time.Minute,
+		ForgotPasswordEmailCooldown: 2 * time.Minute,
+		ForgotPasswordMinDuration:   0,
+	}
+	repo2 := newMockAuthRepo()
+	if err := repo2.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user for cooldown: %v", err)
+	}
+	svcCooldown := NewAuthService(repo2, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfgCooldown})
+	svcCooldown.ForgotPassword(context.Background(), user.Email, "127.0.0.1", "ua")
+	countAfterFirst := len(repo2.resetTokens)
+	svcCooldown.ForgotPassword(context.Background(), user.Email, "127.0.0.1", "ua")
+	if len(repo2.resetTokens) != countAfterFirst {
+		t.Fatalf("expected second request to be throttled by email cooldown")
+	}
+}
+
+func TestAuthService_ForgotPassword_AdditionalBranches(t *testing.T) {
+	t.Run("empty email returns without issuing token", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			ForgotPasswordMinDuration: 0,
+		}})
+
+		svc.ForgotPassword(context.Background(), "   ", "127.0.0.1", "ua")
+		if repo.lastResetToken != nil {
+			t.Fatalf("did not expect reset token for empty email")
+		}
+	})
+
+	t.Run("lookup error applies cooldown and does not issue token", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.getByMailErr = errors.New("db lookup failed")
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			ForgotPasswordEmailCooldown: time.Minute,
+			ForgotPasswordMinDuration:   0,
+		}})
+
+		svc.ForgotPassword(context.Background(), "user@example.com", "127.0.0.1", "ua")
+
+		if repo.lastResetToken != nil {
+			t.Fatalf("did not expect reset token when lookup fails")
+		}
+		if tokens.lastKey == "" || !strings.HasPrefix(tokens.lastKey, "auth:forgot_password:cooldown:") {
+			t.Fatalf("expected cooldown key to be stored, got %q", tokens.lastKey)
+		}
+	})
+
+	t.Run("unknown email is hidden and still applies cooldown", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			ForgotPasswordEmailCooldown: time.Minute,
+			ForgotPasswordMinDuration:   0,
+		}})
+
+		svc.ForgotPassword(context.Background(), "missing@example.com", "127.0.0.1", "ua")
+
+		if repo.lastResetToken != nil {
+			t.Fatalf("did not expect reset token for unknown account")
+		}
+		if tokens.lastKey == "" || !strings.HasPrefix(tokens.lastKey, "auth:forgot_password:cooldown:") {
+			t.Fatalf("expected cooldown key to be stored, got %q", tokens.lastKey)
+		}
+	})
+
+	t.Run("issue failure path still returns and applies cooldown", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.createResetTokenErr = errors.New("insert failed")
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		user := &auth.User{
+			ID:    uuidv7.MustBytes(),
+			Email: "user@example.com",
+		}
+		if err := repo.CreateUser(context.Background(), user); err != nil {
+			t.Fatalf("create user: %v", err)
+		}
+
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			PasswordResetURL:            "https://app.example.com/reset-password",
+			PasswordResetTTL:            20 * time.Minute,
+			ForgotPasswordEmailCooldown: time.Minute,
+			ForgotPasswordMinDuration:   0,
+		}})
+
+		svc.ForgotPassword(context.Background(), user.Email, "127.0.0.1", "ua")
+
+		if repo.lastResetToken != nil {
+			t.Fatalf("did not expect reset token persisted on create error")
+		}
+		if tokens.lastKey == "" || !strings.HasPrefix(tokens.lastKey, "auth:forgot_password:cooldown:") {
+			t.Fatalf("expected cooldown key to be stored, got %q", tokens.lastKey)
+		}
+	})
+}
+
+func TestAuthService_ResetPassword_AdditionalBranches(t *testing.T) {
+	baseCfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		PasswordResetTTL: 20 * time.Minute,
+	}
+
+	t.Run("missing token or password", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		if err := svc.ResetPassword(context.Background(), "", "NewPassword123!"); !errors.Is(err, ErrInvalidResetLink) {
+			t.Fatalf("expected ErrInvalidResetLink for empty token, got %v", err)
+		}
+		if err := svc.ResetPassword(context.Background(), "token", ""); !errors.Is(err, ErrInvalidResetLink) {
+			t.Fatalf("expected ErrInvalidResetLink for empty password, got %v", err)
+		}
+	})
+
+	t.Run("consume repository error is returned", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.consumeResetErr = errors.New("consume failed")
+		roles := newMockRoleRepo()
+		svc := NewAuthService(repo, roles, nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		err := svc.ResetPassword(context.Background(), "token", "NewPassword123!")
+		if !errors.Is(err, repo.consumeResetErr) {
+			t.Fatalf("expected consume error, got %v", err)
+		}
+	})
+
+	t.Run("session version bump failure is ignored", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		tokens.getErr = errors.New("token store unavailable")
+
+		user := &auth.User{
+			ID:    uuidv7.MustBytes(),
+			Email: "user@example.com",
+		}
+		if err := repo.CreateUser(context.Background(), user); err != nil {
+			t.Fatalf("create user: %v", err)
+		}
+		token := "reset-token"
+		tokenHash := hashToken(token)
+		repo.resetTokens[string(tokenHash)] = &auth.PasswordResetToken{
+			ID:        uuidv7.MustBytes(),
+			UserID:    user.ID,
+			TokenHash: tokenHash,
+			ExpiresAt: time.Now().UTC().Add(20 * time.Minute),
+		}
+
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+		if err := svc.ResetPassword(context.Background(), token, "NewPassword123!"); err != nil {
+			t.Fatalf("expected reset to succeed even when bump session version fails, got %v", err)
+		}
+		if !svc.verifyPassword("NewPassword123!", user.PasswordHash, user.SaltValue) {
+			t.Fatalf("expected password to be updated")
+		}
+	})
+}
+
+func TestAuthService_sendInviteSetPassword_Branches(t *testing.T) {
+	user := &auth.User{
+		ID:    uuidv7.MustBytes(),
+		Email: "invitee@example.com",
+	}
+
+	t.Run("skip when token store is nil", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			SetPasswordURL: "https://app.example.com/set-password",
+			InviteTTL:      time.Minute,
+		}})
+		if err := svc.sendInviteSetPassword(context.Background(), user); err != nil {
+			t.Fatalf("expected nil error when token store is nil, got %v", err)
+		}
+	})
+
+	t.Run("skip when set password url is empty", func(t *testing.T) {
+		tokens := newMockTokenStore()
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			InviteTTL: time.Minute,
+		}})
+		if err := svc.sendInviteSetPassword(context.Background(), user); err != nil {
+			t.Fatalf("expected nil error when url is empty, got %v", err)
+		}
+		if tokens.setCount != 0 {
+			t.Fatalf("expected no token stored when url is empty")
+		}
+	})
+
+	t.Run("random token generation error", func(t *testing.T) {
+		orig := rand.Reader
+		rand.Reader = errReader{}
+		defer func() { rand.Reader = orig }()
+
+		tokens := newMockTokenStore()
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			SetPasswordURL: "https://app.example.com/set-password",
+			InviteTTL:      time.Minute,
+		}})
+		if err := svc.sendInviteSetPassword(context.Background(), user); !errors.Is(err, io.ErrUnexpectedEOF) {
+			t.Fatalf("expected random token error, got %v", err)
+		}
+	})
+
+	t.Run("token store error", func(t *testing.T) {
+		tokens := newMockTokenStore()
+		tokens.setErr = errors.New("token set failed")
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			SetPasswordURL: "https://app.example.com/set-password",
+			InviteTTL:      time.Minute,
+		}})
+		if err := svc.sendInviteSetPassword(context.Background(), user); !errors.Is(err, tokens.setErr) {
+			t.Fatalf("expected token store error, got %v", err)
+		}
+	})
+
+	t.Run("queue enqueue error", func(t *testing.T) {
+		tokens := newMockTokenStore()
+		queue := &mockEmailQueue{err: errors.New("queue failed")}
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), tokens, queue, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			SetPasswordURL: "https://app.example.com/set-password",
+			InviteTTL:      time.Minute,
+		}})
+		if err := svc.sendInviteSetPassword(context.Background(), user); !errors.Is(err, queue.err) {
+			t.Fatalf("expected queue error, got %v", err)
+		}
+	})
+
+	t.Run("queue success", func(t *testing.T) {
+		tokens := newMockTokenStore()
+		queue := &mockEmailQueue{}
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), tokens, queue, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			SetPasswordURL: "https://app.example.com/set-password",
+			InviteTTL:      time.Minute,
+		}})
+		if err := svc.sendInviteSetPassword(context.Background(), user); err != nil {
+			t.Fatalf("expected nil error, got %v", err)
+		}
+		if queue.last == nil {
+			t.Fatalf("expected invite email to be queued")
+		}
+		if !strings.Contains(queue.last.Body, "token=") {
+			t.Fatalf("expected invite email body to include token")
+		}
+	})
+
+	t.Run("no queue and no mailer returns nil", func(t *testing.T) {
+		tokens := newMockTokenStore()
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			SetPasswordURL: "https://app.example.com/set-password",
+			InviteTTL:      time.Minute,
+		}})
+		if err := svc.sendInviteSetPassword(context.Background(), user); err != nil {
+			t.Fatalf("expected nil error, got %v", err)
+		}
+		if tokens.setCount != 1 {
+			t.Fatalf("expected invite token to be stored once")
+		}
+	})
+}
+
+func TestAuthService_ResetSetupAndInviteJWT_Branches(t *testing.T) {
+	newProtectedAuthService := func(t *testing.T) (*mockAuthRepo, *AuthService, *auth.User) {
+		t.Helper()
+		repo := newMockAuthRepo()
+		roles := newMockRoleRepo()
+		tokens := newMockTokenStore()
+		key := make([]byte, 32)
+		for i := range key {
+			key[i] = byte(i + 1)
+		}
+		protector, err := NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+		if err != nil {
+			t.Fatalf("protector: %v", err)
+		}
+		cfg := config.AuthConfig{
+			PasswordPepper:  "pepper",
+			HashTime:        1,
+			HashMemoryKB:    64 * 1024,
+			HashThreads:     4,
+			HashKeyLen:      32,
+			JWTAccessSecret: "access",
+			InviteTTL:       time.Minute,
+			SetPasswordURL:  "https://app.example.com/set-password",
+		}
+		svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+		user := &auth.User{ID: uuidv7.MustBytes(), Email: "user@example.com"}
+		hash, salt, err := svc.hashPassword("Password123!")
+		if err != nil {
+			t.Fatalf("hash password: %v", err)
+		}
+		user.PasswordHash = hash
+		user.SaltValue = salt
+		if err := repo.CreateUser(context.Background(), user); err != nil {
+			t.Fatalf("create user: %v", err)
+		}
+		return repo, svc, user
+	}
+
+	t.Run("delete totp setup branches", func(t *testing.T) {
+		repo, svc, user := newProtectedAuthService(t)
+		if err := svc.DeleteTOTPSetup(context.Background(), []byte("short")); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token, got %v", err)
+		}
+		repo.totp[string(user.ID)] = &auth.UserTOTP{UserID: user.ID}
+		if err := svc.DeleteTOTPSetup(context.Background(), user.ID); err != nil {
+			t.Fatalf("unexpected delete totp error: %v", err)
+		}
+		if _, ok := repo.totp[string(user.ID)]; ok {
+			t.Fatalf("expected totp setup deleted")
+		}
+		repo.totp[string(user.ID)] = &auth.UserTOTP{UserID: user.ID}
+		repo.deleteTOTPErr = errors.New("delete totp failed")
+		if err := svc.DeleteTOTPSetup(context.Background(), user.ID); !errors.Is(err, repo.deleteTOTPErr) {
+			t.Fatalf("expected delete totp error, got %v", err)
+		}
+	})
+
+	t.Run("delete webauthn setup branches", func(t *testing.T) {
+		repo, svc, user := newProtectedAuthService(t)
+		if err := svc.DeleteWebAuthnSetup(context.Background(), []byte("short")); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token, got %v", err)
+		}
+		repo.webauthnCredentials[string(user.ID)] = []auth.UserWebAuthnCredential{{ID: uuidv7.MustBytes(), UserID: user.ID}}
+		if err := svc.DeleteWebAuthnSetup(context.Background(), user.ID); err != nil {
+			t.Fatalf("unexpected delete webauthn error: %v", err)
+		}
+		if len(repo.webauthnCredentials[string(user.ID)]) != 0 {
+			t.Fatalf("expected webauthn credentials deleted")
+		}
+		repo.webauthnCredentials[string(user.ID)] = []auth.UserWebAuthnCredential{{ID: uuidv7.MustBytes(), UserID: user.ID}}
+		repo.deleteWebAuthnErr = errors.New("delete webauthn failed")
+		if err := svc.DeleteWebAuthnSetup(context.Background(), user.ID); !errors.Is(err, repo.deleteWebAuthnErr) {
+			t.Fatalf("expected delete webauthn error, got %v", err)
+		}
+	})
+
+	t.Run("authorize with pin or password branches", func(t *testing.T) {
+		repo, svc, user := newProtectedAuthService(t)
+		if err := svc.authorizeWithPINOrPassword(context.Background(), user.ID, "unknown", "", ""); !errors.Is(err, ErrInvalidReauthMethod) {
+			t.Fatalf("expected invalid reauth method, got %v", err)
+		}
+		repo.getByIDErr = errors.New("get user failed")
+		if err := svc.authorizeWithPINOrPassword(context.Background(), user.ID, "password", "", "Password123!"); !errors.Is(err, repo.getByIDErr) {
+			t.Fatalf("expected repo get error, got %v", err)
+		}
+		repo.getByIDErr = nil
+		delete(repo.users, string(user.ID))
+		if err := svc.authorizeWithPINOrPassword(context.Background(), user.ID, "password", "", "Password123!"); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token when user missing, got %v", err)
+		}
+		if err := repo.CreateUser(context.Background(), user); err != nil {
+			t.Fatalf("recreate user: %v", err)
+		}
+		if err := svc.authorizeWithPINOrPassword(context.Background(), user.ID, "password", "", "WrongPassword!"); !errors.Is(err, ErrInvalidCredentials) {
+			t.Fatalf("expected invalid credentials, got %v", err)
+		}
+		if err := svc.authorizeWithPINOrPassword(context.Background(), user.ID, "password", "", "Password123!"); err != nil {
+			t.Fatalf("expected password auth success, got %v", err)
+		}
+		if err := svc.authorizeWithPINOrPassword(context.Background(), user.ID, "pin", "123456", ""); !errors.Is(err, ErrSecurityPINNotSet) {
+			t.Fatalf("expected pin not set, got %v", err)
+		}
+		if err := svc.SetSecurityPIN(context.Background(), user.ID, "123456"); err != nil {
+			t.Fatalf("set pin: %v", err)
+		}
+		if err := svc.authorizeWithPINOrPassword(context.Background(), user.ID, "pin", "000000", ""); !errors.Is(err, ErrInvalidSecurityPIN) {
+			t.Fatalf("expected invalid security pin, got %v", err)
+		}
+		if err := svc.authorizeWithPINOrPassword(context.Background(), user.ID, "pin", "123456", ""); err != nil {
+			t.Fatalf("expected pin auth success, got %v", err)
+		}
+	})
+
+	t.Run("reset totp setup branches", func(t *testing.T) {
+		repo, svc, user := newProtectedAuthService(t)
+		if err := svc.ResetTOTPSetup(context.Background(), []byte("short"), "password", "", "Password123!"); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token, got %v", err)
+		}
+		repo.totp[string(user.ID)] = &auth.UserTOTP{UserID: user.ID}
+		if err := svc.ResetTOTPSetup(context.Background(), user.ID, "password", "", "Password123!"); err != nil {
+			t.Fatalf("expected reset totp success, got %v", err)
+		}
+		repo.totp[string(user.ID)] = &auth.UserTOTP{UserID: user.ID}
+		if err := svc.ResetTOTPSetup(context.Background(), user.ID, "password", "", "WrongPassword!"); !errors.Is(err, ErrInvalidCredentials) {
+			t.Fatalf("expected invalid credentials, got %v", err)
+		}
+		repo.deleteTOTPErr = errors.New("delete totp failed")
+		if err := svc.ResetTOTPSetup(context.Background(), user.ID, "password", "", "Password123!"); !errors.Is(err, repo.deleteTOTPErr) {
+			t.Fatalf("expected delete totp error, got %v", err)
+		}
+	})
+
+	t.Run("reset webauthn setup branches", func(t *testing.T) {
+		repo, svc, user := newProtectedAuthService(t)
+		if err := svc.ResetWebAuthnSetup(context.Background(), []byte("short"), "password", "", "Password123!"); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token, got %v", err)
+		}
+		repo.webauthnCredentials[string(user.ID)] = []auth.UserWebAuthnCredential{{ID: uuidv7.MustBytes(), UserID: user.ID}}
+		if err := svc.ResetWebAuthnSetup(context.Background(), user.ID, "password", "", "Password123!"); err != nil {
+			t.Fatalf("expected reset webauthn success, got %v", err)
+		}
+		repo.webauthnCredentials[string(user.ID)] = []auth.UserWebAuthnCredential{{ID: uuidv7.MustBytes(), UserID: user.ID}}
+		if err := svc.ResetWebAuthnSetup(context.Background(), user.ID, "password", "", "WrongPassword!"); !errors.Is(err, ErrInvalidCredentials) {
+			t.Fatalf("expected invalid credentials, got %v", err)
+		}
+		repo.deleteWebAuthnErr = errors.New("delete webauthn failed")
+		if err := svc.ResetWebAuthnSetup(context.Background(), user.ID, "password", "", "Password123!"); !errors.Is(err, repo.deleteWebAuthnErr) {
+			t.Fatalf("expected delete webauthn error, got %v", err)
+		}
+	})
+
+	t.Run("issue invite jwt branches", func(t *testing.T) {
+		_, svc, user := newProtectedAuthService(t)
+		if _, _, err := svc.issueInviteJWT(nil); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for nil user, got %v", err)
+		}
+		if _, _, err := svc.issueInviteJWT(&auth.User{}); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for invalid user id, got %v", err)
+		}
+		orig := rand.Reader
+		rand.Reader = errReader{}
+		if _, _, err := svc.issueInviteJWT(user); !errors.Is(err, io.ErrUnexpectedEOF) {
+			t.Fatalf("expected random token error, got %v", err)
+		}
+		rand.Reader = orig
+		token, jti, err := svc.issueInviteJWT(user)
+		if err != nil {
+			t.Fatalf("unexpected issue invite jwt error: %v", err)
+		}
+		if strings.TrimSpace(token) == "" || strings.TrimSpace(jti) == "" {
+			t.Fatalf("expected token and jti")
+		}
+	})
+
+	t.Run("parse invite jwt branches", func(t *testing.T) {
+		_, svc, user := newProtectedAuthService(t)
+		if _, _, _, err := svc.parseInviteJWT(""); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for empty token, got %v", err)
+		}
+		svcNoSecret := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), newMockTokenStore(), nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if _, _, _, err := svcNoSecret.parseInviteJWT("token"); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for missing secret, got %v", err)
+		}
+		if _, _, _, err := svc.parseInviteJWT("bad"); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for malformed jwt, got %v", err)
+		}
+
+		validToken, _, err := svc.issueInviteJWT(user)
+		if err != nil {
+			t.Fatalf("issue invite jwt: %v", err)
+		}
+		gotUserID, gotJTI, gotEmail, err := svc.parseInviteJWT(validToken)
+		if err != nil {
+			t.Fatalf("parse valid invite jwt: %v", err)
+		}
+		if string(gotUserID) != string(user.ID) || strings.TrimSpace(gotJTI) == "" || gotEmail != strings.ToLower(user.Email) {
+			t.Fatalf("unexpected parsed invite jwt values")
+		}
+
+		claimsWrongType := jwt.MapClaims{
+			"type":  "wrong",
+			"sub":   mustUUIDStringAuth(t, user.ID),
+			"email": strings.ToLower(user.Email),
+			"jti":   "jti-1",
+			"iat":   time.Now().Unix(),
+			"exp":   time.Now().Add(time.Minute).Unix(),
+		}
+		wrongTypeToken, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claimsWrongType).SignedString([]byte(svc.cfg.JWTAccessSecret))
+		if _, _, _, err := svc.parseInviteJWT(wrongTypeToken); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for wrong type, got %v", err)
+		}
+
+		claimsMissing := jwt.MapClaims{
+			"type": "invite_set_password",
+			"sub":  mustUUIDStringAuth(t, user.ID),
+			"iat":  time.Now().Unix(),
+			"exp":  time.Now().Add(time.Minute).Unix(),
+		}
+		missingClaimsToken, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claimsMissing).SignedString([]byte(svc.cfg.JWTAccessSecret))
+		if _, _, _, err := svc.parseInviteJWT(missingClaimsToken); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for missing claims, got %v", err)
+		}
+
+		claimsBadSub := jwt.MapClaims{
+			"type":  "invite_set_password",
+			"sub":   "not-a-uuid",
+			"email": strings.ToLower(user.Email),
+			"jti":   "jti-2",
+			"iat":   time.Now().Unix(),
+			"exp":   time.Now().Add(time.Minute).Unix(),
+		}
+		badSubToken, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claimsBadSub).SignedString([]byte(svc.cfg.JWTAccessSecret))
+		if _, _, _, err := svc.parseInviteJWT(badSubToken); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for invalid sub, got %v", err)
+		}
+	})
+}
+
+func mustUUIDStringAuth(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestAuthService_createAndSendPasswordReset_Branches(t *testing.T) {
+	user := &auth.User{
+		ID:    uuidv7.MustBytes(),
+		Email: "user@example.com",
+	}
+
+	baseCfg := config.AuthConfig{
+		PasswordResetURL: "https://app.example.com/reset-password",
+		PasswordResetTTL: 20 * time.Minute,
+	}
+
+	t.Run("skip when reset url is empty", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			PasswordResetURL: "",
+			PasswordResetTTL: 20 * time.Minute,
+		}})
+		if err := svc.createAndSendPasswordReset(context.Background(), user, "127.0.0.1", "ua"); err != nil {
+			t.Fatalf("expected nil error when url is empty, got %v", err)
+		}
+	})
+
+	t.Run("random token generation error", func(t *testing.T) {
+		orig := rand.Reader
+		rand.Reader = errReader{}
+		defer func() { rand.Reader = orig }()
+
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+		if err := svc.createAndSendPasswordReset(context.Background(), user, "127.0.0.1", "ua"); !errors.Is(err, io.ErrUnexpectedEOF) {
+			t.Fatalf("expected random token error, got %v", err)
+		}
+	})
+
+	t.Run("invalidate active tokens error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.invalidateResetTokensErr = errors.New("invalidate failed")
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		if err := svc.createAndSendPasswordReset(context.Background(), user, "127.0.0.1", "ua"); !errors.Is(err, repo.invalidateResetTokensErr) {
+			t.Fatalf("expected invalidate error, got %v", err)
+		}
+	})
+
+	t.Run("create token error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.createResetTokenErr = errors.New("create reset failed")
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		if err := svc.createAndSendPasswordReset(context.Background(), user, "127.0.0.1", "ua"); !errors.Is(err, repo.createResetTokenErr) {
+			t.Fatalf("expected create token error, got %v", err)
+		}
+	})
+
+	t.Run("invalid reset url fails before token is persisted", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			PasswordResetURL: "http://",
+			PasswordResetTTL: 20 * time.Minute,
+		}})
+
+		if err := svc.createAndSendPasswordReset(context.Background(), user, "127.0.0.1", "ua"); err == nil {
+			t.Fatalf("expected invalid password reset url error")
+		}
+		if repo.lastResetToken != nil {
+			t.Fatalf("token should not be persisted when reset url is invalid")
+		}
+	})
+
+	t.Run("queue enqueue error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		queue := &mockEmailQueue{err: errors.New("queue failed")}
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, queue, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		if err := svc.createAndSendPasswordReset(context.Background(), user, "127.0.0.1", "ua"); !errors.Is(err, queue.err) {
+			t.Fatalf("expected queue error, got %v", err)
+		}
+	})
+
+	t.Run("queue success", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		queue := &mockEmailQueue{}
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, queue, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		if err := svc.createAndSendPasswordReset(context.Background(), user, "127.0.0.1", "ua"); err != nil {
+			t.Fatalf("expected nil error, got %v", err)
+		}
+		if queue.last == nil {
+			t.Fatalf("expected password reset email to be queued")
+		}
+		if strings.TrimSpace(queue.last.HTMLBody) == "" {
+			t.Fatalf("expected non-empty html body in queued reset email")
+		}
+	})
+
+	t.Run("no queue and no mailer returns nil", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		if err := svc.createAndSendPasswordReset(context.Background(), user, "127.0.0.1", "ua"); err != nil {
+			t.Fatalf("expected nil error, got %v", err)
+		}
+		if repo.lastResetToken == nil {
+			t.Fatalf("expected reset token to be persisted")
+		}
+	})
+}
+
+func extractTokenValue(body string) string {
+	idx := strings.Index(body, "token=")
+	if idx == -1 {
+		return ""
+	}
+	token := body[idx+len("token="):]
+	if end := strings.IndexAny(token, " \n\r\t"); end >= 0 {
+		token = token[:end]
+	}
+	return strings.TrimSpace(token)
+}
+
+func TestAuthService_int64Claim(t *testing.T) {
+	tests := []struct {
+		name  string
+		input any
+		want  int64
+	}{
+		{name: "nil", input: nil, want: 0},
+		{name: "float64", input: float64(123.9), want: 123},
+		{name: "float32", input: float32(45.7), want: 45},
+		{name: "int", input: int(12), want: 12},
+		{name: "int64", input: int64(34), want: 34},
+		{name: "int32", input: int32(56), want: 56},
+		{name: "uint", input: uint(78), want: 78},
+		{name: "uint64", input: uint64(90), want: 90},
+		{name: "uint32", input: uint32(21), want: 21},
+		{name: "string valid", input: "1234", want: 1234},
+		{name: "string invalid", input: "12x", want: 0},
+		{name: "default unsupported", input: true, want: 0},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := int64Claim(tc.input)
+			if got != tc.want {
+				t.Fatalf("expected %d, got %d", tc.want, got)
+			}
+		})
+	}
+}
+
+func TestAuthService_truncate(t *testing.T) {
+	t.Run("max less than or equal zero returns original", func(t *testing.T) {
+		in := "abcdef"
+		if got := truncate(in, 0); got != in {
+			t.Fatalf("expected %q, got %q", in, got)
+		}
+	})
+
+	t.Run("value shorter than max returns original", func(t *testing.T) {
+		in := "abc"
+		if got := truncate(in, 5); got != in {
+			t.Fatalf("expected %q, got %q", in, got)
+		}
+	})
+
+	t.Run("value longer than max is truncated", func(t *testing.T) {
+		if got := truncate("abcdef", 3); got != "abc" {
+			t.Fatalf("expected %q, got %q", "abc", got)
+		}
+	})
+}
+
+func TestAuthService_sleepRemaining(t *testing.T) {
+	t.Run("min less than or equal zero returns quickly", func(t *testing.T) {
+		start := time.Now()
+		sleepRemaining(start, 0)
+		if elapsed := time.Since(start); elapsed > 20*time.Millisecond {
+			t.Fatalf("expected quick return, elapsed=%s", elapsed)
+		}
+	})
+
+	t.Run("elapsed already exceeds min so no sleep", func(t *testing.T) {
+		start := time.Now().Add(-30 * time.Millisecond)
+		before := time.Now()
+		sleepRemaining(start, 10*time.Millisecond)
+		if elapsed := time.Since(before); elapsed > 20*time.Millisecond {
+			t.Fatalf("expected no additional sleep, elapsed=%s", elapsed)
+		}
+	})
+
+	t.Run("sleeps remaining duration when elapsed below min", func(t *testing.T) {
+		start := time.Now()
+		min := 15 * time.Millisecond
+		sleepRemaining(start, min)
+		if elapsed := time.Since(start); elapsed < 10*time.Millisecond {
+			t.Fatalf("expected function to sleep, elapsed=%s", elapsed)
+		}
+	})
+}
+
+func TestAuthService_shortEmailHash(t *testing.T) {
+	a := shortEmailHash(" User@Example.com ")
+	b := shortEmailHash("user@example.com")
+	if len(a) != 12 {
+		t.Fatalf("expected short email hash length 12, got %d", len(a))
+	}
+	if a != b {
+		t.Fatalf("expected normalized email hash to be equal, got %q vs %q", a, b)
+	}
+}
+
+func TestAuthService_sanitizeIP(t *testing.T) {
+	t.Run("encrypts ipv4 and can be decrypted", func(t *testing.T) {
+		protector := newIPSecretProtector("pepper")
+		got1 := sanitizeIP("127.0.0.1", protector)
+		got2 := sanitizeIP("127.0.0.1", protector)
+		if got1 == got2 {
+			t.Fatalf("expected randomized ciphertext, got equal values %q", got1)
+		}
+		if got1 == "127.0.0.1" {
+			t.Fatalf("expected ciphertext, got plaintext %q", got1)
+		}
+		if plain := decryptStoredIP(got1, protector); plain != "127.0.0.1" {
+			t.Fatalf("expected decrypted ipv4 value, got %q", plain)
+		}
+	})
+
+	t.Run("normalizes ipv6 before encryption", func(t *testing.T) {
+		protector := newIPSecretProtector("pepper")
+		got1 := sanitizeIP("2001:0db8:0000:0000:0000:0000:0000:0001", protector)
+		got2 := sanitizeIP("2001:db8::1", protector)
+		if plain := decryptStoredIP(got1, protector); plain != "2001:db8::1" {
+			t.Fatalf("expected canonical decrypted ipv6 value, got %q", plain)
+		}
+		if plain := decryptStoredIP(got2, protector); plain != "2001:db8::1" {
+			t.Fatalf("expected canonical decrypted ipv6 value, got %q", plain)
+		}
+	})
+
+	t.Run("wrong key cannot decrypt", func(t *testing.T) {
+		enc := sanitizeIP("127.0.0.1", newIPSecretProtector("pepper-a"))
+		if plain := decryptStoredIP(enc, newIPSecretProtector("pepper-b")); plain == "127.0.0.1" {
+			t.Fatalf("expected decrypt with wrong key to fail")
+		}
+	})
+
+	t.Run("encrypts invalid ip input after truncation", func(t *testing.T) {
+		raw := strings.Repeat("a", 60)
+		protector := newIPSecretProtector("pepper")
+		enc := sanitizeIP(raw, protector)
+		plain := decryptStoredIP(enc, protector)
+		if len(plain) != 45 {
+			t.Fatalf("expected decrypted/truncated length 45, got %d", len(plain))
+		}
+	})
+
+	t.Run("empty input returns empty", func(t *testing.T) {
+		if got := sanitizeIP("   ", newIPSecretProtector("pepper")); got != "" {
+			t.Fatalf("expected empty result, got %q", got)
+		}
+	})
+}
+
+func TestAuthService_SecurityPIN_SetVerifyChangeAndToken(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, err := NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+	if err != nil {
+		t.Fatalf("new protector: %v", err)
+	}
+
+	userID := uuidv7.MustBytes()
+	repo.users[string(userID)] = &auth.User{
+		ID:    userID,
+		Email: "user@example.com",
+	}
+
+	cfg := config.AuthConfig{
+		SecurityPINActionTokenTTL: 5 * time.Minute,
+		SecurityPINMaxAttempts:    3,
+		SecurityPINLockDuration:   2 * time.Minute,
+	}
+	svc := NewAuthService(repo, roles, tokens, nil, AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+
+	if err := svc.SetSecurityPIN(context.Background(), userID, "12a456"); !errors.Is(err, ErrInvalidSecurityPIN) {
+		t.Fatalf("expected invalid pin format error, got %v", err)
+	}
+
+	if err := svc.SetSecurityPIN(context.Background(), userID, "123456"); err != nil {
+		t.Fatalf("set pin: %v", err)
+	}
+	if len(repo.users[string(userID)].SecurityPINHash) == 0 {
+		t.Fatalf("expected hashed pin record to be persisted")
+	}
+	if err := svc.SetSecurityPIN(context.Background(), userID, "654321"); !errors.Is(err, ErrSecurityPINAlreadySet) {
+		t.Fatalf("expected already set error, got %v", err)
+	}
+
+	if _, err := svc.VerifySecurityPINForAction(context.Background(), userID, "000000", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"); !errors.Is(err, ErrInvalidSecurityPIN) {
+		t.Fatalf("expected invalid pin on first wrong attempt, got %v", err)
+	}
+	if _, err := svc.VerifySecurityPINForAction(context.Background(), userID, "000000", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"); !errors.Is(err, ErrInvalidSecurityPIN) {
+		t.Fatalf("expected invalid pin on second wrong attempt, got %v", err)
+	}
+	if _, err := svc.VerifySecurityPINForAction(context.Background(), userID, "000000", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"); !errors.Is(err, ErrSecurityPINAttemptLimit) {
+		t.Fatalf("expected attempt-limit error on third wrong attempt, got %v", err)
+	}
+	if _, err := svc.VerifySecurityPINForAction(context.Background(), userID, "123456", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"); !errors.Is(err, ErrSecurityPINLocked) {
+		t.Fatalf("expected blocked error after max attempts, got %v", err)
+	}
+
+	if err := svc.clearSecurityPINLockState(context.Background(), userID); err != nil {
+		t.Fatalf("clear lock state: %v", err)
+	}
+
+	token, err := svc.VerifySecurityPINForAction(context.Background(), userID, "123456", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74")
+	if err != nil {
+		t.Fatalf("verify pin for action: %v", err)
+	}
+	if strings.TrimSpace(token) == "" {
+		t.Fatalf("expected non-empty action token")
+	}
+	if err := svc.ValidateSecurityPINActionToken(context.Background(), userID, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", token); err != nil {
+		t.Fatalf("validate pin action token: %v", err)
+	}
+	if err := svc.ValidateSecurityPINActionToken(context.Background(), userID, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", token); err != nil {
+		t.Fatalf("validate pin action token second time: %v", err)
+	}
+
+	sessionBoundToken, err := svc.VerifySecurityPINForActionInSession(context.Background(), userID, "123456", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", "sid-1")
+	if err != nil {
+		t.Fatalf("verify pin in session: %v", err)
+	}
+	if err := svc.ValidateSecurityPINActionTokenInSession(context.Background(), userID, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", sessionBoundToken, "sid-1"); err != nil {
+		t.Fatalf("validate session-bound token: %v", err)
+	}
+	if err := svc.ValidateSecurityPINActionTokenInSession(context.Background(), userID, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", sessionBoundToken, "sid-2"); !errors.Is(err, ErrInvalidPINAction) {
+		t.Fatalf("expected invalid pin action for mismatched session, got %v", err)
+	}
+
+	if err := svc.ConsumeSecurityPINActionToken(context.Background(), userID, "428fdf48-3f99-46ea-bc47-8fb2e312be08", token); !errors.Is(err, ErrInvalidPINAction) {
+		t.Fatalf("expected invalid pin action for mismatched action, got %v", err)
+	}
+
+	token2, err := svc.VerifySecurityPINForAction(context.Background(), userID, "123456", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74")
+	if err != nil {
+		t.Fatalf("verify pin second token: %v", err)
+	}
+	if err := svc.ConsumeSecurityPINActionToken(context.Background(), userID, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", token2); err != nil {
+		t.Fatalf("consume pin action token: %v", err)
+	}
+	if err := svc.ConsumeSecurityPINActionToken(context.Background(), userID, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", token2); !errors.Is(err, ErrInvalidPINAction) {
+		t.Fatalf("expected token to be one-time use, got %v", err)
+	}
+
+	if err := svc.ChangeSecurityPIN(context.Background(), userID, "111111", "654321"); !errors.Is(err, ErrInvalidSecurityPIN) {
+		t.Fatalf("expected invalid current pin, got %v", err)
+	}
+	if err := svc.clearSecurityPINLockState(context.Background(), userID); err != nil {
+		t.Fatalf("clear lock state after failed change: %v", err)
+	}
+	if err := svc.ChangeSecurityPIN(context.Background(), userID, "123456", "654321"); err != nil {
+		t.Fatalf("change pin: %v", err)
+	}
+
+	if _, err := svc.VerifySecurityPINForAction(context.Background(), userID, "123456", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"); !errors.Is(err, ErrInvalidSecurityPIN) {
+		t.Fatalf("expected old pin invalid after change, got %v", err)
+	}
+	if err := svc.clearSecurityPINLockState(context.Background(), userID); err != nil {
+		t.Fatalf("clear lock state after old pin verify: %v", err)
+	}
+	if _, err := svc.VerifySecurityPINForAction(context.Background(), userID, "654321", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"); err != nil {
+		t.Fatalf("expected new pin to verify, got %v", err)
+	}
+}
+
+func TestAuthService_ForgotAndResetSecurityPIN(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	queue := &mockEmailQueue{}
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, err := NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+	if err != nil {
+		t.Fatalf("new protector: %v", err)
+	}
+
+	userID := uuidv7.MustBytes()
+	user := &auth.User{
+		ID:    userID,
+		Email: "user@example.com",
+	}
+	repo.users[string(userID)] = user
+	repo.usersByMail[user.Email] = user
+
+	cfg := config.AuthConfig{
+		PasswordPepper:            "pepper",
+		HashTime:                  1,
+		HashMemoryKB:              64 * 1024,
+		HashThreads:               4,
+		HashKeyLen:                32,
+		SecurityPINResetURL:       "https://app.example.com/reset-pin",
+		SecurityPINResetTTL:       20 * time.Minute,
+		ForgotSecurityPINCooldown: 2 * time.Minute,
+	}
+	svc := NewAuthService(repo, roles, tokens, queue, AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+	hash, salt, err := svc.hashPassword("Password123!")
+	if err != nil {
+		t.Fatalf("hash password: %v", err)
+	}
+	user.PasswordHash = hash
+	user.SaltValue = salt
+
+	svc.ForgotSecurityPIN(context.Background(), user.Email, "127.0.0.1", "ua-test")
+	if repo.lastSecurityPINResetToken == nil {
+		t.Fatalf("expected security pin reset token to be created")
+	}
+	if queue.last == nil {
+		t.Fatalf("expected reset email to be enqueued")
+	}
+	rawToken := extractTokenValue(queue.last.Body)
+	if rawToken == "" {
+		t.Fatalf("expected token in reset email body")
+	}
+
+	if err := svc.ResetSecurityPIN(context.Background(), rawToken, "password", "Password123!", "", "12345"); !errors.Is(err, ErrInvalidSecurityPIN) {
+		t.Fatalf("expected invalid pin format error, got %v", err)
+	}
+
+	if err := svc.ResetSecurityPIN(context.Background(), rawToken, "password", "Password123!", "", "123456"); err != nil {
+		t.Fatalf("reset security pin: %v", err)
+	}
+	if _, err := svc.VerifySecurityPINForAction(context.Background(), userID, "123456", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"); err != nil {
+		t.Fatalf("expected reset pin to verify, got %v", err)
+	}
+
+	if err := svc.ResetSecurityPIN(context.Background(), rawToken, "password", "Password123!", "", "654321"); !errors.Is(err, ErrInvalidResetLink) {
+		t.Fatalf("expected one-time token invalid after use, got %v", err)
+	}
+
+	countBefore := len(repo.securityPINResetTokens)
+	svc.ForgotSecurityPIN(context.Background(), "missing@example.com", "127.0.0.1", "ua-test")
+	if len(repo.securityPINResetTokens) != countBefore {
+		t.Fatalf("expected no new security pin token for missing account")
+	}
+	if tokens.lastKey == "" || !strings.HasPrefix(tokens.lastKey, "auth:security_pin:cooldown:") {
+		t.Fatalf("expected security pin cooldown key to be set, got %q", tokens.lastKey)
+	}
+}
+
+func TestAuthService_RequestSecurityPINReset(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	queue := &mockEmailQueue{}
+
+	userID := uuidv7.MustBytes()
+	user := &auth.User{
+		ID:    userID,
+		Email: "user@example.com",
+	}
+	repo.users[string(userID)] = user
+	repo.usersByMail[user.Email] = user
+
+	cfg := config.AuthConfig{
+		SecurityPINResetURL:       "https://app.example.com/reset-pin",
+		SecurityPINResetTTL:       20 * time.Minute,
+		ForgotSecurityPINCooldown: 2 * time.Minute,
+		SecurityPINMaxAttempts:    5,
+		SecurityPINLockDuration:   0,
+		PasswordPepper:            "pepper",
+		HashTime:                  1,
+		HashMemoryKB:              64 * 1024,
+		HashThreads:               4,
+		HashKeyLen:                32,
+	}
+	svc := NewAuthService(repo, roles, tokens, queue, AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	hash, salt, err := svc.hashPassword("Password123!")
+	if err != nil {
+		t.Fatalf("hash password: %v", err)
+	}
+	user.PasswordHash = hash
+	user.SaltValue = salt
+
+	tokens.store[securityPINLockKey(userID)] = []byte("1")
+
+	if err := svc.RequestSecurityPINReset(context.Background(), userID, "password", "Password123!", "", "127.0.0.1", "ua"); err != nil {
+		t.Fatalf("request security pin reset: %v", err)
+	}
+	if queue.last == nil {
+		t.Fatalf("expected reset email to be enqueued")
+	}
+
+	if err := svc.RequestSecurityPINReset(context.Background(), userID, "password", "Password123!", "", "127.0.0.1", "ua"); !errors.Is(err, ErrSecurityPINResetRatelimit) {
+		t.Fatalf("expected cooldown rate-limit error, got %v", err)
+	}
+
+	delete(tokens.store, forgotSecurityPINCooldownKey(user.Email))
+	if err := svc.RequestSecurityPINReset(context.Background(), userID, "password", "wrong-password", "", "127.0.0.1", "ua"); !errors.Is(err, ErrInvalidPINResetPassword) {
+		t.Fatalf("expected invalid password error, got %v", err)
+	}
+
+	delete(tokens.store, securityPINLockKey(userID))
+	if err := svc.RequestSecurityPINReset(context.Background(), userID, "password", "Password123!", "", "127.0.0.1", "ua"); !errors.Is(err, ErrSecurityPINNotBlocked) {
+		t.Fatalf("expected not blocked error, got %v", err)
+	}
+}
+
+func TestAuthService_MicrosoftReauthPINReset(t *testing.T) {
+	repo := newMockAuthRepo()
+	roles := newMockRoleRepo()
+	tokens := newMockTokenStore()
+	queue := &mockEmailQueue{}
+	sso := &mockSSO{claims: MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane Doe"}}
+
+	userRoleID := uuidv7.MustBytes()
+	roles.rolesByName["user"] = &auth.Role{ID: userRoleID, Name: "user"}
+
+	cfg := config.AuthConfig{
+		SecurityPINResetURL:       "https://app.example.com/reset-pin",
+		SecurityPINResetTTL:       20 * time.Minute,
+		ForgotSecurityPINCooldown: 2 * time.Minute,
+		SecurityPINMaxAttempts:    5,
+		SecurityPINLockDuration:   0,
+		SSOStateTTL:               time.Minute,
+	}
+	svc := NewAuthService(repo, roles, tokens, queue, AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+
+	identity := &auth.UserIdentity{
+		ID:              uuidv7.MustBytes(),
+		UserID:          uuidv7.MustBytes(),
+		Provider:        "microsoft",
+		ProviderSubject: "sub",
+		Email:           "user@example.com",
+	}
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       identity.UserID,
+		Email:    "user@example.com",
+		Timezone: tzpkg.WithDefault(""),
+		RoleID:   userRoleID,
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	_ = repo.CreateIdentity(context.Background(), identity)
+	tokens.store[securityPINLockKey(identity.UserID)] = []byte("1")
+
+	authURL, err := svc.BeginMicrosoftReauth(context.Background(), identity.UserID, microsoftReauthPurposePINResetRequest)
+	if err != nil {
+		t.Fatalf("begin reauth: %v", err)
+	}
+	parsedURL, parseErr := url.Parse(authURL)
+	if parseErr != nil {
+		t.Fatalf("parse auth url: %v", parseErr)
+	}
+	state := parsedURL.Query().Get("state")
+	reauthToken, purpose, err := svc.CompleteMicrosoftReauth(context.Background(), "code", state)
+	if err != nil {
+		t.Fatalf("complete reauth: %v", err)
+	}
+	if purpose != microsoftReauthPurposePINResetRequest {
+		t.Fatalf("unexpected purpose: %s", purpose)
+	}
+
+	if err := svc.RequestSecurityPINReset(context.Background(), identity.UserID, "microsoft", "", reauthToken, "127.0.0.1", "ua"); err != nil {
+		t.Fatalf("request pin reset with microsoft: %v", err)
+	}
+	if queue.last == nil {
+		t.Fatalf("expected reset email to be enqueued")
+	}
+
+	authURL, err = svc.BeginMicrosoftReauth(context.Background(), identity.UserID, microsoftReauthPurposePINResetRequest)
+	if err != nil {
+		t.Fatalf("begin pin reset direct reauth: %v", err)
+	}
+	parsedURL, parseErr = url.Parse(authURL)
+	if parseErr != nil {
+		t.Fatalf("parse auth url: %v", parseErr)
+	}
+	state = parsedURL.Query().Get("state")
+	reauthToken, purpose, err = svc.CompleteMicrosoftReauth(context.Background(), "code", state)
+	if err != nil {
+		t.Fatalf("complete pin reset direct reauth: %v", err)
+	}
+	if purpose != microsoftReauthPurposePINResetRequest {
+		t.Fatalf("unexpected direct reset purpose: %s", purpose)
+	}
+	if err := svc.ResetSecurityPIN(context.Background(), "", "microsoft", "", reauthToken, "123456"); err != nil {
+		t.Fatalf("reset pin with microsoft reauth: %v", err)
+	}
+	if _, err := svc.VerifySecurityPINForAction(context.Background(), identity.UserID, "123456", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"); err != nil {
+		t.Fatalf("expected microsoft reset pin to verify, got %v", err)
+	}
+}
+
+func TestAuthService_ConsumeSecurityPINActionToken_Branches(t *testing.T) {
+	svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	userID := uuidv7.MustBytes()
+	if err := svc.ConsumeSecurityPINActionToken(context.Background(), userID, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", "x"); !errors.Is(err, ErrInvalidPINAction) {
+		t.Fatalf("expected invalid pin action when token store is nil, got %v", err)
+	}
+
+	tokens := newMockTokenStore()
+	svc = NewAuthService(newMockAuthRepo(), newMockRoleRepo(), tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	if err := svc.ConsumeSecurityPINActionToken(context.Background(), []byte("short"), "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", "x"); !errors.Is(err, ErrInvalidPINAction) {
+		t.Fatalf("expected invalid user id error, got %v", err)
+	}
+	if err := svc.ConsumeSecurityPINActionToken(context.Background(), userID, "   ", "x"); !errors.Is(err, ErrInvalidPINAction) {
+		t.Fatalf("expected invalid action error, got %v", err)
+	}
+	if err := svc.ConsumeSecurityPINActionToken(context.Background(), userID, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", ""); !errors.Is(err, ErrInvalidPINAction) {
+		t.Fatalf("expected invalid token error, got %v", err)
+	}
+
+	t.Run("session mismatch does not consume token", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		tokens := newMockTokenStore()
+		svc := NewAuthService(repo, newMockRoleRepo(), tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			SecurityPINActionTokenTTL: time.Minute,
+		}})
+
+		uid := uuidv7.MustBytes()
+		pinHash, err := svc.hashSecurityPIN("123456")
+		if err != nil {
+			t.Fatalf("hash pin: %v", err)
+		}
+		repo.users[string(uid)] = &auth.User{ID: uid, SecurityPINHash: pinHash}
+
+		token, err := svc.VerifySecurityPINForActionInSession(context.Background(), uid, "123456", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", "sid-1")
+		if err != nil {
+			t.Fatalf("issue action token: %v", err)
+		}
+		if err := svc.ConsumeSecurityPINActionTokenInSession(context.Background(), uid, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", token, "sid-2"); !errors.Is(err, ErrInvalidPINAction) {
+			t.Fatalf("expected session mismatch invalid action, got %v", err)
+		}
+		if err := svc.ConsumeSecurityPINActionTokenInSession(context.Background(), uid, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", token, "sid-1"); err != nil {
+			t.Fatalf("expected token still valid after mismatch, got %v", err)
+		}
+	})
+}
+
+func TestAuthService_buildSecurityPINResetEmail(t *testing.T) {
+	resolver := authEmailBrandingResolverMock{
+		branding: AuthEmailBranding{
+			CompanyName:   "Acme Air Rescue",
+			LogoContentID: "branding-email-logo",
+			LogoAttachment: &queue.EmailAttachment{
+				Filename:    "email-logo.png",
+				ContentType: "image/png",
+				ContentID:   "branding-email-logo",
+				Content:     []byte("png"),
+				Inline:      true,
+			},
+		},
+	}
+	email := buildSecurityPINResetEmail(context.Background(), resolver, "Marco", "https://app.example.com/reset-pin?token=abc", 20*time.Minute)
+	if !strings.Contains(email.Subject, "security PIN") {
+		t.Fatalf("unexpected subject: %q", email.Subject)
+	}
+	if !strings.Contains(email.TextBody, "6-digit PIN") {
+		t.Fatalf("expected 6-digit instruction in text body")
+	}
+	if !strings.Contains(email.HTMLBody, "Reset Security PIN") {
+		t.Fatalf("expected reset button text in html body")
+	}
+	if !strings.Contains(email.HTMLBody, "cid:"+resolver.branding.LogoContentID) {
+		t.Fatalf("expected cid logo reference in html body")
+	}
+	if !strings.Contains(email.HTMLBody, resolver.branding.CompanyName) {
+		t.Fatalf("expected branding company name in html body")
+	}
+	if len(email.Attachments) != 1 || !email.Attachments[0].Inline || email.Attachments[0].ContentID != resolver.branding.LogoContentID {
+		t.Fatalf("expected inline logo attachment, got %#v", email.Attachments)
+	}
+}
+
+func TestAuthService_validateSecurityPIN(t *testing.T) {
+	if err := validateSecurityPIN("123456"); err != nil {
+		t.Fatalf("expected valid pin, got %v", err)
+	}
+	if err := validateSecurityPIN("12345"); !errors.Is(err, ErrInvalidSecurityPIN) {
+		t.Fatalf("expected invalid length error, got %v", err)
+	}
+	if err := validateSecurityPIN("12345a"); !errors.Is(err, ErrInvalidSecurityPIN) {
+		t.Fatalf("expected invalid char error, got %v", err)
+	}
+}
+
+func TestAuthService_SecurityPIN_Branches(t *testing.T) {
+	t.Run("set pin invalid user id", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if err := svc.SetSecurityPIN(context.Background(), []byte("short"), "123456"); !errors.Is(err, ErrInvalidSecurityPIN) {
+			t.Fatalf("expected invalid pin error, got %v", err)
+		}
+	})
+
+	t.Run("set pin without protector", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com"}
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if err := svc.SetSecurityPIN(context.Background(), userID, "123456"); err != nil {
+			t.Fatalf("expected set pin to work without protector, got %v", err)
+		}
+		if len(repo.users[string(userID)].SecurityPINHash) == 0 {
+			t.Fatalf("expected hashed pin to be persisted")
+		}
+	})
+
+	t.Run("set pin user not found", func(t *testing.T) {
+		p := &errorProtector{}
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: p, Config: config.AuthConfig{}})
+		if err := svc.SetSecurityPIN(context.Background(), uuidv7.MustBytes(), "123456"); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token for missing user, got %v", err)
+		}
+	})
+
+	t.Run("set pin stores hashed record", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com"}
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if err := svc.SetSecurityPIN(context.Background(), userID, "123456"); err != nil {
+			t.Fatalf("set pin failed: %v", err)
+		}
+		raw := repo.users[string(userID)].SecurityPINHash
+		if len(raw) == 0 {
+			t.Fatalf("expected pin record to be stored")
+		}
+		if bytes.Equal(raw, []byte("123456")) {
+			t.Fatalf("pin must not be stored in plaintext")
+		}
+		parts := strings.Split(string(raw), "$")
+		if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
+			t.Fatalf("expected hash record format <salt_b64>$<hash_b64>, got %q", string(raw))
+		}
+	})
+
+	t.Run("verify pin supports legacy v1 hash record", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com"}
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			PasswordPepper: "pepper",
+		}})
+
+		hash, salt, err := svc.hashPassword("123456")
+		if err != nil {
+			t.Fatalf("hash password: %v", err)
+		}
+		repo.users[string(userID)].SecurityPINHash = []byte(
+			"v1$" + base64.RawURLEncoding.EncodeToString(salt) + "$" + base64.RawURLEncoding.EncodeToString(hash),
+		)
+
+		if err := svc.verifySecurityPIN(context.Background(), userID, "123456"); err != nil {
+			t.Fatalf("expected legacy v1 pin hash to verify, got %v", err)
+		}
+	})
+
+	t.Run("change pin invalid user id", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if err := svc.ChangeSecurityPIN(context.Background(), []byte("short"), "123456", "654321"); !errors.Is(err, ErrInvalidSecurityPIN) {
+			t.Fatalf("expected invalid pin error, got %v", err)
+		}
+	})
+
+	t.Run("change pin new pin format invalid", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if err := svc.ChangeSecurityPIN(context.Background(), uuidv7.MustBytes(), "123456", "xx"); !errors.Is(err, ErrInvalidSecurityPIN) {
+			t.Fatalf("expected invalid new pin format, got %v", err)
+		}
+	})
+
+	t.Run("verify pin not set", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com"}
+		p := &errorProtector{}
+		svc := NewAuthService(repo, newMockRoleRepo(), newMockTokenStore(), nil, AuthServiceDependencies{SSO: nil, Protector: p, Config: config.AuthConfig{
+			SecurityPINActionTokenTTL: time.Minute,
+		}})
+		if _, err := svc.VerifySecurityPINForAction(context.Background(), userID, "123456", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"); !errors.Is(err, ErrSecurityPINNotSet) {
+			t.Fatalf("expected pin not set error, got %v", err)
+		}
+	})
+
+	t.Run("verify pin decrypt error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{
+			ID:              userID,
+			Email:           "user@example.com",
+			SecurityPINHash: []byte("cipher"),
+		}
+		p := &errorProtector{decryptErr: errors.New("decrypt failed")}
+		svc := NewAuthService(repo, newMockRoleRepo(), newMockTokenStore(), nil, AuthServiceDependencies{SSO: nil, Protector: p, Config: config.AuthConfig{
+			SecurityPINActionTokenTTL: time.Minute,
+		}})
+		if _, err := svc.VerifySecurityPINForAction(context.Background(), userID, "123456", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"); !errors.Is(err, p.decryptErr) {
+			t.Fatalf("expected decrypt error, got %v", err)
+		}
+	})
+
+	t.Run("verify pin missing action", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{
+			ID:              userID,
+			Email:           "user@example.com",
+			SecurityPINHash: []byte("cipher"),
+		}
+		p := &errorProtector{}
+		svc := NewAuthService(repo, newMockRoleRepo(), newMockTokenStore(), nil, AuthServiceDependencies{SSO: nil, Protector: p, Config: config.AuthConfig{
+			SecurityPINActionTokenTTL: time.Minute,
+		}})
+		if _, err := svc.VerifySecurityPINForAction(context.Background(), userID, "123456", "   "); err == nil {
+			t.Fatalf("expected missing action error")
+		}
+	})
+
+	t.Run("verify pin token set error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{
+			ID:              userID,
+			Email:           "user@example.com",
+			SecurityPINHash: []byte("cipher"),
+		}
+		p := &errorProtector{}
+		tokens := newMockTokenStore()
+		tokens.setErr = errors.New("set failed")
+		svc := NewAuthService(repo, newMockRoleRepo(), tokens, nil, AuthServiceDependencies{SSO: nil, Protector: p, Config: config.AuthConfig{
+			SecurityPINActionTokenTTL: time.Minute,
+		}})
+		if _, err := svc.VerifySecurityPINForAction(context.Background(), userID, "123456", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"); !errors.Is(err, tokens.setErr) {
+			t.Fatalf("expected token set error, got %v", err)
+		}
+	})
+}
+
+func TestAuthService_ForgotSecurityPIN_Branches(t *testing.T) {
+	t.Run("empty email", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			ForgotSecurityPINMinDuration: 0,
+		}})
+		svc.ForgotSecurityPIN(context.Background(), "   ", "127.0.0.1", "ua")
+	})
+
+	t.Run("cooldown active", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		tokens := newMockTokenStore()
+		email := "user@example.com"
+		tokens.store[forgotSecurityPINCooldownKey(email)] = []byte("1")
+
+		svc := NewAuthService(repo, newMockRoleRepo(), tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			ForgotSecurityPINCooldown: 2 * time.Minute,
+		}})
+		svc.ForgotSecurityPIN(context.Background(), email, "127.0.0.1", "ua")
+		if repo.lastSecurityPINResetToken != nil {
+			t.Fatalf("expected no token created while cooldown is active")
+		}
+	})
+
+	t.Run("lookup error still marks cooldown", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.getByMailErr = errors.New("db down")
+		tokens := newMockTokenStore()
+
+		svc := NewAuthService(repo, newMockRoleRepo(), tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			ForgotSecurityPINCooldown: 2 * time.Minute,
+		}})
+		svc.ForgotSecurityPIN(context.Background(), "user@example.com", "127.0.0.1", "ua")
+		if tokens.lastKey == "" || !strings.HasPrefix(tokens.lastKey, "auth:security_pin:cooldown:") {
+			t.Fatalf("expected cooldown key to be marked, got %q", tokens.lastKey)
+		}
+	})
+}
+
+func TestAuthService_createAndSendSecurityPINReset_Branches(t *testing.T) {
+	user := &auth.User{
+		ID:    uuidv7.MustBytes(),
+		Email: "user@example.com",
+	}
+
+	baseCfg := config.AuthConfig{
+		SecurityPINResetURL: "https://app.example.com/reset-pin",
+		SecurityPINResetTTL: 20 * time.Minute,
+	}
+
+	t.Run("skip when reset url is empty", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			SecurityPINResetURL: "",
+			SecurityPINResetTTL: 20 * time.Minute,
+		}})
+		if err := svc.createAndSendSecurityPINReset(context.Background(), user, "127.0.0.1", "ua"); err != nil {
+			t.Fatalf("expected nil error when url is empty, got %v", err)
+		}
+	})
+
+	t.Run("random token generation error", func(t *testing.T) {
+		orig := rand.Reader
+		rand.Reader = errReader{}
+		defer func() { rand.Reader = orig }()
+
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+		if err := svc.createAndSendSecurityPINReset(context.Background(), user, "127.0.0.1", "ua"); !errors.Is(err, io.ErrUnexpectedEOF) {
+			t.Fatalf("expected random token error, got %v", err)
+		}
+	})
+
+	t.Run("invalidate active tokens error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.invalidatePINResetTokensErr = errors.New("invalidate failed")
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		if err := svc.createAndSendSecurityPINReset(context.Background(), user, "127.0.0.1", "ua"); !errors.Is(err, repo.invalidatePINResetTokensErr) {
+			t.Fatalf("expected invalidate error, got %v", err)
+		}
+	})
+
+	t.Run("create token error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		repo.createPINResetTokenErr = errors.New("create pin reset failed")
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		if err := svc.createAndSendSecurityPINReset(context.Background(), user, "127.0.0.1", "ua"); !errors.Is(err, repo.createPINResetTokenErr) {
+			t.Fatalf("expected create token error, got %v", err)
+		}
+	})
+
+	t.Run("invalid reset url fails before token is persisted", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			SecurityPINResetURL: "http://",
+			SecurityPINResetTTL: 20 * time.Minute,
+		}})
+
+		if err := svc.createAndSendSecurityPINReset(context.Background(), user, "127.0.0.1", "ua"); err == nil {
+			t.Fatalf("expected invalid security pin reset url error")
+		}
+		if repo.lastSecurityPINResetToken != nil {
+			t.Fatalf("token should not be persisted when reset url is invalid")
+		}
+	})
+
+	t.Run("queue enqueue error", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		queue := &mockEmailQueue{err: errors.New("queue failed")}
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, queue, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		if err := svc.createAndSendSecurityPINReset(context.Background(), user, "127.0.0.1", "ua"); !errors.Is(err, queue.err) {
+			t.Fatalf("expected queue error, got %v", err)
+		}
+	})
+
+	t.Run("queue success", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		queue := &mockEmailQueue{}
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, queue, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		if err := svc.createAndSendSecurityPINReset(context.Background(), user, "127.0.0.1", "ua"); err != nil {
+			t.Fatalf("expected nil error, got %v", err)
+		}
+		if queue.last == nil {
+			t.Fatalf("expected security pin reset email to be queued")
+		}
+		if strings.TrimSpace(queue.last.HTMLBody) == "" {
+			t.Fatalf("expected non-empty html body in queued security pin reset email")
+		}
+	})
+
+	t.Run("no queue and no mailer returns nil", func(t *testing.T) {
+		repo := newMockAuthRepo()
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: baseCfg})
+
+		if err := svc.createAndSendSecurityPINReset(context.Background(), user, "127.0.0.1", "ua"); err != nil {
+			t.Fatalf("expected nil error, got %v", err)
+		}
+		if repo.lastSecurityPINResetToken == nil {
+			t.Fatalf("expected security pin reset token to be persisted")
+		}
+	})
+}
+
+func TestAuthService_ResetSecurityPIN_Branches(t *testing.T) {
+	userID := uuidv7.MustBytes()
+	repo := newMockAuthRepo()
+	repo.users[string(userID)] = &auth.User{
+		ID:           userID,
+		Email:        "user@example.com",
+		PasswordHash: []byte("hash"),
+		SaltValue:    []byte("salt"),
+	}
+	repo.securityPINResetTokens[string(hashToken("token"))] = &auth.SecurityPINResetToken{
+		ID:        uuidv7.MustBytes(),
+		UserID:    userID,
+		TokenHash: hashToken("token"),
+		ExpiresAt: time.Now().UTC().Add(20 * time.Minute),
+	}
+
+	t.Run("missing token", func(t *testing.T) {
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if err := svc.ResetSecurityPIN(context.Background(), "   ", "password", "Password123!", "", "123456"); !errors.Is(err, ErrInvalidResetLink) {
+			t.Fatalf("expected invalid reset link, got %v", err)
+		}
+	})
+
+	t.Run("missing password", func(t *testing.T) {
+		svc := NewAuthService(repo, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if err := svc.ResetSecurityPIN(context.Background(), "token", "password", "   ", "", "123456"); !errors.Is(err, ErrInvalidPINResetPassword) {
+			t.Fatalf("expected invalid pin reset password, got %v", err)
+		}
+	})
+
+	t.Run("reset pin works without protector", func(t *testing.T) {
+		password := "Password123!"
+		repo2 := newMockAuthRepo()
+		repo2.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com"}
+		repo2.securityPINResetTokens[string(hashToken("token"))] = &auth.SecurityPINResetToken{
+			ID:        uuidv7.MustBytes(),
+			UserID:    userID,
+			TokenHash: hashToken("token"),
+			ExpiresAt: time.Now().UTC().Add(20 * time.Minute),
+		}
+		svc := NewAuthService(repo2, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			PasswordPepper: "pepper",
+			HashTime:       1,
+			HashMemoryKB:   64 * 1024,
+			HashThreads:    4,
+			HashKeyLen:     32,
+		}})
+		hash, salt, err := svc.hashPassword(password)
+		if err != nil {
+			t.Fatalf("hash password: %v", err)
+		}
+		repo2.users[string(userID)].PasswordHash = hash
+		repo2.users[string(userID)].SaltValue = salt
+		if err := svc.ResetSecurityPIN(context.Background(), "token", "password", password, "", "123456"); err != nil {
+			t.Fatalf("expected reset pin success without protector, got %v", err)
+		}
+	})
+
+	t.Run("microsoft reset works without reset token", func(t *testing.T) {
+		repo2 := newMockAuthRepo()
+		tokens2 := newMockTokenStore()
+		repo2.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com"}
+		token := "reauth-microsoft"
+		tokens2.store[microsoftReauthKey(token)] = []byte(bytesToString(userID) + "|" + microsoftReauthPurposePINResetRequest)
+		svc := NewAuthService(repo2, newMockRoleRepo(), tokens2, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if err := svc.ResetSecurityPIN(context.Background(), "", "microsoft", "", token, "123456"); err != nil {
+			t.Fatalf("expected microsoft reset pin success without reset token, got %v", err)
+		}
+		if len(repo2.users[string(userID)].SecurityPINHash) == 0 {
+			t.Fatalf("expected security pin hash to be updated")
+		}
+	})
+
+	t.Run("consume error", func(t *testing.T) {
+		password := "Password123!"
+		p := &errorProtector{}
+		repo2 := newMockAuthRepo()
+		repo2.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com"}
+		repo2.securityPINResetTokens[string(hashToken("token"))] = &auth.SecurityPINResetToken{
+			ID:        uuidv7.MustBytes(),
+			UserID:    userID,
+			TokenHash: hashToken("token"),
+			ExpiresAt: time.Now().UTC().Add(20 * time.Minute),
+		}
+		repo2.consumePINResetErr = errors.New("consume failed")
+		svc := NewAuthService(repo2, newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: p, Config: config.AuthConfig{
+			PasswordPepper: "pepper",
+			HashTime:       1,
+			HashMemoryKB:   64 * 1024,
+			HashThreads:    4,
+			HashKeyLen:     32,
+		}})
+		hash, salt, err := svc.hashPassword(password)
+		if err != nil {
+			t.Fatalf("hash password: %v", err)
+		}
+		repo2.users[string(userID)].PasswordHash = hash
+		repo2.users[string(userID)].SaltValue = salt
+		if err := svc.ResetSecurityPIN(context.Background(), "token", "password", password, "", "123456"); !errors.Is(err, repo2.consumePINResetErr) {
+			t.Fatalf("expected consume error, got %v", err)
+		}
+	})
+}
+
+func TestAuthService_ForgotSecurityPINCooldownHelpers(t *testing.T) {
+	svcNoTokens := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+		ForgotSecurityPINCooldown: 2 * time.Minute,
+	}})
+	if svcNoTokens.isForgotSecurityPINCooldownActive(context.Background(), "k") {
+		t.Fatalf("expected inactive cooldown when token store is nil")
+	}
+	if err := svcNoTokens.markForgotSecurityPINCooldown(context.Background(), "k"); err != nil {
+		t.Fatalf("expected nil when token store is nil, got %v", err)
+	}
+
+	tokens := newMockTokenStore()
+	svcDisabled := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+		ForgotSecurityPINCooldown: 0,
+	}})
+	if svcDisabled.isForgotSecurityPINCooldownActive(context.Background(), "k") {
+		t.Fatalf("expected inactive cooldown when cooldown disabled")
+	}
+	if err := svcDisabled.markForgotSecurityPINCooldown(context.Background(), "k"); err != nil {
+		t.Fatalf("expected nil when cooldown disabled, got %v", err)
+	}
+
+	svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), tokens, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+		ForgotSecurityPINCooldown: 2 * time.Minute,
+	}})
+	if err := svc.markForgotSecurityPINCooldown(context.Background(), "k1"); err != nil {
+		t.Fatalf("mark cooldown: %v", err)
+	}
+	if !svc.isForgotSecurityPINCooldownActive(context.Background(), "k1") {
+		t.Fatalf("expected cooldown active after mark")
+	}
+}
diff --git a/internal/service/auth_sessions.go b/internal/service/auth_sessions.go
new file mode 100644
index 0000000..6f51de1
--- /dev/null
+++ b/internal/service/auth_sessions.go
@@ -0,0 +1,993 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type authSessionRecord struct {
+	SessionID    string    `json:"session_id"`
+	UserID       string    `json:"user_id"`
+	CurrentJTI   string    `json:"current_jti"`
+	RefreshExpAt time.Time `json:"refresh_exp_at"`
+	AuthProvider string    `json:"auth_provider,omitempty"`
+	MicrosoftSID string    `json:"microsoft_sid,omitempty"`
+	DeviceType   string    `json:"device_type,omitempty"`
+	UserAgent    string    `json:"user_agent,omitempty"`
+	DeviceName   string    `json:"device_name"`
+	IPAddress    string    `json:"ip_address,omitempty"`
+	LongLived    bool      `json:"long_lived"`
+	CreatedAt    time.Time `json:"created_at"`
+	LastActiveAt time.Time `json:"last_active_at"`
+}
+
+type UserSession struct {
+	ID           string    `json:"id"`
+	DeviceName   string    `json:"device_name"`
+	UserAgent    string    `json:"user_agent,omitempty"`
+	IPAddress    string    `json:"ip_address,omitempty"`
+	CreatedAt    time.Time `json:"created_at"`
+	LastActiveAt time.Time `json:"last_active_at"`
+	ActiveNow    bool      `json:"active_now"`
+}
+
+const (
+	refreshReplayTTL          = 5 * time.Second
+	refreshLockTTL            = 15 * time.Second
+	refreshReplayWaitTimeout  = 5 * time.Second
+	refreshReplayPollInterval = 50 * time.Millisecond
+)
+
+type refreshReplayPayload struct {
+	AccessToken      string `json:"access_token"`
+	RefreshToken     string `json:"refresh_token"`
+	RefreshTTLSecond int64  `json:"refresh_ttl_second"`
+	SessionID        string `json:"session_id"`
+	UserID           string `json:"user_id"`
+}
+
+func (p refreshReplayPayload) toTokenPair() TokenPair {
+	return TokenPair{
+		AccessToken:  p.AccessToken,
+		RefreshToken: p.RefreshToken,
+		RefreshTTL:   time.Duration(p.RefreshTTLSecond) * time.Second,
+		SessionID:    p.SessionID,
+	}
+}
+
+func newRefreshReplayPayload(pair TokenPair, userID, sessionID string) refreshReplayPayload {
+	refreshTTL := pair.RefreshTTL
+	if refreshTTL <= 0 {
+		refreshTTL = time.Second
+	}
+	return refreshReplayPayload{
+		AccessToken:      pair.AccessToken,
+		RefreshToken:     pair.RefreshToken,
+		RefreshTTLSecond: int64(refreshTTL.Seconds()),
+		SessionID:        strings.TrimSpace(sessionID),
+		UserID:           strings.TrimSpace(userID),
+	}
+}
+
+func (s *AuthService) IssueTokensWithClient(ctx context.Context, user *auth.User, userAgent, ipAddress string) (TokenPair, error) {
+	return s.issueLoginTokensWithRefreshTTLAndClient(ctx, user, s.cfg.JWTLocalRefreshTTL, false, userAgent, ipAddress, "", "", "")
+}
+
+func (s *AuthService) IssueTokensAfterTOTPWithClient(ctx context.Context, user *auth.User, userAgent, ipAddress string) (TokenPair, error) {
+	return s.issueLoginTokensWithRefreshTTLAndClient(ctx, user, s.cfg.JWTRefreshTOTPTTL, true, userAgent, ipAddress, "", "", "")
+}
+
+func (s *AuthService) IssueTokensWithClientAndDeviceType(
+	ctx context.Context,
+	user *auth.User,
+	userAgent, ipAddress, deviceTypeHint string,
+) (TokenPair, error) {
+	return s.issueLoginTokensWithRefreshTTLAndClient(ctx, user, s.cfg.JWTLocalRefreshTTL, false, userAgent, ipAddress, "", deviceTypeHint, "")
+}
+
+func (s *AuthService) IssueTokensAfterTOTPWithClientAndDeviceType(
+	ctx context.Context,
+	user *auth.User,
+	userAgent, ipAddress, deviceTypeHint string,
+) (TokenPair, error) {
+	return s.issueLoginTokensWithRefreshTTLAndClient(ctx, user, s.cfg.JWTRefreshTOTPTTL, true, userAgent, ipAddress, "", deviceTypeHint, "")
+}
+
+func (s *AuthService) IssueTokensWithClientForProvider(
+	ctx context.Context,
+	user *auth.User,
+	userAgent, ipAddress, authProvider string,
+) (TokenPair, error) {
+	refreshTTL := s.providerRefreshTTL(ctx, user.ID, authProvider)
+	return s.issueLoginTokensWithRefreshTTLAndClient(ctx, user, refreshTTL, false, userAgent, ipAddress, authProvider, "", "")
+}
+
+func (s *AuthService) IssueTokensWithClientForProviderAndDeviceType(
+	ctx context.Context,
+	user *auth.User,
+	userAgent, ipAddress, authProvider, deviceTypeHint string,
+) (TokenPair, error) {
+	refreshTTL := s.providerRefreshTTL(ctx, user.ID, authProvider)
+	return s.issueLoginTokensWithRefreshTTLAndClient(ctx, user, refreshTTL, false, userAgent, ipAddress, authProvider, deviceTypeHint, "")
+}
+
+func (s *AuthService) IssueTokensWithClientForProviderAndMicrosoftSID(
+	ctx context.Context,
+	user *auth.User,
+	userAgent, ipAddress, authProvider, microsoftSID string,
+) (TokenPair, error) {
+	refreshTTL := s.providerRefreshTTL(ctx, user.ID, authProvider)
+	return s.issueLoginTokensWithRefreshTTLAndClient(ctx, user, refreshTTL, false, userAgent, ipAddress, authProvider, "", microsoftSID)
+}
+
+// providerRefreshTTL resolves the refresh-token lifetime for a login session.
+// For Microsoft/SSO sessions it follows the lifetime of the stored Microsoft
+// refresh token so the app session stays valid for exactly as long as Microsoft
+// will keep refreshing it (validated on every /auth/refresh). When Microsoft
+// does not report an expiry it falls back to the configured SSO default. Other
+// providers keep the standard refresh TTL.
+func (s *AuthService) providerRefreshTTL(ctx context.Context, userID []byte, authProvider string) time.Duration {
+	if !strings.EqualFold(strings.TrimSpace(authProvider), ssoProviderMicrosoft) {
+		return s.cfg.JWTRefreshTTL
+	}
+	fallback := s.cfg.JWTSSORefreshTTL
+	if fallback <= 0 {
+		fallback = s.cfg.JWTRefreshTTL
+	}
+	repo, ok := s.repo.(microsoftOAuthTokenStore)
+	if !ok {
+		return fallback
+	}
+	record, err := repo.GetMicrosoftOAuthTokenByUserIDProvider(ctx, userID, ssoProviderMicrosoft)
+	if err != nil || record == nil || record.RefreshTokenExpiresAt == nil {
+		return fallback
+	}
+	remaining := time.Until(*record.RefreshTokenExpiresAt)
+	if remaining <= time.Minute {
+		return fallback
+	}
+	return remaining
+}
+
+func (s *AuthService) issueLoginTokensWithRefreshTTLAndClient(
+	ctx context.Context,
+	user *auth.User,
+	refreshTTL time.Duration,
+	longLived bool,
+	userAgent, ipAddress, authProvider, deviceTypeHint, microsoftSID string,
+) (TokenPair, error) {
+	if user == nil || len(user.ID) != 16 {
+		return TokenPair{}, ErrInvalidToken
+	}
+	if !user.IsActive {
+		return TokenPair{}, ErrInvalidToken
+	}
+	return s.issueTokensWithRefreshTTLAndClient(ctx, user, refreshTTL, longLived, "", userAgent, ipAddress, authProvider, deviceTypeHint, microsoftSID)
+}
+
+func (s *AuthService) issueTokensWithRefreshTTLAndClient(
+	ctx context.Context,
+	user *auth.User,
+	refreshTTL time.Duration,
+	longLived bool,
+	sessionID, userAgent, ipAddress, authProvider, deviceTypeHint, microsoftSID string,
+) (TokenPair, error) {
+	if s.cfg.JWTAccessSecret == "" || s.cfg.JWTRefreshSecret == "" {
+		return TokenPair{}, errors.New("jwt secrets not configured")
+	}
+	if refreshTTL <= 0 {
+		refreshTTL = s.cfg.JWTRefreshTTL
+	}
+
+	now := time.Now().UTC()
+	newLogin := strings.TrimSpace(sessionID) == ""
+	if newLogin {
+		sessionID, _ = uuidv7.BytesToString(uuidv7.MustBytes())
+	}
+
+	existingSessionIDs := []string{}
+	if s.tokens != nil && newLogin {
+		if ids, err := s.loadUserSessionIDs(ctx, user.ID); err == nil {
+			existingSessionIDs = ids
+		}
+	}
+
+	sessionVersion, _ := s.sessionVersion(ctx, user.ID)
+	accessClaims := jwt.MapClaims{
+		"sub":  bytesToString(user.ID),
+		"iat":  now.Unix(),
+		"exp":  now.Add(s.cfg.JWTAccessTTL).Unix(),
+		"type": "access",
+		"sv":   sessionVersion,
+		"sid":  sessionID,
+	}
+	accessToken, err := jwt.NewWithClaims(jwt.SigningMethodHS256, accessClaims).SignedString([]byte(s.cfg.JWTAccessSecret))
+	if err != nil {
+		return TokenPair{}, err
+	}
+
+	jti, err := randomToken(32)
+	if err != nil {
+		return TokenPair{}, err
+	}
+	refreshClaims := jwt.MapClaims{
+		"sub":  bytesToString(user.ID),
+		"iat":  now.Unix(),
+		"exp":  now.Add(refreshTTL).Unix(),
+		"jti":  jti,
+		"type": "refresh",
+		"sv":   sessionVersion,
+		"sid":  sessionID,
+	}
+	if longLived {
+		refreshClaims["ll"] = true
+	}
+	refreshToken, err := jwt.NewWithClaims(jwt.SigningMethodHS256, refreshClaims).SignedString([]byte(s.cfg.JWTRefreshSecret))
+	if err != nil {
+		return TokenPair{}, err
+	}
+
+	if s.tokens != nil {
+		_ = s.tokens.Set(ctx, refreshKey(jti), []byte(sessionID), refreshTTL)
+		if strings.EqualFold(strings.TrimSpace(authProvider), ssoProviderMicrosoft) && strings.TrimSpace(microsoftSID) != "" {
+			_ = s.tokens.Set(ctx, microsoftSessionKey(microsoftSID), []byte(sessionID), refreshTTL)
+		}
+
+		createdAt := now
+		record, _ := s.loadSessionRecord(ctx, sessionID)
+		if record != nil && record.UserID == bytesToString(user.ID) {
+			createdAt = record.CreatedAt
+			if strings.TrimSpace(authProvider) == "" {
+				authProvider = strings.TrimSpace(record.AuthProvider)
+			}
+			if strings.TrimSpace(userAgent) == "" {
+				userAgent = record.UserAgent
+			}
+			if strings.TrimSpace(ipAddress) == "" {
+				ipAddress = record.IPAddress
+			}
+		}
+
+		session := &authSessionRecord{
+			SessionID:    sessionID,
+			UserID:       bytesToString(user.ID),
+			CurrentJTI:   jti,
+			RefreshExpAt: now.Add(refreshTTL),
+			AuthProvider: strings.TrimSpace(authProvider),
+			MicrosoftSID: strings.TrimSpace(microsoftSID),
+			DeviceType:   classifyDeviceType(strings.TrimSpace(userAgent), deviceTypeHint),
+			UserAgent:    strings.TrimSpace(userAgent),
+			DeviceName:   deriveDeviceName(strings.TrimSpace(userAgent)),
+			IPAddress:    sanitizeIP(strings.TrimSpace(ipAddress), s.ipProtector),
+			LongLived:    longLived,
+			CreatedAt:    createdAt,
+			LastActiveAt: now,
+		}
+		if err := s.saveSessionRecord(ctx, session, refreshTTL); err == nil {
+			if newLogin {
+				_ = s.enforceUserDeviceSlots(ctx, user.ID, existingSessionIDs, session)
+			} else {
+				_ = s.addUserSessionID(ctx, user.ID, sessionID)
+			}
+		}
+	}
+
+	return TokenPair{
+		AccessToken:  accessToken,
+		RefreshToken: refreshToken,
+		RefreshTTL:   refreshTTL,
+		SessionID:    sessionID,
+	}, nil
+}
+
+func (s *AuthService) RefreshTokensWithClient(ctx context.Context, refreshToken, userAgent, ipAddress string) (TokenPair, error) {
+	return s.RefreshTokensWithClientAndDeviceType(ctx, refreshToken, userAgent, ipAddress, "")
+}
+
+func (s *AuthService) RefreshTokensWithClientAndDeviceType(
+	ctx context.Context,
+	refreshToken, userAgent, ipAddress, deviceTypeHint string,
+) (TokenPair, error) {
+	if refreshToken == "" {
+		return TokenPair{}, ErrInvalidToken
+	}
+	parsed, err := jwt.Parse(refreshToken, func(t *jwt.Token) (any, error) {
+		if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, ErrInvalidToken
+		}
+		return []byte(s.cfg.JWTRefreshSecret), nil
+	})
+	if err != nil || !parsed.Valid {
+		return TokenPair{}, ErrInvalidToken
+	}
+
+	claims, ok := parsed.Claims.(jwt.MapClaims)
+	if !ok || claims["type"] != "refresh" {
+		return TokenPair{}, ErrInvalidToken
+	}
+	jti, _ := claims["jti"].(string)
+	sub, _ := claims["sub"].(string)
+	sid, _ := claims["sid"].(string)
+	if jti == "" || sub == "" || sid == "" {
+		return TokenPair{}, ErrInvalidToken
+	}
+	userID, err := uuidv7.ParseString(sub)
+	if err != nil {
+		return TokenPair{}, ErrInvalidToken
+	}
+	if s.tokens == nil {
+		return TokenPair{}, ErrInvalidToken
+	}
+	if !s.validSessionVersion(ctx, userID, claims["sv"]) {
+		return TokenPair{}, ErrInvalidToken
+	}
+	if !s.isSessionActive(ctx, userID, sid) {
+		return TokenPair{}, ErrInvalidToken
+	}
+	if replay, ok, err := s.loadRefreshReplay(ctx, jti, userID, sid); err != nil {
+		return TokenPair{}, ErrInvalidToken
+	} else if ok {
+		return replay, nil
+	}
+
+	acquired := false
+	acquired, err = s.tokens.SetIfNotExists(ctx, refreshLockKey(sid), []byte(jti), refreshLockTTL)
+	if err != nil {
+		return TokenPair{}, ErrInvalidToken
+	}
+	if !acquired {
+		replay, ok, waitErr := s.waitForRefreshReplay(ctx, jti, userID, sid)
+		if waitErr != nil {
+			return TokenPair{}, ErrInvalidToken
+		}
+		if ok {
+			return replay, nil
+		}
+		return TokenPair{}, ErrInvalidToken
+	}
+	defer func() {
+		_ = s.tokens.Delete(ctx, refreshLockKey(sid))
+	}()
+
+	var record *authSessionRecord
+	var raw []byte
+	raw, err = s.tokens.Get(ctx, refreshKey(jti))
+	if err != nil || raw == nil || !subtleConstantTimeCompare(raw, []byte(sid)) {
+		return TokenPair{}, ErrInvalidToken
+	}
+	record, err = s.loadSessionRecord(ctx, sid)
+	if err != nil || record == nil {
+		return TokenPair{}, ErrInvalidToken
+	}
+	if record.UserID != bytesToString(userID) || record.CurrentJTI != jti {
+		return TokenPair{}, ErrInvalidToken
+	}
+	if strings.EqualFold(strings.TrimSpace(record.AuthProvider), ssoProviderMicrosoft) {
+		if _, err := s.RefreshMicrosoftAccessToken(ctx, userID); err != nil {
+			// Only revoke when Microsoft says the grant is permanently invalid
+			// (invalid_grant/interaction_required/consent_required, or the
+			// stored refresh token is missing). Transient failures — network
+			// errors, 5xx, throttling, request timeouts, or an open circuit
+			// breaker — must NOT log the user out: keep the app session alive
+			// and retry Microsoft on the next refresh cycle.
+			if errors.Is(err, ErrMicrosoftReauthRequired) {
+				_ = s.RevokeUserSession(ctx, userID, sid)
+				return TokenPair{}, ErrInvalidToken
+			}
+		}
+	}
+	if s.isSessionIdleExpired(record) {
+		// SSO sessions may continue when Microsoft token refresh is still valid.
+		if !s.canRecoverSSOSessionOnIdle(ctx, userID, record) {
+			_ = s.RevokeUserSession(ctx, userID, sid)
+			return TokenPair{}, ErrInvalidToken
+		}
+	}
+
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil || user == nil || !user.IsActive {
+		return TokenPair{}, ErrInvalidToken
+	}
+	longLived := boolClaim(claims["ll"])
+	refreshTTL := s.cfg.JWTRefreshTTL
+	if longLived {
+		refreshTTL = s.cfg.JWTRefreshTOTPTTL
+	} else if strings.EqualFold(strings.TrimSpace(record.AuthProvider), ssoProviderMicrosoft) {
+		// Keep the session sliding with the Microsoft refresh token lifetime.
+		refreshTTL = s.providerRefreshTTL(ctx, userID, record.AuthProvider)
+	}
+	pair, err := s.issueTokensWithRefreshTTLAndClient(ctx, user, refreshTTL, longLived, sid, userAgent, ipAddress, "", deviceTypeHint, "")
+	if err != nil {
+		return TokenPair{}, err
+	}
+	if s.tokens != nil {
+		replay := newRefreshReplayPayload(pair, bytesToString(userID), sid)
+		if payload, marshalErr := json.Marshal(replay); marshalErr == nil {
+			_ = s.tokens.Set(ctx, refreshReplayKey(jti), payload, refreshReplayTTL)
+		}
+	}
+	return pair, nil
+}
+
+func (s *AuthService) loadRefreshReplay(ctx context.Context, jti string, userID []byte, sessionID string) (TokenPair, bool, error) {
+	if s.tokens == nil {
+		return TokenPair{}, false, nil
+	}
+	raw, err := s.tokens.Get(ctx, refreshReplayKey(jti))
+	if err != nil || raw == nil {
+		return TokenPair{}, false, err
+	}
+	var payload refreshReplayPayload
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		return TokenPair{}, false, err
+	}
+	if strings.TrimSpace(payload.SessionID) != strings.TrimSpace(sessionID) {
+		return TokenPair{}, false, nil
+	}
+	if strings.TrimSpace(payload.UserID) != bytesToString(userID) {
+		return TokenPair{}, false, nil
+	}
+	if !s.isSessionActive(ctx, userID, sessionID) {
+		return TokenPair{}, false, nil
+	}
+	return payload.toTokenPair(), true, nil
+}
+
+func (s *AuthService) waitForRefreshReplay(ctx context.Context, jti string, userID []byte, sessionID string) (TokenPair, bool, error) {
+	deadline := time.Now().UTC().Add(refreshReplayWaitTimeout)
+	for {
+		replay, ok, err := s.loadRefreshReplay(ctx, jti, userID, sessionID)
+		if err != nil {
+			return TokenPair{}, false, err
+		}
+		if ok {
+			return replay, true, nil
+		}
+		if time.Now().UTC().After(deadline) {
+			return TokenPair{}, false, nil
+		}
+		select {
+		case <-ctx.Done():
+			return TokenPair{}, false, ctx.Err()
+		case <-time.After(refreshReplayPollInterval):
+		}
+	}
+}
+
+func (s *AuthService) revokeRefreshTokenWithSession(ctx context.Context, refreshToken string) error {
+	if refreshToken == "" {
+		return nil
+	}
+	parsed, err := jwt.Parse(refreshToken, func(t *jwt.Token) (any, error) {
+		if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, ErrInvalidToken
+		}
+		return []byte(s.cfg.JWTRefreshSecret), nil
+	})
+	if err != nil || !parsed.Valid {
+		return nil
+	}
+	claims, ok := parsed.Claims.(jwt.MapClaims)
+	if !ok {
+		return nil
+	}
+	jti, _ := claims["jti"].(string)
+	sid, _ := claims["sid"].(string)
+	sub, _ := claims["sub"].(string)
+	if sid != "" && sub != "" {
+		if userID, err := uuidv7.ParseString(sub); err == nil {
+			_ = s.RevokeUserSession(ctx, userID, sid)
+			return nil
+		}
+	}
+	if jti != "" && s.tokens != nil {
+		_ = s.tokens.Delete(ctx, refreshKey(jti))
+	}
+	return nil
+}
+
+func (s *AuthService) ParseAccessTokenSessionID(ctx context.Context, accessToken string) (string, error) {
+	_, sid, err := s.parseAccessTokenWithSession(ctx, accessToken)
+	if err != nil {
+		return "", err
+	}
+	return sid, nil
+}
+
+func (s *AuthService) GetSessionAuthContextFromAccessToken(ctx context.Context, accessToken string) (string, string, error) {
+	_, sid, err := s.parseAccessTokenWithSession(ctx, accessToken)
+	if err != nil {
+		return "", "", err
+	}
+	if s.tokens == nil {
+		return "email", "email", nil
+	}
+	record, err := s.loadSessionRecord(ctx, sid)
+	if err != nil || record == nil {
+		return "", "", ErrInvalidToken
+	}
+	provider := strings.ToLower(strings.TrimSpace(record.AuthProvider))
+	if provider == ssoProviderMicrosoft {
+		return "sso", ssoProviderMicrosoft, nil
+	}
+	return "email", "email", nil
+}
+
+func (s *AuthService) ListUserSessions(ctx context.Context, userID []byte, currentSessionID string) ([]UserSession, error) {
+	if len(userID) != 16 {
+		return nil, ErrInvalidToken
+	}
+	if s.tokens == nil {
+		return []UserSession{}, nil
+	}
+	ids, err := s.loadUserSessionIDs(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]UserSession, 0, len(ids))
+	for i := range ids {
+		record, err := s.loadSessionRecord(ctx, ids[i])
+		if err != nil || record == nil {
+			continue
+		}
+		if record.UserID != bytesToString(userID) {
+			continue
+		}
+		out = append(out, UserSession{
+			ID:           record.SessionID,
+			DeviceName:   record.DeviceName,
+			UserAgent:    record.UserAgent,
+			IPAddress:    record.IPAddress,
+			CreatedAt:    record.CreatedAt,
+			LastActiveAt: record.LastActiveAt,
+			ActiveNow:    record.SessionID == currentSessionID,
+		})
+	}
+	sort.Slice(out, func(i, j int) bool {
+		return out[i].LastActiveAt.After(out[j].LastActiveAt)
+	})
+	return out, nil
+}
+
+func (s *AuthService) RevokeUserSession(ctx context.Context, userID []byte, sessionID string) error {
+	if len(userID) != 16 || strings.TrimSpace(sessionID) == "" {
+		return ErrInvalidToken
+	}
+	if s.tokens == nil {
+		return nil
+	}
+	record, err := s.loadSessionRecord(ctx, sessionID)
+	if err != nil {
+		return err
+	}
+	if record == nil {
+		return ErrSessionNotFound
+	}
+	if record.UserID != bytesToString(userID) {
+		return ErrInvalidToken
+	}
+	if strings.TrimSpace(record.CurrentJTI) != "" {
+		_ = s.tokens.Delete(ctx, refreshKey(record.CurrentJTI))
+	}
+	if strings.EqualFold(strings.TrimSpace(record.AuthProvider), ssoProviderMicrosoft) && strings.TrimSpace(record.MicrosoftSID) != "" {
+		_ = s.tokens.Delete(ctx, microsoftSessionKey(record.MicrosoftSID))
+	}
+	_ = s.tokens.Delete(ctx, sessionKey(sessionID))
+	_ = s.removeUserSessionID(ctx, userID, sessionID)
+	return nil
+}
+
+func (s *AuthService) RevokeSessionByID(ctx context.Context, sessionID string) error {
+	sessionID = strings.TrimSpace(sessionID)
+	if sessionID == "" {
+		return ErrInvalidToken
+	}
+	if s.tokens == nil {
+		return nil
+	}
+	record, err := s.loadSessionRecord(ctx, sessionID)
+	if err != nil {
+		return err
+	}
+	if record == nil {
+		return ErrSessionNotFound
+	}
+	userID, err := uuidv7.ParseString(strings.TrimSpace(record.UserID))
+	if err != nil {
+		return ErrInvalidToken
+	}
+	return s.RevokeUserSession(ctx, userID, sessionID)
+}
+
+func (s *AuthService) RevokeMicrosoftSessionBySID(ctx context.Context, microsoftSID string) error {
+	microsoftSID = strings.TrimSpace(microsoftSID)
+	if microsoftSID == "" {
+		return ErrInvalidToken
+	}
+	if s.tokens == nil {
+		return nil
+	}
+	raw, err := s.tokens.Get(ctx, microsoftSessionKey(microsoftSID))
+	if err != nil || raw == nil {
+		return err
+	}
+	sessionID := strings.TrimSpace(string(raw))
+	if sessionID == "" {
+		_ = s.tokens.Delete(ctx, microsoftSessionKey(microsoftSID))
+		return ErrSessionNotFound
+	}
+	record, err := s.loadSessionRecord(ctx, sessionID)
+	if err != nil {
+		return err
+	}
+	if record == nil {
+		_ = s.tokens.Delete(ctx, microsoftSessionKey(microsoftSID))
+		return ErrSessionNotFound
+	}
+	if !strings.EqualFold(strings.TrimSpace(record.MicrosoftSID), microsoftSID) {
+		_ = s.tokens.Delete(ctx, microsoftSessionKey(microsoftSID))
+		return ErrSessionNotFound
+	}
+	userID, err := uuidv7.ParseString(strings.TrimSpace(record.UserID))
+	if err != nil {
+		return ErrInvalidToken
+	}
+	return s.RevokeUserSession(ctx, userID, sessionID)
+}
+
+func (s *AuthService) RevokeAllUserSessions(ctx context.Context, userID []byte) error {
+	if len(userID) != 16 {
+		return ErrInvalidToken
+	}
+	if s.tokens == nil {
+		return nil
+	}
+	sessionIDs, err := s.loadUserSessionIDs(ctx, userID)
+	if err != nil {
+		return err
+	}
+	for i := range sessionIDs {
+		sessionID := strings.TrimSpace(sessionIDs[i])
+		if sessionID == "" {
+			continue
+		}
+		record, loadErr := s.loadSessionRecord(ctx, sessionID)
+		if loadErr != nil {
+			return loadErr
+		}
+		if record != nil && record.UserID == bytesToString(userID) && strings.TrimSpace(record.CurrentJTI) != "" {
+			_ = s.tokens.Delete(ctx, refreshKey(record.CurrentJTI))
+			if strings.EqualFold(strings.TrimSpace(record.AuthProvider), ssoProviderMicrosoft) && strings.TrimSpace(record.MicrosoftSID) != "" {
+				_ = s.tokens.Delete(ctx, microsoftSessionKey(record.MicrosoftSID))
+			}
+		}
+		_ = s.tokens.Delete(ctx, sessionKey(sessionID))
+	}
+	_ = s.replaceUserSessionIDs(ctx, userID, []string{})
+	return nil
+}
+
+func (s *AuthService) isSessionActive(ctx context.Context, userID []byte, sessionID string) bool {
+	if s.tokens == nil || len(userID) != 16 || strings.TrimSpace(sessionID) == "" {
+		return false
+	}
+	ids, err := s.loadUserSessionIDs(ctx, userID)
+	if err != nil {
+		return false
+	}
+	active := false
+	for i := range ids {
+		if ids[i] == sessionID {
+			active = true
+			break
+		}
+	}
+	if !active {
+		return false
+	}
+	record, err := s.loadSessionRecord(ctx, sessionID)
+	if err != nil {
+		return false
+	}
+	if record == nil {
+		return false
+	}
+	if record.UserID != bytesToString(userID) {
+		return false
+	}
+	return true
+}
+
+func (s *AuthService) isSessionIdleExpired(record *authSessionRecord) bool {
+	if record == nil || s.cfg.SessionIdleTTL <= 0 || record.LastActiveAt.IsZero() {
+		return false
+	}
+	if !strings.EqualFold(strings.TrimSpace(record.AuthProvider), ssoProviderMicrosoft) {
+		return false
+	}
+	return record.LastActiveAt.Add(s.cfg.SessionIdleTTL).Before(time.Now().UTC())
+}
+
+func (s *AuthService) canRecoverSSOSessionOnIdle(ctx context.Context, userID []byte, record *authSessionRecord) bool {
+	if record == nil || !strings.EqualFold(strings.TrimSpace(record.AuthProvider), ssoProviderMicrosoft) {
+		return false
+	}
+	if _, err := s.RefreshMicrosoftAccessToken(ctx, userID); err != nil {
+		// Transient Microsoft failures should not force a re-login on an idle
+		// session; only a permanent reauth-required error means it cannot
+		// recover.
+		return !errors.Is(err, ErrMicrosoftReauthRequired)
+	}
+	return true
+}
+
+func (s *AuthService) loadSessionRecord(ctx context.Context, sessionID string) (*authSessionRecord, error) {
+	raw, err := s.tokens.Get(ctx, sessionKey(sessionID))
+	if err != nil || raw == nil {
+		return nil, err
+	}
+	var record authSessionRecord
+	if err := json.Unmarshal(raw, &record); err != nil {
+		return nil, err
+	}
+	return &record, nil
+}
+
+func (s *AuthService) saveSessionRecord(ctx context.Context, session *authSessionRecord, ttl time.Duration) error {
+	if session == nil || strings.TrimSpace(session.SessionID) == "" {
+		return ErrInvalidToken
+	}
+	payload, err := json.Marshal(session)
+	if err != nil {
+		return err
+	}
+	if !session.RefreshExpAt.IsZero() {
+		remaining := time.Until(session.RefreshExpAt)
+		if remaining <= 0 {
+			return s.tokens.Delete(ctx, sessionKey(session.SessionID))
+		}
+		ttl = remaining
+	}
+	return s.tokens.Set(ctx, sessionKey(session.SessionID), payload, ttl)
+}
+
+func (s *AuthService) touchSessionActivity(ctx context.Context, userID []byte, sessionID string) {
+	if s.tokens == nil || len(userID) != 16 || strings.TrimSpace(sessionID) == "" {
+		return
+	}
+	record, err := s.loadSessionRecord(ctx, sessionID)
+	if err != nil || record == nil || record.UserID != bytesToString(userID) {
+		return
+	}
+	record.LastActiveAt = time.Now().UTC()
+	if record.RefreshExpAt.IsZero() {
+		_ = s.saveSessionRecord(ctx, record, s.cfg.JWTRefreshTTL)
+		return
+	}
+	_ = s.saveSessionRecord(ctx, record, time.Until(record.RefreshExpAt))
+}
+
+func (s *AuthService) replaceUserSessionIDs(ctx context.Context, userID []byte, sessionIDs []string) error {
+	unique := make([]string, 0, len(sessionIDs))
+	seen := make(map[string]struct{}, len(sessionIDs))
+	for i := range sessionIDs {
+		sessionID := strings.TrimSpace(sessionIDs[i])
+		if sessionID == "" {
+			continue
+		}
+		if _, ok := seen[sessionID]; ok {
+			continue
+		}
+		seen[sessionID] = struct{}{}
+		unique = append(unique, sessionID)
+	}
+	payload, err := json.Marshal(unique)
+	if err != nil {
+		return err
+	}
+	return s.tokens.Set(ctx, userSessionsKey(userID), payload, 0)
+}
+
+func (s *AuthService) loadUserSessionIDs(ctx context.Context, userID []byte) ([]string, error) {
+	raw, err := s.tokens.Get(ctx, userSessionsKey(userID))
+	if err != nil || raw == nil {
+		return []string{}, err
+	}
+	var ids []string
+	if err := json.Unmarshal(raw, &ids); err != nil {
+		return []string{}, nil
+	}
+	return ids, nil
+}
+
+func (s *AuthService) addUserSessionID(ctx context.Context, userID []byte, sessionID string) error {
+	if strings.TrimSpace(sessionID) == "" {
+		return nil
+	}
+	ids, err := s.loadUserSessionIDs(ctx, userID)
+	if err != nil {
+		return err
+	}
+	for i := range ids {
+		if ids[i] == sessionID {
+			return nil
+		}
+	}
+	ids = append(ids, sessionID)
+	payload, err := json.Marshal(ids)
+	if err != nil {
+		return err
+	}
+	return s.tokens.Set(ctx, userSessionsKey(userID), payload, 0)
+}
+
+func (s *AuthService) revokeStaleUserSessions(ctx context.Context, userID []byte, sessionIDs []string, keepSessionID string) error {
+	expectedUserID := bytesToString(userID)
+	seen := make(map[string]struct{}, len(sessionIDs))
+	for i := range sessionIDs {
+		sessionID := strings.TrimSpace(sessionIDs[i])
+		if sessionID == "" || sessionID == keepSessionID {
+			continue
+		}
+		if _, ok := seen[sessionID]; ok {
+			continue
+		}
+		seen[sessionID] = struct{}{}
+
+		record, err := s.loadSessionRecord(ctx, sessionID)
+		if err != nil {
+			return err
+		}
+		if record != nil && record.UserID == expectedUserID && strings.TrimSpace(record.CurrentJTI) != "" {
+			_ = s.tokens.Delete(ctx, refreshKey(record.CurrentJTI))
+		}
+		_ = s.tokens.Delete(ctx, sessionKey(sessionID))
+	}
+	return nil
+}
+
+func (s *AuthService) enforceUserDeviceSlots(ctx context.Context, userID []byte, existingSessionIDs []string, current *authSessionRecord) error {
+	if current == nil {
+		return nil
+	}
+	currentType := strings.TrimSpace(current.DeviceType)
+	if currentType == "" {
+		currentType = "unknown"
+	}
+	kept := make([]string, 0, len(existingSessionIDs)+1)
+	seen := map[string]struct{}{}
+	for i := range existingSessionIDs {
+		sessionID := strings.TrimSpace(existingSessionIDs[i])
+		if sessionID == "" || sessionID == current.SessionID {
+			continue
+		}
+		if _, ok := seen[sessionID]; ok {
+			continue
+		}
+		seen[sessionID] = struct{}{}
+		record, err := s.loadSessionRecord(ctx, sessionID)
+		if err != nil {
+			return err
+		}
+		if record == nil || record.UserID != bytesToString(userID) {
+			continue
+		}
+		recordType := strings.TrimSpace(record.DeviceType)
+		if recordType == "" {
+			recordType = classifyDeviceType(record.UserAgent, "")
+		}
+		if currentType != "unknown" && recordType == currentType {
+			if strings.TrimSpace(record.CurrentJTI) != "" {
+				_ = s.tokens.Delete(ctx, refreshKey(record.CurrentJTI))
+			}
+			_ = s.tokens.Delete(ctx, sessionKey(sessionID))
+			continue
+		}
+		kept = append(kept, sessionID)
+	}
+	kept = append(kept, current.SessionID)
+	return s.replaceUserSessionIDs(ctx, userID, kept)
+}
+
+func (s *AuthService) removeUserSessionID(ctx context.Context, userID []byte, sessionID string) error {
+	ids, err := s.loadUserSessionIDs(ctx, userID)
+	if err != nil {
+		return err
+	}
+	out := make([]string, 0, len(ids))
+	for i := range ids {
+		if ids[i] == sessionID {
+			continue
+		}
+		out = append(out, ids[i])
+	}
+	payload, err := json.Marshal(out)
+	if err != nil {
+		return err
+	}
+	return s.tokens.Set(ctx, userSessionsKey(userID), payload, 0)
+}
+
+func sessionKey(sessionID string) string {
+	return "auth:session:" + sessionID
+}
+
+func microsoftSessionKey(sessionID string) string {
+	return "auth:session:microsoft:sid:" + strings.TrimSpace(sessionID)
+}
+
+func userSessionsKey(userID []byte) string {
+	return "auth:sessions:user:" + bytesToString(userID)
+}
+
+func deriveDeviceName(userAgent string) string {
+	ua := strings.ToLower(strings.TrimSpace(userAgent))
+	if ua == "" {
+		return "Unknown device"
+	}
+	os := "Unknown OS"
+	switch {
+	case strings.Contains(ua, "iphone"):
+		os = "iPhone"
+	case strings.Contains(ua, "ipad"):
+		os = "iPad"
+	case strings.Contains(ua, "android"):
+		os = "Android"
+	case strings.Contains(ua, "mac os x"), strings.Contains(ua, "macintosh"):
+		os = "macOS"
+	case strings.Contains(ua, "windows"):
+		os = "Windows"
+	case strings.Contains(ua, "linux"):
+		os = "Linux"
+	}
+	browser := "Unknown browser"
+	switch {
+	case strings.Contains(ua, "edg/"):
+		browser = "Edge"
+	case strings.Contains(ua, "chrome/"):
+		browser = "Chrome"
+	case strings.Contains(ua, "firefox/"):
+		browser = "Firefox"
+	case strings.Contains(ua, "safari/"):
+		browser = "Safari"
+	}
+	return browser + " on " + os
+}
+
+func classifyDeviceType(userAgent, hint string) string {
+	if h := normalizeDeviceTypeHint(hint); h != "" {
+		return h
+	}
+	ua := strings.ToLower(strings.TrimSpace(userAgent))
+	if ua == "" {
+		return "unknown"
+	}
+	switch {
+	case strings.Contains(ua, "iphone"), strings.Contains(ua, "ipad"), strings.Contains(ua, "android"), strings.Contains(ua, "mobile"):
+		return "mobile"
+	case strings.Contains(ua, "windows"), strings.Contains(ua, "mac os x"), strings.Contains(ua, "macintosh"), strings.Contains(ua, "linux"), strings.Contains(ua, "x11"):
+		return "desktop"
+	default:
+		return "unknown"
+	}
+}
+
+func normalizeDeviceTypeHint(v string) string {
+	switch strings.ToLower(strings.TrimSpace(v)) {
+	case "mobile":
+		return "mobile"
+	case "desktop":
+		return "desktop"
+	default:
+		return ""
+	}
+}
diff --git a/internal/service/auth_webauthn.go b/internal/service/auth_webauthn.go
new file mode 100644
index 0000000..f9bdf39
--- /dev/null
+++ b/internal/service/auth_webauthn.go
@@ -0,0 +1,411 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/go-webauthn/webauthn/protocol"
+	webauthnlib "github.com/go-webauthn/webauthn/webauthn"
+
+	"wucher/internal/domain/auth"
+)
+
+const (
+	webAuthnCeremonyRegistration = "registration"
+	webAuthnCeremonyLogin        = "login"
+)
+
+var (
+	ErrWebAuthnNotConfigured         = errors.New("webauthn not configured")
+	ErrWebAuthnChallengeInvalid      = errors.New("invalid or expired webauthn challenge")
+	ErrWebAuthnPayloadInvalid        = errors.New("invalid webauthn payload")
+	ErrWebAuthnCredentialNotFound    = errors.New("webauthn credential not found")
+	ErrWebAuthnCredentialExists      = errors.New("webauthn credential already exists")
+	ErrWebAuthnCredentialUnavailable = errors.New("webauthn credential is not configured for this account")
+	ErrWebAuthnVerificationFailed    = errors.New("webauthn verification failed")
+)
+
+type webAuthnChallengeEnvelope struct {
+	Ceremony string                  `json:"ceremony"`
+	UserID   []byte                  `json:"user_id"`
+	Session  webauthnlib.SessionData `json:"session"`
+}
+
+type webAuthnUser struct {
+	id          []byte
+	name        string
+	displayName string
+	credentials []webauthnlib.Credential
+}
+
+func (u webAuthnUser) WebAuthnID() []byte {
+	return append([]byte(nil), u.id...)
+}
+
+func (u webAuthnUser) WebAuthnName() string {
+	return u.name
+}
+
+func (u webAuthnUser) WebAuthnDisplayName() string {
+	return u.displayName
+}
+
+func (u webAuthnUser) WebAuthnCredentials() []webauthnlib.Credential {
+	return append([]webauthnlib.Credential(nil), u.credentials...)
+}
+
+func (s *AuthService) WebAuthnChallengeTTL() time.Duration {
+	ttl := s.cfg.WebAuthnChallengeTTL
+	if ttl <= 0 {
+		return 5 * time.Minute
+	}
+	return ttl
+}
+
+func (s *AuthService) IsWebAuthnConfigured(ctx context.Context, userID []byte) (bool, error) {
+	records, err := s.repo.ListUserWebAuthnCredentials(ctx, userID)
+	if err != nil {
+		return false, err
+	}
+	return len(records) > 0, nil
+}
+
+func (s *AuthService) BeginWebAuthnRegistration(ctx context.Context, userID []byte) (*protocol.CredentialCreation, string, error) {
+	if len(userID) != 16 {
+		return nil, "", ErrInvalidToken
+	}
+	client, err := s.webAuthnClient()
+	if err != nil {
+		return nil, "", err
+	}
+
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return nil, "", err
+	}
+	if user == nil {
+		return nil, "", ErrInvalidToken
+	}
+
+	creds, err := s.loadWebAuthnCredentials(ctx, userID)
+	if err != nil {
+		return nil, "", err
+	}
+	waUser := buildWebAuthnUser(user, creds)
+
+	opts := []webauthnlib.RegistrationOption{
+		webauthnlib.WithConveyancePreference(protocol.PreferNoAttestation),
+		webauthnlib.WithResidentKeyRequirement(protocol.ResidentKeyRequirementPreferred),
+	}
+	if len(creds) > 0 {
+		opts = append(opts, webauthnlib.WithExclusions(webauthnlib.Credentials(creds).CredentialDescriptors()))
+	}
+
+	creation, session, err := client.BeginRegistration(waUser, opts...)
+	if err != nil {
+		return nil, "", err
+	}
+	challengeToken, err := s.storeWebAuthnChallenge(ctx, webAuthnCeremonyRegistration, userID, session)
+	if err != nil {
+		return nil, "", err
+	}
+	s.logServiceAudit(ctx, "auth.webauthn.register.begin", userID, true, "challenge_issued", nil)
+	return creation, challengeToken, nil
+}
+
+func (s *AuthService) FinishWebAuthnRegistration(ctx context.Context, userID []byte, challengeToken string, credentialJSON []byte, name string) error {
+	if len(userID) != 16 {
+		return ErrInvalidToken
+	}
+	client, err := s.webAuthnClient()
+	if err != nil {
+		return err
+	}
+	session, err := s.consumeWebAuthnChallenge(ctx, challengeToken, webAuthnCeremonyRegistration)
+	if err != nil {
+		s.logServiceAudit(ctx, "auth.webauthn.register.finish", userID, false, "invalid_challenge", nil)
+		return err
+	}
+	if !bytes.Equal(session.UserID, userID) {
+		s.logServiceAudit(ctx, "auth.webauthn.register.finish", userID, false, "challenge_user_mismatch", nil)
+		return ErrWebAuthnChallengeInvalid
+	}
+
+	user, err := s.repo.GetUserByID(ctx, userID)
+	if err != nil {
+		return err
+	}
+	if user == nil {
+		return ErrInvalidToken
+	}
+	creds, err := s.loadWebAuthnCredentials(ctx, userID)
+	if err != nil {
+		return err
+	}
+	waUser := buildWebAuthnUser(user, creds)
+
+	parsed, err := protocol.ParseCredentialCreationResponseBody(bytes.NewReader(credentialJSON))
+	if err != nil {
+		s.logServiceAudit(ctx, "auth.webauthn.register.finish", userID, false, "invalid_payload", nil)
+		return ErrWebAuthnPayloadInvalid
+	}
+
+	credential, err := client.CreateCredential(waUser, session.Session, parsed)
+	if err != nil {
+		s.logServiceAudit(ctx, "auth.webauthn.register.finish", userID, false, "verification_failed", nil)
+		return ErrWebAuthnVerificationFailed
+	}
+
+	for i := range creds {
+		if bytes.Equal(creds[i].ID, credential.ID) {
+			return ErrWebAuthnCredentialExists
+		}
+	}
+
+	serialized, err := json.Marshal(credential)
+	if err != nil {
+		return err
+	}
+
+	rec := &auth.UserWebAuthnCredential{
+		UserID:         userID,
+		Name:           truncate(strings.TrimSpace(name), 100),
+		CredentialID:   append([]byte(nil), credential.ID...),
+		CredentialJSON: serialized,
+	}
+	if err := s.repo.CreateUserWebAuthnCredential(ctx, rec); err != nil {
+		return err
+	}
+	s.logServiceAudit(ctx, "auth.webauthn.register.finish", userID, true, "credential_registered", nil)
+	return nil
+}
+
+func (s *AuthService) BeginWebAuthnLogin(ctx context.Context, email string) (*protocol.CredentialAssertion, string, error) {
+	client, err := s.webAuthnClient()
+	if err != nil {
+		return nil, "", err
+	}
+	email = strings.ToLower(strings.TrimSpace(email))
+	user, err := s.repo.GetUserByEmail(ctx, email)
+	if err != nil {
+		return nil, "", err
+	}
+	if user == nil {
+		return nil, "", ErrInvalidCredentials
+	}
+	if !user.IsActive {
+		return nil, "", ErrInvalidCredentials
+	}
+	if user.EmailVerifiedAt == nil {
+		return nil, "", ErrEmailNotVerified
+	}
+
+	creds, err := s.loadWebAuthnCredentials(ctx, user.ID)
+	if err != nil {
+		return nil, "", err
+	}
+	if len(creds) == 0 {
+		return nil, "", ErrWebAuthnCredentialUnavailable
+	}
+
+	waUser := buildWebAuthnUser(user, creds)
+	assertion, session, err := client.BeginLogin(waUser, webauthnlib.WithUserVerification(protocol.VerificationRequired))
+	if err != nil {
+		return nil, "", err
+	}
+	challengeToken, err := s.storeWebAuthnChallenge(ctx, webAuthnCeremonyLogin, user.ID, session)
+	if err != nil {
+		return nil, "", err
+	}
+	s.logServiceAudit(ctx, "auth.webauthn.login.begin", user.ID, true, "challenge_issued", nil)
+	return assertion, challengeToken, nil
+}
+
+func (s *AuthService) FinishWebAuthnLogin(ctx context.Context, challengeToken string, credentialJSON []byte) (*auth.User, error) {
+	client, err := s.webAuthnClient()
+	if err != nil {
+		return nil, err
+	}
+	session, err := s.consumeWebAuthnChallenge(ctx, challengeToken, webAuthnCeremonyLogin)
+	if err != nil {
+		s.logServiceAudit(ctx, "auth.webauthn.login.finish", nil, false, "invalid_challenge", nil)
+		return nil, err
+	}
+	if len(session.UserID) != 16 {
+		return nil, ErrWebAuthnChallengeInvalid
+	}
+
+	user, err := s.repo.GetUserByID(ctx, session.UserID)
+	if err != nil {
+		return nil, err
+	}
+	if user == nil {
+		return nil, ErrInvalidCredentials
+	}
+
+	creds, err := s.loadWebAuthnCredentials(ctx, session.UserID)
+	if err != nil {
+		return nil, err
+	}
+	if len(creds) == 0 {
+		return nil, ErrWebAuthnCredentialUnavailable
+	}
+	waUser := buildWebAuthnUser(user, creds)
+
+	parsed, err := protocol.ParseCredentialRequestResponseBody(bytes.NewReader(credentialJSON))
+	if err != nil {
+		s.logServiceAudit(ctx, "auth.webauthn.login.finish", session.UserID, false, "invalid_payload", nil)
+		return nil, ErrWebAuthnPayloadInvalid
+	}
+	credential, err := client.ValidateLogin(waUser, session.Session, parsed)
+	if err != nil {
+		s.logServiceAudit(ctx, "auth.webauthn.login.finish", session.UserID, false, "verification_failed", nil)
+		return nil, ErrWebAuthnVerificationFailed
+	}
+
+	serialized, err := json.Marshal(credential)
+	if err != nil {
+		return nil, err
+	}
+	if err := s.repo.UpdateUserWebAuthnCredential(ctx, session.UserID, credential.ID, serialized, time.Now().UTC()); err != nil {
+		return nil, err
+	}
+
+	s.logServiceAudit(ctx, "auth.webauthn.login.finish", session.UserID, true, "login_success", nil)
+	return user, nil
+}
+
+func (s *AuthService) webAuthnClient() (*webauthnlib.WebAuthn, error) {
+	rpID := strings.TrimSpace(s.cfg.WebAuthnRPID)
+	rpDisplayName := strings.TrimSpace(s.cfg.WebAuthnRPDisplayName)
+	rpOrigins := make([]string, 0, len(s.cfg.WebAuthnRPOrigins))
+	for i := range s.cfg.WebAuthnRPOrigins {
+		origin := strings.TrimSpace(s.cfg.WebAuthnRPOrigins[i])
+		if origin == "" {
+			continue
+		}
+		rpOrigins = append(rpOrigins, origin)
+	}
+
+	if rpID == "" || len(rpOrigins) == 0 {
+		return nil, ErrWebAuthnNotConfigured
+	}
+	if rpDisplayName == "" {
+		rpDisplayName = "Wucher"
+	}
+
+	ttl := s.WebAuthnChallengeTTL()
+	return webauthnlib.New(&webauthnlib.Config{
+		RPID:                  rpID,
+		RPDisplayName:         rpDisplayName,
+		RPOrigins:             rpOrigins,
+		AttestationPreference: protocol.PreferNoAttestation,
+		AuthenticatorSelection: protocol.AuthenticatorSelection{
+			ResidentKey:        protocol.ResidentKeyRequirementPreferred,
+			RequireResidentKey: protocol.ResidentKeyNotRequired(),
+			UserVerification:   protocol.VerificationRequired,
+		},
+		Timeouts: webauthnlib.TimeoutsConfig{
+			Login: webauthnlib.TimeoutConfig{
+				Enforce:    true,
+				Timeout:    ttl,
+				TimeoutUVD: ttl,
+			},
+			Registration: webauthnlib.TimeoutConfig{
+				Enforce:    true,
+				Timeout:    ttl,
+				TimeoutUVD: ttl,
+			},
+		},
+	})
+}
+
+func (s *AuthService) loadWebAuthnCredentials(ctx context.Context, userID []byte) ([]webauthnlib.Credential, error) {
+	records, err := s.repo.ListUserWebAuthnCredentials(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]webauthnlib.Credential, 0, len(records))
+	for i := range records {
+		var credential webauthnlib.Credential
+		if err := json.Unmarshal(records[i].CredentialJSON, &credential); err != nil {
+			return nil, err
+		}
+		out = append(out, credential)
+	}
+	return out, nil
+}
+
+func buildWebAuthnUser(user *auth.User, credentials []webauthnlib.Credential) webAuthnUser {
+	name := strings.TrimSpace(user.Email)
+	displayName := strings.TrimSpace(strings.TrimSpace(user.FirstName) + " " + strings.TrimSpace(user.LastName))
+	if displayName == "" {
+		displayName = name
+	}
+	return webAuthnUser{
+		id:          append([]byte(nil), user.ID...),
+		name:        name,
+		displayName: displayName,
+		credentials: credentials,
+	}
+}
+
+func (s *AuthService) storeWebAuthnChallenge(ctx context.Context, ceremony string, userID []byte, session *webauthnlib.SessionData) (string, error) {
+	if s.tokens == nil {
+		return "", ErrWebAuthnChallengeInvalid
+	}
+	if session == nil {
+		return "", ErrWebAuthnChallengeInvalid
+	}
+
+	token, err := randomToken(32)
+	if err != nil {
+		return "", err
+	}
+	envelope := webAuthnChallengeEnvelope{
+		Ceremony: ceremony,
+		UserID:   append([]byte(nil), userID...),
+		Session:  *session,
+	}
+	payload, err := json.Marshal(envelope)
+	if err != nil {
+		return "", err
+	}
+	if err := s.tokens.Set(ctx, webAuthnChallengeKey(token), payload, s.WebAuthnChallengeTTL()); err != nil {
+		return "", err
+	}
+	return token, nil
+}
+
+func (s *AuthService) consumeWebAuthnChallenge(ctx context.Context, token, ceremony string) (*webAuthnChallengeEnvelope, error) {
+	token = strings.TrimSpace(token)
+	if token == "" || s.tokens == nil {
+		return nil, ErrWebAuthnChallengeInvalid
+	}
+
+	raw, err := s.tokens.Get(ctx, webAuthnChallengeKey(token))
+	if err != nil || raw == nil {
+		return nil, ErrWebAuthnChallengeInvalid
+	}
+	_ = s.tokens.Delete(ctx, webAuthnChallengeKey(token))
+
+	var envelope webAuthnChallengeEnvelope
+	if err := json.Unmarshal(raw, &envelope); err != nil {
+		return nil, ErrWebAuthnChallengeInvalid
+	}
+	if strings.TrimSpace(envelope.Ceremony) != ceremony {
+		return nil, ErrWebAuthnChallengeInvalid
+	}
+	if !envelope.Session.Expires.IsZero() && envelope.Session.Expires.Before(time.Now().UTC()) {
+		return nil, ErrWebAuthnChallengeInvalid
+	}
+	return &envelope, nil
+}
+
+func webAuthnChallengeKey(token string) string {
+	return "auth:webauthn:challenge:" + token
+}
diff --git a/internal/service/auth_webauthn_test.go b/internal/service/auth_webauthn_test.go
new file mode 100644
index 0000000..f2d57d9
--- /dev/null
+++ b/internal/service/auth_webauthn_test.go
@@ -0,0 +1,1007 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"encoding/json"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+	"time"
+
+	webauthnlib "github.com/go-webauthn/webauthn/webauthn"
+
+	"wucher/internal/config"
+	"wucher/internal/domain/auth"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	testCredentialCreationResponseJSON = `{
+	"id":"6xrtBhJQW6QU4tOaB4rrHaS2Ks0yDDL_q8jDC16DEjZ-VLVf4kCRkvl2xp2D71sTPYns-exsHQHTy3G-zJRK8g",
+	"rawId":"6xrtBhJQW6QU4tOaB4rrHaS2Ks0yDDL_q8jDC16DEjZ-VLVf4kCRkvl2xp2D71sTPYns-exsHQHTy3G-zJRK8g",
+	"type":"public-key",
+	"authenticatorAttachment":"platform",
+	"clientExtensionResults":{"appid":true},
+	"response":{
+		"attestationObject":"o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVjEdKbqkhPJnC90siSSsyDPQCYqlMGpUKA5fyklC2CEHvBBAAAAAAAAAAAAAAAAAAAAAAAAAAAAQOsa7QYSUFukFOLTmgeK6x2ktirNMgwy_6vIwwtegxI2flS1X-JAkZL5dsadg-9bEz2J7PnsbB0B08txvsyUSvKlAQIDJiABIVggLKF5xS0_BntttUIrm2Z2tgZ4uQDwllbdIfrrBMABCNciWCDHwin8Zdkr56iSIh0MrB5qZiEzYLQpEOREhMUkY6q4Vw",
+		"clientDataJSON":"eyJjaGFsbGVuZ2UiOiJXOEd6RlU4cEdqaG9SYldyTERsYW1BZnFfeTRTMUNaRzFWdW9lUkxBUnJFIiwib3JpZ2luIjoiaHR0cHM6Ly93ZWJhdXRobi5pbyIsInR5cGUiOiJ3ZWJhdXRobi5jcmVhdGUifQ",
+		"transports":["usb","nfc","fake"]
+	}
+}`
+	testCredentialAssertionResponseJSON = `{
+	"id":"AI7D5q2P0LS-Fal9ZT7CHM2N5BLbUunF92T8b6iYC199bO2kagSuU05-5dZGqb1SP0A0lyTWng",
+	"rawId":"AI7D5q2P0LS-Fal9ZT7CHM2N5BLbUunF92T8b6iYC199bO2kagSuU05-5dZGqb1SP0A0lyTWng",
+	"clientExtensionResults":{"appID":"example.com"},
+	"type":"public-key",
+	"response":{
+		"authenticatorData":"dKbqkhPJnC90siSSsyDPQCYqlMGpUKA5fyklC2CEHvBFXJJiGa3OAAI1vMYKZIsLJfHwVQMANwCOw-atj9C0vhWpfWU-whzNjeQS21Lpxfdk_G-omAtffWztpGoErlNOfuXWRqm9Uj9ANJck1p6lAQIDJiABIVggKAhfsdHcBIc0KPgAcRyAIK_-Vi-nCXHkRHPNaCMBZ-4iWCBxB8fGYQSBONi9uvq0gv95dGWlhJrBwCsj_a4LJQKVHQ",
+		"clientDataJSON":"eyJjaGFsbGVuZ2UiOiJFNFBUY0lIX0hmWDFwQzZTaWdrMVNDOU5BbGdlenROMDQzOXZpOHpfYzlrIiwibmV3X2tleXNfbWF5X2JlX2FkZGVkX2hlcmUiOiJkbyBub3QgY29tcGFyZSBjbGllbnREYXRhSlNPTiBhZ2FpbnN0IGEgdGVtcGxhdGUuIFNlZSBodHRwczovL2dvby5nbC95YWJQZXgiLCJvcmlnaW4iOiJodHRwczovL3dlYmF1dGhuLmlvIiwidHlwZSI6IndlYmF1dGhuLmdldCJ9",
+		"signature":"MEUCIBtIVOQxzFYdyWQyxaLR0tik1TnuPhGVhXVSNgFwLmN5AiEAnxXdCq0UeAVGWxOaFcjBZ_mEZoXqNboY5IkQDdlWZYc",
+		"userHandle":"0ToAAAAAAAAAAA"
+	}
+}`
+)
+
+type webAuthnRepoWithErrors struct {
+	*mockAuthRepo
+	listCredsErr  error
+	createCredErr error
+	updateCredErr error
+}
+
+func newWebAuthnRepoWithErrors() *webAuthnRepoWithErrors {
+	return &webAuthnRepoWithErrors{mockAuthRepo: newMockAuthRepo()}
+}
+
+func (r *webAuthnRepoWithErrors) ListUserWebAuthnCredentials(ctx context.Context, userID []byte) ([]auth.UserWebAuthnCredential, error) {
+	if r.listCredsErr != nil {
+		return nil, r.listCredsErr
+	}
+	return r.mockAuthRepo.ListUserWebAuthnCredentials(ctx, userID)
+}
+
+func (r *webAuthnRepoWithErrors) CreateUserWebAuthnCredential(ctx context.Context, credential *auth.UserWebAuthnCredential) error {
+	if r.createCredErr != nil {
+		return r.createCredErr
+	}
+	return r.mockAuthRepo.CreateUserWebAuthnCredential(ctx, credential)
+}
+
+func (r *webAuthnRepoWithErrors) UpdateUserWebAuthnCredential(ctx context.Context, userID, credentialID, credentialJSON []byte, usedAt time.Time) error {
+	if r.updateCredErr != nil {
+		return r.updateCredErr
+	}
+	return r.mockAuthRepo.UpdateUserWebAuthnCredential(ctx, userID, credentialID, credentialJSON, usedAt)
+}
+
+func newConfiguredWebAuthnService(repo auth.Repository, tokens TokenStore) *AuthService {
+	return NewAuthService(
+		repo,
+		newMockRoleRepo(),
+		tokens,
+		nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			WebAuthnRPID:          "example.com",
+			WebAuthnRPDisplayName: "Wucher Test",
+			WebAuthnRPOrigins:     []string{"https://example.com"},
+			WebAuthnChallengeTTL:  2 * time.Minute,
+		}},
+	)
+}
+
+func putWebAuthnChallengeToken(t *testing.T, tokens *mockTokenStore, token, ceremony string, userID []byte, expires time.Time) {
+	t.Helper()
+	envelope := webAuthnChallengeEnvelope{
+		Ceremony: ceremony,
+		UserID:   append([]byte(nil), userID...),
+		Session: webauthnlib.SessionData{
+			Challenge:      "challenge",
+			RelyingPartyID: "example.com",
+			UserID:         append([]byte(nil), userID...),
+			Expires:        expires,
+		},
+	}
+	payload, err := json.Marshal(envelope)
+	if err != nil {
+		t.Fatalf("marshal envelope: %v", err)
+	}
+	tokens.store[webAuthnChallengeKey(token)] = payload
+}
+
+func TestWebAuthnUserMethods(t *testing.T) {
+	user := webAuthnUser{
+		id:          []byte{1, 2, 3},
+		name:        "user@example.com",
+		displayName: "User Example",
+		credentials: []webauthnlib.Credential{{ID: []byte{9, 8, 7}}},
+	}
+
+	id := user.WebAuthnID()
+	if !bytes.Equal(id, []byte{1, 2, 3}) {
+		t.Fatalf("unexpected id: %v", id)
+	}
+	id[0] = 99
+	if user.id[0] == 99 {
+		t.Fatalf("expected returned id to be copied")
+	}
+
+	if user.WebAuthnName() != "user@example.com" {
+		t.Fatalf("unexpected name")
+	}
+	if user.WebAuthnDisplayName() != "User Example" {
+		t.Fatalf("unexpected display name")
+	}
+
+	creds := user.WebAuthnCredentials()
+	if len(creds) != 1 {
+		t.Fatalf("unexpected credential length")
+	}
+	creds = append(creds, webauthnlib.Credential{})
+	if len(user.credentials) != 1 {
+		t.Fatalf("expected credential slice header to be copied")
+	}
+}
+
+func TestBuildWebAuthnUser(t *testing.T) {
+	uid := uuidv7.MustBytes()
+	credential := webauthnlib.Credential{ID: []byte{1, 2, 3}}
+	user := &auth.User{
+		ID:        uid,
+		Email:     "  alice@example.com ",
+		FirstName: "  Alice ",
+		LastName:  " Smith  ",
+		IsActive:  true,
+	}
+	waUser := buildWebAuthnUser(user, []webauthnlib.Credential{credential})
+	if waUser.WebAuthnName() != "alice@example.com" {
+		t.Fatalf("unexpected webauthn name")
+	}
+	if waUser.WebAuthnDisplayName() != "Alice Smith" {
+		t.Fatalf("unexpected webauthn display name")
+	}
+	if !bytes.Equal(waUser.WebAuthnID(), uid) {
+		t.Fatalf("unexpected webauthn id")
+	}
+
+	fallback := buildWebAuthnUser(&auth.User{
+		ID:        uid,
+		Email:     "bob@example.com",
+		FirstName: " ",
+		LastName:  " ",
+		IsActive:  true,
+	}, nil)
+	if fallback.WebAuthnDisplayName() != "bob@example.com" {
+		t.Fatalf("expected display name fallback to email")
+	}
+}
+
+func TestAuthServiceIsWebAuthnConfigured(t *testing.T) {
+	t.Run("no credentials", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		svc := newConfiguredWebAuthnService(repo, newMockTokenStore())
+		ok, err := svc.IsWebAuthnConfigured(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if ok {
+			t.Fatalf("expected not configured")
+		}
+	})
+
+	t.Run("has credentials", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		userID := uuidv7.MustBytes()
+		repo.webauthnCredentials[string(userID)] = []auth.UserWebAuthnCredential{{
+			ID:           uuidv7.MustBytes(),
+			UserID:       userID,
+			CredentialID: []byte("cred-1"),
+		}}
+		svc := newConfiguredWebAuthnService(repo, newMockTokenStore())
+		ok, err := svc.IsWebAuthnConfigured(context.Background(), userID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if !ok {
+			t.Fatalf("expected configured")
+		}
+	})
+
+	t.Run("repo error", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		repo.listCredsErr = errors.New("list failed")
+		svc := newConfiguredWebAuthnService(repo, newMockTokenStore())
+		ok, err := svc.IsWebAuthnConfigured(context.Background(), uuidv7.MustBytes())
+		if !errors.Is(err, repo.listCredsErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+		if ok {
+			t.Fatalf("expected configured false on error")
+		}
+	})
+}
+
+func TestAuthServiceWebAuthnChallengeTTL(t *testing.T) {
+	svcDefault := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+		WebAuthnChallengeTTL: 0,
+	}})
+	if got := svcDefault.WebAuthnChallengeTTL(); got != 5*time.Minute {
+		t.Fatalf("expected default ttl 5m, got %v", got)
+	}
+
+	svcCustom := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+		WebAuthnChallengeTTL: 42 * time.Second,
+	}})
+	if got := svcCustom.WebAuthnChallengeTTL(); got != 42*time.Second {
+		t.Fatalf("expected custom ttl, got %v", got)
+	}
+}
+
+func TestAuthServiceWebAuthnClient(t *testing.T) {
+	t.Run("missing rpid", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			WebAuthnRPOrigins: []string{"https://example.com"},
+		}})
+		if _, err := svc.webAuthnClient(); !errors.Is(err, ErrWebAuthnNotConfigured) {
+			t.Fatalf("expected not configured error, got %v", err)
+		}
+	})
+
+	t.Run("missing origins", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			WebAuthnRPID: "example.com",
+		}})
+		if _, err := svc.webAuthnClient(); !errors.Is(err, ErrWebAuthnNotConfigured) {
+			t.Fatalf("expected not configured error, got %v", err)
+		}
+	})
+
+	t.Run("success trims and defaults", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), nil, nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			WebAuthnRPID:          " example.com ",
+			WebAuthnRPDisplayName: " ",
+			WebAuthnRPOrigins:     []string{" ", " https://example.com "},
+			WebAuthnChallengeTTL:  30 * time.Second,
+		}})
+		client, err := svc.webAuthnClient()
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if client == nil || client.Config == nil {
+			t.Fatalf("expected webauthn client")
+		}
+		if client.Config.RPID != "example.com" {
+			t.Fatalf("unexpected rpid: %q", client.Config.RPID)
+		}
+		if client.Config.RPDisplayName != "Wucher" {
+			t.Fatalf("expected default rp display name, got %q", client.Config.RPDisplayName)
+		}
+		if len(client.Config.RPOrigins) != 1 || client.Config.RPOrigins[0] != "https://example.com" {
+			t.Fatalf("unexpected rp origins: %#v", client.Config.RPOrigins)
+		}
+		if client.Config.Timeouts.Login.Timeout != 30*time.Second {
+			t.Fatalf("unexpected login timeout: %v", client.Config.Timeouts.Login.Timeout)
+		}
+	})
+}
+
+func TestAuthServiceStoreWebAuthnChallenge(t *testing.T) {
+	t.Run("nil token store", func(t *testing.T) {
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), nil)
+		session := &webauthnlib.SessionData{Challenge: "a"}
+		if _, err := svc.storeWebAuthnChallenge(context.Background(), webAuthnCeremonyLogin, []byte{1}, session); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge error, got %v", err)
+		}
+	})
+
+	t.Run("nil session", func(t *testing.T) {
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), newMockTokenStore())
+		if _, err := svc.storeWebAuthnChallenge(context.Background(), webAuthnCeremonyLogin, []byte{1}, nil); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge error, got %v", err)
+		}
+	})
+
+	t.Run("random token failure", func(t *testing.T) {
+		orig := rand.Reader
+		rand.Reader = errReader{}
+		defer func() { rand.Reader = orig }()
+
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), newMockTokenStore())
+		session := &webauthnlib.SessionData{Challenge: "abc"}
+		if _, err := svc.storeWebAuthnChallenge(context.Background(), webAuthnCeremonyRegistration, []byte{1}, session); !errors.Is(err, io.ErrUnexpectedEOF) {
+			t.Fatalf("expected random token error, got %v", err)
+		}
+	})
+
+	t.Run("token store set error", func(t *testing.T) {
+		tokens := newMockTokenStore()
+		tokens.setErr = errors.New("set failed")
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), tokens)
+		session := &webauthnlib.SessionData{Challenge: "abc"}
+		if _, err := svc.storeWebAuthnChallenge(context.Background(), webAuthnCeremonyRegistration, []byte{1, 2}, session); !errors.Is(err, tokens.setErr) {
+			t.Fatalf("expected set error, got %v", err)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		tokens := newMockTokenStore()
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), tokens)
+		userID := uuidv7.MustBytes()
+		session := &webauthnlib.SessionData{
+			Challenge:      "abc",
+			RelyingPartyID: "example.com",
+			UserID:         userID,
+			Expires:        time.Now().UTC().Add(time.Minute),
+		}
+		token, err := svc.storeWebAuthnChallenge(context.Background(), webAuthnCeremonyLogin, userID, session)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if strings.TrimSpace(token) == "" {
+			t.Fatalf("expected token")
+		}
+		if !strings.HasPrefix(tokens.lastKey, "auth:webauthn:challenge:") {
+			t.Fatalf("unexpected key: %q", tokens.lastKey)
+		}
+
+		raw := tokens.store[tokens.lastKey]
+		var envelope webAuthnChallengeEnvelope
+		if err := json.Unmarshal(raw, &envelope); err != nil {
+			t.Fatalf("unmarshal envelope: %v", err)
+		}
+		if envelope.Ceremony != webAuthnCeremonyLogin || !bytes.Equal(envelope.UserID, userID) {
+			t.Fatalf("unexpected envelope")
+		}
+	})
+}
+
+func TestAuthServiceConsumeWebAuthnChallenge(t *testing.T) {
+	t.Run("empty token", func(t *testing.T) {
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), newMockTokenStore())
+		if _, err := svc.consumeWebAuthnChallenge(context.Background(), " ", webAuthnCeremonyLogin); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge error, got %v", err)
+		}
+	})
+
+	t.Run("nil token store", func(t *testing.T) {
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), nil)
+		if _, err := svc.consumeWebAuthnChallenge(context.Background(), "token", webAuthnCeremonyLogin); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge error, got %v", err)
+		}
+	})
+
+	t.Run("get error", func(t *testing.T) {
+		tokens := newMockTokenStore()
+		tokens.getErr = errors.New("token store down")
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), tokens)
+		if _, err := svc.consumeWebAuthnChallenge(context.Background(), "token", webAuthnCeremonyLogin); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge error, got %v", err)
+		}
+	})
+
+	t.Run("missing token", func(t *testing.T) {
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), newMockTokenStore())
+		if _, err := svc.consumeWebAuthnChallenge(context.Background(), "missing", webAuthnCeremonyLogin); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge error, got %v", err)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		tokens := newMockTokenStore()
+		tokens.store[webAuthnChallengeKey("badjson")] = []byte("{bad")
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), tokens)
+		if _, err := svc.consumeWebAuthnChallenge(context.Background(), "badjson", webAuthnCeremonyLogin); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge error, got %v", err)
+		}
+	})
+
+	t.Run("ceremony mismatch", func(t *testing.T) {
+		tokens := newMockTokenStore()
+		putWebAuthnChallengeToken(t, tokens, "mismatch", webAuthnCeremonyRegistration, uuidv7.MustBytes(), time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), tokens)
+		if _, err := svc.consumeWebAuthnChallenge(context.Background(), "mismatch", webAuthnCeremonyLogin); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge error, got %v", err)
+		}
+	})
+
+	t.Run("expired", func(t *testing.T) {
+		tokens := newMockTokenStore()
+		putWebAuthnChallengeToken(t, tokens, "expired", webAuthnCeremonyLogin, uuidv7.MustBytes(), time.Now().UTC().Add(-time.Second))
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), tokens)
+		if _, err := svc.consumeWebAuthnChallenge(context.Background(), "expired", webAuthnCeremonyLogin); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge error, got %v", err)
+		}
+	})
+
+	t.Run("success deletes token", func(t *testing.T) {
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		putWebAuthnChallengeToken(t, tokens, "ok", webAuthnCeremonyLogin, userID, time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), tokens)
+		envelope, err := svc.consumeWebAuthnChallenge(context.Background(), "ok", webAuthnCeremonyLogin)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if envelope == nil || !bytes.Equal(envelope.UserID, userID) {
+			t.Fatalf("unexpected envelope")
+		}
+		if _, found := tokens.store[webAuthnChallengeKey("ok")]; found {
+			t.Fatalf("expected challenge token to be deleted")
+		}
+	})
+}
+
+func TestWebAuthnChallengeKey(t *testing.T) {
+	if got := webAuthnChallengeKey("abc"); got != "auth:webauthn:challenge:abc" {
+		t.Fatalf("unexpected key: %q", got)
+	}
+}
+
+func TestAuthServiceLoadWebAuthnCredentials(t *testing.T) {
+	t.Run("repo list error", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		repo.listCredsErr = errors.New("list creds failed")
+		svc := newConfiguredWebAuthnService(repo, nil)
+		if _, err := svc.loadWebAuthnCredentials(context.Background(), uuidv7.MustBytes()); !errors.Is(err, repo.listCredsErr) {
+			t.Fatalf("expected list error, got %v", err)
+		}
+	})
+
+	t.Run("invalid credential json", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		userID := uuidv7.MustBytes()
+		repo.webauthnCredentials[string(userID)] = []auth.UserWebAuthnCredential{{
+			UserID:         userID,
+			CredentialID:   []byte{1},
+			CredentialJSON: []byte("{bad"),
+		}}
+		svc := newConfiguredWebAuthnService(repo, nil)
+		if _, err := svc.loadWebAuthnCredentials(context.Background(), userID); err == nil {
+			t.Fatalf("expected unmarshal error")
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		userID := uuidv7.MustBytes()
+		serialized, err := json.Marshal(webauthnlib.Credential{
+			ID:              []byte{1, 2, 3},
+			PublicKey:       []byte{4, 5, 6},
+			AttestationType: "none",
+		})
+		if err != nil {
+			t.Fatalf("marshal credential: %v", err)
+		}
+		repo.webauthnCredentials[string(userID)] = []auth.UserWebAuthnCredential{{
+			UserID:         userID,
+			CredentialID:   []byte{1, 2, 3},
+			CredentialJSON: serialized,
+		}}
+		svc := newConfiguredWebAuthnService(repo, nil)
+		creds, err := svc.loadWebAuthnCredentials(context.Background(), userID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(creds) != 1 || !bytes.Equal(creds[0].ID, []byte{1, 2, 3}) {
+			t.Fatalf("unexpected credentials")
+		}
+	})
+}
+
+func TestAuthServiceBeginWebAuthnRegistrationBranches(t *testing.T) {
+	t.Run("invalid user id length", func(t *testing.T) {
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), newMockTokenStore())
+		if _, _, err := svc.BeginWebAuthnRegistration(context.Background(), []byte("short")); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token, got %v", err)
+		}
+	})
+
+	t.Run("not configured", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), newMockTokenStore(), nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if _, _, err := svc.BeginWebAuthnRegistration(context.Background(), uuidv7.MustBytes()); !errors.Is(err, ErrWebAuthnNotConfigured) {
+			t.Fatalf("expected not configured, got %v", err)
+		}
+	})
+
+	t.Run("user fetch error", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		repo.getByIDErr = errors.New("db failed")
+		svc := newConfiguredWebAuthnService(repo, newMockTokenStore())
+		if _, _, err := svc.BeginWebAuthnRegistration(context.Background(), uuidv7.MustBytes()); !errors.Is(err, repo.getByIDErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("user not found", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		svc := newConfiguredWebAuthnService(repo, newMockTokenStore())
+		if _, _, err := svc.BeginWebAuthnRegistration(context.Background(), uuidv7.MustBytes()); !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token, got %v", err)
+		}
+	})
+
+	t.Run("load credentials error", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com", IsActive: true}
+		repo.listCredsErr = errors.New("list creds failed")
+		svc := newConfiguredWebAuthnService(repo, newMockTokenStore())
+		if _, _, err := svc.BeginWebAuthnRegistration(context.Background(), userID); !errors.Is(err, repo.listCredsErr) {
+			t.Fatalf("expected list creds error, got %v", err)
+		}
+	})
+
+	t.Run("token store unavailable", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com", IsActive: true}
+		svc := newConfiguredWebAuthnService(repo, nil)
+		if _, _, err := svc.BeginWebAuthnRegistration(context.Background(), userID); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge, got %v", err)
+		}
+	})
+
+	t.Run("success with exclusions", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{
+			ID:        userID,
+			Email:     "user@example.com",
+			FirstName: "Web",
+			LastName:  "Authn",
+			IsActive:  true,
+		}
+
+		serialized, err := json.Marshal(webauthnlib.Credential{
+			ID:              []byte{8, 8, 8},
+			PublicKey:       []byte{1, 2, 3},
+			AttestationType: "none",
+		})
+		if err != nil {
+			t.Fatalf("marshal credential: %v", err)
+		}
+		repo.webauthnCredentials[string(userID)] = []auth.UserWebAuthnCredential{{
+			UserID:         userID,
+			CredentialID:   []byte{8, 8, 8},
+			CredentialJSON: serialized,
+		}}
+
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		creation, challengeToken, err := svc.BeginWebAuthnRegistration(context.Background(), userID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if creation == nil || strings.TrimSpace(challengeToken) == "" {
+			t.Fatalf("expected creation options and challenge token")
+		}
+		if len(creation.Response.CredentialExcludeList) != 1 {
+			t.Fatalf("expected one exclusion descriptor")
+		}
+	})
+}
+
+func TestAuthServiceFinishWebAuthnRegistrationBranches(t *testing.T) {
+	t.Run("invalid user id length", func(t *testing.T) {
+		svc := newConfiguredWebAuthnService(newMockAuthRepo(), newMockTokenStore())
+		err := svc.FinishWebAuthnRegistration(context.Background(), []byte("short"), "token", []byte("{}"), "name")
+		if !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token, got %v", err)
+		}
+	})
+
+	t.Run("not configured", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), newMockTokenStore(), nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		err := svc.FinishWebAuthnRegistration(context.Background(), uuidv7.MustBytes(), "token", []byte("{}"), "name")
+		if !errors.Is(err, ErrWebAuthnNotConfigured) {
+			t.Fatalf("expected not configured, got %v", err)
+		}
+	})
+
+	t.Run("invalid challenge", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com", IsActive: true}
+		svc := newConfiguredWebAuthnService(repo, newMockTokenStore())
+		err := svc.FinishWebAuthnRegistration(context.Background(), userID, "missing", []byte("{}"), "name")
+		if !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge, got %v", err)
+		}
+	})
+
+	t.Run("challenge user mismatch", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com", IsActive: true}
+		putWebAuthnChallengeToken(t, tokens, "tok1", webAuthnCeremonyRegistration, uuidv7.MustBytes(), time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		err := svc.FinishWebAuthnRegistration(context.Background(), userID, "tok1", []byte("{}"), "name")
+		if !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected challenge invalid, got %v", err)
+		}
+	})
+
+	t.Run("user fetch error", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		repo.getByIDErr = errors.New("db failed")
+		putWebAuthnChallengeToken(t, tokens, "tokfetch", webAuthnCeremonyRegistration, userID, time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		err := svc.FinishWebAuthnRegistration(context.Background(), userID, "tokfetch", []byte("{}"), "name")
+		if !errors.Is(err, repo.getByIDErr) {
+			t.Fatalf("expected user fetch error, got %v", err)
+		}
+	})
+
+	t.Run("user not found", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		putWebAuthnChallengeToken(t, tokens, "tok2", webAuthnCeremonyRegistration, userID, time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		err := svc.FinishWebAuthnRegistration(context.Background(), userID, "tok2", []byte("{}"), "name")
+		if !errors.Is(err, ErrInvalidToken) {
+			t.Fatalf("expected invalid token, got %v", err)
+		}
+	})
+
+	t.Run("load credentials error", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com", IsActive: true}
+		repo.listCredsErr = errors.New("list creds failed")
+		putWebAuthnChallengeToken(t, tokens, "tok3", webAuthnCeremonyRegistration, userID, time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		err := svc.FinishWebAuthnRegistration(context.Background(), userID, "tok3", []byte("{}"), "name")
+		if !errors.Is(err, repo.listCredsErr) {
+			t.Fatalf("expected list creds error, got %v", err)
+		}
+	})
+
+	t.Run("invalid payload", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com", IsActive: true}
+		putWebAuthnChallengeToken(t, tokens, "tok4", webAuthnCeremonyRegistration, userID, time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		err := svc.FinishWebAuthnRegistration(context.Background(), userID, "tok4", []byte("{}"), "name")
+		if !errors.Is(err, ErrWebAuthnPayloadInvalid) {
+			t.Fatalf("expected payload invalid, got %v", err)
+		}
+	})
+
+	t.Run("verification failed", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{
+			ID:        userID,
+			Email:     "user@example.com",
+			FirstName: "A",
+			LastName:  "B",
+			IsActive:  true,
+		}
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		_, challengeToken, err := svc.BeginWebAuthnRegistration(context.Background(), userID)
+		if err != nil {
+			t.Fatalf("begin registration: %v", err)
+		}
+		err = svc.FinishWebAuthnRegistration(context.Background(), userID, challengeToken, []byte(testCredentialCreationResponseJSON), "Device A")
+		if !errors.Is(err, ErrWebAuthnVerificationFailed) {
+			t.Fatalf("expected verification failed, got %v", err)
+		}
+	})
+
+	t.Run("success persists credential", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{
+			ID:        userID,
+			Email:     "user@example.com",
+			FirstName: "Web",
+			LastName:  "Authn",
+			IsActive:  true,
+		}
+
+		svc := NewAuthService(
+			repo,
+			newMockRoleRepo(),
+			tokens,
+			nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+				WebAuthnRPID:          "webauthn.io",
+				WebAuthnRPDisplayName: "Wucher Test",
+				WebAuthnRPOrigins:     []string{"https://webauthn.io"},
+				WebAuthnChallengeTTL:  2 * time.Minute,
+			}},
+		)
+
+		envelope := webAuthnChallengeEnvelope{
+			Ceremony: webAuthnCeremonyRegistration,
+			UserID:   append([]byte(nil), userID...),
+			Session: webauthnlib.SessionData{
+				Challenge:      "W8GzFU8pGjhoRbWrLDlamAfq_y4S1CZG1VuoeRLARrE",
+				RelyingPartyID: "webauthn.io",
+				UserID:         append([]byte(nil), userID...),
+				Expires:        time.Now().UTC().Add(time.Minute),
+				CredParams:     webauthnlib.CredentialParametersDefault(),
+			},
+		}
+		payload, err := json.Marshal(envelope)
+		if err != nil {
+			t.Fatalf("marshal envelope: %v", err)
+		}
+		tokens.store[webAuthnChallengeKey("toksuccess")] = payload
+
+		if err := svc.FinishWebAuthnRegistration(context.Background(), userID, "toksuccess", []byte(testCredentialCreationResponseJSON), "  Device A  "); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		records := repo.webauthnCredentials[string(userID)]
+		if len(records) != 1 {
+			t.Fatalf("expected one stored webauthn credential, got %d", len(records))
+		}
+		if records[0].Name != "Device A" {
+			t.Fatalf("expected trimmed credential name, got %q", records[0].Name)
+		}
+		if len(records[0].CredentialID) == 0 || len(records[0].CredentialJSON) == 0 {
+			t.Fatalf("expected persisted credential data")
+		}
+	})
+}
+
+func TestAuthServiceBeginWebAuthnLoginBranches(t *testing.T) {
+	t.Run("not configured", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), newMockTokenStore(), nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if _, _, err := svc.BeginWebAuthnLogin(context.Background(), "user@example.com"); !errors.Is(err, ErrWebAuthnNotConfigured) {
+			t.Fatalf("expected not configured, got %v", err)
+		}
+	})
+
+	t.Run("user fetch error", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		repo.getByMailErr = errors.New("db failed")
+		svc := newConfiguredWebAuthnService(repo, newMockTokenStore())
+		if _, _, err := svc.BeginWebAuthnLogin(context.Background(), "user@example.com"); !errors.Is(err, repo.getByMailErr) {
+			t.Fatalf("expected db error, got %v", err)
+		}
+	})
+
+	t.Run("user not found", func(t *testing.T) {
+		svc := newConfiguredWebAuthnService(newWebAuthnRepoWithErrors(), newMockTokenStore())
+		if _, _, err := svc.BeginWebAuthnLogin(context.Background(), "user@example.com"); !errors.Is(err, ErrInvalidCredentials) {
+			t.Fatalf("expected invalid credentials, got %v", err)
+		}
+	})
+
+	t.Run("email not verified", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		userID := uuidv7.MustBytes()
+		repo.usersByMail["user@example.com"] = &auth.User{ID: userID, Email: "user@example.com", IsActive: true}
+		svc := newConfiguredWebAuthnService(repo, newMockTokenStore())
+		if _, _, err := svc.BeginWebAuthnLogin(context.Background(), " user@example.com "); !errors.Is(err, ErrEmailNotVerified) {
+			t.Fatalf("expected email not verified, got %v", err)
+		}
+	})
+
+	t.Run("load credentials error", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		userID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		repo.usersByMail["user@example.com"] = &auth.User{ID: userID, Email: "user@example.com", EmailVerifiedAt: &now, IsActive: true}
+		repo.listCredsErr = errors.New("list creds failed")
+		svc := newConfiguredWebAuthnService(repo, newMockTokenStore())
+		if _, _, err := svc.BeginWebAuthnLogin(context.Background(), "user@example.com"); !errors.Is(err, repo.listCredsErr) {
+			t.Fatalf("expected list creds error, got %v", err)
+		}
+	})
+
+	t.Run("no credentials configured", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		userID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		repo.usersByMail["user@example.com"] = &auth.User{ID: userID, Email: "user@example.com", EmailVerifiedAt: &now, IsActive: true}
+		svc := newConfiguredWebAuthnService(repo, newMockTokenStore())
+		if _, _, err := svc.BeginWebAuthnLogin(context.Background(), "user@example.com"); !errors.Is(err, ErrWebAuthnCredentialUnavailable) {
+			t.Fatalf("expected credential unavailable, got %v", err)
+		}
+	})
+
+	t.Run("token store unavailable", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		userID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		repo.usersByMail["user@example.com"] = &auth.User{ID: userID, Email: "user@example.com", EmailVerifiedAt: &now, IsActive: true}
+		serialized, err := json.Marshal(webauthnlib.Credential{ID: []byte{1, 2, 3}, PublicKey: []byte{4}})
+		if err != nil {
+			t.Fatalf("marshal credential: %v", err)
+		}
+		repo.webauthnCredentials[string(userID)] = []auth.UserWebAuthnCredential{{
+			UserID:         userID,
+			CredentialID:   []byte{1, 2, 3},
+			CredentialJSON: serialized,
+		}}
+		svc := newConfiguredWebAuthnService(repo, nil)
+		if _, _, err := svc.BeginWebAuthnLogin(context.Background(), "user@example.com"); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge, got %v", err)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		repo.usersByMail["user@example.com"] = &auth.User{
+			ID:              userID,
+			Email:           "user@example.com",
+			EmailVerifiedAt: &now,
+			FirstName:       "Web",
+			LastName:        "User",
+			IsActive:        true,
+		}
+		serialized, err := json.Marshal(webauthnlib.Credential{
+			ID:              []byte{1, 2, 3},
+			PublicKey:       []byte{4, 5, 6},
+			AttestationType: "none",
+		})
+		if err != nil {
+			t.Fatalf("marshal credential: %v", err)
+		}
+		repo.webauthnCredentials[string(userID)] = []auth.UserWebAuthnCredential{{
+			UserID:         userID,
+			CredentialID:   []byte{1, 2, 3},
+			CredentialJSON: serialized,
+		}}
+
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		assertion, token, err := svc.BeginWebAuthnLogin(context.Background(), " user@example.com ")
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if assertion == nil || strings.TrimSpace(token) == "" {
+			t.Fatalf("expected assertion and challenge token")
+		}
+		if len(assertion.Response.AllowedCredentials) != 1 {
+			t.Fatalf("expected allowed credential list")
+		}
+	})
+}
+
+func TestAuthServiceFinishWebAuthnLoginBranches(t *testing.T) {
+	t.Run("not configured", func(t *testing.T) {
+		svc := NewAuthService(newMockAuthRepo(), newMockRoleRepo(), newMockTokenStore(), nil, AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		if _, err := svc.FinishWebAuthnLogin(context.Background(), "token", []byte("{}")); !errors.Is(err, ErrWebAuthnNotConfigured) {
+			t.Fatalf("expected not configured, got %v", err)
+		}
+	})
+
+	t.Run("invalid challenge", func(t *testing.T) {
+		svc := newConfiguredWebAuthnService(newWebAuthnRepoWithErrors(), newMockTokenStore())
+		if _, err := svc.FinishWebAuthnLogin(context.Background(), "missing", []byte("{}")); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge, got %v", err)
+		}
+	})
+
+	t.Run("challenge invalid user id length", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		putWebAuthnChallengeToken(t, tokens, "baduid", webAuthnCeremonyLogin, []byte("short"), time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		if _, err := svc.FinishWebAuthnLogin(context.Background(), "baduid", []byte("{}")); !errors.Is(err, ErrWebAuthnChallengeInvalid) {
+			t.Fatalf("expected invalid challenge, got %v", err)
+		}
+	})
+
+	t.Run("user fetch error", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		repo.getByIDErr = errors.New("db failed")
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		putWebAuthnChallengeToken(t, tokens, "tok1", webAuthnCeremonyLogin, userID, time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		if _, err := svc.FinishWebAuthnLogin(context.Background(), "tok1", []byte("{}")); !errors.Is(err, repo.getByIDErr) {
+			t.Fatalf("expected db error, got %v", err)
+		}
+	})
+
+	t.Run("user not found", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		putWebAuthnChallengeToken(t, tokens, "tok2", webAuthnCeremonyLogin, userID, time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		if _, err := svc.FinishWebAuthnLogin(context.Background(), "tok2", []byte("{}")); !errors.Is(err, ErrInvalidCredentials) {
+			t.Fatalf("expected invalid credentials, got %v", err)
+		}
+	})
+
+	t.Run("load credentials error", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		repo.listCredsErr = errors.New("list creds failed")
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com", IsActive: true}
+		putWebAuthnChallengeToken(t, tokens, "tok3", webAuthnCeremonyLogin, userID, time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		if _, err := svc.FinishWebAuthnLogin(context.Background(), "tok3", []byte("{}")); !errors.Is(err, repo.listCredsErr) {
+			t.Fatalf("expected list creds error, got %v", err)
+		}
+	})
+
+	t.Run("no credentials", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com", IsActive: true}
+		putWebAuthnChallengeToken(t, tokens, "tok4", webAuthnCeremonyLogin, userID, time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		if _, err := svc.FinishWebAuthnLogin(context.Background(), "tok4", []byte("{}")); !errors.Is(err, ErrWebAuthnCredentialUnavailable) {
+			t.Fatalf("expected credential unavailable, got %v", err)
+		}
+	})
+
+	t.Run("invalid payload", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, Email: "user@example.com", IsActive: true}
+		serialized, err := json.Marshal(webauthnlib.Credential{ID: []byte{1}, PublicKey: []byte{2}})
+		if err != nil {
+			t.Fatalf("marshal credential: %v", err)
+		}
+		repo.webauthnCredentials[string(userID)] = []auth.UserWebAuthnCredential{{
+			UserID:         userID,
+			CredentialID:   []byte{1},
+			CredentialJSON: serialized,
+		}}
+		putWebAuthnChallengeToken(t, tokens, "tok5", webAuthnCeremonyLogin, userID, time.Now().UTC().Add(time.Minute))
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		if _, err := svc.FinishWebAuthnLogin(context.Background(), "tok5", []byte("{}")); !errors.Is(err, ErrWebAuthnPayloadInvalid) {
+			t.Fatalf("expected payload invalid, got %v", err)
+		}
+	})
+
+	t.Run("verification failed", func(t *testing.T) {
+		repo := newWebAuthnRepoWithErrors()
+		tokens := newMockTokenStore()
+		userID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		user := &auth.User{
+			ID:              userID,
+			Email:           "user@example.com",
+			EmailVerifiedAt: &now,
+			FirstName:       "Web",
+			LastName:        "User",
+			IsActive:        true,
+		}
+		repo.usersByMail["user@example.com"] = user
+		repo.users[string(userID)] = user
+		serialized, err := json.Marshal(webauthnlib.Credential{
+			ID:              []byte{1, 2, 3},
+			PublicKey:       []byte{4, 5, 6},
+			AttestationType: "none",
+		})
+		if err != nil {
+			t.Fatalf("marshal credential: %v", err)
+		}
+		repo.webauthnCredentials[string(userID)] = []auth.UserWebAuthnCredential{{
+			UserID:         userID,
+			CredentialID:   []byte{1, 2, 3},
+			CredentialJSON: serialized,
+		}}
+
+		svc := newConfiguredWebAuthnService(repo, tokens)
+		_, challengeToken, err := svc.BeginWebAuthnLogin(context.Background(), "user@example.com")
+		if err != nil {
+			t.Fatalf("begin login: %v", err)
+		}
+		if _, err := svc.FinishWebAuthnLogin(context.Background(), challengeToken, []byte(testCredentialAssertionResponseJSON)); !errors.Is(err, ErrWebAuthnVerificationFailed) {
+			t.Fatalf("expected verification failed, got %v", err)
+		}
+	})
+}
diff --git a/internal/service/base_service.go b/internal/service/base_service.go
new file mode 100644
index 0000000..4d9fa18
--- /dev/null
+++ b/internal/service/base_service.go
@@ -0,0 +1,151 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"wucher/internal/domain/base"
+	"wucher/internal/shared/pkg/appctx"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type BaseService struct {
+	repo base.Repository
+}
+
+func NewBaseService(repo base.Repository) *BaseService {
+	return &BaseService{repo: repo}
+}
+
+var errInvalidBaseCategoryType = errors.New("invalid base category type")
+
+func (s *BaseService) CreateBase(ctx context.Context, row *base.Base, categoryType string) error {
+	category, ok := base.NormalizeCategoryType(categoryType)
+	if !ok {
+		return errInvalidBaseCategoryType
+	}
+	if err := validateBaseCoordinates(row); err != nil {
+		return err
+	}
+	row.DefaultStartTimeType = normalizeBaseShiftTimeType(row.DefaultStartTimeType)
+	row.DefaultEndTimeType = normalizeBaseShiftTimeType(row.DefaultEndTimeType)
+	if row.DefaultStartTimeType == base.ShiftTimeTypeFixed && strings.TrimSpace(row.DefaultShiftStart) == "" {
+		return errors.New("default_shift_start is required")
+	}
+	if row.DefaultEndTimeType == base.ShiftTimeTypeFixed && strings.TrimSpace(row.DefaultShiftEnd) == "" {
+		return errors.New("default_shift_end is required")
+	}
+	return s.repo.CreateBase(ctx, row, category)
+}
+
+func (s *BaseService) UpdateBase(ctx context.Context, row *base.Base, categoryType string) error {
+	category, ok := base.NormalizeCategoryType(categoryType)
+	if !ok {
+		return errInvalidBaseCategoryType
+	}
+	if err := validateBaseCoordinates(row); err != nil {
+		return err
+	}
+	row.DefaultStartTimeType = normalizeBaseShiftTimeType(row.DefaultStartTimeType)
+	row.DefaultEndTimeType = normalizeBaseShiftTimeType(row.DefaultEndTimeType)
+	if row.DefaultStartTimeType == base.ShiftTimeTypeFixed && strings.TrimSpace(row.DefaultShiftStart) == "" {
+		return errors.New("default_shift_start is required")
+	}
+	if row.DefaultEndTimeType == base.ShiftTimeTypeFixed && strings.TrimSpace(row.DefaultShiftEnd) == "" {
+		return errors.New("default_shift_end is required")
+	}
+	return s.repo.UpdateBase(ctx, row, category)
+}
+
+func (s *BaseService) DeleteBase(ctx context.Context, id []byte, categoryType string) (*base.Base, error) {
+	category, ok := base.NormalizeCategoryType(categoryType)
+	if !ok {
+		return nil, errInvalidBaseCategoryType
+	}
+
+	// fetch existing row before deleting so we can return a copy
+	row, err := s.repo.GetBaseByID(ctx, id, category)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := s.repo.DeleteBase(ctx, id, category); err != nil {
+		return nil, err
+	}
+
+	// if we had a row, populate DeletedAt/DeletedBy to reflect the repository update
+	if row != nil {
+		now := time.Now().UTC()
+		row.DeletedAt = &now
+		// try to pick actor from context if available
+		if actor := appctx.GetUserID(ctx); len(actor) > 0 {
+			row.DeletedBy = make([]byte, len(actor))
+			copy(row.DeletedBy, actor)
+		}
+	}
+
+	return row, nil
+}
+
+func (s *BaseService) GetBaseByID(ctx context.Context, id []byte, categoryType string) (*base.Base, error) {
+	category, ok := base.NormalizeCategoryType(categoryType)
+	if !ok {
+		return nil, errInvalidBaseCategoryType
+	}
+	return s.repo.GetBaseByID(ctx, id, category)
+}
+
+func (s *BaseService) ListBases(ctx context.Context, filter, sort string, limit, offset int, categoryType string, dul *bool) ([]base.Base, int64, error) {
+	if strings.TrimSpace(categoryType) == "" {
+		return s.repo.ListBases(ctx, filter, normalizeBaseSort(sort), limit, offset, "", dul)
+	}
+	category, ok := base.NormalizeCategoryType(categoryType)
+	if !ok {
+		return nil, 0, errInvalidBaseCategoryType
+	}
+	return s.repo.ListBases(ctx, filter, normalizeBaseSort(sort), limit, offset, category, dul)
+}
+
+func normalizeBaseSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "base", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "base", true)),
+			"sortkey",
+		),
+		sortField("base"),
+		sortField("base_abbreviation"),
+		sortField("notes", "note", "notes"),
+		sortField("is_active"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
+
+func validateBaseCoordinates(row *base.Base) error {
+	if row == nil {
+		return nil
+	}
+	if row.Latitude < -90 || row.Latitude > 90 {
+		return errors.New("latitude must be between -90 and 90")
+	}
+	if row.Longitude < -180 || row.Longitude > 180 {
+		return errors.New("longitude must be between -180 and 180")
+	}
+	return nil
+}
+
+func normalizeBaseShiftTimeType(raw string) string {
+	switch strings.ToUpper(strings.TrimSpace(raw)) {
+	case "", base.ShiftTimeTypeFixed:
+		return base.ShiftTimeTypeFixed
+	case base.ShiftTimeTypeBMCT:
+		return base.ShiftTimeTypeBMCT
+	case base.ShiftTimeTypeECET:
+		return base.ShiftTimeTypeECET
+	default:
+		return strings.ToUpper(strings.TrimSpace(raw))
+	}
+}
diff --git a/internal/service/base_service_test.go b/internal/service/base_service_test.go
new file mode 100644
index 0000000..4274394
--- /dev/null
+++ b/internal/service/base_service_test.go
@@ -0,0 +1,278 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/base"
+)
+
+type baseRepoMock struct {
+	createBaseCalled  bool
+	updateBaseCalled  bool
+	deleteBaseCalled  bool
+	getBaseByIDCalled bool
+	listBasesCalled   bool
+
+	lastCreateBase     *base.Base
+	lastCreateCategory string
+	lastUpdateBase     *base.Base
+	lastUpdateCategory string
+	lastDeleteBaseID   []byte
+	lastDeleteCategory string
+	lastGetBaseByIDID  []byte
+	lastGetCategory    string
+	lastListFilter     string
+	lastListSort       string
+	lastListLimit      int
+	lastListOffset     int
+	lastListCategory   string
+	lastListDUL        *bool
+
+	getBaseByIDResult *base.Base
+	listBasesResult   []base.Base
+	listBasesTotal    int64
+
+	createBaseErr  error
+	updateBaseErr  error
+	deleteBaseErr  error
+	getBaseByIDErr error
+	listBasesErr   error
+}
+
+func (m *baseRepoMock) CreateBase(_ context.Context, row *base.Base, categoryType string) error {
+	m.createBaseCalled = true
+	m.lastCreateBase = row
+	m.lastCreateCategory = categoryType
+	return m.createBaseErr
+}
+
+func (m *baseRepoMock) UpdateBase(_ context.Context, row *base.Base, categoryType string) error {
+	m.updateBaseCalled = true
+	m.lastUpdateBase = row
+	m.lastUpdateCategory = categoryType
+	return m.updateBaseErr
+}
+
+func (m *baseRepoMock) DeleteBase(_ context.Context, id []byte, categoryType string) error {
+	m.deleteBaseCalled = true
+	m.lastDeleteBaseID = id
+	m.lastDeleteCategory = categoryType
+	return m.deleteBaseErr
+}
+
+func (m *baseRepoMock) GetBaseByID(_ context.Context, id []byte, categoryType string) (*base.Base, error) {
+	m.getBaseByIDCalled = true
+	m.lastGetBaseByIDID = id
+	m.lastGetCategory = categoryType
+	return m.getBaseByIDResult, m.getBaseByIDErr
+}
+
+func (m *baseRepoMock) ListBases(_ context.Context, filter, sort string, limit, offset int, categoryType string, dul *bool) ([]base.Base, int64, error) {
+	m.listBasesCalled = true
+	m.lastListFilter = filter
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	m.lastListCategory = categoryType
+	m.lastListDUL = dul
+	return m.listBasesResult, m.listBasesTotal, m.listBasesErr
+}
+
+func TestNewBaseService(t *testing.T) {
+	repo := &baseRepoMock{}
+	svc := NewBaseService(repo)
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service and repo initialized")
+	}
+}
+
+func TestBaseServiceCreateBase(t *testing.T) {
+	repo := &baseRepoMock{}
+	svc := NewBaseService(repo)
+	row := &base.Base{BaseName: "Jakarta", DefaultShiftStart: "06:00:00", DefaultShiftEnd: "21:00:00"}
+
+	if err := svc.CreateBase(context.Background(), row, "regular"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.createBaseCalled || repo.lastCreateBase != row || repo.lastCreateCategory != base.CategoryKeyRegular {
+		t.Fatalf("expected CreateBase forwarded with regular category")
+	}
+
+	if err := svc.CreateBase(context.Background(), row, "hems"); err != nil {
+		t.Fatalf("unexpected hems error: %v", err)
+	}
+	if repo.lastCreateCategory != base.CategoryKeyHEMS {
+		t.Fatalf("expected hems category forwarded")
+	}
+
+	repo.createBaseErr = errors.New("create base failed")
+	if err := svc.CreateBase(context.Background(), row, "regular"); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+
+	if err := svc.CreateBase(context.Background(), row, "invalid"); err == nil {
+		t.Fatalf("expected invalid category error")
+	}
+}
+
+func TestBaseServiceUpdateBase(t *testing.T) {
+	repo := &baseRepoMock{}
+	svc := NewBaseService(repo)
+	row := &base.Base{BaseName: "Bandung", DefaultShiftStart: "06:00:00", DefaultShiftEnd: "21:00:00"}
+
+	if err := svc.UpdateBase(context.Background(), row, "regular"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateBaseCalled || repo.lastUpdateBase != row || repo.lastUpdateCategory != base.CategoryKeyRegular {
+		t.Fatalf("expected UpdateBase forwarded")
+	}
+
+	repo.updateBaseErr = errors.New("update base failed")
+	if err := svc.UpdateBase(context.Background(), row, "regular"); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+
+	if err := svc.UpdateBase(context.Background(), row, "x"); err == nil {
+		t.Fatalf("expected invalid category error")
+	}
+}
+
+func TestBaseServiceDeleteBase(t *testing.T) {
+	repo := &baseRepoMock{}
+	svc := NewBaseService(repo)
+	id := []byte("base-id")
+
+	deleted, err := svc.DeleteBase(context.Background(), id, "hems")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if deleted != nil {
+		t.Fatalf("expected deleted result to be nil when repo returns nil")
+	}
+	if !repo.deleteBaseCalled || string(repo.lastDeleteBaseID) != string(id) || repo.lastDeleteCategory != base.CategoryKeyHEMS {
+		t.Fatalf("expected DeleteBase forwarded")
+	}
+
+	repo.deleteBaseErr = errors.New("delete base failed")
+	if _, err := svc.DeleteBase(context.Background(), id, "hems"); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+
+	if _, err := svc.DeleteBase(context.Background(), id, "unknown"); err == nil {
+		t.Fatalf("expected invalid category error")
+	}
+}
+
+func TestBaseServiceGetBaseByID(t *testing.T) {
+	expected := &base.Base{BaseName: "Surabaya"}
+	repo := &baseRepoMock{getBaseByIDResult: expected}
+	svc := NewBaseService(repo)
+	id := []byte("base-id")
+
+	got, err := svc.GetBaseByID(context.Background(), id, "hems")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != expected {
+		t.Fatalf("unexpected result")
+	}
+	if !repo.getBaseByIDCalled || string(repo.lastGetBaseByIDID) != string(id) || repo.lastGetCategory != base.CategoryKeyHEMS {
+		t.Fatalf("expected GetBaseByID forwarded")
+	}
+
+	repo.getBaseByIDErr = errors.New("get base failed")
+	if _, err := svc.GetBaseByID(context.Background(), id, "regular"); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+
+	if _, err := svc.GetBaseByID(context.Background(), id, "invalid"); err == nil {
+		t.Fatalf("expected invalid category error")
+	}
+}
+
+func TestBaseServiceListBases(t *testing.T) {
+	repo := &baseRepoMock{
+		listBasesResult: []base.Base{{BaseName: "Bali"}},
+		listBasesTotal:  1,
+	}
+	svc := NewBaseService(repo)
+
+	rows, total, err := svc.ListBases(context.Background(), "find", "-base", 10, 20, "regular", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if !repo.listBasesCalled {
+		t.Fatalf("expected ListBases forwarded to repo")
+	}
+	if repo.lastListFilter != "find" || repo.lastListSort != "base DESC" || repo.lastListLimit != 10 || repo.lastListOffset != 20 || repo.lastListCategory != base.CategoryKeyRegular {
+		t.Fatalf("unexpected list args forwarded")
+	}
+
+	rows, total, err = svc.ListBases(context.Background(), "find", "sortkey", 10, 20, "regular", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, base ASC" {
+		t.Fatalf("unexpected sortkey args forwarded: %q", repo.lastListSort)
+	}
+
+	repo.listBasesErr = errors.New("list bases failed")
+	if _, _, err := svc.ListBases(context.Background(), "", "unknown", 1, 0, "hems", nil); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+	if repo.lastListSort != "" {
+		t.Fatalf("expected unknown sort normalized to empty")
+	}
+	if repo.lastListCategory != base.CategoryKeyHEMS {
+		t.Fatalf("expected hems category forwarded")
+	}
+
+	if _, _, err := svc.ListBases(context.Background(), "", "base", 1, 0, "invalid", nil); err == nil {
+		t.Fatalf("expected invalid category error")
+	}
+
+	repo.listBasesErr = nil
+	if _, _, err := svc.ListBases(context.Background(), "", "base", 1, 0, "", nil); err != nil {
+		t.Fatalf("expected empty category to list all, got err=%v", err)
+	}
+	if repo.lastListCategory != "" {
+		t.Fatalf("expected empty category forwarded for unfiltered list, got %q", repo.lastListCategory)
+	}
+}
+
+func TestNormalizeBaseSort(t *testing.T) {
+	cases := map[string]string{
+		"sortkey":            "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, base ASC",
+		"-sortkey":           "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, base ASC",
+		"base":               "base ASC",
+		"-base":              "base DESC",
+		"base_abbreviation":  "base_abbreviation ASC",
+		"-base_abbreviation": "base_abbreviation DESC",
+		"note":               "notes ASC",
+		"-note":              "notes DESC",
+		"notes":              "notes ASC",
+		"-notes":             "notes DESC",
+		"is_active":          "is_active ASC",
+		"-is_active":         "is_active DESC",
+		"created_at":         "created_at ASC",
+		"-created_at":        "created_at DESC",
+		"updated_at":         "updated_at ASC",
+		"-updated_at":        "updated_at DESC",
+		"unknown":            "",
+		"":                   "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeBaseSort(in); got != want {
+			t.Fatalf("normalizeBaseSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/base_write_service.go b/internal/service/base_write_service.go
new file mode 100644
index 0000000..8cddebc
--- /dev/null
+++ b/internal/service/base_write_service.go
@@ -0,0 +1,416 @@
+package service
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"time"
+
+	"wucher/internal/domain/base"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type BaseWriteError struct {
+	Status  int
+	Title   string
+	Detail  string
+	Pointer string
+}
+
+func (e *BaseWriteError) Error() string {
+	if e == nil {
+		return ""
+	}
+	return e.Detail
+}
+
+type BaseWriteResult struct {
+	Row                      *base.Base
+	CategoryType             string
+	PreviousFotoAttachmentID []byte
+}
+
+type BaseOperationalShiftTimeInput struct {
+	DateStart     time.Time
+	DateEnd       time.Time
+	StartTimeType string
+	EndTimeType   string
+	ShiftStart    *time.Time
+	ShiftEnd      *time.Time
+}
+
+type BaseCreateInput struct {
+	ID                                 []byte
+	CategoryType                       string
+	BaseName                           string
+	BaseAbbreviation                   string
+	Address                            string
+	Latitude                           float64
+	Longitude                          float64
+	LandlineNumber                     string
+	MobileNumber                       string
+	Email                              string
+	SortKey                            *int
+	SMSAlert                           bool
+	Checklist                          bool
+	LegTime                            string
+	DefaultStartTimeType               string
+	DefaultEndTimeType                 string
+	DefaultShiftStart                  *time.Time
+	DefaultShiftEnd                    *time.Time
+	UTC                                string
+	Dry                                bool
+	ControlCenter                      bool
+	DUL                                bool
+	Notes                              string
+	HEMSEDCContactIDs          [][]byte
+	MedPaxContactIDs           [][]byte
+	ResponsiblePilotContactIDs [][]byte
+	OperationalShiftTimes              []BaseOperationalShiftTimeInput
+	IsActive                           bool
+	CreatedBy                          []byte
+	UpdatedBy                          []byte
+	FotoAttachmentID                   []byte
+}
+
+type BaseUpdateInput struct {
+	ID                                    []byte
+	CategoryType                          string
+	BaseName                              *string
+	BaseAbbreviation                      *string
+	Address                               *string
+	Latitude                              *float64
+	Longitude                             *float64
+	LandlineNumber                        *string
+	MobileNumber                          *string
+	Email                                 *string
+	SortKeySet                            bool
+	SortKeyValid                          bool
+	SortKeyValue                          *int
+	SMSAlert                              *bool
+	Checklist                             *bool
+	LegTime                               *string
+	DefaultStartTimeType                  *string
+	DefaultEndTimeType                    *string
+	DefaultShiftStart                     *time.Time
+	DefaultShiftEnd                       *time.Time
+	UTC                                   *string
+	Dry                                   *bool
+	ControlCenter                         *bool
+	DUL                                   *bool
+	Notes                                 *string
+	HEMSEDCContactIDs      [][]byte
+	HEMSEDCContactIDsSet   bool
+	MedPaxContactIDs       [][]byte
+	MedPaxContactIDsSet    bool
+	ResponsiblePilotContactIDs            [][]byte
+	ResponsiblePilotContactIDsSet         bool
+	OperationalShiftTimes                 []BaseOperationalShiftTimeInput
+	OperationalShiftTimesSet              bool
+	IsActive                              *bool
+	CreatedBy                             []byte
+	CreatedBySet                          bool
+	UpdatedBy                             []byte
+	UpdatedBySet                          bool
+	FotoAttachmentID                      []byte
+	FotoAttachmentSet                     bool
+}
+
+func (s *BaseService) CreateDetailed(ctx context.Context, in BaseCreateInput) (*BaseWriteResult, error) {
+	if s == nil || s.repo == nil {
+		return nil, &BaseWriteError{Status: http.StatusInternalServerError, Title: "Create failed", Detail: "base service is not configured"}
+	}
+	category, ok := base.NormalizeCategoryType(in.CategoryType)
+	if !ok {
+		return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "invalid base category type", Pointer: "/data/attributes/base_category"}
+	}
+	baseName := strings.TrimSpace(in.BaseName)
+	if baseName == "" {
+		return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "base is required", Pointer: "/data/attributes/base"}
+	}
+	if in.Latitude < -90 || in.Latitude > 90 {
+		return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "latitude must be between -90 and 90", Pointer: "/data/attributes/latitude"}
+	}
+	if in.Longitude < -180 || in.Longitude > 180 {
+		return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "longitude must be between -180 and 180", Pointer: "/data/attributes/longitude"}
+	}
+	defaultStartTimeType := normalizeShiftTimeType(in.DefaultStartTimeType)
+	defaultEndTimeType := normalizeShiftTimeType(in.DefaultEndTimeType)
+	if defaultStartTimeType == base.ShiftTimeTypeFixed && in.DefaultShiftStart == nil {
+		return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "default_shift_start is required", Pointer: "/data/attributes/default_shift_start"}
+	}
+	if defaultEndTimeType == base.ShiftTimeTypeFixed && in.DefaultShiftEnd == nil {
+		return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "default_shift_end is required", Pointer: "/data/attributes/default_shift_end"}
+	}
+
+	row := &base.Base{
+		ID:                                 append([]byte(nil), in.ID...),
+		BaseName:                           baseName,
+		BaseAbbreviation:                   strings.TrimSpace(in.BaseAbbreviation),
+		Address:                            strings.TrimSpace(in.Address),
+		Latitude:                           in.Latitude,
+		Longitude:                          in.Longitude,
+		LandlineNumber:                     strings.TrimSpace(in.LandlineNumber),
+		MobileNumber:                       strings.TrimSpace(in.MobileNumber),
+		Email:                              strings.TrimSpace(in.Email),
+		SortKey:                            cloneIntPtr(in.SortKey),
+		SMSAlert:                           in.SMSAlert,
+		Checklist:                          in.Checklist,
+		LegTime:                            strings.TrimSpace(in.LegTime),
+		DefaultStartTimeType:               defaultStartTimeType,
+		DefaultEndTimeType:                 defaultEndTimeType,
+		DefaultShiftStart:                  timePtrToClockString(in.DefaultShiftStart),
+		DefaultShiftEnd:                    timePtrToClockString(in.DefaultShiftEnd),
+		UTC:                                normalizeUTCString(in.UTC),
+		Dry:                                in.Dry,
+		ControlCenter:                      in.ControlCenter,
+		DUL:                                in.DUL,
+		Notes:                              strings.TrimSpace(in.Notes),
+		IsActive:                           in.IsActive,
+		HEMSEDCContactIDs: appendUniqueIDs(in.HEMSEDCContactIDs),
+		MedPaxContactIDs:  appendUniqueIDs(in.MedPaxContactIDs),
+		ResponsiblePilotContactIDs:         appendUniqueIDs(in.ResponsiblePilotContactIDs),
+		OperationalShiftTimes:              cloneOperationalShiftTimeInputs(in.OperationalShiftTimes),
+		CreatedBy:                          append([]byte(nil), in.CreatedBy...),
+		UpdatedBy:                          append([]byte(nil), in.UpdatedBy...),
+		FotoAttachmentID:                   append([]byte(nil), in.FotoAttachmentID...),
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	if err := s.CreateBase(ctx, row, category); err != nil {
+		return nil, &BaseWriteError{Status: http.StatusBadRequest, Title: "Create failed", Detail: err.Error()}
+	}
+	created, err := s.GetBaseByID(ctx, row.ID, category)
+	if err != nil {
+		return nil, &BaseWriteError{Status: http.StatusBadRequest, Title: "Create failed", Detail: err.Error()}
+	}
+	if created == nil {
+		created = row
+	}
+	return &BaseWriteResult{Row: created, CategoryType: category}, nil
+}
+
+func (s *BaseService) UpdateDetailed(ctx context.Context, in BaseUpdateInput) (*BaseWriteResult, error) {
+	if s == nil || s.repo == nil {
+		return nil, &BaseWriteError{Status: http.StatusInternalServerError, Title: "Update failed", Detail: "base service is not configured"}
+	}
+	category, ok := base.NormalizeCategoryType(in.CategoryType)
+	if !ok {
+		return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "invalid base category type", Pointer: "/data/attributes/base_category"}
+	}
+	if len(in.ID) != 16 {
+		return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "uuid is invalid UUID", Pointer: "/path/uuid"}
+	}
+
+	existing, err := s.GetBaseByID(ctx, in.ID, category)
+	if err != nil {
+		return nil, &BaseWriteError{Status: http.StatusNotFound, Title: "Not found", Detail: categoryNotFoundDetail(category)}
+	}
+	if existing == nil {
+		return nil, &BaseWriteError{Status: http.StatusNotFound, Title: "Not found", Detail: categoryNotFoundDetail(category)}
+	}
+	prevFotoAttachmentID := append([]byte(nil), existing.FotoAttachmentID...)
+	if in.Latitude != nil && (*in.Latitude < -90 || *in.Latitude > 90) {
+		return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "latitude must be between -90 and 90", Pointer: "/data/attributes/latitude"}
+	}
+	if in.Longitude != nil && (*in.Longitude < -180 || *in.Longitude > 180) {
+		return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "longitude must be between -180 and 180", Pointer: "/data/attributes/longitude"}
+	}
+
+	if in.BaseName != nil {
+		v := strings.TrimSpace(*in.BaseName)
+		if v == "" {
+			return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "base cannot be empty", Pointer: "/data/attributes/base"}
+		}
+		existing.BaseName = v
+	}
+	if in.BaseAbbreviation != nil {
+		existing.BaseAbbreviation = strings.TrimSpace(*in.BaseAbbreviation)
+	}
+	if in.Address != nil {
+		existing.Address = strings.TrimSpace(*in.Address)
+	}
+	if in.Latitude != nil {
+		existing.Latitude = *in.Latitude
+	}
+	if in.Longitude != nil {
+		existing.Longitude = *in.Longitude
+	}
+	if in.LandlineNumber != nil {
+		existing.LandlineNumber = strings.TrimSpace(*in.LandlineNumber)
+	}
+	if in.MobileNumber != nil {
+		existing.MobileNumber = strings.TrimSpace(*in.MobileNumber)
+	}
+	if in.Email != nil {
+		existing.Email = strings.TrimSpace(*in.Email)
+	}
+	if in.SortKeySet {
+		if in.SortKeyValid {
+			existing.SortKey = cloneIntPtr(in.SortKeyValue)
+		} else {
+			existing.SortKey = nil
+		}
+	}
+	if in.SMSAlert != nil {
+		existing.SMSAlert = *in.SMSAlert
+	}
+	if in.Checklist != nil {
+		existing.Checklist = *in.Checklist
+	}
+	if in.LegTime != nil {
+		existing.LegTime = strings.TrimSpace(*in.LegTime)
+	}
+	if in.DefaultStartTimeType != nil {
+		existing.DefaultStartTimeType = normalizeShiftTimeType(*in.DefaultStartTimeType)
+	}
+	if in.DefaultEndTimeType != nil {
+		existing.DefaultEndTimeType = normalizeShiftTimeType(*in.DefaultEndTimeType)
+	}
+	if in.DefaultShiftStart != nil {
+		existing.DefaultShiftStart = timePtrToClockString(in.DefaultShiftStart)
+	}
+	if in.DefaultShiftEnd != nil {
+		existing.DefaultShiftEnd = timePtrToClockString(in.DefaultShiftEnd)
+	}
+	if normalizeShiftTimeType(existing.DefaultStartTimeType) != base.ShiftTimeTypeFixed {
+		existing.DefaultShiftStart = ""
+	}
+	if normalizeShiftTimeType(existing.DefaultEndTimeType) != base.ShiftTimeTypeFixed {
+		existing.DefaultShiftEnd = ""
+	}
+	if normalizeShiftTimeType(existing.DefaultStartTimeType) == base.ShiftTimeTypeFixed && strings.TrimSpace(existing.DefaultShiftStart) == "" {
+		return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "default_shift_start is required", Pointer: "/data/attributes/default_shift_start"}
+	}
+	if normalizeShiftTimeType(existing.DefaultEndTimeType) == base.ShiftTimeTypeFixed && strings.TrimSpace(existing.DefaultShiftEnd) == "" {
+		return nil, &BaseWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "default_shift_end is required", Pointer: "/data/attributes/default_shift_end"}
+	}
+	if in.UTC != nil {
+		existing.UTC = normalizeUTCString(*in.UTC)
+	}
+	if in.Dry != nil {
+		existing.Dry = *in.Dry
+	}
+	if in.ControlCenter != nil {
+		existing.ControlCenter = *in.ControlCenter
+	}
+	if in.DUL != nil {
+		existing.DUL = *in.DUL
+	}
+	if in.Notes != nil {
+		existing.Notes = strings.TrimSpace(*in.Notes)
+	}
+	if in.HEMSEDCContactIDsSet {
+		existing.HEMSEDCContactIDs = appendUniqueIDs(in.HEMSEDCContactIDs)
+	}
+	if in.MedPaxContactIDsSet {
+		existing.MedPaxContactIDs = appendUniqueIDs(in.MedPaxContactIDs)
+	}
+	if in.ResponsiblePilotContactIDsSet {
+		existing.ResponsiblePilotContactIDs = appendUniqueIDs(in.ResponsiblePilotContactIDs)
+	}
+	if in.OperationalShiftTimesSet {
+		existing.OperationalShiftTimes = cloneOperationalShiftTimeInputs(in.OperationalShiftTimes)
+		if existing.OperationalShiftTimes == nil {
+			existing.OperationalShiftTimes = []base.BaseOperationalShiftTime{}
+		}
+	} else {
+		existing.OperationalShiftTimes = nil
+	}
+	if in.CreatedBySet {
+		existing.CreatedBy = append([]byte(nil), in.CreatedBy...)
+	}
+	if in.UpdatedBySet {
+		existing.UpdatedBy = append([]byte(nil), in.UpdatedBy...)
+	}
+	if in.FotoAttachmentSet {
+		existing.FotoAttachmentID = append([]byte(nil), in.FotoAttachmentID...)
+	}
+	if in.IsActive != nil {
+		existing.IsActive = *in.IsActive
+	}
+
+	if err := s.UpdateBase(ctx, existing, category); err != nil {
+		return nil, &BaseWriteError{Status: http.StatusBadRequest, Title: "Update failed", Detail: err.Error()}
+	}
+	updated, err := s.GetBaseByID(ctx, existing.ID, category)
+	if err != nil {
+		return nil, &BaseWriteError{Status: http.StatusBadRequest, Title: "Update failed", Detail: err.Error()}
+	}
+	if updated == nil {
+		updated = existing
+	}
+	return &BaseWriteResult{Row: updated, CategoryType: category, PreviousFotoAttachmentID: prevFotoAttachmentID}, nil
+}
+
+func cloneOperationalShiftTimeInputs(items []BaseOperationalShiftTimeInput) []base.BaseOperationalShiftTime {
+	if len(items) == 0 {
+		return nil
+	}
+	out := make([]base.BaseOperationalShiftTime, 0, len(items))
+	for i := range items {
+		dateStart := items[i].DateStart.UTC()
+		dateEnd := items[i].DateEnd.UTC()
+		out = append(out, base.BaseOperationalShiftTime{
+			DateStart:     &dateStart,
+			DateEnd:       &dateEnd,
+			StartTimeType: normalizeShiftTimeType(items[i].StartTimeType),
+			EndTimeType:   normalizeShiftTimeType(items[i].EndTimeType),
+			ShiftStart:    timePtrToClockString(items[i].ShiftStart),
+			ShiftEnd:      timePtrToClockString(items[i].ShiftEnd),
+		})
+	}
+	return out
+}
+
+func timePtrToClockString(v *time.Time) string {
+	if v == nil {
+		return ""
+	}
+	return v.UTC().Format("15:04:05")
+}
+
+func normalizeUTCString(raw string) string {
+	return strings.TrimSpace(raw)
+}
+
+func normalizeShiftTimeType(raw string) string {
+	switch strings.ToUpper(strings.TrimSpace(raw)) {
+	case "", base.ShiftTimeTypeFixed:
+		return base.ShiftTimeTypeFixed
+	case base.ShiftTimeTypeBMCT:
+		return base.ShiftTimeTypeBMCT
+	case base.ShiftTimeTypeECET:
+		return base.ShiftTimeTypeECET
+	default:
+		return strings.ToUpper(strings.TrimSpace(raw))
+	}
+}
+
+func appendUniqueIDs(values [][]byte) [][]byte {
+	if len(values) == 0 {
+		return nil
+	}
+	out := make([][]byte, 0, len(values))
+	seen := map[string]struct{}{}
+	for i := range values {
+		if len(values[i]) != 16 {
+			continue
+		}
+		key := string(values[i])
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		out = append(out, append([]byte(nil), values[i]...))
+	}
+	return out
+}
+
+func categoryNotFoundDetail(category string) string {
+	if category == base.CategoryKeyHEMS {
+		return "hems base not found"
+	}
+	return "base not found"
+}
diff --git a/internal/service/before_flight_inspection_service.go b/internal/service/before_flight_inspection_service.go
new file mode 100644
index 0000000..f522e16
--- /dev/null
+++ b/internal/service/before_flight_inspection_service.go
@@ -0,0 +1,149 @@
+package service
+
+import (
+	"context"
+	"fmt"
+
+	beforeflightinspection "wucher/internal/domain/before_flight_inspection"
+	"wucher/internal/shared/pkg/appctx"
+)
+
+type BeforeFlightInspectionService struct {
+	repo beforeflightinspection.Repository
+}
+
+func NewBeforeFlightInspectionService(repo beforeflightinspection.Repository) *BeforeFlightInspectionService {
+	return &BeforeFlightInspectionService{repo: repo}
+}
+
+func (s *BeforeFlightInspectionService) Upsert(ctx context.Context, flightInspectionID []byte, req *beforeflightinspection.UpsertRequest) (*beforeflightinspection.BeforeFlightInspection, error) {
+	if len(flightInspectionID) != 16 {
+		return nil, &beforeflightinspection.ValidationError{Status: 400, Title: "Invalid flight_inspection_id", Detail: "flight_inspection_id must be a valid UUID"}
+	}
+
+	exists, err := s.repo.FlightInspectionExists(ctx, flightInspectionID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check flight inspection: %w", err)
+	}
+	if !exists {
+		return nil, &beforeflightinspection.ValidationError{Status: 404, Title: "Flight inspection not found", Detail: "The specified flight inspection does not exist"}
+	}
+
+	caps, err := s.repo.GetHelicopterCapabilities(ctx, flightInspectionID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get helicopter capabilities: %w", err)
+	}
+
+	if err := s.validateRequest(req, caps); err != nil {
+		return nil, err
+	}
+
+	row := &beforeflightinspection.BeforeFlightInspection{
+		FlightInspectionID:        flightInspectionID,
+		OilEngineNR1Checked:       req.OilEngineNR1Checked,
+		OilEngineNR2Checked:       req.OilEngineNR2Checked,
+		HydraulicLHChecked:        req.HydraulicLHChecked,
+		HydraulicRHChecked:        req.HydraulicRHChecked,
+		OilTransmissionMGBChecked: req.OilTransmissionMGBChecked,
+		OilTransmissionIGBChecked: req.OilTransmissionIGBChecked,
+		OilTransmissionTGBChecked: req.OilTransmissionTGBChecked,
+		FuelAmount:                req.FuelAmount,
+		FuelUnit:                  s.normalizeFuelUnit(req.FuelUnit),
+		FuelAddedAmount:           req.FuelAddedAmount,
+	}
+
+	// Keep update idempotent on unique flight_inspection_id.
+	// If a row already exists, update it instead of inserting a new one.
+	existing, err := s.repo.GetByFlightInspectionID(ctx, flightInspectionID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get before flight inspection: %w", err)
+	}
+	if existing != nil {
+		row.ID = append([]byte(nil), existing.ID...)
+		row.CreatedBy = append([]byte(nil), existing.CreatedBy...)
+		row.CreatedAt = existing.CreatedAt
+	}
+
+	userID := appctx.GetUserID(ctx)
+	if userID != nil {
+		if existing == nil {
+			row.CreatedBy = userID
+		}
+		row.UpdatedBy = userID
+	}
+
+	if err := s.repo.Upsert(ctx, row); err != nil {
+		return nil, fmt.Errorf("failed to upsert before flight inspection: %w", err)
+	}
+
+	return row, nil
+}
+
+func (s *BeforeFlightInspectionService) GetByFlightInspectionID(ctx context.Context, flightInspectionID []byte) (*beforeflightinspection.BeforeFlightInspection, error) {
+	if len(flightInspectionID) != 16 {
+		return nil, &beforeflightinspection.ValidationError{Status: 400, Title: "Invalid flight_inspection_id", Detail: "flight_inspection_id must be a valid UUID"}
+	}
+
+	exists, err := s.repo.FlightInspectionExists(ctx, flightInspectionID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check flight inspection: %w", err)
+	}
+	if !exists {
+		return nil, &beforeflightinspection.ValidationError{Status: 404, Title: "Flight inspection not found", Detail: "The specified flight inspection does not exist"}
+	}
+
+	row, err := s.repo.GetByFlightInspectionID(ctx, flightInspectionID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get before flight inspection: %w", err)
+	}
+
+	return row, nil
+}
+
+func (s *BeforeFlightInspectionService) validateRequest(req *beforeflightinspection.UpsertRequest, caps *beforeflightinspection.HelicopterCapabilities) error {
+	if req.FuelAmount != nil && *req.FuelAmount < 0 {
+		return &beforeflightinspection.ValidationError{Status: 422, Title: "Invalid fuel_amount", Detail: "fuel_amount cannot be negative"}
+	}
+	if req.FuelAddedAmount != nil && *req.FuelAddedAmount < 0 {
+		return &beforeflightinspection.ValidationError{Status: 422, Title: "Invalid fuel_added_amount", Detail: "fuel_added_amount cannot be negative"}
+	}
+
+	if req.FuelUnit != nil {
+		if _, valid := beforeflightinspection.NormalizeFuelUnit(*req.FuelUnit); !valid {
+			return &beforeflightinspection.ValidationError{Status: 422, Title: "Invalid fuel_unit", Detail: "fuel_unit must be one of: LT, KG, POUND"}
+		}
+	}
+
+	// Capability=true means corresponding check must be explicitly true.
+	if caps.NR1 && (req.OilEngineNR1Checked == nil || !*req.OilEngineNR1Checked) {
+		return &beforeflightinspection.ValidationError{Status: 422, Title: "Invalid oil_engine_nr1_checked", Detail: "oil_engine_nr1_checked must be true for this helicopter"}
+	}
+	if caps.NR2 && (req.OilEngineNR2Checked == nil || !*req.OilEngineNR2Checked) {
+		return &beforeflightinspection.ValidationError{Status: 422, Title: "Invalid oil_engine_nr2_checked", Detail: "oil_engine_nr2_checked must be true for this helicopter"}
+	}
+	if caps.LH && (req.HydraulicLHChecked == nil || !*req.HydraulicLHChecked) {
+		return &beforeflightinspection.ValidationError{Status: 422, Title: "Invalid hydraulic_lh_checked", Detail: "hydraulic_lh_checked must be true for this helicopter"}
+	}
+	if caps.RH && (req.HydraulicRHChecked == nil || !*req.HydraulicRHChecked) {
+		return &beforeflightinspection.ValidationError{Status: 422, Title: "Invalid hydraulic_rh_checked", Detail: "hydraulic_rh_checked must be true for this helicopter"}
+	}
+	if caps.MGB && (req.OilTransmissionMGBChecked == nil || !*req.OilTransmissionMGBChecked) {
+		return &beforeflightinspection.ValidationError{Status: 422, Title: "Invalid oil_transmission_mgb_checked", Detail: "oil_transmission_mgb_checked must be true for this helicopter"}
+	}
+	if caps.IGB && (req.OilTransmissionIGBChecked == nil || !*req.OilTransmissionIGBChecked) {
+		return &beforeflightinspection.ValidationError{Status: 422, Title: "Invalid oil_transmission_igb_checked", Detail: "oil_transmission_igb_checked must be true for this helicopter"}
+	}
+	if caps.TGB && (req.OilTransmissionTGBChecked == nil || !*req.OilTransmissionTGBChecked) {
+		return &beforeflightinspection.ValidationError{Status: 422, Title: "Invalid oil_transmission_tgb_checked", Detail: "oil_transmission_tgb_checked must be true for this helicopter"}
+	}
+
+	return nil
+}
+
+func (s *BeforeFlightInspectionService) normalizeFuelUnit(unit *string) string {
+	if unit == nil {
+		return ""
+	}
+	normalized, _ := beforeflightinspection.NormalizeFuelUnit(*unit)
+	return normalized
+}
diff --git a/internal/service/before_flight_inspection_service_test.go b/internal/service/before_flight_inspection_service_test.go
new file mode 100644
index 0000000..a11a8fb
--- /dev/null
+++ b/internal/service/before_flight_inspection_service_test.go
@@ -0,0 +1,98 @@
+package service
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	beforeflightinspection "wucher/internal/domain/before_flight_inspection"
+	"wucher/internal/shared/pkg/appctx"
+)
+
+type beforeFlightInspectionRepoStub struct {
+	exists            bool
+	caps              *beforeflightinspection.HelicopterCapabilities
+	existing          *beforeflightinspection.BeforeFlightInspection
+	upserted          *beforeflightinspection.BeforeFlightInspection
+	upsertCallCount   int
+	lookupCallCount   int
+	existsCallCount   int
+	capabilityChecked int
+}
+
+func (r *beforeFlightInspectionRepoStub) Upsert(_ context.Context, row *beforeflightinspection.BeforeFlightInspection) error {
+	r.upsertCallCount++
+	r.upserted = row
+	return nil
+}
+
+func (r *beforeFlightInspectionRepoStub) GetByFlightInspectionID(_ context.Context, _ []byte) (*beforeflightinspection.BeforeFlightInspection, error) {
+	r.lookupCallCount++
+	return r.existing, nil
+}
+
+func (r *beforeFlightInspectionRepoStub) FlightInspectionExists(_ context.Context, _ []byte) (bool, error) {
+	r.existsCallCount++
+	return r.exists, nil
+}
+
+func (r *beforeFlightInspectionRepoStub) GetHelicopterCapabilities(_ context.Context, _ []byte) (*beforeflightinspection.HelicopterCapabilities, error) {
+	r.capabilityChecked++
+	return r.caps, nil
+}
+
+func TestBeforeFlightInspectionServiceUpsertUsesExistingID(t *testing.T) {
+	t.Parallel()
+
+	flightInspectionID := []byte{0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x20, 0x21, 0x22, 0x23, 0x24, 0x25}
+	existingID := []byte{0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x40, 0x41, 0x42, 0x43, 0x44, 0x45}
+	createdBy := []byte{0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x60, 0x61, 0x62, 0x63, 0x64, 0x65}
+	updatedBy := []byte{0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x80, 0x81, 0x82, 0x83, 0x84, 0x85}
+	createdAt := time.Date(2026, time.April, 16, 8, 30, 0, 0, time.UTC)
+
+	repo := &beforeFlightInspectionRepoStub{
+		exists: true,
+		caps:   &beforeflightinspection.HelicopterCapabilities{},
+		existing: &beforeflightinspection.BeforeFlightInspection{
+			ID:                 existingID,
+			FlightInspectionID: flightInspectionID,
+			CreatedBy:          createdBy,
+			CreatedAt:          createdAt,
+		},
+	}
+	svc := NewBeforeFlightInspectionService(repo)
+
+	fuelUnit := "lt"
+	req := &beforeflightinspection.UpsertRequest{FuelUnit: &fuelUnit}
+
+	ctx := appctx.WithUserID(context.Background(), updatedBy)
+	out, err := svc.Upsert(ctx, flightInspectionID, req)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if out == nil {
+		t.Fatal("expected non-nil output")
+	}
+
+	if repo.upsertCallCount != 1 {
+		t.Fatalf("expected Upsert to be called once, got %d", repo.upsertCallCount)
+	}
+	if repo.upserted == nil {
+		t.Fatal("expected upserted payload to be captured")
+	}
+	if string(repo.upserted.ID) != string(existingID) {
+		t.Fatalf("expected existing ID to be reused, got %q", string(repo.upserted.ID))
+	}
+	if string(repo.upserted.CreatedBy) != string(createdBy) {
+		t.Fatalf("expected existing CreatedBy to be preserved, got %q", string(repo.upserted.CreatedBy))
+	}
+	if !repo.upserted.CreatedAt.Equal(createdAt) {
+		t.Fatalf("expected CreatedAt to be preserved, got %v", repo.upserted.CreatedAt)
+	}
+	if string(repo.upserted.UpdatedBy) != string(updatedBy) {
+		t.Fatalf("expected UpdatedBy to be set from context, got %q", string(repo.upserted.UpdatedBy))
+	}
+	if repo.upserted.FuelUnit != "LT" {
+		t.Fatalf("expected fuel unit normalized to LT, got %q", repo.upserted.FuelUnit)
+	}
+}
diff --git a/internal/service/complaint_service.go b/internal/service/complaint_service.go
new file mode 100644
index 0000000..25353c7
--- /dev/null
+++ b/internal/service/complaint_service.go
@@ -0,0 +1,74 @@
+package service
+
+import (
+	"context"
+
+	complaint "wucher/internal/domain/complaint"
+	"wucher/internal/shared/pkg/userctx"
+)
+
+type ComplaintService struct{ repo complaint.Repository }
+
+func NewComplaintService(repo complaint.Repository) *ComplaintService {
+	return &ComplaintService{repo: repo}
+}
+
+func (s *ComplaintService) Create(ctx context.Context, row *complaint.Complaint) error {
+	return s.repo.Create(ctx, row)
+}
+func (s *ComplaintService) Update(ctx context.Context, row *complaint.Complaint) error {
+	return s.repo.Update(ctx, row)
+}
+func (s *ComplaintService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+func (s *ComplaintService) GetByID(ctx context.Context, id []byte) (*complaint.Complaint, error) {
+	return s.repo.GetByID(ctx, id)
+}
+func (s *ComplaintService) ListByHelicopter(ctx context.Context, helicopterID []byte, limit, offset int) ([]complaint.Complaint, int64, error) {
+	return s.repo.ListByHelicopter(ctx, helicopterID, limit, offset)
+}
+func (s *ComplaintService) List(ctx context.Context, filter complaint.ListFilter, sort string, limit, offset int) ([]complaint.Complaint, int64, error) {
+	return s.repo.List(ctx, filter, sort, limit, offset)
+}
+func (s *ComplaintService) HelicopterHasOpenComplaint(ctx context.Context, helicopterID []byte) (bool, error) {
+	return s.repo.HelicopterHasOpenComplaint(ctx, helicopterID)
+}
+func (s *ComplaintService) ActiveGroundingByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) ([]complaint.Complaint, error) {
+	return s.repo.ActiveGroundingByHelicopterIDs(ctx, helicopterIDs)
+}
+func (s *ComplaintService) OpenByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) ([]complaint.Complaint, error) {
+	return s.repo.OpenByHelicopterIDs(ctx, helicopterIDs)
+}
+func (s *ComplaintService) HelicopterHasUnactionedComplaint(ctx context.Context, helicopterID []byte) (bool, error) {
+	return s.repo.HelicopterHasUnactionedComplaint(ctx, helicopterID)
+}
+func (s *ComplaintService) MarkFixedByHelicopter(ctx context.Context, helicopterID []byte, easaID []byte, actor []byte) error {
+	return s.repo.MarkFixedByHelicopter(ctx, helicopterID, easaID, actor)
+}
+func (s *ComplaintService) MarkFixedByComplaint(ctx context.Context, complaintID []byte, easaID []byte, actor []byte) error {
+	return s.repo.MarkFixedByComplaint(ctx, complaintID, easaID, actor)
+}
+func (s *ComplaintService) MarkFixedByFlight(ctx context.Context, flightID []byte, easaID []byte, actor []byte) error {
+	return s.repo.MarkFixedByFlight(ctx, flightID, easaID, actor)
+}
+func (s *ComplaintService) ResolveUserNames(ctx context.Context, complaints []complaint.Complaint) (map[string]string, error) {
+	out := make(map[string]string)
+	add := func(id []byte) {
+		if len(id) == 0 {
+			return
+		}
+		if _, ok := out[string(id)]; ok {
+			return
+		}
+		if n := userctx.GetDisplayName(ctx, id); n != "" {
+			out[string(id)] = n
+		}
+	}
+	for i := range complaints {
+		add(complaints[i].ReportedBy)
+		add(complaints[i].MELClassifiedBy)
+		add(complaints[i].NSRDecidedBy)
+	}
+	return out, nil
+}
diff --git a/internal/service/complaint_service_test.go b/internal/service/complaint_service_test.go
new file mode 100644
index 0000000..72b58f4
--- /dev/null
+++ b/internal/service/complaint_service_test.go
@@ -0,0 +1,141 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/complaint"
+	"wucher/internal/shared/pkg/userctx"
+)
+
+type stubComplaintRepo struct {
+	row             *complaint.Complaint
+	open            bool
+	unactioned      bool
+	active          []complaint.Complaint
+	createErr       error
+	created         *complaint.Complaint
+	markedHeli      []byte
+	markedComplaint []byte
+	markedFlight    []byte
+}
+
+func (s *stubComplaintRepo) Create(_ context.Context, row *complaint.Complaint) error {
+	s.created = row
+	return s.createErr
+}
+func (s *stubComplaintRepo) Update(_ context.Context, _ *complaint.Complaint) error { return nil }
+func (s *stubComplaintRepo) Delete(_ context.Context, _, _ []byte) error            { return nil }
+func (s *stubComplaintRepo) GetByID(_ context.Context, _ []byte) (*complaint.Complaint, error) {
+	return s.row, nil
+}
+func (s *stubComplaintRepo) ListByHelicopter(_ context.Context, _ []byte, _, _ int) ([]complaint.Complaint, int64, error) {
+	return s.active, int64(len(s.active)), nil
+}
+func (s *stubComplaintRepo) List(_ context.Context, _ complaint.ListFilter, _ string, _, _ int) ([]complaint.Complaint, int64, error) {
+	return s.active, int64(len(s.active)), nil
+}
+func (s *stubComplaintRepo) HelicopterHasOpenComplaint(_ context.Context, _ []byte) (bool, error) {
+	return s.open, nil
+}
+func (s *stubComplaintRepo) ActiveGroundingByHelicopterIDs(_ context.Context, _ [][]byte) ([]complaint.Complaint, error) {
+	return s.active, nil
+}
+func (s *stubComplaintRepo) OpenByHelicopterIDs(_ context.Context, _ [][]byte) ([]complaint.Complaint, error) {
+	return s.active, nil
+}
+func (s *stubComplaintRepo) HelicopterHasUnactionedComplaint(_ context.Context, _ []byte) (bool, error) {
+	return s.unactioned, nil
+}
+func (s *stubComplaintRepo) MarkFixedByHelicopter(_ context.Context, helicopterID, _, _ []byte) error {
+	s.markedHeli = helicopterID
+	return nil
+}
+func (s *stubComplaintRepo) MarkFixedByComplaint(_ context.Context, complaintID, _, _ []byte) error {
+	s.markedComplaint = complaintID
+	return nil
+}
+func (s *stubComplaintRepo) MarkFixedByFlight(_ context.Context, flightID, _, _ []byte) error {
+	s.markedFlight = flightID
+	return nil
+}
+
+func TestComplaintServiceDelegation(t *testing.T) {
+	repo := &stubComplaintRepo{
+		row:        &complaint.Complaint{},
+		open:       true,
+		unactioned: true,
+		active:     []complaint.Complaint{{}},
+	}
+	svc := NewComplaintService(repo)
+	ctx := context.Background()
+
+	if err := svc.Create(ctx, &complaint.Complaint{}); err != nil {
+		t.Fatalf("Create: %v", err)
+	}
+	if err := svc.Update(ctx, &complaint.Complaint{}); err != nil {
+		t.Fatalf("Update: %v", err)
+	}
+	if err := svc.Delete(ctx, []byte("x"), nil); err != nil {
+		t.Fatalf("Delete: %v", err)
+	}
+	if _, err := svc.GetByID(ctx, []byte("x")); err != nil {
+		t.Fatalf("GetByID: %v", err)
+	}
+	if rows, _, err := svc.ListByHelicopter(ctx, []byte("h"), 10, 0); err != nil || len(rows) != 1 {
+		t.Fatalf("ListByHelicopter: %v", err)
+	}
+	if _, _, err := svc.List(ctx, complaint.ListFilter{}, "", 10, 0); err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if open, err := svc.HelicopterHasOpenComplaint(ctx, []byte("h")); err != nil || !open {
+		t.Fatalf("HelicopterHasOpenComplaint: %v", err)
+	}
+	if un, err := svc.HelicopterHasUnactionedComplaint(ctx, []byte("h")); err != nil || !un {
+		t.Fatalf("HelicopterHasUnactionedComplaint: %v", err)
+	}
+	if _, err := svc.ActiveGroundingByHelicopterIDs(ctx, [][]byte{[]byte("h")}); err != nil {
+		t.Fatalf("ActiveGroundingByHelicopterIDs: %v", err)
+	}
+	if err := svc.MarkFixedByHelicopter(ctx, []byte("heli"), []byte("easa"), []byte("actor")); err != nil || string(repo.markedHeli) != "heli" {
+		t.Fatalf("MarkFixedByHelicopter: %v", err)
+	}
+
+	repo.createErr = errors.New("boom")
+	if err := svc.Create(ctx, &complaint.Complaint{}); err == nil {
+		t.Fatal("expected create error to propagate")
+	}
+}
+
+type stubNameGetter struct{}
+
+func (stubNameGetter) GetLastName(_ context.Context, id []byte) (string, error) {
+	return "Name-" + string(id), nil
+}
+
+func TestComplaintServiceResolveUserNames(t *testing.T) {
+	svc := NewComplaintService(&stubComplaintRepo{})
+	ctx := userctx.WithGetter(context.Background(), stubNameGetter{})
+
+	rows := []complaint.Complaint{
+		{ReportedBy: []byte("u1"), MELClassifiedBy: []byte("u1"), NSRDecidedBy: []byte("u2")},
+		{}, // all-empty ids skipped
+	}
+	names, err := svc.ResolveUserNames(ctx, rows)
+	if err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	if names["u1"] != "Name-u1" || names["u2"] != "Name-u2" {
+		t.Fatalf("unexpected names: %v", names)
+	}
+	if len(names) != 2 {
+		t.Fatalf("dup/empty ids should be deduped/skipped, got %v", names)
+	}
+
+	// No getter in context -> no names resolved.
+	empty, _ := svc.ResolveUserNames(context.Background(), rows)
+	if len(empty) != 0 {
+		t.Fatalf("expected no names without getter, got %v", empty)
+	}
+}
diff --git a/internal/service/contact_service.go b/internal/service/contact_service.go
new file mode 100644
index 0000000..22778c7
--- /dev/null
+++ b/internal/service/contact_service.go
@@ -0,0 +1,158 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"wucher/internal/domain/contact"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type pinVerifier interface {
+	ConsumeSecurityPINActionToken(ctx context.Context, userID []byte, action, token string) error
+}
+
+type ContactService struct {
+	repo        contact.Repository
+	pinVerifier pinVerifier
+}
+
+func NewContactService(repo contact.Repository, pinVerifier pinVerifier) *ContactService {
+	return &ContactService{repo: repo, pinVerifier: pinVerifier}
+}
+
+func (s *ContactService) ListContacts(ctx context.Context, filter contact.ListFilter) ([]contact.ContactListItem, int64, error) {
+	if s.repo == nil {
+		return nil, 0, errors.New("contact repository not configured")
+	}
+	filter.Sort = normalizeContactSort(filter.Sort)
+	return s.repo.ListContacts(ctx, filter)
+}
+
+func (s *ContactService) GetContactByID(ctx context.Context, userID []byte) (*contact.ContactListItem, error) {
+	if s.repo == nil {
+		return nil, errors.New("contact repository not configured")
+	}
+	return s.repo.GetContactByID(ctx, userID)
+}
+
+func (s *ContactService) IsActorAdmin(ctx context.Context) (bool, error) {
+	if s.repo == nil {
+		return false, errors.New("contact repository not configured")
+	}
+	return s.repo.IsActorAdmin(ctx)
+}
+
+func (s *ContactService) ResolveRoleCodeByID(ctx context.Context, roleID []byte) (string, error) {
+	if s.repo == nil {
+		return "", errors.New("contact repository not configured")
+	}
+	return s.repo.ResolveRoleCodeByID(ctx, roleID)
+}
+
+func (s *ContactService) CreateContact(ctx context.Context, in contact.CreateInput) ([]byte, error) {
+	if s.repo == nil {
+		return nil, errors.New("contact repository not configured")
+	}
+	return s.repo.CreateContact(ctx, in)
+}
+
+func (s *ContactService) UpdateContact(ctx context.Context, in contact.UpdateInput) error {
+	if s.repo == nil {
+		return errors.New("contact repository not configured")
+	}
+	return s.repo.UpdateContact(ctx, in)
+}
+
+func (s *ContactService) DeleteContact(ctx context.Context, userID []byte) error {
+	if s.repo == nil {
+		return errors.New("contact repository not configured")
+	}
+	return s.repo.DeleteContact(ctx, userID)
+}
+
+func (s *ContactService) UpdateContactStatus(ctx context.Context, userID []byte, isActive bool) error {
+	if s.repo == nil {
+		return errors.New("contact repository not configured")
+	}
+	return s.repo.UpdateContactStatus(ctx, userID, isActive)
+}
+
+func (s *ContactService) UpdateContactRole(ctx context.Context, userID []byte, roleCode string) error {
+	if s.repo == nil {
+		return errors.New("contact repository not configured")
+	}
+	return s.repo.UpdateContactRole(ctx, userID, roleCode)
+}
+
+func (s *ContactService) UpdatePilotCategory(ctx context.Context, userID []byte, category string) error {
+	if s.repo == nil {
+		return errors.New("contact repository not configured")
+	}
+	return s.repo.UpdatePilotCategory(ctx, userID, category)
+}
+
+func (s *ContactService) UpdateLicense(ctx context.Context, userID []byte, licenseNo *string) error {
+	if s.repo == nil {
+		return errors.New("contact repository not configured")
+	}
+	return s.repo.UpdateLicense(ctx, userID, licenseNo)
+}
+
+func (s *ContactService) UpdateChiefFlags(ctx context.Context, userID []byte, patch contact.ProfilePatch) error {
+	if s.repo == nil {
+		return errors.New("contact repository not configured")
+	}
+	return s.repo.UpdateChiefFlags(ctx, userID, patch)
+}
+
+func (s *ContactService) UpdateResponsibleComplaints(ctx context.Context, userID []byte, value bool) error {
+	if s.repo == nil {
+		return errors.New("contact repository not configured")
+	}
+	return s.repo.UpdateResponsibleComplaints(ctx, userID, value)
+}
+
+func (s *ContactService) BulkUpdateStatus(ctx context.Context, userIDs [][]byte, isActive bool) (int64, error) {
+	if s.repo == nil {
+		return 0, errors.New("contact repository not configured")
+	}
+	return s.repo.BulkUpdateStatus(ctx, userIDs, isActive)
+}
+
+func (s *ContactService) CheckSensitiveAction(ctx context.Context, userID []byte, actionToken, action string) error {
+	if len(userID) != 16 {
+		return ErrInvalidPINAction
+	}
+	if s.pinVerifier == nil {
+		return errors.New("pin verifier not configured")
+	}
+	action = strings.TrimSpace(action)
+	actionToken = strings.TrimSpace(actionToken)
+	if action == "" || actionToken == "" {
+		return ErrInvalidPINAction
+	}
+	return s.pinVerifier.ConsumeSecurityPINActionToken(ctx, userID, action, actionToken)
+}
+
+func normalizeContactSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("users", "is_active", "sortkey", "first_name", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("users", "is_active", "sortkey", "first_name", true)),
+			"sortkey",
+		),
+		sortExpr(
+			"COALESCE(pp.note, dp.note, arp.note, tp.note, fap.note, sp.note, '') ASC",
+			"COALESCE(pp.note, dp.note, arp.note, tp.note, fap.note, sp.note, '') DESC",
+			"note",
+		),
+		sortField("users.is_active", "is_active"),
+		sortField("users.first_name", "first_name", "name"),
+		sortField("users.last_name", "last_name"),
+		sortField("users.email", "email"),
+		sortField("users.created_at", "created_at"),
+		sortField("users.updated_at", "updated_at"),
+	)
+}
diff --git a/internal/service/contact_service_test.go b/internal/service/contact_service_test.go
new file mode 100644
index 0000000..c59a8d4
--- /dev/null
+++ b/internal/service/contact_service_test.go
@@ -0,0 +1,504 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/contact"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type mockContactRepo struct {
+	listItems  []contact.ContactListItem
+	listTotal  int64
+	listErr    error
+	lastFilter contact.ListFilter
+
+	getItem         *contact.ContactListItem
+	getErr          error
+	lastGetID       []byte
+	isActorAdmin    bool
+	isActorAdminErr error
+	resolveRoleCode string
+	resolveRoleErr  error
+	lastResolveID   []byte
+
+	createID   []byte
+	createErr  error
+	lastCreate contact.CreateInput
+
+	updateErr  error
+	lastUpdate contact.UpdateInput
+
+	deleteErr    error
+	lastDeleteID []byte
+
+	updateStatusErr    error
+	lastStatusID       []byte
+	lastStatusIsActive bool
+
+	updateRoleErr error
+	lastRoleID    []byte
+	lastRoleCode  string
+
+	updatePilotErr error
+	lastPilotID    []byte
+	lastCategory   string
+
+	updateLicenseErr error
+	lastLicenseID    []byte
+	lastLicenseNo    *string
+
+	updateChiefFlagsErr error
+	lastChiefID         []byte
+	lastChiefPatch      contact.ProfilePatch
+
+	updateResponsibleErr error
+	lastResponsibleID    []byte
+	lastResponsibleValue bool
+
+	bulkErr        error
+	bulkCount      int64
+	lastBulkIDs    [][]byte
+	lastBulkActive bool
+}
+
+func (m *mockContactRepo) ListContacts(_ context.Context, filter contact.ListFilter) ([]contact.ContactListItem, int64, error) {
+	m.lastFilter = filter
+	if m.listErr != nil {
+		return nil, 0, m.listErr
+	}
+	return m.listItems, m.listTotal, nil
+}
+
+func (m *mockContactRepo) GetContactByID(_ context.Context, userID []byte) (*contact.ContactListItem, error) {
+	m.lastGetID = append([]byte(nil), userID...)
+	if m.getErr != nil {
+		return nil, m.getErr
+	}
+	return m.getItem, nil
+}
+
+func (m *mockContactRepo) IsActorAdmin(_ context.Context) (bool, error) {
+	if m.isActorAdminErr != nil {
+		return false, m.isActorAdminErr
+	}
+	return m.isActorAdmin, nil
+}
+
+func (m *mockContactRepo) ResolveRoleCodeByID(_ context.Context, roleID []byte) (string, error) {
+	m.lastResolveID = append([]byte(nil), roleID...)
+	if m.resolveRoleErr != nil {
+		return "", m.resolveRoleErr
+	}
+	return m.resolveRoleCode, nil
+}
+
+func (m *mockContactRepo) CreateContact(_ context.Context, in contact.CreateInput) ([]byte, error) {
+	m.lastCreate = in
+	if m.createErr != nil {
+		return nil, m.createErr
+	}
+	return m.createID, nil
+}
+
+func (m *mockContactRepo) UpdateContact(_ context.Context, in contact.UpdateInput) error {
+	m.lastUpdate = in
+	return m.updateErr
+}
+
+func (m *mockContactRepo) DeleteContact(_ context.Context, userID []byte) error {
+	m.lastDeleteID = append([]byte(nil), userID...)
+	return m.deleteErr
+}
+
+func (m *mockContactRepo) UpdateContactStatus(_ context.Context, userID []byte, isActive bool) error {
+	m.lastStatusID = append([]byte(nil), userID...)
+	m.lastStatusIsActive = isActive
+	return m.updateStatusErr
+}
+
+func (m *mockContactRepo) UpdateContactRole(_ context.Context, userID []byte, roleCode string) error {
+	m.lastRoleID = append([]byte(nil), userID...)
+	m.lastRoleCode = roleCode
+	return m.updateRoleErr
+}
+
+func (m *mockContactRepo) UpdatePilotCategory(_ context.Context, userID []byte, category string) error {
+	m.lastPilotID = append([]byte(nil), userID...)
+	m.lastCategory = category
+	return m.updatePilotErr
+}
+
+func (m *mockContactRepo) UpdateLicense(_ context.Context, userID []byte, licenseNo *string) error {
+	m.lastLicenseID = append([]byte(nil), userID...)
+	m.lastLicenseNo = licenseNo
+	return m.updateLicenseErr
+}
+
+func (m *mockContactRepo) UpdateChiefFlags(_ context.Context, userID []byte, patch contact.ProfilePatch) error {
+	m.lastChiefID = append([]byte(nil), userID...)
+	m.lastChiefPatch = patch
+	return m.updateChiefFlagsErr
+}
+
+func (m *mockContactRepo) UpdateResponsibleComplaints(_ context.Context, userID []byte, value bool) error {
+	m.lastResponsibleID = append([]byte(nil), userID...)
+	m.lastResponsibleValue = value
+	return m.updateResponsibleErr
+}
+
+func (m *mockContactRepo) BulkUpdateStatus(_ context.Context, userIDs [][]byte, isActive bool) (int64, error) {
+	m.lastBulkIDs = append([][]byte(nil), userIDs...)
+	m.lastBulkActive = isActive
+	if m.bulkErr != nil {
+		return 0, m.bulkErr
+	}
+	return m.bulkCount, nil
+}
+
+type mockPINVerifier struct {
+	err        error
+	lastUserID []byte
+	lastAction string
+	lastToken  string
+}
+
+func (m *mockPINVerifier) ConsumeSecurityPINActionToken(_ context.Context, userID []byte, action, token string) error {
+	m.lastUserID = append([]byte(nil), userID...)
+	m.lastAction = action
+	m.lastToken = token
+	return m.err
+}
+
+func TestNewContactService(t *testing.T) {
+	repo := &mockContactRepo{}
+	verifier := &mockPINVerifier{}
+	svc := NewContactService(repo, verifier)
+	if svc == nil || svc.repo != repo || svc.pinVerifier != verifier {
+		t.Fatalf("expected service to hold dependencies")
+	}
+}
+
+func TestContactServiceRepoNotConfigured(t *testing.T) {
+	svc := NewContactService(nil, nil)
+	ctx := context.Background()
+	userID := uuidv7.MustBytes()
+
+	if _, _, err := svc.ListContacts(ctx, contact.ListFilter{}); err == nil {
+		t.Fatalf("expected list error")
+	}
+	if _, err := svc.GetContactByID(ctx, userID); err == nil {
+		t.Fatalf("expected get error")
+	}
+	if _, err := svc.ResolveRoleCodeByID(ctx, userID); err == nil {
+		t.Fatalf("expected resolve role error")
+	}
+	if _, err := svc.CreateContact(ctx, contact.CreateInput{}); err == nil {
+		t.Fatalf("expected create error")
+	}
+	if err := svc.UpdateContact(ctx, contact.UpdateInput{}); err == nil {
+		t.Fatalf("expected update error")
+	}
+	if err := svc.DeleteContact(ctx, userID); err == nil {
+		t.Fatalf("expected delete error")
+	}
+	if err := svc.UpdateContactStatus(ctx, userID, true); err == nil {
+		t.Fatalf("expected status error")
+	}
+	if err := svc.UpdateContactRole(ctx, userID, "pilot"); err == nil {
+		t.Fatalf("expected role error")
+	}
+	if err := svc.UpdatePilotCategory(ctx, userID, "regular"); err == nil {
+		t.Fatalf("expected pilot category error")
+	}
+	if err := svc.UpdateLicense(ctx, userID, nil); err == nil {
+		t.Fatalf("expected license error")
+	}
+	if err := svc.UpdateChiefFlags(ctx, userID, contact.ProfilePatch{}); err == nil {
+		t.Fatalf("expected chief flags error")
+	}
+	if err := svc.UpdateResponsibleComplaints(ctx, userID, true); err == nil {
+		t.Fatalf("expected responsible complaints error")
+	}
+	if _, err := svc.BulkUpdateStatus(ctx, [][]byte{userID}, true); err == nil {
+		t.Fatalf("expected bulk update error")
+	}
+}
+
+func TestContactServiceDelegatesToRepo(t *testing.T) {
+	ctx := context.Background()
+	userID := uuidv7.MustBytes()
+	roleID := uuidv7.MustBytes()
+	licenseNo := "LIC"
+	shortName := "PJ"
+	repoErr := errors.New("repo failed")
+
+	t.Run("list success and error", func(t *testing.T) {
+		repo := &mockContactRepo{
+			listItems: []contact.ContactListItem{{UserID: userID, Email: "user@example.com"}},
+			listTotal: 1,
+		}
+		svc := NewContactService(repo, nil)
+		filter := contact.ListFilter{Role: "pilot", Sort: "sortkey", Limit: 10, Offset: 5}
+		items, total, err := svc.ListContacts(ctx, filter)
+		if err != nil || total != 1 || len(items) != 1 {
+			t.Fatalf("unexpected list result: total=%d len=%d err=%v", total, len(items), err)
+		}
+		if repo.lastFilter.Role != "pilot" || repo.lastFilter.Limit != 10 || repo.lastFilter.Offset != 5 {
+			t.Fatalf("expected filter forwarded, got %#v", repo.lastFilter)
+		}
+		if repo.lastFilter.Sort != "users.is_active DESC, CASE WHEN users.is_active = 1 AND users.sortkey IS NOT NULL AND users.sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN users.is_active = 1 AND users.sortkey IS NOT NULL AND users.sortkey >= 0 THEN users.sortkey END ASC, users.first_name ASC" {
+			t.Fatalf("unexpected normalized sort, got %q", repo.lastFilter.Sort)
+		}
+
+		repo.listErr = repoErr
+		if _, _, err := svc.ListContacts(ctx, filter); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("get success and error", func(t *testing.T) {
+		repo := &mockContactRepo{getItem: &contact.ContactListItem{UserID: userID, Email: "user@example.com"}}
+		svc := NewContactService(repo, nil)
+		item, err := svc.GetContactByID(ctx, userID)
+		if err != nil || item == nil || string(repo.lastGetID) != string(userID) {
+			t.Fatalf("unexpected get result: item=%v err=%v", item, err)
+		}
+		repo.getErr = repoErr
+		if _, err := svc.GetContactByID(ctx, userID); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("resolve role success and error", func(t *testing.T) {
+		repo := &mockContactRepo{resolveRoleCode: "pilot"}
+		svc := NewContactService(repo, nil)
+		roleCode, err := svc.ResolveRoleCodeByID(ctx, roleID)
+		if err != nil || roleCode != "pilot" || string(repo.lastResolveID) != string(roleID) {
+			t.Fatalf("unexpected resolve role result: role=%q err=%v", roleCode, err)
+		}
+		repo.resolveRoleErr = repoErr
+		if _, err := svc.ResolveRoleCodeByID(ctx, roleID); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("create success and error", func(t *testing.T) {
+		repo := &mockContactRepo{createID: userID}
+		svc := NewContactService(repo, nil)
+		in := contact.CreateInput{
+			RoleID:  roleID,
+			User:    contact.UserPatch{Email: &licenseNo},
+			Profile: contact.ProfilePatch{ShortName: &shortName},
+		}
+		gotID, err := svc.CreateContact(ctx, in)
+		if err != nil || string(gotID) != string(userID) {
+			t.Fatalf("unexpected create result: id=%v err=%v", gotID, err)
+		}
+		if string(repo.lastCreate.RoleID) != string(roleID) || repo.lastCreate.Profile.ShortName == nil || *repo.lastCreate.Profile.ShortName != shortName {
+			t.Fatalf("expected create input forwarded")
+		}
+		repo.createErr = repoErr
+		if _, err := svc.CreateContact(ctx, in); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("update success and error", func(t *testing.T) {
+		repo := &mockContactRepo{}
+		svc := NewContactService(repo, nil)
+		in := contact.UpdateInput{UserID: userID, Profile: contact.ProfilePatch{ShortName: &shortName}}
+		if err := svc.UpdateContact(ctx, in); err != nil {
+			t.Fatalf("unexpected update error: %v", err)
+		}
+		if string(repo.lastUpdate.UserID) != string(userID) || repo.lastUpdate.Profile.ShortName == nil || *repo.lastUpdate.Profile.ShortName != shortName {
+			t.Fatalf("expected update input forwarded")
+		}
+		repo.updateErr = repoErr
+		if err := svc.UpdateContact(ctx, in); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("delete success and error", func(t *testing.T) {
+		repo := &mockContactRepo{}
+		svc := NewContactService(repo, nil)
+		if err := svc.DeleteContact(ctx, userID); err != nil {
+			t.Fatalf("unexpected delete error: %v", err)
+		}
+		if string(repo.lastDeleteID) != string(userID) {
+			t.Fatalf("expected delete id forwarded")
+		}
+		repo.deleteErr = repoErr
+		if err := svc.DeleteContact(ctx, userID); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("status success and error", func(t *testing.T) {
+		repo := &mockContactRepo{}
+		svc := NewContactService(repo, nil)
+		if err := svc.UpdateContactStatus(ctx, userID, true); err != nil {
+			t.Fatalf("unexpected status error: %v", err)
+		}
+		if string(repo.lastStatusID) != string(userID) || !repo.lastStatusIsActive {
+			t.Fatalf("expected status args forwarded")
+		}
+		repo.updateStatusErr = repoErr
+		if err := svc.UpdateContactStatus(ctx, userID, true); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("role success and error", func(t *testing.T) {
+		repo := &mockContactRepo{}
+		svc := NewContactService(repo, nil)
+		if err := svc.UpdateContactRole(ctx, userID, "pilot"); err != nil {
+			t.Fatalf("unexpected role error: %v", err)
+		}
+		if string(repo.lastRoleID) != string(userID) || repo.lastRoleCode != "pilot" {
+			t.Fatalf("expected role args forwarded")
+		}
+		repo.updateRoleErr = repoErr
+		if err := svc.UpdateContactRole(ctx, userID, "pilot"); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("pilot category success and error", func(t *testing.T) {
+		repo := &mockContactRepo{}
+		svc := NewContactService(repo, nil)
+		if err := svc.UpdatePilotCategory(ctx, userID, "regular"); err != nil {
+			t.Fatalf("unexpected pilot category error: %v", err)
+		}
+		if string(repo.lastPilotID) != string(userID) || repo.lastCategory != "regular" {
+			t.Fatalf("expected pilot category args forwarded")
+		}
+		repo.updatePilotErr = repoErr
+		if err := svc.UpdatePilotCategory(ctx, userID, "regular"); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("license success and error", func(t *testing.T) {
+		repo := &mockContactRepo{}
+		svc := NewContactService(repo, nil)
+		if err := svc.UpdateLicense(ctx, userID, &licenseNo); err != nil {
+			t.Fatalf("unexpected license error: %v", err)
+		}
+		if string(repo.lastLicenseID) != string(userID) || repo.lastLicenseNo == nil || *repo.lastLicenseNo != licenseNo {
+			t.Fatalf("expected license args forwarded")
+		}
+		repo.updateLicenseErr = repoErr
+		if err := svc.UpdateLicense(ctx, userID, &licenseNo); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("chief flags success and error", func(t *testing.T) {
+		repo := &mockContactRepo{}
+		svc := NewContactService(repo, nil)
+		patch := contact.ProfilePatch{ShortName: &shortName}
+		if err := svc.UpdateChiefFlags(ctx, userID, patch); err != nil {
+			t.Fatalf("unexpected chief flags error: %v", err)
+		}
+		if string(repo.lastChiefID) != string(userID) || repo.lastChiefPatch.ShortName == nil || *repo.lastChiefPatch.ShortName != shortName {
+			t.Fatalf("expected chief flags args forwarded")
+		}
+		repo.updateChiefFlagsErr = repoErr
+		if err := svc.UpdateChiefFlags(ctx, userID, patch); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("responsible complaints success and error", func(t *testing.T) {
+		repo := &mockContactRepo{}
+		svc := NewContactService(repo, nil)
+		if err := svc.UpdateResponsibleComplaints(ctx, userID, true); err != nil {
+			t.Fatalf("unexpected responsible complaints error: %v", err)
+		}
+		if string(repo.lastResponsibleID) != string(userID) || !repo.lastResponsibleValue {
+			t.Fatalf("expected responsible complaints args forwarded")
+		}
+		repo.updateResponsibleErr = repoErr
+		if err := svc.UpdateResponsibleComplaints(ctx, userID, true); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+
+	t.Run("bulk update success and error", func(t *testing.T) {
+		repo := &mockContactRepo{bulkCount: 2}
+		svc := NewContactService(repo, nil)
+		ids := [][]byte{userID, uuidv7.MustBytes()}
+		count, err := svc.BulkUpdateStatus(ctx, ids, true)
+		if err != nil || count != 2 {
+			t.Fatalf("unexpected bulk update result: count=%d err=%v", count, err)
+		}
+		if len(repo.lastBulkIDs) != 2 || !repo.lastBulkActive {
+			t.Fatalf("expected bulk update args forwarded")
+		}
+		repo.bulkErr = repoErr
+		if _, err := svc.BulkUpdateStatus(ctx, ids, true); !errors.Is(err, repoErr) {
+			t.Fatalf("expected repo error, got %v", err)
+		}
+	})
+}
+
+func TestNormalizeContactSort(t *testing.T) {
+	cases := map[string]string{
+		"sortkey":    "users.is_active DESC, CASE WHEN users.is_active = 1 AND users.sortkey IS NOT NULL AND users.sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN users.is_active = 1 AND users.sortkey IS NOT NULL AND users.sortkey >= 0 THEN users.sortkey END ASC, users.first_name ASC",
+		"-sortkey":   "users.is_active DESC, CASE WHEN users.is_active = 1 AND users.sortkey IS NOT NULL AND users.sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN users.is_active = 1 AND users.sortkey IS NOT NULL AND users.sortkey >= 0 THEN users.sortkey END DESC, users.first_name ASC",
+		"note":       "COALESCE(pp.note, dp.note, arp.note, tp.note, fap.note, sp.note, '') ASC",
+		"-note":      "COALESCE(pp.note, dp.note, arp.note, tp.note, fap.note, sp.note, '') DESC",
+		"is_active":  "users.is_active ASC",
+		"-is_active": "users.is_active DESC",
+		"name":       "users.first_name ASC",
+		"email":      "users.email ASC",
+		"unknown":    "",
+		"":           "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeContactSort(in); got != want {
+			t.Fatalf("normalizeContactSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestContactServiceCheckSensitiveAction(t *testing.T) {
+	ctx := context.Background()
+	validUserID := uuidv7.MustBytes()
+	verifierErr := errors.New("pin verify failed")
+
+	svc := NewContactService(&mockContactRepo{}, nil)
+	if err := svc.CheckSensitiveAction(ctx, []byte("short"), "token", "action"); !errors.Is(err, ErrInvalidPINAction) {
+		t.Fatalf("expected invalid pin action for invalid user id, got %v", err)
+	}
+	if err := svc.CheckSensitiveAction(ctx, validUserID, "token", "action"); err == nil || err.Error() != "pin verifier not configured" {
+		t.Fatalf("expected pin verifier not configured error, got %v", err)
+	}
+
+	verifier := &mockPINVerifier{}
+	svc = NewContactService(&mockContactRepo{}, verifier)
+	if err := svc.CheckSensitiveAction(ctx, validUserID, "   ", "action"); !errors.Is(err, ErrInvalidPINAction) {
+		t.Fatalf("expected invalid pin action for empty token, got %v", err)
+	}
+	if err := svc.CheckSensitiveAction(ctx, validUserID, "token", "   "); !errors.Is(err, ErrInvalidPINAction) {
+		t.Fatalf("expected invalid pin action for empty action, got %v", err)
+	}
+
+	verifier.err = verifierErr
+	if err := svc.CheckSensitiveAction(ctx, validUserID, " token ", " action "); !errors.Is(err, verifierErr) {
+		t.Fatalf("expected verifier error, got %v", err)
+	}
+	if string(verifier.lastUserID) != string(validUserID) || verifier.lastAction != "action" || verifier.lastToken != "token" {
+		t.Fatalf("expected trimmed action/token forwarded")
+	}
+
+	verifier.err = nil
+	if err := svc.CheckSensitiveAction(ctx, validUserID, " token ", " action "); err != nil {
+		t.Fatalf("unexpected verifier error: %v", err)
+	}
+}
diff --git a/internal/service/cookies.go b/internal/service/cookies.go
new file mode 100644
index 0000000..110acfe
--- /dev/null
+++ b/internal/service/cookies.go
@@ -0,0 +1,29 @@
+package service
+
+import (
+	"strings"
+)
+
+// CookieValues returns all values for the given cookie name from a raw Cookie header.
+// It preserves header order so callers can try candidates until one validates.
+func CookieValues(rawHeader, cookieName string) []string {
+	rawHeader = strings.TrimSpace(rawHeader)
+	cookieName = strings.TrimSpace(cookieName)
+	if rawHeader == "" || cookieName == "" {
+		return nil
+	}
+
+	prefix := cookieName + "="
+	values := make([]string, 0, 2)
+	for _, part := range strings.Split(rawHeader, ";") {
+		part = strings.TrimSpace(part)
+		if !strings.HasPrefix(part, prefix) {
+			continue
+		}
+		value := strings.TrimSpace(strings.TrimPrefix(part, prefix))
+		if value != "" {
+			values = append(values, value)
+		}
+	}
+	return values
+}
diff --git a/internal/service/cookies_test.go b/internal/service/cookies_test.go
new file mode 100644
index 0000000..7c4dea6
--- /dev/null
+++ b/internal/service/cookies_test.go
@@ -0,0 +1,14 @@
+package service
+
+import "testing"
+
+func TestCookieValues(t *testing.T) {
+	raw := "foo=1; wucher_at=old-token; bar=2; wucher_at=new-token"
+	values := CookieValues(raw, "wucher_at")
+	if len(values) != 2 {
+		t.Fatalf("expected 2 cookie values, got %d", len(values))
+	}
+	if values[0] != "old-token" || values[1] != "new-token" {
+		t.Fatalf("unexpected cookie order: %#v", values)
+	}
+}
diff --git a/internal/service/dul_service.go b/internal/service/dul_service.go
new file mode 100644
index 0000000..68cfe7b
--- /dev/null
+++ b/internal/service/dul_service.go
@@ -0,0 +1,61 @@
+package service
+
+import (
+	"context"
+	"time"
+
+	"wucher/internal/domain/dul"
+)
+
+type DULService struct {
+	repo dul.Repository
+}
+
+func NewDULService(repo dul.Repository) *DULService {
+	return &DULService{repo: repo}
+}
+
+func (s *DULService) Create(ctx context.Context, row *dul.DUL) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *DULService) Update(ctx context.Context, row *dul.DUL) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *DULService) Delete(ctx context.Context, id []byte, actorID []byte) error {
+	row, err := s.repo.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+	if row == nil {
+		return nil
+	}
+	row.DeletedAt = ptrTimeDUL(time.Now().UTC())
+	row.DeletedBy = actorID
+	return s.repo.Delete(ctx, id)
+}
+
+func (s *DULService) GetByID(ctx context.Context, id []byte) (*dul.DUL, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *DULService) List(ctx context.Context, filter, sort string, limit, offset int, baseIDs [][]byte) ([]dul.DUL, int64, error) {
+	return s.repo.List(ctx, filter, sort, limit, offset, baseIDs)
+}
+
+func (s *DULService) WithTransaction(ctx context.Context, fn func(dul.Service) error) error {
+	if s == nil || fn == nil {
+		return nil
+	}
+	if txRepo, ok := s.repo.(dul.TransactionalRepository); ok {
+		return txRepo.WithTransaction(ctx, func(repo dul.Repository) error {
+			return fn(&DULService{repo: repo})
+		})
+	}
+	return fn(s)
+}
+
+func ptrTimeDUL(t time.Time) *time.Time {
+	return &t
+}
diff --git a/internal/service/duty_roster_service.go b/internal/service/duty_roster_service.go
new file mode 100644
index 0000000..3ebaed2
--- /dev/null
+++ b/internal/service/duty_roster_service.go
@@ -0,0 +1,1246 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+
+	dutyroster "wucher/internal/domain/duty_roster"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+)
+
+type DutyRosterService struct {
+	repo dutyroster.Repository
+}
+
+type rangeAssignment struct {
+	crew  dutyroster.DutyRosterCrew
+	start time.Time
+	end   time.Time
+}
+
+type DutyRosterValidationError struct {
+	Status  int
+	Title   string
+	Pointer string
+	Detail  string
+}
+
+func NewDutyRosterService(repo dutyroster.Repository) *DutyRosterService {
+	return &DutyRosterService{repo: repo}
+}
+
+func (s *DutyRosterService) Create(ctx context.Context, row *dutyroster.DutyRoster, crews []dutyroster.DutyRosterCrew) error {
+	normalizeDutyRosterWriteInput(row, crews)
+	return s.repo.InTx(ctx, func(txRepo dutyroster.TxRepository) error {
+		if err := txRepo.CreateHeader(ctx, row); err != nil {
+			return err
+		}
+
+		insertRows := prepareCrewRowsForRosterInsert(row.ID, crews)
+		for i := range insertRows {
+			if err := txRepo.InsertCrew(ctx, &insertRows[i]); err != nil {
+				return err
+			}
+		}
+		return s.addRangeAssignments(ctx, txRepo, row, crews)
+	})
+}
+
+func (s *DutyRosterService) Update(ctx context.Context, row *dutyroster.DutyRoster, crews []dutyroster.DutyRosterCrew) error {
+	normalizeDutyRosterWriteInput(row, crews)
+	return s.repo.InTx(ctx, func(txRepo dutyroster.TxRepository) error {
+		if _, err := txRepo.LockRosterByID(ctx, row.ID); err != nil {
+			return err
+		}
+
+		oldCrews := []dutyroster.DutyRosterCrew{}
+		if len(crews) > 0 {
+			var err error
+			oldCrews, err = txRepo.ListActiveCrewsByRosterID(ctx, row.ID)
+			if err != nil {
+				return err
+			}
+		}
+
+		if err := txRepo.UpdateHeader(ctx, row); err != nil {
+			return err
+		}
+		if len(crews) == 0 {
+			return nil
+		}
+
+		insertRows := prepareCrewRowsForRosterInsert(row.ID, crews)
+		replacedKeys := map[string]struct{}{}
+		for i := range insertRows {
+			replaceKey := replaceByUserKey(insertRows[i].RosterID, insertRows[i].RoleCode, insertRows[i].CrewType, insertRows[i].UserID)
+			if replaceKey != "" {
+				if _, ok := replacedKeys[replaceKey]; !ok {
+					if err := txRepo.SoftDeleteCrewByUser(ctx, insertRows[i].RosterID, insertRows[i].RoleCode, insertRows[i].CrewType, insertRows[i].UserID, row.UpdatedBy); err != nil {
+						return err
+					}
+					replacedKeys[replaceKey] = struct{}{}
+				}
+			}
+			exists, err := txRepo.CrewExists(ctx, insertRows[i])
+			if err != nil {
+				return err
+			}
+			if exists {
+				continue
+			}
+			if err := txRepo.InsertCrew(ctx, &insertRows[i]); err != nil {
+				return err
+			}
+		}
+		if err := s.addRangeAssignments(ctx, txRepo, row, crews); err != nil {
+			return err
+		}
+		return s.removeRangeAssignments(ctx, txRepo, row, oldCrews, crews)
+	})
+}
+
+func (s *DutyRosterService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.InTx(ctx, func(txRepo dutyroster.TxRepository) error {
+		if _, err := txRepo.LockRosterByID(ctx, id); err != nil {
+			return err
+		}
+		if err := txRepo.SoftDeleteHeader(ctx, id, deletedBy); err != nil {
+			return err
+		}
+		return txRepo.SoftDeleteCrewsByRosterID(ctx, id, deletedBy)
+	})
+}
+
+func (s *DutyRosterService) HardDelete(ctx context.Context, id []byte) error {
+	return s.repo.InTx(ctx, func(txRepo dutyroster.TxRepository) error {
+		if err := txRepo.HardDeleteCrewsByRosterID(ctx, id); err != nil {
+			return err
+		}
+		return txRepo.HardDeleteHeader(ctx, id)
+	})
+}
+
+func (s *DutyRosterService) DeleteCrews(ctx context.Context, id []byte, crews []dutyroster.DutyRosterCrew, deletedBy []byte) ([]dutyroster.DeletedCrewResult, error) {
+	if len(crews) == 0 {
+		return []dutyroster.DeletedCrewResult{}, nil
+	}
+	normalizeDutyRosterFilterInput(crews)
+	collected := make(map[string]dutyroster.DeletedCrewResult)
+	err := s.repo.InTx(ctx, func(txRepo dutyroster.TxRepository) error {
+		header, err := txRepo.LockRosterByID(ctx, id)
+		if err != nil {
+			return err
+		}
+		baseDate := dateOnlyUTC(header.DutyDate)
+		for i := range crews {
+			dates := []time.Time{baseDate}
+			if isRoleRangeAssignable(crews[i].RoleCode) && crews[i].DateStart != nil && crews[i].DateEnd != nil {
+				dates = expandDateRange(*crews[i].DateStart, *crews[i].DateEnd)
+			}
+			for _, d := range dates {
+				rosterIDs, err := txRepo.FindRosterIDsByBaseDate(ctx, header.BaseID, d)
+				if err != nil {
+					return err
+				}
+				if len(rosterIDs) == 0 {
+					continue
+				}
+				rows, err := txRepo.MatchCrewByFilter(ctx, rosterIDs, crews[i])
+				if err != nil {
+					return err
+				}
+				if len(rows) == 0 {
+					continue
+				}
+				for j := range rows {
+					k := fmt.Sprintf("%x", rows[j].ID)
+					if _, ok := collected[k]; !ok {
+						collected[k] = rows[j]
+					}
+				}
+				if err := txRepo.SoftDeleteCrewRows(ctx, rows, deletedBy); err != nil {
+					return err
+				}
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	out := make([]dutyroster.DeletedCrewResult, 0, len(collected))
+	for _, v := range collected {
+		out = append(out, v)
+	}
+	return out, nil
+}
+
+func (s *DutyRosterService) GetBaseDefaultShift(ctx context.Context, baseID []byte, baseType string) (string, error) {
+	return s.repo.GetBaseDefaultShift(ctx, baseID, baseType)
+}
+
+func (s *DutyRosterService) ResolveBaseDefaultShiftRange(ctx context.Context, baseID []byte, baseType string) (string, string, error) {
+	if len(baseID) == 0 {
+		return "", "", nil
+	}
+	raw, err := s.repo.GetBaseDefaultShift(ctx, baseID, baseType)
+	if err != nil {
+		return "", "", err
+	}
+	start, end := ParseDutyRosterShiftRange(raw)
+	return start, end, nil
+}
+
+func (s *DutyRosterService) GetHeaderByID(ctx context.Context, id []byte) (*dutyroster.HeaderView, error) {
+	return s.repo.GetHeaderByID(ctx, id)
+}
+
+func (s *DutyRosterService) GetHeaderByIDByBaseType(ctx context.Context, id []byte, baseType string) (*dutyroster.HeaderView, error) {
+	return s.repo.GetHeaderByIDByBaseType(ctx, id, baseType)
+}
+
+func (s *DutyRosterService) GetCrewsByRosterIDs(ctx context.Context, rosterIDs [][]byte) ([]dutyroster.CrewView, error) {
+	return s.repo.GetCrewsByRosterIDs(ctx, rosterIDs)
+}
+
+func (s *DutyRosterService) ListHeadersByRange(ctx context.Context, baseID []byte, from, to time.Time) ([]dutyroster.HeaderView, error) {
+	return s.repo.ListHeadersByRange(ctx, baseID, from, to)
+}
+
+func (s *DutyRosterService) ListHeadersByRangeByBaseType(ctx context.Context, baseID []byte, from, to time.Time, baseType string) ([]dutyroster.HeaderView, error) {
+	return s.repo.ListHeadersByRangeByBaseType(ctx, baseID, from, to, baseType)
+}
+
+func (s *DutyRosterService) ListHEMSBases(ctx context.Context, baseID []byte) ([]dutyroster.BaseView, error) {
+	return s.repo.ListHEMSBases(ctx, baseID)
+}
+
+func (s *DutyRosterService) ListBasesByType(ctx context.Context, baseID []byte, baseType string) ([]dutyroster.BaseView, error) {
+	return s.repo.ListBasesByType(ctx, baseID, baseType)
+}
+
+// ===== Write-path internals: normalization + persistence helpers =====
+func normalizeDutyRosterWriteInput(row *dutyroster.DutyRoster, crews []dutyroster.DutyRosterCrew) {
+	for i := range crews {
+		crews[i].ShiftStart = normalizeCrewShiftForWrite(crews[i].ShiftStart)
+		crews[i].ShiftEnd = normalizeCrewShiftForWrite(crews[i].ShiftEnd)
+	}
+}
+
+func normalizeDutyRosterFilterInput(crews []dutyroster.DutyRosterCrew) {
+	for i := range crews {
+		crews[i].ShiftStart = normalizeCrewShiftForFilter(crews[i].ShiftStart)
+		crews[i].ShiftEnd = normalizeCrewShiftForFilter(crews[i].ShiftEnd)
+	}
+}
+
+func normalizeRosterShiftForWrite(v string) string {
+	s := strings.TrimSpace(v)
+	if s == "" {
+		return ""
+	}
+	if len(s) == 8 {
+		return "2000-01-01 " + s
+	}
+	if len(s) == 5 {
+		return "2000-01-01 " + s + ":00"
+	}
+	return s
+}
+
+func normalizeCrewShiftForWrite(v string) string {
+	s := strings.TrimSpace(v)
+	if s == "" {
+		return "2000-01-01 00:00:00"
+	}
+	return normalizeRosterShiftForWrite(s)
+}
+
+func normalizeCrewShiftForFilter(v string) string {
+	s := strings.TrimSpace(v)
+	if s == "" {
+		return ""
+	}
+	return normalizeRosterShiftForWrite(s)
+}
+
+func prepareCrewRowsForRosterInsert(rosterID []byte, crews []dutyroster.DutyRosterCrew) []dutyroster.DutyRosterCrew {
+	if len(crews) == 0 {
+		return nil
+	}
+	out := make([]dutyroster.DutyRosterCrew, 0, len(crews))
+	for i := range crews {
+		row := crews[i]
+		row.RosterID = append([]byte(nil), rosterID...)
+		out = append(out, row)
+	}
+	return out
+}
+
+// Multi-day assignment orchestration.
+func (s *DutyRosterService) addRangeAssignments(
+	ctx context.Context,
+	txRepo dutyroster.TxRepository,
+	row *dutyroster.DutyRoster,
+	crews []dutyroster.DutyRosterCrew,
+) error {
+	assignments := collectRangeAssignments(crews)
+	if len(assignments) == 0 {
+		return nil
+	}
+	currentDate := dateOnlyUTC(row.DutyDate)
+	replacedKeys := map[string]struct{}{}
+	for i := range assignments {
+		dates := expandDateRange(assignments[i].start, assignments[i].end)
+		for _, d := range dates {
+			if d.Equal(currentDate) {
+				continue
+			}
+			rosterID, err := s.ensureRosterForDate(ctx, txRepo, row, d)
+			if err != nil {
+				return err
+			}
+			insert := assignments[i].crew
+			insert.RosterID = append([]byte(nil), rosterID...)
+			replaceKey := replaceByUserKey(insert.RosterID, insert.RoleCode, insert.CrewType, insert.UserID)
+			if replaceKey != "" {
+				if _, ok := replacedKeys[replaceKey]; !ok {
+					if err := txRepo.SoftDeleteCrewByUser(ctx, insert.RosterID, insert.RoleCode, insert.CrewType, insert.UserID, row.UpdatedBy); err != nil {
+						return err
+					}
+					replacedKeys[replaceKey] = struct{}{}
+				}
+			}
+			exists, err := txRepo.CrewExists(ctx, insert)
+			if err != nil {
+				return err
+			}
+			if exists {
+				continue
+			}
+			if err := txRepo.InsertCrew(ctx, &insert); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+func (s *DutyRosterService) removeRangeAssignments(
+	ctx context.Context,
+	txRepo dutyroster.TxRepository,
+	row *dutyroster.DutyRoster,
+	oldCrews []dutyroster.DutyRosterCrew,
+	newCrews []dutyroster.DutyRosterCrew,
+) error {
+	oldAssignments := collectRangeAssignments(oldCrews)
+	if len(oldAssignments) == 0 {
+		return nil
+	}
+	newAssignments := collectRangeAssignments(newCrews)
+	newByKey := make(map[string][]rangeAssignment)
+	for i := range newAssignments {
+		k := assignmentKey(newAssignments[i].crew)
+		newByKey[k] = append(newByKey[k], newAssignments[i])
+	}
+	for i := range oldAssignments {
+		k := assignmentKey(oldAssignments[i].crew)
+		keep := map[string]struct{}{}
+		for _, n := range newByKey[k] {
+			for _, d := range expandDateRange(n.start, n.end) {
+				keep[d.Format("2006-01-02")] = struct{}{}
+			}
+		}
+		for _, d := range expandDateRange(oldAssignments[i].start, oldAssignments[i].end) {
+			if _, ok := keep[d.Format("2006-01-02")]; ok {
+				continue
+			}
+			if err := txRepo.SoftDeleteCrewForDate(ctx, row.BaseID, d, oldAssignments[i].crew, row.UpdatedBy); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+func (s *DutyRosterService) ensureRosterForDate(
+	ctx context.Context,
+	txRepo dutyroster.TxRepository,
+	source *dutyroster.DutyRoster,
+	dutyDate time.Time,
+) ([]byte, error) {
+	date := dateOnlyUTC(dutyDate)
+	id, err := txRepo.FindRosterIDByBaseDate(ctx, source.BaseID, date)
+	if err != nil {
+		return nil, err
+	}
+	if len(id) > 0 {
+		if _, err := txRepo.LockRosterByID(ctx, id); err != nil {
+			return nil, err
+		}
+		return id, nil
+	}
+	newRow := &dutyroster.DutyRoster{
+		BaseID:    append([]byte(nil), source.BaseID...),
+		DutyDate:  date,
+		CreatedBy: append([]byte(nil), source.CreatedBy...),
+		UpdatedBy: append([]byte(nil), source.UpdatedBy...),
+	}
+	if err := txRepo.CreateHeader(ctx, newRow); err != nil {
+		id, fetchErr := txRepo.FindRosterIDByBaseDate(ctx, source.BaseID, date)
+		if fetchErr == nil && len(id) > 0 {
+			if _, lockErr := txRepo.LockRosterByID(ctx, id); lockErr != nil {
+				return nil, lockErr
+			}
+			return id, nil
+		}
+		if fetchErr != nil {
+			return nil, fetchErr
+		}
+		return nil, err
+	}
+	return newRow.ID, nil
+}
+
+func collectRangeAssignments(crews []dutyroster.DutyRosterCrew) []rangeAssignment {
+	out := make([]rangeAssignment, 0)
+	for i := range crews {
+		c := crews[i]
+		if !isRoleRangeAssignable(c.RoleCode) {
+			continue
+		}
+		if c.DateStart == nil || c.DateEnd == nil {
+			continue
+		}
+		start := dateOnlyUTC(*c.DateStart)
+		end := dateOnlyUTC(*c.DateEnd)
+		if end.Before(start) {
+			continue
+		}
+		out = append(out, rangeAssignment{crew: c, start: start, end: end})
+	}
+	return out
+}
+
+func assignmentKey(c dutyroster.DutyRosterCrew) string {
+	return fmt.Sprintf(
+		"%s|%x|%s|%s",
+		strings.ToLower(strings.TrimSpace(c.RoleCode)),
+		c.UserID,
+		strings.ToLower(strings.TrimSpace(c.CrewType)),
+		strings.ToLower(strings.TrimSpace(c.NameLabel)),
+	)
+}
+
+func replaceByUserKey(rosterID []byte, roleCode, crewType string, userID []byte) string {
+	if len(rosterID) == 0 || len(userID) == 0 {
+		return ""
+	}
+	return fmt.Sprintf(
+		"%x|%s|%s|%x",
+		rosterID,
+		strings.ToLower(strings.TrimSpace(roleCode)),
+		strings.ToLower(strings.TrimSpace(crewType)),
+		userID,
+	)
+}
+
+func dateOnlyUTC(t time.Time) time.Time {
+	return time.Date(t.UTC().Year(), t.UTC().Month(), t.UTC().Day(), 0, 0, 0, 0, time.UTC)
+}
+
+func expandDateRange(start, end time.Time) []time.Time {
+	start = dateOnlyUTC(start)
+	end = dateOnlyUTC(end)
+	if end.Before(start) {
+		return nil
+	}
+	out := make([]time.Time, 0, int(end.Sub(start).Hours()/24)+1)
+	for d := start; !d.After(end); d = d.AddDate(0, 0, 1) {
+		out = append(out, d)
+	}
+	return out
+}
+
+func isRoleRangeAssignable(roleCode string) bool {
+	switch strings.ToLower(strings.TrimSpace(roleCode)) {
+	case "other_person", "other":
+		return false
+	default:
+		return true
+	}
+}
+
+// ===== Request parsing + validation helpers =====
+func BuildDutyRosterCrewRows(details requestdto.DutyRosterDetailsInput, actor []byte) ([]dutyroster.DutyRosterCrew, *DutyRosterValidationError) {
+	out := make([]dutyroster.DutyRosterCrew, 0)
+	seen := map[string]struct{}{}
+
+	appendNonPilotRole := func(roleCode string, items []requestdto.DutyRosterCrewInput) *DutyRosterValidationError {
+		for _, in := range items {
+			row, errObj := buildDutyRosterCrewRow(
+				actor,
+				roleCode,
+				"main",
+				in.ID,
+				"",
+				"",
+				"",
+				in.ShiftDate,
+				true,
+			)
+			if errObj != nil {
+				return errObj
+			}
+			if errObj := appendDutyRosterCrewRow(&out, seen, row); errObj != nil {
+				return errObj
+			}
+		}
+		return nil
+	}
+	appendOtherPersonRole := func(items []requestdto.DutyRosterOtherPersonInput) *DutyRosterValidationError {
+		for _, in := range items {
+			if strings.TrimSpace(in.Name) == "" {
+				return &DutyRosterValidationError{
+					Pointer: "/data/attributes/roster_detail/other_person",
+					Detail:  "other_person name is required",
+				}
+			}
+			row := dutyroster.DutyRosterCrew{
+				RoleCode:    "other_person",
+				CrewType:    "main",
+				NameLabel:   strings.TrimSpace(in.Name),
+				MobilePhone: strings.TrimSpace(in.MobilePhone),
+				Email:       strings.TrimSpace(in.Email),
+				ShiftStart:  "",
+				ShiftEnd:    "",
+				CreatedBy:   actor,
+				UpdatedBy:   actor,
+			}
+			if errObj := appendDutyRosterCrewRow(&out, seen, row); errObj != nil {
+				return errObj
+			}
+		}
+		return nil
+	}
+
+	appendPilotRole := func(items []requestdto.DutyRosterPilotCrewInput) *DutyRosterValidationError {
+		for _, in := range items {
+			crewType := normalizeCrewType(in.CrewType)
+			row, errObj := buildDutyRosterCrewRow(
+				actor,
+				"pilot",
+				crewType,
+				in.ID,
+				"",
+				"",
+				"",
+				in.ShiftDate,
+				true,
+			)
+			if errObj != nil {
+				return errObj
+			}
+			if crewType == "additional" {
+				row.FlightInstructor = in.FlightInstructor
+				row.LineChecker = in.LineChecker
+				row.Supervisor = in.Supervisor
+				row.Examiner = in.Examiner
+				row.CoPilot = in.CoPilot
+			}
+			if errObj := appendDutyRosterCrewRow(&out, seen, row); errObj != nil {
+				return errObj
+			}
+		}
+		return nil
+	}
+
+	if err := appendPilotRole(details.Pilot); err != nil {
+		return nil, err
+	}
+	if err := appendNonPilotRole("doctor", details.Doctor); err != nil {
+		return nil, err
+	}
+	if err := appendNonPilotRole("rescuer", details.Rescuer); err != nil {
+		return nil, err
+	}
+	if err := appendNonPilotRole("helper", details.Helper); err != nil {
+		return nil, err
+	}
+	if err := appendOtherPersonRole(details.OtherPerson); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func buildDutyRosterCrewRow(
+	actor []byte,
+	roleCode string,
+	crewType string,
+	id string,
+	name string,
+	mobilePhone string,
+	email string,
+	shiftDate *requestdto.DutyRosterShiftDate,
+	allowUserID bool,
+) (dutyroster.DutyRosterCrew, *DutyRosterValidationError) {
+	row := dutyroster.DutyRosterCrew{
+		RoleCode:    roleCode,
+		CrewType:    crewType,
+		NameLabel:   strings.TrimSpace(name),
+		MobilePhone: strings.TrimSpace(mobilePhone),
+		Email:       strings.TrimSpace(email),
+		ShiftStart:  "",
+		ShiftEnd:    "",
+		CreatedBy:   actor,
+		UpdatedBy:   actor,
+	}
+	if allowUserID && strings.TrimSpace(id) != "" {
+		parsedID, err := uuidv7.ParseString(strings.TrimSpace(id))
+		if err != nil {
+			return dutyroster.DutyRosterCrew{}, &DutyRosterValidationError{
+				Pointer: "/data/attributes/roster_detail",
+				Detail:  "crew id is invalid UUID",
+			}
+		}
+		row.UserID = parsedID
+	}
+	if errObj := applyCrewShiftDateInput(&row, shiftDate); errObj != nil {
+		return dutyroster.DutyRosterCrew{}, errObj
+	}
+	return row, nil
+}
+
+func appendDutyRosterCrewRow(out *[]dutyroster.DutyRosterCrew, seen map[string]struct{}, row dutyroster.DutyRosterCrew) *DutyRosterValidationError {
+	dupKey := buildDutyRosterCrewDupKey(row)
+	if _, ok := seen[dupKey]; ok {
+		return &DutyRosterValidationError{
+			Pointer: "/data/attributes/roster_detail",
+			Detail:  "duplicate crew assignment in request payload",
+		}
+	}
+	seen[dupKey] = struct{}{}
+	*out = append(*out, row)
+	return nil
+}
+
+func validateDutyRosterDeleteCrews(crews []dutyroster.DutyRosterCrew) *DutyRosterValidationError {
+	for i := range crews {
+		if !roleNeedsShiftDateForDelete(crews[i].RoleCode) {
+			continue
+		}
+		hasStart := crews[i].DateStart != nil
+		hasEnd := crews[i].DateEnd != nil
+		if hasStart != hasEnd {
+			return &DutyRosterValidationError{
+				Pointer: "/data/attributes/roster_detail",
+				Detail:  "shift_date.date_start and shift_date.date_end must be provided together",
+			}
+		}
+		if hasStart && crews[i].DateEnd.Before(*crews[i].DateStart) {
+			return &DutyRosterValidationError{
+				Pointer: "/data/attributes/roster_detail",
+				Detail:  "shift_date.date_end must be >= shift_date.date_start",
+			}
+		}
+	}
+	return nil
+}
+
+func applyCrewShiftDateInput(row *dutyroster.DutyRosterCrew, in *requestdto.DutyRosterShiftDate) *DutyRosterValidationError {
+	if in == nil {
+		return nil
+	}
+	if strings.TrimSpace(in.DateStart) != "" {
+		d, err := parseDateOnlyForCrew(in.DateStart)
+		if err != nil {
+			return &DutyRosterValidationError{
+				Pointer: "/data/attributes/roster_detail",
+				Detail:  "ERR_DUTY_ROSTER_SHIFT_DATE_START_FORMAT",
+			}
+		}
+		row.DateStart = &d
+	}
+	if strings.TrimSpace(in.DateEnd) != "" {
+		d, err := parseDateOnlyForCrew(in.DateEnd)
+		if err != nil {
+			return &DutyRosterValidationError{
+				Pointer: "/data/attributes/roster_detail",
+				Detail:  "ERR_DUTY_ROSTER_SHIFT_DATE_END_FORMAT",
+			}
+		}
+		row.DateEnd = &d
+	}
+	return nil
+}
+
+func buildDutyRosterCrewDupKey(row dutyroster.DutyRosterCrew) string {
+	return strings.ToLower(strings.TrimSpace(row.RoleCode)) + "|" +
+		strings.ToLower(strings.TrimSpace(row.CrewType)) + "|" +
+		uuidNoCtx(row.UserID) + "|" +
+		strings.ToLower(strings.TrimSpace(row.NameLabel)) + "|" +
+		dateToString(row.DateStart) + "|" +
+		dateToString(row.DateEnd) + "|" +
+		strings.TrimSpace(row.ShiftStart) + "|" +
+		strings.TrimSpace(row.ShiftEnd)
+}
+
+func normalizeClockOrDefaultForCrew(v, def string) string {
+	s := strings.TrimSpace(v)
+	if s == "" {
+		return def
+	}
+	if len(s) == 5 {
+		return s + ":00"
+	}
+	return s
+}
+
+func normalizeClockInputForCrew(v, def, pointer string) (string, *DutyRosterValidationError) {
+	out := normalizeClockOrDefaultForCrew(v, def)
+	if strings.TrimSpace(out) == "" {
+		return out, nil
+	}
+	if _, err := time.Parse("15:04:05", out); err != nil {
+		return "", &DutyRosterValidationError{
+			Pointer: pointer,
+			Detail:  "time must be HH:MM or HH:MM:SS",
+		}
+	}
+	return out, nil
+}
+
+func NormalizeDutyRosterClockInput(v, def, pointer string) (string, *DutyRosterValidationError) {
+	return normalizeClockInputForCrew(v, def, pointer)
+}
+
+// ===== Date/time parsing helpers used by handlers =====
+func ParseDutyRosterShiftRange(raw string) (string, string) {
+	tokens := extractClockTokensForShift(raw)
+	if len(tokens) == 0 {
+		return "", ""
+	}
+	start := normalizeClockOrDefaultForCrew(tokens[0], "")
+	if _, err := time.Parse("15:04:05", start); err != nil {
+		start = ""
+	}
+	end := start
+	if len(tokens) > 1 {
+		end = normalizeClockOrDefaultForCrew(tokens[1], "")
+		if _, err := time.Parse("15:04:05", end); err != nil {
+			end = ""
+		}
+	}
+	return start, end
+}
+
+func ResolveDutyRosterShiftDefaultsForUpdate(ctx context.Context, svc dutyroster.Service, baseID []byte, baseType, currentShiftStart, currentShiftEnd string) (string, string, error) {
+	defaultShiftStart := strings.TrimSpace(currentShiftStart)
+	defaultShiftEnd := strings.TrimSpace(currentShiftEnd)
+	if defaultShiftStart != "" && defaultShiftEnd != "" {
+		return defaultShiftStart, defaultShiftEnd, nil
+	}
+
+	baseShiftStart, baseShiftEnd, err := svc.ResolveBaseDefaultShiftRange(ctx, baseID, baseType)
+	if err != nil {
+		return "", "", err
+	}
+	if defaultShiftStart == "" {
+		defaultShiftStart = baseShiftStart
+	}
+	if defaultShiftEnd == "" {
+		defaultShiftEnd = baseShiftEnd
+	}
+	return defaultShiftStart, defaultShiftEnd, nil
+}
+
+func extractClockTokensForShift(raw string) []string {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return nil
+	}
+	out := make([]string, 0, 2)
+	for i := 0; i < len(s) && len(out) < 2; i++ {
+		if i+5 > len(s) || !isDigitForShift(s[i]) || !isDigitForShift(s[i+1]) || s[i+2] != ':' || !isDigitForShift(s[i+3]) || !isDigitForShift(s[i+4]) {
+			continue
+		}
+		token := s[i : i+5]
+		if i+8 <= len(s) && s[i+5] == ':' && isDigitForShift(s[i+6]) && isDigitForShift(s[i+7]) {
+			token = s[i : i+8]
+		}
+		out = append(out, token)
+	}
+	return out
+}
+
+func isDigitForShift(b byte) bool {
+	return b >= '0' && b <= '9'
+}
+
+func ParseDutyRosterDateRangeOrDefault(fromRaw, toRaw string, now time.Time) (time.Time, time.Time, *DutyRosterValidationError) {
+	defaultFrom := time.Date(now.UTC().Year(), now.UTC().Month(), 1, 0, 0, 0, 0, time.UTC)
+	defaultTo := defaultFrom.AddDate(0, 1, -1)
+
+	fromText := strings.TrimSpace(fromRaw)
+	toText := strings.TrimSpace(toRaw)
+	from := defaultFrom
+	to := defaultTo
+
+	if fromText != "" {
+		parsedFrom, err := parseDateOnlyForCrew(fromText)
+		if err != nil {
+			return time.Time{}, time.Time{}, &DutyRosterValidationError{
+				Pointer: "/query/from",
+				Detail:  "from must be YYYY-MM-DD",
+			}
+		}
+		from = parsedFrom
+	}
+	if toText != "" {
+		parsedTo, err := parseDateOnlyForCrew(toText)
+		if err != nil {
+			return time.Time{}, time.Time{}, &DutyRosterValidationError{
+				Pointer: "/query/to",
+				Detail:  "to must be YYYY-MM-DD",
+			}
+		}
+		to = parsedTo
+	}
+	return from, to, nil
+}
+
+func ParseDutyRosterDateOnly(v string) (time.Time, error) {
+	return parseDateOnlyForCrew(v)
+}
+
+// ===== Request body decoder helpers =====
+func BuildDutyRosterDeleteCrews(raw []byte, actor []byte) ([]dutyroster.DutyRosterCrew, *DutyRosterValidationError) {
+	trimmed := bytes.TrimSpace(raw)
+	if len(trimmed) == 0 || bytes.Equal(trimmed, []byte("{}")) {
+		return nil, nil
+	}
+	var req struct {
+		Data struct {
+			Attributes struct {
+				Detail *requestdto.DutyRosterDetailsInput `json:"roster_detail,omitempty"`
+			} `json:"attributes"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(trimmed, &req); err != nil {
+		return nil, &DutyRosterValidationError{
+			Pointer: "/data",
+			Detail:  "invalid delete payload",
+		}
+	}
+	detail := req.Data.Attributes.Detail
+	if detail == nil {
+		return nil, nil
+	}
+	crews, crewErr := BuildDutyRosterCrewRows(*detail, actor)
+	if crewErr != nil {
+		return nil, crewErr
+	}
+	if errObj := validateDutyRosterDeleteCrews(crews); errObj != nil {
+		return nil, errObj
+	}
+	return crews, nil
+}
+
+func isDutyRosterDetailsInputEmpty(d requestdto.DutyRosterDetailsInput) bool {
+	return len(d.Pilot) == 0 &&
+		len(d.Doctor) == 0 &&
+		len(d.Rescuer) == 0 &&
+		len(d.Helper) == 0 &&
+		len(d.OtherPerson) == 0
+}
+
+func parseDateOnlyForCrew(v string) (time.Time, error) {
+	return time.ParseInLocation("2006-01-02", strings.TrimSpace(v), time.UTC)
+}
+
+func normalizeCrewType(v string) string {
+	s := strings.ToLower(strings.TrimSpace(v))
+	if s == "additional" {
+		return "additional"
+	}
+	return "main"
+}
+
+func roleNeedsShiftDateForDelete(roleCode string) bool {
+	switch strings.ToLower(strings.TrimSpace(roleCode)) {
+	case "other_person", "other":
+		return false
+	default:
+		return true
+	}
+}
+
+func dateToString(t *time.Time) string {
+	if t == nil || t.IsZero() {
+		return ""
+	}
+	return t.UTC().Format("2006-01-02")
+}
+
+// uuidNoCtx converts a UUID byte slice to string without any context-based lookup.
+// Used only for internal deduplication keys where user names are not needed.
+func uuidNoCtx(id []byte) string {
+	if len(id) == 0 {
+		return ""
+	}
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		return ""
+	}
+	return s
+}
+
+func uuidStringOrEmpty(ctx context.Context, id []byte) string {
+	if len(id) == 0 {
+		return ""
+	}
+	// Try GlobalUserNameGetter first.
+	if name := getLastNameFromServiceGetter(ctx, id); name != "" {
+		return name
+	}
+	return uuidNoCtx(id)
+}
+
+func getLastNameFromServiceGetter(ctx context.Context, id []byte) string {
+	if name := userctx.GetDisplayName(ctx, id); name != "" {
+		return name
+	}
+	return ""
+}
+
+// ===== DTO/resource mapping helpers =====
+func DutyRosterResource(ctx context.Context, header dutyroster.HeaderView, crews []dutyroster.CrewView) responsedto.DutyRosterResource {
+	details := responsedto.DutyRosterDetailsResponse{
+		Pilot:       []responsedto.DutyRosterPilotCrew{},
+		Doctor:      []responsedto.DutyRosterCrew{},
+		Rescuer:     []responsedto.DutyRosterCrew{},
+		Helper:      []responsedto.DutyRosterCrew{},
+		OtherPerson: []responsedto.DutyRosterCrew{},
+	}
+
+	for i := range crews {
+		baseItem := responsedto.DutyRosterCrew{
+			ID:          firstNonEmpty(uuidNoCtx(crews[i].UserID), uuidNoCtx(crews[i].ID)),
+			Name:        strings.TrimSpace(crews[i].Name),
+			Role:        strings.TrimSpace(crews[i].Role),
+			MobilePhone: strings.TrimSpace(crews[i].MobilePhone),
+			Email:       strings.TrimSpace(crews[i].Email),
+		}
+		if crews[i].DateStart != nil || crews[i].DateEnd != nil {
+			baseItem.ShiftDate = &responsedto.DutyRosterShiftDate{DateStart: dateToString(crews[i].DateStart), DateEnd: dateToString(crews[i].DateEnd)}
+		}
+		switch roleBucket(crews[i].RoleCode) {
+		case "pilot":
+			applyEffectiveCrewShiftTime(&baseItem, crews[i], header)
+			pilotItem := responsedto.DutyRosterPilotCrew{
+				ID:          baseItem.ID,
+				Name:        baseItem.Name,
+				Role:        baseItem.Role,
+				CrewType:    strings.TrimSpace(crews[i].CrewType),
+				MobilePhone: baseItem.MobilePhone,
+				Email:       baseItem.Email,
+				ShiftDate:   baseItem.ShiftDate,
+			}
+			if strings.EqualFold(strings.TrimSpace(crews[i].CrewType), "additional") {
+				pilotItem.FlightInstructor = boolPtrIfTrue(crews[i].FlightInstructor)
+				pilotItem.LineChecker = boolPtrIfTrue(crews[i].LineChecker)
+				pilotItem.Supervisor = boolPtrIfTrue(crews[i].Supervisor)
+				pilotItem.Examiner = boolPtrIfTrue(crews[i].Examiner)
+				pilotItem.CoPilot = boolPtrIfTrue(crews[i].CoPilot)
+			}
+			details.Pilot = append(details.Pilot, pilotItem)
+		case "doctor":
+			applyEffectiveCrewShiftTime(&baseItem, crews[i], header)
+			details.Doctor = append(details.Doctor, baseItem)
+		case "rescuer":
+			applyEffectiveCrewShiftTime(&baseItem, crews[i], header)
+			details.Rescuer = append(details.Rescuer, baseItem)
+		case "helper":
+			applyEffectiveCrewShiftTime(&baseItem, crews[i], header)
+			details.Helper = append(details.Helper, baseItem)
+		default:
+			baseItem.ShiftDate = nil
+			baseItem.ShiftTime = nil
+			details.OtherPerson = append(details.OtherPerson, baseItem)
+		}
+	}
+
+	return responsedto.DutyRosterResource{
+		Type: "duty_roster",
+		ID:   uuidNoCtx(header.ID),
+		Attributes: responsedto.DutyRosterAttributes{
+			Bases: responsedto.DutyRosterBaseInfo{
+				ID:               uuidNoCtx(header.BaseID),
+				Type:             "hems",
+				BaseName:         header.BaseName, 
+				BaseAbbreviation: header.BaseAbbreviation,
+			},
+			Helicopter: buildDutyRosterHelicopterFromHeader(header),
+			DutyDate:   header.DutyDate.UTC().Format("2006-01-02"),
+			ShiftTime:  responsedto.DutyRosterShiftTime{ShiftStart: header.ShiftStart, ShiftEnd: header.ShiftEnd},
+			Detail:     details,
+			CreatedBy:  uuidStringOrEmpty(ctx, header.CreatedBy),
+			CreatedAt:  header.CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedAt:  header.UpdatedAt.UTC().Format(time.RFC3339),
+		},
+	}
+}
+
+func applyEffectiveCrewShiftTime(baseItem *responsedto.DutyRosterCrew, crew dutyroster.CrewView, header dutyroster.HeaderView) {
+	effectiveShiftStart := strings.TrimSpace(crew.ShiftStart)
+	effectiveShiftEnd := strings.TrimSpace(crew.ShiftEnd)
+	if effectiveShiftStart == "" {
+		effectiveShiftStart = header.ShiftStart
+	}
+	if effectiveShiftEnd == "" {
+		effectiveShiftEnd = header.ShiftEnd
+	}
+	if effectiveShiftStart == "" && effectiveShiftEnd == "" {
+		return
+	}
+	baseItem.ShiftTime = &responsedto.DutyRosterShiftTime{ShiftStart: effectiveShiftStart, ShiftEnd: effectiveShiftEnd}
+}
+
+func buildDutyRosterHelicopterFromHeader(header dutyroster.HeaderView) responsedto.DutyRosterHelicopterSummary {
+	id := uuidNoCtx(header.HelicopterID)
+	typ := strings.TrimSpace(header.HelicopterType)
+	designation := strings.TrimSpace(header.HelicopterDesignation)
+	identifier := strings.TrimSpace(header.HelicopterIdentifier)
+	return responsedto.DutyRosterHelicopterSummary{
+		ID:          id,
+		Designation: designation,
+		Identifier:  identifier,
+		Type:        typ,
+	}
+}
+
+func DutyRosterDeletedCrewItems(rows []dutyroster.DeletedCrewResult) []map[string]any {
+	out := make([]map[string]any, 0, len(rows))
+	for i := range rows {
+		out = append(out, map[string]any{
+			"id":         uuidNoCtx(rows[i].ID),
+			"roster_id":  uuidNoCtx(rows[i].RosterID),
+			"user_id":    uuidNoCtx(rows[i].UserID),
+			"name":       strings.TrimSpace(rows[i].Name),
+			"role_code":  strings.TrimSpace(rows[i].RoleCode),
+			"crew_type":  strings.TrimSpace(rows[i].CrewType),
+			"date_start": dateToString(rows[i].DateStart),
+			"date_end":   dateToString(rows[i].DateEnd),
+		})
+	}
+	return out
+}
+
+func DutyRosterCrewAuditMetadata(rosterID []byte, baseType string, crews []dutyroster.DutyRosterCrew) map[string]any {
+	items := make([]map[string]any, 0, len(crews))
+	for i := range crews {
+		items = append(items, map[string]any{
+			"user_id":    uuidNoCtx(crews[i].UserID),
+			"name_label": strings.TrimSpace(crews[i].NameLabel),
+			"role_code":  strings.TrimSpace(crews[i].RoleCode),
+			"crew_type":  strings.TrimSpace(crews[i].CrewType),
+			"date_start": dateToString(crews[i].DateStart),
+			"date_end":   dateToString(crews[i].DateEnd),
+		})
+	}
+	return map[string]any{
+		"roster_id":   uuidNoCtx(rosterID),
+		"base_type":   strings.TrimSpace(baseType),
+		"crew_count":  len(crews),
+		"crew_detail": items,
+	}
+}
+
+// ===== Grouping/filtering/pagination helpers for list endpoints =====
+func GroupRostersByBase(items []responsedto.DutyRosterResource) []responsedto.DutyRosterBaseGroupResource {
+	return groupRosterResourcesByBase(
+		items,
+		func(item responsedto.DutyRosterResource) string { return item.Attributes.Bases.ID },
+		func(item responsedto.DutyRosterResource) responsedto.DutyRosterBaseGroupResource {
+			return responsedto.DutyRosterBaseGroupResource{
+				Type: "hems_base_roster_group",
+				Attributes: responsedto.DutyRosterBaseGroupAttributes{
+					Bases:   item.Attributes.Bases,
+					Rosters: []responsedto.DutyRosterGroupRoster{},
+				},
+			}
+		},
+		func(group *responsedto.DutyRosterBaseGroupResource, item responsedto.DutyRosterResource) {
+			group.Attributes.Rosters = append(group.Attributes.Rosters, responsedto.DutyRosterGroupRoster{
+				ID:         item.ID,
+				FlightID:   item.Attributes.FlightID,
+				Helicopter: item.Attributes.Helicopter,
+				DutyDate:   item.Attributes.DutyDate,
+				ShiftTime:  item.Attributes.ShiftTime,
+				Detail:     item.Attributes.Detail,
+				CreatedBy:  item.Attributes.CreatedBy,
+				CreatedAt:  item.Attributes.CreatedAt,
+				UpdatedAt:  item.Attributes.UpdatedAt,
+			})
+		},
+	)
+}
+
+func groupRosterResourcesByBase[T any, G any](
+	items []T,
+	getBaseID func(item T) string,
+	newGroup func(item T) G,
+	appendToGroup func(group *G, item T),
+) []G {
+	out := make([]G, 0)
+	indexByBase := map[string]int{}
+	for i := range items {
+		baseKey := normalizeRosterBaseGroupKey(getBaseID(items[i]))
+		idx, ok := indexByBase[baseKey]
+		if !ok {
+			out = append(out, newGroup(items[i]))
+			idx = len(out) - 1
+			indexByBase[baseKey] = idx
+		}
+		appendToGroup(&out[idx], items[i])
+	}
+	return out
+}
+
+func normalizeRosterBaseGroupKey(baseID string) string {
+	s := strings.TrimSpace(baseID)
+	if s == "" {
+		return "unknown"
+	}
+	return s
+}
+
+func MergeEmptyBaseGroups(groups []responsedto.DutyRosterBaseGroupResource, bases []dutyroster.BaseView) []responsedto.DutyRosterBaseGroupResource {
+	indexByBase := make(map[string]int, len(groups))
+	for i := range groups {
+		baseID := strings.TrimSpace(groups[i].Attributes.Bases.ID)
+		if baseID == "" || baseID == "unknown" {
+			continue
+		}
+		indexByBase[baseID] = i
+	}
+	for i := range bases {
+		baseID := uuidNoCtx(bases[i].ID)
+		if baseID == "" {
+			continue
+		}
+		if _, exists := indexByBase[baseID]; exists {
+			continue
+		}
+		groups = append(groups, responsedto.DutyRosterBaseGroupResource{
+			Type: "hems_base_roster_group",
+			Attributes: responsedto.DutyRosterBaseGroupAttributes{
+				Bases: responsedto.DutyRosterBaseInfo{
+					ID:               baseID,
+					Type:             "hems",
+					BaseName:         strings.TrimSpace(bases[i].BaseName),
+					BaseAbbreviation: strings.TrimSpace(bases[i].BaseAbbreviation),
+				},
+				Rosters: []responsedto.DutyRosterGroupRoster{},
+			},
+		})
+	}
+	return groups
+}
+
+func LoadHEMSRosterGroups(ctx context.Context, svc dutyroster.Service, baseID []byte, from, to time.Time, baseName string) ([]responsedto.DutyRosterBaseGroupResource, error) {
+	headers, err := svc.ListHeadersByRange(ctx, baseID, from, to)
+	if err != nil {
+		return nil, err
+	}
+	bases, err := svc.ListHEMSBases(ctx, baseID)
+	if err != nil {
+		return nil, err
+	}
+	rosterIDs := make([][]byte, 0, len(headers))
+	for i := range headers {
+		rosterIDs = append(rosterIDs, headers[i].ID)
+	}
+	crews, err := svc.GetCrewsByRosterIDs(ctx, rosterIDs)
+	if err != nil {
+		return nil, err
+	}
+
+	byRoster := make(map[string][]dutyroster.CrewView)
+	for i := range crews {
+		k, _ := uuidv7.BytesToString(crews[i].RosterID)
+		byRoster[k] = append(byRoster[k], crews[i])
+	}
+	out := make([]responsedto.DutyRosterResource, 0, len(headers))
+	for i := range headers {
+		k, _ := uuidv7.BytesToString(headers[i].ID)
+		out = append(out, DutyRosterResource(ctx, headers[i], byRoster[k]))
+	}
+	grouped := MergeEmptyBaseGroups(GroupRostersByBase(out), bases)
+
+	needle := strings.ToLower(strings.TrimSpace(baseName))
+	if needle == "" {
+		return grouped, nil
+	}
+	filtered := make([]responsedto.DutyRosterBaseGroupResource, 0, len(grouped))
+	for i := range grouped {
+		name := strings.ToLower(strings.TrimSpace(grouped[i].Attributes.Bases.BaseName))
+		if strings.Contains(name, needle) {
+			filtered = append(filtered, grouped[i])
+		}
+	}
+	return filtered, nil
+}
+
+func PaginateHEMSRosterGroups(groups []responsedto.DutyRosterBaseGroupResource, start, length int) ([]responsedto.DutyRosterBaseGroupResource, int) {
+	total := len(groups)
+	if start > total {
+		start = total
+	}
+	end := start + length
+	if end > total {
+		end = total
+	}
+	return groups[start:end], total
+}
+
+// ===== Small generic helpers =====
+func roleBucket(code string) string {
+	s := strings.ToLower(strings.TrimSpace(code))
+	switch s {
+	case "pilot":
+		return "pilot"
+	case "doctor":
+		return "doctor"
+	case "air_rescuer", "rescuer":
+		return "rescuer"
+	case "flight_assistant", "helper":
+		return "helper"
+	case "other", "other_person":
+		return "other_person"
+	default:
+		return "other_person"
+	}
+}
+
+func firstNonEmpty(a, b string) string {
+	if strings.TrimSpace(a) != "" {
+		return a
+	}
+	return b
+}
+
+func boolPtrIfTrue(v bool) *bool {
+	if !v {
+		return nil
+	}
+	b := true
+	return &b
+}
diff --git a/internal/service/duty_roster_service_test.go b/internal/service/duty_roster_service_test.go
new file mode 100644
index 0000000..ed76c85
--- /dev/null
+++ b/internal/service/duty_roster_service_test.go
@@ -0,0 +1,1222 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	dutyroster "wucher/internal/domain/duty_roster"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+)
+
+type hemsDutyRosterRepoMock struct {
+	createCalled bool
+	updateCalled bool
+	deleteCalled bool
+	getCalled    bool
+	crewsCalled  bool
+	listCalled   bool
+	basesCalled  bool
+	shiftCalled  bool
+
+	lastCreateRow   *dutyroster.DutyRoster
+	lastCreateCrews []dutyroster.DutyRosterCrew
+	lastUpdateRow   *dutyroster.DutyRoster
+	lastUpdateCrews []dutyroster.DutyRosterCrew
+	lastDeleteID    []byte
+	lastDeleteBy    []byte
+	lastGetID       []byte
+	lastRosterIDs   [][]byte
+	lastListBaseID  []byte
+	lastListFrom    time.Time
+	lastListTo      time.Time
+	lastBasesID     []byte
+	lastShiftBaseID []byte
+	lastShiftType   string
+	lastHeaderType  string
+	lastListType    string
+	lastBasesType   string
+	insertedCrews   []dutyroster.DutyRosterCrew
+
+	headerResult  *dutyroster.HeaderView
+	crewsResult   []dutyroster.CrewView
+	headersResult []dutyroster.HeaderView
+	basesResult   []dutyroster.BaseView
+	shiftResult   string
+
+	createErr error
+	updateErr error
+	deleteErr error
+	getErr    error
+	crewsErr  error
+	listErr   error
+	basesErr  error
+	shiftErr  error
+}
+
+func (m *hemsDutyRosterRepoMock) InTx(_ context.Context, fn func(txRepo dutyroster.TxRepository) error) error {
+	return fn(m)
+}
+
+func (m *hemsDutyRosterRepoMock) CreateHeader(_ context.Context, row *dutyroster.DutyRoster) error {
+	return m.Create(context.Background(), row, nil)
+}
+
+func (m *hemsDutyRosterRepoMock) UpdateHeader(_ context.Context, row *dutyroster.DutyRoster) error {
+	return m.Update(context.Background(), row, nil)
+}
+
+func (m *hemsDutyRosterRepoMock) ListActiveCrewsByRosterID(_ context.Context, _ []byte) ([]dutyroster.DutyRosterCrew, error) {
+	return []dutyroster.DutyRosterCrew{}, nil
+}
+
+func (m *hemsDutyRosterRepoMock) InsertCrew(_ context.Context, row *dutyroster.DutyRosterCrew) error {
+	if row != nil {
+		m.insertedCrews = append(m.insertedCrews, *row)
+	}
+	return nil
+}
+
+func (m *hemsDutyRosterRepoMock) CrewExists(_ context.Context, _ dutyroster.DutyRosterCrew) (bool, error) {
+	return false, nil
+}
+
+func (m *hemsDutyRosterRepoMock) SoftDeleteCrewByUser(_ context.Context, _ []byte, _, _ string, _ []byte, _ []byte) error {
+	return nil
+}
+
+func (m *hemsDutyRosterRepoMock) FindRosterIDByBaseDate(_ context.Context, _ []byte, _ time.Time) ([]byte, error) {
+	return nil, nil
+}
+
+func (m *hemsDutyRosterRepoMock) FindRosterIDsByBaseDate(_ context.Context, _ []byte, _ time.Time) ([][]byte, error) {
+	return [][]byte{}, nil
+}
+
+func (m *hemsDutyRosterRepoMock) MatchCrewByFilter(_ context.Context, _ [][]byte, _ dutyroster.DutyRosterCrew) ([]dutyroster.DeletedCrewResult, error) {
+	return []dutyroster.DeletedCrewResult{}, nil
+}
+
+func (m *hemsDutyRosterRepoMock) SoftDeleteCrewRows(_ context.Context, _ []dutyroster.DeletedCrewResult, _ []byte) error {
+	return nil
+}
+
+func (m *hemsDutyRosterRepoMock) SoftDeleteCrewForDate(_ context.Context, _ []byte, _ time.Time, _ dutyroster.DutyRosterCrew, _ []byte) error {
+	return nil
+}
+
+func (m *hemsDutyRosterRepoMock) HardDeleteHeader(_ context.Context, id []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	return m.deleteErr
+}
+
+func (m *hemsDutyRosterRepoMock) HardDeleteCrewsByRosterID(_ context.Context, id []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	return m.deleteErr
+}
+
+func (m *hemsDutyRosterRepoMock) GetRosterByID(_ context.Context, id []byte) (*dutyroster.DutyRoster, error) {
+	m.getCalled = true
+	m.lastGetID = id
+	if m.getErr != nil {
+		return nil, m.getErr
+	}
+	return &dutyroster.DutyRoster{
+		ID:       id,
+		BaseID:   m.lastBasesID,
+		DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+	}, nil
+}
+
+func (m *hemsDutyRosterRepoMock) LockRosterByID(_ context.Context, id []byte) (*dutyroster.DutyRoster, error) {
+	return m.GetRosterByID(context.Background(), id)
+}
+
+func (m *hemsDutyRosterRepoMock) SoftDeleteHeader(_ context.Context, id []byte, deletedBy []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return m.deleteErr
+}
+
+func (m *hemsDutyRosterRepoMock) SoftDeleteCrewsByRosterID(_ context.Context, id []byte, deletedBy []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return m.deleteErr
+}
+
+func (m *hemsDutyRosterRepoMock) Create(_ context.Context, row *dutyroster.DutyRoster, crews []dutyroster.DutyRosterCrew) error {
+	m.createCalled = true
+	m.lastCreateRow = row
+	m.lastCreateCrews = crews
+	return m.createErr
+}
+
+func (m *hemsDutyRosterRepoMock) Update(_ context.Context, row *dutyroster.DutyRoster, crews []dutyroster.DutyRosterCrew) error {
+	m.updateCalled = true
+	m.lastUpdateRow = row
+	m.lastUpdateCrews = crews
+	return m.updateErr
+}
+
+func (m *hemsDutyRosterRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return m.deleteErr
+}
+
+func (m *hemsDutyRosterRepoMock) DeleteCrews(_ context.Context, id []byte, _ []dutyroster.DutyRosterCrew, deletedBy []byte) ([]dutyroster.DeletedCrewResult, error) {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return []dutyroster.DeletedCrewResult{}, m.deleteErr
+}
+
+func (m *hemsDutyRosterRepoMock) GetBaseDefaultShift(_ context.Context, baseID []byte, baseType string) (string, error) {
+	m.shiftCalled = true
+	m.lastShiftBaseID = baseID
+	m.lastShiftType = baseType
+	return m.shiftResult, m.shiftErr
+}
+
+func (m *hemsDutyRosterRepoMock) GetHeaderByID(_ context.Context, id []byte) (*dutyroster.HeaderView, error) {
+	m.getCalled = true
+	m.lastGetID = id
+	return m.headerResult, m.getErr
+}
+
+func (m *hemsDutyRosterRepoMock) GetHeaderByIDByBaseType(_ context.Context, id []byte, baseType string) (*dutyroster.HeaderView, error) {
+	m.lastHeaderType = baseType
+	return m.GetHeaderByID(context.Background(), id)
+}
+
+func (m *hemsDutyRosterRepoMock) GetCrewsByRosterIDs(_ context.Context, rosterIDs [][]byte) ([]dutyroster.CrewView, error) {
+	m.crewsCalled = true
+	m.lastRosterIDs = rosterIDs
+	return m.crewsResult, m.crewsErr
+}
+
+func (m *hemsDutyRosterRepoMock) ListHeadersByRange(_ context.Context, baseID []byte, from, to time.Time) ([]dutyroster.HeaderView, error) {
+	m.listCalled = true
+	m.lastListBaseID = baseID
+	m.lastListFrom = from
+	m.lastListTo = to
+	return m.headersResult, m.listErr
+}
+
+func (m *hemsDutyRosterRepoMock) ListHeadersByRangeByBaseType(_ context.Context, baseID []byte, from, to time.Time, baseType string) ([]dutyroster.HeaderView, error) {
+	m.lastListType = baseType
+	return m.ListHeadersByRange(context.Background(), baseID, from, to)
+}
+
+func (m *hemsDutyRosterRepoMock) ListHEMSBases(_ context.Context, baseID []byte) ([]dutyroster.BaseView, error) {
+	m.basesCalled = true
+	m.lastBasesID = baseID
+	return m.basesResult, m.basesErr
+}
+
+func (m *hemsDutyRosterRepoMock) ListBasesByType(_ context.Context, baseID []byte, baseType string) ([]dutyroster.BaseView, error) {
+	m.lastBasesType = baseType
+	m.basesCalled = true
+	m.lastBasesID = baseID
+	return m.basesResult, m.basesErr
+}
+
+func TestHemsDutyRosterService_ForwardsAllMethods(t *testing.T) {
+	repo := &hemsDutyRosterRepoMock{
+		headerResult: &dutyroster.HeaderView{BaseName: "Base A"},
+		crewsResult:  []dutyroster.CrewView{{RoleCode: "pilot"}},
+		headersResult: []dutyroster.HeaderView{{
+			BaseName: "Base A",
+		}},
+		basesResult: []dutyroster.BaseView{{BaseName: "Base A"}},
+	}
+	svc := NewDutyRosterService(repo)
+
+	row := &dutyroster.DutyRoster{}
+	crews := []dutyroster.DutyRosterCrew{{RoleCode: "pilot"}}
+	id := []byte("roster-id-123456")
+	deletedBy := []byte("actor-id-1234567")
+	baseID := []byte("base-id-12345678")
+	from := time.Date(2026, 3, 1, 0, 0, 0, 0, time.UTC)
+	to := time.Date(2026, 3, 31, 0, 0, 0, 0, time.UTC)
+
+	if err := svc.Create(context.Background(), row, crews); err != nil {
+		t.Fatalf("create: %v", err)
+	}
+	if !repo.createCalled || repo.lastCreateRow != row {
+		t.Fatalf("expected create forwarded")
+	}
+
+	if err := svc.Update(context.Background(), row, crews); err != nil {
+		t.Fatalf("update: %v", err)
+	}
+	if !repo.updateCalled || repo.lastUpdateRow != row {
+		t.Fatalf("expected update forwarded")
+	}
+
+	if err := svc.Delete(context.Background(), id, deletedBy); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+	if !repo.deleteCalled || string(repo.lastDeleteID) != string(id) || string(repo.lastDeleteBy) != string(deletedBy) {
+		t.Fatalf("expected delete forwarded")
+	}
+
+	if _, err := svc.GetBaseDefaultShift(context.Background(), baseID, "hems"); err != nil {
+		t.Fatalf("get base default shift: %v", err)
+	}
+	if !repo.shiftCalled || string(repo.lastShiftBaseID) != string(baseID) || repo.lastShiftType != "hems" {
+		t.Fatalf("expected get base default shift forwarded")
+	}
+
+	gotHeader, err := svc.GetHeaderByID(context.Background(), id)
+	if err != nil || gotHeader == nil || gotHeader.BaseName != "Base A" {
+		t.Fatalf("expected get header forwarded")
+	}
+	if !repo.getCalled || string(repo.lastGetID) != string(id) {
+		t.Fatalf("expected get header args forwarded")
+	}
+	if _, err := svc.GetHeaderByIDByBaseType(context.Background(), id, "base"); err != nil {
+		t.Fatalf("expected get header by base type forwarded")
+	}
+	if repo.lastHeaderType == "" {
+		t.Fatalf("expected base type get header path called")
+	}
+
+	gotCrews, err := svc.GetCrewsByRosterIDs(context.Background(), [][]byte{id})
+	if err != nil || len(gotCrews) != 1 {
+		t.Fatalf("expected get crews forwarded")
+	}
+	if !repo.crewsCalled || len(repo.lastRosterIDs) != 1 {
+		t.Fatalf("expected get crews args forwarded")
+	}
+
+	gotHeaders, err := svc.ListHeadersByRange(context.Background(), baseID, from, to)
+	if err != nil || len(gotHeaders) != 1 {
+		t.Fatalf("expected list headers forwarded")
+	}
+	if !repo.listCalled || string(repo.lastListBaseID) != string(baseID) || !repo.lastListFrom.Equal(from) || !repo.lastListTo.Equal(to) {
+		t.Fatalf("expected list headers args forwarded")
+	}
+	if _, err := svc.ListHeadersByRangeByBaseType(context.Background(), baseID, from, to, "base"); err != nil {
+		t.Fatalf("expected list headers by base type forwarded")
+	}
+	if repo.lastListType != "base" {
+		t.Fatalf("expected base type forwarded to list headers, got %q", repo.lastListType)
+	}
+
+	gotBases, err := svc.ListHEMSBases(context.Background(), baseID)
+	if err != nil || len(gotBases) != 1 {
+		t.Fatalf("expected list bases forwarded")
+	}
+	if !repo.basesCalled || string(repo.lastBasesID) != string(baseID) {
+		t.Fatalf("expected list bases args forwarded")
+	}
+	if _, err := svc.ListBasesByType(context.Background(), baseID, "base"); err != nil {
+		t.Fatalf("expected list bases by type forwarded")
+	}
+	if repo.lastBasesType != "base" {
+		t.Fatalf("expected base type forwarded to list bases, got %q", repo.lastBasesType)
+	}
+}
+
+func TestHemsDutyRosterService_PropagatesErrors(t *testing.T) {
+	repo := &hemsDutyRosterRepoMock{
+		createErr: errors.New("create error"),
+		updateErr: errors.New("update error"),
+		deleteErr: errors.New("delete error"),
+		getErr:    errors.New("get error"),
+		crewsErr:  errors.New("crews error"),
+		listErr:   errors.New("list error"),
+		basesErr:  errors.New("bases error"),
+	}
+	svc := NewDutyRosterService(repo)
+
+	if err := svc.Create(context.Background(), &dutyroster.DutyRoster{}, nil); err == nil {
+		t.Fatalf("expected create error")
+	}
+	if err := svc.Update(context.Background(), &dutyroster.DutyRoster{}, nil); err == nil {
+		t.Fatalf("expected update error")
+	}
+	if err := svc.Delete(context.Background(), []byte("id"), []byte("actor")); err == nil {
+		t.Fatalf("expected delete error")
+	}
+	if _, err := svc.GetHeaderByID(context.Background(), []byte("id")); err == nil {
+		t.Fatalf("expected get error")
+	}
+	if _, err := svc.GetCrewsByRosterIDs(context.Background(), [][]byte{[]byte("id")}); err == nil {
+		t.Fatalf("expected crews error")
+	}
+	if _, err := svc.ListHeadersByRange(context.Background(), []byte("base"), time.Now(), time.Now()); err == nil {
+		t.Fatalf("expected list error")
+	}
+	if _, err := svc.ListHEMSBases(context.Background(), []byte("base")); err == nil {
+		t.Fatalf("expected bases error")
+	}
+}
+
+func TestHemsDutyRosterService_NormalizesWritePayloadBeforeRepo(t *testing.T) {
+	repo := &hemsDutyRosterRepoMock{}
+	svc := NewDutyRosterService(repo)
+
+	row := &dutyroster.DutyRoster{}
+	crews := []dutyroster.DutyRosterCrew{
+		{
+			RoleCode: "pilot",
+			CrewType: "main",
+		},
+	}
+
+	if err := svc.Create(context.Background(), row, crews); err != nil {
+		t.Fatalf("create: %v", err)
+	}
+	if repo.lastCreateRow == nil {
+		t.Fatalf("expected create row forwarded")
+	}
+	if len(repo.insertedCrews) != 1 {
+		t.Fatalf("expected 1 crew inserted")
+	}
+	if repo.insertedCrews[0].ShiftStart != "2000-01-01 00:00:00" || repo.insertedCrews[0].ShiftEnd != "2000-01-01 00:00:00" {
+		t.Fatalf("expected crew shift normalized, got %q-%q", repo.insertedCrews[0].ShiftStart, repo.insertedCrews[0].ShiftEnd)
+	}
+}
+
+func TestHemsDutyRosterService_NormalizeFilterShiftInput(t *testing.T) {
+	if got := normalizeCrewShiftForFilter(""); got != "" {
+		t.Fatalf("expected empty filter shift, got %q", got)
+	}
+	if got := normalizeCrewShiftForFilter("08:15"); got != "2000-01-01 08:15:00" {
+		t.Fatalf("expected normalized filter shift, got %q", got)
+	}
+}
+
+func TestDutyRosterDeletedCrewItems_IncludesName(t *testing.T) {
+	rows := []dutyroster.DeletedCrewResult{
+		{
+			ID:       []byte("1234567890123456"),
+			RosterID: []byte("abcdefabcdefabcd"),
+			UserID:   []byte("9999999999999999"),
+			Name:     "Pilot One",
+			RoleCode: "pilot",
+			CrewType: "main",
+		},
+	}
+
+	items := DutyRosterDeletedCrewItems(rows)
+	if len(items) != 1 {
+		t.Fatalf("expected 1 item, got %d", len(items))
+	}
+	if got, _ := items[0]["name"].(string); got != "Pilot One" {
+		t.Fatalf("expected deleted item name, got %#v", items[0]["name"])
+	}
+}
+
+type dutyRosterTxRepoMock struct {
+	lockFn              func(ctx context.Context, id []byte) (*dutyroster.DutyRoster, error)
+	createHeaderFn      func(ctx context.Context, row *dutyroster.DutyRoster) error
+	findIDByDateFn      func(ctx context.Context, baseID []byte, dutyDate time.Time) ([]byte, error)
+	listActiveCrewsFn   func(ctx context.Context, rosterID []byte) ([]dutyroster.DutyRosterCrew, error)
+	insertCrewFn        func(ctx context.Context, row *dutyroster.DutyRosterCrew) error
+	crewExistsFn        func(ctx context.Context, row dutyroster.DutyRosterCrew) (bool, error)
+	softDeleteByUserFn  func(ctx context.Context, rosterID []byte, roleCode, crewType string, userID []byte, deletedBy []byte) error
+	softDeleteCrewsFn   func(ctx context.Context, rosterID []byte, deletedBy []byte) error
+	softDeleteForDateFn func(ctx context.Context, baseID []byte, dutyDate time.Time, crew dutyroster.DutyRosterCrew, deletedBy []byte) error
+	findIDsByDateFn     func(ctx context.Context, baseID []byte, dutyDate time.Time) ([][]byte, error)
+	matchCrewByFilterFn func(ctx context.Context, rosterIDs [][]byte, crew dutyroster.DutyRosterCrew) ([]dutyroster.DeletedCrewResult, error)
+	softDeleteRowsFn    func(ctx context.Context, rows []dutyroster.DeletedCrewResult, deletedBy []byte) error
+}
+
+func (m *dutyRosterTxRepoMock) GetRosterByID(_ context.Context, _ []byte) (*dutyroster.DutyRoster, error) {
+	return nil, nil
+}
+func (m *dutyRosterTxRepoMock) LockRosterByID(ctx context.Context, id []byte) (*dutyroster.DutyRoster, error) {
+	if m.lockFn != nil {
+		return m.lockFn(ctx, id)
+	}
+	return &dutyroster.DutyRoster{ID: id, BaseID: uuidv7.MustBytes(), DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)}, nil
+}
+func (m *dutyRosterTxRepoMock) CreateHeader(ctx context.Context, row *dutyroster.DutyRoster) error {
+	if m.createHeaderFn != nil {
+		return m.createHeaderFn(ctx, row)
+	}
+	return nil
+}
+func (m *dutyRosterTxRepoMock) UpdateHeader(_ context.Context, _ *dutyroster.DutyRoster) error {
+	return nil
+}
+func (m *dutyRosterTxRepoMock) SoftDeleteHeader(_ context.Context, _ []byte, _ []byte) error {
+	return nil
+}
+func (m *dutyRosterTxRepoMock) SoftDeleteCrewsByRosterID(ctx context.Context, rosterID []byte, deletedBy []byte) error {
+	if m.softDeleteCrewsFn != nil {
+		return m.softDeleteCrewsFn(ctx, rosterID, deletedBy)
+	}
+	return nil
+}
+func (m *dutyRosterTxRepoMock) ListActiveCrewsByRosterID(ctx context.Context, rosterID []byte) ([]dutyroster.DutyRosterCrew, error) {
+	if m.listActiveCrewsFn != nil {
+		return m.listActiveCrewsFn(ctx, rosterID)
+	}
+	return nil, nil
+}
+func (m *dutyRosterTxRepoMock) InsertCrew(ctx context.Context, row *dutyroster.DutyRosterCrew) error {
+	if m.insertCrewFn != nil {
+		return m.insertCrewFn(ctx, row)
+	}
+	return nil
+}
+func (m *dutyRosterTxRepoMock) CrewExists(ctx context.Context, row dutyroster.DutyRosterCrew) (bool, error) {
+	if m.crewExistsFn != nil {
+		return m.crewExistsFn(ctx, row)
+	}
+	return false, nil
+}
+func (m *dutyRosterTxRepoMock) SoftDeleteCrewByUser(ctx context.Context, rosterID []byte, roleCode, crewType string, userID []byte, deletedBy []byte) error {
+	if m.softDeleteByUserFn != nil {
+		return m.softDeleteByUserFn(ctx, rosterID, roleCode, crewType, userID, deletedBy)
+	}
+	return nil
+}
+func (m *dutyRosterTxRepoMock) FindRosterIDByBaseDate(ctx context.Context, baseID []byte, dutyDate time.Time) ([]byte, error) {
+	if m.findIDByDateFn != nil {
+		return m.findIDByDateFn(ctx, baseID, dutyDate)
+	}
+	return nil, nil
+}
+func (m *dutyRosterTxRepoMock) FindRosterIDsByBaseDate(ctx context.Context, baseID []byte, dutyDate time.Time) ([][]byte, error) {
+	if m.findIDsByDateFn != nil {
+		return m.findIDsByDateFn(ctx, baseID, dutyDate)
+	}
+	return [][]byte{uuidv7.MustBytes()}, nil
+}
+func (m *dutyRosterTxRepoMock) MatchCrewByFilter(ctx context.Context, rosterIDs [][]byte, crew dutyroster.DutyRosterCrew) ([]dutyroster.DeletedCrewResult, error) {
+	if m.matchCrewByFilterFn != nil {
+		return m.matchCrewByFilterFn(ctx, rosterIDs, crew)
+	}
+	return []dutyroster.DeletedCrewResult{}, nil
+}
+func (m *dutyRosterTxRepoMock) SoftDeleteCrewRows(ctx context.Context, rows []dutyroster.DeletedCrewResult, deletedBy []byte) error {
+	if m.softDeleteRowsFn != nil {
+		return m.softDeleteRowsFn(ctx, rows, deletedBy)
+	}
+	return nil
+}
+func (m *dutyRosterTxRepoMock) SoftDeleteCrewForDate(ctx context.Context, baseID []byte, dutyDate time.Time, crew dutyroster.DutyRosterCrew, deletedBy []byte) error {
+	if m.softDeleteForDateFn != nil {
+		return m.softDeleteForDateFn(ctx, baseID, dutyDate, crew, deletedBy)
+	}
+	return nil
+}
+
+func (m *dutyRosterTxRepoMock) HardDeleteHeader(_ context.Context, _ []byte) error {
+	return nil
+}
+
+func (m *dutyRosterTxRepoMock) HardDeleteCrewsByRosterID(_ context.Context, _ []byte) error {
+	return nil
+}
+
+type dutyRosterRepoWithTxMock struct {
+	txRepo      dutyroster.TxRepository
+	inTxErr     error
+	shiftResult string
+	shiftErr    error
+}
+
+func (m *dutyRosterRepoWithTxMock) InTx(ctx context.Context, fn func(txRepo dutyroster.TxRepository) error) error {
+	if m.inTxErr != nil {
+		return m.inTxErr
+	}
+	return fn(m.txRepo)
+}
+func (m *dutyRosterRepoWithTxMock) GetBaseDefaultShift(_ context.Context, _ []byte, _ string) (string, error) {
+	return m.shiftResult, m.shiftErr
+}
+func (m *dutyRosterRepoWithTxMock) GetHeaderByID(_ context.Context, _ []byte) (*dutyroster.HeaderView, error) {
+	return nil, nil
+}
+func (m *dutyRosterRepoWithTxMock) GetHeaderByIDByBaseType(_ context.Context, _ []byte, _ string) (*dutyroster.HeaderView, error) {
+	return nil, nil
+}
+func (m *dutyRosterRepoWithTxMock) GetCrewsByRosterIDs(_ context.Context, _ [][]byte) ([]dutyroster.CrewView, error) {
+	return nil, nil
+}
+func (m *dutyRosterRepoWithTxMock) ListHeadersByRange(_ context.Context, _ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+	return nil, nil
+}
+func (m *dutyRosterRepoWithTxMock) ListHeadersByRangeByBaseType(_ context.Context, _ []byte, _, _ time.Time, _ string) ([]dutyroster.HeaderView, error) {
+	return nil, nil
+}
+func (m *dutyRosterRepoWithTxMock) ListHEMSBases(_ context.Context, _ []byte) ([]dutyroster.BaseView, error) {
+	return nil, nil
+}
+func (m *dutyRosterRepoWithTxMock) ListBasesByType(_ context.Context, _ []byte, _ string) ([]dutyroster.BaseView, error) {
+	return nil, nil
+}
+
+func TestDutyRosterDeleteCrewsFlow(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	rosterID := uuidv7.MustBytes()
+	deletedBy := uuidv7.MustBytes()
+	rowA := dutyroster.DeletedCrewResult{ID: uuidv7.MustBytes(), RosterID: rosterID, UserID: uuidv7.MustBytes(), Name: "Pilot A", RoleCode: "pilot", CrewType: "main"}
+	rowB := dutyroster.DeletedCrewResult{ID: uuidv7.MustBytes(), RosterID: rosterID, UserID: uuidv7.MustBytes(), Name: "Pilot B", RoleCode: "pilot", CrewType: "main"}
+
+	deleteCalls := 0
+	tx := &dutyRosterTxRepoMock{
+		lockFn: func(_ context.Context, _ []byte) (*dutyroster.DutyRoster, error) {
+			return &dutyroster.DutyRoster{ID: rosterID, BaseID: baseID, DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)}, nil
+		},
+		findIDsByDateFn: func(_ context.Context, _ []byte, _ time.Time) ([][]byte, error) {
+			return [][]byte{rosterID}, nil
+		},
+		matchCrewByFilterFn: func(_ context.Context, _ [][]byte, _ dutyroster.DutyRosterCrew) ([]dutyroster.DeletedCrewResult, error) {
+			// include duplicate ID to cover de-dup collector.
+			return []dutyroster.DeletedCrewResult{rowA, rowA, rowB}, nil
+		},
+		softDeleteRowsFn: func(_ context.Context, rows []dutyroster.DeletedCrewResult, _ []byte) error {
+			deleteCalls++
+			if len(rows) == 0 {
+				t.Fatalf("expected rows for delete")
+			}
+			return nil
+		},
+	}
+	repo := &dutyRosterRepoWithTxMock{txRepo: tx}
+	svc := NewDutyRosterService(repo)
+
+	start := time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)
+	end := time.Date(2026, 3, 21, 0, 0, 0, 0, time.UTC)
+	crews := []dutyroster.DutyRosterCrew{
+		{
+			RoleCode:  "pilot",
+			CrewType:  "main",
+			UserID:    rowA.UserID,
+			DateStart: &start,
+			DateEnd:   &end,
+		},
+	}
+	out, err := svc.DeleteCrews(context.Background(), rosterID, crews, deletedBy)
+	if err != nil {
+		t.Fatalf("delete crews: %v", err)
+	}
+	if deleteCalls == 0 {
+		t.Fatalf("expected soft delete called")
+	}
+	if len(out) != 2 {
+		t.Fatalf("expected de-duplicated deleted rows = 2, got %d", len(out))
+	}
+}
+
+func TestDutyRosterDeleteCrews_Errors(t *testing.T) {
+	rosterID := uuidv7.MustBytes()
+	tx := &dutyRosterTxRepoMock{
+		lockFn: func(_ context.Context, _ []byte) (*dutyroster.DutyRoster, error) {
+			return nil, errors.New("lock failed")
+		},
+	}
+	repo := &dutyRosterRepoWithTxMock{txRepo: tx}
+	svc := NewDutyRosterService(repo)
+
+	_, err := svc.DeleteCrews(context.Background(), rosterID, []dutyroster.DutyRosterCrew{{RoleCode: "pilot"}}, uuidv7.MustBytes())
+	if err == nil {
+		t.Fatalf("expected error")
+	}
+}
+
+func TestDutyRosterResolveBaseDefaultShiftRangeBranches(t *testing.T) {
+	svc := NewDutyRosterService(&dutyRosterRepoWithTxMock{txRepo: &dutyRosterTxRepoMock{}})
+	start, end, err := svc.ResolveBaseDefaultShiftRange(context.Background(), nil, "base")
+	if err != nil || start != "" || end != "" {
+		t.Fatalf("expected empty fallback shift, got %q-%q err=%v", start, end, err)
+	}
+
+	repoErr := &dutyRosterRepoWithTxMock{txRepo: &dutyRosterTxRepoMock{}, shiftErr: errors.New("db error")}
+	svcErr := NewDutyRosterService(repoErr)
+	_, _, err = svcErr.ResolveBaseDefaultShiftRange(context.Background(), uuidv7.MustBytes(), "base")
+	if err == nil {
+		t.Fatalf("expected error from repo")
+	}
+
+	repoRaw := &dutyRosterRepoWithTxMock{txRepo: &dutyRosterTxRepoMock{}, shiftResult: "start=07:00 end=19:00"}
+	svcRaw := NewDutyRosterService(repoRaw)
+	start, end, err = svcRaw.ResolveBaseDefaultShiftRange(context.Background(), uuidv7.MustBytes(), "base")
+	if err != nil || start != "07:00:00" || end != "19:00:00" {
+		t.Fatalf("expected parsed shift, got %q-%q err=%v", start, end, err)
+	}
+}
+
+func TestDutyRosterParsingHelpers(t *testing.T) {
+	// ParseDutyRosterShiftRange + token extraction
+	s, e := ParseDutyRosterShiftRange("Shift 08:15 - 20:45")
+	if s != "08:15:00" || e != "20:45:00" {
+		t.Fatalf("unexpected parsed range: %q-%q", s, e)
+	}
+	s, e = ParseDutyRosterShiftRange("bad")
+	if s != "" || e != "" {
+		t.Fatalf("expected empty range on bad input")
+	}
+
+	// NormalizeDutyRosterClockInput
+	out, errObj := NormalizeDutyRosterClockInput("09:30", "", "/x")
+	if errObj != nil || out != "09:30:00" {
+		t.Fatalf("expected normalized HH:MM, got out=%q err=%#v", out, errObj)
+	}
+	_, errObj = NormalizeDutyRosterClockInput("99:99", "", "/x")
+	if errObj == nil {
+		t.Fatalf("expected invalid time error")
+	}
+
+	// ParseDutyRosterDateRangeOrDefault
+	now := time.Date(2026, 3, 18, 10, 0, 0, 0, time.UTC)
+	from, to, errObj := ParseDutyRosterDateRangeOrDefault("", "", now)
+	if errObj != nil || from.Format("2006-01-02") != "2026-03-01" || to.Format("2006-01-02") != "2026-03-31" {
+		t.Fatalf("unexpected default range: %v %v err=%#v", from, to, errObj)
+	}
+	_, _, errObj = ParseDutyRosterDateRangeOrDefault("bad", "", now)
+	if errObj == nil || errObj.Pointer != "/query/from" {
+		t.Fatalf("expected invalid from")
+	}
+	_, _, errObj = ParseDutyRosterDateRangeOrDefault("", "bad", now)
+	if errObj == nil || errObj.Pointer != "/query/to" {
+		t.Fatalf("expected invalid to")
+	}
+
+	if _, err := ParseDutyRosterDateOnly("2026-03-20"); err != nil {
+		t.Fatalf("ParseDutyRosterDateOnly: %v", err)
+	}
+}
+
+func TestBuildDutyRosterDeleteCrewsBranches(t *testing.T) {
+	actor := uuidv7.MustBytes()
+
+	crews, errObj := BuildDutyRosterDeleteCrews([]byte("{}"), actor)
+	if errObj != nil || crews != nil {
+		t.Fatalf("expected nil crews on empty payload")
+	}
+
+	_, errObj = BuildDutyRosterDeleteCrews([]byte("{"), actor)
+	if errObj == nil || errObj.Pointer != "/data" {
+		t.Fatalf("expected invalid delete payload")
+	}
+
+	body := []byte(`{"data":{"attributes":{"roster_detail":{"pilot":[{"id":"` + mustUUID(t) + `","shift_date":{"date_start":"2026-03-21"}}]}}}}`)
+	_, errObj = BuildDutyRosterDeleteCrews(body, actor)
+	if errObj == nil || errObj.Detail != "shift_date.date_start and shift_date.date_end must be provided together" {
+		t.Fatalf("expected shift_date pair validation, got %#v", errObj)
+	}
+
+	body = []byte(`{"data":{"attributes":{"roster_detail":{"other_person":[{"name":"Guest"}]}}}}`)
+	crews, errObj = BuildDutyRosterDeleteCrews(body, actor)
+	if errObj != nil || len(crews) != 1 {
+		t.Fatalf("expected valid other_person delete crew, got crews=%d err=%#v", len(crews), errObj)
+	}
+}
+
+func TestDutyRosterGroupingAndMetadataHelpers(t *testing.T) {
+	rosterID := uuidv7.MustBytes()
+	baseID := uuidv7.MustBytes()
+	groups := GroupRostersByBase([]responsedto.DutyRosterResource{
+		{
+			ID: "r1",
+			Attributes: responsedto.DutyRosterAttributes{
+				Bases: responsedto.DutyRosterBaseInfo{ID: "b1", BaseName: "Base 1"},
+			},
+		},
+		{
+			ID: "r2",
+			Attributes: responsedto.DutyRosterAttributes{
+				Bases: responsedto.DutyRosterBaseInfo{ID: "b1", BaseName: "Base 1"},
+			},
+		},
+	})
+	if len(groups) != 1 || len(groups[0].Attributes.Rosters) != 2 {
+		t.Fatalf("unexpected grouped rosters: %#v", groups)
+	}
+
+	merged := MergeEmptyBaseGroups(groups, []dutyroster.BaseView{{ID: baseID, BaseName: "Base 2"}})
+	if len(merged) != 2 {
+		t.Fatalf("expected appended empty base group")
+	}
+
+	meta := DutyRosterCrewAuditMetadata(rosterID, "hems", []dutyroster.DutyRosterCrew{{RoleCode: "pilot"}})
+	if meta["base_type"] != "hems" {
+		t.Fatalf("unexpected metadata: %#v", meta)
+	}
+
+	if roleBucket("air_rescuer") != "rescuer" || roleBucket("flight_assistant") != "helper" || roleBucket("x") != "other_person" {
+		t.Fatalf("unexpected role bucket mapping")
+	}
+	if firstNonEmpty("a", "b") != "a" || firstNonEmpty("", "b") != "b" {
+		t.Fatalf("unexpected firstNonEmpty")
+	}
+	if p := boolPtrIfTrue(true); p == nil || !*p {
+		t.Fatalf("unexpected bool ptr")
+	}
+	if p := boolPtrIfTrue(false); p != nil {
+		t.Fatalf("expected nil ptr for false")
+	}
+}
+
+func TestDutyRosterResourceMapping(t *testing.T) {
+	header := dutyroster.HeaderView{
+		ID:               uuidv7.MustBytes(),
+		BaseID:           uuidv7.MustBytes(),
+		BaseName:         "Base A",
+		BaseAbbreviation: "BA",
+		DutyDate:         time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+		CreatedBy:        uuidv7.MustBytes(),
+		CreatedAt:        time.Date(2026, 3, 20, 1, 0, 0, 0, time.UTC),
+		UpdatedAt:        time.Date(2026, 3, 20, 2, 0, 0, 0, time.UTC),
+	}
+	crews := []dutyroster.CrewView{
+		{
+			ID:               uuidv7.MustBytes(),
+			UserID:           uuidv7.MustBytes(),
+			Name:             "Pilot One",
+			Role:             "pilot",
+			RoleCode:         "pilot",
+			CrewType:         "additional",
+			FlightInstructor: true,
+		},
+		{
+			ID:       uuidv7.MustBytes(),
+			Name:     "Guest",
+			Role:     "other",
+			RoleCode: "other_person",
+		},
+	}
+	got := DutyRosterResource(context.Background(), header, crews)
+	if got.Type != "duty_roster" || got.Attributes.Bases.BaseName != "Base A" {
+		t.Fatalf("unexpected duty roster resource: %#v", got)
+	}
+	if len(got.Attributes.Detail.Pilot) != 1 || len(got.Attributes.Detail.OtherPerson) != 1 {
+		t.Fatalf("unexpected role buckets: %#v", got.Attributes.Detail)
+	}
+	if got.Attributes.CreatedBy == "" {
+		t.Fatalf("expected created_by on duty roster resource")
+	}
+}
+
+func TestBuildDutyRosterCrewRows_CoreBranches(t *testing.T) {
+	actor := uuidv7.MustBytes()
+	pilotID := mustUUID(t)
+
+	// invalid crew id
+	_, errObj := BuildDutyRosterCrewRows(requestdto.DutyRosterDetailsInput{
+		Pilot: []requestdto.DutyRosterPilotCrewInput{{ID: "bad"}},
+	}, actor)
+	if errObj == nil || errObj.Detail != "crew id is invalid UUID" {
+		t.Fatalf("expected invalid id error, got %#v", errObj)
+	}
+
+	// success with pilot additional flags + other_person
+	rows, errObj := BuildDutyRosterCrewRows(requestdto.DutyRosterDetailsInput{
+		Pilot: []requestdto.DutyRosterPilotCrewInput{{
+			ID:               pilotID,
+			CrewType:         "additional",
+			FlightInstructor: true,
+		}},
+		OtherPerson: []requestdto.DutyRosterOtherPersonInput{{
+			Name: "Guest",
+		}},
+	}, actor)
+	if errObj != nil || len(rows) != 2 {
+		t.Fatalf("expected success rows, got err=%#v len=%d", errObj, len(rows))
+	}
+	if !rows[0].FlightInstructor {
+		t.Fatalf("expected pilot additional flag set")
+	}
+	if rows[1].RoleCode != "other_person" || rows[1].DateStart != nil || rows[1].ShiftStart != "" {
+		t.Fatalf("expected other_person shift/date stripped")
+	}
+}
+
+func TestDutyRosterService_EnsureRosterForDateBranches(t *testing.T) {
+	svc := NewDutyRosterService(&dutyRosterRepoWithTxMock{txRepo: &dutyRosterTxRepoMock{}})
+	source := &dutyroster.DutyRoster{
+		BaseID:    uuidv7.MustBytes(),
+		DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+		CreatedBy: uuidv7.MustBytes(),
+		UpdatedBy: uuidv7.MustBytes(),
+	}
+	target := time.Date(2026, 3, 21, 10, 0, 0, 0, time.FixedZone("X", 7*3600))
+
+	t.Run("existing roster", func(t *testing.T) {
+		existingID := uuidv7.MustBytes()
+		locked := 0
+		tx := &dutyRosterTxRepoMock{
+			findIDByDateFn: func(_ context.Context, _ []byte, _ time.Time) ([]byte, error) {
+				return existingID, nil
+			},
+			lockFn: func(_ context.Context, id []byte) (*dutyroster.DutyRoster, error) {
+				locked++
+				return &dutyroster.DutyRoster{ID: id}, nil
+			},
+		}
+		got, err := svc.ensureRosterForDate(context.Background(), tx, source, target)
+		if err != nil || string(got) != string(existingID) || locked != 1 {
+			t.Fatalf("expected existing roster path, got id=%x lock=%d err=%v", got, locked, err)
+		}
+	})
+
+	t.Run("create header", func(t *testing.T) {
+		tx := &dutyRosterTxRepoMock{
+			createHeaderFn: func(_ context.Context, row *dutyroster.DutyRoster) error {
+				row.ID = uuidv7.MustBytes()
+				return nil
+			},
+		}
+		got, err := svc.ensureRosterForDate(context.Background(), tx, source, target)
+		if err != nil || len(got) == 0 {
+			t.Fatalf("expected created roster id, got %x err=%v", got, err)
+		}
+	})
+
+	t.Run("concurrent create fallback winner", func(t *testing.T) {
+		winner := uuidv7.MustBytes()
+		locked := 0
+		tx := &dutyRosterTxRepoMock{
+			createHeaderFn: func(_ context.Context, _ *dutyroster.DutyRoster) error { return errors.New("duplicate") },
+			findIDByDateFn: func(_ context.Context, _ []byte, _ time.Time) ([]byte, error) { return winner, nil },
+			lockFn: func(_ context.Context, id []byte) (*dutyroster.DutyRoster, error) {
+				locked++
+				return &dutyroster.DutyRoster{ID: id}, nil
+			},
+		}
+		got, err := svc.ensureRosterForDate(context.Background(), tx, source, target)
+		if err != nil || string(got) != string(winner) || locked != 1 {
+			t.Fatalf("expected winner fallback, got id=%x lock=%d err=%v", got, locked, err)
+		}
+	})
+
+	t.Run("existing roster lock error", func(t *testing.T) {
+		existingID := uuidv7.MustBytes()
+		tx := &dutyRosterTxRepoMock{
+			findIDByDateFn: func(_ context.Context, _ []byte, _ time.Time) ([]byte, error) {
+				return existingID, nil
+			},
+			lockFn: func(_ context.Context, _ []byte) (*dutyroster.DutyRoster, error) {
+				return nil, errors.New("lock failed")
+			},
+		}
+		_, err := svc.ensureRosterForDate(context.Background(), tx, source, target)
+		if err == nil {
+			t.Fatalf("expected lock error")
+		}
+	})
+
+	t.Run("create error and fetch error", func(t *testing.T) {
+		tx := &dutyRosterTxRepoMock{
+			createHeaderFn: func(_ context.Context, _ *dutyroster.DutyRoster) error { return errors.New("duplicate") },
+			findIDByDateFn: func(_ context.Context, _ []byte, _ time.Time) ([]byte, error) { return nil, errors.New("fetch failed") },
+		}
+		_, err := svc.ensureRosterForDate(context.Background(), tx, source, target)
+		if err == nil || !strings.Contains(err.Error(), "fetch failed") {
+			t.Fatalf("expected fetch error after create fail, got %v", err)
+		}
+	})
+
+	t.Run("create error and no winner id", func(t *testing.T) {
+		tx := &dutyRosterTxRepoMock{
+			createHeaderFn: func(_ context.Context, _ *dutyroster.DutyRoster) error { return errors.New("duplicate") },
+			findIDByDateFn: func(_ context.Context, _ []byte, _ time.Time) ([]byte, error) { return nil, nil },
+		}
+		_, err := svc.ensureRosterForDate(context.Background(), tx, source, target)
+		if err == nil || !strings.Contains(err.Error(), "duplicate") {
+			t.Fatalf("expected original create error, got %v", err)
+		}
+	})
+}
+
+func TestDutyRosterService_AddRemoveRangeAssignmentsAndHelpers(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	row := &dutyroster.DutyRoster{
+		BaseID:    baseID,
+		DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+		UpdatedBy: uuidv7.MustBytes(),
+		CreatedBy: uuidv7.MustBytes(),
+	}
+	userID := uuidv7.MustBytes()
+	start := time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)
+	end := time.Date(2026, 3, 22, 0, 0, 0, 0, time.UTC)
+	crews := []dutyroster.DutyRosterCrew{{
+		RoleCode:  "pilot",
+		CrewType:  "main",
+		UserID:    userID,
+		DateStart: &start,
+		DateEnd:   &end,
+	}}
+
+	t.Run("add range", func(t *testing.T) {
+		inserted := 0
+		deletedByUser := 0
+		callsByDate := map[string]int{}
+		existingRoster := uuidv7.MustBytes()
+		newRoster := uuidv7.MustBytes()
+		tx := &dutyRosterTxRepoMock{
+			findIDByDateFn: func(_ context.Context, _ []byte, dutyDate time.Time) ([]byte, error) {
+				d := dutyDate.UTC().Format("2006-01-02")
+				callsByDate[d]++
+				if d == "2026-03-21" {
+					return existingRoster, nil
+				}
+				return nil, nil
+			},
+			lockFn: func(_ context.Context, id []byte) (*dutyroster.DutyRoster, error) {
+				return &dutyroster.DutyRoster{ID: id}, nil
+			},
+			createHeaderFn: func(_ context.Context, r *dutyroster.DutyRoster) error {
+				r.ID = append([]byte(nil), newRoster...)
+				return nil
+			},
+			crewExistsFn: func(_ context.Context, row dutyroster.DutyRosterCrew) (bool, error) {
+				// skip insert for existing roster, insert for newly-created roster.
+				return string(row.RosterID) == string(existingRoster), nil
+			},
+			insertCrewFn: func(_ context.Context, _ *dutyroster.DutyRosterCrew) error {
+				inserted++
+				return nil
+			},
+			softDeleteByUserFn: func(_ context.Context, _ []byte, _, _ string, _ []byte, _ []byte) error {
+				deletedByUser++
+				return nil
+			},
+		}
+		svc := NewDutyRosterService(&dutyRosterRepoWithTxMock{txRepo: tx})
+		if err := svc.addRangeAssignments(context.Background(), tx, row, crews); err != nil {
+			t.Fatalf("add range assignments: %v", err)
+		}
+		if inserted != 1 || deletedByUser != 2 || callsByDate["2026-03-21"] == 0 || callsByDate["2026-03-22"] == 0 {
+			t.Fatalf("unexpected add-range effects inserted=%d deletedByUser=%d calls=%v", inserted, deletedByUser, callsByDate)
+		}
+	})
+
+	t.Run("remove range", func(t *testing.T) {
+		deletedDates := []string{}
+		tx := &dutyRosterTxRepoMock{
+			softDeleteForDateFn: func(_ context.Context, _ []byte, dutyDate time.Time, _ dutyroster.DutyRosterCrew, _ []byte) error {
+				deletedDates = append(deletedDates, dutyDate.UTC().Format("2006-01-02"))
+				return nil
+			},
+		}
+		svc := NewDutyRosterService(&dutyRosterRepoWithTxMock{txRepo: tx})
+		newEnd := time.Date(2026, 3, 21, 0, 0, 0, 0, time.UTC)
+		newCrews := []dutyroster.DutyRosterCrew{{
+			RoleCode:  "pilot",
+			CrewType:  "main",
+			UserID:    userID,
+			DateStart: &start,
+			DateEnd:   &newEnd,
+		}}
+		if err := svc.removeRangeAssignments(context.Background(), tx, row, crews, newCrews); err != nil {
+			t.Fatalf("remove range assignments: %v", err)
+		}
+		if len(deletedDates) != 1 || deletedDates[0] != "2026-03-22" {
+			t.Fatalf("expected delete only out-of-range day, got %v", deletedDates)
+		}
+	})
+
+	parsed := collectRangeAssignments([]dutyroster.DutyRosterCrew{
+		{RoleCode: "other_person", DateStart: &start, DateEnd: &end},
+		{RoleCode: "pilot", DateStart: &end, DateEnd: &start},
+		{RoleCode: "pilot", DateStart: &start, DateEnd: &end, UserID: userID, CrewType: "main"},
+	})
+	if len(parsed) != 1 {
+		t.Fatalf("expected one valid range assignment, got %d", len(parsed))
+	}
+	if assignmentKey(parsed[0].crew) == "" {
+		t.Fatalf("expected non-empty assignment key")
+	}
+	if replaceByUserKey(nil, "pilot", "main", userID) != "" || replaceByUserKey(uuidv7.MustBytes(), "pilot", "main", nil) != "" {
+		t.Fatalf("expected empty replace key for missing ids")
+	}
+	if !isRoleRangeAssignable("pilot") || isRoleRangeAssignable("other_person") {
+		t.Fatalf("unexpected range-assignable role mapping")
+	}
+
+	if len(expandDateRange(time.Date(2026, 3, 21, 0, 0, 0, 0, time.UTC), time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC))) != 0 {
+		t.Fatalf("expected empty range when end before start")
+	}
+}
+
+func TestDutyRosterService_CRUDBranchesWithTx(t *testing.T) {
+	row := &dutyroster.DutyRoster{
+		ID:        uuidv7.MustBytes(),
+		BaseID:    uuidv7.MustBytes(),
+		DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+		UpdatedBy: uuidv7.MustBytes(),
+		CreatedBy: uuidv7.MustBytes(),
+	}
+	crews := []dutyroster.DutyRosterCrew{{
+		RoleCode: "pilot",
+		CrewType: "main",
+		UserID:   uuidv7.MustBytes(),
+	}}
+
+	t.Run("create inTx error", func(t *testing.T) {
+		svc := NewDutyRosterService(&dutyRosterRepoWithTxMock{txRepo: &dutyRosterTxRepoMock{}, inTxErr: errors.New("tx failed")})
+		if err := svc.Create(context.Background(), row, crews); err == nil {
+			t.Fatalf("expected create tx error")
+		}
+	})
+
+	t.Run("update with no crews", func(t *testing.T) {
+		tx := &dutyRosterTxRepoMock{
+			lockFn: func(_ context.Context, _ []byte) (*dutyroster.DutyRoster, error) {
+				return &dutyroster.DutyRoster{ID: row.ID, BaseID: row.BaseID, DutyDate: row.DutyDate}, nil
+			},
+		}
+		svc := NewDutyRosterService(&dutyRosterRepoWithTxMock{txRepo: tx})
+		if err := svc.Update(context.Background(), row, nil); err != nil {
+			t.Fatalf("expected update without crews success, got %v", err)
+		}
+	})
+
+	t.Run("delete lock error", func(t *testing.T) {
+		tx := &dutyRosterTxRepoMock{
+			lockFn: func(_ context.Context, _ []byte) (*dutyroster.DutyRoster, error) {
+				return nil, errors.New("lock failed")
+			},
+		}
+		svc := NewDutyRosterService(&dutyRosterRepoWithTxMock{txRepo: tx})
+		if err := svc.Delete(context.Background(), row.ID, row.UpdatedBy); err == nil {
+			t.Fatalf("expected delete lock error")
+		}
+	})
+}
+
+func TestDutyRosterService_ParsingAndValidationExtraBranches(t *testing.T) {
+	// Validate delete shift_date branches
+	start := time.Date(2026, 3, 21, 0, 0, 0, 0, time.UTC)
+	end := time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)
+	if errObj := validateDutyRosterDeleteCrews([]dutyroster.DutyRosterCrew{{RoleCode: "pilot", DateStart: &start}}); errObj == nil {
+		t.Fatalf("expected start/end pair validation error")
+	}
+	if errObj := validateDutyRosterDeleteCrews([]dutyroster.DutyRosterCrew{{RoleCode: "pilot", DateStart: &start, DateEnd: &end}}); errObj == nil {
+		t.Fatalf("expected end >= start validation error")
+	}
+	if errObj := validateDutyRosterDeleteCrews([]dutyroster.DutyRosterCrew{{RoleCode: "other_person", DateStart: &start}}); errObj != nil {
+		t.Fatalf("other_person should skip shift_date validation, got %#v", errObj)
+	}
+
+	if got := normalizeClockOrDefaultForCrew("", "07:00:00"); got != "07:00:00" {
+		t.Fatalf("expected default clock, got %q", got)
+	}
+	if got, errObj := normalizeClockInputForCrew("bad", "", "/p"); errObj == nil || got != "" {
+		t.Fatalf("expected invalid clock error")
+	}
+
+	// Parse shift range single token + invalid second token
+	s, e := ParseDutyRosterShiftRange("start 09:15")
+	if s != "09:15:00" || e != "09:15:00" {
+		t.Fatalf("expected single token shift, got %q-%q", s, e)
+	}
+	s, e = ParseDutyRosterShiftRange("09:00 xx:yy")
+	if s != "09:00:00" || e != "09:00:00" {
+		t.Fatalf("expected invalid second token fallback to start, got %q-%q", s, e)
+	}
+	if len(extractClockTokensForShift("")) != 0 {
+		t.Fatalf("expected no tokens for empty shift text")
+	}
+
+	now := time.Date(2026, 3, 18, 10, 0, 0, 0, time.UTC)
+	from, to, errObj := ParseDutyRosterDateRangeOrDefault("2026-03-10", "", now)
+	if errObj != nil || from.Format("2006-01-02") != "2026-03-10" || to.Format("2006-01-02") != "2026-03-31" {
+		t.Fatalf("unexpected only-from parse result")
+	}
+	from, to, errObj = ParseDutyRosterDateRangeOrDefault("", "2026-03-20", now)
+	if errObj != nil || from.Format("2006-01-02") != "2026-03-01" || to.Format("2006-01-02") != "2026-03-20" {
+		t.Fatalf("unexpected only-to parse result")
+	}
+}
+
+func TestDutyRosterService_BuildDeleteCrewsAndUUIDExtraBranches(t *testing.T) {
+	actor := uuidv7.MustBytes()
+	// nil detail branch
+	rows, errObj := BuildDutyRosterDeleteCrews([]byte(`{"data":{"attributes":{}}}`), actor)
+	if errObj != nil || rows != nil {
+		t.Fatalf("expected nil rows when detail omitted, got rows=%v err=%#v", rows, errObj)
+	}
+	// invalid payload branch
+	if _, errObj = BuildDutyRosterDeleteCrews([]byte(`not-json`), actor); errObj == nil {
+		t.Fatalf("expected invalid delete payload error")
+	}
+
+	// uuid conversion error branch
+	if got := uuidStringOrEmpty(context.Background(), []byte{1, 2, 3}); got != "" {
+		t.Fatalf("expected empty string for invalid uuid bytes, got %q", got)
+	}
+
+	if out, errObj := normalizeClockInputForCrew("", "", "/p"); errObj != nil || out != "" {
+		t.Fatalf("expected empty clock allowed, got out=%q err=%#v", out, errObj)
+	}
+	if s, e := ParseDutyRosterShiftRange("99:99 09:00"); s != "" || e != "09:00:00" {
+		t.Fatalf("expected invalid first token ignored by parse, got %q-%q", s, e)
+	}
+	if s, e := ParseDutyRosterShiftRange("09:00 99:99"); s != "09:00:00" || e != "" {
+		t.Fatalf("expected invalid second token cleared, got %q-%q", s, e)
+	}
+
+	svc := NewDutyRosterService(&dutyRosterRepoWithTxMock{txRepo: &dutyRosterTxRepoMock{}})
+	rows2, err := svc.DeleteCrews(context.Background(), uuidv7.MustBytes(), nil, uuidv7.MustBytes())
+	if err != nil || len(rows2) != 0 {
+		t.Fatalf("expected empty delete crews shortcut, got rows=%v err=%v", rows2, err)
+	}
+}
+
+func TestDutyRosterService_GroupMergeExtraBranches(t *testing.T) {
+	empty := GroupRostersByBase(nil)
+	merged := MergeEmptyBaseGroups(empty, []dutyroster.BaseView{{ID: uuidv7.MustBytes(), BaseName: "H1", BaseAbbreviation: "H1"}})
+	if len(merged) != 1 || len(merged[0].Attributes.Rosters) != 0 {
+		t.Fatalf("expected one empty hems base group, got %#v", merged)
+	}
+
+}
+
+func TestDutyRosterResource_AllRoleDetails(t *testing.T) {
+	header := dutyroster.HeaderView{
+		ID:               uuidv7.MustBytes(),
+		BaseID:           uuidv7.MustBytes(),
+		BaseName:         "Base B",
+		BaseAbbreviation: "BB",
+		DutyDate:         time.Date(2026, 3, 21, 0, 0, 0, 0, time.UTC),
+		CreatedAt:        time.Date(2026, 3, 21, 1, 0, 0, 0, time.UTC),
+		UpdatedAt:        time.Date(2026, 3, 21, 2, 0, 0, 0, time.UTC),
+	}
+	crews := []dutyroster.CrewView{
+		{ID: uuidv7.MustBytes(), UserID: uuidv7.MustBytes(), Name: "Pilot Main", RoleCode: "pilot", CrewType: "main", Supervisor: true},
+		{ID: uuidv7.MustBytes(), UserID: uuidv7.MustBytes(), Name: "Pilot Main", RoleCode: "pilot", CrewType: "main", Supervisor: true},
+		{ID: uuidv7.MustBytes(), UserID: uuidv7.MustBytes(), Name: "Doctor", RoleCode: "doctor"},
+		{ID: uuidv7.MustBytes(), UserID: uuidv7.MustBytes(), Name: "Rescuer", RoleCode: "rescuer"},
+		{ID: uuidv7.MustBytes(), UserID: uuidv7.MustBytes(), Name: "Helper", RoleCode: "helper"},
+		{ID: uuidv7.MustBytes(), Name: "Guest", RoleCode: "other_person", Email: "guest@example.com"},
+		{ID: uuidv7.MustBytes(), Name: "Unknown", RoleCode: "unknown"},
+	}
+	got := DutyRosterResource(context.Background(), header, crews)
+	if got.Attributes.ShiftTime.ShiftStart != "" || got.Attributes.ShiftTime.ShiftEnd != "" {
+		t.Fatalf("expected empty header shift in response when source empty")
+	}
+	if len(got.Attributes.Detail.Pilot) != 2 || len(got.Attributes.Detail.Doctor) != 1 || len(got.Attributes.Detail.Rescuer) != 1 || len(got.Attributes.Detail.Helper) != 1 {
+		t.Fatalf("expected all operational buckets mapped, got %#v", got.Attributes.Detail)
+	}
+	if len(got.Attributes.Detail.OtherPerson) != 2 {
+		t.Fatalf("expected unknown role falls into other_person bucket, got %d", len(got.Attributes.Detail.OtherPerson))
+	}
+}
+
+func mustUUID(t *testing.T) string {
+	t.Helper()
+	v, err := uuidv7.BytesToString(uuidv7.MustBytes())
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return v
+}
diff --git a/internal/service/easa_release_service.go b/internal/service/easa_release_service.go
new file mode 100644
index 0000000..3ee9f84
--- /dev/null
+++ b/internal/service/easa_release_service.go
@@ -0,0 +1,109 @@
+package service
+
+import (
+	"context"
+	"time"
+
+	easarelease "wucher/internal/domain/easa_release"
+)
+
+type EASAReleaseService struct{ repo easarelease.Repository }
+
+func NewEASAReleaseService(repo easarelease.Repository) *EASAReleaseService {
+	return &EASAReleaseService{repo: repo}
+}
+
+func (s *EASAReleaseService) Create(ctx context.Context, row *easarelease.EASARelease) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *EASAReleaseService) Update(ctx context.Context, row *easarelease.EASARelease) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *EASAReleaseService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *EASAReleaseService) GetByID(ctx context.Context, id []byte) (*easarelease.EASARelease, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+// GetByFlightID returns the current (newest non-voided) release for a flight.
+func (s *EASAReleaseService) GetByFlightID(ctx context.Context, flightID []byte) (*easarelease.EASARelease, error) {
+	return s.repo.GetByFlightID(ctx, flightID)
+}
+
+// GetByComplaintID returns the current (newest non-voided) release for a complaint.
+func (s *EASAReleaseService) GetByComplaintID(ctx context.Context, complaintID []byte) (*easarelease.EASARelease, error) {
+	return s.repo.GetByComplaintID(ctx, complaintID)
+}
+
+func (s *EASAReleaseService) ListByHelicopter(ctx context.Context, helicopterID []byte) ([]easarelease.EASARelease, error) {
+	return s.repo.ListByHelicopter(ctx, helicopterID)
+}
+
+func (s *EASAReleaseService) GetLatestByHelicopter(ctx context.Context, helicopterID []byte) (*easarelease.EASARelease, error) {
+	return s.repo.GetLatestByHelicopter(ctx, helicopterID)
+}
+
+func (s *EASAReleaseService) GetActiveByHelicopter(ctx context.Context, helicopterID []byte) (*easarelease.EASARelease, error) {
+	return s.repo.GetActiveByHelicopter(ctx, helicopterID)
+}
+
+// Sign stamps the maintenance release as signed (active). A signed release closes
+// the defects of its flight inspection. Re-signing an already-signed release fails.
+func (s *EASAReleaseService) Sign(ctx context.Context, id []byte, signerID []byte) error {
+	row, err := s.repo.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+	if row == nil {
+		return easarelease.ErrNotFound
+	}
+	if row.SignedAt != nil {
+		return easarelease.ErrAlreadySigned
+	}
+	if len(row.MissingSignFields()) > 0 {
+		return easarelease.ErrIncompleteForSign
+	}
+	now := time.Now().UTC()
+	row.SignedAt = &now
+	row.SignedBy = append([]byte(nil), signerID...)
+	row.UpdatedBy = append([]byte(nil), signerID...)
+	return s.repo.Update(ctx, row)
+}
+
+// Amend supersedes the current release: it voids (soft-deletes) the current one and
+// creates a fresh unsigned copy for the same flight inspection, returning the new id.
+func (s *EASAReleaseService) Amend(ctx context.Context, currentID []byte, reason string, actor []byte) ([]byte, error) {
+	cur, err := s.repo.GetByID(ctx, currentID)
+	if err != nil {
+		return nil, err
+	}
+	if cur == nil {
+		return nil, easarelease.ErrNotFound
+	}
+	if err := s.repo.VoidByID(ctx, currentID, reason, actor); err != nil {
+		return nil, err
+	}
+	next := &easarelease.EASARelease{
+		HelicopterID:               append([]byte(nil), cur.HelicopterID...),
+		FlightID:                   append([]byte(nil), cur.FlightID...),
+		ComplaintID:                append([]byte(nil), cur.ComplaintID...),
+		EASADate:                   cur.EASADate,
+		EASAACHours:                cur.EASAACHours,
+		EASALocation:               cur.EASALocation,
+		EASAWONo:                   cur.EASAWONo,
+		EASAMaintManualRevAirframe: cur.EASAMaintManualRevAirframe,
+		EASAMaintManualRevEngine:   cur.EASAMaintManualRevEngine,
+		EASASignerID:               cur.EASASignerID,
+		EASAPermitNo:               cur.EASAPermitNo,
+		CreatedBy:                  append([]byte(nil), actor...),
+		UpdatedBy:                  append([]byte(nil), actor...),
+	}
+	if err := s.repo.Create(ctx, next); err != nil {
+		return nil, err
+	}
+	return next.ID, nil
+}
diff --git a/internal/service/easa_release_service_test.go b/internal/service/easa_release_service_test.go
new file mode 100644
index 0000000..dc91a4d
--- /dev/null
+++ b/internal/service/easa_release_service_test.go
@@ -0,0 +1,173 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	easarelease "wucher/internal/domain/easa_release"
+)
+
+type stubEASARepo struct {
+	row       *easarelease.EASARelease
+	updated   *easarelease.EASARelease
+	created   *easarelease.EASARelease
+	voidedID  []byte
+	createErr error
+	getErr    error
+	voidErr   error
+}
+
+func (s *stubEASARepo) Create(_ context.Context, row *easarelease.EASARelease) error {
+	s.created = row
+	if len(row.ID) == 0 {
+		row.ID = []byte("newid0123456789a")
+	}
+	return s.createErr
+}
+func (s *stubEASARepo) Update(_ context.Context, row *easarelease.EASARelease) error {
+	s.updated = row
+	return nil
+}
+func (s *stubEASARepo) Delete(_ context.Context, _, _ []byte) error { return nil }
+func (s *stubEASARepo) GetByID(_ context.Context, _ []byte) (*easarelease.EASARelease, error) {
+	return s.row, s.getErr
+}
+func (s *stubEASARepo) GetByFlightID(_ context.Context, _ []byte) (*easarelease.EASARelease, error) {
+	return s.row, s.getErr
+}
+func (s *stubEASARepo) GetByComplaintID(_ context.Context, _ []byte) (*easarelease.EASARelease, error) {
+	return s.row, s.getErr
+}
+func (s *stubEASARepo) ListByHelicopter(_ context.Context, _ []byte) ([]easarelease.EASARelease, error) {
+	if s.row != nil {
+		return []easarelease.EASARelease{*s.row}, nil
+	}
+	return nil, nil
+}
+func (s *stubEASARepo) GetLatestByHelicopter(_ context.Context, _ []byte) (*easarelease.EASARelease, error) {
+	return s.row, nil
+}
+func (s *stubEASARepo) GetActiveByHelicopter(_ context.Context, _ []byte) (*easarelease.EASARelease, error) {
+	return s.row, nil
+}
+func (s *stubEASARepo) VoidByID(_ context.Context, id []byte, _ string, _ []byte) error {
+	s.voidedID = id
+	return s.voidErr
+}
+
+func completeUnsigned() *easarelease.EASARelease {
+	now := time.Now()
+	return &easarelease.EASARelease{
+		ID:           []byte("0123456789abcdef"),
+		HelicopterID: []byte("fedcba9876543210"),
+		EASADate:     &now,
+		EASAACHours:  ptr("1245.3"),
+		EASALocation: ptr("LOWI"),
+		EASAWONo:     ptr("WO-1"),
+		EASASignerID: ptr("019d61db-53c6-7280-87ec-e65f205c6d3b"),
+	}
+}
+
+func TestEASAReleaseServiceSign(t *testing.T) {
+	actor := []byte("aaaaaaaaaaaaaaaa")
+	ctx := context.Background()
+
+	if err := NewEASAReleaseService(&stubEASARepo{row: nil}).Sign(ctx, []byte("x"), actor); !errors.Is(err, easarelease.ErrNotFound) {
+		t.Fatalf("want ErrNotFound, got %v", err)
+	}
+
+	incompleteRepo := &stubEASARepo{row: &easarelease.EASARelease{ID: []byte("0123456789abcdef")}}
+	if err := NewEASAReleaseService(incompleteRepo).Sign(ctx, incompleteRepo.row.ID, actor); !errors.Is(err, easarelease.ErrIncompleteForSign) {
+		t.Fatalf("want ErrIncompleteForSign, got %v", err)
+	}
+	if incompleteRepo.updated != nil {
+		t.Fatal("incomplete release must not be persisted signed")
+	}
+
+	signed := completeUnsigned()
+	at := time.Now()
+	signed.SignedAt = &at
+	if err := NewEASAReleaseService(&stubEASARepo{row: signed}).Sign(ctx, signed.ID, actor); !errors.Is(err, easarelease.ErrAlreadySigned) {
+		t.Fatalf("want ErrAlreadySigned, got %v", err)
+	}
+
+	okRepo := &stubEASARepo{row: completeUnsigned()}
+	if err := NewEASAReleaseService(okRepo).Sign(ctx, okRepo.row.ID, actor); err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	if okRepo.updated == nil || okRepo.updated.SignedAt == nil || string(okRepo.updated.SignedBy) != string(actor) {
+		t.Fatal("complete release should be persisted signed by actor")
+	}
+}
+
+func TestEASAReleaseServiceAmendAndDelegation(t *testing.T) {
+	ctx := context.Background()
+	repo := &stubEASARepo{row: completeUnsigned()}
+	svc := NewEASAReleaseService(repo)
+
+	newID, err := svc.Amend(ctx, repo.row.ID, "superseded", []byte("actor"))
+	if err != nil {
+		t.Fatalf("Amend err: %v", err)
+	}
+	if string(repo.voidedID) != string(repo.row.ID) {
+		t.Fatal("Amend should void the current release")
+	}
+	if repo.created == nil || string(repo.created.HelicopterID) != string(repo.row.HelicopterID) {
+		t.Fatal("Amend should create a copy for the same helicopter")
+	}
+	if len(newID) == 0 {
+		t.Fatal("Amend should return the new id")
+	}
+
+	if _, err := svc.GetLatestByHelicopter(ctx, []byte("h")); err != nil {
+		t.Fatalf("GetLatestByHelicopter: %v", err)
+	}
+	if _, err := svc.GetActiveByHelicopter(ctx, []byte("h")); err != nil {
+		t.Fatalf("GetActiveByHelicopter: %v", err)
+	}
+	if rows, err := svc.ListByHelicopter(ctx, []byte("h")); err != nil || len(rows) != 1 {
+		t.Fatalf("ListByHelicopter: %v", err)
+	}
+	if err := svc.Delete(ctx, []byte("x"), nil); err != nil {
+		t.Fatalf("Delete: %v", err)
+	}
+	if _, err := svc.GetByID(ctx, []byte("x")); err != nil {
+		t.Fatalf("GetByID: %v", err)
+	}
+
+	// Amend on missing release.
+	if _, err := NewEASAReleaseService(&stubEASARepo{row: nil}).Amend(ctx, []byte("x"), "r", nil); !errors.Is(err, easarelease.ErrNotFound) {
+		t.Fatalf("Amend missing: want ErrNotFound, got %v", err)
+	}
+	// Amend with void error.
+	if _, err := NewEASAReleaseService(&stubEASARepo{row: completeUnsigned(), voidErr: errors.New("boom")}).Amend(ctx, []byte("x"), "r", nil); err == nil {
+		t.Fatal("Amend should propagate void error")
+	}
+	// Amend with create error.
+	if _, err := NewEASAReleaseService(&stubEASARepo{row: completeUnsigned(), createErr: errors.New("boom")}).Amend(ctx, []byte("x"), "r", nil); err == nil {
+		t.Fatal("Amend should propagate create error")
+	}
+	// Amend with GetByID error.
+	if _, err := NewEASAReleaseService(&stubEASARepo{getErr: errors.New("boom")}).Amend(ctx, []byte("x"), "r", nil); err == nil {
+		t.Fatal("Amend should propagate GetByID error")
+	}
+}
+
+func TestEASAReleaseServiceCreateUpdateAndErrors(t *testing.T) {
+	ctx := context.Background()
+	repo := &stubEASARepo{}
+	svc := NewEASAReleaseService(repo)
+	row := completeUnsigned()
+	if err := svc.Create(ctx, row); err != nil || repo.created != row {
+		t.Fatalf("Create not delegated: %v", err)
+	}
+	if err := svc.Update(ctx, row); err != nil || repo.updated != row {
+		t.Fatalf("Update not delegated: %v", err)
+	}
+	// Sign with GetByID error.
+	if err := NewEASAReleaseService(&stubEASARepo{getErr: errors.New("boom")}).Sign(ctx, []byte("x"), nil); err == nil {
+		t.Fatal("Sign should propagate GetByID error")
+	}
+}
diff --git a/internal/service/email_job_handler.go b/internal/service/email_job_handler.go
new file mode 100644
index 0000000..34dedb7
--- /dev/null
+++ b/internal/service/email_job_handler.go
@@ -0,0 +1,119 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"net"
+	"strings"
+
+	"github.com/aws/smithy-go"
+
+	"wucher/internal/queue"
+)
+
+type EmailDeliveryHandler struct {
+	sender EmailSender
+	logger *slog.Logger
+}
+
+func NewEmailDeliveryHandler(sender EmailSender, logger *slog.Logger) *EmailDeliveryHandler {
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &EmailDeliveryHandler{
+		sender: sender,
+		logger: logger,
+	}
+}
+
+func (h *EmailDeliveryHandler) Handle(ctx context.Context, envelope *queue.Envelope) error {
+	if h.sender == nil {
+		return queue.Permanent(errors.New("email sender is required"))
+	}
+	if envelope == nil {
+		return queue.Permanent(errors.New("email envelope is required"))
+	}
+	if err := envelope.Payload.Validate(); err != nil {
+		return queue.Permanent(err)
+	}
+
+	job := envelope.Payload
+	shouldSkipSend := strings.EqualFold(strings.TrimSpace(job.Metadata["skip_send"]), "true")
+	// Defense-in-depth: register verification emails should never be delivered.
+	if !shouldSkipSend &&
+		strings.EqualFold(strings.TrimSpace(job.MessageType), "email_verify") &&
+		strings.EqualFold(strings.TrimSpace(job.Tags["source"]), "register") {
+		shouldSkipSend = true
+	}
+	if shouldSkipSend {
+		h.logger.Info("email delivery skipped",
+			slog.String("message_id", envelope.MessageID),
+			slog.String("job_type", job.NormalizedType()),
+			slog.String("recipient_hash", job.RecipientHash()),
+			slog.String("correlation_id", envelope.CorrelationID),
+		)
+		return nil
+	}
+	result, err := h.sender.Send(ctx, job)
+	if err != nil {
+		classified := classifyDeliveryError(err)
+		h.logger.Error("email delivery failed",
+			slog.String("message_id", envelope.MessageID),
+			slog.String("job_type", job.NormalizedType()),
+			slog.String("recipient_hash", job.RecipientHash()),
+			slog.String("correlation_id", envelope.CorrelationID),
+			slog.Any("error", err),
+		)
+		return classified
+	}
+
+	h.logger.Info("email delivered",
+		slog.String("message_id", envelope.MessageID),
+		slog.String("job_type", job.NormalizedType()),
+		slog.String("recipient_hash", job.RecipientHash()),
+		slog.String("correlation_id", envelope.CorrelationID),
+		slog.String("provider", result.Provider),
+		slog.String("provider_message_id", result.ProviderMessageID),
+		slog.String("provider_request_id", result.RequestID),
+	)
+	return nil
+}
+
+func classifyDeliveryError(err error) error {
+	if err == nil {
+		return nil
+	}
+	if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+		return queue.Transient(err)
+	}
+	var netErr net.Error
+	if errors.As(err, &netErr) {
+		return queue.Transient(err)
+	}
+	var apiErr smithy.APIError
+	if errors.As(err, &apiErr) {
+		code := strings.ToLower(strings.TrimSpace(apiErr.ErrorCode()))
+		switch code {
+		case "throttling", "throttlingexception", "toomanyrequestsexception", "serviceunavailableexception", "internalserviceerror", "sendingpausedexception":
+			return queue.Transient(err)
+		case "message_rejected", "messagerejected", "badrequestexception", "mailfromdomainnotverifiedexception", "configurationsetdoesnotexistexception", "notfoundexception":
+			return queue.Permanent(err)
+		}
+	}
+	message := strings.ToLower(strings.TrimSpace(err.Error()))
+	switch {
+	case strings.Contains(message, "recipient is required"):
+		return queue.Permanent(err)
+	case strings.Contains(message, "subject is required"):
+		return queue.Permanent(err)
+	case strings.Contains(message, "body is required"):
+		return queue.Permanent(err)
+	case strings.Contains(message, "invalid email job"):
+		return queue.Permanent(err)
+	case strings.Contains(message, "ses is not configured"):
+		return queue.Permanent(err)
+	default:
+		return queue.Transient(err)
+	}
+}
diff --git a/internal/service/email_job_handler_test.go b/internal/service/email_job_handler_test.go
new file mode 100644
index 0000000..8a74aad
--- /dev/null
+++ b/internal/service/email_job_handler_test.go
@@ -0,0 +1,93 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/queue"
+)
+
+type emailSenderStub struct {
+	sendFn func(ctx context.Context, job EmailJob) (EmailDeliveryResult, error)
+}
+
+func (s emailSenderStub) Send(ctx context.Context, job EmailJob) (EmailDeliveryResult, error) {
+	if s.sendFn != nil {
+		return s.sendFn(ctx, job)
+	}
+	return EmailDeliveryResult{}, nil
+}
+
+func TestEmailDeliveryHandler_Handle_SkipSend(t *testing.T) {
+	called := false
+	handler := NewEmailDeliveryHandler(emailSenderStub{
+		sendFn: func(context.Context, EmailJob) (EmailDeliveryResult, error) {
+			called = true
+			return EmailDeliveryResult{}, nil
+		},
+	}, nil)
+
+	err := handler.Handle(context.Background(), &queue.Envelope{
+		MessageID: "msg-1",
+		Payload: EmailJob{
+			To:       "user@example.com",
+			Subject:  "Verify",
+			TextBody: "Body",
+			Metadata: map[string]string{
+				"skip_send": "true",
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("expected nil error, got %v", err)
+	}
+	if called {
+		t.Fatalf("expected sender not called when skip_send=true")
+	}
+}
+
+func TestEmailDeliveryHandler_Handle_SendWhenNotSkipped(t *testing.T) {
+	called := false
+	handler := NewEmailDeliveryHandler(emailSenderStub{
+		sendFn: func(context.Context, EmailJob) (EmailDeliveryResult, error) {
+			called = true
+			return EmailDeliveryResult{}, nil
+		},
+	}, nil)
+
+	err := handler.Handle(context.Background(), &queue.Envelope{
+		MessageID: "msg-2",
+		Payload: EmailJob{
+			To:       "user@example.com",
+			Subject:  "Verify",
+			TextBody: "Body",
+		},
+	})
+	if err != nil {
+		t.Fatalf("expected nil error, got %v", err)
+	}
+	if !called {
+		t.Fatalf("expected sender called when skip_send is absent")
+	}
+}
+
+func TestEmailDeliveryHandler_Handle_ClassifyErrorWhenNotSkipped(t *testing.T) {
+	handler := NewEmailDeliveryHandler(emailSenderStub{
+		sendFn: func(context.Context, EmailJob) (EmailDeliveryResult, error) {
+			return EmailDeliveryResult{}, errors.New("network timeout")
+		},
+	}, nil)
+
+	err := handler.Handle(context.Background(), &queue.Envelope{
+		MessageID: "msg-3",
+		Payload: EmailJob{
+			To:       "user@example.com",
+			Subject:  "Verify",
+			TextBody: "Body",
+		},
+	})
+	if err == nil {
+		t.Fatalf("expected classified error")
+	}
+}
diff --git a/internal/service/email_queue.go b/internal/service/email_queue.go
new file mode 100644
index 0000000..61ccc44
--- /dev/null
+++ b/internal/service/email_queue.go
@@ -0,0 +1,43 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+
+	"wucher/internal/queue"
+)
+
+type EmailJob = queue.EmailJob
+
+type EmailQueue = queue.EmailJobProducer
+
+func EncodeEmailJob(job EmailJob) ([]byte, error) {
+	return json.Marshal(job.Canonical())
+}
+
+func DecodeEmailJob(b []byte) (*EmailJob, error) {
+	var job EmailJob
+	if err := json.Unmarshal(b, &job); err != nil {
+		return nil, err
+	}
+	job = job.Canonical()
+	if err := job.Validate(); err != nil {
+		return nil, err
+	}
+	return &job, nil
+}
+
+type emailQueueAdapter struct {
+	producer queue.EmailJobProducer
+}
+
+func (a emailQueueAdapter) Enqueue(ctx context.Context, job EmailJob) error {
+	return a.producer.Enqueue(ctx, job)
+}
+
+func AdaptEmailQueue(producer queue.EmailJobProducer) EmailQueue {
+	if producer == nil {
+		return nil
+	}
+	return emailQueueAdapter{producer: producer}
+}
diff --git a/internal/service/email_queue_test.go b/internal/service/email_queue_test.go
new file mode 100644
index 0000000..7d4fa2b
--- /dev/null
+++ b/internal/service/email_queue_test.go
@@ -0,0 +1,38 @@
+package service
+
+import "testing"
+
+func TestEncodeEmailJob(t *testing.T) {
+	data, err := EncodeEmailJob(EmailJob{
+		To:      "user@example.com",
+		Subject: "Welcome",
+		Body:    "Hello",
+	})
+	if err != nil {
+		t.Fatalf("encode failed: %v", err)
+	}
+	if len(data) == 0 {
+		t.Fatalf("expected encoded payload")
+	}
+}
+
+func TestDecodeEmailJob(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		job, err := DecodeEmailJob([]byte(`{"to":"user@example.com","subject":"Welcome","body":"Hello"}`))
+		if err != nil {
+			t.Fatalf("decode failed: %v", err)
+		}
+		if job == nil {
+			t.Fatalf("expected email job")
+		}
+		if job.To != "user@example.com" || job.Subject != "Welcome" || job.TextBody != "Hello" {
+			t.Fatalf("unexpected decoded value: %+v", job)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		if _, err := DecodeEmailJob([]byte(`{"to":`)); err == nil {
+			t.Fatalf("expected decode error")
+		}
+	})
+}
diff --git a/internal/service/email_raw_mime.go b/internal/service/email_raw_mime.go
new file mode 100644
index 0000000..3594621
--- /dev/null
+++ b/internal/service/email_raw_mime.go
@@ -0,0 +1,138 @@
+package service
+
+import (
+	"bytes"
+	"encoding/base64"
+	"fmt"
+	"mime/quotedprintable"
+	"strings"
+
+	sestypes "github.com/aws/aws-sdk-go-v2/service/sesv2/types"
+
+	"wucher/internal/queue"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func buildSESRawContent(from string, to, cc, replyTo []string, job queue.EmailJob) (*sestypes.EmailContent, error) {
+	mixedBoundary := randomMIMEBoundary("mixed")
+	relatedBoundary := randomMIMEBoundary("related")
+	alternativeBoundary := randomMIMEBoundary("alt")
+
+	var buf bytes.Buffer
+	writeMIMEHeader(&buf, "From", from)
+	if len(to) > 0 {
+		writeMIMEHeader(&buf, "To", strings.Join(to, ", "))
+	}
+	if len(cc) > 0 {
+		writeMIMEHeader(&buf, "Cc", strings.Join(cc, ", "))
+	}
+	if len(replyTo) > 0 {
+		writeMIMEHeader(&buf, "Reply-To", strings.Join(replyTo, ", "))
+	}
+	writeMIMEHeader(&buf, "Subject", sanitizeSubject(job.Subject))
+	writeMIMEHeader(&buf, "MIME-Version", "1.0")
+	writeMIMEHeader(&buf, "Content-Type", fmt.Sprintf(`multipart/mixed; boundary="%s"`, mixedBoundary))
+	buf.WriteString("\r\n")
+
+	writeBoundary(&buf, mixedBoundary)
+	writeMIMEHeader(&buf, "Content-Type", fmt.Sprintf(`multipart/related; boundary="%s"`, relatedBoundary))
+	buf.WriteString("\r\n")
+
+	writeBoundary(&buf, relatedBoundary)
+	writeMIMEHeader(&buf, "Content-Type", fmt.Sprintf(`multipart/alternative; boundary="%s"`, alternativeBoundary))
+	buf.WriteString("\r\n")
+
+	if textBody := strings.TrimSpace(job.TextBodyValue()); textBody != "" {
+		writeBoundary(&buf, alternativeBoundary)
+		writeTextPart(&buf, "text/plain", textBody)
+	}
+	if htmlBody := strings.TrimSpace(job.HTMLBody); htmlBody != "" {
+		writeBoundary(&buf, alternativeBoundary)
+		writeTextPart(&buf, "text/html", htmlBody)
+	}
+	writeClosingBoundary(&buf, alternativeBoundary)
+
+	for i := range job.Attachments {
+		writeBoundary(&buf, relatedBoundary)
+		writeAttachmentPart(&buf, job.Attachments[i])
+	}
+	writeClosingBoundary(&buf, relatedBoundary)
+	writeClosingBoundary(&buf, mixedBoundary)
+
+	return &sestypes.EmailContent{
+		Raw: &sestypes.RawMessage{Data: buf.Bytes()},
+	}, nil
+}
+
+func writeTextPart(buf *bytes.Buffer, contentType, body string) {
+	writeMIMEHeader(buf, "Content-Type", contentType+`; charset="UTF-8"`)
+	writeMIMEHeader(buf, "Content-Transfer-Encoding", "quoted-printable")
+	buf.WriteString("\r\n")
+	qp := quotedprintable.NewWriter(buf)
+	_, _ = qp.Write([]byte(body))
+	_ = qp.Close()
+	buf.WriteString("\r\n")
+}
+
+func writeAttachmentPart(buf *bytes.Buffer, attachment queue.EmailAttachment) {
+	filename := attachment.Filename
+	if filename == "" {
+		filename = "attachment"
+	}
+	writeMIMEHeader(buf, "Content-Type", fmt.Sprintf(`%s; name="%s"`, attachment.ContentType, escapeMIMEHeaderValue(filename)))
+	writeMIMEHeader(buf, "Content-Transfer-Encoding", "base64")
+	disposition := "attachment"
+	if attachment.Inline {
+		disposition = "inline"
+	}
+	writeMIMEHeader(buf, "Content-Disposition", fmt.Sprintf(`%s; filename="%s"`, disposition, escapeMIMEHeaderValue(filename)))
+	if attachment.Inline && strings.TrimSpace(attachment.ContentID) != "" {
+		writeMIMEHeader(buf, "Content-ID", "<"+strings.TrimSpace(attachment.ContentID)+">")
+	}
+	buf.WriteString("\r\n")
+	writeBase64Lines(buf, attachment.Content)
+}
+
+func writeBase64Lines(buf *bytes.Buffer, payload []byte) {
+	encoded := base64.StdEncoding.EncodeToString(payload)
+	for len(encoded) > 76 {
+		buf.WriteString(encoded[:76])
+		buf.WriteString("\r\n")
+		encoded = encoded[76:]
+	}
+	if encoded != "" {
+		buf.WriteString(encoded)
+		buf.WriteString("\r\n")
+	}
+}
+
+func writeMIMEHeader(buf *bytes.Buffer, key, value string) {
+	buf.WriteString(key)
+	buf.WriteString(": ")
+	buf.WriteString(value)
+	buf.WriteString("\r\n")
+}
+
+func writeBoundary(buf *bytes.Buffer, boundary string) {
+	buf.WriteString("--")
+	buf.WriteString(boundary)
+	buf.WriteString("\r\n")
+}
+
+func writeClosingBoundary(buf *bytes.Buffer, boundary string) {
+	buf.WriteString("--")
+	buf.WriteString(boundary)
+	buf.WriteString("--\r\n")
+}
+
+func randomMIMEBoundary(prefix string) string {
+	id, err := uuidv7.String(uuidv7.MustNew())
+	if err != nil {
+		return prefix + "_fallback"
+	}
+	return prefix + "_" + strings.ReplaceAll(id, "-", "")
+}
+
+func escapeMIMEHeaderValue(value string) string {
+	return strings.ReplaceAll(strings.TrimSpace(value), `"`, `'`)
+}
diff --git a/internal/service/email_sender.go b/internal/service/email_sender.go
new file mode 100644
index 0000000..276198a
--- /dev/null
+++ b/internal/service/email_sender.go
@@ -0,0 +1,17 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/queue"
+)
+
+type EmailDeliveryResult struct {
+	Provider          string
+	ProviderMessageID string
+	RequestID         string
+}
+
+type EmailSender interface {
+	Send(ctx context.Context, job queue.EmailJob) (EmailDeliveryResult, error)
+}
diff --git a/internal/service/facility_service.go b/internal/service/facility_service.go
new file mode 100644
index 0000000..c5ad040
--- /dev/null
+++ b/internal/service/facility_service.go
@@ -0,0 +1,52 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/facility"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type FacilityService struct {
+	repo facility.Repository
+}
+
+func NewFacilityService(repo facility.Repository) *FacilityService {
+	return &FacilityService{repo: repo}
+}
+
+func (s *FacilityService) Create(ctx context.Context, f *facility.Facility) error {
+	return s.repo.Create(ctx, f)
+}
+
+func (s *FacilityService) Update(ctx context.Context, f *facility.Facility) error {
+	return s.repo.Update(ctx, f)
+}
+
+func (s *FacilityService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *FacilityService) GetByID(ctx context.Context, id []byte) (*facility.Facility, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *FacilityService) List(ctx context.Context, filter, category, sort string, limit, offset int) ([]facility.Facility, int64, error) {
+	return s.repo.List(ctx, filter, category, normalizeFacilitySort(sort), limit, offset)
+}
+
+func normalizeFacilitySort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", true)),
+			"sortkey",
+		),
+		sortField("category"),
+		sortField("name"),
+		sortField("type"),
+		sortField("is_active"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/facility_service_test.go b/internal/service/facility_service_test.go
new file mode 100644
index 0000000..342ff8e
--- /dev/null
+++ b/internal/service/facility_service_test.go
@@ -0,0 +1,227 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/facility"
+)
+
+type facilityRepoMock struct {
+	createCalled  bool
+	updateCalled  bool
+	deleteCalled  bool
+	getByIDCalled bool
+	listCalled    bool
+
+	lastCreate       *facility.Facility
+	lastUpdate       *facility.Facility
+	lastDeleteID     []byte
+	lastGetByID      []byte
+	lastListFilter   string
+	lastListCategory string
+	lastListSort     string
+	lastListLimit    int
+	lastListOffset   int
+
+	getByIDResult *facility.Facility
+	listResult    []facility.Facility
+	listTotal     int64
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+}
+
+func (m *facilityRepoMock) Create(_ context.Context, row *facility.Facility) error {
+	m.createCalled = true
+	m.lastCreate = row
+	return m.createErr
+}
+
+func (m *facilityRepoMock) Update(_ context.Context, row *facility.Facility) error {
+	m.updateCalled = true
+	m.lastUpdate = row
+	return m.updateErr
+}
+
+func (m *facilityRepoMock) Delete(_ context.Context, id []byte, _ []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	return m.deleteErr
+}
+
+func (m *facilityRepoMock) GetByID(_ context.Context, id []byte) (*facility.Facility, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *facilityRepoMock) List(_ context.Context, filter, category, sort string, limit, offset int) ([]facility.Facility, int64, error) {
+	m.listCalled = true
+	m.lastListFilter = filter
+	m.lastListCategory = category
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listResult, m.listTotal, m.listErr
+}
+
+func TestNewFacilityService(t *testing.T) {
+	repo := &facilityRepoMock{}
+	svc := NewFacilityService(repo)
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service and repo initialized")
+	}
+}
+
+func TestFacilityServiceCreate(t *testing.T) {
+	repo := &facilityRepoMock{}
+	svc := NewFacilityService(repo)
+	row := &facility.Facility{Category: "HEMS", Name: "HEC Sling", Type: "Sling"}
+
+	if err := svc.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.createCalled || repo.lastCreate != row {
+		t.Fatalf("expected Create forwarded to repo")
+	}
+
+	repo.createErr = errors.New("create failed")
+	if err := svc.Create(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestFacilityServiceUpdate(t *testing.T) {
+	repo := &facilityRepoMock{}
+	svc := NewFacilityService(repo)
+	row := &facility.Facility{Category: "HEMS", Name: "HEC Sling", Type: "Sling"}
+
+	if err := svc.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateCalled || repo.lastUpdate != row {
+		t.Fatalf("expected Update forwarded to repo")
+	}
+
+	repo.updateErr = errors.New("update failed")
+	if err := svc.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestFacilityServiceDelete(t *testing.T) {
+	repo := &facilityRepoMock{}
+	svc := NewFacilityService(repo)
+	id := []byte("id")
+
+	if err := svc.Delete(context.Background(), id, nil); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.deleteCalled {
+		t.Fatalf("expected Delete forwarded to repo")
+	}
+	if string(repo.lastDeleteID) != string(id) {
+		t.Fatalf("expected delete id forwarded")
+	}
+
+	repo.deleteErr = errors.New("delete failed")
+	if err := svc.Delete(context.Background(), id, nil); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestFacilityServiceGetByID(t *testing.T) {
+	expected := &facility.Facility{Category: "HEMS", Name: "HEC Sling", Type: "Sling"}
+	repo := &facilityRepoMock{getByIDResult: expected}
+	svc := NewFacilityService(repo)
+	id := []byte("id")
+
+	got, err := svc.GetByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != expected {
+		t.Fatalf("unexpected result")
+	}
+	if !repo.getByIDCalled || string(repo.lastGetByID) != string(id) {
+		t.Fatalf("expected GetByID forwarded")
+	}
+
+	repo.getByIDErr = errors.New("get failed")
+	if _, err := svc.GetByID(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestFacilityServiceList(t *testing.T) {
+	repo := &facilityRepoMock{
+		listResult: []facility.Facility{{Category: "HEMS", Name: "HEC Sling", Type: "Sling"}},
+		listTotal:  1,
+	}
+	svc := NewFacilityService(repo)
+
+	rows, total, err := svc.List(context.Background(), "find", "HEMS", "-name", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if !repo.listCalled {
+		t.Fatalf("expected List forwarded to repo")
+	}
+	if repo.lastListFilter != "find" || repo.lastListCategory != "HEMS" || repo.lastListSort != "name DESC" || repo.lastListLimit != 10 || repo.lastListOffset != 20 {
+		t.Fatalf("unexpected list args forwarded")
+	}
+
+	rows, total, err = svc.List(context.Background(), "find", "HEMS", "sortkey", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC" {
+		t.Fatalf("unexpected sortkey args forwarded: %q", repo.lastListSort)
+	}
+
+	repo.listErr = errors.New("list failed")
+	if _, _, err := svc.List(context.Background(), "", "", "unknown", 1, 0); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+	if repo.lastListSort != "" {
+		t.Fatalf("expected unknown sort normalized to empty")
+	}
+}
+
+func TestNormalizeFacilitySort(t *testing.T) {
+	cases := map[string]string{
+		"sortkey":     "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC",
+		"-sortkey":    "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC",
+		"category":    "category ASC",
+		"-category":   "category DESC",
+		"name":        "name ASC",
+		"-name":       "name DESC",
+		"type":        "type ASC",
+		"-type":       "type DESC",
+		"is_active":   "is_active ASC",
+		"-is_active":  "is_active DESC",
+		"created_at":  "created_at ASC",
+		"-created_at": "created_at DESC",
+		"updated_at":  "updated_at ASC",
+		"-updated_at": "updated_at DESC",
+		"unknown":     "",
+		"":            "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeFacilitySort(in); got != want {
+			t.Fatalf("normalizeFacilitySort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/federal_state_service.go b/internal/service/federal_state_service.go
new file mode 100644
index 0000000..38c6b1b
--- /dev/null
+++ b/internal/service/federal_state_service.go
@@ -0,0 +1,51 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/federal_state"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type FederalStateService struct {
+	repo federal_state.Repository
+}
+
+func NewFederalStateService(repo federal_state.Repository) *FederalStateService {
+	return &FederalStateService{repo: repo}
+}
+
+func (s *FederalStateService) Create(ctx context.Context, row *federal_state.FederalState) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *FederalStateService) Update(ctx context.Context, row *federal_state.FederalState) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *FederalStateService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *FederalStateService) GetByID(ctx context.Context, id []byte) (*federal_state.FederalState, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *FederalStateService) List(ctx context.Context, filter, sort string, limit, offset int, landID []byte, landName string) ([]federal_state.FederalState, int64, error) {
+	return s.repo.List(ctx, filter, normalizeFederalStateSort(sort), limit, offset, landID, landName)
+}
+
+func normalizeFederalStateSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", true)),
+			"sortkey",
+		),
+		sortField("name"),
+		sortField("sortkey", "sortkey", "sort_key"),
+		sortField("is_active"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/federal_state_service_test.go b/internal/service/federal_state_service_test.go
new file mode 100644
index 0000000..bb853a9
--- /dev/null
+++ b/internal/service/federal_state_service_test.go
@@ -0,0 +1,217 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/federal_state"
+)
+
+type federalStateRepoMock struct {
+	createCalled  bool
+	updateCalled  bool
+	deleteCalled  bool
+	getByIDCalled bool
+	listCalled    bool
+
+	lastCreate     *federal_state.FederalState
+	lastUpdate     *federal_state.FederalState
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastGetByID    []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+	lastListLandID []byte
+	lastLandName   string
+
+	getByIDResult *federal_state.FederalState
+	listResult    []federal_state.FederalState
+	listTotal     int64
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+}
+
+func (m *federalStateRepoMock) Create(_ context.Context, o *federal_state.FederalState) error {
+	m.createCalled = true
+	m.lastCreate = o
+	return m.createErr
+}
+
+func (m *federalStateRepoMock) Update(_ context.Context, o *federal_state.FederalState) error {
+	m.updateCalled = true
+	m.lastUpdate = o
+	return m.updateErr
+}
+
+func (m *federalStateRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return m.deleteErr
+}
+
+func (m *federalStateRepoMock) GetByID(_ context.Context, id []byte) (*federal_state.FederalState, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *federalStateRepoMock) List(_ context.Context, filter, sort string, limit, offset int, landID []byte, landName string) ([]federal_state.FederalState, int64, error) {
+	m.listCalled = true
+	m.lastListFilter = filter
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	m.lastListLandID = append([]byte(nil), landID...)
+	m.lastLandName = landName
+	return m.listResult, m.listTotal, m.listErr
+}
+
+func TestNewFederalStateService(t *testing.T) {
+	repo := &federalStateRepoMock{}
+	svc := NewFederalStateService(repo)
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service and repo initialized")
+	}
+}
+
+func TestFederalStateServiceCreate(t *testing.T) {
+	repo := &federalStateRepoMock{}
+	svc := NewFederalStateService(repo)
+	row := &federal_state.FederalState{Name: "Name"}
+
+	if err := svc.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.createCalled || repo.lastCreate != row {
+		t.Fatalf("expected Create forwarded to repo")
+	}
+
+	repo.createErr = errors.New("create failed")
+	if err := svc.Create(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestFederalStateServiceUpdate(t *testing.T) {
+	repo := &federalStateRepoMock{}
+	svc := NewFederalStateService(repo)
+	row := &federal_state.FederalState{Name: "Updated"}
+
+	if err := svc.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateCalled || repo.lastUpdate != row {
+		t.Fatalf("expected Update forwarded to repo")
+	}
+
+	repo.updateErr = errors.New("update failed")
+	if err := svc.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestFederalStateServiceDelete(t *testing.T) {
+	repo := &federalStateRepoMock{}
+	svc := NewFederalStateService(repo)
+	id := []byte("id")
+	deletedBy := []byte("by")
+
+	if err := svc.Delete(context.Background(), id, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.deleteCalled {
+		t.Fatalf("expected Delete forwarded to repo")
+	}
+	if string(repo.lastDeleteID) != string(id) || string(repo.lastDeleteBy) != string(deletedBy) {
+		t.Fatalf("expected delete params forwarded")
+	}
+
+	repo.deleteErr = errors.New("delete failed")
+	if err := svc.Delete(context.Background(), id, deletedBy); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestFederalStateServiceGetByID(t *testing.T) {
+	expected := &federal_state.FederalState{Name: "A"}
+	repo := &federalStateRepoMock{getByIDResult: expected}
+	svc := NewFederalStateService(repo)
+	id := []byte("id")
+
+	got, err := svc.GetByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != expected {
+		t.Fatalf("unexpected result")
+	}
+	if !repo.getByIDCalled || string(repo.lastGetByID) != string(id) {
+		t.Fatalf("expected GetByID forwarded")
+	}
+
+	repo.getByIDErr = errors.New("get failed")
+	if _, err := svc.GetByID(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestFederalStateServiceList(t *testing.T) {
+	repo := &federalStateRepoMock{
+		listResult: []federal_state.FederalState{{Name: "A"}},
+		listTotal:  1,
+	}
+	svc := NewFederalStateService(repo)
+
+	landID := []byte("land")
+	rows, total, err := svc.List(context.Background(), "find", "sortkey", 10, 20, landID, "Germany")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if !repo.listCalled {
+		t.Fatalf("expected List forwarded to repo")
+	}
+	if repo.lastListFilter != "find" || repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC" || repo.lastListLimit != 10 || repo.lastListOffset != 20 || string(repo.lastListLandID) != string(landID) || repo.lastLandName != "Germany" {
+		t.Fatalf("unexpected list args forwarded")
+	}
+
+	repo.listErr = errors.New("list failed")
+	if _, _, err := svc.List(context.Background(), "", "unknown", 1, 0, nil, ""); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestNormalizeFederalStateSort(t *testing.T) {
+	cases := map[string]string{
+		"name":        "name ASC",
+		"-name":       "name DESC",
+		"sortkey":     "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC",
+		"-sortkey":    "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC",
+		"sort_key":    "sortkey ASC",
+		"-sort_key":   "sortkey DESC",
+		"is_active":   "is_active ASC",
+		"-is_active":  "is_active DESC",
+		"created_at":  "created_at ASC",
+		"-created_at": "created_at DESC",
+		"updated_at":  "updated_at ASC",
+		"-updated_at": "updated_at DESC",
+		"unknown":     "",
+		"":            "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeFederalStateSort(in); got != want {
+			t.Fatalf("normalizeFederalStateSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/file_manager_service.go b/internal/service/file_manager_service.go
new file mode 100644
index 0000000..740b6d1
--- /dev/null
+++ b/internal/service/file_manager_service.go
@@ -0,0 +1,2974 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/queue"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type FileManagerService struct {
+	folderRepo           filemanager.FolderRepository
+	fileRepo             filemanager.FileRepository
+	attachmentRepo       filemanager.AttachmentRepository
+	uploadIntentRepo     filemanager.FileUploadIntentRepository
+	storage              filemanager.ObjectStorage
+	uploadPolicy         filemanager.FileUploadPolicy
+	fileQueue            filemanager.FileProcessingQueue
+	fileOutbox           filemanager.FileProcessingOutboxWriter
+	fileOutboxSerializer queue.FileProcessingMessageSerializer
+	fileStatusEvents     filemanager.FileStatusRealtimeEventWriter
+	trashRetention       time.Duration
+	logger               *slog.Logger
+	enableS3Tagging      bool
+}
+
+type FileManagerServiceDependencies struct {
+	UploadIntentRepo     filemanager.FileUploadIntentRepository
+	Storage              filemanager.ObjectStorage
+	UploadPolicy         filemanager.FileUploadPolicy
+	FileQueue            filemanager.FileProcessingQueue
+	FileOutbox           filemanager.FileProcessingOutboxWriter
+	FileOutboxSerializer queue.FileProcessingMessageSerializer
+	FileStatusEvents     filemanager.FileStatusRealtimeEventWriter
+	TrashRetention       time.Duration
+	Logger               *slog.Logger
+	EnableS3Tagging      bool
+}
+
+func NewFileManagerService(
+	folderRepo filemanager.FolderRepository,
+	fileRepo filemanager.FileRepository,
+	attachmentRepo filemanager.AttachmentRepository,
+	deps FileManagerServiceDependencies,
+) *FileManagerService {
+	svc := &FileManagerService{
+		folderRepo:           folderRepo,
+		fileRepo:             fileRepo,
+		attachmentRepo:       attachmentRepo,
+		uploadIntentRepo:     deps.UploadIntentRepo,
+		storage:              deps.Storage,
+		fileQueue:            deps.FileQueue,
+		fileOutbox:           deps.FileOutbox,
+		fileOutboxSerializer: deps.FileOutboxSerializer,
+		fileStatusEvents:     deps.FileStatusEvents,
+		trashRetention:       30 * 24 * time.Hour,
+		logger:               deps.Logger,
+		enableS3Tagging:      deps.EnableS3Tagging,
+	}
+	if svc.logger == nil {
+		svc.logger = slog.Default()
+	}
+	if deps.TrashRetention >= 0 {
+		svc.trashRetention = deps.TrashRetention
+	}
+	if svc.uploadIntentRepo == nil {
+		uploadIntentRepo, ok := fileRepo.(filemanager.FileUploadIntentRepository)
+		if ok {
+			svc.uploadIntentRepo = uploadIntentRepo
+		}
+	}
+	svc.SetUploadPolicy(deps.UploadPolicy)
+	return svc
+}
+
+func (s *FileManagerService) SetTrashRetention(retention time.Duration) {
+	if retention < 0 {
+		retention = 0
+	}
+	s.trashRetention = retention
+}
+
+func (s *FileManagerService) defaultTrashPurgeAt(now time.Time) *time.Time {
+	if s.trashRetention <= 0 {
+		return nil
+	}
+	v := now.UTC().Add(s.trashRetention)
+	return &v
+}
+
+func (s *FileManagerService) SetObjectStorage(storage filemanager.ObjectStorage) {
+	s.storage = storage
+}
+
+func (s *FileManagerService) SetUploadPolicy(policy filemanager.FileUploadPolicy) {
+	s.uploadPolicy = normalizeUploadPolicy(policy)
+}
+
+func (s *FileManagerService) SetFileProcessingQueue(fileQueue filemanager.FileProcessingQueue) {
+	s.fileQueue = fileQueue
+}
+
+func (s *FileManagerService) SetFileUploadIntentRepository(repo filemanager.FileUploadIntentRepository) {
+	s.uploadIntentRepo = repo
+}
+
+func (s *FileManagerService) SetFileProcessingOutbox(
+	outbox filemanager.FileProcessingOutboxWriter,
+	serializer queue.FileProcessingMessageSerializer,
+) {
+	s.fileOutbox = outbox
+	s.fileOutboxSerializer = serializer
+}
+
+func (s *FileManagerService) SetFileStatusRealtimeEventWriter(writer filemanager.FileStatusRealtimeEventWriter) {
+	s.fileStatusEvents = writer
+}
+
+func (s *FileManagerService) GetOrCreateSystemRootFolder(ctx context.Context) (*filemanager.Folder, error) {
+	if s.folderRepo == nil {
+		return nil, filemanager.ErrFolderNotFound
+	}
+
+	root, err := s.folderRepo.GetByParentAndName(ctx, nil, filemanager.SystemRootFolderName)
+	if err != nil {
+		return nil, err
+	}
+	if root != nil {
+		return root, nil
+	}
+
+	row := &filemanager.Folder{
+		ParentID:       nil,
+		Name:           filemanager.SystemRootFolderName,
+		NameNormalized: filemanager.SystemRootFolderName,
+		Depth:          0,
+		PathCache:      "/" + filemanager.SystemRootFolderName,
+		NameSlot:       "live",
+	}
+	if err := s.folderRepo.Create(ctx, row); err != nil {
+		// If another request created it first, re-read.
+		root, getErr := s.folderRepo.GetByParentAndName(ctx, nil, filemanager.SystemRootFolderName)
+		if getErr == nil && root != nil {
+			return root, nil
+		}
+		return nil, err
+	}
+	return row, nil
+}
+
+func (s *FileManagerService) CreateFolderNode(ctx context.Context, params filemanager.CreateFolderParams) (*filemanager.Folder, error) {
+	name, nameNormalized, err := normalizeFolderName(params.Name)
+	if err != nil {
+		return nil, err
+	}
+
+	var parentID []byte
+	depth := 0
+	pathCache := buildFolderPathCache("", name)
+	if len(params.ParentID) != 0 {
+		parent, err := s.folderRepo.GetByID(ctx, params.ParentID)
+		if err != nil {
+			return nil, err
+		}
+		if parent == nil {
+			return nil, filemanager.ErrFolderNotFound
+		}
+		parentID = append([]byte(nil), params.ParentID...)
+		depth = parent.Depth + 1
+		pathCache = buildFolderPathCache(parent.PathCache, name)
+	}
+
+	dup, err := s.folderRepo.GetByParentAndName(ctx, parentID, nameNormalized)
+	if err != nil {
+		return nil, err
+	}
+	if dup != nil {
+		return nil, filemanager.ErrDuplicateName
+	}
+
+	row := &filemanager.Folder{
+		ParentID:       parentID,
+		Name:           name,
+		NameNormalized: nameNormalized,
+		Depth:          depth,
+		PathCache:      pathCache,
+		NameSlot:       "live",
+		CreatedBy:      params.ActorID,
+		UpdatedBy:      params.ActorID,
+	}
+	if err := s.folderRepo.Create(ctx, row); err != nil {
+		if errors.Is(err, gorm.ErrDuplicatedKey) {
+			return nil, filemanager.ErrDuplicateName
+		}
+		return nil, err
+	}
+
+	created, err := s.folderRepo.GetByID(ctx, row.ID)
+	if err == nil && created != nil {
+		return created, nil
+	}
+	return row, nil
+}
+
+func (s *FileManagerService) MoveFolderNode(ctx context.Context, id []byte, params filemanager.MoveFolderParams) (*filemanager.Folder, error) {
+	current, err := s.folderRepo.GetByIDAny(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	if current == nil {
+		return nil, filemanager.ErrFolderNotFound
+	}
+	if current.DeletedAt != nil {
+		return nil, fmt.Errorf("%w: folder in trash cannot be moved", filemanager.ErrInvalidMove)
+	}
+
+	targetName := current.Name
+	targetNameNormalized := current.NameNormalized
+	if params.Name != nil {
+		name, nameNormalized, err := normalizeFolderName(*params.Name)
+		if err != nil {
+			return nil, err
+		}
+		targetName = name
+		targetNameNormalized = nameNormalized
+	}
+
+	targetParentID := current.ParentID
+	if params.ParentProvided {
+		targetParentID = append([]byte(nil), params.ParentID...)
+		if len(targetParentID) != 0 {
+			parent, err := s.folderRepo.GetByIDAny(ctx, targetParentID)
+			if err != nil {
+				return nil, err
+			}
+			if parent == nil {
+				return nil, filemanager.ErrFolderNotFound
+			}
+			if parent.DeletedAt != nil {
+				return nil, fmt.Errorf("%w: destination folder in trash cannot be used", filemanager.ErrInvalidMove)
+			}
+		}
+	}
+
+	moved, err := s.folderRepo.MoveSubtree(ctx, id, targetParentID, targetName, targetNameNormalized, params.ActorID)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, filemanager.ErrFolderNotFound
+		}
+		if errors.Is(err, gorm.ErrDuplicatedKey) {
+			return nil, filemanager.ErrDuplicateName
+		}
+		if errors.Is(err, filemanager.ErrInvalidMove) {
+			return nil, filemanager.ErrInvalidMove
+		}
+		return nil, err
+	}
+	if moved == nil {
+		return nil, filemanager.ErrFolderNotFound
+	}
+	return moved, nil
+}
+
+func (s *FileManagerService) RequestFileUploadIntent(ctx context.Context, params filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+	if s.storage == nil {
+		return nil, filemanager.ErrStorageUnavailable
+	}
+	if s.uploadIntentRepo == nil {
+		return nil, filemanager.ErrUploadIntentRepositoryDisabled
+	}
+
+	name, nameNormalized, err := normalizeFileName(params.Name)
+	if err != nil {
+		return nil, err
+	}
+
+	contentType := normalizeUploadedMimeType(params.ContentType)
+	if err := s.validateUploadAgainstPolicy(name, contentType, params.SizeBytes); err != nil {
+		return nil, err
+	}
+
+	intentID := uuidv7.MustBytes()
+	objectKey := buildImmutableFileObjectKey(name)
+	grant, err := s.storage.PresignPutObject(ctx, filemanager.PresignPutObjectInput{
+		ObjectKey:   objectKey,
+		ContentType: contentType,
+		SizeBytes:   params.SizeBytes,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	expiresAt := grant.ExpiresAt.UTC()
+	if expiresAt.IsZero() {
+		expiresAt = time.Now().UTC().Add(15 * time.Minute)
+	}
+	bucket := strings.TrimSpace(grant.Bucket)
+	key := strings.TrimSpace(grant.ObjectKey)
+	if key == "" {
+		key = objectKey
+	}
+	method := strings.ToUpper(strings.TrimSpace(grant.Method))
+	if method == "" {
+		method = "PUT"
+	}
+
+	intent := &filemanager.FileUploadIntent{
+		ID:             intentID,
+		Name:           name,
+		NameNormalized: nameNormalized,
+		Extension:      extensionFromName(name),
+		SizeBytes:      params.SizeBytes,
+		MimeType:       contentType,
+		Bucket:         bucket,
+		ObjectKey:      key,
+		Status:         filemanager.FileUploadIntentStatusPending,
+		ExpiresAt:      expiresAt,
+		CreatedBy:      params.ActorID,
+		UpdatedBy:      params.ActorID,
+	}
+	if err := s.uploadIntentRepo.CreateUploadIntent(ctx, intent); err != nil {
+		return nil, err
+	}
+
+	return &filemanager.FileUploadIntentGrant{
+		UploadIntentID: append([]byte(nil), intent.ID...),
+		Bucket:         intent.Bucket,
+		ObjectKey:      intent.ObjectKey,
+		Name:           intent.Name,
+		MimeType:       intent.MimeType,
+		SizeBytes:      intent.SizeBytes,
+		Method:         method,
+		UploadURL:      strings.TrimSpace(grant.URL),
+		Headers:        cloneTrimmedStringMap(grant.Headers),
+		ExpiresAt:      intent.ExpiresAt.UTC(),
+	}, nil
+}
+
+func (s *FileManagerService) UpdateUploadIntentSize(ctx context.Context, params filemanager.FileUploadIntentSizeUpdateParams) error {
+	if s.uploadIntentRepo == nil {
+		return filemanager.ErrUploadIntentRepositoryDisabled
+	}
+	updater, ok := s.uploadIntentRepo.(interface {
+		UpdateUploadIntentSize(context.Context, filemanager.FileUploadIntentSizeUpdateParams) error
+	})
+	if !ok {
+		return filemanager.ErrUploadIntentRepositoryDisabled
+	}
+	return updater.UpdateUploadIntentSize(ctx, params)
+}
+
+func (s *FileManagerService) CompleteFileUploadIntent(ctx context.Context, params filemanager.CompleteFileUploadIntentParams) (*filemanager.File, error) {
+	if s.storage == nil {
+		return nil, filemanager.ErrStorageUnavailable
+	}
+	if s.uploadIntentRepo == nil {
+		return nil, filemanager.ErrUploadIntentRepositoryDisabled
+	}
+
+	intent, err := s.uploadIntentRepo.GetUploadIntentByID(ctx, params.UploadIntentID)
+	if err != nil {
+		return nil, err
+	}
+	if intent == nil {
+		return nil, filemanager.ErrUploadIntentNotFound
+	}
+
+	status := filemanager.NormalizeFileUploadIntentStatus(intent.Status)
+	if status == filemanager.FileUploadIntentStatusCompleted {
+		row, err := s.fileRepo.GetByObjectKey(ctx, intent.ObjectKey)
+		if err != nil {
+			return nil, err
+		}
+		if row != nil {
+			if touchErr := s.touchFolders(ctx, params.ActorID, row.FolderID); touchErr != nil {
+				return nil, touchErr
+			}
+			return row, nil
+		}
+		return nil, filemanager.ErrUploadIntentAlreadyComplete
+	}
+	if status == filemanager.FileUploadIntentStatusExpired {
+		return nil, filemanager.ErrUploadIntentExpired
+	}
+	if status != filemanager.FileUploadIntentStatusPending {
+		return nil, filemanager.ErrUploadIntentStatusConflict
+	}
+
+	now := time.Now().UTC()
+	if !intent.ExpiresAt.IsZero() && now.After(intent.ExpiresAt.UTC()) {
+		_ = s.uploadIntentRepo.MarkUploadIntentExpired(ctx, filemanager.FileUploadIntentExpireParams{
+			ID:        intent.ID,
+			UpdatedBy: params.ActorID,
+			ExpiredAt: now,
+		})
+		return nil, filemanager.ErrUploadIntentExpired
+	}
+
+	headMeta, err := s.verifyUploadedObjectForIntent(ctx, intent)
+	if err != nil {
+		return nil, err
+	}
+
+	if txRepo, ok := s.fileRepo.(filemanager.FileTransactionalRepository); ok && s.fileOutboxReady() {
+		row, err := s.completeFileUploadIntentDurable(ctx, txRepo, intent, headMeta, params.ActorID)
+		if err != nil {
+			return nil, err
+		}
+		if touchErr := s.touchFolders(ctx, params.ActorID, row.FolderID); touchErr != nil {
+			return nil, touchErr
+		}
+		s.ensureLifecycleTempMarker(ctx, row)
+		s.emitFileStatusRealtimeEvent(ctx, row, filemanager.FileStatusUploaded, params.ActorID, "")
+		return row, nil
+	}
+
+	row, err := s.createUploadedFileFromIntent(ctx, intent, headMeta, params.ActorID)
+	if err != nil {
+		return nil, err
+	}
+	if err := s.uploadIntentRepo.MarkUploadIntentCompleted(ctx, filemanager.FileUploadIntentCompleteParams{
+		ID:          intent.ID,
+		UpdatedBy:   params.ActorID,
+		CompletedAt: time.Now().UTC(),
+	}); err != nil {
+		return nil, err
+	}
+	if touchErr := s.touchFolders(ctx, params.ActorID, row.FolderID); touchErr != nil {
+		return nil, touchErr
+	}
+	s.ensureLifecycleTempMarker(ctx, row)
+
+	s.emitFileStatusRealtimeEvent(ctx, row, filemanager.FileStatusUploaded, params.ActorID, "")
+	if err := s.enqueueUploadedFileForProcessing(ctx, row, params.ActorID); err != nil {
+		failedAt := time.Now().UTC()
+		reason := truncateFailureReason(err.Error())
+		_ = s.fileRepo.TransitionStatus(ctx, filemanager.FileStatusTransitionParams{
+			ID:            row.ID,
+			ExpectedFrom:  filemanager.FileStatusUploaded,
+			To:            filemanager.FileStatusFailed,
+			UpdatedBy:     params.ActorID,
+			ProcessedAt:   &failedAt,
+			FailedAt:      &failedAt,
+			FailureReason: &reason,
+		})
+		row.Status = filemanager.FileStatusFailed
+		row.FailureReason = reason
+		row.UpdatedAt = failedAt
+		row.UpdatedBy = append([]byte(nil), params.ActorID...)
+		s.emitFileStatusRealtimeEvent(ctx, row, filemanager.FileStatusFailed, params.ActorID, reason)
+		return nil, err
+	}
+
+	return row, nil
+}
+
+func (s *FileManagerService) CancelFileUploadIntent(ctx context.Context, params filemanager.CancelFileUploadIntentParams) error {
+	if s.uploadIntentRepo == nil {
+		return filemanager.ErrUploadIntentRepositoryDisabled
+	}
+
+	intent, err := s.uploadIntentRepo.GetUploadIntentByID(ctx, params.UploadIntentID)
+	if err != nil {
+		return err
+	}
+	if intent == nil {
+		return filemanager.ErrUploadIntentNotFound
+	}
+
+	status := filemanager.NormalizeFileUploadIntentStatus(intent.Status)
+	switch status {
+	case filemanager.FileUploadIntentStatusExpired:
+		// Idempotent: already canceled/expired.
+		return nil
+	case filemanager.FileUploadIntentStatusCompleted:
+		return filemanager.ErrUploadIntentAlreadyComplete
+	case filemanager.FileUploadIntentStatusPending:
+		// Continue to cancellation flow.
+	default:
+		return filemanager.ErrUploadIntentStatusConflict
+	}
+
+	if s.storage == nil {
+		return filemanager.ErrStorageUnavailable
+	}
+
+	if strings.TrimSpace(intent.ObjectKey) != "" {
+		if err := s.storage.DeleteObject(ctx, intent.ObjectKey); err != nil {
+			return err
+		}
+	}
+
+	now := time.Now().UTC()
+	if err := s.uploadIntentRepo.MarkUploadIntentExpired(ctx, filemanager.FileUploadIntentExpireParams{
+		ID:        intent.ID,
+		UpdatedBy: params.ActorID,
+		ExpiredAt: now,
+	}); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return filemanager.ErrUploadIntentStatusConflict
+		}
+		return err
+	}
+
+	return nil
+}
+
+func (s *FileManagerService) UploadFileNode(ctx context.Context, params filemanager.UploadFileParams) (*filemanager.File, error) {
+	if s.storage == nil {
+		return nil, filemanager.ErrStorageUnavailable
+	}
+	if params.Body == nil {
+		return nil, filemanager.ErrInvalidName
+	}
+
+	name, nameNormalized, err := normalizeFileName(params.Name)
+	if err != nil {
+		return nil, err
+	}
+
+	contentType := normalizeUploadedMimeType(params.ContentType)
+	if err := s.validateUploadAgainstPolicy(name, contentType, params.SizeBytes); err != nil {
+		return nil, err
+	}
+
+	// Upload stage always parks metadata under hidden system root.
+	// The final logical folder/name is set by CreateFileNodeFromUpload.
+	root, err := s.GetOrCreateSystemRootFolder(ctx)
+	if err != nil {
+		return nil, err
+	}
+	targetFolderID := root.ID
+
+	objectKey := buildImmutableFileObjectKey(name)
+	validatedAt := time.Now().UTC()
+	metadata := map[string]string{
+		"uploaded": validatedAt.Format(time.RFC3339),
+	}
+	if folderIDStr, err := uuidv7.BytesToString(targetFolderID); err == nil {
+		metadata["folder_id"] = folderIDStr
+	}
+	meta, err := s.storage.PutObject(ctx, filemanager.PutObjectInput{
+		ObjectKey:   objectKey,
+		ContentType: contentType,
+		SizeBytes:   params.SizeBytes,
+		Body:        params.Body,
+		Metadata:    metadata,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	row := &filemanager.File{
+		ID:                  uuidv7.MustBytes(),
+		FolderID:            targetFolderID,
+		Name:                name,
+		NameNormalized:      nameNormalized,
+		Extension:           extensionFromName(name),
+		SizeBytes:           params.SizeBytes,
+		MimeType:            contentType,
+		Bucket:              meta.Bucket,
+		ObjectKey:           meta.ObjectKey,
+		ObjectVersion:       meta.VersionID,
+		ETag:                meta.ETag,
+		IsTemplate:          params.IsTemplate,
+		Status:              filemanager.FileStatusUploaded,
+		LifecycleStatus:     filemanager.FileLifecycleStatusTemp,
+		ProcessingStartedAt: nil,
+		ProcessedAt:         nil,
+		ValidatedAt:         nil,
+		NameSlot:            tempUploadNameSlot(),
+		CreatedBy:           params.ActorID,
+		UpdatedBy:           params.ActorID,
+	}
+
+	if txRepo, ok := s.fileRepo.(filemanager.FileTransactionalRepository); ok && s.fileOutboxReady() {
+		if err := txRepo.WithTransaction(ctx, func(repo filemanager.FileRepository, outbox filemanager.FileProcessingOutboxWriter) error {
+			if err := repo.Create(ctx, row); err != nil {
+				return err
+			}
+			return s.persistFileProcessingOutbox(ctx, outbox, row, params.ActorID)
+		}); err != nil {
+			_ = s.storage.DeleteObject(ctx, meta.ObjectKey)
+			return nil, err
+		}
+
+		createdRow := row
+		created, err := s.fileRepo.GetByID(ctx, row.ID)
+		if err == nil && created != nil {
+			createdRow = created
+		}
+		s.ensureLifecycleTempMarker(ctx, createdRow)
+		s.emitFileStatusRealtimeEvent(ctx, createdRow, filemanager.FileStatusUploaded, params.ActorID, "")
+		return createdRow, nil
+	}
+
+	if err := s.fileRepo.Create(ctx, row); err != nil {
+		_ = s.storage.DeleteObject(ctx, meta.ObjectKey)
+		return nil, err
+	}
+
+	createdRow := row
+	created, err := s.fileRepo.GetByID(ctx, row.ID)
+	if err == nil && created != nil {
+		createdRow = created
+	}
+	if touchErr := s.touchFolders(ctx, params.ActorID, createdRow.FolderID); touchErr != nil {
+		return nil, touchErr
+	}
+	s.ensureLifecycleTempMarker(ctx, createdRow)
+	s.emitFileStatusRealtimeEvent(ctx, createdRow, filemanager.FileStatusUploaded, params.ActorID, "")
+
+	if err := s.enqueueUploadedFileForProcessing(ctx, createdRow, params.ActorID); err != nil {
+		now := time.Now().UTC()
+		reason := truncateFailureReason(err.Error())
+		_ = s.fileRepo.TransitionStatus(ctx, filemanager.FileStatusTransitionParams{
+			ID:            createdRow.ID,
+			ExpectedFrom:  filemanager.FileStatusUploaded,
+			To:            filemanager.FileStatusFailed,
+			UpdatedBy:     params.ActorID,
+			ProcessedAt:   &now,
+			FailedAt:      &now,
+			FailureReason: &reason,
+		})
+		createdRow.Status = filemanager.FileStatusFailed
+		createdRow.FailureReason = reason
+		createdRow.UpdatedBy = append([]byte(nil), params.ActorID...)
+		createdRow.UpdatedAt = now
+		s.emitFileStatusRealtimeEvent(ctx, createdRow, filemanager.FileStatusFailed, params.ActorID, reason)
+		return nil, err
+	}
+
+	return createdRow, nil
+}
+
+func (s *FileManagerService) CreateFileNodeFromUploadIntent(ctx context.Context, params filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+	name, _, err := normalizeFileName(params.Name)
+	if err != nil {
+		return nil, err
+	}
+
+	targetFolderID, err := s.resolveTargetFolderID(ctx, params.FolderID, params.FolderProvided, true)
+	if err != nil {
+		return nil, err
+	}
+
+	uploaded, err := s.CompleteFileUploadIntent(ctx, filemanager.CompleteFileUploadIntentParams{
+		UploadIntentID: params.UploadIntentID,
+		ActorID:        params.ActorID,
+	})
+	if err != nil {
+		return nil, err
+	}
+	if uploaded == nil {
+		return nil, filemanager.ErrFileNotFound
+	}
+
+	currentStatus := filemanager.NormalizeFileStatus(uploaded.Status)
+	if strings.EqualFold(strings.TrimSpace(uploaded.NameSlot), "live") && currentStatus == filemanager.FileStatusReady {
+		return nil, filemanager.ErrFileAlreadyFinalized
+	}
+	if uploaded.IsTemplate != params.IsTemplate {
+		uploaded.IsTemplate = params.IsTemplate
+		if err := s.fileRepo.Update(ctx, uploaded); err != nil {
+			return nil, err
+		}
+	}
+	targetName, _, err := s.resolveAvailableFileName(ctx, targetFolderID, name, uploaded.ID)
+	if err != nil {
+		return nil, err
+	}
+
+	moved, err := s.MoveFileNode(ctx, uploaded.ID, filemanager.MoveFileParams{
+		Name:           &targetName,
+		FolderID:       targetFolderID,
+		FolderProvided: true,
+		ActorID:        params.ActorID,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	return moved, nil
+}
+
+func (s *FileManagerService) CreateFileNodeFromUpload(ctx context.Context, params filemanager.CreateFileFromUploadParams) (*filemanager.File, error) {
+	current, err := s.fileRepo.GetByID(ctx, params.UploadFileID)
+	if err != nil {
+		return nil, err
+	}
+	if current == nil {
+		return nil, filemanager.ErrFileNotFound
+	}
+	currentStatus := filemanager.NormalizeFileStatus(current.Status)
+	if strings.EqualFold(strings.TrimSpace(current.NameSlot), "live") &&
+		currentStatus == filemanager.FileStatusReady {
+		return nil, filemanager.ErrFileAlreadyFinalized
+	}
+	if err := ensureFileStatusTransition(currentStatus, filemanager.FileStatusReady); err != nil {
+		return nil, fmt.Errorf("%w: current status is %q", filemanager.ErrFileNotEligibleForFinalize, currentStatus)
+	}
+
+	targetFolderID := current.FolderID
+	if params.FolderProvided {
+		folderID, err := s.resolveTargetFolderID(ctx, params.FolderID, true, true)
+		if err != nil {
+			return nil, err
+		}
+		targetFolderID = folderID
+	}
+
+	targetName := current.Name
+	if params.Name != nil {
+		name, _, err := normalizeFileName(*params.Name)
+		if err != nil {
+			return nil, err
+		}
+		targetName = name
+	}
+
+	targetName, targetNameNormalized, err := s.resolveAvailableFileName(ctx, targetFolderID, targetName, current.ID)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := s.fileRepo.Finalize(ctx, filemanager.FileFinalizeParams{
+		ID:             current.ID,
+		ExpectedFrom:   currentStatus,
+		FolderID:       targetFolderID,
+		Name:           targetName,
+		NameNormalized: targetNameNormalized,
+		Extension:      extensionFromName(targetName),
+		UpdatedBy:      params.ActorID,
+	}); err != nil {
+		if errors.Is(err, gorm.ErrDuplicatedKey) {
+			return nil, filemanager.ErrDuplicateName
+		}
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, filemanager.ErrFileStatusConflict
+		}
+		return nil, err
+	}
+
+	updated, err := s.fileRepo.GetByID(ctx, params.UploadFileID)
+	if err == nil && updated != nil {
+		if touchErr := s.touchFolders(ctx, params.ActorID, updated.FolderID); touchErr != nil {
+			return nil, touchErr
+		}
+		s.emitFileStatusRealtimeEvent(ctx, updated, filemanager.FileStatusReady, params.ActorID, "")
+		return updated, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return nil, filemanager.ErrFileNotFound
+}
+
+func (s *FileManagerService) UploadFileNodesBulk(ctx context.Context, params []filemanager.UploadFileParams) []filemanager.BulkFileNodeResult {
+	results := make([]filemanager.BulkFileNodeResult, 0, len(params))
+	for i := range params {
+		row, err := s.UploadFileNode(ctx, params[i])
+		results = append(results, filemanager.BulkFileNodeResult{
+			Index: i,
+			File:  row,
+			Err:   err,
+		})
+	}
+	return results
+}
+
+func (s *FileManagerService) CreateFileNodesFromUploadBulk(ctx context.Context, params []filemanager.CreateFileFromUploadParams) []filemanager.BulkFileNodeResult {
+	results := make([]filemanager.BulkFileNodeResult, 0, len(params))
+	for i := range params {
+		row, err := s.CreateFileNodeFromUpload(ctx, params[i])
+		results = append(results, filemanager.BulkFileNodeResult{
+			Index: i,
+			File:  row,
+			Err:   err,
+		})
+	}
+	return results
+}
+
+func (s *FileManagerService) MoveFileNode(ctx context.Context, id []byte, params filemanager.MoveFileParams) (*filemanager.File, error) {
+	current, err := s.fileRepo.GetByIDAny(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	if current == nil {
+		return nil, filemanager.ErrFileNotFound
+	}
+	if current.DeletedAt != nil {
+		return nil, fmt.Errorf("%w: file in trash cannot be moved", filemanager.ErrInvalidMove)
+	}
+
+	targetFolderID := current.FolderID
+	sourceFolderID := append([]byte(nil), current.FolderID...)
+	if params.FolderProvided {
+		targetFolderID = append([]byte(nil), params.FolderID...)
+		if len(targetFolderID) != 0 {
+			destination, err := s.folderRepo.GetByIDAny(ctx, targetFolderID)
+			if err != nil {
+				return nil, err
+			}
+			if destination == nil {
+				return nil, filemanager.ErrFolderNotFound
+			}
+			if destination.DeletedAt != nil {
+				return nil, fmt.Errorf("%w: destination folder in trash cannot be used", filemanager.ErrInvalidMove)
+			}
+		}
+	}
+
+	targetName := current.Name
+	targetNameNormalized := current.NameNormalized
+	if params.Name != nil {
+		name, nameNormalized, err := normalizeFileName(*params.Name)
+		if err != nil {
+			return nil, err
+		}
+		targetName = name
+		targetNameNormalized = nameNormalized
+	}
+
+	dup, err := s.fileRepo.GetByFolderAndName(ctx, targetFolderID, targetNameNormalized)
+	if err != nil {
+		return nil, err
+	}
+	if dup != nil && !bytesEqual16(dup.ID, current.ID) {
+		return nil, filemanager.ErrDuplicateName
+	}
+
+	current.FolderID = targetFolderID
+	current.Name = targetName
+	current.NameNormalized = targetNameNormalized
+	current.Extension = extensionFromName(targetName)
+	current.NameSlot = "live"
+	current.UpdatedBy = params.ActorID
+
+	if err := s.fileRepo.Update(ctx, current); err != nil {
+		if errors.Is(err, gorm.ErrDuplicatedKey) {
+			return nil, filemanager.ErrDuplicateName
+		}
+		return nil, err
+	}
+	if err := s.touchFolders(ctx, params.ActorID, sourceFolderID, targetFolderID); err != nil {
+		return nil, err
+	}
+
+	updated, err := s.fileRepo.GetByID(ctx, current.ID)
+	if err == nil && updated != nil {
+		return updated, nil
+	}
+	return current, nil
+}
+
+func (s *FileManagerService) PurgeFolderNode(ctx context.Context, id []byte) error {
+	row, err := s.folderRepo.GetByIDAny(ctx, id)
+	if err != nil {
+		return err
+	}
+	if row == nil || isSystemRootFolder(row) {
+		return filemanager.ErrFolderNotFound
+	}
+	if row.DeletedAt == nil {
+		return filemanager.ErrFolderNotInTrash
+	}
+
+	subtreeFolders, err := s.collectFolderSubtreeAny(ctx, id)
+	if err != nil {
+		return err
+	}
+	if len(subtreeFolders) == 0 {
+		return filemanager.ErrFolderNotFound
+	}
+
+	folderIDs := make([][]byte, 0, len(subtreeFolders))
+	for i := range subtreeFolders {
+		folderIDs = append(folderIDs, subtreeFolders[i].ID)
+	}
+
+	allFiles, err := s.listAllFilesByFolders(ctx, folderIDs)
+	if err != nil {
+		return err
+	}
+
+	objectKeys := make([]string, 0, len(allFiles))
+	for i := range allFiles {
+		fileRow := allFiles[i]
+		if fileRow.DeletedAt == nil {
+			if err := s.fileRepo.Delete(ctx, fileRow.ID, nil, nil); err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+				return err
+			}
+		}
+		if err := s.fileRepo.Purge(ctx, fileRow.ID); err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+			return err
+		}
+		if key := strings.TrimSpace(fileRow.ObjectKey); key != "" {
+			objectKeys = append(objectKeys, key)
+		}
+		if fileRow.ThumbnailObjectKey != nil {
+			if key := strings.TrimSpace(*fileRow.ThumbnailObjectKey); key != "" {
+				objectKeys = append(objectKeys, key)
+			}
+		}
+	}
+
+	sort.SliceStable(subtreeFolders, func(i, j int) bool {
+		return subtreeFolders[i].Depth > subtreeFolders[j].Depth
+	})
+	for i := range subtreeFolders {
+		folderID := subtreeFolders[i].ID
+		if subtreeFolders[i].DeletedAt == nil {
+			if err := s.folderRepo.Delete(ctx, folderID, nil, nil); err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+				return err
+			}
+		}
+		if err := s.folderRepo.Purge(ctx, folderID); err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+			return err
+		}
+	}
+
+	if s.storage != nil && len(objectKeys) > 0 {
+		uniqueKeys := uniqueNonEmptyStrings(objectKeys)
+		go func(storage filemanager.ObjectStorage, keys []string) {
+			bgCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+			defer cancel()
+			for i := range keys {
+				_ = storage.DeleteObject(bgCtx, keys[i])
+			}
+		}(s.storage, uniqueKeys)
+	}
+
+	return nil
+}
+
+func (s *FileManagerService) PurgeFileNode(ctx context.Context, id []byte) error {
+	row, err := s.fileRepo.GetByIDAny(ctx, id)
+	if err != nil {
+		return err
+	}
+	if row == nil {
+		return filemanager.ErrFileNotFound
+	}
+	if row.DeletedAt == nil {
+		return filemanager.ErrFileNotInTrash
+	}
+
+	objectKeys := make([]string, 0, 2)
+	if key := strings.TrimSpace(row.ObjectKey); key != "" {
+		objectKeys = append(objectKeys, key)
+	}
+	if row.ThumbnailObjectKey != nil {
+		if key := strings.TrimSpace(*row.ThumbnailObjectKey); key != "" {
+			objectKeys = append(objectKeys, key)
+		}
+	}
+	if err := s.fileRepo.Purge(ctx, id); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return filemanager.ErrFileNotFound
+		}
+		return err
+	}
+
+	if s.storage != nil && len(objectKeys) > 0 {
+		uniqueKeys := uniqueNonEmptyStrings(objectKeys)
+		go func(storage filemanager.ObjectStorage, keys []string) {
+			bgCtx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+			defer cancel()
+			for i := range keys {
+				_ = storage.DeleteObject(bgCtx, keys[i])
+			}
+		}(s.storage, uniqueKeys)
+	}
+	return nil
+}
+
+func (s *FileManagerService) ListNodesByParent(ctx context.Context, parentID []byte) ([]filemanager.Folder, []filemanager.File, error) {
+	if len(parentID) != 0 {
+		parent, err := s.folderRepo.GetByID(ctx, parentID)
+		if err != nil {
+			return nil, nil, err
+		}
+		if parent == nil {
+			return nil, nil, filemanager.ErrFolderNotFound
+		}
+		folders, _, err := s.folderRepo.ListByParent(ctx, parentID, "name ASC", 0, 0)
+		if err != nil {
+			return nil, nil, err
+		}
+		files, _, err := s.fileRepo.ListByFolder(ctx, parentID, "name ASC", 0, 0)
+		if err != nil {
+			return nil, nil, err
+		}
+		return folders, files, nil
+	}
+
+	root, err := s.GetOrCreateSystemRootFolder(ctx)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	rootFolders, _, err := s.folderRepo.ListByParent(ctx, nil, "name ASC", 0, 0)
+	if err != nil {
+		return nil, nil, err
+	}
+	systemRootChildren, _, err := s.folderRepo.ListByParent(ctx, root.ID, "name ASC", 0, 0)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	out := make([]filemanager.Folder, 0, len(rootFolders)+len(systemRootChildren))
+	seen := make(map[string]struct{}, len(rootFolders)+len(systemRootChildren))
+	appendVisibleFolder := func(row filemanager.Folder) {
+		if isSystemRootFolder(&row) {
+			return
+		}
+		idKey := string(row.ID)
+		if _, ok := seen[idKey]; ok {
+			return
+		}
+		seen[idKey] = struct{}{}
+		out = append(out, row)
+	}
+	for i := range rootFolders {
+		appendVisibleFolder(rootFolders[i])
+	}
+	for i := range systemRootChildren {
+		appendVisibleFolder(systemRootChildren[i])
+	}
+	sort.SliceStable(out, func(i, j int) bool {
+		return strings.ToLower(strings.TrimSpace(out[i].Name)) < strings.ToLower(strings.TrimSpace(out[j].Name))
+	})
+
+	files, _, err := s.fileRepo.ListByFolder(ctx, root.ID, "name ASC", 0, 0)
+	if err != nil {
+		return nil, nil, err
+	}
+	return out, files, nil
+}
+
+func (s *FileManagerService) SearchNodes(ctx context.Context, query string) ([]filemanager.Folder, []filemanager.File, error) {
+	folders, _, err := s.folderRepo.SearchByName(ctx, query, "name ASC", 0, 0)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	files, _, err := s.fileRepo.SearchByName(ctx, query, "name ASC", 0, 0)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	return folders, files, nil
+}
+
+func (s *FileManagerService) ListTrashNodes(ctx context.Context) ([]filemanager.Folder, []filemanager.File, error) {
+	folders, _, err := s.folderRepo.ListTrash(ctx, "deleted_at DESC", 0, 0)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	files, _, err := s.fileRepo.ListTrashByFolder(ctx, nil, "deleted_at DESC", 0, 0)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	return folders, files, nil
+}
+
+func (s *FileManagerService) resolveTargetFolderID(ctx context.Context, folderID []byte, folderProvided bool, allowRoot bool) ([]byte, error) {
+	if folderProvided && len(folderID) != 0 {
+		folder, err := s.folderRepo.GetByID(ctx, folderID)
+		if err != nil {
+			return nil, err
+		}
+		if folder == nil {
+			return nil, filemanager.ErrFolderNotFound
+		}
+		return folder.ID, nil
+	}
+
+	if allowRoot {
+		root, err := s.GetOrCreateSystemRootFolder(ctx)
+		if err != nil {
+			return nil, err
+		}
+		return root.ID, nil
+	}
+
+	return nil, filemanager.ErrFolderNotFound
+}
+
+func (s *FileManagerService) CreateFolder(ctx context.Context, row *filemanager.Folder) error {
+	return s.folderRepo.Create(ctx, row)
+}
+
+func (s *FileManagerService) UpdateFolder(ctx context.Context, row *filemanager.Folder) error {
+	return s.folderRepo.Update(ctx, row)
+}
+
+func (s *FileManagerService) DeleteFolder(ctx context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error {
+	resolvedPurgeAt := purgeAt
+	if resolvedPurgeAt == nil {
+		resolvedPurgeAt = s.defaultTrashPurgeAt(time.Now().UTC())
+	}
+
+	row, err := s.folderRepo.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+	if row == nil || isSystemRootFolder(row) {
+		return filemanager.ErrFolderNotFound
+	}
+
+	subtreeFolders, err := s.collectFolderSubtreeAny(ctx, id)
+	if err != nil {
+		return err
+	}
+	if len(subtreeFolders) == 0 {
+		return filemanager.ErrFolderNotFound
+	}
+
+	folderIDs := make([][]byte, 0, len(subtreeFolders))
+	for i := range subtreeFolders {
+		folderIDs = append(folderIDs, subtreeFolders[i].ID)
+	}
+
+	activeFiles, err := s.listActiveFilesByFolders(ctx, folderIDs)
+	if err != nil {
+		return err
+	}
+	for i := range activeFiles {
+		fileID := append([]byte(nil), activeFiles[i].ID...)
+		if err := s.fileRepo.Delete(ctx, fileID, deletedBy, resolvedPurgeAt); err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				continue
+			}
+			return err
+		}
+	}
+
+	sort.SliceStable(subtreeFolders, func(i, j int) bool {
+		return subtreeFolders[i].Depth > subtreeFolders[j].Depth
+	})
+	for i := range subtreeFolders {
+		if subtreeFolders[i].DeletedAt != nil {
+			continue
+		}
+		folderID := append([]byte(nil), subtreeFolders[i].ID...)
+		if err := s.folderRepo.Delete(ctx, folderID, deletedBy, resolvedPurgeAt); err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				continue
+			}
+			return err
+		}
+	}
+	return nil
+}
+
+func (s *FileManagerService) RestoreFolder(ctx context.Context, id []byte, targetParentID []byte, targetProvided bool, restoredBy []byte) error {
+	row, err := s.folderRepo.GetByIDAny(ctx, id)
+	if err != nil {
+		return err
+	}
+	if row == nil {
+		return filemanager.ErrFolderNotFound
+	}
+	if row.DeletedAt == nil {
+		return filemanager.ErrFolderNotInTrash
+	}
+	if isSystemRootFolder(row) {
+		return filemanager.ErrFolderNotFound
+	}
+
+	_ = targetParentID
+	_ = targetProvided
+
+	var (
+		resolvedParentID  []byte
+		newRootDepth      int
+		newRootParentPath string
+	)
+	if len(row.ParentID) != 0 {
+		parent, err := s.folderRepo.GetByID(ctx, row.ParentID)
+		if err != nil {
+			return err
+		}
+		if parent == nil {
+			return filemanager.ErrFolderNotFound
+		}
+		if bytesEqual16(parent.ID, row.ID) {
+			return filemanager.ErrInvalidMove
+		}
+		if !isSystemRootFolder(parent) {
+			resolvedParentID = append([]byte(nil), parent.ID...)
+			newRootDepth = parent.Depth + 1
+			newRootParentPath = parent.PathCache
+		}
+	}
+
+	dup, err := s.folderRepo.GetByParentAndName(ctx, resolvedParentID, row.NameNormalized)
+	if err != nil {
+		return err
+	}
+	if dup != nil && !bytesEqual16(dup.ID, row.ID) {
+		return filemanager.ErrDuplicateName
+	}
+
+	subtreeFolders, err := s.collectFolderSubtreeAny(ctx, id)
+	if err != nil {
+		return err
+	}
+	if len(subtreeFolders) == 0 {
+		return filemanager.ErrFolderNotFound
+	}
+	oldRootPath := strings.TrimSpace(row.PathCache)
+	if oldRootPath == "" {
+		oldRootPath = buildFolderPathCache("", row.Name)
+	}
+	newRootPath := buildFolderPathCache(newRootParentPath, row.Name)
+	depthDelta := newRootDepth - row.Depth
+
+	sort.SliceStable(subtreeFolders, func(i, j int) bool {
+		return subtreeFolders[i].Depth < subtreeFolders[j].Depth
+	})
+
+	for i := range subtreeFolders {
+		current := subtreeFolders[i]
+		updated := current
+		if bytesEqual16(current.ID, row.ID) {
+			updated.ParentID = append([]byte(nil), resolvedParentID...)
+			updated.Depth = newRootDepth
+			updated.PathCache = newRootPath
+		} else {
+			updated.Depth = current.Depth + depthDelta
+			if updated.Depth < 0 {
+				updated.Depth = 0
+			}
+			updated.PathCache = replaceFolderPathPrefix(current.PathCache, oldRootPath, newRootPath)
+		}
+
+		if current.DeletedAt != nil {
+			updated.DeletedAt = nil
+			updated.DeletedBy = nil
+			updated.PurgeAt = nil
+			updated.NameSlot = "live"
+		}
+		updated.UpdatedBy = restoredBy
+
+		if err := s.folderRepo.Update(ctx, &updated); err != nil {
+			if errors.Is(err, gorm.ErrDuplicatedKey) {
+				return filemanager.ErrDuplicateName
+			}
+			return err
+		}
+	}
+
+	folderIDs := make([][]byte, 0, len(subtreeFolders))
+	for i := range subtreeFolders {
+		folderIDs = append(folderIDs, subtreeFolders[i].ID)
+	}
+	trashedFiles, err := s.listTrashedFilesByFolders(ctx, folderIDs)
+	if err != nil {
+		return err
+	}
+	for i := range trashedFiles {
+		rowFile := trashedFiles[i]
+		rowFile.Status = filemanager.FileStatusReady
+		rowFile.TrashedAt = nil
+		rowFile.DeletedAt = nil
+		rowFile.DeletedBy = nil
+		rowFile.PurgeAt = nil
+		rowFile.NameSlot = "live"
+		rowFile.UpdatedBy = restoredBy
+		if err := s.fileRepo.Update(ctx, &rowFile); err != nil {
+			if errors.Is(err, gorm.ErrDuplicatedKey) {
+				return filemanager.ErrDuplicateName
+			}
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (s *FileManagerService) PurgeFolder(ctx context.Context, id []byte) error {
+	return s.folderRepo.Purge(ctx, id)
+}
+
+func (s *FileManagerService) GetFolderByID(ctx context.Context, id []byte) (*filemanager.Folder, error) {
+	row, err := s.folderRepo.GetByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	if row != nil && isSystemRootFolder(row) {
+		return nil, nil
+	}
+	return row, nil
+}
+
+func (s *FileManagerService) GetFolderByIDAny(ctx context.Context, id []byte) (*filemanager.Folder, error) {
+	row, err := s.folderRepo.GetByIDAny(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	if row != nil && isSystemRootFolder(row) {
+		return nil, nil
+	}
+	return row, nil
+}
+
+func (s *FileManagerService) GetFolderByParentAndName(ctx context.Context, parentID []byte, nameNormalized string) (*filemanager.Folder, error) {
+	row, err := s.folderRepo.GetByParentAndName(ctx, parentID, nameNormalized)
+	if err != nil {
+		return nil, err
+	}
+	if row != nil && isSystemRootFolder(row) {
+		return nil, nil
+	}
+	return row, nil
+}
+
+func (s *FileManagerService) ListFoldersByParent(ctx context.Context, parentID []byte, sort string, limit, offset int) ([]filemanager.Folder, int64, error) {
+	rows, total, err := s.folderRepo.ListByParent(ctx, parentID, normalizeFolderSort(sort), limit, offset)
+	if err != nil {
+		return nil, 0, err
+	}
+	if len(parentID) != 0 {
+		return rows, total, nil
+	}
+
+	filtered := make([]filemanager.Folder, 0, len(rows))
+	for i := range rows {
+		if isSystemRootFolder(&rows[i]) {
+			continue
+		}
+		filtered = append(filtered, rows[i])
+	}
+	if total > int64(len(rows)-len(filtered)) {
+		total -= int64(len(rows) - len(filtered))
+	}
+	return filtered, total, nil
+}
+
+func (s *FileManagerService) ListTrashFoldersByParent(ctx context.Context, parentID []byte, sort string, limit, offset int) ([]filemanager.Folder, int64, error) {
+	return s.folderRepo.ListTrashByParent(ctx, parentID, normalizeFolderSort(sort), limit, offset)
+}
+
+func (s *FileManagerService) CreateFile(ctx context.Context, row *filemanager.File) error {
+	if err := s.fileRepo.Create(ctx, row); err != nil {
+		return err
+	}
+	actorID := row.UpdatedBy
+	if len(actorID) == 0 {
+		actorID = row.CreatedBy
+	}
+	return s.touchFolders(ctx, actorID, row.FolderID)
+}
+
+func (s *FileManagerService) UpdateFile(ctx context.Context, row *filemanager.File) error {
+	return s.fileRepo.Update(ctx, row)
+}
+
+func (s *FileManagerService) DeleteFile(ctx context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error {
+	resolvedPurgeAt := purgeAt
+	if resolvedPurgeAt == nil {
+		resolvedPurgeAt = s.defaultTrashPurgeAt(time.Now().UTC())
+	}
+
+	row, err := s.fileRepo.GetByIDAny(ctx, id)
+	if err != nil {
+		return err
+	}
+	if row == nil || row.DeletedAt != nil {
+		return filemanager.ErrFileNotFound
+	}
+
+	if err := s.fileRepo.Delete(ctx, id, deletedBy, resolvedPurgeAt); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return filemanager.ErrFileNotFound
+		}
+		return err
+	}
+	if err := s.touchFolders(ctx, deletedBy, row.FolderID); err != nil {
+		return err
+	}
+
+	deletedAt := time.Now().UTC()
+	row.Status = filemanager.FileStatusTrashed
+	row.TrashedAt = &deletedAt
+	row.DeletedAt = &deletedAt
+	row.DeletedBy = append([]byte(nil), deletedBy...)
+	row.UpdatedBy = append([]byte(nil), deletedBy...)
+	row.UpdatedAt = deletedAt
+	if resolvedPurgeAt != nil {
+		purgeAtCopy := resolvedPurgeAt.UTC()
+		row.PurgeAt = &purgeAtCopy
+	}
+	s.emitFileStatusRealtimeEvent(ctx, row, filemanager.FileStatusTrashed, deletedBy, "")
+	return nil
+}
+
+func (s *FileManagerService) PurgeExpiredTrash(ctx context.Context, now time.Time, limit int) (int, int, error) {
+	if limit == 0 {
+		limit = 200
+	}
+	if limit < 0 {
+		limit = 0
+	}
+
+	shouldPurge := func(deletedAt, purgeAt *time.Time) bool {
+		if deletedAt == nil {
+			return false
+		}
+		if purgeAt != nil {
+			return !purgeAt.UTC().After(now.UTC())
+		}
+		if s.trashRetention <= 0 {
+			return false
+		}
+		dueAt := deletedAt.UTC().Add(s.trashRetention)
+		return !dueAt.After(now.UTC())
+	}
+
+	files, _, err := s.fileRepo.ListTrashByFolder(ctx, nil, "deleted_at ASC", 0, 0)
+	if err != nil {
+		return 0, 0, err
+	}
+
+	dueFileIDs := make([][]byte, 0, len(files))
+	for i := range files {
+		if shouldPurge(files[i].DeletedAt, files[i].PurgeAt) {
+			dueFileIDs = append(dueFileIDs, append([]byte(nil), files[i].ID...))
+		}
+	}
+
+	folders, _, err := s.folderRepo.ListTrash(ctx, "deleted_at ASC", 0, 0)
+	if err != nil {
+		return 0, 0, err
+	}
+
+	dueFolders := make([]filemanager.Folder, 0, len(folders))
+	for i := range folders {
+		if shouldPurge(folders[i].DeletedAt, folders[i].PurgeAt) {
+			dueFolders = append(dueFolders, folders[i])
+		}
+	}
+	sort.SliceStable(dueFolders, func(i, j int) bool {
+		return dueFolders[i].Depth < dueFolders[j].Depth
+	})
+
+	purgedFiles := 0
+	purgedFolders := 0
+	maxOps := limit
+	ops := 0
+
+	for i := range dueFileIDs {
+		if maxOps > 0 && ops >= maxOps {
+			return purgedFiles, purgedFolders, nil
+		}
+		if err := s.PurgeFileNode(ctx, dueFileIDs[i]); err != nil {
+			if errors.Is(err, filemanager.ErrFileNotFound) || errors.Is(err, filemanager.ErrFileNotInTrash) {
+				continue
+			}
+			return purgedFiles, purgedFolders, err
+		}
+		purgedFiles++
+		ops++
+	}
+
+	for i := range dueFolders {
+		if maxOps > 0 && ops >= maxOps {
+			return purgedFiles, purgedFolders, nil
+		}
+		if err := s.PurgeFolderNode(ctx, dueFolders[i].ID); err != nil {
+			if errors.Is(err, filemanager.ErrFolderNotFound) || errors.Is(err, filemanager.ErrFolderNotInTrash) {
+				continue
+			}
+			return purgedFiles, purgedFolders, err
+		}
+		purgedFolders++
+		ops++
+	}
+
+	return purgedFiles, purgedFolders, nil
+}
+
+func (s *FileManagerService) RestoreFile(ctx context.Context, id []byte, targetFolderID []byte, targetProvided bool, restoredBy []byte) error {
+	row, err := s.fileRepo.GetByIDAny(ctx, id)
+	if err != nil {
+		return err
+	}
+	if row == nil {
+		return filemanager.ErrFileNotFound
+	}
+	if row.DeletedAt == nil {
+		return filemanager.ErrFileNotInTrash
+	}
+
+	_ = targetFolderID
+	_ = targetProvided
+
+	folder, err := s.folderRepo.GetByID(ctx, row.FolderID)
+	if err != nil {
+		return err
+	}
+	if folder == nil {
+		return filemanager.ErrFolderNotFound
+	}
+	resolvedFolderID := append([]byte(nil), row.FolderID...)
+
+	dup, err := s.fileRepo.GetByFolderAndName(ctx, resolvedFolderID, row.NameNormalized)
+	if err != nil {
+		return err
+	}
+	if dup != nil && !bytesEqual16(dup.ID, row.ID) {
+		return filemanager.ErrDuplicateName
+	}
+
+	row.FolderID = append([]byte(nil), resolvedFolderID...)
+	row.Status = filemanager.FileStatusReady
+	row.TrashedAt = nil
+	row.DeletedAt = nil
+	row.DeletedBy = nil
+	row.PurgeAt = nil
+	row.NameSlot = "live"
+	row.UpdatedBy = restoredBy
+
+	if err := s.fileRepo.Update(ctx, row); err != nil {
+		if errors.Is(err, gorm.ErrDuplicatedKey) {
+			return filemanager.ErrDuplicateName
+		}
+		return err
+	}
+	if err := s.touchFolders(ctx, restoredBy, row.FolderID); err != nil {
+		return err
+	}
+	row.UpdatedAt = time.Now().UTC()
+	s.emitFileStatusRealtimeEvent(ctx, row, filemanager.FileStatusReady, restoredBy, "")
+	return nil
+}
+
+func (s *FileManagerService) PurgeFile(ctx context.Context, id []byte) error {
+	return s.fileRepo.Purge(ctx, id)
+}
+
+func (s *FileManagerService) GetFileByID(ctx context.Context, id []byte) (*filemanager.File, error) {
+	return s.fileRepo.GetByID(ctx, id)
+}
+
+func (s *FileManagerService) GetFileByIDAny(ctx context.Context, id []byte) (*filemanager.File, error) {
+	return s.fileRepo.GetByIDAny(ctx, id)
+}
+
+func (s *FileManagerService) GetFileByObjectKey(ctx context.Context, objectKey string) (*filemanager.File, error) {
+	return s.fileRepo.GetByObjectKey(ctx, objectKey)
+}
+
+func (s *FileManagerService) GetFileByFolderAndName(ctx context.Context, folderID []byte, nameNormalized string) (*filemanager.File, error) {
+	return s.fileRepo.GetByFolderAndName(ctx, folderID, nameNormalized)
+}
+
+func (s *FileManagerService) GetFileByTemplateAndTakeover(ctx context.Context, templateUUID, takeoverID []byte) (*filemanager.File, error) {
+	return s.fileRepo.GetByTemplateAndTakeover(ctx, templateUUID, takeoverID)
+}
+
+func (s *FileManagerService) ListFilesByFolder(ctx context.Context, folderID []byte, sort string, limit, offset int) ([]filemanager.File, int64, error) {
+	return s.fileRepo.ListByFolder(ctx, folderID, normalizeFileSort(sort), limit, offset)
+}
+
+func (s *FileManagerService) ListTrashFilesByFolder(ctx context.Context, folderID []byte, sort string, limit, offset int) ([]filemanager.File, int64, error) {
+	return s.fileRepo.ListTrashByFolder(ctx, folderID, normalizeFileSort(sort), limit, offset)
+}
+
+func (s *FileManagerService) CreateAttachment(ctx context.Context, params filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+	if s.attachmentRepo == nil {
+		return nil, filemanager.ErrAttachmentRepositoryDisabled
+	}
+
+	refType := strings.ToLower(strings.TrimSpace(params.RefType))
+	refID := strings.TrimSpace(params.RefID)
+	if refType == "" || refID == "" {
+		return nil, filemanager.ErrAttachmentRefRequired
+	}
+
+	row, err := s.fileRepo.GetByID(ctx, params.FileID)
+	if err != nil {
+		return nil, err
+	}
+	if row == nil {
+		return nil, filemanager.ErrFileNotFound
+	}
+	if filemanager.NormalizeFileStatus(row.Status) != filemanager.FileStatusReady {
+		return nil, filemanager.ErrFileNotReadyForAttachment
+	}
+
+	category := normalizeOptionalString(params.Category)
+
+	dup, err := s.attachmentRepo.GetByRefAndFile(ctx, refType, refID, row.ID)
+	if err != nil {
+		return nil, err
+	}
+	if dup != nil {
+		return nil, filemanager.ErrAttachmentAlreadyExists
+	}
+
+	attachment := &filemanager.Attachment{
+		FileID:     append([]byte(nil), row.ID...),
+		RefType:    refType,
+		RefID:      refID,
+		Category:   category,
+		SortOrder:  params.SortOrder,
+		IsPrimary:  params.IsPrimary,
+		AttachedBy: append([]byte(nil), params.ActorID...),
+	}
+
+	if err := s.attachmentRepo.Create(ctx, attachment); err != nil {
+		if errors.Is(err, gorm.ErrDuplicatedKey) {
+			return nil, filemanager.ErrAttachmentAlreadyExists
+		}
+		return nil, err
+	}
+
+	if err := s.MarkFileActive(ctx, row.ID, params.ActorID); err != nil {
+		return nil, err
+	}
+
+	created, err := s.attachmentRepo.GetByID(ctx, attachment.ID)
+	if err != nil {
+		return nil, err
+	}
+	if created != nil {
+		return created, nil
+	}
+	return attachment, nil
+}
+
+func (s *FileManagerService) GetAttachmentByID(ctx context.Context, id []byte) (*filemanager.Attachment, error) {
+	if s.attachmentRepo == nil {
+		return nil, filemanager.ErrAttachmentRepositoryDisabled
+	}
+	return s.attachmentRepo.GetByID(ctx, id)
+}
+
+func (s *FileManagerService) ListAttachmentsByReference(ctx context.Context, params filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error) {
+	if s.attachmentRepo == nil {
+		return nil, 0, filemanager.ErrAttachmentRepositoryDisabled
+	}
+
+	refType := strings.ToLower(strings.TrimSpace(params.RefType))
+	refID := strings.TrimSpace(params.RefID)
+	if refType == "" || refID == "" {
+		return nil, 0, filemanager.ErrAttachmentRefRequired
+	}
+
+	filter := filemanager.AttachmentListFilter{
+		RefType:  refType,
+		RefID:    refID,
+		Category: normalizeOptionalString(params.Category),
+		Sort:     normalizeAttachmentSort(params.Sort),
+		Limit:    params.Limit,
+		Offset:   params.Offset,
+	}
+	return s.attachmentRepo.ListByReference(ctx, filter)
+}
+
+func (s *FileManagerService) DeleteAttachment(ctx context.Context, id []byte) error {
+	if s.attachmentRepo == nil {
+		return filemanager.ErrAttachmentRepositoryDisabled
+	}
+
+	existing, err := s.attachmentRepo.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+	if existing == nil {
+		return filemanager.ErrAttachmentNotFound
+	}
+
+	if err := s.attachmentRepo.Delete(ctx, id); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return filemanager.ErrAttachmentNotFound
+		}
+		return err
+	}
+	if err := s.ReconcileFileLifecycle(ctx, existing.FileID, nil); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (s *FileManagerService) ListEditedWBFilesByTakeoverID(ctx context.Context, takeoverID []byte) ([]filemanager.File, error) {
+	return s.fileRepo.ListEditedTemplatesByTakeoverID(ctx, takeoverID)
+}
+
+func (s *FileManagerService) MarkFileActive(ctx context.Context, fileID []byte, actorID []byte) error {
+	if len(fileID) == 0 {
+		return nil
+	}
+	lifecycleRepo, ok := s.fileRepo.(filemanager.FileLifecycleRepository)
+	if !ok {
+		return nil
+	}
+	row, err := s.fileRepo.GetByIDAny(ctx, fileID)
+	if err != nil {
+		return err
+	}
+	if row == nil || row.DeletedAt != nil {
+		return nil
+	}
+	now := time.Now().UTC()
+	if err := lifecycleRepo.UpdateLifecycle(ctx, filemanager.FileLifecycleTransitionParams{
+		ID:              fileID,
+		Status:          filemanager.FileLifecycleStatusActive,
+		UpdatedBy:       actorID,
+		AttachedAt:      &now,
+		ClearOrphanedAt: true,
+	}); err != nil {
+		if !errors.Is(err, gorm.ErrRecordNotFound) {
+			return err
+		}
+		return nil
+	}
+	s.applyLifecycleTag(ctx, row.ObjectKey, lifecycleTagKeep)
+	return nil
+}
+
+func (s *FileManagerService) ReconcileFileLifecycle(ctx context.Context, fileID []byte, actorID []byte) error {
+	if len(fileID) == 0 {
+		return nil
+	}
+	lifecycleRepo, ok := s.fileRepo.(filemanager.FileLifecycleRepository)
+	if !ok {
+		return nil
+	}
+	row, err := s.fileRepo.GetByIDAny(ctx, fileID)
+	if err != nil {
+		return err
+	}
+	if row == nil || row.DeletedAt != nil {
+		return nil
+	}
+	if filemanager.NormalizeFileLifecycleStatus(row.LifecycleStatus) == filemanager.FileLifecycleStatusDeleted {
+		return nil
+	}
+	referenced, err := lifecycleRepo.IsFileReferenced(ctx, fileID)
+	if err != nil {
+		return err
+	}
+	if referenced {
+		return s.MarkFileActive(ctx, fileID, actorID)
+	}
+	now := time.Now().UTC()
+	if err := lifecycleRepo.UpdateLifecycle(ctx, filemanager.FileLifecycleTransitionParams{
+		ID:         fileID,
+		Status:     filemanager.FileLifecycleStatusOrphanPending,
+		UpdatedBy:  actorID,
+		OrphanedAt: &now,
+	}); err != nil {
+		if !errors.Is(err, gorm.ErrRecordNotFound) {
+			return err
+		}
+		return nil
+	}
+	s.applyLifecycleTag(ctx, row.ObjectKey, lifecycleTagKeep)
+	return nil
+}
+
+func (s *FileManagerService) CleanupOrphanPendingFiles(
+	ctx context.Context,
+	now time.Time,
+	gracePeriod time.Duration,
+	limit int,
+	dryRun bool,
+) (filemanager.FileCleanupStats, error) {
+	stats := filemanager.FileCleanupStats{DryRun: dryRun}
+	lifecycleRepo, ok := s.fileRepo.(filemanager.FileLifecycleRepository)
+	if !ok {
+		return stats, nil
+	}
+	if limit <= 0 {
+		limit = 100
+	}
+	cutoff := now.UTC()
+	if gracePeriod > 0 {
+		cutoff = cutoff.Add(-gracePeriod)
+	}
+	rows, err := lifecycleRepo.ListFilesByLifecycle(ctx, filemanager.FileLifecycleListFilter{
+		Status:                  filemanager.FileLifecycleStatusOrphanPending,
+		OrphanedBeforeEq:        &cutoff,
+		ExcludeInTrash:          true,
+		ExcludeLifecycleDeleted: true,
+		Limit:                   limit,
+	})
+	if err != nil {
+		return stats, err
+	}
+	stats = s.reapUnreferencedFiles(ctx, lifecycleRepo, rows, dryRun)
+	s.logger.Info("file cleanup completed", "scanned", stats.Scanned, "deleted", stats.Deleted, "skipped", stats.Skipped, "failed", stats.Failed, "dry_run", dryRun)
+	return stats, nil
+}
+
+func (s *FileManagerService) CleanupStaleTempUploads(
+	ctx context.Context,
+	now time.Time,
+	gracePeriod time.Duration,
+	limit int,
+	dryRun bool,
+) (filemanager.FileCleanupStats, error) {
+	stats := filemanager.FileCleanupStats{DryRun: dryRun}
+	lifecycleRepo, ok := s.fileRepo.(filemanager.FileLifecycleRepository)
+	if !ok {
+		return stats, nil
+	}
+	if limit <= 0 {
+		limit = 100
+	}
+	cutoff := now.UTC()
+	if gracePeriod > 0 {
+		cutoff = cutoff.Add(-gracePeriod)
+	}
+	rows, err := lifecycleRepo.ListFilesByLifecycle(ctx, filemanager.FileLifecycleListFilter{
+		Status:                  filemanager.FileLifecycleStatusTemp,
+		CreatedBeforeEq:         &cutoff,
+		ExcludeInTrash:          true,
+		ExcludeLifecycleDeleted: true,
+		Limit:                   limit,
+	})
+	if err != nil {
+		return stats, err
+	}
+	stats = s.reapUnreferencedFiles(ctx, lifecycleRepo, rows, dryRun)
+	s.logger.Info("temp upload cleanup completed", "scanned", stats.Scanned, "deleted", stats.Deleted, "skipped", stats.Skipped, "failed", stats.Failed, "dry_run", dryRun)
+	return stats, nil
+}
+
+func (s *FileManagerService) CleanupStaleDraftFiles(
+	ctx context.Context,
+	now time.Time,
+	gracePeriod time.Duration,
+	limit int,
+	dryRun bool,
+) (filemanager.FileCleanupStats, error) {
+	stats := filemanager.FileCleanupStats{DryRun: dryRun}
+	lifecycleRepo, ok := s.fileRepo.(filemanager.FileLifecycleRepository)
+	if !ok {
+		return stats, nil
+	}
+	if limit <= 0 {
+		limit = 100
+	}
+	cutoff := now.UTC()
+	if gracePeriod > 0 {
+		cutoff = cutoff.Add(-gracePeriod)
+	}
+	rows, err := lifecycleRepo.ListFilesByLifecycle(ctx, filemanager.FileLifecycleListFilter{
+		Status:                  filemanager.FileLifecycleStatusDraft,
+		CreatedBeforeEq:         &cutoff,
+		ExcludeInTrash:          true,
+		ExcludeLifecycleDeleted: true,
+		Limit:                   limit,
+	})
+	if err != nil {
+		return stats, err
+	}
+	stats = s.reapUnreferencedFiles(ctx, lifecycleRepo, rows, dryRun)
+	s.logger.Info("draft cleanup completed", "scanned", stats.Scanned, "deleted", stats.Deleted, "skipped", stats.Skipped, "failed", stats.Failed, "dry_run", dryRun)
+	return stats, nil
+}
+
+func (s *FileManagerService) reapUnreferencedFiles(
+	ctx context.Context,
+	lifecycleRepo filemanager.FileLifecycleRepository,
+	rows []filemanager.File,
+	dryRun bool,
+) filemanager.FileCleanupStats {
+	stats := filemanager.FileCleanupStats{DryRun: dryRun}
+	for i := range rows {
+		row := rows[i]
+		stats.Scanned++
+
+		referenced, refErr := lifecycleRepo.IsFileReferenced(ctx, row.ID)
+		if refErr != nil {
+			stats.Failed++
+			s.logger.Error("file cleanup: reference check failed", "file_id", fileIDString(row.ID), "error", refErr)
+			continue
+		}
+		if referenced {
+			if err := s.MarkFileActive(ctx, row.ID, nil); err != nil {
+				stats.Failed++
+				s.logger.Error("file cleanup: re-activate failed", "file_id", fileIDString(row.ID), "error", err)
+				continue
+			}
+			stats.Skipped++
+			continue
+		}
+
+		if dryRun {
+			stats.Skipped++
+			s.logger.Info("file cleanup dry-run: candidate", "file_id", fileIDString(row.ID), "object_key", row.ObjectKey)
+			continue
+		}
+
+		s.applyLifecycleTag(ctx, row.ObjectKey, lifecycleTagDelete)
+		if err := s.deleteFileObjects(ctx, &row); err != nil {
+			stats.Failed++
+			s.logger.Error("file cleanup: object delete failed", "file_id", fileIDString(row.ID), "error", err)
+			continue
+		}
+		deletedAt := time.Now().UTC()
+		if err := lifecycleRepo.UpdateLifecycle(ctx, filemanager.FileLifecycleTransitionParams{
+			ID:              row.ID,
+			Status:          filemanager.FileLifecycleStatusDeleted,
+			UpdatedBy:       nil,
+			LifecycleDelete: &deletedAt,
+			ClearOrphanedAt: true,
+		}); err != nil {
+			stats.Failed++
+			s.logger.Error("file cleanup: mark deleted failed", "file_id", fileIDString(row.ID), "error", err)
+			continue
+		}
+		stats.Deleted++
+	}
+	return stats
+}
+
+const (
+	lifecycleTagKey    = "gc"
+	lifecycleTagTemp   = "temp"
+	lifecycleTagKeep   = "keep"
+	lifecycleTagDelete = "delete"
+)
+
+func (s *FileManagerService) ensureLifecycleTempMarker(ctx context.Context, row *filemanager.File) {
+	if row == nil {
+		return
+	}
+	if row.DeletedAt != nil {
+		return
+	}
+	status := filemanager.NormalizeFileLifecycleStatus(row.LifecycleStatus)
+	if status != "" && status != filemanager.FileLifecycleStatusTemp {
+		return
+	}
+	if lifecycleRepo, ok := s.fileRepo.(filemanager.FileLifecycleRepository); ok {
+		if err := lifecycleRepo.UpdateLifecycle(ctx, filemanager.FileLifecycleTransitionParams{
+			ID:              row.ID,
+			Status:          filemanager.FileLifecycleStatusTemp,
+			UpdatedBy:       row.UpdatedBy,
+			ClearOrphanedAt: true,
+		}); err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+			s.logger.Error("failed to set temp lifecycle status", "file_id", fileIDString(row.ID), "error", err)
+		}
+	}
+	s.applyLifecycleTag(ctx, row.ObjectKey, lifecycleTagTemp)
+}
+
+func (s *FileManagerService) applyLifecycleTag(ctx context.Context, objectKey, value string) {
+	if !s.enableS3Tagging {
+		return
+	}
+	tagger, ok := s.storage.(filemanager.ObjectTaggingStorage)
+	if !ok {
+		return
+	}
+	key := strings.TrimSpace(objectKey)
+	val := strings.TrimSpace(value)
+	if key == "" || val == "" {
+		return
+	}
+	go func(k, v string) {
+		bgCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		if err := tagger.PutObjectTagging(bgCtx, k, map[string]string{lifecycleTagKey: v}); err != nil {
+			s.logger.Error("failed to apply lifecycle object tag", "object_key", k, "tag", lifecycleTagKey+"="+v, "error", err)
+		}
+	}(key, val)
+}
+
+func (s *FileManagerService) deleteFileObjects(ctx context.Context, row *filemanager.File) error {
+	if row == nil || s.storage == nil {
+		return nil
+	}
+	keys := make([]string, 0, 2)
+	if key := strings.TrimSpace(row.ObjectKey); key != "" {
+		keys = append(keys, key)
+	}
+	if row.ThumbnailObjectKey != nil {
+		if key := strings.TrimSpace(*row.ThumbnailObjectKey); key != "" {
+			keys = append(keys, key)
+		}
+	}
+	for i := range keys {
+		if err := s.storage.DeleteObject(ctx, keys[i]); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func fileIDString(id []byte) string {
+	v, err := uuidv7.BytesToString(id)
+	if err != nil {
+		return ""
+	}
+	return v
+}
+
+func normalizeFolderName(raw string) (string, string, error) {
+	name := strings.TrimSpace(raw)
+	if name == "" {
+		return "", "", filemanager.ErrInvalidName
+	}
+	if name == "." || name == ".." || strings.ContainsAny(name, "/\\") {
+		return "", "", filemanager.ErrInvalidName
+	}
+	nameNormalized := strings.ToLower(name)
+	if nameNormalized == filemanager.SystemRootFolderName {
+		return "", "", filemanager.ErrReservedName
+	}
+	return name, nameNormalized, nil
+}
+
+func normalizeFileName(raw string) (string, string, error) {
+	name := strings.TrimSpace(raw)
+	if name == "" {
+		return "", "", filemanager.ErrInvalidName
+	}
+	name = strings.ReplaceAll(name, "\\", "/")
+	name = filepath.Base(name)
+	if name == "" || name == "." || name == "/" || strings.Contains(name, "\x00") {
+		return "", "", filemanager.ErrInvalidName
+	}
+	return name, strings.ToLower(name), nil
+}
+
+func buildFolderPathCache(parentPath, name string) string {
+	parentPath = strings.TrimSpace(parentPath)
+	if parentPath == "" {
+		return "/" + name
+	}
+	parentPath = strings.TrimRight(parentPath, "/")
+	return parentPath + "/" + name
+}
+
+func extensionFromName(name string) string {
+	ext := strings.TrimPrefix(strings.ToLower(filepath.Ext(name)), ".")
+	if len(ext) > 32 {
+		ext = ext[:32]
+	}
+	return ext
+}
+
+func (s *FileManagerService) resolveAvailableFileName(
+	ctx context.Context,
+	folderID []byte,
+	requestedName string,
+	excludeID []byte,
+) (string, string, error) {
+	name, nameNormalized, err := normalizeFileName(requestedName)
+	if err != nil {
+		return "", "", err
+	}
+
+	available, err := s.isFileNameAvailable(ctx, folderID, nameNormalized, excludeID)
+	if err != nil {
+		return "", "", err
+	}
+	if available {
+		return name, nameNormalized, nil
+	}
+
+	base, ext := splitNameAndExt(name)
+	for i := 1; i <= 10000; i++ {
+		candidateRaw := indexedFileName(base, ext, i)
+		candidate, candidateNormalized, err := normalizeFileName(candidateRaw)
+		if err != nil {
+			return "", "", err
+		}
+		available, err := s.isFileNameAvailable(ctx, folderID, candidateNormalized, excludeID)
+		if err != nil {
+			return "", "", err
+		}
+		if available {
+			return candidate, candidateNormalized, nil
+		}
+	}
+
+	return "", "", filemanager.ErrDuplicateName
+}
+
+func (s *FileManagerService) isFileNameAvailable(
+	ctx context.Context,
+	folderID []byte,
+	nameNormalized string,
+	excludeID []byte,
+) (bool, error) {
+	dup, err := s.fileRepo.GetByFolderAndName(ctx, folderID, nameNormalized)
+	if err != nil {
+		return false, err
+	}
+	if dup == nil {
+		return true, nil
+	}
+	if len(excludeID) == 16 && bytesEqual16(dup.ID, excludeID) {
+		return true, nil
+	}
+	return false, nil
+}
+
+func splitNameAndExt(name string) (string, string) {
+	ext := filepath.Ext(name)
+	base := strings.TrimSuffix(name, ext)
+	if base == "" {
+		base = name
+		ext = ""
+	}
+	return base, ext
+}
+
+func indexedFileName(base, ext string, idx int) string {
+	suffix := fmt.Sprintf(" (%d)", idx)
+	maxNameRunes := 255
+	allowedBaseRunes := maxNameRunes - utf8.RuneCountInString(ext) - utf8.RuneCountInString(suffix)
+	if allowedBaseRunes < 1 {
+		allowedBaseRunes = 1
+	}
+	if utf8.RuneCountInString(base) > allowedBaseRunes {
+		base = truncateRunes(base, allowedBaseRunes)
+		base = strings.TrimSpace(base)
+		if base == "" {
+			base = "file"
+		}
+	}
+	return base + suffix + ext
+}
+
+func truncateRunes(value string, maxRunes int) string {
+	if maxRunes <= 0 {
+		return ""
+	}
+	if utf8.RuneCountInString(value) <= maxRunes {
+		return value
+	}
+	var b strings.Builder
+	count := 0
+	for _, r := range value {
+		if count >= maxRunes {
+			break
+		}
+		b.WriteRune(r)
+		count++
+	}
+	return b.String()
+}
+
+func buildImmutableFileObjectKey(name string) string {
+	uuidBytes := uuidv7.MustBytes()
+	uuidStr, err := uuidv7.BytesToString(uuidBytes)
+	if err != nil {
+		uuidStr = strings.ReplaceAll(fmt.Sprintf("%x", uuidBytes), "-", "")
+	}
+	uuidStr = strings.ReplaceAll(uuidStr, "-", "")
+	ext := filepath.Ext(name)
+	ext = strings.ToLower(strings.TrimSpace(ext))
+	if len(ext) > 16 {
+		ext = ext[:16]
+	}
+	datePrefix := time.Now().UTC().Format("2006/01/02")
+	if ext == "" {
+		return "files/" + datePrefix + "/" + uuidStr
+	}
+	return "files/" + datePrefix + "/" + uuidStr + ext
+}
+
+func tempUploadNameSlot() string {
+	uuidBytes := uuidv7.MustBytes()
+	slot, err := uuidv7.BytesToString(uuidBytes)
+	if err == nil && strings.TrimSpace(slot) != "" {
+		return slot
+	}
+	return strings.ReplaceAll(fmt.Sprintf("%x", uuidBytes), "-", "")
+}
+
+func ensureFileStatusTransition(fromStatus, toStatus string) error {
+	from := filemanager.NormalizeFileStatus(fromStatus)
+	to := filemanager.NormalizeFileStatus(toStatus)
+	if !filemanager.CanTransitionFileStatus(from, to) {
+		return fmt.Errorf("%w: %s -> %s", filemanager.ErrInvalidFileStatusTransition, from, to)
+	}
+	return nil
+}
+
+func normalizeUploadPolicy(policy filemanager.FileUploadPolicy) filemanager.FileUploadPolicy {
+	normalized := filemanager.FileUploadPolicy{
+		MaxFileSizeBytes:  policy.MaxFileSizeBytes,
+		AllowEmptyFile:    policy.AllowEmptyFile,
+		MaxFilenameLength: policy.MaxFilenameLength,
+	}
+	if normalized.MaxFilenameLength <= 0 {
+		normalized.MaxFilenameLength = 255
+	}
+
+	if len(policy.AllowedMimeTypes) > 0 {
+		seen := make(map[string]struct{}, len(policy.AllowedMimeTypes))
+		for i := range policy.AllowedMimeTypes {
+			v := normalizeMimeTypeToken(policy.AllowedMimeTypes[i])
+			if v == "" {
+				continue
+			}
+			if _, ok := seen[v]; ok {
+				continue
+			}
+			seen[v] = struct{}{}
+			normalized.AllowedMimeTypes = append(normalized.AllowedMimeTypes, v)
+		}
+	}
+
+	if len(policy.AllowedExtensions) > 0 {
+		seen := make(map[string]struct{}, len(policy.AllowedExtensions))
+		for i := range policy.AllowedExtensions {
+			v := normalizeExtensionToken(policy.AllowedExtensions[i])
+			if v == "" {
+				continue
+			}
+			if _, ok := seen[v]; ok {
+				continue
+			}
+			seen[v] = struct{}{}
+			normalized.AllowedExtensions = append(normalized.AllowedExtensions, v)
+		}
+	}
+
+	return normalized
+}
+
+func (s *FileManagerService) validateUploadAgainstPolicy(fileName, contentType string, sizeBytes int64) error {
+	policy := s.uploadPolicy
+
+	if sizeBytes == 0 && !policy.AllowEmptyFile {
+		return filemanager.ErrEmptyFileNotAllowed
+	}
+	if policy.MaxFileSizeBytes > 0 && sizeBytes > policy.MaxFileSizeBytes {
+		return fmt.Errorf("%w: max %d bytes", filemanager.ErrFileTooLarge, policy.MaxFileSizeBytes)
+	}
+
+	if policy.MaxFilenameLength > 0 {
+		nameLength := utf8.RuneCountInString(fileName)
+		if nameLength > policy.MaxFilenameLength {
+			return fmt.Errorf("%w: max %d characters", filemanager.ErrFileNameTooLong, policy.MaxFilenameLength)
+		}
+	}
+
+	if len(policy.AllowedMimeTypes) > 0 {
+		allowed := false
+		normalizedMime := normalizeMimeTypeToken(contentType)
+		for i := range policy.AllowedMimeTypes {
+			if policy.AllowedMimeTypes[i] == normalizedMime {
+				allowed = true
+				break
+			}
+		}
+		if !allowed {
+			return fmt.Errorf("%w: %s", filemanager.ErrFileMimeTypeNotAllowed, normalizedMime)
+		}
+	}
+
+	if len(policy.AllowedExtensions) > 0 {
+		allowed := false
+		ext := normalizeExtensionToken(extensionFromName(fileName))
+		for i := range policy.AllowedExtensions {
+			if policy.AllowedExtensions[i] == ext {
+				allowed = true
+				break
+			}
+		}
+		if !allowed {
+			if ext == "" {
+				return fmt.Errorf("%w: file has no extension", filemanager.ErrFileExtensionNotAllowed)
+			}
+			return fmt.Errorf("%w: .%s", filemanager.ErrFileExtensionNotAllowed, ext)
+		}
+	}
+
+	return nil
+}
+
+func normalizeUploadedMimeType(raw string) string {
+	normalized := normalizeMimeTypeToken(raw)
+	if normalized == "" {
+		return "application/octet-stream"
+	}
+	return normalized
+}
+
+func normalizeMimeTypeToken(raw string) string {
+	v := strings.ToLower(strings.TrimSpace(raw))
+	if idx := strings.Index(v, ";"); idx >= 0 {
+		v = strings.TrimSpace(v[:idx])
+	}
+	return v
+}
+
+func normalizeExtensionToken(raw string) string {
+	v := strings.ToLower(strings.TrimSpace(raw))
+	v = strings.TrimPrefix(v, ".")
+	return v
+}
+
+func (s *FileManagerService) fileOutboxReady() bool {
+	return s.fileOutbox != nil && s.fileOutboxSerializer != nil
+}
+
+func (s *FileManagerService) persistFileProcessingOutbox(
+	ctx context.Context,
+	outbox filemanager.FileProcessingOutboxWriter,
+	row *filemanager.File,
+	actorID []byte,
+) error {
+	if outbox == nil || !s.fileOutboxReady() {
+		return filemanager.ErrFileProcessingQueueDisabled
+	}
+	job, err := buildFileProcessingJob(row, actorID)
+	if err != nil {
+		return err
+	}
+	message, err := s.fileOutboxSerializer.Serialize(ctx, queue.FileProcessingJob{
+		JobID:      job.JobID,
+		FileUUID:   job.FileUUID,
+		Bucket:     job.Bucket,
+		ObjectKey:  job.ObjectKey,
+		UploadedBy: job.UploadedBy,
+		MimeType:   job.MimeType,
+		SizeBytes:  job.SizeBytes,
+		TraceID:    job.TraceID,
+		RequestID:  job.RequestID,
+	})
+	if err != nil {
+		return err
+	}
+	record, err := filemanager.NewFileProcessingOutboxMessage(time.Now().UTC(), &filemanager.FileProcessingOutboundMessage{
+		ID:              message.ID,
+		Body:            append([]byte(nil), message.Body...),
+		Attributes:      message.Attributes,
+		MessageGroupID:  message.MessageGroupID,
+		DeduplicationID: message.DeduplicationID,
+	})
+	if err != nil {
+		return err
+	}
+	return outbox.CreateFileProcessingOutboxMessage(ctx, record)
+}
+
+func (s *FileManagerService) enqueueUploadedFileForProcessing(ctx context.Context, row *filemanager.File, actorID []byte) error {
+	if row == nil {
+		return filemanager.ErrFileNotFound
+	}
+	if s.fileQueue == nil {
+		return filemanager.ErrFileProcessingQueueDisabled
+	}
+	job, err := buildFileProcessingJob(row, actorID)
+	if err != nil {
+		return err
+	}
+	return s.fileQueue.Enqueue(ctx, job)
+}
+
+func (s *FileManagerService) verifyUploadedObjectForIntent(ctx context.Context, intent *filemanager.FileUploadIntent) (filemanager.ObjectMetadata, error) {
+	if intent == nil {
+		return filemanager.ObjectMetadata{}, filemanager.ErrUploadIntentNotFound
+	}
+
+	meta, err := s.storage.HeadObject(ctx, intent.ObjectKey)
+	if err != nil {
+		if errors.Is(err, filemanager.ErrUploadObjectNotFound) {
+			return filemanager.ObjectMetadata{}, filemanager.ErrUploadObjectNotFound
+		}
+		return filemanager.ObjectMetadata{}, err
+	}
+
+	if strings.TrimSpace(meta.ObjectKey) == "" {
+		meta.ObjectKey = strings.TrimSpace(intent.ObjectKey)
+	}
+	if strings.TrimSpace(meta.Bucket) == "" {
+		meta.Bucket = strings.TrimSpace(intent.Bucket)
+	}
+
+	if strings.TrimSpace(meta.ObjectKey) != strings.TrimSpace(intent.ObjectKey) {
+		return filemanager.ObjectMetadata{}, fmt.Errorf("%w: object key mismatch", filemanager.ErrUploadObjectMismatch)
+	}
+	if expectedBucket := strings.TrimSpace(intent.Bucket); expectedBucket != "" && !strings.EqualFold(strings.TrimSpace(meta.Bucket), expectedBucket) {
+		return filemanager.ObjectMetadata{}, fmt.Errorf("%w: bucket mismatch", filemanager.ErrUploadObjectMismatch)
+	}
+	if intent.SizeBytes >= 0 && meta.SizeBytes != intent.SizeBytes {
+		return filemanager.ObjectMetadata{}, fmt.Errorf("%w: expected size %d bytes, got %d bytes", filemanager.ErrUploadObjectMismatch, intent.SizeBytes, meta.SizeBytes)
+	}
+
+	expectedMime := normalizeMimeTypeToken(intent.MimeType)
+	actualMime := normalizeMimeTypeToken(meta.ContentType)
+	if expectedMime != "" && actualMime != "" && expectedMime != actualMime {
+		return filemanager.ObjectMetadata{}, fmt.Errorf("%w: expected mime %s, got %s", filemanager.ErrUploadObjectMismatch, expectedMime, actualMime)
+	}
+	return meta, nil
+}
+
+func (s *FileManagerService) createUploadedFileFromIntent(
+	ctx context.Context,
+	intent *filemanager.FileUploadIntent,
+	meta filemanager.ObjectMetadata,
+	actorID []byte,
+) (*filemanager.File, error) {
+	if intent == nil {
+		return nil, filemanager.ErrUploadIntentNotFound
+	}
+
+	root, err := s.GetOrCreateSystemRootFolder(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	sizeBytes := intent.SizeBytes
+	if meta.SizeBytes >= 0 {
+		sizeBytes = meta.SizeBytes
+	}
+	mimeType := normalizeUploadedMimeType(firstNonEmptyString(meta.ContentType, intent.MimeType))
+	row := &filemanager.File{
+		ID:                  uuidv7.MustBytes(),
+		FolderID:            root.ID,
+		Name:                intent.Name,
+		NameNormalized:      intent.NameNormalized,
+		Extension:           firstNonEmptyString(intent.Extension, extensionFromName(intent.Name)),
+		SizeBytes:           sizeBytes,
+		MimeType:            mimeType,
+		Bucket:              firstNonEmptyString(meta.Bucket, intent.Bucket),
+		ObjectKey:           firstNonEmptyString(meta.ObjectKey, intent.ObjectKey),
+		ObjectVersion:       strings.TrimSpace(meta.VersionID),
+		ETag:                strings.TrimSpace(meta.ETag),
+		IsTemplate:          false,
+		Status:              filemanager.FileStatusUploaded,
+		LifecycleStatus:     filemanager.FileLifecycleStatusTemp,
+		ProcessingStartedAt: nil,
+		ProcessedAt:         nil,
+		ValidatedAt:         nil,
+		NameSlot:            tempUploadNameSlot(),
+		CreatedBy:           actorID,
+		UpdatedBy:           actorID,
+	}
+
+	if err := s.fileRepo.Create(ctx, row); err != nil {
+		return nil, err
+	}
+
+	created, err := s.fileRepo.GetByID(ctx, row.ID)
+	if err == nil && created != nil {
+		return created, nil
+	}
+	return row, nil
+}
+
+func (s *FileManagerService) completeFileUploadIntentDurable(
+	ctx context.Context,
+	txRepo filemanager.FileTransactionalRepository,
+	intent *filemanager.FileUploadIntent,
+	meta filemanager.ObjectMetadata,
+	actorID []byte,
+) (*filemanager.File, error) {
+	var completedRow *filemanager.File
+	root, err := s.GetOrCreateSystemRootFolder(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := txRepo.WithTransaction(ctx, func(repo filemanager.FileRepository, outbox filemanager.FileProcessingOutboxWriter) error {
+		intentRepo, ok := repo.(filemanager.FileUploadIntentRepository)
+		if !ok {
+			return filemanager.ErrUploadIntentRepositoryDisabled
+		}
+
+		lockedIntent, err := intentRepo.GetUploadIntentByIDForUpdate(ctx, intent.ID)
+		if err != nil {
+			return err
+		}
+		if lockedIntent == nil {
+			return filemanager.ErrUploadIntentNotFound
+		}
+
+		status := filemanager.NormalizeFileUploadIntentStatus(lockedIntent.Status)
+		switch status {
+		case filemanager.FileUploadIntentStatusCompleted:
+			existing, getErr := repo.GetByObjectKey(ctx, lockedIntent.ObjectKey)
+			if getErr != nil {
+				return getErr
+			}
+			if existing != nil {
+				completedRow = existing
+				return nil
+			}
+			return filemanager.ErrUploadIntentAlreadyComplete
+		case filemanager.FileUploadIntentStatusExpired:
+			return filemanager.ErrUploadIntentExpired
+		case filemanager.FileUploadIntentStatusPending:
+		default:
+			return filemanager.ErrUploadIntentStatusConflict
+		}
+
+		now := time.Now().UTC()
+		if !lockedIntent.ExpiresAt.IsZero() && now.After(lockedIntent.ExpiresAt.UTC()) {
+			if err := intentRepo.MarkUploadIntentExpired(ctx, filemanager.FileUploadIntentExpireParams{
+				ID:        lockedIntent.ID,
+				UpdatedBy: actorID,
+				ExpiredAt: now,
+			}); err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+				return err
+			}
+			return filemanager.ErrUploadIntentExpired
+		}
+
+		existing, err := repo.GetByObjectKey(ctx, lockedIntent.ObjectKey)
+		if err != nil {
+			return err
+		}
+		if existing != nil {
+			completedRow = existing
+			if err := intentRepo.MarkUploadIntentCompleted(ctx, filemanager.FileUploadIntentCompleteParams{
+				ID:          lockedIntent.ID,
+				UpdatedBy:   actorID,
+				CompletedAt: now,
+			}); err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+				return err
+			}
+			return nil
+		}
+
+		sizeBytes := lockedIntent.SizeBytes
+		if meta.SizeBytes >= 0 {
+			sizeBytes = meta.SizeBytes
+		}
+		row := &filemanager.File{
+			ID:                  uuidv7.MustBytes(),
+			FolderID:            root.ID,
+			Name:                lockedIntent.Name,
+			NameNormalized:      lockedIntent.NameNormalized,
+			Extension:           firstNonEmptyString(lockedIntent.Extension, extensionFromName(lockedIntent.Name)),
+			SizeBytes:           sizeBytes,
+			MimeType:            normalizeUploadedMimeType(firstNonEmptyString(meta.ContentType, lockedIntent.MimeType)),
+			Bucket:              firstNonEmptyString(meta.Bucket, lockedIntent.Bucket),
+			ObjectKey:           firstNonEmptyString(meta.ObjectKey, lockedIntent.ObjectKey),
+			ObjectVersion:       strings.TrimSpace(meta.VersionID),
+			ETag:                strings.TrimSpace(meta.ETag),
+			Status:              filemanager.FileStatusUploaded,
+			LifecycleStatus:     filemanager.FileLifecycleStatusTemp,
+			ProcessingStartedAt: nil,
+			ProcessedAt:         nil,
+			ValidatedAt:         nil,
+			NameSlot:            tempUploadNameSlot(),
+			CreatedBy:           actorID,
+			UpdatedBy:           actorID,
+		}
+
+		if err := repo.Create(ctx, row); err != nil {
+			return err
+		}
+		if err := s.persistFileProcessingOutbox(ctx, outbox, row, actorID); err != nil {
+			return err
+		}
+		if err := intentRepo.MarkUploadIntentCompleted(ctx, filemanager.FileUploadIntentCompleteParams{
+			ID:          lockedIntent.ID,
+			UpdatedBy:   actorID,
+			CompletedAt: now,
+		}); err != nil {
+			return err
+		}
+
+		completedRow = row
+		return nil
+	}); err != nil {
+		return nil, err
+	}
+
+	if completedRow == nil {
+		return nil, filemanager.ErrFileNotFound
+	}
+
+	if len(completedRow.ID) == 16 {
+		created, err := s.fileRepo.GetByID(ctx, completedRow.ID)
+		if err == nil && created != nil {
+			return created, nil
+		}
+	}
+	return completedRow, nil
+}
+
+func (s *FileManagerService) emitFileStatusRealtimeEvent(
+	ctx context.Context,
+	row *filemanager.File,
+	status string,
+	actorID []byte,
+	failureReason string,
+) {
+	if s.fileStatusEvents == nil || row == nil {
+		return
+	}
+	if len(row.ID) == 0 {
+		return
+	}
+
+	status = filemanager.NormalizeFileStatus(status)
+	if !filemanager.IsKnownFileStatus(status) {
+		return
+	}
+
+	userID := pickRealtimeEventUserID(actorID, row.CreatedBy, row.UpdatedBy)
+	if len(userID) == 0 {
+		return
+	}
+
+	name := strings.TrimSpace(row.Name)
+	reason := strings.TrimSpace(failureReason)
+	if reason == "" {
+		reason = strings.TrimSpace(row.FailureReason)
+	}
+	occurredAt := row.UpdatedAt
+	if occurredAt.IsZero() {
+		occurredAt = time.Now().UTC()
+	}
+
+	_ = s.fileStatusEvents.CreateFileStatusRealtimeEvent(ctx, filemanager.FileStatusRealtimeEventInput{
+		FileID:        append([]byte(nil), row.ID...),
+		UserID:        userID,
+		Status:        status,
+		Name:          name,
+		FailureReason: reason,
+		OccurredAt:    occurredAt,
+	})
+}
+
+func pickRealtimeEventUserID(candidates ...[]byte) []byte {
+	for i := range candidates {
+		if len(candidates[i]) == 16 {
+			return append([]byte(nil), candidates[i]...)
+		}
+	}
+	return nil
+}
+
+func buildFileProcessingJob(row *filemanager.File, actorID []byte) (filemanager.FileProcessingJob, error) {
+	if row == nil {
+		return filemanager.FileProcessingJob{}, filemanager.ErrFileNotFound
+	}
+	job := filemanager.FileProcessingJob{
+		Bucket:     strings.TrimSpace(row.Bucket),
+		ObjectKey:  strings.TrimSpace(row.ObjectKey),
+		MimeType:   strings.TrimSpace(row.MimeType),
+		SizeBytes:  row.SizeBytes,
+		UploadedBy: bytesToUUIDString(actorID),
+	}
+	fileUUID, err := uuidv7.BytesToString(row.ID)
+	if err != nil {
+		return filemanager.FileProcessingJob{}, fmt.Errorf("convert file id to uuid: %w", err)
+	}
+	job.FileUUID = fileUUID
+	return job, nil
+}
+
+func truncateFailureReason(raw string) string {
+	const maxReasonLength = 1024
+	raw = strings.TrimSpace(raw)
+	if len(raw) <= maxReasonLength {
+		return raw
+	}
+	return raw[:maxReasonLength]
+}
+
+func bytesToUUIDString(raw []byte) string {
+	if len(raw) == 0 {
+		return ""
+	}
+	value, err := uuidv7.BytesToString(raw)
+	if err != nil {
+		return ""
+	}
+	return value
+}
+
+func firstNonEmptyString(values ...string) string {
+	for i := range values {
+		value := strings.TrimSpace(values[i])
+		if value != "" {
+			return value
+		}
+	}
+	return ""
+}
+
+func cloneTrimmedStringMap(input map[string]string) map[string]string {
+	if len(input) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(input))
+	for key, value := range input {
+		k := strings.TrimSpace(key)
+		if k == "" {
+			continue
+		}
+		out[k] = strings.TrimSpace(value)
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func (s *FileManagerService) collectFolderSubtreeAny(ctx context.Context, rootID []byte) ([]filemanager.Folder, error) {
+	root, err := s.folderRepo.GetByIDAny(ctx, rootID)
+	if err != nil {
+		return nil, err
+	}
+	if root == nil {
+		return nil, nil
+	}
+
+	out := make([]filemanager.Folder, 0, 16)
+	queue := make([]filemanager.Folder, 0, 16)
+	seen := make(map[string]struct{}, 16)
+
+	rootUUID := bytesToUUIDString(root.ID)
+	seen[rootUUID] = struct{}{}
+	out = append(out, *root)
+	queue = append(queue, *root)
+
+	for len(queue) > 0 {
+		parent := queue[0]
+		queue = queue[1:]
+
+		activeChildren, _, err := s.folderRepo.ListByParent(ctx, parent.ID, "name ASC", 0, 0)
+		if err != nil {
+			return nil, err
+		}
+		trashedChildren, _, err := s.folderRepo.ListTrashByParent(ctx, parent.ID, "name ASC", 0, 0)
+		if err != nil {
+			return nil, err
+		}
+
+		for i := range activeChildren {
+			child := activeChildren[i]
+			key := bytesToUUIDString(child.ID)
+			if _, ok := seen[key]; ok {
+				continue
+			}
+			seen[key] = struct{}{}
+			out = append(out, child)
+			queue = append(queue, child)
+		}
+		for i := range trashedChildren {
+			child := trashedChildren[i]
+			key := bytesToUUIDString(child.ID)
+			if _, ok := seen[key]; ok {
+				continue
+			}
+			seen[key] = struct{}{}
+			out = append(out, child)
+			queue = append(queue, child)
+		}
+	}
+
+	return out, nil
+}
+
+func (s *FileManagerService) listActiveFilesByFolders(ctx context.Context, folderIDs [][]byte) ([]filemanager.File, error) {
+	out := make([]filemanager.File, 0, len(folderIDs))
+	for i := range folderIDs {
+		rows, _, err := s.fileRepo.ListByFolder(ctx, folderIDs[i], "name ASC", 0, 0)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, rows...)
+	}
+	return out, nil
+}
+
+func (s *FileManagerService) listTrashedFilesByFolders(ctx context.Context, folderIDs [][]byte) ([]filemanager.File, error) {
+	out := make([]filemanager.File, 0, len(folderIDs))
+	for i := range folderIDs {
+		rows, _, err := s.fileRepo.ListTrashByFolder(ctx, folderIDs[i], "name ASC", 0, 0)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, rows...)
+	}
+	return out, nil
+}
+
+func (s *FileManagerService) listAllFilesByFolders(ctx context.Context, folderIDs [][]byte) ([]filemanager.File, error) {
+	activeRows, err := s.listActiveFilesByFolders(ctx, folderIDs)
+	if err != nil {
+		return nil, err
+	}
+	trashedRows, err := s.listTrashedFilesByFolders(ctx, folderIDs)
+	if err != nil {
+		return nil, err
+	}
+
+	out := make([]filemanager.File, 0, len(activeRows)+len(trashedRows))
+	seen := make(map[string]struct{}, len(activeRows)+len(trashedRows))
+
+	appendUnique := func(rows []filemanager.File) {
+		for i := range rows {
+			key := bytesToUUIDString(rows[i].ID)
+			if _, ok := seen[key]; ok {
+				continue
+			}
+			seen[key] = struct{}{}
+			out = append(out, rows[i])
+		}
+	}
+
+	appendUnique(activeRows)
+	appendUnique(trashedRows)
+	return out, nil
+}
+
+func uniqueNonEmptyStrings(values []string) []string {
+	if len(values) == 0 {
+		return nil
+	}
+
+	out := make([]string, 0, len(values))
+	seen := make(map[string]struct{}, len(values))
+	for i := range values {
+		value := strings.TrimSpace(values[i])
+		if value == "" {
+			continue
+		}
+		if _, ok := seen[value]; ok {
+			continue
+		}
+		seen[value] = struct{}{}
+		out = append(out, value)
+	}
+	return out
+}
+
+func replaceFolderPathPrefix(pathCache string, oldPrefix string, newPrefix string) string {
+	if oldPrefix == "" {
+		return pathCache
+	}
+	if pathCache == oldPrefix {
+		return newPrefix
+	}
+	prefixWithSlash := oldPrefix + "/"
+	if strings.HasPrefix(pathCache, prefixWithSlash) {
+		return newPrefix + strings.TrimPrefix(pathCache, oldPrefix)
+	}
+	return pathCache
+}
+
+func bytesEqual16(a, b []byte) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
+
+func isSystemRootFolder(row *filemanager.Folder) bool {
+	if row == nil {
+		return false
+	}
+	return len(row.ParentID) == 0 && strings.EqualFold(strings.TrimSpace(row.NameNormalized), filemanager.SystemRootFolderName)
+}
+
+func normalizeFolderSort(sort string) string {
+	if normalized := normalizeSortByRules(sort,
+		sortField("name"),
+		sortField("depth"),
+		sortField("created_at"),
+		sortField("updated_at", "updated_at", "updated_by"),
+	); normalized != "" {
+		return normalized
+	}
+	return "name ASC"
+}
+
+func normalizeFileSort(sort string) string {
+	if normalized := normalizeSortByRules(sort,
+		sortField("name"),
+		sortField("size_bytes"),
+		sortField("mime_type"),
+		sortField("created_at"),
+		sortField("updated_at", "updated_at", "updated_by"),
+	); normalized != "" {
+		return normalized
+	}
+	return "name ASC"
+}
+
+func normalizeAttachmentSort(sort string) string {
+	if normalized := normalizeSortByRules(sort,
+		sortExpr("sort_order ASC, created_at DESC", "sort_order DESC, created_at DESC", "sort_order"),
+		sortField("created_at"),
+		sortField("updated_at", "updated_at", "updated_by"),
+	); normalized != "" {
+		return normalized
+	}
+	return "sort_order ASC, created_at DESC"
+}
+
+func normalizeOptionalString(value *string) *string {
+	if value == nil {
+		return nil
+	}
+	cleaned := strings.TrimSpace(*value)
+	if cleaned == "" {
+		return nil
+	}
+	return &cleaned
+}
+
+func (s *FileManagerService) touchFolders(ctx context.Context, updatedBy []byte, folderIDs ...[]byte) error {
+	seen := make(map[string]struct{}, len(folderIDs))
+	now := time.Now().UTC()
+	queue := make([][]byte, 0, len(folderIDs))
+	for i := range folderIDs {
+		if len(folderIDs[i]) != 0 {
+			queue = append(queue, append([]byte(nil), folderIDs[i]...))
+		}
+	}
+	for len(queue) > 0 {
+		id := queue[0]
+		queue = queue[1:]
+		if len(id) == 0 {
+			continue
+		}
+		key := string(id)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+
+		folder, err := s.folderRepo.GetByIDAny(ctx, id)
+		if err != nil {
+			return err
+		}
+		if folder == nil {
+			continue
+		}
+		if len(folder.ParentID) != 0 {
+			queue = append(queue, append([]byte(nil), folder.ParentID...))
+		}
+		if folder.DeletedAt != nil {
+			continue
+		}
+		folder.UpdatedBy = append([]byte(nil), updatedBy...)
+		folder.UpdatedAt = now
+		if err := s.folderRepo.Update(ctx, folder); err != nil {
+			return err
+		}
+	}
+	return nil
+}
diff --git a/internal/service/file_manager_service_test.go b/internal/service/file_manager_service_test.go
new file mode 100644
index 0000000..ea72ccf
--- /dev/null
+++ b/internal/service/file_manager_service_test.go
@@ -0,0 +1,2620 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/queue"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type fileManagerFolderRepoMock struct {
+	createCalled            bool
+	updateCalled            bool
+	updateCalls             int
+	moveSubtreeCalled       bool
+	deleteCalled            bool
+	restoreCalled           bool
+	purgeCalled             bool
+	getByIDCalled           bool
+	getByIDAnyCalled        bool
+	getByParentNameCalled   bool
+	listByParentCalled      bool
+	listByParentCalls       int
+	listTrashCalled         bool
+	listTrashByParentCalled bool
+
+	lastCreate                *filemanager.Folder
+	lastUpdate                *filemanager.Folder
+	updateIDs                 [][]byte
+	lastMoveSubtreeID         []byte
+	lastMoveTargetParentID    []byte
+	lastMoveTargetName        string
+	lastMoveTargetNameNorm    string
+	lastMoveUpdatedBy         []byte
+	lastDeleteID              []byte
+	lastDeleteBy              []byte
+	lastDeletePurgeAt         *time.Time
+	lastRestoreID             []byte
+	lastRestoreBy             []byte
+	lastPurgeID               []byte
+	lastGetByID               []byte
+	lastGetByIDAny            []byte
+	lastGetParentID           []byte
+	lastGetNameNormalized     string
+	lastListParentID          []byte
+	lastListSort              string
+	lastListLimit             int
+	lastListOffset            int
+	lastListTrashParentID     []byte
+	lastListTrashSortGlobal   string
+	lastListTrashLimitGlobal  int
+	lastListTrashOffsetGlobal int
+	lastListTrashSort         string
+	lastListTrashLimit        int
+	lastListTrashOffset       int
+	getByIDResult             *filemanager.Folder
+	getByIDAnyResult          *filemanager.Folder
+	getByParentNameResult     *filemanager.Folder
+	listByParentResult        []filemanager.Folder
+	listByParentTotal         int64
+	listTrashByParentResult   []filemanager.Folder
+	listTrashResult           []filemanager.Folder
+	listTrashByParentTotal    int64
+	listTrashTotal            int64
+	moveSubtreeResult         *filemanager.Folder
+	createErr                 error
+	updateErr                 error
+	moveSubtreeErr            error
+	deleteErr                 error
+	restoreErr                error
+	purgeErr                  error
+	getByIDErr                error
+	getByIDAnyErr             error
+	getByParentNameErr        error
+	listByParentErr           error
+	listTrashByParentErr      error
+	listTrashErr              error
+	listByParentFn            func(context.Context, []byte, string, int, int) ([]filemanager.Folder, int64, error)
+}
+
+func (m *fileManagerFolderRepoMock) Create(_ context.Context, row *filemanager.Folder) error {
+	m.createCalled = true
+	m.lastCreate = row
+	return m.createErr
+}
+
+func (m *fileManagerFolderRepoMock) Update(_ context.Context, row *filemanager.Folder) error {
+	m.updateCalled = true
+	m.updateCalls++
+	m.lastUpdate = row
+	if row != nil {
+		m.updateIDs = append(m.updateIDs, append([]byte(nil), row.ID...))
+	}
+	return m.updateErr
+}
+
+func (m *fileManagerFolderRepoMock) MoveSubtree(_ context.Context, id []byte, targetParentID []byte, targetName string, targetNameNormalized string, updatedBy []byte) (*filemanager.Folder, error) {
+	m.moveSubtreeCalled = true
+	m.lastMoveSubtreeID = id
+	m.lastMoveTargetParentID = targetParentID
+	m.lastMoveTargetName = targetName
+	m.lastMoveTargetNameNorm = targetNameNormalized
+	m.lastMoveUpdatedBy = updatedBy
+	return m.moveSubtreeResult, m.moveSubtreeErr
+}
+
+func (m *fileManagerFolderRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	m.lastDeletePurgeAt = purgeAt
+	return m.deleteErr
+}
+
+func (m *fileManagerFolderRepoMock) Restore(_ context.Context, id []byte, restoredBy []byte) error {
+	m.restoreCalled = true
+	m.lastRestoreID = id
+	m.lastRestoreBy = restoredBy
+	return m.restoreErr
+}
+
+func (m *fileManagerFolderRepoMock) Purge(_ context.Context, id []byte) error {
+	m.purgeCalled = true
+	m.lastPurgeID = id
+	return m.purgeErr
+}
+func (m *fileManagerFolderRepoMock) SearchByName(context.Context, string, string, int, int) ([]filemanager.Folder, int64, error) {
+	return nil, 0, nil
+}
+
+func (m *fileManagerFolderRepoMock) GetByID(_ context.Context, id []byte) (*filemanager.Folder, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *fileManagerFolderRepoMock) GetByIDAny(_ context.Context, id []byte) (*filemanager.Folder, error) {
+	m.getByIDAnyCalled = true
+	m.lastGetByIDAny = id
+	return m.getByIDAnyResult, m.getByIDAnyErr
+}
+
+func (m *fileManagerFolderRepoMock) GetByParentAndName(_ context.Context, parentID []byte, nameNormalized string) (*filemanager.Folder, error) {
+	m.getByParentNameCalled = true
+	m.lastGetParentID = parentID
+	m.lastGetNameNormalized = nameNormalized
+	return m.getByParentNameResult, m.getByParentNameErr
+}
+
+func (m *fileManagerFolderRepoMock) ListByParent(ctx context.Context, parentID []byte, sort string, limit, offset int) ([]filemanager.Folder, int64, error) {
+	m.listByParentCalled = true
+	m.listByParentCalls++
+	m.lastListParentID = parentID
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	if m.listByParentFn != nil {
+		return m.listByParentFn(ctx, parentID, sort, limit, offset)
+	}
+	return m.listByParentResult, m.listByParentTotal, m.listByParentErr
+}
+
+func (m *fileManagerFolderRepoMock) ListTrashByParent(_ context.Context, parentID []byte, sort string, limit, offset int) ([]filemanager.Folder, int64, error) {
+	m.listTrashByParentCalled = true
+	m.lastListTrashParentID = parentID
+	m.lastListTrashSort = sort
+	m.lastListTrashLimit = limit
+	m.lastListTrashOffset = offset
+	return m.listTrashByParentResult, m.listTrashByParentTotal, m.listTrashByParentErr
+}
+
+func (m *fileManagerFolderRepoMock) ListTrash(_ context.Context, sort string, limit, offset int) ([]filemanager.Folder, int64, error) {
+	m.listTrashCalled = true
+	m.lastListTrashSortGlobal = sort
+	m.lastListTrashLimitGlobal = limit
+	m.lastListTrashOffsetGlobal = offset
+	return m.listTrashResult, m.listTrashTotal, m.listTrashErr
+}
+
+type fileManagerFileRepoMock struct {
+	createCalled                bool
+	updateCalled                bool
+	transitionStatusCalled      bool
+	transitionStatusCalls       int
+	withTransactionCalled       bool
+	finalizeCalled              bool
+	deleteCalled                bool
+	restoreCalled               bool
+	purgeCalled                 bool
+	getByIDCalled               bool
+	getByIDAnyCalled            bool
+	getByObjectKeyCalled        bool
+	getByFolderNameCalled       bool
+	getByTemplateTakeoverCalled bool
+	listByFolderCalled          bool
+	listTrashByFolderCalled     bool
+	updateLifecycleCalled       bool
+	isFileReferencedCalled      bool
+	listByLifecycleCalled       bool
+
+	lastCreate               *filemanager.File
+	lastUpdate               *filemanager.File
+	lastTransitionStatus     filemanager.FileStatusTransitionParams
+	lastFinalize             filemanager.FileFinalizeParams
+	lastDeleteID             []byte
+	lastDeleteBy             []byte
+	lastDeletePurgeAt        *time.Time
+	lastRestoreID            []byte
+	lastRestoreBy            []byte
+	lastPurgeID              []byte
+	lastGetByID              []byte
+	lastGetByIDAny           []byte
+	lastGetByObjectKey       string
+	lastGetFolderID          []byte
+	lastGetNameNormalized    string
+	lastListFolderID         []byte
+	lastListSort             string
+	lastListLimit            int
+	lastListOffset           int
+	lastTrashListFolderID    []byte
+	lastTrashListSort        string
+	lastTrashListLimit       int
+	lastTrashListOffset      int
+	getByIDResult            *filemanager.File
+	getByIDAnyResult         *filemanager.File
+	getByObjectKeyResult     *filemanager.File
+	getByFolderNameResult    *filemanager.File
+	listByFolderResult       []filemanager.File
+	listByFolderTotal        int64
+	listTrashByFolderResult  []filemanager.File
+	listTrashByFolderTotal   int64
+	listByLifecycleResult    []filemanager.File
+	outboxMessages           []*filemanager.FileProcessingOutboxMessage
+	realtimeEvents           []filemanager.FileStatusRealtimeEventInput
+	createErr                error
+	updateErr                error
+	transitionStatusErr      error
+	withTransactionErr       error
+	outboxErr                error
+	realtimeEventErr         error
+	finalizeErr              error
+	deleteErr                error
+	restoreErr               error
+	purgeErr                 error
+	getByIDErr               error
+	getByIDAnyErr            error
+	getByObjectKeyErr        error
+	getByFolderNameErr       error
+	getByTemplateTakeoverErr error
+	listByFolderErr          error
+	listTrashByFolderErr     error
+	updateLifecycleErr       error
+	isFileReferencedErr      error
+	listByLifecycleErr       error
+	isFileReferencedResult   bool
+
+	createFn                func(context.Context, *filemanager.File) error
+	updateFn                func(context.Context, *filemanager.File) error
+	transitionStatusFn      func(context.Context, filemanager.FileStatusTransitionParams) error
+	finalizeFn              func(context.Context, filemanager.FileFinalizeParams) error
+	getByIDFn               func(context.Context, []byte) (*filemanager.File, error)
+	getByFolderNameFn       func(context.Context, []byte, string) (*filemanager.File, error)
+	getByTemplateTakeoverFn func(context.Context, []byte, []byte) (*filemanager.File, error)
+	listByLifecycleFn       func(context.Context, filemanager.FileLifecycleListFilter) ([]filemanager.File, error)
+	isReferencedFn          func(context.Context, []byte) (bool, error)
+	uploadIntentByID        map[string]*filemanager.FileUploadIntent
+}
+
+func (m *fileManagerFileRepoMock) WithTransaction(ctx context.Context, fn func(repo filemanager.FileRepository, outbox filemanager.FileProcessingOutboxWriter) error) error {
+	m.withTransactionCalled = true
+	if m.withTransactionErr != nil {
+		return m.withTransactionErr
+	}
+	if fn == nil {
+		return nil
+	}
+	return fn(m, m)
+}
+
+func (m *fileManagerFileRepoMock) CreateFileProcessingOutboxMessage(_ context.Context, message *filemanager.FileProcessingOutboxMessage) error {
+	if m.outboxErr != nil {
+		return m.outboxErr
+	}
+	if message == nil {
+		return errors.New("nil outbox message")
+	}
+	cp := *message
+	cp.ID = append([]byte(nil), message.ID...)
+	cp.Body = append([]byte(nil), message.Body...)
+	cp.Attributes = append([]byte(nil), message.Attributes...)
+	m.outboxMessages = append(m.outboxMessages, &cp)
+	return nil
+}
+
+func (m *fileManagerFileRepoMock) CreateFileStatusRealtimeEvent(_ context.Context, input filemanager.FileStatusRealtimeEventInput) error {
+	if m.realtimeEventErr != nil {
+		return m.realtimeEventErr
+	}
+	cp := input
+	cp.FileID = append([]byte(nil), input.FileID...)
+	cp.UserID = append([]byte(nil), input.UserID...)
+	m.realtimeEvents = append(m.realtimeEvents, cp)
+	return nil
+}
+
+func (m *fileManagerFileRepoMock) Create(ctx context.Context, row *filemanager.File) error {
+	m.createCalled = true
+	if row != nil && len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	m.lastCreate = row
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return m.createErr
+}
+
+func (m *fileManagerFileRepoMock) Update(ctx context.Context, row *filemanager.File) error {
+	m.updateCalled = true
+	m.lastUpdate = row
+	if m.updateFn != nil {
+		return m.updateFn(ctx, row)
+	}
+	return m.updateErr
+}
+
+func (m *fileManagerFileRepoMock) TransitionStatus(ctx context.Context, params filemanager.FileStatusTransitionParams) error {
+	m.transitionStatusCalled = true
+	m.transitionStatusCalls++
+	m.lastTransitionStatus = params
+	if m.transitionStatusFn != nil {
+		return m.transitionStatusFn(ctx, params)
+	}
+	return m.transitionStatusErr
+}
+
+func (m *fileManagerFileRepoMock) Finalize(ctx context.Context, params filemanager.FileFinalizeParams) error {
+	m.finalizeCalled = true
+	m.lastFinalize = params
+	if m.finalizeFn != nil {
+		return m.finalizeFn(ctx, params)
+	}
+	return m.finalizeErr
+}
+
+func (m *fileManagerFileRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	m.lastDeletePurgeAt = purgeAt
+	return m.deleteErr
+}
+
+func (m *fileManagerFileRepoMock) Restore(_ context.Context, id []byte, restoredBy []byte) error {
+	m.restoreCalled = true
+	m.lastRestoreID = id
+	m.lastRestoreBy = restoredBy
+	return m.restoreErr
+}
+
+func (m *fileManagerFileRepoMock) Purge(_ context.Context, id []byte) error {
+	m.purgeCalled = true
+	m.lastPurgeID = id
+	return m.purgeErr
+}
+func (m *fileManagerFileRepoMock) SearchByName(context.Context, string, string, int, int) ([]filemanager.File, int64, error) {
+	return nil, 0, nil
+}
+
+func (m *fileManagerFileRepoMock) GetByID(ctx context.Context, id []byte) (*filemanager.File, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *fileManagerFileRepoMock) GetByIDAny(_ context.Context, id []byte) (*filemanager.File, error) {
+	m.getByIDAnyCalled = true
+	m.lastGetByIDAny = id
+	return m.getByIDAnyResult, m.getByIDAnyErr
+}
+
+func (m *fileManagerFileRepoMock) GetByObjectKey(_ context.Context, objectKey string) (*filemanager.File, error) {
+	m.getByObjectKeyCalled = true
+	m.lastGetByObjectKey = objectKey
+	return m.getByObjectKeyResult, m.getByObjectKeyErr
+}
+
+func (m *fileManagerFileRepoMock) GetByFolderAndName(ctx context.Context, folderID []byte, nameNormalized string) (*filemanager.File, error) {
+	m.getByFolderNameCalled = true
+	m.lastGetFolderID = folderID
+	m.lastGetNameNormalized = nameNormalized
+	if m.getByFolderNameFn != nil {
+		return m.getByFolderNameFn(ctx, folderID, nameNormalized)
+	}
+	return m.getByFolderNameResult, m.getByFolderNameErr
+}
+
+func (m *fileManagerFileRepoMock) GetByTemplateAndTakeover(ctx context.Context, templateUUID, takeoverID []byte) (*filemanager.File, error) {
+	m.getByTemplateTakeoverCalled = true
+	if m.getByTemplateTakeoverFn != nil {
+		return m.getByTemplateTakeoverFn(ctx, templateUUID, takeoverID)
+	}
+	return nil, m.getByTemplateTakeoverErr
+}
+
+func (m *fileManagerFileRepoMock) ListByFolder(_ context.Context, folderID []byte, sort string, limit, offset int) ([]filemanager.File, int64, error) {
+	m.listByFolderCalled = true
+	m.lastListFolderID = folderID
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listByFolderResult, m.listByFolderTotal, m.listByFolderErr
+}
+
+func (m *fileManagerFileRepoMock) ListTrashByFolder(_ context.Context, folderID []byte, sort string, limit, offset int) ([]filemanager.File, int64, error) {
+	m.listTrashByFolderCalled = true
+	m.lastTrashListFolderID = folderID
+	m.lastTrashListSort = sort
+	m.lastTrashListLimit = limit
+	m.lastTrashListOffset = offset
+	return m.listTrashByFolderResult, m.listTrashByFolderTotal, m.listTrashByFolderErr
+}
+
+func (m *fileManagerFileRepoMock) UpdateLifecycle(_ context.Context, params filemanager.FileLifecycleTransitionParams) error {
+	m.updateLifecycleCalled = true
+	if m.updateLifecycleErr != nil {
+		return m.updateLifecycleErr
+	}
+	if m.getByIDAnyResult != nil && string(m.getByIDAnyResult.ID) == string(params.ID) {
+		m.getByIDAnyResult.LifecycleStatus = params.Status
+		m.getByIDAnyResult.AttachedAt = params.AttachedAt
+		if params.ClearOrphanedAt {
+			m.getByIDAnyResult.OrphanedAt = nil
+		} else {
+			m.getByIDAnyResult.OrphanedAt = params.OrphanedAt
+		}
+		m.getByIDAnyResult.LifecycleDeletedAt = params.LifecycleDelete
+	}
+	return nil
+}
+
+func (m *fileManagerFileRepoMock) IsFileReferenced(ctx context.Context, fileID []byte) (bool, error) {
+	m.isFileReferencedCalled = true
+	if m.isReferencedFn != nil {
+		return m.isReferencedFn(ctx, fileID)
+	}
+	if m.isFileReferencedErr != nil {
+		return false, m.isFileReferencedErr
+	}
+	return m.isFileReferencedResult, nil
+}
+
+func (m *fileManagerFileRepoMock) ListFilesByLifecycle(ctx context.Context, filter filemanager.FileLifecycleListFilter) ([]filemanager.File, error) {
+	m.listByLifecycleCalled = true
+	if m.listByLifecycleFn != nil {
+		return m.listByLifecycleFn(ctx, filter)
+	}
+	if m.listByLifecycleErr != nil {
+		return nil, m.listByLifecycleErr
+	}
+	return m.listByLifecycleResult, nil
+}
+
+func (m *fileManagerFileRepoMock) CreateUploadIntent(_ context.Context, row *filemanager.FileUploadIntent) error {
+	if row == nil {
+		return errors.New("upload intent is required")
+	}
+	cp := *row
+	cp.ID = append([]byte(nil), row.ID...)
+	cp.CreatedBy = append([]byte(nil), row.CreatedBy...)
+	cp.UpdatedBy = append([]byte(nil), row.UpdatedBy...)
+	if m.uploadIntentByID == nil {
+		m.uploadIntentByID = map[string]*filemanager.FileUploadIntent{}
+	}
+	m.uploadIntentByID[string(cp.ID)] = &cp
+	return nil
+}
+
+func (m *fileManagerFileRepoMock) GetUploadIntentByID(_ context.Context, id []byte) (*filemanager.FileUploadIntent, error) {
+	if m.uploadIntentByID == nil {
+		return nil, nil
+	}
+	row, ok := m.uploadIntentByID[string(id)]
+	if !ok || row == nil {
+		return nil, nil
+	}
+	cp := *row
+	cp.ID = append([]byte(nil), row.ID...)
+	cp.CreatedBy = append([]byte(nil), row.CreatedBy...)
+	cp.UpdatedBy = append([]byte(nil), row.UpdatedBy...)
+	return &cp, nil
+}
+
+func (m *fileManagerFileRepoMock) GetUploadIntentByIDForUpdate(ctx context.Context, id []byte) (*filemanager.FileUploadIntent, error) {
+	return m.GetUploadIntentByID(ctx, id)
+}
+
+func (m *fileManagerFileRepoMock) MarkUploadIntentCompleted(_ context.Context, params filemanager.FileUploadIntentCompleteParams) error {
+	if m.uploadIntentByID == nil {
+		return nil
+	}
+	row, ok := m.uploadIntentByID[string(params.ID)]
+	if !ok || row == nil {
+		return nil
+	}
+	completedAt := params.CompletedAt
+	row.Status = filemanager.FileUploadIntentStatusCompleted
+	row.CompletedAt = &completedAt
+	row.UpdatedBy = append([]byte(nil), params.UpdatedBy...)
+	return nil
+}
+
+func (m *fileManagerFileRepoMock) MarkUploadIntentExpired(_ context.Context, params filemanager.FileUploadIntentExpireParams) error {
+	if m.uploadIntentByID == nil {
+		return nil
+	}
+	row, ok := m.uploadIntentByID[string(params.ID)]
+	if !ok || row == nil {
+		return nil
+	}
+	row.Status = filemanager.FileUploadIntentStatusExpired
+	row.UpdatedBy = append([]byte(nil), params.UpdatedBy...)
+	return nil
+}
+
+type fileManagerStorageMock struct {
+	putCalls        int
+	deleteCalls     int
+	deletedKeys     []string
+	presignPutCalls int
+	putErrAt        map[int]error
+	lastInput       filemanager.PutObjectInput
+	headMeta        filemanager.ObjectMetadata
+	headErr         error
+	presignPut      filemanager.PresignedPutObject
+	presignErr      error
+	taggingCalls    int
+	lastTags        map[string]string
+	taggingErr      error
+}
+
+type fileProcessingQueueMock struct {
+	enqueueCalled bool
+	lastJob       filemanager.FileProcessingJob
+	enqueueErr    error
+}
+
+type fileUploadIntentRepoMock struct {
+	createCalled            bool
+	getByIDCalled           bool
+	getByIDForUpdateCalled  bool
+	markCompletedCalled     bool
+	markExpiredCalled       bool
+	lastCreate              *filemanager.FileUploadIntent
+	lastGetID               []byte
+	lastGetForUpdateID      []byte
+	lastMarkCompletedParams filemanager.FileUploadIntentCompleteParams
+	lastMarkExpiredParams   filemanager.FileUploadIntentExpireParams
+	createErr               error
+	getByIDErr              error
+	getByIDForUpdateErr     error
+	markCompletedErr        error
+	markExpiredErr          error
+	getByIDResult           *filemanager.FileUploadIntent
+	getByIDForUpdateResult  *filemanager.FileUploadIntent
+	storedByID              map[string]*filemanager.FileUploadIntent
+}
+
+func (m *fileUploadIntentRepoMock) CreateUploadIntent(_ context.Context, row *filemanager.FileUploadIntent) error {
+	m.createCalled = true
+	if row != nil {
+		cp := *row
+		cp.ID = append([]byte(nil), row.ID...)
+		cp.CreatedBy = append([]byte(nil), row.CreatedBy...)
+		cp.UpdatedBy = append([]byte(nil), row.UpdatedBy...)
+		m.lastCreate = &cp
+		if m.storedByID == nil {
+			m.storedByID = map[string]*filemanager.FileUploadIntent{}
+		}
+		m.storedByID[string(cp.ID)] = &cp
+	}
+	return m.createErr
+}
+
+func (m *fileUploadIntentRepoMock) GetUploadIntentByID(_ context.Context, id []byte) (*filemanager.FileUploadIntent, error) {
+	m.getByIDCalled = true
+	m.lastGetID = append([]byte(nil), id...)
+	if m.getByIDErr != nil {
+		return nil, m.getByIDErr
+	}
+	if m.getByIDResult != nil {
+		cp := *m.getByIDResult
+		cp.ID = append([]byte(nil), m.getByIDResult.ID...)
+		return &cp, nil
+	}
+	if m.storedByID != nil {
+		if row, ok := m.storedByID[string(id)]; ok {
+			cp := *row
+			cp.ID = append([]byte(nil), row.ID...)
+			return &cp, nil
+		}
+	}
+	return nil, nil
+}
+
+func (m *fileUploadIntentRepoMock) GetUploadIntentByIDForUpdate(_ context.Context, id []byte) (*filemanager.FileUploadIntent, error) {
+	m.getByIDForUpdateCalled = true
+	m.lastGetForUpdateID = append([]byte(nil), id...)
+	if m.getByIDForUpdateErr != nil {
+		return nil, m.getByIDForUpdateErr
+	}
+	if m.getByIDForUpdateResult != nil {
+		cp := *m.getByIDForUpdateResult
+		cp.ID = append([]byte(nil), m.getByIDForUpdateResult.ID...)
+		return &cp, nil
+	}
+	if m.storedByID != nil {
+		if row, ok := m.storedByID[string(id)]; ok {
+			cp := *row
+			cp.ID = append([]byte(nil), row.ID...)
+			return &cp, nil
+		}
+	}
+	return nil, nil
+}
+
+func (m *fileUploadIntentRepoMock) MarkUploadIntentCompleted(_ context.Context, params filemanager.FileUploadIntentCompleteParams) error {
+	m.markCompletedCalled = true
+	m.lastMarkCompletedParams = params
+	if m.markCompletedErr != nil {
+		return m.markCompletedErr
+	}
+	if m.storedByID != nil {
+		if row, ok := m.storedByID[string(params.ID)]; ok {
+			row.Status = filemanager.FileUploadIntentStatusCompleted
+			completedAt := params.CompletedAt
+			row.CompletedAt = &completedAt
+		}
+	}
+	return nil
+}
+
+func (m *fileUploadIntentRepoMock) MarkUploadIntentExpired(_ context.Context, params filemanager.FileUploadIntentExpireParams) error {
+	m.markExpiredCalled = true
+	m.lastMarkExpiredParams = params
+	if m.markExpiredErr != nil {
+		return m.markExpiredErr
+	}
+	if m.storedByID != nil {
+		if row, ok := m.storedByID[string(params.ID)]; ok {
+			row.Status = filemanager.FileUploadIntentStatusExpired
+		}
+	}
+	return nil
+}
+
+func (m *fileProcessingQueueMock) Enqueue(_ context.Context, job filemanager.FileProcessingJob) error {
+	m.enqueueCalled = true
+	m.lastJob = job
+	return m.enqueueErr
+}
+
+func (m *fileManagerStorageMock) EnsureBucket(_ context.Context) error { return nil }
+
+func (m *fileManagerStorageMock) PutObject(_ context.Context, input filemanager.PutObjectInput) (filemanager.ObjectMetadata, error) {
+	m.putCalls++
+	m.lastInput = input
+	if m.putErrAt != nil {
+		if err, ok := m.putErrAt[m.putCalls]; ok && err != nil {
+			return filemanager.ObjectMetadata{}, err
+		}
+	}
+	return filemanager.ObjectMetadata{
+		Bucket:    "test-bucket",
+		ObjectKey: input.ObjectKey,
+		ETag:      "etag",
+		VersionID: "v1",
+		SizeBytes: input.SizeBytes,
+	}, nil
+}
+
+func (m *fileManagerStorageMock) DeleteObject(_ context.Context, key string) error {
+	m.deleteCalls++
+	m.deletedKeys = append(m.deletedKeys, key)
+	return nil
+}
+
+func (m *fileManagerStorageMock) HeadObject(_ context.Context, objectKey string) (filemanager.ObjectMetadata, error) {
+	if m.headErr != nil {
+		return filemanager.ObjectMetadata{}, m.headErr
+	}
+	if strings.TrimSpace(m.headMeta.ObjectKey) != "" {
+		return m.headMeta, nil
+	}
+	return filemanager.ObjectMetadata{
+		Bucket:    "test-bucket",
+		ObjectKey: objectKey,
+		SizeBytes: m.lastInput.SizeBytes,
+	}, nil
+}
+
+func (m *fileManagerStorageMock) PresignPutObject(_ context.Context, input filemanager.PresignPutObjectInput) (filemanager.PresignedPutObject, error) {
+	m.presignPutCalls++
+	if m.presignErr != nil {
+		return filemanager.PresignedPutObject{}, m.presignErr
+	}
+	if strings.TrimSpace(m.presignPut.URL) != "" {
+		return m.presignPut, nil
+	}
+	return filemanager.PresignedPutObject{
+		Bucket:    "test-bucket",
+		ObjectKey: input.ObjectKey,
+		Method:    "PUT",
+		URL:       "https://example.local/upload",
+		Headers:   map[string]string{"content-type": input.ContentType},
+		ExpiresAt: time.Now().UTC().Add(15 * time.Minute),
+	}, nil
+}
+
+func (m *fileManagerStorageMock) PresignGetObject(_ context.Context, _ string, _ time.Duration) (string, error) {
+	return "https://example.local/presigned", nil
+}
+
+func (m *fileManagerStorageMock) PutObjectTagging(_ context.Context, _ string, tags map[string]string) error {
+	m.taggingCalls++
+	m.lastTags = tags
+	return m.taggingErr
+}
+
+func (m *fileManagerStorageMock) DeleteObjectTaggingKeys(_ context.Context, _ string, _ []string) error {
+	return nil
+}
+
+func TestNewFileManagerService(t *testing.T) {
+	folderRepo := &fileManagerFolderRepoMock{}
+	fileRepo := &fileManagerFileRepoMock{}
+
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+	if svc == nil || svc.folderRepo == nil || svc.fileRepo == nil {
+		t.Fatalf("expected service initialized")
+	}
+}
+
+func TestFileManagerServiceFolderMethods(t *testing.T) {
+	folderRepo := &fileManagerFolderRepoMock{
+		getByIDResult:           &filemanager.Folder{Name: "Folder A"},
+		getByIDAnyResult:        &filemanager.Folder{Name: "Folder Any"},
+		getByParentNameResult:   &filemanager.Folder{Name: "Folder B"},
+		listByParentResult:      []filemanager.Folder{{Name: "Folder A"}},
+		listByParentTotal:       1,
+		listTrashByParentResult: []filemanager.Folder{{Name: "Folder Trash"}},
+		listTrashByParentTotal:  1,
+	}
+	fileRepo := &fileManagerFileRepoMock{}
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+
+	row := &filemanager.Folder{Name: "Create"}
+	if err := svc.CreateFolder(context.Background(), row); err != nil {
+		t.Fatalf("create folder: %v", err)
+	}
+	if !folderRepo.createCalled || folderRepo.lastCreate != row {
+		t.Fatalf("expected CreateFolder forwarded")
+	}
+
+	if err := svc.UpdateFolder(context.Background(), row); err != nil {
+		t.Fatalf("update folder: %v", err)
+	}
+	if !folderRepo.updateCalled || folderRepo.lastUpdate != row {
+		t.Fatalf("expected UpdateFolder forwarded")
+	}
+
+	id := []byte("folder-id")
+	actor := []byte("actor-id")
+	purgeAt := time.Now().UTC().Add(24 * time.Hour)
+	folderRepo.listByParentTotal = 0
+	fileRepo.listByFolderTotal = 0
+	if err := svc.DeleteFolder(context.Background(), id, actor, &purgeAt); err != nil {
+		t.Fatalf("delete folder: %v", err)
+	}
+	if !folderRepo.deleteCalled {
+		t.Fatalf("expected DeleteFolder forwarded")
+	}
+
+	deletedAt := time.Now().UTC()
+	folderRepo.getByIDAnyResult = &filemanager.Folder{
+		ID:        id,
+		Name:      "Folder Any",
+		PathCache: "/Folder Any",
+		DeletedAt: &deletedAt,
+	}
+	folderRepo.getByParentNameResult = nil
+	folderRepo.updateCalled = false
+	if err := svc.RestoreFolder(context.Background(), id, nil, false, actor); err != nil {
+		t.Fatalf("restore folder: %v", err)
+	}
+	if !folderRepo.updateCalled {
+		t.Fatalf("expected RestoreFolder to update folder state")
+	}
+	folderRepo.listByParentTotal = 1
+	fileRepo.listByFolderTotal = 1
+
+	if err := svc.PurgeFolder(context.Background(), id); err != nil {
+		t.Fatalf("purge folder: %v", err)
+	}
+	if !folderRepo.purgeCalled {
+		t.Fatalf("expected PurgeFolder forwarded")
+	}
+
+	gotByID, err := svc.GetFolderByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("get folder by id: %v", err)
+	}
+	if gotByID == nil || gotByID.Name != "Folder A" {
+		t.Fatalf("unexpected folder by id result")
+	}
+
+	gotByIDAny, err := svc.GetFolderByIDAny(context.Background(), id)
+	if err != nil {
+		t.Fatalf("get folder by id any: %v", err)
+	}
+	if gotByIDAny == nil || gotByIDAny.Name != "Folder Any" {
+		t.Fatalf("unexpected folder by id any result")
+	}
+
+	folderRepo.getByParentNameResult = &filemanager.Folder{Name: "Folder B"}
+	gotByName, err := svc.GetFolderByParentAndName(context.Background(), nil, "folder-b")
+	if err != nil {
+		t.Fatalf("get folder by parent/name: %v", err)
+	}
+	if gotByName == nil || gotByName.Name != "Folder B" {
+		t.Fatalf("unexpected folder by parent/name result")
+	}
+
+	rows, total, err := svc.ListFoldersByParent(context.Background(), nil, "-name", 10, 0)
+	if err != nil {
+		t.Fatalf("list folders: %v", err)
+	}
+	if total != 1 || len(rows) != 1 {
+		t.Fatalf("unexpected list folders result")
+	}
+	if folderRepo.lastListSort != "name DESC" {
+		t.Fatalf("expected normalized folder sort, got %q", folderRepo.lastListSort)
+	}
+
+	trashRows, trashTotal, err := svc.ListTrashFoldersByParent(context.Background(), nil, "name", 10, 0)
+	if err != nil {
+		t.Fatalf("list trash folders: %v", err)
+	}
+	if trashTotal != 1 || len(trashRows) != 1 {
+		t.Fatalf("unexpected list trash folders result")
+	}
+	if folderRepo.lastListTrashSort != "name ASC" {
+		t.Fatalf("expected normalized trash folder sort, got %q", folderRepo.lastListTrashSort)
+	}
+
+	folderRepo.createErr = errors.New("create failed")
+	if err := svc.CreateFolder(context.Background(), row); err == nil {
+		t.Fatalf("expected create error")
+	}
+}
+
+func TestFileManagerServiceFileMethods(t *testing.T) {
+	folderID := []byte("folder-id")
+	folderRepo := &fileManagerFolderRepoMock{
+		getByIDAnyResult: &filemanager.Folder{ID: append([]byte(nil), folderID...)},
+	}
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDResult:           &filemanager.File{Name: "File A"},
+		getByIDAnyResult:        &filemanager.File{Name: "File Any", Status: filemanager.FileStatusReady},
+		getByObjectKeyResult:    &filemanager.File{Name: "File B"},
+		getByFolderNameResult:   &filemanager.File{Name: "File C"},
+		listByFolderResult:      []filemanager.File{{Name: "File A"}},
+		listByFolderTotal:       1,
+		listTrashByFolderResult: []filemanager.File{{Name: "File Trash"}},
+		listTrashByFolderTotal:  1,
+	}
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+
+	row := &filemanager.File{Name: "Create.txt", FolderID: append([]byte(nil), folderID...), CreatedBy: []byte("actor-id")}
+	if err := svc.CreateFile(context.Background(), row); err != nil {
+		t.Fatalf("create file: %v", err)
+	}
+	if !fileRepo.createCalled || fileRepo.lastCreate != row {
+		t.Fatalf("expected CreateFile forwarded")
+	}
+	if !folderRepo.updateCalled {
+		t.Fatalf("expected CreateFile to touch parent folder")
+	}
+
+	if err := svc.UpdateFile(context.Background(), row); err != nil {
+		t.Fatalf("update file: %v", err)
+	}
+	if !fileRepo.updateCalled || fileRepo.lastUpdate != row {
+		t.Fatalf("expected UpdateFile forwarded")
+	}
+
+	id := []byte("file-id")
+	actor := []byte("actor-id")
+	purgeAt := time.Now().UTC().Add(24 * time.Hour)
+	if err := svc.DeleteFile(context.Background(), id, actor, &purgeAt); err != nil {
+		t.Fatalf("delete file: %v", err)
+	}
+	if !fileRepo.deleteCalled {
+		t.Fatalf("expected DeleteFile forwarded")
+	}
+
+	fileDeletedAt := time.Now().UTC()
+	fileRepo.getByIDAnyResult = &filemanager.File{
+		ID:        id,
+		Name:      "File Any",
+		FolderID:  []byte("folder-id"),
+		Status:    filemanager.FileStatusTrashed,
+		DeletedAt: &fileDeletedAt,
+	}
+	fileRepo.getByFolderNameResult = nil
+	fileRepo.updateCalled = false
+	folderRepo.getByIDResult = &filemanager.Folder{Name: "Folder A"}
+	if err := svc.RestoreFile(context.Background(), id, nil, false, actor); err != nil {
+		t.Fatalf("restore file: %v", err)
+	}
+	if !fileRepo.updateCalled {
+		t.Fatalf("expected RestoreFile to update file state")
+	}
+
+	if err := svc.PurgeFile(context.Background(), id); err != nil {
+		t.Fatalf("purge file: %v", err)
+	}
+	if !fileRepo.purgeCalled {
+		t.Fatalf("expected PurgeFile forwarded")
+	}
+
+	gotByID, err := svc.GetFileByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("get file by id: %v", err)
+	}
+	if gotByID == nil || gotByID.Name != "File A" {
+		t.Fatalf("unexpected file by id result")
+	}
+
+	gotByIDAny, err := svc.GetFileByIDAny(context.Background(), id)
+	if err != nil {
+		t.Fatalf("get file by id any: %v", err)
+	}
+	if gotByIDAny == nil || gotByIDAny.Name != "File Any" {
+		t.Fatalf("unexpected file by id any result")
+	}
+
+	gotByObjectKey, err := svc.GetFileByObjectKey(context.Background(), "fm/objects/x")
+	if err != nil {
+		t.Fatalf("get file by object key: %v", err)
+	}
+	if gotByObjectKey == nil || gotByObjectKey.Name != "File B" {
+		t.Fatalf("unexpected file by object key result")
+	}
+
+	fileRepo.getByFolderNameResult = &filemanager.File{Name: "File C"}
+	gotByName, err := svc.GetFileByFolderAndName(context.Background(), []byte("folder-id"), "file-c")
+	if err != nil {
+		t.Fatalf("get file by folder/name: %v", err)
+	}
+	if gotByName == nil || gotByName.Name != "File C" {
+		t.Fatalf("unexpected file by folder/name result")
+	}
+
+	rows, total, err := svc.ListFilesByFolder(context.Background(), []byte("folder-id"), "-size_bytes", 10, 0)
+	if err != nil {
+		t.Fatalf("list files: %v", err)
+	}
+	if total != 1 || len(rows) != 1 {
+		t.Fatalf("unexpected list files result")
+	}
+	if fileRepo.lastListSort != "size_bytes DESC" {
+		t.Fatalf("expected normalized file sort, got %q", fileRepo.lastListSort)
+	}
+
+	trashRows, trashTotal, err := svc.ListTrashFilesByFolder(context.Background(), []byte("folder-id"), "-created_at", 10, 0)
+	if err != nil {
+		t.Fatalf("list trash files: %v", err)
+	}
+	if trashTotal != 1 || len(trashRows) != 1 {
+		t.Fatalf("unexpected list trash files result")
+	}
+	if fileRepo.lastTrashListSort != "created_at DESC" {
+		t.Fatalf("expected normalized trash file sort, got %q", fileRepo.lastTrashListSort)
+	}
+
+	fileRepo.createErr = errors.New("create failed")
+	if err := svc.CreateFile(context.Background(), row); err == nil {
+		t.Fatalf("expected create error")
+	}
+}
+
+func TestFileManagerServiceListTrashNodes(t *testing.T) {
+	folderRepo := &fileManagerFolderRepoMock{
+		listTrashResult: []filemanager.Folder{{Name: "Folder Trash"}},
+		listTrashTotal:  1,
+	}
+	fileRepo := &fileManagerFileRepoMock{
+		listTrashByFolderResult: []filemanager.File{{Name: "File Trash"}},
+		listTrashByFolderTotal:  1,
+	}
+
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+	folders, files, err := svc.ListTrashNodes(context.Background())
+	if err != nil {
+		t.Fatalf("list trash nodes: %v", err)
+	}
+	if len(folders) != 1 || len(files) != 1 {
+		t.Fatalf("unexpected trash node counts: folders=%d files=%d", len(folders), len(files))
+	}
+	if !folderRepo.listTrashCalled {
+		t.Fatalf("expected folder ListTrash to be called")
+	}
+	if folderRepo.lastListTrashSortGlobal != "deleted_at DESC" {
+		t.Fatalf("expected folder trash sort deleted_at DESC, got %q", folderRepo.lastListTrashSortGlobal)
+	}
+	if !fileRepo.listTrashByFolderCalled {
+		t.Fatalf("expected file ListTrashByFolder to be called")
+	}
+	if len(fileRepo.lastTrashListFolderID) != 0 {
+		t.Fatalf("expected file trash folder filter to be empty")
+	}
+	if fileRepo.lastTrashListSort != "deleted_at DESC" {
+		t.Fatalf("expected file trash sort deleted_at DESC, got %q", fileRepo.lastTrashListSort)
+	}
+}
+
+func TestFileManagerServiceListNodesByParent_RootIncludesSystemRootChildren(t *testing.T) {
+	rootID := []byte("root-folder-id")
+	folderRepo := &fileManagerFolderRepoMock{
+		getByParentNameResult: &filemanager.Folder{
+			ID:             append([]byte(nil), rootID...),
+			Name:           filemanager.SystemRootFolderName,
+			NameNormalized: filemanager.SystemRootFolderName,
+		},
+		listByParentFn: func(_ context.Context, parentID []byte, _ string, _, _ int) ([]filemanager.Folder, int64, error) {
+			if len(parentID) == 0 {
+				rows := []filemanager.Folder{
+					{ID: append([]byte(nil), rootID...), Name: filemanager.SystemRootFolderName, NameNormalized: filemanager.SystemRootFolderName},
+					{ID: []byte("public-folder-id"), Name: "Public", NameNormalized: "public"},
+				}
+				return rows, int64(len(rows)), nil
+			}
+			if string(parentID) == string(rootID) {
+				rows := []filemanager.Folder{
+					{ID: []byte("aircraft-folder-id"), Name: "aircraft", NameNormalized: "aircraft"},
+				}
+				return rows, int64(len(rows)), nil
+			}
+			return nil, 0, nil
+		},
+	}
+	fileRepo := &fileManagerFileRepoMock{
+		listByFolderResult: []filemanager.File{{ID: []byte("file-1"), Name: "image.jpg"}},
+		listByFolderTotal:  1,
+	}
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+
+	folders, files, err := svc.ListNodesByParent(context.Background(), nil)
+	if err != nil {
+		t.Fatalf("list root nodes: %v", err)
+	}
+	if len(files) != 1 {
+		t.Fatalf("expected 1 file at root, got %d", len(files))
+	}
+	if len(folders) != 2 {
+		t.Fatalf("expected 2 folders (public + aircraft), got %d", len(folders))
+	}
+	if folderRepo.listByParentCalls != 2 {
+		t.Fatalf("expected ListByParent called twice for root listing, got %d", folderRepo.listByParentCalls)
+	}
+	if got := string(fileRepo.lastListFolderID); got != string(rootID) {
+		t.Fatalf("expected root folder id for file list, got %q", got)
+	}
+	if folders[0].Name != "aircraft" || folders[1].Name != "Public" {
+		t.Fatalf("expected root folders sorted and include aircraft/public, got %#v", folders)
+	}
+}
+
+func TestFileManagerServiceUploadFileNodesBulk_Success(t *testing.T) {
+	rootID := []byte("root-folder-id")
+	folderRepo := &fileManagerFolderRepoMock{
+		getByParentNameResult: &filemanager.Folder{
+			ID:             rootID,
+			Name:           filemanager.SystemRootFolderName,
+			NameNormalized: filemanager.SystemRootFolderName,
+		},
+	}
+	fileRepo := &fileManagerFileRepoMock{}
+	storage := &fileManagerStorageMock{}
+	fileQueue := &fileProcessingQueueMock{}
+
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+	svc.SetObjectStorage(storage)
+	svc.SetFileProcessingQueue(fileQueue)
+	svc.SetFileStatusRealtimeEventWriter(fileRepo)
+
+	results := svc.UploadFileNodesBulk(context.Background(), []filemanager.UploadFileParams{
+		{Name: "invoice-1.pdf", ContentType: "application/pdf", SizeBytes: 12, Body: strings.NewReader("file-1")},
+		{Name: "invoice-2.pdf", ContentType: "application/pdf", SizeBytes: 12, Body: strings.NewReader("file-2")},
+	})
+
+	if len(results) != 2 {
+		t.Fatalf("expected 2 results, got %d", len(results))
+	}
+	for i := range results {
+		if results[i].Err != nil {
+			t.Fatalf("expected success at index %d, got error %v", i, results[i].Err)
+		}
+		if results[i].File == nil {
+			t.Fatalf("expected file at index %d", i)
+		}
+		if results[i].File.Status != filemanager.FileStatusUploaded {
+			t.Fatalf("expected uploaded status at index %d, got %s", i, results[i].File.Status)
+		}
+	}
+	if storage.putCalls != 2 {
+		t.Fatalf("expected 2 storage put calls, got %d", storage.putCalls)
+	}
+	if !fileQueue.enqueueCalled {
+		t.Fatalf("expected enqueue called")
+	}
+}
+
+func TestFileManagerServiceUploadFileNodesBulk_PartialFailure(t *testing.T) {
+	rootID := []byte("root-folder-id")
+	folderRepo := &fileManagerFolderRepoMock{
+		getByParentNameResult: &filemanager.Folder{
+			ID:             rootID,
+			Name:           filemanager.SystemRootFolderName,
+			NameNormalized: filemanager.SystemRootFolderName,
+		},
+	}
+	fileRepo := &fileManagerFileRepoMock{}
+	storage := &fileManagerStorageMock{
+		putErrAt: map[int]error{
+			2: errors.New("storage offline"),
+		},
+	}
+	fileQueue := &fileProcessingQueueMock{}
+
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+	svc.SetObjectStorage(storage)
+	svc.SetFileProcessingQueue(fileQueue)
+
+	results := svc.UploadFileNodesBulk(context.Background(), []filemanager.UploadFileParams{
+		{Name: "ok.pdf", ContentType: "application/pdf", SizeBytes: 2, Body: strings.NewReader("ok")},
+		{Name: "fail.pdf", ContentType: "application/pdf", SizeBytes: 4, Body: strings.NewReader("fail")},
+	})
+
+	if len(results) != 2 {
+		t.Fatalf("expected 2 results, got %d", len(results))
+	}
+	if results[0].Err != nil || results[0].File == nil {
+		t.Fatalf("expected first upload success, got err=%v", results[0].Err)
+	}
+	if results[1].Err == nil {
+		t.Fatalf("expected second upload failure")
+	}
+}
+
+func TestFileManagerServiceCreateFileNodesFromUploadBulk_Success(t *testing.T) {
+	files := map[string]*filemanager.File{
+		"upload-1": {
+			ID:             []byte("upload-1"),
+			FolderID:       []byte("root-folder"),
+			Name:           "raw-1.pdf",
+			NameNormalized: "raw-1.pdf",
+			Status:         filemanager.FileStatusValidated,
+			NameSlot:       "tmp-slot-1",
+		},
+		"upload-2": {
+			ID:             []byte("upload-2"),
+			FolderID:       []byte("root-folder"),
+			Name:           "raw-2.pdf",
+			NameNormalized: "raw-2.pdf",
+			Status:         filemanager.FileStatusValidated,
+			NameSlot:       "tmp-slot-2",
+		},
+	}
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+			row := files[string(id)]
+			if row == nil {
+				return nil, nil
+			}
+			cp := *row
+			return &cp, nil
+		},
+		getByFolderNameFn: func(_ context.Context, folderID []byte, nameNormalized string) (*filemanager.File, error) {
+			for _, row := range files {
+				if row.DeletedAt == nil && row.NameSlot == "live" && string(row.FolderID) == string(folderID) && row.NameNormalized == nameNormalized {
+					cp := *row
+					return &cp, nil
+				}
+			}
+			return nil, nil
+		},
+		finalizeFn: func(_ context.Context, params filemanager.FileFinalizeParams) error {
+			row := files[string(params.ID)]
+			if row == nil {
+				return nil
+			}
+			row.FolderID = append([]byte(nil), params.FolderID...)
+			row.Name = params.Name
+			row.NameNormalized = params.NameNormalized
+			row.Extension = params.Extension
+			row.Status = filemanager.FileStatusReady
+			row.NameSlot = "live"
+			return nil
+		},
+	}
+
+	svc := NewFileManagerService(&fileManagerFolderRepoMock{}, fileRepo, nil, FileManagerServiceDependencies{})
+	nameOverride := "final-2.pdf"
+	results := svc.CreateFileNodesFromUploadBulk(context.Background(), []filemanager.CreateFileFromUploadParams{
+		{UploadFileID: []byte("upload-1")},
+		{UploadFileID: []byte("upload-2"), Name: &nameOverride},
+	})
+
+	if len(results) != 2 {
+		t.Fatalf("expected 2 results, got %d", len(results))
+	}
+	for i := range results {
+		if results[i].Err != nil {
+			t.Fatalf("expected success at index %d, got %v", i, results[i].Err)
+		}
+		if results[i].File == nil {
+			t.Fatalf("expected file at index %d", i)
+		}
+		if results[i].File.Status != filemanager.FileStatusReady {
+			t.Fatalf("expected ready status at index %d, got %s", i, results[i].File.Status)
+		}
+	}
+	if files["upload-1"].NameSlot != "live" || files["upload-2"].NameSlot != "live" {
+		t.Fatalf("expected finalized live name slots")
+	}
+}
+
+func TestFileManagerServiceCreateFileNodesFromUploadBulk_PartialFailure(t *testing.T) {
+	files := map[string]*filemanager.File{
+		"upload-1": {
+			ID:             []byte("upload-1"),
+			FolderID:       []byte("root-folder"),
+			Name:           "raw.pdf",
+			NameNormalized: "raw.pdf",
+			Status:         filemanager.FileStatusValidated,
+			NameSlot:       "tmp-slot",
+		},
+	}
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+			row := files[string(id)]
+			if row == nil {
+				return nil, nil
+			}
+			cp := *row
+			return &cp, nil
+		},
+		getByFolderNameFn: func(_ context.Context, folderID []byte, nameNormalized string) (*filemanager.File, error) {
+			for _, row := range files {
+				if row.DeletedAt == nil && row.NameSlot == "live" && string(row.FolderID) == string(folderID) && row.NameNormalized == nameNormalized {
+					cp := *row
+					return &cp, nil
+				}
+			}
+			return nil, nil
+		},
+		finalizeFn: func(_ context.Context, params filemanager.FileFinalizeParams) error {
+			row := files[string(params.ID)]
+			if row == nil {
+				return nil
+			}
+			row.FolderID = append([]byte(nil), params.FolderID...)
+			row.Name = params.Name
+			row.NameNormalized = params.NameNormalized
+			row.Extension = params.Extension
+			row.Status = filemanager.FileStatusReady
+			row.NameSlot = "live"
+			return nil
+		},
+	}
+
+	svc := NewFileManagerService(&fileManagerFolderRepoMock{}, fileRepo, nil, FileManagerServiceDependencies{})
+	results := svc.CreateFileNodesFromUploadBulk(context.Background(), []filemanager.CreateFileFromUploadParams{
+		{UploadFileID: []byte("upload-1")},
+		{UploadFileID: []byte("upload-1")},
+	})
+
+	if len(results) != 2 {
+		t.Fatalf("expected 2 results, got %d", len(results))
+	}
+	if results[0].Err != nil {
+		t.Fatalf("expected first create success, got %v", results[0].Err)
+	}
+	if !errors.Is(results[1].Err, filemanager.ErrFileAlreadyFinalized) {
+		t.Fatalf("expected second create ErrFileAlreadyFinalized, got %v", results[1].Err)
+	}
+}
+
+func TestFileManagerServiceCreateFileNodeFromUpload_RequiresValidatedStatus(t *testing.T) {
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDResult: &filemanager.File{
+			ID:             []byte("upload-1"),
+			FolderID:       []byte("root-folder"),
+			Name:           "raw.pdf",
+			NameNormalized: "raw.pdf",
+			Status:         filemanager.FileStatusUploaded,
+			NameSlot:       "tmp-slot",
+		},
+	}
+	svc := NewFileManagerService(&fileManagerFolderRepoMock{}, fileRepo, nil, FileManagerServiceDependencies{})
+
+	_, err := svc.CreateFileNodeFromUpload(context.Background(), filemanager.CreateFileFromUploadParams{
+		UploadFileID: []byte("upload-1"),
+	})
+	if !errors.Is(err, filemanager.ErrFileNotEligibleForFinalize) {
+		t.Fatalf("expected ErrFileNotEligibleForFinalize, got %v", err)
+	}
+	if fileRepo.finalizeCalled {
+		t.Fatalf("expected finalize not called for non-eligible status")
+	}
+}
+
+func TestFileManagerServiceSingleUploadAndCreateCompatibility(t *testing.T) {
+	rootID := []byte("root-folder-id")
+	files := map[string]*filemanager.File{}
+
+	folderRepo := &fileManagerFolderRepoMock{
+		getByParentNameResult: &filemanager.Folder{
+			ID:             rootID,
+			Name:           filemanager.SystemRootFolderName,
+			NameNormalized: filemanager.SystemRootFolderName,
+		},
+	}
+	fileRepo := &fileManagerFileRepoMock{
+		createFn: func(_ context.Context, row *filemanager.File) error {
+			cp := *row
+			files[string(row.ID)] = &cp
+			return nil
+		},
+		getByIDFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+			row := files[string(id)]
+			if row == nil {
+				return nil, nil
+			}
+			cp := *row
+			return &cp, nil
+		},
+		getByFolderNameFn: func(_ context.Context, folderID []byte, nameNormalized string) (*filemanager.File, error) {
+			for _, row := range files {
+				if row.DeletedAt == nil && row.NameSlot == "live" && string(row.FolderID) == string(folderID) && row.NameNormalized == nameNormalized {
+					cp := *row
+					return &cp, nil
+				}
+			}
+			return nil, nil
+		},
+		finalizeFn: func(_ context.Context, params filemanager.FileFinalizeParams) error {
+			row := files[string(params.ID)]
+			if row == nil {
+				return nil
+			}
+			row.FolderID = append([]byte(nil), params.FolderID...)
+			row.Name = params.Name
+			row.NameNormalized = params.NameNormalized
+			row.Extension = params.Extension
+			row.Status = filemanager.FileStatusReady
+			row.NameSlot = "live"
+			return nil
+		},
+	}
+	storage := &fileManagerStorageMock{}
+	fileQueue := &fileProcessingQueueMock{}
+	actorID := uuidv7.MustBytes()
+
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+	svc.SetObjectStorage(storage)
+	svc.SetFileProcessingQueue(fileQueue)
+	svc.SetFileStatusRealtimeEventWriter(fileRepo)
+
+	uploaded, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+		Name:        "logo.png",
+		ContentType: "image/png",
+		SizeBytes:   8,
+		Body:        strings.NewReader("png-data"),
+		ActorID:     actorID,
+	})
+	if err != nil {
+		t.Fatalf("upload single failed: %v", err)
+	}
+	if uploaded == nil || uploaded.Status != filemanager.FileStatusUploaded {
+		t.Fatalf("expected uploaded status row")
+	}
+
+	// Simulate asynchronous file worker validation before finalize/create.
+	stored := files[string(uploaded.ID)]
+	if stored == nil {
+		t.Fatalf("expected uploaded row persisted")
+	}
+	stored.Status = filemanager.FileStatusValidated
+
+	finalName := "logo-final.png"
+	created, err := svc.CreateFileNodeFromUpload(context.Background(), filemanager.CreateFileFromUploadParams{
+		UploadFileID: uploaded.ID,
+		Name:         &finalName,
+		ActorID:      actorID,
+	})
+	if err != nil {
+		t.Fatalf("create from upload failed: %v", err)
+	}
+	if created == nil || created.Status != filemanager.FileStatusReady {
+		t.Fatalf("expected ready created row")
+	}
+	if created.Name != finalName {
+		t.Fatalf("expected final name %q, got %q", finalName, created.Name)
+	}
+	if len(fileRepo.realtimeEvents) != 2 {
+		t.Fatalf("expected 2 realtime events (uploaded + ready), got %d", len(fileRepo.realtimeEvents))
+	}
+	if got := filemanager.NormalizeFileStatus(fileRepo.realtimeEvents[0].Status); got != filemanager.FileStatusUploaded {
+		t.Fatalf("expected first realtime status uploaded, got %s", got)
+	}
+	if got := filemanager.NormalizeFileStatus(fileRepo.realtimeEvents[1].Status); got != filemanager.FileStatusReady {
+		t.Fatalf("expected second realtime status ready, got %s", got)
+	}
+}
+
+func TestFileManagerServiceUploadFileNode_QueuePublishFailureMarksFailed(t *testing.T) {
+	rootID := []byte("root-folder-id")
+	folderRepo := &fileManagerFolderRepoMock{
+		getByParentNameResult: &filemanager.Folder{
+			ID:             rootID,
+			Name:           filemanager.SystemRootFolderName,
+			NameNormalized: filemanager.SystemRootFolderName,
+		},
+	}
+	fileRepo := &fileManagerFileRepoMock{}
+	storage := &fileManagerStorageMock{}
+	fileQueue := &fileProcessingQueueMock{
+		enqueueErr: errors.New("sqs unavailable"),
+	}
+	actorID := uuidv7.MustBytes()
+
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+	svc.SetObjectStorage(storage)
+	svc.SetFileProcessingQueue(fileQueue)
+	svc.SetFileStatusRealtimeEventWriter(fileRepo)
+
+	uploaded, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+		Name:        "draft.pdf",
+		ContentType: "application/pdf",
+		SizeBytes:   16,
+		Body:        strings.NewReader("pdf"),
+		ActorID:     actorID,
+	})
+	if err == nil {
+		t.Fatalf("expected upload error when enqueue fails")
+	}
+	if uploaded != nil {
+		t.Fatalf("expected nil uploaded row on enqueue failure")
+	}
+	if storage.putCalls != 1 {
+		t.Fatalf("expected storage put called once")
+	}
+	if !fileQueue.enqueueCalled {
+		t.Fatalf("expected queue enqueue called")
+	}
+	if !fileRepo.transitionStatusCalled {
+		t.Fatalf("expected transition status called to mark failed")
+	}
+	if filemanager.NormalizeFileStatus(fileRepo.lastTransitionStatus.ExpectedFrom) != filemanager.FileStatusUploaded {
+		t.Fatalf("expected transition from uploaded, got %q", fileRepo.lastTransitionStatus.ExpectedFrom)
+	}
+	if filemanager.NormalizeFileStatus(fileRepo.lastTransitionStatus.To) != filemanager.FileStatusFailed {
+		t.Fatalf("expected transition to failed, got %q", fileRepo.lastTransitionStatus.To)
+	}
+	if len(fileRepo.realtimeEvents) < 2 {
+		t.Fatalf("expected realtime events for uploaded + failed, got %d", len(fileRepo.realtimeEvents))
+	}
+	last := fileRepo.realtimeEvents[len(fileRepo.realtimeEvents)-1]
+	if got := filemanager.NormalizeFileStatus(last.Status); got != filemanager.FileStatusFailed {
+		t.Fatalf("expected last realtime status failed, got %s", got)
+	}
+}
+
+func TestFileManagerServiceUploadFileNode_OutboxDurablePath(t *testing.T) {
+	rootID := []byte("root-folder-id")
+	folderRepo := &fileManagerFolderRepoMock{
+		getByParentNameResult: &filemanager.Folder{
+			ID:             rootID,
+			Name:           filemanager.SystemRootFolderName,
+			NameNormalized: filemanager.SystemRootFolderName,
+		},
+	}
+	fileRepo := &fileManagerFileRepoMock{}
+	storage := &fileManagerStorageMock{}
+
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+	svc.SetObjectStorage(storage)
+	svc.SetFileProcessingOutbox(fileRepo, queue.NewFileProcessingJSONSerializer("v1", queue.QueueTypeStandard, ""))
+
+	uploaded, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+		Name:        "draft.pdf",
+		ContentType: "application/pdf",
+		SizeBytes:   16,
+		Body:        strings.NewReader("pdf"),
+	})
+	if err != nil {
+		t.Fatalf("expected upload success, got %v", err)
+	}
+	if uploaded == nil {
+		t.Fatalf("expected uploaded row")
+	}
+	if uploaded.Status != filemanager.FileStatusUploaded {
+		t.Fatalf("expected status uploaded, got %s", uploaded.Status)
+	}
+	if !fileRepo.withTransactionCalled {
+		t.Fatalf("expected transaction path to be used")
+	}
+	if len(fileRepo.outboxMessages) != 1 {
+		t.Fatalf("expected one outbox message, got %d", len(fileRepo.outboxMessages))
+	}
+	if fileRepo.transitionStatusCalled {
+		t.Fatalf("expected no failed transition on successful outbox path")
+	}
+	if storage.deleteCalls != 0 {
+		t.Fatalf("expected no storage cleanup on successful upload")
+	}
+}
+
+func TestFileManagerServiceUploadFileNode_OutboxFailureRollsBackAndCleansStorage(t *testing.T) {
+	rootID := []byte("root-folder-id")
+	folderRepo := &fileManagerFolderRepoMock{
+		getByParentNameResult: &filemanager.Folder{
+			ID:             rootID,
+			Name:           filemanager.SystemRootFolderName,
+			NameNormalized: filemanager.SystemRootFolderName,
+		},
+	}
+	fileRepo := &fileManagerFileRepoMock{
+		outboxErr: errors.New("outbox write failed"),
+	}
+	storage := &fileManagerStorageMock{}
+
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+	svc.SetObjectStorage(storage)
+	svc.SetFileProcessingOutbox(fileRepo, queue.NewFileProcessingJSONSerializer("v1", queue.QueueTypeStandard, ""))
+
+	uploaded, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+		Name:        "draft.pdf",
+		ContentType: "application/pdf",
+		SizeBytes:   16,
+		Body:        strings.NewReader("pdf"),
+	})
+	if err == nil {
+		t.Fatalf("expected upload error when outbox persist fails")
+	}
+	if uploaded != nil {
+		t.Fatalf("expected nil uploaded row on outbox failure")
+	}
+	if !fileRepo.withTransactionCalled {
+		t.Fatalf("expected transaction path to be used")
+	}
+	if storage.putCalls != 1 {
+		t.Fatalf("expected storage put called once")
+	}
+	if storage.deleteCalls != 1 {
+		t.Fatalf("expected storage cleanup after outbox failure, got %d", storage.deleteCalls)
+	}
+	if fileRepo.transitionStatusCalled {
+		t.Fatalf("expected no transition-to-failed when transactional outbox persistence fails")
+	}
+}
+
+func TestFileManagerServiceUploadFileNode_WithUploadPolicy(t *testing.T) {
+	newUploadService := func(policy filemanager.FileUploadPolicy) (*FileManagerService, *fileManagerStorageMock, *fileManagerFileRepoMock) {
+		rootID := []byte("root-folder-id")
+		folderRepo := &fileManagerFolderRepoMock{
+			getByParentNameResult: &filemanager.Folder{
+				ID:             rootID,
+				Name:           filemanager.SystemRootFolderName,
+				NameNormalized: filemanager.SystemRootFolderName,
+			},
+			getByIDAnyResult: &filemanager.Folder{
+				ID:             rootID,
+				Name:           filemanager.SystemRootFolderName,
+				NameNormalized: filemanager.SystemRootFolderName,
+			},
+		}
+		fileRepo := &fileManagerFileRepoMock{}
+		storage := &fileManagerStorageMock{}
+		svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+		svc.SetObjectStorage(storage)
+		svc.SetUploadPolicy(policy)
+		svc.SetFileProcessingQueue(&fileProcessingQueueMock{})
+		return svc, storage, fileRepo
+	}
+
+	t.Run("upload success when all policy checks pass", func(t *testing.T) {
+		svc, storage, fileRepo := newUploadService(filemanager.FileUploadPolicy{
+			MaxFileSizeBytes:  1024,
+			AllowedMimeTypes:  []string{"image/png"},
+			AllowedExtensions: []string{".png"},
+			AllowEmptyFile:    false,
+			MaxFilenameLength: 128,
+		})
+
+		row, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+			Name:        "Logo.PNG",
+			ContentType: "image/png; charset=utf-8",
+			SizeBytes:   8,
+			Body:        strings.NewReader("png-data"),
+		})
+		if err != nil {
+			t.Fatalf("upload failed: %v", err)
+		}
+		if row == nil {
+			t.Fatalf("expected uploaded row")
+		}
+		if row.Status != filemanager.FileStatusUploaded {
+			t.Fatalf("expected status uploaded, got %s", row.Status)
+		}
+		if storage.putCalls != 1 {
+			t.Fatalf("expected 1 storage put call, got %d", storage.putCalls)
+		}
+		if !fileRepo.createCalled {
+			t.Fatalf("expected db create called")
+		}
+	})
+
+	t.Run("reject file too large", func(t *testing.T) {
+		svc, storage, _ := newUploadService(filemanager.FileUploadPolicy{
+			MaxFileSizeBytes: 128,
+		})
+		_, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+			Name:      "large.bin",
+			SizeBytes: 129,
+			Body:      strings.NewReader("data"),
+		})
+		if !errors.Is(err, filemanager.ErrFileTooLarge) {
+			t.Fatalf("expected ErrFileTooLarge, got %v", err)
+		}
+		if storage.putCalls != 0 {
+			t.Fatalf("expected no storage calls")
+		}
+	})
+
+	t.Run("reject mime type not allowed", func(t *testing.T) {
+		svc, storage, _ := newUploadService(filemanager.FileUploadPolicy{
+			AllowedMimeTypes: []string{"image/png"},
+		})
+		_, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+			Name:        "doc.pdf",
+			ContentType: "application/pdf",
+			SizeBytes:   10,
+			Body:        strings.NewReader("pdf"),
+		})
+		if !errors.Is(err, filemanager.ErrFileMimeTypeNotAllowed) {
+			t.Fatalf("expected ErrFileMimeTypeNotAllowed, got %v", err)
+		}
+		if storage.putCalls != 0 {
+			t.Fatalf("expected no storage calls")
+		}
+	})
+
+	t.Run("reject extension not allowed", func(t *testing.T) {
+		svc, storage, _ := newUploadService(filemanager.FileUploadPolicy{
+			AllowedExtensions: []string{"png"},
+		})
+		_, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+			Name:      "doc.pdf",
+			SizeBytes: 10,
+			Body:      strings.NewReader("pdf"),
+		})
+		if !errors.Is(err, filemanager.ErrFileExtensionNotAllowed) {
+			t.Fatalf("expected ErrFileExtensionNotAllowed, got %v", err)
+		}
+		if storage.putCalls != 0 {
+			t.Fatalf("expected no storage calls")
+		}
+	})
+
+	t.Run("reject empty file when not allowed", func(t *testing.T) {
+		svc, storage, _ := newUploadService(filemanager.FileUploadPolicy{
+			AllowEmptyFile: false,
+		})
+		_, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+			Name:      "empty.txt",
+			SizeBytes: 0,
+			Body:      strings.NewReader(""),
+		})
+		if !errors.Is(err, filemanager.ErrEmptyFileNotAllowed) {
+			t.Fatalf("expected ErrEmptyFileNotAllowed, got %v", err)
+		}
+		if storage.putCalls != 0 {
+			t.Fatalf("expected no storage calls")
+		}
+	})
+
+	t.Run("reject file name too long", func(t *testing.T) {
+		svc, storage, _ := newUploadService(filemanager.FileUploadPolicy{
+			MaxFilenameLength: 8,
+		})
+		_, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+			Name:      "this-name-is-too-long.txt",
+			SizeBytes: 12,
+			Body:      strings.NewReader("payload"),
+		})
+		if !errors.Is(err, filemanager.ErrFileNameTooLong) {
+			t.Fatalf("expected ErrFileNameTooLong, got %v", err)
+		}
+		if storage.putCalls != 0 {
+			t.Fatalf("expected no storage calls")
+		}
+	})
+
+	t.Run("empty allowed-list config allows mime and extension", func(t *testing.T) {
+		svc, storage, _ := newUploadService(filemanager.FileUploadPolicy{
+			MaxFileSizeBytes:  1024,
+			MaxFilenameLength: 255,
+		})
+		_, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+			Name:        "archive.unknownext",
+			ContentType: "application/x-custom",
+			SizeBytes:   11,
+			Body:        strings.NewReader("custom-data"),
+		})
+		if err != nil {
+			t.Fatalf("expected upload allowed for empty allow-list config, got %v", err)
+		}
+		if storage.putCalls != 1 {
+			t.Fatalf("expected storage put called once")
+		}
+	})
+}
+
+func TestFileManagerServiceRequestFileUploadIntent(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		fileRepo := &fileManagerFileRepoMock{}
+		intentRepo := &fileUploadIntentRepoMock{}
+		storage := &fileManagerStorageMock{
+			presignPut: filemanager.PresignedPutObject{
+				Bucket:    "wucher-file-dev",
+				ObjectKey: "files/2026/04/05/object.pdf",
+				Method:    "PUT",
+				URL:       "https://example.local/upload",
+				Headers:   map[string]string{"content-type": "application/pdf"},
+				ExpiresAt: time.Now().UTC().Add(10 * time.Minute),
+			},
+		}
+
+		svc := NewFileManagerService(&fileManagerFolderRepoMock{}, fileRepo, nil, FileManagerServiceDependencies{})
+		svc.SetObjectStorage(storage)
+		svc.SetFileUploadIntentRepository(intentRepo)
+		svc.SetUploadPolicy(filemanager.FileUploadPolicy{
+			MaxFileSizeBytes:  1024 * 1024,
+			AllowedMimeTypes:  []string{"application/pdf"},
+			AllowedExtensions: []string{"pdf"},
+			AllowEmptyFile:    false,
+		})
+
+		grant, err := svc.RequestFileUploadIntent(context.Background(), filemanager.RequestFileUploadIntentParams{
+			Name:        "policy.pdf",
+			ContentType: "application/pdf; charset=utf-8",
+			SizeBytes:   120,
+			ActorID:     uuidv7.MustBytes(),
+		})
+		if err != nil {
+			t.Fatalf("RequestFileUploadIntent() error = %v", err)
+		}
+		if grant == nil {
+			t.Fatalf("expected upload intent grant")
+		}
+		if !intentRepo.createCalled {
+			t.Fatalf("expected upload intent to be persisted")
+		}
+		if storage.presignPutCalls != 1 {
+			t.Fatalf("expected presign put called once, got %d", storage.presignPutCalls)
+		}
+		if intentRepo.lastCreate == nil || intentRepo.lastCreate.Status != filemanager.FileUploadIntentStatusPending {
+			t.Fatalf("expected pending upload intent status")
+		}
+		if grant.Method != "PUT" {
+			t.Fatalf("expected PUT method, got %q", grant.Method)
+		}
+	})
+
+	t.Run("reject invalid policy before presign", func(t *testing.T) {
+		fileRepo := &fileManagerFileRepoMock{}
+		intentRepo := &fileUploadIntentRepoMock{}
+		storage := &fileManagerStorageMock{}
+
+		svc := NewFileManagerService(&fileManagerFolderRepoMock{}, fileRepo, nil, FileManagerServiceDependencies{})
+		svc.SetObjectStorage(storage)
+		svc.SetFileUploadIntentRepository(intentRepo)
+		svc.SetUploadPolicy(filemanager.FileUploadPolicy{
+			MaxFileSizeBytes: 100,
+		})
+
+		grant, err := svc.RequestFileUploadIntent(context.Background(), filemanager.RequestFileUploadIntentParams{
+			Name:        "large.bin",
+			ContentType: "application/octet-stream",
+			SizeBytes:   200,
+			ActorID:     uuidv7.MustBytes(),
+		})
+		if !errors.Is(err, filemanager.ErrFileTooLarge) {
+			t.Fatalf("expected ErrFileTooLarge, got %v", err)
+		}
+		if grant != nil {
+			t.Fatalf("expected nil grant on policy failure")
+		}
+		if storage.presignPutCalls != 0 {
+			t.Fatalf("expected no presign call when policy validation fails")
+		}
+		if intentRepo.createCalled {
+			t.Fatalf("expected no upload intent persistence when policy validation fails")
+		}
+	})
+}
+
+func TestFileManagerServiceCompleteFileUploadIntent(t *testing.T) {
+	newService := func(headMeta filemanager.ObjectMetadata, headErr error) (*FileManagerService, *fileManagerFileRepoMock, *fileManagerStorageMock, []byte) {
+		rootID := uuidv7.MustBytes()
+		intentID := uuidv7.MustBytes()
+		actorID := uuidv7.MustBytes()
+		intent := &filemanager.FileUploadIntent{
+			ID:             intentID,
+			Name:           "evidence.pdf",
+			NameNormalized: "evidence.pdf",
+			Extension:      "pdf",
+			SizeBytes:      42,
+			MimeType:       "application/pdf",
+			Bucket:         "test-bucket",
+			ObjectKey:      "files/2026/04/05/evidence.pdf",
+			Status:         filemanager.FileUploadIntentStatusPending,
+			ExpiresAt:      time.Now().UTC().Add(5 * time.Minute),
+			CreatedBy:      actorID,
+			UpdatedBy:      actorID,
+		}
+
+		folderRepo := &fileManagerFolderRepoMock{
+			getByParentNameResult: &filemanager.Folder{
+				ID:             rootID,
+				Name:           filemanager.SystemRootFolderName,
+				NameNormalized: filemanager.SystemRootFolderName,
+			},
+			getByIDAnyResult: &filemanager.Folder{
+				ID:             rootID,
+				Name:           filemanager.SystemRootFolderName,
+				NameNormalized: filemanager.SystemRootFolderName,
+			},
+		}
+		fileRepo := &fileManagerFileRepoMock{
+			uploadIntentByID: map[string]*filemanager.FileUploadIntent{
+				string(intentID): intent,
+			},
+		}
+		storage := &fileManagerStorageMock{
+			headMeta: headMeta,
+			headErr:  headErr,
+		}
+
+		svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+		svc.SetObjectStorage(storage)
+		svc.SetFileUploadIntentRepository(fileRepo)
+		svc.SetFileProcessingOutbox(fileRepo, queue.NewFileProcessingJSONSerializer("v1", queue.QueueTypeStandard, ""))
+
+		return svc, fileRepo, storage, intentID
+	}
+
+	t.Run("success persists uploaded file and outbox", func(t *testing.T) {
+		svc, fileRepo, _, intentID := newService(filemanager.ObjectMetadata{
+			Bucket:      "test-bucket",
+			ObjectKey:   "files/2026/04/05/evidence.pdf",
+			SizeBytes:   42,
+			ContentType: "application/pdf",
+		}, nil)
+
+		row, err := svc.CompleteFileUploadIntent(context.Background(), filemanager.CompleteFileUploadIntentParams{
+			UploadIntentID: intentID,
+			ActorID:        uuidv7.MustBytes(),
+		})
+		if err != nil {
+			t.Fatalf("CompleteFileUploadIntent() error = %v", err)
+		}
+		if row == nil {
+			t.Fatalf("expected completed file row")
+		}
+		if row.Status != filemanager.FileStatusUploaded {
+			t.Fatalf("expected status uploaded, got %q", row.Status)
+		}
+		if !fileRepo.withTransactionCalled {
+			t.Fatalf("expected transactional durable path")
+		}
+		if !fileRepo.createCalled {
+			t.Fatalf("expected file metadata create call")
+		}
+		if len(fileRepo.outboxMessages) != 1 {
+			t.Fatalf("expected one outbox message, got %d", len(fileRepo.outboxMessages))
+		}
+		intent := fileRepo.uploadIntentByID[string(intentID)]
+		if intent == nil || intent.Status != filemanager.FileUploadIntentStatusCompleted {
+			t.Fatalf("expected upload intent completed")
+		}
+	})
+
+	t.Run("fails when uploaded object is missing", func(t *testing.T) {
+		svc, fileRepo, _, intentID := newService(filemanager.ObjectMetadata{}, filemanager.ErrUploadObjectNotFound)
+		row, err := svc.CompleteFileUploadIntent(context.Background(), filemanager.CompleteFileUploadIntentParams{
+			UploadIntentID: intentID,
+			ActorID:        uuidv7.MustBytes(),
+		})
+		if !errors.Is(err, filemanager.ErrUploadObjectNotFound) {
+			t.Fatalf("expected ErrUploadObjectNotFound, got %v", err)
+		}
+		if row != nil {
+			t.Fatalf("expected nil row when object not found")
+		}
+		if fileRepo.createCalled {
+			t.Fatalf("expected no metadata row create when object verification fails")
+		}
+		if fileRepo.withTransactionCalled {
+			t.Fatalf("expected no transaction when object verification fails")
+		}
+	})
+}
+
+func TestFileManagerServiceCreateFileNodeFromUploadIntent(t *testing.T) {
+	newService := func(headMeta filemanager.ObjectMetadata, headErr error) (*FileManagerService, *fileManagerFolderRepoMock, *fileManagerFileRepoMock, []byte, []byte) {
+		rootID := uuidv7.MustBytes()
+		intentID := uuidv7.MustBytes()
+		actorID := uuidv7.MustBytes()
+		intent := &filemanager.FileUploadIntent{
+			ID:             intentID,
+			Name:           "upload-source.pdf",
+			NameNormalized: "upload-source.pdf",
+			Extension:      "pdf",
+			SizeBytes:      42,
+			MimeType:       "application/pdf",
+			Bucket:         "test-bucket",
+			ObjectKey:      "files/2026/04/05/upload-source.pdf",
+			Status:         filemanager.FileUploadIntentStatusPending,
+			ExpiresAt:      time.Now().UTC().Add(5 * time.Minute),
+			CreatedBy:      actorID,
+			UpdatedBy:      actorID,
+		}
+
+		folderRepo := &fileManagerFolderRepoMock{
+			getByParentNameResult: &filemanager.Folder{
+				ID:             rootID,
+				Name:           filemanager.SystemRootFolderName,
+				NameNormalized: filemanager.SystemRootFolderName,
+			},
+			getByIDAnyResult: &filemanager.Folder{
+				ID:             rootID,
+				Name:           filemanager.SystemRootFolderName,
+				NameNormalized: filemanager.SystemRootFolderName,
+			},
+		}
+		fileRepo := &fileManagerFileRepoMock{
+			uploadIntentByID: map[string]*filemanager.FileUploadIntent{
+				string(intentID): intent,
+			},
+		}
+		stored := &filemanager.File{}
+		fileRepo.getByFolderNameFn = func(_ context.Context, _ []byte, nameNormalized string) (*filemanager.File, error) {
+			if len(stored.ID) == 0 {
+				return nil, nil
+			}
+			if stored.NameNormalized == nameNormalized {
+				cp := *stored
+				return &cp, nil
+			}
+			return nil, nil
+		}
+		fileRepo.createFn = func(_ context.Context, row *filemanager.File) error {
+			if len(row.ID) == 0 {
+				row.ID = uuidv7.MustBytes()
+			}
+			cp := *row
+			cp.ID = append([]byte(nil), row.ID...)
+			cp.FolderID = append([]byte(nil), row.FolderID...)
+			*stored = cp
+			fileRepo.getByIDAnyResult = stored
+			fileRepo.getByIDResult = stored
+			return nil
+		}
+		fileRepo.updateFn = func(_ context.Context, row *filemanager.File) error {
+			cp := *row
+			cp.ID = append([]byte(nil), row.ID...)
+			cp.FolderID = append([]byte(nil), row.FolderID...)
+			*stored = cp
+			fileRepo.getByIDAnyResult = stored
+			fileRepo.getByIDResult = stored
+			return nil
+		}
+
+		storage := &fileManagerStorageMock{
+			headMeta: headMeta,
+			headErr:  headErr,
+		}
+
+		svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+		svc.SetObjectStorage(storage)
+		svc.SetFileUploadIntentRepository(fileRepo)
+		svc.SetFileProcessingOutbox(fileRepo, queue.NewFileProcessingJSONSerializer("v1", queue.QueueTypeStandard, ""))
+
+		return svc, folderRepo, fileRepo, intentID, actorID
+	}
+
+	t.Run("success", func(t *testing.T) {
+		svc, _, fileRepo, intentID, actorID := newService(filemanager.ObjectMetadata{
+			Bucket:      "test-bucket",
+			ObjectKey:   "files/2026/04/05/upload-source.pdf",
+			SizeBytes:   42,
+			ContentType: "application/pdf",
+		}, nil)
+
+		row, err := svc.CreateFileNodeFromUploadIntent(context.Background(), filemanager.CreateFileFromUploadIntentParams{
+			UploadIntentID: intentID,
+			Name:           "policy-final.pdf",
+			ActorID:        actorID,
+			IsTemplate:     true,
+		})
+		if err != nil {
+			t.Fatalf("CreateFileNodeFromUploadIntent() error = %v", err)
+		}
+		if row == nil {
+			t.Fatalf("expected created file row")
+		}
+		if filemanager.NormalizeFileStatus(row.Status) != filemanager.FileStatusUploaded {
+			t.Fatalf("expected uploaded status, got %q", row.Status)
+		}
+		if row.Name != "policy-final.pdf" {
+			t.Fatalf("expected renamed file, got %q", row.Name)
+		}
+		if !row.IsTemplate {
+			t.Fatalf("expected template flag to be persisted")
+		}
+		if !strings.EqualFold(strings.TrimSpace(row.NameSlot), "live") {
+			t.Fatalf("expected live name slot, got %q", row.NameSlot)
+		}
+		if !fileRepo.withTransactionCalled {
+			t.Fatalf("expected durable transaction path")
+		}
+		if len(fileRepo.outboxMessages) != 1 {
+			t.Fatalf("expected outbox message created, got %d", len(fileRepo.outboxMessages))
+		}
+		if !fileRepo.updateCalled {
+			t.Fatalf("expected file metadata move/update call")
+		}
+		intent := fileRepo.uploadIntentByID[string(intentID)]
+		if intent == nil || intent.Status != filemanager.FileUploadIntentStatusCompleted {
+			t.Fatalf("expected upload intent completed")
+		}
+	})
+
+	t.Run("auto rename when target name already exists", func(t *testing.T) {
+		svc, _, fileRepo, intentID, actorID := newService(filemanager.ObjectMetadata{
+			Bucket:      "test-bucket",
+			ObjectKey:   "files/2026/04/05/upload-source.pdf",
+			SizeBytes:   42,
+			ContentType: "application/pdf",
+		}, nil)
+
+		existingID := uuidv7.MustBytes()
+		fileRepo.getByFolderNameFn = func(_ context.Context, _ []byte, nameNormalized string) (*filemanager.File, error) {
+			if nameNormalized == "policy-final.pdf" {
+				return &filemanager.File{
+					ID:             existingID,
+					Name:           "policy-final.pdf",
+					NameNormalized: "policy-final.pdf",
+					NameSlot:       "live",
+				}, nil
+			}
+			return nil, nil
+		}
+
+		row, err := svc.CreateFileNodeFromUploadIntent(context.Background(), filemanager.CreateFileFromUploadIntentParams{
+			UploadIntentID: intentID,
+			Name:           "policy-final.pdf",
+			ActorID:        actorID,
+			IsTemplate:     false,
+		})
+		if err != nil {
+			t.Fatalf("CreateFileNodeFromUploadIntent() error = %v", err)
+		}
+		if row == nil {
+			t.Fatalf("expected created file row")
+		}
+		if row.Name != "policy-final (1).pdf" {
+			t.Fatalf("expected auto renamed file, got %q", row.Name)
+		}
+		if filemanager.NormalizeFileStatus(row.Status) != filemanager.FileStatusUploaded {
+			t.Fatalf("expected uploaded status, got %q", row.Status)
+		}
+		if !strings.EqualFold(strings.TrimSpace(row.NameSlot), "live") {
+			t.Fatalf("expected live name slot, got %q", row.NameSlot)
+		}
+	})
+
+	t.Run("fails when uploaded object is missing", func(t *testing.T) {
+		svc, _, fileRepo, intentID, actorID := newService(filemanager.ObjectMetadata{}, filemanager.ErrUploadObjectNotFound)
+
+		row, err := svc.CreateFileNodeFromUploadIntent(context.Background(), filemanager.CreateFileFromUploadIntentParams{
+			UploadIntentID: intentID,
+			Name:           "policy-final.pdf",
+			ActorID:        actorID,
+		})
+		if !errors.Is(err, filemanager.ErrUploadObjectNotFound) {
+			t.Fatalf("expected ErrUploadObjectNotFound, got %v", err)
+		}
+		if row != nil {
+			t.Fatalf("expected nil row when object not found")
+		}
+		if fileRepo.createCalled {
+			t.Fatalf("expected no file metadata create when object verification fails")
+		}
+		if fileRepo.withTransactionCalled {
+			t.Fatalf("expected no durable transaction when object verification fails")
+		}
+	})
+}
+
+func TestFileManagerServiceCreateFileNodeFromUpload_AutoRenameDuplicate(t *testing.T) {
+	uploadID := []byte("upload-1")
+	targetFolderID := []byte("folder-1")
+	existingID := []byte("existing-1")
+
+	files := map[string]*filemanager.File{
+		string(uploadID): {
+			ID:             append([]byte(nil), uploadID...),
+			FolderID:       append([]byte(nil), targetFolderID...),
+			Name:           "report.pdf",
+			NameNormalized: "report.pdf",
+			Status:         filemanager.FileStatusValidated,
+			NameSlot:       "tmp-slot",
+		},
+		string(existingID): {
+			ID:             append([]byte(nil), existingID...),
+			FolderID:       append([]byte(nil), targetFolderID...),
+			Name:           "report.pdf",
+			NameNormalized: "report.pdf",
+			Status:         filemanager.FileStatusReady,
+			NameSlot:       "live",
+		},
+	}
+
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+			row := files[string(id)]
+			if row == nil {
+				return nil, nil
+			}
+			cp := *row
+			return &cp, nil
+		},
+		getByFolderNameFn: func(_ context.Context, folderID []byte, nameNormalized string) (*filemanager.File, error) {
+			for _, row := range files {
+				if row.DeletedAt != nil || row.NameSlot != "live" {
+					continue
+				}
+				if string(row.FolderID) == string(folderID) && row.NameNormalized == nameNormalized {
+					cp := *row
+					return &cp, nil
+				}
+			}
+			return nil, nil
+		},
+		finalizeFn: func(_ context.Context, params filemanager.FileFinalizeParams) error {
+			row := files[string(params.ID)]
+			if row == nil {
+				return nil
+			}
+			row.FolderID = append([]byte(nil), params.FolderID...)
+			row.Name = params.Name
+			row.NameNormalized = params.NameNormalized
+			row.Extension = params.Extension
+			row.Status = filemanager.FileStatusReady
+			row.NameSlot = "live"
+			return nil
+		},
+	}
+
+	svc := NewFileManagerService(&fileManagerFolderRepoMock{}, fileRepo, nil, FileManagerServiceDependencies{})
+	targetName := "report.pdf"
+	created, err := svc.CreateFileNodeFromUpload(context.Background(), filemanager.CreateFileFromUploadParams{
+		UploadFileID: uploadID,
+		Name:         &targetName,
+		ActorID:      uuidv7.MustBytes(),
+	})
+	if err != nil {
+		t.Fatalf("CreateFileNodeFromUpload() error = %v", err)
+	}
+	if created == nil {
+		t.Fatalf("expected created file")
+	}
+	if created.Name != "report (1).pdf" {
+		t.Fatalf("expected auto renamed file, got %q", created.Name)
+	}
+}
+
+func TestNormalizeFolderSort(t *testing.T) {
+	cases := map[string]string{
+		"name":        "name ASC",
+		"-name":       "name DESC",
+		"depth":       "depth ASC",
+		"-depth":      "depth DESC",
+		"created_at":  "created_at ASC",
+		"-created_at": "created_at DESC",
+		"updated_at":  "updated_at ASC",
+		"-updated_at": "updated_at DESC",
+		"updated_by":  "updated_at ASC",
+		"-updated_by": "updated_at DESC",
+		"unknown":     "name ASC",
+		"":            "name ASC",
+	}
+	for in, want := range cases {
+		if got := normalizeFolderSort(in); got != want {
+			t.Fatalf("normalizeFolderSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestNormalizeFileSort(t *testing.T) {
+	cases := map[string]string{
+		"name":        "name ASC",
+		"-name":       "name DESC",
+		"size_bytes":  "size_bytes ASC",
+		"-size_bytes": "size_bytes DESC",
+		"mime_type":   "mime_type ASC",
+		"-mime_type":  "mime_type DESC",
+		"created_at":  "created_at ASC",
+		"-created_at": "created_at DESC",
+		"updated_at":  "updated_at ASC",
+		"-updated_at": "updated_at DESC",
+		"updated_by":  "updated_at ASC",
+		"-updated_by": "updated_at DESC",
+		"unknown":     "name ASC",
+		"":            "name ASC",
+	}
+	for in, want := range cases {
+		if got := normalizeFileSort(in); got != want {
+			t.Fatalf("normalizeFileSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestNormalizeAttachmentSort(t *testing.T) {
+	cases := map[string]string{
+		"sort_order":  "sort_order ASC, created_at DESC",
+		"-sort_order": "sort_order DESC, created_at DESC",
+		"created_at":  "created_at ASC",
+		"-created_at": "created_at DESC",
+		"updated_at":  "updated_at ASC",
+		"-updated_at": "updated_at DESC",
+		"updated_by":  "updated_at ASC",
+		"-updated_by": "updated_at DESC",
+		"unknown":     "sort_order ASC, created_at DESC",
+		"":            "sort_order ASC, created_at DESC",
+	}
+	for in, want := range cases {
+		if got := normalizeAttachmentSort(in); got != want {
+			t.Fatalf("normalizeAttachmentSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestFileManagerServiceDeleteFile_EmitsTrashedRealtimeEvent(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	actorID := uuidv7.MustBytes()
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDAnyResult: &filemanager.File{
+			ID:        append([]byte(nil), fileID...),
+			Name:      "logo.jpg",
+			FolderID:  uuidv7.MustBytes(),
+			Status:    filemanager.FileStatusUploaded,
+			CreatedBy: append([]byte(nil), actorID...),
+		},
+	}
+
+	svc := NewFileManagerService(&fileManagerFolderRepoMock{}, fileRepo, nil, FileManagerServiceDependencies{})
+	svc.SetFileStatusRealtimeEventWriter(fileRepo)
+
+	if err := svc.DeleteFile(context.Background(), fileID, actorID, nil); err != nil {
+		t.Fatalf("delete file: %v", err)
+	}
+	if len(fileRepo.realtimeEvents) != 1 {
+		t.Fatalf("expected 1 realtime event, got %d", len(fileRepo.realtimeEvents))
+	}
+	event := fileRepo.realtimeEvents[0]
+	if got := filemanager.NormalizeFileStatus(event.Status); got != filemanager.FileStatusTrashed {
+		t.Fatalf("expected trashed realtime status, got %s", got)
+	}
+	if string(event.FileID) != string(fileID) {
+		t.Fatalf("expected realtime event file id to match deleted file")
+	}
+	if string(event.UserID) != string(actorID) {
+		t.Fatalf("expected realtime event user id to match actor")
+	}
+}
+
+func TestFileManagerServiceRestoreFile_EmitsReadyRealtimeEvent(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	folderID := uuidv7.MustBytes()
+	actorID := uuidv7.MustBytes()
+	deletedAt := time.Now().UTC().Add(-time.Minute)
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDAnyResult: &filemanager.File{
+			ID:             append([]byte(nil), fileID...),
+			Name:           "logo.jpg",
+			NameNormalized: "logo.jpg",
+			FolderID:       append([]byte(nil), folderID...),
+			Status:         filemanager.FileStatusTrashed,
+			DeletedAt:      &deletedAt,
+			CreatedBy:      append([]byte(nil), actorID...),
+		},
+	}
+	folderRepo := &fileManagerFolderRepoMock{
+		getByIDResult: &filemanager.Folder{ID: append([]byte(nil), folderID...), Name: "Assets"},
+	}
+
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+	svc.SetFileStatusRealtimeEventWriter(fileRepo)
+
+	if err := svc.RestoreFile(context.Background(), fileID, nil, false, actorID); err != nil {
+		t.Fatalf("restore file: %v", err)
+	}
+	if len(fileRepo.realtimeEvents) != 1 {
+		t.Fatalf("expected 1 realtime event, got %d", len(fileRepo.realtimeEvents))
+	}
+	event := fileRepo.realtimeEvents[0]
+	if got := filemanager.NormalizeFileStatus(event.Status); got != filemanager.FileStatusReady {
+		t.Fatalf("expected ready realtime status, got %s", got)
+	}
+	if string(event.FileID) != string(fileID) {
+		t.Fatalf("expected realtime event file id to match restored file")
+	}
+	if string(event.UserID) != string(actorID) {
+		t.Fatalf("expected realtime event user id to match actor")
+	}
+}
+
+func TestFileManagerServiceDeleteFile_TouchesParentFolderUpdatedAt(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	folderID := uuidv7.MustBytes()
+	actorID := uuidv7.MustBytes()
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDAnyResult: &filemanager.File{
+			ID:       append([]byte(nil), fileID...),
+			FolderID: append([]byte(nil), folderID...),
+			Status:   filemanager.FileStatusReady,
+		},
+	}
+	folderRepo := &fileManagerFolderRepoMock{
+		getByIDAnyResult: &filemanager.Folder{
+			ID: append([]byte(nil), folderID...),
+		},
+	}
+
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+	if err := svc.DeleteFile(context.Background(), fileID, actorID, nil); err != nil {
+		t.Fatalf("delete file: %v", err)
+	}
+	if !folderRepo.updateCalled {
+		t.Fatalf("expected parent folder to be touched")
+	}
+	if folderRepo.lastUpdate == nil || folderRepo.lastUpdate.UpdatedAt.IsZero() {
+		t.Fatalf("expected folder updated_at to be set")
+	}
+	if string(folderRepo.lastUpdate.UpdatedBy) != string(actorID) {
+		t.Fatalf("expected folder updated_by to match actor")
+	}
+}
+
+func TestFileManagerServiceMoveFileNode_TouchesSourceAndTargetFolders(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	sourceFolderID := uuidv7.MustBytes()
+	targetFolderID := uuidv7.MustBytes()
+	actorID := uuidv7.MustBytes()
+
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDAnyResult: &filemanager.File{
+			ID:             append([]byte(nil), fileID...),
+			FolderID:       append([]byte(nil), sourceFolderID...),
+			Name:           "doc.pdf",
+			NameNormalized: "doc.pdf",
+		},
+		getByIDResult: &filemanager.File{
+			ID:             append([]byte(nil), fileID...),
+			FolderID:       append([]byte(nil), targetFolderID...),
+			Name:           "doc.pdf",
+			NameNormalized: "doc.pdf",
+		},
+	}
+	folderRepo := &fileManagerFolderRepoMock{
+		getByIDAnyResult: &filemanager.Folder{
+			ID: uuidv7.MustBytes(),
+		},
+	}
+
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{})
+	_, err := svc.MoveFileNode(context.Background(), fileID, filemanager.MoveFileParams{
+		FolderID:       targetFolderID,
+		FolderProvided: true,
+		ActorID:        actorID,
+	})
+	if err != nil {
+		t.Fatalf("move file: %v", err)
+	}
+	if folderRepo.updateCalls != 2 {
+		t.Fatalf("expected both source and target folders touched, got %d updates", folderRepo.updateCalls)
+	}
+}
+
+func TestFileManagerServiceUploadFileNode_SetsTempLifecycleAndTag(t *testing.T) {
+	rootID := uuidv7.MustBytes()
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDResult: &filemanager.File{
+			ID:             uuidv7.MustBytes(),
+			FolderID:       rootID,
+			Name:           "proof.pdf",
+			NameNormalized: "proof.pdf",
+			ObjectKey:      "files/2026/04/27/proof.pdf",
+			Status:         filemanager.FileStatusUploaded,
+		},
+	}
+	folderRepo := &fileManagerFolderRepoMock{
+		getByParentNameResult: &filemanager.Folder{
+			ID:             rootID,
+			Name:           filemanager.SystemRootFolderName,
+			NameNormalized: filemanager.SystemRootFolderName,
+		},
+	}
+	storage := &fileManagerStorageMock{}
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{
+		EnableS3Tagging: true,
+	})
+	svc.SetObjectStorage(storage)
+	svc.SetFileProcessingQueue(&fileProcessingQueueMock{})
+
+	_, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+		Name:        "proof.pdf",
+		ContentType: "application/pdf",
+		SizeBytes:   10,
+		Body:        strings.NewReader("0123456789"),
+	})
+	if err != nil {
+		t.Fatalf("UploadFileNode() error = %v", err)
+	}
+	if !fileRepo.updateLifecycleCalled {
+		t.Fatalf("expected lifecycle update to be called")
+	}
+	if storage.taggingCalls == 0 {
+		t.Fatalf("expected object tagging to be called")
+	}
+	if storage.lastTags["gc"] != "temp" {
+		t.Fatalf("expected gc=temp tag, got %v", storage.lastTags)
+	}
+}
+
+func TestFileManagerServiceReconcileFileLifecycle_MarksOrphanPendingWhenUnreferenced(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDAnyResult: &filemanager.File{
+			ID:              append([]byte(nil), fileID...),
+			ObjectKey:       "files/2026/04/27/a.pdf",
+			LifecycleStatus: filemanager.FileLifecycleStatusActive,
+		},
+		isFileReferencedResult: false,
+	}
+	storage := &fileManagerStorageMock{}
+	svc := NewFileManagerService(&fileManagerFolderRepoMock{}, fileRepo, nil, FileManagerServiceDependencies{
+		EnableS3Tagging: true,
+	})
+	svc.SetObjectStorage(storage)
+
+	if err := svc.ReconcileFileLifecycle(context.Background(), fileID, uuidv7.MustBytes()); err != nil {
+		t.Fatalf("ReconcileFileLifecycle() error = %v", err)
+	}
+	if !fileRepo.updateLifecycleCalled {
+		t.Fatalf("expected lifecycle update called")
+	}
+	if storage.lastTags["gc"] != "keep" {
+		t.Fatalf("expected gc=keep tag, got %v", storage.lastTags)
+	}
+}
+
+func TestFileManagerServiceCleanupOrphanPendingFiles_DryRunAndDelete(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	orphanedAt := time.Now().UTC().Add(-48 * time.Hour)
+	fileRepo := &fileManagerFileRepoMock{
+		listByLifecycleResult: []filemanager.File{{
+			ID:              append([]byte(nil), fileID...),
+			ObjectKey:       "files/2026/04/25/a.pdf",
+			LifecycleStatus: filemanager.FileLifecycleStatusOrphanPending,
+			OrphanedAt:      &orphanedAt,
+		}},
+		isFileReferencedResult: false,
+	}
+	storage := &fileManagerStorageMock{}
+	svc := NewFileManagerService(&fileManagerFolderRepoMock{}, fileRepo, nil, FileManagerServiceDependencies{
+		EnableS3Tagging: true,
+	})
+	svc.SetObjectStorage(storage)
+
+	stats, err := svc.CleanupOrphanPendingFiles(context.Background(), time.Now().UTC(), 24*time.Hour, 10, true)
+	if err != nil {
+		t.Fatalf("dry-run cleanup error = %v", err)
+	}
+	if stats.DryRun != true || stats.Scanned != 1 || stats.Deleted != 0 {
+		t.Fatalf("unexpected dry-run stats: %+v", stats)
+	}
+
+	stats, err = svc.CleanupOrphanPendingFiles(context.Background(), time.Now().UTC(), 24*time.Hour, 10, false)
+	if err != nil {
+		t.Fatalf("cleanup error = %v", err)
+	}
+	if stats.Deleted != 1 {
+		t.Fatalf("expected 1 deleted file, got %+v", stats)
+	}
+	if storage.deleteCalls == 0 {
+		t.Fatalf("expected s3 delete called")
+	}
+}
+
+func TestFileManagerServicePurgeFileNode_DeletesThumbnailObject(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	deletedAt := time.Now().UTC().Add(-time.Minute)
+	thumbKey := "files/2026/04/27/thumb-photo.jpg"
+	objectKey := "files/2026/04/27/photo.jpg"
+
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDAnyResult: &filemanager.File{
+			ID:                 append([]byte(nil), fileID...),
+			ObjectKey:          objectKey,
+			ThumbnailObjectKey: &thumbKey,
+			DeletedAt:          &deletedAt,
+		},
+	}
+	storage := &fileManagerStorageMock{}
+	svc := NewFileManagerService(&fileManagerFolderRepoMock{}, fileRepo, nil, FileManagerServiceDependencies{})
+	svc.SetObjectStorage(storage)
+
+	if err := svc.PurgeFileNode(context.Background(), fileID); err != nil {
+		t.Fatalf("purge file node: %v", err)
+	}
+	if !fileRepo.purgeCalled {
+		t.Fatalf("expected purge repository called")
+	}
+
+	deadline := time.Now().Add(300 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		if storage.deleteCalls >= 2 {
+			break
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	if storage.deleteCalls != 2 {
+		t.Fatalf("expected 2 deleted objects (main+thumb), got %d", storage.deleteCalls)
+	}
+	hasObject := false
+	hasThumb := false
+	for i := range storage.deletedKeys {
+		if storage.deletedKeys[i] == objectKey {
+			hasObject = true
+		}
+		if storage.deletedKeys[i] == thumbKey {
+			hasThumb = true
+		}
+	}
+	if !hasObject || !hasThumb {
+		t.Fatalf("expected deleted keys to include main and thumb, got %#v", storage.deletedKeys)
+	}
+}
+
+func TestFileManagerServiceUploadFileNode_TaggingFailureDoesNotFailUpload(t *testing.T) {
+	rootID := uuidv7.MustBytes()
+	fileRepo := &fileManagerFileRepoMock{
+		getByIDResult: &filemanager.File{
+			ID:             uuidv7.MustBytes(),
+			FolderID:       rootID,
+			Name:           "proof.pdf",
+			NameNormalized: "proof.pdf",
+			ObjectKey:      "files/2026/04/27/proof.pdf",
+			Status:         filemanager.FileStatusUploaded,
+		},
+	}
+	folderRepo := &fileManagerFolderRepoMock{
+		getByParentNameResult: &filemanager.Folder{
+			ID:             rootID,
+			Name:           filemanager.SystemRootFolderName,
+			NameNormalized: filemanager.SystemRootFolderName,
+		},
+	}
+	storage := &fileManagerStorageMock{taggingErr: errors.New("tagging denied")}
+	svc := NewFileManagerService(folderRepo, fileRepo, nil, FileManagerServiceDependencies{
+		EnableS3Tagging: true,
+	})
+	svc.SetObjectStorage(storage)
+	svc.SetFileProcessingQueue(&fileProcessingQueueMock{})
+
+	if _, err := svc.UploadFileNode(context.Background(), filemanager.UploadFileParams{
+		Name:        "proof.pdf",
+		ContentType: "application/pdf",
+		SizeBytes:   10,
+		Body:        strings.NewReader("0123456789"),
+	}); err != nil {
+		t.Fatalf("upload should still succeed when tagging fails, err=%v", err)
+	}
+}
diff --git a/internal/service/file_processing_queue.go b/internal/service/file_processing_queue.go
new file mode 100644
index 0000000..036a0ce
--- /dev/null
+++ b/internal/service/file_processing_queue.go
@@ -0,0 +1,33 @@
+package service
+
+import (
+	"context"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/queue"
+)
+
+type fileProcessingQueueAdapter struct {
+	producer queue.FileProcessingJobProducer
+}
+
+func (a fileProcessingQueueAdapter) Enqueue(ctx context.Context, job filemanager.FileProcessingJob) error {
+	return a.producer.Enqueue(ctx, queue.FileProcessingJob{
+		JobID:      job.JobID,
+		FileUUID:   job.FileUUID,
+		Bucket:     job.Bucket,
+		ObjectKey:  job.ObjectKey,
+		UploadedBy: job.UploadedBy,
+		MimeType:   job.MimeType,
+		SizeBytes:  job.SizeBytes,
+		TraceID:    job.TraceID,
+		RequestID:  job.RequestID,
+	})
+}
+
+func AdaptFileProcessingQueue(producer queue.FileProcessingJobProducer) filemanager.FileProcessingQueue {
+	if producer == nil {
+		return nil
+	}
+	return fileProcessingQueueAdapter{producer: producer}
+}
diff --git a/internal/service/file_processing_usecase.go b/internal/service/file_processing_usecase.go
new file mode 100644
index 0000000..5f078f0
--- /dev/null
+++ b/internal/service/file_processing_usecase.go
@@ -0,0 +1,769 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"image"
+	_ "image/gif"
+	"image/jpeg"
+	_ "image/jpeg"
+	"image/png"
+	_ "image/png"
+	"io"
+	"log/slog"
+	"mime/multipart"
+	"net/http"
+	"path/filepath"
+	"strings"
+	"time"
+
+	xdraw "golang.org/x/image/draw"
+	_ "golang.org/x/image/webp"
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type fileProcessingPermanentError struct {
+	err error
+}
+
+func (e *fileProcessingPermanentError) Error() string {
+	if e == nil || e.err == nil {
+		return "file processing permanent error"
+	}
+	return e.err.Error()
+}
+
+func (e *fileProcessingPermanentError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.err
+}
+
+func wrapFileProcessingPermanent(err error) error {
+	if err == nil {
+		return nil
+	}
+	var marker *fileProcessingPermanentError
+	if errors.As(err, &marker) {
+		return err
+	}
+	return &fileProcessingPermanentError{err: err}
+}
+
+func IsFileProcessingPermanentError(err error) bool {
+	var marker *fileProcessingPermanentError
+	return errors.As(err, &marker)
+}
+
+type FileProcessingUseCase struct {
+	fileRepo         filemanager.FileRepository
+	storage          FileProcessingObjectStorage
+	logger           *slog.Logger
+	fileStatusEvents filemanager.FileStatusRealtimeEventWriter
+	gotenbergURL     string
+}
+
+type FileProcessingObjectStorage interface {
+	GetObject(ctx context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error)
+	PutObject(ctx context.Context, input filemanager.PutObjectInput) (filemanager.ObjectMetadata, error)
+	DeleteObject(ctx context.Context, objectKey string) error
+}
+
+type FileProcessingUseCaseDependencies struct {
+	Logger           *slog.Logger
+	Storage          FileProcessingObjectStorage
+	FileStatusEvents filemanager.FileStatusRealtimeEventWriter
+	GotenbergURL     string
+}
+
+const (
+	jpegContentType        = "image/jpeg"
+	pngContentType         = "image/png"
+	jpegCompressionQuality = 80
+	thumbnailMaxDimension  = 512
+)
+
+func stringPointerOrNil(value string) *string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return nil
+	}
+	return &value
+}
+
+func NewFileProcessingUseCase(fileRepo filemanager.FileRepository, deps FileProcessingUseCaseDependencies) *FileProcessingUseCase {
+	logger := deps.Logger
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &FileProcessingUseCase{
+		fileRepo:         fileRepo,
+		logger:           logger,
+		storage:          deps.Storage,
+		fileStatusEvents: deps.FileStatusEvents,
+		gotenbergURL:     strings.TrimSpace(deps.GotenbergURL),
+	}
+}
+
+func (u *FileProcessingUseCase) SetFileStatusRealtimeEventWriter(writer filemanager.FileStatusRealtimeEventWriter) {
+	u.fileStatusEvents = writer
+}
+
+func (u *FileProcessingUseCase) SetObjectStorage(storage FileProcessingObjectStorage) {
+	u.storage = storage
+}
+
+func (u *FileProcessingUseCase) Process(ctx context.Context, job filemanager.FileProcessingJob, correlationID string) error {
+	if u.fileRepo == nil {
+		return wrapFileProcessingPermanent(errors.New("file repository is required"))
+	}
+
+	job = canonicalFileProcessingJob(job)
+	if err := validateFileProcessingJob(job); err != nil {
+		return wrapFileProcessingPermanent(err)
+	}
+
+	fileID, err := uuidv7.ParseString(job.FileUUID)
+	if err != nil {
+		return wrapFileProcessingPermanent(fmt.Errorf("parse file uuid: %w", err))
+	}
+
+	row, err := u.fileRepo.GetByIDAny(ctx, fileID)
+	if err != nil {
+		return err
+	}
+	if row == nil {
+		return wrapFileProcessingPermanent(filemanager.ErrFileNotFound)
+	}
+
+	status := filemanager.NormalizeFileStatus(row.Status)
+	switch status {
+	case filemanager.FileStatusValidated, filemanager.FileStatusFailed, filemanager.FileStatusReady, filemanager.FileStatusTrashed:
+		return nil
+	case filemanager.FileStatusUploaded:
+		changed, err := u.transitionToProcessing(ctx, fileID)
+		if err != nil {
+			return err
+		}
+		if changed {
+			row.Status = filemanager.FileStatusProcessing
+			row.UpdatedAt = time.Now().UTC()
+			u.emitStatusEvent(ctx, row, filemanager.FileStatusProcessing, "")
+		}
+	case filemanager.FileStatusProcessing:
+		// Continue from processing state for at-least-once delivery semantics.
+	default:
+		return wrapFileProcessingPermanent(fmt.Errorf("unexpected file status %q", status))
+	}
+
+	if err := validateFileProcessingPayload(row, job); err != nil {
+		reason := truncateFailureReason(err.Error())
+		changed, markErr := u.markFailedFrom(ctx, fileID, filemanager.FileStatusProcessing, reason)
+		if markErr != nil {
+			return markErr
+		}
+		if changed {
+			row.Status = filemanager.FileStatusFailed
+			row.FailureReason = reason
+			row.UpdatedAt = time.Now().UTC()
+			u.emitStatusEvent(ctx, row, filemanager.FileStatusFailed, reason)
+		}
+		u.logger.Warn("file processing failed",
+			slog.String("file_uuid", job.FileUUID),
+			slog.String("reason", reason),
+			slog.String("correlation_id", correlationID),
+		)
+		return nil
+	}
+
+	if err := u.compressObjectIfNeeded(ctx, row, correlationID); err != nil {
+		return err
+	}
+
+	if err := u.convertDocumentIfNeeded(ctx, row, correlationID); err != nil {
+		return err
+	}
+
+	changed, err := u.markValidated(ctx, fileID)
+	if err != nil {
+		return err
+	}
+	if changed {
+		row.Status = filemanager.FileStatusValidated
+		row.FailureReason = ""
+		row.UpdatedAt = time.Now().UTC()
+		u.emitStatusEvent(ctx, row, filemanager.FileStatusValidated, "")
+	}
+
+	readyChanged, err := u.markReady(ctx, fileID, row)
+	if err != nil {
+		reason := truncateFailureReason(err.Error())
+		failedChanged, markErr := u.markFailedFrom(ctx, fileID, filemanager.FileStatusValidated, reason)
+		if markErr != nil {
+			return markErr
+		}
+		if failedChanged {
+			row.Status = filemanager.FileStatusFailed
+			row.FailureReason = reason
+			row.UpdatedAt = time.Now().UTC()
+			u.emitStatusEvent(ctx, row, filemanager.FileStatusFailed, reason)
+		}
+		u.logger.Warn("file processing finalize failed",
+			slog.String("file_uuid", job.FileUUID),
+			slog.String("reason", reason),
+			slog.String("correlation_id", correlationID),
+		)
+		return nil
+	}
+	if readyChanged {
+		row.Status = filemanager.FileStatusReady
+		row.FailureReason = ""
+		row.UpdatedAt = time.Now().UTC()
+		u.emitStatusEvent(ctx, row, filemanager.FileStatusReady, "")
+	}
+
+	u.logger.Info("file processing completed",
+		slog.String("file_uuid", job.FileUUID),
+		slog.String("correlation_id", correlationID),
+	)
+	return nil
+}
+
+func (u *FileProcessingUseCase) compressObjectIfNeeded(ctx context.Context, row *filemanager.File, correlationID string) error {
+	if row == nil || u.storage == nil {
+		return nil
+	}
+	originalMimeType := normalizeUploadedMimeType(row.MimeType)
+	if !isCompressibleImageMimeType(originalMimeType) {
+		return nil
+	}
+
+	body, _, err := u.storage.GetObject(ctx, row.ObjectKey)
+	if err != nil {
+		return err
+	}
+	defer body.Close()
+
+	raw, err := io.ReadAll(body)
+	if err != nil {
+		return err
+	}
+
+	compressed, thumbnailContentType, err := compressImageForPreview(raw, originalMimeType)
+	if err != nil {
+		u.logger.Warn("file compression skipped: decode/encode failed",
+			slog.String("object_key", row.ObjectKey),
+			slog.String("mime_type", originalMimeType),
+			slog.String("error", err.Error()),
+			slog.String("correlation_id", correlationID),
+		)
+		return nil
+	}
+	if len(compressed) == 0 {
+		return nil
+	}
+
+	originalObjectKey := strings.TrimSpace(row.ObjectKey)
+	targetObjectKey := thumbnailObjectKey(originalObjectKey, thumbnailContentType)
+	meta, err := u.storage.PutObject(ctx, filemanager.PutObjectInput{
+		ObjectKey:   targetObjectKey,
+		ContentType: thumbnailContentType,
+		SizeBytes:   int64(len(compressed)),
+		Body:        bytes.NewReader(compressed),
+	})
+	if err != nil {
+		return err
+	}
+
+	row.ThumbnailMimeType = stringPointerOrNil(thumbnailContentType)
+	row.ThumbnailSizeBytes = int64(len(compressed))
+	thumbnailBucket := strings.TrimSpace(meta.Bucket)
+	if thumbnailBucket == "" {
+		thumbnailBucket = strings.TrimSpace(row.Bucket)
+	}
+	row.ThumbnailBucket = stringPointerOrNil(thumbnailBucket)
+	thumbnailObjectKey := strings.TrimSpace(meta.ObjectKey)
+	if thumbnailObjectKey == "" {
+		thumbnailObjectKey = targetObjectKey
+	}
+	row.ThumbnailObjectKey = stringPointerOrNil(thumbnailObjectKey)
+	row.ThumbnailETag = stringPointerOrNil(meta.ETag)
+	row.ThumbnailObjectVersion = stringPointerOrNil(meta.VersionID)
+	if err := u.fileRepo.Update(ctx, row); err != nil {
+		return err
+	}
+
+	u.logger.Info("file thumbnail generated",
+		slog.String("object_key", row.ObjectKey),
+		slog.String("thumbnail_object_key", thumbnailObjectKey),
+		slog.String("mime_type_before", originalMimeType),
+		slog.String("mime_type_after", thumbnailContentType),
+		slog.Int("before_bytes", len(raw)),
+		slog.Int("after_bytes", len(compressed)),
+		slog.String("correlation_id", correlationID),
+	)
+	return nil
+}
+
+func isCompressibleImageMimeType(mimeType string) bool {
+	mimeType = strings.ToLower(strings.TrimSpace(mimeType))
+	if !strings.HasPrefix(mimeType, "image/") {
+		return false
+	}
+	switch mimeType {
+	case "image/svg+xml", "image/webp":
+		return false
+	default:
+		return true
+	}
+}
+
+func compressImageForPreview(raw []byte, originalMimeType string) ([]byte, string, error) {
+	if len(raw) == 0 {
+		return nil, "", errors.New("empty image payload")
+	}
+	img, _, err := image.Decode(bytes.NewReader(raw))
+	if err != nil {
+		return nil, "", err
+	}
+	img = downscaleForThumbnail(img, thumbnailMaxDimension)
+
+	var out bytes.Buffer
+	switch normalizeUploadedMimeType(originalMimeType) {
+	case pngContentType, "image/gif":
+		encoder := png.Encoder{CompressionLevel: png.BestCompression}
+		if err := encoder.Encode(&out, img); err != nil {
+			return nil, "", err
+		}
+		return out.Bytes(), pngContentType, nil
+	default:
+		if err := jpeg.Encode(&out, img, &jpeg.Options{Quality: jpegCompressionQuality}); err != nil {
+			return nil, "", err
+		}
+		return out.Bytes(), jpegContentType, nil
+	}
+}
+
+func downscaleForThumbnail(src image.Image, maxDim int) image.Image {
+	if src == nil || maxDim <= 0 {
+		return src
+	}
+	bounds := src.Bounds()
+	width := bounds.Dx()
+	height := bounds.Dy()
+	if width <= 0 || height <= 0 {
+		return src
+	}
+	if width <= maxDim && height <= maxDim {
+		return src
+	}
+
+	scale := float64(maxDim) / float64(width)
+	if height > width {
+		scale = float64(maxDim) / float64(height)
+	}
+	newWidth := int(float64(width) * scale)
+	newHeight := int(float64(height) * scale)
+	if newWidth < 1 {
+		newWidth = 1
+	}
+	if newHeight < 1 {
+		newHeight = 1
+	}
+
+	dst := image.NewRGBA(image.Rect(0, 0, newWidth, newHeight))
+	xdraw.CatmullRom.Scale(dst, dst.Bounds(), src, bounds, xdraw.Over, nil)
+	return dst
+}
+
+func (u *FileProcessingUseCase) transitionToProcessing(ctx context.Context, fileID []byte) (bool, error) {
+	now := time.Now().UTC()
+	if err := u.fileRepo.TransitionStatus(ctx, filemanager.FileStatusTransitionParams{
+		ID:                  fileID,
+		ExpectedFrom:        filemanager.FileStatusUploaded,
+		To:                  filemanager.FileStatusProcessing,
+		ProcessingStartedAt: &now,
+	}); err != nil {
+		if !errors.Is(err, gorm.ErrRecordNotFound) {
+			return false, err
+		}
+		current, getErr := u.fileRepo.GetByIDAny(ctx, fileID)
+		if getErr != nil {
+			return false, getErr
+		}
+		if current == nil {
+			return false, wrapFileProcessingPermanent(filemanager.ErrFileNotFound)
+		}
+		switch filemanager.NormalizeFileStatus(current.Status) {
+		case filemanager.FileStatusProcessing, filemanager.FileStatusValidated, filemanager.FileStatusFailed, filemanager.FileStatusReady, filemanager.FileStatusTrashed:
+			return false, nil
+		default:
+			return false, err
+		}
+	}
+	return true, nil
+}
+
+func (u *FileProcessingUseCase) markValidated(ctx context.Context, fileID []byte) (bool, error) {
+	now := time.Now().UTC()
+	if err := u.fileRepo.TransitionStatus(ctx, filemanager.FileStatusTransitionParams{
+		ID:           fileID,
+		ExpectedFrom: filemanager.FileStatusProcessing,
+		To:           filemanager.FileStatusValidated,
+		ProcessedAt:  &now,
+		ValidatedAt:  &now,
+	}); err != nil {
+		if !errors.Is(err, gorm.ErrRecordNotFound) {
+			return false, err
+		}
+		current, getErr := u.fileRepo.GetByIDAny(ctx, fileID)
+		if getErr != nil {
+			return false, getErr
+		}
+		if current == nil {
+			return false, nil
+		}
+		switch filemanager.NormalizeFileStatus(current.Status) {
+		case filemanager.FileStatusValidated, filemanager.FileStatusFailed, filemanager.FileStatusReady, filemanager.FileStatusTrashed:
+			return false, nil
+		default:
+			return false, err
+		}
+	}
+	return true, nil
+}
+
+func (u *FileProcessingUseCase) markFailedFrom(ctx context.Context, fileID []byte, expectedFrom string, reason string) (bool, error) {
+	now := time.Now().UTC()
+	if err := u.fileRepo.TransitionStatus(ctx, filemanager.FileStatusTransitionParams{
+		ID:            fileID,
+		ExpectedFrom:  expectedFrom,
+		To:            filemanager.FileStatusFailed,
+		ProcessedAt:   &now,
+		FailedAt:      &now,
+		FailureReason: &reason,
+	}); err != nil {
+		if !errors.Is(err, gorm.ErrRecordNotFound) {
+			return false, err
+		}
+		current, getErr := u.fileRepo.GetByIDAny(ctx, fileID)
+		if getErr != nil {
+			return false, getErr
+		}
+		if current == nil {
+			return false, nil
+		}
+		switch filemanager.NormalizeFileStatus(current.Status) {
+		case filemanager.FileStatusFailed, filemanager.FileStatusReady, filemanager.FileStatusTrashed:
+			return false, nil
+		default:
+			return false, err
+		}
+	}
+	return true, nil
+}
+
+func (u *FileProcessingUseCase) markReady(ctx context.Context, fileID []byte, row *filemanager.File) (bool, error) {
+	if row == nil {
+		return false, errors.New("file row is required")
+	}
+	nameNormalized := strings.TrimSpace(row.NameNormalized)
+	if nameNormalized == "" {
+		nameNormalized = strings.ToLower(strings.TrimSpace(row.Name))
+	}
+
+	updatedBy := row.UpdatedBy
+	if len(updatedBy) != 16 {
+		updatedBy = row.CreatedBy
+	}
+
+	if err := u.fileRepo.Finalize(ctx, filemanager.FileFinalizeParams{
+		ID:             fileID,
+		ExpectedFrom:   filemanager.FileStatusValidated,
+		FolderID:       append([]byte(nil), row.FolderID...),
+		Name:           row.Name,
+		NameNormalized: nameNormalized,
+		Extension:      normalizeExtensionToken(firstNonEmptyString(row.Extension, extensionFromName(row.Name))),
+		UpdatedBy:      updatedBy,
+	}); err != nil {
+		if errors.Is(err, gorm.ErrDuplicatedKey) {
+			return false, filemanager.ErrDuplicateName
+		}
+		if !errors.Is(err, gorm.ErrRecordNotFound) {
+			return false, err
+		}
+		current, getErr := u.fileRepo.GetByIDAny(ctx, fileID)
+		if getErr != nil {
+			return false, getErr
+		}
+		if current == nil {
+			return false, nil
+		}
+		switch filemanager.NormalizeFileStatus(current.Status) {
+		case filemanager.FileStatusReady, filemanager.FileStatusFailed, filemanager.FileStatusTrashed:
+			return false, nil
+		default:
+			return false, err
+		}
+	}
+	return true, nil
+}
+
+func (u *FileProcessingUseCase) emitStatusEvent(ctx context.Context, row *filemanager.File, status, failureReason string) {
+	if u.fileStatusEvents == nil || row == nil {
+		return
+	}
+	userID := row.CreatedBy
+	if len(userID) != 16 {
+		userID = row.UpdatedBy
+	}
+	if len(userID) != 16 {
+		return
+	}
+
+	occurredAt := row.UpdatedAt
+	if occurredAt.IsZero() {
+		occurredAt = time.Now().UTC()
+	}
+	_ = u.fileStatusEvents.CreateFileStatusRealtimeEvent(ctx, filemanager.FileStatusRealtimeEventInput{
+		FileID:        append([]byte(nil), row.ID...),
+		UserID:        append([]byte(nil), userID...),
+		Status:        status,
+		Name:          row.Name,
+		FailureReason: strings.TrimSpace(failureReason),
+		OccurredAt:    occurredAt,
+	})
+}
+
+func canonicalFileProcessingJob(job filemanager.FileProcessingJob) filemanager.FileProcessingJob {
+	job.JobID = strings.TrimSpace(job.JobID)
+	job.FileUUID = strings.TrimSpace(job.FileUUID)
+	job.Bucket = strings.TrimSpace(job.Bucket)
+	job.ObjectKey = strings.TrimSpace(job.ObjectKey)
+	job.UploadedBy = strings.TrimSpace(job.UploadedBy)
+	job.MimeType = strings.ToLower(strings.TrimSpace(job.MimeType))
+	job.TraceID = strings.TrimSpace(job.TraceID)
+	job.RequestID = strings.TrimSpace(job.RequestID)
+	return job
+}
+
+func validateFileProcessingJob(job filemanager.FileProcessingJob) error {
+	if strings.TrimSpace(job.FileUUID) == "" {
+		return errors.New("file uuid is required")
+	}
+	if strings.TrimSpace(job.Bucket) == "" {
+		return errors.New("bucket is required")
+	}
+	if strings.TrimSpace(job.ObjectKey) == "" {
+		return errors.New("object key is required")
+	}
+	if job.SizeBytes < 0 {
+		return errors.New("size bytes must be non-negative")
+	}
+	return nil
+}
+
+func validateFileProcessingPayload(row *filemanager.File, job filemanager.FileProcessingJob) error {
+	if row == nil {
+		return errors.New("file row is missing")
+	}
+	if strings.TrimSpace(row.Bucket) == "" {
+		return errors.New("file bucket is empty")
+	}
+	if strings.TrimSpace(row.ObjectKey) == "" {
+		return errors.New("file object key is empty")
+	}
+	if !strings.EqualFold(strings.TrimSpace(row.Bucket), strings.TrimSpace(job.Bucket)) {
+		return errors.New("file bucket mismatch")
+	}
+	rowObjectKey := strings.TrimSpace(row.ObjectKey)
+	jobObjectKey := strings.TrimSpace(job.ObjectKey)
+	if rowObjectKey != jobObjectKey {
+		// Keep compatibility with records converted by earlier worker behavior.
+		if rowObjectKey != webpObjectKey(jobObjectKey) {
+			return errors.New("file object key mismatch")
+		}
+	}
+	if row.SizeBytes < 0 {
+		return errors.New("file size is invalid")
+	}
+	return nil
+}
+
+func webpObjectKey(objectKey string) string {
+	objectKey = strings.TrimSpace(objectKey)
+	if objectKey == "" {
+		return objectKey
+	}
+	ext := strings.ToLower(strings.TrimSpace(filepath.Ext(objectKey)))
+	if ext == ".webp" {
+		return objectKey
+	}
+	if ext == "" {
+		return objectKey + ".webp"
+	}
+	return strings.TrimSuffix(objectKey, ext) + ".webp"
+}
+
+func thumbnailObjectKey(objectKey, mimeType string) string {
+	objectKey = strings.TrimSpace(objectKey)
+	if objectKey == "" {
+		return objectKey
+	}
+	thumbExt := ".jpg"
+	switch normalizeUploadedMimeType(mimeType) {
+	case pngContentType:
+		thumbExt = ".png"
+	}
+	ext := strings.TrimSpace(filepath.Ext(objectKey))
+	if ext == "" {
+		return objectKey + ".thumb" + thumbExt
+	}
+	return strings.TrimSuffix(objectKey, ext) + ".thumb" + thumbExt
+}
+
+func previewObjectKey(objectKey string) string {
+	objectKey = strings.TrimSpace(objectKey)
+	if objectKey == "" {
+		return objectKey
+	}
+	ext := strings.TrimSpace(filepath.Ext(objectKey))
+	if ext == "" {
+		return objectKey + ".preview.pdf"
+	}
+	return strings.TrimSuffix(objectKey, ext) + ".preview.pdf"
+}
+
+func isConvertibleDocumentMimeType(mimeType string) bool {
+	switch strings.ToLower(strings.TrimSpace(mimeType)) {
+	case "application/vnd.openxmlformats-officedocument.wordprocessingml.document", // docx
+		"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",         // xlsx
+		"application/vnd.openxmlformats-officedocument.presentationml.presentation", // pptx
+		"application/msword",           // doc
+		"application/vnd.ms-excel",     // xls
+		"application/vnd.ms-powerpoint": // ppt
+		return true
+	default:
+		return false
+	}
+}
+
+func (u *FileProcessingUseCase) convertDocumentIfNeeded(ctx context.Context, row *filemanager.File, correlationID string) error {
+	if row == nil || u.storage == nil || u.gotenbergURL == "" {
+		return nil
+	}
+	if !isConvertibleDocumentMimeType(row.MimeType) {
+		return nil
+	}
+
+	body, _, err := u.storage.GetObject(ctx, row.ObjectKey)
+	if err != nil {
+		return fmt.Errorf("document preview: get original from storage: %w", err)
+	}
+	defer body.Close()
+
+	raw, err := io.ReadAll(body)
+	if err != nil {
+		return fmt.Errorf("document preview: read original: %w", err)
+	}
+
+	pdfBytes, err := u.callGotenberg(ctx, raw, row.Name)
+	if err != nil {
+		return err
+	}
+
+	targetKey := previewObjectKey(strings.TrimSpace(row.ObjectKey))
+	meta, err := u.storage.PutObject(ctx, filemanager.PutObjectInput{
+		ObjectKey:   targetKey,
+		ContentType: "application/pdf",
+		SizeBytes:   int64(len(pdfBytes)),
+		Body:        bytes.NewReader(pdfBytes),
+	})
+	if err != nil {
+		return fmt.Errorf("document preview: upload preview to storage: %w", err)
+	}
+
+	previewMimeType := "application/pdf"
+	row.PreviewMimeType = &previewMimeType
+	row.PreviewSizeBytes = int64(len(pdfBytes))
+	previewBucket := strings.TrimSpace(meta.Bucket)
+	if previewBucket == "" {
+		previewBucket = strings.TrimSpace(row.Bucket)
+	}
+	row.PreviewBucket = &previewBucket
+	previewKey := strings.TrimSpace(meta.ObjectKey)
+	if previewKey == "" {
+		previewKey = targetKey
+	}
+	row.PreviewObjectKey = &previewKey
+	row.PreviewETag = stringPointerOrNil(meta.ETag)
+	row.PreviewObjectVersion = stringPointerOrNil(meta.VersionID)
+
+	if err := u.fileRepo.Update(ctx, row); err != nil {
+		return fmt.Errorf("document preview: save preview metadata: %w", err)
+	}
+
+	u.logger.Info("document preview generated",
+		slog.String("object_key", row.ObjectKey),
+		slog.String("preview_object_key", previewKey),
+		slog.String("mime_type", row.MimeType),
+		slog.Int("preview_bytes", len(pdfBytes)),
+		slog.String("correlation_id", correlationID),
+	)
+	return nil
+}
+
+func (u *FileProcessingUseCase) callGotenberg(ctx context.Context, raw []byte, filename string) ([]byte, error) {
+	var body bytes.Buffer
+	writer := multipart.NewWriter(&body)
+
+	part, err := writer.CreateFormFile("files", filename)
+	if err != nil {
+		return nil, wrapFileProcessingPermanent(fmt.Errorf("document preview: create multipart field: %w", err))
+	}
+	if _, err := part.Write(raw); err != nil {
+		return nil, wrapFileProcessingPermanent(fmt.Errorf("document preview: write file to multipart: %w", err))
+	}
+	if err := writer.Close(); err != nil {
+		return nil, wrapFileProcessingPermanent(fmt.Errorf("document preview: close multipart writer: %w", err))
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, u.gotenbergURL+"/forms/libreoffice/convert", &body)
+	if err != nil {
+		return nil, wrapFileProcessingPermanent(fmt.Errorf("document preview: build gotenberg request: %w", err))
+	}
+	req.Header.Set("Content-Type", writer.FormDataContentType())
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		// Network or connection error — transient, allow retry.
+		return nil, fmt.Errorf("document preview: gotenberg request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("document preview: read gotenberg response: %w", err)
+	}
+
+	if resp.StatusCode >= http.StatusBadRequest && resp.StatusCode < http.StatusInternalServerError {
+		// 4xx: bad document or unsupported format — permanent failure.
+		return nil, wrapFileProcessingPermanent(fmt.Errorf("document preview: gotenberg rejected document (status %d)", resp.StatusCode))
+	}
+	if resp.StatusCode != http.StatusOK {
+		// 5xx or unexpected — transient, allow retry.
+		return nil, fmt.Errorf("document preview: gotenberg returned status %d", resp.StatusCode)
+	}
+
+	if len(respBody) == 0 {
+		return nil, wrapFileProcessingPermanent(fmt.Errorf("document preview: gotenberg returned empty PDF"))
+	}
+
+	return respBody, nil
+}
diff --git a/internal/service/file_processing_usecase_test.go b/internal/service/file_processing_usecase_test.go
new file mode 100644
index 0000000..a19af2d
--- /dev/null
+++ b/internal/service/file_processing_usecase_test.go
@@ -0,0 +1,416 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"io"
+	"strings"
+	"testing"
+
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/logger"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type fileProcessingStorageMock struct {
+	getObjectFn func(context.Context, string) (io.ReadCloser, filemanager.ObjectMetadata, error)
+	putObjectFn func(context.Context, filemanager.PutObjectInput) (filemanager.ObjectMetadata, error)
+	deleteFn    func(context.Context, string) error
+}
+
+func (m *fileProcessingStorageMock) GetObject(ctx context.Context, key string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+	if m.getObjectFn != nil {
+		return m.getObjectFn(ctx, key)
+	}
+	return io.NopCloser(bytes.NewReader(nil)), filemanager.ObjectMetadata{}, nil
+}
+
+func (m *fileProcessingStorageMock) PutObject(ctx context.Context, input filemanager.PutObjectInput) (filemanager.ObjectMetadata, error) {
+	if m.putObjectFn != nil {
+		return m.putObjectFn(ctx, input)
+	}
+	return filemanager.ObjectMetadata{}, nil
+}
+
+func (m *fileProcessingStorageMock) DeleteObject(ctx context.Context, key string) error {
+	if m.deleteFn != nil {
+		return m.deleteFn(ctx, key)
+	}
+	return nil
+}
+
+func TestFileProcessingUseCase_Process_Success(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	fileUUID, err := uuidv7.BytesToString(fileID)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+
+	row := &filemanager.File{
+		ID:        append([]byte(nil), fileID...),
+		Status:    filemanager.FileStatusUploaded,
+		Bucket:    "bucket-a",
+		ObjectKey: "files/2026/04/03/a.pdf",
+		SizeBytes: 8,
+		CreatedBy: uuidv7.MustBytes(),
+	}
+	repo := &fileManagerFileRepoMock{
+		getByIDAnyResult: row,
+		transitionStatusFn: func(_ context.Context, params filemanager.FileStatusTransitionParams) error {
+			if filemanager.NormalizeFileStatus(row.Status) != filemanager.NormalizeFileStatus(params.ExpectedFrom) {
+				return gorm.ErrRecordNotFound
+			}
+			row.Status = params.To
+			row.ProcessingStartedAt = params.ProcessingStartedAt
+			row.ProcessedAt = params.ProcessedAt
+			row.ValidatedAt = params.ValidatedAt
+			row.FailedAt = params.FailedAt
+			if params.FailureReason != nil {
+				row.FailureReason = *params.FailureReason
+			}
+			return nil
+		},
+	}
+	useCase := NewFileProcessingUseCase(repo, FileProcessingUseCaseDependencies{Logger: logger.NewDiscard()})
+	useCase.SetFileStatusRealtimeEventWriter(repo)
+
+	err = useCase.Process(context.Background(), filemanager.FileProcessingJob{
+		FileUUID:  fileUUID,
+		Bucket:    row.Bucket,
+		ObjectKey: row.ObjectKey,
+		SizeBytes: row.SizeBytes,
+	}, "corr-1")
+	if err != nil {
+		t.Fatalf("process: %v", err)
+	}
+	if filemanager.NormalizeFileStatus(row.Status) != filemanager.FileStatusReady {
+		t.Fatalf("expected ready status, got %s", row.Status)
+	}
+	if repo.transitionStatusCalls != 2 {
+		t.Fatalf("expected 2 transitions (processing+validated), got %d", repo.transitionStatusCalls)
+	}
+	if !repo.finalizeCalled {
+		t.Fatalf("expected finalize to be called")
+	}
+	if len(repo.realtimeEvents) != 3 {
+		t.Fatalf("expected 3 realtime events, got %d", len(repo.realtimeEvents))
+	}
+	if got := filemanager.NormalizeFileStatus(repo.realtimeEvents[0].Status); got != filemanager.FileStatusProcessing {
+		t.Fatalf("expected first realtime status processing, got %s", got)
+	}
+	if got := filemanager.NormalizeFileStatus(repo.realtimeEvents[1].Status); got != filemanager.FileStatusValidated {
+		t.Fatalf("expected second realtime status validated, got %s", got)
+	}
+	if got := filemanager.NormalizeFileStatus(repo.realtimeEvents[2].Status); got != filemanager.FileStatusReady {
+		t.Fatalf("expected third realtime status ready, got %s", got)
+	}
+}
+
+func TestFileProcessingUseCase_Process_MarkFailedOnValidationError(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	fileUUID, err := uuidv7.BytesToString(fileID)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+
+	row := &filemanager.File{
+		ID:        append([]byte(nil), fileID...),
+		Status:    filemanager.FileStatusUploaded,
+		Bucket:    "bucket-a",
+		ObjectKey: "files/2026/04/03/a.pdf",
+		SizeBytes: 8,
+		CreatedBy: uuidv7.MustBytes(),
+	}
+	repo := &fileManagerFileRepoMock{
+		getByIDAnyResult: row,
+		transitionStatusFn: func(_ context.Context, params filemanager.FileStatusTransitionParams) error {
+			if filemanager.NormalizeFileStatus(row.Status) != filemanager.NormalizeFileStatus(params.ExpectedFrom) {
+				return gorm.ErrRecordNotFound
+			}
+			row.Status = params.To
+			row.ProcessingStartedAt = params.ProcessingStartedAt
+			row.ProcessedAt = params.ProcessedAt
+			row.ValidatedAt = params.ValidatedAt
+			row.FailedAt = params.FailedAt
+			if params.FailureReason != nil {
+				row.FailureReason = *params.FailureReason
+			}
+			return nil
+		},
+	}
+	useCase := NewFileProcessingUseCase(repo, FileProcessingUseCaseDependencies{Logger: logger.NewDiscard()})
+	useCase.SetFileStatusRealtimeEventWriter(repo)
+
+	err = useCase.Process(context.Background(), filemanager.FileProcessingJob{
+		FileUUID:  fileUUID,
+		Bucket:    "bucket-other",
+		ObjectKey: row.ObjectKey,
+		SizeBytes: row.SizeBytes,
+	}, "corr-2")
+	if err != nil {
+		t.Fatalf("process: %v", err)
+	}
+	if filemanager.NormalizeFileStatus(row.Status) != filemanager.FileStatusFailed {
+		t.Fatalf("expected failed status, got %s", row.Status)
+	}
+	if row.FailureReason == "" {
+		t.Fatalf("expected failure reason set")
+	}
+	if repo.transitionStatusCalls != 2 {
+		t.Fatalf("expected 2 transitions (processing+failed), got %d", repo.transitionStatusCalls)
+	}
+	if len(repo.realtimeEvents) != 2 {
+		t.Fatalf("expected 2 realtime events, got %d", len(repo.realtimeEvents))
+	}
+	if got := filemanager.NormalizeFileStatus(repo.realtimeEvents[0].Status); got != filemanager.FileStatusProcessing {
+		t.Fatalf("expected first realtime status processing, got %s", got)
+	}
+	if got := filemanager.NormalizeFileStatus(repo.realtimeEvents[1].Status); got != filemanager.FileStatusFailed {
+		t.Fatalf("expected second realtime status failed, got %s", got)
+	}
+	if strings.TrimSpace(repo.realtimeEvents[1].FailureReason) == "" {
+		t.Fatalf("expected failure reason on failed realtime event")
+	}
+}
+
+func TestFileProcessingUseCase_Process_MarkFailedOnFinalizeError(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	fileUUID, err := uuidv7.BytesToString(fileID)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+
+	row := &filemanager.File{
+		ID:             append([]byte(nil), fileID...),
+		Status:         filemanager.FileStatusUploaded,
+		Bucket:         "bucket-a",
+		ObjectKey:      "files/2026/04/03/a.pdf",
+		Name:           "a.pdf",
+		NameNormalized: "a.pdf",
+		SizeBytes:      8,
+		CreatedBy:      uuidv7.MustBytes(),
+	}
+	repo := &fileManagerFileRepoMock{
+		getByIDAnyResult: row,
+		transitionStatusFn: func(_ context.Context, params filemanager.FileStatusTransitionParams) error {
+			if filemanager.NormalizeFileStatus(row.Status) != filemanager.NormalizeFileStatus(params.ExpectedFrom) {
+				return gorm.ErrRecordNotFound
+			}
+			row.Status = params.To
+			row.ProcessingStartedAt = params.ProcessingStartedAt
+			row.ProcessedAt = params.ProcessedAt
+			row.ValidatedAt = params.ValidatedAt
+			row.FailedAt = params.FailedAt
+			if params.FailureReason != nil {
+				row.FailureReason = *params.FailureReason
+			}
+			return nil
+		},
+		finalizeErr: gorm.ErrDuplicatedKey,
+	}
+	useCase := NewFileProcessingUseCase(repo, FileProcessingUseCaseDependencies{Logger: logger.NewDiscard()})
+	useCase.SetFileStatusRealtimeEventWriter(repo)
+
+	err = useCase.Process(context.Background(), filemanager.FileProcessingJob{
+		FileUUID:  fileUUID,
+		Bucket:    row.Bucket,
+		ObjectKey: row.ObjectKey,
+		SizeBytes: row.SizeBytes,
+	}, "corr-5")
+	if err != nil {
+		t.Fatalf("process: %v", err)
+	}
+	if filemanager.NormalizeFileStatus(row.Status) != filemanager.FileStatusFailed {
+		t.Fatalf("expected failed status, got %s", row.Status)
+	}
+	if repo.transitionStatusCalls != 3 {
+		t.Fatalf("expected 3 transitions (processing+validated+failed), got %d", repo.transitionStatusCalls)
+	}
+	if len(repo.realtimeEvents) != 3 {
+		t.Fatalf("expected 3 realtime events, got %d", len(repo.realtimeEvents))
+	}
+	if got := filemanager.NormalizeFileStatus(repo.realtimeEvents[2].Status); got != filemanager.FileStatusFailed {
+		t.Fatalf("expected third realtime status failed, got %s", got)
+	}
+}
+
+func TestFileProcessingUseCase_Process_IgnoreNonEligibleStatus(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	fileUUID, err := uuidv7.BytesToString(fileID)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+
+	row := &filemanager.File{
+		ID:        append([]byte(nil), fileID...),
+		Status:    filemanager.FileStatusReady,
+		Bucket:    "bucket-a",
+		ObjectKey: "files/2026/04/03/a.pdf",
+		SizeBytes: 8,
+	}
+	repo := &fileManagerFileRepoMock{
+		getByIDAnyResult: row,
+	}
+	useCase := NewFileProcessingUseCase(repo, FileProcessingUseCaseDependencies{Logger: logger.NewDiscard()})
+
+	err = useCase.Process(context.Background(), filemanager.FileProcessingJob{
+		FileUUID:  fileUUID,
+		Bucket:    row.Bucket,
+		ObjectKey: row.ObjectKey,
+		SizeBytes: row.SizeBytes,
+	}, "corr-3")
+	if err != nil {
+		t.Fatalf("process: %v", err)
+	}
+	if repo.transitionStatusCalls != 0 {
+		t.Fatalf("expected no transition for ready status")
+	}
+}
+
+func TestFileProcessingUseCase_Process_FileNotFoundPermanent(t *testing.T) {
+	fileUUID, err := uuidv7.String(uuidv7.MustNew())
+	if err != nil {
+		t.Fatalf("uuid string: %v", err)
+	}
+	repo := &fileManagerFileRepoMock{}
+	useCase := NewFileProcessingUseCase(repo, FileProcessingUseCaseDependencies{Logger: logger.NewDiscard()})
+
+	err = useCase.Process(context.Background(), filemanager.FileProcessingJob{
+		FileUUID:  fileUUID,
+		Bucket:    "bucket-a",
+		ObjectKey: "files/2026/04/03/a.pdf",
+		SizeBytes: 8,
+	}, "corr-4")
+	if err == nil {
+		t.Fatalf("expected not found error")
+	}
+	if !IsFileProcessingPermanentError(err) {
+		t.Fatalf("expected permanent classification")
+	}
+	if !errors.Is(err, filemanager.ErrFileNotFound) {
+		t.Fatalf("expected ErrFileNotFound, got %v", err)
+	}
+}
+
+func TestFileProcessingUseCase_Process_CompressesJPEGInWorker(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	fileUUID, err := uuidv7.BytesToString(fileID)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+
+	// Create a JPEG and ensure worker converts image payload to WebP.
+	img := image.NewRGBA(image.Rect(0, 0, 1600, 900))
+	for y := 0; y < 900; y++ {
+		for x := 0; x < 1600; x++ {
+			img.Set(x, y, color.RGBA{R: uint8((x + y) % 255), G: uint8(x % 255), B: uint8(y % 255), A: 255})
+		}
+	}
+	var source bytes.Buffer
+	if err := jpeg.Encode(&source, img, &jpeg.Options{Quality: 100}); err != nil {
+		t.Fatalf("encode source jpeg: %v", err)
+	}
+	row := &filemanager.File{
+		ID:        append([]byte(nil), fileID...),
+		Status:    filemanager.FileStatusUploaded,
+		Bucket:    "bucket-a",
+		ObjectKey: "files/2026/04/03/a.jpg",
+		SizeBytes: int64(source.Len()),
+		MimeType:  "image/jpeg",
+		CreatedBy: uuidv7.MustBytes(),
+	}
+	repo := &fileManagerFileRepoMock{
+		getByIDAnyResult: row,
+		transitionStatusFn: func(_ context.Context, params filemanager.FileStatusTransitionParams) error {
+			if filemanager.NormalizeFileStatus(row.Status) != filemanager.NormalizeFileStatus(params.ExpectedFrom) {
+				return gorm.ErrRecordNotFound
+			}
+			row.Status = params.To
+			return nil
+		},
+	}
+
+	var putCalled bool
+	var uploadedBytes int
+	originalObjectKey := row.ObjectKey
+	thumbnailObjectKey := thumbnailObjectKey(originalObjectKey, jpegContentType)
+	storage := &fileProcessingStorageMock{
+		getObjectFn: func(_ context.Context, key string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+			if key != originalObjectKey {
+				t.Fatalf("unexpected object key %q", key)
+			}
+			return io.NopCloser(bytes.NewReader(source.Bytes())), filemanager.ObjectMetadata{
+				Bucket:    row.Bucket,
+				ObjectKey: originalObjectKey,
+				SizeBytes: int64(source.Len()),
+			}, nil
+		},
+		putObjectFn: func(_ context.Context, input filemanager.PutObjectInput) (filemanager.ObjectMetadata, error) {
+			putCalled = true
+			if input.ObjectKey != thumbnailObjectKey {
+				t.Fatalf("unexpected put object key %q", input.ObjectKey)
+			}
+			if input.ContentType != jpegContentType {
+				t.Fatalf("expected content-type %q, got %q", jpegContentType, input.ContentType)
+			}
+			body, err := io.ReadAll(input.Body)
+			if err != nil {
+				return filemanager.ObjectMetadata{}, err
+			}
+			uploadedBytes = len(body)
+			return filemanager.ObjectMetadata{
+				Bucket:    row.Bucket,
+				ObjectKey: thumbnailObjectKey,
+				ETag:      "etag-new",
+				VersionID: "v2",
+			}, nil
+		},
+	}
+
+	useCase := NewFileProcessingUseCase(repo, FileProcessingUseCaseDependencies{Logger: logger.NewDiscard()})
+	useCase.SetObjectStorage(storage)
+
+	err = useCase.Process(context.Background(), filemanager.FileProcessingJob{
+		FileUUID:  fileUUID,
+		Bucket:    row.Bucket,
+		ObjectKey: row.ObjectKey,
+		SizeBytes: row.SizeBytes,
+	}, "corr-compress")
+	if err != nil {
+		t.Fatalf("process: %v", err)
+	}
+
+	if !putCalled {
+		t.Fatalf("expected compressed object upload")
+	}
+	if !repo.updateCalled {
+		t.Fatalf("expected file metadata update after compression")
+	}
+	if uploadedBytes <= 0 {
+		t.Fatalf("expected non-empty encoded thumbnail bytes")
+	}
+	if row.ThumbnailSizeBytes != int64(uploadedBytes) {
+		t.Fatalf("expected thumbnail size updated to %d, got %d", uploadedBytes, row.ThumbnailSizeBytes)
+	}
+	if row.MimeType != "image/jpeg" {
+		t.Fatalf("expected original mime type untouched, got %q", row.MimeType)
+	}
+	if row.ThumbnailMimeType == nil || *row.ThumbnailMimeType != jpegContentType {
+		t.Fatalf("expected thumbnail mime type %q, got %v", jpegContentType, row.ThumbnailMimeType)
+	}
+	if row.ObjectKey != originalObjectKey {
+		t.Fatalf("expected original object key untouched, got %q", row.ObjectKey)
+	}
+	if row.ThumbnailObjectKey == nil || *row.ThumbnailObjectKey != thumbnailObjectKey {
+		t.Fatalf("expected thumbnail object key %q, got %v", thumbnailObjectKey, row.ThumbnailObjectKey)
+	}
+	if filemanager.NormalizeFileStatus(row.Status) != filemanager.FileStatusReady {
+		t.Fatalf("expected ready status, got %s", row.Status)
+	}
+}
diff --git a/internal/service/fleet_history_service.go b/internal/service/fleet_history_service.go
new file mode 100644
index 0000000..e618e74
--- /dev/null
+++ b/internal/service/fleet_history_service.go
@@ -0,0 +1,42 @@
+package service
+
+import (
+	"context"
+
+	fleethistory "wucher/internal/domain/fleet_history"
+)
+
+type FleetHistoryService struct{ repo fleethistory.Repository }
+
+func NewFleetHistoryService(repo fleethistory.Repository) *FleetHistoryService {
+	return &FleetHistoryService{repo: repo}
+}
+
+func (s *FleetHistoryService) Record(ctx context.Context, helicopterID []byte, entityType string, entityID []byte, action, message string, actor []byte) error {
+	if s == nil || s.repo == nil || len(helicopterID) != 16 {
+		return nil
+	}
+	return s.repo.Create(ctx, &fleethistory.FleetHistory{
+		HelicopterID: append([]byte(nil), helicopterID...),
+		EntityType:   entityType,
+		EntityID:     append([]byte(nil), entityID...),
+		Action:       action,
+		Message:      message,
+		Actor:        append([]byte(nil), actor...),
+	})
+}
+
+func (s *FleetHistoryService) RecordByInspection(ctx context.Context, inspectionID []byte, entityType string, entityID []byte, action, message string, actor []byte) error {
+	if s == nil || s.repo == nil || len(inspectionID) != 16 {
+		return nil
+	}
+	helicopterID, err := s.repo.HelicopterIDByInspection(ctx, inspectionID)
+	if err != nil {
+		return err
+	}
+	return s.Record(ctx, helicopterID, entityType, entityID, action, message, actor)
+}
+
+func (s *FleetHistoryService) ListByHelicopter(ctx context.Context, helicopterID []byte, limit, offset int) ([]fleethistory.FleetHistory, int64, error) {
+	return s.repo.ListByHelicopter(ctx, helicopterID, limit, offset)
+}
diff --git a/internal/service/fleet_status_file_service.go b/internal/service/fleet_status_file_service.go
new file mode 100644
index 0000000..042d857
--- /dev/null
+++ b/internal/service/fleet_status_file_service.go
@@ -0,0 +1,11 @@
+package service
+
+import "wucher/internal/domain/file_manager"
+
+type FleetStatusFileService struct {
+	fileManager filemanager.Service
+}
+
+func NewFleetStatusFileService(fileManager filemanager.Service) *FleetStatusFileService {
+	return &FleetStatusFileService{fileManager: fileManager}
+}
diff --git a/internal/service/fleet_status_service.go b/internal/service/fleet_status_service.go
new file mode 100644
index 0000000..6be2b80
--- /dev/null
+++ b/internal/service/fleet_status_service.go
@@ -0,0 +1,664 @@
+package service
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"strings"
+	"time"
+
+	complaint "wucher/internal/domain/complaint"
+	filemanager "wucher/internal/domain/file_manager"
+	fleethistory "wucher/internal/domain/fleet_history"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	"wucher/internal/domain/helicopter"
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+	"wucher/internal/shared/pkg/nextdue"
+	"wucher/internal/shared/pkg/uuidv7"
+	shareddto "wucher/internal/transport/http/dto/shared"
+)
+
+type fleetStatusAttachments interface {
+	CreateAttachment(ctx context.Context, params filemanager.CreateAttachmentParams) (*filemanager.Attachment, error)
+	DeleteAttachment(ctx context.Context, id []byte) error
+}
+
+type fleetStatusHelicopters interface {
+	GetByID(ctx context.Context, id []byte) (*helicopter.Helicopter, error)
+	Update(ctx context.Context, h *helicopter.Helicopter) error
+}
+
+type fleetStatusComplaints interface {
+	ListByHelicopter(ctx context.Context, helicopterID []byte, limit, offset int) ([]complaint.Complaint, int64, error)
+	ResolveUserNames(ctx context.Context, complaints []complaint.Complaint) (map[string]string, error)
+}
+
+type fleetStatusUsage interface {
+	GetByHelicopterID(ctx context.Context, helicopterID []byte) (*helicopterusage.HelicopterUsage, error)
+	ReviseManualTotals(ctx context.Context, helicopterID []byte, in helicopterusage.ManualSummaryInput, actor []byte) error
+}
+
+const (
+	FleetStatusFileRefType = "fleet_status"
+
+	autoAOGReasonPrefixNextDue   = "[auto_next_due]"
+	autoAOGReasonPrefixComplaint = "[auto_complaint]"
+)
+
+type NextDueEvaluation struct {
+	InspectionType string
+	AOG            bool
+	Reason         string
+}
+
+type ComponentHours struct {
+	Airframe float64
+	Engine1  float64
+	Engine2  float64
+}
+
+type FleetStatusService struct {
+	repo        fleetstatus.Repository
+	attachments fleetStatusAttachments
+	helicopters fleetStatusHelicopters
+	complaints  fleetStatusComplaints
+	history     *FleetHistoryService
+	usage       fleetStatusUsage
+}
+
+func (s *FleetStatusService) Create(ctx context.Context, row *fleetstatus.FleetStatus) error {
+	if s.attachments == nil {
+		if err := s.repo.Create(ctx, row); err != nil {
+			return err
+		}
+		return s.syncAutomaticAOG(ctx, row)
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	files, createdIDs, err := s.resolveFileLinks(ctx, row.ID, row.Files, nil, row.UpdatedBy)
+	if err != nil {
+		return err
+	}
+	row.Files = files
+	if err := s.repo.Create(ctx, row); err != nil {
+		s.rollbackAttachments(ctx, createdIDs)
+		return err
+	}
+	if err := s.syncAutomaticAOG(ctx, row); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (s *FleetStatusService) Update(ctx context.Context, row *fleetstatus.FleetStatus) error {
+	if s.attachments == nil {
+		if err := s.repo.Update(ctx, row); err != nil {
+			return err
+		}
+		return s.syncAutomaticAOG(ctx, row)
+	}
+
+	newKeys := make(map[string]struct{})
+	for i := range row.Files {
+		if len(row.Files[i].FileID) == 16 {
+			key, _ := uuidv7.BytesToString(row.Files[i].FileID)
+			newKeys[key] = struct{}{}
+		}
+	}
+	if len(newKeys) == 0 {
+		if err := s.repo.Update(ctx, row); err != nil {
+			return err
+		}
+		return s.syncAutomaticAOG(ctx, row)
+	}
+
+	existing, err := s.repo.GetByID(ctx, row.ID)
+	if err != nil {
+		return err
+	}
+	reuse := make(map[string][]byte)
+	type oldRef struct {
+		key   string
+		attID []byte
+	}
+	var olds []oldRef
+	if existing != nil {
+		for i := range existing.Files {
+			ef := existing.Files[i]
+			if ef.Attachment == nil || len(ef.Attachment.FileID) != 16 {
+				continue
+			}
+			key, _ := uuidv7.BytesToString(ef.Attachment.FileID)
+			reuse[key] = ef.FileAttachmentID
+			olds = append(olds, oldRef{key: key, attID: ef.FileAttachmentID})
+		}
+	}
+
+	files, createdIDs, err := s.resolveFileLinks(ctx, row.ID, row.Files, reuse, row.UpdatedBy)
+	if err != nil {
+		return err
+	}
+	row.Files = files
+
+	if err := s.repo.Update(ctx, row); err != nil {
+		s.rollbackAttachments(ctx, createdIDs)
+		return err
+	}
+
+	if err := s.syncAutomaticAOG(ctx, row); err != nil {
+		return err
+	}
+
+	for _, o := range olds {
+		if _, keep := newKeys[o.key]; keep {
+			continue
+		}
+		_ = s.attachments.DeleteAttachment(ctx, o.attID)
+	}
+	return nil
+}
+
+func (s *FleetStatusService) WithUsage(u fleetStatusUsage) *FleetStatusService {
+	s.usage = u
+	return s
+}
+
+func (s *FleetStatusService) ReviseSummary(ctx context.Context, helicopterID []byte, in helicopterusage.ManualSummaryInput, actor []byte) error {
+	if s.usage == nil || len(helicopterID) != 16 {
+		return nil
+	}
+	return s.usage.ReviseManualTotals(ctx, helicopterID, in, actor)
+}
+
+func (s *FleetStatusService) WithHistory(h *FleetHistoryService) *FleetStatusService {
+	s.history = h
+	return s
+}
+
+func (s *FleetStatusService) recordAutoAOG(ctx context.Context, heli *helicopter.Helicopter, set bool, reason string) {
+	if s.history == nil || heli == nil {
+		return
+	}
+	action := fleethistory.ActionAOGCleared
+	msg := "AOG cleared (auto: maintenance no longer due)"
+	if set {
+		action = fleethistory.ActionAOGSet
+		msg = "AOG set (auto: maintenance next due)"
+		if r := strings.TrimSpace(reason); r != "" {
+			msg = "AOG set (auto) — " + r
+		}
+	}
+	if err := s.history.Record(ctx, heli.ID, fleethistory.EntityHelicopter, heli.ID, action, msg, nil); err != nil {
+		slog.WarnContext(ctx, "fleet status: record auto-AOG history failed", slog.Any("error", err))
+	}
+}
+
+func NewFleetStatusService(repo fleetstatus.Repository, attachments fleetStatusAttachments, helicopters fleetStatusHelicopters, complaints fleetStatusComplaints) *FleetStatusService {
+	return &FleetStatusService{repo: repo, attachments: attachments, helicopters: helicopters, complaints: complaints}
+}
+
+func (s *FleetStatusService) syncAutomaticAOG(ctx context.Context, row *fleetstatus.FleetStatus) error {
+	if s == nil || s.helicopters == nil || row == nil || len(row.HelicopterID) != 16 {
+		return nil
+	}
+	heli, err := s.helicopters.GetByID(ctx, row.HelicopterID)
+	if err != nil {
+		return err
+	}
+	if heli == nil {
+		idStr, _ := uuidv7.BytesToString(row.HelicopterID)
+		slog.WarnContext(ctx, "fleet status: helicopter not found, skipping AOG sync", slog.String("helicopter_id", idStr))
+		return nil
+	}
+	now := time.Now().UTC()
+
+	var evals []NextDueEvaluation
+	if hasEligibleSchedule(row.MaintenanceSchedules) {
+		summary, sErr := s.GetSummaryByHelicopterID(ctx, row.HelicopterID)
+		if sErr != nil {
+			return sErr
+		}
+		hours := ComponentHours{
+			Airframe: derefFloat(summary.Airframe.Hours),
+			Engine1:  derefFloat(summary.Engine1.Hours),
+			Engine2:  derefFloat(summary.Engine2.Hours),
+		}
+		evals, err = EvaluateNextDueSchedules(row.MaintenanceSchedules, hours, summary.Airframe.Hours != nil, heli.NR1, heli.NR2, now)
+		if err != nil {
+			return err
+		}
+	}
+
+	loadComplaints := func() ([]complaint.Complaint, error) {
+		if s.complaints == nil {
+			return nil, nil
+		}
+		rows, _, lErr := s.complaints.ListByHelicopter(ctx, row.HelicopterID, 100, 0)
+		return rows, lErr
+	}
+	grounded, reason, source, err := decideAutoAOG(evals, now, loadComplaints, func(c complaint.Complaint) string {
+		return s.complaintAOGReason(ctx, c)
+	})
+	if err != nil {
+		return err
+	}
+	return s.applyAutoAOG(ctx, heli, grounded, reason, source)
+}
+
+func decideAutoAOG(evals []NextDueEvaluation, now time.Time, loadComplaints func() ([]complaint.Complaint, error), complaintReason func(complaint.Complaint) string) (grounded bool, reason string, source string, err error) {
+	for i := range evals {
+		if !evals[i].AOG {
+			continue
+		}
+		cleanReason := strings.TrimSpace(evals[i].Reason)
+		if cleanReason == "" {
+			cleanReason = fmt.Sprintf("%s next due reached", evals[i].InspectionType)
+		}
+		return true, autoAOGReasonPrefixNextDue + " " + cleanReason, helicopter.AOGSourceAuto, nil
+	}
+
+	complaints, err := loadComplaints()
+	if err != nil {
+		return false, "", "", err
+	}
+	for i := range complaints {
+		if complaints[i].IsGrounding(now) {
+			return true, complaintReason(complaints[i]), helicopter.AOGSourceComplaint, nil
+		}
+	}
+	return false, "", "", nil
+}
+
+func (s *FleetStatusService) applyAutoAOG(ctx context.Context, heli *helicopter.Helicopter, grounded bool, reason, source string) error {
+	if grounded {
+		wasAOG := heli.AirOnGround
+		if !heli.AirOnGround || strings.TrimSpace(heli.AOGReason) != reason || strings.TrimSpace(heli.AOGSource) != source {
+			heli.AirOnGround = true
+			heli.AOGReason = reason
+			heli.AOGSource = source
+			if err := s.helicopters.Update(ctx, heli); err != nil {
+				return err
+			}
+			if !wasAOG {
+				s.recordAutoAOG(ctx, heli, true, reason)
+			}
+		}
+		return nil
+	}
+
+	if isAutoAOG(heli) {
+		heli.AirOnGround = false
+		heli.AOGReason = ""
+		heli.AOGSource = helicopter.AOGSourceUnknown
+		if err := s.helicopters.Update(ctx, heli); err != nil {
+			return err
+		}
+		s.recordAutoAOG(ctx, heli, false, "")
+	}
+	return nil
+}
+
+func hasEligibleSchedule(schedules []fleetstatus.MaintenanceSchedule) bool {
+	for i := range schedules {
+		if strings.TrimSpace(schedules[i].Due) != "" || strings.TrimSpace(schedules[i].Ext) != "" {
+			return true
+		}
+	}
+	return false
+}
+
+func (s *FleetStatusService) OverdueInspections(ctx context.Context, helicopterID []byte) ([]fleetstatus.OverdueInspection, error) {
+	if s == nil || s.helicopters == nil || len(helicopterID) != 16 {
+		return nil, nil
+	}
+	latest, err := s.repo.LatestByHelicopterIDs(ctx, [][]byte{helicopterID})
+	if err != nil {
+		return nil, err
+	}
+	row := latest[string(helicopterID)]
+	if row == nil || !hasEligibleSchedule(row.MaintenanceSchedules) {
+		return nil, nil
+	}
+	heli, err := s.helicopters.GetByID(ctx, helicopterID)
+	if err != nil || heli == nil {
+		return nil, err
+	}
+	summary, err := s.GetSummaryByHelicopterID(ctx, helicopterID)
+	if err != nil {
+		return nil, err
+	}
+	hours := ComponentHours{
+		Airframe: derefFloat(summary.Airframe.Hours),
+		Engine1:  derefFloat(summary.Engine1.Hours),
+		Engine2:  derefFloat(summary.Engine2.Hours),
+	}
+	evals, err := EvaluateNextDueSchedules(row.MaintenanceSchedules, hours, summary.Airframe.Hours != nil, heli.NR1, heli.NR2, time.Now().UTC())
+	if err != nil {
+		return nil, err
+	}
+	out := make([]fleetstatus.OverdueInspection, 0, len(evals))
+	for i := range evals {
+		if !evals[i].AOG {
+			continue
+		}
+		detail := strings.TrimSpace(evals[i].Reason)
+		if detail == "" {
+			detail = evals[i].InspectionType + " next due reached"
+		}
+		out = append(out, fleetstatus.OverdueInspection{InspectionType: evals[i].InspectionType, Detail: detail})
+	}
+	return out, nil
+}
+
+func isAutoAOG(heli *helicopter.Helicopter) bool {
+	if heli == nil || !heli.AirOnGround {
+		return false
+	}
+	src := strings.TrimSpace(heli.AOGSource)
+	if src == helicopter.AOGSourceAuto || src == helicopter.AOGSourceComplaint {
+		return true
+	}
+	reason := strings.TrimSpace(heli.AOGReason)
+	return strings.HasPrefix(reason, autoAOGReasonPrefixNextDue) || strings.HasPrefix(reason, autoAOGReasonPrefixComplaint)
+}
+
+func (s *FleetStatusService) complaintAOGReason(ctx context.Context, c complaint.Complaint) string {
+	if c.MELSeverity > complaint.MELSeverityNonMEL {
+		return autoAOGReasonPrefixComplaint + " MEL " + shareddto.MELLabel(c.MELSeverity) + " grace period expired"
+	}
+	if s.complaints != nil {
+		if names, err := s.complaints.ResolveUserNames(ctx, []complaint.Complaint{c}); err == nil {
+			if name := names[string(c.ReportedBy)]; name != "" {
+				return autoAOGReasonPrefixComplaint + " NON-MEL complaint reported by " + name
+			}
+		}
+	}
+	return autoAOGReasonPrefixComplaint + " NON-MEL complaint reported"
+}
+
+func derefFloat(v *float64) float64 {
+	if v == nil {
+		return 0
+	}
+	return *v
+}
+
+func (s *FleetStatusService) resolveFileLinks(
+	ctx context.Context,
+	fleetStatusID []byte,
+	files []fleetstatus.FleetStatusFile,
+	reuse map[string][]byte,
+	actor []byte,
+) ([]fleetstatus.FleetStatusFile, [][]byte, error) {
+	refID, _ := uuidv7.BytesToString(fleetStatusID)
+	out := make([]fleetstatus.FleetStatusFile, 0, len(files))
+	createdIDs := make([][]byte, 0, len(files))
+	for i := range files {
+		f := files[i]
+		f.FleetStatusID = fleetStatusID
+		if len(f.FileID) != 16 {
+			if len(f.FileAttachmentID) == 16 {
+				out = append(out, f)
+			}
+			continue
+		}
+		key, _ := uuidv7.BytesToString(f.FileID)
+		if attID, ok := reuse[key]; ok {
+			f.FileAttachmentID = attID
+			f.FileID = nil
+			out = append(out, f)
+			continue
+		}
+		cat := f.Category
+		att, err := s.attachments.CreateAttachment(ctx, filemanager.CreateAttachmentParams{
+			FileID:   f.FileID,
+			RefType:  FleetStatusFileRefType,
+			RefID:    refID,
+			Category: &cat,
+			ActorID:  actor,
+		})
+		if err != nil {
+			s.rollbackAttachments(ctx, createdIDs)
+			return nil, nil, err
+		}
+		createdIDs = append(createdIDs, att.ID)
+		f.FileAttachmentID = att.ID
+		f.FileID = nil
+		out = append(out, f)
+	}
+	return out, createdIDs, nil
+}
+
+func (s *FleetStatusService) rollbackAttachments(ctx context.Context, ids [][]byte) {
+	for _, id := range ids {
+		_ = s.attachments.DeleteAttachment(ctx, id)
+	}
+}
+
+func (s *FleetStatusService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *FleetStatusService) GetByID(ctx context.Context, id []byte) (*fleetstatus.FleetStatus, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *FleetStatusService) List(ctx context.Context, filter, sort string, limit, offset int) ([]fleetstatus.FleetStatus, int64, error) {
+	return s.repo.List(ctx, filter, normalizeSortByRules(sort,
+		sortField("created_at"),
+		sortField("updated_at"),
+	), limit, offset)
+}
+
+func (s *FleetStatusService) LatestByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]*fleetstatus.FleetStatus, error) {
+	return s.repo.LatestByHelicopterIDs(ctx, helicopterIDs)
+}
+
+func (s *FleetStatusService) RecalculateAOGByHelicopter(ctx context.Context, helicopterID []byte) error {
+	if s == nil || len(helicopterID) != 16 {
+		return nil
+	}
+	latest, err := s.repo.LatestByHelicopterIDs(ctx, [][]byte{helicopterID})
+	if err != nil {
+		return err
+	}
+	row := latest[string(helicopterID)]
+	if row == nil {
+		row = &fleetstatus.FleetStatus{HelicopterID: append([]byte(nil), helicopterID...)}
+	}
+	return s.syncAutomaticAOG(ctx, row)
+}
+
+func (s *FleetStatusService) RecalculateAllAOG(ctx context.Context) (int, error) {
+	if s == nil {
+		return 0, nil
+	}
+	ids, err := s.repo.HelicopterIDsWithFleetStatus(ctx)
+	if err != nil {
+		return 0, err
+	}
+	n := 0
+	failed := 0
+	for _, id := range ids {
+		if err := s.RecalculateAOGByHelicopter(ctx, id); err != nil {
+			failed++
+			idStr, _ := uuidv7.BytesToString(id)
+			slog.WarnContext(ctx, "fleet status AOG recompute failed for helicopter", slog.String("helicopter_id", idStr), slog.Any("error", err))
+			continue
+		}
+		n++
+	}
+	if failed > 0 {
+		slog.WarnContext(ctx, "fleet status AOG recompute completed with failures", slog.Int("succeeded", n), slog.Int("failed", failed))
+	}
+	return n, nil
+}
+
+func (s *FleetStatusService) RecalculateAOGByMission(ctx context.Context, missionID []byte) error {
+	if s == nil || len(missionID) == 0 {
+		return nil
+	}
+	helicopterID, err := s.repo.HelicopterIDByMissionID(ctx, missionID)
+	if err != nil {
+		return err
+	}
+	return s.RecalculateAOGByHelicopter(ctx, helicopterID)
+}
+
+func (s *FleetStatusService) MarkServiced(ctx context.Context, id []byte, servicedAt time.Time, actorID []byte) error {
+	if servicedAt.IsZero() {
+		servicedAt = time.Now().UTC()
+	}
+	if err := s.repo.MarkServiced(ctx, id, servicedAt.UTC(), actorID); err != nil {
+		return err
+	}
+	row, err := s.repo.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+	if row == nil {
+		idStr, _ := uuidv7.BytesToString(id)
+		slog.WarnContext(ctx, "fleet status: not found after mark-serviced, skipping AOG sync", slog.String("id", idStr))
+		return nil
+	}
+	return s.syncAutomaticAOG(ctx, row)
+}
+
+func (s *FleetStatusService) ListServiceHistoryByHelicopterID(ctx context.Context, helicopterID []byte, limit, offset int) ([]fleetstatus.FleetStatusServiceLog, int64, error) {
+	return s.repo.ListServiceHistoryByHelicopterID(ctx, helicopterID, limit, offset)
+}
+
+func (s *FleetStatusService) GetSummaryByHelicopterID(ctx context.Context, helicopterID []byte) (*shareddto.FleetStatusSummary, error) {
+	if s.usage == nil || len(helicopterID) != 16 {
+		return &shareddto.FleetStatusSummary{}, nil
+	}
+	usage, err := s.usage.GetByHelicopterID(ctx, helicopterID)
+	if err != nil {
+		return &shareddto.FleetStatusSummary{}, err
+	}
+	if usage == nil {
+		return &shareddto.FleetStatusSummary{}, nil
+	}
+	hasE1, hasE2 := true, true
+	if s.helicopters != nil {
+		if heli, herr := s.helicopters.GetByID(ctx, helicopterID); herr == nil && heli != nil {
+			hasE1, hasE2 = heli.NR1, heli.NR2
+		}
+	}
+	summary := buildFleetStatusSummary(usage, hasE1, hasE2)
+	return &summary, nil
+}
+
+func EvaluateNextDueSchedules(schedules []fleetstatus.MaintenanceSchedule, hours ComponentHours, hasUsageData, hasEngine1, hasEngine2 bool, now time.Time) ([]NextDueEvaluation, error) {
+	parser := nextdue.NewParser()
+	out := make([]NextDueEvaluation, 0, len(schedules))
+	for i := range schedules {
+		it := strings.TrimSpace(schedules[i].InspectionType)
+		if (it == fleetstatus.InspectionTypeENG1 && !hasEngine1) || (it == fleetstatus.InspectionTypeENG2 && !hasEngine2) {
+			out = append(out, NextDueEvaluation{InspectionType: it})
+			continue
+		}
+		current := hours.Airframe
+		switch it {
+		case fleetstatus.InspectionTypeENG1:
+			current = hours.Engine1
+		case fleetstatus.InspectionTypeENG2:
+			current = hours.Engine2
+		}
+		ev, err := evaluateInspectionDue(parser, it, schedules[i].Due, schedules[i].Ext, current, hasUsageData, now)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, ev)
+	}
+	return out, nil
+}
+
+func evaluateInspectionDue(parser nextdue.Parser, inspectionType, dueRaw, extRaw string, currentHours float64, hasUsageData bool, now time.Time) (NextDueEvaluation, error) {
+	due, err := parser.Parse("due", dueRaw)
+	if err != nil {
+		return NextDueEvaluation{}, err
+	}
+	ext, err := parser.Parse("ext", extRaw)
+	if err != nil {
+		return NextDueEvaluation{}, err
+	}
+	ev := NextDueEvaluation{InspectionType: strings.TrimSpace(inspectionType)}
+
+	limit := due
+	limitIsExt := false
+	if !nextdue.IsUnset(ext) {
+		limit, limitIsExt = ext, true
+	}
+	if nextdue.IsUnset(limit) {
+		return ev, nil
+	}
+
+	switch limit.Kind {
+	case nextdue.ValueKindHours:
+		if !hasUsageData {
+			return ev, nil
+		}
+		if limit.Hours != nil && currentHours > *limit.Hours {
+			ev.AOG = true
+			ev.Reason = nextDueOverdueReason(inspectionType, limitIsExt, true)
+		}
+	case nextdue.ValueKindDate:
+		if limit.Date != nil && nextdue.NormalizeDate(now).After(nextdue.NormalizeDate(*limit.Date)) {
+			ev.AOG = true
+			ev.Reason = nextDueOverdueReason(inspectionType, limitIsExt, false)
+		}
+	}
+	return ev, nil
+}
+
+func nextDueOverdueReason(inspectionType string, isExt, isHours bool) string {
+	it := strings.TrimSpace(inspectionType)
+	switch {
+	case isExt && isHours:
+		return it + " extended hours reached"
+	case isExt:
+		return it + " extended due date reached"
+	case isHours:
+		return it + " due hours reached"
+	default:
+		return it + " due date reached"
+	}
+}
+
+func buildFleetStatusSummary(u *helicopterusage.HelicopterUsage, hasE1, hasE2 bool) shareddto.FleetStatusSummary {
+	airframeHours := u.TotalAirframeHours
+	airframeCycles := float64(u.TotalAirframeCycles)
+	landings := float64(u.TotalLanding)
+	flightReports := float64(u.TotalFlightReport)
+	rotorBrakeCycles := float64(u.TotalRotorBrakeCycle)
+	hookReleases := float64(u.TotalHookRelease)
+	summary := shareddto.FleetStatusSummary{
+		Airframe: shareddto.FleetStatusSummaryAirframe{
+			Hours:  &airframeHours,
+			Cycles: &airframeCycles,
+		},
+		Landings:         &landings,
+		FlightReports:    &flightReports,
+		RotorBrakeCycles: &rotorBrakeCycles,
+		HookReleases:     &hookReleases,
+	}
+	if hasE1 {
+		summary.Engine1 = buildFleetStatusUsageEngine(u.TotalEngine1Hours, u.TotalEngine1GpcNgN1, u.TotalEngine1PtcNfN2, u.TotalEngine1Ccc)
+	}
+	if hasE2 {
+		summary.Engine2 = buildFleetStatusUsageEngine(u.TotalEngine2Hours, u.TotalEngine2GpcNgN1, u.TotalEngine2PtcNfN2, u.TotalEngine2Ccc)
+	}
+	return summary
+}
+
+func buildFleetStatusUsageEngine(hours, gpcNgN1, ptcNfN2, ccc float64) shareddto.FleetStatusSummaryEngine {
+	cccVal := ccc
+	return shareddto.FleetStatusSummaryEngine{
+		Hours:   &hours,
+		GpcNgN1: &gpcNgN1,
+		PtcNfN2: &ptcNfN2,
+		Ccc:     &cccVal,
+	}
+}
diff --git a/internal/service/fleet_status_service_test.go b/internal/service/fleet_status_service_test.go
new file mode 100644
index 0000000..0c58b87
--- /dev/null
+++ b/internal/service/fleet_status_service_test.go
@@ -0,0 +1,267 @@
+package service
+
+import (
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	complaint "wucher/internal/domain/complaint"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	"wucher/internal/domain/helicopter"
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+	"wucher/internal/shared/pkg/nextdue"
+)
+
+func ptr[T any](v T) *T { return &v }
+
+func TestDecideAutoAOG(t *testing.T) {
+	now := time.Date(2026, 6, 17, 8, 0, 0, 0, time.UTC)
+	reasonFn := func(c complaint.Complaint) string { return "complaint:" + c.Description }
+	noComplaints := func() ([]complaint.Complaint, error) { return nil, nil }
+
+	t.Run("next due grounds; complaints not consulted", func(t *testing.T) {
+		loaderCalled := false
+		loader := func() ([]complaint.Complaint, error) { loaderCalled = true; return nil, nil }
+		evals := []NextDueEvaluation{{InspectionType: "A/F", AOG: true, Reason: "A/F due hours reached"}}
+		grounded, reason, source, err := decideAutoAOG(evals, now, loader, reasonFn)
+		if err != nil || !grounded {
+			t.Fatalf("expected grounded, got grounded=%v err=%v", grounded, err)
+		}
+		if source != helicopter.AOGSourceAuto {
+			t.Fatalf("source = %q, want auto", source)
+		}
+		if !strings.HasPrefix(reason, autoAOGReasonPrefixNextDue) {
+			t.Fatalf("reason %q missing next-due prefix", reason)
+		}
+		if loaderCalled {
+			t.Fatal("next-due grounded -> complaints must not be loaded (short-circuit)")
+		}
+	})
+
+	t.Run("complaint grounds when no next due", func(t *testing.T) {
+		classified := now.Add(-time.Hour)
+		loader := func() ([]complaint.Complaint, error) {
+			return []complaint.Complaint{{Description: "blade crack", MELSeverity: complaint.MELSeverityNonMEL, ReportedAt: now.Add(-time.Hour), MELClassifiedAt: &classified}}, nil
+		}
+		grounded, reason, source, err := decideAutoAOG(nil, now, loader, reasonFn)
+		if err != nil || !grounded {
+			t.Fatalf("expected grounded, got grounded=%v err=%v", grounded, err)
+		}
+		if source != helicopter.AOGSourceComplaint {
+			t.Fatalf("source = %q, want complaint", source)
+		}
+		if reason != "complaint:blade crack" {
+			t.Fatalf("reason = %q, want injected complaint reason", reason)
+		}
+	})
+
+	t.Run("nothing grounds", func(t *testing.T) {
+		grounded, _, _, err := decideAutoAOG(nil, now, noComplaints, reasonFn)
+		if err != nil || grounded {
+			t.Fatalf("expected not grounded, got grounded=%v err=%v", grounded, err)
+		}
+	})
+
+	t.Run("loader error propagates", func(t *testing.T) {
+		loader := func() ([]complaint.Complaint, error) { return nil, errors.New("db down") }
+		if _, _, _, err := decideAutoAOG(nil, now, loader, reasonFn); err == nil {
+			t.Fatal("expected loader error to propagate")
+		}
+	})
+}
+
+func assertFloatPtr(t *testing.T, label string, got, want *float64) {
+	t.Helper()
+	if want == nil {
+		if got != nil {
+			t.Errorf("%s = %v, want nil", label, *got)
+		}
+		return
+	}
+	if got == nil {
+		t.Errorf("%s = nil, want %v", label, *want)
+		return
+	}
+	const eps = 1e-9
+	if diff := *got - *want; diff < -eps || diff > eps {
+		t.Errorf("%s = %v, want %v", label, *got, *want)
+	}
+}
+
+func TestBuildFleetStatusSummaryEngineGating(t *testing.T) {
+	u := &helicopterusage.HelicopterUsage{TotalAirframeHours: 10}
+	got := buildFleetStatusSummary(u, false, false)
+	assertFloatPtr(t, "airframe.hours", got.Airframe.Hours, ptr(10.0))
+	if got.Engine1.Hours != nil || got.Engine2.Hours != nil {
+		t.Errorf("expected empty engines, got %+v / %+v", got.Engine1, got.Engine2)
+	}
+}
+
+func TestBuildFleetStatusSummaryFromUsage(t *testing.T) {
+	u := &helicopterusage.HelicopterUsage{
+		TotalLanding:         10,
+		TotalAirframeHours:   3,
+		TotalAirframeCycles:  20,
+		TotalEngine1Hours:    8011,
+		TotalEngine1GpcNgN1:  101,
+		TotalEngine1PtcNfN2:  102,
+		TotalEngine1Ccc:      7,
+		TotalEngine2Hours:    5981,
+		TotalRotorBrakeCycle: 4,
+		TotalHookRelease:     2,
+	}
+	got := buildFleetStatusSummary(u, true, false)
+	assertFloatPtr(t, "airframe.hours", got.Airframe.Hours, ptr(3.0))
+	assertFloatPtr(t, "airframe.cycles", got.Airframe.Cycles, ptr(20.0))
+	assertFloatPtr(t, "engine1.hours", got.Engine1.Hours, ptr(8011.0))
+	assertFloatPtr(t, "engine1.gpc_ng_n1", got.Engine1.GpcNgN1, ptr(101.0))
+	assertFloatPtr(t, "engine1.ptc_nf_n2", got.Engine1.PtcNfN2, ptr(102.0))
+	assertFloatPtr(t, "engine1.ccc", got.Engine1.Ccc, ptr(7.0))
+	if got.Engine2.Hours != nil {
+		t.Errorf("engine 2 absent (NR2 false) -> hours must be nil, got %v", *got.Engine2.Hours)
+	}
+	assertFloatPtr(t, "landings", got.Landings, ptr(10.0))
+	assertFloatPtr(t, "rotor_brake", got.RotorBrakeCycles, ptr(4.0))
+	assertFloatPtr(t, "hook_releases", got.HookReleases, ptr(2.0))
+}
+
+func TestDerefFloat(t *testing.T) {
+	if derefFloat(nil) != 0 {
+		t.Fatal("nil should deref to 0")
+	}
+	if derefFloat(ptr(12.5)) != 12.5 {
+		t.Fatal("deref value mismatch")
+	}
+}
+
+func TestEvaluateNextDueSchedulesPerComponent(t *testing.T) {
+	now := time.Date(2026, 6, 17, 8, 0, 0, 0, time.UTC)
+	schedules := []fleetstatus.MaintenanceSchedule{
+		{InspectionType: fleetstatus.InspectionTypeAF, Due: "100"},
+		{InspectionType: fleetstatus.InspectionTypeENG1, Due: "100", Ext: "120"},
+		{InspectionType: fleetstatus.InspectionTypeENG2, Due: "100"},
+	}
+	hours := ComponentHours{Airframe: 150, Engine1: 110, Engine2: 90}
+
+	// Engine 2 present: ENG2 (90 < 100) not overdue; A/F (150>100) overdue; ENG1 (110<120 ext) not overdue.
+	evals, err := EvaluateNextDueSchedules(schedules, hours, true, true, true, now)
+	if err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	got := map[string]bool{}
+	for _, e := range evals {
+		got[e.InspectionType] = e.AOG
+	}
+	if !got[fleetstatus.InspectionTypeAF] {
+		t.Error("A/F should be overdue (150 > 100)")
+	}
+	if got[fleetstatus.InspectionTypeENG1] {
+		t.Error("ENG1 should NOT be overdue (110 < 120 ext)")
+	}
+	if got[fleetstatus.InspectionTypeENG2] {
+		t.Error("ENG2 should NOT be overdue (90 < 100)")
+	}
+
+	// Engine 2 absent: an ENG2 schedule must be skipped even if hours exceed the limit.
+	hours.Engine2 = 999
+	evals2, err := EvaluateNextDueSchedules(schedules, hours, true, true, false, now)
+	if err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	for _, e := range evals2 {
+		if e.InspectionType == fleetstatus.InspectionTypeENG2 && e.AOG {
+			t.Error("absent engine 2 must not ground the aircraft")
+		}
+	}
+}
+
+func TestEvaluateInspectionDueHours(t *testing.T) {
+	now := time.Date(2026, 6, 17, 8, 0, 0, 0, time.UTC)
+	p := nextdue.NewParser()
+	cases := []struct {
+		name    string
+		due     string
+		ext     string
+		current float64
+		wantAOG bool
+	}{
+		{name: "below due", due: "100", ext: "", current: 99, wantAOG: false},
+		{name: "exactly at due not overdue", due: "100", ext: "", current: 100, wantAOG: false},
+		{name: "past due", due: "100", ext: "", current: 101, wantAOG: true},
+		{name: "ext extends beyond due", due: "100", ext: "120", current: 110, wantAOG: false},
+		{name: "past ext", due: "100", ext: "120", current: 121, wantAOG: true},
+		{name: "ext zero treated as unset", due: "100", ext: "0", current: 101, wantAOG: true},
+		{name: "unset", due: "", ext: "", current: 9999, wantAOG: false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			ev, err := evaluateInspectionDue(p, "A/F", tc.due, tc.ext, tc.current, true, now)
+			if err != nil {
+				t.Fatalf("unexpected err: %v", err)
+			}
+			if ev.AOG != tc.wantAOG {
+				t.Fatalf("AOG = %v (reason %q), want %v", ev.AOG, ev.Reason, tc.wantAOG)
+			}
+		})
+	}
+}
+
+func TestEvaluateInspectionDueDate(t *testing.T) {
+	now := time.Date(2026, 6, 17, 8, 0, 0, 0, time.UTC)
+	p := nextdue.NewParser()
+	cases := []struct {
+		name    string
+		due     string
+		ext     string
+		wantAOG bool
+	}{
+		{name: "due date passed", due: "2026-06-10", ext: "", wantAOG: true},
+		{name: "due date today not yet overdue", due: "2026-06-17", ext: "", wantAOG: false},
+		{name: "due date future", due: "2026-06-20", ext: "", wantAOG: false},
+		{name: "ext date extends beyond passed due", due: "2026-06-10", ext: "2026-06-25", wantAOG: false},
+		{name: "past ext date", due: "2026-06-10", ext: "2026-06-12", wantAOG: true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			ev, err := evaluateInspectionDue(p, "MAIN1", tc.due, tc.ext, 0, true, now)
+			if err != nil {
+				t.Fatalf("unexpected err: %v", err)
+			}
+			if ev.AOG != tc.wantAOG {
+				t.Fatalf("AOG = %v (reason %q), want %v", ev.AOG, ev.Reason, tc.wantAOG)
+			}
+		})
+	}
+}
+
+func TestEvaluateInspectionDueInvalid(t *testing.T) {
+	p := nextdue.NewParser()
+	if _, err := evaluateInspectionDue(p, "A/F", "100 FH", "", 0, true, time.Now()); err == nil {
+		t.Fatal("expected parse error for due '100 FH'")
+	}
+	if _, err := evaluateInspectionDue(p, "A/F", "100", "bad ext", 0, true, time.Now()); err == nil {
+		t.Fatal("expected parse error for ext 'bad ext'")
+	}
+}
+
+func TestEvaluateInspectionDueNoUsageData(t *testing.T) {
+	p := nextdue.NewParser()
+	now := time.Date(2026, 6, 17, 8, 0, 0, 0, time.UTC)
+
+	ev, err := evaluateInspectionDue(p, "A/F", "100", "", 150, false, now)
+	if err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	if ev.AOG {
+		t.Fatal("hours due must not ground when there is no usage data yet")
+	}
+
+	evDate, err := evaluateInspectionDue(p, "MAIN1", "2026-06-10", "", 0, false, now)
+	if err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	if !evDate.AOG {
+		t.Fatal("a passed date due should still ground regardless of usage data")
+	}
+}
diff --git a/internal/service/fleet_status_stateful_test.go b/internal/service/fleet_status_stateful_test.go
new file mode 100644
index 0000000..b8662bc
--- /dev/null
+++ b/internal/service/fleet_status_stateful_test.go
@@ -0,0 +1,286 @@
+package service
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	fleethistory "wucher/internal/domain/fleet_history"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	"wucher/internal/domain/helicopter"
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+)
+
+type stubFleetRepo struct {
+	latest      map[string]*fleetstatus.FleetStatus
+	missionHeli []byte
+	created     *fleetstatus.FleetStatus
+	updated     *fleetstatus.FleetStatus
+	deletedID   []byte
+	servicedID  []byte
+}
+
+func (s *stubFleetRepo) Create(_ context.Context, row *fleetstatus.FleetStatus) error {
+	s.created = row
+	return nil
+}
+func (s *stubFleetRepo) Update(_ context.Context, row *fleetstatus.FleetStatus) error {
+	s.updated = row
+	return nil
+}
+func (s *stubFleetRepo) Delete(_ context.Context, id, _ []byte) error { s.deletedID = id; return nil }
+func (s *stubFleetRepo) GetByID(_ context.Context, _ []byte) (*fleetstatus.FleetStatus, error) {
+	return s.created, nil
+}
+func (s *stubFleetRepo) List(_ context.Context, _, _ string, _, _ int) ([]fleetstatus.FleetStatus, int64, error) {
+	return nil, 0, nil
+}
+func (s *stubFleetRepo) LatestByHelicopterIDs(_ context.Context, _ [][]byte) (map[string]*fleetstatus.FleetStatus, error) {
+	return s.latest, nil
+}
+func (s *stubFleetRepo) MarkServiced(_ context.Context, id []byte, _ time.Time, _ []byte) error {
+	s.servicedID = id
+	return nil
+}
+func (s *stubFleetRepo) ListServiceHistoryByHelicopterID(_ context.Context, _ []byte, _, _ int) ([]fleetstatus.FleetStatusServiceLog, int64, error) {
+	return nil, 0, nil
+}
+func (s *stubFleetRepo) HelicopterIDByMissionID(_ context.Context, _ []byte) ([]byte, error) {
+	return s.missionHeli, nil
+}
+func (s *stubFleetRepo) HelicopterIDsWithFleetStatus(_ context.Context) ([][]byte, error) {
+	out := make([][]byte, 0, len(s.latest))
+	for k := range s.latest {
+		out = append(out, []byte(k))
+	}
+	return out, nil
+}
+
+type stubFleetHelis struct {
+	heli    *helicopter.Helicopter
+	updated *helicopter.Helicopter
+}
+
+func (s *stubFleetHelis) GetByID(_ context.Context, _ []byte) (*helicopter.Helicopter, error) {
+	return s.heli, nil
+}
+func (s *stubFleetHelis) Update(_ context.Context, h *helicopter.Helicopter) error {
+	s.updated = h
+	return nil
+}
+
+type stubFleetUsage struct {
+	usage *helicopterusage.HelicopterUsage
+}
+
+func (s *stubFleetUsage) GetByHelicopterID(_ context.Context, _ []byte) (*helicopterusage.HelicopterUsage, error) {
+	return s.usage, nil
+}
+
+func (s *stubFleetUsage) ReviseManualTotals(_ context.Context, _ []byte, _ helicopterusage.ManualSummaryInput, _ []byte) error {
+	return nil
+}
+
+func fleetUsage(airframeHours float64) *stubFleetUsage {
+	return &stubFleetUsage{usage: &helicopterusage.HelicopterUsage{TotalAirframeHours: airframeHours}}
+}
+
+type stubHistoryRepo struct{ recorded int }
+
+func (s *stubHistoryRepo) Create(_ context.Context, _ *fleethistory.FleetHistory) error {
+	s.recorded++
+	return nil
+}
+func (s *stubHistoryRepo) ListByHelicopter(_ context.Context, _ []byte, _, _ int) ([]fleethistory.FleetHistory, int64, error) {
+	return nil, 0, nil
+}
+func (s *stubHistoryRepo) HelicopterIDByInspection(_ context.Context, _ []byte) ([]byte, error) {
+	return nil, nil
+}
+
+func newHistory() *FleetHistoryService { return NewFleetHistoryService(&stubHistoryRepo{}) }
+
+func heliID() []byte { return []byte("0123456789abcdef") }
+
+func fleetWith(schedDue string) *fleetstatus.FleetStatus {
+	return &fleetstatus.FleetStatus{
+		ID:           []byte("fedcba9876543210"),
+		HelicopterID: heliID(),
+		MaintenanceSchedules: []fleetstatus.MaintenanceSchedule{
+			{InspectionType: fleetstatus.InspectionTypeAF, Due: schedDue},
+		},
+	}
+}
+
+func TestSyncAutomaticAOG_SetWhenOverdue(t *testing.T) {
+	row := fleetWith("100")
+	repo := &stubFleetRepo{
+		latest: map[string]*fleetstatus.FleetStatus{string(heliID()): row},
+	}
+	helis := &stubFleetHelis{heli: &helicopter.Helicopter{ID: heliID(), NR1: true, NR2: true}}
+	svc := NewFleetStatusService(repo, nil, helis, nil).WithHistory(newHistory()).WithUsage(fleetUsage(150))
+
+	if err := svc.RecalculateAOGByHelicopter(context.Background(), heliID()); err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	if helis.updated == nil || !helis.updated.AirOnGround {
+		t.Fatal("expected helicopter set AOG (150h > 100h due)")
+	}
+	if helis.updated.AOGSource != helicopter.AOGSourceAuto {
+		t.Fatalf("expected auto AOG source, got %q", helis.updated.AOGSource)
+	}
+}
+
+func TestSyncAutomaticAOG_NotOverdueNotGrounded(t *testing.T) {
+	row := fleetWith("100")
+	repo := &stubFleetRepo{
+		latest: map[string]*fleetstatus.FleetStatus{string(heliID()): row},
+	}
+	helis := &stubFleetHelis{heli: &helicopter.Helicopter{ID: heliID(), NR1: true, NR2: true}}
+	svc := NewFleetStatusService(repo, nil, helis, nil).WithUsage(fleetUsage(50))
+
+	if err := svc.RecalculateAOGByHelicopter(context.Background(), heliID()); err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	if helis.updated != nil {
+		t.Fatal("not overdue and not previously auto-AOG: should not touch helicopter")
+	}
+}
+
+func TestSyncAutomaticAOG_NoUsageDataNotGrounded(t *testing.T) {
+	row := fleetWith("100")
+	repo := &stubFleetRepo{
+		latest: map[string]*fleetstatus.FleetStatus{string(heliID()): row},
+	}
+	helis := &stubFleetHelis{heli: &helicopter.Helicopter{ID: heliID(), NR1: true, NR2: true}}
+	svc := NewFleetStatusService(repo, nil, helis, nil).WithUsage(&stubFleetUsage{usage: nil})
+
+	if err := svc.RecalculateAOGByHelicopter(context.Background(), heliID()); err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	if helis.updated != nil {
+		t.Fatal("fresh aircraft with no usage data must not be auto-AOG on an hours due")
+	}
+}
+
+func TestSyncAutomaticAOG_ClearWhenNoLongerOverdue(t *testing.T) {
+	row := fleetWith("100")
+	repo := &stubFleetRepo{
+		latest: map[string]*fleetstatus.FleetStatus{string(heliID()): row},
+	}
+	helis := &stubFleetHelis{heli: &helicopter.Helicopter{
+		ID: heliID(), NR1: true, NR2: true,
+		AirOnGround: true, AOGSource: helicopter.AOGSourceAuto, AOGReason: "[auto_next_due] A/F due hours reached",
+	}}
+	svc := NewFleetStatusService(repo, nil, helis, nil).WithHistory(newHistory()).WithUsage(fleetUsage(50))
+
+	if err := svc.RecalculateAOGByHelicopter(context.Background(), heliID()); err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	if helis.updated == nil || helis.updated.AirOnGround {
+		t.Fatal("auto-AOG should be cleared once no longer overdue")
+	}
+}
+
+func TestFleetStatusCreateUpdateGet(t *testing.T) {
+	repo := &stubFleetRepo{}
+	svc := NewFleetStatusService(repo, nil, nil, nil) // attachments nil -> simple path
+	ctx := context.Background()
+	row := &fleetstatus.FleetStatus{HelicopterID: heliID()}
+	if err := svc.Create(ctx, row); err != nil || repo.created != row {
+		t.Fatalf("Create: %v", err)
+	}
+	if err := svc.Update(ctx, row); err != nil || repo.updated != row {
+		t.Fatalf("Update: %v", err)
+	}
+	if _, err := svc.GetByID(ctx, heliID()); err != nil {
+		t.Fatalf("GetByID: %v", err)
+	}
+}
+
+func TestRecalculateAOGByMission(t *testing.T) {
+	row := fleetWith("100")
+	repo := &stubFleetRepo{
+		latest:      map[string]*fleetstatus.FleetStatus{string(heliID()): row},
+		missionHeli: heliID(),
+	}
+	helis := &stubFleetHelis{heli: &helicopter.Helicopter{ID: heliID(), NR1: true, NR2: true}}
+	svc := NewFleetStatusService(repo, nil, helis, nil).WithUsage(fleetUsage(150))
+
+	if err := svc.RecalculateAOGByMission(context.Background(), []byte("mission0123456789")); err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	if helis.updated == nil || !helis.updated.AirOnGround {
+		t.Fatal("mission recalc should set AOG")
+	}
+
+	// empty mission id -> no-op
+	if err := svc.RecalculateAOGByMission(context.Background(), nil); err != nil {
+		t.Fatalf("nil mission err: %v", err)
+	}
+	// no fleet status for helicopter -> no-op
+	if err := NewFleetStatusService(&stubFleetRepo{}, nil, helis, nil).RecalculateAOGByHelicopter(context.Background(), heliID()); err != nil {
+		t.Fatalf("no-fleet-status err: %v", err)
+	}
+}
+
+func TestRecalculateAllAOG(t *testing.T) {
+	row := fleetWith("100")
+	repo := &stubFleetRepo{
+		latest: map[string]*fleetstatus.FleetStatus{string(heliID()): row},
+	}
+	helis := &stubFleetHelis{heli: &helicopter.Helicopter{ID: heliID(), NR1: true, NR2: true}}
+	svc := NewFleetStatusService(repo, nil, helis, nil).WithUsage(fleetUsage(150))
+
+	n, err := svc.RecalculateAllAOG(context.Background())
+	if err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	if n != 1 {
+		t.Fatalf("expected 1 helicopter recomputed, got %d", n)
+	}
+	if helis.updated == nil || !helis.updated.AirOnGround {
+		t.Fatal("overdue helicopter should have been set AOG by the sweep")
+	}
+}
+
+func TestGetSummaryByHelicopterID_EngineGating(t *testing.T) {
+	usage := &stubFleetUsage{usage: &helicopterusage.HelicopterUsage{
+		TotalAirframeHours: 6620,
+		TotalEngine1Hours:  8011,
+		TotalEngine2Hours:  5981,
+	}}
+	helis := &stubFleetHelis{heli: &helicopter.Helicopter{ID: heliID(), NR1: true, NR2: false}}
+	svc := NewFleetStatusService(&stubFleetRepo{}, nil, helis, nil).WithUsage(usage)
+
+	summary, err := svc.GetSummaryByHelicopterID(context.Background(), heliID())
+	if err != nil {
+		t.Fatalf("err: %v", err)
+	}
+	assertFloatPtr(t, "airframe", summary.Airframe.Hours, ptr(6620.0))
+	assertFloatPtr(t, "engine1", summary.Engine1.Hours, ptr(8011.0))
+	if summary.Engine2.Hours != nil {
+		t.Fatal("engine 2 absent (NR2 false) -> hours must be nil")
+	}
+}
+
+func TestFleetStatusSimpleDelegators(t *testing.T) {
+	repo := &stubFleetRepo{}
+	svc := NewFleetStatusService(repo, nil, nil, nil).WithHistory(nil)
+	ctx := context.Background()
+	if err := svc.Delete(ctx, []byte("id"), nil); err != nil || string(repo.deletedID) != "id" {
+		t.Fatalf("Delete: %v", err)
+	}
+	if _, _, err := svc.List(ctx, "", "", 0, 0); err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	if _, err := svc.LatestByHelicopterIDs(ctx, [][]byte{heliID()}); err != nil {
+		t.Fatalf("LatestByHelicopterIDs: %v", err)
+	}
+	if _, _, err := svc.ListServiceHistoryByHelicopterID(ctx, heliID(), 0, 0); err != nil {
+		t.Fatalf("ListServiceHistory: %v", err)
+	}
+	if err := svc.MarkServiced(ctx, []byte("ms"), time.Time{}, nil); err != nil || string(repo.servicedID) != "ms" {
+		t.Fatalf("MarkServiced: %v", err)
+	}
+}
diff --git a/internal/service/fleet_status_update_test.go b/internal/service/fleet_status_update_test.go
new file mode 100644
index 0000000..a4d01e6
--- /dev/null
+++ b/internal/service/fleet_status_update_test.go
@@ -0,0 +1,95 @@
+package service
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	"wucher/internal/domain/helicopter"
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+	"wucher/internal/repository/mysql"
+)
+
+// TestFleetStatusUpdateAcceptsNegativeSummaryAndBareSchedule guards the full service path
+// behind PATCH /fleet-status/update/{id}: negative summary values + an A/F schedule with
+// empty type/due/ext must persist (incl. syncAutomaticAOG, which the repo-level test skips).
+func TestFleetStatusUpdateAcceptsNegativeSummaryAndBareSchedule(t *testing.T) {
+	dsn := fmt.Sprintf("file:fleet_update_repro_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{NowFunc: func() time.Time { return time.Now().UTC() }})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(
+		&filemanager.Folder{}, &filemanager.File{}, &filemanager.Attachment{},
+		&helicopter.Helicopter{},
+		&fleetstatus.FleetStatus{}, &fleetstatus.MaintenanceSchedule{}, &fleetstatus.FleetStatusFile{},
+		&helicopterusage.HelicopterUsage{},
+	); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	ctx := context.Background()
+
+	heliRepo := mysql.NewHelicopterRepository(db)
+	heli := &helicopter.Helicopter{Designation: "H1", Identifier: "PK-H1", Type: "Twin", NR1: true, NR2: true}
+	if err := heliRepo.Create(ctx, heli); err != nil {
+		t.Fatalf("create heli: %v", err)
+	}
+	fsRepo := mysql.NewFleetStatusRepository(db)
+	fs := &fleetstatus.FleetStatus{HelicopterID: heli.ID, Status: fleetstatus.StatusActive}
+	if err := fsRepo.Create(ctx, fs); err != nil {
+		t.Fatalf("create fs: %v", err)
+	}
+
+	usageSvc := NewHelicopterUsageService(mysql.NewHelicopterUsageRepository(db))
+	svc := NewFleetStatusService(fsRepo, nil, NewHelicopterService(heliRepo), nil).WithUsage(usageSvc)
+
+	// Handler builds this row from the patch: full-replace schedules with one A/F entry.
+	fs.MaintenanceSchedules = []fleetstatus.MaintenanceSchedule{
+		{FleetStatusID: fs.ID, InspectionType: "A/F", Type: "", Due: "", Ext: ""},
+	}
+	fs.UpdatedBy = heli.ID // any actor
+	if err := svc.Update(ctx, fs); err != nil {
+		t.Fatalf("REPRO: FleetStatusService.Update FAILED: %v", err)
+	}
+	t.Log("FleetStatusService.Update OK (incl syncAutomaticAOG)")
+
+	f := func(v float64) *float64 { return &v }
+	if err := svc.ReviseSummary(ctx, heli.ID, helicopterusage.ManualSummaryInput{
+		AirframeHours: f(1234), AirframeCycles: f(-1),
+		Engine1Hours: f(1234), Engine1GpcNgN1: f(23.23), Engine1PtcNfN2: f(23.59), Engine1Ccc: f(-8),
+		Engine2Hours: f(234), Engine2GpcNgN1: f(123), Engine2PtcNfN2: f(1230), Engine2Ccc: f(123),
+		Landing: f(1), FlightReport: f(1), HookRelease: f(1), RotorBrakeCycle: f(1),
+	}, heli.ID); err != nil {
+		t.Fatalf("REPRO: ReviseSummary FAILED: %v", err)
+	}
+	got, _ := usageSvc.GetByHelicopterID(ctx, heli.ID)
+	t.Logf("ReviseSummary OK: cycles=%v ccc1=%v ccc2=%v", got.TotalAirframeCycles, got.TotalEngine1Ccc, got.TotalEngine2Ccc)
+
+	// The fleet GET reads the summary via GetSummaryByHelicopterID — verify it reflects the patch.
+	summary, err := svc.GetSummaryByHelicopterID(ctx, heli.ID)
+	if err != nil {
+		t.Fatalf("GetSummaryByHelicopterID: %v", err)
+	}
+	if summary.Airframe.Hours == nil || *summary.Airframe.Hours != 1234 {
+		t.Fatalf("summary airframe hours = %v, want 1234 (patch not reflected)", summary.Airframe.Hours)
+	}
+	if summary.Engine1.Hours == nil || *summary.Engine1.Hours != 1234 {
+		t.Fatalf("summary engine1 hours = %v, want 1234", summary.Engine1.Hours)
+	}
+
+	// Second PATCH with a NEW value — the "ga terganti" (value doesn't change) scenario.
+	if err := svc.ReviseSummary(ctx, heli.ID, helicopterusage.ManualSummaryInput{AirframeHours: f(9999)}, heli.ID); err != nil {
+		t.Fatalf("second ReviseSummary: %v", err)
+	}
+	summary2, _ := svc.GetSummaryByHelicopterID(ctx, heli.ID)
+	if summary2.Airframe.Hours == nil || *summary2.Airframe.Hours != 9999 {
+		t.Fatalf("second patch: airframe hours = %v, want 9999 (VALUE DID NOT CHANGE)", summary2.Airframe.Hours)
+	}
+	t.Logf("both patches reflected in GET summary: first af.hours=1234, second=%v", *summary2.Airframe.Hours)
+}
diff --git a/internal/service/flight_data_service.go b/internal/service/flight_data_service.go
new file mode 100644
index 0000000..057e7b7
--- /dev/null
+++ b/internal/service/flight_data_service.go
@@ -0,0 +1,332 @@
+package service
+
+import (
+	"context"
+	"strings"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	flightdomain "wucher/internal/domain/flight"
+	flightdata "wucher/internal/domain/flight_data"
+	fmreport "wucher/internal/domain/fm_report"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type aogRecalculator interface {
+	RecalculateAOGByMission(ctx context.Context, missionID []byte) error
+}
+
+type missionFlightResolver interface {
+	FlightIDByMissionID(ctx context.Context, missionID []byte) ([]byte, error)
+}
+
+type fmReportLookup interface {
+	GetByFlightID(ctx context.Context, flightID []byte) (*fmreport.Report, error)
+}
+
+type flightLookup interface {
+	GetByID(context.Context, []byte) (*flightdomain.Flight, error)
+}
+
+type afterFlightInspectionLookup interface {
+	GetByFlightInspectionID(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error)
+}
+
+type FlightDataService struct {
+	repo        flightdata.Repository
+	aog         aogRecalculator
+	mission     missionFlightResolver
+	flight      flightLookup
+	fmReports   fmReportLookup
+	afterFlight afterFlightInspectionLookup
+}
+
+func NewFlightDataService(repo flightdata.Repository) *FlightDataService {
+	return &FlightDataService{repo: repo}
+}
+
+func (s *FlightDataService) WithAOGRecalculator(a aogRecalculator) *FlightDataService {
+	s.aog = a
+	return s
+}
+
+func (s *FlightDataService) WithMissionResolver(resolver missionFlightResolver) *FlightDataService {
+	s.mission = resolver
+	return s
+}
+
+func (s *FlightDataService) WithFlightLookup(lookup flightLookup) *FlightDataService {
+	s.flight = lookup
+	return s
+}
+
+func (s *FlightDataService) WithFMReportLookup(lookup fmReportLookup) *FlightDataService {
+	s.fmReports = lookup
+	return s
+}
+
+func (s *FlightDataService) WithAfterFlightInspectionLookup(lookup afterFlightInspectionLookup) *FlightDataService {
+	s.afterFlight = lookup
+	return s
+}
+
+func (s *FlightDataService) recalcAOG(ctx context.Context, missionID []byte) {
+	if s.aog == nil || len(missionID) == 0 {
+		return
+	}
+	_ = s.aog.RecalculateAOGByMission(ctx, missionID)
+}
+
+func (s *FlightDataService) Create(ctx context.Context, row *flightdata.FlightData) error {
+	if row == nil {
+		return flightdata.ErrRequired
+	}
+	if err := validateFlightDataLocationPair(row.FromICAOID, row.FromHospitalID, true); err != nil {
+		return err
+	}
+	if err := validateFlightDataLocationPair(row.ToICAOID, row.ToHospitalID, false); err != nil {
+		return err
+	}
+	if err := s.canCreateForMission(ctx, row.MissionID); err != nil {
+		return err
+	}
+	row.Status = flightdata.StatusInProgress
+	if err := s.repo.Create(ctx, row); err != nil {
+		return err
+	}
+	s.recalcAOG(ctx, row.MissionID)
+	if err := s.syncStatus(ctx, row.ID); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (s *FlightDataService) CreatePlaceholder(ctx context.Context, row *flightdata.FlightData) error {
+	if row == nil {
+		return flightdata.ErrRequired
+	}
+	if err := s.canCreateForMission(ctx, row.MissionID); err != nil {
+		return err
+	}
+	row.Status = flightdata.StatusInProgress
+	if err := s.repo.Create(ctx, row); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (s *FlightDataService) Update(ctx context.Context, row *flightdata.FlightData) error {
+	if row == nil {
+		return flightdata.ErrRequired
+	}
+	if err := validateFlightDataLocationPair(row.FromICAOID, row.FromHospitalID, true); err != nil {
+		return err
+	}
+	if err := validateFlightDataLocationPair(row.ToICAOID, row.ToHospitalID, false); err != nil {
+		return err
+	}
+	if err := s.ensureEditable(ctx, row.MissionID); err != nil {
+		return err
+	}
+	if err := s.repo.Update(ctx, row); err != nil {
+		return err
+	}
+	s.recalcAOG(ctx, row.MissionID)
+	if err := s.syncStatus(ctx, row.ID); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (s *FlightDataService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	var missionID []byte
+	if row, err := s.repo.GetByID(ctx, id); err == nil && row != nil {
+		missionID = row.MissionID
+		if err := s.ensureAfterFlightInspectionNotLocked(ctx, missionID); err != nil {
+			return err
+		}
+		if err := s.ensureEditable(ctx, missionID); err != nil {
+			return err
+		}
+	}
+	if err := s.repo.Delete(ctx, id, deletedBy); err != nil {
+		return err
+	}
+	s.recalcAOG(ctx, missionID)
+	return nil
+}
+
+func (s *FlightDataService) GetByID(ctx context.Context, id []byte) (*flightdata.FlightData, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *FlightDataService) GetByFlightID(ctx context.Context, flightID []byte) (*flightdata.FlightData, error) {
+	return s.repo.GetByFlightID(ctx, flightID)
+}
+
+func (s *FlightDataService) GetByMissionID(ctx context.Context, missionID []byte) (*flightdata.FlightData, error) {
+	return s.repo.GetByMissionID(ctx, missionID)
+}
+
+func (s *FlightDataService) ListByMissionID(ctx context.Context, missionID []byte) ([]flightdata.FlightData, error) {
+	return s.repo.ListByMissionID(ctx, missionID)
+}
+
+func (s *FlightDataService) List(ctx context.Context, date string, missionID, flightDataID []byte, limit, offset int) ([]flightdata.FlightData, int64, error) {
+	return s.repo.List(ctx, date, missionID, flightDataID, limit, offset)
+}
+
+func (s *FlightDataService) GetSPODetailsByFlightDataID(ctx context.Context, flightDataID []byte) (*flightdata.SPODetails, error) {
+	return s.repo.GetSPODetailsByFlightDataID(ctx, flightDataID)
+}
+
+func (s *FlightDataService) UpsertSPODetails(ctx context.Context, flightDataID []byte, data *flightdata.SPOUpsertData) error {
+	return s.repo.UpsertSPODetails(ctx, flightDataID, data)
+}
+
+func (s *FlightDataService) CanCreateForMission(ctx context.Context, missionID []byte) error {
+	return s.canCreateForMission(ctx, missionID)
+}
+
+func (s *FlightDataService) canCreateForMission(ctx context.Context, missionID []byte) error {
+	if err := s.ensureAfterFlightInspectionNotLocked(ctx, missionID); err != nil {
+		return err
+	}
+	flightID, err := s.flightIDByMissionID(ctx, missionID)
+	if err != nil {
+		return err
+	}
+	if len(flightID) != 16 || s.fmReports == nil {
+		return nil
+	}
+	report, err := s.fmReports.GetByFlightID(ctx, flightID)
+	if err != nil {
+		return err
+	}
+	if report != nil {
+		return flightdata.ErrCreateBlocked
+	}
+	return nil
+}
+
+func (s *FlightDataService) ensureEditable(ctx context.Context, missionID []byte) error {
+	flightID, err := s.flightIDByMissionID(ctx, missionID)
+	if err != nil {
+		return err
+	}
+	if len(flightID) != 16 || s.fmReports == nil {
+		return nil
+	}
+	report, err := s.fmReports.GetByFlightID(ctx, flightID)
+	if err != nil {
+		return err
+	}
+	if report != nil && report.CompletedAt != nil {
+		return flightdata.ErrLocked
+	}
+	return nil
+}
+
+func (s *FlightDataService) ensureAfterFlightInspectionNotLocked(ctx context.Context, missionID []byte) error {
+	flightID, err := s.flightIDByMissionID(ctx, missionID)
+	if err != nil {
+		return err
+	}
+	if len(flightID) != 16 || s.flight == nil || s.afterFlight == nil {
+		return nil
+	}
+	flightRow, err := s.flight.GetByID(ctx, flightID)
+	if err != nil {
+		return err
+	}
+	if flightRow == nil || flightRow.Takeover == nil || flightRow.Takeover.ReserveAc == nil || len(flightRow.Takeover.ReserveAc.InspectionID) != 16 {
+		return nil
+	}
+	afterRow, err := s.afterFlight.GetByFlightInspectionID(ctx, flightRow.Takeover.ReserveAc.InspectionID)
+	if err != nil {
+		return err
+	}
+	if afterRow != nil {
+		return flightdata.ErrLockedAfterFlightInspection
+	}
+	return nil
+}
+
+func (s *FlightDataService) flightIDByMissionID(ctx context.Context, missionID []byte) ([]byte, error) {
+	if len(missionID) != 16 || s.mission == nil {
+		return nil, nil
+	}
+	flightID, err := s.mission.FlightIDByMissionID(ctx, missionID)
+	if err != nil {
+		return nil, err
+	}
+	return flightID, nil
+}
+
+func (s *FlightDataService) AttachmentReferenceType() string {
+	return sharedconst.FlightDataResourceType
+}
+
+func (s *FlightDataService) AttachmentReferenceID(row *flightdata.FlightData) string {
+	if row == nil {
+		return ""
+	}
+	id, err := uuidv7.BytesToString(row.ID)
+	if err != nil {
+		return ""
+	}
+	return id
+}
+
+func (s *FlightDataService) syncStatus(ctx context.Context, id []byte) error {
+	if len(id) != 16 {
+		return nil
+	}
+
+	row, err := s.repo.GetByID(ctx, id)
+	if err != nil || row == nil {
+		return err
+	}
+	if row.Mission == nil && len(row.MissionID) == 16 {
+		if byMissionID, lookupErr := s.repo.GetByMissionID(ctx, row.MissionID); lookupErr == nil && byMissionID != nil {
+			row = byMissionID
+		}
+	}
+
+	details, err := s.loadSPODetails(ctx, row)
+	if err != nil {
+		return err
+	}
+	desired := flightdata.DeriveStatus(row, details)
+	if strings.EqualFold(strings.TrimSpace(row.Status), desired) {
+		return nil
+	}
+	row.Status = desired
+	return s.repo.Update(ctx, row)
+}
+
+func (s *FlightDataService) loadSPODetails(ctx context.Context, row *flightdata.FlightData) (*flightdata.SPODetails, error) {
+	if row == nil || row.Mission == nil {
+		return nil, nil
+	}
+	if !strings.EqualFold(strings.TrimSpace(row.Mission.Type), sharedconst.MissionTypeSPO) {
+		return nil, nil
+	}
+	details, err := s.repo.GetSPODetailsByFlightDataID(ctx, row.ID)
+	if err != nil {
+		return nil, err
+	}
+	return details, nil
+}
+
+func validateFlightDataLocationPair(a, b []byte, isOrigin bool) error {
+	hasA := len(a) > 0
+	hasB := len(b) > 0
+	if hasA == hasB {
+		if isOrigin {
+			return flightdata.ErrOriginLocationReference
+		}
+		return flightdata.ErrDestinationLocationReference
+	}
+	return nil
+}
diff --git a/internal/service/flight_data_service_test.go b/internal/service/flight_data_service_test.go
new file mode 100644
index 0000000..5a6161f
--- /dev/null
+++ b/internal/service/flight_data_service_test.go
@@ -0,0 +1,468 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	flightdomain "wucher/internal/domain/flight"
+	flightdata "wucher/internal/domain/flight_data"
+	fmreport "wucher/internal/domain/fm_report"
+	missiondomain "wucher/internal/domain/mission"
+	reserveac "wucher/internal/domain/reserve_ac"
+	takeoverdomain "wucher/internal/domain/takeover"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type flightDataRepoStub struct {
+	createFn                func(context.Context, *flightdata.FlightData) error
+	updateFn                func(context.Context, *flightdata.FlightData) error
+	getByIDFn               func(context.Context, []byte) (*flightdata.FlightData, error)
+	getByMissionIDFn        func(context.Context, []byte) (*flightdata.FlightData, error)
+	getSPODetailsByFlightID func(context.Context, []byte) (*flightdata.SPODetails, error)
+}
+
+type missionResolverStub struct {
+	flightID []byte
+	err      error
+}
+
+func (m missionResolverStub) FlightIDByMissionID(context.Context, []byte) ([]byte, error) {
+	return append([]byte(nil), m.flightID...), m.err
+}
+
+type fmReportLookupStub struct {
+	report *fmreport.Report
+	err    error
+}
+
+type flightLookupStub struct {
+	flight *flightdomain.Flight
+	err    error
+}
+
+type afterFlightInspectionLookupStub struct {
+	row *afterflightinspection.AfterFlightInspection
+	err error
+}
+
+func (s fmReportLookupStub) GetByFlightID(context.Context, []byte) (*fmreport.Report, error) {
+	return s.report, s.err
+}
+
+func (s flightLookupStub) GetByID(context.Context, []byte) (*flightdomain.Flight, error) {
+	return s.flight, s.err
+}
+
+func (s afterFlightInspectionLookupStub) GetByFlightInspectionID(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+	return s.row, s.err
+}
+
+func (r *flightDataRepoStub) Create(ctx context.Context, row *flightdata.FlightData) error {
+	if r.createFn != nil {
+		return r.createFn(ctx, row)
+	}
+	return nil
+}
+
+func (r *flightDataRepoStub) Update(ctx context.Context, row *flightdata.FlightData) error {
+	if r.updateFn != nil {
+		return r.updateFn(ctx, row)
+	}
+	return nil
+}
+
+func (r *flightDataRepoStub) Delete(context.Context, []byte, []byte) error { return nil }
+
+func (r *flightDataRepoStub) GetByID(ctx context.Context, id []byte) (*flightdata.FlightData, error) {
+	if r.getByIDFn != nil {
+		return r.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (r *flightDataRepoStub) GetByFlightID(context.Context, []byte) (*flightdata.FlightData, error) {
+	return nil, nil
+}
+
+func (r *flightDataRepoStub) GetByMissionID(ctx context.Context, id []byte) (*flightdata.FlightData, error) {
+	if r.getByMissionIDFn != nil {
+		return r.getByMissionIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (r *flightDataRepoStub) ListByMissionID(context.Context, []byte) ([]flightdata.FlightData, error) {
+	return nil, nil
+}
+
+func (r *flightDataRepoStub) List(context.Context, string, []byte, []byte, int, int) ([]flightdata.FlightData, int64, error) {
+	return nil, 0, nil
+}
+
+func (r *flightDataRepoStub) GetSPODetailsByFlightDataID(ctx context.Context, id []byte) (*flightdata.SPODetails, error) {
+	if r.getSPODetailsByFlightID != nil {
+		return r.getSPODetailsByFlightID(ctx, id)
+	}
+	return nil, nil
+}
+
+func (r *flightDataRepoStub) UpsertSPODetails(context.Context, []byte, *flightdata.SPOUpsertData) error {
+	return nil
+}
+
+func TestFlightDataServiceCreateSyncsCompleteStatus(t *testing.T) {
+	var updates []*flightdata.FlightData
+	rowID := []byte("019ecc1111111111")
+	repo := &flightDataRepoStub{
+		getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+			loaded := &flightdata.FlightData{
+				ID:              id,
+				MissionID:       []byte("1234567890123456"),
+				CoPilotID:       []byte("2345678901234567"),
+				FromICAOID:      []byte("3456789012345678"),
+				ToHospitalID:    []byte("4567890123456789"),
+				Mission:         &missiondomain.Mission{Type: sharedconst.MissionTypeCAT},
+				FlightTakeOff:   time.Now().UTC(),
+				FlightLanding:   time.Now().UTC(),
+				FlightDuration:  time.Hour,
+				LandingCount:    1,
+				RotorBrakeCycle: 1,
+				Status:          flightdata.StatusInProgress,
+			}
+			if got := flightdata.DeriveStatus(loaded, nil); got != flightdata.StatusCompleted {
+				t.Fatalf("expected derived status complete, got %q", got)
+			}
+			return loaded, nil
+		},
+		updateFn: func(_ context.Context, row *flightdata.FlightData) error {
+			updates = append(updates, row)
+			return nil
+		},
+	}
+
+	svc := NewFlightDataService(repo)
+	if err := svc.syncStatus(context.Background(), rowID); err != nil {
+		t.Fatalf("syncStatus returned error: %v", err)
+	}
+	if len(updates) != 1 {
+		t.Fatalf("expected one status sync update, got %d", len(updates))
+	}
+	if updates[0].Status != flightdata.StatusCompleted {
+		t.Fatalf("expected sync update to complete status, got %q", updates[0].Status)
+	}
+}
+
+func TestFlightDataServiceCreateKeepsSPOIncompleteStatus(t *testing.T) {
+	rowID := []byte("019ecc1122222222")
+	repo := &flightDataRepoStub{
+		getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+			loaded := &flightdata.FlightData{
+				ID:              id,
+				MissionID:       []byte("1234567890123456"),
+				CoPilotID:       []byte("2345678901234567"),
+				FromICAOID:      []byte("3456789012345678"),
+				ToHospitalID:    []byte("4567890123456789"),
+				FlightTakeOff:   time.Now().UTC(),
+				FlightLanding:   time.Now().UTC(),
+				FlightDuration:  time.Hour,
+				LandingCount:    1,
+				RotorBrakeCycle: 1,
+				Mission:         &missiondomain.Mission{Type: sharedconst.MissionTypeSPO},
+				Status:          flightdata.StatusInProgress,
+			}
+			if got := flightdata.DeriveStatus(loaded, nil); got != flightdata.StatusInProgress {
+				t.Fatalf("expected derived status on_progress, got %q", got)
+			}
+			return loaded, nil
+		},
+		getSPODetailsByFlightID: func(context.Context, []byte) (*flightdata.SPODetails, error) {
+			return &flightdata.SPODetails{}, nil
+		},
+	}
+
+	svc := NewFlightDataService(repo)
+	if err := svc.syncStatus(context.Background(), rowID); err != nil {
+		t.Fatalf("syncStatus returned error: %v", err)
+	}
+}
+
+func TestFlightDataServiceCreateSyncsCompleteStatusWithoutRotorBrakeCycleForCATAndNCO(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		typ  string
+	}{
+		{name: "cat", typ: sharedconst.MissionTypeCAT},
+		{name: "nco", typ: sharedconst.MissionTypeNCO},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var updates []*flightdata.FlightData
+			rowID := []byte("019ecc1144444444")
+			repo := &flightDataRepoStub{
+				getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+					loaded := &flightdata.FlightData{
+						ID:             id,
+						MissionID:      []byte("1234567890123456"),
+						CoPilotID:      []byte("2345678901234567"),
+						FromICAOID:     []byte("3456789012345678"),
+						ToHospitalID:   []byte("4567890123456789"),
+						FlightTakeOff:  time.Now().UTC(),
+						FlightLanding:  time.Now().UTC(),
+						FlightDuration: time.Hour,
+						LandingCount:   1,
+						Mission:        &missiondomain.Mission{Type: tc.typ},
+						Status:         flightdata.StatusInProgress,
+					}
+					if got := flightdata.DeriveStatus(loaded, nil); got != flightdata.StatusCompleted {
+						t.Fatalf("expected derived status complete, got %q", got)
+					}
+					return loaded, nil
+				},
+				updateFn: func(_ context.Context, row *flightdata.FlightData) error {
+					updates = append(updates, row)
+					return nil
+				},
+			}
+
+			svc := NewFlightDataService(repo)
+			if err := svc.syncStatus(context.Background(), rowID); err != nil {
+				t.Fatalf("syncStatus returned error: %v", err)
+			}
+			if len(updates) != 1 {
+				t.Fatalf("expected one status sync update, got %d", len(updates))
+			}
+			if updates[0].Status != flightdata.StatusCompleted {
+				t.Fatalf("expected sync update to complete status, got %q", updates[0].Status)
+			}
+		})
+	}
+}
+
+func TestFlightDataServiceSyncStatusFallsBackToMissionLookup(t *testing.T) {
+	var updates []*flightdata.FlightData
+	rowID := []byte("019ecc1133333333")
+	missionID := []byte("1234567890123456")
+	repo := &flightDataRepoStub{
+		getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+			return &flightdata.FlightData{
+				ID:              id,
+				MissionID:       missionID,
+				CoPilotID:       []byte("2345678901234567"),
+				FromHospitalID:  []byte("3456789012345678"),
+				ToHospitalID:    []byte("4567890123456789"),
+				FlightTakeOff:   time.Now().UTC(),
+				FlightLanding:   time.Now().UTC(),
+				FlightDuration:  time.Hour,
+				LandingCount:    1,
+				RotorBrakeCycle: 1,
+				Status:          flightdata.StatusInProgress,
+			}, nil
+		},
+		getByMissionIDFn: func(_ context.Context, _ []byte) (*flightdata.FlightData, error) {
+			return &flightdata.FlightData{
+				ID:              rowID,
+				MissionID:       missionID,
+				CoPilotID:       []byte("2345678901234567"),
+				FromHospitalID:  []byte("3456789012345678"),
+				ToHospitalID:    []byte("4567890123456789"),
+				FlightTakeOff:   time.Now().UTC(),
+				FlightLanding:   time.Now().UTC(),
+				FlightDuration:  time.Hour,
+				LandingCount:    1,
+				RotorBrakeCycle: 1,
+				Mission:         &missiondomain.Mission{Type: sharedconst.MissionTypeCAT},
+				Status:          flightdata.StatusInProgress,
+			}, nil
+		},
+		updateFn: func(_ context.Context, row *flightdata.FlightData) error {
+			updates = append(updates, row)
+			return nil
+		},
+	}
+
+	svc := NewFlightDataService(repo)
+	if err := svc.syncStatus(context.Background(), rowID); err != nil {
+		t.Fatalf("syncStatus returned error: %v", err)
+	}
+	if len(updates) != 1 {
+		t.Fatalf("expected one status sync update, got %d", len(updates))
+	}
+	if updates[0].Status != flightdata.StatusCompleted {
+		t.Fatalf("expected sync update to complete status, got %q", updates[0].Status)
+	}
+}
+
+func TestFlightDataServiceCreateBlockedWhenFMReportExists(t *testing.T) {
+	missionID := uuidv7.MustBytes()
+	repo := &flightDataRepoStub{
+		createFn: func(context.Context, *flightdata.FlightData) error {
+			t.Fatal("create should not be called when fm report already exists")
+			return nil
+		},
+	}
+	svc := NewFlightDataService(repo).
+		WithMissionResolver(missionResolverStub{flightID: uuidv7.MustBytes()}).
+		WithFMReportLookup(fmReportLookupStub{report: &fmreport.Report{ID: uuidv7.MustBytes(), FlightID: uuidv7.MustBytes()}})
+
+	err := svc.Create(context.Background(), &flightdata.FlightData{
+		MissionID:       missionID,
+		CoPilotID:       uuidv7.MustBytes(),
+		FromHospitalID:  uuidv7.MustBytes(),
+		ToICAOID:        uuidv7.MustBytes(),
+		FlightTakeOff:   time.Now().UTC(),
+		FlightLanding:   time.Now().UTC(),
+		FlightDuration:  time.Hour,
+		LandingCount:    1,
+		RotorBrakeCycle: 1,
+	})
+	if !errors.Is(err, flightdata.ErrCreateBlocked) {
+		t.Fatalf("expected create blocked, got %v", err)
+	}
+}
+
+func TestFlightDataServiceUpdateLockedWhenFMReportCompleted(t *testing.T) {
+	missionID := uuidv7.MustBytes()
+	repo := &flightDataRepoStub{
+		getByIDFn: func(context.Context, []byte) (*flightdata.FlightData, error) {
+			return &flightdata.FlightData{
+				ID:              uuidv7.MustBytes(),
+				MissionID:       missionID,
+				CoPilotID:       uuidv7.MustBytes(),
+				FromHospitalID:  uuidv7.MustBytes(),
+				ToICAOID:        uuidv7.MustBytes(),
+				FlightTakeOff:   time.Now().UTC(),
+				FlightLanding:   time.Now().UTC(),
+				FlightDuration:  time.Hour,
+				LandingCount:    1,
+				RotorBrakeCycle: 1,
+			}, nil
+		},
+		updateFn: func(context.Context, *flightdata.FlightData) error {
+			t.Fatal("update should not be called when fm report is completed")
+			return nil
+		},
+	}
+	completedAt := time.Now().UTC()
+	svc := NewFlightDataService(repo).
+		WithMissionResolver(missionResolverStub{flightID: uuidv7.MustBytes()}).
+		WithFMReportLookup(fmReportLookupStub{report: &fmreport.Report{ID: uuidv7.MustBytes(), FlightID: uuidv7.MustBytes(), CompletedAt: &completedAt}})
+
+	err := svc.Update(context.Background(), &flightdata.FlightData{
+		ID:              uuidv7.MustBytes(),
+		MissionID:       missionID,
+		CoPilotID:       uuidv7.MustBytes(),
+		FromHospitalID:  uuidv7.MustBytes(),
+		ToICAOID:        uuidv7.MustBytes(),
+		FlightTakeOff:   time.Now().UTC(),
+		FlightLanding:   time.Now().UTC(),
+		FlightDuration:  time.Hour,
+		LandingCount:    1,
+		RotorBrakeCycle: 1,
+	})
+	if !errors.Is(err, flightdata.ErrLocked) {
+		t.Fatalf("expected locked error, got %v", err)
+	}
+}
+
+func TestFlightDataServiceCreateBlockedWhenAfterFlightInspectionExists(t *testing.T) {
+	missionID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	repo := &flightDataRepoStub{
+		createFn: func(context.Context, *flightdata.FlightData) error {
+			t.Fatal("create should not be called when after flight inspection exists")
+			return nil
+		},
+	}
+	svc := NewFlightDataService(repo).
+		WithMissionResolver(missionResolverStub{flightID: uuidv7.MustBytes()}).
+		WithFlightLookup(flightLookupStub{
+			flight: &flightdomain.Flight{
+				ID: uuidv7.MustBytes(),
+				Takeover: &takeoverdomain.TakeoverAc{
+					ReserveAc: &reserveac.ReserveAc{InspectionID: inspectionID},
+				},
+			},
+		}).
+		WithAfterFlightInspectionLookup(afterFlightInspectionLookupStub{row: &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), FlightInspectionID: inspectionID}})
+
+	err := svc.Create(context.Background(), &flightdata.FlightData{
+		MissionID:       missionID,
+		CoPilotID:       uuidv7.MustBytes(),
+		FromHospitalID:  uuidv7.MustBytes(),
+		ToICAOID:        uuidv7.MustBytes(),
+		FlightTakeOff:   time.Now().UTC(),
+		FlightLanding:   time.Now().UTC(),
+		FlightDuration:  time.Hour,
+		LandingCount:    1,
+		RotorBrakeCycle: 1,
+	})
+	if !errors.Is(err, flightdata.ErrLockedAfterFlightInspection) {
+		t.Fatalf("expected after-flight inspection lock error, got %v", err)
+	}
+}
+
+func TestFlightDataServiceUpdateAllowedWhenAfterFlightInspectionExists(t *testing.T) {
+	missionID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	updated := false
+	repo := &flightDataRepoStub{
+		getByIDFn: func(context.Context, []byte) (*flightdata.FlightData, error) {
+			return &flightdata.FlightData{
+				ID:              uuidv7.MustBytes(),
+				MissionID:       missionID,
+				CoPilotID:       uuidv7.MustBytes(),
+				FromHospitalID:  uuidv7.MustBytes(),
+				ToICAOID:        uuidv7.MustBytes(),
+				FlightTakeOff:   time.Now().UTC(),
+				FlightLanding:   time.Now().UTC(),
+				FlightDuration:  time.Hour,
+				LandingCount:    1,
+				RotorBrakeCycle: 1,
+			}, nil
+		},
+		updateFn: func(context.Context, *flightdata.FlightData) error {
+			updated = true
+			return nil
+		},
+	}
+	svc := NewFlightDataService(repo).
+		WithMissionResolver(missionResolverStub{flightID: uuidv7.MustBytes()}).
+		WithFlightLookup(flightLookupStub{
+			flight: &flightdomain.Flight{
+				ID: uuidv7.MustBytes(),
+				Takeover: &takeoverdomain.TakeoverAc{
+					ReserveAc: &reserveac.ReserveAc{InspectionID: inspectionID},
+				},
+			},
+		}).
+		WithAfterFlightInspectionLookup(afterFlightInspectionLookupStub{row: &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), FlightInspectionID: inspectionID}})
+
+	err := svc.Update(context.Background(), &flightdata.FlightData{
+		ID:              uuidv7.MustBytes(),
+		MissionID:       missionID,
+		CoPilotID:       uuidv7.MustBytes(),
+		FromHospitalID:  uuidv7.MustBytes(),
+		ToICAOID:        uuidv7.MustBytes(),
+		FlightTakeOff:   time.Now().UTC(),
+		FlightLanding:   time.Now().UTC(),
+		FlightDuration:  time.Hour,
+		LandingCount:    1,
+		RotorBrakeCycle: 1,
+	})
+	if err != nil {
+		t.Fatalf("expected update to be allowed, got %v", err)
+	}
+	if !updated {
+		t.Fatal("expected update to be called")
+	}
+}
+
+func TestFlightDataServiceUpdateRequiresRow(t *testing.T) {
+	svc := NewFlightDataService(&flightDataRepoStub{})
+	if err := svc.Update(context.Background(), nil); !errors.Is(err, flightdata.ErrRequired) {
+		t.Fatalf("expected ErrRequired, got %v", err)
+	}
+}
diff --git a/internal/service/flight_inspection_file_checklist_service.go b/internal/service/flight_inspection_file_checklist_service.go
new file mode 100644
index 0000000..8bb1a7d
--- /dev/null
+++ b/internal/service/flight_inspection_file_checklist_service.go
@@ -0,0 +1,59 @@
+package service
+
+import (
+	"context"
+	"strings"
+
+	flightinspectionfilechecklist "wucher/internal/domain/flight_inspection_file_checklist"
+)
+
+type FlightInspectionFileChecklistService struct {
+	repo flightinspectionfilechecklist.Repository
+}
+
+func NewFlightInspectionFileChecklistService(repo flightinspectionfilechecklist.Repository) *FlightInspectionFileChecklistService {
+	return &FlightInspectionFileChecklistService{repo: repo}
+}
+
+func (s *FlightInspectionFileChecklistService) Create(ctx context.Context, row *flightinspectionfilechecklist.FlightInspectionFileChecklist) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *FlightInspectionFileChecklistService) Update(ctx context.Context, row *flightinspectionfilechecklist.FlightInspectionFileChecklist) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *FlightInspectionFileChecklistService) Delete(ctx context.Context, id []byte) error {
+	return s.repo.Delete(ctx, id)
+}
+
+func (s *FlightInspectionFileChecklistService) GetByID(ctx context.Context, id []byte) (*flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *FlightInspectionFileChecklistService) List(ctx context.Context, filter string, sort string, limit, offset int) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, int64, error) {
+	return s.repo.List(ctx, filter, normalizeFlightInspectionFileChecklistSort(sort), limit, offset)
+}
+
+func (s *FlightInspectionFileChecklistService) ListByInspectionID(ctx context.Context, inspectionID []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+	return s.repo.ListByInspectionID(ctx, inspectionID)
+}
+
+func (s *FlightInspectionFileChecklistService) FlightInspectionExists(ctx context.Context, inspectionID []byte) (bool, error) {
+	return s.repo.FlightInspectionExists(ctx, inspectionID)
+}
+
+func (s *FlightInspectionFileChecklistService) HelicopterFileExists(ctx context.Context, helicopterFileID []byte) (bool, error) {
+	return s.repo.HelicopterFileExists(ctx, helicopterFileID)
+}
+
+func normalizeFlightInspectionFileChecklistSort(sort string) string {
+	if normalized := normalizeSortByRules(strings.TrimSpace(sort),
+		sortExpr("is_done ASC, created_at ASC", "is_done DESC, created_at DESC", "is_done"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	); normalized != "" {
+		return normalized
+	}
+	return "created_at DESC"
+}
diff --git a/internal/service/flight_inspection_service.go b/internal/service/flight_inspection_service.go
new file mode 100644
index 0000000..f1e6cb0
--- /dev/null
+++ b/internal/service/flight_inspection_service.go
@@ -0,0 +1,51 @@
+package service
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	flightinspection "wucher/internal/domain/flight_inspection"
+)
+
+type FlightInspectionService struct {
+	repo flightinspection.FlightInspectionRepository
+}
+
+func NewFlightInspectionService(repo flightinspection.FlightInspectionRepository) *FlightInspectionService {
+	return &FlightInspectionService{repo: repo}
+}
+
+func (s *FlightInspectionService) CreateDraft(ctx context.Context, row *flightinspection.FlightInspection) error {
+	row.Status = flightinspection.StatusDraft
+	row.InspectionDate = dateOnlyUTCService(row.InspectionDate)
+	return s.repo.Create(ctx, row)
+}
+
+func (s *FlightInspectionService) Update(ctx context.Context, row *flightinspection.FlightInspection) error {
+	row.InspectionDate = dateOnlyUTCService(row.InspectionDate)
+	return s.repo.Update(ctx, row)
+}
+
+func (s *FlightInspectionService) GetByID(ctx context.Context, id []byte) (*flightinspection.FlightInspection, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *FlightInspectionService) List(ctx context.Context, sort string, limit, offset int) ([]flightinspection.FlightInspection, int64, error) {
+	return s.repo.List(ctx, normalizeFlightInspectionSort(sort), limit, offset)
+}
+
+func normalizeFlightInspectionSort(sort string) string {
+	if normalized := normalizeSortByRules(strings.TrimSpace(sort),
+		sortExpr("inspection_date ASC, created_at ASC", "inspection_date DESC, created_at DESC", "inspection_date"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	); normalized != "" {
+		return normalized
+	}
+	return "inspection_date DESC, created_at DESC"
+}
+
+func dateOnlyUTCService(t time.Time) time.Time {
+	return time.Date(t.UTC().Year(), t.UTC().Month(), t.UTC().Day(), 0, 0, 0, 0, time.UTC)
+}
diff --git a/internal/service/flight_prep_check_service.go b/internal/service/flight_prep_check_service.go
new file mode 100644
index 0000000..cac263e
--- /dev/null
+++ b/internal/service/flight_prep_check_service.go
@@ -0,0 +1,151 @@
+package service
+
+import (
+	"context"
+	"fmt"
+
+	flightinspection "wucher/internal/domain/flight_inspection"
+	flightprepcheck "wucher/internal/domain/flight_prep_check"
+	"wucher/internal/shared/pkg/appctx"
+)
+
+type FlightPrepCheckService struct {
+	checkRepo      flightprepcheck.Repository
+	inspectionRepo flightinspection.FlightInspectionRepository
+}
+
+func NewFlightPrepCheckService(
+	checkRepo flightprepcheck.Repository,
+	inspectionRepo flightinspection.FlightInspectionRepository,
+) *FlightPrepCheckService {
+	return &FlightPrepCheckService{
+		checkRepo:      checkRepo,
+		inspectionRepo: inspectionRepo,
+	}
+}
+
+func (s *FlightPrepCheckService) InitializeChecks(ctx context.Context, flightInspectionID []byte) (int, error) {
+	if len(flightInspectionID) != 16 {
+		return 0, &flightprepcheck.ValidationError{Status: 400, Title: "Invalid ID", Detail: "flight_inspection_id must be a valid UUID"}
+	}
+
+	inspection, err := s.inspectionRepo.GetByID(ctx, flightInspectionID)
+	if err != nil {
+		return 0, fmt.Errorf("failed to check flight inspection: %w", err)
+	}
+	if inspection == nil {
+		return 0, &flightprepcheck.ValidationError{Status: 404, Title: "Not found", Detail: "flight inspection not found"}
+	}
+
+	existing, err := s.checkRepo.GetByFlightInspectionID(ctx, flightInspectionID)
+	if err != nil {
+		return 0, fmt.Errorf("failed to get prep check: %w", err)
+	}
+	if existing != nil {
+		return 0, nil
+	}
+
+	row := &flightprepcheck.FlightPrepCheck{
+		FlightInspectionID: flightInspectionID,
+	}
+	if userID := appctx.GetUserID(ctx); userID != nil {
+		row.CreatedBy = userID
+		row.UpdatedBy = userID
+	}
+	if err := s.checkRepo.Create(ctx, row); err != nil {
+		return 0, fmt.Errorf("failed to create prep check: %w", err)
+	}
+
+	return 1, nil
+}
+
+func (s *FlightPrepCheckService) GetByFlightInspection(ctx context.Context, flightInspectionID []byte) (*flightprepcheck.FlightPrepCheck, error) {
+	if len(flightInspectionID) != 16 {
+		return nil, &flightprepcheck.ValidationError{Status: 400, Title: "Invalid ID", Detail: "flight_inspection_id must be a valid UUID"}
+	}
+
+	inspection, err := s.inspectionRepo.GetByID(ctx, flightInspectionID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check flight inspection: %w", err)
+	}
+	if inspection == nil {
+		return nil, &flightprepcheck.ValidationError{Status: 404, Title: "Not found", Detail: "flight inspection not found"}
+	}
+
+	return s.checkRepo.GetByFlightInspectionID(ctx, flightInspectionID)
+}
+
+func (s *FlightPrepCheckService) UpdateCheck(ctx context.Context, checkID []byte, req *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+	if len(checkID) != 16 {
+		return nil, &flightprepcheck.ValidationError{Status: 400, Title: "Invalid ID", Detail: "check_id must be a valid UUID"}
+	}
+	existing, err := s.checkRepo.GetByID(ctx, checkID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get prep check: %w", err)
+	}
+	if existing == nil {
+		return nil, &flightprepcheck.ValidationError{Status: 404, Title: "Not found", Detail: "flight prep check not found"}
+	}
+	applyFlightPrepCheckUpsert(existing, req)
+	if userID := appctx.GetUserID(ctx); userID != nil {
+		existing.UpdatedBy = userID
+	}
+	if err := s.checkRepo.Update(ctx, existing); err != nil {
+		return nil, fmt.Errorf("failed to update prep check: %w", err)
+	}
+	return existing, nil
+}
+
+func (s *FlightPrepCheckService) UpsertByFlightInspection(ctx context.Context, flightInspectionID []byte, req *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+	if len(flightInspectionID) != 16 {
+		return nil, &flightprepcheck.ValidationError{Status: 400, Title: "Invalid ID", Detail: "flight_inspection_id must be a valid UUID"}
+	}
+	inspection, err := s.inspectionRepo.GetByID(ctx, flightInspectionID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to check flight inspection: %w", err)
+	}
+	if inspection == nil {
+		return nil, &flightprepcheck.ValidationError{Status: 404, Title: "Not found", Detail: "flight inspection not found"}
+	}
+
+	existing, err := s.checkRepo.GetByFlightInspectionID(ctx, flightInspectionID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get prep check: %w", err)
+	}
+	if existing == nil {
+		existing = &flightprepcheck.FlightPrepCheck{FlightInspectionID: flightInspectionID}
+		if userID := appctx.GetUserID(ctx); userID != nil {
+			existing.CreatedBy = userID
+			existing.UpdatedBy = userID
+		}
+		applyFlightPrepCheckUpsert(existing, req)
+		if err := s.checkRepo.Create(ctx, existing); err != nil {
+			return nil, fmt.Errorf("failed to create prep check: %w", err)
+		}
+		return existing, nil
+	}
+
+	applyFlightPrepCheckUpsert(existing, req)
+	if userID := appctx.GetUserID(ctx); userID != nil {
+		existing.UpdatedBy = userID
+	}
+	if err := s.checkRepo.Update(ctx, existing); err != nil {
+		return nil, fmt.Errorf("failed to update prep check: %w", err)
+	}
+	return existing, nil
+}
+
+func applyFlightPrepCheckUpsert(row *flightprepcheck.FlightPrepCheck, req *flightprepcheck.UpsertRequest) {
+	if row == nil || req == nil {
+		return
+	}
+	if req.NOTAMBriefing != nil {
+		row.NOTAMBriefing = *req.NOTAMBriefing
+	}
+	if req.WeatherBriefing != nil {
+		row.WeatherBriefing = *req.WeatherBriefing
+	}
+	if req.OperationalFlightPlan != nil {
+		row.OperationalFlightPlan = *req.OperationalFlightPlan
+	}
+}
diff --git a/internal/service/flight_service.go b/internal/service/flight_service.go
new file mode 100644
index 0000000..98b9857
--- /dev/null
+++ b/internal/service/flight_service.go
@@ -0,0 +1,92 @@
+package service
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"wucher/internal/domain/flight"
+	"wucher/internal/shared/pkg/missioncode"
+)
+
+type FlightService struct {
+	repo flight.FlightRepository
+}
+
+func NewFlightService(repo flight.FlightRepository) *FlightService {
+	return &FlightService{repo: repo}
+}
+
+func (s *FlightService) Create(ctx context.Context, row *flight.Flight) error {
+	if row != nil {
+		now := time.Now()
+		prefix := missioncode.BuildPrefix(now)
+		latest, err := s.repo.GetLatestMissionCodeByPrefix(ctx, prefix)
+		if err != nil {
+			return err
+		}
+		nextCode := missioncode.NextFromLatest(prefix, latest)
+		row.MissionCode = &nextCode
+	}
+	return s.repo.Create(ctx, row)
+}
+
+func (s *FlightService) Update(ctx context.Context, row *flight.Flight) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *FlightService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *FlightService) GetByID(ctx context.Context, id []byte) (*flight.Flight, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *FlightService) ListByUserID(ctx context.Context, userID []byte, limit, offset int) ([]flight.Flight, int64, error) {
+	return s.repo.ListByUserID(ctx, userID, limit, offset)
+}
+
+func (s *FlightService) ListByCreatedBy(ctx context.Context, createdBy []byte, filter string, date string, sort string, limit, offset int) ([]flight.Flight, int64, error) {
+	return s.repo.ListByCreatedBy(ctx, createdBy, filter, date, normalizeFlightSort(sort), limit, offset)
+}
+
+func (s *FlightService) GetByReserveAcID(ctx context.Context, reserveAcID []byte) (*flight.Flight, error) {
+	return s.repo.GetByReserveAcID(ctx, reserveAcID)
+}
+
+func (s *FlightService) ListByReserveAcID(ctx context.Context, reserveAcID []byte) ([]flight.Flight, error) {
+	return s.repo.ListByReserveAcID(ctx, reserveAcID)
+}
+
+func (s *FlightService) GetByTakeoverAcID(ctx context.Context, takeoverAcID []byte) (*flight.Flight, error) {
+	return s.repo.GetByTakeoverAcID(ctx, takeoverAcID)
+}
+
+func (s *FlightService) ListByTakeoverAcIDs(ctx context.Context, takeoverAcIDs [][]byte) ([]flight.Flight, error) {
+	return s.repo.ListByTakeoverAcIDs(ctx, takeoverAcIDs)
+}
+
+func (s *FlightService) GetByDutyRosterID(ctx context.Context, dutyRosterID []byte) (*flight.Flight, error) {
+	return s.repo.GetByDutyRosterID(ctx, dutyRosterID)
+}
+
+func (s *FlightService) ListByDutyRosterIDs(ctx context.Context, dutyRosterIDs [][]byte) ([]flight.Flight, error) {
+	return s.repo.ListByDutyRosterIDs(ctx, dutyRosterIDs)
+}
+
+func (s *FlightService) List(ctx context.Context, filter string, date string, sort string, limit, offset int) ([]flight.Flight, int64, error) {
+	return s.repo.List(ctx, filter, date, normalizeFlightSort(sort), limit, offset)
+}
+
+func normalizeFlightSort(sort string) string {
+	if normalized := normalizeSortByRules(strings.TrimSpace(sort),
+		sortField("flights.mission_code", "mission_code"),
+		sortField("flights.date", "date"),
+		sortField("flights.created_at", "created_at"),
+		sortField("flights.updated_at", "updated_at"),
+	); normalized != "" {
+		return normalized
+	}
+	return "flights.date DESC, flights.created_at DESC"
+}
diff --git a/internal/service/fm_report_service.go b/internal/service/fm_report_service.go
new file mode 100644
index 0000000..938cdb7
--- /dev/null
+++ b/internal/service/fm_report_service.go
@@ -0,0 +1,289 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"wucher/internal/domain/flight"
+	fmreport "wucher/internal/domain/fm_report"
+	"wucher/internal/shared/pkg/appctx"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const reportCodeMaxAttempts = 5
+
+type FMReportService struct {
+	repo           fmreport.Repository
+	historyBuilder fmreport.FleetHistoryBuilder
+	codeResolver   fmreport.ReportCodeResolver
+	usage          interface {
+		RefreshAll(context.Context) error
+	}
+}
+
+func NewFMReportService(repo fmreport.Repository) *FMReportService {
+	return &FMReportService{repo: repo}
+}
+
+func (s *FMReportService) WithFleetHistoryBuilder(builder fmreport.FleetHistoryBuilder) *FMReportService {
+	s.historyBuilder = builder
+	return s
+}
+
+func (s *FMReportService) WithReportCodeResolver(resolver fmreport.ReportCodeResolver) *FMReportService {
+	s.codeResolver = resolver
+	return s
+}
+
+func (s *FMReportService) WithUsageRefresher(refresher interface {
+	RefreshAll(context.Context) error
+}) *FMReportService {
+	s.usage = refresher
+	return s
+}
+
+func (s *FMReportService) resolveHelicopterForReportCode(ctx context.Context, takeoverID []byte) ([]byte, string) {
+	if s.codeResolver == nil || len(takeoverID) != 16 {
+		return nil, ""
+	}
+	helicopterID, reportPrefix := s.codeResolver.ResolveHelicopterForReportCode(ctx, takeoverID)
+	reportPrefix = strings.ToUpper(strings.TrimSpace(reportPrefix))
+	if len(helicopterID) != 16 || reportPrefix == "" {
+		return nil, ""
+	}
+	return helicopterID, reportPrefix
+}
+
+func (s *FMReportService) assignReportCode(ctx context.Context, row *fmreport.Report, helicopterID []byte, reportPrefix string) {
+	if len(helicopterID) != 16 || reportPrefix == "" || len(row.ID) != 16 {
+		return
+	}
+	for attempt := 0; attempt < reportCodeMaxAttempts; attempt++ {
+		maxSeq, err := s.repo.MaxReportSeqByHelicopter(ctx, helicopterID)
+		if err != nil {
+			return
+		}
+		code := reportPrefix + "-" + fmt.Sprintf("%04d", maxSeq+1)
+		if err := s.repo.SetReportCode(ctx, row.ID, code); err != nil {
+			if errors.Is(err, fmreport.ErrDuplicateReportCode) {
+				continue
+			}
+			return
+		}
+		row.ReportCode = &code
+		return
+	}
+}
+
+func (s *FMReportService) GetFleetHistory(ctx context.Context, reportID []byte) (*fmreport.FleetHistory, error) {
+	if len(reportID) != 16 {
+		return nil, fmt.Errorf("report id must be a valid UUID")
+	}
+	return s.repo.GetFleetHistoryByReportID(ctx, reportID)
+}
+
+func (s *FMReportService) UpsertForFlight(ctx context.Context, flightRow *flight.Flight, flightInspectionID []byte) (*fmreport.Report, error) {
+	if flightRow == nil || len(flightRow.ID) != 16 {
+		return nil, fmt.Errorf("flight is required")
+	}
+	if len(flightRow.TakeoverAcID) != 16 {
+		return nil, fmt.Errorf("takeover id is required")
+	}
+	if len(flightInspectionID) != 16 {
+		return nil, fmt.Errorf("flight inspection id is required")
+	}
+
+	row := &fmreport.Report{
+		FlightID:           flightRow.ID,
+		TakeoverID:         flightRow.TakeoverAcID,
+		FlightInspectionID: flightInspectionID,
+	}
+	if userID := appctx.GetUserID(ctx); len(userID) == 16 {
+		row.CreatedBy = userID
+		row.UpdatedBy = userID
+	}
+	isNew := true
+	if existing, err := s.repo.GetByFlightID(ctx, flightRow.ID); err == nil && existing != nil && len(existing.ID) == 16 {
+		isNew = false
+		if existing.CompletedAt != nil {
+			return existing, nil
+		}
+		row.ID = existing.ID
+		row.CreatedAt = existing.CreatedAt
+		row.CreatedBy = existing.CreatedBy
+		row.HelicopterID = existing.HelicopterID
+		row.ReportCode = existing.ReportCode
+		row.Engine1GpcN1 = existing.Engine1GpcN1
+		row.Engine1PtcN2 = existing.Engine1PtcN2
+		row.Engine2GpcN1 = existing.Engine2GpcN1
+		row.Engine2PtcN2 = existing.Engine2PtcN2
+	}
+
+	var helicopterID []byte
+	var reportPrefix string
+	if isNew {
+		helicopterID, reportPrefix = s.resolveHelicopterForReportCode(ctx, flightRow.TakeoverAcID)
+		if len(helicopterID) == 16 {
+			row.HelicopterID = helicopterID
+		}
+	}
+	if err := s.repo.Upsert(ctx, row); err != nil {
+		return nil, fmt.Errorf("failed to upsert fm report: %w", err)
+	}
+	if isNew {
+		s.assignReportCode(ctx, row, helicopterID, reportPrefix)
+	}
+
+	// The fleet-status snapshot is frozen at COMPLETION (see Complete), not here — while the
+	// report is open its fleet_status is shown live so fleet updates reflect.
+	return row, nil
+}
+
+// snapshotFleetStatus freezes the current fleet status for a report (idempotent: no-op if a
+// snapshot already exists for the report).
+func (s *FMReportService) snapshotFleetStatus(ctx context.Context, row *fmreport.Report) {
+	if s.historyBuilder == nil || len(row.ID) != 16 {
+		return
+	}
+	if existing, _ := s.repo.GetFleetHistoryByReportID(ctx, row.ID); existing != nil {
+		return
+	}
+	if history := s.historyBuilder.BuildFleetHistory(ctx, row.TakeoverID); history != nil {
+		history.FMReportID = row.ID
+		_ = s.repo.CreateFleetHistory(ctx, history)
+	}
+}
+
+func (s *FMReportService) UpdateForFlight(ctx context.Context, flightID []byte, engine1GpcN1, engine1PtcN2, engine2GpcN1, engine2PtcN2 *string) (*fmreport.Report, error) {
+	if len(flightID) != 16 {
+		return nil, fmt.Errorf("flight id must be a valid UUID")
+	}
+	row, err := s.repo.GetByFlightID(ctx, flightID)
+	if err != nil {
+		return nil, err
+	}
+	if row == nil || len(row.ID) != 16 {
+		return nil, fmreport.ErrNotFound
+	}
+	if row.CompletedAt != nil {
+		return nil, fmreport.ErrCompleted
+	}
+	if engine1GpcN1 != nil {
+		v := strings.TrimSpace(*engine1GpcN1)
+		row.Engine1GpcN1 = &v
+	}
+	if engine1PtcN2 != nil {
+		v := strings.TrimSpace(*engine1PtcN2)
+		row.Engine1PtcN2 = &v
+	}
+	if engine2GpcN1 != nil {
+		v := strings.TrimSpace(*engine2GpcN1)
+		row.Engine2GpcN1 = &v
+	}
+	if engine2PtcN2 != nil {
+		v := strings.TrimSpace(*engine2PtcN2)
+		row.Engine2PtcN2 = &v
+	}
+	if userID := appctx.GetUserID(ctx); len(userID) == 16 {
+		row.UpdatedBy = userID
+	}
+	if err := s.repo.Upsert(ctx, row); err != nil {
+		return nil, fmt.Errorf("failed to update fm report: %w", err)
+	}
+	return row, nil
+}
+
+func (s *FMReportService) Complete(ctx context.Context, flightID []byte) (*fmreport.Report, error) {
+	if len(flightID) != 16 {
+		return nil, fmt.Errorf("flight id must be a valid UUID")
+	}
+	row, err := s.repo.GetByFlightID(ctx, flightID)
+	if err != nil {
+		return nil, err
+	}
+	if row == nil || len(row.ID) != 16 {
+		return nil, fmreport.ErrNotFound
+	}
+	if row.CompletedAt != nil {
+		if s.usage != nil {
+			if err := s.usage.RefreshAll(ctx); err != nil {
+				return nil, err
+			}
+		}
+		return row, nil
+	}
+
+	now := time.Now().UTC()
+	row.CompletedAt = &now
+	if userID := appctx.GetUserID(ctx); len(userID) == 16 {
+		row.CompletedBy = userID
+		row.UpdatedBy = userID
+	}
+	if err := s.repo.Upsert(ctx, row); err != nil {
+		return nil, fmt.Errorf("failed to complete fm report: %w", err)
+	}
+	// Freeze the fleet-status snapshot at the moment of completion.
+	s.snapshotFleetStatus(ctx, row)
+	if s.usage != nil {
+		if err := s.usage.RefreshAll(ctx); err != nil {
+			return nil, err
+		}
+	}
+	return row, nil
+}
+
+func (s *FMReportService) GetByID(ctx context.Context, id []byte) (*fmreport.Report, error) {
+	if len(id) != 16 {
+		return nil, fmt.Errorf("id must be a valid UUID")
+	}
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *FMReportService) GetByFlightID(ctx context.Context, flightID []byte) (*fmreport.Report, error) {
+	if len(flightID) != 16 {
+		return nil, fmt.Errorf("flight id must be a valid UUID")
+	}
+	row, err := s.repo.GetByFlightID(ctx, flightID)
+	if err != nil {
+		return nil, err
+	}
+	return row, nil
+}
+
+func (s *FMReportService) List(ctx context.Context, filter fmreport.ListFilter, limit, offset int) ([]fmreport.Report, int64, error) {
+	return s.repo.List(ctx, filter, limit, offset)
+}
+
+func (s *FMReportService) Delete(ctx context.Context, id []byte) error {
+	if len(id) != 16 {
+		return fmt.Errorf("id must be a valid UUID")
+	}
+	row, err := s.repo.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+	if row == nil || len(row.ID) != 16 {
+		return fmreport.ErrNotFound
+	}
+	var deletedBy []byte
+	if userID := appctx.GetUserID(ctx); len(userID) == 16 {
+		deletedBy = userID
+	}
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *FMReportService) AttachmentReferenceType() string { return "fm_report" }
+
+func (s *FMReportService) AttachmentReferenceID(row *fmreport.Report) string {
+	if row == nil {
+		return ""
+	}
+	id, err := uuidv7.BytesToString(row.ID)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(id)
+}
diff --git a/internal/service/fm_report_service_test.go b/internal/service/fm_report_service_test.go
new file mode 100644
index 0000000..1bb77cd
--- /dev/null
+++ b/internal/service/fm_report_service_test.go
@@ -0,0 +1,356 @@
+package service
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"wucher/internal/domain/flight"
+	fmreport "wucher/internal/domain/fm_report"
+	"wucher/internal/shared/pkg/appctx"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type fmReportRepoMock struct {
+	upsertFn             func(context.Context, *fmreport.Report) error
+	getByFlightFn        func(context.Context, []byte) (*fmreport.Report, error)
+	maxReportSeqFn       func(context.Context, []byte) (int, error)
+	setReportCodeFn      func(context.Context, []byte, string) error
+	listFn               func(context.Context, fmreport.ListFilter, int, int) ([]fmreport.Report, int64, error)
+	createFleetHistoryFn func(context.Context, *fmreport.FleetHistory) error
+	getFleetHistoryFn    func(context.Context, []byte) (*fmreport.FleetHistory, error)
+}
+
+type fmReportUsageRefresherStub struct {
+	calls int
+}
+
+func (s *fmReportUsageRefresherStub) RefreshAll(context.Context) error {
+	s.calls++
+	return nil
+}
+
+func (m *fmReportRepoMock) MaxReportSeqByHelicopter(ctx context.Context, helicopterID []byte) (int, error) {
+	if m.maxReportSeqFn != nil {
+		return m.maxReportSeqFn(ctx, helicopterID)
+	}
+	return 0, nil
+}
+
+func (m *fmReportRepoMock) SetReportCode(ctx context.Context, id []byte, code string) error {
+	if m.setReportCodeFn != nil {
+		return m.setReportCodeFn(ctx, id, code)
+	}
+	return nil
+}
+
+func fmStrPtr(v string) *string { return &v }
+
+func (m *fmReportRepoMock) CreateFleetHistory(ctx context.Context, row *fmreport.FleetHistory) error {
+	if m.createFleetHistoryFn != nil {
+		return m.createFleetHistoryFn(ctx, row)
+	}
+	return nil
+}
+
+func (m *fmReportRepoMock) GetFleetHistoryByReportID(ctx context.Context, reportID []byte) (*fmreport.FleetHistory, error) {
+	if m.getFleetHistoryFn != nil {
+		return m.getFleetHistoryFn(ctx, reportID)
+	}
+	return nil, nil
+}
+
+func (m *fmReportRepoMock) Upsert(ctx context.Context, row *fmreport.Report) error {
+	if m.upsertFn != nil {
+		return m.upsertFn(ctx, row)
+	}
+	return nil
+}
+
+func (m *fmReportRepoMock) GetByFlightID(ctx context.Context, flightID []byte) (*fmreport.Report, error) {
+	if m.getByFlightFn != nil {
+		return m.getByFlightFn(ctx, flightID)
+	}
+	return nil, nil
+}
+
+func (m *fmReportRepoMock) List(ctx context.Context, filter fmreport.ListFilter, limit, offset int) ([]fmreport.Report, int64, error) {
+	if m.listFn != nil {
+		return m.listFn(ctx, filter, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func TestFMReportServiceUpsertForFlightPreservesExistingMetrics(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	existingID := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+	refresher := &fmReportUsageRefresherStub{}
+
+	repo := &fmReportRepoMock{
+		getByFlightFn: func(context.Context, []byte) (*fmreport.Report, error) {
+			return &fmreport.Report{
+				ID:                 existingID,
+				FlightID:           flightID,
+				TakeoverID:         takeoverID,
+				FlightInspectionID: inspectionID,
+				Engine1GpcN1:       fmStrPtr("old-e1-gpc"),
+				Engine1PtcN2:       fmStrPtr("old-e1-ptc"),
+				Engine2GpcN1:       fmStrPtr("old-e2-gpc"),
+				Engine2PtcN2:       fmStrPtr("old-e2-ptc"),
+				CreatedAt:          time.Date(2026, 6, 18, 10, 0, 0, 0, time.UTC),
+				CreatedBy:          userID,
+			}, nil
+		},
+		upsertFn: func(_ context.Context, row *fmreport.Report) error {
+			if row.Engine1GpcN1 == nil || row.Engine1PtcN2 == nil || row.Engine2GpcN1 == nil || row.Engine2PtcN2 == nil {
+				t.Fatalf("expected metrics preserved, got %+v", row)
+			}
+			if *row.Engine1GpcN1 != "old-e1-gpc" || *row.Engine1PtcN2 != "old-e1-ptc" || *row.Engine2GpcN1 != "old-e2-gpc" || *row.Engine2PtcN2 != "old-e2-ptc" {
+				t.Fatalf("expected metrics preserved, got %+v", row)
+			}
+			return nil
+		},
+	}
+	svc := NewFMReportService(repo).WithUsageRefresher(refresher)
+	ctx := appctx.WithUserID(context.Background(), userID)
+
+	got, err := svc.UpsertForFlight(ctx, &flight.Flight{ID: flightID, TakeoverAcID: takeoverID}, inspectionID)
+	if err != nil {
+		t.Fatalf("UpsertForFlight: %v", err)
+	}
+	if got == nil || got.Engine1GpcN1 == nil || got.Engine1PtcN2 == nil || got.Engine2GpcN1 == nil || got.Engine2PtcN2 == nil {
+		t.Fatalf("unexpected report: %+v", got)
+	}
+	if *got.Engine1GpcN1 != "old-e1-gpc" || *got.Engine1PtcN2 != "old-e1-ptc" || *got.Engine2GpcN1 != "old-e2-gpc" || *got.Engine2PtcN2 != "old-e2-ptc" {
+		t.Fatalf("unexpected report: %+v", got)
+	}
+	if refresher.calls != 0 {
+		t.Fatalf("expected no usage refresh on upsert, got %d", refresher.calls)
+	}
+}
+
+func TestFMReportServiceUpdateForFlight(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	reportID := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+	refresher := &fmReportUsageRefresherStub{}
+
+	repo := &fmReportRepoMock{
+		getByFlightFn: func(context.Context, []byte) (*fmreport.Report, error) {
+			return &fmreport.Report{
+				ID:                 reportID,
+				FlightID:           flightID,
+				TakeoverID:         uuidv7.MustBytes(),
+				FlightInspectionID: uuidv7.MustBytes(),
+				Engine1GpcN1:       fmStrPtr("old-e1-gpc"),
+				Engine1PtcN2:       fmStrPtr("old-e1-ptc"),
+				Engine2GpcN1:       fmStrPtr("old-e2-gpc"),
+				Engine2PtcN2:       fmStrPtr("old-e2-ptc"),
+			}, nil
+		},
+		upsertFn: func(ctx context.Context, row *fmreport.Report) error {
+			if row.Engine1GpcN1 == nil || row.Engine1PtcN2 == nil || row.Engine2GpcN1 == nil || row.Engine2PtcN2 == nil {
+				t.Fatalf("unexpected patched values: %+v", row)
+			}
+			if *row.Engine1GpcN1 != "new-e1-gpc" || *row.Engine1PtcN2 != "new-e1-ptc" || *row.Engine2GpcN1 != "new-e2-gpc" || *row.Engine2PtcN2 != "new-e2-ptc" {
+				t.Fatalf("unexpected patched values: %+v", row)
+			}
+			if got := appctx.GetUserID(ctx); string(got) != string(userID) {
+				t.Fatalf("expected updated by user to be preserved in context")
+			}
+			return nil
+		},
+	}
+	svc := NewFMReportService(repo).WithUsageRefresher(refresher)
+	ctx := appctx.WithUserID(context.Background(), userID)
+
+	got, err := svc.UpdateForFlight(ctx, flightID, fmStrPtr("new-e1-gpc"), fmStrPtr("new-e1-ptc"), fmStrPtr("new-e2-gpc"), fmStrPtr("new-e2-ptc"))
+	if err != nil {
+		t.Fatalf("UpdateForFlight: %v", err)
+	}
+	if got == nil || got.Engine1GpcN1 == nil || got.Engine1PtcN2 == nil || got.Engine2GpcN1 == nil || got.Engine2PtcN2 == nil {
+		t.Fatalf("unexpected report: %+v", got)
+	}
+	if *got.Engine1GpcN1 != "new-e1-gpc" || *got.Engine1PtcN2 != "new-e1-ptc" || *got.Engine2GpcN1 != "new-e2-gpc" || *got.Engine2PtcN2 != "new-e2-ptc" {
+		t.Fatalf("unexpected report: %+v", got)
+	}
+	if refresher.calls != 0 {
+		t.Fatalf("expected no usage refresh on update, got %d", refresher.calls)
+	}
+}
+
+type fmReportCodeResolverMock struct {
+	helicopterID   []byte
+	helicopterType string
+}
+
+func (m fmReportCodeResolverMock) ResolveHelicopterForReportCode(context.Context, []byte) ([]byte, string) {
+	return m.helicopterID, m.helicopterType
+}
+
+func TestFMReportServiceUpsertForFlightAssignsReportCode(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+
+	var saved *fmreport.Report
+	var setCode string
+	repo := &fmReportRepoMock{
+		getByFlightFn: func(context.Context, []byte) (*fmreport.Report, error) {
+			return nil, nil
+		},
+		maxReportSeqFn: func(_ context.Context, gotHeli []byte) (int, error) {
+			if string(gotHeli) != string(helicopterID) {
+				t.Fatalf("expected counter scoped to helicopter, got %x", gotHeli)
+			}
+			return 4, nil
+		},
+		upsertFn: func(_ context.Context, row *fmreport.Report) error {
+			saved = row
+			if string(row.HelicopterID) != string(helicopterID) {
+				t.Fatalf("expected helicopter id persisted, got %x", row.HelicopterID)
+			}
+			if row.ReportCode != nil {
+				t.Fatalf("expected report code unset on insert, got %q", *row.ReportCode)
+			}
+			if len(row.ID) != 16 {
+				row.ID = uuidv7.MustBytes()
+			}
+			return nil
+		},
+		setReportCodeFn: func(_ context.Context, _ []byte, code string) error {
+			setCode = code
+			return nil
+		},
+	}
+	svc := NewFMReportService(repo).WithReportCodeResolver(fmReportCodeResolverMock{
+		helicopterID:   helicopterID,
+		helicopterType: "SN0901",
+	})
+	ctx := appctx.WithUserID(context.Background(), userID)
+
+	got, err := svc.UpsertForFlight(ctx, &flight.Flight{ID: flightID, TakeoverAcID: takeoverID}, inspectionID)
+	if err != nil {
+		t.Fatalf("UpsertForFlight: %v", err)
+	}
+	if saved == nil {
+		t.Fatalf("expected report upserted")
+	}
+	if setCode != "SN0901-0005" {
+		t.Fatalf("expected report code SN0901-0005 persisted, got %q", setCode)
+	}
+	if got == nil || got.ReportCode == nil || *got.ReportCode != "SN0901-0005" {
+		t.Fatalf("unexpected returned report: %+v", got)
+	}
+}
+
+func TestFMReportServiceUpsertForFlightRetriesOnDuplicateReportCode(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+
+	maxCalls := 0
+	setCalls := 0
+	repo := &fmReportRepoMock{
+		getByFlightFn: func(context.Context, []byte) (*fmreport.Report, error) {
+			return nil, nil
+		},
+		maxReportSeqFn: func(context.Context, []byte) (int, error) {
+			// First read sees 4; after the concurrent winner committed SN0901-0005,
+			// the retry sees 5.
+			maxCalls++
+			if maxCalls == 1 {
+				return 4, nil
+			}
+			return 5, nil
+		},
+		setReportCodeFn: func(_ context.Context, _ []byte, code string) error {
+			setCalls++
+			if code == "SN0901-0005" {
+				return fmreport.ErrDuplicateReportCode
+			}
+			return nil
+		},
+		upsertFn: func(_ context.Context, row *fmreport.Report) error {
+			if len(row.ID) != 16 {
+				row.ID = uuidv7.MustBytes()
+			}
+			return nil
+		},
+	}
+	svc := NewFMReportService(repo).WithReportCodeResolver(fmReportCodeResolverMock{
+		helicopterID:   helicopterID,
+		helicopterType: "SN0901",
+	})
+
+	got, err := svc.UpsertForFlight(context.Background(), &flight.Flight{ID: flightID, TakeoverAcID: takeoverID}, inspectionID)
+	if err != nil {
+		t.Fatalf("UpsertForFlight: %v", err)
+	}
+	if setCalls != 2 {
+		t.Fatalf("expected one retry after duplicate, got %d SetReportCode calls", setCalls)
+	}
+	if got == nil || got.ReportCode == nil || *got.ReportCode != "SN0901-0006" {
+		t.Fatalf("expected report code SN0901-0006 after retry, got %+v", got)
+	}
+}
+
+func TestFMReportServiceUpdateForFlightNotFound(t *testing.T) {
+	svc := NewFMReportService(&fmReportRepoMock{
+		getByFlightFn: func(context.Context, []byte) (*fmreport.Report, error) {
+			return nil, nil
+		},
+	})
+	if _, err := svc.UpdateForFlight(context.Background(), uuidv7.MustBytes(), fmStrPtr("a"), fmStrPtr("b"), fmStrPtr("c"), fmStrPtr("d")); err == nil {
+		t.Fatal("expected error")
+	}
+}
+
+func TestFMReportServiceCompleteSetsCompletionFieldsAndRefreshesUsage(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	reportID := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+	refresher := &fmReportUsageRefresherStub{}
+
+	repo := &fmReportRepoMock{
+		getByFlightFn: func(context.Context, []byte) (*fmreport.Report, error) {
+			return &fmreport.Report{
+				ID:                 reportID,
+				FlightID:           flightID,
+				TakeoverID:         uuidv7.MustBytes(),
+				FlightInspectionID: uuidv7.MustBytes(),
+			}, nil
+		},
+		upsertFn: func(ctx context.Context, row *fmreport.Report) error {
+			if row.CompletedAt == nil {
+				t.Fatal("expected completed_at to be set")
+			}
+			if len(row.CompletedBy) != 16 {
+				t.Fatal("expected completed_by to be set")
+			}
+			if got := appctx.GetUserID(ctx); string(got) != string(userID) {
+				t.Fatal("expected user id propagated in context")
+			}
+			return nil
+		},
+	}
+	svc := NewFMReportService(repo).WithUsageRefresher(refresher)
+	ctx := appctx.WithUserID(context.Background(), userID)
+
+	got, err := svc.Complete(ctx, flightID)
+	if err != nil {
+		t.Fatalf("Complete: %v", err)
+	}
+	if got == nil || got.CompletedAt == nil || len(got.CompletedBy) != 16 {
+		t.Fatalf("unexpected completed report: %+v", got)
+	}
+	if refresher.calls != 1 {
+		t.Fatalf("expected one usage refresh, got %d", refresher.calls)
+	}
+}
diff --git a/internal/service/fm_report_snapshot_test.go b/internal/service/fm_report_snapshot_test.go
new file mode 100644
index 0000000..744344e
--- /dev/null
+++ b/internal/service/fm_report_snapshot_test.go
@@ -0,0 +1,52 @@
+package service
+
+import (
+	"context"
+	"testing"
+
+	fmreport "wucher/internal/domain/fm_report"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type fmSnapshotBuilderStub struct {
+	built *fmreport.FleetHistory
+	calls int
+}
+
+func (b *fmSnapshotBuilderStub) BuildFleetHistory(context.Context, []byte) *fmreport.FleetHistory {
+	b.calls++
+	return b.built
+}
+
+// TestFMReportCompleteFreezesFleetSnapshot verifies the fleet-status snapshot is written at
+// COMPLETION (so the FM report shows live fleet status while open, frozen once completed).
+func TestFMReportCompleteFreezesFleetSnapshot(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	reportID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+
+	var created *fmreport.FleetHistory
+	repo := &fmReportRepoMock{
+		getByFlightFn: func(context.Context, []byte) (*fmreport.Report, error) {
+			return &fmreport.Report{ID: reportID, FlightID: flightID, TakeoverID: takeoverID, FlightInspectionID: uuidv7.MustBytes()}, nil
+		},
+		upsertFn:          func(context.Context, *fmreport.Report) error { return nil },
+		getFleetHistoryFn: func(context.Context, []byte) (*fmreport.FleetHistory, error) { return nil, nil },
+		createFleetHistoryFn: func(_ context.Context, row *fmreport.FleetHistory) error {
+			created = row
+			return nil
+		},
+	}
+	builder := &fmSnapshotBuilderStub{built: &fmreport.FleetHistory{}}
+	svc := NewFMReportService(repo).WithFleetHistoryBuilder(builder)
+
+	if _, err := svc.Complete(context.Background(), flightID); err != nil {
+		t.Fatalf("complete: %v", err)
+	}
+	if builder.calls != 1 {
+		t.Fatalf("expected snapshot built once at completion, got %d", builder.calls)
+	}
+	if created == nil || string(created.FMReportID) != string(reportID) {
+		t.Fatalf("expected snapshot created for the report at completion, got %+v", created)
+	}
+}
diff --git a/internal/service/forces_present_service.go b/internal/service/forces_present_service.go
new file mode 100644
index 0000000..0f51bff
--- /dev/null
+++ b/internal/service/forces_present_service.go
@@ -0,0 +1,51 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/forces_present"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type ForcesPresentService struct {
+	repo forces_present.Repository
+}
+
+func NewForcesPresentService(repo forces_present.Repository) *ForcesPresentService {
+	return &ForcesPresentService{repo: repo}
+}
+
+func (s *ForcesPresentService) Create(ctx context.Context, row *forces_present.ForcesPresent) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *ForcesPresentService) Update(ctx context.Context, row *forces_present.ForcesPresent) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *ForcesPresentService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *ForcesPresentService) GetByID(ctx context.Context, id []byte) (*forces_present.ForcesPresent, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *ForcesPresentService) List(ctx context.Context, filter, sort string, limit, offset int) ([]forces_present.ForcesPresent, int64, error) {
+	return s.repo.List(ctx, filter, normalizeForcesPresentSort(sort), limit, offset)
+}
+
+func normalizeForcesPresentSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", true)),
+			"sortkey",
+		),
+		sortField("name"),
+		sortField("note"),
+		sortField("is_active"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/forces_present_service_test.go b/internal/service/forces_present_service_test.go
new file mode 100644
index 0000000..7e6b45c
--- /dev/null
+++ b/internal/service/forces_present_service_test.go
@@ -0,0 +1,223 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/forces_present"
+)
+
+type forcesPresentRepoMock struct {
+	createCalled  bool
+	updateCalled  bool
+	deleteCalled  bool
+	getByIDCalled bool
+	listCalled    bool
+
+	lastCreate     *forces_present.ForcesPresent
+	lastUpdate     *forces_present.ForcesPresent
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastGetByID    []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+
+	getByIDResult *forces_present.ForcesPresent
+	listResult    []forces_present.ForcesPresent
+	listTotal     int64
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+}
+
+func (m *forcesPresentRepoMock) Create(_ context.Context, row *forces_present.ForcesPresent) error {
+	m.createCalled = true
+	m.lastCreate = row
+	return m.createErr
+}
+
+func (m *forcesPresentRepoMock) Update(_ context.Context, row *forces_present.ForcesPresent) error {
+	m.updateCalled = true
+	m.lastUpdate = row
+	return m.updateErr
+}
+
+func (m *forcesPresentRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return m.deleteErr
+}
+
+func (m *forcesPresentRepoMock) GetByID(_ context.Context, id []byte) (*forces_present.ForcesPresent, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *forcesPresentRepoMock) List(_ context.Context, filter, sort string, limit, offset int) ([]forces_present.ForcesPresent, int64, error) {
+	m.listCalled = true
+	m.lastListFilter = filter
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listResult, m.listTotal, m.listErr
+}
+
+func TestNewForcesPresentService(t *testing.T) {
+	repo := &forcesPresentRepoMock{}
+	svc := NewForcesPresentService(repo)
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service and repo initialized")
+	}
+}
+
+func TestForcesPresentServiceCreate(t *testing.T) {
+	repo := &forcesPresentRepoMock{}
+	svc := NewForcesPresentService(repo)
+	row := &forces_present.ForcesPresent{Name: "Team A"}
+
+	if err := svc.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.createCalled || repo.lastCreate != row {
+		t.Fatalf("expected Create forwarded to repo")
+	}
+
+	repo.createErr = errors.New("create failed")
+	if err := svc.Create(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestForcesPresentServiceUpdate(t *testing.T) {
+	repo := &forcesPresentRepoMock{}
+	svc := NewForcesPresentService(repo)
+	row := &forces_present.ForcesPresent{Name: "Team B"}
+
+	if err := svc.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateCalled || repo.lastUpdate != row {
+		t.Fatalf("expected Update forwarded to repo")
+	}
+
+	repo.updateErr = errors.New("update failed")
+	if err := svc.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestForcesPresentServiceDelete(t *testing.T) {
+	repo := &forcesPresentRepoMock{}
+	svc := NewForcesPresentService(repo)
+	id := []byte("id")
+	deletedBy := []byte("by")
+
+	if err := svc.Delete(context.Background(), id, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.deleteCalled {
+		t.Fatalf("expected Delete forwarded to repo")
+	}
+	if string(repo.lastDeleteID) != string(id) || string(repo.lastDeleteBy) != string(deletedBy) {
+		t.Fatalf("expected delete params forwarded")
+	}
+
+	repo.deleteErr = errors.New("delete failed")
+	if err := svc.Delete(context.Background(), id, deletedBy); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestForcesPresentServiceGetByID(t *testing.T) {
+	expected := &forces_present.ForcesPresent{Name: "Team A"}
+	repo := &forcesPresentRepoMock{getByIDResult: expected}
+	svc := NewForcesPresentService(repo)
+	id := []byte("id")
+
+	got, err := svc.GetByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != expected {
+		t.Fatalf("unexpected result")
+	}
+	if !repo.getByIDCalled || string(repo.lastGetByID) != string(id) {
+		t.Fatalf("expected GetByID forwarded")
+	}
+
+	repo.getByIDErr = errors.New("get failed")
+	if _, err := svc.GetByID(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestForcesPresentServiceList(t *testing.T) {
+	repo := &forcesPresentRepoMock{
+		listResult: []forces_present.ForcesPresent{{Name: "Team A"}},
+		listTotal:  1,
+	}
+	svc := NewForcesPresentService(repo)
+
+	rows, total, err := svc.List(context.Background(), "find", "name", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if !repo.listCalled {
+		t.Fatalf("expected List forwarded to repo")
+	}
+	if repo.lastListFilter != "find" || repo.lastListSort != "name ASC" || repo.lastListLimit != 10 || repo.lastListOffset != 20 {
+		t.Fatalf("unexpected list args forwarded")
+	}
+
+	rows, total, err = svc.List(context.Background(), "find", "sortkey", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC" {
+		t.Fatalf("unexpected sortkey args forwarded: %q", repo.lastListSort)
+	}
+
+	repo.listErr = errors.New("list failed")
+	if _, _, err := svc.List(context.Background(), "", "unknown", 1, 0); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestNormalizeForcesPresentSort(t *testing.T) {
+	cases := map[string]string{
+		"name":        "name ASC",
+		"-name":       "name DESC",
+		"sortkey":     "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC",
+		"-sortkey":    "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC",
+		"note":        "note ASC",
+		"-note":       "note DESC",
+		"is_active":   "is_active ASC",
+		"-is_active":  "is_active DESC",
+		"created_at":  "created_at ASC",
+		"-created_at": "created_at DESC",
+		"updated_at":  "updated_at ASC",
+		"-updated_at": "updated_at DESC",
+		"unknown":     "",
+		"":            "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeForcesPresentSort(in); got != want {
+			t.Fatalf("normalizeForcesPresentSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/health_insurance_companies_service.go b/internal/service/health_insurance_companies_service.go
new file mode 100644
index 0000000..07eb7cc
--- /dev/null
+++ b/internal/service/health_insurance_companies_service.go
@@ -0,0 +1,63 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/health_insurance_companies"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type HealthInsuranceCompaniesService struct {
+	repo health_insurance_companies.Repository
+}
+
+func NewHealthInsuranceCompaniesService(repo health_insurance_companies.Repository) *HealthInsuranceCompaniesService {
+	return &HealthInsuranceCompaniesService{repo: repo}
+}
+
+func (s *HealthInsuranceCompaniesService) Create(ctx context.Context, row *health_insurance_companies.HealthInsuranceCompany) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *HealthInsuranceCompaniesService) Update(ctx context.Context, row *health_insurance_companies.HealthInsuranceCompany) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *HealthInsuranceCompaniesService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *HealthInsuranceCompaniesService) GetByID(ctx context.Context, id []byte) (*health_insurance_companies.HealthInsuranceCompany, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *HealthInsuranceCompaniesService) List(ctx context.Context, filter, sort string, limit, offset int) ([]health_insurance_companies.HealthInsuranceCompany, int64, error) {
+	return s.repo.List(ctx, filter, normalizeHealthInsuranceCompaniesSort(sort), limit, offset)
+}
+
+func (s *HealthInsuranceCompaniesService) ResolveStateDetails(ctx context.Context, stateNames []string) (map[string]health_insurance_companies.StateDetail, error) {
+	return s.repo.ResolveStateDetails(ctx, stateNames)
+}
+
+func (s *HealthInsuranceCompaniesService) ResolveLandDetails(ctx context.Context, landIDs []string) (map[string]health_insurance_companies.LandDetail, error) {
+	return s.repo.ResolveLandDetails(ctx, landIDs)
+}
+
+func normalizeHealthInsuranceCompaniesSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", true)),
+			"sortkey",
+		),
+		sortField("name"),
+		sortField("state"),
+		sortField("address"),
+		sortField("mobile_number"),
+		sortField("email"),
+		sortField("note"),
+		sortField("is_active"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/health_insurance_companies_service_test.go b/internal/service/health_insurance_companies_service_test.go
new file mode 100644
index 0000000..3f30a48
--- /dev/null
+++ b/internal/service/health_insurance_companies_service_test.go
@@ -0,0 +1,275 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/health_insurance_companies"
+)
+
+type healthInsuranceCompaniesRepoMock struct {
+	createCalled  bool
+	updateCalled  bool
+	deleteCalled  bool
+	getByIDCalled bool
+	listCalled    bool
+
+	lastCreate     *health_insurance_companies.HealthInsuranceCompany
+	lastUpdate     *health_insurance_companies.HealthInsuranceCompany
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastGetByID    []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+
+	getByIDResult *health_insurance_companies.HealthInsuranceCompany
+	listResult    []health_insurance_companies.HealthInsuranceCompany
+	listTotal     int64
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+	resolveErr error
+
+	resolveResult     map[string]health_insurance_companies.StateDetail
+	resolveLandResult map[string]health_insurance_companies.LandDetail
+}
+
+func (m *healthInsuranceCompaniesRepoMock) Create(_ context.Context, o *health_insurance_companies.HealthInsuranceCompany) error {
+	m.createCalled = true
+	m.lastCreate = o
+	return m.createErr
+}
+
+func (m *healthInsuranceCompaniesRepoMock) Update(_ context.Context, o *health_insurance_companies.HealthInsuranceCompany) error {
+	m.updateCalled = true
+	m.lastUpdate = o
+	return m.updateErr
+}
+
+func (m *healthInsuranceCompaniesRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return m.deleteErr
+}
+
+func (m *healthInsuranceCompaniesRepoMock) GetByID(_ context.Context, id []byte) (*health_insurance_companies.HealthInsuranceCompany, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *healthInsuranceCompaniesRepoMock) List(_ context.Context, filter, sort string, limit, offset int) ([]health_insurance_companies.HealthInsuranceCompany, int64, error) {
+	m.listCalled = true
+	m.lastListFilter = filter
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listResult, m.listTotal, m.listErr
+}
+
+func (m *healthInsuranceCompaniesRepoMock) ResolveStateDetails(_ context.Context, _ []string) (map[string]health_insurance_companies.StateDetail, error) {
+	return m.resolveResult, m.resolveErr
+}
+
+func (m *healthInsuranceCompaniesRepoMock) ResolveLandDetails(_ context.Context, _ []string) (map[string]health_insurance_companies.LandDetail, error) {
+	return m.resolveLandResult, m.resolveErr
+}
+
+func TestNewHealthInsuranceCompaniesService(t *testing.T) {
+	repo := &healthInsuranceCompaniesRepoMock{}
+	svc := NewHealthInsuranceCompaniesService(repo)
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service and repo initialized")
+	}
+}
+
+func TestHealthInsuranceCompaniesServiceCreate(t *testing.T) {
+	repo := &healthInsuranceCompaniesRepoMock{}
+	svc := NewHealthInsuranceCompaniesService(repo)
+	row := &health_insurance_companies.HealthInsuranceCompany{Name: "Name"}
+
+	if err := svc.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.createCalled || repo.lastCreate != row {
+		t.Fatalf("expected Create forwarded to repo")
+	}
+
+	repo.createErr = errors.New("create failed")
+	if err := svc.Create(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHealthInsuranceCompaniesServiceUpdate(t *testing.T) {
+	repo := &healthInsuranceCompaniesRepoMock{}
+	svc := NewHealthInsuranceCompaniesService(repo)
+	row := &health_insurance_companies.HealthInsuranceCompany{Name: "Updated"}
+
+	if err := svc.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateCalled || repo.lastUpdate != row {
+		t.Fatalf("expected Update forwarded to repo")
+	}
+
+	repo.updateErr = errors.New("update failed")
+	if err := svc.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHealthInsuranceCompaniesServiceDelete(t *testing.T) {
+	repo := &healthInsuranceCompaniesRepoMock{}
+	svc := NewHealthInsuranceCompaniesService(repo)
+	id := []byte("id")
+	deletedBy := []byte("by")
+
+	if err := svc.Delete(context.Background(), id, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.deleteCalled {
+		t.Fatalf("expected Delete forwarded to repo")
+	}
+	if string(repo.lastDeleteID) != string(id) || string(repo.lastDeleteBy) != string(deletedBy) {
+		t.Fatalf("expected delete params forwarded")
+	}
+
+	repo.deleteErr = errors.New("delete failed")
+	if err := svc.Delete(context.Background(), id, deletedBy); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHealthInsuranceCompaniesServiceGetByID(t *testing.T) {
+	expected := &health_insurance_companies.HealthInsuranceCompany{Name: "A"}
+	repo := &healthInsuranceCompaniesRepoMock{getByIDResult: expected}
+	svc := NewHealthInsuranceCompaniesService(repo)
+	id := []byte("id")
+
+	got, err := svc.GetByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != expected {
+		t.Fatalf("unexpected result")
+	}
+	if !repo.getByIDCalled || string(repo.lastGetByID) != string(id) {
+		t.Fatalf("expected GetByID forwarded")
+	}
+
+	repo.getByIDErr = errors.New("get failed")
+	if _, err := svc.GetByID(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHealthInsuranceCompaniesServiceList(t *testing.T) {
+	repo := &healthInsuranceCompaniesRepoMock{
+		listResult: []health_insurance_companies.HealthInsuranceCompany{{Name: "A"}},
+		listTotal:  1,
+	}
+	svc := NewHealthInsuranceCompaniesService(repo)
+
+	rows, total, err := svc.List(context.Background(), "find", "name", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if !repo.listCalled {
+		t.Fatalf("expected List forwarded to repo")
+	}
+	if repo.lastListFilter != "find" || repo.lastListSort != "name ASC" || repo.lastListLimit != 10 || repo.lastListOffset != 20 {
+		t.Fatalf("unexpected list args forwarded")
+	}
+
+	rows, total, err = svc.List(context.Background(), "find", "sortkey", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC" {
+		t.Fatalf("unexpected sortkey args forwarded: %q", repo.lastListSort)
+	}
+
+	repo.listErr = errors.New("list failed")
+	if _, _, err := svc.List(context.Background(), "", "unknown", 1, 0); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestNormalizeHealthInsuranceCompaniesSort(t *testing.T) {
+	cases := map[string]string{
+		"name":           "name ASC",
+		"-name":          "name DESC",
+		"sortkey":        "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC",
+		"-sortkey":       "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC",
+		"state":          "state ASC",
+		"-state":         "state DESC",
+		"address":        "address ASC",
+		"-address":       "address DESC",
+		"mobile_number":  "mobile_number ASC",
+		"-mobile_number": "mobile_number DESC",
+		"email":          "email ASC",
+		"-email":         "email DESC",
+		"note":           "note ASC",
+		"-note":          "note DESC",
+		"is_active":      "is_active ASC",
+		"-is_active":     "is_active DESC",
+		"created_at":     "created_at ASC",
+		"-created_at":    "created_at DESC",
+		"updated_at":     "updated_at ASC",
+		"-updated_at":    "updated_at DESC",
+		"unknown":        "",
+		"":               "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeHealthInsuranceCompaniesSort(in); got != want {
+			t.Fatalf("normalizeHealthInsuranceCompaniesSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestHealthInsuranceCompaniesServiceResolveStateDetails(t *testing.T) {
+	want := map[string]health_insurance_companies.StateDetail{
+		"berlin": {FederalStateID: "id1", FederalState: "Berlin", LandName: "Deutschland", LandISOCode: "DE"},
+	}
+	repo := &healthInsuranceCompaniesRepoMock{resolveResult: want}
+	svc := NewHealthInsuranceCompaniesService(repo)
+
+	got, err := svc.ResolveStateDetails(context.Background(), []string{"Berlin"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got["berlin"].FederalStateID != "id1" {
+		t.Fatalf("unexpected resolve result")
+	}
+}
+
+func TestHealthInsuranceCompaniesServiceResolveLandDetails(t *testing.T) {
+	want := map[string]health_insurance_companies.LandDetail{
+		"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d": {LandID: "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d", LandName: "Deutschland", LandISOCode: "DE"},
+	}
+	repo := &healthInsuranceCompaniesRepoMock{resolveLandResult: want}
+	svc := NewHealthInsuranceCompaniesService(repo)
+
+	got, err := svc.ResolveLandDetails(context.Background(), []string{"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got["018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"].LandName != "Deutschland" {
+		t.Fatalf("unexpected land resolve result")
+	}
+}
diff --git a/internal/service/heavy_service.go b/internal/service/heavy_service.go
new file mode 100644
index 0000000..be3bb07
--- /dev/null
+++ b/internal/service/heavy_service.go
@@ -0,0 +1,3 @@
+package service
+
+// Placeholder for future heavy/background operations.
diff --git a/internal/service/helicopter_file_service.go b/internal/service/helicopter_file_service.go
new file mode 100644
index 0000000..b0e3f8d
--- /dev/null
+++ b/internal/service/helicopter_file_service.go
@@ -0,0 +1,561 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"strings"
+	"time"
+
+	filemanager "wucher/internal/domain/file_manager"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	helicopterfilerealtime "wucher/internal/realtime/helicopterfile"
+	"wucher/internal/shared/pkg/attachmentresolver"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type HelicopterFileService struct {
+	repo        helicopterfile.Repository
+	fileManager filemanager.Service
+	events      helicopterFileEventPublisher
+}
+
+func NewHelicopterFileService(repo helicopterfile.Repository) *HelicopterFileService {
+	return &HelicopterFileService{repo: repo}
+}
+
+type helicopterFileEventPublisher interface {
+	PublishToUsers(userUUIDs []string, event helicopterfilerealtime.Event) int
+}
+
+func (s *HelicopterFileService) WithFileManagerService(fileManagerSvc filemanager.Service) *HelicopterFileService {
+	s.fileManager = fileManagerSvc
+	return s
+}
+
+func (s *HelicopterFileService) WithHelicopterFileEvents(publisher helicopterFileEventPublisher) *HelicopterFileService {
+	s.events = publisher
+	return s
+}
+
+func (s *HelicopterFileService) Create(ctx context.Context, row *helicopterfile.HelicopterFile) error {
+	if row != nil && row.Position <= 0 {
+		next, err := s.nextPositionByHelicopterSection(ctx, row.HelicopterID, row.Section)
+		if err != nil {
+			return err
+		}
+		row.Position = next
+	}
+	return s.repo.Create(ctx, row)
+}
+
+func (s *HelicopterFileService) Update(ctx context.Context, row *helicopterfile.HelicopterFile) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *HelicopterFileService) Delete(ctx context.Context, id []byte) error {
+	return s.repo.Delete(ctx, id)
+}
+
+func (s *HelicopterFileService) GetByID(ctx context.Context, id []byte) (*helicopterfile.HelicopterFile, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *HelicopterFileService) List(ctx context.Context, filter string, sort string, limit, offset int) ([]helicopterfile.HelicopterFile, int64, error) {
+	return s.repo.List(ctx, filter, normalizeHelicopterFileSort(sort), limit, offset)
+}
+
+func (s *HelicopterFileService) ListByHelicopter(ctx context.Context, helicopterID []byte) ([]helicopterfile.HelicopterFile, error) {
+	return s.repo.ListByHelicopter(ctx, helicopterID)
+}
+
+func (s *HelicopterFileService) ListByHelicopterAndSection(ctx context.Context, helicopterID []byte, section string) ([]helicopterfile.HelicopterFile, error) {
+	return s.repo.ListByHelicopterAndSection(ctx, helicopterID, section)
+}
+
+func (s *HelicopterFileService) HelicopterExists(ctx context.Context, helicopterID []byte) (bool, error) {
+	return s.repo.HelicopterExists(ctx, helicopterID)
+}
+
+func (s *HelicopterFileService) AttachmentExists(ctx context.Context, attachmentID []byte) (bool, error) {
+	return s.repo.AttachmentExists(ctx, attachmentID)
+}
+
+func (s *HelicopterFileService) RequestUploadIntentsBulk(ctx context.Context, inputs []helicopterfile.UploadIntentBulkInput, actorID []byte) []helicopterfile.UploadIntentBulkItemResult {
+	items := make([]helicopterfile.UploadIntentBulkItemResult, len(inputs))
+	if s.fileManager == nil {
+		for i := range items {
+			items[i] = helicopterfile.UploadIntentBulkItemResult{
+				Index:   i,
+				Success: false,
+				Error: &helicopterfile.BulkItemError{
+					Status: 400,
+					Title:  "Upload intent failed",
+					Detail: "file manager service is not configured",
+				},
+			}
+		}
+		return items
+	}
+
+	for i := range inputs {
+		item := inputs[i]
+		typ := strings.TrimSpace(item.Type)
+		if typ != "helicopter_file_upload" {
+			items[i] = uploadIntentBulkError(i, 422, "Validation error", "type must be helicopter_file_upload")
+			continue
+		}
+
+		name := strings.TrimSpace(item.Name)
+		if name == "" {
+			items[i] = uploadIntentBulkError(i, 422, "Validation error", "name is required")
+			continue
+		}
+
+		contentType := strings.TrimSpace(item.ContentType)
+		if contentType == "" {
+			items[i] = uploadIntentBulkError(i, 422, "Validation error", "content_type is required")
+			continue
+		}
+
+		if item.SizeBytes < 0 {
+			items[i] = uploadIntentBulkError(i, 422, "Validation error", "size_bytes must be greater than or equal to 0")
+			continue
+		}
+
+		grant, grantErr := s.fileManager.RequestFileUploadIntent(ctx, filemanager.RequestFileUploadIntentParams{
+			Name:        name,
+			ContentType: contentType,
+			SizeBytes:   item.SizeBytes,
+			ActorID:     actorID,
+		})
+		if grantErr != nil {
+			items[i] = uploadIntentBulkError(i, 400, "Upload intent failed", grantErr.Error())
+			continue
+		}
+
+		items[i] = helicopterfile.UploadIntentBulkItemResult{
+			Index:   i,
+			Success: true,
+			Grant:   grant,
+		}
+	}
+
+	return items
+}
+
+func (s *HelicopterFileService) CreateFromUploadIntentsBulk(ctx context.Context, inputs []helicopterfile.CreateBulkInput, actorID []byte) []helicopterfile.CreateBulkItemResult {
+	items := make([]helicopterfile.CreateBulkItemResult, len(inputs))
+	if s.fileManager == nil {
+		for i := range items {
+			items[i] = createBulkError(i, 400, "Create failed", "file manager service is not configured")
+		}
+		return items
+	}
+
+	for i := range inputs {
+		item := inputs[i]
+		typ := strings.TrimSpace(item.Type)
+		if typ != "helicopter_file_create" && typ != "helicopter_file" {
+			items[i] = createBulkError(i, 422, "Validation error", "type must be helicopter_file_create or helicopter_file")
+			continue
+		}
+
+		section := strings.TrimSpace(item.Section)
+		if !isValidHelicopterFileSection(section) {
+			items[i] = createBulkError(i, 422, "Validation error", "section is invalid")
+			continue
+		}
+
+		helicopterID, err := uuidv7.ParseString(strings.TrimSpace(item.HelicopterID))
+		if err != nil {
+			items[i] = createBulkError(i, 422, "Validation error", "helicopter_id is invalid UUID")
+			continue
+		}
+		exists, err := s.repo.HelicopterExists(ctx, helicopterID)
+		if err != nil {
+			items[i] = createBulkError(i, 400, "Create failed", err.Error())
+			continue
+		}
+		if !exists {
+			items[i] = createBulkError(i, 422, "Validation error", "helicopter_id not found")
+			continue
+		}
+
+		uploadIntentID, parseErr := uuidv7.ParseString(strings.TrimSpace(item.UploadIntentUUID))
+		if parseErr != nil {
+			items[i] = createBulkError(i, 422, "Validation error", "upload_intent_uuid is invalid UUID")
+			continue
+		}
+
+		fileName := strings.TrimSpace(item.FileName)
+		if fileName == "" {
+			items[i] = createBulkError(i, 422, "Validation error", "file_name is required")
+			continue
+		}
+
+		var folderID []byte
+		folderProvided := false
+		if item.FolderUUID != nil {
+			folderProvided = true
+			folderUUID := strings.TrimSpace(*item.FolderUUID)
+			if folderUUID != "" {
+				parsedFolderID, folderErr := uuidv7.ParseString(folderUUID)
+				if folderErr != nil {
+					items[i] = createBulkError(i, 422, "Validation error", "folder_uuid is invalid UUID")
+					continue
+				}
+				folderID = parsedFolderID
+			}
+		}
+
+		createdFile, createErr := s.fileManager.CreateFileNodeFromUploadIntent(ctx, filemanager.CreateFileFromUploadIntentParams{
+			UploadIntentID: uploadIntentID,
+			FolderID:       folderID,
+			FolderProvided: folderProvided,
+			Name:           fileName,
+			ActorID:        actorID,
+			IsTemplate:     true,
+		})
+		if createErr != nil {
+			if errors.Is(createErr, filemanager.ErrDuplicateName) {
+				targetFolderID := folderID
+				if !folderProvided || len(targetFolderID) == 0 {
+					root, rootErr := s.fileManager.GetOrCreateSystemRootFolder(ctx)
+					if rootErr != nil || root == nil {
+						detail := "unable to resolve target folder"
+						if rootErr != nil {
+							detail = rootErr.Error()
+						}
+						items[i] = createBulkError(i, 400, "Create failed", detail)
+						continue
+					}
+					targetFolderID = root.ID
+				}
+
+				nameNormalized := strings.ToLower(filepath.Base(strings.TrimSpace(fileName)))
+				if nameNormalized == "" {
+					items[i] = createBulkError(i, 422, "Validation error", "file_name is invalid")
+					continue
+				}
+				existingFile, existingErr := s.fileManager.GetFileByFolderAndName(ctx, targetFolderID, nameNormalized)
+				if existingErr != nil || existingFile == nil {
+					detail := "duplicate file exists but cannot be resolved"
+					if existingErr != nil {
+						detail = existingErr.Error()
+					}
+					items[i] = createBulkError(i, 400, "Create failed", detail)
+					continue
+				}
+				createdFile = existingFile
+			} else {
+				items[i] = createBulkError(i, 400, "Create failed", createErr.Error())
+				continue
+			}
+		}
+		if createdFile == nil {
+			items[i] = createBulkError(i, 400, "Create failed", "unable to create file from upload intent")
+			continue
+		}
+
+		position := 0
+		if item.Position != nil {
+			position = *item.Position
+		}
+		isMandatory := false
+		if item.IsMandatory != nil {
+			isMandatory = *item.IsMandatory
+		}
+		row := &helicopterfile.HelicopterFile{
+			Section:      section,
+			Position:     position,
+			IsMandatory:  isMandatory,
+			HelicopterID: helicopterID,
+			SourceFileID: append([]byte(nil), createdFile.ID...),
+			CreatedBy:    actorID,
+			UpdatedBy:    actorID,
+		}
+		if row.Position <= 0 {
+			next, nextErr := s.nextPositionByHelicopterSection(ctx, row.HelicopterID, row.Section)
+			if nextErr != nil {
+				items[i] = createBulkError(i, 400, "Create failed", nextErr.Error())
+				continue
+			}
+			row.Position = next
+		}
+		if err := s.repo.Create(ctx, row); err != nil {
+			items[i] = createBulkError(i, 400, "Create failed", err.Error())
+			continue
+		}
+
+		createdRow, getErr := s.repo.GetByID(ctx, row.ID)
+		if getErr == nil && createdRow != nil {
+			items[i] = helicopterfile.CreateBulkItemResult{
+				Index:   i,
+				Success: true,
+				Row:     createdRow,
+			}
+			continue
+		}
+
+		items[i] = helicopterfile.CreateBulkItemResult{
+			Index:   i,
+			Success: true,
+			Row:     row,
+		}
+	}
+
+	return items
+}
+
+func (s *HelicopterFileService) FinalizePendingAttachments(ctx context.Context, limit int) (int, error) {
+	if s == nil || s.repo == nil {
+		return 0, errors.New("helicopter file service is not configured")
+	}
+	if s.fileManager == nil {
+		return 0, nil
+	}
+
+	rows, err := s.repo.ListPendingAttachments(ctx, limit)
+	if err != nil {
+		return 0, err
+	}
+	return s.finalizePendingAttachmentRows(ctx, rows), nil
+}
+
+func (s *HelicopterFileService) FinalizePendingAttachmentsBySourceFileUUID(ctx context.Context, sourceFileUUID string, limit int) (int, error) {
+	if s == nil || s.repo == nil {
+		return 0, errors.New("helicopter file service is not configured")
+	}
+	if s.fileManager == nil {
+		return 0, nil
+	}
+
+	sourceFileUUID = strings.TrimSpace(sourceFileUUID)
+	if sourceFileUUID == "" {
+		return 0, nil
+	}
+	sourceFileID, err := uuidv7.ParseString(sourceFileUUID)
+	if err != nil {
+		return 0, err
+	}
+
+	rows, err := s.repo.ListPendingAttachmentsBySourceFileID(ctx, sourceFileID, limit)
+	if err != nil {
+		return 0, err
+	}
+	return s.finalizePendingAttachmentRows(ctx, rows), nil
+}
+
+func (s *HelicopterFileService) finalizePendingAttachmentRows(ctx context.Context, rows []helicopterfile.HelicopterFile) int {
+	finalized := 0
+	for i := range rows {
+		row := &rows[i]
+		if len(row.ID) != 16 || len(row.SourceFileID) != 16 || len(row.FileAttachmentID) == 16 {
+			continue
+		}
+
+		attachmentID, ok, err := s.finalizePendingAttachment(ctx, row)
+		if err != nil || !ok || len(attachmentID) != 16 {
+			continue
+		}
+		finalized++
+	}
+	return finalized
+}
+
+func (s *HelicopterFileService) finalizePendingAttachment(ctx context.Context, row *helicopterfile.HelicopterFile) ([]byte, bool, error) {
+	if s == nil || row == nil || s.fileManager == nil {
+		return nil, false, nil
+	}
+	if len(row.SourceFileID) != 16 || len(row.ID) != 16 || len(row.HelicopterID) != 16 {
+		return nil, false, nil
+	}
+
+	sourceFileUUID := uuidBytesToStringOrEmpty(row.SourceFileID)
+	if sourceFileUUID == "" {
+		return nil, false, nil
+	}
+	helicopterUUID := uuidBytesToStringOrEmpty(row.HelicopterID)
+	if helicopterUUID == "" {
+		return nil, false, nil
+	}
+	category := "helicopter_file"
+	attachmentID, err := attachmentresolver.Resolve(ctx, attachmentresolver.Params{
+		FileManager: s.fileManager,
+		RawFileID:   &sourceFileUUID,
+
+		AttachmentField: "file_attachment_id",
+		FileField:       "source_file_id",
+		RequireValue:    true,
+
+		RefType:  "helicopter",
+		RefID:    helicopterUUID,
+		Category: &category,
+
+		IsPrimary: false,
+		ActorID:   append([]byte(nil), row.UpdatedBy...),
+	})
+	if err != nil {
+		var resolveErr *attachmentresolver.ResolveError
+		if errors.As(err, &resolveErr) && resolveErr.Code == attachmentresolver.ErrorFileNotReadyForAttachment {
+			return nil, false, nil
+		}
+		return nil, false, err
+	}
+	if len(attachmentID) != 16 {
+		return nil, false, nil
+	}
+
+	row.FileAttachmentID = append([]byte(nil), attachmentID...)
+	row.SourceFileID = nil
+	row.UpdatedAt = time.Now().UTC()
+	if len(row.UpdatedBy) == 0 {
+		row.UpdatedBy = append([]byte(nil), row.CreatedBy...)
+	}
+	if err := s.repo.Update(ctx, row); err != nil {
+		return nil, false, err
+	}
+	s.publishHelicopterFileState(row, attachmentID)
+	if err := s.markAttachmentFileActive(ctx, attachmentID, row.UpdatedBy); err != nil {
+		return attachmentID, true, err
+	}
+	return attachmentID, true, nil
+}
+
+func (s *HelicopterFileService) publishHelicopterFileState(row *helicopterfile.HelicopterFile, fileID []byte) {
+	if s == nil || s.events == nil || row == nil || len(row.ID) != 16 || len(row.HelicopterID) != 16 {
+		return
+	}
+
+	actorID := row.UpdatedBy
+	if len(actorID) != 16 {
+		actorID = row.CreatedBy
+	}
+	if len(actorID) != 16 {
+		return
+	}
+
+	actorUUID := uuidBytesToStringOrEmpty(actorID)
+	helicopterUUID := uuidBytesToStringOrEmpty(row.HelicopterID)
+	helicopterFileUUID := uuidBytesToStringOrEmpty(row.ID)
+	attachmentUUID := uuidBytesToStringOrEmpty(fileID)
+	if attachmentUUID == "" {
+		attachmentUUID = uuidBytesToStringOrEmpty(row.FileAttachmentID)
+	}
+	if actorUUID == "" || helicopterUUID == "" || helicopterFileUUID == "" || attachmentUUID == "" {
+		return
+	}
+
+	updatedAt := row.UpdatedAt.UTC()
+	if updatedAt.IsZero() {
+		updatedAt = time.Now().UTC()
+	}
+
+	sourceFile := row.SourceFile
+	name := ""
+	mimeType := ""
+	if sourceFile != nil {
+		name = strings.TrimSpace(sourceFile.Name)
+		mimeType = strings.TrimSpace(sourceFile.MimeType)
+	}
+
+	s.events.PublishToUsers([]string{actorUUID}, helicopterfilerealtime.Event{
+		EventType:         helicopterfilerealtime.DefaultEventType,
+		HelicopterID:      helicopterUUID,
+		HelicopterFileID:  helicopterFileUUID,
+		FileID:            attachmentUUID,
+		Section:           strings.TrimSpace(row.Section),
+		Name:              name,
+		MimeType:          mimeType,
+		AttachmentPending: len(row.FileAttachmentID) != 16 && len(row.SourceFileID) == 16,
+		Position:          row.Position,
+		IsMandatory:       row.IsMandatory,
+		UpdatedAt:         updatedAt.Format(time.RFC3339),
+	})
+}
+
+func (s *HelicopterFileService) markAttachmentFileActive(ctx context.Context, attachmentID []byte, actorID []byte) error {
+	if s == nil || s.fileManager == nil || len(attachmentID) != 16 {
+		return nil
+	}
+	lifecycle, ok := s.fileManager.(filemanager.LifecycleManager)
+	if !ok {
+		return nil
+	}
+	attachment, err := s.fileManager.GetAttachmentByID(ctx, attachmentID)
+	if err != nil || attachment == nil || len(attachment.FileID) != 16 {
+		return err
+	}
+	return lifecycle.MarkFileActive(ctx, attachment.FileID, actorID)
+}
+
+func (s *HelicopterFileService) nextPositionByHelicopterSection(ctx context.Context, helicopterID []byte, section string) (int, error) {
+	rows, err := s.repo.ListByHelicopterAndSection(ctx, helicopterID, section)
+	if err != nil {
+		return 0, err
+	}
+	maxPos := 0
+	for i := range rows {
+		if rows[i].Position > maxPos {
+			maxPos = rows[i].Position
+		}
+	}
+	return maxPos + 1, nil
+}
+
+func uploadIntentBulkError(index int, status int, title, detail string) helicopterfile.UploadIntentBulkItemResult {
+	return helicopterfile.UploadIntentBulkItemResult{
+		Index:   index,
+		Success: false,
+		Error: &helicopterfile.BulkItemError{
+			Status: status,
+			Title:  title,
+			Detail: detail,
+		},
+	}
+}
+
+func createBulkError(index int, status int, title, detail string) helicopterfile.CreateBulkItemResult {
+	return helicopterfile.CreateBulkItemResult{
+		Index:   index,
+		Success: false,
+		Error: &helicopterfile.BulkItemError{
+			Status: status,
+			Title:  title,
+			Detail: detail,
+		},
+	}
+}
+
+func isValidHelicopterFileSection(section string) bool {
+	switch strings.TrimSpace(section) {
+	case helicopterfile.SectionBeforeFirstFlightInspection,
+		helicopterfile.SectionFlightPreparationAndWB,
+		helicopterfile.SectionAfterLastFlightInspection:
+		return true
+	default:
+		return false
+	}
+}
+
+func uuidBytesToStringOrEmpty(id []byte) string {
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		return ""
+	}
+	return s
+}
+
+func normalizeHelicopterFileSort(sort string) string {
+	if normalized := normalizeSortByRules(strings.TrimSpace(sort),
+		sortExpr("section ASC, position ASC, created_at ASC", "section DESC, position DESC, created_at DESC", "section"),
+		sortField("position"),
+		sortField("is_mandatory"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	); normalized != "" {
+		return normalized
+	}
+	return "section ASC, position ASC, created_at ASC"
+}
diff --git a/internal/service/helicopter_file_service_test.go b/internal/service/helicopter_file_service_test.go
new file mode 100644
index 0000000..fe8464a
--- /dev/null
+++ b/internal/service/helicopter_file_service_test.go
@@ -0,0 +1,374 @@
+package service
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	filemanager "wucher/internal/domain/file_manager"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	helicopterfilerealtime "wucher/internal/realtime/helicopterfile"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type helicopterFileServiceRepoStub struct {
+	listPendingFn         func(context.Context, int) ([]helicopterfile.HelicopterFile, error)
+	listPendingBySourceFn func(context.Context, []byte, int) ([]helicopterfile.HelicopterFile, error)
+	updateFn              func(context.Context, *helicopterfile.HelicopterFile) error
+}
+
+func (r *helicopterFileServiceRepoStub) Create(context.Context, *helicopterfile.HelicopterFile) error {
+	return nil
+}
+
+func (r *helicopterFileServiceRepoStub) Update(ctx context.Context, row *helicopterfile.HelicopterFile) error {
+	if r.updateFn != nil {
+		return r.updateFn(ctx, row)
+	}
+	return nil
+}
+
+func (r *helicopterFileServiceRepoStub) Delete(context.Context, []byte) error { return nil }
+
+func (r *helicopterFileServiceRepoStub) GetByID(context.Context, []byte) (*helicopterfile.HelicopterFile, error) {
+	return nil, nil
+}
+
+func (r *helicopterFileServiceRepoStub) List(context.Context, string, string, int, int) ([]helicopterfile.HelicopterFile, int64, error) {
+	return nil, 0, nil
+}
+
+func (r *helicopterFileServiceRepoStub) ListPendingAttachments(ctx context.Context, limit int) ([]helicopterfile.HelicopterFile, error) {
+	if r.listPendingFn != nil {
+		return r.listPendingFn(ctx, limit)
+	}
+	return nil, nil
+}
+
+func (r *helicopterFileServiceRepoStub) ListPendingAttachmentsBySourceFileID(ctx context.Context, sourceFileID []byte, limit int) ([]helicopterfile.HelicopterFile, error) {
+	if r.listPendingBySourceFn != nil {
+		return r.listPendingBySourceFn(ctx, sourceFileID, limit)
+	}
+	return nil, nil
+}
+
+func (r *helicopterFileServiceRepoStub) ListByHelicopter(context.Context, []byte) ([]helicopterfile.HelicopterFile, error) {
+	return nil, nil
+}
+
+func (r *helicopterFileServiceRepoStub) ListByHelicopterAndSection(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+	return nil, nil
+}
+
+func (r *helicopterFileServiceRepoStub) HelicopterExists(context.Context, []byte) (bool, error) {
+	return false, nil
+}
+
+func (r *helicopterFileServiceRepoStub) AttachmentExists(context.Context, []byte) (bool, error) {
+	return false, nil
+}
+
+type helicopterFileServiceManagerStub struct {
+	filemanager.Service
+
+	createAttachmentFn   func(context.Context, filemanager.CreateAttachmentParams) (*filemanager.Attachment, error)
+	getAttachmentByIDFn  func(context.Context, []byte) (*filemanager.Attachment, error)
+	markFileActiveFn     func(context.Context, []byte, []byte) error
+	createAttachmentArgs []filemanager.CreateAttachmentParams
+	markFileActiveArgs   []struct {
+		fileID  []byte
+		actorID []byte
+	}
+}
+
+func (m *helicopterFileServiceManagerStub) CreateAttachment(ctx context.Context, params filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+	copied := params
+	copied.FileID = append([]byte(nil), params.FileID...)
+	copied.ActorID = append([]byte(nil), params.ActorID...)
+	m.createAttachmentArgs = append(m.createAttachmentArgs, copied)
+	if m.createAttachmentFn != nil {
+		return m.createAttachmentFn(ctx, params)
+	}
+	return nil, nil
+}
+
+func (m *helicopterFileServiceManagerStub) GetAttachmentByID(ctx context.Context, id []byte) (*filemanager.Attachment, error) {
+	if m.getAttachmentByIDFn != nil {
+		return m.getAttachmentByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *helicopterFileServiceManagerStub) MarkFileActive(ctx context.Context, fileID []byte, actorID []byte) error {
+	m.markFileActiveArgs = append(m.markFileActiveArgs, struct {
+		fileID  []byte
+		actorID []byte
+	}{fileID: append([]byte(nil), fileID...), actorID: append([]byte(nil), actorID...)})
+	if m.markFileActiveFn != nil {
+		return m.markFileActiveFn(ctx, fileID, actorID)
+	}
+	return nil
+}
+
+func (m *helicopterFileServiceManagerStub) ReconcileFileLifecycle(context.Context, []byte, []byte) error {
+	return nil
+}
+
+func (m *helicopterFileServiceManagerStub) CleanupOrphanPendingFiles(context.Context, time.Time, time.Duration, int, bool) (filemanager.FileCleanupStats, error) {
+	return filemanager.FileCleanupStats{}, nil
+}
+
+type helicopterFileServiceEventsStub struct {
+	publishedUsers []string
+	event          *helicopterfilerealtime.Event
+}
+
+func (m *helicopterFileServiceEventsStub) PublishToUsers(userUUIDs []string, event helicopterfilerealtime.Event) int {
+	m.publishedUsers = append([]string(nil), userUUIDs...)
+	copied := event
+	m.event = &copied
+	return len(userUUIDs)
+}
+
+func TestHelicopterFileServiceFinalizePendingAttachmentsPublishesReadyEvent(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	helicopterFileID := uuidv7.MustBytes()
+	sourceFileID := uuidv7.MustBytes()
+	attachmentID := uuidv7.MustBytes()
+
+	sourceFile := &filemanager.File{
+		ID:       sourceFileID,
+		Name:     "purchase_orders 1 (15).xlsx",
+		MimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+		Status:   filemanager.FileStatusReady,
+	}
+
+	repo := &helicopterFileServiceRepoStub{
+		listPendingFn: func(_ context.Context, limit int) ([]helicopterfile.HelicopterFile, error) {
+			if limit != 1 {
+				t.Fatalf("expected limit 1, got %d", limit)
+			}
+			return []helicopterfile.HelicopterFile{
+				{
+					ID:               helicopterFileID,
+					HelicopterID:     helicopterID,
+					SourceFileID:     sourceFileID,
+					CreatedBy:        actorID,
+					UpdatedBy:        actorID,
+					SourceFile:       sourceFile,
+					Position:         4,
+					IsMandatory:      false,
+					Section:          helicopterfile.SectionBeforeFirstFlightInspection,
+					UpdatedAt:        time.Unix(100, 0).UTC(),
+					CreatedAt:        time.Unix(90, 0).UTC(),
+					FileAttachmentID: nil,
+				},
+			}, nil
+		},
+		updateFn: func(_ context.Context, row *helicopterfile.HelicopterFile) error {
+			if row == nil {
+				t.Fatal("expected row to be updated")
+			}
+			if len(row.FileAttachmentID) != 16 {
+				t.Fatalf("expected attachment id to be set, got %d bytes", len(row.FileAttachmentID))
+			}
+			if len(row.SourceFileID) != 0 {
+				t.Fatalf("expected source file id to be cleared, got %d bytes", len(row.SourceFileID))
+			}
+			return nil
+		},
+	}
+
+	fm := &helicopterFileServiceManagerStub{
+		createAttachmentFn: func(_ context.Context, params filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+			if got, want := uuidStringOrFail(t, params.FileID), uuidStringOrFail(t, sourceFileID); got != want {
+				t.Fatalf("unexpected file id: got %s want %s", got, want)
+			}
+			if got, want := params.RefType, "helicopter"; got != want {
+				t.Fatalf("unexpected ref type: got %q want %q", got, want)
+			}
+			if got, want := params.RefID, uuidStringOrFail(t, helicopterID); got != want {
+				t.Fatalf("unexpected ref id: got %q want %q", got, want)
+			}
+			if params.Category == nil || *params.Category != "helicopter_file" {
+				t.Fatalf("expected helicopter_file category, got %#v", params.Category)
+			}
+			return &filemanager.Attachment{
+				ID:     attachmentID,
+				FileID: sourceFileID,
+				File:   sourceFile,
+			}, nil
+		},
+		getAttachmentByIDFn: func(_ context.Context, id []byte) (*filemanager.Attachment, error) {
+			if got, want := uuidStringOrFail(t, id), uuidStringOrFail(t, attachmentID); got != want {
+				t.Fatalf("unexpected attachment lookup id: got %s want %s", got, want)
+			}
+			return &filemanager.Attachment{
+				ID:     attachmentID,
+				FileID: sourceFileID,
+				File:   sourceFile,
+			}, nil
+		},
+	}
+	events := &helicopterFileServiceEventsStub{}
+
+	svc := NewHelicopterFileService(repo).
+		WithFileManagerService(fm).
+		WithHelicopterFileEvents(events)
+
+	finalized, err := svc.FinalizePendingAttachments(context.Background(), 1)
+	if err != nil {
+		t.Fatalf("FinalizePendingAttachments returned error: %v", err)
+	}
+	if finalized != 1 {
+		t.Fatalf("expected one finalized attachment, got %d", finalized)
+	}
+	if len(fm.createAttachmentArgs) != 1 {
+		t.Fatalf("expected one attachment create call, got %d", len(fm.createAttachmentArgs))
+	}
+	if len(fm.markFileActiveArgs) != 1 {
+		t.Fatalf("expected one mark active call, got %d", len(fm.markFileActiveArgs))
+	}
+	if events.event == nil {
+		t.Fatal("expected helicopter file event to be published")
+	}
+
+	expectedUser := uuidStringOrFail(t, actorID)
+	if len(events.publishedUsers) != 1 || events.publishedUsers[0] != expectedUser {
+		t.Fatalf("unexpected published users: %#v", events.publishedUsers)
+	}
+	if events.event.EventType != helicopterfilerealtime.DefaultEventType {
+		t.Fatalf("expected default event type, got %q", events.event.EventType)
+	}
+	if events.event.HelicopterID != uuidStringOrFail(t, helicopterID) {
+		t.Fatalf("unexpected helicopter id: %+v", events.event)
+	}
+	if events.event.HelicopterFileID != uuidStringOrFail(t, helicopterFileID) {
+		t.Fatalf("unexpected helicopter file id: %+v", events.event)
+	}
+	if events.event.FileID != uuidStringOrFail(t, attachmentID) {
+		t.Fatalf("expected finalized event to point to attachment id, got %+v", events.event)
+	}
+	if events.event.AttachmentPending {
+		t.Fatalf("expected finalized event to mark attachment pending false, got %+v", events.event)
+	}
+	if events.event.Name != sourceFile.Name || events.event.MimeType != sourceFile.MimeType {
+		t.Fatalf("unexpected file metadata in event: %+v", events.event)
+	}
+}
+
+func TestHelicopterFileServiceFinalizePendingAttachmentsBySourceFileUUIDPublishesReadyEvent(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	helicopterFileID := uuidv7.MustBytes()
+	sourceFileID := uuidv7.MustBytes()
+	attachmentID := uuidv7.MustBytes()
+	sourceFileUUID := uuidStringOrFail(t, sourceFileID)
+
+	sourceFile := &filemanager.File{
+		ID:       sourceFileID,
+		Name:     "purchase_orders 1 (15).xlsx",
+		MimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+		Status:   filemanager.FileStatusReady,
+	}
+
+	repo := &helicopterFileServiceRepoStub{
+		listPendingBySourceFn: func(_ context.Context, source []byte, limit int) ([]helicopterfile.HelicopterFile, error) {
+			if got, want := uuidStringOrFail(t, source), sourceFileUUID; got != want {
+				t.Fatalf("unexpected source file id: got %s want %s", got, want)
+			}
+			if limit != 1 {
+				t.Fatalf("expected limit 1, got %d", limit)
+			}
+			return []helicopterfile.HelicopterFile{
+				{
+					ID:               helicopterFileID,
+					HelicopterID:     helicopterID,
+					SourceFileID:     sourceFileID,
+					CreatedBy:        actorID,
+					UpdatedBy:        actorID,
+					SourceFile:       sourceFile,
+					Position:         4,
+					IsMandatory:      false,
+					Section:          helicopterfile.SectionBeforeFirstFlightInspection,
+					UpdatedAt:        time.Unix(100, 0).UTC(),
+					CreatedAt:        time.Unix(90, 0).UTC(),
+					FileAttachmentID: nil,
+				},
+			}, nil
+		},
+		updateFn: func(_ context.Context, row *helicopterfile.HelicopterFile) error {
+			if row == nil {
+				t.Fatal("expected row to be updated")
+			}
+			if len(row.FileAttachmentID) != 16 {
+				t.Fatalf("expected attachment id to be set, got %d bytes", len(row.FileAttachmentID))
+			}
+			if len(row.SourceFileID) != 0 {
+				t.Fatalf("expected source file id to be cleared, got %d bytes", len(row.SourceFileID))
+			}
+			return nil
+		},
+	}
+
+	fm := &helicopterFileServiceManagerStub{
+		createAttachmentFn: func(_ context.Context, params filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+			if got, want := uuidStringOrFail(t, params.FileID), sourceFileUUID; got != want {
+				t.Fatalf("unexpected file id: got %s want %s", got, want)
+			}
+			return &filemanager.Attachment{
+				ID:     attachmentID,
+				FileID: sourceFileID,
+				File:   sourceFile,
+			}, nil
+		},
+		getAttachmentByIDFn: func(_ context.Context, id []byte) (*filemanager.Attachment, error) {
+			if got, want := uuidStringOrFail(t, id), uuidStringOrFail(t, attachmentID); got != want {
+				t.Fatalf("unexpected attachment lookup id: got %s want %s", got, want)
+			}
+			return &filemanager.Attachment{
+				ID:     attachmentID,
+				FileID: sourceFileID,
+				File:   sourceFile,
+			}, nil
+		},
+	}
+	events := &helicopterFileServiceEventsStub{}
+
+	svc := NewHelicopterFileService(repo).
+		WithFileManagerService(fm).
+		WithHelicopterFileEvents(events)
+
+	finalized, err := svc.FinalizePendingAttachmentsBySourceFileUUID(context.Background(), sourceFileUUID, 1)
+	if err != nil {
+		t.Fatalf("FinalizePendingAttachmentsBySourceFileUUID returned error: %v", err)
+	}
+	if finalized != 1 {
+		t.Fatalf("expected one finalized attachment, got %d", finalized)
+	}
+	if len(fm.createAttachmentArgs) != 1 {
+		t.Fatalf("expected one attachment create call, got %d", len(fm.createAttachmentArgs))
+	}
+	if len(fm.markFileActiveArgs) != 1 {
+		t.Fatalf("expected one mark active call, got %d", len(fm.markFileActiveArgs))
+	}
+	if events.event == nil {
+		t.Fatal("expected helicopter file event to be published")
+	}
+	if events.event.FileID != uuidStringOrFail(t, attachmentID) {
+		t.Fatalf("expected finalized event to point to attachment id, got %+v", events.event)
+	}
+	if events.event.AttachmentPending {
+		t.Fatalf("expected finalized event to mark attachment pending false, got %+v", events.event)
+	}
+}
+
+func uuidStringOrFail(t *testing.T, raw []byte) string {
+	t.Helper()
+	out, err := uuidv7.BytesToString(raw)
+	if err != nil {
+		t.Fatalf("convert uuid: %v", err)
+	}
+	return out
+}
diff --git a/internal/service/helicopter_service.go b/internal/service/helicopter_service.go
new file mode 100644
index 0000000..1e3cf22
--- /dev/null
+++ b/internal/service/helicopter_service.go
@@ -0,0 +1,113 @@
+package service
+
+import (
+	"context"
+
+	"gorm.io/gorm"
+
+	fleetstatus "wucher/internal/domain/fleet_status"
+	"wucher/internal/domain/helicopter"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type HelicopterService struct {
+	repo   helicopter.Repository
+	txRepo helicopterTxRepository
+}
+
+func NewHelicopterService(repo helicopter.Repository) *HelicopterService {
+	svc := &HelicopterService{repo: repo}
+	if txRepo, ok := repo.(helicopterTxRepository); ok {
+		svc.txRepo = txRepo
+	}
+	return svc
+}
+
+type helicopterTxRepository interface {
+	helicopter.Repository
+	Transaction(ctx context.Context, fn func(tx *gorm.DB) error) error
+	CreateWithDB(ctx context.Context, db *gorm.DB, h *helicopter.Helicopter) error
+}
+
+func (s *HelicopterService) Create(ctx context.Context, h *helicopter.Helicopter) error {
+	if h != nil {
+		h.EnforceAOGInactive()
+	}
+	if s.txRepo == nil {
+		if err := s.repo.Create(ctx, h); err != nil {
+			return err
+		}
+		return nil
+	}
+	return s.txRepo.Transaction(ctx, func(tx *gorm.DB) error {
+		if err := s.txRepo.CreateWithDB(ctx, tx, h); err != nil {
+			return err
+		}
+		if h != nil && len(h.ID) == 16 {
+			return tx.WithContext(ctx).Create(&fleetstatus.FleetStatus{HelicopterID: append([]byte(nil), h.ID...)}).Error
+		}
+		return nil
+	})
+}
+
+func (s *HelicopterService) Update(ctx context.Context, h *helicopter.Helicopter) error {
+	if h != nil {
+		h.EnforceAOGInactive()
+	}
+	return s.repo.Update(ctx, h)
+}
+
+func (s *HelicopterService) ExistsByIdentifier(ctx context.Context, identifier string, excludeID []byte) (bool, error) {
+	return s.repo.ExistsByIdentifier(ctx, identifier, excludeID)
+}
+
+func (s *HelicopterService) ApplySortKeyPatch(h *helicopter.Helicopter, patch helicopter.SortKeyPatch) {
+	if h == nil || !patch.Set {
+		return
+	}
+	if patch.Value == nil {
+		h.SortKey = nil
+		return
+	}
+	v := *patch.Value
+	h.SortKey = &v
+}
+
+func (s *HelicopterService) Delete(ctx context.Context, id []byte) error {
+	return s.repo.Delete(ctx, id)
+}
+
+func (s *HelicopterService) GetByID(ctx context.Context, id []byte) (*helicopter.Helicopter, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *HelicopterService) List(ctx context.Context, filter string, statuses []string, sort string, limit, offset int, groundedIDs [][]byte) ([]helicopter.Helicopter, int64, error) {
+	return s.repo.List(ctx, filter, statuses, normalizeHelicopterSort(sort), limit, offset, groundedIDs)
+}
+
+func (s *HelicopterService) NextReportNumber(ctx context.Context, id []byte) (string, int, error) {
+	return s.repo.NextReportNumber(ctx, id)
+}
+
+func (s *HelicopterService) IsInUse(ctx context.Context, id []byte) (bool, error) {
+	return s.repo.IsInUse(ctx, id)
+}
+
+func (s *HelicopterService) InUseByAircraftIDs(ctx context.Context, ids [][]byte) (map[string]bool, error) {
+	return s.repo.InUseByAircraftIDs(ctx, ids)
+}
+
+func (s *HelicopterService) ActiveFlightIDByAircraftIDs(ctx context.Context, ids [][]byte) (map[string][]byte, error) {
+	return s.repo.ActiveFlightIDByAircraftIDs(ctx, ids)
+}
+
+func normalizeHelicopterSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortField("designation"),
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "designation", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "designation", true)),
+			"sortkey",
+		),
+	)
+}
diff --git a/internal/service/helicopter_service_test.go b/internal/service/helicopter_service_test.go
new file mode 100644
index 0000000..d4fbf6f
--- /dev/null
+++ b/internal/service/helicopter_service_test.go
@@ -0,0 +1,319 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/helicopter"
+)
+
+type helicopterRepoMock struct {
+	createCalled           bool
+	updateCalled           bool
+	deleteCalled           bool
+	getByIDCalled          bool
+	listCalled             bool
+	nextReportNumberCalled bool
+	isInUseCalled          bool
+	inUseByIDsCalled       bool
+	existsByIdentifier     bool
+	existsCalled           bool
+
+	lastCreate       *helicopter.Helicopter
+	lastUpdate       *helicopter.Helicopter
+	lastDeleteID     []byte
+	lastGetByID      []byte
+	lastListFilter   string
+	lastListStatuses []string
+	lastListSort     string
+	lastListLimit    int
+	lastListOffset   int
+	lastNextReportID []byte
+	lastIsInUseID    []byte
+	lastInUseIDs     [][]byte
+
+	getByIDResult          *helicopter.Helicopter
+	listResult             []helicopter.Helicopter
+	listTotal              int64
+	nextReportNumberResult string
+	nextReportCounter      int
+	isInUseResult          bool
+	inUseByIDsResult       map[string]bool
+	existsByIdentifierID   string
+	existsByIdentifierSkip []byte
+
+	createErr           error
+	updateErr           error
+	deleteErr           error
+	getByIDErr          error
+	listErr             error
+	nextReportNumberErr error
+	isInUseErr          error
+	inUseByIDsErr       error
+	existsErr           error
+}
+
+func (m *helicopterRepoMock) Create(_ context.Context, row *helicopter.Helicopter) error {
+	m.createCalled = true
+	m.lastCreate = row
+	return m.createErr
+}
+
+func (m *helicopterRepoMock) Update(_ context.Context, row *helicopter.Helicopter) error {
+	m.updateCalled = true
+	m.lastUpdate = row
+	return m.updateErr
+}
+
+func (m *helicopterRepoMock) Delete(_ context.Context, id []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	return m.deleteErr
+}
+
+func (m *helicopterRepoMock) GetByID(_ context.Context, id []byte) (*helicopter.Helicopter, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *helicopterRepoMock) List(_ context.Context, filter string, statuses []string, sort string, limit, offset int, _ [][]byte) ([]helicopter.Helicopter, int64, error) {
+	m.listCalled = true
+	m.lastListFilter = filter
+	m.lastListStatuses = statuses
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listResult, m.listTotal, m.listErr
+}
+
+func (m *helicopterRepoMock) NextReportNumber(_ context.Context, id []byte) (string, int, error) {
+	m.nextReportNumberCalled = true
+	m.lastNextReportID = id
+	return m.nextReportNumberResult, m.nextReportCounter, m.nextReportNumberErr
+}
+
+func (m *helicopterRepoMock) IsInUse(_ context.Context, id []byte) (bool, error) {
+	m.isInUseCalled = true
+	m.lastIsInUseID = append([]byte(nil), id...)
+	return m.isInUseResult, m.isInUseErr
+}
+
+func (m *helicopterRepoMock) InUseByAircraftIDs(_ context.Context, ids [][]byte) (map[string]bool, error) {
+	m.inUseByIDsCalled = true
+	m.lastInUseIDs = m.lastInUseIDs[:0]
+	for i := range ids {
+		m.lastInUseIDs = append(m.lastInUseIDs, append([]byte(nil), ids[i]...))
+	}
+	if m.inUseByIDsResult == nil {
+		return map[string]bool{}, m.inUseByIDsErr
+	}
+	return m.inUseByIDsResult, m.inUseByIDsErr
+}
+
+func (m *helicopterRepoMock) ActiveFlightIDByAircraftIDs(_ context.Context, _ [][]byte) (map[string][]byte, error) {
+	return map[string][]byte{}, nil
+}
+
+func (m *helicopterRepoMock) ExistsByIdentifier(_ context.Context, identifier string, excludeID []byte) (bool, error) {
+	m.existsCalled = true
+	m.existsByIdentifierID = identifier
+	m.existsByIdentifierSkip = append([]byte(nil), excludeID...)
+	return m.existsByIdentifier, m.existsErr
+}
+
+func TestNewHelicopterService(t *testing.T) {
+	repo := &helicopterRepoMock{}
+	svc := NewHelicopterService(repo)
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service and repo initialized")
+	}
+}
+
+func TestHelicopterServiceCreate(t *testing.T) {
+	repo := &helicopterRepoMock{}
+	svc := NewHelicopterService(repo)
+	row := &helicopter.Helicopter{Designation: "H145", Identifier: "PK-ABC", Type: "Twin"}
+
+	if err := svc.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.createCalled || repo.lastCreate != row {
+		t.Fatalf("expected Create forwarded to repo")
+	}
+
+	repo.createErr = errors.New("create failed")
+	if err := svc.Create(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHelicopterServiceUpdate(t *testing.T) {
+	repo := &helicopterRepoMock{}
+	svc := NewHelicopterService(repo)
+	row := &helicopter.Helicopter{Designation: "H145", Identifier: "PK-ABC", Type: "Twin"}
+
+	if err := svc.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateCalled || repo.lastUpdate != row {
+		t.Fatalf("expected Update forwarded to repo")
+	}
+
+	repo.updateErr = errors.New("update failed")
+	if err := svc.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHelicopterServiceDelete(t *testing.T) {
+	repo := &helicopterRepoMock{}
+	svc := NewHelicopterService(repo)
+	id := []byte("id")
+
+	if err := svc.Delete(context.Background(), id); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.deleteCalled {
+		t.Fatalf("expected Delete forwarded to repo")
+	}
+	if string(repo.lastDeleteID) != string(id) {
+		t.Fatalf("expected delete id forwarded")
+	}
+
+	repo.deleteErr = errors.New("delete failed")
+	if err := svc.Delete(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHelicopterServiceGetByID(t *testing.T) {
+	expected := &helicopter.Helicopter{Designation: "H145", Identifier: "PK-ABC", Type: "Twin"}
+	repo := &helicopterRepoMock{getByIDResult: expected}
+	svc := NewHelicopterService(repo)
+	id := []byte("id")
+
+	got, err := svc.GetByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != expected {
+		t.Fatalf("unexpected result")
+	}
+	if !repo.getByIDCalled || string(repo.lastGetByID) != string(id) {
+		t.Fatalf("expected GetByID forwarded")
+	}
+
+	repo.getByIDErr = errors.New("get failed")
+	if _, err := svc.GetByID(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHelicopterServiceList(t *testing.T) {
+	repo := &helicopterRepoMock{
+		listResult: []helicopter.Helicopter{{Designation: "H145", Identifier: "PK-ABC", Type: "Twin"}},
+		listTotal:  1,
+	}
+	svc := NewHelicopterService(repo)
+
+	rows, total, err := svc.List(context.Background(), "find", []string{"available", "booked"}, "-designation", 10, 20, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if !repo.listCalled {
+		t.Fatalf("expected List forwarded to repo")
+	}
+	if repo.lastListFilter != "find" || repo.lastListSort != "designation DESC" || repo.lastListLimit != 10 || repo.lastListOffset != 20 {
+		t.Fatalf("unexpected list args forwarded")
+	}
+	if len(repo.lastListStatuses) != 2 || repo.lastListStatuses[0] != "available" || repo.lastListStatuses[1] != "booked" {
+		t.Fatalf("unexpected status filter forwarded: %v", repo.lastListStatuses)
+	}
+
+	repo.listErr = errors.New("list failed")
+	if _, _, err := svc.List(context.Background(), "", nil, "unknown", 1, 0, nil); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+	if repo.lastListSort != "" {
+		t.Fatalf("expected unknown sort normalized to empty")
+	}
+}
+
+func TestHelicopterServiceExistsByIdentifier(t *testing.T) {
+	repo := &helicopterRepoMock{existsByIdentifier: true}
+	svc := NewHelicopterService(repo)
+	excludeID := []byte("id")
+
+	exists, err := svc.ExistsByIdentifier(context.Background(), "SN-0001", excludeID)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !exists {
+		t.Fatalf("expected duplicate exists result")
+	}
+	if !repo.existsCalled || repo.existsByIdentifierID != "SN-0001" || string(repo.existsByIdentifierSkip) != string(excludeID) {
+		t.Fatalf("expected ExistsByIdentifier forwarded")
+	}
+
+	repo.existsErr = errors.New("exists failed")
+	if _, err := svc.ExistsByIdentifier(context.Background(), "SN-0001", nil); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHelicopterServiceNextReportNumber(t *testing.T) {
+	repo := &helicopterRepoMock{
+		nextReportNumberResult: "RPT-0001",
+		nextReportCounter:      1,
+	}
+	svc := NewHelicopterService(repo)
+	id := []byte("id")
+
+	number, counter, err := svc.NextReportNumber(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if number != "RPT-0001" || counter != 1 {
+		t.Fatalf("unexpected next report result")
+	}
+	if !repo.nextReportNumberCalled || string(repo.lastNextReportID) != string(id) {
+		t.Fatalf("expected NextReportNumber forwarded")
+	}
+
+	repo.nextReportNumberErr = errors.New("next failed")
+	if _, _, err := svc.NextReportNumber(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestNormalizeHelicopterSort(t *testing.T) {
+	cases := map[string]string{
+		"designation":  "designation ASC",
+		"-designation": "designation DESC",
+		"sortkey":      "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, designation ASC",
+		"-sortkey":     "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, designation ASC",
+		"identifier":   "",
+		"-identifier":  "",
+		"type":         "",
+		"-type":        "",
+		"counter":      "",
+		"-counter":     "",
+		"created_at":   "",
+		"-created_at":  "",
+		"updated_at":   "",
+		"-updated_at":  "",
+		"unknown":      "",
+		"":             "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeHelicopterSort(in); got != want {
+			t.Fatalf("normalizeHelicopterSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/helicopter_usage_service.go b/internal/service/helicopter_usage_service.go
new file mode 100644
index 0000000..4729c32
--- /dev/null
+++ b/internal/service/helicopter_usage_service.go
@@ -0,0 +1,89 @@
+package service
+
+import (
+	"context"
+
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+)
+
+type HelicopterUsageService struct {
+	repo helicopterusage.Repository
+}
+
+func NewHelicopterUsageService(repo helicopterusage.Repository) *HelicopterUsageService {
+	return &HelicopterUsageService{repo: repo}
+}
+
+func (s *HelicopterUsageService) Create(ctx context.Context, row *helicopterusage.HelicopterUsage) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *HelicopterUsageService) Update(ctx context.Context, row *helicopterusage.HelicopterUsage) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *HelicopterUsageService) ReviseManualTotals(ctx context.Context, helicopterID []byte, in helicopterusage.ManualSummaryInput, actor []byte) error {
+	if len(helicopterID) != 16 {
+		return nil
+	}
+	row, err := s.repo.GetByHelicopterID(ctx, helicopterID)
+	if err != nil {
+		return err
+	}
+	if row == nil {
+		row = &helicopterusage.HelicopterUsage{HelicopterID: append([]byte(nil), helicopterID...), CreatedBy: actor}
+	}
+	row.ApplyManualSummary(in)
+	row.UpdatedBy = actor
+	if len(row.ID) == 0 {
+		return s.repo.Create(ctx, row)
+	}
+	return s.repo.Update(ctx, row)
+}
+
+func (s *HelicopterUsageService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *HelicopterUsageService) RefreshAll(ctx context.Context) error {
+	if refresher, ok := s.repo.(interface {
+		RefreshAll(context.Context) error
+	}); ok {
+		return refresher.RefreshAll(ctx)
+	}
+	return nil
+}
+
+func (s *HelicopterUsageService) GetByID(ctx context.Context, id []byte) (*helicopterusage.HelicopterUsage, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *HelicopterUsageService) GetByHelicopterID(ctx context.Context, helicopterID []byte) (*helicopterusage.HelicopterUsage, error) {
+	return s.repo.GetByHelicopterID(ctx, helicopterID)
+}
+
+func (s *HelicopterUsageService) FlightStatsByFlightID(ctx context.Context, flightID []byte) (helicopterusage.FlightDayStats, error) {
+	return s.repo.FlightStatsByFlightID(ctx, flightID)
+}
+
+func (s *HelicopterUsageService) List(ctx context.Context, filter, sort string, limit, offset int) ([]helicopterusage.HelicopterUsage, int64, error) {
+	return s.repo.List(ctx, filter, normalizeSortByRules(sort,
+		sortField("helicopter_id"),
+		sortField("total_landing"),
+		sortField("total_airframe_hours"),
+		sortField("total_airframe_cycles"),
+		sortField("total_engine_1_hours"),
+		sortField("total_engine_1_gpc_ng_n1"),
+		sortField("total_engine_1_ptc_nf_n2"),
+		sortField("total_engine_1_ccc"),
+		sortField("total_engine_2_hours"),
+		sortField("total_engine_2_gpc_ng_n1"),
+		sortField("total_engine_2_ptc_nf_n2"),
+		sortField("total_engine_2_ccc"),
+		sortField("total_flight_report"),
+		sortField("total_hook_release"),
+		sortField("total_rotor_brake_cycle"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	), limit, offset)
+}
diff --git a/internal/service/helicopter_write_service.go b/internal/service/helicopter_write_service.go
new file mode 100644
index 0000000..54fb99b
--- /dev/null
+++ b/internal/service/helicopter_write_service.go
@@ -0,0 +1,443 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"strings"
+
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/helicopter"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type helicopterPINVerifier interface {
+	ConsumeSecurityPINActionToken(ctx context.Context, userID []byte, action, token string) error
+}
+
+type helicopterPINSessionVerifier interface {
+	AccessCookieName() string
+	ParseAccessTokenSessionID(ctx context.Context, accessToken string) (string, error)
+	ConsumeSecurityPINActionTokenInSession(ctx context.Context, userID []byte, action, token, sessionID string) error
+}
+
+type HelicopterWriteError struct {
+	Status  int
+	Title   string
+	Detail  string
+	Pointer string
+}
+
+func (e *HelicopterWriteError) Error() string {
+	if e == nil {
+		return ""
+	}
+	return e.Detail
+}
+
+type HelicopterWriteResult struct {
+	Row                      *helicopter.Helicopter
+	IsInUse                  bool
+	PreviousFotoAttachmentID []byte
+}
+
+type HelicopterCreateInput struct {
+	ID               []byte
+	Designation      string
+	Identifier       string
+	Type             string
+	SortKey          *int
+	Engine1          string
+	Engine2          string
+	Consumption      float64
+	NR1              bool
+	NR2              bool
+	LH               bool
+	RH               bool
+	MGB              bool
+	IGB              bool
+	TGB              bool
+	UTCOffset        int
+	FotoAttachmentID []byte
+	Dry              bool
+	AirOnGround      bool
+	AOGReason        string
+	AOGSource        string
+	Note             string
+	IsActive         bool
+	ActorUserID      []byte
+	PINVerifier      helicopterPINVerifier
+	PINToken         string
+	AccessToken      string
+}
+
+type HelicopterUpdateInput struct {
+	ID                []byte
+	Designation       *string
+	Identifier        *string
+	Type              *string
+	SortKey           helicopter.SortKeyPatch
+	Engine1           *string
+	Engine2           *string
+	Consumption       *float64
+	NR1               *bool
+	NR2               *bool
+	LH                *bool
+	RH                *bool
+	MGB               *bool
+	IGB               *bool
+	TGB               *bool
+	UTCOffset         *int
+	FotoAttachmentID  []byte
+	FotoAttachmentSet bool
+	Dry               *bool
+	AirOnGround       *bool
+	AOGReason         *string
+	AOGSource         *string
+	Note              *string
+	IsActive          *bool
+	ActorUserID       []byte
+	PINVerifier       helicopterPINVerifier
+	PINToken          string
+	AccessToken       string
+}
+
+func (s *HelicopterService) CreateDetailed(ctx context.Context, in HelicopterCreateInput) (*HelicopterWriteResult, error) {
+	if s == nil || s.repo == nil {
+		return nil, &HelicopterWriteError{Status: http.StatusInternalServerError, Title: "Create failed", Detail: "helicopter service is not configured"}
+	}
+
+	designation := strings.TrimSpace(in.Designation)
+	identifier := normalizeHelicopterIdentifier(in.Identifier)
+	heliType := strings.TrimSpace(in.Type)
+	if designation == "" || identifier == "" || heliType == "" {
+		return nil, &HelicopterWriteError{
+			Status:  http.StatusUnprocessableEntity,
+			Title:   "Validation error",
+			Detail:  "designation, identifier, and type are required",
+			Pointer: "/data/attributes",
+		}
+	}
+	exists, err := s.repo.ExistsByIdentifier(ctx, identifier, nil)
+	if err != nil {
+		return nil, &HelicopterWriteError{Status: http.StatusBadRequest, Title: "Create failed", Detail: err.Error()}
+	}
+	if exists {
+		return nil, &HelicopterWriteError{
+			Status:  http.StatusConflict,
+			Title:   "Conflict",
+			Detail:  "Serial number already exists",
+			Pointer: "/data/attributes/identifier",
+		}
+	}
+
+	aogReason := strings.TrimSpace(in.AOGReason)
+	if in.AirOnGround && aogReason == "" {
+		return nil, &HelicopterWriteError{
+			Status:  http.StatusUnprocessableEntity,
+			Title:   "AOG reason required",
+			Detail:  "AOG reason must be provided when AOG is active (`aog=true`).",
+			Pointer: "/data/attributes/aog_reason",
+		}
+	}
+	if in.AirOnGround {
+		if err := verifyHelicopterAOGPIN(ctx, in.PINVerifier, in.AccessToken, in.ActorUserID, in.PINToken); err != nil {
+			return nil, err
+		}
+	}
+
+	row := &helicopter.Helicopter{
+		ID:               append([]byte(nil), in.ID...),
+		Designation:      designation,
+		Identifier:       identifier,
+		ReportSequence:   0,
+		Type:             heliType,
+		SortKey:          cloneIntPtr(in.SortKey),
+		Engine1:          strings.TrimSpace(in.Engine1),
+		Engine2:          strings.TrimSpace(in.Engine2),
+		Consumption:      in.Consumption,
+		NR1:              in.NR1,
+		NR2:              in.NR2,
+		LH:               in.LH,
+		RH:               in.RH,
+		MGB:              in.MGB,
+		IGB:              in.IGB,
+		TGB:              in.TGB,
+		UTCOffset:        in.UTCOffset,
+		FotoAttachmentID: append([]byte(nil), in.FotoAttachmentID...),
+		Dry:              in.Dry,
+		AirOnGround:      in.AirOnGround,
+		AOGReason:        aogReason,
+		AOGSource: func() string {
+			if in.AirOnGround {
+				return helicopter.AOGSourceManual
+			}
+			return helicopter.AOGSourceUnknown
+		}(),
+		Note:      strings.TrimSpace(in.Note),
+		IsActive:  in.IsActive,
+		CreatedBy: append([]byte(nil), in.ActorUserID...),
+		UpdatedBy: append([]byte(nil), in.ActorUserID...),
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	if err := s.Create(ctx, row); err != nil {
+		return nil, &HelicopterWriteError{Status: http.StatusBadRequest, Title: "Create failed", Detail: err.Error()}
+	}
+
+	created, err := s.GetByID(ctx, row.ID)
+	if err != nil {
+		return nil, &HelicopterWriteError{Status: http.StatusBadRequest, Title: "Create failed", Detail: err.Error()}
+	}
+	if created == nil {
+		created = row
+	}
+	isInUse, err := s.IsInUse(ctx, row.ID)
+	if err != nil {
+		return nil, &HelicopterWriteError{Status: http.StatusBadRequest, Title: "Create failed", Detail: err.Error()}
+	}
+	return &HelicopterWriteResult{Row: created, IsInUse: isInUse}, nil
+}
+
+func (s *HelicopterService) UpdateDetailed(ctx context.Context, in HelicopterUpdateInput) (*HelicopterWriteResult, error) {
+	if s == nil || s.repo == nil {
+		return nil, &HelicopterWriteError{Status: http.StatusInternalServerError, Title: "Update failed", Detail: "helicopter service is not configured"}
+	}
+	if len(in.ID) != 16 {
+		return nil, &HelicopterWriteError{
+			Status:  http.StatusUnprocessableEntity,
+			Title:   "Validation error",
+			Detail:  "id is invalid UUID",
+			Pointer: "/path/id",
+		}
+	}
+
+	existing, err := s.GetByID(ctx, in.ID)
+	if err != nil {
+		return nil, &HelicopterWriteError{Status: http.StatusBadRequest, Title: "Update failed", Detail: err.Error()}
+	}
+	if existing == nil {
+		return nil, &HelicopterWriteError{Status: http.StatusNotFound, Title: "Not found", Detail: "helicopter not found"}
+	}
+
+	prevAOG := existing.AirOnGround
+	prevFotoAttachmentID := append([]byte(nil), existing.FotoAttachmentID...)
+
+	if in.Designation != nil {
+		v := strings.TrimSpace(*in.Designation)
+		if v == "" {
+			return nil, &HelicopterWriteError{
+				Status:  http.StatusUnprocessableEntity,
+				Title:   "Validation error",
+				Detail:  "designation cannot be empty",
+				Pointer: "/data/attributes/designation",
+			}
+		}
+		existing.Designation = v
+	}
+	if in.Identifier != nil {
+		raw := normalizeHelicopterIdentifier(*in.Identifier)
+		if raw == "" {
+			return nil, &HelicopterWriteError{
+				Status:  http.StatusUnprocessableEntity,
+				Title:   "Validation error",
+				Detail:  "identifier cannot be empty",
+				Pointer: "/data/attributes/identifier",
+			}
+		}
+		exists, existsErr := s.repo.ExistsByIdentifier(ctx, raw, existing.ID)
+		if existsErr != nil {
+			return nil, &HelicopterWriteError{Status: http.StatusBadRequest, Title: "Update failed", Detail: existsErr.Error()}
+		}
+		if exists {
+			return nil, &HelicopterWriteError{
+				Status:  http.StatusConflict,
+				Title:   "Conflict",
+				Detail:  "Serial number already exists",
+				Pointer: "/data/attributes/identifier",
+			}
+		}
+		existing.Identifier = raw
+	}
+	if in.Type != nil {
+		v := strings.TrimSpace(*in.Type)
+		if v == "" {
+			return nil, &HelicopterWriteError{
+				Status:  http.StatusUnprocessableEntity,
+				Title:   "Validation error",
+				Detail:  "type cannot be empty",
+				Pointer: "/data/attributes/type",
+			}
+		}
+		existing.Type = v
+	}
+	s.ApplySortKeyPatch(existing, in.SortKey)
+	if in.Engine1 != nil {
+		existing.Engine1 = strings.TrimSpace(*in.Engine1)
+	}
+	if in.Engine2 != nil {
+		existing.Engine2 = strings.TrimSpace(*in.Engine2)
+	}
+	if in.Consumption != nil {
+		existing.Consumption = *in.Consumption
+	}
+	if in.NR1 != nil {
+		existing.NR1 = *in.NR1
+	}
+	if in.NR2 != nil {
+		existing.NR2 = *in.NR2
+	}
+	if in.LH != nil {
+		existing.LH = *in.LH
+	}
+	if in.RH != nil {
+		existing.RH = *in.RH
+	}
+	if in.MGB != nil {
+		existing.MGB = *in.MGB
+	}
+	if in.IGB != nil {
+		existing.IGB = *in.IGB
+	}
+	if in.TGB != nil {
+		existing.TGB = *in.TGB
+	}
+	if in.UTCOffset != nil {
+		existing.UTCOffset = *in.UTCOffset
+	}
+	if in.FotoAttachmentSet {
+		if len(in.FotoAttachmentID) == 0 {
+			existing.FotoAttachmentID = nil
+		} else {
+			existing.FotoAttachmentID = append([]byte(nil), in.FotoAttachmentID...)
+		}
+	}
+	if in.Dry != nil {
+		existing.Dry = *in.Dry
+	}
+	if in.AirOnGround != nil {
+		existing.AirOnGround = *in.AirOnGround
+		if *in.AirOnGround {
+			existing.AOGSource = helicopter.AOGSourceManual
+		}
+	}
+	if in.AOGReason != nil {
+		existing.AOGReason = strings.TrimSpace(*in.AOGReason)
+	}
+	if in.AOGSource != nil {
+		existing.AOGSource = strings.TrimSpace(*in.AOGSource)
+	}
+	if existing.AirOnGround && strings.TrimSpace(existing.AOGReason) == "" {
+		return nil, &HelicopterWriteError{
+			Status:  http.StatusUnprocessableEntity,
+			Title:   "AOG reason required",
+			Detail:  "AOG reason must be provided when AOG is active (`aog=true`).",
+			Pointer: "/data/attributes/aog_reason",
+		}
+	}
+	if in.AirOnGround != nil && *in.AirOnGround != prevAOG {
+		if err := verifyHelicopterAOGPIN(ctx, in.PINVerifier, in.AccessToken, in.ActorUserID, in.PINToken); err != nil {
+			return nil, err
+		}
+	}
+	if in.Note != nil {
+		existing.Note = strings.TrimSpace(*in.Note)
+	}
+	if in.IsActive != nil {
+		existing.IsActive = *in.IsActive
+	}
+	existing.UpdatedBy = append([]byte(nil), in.ActorUserID...)
+
+	if err := s.Update(ctx, existing); err != nil {
+		return nil, &HelicopterWriteError{Status: http.StatusBadRequest, Title: "Update failed", Detail: err.Error()}
+	}
+	updated, err := s.GetByID(ctx, existing.ID)
+	if err != nil {
+		return nil, &HelicopterWriteError{Status: http.StatusBadRequest, Title: "Update failed", Detail: err.Error()}
+	}
+	if updated == nil {
+		updated = existing
+	}
+	isInUse, err := s.IsInUse(ctx, existing.ID)
+	if err != nil {
+		return nil, &HelicopterWriteError{Status: http.StatusBadRequest, Title: "Update failed", Detail: err.Error()}
+	}
+	return &HelicopterWriteResult{Row: updated, IsInUse: isInUse, PreviousFotoAttachmentID: prevFotoAttachmentID}, nil
+}
+
+func verifyHelicopterAOGPIN(
+	ctx context.Context,
+	verifier helicopterPINVerifier,
+	accessToken string,
+	userID []byte,
+	token string,
+) error {
+	if verifier == nil {
+		return &HelicopterWriteError{
+			Status: http.StatusUnauthorized,
+			Title:  "Unauthorized",
+			Detail: "auth service not configured",
+		}
+	}
+	if len(userID) == 0 {
+		return &HelicopterWriteError{
+			Status: http.StatusUnauthorized,
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}
+	}
+
+	if sessionVerifier, ok := verifier.(helicopterPINSessionVerifier); ok {
+		sessionID := ""
+		if accessToken = strings.TrimSpace(accessToken); accessToken != "" {
+			sid, err := sessionVerifier.ParseAccessTokenSessionID(ctx, accessToken)
+			if err != nil {
+				return &HelicopterWriteError{
+					Status: http.StatusUnauthorized,
+					Title:  "Unauthorized",
+					Detail: "invalid or expired token",
+				}
+			}
+			sessionID = sid
+		}
+
+		if err := sessionVerifier.ConsumeSecurityPINActionTokenInSession(ctx, userID, sharedconst.PinActionHelicopterAOGChange, token, sessionID); err != nil {
+			return &HelicopterWriteError{
+				Status:  http.StatusAccepted,
+				Title:   "PIN verification required",
+				Detail:  "valid PIN action token is required",
+				Pointer: "/headers/X-PIN-Verification-Token",
+			}
+		}
+		return nil
+	}
+
+	if err := verifier.ConsumeSecurityPINActionToken(ctx, userID, sharedconst.PinActionHelicopterAOGChange, token); err != nil {
+		return &HelicopterWriteError{
+			Status:  http.StatusAccepted,
+			Title:   "PIN verification required",
+			Detail:  "valid PIN action token is required",
+			Pointer: "/headers/X-PIN-Verification-Token",
+		}
+	}
+	return nil
+}
+
+func normalizeHelicopterIdentifier(raw string) string {
+	return strings.ToUpper(strings.TrimSpace(raw))
+}
+
+func cloneIntPtr(v *int) *int {
+	if v == nil {
+		return nil
+	}
+	out := *v
+	return &out
+}
+
+func isHelicopterNotFound(err error) bool {
+	return errors.Is(err, gorm.ErrRecordNotFound)
+}
diff --git a/internal/service/hems_operation_category_service.go b/internal/service/hems_operation_category_service.go
new file mode 100644
index 0000000..0112d62
--- /dev/null
+++ b/internal/service/hems_operation_category_service.go
@@ -0,0 +1,44 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/operation"
+)
+
+type HEMSOperationCategoryService struct {
+	repo operation.HEMSOperationCategoryRepository
+}
+
+func NewHEMSOperationCategoryService(repo operation.HEMSOperationCategoryRepository) *HEMSOperationCategoryService {
+	return &HEMSOperationCategoryService{repo: repo}
+}
+
+func (s *HEMSOperationCategoryService) Create(ctx context.Context, category *operation.HEMSOperationCategory) error {
+	return s.repo.Create(ctx, category)
+}
+
+func (s *HEMSOperationCategoryService) Update(ctx context.Context, category *operation.HEMSOperationCategory) error {
+	return s.repo.Update(ctx, category)
+}
+
+func (s *HEMSOperationCategoryService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *HEMSOperationCategoryService) GetByID(ctx context.Context, id []byte) (*operation.HEMSOperationCategory, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *HEMSOperationCategoryService) List(ctx context.Context, filter string, sort string, limit, offset int) ([]operation.HEMSOperationCategory, int64, error) {
+	return s.repo.List(ctx, filter, normalizeHEMSOperationCategorySort(sort), limit, offset)
+}
+
+func normalizeHEMSOperationCategorySort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortField("name"),
+		sortField("type"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/hems_operation_service.go b/internal/service/hems_operation_service.go
new file mode 100644
index 0000000..291e5a1
--- /dev/null
+++ b/internal/service/hems_operation_service.go
@@ -0,0 +1,43 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/operation"
+)
+
+type HEMSOperationService struct {
+	repo operation.HEMSOperationRepository
+}
+
+func NewHEMSOperationService(repo operation.HEMSOperationRepository) *HEMSOperationService {
+	return &HEMSOperationService{repo: repo}
+}
+
+func (s *HEMSOperationService) Create(ctx context.Context, row *operation.HEMSOperation) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *HEMSOperationService) Update(ctx context.Context, row *operation.HEMSOperation) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *HEMSOperationService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *HEMSOperationService) GetByID(ctx context.Context, id []byte) (*operation.HEMSOperation, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *HEMSOperationService) List(ctx context.Context, filter string, sort string, limit, offset int) ([]operation.HEMSOperation, int64, error) {
+	return s.repo.List(ctx, filter, normalizeHEMSOperationSort(sort), limit, offset)
+}
+
+func normalizeHEMSOperationSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortField("date"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/hems_operational_data_service.go b/internal/service/hems_operational_data_service.go
new file mode 100644
index 0000000..e295c62
--- /dev/null
+++ b/internal/service/hems_operational_data_service.go
@@ -0,0 +1,44 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/operation"
+)
+
+type HEMSOperationalDataService struct {
+	repo operation.HEMSOperationalDataRepository
+}
+
+func NewHEMSOperationalDataService(repo operation.HEMSOperationalDataRepository) *HEMSOperationalDataService {
+	return &HEMSOperationalDataService{repo: repo}
+}
+
+func (s *HEMSOperationalDataService) Create(ctx context.Context, row *operation.HEMSOperationalData) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *HEMSOperationalDataService) Update(ctx context.Context, row *operation.HEMSOperationalData) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *HEMSOperationalDataService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *HEMSOperationalDataService) GetByID(ctx context.Context, id []byte) (*operation.HEMSOperationalData, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *HEMSOperationalDataService) List(ctx context.Context, filter, sort string, limit, offset int) ([]operation.HEMSOperationalData, int64, error) {
+	return s.repo.List(ctx, filter, normalizeHEMSOperationalDataSort(sort), limit, offset)
+}
+
+func normalizeHEMSOperationalDataSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortField("time"),
+		sortField("location"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/hospital_service.go b/internal/service/hospital_service.go
new file mode 100644
index 0000000..7bb5846
--- /dev/null
+++ b/internal/service/hospital_service.go
@@ -0,0 +1,55 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/hospital"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type HospitalService struct {
+	repo hospital.Repository
+}
+
+func NewHospitalService(repo hospital.Repository) *HospitalService {
+	return &HospitalService{repo: repo}
+}
+
+func (s *HospitalService) Create(ctx context.Context, row *hospital.Hospital) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *HospitalService) Update(ctx context.Context, row *hospital.Hospital) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *HospitalService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *HospitalService) GetByID(ctx context.Context, id []byte) (*hospital.Hospital, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *HospitalService) List(ctx context.Context, filter, sort string, limit, offset int) ([]hospital.Hospital, int64, error) {
+	return s.repo.List(ctx, filter, normalizeHospitalSort(sort), limit, offset)
+}
+
+func normalizeHospitalSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "hospital_name", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "hospital_name", true)),
+			"sortkey",
+		),
+		sortField("hospital_name", "name", "hospital_name"),
+		sortField("address"),
+		sortField("landline_number"),
+		sortField("mobile_number"),
+		sortField("email"),
+		sortField("note"),
+		sortField("created_at"),
+		sortField("updated_at"),
+		sortField("is_active"),
+	)
+}
diff --git a/internal/service/hospital_service_test.go b/internal/service/hospital_service_test.go
new file mode 100644
index 0000000..5e5559f
--- /dev/null
+++ b/internal/service/hospital_service_test.go
@@ -0,0 +1,233 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/hospital"
+)
+
+type hospitalRepoMock struct {
+	createCalled  bool
+	updateCalled  bool
+	deleteCalled  bool
+	getByIDCalled bool
+	listCalled    bool
+
+	lastCreate     *hospital.Hospital
+	lastUpdate     *hospital.Hospital
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastGetByID    []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+
+	getByIDResult *hospital.Hospital
+	listResult    []hospital.Hospital
+	listTotal     int64
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+}
+
+func (m *hospitalRepoMock) Create(_ context.Context, row *hospital.Hospital) error {
+	m.createCalled = true
+	m.lastCreate = row
+	return m.createErr
+}
+
+func (m *hospitalRepoMock) Update(_ context.Context, row *hospital.Hospital) error {
+	m.updateCalled = true
+	m.lastUpdate = row
+	return m.updateErr
+}
+
+func (m *hospitalRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return m.deleteErr
+}
+
+func (m *hospitalRepoMock) GetByID(_ context.Context, id []byte) (*hospital.Hospital, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *hospitalRepoMock) List(_ context.Context, filter, sort string, limit, offset int) ([]hospital.Hospital, int64, error) {
+	m.listCalled = true
+	m.lastListFilter = filter
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listResult, m.listTotal, m.listErr
+}
+
+func TestNewHospitalService(t *testing.T) {
+	repo := &hospitalRepoMock{}
+	svc := NewHospitalService(repo)
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service and repo initialized")
+	}
+}
+
+func TestHospitalServiceCreate(t *testing.T) {
+	repo := &hospitalRepoMock{}
+	svc := NewHospitalService(repo)
+	row := &hospital.Hospital{Name: "RSUD Kota", Address: "Jl. Merdeka"}
+
+	if err := svc.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.createCalled || repo.lastCreate != row {
+		t.Fatalf("expected Create forwarded to repo")
+	}
+
+	repo.createErr = errors.New("create failed")
+	if err := svc.Create(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHospitalServiceUpdate(t *testing.T) {
+	repo := &hospitalRepoMock{}
+	svc := NewHospitalService(repo)
+	row := &hospital.Hospital{Name: "RSUD Kota", Address: "Jl. Baru"}
+
+	if err := svc.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateCalled || repo.lastUpdate != row {
+		t.Fatalf("expected Update forwarded to repo")
+	}
+
+	repo.updateErr = errors.New("update failed")
+	if err := svc.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHospitalServiceDelete(t *testing.T) {
+	repo := &hospitalRepoMock{}
+	svc := NewHospitalService(repo)
+	id := []byte("id")
+	deletedBy := []byte("by")
+
+	if err := svc.Delete(context.Background(), id, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.deleteCalled {
+		t.Fatalf("expected Delete forwarded to repo")
+	}
+	if string(repo.lastDeleteID) != string(id) || string(repo.lastDeleteBy) != string(deletedBy) {
+		t.Fatalf("expected delete params forwarded")
+	}
+
+	repo.deleteErr = errors.New("delete failed")
+	if err := svc.Delete(context.Background(), id, deletedBy); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHospitalServiceGetByID(t *testing.T) {
+	expected := &hospital.Hospital{Name: "RSUD Kota", Address: "Jl. Merdeka"}
+	repo := &hospitalRepoMock{getByIDResult: expected}
+	svc := NewHospitalService(repo)
+	id := []byte("id")
+
+	got, err := svc.GetByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != expected {
+		t.Fatalf("unexpected result")
+	}
+	if !repo.getByIDCalled || string(repo.lastGetByID) != string(id) {
+		t.Fatalf("expected GetByID forwarded")
+	}
+
+	repo.getByIDErr = errors.New("get failed")
+	if _, err := svc.GetByID(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestHospitalServiceList(t *testing.T) {
+	repo := &hospitalRepoMock{
+		listResult: []hospital.Hospital{{Name: "RSUD Kota", Address: "Jl. Merdeka"}},
+		listTotal:  1,
+	}
+	svc := NewHospitalService(repo)
+
+	rows, total, err := svc.List(context.Background(), "find", "name", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if !repo.listCalled {
+		t.Fatalf("expected List forwarded to repo")
+	}
+	if repo.lastListFilter != "find" || repo.lastListSort != "hospital_name ASC" || repo.lastListLimit != 10 || repo.lastListOffset != 20 {
+		t.Fatalf("unexpected list args forwarded")
+	}
+
+	rows, total, err = svc.List(context.Background(), "find", "sortkey", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, hospital_name ASC" {
+		t.Fatalf("unexpected sortkey args forwarded: %q", repo.lastListSort)
+	}
+
+	repo.listErr = errors.New("list failed")
+	if _, _, err := svc.List(context.Background(), "", "unknown", 1, 0); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestNormalizeHospitalSort(t *testing.T) {
+	cases := map[string]string{
+		"name":             "hospital_name ASC",
+		"-name":            "hospital_name DESC",
+		"hospital_name":    "hospital_name ASC",
+		"-hospital_name":   "hospital_name DESC",
+		"sortkey":          "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, hospital_name ASC",
+		"-sortkey":         "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, hospital_name ASC",
+		"address":          "address ASC",
+		"-address":         "address DESC",
+		"landline_number":  "landline_number ASC",
+		"-landline_number": "landline_number DESC",
+		"mobile_number":    "mobile_number ASC",
+		"-mobile_number":   "mobile_number DESC",
+		"email":            "email ASC",
+		"-email":           "email DESC",
+		"note":             "note ASC",
+		"-note":            "note DESC",
+		"is_active":        "is_active ASC",
+		"-is_active":       "is_active DESC",
+		"created_at":       "created_at ASC",
+		"-created_at":      "created_at DESC",
+		"updated_at":       "updated_at ASC",
+		"-updated_at":      "updated_at DESC",
+		"unknown":          "",
+		"":                 "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeHospitalSort(in); got != want {
+			t.Fatalf("normalizeHospitalSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/icao_service.go b/internal/service/icao_service.go
new file mode 100644
index 0000000..ab82111
--- /dev/null
+++ b/internal/service/icao_service.go
@@ -0,0 +1,56 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/icao"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type ICAOService struct {
+	repo icao.Repository
+}
+
+func NewICAOService(repo icao.Repository) *ICAOService {
+	return &ICAOService{repo: repo}
+}
+
+func (s *ICAOService) Create(ctx context.Context, row *icao.ICAO) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *ICAOService) Update(ctx context.Context, row *icao.ICAO) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *ICAOService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *ICAOService) GetByID(ctx context.Context, id []byte) (*icao.ICAO, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *ICAOService) List(ctx context.Context, filter, sort string, limit, offset int) ([]icao.ICAO, int64, error) {
+	return s.repo.List(ctx, filter, normalizeICAOSort(sort), limit, offset)
+}
+
+func normalizeICAOSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "icao_code", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "icao_code", true)),
+			"sortkey",
+		),
+		sortField("name"),
+		sortField("icao_code"),
+		sortField("address"),
+		sortField("landline_number"),
+		sortField("mobile_number"),
+		sortField("email"),
+		sortField("note"),
+		sortField("is_active"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/icao_service_test.go b/internal/service/icao_service_test.go
new file mode 100644
index 0000000..277480a
--- /dev/null
+++ b/internal/service/icao_service_test.go
@@ -0,0 +1,231 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/icao"
+)
+
+type icaoRepoMock struct {
+	createCalled  bool
+	updateCalled  bool
+	deleteCalled  bool
+	getByIDCalled bool
+	listCalled    bool
+
+	lastCreate     *icao.ICAO
+	lastUpdate     *icao.ICAO
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastGetByID    []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+
+	getByIDResult *icao.ICAO
+	listResult    []icao.ICAO
+	listTotal     int64
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+}
+
+func (m *icaoRepoMock) Create(_ context.Context, o *icao.ICAO) error {
+	m.createCalled = true
+	m.lastCreate = o
+	return m.createErr
+}
+
+func (m *icaoRepoMock) Update(_ context.Context, o *icao.ICAO) error {
+	m.updateCalled = true
+	m.lastUpdate = o
+	return m.updateErr
+}
+
+func (m *icaoRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return m.deleteErr
+}
+
+func (m *icaoRepoMock) GetByID(_ context.Context, id []byte) (*icao.ICAO, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *icaoRepoMock) List(_ context.Context, filter, sort string, limit, offset int) ([]icao.ICAO, int64, error) {
+	m.listCalled = true
+	m.lastListFilter = filter
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listResult, m.listTotal, m.listErr
+}
+
+func TestNewICAOService(t *testing.T) {
+	repo := &icaoRepoMock{}
+	svc := NewICAOService(repo)
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service and repo initialized")
+	}
+}
+
+func TestICAOServiceCreate(t *testing.T) {
+	repo := &icaoRepoMock{}
+	svc := NewICAOService(repo)
+	row := &icao.ICAO{ICAOCode: "EDDB"}
+
+	if err := svc.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.createCalled || repo.lastCreate != row {
+		t.Fatalf("expected Create forwarded to repo")
+	}
+
+	repo.createErr = errors.New("create failed")
+	if err := svc.Create(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestICAOServiceUpdate(t *testing.T) {
+	repo := &icaoRepoMock{}
+	svc := NewICAOService(repo)
+	row := &icao.ICAO{ICAOCode: "EDDF"}
+
+	if err := svc.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateCalled || repo.lastUpdate != row {
+		t.Fatalf("expected Update forwarded to repo")
+	}
+
+	repo.updateErr = errors.New("update failed")
+	if err := svc.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestICAOServiceDelete(t *testing.T) {
+	repo := &icaoRepoMock{}
+	svc := NewICAOService(repo)
+	id := []byte("id")
+	deletedBy := []byte("by")
+
+	if err := svc.Delete(context.Background(), id, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.deleteCalled {
+		t.Fatalf("expected Delete forwarded to repo")
+	}
+	if string(repo.lastDeleteID) != string(id) || string(repo.lastDeleteBy) != string(deletedBy) {
+		t.Fatalf("expected delete params forwarded")
+	}
+
+	repo.deleteErr = errors.New("delete failed")
+	if err := svc.Delete(context.Background(), id, deletedBy); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestICAOServiceGetByID(t *testing.T) {
+	expected := &icao.ICAO{ICAOCode: "A"}
+	repo := &icaoRepoMock{getByIDResult: expected}
+	svc := NewICAOService(repo)
+	id := []byte("id")
+
+	got, err := svc.GetByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != expected {
+		t.Fatalf("unexpected result")
+	}
+	if !repo.getByIDCalled || string(repo.lastGetByID) != string(id) {
+		t.Fatalf("expected GetByID forwarded")
+	}
+
+	repo.getByIDErr = errors.New("get failed")
+	if _, err := svc.GetByID(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestICAOServiceList(t *testing.T) {
+	repo := &icaoRepoMock{
+		listResult: []icao.ICAO{{ICAOCode: "A"}},
+		listTotal:  1,
+	}
+	svc := NewICAOService(repo)
+
+	rows, total, err := svc.List(context.Background(), "find", "icao_code", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if !repo.listCalled {
+		t.Fatalf("expected List forwarded to repo")
+	}
+	if repo.lastListFilter != "find" || repo.lastListSort != "icao_code ASC" || repo.lastListLimit != 10 || repo.lastListOffset != 20 {
+		t.Fatalf("unexpected list args forwarded")
+	}
+
+	rows, total, err = svc.List(context.Background(), "find", "sortkey", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, icao_code ASC" {
+		t.Fatalf("unexpected sortkey args forwarded: %q", repo.lastListSort)
+	}
+
+	repo.listErr = errors.New("list failed")
+	if _, _, err := svc.List(context.Background(), "", "unknown", 1, 0); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestNormalizeICAOSort(t *testing.T) {
+	cases := map[string]string{
+		"icao_code":        "icao_code ASC",
+		"-icao_code":       "icao_code DESC",
+		"sortkey":          "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, icao_code ASC",
+		"-sortkey":         "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, icao_code ASC",
+		"address":          "address ASC",
+		"-address":         "address DESC",
+		"landline_number":  "landline_number ASC",
+		"-landline_number": "landline_number DESC",
+		"mobile_number":    "mobile_number ASC",
+		"-mobile_number":   "mobile_number DESC",
+		"email":            "email ASC",
+		"-email":           "email DESC",
+		"note":             "note ASC",
+		"-note":            "note DESC",
+		"is_active":        "is_active ASC",
+		"-is_active":       "is_active DESC",
+		"created_at":       "created_at ASC",
+		"-created_at":      "created_at DESC",
+		"updated_at":       "updated_at ASC",
+		"-updated_at":      "updated_at DESC",
+		"unknown":          "",
+		"":                 "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeICAOSort(in); got != want {
+			t.Fatalf("normalizeICAOSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/insurance_patient_data_service.go b/internal/service/insurance_patient_data_service.go
new file mode 100644
index 0000000..cbbf963
--- /dev/null
+++ b/internal/service/insurance_patient_data_service.go
@@ -0,0 +1,42 @@
+package service
+
+import (
+	"context"
+
+	insurancepatientdata "wucher/internal/domain/insurance_patient_data"
+)
+
+type InsurancePatientDataService struct {
+	repo insurancepatientdata.Repository
+}
+
+func NewInsurancePatientDataService(repo insurancepatientdata.Repository) *InsurancePatientDataService {
+	return &InsurancePatientDataService{repo: repo}
+}
+
+func (s *InsurancePatientDataService) Create(ctx context.Context, row *insurancepatientdata.InsurancePatientData) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *InsurancePatientDataService) Update(ctx context.Context, row *insurancepatientdata.InsurancePatientData) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *InsurancePatientDataService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *InsurancePatientDataService) GetByID(ctx context.Context, id []byte) (*insurancepatientdata.InsurancePatientData, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *InsurancePatientDataService) List(ctx context.Context, filter, sort string, limit, offset int) ([]insurancepatientdata.InsurancePatientData, int64, error) {
+	return s.repo.List(ctx, filter, normalizeInsurancePatientDataSort(sort), limit, offset)
+}
+
+func normalizeInsurancePatientDataSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/land_service.go b/internal/service/land_service.go
new file mode 100644
index 0000000..5d56d3e
--- /dev/null
+++ b/internal/service/land_service.go
@@ -0,0 +1,81 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/land"
+	"wucher/internal/shared/pkg/sortkey"
+	"wucher/internal/transport/http/dto"
+)
+
+type LandService struct {
+	repo land.Repository
+}
+
+func NewLandService(repo land.Repository) *LandService {
+	return &LandService{repo: repo}
+}
+
+func (s *LandService) Create(ctx context.Context, row *land.Land) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *LandService) Update(ctx context.Context, row *land.Land) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *LandService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *LandService) GetByID(ctx context.Context, id []byte) (*land.Land, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *LandService) List(ctx context.Context, filter, sort string, limit, offset int) ([]land.Land, int64, error) {
+	return s.repo.List(ctx, filter, normalizeLandSort(sort), limit, offset)
+}
+
+func (s *LandService) GetByIDView(ctx context.Context, id []byte) (*dto.LandView, error) {
+	if repo, ok := s.repo.(interface {
+		GetByIDView(context.Context, []byte) (*dto.LandView, error)
+	}); ok {
+		return repo.GetByIDView(ctx, id)
+	}
+	row, err := s.repo.GetByID(ctx, id)
+	if err != nil || row == nil {
+		return nil, err
+	}
+	return &dto.LandView{Row: *row}, nil
+}
+
+func (s *LandService) ListView(ctx context.Context, filter, sort string, limit, offset int) ([]dto.LandView, int64, error) {
+	if repo, ok := s.repo.(interface {
+		ListView(context.Context, string, string, int, int) ([]dto.LandView, int64, error)
+	}); ok {
+		return repo.ListView(ctx, filter, normalizeLandSort(sort), limit, offset)
+	}
+	rows, total, err := s.repo.List(ctx, filter, normalizeLandSort(sort), limit, offset)
+	if err != nil {
+		return nil, 0, err
+	}
+	views := make([]dto.LandView, 0, len(rows))
+	for i := range rows {
+		views = append(views, dto.LandView{Row: rows[i]})
+	}
+	return views, total, nil
+}
+
+func normalizeLandSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", true)),
+			"sortkey",
+		),
+		sortField("name"),
+		sortField("is_active"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/land_service_test.go b/internal/service/land_service_test.go
new file mode 100644
index 0000000..d3a1967
--- /dev/null
+++ b/internal/service/land_service_test.go
@@ -0,0 +1,221 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/land"
+)
+
+type landRepoMock struct {
+	createCalled  bool
+	updateCalled  bool
+	deleteCalled  bool
+	getByIDCalled bool
+	listCalled    bool
+
+	lastCreate     *land.Land
+	lastUpdate     *land.Land
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastGetByID    []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+
+	getByIDResult *land.Land
+	listResult    []land.Land
+	listTotal     int64
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+}
+
+func (m *landRepoMock) Create(_ context.Context, o *land.Land) error {
+	m.createCalled = true
+	m.lastCreate = o
+	return m.createErr
+}
+
+func (m *landRepoMock) Update(_ context.Context, o *land.Land) error {
+	m.updateCalled = true
+	m.lastUpdate = o
+	return m.updateErr
+}
+
+func (m *landRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return m.deleteErr
+}
+
+func (m *landRepoMock) GetByID(_ context.Context, id []byte) (*land.Land, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *landRepoMock) List(_ context.Context, filter, sort string, limit, offset int) ([]land.Land, int64, error) {
+	m.listCalled = true
+	m.lastListFilter = filter
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listResult, m.listTotal, m.listErr
+}
+
+func TestNewLandService(t *testing.T) {
+	repo := &landRepoMock{}
+	svc := NewLandService(repo)
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service and repo initialized")
+	}
+}
+
+func TestLandServiceCreate(t *testing.T) {
+	repo := &landRepoMock{}
+	svc := NewLandService(repo)
+	row := &land.Land{Name: "Germany"}
+
+	if err := svc.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.createCalled || repo.lastCreate != row {
+		t.Fatalf("expected Create forwarded to repo")
+	}
+
+	repo.createErr = errors.New("create failed")
+	if err := svc.Create(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestLandServiceUpdate(t *testing.T) {
+	repo := &landRepoMock{}
+	svc := NewLandService(repo)
+	row := &land.Land{Name: "Updated"}
+
+	if err := svc.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateCalled || repo.lastUpdate != row {
+		t.Fatalf("expected Update forwarded to repo")
+	}
+
+	repo.updateErr = errors.New("update failed")
+	if err := svc.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestLandServiceDelete(t *testing.T) {
+	repo := &landRepoMock{}
+	svc := NewLandService(repo)
+	id := []byte("id")
+	deletedBy := []byte("by")
+
+	if err := svc.Delete(context.Background(), id, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.deleteCalled {
+		t.Fatalf("expected Delete forwarded to repo")
+	}
+	if string(repo.lastDeleteID) != string(id) || string(repo.lastDeleteBy) != string(deletedBy) {
+		t.Fatalf("expected delete params forwarded")
+	}
+
+	repo.deleteErr = errors.New("delete failed")
+	if err := svc.Delete(context.Background(), id, deletedBy); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestLandServiceGetByID(t *testing.T) {
+	expected := &land.Land{Name: "A"}
+	repo := &landRepoMock{getByIDResult: expected}
+	svc := NewLandService(repo)
+	id := []byte("id")
+
+	got, err := svc.GetByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != expected {
+		t.Fatalf("unexpected result")
+	}
+	if !repo.getByIDCalled || string(repo.lastGetByID) != string(id) {
+		t.Fatalf("expected GetByID forwarded")
+	}
+
+	repo.getByIDErr = errors.New("get failed")
+	if _, err := svc.GetByID(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestLandServiceList(t *testing.T) {
+	repo := &landRepoMock{
+		listResult: []land.Land{{Name: "A"}},
+		listTotal:  1,
+	}
+	svc := NewLandService(repo)
+
+	rows, total, err := svc.List(context.Background(), "find", "name", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if !repo.listCalled {
+		t.Fatalf("expected List forwarded to repo")
+	}
+	if repo.lastListFilter != "find" || repo.lastListSort != "name ASC" || repo.lastListLimit != 10 || repo.lastListOffset != 20 {
+		t.Fatalf("unexpected list args forwarded")
+	}
+
+	rows, total, err = svc.List(context.Background(), "find", "sortkey", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC" {
+		t.Fatalf("unexpected sortkey args forwarded: %q", repo.lastListSort)
+	}
+
+	repo.listErr = errors.New("list failed")
+	if _, _, err := svc.List(context.Background(), "", "unknown", 1, 0); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestNormalizeLandSort(t *testing.T) {
+	cases := map[string]string{
+		"name":        "name ASC",
+		"-name":       "name DESC",
+		"sortkey":     "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC",
+		"-sortkey":    "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC",
+		"is_active":   "is_active ASC",
+		"-is_active":  "is_active DESC",
+		"created_at":  "created_at ASC",
+		"-created_at": "created_at DESC",
+		"updated_at":  "updated_at ASC",
+		"-updated_at": "updated_at DESC",
+		"unknown":     "",
+		"":            "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeLandSort(in); got != want {
+			t.Fatalf("normalizeLandSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/master_settings_service.go b/internal/service/master_settings_service.go
new file mode 100644
index 0000000..bd8fccb
--- /dev/null
+++ b/internal/service/master_settings_service.go
@@ -0,0 +1,439 @@
+package service
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"net/url"
+	"strconv"
+	"strings"
+
+	"wucher/internal/config"
+	mastersettings "wucher/internal/domain/master_settings"
+)
+
+type MasterSettingsService struct {
+	repo      mastersettings.Repository
+	protector SecretProtector
+}
+
+type MasterSettingsServiceDependencies struct {
+	Protector SecretProtector
+}
+
+func NewMasterSettingsService(repo mastersettings.Repository, deps MasterSettingsServiceDependencies) *MasterSettingsService {
+	return &MasterSettingsService{
+		repo:      repo,
+		protector: deps.Protector,
+	}
+}
+
+func (s *MasterSettingsService) SetSecretProtector(protector SecretProtector) *MasterSettingsService {
+	if s == nil {
+		return nil
+	}
+	s.protector = protector
+	return s
+}
+
+func (s *MasterSettingsService) Create(ctx context.Context, row *mastersettings.MasterSettings) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *MasterSettingsService) Update(ctx context.Context, row *mastersettings.MasterSettings) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *MasterSettingsService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *MasterSettingsService) GetByID(ctx context.Context, id []byte) (*mastersettings.MasterSettings, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *MasterSettingsService) List(ctx context.Context, filter, sort string, limit, offset int) ([]mastersettings.MasterSettings, int64, error) {
+	return s.repo.List(ctx, filter, normalizeMasterSettingsSort(sort), limit, offset)
+}
+
+func (s *MasterSettingsService) UpsertMicrosoftEntraConfig(
+	ctx context.Context,
+	input mastersettings.MicrosoftEntraConfigInput,
+	actor []byte,
+) (*mastersettings.MicrosoftEntraConfigView, error) {
+	normalized, err := normalizeMicrosoftEntraConfigInput(input)
+	if err != nil {
+		return nil, err
+	}
+
+	rows := []mastersettings.MasterSettingValue{
+		{
+			SettingKey:  mastersettings.SettingMicrosoftEntraTenantID,
+			Value:       normalized.TenantID,
+			CreatedBy:   actor,
+			UpdatedBy:   actor,
+			IsEncrypted: false,
+		},
+		{
+			SettingKey:  mastersettings.SettingMicrosoftEntraClientID,
+			Value:       normalized.ClientID,
+			CreatedBy:   actor,
+			UpdatedBy:   actor,
+			IsEncrypted: false,
+		},
+		{
+			SettingKey:  mastersettings.SettingMicrosoftEntraRedirectURL,
+			Value:       normalized.RedirectURL,
+			CreatedBy:   actor,
+			UpdatedBy:   actor,
+			IsEncrypted: false,
+		},
+		{
+			SettingKey:  mastersettings.SettingMicrosoftEntraAuthority,
+			Value:       normalized.Authority,
+			CreatedBy:   actor,
+			UpdatedBy:   actor,
+			IsEncrypted: false,
+		},
+		{
+			SettingKey:  mastersettings.SettingMicrosoftEntraScopes,
+			Value:       normalized.Scopes,
+			CreatedBy:   actor,
+			UpdatedBy:   actor,
+			IsEncrypted: false,
+		},
+	}
+	if normalized.ClientSecret != "" {
+		if s.protector == nil {
+			return nil, errors.New("secret protector not configured")
+		}
+		encryptedSecret, err := s.protector.Encrypt([]byte(normalized.ClientSecret))
+		if err != nil {
+			return nil, fmt.Errorf("encrypt MS_ENTRA_CLIENT_SECRET: %w", err)
+		}
+		encodedSecret := base64.StdEncoding.EncodeToString(encryptedSecret)
+		rows = append(rows, mastersettings.MasterSettingValue{
+			SettingKey:  mastersettings.SettingMicrosoftEntraClientSecret,
+			Value:       encodedSecret,
+			CreatedBy:   actor,
+			UpdatedBy:   actor,
+			IsEncrypted: true,
+		})
+	} else {
+		existingSecretRows, err := s.repo.GetSettingValuesByKeys(ctx, []string{mastersettings.SettingMicrosoftEntraClientSecret})
+		if err != nil {
+			return nil, err
+		}
+		_, _, existingSecret, _, _, _, _ := extractMicrosoftEntraValues(existingSecretRows)
+		if strings.TrimSpace(existingSecret) == "" {
+			return nil, errors.New("MS_ENTRA_CLIENT_SECRET is required for initial setup")
+		}
+	}
+	if err := s.repo.UpsertSettingValues(ctx, rows); err != nil {
+		return nil, err
+	}
+	return s.GetMicrosoftEntraConfig(ctx)
+}
+
+func (s *MasterSettingsService) GetMicrosoftEntraConfig(ctx context.Context) (*mastersettings.MicrosoftEntraConfigView, error) {
+	rows, err := s.repo.GetSettingValuesByKeys(ctx, mastersettings.MicrosoftEntraSettingKeys)
+	if err != nil {
+		return nil, err
+	}
+	tenant, clientID, secret, redirectURL, authority, scopes, encrypted := extractMicrosoftEntraValues(rows)
+	// UI view supports partial config so non-sensitive bootstrapped keys can be rendered.
+	// Runtime login flow still uses LoadMicrosoftEntraRuntimeConfig, which remains strict.
+	if redirectURL == "" || authority == "" || scopes == "" {
+		return nil, nil
+	}
+
+	secretMasked := ""
+	if secret != "" && encrypted {
+		secretMasked = "********"
+	} else if secret != "" {
+		secretMasked = maskMicrosoftSecret(secret)
+	}
+
+	return &mastersettings.MicrosoftEntraConfigView{
+		TenantID:           tenant,
+		ClientID:           clientID,
+		ClientSecretMasked: secretMasked,
+		RedirectURL:        redirectURL,
+		Authority:          authority,
+		Scopes:             scopes,
+	}, nil
+}
+
+func (s *MasterSettingsService) LoadMicrosoftEntraRuntimeConfig(ctx context.Context) (config.MicrosoftSSOConfig, error) {
+	rows, err := s.repo.GetSettingValuesByKeys(ctx, mastersettings.MicrosoftEntraSettingKeys)
+	if err != nil {
+		return config.MicrosoftSSOConfig{}, err
+	}
+	tenant, clientID, secret, redirectURL, authority, scopes, encrypted := extractMicrosoftEntraValues(rows)
+	if tenant == "" || clientID == "" || secret == "" || redirectURL == "" || authority == "" || scopes == "" {
+		return config.MicrosoftSSOConfig{}, errors.New("sso not configured")
+	}
+
+	plainSecret := secret
+	if encrypted {
+		if s.protector == nil {
+			return config.MicrosoftSSOConfig{}, errors.New("secret protector not configured")
+		}
+		cipherBytes, err := base64.StdEncoding.DecodeString(secret)
+		if err != nil {
+			return config.MicrosoftSSOConfig{}, errors.New("invalid encrypted MS_ENTRA_CLIENT_SECRET")
+		}
+		plainBytes, err := s.protector.Decrypt(cipherBytes)
+		if err != nil {
+			return config.MicrosoftSSOConfig{}, errors.New("failed to decrypt MS_ENTRA_CLIENT_SECRET")
+		}
+		plainSecret = strings.TrimSpace(string(plainBytes))
+	}
+	if plainSecret == "" {
+		return config.MicrosoftSSOConfig{}, errors.New("sso not configured")
+	}
+
+	return config.MicrosoftSSOConfig{
+		TenantID:     tenant,
+		ClientID:     clientID,
+		ClientSecret: plainSecret,
+		RedirectURL:  redirectURL,
+		Authority:    authority,
+		Scopes:       splitCSV(scopes),
+	}, nil
+}
+
+func (s *MasterSettingsService) IsLoginEmailOTPEnabled(ctx context.Context) (bool, error) {
+	if s == nil || s.repo == nil {
+		return true, nil
+	}
+	rows, err := s.repo.GetSettingValuesByKeys(ctx, []string{mastersettings.SettingAuthLoginEmailOTPEnabled})
+	if err != nil {
+		return true, err
+	}
+	if len(rows) == 0 {
+		return true, nil
+	}
+	raw := strings.TrimSpace(rows[0].Value)
+	if raw == "" {
+		return true, nil
+	}
+	enabled, parseErr := strconv.ParseBool(raw)
+	if parseErr != nil {
+		return true, nil
+	}
+	return enabled, nil
+}
+
+// SeedMicrosoftEntraConfigIfMissing backfills missing non-sensitive SSO setting keys from app config.
+// Existing non-empty values are preserved.
+func (s *MasterSettingsService) SeedMicrosoftEntraConfigIfMissing(
+	ctx context.Context,
+	cfg config.MicrosoftSSOConfig,
+) error {
+	if s == nil || s.repo == nil {
+		return nil
+	}
+
+	rows, err := s.repo.GetSettingValuesByKeys(ctx, mastersettings.MicrosoftEntraSettingKeys)
+	if err != nil {
+		return err
+	}
+	existing := make(map[string]mastersettings.MasterSettingValue, len(rows))
+	for i := range rows {
+		key := strings.TrimSpace(rows[i].SettingKey)
+		if key == "" {
+			continue
+		}
+		existing[key] = rows[i]
+	}
+	isMissing := func(key string) bool {
+		row, ok := existing[key]
+		if !ok {
+			return true
+		}
+		return strings.TrimSpace(row.Value) == ""
+	}
+
+	normalized, err := normalizeMicrosoftEntraConfigInput(mastersettings.MicrosoftEntraConfigInput{
+		// Only validate and seed non-sensitive fields.
+		// Tenant ID, Client ID, and Client Secret are intentionally excluded.
+		TenantID:     "placeholder",
+		ClientID:     "placeholder",
+		ClientSecret: "placeholder",
+		RedirectURL:  cfg.RedirectURL,
+		Authority:    cfg.Authority,
+		Scopes:       strings.Join(cfg.Scopes, ","),
+	})
+	if err != nil {
+		return err
+	}
+
+	insertRows := make([]mastersettings.MasterSettingValue, 0, 3)
+	if isMissing(mastersettings.SettingMicrosoftEntraRedirectURL) {
+		insertRows = append(insertRows, mastersettings.MasterSettingValue{
+			SettingKey:  mastersettings.SettingMicrosoftEntraRedirectURL,
+			Value:       normalized.RedirectURL,
+			IsEncrypted: false,
+		})
+	}
+	if isMissing(mastersettings.SettingMicrosoftEntraAuthority) {
+		insertRows = append(insertRows, mastersettings.MasterSettingValue{
+			SettingKey:  mastersettings.SettingMicrosoftEntraAuthority,
+			Value:       normalized.Authority,
+			IsEncrypted: false,
+		})
+	}
+	if isMissing(mastersettings.SettingMicrosoftEntraScopes) {
+		insertRows = append(insertRows, mastersettings.MasterSettingValue{
+			SettingKey:  mastersettings.SettingMicrosoftEntraScopes,
+			Value:       normalized.Scopes,
+			IsEncrypted: false,
+		})
+	}
+
+	if len(insertRows) == 0 {
+		return nil
+	}
+	return s.repo.UpsertSettingValues(ctx, insertRows)
+}
+
+func normalizeMasterSettingsSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortField("company_name"),
+		sortField("title"),
+		sortField("subtitle"),
+		sortField("logo_url"),
+		sortField("logo_file_id", "logo_file_uuid"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
+
+func normalizeMicrosoftEntraConfigInput(input mastersettings.MicrosoftEntraConfigInput) (mastersettings.MicrosoftEntraConfigInput, error) {
+	normalized := mastersettings.MicrosoftEntraConfigInput{
+		TenantID:     strings.TrimSpace(input.TenantID),
+		ClientID:     strings.TrimSpace(input.ClientID),
+		ClientSecret: strings.TrimSpace(input.ClientSecret),
+		RedirectURL:  strings.TrimSpace(input.RedirectURL),
+		Authority:    strings.TrimSpace(input.Authority),
+		Scopes:       normalizeCSV(input.Scopes),
+	}
+
+	if normalized.TenantID == "" {
+		return mastersettings.MicrosoftEntraConfigInput{}, errors.New("MS_ENTRA_TENANT_ID is required")
+	}
+	if normalized.ClientID == "" {
+		return mastersettings.MicrosoftEntraConfigInput{}, errors.New("MS_ENTRA_CLIENT_ID is required")
+	}
+	if normalized.RedirectURL == "" {
+		return mastersettings.MicrosoftEntraConfigInput{}, errors.New("MS_ENTRA_REDIRECT_URL is required")
+	}
+	if normalized.Authority == "" {
+		return mastersettings.MicrosoftEntraConfigInput{}, errors.New("MS_ENTRA_AUTHORITY is required")
+	}
+	if normalized.Scopes == "" {
+		return mastersettings.MicrosoftEntraConfigInput{}, errors.New("MS_ENTRA_SCOPES is required")
+	}
+	if !isValidHTTPURL(normalized.RedirectURL) {
+		return mastersettings.MicrosoftEntraConfigInput{}, errors.New("MS_ENTRA_REDIRECT_URL must be a valid absolute URL")
+	}
+	if !isValidAuthorityURL(normalized.Authority) {
+		return mastersettings.MicrosoftEntraConfigInput{}, errors.New("MS_ENTRA_AUTHORITY must be a valid absolute URL with scheme")
+	}
+	normalized.Authority = ensureTrailingSlash(normalized.Authority)
+
+	return normalized, nil
+}
+
+func normalizeCSV(raw string) string {
+	parts := strings.Split(raw, ",")
+	items := make([]string, 0, len(parts))
+	seen := make(map[string]struct{}, len(parts))
+	for _, part := range parts {
+		item := strings.TrimSpace(part)
+		if item == "" {
+			continue
+		}
+		if _, ok := seen[item]; ok {
+			continue
+		}
+		seen[item] = struct{}{}
+		items = append(items, item)
+	}
+	return strings.Join(items, ",")
+}
+
+func isValidHTTPURL(raw string) bool {
+	u, err := url.Parse(raw)
+	if err != nil {
+		return false
+	}
+	if u == nil || !u.IsAbs() || strings.TrimSpace(u.Host) == "" {
+		return false
+	}
+	switch strings.ToLower(strings.TrimSpace(u.Scheme)) {
+	case "http", "https":
+		return true
+	default:
+		return false
+	}
+}
+
+func isValidAuthorityURL(raw string) bool {
+	u, err := url.Parse(raw)
+	if err != nil {
+		return false
+	}
+	return u != nil && u.IsAbs() && strings.TrimSpace(u.Host) != "" && strings.TrimSpace(u.Scheme) != ""
+}
+
+func ensureTrailingSlash(raw string) string {
+	if strings.HasSuffix(raw, "/") {
+		return raw
+	}
+	return raw + "/"
+}
+
+func maskMicrosoftSecret(secret string) string {
+	secret = strings.TrimSpace(secret)
+	if secret == "" {
+		return ""
+	}
+	if len(secret) <= 4 {
+		return "****"
+	}
+	return strings.Repeat("*", len(secret)-4) + secret[len(secret)-4:]
+}
+
+func extractMicrosoftEntraValues(rows []mastersettings.MasterSettingValue) (tenant, clientID, secret, redirectURL, authority, scopes string, encrypted bool) {
+	if len(rows) == 0 {
+		return "", "", "", "", "", "", false
+	}
+	values := make(map[string]mastersettings.MasterSettingValue, len(rows))
+	for i := range rows {
+		values[rows[i].SettingKey] = rows[i]
+	}
+	tenant = strings.TrimSpace(values[mastersettings.SettingMicrosoftEntraTenantID].Value)
+	clientID = strings.TrimSpace(values[mastersettings.SettingMicrosoftEntraClientID].Value)
+	secret = strings.TrimSpace(values[mastersettings.SettingMicrosoftEntraClientSecret].Value)
+	redirectURL = strings.TrimSpace(values[mastersettings.SettingMicrosoftEntraRedirectURL].Value)
+	authority = strings.TrimSpace(values[mastersettings.SettingMicrosoftEntraAuthority].Value)
+	scopes = strings.TrimSpace(values[mastersettings.SettingMicrosoftEntraScopes].Value)
+	encrypted = values[mastersettings.SettingMicrosoftEntraClientSecret].IsEncrypted
+	return tenant, clientID, secret, redirectURL, authority, scopes, encrypted
+}
+
+func splitCSV(raw string) []string {
+	parts := strings.Split(raw, ",")
+	items := make([]string, 0, len(parts))
+	for _, part := range parts {
+		item := strings.TrimSpace(part)
+		if item == "" {
+			continue
+		}
+		items = append(items, item)
+	}
+	return items
+}
diff --git a/internal/service/master_settings_service_test.go b/internal/service/master_settings_service_test.go
new file mode 100644
index 0000000..890de43
--- /dev/null
+++ b/internal/service/master_settings_service_test.go
@@ -0,0 +1,434 @@
+package service
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"testing"
+
+	"wucher/internal/config"
+	mastersettings "wucher/internal/domain/master_settings"
+)
+
+type masterSettingsRepoMock struct {
+	createErr error
+	updateErr error
+	deleteErr error
+	getErr    error
+	listErr   error
+
+	lastCreate     *mastersettings.MasterSettings
+	lastUpdate     *mastersettings.MasterSettings
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastGetID      []byte
+	lastListSort   string
+	lastListFilter string
+	lastListLimit  int
+	lastListOffset int
+
+	getRow    *mastersettings.MasterSettings
+	listRows  []mastersettings.MasterSettings
+	listTotal int64
+
+	lastSettingRows []mastersettings.MasterSettingValue
+	lastSettingKeys []string
+	settingRows     []mastersettings.MasterSettingValue
+	settingErr      error
+}
+
+func (m *masterSettingsRepoMock) Create(_ context.Context, row *mastersettings.MasterSettings) error {
+	m.lastCreate = row
+	return m.createErr
+}
+
+func (m *masterSettingsRepoMock) Update(_ context.Context, row *mastersettings.MasterSettings) error {
+	m.lastUpdate = row
+	return m.updateErr
+}
+
+func (m *masterSettingsRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	m.lastDeleteID = append([]byte(nil), id...)
+	m.lastDeleteBy = append([]byte(nil), deletedBy...)
+	return m.deleteErr
+}
+
+func (m *masterSettingsRepoMock) GetByID(_ context.Context, id []byte) (*mastersettings.MasterSettings, error) {
+	m.lastGetID = append([]byte(nil), id...)
+	return m.getRow, m.getErr
+}
+
+func (m *masterSettingsRepoMock) List(_ context.Context, filter, sort string, limit, offset int) ([]mastersettings.MasterSettings, int64, error) {
+	m.lastListFilter = filter
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listRows, m.listTotal, m.listErr
+}
+
+func (m *masterSettingsRepoMock) UpsertSettingValues(_ context.Context, rows []mastersettings.MasterSettingValue) error {
+	m.lastSettingRows = append([]mastersettings.MasterSettingValue(nil), rows...)
+	return m.settingErr
+}
+
+func (m *masterSettingsRepoMock) GetSettingValuesByKeys(_ context.Context, keys []string) ([]mastersettings.MasterSettingValue, error) {
+	m.lastSettingKeys = append([]string(nil), keys...)
+	return append([]mastersettings.MasterSettingValue(nil), m.settingRows...), m.settingErr
+}
+
+func TestNewMasterSettingsService(t *testing.T) {
+	svc := NewMasterSettingsService(&masterSettingsRepoMock{}, MasterSettingsServiceDependencies{})
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service initialized")
+	}
+}
+
+func TestMasterSettingsServiceCreateUpdateDeleteGetByID(t *testing.T) {
+	ctx := context.Background()
+	row := &mastersettings.MasterSettings{CompanyName: "Wucher"}
+	id := []byte("1234567890123456")
+	actor := []byte("abcdefghijklmnop")
+
+	t.Run("create success and error", func(t *testing.T) {
+		repo := &masterSettingsRepoMock{}
+		svc := NewMasterSettingsService(repo, MasterSettingsServiceDependencies{})
+		if err := svc.Create(ctx, row); err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if repo.lastCreate != row {
+			t.Fatalf("expected row passed to repo")
+		}
+
+		repo.createErr = errors.New("create failed")
+		if err := svc.Create(ctx, row); err == nil {
+			t.Fatalf("expected create error")
+		}
+	})
+
+	t.Run("update success and error", func(t *testing.T) {
+		repo := &masterSettingsRepoMock{}
+		svc := NewMasterSettingsService(repo, MasterSettingsServiceDependencies{})
+		if err := svc.Update(ctx, row); err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if repo.lastUpdate != row {
+			t.Fatalf("expected row passed to repo")
+		}
+
+		repo.updateErr = errors.New("update failed")
+		if err := svc.Update(ctx, row); err == nil {
+			t.Fatalf("expected update error")
+		}
+	})
+
+	t.Run("delete success and error", func(t *testing.T) {
+		repo := &masterSettingsRepoMock{}
+		svc := NewMasterSettingsService(repo, MasterSettingsServiceDependencies{})
+		if err := svc.Delete(ctx, id, actor); err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if string(repo.lastDeleteID) != string(id) || string(repo.lastDeleteBy) != string(actor) {
+			t.Fatalf("expected id and deletedBy passed to repo")
+		}
+
+		repo.deleteErr = errors.New("delete failed")
+		if err := svc.Delete(ctx, id, actor); err == nil {
+			t.Fatalf("expected delete error")
+		}
+	})
+
+	t.Run("get by id success and error", func(t *testing.T) {
+		repo := &masterSettingsRepoMock{getRow: row}
+		svc := NewMasterSettingsService(repo, MasterSettingsServiceDependencies{})
+		got, err := svc.GetByID(ctx, id)
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if got != row {
+			t.Fatalf("expected repo row returned")
+		}
+		if string(repo.lastGetID) != string(id) {
+			t.Fatalf("expected id passed to repo")
+		}
+
+		repo.getErr = errors.New("get failed")
+		if _, err := svc.GetByID(ctx, id); err == nil {
+			t.Fatalf("expected get error")
+		}
+	})
+}
+
+func TestMasterSettingsServiceList(t *testing.T) {
+	ctx := context.Background()
+	repo := &masterSettingsRepoMock{
+		listRows:  []mastersettings.MasterSettings{{CompanyName: "Wucher"}},
+		listTotal: 1,
+	}
+	svc := NewMasterSettingsService(repo, MasterSettingsServiceDependencies{})
+
+	rows, total, err := svc.List(ctx, "wu", "-updated_at", 10, 5)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result: len=%d total=%d", len(rows), total)
+	}
+	if repo.lastListSort != "updated_at DESC" {
+		t.Fatalf("expected normalized sort, got %q", repo.lastListSort)
+	}
+	if repo.lastListFilter != "wu" || repo.lastListLimit != 10 || repo.lastListOffset != 5 {
+		t.Fatalf("unexpected list params passed to repo")
+	}
+
+	repo.listErr = errors.New("list failed")
+	if _, _, err := svc.List(ctx, "", "unknown", 0, 0); err == nil {
+		t.Fatalf("expected list error")
+	}
+	if repo.lastListSort != "" {
+		t.Fatalf("expected unknown sort normalized to empty string, got %q", repo.lastListSort)
+	}
+}
+
+func TestNormalizeMasterSettingsSort(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{name: "company asc", in: "company_name", want: "company_name ASC"},
+		{name: "company desc", in: "-company_name", want: "company_name DESC"},
+		{name: "title asc", in: "title", want: "title ASC"},
+		{name: "title desc", in: "-title", want: "title DESC"},
+		{name: "subtitle asc", in: "subtitle", want: "subtitle ASC"},
+		{name: "subtitle desc", in: "-subtitle", want: "subtitle DESC"},
+		{name: "logo url asc", in: "logo_url", want: "logo_url ASC"},
+		{name: "logo url desc", in: "-logo_url", want: "logo_url DESC"},
+		{name: "logo file asc", in: "logo_file_uuid", want: "logo_file_id ASC"},
+		{name: "logo file desc", in: "-logo_file_uuid", want: "logo_file_id DESC"},
+		{name: "created asc", in: "created_at", want: "created_at ASC"},
+		{name: "created desc", in: "-created_at", want: "created_at DESC"},
+		{name: "updated asc", in: "updated_at", want: "updated_at ASC"},
+		{name: "updated desc", in: "-updated_at", want: "updated_at DESC"},
+		{name: "unknown", in: "x", want: ""},
+		{name: "empty", in: "", want: ""},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := normalizeMasterSettingsSort(tc.in)
+			if got != tc.want {
+				t.Fatalf("normalize sort %q: got %q want %q", tc.in, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestMasterSettingsServiceMicrosoftEntra(t *testing.T) {
+	ctx := context.Background()
+	repo := &masterSettingsRepoMock{}
+	svc := NewMasterSettingsService(repo, MasterSettingsServiceDependencies{})
+
+	keyB64 := "MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY="
+	protector, err := NewAESGCMProtectorFromBase64(keyB64)
+	if err != nil {
+		t.Fatalf("new protector: %v", err)
+	}
+	svc.SetSecretProtector(protector)
+
+	repo.settingRows = []mastersettings.MasterSettingValue{
+		{SettingKey: mastersettings.SettingMicrosoftEntraTenantID, Value: "tenant"},
+		{SettingKey: mastersettings.SettingMicrosoftEntraClientID, Value: "client"},
+		{SettingKey: mastersettings.SettingMicrosoftEntraClientSecret, Value: "cipher", IsEncrypted: true},
+		{SettingKey: mastersettings.SettingMicrosoftEntraRedirectURL, Value: "https://app.example.com/callback"},
+		{SettingKey: mastersettings.SettingMicrosoftEntraAuthority, Value: "https://login.microsoftonline.com/"},
+		{SettingKey: mastersettings.SettingMicrosoftEntraScopes, Value: "openid,profile,email"},
+	}
+
+	got, err := svc.UpsertMicrosoftEntraConfig(ctx, mastersettings.MicrosoftEntraConfigInput{
+		TenantID:     " tenant ",
+		ClientID:     " client ",
+		ClientSecret: "super-secret",
+		RedirectURL:  "https://app.example.com/callback",
+		Authority:    "https://login.microsoftonline.com",
+		Scopes:       "openid, profile,email,profile",
+	}, []byte("abcdefghijklmnop"))
+	if err != nil {
+		t.Fatalf("upsert microsoft entra config: %v", err)
+	}
+	if got == nil || got.ClientSecretMasked != "********" {
+		t.Fatalf("expected masked secret in view")
+	}
+	if len(repo.lastSettingRows) != len(mastersettings.MicrosoftEntraSettingKeys) {
+		t.Fatalf("unexpected setting rows len: %d", len(repo.lastSettingRows))
+	}
+
+	var encryptedSecret string
+	for _, row := range repo.lastSettingRows {
+		if row.SettingKey == mastersettings.SettingMicrosoftEntraClientSecret {
+			encryptedSecret = row.Value
+			if !row.IsEncrypted {
+				t.Fatalf("expected secret row encrypted")
+			}
+		}
+	}
+	if encryptedSecret == "" {
+		t.Fatalf("secret row not written")
+	}
+	rawCipher, err := base64.StdEncoding.DecodeString(encryptedSecret)
+	if err != nil {
+		t.Fatalf("decode secret ciphertext: %v", err)
+	}
+	plain, err := protector.Decrypt(rawCipher)
+	if err != nil {
+		t.Fatalf("decrypt secret ciphertext: %v", err)
+	}
+	if string(plain) != "super-secret" {
+		t.Fatalf("unexpected decrypted secret: %q", string(plain))
+	}
+
+	loaded, err := svc.GetMicrosoftEntraConfig(ctx)
+	if err != nil {
+		t.Fatalf("get microsoft entra config: %v", err)
+	}
+	if loaded == nil || loaded.ClientSecretMasked != "********" {
+		t.Fatalf("expected masked secret from get")
+	}
+
+	t.Run("keep existing secret when input secret is empty", func(t *testing.T) {
+		repo.lastSettingRows = nil
+		repo.settingRows = []mastersettings.MasterSettingValue{
+			{SettingKey: mastersettings.SettingMicrosoftEntraClientSecret, Value: "existing-cipher", IsEncrypted: true},
+			{SettingKey: mastersettings.SettingMicrosoftEntraTenantID, Value: "tenant"},
+			{SettingKey: mastersettings.SettingMicrosoftEntraClientID, Value: "client"},
+			{SettingKey: mastersettings.SettingMicrosoftEntraRedirectURL, Value: "https://app.example.com/callback"},
+			{SettingKey: mastersettings.SettingMicrosoftEntraAuthority, Value: "https://login.microsoftonline.com/"},
+			{SettingKey: mastersettings.SettingMicrosoftEntraScopes, Value: "openid,profile,email"},
+		}
+
+		_, err := svc.UpsertMicrosoftEntraConfig(ctx, mastersettings.MicrosoftEntraConfigInput{
+			TenantID:     "tenant",
+			ClientID:     "client",
+			ClientSecret: " ",
+			RedirectURL:  "https://app.example.com/callback",
+			Authority:    "https://login.microsoftonline.com/",
+			Scopes:       "openid,profile,email",
+		}, []byte("abcdefghijklmnop"))
+		if err != nil {
+			t.Fatalf("upsert with empty secret: %v", err)
+		}
+
+		for _, row := range repo.lastSettingRows {
+			if row.SettingKey == mastersettings.SettingMicrosoftEntraClientSecret {
+				t.Fatalf("expected secret row not updated when input secret is empty")
+			}
+		}
+	})
+
+	t.Run("empty secret rejected on initial setup", func(t *testing.T) {
+		repo.lastSettingRows = nil
+		repo.settingRows = []mastersettings.MasterSettingValue{}
+
+		_, err := svc.UpsertMicrosoftEntraConfig(ctx, mastersettings.MicrosoftEntraConfigInput{
+			TenantID:     "tenant",
+			ClientID:     "client",
+			ClientSecret: "",
+			RedirectURL:  "https://app.example.com/callback",
+			Authority:    "https://login.microsoftonline.com/",
+			Scopes:       "openid,profile,email",
+		}, []byte("abcdefghijklmnop"))
+		if err == nil {
+			t.Fatalf("expected error when secret empty and no existing value")
+		}
+		if err.Error() != "MS_ENTRA_CLIENT_SECRET is required for initial setup" {
+			t.Fatalf("unexpected error: %v", err)
+		}
+	})
+}
+
+func TestSeedMicrosoftEntraConfigIfMissing(t *testing.T) {
+	ctx := context.Background()
+
+	keyB64 := "MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY="
+	protector, err := NewAESGCMProtectorFromBase64(keyB64)
+	if err != nil {
+		t.Fatalf("new protector: %v", err)
+	}
+
+	t.Run("seed inserts all keys when missing", func(t *testing.T) {
+		repo := &masterSettingsRepoMock{}
+		svc := NewMasterSettingsService(repo, MasterSettingsServiceDependencies{Protector: protector})
+
+		err := svc.SeedMicrosoftEntraConfigIfMissing(ctx, config.MicrosoftSSOConfig{
+			TenantID:     "tenant",
+			ClientID:     "client",
+			ClientSecret: "secret",
+			RedirectURL:  "https://app.example.com/challenge/msentra",
+			Authority:    "https://login.microsoftonline.com/",
+			Scopes:       []string{"openid", "profile", "email"},
+		})
+		if err != nil {
+			t.Fatalf("seed microsoft entra: %v", err)
+		}
+		if len(repo.lastSettingRows) != 3 {
+			t.Fatalf("expected 3 rows, got %d", len(repo.lastSettingRows))
+		}
+	})
+
+	t.Run("seed only inserts missing and preserves existing", func(t *testing.T) {
+		repo := &masterSettingsRepoMock{
+			settingRows: []mastersettings.MasterSettingValue{
+				{SettingKey: mastersettings.SettingMicrosoftEntraTenantID, Value: "existing-tenant"},
+				{SettingKey: mastersettings.SettingMicrosoftEntraClientID, Value: "existing-client"},
+				{SettingKey: mastersettings.SettingMicrosoftEntraClientSecret, Value: "existing-encrypted", IsEncrypted: true},
+			},
+		}
+		svc := NewMasterSettingsService(repo, MasterSettingsServiceDependencies{Protector: protector})
+
+		err := svc.SeedMicrosoftEntraConfigIfMissing(ctx, config.MicrosoftSSOConfig{
+			TenantID:     "tenant",
+			ClientID:     "client",
+			ClientSecret: "secret",
+			RedirectURL:  "https://app.example.com/challenge/msentra",
+			Authority:    "https://login.microsoftonline.com",
+			Scopes:       []string{"openid", "profile", "email"},
+		})
+		if err != nil {
+			t.Fatalf("seed microsoft entra: %v", err)
+		}
+		if len(repo.lastSettingRows) != 3 {
+			t.Fatalf("expected 3 missing rows to be inserted, got %d", len(repo.lastSettingRows))
+		}
+		for i := range repo.lastSettingRows {
+			if repo.lastSettingRows[i].SettingKey == mastersettings.SettingMicrosoftEntraClientSecret {
+				t.Fatalf("client secret should not be overwritten when existing value is present")
+			}
+		}
+	})
+}
+
+func TestMicrosoftEntraPartialViewButStrictRuntime(t *testing.T) {
+	ctx := context.Background()
+	repo := &masterSettingsRepoMock{
+		settingRows: []mastersettings.MasterSettingValue{
+			{SettingKey: mastersettings.SettingMicrosoftEntraRedirectURL, Value: "https://app.example.com/challenge/msentra"},
+			{SettingKey: mastersettings.SettingMicrosoftEntraAuthority, Value: "https://login.microsoftonline.com/"},
+			{SettingKey: mastersettings.SettingMicrosoftEntraScopes, Value: "openid,profile,email"},
+		},
+	}
+	svc := NewMasterSettingsService(repo, MasterSettingsServiceDependencies{})
+
+	view, err := svc.GetMicrosoftEntraConfig(ctx)
+	if err != nil {
+		t.Fatalf("get microsoft entra config: %v", err)
+	}
+	if view == nil {
+		t.Fatalf("expected partial config view, got nil")
+	}
+	if view.RedirectURL == "" || view.Authority == "" || view.Scopes == "" {
+		t.Fatalf("expected non-sensitive fields populated")
+	}
+
+	if _, err := svc.LoadMicrosoftEntraRuntimeConfig(ctx); err == nil {
+		t.Fatalf("expected strict runtime config to fail when tenant/client/secret missing")
+	}
+}
diff --git a/internal/service/mcf_service.go b/internal/service/mcf_service.go
new file mode 100644
index 0000000..fbe6413
--- /dev/null
+++ b/internal/service/mcf_service.go
@@ -0,0 +1,47 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/mcf"
+)
+
+type MCFService struct{ repo mcf.Repository }
+
+func NewMCFService(repo mcf.Repository) *MCFService { return &MCFService{repo: repo} }
+
+func (s *MCFService) Create(ctx context.Context, row *mcf.MaintenanceCheckFlight) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *MCFService) Update(ctx context.Context, row *mcf.MaintenanceCheckFlight) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *MCFService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *MCFService) GetByID(ctx context.Context, id []byte) (*mcf.MaintenanceCheckFlight, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *MCFService) ListByHelicopter(ctx context.Context, helicopterID []byte) ([]mcf.MaintenanceCheckFlight, error) {
+	return s.repo.ListByHelicopter(ctx, helicopterID)
+}
+
+func (s *MCFService) GetLatestByHelicopter(ctx context.Context, helicopterID []byte) (*mcf.MaintenanceCheckFlight, error) {
+	return s.repo.GetLatestByHelicopter(ctx, helicopterID)
+}
+
+func (s *MCFService) LatestByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]*mcf.MaintenanceCheckFlight, error) {
+	return s.repo.LatestByHelicopterIDs(ctx, helicopterIDs)
+}
+
+func (s *MCFService) PendingHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]bool, error) {
+	return s.repo.PendingHelicopterIDs(ctx, helicopterIDs)
+}
+
+func (s *MCFService) HelicopterHasOpenMCF(ctx context.Context, helicopterID []byte) (bool, error) {
+	return s.repo.HelicopterHasOpenMCF(ctx, helicopterID)
+}
diff --git a/internal/service/mcf_service_test.go b/internal/service/mcf_service_test.go
new file mode 100644
index 0000000..1a39c82
--- /dev/null
+++ b/internal/service/mcf_service_test.go
@@ -0,0 +1,85 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/mcf"
+)
+
+type stubMCFRepo struct {
+	row       *mcf.MaintenanceCheckFlight
+	pending   map[string]bool
+	createErr error
+	created   *mcf.MaintenanceCheckFlight
+	updated   *mcf.MaintenanceCheckFlight
+	deletedID []byte
+}
+
+func (s *stubMCFRepo) Create(_ context.Context, row *mcf.MaintenanceCheckFlight) error {
+	s.created = row
+	return s.createErr
+}
+func (s *stubMCFRepo) Update(_ context.Context, row *mcf.MaintenanceCheckFlight) error {
+	s.updated = row
+	return nil
+}
+func (s *stubMCFRepo) Delete(_ context.Context, id, _ []byte) error { s.deletedID = id; return nil }
+func (s *stubMCFRepo) GetByID(_ context.Context, _ []byte) (*mcf.MaintenanceCheckFlight, error) {
+	return s.row, nil
+}
+func (s *stubMCFRepo) ListByHelicopter(_ context.Context, _ []byte) ([]mcf.MaintenanceCheckFlight, error) {
+	if s.row != nil {
+		return []mcf.MaintenanceCheckFlight{*s.row}, nil
+	}
+	return nil, nil
+}
+func (s *stubMCFRepo) GetLatestByHelicopter(_ context.Context, _ []byte) (*mcf.MaintenanceCheckFlight, error) {
+	return s.row, nil
+}
+func (s *stubMCFRepo) PendingHelicopterIDs(_ context.Context, _ [][]byte) (map[string]bool, error) {
+	return s.pending, nil
+}
+
+func (s *stubMCFRepo) LatestByHelicopterIDs(_ context.Context, _ [][]byte) (map[string]*mcf.MaintenanceCheckFlight, error) {
+	return nil, nil
+}
+
+func (s *stubMCFRepo) HelicopterHasOpenMCF(_ context.Context, _ []byte) (bool, error) {
+	return false, nil
+}
+
+func TestMCFServiceDelegation(t *testing.T) {
+	repo := &stubMCFRepo{row: &mcf.MaintenanceCheckFlight{}, pending: map[string]bool{"x": true}}
+	svc := NewMCFService(repo)
+	ctx := context.Background()
+	row := &mcf.MaintenanceCheckFlight{}
+
+	if err := svc.Create(ctx, row); err != nil || repo.created != row {
+		t.Fatalf("Create not delegated: %v", err)
+	}
+	if err := svc.Update(ctx, row); err != nil || repo.updated != row {
+		t.Fatalf("Update not delegated: %v", err)
+	}
+	if err := svc.Delete(ctx, []byte("0123456789abcdef"), nil); err != nil || string(repo.deletedID) != "0123456789abcdef" {
+		t.Fatalf("Delete not delegated: %v", err)
+	}
+	if got, err := svc.GetByID(ctx, []byte("x")); err != nil || got != repo.row {
+		t.Fatalf("GetByID not delegated: %v", err)
+	}
+	if rows, err := svc.ListByHelicopter(ctx, []byte("h")); err != nil || len(rows) != 1 {
+		t.Fatalf("ListByHelicopter not delegated: %v", err)
+	}
+	if got, err := svc.PendingHelicopterIDs(ctx, [][]byte{[]byte("x")}); err != nil || !got["x"] {
+		t.Fatalf("PendingHelicopterIDs not delegated: %v", err)
+	}
+	if got, err := svc.GetLatestByHelicopter(ctx, []byte("h")); err != nil || got != repo.row {
+		t.Fatalf("GetLatestByHelicopter not delegated: %v", err)
+	}
+
+	repo.createErr = errors.New("boom")
+	if err := svc.Create(ctx, row); err == nil {
+		t.Fatal("expected create error to propagate")
+	}
+}
diff --git a/internal/service/medicine_service.go b/internal/service/medicine_service.go
new file mode 100644
index 0000000..8e53f3e
--- /dev/null
+++ b/internal/service/medicine_service.go
@@ -0,0 +1,176 @@
+package service
+
+import (
+	"context"
+	"errors"
+
+	"wucher/internal/domain/medicine"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type MedicineService struct {
+	repo medicine.Repository
+}
+
+func NewMedicineService(repo medicine.Repository) *MedicineService {
+	return &MedicineService{repo: repo}
+}
+
+func (s *MedicineService) Create(ctx context.Context, row *medicine.Medicine) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *MedicineService) Update(ctx context.Context, row *medicine.Medicine) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *MedicineService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *MedicineService) GetByID(ctx context.Context, id []byte) (*medicine.Medicine, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *MedicineService) List(ctx context.Context, filter, sort string, limit, offset int) ([]medicine.Medicine, int64, error) {
+	return s.repo.List(ctx, filter, normalizeMedicineSort(sort), limit, offset)
+}
+
+func normalizeMedicineSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", true)),
+			"sortkey",
+		),
+		sortField("name"),
+		sortExpr(
+			"COALESCE(NULLIF(note, ''), pack) ASC",
+			"COALESCE(NULLIF(note, ''), pack) DESC",
+			"note",
+		),
+		sortField("pack"),
+		sortField("unit"),
+		sortField("`column`", "column"),
+		sortField("is_active"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
+
+func (s *MedicineService) CreateGroup(ctx context.Context, row *medicine.MedicineGroup) error {
+	repo, ok := s.repo.(interface {
+		CreateGroup(context.Context, *medicine.MedicineGroup) error
+	})
+	if !ok {
+		return errors.New("medicine group repository not configured")
+	}
+	return repo.CreateGroup(ctx, row)
+}
+
+func (s *MedicineService) UpdateGroup(ctx context.Context, row *medicine.MedicineGroup) error {
+	repo, ok := s.repo.(interface {
+		UpdateGroup(context.Context, *medicine.MedicineGroup) error
+	})
+	if !ok {
+		return errors.New("medicine group repository not configured")
+	}
+	return repo.UpdateGroup(ctx, row)
+}
+
+func (s *MedicineService) DeleteGroup(ctx context.Context, id []byte, deletedBy []byte) error {
+	repo, ok := s.repo.(interface {
+		DeleteGroup(context.Context, []byte, []byte) error
+	})
+	if !ok {
+		return errors.New("medicine group repository not configured")
+	}
+	return repo.DeleteGroup(ctx, id, deletedBy)
+}
+
+func (s *MedicineService) GetGroupByID(ctx context.Context, id []byte) (*medicine.MedicineGroup, error) {
+	repo, ok := s.repo.(interface {
+		GetGroupByID(context.Context, []byte) (*medicine.MedicineGroup, error)
+	})
+	if !ok {
+		return nil, errors.New("medicine group repository not configured")
+	}
+	return repo.GetGroupByID(ctx, id)
+}
+
+func (s *MedicineService) ListGroups(ctx context.Context, filter, sort string, limit, offset int) ([]medicine.MedicineGroup, int64, error) {
+	repo, ok := s.repo.(interface {
+		ListGroups(context.Context, string, string, int, int) ([]medicine.MedicineGroup, int64, error)
+	})
+	if !ok {
+		return nil, 0, errors.New("medicine group repository not configured")
+	}
+	return repo.ListGroups(ctx, filter, normalizeMedicineGroupSort(sort), limit, offset)
+}
+
+func normalizeMedicineGroupSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortField("name"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
+
+func (s *MedicineService) CreateReaction(ctx context.Context, row *medicine.MotorReaction) error {
+	repo, ok := s.repo.(interface {
+		CreateReaction(context.Context, *medicine.MotorReaction) error
+	})
+	if !ok {
+		return errors.New("motor reaction repository not configured")
+	}
+	return repo.CreateReaction(ctx, row)
+}
+
+func (s *MedicineService) UpdateReaction(ctx context.Context, row *medicine.MotorReaction) error {
+	repo, ok := s.repo.(interface {
+		UpdateReaction(context.Context, *medicine.MotorReaction) error
+	})
+	if !ok {
+		return errors.New("motor reaction repository not configured")
+	}
+	return repo.UpdateReaction(ctx, row)
+}
+
+func (s *MedicineService) DeleteReaction(ctx context.Context, id []byte, deletedBy []byte) error {
+	repo, ok := s.repo.(interface {
+		DeleteReaction(context.Context, []byte, []byte) error
+	})
+	if !ok {
+		return errors.New("motor reaction repository not configured")
+	}
+	return repo.DeleteReaction(ctx, id, deletedBy)
+}
+
+func (s *MedicineService) GetReactionByID(ctx context.Context, id []byte) (*medicine.MotorReaction, error) {
+	repo, ok := s.repo.(interface {
+		GetReactionByID(context.Context, []byte) (*medicine.MotorReaction, error)
+	})
+	if !ok {
+		return nil, errors.New("motor reaction repository not configured")
+	}
+	return repo.GetReactionByID(ctx, id)
+}
+
+func (s *MedicineService) ListReactions(ctx context.Context, filter, sort string, limit, offset int) ([]medicine.MotorReaction, int64, error) {
+	repo, ok := s.repo.(interface {
+		ListReactions(context.Context, string, string, int, int) ([]medicine.MotorReaction, int64, error)
+	})
+	if !ok {
+		return nil, 0, errors.New("motor reaction repository not configured")
+	}
+	return repo.ListReactions(ctx, filter, normalizeMotorReactionSort(sort), limit, offset)
+}
+
+func normalizeMotorReactionSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortField("name"),
+		sortField("score"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/medicine_service_test.go b/internal/service/medicine_service_test.go
new file mode 100644
index 0000000..9713479
--- /dev/null
+++ b/internal/service/medicine_service_test.go
@@ -0,0 +1,227 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/medicine"
+)
+
+type medicineRepoMock struct {
+	createCalled  bool
+	updateCalled  bool
+	deleteCalled  bool
+	getByIDCalled bool
+	listCalled    bool
+
+	lastCreate     *medicine.Medicine
+	lastUpdate     *medicine.Medicine
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastGetByID    []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+
+	getByIDResult *medicine.Medicine
+	listResult    []medicine.Medicine
+	listTotal     int64
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+}
+
+func (m *medicineRepoMock) Create(_ context.Context, row *medicine.Medicine) error {
+	m.createCalled = true
+	m.lastCreate = row
+	return m.createErr
+}
+
+func (m *medicineRepoMock) Update(_ context.Context, row *medicine.Medicine) error {
+	m.updateCalled = true
+	m.lastUpdate = row
+	return m.updateErr
+}
+
+func (m *medicineRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return m.deleteErr
+}
+
+func (m *medicineRepoMock) GetByID(_ context.Context, id []byte) (*medicine.Medicine, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *medicineRepoMock) List(_ context.Context, filter, sort string, limit, offset int) ([]medicine.Medicine, int64, error) {
+	m.listCalled = true
+	m.lastListFilter = filter
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listResult, m.listTotal, m.listErr
+}
+
+func TestNewMedicineService(t *testing.T) {
+	repo := &medicineRepoMock{}
+	svc := NewMedicineService(repo)
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service and repo initialized")
+	}
+}
+
+func TestMedicineServiceCreate(t *testing.T) {
+	repo := &medicineRepoMock{}
+	svc := NewMedicineService(repo)
+	row := &medicine.Medicine{Name: "Paracetamol", Pack:"500mg", Column: 1}
+
+	if err := svc.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.createCalled || repo.lastCreate != row {
+		t.Fatalf("expected Create forwarded to repo")
+	}
+
+	repo.createErr = errors.New("create failed")
+	if err := svc.Create(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestMedicineServiceUpdate(t *testing.T) {
+	repo := &medicineRepoMock{}
+	svc := NewMedicineService(repo)
+	row := &medicine.Medicine{Name: "Paracetamol", Pack:"500mg", Column: 1}
+
+	if err := svc.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateCalled || repo.lastUpdate != row {
+		t.Fatalf("expected Update forwarded to repo")
+	}
+
+	repo.updateErr = errors.New("update failed")
+	if err := svc.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestMedicineServiceDelete(t *testing.T) {
+	repo := &medicineRepoMock{}
+	svc := NewMedicineService(repo)
+	id := []byte("id")
+	deletedBy := []byte("by")
+
+	if err := svc.Delete(context.Background(), id, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.deleteCalled {
+		t.Fatalf("expected Delete forwarded to repo")
+	}
+	if string(repo.lastDeleteID) != string(id) || string(repo.lastDeleteBy) != string(deletedBy) {
+		t.Fatalf("expected delete params forwarded")
+	}
+
+	repo.deleteErr = errors.New("delete failed")
+	if err := svc.Delete(context.Background(), id, deletedBy); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestMedicineServiceGetByID(t *testing.T) {
+	expected := &medicine.Medicine{Name: "Paracetamol", Pack:"500mg", Column: 1}
+	repo := &medicineRepoMock{getByIDResult: expected}
+	svc := NewMedicineService(repo)
+	id := []byte("id")
+
+	got, err := svc.GetByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != expected {
+		t.Fatalf("unexpected result")
+	}
+	if !repo.getByIDCalled || string(repo.lastGetByID) != string(id) {
+		t.Fatalf("expected GetByID forwarded")
+	}
+
+	repo.getByIDErr = errors.New("get failed")
+	if _, err := svc.GetByID(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestMedicineServiceList(t *testing.T) {
+	repo := &medicineRepoMock{
+		listResult: []medicine.Medicine{{Name: "Paracetamol", Pack:"500mg", Column: 1}},
+		listTotal:  1,
+	}
+	svc := NewMedicineService(repo)
+
+	rows, total, err := svc.List(context.Background(), "find", "column", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if !repo.listCalled {
+		t.Fatalf("expected List forwarded to repo")
+	}
+	if repo.lastListFilter != "find" || repo.lastListSort != "`column` ASC" || repo.lastListLimit != 10 || repo.lastListOffset != 20 {
+		t.Fatalf("unexpected list args forwarded")
+	}
+
+	rows, total, err = svc.List(context.Background(), "find", "name", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if repo.lastListSort != "name ASC" {
+		t.Fatalf("unexpected name sort args forwarded: %q", repo.lastListSort)
+	}
+
+	repo.listErr = errors.New("list failed")
+	if _, _, err := svc.List(context.Background(), "", "unknown", 1, 0); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestNormalizeMedicineSort(t *testing.T) {
+	cases := map[string]string{
+		"name":        "name ASC",
+		"-name":       "name DESC",
+		"note":        "COALESCE(NULLIF(note, ''), pack) ASC",
+		"-note":       "COALESCE(NULLIF(note, ''), pack) DESC",
+		"pack":        "pack ASC",
+		"-pack":       "pack DESC",
+		"unit":        "unit ASC",
+		"-unit":       "unit DESC",
+		"column":      "`column` ASC",
+		"-column":     "`column` DESC",
+		"is_active":   "is_active ASC",
+		"-is_active":  "is_active DESC",
+		"created_at":  "created_at ASC",
+		"-created_at": "created_at DESC",
+		"updated_at":  "updated_at ASC",
+		"-updated_at": "updated_at DESC",
+		"unknown":     "",
+		"":            "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeMedicineSort(in); got != want {
+			t.Fatalf("normalizeMedicineSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/microsoft_sso.go b/internal/service/microsoft_sso.go
new file mode 100644
index 0000000..ee440e1
--- /dev/null
+++ b/internal/service/microsoft_sso.go
@@ -0,0 +1,332 @@
+package service
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"wucher/internal/config"
+	"wucher/internal/resilience"
+)
+
+type MicrosoftTokenSet struct {
+	AccessToken           string
+	RefreshToken          string
+	IDToken               string
+	TokenType             string
+	Scope                 string
+	ExpiresIn             int64
+	RefreshTokenExpiresIn int64
+}
+
+type MicrosoftSSOClient struct {
+	cfg            config.MicrosoftSSOConfig
+	client         *http.Client
+	executor       *resilience.Executor
+	configResolver func(context.Context) (config.MicrosoftSSOConfig, error)
+}
+
+func NewMicrosoftSSO(cfg config.MicrosoftSSOConfig) *MicrosoftSSOClient {
+	return &MicrosoftSSOClient{
+		cfg: cfg,
+		client: &http.Client{
+			Timeout: 10 * time.Second,
+		},
+	}
+}
+
+func (m *MicrosoftSSOClient) WithExecutor(executor *resilience.Executor) *MicrosoftSSOClient {
+	if m == nil {
+		return nil
+	}
+	m.executor = executor
+	return m
+}
+
+func (m *MicrosoftSSOClient) WithConfigResolver(resolver func(context.Context) (config.MicrosoftSSOConfig, error)) *MicrosoftSSOClient {
+	if m == nil {
+		return nil
+	}
+	m.configResolver = resolver
+	return m
+}
+
+func (m *MicrosoftSSOClient) AuthCodeURL(state string) string {
+	cfg, err := m.currentConfig(context.Background())
+	if err != nil || !isMicrosoftSSOAuthConfigComplete(cfg) {
+		return ""
+	}
+	scopes := ensureMicrosoftScopes(cfg.Scopes)
+	q := url.Values{}
+	q.Set("client_id", cfg.ClientID)
+	q.Set("response_type", "code")
+	q.Set("redirect_uri", cfg.RedirectURL)
+	q.Set("response_mode", "query")
+	q.Set("scope", strings.Join(scopes, " "))
+	q.Set("state", state)
+	q.Set("prompt", "select_account")
+	return fmt.Sprintf("%s%s/oauth2/v2.0/authorize?%s", cfg.Authority, cfg.TenantID, q.Encode())
+}
+
+func (m *MicrosoftSSOClient) LogoutURL(postLogoutRedirectURL string) string {
+	cfg, err := m.currentConfig(context.Background())
+	if err != nil || !isMicrosoftSSOAuthConfigComplete(cfg) {
+		return ""
+	}
+	q := url.Values{}
+	if redirect := strings.TrimSpace(postLogoutRedirectURL); redirect != "" {
+		q.Set("post_logout_redirect_uri", redirect)
+	}
+	base := fmt.Sprintf("%s%s/oauth2/v2.0/logout", cfg.Authority, cfg.TenantID)
+	if encoded := q.Encode(); encoded != "" {
+		return base + "?" + encoded
+	}
+	return base
+}
+
+func (m *MicrosoftSSOClient) ExchangeCode(ctx context.Context, code string) (MicrosoftClaims, error) {
+	_, claims, err := m.ExchangeCodeAndTokens(ctx, code, "")
+	return claims, err
+}
+
+func (m *MicrosoftSSOClient) ExchangeCodeAndTokens(ctx context.Context, code, codeVerifier string) (MicrosoftTokenSet, MicrosoftClaims, error) {
+	set, err := resilience.Do(ctx, m.executor, func(ctx context.Context) (MicrosoftTokenSet, error) {
+		if code == "" {
+			return MicrosoftTokenSet{}, errors.New("missing code")
+		}
+		cfg, err := m.currentConfig(ctx)
+		if err != nil || !isMicrosoftSSOConfigComplete(cfg) {
+			return MicrosoftTokenSet{}, errors.New("sso not configured")
+		}
+
+		scopes := ensureMicrosoftScopes(cfg.Scopes)
+		form := url.Values{}
+		form.Set("client_id", cfg.ClientID)
+		form.Set("client_secret", cfg.ClientSecret)
+		form.Set("grant_type", "authorization_code")
+		form.Set("code", code)
+		form.Set("redirect_uri", cfg.RedirectURL)
+		form.Set("scope", strings.Join(scopes, " "))
+		if strings.TrimSpace(codeVerifier) != "" {
+			form.Set("code_verifier", strings.TrimSpace(codeVerifier))
+		}
+
+		tokenURL := fmt.Sprintf("%s%s/oauth2/v2.0/token", cfg.Authority, cfg.TenantID)
+		return m.exchangeTokenForm(ctx, tokenURL, form)
+	})
+	if err != nil {
+		return MicrosoftTokenSet{}, MicrosoftClaims{}, err
+	}
+	claims, err := parseMicrosoftClaimsFromIDToken(set.IDToken)
+	if err != nil {
+		return MicrosoftTokenSet{}, MicrosoftClaims{}, err
+	}
+	return set, claims, nil
+}
+
+func (m *MicrosoftSSOClient) RefreshAccessToken(ctx context.Context, refreshToken, codeVerifier string) (MicrosoftTokenSet, error) {
+	return resilience.Do(ctx, m.executor, func(ctx context.Context) (MicrosoftTokenSet, error) {
+		if strings.TrimSpace(refreshToken) == "" {
+			return MicrosoftTokenSet{}, errors.New("missing refresh token")
+		}
+		cfg, err := m.currentConfig(ctx)
+		if err != nil || !isMicrosoftSSOConfigComplete(cfg) {
+			return MicrosoftTokenSet{}, errors.New("sso not configured")
+		}
+
+		scopes := ensureMicrosoftScopes(cfg.Scopes)
+		form := url.Values{}
+		form.Set("client_id", cfg.ClientID)
+		form.Set("client_secret", cfg.ClientSecret)
+		form.Set("grant_type", "refresh_token")
+		form.Set("refresh_token", strings.TrimSpace(refreshToken))
+		form.Set("redirect_uri", cfg.RedirectURL)
+		form.Set("scope", strings.Join(scopes, " "))
+		if strings.TrimSpace(codeVerifier) != "" {
+			form.Set("code_verifier", strings.TrimSpace(codeVerifier))
+		}
+		tokenURL := fmt.Sprintf("%s%s/oauth2/v2.0/token", cfg.Authority, cfg.TenantID)
+		return m.exchangeTokenForm(ctx, tokenURL, form)
+	})
+}
+
+func (m *MicrosoftSSOClient) exchangeTokenForm(ctx context.Context, tokenURL string, form url.Values) (MicrosoftTokenSet, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, tokenURL, strings.NewReader(form.Encode()))
+	if err != nil {
+		return MicrosoftTokenSet{}, err
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	resp, err := m.client.Do(req)
+	if err != nil {
+		return MicrosoftTokenSet{}, err
+	}
+	defer resp.Body.Close()
+
+	body, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		bodyStr := string(body)
+		if resp.StatusCode == http.StatusUnauthorized && strings.Contains(bodyStr, "invalid_client") {
+			return MicrosoftTokenSet{}, fmt.Errorf(
+				"token exchange failed: invalid_client (check MS_ENTRA_CLIENT_SECRET uses secret VALUE, not secret ID): %s",
+				bodyStr,
+			)
+		}
+		return MicrosoftTokenSet{}, &resilience.HTTPStatusError{
+			Operation:  "token exchange failed",
+			StatusCode: resp.StatusCode,
+			Body:       bodyStr,
+		}
+	}
+
+	var token struct {
+		AccessToken           string `json:"access_token"`
+		RefreshToken          string `json:"refresh_token"`
+		IDToken               string `json:"id_token"`
+		TokenType             string `json:"token_type"`
+		Scope                 string `json:"scope"`
+		ExpiresIn             int64  `json:"expires_in"`
+		RefreshTokenExpiresIn int64  `json:"refresh_token_expires_in"`
+	}
+	if err := json.Unmarshal(body, &token); err != nil {
+		return MicrosoftTokenSet{}, err
+	}
+	if strings.TrimSpace(token.IDToken) == "" {
+		return MicrosoftTokenSet{}, errors.New("missing id_token")
+	}
+	if strings.TrimSpace(token.AccessToken) == "" {
+		return MicrosoftTokenSet{}, errors.New("missing access_token")
+	}
+
+	return MicrosoftTokenSet{
+		AccessToken:           strings.TrimSpace(token.AccessToken),
+		RefreshToken:          strings.TrimSpace(token.RefreshToken),
+		IDToken:               strings.TrimSpace(token.IDToken),
+		TokenType:             strings.TrimSpace(token.TokenType),
+		Scope:                 strings.TrimSpace(token.Scope),
+		ExpiresIn:             token.ExpiresIn,
+		RefreshTokenExpiresIn: token.RefreshTokenExpiresIn,
+	}, nil
+}
+
+func (m *MicrosoftSSOClient) currentConfig(ctx context.Context) (config.MicrosoftSSOConfig, error) {
+	if m == nil {
+		return config.MicrosoftSSOConfig{}, errors.New("sso client is nil")
+	}
+	if m.configResolver == nil {
+		return m.cfg, nil
+	}
+	return m.configResolver(ctx)
+}
+
+func isMicrosoftSSOConfigComplete(cfg config.MicrosoftSSOConfig) bool {
+	return strings.TrimSpace(cfg.TenantID) != "" &&
+		strings.TrimSpace(cfg.ClientID) != "" &&
+		strings.TrimSpace(cfg.ClientSecret) != "" &&
+		strings.TrimSpace(cfg.RedirectURL) != "" &&
+		strings.TrimSpace(cfg.Authority) != "" &&
+		len(ensureMicrosoftScopes(cfg.Scopes)) > 0
+}
+
+func IsMicrosoftSSOConfigComplete(cfg config.MicrosoftSSOConfig) bool {
+	return isMicrosoftSSOConfigComplete(cfg)
+}
+
+func isMicrosoftSSOAuthConfigComplete(cfg config.MicrosoftSSOConfig) bool {
+	return strings.TrimSpace(cfg.TenantID) != "" &&
+		strings.TrimSpace(cfg.ClientID) != "" &&
+		strings.TrimSpace(cfg.RedirectURL) != "" &&
+		strings.TrimSpace(cfg.Authority) != "" &&
+		len(ensureMicrosoftScopes(cfg.Scopes)) > 0
+}
+
+func ensureMicrosoftScopes(scopes []string) []string {
+	merged := make([]string, 0, len(scopes)+5)
+	seen := map[string]struct{}{}
+	appendScope := func(v string) {
+		v = strings.TrimSpace(v)
+		if v == "" {
+			return
+		}
+		key := strings.ToLower(v)
+		if _, ok := seen[key]; ok {
+			return
+		}
+		seen[key] = struct{}{}
+		merged = append(merged, v)
+	}
+	for i := range scopes {
+		appendScope(scopes[i])
+	}
+	appendScope("openid")
+	appendScope("profile")
+	appendScope("email")
+	appendScope("offline_access")
+	appendScope("User.Read")
+	return merged
+}
+
+func parseMicrosoftClaimsFromIDToken(idToken string) (MicrosoftClaims, error) {
+	claimsMap, err := parseJWTClaims(idToken)
+	if err != nil {
+		return MicrosoftClaims{}, err
+	}
+	sub, _ := claimsMap["sub"].(string)
+	email, _ := claimsMap["email"].(string)
+	name, _ := claimsMap["name"].(string)
+	if email == "" {
+		email, _ = claimsMap["preferred_username"].(string)
+	}
+	tid, _ := claimsMap["tid"].(string)
+	oid, _ := claimsMap["oid"].(string)
+	sid, _ := claimsMap["sid"].(string)
+	return MicrosoftClaims{
+		Subject:  strings.TrimSpace(sub),
+		Email:    strings.TrimSpace(email),
+		Name:     strings.TrimSpace(name),
+		TenantID: strings.TrimSpace(tid),
+		ObjectID: strings.TrimSpace(oid),
+		SessionID: strings.TrimSpace(sid),
+	}, nil
+}
+
+func parseJWTClaims(token string) (map[string]any, error) {
+	parts := strings.Split(token, ".")
+	if len(parts) < 2 {
+		return nil, errors.New("invalid jwt")
+	}
+	payload, err := decodeSegment(parts[1])
+	if err != nil {
+		return nil, err
+	}
+	var claims map[string]any
+	if err := json.Unmarshal(payload, &claims); err != nil {
+		return nil, err
+	}
+	return claims, nil
+}
+
+func decodeSegment(seg string) ([]byte, error) {
+	seg = strings.ReplaceAll(seg, "-", "+")
+	seg = strings.ReplaceAll(seg, "_", "/")
+	switch len(seg) % 4 {
+	case 2:
+		seg += "=="
+	case 3:
+		seg += "="
+	}
+	return io.ReadAll(base64.NewDecoder(base64.StdEncoding, strings.NewReader(seg)))
+}
+
+func microsoftPKCEChallengeS256(verifier string) string {
+	h := sha256.Sum256([]byte(strings.TrimSpace(verifier)))
+	return base64.RawURLEncoding.EncodeToString(h[:])
+}
diff --git a/internal/service/microsoft_sso_test.go b/internal/service/microsoft_sso_test.go
new file mode 100644
index 0000000..0f146f8
--- /dev/null
+++ b/internal/service/microsoft_sso_test.go
@@ -0,0 +1,442 @@
+package service
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"wucher/internal/config"
+	"wucher/internal/resilience"
+)
+
+func TestNewMicrosoftSSO(t *testing.T) {
+	cfg := config.MicrosoftSSOConfig{
+		TenantID:     "tenant-id",
+		ClientID:     "client-id",
+		ClientSecret: "secret",
+		RedirectURL:  "http://localhost/callback",
+		Authority:    "https://login.microsoftonline.com/",
+		Scopes:       []string{"openid", "profile", "email"},
+	}
+
+	client := NewMicrosoftSSO(cfg)
+	if client == nil {
+		t.Fatalf("expected client")
+	}
+	if client.cfg.ClientID != cfg.ClientID {
+		t.Fatalf("client config not set")
+	}
+	if client.client == nil {
+		t.Fatalf("http client should not be nil")
+	}
+	if client.client.Timeout != 10*time.Second {
+		t.Fatalf("unexpected timeout: %v", client.client.Timeout)
+	}
+}
+
+func TestMicrosoftSSO_AuthCodeURL(t *testing.T) {
+	cfg := config.MicrosoftSSOConfig{
+		TenantID:    "tenant-id",
+		ClientID:    "client-id",
+		RedirectURL: "http://localhost/callback",
+		Authority:   "https://login.microsoftonline.com/",
+		Scopes:      []string{"openid", "profile", "email"},
+	}
+	client := NewMicrosoftSSO(cfg)
+
+	raw := client.AuthCodeURL("state-123")
+	parsed, err := url.Parse(raw)
+	if err != nil {
+		t.Fatalf("parse url: %v", err)
+	}
+	if parsed.Path != "/tenant-id/oauth2/v2.0/authorize" {
+		t.Fatalf("unexpected authorize path: %s", parsed.Path)
+	}
+	q := parsed.Query()
+	if q.Get("client_id") != "client-id" ||
+		q.Get("response_type") != "code" ||
+		q.Get("redirect_uri") != "http://localhost/callback" ||
+		q.Get("response_mode") != "query" ||
+		q.Get("scope") != "openid profile email offline_access User.Read" ||
+		q.Get("prompt") != "select_account" ||
+		q.Get("state") != "state-123" {
+		t.Fatalf("unexpected query values: %v", q)
+	}
+	if got := q.Get("max_age"); got != "" {
+		t.Fatalf("max_age should not be set, got %q", got)
+	}
+}
+
+func TestMicrosoftSSO_LogoutURL(t *testing.T) {
+	cfg := config.MicrosoftSSOConfig{
+		TenantID:    "tenant-id",
+		ClientID:    "client-id",
+		RedirectURL: "http://localhost/callback",
+		Authority:   "https://login.microsoftonline.com/",
+		Scopes:      []string{"openid", "profile", "email"},
+	}
+	client := NewMicrosoftSSO(cfg)
+
+	raw := client.LogoutURL("http://localhost/logout-done")
+	parsed, err := url.Parse(raw)
+	if err != nil {
+		t.Fatalf("parse url: %v", err)
+	}
+	if parsed.Path != "/tenant-id/oauth2/v2.0/logout" {
+		t.Fatalf("unexpected logout path: %s", parsed.Path)
+	}
+	if got := parsed.Query().Get("post_logout_redirect_uri"); got != "http://localhost/logout-done" {
+		t.Fatalf("unexpected post logout redirect: %q", got)
+	}
+}
+
+func TestMicrosoftSSO_ExchangeCode(t *testing.T) {
+	t.Run("missing code", func(t *testing.T) {
+		client := NewMicrosoftSSO(config.MicrosoftSSOConfig{})
+		if _, err := client.ExchangeCode(context.Background(), ""); err == nil {
+			t.Fatalf("expected error for missing code")
+		}
+	})
+
+	t.Run("token endpoint non 2xx", func(t *testing.T) {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			http.Error(w, "bad request", http.StatusBadRequest)
+		}))
+		defer server.Close()
+
+		client := NewMicrosoftSSO(config.MicrosoftSSOConfig{
+			TenantID:     "tenant-id",
+			ClientID:     "client-id",
+			ClientSecret: "secret",
+			RedirectURL:  "http://localhost/callback",
+			Authority:    server.URL + "/",
+			Scopes:       []string{"openid"},
+		})
+
+		if _, err := client.ExchangeCode(context.Background(), "code-1"); err == nil || !strings.Contains(err.Error(), "token exchange failed") {
+			t.Fatalf("expected token exchange failed error, got %v", err)
+		}
+	})
+
+	t.Run("invalid json response", func(t *testing.T) {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{invalid`))
+		}))
+		defer server.Close()
+
+		client := NewMicrosoftSSO(config.MicrosoftSSOConfig{
+			TenantID:     "tenant-id",
+			ClientID:     "client-id",
+			ClientSecret: "secret",
+			RedirectURL:  "http://localhost/callback",
+			Authority:    server.URL + "/",
+			Scopes:       []string{"openid"},
+		})
+
+		if _, err := client.ExchangeCode(context.Background(), "code-1"); err == nil {
+			t.Fatalf("expected unmarshal error")
+		}
+	})
+
+	t.Run("missing id token", func(t *testing.T) {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"access_token":"abc"}`))
+		}))
+		defer server.Close()
+
+		client := NewMicrosoftSSO(config.MicrosoftSSOConfig{
+			TenantID:     "tenant-id",
+			ClientID:     "client-id",
+			ClientSecret: "secret",
+			RedirectURL:  "http://localhost/callback",
+			Authority:    server.URL + "/",
+			Scopes:       []string{"openid"},
+		})
+
+		if _, err := client.ExchangeCode(context.Background(), "code-1"); err == nil || !strings.Contains(err.Error(), "missing id_token") {
+			t.Fatalf("expected missing id_token error, got %v", err)
+		}
+	})
+
+	t.Run("invalid id token claims", func(t *testing.T) {
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"id_token":"invalid-token"}`))
+		}))
+		defer server.Close()
+
+		client := NewMicrosoftSSO(config.MicrosoftSSOConfig{
+			TenantID:     "tenant-id",
+			ClientID:     "client-id",
+			ClientSecret: "secret",
+			RedirectURL:  "http://localhost/callback",
+			Authority:    server.URL + "/",
+			Scopes:       []string{"openid"},
+		})
+
+		if _, err := client.ExchangeCode(context.Background(), "code-1"); err == nil {
+			t.Fatalf("expected parse jwt error")
+		}
+	})
+
+	t.Run("success with email claim", func(t *testing.T) {
+		idToken := makeUnsignedJWT(map[string]any{
+			"sub":   "subject-1",
+			"email": "user@example.com",
+			"name":  "John Doe",
+		})
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.Method != http.MethodPost {
+				t.Fatalf("expected POST")
+			}
+			if r.URL.Path != "/tenant-id/oauth2/v2.0/token" {
+				t.Fatalf("unexpected path: %s", r.URL.Path)
+			}
+			if err := r.ParseForm(); err != nil {
+				t.Fatalf("parse form: %v", err)
+			}
+			if r.PostForm.Get("client_id") != "client-id" ||
+				r.PostForm.Get("client_secret") != "secret" ||
+				r.PostForm.Get("grant_type") != "authorization_code" ||
+				r.PostForm.Get("code") != "code-1" ||
+				r.PostForm.Get("redirect_uri") != "http://localhost/callback" ||
+				r.PostForm.Get("scope") != "openid profile email offline_access User.Read" {
+				t.Fatalf("unexpected form values: %v", r.PostForm)
+			}
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]string{"id_token": idToken, "access_token": "at-1"})
+		}))
+		defer server.Close()
+
+		client := NewMicrosoftSSO(config.MicrosoftSSOConfig{
+			TenantID:     "tenant-id",
+			ClientID:     "client-id",
+			ClientSecret: "secret",
+			RedirectURL:  "http://localhost/callback",
+			Authority:    server.URL + "/",
+			Scopes:       []string{"openid", "profile", "email"},
+		})
+
+		claims, err := client.ExchangeCode(context.Background(), "code-1")
+		if err != nil {
+			t.Fatalf("exchange code failed: %v", err)
+		}
+		if claims.Subject != "subject-1" || claims.Email != "user@example.com" || claims.Name != "John Doe" {
+			t.Fatalf("unexpected claims: %+v", claims)
+		}
+	})
+
+	t.Run("success fallback preferred username", func(t *testing.T) {
+		idToken := makeUnsignedJWT(map[string]any{
+			"sub":                "subject-2",
+			"preferred_username": "fallback@example.com",
+			"name":               "Jane Doe",
+		})
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]string{"id_token": idToken, "access_token": "at-2"})
+		}))
+		defer server.Close()
+
+		client := NewMicrosoftSSO(config.MicrosoftSSOConfig{
+			TenantID:     "tenant-id",
+			ClientID:     "client-id",
+			ClientSecret: "secret",
+			RedirectURL:  "http://localhost/callback",
+			Authority:    server.URL + "/",
+			Scopes:       []string{"openid"},
+		})
+
+		claims, err := client.ExchangeCode(context.Background(), "code-1")
+		if err != nil {
+			t.Fatalf("exchange code failed: %v", err)
+		}
+		if claims.Email != "fallback@example.com" {
+			t.Fatalf("expected preferred_username fallback, got %q", claims.Email)
+		}
+	})
+
+	t.Run("http client do error", func(t *testing.T) {
+		client := NewMicrosoftSSO(config.MicrosoftSSOConfig{
+			TenantID:     "tenant-id",
+			ClientID:     "client-id",
+			ClientSecret: "secret",
+			RedirectURL:  "http://localhost/callback",
+			Authority:    "https://example.com/",
+			Scopes:       []string{"openid"},
+		})
+		client.client = &http.Client{
+			Transport: roundTripFunc(func(*http.Request) (*http.Response, error) {
+				return nil, errors.New("network down")
+			}),
+		}
+
+		if _, err := client.ExchangeCode(context.Background(), "code-1"); err == nil || !strings.Contains(err.Error(), "network down") {
+			t.Fatalf("expected http client error, got %v", err)
+		}
+	})
+}
+
+func TestMicrosoftSSO_ExchangeCode_CircuitBreaker(t *testing.T) {
+	newExecutor := func() *resilience.Executor {
+		return resilience.NewExecutor("microsoft_sso", config.CircuitBreakerPolicy{
+			Enabled:             true,
+			Timeout:             time.Second,
+			MinRequests:         2,
+			FailureRatio:        0.5,
+			ConsecutiveFailures: 2,
+		}, slog.New(slog.NewJSONHandler(io.Discard, nil)), resilience.ClassifyMicrosoftSSOError)
+	}
+
+	t.Run("client errors are excluded", func(t *testing.T) {
+		hits := 0
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			hits++
+			http.Error(w, "bad request", http.StatusBadRequest)
+		}))
+		defer server.Close()
+
+		client := NewMicrosoftSSO(config.MicrosoftSSOConfig{
+			TenantID:     "tenant-id",
+			ClientID:     "client-id",
+			ClientSecret: "secret",
+			RedirectURL:  "http://localhost/callback",
+			Authority:    server.URL + "/",
+			Scopes:       []string{"openid"},
+		}).WithExecutor(newExecutor())
+
+		for range 3 {
+			if _, err := client.ExchangeCode(context.Background(), "code-1"); err == nil || !strings.Contains(err.Error(), "token exchange failed") {
+				t.Fatalf("expected token exchange failed error, got %v", err)
+			}
+		}
+		if hits != 3 {
+			t.Fatalf("expected breaker to stay closed for excluded client errors, got %d hits", hits)
+		}
+	})
+
+	t.Run("server errors open the breaker", func(t *testing.T) {
+		hits := 0
+		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			hits++
+			http.Error(w, "unavailable", http.StatusServiceUnavailable)
+		}))
+		defer server.Close()
+
+		client := NewMicrosoftSSO(config.MicrosoftSSOConfig{
+			TenantID:     "tenant-id",
+			ClientID:     "client-id",
+			ClientSecret: "secret",
+			RedirectURL:  "http://localhost/callback",
+			Authority:    server.URL + "/",
+			Scopes:       []string{"openid"},
+		}).WithExecutor(newExecutor())
+
+		for range 2 {
+			if _, err := client.ExchangeCode(context.Background(), "code-1"); err == nil || !strings.Contains(err.Error(), "token exchange failed") {
+				t.Fatalf("expected token exchange failed error, got %v", err)
+			}
+		}
+		_, err := client.ExchangeCode(context.Background(), "code-1")
+		var openErr *resilience.OpenError
+		if !errors.As(err, &openErr) {
+			t.Fatalf("expected circuit open error, got %v", err)
+		}
+		if hits != 2 {
+			t.Fatalf("expected breaker to fail fast after opening, got %d hits", hits)
+		}
+	})
+}
+
+func TestParseJWTClaims(t *testing.T) {
+	t.Run("invalid jwt format", func(t *testing.T) {
+		if _, err := parseJWTClaims("invalid"); err == nil {
+			t.Fatalf("expected invalid jwt error")
+		}
+	})
+
+	t.Run("invalid payload encoding", func(t *testing.T) {
+		if _, err := parseJWTClaims("header.%%%.sig"); err == nil {
+			t.Fatalf("expected decode error")
+		}
+	})
+
+	t.Run("invalid payload json", func(t *testing.T) {
+		payload := base64.RawURLEncoding.EncodeToString([]byte("not-json"))
+		if _, err := parseJWTClaims("header." + payload + ".sig"); err == nil {
+			t.Fatalf("expected json unmarshal error")
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		token := makeUnsignedJWT(map[string]any{
+			"sub":   "subject-1",
+			"email": "user@example.com",
+			"name":  "John Doe",
+		})
+		claims, err := parseJWTClaims(token)
+		if err != nil {
+			t.Fatalf("parse claims failed: %v", err)
+		}
+		if claims["sub"] != "subject-1" || claims["email"] != "user@example.com" {
+			t.Fatalf("unexpected claims: %+v", claims)
+		}
+	})
+}
+
+func TestDecodeSegment(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		raw := base64.RawURLEncoding.EncodeToString([]byte("hello"))
+		got, err := decodeSegment(raw)
+		if err != nil {
+			t.Fatalf("decode failed: %v", err)
+		}
+		if string(got) != "hello" {
+			t.Fatalf("unexpected value: %q", string(got))
+		}
+	})
+
+	t.Run("success url safe alphabet", func(t *testing.T) {
+		got, err := decodeSegment("--__")
+		if err != nil {
+			t.Fatalf("decode failed: %v", err)
+		}
+		want := []byte{0xfb, 0xef, 0xff}
+		if len(got) != len(want) {
+			t.Fatalf("unexpected length: %d", len(got))
+		}
+		for i := range want {
+			if got[i] != want[i] {
+				t.Fatalf("unexpected byte at %d: got %x want %x", i, got[i], want[i])
+			}
+		}
+	})
+
+	t.Run("invalid base64", func(t *testing.T) {
+		if _, err := decodeSegment("%"); err == nil {
+			t.Fatalf("expected decode error")
+		}
+	})
+}
+
+type roundTripFunc func(req *http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) { return f(req) }
+
+func makeUnsignedJWT(claims map[string]any) string {
+	header := base64.RawURLEncoding.EncodeToString([]byte(`{"alg":"none","typ":"JWT"}`))
+	payloadBytes, _ := json.Marshal(claims)
+	payload := base64.RawURLEncoding.EncodeToString(payloadBytes)
+	return header + "." + payload + ".sig"
+}
diff --git a/internal/service/mission_service.go b/internal/service/mission_service.go
new file mode 100644
index 0000000..d65af6e
--- /dev/null
+++ b/internal/service/mission_service.go
@@ -0,0 +1,356 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	basedomain "wucher/internal/domain/base"
+	flightdomain "wucher/internal/domain/flight"
+	flightdata "wucher/internal/domain/flight_data"
+	"wucher/internal/domain/mission"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/util"
+)
+
+type MissionService struct {
+	repo          mission.Repository
+	flightSvc     flightdomain.FlightService
+	flightDataSvc flightdata.Service
+	afterFlight   afterflightinspection.Service
+}
+
+func missionCodePrefix(missionType string, t time.Time) string {
+	return strings.ToUpper(strings.TrimSpace(missionType)) + "-" + t.Format("06") + "-"
+}
+
+func NewMissionService(repo mission.Repository, deps ...any) *MissionService {
+	var flightSvc flightdomain.FlightService
+	var fdSvc flightdata.Service
+	var afterSvc afterflightinspection.Service
+	for _, dep := range deps {
+		switch v := dep.(type) {
+		case flightdomain.FlightService:
+			flightSvc = v
+		case flightdata.Service:
+			fdSvc = v
+		case afterflightinspection.Service:
+			afterSvc = v
+		}
+	}
+	return &MissionService{repo: repo, flightSvc: flightSvc, flightDataSvc: fdSvc, afterFlight: afterSvc}
+}
+
+func (s *MissionService) Create(ctx context.Context, row *mission.Mission) error {
+	if row == nil {
+		return mission.ErrRequired
+	}
+	if len(row.FlightID) == 0 {
+		return mission.ErrFlightIDRequired
+	}
+	row.Type = strings.ToUpper(strings.TrimSpace(row.Type))
+	category, err := s.repo.FindCategoryByCode(ctx, row.Type)
+	if err != nil {
+		return err
+	}
+	if category == nil || len(category.ID) == 0 {
+		return mission.ErrTypeInvalid
+	}
+	row.MissionCategoryID = append([]byte(nil), category.ID...)
+	if row.Type == sharedconst.MissionTypeHEMS {
+		if len(row.SubtypeID) == 0 {
+			return mission.ErrSubtypeRequired
+		}
+		ok, err := s.repo.SubCategoryBelongsToCategory(ctx, row.SubtypeID, row.MissionCategoryID)
+		if err != nil {
+			return err
+		}
+		if !ok {
+			return mission.ErrSubtypeInvalid
+		}
+	} else if len(row.SubtypeID) > 0 {
+		return mission.ErrSubtypeForbidden
+	}
+
+	startTime, endTime, err := s.resolveMissionTimes(ctx, row.FlightID)
+	if err != nil {
+		return err
+	}
+	row.StartTime = startTime
+	row.EndTime = endTime
+	if err := s.ensureNotAfterFlightLocked(ctx, row.FlightID); err != nil {
+		return err
+	}
+
+	return s.repo.WithTransaction(ctx, func(txCtx context.Context) error {
+		return s.persistMissionCreate(txCtx, row)
+	})
+}
+
+func (s *MissionService) persistMissionCreate(ctx context.Context, row *mission.Mission) error {
+	if strings.TrimSpace(row.Code) == "" {
+		prefix := missionCodePrefix(row.Type, time.Now())
+		maxSeq, err := s.repo.MaxCodeSeqByPrefix(ctx, prefix)
+		if err != nil {
+			return err
+		}
+		row.Code = prefix + strconv.Itoa(maxSeq+1)
+	}
+	return s.repo.Create(ctx, row)
+}
+
+func (s *MissionService) CreateType(ctx context.Context, row *mission.MissionCategory) error {
+	if row == nil {
+		return mission.ErrRequired
+	}
+	row.CodeType = strings.ToUpper(strings.TrimSpace(row.CodeType))
+	row.TypeName = strings.TrimSpace(row.TypeName)
+	if row.CodeType == "" || row.TypeName == "" {
+		return mission.ErrTypeInvalid
+	}
+	return s.repo.CreateCategory(ctx, row)
+}
+
+func (s *MissionService) UpdateByID(ctx context.Context, missionID []byte, missionType string, subtypeID []byte, note string, updatedBy []byte) error {
+	if len(missionID) == 0 {
+		return mission.ErrMissionIDRequired
+	}
+	missionType = strings.ToUpper(strings.TrimSpace(missionType))
+	category, err := s.repo.FindCategoryByCode(ctx, missionType)
+	if err != nil {
+		return err
+	}
+	if category == nil || len(category.ID) == 0 {
+		return mission.ErrTypeInvalid
+	}
+
+	if missionType == sharedconst.MissionTypeHEMS {
+		if len(subtypeID) == 0 {
+			return mission.ErrSubtypeRequired
+		}
+		ok, err := s.repo.SubCategoryBelongsToCategory(ctx, subtypeID, category.ID)
+		if err != nil {
+			return err
+		}
+		if !ok {
+			return mission.ErrSubtypeInvalid
+		}
+	} else if len(subtypeID) > 0 {
+		return mission.ErrSubtypeForbidden
+	}
+
+	return s.repo.UpdateByID(ctx, missionID, missionType, category.ID, subtypeID, note, updatedBy)
+}
+
+func (s *MissionService) FlightIDByMissionID(ctx context.Context, missionID []byte) ([]byte, error) {
+	if len(missionID) != 16 {
+		return nil, nil
+	}
+	row, err := s.repo.GetByID(ctx, missionID)
+	if err != nil {
+		return nil, err
+	}
+	if row == nil || len(row.FlightID) != 16 {
+		return nil, nil
+	}
+	return append([]byte(nil), row.FlightID...), nil
+}
+
+func (s *MissionService) resolveMissionTimes(ctx context.Context, flightID []byte) (string, string, error) {
+	if s.flightSvc == nil {
+		return "", "", mission.ErrScheduleMissing
+	}
+	flightRow, err := s.flightSvc.GetByID(ctx, flightID)
+	if err != nil {
+		return "", "", err
+	}
+	if flightRow == nil || len(flightRow.ID) != 16 || flightRow.Date.IsZero() {
+		return "", "", mission.ErrScheduleMissing
+	}
+	baseRow := missionBaseFromFlight(flightRow)
+	if baseRow == nil {
+		return "", "", mission.ErrBaseMissing
+	}
+	startTime, endTime, err := util.ResolveShiftWindow(baseRow, flightRow.Date)
+	if err != nil {
+		return "", "", mapBaseShiftError(err)
+	}
+	return startTime, endTime, nil
+}
+
+func mapBaseShiftError(err error) error {
+	switch {
+	case errors.Is(err, util.ErrShiftCoordinatesInvalid):
+		return mission.ErrCoordinatesInvalid
+	case errors.Is(err, util.ErrShiftTwilightMissing):
+		return mission.ErrTwilightMissing
+	case errors.Is(err, util.ErrShiftScheduleMissing):
+		return mission.ErrScheduleMissing
+	default:
+		return err
+	}
+}
+
+func (s *MissionService) ensureNotAfterFlightLocked(ctx context.Context, flightID []byte) error {
+	if s.flightSvc == nil || s.afterFlight == nil || len(flightID) != 16 {
+		return nil
+	}
+	flightRow, err := s.flightSvc.GetByID(ctx, flightID)
+	if err != nil {
+		return err
+	}
+	if flightRow == nil || flightRow.Takeover == nil || flightRow.Takeover.ReserveAc == nil || len(flightRow.Takeover.ReserveAc.InspectionID) != 16 {
+		return nil
+	}
+	afterRow, err := s.afterFlight.GetByFlightInspectionID(ctx, flightRow.Takeover.ReserveAc.InspectionID)
+	if err != nil {
+		return err
+	}
+	if afterRow != nil {
+		return mission.ErrLockedAfterFlightInspection
+	}
+	return nil
+}
+
+func missionBaseFromFlight(row *flightdomain.Flight) *basedomain.Base {
+	if row == nil || row.Takeover == nil {
+		return nil
+	}
+	return row.Takeover.Base
+}
+
+func (s *MissionService) DeleteByID(ctx context.Context, missionID []byte, deletedBy []byte) error {
+	if len(missionID) == 0 {
+		return mission.ErrMissionIDRequired
+	}
+	return s.repo.DeleteByID(ctx, missionID, deletedBy)
+}
+
+func (s *MissionService) DeleteByFlightID(ctx context.Context, flightID []byte, deletedBy []byte) error {
+	if len(flightID) == 0 {
+		return mission.ErrFlightIDRequired
+	}
+	return s.repo.DeleteByFlightID(ctx, flightID, deletedBy)
+}
+
+func (s *MissionService) AttachFile(ctx context.Context, missionID []byte, fileAttachmentID []byte) error {
+	if len(missionID) != 16 {
+		return mission.ErrMissionIDRequired
+	}
+	if len(fileAttachmentID) != 16 {
+		return mission.ErrFileAttachmentIDRequired
+	}
+	return s.repo.AttachFile(ctx, missionID, fileAttachmentID)
+}
+
+func (s *MissionService) DetachFile(ctx context.Context, missionID []byte, fileAttachmentID []byte) error {
+	if len(missionID) != 16 {
+		return mission.ErrMissionIDRequired
+	}
+	if len(fileAttachmentID) != 16 {
+		return mission.ErrFileAttachmentIDRequired
+	}
+	return s.repo.DetachFile(ctx, missionID, fileAttachmentID)
+}
+
+func (s *MissionService) GetByID(ctx context.Context, missionID []byte) (*mission.Mission, error) {
+	if len(missionID) == 0 {
+		return nil, mission.ErrMissionIDRequired
+	}
+	row, err := s.repo.GetByID(ctx, missionID)
+	if err != nil {
+		return nil, err
+	}
+	if err := s.hydrateFlightDataCompletion(ctx, row); err != nil {
+		return nil, err
+	}
+	return row, nil
+}
+
+func (s *MissionService) ListByFlightID(ctx context.Context, flightID []byte) ([]mission.Mission, error) {
+	if len(flightID) == 0 {
+		return nil, mission.ErrFlightIDRequired
+	}
+	rows, err := s.repo.ListByFlightID(ctx, flightID)
+	if err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (s *MissionService) ListByFlightIDs(ctx context.Context, flightIDs [][]byte) ([]mission.Mission, error) {
+	rows, err := s.repo.ListByFlightIDs(ctx, flightIDs)
+	if err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (s *MissionService) GetByFlightID(ctx context.Context, flightID []byte) (*mission.Mission, error) {
+	if len(flightID) == 0 {
+		return nil, mission.ErrFlightIDRequired
+	}
+	row, err := s.repo.GetByFlightID(ctx, flightID)
+	if err != nil {
+		return nil, err
+	}
+	return row, nil
+}
+
+func (s *MissionService) List(ctx context.Context, filter, sort string, flightID []byte, flightDataStatus string, limit, offset int) ([]mission.Mission, int64, error) {
+	rows, total, err := s.repo.List(ctx, filter, normalizeMissionSort(sort), flightID, flightDataStatus, limit, offset)
+	if err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func (s *MissionService) ListDatatable(ctx context.Context, filter mission.ListFilter, limit, offset int) ([]mission.Mission, int64, int64, error) {
+	filter.Sort = normalizeMissionSort(filter.Sort)
+	rows, total, filtered, err := s.repo.ListDatatable(ctx, filter, limit, offset)
+	if err != nil {
+		return nil, 0, 0, err
+	}
+	return rows, total, filtered, nil
+}
+
+func (s *MissionService) ListTypes(ctx context.Context) ([]mission.MissionCategory, error) {
+	return s.repo.ListCategoriesWithSubCategories(ctx)
+}
+
+func (s *MissionService) hydrateFlightDataCompletion(ctx context.Context, row *mission.Mission) error {
+	if s.flightDataSvc == nil || row == nil || len(row.ID) == 0 {
+		return nil
+	}
+	fd, err := s.flightDataSvc.GetByMissionID(ctx, row.ID)
+	if err != nil {
+		return err
+	}
+	if fd == nil {
+		return nil
+	}
+	var details *flightdata.SPODetails
+	if strings.ToUpper(strings.TrimSpace(row.Type)) == sharedconst.MissionTypeSPO {
+		details, err = s.flightDataSvc.GetSPODetailsByFlightDataID(ctx, fd.ID)
+		if err != nil {
+			return err
+		}
+	}
+	row.FlightDataStatus = flightdata.DeriveStatus(fd, details)
+	return nil
+}
+
+func normalizeMissionSort(sort string) string {
+	if normalized := normalizeSortByRules(sort,
+		sortField("missions.type", "type"),
+		sortField("flights.date", "flight_date"),
+		sortField("missions.created_at", "created_at"),
+		sortField("missions.updated_at", "updated_at"),
+	); normalized != "" {
+		return normalized
+	}
+	return "missions.created_at DESC"
+}
diff --git a/internal/service/mission_service_test.go b/internal/service/mission_service_test.go
new file mode 100644
index 0000000..a055924
--- /dev/null
+++ b/internal/service/mission_service_test.go
@@ -0,0 +1,581 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	basedomain "wucher/internal/domain/base"
+	flightdomain "wucher/internal/domain/flight"
+	flightdata "wucher/internal/domain/flight_data"
+	"wucher/internal/domain/mission"
+	reserveac "wucher/internal/domain/reserve_ac"
+	takeoverdomain "wucher/internal/domain/takeover"
+	"wucher/internal/shared/pkg/util"
+)
+
+type missionRepoMock struct {
+	createFn                 func(context.Context, *mission.Mission) error
+	findCategoryByCodeFn     func(context.Context, string) (*mission.MissionCategory, error)
+	updateFlightDataIDByIDFn func(context.Context, []byte, []byte, []byte) error
+	deleteByIDFn             func(context.Context, []byte, []byte) error
+	deleteByFlightIDFn       func(ctx context.Context, flightID []byte, deletedBy []byte) error
+	maxCodeSeqFn             func() (int, error)
+}
+
+func (m *missionRepoMock) WithTransaction(ctx context.Context, fn func(context.Context) error) error {
+	return fn(ctx)
+}
+
+func (m *missionRepoMock) Create(ctx context.Context, row *mission.Mission) error {
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return nil
+}
+
+func (m *missionRepoMock) CreateCategory(context.Context, *mission.MissionCategory) error { return nil }
+
+func (m *missionRepoMock) CreatePlaceholder(context.Context, *flightdata.FlightData) error {
+	return nil
+}
+
+func (m *missionRepoMock) UpdateFlightDataIDByID(ctx context.Context, missionID, flightDataID, updatedBy []byte) error {
+	if m.updateFlightDataIDByIDFn != nil {
+		return m.updateFlightDataIDByIDFn(ctx, missionID, flightDataID, updatedBy)
+	}
+	return nil
+}
+
+func (m *missionRepoMock) UpdateByID(context.Context, []byte, string, []byte, []byte, string, []byte) error {
+	return nil
+}
+func (m *missionRepoMock) AttachFile(context.Context, []byte, []byte) error {
+	return nil
+}
+
+func (m *missionRepoMock) DetachFile(context.Context, []byte, []byte) error {
+	return nil
+}
+
+func (m *missionRepoMock) DeleteByID(ctx context.Context, missionID []byte, deletedBy []byte) error {
+	if m.deleteByIDFn != nil {
+		return m.deleteByIDFn(ctx, missionID, deletedBy)
+	}
+	return nil
+}
+
+func (m *missionRepoMock) DeleteByFlightID(ctx context.Context, flightID []byte, deletedBy []byte) error {
+	if m.deleteByFlightIDFn != nil {
+		return m.deleteByFlightIDFn(ctx, flightID, deletedBy)
+	}
+	return nil
+}
+
+func (m *missionRepoMock) ListByFlightID(context.Context, []byte) ([]mission.Mission, error) {
+	return nil, nil
+}
+func (m *missionRepoMock) ListByFlightIDs(context.Context, [][]byte) ([]mission.Mission, error) {
+	return nil, nil
+}
+
+func (m *missionRepoMock) GetByID(context.Context, []byte) (*mission.Mission, error) {
+	return nil, nil
+}
+
+func (m *missionRepoMock) GetByFlightID(context.Context, []byte) (*mission.Mission, error) {
+	return nil, nil
+}
+
+func (m *missionRepoMock) List(context.Context, string, string, []byte, string, int, int) ([]mission.Mission, int64, error) {
+	return nil, 0, nil
+}
+
+func (m *missionRepoMock) ListDatatable(context.Context, mission.ListFilter, int, int) ([]mission.Mission, int64, int64, error) {
+	return nil, 0, 0, nil
+}
+
+func (m *missionRepoMock) ListCategoriesWithSubCategories(context.Context) ([]mission.MissionCategory, error) {
+	return nil, nil
+}
+
+func (m *missionRepoMock) FindCategoryByCode(ctx context.Context, code string) (*mission.MissionCategory, error) {
+	if m.findCategoryByCodeFn != nil {
+		return m.findCategoryByCodeFn(ctx, code)
+	}
+	return nil, nil
+}
+
+func (m *missionRepoMock) SubCategoryBelongsToCategory(context.Context, []byte, []byte) (bool, error) {
+	return false, nil
+}
+
+func (m *missionRepoMock) MaxCodeSeqByPrefix(context.Context, string) (int, error) {
+	if m.maxCodeSeqFn != nil {
+		return m.maxCodeSeqFn()
+	}
+	return 0, nil
+}
+
+type flightDataSvcMockForMission struct {
+	createPlaceholderFn func(context.Context, *flightdata.FlightData) error
+}
+
+type afterFlightInspectionSvcMockForMission struct {
+	getByFlightInspectionIDFn func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error)
+}
+
+type flightSvcMockForMission struct {
+	getByIDFn func(context.Context, []byte) (*flightdomain.Flight, error)
+}
+
+func (m *flightSvcMockForMission) Create(context.Context, *flightdomain.Flight) error { return nil }
+func (m *flightSvcMockForMission) Update(context.Context, *flightdomain.Flight) error { return nil }
+func (m *flightSvcMockForMission) Delete(context.Context, []byte, []byte) error       { return nil }
+func (m *flightSvcMockForMission) GetByID(ctx context.Context, id []byte) (*flightdomain.Flight, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *flightSvcMockForMission) ListByUserID(context.Context, []byte, int, int) ([]flightdomain.Flight, int64, error) {
+	return nil, 0, nil
+}
+func (m *flightSvcMockForMission) ListByCreatedBy(context.Context, []byte, string, string, string, int, int) ([]flightdomain.Flight, int64, error) {
+	return nil, 0, nil
+}
+func (m *flightSvcMockForMission) GetByReserveAcID(context.Context, []byte) (*flightdomain.Flight, error) {
+	return nil, nil
+}
+func (m *flightSvcMockForMission) ListByReserveAcID(context.Context, []byte) ([]flightdomain.Flight, error) {
+	return nil, nil
+}
+func (m *flightSvcMockForMission) GetByTakeoverAcID(context.Context, []byte) (*flightdomain.Flight, error) {
+	return nil, nil
+}
+func (m *flightSvcMockForMission) ListByTakeoverAcIDs(context.Context, [][]byte) ([]flightdomain.Flight, error) {
+	return nil, nil
+}
+func (m *flightSvcMockForMission) GetByDutyRosterID(context.Context, []byte) (*flightdomain.Flight, error) {
+	return nil, nil
+}
+func (m *flightSvcMockForMission) ListByDutyRosterIDs(context.Context, [][]byte) ([]flightdomain.Flight, error) {
+	return nil, nil
+}
+func (m *flightSvcMockForMission) List(context.Context, string, string, string, int, int) ([]flightdomain.Flight, int64, error) {
+	return nil, 0, nil
+}
+
+func (m *flightDataSvcMockForMission) Create(context.Context, *flightdata.FlightData) error {
+	return nil
+}
+
+func (m *flightDataSvcMockForMission) CreatePlaceholder(ctx context.Context, row *flightdata.FlightData) error {
+	if m.createPlaceholderFn != nil {
+		return m.createPlaceholderFn(ctx, row)
+	}
+	return nil
+}
+
+func (m *flightDataSvcMockForMission) Update(context.Context, *flightdata.FlightData) error {
+	return nil
+}
+
+func (m *flightDataSvcMockForMission) Delete(context.Context, []byte, []byte) error {
+	return nil
+}
+
+func (m *flightDataSvcMockForMission) GetByID(context.Context, []byte) (*flightdata.FlightData, error) {
+	return nil, nil
+}
+
+func (m *flightDataSvcMockForMission) GetByFlightID(context.Context, []byte) (*flightdata.FlightData, error) {
+	return nil, nil
+}
+
+func (m *flightDataSvcMockForMission) GetByMissionID(context.Context, []byte) (*flightdata.FlightData, error) {
+	return nil, nil
+}
+
+func (m *flightDataSvcMockForMission) ListByMissionID(context.Context, []byte) ([]flightdata.FlightData, error) {
+	return nil, nil
+}
+
+func (m *flightDataSvcMockForMission) List(context.Context, string, []byte, []byte, int, int) ([]flightdata.FlightData, int64, error) {
+	return nil, 0, nil
+}
+
+func (m *flightDataSvcMockForMission) GetSPODetailsByFlightDataID(context.Context, []byte) (*flightdata.SPODetails, error) {
+	return nil, nil
+}
+
+func (m *flightDataSvcMockForMission) UpsertSPODetails(context.Context, []byte, *flightdata.SPOUpsertData) error {
+	return nil
+}
+
+func (m *afterFlightInspectionSvcMockForMission) Upsert(context.Context, []byte, *afterflightinspection.UpsertRequest) (*afterflightinspection.AfterFlightInspection, error) {
+	return nil, nil
+}
+
+func (m *afterFlightInspectionSvcMockForMission) GetByFlightInspectionID(ctx context.Context, id []byte) (*afterflightinspection.AfterFlightInspection, error) {
+	if m.getByFlightInspectionIDFn != nil {
+		return m.getByFlightInspectionIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *afterFlightInspectionSvcMockForMission) DeleteByFlightInspectionID(context.Context, []byte) error {
+	return nil
+}
+
+func TestMissionServiceCreateDoesNotAutoCreateFlightData(t *testing.T) {
+	var createdPlaceholder *flightdata.FlightData
+	var updatedFlightDataID bool
+	flightID := []byte("flight-id-123456")
+	date := time.Date(2026, 6, 15, 0, 0, 0, 0, time.UTC)
+	baseRow := &basedomain.Base{
+		ID:        []byte("base-id-12345678"),
+		BaseName:  "Zurich",
+		Latitude:  47.3769,
+		Longitude: 8.5417,
+		UTC:       "Europe/Zurich",
+		OperationalShiftTimes: []basedomain.BaseOperationalShiftTime{{
+			DateStart:     &date,
+			DateEnd:       &date,
+			StartTimeType: basedomain.ShiftTimeTypeFixed,
+			EndTimeType:   basedomain.ShiftTimeTypeFixed,
+			ShiftStart:    "09:00:00",
+			ShiftEnd:      "17:00:00",
+		}},
+	}
+
+	svc := NewMissionService(
+		&missionRepoMock{
+			findCategoryByCodeFn: func(context.Context, string) (*mission.MissionCategory, error) {
+				return &mission.MissionCategory{ID: []byte("category-id-1234"), CodeType: "SPO", TypeName: "SPO"}, nil
+			},
+			updateFlightDataIDByIDFn: func(context.Context, []byte, []byte, []byte) error {
+				updatedFlightDataID = true
+				return nil
+			},
+			maxCodeSeqFn: func() (int, error) { return 4, nil },
+			createFn: func(_ context.Context, row *mission.Mission) error {
+				if row.StartTime == "" || row.EndTime == "" {
+					t.Fatalf("expected resolved mission times on create, got start=%q end=%q", row.StartTime, row.EndTime)
+				}
+				if !strings.HasPrefix(row.Code, "SPO-") || !strings.HasSuffix(row.Code, "-5") {
+					t.Fatalf("expected generated code SPO-<yy>-5, got %q", row.Code)
+				}
+				return nil
+			},
+		},
+		&flightSvcMockForMission{
+			getByIDFn: func(context.Context, []byte) (*flightdomain.Flight, error) {
+				return &flightdomain.Flight{
+					ID:   flightID,
+					Date: date,
+					Takeover: &takeoverdomain.TakeoverAc{
+						Base: baseRow,
+					},
+				}, nil
+			},
+		},
+		&flightDataSvcMockForMission{
+			createPlaceholderFn: func(_ context.Context, row *flightdata.FlightData) error {
+				row.ID = []byte("flight-data-id-123")
+				createdPlaceholder = row
+				return nil
+			},
+		},
+	)
+
+	row := &mission.Mission{
+		FlightID:  flightID,
+		Type:      "spo",
+		CreatedBy: []byte("creator-id-12345"),
+		UpdatedBy: []byte("creator-id-12345"),
+	}
+
+	if err := svc.Create(context.Background(), row); err != nil {
+		t.Fatalf("Create returned error: %v", err)
+	}
+	// Mission create must NOT auto-create any flight data anymore.
+	if createdPlaceholder != nil {
+		t.Fatal("expected no placeholder flight data to be created on mission create")
+	}
+	if updatedFlightDataID {
+		t.Fatal("expected mission flight_data_id not to be touched")
+	}
+	if len(row.FlightDataID) != 0 {
+		t.Fatalf("expected mission flight_data_id to stay empty, got %x", row.FlightDataID)
+	}
+}
+
+func TestMissionServiceCreateBlockedWhenAfterFlightInspectionExists(t *testing.T) {
+	flightID := []byte("flight-id-123456")
+	inspectionID := []byte("inspection-id-12")
+	date := time.Date(2026, 6, 15, 0, 0, 0, 0, time.UTC)
+	baseRow := &basedomain.Base{
+		ID:        []byte("base-id-12345678"),
+		BaseName:  "Zurich",
+		Latitude:  47.3769,
+		Longitude: 8.5417,
+		UTC:       "Europe/Zurich",
+		OperationalShiftTimes: []basedomain.BaseOperationalShiftTime{{
+			DateStart:     &date,
+			DateEnd:       &date,
+			StartTimeType: basedomain.ShiftTimeTypeFixed,
+			EndTimeType:   basedomain.ShiftTimeTypeFixed,
+			ShiftStart:    "09:00:00",
+			ShiftEnd:      "17:00:00",
+		}},
+	}
+	repo := &missionRepoMock{
+		findCategoryByCodeFn: func(context.Context, string) (*mission.MissionCategory, error) {
+			return &mission.MissionCategory{ID: []byte("category-id-1234"), CodeType: "SPO", TypeName: "SPO"}, nil
+		},
+		createFn: func(context.Context, *mission.Mission) error {
+			t.Fatal("mission create should not be called when after flight inspection exists")
+			return nil
+		},
+	}
+
+	svc := NewMissionService(
+		repo,
+		&flightSvcMockForMission{
+			getByIDFn: func(context.Context, []byte) (*flightdomain.Flight, error) {
+				return &flightdomain.Flight{
+					ID:   flightID,
+					Date: date,
+					Takeover: &takeoverdomain.TakeoverAc{
+						Base:      baseRow,
+						ReserveAc: &reserveac.ReserveAc{InspectionID: inspectionID},
+					},
+				}, nil
+			},
+		},
+		&afterFlightInspectionSvcMockForMission{
+			getByFlightInspectionIDFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+				return &afterflightinspection.AfterFlightInspection{ID: []byte("after-flight-123")}, nil
+			},
+		},
+	)
+
+	err := svc.Create(context.Background(), &mission.Mission{
+		FlightID:  flightID,
+		Type:      "SPO",
+		CreatedBy: []byte("creator-12345678"),
+		UpdatedBy: []byte("creator-12345678"),
+	})
+	if !errors.Is(err, mission.ErrLockedAfterFlightInspection) {
+		t.Fatalf("expected after-flight inspection lock error, got %v", err)
+	}
+}
+
+func TestMissionServiceCreateResolvesMissionTimes(t *testing.T) {
+	flightID := []byte("flight-id-123456")
+	date := time.Date(2026, 6, 15, 0, 0, 0, 0, time.UTC)
+
+	cases := []struct {
+		name            string
+		startType       string
+		endType         string
+		startClock      string
+		endClock        string
+		useDefaultShift bool
+		defaultStart    string
+		defaultEnd      string
+		wantStart       string
+		wantEnd         string
+	}{
+		{
+			name:       "fixed",
+			startType:  basedomain.ShiftTimeTypeFixed,
+			endType:    basedomain.ShiftTimeTypeFixed,
+			startClock: "06:00:00",
+			endClock:   "21:00:00",
+			wantStart:  "06:00",
+			wantEnd:    "21:00",
+		},
+		{
+			name:      "bmct and ecet",
+			startType: basedomain.ShiftTimeTypeBMCT,
+			endType:   basedomain.ShiftTimeTypeECET,
+			wantStart: "04:49",
+			wantEnd:   "22:05",
+		},
+		{
+			name:       "mixed fixed start",
+			startType:  basedomain.ShiftTimeTypeFixed,
+			endType:    basedomain.ShiftTimeTypeECET,
+			startClock: "23:59:00",
+			wantStart:  "23:59",
+			wantEnd:    "22:05",
+		},
+		{
+			name:      "mixed fixed end",
+			startType: basedomain.ShiftTimeTypeBMCT,
+			endType:   basedomain.ShiftTimeTypeFixed,
+			endClock:  "23:59:00",
+			wantStart: "04:49",
+			wantEnd:   "23:59",
+		},
+		{
+			name:            "fallback to default shift when operational schedule missing",
+			useDefaultShift: true,
+			wantStart:       "06:00",
+			wantEnd:         "21:00",
+		},
+		{
+			name:            "fallback accepts datetime default shifts",
+			useDefaultShift: true,
+			defaultStart:    "2000-01-01 06:00:00",
+			defaultEnd:      "2000-01-01 21:00:00",
+			wantStart:       "06:00",
+			wantEnd:         "21:00",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			baseRow := &basedomain.Base{
+				ID:                []byte("base-id-12345678"),
+				BaseName:          "Zurich",
+				Latitude:          47.3769,
+				Longitude:         8.5417,
+				UTC:               "Europe/Zurich",
+				DefaultShiftStart: "06:00:00",
+				DefaultShiftEnd:   "21:00:00",
+			}
+			if tc.defaultStart != "" {
+				baseRow.DefaultShiftStart = tc.defaultStart
+			}
+			if tc.defaultEnd != "" {
+				baseRow.DefaultShiftEnd = tc.defaultEnd
+			}
+			if !tc.useDefaultShift {
+				baseRow.OperationalShiftTimes = []basedomain.BaseOperationalShiftTime{{
+					DateStart:     &date,
+					DateEnd:       &date,
+					StartTimeType: tc.startType,
+					EndTimeType:   tc.endType,
+					ShiftStart:    tc.startClock,
+					ShiftEnd:      tc.endClock,
+				}}
+			}
+
+			var gotStart, gotEnd string
+			svc := NewMissionService(
+				&missionRepoMock{
+					findCategoryByCodeFn: func(context.Context, string) (*mission.MissionCategory, error) {
+						return &mission.MissionCategory{ID: []byte("category-id-1234"), CodeType: "SPO", TypeName: "SPO"}, nil
+					},
+					createFn: func(_ context.Context, row *mission.Mission) error {
+						gotStart = row.StartTime
+						gotEnd = row.EndTime
+						return nil
+					},
+				},
+				&flightSvcMockForMission{
+					getByIDFn: func(context.Context, []byte) (*flightdomain.Flight, error) {
+						return &flightdomain.Flight{
+							ID:   flightID,
+							Date: date,
+							Takeover: &takeoverdomain.TakeoverAc{
+								Base: baseRow,
+							},
+						}, nil
+					},
+				},
+			)
+
+			row := &mission.Mission{FlightID: flightID, Type: "SPO"}
+			if err := svc.Create(context.Background(), row); err != nil {
+				t.Fatalf("Create returned error: %v", err)
+			}
+			if gotStart != tc.wantStart || gotEnd != tc.wantEnd {
+				t.Fatalf("unexpected resolved times: got %s/%s want %s/%s", gotStart, gotEnd, tc.wantStart, tc.wantEnd)
+			}
+		})
+	}
+}
+
+func TestMissionServiceDeleteByFlightIDRequiresFlightID(t *testing.T) {
+	svc := NewMissionService(&missionRepoMock{})
+
+	err := svc.DeleteByFlightID(context.Background(), nil, nil)
+	if !errors.Is(err, mission.ErrFlightIDRequired) {
+		t.Fatalf("expected ErrFlightIDRequired, got %v", err)
+	}
+}
+
+func TestMissionServiceDeleteByFlightIDDelegatesToRepo(t *testing.T) {
+	wantFlightID := []byte("1234567890123456")
+	wantDeletedBy := []byte("6543210987654321")
+	called := false
+
+	svc := NewMissionService(&missionRepoMock{
+		deleteByFlightIDFn: func(_ context.Context, flightID []byte, deletedBy []byte) error {
+			called = true
+			if string(flightID) != string(wantFlightID) {
+				t.Fatalf("unexpected flightID: %x", flightID)
+			}
+			if string(deletedBy) != string(wantDeletedBy) {
+				t.Fatalf("unexpected deletedBy: %x", deletedBy)
+			}
+			return nil
+		},
+	})
+
+	if err := svc.DeleteByFlightID(context.Background(), wantFlightID, wantDeletedBy); err != nil {
+		t.Fatalf("DeleteByFlightID returned error: %v", err)
+	}
+	if !called {
+		t.Fatal("expected repository DeleteByFlightID to be called")
+	}
+}
+
+func TestNormalizeMissionClockValueAcceptsDatetime(t *testing.T) {
+	got := util.NormalizeClockValue("2000-01-01 08:00:00")
+	if got != "08:00" {
+		t.Fatalf("expected 08:00, got %q", got)
+	}
+}
+
+func TestMissionServiceDeleteByIDRequiresMissionID(t *testing.T) {
+	svc := NewMissionService(&missionRepoMock{})
+
+	err := svc.DeleteByID(context.Background(), nil, nil)
+	if !errors.Is(err, mission.ErrMissionIDRequired) {
+		t.Fatalf("expected ErrMissionIDRequired, got %v", err)
+	}
+}
+
+func TestMissionServiceDeleteByIDDelegatesToRepo(t *testing.T) {
+	wantMissionID := []byte("1234567890123456")
+	wantDeletedBy := []byte("6543210987654321")
+	called := false
+
+	svc := NewMissionService(&missionRepoMock{
+		deleteByIDFn: func(_ context.Context, missionID []byte, deletedBy []byte) error {
+			called = true
+			if string(missionID) != string(wantMissionID) {
+				t.Fatalf("unexpected missionID: %x", missionID)
+			}
+			if string(deletedBy) != string(wantDeletedBy) {
+				t.Fatalf("unexpected deletedBy: %x", deletedBy)
+			}
+			return nil
+		},
+	})
+
+	if err := svc.DeleteByID(context.Background(), wantMissionID, wantDeletedBy); err != nil {
+		t.Fatalf("DeleteByID returned error: %v", err)
+	}
+	if !called {
+		t.Fatal("expected repository DeleteByID to be called")
+	}
+}
diff --git a/internal/service/mock_email_sender.go b/internal/service/mock_email_sender.go
new file mode 100644
index 0000000..0a8bc9d
--- /dev/null
+++ b/internal/service/mock_email_sender.go
@@ -0,0 +1,141 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/queue"
+)
+
+type MockEmailSender struct {
+	dir string
+}
+
+type MockEmailRecord struct {
+	StoredAt    time.Time         `json:"stored_at"`
+	Provider    string            `json:"provider"`
+	JobID       string            `json:"job_id"`
+	MessageType string            `json:"message_type"`
+	To          string            `json:"to"`
+	CC          []string          `json:"cc,omitempty"`
+	BCC         []string          `json:"bcc,omitempty"`
+	ReplyTo     []string          `json:"reply_to,omitempty"`
+	Subject     string            `json:"subject"`
+	TextBody    string            `json:"text_body,omitempty"`
+	HTMLBody    string            `json:"html_body,omitempty"`
+	Tags        map[string]string `json:"tags,omitempty"`
+	Metadata    map[string]string `json:"metadata,omitempty"`
+	TraceID     string            `json:"trace_id,omitempty"`
+	RequestID   string            `json:"request_id,omitempty"`
+}
+
+func NewMockEmailSender(dir string) *MockEmailSender {
+	return &MockEmailSender{dir: strings.TrimSpace(dir)}
+}
+
+func (s *MockEmailSender) Configured() bool {
+	return s != nil && strings.TrimSpace(s.dir) != ""
+}
+
+func (s *MockEmailSender) Send(ctx context.Context, job queue.EmailJob) (EmailDeliveryResult, error) {
+	if !s.Configured() {
+		return EmailDeliveryResult{}, errors.New("mock email sender is not configured")
+	}
+	job = job.Canonical()
+	if err := job.Validate(); err != nil {
+		return EmailDeliveryResult{}, err
+	}
+	select {
+	case <-ctx.Done():
+		return EmailDeliveryResult{}, ctx.Err()
+	default:
+	}
+
+	if err := os.MkdirAll(s.dir, 0o755); err != nil {
+		return EmailDeliveryResult{}, err
+	}
+
+	jobID := strings.TrimSpace(job.JobID)
+	if jobID == "" {
+		var err error
+		jobID, err = uuidv7.String(uuidv7.MustNew())
+		if err != nil {
+			return EmailDeliveryResult{}, err
+		}
+	}
+	filename := time.Now().UTC().Format("20060102T150405.000000000Z") + "_" + sanitizeFileName(job.NormalizedType()) + "_" + sanitizeFileName(jobID) + ".json"
+	path := filepath.Join(s.dir, filename)
+
+	record := MockEmailRecord{
+		StoredAt:    time.Now().UTC(),
+		Provider:    "mock",
+		JobID:       jobID,
+		MessageType: job.NormalizedType(),
+		To:          job.To,
+		CC:          append([]string(nil), job.CC...),
+		BCC:         append([]string(nil), job.BCC...),
+		ReplyTo:     append([]string(nil), job.ReplyTo...),
+		Subject:     job.Subject,
+		TextBody:    job.TextBodyValue(),
+		HTMLBody:    job.HTMLBody,
+		Tags:        cloneStringMap(job.Tags),
+		Metadata:    cloneStringMap(job.Metadata),
+		TraceID:     job.TraceID,
+		RequestID:   job.RequestID,
+	}
+	payload, err := json.MarshalIndent(record, "", "  ")
+	if err != nil {
+		return EmailDeliveryResult{}, err
+	}
+	payload = append(payload, '\n')
+
+	if err := os.WriteFile(path, payload, 0o600); err != nil {
+		return EmailDeliveryResult{}, err
+	}
+	return EmailDeliveryResult{
+		Provider:          "mock",
+		ProviderMessageID: filename,
+		RequestID:         path,
+	}, nil
+}
+
+func sanitizeFileName(value string) string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return "email"
+	}
+	var b strings.Builder
+	b.Grow(len(value))
+	for _, r := range value {
+		switch {
+		case r >= 'a' && r <= 'z':
+			b.WriteRune(r)
+		case r >= 'A' && r <= 'Z':
+			b.WriteRune(r)
+		case r >= '0' && r <= '9':
+			b.WriteRune(r)
+		case r == '-', r == '_':
+			b.WriteRune(r)
+		default:
+			b.WriteRune('_')
+		}
+	}
+	return b.String()
+}
+
+func cloneStringMap(values map[string]string) map[string]string {
+	if len(values) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(values))
+	for key, value := range values {
+		out[key] = value
+	}
+	return out
+}
diff --git a/internal/service/mock_email_sender_test.go b/internal/service/mock_email_sender_test.go
new file mode 100644
index 0000000..95a3c0d
--- /dev/null
+++ b/internal/service/mock_email_sender_test.go
@@ -0,0 +1,66 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"wucher/internal/queue"
+)
+
+func TestMockEmailSenderSend(t *testing.T) {
+	dir := t.TempDir()
+	sender := NewMockEmailSender(dir)
+
+	result, err := sender.Send(context.Background(), queue.EmailJob{
+		JobID:       "job-123",
+		MessageType: "password_reset",
+		To:          "user@example.com",
+		Subject:     "Reset password",
+		TextBody:    "plain body",
+		HTMLBody:    "<p>html body</p>",
+		Tags: map[string]string{
+			"message_type": "password_reset",
+		},
+	})
+	if err != nil {
+		t.Fatalf("send: %v", err)
+	}
+	if result.Provider != "mock" || result.ProviderMessageID == "" || result.RequestID == "" {
+		t.Fatalf("unexpected result: %+v", result)
+	}
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatalf("read dir: %v", err)
+	}
+	if len(entries) != 1 {
+		t.Fatalf("expected one stored email, got %d", len(entries))
+	}
+	data, err := os.ReadFile(filepath.Join(dir, entries[0].Name()))
+	if err != nil {
+		t.Fatalf("read file: %v", err)
+	}
+	var record MockEmailRecord
+	if err := json.Unmarshal(data, &record); err != nil {
+		t.Fatalf("unmarshal record: %v", err)
+	}
+	if record.JobID != "job-123" || record.MessageType != "password_reset" || record.To != "user@example.com" {
+		t.Fatalf("unexpected record: %+v", record)
+	}
+	if record.TextBody != "plain body" || record.HTMLBody != "<p>html body</p>" {
+		t.Fatalf("unexpected bodies: %+v", record)
+	}
+}
+
+func TestMockEmailSenderValidation(t *testing.T) {
+	if _, err := NewMockEmailSender("").Send(context.Background(), queue.EmailJob{
+		To:       "user@example.com",
+		Subject:  "Hello",
+		TextBody: "World",
+	}); err == nil {
+		t.Fatalf("expected config error")
+	}
+}
diff --git a/internal/service/opc_service.go b/internal/service/opc_service.go
new file mode 100644
index 0000000..0c155a7
--- /dev/null
+++ b/internal/service/opc_service.go
@@ -0,0 +1,51 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/opc"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type OpcService struct {
+	repo opc.Repository
+}
+
+func NewOpcService(repo opc.Repository) *OpcService {
+	return &OpcService{repo: repo}
+}
+
+func (s *OpcService) Create(ctx context.Context, o *opc.Opc) error {
+	return s.repo.Create(ctx, o)
+}
+
+func (s *OpcService) Update(ctx context.Context, o *opc.Opc) error {
+	return s.repo.Update(ctx, o)
+}
+
+func (s *OpcService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *OpcService) GetByID(ctx context.Context, id []byte) (*opc.Opc, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *OpcService) List(ctx context.Context, filter, sort string, limit, offset int) ([]opc.Opc, int64, error) {
+	return s.repo.List(ctx, filter, normalizeOpcSort(sort), limit, offset)
+}
+
+func normalizeOpcSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", true)),
+			"sortkey",
+		),
+		sortField("name", "title"),
+		sortField("note"),
+		sortField("is_active"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/opc_service_test.go b/internal/service/opc_service_test.go
new file mode 100644
index 0000000..79a9449
--- /dev/null
+++ b/internal/service/opc_service_test.go
@@ -0,0 +1,223 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/opc"
+)
+
+type opcRepoMock struct {
+	createCalled  bool
+	updateCalled  bool
+	deleteCalled  bool
+	getByIDCalled bool
+	listCalled    bool
+
+	lastCreate     *opc.Opc
+	lastUpdate     *opc.Opc
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastGetByID    []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+
+	getByIDResult *opc.Opc
+	listResult    []opc.Opc
+	listTotal     int64
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+}
+
+func (m *opcRepoMock) Create(_ context.Context, o *opc.Opc) error {
+	m.createCalled = true
+	m.lastCreate = o
+	return m.createErr
+}
+
+func (m *opcRepoMock) Update(_ context.Context, o *opc.Opc) error {
+	m.updateCalled = true
+	m.lastUpdate = o
+	return m.updateErr
+}
+
+func (m *opcRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return m.deleteErr
+}
+
+func (m *opcRepoMock) GetByID(_ context.Context, id []byte) (*opc.Opc, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *opcRepoMock) List(_ context.Context, filter, sort string, limit, offset int) ([]opc.Opc, int64, error) {
+	m.listCalled = true
+	m.lastListFilter = filter
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listResult, m.listTotal, m.listErr
+}
+
+func TestNewOpcService(t *testing.T) {
+	repo := &opcRepoMock{}
+	svc := NewOpcService(repo)
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service and repo initialized")
+	}
+}
+
+func TestOpcServiceCreate(t *testing.T) {
+	repo := &opcRepoMock{}
+	svc := NewOpcService(repo)
+	row := &opc.Opc{Title: "Title"}
+
+	if err := svc.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.createCalled || repo.lastCreate != row {
+		t.Fatalf("expected Create forwarded to repo")
+	}
+
+	repo.createErr = errors.New("create failed")
+	if err := svc.Create(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestOpcServiceUpdate(t *testing.T) {
+	repo := &opcRepoMock{}
+	svc := NewOpcService(repo)
+	row := &opc.Opc{Title: "Updated"}
+
+	if err := svc.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateCalled || repo.lastUpdate != row {
+		t.Fatalf("expected Update forwarded to repo")
+	}
+
+	repo.updateErr = errors.New("update failed")
+	if err := svc.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestOpcServiceDelete(t *testing.T) {
+	repo := &opcRepoMock{}
+	svc := NewOpcService(repo)
+	id := []byte("id")
+	deletedBy := []byte("by")
+
+	if err := svc.Delete(context.Background(), id, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.deleteCalled {
+		t.Fatalf("expected Delete forwarded to repo")
+	}
+	if string(repo.lastDeleteID) != string(id) || string(repo.lastDeleteBy) != string(deletedBy) {
+		t.Fatalf("expected delete params forwarded")
+	}
+
+	repo.deleteErr = errors.New("delete failed")
+	if err := svc.Delete(context.Background(), id, deletedBy); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestOpcServiceGetByID(t *testing.T) {
+	expected := &opc.Opc{Title: "A"}
+	repo := &opcRepoMock{getByIDResult: expected}
+	svc := NewOpcService(repo)
+	id := []byte("id")
+
+	got, err := svc.GetByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != expected {
+		t.Fatalf("unexpected result")
+	}
+	if !repo.getByIDCalled || string(repo.lastGetByID) != string(id) {
+		t.Fatalf("expected GetByID forwarded")
+	}
+
+	repo.getByIDErr = errors.New("get failed")
+	if _, err := svc.GetByID(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestOpcServiceList(t *testing.T) {
+	repo := &opcRepoMock{
+		listResult: []opc.Opc{{Title: "A"}},
+		listTotal:  1,
+	}
+	svc := NewOpcService(repo)
+
+	rows, total, err := svc.List(context.Background(), "find", "title", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if !repo.listCalled {
+		t.Fatalf("expected List forwarded to repo")
+	}
+	if repo.lastListFilter != "find" || repo.lastListSort != "name ASC" || repo.lastListLimit != 10 || repo.lastListOffset != 20 {
+		t.Fatalf("unexpected list args forwarded")
+	}
+
+	rows, total, err = svc.List(context.Background(), "find", "sortkey", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC" {
+		t.Fatalf("unexpected sortkey args forwarded: %q", repo.lastListSort)
+	}
+
+	repo.listErr = errors.New("list failed")
+	if _, _, err := svc.List(context.Background(), "", "unknown", 1, 0); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestNormalizeOpcSort(t *testing.T) {
+	cases := map[string]string{
+		"title":       "name ASC",
+		"-title":      "name DESC",
+		"sortkey":     "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC",
+		"-sortkey":    "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC",
+		"note":        "note ASC",
+		"-note":       "note DESC",
+		"is_active":   "is_active ASC",
+		"-is_active":  "is_active DESC",
+		"created_at":  "created_at ASC",
+		"-created_at": "created_at DESC",
+		"updated_at":  "updated_at ASC",
+		"-updated_at": "updated_at DESC",
+		"unknown":     "",
+		"":            "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeOpcSort(in); got != want {
+			t.Fatalf("normalizeOpcSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/other_person_service.go b/internal/service/other_person_service.go
new file mode 100644
index 0000000..6d774cf
--- /dev/null
+++ b/internal/service/other_person_service.go
@@ -0,0 +1,83 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"strings"
+
+	otherperson "wucher/internal/domain/other_person"
+)
+
+type OtherPersonService struct{ repo otherperson.Repository }
+
+func NewOtherPersonService(repo otherperson.Repository) *OtherPersonService {
+	return &OtherPersonService{repo: repo}
+}
+
+func (s *OtherPersonService) Upsert(ctx context.Context, p *otherperson.OtherPerson) error {
+	return s.repo.Upsert(ctx, p)
+}
+
+// Create registers a new master person. Name is required and the (name, mobile_phone,
+// email) identity must be unique among live rows.
+func (s *OtherPersonService) Create(ctx context.Context, p *otherperson.OtherPerson) error {
+	p.Name = strings.TrimSpace(p.Name)
+	p.MobilePhone = strings.TrimSpace(p.MobilePhone)
+	p.Email = strings.TrimSpace(p.Email)
+	if p.Name == "" {
+		return otherperson.ErrNameRequired
+	}
+	existing, err := s.repo.FindByIdentity(ctx, p.Name, p.MobilePhone, p.Email)
+	if err != nil {
+		return err
+	}
+	if existing != nil {
+		return otherperson.ErrDuplicate
+	}
+	return s.repo.Create(ctx, p)
+}
+
+// Update replaces the identity fields of an existing master person. The new identity must
+// not collide with a different live row.
+func (s *OtherPersonService) Update(ctx context.Context, p *otherperson.OtherPerson) error {
+	p.Name = strings.TrimSpace(p.Name)
+	p.MobilePhone = strings.TrimSpace(p.MobilePhone)
+	p.Email = strings.TrimSpace(p.Email)
+	if p.Name == "" {
+		return otherperson.ErrNameRequired
+	}
+	current, err := s.repo.GetByID(ctx, p.ID)
+	if err != nil {
+		return err
+	}
+	if current == nil {
+		return otherperson.ErrNotFound
+	}
+	existing, err := s.repo.FindByIdentity(ctx, p.Name, p.MobilePhone, p.Email)
+	if err != nil {
+		return err
+	}
+	if existing != nil && !bytes.Equal(existing.ID, p.ID) {
+		return otherperson.ErrDuplicate
+	}
+	return s.repo.Update(ctx, p)
+}
+
+func (s *OtherPersonService) Delete(ctx context.Context, id, actor []byte) error {
+	current, err := s.repo.GetByID(ctx, id)
+	if err != nil {
+		return err
+	}
+	if current == nil {
+		return otherperson.ErrNotFound
+	}
+	return s.repo.Delete(ctx, id, actor)
+}
+
+func (s *OtherPersonService) GetByID(ctx context.Context, id []byte) (*otherperson.OtherPerson, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *OtherPersonService) Search(ctx context.Context, q string, limit, offset int) ([]otherperson.OtherPerson, int64, error) {
+	return s.repo.Search(ctx, q, limit, offset)
+}
diff --git a/internal/service/other_person_service_test.go b/internal/service/other_person_service_test.go
new file mode 100644
index 0000000..d78d914
--- /dev/null
+++ b/internal/service/other_person_service_test.go
@@ -0,0 +1,142 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	otherperson "wucher/internal/domain/other_person"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type fakeOtherPersonRepo struct {
+	byID       map[string]*otherperson.OtherPerson
+	identity   map[string]*otherperson.OtherPerson // key: name|phone|email
+	created    *otherperson.OtherPerson
+	updated    *otherperson.OtherPerson
+	deletedID  []byte
+	forceError error
+}
+
+func newFakeOtherPersonRepo() *fakeOtherPersonRepo {
+	return &fakeOtherPersonRepo{
+		byID:     map[string]*otherperson.OtherPerson{},
+		identity: map[string]*otherperson.OtherPerson{},
+	}
+}
+
+func identityKey(name, phone, email string) string { return name + "|" + phone + "|" + email }
+
+func (r *fakeOtherPersonRepo) Upsert(context.Context, *otherperson.OtherPerson) error { return nil }
+
+func (r *fakeOtherPersonRepo) Create(_ context.Context, p *otherperson.OtherPerson) error {
+	if r.forceError != nil {
+		return r.forceError
+	}
+	if len(p.ID) == 0 {
+		p.ID = uuidv7.MustBytes()
+	}
+	r.created = p
+	cp := *p
+	r.byID[string(p.ID)] = &cp
+	r.identity[identityKey(p.Name, p.MobilePhone, p.Email)] = &cp
+	return nil
+}
+
+func (r *fakeOtherPersonRepo) Update(_ context.Context, p *otherperson.OtherPerson) error {
+	if r.forceError != nil {
+		return r.forceError
+	}
+	r.updated = p
+	cp := *p
+	r.byID[string(p.ID)] = &cp
+	return nil
+}
+
+func (r *fakeOtherPersonRepo) Delete(_ context.Context, id, _ []byte) error {
+	if r.forceError != nil {
+		return r.forceError
+	}
+	r.deletedID = id
+	delete(r.byID, string(id))
+	return nil
+}
+
+func (r *fakeOtherPersonRepo) GetByID(_ context.Context, id []byte) (*otherperson.OtherPerson, error) {
+	return r.byID[string(id)], nil
+}
+
+func (r *fakeOtherPersonRepo) FindByIdentity(_ context.Context, name, phone, email string) (*otherperson.OtherPerson, error) {
+	return r.identity[identityKey(name, phone, email)], nil
+}
+
+func (r *fakeOtherPersonRepo) Search(context.Context, string, int, int) ([]otherperson.OtherPerson, int64, error) {
+	return nil, 0, nil
+}
+
+func TestOtherPersonServiceCreate(t *testing.T) {
+	repo := newFakeOtherPersonRepo()
+	svc := NewOtherPersonService(repo)
+	ctx := context.Background()
+
+	// Name required.
+	if err := svc.Create(ctx, &otherperson.OtherPerson{Name: "   "}); !errors.Is(err, otherperson.ErrNameRequired) {
+		t.Fatalf("expected ErrNameRequired, got %v", err)
+	}
+
+	// Happy path.
+	p := &otherperson.OtherPerson{Name: "Guest", MobilePhone: "1", Email: "g@x.io"}
+	if err := svc.Create(ctx, p); err != nil {
+		t.Fatalf("create: %v", err)
+	}
+	if len(p.ID) == 0 || repo.created == nil {
+		t.Fatalf("expected create persisted")
+	}
+
+	// Duplicate identity rejected.
+	dup := &otherperson.OtherPerson{Name: "Guest", MobilePhone: "1", Email: "g@x.io"}
+	if err := svc.Create(ctx, dup); !errors.Is(err, otherperson.ErrDuplicate) {
+		t.Fatalf("expected ErrDuplicate, got %v", err)
+	}
+}
+
+func TestOtherPersonServiceUpdate(t *testing.T) {
+	repo := newFakeOtherPersonRepo()
+	svc := NewOtherPersonService(repo)
+	ctx := context.Background()
+
+	// Seed two rows.
+	a := &otherperson.OtherPerson{Name: "Alpha", MobilePhone: "1", Email: "a@x.io"}
+	b := &otherperson.OtherPerson{Name: "Beta", MobilePhone: "2", Email: "b@x.io"}
+	_ = svc.Create(ctx, a)
+	_ = svc.Create(ctx, b)
+
+	// Updating a missing id -> not found.
+	missing := &otherperson.OtherPerson{ID: uuidv7.MustBytes(), Name: "X"}
+	if err := svc.Update(ctx, missing); !errors.Is(err, otherperson.ErrNotFound) {
+		t.Fatalf("expected ErrNotFound, got %v", err)
+	}
+
+	// Updating A to B's identity -> duplicate.
+	clash := &otherperson.OtherPerson{ID: a.ID, Name: "Beta", MobilePhone: "2", Email: "b@x.io"}
+	if err := svc.Update(ctx, clash); !errors.Is(err, otherperson.ErrDuplicate) {
+		t.Fatalf("expected ErrDuplicate, got %v", err)
+	}
+
+	// Updating A to a fresh identity -> ok.
+	ok := &otherperson.OtherPerson{ID: a.ID, Name: "Alpha2", MobilePhone: "1", Email: "a@x.io"}
+	if err := svc.Update(ctx, ok); err != nil {
+		t.Fatalf("expected update ok, got %v", err)
+	}
+	if repo.updated == nil || repo.updated.Name != "Alpha2" {
+		t.Fatalf("update not forwarded")
+	}
+}
+
+func TestOtherPersonServiceDeleteNotFound(t *testing.T) {
+	repo := newFakeOtherPersonRepo()
+	svc := NewOtherPersonService(repo)
+	if err := svc.Delete(context.Background(), uuidv7.MustBytes(), nil); !errors.Is(err, otherperson.ErrNotFound) {
+		t.Fatalf("expected ErrNotFound, got %v", err)
+	}
+}
diff --git a/internal/service/patient_data_service.go b/internal/service/patient_data_service.go
new file mode 100644
index 0000000..acd4006
--- /dev/null
+++ b/internal/service/patient_data_service.go
@@ -0,0 +1,46 @@
+package service
+
+import (
+	"context"
+
+	patientdata "wucher/internal/domain/patient_data"
+)
+
+type PatientDataService struct {
+	repo patientdata.Repository
+}
+
+func NewPatientDataService(repo patientdata.Repository) *PatientDataService {
+	return &PatientDataService{repo: repo}
+}
+
+func (s *PatientDataService) Create(ctx context.Context, row *patientdata.PatientData) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *PatientDataService) Update(ctx context.Context, row *patientdata.PatientData) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *PatientDataService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *PatientDataService) GetByID(ctx context.Context, id []byte) (*patientdata.PatientData, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *PatientDataService) List(ctx context.Context, filter, sort string, limit, offset int) ([]patientdata.PatientData, int64, error) {
+	return s.repo.List(ctx, filter, normalizePatientDataSort(sort), limit, offset)
+}
+
+func normalizePatientDataSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortField("family_name"),
+		sortField("first_name"),
+		sortField("birth_date"),
+		sortField("gender"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/reserve_ac_service.go b/internal/service/reserve_ac_service.go
new file mode 100644
index 0000000..4e9571b
--- /dev/null
+++ b/internal/service/reserve_ac_service.go
@@ -0,0 +1,82 @@
+package service
+
+import (
+	"context"
+	"strings"
+
+	reserveac "wucher/internal/domain/reserve_ac"
+	"wucher/internal/shared/pkg/reserveacutil"
+	shareddto "wucher/internal/transport/http/dto/shared"
+)
+
+type ReserveAcService struct {
+	repo reserveac.ReserveAcRepository
+}
+
+func NewReserveAcService(repo reserveac.ReserveAcRepository) *ReserveAcService {
+	return &ReserveAcService{repo: repo}
+}
+
+func (s *ReserveAcService) Create(ctx context.Context, row *reserveac.ReserveAc) error {
+	row.Status = reserveacutil.NormalizeStatus(row.Status)
+	return s.repo.Create(ctx, row)
+}
+
+func (s *ReserveAcService) Update(ctx context.Context, row *reserveac.ReserveAc) error {
+	row.Status = reserveacutil.NormalizeStatus(row.Status)
+	return s.repo.Update(ctx, row)
+}
+
+func (s *ReserveAcService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *ReserveAcService) GetByID(ctx context.Context, id []byte) (*reserveac.ReserveAc, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *ReserveAcService) GetActiveByInspectionID(ctx context.Context, inspectionID []byte) (*reserveac.ReserveAc, error) {
+	return s.repo.GetActiveByInspectionID(ctx, inspectionID)
+}
+
+func (s *ReserveAcService) List(ctx context.Context, filter string, sort string, limit, offset int) ([]reserveac.ReserveAc, int64, error) {
+	return s.repo.List(ctx, filter, normalizeReserveAcSort(sort), limit, offset)
+}
+
+func (s *ReserveAcService) AircraftExists(ctx context.Context, helicopterID []byte) (bool, error) {
+	return s.repo.AircraftExists(ctx, helicopterID)
+}
+
+func (s *ReserveAcService) FlightInspectionExists(ctx context.Context, inspectionID []byte) (bool, error) {
+	return s.repo.FlightInspectionExists(ctx, inspectionID)
+}
+
+func (s *ReserveAcService) ExistsActiveByInspectionID(ctx context.Context, inspectionID []byte, excludeID []byte) (bool, error) {
+	return s.repo.ExistsActiveByInspectionID(ctx, inspectionID, excludeID)
+}
+
+func (s *ReserveAcService) GetLastDailyInspectionByHelicopterID(ctx context.Context, helicopterID []byte) (*shareddto.LastDailyInspection, error) {
+	return s.repo.GetLastDailyInspectionByHelicopterID(ctx, helicopterID)
+}
+
+func (s *ReserveAcService) GetLastDailyInspectionSummaryByHelicopterID(ctx context.Context, helicopterID []byte) (*shareddto.LastDailyInspectionSummary, error) {
+	type lastDailyInspectionSummaryRepository interface {
+		GetLastDailyInspectionSummaryByHelicopterID(ctx context.Context, helicopterID []byte) (*shareddto.LastDailyInspectionSummary, error)
+	}
+
+	if repo, ok := any(s.repo).(lastDailyInspectionSummaryRepository); ok {
+		return repo.GetLastDailyInspectionSummaryByHelicopterID(ctx, helicopterID)
+	}
+	return nil, nil
+}
+
+func normalizeReserveAcSort(sort string) string {
+	if normalized := normalizeSortByRules(strings.TrimSpace(sort),
+		sortExpr("status ASC, created_at ASC", "status DESC, created_at DESC", "status"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	); normalized != "" {
+		return normalized
+	}
+	return "created_at DESC"
+}
diff --git a/internal/service/reserve_ac_update_service.go b/internal/service/reserve_ac_update_service.go
new file mode 100644
index 0000000..a8f3088
--- /dev/null
+++ b/internal/service/reserve_ac_update_service.go
@@ -0,0 +1,555 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"strings"
+	"time"
+
+	beforeflightinspection "wucher/internal/domain/before_flight_inspection"
+	"wucher/internal/domain/flight"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	flightinspectionfilechecklist "wucher/internal/domain/flight_inspection_file_checklist"
+	flightprepcheck "wucher/internal/domain/flight_prep_check"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	reserveac "wucher/internal/domain/reserve_ac"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+)
+
+// ReserveAcUpdateError carries structured validation/update failures from the
+// application service layer back to the HTTP handler.
+type ReserveAcUpdateError struct {
+	Status  int
+	Title   string
+	Detail  string
+	Pointer string
+}
+
+func (e *ReserveAcUpdateError) Error() string {
+	if e == nil {
+		return ""
+	}
+	return e.Detail
+}
+
+type ReserveAcUpdateInput struct {
+	ID            []byte
+	ActorUserID   []byte
+	AircraftID    *string
+	FlightID      *string
+	Inspection    *requestdto.ReserveAcInspectionUpdateAttributes
+	Flight        reserveAcFlightService
+	Inspect       flightinspection.FlightInspectionService
+	Before        beforeflightinspection.Service
+	Prep          flightprepcheck.Service
+	HeliFile      helicopterfile.Service
+	FileChecklist flightinspectionfilechecklist.Service
+}
+
+type reserveAcFlightService interface {
+	GetByID(ctx context.Context, id []byte) (*flight.Flight, error)
+	GetByReserveAcID(ctx context.Context, reserveAcID []byte) (*flight.Flight, error)
+	Update(ctx context.Context, row *flight.Flight) error
+}
+
+type ReserveAcCreateInput struct {
+	HelicopterID   []byte
+	FlightID       []byte
+	InspectionDate time.Time
+	Before         *requestdto.ReserveAcBeforeInspectionAttributes
+	Prepare        *requestdto.ReserveAcPrepareInspectionAttributes
+	ActorUserID    []byte
+	Flight         reserveAcFlightService
+	Inspect        flightinspection.FlightInspectionService
+	BeforeSvc      beforeflightinspection.Service
+	Prep           flightprepcheck.Service
+	HeliFile       helicopterfile.Service
+	FileChecklist  flightinspectionfilechecklist.Service
+}
+
+func (s *ReserveAcService) UpdateDetailed(ctx context.Context, in ReserveAcUpdateInput) (*reserveac.ReserveAc, error) {
+	if s == nil || s.repo == nil {
+		return nil, &ReserveAcUpdateError{Status: 500, Title: "Update failed", Detail: "reserve ac service is not configured"}
+	}
+	if len(in.ID) != 16 {
+		return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "id is invalid UUID", Pointer: "/data/id"}
+	}
+
+	existing, err := s.repo.GetByID(ctx, in.ID)
+	if err != nil {
+		return nil, &ReserveAcUpdateError{Status: 400, Title: "Update failed", Detail: err.Error()}
+	}
+	if existing == nil {
+		return nil, &ReserveAcUpdateError{Status: 404, Title: "Not found", Detail: "reserve_ac not found"}
+	}
+
+	if in.FlightID != nil {
+		if in.Flight == nil {
+			return nil, &ReserveAcUpdateError{Status: 500, Title: "Update failed", Detail: "flight service is not configured"}
+		}
+		flightValue := strings.TrimSpace(*in.FlightID)
+		flightID, parseErr := uuidv7.ParseString(flightValue)
+		if parseErr != nil {
+			return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "flight_id is invalid UUID", Pointer: "/data/attributes/flight_id"}
+		}
+
+		targetFlight, flightErr := in.Flight.GetByID(ctx, flightID)
+		if flightErr != nil {
+			return nil, &ReserveAcUpdateError{Status: 400, Title: "Update failed", Detail: flightErr.Error()}
+		}
+		if targetFlight == nil {
+			return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "flight_id does not exist", Pointer: "/data/attributes/flight_id"}
+		}
+		if len(targetFlight.ReserveAcID) == 16 && !bytes.Equal(targetFlight.ReserveAcID, existing.ID) {
+			return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "flight already has reserve_ac assigned", Pointer: "/data/attributes/flight_id"}
+		}
+
+		currentFlight, currentErr := in.Flight.GetByReserveAcID(ctx, existing.ID)
+		if currentErr != nil {
+			return nil, &ReserveAcUpdateError{Status: 400, Title: "Update failed", Detail: currentErr.Error()}
+		}
+		if currentFlight != nil && !bytes.Equal(currentFlight.ID, targetFlight.ID) {
+			currentFlight.ReserveAcID = nil
+			currentFlight.UpdatedBy = in.ActorUserID
+			if updateErr := in.Flight.Update(ctx, currentFlight); updateErr != nil {
+				return nil, &ReserveAcUpdateError{Status: 400, Title: "Update failed", Detail: updateErr.Error()}
+			}
+		}
+
+		if len(targetFlight.ReserveAcID) != 16 || !bytes.Equal(targetFlight.ReserveAcID, existing.ID) {
+			targetFlight.ReserveAcID = append([]byte(nil), existing.ID...)
+			targetFlight.UpdatedBy = in.ActorUserID
+			if updateErr := in.Flight.Update(ctx, targetFlight); updateErr != nil {
+				return nil, &ReserveAcUpdateError{Status: 400, Title: "Update failed", Detail: updateErr.Error()}
+			}
+		}
+	}
+
+	if in.AircraftID != nil && strings.TrimSpace(*in.AircraftID) != "" {
+		helicopterValue := strings.TrimSpace(*in.AircraftID)
+		helicopterID, parseErr := uuidv7.ParseString(helicopterValue)
+		if parseErr != nil {
+			return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "helicopter_id is invalid UUID", Pointer: "/data/attributes/helicopter_id"}
+		}
+		exists, existsErr := s.repo.AircraftExists(ctx, helicopterID)
+		if existsErr != nil {
+			return nil, &ReserveAcUpdateError{Status: 400, Title: "Update failed", Detail: existsErr.Error()}
+		}
+		if !exists {
+			return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "helicopter_id does not exist", Pointer: "/data/attributes/helicopter_id"}
+		}
+		existing.AircraftID = helicopterID
+	}
+
+	if in.Inspection != nil {
+		if in.Inspect == nil {
+			return nil, &ReserveAcUpdateError{Status: 500, Title: "Update failed", Detail: "flight inspection service is not configured"}
+		}
+		if in.Before == nil {
+			return nil, &ReserveAcUpdateError{Status: 500, Title: "Update failed", Detail: "before flight inspection service is not configured"}
+		}
+		if in.Prep == nil {
+			return nil, &ReserveAcUpdateError{Status: 500, Title: "Update failed", Detail: "flight prep check service is not configured"}
+		}
+		if in.HeliFile == nil {
+			return nil, &ReserveAcUpdateError{Status: 500, Title: "Update failed", Detail: "helicopter file service is not configured"}
+		}
+		if in.FileChecklist == nil {
+			return nil, &ReserveAcUpdateError{Status: 500, Title: "Update failed", Detail: "flight inspection file checklist service is not configured"}
+		}
+
+		inspectionRow, getErr := in.Inspect.GetByID(ctx, existing.InspectionID)
+		if getErr != nil {
+			return nil, &ReserveAcUpdateError{Status: 400, Title: "Update failed", Detail: getErr.Error()}
+		}
+		if inspectionRow == nil {
+			return nil, &ReserveAcUpdateError{Status: 404, Title: "Not found", Detail: "flight inspection not found"}
+		}
+
+		if in.Inspection.InspectionDate != nil {
+			inspectionDate, parseErr := time.Parse("2006-01-02", strings.TrimSpace(*in.Inspection.InspectionDate))
+			if parseErr != nil {
+				return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "inspection.inspection_date must be YYYY-MM-DD", Pointer: "/data/attributes/inspection/inspection_date"}
+			}
+			inspectionRow.InspectionDate = inspectionDate.UTC()
+			inspectionRow.UpdatedBy = in.ActorUserID
+			if updateErr := in.Inspect.Update(ctx, inspectionRow); updateErr != nil {
+				return nil, &ReserveAcUpdateError{Status: 400, Title: "Update failed", Detail: updateErr.Error()}
+			}
+		}
+
+		if in.Inspection.Before != nil {
+			beforeReq := &beforeflightinspection.UpsertRequest{
+				OilEngineNR1Checked:       in.Inspection.Before.OilEngineNR1Checked,
+				OilEngineNR2Checked:       in.Inspection.Before.OilEngineNR2Checked,
+				HydraulicLHChecked:        in.Inspection.Before.HydraulicLHChecked,
+				HydraulicRHChecked:        in.Inspection.Before.HydraulicRHChecked,
+				OilTransmissionMGBChecked: in.Inspection.Before.OilTransmissionMGBChecked,
+				OilTransmissionIGBChecked: in.Inspection.Before.OilTransmissionIGBChecked,
+				OilTransmissionTGBChecked: in.Inspection.Before.OilTransmissionTGBChecked,
+				FuelAmount:                in.Inspection.Before.FuelAmount,
+				FuelUnit:                  in.Inspection.Before.FuelUnit,
+				FuelAddedAmount:           in.Inspection.Before.FuelAddedAmount,
+				Note:                      in.Inspection.Before.Note,
+			}
+			if _, upsertErr := in.Before.Upsert(ctx, existing.InspectionID, beforeReq); upsertErr != nil {
+				return nil, &ReserveAcUpdateError{Status: 400, Title: "Update failed", Detail: upsertErr.Error()}
+			}
+			if in.Inspection.Before.FileChecklist != nil {
+				if err := s.upsertInspectionFileChecklistSection(ctx, in, existing.InspectionID, existing.AircraftID, helicopterfile.SectionBeforeFirstFlightInspection, in.Inspection.Before.FileChecklist, "/data/attributes/inspection/before/file_checklist", existing.ID); err != nil {
+					return nil, err
+				}
+			}
+		}
+
+		if in.Inspection.Prepare != nil {
+			if _, upsertErr := in.Prep.UpsertByFlightInspection(ctx, existing.InspectionID, &flightprepcheck.UpsertRequest{
+				NOTAMBriefing:         in.Inspection.Prepare.NotamBriefing,
+				WeatherBriefing:       in.Inspection.Prepare.WeatherBriefing,
+				OperationalFlightPlan: in.Inspection.Prepare.OperationalFlightPlan,
+			}); upsertErr != nil {
+				return nil, &ReserveAcUpdateError{Status: 400, Title: "Update failed", Detail: upsertErr.Error()}
+			}
+			if in.Inspection.Prepare.FileChecklist != nil {
+				if err := s.upsertInspectionFileChecklistSection(ctx, in, existing.InspectionID, existing.AircraftID, helicopterfile.SectionFlightPreparationAndWB, in.Inspection.Prepare.FileChecklist, "/data/attributes/inspection/prepare/file_checklist", existing.ID); err != nil {
+					return nil, err
+				}
+			}
+		}
+	}
+
+	existing.UpdatedBy = in.ActorUserID
+	existing.Status = s.calculateReserveAcStatus(ctx, in, existing.InspectionID, existing.AircraftID)
+	if err := s.Update(ctx, existing); err != nil {
+		return nil, &ReserveAcUpdateError{Status: 400, Title: "Update failed", Detail: err.Error()}
+	}
+
+	return existing, nil
+}
+
+func (s *ReserveAcService) CreateDetailed(ctx context.Context, in ReserveAcCreateInput) (*reserveac.ReserveAc, error) {
+	if s == nil || s.repo == nil {
+		return nil, &ReserveAcUpdateError{Status: 500, Title: "Create failed", Detail: "reserve ac service is not configured"}
+	}
+	if len(in.HelicopterID) != 16 {
+		return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "helicopter_id is invalid UUID", Pointer: "/data/attributes/helicopter_id"}
+	}
+	if len(in.FlightID) != 16 {
+		return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "flight_id is invalid UUID", Pointer: "/data/attributes/flight_id"}
+	}
+	if in.Before == nil {
+		return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "inspection.before is required", Pointer: "/data/attributes/inspection/before"}
+	}
+	if in.Prepare == nil {
+		return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "inspection.prepare is required", Pointer: "/data/attributes/inspection/prepare"}
+	}
+	if in.Flight == nil {
+		return nil, &ReserveAcUpdateError{Status: 500, Title: "Create failed", Detail: "flight service is not configured"}
+	}
+	if in.Inspect == nil {
+		return nil, &ReserveAcUpdateError{Status: 500, Title: "Create failed", Detail: "flight inspection service is not configured"}
+	}
+	if in.BeforeSvc == nil {
+		return nil, &ReserveAcUpdateError{Status: 500, Title: "Create failed", Detail: "before flight inspection service is not configured"}
+	}
+	if in.Prep == nil {
+		return nil, &ReserveAcUpdateError{Status: 500, Title: "Create failed", Detail: "flight prep check service is not configured"}
+	}
+	if in.HeliFile == nil {
+		return nil, &ReserveAcUpdateError{Status: 500, Title: "Create failed", Detail: "helicopter file service is not configured"}
+	}
+	if in.FileChecklist == nil {
+		return nil, &ReserveAcUpdateError{Status: 500, Title: "Create failed", Detail: "flight inspection file checklist service is not configured"}
+	}
+
+	flightRow, err := in.Flight.GetByID(ctx, in.FlightID)
+	if err != nil {
+		return nil, &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+	}
+	if flightRow == nil {
+		return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "flight_id does not exist", Pointer: "/data/attributes/flight_id"}
+	}
+	if len(flightRow.ReserveAcID) == 16 {
+		return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "flight already has reserve_ac assigned", Pointer: "/data/attributes/flight_id"}
+	}
+
+	exists, err := s.repo.AircraftExists(ctx, in.HelicopterID)
+	if err != nil {
+		return nil, &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+	}
+	if !exists {
+		return nil, &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "helicopter_id does not exist", Pointer: "/data/attributes/helicopter_id"}
+	}
+
+	inspection := &flightinspection.FlightInspection{
+		InspectionDate: in.InspectionDate.UTC(),
+		CreatedBy:      in.ActorUserID,
+		UpdatedBy:      in.ActorUserID,
+	}
+	if err := in.Inspect.CreateDraft(ctx, inspection); err != nil {
+		return nil, &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+	}
+
+	row := &reserveac.ReserveAc{
+		Status:       reserveac.StatusPending,
+		AircraftID:   append([]byte(nil), in.HelicopterID...),
+		InspectionID: append([]byte(nil), inspection.ID...),
+		CreatedBy:    in.ActorUserID,
+		UpdatedBy:    in.ActorUserID,
+	}
+	if err := s.Create(ctx, row); err != nil {
+		return nil, &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+	}
+
+	beforeReq := &beforeflightinspection.UpsertRequest{
+		OilEngineNR1Checked:       in.Before.OilEngineNR1Checked,
+		OilEngineNR2Checked:       in.Before.OilEngineNR2Checked,
+		HydraulicLHChecked:        in.Before.HydraulicLHChecked,
+		HydraulicRHChecked:        in.Before.HydraulicRHChecked,
+		OilTransmissionMGBChecked: in.Before.OilTransmissionMGBChecked,
+		OilTransmissionIGBChecked: in.Before.OilTransmissionIGBChecked,
+		OilTransmissionTGBChecked: in.Before.OilTransmissionTGBChecked,
+		FuelAmount:                in.Before.FuelAmount,
+		FuelUnit:                  in.Before.FuelUnit,
+		FuelAddedAmount:           in.Before.FuelAddedAmount,
+		Note:                      in.Before.Note,
+	}
+	if _, err := in.BeforeSvc.Upsert(ctx, inspection.ID, beforeReq); err != nil {
+		_ = s.Delete(ctx, row.ID, in.ActorUserID)
+		return nil, &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+	}
+	if _, err := in.Prep.InitializeChecks(ctx, inspection.ID); err != nil {
+		_ = s.Delete(ctx, row.ID, in.ActorUserID)
+		return nil, &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+	}
+	if _, err := in.Prep.UpsertByFlightInspection(ctx, inspection.ID, &flightprepcheck.UpsertRequest{
+		NOTAMBriefing:         in.Prepare.NotamBriefing,
+		WeatherBriefing:       in.Prepare.WeatherBriefing,
+		OperationalFlightPlan: in.Prepare.OperationalFlightPlan,
+	}); err != nil {
+		_ = s.Delete(ctx, row.ID, in.ActorUserID)
+		return nil, &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+	}
+	if in.Before.FileChecklist != nil {
+		if err := s.upsertInspectionFileChecklistSection(ctx, ReserveAcUpdateInput{
+			ActorUserID:   in.ActorUserID,
+			HeliFile:      in.HeliFile,
+			FileChecklist: in.FileChecklist,
+		}, inspection.ID, in.HelicopterID, helicopterfile.SectionBeforeFirstFlightInspection, in.Before.FileChecklist, "/data/attributes/inspection/before/file_checklist", row.ID); err != nil {
+			return nil, err
+		}
+	}
+	if in.Prepare.FileChecklist != nil {
+		if err := s.upsertInspectionFileChecklistSection(ctx, ReserveAcUpdateInput{
+			ActorUserID:   in.ActorUserID,
+			HeliFile:      in.HeliFile,
+			FileChecklist: in.FileChecklist,
+		}, inspection.ID, in.HelicopterID, helicopterfile.SectionFlightPreparationAndWB, in.Prepare.FileChecklist, "/data/attributes/inspection/prepare/file_checklist", row.ID); err != nil {
+			return nil, err
+		}
+	}
+
+	flightRow.ReserveAcID = append([]byte(nil), row.ID...)
+	flightRow.UpdatedBy = in.ActorUserID
+	if err := in.Flight.Update(ctx, flightRow); err != nil {
+		_ = s.Delete(ctx, row.ID, in.ActorUserID)
+		return nil, &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+	}
+
+	row.Status = s.calculateReserveAcStatus(ctx, ReserveAcUpdateInput{
+		Inspect:       in.Inspect,
+		Before:        in.BeforeSvc,
+		Prep:          in.Prep,
+		HeliFile:      in.HeliFile,
+		FileChecklist: in.FileChecklist,
+	}, inspection.ID, in.HelicopterID)
+	if err := s.Update(ctx, row); err != nil {
+		_ = s.Delete(ctx, row.ID, in.ActorUserID)
+		return nil, &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+	}
+
+	return row, nil
+}
+
+func (s *ReserveAcService) calculateReserveAcStatus(ctx context.Context, in ReserveAcUpdateInput, inspectionID []byte, helicopterID []byte) string {
+	if len(inspectionID) != 16 || len(helicopterID) != 16 {
+		return reserveac.StatusPending
+	}
+	if in.Inspect == nil || in.Before == nil || in.Prep == nil || in.HeliFile == nil || in.FileChecklist == nil {
+		return reserveac.StatusPending
+	}
+
+	inspectionRow, err := in.Inspect.GetByID(ctx, inspectionID)
+	if err != nil || inspectionRow == nil {
+		return reserveac.StatusPending
+	}
+	ckRows, err := in.FileChecklist.ListByInspectionID(ctx, inspectionID)
+	if err != nil {
+		return reserveac.StatusPending
+	}
+	isDoneByHeliFileID := make(map[string]bool, len(ckRows))
+	for i := range ckRows {
+		isDoneByHeliFileID[string(ckRows[i].HelicopterFileID)] = ckRows[i].IsDone
+	}
+
+	beforeRows, err := in.HeliFile.ListByHelicopterAndSection(ctx, helicopterID, helicopterfile.SectionBeforeFirstFlightInspection)
+	if err != nil {
+		return reserveac.StatusPending
+	}
+	prepareRows, err := in.HeliFile.ListByHelicopterAndSection(ctx, helicopterID, helicopterfile.SectionFlightPreparationAndWB)
+	if err != nil {
+		return reserveac.StatusPending
+	}
+	beforeData, _ := in.Before.GetByFlightInspectionID(ctx, inspectionID)
+	prepareData, _ := in.Prep.GetByFlightInspection(ctx, inspectionID)
+
+	beforeDone := countCompletedChecklist(beforeRows, isDoneByHeliFileID)
+	prepareDone := countCompletedChecklist(prepareRows, isDoneByHeliFileID)
+	totalChecklist := len(beforeRows) + len(prepareRows)
+	doneChecklist := beforeDone + prepareDone
+	if totalChecklist > 0 {
+		if doneChecklist == 0 {
+			return reserveac.StatusPending
+		}
+		if doneChecklist < totalChecklist {
+			return reserveac.StatusOnProgress
+		}
+		return reserveac.StatusApproved
+	}
+	if beforeData != nil || prepareData != nil {
+		return reserveac.StatusOnProgress
+	}
+	return reserveac.StatusPending
+}
+
+func countCompletedChecklist(files []helicopterfile.HelicopterFile, doneByID map[string]bool) int {
+	if len(files) == 0 {
+		return 0
+	}
+	completed := 0
+	for i := range files {
+		if doneByID[string(files[i].ID)] {
+			completed++
+		}
+	}
+	return completed
+}
+
+func (s *ReserveAcService) upsertInspectionFileChecklistSection(
+	ctx context.Context,
+	in ReserveAcUpdateInput,
+	inspectionID []byte,
+	helicopterID []byte,
+	section string,
+	payload []requestdto.ReserveAcFileChecklistItem,
+	payloadPointer string,
+	reserveAcID []byte,
+) error {
+	templateFiles, err := in.HeliFile.ListByHelicopterAndSection(ctx, helicopterID, section)
+	if err != nil {
+		if len(reserveAcID) == 16 {
+			_ = s.Delete(ctx, reserveAcID, in.ActorUserID)
+		}
+		return &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+	}
+
+	type requestedChecklist struct {
+		fileID []byte
+		isDone bool
+	}
+	requested := make([]requestedChecklist, 0, len(payload))
+	for i := range payload {
+		fileID, parseErr := uuidv7.ParseString(strings.TrimSpace(payload[i].HelicopterFileID))
+		if parseErr != nil {
+			if len(reserveAcID) == 16 {
+				_ = s.Delete(ctx, reserveAcID, in.ActorUserID)
+			}
+			return &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "helicopter_file_id is invalid UUID", Pointer: payloadPointer}
+		}
+		requested = append(requested, requestedChecklist{
+			fileID: fileID,
+			isDone: payload[i].IsDone,
+		})
+	}
+	requestedByFileID := make(map[string]bool, len(requested))
+	for i := range requested {
+		requestedByFileID[string(requested[i].fileID)] = requested[i].isDone
+	}
+
+	existingRows, err := in.FileChecklist.ListByInspectionID(ctx, inspectionID)
+	if err != nil {
+		if len(reserveAcID) == 16 {
+			_ = s.Delete(ctx, reserveAcID, in.ActorUserID)
+		}
+		return &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+	}
+	existingByFileID := make(map[string]*flightinspectionfilechecklist.FlightInspectionFileChecklist, len(existingRows))
+	for i := range existingRows {
+		fileID := string(existingRows[i].HelicopterFileID)
+		existingByFileID[fileID] = &existingRows[i]
+	}
+
+	templateSet := make(map[string]struct{}, len(templateFiles))
+	for i := range templateFiles {
+		fileKey := string(templateFiles[i].ID)
+		templateSet[fileKey] = struct{}{}
+
+		current := existingByFileID[fileKey]
+		targetDone, hasOverride := requestedByFileID[fileKey]
+
+		if templateFiles[i].IsMandatory && !targetDone {
+			if len(reserveAcID) == 16 {
+				_ = s.Delete(ctx, reserveAcID, in.ActorUserID)
+			}
+			return &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "file_checklist must be fully checked", Pointer: payloadPointer}
+		}
+
+		if current == nil {
+			if !hasOverride {
+				targetDone = false
+			}
+			newRow := &flightinspectionfilechecklist.FlightInspectionFileChecklist{
+				FlightInspectionID: inspectionID,
+				HelicopterFileID:   templateFiles[i].ID,
+				IsDone:             targetDone,
+				CreatedBy:          in.ActorUserID,
+				UpdatedBy:          in.ActorUserID,
+			}
+			if err := in.FileChecklist.Create(ctx, newRow); err != nil {
+				if len(reserveAcID) == 16 {
+					_ = s.Delete(ctx, reserveAcID, in.ActorUserID)
+				}
+				return &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+			}
+			continue
+		}
+
+		if !hasOverride {
+			targetDone = current.IsDone
+		}
+
+		if current.IsDone != targetDone {
+			current.IsDone = targetDone
+			current.UpdatedBy = in.ActorUserID
+			if err := in.FileChecklist.Update(ctx, current); err != nil {
+				if len(reserveAcID) == 16 {
+					_ = s.Delete(ctx, reserveAcID, in.ActorUserID)
+				}
+				return &ReserveAcUpdateError{Status: 400, Title: "Create failed", Detail: err.Error()}
+			}
+		}
+	}
+
+	for i := range requested {
+		if _, ok := templateSet[string(requested[i].fileID)]; ok {
+			continue
+		}
+		if len(reserveAcID) == 16 {
+			_ = s.Delete(ctx, reserveAcID, in.ActorUserID)
+		}
+		return &ReserveAcUpdateError{Status: 422, Title: "Validation error", Detail: "helicopter_file_id does not belong to selected helicopter/section", Pointer: payloadPointer}
+	}
+
+	return nil
+}
diff --git a/internal/service/role_service.go b/internal/service/role_service.go
new file mode 100644
index 0000000..5543eaf
--- /dev/null
+++ b/internal/service/role_service.go
@@ -0,0 +1,98 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"wucher/internal/domain/auth"
+)
+
+type RoleService struct {
+	repo auth.RoleRepository
+}
+
+func NewRoleService(repo auth.RoleRepository) *RoleService {
+	return &RoleService{repo: repo}
+}
+
+func (s *RoleService) Create(ctx context.Context, role *auth.Role) error {
+	if strings.TrimSpace(role.Name) == "" {
+		return errors.New("name is required")
+	}
+	return s.repo.CreateRole(ctx, role)
+}
+
+func (s *RoleService) Update(ctx context.Context, role *auth.Role) error {
+	if strings.TrimSpace(role.Name) == "" {
+		return errors.New("name is required")
+	}
+	return s.repo.UpdateRole(ctx, role)
+}
+
+func (s *RoleService) Delete(ctx context.Context, id []byte) error {
+	return s.repo.DeleteRole(ctx, id)
+}
+
+func (s *RoleService) GetByID(ctx context.Context, id []byte) (*auth.Role, error) {
+	return s.repo.GetRoleByID(ctx, id)
+}
+
+func (s *RoleService) GetByName(ctx context.Context, name string) (*auth.Role, error) {
+	return s.repo.GetRoleByName(ctx, name)
+}
+
+func (s *RoleService) GetPermissionByID(ctx context.Context, id []byte) (*auth.Permission, error) {
+	return s.repo.GetPermissionByID(ctx, id)
+}
+
+func (s *RoleService) GetPermissionByKey(ctx context.Context, key string) (*auth.Permission, error) {
+	return s.repo.GetPermissionByKey(ctx, key)
+}
+
+func (s *RoleService) UpdatePermission(ctx context.Context, permission *auth.Permission) error {
+	if strings.TrimSpace(permission.Name) == "" {
+		return errors.New("name is required")
+	}
+	if strings.TrimSpace(permission.Key) == "" {
+		return errors.New("key is required")
+	}
+	return s.repo.UpdatePermission(ctx, permission)
+}
+
+func (s *RoleService) AssignPermission(ctx context.Context, roleID, permissionID []byte) (*auth.RolePermission, error) {
+	return s.repo.AssignPermission(ctx, roleID, permissionID)
+}
+
+func (s *RoleService) RemovePermission(ctx context.Context, roleID, permissionID []byte) error {
+	return s.repo.RemovePermission(ctx, roleID, permissionID)
+}
+
+func (s *RoleService) ListPermissions(ctx context.Context, filter, sort string, limit, offset int) ([]auth.Permission, int64, error) {
+	return s.repo.ListPermissions(ctx, filter, normalizePermissionSort(sort), limit, offset)
+}
+
+func (s *RoleService) ListPermissionsByRoleID(ctx context.Context, roleID []byte) ([]auth.Permission, error) {
+	return s.repo.ListPermissionsByRoleID(ctx, roleID)
+}
+
+func (s *RoleService) List(ctx context.Context, filterName, sort string, limit, offset int) ([]auth.Role, int64, error) {
+	return s.repo.ListRoles(ctx, filterName, normalizeSort(sort), limit, offset)
+}
+
+func normalizeSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortField("name"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
+
+func normalizePermissionSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortField("name"),
+		sortField("`key`", "key"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/role_service_test.go b/internal/service/role_service_test.go
new file mode 100644
index 0000000..dd8eaa3
--- /dev/null
+++ b/internal/service/role_service_test.go
@@ -0,0 +1,501 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/auth"
+)
+
+type roleServiceRepoMock struct {
+	createCalled       bool
+	updateCalled       bool
+	deleteCalled       bool
+	getByIDCalled      bool
+	getByNameCalled    bool
+	listCalled         bool
+	getPermByIDCalled  bool
+	getPermByKeyCalled bool
+	updatePermCalled   bool
+	assignPermCalled   bool
+	removePermCalled   bool
+	listPermCalled     bool
+
+	lastCreate             *auth.Role
+	lastUpdate             *auth.Role
+	lastDelete             []byte
+	lastListFilter         string
+	lastListSort           string
+	lastListLimit          int
+	lastListOffset         int
+	lastGetPermID          []byte
+	lastGetPermKey         string
+	lastAssignRoleID       []byte
+	lastAssignPermissionID []byte
+	lastRemoveRoleID       []byte
+	lastRemovePermissionID []byte
+	lastPermFilter         string
+	lastPermSort           string
+	lastPermLimit          int
+	lastPermOffset         int
+
+	roleByID             *auth.Role
+	roleByName           *auth.Role
+	listRoles            []auth.Role
+	listTotal            int64
+	permissionByID       *auth.Permission
+	permissionByKey      *auth.Permission
+	assignedPermission   *auth.RolePermission
+	listPermissions      []auth.Permission
+	listPermissionsTotal int64
+
+	createErr       error
+	updateErr       error
+	deleteErr       error
+	getByIDErr      error
+	getByNameErr    error
+	listErr         error
+	getPermByIDErr  error
+	getPermByKeyErr error
+	updatePermErr   error
+	assignPermErr   error
+	removePermErr   error
+	listPermErr     error
+}
+
+func (m *roleServiceRepoMock) CreateRole(_ context.Context, role *auth.Role) error {
+	m.createCalled = true
+	m.lastCreate = role
+	return m.createErr
+}
+
+func (m *roleServiceRepoMock) UpdateRole(_ context.Context, role *auth.Role) error {
+	m.updateCalled = true
+	m.lastUpdate = role
+	return m.updateErr
+}
+
+func (m *roleServiceRepoMock) DeleteRole(_ context.Context, id []byte) error {
+	m.deleteCalled = true
+	m.lastDelete = id
+	return m.deleteErr
+}
+
+func (m *roleServiceRepoMock) GetRoleByID(_ context.Context, _ []byte) (*auth.Role, error) {
+	m.getByIDCalled = true
+	return m.roleByID, m.getByIDErr
+}
+
+func (m *roleServiceRepoMock) GetRoleByName(_ context.Context, _ string) (*auth.Role, error) {
+	m.getByNameCalled = true
+	return m.roleByName, m.getByNameErr
+}
+
+func (m *roleServiceRepoMock) ListRoles(_ context.Context, filterName string, sort string, limit, offset int) ([]auth.Role, int64, error) {
+	m.listCalled = true
+	m.lastListFilter = filterName
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listRoles, m.listTotal, m.listErr
+}
+
+func (m *roleServiceRepoMock) GetPermissionByID(_ context.Context, id []byte) (*auth.Permission, error) {
+	m.getPermByIDCalled = true
+	m.lastGetPermID = id
+	return m.permissionByID, m.getPermByIDErr
+}
+
+func (m *roleServiceRepoMock) GetPermissionByKey(_ context.Context, key string) (*auth.Permission, error) {
+	m.getPermByKeyCalled = true
+	m.lastGetPermKey = key
+	return m.permissionByKey, m.getPermByKeyErr
+}
+
+func (m *roleServiceRepoMock) UpdatePermission(_ context.Context, permission *auth.Permission) error {
+	m.updatePermCalled = true
+	m.permissionByID = permission
+	return m.updatePermErr
+}
+
+func (m *roleServiceRepoMock) ListPermissions(_ context.Context, filter, sort string, limit, offset int) ([]auth.Permission, int64, error) {
+	m.listPermCalled = true
+	m.lastPermFilter = filter
+	m.lastPermSort = sort
+	m.lastPermLimit = limit
+	m.lastPermOffset = offset
+	return m.listPermissions, m.listPermissionsTotal, m.listPermErr
+}
+func (m *roleServiceRepoMock) ListPermissionsByRoleID(_ context.Context, _ []byte) ([]auth.Permission, error) {
+	return []auth.Permission{}, nil
+}
+
+func (m *roleServiceRepoMock) HasRolePermission(_ context.Context, _ []byte, _ string) (bool, error) {
+	return true, nil
+}
+
+func (m *roleServiceRepoMock) AssignPermission(_ context.Context, roleID, permissionID []byte) (*auth.RolePermission, error) {
+	m.assignPermCalled = true
+	m.lastAssignRoleID = roleID
+	m.lastAssignPermissionID = permissionID
+	if m.assignedPermission == nil {
+		m.assignedPermission = &auth.RolePermission{RoleID: roleID, PermissionID: permissionID}
+	}
+	return m.assignedPermission, m.assignPermErr
+}
+
+func (m *roleServiceRepoMock) RemovePermission(_ context.Context, roleID []byte, permissionID []byte) error {
+	m.removePermCalled = true
+	m.lastRemoveRoleID = roleID
+	m.lastRemovePermissionID = permissionID
+	return m.removePermErr
+}
+
+func TestRoleService_Create_Validation(t *testing.T) {
+	repo := &roleServiceRepoMock{}
+	svc := NewRoleService(repo)
+
+	if err := svc.Create(context.Background(), &auth.Role{Name: "   "}); err == nil {
+		t.Fatalf("expected validation error")
+	}
+	if repo.createCalled {
+		t.Fatalf("expected repo.CreateRole not called")
+	}
+}
+
+func TestRoleService_Create_RepoError(t *testing.T) {
+	repo := &roleServiceRepoMock{createErr: errors.New("db error")}
+	svc := NewRoleService(repo)
+
+	err := svc.Create(context.Background(), &auth.Role{Name: "admin"})
+	if err == nil {
+		t.Fatalf("expected error")
+	}
+	if !repo.createCalled {
+		t.Fatalf("expected repo.CreateRole called")
+	}
+}
+
+func TestRoleService_Update_Validation(t *testing.T) {
+	repo := &roleServiceRepoMock{}
+	svc := NewRoleService(repo)
+
+	if err := svc.Update(context.Background(), &auth.Role{Name: ""}); err == nil {
+		t.Fatalf("expected validation error")
+	}
+	if repo.updateCalled {
+		t.Fatalf("expected repo.UpdateRole not called")
+	}
+}
+
+func TestRoleService_Update_Success(t *testing.T) {
+	repo := &roleServiceRepoMock{}
+	svc := NewRoleService(repo)
+
+	err := svc.Update(context.Background(), &auth.Role{Name: "admin"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateCalled {
+		t.Fatalf("expected repo.UpdateRole called")
+	}
+}
+
+func TestRoleService_Delete_Success(t *testing.T) {
+	repo := &roleServiceRepoMock{}
+	svc := NewRoleService(repo)
+
+	id := []byte("id")
+	err := svc.Delete(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.deleteCalled {
+		t.Fatalf("expected repo.DeleteRole called")
+	}
+	if string(repo.lastDelete) != string(id) {
+		t.Fatalf("expected delete id passed to repo")
+	}
+}
+
+func TestRoleService_GetByID_Success(t *testing.T) {
+	repo := &roleServiceRepoMock{roleByID: &auth.Role{Name: "admin"}}
+	svc := NewRoleService(repo)
+
+	role, err := svc.GetByID(context.Background(), []byte("id"))
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if role == nil || role.Name != "admin" {
+		t.Fatalf("unexpected role")
+	}
+	if !repo.getByIDCalled {
+		t.Fatalf("expected repo.GetRoleByID called")
+	}
+}
+
+func TestRoleService_GetByName_Success(t *testing.T) {
+	repo := &roleServiceRepoMock{roleByName: &auth.Role{Name: "admin"}}
+	svc := NewRoleService(repo)
+
+	role, err := svc.GetByName(context.Background(), "admin")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if role == nil || role.Name != "admin" {
+		t.Fatalf("unexpected role")
+	}
+	if !repo.getByNameCalled {
+		t.Fatalf("expected repo.GetRoleByName called")
+	}
+}
+
+func TestRoleService_GetPermissionByID(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		perm := &auth.Permission{Name: "Users Read", Key: "users.read"}
+		repo := &roleServiceRepoMock{permissionByID: perm}
+		svc := NewRoleService(repo)
+
+		id := []byte("perm-id")
+		got, err := svc.GetPermissionByID(context.Background(), id)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if got == nil || got.Key != "users.read" {
+			t.Fatalf("unexpected permission: %+v", got)
+		}
+		if !repo.getPermByIDCalled {
+			t.Fatalf("expected repo.GetPermissionByID called")
+		}
+		if string(repo.lastGetPermID) != string(id) {
+			t.Fatalf("expected id forwarded to repo")
+		}
+	})
+
+	t.Run("repo error", func(t *testing.T) {
+		repo := &roleServiceRepoMock{getPermByIDErr: errors.New("db error")}
+		svc := NewRoleService(repo)
+
+		if _, err := svc.GetPermissionByID(context.Background(), []byte("perm-id")); err == nil {
+			t.Fatalf("expected error")
+		}
+	})
+}
+
+func TestRoleService_GetPermissionByKey(t *testing.T) {
+	repo := &roleServiceRepoMock{
+		permissionByKey: &auth.Permission{Name: "Delete User", Key: "user.delete"},
+	}
+	svc := NewRoleService(repo)
+
+	got, err := svc.GetPermissionByKey(context.Background(), "user.delete")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got == nil || got.Key != "user.delete" {
+		t.Fatalf("unexpected permission: %+v", got)
+	}
+	if !repo.getPermByKeyCalled {
+		t.Fatalf("expected repo.GetPermissionByKey called")
+	}
+	if repo.lastGetPermKey != "user.delete" {
+		t.Fatalf("expected key forwarded to repo")
+	}
+}
+
+func TestRoleService_UpdatePermission(t *testing.T) {
+	t.Run("validation", func(t *testing.T) {
+		repo := &roleServiceRepoMock{}
+		svc := NewRoleService(repo)
+
+		if err := svc.UpdatePermission(context.Background(), &auth.Permission{Name: "   ", Key: "user.delete"}); err == nil {
+			t.Fatalf("expected validation error for empty name")
+		}
+		if err := svc.UpdatePermission(context.Background(), &auth.Permission{Name: "Delete User", Key: "   "}); err == nil {
+			t.Fatalf("expected validation error for empty key")
+		}
+		if repo.updatePermCalled {
+			t.Fatalf("expected repo.UpdatePermission not called")
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := &roleServiceRepoMock{}
+		svc := NewRoleService(repo)
+
+		perm := &auth.Permission{Name: "Delete User", Key: "user.delete", RequiresPIN: true}
+		if err := svc.UpdatePermission(context.Background(), perm); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if !repo.updatePermCalled {
+			t.Fatalf("expected repo.UpdatePermission called")
+		}
+		if repo.permissionByID == nil || !repo.permissionByID.RequiresPIN {
+			t.Fatalf("expected permission forwarded to repo")
+		}
+	})
+}
+
+func TestRoleService_AssignPermission(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		roleID := []byte("role-id")
+		permID := []byte("perm-id")
+		repo := &roleServiceRepoMock{}
+		svc := NewRoleService(repo)
+
+		rp, err := svc.AssignPermission(context.Background(), roleID, permID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if rp == nil {
+			t.Fatalf("expected role permission")
+		}
+		if !repo.assignPermCalled {
+			t.Fatalf("expected repo.AssignPermission called")
+		}
+		if string(repo.lastAssignRoleID) != string(roleID) || string(repo.lastAssignPermissionID) != string(permID) {
+			t.Fatalf("expected roleID/permissionID forwarded to repo")
+		}
+	})
+
+	t.Run("repo error", func(t *testing.T) {
+		repo := &roleServiceRepoMock{assignPermErr: errors.New("assign error")}
+		svc := NewRoleService(repo)
+
+		if _, err := svc.AssignPermission(context.Background(), []byte("role-id"), []byte("perm-id")); err == nil {
+			t.Fatalf("expected error")
+		}
+	})
+}
+
+func TestRoleService_RemovePermission(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		roleID := []byte("role-id")
+		permID := []byte("perm-id")
+		repo := &roleServiceRepoMock{}
+		svc := NewRoleService(repo)
+
+		err := svc.RemovePermission(context.Background(), roleID, permID)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if !repo.removePermCalled {
+			t.Fatalf("expected repo.RemovePermission called")
+		}
+		if string(repo.lastRemoveRoleID) != string(roleID) || string(repo.lastRemovePermissionID) != string(permID) {
+			t.Fatalf("expected roleID/permissionID forwarded to repo")
+		}
+	})
+
+	t.Run("repo error", func(t *testing.T) {
+		repo := &roleServiceRepoMock{removePermErr: errors.New("remove error")}
+		svc := NewRoleService(repo)
+
+		if err := svc.RemovePermission(context.Background(), []byte("role-id"), []byte("perm-id")); err == nil {
+			t.Fatalf("expected error")
+		}
+	})
+}
+
+func TestRoleService_ListPermissions(t *testing.T) {
+	t.Run("normalize sort and forward args", func(t *testing.T) {
+		repo := &roleServiceRepoMock{
+			listPermissions:      []auth.Permission{{Name: "Users Read", Key: "users.read"}},
+			listPermissionsTotal: 1,
+		}
+		svc := NewRoleService(repo)
+
+		perms, total, err := svc.ListPermissions(context.Background(), "users", "-key", 10, 20)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(perms) != 1 || perms[0].Key != "users.read" || total != 1 {
+			t.Fatalf("unexpected list result: perms=%+v total=%d", perms, total)
+		}
+		if !repo.listPermCalled {
+			t.Fatalf("expected repo.ListPermissions called")
+		}
+		if repo.lastPermFilter != "users" {
+			t.Fatalf("expected filter forwarded")
+		}
+		if repo.lastPermSort != "`key` DESC" {
+			t.Fatalf("expected normalized permission sort, got %q", repo.lastPermSort)
+		}
+		if repo.lastPermLimit != 10 || repo.lastPermOffset != 20 {
+			t.Fatalf("expected limit/offset forwarded")
+		}
+	})
+
+	t.Run("repo error", func(t *testing.T) {
+		repo := &roleServiceRepoMock{listPermErr: errors.New("list error")}
+		svc := NewRoleService(repo)
+
+		if _, _, err := svc.ListPermissions(context.Background(), "", "bad", 10, 0); err == nil {
+			t.Fatalf("expected error")
+		}
+		if repo.lastPermSort != "" {
+			t.Fatalf("unexpected sort for invalid input, got %q", repo.lastPermSort)
+		}
+	})
+}
+
+func TestRoleService_List_NormalizeSort(t *testing.T) {
+	repo := &roleServiceRepoMock{}
+	svc := NewRoleService(repo)
+
+	_, _, err := svc.List(context.Background(), "adm", "-created_at", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.listCalled {
+		t.Fatalf("expected repo.ListRoles called")
+	}
+	if repo.lastListFilter != "adm" {
+		t.Fatalf("expected filter passed to repo")
+	}
+	if repo.lastListSort != "created_at DESC" {
+		t.Fatalf("expected normalized sort, got %q", repo.lastListSort)
+	}
+	if repo.lastListLimit != 10 || repo.lastListOffset != 20 {
+		t.Fatalf("expected limit/offset passed to repo")
+	}
+}
+
+func TestNormalizeSort(t *testing.T) {
+	cases := map[string]string{
+		"name":        "name ASC",
+		"-name":       "name DESC",
+		"created_at":  "created_at ASC",
+		"-created_at": "created_at DESC",
+		"updated_at":  "updated_at ASC",
+		"-updated_at": "updated_at DESC",
+		"":            "",
+		"bad":         "",
+	}
+	for in, want := range cases {
+		if got := normalizeSort(in); got != want {
+			t.Fatalf("normalizeSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestNormalizePermissionSort(t *testing.T) {
+	cases := map[string]string{
+		"name":        "name ASC",
+		"-name":       "name DESC",
+		"key":         "`key` ASC",
+		"-key":        "`key` DESC",
+		"created_at":  "created_at ASC",
+		"-created_at": "created_at DESC",
+		"updated_at":  "updated_at ASC",
+		"-updated_at": "updated_at DESC",
+		"":            "",
+		"bad":         "",
+	}
+	for in, want := range cases {
+		if got := normalizePermissionSort(in); got != want {
+			t.Fatalf("normalizePermissionSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/secret_protector.go b/internal/service/secret_protector.go
new file mode 100644
index 0000000..e3cd908
--- /dev/null
+++ b/internal/service/secret_protector.go
@@ -0,0 +1,62 @@
+package service
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"encoding/base64"
+	"errors"
+	"io"
+)
+
+type AESGCMProtector struct {
+	key []byte
+}
+
+func NewAESGCMProtectorFromBase64(keyB64 string) (*AESGCMProtector, error) {
+	if keyB64 == "" {
+		return nil, errors.New("empty key")
+	}
+	key, err := base64.StdEncoding.DecodeString(keyB64)
+	if err != nil {
+		return nil, err
+	}
+	if len(key) != 32 {
+		return nil, errors.New("key must be 32 bytes (base64-encoded)")
+	}
+	return &AESGCMProtector{key: key}, nil
+}
+
+func (p *AESGCMProtector) Encrypt(plain []byte) ([]byte, error) {
+	block, err := aes.NewCipher(p.key)
+	if err != nil {
+		return nil, err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, err
+	}
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
+		return nil, err
+	}
+	ciphertext := gcm.Seal(nonce, nonce, plain, nil)
+	return ciphertext, nil
+}
+
+func (p *AESGCMProtector) Decrypt(ciphertext []byte) ([]byte, error) {
+	block, err := aes.NewCipher(p.key)
+	if err != nil {
+		return nil, err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, err
+	}
+	if len(ciphertext) < gcm.NonceSize() {
+		return nil, errors.New("ciphertext too short")
+	}
+	nonce := ciphertext[:gcm.NonceSize()]
+	data := ciphertext[gcm.NonceSize():]
+	return gcm.Open(nil, nonce, data, nil)
+}
diff --git a/internal/service/secret_protector_test.go b/internal/service/secret_protector_test.go
new file mode 100644
index 0000000..be5e867
--- /dev/null
+++ b/internal/service/secret_protector_test.go
@@ -0,0 +1,94 @@
+package service
+
+import (
+	"bytes"
+	"encoding/base64"
+	"testing"
+)
+
+func TestNewAESGCMProtectorFromBase64(t *testing.T) {
+	if _, err := NewAESGCMProtectorFromBase64(""); err == nil {
+		t.Fatalf("expected error for empty key")
+	}
+	if _, err := NewAESGCMProtectorFromBase64("not-base64"); err == nil {
+		t.Fatalf("expected error for invalid base64")
+	}
+	shortKey := make([]byte, 16)
+	if _, err := NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(shortKey)); err == nil {
+		t.Fatalf("expected error for non-32-byte key")
+	}
+}
+
+func TestAESGCMProtector_EncryptDecrypt_RoundTrip(t *testing.T) {
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	p, err := NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+	if err != nil {
+		t.Fatalf("new protector: %v", err)
+	}
+
+	plain := []byte("hello-secret")
+	ciphertext, err := p.Encrypt(plain)
+	if err != nil {
+		t.Fatalf("encrypt: %v", err)
+	}
+	if bytes.Equal(ciphertext, plain) {
+		t.Fatalf("ciphertext should differ from plain")
+	}
+
+	decrypted, err := p.Decrypt(ciphertext)
+	if err != nil {
+		t.Fatalf("decrypt: %v", err)
+	}
+	if !bytes.Equal(decrypted, plain) {
+		t.Fatalf("decrypted plaintext mismatch")
+	}
+}
+
+func TestAESGCMProtector_Decrypt_CiphertextTooShort(t *testing.T) {
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	p, err := NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+	if err != nil {
+		t.Fatalf("new protector: %v", err)
+	}
+
+	if _, err := p.Decrypt([]byte("short")); err == nil {
+		t.Fatalf("expected ciphertext too short error")
+	}
+}
+
+func TestAESGCMProtector_Decrypt_TamperedCiphertext(t *testing.T) {
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	p, err := NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+	if err != nil {
+		t.Fatalf("new protector: %v", err)
+	}
+
+	ciphertext, err := p.Encrypt([]byte("hello-secret"))
+	if err != nil {
+		t.Fatalf("encrypt: %v", err)
+	}
+	ciphertext[len(ciphertext)-1] ^= 0x01
+
+	if _, err := p.Decrypt(ciphertext); err == nil {
+		t.Fatalf("expected auth failure for tampered ciphertext")
+	}
+}
+
+func TestAESGCMProtector_EncryptDecrypt_InvalidKey(t *testing.T) {
+	p := &AESGCMProtector{key: []byte("short")}
+	if _, err := p.Encrypt([]byte("hello")); err == nil {
+		t.Fatalf("expected encrypt error for invalid key")
+	}
+	if _, err := p.Decrypt([]byte("cipher")); err == nil {
+		t.Fatalf("expected decrypt error for invalid key")
+	}
+}
diff --git a/internal/service/ses_event.go b/internal/service/ses_event.go
new file mode 100644
index 0000000..a94c15f
--- /dev/null
+++ b/internal/service/ses_event.go
@@ -0,0 +1,102 @@
+package service
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"time"
+)
+
+var ErrInvalidSESEvent = errors.New("invalid ses event notification")
+
+type SESEventNotification struct {
+	EventType  string                     `json:"eventType"`
+	Mail       SESEventMail               `json:"mail"`
+	Bounce     *SESBounceEvent            `json:"bounce,omitempty"`
+	Complaint  *SESComplaintEvent         `json:"complaint,omitempty"`
+	Delivery   *SESDeliveryEvent          `json:"delivery,omitempty"`
+	Metadata   map[string]any             `json:"-"`
+	RawPayload map[string]json.RawMessage `json:"-"`
+}
+
+type SESEventMail struct {
+	Timestamp        time.Time           `json:"timestamp"`
+	MessageID        string              `json:"messageId"`
+	Source           string              `json:"source"`
+	Destination      []string            `json:"destination"`
+	Tags             map[string][]string `json:"tags,omitempty"`
+	ConfigurationSet string              `json:"configurationSet,omitempty"`
+}
+
+type SESBounceEvent struct {
+	BounceType        string `json:"bounceType,omitempty"`
+	BounceSubType     string `json:"bounceSubType,omitempty"`
+	ReportingMTA      string `json:"reportingMTA,omitempty"`
+	RemoteMTAIP       string `json:"remoteMtaIp,omitempty"`
+	FeedbackID        string `json:"feedbackId,omitempty"`
+	FeedbackSourceArn string `json:"feedbackSourceArn,omitempty"`
+}
+
+type SESComplaintEvent struct {
+	ComplaintFeedbackType string `json:"complaintFeedbackType,omitempty"`
+	UserAgent             string `json:"userAgent,omitempty"`
+	FeedbackID            string `json:"feedbackId,omitempty"`
+}
+
+type SESDeliveryEvent struct {
+	Timestamp            time.Time `json:"timestamp"`
+	ProcessingTimeMillis int64     `json:"processingTimeMillis,omitempty"`
+	ReportingMTA         string    `json:"reportingMTA,omitempty"`
+	SMTPResponse         string    `json:"smtpResponse,omitempty"`
+	RemoteMTAIP          string    `json:"remoteMtaIp,omitempty"`
+}
+
+type snsEnvelope struct {
+	Type    string `json:"Type"`
+	Message string `json:"Message"`
+}
+
+func ParseSESEventNotification(body []byte) (*SESEventNotification, error) {
+	body = []byte(strings.TrimSpace(string(body)))
+	if len(body) == 0 {
+		return nil, ErrInvalidSESEvent
+	}
+
+	if inner, ok := unwrapSNSMessage(body); ok {
+		body = inner
+	}
+
+	var raw map[string]json.RawMessage
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return nil, errors.Join(ErrInvalidSESEvent, err)
+	}
+
+	var event SESEventNotification
+	if err := json.Unmarshal(body, &event); err != nil {
+		return nil, errors.Join(ErrInvalidSESEvent, err)
+	}
+	if strings.TrimSpace(event.EventType) == "" {
+		return nil, errors.Join(ErrInvalidSESEvent, errors.New("event type is required"))
+	}
+	if strings.TrimSpace(event.Mail.MessageID) == "" {
+		return nil, errors.Join(ErrInvalidSESEvent, errors.New("mail message id is required"))
+	}
+	event.RawPayload = raw
+	return &event, nil
+}
+
+func unwrapSNSMessage(body []byte) ([]byte, bool) {
+	var envelope snsEnvelope
+	if err := json.Unmarshal(body, &envelope); err != nil {
+		return nil, false
+	}
+	if strings.TrimSpace(envelope.Message) == "" {
+		return nil, false
+	}
+	switch strings.TrimSpace(envelope.Type) {
+	case "Notification", "":
+		return []byte(envelope.Message), true
+	default:
+		return nil, false
+	}
+}
diff --git a/internal/service/ses_event_test.go b/internal/service/ses_event_test.go
new file mode 100644
index 0000000..1532961
--- /dev/null
+++ b/internal/service/ses_event_test.go
@@ -0,0 +1,44 @@
+package service
+
+import "testing"
+
+func TestParseSESEventNotification(t *testing.T) {
+	t.Run("parses direct SES event payload", func(t *testing.T) {
+		event, err := ParseSESEventNotification([]byte(`{
+			"eventType":"Delivery",
+			"mail":{"messageId":"ses-msg-1","source":"no-reply@example.com","destination":["user@example.com"]},
+			"delivery":{"processingTimeMillis":123}
+		}`))
+		if err != nil {
+			t.Fatalf("parse: %v", err)
+		}
+		if event.EventType != "Delivery" || event.Mail.MessageID != "ses-msg-1" {
+			t.Fatalf("unexpected event: %+v", event)
+		}
+		if event.Delivery == nil || event.Delivery.ProcessingTimeMillis != 123 {
+			t.Fatalf("expected delivery details, got %+v", event.Delivery)
+		}
+	})
+
+	t.Run("parses SNS-wrapped SES event payload", func(t *testing.T) {
+		event, err := ParseSESEventNotification([]byte(`{
+			"Type":"Notification",
+			"Message":"{\"eventType\":\"Bounce\",\"mail\":{\"messageId\":\"ses-msg-2\",\"source\":\"no-reply@example.com\",\"destination\":[\"user@example.com\"]},\"bounce\":{\"bounceType\":\"Permanent\"}}"
+		}`))
+		if err != nil {
+			t.Fatalf("parse: %v", err)
+		}
+		if event.EventType != "Bounce" || event.Mail.MessageID != "ses-msg-2" {
+			t.Fatalf("unexpected event: %+v", event)
+		}
+		if event.Bounce == nil || event.Bounce.BounceType != "Permanent" {
+			t.Fatalf("expected bounce details, got %+v", event.Bounce)
+		}
+	})
+
+	t.Run("rejects missing event type", func(t *testing.T) {
+		if _, err := ParseSESEventNotification([]byte(`{"mail":{"messageId":"ses-msg-3"}}`)); err == nil {
+			t.Fatalf("expected error for missing event type")
+		}
+	})
+}
diff --git a/internal/service/ses_sender.go b/internal/service/ses_sender.go
new file mode 100644
index 0000000..9be09bf
--- /dev/null
+++ b/internal/service/ses_sender.go
@@ -0,0 +1,305 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/mail"
+	"net/url"
+	"sort"
+	"strings"
+	"time"
+
+	awsv2 "github.com/aws/aws-sdk-go-v2/aws"
+	awsmiddleware "github.com/aws/aws-sdk-go-v2/aws/middleware"
+	awsconfig "github.com/aws/aws-sdk-go-v2/config"
+	"github.com/aws/aws-sdk-go-v2/service/sesv2"
+	sestypes "github.com/aws/aws-sdk-go-v2/service/sesv2/types"
+
+	"wucher/internal/config"
+	"wucher/internal/queue"
+	"wucher/internal/resilience"
+	"wucher/internal/shared/pkg/metrics"
+)
+
+const utf8Charset = "UTF-8"
+
+type sesAPI interface {
+	SendEmail(ctx context.Context, params *sesv2.SendEmailInput, optFns ...func(*sesv2.Options)) (*sesv2.SendEmailOutput, error)
+}
+
+type SESSender struct {
+	cfg       config.SESConfig
+	api       sesAPI
+	executor  *resilience.Executor
+	component string
+}
+
+func NewSESSender(ctx context.Context, cfg config.SESConfig) (*SESSender, error) {
+	api, err := newSESAPI(ctx, cfg)
+	if err != nil {
+		return nil, err
+	}
+	return &SESSender{
+		cfg:       cfg,
+		api:       api,
+		component: "worker",
+	}, nil
+}
+
+func NewSESSenderWithAPI(cfg config.SESConfig, api sesAPI) *SESSender {
+	return &SESSender{
+		cfg:       cfg,
+		api:       api,
+		component: "worker",
+	}
+}
+
+func (s *SESSender) WithExecutor(executor *resilience.Executor) *SESSender {
+	if s == nil {
+		return nil
+	}
+	s.executor = executor
+	return s
+}
+
+func (s *SESSender) WithMetricsComponent(component string) *SESSender {
+	if s == nil {
+		return nil
+	}
+	component = strings.TrimSpace(component)
+	if component == "" {
+		return s
+	}
+	s.component = component
+	return s
+}
+
+func (s *SESSender) Configured() bool {
+	return s != nil && strings.TrimSpace(s.cfg.Region) != "" && strings.TrimSpace(s.cfg.From) != ""
+}
+
+func (s *SESSender) Send(ctx context.Context, job queue.EmailJob) (EmailDeliveryResult, error) {
+	return resilience.Do(ctx, s.executor, func(ctx context.Context) (EmailDeliveryResult, error) {
+		if !s.Configured() {
+			return EmailDeliveryResult{}, errors.New("ses is not configured")
+		}
+		if s.api == nil {
+			return EmailDeliveryResult{}, errors.New("ses client is required")
+		}
+		job = job.Canonical()
+		if err := job.Validate(); err != nil {
+			return EmailDeliveryResult{}, err
+		}
+		input, err := s.buildSendInput(job)
+		if err != nil {
+			return EmailDeliveryResult{}, err
+		}
+
+		sendCtx := ctx
+		cancel := func() {}
+		if s.cfg.SendTimeout > 0 {
+			sendCtx, cancel = context.WithTimeout(ctx, s.cfg.SendTimeout)
+		}
+		defer cancel()
+
+		started := time.Now()
+		output, err := s.api.SendEmail(sendCtx, input)
+		metrics.ObserveAWSRequest(s.component, "ses", "SendEmail", err, started)
+		metrics.ObserveEmailSend(s.component, "ses", err, started)
+		if err != nil {
+			return EmailDeliveryResult{}, err
+		}
+
+		result := EmailDeliveryResult{
+			Provider:          "ses",
+			ProviderMessageID: awsv2.ToString(output.MessageId),
+		}
+		if requestID, ok := awsmiddleware.GetRequestIDMetadata(output.ResultMetadata); ok {
+			result.RequestID = requestID
+		}
+		return result, nil
+	})
+}
+
+func (s *SESSender) buildSendInput(job queue.EmailJob) (*sesv2.SendEmailInput, error) {
+	from, err := mail.ParseAddress(strings.TrimSpace(s.cfg.From))
+	if err != nil {
+		return nil, err
+	}
+	to, err := normalizeEmailAddresses([]string{job.To})
+	if err != nil {
+		return nil, err
+	}
+	cc, err := normalizeEmailAddresses(job.CC)
+	if err != nil {
+		return nil, err
+	}
+	bcc, err := normalizeEmailAddresses(job.BCC)
+	if err != nil {
+		return nil, err
+	}
+	replyTo, err := normalizeEmailAddresses(job.ReplyTo)
+	if err != nil {
+		return nil, err
+	}
+
+	input := &sesv2.SendEmailInput{
+		FromEmailAddress: awsv2.String(from.String()),
+		Destination: &sestypes.Destination{
+			ToAddresses:  to,
+			CcAddresses:  cc,
+			BccAddresses: bcc,
+		},
+		ReplyToAddresses: replyTo,
+		EmailTags:        buildSESTags(job.Tags),
+	}
+	if cfgSet := strings.TrimSpace(s.cfg.ConfigurationSetName); cfgSet != "" {
+		input.ConfigurationSetName = awsv2.String(cfgSet)
+	}
+
+	content, err := buildSESContent(from.String(), to, cc, replyTo, job)
+	if err != nil {
+		return nil, err
+	}
+	input.Content = content
+	return input, nil
+}
+
+func buildSESContent(from string, to, cc, replyTo []string, job queue.EmailJob) (*sestypes.EmailContent, error) {
+	if len(job.Attachments) > 0 {
+		return buildSESRawContent(from, to, cc, replyTo, job)
+	}
+	if strings.TrimSpace(job.TemplateName) != "" && strings.TrimSpace(job.TextBodyValue()) == "" && strings.TrimSpace(job.HTMLBody) == "" {
+		templateData := "{}"
+		if len(job.TemplateData) > 0 {
+			encoded, err := json.Marshal(job.TemplateData)
+			if err != nil {
+				return nil, err
+			}
+			templateData = string(encoded)
+		}
+		return &sestypes.EmailContent{
+			Template: &sestypes.Template{
+				TemplateName: awsv2.String(job.TemplateName),
+				TemplateData: awsv2.String(templateData),
+			},
+		}, nil
+	}
+
+	body := &sestypes.Body{}
+	if textBody := strings.TrimSpace(job.TextBodyValue()); textBody != "" {
+		body.Text = &sestypes.Content{
+			Data:    awsv2.String(textBody),
+			Charset: awsv2.String(utf8Charset),
+		}
+	}
+	if htmlBody := strings.TrimSpace(job.HTMLBody); htmlBody != "" {
+		body.Html = &sestypes.Content{
+			Data:    awsv2.String(htmlBody),
+			Charset: awsv2.String(utf8Charset),
+		}
+	}
+	return &sestypes.EmailContent{
+		Simple: &sestypes.Message{
+			Subject: &sestypes.Content{
+				Data:    awsv2.String(sanitizeSubject(job.Subject)),
+				Charset: awsv2.String(utf8Charset),
+			},
+			Body: body,
+		},
+	}, nil
+}
+
+func normalizeEmailAddresses(addresses []string) ([]string, error) {
+	if len(addresses) == 0 {
+		return nil, nil
+	}
+	out := make([]string, 0, len(addresses))
+	for _, address := range addresses {
+		address = strings.TrimSpace(address)
+		if address == "" {
+			continue
+		}
+		parsed, err := mail.ParseAddress(address)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, parsed.Address)
+	}
+	if len(out) == 0 {
+		return nil, nil
+	}
+	return out, nil
+}
+
+func buildSESTags(tags map[string]string) []sestypes.MessageTag {
+	if len(tags) == 0 {
+		return nil
+	}
+	keys := make([]string, 0, len(tags))
+	for key := range tags {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	out := make([]sestypes.MessageTag, 0, len(keys))
+	for _, key := range keys {
+		value := strings.TrimSpace(tags[key])
+		if strings.TrimSpace(key) == "" || value == "" {
+			continue
+		}
+		out = append(out, sestypes.MessageTag{
+			Name:  awsv2.String(strings.TrimSpace(key)),
+			Value: awsv2.String(value),
+		})
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func sanitizeSubject(subject string) string {
+	subject = strings.TrimSpace(subject)
+	subject = strings.ReplaceAll(subject, "\r", "")
+	subject = strings.ReplaceAll(subject, "\n", "")
+	return subject
+}
+
+func newSESAPI(ctx context.Context, cfg config.SESConfig) (sesAPI, error) {
+	if err := validateSESConfig(cfg); err != nil {
+		return nil, err
+	}
+	loadOptions := make([]func(*awsconfig.LoadOptions) error, 0, 1)
+	if strings.TrimSpace(cfg.Region) != "" {
+		loadOptions = append(loadOptions, awsconfig.WithRegion(strings.TrimSpace(cfg.Region)))
+	}
+	awsCfg, err := awsconfig.LoadDefaultConfig(ctx, loadOptions...)
+	if err != nil {
+		return nil, err
+	}
+	return sesv2.NewFromConfig(awsCfg, func(options *sesv2.Options) {
+		if endpoint := strings.TrimSpace(cfg.Endpoint); endpoint != "" {
+			options.EndpointResolver = sesv2.EndpointResolverFromURL(endpoint)
+		}
+	}), nil
+}
+
+func validateSESConfig(cfg config.SESConfig) error {
+	if strings.TrimSpace(cfg.Region) == "" {
+		return errors.New("aws region is required")
+	}
+	if strings.TrimSpace(cfg.From) == "" {
+		return errors.New("ses from address is required")
+	}
+	if endpoint := strings.TrimSpace(cfg.Endpoint); endpoint != "" {
+		parsed, err := url.Parse(endpoint)
+		if err != nil {
+			return err
+		}
+		if parsed.Scheme != "https" && !cfg.AllowInsecureEndpoint {
+			return errors.New("insecure ses endpoint is disabled")
+		}
+	}
+	return nil
+}
diff --git a/internal/service/ses_sender_test.go b/internal/service/ses_sender_test.go
new file mode 100644
index 0000000..21e655b
--- /dev/null
+++ b/internal/service/ses_sender_test.go
@@ -0,0 +1,240 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	awsmiddleware "github.com/aws/aws-sdk-go-v2/aws/middleware"
+	"github.com/aws/aws-sdk-go-v2/service/sesv2"
+	sestypes "github.com/aws/aws-sdk-go-v2/service/sesv2/types"
+	"github.com/aws/smithy-go"
+	smithymiddleware "github.com/aws/smithy-go/middleware"
+
+	"wucher/internal/config"
+	"wucher/internal/queue"
+)
+
+type mockSESAPI struct {
+	input  *sesv2.SendEmailInput
+	output *sesv2.SendEmailOutput
+	err    error
+	calls  int
+}
+
+func (m *mockSESAPI) SendEmail(_ context.Context, params *sesv2.SendEmailInput, _ ...func(*sesv2.Options)) (*sesv2.SendEmailOutput, error) {
+	m.calls++
+	m.input = params
+	if m.err != nil {
+		return nil, m.err
+	}
+	if m.output != nil {
+		return m.output, nil
+	}
+	return &sesv2.SendEmailOutput{}, nil
+}
+
+func TestSESSenderSendSimple(t *testing.T) {
+	metadata := smithymiddleware.Metadata{}
+	awsmiddleware.SetRequestIDMetadata(&metadata, "req-123")
+	api := &mockSESAPI{
+		output: &sesv2.SendEmailOutput{
+			MessageId:      strPtr("ses-msg-1"),
+			ResultMetadata: metadata,
+		},
+	}
+	sender := NewSESSenderWithAPI(config.SESConfig{
+		Region:               "ap-southeast-1",
+		From:                 "Wucher <no-reply@example.com>",
+		ConfigurationSetName: "auth-events",
+	}, api)
+
+	result, err := sender.Send(context.Background(), queue.EmailJob{
+		MessageType: "password_reset",
+		To:          "user@example.com",
+		CC:          []string{"cc@example.com"},
+		BCC:         []string{"bcc@example.com"},
+		ReplyTo:     []string{"reply@example.com"},
+		Subject:     "Reset Password",
+		TextBody:    "plain body",
+		HTMLBody:    "<p>html body</p>",
+		Tags: map[string]string{
+			"message_type": "password_reset",
+			"template":     "auth_password_reset",
+		},
+	})
+	if err != nil {
+		t.Fatalf("send: %v", err)
+	}
+	if result.Provider != "ses" || result.ProviderMessageID != "ses-msg-1" || result.RequestID != "req-123" {
+		t.Fatalf("unexpected result: %+v", result)
+	}
+	if api.calls != 1 || api.input == nil {
+		t.Fatalf("expected SES SendEmail to be called once")
+	}
+	if got := *api.input.ConfigurationSetName; got != "auth-events" {
+		t.Fatalf("unexpected configuration set: %q", got)
+	}
+	if got := *api.input.FromEmailAddress; got != "\"Wucher\" <no-reply@example.com>" {
+		t.Fatalf("unexpected from address: %q", got)
+	}
+	if got := api.input.Destination.ToAddresses; len(got) != 1 || got[0] != "user@example.com" {
+		t.Fatalf("unexpected to addresses: %#v", got)
+	}
+	if got := api.input.Destination.CcAddresses; len(got) != 1 || got[0] != "cc@example.com" {
+		t.Fatalf("unexpected cc addresses: %#v", got)
+	}
+	if got := api.input.Destination.BccAddresses; len(got) != 1 || got[0] != "bcc@example.com" {
+		t.Fatalf("unexpected bcc addresses: %#v", got)
+	}
+	if got := api.input.ReplyToAddresses; len(got) != 1 || got[0] != "reply@example.com" {
+		t.Fatalf("unexpected reply-to addresses: %#v", got)
+	}
+	if api.input.Content == nil || api.input.Content.Simple == nil {
+		t.Fatalf("expected simple SES content")
+	}
+	if got := *api.input.Content.Simple.Subject.Data; got != "Reset Password" {
+		t.Fatalf("unexpected subject: %q", got)
+	}
+	if got := *api.input.Content.Simple.Body.Text.Data; got != "plain body" {
+		t.Fatalf("unexpected text body: %q", got)
+	}
+	if got := *api.input.Content.Simple.Body.Html.Data; got != "<p>html body</p>" {
+		t.Fatalf("unexpected html body: %q", got)
+	}
+	if len(api.input.EmailTags) != 2 {
+		t.Fatalf("expected tags to be forwarded, got %#v", api.input.EmailTags)
+	}
+}
+
+func TestSESSenderSendTemplate(t *testing.T) {
+	api := &mockSESAPI{}
+	sender := NewSESSenderWithAPI(config.SESConfig{
+		Region: "ap-southeast-1",
+		From:   "no-reply@example.com",
+	}, api)
+
+	_, err := sender.Send(context.Background(), queue.EmailJob{
+		MessageType:  "invite_set_password",
+		To:           "user@example.com",
+		TemplateName: "auth.invite_set_password",
+		TemplateData: map[string]any{"name": "John"},
+	})
+	if err != nil {
+		t.Fatalf("send: %v", err)
+	}
+	if api.input == nil || api.input.Content == nil || api.input.Content.Template == nil {
+		t.Fatalf("expected templated SES content")
+	}
+	if got := *api.input.Content.Template.TemplateName; got != "auth.invite_set_password" {
+		t.Fatalf("unexpected template name: %q", got)
+	}
+	if got := *api.input.Content.Template.TemplateData; got != "{\"name\":\"John\"}" {
+		t.Fatalf("unexpected template data: %q", got)
+	}
+}
+
+func TestSESSenderSendInlineAttachmentUsesRawMIME(t *testing.T) {
+	api := &mockSESAPI{}
+	sender := NewSESSenderWithAPI(config.SESConfig{
+		Region: "ap-southeast-1",
+		From:   "no-reply@example.com",
+	}, api)
+
+	_, err := sender.Send(context.Background(), queue.EmailJob{
+		MessageType: "security_pin_reset",
+		To:          "user@example.com",
+		Subject:     "Reset Security PIN",
+		TextBody:    "plain body",
+		HTMLBody:    `<img src="cid:branding-email-logo"><p>html body</p>`,
+		Attachments: []queue.EmailAttachment{{
+			Filename:    "email-logo.png",
+			ContentType: "image/png",
+			ContentID:   "branding-email-logo",
+			Content:     []byte("png"),
+			Inline:      true,
+		}},
+	})
+	if err != nil {
+		t.Fatalf("send: %v", err)
+	}
+	if api.input == nil || api.input.Content == nil || api.input.Content.Raw == nil {
+		t.Fatalf("expected raw SES content")
+	}
+
+	raw := string(api.input.Content.Raw.Data)
+	if !strings.Contains(raw, `Content-ID: <branding-email-logo>`) {
+		t.Fatalf("expected inline content id in raw MIME: %q", raw)
+	}
+	if !strings.Contains(raw, `Content-Disposition: inline; filename="email-logo.png"`) {
+		t.Fatalf("expected inline content disposition in raw MIME: %q", raw)
+	}
+	if !strings.Contains(raw, `cid:branding-email-logo`) {
+		t.Fatalf("expected html body cid reference in raw MIME: %q", raw)
+	}
+}
+
+func TestSESSenderSendValidationError(t *testing.T) {
+	sender := NewSESSenderWithAPI(config.SESConfig{
+		Region: "ap-southeast-1",
+		From:   "no-reply@example.com",
+	}, &mockSESAPI{})
+
+	if _, err := sender.Send(context.Background(), queue.EmailJob{
+		To:       "not-an-email",
+		Subject:  "Hello",
+		TextBody: "Body",
+	}); err == nil {
+		t.Fatalf("expected invalid recipient error")
+	}
+
+	invalidCfgSender := NewSESSenderWithAPI(config.SESConfig{}, &mockSESAPI{})
+	if _, err := invalidCfgSender.Send(context.Background(), queue.EmailJob{
+		To:       "user@example.com",
+		Subject:  "Hello",
+		TextBody: "Body",
+	}); err == nil {
+		t.Fatalf("expected missing SES config error")
+	}
+}
+
+func TestClassifyDeliveryError(t *testing.T) {
+	t.Run("throttling is transient", func(t *testing.T) {
+		err := classifyDeliveryError(sesSenderAPIError{code: "TooManyRequestsException", fault: smithy.FaultClient})
+		if !queue.IsTransient(err) {
+			t.Fatalf("expected transient classification, got %v", err)
+		}
+	})
+
+	t.Run("message rejected is permanent", func(t *testing.T) {
+		err := classifyDeliveryError(sesSenderAPIError{code: "MessageRejected", fault: smithy.FaultClient})
+		if !queue.IsPermanent(err) {
+			t.Fatalf("expected permanent classification, got %v", err)
+		}
+	})
+
+	t.Run("validation error is permanent", func(t *testing.T) {
+		err := classifyDeliveryError(errors.New("invalid email job: recipient is required"))
+		if !queue.IsPermanent(err) {
+			t.Fatalf("expected permanent classification, got %v", err)
+		}
+	})
+}
+
+type sesSenderAPIError struct {
+	code  string
+	fault smithy.ErrorFault
+}
+
+func (e sesSenderAPIError) Error() string                 { return e.code }
+func (e sesSenderAPIError) ErrorCode() string             { return e.code }
+func (e sesSenderAPIError) ErrorMessage() string          { return e.code }
+func (e sesSenderAPIError) ErrorFault() smithy.ErrorFault { return e.fault }
+
+func strPtr(value string) *string {
+	return &value
+}
+
+var _ sesAPI = (*mockSESAPI)(nil)
+var _ = sestypes.MessageTag{}
diff --git a/internal/service/sort_helper.go b/internal/service/sort_helper.go
new file mode 100644
index 0000000..0f6e9f0
--- /dev/null
+++ b/internal/service/sort_helper.go
@@ -0,0 +1,50 @@
+package service
+
+import "strings"
+
+type sortRule struct {
+	keys []string
+	asc  string
+	desc string
+}
+
+func sortField(column string, keys ...string) sortRule {
+	if len(keys) == 0 {
+		keys = []string{column}
+	}
+	return sortRule{
+		keys: keys,
+		asc:  column + " ASC",
+		desc: column + " DESC",
+	}
+}
+
+func sortExpr(asc, desc string, keys ...string) sortRule {
+	return sortRule{
+		keys: keys,
+		asc:  asc,
+		desc: desc,
+	}
+}
+
+func normalizeSortByRules(sort string, rules ...sortRule) string {
+	for _, rule := range rules {
+		for _, key := range rule.keys {
+			key = strings.TrimSpace(key)
+			if key == "" {
+				continue
+			}
+			if sort == key {
+				return rule.asc
+			}
+			if sort == "-"+key {
+				return rule.desc
+			}
+		}
+	}
+	return ""
+}
+
+func joinSortClauses(clauses []string) string {
+	return strings.Join(clauses, ", ")
+}
diff --git a/internal/service/sort_helper_test.go b/internal/service/sort_helper_test.go
new file mode 100644
index 0000000..4f45de3
--- /dev/null
+++ b/internal/service/sort_helper_test.go
@@ -0,0 +1,31 @@
+package service
+
+import "testing"
+
+func TestNormalizeSortByRules(t *testing.T) {
+	t.Run("field asc and desc", func(t *testing.T) {
+		if got := normalizeSortByRules("name", sortField("name")); got != "name ASC" {
+			t.Fatalf("unexpected asc sort: %q", got)
+		}
+		if got := normalizeSortByRules("-name", sortField("name")); got != "name DESC" {
+			t.Fatalf("unexpected desc sort: %q", got)
+		}
+	})
+
+	t.Run("alias and custom expression", func(t *testing.T) {
+		got := normalizeSortByRules("sort_order", sortExpr("sort_order ASC, created_at DESC", "sort_order DESC, created_at DESC", "sort_order"))
+		if got != "sort_order ASC, created_at DESC" {
+			t.Fatalf("unexpected custom sort: %q", got)
+		}
+		got = normalizeSortByRules("-hospital_name", sortField("hospital_name", "name", "hospital_name"))
+		if got != "hospital_name DESC" {
+			t.Fatalf("unexpected alias sort: %q", got)
+		}
+	})
+
+	t.Run("unknown", func(t *testing.T) {
+		if got := normalizeSortByRules("unknown", sortField("name")); got != "" {
+			t.Fatalf("expected empty for unknown, got %q", got)
+		}
+	})
+}
diff --git a/internal/service/takeover_module_service.go b/internal/service/takeover_module_service.go
new file mode 100644
index 0000000..b805362
--- /dev/null
+++ b/internal/service/takeover_module_service.go
@@ -0,0 +1,35 @@
+package service
+
+import (
+	"context"
+
+	takeover "wucher/internal/domain/takeover"
+)
+
+type TakeoverModuleService struct {
+	repo takeover.Repository
+}
+
+func NewTakeoverModuleService(repo takeover.Repository) *TakeoverModuleService {
+	return &TakeoverModuleService{repo: repo}
+}
+
+func (s *TakeoverModuleService) Create(ctx context.Context, row *takeover.TakeoverAc) error {
+	return s.repo.Create(ctx, row)
+}
+
+func (s *TakeoverModuleService) Update(ctx context.Context, row *takeover.TakeoverAc) error {
+	return s.repo.Update(ctx, row)
+}
+
+func (s *TakeoverModuleService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *TakeoverModuleService) GetByID(ctx context.Context, id []byte) (*takeover.TakeoverAc, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *TakeoverModuleService) List(ctx context.Context, limit, offset int) ([]takeover.TakeoverAc, int64, error) {
+	return s.repo.List(ctx, limit, offset)
+}
diff --git a/internal/service/takeover_service.go b/internal/service/takeover_service.go
new file mode 100644
index 0000000..bb5ae3f
--- /dev/null
+++ b/internal/service/takeover_service.go
@@ -0,0 +1,1647 @@
+package service
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	basedomain "wucher/internal/domain/base"
+	beforeflightinspection "wucher/internal/domain/before_flight_inspection"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/flight"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	flightinspectionfilechecklist "wucher/internal/domain/flight_inspection_file_checklist"
+	flightprepcheck "wucher/internal/domain/flight_prep_check"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	otherpersondomain "wucher/internal/domain/other_person"
+	reserveac "wucher/internal/domain/reserve_ac"
+	takeoverdomain "wucher/internal/domain/takeover"
+	"wucher/internal/shared/pkg/missioncode"
+	"wucher/internal/shared/pkg/reserveacutil"
+	"wucher/internal/shared/pkg/util"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+)
+
+// checklistTemplateFileRepository loads the helicopter files that make up an inspection
+// checklist section. The concrete implementation (mysql.TakeoverRepository) is injected so
+// the service does not depend on the repository package directly. The transaction handle is
+// passed through so the read runs within the caller's ongoing transaction.
+type checklistTemplateFileRepository interface {
+	ListChecklistTemplateFiles(tx *gorm.DB, helicopterID []byte, section string) ([]helicopterfile.HelicopterFile, error)
+	ListActiveEditedTemplateUUIDs(tx *gorm.DB, takeoverID []byte) ([][]byte, error)
+}
+
+type TakeoverService struct {
+	db             *gorm.DB
+	checklistFiles checklistTemplateFileRepository
+}
+
+type TakeoverCreateInput struct {
+	BaseID          []byte
+	HasBaseID       bool
+	DutyDate        time.Time
+	HasDutyDate     bool
+	Notes           *string
+	RosterDetail    *requestdto.DutyRosterDetailsInput
+	HasRosterDetail bool
+	HelicopterID    []byte
+	HasHelicopterID bool
+	Inspection      *requestdto.ReserveAcInspectionCreateAttributes
+	HasInspection   bool
+	ActorUserID     []byte
+}
+
+type TakeoverCreateResult struct {
+	TakeoverAcID       []byte
+	DutyRosterID       []byte
+	FlightID           []byte
+	ReserveAcID        []byte
+	FlightInspectionID []byte
+	ShiftStart         string
+	ShiftEnd           string
+}
+
+type takeoverExisting struct {
+	Flight   *flight.Flight
+	Takeover *takeoverdomain.TakeoverAc
+	Reserve  *reserveac.ReserveAc
+	Crews    []takeoverdomain.TakeoverRosterCrew
+	Others   []takeoverdomain.TakeoverOtherPerson
+	Before   *beforeflightinspection.BeforeFlightInspection
+	Prep     *flightprepcheck.FlightPrepCheck
+}
+
+func NewTakeoverService(db *gorm.DB) *TakeoverService {
+	return &TakeoverService{db: db}
+}
+
+// WithChecklistTemplateRepository injects the repository used to load checklist template
+// files. It must be wired at startup so DB access stays in the repository layer.
+func (s *TakeoverService) WithChecklistTemplateRepository(repo checklistTemplateFileRepository) *TakeoverService {
+	if s != nil {
+		s.checklistFiles = repo
+	}
+	return s
+}
+
+func logTakeoverServiceStepError(step string, err error) {
+	if err == nil {
+		return
+	}
+	slog.Error("takeover service step failed",
+		"step", step,
+		"error", err.Error(),
+		"error_type", fmt.Sprintf("%T", err),
+	)
+}
+
+func (s *TakeoverService) Create(ctx context.Context, in TakeoverCreateInput) (*TakeoverCreateResult, error) {
+	if s == nil || s.db == nil {
+		return nil, errors.New("takeover service is not configured")
+	}
+	if !in.HasDutyDate {
+		return nil, errors.New("duty_date is required")
+	}
+	if in.HasBaseID && len(in.BaseID) != 16 {
+		return nil, errors.New("base_id must be a valid UUID")
+	}
+	if in.HasHelicopterID && len(in.HelicopterID) != 16 {
+		return nil, errors.New("helicopter_id must be a valid UUID")
+	}
+	if !in.HasBaseID && !in.HasRosterDetail {
+		return nil, errors.New("base_id or roster_detail is required")
+	}
+
+	return s.createInTx(ctx, in)
+}
+
+func (s *TakeoverService) createInTx(ctx context.Context, in TakeoverCreateInput) (*TakeoverCreateResult, error) {
+	result := &TakeoverCreateResult{}
+	err := s.withRetryTx(ctx, func(tx *gorm.DB) error {
+		if in.HasHelicopterID {
+			booked, err := isHelicopterBookedTx(tx, in.HelicopterID, nil)
+			if err != nil {
+				return err
+			}
+			if booked {
+				return errors.New("helicopter is already booked")
+			}
+		}
+
+		takeoverAc := &takeoverdomain.TakeoverAc{
+			Notes:     in.Notes,
+			CreatedBy: in.ActorUserID,
+			UpdatedBy: in.ActorUserID,
+		}
+		if in.HasBaseID {
+			shiftStart, shiftEnd, err := ResolveBaseShiftRangeTx(tx, in.BaseID, in.DutyDate)
+			if err != nil {
+				return err
+			}
+			result.ShiftStart = shiftStart
+			result.ShiftEnd = shiftEnd
+			if err := ensureBaseExistsTx(tx, in.BaseID); err != nil {
+				return err
+			}
+			takeoverAc.BaseID = append([]byte(nil), in.BaseID...)
+		}
+		if err := tx.Create(takeoverAc).Error; err != nil {
+			return err
+		}
+		result.TakeoverAcID = append([]byte(nil), takeoverAc.ID...)
+
+		if in.HasRosterDetail {
+			if err := s.upsertTakeoverRosterRowsTx(tx, takeoverAc.ID, in); err != nil {
+				return err
+			}
+		}
+
+		existing := &takeoverExisting{}
+		if err := s.upsertTakeoverReserveTx(tx, takeoverAc.ID, in.BaseID, existing, in); err != nil {
+			return err
+		}
+
+		now := time.Now().UTC()
+		prefix := missioncode.BuildPrefix(now)
+		latest, err := getLatestMissionCodeByPrefixTx(tx, prefix)
+		if err != nil {
+			return err
+		}
+		nextCode := missioncode.NextFromLatest(prefix, latest)
+		flightRow := &flight.Flight{
+			Status:       "draft",
+			MissionCode:  &nextCode,
+			Date:         dateOnlyUTC(in.DutyDate),
+			TakeoverAcID: append([]byte(nil), takeoverAc.ID...),
+			CreatedBy:    in.ActorUserID,
+			UpdatedBy:    in.ActorUserID,
+		}
+		if err := tx.Create(flightRow).Error; err != nil {
+			return err
+		}
+		result.FlightID = append([]byte(nil), flightRow.ID...)
+		if existing.Reserve != nil {
+			result.ReserveAcID = append([]byte(nil), existing.Reserve.ID...)
+			result.FlightInspectionID = append([]byte(nil), existing.Reserve.InspectionID...)
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return result, nil
+}
+
+func (s *TakeoverService) Replace(ctx context.Context, existingFlightID []byte, in TakeoverCreateInput) (*TakeoverCreateResult, error) {
+	if len(existingFlightID) != 16 {
+		return nil, errors.New("id is invalid UUID")
+	}
+	result := &TakeoverCreateResult{}
+	err := s.withRetryTx(ctx, func(tx *gorm.DB) error {
+		existing, err := loadTakeoverExistingTx(tx, existingFlightID)
+		if err != nil {
+			logTakeoverServiceStepError("Replace.loadTakeoverExistingTx", err)
+			return err
+		}
+		if existing == nil || existing.Flight == nil {
+			return gorm.ErrRecordNotFound
+		}
+
+		targetBaseID := []byte(nil)
+		if existing.Reserve != nil && len(existing.Reserve.BaseID) > 0 {
+			targetBaseID = append([]byte(nil), existing.Reserve.BaseID...)
+		} else if existing.Takeover != nil && len(existing.Takeover.BaseID) > 0 {
+			targetBaseID = append([]byte(nil), existing.Takeover.BaseID...)
+		}
+		if in.HasBaseID {
+			if len(in.BaseID) != 16 {
+				return errors.New("base_id must be a valid UUID")
+			}
+			if err := ensureBaseExistsTx(tx, in.BaseID); err != nil {
+				logTakeoverServiceStepError("Replace.ensureBaseExistsTx", err)
+				return err
+			}
+			targetBaseID = append([]byte(nil), in.BaseID...)
+		}
+
+		effectiveDutyDate := existing.Flight.Date
+		if in.HasDutyDate {
+			effectiveDutyDate = dateOnlyUTC(in.DutyDate)
+		}
+		if len(targetBaseID) > 0 {
+			shiftStart, shiftEnd, err := ResolveBaseShiftRangeTx(tx, targetBaseID, effectiveDutyDate)
+			if err != nil {
+				logTakeoverServiceStepError("Replace.ResolveBaseShiftRangeTx", err)
+				return err
+			}
+			result.ShiftStart = shiftStart
+			result.ShiftEnd = shiftEnd
+		}
+
+		takeoverID := existing.Flight.TakeoverAcID
+		if len(takeoverID) != 16 {
+			return gorm.ErrRecordNotFound
+		}
+
+		currentHelicopterID := []byte(nil)
+		if existing.Reserve != nil && len(existing.Reserve.AircraftID) == 16 {
+			currentHelicopterID = append([]byte(nil), existing.Reserve.AircraftID...)
+		}
+		if in.HasHelicopterID && len(in.HelicopterID) == 16 && !bytes.Equal(in.HelicopterID, currentHelicopterID) {
+			booked, err := isHelicopterBookedTx(tx, in.HelicopterID, takeoverID)
+			if err != nil {
+				logTakeoverServiceStepError("Replace.isHelicopterBookedTx", err)
+				return err
+			}
+			if booked {
+				return errors.New("helicopter is already booked")
+			}
+		}
+
+		takeoverUpdates := map[string]any{"base_id": targetBaseID, "updated_by": in.ActorUserID}
+		if in.Notes != nil {
+			takeoverUpdates["notes"] = *in.Notes
+		}
+		if err := tx.Model(&takeoverdomain.TakeoverAc{}).
+			Where("id = ? AND deleted_at IS NULL", takeoverID).
+			Updates(takeoverUpdates).Error; err != nil {
+			logTakeoverServiceStepError("Replace.updateTakeover", err)
+			return err
+		}
+
+		if err := s.upsertTakeoverReserveTx(tx, takeoverID, targetBaseID, existing, in); err != nil {
+			logTakeoverServiceStepError("Replace.upsertTakeoverReserveTx", err)
+			return err
+		}
+
+		targetFlightDate := dateOnlyUTC(in.DutyDate)
+		if in.HasDutyDate && !existing.Flight.Date.Equal(targetFlightDate) {
+			existing.Flight.Date = targetFlightDate
+			if err := tx.Save(existing.Flight).Error; err != nil {
+				logTakeoverServiceStepError("Replace.saveFlightDate", err)
+				return err
+			}
+		}
+
+		if in.HasRosterDetail {
+			if err := s.upsertTakeoverRosterRowsTx(tx, takeoverID, in); err != nil {
+				logTakeoverServiceStepError("Replace.upsertTakeoverRosterRowsTx", err)
+				return err
+			}
+		}
+
+		if existing.Reserve != nil {
+			result.ReserveAcID = append([]byte(nil), existing.Reserve.ID...)
+			result.FlightInspectionID = append([]byte(nil), existing.Reserve.InspectionID...)
+		}
+		result.TakeoverAcID = append([]byte(nil), takeoverID...)
+		result.FlightID = append([]byte(nil), existing.Flight.ID...)
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return result, nil
+}
+
+func (s *TakeoverService) GetByID(ctx context.Context, id []byte) (*takeoverdomain.TakeoverAc, error) {
+	if s == nil || s.db == nil {
+		return nil, errors.New("takeover service is not configured")
+	}
+	if len(id) != 16 {
+		return nil, errors.New("id is invalid UUID")
+	}
+	var row takeoverdomain.TakeoverAc
+	err := s.db.WithContext(ctx).
+		Preload("Base").
+		Preload("ReserveAc").
+		Preload("ReserveAc.Aircraft").
+		Preload("ReserveAc.Inspection").
+		Preload("RosterCrews").
+		Preload("RosterCrews.User").
+		Preload("OtherPeople").
+		Preload("Files").
+		Preload("Files.FileAttachment").
+		Preload("Files.FileAttachment.File").
+		Where("id = ? AND deleted_at IS NULL", id).
+		First(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &row, err
+}
+
+func (s *TakeoverService) List(ctx context.Context, limit, offset int) ([]takeoverdomain.TakeoverAc, int64, error) {
+	if s == nil || s.db == nil {
+		return nil, 0, errors.New("takeover service is not configured")
+	}
+	rows := make([]takeoverdomain.TakeoverAc, 0)
+	var total int64
+	base := s.db.WithContext(ctx).
+		Model(&takeoverdomain.TakeoverAc{}).
+		Preload("Base").
+		Preload("ReserveAc").
+		Preload("ReserveAc.Aircraft").
+		Preload("ReserveAc.Inspection").
+		Preload("RosterCrews").
+		Preload("OtherPeople").
+		Preload("Files").
+		Preload("Files.FileAttachment").
+		Preload("Files.FileAttachment.File").
+		Where("deleted_at IS NULL")
+	if err := base.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+	q := base.Order("created_at DESC")
+	if limit > 0 {
+		q = q.Limit(limit).Offset(offset)
+	}
+	if err := q.Find(&rows).Error; err != nil {
+		return nil, 0, err
+	}
+	return rows, total, nil
+}
+
+func (s *TakeoverService) AttachFile(ctx context.Context, takeoverID []byte, fileAttachmentID []byte) error {
+	if s == nil || s.db == nil {
+		return errors.New("takeover service is not configured")
+	}
+	if len(takeoverID) != 16 {
+		return errors.New("takeover_id must be a valid UUID")
+	}
+	if len(fileAttachmentID) != 16 {
+		return errors.New("file_attachment_id must be a valid UUID")
+	}
+
+	return s.withRetryTx(ctx, func(tx *gorm.DB) error {
+		return attachTakeoverFilesTx(tx, takeoverID, [][]byte{fileAttachmentID})
+	})
+}
+
+func (s *TakeoverService) DetachFile(ctx context.Context, takeoverID []byte, fileAttachmentID []byte) error {
+	if s == nil || s.db == nil {
+		return errors.New("takeover service is not configured")
+	}
+	if len(takeoverID) != 16 {
+		return errors.New("takeover_id must be a valid UUID")
+	}
+	if len(fileAttachmentID) != 16 {
+		return errors.New("file_attachment_id must be a valid UUID")
+	}
+
+	return s.withRetryTx(ctx, func(tx *gorm.DB) error {
+		var takeoverRow takeoverdomain.TakeoverAc
+		if err := tx.Where("id = ? AND deleted_at IS NULL", takeoverID).Take(&takeoverRow).Error; err != nil {
+			return err
+		}
+		res := tx.Where("takeover_id = ? AND file_attachment_id = ?", takeoverID, fileAttachmentID).Delete(&takeoverdomain.TakeoverFile{})
+		if res.Error != nil {
+			return res.Error
+		}
+		if res.RowsAffected == 0 {
+			return gorm.ErrRecordNotFound
+		}
+		return nil
+	})
+}
+
+func attachTakeoverFilesTx(tx *gorm.DB, takeoverID []byte, fileAttachmentIDs [][]byte) error {
+	if len(takeoverID) != 16 {
+		return errors.New("takeover_id must be a valid UUID")
+	}
+	var takeoverRow takeoverdomain.TakeoverAc
+	if err := tx.Where("id = ? AND deleted_at IS NULL", takeoverID).Take(&takeoverRow).Error; err != nil {
+		return err
+	}
+	for i := range fileAttachmentIDs {
+		fileAttachmentID := fileAttachmentIDs[i]
+		if len(fileAttachmentID) != 16 {
+			return errors.New("file_attachment_id must be a valid UUID")
+		}
+		var attachment filemanager.Attachment
+		if err := tx.Where("id = ?", fileAttachmentID).Take(&attachment).Error; err != nil {
+			return err
+		}
+		var existing takeoverdomain.TakeoverFile
+		err := tx.Where("takeover_id = ? AND file_attachment_id = ?", takeoverID, fileAttachmentID).Take(&existing).Error
+		if err == nil {
+			continue
+		}
+		if !errors.Is(err, gorm.ErrRecordNotFound) {
+			return err
+		}
+		row := &takeoverdomain.TakeoverFile{
+			TakeoverID:       append([]byte(nil), takeoverID...),
+			FileAttachmentID: append([]byte(nil), fileAttachmentID...),
+		}
+		if err := tx.Create(row).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (s *TakeoverService) withRetryTx(ctx context.Context, fn func(tx *gorm.DB) error) error {
+	const maxAttempts = 2
+	var lastErr error
+	for attempt := 1; attempt <= maxAttempts; attempt++ {
+		lastErr = s.db.WithContext(ctx).Transaction(fn)
+		if lastErr == nil {
+			return nil
+		}
+		if !isRetryableDBErr(lastErr) || attempt == maxAttempts {
+			return lastErr
+		}
+	}
+	return lastErr
+}
+
+func isRetryableDBErr(err error) bool {
+	if err == nil {
+		return false
+	}
+	msg := strings.ToLower(err.Error())
+	return strings.Contains(msg, "bad connection") ||
+		strings.Contains(msg, "invalid connection") ||
+		strings.Contains(msg, "connection refused") ||
+		strings.Contains(msg, "broken pipe") ||
+		strings.Contains(msg, "driver: bad connection")
+}
+
+func loadTakeoverExistingTx(tx *gorm.DB, flightID []byte) (*takeoverExisting, error) {
+	var fl flight.Flight
+	if err := tx.Where("id = ? AND deleted_at IS NULL", flightID).Take(&fl).Error; err != nil {
+		return nil, err
+	}
+	var takeoverRow takeoverdomain.TakeoverAc
+	if err := tx.Where("id = ? AND deleted_at IS NULL", fl.TakeoverAcID).Take(&takeoverRow).Error; err != nil {
+		return nil, err
+	}
+	crews, err := loadTakeoverRosterCrewsTx(tx, takeoverRow.ID)
+	if err != nil {
+		return nil, err
+	}
+	others, err := loadTakeoverOtherPeopleTx(tx, takeoverRow.ID)
+	if err != nil {
+		return nil, err
+	}
+	var reserve *reserveac.ReserveAc
+	if len(takeoverRow.ReserveAcID) == 16 {
+		var reserveRow reserveac.ReserveAc
+		if err := tx.Where("id = ? AND deleted_at IS NULL", takeoverRow.ReserveAcID).Take(&reserveRow).Error; err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, err
+		} else if err == nil {
+			reserve = &reserveRow
+		}
+	}
+	var beforeRow *beforeflightinspection.BeforeFlightInspection
+	var prepRow *flightprepcheck.FlightPrepCheck
+	if reserve != nil && len(reserve.InspectionID) == 16 {
+		var before beforeflightinspection.BeforeFlightInspection
+		if err := tx.Where("flight_inspection_id = ?", reserve.InspectionID).Take(&before).Error; err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, err
+		} else if err == nil {
+			beforeRow = &before
+		}
+		var prep flightprepcheck.FlightPrepCheck
+		if err := tx.Where("flight_inspection_id = ?", reserve.InspectionID).Take(&prep).Error; err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, err
+		} else if err == nil {
+			prepRow = &prep
+		}
+	}
+	return &takeoverExisting{Flight: &fl, Takeover: &takeoverRow, Reserve: reserve, Crews: crews, Others: others, Before: beforeRow, Prep: prepRow}, nil
+}
+
+func dutyDateTimeString(dutyDate time.Time, clock string) string {
+	trimmed := strings.TrimSpace(clock)
+	if len(trimmed) == 5 {
+		trimmed += ":00"
+	}
+	return dutyDate.UTC().Format("2006-01-02") + " " + trimmed
+}
+
+func ensureBaseExistsTx(tx *gorm.DB, id []byte) error {
+	var count int64
+	if err := tx.Table("bases").Where("id = ? AND deleted_at IS NULL", id).Count(&count).Error; err != nil {
+		return err
+	}
+	if count == 0 {
+		return errors.New("base_id does not exist")
+	}
+	return nil
+}
+
+func ensureHelicopterExistsTx(tx *gorm.DB, id []byte) error {
+	var count int64
+	if err := tx.Table("helicopters").Where("id = ?", id).Count(&count).Error; err != nil {
+		return err
+	}
+	if count == 0 {
+		return errors.New("helicopter_id does not exist")
+	}
+	return nil
+}
+
+func ResolveBaseShiftRangeTx(tx *gorm.DB, baseID []byte, dutyDate time.Time) (string, string, error) {
+	if len(baseID) != 16 {
+		return "", "", errors.New("base_id does not exist")
+	}
+	var baseRow basedomain.Base
+	err := tx.Preload("OperationalShiftTimes", func(db *gorm.DB) *gorm.DB {
+		return db.Where("deleted_at IS NULL").Order("date_start ASC, date_end ASC")
+	}).
+		Where("id = ? AND deleted_at IS NULL", baseID).
+		First(&baseRow).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return "", "", errors.New("base_id does not exist")
+	}
+	if err != nil {
+		return "", "", err
+	}
+	return util.ResolveShiftWindow(&baseRow, dutyDate)
+}
+
+func isHelicopterBookedTx(tx *gorm.DB, helicopterID []byte, excludeTakeoverID []byte) (bool, error) {
+	if len(helicopterID) != 16 {
+		return false, nil
+	}
+	q := tx.Table("reserve_acs ra").
+		Joins("JOIN takeover_acs ta ON ta.reserve_ac_id = ra.id AND ta.deleted_at IS NULL").
+		Joins("JOIN flights f ON f.takeover_ac_id = ta.id").
+		Joins("LEFT JOIN after_flight_inspections afi ON afi.flight_inspection_id = ra.inspection_id").
+		Where("ra.helicopter_id = ? AND ra.deleted_at IS NULL AND f.deleted_at IS NULL AND afi.id IS NULL", helicopterID)
+	if len(excludeTakeoverID) == 16 {
+		q = q.Where("ta.id <> ?", excludeTakeoverID)
+	}
+	var total int64
+	if err := q.Count(&total).Error; err != nil {
+		return false, err
+	}
+	return total > 0, nil
+}
+
+func ensureUserExistsTx(tx *gorm.DB, id []byte) error {
+	var count int64
+	if err := tx.Table("users").Where("id = ?", id).Count(&count).Error; err != nil {
+		return err
+	}
+	if count == 0 {
+		return errors.New("one or more crew contact ids do not exist")
+	}
+	return nil
+}
+
+func (s *TakeoverService) upsertTakeoverChecklistItemsTx(tx *gorm.DB, inspectionID, helicopterID []byte, section string, items []requestdto.ReserveAcFileChecklistItem, actor []byte) error {
+	if s == nil || s.checklistFiles == nil {
+		return errors.New("checklist template repository is not configured")
+	}
+	templateFiles, err := s.checklistFiles.ListChecklistTemplateFiles(tx, helicopterID, section)
+	if err != nil {
+		return err
+	}
+	if len(templateFiles) == 0 {
+		if len(items) == 0 {
+			return nil
+		}
+		return fmt.Errorf("inspection checklist template is empty for section %s", section)
+	}
+	if len(items) == 0 {
+		return fmt.Errorf("%s is required", takeoverChecklistSectionLabel(section))
+	}
+
+	payloadByFileID := make(map[string]bool, len(items))
+	for i := range items {
+		if len(items[i].HelicopterFileID) == 0 {
+			return errors.New("helicopter_file_id is required")
+		}
+		hfID := strings.TrimSpace(items[i].HelicopterFileID)
+		parsedHFID, err := uuidv7.ParseString(hfID)
+		if err != nil {
+			return errors.New("invalid helicopter_file_id")
+		}
+		fileKey := string(parsedHFID)
+		if _, exists := payloadByFileID[fileKey]; exists {
+			return fmt.Errorf("duplicate helicopter_file_id in %s", takeoverChecklistSectionLabel(section))
+		}
+		payloadByFileID[fileKey] = items[i].IsDone
+	}
+
+	templateSet := make(map[string]struct{}, len(templateFiles))
+	for i := range templateFiles {
+		templateSet[string(templateFiles[i].ID)] = struct{}{}
+	}
+
+	for fileKey := range payloadByFileID {
+		if _, ok := templateSet[fileKey]; ok {
+			continue
+		}
+		return fmt.Errorf("helicopter_file_id does not belong to selected helicopter/section")
+	}
+
+	for i := range templateFiles {
+		fileKey := string(templateFiles[i].ID)
+		isDone, ok := payloadByFileID[fileKey]
+		if !ok {
+			// Only the files the user actually submitted are recorded. A catalog
+			// file that was not edited need not be included in the checklist
+			// (even if it is mandatory) — validateTakeoverEditedTemplateFilesTx
+			// separately guarantees every edited file IS included.
+			continue
+		}
+		if templateFiles[i].IsMandatory && !isDone {
+			return fmt.Errorf("%s must be fully checked", takeoverChecklistSectionLabel(section))
+		}
+		row := &flightinspectionfilechecklist.FlightInspectionFileChecklist{
+			HelicopterFileID:   templateFiles[i].ID,
+			FlightInspectionID: inspectionID,
+			IsDone:             isDone,
+			CreatedBy:          actor,
+			UpdatedBy:          actor,
+		}
+		if err := tx.Clauses(clause.OnConflict{
+			Columns:   []clause.Column{{Name: "flight_inspection_id"}, {Name: "helicopter_file_id"}},
+			DoUpdates: clause.AssignmentColumns([]string{"is_done", "updated_by"}),
+		}).Create(row).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// validateTakeoverEditedTemplateFilesTx enforces that every file that was
+// created/edited from an FPWB template for this takeover is included in the
+// submitted flight-preparation file checklist. A file that was not edited does
+// not need to be in the checklist.
+//
+// New data stores template_uuid == HelicopterFile.ID. Legacy data may instead
+// store the underlying source file ID. We accept both by resolving active FPWB
+// checklist templates to a canonical helicopter_file_id before validating.
+// Orphaned historical references that no longer map to an active checklist
+// template are ignored so stale data cannot block takeover updates forever.
+func (s *TakeoverService) validateTakeoverEditedTemplateFilesTx(tx *gorm.DB, takeoverID, helicopterID []byte, items []requestdto.ReserveAcFileChecklistItem) error {
+	if len(takeoverID) != 16 {
+		return nil
+	}
+	if s == nil || s.checklistFiles == nil {
+		return errors.New("checklist template repository is not configured")
+	}
+	editedTemplateUUIDs, err := s.checklistFiles.ListActiveEditedTemplateUUIDs(tx, takeoverID)
+	if err != nil {
+		return err
+	}
+	if len(editedTemplateUUIDs) == 0 {
+		return nil
+	}
+
+	templateFiles, err := s.checklistFiles.ListChecklistTemplateFiles(tx, helicopterID, helicopterfile.SectionFlightPreparationAndWB)
+	if err != nil {
+		return err
+	}
+	templateReferenceToChecklistID := make(map[string]string, len(templateFiles)*3)
+	for i := range templateFiles {
+		if len(templateFiles[i].ID) == 16 {
+			canonicalID := string(templateFiles[i].ID)
+			templateReferenceToChecklistID[canonicalID] = canonicalID
+			if len(templateFiles[i].SourceFileID) == 16 {
+				templateReferenceToChecklistID[string(templateFiles[i].SourceFileID)] = canonicalID
+			}
+			if templateFiles[i].SourceFile != nil && len(templateFiles[i].SourceFile.ID) == 16 {
+				templateReferenceToChecklistID[string(templateFiles[i].SourceFile.ID)] = canonicalID
+			}
+			if templateFiles[i].FileAttachment != nil && templateFiles[i].FileAttachment.File != nil && len(templateFiles[i].FileAttachment.File.ID) == 16 {
+				templateReferenceToChecklistID[string(templateFiles[i].FileAttachment.File.ID)] = canonicalID
+			}
+		}
+	}
+
+	checklistSet := make(map[string]struct{}, len(items))
+	for i := range items {
+		hfID := strings.TrimSpace(items[i].HelicopterFileID)
+		if hfID == "" {
+			continue
+		}
+		parsedHFID, err := uuidv7.ParseString(hfID)
+		if err != nil {
+			return errors.New("invalid helicopter_file_id")
+		}
+		checklistSet[string(parsedHFID)] = struct{}{}
+	}
+
+	for i := range editedTemplateUUIDs {
+		if len(editedTemplateUUIDs[i]) != 16 {
+			continue
+		}
+		requiredChecklistID, ok := templateReferenceToChecklistID[string(editedTemplateUUIDs[i])]
+		if !ok {
+			continue
+		}
+		if _, ok := checklistSet[requiredChecklistID]; !ok {
+			return fmt.Errorf("edited template file must be included in the flight preparation file checklist")
+		}
+	}
+	return nil
+}
+
+func takeoverChecklistSectionLabel(section string) string {
+	switch section {
+	case helicopterfile.SectionBeforeFirstFlightInspection:
+		return "inspection.before.file_checklist"
+	case helicopterfile.SectionFlightPreparationAndWB:
+		return "inspection.prepare.file_checklist"
+	default:
+		return fmt.Sprintf("inspection.%s.file_checklist", section)
+	}
+}
+
+// resolveOtherPeopleMasterInputTx fills each id-referenced other-person's name/phone/email
+// from the master (a snapshot), so an id-only reuse still passes the "name required"
+// validation and later upserts to the same master.
+func resolveOtherPeopleMasterInputTx(tx *gorm.DB, detail *requestdto.DutyRosterDetailsInput) error {
+	if detail == nil {
+		return nil
+	}
+	for i := range detail.OtherPerson {
+		idStr := strings.TrimSpace(detail.OtherPerson[i].OtherPersonID)
+		if idStr == "" {
+			continue
+		}
+		id, err := uuidv7.ParseString(idStr)
+		if err != nil {
+			return errors.New("other_person_id is invalid UUID")
+		}
+		var master otherpersondomain.OtherPerson
+		if err := tx.Where("id = ? AND deleted_at IS NULL", id).First(&master).Error; err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return errors.New("other_person_id not found")
+			}
+			return err
+		}
+		detail.OtherPerson[i].Name = master.Name
+		detail.OtherPerson[i].MobilePhone = master.MobilePhone
+		detail.OtherPerson[i].Email = master.Email
+	}
+	return nil
+}
+
+// upsertOtherPersonTx returns the canonical master person for (name, mobile_phone, email),
+// creating it when absent. On return p.ID is the canonical id.
+func upsertOtherPersonTx(tx *gorm.DB, p *otherpersondomain.OtherPerson) error {
+	name := strings.TrimSpace(p.Name)
+	phone := strings.TrimSpace(p.MobilePhone)
+	email := strings.TrimSpace(p.Email)
+	if name == "" {
+		return nil
+	}
+	var existing otherpersondomain.OtherPerson
+	err := tx.Where("name = ? AND mobile_phone = ? AND email = ? AND deleted_at IS NULL", name, phone, email).First(&existing).Error
+	if err == nil {
+		p.ID = existing.ID
+		return nil
+	}
+	if !errors.Is(err, gorm.ErrRecordNotFound) {
+		return err
+	}
+	p.Name, p.MobilePhone, p.Email = name, phone, email
+	return tx.Create(p).Error
+}
+
+func buildTakeoverCrewRows(details *requestdto.DutyRosterDetailsInput, actor []byte) ([]takeoverdomain.TakeoverRosterCrew, []takeoverdomain.TakeoverOtherPerson, *DutyRosterValidationError) {
+	if details == nil {
+		return []takeoverdomain.TakeoverRosterCrew{}, []takeoverdomain.TakeoverOtherPerson{}, nil
+	}
+	rows, err := BuildDutyRosterCrewRows(*details, actor)
+	if err != nil {
+		return nil, nil, err
+	}
+	crews := make([]takeoverdomain.TakeoverRosterCrew, 0, len(rows))
+	others := make([]takeoverdomain.TakeoverOtherPerson, 0)
+	for i := range rows {
+		if strings.EqualFold(strings.TrimSpace(rows[i].RoleCode), "other_person") {
+			others = append(others, takeoverdomain.TakeoverOtherPerson{
+				Name:        rows[i].NameLabel,
+				MobilePhone: rows[i].MobilePhone,
+				Email:       rows[i].Email,
+				CreatedBy:   actor,
+				UpdatedBy:   actor,
+			})
+			continue
+		}
+		crews = append(crews, takeoverdomain.TakeoverRosterCrew{
+			RoleCode:         rows[i].RoleCode,
+			CrewType:         rows[i].CrewType,
+			UserID:           append([]byte(nil), rows[i].UserID...),
+			NameLabel:        rows[i].NameLabel,
+			MobilePhone:      rows[i].MobilePhone,
+			Email:            rows[i].Email,
+			DateStart:        rows[i].DateStart,
+			DateEnd:          rows[i].DateEnd,
+			ShiftStart:       nullableTimeStringPtr(rows[i].ShiftStart),
+			ShiftEnd:         nullableTimeStringPtr(rows[i].ShiftEnd),
+			FlightInstructor: rows[i].FlightInstructor,
+			LineChecker:      rows[i].LineChecker,
+			Supervisor:       rows[i].Supervisor,
+			Examiner:         rows[i].Examiner,
+			CoPilot:          rows[i].CoPilot,
+			CreatedBy:        actor,
+			UpdatedBy:        actor,
+		})
+	}
+	return crews, others, nil
+}
+
+func takeoverRosterCrewIdentityKey(row takeoverdomain.TakeoverRosterCrew) string {
+	return fmt.Sprintf(
+		"%s|%s|%s|%s|%s|%s|%s|%s|%s",
+		strings.ToLower(strings.TrimSpace(row.RoleCode)),
+		bytesKey(row.UserID),
+		strings.ToLower(strings.TrimSpace(row.CrewType)),
+		strings.ToLower(strings.TrimSpace(row.NameLabel)),
+		strings.ToLower(strings.TrimSpace(row.MobilePhone)),
+		strings.ToLower(strings.TrimSpace(row.Email)),
+		nullableDateKey(row.DateStart),
+		nullableDateKey(row.DateEnd),
+		nullableTimeStringKey(row.ShiftStart)+"|"+nullableTimeStringKey(row.ShiftEnd),
+	)
+}
+
+func takeoverRosterCrewPayloadEqual(a, b takeoverdomain.TakeoverRosterCrew) bool {
+	return bytes.Equal(a.UserID, b.UserID) &&
+		strings.EqualFold(strings.TrimSpace(a.RoleCode), strings.TrimSpace(b.RoleCode)) &&
+		strings.EqualFold(strings.TrimSpace(a.CrewType), strings.TrimSpace(b.CrewType)) &&
+		strings.TrimSpace(a.NameLabel) == strings.TrimSpace(b.NameLabel) &&
+		strings.TrimSpace(a.MobilePhone) == strings.TrimSpace(b.MobilePhone) &&
+		strings.TrimSpace(a.Email) == strings.TrimSpace(b.Email) &&
+		nullableDateEqual(a.DateStart, b.DateStart) &&
+		nullableDateEqual(a.DateEnd, b.DateEnd) &&
+		nullableTimeStringEqual(a.ShiftStart, b.ShiftStart) &&
+		nullableTimeStringEqual(a.ShiftEnd, b.ShiftEnd) &&
+		a.FlightInstructor == b.FlightInstructor &&
+		a.LineChecker == b.LineChecker &&
+		a.Supervisor == b.Supervisor &&
+		a.Examiner == b.Examiner &&
+		a.CoPilot == b.CoPilot
+}
+
+func nullableDateEqual(a, b *time.Time) bool {
+	switch {
+	case a == nil && b == nil:
+		return true
+	case a == nil || b == nil:
+		return false
+	default:
+		return dateOnlyUTC(*a).Equal(dateOnlyUTC(*b))
+	}
+}
+
+func nullableDateKey(v *time.Time) string {
+	if v == nil {
+		return "nil"
+	}
+	return dateOnlyUTC(*v).Format("2006-01-02")
+}
+
+func bytesKey(v []byte) string {
+	if len(v) == 0 {
+		return "nil"
+	}
+	return fmt.Sprintf("%x", v)
+}
+
+func nullableTimeStringPtr(v string) *string {
+	trimmed := strings.TrimSpace(v)
+	if trimmed == "" {
+		return nil
+	}
+	return &trimmed
+}
+
+func nullableTimeStringKey(v *string) string {
+	if v == nil {
+		return "nil"
+	}
+	return strings.TrimSpace(*v)
+}
+
+func nullableTimeStringEqual(a, b *string) bool {
+	switch {
+	case a == nil && b == nil:
+		return true
+	case a == nil || b == nil:
+		return false
+	default:
+		return strings.TrimSpace(*a) == strings.TrimSpace(*b)
+	}
+}
+
+func loadTakeoverRosterCrewsTx(tx *gorm.DB, takeoverID []byte) ([]takeoverdomain.TakeoverRosterCrew, error) {
+	rows := make([]takeoverdomain.TakeoverRosterCrew, 0)
+	if err := tx.Where("takeover_id = ? AND deleted_at IS NULL", takeoverID).Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func loadTakeoverOtherPeopleTx(tx *gorm.DB, takeoverID []byte) ([]takeoverdomain.TakeoverOtherPerson, error) {
+	rows := make([]takeoverdomain.TakeoverOtherPerson, 0)
+	if err := tx.Where("takeover_id = ? AND deleted_at IS NULL", takeoverID).Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func (s *TakeoverService) upsertTakeoverRosterRowsTx(
+	tx *gorm.DB,
+	takeoverID []byte,
+	in TakeoverCreateInput,
+) error {
+	// Reuse: fill id-referenced other-people from the master (snapshot) BEFORE rows are
+	// built, so an id-only reuse still passes the "name required" validation.
+	if err := resolveOtherPeopleMasterInputTx(tx, in.RosterDetail); err != nil {
+		return err
+	}
+	crews, others, crewErr := buildTakeoverCrewRows(in.RosterDetail, in.ActorUserID)
+	if crewErr != nil {
+		if strings.TrimSpace(crewErr.Detail) != "" {
+			return errors.New(crewErr.Detail)
+		}
+		return errors.New("invalid roster_detail")
+	}
+	if len(crews) == 0 && len(others) == 0 {
+		return nil
+	}
+	// Register/link each other-person to the reusable master (other_people). The takeover
+	// keeps its own snapshot (name/phone/email); other_person_id points at the master.
+	for i := range others {
+		master := &otherpersondomain.OtherPerson{
+			Name:        others[i].Name,
+			MobilePhone: others[i].MobilePhone,
+			Email:       others[i].Email,
+			CreatedBy:   in.ActorUserID,
+			UpdatedBy:   in.ActorUserID,
+		}
+		if err := upsertOtherPersonTx(tx, master); err != nil {
+			return err
+		}
+		others[i].OtherPersonID = append([]byte(nil), master.ID...)
+	}
+	existingCrews, err := loadTakeoverRosterCrewsTx(tx, takeoverID)
+	if err != nil {
+		return err
+	}
+	existingOthers, err := loadTakeoverOtherPeopleTx(tx, takeoverID)
+	if err != nil {
+		return err
+	}
+	existingCrewMap := make(map[string]takeoverdomain.TakeoverRosterCrew, len(existingCrews))
+	for i := range existingCrews {
+		existingCrewMap[takeoverRosterCrewIdentityKey(existingCrews[i])] = existingCrews[i]
+	}
+	existingOtherMap := make(map[string]takeoverdomain.TakeoverOtherPerson, len(existingOthers))
+	for i := range existingOthers {
+		key := strings.ToLower(strings.TrimSpace(existingOthers[i].Name)) + "|" +
+			strings.ToLower(strings.TrimSpace(existingOthers[i].MobilePhone)) + "|" +
+			strings.ToLower(strings.TrimSpace(existingOthers[i].Email))
+		existingOtherMap[key] = existingOthers[i]
+	}
+	touchedCrewKeys := make(map[string]struct{}, len(crews))
+	touchedOtherKeys := make(map[string]struct{}, len(others))
+	for i := range crews {
+		crews[i].TakeoverID = append([]byte(nil), takeoverID...)
+		key := takeoverRosterCrewIdentityKey(crews[i])
+		touchedCrewKeys[key] = struct{}{}
+		if existingRow, ok := existingCrewMap[key]; ok {
+			crews[i].ID = append([]byte(nil), existingRow.ID...)
+			if takeoverRosterCrewPayloadEqual(existingRow, crews[i]) {
+				continue
+			}
+			if err := tx.Model(&takeoverdomain.TakeoverRosterCrew{}).
+				Where("id = ? AND deleted_at IS NULL", crews[i].ID).
+				Updates(map[string]any{
+					"takeover_id":       crews[i].TakeoverID,
+					"confirm_at":        crews[i].ConfirmAt,
+					"role_code":         crews[i].RoleCode,
+					"crew_type":         crews[i].CrewType,
+					"user_id":           crews[i].UserID,
+					"name_label":        crews[i].NameLabel,
+					"mobile_phone":      crews[i].MobilePhone,
+					"email":             crews[i].Email,
+					"date_start":        crews[i].DateStart,
+					"date_end":          crews[i].DateEnd,
+					"shift_start":       crews[i].ShiftStart,
+					"shift_end":         crews[i].ShiftEnd,
+					"flight_instructor": crews[i].FlightInstructor,
+					"line_checker":      crews[i].LineChecker,
+					"supervisor":        crews[i].Supervisor,
+					"examiner":          crews[i].Examiner,
+					"co_pilot":          crews[i].CoPilot,
+					"updated_by":        in.ActorUserID,
+				}).Error; err != nil {
+				return err
+			}
+			continue
+		}
+		if err := tx.Create(&crews[i]).Error; err != nil {
+			return err
+		}
+	}
+	for _, existingRow := range existingCrews {
+		key := takeoverRosterCrewIdentityKey(existingRow)
+		if _, ok := touchedCrewKeys[key]; ok {
+			continue
+		}
+		if err := tx.Model(&takeoverdomain.TakeoverRosterCrew{}).
+			Where("id = ? AND deleted_at IS NULL", existingRow.ID).
+			Updates(map[string]any{"deleted_at": time.Now().UTC(), "deleted_by": in.ActorUserID, "updated_by": in.ActorUserID}).Error; err != nil {
+			return err
+		}
+	}
+	for i := range others {
+		others[i].TakeoverID = append([]byte(nil), takeoverID...)
+		key := strings.ToLower(strings.TrimSpace(others[i].Name)) + "|" +
+			strings.ToLower(strings.TrimSpace(others[i].MobilePhone)) + "|" +
+			strings.ToLower(strings.TrimSpace(others[i].Email))
+		touchedOtherKeys[key] = struct{}{}
+		if existingRow, ok := existingOtherMap[key]; ok {
+			others[i].ID = append([]byte(nil), existingRow.ID...)
+			if strings.TrimSpace(existingRow.Name) == strings.TrimSpace(others[i].Name) &&
+				strings.TrimSpace(existingRow.MobilePhone) == strings.TrimSpace(others[i].MobilePhone) &&
+				strings.TrimSpace(existingRow.Email) == strings.TrimSpace(others[i].Email) {
+				continue
+			}
+			if err := tx.Model(&takeoverdomain.TakeoverOtherPerson{}).
+				Where("id = ? AND deleted_at IS NULL", others[i].ID).
+				Updates(map[string]any{
+					"takeover_id":     others[i].TakeoverID,
+					"other_person_id": others[i].OtherPersonID,
+					"name":            others[i].Name,
+					"mobile_phone":    others[i].MobilePhone,
+					"email":           others[i].Email,
+					"updated_by":      in.ActorUserID,
+				}).Error; err != nil {
+				return err
+			}
+			continue
+		}
+		if err := tx.Create(&others[i]).Error; err != nil {
+			return err
+		}
+	}
+	for _, existingRow := range existingOthers {
+		key := strings.ToLower(strings.TrimSpace(existingRow.Name)) + "|" +
+			strings.ToLower(strings.TrimSpace(existingRow.MobilePhone)) + "|" +
+			strings.ToLower(strings.TrimSpace(existingRow.Email))
+		if _, ok := touchedOtherKeys[key]; ok {
+			continue
+		}
+		if err := tx.Model(&takeoverdomain.TakeoverOtherPerson{}).
+			Where("id = ? AND deleted_at IS NULL", existingRow.ID).
+			Updates(map[string]any{"deleted_at": time.Now().UTC(), "deleted_by": in.ActorUserID, "updated_by": in.ActorUserID}).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (s *TakeoverService) upsertTakeoverInspectionTx(
+	tx *gorm.DB,
+	takeoverID []byte,
+	inspectionID []byte,
+	in *requestdto.ReserveAcInspectionCreateAttributes,
+	helicopterID []byte,
+	actor []byte,
+) ([]byte, error) {
+	if in == nil {
+		return inspectionID, nil
+	}
+	if len(helicopterID) != 16 {
+		return nil, errors.New("helicopter_id is required for inspection data")
+	}
+	// Every file edited/created from an FPWB template for this takeover must be
+	// represented in the submitted flight-preparation file checklist. Files that
+	// were not edited need not be in the checklist.
+	if err := s.validateTakeoverEditedTemplateFilesTx(tx, takeoverID, helicopterID, in.Prepare.FileChecklist); err != nil {
+		return nil, err
+	}
+	inspectionDate, err := time.Parse("2006-01-02", strings.TrimSpace(in.InspectionDate))
+	if err != nil {
+		return nil, errors.New("inspection.inspection_date must be YYYY-MM-DD")
+	}
+	if len(inspectionID) == 0 {
+		inspection := &flightinspection.FlightInspection{
+			InspectionDate: dateOnlyUTC(inspectionDate),
+			Status:         flightinspection.StatusDraft,
+			CreatedBy:      actor,
+			UpdatedBy:      actor,
+		}
+		if err := tx.Create(inspection).Error; err != nil {
+			return nil, err
+		}
+		inspectionID = append([]byte(nil), inspection.ID...)
+	} else {
+		if err := tx.Model(&flightinspection.FlightInspection{}).
+			Where("id = ?", inspectionID).
+			Updates(map[string]any{
+				"inspection_date": inspectionDate,
+				"updated_by":      actor,
+			}).Error; err != nil {
+			return nil, err
+		}
+	}
+
+	beforeRow := &beforeflightinspection.BeforeFlightInspection{
+		FlightInspectionID:        append([]byte(nil), inspectionID...),
+		OilEngineNR1Checked:       in.Before.OilEngineNR1Checked,
+		OilEngineNR2Checked:       in.Before.OilEngineNR2Checked,
+		HydraulicLHChecked:        in.Before.HydraulicLHChecked,
+		HydraulicRHChecked:        in.Before.HydraulicRHChecked,
+		OilTransmissionMGBChecked: in.Before.OilTransmissionMGBChecked,
+		OilTransmissionIGBChecked: in.Before.OilTransmissionIGBChecked,
+		OilTransmissionTGBChecked: in.Before.OilTransmissionTGBChecked,
+		FuelAmount:                in.Before.FuelAmount,
+		FuelAddedAmount:           in.Before.FuelAddedAmount,
+		Note:                      in.Before.Note,
+		CreatedBy:                 actor,
+		UpdatedBy:                 actor,
+	}
+	if in.Before.FuelUnit != nil {
+		unit, ok := beforeflightinspection.NormalizeFuelUnit(*in.Before.FuelUnit)
+		if !ok {
+			return nil, errors.New("inspection.before.fuel_unit must be one of LT, KG, POUND")
+		}
+		beforeRow.FuelUnit = unit
+	}
+	if err := tx.Clauses(clause.OnConflict{
+		Columns: []clause.Column{{Name: "flight_inspection_id"}},
+		DoUpdates: clause.AssignmentColumns([]string{
+			"oil_engine_nr1_checked",
+			"oil_engine_nr2_checked",
+			"hydraulic_lh_checked",
+			"hydraulic_rh_checked",
+			"oil_transmission_mgb_checked",
+			"oil_transmission_igb_checked",
+			"oil_transmission_tgb_checked",
+			"fuel_amount",
+			"fuel_unit",
+			"fuel_added_amount",
+			"note",
+			"updated_by",
+		}),
+	}).Create(beforeRow).Error; err != nil {
+		return nil, err
+	}
+
+	prepRow := &flightprepcheck.FlightPrepCheck{
+		FlightInspectionID: append([]byte(nil), inspectionID...),
+		CreatedBy:          actor,
+		UpdatedBy:          actor,
+	}
+	if in.Prepare.NotamBriefing != nil {
+		prepRow.NOTAMBriefing = *in.Prepare.NotamBriefing
+	}
+	if in.Prepare.WeatherBriefing != nil {
+		prepRow.WeatherBriefing = *in.Prepare.WeatherBriefing
+	}
+	if in.Prepare.OperationalFlightPlan != nil {
+		prepRow.OperationalFlightPlan = *in.Prepare.OperationalFlightPlan
+	}
+	if err := tx.Clauses(clause.OnConflict{
+		Columns: []clause.Column{{Name: "flight_inspection_id"}},
+		DoUpdates: clause.AssignmentColumns([]string{
+			"notam_briefing",
+			"weather_briefing",
+			"operational_flight_plan",
+			"updated_by",
+		}),
+	}).Create(prepRow).Error; err != nil {
+		return nil, err
+	}
+
+	if len(in.Before.FileChecklist) > 0 {
+		if err := s.upsertTakeoverChecklistItemsTx(tx, inspectionID, helicopterID, helicopterfile.SectionBeforeFirstFlightInspection, in.Before.FileChecklist, actor); err != nil {
+			return nil, err
+		}
+	}
+	if len(in.Prepare.FileChecklist) > 0 {
+		if err := s.upsertTakeoverChecklistItemsTx(tx, inspectionID, helicopterID, helicopterfile.SectionFlightPreparationAndWB, in.Prepare.FileChecklist, actor); err != nil {
+			return nil, err
+		}
+	}
+	return inspectionID, nil
+}
+
+func (s *TakeoverService) upsertTakeoverReserveTx(
+	tx *gorm.DB,
+	takeoverID []byte,
+	baseID []byte,
+	existing *takeoverExisting,
+	in TakeoverCreateInput,
+) error {
+	if existing == nil {
+		return errors.New("takeover state is not loaded")
+	}
+	if existing.Reserve == nil {
+		if !in.HasHelicopterID && !in.HasInspection {
+			return nil
+		}
+		if !in.HasHelicopterID || !in.HasInspection || in.Inspection == nil {
+			return errors.New("helicopter_id and inspection are required to create reserve data")
+		}
+		if err := ensureHelicopterExistsTx(tx, in.HelicopterID); err != nil {
+			logTakeoverServiceStepError("upsertTakeoverReserveTx.ensureHelicopterExistsTx", err)
+			return err
+		}
+		inspectionID, err := s.upsertTakeoverInspectionTx(tx, takeoverID, nil, in.Inspection, in.HelicopterID, in.ActorUserID)
+		if err != nil {
+			logTakeoverServiceStepError("upsertTakeoverReserveTx.upsertTakeoverInspectionTx(create)", err)
+			return err
+		}
+		reserveRow := &reserveac.ReserveAc{
+			Status:       reserveacutil.StatusPending,
+			BaseID:       append([]byte(nil), baseID...),
+			Notes:        in.Notes,
+			AircraftID:   append([]byte(nil), in.HelicopterID...),
+			InspectionID: inspectionID,
+			CreatedBy:    in.ActorUserID,
+			UpdatedBy:    in.ActorUserID,
+		}
+		if err := tx.Create(reserveRow).Error; err != nil {
+			logTakeoverServiceStepError("upsertTakeoverReserveTx.createReserve", err)
+			return err
+		}
+		if err := tx.Model(&takeoverdomain.TakeoverAc{}).
+			Where("id = ? AND deleted_at IS NULL", takeoverID).
+			Updates(map[string]any{"reserve_ac_id": reserveRow.ID, "updated_by": in.ActorUserID}).Error; err != nil {
+			logTakeoverServiceStepError("upsertTakeoverReserveTx.attachReserveToTakeover", err)
+			return err
+		}
+		existing.Reserve = reserveRow
+		return nil
+	}
+
+	changed := false
+	if len(baseID) == 16 && !bytes.Equal(existing.Reserve.BaseID, baseID) {
+		existing.Reserve.BaseID = append([]byte(nil), baseID...)
+		changed = true
+	}
+	if in.Notes != nil && (existing.Reserve.Notes == nil || *existing.Reserve.Notes != *in.Notes) {
+		existing.Reserve.Notes = in.Notes
+		changed = true
+	}
+	if in.HasHelicopterID {
+		if len(in.HelicopterID) != 16 {
+			return errors.New("helicopter_id must be a valid UUID")
+		}
+		if err := ensureHelicopterExistsTx(tx, in.HelicopterID); err != nil {
+			logTakeoverServiceStepError("upsertTakeoverReserveTx.ensureHelicopterExistsTx(update)", err)
+			return err
+		}
+		if !bytes.Equal(existing.Reserve.AircraftID, in.HelicopterID) {
+			existing.Reserve.AircraftID = append([]byte(nil), in.HelicopterID...)
+			changed = true
+		}
+	}
+	if in.HasInspection {
+		if in.Inspection == nil {
+			return errors.New("inspection data is required")
+		}
+		helicopterID := existing.Reserve.AircraftID
+		if in.HasHelicopterID {
+			helicopterID = in.HelicopterID
+		}
+		if len(helicopterID) != 16 {
+			return errors.New("helicopter_id is required for inspection data")
+		}
+		inspectionID, err := s.upsertTakeoverInspectionTx(tx, takeoverID, existing.Reserve.InspectionID, in.Inspection, helicopterID, in.ActorUserID)
+		if err != nil {
+			logTakeoverServiceStepError("upsertTakeoverReserveTx.upsertTakeoverInspectionTx(update)", err)
+			return err
+		}
+		if len(existing.Reserve.InspectionID) != 16 || !bytes.Equal(existing.Reserve.InspectionID, inspectionID) {
+			existing.Reserve.InspectionID = append([]byte(nil), inspectionID...)
+			changed = true
+		}
+	}
+	if changed {
+		existing.Reserve.UpdatedBy = in.ActorUserID
+		if err := tx.Save(existing.Reserve).Error; err != nil {
+			logTakeoverServiceStepError("upsertTakeoverReserveTx.saveReserve", err)
+			return err
+		}
+	}
+	return nil
+}
+
+/*
+
+func (s *TakeoverService) upsertTakeoverReserveTx(
+	tx *gorm.DB,
+	takeoverID []byte,
+	baseID []byte,
+	existing *takeoverExisting,
+	in TakeoverCreateInput,
+) error {
+	if existing == nil {
+		return errors.New("takeover state is not available")
+	}
+	if existing.Reserve == nil {
+		if !in.HasHelicopterID && !in.HasInspection {
+			return nil
+		}
+		if !in.HasHelicopterID || len(in.HelicopterID) != 16 {
+			return errors.New("helicopter_id is required to create reserve data")
+		}
+		if !in.HasInspection || in.Inspection == nil {
+			return errors.New("inspection is required to create reserve data")
+		}
+		if err := ensureHelicopterExistsTx(tx, in.HelicopterID); err != nil {
+			return err
+		}
+		inspectionID, err := upsertTakeoverInspectionTx(tx, nil, in.Inspection, in.ActorUserID, in.HelicopterID)
+		if err != nil {
+			return err
+		}
+		reserveRow := &reserveac.ReserveAc{
+			Status:       reserveacutil.StatusPending,
+			BaseID:       append([]byte(nil), baseID...),
+			Notes:        in.Notes,
+			AircraftID:   append([]byte(nil), in.HelicopterID...),
+			InspectionID: append([]byte(nil), inspectionID...),
+			CreatedBy:    in.ActorUserID,
+			UpdatedBy:    in.ActorUserID,
+		}
+		if err := tx.Create(reserveRow).Error; err != nil {
+			return err
+		}
+		if err := tx.Model(&takeoverdomain.TakeoverAc{}).
+			Where("id = ? AND deleted_at IS NULL", takeoverID).
+			Updates(map[string]any{"reserve_ac_id": reserveRow.ID, "updated_by": in.ActorUserID}).Error; err != nil {
+			return err
+		}
+		existing.Reserve = reserveRow
+		return nil
+	}
+
+	changed := false
+	if in.HasBaseID && !bytes.Equal(existing.Reserve.BaseID, baseID) {
+		existing.Reserve.BaseID = append([]byte(nil), baseID...)
+		changed = true
+	}
+	if in.Notes != nil && (existing.Reserve.Notes == nil || strings.TrimSpace(*existing.Reserve.Notes) != strings.TrimSpace(*in.Notes)) {
+		existing.Reserve.Notes = in.Notes
+		changed = true
+	}
+	if in.HasHelicopterID {
+		if len(in.HelicopterID) != 16 {
+			return errors.New("helicopter_id must be a valid UUID")
+		}
+		if err := ensureHelicopterExistsTx(tx, in.HelicopterID); err != nil {
+			return err
+		}
+		if !bytes.Equal(existing.Reserve.AircraftID, in.HelicopterID) {
+			existing.Reserve.AircraftID = append([]byte(nil), in.HelicopterID...)
+			changed = true
+		}
+	}
+	if in.HasInspection {
+		if in.Inspection == nil {
+			return errors.New("inspection data is required when inspection is provided")
+		}
+		heliID := existing.Reserve.AircraftID
+		if in.HasHelicopterID {
+			heliID = in.HelicopterID
+		}
+		if len(heliID) != 16 {
+			return errors.New("helicopter_id is required to update inspection data")
+		}
+		inspectionID, err := upsertTakeoverInspectionTx(tx, existing.Reserve.InspectionID, in.Inspection, in.ActorUserID, heliID)
+		if err != nil {
+			return err
+		}
+		if len(existing.Reserve.InspectionID) != 16 || !bytes.Equal(existing.Reserve.InspectionID, inspectionID) {
+			existing.Reserve.InspectionID = append([]byte(nil), inspectionID...)
+			changed = true
+		}
+	}
+	if changed {
+		existing.Reserve.UpdatedBy = in.ActorUserID
+		if err := tx.Save(existing.Reserve).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func upsertTakeoverInspectionTx(tx *gorm.DB, inspectionID []byte, in *requestdto.ReserveAcInspectionCreateAttributes, actor []byte, helicopterID []byte) ([]byte, error) {
+	if in == nil {
+		return inspectionID, nil
+	}
+	existingInspection := len(inspectionID) == 16
+	if len(helicopterID) != 16 {
+		return nil, errors.New("helicopter_id is required to update inspection data")
+	}
+	if err := validateTakeoverInspectionChecklists(in); err != nil {
+		logTakeoverServiceStepError("upsertTakeoverInspectionTx.validateTakeoverInspectionChecklists", err)
+		return nil, err
+	}
+	inspectionDate, err := time.Parse("2006-01-02", strings.TrimSpace(in.InspectionDate))
+	if err != nil {
+		logTakeoverServiceStepError("upsertTakeoverInspectionTx.parseInspectionDate", err)
+		return nil, errors.New("inspection.inspection_date must be YYYY-MM-DD")
+	}
+	if len(inspectionID) != 16 {
+		inspection := &flightinspection.FlightInspection{
+			InspectionDate: dateOnlyUTC(inspectionDate),
+			Status:         flightinspection.StatusDraft,
+			CreatedBy:      actor,
+			UpdatedBy:      actor,
+		}
+		if err := tx.Create(inspection).Error; err != nil {
+			logTakeoverServiceStepError("upsertTakeoverInspectionTx.createFlightInspection", err)
+			return nil, err
+		}
+		inspectionID = append([]byte(nil), inspection.ID...)
+	} else if err := tx.Model(&flightinspection.FlightInspection{}).
+		Where("id = ?", inspectionID).
+		Updates(map[string]any{"inspection_date": dateOnlyUTC(inspectionDate), "updated_by": actor}).Error; err != nil {
+		logTakeoverServiceStepError("upsertTakeoverInspectionTx.updateFlightInspection", err)
+		return nil, err
+	}
+
+	beforeRow := &beforeflightinspection.BeforeFlightInspection{
+		FlightInspectionID:        append([]byte(nil), inspectionID...),
+		OilEngineNR1Checked:       in.Before.OilEngineNR1Checked,
+		OilEngineNR2Checked:       in.Before.OilEngineNR2Checked,
+		HydraulicLHChecked:        in.Before.HydraulicLHChecked,
+		HydraulicRHChecked:        in.Before.HydraulicRHChecked,
+		OilTransmissionMGBChecked: in.Before.OilTransmissionMGBChecked,
+		OilTransmissionIGBChecked: in.Before.OilTransmissionIGBChecked,
+		OilTransmissionTGBChecked: in.Before.OilTransmissionTGBChecked,
+		FuelAmount:                in.Before.FuelAmount,
+		FuelAddedAmount:           in.Before.FuelAddedAmount,
+		Note:                      in.Before.Note,
+		CreatedBy:                 actor,
+		UpdatedBy:                 actor,
+	}
+	if in.Before.FuelUnit != nil {
+		unit, ok := beforeflightinspection.NormalizeFuelUnit(*in.Before.FuelUnit)
+		if !ok {
+			return nil, errors.New("inspection.before.fuel_unit must be one of LT, KG, POUND")
+		}
+		beforeRow.FuelUnit = unit
+	}
+	if err := tx.Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "flight_inspection_id"}},
+		DoUpdates: clause.AssignmentColumns([]string{"oil_engine_nr1_checked", "oil_engine_nr2_checked", "hydraulic_lh_checked", "hydraulic_rh_checked", "oil_transmission_mgb_checked", "oil_transmission_igb_checked", "oil_transmission_tgb_checked", "fuel_amount", "fuel_unit", "fuel_added_amount", "note", "updated_by"}),
+	}).Create(beforeRow).Error; err != nil {
+		logTakeoverServiceStepError("upsertTakeoverInspectionTx.upsertBeforeFlightInspection", err)
+		return nil, err
+	}
+
+	prepRow := &flightprepcheck.FlightPrepCheck{
+		FlightInspectionID: append([]byte(nil), inspectionID...),
+		CreatedBy:          actor,
+		UpdatedBy:          actor,
+	}
+	if in.Prepare.NotamBriefing != nil {
+		prepRow.NOTAMBriefing = *in.Prepare.NotamBriefing
+	}
+	if in.Prepare.WeatherBriefing != nil {
+		prepRow.WeatherBriefing = *in.Prepare.WeatherBriefing
+	}
+	if in.Prepare.OperationalFlightPlan != nil {
+		prepRow.OperationalFlightPlan = *in.Prepare.OperationalFlightPlan
+	}
+	if err := tx.Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "flight_inspection_id"}},
+		DoUpdates: clause.AssignmentColumns([]string{"notam_briefing", "weather_briefing", "operational_flight_plan", "updated_by"}),
+	}).Create(prepRow).Error; err != nil {
+		logTakeoverServiceStepError("upsertTakeoverInspectionTx.upsertFlightPrepCheck", err)
+		return nil, err
+	}
+
+	if !existingInspection || len(in.Before.FileChecklist) > 0 {
+		if err := s.upsertTakeoverChecklistItemsTx(tx, inspectionID, helicopterID, helicopterfile.SectionBeforeFirstFlightInspection, in.Before.FileChecklist, actor); err != nil {
+			logTakeoverServiceStepError("upsertTakeoverInspectionTx.beforeChecklist", err)
+			return nil, err
+		}
+	}
+	if !existingInspection || len(in.Prepare.FileChecklist) > 0 {
+		if err := s.upsertTakeoverChecklistItemsTx(tx, inspectionID, helicopterID, helicopterfile.SectionFlightPreparationAndWB, in.Prepare.FileChecklist, actor); err != nil {
+			logTakeoverServiceStepError("upsertTakeoverInspectionTx.prepareChecklist", err)
+			return nil, err
+		}
+	}
+	// On updates, an omitted fleet_status_file block means "keep the existing
+	// checklist as-is". Only enforce the mandatory-file check when the caller
+	// actually sends the section, or when we're creating a brand new inspection.
+	if !existingInspection || len(in.FleetStatusFile.FileChecklist) > 0 {
+		if err := validateMandatoryFleetStatusFilesTx(tx, helicopterID, in.FleetStatusFile.FileChecklist); err != nil {
+			logTakeoverServiceStepError("upsertTakeoverInspectionTx.validateMandatoryFleetStatusFilesTx", err)
+			return nil, err
+		}
+	}
+	return inspectionID, nil
+}
+*/
+
+func validateTakeoverInspectionChecklists(in *requestdto.ReserveAcInspectionCreateAttributes) error {
+	if in == nil {
+		return nil
+	}
+	if err := validateTakeoverChecklistSection(in.Before.FileChecklist, "inspection.before.file_checklist"); err != nil {
+		return err
+	}
+	if err := validateTakeoverChecklistSection(in.Prepare.FileChecklist, "inspection.prepare.file_checklist"); err != nil {
+		return err
+	}
+	return nil
+}
+
+func validateTakeoverChecklistSection(items []requestdto.ReserveAcFileChecklistItem, label string) error {
+	if len(items) == 0 {
+		return nil
+	}
+	for i := range items {
+		if !items[i].IsDone {
+			return fmt.Errorf("%s must be fully checked", label)
+		}
+	}
+	return nil
+}
+
+func validateMandatoryFleetStatusFilesTx(tx *gorm.DB, helicopterID []byte, items []requestdto.ReserveAcFileChecklistItem) error {
+	if len(helicopterID) != 16 {
+		return nil
+	}
+	type fsfRow struct {
+		ID []byte `gorm:"column:id"`
+	}
+	latest := tx.Table("fleet_statuses").
+		Select("id").
+		Where("helicopter_id = ? AND deleted_at IS NULL", helicopterID).
+		Order("created_at DESC").
+		Limit(1)
+	mandatory := make([]fsfRow, 0)
+	if err := tx.Table("fleet_status_files").
+		Select("id").
+		Where("is_mandatory = ? AND fleet_status_id = (?)", true, latest).
+		Scan(&mandatory).Error; err != nil {
+		return err
+	}
+	if len(mandatory) == 0 {
+		return nil
+	}
+	done := make(map[string]bool, len(items))
+	for i := range items {
+		id, err := uuidv7.ParseString(strings.TrimSpace(items[i].HelicopterFileID))
+		if err != nil {
+			continue
+		}
+		done[string(id)] = items[i].IsDone
+	}
+	for _, m := range mandatory {
+		if !done[string(m.ID)] {
+			return fmt.Errorf("inspection.fleet_status_file: a mandatory file must be checked (is_done) before takeover")
+		}
+	}
+	return nil
+}
+
+func loadTakeoverReserveTx(tx *gorm.DB, id []byte) (*reserveac.ReserveAc, error) {
+	if len(id) != 16 {
+		return nil, nil
+	}
+	var row reserveac.ReserveAc
+	if err := tx.Where("id = ? AND deleted_at IS NULL", id).Take(&row).Error; err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	return &row, nil
+}
+
+func getLatestMissionCodeByPrefixTx(tx *gorm.DB, prefix string) (string, error) {
+	var out struct {
+		MissionCode string `gorm:"column:mission_code"`
+	}
+	err := tx.Table("flights").
+		Select("mission_code").
+		Where("mission_code LIKE ? AND deleted_at IS NULL", prefix+"%").
+		Order("mission_code DESC").
+		Limit(1).
+		Scan(&out).Error
+	if err != nil {
+		return "", err
+	}
+	return out.MissionCode, nil
+}
diff --git a/internal/service/takeover_service_test.go b/internal/service/takeover_service_test.go
new file mode 100644
index 0000000..3a4de56
--- /dev/null
+++ b/internal/service/takeover_service_test.go
@@ -0,0 +1,741 @@
+package service
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/base"
+	beforeflightinspection "wucher/internal/domain/before_flight_inspection"
+	filemanager "wucher/internal/domain/file_manager"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	flightprepcheck "wucher/internal/domain/flight_prep_check"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	"wucher/internal/repository/mysql"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+)
+
+func openTakeoverServiceTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:%s?mode=memory&cache=shared", filepath.Join(t.TempDir(), "takeover.db"))
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&base.BaseCategory{}, &base.Base{}, &base.BaseOperationalShiftTime{}); err != nil {
+		t.Fatalf("auto migrate base models: %v", err)
+	}
+	if err := db.AutoMigrate(&flightinspection.FlightInspection{}, &beforeflightinspection.BeforeFlightInspection{}, &flightprepcheck.FlightPrepCheck{}); err != nil {
+		t.Fatalf("auto migrate inspection models: %v", err)
+	}
+	if err := db.Exec(`CREATE TABLE helicopter_files (
+		id BLOB PRIMARY KEY,
+		section TEXT NOT NULL,
+		position INTEGER NOT NULL DEFAULT 1,
+		is_mandatory INTEGER NOT NULL DEFAULT 0,
+		helicopter_id BLOB NOT NULL,
+		file_attachment_id BLOB,
+		source_file_id BLOB,
+		created_at DATETIME,
+		created_by BLOB,
+		updated_at DATETIME,
+		updated_by BLOB
+	)`).Error; err != nil {
+		t.Fatalf("create helicopter_files table: %v", err)
+	}
+	if err := db.Exec(`CREATE TABLE flight_inspection_file_checklists (
+		id BLOB PRIMARY KEY,
+		is_done INTEGER NOT NULL DEFAULT 0,
+		helicopter_file_id BLOB NOT NULL,
+		flight_inspection_id BLOB NOT NULL,
+		created_at DATETIME,
+		created_by BLOB,
+		updated_at DATETIME,
+		updated_by BLOB,
+		UNIQUE (flight_inspection_id, helicopter_file_id)
+	)`).Error; err != nil {
+		t.Fatalf("create flight_inspection_file_checklists table: %v", err)
+	}
+	return db
+}
+
+// newChecklistTestService builds a TakeoverService wired with the concrete repository so
+// the checklist upsert can load template files (DB access lives in the repository layer).
+func newChecklistTestService(db *gorm.DB) *TakeoverService {
+	return NewTakeoverService(db).WithChecklistTemplateRepository(mysql.NewTakeoverRepository(db))
+}
+
+func TestValidateTakeoverInspectionChecklistsAllowsEmptySections(t *testing.T) {
+	if err := validateTakeoverInspectionChecklists(&requestdto.ReserveAcInspectionCreateAttributes{}); err != nil {
+		t.Fatalf("expected empty sections to be allowed, got %v", err)
+	}
+}
+
+func TestUpsertTakeoverInspectionTxAllowsMissingFleetStatusFileOnUpdate(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	now := time.Now().UTC()
+	helicopterID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	inspectionDate := time.Date(2026, 6, 24, 0, 0, 0, 0, time.UTC)
+
+	if err := db.Create(&flightinspection.FlightInspection{
+		ID:             inspectionID,
+		InspectionDate: inspectionDate,
+		Status:         flightinspection.StatusDraft,
+		CreatedAt:      now,
+		UpdatedAt:      now,
+	}).Error; err != nil {
+		t.Fatalf("create inspection: %v", err)
+	}
+
+	req := &requestdto.ReserveAcInspectionCreateAttributes{
+		InspectionDate: "2026-06-24",
+		Before: requestdto.ReserveAcBeforeInspectionAttributes{
+			OilEngineNR1Checked:       boolPtr(true),
+			OilEngineNR2Checked:       boolPtr(true),
+			HydraulicLHChecked:        boolPtr(true),
+			HydraulicRHChecked:        boolPtr(true),
+			OilTransmissionMGBChecked: boolPtr(true),
+			OilTransmissionIGBChecked: boolPtr(false),
+			OilTransmissionTGBChecked: boolPtr(true),
+			FuelAmount:                floatPtr(1),
+			FuelUnit:                  stringPtr(beforeflightinspection.FuelUnitLT),
+			FuelAddedAmount:           floatPtr(0),
+		},
+		Prepare: requestdto.ReserveAcPrepareInspectionAttributes{
+			NotamBriefing:         boolPtr(true),
+			WeatherBriefing:       boolPtr(true),
+			OperationalFlightPlan: boolPtr(false),
+		},
+	}
+
+	gotID, err := newChecklistTestService(db).upsertTakeoverInspectionTx(db, nil, inspectionID, req, helicopterID, uuidv7.MustBytes())
+	if err != nil {
+		t.Fatalf("expected update inspection without fleet_status_file to pass, got %v", err)
+	}
+	if string(gotID) != string(inspectionID) {
+		t.Fatalf("unexpected inspection id: %x", gotID)
+	}
+}
+
+func TestUpsertTakeoverInspectionTxAllowsMissingFileChecklistsOnUpdate(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	now := time.Now().UTC()
+	helicopterID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	inspectionDate := time.Date(2026, 6, 24, 0, 0, 0, 0, time.UTC)
+
+	if err := db.Create(&flightinspection.FlightInspection{
+		ID:             inspectionID,
+		InspectionDate: inspectionDate,
+		Status:         flightinspection.StatusDraft,
+		CreatedAt:      now,
+		UpdatedAt:      now,
+	}).Error; err != nil {
+		t.Fatalf("create inspection: %v", err)
+	}
+
+	req := &requestdto.ReserveAcInspectionCreateAttributes{
+		InspectionDate: "2026-06-24",
+		Before: requestdto.ReserveAcBeforeInspectionAttributes{
+			OilEngineNR1Checked:       boolPtr(true),
+			OilEngineNR2Checked:       boolPtr(true),
+			HydraulicLHChecked:        boolPtr(true),
+			HydraulicRHChecked:        boolPtr(true),
+			OilTransmissionMGBChecked: boolPtr(true),
+			OilTransmissionIGBChecked: boolPtr(false),
+			OilTransmissionTGBChecked: boolPtr(true),
+			FuelAmount:                floatPtr(1),
+			FuelUnit:                  stringPtr(beforeflightinspection.FuelUnitLT),
+			FuelAddedAmount:           floatPtr(0),
+		},
+		Prepare: requestdto.ReserveAcPrepareInspectionAttributes{
+			NotamBriefing:         boolPtr(true),
+			WeatherBriefing:       boolPtr(true),
+			OperationalFlightPlan: boolPtr(false),
+		},
+	}
+
+	gotID, err := newChecklistTestService(db).upsertTakeoverInspectionTx(db, nil, inspectionID, req, helicopterID, uuidv7.MustBytes())
+	if err != nil {
+		t.Fatalf("expected update inspection without file_checklists to pass, got %v", err)
+	}
+	if string(gotID) != string(inspectionID) {
+		t.Fatalf("unexpected inspection id: %x", gotID)
+	}
+}
+
+func TestEnsureHelicopterExistsTxDoesNotRequireDeletedAtColumn(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	helicopterID := uuidv7.MustBytes()
+
+	if err := db.Exec(`CREATE TABLE helicopters (
+		id BLOB PRIMARY KEY
+	)`).Error; err != nil {
+		t.Fatalf("create helicopters table: %v", err)
+	}
+	if err := db.Exec(fmt.Sprintf(`INSERT INTO helicopters (id) VALUES (X'%x')`, helicopterID)).Error; err != nil {
+		t.Fatalf("seed helicopter: %v", err)
+	}
+
+	if err := ensureHelicopterExistsTx(db, helicopterID); err != nil {
+		t.Fatalf("expected helicopter existence check to pass without deleted_at column, got %v", err)
+	}
+	if err := ensureHelicopterExistsTx(db, uuidv7.MustBytes()); err == nil {
+		t.Fatalf("expected missing helicopter to fail")
+	}
+}
+
+func TestUpsertTakeoverInspectionTxAllowsEmptyFileChecklistsOnUpdate(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	now := time.Now().UTC()
+	helicopterID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	inspectionDate := time.Date(2026, 6, 24, 0, 0, 0, 0, time.UTC)
+
+	if err := db.Create(&flightinspection.FlightInspection{
+		ID:             inspectionID,
+		InspectionDate: inspectionDate,
+		Status:         flightinspection.StatusDraft,
+		CreatedAt:      now,
+		UpdatedAt:      now,
+	}).Error; err != nil {
+		t.Fatalf("create inspection: %v", err)
+	}
+	templateFile := helicopterfile.HelicopterFile{
+		ID:               uuidv7.MustBytes(),
+		Section:          helicopterfile.SectionBeforeFirstFlightInspection,
+		Position:         1,
+		IsMandatory:      true,
+		HelicopterID:     helicopterID,
+		FileAttachmentID: uuidv7.MustBytes(),
+		CreatedAt:        now,
+		UpdatedAt:        now,
+	}
+	if err := db.Create(&templateFile).Error; err != nil {
+		t.Fatalf("create helicopter file template: %v", err)
+	}
+
+	req := &requestdto.ReserveAcInspectionCreateAttributes{
+		InspectionDate: "2026-06-24",
+		Before: requestdto.ReserveAcBeforeInspectionAttributes{
+			OilEngineNR1Checked:       boolPtr(true),
+			OilEngineNR2Checked:       boolPtr(true),
+			HydraulicLHChecked:        boolPtr(true),
+			HydraulicRHChecked:        boolPtr(true),
+			OilTransmissionMGBChecked: boolPtr(true),
+			OilTransmissionIGBChecked: boolPtr(false),
+			OilTransmissionTGBChecked: boolPtr(true),
+			FuelAmount:                floatPtr(1),
+			FuelUnit:                  stringPtr(beforeflightinspection.FuelUnitLT),
+			FuelAddedAmount:           floatPtr(0),
+			FileChecklist:             []requestdto.ReserveAcFileChecklistItem{},
+		},
+		Prepare: requestdto.ReserveAcPrepareInspectionAttributes{
+			NotamBriefing:         boolPtr(true),
+			WeatherBriefing:       boolPtr(true),
+			OperationalFlightPlan: boolPtr(false),
+			FileChecklist:         []requestdto.ReserveAcFileChecklistItem{},
+		},
+	}
+
+	gotID, err := newChecklistTestService(db).upsertTakeoverInspectionTx(db, nil, inspectionID, req, helicopterID, uuidv7.MustBytes())
+	if err != nil {
+		t.Fatalf("expected update inspection with empty file_checklists to pass, got %v", err)
+	}
+	if string(gotID) != string(inspectionID) {
+		t.Fatalf("unexpected inspection id: %x", gotID)
+	}
+
+	var checklistCount int64
+	if err := db.Table("flight_inspection_file_checklists").Count(&checklistCount).Error; err != nil {
+		t.Fatalf("count file checklists: %v", err)
+	}
+	if checklistCount != 0 {
+		t.Fatalf("expected no checklist rows to be created on empty update, got %d", checklistCount)
+	}
+}
+
+func boolPtr(v bool) *bool { return &v }
+
+func floatPtr(v float64) *float64 { return &v }
+
+func stringPtr(v string) *string { return &v }
+
+func TestUpsertTakeoverChecklistItemsTxAllowsEmptyTemplateAndEmptyPayload(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	inspectionID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+
+	err := newChecklistTestService(db).upsertTakeoverChecklistItemsTx(db, inspectionID, helicopterID, "fpwb", nil, uuidv7.MustBytes())
+	if err != nil {
+		t.Fatalf("expected empty template and empty payload to pass, got %v", err)
+	}
+}
+
+func TestUpsertTakeoverChecklistItemsTxRejectsItemsWhenTemplateMissing(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	inspectionID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	fileIDStr, _ := uuidv7.BytesToString(fileID)
+
+	err := newChecklistTestService(db).upsertTakeoverChecklistItemsTx(db, inspectionID, helicopterID, "fpwb", []requestdto.ReserveAcFileChecklistItem{{
+		HelicopterFileID: fileIDStr,
+		IsDone:           true,
+	}}, uuidv7.MustBytes())
+	if err == nil {
+		t.Fatal("expected error when template is missing and payload has items")
+	}
+	if !strings.Contains(err.Error(), "inspection checklist template is empty for section fpwb") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestUpsertTakeoverChecklistItemsTxAllowsOptionalFalseButRequiresMandatoryTrue(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	inspectionID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	now := time.Now().UTC()
+
+	mandatoryFile := helicopterfile.HelicopterFile{
+		ID:               uuidv7.MustBytes(),
+		Section:          "fpwb",
+		Position:         1,
+		IsMandatory:      true,
+		HelicopterID:     helicopterID,
+		FileAttachmentID: uuidv7.MustBytes(),
+		CreatedAt:        now,
+		UpdatedAt:        now,
+	}
+	optionalFile := helicopterfile.HelicopterFile{
+		ID:               uuidv7.MustBytes(),
+		Section:          "fpwb",
+		Position:         2,
+		IsMandatory:      false,
+		HelicopterID:     helicopterID,
+		FileAttachmentID: uuidv7.MustBytes(),
+		CreatedAt:        now,
+		UpdatedAt:        now,
+	}
+	if err := db.Create(&mandatoryFile).Error; err != nil {
+		t.Fatalf("create mandatory file: %v", err)
+	}
+	if err := db.Create(&optionalFile).Error; err != nil {
+		t.Fatalf("create optional file: %v", err)
+	}
+
+	mandatoryIDStr, _ := uuidv7.BytesToString(mandatoryFile.ID)
+	optionalIDStr, _ := uuidv7.BytesToString(optionalFile.ID)
+	err := newChecklistTestService(db).upsertTakeoverChecklistItemsTx(db, inspectionID, helicopterID, "fpwb", []requestdto.ReserveAcFileChecklistItem{
+		{HelicopterFileID: mandatoryIDStr, IsDone: true},
+		{HelicopterFileID: optionalIDStr, IsDone: false},
+	}, uuidv7.MustBytes())
+	if err != nil {
+		t.Fatalf("expected optional false to pass, got %v", err)
+	}
+
+	err = newChecklistTestService(db).upsertTakeoverChecklistItemsTx(db, inspectionID, helicopterID, "fpwb", []requestdto.ReserveAcFileChecklistItem{
+		{HelicopterFileID: mandatoryIDStr, IsDone: false},
+		{HelicopterFileID: optionalIDStr, IsDone: false},
+	}, uuidv7.MustBytes())
+	if err == nil {
+		t.Fatal("expected mandatory false to fail")
+	}
+	if !strings.Contains(err.Error(), "must be fully checked") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestUpsertTakeoverChecklistItemsTxAllowsPartialChecklist(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	inspectionID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	now := time.Now().UTC()
+
+	mandatoryFile := helicopterfile.HelicopterFile{
+		ID: uuidv7.MustBytes(), Section: "fpwb", Position: 1, IsMandatory: true,
+		HelicopterID: helicopterID, FileAttachmentID: uuidv7.MustBytes(), CreatedAt: now, UpdatedAt: now,
+	}
+	optionalFile := helicopterfile.HelicopterFile{
+		ID: uuidv7.MustBytes(), Section: "fpwb", Position: 2, IsMandatory: false,
+		HelicopterID: helicopterID, FileAttachmentID: uuidv7.MustBytes(), CreatedAt: now, UpdatedAt: now,
+	}
+	if err := db.Create(&mandatoryFile).Error; err != nil {
+		t.Fatalf("create mandatory file: %v", err)
+	}
+	if err := db.Create(&optionalFile).Error; err != nil {
+		t.Fatalf("create optional file: %v", err)
+	}
+
+	optionalIDStr, _ := uuidv7.BytesToString(optionalFile.ID)
+
+	// Submit ONLY the optional file; the unedited mandatory catalog file may be
+	// omitted from the checklist (no more "must include all helicopter files").
+	if err := newChecklistTestService(db).upsertTakeoverChecklistItemsTx(db, inspectionID, helicopterID, "fpwb", []requestdto.ReserveAcFileChecklistItem{
+		{HelicopterFileID: optionalIDStr, IsDone: true},
+	}, uuidv7.MustBytes()); err != nil {
+		t.Fatalf("expected partial checklist omitting non-edited files to pass, got %v", err)
+	}
+
+	// Only the submitted item is recorded.
+	var count int64
+	if err := db.Table("flight_inspection_file_checklists").Where("flight_inspection_id = ?", inspectionID).Count(&count).Error; err != nil {
+		t.Fatalf("count checklist rows: %v", err)
+	}
+	if count != 1 {
+		t.Fatalf("expected exactly 1 checklist row, got %d", count)
+	}
+
+	// A mandatory file that IS submitted but not done is still rejected.
+	mandatoryIDStr, _ := uuidv7.BytesToString(mandatoryFile.ID)
+	if err := newChecklistTestService(db).upsertTakeoverChecklistItemsTx(db, inspectionID, helicopterID, "fpwb", []requestdto.ReserveAcFileChecklistItem{
+		{HelicopterFileID: mandatoryIDStr, IsDone: false},
+	}, uuidv7.MustBytes()); err == nil {
+		t.Fatal("expected submitted-but-undone mandatory file to be rejected")
+	}
+}
+
+func TestUpsertTakeoverChecklistItemsTxExcludesTemplateDerivedFiles(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	if err := db.AutoMigrate(&filemanager.File{}); err != nil {
+		t.Fatalf("migrate files: %v", err)
+	}
+	now := time.Now().UTC()
+	helicopterID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+
+	templateFileID := uuidv7.MustBytes()
+	derivedFileID := uuidv7.MustBytes()
+	folderID := uuidv7.MustBytes()
+	if err := db.Create(&filemanager.File{ID: templateFileID, FolderID: folderID, Name: "template.docx", ObjectKey: "k1", IsTemplate: true}).Error; err != nil {
+		t.Fatalf("create template file: %v", err)
+	}
+	// A document created from a template (has a non-empty template_uuid).
+	if err := db.Create(&filemanager.File{ID: derivedFileID, FolderID: folderID, Name: "from-template.docx", ObjectKey: "k2", TemplateUUID: uuidv7.MustBytes()}).Error; err != nil {
+		t.Fatalf("create derived file: %v", err)
+	}
+
+	templateRow := helicopterfile.HelicopterFile{
+		ID: uuidv7.MustBytes(), Section: "fpwb", Position: 1,
+		HelicopterID: helicopterID, SourceFileID: templateFileID, CreatedAt: now, UpdatedAt: now,
+	}
+	derivedRow := helicopterfile.HelicopterFile{
+		ID: uuidv7.MustBytes(), Section: "fpwb", Position: 2,
+		HelicopterID: helicopterID, SourceFileID: derivedFileID, CreatedAt: now, UpdatedAt: now,
+	}
+	if err := db.Create(&templateRow).Error; err != nil {
+		t.Fatalf("create template row: %v", err)
+	}
+	if err := db.Create(&derivedRow).Error; err != nil {
+		t.Fatalf("create derived row: %v", err)
+	}
+
+	templateIDStr, _ := uuidv7.BytesToString(templateRow.ID)
+	// Payload includes only the real template; the template-derived row must not be
+	// required by the checklist completeness check.
+	if err := newChecklistTestService(db).upsertTakeoverChecklistItemsTx(db, inspectionID, helicopterID, "fpwb", []requestdto.ReserveAcFileChecklistItem{
+		{HelicopterFileID: templateIDStr, IsDone: true},
+	}, uuidv7.MustBytes()); err != nil {
+		t.Fatalf("expected success when only the template is checked, got %v", err)
+	}
+}
+
+func TestValidateTakeoverEditedTemplateFilesTx(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	if err := db.AutoMigrate(&filemanager.File{}); err != nil {
+		t.Fatalf("migrate files: %v", err)
+	}
+	svc := newChecklistTestService(db)
+	takeoverID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	folderID := uuidv7.MustBytes()
+	now := time.Now().UTC()
+
+	// template_uuid on a from-template document == the source HelicopterFile.ID
+	// that a checklist item's helicopter_file_id references.
+	editedTemplateA := uuidv7.MustBytes()
+	editedTemplateB := uuidv7.MustBytes()
+	if err := db.Create(&helicopterfile.HelicopterFile{
+		ID:           editedTemplateA,
+		Section:      helicopterfile.SectionFlightPreparationAndWB,
+		HelicopterID: helicopterID,
+		SourceFileID: uuidv7.MustBytes(),
+		CreatedAt:    now,
+		UpdatedAt:    now,
+	}).Error; err != nil {
+		t.Fatalf("create checklist template A: %v", err)
+	}
+	if err := db.Create(&helicopterfile.HelicopterFile{
+		ID:           editedTemplateB,
+		Section:      helicopterfile.SectionFlightPreparationAndWB,
+		HelicopterID: helicopterID,
+		SourceFileID: uuidv7.MustBytes(),
+		CreatedAt:    now,
+		UpdatedAt:    now,
+	}).Error; err != nil {
+		t.Fatalf("create checklist template B: %v", err)
+	}
+
+	// Two documents edited/created from a template for this takeover.
+	if err := db.Create(&filemanager.File{ID: uuidv7.MustBytes(), FolderID: folderID, Name: "a.docx", ObjectKey: "a", TemplateUUID: editedTemplateA, TakeoverID: takeoverID}).Error; err != nil {
+		t.Fatalf("create edited file A: %v", err)
+	}
+	if err := db.Create(&filemanager.File{ID: uuidv7.MustBytes(), FolderID: folderID, Name: "b.docx", ObjectKey: "b", TemplateUUID: editedTemplateB, TakeoverID: takeoverID}).Error; err != nil {
+		t.Fatalf("create edited file B: %v", err)
+	}
+	// A from-template document for a different takeover must be ignored.
+	if err := db.Create(&filemanager.File{ID: uuidv7.MustBytes(), FolderID: folderID, Name: "other.docx", ObjectKey: "o", TemplateUUID: uuidv7.MustBytes(), TakeoverID: uuidv7.MustBytes()}).Error; err != nil {
+		t.Fatalf("create other-takeover file: %v", err)
+	}
+
+	aStr, _ := uuidv7.BytesToString(editedTemplateA)
+	bStr, _ := uuidv7.BytesToString(editedTemplateB)
+	unrelatedStr, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+
+	// 1) Checklist missing an edited file (B) -> reject.
+	if err := svc.validateTakeoverEditedTemplateFilesTx(db, takeoverID, helicopterID, []requestdto.ReserveAcFileChecklistItem{
+		{HelicopterFileID: aStr, IsDone: true},
+	}); err == nil {
+		t.Fatalf("expected rejection when an edited file is missing from the checklist")
+	}
+
+	// 2) Edited files exist but checklist is empty -> reject.
+	if err := svc.validateTakeoverEditedTemplateFilesTx(db, takeoverID, helicopterID, nil); err == nil {
+		t.Fatalf("expected rejection when edited files exist but checklist is empty")
+	}
+
+	// 3) Checklist includes both edited files plus an unrelated (non-edited)
+	//    item -> success; a checklist item that was not edited is fine.
+	if err := svc.validateTakeoverEditedTemplateFilesTx(db, takeoverID, helicopterID, []requestdto.ReserveAcFileChecklistItem{
+		{HelicopterFileID: aStr, IsDone: true},
+		{HelicopterFileID: bStr, IsDone: true},
+		{HelicopterFileID: unrelatedStr, IsDone: false},
+	}); err != nil {
+		t.Fatalf("expected success when all edited files are in the checklist, got %v", err)
+	}
+
+	// 4) No edited files for the takeover -> success regardless of checklist.
+	if err := svc.validateTakeoverEditedTemplateFilesTx(db, uuidv7.MustBytes(), uuidv7.MustBytes(), nil); err != nil {
+		t.Fatalf("expected success when there are no edited files, got %v", err)
+	}
+
+	// 5) A template-derived file that has already been trashed should not block
+	//    an inspection update when it is no longer part of the active takeover set.
+	trashedTemplate := uuidv7.MustBytes()
+	trashedTakeoverID := uuidv7.MustBytes()
+	if err := db.Create(&filemanager.File{
+		ID:           uuidv7.MustBytes(),
+		FolderID:     folderID,
+		Name:         "trashed.docx",
+		ObjectKey:    "trashed",
+		TemplateUUID: trashedTemplate,
+		TakeoverID:   trashedTakeoverID,
+		Status:       filemanager.FileStatusTrashed,
+	}).Error; err != nil {
+		t.Fatalf("create trashed edited file: %v", err)
+	}
+	if err := svc.validateTakeoverEditedTemplateFilesTx(db, trashedTakeoverID, helicopterID, nil); err != nil {
+		t.Fatalf("expected trashed edited file to be ignored, got %v", err)
+	}
+}
+
+func TestValidateTakeoverEditedTemplateFilesTxAcceptsLegacySourceFileReferences(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	if err := db.AutoMigrate(&filemanager.File{}); err != nil {
+		t.Fatalf("migrate files: %v", err)
+	}
+	svc := newChecklistTestService(db)
+	takeoverID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	folderID := uuidv7.MustBytes()
+	now := time.Now().UTC()
+
+	sourceFileID := uuidv7.MustBytes()
+	templateHeliFileID := uuidv7.MustBytes()
+	if err := db.Create(&filemanager.File{
+		ID:        sourceFileID,
+		FolderID:  folderID,
+		Name:      "template.xlsx",
+		ObjectKey: "template.xlsx",
+	}).Error; err != nil {
+		t.Fatalf("create source template file: %v", err)
+	}
+	if err := db.Create(&helicopterfile.HelicopterFile{
+		ID:           templateHeliFileID,
+		Section:      helicopterfile.SectionFlightPreparationAndWB,
+		HelicopterID: helicopterID,
+		SourceFileID: sourceFileID,
+		CreatedAt:    now,
+		UpdatedAt:    now,
+	}).Error; err != nil {
+		t.Fatalf("create helicopter template row: %v", err)
+	}
+
+	// Legacy data may have template_uuid pointing to the source file ID instead
+	// of the helicopter_file ID shown in the checklist payload.
+	if err := db.Create(&filemanager.File{
+		ID:           uuidv7.MustBytes(),
+		FolderID:     folderID,
+		Name:         "draft.xlsx",
+		ObjectKey:    "draft.xlsx",
+		TemplateUUID: sourceFileID,
+		TakeoverID:   takeoverID,
+	}).Error; err != nil {
+		t.Fatalf("create legacy edited file: %v", err)
+	}
+
+	templateChecklistID, _ := uuidv7.BytesToString(templateHeliFileID)
+	if err := svc.validateTakeoverEditedTemplateFilesTx(db, takeoverID, helicopterID, []requestdto.ReserveAcFileChecklistItem{
+		{HelicopterFileID: templateChecklistID, IsDone: true},
+	}); err != nil {
+		t.Fatalf("expected legacy source file template_uuid to map back to checklist template, got %v", err)
+	}
+}
+
+func TestValidateTakeoverEditedTemplateFilesTxIgnoresOrphanedTemplateReferences(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	if err := db.AutoMigrate(&filemanager.File{}); err != nil {
+		t.Fatalf("migrate files: %v", err)
+	}
+	svc := newChecklistTestService(db)
+	takeoverID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	folderID := uuidv7.MustBytes()
+
+	if err := db.Create(&filemanager.File{
+		ID:           uuidv7.MustBytes(),
+		FolderID:     folderID,
+		Name:         "orphaned-draft.xlsx",
+		ObjectKey:    "orphaned-draft.xlsx",
+		TemplateUUID: uuidv7.MustBytes(),
+		TakeoverID:   takeoverID,
+	}).Error; err != nil {
+		t.Fatalf("create orphaned edited file: %v", err)
+	}
+
+	if err := svc.validateTakeoverEditedTemplateFilesTx(db, takeoverID, helicopterID, nil); err != nil {
+		t.Fatalf("expected orphaned historical template reference to be ignored, got %v", err)
+	}
+}
+
+func TestResolveBaseShiftRangeTxPrefersOperationalShiftTime(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	now := time.Now().UTC()
+	category := &base.BaseCategory{ID: uuidv7.MustBytes(), Key: base.CategoryKeyRegular, Name: "Regular", CreatedAt: now, UpdatedAt: now}
+	if err := db.Create(category).Error; err != nil {
+		t.Fatalf("create category: %v", err)
+	}
+	defaultStart := time.Date(1900, 1, 1, 9, 0, 0, 0, time.UTC)
+	defaultEnd := time.Date(1900, 1, 1, 18, 0, 0, 0, time.UTC)
+	baseID := uuidv7.MustBytes()
+	row := &base.Base{
+		ID:                baseID,
+		BaseCategoryID:    category.ID,
+		BaseName:          "Base A",
+		DefaultShiftStart: defaultStart.Format("15:04:05"),
+		DefaultShiftEnd:   defaultEnd.Format("15:04:05"),
+		CreatedAt:         now,
+		UpdatedAt:         now,
+	}
+	if err := db.Create(row).Error; err != nil {
+		t.Fatalf("create base: %v", err)
+	}
+	opStart := time.Date(1900, 1, 1, 9, 0, 0, 0, time.UTC)
+	opEnd := time.Date(1900, 1, 1, 17, 0, 0, 0, time.UTC)
+	opDate := time.Date(2026, 4, 12, 0, 0, 0, 0, time.UTC)
+	opRow := &base.BaseOperationalShiftTime{
+		ID:         uuidv7.MustBytes(),
+		BaseID:     baseID,
+		DateStart:  &opDate,
+		DateEnd:    &opDate,
+		ShiftStart: opStart.Format("15:04:05"),
+		ShiftEnd:   opEnd.Format("15:04:05"),
+		CreatedAt:  now,
+		UpdatedAt:  now,
+	}
+	if err := db.Create(opRow).Error; err != nil {
+		t.Fatalf("create operational shift: %v", err)
+	}
+
+	start, end, err := ResolveBaseShiftRangeTx(db, baseID, time.Date(2026, 4, 12, 0, 0, 0, 0, time.UTC))
+	if err != nil {
+		t.Fatalf("resolve shift: %v", err)
+	}
+	if start != "09:00" || end != "17:00" {
+		t.Fatalf("unexpected operational shift: start=%s end=%s", start, end)
+	}
+}
+
+func TestResolveBaseShiftRangeTxFallsBackToDefaultShiftTime(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	now := time.Now().UTC()
+	category := &base.BaseCategory{ID: uuidv7.MustBytes(), Key: base.CategoryKeyRegular, Name: "Regular", CreatedAt: now, UpdatedAt: now}
+	if err := db.Create(category).Error; err != nil {
+		t.Fatalf("create category: %v", err)
+	}
+	defaultStart := time.Date(1900, 1, 1, 9, 0, 0, 0, time.UTC)
+	defaultEnd := time.Date(1900, 1, 1, 18, 0, 0, 0, time.UTC)
+	baseID := uuidv7.MustBytes()
+	row := &base.Base{
+		ID:                baseID,
+		BaseCategoryID:    category.ID,
+		BaseName:          "Base B",
+		DefaultShiftStart: defaultStart.Format("15:04:05"),
+		DefaultShiftEnd:   defaultEnd.Format("15:04:05"),
+		CreatedAt:         now,
+		UpdatedAt:         now,
+	}
+	if err := db.Create(row).Error; err != nil {
+		t.Fatalf("create base: %v", err)
+	}
+
+	start, end, err := ResolveBaseShiftRangeTx(db, baseID, time.Date(2026, 4, 13, 0, 0, 0, 0, time.UTC))
+	if err != nil {
+		t.Fatalf("resolve shift: %v", err)
+	}
+	if start != "09:00" || end != "18:00" {
+		t.Fatalf("unexpected default shift: start=%s end=%s", start, end)
+	}
+}
+
+func TestResolveBaseShiftRangeTxResolvesBMCTECETFromCoordinates(t *testing.T) {
+	db := openTakeoverServiceTestDB(t)
+	now := time.Now().UTC()
+	category := &base.BaseCategory{ID: uuidv7.MustBytes(), Key: base.CategoryKeyRegular, Name: "Regular", CreatedAt: now, UpdatedAt: now}
+	if err := db.Create(category).Error; err != nil {
+		t.Fatalf("create category: %v", err)
+	}
+	baseID := uuidv7.MustBytes()
+	row := &base.Base{
+		ID:                   baseID,
+		BaseCategoryID:       category.ID,
+		BaseName:             "Base C",
+		Latitude:             47.3769,
+		Longitude:            8.5417,
+		DefaultStartTimeType: base.ShiftTimeTypeBMCT,
+		DefaultEndTimeType:   base.ShiftTimeTypeECET,
+		CreatedAt:            now,
+		UpdatedAt:            now,
+	}
+	if err := db.Create(row).Error; err != nil {
+		t.Fatalf("create base: %v", err)
+	}
+
+	start, end, err := ResolveBaseShiftRangeTx(db, baseID, time.Date(2026, 4, 13, 0, 0, 0, 0, time.UTC))
+	if err != nil {
+		t.Fatalf("resolve shift: %v", err)
+	}
+	if strings.TrimSpace(start) == "" || strings.TrimSpace(end) == "" {
+		t.Fatalf("expected resolved BMCT/ECET shift, got start=%q end=%q", start, end)
+	}
+	if start == "09:00:00" || end == "18:00:00" {
+		t.Fatalf("expected computed twilight times, got fixed-looking values start=%s end=%s", start, end)
+	}
+}
diff --git a/internal/service/user_service.go b/internal/service/user_service.go
new file mode 100644
index 0000000..18e3388
--- /dev/null
+++ b/internal/service/user_service.go
@@ -0,0 +1,53 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/user"
+)
+
+type UserService struct {
+	repo user.Repository
+}
+
+func NewUserService(repo user.Repository) *UserService {
+	return &UserService{repo: repo}
+}
+
+func (s *UserService) Create(ctx context.Context, u *user.User) error {
+	return s.repo.Create(ctx, u)
+}
+
+func (s *UserService) Update(ctx context.Context, u *user.User) error {
+	return s.repo.Update(ctx, u)
+}
+
+func (s *UserService) Delete(ctx context.Context, id []byte) error {
+	return s.repo.Delete(ctx, id)
+}
+
+func (s *UserService) GetByID(ctx context.Context, id []byte) (*user.User, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *UserService) GetByEmail(ctx context.Context, email string) (*user.User, error) {
+	return s.repo.GetByEmail(ctx, email)
+}
+
+func (s *UserService) GetByUsername(ctx context.Context, username string) (*user.User, error) {
+	return s.repo.GetByUsername(ctx, username)
+}
+
+func (s *UserService) List(ctx context.Context, filter string, sort string, limit, offset int) ([]user.User, int64, error) {
+	return s.repo.List(ctx, filter, normalizeUserSort(sort), limit, offset)
+}
+
+func normalizeUserSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortField("users.email", "email"),
+		sortField("users.first_name", "first_name"),
+		sortField("users.last_name", "last_name"),
+		sortField("users.created_at", "created_at"),
+		sortField("users.updated_at", "updated_at"),
+	)
+}
diff --git a/internal/service/user_service_test.go b/internal/service/user_service_test.go
new file mode 100644
index 0000000..6541331
--- /dev/null
+++ b/internal/service/user_service_test.go
@@ -0,0 +1,185 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/user"
+)
+
+type userRepoMock struct {
+	createErr        error
+	updateErr        error
+	deleteErr        error
+	getByIDErr       error
+	getByEmailErr    error
+	getByUsernameErr error
+	listErr          error
+
+	gotCreate        *user.User
+	gotUpdate        *user.User
+	gotDelete        []byte
+	gotGetByID       []byte
+	gotGetByEmail    string
+	gotGetByUsername string
+	gotListFilter    string
+	gotListSort      string
+	gotListLimit     int
+	gotListOffset    int
+
+	retByID       *user.User
+	retByEmail    *user.User
+	retByUsername *user.User
+	retList       []user.User
+	retTotal      int64
+}
+
+func (m *userRepoMock) Create(_ context.Context, u *user.User) error {
+	m.gotCreate = u
+	return m.createErr
+}
+func (m *userRepoMock) Update(_ context.Context, u *user.User) error {
+	m.gotUpdate = u
+	return m.updateErr
+}
+func (m *userRepoMock) Delete(_ context.Context, id []byte) error {
+	m.gotDelete = id
+	return m.deleteErr
+}
+func (m *userRepoMock) GetByID(_ context.Context, id []byte) (*user.User, error) {
+	m.gotGetByID = id
+	return m.retByID, m.getByIDErr
+}
+func (m *userRepoMock) GetByEmail(_ context.Context, email string) (*user.User, error) {
+	m.gotGetByEmail = email
+	return m.retByEmail, m.getByEmailErr
+}
+func (m *userRepoMock) GetByUsername(_ context.Context, username string) (*user.User, error) {
+	m.gotGetByUsername = username
+	return m.retByUsername, m.getByUsernameErr
+}
+func (m *userRepoMock) List(_ context.Context, filter, sort string, limit, offset int) ([]user.User, int64, error) {
+	m.gotListFilter = filter
+	m.gotListSort = sort
+	m.gotListLimit = limit
+	m.gotListOffset = offset
+	return m.retList, m.retTotal, m.listErr
+}
+
+func (m *userRepoMock) GetLastNameByID(_ context.Context, _ []byte) (string, error) {
+	return "", nil
+}
+
+func TestUserService_CRUDAndGet(t *testing.T) {
+	repo := &userRepoMock{}
+	svc := NewUserService(repo)
+
+	u := &user.User{Email: "u@e.com"}
+	if err := svc.Create(context.Background(), u); err != nil {
+		t.Fatalf("create: %v", err)
+	}
+	if repo.gotCreate != u {
+		t.Fatalf("expected create arg passed")
+	}
+
+	if err := svc.Update(context.Background(), u); err != nil {
+		t.Fatalf("update: %v", err)
+	}
+	if repo.gotUpdate != u {
+		t.Fatalf("expected update arg passed")
+	}
+
+	id := []byte("id")
+	if err := svc.Delete(context.Background(), id); err != nil {
+		t.Fatalf("delete: %v", err)
+	}
+	if string(repo.gotDelete) != string(id) {
+		t.Fatalf("expected delete id passed")
+	}
+
+	repo.retByID = u
+	got, err := svc.GetByID(context.Background(), id)
+	if err != nil || got != u {
+		t.Fatalf("getByID failed")
+	}
+
+	repo.retByEmail = u
+	got, err = svc.GetByEmail(context.Background(), "u@e.com")
+	if err != nil || got != u {
+		t.Fatalf("getByEmail failed")
+	}
+
+	repo.retByUsername = u
+	got, err = svc.GetByUsername(context.Background(), "john")
+	if err != nil || got != u {
+		t.Fatalf("getByUsername failed")
+	}
+}
+
+func TestUserService_RepoErrors(t *testing.T) {
+	repo := &userRepoMock{
+		createErr:        errors.New("e"),
+		updateErr:        errors.New("e"),
+		deleteErr:        errors.New("e"),
+		getByIDErr:       errors.New("e"),
+		getByEmailErr:    errors.New("e"),
+		getByUsernameErr: errors.New("e"),
+		listErr:          errors.New("e"),
+	}
+	svc := NewUserService(repo)
+	if svc.Create(context.Background(), &user.User{}) == nil {
+		t.Fatalf("expected create err")
+	}
+	if svc.Update(context.Background(), &user.User{}) == nil {
+		t.Fatalf("expected update err")
+	}
+	if svc.Delete(context.Background(), []byte("id")) == nil {
+		t.Fatalf("expected delete err")
+	}
+	if _, err := svc.GetByID(context.Background(), []byte("id")); err == nil {
+		t.Fatalf("expected getByID err")
+	}
+	if _, err := svc.GetByEmail(context.Background(), "u@e.com"); err == nil {
+		t.Fatalf("expected getByEmail err")
+	}
+	if _, err := svc.GetByUsername(context.Background(), "john"); err == nil {
+		t.Fatalf("expected getByUsername err")
+	}
+	if _, _, err := svc.List(context.Background(), "", "", 1, 0); err == nil {
+		t.Fatalf("expected list err")
+	}
+}
+
+func TestUserService_ListAndNormalizeSort(t *testing.T) {
+	repo := &userRepoMock{retList: []user.User{{Email: "u@e.com"}}, retTotal: 1}
+	svc := NewUserService(repo)
+
+	_, _, err := svc.List(context.Background(), "u", "-email", 10, 20)
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if repo.gotListSort != "users.email DESC" {
+		t.Fatalf("unexpected sort: %s", repo.gotListSort)
+	}
+
+	cases := map[string]string{
+		"email":       "users.email ASC",
+		"-email":      "users.email DESC",
+		"first_name":  "users.first_name ASC",
+		"-first_name": "users.first_name DESC",
+		"last_name":   "users.last_name ASC",
+		"-last_name":  "users.last_name DESC",
+		"created_at":  "users.created_at ASC",
+		"-created_at": "users.created_at DESC",
+		"updated_at":  "users.updated_at ASC",
+		"-updated_at": "users.updated_at DESC",
+		"bad":         "",
+		"":            "",
+	}
+	for in, want := range cases {
+		if got := normalizeUserSort(in); got != want {
+			t.Fatalf("normalizeUserSort(%q)=%q want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/user_write_service.go b/internal/service/user_write_service.go
new file mode 100644
index 0000000..3d9e22f
--- /dev/null
+++ b/internal/service/user_write_service.go
@@ -0,0 +1,160 @@
+package service
+
+import (
+	"context"
+	"net/http"
+	"strings"
+
+	"wucher/internal/domain/user"
+)
+
+type UserWriteError struct {
+	Status  int
+	Title   string
+	Detail  string
+	Pointer string
+}
+
+func (e *UserWriteError) Error() string {
+	if e == nil {
+		return ""
+	}
+	return e.Detail
+}
+
+type UserWriteResult struct {
+	Row                         *user.User
+	PreviousProfileAttachmentID []byte
+}
+
+type UserCreateInput struct {
+	ID                  []byte
+	Email               string
+	Username            string
+	FirstName           string
+	LastName            string
+	MobilePhone         string
+	Timezone            string
+	RoleID              []byte
+	RoleIDs             [][]byte
+	ProfileAttachmentID []byte
+	CreatedBy           []byte
+	UpdatedBy           []byte
+}
+
+type UserUpdateInput struct {
+	ID                   []byte
+	Email                *string
+	FirstName            *string
+	LastName             *string
+	MobilePhone          *string
+	Timezone             *string
+	ProfileAttachmentSet bool
+	ProfileAttachmentID  []byte
+	ActorUserID          []byte
+}
+
+func (s *UserService) CreateDetailed(ctx context.Context, in UserCreateInput) (*UserWriteResult, error) {
+	if s == nil || s.repo == nil {
+		return nil, &UserWriteError{Status: http.StatusInternalServerError, Title: "Create failed", Detail: "user service is not configured"}
+	}
+	email := strings.TrimSpace(in.Email)
+	username := strings.TrimSpace(in.Username)
+	firstName := strings.TrimSpace(in.FirstName)
+	lastName := strings.TrimSpace(in.LastName)
+	if email == "" || username == "" || firstName == "" || lastName == "" {
+		return nil, &UserWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "email, username, first_name, and last_name are required", Pointer: "/data/attributes"}
+	}
+	row := &user.User{
+		ID:                  append([]byte(nil), in.ID...),
+		Email:               email,
+		Username:            username,
+		FirstName:           firstName,
+		LastName:            lastName,
+		MobilePhone:         strings.TrimSpace(in.MobilePhone),
+		Timezone:            strings.TrimSpace(in.Timezone),
+		RoleID:              append([]byte(nil), in.RoleID...),
+		RoleIDs:             appendUniqueIDs(in.RoleIDs),
+		ProfileAttachmentID: append([]byte(nil), in.ProfileAttachmentID...),
+		ImageAttachmentID:   append([]byte(nil), in.ProfileAttachmentID...),
+		CreatedBy:           append([]byte(nil), in.CreatedBy...),
+		UpdatedBy:           append([]byte(nil), in.UpdatedBy...),
+	}
+	if err := s.Create(ctx, row); err != nil {
+		return nil, &UserWriteError{Status: http.StatusBadRequest, Title: "Create failed", Detail: err.Error()}
+	}
+	created, err := s.GetByID(ctx, row.ID)
+	if err != nil {
+		return nil, &UserWriteError{Status: http.StatusBadRequest, Title: "Create failed", Detail: err.Error()}
+	}
+	if created == nil {
+		created = row
+	}
+	return &UserWriteResult{Row: created}, nil
+}
+
+func (s *UserService) UpdateDetailed(ctx context.Context, in UserUpdateInput) (*UserWriteResult, error) {
+	if s == nil || s.repo == nil {
+		return nil, &UserWriteError{Status: http.StatusInternalServerError, Title: "Update failed", Detail: "user service is not configured"}
+	}
+	if len(in.ID) != 16 {
+		return nil, &UserWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "uuid is invalid UUID", Pointer: "/path/uuid"}
+	}
+
+	existing, err := s.GetByID(ctx, in.ID)
+	if err != nil || existing == nil {
+		return nil, &UserWriteError{Status: http.StatusNotFound, Title: "Not found", Detail: "user not found"}
+	}
+	prevProfileAttachmentID := append([]byte(nil), existing.ProfileAttachmentID...)
+
+	if in.Email != nil {
+		email := strings.TrimSpace(*in.Email)
+		if email == "" {
+			return nil, &UserWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "email cannot be empty", Pointer: "/data/attributes/email"}
+		}
+		existing.Email = email
+	}
+	if in.FirstName != nil {
+		firstName := strings.TrimSpace(*in.FirstName)
+		if firstName == "" {
+			return nil, &UserWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "first_name cannot be empty", Pointer: "/data/attributes/first_name"}
+		}
+		existing.FirstName = firstName
+	}
+	if in.LastName != nil {
+		lastName := strings.TrimSpace(*in.LastName)
+		if lastName == "" {
+			return nil, &UserWriteError{Status: http.StatusUnprocessableEntity, Title: "Validation error", Detail: "last_name cannot be empty", Pointer: "/data/attributes/last_name"}
+		}
+		existing.LastName = lastName
+	}
+	if in.MobilePhone != nil {
+		existing.MobilePhone = strings.TrimSpace(*in.MobilePhone)
+	}
+	if in.Timezone != nil {
+		existing.Timezone = strings.TrimSpace(*in.Timezone)
+	}
+	if in.ProfileAttachmentSet {
+		if len(in.ProfileAttachmentID) == 0 {
+			existing.ProfileAttachmentID = nil
+			existing.ImageAttachmentID = nil
+		} else {
+			existing.ProfileAttachmentID = append([]byte(nil), in.ProfileAttachmentID...)
+			existing.ImageAttachmentID = append([]byte(nil), in.ProfileAttachmentID...)
+		}
+		existing.ProfileAttachmentPatchSet = true
+	}
+	existing.UpdatedBy = append([]byte(nil), in.ActorUserID...)
+
+	if err := s.Update(ctx, existing); err != nil {
+		return nil, &UserWriteError{Status: http.StatusBadRequest, Title: "Update failed", Detail: err.Error()}
+	}
+	updated, err := s.GetByID(ctx, existing.ID)
+	if err != nil {
+		return nil, &UserWriteError{Status: http.StatusBadRequest, Title: "Update failed", Detail: err.Error()}
+	}
+	if updated == nil {
+		updated = existing
+	}
+	return &UserWriteResult{Row: updated, PreviousProfileAttachmentID: prevProfileAttachmentID}, nil
+}
diff --git a/internal/service/vocation_service.go b/internal/service/vocation_service.go
new file mode 100644
index 0000000..ecb5c95
--- /dev/null
+++ b/internal/service/vocation_service.go
@@ -0,0 +1,51 @@
+package service
+
+import (
+	"context"
+
+	"wucher/internal/domain/vocation"
+	"wucher/internal/shared/pkg/sortkey"
+)
+
+type VocationService struct {
+	repo vocation.Repository
+}
+
+func NewVocationService(repo vocation.Repository) *VocationService {
+	return &VocationService{repo: repo}
+}
+
+func (s *VocationService) Create(ctx context.Context, v *vocation.Vocation) error {
+	return s.repo.Create(ctx, v)
+}
+
+func (s *VocationService) Update(ctx context.Context, v *vocation.Vocation) error {
+	return s.repo.Update(ctx, v)
+}
+
+func (s *VocationService) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	return s.repo.Delete(ctx, id, deletedBy)
+}
+
+func (s *VocationService) GetByID(ctx context.Context, id []byte) (*vocation.Vocation, error) {
+	return s.repo.GetByID(ctx, id)
+}
+
+func (s *VocationService) List(ctx context.Context, filter, sort string, limit, offset int) ([]vocation.Vocation, int64, error) {
+	return s.repo.List(ctx, filter, normalizeVocationSort(sort), limit, offset)
+}
+
+func normalizeVocationSort(sort string) string {
+	return normalizeSortByRules(sort,
+		sortExpr(
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", false)),
+			joinSortClauses(sortkey.ActivePositiveSortClauses("", "is_active", "sortkey", "name", true)),
+			"sortkey",
+		),
+		sortField("name"),
+		sortField("note"),
+		sortField("is_active"),
+		sortField("created_at"),
+		sortField("updated_at"),
+	)
+}
diff --git a/internal/service/vocation_service_test.go b/internal/service/vocation_service_test.go
new file mode 100644
index 0000000..64f730b
--- /dev/null
+++ b/internal/service/vocation_service_test.go
@@ -0,0 +1,223 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"wucher/internal/domain/vocation"
+)
+
+type vocationRepoMock struct {
+	createCalled  bool
+	updateCalled  bool
+	deleteCalled  bool
+	getByIDCalled bool
+	listCalled    bool
+
+	lastCreate     *vocation.Vocation
+	lastUpdate     *vocation.Vocation
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastGetByID    []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+
+	getByIDResult *vocation.Vocation
+	listResult    []vocation.Vocation
+	listTotal     int64
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+}
+
+func (m *vocationRepoMock) Create(_ context.Context, o *vocation.Vocation) error {
+	m.createCalled = true
+	m.lastCreate = o
+	return m.createErr
+}
+
+func (m *vocationRepoMock) Update(_ context.Context, o *vocation.Vocation) error {
+	m.updateCalled = true
+	m.lastUpdate = o
+	return m.updateErr
+}
+
+func (m *vocationRepoMock) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	m.deleteCalled = true
+	m.lastDeleteID = id
+	m.lastDeleteBy = deletedBy
+	return m.deleteErr
+}
+
+func (m *vocationRepoMock) GetByID(_ context.Context, id []byte) (*vocation.Vocation, error) {
+	m.getByIDCalled = true
+	m.lastGetByID = id
+	return m.getByIDResult, m.getByIDErr
+}
+
+func (m *vocationRepoMock) List(_ context.Context, filter, sort string, limit, offset int) ([]vocation.Vocation, int64, error) {
+	m.listCalled = true
+	m.lastListFilter = filter
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listResult, m.listTotal, m.listErr
+}
+
+func TestNewVocationService(t *testing.T) {
+	repo := &vocationRepoMock{}
+	svc := NewVocationService(repo)
+	if svc == nil || svc.repo == nil {
+		t.Fatalf("expected service and repo initialized")
+	}
+}
+
+func TestVocationServiceCreate(t *testing.T) {
+	repo := &vocationRepoMock{}
+	svc := NewVocationService(repo)
+	row := &vocation.Vocation{Name: "Name"}
+
+	if err := svc.Create(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.createCalled || repo.lastCreate != row {
+		t.Fatalf("expected Create forwarded to repo")
+	}
+
+	repo.createErr = errors.New("create failed")
+	if err := svc.Create(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestVocationServiceUpdate(t *testing.T) {
+	repo := &vocationRepoMock{}
+	svc := NewVocationService(repo)
+	row := &vocation.Vocation{Name: "Updated"}
+
+	if err := svc.Update(context.Background(), row); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.updateCalled || repo.lastUpdate != row {
+		t.Fatalf("expected Update forwarded to repo")
+	}
+
+	repo.updateErr = errors.New("update failed")
+	if err := svc.Update(context.Background(), row); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestVocationServiceDelete(t *testing.T) {
+	repo := &vocationRepoMock{}
+	svc := NewVocationService(repo)
+	id := []byte("id")
+	deletedBy := []byte("by")
+
+	if err := svc.Delete(context.Background(), id, deletedBy); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !repo.deleteCalled {
+		t.Fatalf("expected Delete forwarded to repo")
+	}
+	if string(repo.lastDeleteID) != string(id) || string(repo.lastDeleteBy) != string(deletedBy) {
+		t.Fatalf("expected delete params forwarded")
+	}
+
+	repo.deleteErr = errors.New("delete failed")
+	if err := svc.Delete(context.Background(), id, deletedBy); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestVocationServiceGetByID(t *testing.T) {
+	expected := &vocation.Vocation{Name: "A"}
+	repo := &vocationRepoMock{getByIDResult: expected}
+	svc := NewVocationService(repo)
+	id := []byte("id")
+
+	got, err := svc.GetByID(context.Background(), id)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != expected {
+		t.Fatalf("unexpected result")
+	}
+	if !repo.getByIDCalled || string(repo.lastGetByID) != string(id) {
+		t.Fatalf("expected GetByID forwarded")
+	}
+
+	repo.getByIDErr = errors.New("get failed")
+	if _, err := svc.GetByID(context.Background(), id); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestVocationServiceList(t *testing.T) {
+	repo := &vocationRepoMock{
+		listResult: []vocation.Vocation{{Name: "A"}},
+		listTotal:  1,
+	}
+	svc := NewVocationService(repo)
+
+	rows, total, err := svc.List(context.Background(), "find", "name", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if !repo.listCalled {
+		t.Fatalf("expected List forwarded to repo")
+	}
+	if repo.lastListFilter != "find" || repo.lastListSort != "name ASC" || repo.lastListLimit != 10 || repo.lastListOffset != 20 {
+		t.Fatalf("unexpected list args forwarded")
+	}
+
+	rows, total, err = svc.List(context.Background(), "find", "sortkey", 10, 20)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(rows) != 1 || total != 1 {
+		t.Fatalf("unexpected list result")
+	}
+	if repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC" {
+		t.Fatalf("unexpected sortkey args forwarded: %q", repo.lastListSort)
+	}
+
+	repo.listErr = errors.New("list failed")
+	if _, _, err := svc.List(context.Background(), "", "unknown", 1, 0); err == nil {
+		t.Fatalf("expected error from repo")
+	}
+}
+
+func TestNormalizeVocationSort(t *testing.T) {
+	cases := map[string]string{
+		"name":        "name ASC",
+		"-name":       "name DESC",
+		"sortkey":     "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC, name ASC",
+		"-sortkey":    "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC",
+		"note":        "note ASC",
+		"-note":       "note DESC",
+		"is_active":   "is_active ASC",
+		"-is_active":  "is_active DESC",
+		"created_at":  "created_at ASC",
+		"-created_at": "created_at DESC",
+		"updated_at":  "updated_at ASC",
+		"-updated_at": "updated_at DESC",
+		"unknown":     "",
+		"":            "",
+	}
+
+	for in, want := range cases {
+		if got := normalizeVocationSort(in); got != want {
+			t.Fatalf("normalizeVocationSort(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
diff --git a/internal/service/wopi_service.go b/internal/service/wopi_service.go
new file mode 100644
index 0000000..543c306
--- /dev/null
+++ b/internal/service/wopi_service.go
@@ -0,0 +1,385 @@
+package service
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type WOPIPermission string
+
+const (
+	WOPIPermissionRead  WOPIPermission = "read"
+	WOPIPermissionWrite WOPIPermission = "write"
+)
+
+type WOPIConfig struct {
+	TokenSecret   string
+	ProofSecret   string
+	DiscoveryURL  string
+	PublicBaseURL string
+	EditActionURL string
+	TokenTTL      time.Duration
+	MaxBodyBytes  int
+	RequireProof  bool
+}
+
+func LoadWOPIConfigFromEnv() WOPIConfig {
+	return WOPIConfig{
+		TokenSecret:   strings.TrimSpace(os.Getenv("WOPI_TOKEN_SECRET")),
+		ProofSecret:   strings.TrimSpace(os.Getenv("WOPI_PROOF_SECRET")),
+		DiscoveryURL:  strings.TrimSpace(os.Getenv("WOPI_DISCOVERY_URL")),
+		PublicBaseURL: strings.TrimSpace(os.Getenv("WOPI_PUBLIC_BASE_URL")),
+		EditActionURL: strings.TrimSpace(os.Getenv("WOPI_EDIT_ACTION_URL")),
+		TokenTTL:      envDuration("WOPI_TOKEN_TTL", 30*time.Minute),
+		MaxBodyBytes:  envInt("WOPI_MAX_BODY_BYTES", 8*1024*1024),
+		RequireProof:  envBool("WOPI_REQUIRE_PROOF", false),
+	}
+}
+
+type WOPIClaims struct {
+	jwt.RegisteredClaims
+	FileID     string `json:"file_id"`
+	UserID     string `json:"user_id"`
+	TakeoverID string `json:"takeover_id"`
+	Permission string `json:"permission"`
+}
+
+type wopiDiscoveryCache struct {
+	URLSrc string
+	Loaded time.Time
+}
+
+type WOPIService struct {
+	cfg       WOPIConfig
+	http      *http.Client
+	mu        sync.RWMutex
+	discovery wopiDiscoveryCache
+}
+
+func NewWOPIService(cfg WOPIConfig) *WOPIService {
+	if cfg.TokenTTL <= 0 {
+		cfg.TokenTTL = 30 * time.Minute
+	}
+	if cfg.MaxBodyBytes <= 0 {
+		cfg.MaxBodyBytes = 8 * 1024 * 1024
+	}
+	return &WOPIService{
+		cfg: cfg,
+		http: &http.Client{
+			Timeout: 10 * time.Second,
+		},
+	}
+}
+
+func (s *WOPIService) TokenTTL() time.Duration {
+	if s == nil || s.cfg.TokenTTL <= 0 {
+		return 30 * time.Minute
+	}
+	return s.cfg.TokenTTL
+}
+
+func (s *WOPIService) MaxBodyBytes() int {
+	if s == nil || s.cfg.MaxBodyBytes <= 0 {
+		return 8 * 1024 * 1024
+	}
+	return s.cfg.MaxBodyBytes
+}
+
+func (s *WOPIService) MintAccessToken(fileID, userID, takeoverID []byte, perm WOPIPermission) (string, int64, error) {
+	if s == nil || strings.TrimSpace(s.cfg.TokenSecret) == "" {
+		return "", 0, errors.New("wopi token secret is not configured")
+	}
+	if len(fileID) != 16 || len(userID) != 16 {
+		return "", 0, errors.New("invalid wopi token claims")
+	}
+	takeoverClaim := ""
+	if len(takeoverID) != 0 {
+		if len(takeoverID) != 16 {
+			return "", 0, errors.New("invalid wopi token claims")
+		}
+		takeoverClaim = uuidBytesString(takeoverID)
+	}
+	jti, err := randomToken(24)
+	if err != nil {
+		return "", 0, err
+	}
+	now := time.Now().UTC()
+	expiresAt := now.Add(s.TokenTTL())
+	claims := WOPIClaims{
+		RegisteredClaims: jwt.RegisteredClaims{
+			Subject:   uuidBytesString(userID),
+			ID:        jti,
+			IssuedAt:  jwt.NewNumericDate(now),
+			ExpiresAt: jwt.NewNumericDate(expiresAt),
+			NotBefore: jwt.NewNumericDate(now.Add(-1 * time.Minute)),
+			Audience:  jwt.ClaimStrings{"wopi"},
+		},
+		FileID:     uuidBytesString(fileID),
+		UserID:     uuidBytesString(userID),
+		TakeoverID: takeoverClaim,
+		Permission: string(perm),
+	}
+	token, err := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(s.cfg.TokenSecret))
+	if err != nil {
+		return "", 0, err
+	}
+	// WOPI/Collabora expects access_token_ttl as an ABSOLUTE expiry time in
+	// epoch milliseconds (equal to the JWT exp claim), not a duration. Returning
+	// the bare duration made Collabora read it as "1970-01-01 + ttl" and show
+	// "session expired" immediately.
+	return token, expiresAt.UnixMilli(), nil
+}
+
+func (s *WOPIService) VerifyAccessToken(token string, fileID []byte) (*WOPIClaims, error) {
+	if s == nil || strings.TrimSpace(s.cfg.TokenSecret) == "" {
+		return nil, errors.New("wopi token secret is not configured")
+	}
+	parsed, err := jwt.ParseWithClaims(strings.TrimSpace(token), &WOPIClaims{}, func(t *jwt.Token) (any, error) {
+		if t.Method.Alg() != jwt.SigningMethodHS256.Alg() {
+			return nil, errors.New("unexpected wopi token algorithm")
+		}
+		return []byte(s.cfg.TokenSecret), nil
+	}, jwt.WithLeeway(30*time.Second))
+	if err != nil {
+		return nil, err
+	}
+	claims, ok := parsed.Claims.(*WOPIClaims)
+	if !ok || claims == nil || !parsed.Valid {
+		return nil, errors.New("invalid wopi access token")
+	}
+	if !strings.EqualFold(strings.TrimSpace(claims.FileID), uuidBytesString(fileID)) {
+		return nil, errors.New("wopi token file mismatch")
+	}
+	return claims, nil
+}
+
+func (s *WOPIService) BuildActionURL(ctx context.Context, wopiSrc string) (string, error) {
+	urlSrc, err := s.discoveryURLSrc(ctx)
+	if err != nil {
+		return "", err
+	}
+	escaped := url.QueryEscape(strings.TrimSpace(wopiSrc))
+	switch {
+	case strings.Contains(urlSrc, "{WOPISrc}"):
+		return strings.ReplaceAll(urlSrc, "{WOPISrc}", escaped), nil
+	case strings.Contains(urlSrc, "WOPISrc="):
+		return urlSrc + escaped, nil
+	default:
+		sep := "?"
+		if strings.Contains(urlSrc, "?") {
+			sep = "&"
+		}
+		return urlSrc + sep + "WOPISrc=" + escaped, nil
+	}
+}
+
+func (s *WOPIService) WOPISrc(fileID string) string {
+	fileID = strings.TrimSpace(fileID)
+	base := strings.TrimSpace(s.cfg.PublicBaseURL)
+	if base == "" {
+		return "/wopi/files/" + fileID
+	}
+	return strings.TrimRight(base, "/") + "/wopi/files/" + fileID
+}
+
+// BuildActionURLWithToken builds the Collabora editor action URL for a file.
+//
+// Per the WOPI/Collabora contract the action URL carries THREE separate query
+// parameters: WOPISrc (the BARE file URL, no token), access_token and
+// access_token_ttl. Collabora echoes access_token/access_token_ttl back on
+// every WOPI callback (CheckFileInfo, GetFile, PutFile, Lock). Embedding the
+// token inside the WOPISrc value instead leaves Collabora with an empty
+// top-level access_token, which the WOPI host rejects — surfacing as a bogus
+// "file is corrupt" prompt on load and "no write-able session" errors on save.
+//
+// accessTokenTTL is an ABSOLUTE expiry time in epoch milliseconds (matching the
+// JWT exp claim), as required by WOPI/Collabora — not a duration.
+func (s *WOPIService) BuildActionURLWithToken(ctx context.Context, fileID, token string, accessTokenTTL int64) (string, error) {
+	actionURL, err := s.BuildActionURL(ctx, s.WOPISrc(fileID))
+	if err != nil {
+		return "", err
+	}
+	token = strings.TrimSpace(token)
+	if token == "" {
+		return actionURL, nil
+	}
+	sep := "?"
+	if strings.Contains(actionURL, "?") {
+		sep = "&"
+	}
+	actionURL += sep + "access_token=" + url.QueryEscape(token)
+	if accessTokenTTL > 0 {
+		actionURL += "&access_token_ttl=" + strconv.FormatInt(accessTokenTTL, 10)
+	}
+	return actionURL, nil
+}
+
+func (s *WOPIService) discoveryURLSrc(ctx context.Context) (string, error) {
+	if s == nil {
+		return "", errors.New("wopi service is nil")
+	}
+	s.mu.RLock()
+	cached := s.discovery
+	s.mu.RUnlock()
+	if strings.TrimSpace(cached.URLSrc) != "" && time.Since(cached.Loaded) < 15*time.Minute {
+		return cached.URLSrc, nil
+	}
+	if strings.TrimSpace(s.cfg.EditActionURL) != "" {
+		s.mu.Lock()
+		s.discovery = wopiDiscoveryCache{URLSrc: strings.TrimSpace(s.cfg.EditActionURL), Loaded: time.Now().UTC()}
+		s.mu.Unlock()
+		return s.cfg.EditActionURL, nil
+	}
+	if strings.TrimSpace(s.cfg.DiscoveryURL) == "" {
+		return "", errors.New("wopi discovery url is not configured")
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, s.cfg.DiscoveryURL, nil)
+	if err != nil {
+		return "", err
+	}
+	resp, err := s.http.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return "", fmt.Errorf("wopi discovery returned %s", resp.Status)
+	}
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1024*1024))
+	if err != nil {
+		return "", err
+	}
+	urlSrc := parseWOPIDiscoveryURLSrc(string(body))
+	if urlSrc == "" {
+		return "", errors.New("wopi discovery missing urlsrc")
+	}
+	s.mu.Lock()
+	s.discovery = wopiDiscoveryCache{URLSrc: urlSrc, Loaded: time.Now().UTC()}
+	s.mu.Unlock()
+	return urlSrc, nil
+}
+
+func parseWOPIDiscoveryURLSrc(raw string) string {
+	start := strings.Index(raw, "urlsrc=\"")
+	if start < 0 {
+		return ""
+	}
+	start += len(`urlsrc="`)
+	end := strings.Index(raw[start:], `"`)
+	if end < 0 {
+		return ""
+	}
+	return htmlUnescape(raw[start : start+end])
+}
+
+func htmlUnescape(v string) string {
+	v = strings.ReplaceAll(v, "&amp;", "&")
+	v = strings.ReplaceAll(v, "&lt;", "<")
+	v = strings.ReplaceAll(v, "&gt;", ">")
+	v = strings.ReplaceAll(v, "&#39;", "'")
+	v = strings.ReplaceAll(v, "&quot;", "\"")
+	return v
+}
+
+func (s *WOPIService) VerifyProof(method, path, accessToken, timestamp, proof, proofOld string) error {
+	if s == nil || !s.cfg.RequireProof {
+		return nil
+	}
+	if strings.TrimSpace(s.cfg.ProofSecret) == "" {
+		return errors.New("wopi proof secret is not configured")
+	}
+	ts, err := strconv.ParseInt(strings.TrimSpace(timestamp), 10, 64)
+	if err != nil {
+		return errors.New("invalid wopi timestamp")
+	}
+	reqTime := time.Unix(0, ts*int64(time.Millisecond))
+	if d := time.Since(reqTime); d > 10*time.Minute || d < -10*time.Minute {
+		return errors.New("stale wopi request")
+	}
+	base := strings.Join([]string{
+		strings.ToUpper(strings.TrimSpace(method)),
+		strings.TrimSpace(path),
+		strings.TrimSpace(accessToken),
+		strings.TrimSpace(timestamp),
+	}, "\n")
+	if verifyWOPIProofSignature(s.cfg.ProofSecret, base, proof) {
+		return nil
+	}
+	if verifyWOPIProofSignature(s.cfg.ProofSecret, base, proofOld) {
+		return nil
+	}
+	return errors.New("invalid wopi proof")
+}
+
+func verifyWOPIProofSignature(secret, payload, proof string) bool {
+	if strings.TrimSpace(proof) == "" {
+		return false
+	}
+	sum := hmac.New(sha256.New, []byte(secret))
+	_, _ = sum.Write([]byte(payload))
+	expected := base64.RawURLEncoding.EncodeToString(sum.Sum(nil))
+	return hmac.Equal([]byte(expected), []byte(strings.TrimSpace(proof)))
+}
+
+func envDuration(key string, fallback time.Duration) time.Duration {
+	raw := strings.TrimSpace(os.Getenv(key))
+	if raw == "" {
+		return fallback
+	}
+	v, err := time.ParseDuration(raw)
+	if err != nil {
+		return fallback
+	}
+	return v
+}
+
+func envInt(key string, fallback int) int {
+	raw := strings.TrimSpace(os.Getenv(key))
+	if raw == "" {
+		return fallback
+	}
+	v, err := strconv.Atoi(raw)
+	if err != nil {
+		return fallback
+	}
+	return v
+}
+
+func envBool(key string, fallback bool) bool {
+	raw := strings.TrimSpace(os.Getenv(key))
+	if raw == "" {
+		return fallback
+	}
+	v, err := strconv.ParseBool(raw)
+	if err != nil {
+		return fallback
+	}
+	return v
+}
+
+func uuidBytesString(id []byte) string {
+	if len(id) != 16 {
+		return ""
+	}
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		return ""
+	}
+	return s
+}
diff --git a/internal/service/wopi_service_test.go b/internal/service/wopi_service_test.go
new file mode 100644
index 0000000..19f1823
--- /dev/null
+++ b/internal/service/wopi_service_test.go
@@ -0,0 +1,53 @@
+package service
+
+import (
+	"context"
+	"net/url"
+	"testing"
+)
+
+func TestBuildActionURLWithToken(t *testing.T) {
+	t.Parallel()
+
+	svc := NewWOPIService(WOPIConfig{
+		PublicBaseURL: "https://api-wfm-dev.mybit.co.id",
+		EditActionURL: "https://collabora.mybit.co.id/browser/abc/cool.html?",
+	})
+
+	// access_token_ttl is an absolute expiry time in epoch milliseconds.
+	const accessTokenTTL = int64(1782971996000)
+	got, err := svc.BuildActionURLWithToken(
+		context.Background(),
+		"019f1c17-b244-76c3-a1c0-6b3b382ad8b6",
+		"jwt-token-value",
+		accessTokenTTL,
+	)
+	if err != nil {
+		t.Fatalf("BuildActionURLWithToken error = %v", err)
+	}
+
+	parsed, err := url.Parse(got)
+	if err != nil {
+		t.Fatalf("url.Parse error = %v", err)
+	}
+
+	// access_token and access_token_ttl must be SEPARATE top-level params so
+	// Collabora echoes them back on every WOPI callback.
+	if q := parsed.Query().Get("access_token"); q != "jwt-token-value" {
+		t.Fatalf("unexpected access_token: %q", q)
+	}
+	if q := parsed.Query().Get("access_token_ttl"); q != "1782971996000" {
+		t.Fatalf("unexpected access_token_ttl: %q", q)
+	}
+
+	// WOPISrc must be the BARE file URL — no token embedded inside it.
+	wopiSrc := parsed.Query().Get("WOPISrc")
+	if wopiSrc != "https://api-wfm-dev.mybit.co.id/wopi/files/019f1c17-b244-76c3-a1c0-6b3b382ad8b6" {
+		t.Fatalf("WOPISrc must be the bare file url, got %q", wopiSrc)
+	}
+	if inner, err := url.Parse(wopiSrc); err == nil {
+		if tok := inner.Query().Get("access_token"); tok != "" {
+			t.Fatalf("WOPISrc must not embed access_token, got %q", tok)
+		}
+	}
+}
diff --git a/internal/shared/const/audit.go b/internal/shared/const/audit.go
new file mode 100644
index 0000000..5e9f81b
--- /dev/null
+++ b/internal/shared/const/audit.go
@@ -0,0 +1,48 @@
+package sharedconst
+
+const (
+	AuditModuleUnknown                = "unknown"
+	AuditModuleAirRescuerChecklist    = "air_rescuer_checklist"
+	AuditModuleAuditLog               = "audit_log"
+	AuditModuleAuth                   = "auth"
+	AuditModuleBase                   = "base"
+	AuditModuleBaseRegular            = "base_regular"
+	AuditModuleBaseHEMS               = "base_hems"
+	AuditModuleBranding               = "branding"
+	AuditModuleContact                = "contact"
+	AuditModuleDutyRoster             = "duty_roster"
+	AuditModuleDUL                    = "dul"
+	AuditModuleFacility               = "facility"
+	AuditModuleFederalState           = "federal_state"
+	AuditModuleFileManager            = "file_manager"
+	AuditModuleFlightData             = "flight_data"
+	AuditModuleFlight                 = "flight"
+	AuditModuleForcesPresent          = "forces_present"
+	AuditModuleHealthInsuranceCompany = "health_insurance_company"
+	AuditModuleHelicopterFile         = "helicopter_file"
+	AuditModuleHelicopter             = "helicopter"
+	AuditModuleHospital               = "hospital"
+	AuditModuleICAO                   = "icao"
+	AuditModuleInsurancePatientData   = "insurance_patient_data"
+	AuditModuleLand                   = "land"
+	AuditModuleMasterSetting          = "master_setting"
+	AuditModuleMedicine               = "medicine"
+	AuditModuleMission                = "mission"
+	AuditModuleOPC                    = "opc"
+	AuditModulePatientData            = "patient_data"
+	AuditModuleReserveAC              = "reserve_ac"
+	AuditModuleRole                   = "role"
+	AuditModuleUser                   = "user"
+	AuditModuleVocation               = "vocation"
+)
+
+const (
+	AuditActionList   = "list"
+	AuditActionGet    = "get"
+	AuditActionCreate = "create"
+	AuditActionUpdate = "update"
+	AuditActionDelete = "delete"
+	AuditActionExport = "export"
+	AuditActionImport = "import"
+	AuditActionCustom = "custom"
+)
diff --git a/internal/shared/const/branding.go b/internal/shared/const/branding.go
new file mode 100644
index 0000000..ec64fef
--- /dev/null
+++ b/internal/shared/const/branding.go
@@ -0,0 +1,5 @@
+package sharedconst
+
+const (
+	BrandingEmailLogoPublicPath = "/api/v1/public/branding/email-logo"
+)
diff --git a/internal/shared/const/flight_data.go b/internal/shared/const/flight_data.go
new file mode 100644
index 0000000..ccc5a39
--- /dev/null
+++ b/internal/shared/const/flight_data.go
@@ -0,0 +1,14 @@
+package sharedconst
+
+const (
+	FlightDataResourceType = "flight_data"
+
+	FlightDataLocationTypeICAO     = "icao"
+	FlightDataLocationTypeHospital = "hospital"
+
+	FlightDataFacilityCategoryHesloRopeLabel  = "heslo-rope-label"
+	FlightDataFacilityCategoryHesloRopeLength = "heslo-rope-length"
+	FlightDataFacilityCategoryHesloHook       = "heslo-hook"
+	FlightDataFacilityCategoryHecRopeLabel    = "hec-rope-label"
+	FlightDataFacilityCategoryHecRopeLength   = "hec-rope-length"
+)
diff --git a/internal/shared/const/mission.go b/internal/shared/const/mission.go
new file mode 100644
index 0000000..0b11cb7
--- /dev/null
+++ b/internal/shared/const/mission.go
@@ -0,0 +1,15 @@
+package sharedconst
+
+const (
+	MissionDefaultPageSize = 20
+	MissionMaxPageSize     = 100
+)
+
+const (
+	MissionResourceType = "mission"
+
+	MissionTypeCAT  = "CAT"
+	MissionTypeSPO  = "SPO"
+	MissionTypeNCO  = "NCO"
+	MissionTypeHEMS = "HEMS"
+)
diff --git a/internal/shared/const/pin_actions.go b/internal/shared/const/pin_actions.go
new file mode 100644
index 0000000..e981ed4
--- /dev/null
+++ b/internal/shared/const/pin_actions.go
@@ -0,0 +1,344 @@
+package sharedconst
+
+import "strings"
+
+const (
+	// Opaque transaction IDs for PIN-protected HTTP actions.
+	PinActionUserCreate                     = "2a59e8b4-5a72-4be3-b8fc-4f49941181c3"
+	PinActionUserUpdate                     = "428fdf48-3f99-46ea-bc47-8fb2e312be08"
+	PinActionUserDelete                     = "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"
+	PinActionRoleCreate                     = "7fb1d693-8692-4e8f-be86-fd0e29e96bc3"
+	PinActionRoleUpdate                     = "18ca5bbf-ce9d-4e24-8ace-793de56c1de0"
+	PinActionRoleDelete                     = "b87fca76-783d-45e7-9022-b2d9c95f6da7"
+	PinActionRolePermissionAssign           = "48e523f8-d86f-4b24-b0e3-e213e4d33db4"
+	PinActionRolePermissionRemove           = "f2bf59f8-0783-40fc-94ce-a79e40f84c44"
+	PinActionRolePermissionUpdate           = "de8f3c0c-8f84-4c13-a146-5ca833bc66f7"
+	PinActionHelicopterCreate               = "11c8f526-2bf5-4507-bf6b-5ea65e4f2b8a"
+	PinActionHelicopterReportGenerate       = "f84fc149-c1a8-4b55-8d68-7f1130a91c62"
+	PinActionHelicopterUpdate               = "7436fdf4-0f71-4a5d-a21e-a22cbf7f45fa"
+	PinActionHelicopterDelete               = "3b3f6c0c-7e9d-4d7e-b2f2-250d325a9008"
+	PinActionHelicopterAOGChange            = "9b2a8f32-b7f1-4cc8-9f75-2f7f4e5d8f1c"
+	PinActionFlightInspectionCreate         = "6a4f31e2-f6f2-4fd0-8e0f-c56613fb7996"
+	PinActionFlightInspectionUpdate         = "fe936c6f-6634-4c8f-88c0-86f46c22f6e2"
+	PinActionAfterFlightInspectionRead      = "7a4f1d7a-3f8e-4a8b-9f8c-5e7b3a9d8a31"
+	PinActionAfterFlightInspectionCreate    = "1d7f1e5c-0c1f-4d5d-9c59-2d7b7f9d3c2f"
+	PinActionAfterFlightInspectionUpdate    = "b4a7e8b2-1fb4-4c9f-9e6b-7f53c0b4f1a8"
+	PinActionAfterFlightInspectionDelete    = "d9c0b6f3-5f3b-4f9d-8a5b-1b0c2d7a9e4f"
+	PinActionFlightCreate                   = "03482710-17bb-4478-b379-fafd92a6f2f1"
+	PinActionFlightUpdate                   = "f5fe23d8-79af-4f53-82f8-ef5436f54d73"
+	PinActionFlightDelete                   = "846f2a97-b4c0-4a89-bacf-14393968ce4d"
+	PinActionReserveACCreate                = "70fccbfe-1908-44fd-97eb-8ec7cb26f441"
+	PinActionReserveACUpdate                = "514ec6f8-57ef-43a2-ad8c-48be77ef7f7e"
+	PinActionReserveACDelete                = "01954c5e-e321-4556-aef1-ed9724f64409"
+	PinActionFacilityCreate                 = "4a4e2041-258c-4f12-89af-8473f8b666d6"
+	PinActionFacilityUpdate                 = "2a7530e9-b365-4229-b2cc-a7059dbb6530"
+	PinActionFacilityDelete                 = "6ca1f6ca-b89f-4be2-9e5d-bebcd4f7140f"
+	PinActionBaseCreate                     = "195f2e65-8159-42a9-a198-34fa8e47a9b4"
+	PinActionBaseUpdate                     = "f57ef758-53e6-4065-b1ed-58afbfd1bb89"
+	PinActionBaseDelete                     = "2e6c907f-7e29-4617-9fd5-5298c4cb5f16"
+	PinActionMedicineCreate                 = "8477bc66-28b8-4c21-aa15-3e06d8944aef"
+	PinActionMedicineUpdate                 = "832ddfcb-ef58-4c00-b863-d5e11fec3e3d"
+	PinActionMedicineDelete                 = "c5ec1cb5-f403-48de-868a-576e4d1d84e1"
+	PinActionVocationCreate                 = "e07b5460-5e74-4df7-a81a-0be67a62cc58"
+	PinActionVocationUpdate                 = "f3629c15-8a20-4c61-ba04-81bdff021ae6"
+	PinActionVocationDelete                 = "dbb1f792-f15c-4a19-9e5d-07c42c2a79df"
+	PinActionOpcCreate                      = "97285960-79b9-4beb-97c6-68d0a1113a1d"
+	PinActionOpcUpdate                      = "f5c3018b-fcec-470e-88ed-99d58f6d1d45"
+	PinActionOpcDelete                      = "f8d692cf-8196-4eab-b33d-fa073729f5a6"
+	PinActionForcesPresentCreate            = "fb4026a1-5b41-4a39-bd3e-9f659de7422f"
+	PinActionForcesPresentUpdate            = "9e3edd96-7a70-406f-bfa0-5990999f8563"
+	PinActionForcesPresentDelete            = "8abebbd0-a265-44d2-8c24-a9787fa168bf"
+	PinActionNoIcaoCodeCreate               = "6de5d0e9-f157-4f8f-b86f-470f0f2f4f59"
+	PinActionNoIcaoCodeUpdate               = "f116da2f-1229-4f12-97ec-ecbff1936fa7"
+	PinActionNoIcaoCodeDelete               = "f315f998-6bc2-4bdd-8aab-2a61184bf51d"
+	PinActionHospitalCreate                 = PinActionNoIcaoCodeCreate
+	PinActionHospitalUpdate                 = PinActionNoIcaoCodeUpdate
+	PinActionHospitalDelete                 = PinActionNoIcaoCodeDelete
+	PinActionHealthInsuranceCompaniesCreate = "7d6494e4-44f3-4a49-a370-8cf0f430af26"
+	PinActionHealthInsuranceCompaniesUpdate = "88f1e75f-bfc0-48d7-bbe2-10f02f92c514"
+	PinActionHealthInsuranceCompaniesDelete = "5ce3f937-1f8c-4140-9f50-9f0a0d9b930f"
+	PinActionFederalStateCreate             = "17720d29-8afa-4932-93a3-40d44fbf8563"
+	PinActionFederalStateUpdate             = "43f5db24-ac9f-44cd-82da-2d596d93c736"
+	PinActionFederalStateDelete             = "b37f7fb2-fdf4-4f31-9de3-a62f0b47eb3b"
+	PinActionICAOCreate                     = "f7d407cf-0fb7-4b6b-a530-a22f378f0f2d"
+	PinActionICAOUpdate                     = "96f05643-b5ca-4d36-9459-f31d55c5c350"
+	PinActionICAODelete                     = "89f3de85-4bca-4fce-8c8f-b79156257e95"
+	PinActionCountryCreate                  = "056984e1-e316-428e-a9a1-c4ed6fac2c5a"
+	PinActionCountryUpdate                  = "436fcde1-50d3-4bfc-9d90-a082c94732a1"
+	PinActionCountryDelete                  = "b72ecaf6-fa38-4bd9-a272-5b00307e5e34"
+	PinActionLandCreate                     = PinActionCountryCreate
+	PinActionLandUpdate                     = PinActionCountryUpdate
+	PinActionLandDelete                     = PinActionCountryDelete
+	PinActionMasterSettingsCreate           = "24f9e3f1-4de7-4fd4-bdf6-5e6ac7d3a8a5"
+	PinActionMasterSettingsUpdate           = "8ff7fa7f-8d27-4e7a-81dc-b2d15a6cce9d"
+	PinActionMasterSettingsDelete           = "c0c9cbe8-f281-44e9-8414-47a5fcc8d6d3"
+	PinActionCrewCreate                     = "c6911bc0-9677-4a6d-96e5-8debcde079cb"
+	PinActionCrewUpdate                     = "f89fc2cb-11f0-46c8-b5db-71f9be889734"
+	PinActionCrewDelete                     = "49e6782e-7d38-48bd-b949-8414827483fb"
+	PinActionFileManagerFolderCreate        = "0a5f5463-0f9c-4f75-8da4-5aef28e0fc42"
+	PinActionFileManagerFolderUpdate        = "b1fb11f7-a8b4-4d80-b3aa-f54a0f4ec9c0"
+	PinActionFileManagerFolderDelete        = "6b84e2d6-2b61-44e3-a4df-7ad4568baf5d"
+	PinActionFileManagerFolderRestore       = "08f5d1f2-99a6-4e2e-aaf9-24103fb34b5f"
+	PinActionFileManagerFolderPurge         = "645c13eb-0ef4-4f3f-a31f-81f7f08a7718"
+	PinActionFileManagerFileCreate          = "f8f4e17c-9b2f-4f1a-a86a-c8c4f2a9de41"
+	PinActionFileManagerFileUpload          = "8ef739b4-a56a-4fb2-b563-0bc8f1e9d305"
+	PinActionFileManagerFileUpdate          = "4f6405aa-b889-4b9a-8872-d662ef53fcb8"
+	PinActionFileManagerFileDelete          = "29db3d11-1064-4940-bf97-e9c8d8cab2b1"
+	PinActionFileManagerFileRestore         = "198edb44-8443-4b66-ae5f-1587c3130cc0"
+	PinActionFileManagerFilePurge           = "4d2ad12d-aafd-460b-818d-e4bd8f4bf947"
+	PinActionFileManagerAttachmentCreate    = "55f6de50-49ea-4e03-b16f-cfe1bcb4f0a2"
+	PinActionFileManagerAttachmentDelete    = "39ef5f25-a86d-4f06-a5fc-f85ba6df8a45"
+	PinActionHemsDutyRosterCreate           = "a9a8d9d7-8804-4f2b-bd17-a990488f0fc1"
+	PinActionHemsDutyRosterUpdate           = "c1c9f6d6-205f-4488-b68a-29f810123b7b"
+	PinActionHemsDutyRosterDelete           = "3f8c8de7-10eb-4e92-9415-cfca2b50cc72"
+	PinActionHemsDutyRosterDeleteCrew       = "b2f1d1f1-a8b5-43ea-8fea-e4f3225e9d31"
+	PinActionBaseDutyRosterCreate           = "b1f0743f-4af8-43f9-acf1-f3ad3df842fb"
+	PinActionBaseDutyRosterUpdate           = "cb7f6494-7035-4288-a736-c21ca2aaad6e"
+	PinActionBaseDutyRosterDelete           = "399be2cb-b7ea-4e4a-a95e-a45a78475c4f"
+	PinActionBaseDutyRosterDeleteCrew       = "f7f57b0a-6e4a-4a59-b8cc-5b0c7fdb3f0f"
+	PinActionAirRescuerChecklistCreate      = "0da46094-7af2-4897-84f2-d4f6409a23cd"
+	PinActionAirRescuerChecklistUpdate      = "2a8df0df-6c30-4338-a7eb-a288f8f43cb8"
+	PinActionAirRescuerChecklistDelete      = "74c4dd5f-4040-4b4f-87c6-f7ca6ad2ffde"
+	PinActionFlightPrepCheckCreate          = "c2d8014f-86f7-4e59-acaa-7126d8fa1b2f"
+	PinActionFlightPrepCheckUpdate          = "acbe9954-e9b2-447f-bf53-f10da99f1ff8"
+	PinActionInsurancePatientDataCreate     = "5b8f8f70-c3f5-4c3a-8e3f-fb5bb886f12f"
+	PinActionInsurancePatientDataUpdate     = "ea5da1cf-735f-4bcf-8b6d-d50b9f0f2e85"
+	PinActionInsurancePatientDataDelete     = "f5e36c38-10cf-4df2-8eb0-e546f57ecce1"
+	PinActionPatientDataCreate              = "a8f4dd13-f255-4d22-8fcf-3ddedca95f79"
+	PinActionPatientDataUpdate              = "0171a3fe-33ee-450f-9f64-bfe2ce6ecf72"
+	PinActionPatientDataDelete              = "a311702f-778a-4737-9fa5-cb67bf0e43cb"
+	PinActionOperationCreate                = "cd6d274d-8459-4fd8-b840-f3f9c06a53d2"
+	PinActionOperationUpdate                = "5340a403-7eb1-4f57-966a-d5da679048f4"
+	PinActionOperationDelete                = "b5d6ec7c-994b-40f5-90f5-f38bf0878e6e"
+	PinActionOperationCategoryCreate        = "e1cb42db-f6d1-42e5-8d5f-cf711ab4bff2"
+	PinActionOperationCategoryUpdate        = "ed5e8d89-0674-4378-b260-d560f815d8cb"
+	PinActionOperationCategoryDelete        = "3f7b7ce4-f358-4898-baea-19b8f15235d1"
+	PinActionHemsOperationCreate            = "5fef650e-0477-4200-af6c-3034f2cd96a6"
+	PinActionHemsOperationUpdate            = "2c20f88a-5866-4972-a908-c9766156f332"
+	PinActionHemsOperationDelete            = "62de5f5f-e737-4f58-8d8f-b3fce2d618d7"
+	PinActionAirRescuerChecklistItemCreate  = "654f0050-c4ad-4dd3-aa52-4a93e9737397"
+	PinActionAirRescuerChecklistItemUpdate  = "73ce2aaf-b7a5-4c05-af6f-536775df6e5d"
+	PinActionAirRescuerChecklistItemDelete  = "9f2053e6-4be8-4d77-b6f5-89ad6d04a2a4"
+	PinActionAuditLogRead                   = "c847e7fc-5e44-48f0-a7d9-1e8d15543d74"
+	PinActionTOTPResetSetup                 = "0b5409b5-94f3-4aab-9de2-44b0ad5858f1"
+	PinActionWebAuthnResetSetup             = "1f7d457e-0a19-4a36-8d9f-2c66fd2369ab"
+	PinActionSessionDelete                  = "3d7d1d5f-ec48-4eca-a7ea-37f4f7927d06"
+	PinActionContactCreate                  = "6eea32d5-3c73-4a63-a929-ace48542bd5e"
+	PinActionContactUpdate                  = "aa2cfd85-f87d-400f-918c-01d90d965516"
+	PinActionContactDelete                  = "1d6d5f43-c174-488f-aab5-8f71be570156"
+	PinActionContactStatusChange            = "31f8bb88-a95f-43be-8fd8-129e1355d6a5"
+	PinActionContactRoleChange              = "28d6b6fa-4de8-4e70-b65d-59bb54ca9387"
+	PinActionContactPilotCategoryChange     = "a90d6543-4196-4a94-b2f5-c1db89dc0f79"
+	PinActionContactLicenseEdit             = "dc4cc081-68e5-4304-8b39-40ef7d995f48"
+	PinActionContactChiefFlagsEdit          = "ebc77226-7d84-4b4f-9f08-27f004770aee"
+	PinActionContactResponsibleComplaints   = "4f4c8f3d-73ea-4eec-8d08-c3be6e2ffad6"
+	PinActionContactBulkUpdate              = "d9dc5187-c67e-4f58-9dd3-2664cbc9f9fd"
+	PinActionContactIrreversible            = "78f90214-8bcf-4274-adfb-6d207c5f5af6"
+	PinActionFmReportComplete               = "1a75135b-430a-4592-83e1-6d27814185af"
+	PinActionFmReportDelete                 = "9b4e6d8f-0a2c-4c5e-a7f3-1b0d5e7c9a2f"
+	PinActionEASAReleaseSign                = "e4a1c2d8-6b3f-4f7a-9c21-8d5e0b7a4f36"
+)
+
+func PinActionForPermissionKey(permissionKey string) string {
+	switch strings.TrimSpace(strings.ToLower(permissionKey)) {
+	case "user.create":
+		return PinActionUserCreate
+	case "user.update":
+		return PinActionUserUpdate
+	case "user.delete":
+		return PinActionUserDelete
+	case "role.create":
+		return PinActionRoleCreate
+	case "role.update":
+		return PinActionRoleUpdate
+	case "role.delete":
+		return PinActionRoleDelete
+	case "role.permission.assign":
+		return PinActionRolePermissionAssign
+	case "role.permission.remove":
+		return PinActionRolePermissionRemove
+	case "role.permission.update":
+		return PinActionRolePermissionUpdate
+	case "audit.read":
+		return PinActionAuditLogRead
+	case "helicopter.create":
+		return PinActionHelicopterCreate
+	case "helicopter.update":
+		return PinActionHelicopterUpdate
+	case "helicopter.delete":
+		return PinActionHelicopterDelete
+	case "helicopter.report.generate":
+		return PinActionHelicopterReportGenerate
+	case "flight_inspection.create":
+		return PinActionFlightInspectionCreate
+	case "flight_inspection.update":
+		return PinActionFlightInspectionUpdate
+	case "after_flight.read":
+		return PinActionAfterFlightInspectionRead
+	case "after_flight.create":
+		return PinActionAfterFlightInspectionCreate
+	case "after_flight.update":
+		return PinActionAfterFlightInspectionUpdate
+	case "after_flight.delete":
+		return PinActionAfterFlightInspectionDelete
+	case "flight.create":
+		return PinActionFlightCreate
+	case "flight.update":
+		return PinActionFlightUpdate
+	case "flight.complete":
+		return PinActionFmReportComplete
+	case "easa_release.sign":
+		return PinActionEASAReleaseSign
+	case "flight.delete":
+		return PinActionFlightDelete
+	case "reserve_ac.create":
+		return PinActionReserveACCreate
+	case "reserve_ac.update":
+		return PinActionReserveACUpdate
+	case "reserve_ac.delete":
+		return PinActionReserveACDelete
+	case "facility.create":
+		return PinActionFacilityCreate
+	case "facility.update":
+		return PinActionFacilityUpdate
+	case "facility.delete":
+		return PinActionFacilityDelete
+	case "base.create":
+		return PinActionBaseCreate
+	case "base.update":
+		return PinActionBaseUpdate
+	case "base.delete":
+		return PinActionBaseDelete
+	case "hems_base.create":
+		return PinActionBaseCreate
+	case "hems_base.update":
+		return PinActionBaseUpdate
+	case "hems_base.delete":
+		return PinActionBaseDelete
+	case "medicine.create":
+		return PinActionMedicineCreate
+	case "medicine.update":
+		return PinActionMedicineUpdate
+	case "medicine.delete":
+		return PinActionMedicineDelete
+	case "vocation.create":
+		return PinActionVocationCreate
+	case "vocation.update":
+		return PinActionVocationUpdate
+	case "vocation.delete":
+		return PinActionVocationDelete
+	case "opc.create":
+		return PinActionOpcCreate
+	case "opc.update":
+		return PinActionOpcUpdate
+	case "opc.delete":
+		return PinActionOpcDelete
+	case "forces_present.create":
+		return PinActionForcesPresentCreate
+	case "forces_present.update":
+		return PinActionForcesPresentUpdate
+	case "forces_present.delete":
+		return PinActionForcesPresentDelete
+	case "hospital.create", "no_icao_code.create":
+		return PinActionNoIcaoCodeCreate
+	case "hospital.update", "no_icao_code.update":
+		return PinActionNoIcaoCodeUpdate
+	case "hospital.delete", "no_icao_code.delete":
+		return PinActionNoIcaoCodeDelete
+	case "health_insurance_companies.create":
+		return PinActionHealthInsuranceCompaniesCreate
+	case "health_insurance_companies.update":
+		return PinActionHealthInsuranceCompaniesUpdate
+	case "health_insurance_companies.delete":
+		return PinActionHealthInsuranceCompaniesDelete
+	case "federal_state.create":
+		return PinActionFederalStateCreate
+	case "federal_state.update":
+		return PinActionFederalStateUpdate
+	case "federal_state.delete":
+		return PinActionFederalStateDelete
+	case "icao.create":
+		return PinActionICAOCreate
+	case "icao.update":
+		return PinActionICAOUpdate
+	case "icao.delete":
+		return PinActionICAODelete
+	case "land.create", "country.create":
+		return PinActionCountryCreate
+	case "land.update", "country.update":
+		return PinActionCountryUpdate
+	case "land.delete", "country.delete":
+		return PinActionCountryDelete
+	case "master_settings.create":
+		return PinActionMasterSettingsCreate
+	case "master_settings.update":
+		return PinActionMasterSettingsUpdate
+	case "master_settings.delete":
+		return PinActionMasterSettingsDelete
+	case "flight_prep_check.create":
+		return PinActionFlightPrepCheckCreate
+	case "flight_prep_check.update":
+		return PinActionFlightPrepCheckUpdate
+	case "insurance_patient_data.create":
+		return PinActionInsurancePatientDataCreate
+	case "insurance_patient_data.update":
+		return PinActionInsurancePatientDataUpdate
+	case "insurance_patient_data.delete":
+		return PinActionInsurancePatientDataDelete
+	case "patient_data.create":
+		return PinActionPatientDataCreate
+	case "patient_data.update":
+		return PinActionPatientDataUpdate
+	case "patient_data.delete":
+		return PinActionPatientDataDelete
+	case "operation.create":
+		return PinActionOperationCreate
+	case "operation.update":
+		return PinActionOperationUpdate
+	case "operation.delete":
+		return PinActionOperationDelete
+	case "operation_category.create":
+		return PinActionOperationCategoryCreate
+	case "operation_category.update":
+		return PinActionOperationCategoryUpdate
+	case "operation_category.delete":
+		return PinActionOperationCategoryDelete
+	case "hems_operation.create":
+		return PinActionHemsOperationCreate
+	case "hems_operation.update":
+		return PinActionHemsOperationUpdate
+	case "hems_operation.delete":
+		return PinActionHemsOperationDelete
+	case "hems_duty_roster.create":
+		return PinActionHemsDutyRosterCreate
+	case "hems_duty_roster.update":
+		return PinActionHemsDutyRosterUpdate
+	case "hems_duty_roster.delete":
+		return PinActionHemsDutyRosterDelete
+	case "air_rescuer_checklist.create":
+		return PinActionAirRescuerChecklistCreate
+	case "air_rescuer_checklist.update":
+		return PinActionAirRescuerChecklistUpdate
+	case "air_rescuer_checklist.delete":
+		return PinActionAirRescuerChecklistDelete
+	case "file_manager.create":
+		return PinActionFileManagerFileCreate
+	case "file_manager.update":
+		return PinActionFileManagerFileUpdate
+	case "file_manager.delete":
+		return PinActionFileManagerFileDelete
+	case "file_manager.folder.create":
+		return PinActionFileManagerFolderCreate
+	case "file_manager.folder.update":
+		return PinActionFileManagerFolderUpdate
+	case "file_manager.folder.delete":
+		return PinActionFileManagerFolderDelete
+	case "file_manager.file.create":
+		return PinActionFileManagerFileCreate
+	case "file_manager.file.update":
+		return PinActionFileManagerFileUpdate
+	case "file_manager.file.delete":
+		return PinActionFileManagerFileDelete
+	}
+	return ""
+}
diff --git a/internal/shared/pkg/appctx/appctx.go b/internal/shared/pkg/appctx/appctx.go
new file mode 100644
index 0000000..d343702
--- /dev/null
+++ b/internal/shared/pkg/appctx/appctx.go
@@ -0,0 +1,57 @@
+package appctx
+
+import (
+	"context"
+	"strings"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type contextKey string
+
+const userIDKey contextKey = "appctx-user-id"
+
+func WithUserID(ctx context.Context, userID []byte) context.Context {
+	if len(userID) == 0 {
+		return ctx
+	}
+
+	copyID := make([]byte, len(userID))
+	copy(copyID, userID)
+	return context.WithValue(ctx, userIDKey, copyID)
+}
+
+func GetUserID(ctx context.Context) []byte {
+	if ctx == nil {
+		return nil
+	}
+
+	raw := ctx.Value(userIDKey)
+	if raw == nil {
+		if getter, ok := any(ctx).(interface{ UserValue(any) any }); ok {
+			raw = getter.UserValue("user_id")
+		}
+	}
+
+	switch v := raw.(type) {
+	case []byte:
+		if len(v) == 0 {
+			return nil
+		}
+		out := make([]byte, len(v))
+		copy(out, v)
+		return out
+	case string:
+		s := strings.TrimSpace(v)
+		if s == "" {
+			return nil
+		}
+		id, err := uuidv7.ParseString(s)
+		if err != nil {
+			return nil
+		}
+		return id
+	default:
+		return nil
+	}
+}
diff --git a/internal/shared/pkg/appctx/appctx_test.go b/internal/shared/pkg/appctx/appctx_test.go
new file mode 100644
index 0000000..579ebf4
--- /dev/null
+++ b/internal/shared/pkg/appctx/appctx_test.go
@@ -0,0 +1,46 @@
+package appctx
+
+import (
+	"context"
+	"testing"
+
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func TestWithUserIDAndGetUserID(t *testing.T) {
+	id, err := uuidv7.ParseString("00000000-0000-0000-0000-000000000001")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ctx := WithUserID(context.Background(), id)
+	got := GetUserID(ctx)
+	if len(got) != len(id) {
+		t.Fatalf("expected %d bytes, got %d", len(id), len(got))
+	}
+	if string(got) != string(id) {
+		t.Fatalf("expected %x, got %x", id, got)
+	}
+
+	got[0] ^= 0xff
+	if string(GetUserID(ctx)) == string(got) {
+		t.Fatal("GetUserID returned a reference to internal data")
+	}
+}
+
+func TestGetUserIDFromLegacyContext(t *testing.T) {
+	ctx := &legacyContext{Context: context.Background(), userID: []byte("legacy")}
+	got := GetUserID(ctx)
+	if string(got) != "legacy" {
+		t.Fatalf("expected legacy user id, got %s", got)
+	}
+}
+
+type legacyContext struct {
+	context.Context
+	userID []byte
+}
+
+func (c *legacyContext) UserValue(_ any) any {
+	return c.userID
+}
diff --git a/internal/shared/pkg/apperrors/delete_conflict.go b/internal/shared/pkg/apperrors/delete_conflict.go
new file mode 100644
index 0000000..e0d0e4c
--- /dev/null
+++ b/internal/shared/pkg/apperrors/delete_conflict.go
@@ -0,0 +1,57 @@
+package apperrors
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+)
+
+type DeleteConflictError struct {
+	RelatedModules []string
+}
+
+func (e *DeleteConflictError) Error() string {
+	modules := cleanModules(e.RelatedModules)
+	if len(modules) == 0 {
+		return "cannot delete this data because it is currently used by another module. please remove the relation first"
+	}
+	return fmt.Sprintf(
+		"cannot delete this data because it is currently used by %s. please remove the relation first",
+		strings.Join(modules, ", "),
+	)
+}
+
+func IsDeleteConflict(err error) bool {
+	var target *DeleteConflictError
+	return errors.As(err, &target)
+}
+
+func AsDeleteConflict(err error) (*DeleteConflictError, bool) {
+	var target *DeleteConflictError
+	if !errors.As(err, &target) {
+		return nil, false
+	}
+	return target, true
+}
+
+func NewDeleteConflictError(relatedModules ...string) error {
+	return &DeleteConflictError{RelatedModules: cleanModules(relatedModules)}
+}
+
+func cleanModules(in []string) []string {
+	out := make([]string, 0, len(in))
+	seen := map[string]struct{}{}
+	for _, module := range in {
+		trimmed := strings.TrimSpace(module)
+		if trimmed == "" {
+			continue
+		}
+		key := strings.ToLower(trimmed)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		out = append(out, trimmed)
+	}
+	return out
+}
diff --git a/internal/shared/pkg/apperrorsx/apperror.go b/internal/shared/pkg/apperrorsx/apperror.go
new file mode 100644
index 0000000..ede7491
--- /dev/null
+++ b/internal/shared/pkg/apperrorsx/apperror.go
@@ -0,0 +1,36 @@
+package apperrorsx
+
+import "wucher/internal/transport/http/jsonapi"
+
+// AppError is the canonical backend error contract used by translators and writers.
+type AppError struct {
+	Status    int
+	Code      string
+	ErrorCode string
+	Title     string
+	Message   string
+	Detail    any
+	Source    *jsonapi.ErrorSource
+	Cause     error
+}
+
+func (e *AppError) Error() string {
+	if e == nil {
+		return ""
+	}
+	if e.Message != "" {
+		return e.Message
+	}
+	if e.Cause != nil {
+		return e.Cause.Error()
+	}
+	return e.Code
+}
+
+func (e *AppError) WithCause(err error) *AppError {
+	if e == nil {
+		return nil
+	}
+	e.Cause = err
+	return e
+}
diff --git a/internal/shared/pkg/apperrorsx/codes.go b/internal/shared/pkg/apperrorsx/codes.go
new file mode 100644
index 0000000..9137532
--- /dev/null
+++ b/internal/shared/pkg/apperrorsx/codes.go
@@ -0,0 +1,183 @@
+package apperrorsx
+
+import (
+	"fmt"
+	"net/http"
+)
+
+const (
+	ModuleGeneral                  = "00"
+	ModuleAuth                     = "01"
+	ModulePIN                      = "02"
+	ModuleHelicopter               = "03"
+	ModuleHelicopterUsage          = "35"
+	ModuleUser                     = "04"
+	ModuleMasterData               = "05"
+	ModuleDutyRoster               = "06"
+	ModuleFlight                   = "07"
+	ModuleContact                  = "08"
+	ModuleMissionOps               = "09"
+	ModuleFacility                 = "10"
+	ModuleHospital                 = "11"
+	ModuleFederalState             = "12"
+	ModuleNationality              = "13"
+	ModuleICAO                     = "14"
+	ModuleLand                     = "15"
+	ModuleBase                     = "16"
+	ModuleHealthInsuranceCompanies = "17"
+	ModuleVocation                 = "18"
+	ModuleMedicine                 = "19"
+	ModuleMasterSettings           = "20"
+	ModuleFileManager              = "21"
+	ModuleOPCData                  = "22"
+	ModulePatientData              = "23"
+	ModuleInsurancePatientData     = "24"
+	ModuleRole                     = "25"
+	ModuleFlightData               = "26"
+	ModuleAirRescuerChecklist      = "27"
+	ModuleBranding                 = "28"
+	ModuleDUL                      = "29"
+	ModuleTakeover                 = "30"
+	ModuleFleetStatus              = "31"
+	ModuleComplaint                = "32"
+	ModuleEASARelease              = "33"
+	ModuleMCF                      = "34"
+	ModuleHelicopterUsageSync      = "35"
+	ModuleFMReport                 = "36"
+	ModuleAfterFlightInspection    = "37"
+	ModuleActionSignoff            = "38"
+)
+
+// ContextKeyHTTPErrorDetail stores the original, non-sanitized error detail for
+// request logging. HTTP response writers should sanitize the public payload but
+// keep this local available for access logs.
+const ContextKeyHTTPErrorDetail = "http_error_detail"
+
+// ContextKeyHTTPErrorInternalDetail stores an internal-only, verbose error
+// summary for request logging. Unlike ContextKeyHTTPErrorDetail, this is not
+// meant for public response sanitizers.
+const ContextKeyHTTPErrorInternalDetail = "http_error_internal_detail"
+
+type Def struct {
+	Status    int
+	Code      string
+	ErrorCode string
+	Title     string
+	Message   string
+}
+
+func Build(status int, moduleCode, caseCode, code, message string) Def {
+	return BuildWithTitle(
+		status,
+		moduleCode,
+		caseCode,
+		code,
+		titleForStatus(status),
+		message,
+	)
+}
+
+func BuildWithTitle(status int, moduleCode, caseCode, code, title, message string) Def {
+	return Def{
+		Status:    status,
+		Code:      code,
+		ErrorCode: fmt.Sprintf("%03d%s%s", status, moduleCode, caseCode),
+		Title:     title,
+		Message:   message,
+	}
+}
+
+func titleForStatus(status int) string {
+	switch status {
+	case http.StatusAccepted:
+		return "Accepted"
+	case http.StatusBadRequest:
+		return "Bad Request"
+	case http.StatusUnauthorized:
+		return "Unauthorized"
+	case http.StatusLocked:
+		return "Locked"
+	case http.StatusForbidden:
+		return "Forbidden"
+	case http.StatusNotFound:
+		return "Not found"
+	case http.StatusConflict:
+		return "Conflict"
+	case http.StatusUnprocessableEntity:
+		return "Validation error"
+	case http.StatusTooManyRequests:
+		return "Too many requests"
+	default:
+		return "Internal server error"
+	}
+}
+
+func New(def Def) *AppError {
+	return &AppError{
+		Status:    def.Status,
+		Code:      def.Code,
+		ErrorCode: def.ErrorCode,
+		Title:     def.Title,
+		Message:   def.Message,
+	}
+}
+
+func DefGeneral(status int, caseCode, code, message string) Def {
+	return Build(status, ModuleGeneral, caseCode, code, message)
+}
+
+func DefGeneralWithTitle(status int, caseCode, code, title, message string) Def {
+	return BuildWithTitle(status, ModuleGeneral, caseCode, code, title, message)
+}
+
+func DefAuth(status int, caseCode, code, message string) Def {
+	return Build(status, ModuleAuth, caseCode, code, message)
+}
+
+func DefPIN(status int, caseCode, code, message string) Def {
+	return Build(status, ModulePIN, caseCode, code, message)
+}
+
+func DefPINWithTitle(status int, caseCode, code, title, message string) Def {
+	return BuildWithTitle(status, ModulePIN, caseCode, code, title, message)
+}
+
+func DefHelicopter(status int, caseCode, code, message string) Def {
+	return Build(status, ModuleHelicopter, caseCode, code, message)
+}
+
+func DefHelicopterWithTitle(status int, caseCode, code, title, message string) Def {
+	return BuildWithTitle(status, ModuleHelicopter, caseCode, code, title, message)
+}
+
+func DefHelicopterUsage(status int, caseCode, code, message string) Def {
+	return Build(status, ModuleHelicopterUsage, caseCode, code, message)
+}
+
+func DefHelicopterUsageWithTitle(status int, caseCode, code, title, message string) Def {
+	return BuildWithTitle(status, ModuleHelicopterUsage, caseCode, code, title, message)
+}
+
+func DefHelicopterUsageSync(status int, caseCode, code, message string) Def {
+	return Build(status, ModuleHelicopterUsageSync, caseCode, code, message)
+}
+
+func DefHelicopterUsageSyncWithTitle(status int, caseCode, code, title, message string) Def {
+	return BuildWithTitle(status, ModuleHelicopterUsageSync, caseCode, code, title, message)
+}
+
+func DefFMReport(status int, caseCode, code, message string) Def {
+	return Build(status, ModuleFMReport, caseCode, code, message)
+}
+
+func DefFMReportWithTitle(status int, caseCode, code, title, message string) Def {
+	return BuildWithTitle(status, ModuleFMReport, caseCode, code, title, message)
+}
+
+func DefByModule(moduleCode string, status int, caseCode, code, message string) Def {
+	return Build(status, moduleCode, caseCode, code, message)
+}
+
+func DefByModuleWithTitle(moduleCode string, status int, caseCode, code, title, message string) Def {
+	return BuildWithTitle(status, moduleCode, caseCode, code, title, message)
+}
diff --git a/internal/shared/pkg/apperrorsx/codes_defs.go b/internal/shared/pkg/apperrorsx/codes_defs.go
new file mode 100644
index 0000000..2b86964
--- /dev/null
+++ b/internal/shared/pkg/apperrorsx/codes_defs.go
@@ -0,0 +1,2601 @@
+// Centralized error definitions.
+package apperrorsx
+
+import "net/http"
+
+const (
+	CodeInvalidRequest                = "INVALID_REQUEST"
+	CodeInvalidDataType               = "INVALID_DATA_TYPE"
+	CodeDataNotFound                  = "DATA_NOT_FOUND"
+	CodeValidationError               = "VALIDATION_ERROR"
+	CodeBusinessRuleFailed            = "BUSINESS_RULE_FAILED"
+	CodeInternalServerError           = "INTERNAL_SERVER_ERROR"
+	CodeSessionExpired                = "SESSION_EXPIRED"
+	CodeTokenInvalid                  = "TOKEN_INVALID"
+	CodeUserUnauthorized              = "USER_UNAUTHORIZED"
+	CodeForbiddenAccess               = "FORBIDDEN_ACCESS"
+	CodeAuthInvalidJSON               = "AUTH_INVALID_JSON"
+	CodeAuthRegistrationDisabled      = "AUTH_REGISTRATION_DISABLED"
+	CodeAuthRoleNotFound              = "AUTH_ROLE_NOT_FOUND"
+	CodeAuthRegistrationFailed        = "AUTH_REGISTRATION_FAILED"
+	CodeAuthInviteFailed              = "AUTH_INVITE_FAILED"
+	CodeAuthSetPasswordFailed         = "AUTH_SET_PASSWORD_FAILED"
+	CodeAuthSetPasswordTokenInvalid   = "AUTH_SET_PASSWORD_TOKEN_INVALID"
+	CodeAuthUsernameAlreadyRegistered = "AUTH_USERNAME_ALREADY_REGISTERED"
+	CodeAuthResetPasswordInvalidLink  = "AUTH_RESET_PASSWORD_INVALID_LINK"
+	CodeAuthResetPasswordFailed       = "AUTH_RESET_PASSWORD_FAILED"
+
+	CodePINVerificationRequired = "PIN_VERIFICATION_REQUIRED"
+	CodePINIncorrect            = "PIN_INCORRECT"
+	CodePINBlocked              = "PIN_BLOCKED"
+	CodePINNotSet               = "PIN_NOT_SET"
+	CodePINNotBlocked           = "PIN_NOT_BLOCKED"
+	CodePINValidationFailed     = "PIN_VALIDATION_FAILED"
+	CodePINAttemptLimitReached  = "PIN_ATTEMPT_LIMIT_REACHED"
+
+	CodeHelicopterNotFound                = "HELICOPTER_NOT_FOUND"
+	CodeHelicopterDuplicate               = "HELICOPTER_DUPLICATE"
+	CodeHelicopterRelationDelete          = "HELICOPTER_RELATION_DELETE_ERROR"
+	CodeHelicopterInvalidPayload          = "HELICOPTER_INVALID_PAYLOAD"
+	CodeHelicopterInvalidType             = "HELICOPTER_INVALID_TYPE"
+	CodeHelicopterInvalidJSON             = "HELICOPTER_INVALID_JSON"
+	CodeHelicopterInvalidID               = "HELICOPTER_INVALID_ID"
+	CodeHelicopterIDRequired              = "HELICOPTER_ID_REQUIRED"
+	CodeHelicopterIDMismatch              = "HELICOPTER_ID_MISMATCH"
+	CodeHelicopterAttributesRequired      = "HELICOPTER_ATTRIBUTES_REQUIRED"
+	CodeHelicopterCreateFailed            = "HELICOPTER_CREATE_FAILED"
+	CodeHelicopterUpdateFailed            = "HELICOPTER_UPDATE_FAILED"
+	CodeHelicopterDeleteFailed            = "HELICOPTER_DELETE_FAILED"
+	CodeHelicopterGenerateFailed          = "HELICOPTER_GENERATE_FAILED"
+	CodeHelicopterListFailed              = "HELICOPTER_LIST_FAILED"
+	CodeHelicopterPinVerificationRequired = "HELICOPTER_PIN_VERIFICATION_REQUIRED"
+	CodeHelicopterUnauthorized            = "HELICOPTER_UNAUTHORIZED"
+	CodeHelicopterFileNotFound            = "HELICOPTER_FILE_NOT_FOUND"
+	CodeHelicopterFileInvalidPayload      = "HELICOPTER_FILE_INVALID_PAYLOAD"
+	CodeHelicopterFileInvalidJSON         = "HELICOPTER_FILE_INVALID_JSON"
+	CodeHelicopterFileInvalidUUID         = "HELICOPTER_FILE_INVALID_UUID"
+	CodeHelicopterFileSectionInvalid      = "HELICOPTER_FILE_SECTION_INVALID"
+	CodeHelicopterFileFileNameRequired    = "HELICOPTER_FILE_FILE_NAME_REQUIRED"
+	CodeHelicopterFileCreateFailed        = "HELICOPTER_FILE_CREATE_FAILED"
+	CodeHelicopterFileUpdateFailed        = "HELICOPTER_FILE_UPDATE_FAILED"
+	CodeHelicopterFileDeleteFailed        = "HELICOPTER_FILE_DELETE_FAILED"
+	CodeHelicopterFileGetFailed           = "HELICOPTER_FILE_GET_FAILED"
+	CodeHelicopterFileListFailed          = "HELICOPTER_FILE_LIST_FAILED"
+	CodeHelicopterUsageNotFound           = "HELICOPTER_USAGE_NOT_FOUND"
+	CodeHelicopterUsageDuplicate          = "HELICOPTER_USAGE_DUPLICATE"
+	CodeHelicopterUsageRelationDelete     = "HELICOPTER_USAGE_RELATION_DELETE_ERROR"
+	CodeHelicopterUsageInvalidPayload     = "HELICOPTER_USAGE_INVALID_PAYLOAD"
+	CodeHelicopterUsageInvalidJSON        = "HELICOPTER_USAGE_INVALID_JSON"
+	CodeHelicopterUsageInvalidUUID        = "HELICOPTER_USAGE_INVALID_UUID"
+	CodeHelicopterUsageIDRequired         = "HELICOPTER_USAGE_ID_REQUIRED"
+	CodeHelicopterUsageIDMismatch         = "HELICOPTER_USAGE_ID_MISMATCH"
+	CodeHelicopterUsageAttributesRequired = "HELICOPTER_USAGE_ATTRIBUTES_REQUIRED"
+	CodeHelicopterUsageCreateFailed       = "HELICOPTER_USAGE_CREATE_FAILED"
+	CodeHelicopterUsageGetFailed          = "HELICOPTER_USAGE_GET_FAILED"
+	CodeHelicopterUsageUpdateFailed       = "HELICOPTER_USAGE_UPDATE_FAILED"
+	CodeHelicopterUsageDeleteFailed       = "HELICOPTER_USAGE_DELETE_FAILED"
+	CodeHelicopterUsageListFailed         = "HELICOPTER_USAGE_LIST_FAILED"
+	CodeHelicopterUsageSyncFailed         = "HELICOPTER_USAGE_SYNC_FAILED"
+
+	CodeFMReportNotFound       = "FM_REPORT_NOT_FOUND"
+	CodeFMReportInvalidJSON    = "FM_REPORT_INVALID_JSON"
+	CodeFMReportInvalidUUID    = "FM_REPORT_INVALID_UUID"
+	CodeFMReportInvalidPayload = "FM_REPORT_INVALID_PAYLOAD"
+	CodeFMReportCompleteFailed = "FM_REPORT_COMPLETE_FAILED"
+	CodeFMReportLocked         = "FM_REPORT_LOCKED"
+
+	CodeUserNotFound           = "USER_NOT_FOUND"
+	CodeUserInvalidPayload     = "USER_INVALID_PAYLOAD"
+	CodeUserInvalidJSON        = "USER_INVALID_JSON"
+	CodeUserInvalidUUID        = "USER_INVALID_UUID"
+	CodeUserValidationFailed   = "USER_VALIDATION_FAILED"
+	CodeUserCreateFailed       = "USER_CREATE_FAILED"
+	CodeUserUpdateFailed       = "USER_UPDATE_FAILED"
+	CodeUserDeleteFailed       = "USER_DELETE_FAILED"
+	CodeUserListFailed         = "USER_LIST_FAILED"
+	CodeUserTimezoneInvalid    = "USER_TIMEZONE_INVALID"
+	CodeUserRoleIDsInvalid     = "USER_ROLE_IDS_INVALID"
+	CodeUserRoleIDsRequired    = "USER_ROLE_IDS_REQUIRED"
+	CodeUserPrimaryRoleInvalid = "USER_PRIMARY_ROLE_INVALID"
+
+	CodeMasterDataNotFound         = "MASTER_DATA_NOT_FOUND"
+	CodeMasterDataInvalidPayload   = "MASTER_DATA_INVALID_PAYLOAD"
+	CodeMasterDataInvalidJSON      = "MASTER_DATA_INVALID_JSON"
+	CodeMasterDataValidationFailed = "MASTER_DATA_VALIDATION_FAILED"
+	CodeMasterDataCreateFailed     = "MASTER_DATA_CREATE_FAILED"
+	CodeMasterDataUpdateFailed     = "MASTER_DATA_UPDATE_FAILED"
+	CodeMasterDataDeleteFailed     = "MASTER_DATA_DELETE_FAILED"
+	CodeMasterDataListFailed       = "MASTER_DATA_LIST_FAILED"
+
+	CodeDutyRosterNotFound               = "DUTY_ROSTER_NOT_FOUND"
+	CodeDutyRosterInvalidPayload         = "DUTY_ROSTER_INVALID_PAYLOAD"
+	CodeDutyRosterInvalidJSON            = "DUTY_ROSTER_INVALID_JSON"
+	CodeDutyRosterInvalidUUID            = "DUTY_ROSTER_INVALID_UUID"
+	CodeDutyRosterValidationFailed       = "DUTY_ROSTER_VALIDATION_FAILED"
+	CodeDutyRosterConflict               = "DUTY_ROSTER_CONFLICT"
+	CodeDutyRosterCreateFailed           = "DUTY_ROSTER_CREATE_FAILED"
+	CodeDutyRosterUpdateFailed           = "DUTY_ROSTER_UPDATE_FAILED"
+	CodeDutyRosterDeleteFailed           = "DUTY_ROSTER_DELETE_FAILED"
+	CodeDutyRosterListFailed             = "DUTY_ROSTER_LIST_FAILED"
+	CodeDutyRosterUnauthorized           = "DUTY_ROSTER_UNAUTHORIZED"
+	CodeDutyRosterBaseTypeInvalid        = "DUTY_ROSTER_BASE_TYPE_INVALID"
+	CodeDutyRosterRelationDeleteConflict = "DUTY_ROSTER_RELATION_DELETE_ERROR"
+	CodeDULNotFound                      = "DUL_NOT_FOUND"
+	CodeDULInvalidPayload                = "DUL_INVALID_PAYLOAD"
+	CodeDULInvalidJSON                   = "DUL_INVALID_JSON"
+	CodeDULInvalidUUID                   = "DUL_INVALID_UUID"
+	CodeDULValidationFailed              = "DUL_VALIDATION_FAILED"
+	CodeDULCreateFailed                  = "DUL_CREATE_FAILED"
+	CodeDULUpdateFailed                  = "DUL_UPDATE_FAILED"
+	CodeDULDeleteFailed                  = "DUL_DELETE_FAILED"
+	CodeDULListFailed                    = "DUL_LIST_FAILED"
+	CodeDULDateInvalid                   = "DUL_DATE_INVALID"
+
+	CodeFlightNotFound         = "FLIGHT_NOT_FOUND"
+	CodeFlightInvalidPayload   = "FLIGHT_INVALID_PAYLOAD"
+	CodeFlightInvalidJSON      = "FLIGHT_INVALID_JSON"
+	CodeFlightInvalidUUID      = "FLIGHT_INVALID_UUID"
+	CodeFlightValidationFailed = "FLIGHT_VALIDATION_FAILED"
+	CodeFlightCreateFailed     = "FLIGHT_CREATE_FAILED"
+	CodeFlightGetFailed        = "FLIGHT_GET_FAILED"
+	CodeFlightListFailed       = "FLIGHT_LIST_FAILED"
+	CodeFlightUnauthorized     = "FLIGHT_UNAUTHORIZED"
+	CodeFlightDateInvalid      = "FLIGHT_DATE_INVALID"
+
+	CodeNoIcaoCodeNotFound           = "NO_ICAO_CODE_NOT_FOUND"
+	CodeNoIcaoCodeRelationDelete     = "NO_ICAO_CODE_RELATION_DELETE_ERROR"
+	CodeNoIcaoCodeInvalidPayload     = "NO_ICAO_CODE_INVALID_PAYLOAD"
+	CodeNoIcaoCodeInvalidJSON        = "NO_ICAO_CODE_INVALID_JSON"
+	CodeNoIcaoCodeInvalidUUID        = "NO_ICAO_CODE_INVALID_UUID"
+	CodeNoIcaoCodeIDRequired         = "NO_ICAO_CODE_ID_REQUIRED"
+	CodeNoIcaoCodeIDMismatch         = "NO_ICAO_CODE_ID_MISMATCH"
+	CodeNoIcaoCodeAttributesRequired = "NO_ICAO_CODE_ATTRIBUTES_REQUIRED"
+	CodeNoIcaoCodeNameRequired       = "NO_ICAO_CODE_NAME_REQUIRED"
+	CodeNoIcaoCodeCreateFailed       = "NO_ICAO_CODE_CREATE_FAILED"
+	CodeNoIcaoCodeUpdateFailed       = "NO_ICAO_CODE_UPDATE_FAILED"
+	CodeNoIcaoCodeDeleteFailed       = "NO_ICAO_CODE_DELETE_FAILED"
+	CodeNoIcaoCodeListFailed         = "NO_ICAO_CODE_LIST_FAILED"
+	CodeHospitalNotFound             = CodeNoIcaoCodeNotFound
+	CodeHospitalRelationDelete       = CodeNoIcaoCodeRelationDelete
+	CodeHospitalInvalidPayload       = CodeNoIcaoCodeInvalidPayload
+	CodeHospitalInvalidJSON          = CodeNoIcaoCodeInvalidJSON
+	CodeHospitalInvalidUUID          = CodeNoIcaoCodeInvalidUUID
+	CodeHospitalIDRequired           = CodeNoIcaoCodeIDRequired
+	CodeHospitalIDMismatch           = CodeNoIcaoCodeIDMismatch
+	CodeHospitalAttributesRequired   = CodeNoIcaoCodeAttributesRequired
+	CodeHospitalNameRequired         = CodeNoIcaoCodeNameRequired
+	CodeHospitalCreateFailed         = CodeNoIcaoCodeCreateFailed
+	CodeHospitalUpdateFailed         = CodeNoIcaoCodeUpdateFailed
+	CodeHospitalDeleteFailed         = CodeNoIcaoCodeDeleteFailed
+	CodeHospitalListFailed           = CodeNoIcaoCodeListFailed
+
+	CodeBaseNotFound                  = "BASE_NOT_FOUND"
+	CodeBaseRelationDelete            = "BASE_DELETE_CONFLICT"
+	CodeBaseInvalidPayload            = "BASE_INVALID_PAYLOAD"
+	CodeBaseInvalidJSON               = "BASE_INVALID_JSON"
+	CodeBaseInvalidUUID               = "BASE_INVALID_UUID"
+	CodeBaseInvalidCategory           = "BASE_INVALID_CATEGORY"
+	CodeBaseAttributesRequired        = "BASE_ATTRIBUTES_REQUIRED"
+	CodeBaseNameRequired              = "BASE_NAME_REQUIRED"
+	CodeBaseDefaultShiftStartRequired = "BASE_DEFAULT_SHIFT_START_REQUIRED"
+	CodeBaseDefaultShiftEndRequired   = "BASE_DEFAULT_SHIFT_END_REQUIRED"
+	CodeBaseCreateFailed              = "BASE_CREATE_FAILED"
+	CodeBaseUpdateFailed              = "BASE_UPDATE_FAILED"
+	CodeBaseDeleteFailed              = "BASE_DELETE_FAILED"
+	CodeBaseListFailed                = "BASE_LIST_FAILED"
+	CodeBaseInvalidContactIDs         = "BASE_INVALID_CONTACT_IDS"
+	CodeBaseInvalidTime               = "BASE_INVALID_TIME"
+
+	CodeFacilityNotFound           = "FACILITY_NOT_FOUND"
+	CodeFacilityRelationDelete     = "FACILITY_RELATION_DELETE_ERROR"
+	CodeFacilityInvalidPayload     = "FACILITY_INVALID_PAYLOAD"
+	CodeFacilityInvalidJSON        = "FACILITY_INVALID_JSON"
+	CodeFacilityInvalidUUID        = "FACILITY_INVALID_UUID"
+	CodeFacilityAttributesRequired = "FACILITY_ATTRIBUTES_REQUIRED"
+	CodeFacilityCategoryRequired   = "FACILITY_CATEGORY_REQUIRED"
+	CodeFacilityNameRequired       = "FACILITY_NAME_REQUIRED"
+	CodeFacilityTypeRequired       = "FACILITY_TYPE_REQUIRED"
+	CodeFacilityCreateFailed       = "FACILITY_CREATE_FAILED"
+	CodeFacilityUpdateFailed       = "FACILITY_UPDATE_FAILED"
+	CodeFacilityDeleteFailed       = "FACILITY_DELETE_FAILED"
+	CodeFacilityListFailed         = "FACILITY_LIST_FAILED"
+
+	CodeFederalStateNotFound           = "FEDERAL_STATE_NOT_FOUND"
+	CodeFederalStateRelationDelete     = "FEDERAL_STATE_RELATION_DELETE_ERROR"
+	CodeFederalStateInvalidPayload     = "FEDERAL_STATE_INVALID_PAYLOAD"
+	CodeFederalStateInvalidJSON        = "FEDERAL_STATE_INVALID_JSON"
+	CodeFederalStateInvalidID          = "FEDERAL_STATE_INVALID_ID"
+	CodeFederalStateLandIDInvalid      = "FEDERAL_STATE_LAND_ID_INVALID"
+	CodeFederalStateIDRequired         = "FEDERAL_STATE_ID_REQUIRED"
+	CodeFederalStateIDMismatch         = "FEDERAL_STATE_ID_MISMATCH"
+	CodeFederalStateAttributesRequired = "FEDERAL_STATE_ATTRIBUTES_REQUIRED"
+	CodeFederalStateNameRequired       = "FEDERAL_STATE_NAME_REQUIRED"
+	CodeFederalStateCreateFailed       = "FEDERAL_STATE_CREATE_FAILED"
+	CodeFederalStateUpdateFailed       = "FEDERAL_STATE_UPDATE_FAILED"
+	CodeFederalStateDeleteFailed       = "FEDERAL_STATE_DELETE_FAILED"
+	CodeFederalStateListFailed         = "FEDERAL_STATE_LIST_FAILED"
+
+	CodeNationalityNotFound           = "NATIONALITY_NOT_FOUND"
+	CodeNationalityRelationDelete     = "NATIONALITY_RELATION_DELETE_ERROR"
+	CodeNationalityInvalidPayload     = "NATIONALITY_INVALID_PAYLOAD"
+	CodeNationalityInvalidJSON        = "NATIONALITY_INVALID_JSON"
+	CodeNationalityInvalidUUID        = "NATIONALITY_INVALID_UUID"
+	CodeNationalityIDRequired         = "NATIONALITY_ID_REQUIRED"
+	CodeNationalityIDMismatch         = "NATIONALITY_ID_MISMATCH"
+	CodeNationalityAttributesRequired = "NATIONALITY_ATTRIBUTES_REQUIRED"
+	CodeNationalityNameRequired       = "NATIONALITY_NAME_REQUIRED"
+	CodeNationalityCreateFailed       = "NATIONALITY_CREATE_FAILED"
+	CodeNationalityUpdateFailed       = "NATIONALITY_UPDATE_FAILED"
+	CodeNationalityDeleteFailed       = "NATIONALITY_DELETE_FAILED"
+	CodeNationalityListFailed         = "NATIONALITY_LIST_FAILED"
+
+	CodeCountryNotFound           = "COUNTRY_NOT_FOUND"
+	CodeCountryRelationDelete     = "COUNTRY_RELATION_DELETE_ERROR"
+	CodeCountryInvalidPayload     = "COUNTRY_INVALID_PAYLOAD"
+	CodeCountryInvalidJSON        = "COUNTRY_INVALID_JSON"
+	CodeCountryInvalidID          = "COUNTRY_INVALID_ID"
+	CodeCountryIDRequired         = "COUNTRY_ID_REQUIRED"
+	CodeCountryIDMismatch         = "COUNTRY_ID_MISMATCH"
+	CodeCountryAttributesRequired = "COUNTRY_ATTRIBUTES_REQUIRED"
+	CodeCountryNameRequired       = "COUNTRY_NAME_REQUIRED"
+	CodeCountryISOCodeInvalid     = "COUNTRY_ISO_CODE_INVALID"
+	CodeCountryISOCodeDuplicate   = "COUNTRY_ISO_CODE_DUPLICATE"
+	CodeCountryCreateFailed       = "COUNTRY_CREATE_FAILED"
+	CodeCountryUpdateFailed       = "COUNTRY_UPDATE_FAILED"
+	CodeCountryDeleteFailed       = "COUNTRY_DELETE_FAILED"
+	CodeCountryListFailed         = "COUNTRY_LIST_FAILED"
+	CodeLandNotFound              = CodeCountryNotFound
+	CodeLandRelationDelete        = CodeCountryRelationDelete
+	CodeLandInvalidPayload        = CodeCountryInvalidPayload
+	CodeLandInvalidJSON           = CodeCountryInvalidJSON
+	CodeLandInvalidID             = CodeCountryInvalidID
+	CodeLandIDRequired            = CodeCountryIDRequired
+	CodeLandIDMismatch            = CodeCountryIDMismatch
+	CodeLandAttributesRequired    = CodeCountryAttributesRequired
+	CodeLandNameRequired          = CodeCountryNameRequired
+	CodeLandISOCodeInvalid        = CodeCountryISOCodeInvalid
+	CodeLandISOCodeDuplicate      = CodeCountryISOCodeDuplicate
+	CodeLandCreateFailed          = CodeCountryCreateFailed
+	CodeLandUpdateFailed          = CodeCountryUpdateFailed
+	CodeLandDeleteFailed          = CodeCountryDeleteFailed
+	CodeLandListFailed            = CodeCountryListFailed
+
+	CodeICAONotFound            = "ICAO_NOT_FOUND"
+	CodeICAORelationDelete      = "ICAO_RELATION_DELETE_ERROR"
+	CodeICAOInvalidPayload      = "ICAO_INVALID_PAYLOAD"
+	CodeICAOInvalidJSON         = "ICAO_INVALID_JSON"
+	CodeICAOInvalidUUID         = "ICAO_INVALID_UUID"
+	CodeICAOIDRequired          = "ICAO_ID_REQUIRED"
+	CodeICAOIDMismatch          = "ICAO_ID_MISMATCH"
+	CodeICAOAttributesRequired  = "ICAO_ATTRIBUTES_REQUIRED"
+	CodeICAOCodeRequired        = "ICAO_CODE_REQUIRED"
+	CodeICAOLandIDInvalid       = "ICAO_LAND_ID_INVALID"
+	CodeICAOFederalStateInvalid = "ICAO_FEDERAL_STATE_ID_INVALID"
+	CodeICAOCreateFailed        = "ICAO_CREATE_FAILED"
+	CodeICAOUpdateFailed        = "ICAO_UPDATE_FAILED"
+	CodeICAODeleteFailed        = "ICAO_DELETE_FAILED"
+	CodeICAOListFailed          = "ICAO_LIST_FAILED"
+
+	CodeVocationNotFound           = "VOCATION_NOT_FOUND"
+	CodeVocationRelationDelete     = "VOCATION_RELATION_DELETE_ERROR"
+	CodeVocationInvalidPayload     = "VOCATION_INVALID_PAYLOAD"
+	CodeVocationInvalidJSON        = "VOCATION_INVALID_JSON"
+	CodeVocationInvalidUUID        = "VOCATION_INVALID_UUID"
+	CodeVocationIDRequired         = "VOCATION_ID_REQUIRED"
+	CodeVocationIDMismatch         = "VOCATION_ID_MISMATCH"
+	CodeVocationAttributesRequired = "VOCATION_ATTRIBUTES_REQUIRED"
+	CodeVocationNameRequired       = "VOCATION_NAME_REQUIRED"
+	CodeVocationCreateFailed       = "VOCATION_CREATE_FAILED"
+	CodeVocationUpdateFailed       = "VOCATION_UPDATE_FAILED"
+	CodeVocationDeleteFailed       = "VOCATION_DELETE_FAILED"
+	CodeVocationListFailed         = "VOCATION_LIST_FAILED"
+
+	CodeHealthInsuranceNotFound           = "HEALTH_INSURANCE_COMPANY_NOT_FOUND"
+	CodeHealthInsuranceRelationDelete     = "HEALTH_INSURANCE_COMPANY_RELATION_DELETE_ERROR"
+	CodeHealthInsuranceInvalidPayload     = "HEALTH_INSURANCE_COMPANY_INVALID_PAYLOAD"
+	CodeHealthInsuranceInvalidJSON        = "HEALTH_INSURANCE_COMPANY_INVALID_JSON"
+	CodeHealthInsuranceInvalidUUID        = "HEALTH_INSURANCE_COMPANY_INVALID_UUID"
+	CodeHealthInsuranceIDRequired         = "HEALTH_INSURANCE_COMPANY_ID_REQUIRED"
+	CodeHealthInsuranceIDMismatch         = "HEALTH_INSURANCE_COMPANY_ID_MISMATCH"
+	CodeHealthInsuranceAttributesRequired = "HEALTH_INSURANCE_COMPANY_ATTRIBUTES_REQUIRED"
+	CodeHealthInsuranceNameRequired       = "HEALTH_INSURANCE_COMPANY_NAME_REQUIRED"
+	CodeHealthInsuranceLandIDInvalid      = "HEALTH_INSURANCE_COMPANY_LAND_ID_INVALID"
+	CodeHealthInsuranceCreateFailed       = "HEALTH_INSURANCE_COMPANY_CREATE_FAILED"
+	CodeHealthInsuranceUpdateFailed       = "HEALTH_INSURANCE_COMPANY_UPDATE_FAILED"
+	CodeHealthInsuranceDeleteFailed       = "HEALTH_INSURANCE_COMPANY_DELETE_FAILED"
+	CodeHealthInsuranceListFailed         = "HEALTH_INSURANCE_COMPANY_LIST_FAILED"
+
+	CodeMedicineNotFound                = "MEDICINE_NOT_FOUND"
+	CodeMedicineRelationDelete          = "MEDICINE_RELATION_DELETE_ERROR"
+	CodeMedicineInvalidPayload          = "MEDICINE_INVALID_PAYLOAD"
+	CodeMedicineInvalidJSON             = "MEDICINE_INVALID_JSON"
+	CodeMedicineInvalidUUID             = "MEDICINE_INVALID_UUID"
+	CodeMedicineIDRequired              = "MEDICINE_ID_REQUIRED"
+	CodeMedicineIDMismatch              = "MEDICINE_ID_MISMATCH"
+	CodeMedicineAttributesRequired      = "MEDICINE_ATTRIBUTES_REQUIRED"
+	CodeMedicineNameRequired            = "MEDICINE_NAME_REQUIRED"
+	CodeMedicineGroupIDInvalid          = "MEDICINE_GROUP_ID_INVALID"
+	CodeMedicineMotorReactionIDInvalid  = "MEDICINE_MOTOR_REACTION_ID_INVALID"
+	CodeMedicineMotorReactionIDsInvalid = "MEDICINE_MOTOR_REACTION_IDS_INVALID"
+	CodeMedicineCreateFailed            = "MEDICINE_CREATE_FAILED"
+	CodeMedicineUpdateFailed            = "MEDICINE_UPDATE_FAILED"
+	CodeMedicineDeleteFailed            = "MEDICINE_DELETE_FAILED"
+	CodeMedicineListFailed              = "MEDICINE_LIST_FAILED"
+
+	CodeMasterSettingsNotFound              = "MASTER_SETTINGS_NOT_FOUND"
+	CodeMasterSettingsInvalidPayload        = "MASTER_SETTINGS_INVALID_PAYLOAD"
+	CodeMasterSettingsInvalidJSON           = "MASTER_SETTINGS_INVALID_JSON"
+	CodeMasterSettingsInvalidUUID           = "MASTER_SETTINGS_INVALID_UUID"
+	CodeMasterSettingsIDRequired            = "MASTER_SETTINGS_ID_REQUIRED"
+	CodeMasterSettingsIDMismatch            = "MASTER_SETTINGS_ID_MISMATCH"
+	CodeMasterSettingsAttributesRequired    = "MASTER_SETTINGS_ATTRIBUTES_REQUIRED"
+	CodeMasterSettingsCompanyNameRequired   = "MASTER_SETTINGS_COMPANY_NAME_REQUIRED"
+	CodeMasterSettingsLogoFileInvalid       = "MASTER_SETTINGS_LOGO_FILE_INVALID"
+	CodeMasterSettingsCoverFileInvalid      = "MASTER_SETTINGS_COVER_FILE_INVALID"
+	CodeMasterSettingsCreateFailed          = "MASTER_SETTINGS_CREATE_FAILED"
+	CodeMasterSettingsUpdateFailed          = "MASTER_SETTINGS_UPDATE_FAILED"
+	CodeMasterSettingsDeleteFailed          = "MASTER_SETTINGS_DELETE_FAILED"
+	CodeMasterSettingsGetFailed             = "MASTER_SETTINGS_GET_FAILED"
+	CodeMasterSettingsMicrosoftUpsertFailed = "MASTER_SETTINGS_MICROSOFT_ENTRA_UPSERT_FAILED"
+	CodeBrandingLogoFetchFailed             = "BRANDING_LOGO_FETCH_FAILED"
+	CodeBrandingCoverFetchFailed            = "BRANDING_COVER_FETCH_FAILED"
+	CodeBrandingEmailLogoFetchFailed        = "BRANDING_EMAIL_LOGO_FETCH_FAILED"
+	CodeBrandingContentFetchFailed          = "BRANDING_CONTENT_FETCH_FAILED"
+	CodeBrandingStorageUnavailable          = "BRANDING_STORAGE_UNAVAILABLE"
+	CodeBrandingFileManagerUnavailable      = "BRANDING_FILE_MANAGER_UNAVAILABLE"
+
+	CodeFileManagerStorageUnavailable           = "FILE_MANAGER_STORAGE_UNAVAILABLE"
+	CodeFileManagerQueueUnavailable             = "FILE_MANAGER_QUEUE_UNAVAILABLE"
+	CodeFileManagerUploadIntentUnavailable      = "FILE_MANAGER_UPLOAD_INTENT_UNAVAILABLE"
+	CodeFileManagerAttachmentServiceUnavailable = "FILE_MANAGER_ATTACHMENT_SERVICE_UNAVAILABLE"
+	CodeFileManagerFolderNotFound               = "FILE_MANAGER_FOLDER_NOT_FOUND"
+	CodeFileManagerFileNotFound                 = "FILE_MANAGER_FILE_NOT_FOUND"
+	CodeFileManagerAttachmentNotFound           = "FILE_MANAGER_ATTACHMENT_NOT_FOUND"
+	CodeFileManagerUploadIntentNotFound         = "FILE_MANAGER_UPLOAD_INTENT_NOT_FOUND"
+	CodeFileManagerStatusConflict               = "FILE_MANAGER_STATUS_CONFLICT"
+	CodeFileManagerUploadIntentConflict         = "FILE_MANAGER_UPLOAD_INTENT_CONFLICT"
+	CodeFileManagerValidationFailed             = "FILE_MANAGER_VALIDATION_FAILED"
+	CodeFileManagerActionFailed                 = "FILE_MANAGER_ACTION_FAILED"
+	CodeFileManagerWOPIServiceUnavailable       = "FILE_MANAGER_WOPI_SERVICE_UNAVAILABLE"
+	CodeFileManagerWOPIInvalidFileID            = "FILE_MANAGER_WOPI_INVALID_FILE_ID"
+	CodeFileManagerWOPIInvalidToken             = "FILE_MANAGER_WOPI_INVALID_TOKEN"
+	CodeFileManagerWOPIInvalidProof             = "FILE_MANAGER_WOPI_INVALID_PROOF"
+	CodeFileManagerWOPIPermissionDenied         = "FILE_MANAGER_WOPI_PERMISSION_DENIED"
+	CodeFileManagerWOPIFileNotFound             = "FILE_MANAGER_WOPI_FILE_NOT_FOUND"
+	CodeFileManagerWOPILockConflict             = "FILE_MANAGER_WOPI_LOCK_CONFLICT"
+	CodeFileManagerWOPIStaleTimestamp           = "FILE_MANAGER_WOPI_STALE_TIMESTAMP"
+	CodeFileManagerWOPIValidationFailed         = "FILE_MANAGER_WOPI_VALIDATION_FAILED"
+
+	CodeOPCNotFound           = "OPC_NOT_FOUND"
+	CodeOPCRelationDelete     = "OPC_RELATION_DELETE_ERROR"
+	CodeOPCInvalidPayload     = "OPC_INVALID_PAYLOAD"
+	CodeOPCInvalidJSON        = "OPC_INVALID_JSON"
+	CodeOPCInvalidUUID        = "OPC_INVALID_UUID"
+	CodeOPCIDRequired         = "OPC_ID_REQUIRED"
+	CodeOPCIDMismatch         = "OPC_ID_MISMATCH"
+	CodeOPCAttributesRequired = "OPC_ATTRIBUTES_REQUIRED"
+	CodeOPCTitleRequired      = "OPC_TITLE_REQUIRED"
+	CodeOPCCreateFailed       = "OPC_CREATE_FAILED"
+	CodeOPCUpdateFailed       = "OPC_UPDATE_FAILED"
+	CodeOPCDeleteFailed       = "OPC_DELETE_FAILED"
+	CodeOPCListFailed         = "OPC_LIST_FAILED"
+
+	CodeInsurancePatientDataNotFound                 = "INSURANCE_PATIENT_DATA_NOT_FOUND"
+	CodeInsurancePatientDataRelationDelete           = "INSURANCE_PATIENT_DATA_RELATION_DELETE_ERROR"
+	CodeInsurancePatientDataInvalidPayload           = "INSURANCE_PATIENT_DATA_INVALID_PAYLOAD"
+	CodeInsurancePatientDataInvalidJSON              = "INSURANCE_PATIENT_DATA_INVALID_JSON"
+	CodeInsurancePatientDataInvalidUUID              = "INSURANCE_PATIENT_DATA_INVALID_UUID"
+	CodeInsurancePatientDataIDRequired               = "INSURANCE_PATIENT_DATA_ID_REQUIRED"
+	CodeInsurancePatientDataIDMismatch               = "INSURANCE_PATIENT_DATA_ID_MISMATCH"
+	CodeInsurancePatientDataAttributesRequired       = "INSURANCE_PATIENT_DATA_ATTRIBUTES_REQUIRED"
+	CodeInsurancePatientDataHealthInsuranceIDInvalid = "INSURANCE_PATIENT_DATA_HEALTH_INSURANCE_ID_INVALID"
+	CodeInsurancePatientDataFederalStateIDInvalid    = "INSURANCE_PATIENT_DATA_FEDERAL_STATE_ID_INVALID"
+	CodeInsurancePatientDataCreateFailed             = "INSURANCE_PATIENT_DATA_CREATE_FAILED"
+	CodeInsurancePatientDataUpdateFailed             = "INSURANCE_PATIENT_DATA_UPDATE_FAILED"
+	CodeInsurancePatientDataDeleteFailed             = "INSURANCE_PATIENT_DATA_DELETE_FAILED"
+	CodeInsurancePatientDataListFailed               = "INSURANCE_PATIENT_DATA_LIST_FAILED"
+
+	CodePatientDataNotFound                      = "PATIENT_DATA_NOT_FOUND"
+	CodePatientDataRelationDelete                = "PATIENT_DATA_RELATION_DELETE_ERROR"
+	CodePatientDataInvalidPayload                = "PATIENT_DATA_INVALID_PAYLOAD"
+	CodePatientDataInvalidJSON                   = "PATIENT_DATA_INVALID_JSON"
+	CodePatientDataInvalidUUID                   = "PATIENT_DATA_INVALID_UUID"
+	CodePatientDataIDRequired                    = "PATIENT_DATA_ID_REQUIRED"
+	CodePatientDataIDMismatch                    = "PATIENT_DATA_ID_MISMATCH"
+	CodePatientDataAttributesRequired            = "PATIENT_DATA_ATTRIBUTES_REQUIRED"
+	CodePatientDataFamilyNameRequired            = "PATIENT_DATA_FAMILY_NAME_REQUIRED"
+	CodePatientDataFirstNameRequired             = "PATIENT_DATA_FIRST_NAME_REQUIRED"
+	CodePatientDataBirthDateInvalid              = "PATIENT_DATA_BIRTH_DATE_INVALID"
+	CodePatientDataGenderInvalid                 = "PATIENT_DATA_GENDER_INVALID"
+	CodePatientDataOPCIDInvalid                  = "PATIENT_DATA_OPC_ID_INVALID"
+	CodePatientDataInsurancePatientDataIDInvalid = "PATIENT_DATA_INSURANCE_PATIENT_DATA_ID_INVALID"
+	CodePatientDataCreateFailed                  = "PATIENT_DATA_CREATE_FAILED"
+	CodePatientDataUpdateFailed                  = "PATIENT_DATA_UPDATE_FAILED"
+	CodePatientDataDeleteFailed                  = "PATIENT_DATA_DELETE_FAILED"
+	CodePatientDataListFailed                    = "PATIENT_DATA_LIST_FAILED"
+
+	CodeRoleNotFound                 = "ROLE_NOT_FOUND"
+	CodeRolePermissionNotFound       = "ROLE_PERMISSION_NOT_FOUND"
+	CodeRoleRelationDelete           = "ROLE_RELATION_DELETE_ERROR"
+	CodeRoleInvalidPayload           = "ROLE_INVALID_PAYLOAD"
+	CodeRoleInvalidJSON              = "ROLE_INVALID_JSON"
+	CodeRoleInvalidUUID              = "ROLE_INVALID_UUID"
+	CodeRoleInvalidPermissionUUID    = "ROLE_INVALID_PERMISSION_UUID"
+	CodeRoleIDRequired               = "ROLE_ID_REQUIRED"
+	CodeRoleIDMismatch               = "ROLE_ID_MISMATCH"
+	CodeRoleAttributesRequired       = "ROLE_ATTRIBUTES_REQUIRED"
+	CodeRoleNameRequired             = "ROLE_NAME_REQUIRED"
+	CodeRolePermissionIDRequired     = "ROLE_PERMISSION_ID_REQUIRED"
+	CodeRolePermissionIDsEmpty       = "ROLE_PERMISSION_IDS_EMPTY"
+	CodeRoleCreateFailed             = "ROLE_CREATE_FAILED"
+	CodeRoleUpdateFailed             = "ROLE_UPDATE_FAILED"
+	CodeRoleDeleteFailed             = "ROLE_DELETE_FAILED"
+	CodeRoleAssignFailed             = "ROLE_ASSIGN_FAILED"
+	CodeRoleRemoveFailed             = "ROLE_REMOVE_FAILED"
+	CodeRoleListFailed               = "ROLE_LIST_FAILED"
+	CodeRolePermissionListFailed     = "ROLE_PERMISSION_LIST_FAILED"
+	CodeRolePermissionUpdateFailed   = "ROLE_PERMISSION_UPDATE_FAILED"
+	CodeRolePermissionRequiresPINReq = "ROLE_PERMISSION_REQUIRES_PIN_REQUIRED"
+
+	CodeMissionNotFound           = "MISSION_NOT_FOUND"
+	CodeMissionInvalidPayload     = "MISSION_INVALID_PAYLOAD"
+	CodeMissionInvalidJSON        = "MISSION_INVALID_JSON"
+	CodeMissionInvalidFlightUUID  = "MISSION_INVALID_FLIGHT_UUID"
+	CodeMissionInvalidMissionUUID = "MISSION_INVALID_MISSION_UUID"
+	CodeMissionFlightIDRequired   = "MISSION_FLIGHT_ID_REQUIRED"
+	CodeMissionMissionIDRequired  = "MISSION_MISSION_ID_REQUIRED"
+	CodeMissionTypeInvalid        = "MISSION_TYPE_INVALID"
+	CodeMissionSubtypeRequired    = "MISSION_SUBTYPE_REQUIRED"
+	CodeMissionSubtypeInvalid     = "MISSION_SUBTYPE_INVALID"
+	CodeMissionSubtypeForbidden   = "MISSION_SUBTYPE_FORBIDDEN"
+	CodeMissionDuplicateFlight    = "MISSION_DUPLICATE_FLIGHT"
+	CodeMissionCreateFailed       = "MISSION_CREATE_FAILED"
+	CodeMissionUpdateFailed       = "MISSION_UPDATE_FAILED"
+	CodeMissionDeleteFailed       = "MISSION_DELETE_FAILED"
+	CodeMissionGetFailed          = "MISSION_GET_FAILED"
+	CodeMissionListFailed         = "MISSION_LIST_FAILED"
+	CodeMissionAfterFlightLocked  = "MISSION_AFTER_FLIGHT_LOCKED"
+
+	CodeMissionFileInvalidJSON        = "MISSION_FILE_INVALID_JSON"
+	CodeMissionFileValidation         = "MISSION_FILE_VALIDATION"
+	CodeMissionFileInvalidMissionUUID = "MISSION_FILE_INVALID_MISSION_UUID"
+	CodeMissionFileMissionNotFound    = "MISSION_FILE_MISSION_NOT_FOUND"
+	CodeMissionFileServiceUnavailable = "MISSION_FILE_SERVICE_UNAVAILABLE"
+	CodeMissionFileActionFailed       = "MISSION_FILE_ACTION_FAILED"
+
+	CodeFlightDataNotFound                     = "FLIGHT_DATA_NOT_FOUND"
+	CodeFlightDataInvalidPayload               = "FLIGHT_DATA_INVALID_PAYLOAD"
+	CodeFlightDataInvalidJSON                  = "FLIGHT_DATA_INVALID_JSON"
+	CodeFlightDataInvalidPathUUID              = "FLIGHT_DATA_INVALID_PATH_UUID"
+	CodeFlightDataMissionIDRequired            = "FLIGHT_DATA_MISSION_ID_REQUIRED"
+	CodeFlightDataCoPilotIDRequired            = "FLIGHT_DATA_CO_PILOT_ID_REQUIRED"
+	CodeFlightDataPilotIDRequired              = CodeFlightDataCoPilotIDRequired
+	CodeFlightDataMissionReference             = "FLIGHT_DATA_MISSION_REFERENCE"
+	CodeFlightDataPilotReference               = "FLIGHT_DATA_PILOT_REFERENCE"
+	CodeFlightDataInvalidUUID                  = "FLIGHT_DATA_INVALID_UUID"
+	CodeFlightDataInvalidRFC3339               = "FLIGHT_DATA_INVALID_RFC3339"
+	CodeFlightDataOriginLocationReference      = "FLIGHT_DATA_ORIGIN_LOCATION_REFERENCE"
+	CodeFlightDataDestinationLocationReference = "FLIGHT_DATA_DESTINATION_LOCATION_REFERENCE"
+	CodeFlightDataFacilityReference            = "FLIGHT_DATA_FACILITY_REFERENCE"
+	CodeFlightDataRequired                     = "FLIGHT_DATA_REQUIRED"
+	CodeFlightDataCreateFailed                 = "FLIGHT_DATA_CREATE_FAILED"
+	CodeFlightDataGetFailed                    = "FLIGHT_DATA_GET_FAILED"
+	CodeFlightDataAfterFlightIncomplete        = "FLIGHT_DATA_AFTER_FLIGHT_INCOMPLETE"
+	CodeFlightDataAfterFlightLocked            = "FLIGHT_DATA_AFTER_FLIGHT_LOCKED"
+	CodeAirRescuerChecklistNotFound            = "AIR_RESCUER_CHECKLIST_NOT_FOUND"
+	CodeAirRescuerChecklistItemNotFound        = "AIR_RESCUER_CHECKLIST_ITEM_NOT_FOUND"
+	CodeAirRescuerChecklistInvalidPayload      = "AIR_RESCUER_CHECKLIST_INVALID_PAYLOAD"
+	CodeAirRescuerChecklistInvalidJSON         = "AIR_RESCUER_CHECKLIST_INVALID_JSON"
+	CodeAirRescuerChecklistInvalidUUID         = "AIR_RESCUER_CHECKLIST_INVALID_UUID"
+	CodeAirRescuerChecklistIDMismatch          = "AIR_RESCUER_CHECKLIST_ID_MISMATCH"
+	CodeAirRescuerChecklistScopeInvalid        = "AIR_RESCUER_CHECKLIST_SCOPE_INVALID"
+	CodeAirRescuerChecklistScopeRequired       = "AIR_RESCUER_CHECKLIST_SCOPE_REQUIRED"
+	CodeAirRescuerChecklistTitleRequired       = "AIR_RESCUER_CHECKLIST_TITLE_REQUIRED"
+	CodeAirRescuerChecklistNameRequired        = "AIR_RESCUER_CHECKLIST_NAME_REQUIRED"
+	CodeAirRescuerChecklistBaseNotFound        = "AIR_RESCUER_CHECKLIST_BASE_NOT_FOUND"
+	CodeAirRescuerChecklistCreateFailed        = "AIR_RESCUER_CHECKLIST_CREATE_FAILED"
+	CodeAirRescuerChecklistUpdateFailed        = "AIR_RESCUER_CHECKLIST_UPDATE_FAILED"
+	CodeAirRescuerChecklistDeleteFailed        = "AIR_RESCUER_CHECKLIST_DELETE_FAILED"
+	CodeAirRescuerChecklistListFailed          = "AIR_RESCUER_CHECKLIST_LIST_FAILED"
+	CodeAirRescuerChecklistReorderFailed       = "AIR_RESCUER_CHECKLIST_REORDER_FAILED"
+	CodeAirRescuerChecklistValidationFailed    = "AIR_RESCUER_CHECKLIST_VALIDATION_FAILED"
+
+	CodeTakeoverNotFound           = "TAKEOVER_NOT_FOUND"
+	CodeTakeoverInvalidPayload     = "TAKEOVER_INVALID_PAYLOAD"
+	CodeTakeoverInvalidJSON        = "TAKEOVER_INVALID_JSON"
+	CodeTakeoverInvalidUUID        = "TAKEOVER_INVALID_UUID"
+	CodeTakeoverIDRequired         = "TAKEOVER_ID_REQUIRED"
+	CodeTakeoverIDMismatch         = "TAKEOVER_ID_MISMATCH"
+	CodeTakeoverFileSectionInvalid = "TAKEOVER_FILE_SECTION_INVALID"
+	CodeTakeoverCreateFailed       = "TAKEOVER_CREATE_FAILED"
+	CodeTakeoverUpdateFailed       = "TAKEOVER_UPDATE_FAILED"
+	CodeTakeoverDeleteFailed       = "TAKEOVER_DELETE_FAILED"
+	CodeTakeoverGetFailed          = "TAKEOVER_GET_FAILED"
+	CodeTakeoverListFailed         = "TAKEOVER_LIST_FAILED"
+	CodeTakeoverHelicopterInUse    = "TAKEOVER_HELICOPTER_IN_USE"
+	CodeTakeoverHelicopterAOG      = "TAKEOVER_HELICOPTER_AOG"
+	CodeTakeoverHelicopterMCF      = "TAKEOVER_HELICOPTER_MCF"
+
+	CodeHEMSOperationNotFound                 = "HEMS_OPERATION_NOT_FOUND"
+	CodeHEMSOperationInvalidPayload           = "HEMS_OPERATION_INVALID_PAYLOAD"
+	CodeHEMSOperationInvalidJSON              = "HEMS_OPERATION_INVALID_JSON"
+	CodeHEMSOperationInvalidUUID              = "HEMS_OPERATION_INVALID_UUID"
+	CodeHEMSOperationAttributesRequired       = "HEMS_OPERATION_ATTRIBUTES_REQUIRED"
+	CodeHEMSOperationDateInvalidRFC3339       = "HEMS_OPERATION_DATE_INVALID_RFC3339"
+	CodeHEMSOperationRelationReferenceInvalid = "HEMS_OPERATION_RELATION_REFERENCE_INVALID"
+	CodeHEMSOperationCreateFailed             = "HEMS_OPERATION_CREATE_FAILED"
+	CodeHEMSOperationUpdateFailed             = "HEMS_OPERATION_UPDATE_FAILED"
+	CodeHEMSOperationDeleteFailed             = "HEMS_OPERATION_DELETE_FAILED"
+	CodeHEMSOperationListFailed               = "HEMS_OPERATION_LIST_FAILED"
+	CodeForcesPresentNotFound                 = "FORCES_PRESENT_NOT_FOUND"
+	CodeForcesPresentRelationDelete           = "FORCES_PRESENT_RELATION_DELETE_ERROR"
+	CodeForcesPresentInvalidPayload           = "FORCES_PRESENT_INVALID_PAYLOAD"
+	CodeForcesPresentInvalidJSON              = "FORCES_PRESENT_INVALID_JSON"
+	CodeForcesPresentInvalidUUID              = "FORCES_PRESENT_INVALID_UUID"
+	CodeForcesPresentIDRequired               = "FORCES_PRESENT_ID_REQUIRED"
+	CodeForcesPresentIDMismatch               = "FORCES_PRESENT_ID_MISMATCH"
+	CodeForcesPresentAttributesRequired       = "FORCES_PRESENT_ATTRIBUTES_REQUIRED"
+	CodeForcesPresentNameRequired             = "FORCES_PRESENT_NAME_REQUIRED"
+	CodeForcesPresentCreateFailed             = "FORCES_PRESENT_CREATE_FAILED"
+	CodeForcesPresentUpdateFailed             = "FORCES_PRESENT_UPDATE_FAILED"
+	CodeForcesPresentDeleteFailed             = "FORCES_PRESENT_DELETE_FAILED"
+	CodeForcesPresentListFailed               = "FORCES_PRESENT_LIST_FAILED"
+
+	CodeContactNotFound                          = "CONTACT_NOT_FOUND"
+	CodeContactInvalidPayload                    = "CONTACT_INVALID_PAYLOAD"
+	CodeContactInvalidJSON                       = "CONTACT_INVALID_JSON"
+	CodeContactInvalidUserID                     = "CONTACT_INVALID_USER_ID"
+	CodeContactValidationFailed                  = "CONTACT_VALIDATION_FAILED"
+	CodeContactCreateFailed                      = "CONTACT_CREATE_FAILED"
+	CodeContactGetFailed                         = "CONTACT_GET_FAILED"
+	CodeContactUpdateFailed                      = "CONTACT_UPDATE_FAILED"
+	CodeContactUsernameConflict                  = "CONTACT_USERNAME_CONFLICT"
+	CodeContactDeleteFailed                      = "CONTACT_DELETE_FAILED"
+	CodeContactUpdateStatusFailed                = "CONTACT_UPDATE_STATUS_FAILED"
+	CodeContactUpdateRoleFailed                  = "CONTACT_UPDATE_ROLE_FAILED"
+	CodeContactUpdatePilotCategoryFailed         = "CONTACT_UPDATE_PILOT_CATEGORY_FAILED"
+	CodeContactUpdateLicenseFailed               = "CONTACT_UPDATE_LICENSE_FAILED"
+	CodeContactUpdateChiefFlagsFailed            = "CONTACT_UPDATE_CHIEF_FLAGS_FAILED"
+	CodeContactUpdateResponsibleComplaintsFailed = "CONTACT_UPDATE_RESPONSIBLE_COMPLAINTS_FAILED"
+	CodeContactBulkUpdateFailed                  = "CONTACT_BULK_UPDATE_FAILED"
+	CodeContactListFailed                        = "CONTACT_LIST_FAILED"
+
+	CodeFleetStatusNotFound           = "FLEET_STATUS_NOT_FOUND"
+	CodeFleetStatusInvalidPayload     = "FLEET_STATUS_INVALID_PAYLOAD"
+	CodeFleetStatusInvalidJSON        = "FLEET_STATUS_INVALID_JSON"
+	CodeFleetStatusInvalidID          = "FLEET_STATUS_INVALID_ID"
+	CodeFleetStatusIDRequired         = "FLEET_STATUS_ID_REQUIRED"
+	CodeFleetStatusIDMismatch         = "FLEET_STATUS_ID_MISMATCH"
+	CodeFleetStatusHelicopterRequired = "FLEET_STATUS_HELICOPTER_REQUIRED"
+	CodeFleetStatusHelicopterInvalid  = "FLEET_STATUS_HELICOPTER_INVALID"
+	CodeFleetStatusDuplicate          = "FLEET_STATUS_DUPLICATE"
+	CodeFleetStatusRelationDelete     = "FLEET_STATUS_RELATION_DELETE_ERROR"
+	CodeFleetStatusCreateFailed       = "FLEET_STATUS_CREATE_FAILED"
+	CodeFleetStatusUpdateFailed       = "FLEET_STATUS_UPDATE_FAILED"
+	CodeFleetStatusDeleteFailed       = "FLEET_STATUS_DELETE_FAILED"
+	CodeFleetStatusListFailed         = "FLEET_STATUS_LIST_FAILED"
+	CodeFleetStatusMarkServicedFailed = "FLEET_STATUS_MARK_SERVICED_FAILED"
+
+	CodeFleetStatusFileInvalidJSON         = "FLEET_STATUS_FILE_INVALID_JSON"
+	CodeFleetStatusFileInvalidPayload      = "FLEET_STATUS_FILE_INVALID_PAYLOAD"
+	CodeFleetStatusFileUploadIntentInvalid = "FLEET_STATUS_FILE_UPLOAD_INTENT_INVALID"
+	CodeFleetStatusFileStorageUnavailable  = "FLEET_STATUS_FILE_STORAGE_UNAVAILABLE"
+	CodeFleetStatusFileFailed              = "FLEET_STATUS_FILE_FAILED"
+
+	CodeComplaintNotFound            = "COMPLAINT_NOT_FOUND"
+	CodeComplaintInvalidPayload      = "COMPLAINT_INVALID_PAYLOAD"
+	CodeComplaintInvalidJSON         = "COMPLAINT_INVALID_JSON"
+	CodeComplaintInvalidUUID         = "COMPLAINT_INVALID_UUID"
+	CodeComplaintIDRequired          = "COMPLAINT_ID_REQUIRED"
+	CodeComplaintIDMismatch          = "COMPLAINT_ID_MISMATCH"
+	CodeComplaintCreateFailed        = "COMPLAINT_CREATE_FAILED"
+	CodeComplaintUpdateFailed        = "COMPLAINT_UPDATE_FAILED"
+	CodeComplaintDeleteFailed        = "COMPLAINT_DELETE_FAILED"
+	CodeComplaintListFailed          = "COMPLAINT_LIST_FAILED"
+	CodeComplaintGroupedListFailed   = "COMPLAINT_GROUPED_LIST_FAILED"
+	CodeComplaintRelationDelete      = "COMPLAINT_RELATION_DELETE_ERROR"
+	CodeComplaintInvalidHelicopterID = "COMPLAINT_INVALID_HELICOPTER_ID"
+	CodeComplaintMELRequired         = "COMPLAINT_MEL_REQUIRED"
+	CodeComplaintActionSignedLocked  = "COMPLAINT_ACTION_SIGNED_LOCKED"
+
+	CodeEASAReleaseNotFound          = "EASA_RELEASE_NOT_FOUND"
+	CodeEASAReleaseInvalidJSON       = "EASA_RELEASE_INVALID_JSON"
+	CodeEASAReleaseInvalidUUID       = "EASA_RELEASE_INVALID_UUID"
+	CodeEASAReleaseInvalidPayload    = "EASA_RELEASE_INVALID_PAYLOAD"
+	CodeEASAReleaseCreateFailed      = "EASA_RELEASE_CREATE_FAILED"
+	CodeEASAReleaseUpdateFailed      = "EASA_RELEASE_UPDATE_FAILED"
+	CodeEASAReleaseDeleteFailed      = "EASA_RELEASE_DELETE_FAILED"
+	CodeEASAReleaseListFailed        = "EASA_RELEASE_LIST_FAILED"
+	CodeEASAReleaseSignFailed        = "EASA_RELEASE_SIGN_FAILED"
+	CodeEASAReleaseAlreadySigned     = "EASA_RELEASE_ALREADY_SIGNED"
+	CodeEASAReleaseIncompleteForSign = "EASA_RELEASE_INCOMPLETE_FOR_SIGN"
+	CodeEASAReleaseSignoffRequired   = "EASA_RELEASE_SIGNOFF_REQUIRED"
+
+	CodeActionSignoffNotFound          = "ACTION_SIGNOFF_NOT_FOUND"
+	CodeActionSignoffInvalidUUID       = "ACTION_SIGNOFF_INVALID_UUID"
+	CodeActionSignoffInvalidJSON       = "ACTION_SIGNOFF_INVALID_JSON"
+	CodeActionSignoffSignFailed        = "ACTION_SIGNOFF_SIGN_FAILED"
+	CodeActionSignoffUnsignFailed      = "ACTION_SIGNOFF_UNSIGN_FAILED"
+	CodeActionSignoffComplaintNotFound = "ACTION_SIGNOFF_COMPLAINT_NOT_FOUND"
+	CodeActionSignoffActionRequired    = "ACTION_SIGNOFF_ACTION_REQUIRED"
+
+	CodeMCFNotFound       = "MCF_NOT_FOUND"
+	CodeMCFInvalidJSON    = "MCF_INVALID_JSON"
+	CodeMCFInvalidUUID    = "MCF_INVALID_UUID"
+	CodeMCFInvalidPayload = "MCF_INVALID_PAYLOAD"
+	CodeMCFCreateFailed   = "MCF_CREATE_FAILED"
+	CodeMCFCompleteFailed = "MCF_COMPLETE_FAILED"
+	CodeMCFNoOpen            = "MCF_NO_OPEN"
+	CodeMCFListFailed        = "MCF_LIST_FAILED"
+	CodeMCFHelicopterHasOpen = "MCF_HELICOPTER_HAS_OPEN"
+)
+
+const (
+	CaseGeneralInvalidRequest     = "01"
+	CaseGeneralInvalidDataType    = "06"
+	CaseGeneralDataNotFound       = "02"
+	CaseGeneralValidationError    = "03"
+	CaseGeneralBusinessRuleFailed = "04"
+	CaseGeneralInternalError      = "05"
+)
+
+const (
+	CaseAuthSessionExpired            = "01"
+	CaseAuthTokenInvalid              = "02"
+	CaseAuthUnauthorized              = "03"
+	CaseAuthForbidden                 = "04"
+	CaseAuthInvalidJSON               = "05"
+	CaseAuthRegistrationDisabled      = "06"
+	CaseAuthRoleNotFound              = "07"
+	CaseAuthRegistrationFailed        = "08"
+	CaseAuthInviteFailed              = "09"
+	CaseAuthSetPasswordFailed         = "10"
+	CaseAuthSetPasswordTokenInvalid   = "11"
+	CaseAuthUsernameAlreadyRegistered = "12"
+	CaseAuthResetPasswordInvalidLink  = "13"
+	CaseAuthResetPasswordFailed       = "14"
+)
+
+const (
+	CasePINIncorrect            = "01"
+	CasePINBlocked              = "02"
+	CasePINAttemptLimitReached  = "03"
+	CasePINNotSet               = "04"
+	CasePINValidationFailed     = "05"
+	CasePINVerificationRequired = "06"
+	CasePINNotBlocked           = "07"
+)
+
+const (
+	CaseHelicopterDuplicate               = "01"
+	CaseHelicopterNotFound                = "02"
+	CaseHelicopterRelationDelete          = "03"
+	CaseHelicopterInvalidPayload          = "04"
+	CaseHelicopterInvalidType             = "17"
+	CaseHelicopterInvalidJSON             = "05"
+	CaseHelicopterInvalidID               = "06"
+	CaseHelicopterIDRequired              = "07"
+	CaseHelicopterIDMismatch              = "08"
+	CaseHelicopterAttributesRequired      = "09"
+	CaseHelicopterCreateFailed            = "10"
+	CaseHelicopterUpdateFailed            = "11"
+	CaseHelicopterDeleteFailed            = "12"
+	CaseHelicopterGenerateFailed          = "13"
+	CaseHelicopterListFailed              = "14"
+	CaseHelicopterPinVerificationRequired = "15"
+	CaseHelicopterUnauthorized            = "16"
+	CaseHelicopterFileNotFound            = "18"
+	CaseHelicopterFileInvalidPayload      = "19"
+	CaseHelicopterFileInvalidJSON         = "20"
+	CaseHelicopterFileInvalidUUID         = "21"
+	CaseHelicopterFileSectionInvalid      = "22"
+	CaseHelicopterFileFileNameRequired    = "23"
+	CaseHelicopterFileCreateFailed        = "24"
+	CaseHelicopterFileUpdateFailed        = "25"
+	CaseHelicopterFileDeleteFailed        = "26"
+	CaseHelicopterFileGetFailed           = "27"
+	CaseHelicopterFileListFailed          = "28"
+	CaseHelicopterUsageNotFound           = "29"
+	CaseHelicopterUsageDuplicate          = "30"
+	CaseHelicopterUsageRelationDelete     = "31"
+	CaseHelicopterUsageInvalidPayload     = "32"
+	CaseHelicopterUsageInvalidJSON        = "33"
+	CaseHelicopterUsageInvalidUUID        = "34"
+	CaseHelicopterUsageIDRequired         = "35"
+	CaseHelicopterUsageIDMismatch         = "36"
+	CaseHelicopterUsageAttributesRequired = "37"
+	CaseHelicopterUsageCreateFailed       = "38"
+	CaseHelicopterUsageGetFailed          = "39"
+	CaseHelicopterUsageUpdateFailed       = "40"
+	CaseHelicopterUsageDeleteFailed       = "41"
+	CaseHelicopterUsageListFailed         = "42"
+	CaseHelicopterUsageSyncFailed         = "43"
+
+	CaseFMReportNotFound       = "01"
+	CaseFMReportInvalidJSON    = "02"
+	CaseFMReportInvalidUUID    = "03"
+	CaseFMReportInvalidPayload = "04"
+	CaseFMReportCompleteFailed = "05"
+	CaseFMReportLocked         = "06"
+)
+
+const (
+	CaseUserNotFound           = "01"
+	CaseUserInvalidPayload     = "02"
+	CaseUserInvalidJSON        = "03"
+	CaseUserInvalidUUID        = "04"
+	CaseUserValidationFailed   = "05"
+	CaseUserCreateFailed       = "06"
+	CaseUserUpdateFailed       = "07"
+	CaseUserDeleteFailed       = "08"
+	CaseUserListFailed         = "09"
+	CaseUserTimezoneInvalid    = "10"
+	CaseUserRoleIDsInvalid     = "11"
+	CaseUserRoleIDsRequired    = "12"
+	CaseUserPrimaryRoleInvalid = "13"
+)
+
+const (
+	CaseMasterDataNotFound         = "01"
+	CaseMasterDataInvalidPayload   = "02"
+	CaseMasterDataInvalidJSON      = "03"
+	CaseMasterDataValidationFailed = "04"
+	CaseMasterDataCreateFailed     = "05"
+	CaseMasterDataUpdateFailed     = "06"
+	CaseMasterDataDeleteFailed     = "07"
+	CaseMasterDataListFailed       = "08"
+)
+
+const (
+	CaseDutyRosterNotFound               = "01"
+	CaseDutyRosterInvalidPayload         = "02"
+	CaseDutyRosterInvalidJSON            = "03"
+	CaseDutyRosterInvalidUUID            = "04"
+	CaseDutyRosterValidationFailed       = "05"
+	CaseDutyRosterConflict               = "06"
+	CaseDutyRosterCreateFailed           = "07"
+	CaseDutyRosterUpdateFailed           = "08"
+	CaseDutyRosterDeleteFailed           = "09"
+	CaseDutyRosterListFailed             = "10"
+	CaseDutyRosterUnauthorized           = "11"
+	CaseDutyRosterBaseTypeInvalid        = "12"
+	CaseDutyRosterRelationDeleteConflict = "13"
+)
+
+const (
+	CaseDULNotFound         = "01"
+	CaseDULInvalidPayload   = "02"
+	CaseDULInvalidJSON      = "03"
+	CaseDULInvalidUUID      = "04"
+	CaseDULValidationFailed = "05"
+	CaseDULCreateFailed     = "06"
+	CaseDULUpdateFailed     = "07"
+	CaseDULDeleteFailed     = "08"
+	CaseDULListFailed       = "09"
+	CaseDULDateInvalid      = "10"
+)
+
+const (
+	CaseFlightNotFound         = "01"
+	CaseFlightInvalidPayload   = "02"
+	CaseFlightInvalidJSON      = "03"
+	CaseFlightInvalidUUID      = "04"
+	CaseFlightValidationFailed = "05"
+	CaseFlightCreateFailed     = "06"
+	CaseFlightGetFailed        = "07"
+	CaseFlightListFailed       = "08"
+	CaseFlightUnauthorized     = "09"
+	CaseFlightDateInvalid      = "10"
+)
+
+const (
+	CaseNoIcaoCodeNotFound           = "01"
+	CaseNoIcaoCodeRelationDelete     = "02"
+	CaseNoIcaoCodeInvalidPayload     = "03"
+	CaseNoIcaoCodeInvalidJSON        = "04"
+	CaseNoIcaoCodeInvalidUUID        = "05"
+	CaseNoIcaoCodeIDRequired         = "06"
+	CaseNoIcaoCodeIDMismatch         = "07"
+	CaseNoIcaoCodeAttributesRequired = "08"
+	CaseNoIcaoCodeNameRequired       = "09"
+	CaseNoIcaoCodeCreateFailed       = "10"
+	CaseNoIcaoCodeUpdateFailed       = "11"
+	CaseNoIcaoCodeDeleteFailed       = "12"
+	CaseNoIcaoCodeListFailed         = "13"
+	CaseHospitalNotFound             = CaseNoIcaoCodeNotFound
+	CaseHospitalRelationDelete       = CaseNoIcaoCodeRelationDelete
+	CaseHospitalInvalidPayload       = CaseNoIcaoCodeInvalidPayload
+	CaseHospitalInvalidJSON          = CaseNoIcaoCodeInvalidJSON
+	CaseHospitalInvalidUUID          = CaseNoIcaoCodeInvalidUUID
+	CaseHospitalIDRequired           = CaseNoIcaoCodeIDRequired
+	CaseHospitalIDMismatch           = CaseNoIcaoCodeIDMismatch
+	CaseHospitalAttributesRequired   = CaseNoIcaoCodeAttributesRequired
+	CaseHospitalNameRequired         = CaseNoIcaoCodeNameRequired
+	CaseHospitalCreateFailed         = CaseNoIcaoCodeCreateFailed
+	CaseHospitalUpdateFailed         = CaseNoIcaoCodeUpdateFailed
+	CaseHospitalDeleteFailed         = CaseNoIcaoCodeDeleteFailed
+	CaseHospitalListFailed           = CaseNoIcaoCodeListFailed
+)
+
+const (
+	CaseBaseNotFound                  = "01"
+	CaseBaseRelationDelete            = "15"
+	CaseBaseInvalidPayload            = "03"
+	CaseBaseInvalidJSON               = "04"
+	CaseBaseInvalidUUID               = "05"
+	CaseBaseInvalidCategory           = "06"
+	CaseBaseAttributesRequired        = "07"
+	CaseBaseNameRequired              = "08"
+	CaseBaseCreateFailed              = "09"
+	CaseBaseUpdateFailed              = "10"
+	CaseBaseDeleteFailed              = "11"
+	CaseBaseListFailed                = "12"
+	CaseBaseInvalidContactIDs         = "13"
+	CaseBaseInvalidTime               = "14"
+	CaseBaseDefaultShiftStartRequired = "16"
+	CaseBaseDefaultShiftEndRequired   = "17"
+)
+
+const (
+	CaseFacilityNotFound           = "01"
+	CaseFacilityRelationDelete     = "02"
+	CaseFacilityInvalidPayload     = "03"
+	CaseFacilityInvalidJSON        = "04"
+	CaseFacilityInvalidUUID        = "05"
+	CaseFacilityAttributesRequired = "06"
+	CaseFacilityCategoryRequired   = "07"
+	CaseFacilityNameRequired       = "08"
+	CaseFacilityTypeRequired       = "09"
+	CaseFacilityCreateFailed       = "10"
+	CaseFacilityUpdateFailed       = "11"
+	CaseFacilityDeleteFailed       = "12"
+	CaseFacilityListFailed         = "13"
+)
+
+const (
+	CaseFederalStateNotFound           = "01"
+	CaseFederalStateRelationDelete     = "02"
+	CaseFederalStateInvalidPayload     = "03"
+	CaseFederalStateInvalidJSON        = "04"
+	CaseFederalStateInvalidID          = "05"
+	CaseFederalStateLandIDInvalid      = "06"
+	CaseFederalStateIDRequired         = "07"
+	CaseFederalStateIDMismatch         = "08"
+	CaseFederalStateAttributesRequired = "09"
+	CaseFederalStateNameRequired       = "10"
+	CaseFederalStateCreateFailed       = "11"
+	CaseFederalStateUpdateFailed       = "12"
+	CaseFederalStateDeleteFailed       = "13"
+	CaseFederalStateListFailed         = "14"
+)
+
+const (
+	CaseNationalityNotFound           = "01"
+	CaseNationalityRelationDelete     = "02"
+	CaseNationalityInvalidPayload     = "03"
+	CaseNationalityInvalidJSON        = "04"
+	CaseNationalityInvalidUUID        = "05"
+	CaseNationalityIDRequired         = "06"
+	CaseNationalityIDMismatch         = "07"
+	CaseNationalityAttributesRequired = "08"
+	CaseNationalityNameRequired       = "09"
+	CaseNationalityCreateFailed       = "10"
+	CaseNationalityUpdateFailed       = "11"
+	CaseNationalityDeleteFailed       = "12"
+	CaseNationalityListFailed         = "13"
+)
+
+const (
+	CaseCountryNotFound           = "01"
+	CaseCountryRelationDelete     = "02"
+	CaseCountryInvalidPayload     = "03"
+	CaseCountryInvalidJSON        = "04"
+	CaseCountryInvalidID          = "05"
+	CaseCountryIDRequired         = "06"
+	CaseCountryIDMismatch         = "07"
+	CaseCountryAttributesRequired = "08"
+	CaseCountryNameRequired       = "09"
+	CaseCountryISOCodeInvalid     = "10"
+	CaseCountryISOCodeDuplicate   = "11"
+	CaseCountryCreateFailed       = "12"
+	CaseCountryUpdateFailed       = "13"
+	CaseCountryDeleteFailed       = "14"
+	CaseCountryListFailed         = "15"
+	CaseLandNotFound              = CaseCountryNotFound
+	CaseLandRelationDelete        = CaseCountryRelationDelete
+	CaseLandInvalidPayload        = CaseCountryInvalidPayload
+	CaseLandInvalidJSON           = CaseCountryInvalidJSON
+	CaseLandInvalidID             = CaseCountryInvalidID
+	CaseLandIDRequired            = CaseCountryIDRequired
+	CaseLandIDMismatch            = CaseCountryIDMismatch
+	CaseLandAttributesRequired    = CaseCountryAttributesRequired
+	CaseLandNameRequired          = CaseCountryNameRequired
+	CaseLandISOCodeInvalid        = CaseCountryISOCodeInvalid
+	CaseLandISOCodeDuplicate      = CaseCountryISOCodeDuplicate
+	CaseLandCreateFailed          = CaseCountryCreateFailed
+	CaseLandUpdateFailed          = CaseCountryUpdateFailed
+	CaseLandDeleteFailed          = CaseCountryDeleteFailed
+	CaseLandListFailed            = CaseCountryListFailed
+)
+
+const (
+	CaseICAONotFound            = "01"
+	CaseICAORelationDelete      = "02"
+	CaseICAOInvalidPayload      = "03"
+	CaseICAOInvalidJSON         = "04"
+	CaseICAOInvalidUUID         = "05"
+	CaseICAOIDRequired          = "06"
+	CaseICAOIDMismatch          = "07"
+	CaseICAOAttributesRequired  = "08"
+	CaseICAOCodeRequired        = "09"
+	CaseICAOLandIDInvalid       = "10"
+	CaseICAOFederalStateInvalid = "11"
+	CaseICAOCreateFailed        = "12"
+	CaseICAOUpdateFailed        = "13"
+	CaseICAODeleteFailed        = "14"
+	CaseICAOListFailed          = "15"
+)
+
+const (
+	CaseVocationNotFound           = "01"
+	CaseVocationRelationDelete     = "02"
+	CaseVocationInvalidPayload     = "03"
+	CaseVocationInvalidJSON        = "04"
+	CaseVocationInvalidUUID        = "05"
+	CaseVocationIDRequired         = "06"
+	CaseVocationIDMismatch         = "07"
+	CaseVocationAttributesRequired = "08"
+	CaseVocationNameRequired       = "09"
+	CaseVocationCreateFailed       = "10"
+	CaseVocationUpdateFailed       = "11"
+	CaseVocationDeleteFailed       = "12"
+	CaseVocationListFailed         = "13"
+)
+
+const (
+	CaseHealthInsuranceNotFound           = "01"
+	CaseHealthInsuranceRelationDelete     = "02"
+	CaseHealthInsuranceInvalidPayload     = "03"
+	CaseHealthInsuranceInvalidJSON        = "04"
+	CaseHealthInsuranceInvalidUUID        = "05"
+	CaseHealthInsuranceIDRequired         = "06"
+	CaseHealthInsuranceIDMismatch         = "07"
+	CaseHealthInsuranceAttributesRequired = "08"
+	CaseHealthInsuranceNameRequired       = "09"
+	CaseHealthInsuranceLandIDInvalid      = "10"
+	CaseHealthInsuranceCreateFailed       = "11"
+	CaseHealthInsuranceUpdateFailed       = "12"
+	CaseHealthInsuranceDeleteFailed       = "13"
+	CaseHealthInsuranceListFailed         = "14"
+)
+
+const (
+	CaseMedicineNotFound                = "01"
+	CaseMedicineRelationDelete          = "02"
+	CaseMedicineInvalidPayload          = "03"
+	CaseMedicineInvalidJSON             = "04"
+	CaseMedicineInvalidUUID             = "05"
+	CaseMedicineIDRequired              = "06"
+	CaseMedicineIDMismatch              = "07"
+	CaseMedicineAttributesRequired      = "08"
+	CaseMedicineNameRequired            = "09"
+	CaseMedicineGroupIDInvalid          = "10"
+	CaseMedicineMotorReactionIDInvalid  = "11"
+	CaseMedicineMotorReactionIDsInvalid = "12"
+	CaseMedicineCreateFailed            = "13"
+	CaseMedicineUpdateFailed            = "14"
+	CaseMedicineDeleteFailed            = "15"
+	CaseMedicineListFailed              = "16"
+)
+
+const (
+	CaseMasterSettingsNotFound            = "01"
+	CaseMasterSettingsInvalidPayload      = "02"
+	CaseMasterSettingsInvalidJSON         = "03"
+	CaseMasterSettingsInvalidUUID         = "04"
+	CaseMasterSettingsIDRequired          = "05"
+	CaseMasterSettingsIDMismatch          = "06"
+	CaseMasterSettingsAttributesRequired  = "07"
+	CaseMasterSettingsCompanyNameRequired = "08"
+	CaseMasterSettingsLogoFileInvalid     = "09"
+	CaseMasterSettingsCoverFileInvalid    = "10"
+	CaseMasterSettingsCreateFailed        = "11"
+	CaseMasterSettingsUpdateFailed        = "12"
+	CaseMasterSettingsDeleteFailed        = "13"
+	CaseMasterSettingsGetFailed           = "14"
+	CaseMasterSettingsMicrosoftUpsert     = "15"
+)
+
+const (
+	CaseBrandingLogoFetchFailed        = "01"
+	CaseBrandingCoverFetchFailed       = "02"
+	CaseBrandingEmailLogoFetchFailed   = "03"
+	CaseBrandingContentFetchFailed     = "04"
+	CaseBrandingStorageUnavailable     = "05"
+	CaseBrandingFileManagerUnavailable = "06"
+)
+
+const (
+	CaseFileManagerStorageUnavailable           = "01"
+	CaseFileManagerQueueUnavailable             = "02"
+	CaseFileManagerUploadIntentUnavailable      = "03"
+	CaseFileManagerAttachmentServiceUnavailable = "04"
+	CaseFileManagerFolderNotFound               = "05"
+	CaseFileManagerFileNotFound                 = "06"
+	CaseFileManagerAttachmentNotFound           = "07"
+	CaseFileManagerUploadIntentNotFound         = "08"
+	CaseFileManagerStatusConflict               = "09"
+	CaseFileManagerUploadIntentConflict         = "10"
+	CaseFileManagerValidationFailed             = "11"
+	CaseFileManagerActionFailed                 = "12"
+	CaseFileManagerWOPIServiceUnavailable       = "13"
+	CaseFileManagerWOPIInvalidFileID            = "14"
+	CaseFileManagerWOPIInvalidToken             = "15"
+	CaseFileManagerWOPIInvalidProof             = "16"
+	CaseFileManagerWOPIPermissionDenied         = "17"
+	CaseFileManagerWOPIFileNotFound             = "18"
+	CaseFileManagerWOPILockConflict             = "19"
+	CaseFileManagerWOPIStaleTimestamp           = "20"
+	CaseFileManagerWOPIValidationFailed         = "21"
+)
+
+const (
+	CaseOPCNotFound           = "01"
+	CaseOPCRelationDelete     = "02"
+	CaseOPCInvalidPayload     = "03"
+	CaseOPCInvalidJSON        = "04"
+	CaseOPCInvalidUUID        = "05"
+	CaseOPCIDRequired         = "06"
+	CaseOPCIDMismatch         = "07"
+	CaseOPCAttributesRequired = "08"
+	CaseOPCTitleRequired      = "09"
+	CaseOPCCreateFailed       = "10"
+	CaseOPCUpdateFailed       = "11"
+	CaseOPCDeleteFailed       = "12"
+	CaseOPCListFailed         = "13"
+)
+
+const (
+	CaseInsurancePatientDataNotFound                 = "01"
+	CaseInsurancePatientDataRelationDelete           = "02"
+	CaseInsurancePatientDataInvalidPayload           = "03"
+	CaseInsurancePatientDataInvalidJSON              = "04"
+	CaseInsurancePatientDataInvalidUUID              = "05"
+	CaseInsurancePatientDataIDRequired               = "06"
+	CaseInsurancePatientDataIDMismatch               = "07"
+	CaseInsurancePatientDataAttributesRequired       = "08"
+	CaseInsurancePatientDataHealthInsuranceIDInvalid = "09"
+	CaseInsurancePatientDataFederalStateIDInvalid    = "10"
+	CaseInsurancePatientDataCreateFailed             = "11"
+	CaseInsurancePatientDataUpdateFailed             = "12"
+	CaseInsurancePatientDataDeleteFailed             = "13"
+	CaseInsurancePatientDataListFailed               = "14"
+)
+
+const (
+	CasePatientDataNotFound                      = "01"
+	CasePatientDataRelationDelete                = "02"
+	CasePatientDataInvalidPayload                = "03"
+	CasePatientDataInvalidJSON                   = "04"
+	CasePatientDataInvalidUUID                   = "05"
+	CasePatientDataIDRequired                    = "06"
+	CasePatientDataIDMismatch                    = "07"
+	CasePatientDataAttributesRequired            = "08"
+	CasePatientDataFamilyNameRequired            = "09"
+	CasePatientDataFirstNameRequired             = "10"
+	CasePatientDataBirthDateInvalid              = "11"
+	CasePatientDataGenderInvalid                 = "12"
+	CasePatientDataOPCIDInvalid                  = "13"
+	CasePatientDataInsurancePatientDataIDInvalid = "14"
+	CasePatientDataCreateFailed                  = "15"
+	CasePatientDataUpdateFailed                  = "16"
+	CasePatientDataDeleteFailed                  = "17"
+	CasePatientDataListFailed                    = "18"
+)
+
+const (
+	CaseRoleNotFound                 = "01"
+	CaseRolePermissionNotFound       = "02"
+	CaseRoleRelationDelete           = "03"
+	CaseRoleInvalidPayload           = "04"
+	CaseRoleInvalidJSON              = "05"
+	CaseRoleInvalidUUID              = "06"
+	CaseRoleInvalidPermissionUUID    = "07"
+	CaseRoleIDRequired               = "08"
+	CaseRoleIDMismatch               = "09"
+	CaseRoleAttributesRequired       = "10"
+	CaseRoleNameRequired             = "11"
+	CaseRolePermissionIDRequired     = "12"
+	CaseRolePermissionIDsEmpty       = "13"
+	CaseRoleCreateFailed             = "14"
+	CaseRoleUpdateFailed             = "15"
+	CaseRoleDeleteFailed             = "16"
+	CaseRoleAssignFailed             = "17"
+	CaseRoleRemoveFailed             = "18"
+	CaseRoleListFailed               = "19"
+	CaseRolePermissionListFailed     = "20"
+	CaseRolePermissionUpdateFailed   = "21"
+	CaseRolePermissionRequiresPINReq = "22"
+)
+
+const (
+	CaseFlightDataNotFound                     = "01"
+	CaseFlightDataInvalidPayload               = "02"
+	CaseFlightDataInvalidJSON                  = "03"
+	CaseFlightDataInvalidPathUUID              = "04"
+	CaseFlightDataMissionIDRequired            = "05"
+	CaseFlightDataCoPilotIDRequired            = "06"
+	CaseFlightDataPilotIDRequired              = CaseFlightDataCoPilotIDRequired
+	CaseFlightDataMissionReference             = "07"
+	CaseFlightDataPilotReference               = "08"
+	CaseFlightDataInvalidUUID                  = "09"
+	CaseFlightDataInvalidRFC3339               = "10"
+	CaseFlightDataOriginLocationReference      = "11"
+	CaseFlightDataDestinationLocationReference = "12"
+	CaseFlightDataFacilityReference            = "13"
+	CaseFlightDataRequired                     = "14"
+	CaseFlightDataCreateFailed                 = "15"
+	CaseFlightDataGetFailed                    = "16"
+	CaseFlightDataAfterFlightIncomplete        = "17"
+	CaseFlightDataAfterFlightLocked            = "18"
+)
+
+const (
+	CaseAirRescuerChecklistNotFound         = "01"
+	CaseAirRescuerChecklistItemNotFound     = "02"
+	CaseAirRescuerChecklistInvalidPayload   = "03"
+	CaseAirRescuerChecklistInvalidJSON      = "04"
+	CaseAirRescuerChecklistInvalidUUID      = "05"
+	CaseAirRescuerChecklistIDMismatch       = "06"
+	CaseAirRescuerChecklistScopeInvalid     = "07"
+	CaseAirRescuerChecklistScopeRequired    = "08"
+	CaseAirRescuerChecklistTitleRequired    = "09"
+	CaseAirRescuerChecklistNameRequired     = "10"
+	CaseAirRescuerChecklistBaseNotFound     = "11"
+	CaseAirRescuerChecklistCreateFailed     = "12"
+	CaseAirRescuerChecklistUpdateFailed     = "13"
+	CaseAirRescuerChecklistDeleteFailed     = "14"
+	CaseAirRescuerChecklistListFailed       = "15"
+	CaseAirRescuerChecklistReorderFailed    = "16"
+	CaseAirRescuerChecklistValidationFailed = "17"
+
+	CaseTakeoverNotFound           = "01"
+	CaseTakeoverInvalidPayload     = "02"
+	CaseTakeoverInvalidJSON        = "03"
+	CaseTakeoverInvalidUUID        = "04"
+	CaseTakeoverIDRequired         = "05"
+	CaseTakeoverIDMismatch         = "06"
+	CaseTakeoverFileSectionInvalid = "07"
+	CaseTakeoverCreateFailed       = "08"
+	CaseTakeoverUpdateFailed       = "09"
+	CaseTakeoverDeleteFailed       = "10"
+	CaseTakeoverGetFailed          = "11"
+	CaseTakeoverListFailed         = "12"
+	CaseTakeoverHelicopterInUse    = "13"
+	CaseTakeoverHelicopterAOG      = "14"
+	CaseTakeoverHelicopterMCF      = "15"
+)
+
+const (
+	CaseFleetStatusNotFound           = "01"
+	CaseFleetStatusInvalidPayload     = "02"
+	CaseFleetStatusInvalidJSON        = "03"
+	CaseFleetStatusInvalidID          = "04"
+	CaseFleetStatusIDRequired         = "05"
+	CaseFleetStatusIDMismatch         = "06"
+	CaseFleetStatusHelicopterRequired = "07"
+	CaseFleetStatusHelicopterInvalid  = "08"
+	CaseFleetStatusDuplicate          = "09"
+	CaseFleetStatusRelationDelete     = "10"
+	CaseFleetStatusCreateFailed       = "11"
+	CaseFleetStatusUpdateFailed       = "12"
+	CaseFleetStatusDeleteFailed       = "13"
+	CaseFleetStatusListFailed         = "14"
+	CaseFleetStatusMarkServicedFailed = "15"
+
+	CaseFleetStatusFileInvalidJSON         = "16"
+	CaseFleetStatusFileInvalidPayload      = "17"
+	CaseFleetStatusFileUploadIntentInvalid = "19"
+	CaseFleetStatusFileStorageUnavailable  = "20"
+	CaseFleetStatusFileFailed              = "21"
+)
+
+const (
+	CaseHEMSOperationNotFound                 = "01"
+	CaseHEMSOperationInvalidPayload           = "02"
+	CaseHEMSOperationInvalidJSON              = "03"
+	CaseHEMSOperationInvalidUUID              = "04"
+	CaseHEMSOperationAttributesRequired       = "05"
+	CaseHEMSOperationDateInvalidRFC3339       = "06"
+	CaseHEMSOperationRelationReferenceInvalid = "07"
+	CaseHEMSOperationCreateFailed             = "08"
+	CaseHEMSOperationUpdateFailed             = "09"
+	CaseHEMSOperationDeleteFailed             = "10"
+	CaseHEMSOperationListFailed               = "11"
+)
+
+const (
+	CaseForcesPresentNotFound           = "12"
+	CaseForcesPresentRelationDelete     = "13"
+	CaseForcesPresentInvalidPayload     = "14"
+	CaseForcesPresentInvalidJSON        = "15"
+	CaseForcesPresentInvalidUUID        = "16"
+	CaseForcesPresentIDRequired         = "17"
+	CaseForcesPresentIDMismatch         = "18"
+	CaseForcesPresentAttributesRequired = "19"
+	CaseForcesPresentNameRequired       = "20"
+	CaseForcesPresentCreateFailed       = "21"
+	CaseForcesPresentUpdateFailed       = "22"
+	CaseForcesPresentDeleteFailed       = "23"
+	CaseForcesPresentListFailed         = "24"
+)
+
+const (
+	CaseMissionNotFound           = "25"
+	CaseMissionInvalidPayload     = "26"
+	CaseMissionInvalidJSON        = "27"
+	CaseMissionInvalidFlightUUID  = "28"
+	CaseMissionFlightIDRequired   = "29"
+	CaseMissionMissionIDRequired  = "30"
+	CaseMissionTypeInvalid        = "31"
+	CaseMissionSubtypeRequired    = "32"
+	CaseMissionSubtypeInvalid     = "33"
+	CaseMissionSubtypeForbidden   = "34"
+	CaseMissionDuplicateFlight    = "35"
+	CaseMissionCreateFailed       = "36"
+	CaseMissionUpdateFailed       = "37"
+	CaseMissionDeleteFailed       = "38"
+	CaseMissionGetFailed          = "39"
+	CaseMissionInvalidMissionUUID = "40"
+	CaseMissionListFailed         = "41"
+	CaseMissionAfterFlightLocked  = "42"
+
+	CaseMissionFileInvalidJSON        = "43"
+	CaseMissionFileValidation         = "44"
+	CaseMissionFileInvalidMissionUUID = "45"
+	CaseMissionFileMissionNotFound    = "46"
+	CaseMissionFileServiceUnavailable = "47"
+	CaseMissionFileActionFailed       = "48"
+)
+
+const (
+	CaseContactNotFound                          = "01"
+	CaseContactInvalidPayload                    = "02"
+	CaseContactInvalidJSON                       = "03"
+	CaseContactInvalidUserID                     = "04"
+	CaseContactValidationFailed                  = "05"
+	CaseContactCreateFailed                      = "06"
+	CaseContactGetFailed                         = "07"
+	CaseContactUpdateFailed                      = "08"
+	CaseContactUsernameConflict                  = "09"
+	CaseContactDeleteFailed                      = "10"
+	CaseContactUpdateStatusFailed                = "11"
+	CaseContactUpdateRoleFailed                  = "12"
+	CaseContactUpdatePilotCategoryFailed         = "13"
+	CaseContactUpdateLicenseFailed               = "14"
+	CaseContactUpdateChiefFlagsFailed            = "15"
+	CaseContactUpdateResponsibleComplaintsFailed = "16"
+	CaseContactBulkUpdateFailed                  = "17"
+	CaseContactListFailed                        = "18"
+)
+
+var (
+	// General
+	ErrInvalidRequest     = DefGeneral(http.StatusBadRequest, CaseGeneralInvalidRequest, CodeInvalidRequest, "invalid request")
+	ErrInvalidDataType    = DefGeneralWithTitle(http.StatusUnprocessableEntity, CaseGeneralInvalidDataType, CodeInvalidDataType, "Invalid data type", "a field was sent with the wrong data type")
+	ErrDataNotFound       = DefGeneral(http.StatusNotFound, CaseGeneralDataNotFound, CodeDataNotFound, "data not found")
+	ErrValidation         = DefGeneral(http.StatusUnprocessableEntity, CaseGeneralValidationError, CodeValidationError, "validation error")
+	ErrBusinessRuleFailed = DefGeneralWithTitle(http.StatusUnprocessableEntity, CaseGeneralBusinessRuleFailed, CodeBusinessRuleFailed, "Business rule failed", "business rule validation failed")
+	ErrInternal           = DefGeneral(http.StatusInternalServerError, CaseGeneralInternalError, CodeInternalServerError, "internal server error")
+
+	// Auth
+	ErrSessionExpired                = DefAuth(http.StatusUnauthorized, CaseAuthSessionExpired, CodeSessionExpired, "session expired")
+	ErrTokenInvalid                  = DefAuth(http.StatusUnauthorized, CaseAuthTokenInvalid, CodeTokenInvalid, "token is invalid")
+	ErrUserUnauthorized              = DefAuth(http.StatusUnauthorized, CaseAuthUnauthorized, CodeUserUnauthorized, "user is unauthorized")
+	ErrForbiddenAccess               = DefAuth(http.StatusForbidden, CaseAuthForbidden, CodeForbiddenAccess, "forbidden access")
+	ErrAuthInvalidJSON               = DefAuth(http.StatusBadRequest, CaseAuthInvalidJSON, CodeAuthInvalidJSON, "invalid json")
+	ErrAuthRegistrationDisabled      = DefAuth(http.StatusForbidden, CaseAuthRegistrationDisabled, CodeAuthRegistrationDisabled, "registration is disabled")
+	ErrAuthRoleNotFound              = DefAuth(http.StatusBadRequest, CaseAuthRoleNotFound, CodeAuthRoleNotFound, "public registration role not found")
+	ErrAuthRegistrationFailed        = DefAuth(http.StatusBadRequest, CaseAuthRegistrationFailed, CodeAuthRegistrationFailed, "registration failed")
+	ErrAuthInviteFailed              = DefAuth(http.StatusBadRequest, CaseAuthInviteFailed, CodeAuthInviteFailed, "invite failed")
+	ErrAuthSetPasswordFailed         = DefAuth(http.StatusBadRequest, CaseAuthSetPasswordFailed, CodeAuthSetPasswordFailed, "set password failed")
+	ErrAuthSetPasswordTokenInvalid   = DefAuth(http.StatusBadRequest, CaseAuthSetPasswordTokenInvalid, CodeAuthSetPasswordTokenInvalid, "set password token invalid")
+	ErrAuthUsernameAlreadyRegistered = DefAuth(http.StatusBadRequest, CaseAuthUsernameAlreadyRegistered, CodeAuthUsernameAlreadyRegistered, "username already registered")
+	ErrAuthResetPasswordInvalidLink  = DefAuth(http.StatusBadRequest, CaseAuthResetPasswordInvalidLink, CodeAuthResetPasswordInvalidLink, "reset password link invalid")
+	ErrAuthResetPasswordFailed       = DefAuth(http.StatusInternalServerError, CaseAuthResetPasswordFailed, CodeAuthResetPasswordFailed, "reset password failed")
+
+	// PIN
+	ErrPINVerificationRequired202 = DefPINWithTitle(http.StatusAccepted, CasePINVerificationRequired, CodePINVerificationRequired, "PIN verification required", "valid PIN action token is required")
+	ErrPINIncorrect               = DefPIN(http.StatusUnauthorized, CasePINIncorrect, CodePINIncorrect, "invalid security pin")
+	ErrPINBlocked                 = DefPIN(http.StatusLocked, CasePINBlocked, CodePINBlocked, "PIN has been blocked")
+	ErrPINNotSet                  = DefPINWithTitle(http.StatusConflict, CasePINNotSet, CodePINNotSet, "PIN not configured", "security PIN is not set")
+	ErrPINNotBlocked              = DefPINWithTitle(http.StatusConflict, CasePINNotBlocked, CodePINNotBlocked, "PIN not blocked", "security PIN is not blocked")
+	ErrPINValidationFailed        = DefPIN(http.StatusUnprocessableEntity, CasePINValidationFailed, CodePINValidationFailed, "PIN validation failed")
+	ErrPINAttemptLimitReached     = DefPIN(http.StatusTooManyRequests, CasePINAttemptLimitReached, CodePINAttemptLimitReached, "PIN attempt limit reached")
+
+	// Helicopter
+	ErrHelicopterNotFound                = DefHelicopter(http.StatusNotFound, CaseHelicopterNotFound, CodeHelicopterNotFound, "helicopter not found")
+	ErrHelicopterDuplicate               = DefHelicopter(http.StatusConflict, CaseHelicopterDuplicate, CodeHelicopterDuplicate, "helicopter identifier already exists")
+	ErrHelicopterRelationDelete          = DefHelicopter(http.StatusConflict, CaseHelicopterRelationDelete, CodeHelicopterRelationDelete, "cannot delete helicopter due to active relations")
+	ErrHelicopterInvalidPayload          = DefHelicopter(http.StatusUnprocessableEntity, CaseHelicopterInvalidPayload, CodeHelicopterInvalidPayload, "invalid helicopter payload")
+	ErrHelicopterInvalidType             = DefHelicopter(http.StatusUnprocessableEntity, CaseHelicopterInvalidType, CodeHelicopterInvalidType, "helicopter type is invalid")
+	ErrHelicopterInvalidJSON             = DefHelicopter(http.StatusBadRequest, CaseHelicopterInvalidJSON, CodeHelicopterInvalidJSON, "invalid json payload")
+	ErrHelicopterInvalidID               = DefHelicopter(http.StatusUnprocessableEntity, CaseHelicopterInvalidID, CodeHelicopterInvalidID, "helicopter id is invalid")
+	ErrHelicopterIDRequired              = DefHelicopter(http.StatusUnprocessableEntity, CaseHelicopterIDRequired, CodeHelicopterIDRequired, "helicopter id is required")
+	ErrHelicopterIDMismatch              = DefHelicopter(http.StatusUnprocessableEntity, CaseHelicopterIDMismatch, CodeHelicopterIDMismatch, "helicopter id mismatch")
+	ErrHelicopterAttributesRequired      = DefHelicopter(http.StatusUnprocessableEntity, CaseHelicopterAttributesRequired, CodeHelicopterAttributesRequired, "at least one attribute must be provided")
+	ErrHelicopterCreateFailed            = DefHelicopter(http.StatusBadRequest, CaseHelicopterCreateFailed, CodeHelicopterCreateFailed, "failed to create helicopter")
+	ErrHelicopterUpdateFailed            = DefHelicopter(http.StatusBadRequest, CaseHelicopterUpdateFailed, CodeHelicopterUpdateFailed, "failed to update helicopter")
+	ErrHelicopterDeleteFailed            = DefHelicopter(http.StatusBadRequest, CaseHelicopterDeleteFailed, CodeHelicopterDeleteFailed, "failed to delete helicopter")
+	ErrHelicopterGenerateFailed          = DefHelicopter(http.StatusBadRequest, CaseHelicopterGenerateFailed, CodeHelicopterGenerateFailed, "failed to generate helicopter report number")
+	ErrHelicopterListFailed              = DefHelicopter(http.StatusBadRequest, CaseHelicopterListFailed, CodeHelicopterListFailed, "failed to list helicopter data")
+	ErrHelicopterPinVerificationRequired = DefHelicopterWithTitle(http.StatusAccepted, CaseHelicopterPinVerificationRequired, CodeHelicopterPinVerificationRequired, "PIN verification required", "valid PIN action token is required")
+	ErrHelicopterUnauthorized            = DefHelicopter(http.StatusUnauthorized, CaseHelicopterUnauthorized, CodeHelicopterUnauthorized, "helicopter action unauthorized")
+	ErrHelicopterFileNotFound            = DefHelicopter(http.StatusNotFound, CaseHelicopterFileNotFound, CodeHelicopterFileNotFound, "helicopter file not found")
+	ErrHelicopterFileInvalidPayload      = DefHelicopter(http.StatusUnprocessableEntity, CaseHelicopterFileInvalidPayload, CodeHelicopterFileInvalidPayload, "invalid helicopter file payload")
+	ErrHelicopterFileInvalidJSON         = DefHelicopter(http.StatusBadRequest, CaseHelicopterFileInvalidJSON, CodeHelicopterFileInvalidJSON, "invalid json payload")
+	ErrHelicopterFileInvalidUUID         = DefHelicopter(http.StatusUnprocessableEntity, CaseHelicopterFileInvalidUUID, CodeHelicopterFileInvalidUUID, "helicopter file uuid is invalid")
+	ErrHelicopterFileSectionInvalid      = DefHelicopter(http.StatusUnprocessableEntity, CaseHelicopterFileSectionInvalid, CodeHelicopterFileSectionInvalid, "section is invalid")
+	ErrHelicopterFileFileNameRequired    = DefHelicopter(http.StatusUnprocessableEntity, CaseHelicopterFileFileNameRequired, CodeHelicopterFileFileNameRequired, "file_name is required")
+	ErrHelicopterFileCreateFailed        = DefHelicopter(http.StatusBadRequest, CaseHelicopterFileCreateFailed, CodeHelicopterFileCreateFailed, "failed to create helicopter file")
+	ErrHelicopterFileUpdateFailed        = DefHelicopter(http.StatusBadRequest, CaseHelicopterFileUpdateFailed, CodeHelicopterFileUpdateFailed, "failed to update helicopter file")
+	ErrHelicopterFileDeleteFailed        = DefHelicopter(http.StatusBadRequest, CaseHelicopterFileDeleteFailed, CodeHelicopterFileDeleteFailed, "failed to delete helicopter file")
+	ErrHelicopterFileGetFailed           = DefHelicopter(http.StatusBadRequest, CaseHelicopterFileGetFailed, CodeHelicopterFileGetFailed, "failed to get helicopter file")
+	ErrHelicopterFileListFailed          = DefHelicopter(http.StatusBadRequest, CaseHelicopterFileListFailed, CodeHelicopterFileListFailed, "failed to list helicopter file data")
+	ErrHelicopterUsageNotFound           = DefHelicopterUsage(http.StatusNotFound, CaseHelicopterUsageNotFound, CodeHelicopterUsageNotFound, "helicopter usage not found")
+	ErrHelicopterUsageDuplicate          = DefHelicopterUsage(http.StatusConflict, CaseHelicopterUsageDuplicate, CodeHelicopterUsageDuplicate, "helicopter usage already exists")
+	ErrHelicopterUsageRelationDelete     = DefHelicopterUsage(http.StatusConflict, CaseHelicopterUsageRelationDelete, CodeHelicopterUsageRelationDelete, "cannot delete helicopter usage due to active relations")
+	ErrHelicopterUsageInvalidPayload     = DefHelicopterUsage(http.StatusUnprocessableEntity, CaseHelicopterUsageInvalidPayload, CodeHelicopterUsageInvalidPayload, "invalid helicopter usage payload")
+	ErrHelicopterUsageInvalidJSON        = DefHelicopterUsage(http.StatusBadRequest, CaseHelicopterUsageInvalidJSON, CodeHelicopterUsageInvalidJSON, "invalid json payload")
+	ErrHelicopterUsageInvalidUUID        = DefHelicopterUsage(http.StatusUnprocessableEntity, CaseHelicopterUsageInvalidUUID, CodeHelicopterUsageInvalidUUID, "helicopter usage uuid is invalid")
+	ErrHelicopterUsageIDRequired         = DefHelicopterUsage(http.StatusUnprocessableEntity, CaseHelicopterUsageIDRequired, CodeHelicopterUsageIDRequired, "helicopter usage id is required")
+	ErrHelicopterUsageIDMismatch         = DefHelicopterUsage(http.StatusUnprocessableEntity, CaseHelicopterUsageIDMismatch, CodeHelicopterUsageIDMismatch, "helicopter usage id mismatch")
+	ErrHelicopterUsageAttributesRequired = DefHelicopterUsage(http.StatusUnprocessableEntity, CaseHelicopterUsageAttributesRequired, CodeHelicopterUsageAttributesRequired, "at least one helicopter usage attribute must be provided")
+	ErrHelicopterUsageCreateFailed       = DefHelicopterUsage(http.StatusBadRequest, CaseHelicopterUsageCreateFailed, CodeHelicopterUsageCreateFailed, "failed to create helicopter usage")
+	ErrHelicopterUsageGetFailed          = DefHelicopterUsage(http.StatusBadRequest, CaseHelicopterUsageGetFailed, CodeHelicopterUsageGetFailed, "failed to get helicopter usage")
+	ErrHelicopterUsageUpdateFailed       = DefHelicopterUsage(http.StatusBadRequest, CaseHelicopterUsageUpdateFailed, CodeHelicopterUsageUpdateFailed, "failed to update helicopter usage")
+	ErrHelicopterUsageDeleteFailed       = DefHelicopterUsage(http.StatusBadRequest, CaseHelicopterUsageDeleteFailed, CodeHelicopterUsageDeleteFailed, "failed to delete helicopter usage")
+	ErrHelicopterUsageListFailed         = DefHelicopterUsage(http.StatusBadRequest, CaseHelicopterUsageListFailed, CodeHelicopterUsageListFailed, "failed to list helicopter usage data")
+	ErrHelicopterUsageSyncFailed         = DefHelicopterUsageSync(http.StatusBadRequest, CaseHelicopterUsageSyncFailed, CodeHelicopterUsageSyncFailed, "failed to refresh helicopter usage data")
+
+	ErrFMReportNotFound       = DefFMReport(http.StatusNotFound, CaseFMReportNotFound, CodeFMReportNotFound, "fm report not found")
+	ErrFMReportInvalidJSON    = DefFMReport(http.StatusBadRequest, CaseFMReportInvalidJSON, CodeFMReportInvalidJSON, "invalid fm report json payload")
+	ErrFMReportInvalidUUID    = DefFMReport(http.StatusUnprocessableEntity, CaseFMReportInvalidUUID, CodeFMReportInvalidUUID, "fm report uuid is invalid")
+	ErrFMReportInvalidPayload = DefFMReport(http.StatusUnprocessableEntity, CaseFMReportInvalidPayload, CodeFMReportInvalidPayload, "invalid fm report payload")
+	ErrFMReportCompleteFailed = DefFMReport(http.StatusBadRequest, CaseFMReportCompleteFailed, CodeFMReportCompleteFailed, "failed to complete fm report")
+	ErrFMReportLocked         = DefFMReport(http.StatusLocked, CaseFMReportLocked, CodeFMReportLocked, "fm report is completed")
+
+	// User
+	ErrUserNotFound           = DefByModule(ModuleUser, http.StatusNotFound, CaseUserNotFound, CodeUserNotFound, "user not found")
+	ErrUserInvalidPayload     = DefByModule(ModuleUser, http.StatusUnprocessableEntity, CaseUserInvalidPayload, CodeUserInvalidPayload, "invalid user payload")
+	ErrUserInvalidJSON        = DefByModule(ModuleUser, http.StatusBadRequest, CaseUserInvalidJSON, CodeUserInvalidJSON, "invalid json payload")
+	ErrUserInvalidUUID        = DefByModule(ModuleUser, http.StatusUnprocessableEntity, CaseUserInvalidUUID, CodeUserInvalidUUID, "user uuid is invalid")
+	ErrUserValidationFailed   = DefByModule(ModuleUser, http.StatusUnprocessableEntity, CaseUserValidationFailed, CodeUserValidationFailed, "user validation failed")
+	ErrUserCreateFailed       = DefByModule(ModuleUser, http.StatusBadRequest, CaseUserCreateFailed, CodeUserCreateFailed, "failed to create user")
+	ErrUserUpdateFailed       = DefByModule(ModuleUser, http.StatusBadRequest, CaseUserUpdateFailed, CodeUserUpdateFailed, "failed to update user")
+	ErrUserDeleteFailed       = DefByModule(ModuleUser, http.StatusBadRequest, CaseUserDeleteFailed, CodeUserDeleteFailed, "failed to delete user")
+	ErrUserListFailed         = DefByModule(ModuleUser, http.StatusBadRequest, CaseUserListFailed, CodeUserListFailed, "failed to list users")
+	ErrUserTimezoneInvalid    = DefByModule(ModuleUser, http.StatusUnprocessableEntity, CaseUserTimezoneInvalid, CodeUserTimezoneInvalid, "timezone is invalid")
+	ErrUserRoleIDsInvalid     = DefByModule(ModuleUser, http.StatusUnprocessableEntity, CaseUserRoleIDsInvalid, CodeUserRoleIDsInvalid, "role_ids contains invalid uuid")
+	ErrUserRoleIDsRequired    = DefByModule(ModuleUser, http.StatusUnprocessableEntity, CaseUserRoleIDsRequired, CodeUserRoleIDsRequired, "role_ids must contain at least one role")
+	ErrUserPrimaryRoleInvalid = DefByModule(ModuleUser, http.StatusUnprocessableEntity, CaseUserPrimaryRoleInvalid, CodeUserPrimaryRoleInvalid, "primary role must be included in role_ids")
+
+	// Master Data
+	ErrMasterDataNotFound         = DefByModule(ModuleMasterData, http.StatusNotFound, CaseMasterDataNotFound, CodeMasterDataNotFound, "master data not found")
+	ErrMasterDataInvalidPayload   = DefByModule(ModuleMasterData, http.StatusUnprocessableEntity, CaseMasterDataInvalidPayload, CodeMasterDataInvalidPayload, "invalid master data payload")
+	ErrMasterDataInvalidJSON      = DefByModule(ModuleMasterData, http.StatusBadRequest, CaseMasterDataInvalidJSON, CodeMasterDataInvalidJSON, "invalid json payload")
+	ErrMasterDataValidationFailed = DefByModule(ModuleMasterData, http.StatusUnprocessableEntity, CaseMasterDataValidationFailed, CodeMasterDataValidationFailed, "master data validation failed")
+	ErrMasterDataCreateFailed     = DefByModule(ModuleMasterData, http.StatusBadRequest, CaseMasterDataCreateFailed, CodeMasterDataCreateFailed, "failed to create master data")
+	ErrMasterDataUpdateFailed     = DefByModule(ModuleMasterData, http.StatusBadRequest, CaseMasterDataUpdateFailed, CodeMasterDataUpdateFailed, "failed to update master data")
+	ErrMasterDataDeleteFailed     = DefByModule(ModuleMasterData, http.StatusBadRequest, CaseMasterDataDeleteFailed, CodeMasterDataDeleteFailed, "failed to delete master data")
+	ErrMasterDataListFailed       = DefByModule(ModuleMasterData, http.StatusBadRequest, CaseMasterDataListFailed, CodeMasterDataListFailed, "failed to list master data")
+
+	// Duty Roster
+	ErrDutyRosterNotFound               = DefByModule(ModuleDutyRoster, http.StatusNotFound, CaseDutyRosterNotFound, CodeDutyRosterNotFound, "duty roster not found")
+	ErrDutyRosterInvalidPayload         = DefByModule(ModuleDutyRoster, http.StatusUnprocessableEntity, CaseDutyRosterInvalidPayload, CodeDutyRosterInvalidPayload, "invalid duty roster payload")
+	ErrDutyRosterInvalidJSON            = DefByModule(ModuleDutyRoster, http.StatusBadRequest, CaseDutyRosterInvalidJSON, CodeDutyRosterInvalidJSON, "invalid json payload")
+	ErrDutyRosterInvalidUUID            = DefByModule(ModuleDutyRoster, http.StatusUnprocessableEntity, CaseDutyRosterInvalidUUID, CodeDutyRosterInvalidUUID, "duty roster uuid is invalid")
+	ErrDutyRosterValidationFailed       = DefByModule(ModuleDutyRoster, http.StatusUnprocessableEntity, CaseDutyRosterValidationFailed, CodeDutyRosterValidationFailed, "duty roster validation failed")
+	ErrDutyRosterConflict               = DefByModule(ModuleDutyRoster, http.StatusConflict, CaseDutyRosterConflict, CodeDutyRosterConflict, "duty roster conflict")
+	ErrDutyRosterCreateFailed           = DefByModule(ModuleDutyRoster, http.StatusBadRequest, CaseDutyRosterCreateFailed, CodeDutyRosterCreateFailed, "failed to create duty roster")
+	ErrDutyRosterUpdateFailed           = DefByModule(ModuleDutyRoster, http.StatusBadRequest, CaseDutyRosterUpdateFailed, CodeDutyRosterUpdateFailed, "failed to update duty roster")
+	ErrDutyRosterDeleteFailed           = DefByModule(ModuleDutyRoster, http.StatusBadRequest, CaseDutyRosterDeleteFailed, CodeDutyRosterDeleteFailed, "failed to delete duty roster")
+	ErrDutyRosterListFailed             = DefByModule(ModuleDutyRoster, http.StatusBadRequest, CaseDutyRosterListFailed, CodeDutyRosterListFailed, "failed to list duty roster data")
+	ErrDutyRosterUnauthorized           = DefByModule(ModuleDutyRoster, http.StatusUnauthorized, CaseDutyRosterUnauthorized, CodeDutyRosterUnauthorized, "duty roster unauthorized")
+	ErrDutyRosterBaseTypeInvalid        = DefByModule(ModuleDutyRoster, http.StatusUnprocessableEntity, CaseDutyRosterBaseTypeInvalid, CodeDutyRosterBaseTypeInvalid, "duty roster base type is invalid")
+	ErrDutyRosterRelationDeleteConflict = DefByModule(ModuleDutyRoster, http.StatusConflict, CaseDutyRosterRelationDeleteConflict, CodeDutyRosterRelationDeleteConflict, "cannot delete duty roster due to active relations")
+
+	// DUL
+	ErrDULNotFound         = DefByModule(ModuleDUL, http.StatusNotFound, CaseDULNotFound, CodeDULNotFound, "dul not found")
+	ErrDULInvalidPayload   = DefByModule(ModuleDUL, http.StatusUnprocessableEntity, CaseDULInvalidPayload, CodeDULInvalidPayload, "invalid dul payload")
+	ErrDULInvalidJSON      = DefByModule(ModuleDUL, http.StatusBadRequest, CaseDULInvalidJSON, CodeDULInvalidJSON, "invalid json payload")
+	ErrDULInvalidUUID      = DefByModule(ModuleDUL, http.StatusUnprocessableEntity, CaseDULInvalidUUID, CodeDULInvalidUUID, "dul uuid is invalid")
+	ErrDULValidationFailed = DefByModule(ModuleDUL, http.StatusUnprocessableEntity, CaseDULValidationFailed, CodeDULValidationFailed, "dul validation failed")
+	ErrDULCreateFailed     = DefByModule(ModuleDUL, http.StatusBadRequest, CaseDULCreateFailed, CodeDULCreateFailed, "failed to create dul")
+	ErrDULUpdateFailed     = DefByModule(ModuleDUL, http.StatusBadRequest, CaseDULUpdateFailed, CodeDULUpdateFailed, "failed to update dul")
+	ErrDULDeleteFailed     = DefByModule(ModuleDUL, http.StatusBadRequest, CaseDULDeleteFailed, CodeDULDeleteFailed, "failed to delete dul")
+	ErrDULListFailed       = DefByModule(ModuleDUL, http.StatusBadRequest, CaseDULListFailed, CodeDULListFailed, "failed to list dul")
+	ErrDULDateInvalid      = DefByModule(ModuleDUL, http.StatusUnprocessableEntity, CaseDULDateInvalid, CodeDULDateInvalid, "date must be YYYY-MM-DD")
+
+	// Flight
+	ErrFlightNotFound         = DefByModule(ModuleFlight, http.StatusNotFound, CaseFlightNotFound, CodeFlightNotFound, "flight not found")
+	ErrFlightInvalidPayload   = DefByModule(ModuleFlight, http.StatusUnprocessableEntity, CaseFlightInvalidPayload, CodeFlightInvalidPayload, "invalid flight payload")
+	ErrFlightInvalidJSON      = DefByModule(ModuleFlight, http.StatusBadRequest, CaseFlightInvalidJSON, CodeFlightInvalidJSON, "invalid json payload")
+	ErrFlightInvalidUUID      = DefByModule(ModuleFlight, http.StatusUnprocessableEntity, CaseFlightInvalidUUID, CodeFlightInvalidUUID, "flight uuid is invalid")
+	ErrFlightValidationFailed = DefByModule(ModuleFlight, http.StatusUnprocessableEntity, CaseFlightValidationFailed, CodeFlightValidationFailed, "flight validation failed")
+	ErrFlightCreateFailed     = DefByModule(ModuleFlight, http.StatusBadRequest, CaseFlightCreateFailed, CodeFlightCreateFailed, "failed to create flight")
+	ErrFlightGetFailed        = DefByModule(ModuleFlight, http.StatusBadRequest, CaseFlightGetFailed, CodeFlightGetFailed, "failed to get flight")
+	ErrFlightListFailed       = DefByModule(ModuleFlight, http.StatusBadRequest, CaseFlightListFailed, CodeFlightListFailed, "failed to list flight data")
+	ErrFlightUnauthorized     = DefByModule(ModuleFlight, http.StatusUnauthorized, CaseFlightUnauthorized, CodeFlightUnauthorized, "flight action unauthorized")
+	ErrFlightDateInvalid      = DefByModule(ModuleFlight, http.StatusUnprocessableEntity, CaseFlightDateInvalid, CodeFlightDateInvalid, "date must be YYYY-MM-DD")
+
+	// No ICAO Code
+	ErrNoIcaoCodeNotFound           = DefByModule(ModuleHospital, http.StatusNotFound, CaseNoIcaoCodeNotFound, CodeNoIcaoCodeNotFound, "no icao code not found")
+	ErrNoIcaoCodeRelationDelete     = DefByModule(ModuleHospital, http.StatusConflict, CaseNoIcaoCodeRelationDelete, CodeNoIcaoCodeRelationDelete, "cannot delete no icao code due to active relations")
+	ErrNoIcaoCodeInvalidPayload     = DefByModule(ModuleHospital, http.StatusUnprocessableEntity, CaseNoIcaoCodeInvalidPayload, CodeNoIcaoCodeInvalidPayload, "invalid no icao code payload")
+	ErrNoIcaoCodeInvalidJSON        = DefByModule(ModuleHospital, http.StatusBadRequest, CaseNoIcaoCodeInvalidJSON, CodeNoIcaoCodeInvalidJSON, "invalid json payload")
+	ErrNoIcaoCodeInvalidUUID        = DefByModule(ModuleHospital, http.StatusUnprocessableEntity, CaseNoIcaoCodeInvalidUUID, CodeNoIcaoCodeInvalidUUID, "no icao code uuid is invalid")
+	ErrNoIcaoCodeIDRequired         = DefByModule(ModuleHospital, http.StatusUnprocessableEntity, CaseNoIcaoCodeIDRequired, CodeNoIcaoCodeIDRequired, "no icao code id is required")
+	ErrNoIcaoCodeIDMismatch         = DefByModule(ModuleHospital, http.StatusUnprocessableEntity, CaseNoIcaoCodeIDMismatch, CodeNoIcaoCodeIDMismatch, "no icao code id mismatch")
+	ErrNoIcaoCodeAttributesRequired = DefByModule(ModuleHospital, http.StatusUnprocessableEntity, CaseNoIcaoCodeAttributesRequired, CodeNoIcaoCodeAttributesRequired, "at least one no icao code attribute must be provided")
+	ErrNoIcaoCodeNameRequired       = DefByModule(ModuleHospital, http.StatusUnprocessableEntity, CaseNoIcaoCodeNameRequired, CodeNoIcaoCodeNameRequired, "no icao code name is required")
+	ErrNoIcaoCodeCreateFailed       = DefByModule(ModuleHospital, http.StatusBadRequest, CaseNoIcaoCodeCreateFailed, CodeNoIcaoCodeCreateFailed, "failed to create no icao code")
+	ErrNoIcaoCodeUpdateFailed       = DefByModule(ModuleHospital, http.StatusBadRequest, CaseNoIcaoCodeUpdateFailed, CodeNoIcaoCodeUpdateFailed, "failed to update no icao code")
+	ErrNoIcaoCodeDeleteFailed       = DefByModule(ModuleHospital, http.StatusBadRequest, CaseNoIcaoCodeDeleteFailed, CodeNoIcaoCodeDeleteFailed, "failed to delete no icao code")
+	ErrNoIcaoCodeListFailed         = DefByModule(ModuleHospital, http.StatusBadRequest, CaseNoIcaoCodeListFailed, CodeNoIcaoCodeListFailed, "failed to list no icao code data")
+	ErrHospitalNotFound             = ErrNoIcaoCodeNotFound
+	ErrHospitalRelationDelete       = ErrNoIcaoCodeRelationDelete
+	ErrHospitalInvalidPayload       = ErrNoIcaoCodeInvalidPayload
+	ErrHospitalInvalidJSON          = ErrNoIcaoCodeInvalidJSON
+	ErrHospitalInvalidUUID          = ErrNoIcaoCodeInvalidUUID
+	ErrHospitalIDRequired           = ErrNoIcaoCodeIDRequired
+	ErrHospitalIDMismatch           = ErrNoIcaoCodeIDMismatch
+	ErrHospitalAttributesRequired   = ErrNoIcaoCodeAttributesRequired
+	ErrHospitalNameRequired         = ErrNoIcaoCodeNameRequired
+	ErrHospitalCreateFailed         = ErrNoIcaoCodeCreateFailed
+	ErrHospitalUpdateFailed         = ErrNoIcaoCodeUpdateFailed
+	ErrHospitalDeleteFailed         = ErrNoIcaoCodeDeleteFailed
+	ErrHospitalListFailed           = ErrNoIcaoCodeListFailed
+
+	// Base
+	ErrBaseNotFound                  = DefByModule(ModuleBase, http.StatusNotFound, CaseBaseNotFound, CodeBaseNotFound, "base not found")
+	ErrBaseRelationDelete            = DefByModule(ModuleBase, http.StatusConflict, CaseBaseRelationDelete, CodeBaseRelationDelete, "cannot delete base because it is referenced by another record")
+	ErrBaseInvalidPayload            = DefByModule(ModuleBase, http.StatusUnprocessableEntity, CaseBaseInvalidPayload, CodeBaseInvalidPayload, "invalid base payload")
+	ErrBaseInvalidJSON               = DefByModule(ModuleBase, http.StatusBadRequest, CaseBaseInvalidJSON, CodeBaseInvalidJSON, "invalid json payload")
+	ErrBaseInvalidUUID               = DefByModule(ModuleBase, http.StatusUnprocessableEntity, CaseBaseInvalidUUID, CodeBaseInvalidUUID, "base uuid is invalid")
+	ErrBaseInvalidCategory           = DefByModule(ModuleBase, http.StatusUnprocessableEntity, CaseBaseInvalidCategory, CodeBaseInvalidCategory, "base category is invalid")
+	ErrBaseAttributesRequired        = DefByModule(ModuleBase, http.StatusUnprocessableEntity, CaseBaseAttributesRequired, CodeBaseAttributesRequired, "at least one base attribute must be provided")
+	ErrBaseNameRequired              = DefByModule(ModuleBase, http.StatusUnprocessableEntity, CaseBaseNameRequired, CodeBaseNameRequired, "base name is required")
+	ErrBaseCreateFailed              = DefByModule(ModuleBase, http.StatusBadRequest, CaseBaseCreateFailed, CodeBaseCreateFailed, "failed to create base")
+	ErrBaseUpdateFailed              = DefByModule(ModuleBase, http.StatusBadRequest, CaseBaseUpdateFailed, CodeBaseUpdateFailed, "failed to update base")
+	ErrBaseDeleteFailed              = DefByModule(ModuleBase, http.StatusBadRequest, CaseBaseDeleteFailed, CodeBaseDeleteFailed, "failed to delete base")
+	ErrBaseListFailed                = DefByModule(ModuleBase, http.StatusBadRequest, CaseBaseListFailed, CodeBaseListFailed, "failed to list base data")
+	ErrBaseInvalidContactIDs         = DefByModule(ModuleBase, http.StatusUnprocessableEntity, CaseBaseInvalidContactIDs, CodeBaseInvalidContactIDs, "base contact ids are invalid")
+	ErrBaseInvalidTime               = DefByModule(ModuleBase, http.StatusUnprocessableEntity, CaseBaseInvalidTime, CodeBaseInvalidTime, "base time format is invalid")
+	ErrBaseDefaultShiftStartRequired = DefByModule(ModuleBase, http.StatusUnprocessableEntity, CaseBaseDefaultShiftStartRequired, CodeBaseDefaultShiftStartRequired, "default_shift_start is required")
+	ErrBaseDefaultShiftEndRequired   = DefByModule(ModuleBase, http.StatusUnprocessableEntity, CaseBaseDefaultShiftEndRequired, CodeBaseDefaultShiftEndRequired, "default_shift_end is required")
+
+	// Facility
+	ErrFacilityNotFound           = DefByModule(ModuleFacility, http.StatusNotFound, CaseFacilityNotFound, CodeFacilityNotFound, "facility not found")
+	ErrFacilityRelationDelete     = DefByModule(ModuleFacility, http.StatusConflict, CaseFacilityRelationDelete, CodeFacilityRelationDelete, "cannot delete facility due to active relations")
+	ErrFacilityInvalidPayload     = DefByModule(ModuleFacility, http.StatusUnprocessableEntity, CaseFacilityInvalidPayload, CodeFacilityInvalidPayload, "invalid facility payload")
+	ErrFacilityInvalidJSON        = DefByModule(ModuleFacility, http.StatusBadRequest, CaseFacilityInvalidJSON, CodeFacilityInvalidJSON, "invalid json payload")
+	ErrFacilityInvalidUUID        = DefByModule(ModuleFacility, http.StatusUnprocessableEntity, CaseFacilityInvalidUUID, CodeFacilityInvalidUUID, "facility uuid is invalid")
+	ErrFacilityAttributesRequired = DefByModule(ModuleFacility, http.StatusUnprocessableEntity, CaseFacilityAttributesRequired, CodeFacilityAttributesRequired, "at least one facility attribute must be provided")
+	ErrFacilityCategoryRequired   = DefByModule(ModuleFacility, http.StatusUnprocessableEntity, CaseFacilityCategoryRequired, CodeFacilityCategoryRequired, "facility category is required")
+	ErrFacilityNameRequired       = DefByModule(ModuleFacility, http.StatusUnprocessableEntity, CaseFacilityNameRequired, CodeFacilityNameRequired, "facility name is required")
+	ErrFacilityTypeRequired       = DefByModule(ModuleFacility, http.StatusUnprocessableEntity, CaseFacilityTypeRequired, CodeFacilityTypeRequired, "facility type is required")
+	ErrFacilityCreateFailed       = DefByModule(ModuleFacility, http.StatusBadRequest, CaseFacilityCreateFailed, CodeFacilityCreateFailed, "failed to create facility")
+	ErrFacilityUpdateFailed       = DefByModule(ModuleFacility, http.StatusBadRequest, CaseFacilityUpdateFailed, CodeFacilityUpdateFailed, "failed to update facility")
+	ErrFacilityDeleteFailed       = DefByModule(ModuleFacility, http.StatusBadRequest, CaseFacilityDeleteFailed, CodeFacilityDeleteFailed, "failed to delete facility")
+	ErrFacilityListFailed         = DefByModule(ModuleFacility, http.StatusBadRequest, CaseFacilityListFailed, CodeFacilityListFailed, "failed to list facility data")
+
+	// Federal State
+	ErrFederalStateNotFound           = DefByModule(ModuleFederalState, http.StatusNotFound, CaseFederalStateNotFound, CodeFederalStateNotFound, "federal state not found")
+	ErrFederalStateRelationDelete     = DefByModule(ModuleFederalState, http.StatusConflict, CaseFederalStateRelationDelete, CodeFederalStateRelationDelete, "cannot delete federal state due to active relations")
+	ErrFederalStateInvalidPayload     = DefByModule(ModuleFederalState, http.StatusUnprocessableEntity, CaseFederalStateInvalidPayload, CodeFederalStateInvalidPayload, "invalid federal state payload")
+	ErrFederalStateInvalidJSON        = DefByModule(ModuleFederalState, http.StatusBadRequest, CaseFederalStateInvalidJSON, CodeFederalStateInvalidJSON, "invalid json payload")
+	ErrFederalStateInvalidID          = DefByModule(ModuleFederalState, http.StatusUnprocessableEntity, CaseFederalStateInvalidID, CodeFederalStateInvalidID, "federal state id is invalid")
+	ErrFederalStateLandIDInvalid      = DefByModule(ModuleFederalState, http.StatusUnprocessableEntity, CaseFederalStateLandIDInvalid, CodeFederalStateLandIDInvalid, "federal state land_id is invalid")
+	ErrFederalStateIDRequired         = DefByModule(ModuleFederalState, http.StatusUnprocessableEntity, CaseFederalStateIDRequired, CodeFederalStateIDRequired, "federal state id is required")
+	ErrFederalStateIDMismatch         = DefByModule(ModuleFederalState, http.StatusUnprocessableEntity, CaseFederalStateIDMismatch, CodeFederalStateIDMismatch, "federal state id mismatch")
+	ErrFederalStateAttributesRequired = DefByModule(ModuleFederalState, http.StatusUnprocessableEntity, CaseFederalStateAttributesRequired, CodeFederalStateAttributesRequired, "at least one federal state attribute must be provided")
+	ErrFederalStateNameRequired       = DefByModule(ModuleFederalState, http.StatusUnprocessableEntity, CaseFederalStateNameRequired, CodeFederalStateNameRequired, "federal state name is required")
+	ErrFederalStateCreateFailed       = DefByModule(ModuleFederalState, http.StatusBadRequest, CaseFederalStateCreateFailed, CodeFederalStateCreateFailed, "failed to create federal state")
+	ErrFederalStateUpdateFailed       = DefByModule(ModuleFederalState, http.StatusBadRequest, CaseFederalStateUpdateFailed, CodeFederalStateUpdateFailed, "failed to update federal state")
+	ErrFederalStateDeleteFailed       = DefByModule(ModuleFederalState, http.StatusBadRequest, CaseFederalStateDeleteFailed, CodeFederalStateDeleteFailed, "failed to delete federal state")
+	ErrFederalStateListFailed         = DefByModule(ModuleFederalState, http.StatusBadRequest, CaseFederalStateListFailed, CodeFederalStateListFailed, "failed to list federal state data")
+
+	// Nationality
+	ErrNationalityNotFound           = DefByModule(ModuleNationality, http.StatusNotFound, CaseNationalityNotFound, CodeNationalityNotFound, "nationality not found")
+	ErrNationalityRelationDelete     = DefByModule(ModuleNationality, http.StatusConflict, CaseNationalityRelationDelete, CodeNationalityRelationDelete, "cannot delete nationality due to active relations")
+	ErrNationalityInvalidPayload     = DefByModule(ModuleNationality, http.StatusUnprocessableEntity, CaseNationalityInvalidPayload, CodeNationalityInvalidPayload, "invalid nationality payload")
+	ErrNationalityInvalidJSON        = DefByModule(ModuleNationality, http.StatusBadRequest, CaseNationalityInvalidJSON, CodeNationalityInvalidJSON, "invalid json payload")
+	ErrNationalityInvalidUUID        = DefByModule(ModuleNationality, http.StatusUnprocessableEntity, CaseNationalityInvalidUUID, CodeNationalityInvalidUUID, "nationality uuid is invalid")
+	ErrNationalityIDRequired         = DefByModule(ModuleNationality, http.StatusUnprocessableEntity, CaseNationalityIDRequired, CodeNationalityIDRequired, "nationality id is required")
+	ErrNationalityIDMismatch         = DefByModule(ModuleNationality, http.StatusUnprocessableEntity, CaseNationalityIDMismatch, CodeNationalityIDMismatch, "nationality id mismatch")
+	ErrNationalityAttributesRequired = DefByModule(ModuleNationality, http.StatusUnprocessableEntity, CaseNationalityAttributesRequired, CodeNationalityAttributesRequired, "at least one nationality attribute must be provided")
+	ErrNationalityNameRequired       = DefByModule(ModuleNationality, http.StatusUnprocessableEntity, CaseNationalityNameRequired, CodeNationalityNameRequired, "nationality name is required")
+	ErrNationalityCreateFailed       = DefByModule(ModuleNationality, http.StatusBadRequest, CaseNationalityCreateFailed, CodeNationalityCreateFailed, "failed to create nationality")
+	ErrNationalityUpdateFailed       = DefByModule(ModuleNationality, http.StatusBadRequest, CaseNationalityUpdateFailed, CodeNationalityUpdateFailed, "failed to update nationality")
+	ErrNationalityDeleteFailed       = DefByModule(ModuleNationality, http.StatusBadRequest, CaseNationalityDeleteFailed, CodeNationalityDeleteFailed, "failed to delete nationality")
+	ErrNationalityListFailed         = DefByModule(ModuleNationality, http.StatusBadRequest, CaseNationalityListFailed, CodeNationalityListFailed, "failed to list nationality data")
+
+	// Country
+	ErrCountryNotFound           = DefByModule(ModuleLand, http.StatusNotFound, CaseCountryNotFound, CodeCountryNotFound, "country not found")
+	ErrCountryRelationDelete     = DefByModule(ModuleLand, http.StatusConflict, CaseCountryRelationDelete, CodeCountryRelationDelete, "cannot delete country due to active relations")
+	ErrCountryInvalidPayload     = DefByModule(ModuleLand, http.StatusUnprocessableEntity, CaseCountryInvalidPayload, CodeCountryInvalidPayload, "invalid country payload")
+	ErrCountryInvalidJSON        = DefByModule(ModuleLand, http.StatusBadRequest, CaseCountryInvalidJSON, CodeCountryInvalidJSON, "invalid json payload")
+	ErrCountryInvalidID          = DefByModule(ModuleLand, http.StatusUnprocessableEntity, CaseCountryInvalidID, CodeCountryInvalidID, "country id is invalid")
+	ErrCountryIDRequired         = DefByModule(ModuleLand, http.StatusUnprocessableEntity, CaseCountryIDRequired, CodeCountryIDRequired, "country id is required")
+	ErrCountryIDMismatch         = DefByModule(ModuleLand, http.StatusUnprocessableEntity, CaseCountryIDMismatch, CodeCountryIDMismatch, "country id mismatch")
+	ErrCountryAttributesRequired = DefByModule(ModuleLand, http.StatusUnprocessableEntity, CaseCountryAttributesRequired, CodeCountryAttributesRequired, "at least one country attribute must be provided")
+	ErrCountryNameRequired       = DefByModule(ModuleLand, http.StatusUnprocessableEntity, CaseCountryNameRequired, CodeCountryNameRequired, "country name is required")
+	ErrCountryISOCodeInvalid     = DefByModule(ModuleLand, http.StatusUnprocessableEntity, CaseCountryISOCodeInvalid, CodeCountryISOCodeInvalid, "country iso_code is invalid")
+	ErrCountryISOCodeDuplicate   = DefByModule(ModuleLand, http.StatusConflict, CaseCountryISOCodeDuplicate, CodeCountryISOCodeDuplicate, "iso_code already exists")
+	ErrCountryCreateFailed       = DefByModule(ModuleLand, http.StatusBadRequest, CaseCountryCreateFailed, CodeCountryCreateFailed, "failed to create country")
+	ErrCountryUpdateFailed       = DefByModule(ModuleLand, http.StatusBadRequest, CaseCountryUpdateFailed, CodeCountryUpdateFailed, "failed to update country")
+	ErrCountryDeleteFailed       = DefByModule(ModuleLand, http.StatusBadRequest, CaseCountryDeleteFailed, CodeCountryDeleteFailed, "failed to delete country")
+	ErrCountryListFailed         = DefByModule(ModuleLand, http.StatusBadRequest, CaseCountryListFailed, CodeCountryListFailed, "failed to list country data")
+	ErrLandNotFound              = ErrCountryNotFound
+	ErrLandRelationDelete        = ErrCountryRelationDelete
+	ErrLandInvalidPayload        = ErrCountryInvalidPayload
+	ErrLandInvalidJSON           = ErrCountryInvalidJSON
+	ErrLandInvalidID             = ErrCountryInvalidID
+	ErrLandIDRequired            = ErrCountryIDRequired
+	ErrLandIDMismatch            = ErrCountryIDMismatch
+	ErrLandAttributesRequired    = ErrCountryAttributesRequired
+	ErrLandNameRequired          = ErrCountryNameRequired
+	ErrLandISOCodeInvalid        = ErrCountryISOCodeInvalid
+	ErrLandISOCodeDuplicate      = ErrCountryISOCodeDuplicate
+	ErrLandCreateFailed          = ErrCountryCreateFailed
+	ErrLandUpdateFailed          = ErrCountryUpdateFailed
+	ErrLandDeleteFailed          = ErrCountryDeleteFailed
+	ErrLandListFailed            = ErrCountryListFailed
+
+	// ICAO
+	ErrICAONotFound            = DefByModule(ModuleICAO, http.StatusNotFound, CaseICAONotFound, CodeICAONotFound, "icao not found")
+	ErrICAORelationDelete      = DefByModule(ModuleICAO, http.StatusConflict, CaseICAORelationDelete, CodeICAORelationDelete, "cannot delete icao due to active relations")
+	ErrICAOInvalidPayload      = DefByModule(ModuleICAO, http.StatusUnprocessableEntity, CaseICAOInvalidPayload, CodeICAOInvalidPayload, "invalid icao payload")
+	ErrICAOInvalidJSON         = DefByModule(ModuleICAO, http.StatusBadRequest, CaseICAOInvalidJSON, CodeICAOInvalidJSON, "invalid json payload")
+	ErrICAOInvalidUUID         = DefByModule(ModuleICAO, http.StatusUnprocessableEntity, CaseICAOInvalidUUID, CodeICAOInvalidUUID, "icao uuid is invalid")
+	ErrICAOIDRequired          = DefByModule(ModuleICAO, http.StatusUnprocessableEntity, CaseICAOIDRequired, CodeICAOIDRequired, "icao id is required")
+	ErrICAOIDMismatch          = DefByModule(ModuleICAO, http.StatusUnprocessableEntity, CaseICAOIDMismatch, CodeICAOIDMismatch, "icao id mismatch")
+	ErrICAOAttributesRequired  = DefByModule(ModuleICAO, http.StatusUnprocessableEntity, CaseICAOAttributesRequired, CodeICAOAttributesRequired, "at least one icao attribute must be provided")
+	ErrICAOCodeRequired        = DefByModule(ModuleICAO, http.StatusUnprocessableEntity, CaseICAOCodeRequired, CodeICAOCodeRequired, "icao code is required")
+	ErrICAOLandIDInvalid       = DefByModule(ModuleICAO, http.StatusUnprocessableEntity, CaseICAOLandIDInvalid, CodeICAOLandIDInvalid, "icao land_id is invalid")
+	ErrICAOFederalStateInvalid = DefByModule(ModuleICAO, http.StatusUnprocessableEntity, CaseICAOFederalStateInvalid, CodeICAOFederalStateInvalid, "icao federal_state_id is invalid")
+	ErrICAOCreateFailed        = DefByModule(ModuleICAO, http.StatusBadRequest, CaseICAOCreateFailed, CodeICAOCreateFailed, "failed to create icao")
+	ErrICAOUpdateFailed        = DefByModule(ModuleICAO, http.StatusBadRequest, CaseICAOUpdateFailed, CodeICAOUpdateFailed, "failed to update icao")
+	ErrICAODeleteFailed        = DefByModule(ModuleICAO, http.StatusBadRequest, CaseICAODeleteFailed, CodeICAODeleteFailed, "failed to delete icao")
+	ErrICAOListFailed          = DefByModule(ModuleICAO, http.StatusBadRequest, CaseICAOListFailed, CodeICAOListFailed, "failed to list icao data")
+
+	// Vocation
+	ErrVocationNotFound           = DefByModule(ModuleVocation, http.StatusNotFound, CaseVocationNotFound, CodeVocationNotFound, "vocation not found")
+	ErrVocationRelationDelete     = DefByModule(ModuleVocation, http.StatusConflict, CaseVocationRelationDelete, CodeVocationRelationDelete, "cannot delete vocation due to active relations")
+	ErrVocationInvalidPayload     = DefByModule(ModuleVocation, http.StatusUnprocessableEntity, CaseVocationInvalidPayload, CodeVocationInvalidPayload, "invalid vocation payload")
+	ErrVocationInvalidJSON        = DefByModule(ModuleVocation, http.StatusBadRequest, CaseVocationInvalidJSON, CodeVocationInvalidJSON, "invalid json payload")
+	ErrVocationInvalidUUID        = DefByModule(ModuleVocation, http.StatusUnprocessableEntity, CaseVocationInvalidUUID, CodeVocationInvalidUUID, "vocation uuid is invalid")
+	ErrVocationIDRequired         = DefByModule(ModuleVocation, http.StatusUnprocessableEntity, CaseVocationIDRequired, CodeVocationIDRequired, "vocation id is required")
+	ErrVocationIDMismatch         = DefByModule(ModuleVocation, http.StatusUnprocessableEntity, CaseVocationIDMismatch, CodeVocationIDMismatch, "vocation id mismatch")
+	ErrVocationAttributesRequired = DefByModule(ModuleVocation, http.StatusUnprocessableEntity, CaseVocationAttributesRequired, CodeVocationAttributesRequired, "at least one vocation attribute must be provided")
+	ErrVocationNameRequired       = DefByModule(ModuleVocation, http.StatusUnprocessableEntity, CaseVocationNameRequired, CodeVocationNameRequired, "vocation name is required")
+	ErrVocationCreateFailed       = DefByModule(ModuleVocation, http.StatusBadRequest, CaseVocationCreateFailed, CodeVocationCreateFailed, "failed to create vocation")
+	ErrVocationUpdateFailed       = DefByModule(ModuleVocation, http.StatusBadRequest, CaseVocationUpdateFailed, CodeVocationUpdateFailed, "failed to update vocation")
+	ErrVocationDeleteFailed       = DefByModule(ModuleVocation, http.StatusBadRequest, CaseVocationDeleteFailed, CodeVocationDeleteFailed, "failed to delete vocation")
+	ErrVocationListFailed         = DefByModule(ModuleVocation, http.StatusBadRequest, CaseVocationListFailed, CodeVocationListFailed, "failed to list vocation data")
+
+	// Health Insurance Companies
+	ErrHealthInsuranceNotFound           = DefByModule(ModuleHealthInsuranceCompanies, http.StatusNotFound, CaseHealthInsuranceNotFound, CodeHealthInsuranceNotFound, "health insurance company not found")
+	ErrHealthInsuranceRelationDelete     = DefByModule(ModuleHealthInsuranceCompanies, http.StatusConflict, CaseHealthInsuranceRelationDelete, CodeHealthInsuranceRelationDelete, "cannot delete health insurance company due to active relations")
+	ErrHealthInsuranceInvalidPayload     = DefByModule(ModuleHealthInsuranceCompanies, http.StatusUnprocessableEntity, CaseHealthInsuranceInvalidPayload, CodeHealthInsuranceInvalidPayload, "invalid health insurance company payload")
+	ErrHealthInsuranceInvalidJSON        = DefByModule(ModuleHealthInsuranceCompanies, http.StatusBadRequest, CaseHealthInsuranceInvalidJSON, CodeHealthInsuranceInvalidJSON, "invalid json payload")
+	ErrHealthInsuranceInvalidUUID        = DefByModule(ModuleHealthInsuranceCompanies, http.StatusUnprocessableEntity, CaseHealthInsuranceInvalidUUID, CodeHealthInsuranceInvalidUUID, "health insurance company uuid is invalid")
+	ErrHealthInsuranceIDRequired         = DefByModule(ModuleHealthInsuranceCompanies, http.StatusUnprocessableEntity, CaseHealthInsuranceIDRequired, CodeHealthInsuranceIDRequired, "health insurance company id is required")
+	ErrHealthInsuranceIDMismatch         = DefByModule(ModuleHealthInsuranceCompanies, http.StatusUnprocessableEntity, CaseHealthInsuranceIDMismatch, CodeHealthInsuranceIDMismatch, "health insurance company id mismatch")
+	ErrHealthInsuranceAttributesRequired = DefByModule(ModuleHealthInsuranceCompanies, http.StatusUnprocessableEntity, CaseHealthInsuranceAttributesRequired, CodeHealthInsuranceAttributesRequired, "at least one health insurance company attribute must be provided")
+	ErrHealthInsuranceNameRequired       = DefByModule(ModuleHealthInsuranceCompanies, http.StatusUnprocessableEntity, CaseHealthInsuranceNameRequired, CodeHealthInsuranceNameRequired, "health insurance company name is required")
+	ErrHealthInsuranceLandIDInvalid      = DefByModule(ModuleHealthInsuranceCompanies, http.StatusUnprocessableEntity, CaseHealthInsuranceLandIDInvalid, CodeHealthInsuranceLandIDInvalid, "health insurance company land_id is invalid")
+	ErrHealthInsuranceCreateFailed       = DefByModule(ModuleHealthInsuranceCompanies, http.StatusBadRequest, CaseHealthInsuranceCreateFailed, CodeHealthInsuranceCreateFailed, "failed to create health insurance company")
+	ErrHealthInsuranceUpdateFailed       = DefByModule(ModuleHealthInsuranceCompanies, http.StatusBadRequest, CaseHealthInsuranceUpdateFailed, CodeHealthInsuranceUpdateFailed, "failed to update health insurance company")
+	ErrHealthInsuranceDeleteFailed       = DefByModule(ModuleHealthInsuranceCompanies, http.StatusBadRequest, CaseHealthInsuranceDeleteFailed, CodeHealthInsuranceDeleteFailed, "failed to delete health insurance company")
+	ErrHealthInsuranceListFailed         = DefByModule(ModuleHealthInsuranceCompanies, http.StatusBadRequest, CaseHealthInsuranceListFailed, CodeHealthInsuranceListFailed, "failed to list health insurance company data")
+
+	// Medicine
+	ErrMedicineNotFound                = DefByModule(ModuleMedicine, http.StatusNotFound, CaseMedicineNotFound, CodeMedicineNotFound, "medicine not found")
+	ErrMedicineRelationDelete          = DefByModule(ModuleMedicine, http.StatusConflict, CaseMedicineRelationDelete, CodeMedicineRelationDelete, "cannot delete medicine due to active relations")
+	ErrMedicineInvalidPayload          = DefByModule(ModuleMedicine, http.StatusUnprocessableEntity, CaseMedicineInvalidPayload, CodeMedicineInvalidPayload, "invalid medicine payload")
+	ErrMedicineInvalidJSON             = DefByModule(ModuleMedicine, http.StatusBadRequest, CaseMedicineInvalidJSON, CodeMedicineInvalidJSON, "invalid json payload")
+	ErrMedicineInvalidUUID             = DefByModule(ModuleMedicine, http.StatusUnprocessableEntity, CaseMedicineInvalidUUID, CodeMedicineInvalidUUID, "medicine uuid is invalid")
+	ErrMedicineIDRequired              = DefByModule(ModuleMedicine, http.StatusUnprocessableEntity, CaseMedicineIDRequired, CodeMedicineIDRequired, "medicine id is required")
+	ErrMedicineIDMismatch              = DefByModule(ModuleMedicine, http.StatusUnprocessableEntity, CaseMedicineIDMismatch, CodeMedicineIDMismatch, "medicine id mismatch")
+	ErrMedicineAttributesRequired      = DefByModule(ModuleMedicine, http.StatusUnprocessableEntity, CaseMedicineAttributesRequired, CodeMedicineAttributesRequired, "at least one medicine attribute must be provided")
+	ErrMedicineNameRequired            = DefByModule(ModuleMedicine, http.StatusUnprocessableEntity, CaseMedicineNameRequired, CodeMedicineNameRequired, "medicine name is required")
+	ErrMedicineGroupIDInvalid          = DefByModule(ModuleMedicine, http.StatusUnprocessableEntity, CaseMedicineGroupIDInvalid, CodeMedicineGroupIDInvalid, "medicine_group_id is invalid")
+	ErrMedicineMotorReactionIDInvalid  = DefByModule(ModuleMedicine, http.StatusUnprocessableEntity, CaseMedicineMotorReactionIDInvalid, CodeMedicineMotorReactionIDInvalid, "motor_reaction_id is invalid")
+	ErrMedicineMotorReactionIDsInvalid = DefByModule(ModuleMedicine, http.StatusUnprocessableEntity, CaseMedicineMotorReactionIDsInvalid, CodeMedicineMotorReactionIDsInvalid, "motor_reaction_ids contains invalid uuid")
+	ErrMedicineCreateFailed            = DefByModule(ModuleMedicine, http.StatusBadRequest, CaseMedicineCreateFailed, CodeMedicineCreateFailed, "failed to create medicine")
+	ErrMedicineUpdateFailed            = DefByModule(ModuleMedicine, http.StatusBadRequest, CaseMedicineUpdateFailed, CodeMedicineUpdateFailed, "failed to update medicine")
+	ErrMedicineDeleteFailed            = DefByModule(ModuleMedicine, http.StatusBadRequest, CaseMedicineDeleteFailed, CodeMedicineDeleteFailed, "failed to delete medicine")
+	ErrMedicineListFailed              = DefByModule(ModuleMedicine, http.StatusBadRequest, CaseMedicineListFailed, CodeMedicineListFailed, "failed to list medicine data")
+
+	// Master Settings
+	ErrMasterSettingsNotFound            = DefByModule(ModuleMasterSettings, http.StatusNotFound, CaseMasterSettingsNotFound, CodeMasterSettingsNotFound, "master settings not found")
+	ErrMasterSettingsInvalidPayload      = DefByModule(ModuleMasterSettings, http.StatusUnprocessableEntity, CaseMasterSettingsInvalidPayload, CodeMasterSettingsInvalidPayload, "invalid master settings payload")
+	ErrMasterSettingsInvalidJSON         = DefByModule(ModuleMasterSettings, http.StatusBadRequest, CaseMasterSettingsInvalidJSON, CodeMasterSettingsInvalidJSON, "invalid json payload")
+	ErrMasterSettingsInvalidUUID         = DefByModule(ModuleMasterSettings, http.StatusUnprocessableEntity, CaseMasterSettingsInvalidUUID, CodeMasterSettingsInvalidUUID, "master settings uuid is invalid")
+	ErrMasterSettingsIDRequired          = DefByModule(ModuleMasterSettings, http.StatusUnprocessableEntity, CaseMasterSettingsIDRequired, CodeMasterSettingsIDRequired, "master settings id is required")
+	ErrMasterSettingsIDMismatch          = DefByModule(ModuleMasterSettings, http.StatusUnprocessableEntity, CaseMasterSettingsIDMismatch, CodeMasterSettingsIDMismatch, "master settings id mismatch")
+	ErrMasterSettingsAttributesRequired  = DefByModule(ModuleMasterSettings, http.StatusUnprocessableEntity, CaseMasterSettingsAttributesRequired, CodeMasterSettingsAttributesRequired, "at least one master settings attribute must be provided")
+	ErrMasterSettingsCompanyNameRequired = DefByModule(ModuleMasterSettings, http.StatusUnprocessableEntity, CaseMasterSettingsCompanyNameRequired, CodeMasterSettingsCompanyNameRequired, "company_name is required")
+	ErrMasterSettingsLogoFileInvalid     = DefByModule(ModuleMasterSettings, http.StatusUnprocessableEntity, CaseMasterSettingsLogoFileInvalid, CodeMasterSettingsLogoFileInvalid, "logo file uuid is invalid")
+	ErrMasterSettingsCoverFileInvalid    = DefByModule(ModuleMasterSettings, http.StatusUnprocessableEntity, CaseMasterSettingsCoverFileInvalid, CodeMasterSettingsCoverFileInvalid, "cover file uuid is invalid")
+	ErrMasterSettingsCreateFailed        = DefByModule(ModuleMasterSettings, http.StatusBadRequest, CaseMasterSettingsCreateFailed, CodeMasterSettingsCreateFailed, "failed to create master settings")
+	ErrMasterSettingsUpdateFailed        = DefByModule(ModuleMasterSettings, http.StatusBadRequest, CaseMasterSettingsUpdateFailed, CodeMasterSettingsUpdateFailed, "failed to update master settings")
+	ErrMasterSettingsDeleteFailed        = DefByModule(ModuleMasterSettings, http.StatusBadRequest, CaseMasterSettingsDeleteFailed, CodeMasterSettingsDeleteFailed, "failed to delete master settings")
+	ErrMasterSettingsGetFailed           = DefByModule(ModuleMasterSettings, http.StatusBadRequest, CaseMasterSettingsGetFailed, CodeMasterSettingsGetFailed, "failed to get master settings")
+	ErrMasterSettingsMicrosoftUpsert     = DefByModule(ModuleMasterSettings, http.StatusBadRequest, CaseMasterSettingsMicrosoftUpsert, CodeMasterSettingsMicrosoftUpsertFailed, "failed to upsert microsoft entra sso settings")
+
+	// Branding
+	ErrBrandingLogoFetchFailed        = DefByModule(ModuleBranding, http.StatusBadRequest, CaseBrandingLogoFetchFailed, CodeBrandingLogoFetchFailed, "failed to fetch branding logo")
+	ErrBrandingCoverFetchFailed       = DefByModule(ModuleBranding, http.StatusBadRequest, CaseBrandingCoverFetchFailed, CodeBrandingCoverFetchFailed, "failed to fetch branding cover")
+	ErrBrandingEmailLogoFetchFailed   = DefByModule(ModuleBranding, http.StatusBadRequest, CaseBrandingEmailLogoFetchFailed, CodeBrandingEmailLogoFetchFailed, "failed to fetch branding email logo")
+	ErrBrandingContentFetchFailed     = DefByModule(ModuleBranding, http.StatusBadRequest, CaseBrandingContentFetchFailed, CodeBrandingContentFetchFailed, "failed to fetch branding content")
+	ErrBrandingStorageUnavailable     = DefByModule(ModuleBranding, http.StatusServiceUnavailable, CaseBrandingStorageUnavailable, CodeBrandingStorageUnavailable, "branding storage service unavailable")
+	ErrBrandingFileManagerUnavailable = DefByModule(ModuleBranding, http.StatusServiceUnavailable, CaseBrandingFileManagerUnavailable, CodeBrandingFileManagerUnavailable, "branding file manager service unavailable")
+
+	// File Manager
+	ErrFileManagerStorageUnavailable           = DefByModuleWithTitle(ModuleFileManager, http.StatusServiceUnavailable, CaseFileManagerStorageUnavailable, CodeFileManagerStorageUnavailable, "Storage unavailable", "storage service is unavailable")
+	ErrFileManagerQueueUnavailable             = DefByModuleWithTitle(ModuleFileManager, http.StatusServiceUnavailable, CaseFileManagerQueueUnavailable, CodeFileManagerQueueUnavailable, "Queue unavailable", "queue service is unavailable")
+	ErrFileManagerUploadIntentUnavailable      = DefByModuleWithTitle(ModuleFileManager, http.StatusServiceUnavailable, CaseFileManagerUploadIntentUnavailable, CodeFileManagerUploadIntentUnavailable, "Upload intent unavailable", "upload intent service is unavailable")
+	ErrFileManagerAttachmentServiceUnavailable = DefByModuleWithTitle(ModuleFileManager, http.StatusServiceUnavailable, CaseFileManagerAttachmentServiceUnavailable, CodeFileManagerAttachmentServiceUnavailable, "Attachment service unavailable", "attachment service is unavailable")
+	ErrFileManagerFolderNotFound               = DefByModule(ModuleFileManager, http.StatusNotFound, CaseFileManagerFolderNotFound, CodeFileManagerFolderNotFound, "folder not found")
+	ErrFileManagerFileNotFound                 = DefByModule(ModuleFileManager, http.StatusNotFound, CaseFileManagerFileNotFound, CodeFileManagerFileNotFound, "file not found")
+	ErrFileManagerAttachmentNotFound           = DefByModule(ModuleFileManager, http.StatusNotFound, CaseFileManagerAttachmentNotFound, CodeFileManagerAttachmentNotFound, "attachment not found")
+	ErrFileManagerUploadIntentNotFound         = DefByModule(ModuleFileManager, http.StatusNotFound, CaseFileManagerUploadIntentNotFound, CodeFileManagerUploadIntentNotFound, "upload intent not found")
+	ErrFileManagerStatusConflict               = DefByModule(ModuleFileManager, http.StatusConflict, CaseFileManagerStatusConflict, CodeFileManagerStatusConflict, "file status conflict")
+	ErrFileManagerUploadIntentConflict         = DefByModule(ModuleFileManager, http.StatusConflict, CaseFileManagerUploadIntentConflict, CodeFileManagerUploadIntentConflict, "upload intent conflict")
+	ErrFileManagerValidationFailed             = DefByModule(ModuleFileManager, http.StatusUnprocessableEntity, CaseFileManagerValidationFailed, CodeFileManagerValidationFailed, "file manager validation failed")
+	ErrFileManagerActionFailed                 = DefByModule(ModuleFileManager, http.StatusBadRequest, CaseFileManagerActionFailed, CodeFileManagerActionFailed, "file manager action failed")
+	ErrFileManagerWOPIServiceUnavailable       = DefByModuleWithTitle(ModuleFileManager, http.StatusServiceUnavailable, CaseFileManagerWOPIServiceUnavailable, CodeFileManagerWOPIServiceUnavailable, "WOPI service unavailable", "wopi service is unavailable")
+	ErrFileManagerWOPIInvalidFileID            = DefByModule(ModuleFileManager, http.StatusUnprocessableEntity, CaseFileManagerWOPIInvalidFileID, CodeFileManagerWOPIInvalidFileID, "wopi file id is invalid")
+	ErrFileManagerWOPIInvalidToken             = DefByModule(ModuleFileManager, http.StatusUnauthorized, CaseFileManagerWOPIInvalidToken, CodeFileManagerWOPIInvalidToken, "wopi access token is invalid or expired")
+	ErrFileManagerWOPIInvalidProof             = DefByModule(ModuleFileManager, http.StatusForbidden, CaseFileManagerWOPIInvalidProof, CodeFileManagerWOPIInvalidProof, "wopi proof is invalid")
+	ErrFileManagerWOPIPermissionDenied         = DefByModule(ModuleFileManager, http.StatusForbidden, CaseFileManagerWOPIPermissionDenied, CodeFileManagerWOPIPermissionDenied, "wopi permission denied")
+	ErrFileManagerWOPIFileNotFound             = DefByModule(ModuleFileManager, http.StatusNotFound, CaseFileManagerWOPIFileNotFound, CodeFileManagerWOPIFileNotFound, "wopi file not found")
+	ErrFileManagerWOPILockConflict             = DefByModule(ModuleFileManager, http.StatusConflict, CaseFileManagerWOPILockConflict, CodeFileManagerWOPILockConflict, "wopi lock conflict")
+	ErrFileManagerWOPIStaleTimestamp           = DefByModule(ModuleFileManager, http.StatusConflict, CaseFileManagerWOPIStaleTimestamp, CodeFileManagerWOPIStaleTimestamp, "wopi save timestamp is stale")
+	ErrFileManagerWOPIValidationFailed         = DefByModule(ModuleFileManager, http.StatusUnprocessableEntity, CaseFileManagerWOPIValidationFailed, CodeFileManagerWOPIValidationFailed, "wopi validation failed")
+
+	// OPC
+	ErrOPCNotFound           = DefByModule(ModuleOPCData, http.StatusNotFound, CaseOPCNotFound, CodeOPCNotFound, "opc not found")
+	ErrOPCRelationDelete     = DefByModule(ModuleOPCData, http.StatusConflict, CaseOPCRelationDelete, CodeOPCRelationDelete, "cannot delete opc due to active relations")
+	ErrOPCInvalidPayload     = DefByModule(ModuleOPCData, http.StatusUnprocessableEntity, CaseOPCInvalidPayload, CodeOPCInvalidPayload, "invalid opc payload")
+	ErrOPCInvalidJSON        = DefByModule(ModuleOPCData, http.StatusBadRequest, CaseOPCInvalidJSON, CodeOPCInvalidJSON, "invalid json payload")
+	ErrOPCInvalidUUID        = DefByModule(ModuleOPCData, http.StatusUnprocessableEntity, CaseOPCInvalidUUID, CodeOPCInvalidUUID, "opc uuid is invalid")
+	ErrOPCIDRequired         = DefByModule(ModuleOPCData, http.StatusUnprocessableEntity, CaseOPCIDRequired, CodeOPCIDRequired, "opc id is required")
+	ErrOPCIDMismatch         = DefByModule(ModuleOPCData, http.StatusUnprocessableEntity, CaseOPCIDMismatch, CodeOPCIDMismatch, "opc id mismatch")
+	ErrOPCAttributesRequired = DefByModule(ModuleOPCData, http.StatusUnprocessableEntity, CaseOPCAttributesRequired, CodeOPCAttributesRequired, "at least one opc attribute must be provided")
+	ErrOPCTitleRequired      = DefByModule(ModuleOPCData, http.StatusUnprocessableEntity, CaseOPCTitleRequired, CodeOPCTitleRequired, "opc title is required")
+	ErrOPCCreateFailed       = DefByModule(ModuleOPCData, http.StatusBadRequest, CaseOPCCreateFailed, CodeOPCCreateFailed, "failed to create opc")
+	ErrOPCUpdateFailed       = DefByModule(ModuleOPCData, http.StatusBadRequest, CaseOPCUpdateFailed, CodeOPCUpdateFailed, "failed to update opc")
+	ErrOPCDeleteFailed       = DefByModule(ModuleOPCData, http.StatusBadRequest, CaseOPCDeleteFailed, CodeOPCDeleteFailed, "failed to delete opc")
+	ErrOPCListFailed         = DefByModule(ModuleOPCData, http.StatusBadRequest, CaseOPCListFailed, CodeOPCListFailed, "failed to list opc data")
+
+	// Insurance Patient Data
+	ErrInsurancePatientDataNotFound                 = DefByModule(ModuleInsurancePatientData, http.StatusNotFound, CaseInsurancePatientDataNotFound, CodeInsurancePatientDataNotFound, "insurance patient data not found")
+	ErrInsurancePatientDataRelationDelete           = DefByModule(ModuleInsurancePatientData, http.StatusConflict, CaseInsurancePatientDataRelationDelete, CodeInsurancePatientDataRelationDelete, "cannot delete insurance patient data due to active relations")
+	ErrInsurancePatientDataInvalidPayload           = DefByModule(ModuleInsurancePatientData, http.StatusUnprocessableEntity, CaseInsurancePatientDataInvalidPayload, CodeInsurancePatientDataInvalidPayload, "invalid insurance patient data payload")
+	ErrInsurancePatientDataInvalidJSON              = DefByModule(ModuleInsurancePatientData, http.StatusBadRequest, CaseInsurancePatientDataInvalidJSON, CodeInsurancePatientDataInvalidJSON, "invalid json payload")
+	ErrInsurancePatientDataInvalidUUID              = DefByModule(ModuleInsurancePatientData, http.StatusUnprocessableEntity, CaseInsurancePatientDataInvalidUUID, CodeInsurancePatientDataInvalidUUID, "insurance patient data uuid is invalid")
+	ErrInsurancePatientDataIDRequired               = DefByModule(ModuleInsurancePatientData, http.StatusUnprocessableEntity, CaseInsurancePatientDataIDRequired, CodeInsurancePatientDataIDRequired, "insurance patient data id is required")
+	ErrInsurancePatientDataIDMismatch               = DefByModule(ModuleInsurancePatientData, http.StatusUnprocessableEntity, CaseInsurancePatientDataIDMismatch, CodeInsurancePatientDataIDMismatch, "insurance patient data id mismatch")
+	ErrInsurancePatientDataAttributesRequired       = DefByModule(ModuleInsurancePatientData, http.StatusUnprocessableEntity, CaseInsurancePatientDataAttributesRequired, CodeInsurancePatientDataAttributesRequired, "at least one insurance patient data attribute must be provided")
+	ErrInsurancePatientDataHealthInsuranceIDInvalid = DefByModule(ModuleInsurancePatientData, http.StatusUnprocessableEntity, CaseInsurancePatientDataHealthInsuranceIDInvalid, CodeInsurancePatientDataHealthInsuranceIDInvalid, "health_insurance_companies_id is invalid")
+	ErrInsurancePatientDataFederalStateIDInvalid    = DefByModule(ModuleInsurancePatientData, http.StatusUnprocessableEntity, CaseInsurancePatientDataFederalStateIDInvalid, CodeInsurancePatientDataFederalStateIDInvalid, "federal_state_id is invalid")
+	ErrInsurancePatientDataCreateFailed             = DefByModule(ModuleInsurancePatientData, http.StatusBadRequest, CaseInsurancePatientDataCreateFailed, CodeInsurancePatientDataCreateFailed, "failed to create insurance patient data")
+	ErrInsurancePatientDataUpdateFailed             = DefByModule(ModuleInsurancePatientData, http.StatusBadRequest, CaseInsurancePatientDataUpdateFailed, CodeInsurancePatientDataUpdateFailed, "failed to update insurance patient data")
+	ErrInsurancePatientDataDeleteFailed             = DefByModule(ModuleInsurancePatientData, http.StatusBadRequest, CaseInsurancePatientDataDeleteFailed, CodeInsurancePatientDataDeleteFailed, "failed to delete insurance patient data")
+	ErrInsurancePatientDataListFailed               = DefByModule(ModuleInsurancePatientData, http.StatusBadRequest, CaseInsurancePatientDataListFailed, CodeInsurancePatientDataListFailed, "failed to list insurance patient data")
+
+	// Patient Data
+	ErrPatientDataNotFound                      = DefByModule(ModulePatientData, http.StatusNotFound, CasePatientDataNotFound, CodePatientDataNotFound, "patient data not found")
+	ErrPatientDataRelationDelete                = DefByModule(ModulePatientData, http.StatusConflict, CasePatientDataRelationDelete, CodePatientDataRelationDelete, "cannot delete patient data due to active relations")
+	ErrPatientDataInvalidPayload                = DefByModule(ModulePatientData, http.StatusUnprocessableEntity, CasePatientDataInvalidPayload, CodePatientDataInvalidPayload, "invalid patient data payload")
+	ErrPatientDataInvalidJSON                   = DefByModule(ModulePatientData, http.StatusBadRequest, CasePatientDataInvalidJSON, CodePatientDataInvalidJSON, "invalid json payload")
+	ErrPatientDataInvalidUUID                   = DefByModule(ModulePatientData, http.StatusUnprocessableEntity, CasePatientDataInvalidUUID, CodePatientDataInvalidUUID, "patient data uuid is invalid")
+	ErrPatientDataIDRequired                    = DefByModule(ModulePatientData, http.StatusUnprocessableEntity, CasePatientDataIDRequired, CodePatientDataIDRequired, "patient data id is required")
+	ErrPatientDataIDMismatch                    = DefByModule(ModulePatientData, http.StatusUnprocessableEntity, CasePatientDataIDMismatch, CodePatientDataIDMismatch, "patient data id mismatch")
+	ErrPatientDataAttributesRequired            = DefByModule(ModulePatientData, http.StatusUnprocessableEntity, CasePatientDataAttributesRequired, CodePatientDataAttributesRequired, "at least one patient data attribute must be provided")
+	ErrPatientDataFamilyNameRequired            = DefByModule(ModulePatientData, http.StatusUnprocessableEntity, CasePatientDataFamilyNameRequired, CodePatientDataFamilyNameRequired, "family_name is required")
+	ErrPatientDataFirstNameRequired             = DefByModule(ModulePatientData, http.StatusUnprocessableEntity, CasePatientDataFirstNameRequired, CodePatientDataFirstNameRequired, "first_name is required")
+	ErrPatientDataBirthDateInvalid              = DefByModule(ModulePatientData, http.StatusUnprocessableEntity, CasePatientDataBirthDateInvalid, CodePatientDataBirthDateInvalid, "birth_date is invalid")
+	ErrPatientDataGenderInvalid                 = DefByModule(ModulePatientData, http.StatusUnprocessableEntity, CasePatientDataGenderInvalid, CodePatientDataGenderInvalid, "gender is invalid")
+	ErrPatientDataOPCIDInvalid                  = DefByModule(ModulePatientData, http.StatusUnprocessableEntity, CasePatientDataOPCIDInvalid, CodePatientDataOPCIDInvalid, "opc_id is invalid")
+	ErrPatientDataInsurancePatientDataIDInvalid = DefByModule(ModulePatientData, http.StatusUnprocessableEntity, CasePatientDataInsurancePatientDataIDInvalid, CodePatientDataInsurancePatientDataIDInvalid, "insurance_patient_data_id is invalid")
+	ErrPatientDataCreateFailed                  = DefByModule(ModulePatientData, http.StatusBadRequest, CasePatientDataCreateFailed, CodePatientDataCreateFailed, "failed to create patient data")
+	ErrPatientDataUpdateFailed                  = DefByModule(ModulePatientData, http.StatusBadRequest, CasePatientDataUpdateFailed, CodePatientDataUpdateFailed, "failed to update patient data")
+	ErrPatientDataDeleteFailed                  = DefByModule(ModulePatientData, http.StatusBadRequest, CasePatientDataDeleteFailed, CodePatientDataDeleteFailed, "failed to delete patient data")
+	ErrPatientDataListFailed                    = DefByModule(ModulePatientData, http.StatusBadRequest, CasePatientDataListFailed, CodePatientDataListFailed, "failed to list patient data")
+
+	// Role
+	ErrRoleNotFound                 = DefByModule(ModuleRole, http.StatusNotFound, CaseRoleNotFound, CodeRoleNotFound, "role not found")
+	ErrRolePermissionNotFound       = DefByModule(ModuleRole, http.StatusNotFound, CaseRolePermissionNotFound, CodeRolePermissionNotFound, "permission not found")
+	ErrRoleRelationDelete           = DefByModule(ModuleRole, http.StatusConflict, CaseRoleRelationDelete, CodeRoleRelationDelete, "cannot delete role due to active relations")
+	ErrRoleInvalidPayload           = DefByModule(ModuleRole, http.StatusUnprocessableEntity, CaseRoleInvalidPayload, CodeRoleInvalidPayload, "invalid role payload")
+	ErrRoleInvalidJSON              = DefByModule(ModuleRole, http.StatusBadRequest, CaseRoleInvalidJSON, CodeRoleInvalidJSON, "invalid json payload")
+	ErrRoleInvalidUUID              = DefByModule(ModuleRole, http.StatusUnprocessableEntity, CaseRoleInvalidUUID, CodeRoleInvalidUUID, "role uuid is invalid")
+	ErrRoleInvalidPermissionUUID    = DefByModule(ModuleRole, http.StatusUnprocessableEntity, CaseRoleInvalidPermissionUUID, CodeRoleInvalidPermissionUUID, "permission uuid is invalid")
+	ErrRoleIDRequired               = DefByModule(ModuleRole, http.StatusUnprocessableEntity, CaseRoleIDRequired, CodeRoleIDRequired, "role id is required")
+	ErrRoleIDMismatch               = DefByModule(ModuleRole, http.StatusUnprocessableEntity, CaseRoleIDMismatch, CodeRoleIDMismatch, "role id mismatch")
+	ErrRoleAttributesRequired       = DefByModule(ModuleRole, http.StatusUnprocessableEntity, CaseRoleAttributesRequired, CodeRoleAttributesRequired, "at least one role attribute must be provided")
+	ErrRoleNameRequired             = DefByModule(ModuleRole, http.StatusUnprocessableEntity, CaseRoleNameRequired, CodeRoleNameRequired, "role name is required")
+	ErrRolePermissionIDRequired     = DefByModule(ModuleRole, http.StatusUnprocessableEntity, CaseRolePermissionIDRequired, CodeRolePermissionIDRequired, "permission_id is required")
+	ErrRolePermissionIDsEmpty       = DefByModule(ModuleRole, http.StatusUnprocessableEntity, CaseRolePermissionIDsEmpty, CodeRolePermissionIDsEmpty, "permission_ids must not be empty")
+	ErrRoleCreateFailed             = DefByModule(ModuleRole, http.StatusBadRequest, CaseRoleCreateFailed, CodeRoleCreateFailed, "failed to create role")
+	ErrRoleUpdateFailed             = DefByModule(ModuleRole, http.StatusBadRequest, CaseRoleUpdateFailed, CodeRoleUpdateFailed, "failed to update role")
+	ErrRoleDeleteFailed             = DefByModule(ModuleRole, http.StatusBadRequest, CaseRoleDeleteFailed, CodeRoleDeleteFailed, "failed to delete role")
+	ErrRoleAssignFailed             = DefByModule(ModuleRole, http.StatusBadRequest, CaseRoleAssignFailed, CodeRoleAssignFailed, "failed to assign permission")
+	ErrRoleRemoveFailed             = DefByModule(ModuleRole, http.StatusBadRequest, CaseRoleRemoveFailed, CodeRoleRemoveFailed, "failed to remove permission")
+	ErrRoleListFailed               = DefByModule(ModuleRole, http.StatusBadRequest, CaseRoleListFailed, CodeRoleListFailed, "failed to list role data")
+	ErrRolePermissionListFailed     = DefByModule(ModuleRole, http.StatusBadRequest, CaseRolePermissionListFailed, CodeRolePermissionListFailed, "failed to list permission data")
+	ErrRolePermissionUpdateFailed   = DefByModule(ModuleRole, http.StatusBadRequest, CaseRolePermissionUpdateFailed, CodeRolePermissionUpdateFailed, "failed to update permission")
+	ErrRolePermissionRequiresPINReq = DefByModule(ModuleRole, http.StatusUnprocessableEntity, CaseRolePermissionRequiresPINReq, CodeRolePermissionRequiresPINReq, "requires_pin is required")
+
+	// Flight Data
+	ErrFlightDataNotFound                     = DefByModule(ModuleFlightData, http.StatusNotFound, CaseFlightDataNotFound, CodeFlightDataNotFound, "flight data not found")
+	ErrFlightDataInvalidPayload               = DefByModule(ModuleFlightData, http.StatusUnprocessableEntity, CaseFlightDataInvalidPayload, CodeFlightDataInvalidPayload, "invalid flight data payload")
+	ErrFlightDataInvalidJSON                  = DefByModule(ModuleFlightData, http.StatusBadRequest, CaseFlightDataInvalidJSON, CodeFlightDataInvalidJSON, "invalid json payload")
+	ErrFlightDataInvalidPathUUID              = DefByModule(ModuleFlightData, http.StatusUnprocessableEntity, CaseFlightDataInvalidPathUUID, CodeFlightDataInvalidPathUUID, "path uuid is invalid")
+	ErrFlightDataMissionIDRequired            = DefByModule(ModuleFlightData, http.StatusUnprocessableEntity, CaseFlightDataMissionIDRequired, CodeFlightDataMissionIDRequired, "mission_id is required")
+	ErrFlightDataCoPilotIDRequired            = DefByModule(ModuleFlightData, http.StatusUnprocessableEntity, CaseFlightDataCoPilotIDRequired, CodeFlightDataCoPilotIDRequired, "co_pilot_id is required")
+	ErrFlightDataPilotIDRequired              = ErrFlightDataCoPilotIDRequired
+	ErrFlightDataMissionReference             = DefByModule(ModuleFlightData, http.StatusUnprocessableEntity, CaseFlightDataMissionReference, CodeFlightDataMissionReference, "mission reference is invalid")
+	ErrFlightDataPilotReference               = DefByModule(ModuleFlightData, http.StatusUnprocessableEntity, CaseFlightDataPilotReference, CodeFlightDataPilotReference, "pilot reference is invalid")
+	ErrFlightDataInvalidUUID                  = DefByModule(ModuleFlightData, http.StatusUnprocessableEntity, CaseFlightDataInvalidUUID, CodeFlightDataInvalidUUID, "uuid is invalid")
+	ErrFlightDataInvalidRFC3339               = DefByModule(ModuleFlightData, http.StatusUnprocessableEntity, CaseFlightDataInvalidRFC3339, CodeFlightDataInvalidRFC3339, "datetime must be RFC3339")
+	ErrFlightDataOriginLocationReference      = DefByModule(ModuleFlightData, http.StatusUnprocessableEntity, CaseFlightDataOriginLocationReference, CodeFlightDataOriginLocationReference, "origin location reference is invalid")
+	ErrFlightDataDestinationLocationReference = DefByModule(ModuleFlightData, http.StatusUnprocessableEntity, CaseFlightDataDestinationLocationReference, CodeFlightDataDestinationLocationReference, "destination location reference is invalid")
+	ErrFlightDataFacilityReference            = DefByModule(ModuleFlightData, http.StatusUnprocessableEntity, CaseFlightDataFacilityReference, CodeFlightDataFacilityReference, "facility reference is invalid")
+	ErrFlightDataRequired                     = DefByModule(ModuleFlightData, http.StatusBadRequest, CaseFlightDataRequired, CodeFlightDataRequired, "required flight data is missing")
+	ErrFlightDataCreateFailed                 = DefByModule(ModuleFlightData, http.StatusBadRequest, CaseFlightDataCreateFailed, CodeFlightDataCreateFailed, "failed to create flight data")
+	ErrFlightDataGetFailed                    = DefByModule(ModuleFlightData, http.StatusBadRequest, CaseFlightDataGetFailed, CodeFlightDataGetFailed, "failed to get flight data")
+	ErrFlightDataAfterFlightIncomplete        = DefByModule(ModuleFlightData, http.StatusUnprocessableEntity, CaseFlightDataAfterFlightIncomplete, CodeFlightDataAfterFlightIncomplete, "cannot submit after-flight: flight data is incomplete")
+	ErrFlightDataLockedAfterFlightInspection  = DefByModule(ModuleFlightData, http.StatusLocked, CaseFlightDataAfterFlightLocked, CodeFlightDataAfterFlightLocked, "flight data is locked because after flight inspection already exists")
+	ErrFlightDataCreateBlocked                = DefByModule(ModuleFlightData, http.StatusConflict, "18", "FLIGHT_DATA_CREATE_BLOCKED", "flight data cannot be created because fm report already exists for this flight")
+	ErrFlightDataLocked                       = DefByModule(ModuleFlightData, http.StatusLocked, "19", "FLIGHT_DATA_LOCKED", "flight data is locked because fm report is completed")
+
+	// Air Rescuer Checklist
+	ErrAirRescuerChecklistNotFound         = DefByModule(ModuleAirRescuerChecklist, http.StatusNotFound, CaseAirRescuerChecklistNotFound, CodeAirRescuerChecklistNotFound, "air rescuer checklist not found")
+	ErrAirRescuerChecklistItemNotFound     = DefByModule(ModuleAirRescuerChecklist, http.StatusNotFound, CaseAirRescuerChecklistItemNotFound, CodeAirRescuerChecklistItemNotFound, "air rescuer checklist item not found")
+	ErrAirRescuerChecklistInvalidPayload   = DefByModule(ModuleAirRescuerChecklist, http.StatusUnprocessableEntity, CaseAirRescuerChecklistInvalidPayload, CodeAirRescuerChecklistInvalidPayload, "invalid air rescuer checklist payload")
+	ErrAirRescuerChecklistInvalidJSON      = DefByModule(ModuleAirRescuerChecklist, http.StatusBadRequest, CaseAirRescuerChecklistInvalidJSON, CodeAirRescuerChecklistInvalidJSON, "invalid json payload")
+	ErrAirRescuerChecklistInvalidUUID      = DefByModule(ModuleAirRescuerChecklist, http.StatusUnprocessableEntity, CaseAirRescuerChecklistInvalidUUID, CodeAirRescuerChecklistInvalidUUID, "air rescuer checklist uuid is invalid")
+	ErrAirRescuerChecklistIDMismatch       = DefByModule(ModuleAirRescuerChecklist, http.StatusUnprocessableEntity, CaseAirRescuerChecklistIDMismatch, CodeAirRescuerChecklistIDMismatch, "id does not match path uuid")
+	ErrAirRescuerChecklistScopeInvalid     = DefByModule(ModuleAirRescuerChecklist, http.StatusUnprocessableEntity, CaseAirRescuerChecklistScopeInvalid, CodeAirRescuerChecklistScopeInvalid, "scope_code is invalid")
+	ErrAirRescuerChecklistScopeRequired    = DefByModule(ModuleAirRescuerChecklist, http.StatusUnprocessableEntity, CaseAirRescuerChecklistScopeRequired, CodeAirRescuerChecklistScopeRequired, "scope_code is required")
+	ErrAirRescuerChecklistTitleRequired    = DefByModule(ModuleAirRescuerChecklist, http.StatusUnprocessableEntity, CaseAirRescuerChecklistTitleRequired, CodeAirRescuerChecklistTitleRequired, "title is required")
+	ErrAirRescuerChecklistNameRequired     = DefByModule(ModuleAirRescuerChecklist, http.StatusUnprocessableEntity, CaseAirRescuerChecklistNameRequired, CodeAirRescuerChecklistNameRequired, "name is required")
+	ErrAirRescuerChecklistBaseNotFound     = DefByModule(ModuleAirRescuerChecklist, http.StatusNotFound, CaseAirRescuerChecklistBaseNotFound, CodeAirRescuerChecklistBaseNotFound, "base not found")
+	ErrAirRescuerChecklistCreateFailed     = DefByModule(ModuleAirRescuerChecklist, http.StatusBadRequest, CaseAirRescuerChecklistCreateFailed, CodeAirRescuerChecklistCreateFailed, "failed to create air rescuer checklist")
+	ErrAirRescuerChecklistUpdateFailed     = DefByModule(ModuleAirRescuerChecklist, http.StatusBadRequest, CaseAirRescuerChecklistUpdateFailed, CodeAirRescuerChecklistUpdateFailed, "failed to update air rescuer checklist")
+	ErrAirRescuerChecklistDeleteFailed     = DefByModule(ModuleAirRescuerChecklist, http.StatusBadRequest, CaseAirRescuerChecklistDeleteFailed, CodeAirRescuerChecklistDeleteFailed, "failed to delete air rescuer checklist")
+	ErrAirRescuerChecklistListFailed       = DefByModule(ModuleAirRescuerChecklist, http.StatusBadRequest, CaseAirRescuerChecklistListFailed, CodeAirRescuerChecklistListFailed, "failed to list air rescuer checklist")
+	ErrAirRescuerChecklistReorderFailed    = DefByModule(ModuleAirRescuerChecklist, http.StatusBadRequest, CaseAirRescuerChecklistReorderFailed, CodeAirRescuerChecklistReorderFailed, "failed to reorder air rescuer checklist items")
+	ErrAirRescuerChecklistValidationFailed = DefByModule(ModuleAirRescuerChecklist, http.StatusUnprocessableEntity, CaseAirRescuerChecklistValidationFailed, CodeAirRescuerChecklistValidationFailed, "air rescuer checklist validation failed")
+
+	// Takeover
+	ErrTakeoverNotFound           = DefByModule(ModuleTakeover, http.StatusNotFound, CaseTakeoverNotFound, CodeTakeoverNotFound, "takeover not found")
+	ErrTakeoverInvalidPayload     = DefByModule(ModuleTakeover, http.StatusUnprocessableEntity, CaseTakeoverInvalidPayload, CodeTakeoverInvalidPayload, "invalid takeover payload")
+	ErrTakeoverInvalidJSON        = DefByModule(ModuleTakeover, http.StatusBadRequest, CaseTakeoverInvalidJSON, CodeTakeoverInvalidJSON, "invalid json payload")
+	ErrTakeoverInvalidUUID        = DefByModule(ModuleTakeover, http.StatusUnprocessableEntity, CaseTakeoverInvalidUUID, CodeTakeoverInvalidUUID, "takeover uuid is invalid")
+	ErrTakeoverIDRequired         = DefByModule(ModuleTakeover, http.StatusUnprocessableEntity, CaseTakeoverIDRequired, CodeTakeoverIDRequired, "id is required")
+	ErrTakeoverIDMismatch         = DefByModule(ModuleTakeover, http.StatusUnprocessableEntity, CaseTakeoverIDMismatch, CodeTakeoverIDMismatch, "id does not match path uuid")
+	ErrTakeoverFileSectionInvalid = DefByModule(ModuleTakeover, http.StatusUnprocessableEntity, CaseTakeoverFileSectionInvalid, CodeTakeoverFileSectionInvalid, "helicopter_file_id does not belong to selected helicopter/section")
+	ErrTakeoverCreateFailed       = DefByModule(ModuleTakeover, http.StatusBadRequest, CaseTakeoverCreateFailed, CodeTakeoverCreateFailed, "failed to create takeover")
+	ErrTakeoverUpdateFailed       = DefByModule(ModuleTakeover, http.StatusBadRequest, CaseTakeoverUpdateFailed, CodeTakeoverUpdateFailed, "failed to update takeover")
+	ErrTakeoverDeleteFailed       = DefByModule(ModuleTakeover, http.StatusBadRequest, CaseTakeoverDeleteFailed, CodeTakeoverDeleteFailed, "failed to delete takeover")
+	ErrTakeoverGetFailed          = DefByModule(ModuleTakeover, http.StatusBadRequest, CaseTakeoverGetFailed, CodeTakeoverGetFailed, "failed to get takeover")
+	ErrTakeoverListFailed         = DefByModule(ModuleTakeover, http.StatusBadRequest, CaseTakeoverListFailed, CodeTakeoverListFailed, "failed to list takeover data")
+	ErrTakeoverHelicopterInUse    = DefByModule(ModuleTakeover, http.StatusConflict, CaseTakeoverHelicopterInUse, CodeTakeoverHelicopterInUse, "helicopter is already booked and cannot be used")
+	ErrTakeoverHelicopterAOG      = DefByModule(ModuleTakeover, http.StatusConflict, CaseTakeoverHelicopterAOG, CodeTakeoverHelicopterAOG, "helicopter is AOG (grounded) and cannot be used")
+	ErrTakeoverHelicopterMCF      = DefByModule(ModuleTakeover, http.StatusConflict, CaseTakeoverHelicopterMCF, CodeTakeoverHelicopterMCF, "helicopter is in MCF and cannot be used")
+
+	// Fleet Status
+	ErrFleetStatusNotFound           = DefByModule(ModuleFleetStatus, http.StatusNotFound, CaseFleetStatusNotFound, CodeFleetStatusNotFound, "fleet status not found")
+	ErrFleetStatusInvalidPayload     = DefByModule(ModuleFleetStatus, http.StatusUnprocessableEntity, CaseFleetStatusInvalidPayload, CodeFleetStatusInvalidPayload, "invalid fleet status payload")
+	ErrFleetStatusInvalidJSON        = DefByModule(ModuleFleetStatus, http.StatusBadRequest, CaseFleetStatusInvalidJSON, CodeFleetStatusInvalidJSON, "invalid json payload")
+	ErrFleetStatusInvalidID          = DefByModule(ModuleFleetStatus, http.StatusUnprocessableEntity, CaseFleetStatusInvalidID, CodeFleetStatusInvalidID, "fleet status id is invalid")
+	ErrFleetStatusIDRequired         = DefByModule(ModuleFleetStatus, http.StatusUnprocessableEntity, CaseFleetStatusIDRequired, CodeFleetStatusIDRequired, "id is required")
+	ErrFleetStatusIDMismatch         = DefByModule(ModuleFleetStatus, http.StatusUnprocessableEntity, CaseFleetStatusIDMismatch, CodeFleetStatusIDMismatch, "id does not match path id")
+	ErrFleetStatusHelicopterRequired = DefByModule(ModuleFleetStatus, http.StatusUnprocessableEntity, CaseFleetStatusHelicopterRequired, CodeFleetStatusHelicopterRequired, "helicopter_id is required")
+	ErrFleetStatusHelicopterInvalid  = DefByModule(ModuleFleetStatus, http.StatusUnprocessableEntity, CaseFleetStatusHelicopterInvalid, CodeFleetStatusHelicopterInvalid, "referenced helicopter does not exist")
+	ErrFleetStatusDuplicate          = DefByModule(ModuleFleetStatus, http.StatusConflict, CaseFleetStatusDuplicate, CodeFleetStatusDuplicate, "fleet status already exists")
+	ErrFleetStatusRelationDelete     = DefByModule(ModuleFleetStatus, http.StatusConflict, CaseFleetStatusRelationDelete, CodeFleetStatusRelationDelete, "cannot delete fleet status due to active relations")
+	// Deprecated: 400 is wrong for unexpected service/DB failures — service errors now
+	// go through writeFleetStatusServiceError (500 fallback). Do not use as a new fallback.
+	// TODO: remove these from the catalog in a separate cleanup.
+	ErrFleetStatusCreateFailed       = DefByModule(ModuleFleetStatus, http.StatusBadRequest, CaseFleetStatusCreateFailed, CodeFleetStatusCreateFailed, "failed to create fleet status")
+	ErrFleetStatusUpdateFailed       = DefByModule(ModuleFleetStatus, http.StatusBadRequest, CaseFleetStatusUpdateFailed, CodeFleetStatusUpdateFailed, "failed to update fleet status")
+	ErrFleetStatusDeleteFailed       = DefByModule(ModuleFleetStatus, http.StatusBadRequest, CaseFleetStatusDeleteFailed, CodeFleetStatusDeleteFailed, "failed to delete fleet status")
+	ErrFleetStatusListFailed         = DefByModule(ModuleFleetStatus, http.StatusBadRequest, CaseFleetStatusListFailed, CodeFleetStatusListFailed, "failed to list fleet status data")
+	ErrFleetStatusMarkServicedFailed = DefByModule(ModuleFleetStatus, http.StatusBadRequest, CaseFleetStatusMarkServicedFailed, CodeFleetStatusMarkServicedFailed, "failed to mark fleet status serviced")
+
+	// Fleet Status File (upload + create)
+	ErrFleetStatusFileInvalidJSON         = DefByModule(ModuleFleetStatus, http.StatusBadRequest, CaseFleetStatusFileInvalidJSON, CodeFleetStatusFileInvalidJSON, "invalid json payload")
+	ErrFleetStatusFileInvalidPayload      = DefByModule(ModuleFleetStatus, http.StatusUnprocessableEntity, CaseFleetStatusFileInvalidPayload, CodeFleetStatusFileInvalidPayload, "invalid fleet status file payload")
+	ErrFleetStatusFileUploadIntentInvalid = DefByModule(ModuleFleetStatus, http.StatusConflict, CaseFleetStatusFileUploadIntentInvalid, CodeFleetStatusFileUploadIntentInvalid, "upload intent is invalid, expired, or already used")
+	ErrFleetStatusFileStorageUnavailable  = DefByModule(ModuleFleetStatus, http.StatusServiceUnavailable, CaseFleetStatusFileStorageUnavailable, CodeFleetStatusFileStorageUnavailable, "file storage is unavailable")
+	ErrFleetStatusFileFailed              = DefByModule(ModuleFleetStatus, http.StatusBadRequest, CaseFleetStatusFileFailed, CodeFleetStatusFileFailed, "failed to process fleet status file")
+
+	// Complaint
+	ErrComplaintNotFound            = DefByModule(ModuleComplaint, http.StatusNotFound, "01", CodeComplaintNotFound, "complaint not found")
+	ErrComplaintInvalidPayload      = DefByModule(ModuleComplaint, http.StatusUnprocessableEntity, "02", CodeComplaintInvalidPayload, "invalid complaint payload")
+	ErrComplaintInvalidJSON         = DefByModule(ModuleComplaint, http.StatusBadRequest, "03", CodeComplaintInvalidJSON, "invalid json payload")
+	ErrComplaintInvalidUUID         = DefByModule(ModuleComplaint, http.StatusUnprocessableEntity, "04", CodeComplaintInvalidUUID, "complaint uuid is invalid")
+	ErrComplaintIDRequired          = DefByModule(ModuleComplaint, http.StatusUnprocessableEntity, "05", CodeComplaintIDRequired, "complaint id is required")
+	ErrComplaintIDMismatch          = DefByModule(ModuleComplaint, http.StatusUnprocessableEntity, "06", CodeComplaintIDMismatch, "complaint id does not match path id")
+	ErrComplaintCreateFailed        = DefByModule(ModuleComplaint, http.StatusBadRequest, "07", CodeComplaintCreateFailed, "failed to create complaint")
+	ErrComplaintUpdateFailed        = DefByModule(ModuleComplaint, http.StatusBadRequest, "08", CodeComplaintUpdateFailed, "failed to update complaint")
+	ErrComplaintDeleteFailed        = DefByModule(ModuleComplaint, http.StatusBadRequest, "09", CodeComplaintDeleteFailed, "failed to delete complaint")
+	ErrComplaintListFailed          = DefByModule(ModuleComplaint, http.StatusBadRequest, "10", CodeComplaintListFailed, "failed to list complaint data")
+	ErrComplaintGroupedListFailed   = DefByModule(ModuleComplaint, http.StatusBadRequest, "11", CodeComplaintGroupedListFailed, "failed to list grouped complaint data")
+	ErrComplaintRelationDelete      = DefByModule(ModuleComplaint, http.StatusConflict, "12", CodeComplaintRelationDelete, "cannot delete complaint due to active relations")
+	ErrComplaintInvalidHelicopterID = DefByModule(ModuleComplaint, http.StatusUnprocessableEntity, "13", CodeComplaintInvalidHelicopterID, "helicopter id is invalid")
+	ErrComplaintMELRequired         = DefByModuleWithTitle(ModuleComplaint, http.StatusUnprocessableEntity, "15", CodeComplaintMELRequired, "Classify the MEL (Non-MEL or MEL A/B/C/D) before recording the action", "mel_severity must be classified before recording action taken (0=Non-MEL, 1=A, 2=B, 3=C, 4=D)")
+	ErrComplaintActionSignedLocked  = DefByModuleWithTitle(ModuleComplaint, http.StatusConflict, "16", CodeComplaintActionSignedLocked, "Action already signed off — cannot clear", "cannot clear a signed-off corrective action; unsign it first")
+
+	ErrEASAReleaseNotFound          = DefByModule(ModuleEASARelease, http.StatusNotFound, "01", CodeEASAReleaseNotFound, "easa release not found")
+	ErrEASAReleaseInvalidJSON       = DefByModule(ModuleEASARelease, http.StatusBadRequest, "02", CodeEASAReleaseInvalidJSON, "invalid json payload")
+	ErrEASAReleaseInvalidUUID       = DefByModule(ModuleEASARelease, http.StatusUnprocessableEntity, "03", CodeEASAReleaseInvalidUUID, "easa release uuid is invalid")
+	ErrEASAReleaseInvalidPayload    = DefByModule(ModuleEASARelease, http.StatusUnprocessableEntity, "04", CodeEASAReleaseInvalidPayload, "invalid easa release payload")
+	ErrEASAReleaseCreateFailed      = DefByModule(ModuleEASARelease, http.StatusBadRequest, "05", CodeEASAReleaseCreateFailed, "failed to create easa release")
+	ErrEASAReleaseUpdateFailed      = DefByModule(ModuleEASARelease, http.StatusBadRequest, "06", CodeEASAReleaseUpdateFailed, "failed to update easa release")
+	ErrEASAReleaseDeleteFailed      = DefByModule(ModuleEASARelease, http.StatusBadRequest, "07", CodeEASAReleaseDeleteFailed, "failed to delete easa release")
+	ErrEASAReleaseListFailed        = DefByModule(ModuleEASARelease, http.StatusBadRequest, "08", CodeEASAReleaseListFailed, "failed to list easa release data")
+	ErrEASAReleaseSignFailed        = DefByModule(ModuleEASARelease, http.StatusBadRequest, "09", CodeEASAReleaseSignFailed, "failed to sign easa release")
+	ErrEASAReleaseAlreadySigned     = DefByModule(ModuleEASARelease, http.StatusConflict, "10", CodeEASAReleaseAlreadySigned, "easa release already signed")
+	ErrEASAReleaseIncompleteForSign = DefByModuleWithTitle(ModuleEASARelease, http.StatusUnprocessableEntity, "12", CodeEASAReleaseIncompleteForSign, "Fill all required fields before signing the release", "cannot sign release: required fields are incomplete")
+	ErrEASAReleaseSignoffRequired   = DefByModuleWithTitle(ModuleEASARelease, http.StatusUnprocessableEntity, "13", CodeEASAReleaseSignoffRequired, "Sign off the corrective action before releasing to service", "cannot create release: the corrective-action sign-off is missing")
+
+	ErrActionSignoffNotFound          = DefByModule(ModuleActionSignoff, http.StatusNotFound, "01", CodeActionSignoffNotFound, "action sign-off not found")
+	ErrActionSignoffInvalidUUID       = DefByModule(ModuleActionSignoff, http.StatusUnprocessableEntity, "02", CodeActionSignoffInvalidUUID, "action sign-off helicopter id is invalid")
+	ErrActionSignoffInvalidJSON       = DefByModule(ModuleActionSignoff, http.StatusBadRequest, "03", CodeActionSignoffInvalidJSON, "invalid json payload")
+	ErrActionSignoffSignFailed        = DefByModule(ModuleActionSignoff, http.StatusBadRequest, "04", CodeActionSignoffSignFailed, "failed to sign action sign-off")
+	ErrActionSignoffUnsignFailed      = DefByModule(ModuleActionSignoff, http.StatusBadRequest, "05", CodeActionSignoffUnsignFailed, "failed to unsign action sign-off")
+	ErrActionSignoffComplaintNotFound = DefByModule(ModuleActionSignoff, http.StatusNotFound, "06", CodeActionSignoffComplaintNotFound, "complaint not found for action sign-off")
+	ErrActionSignoffActionRequired    = DefByModuleWithTitle(ModuleActionSignoff, http.StatusUnprocessableEntity, "07", CodeActionSignoffActionRequired, "Record the corrective action first", "action_taken must be recorded on the complaint before it can be signed off")
+
+	ErrMCFNotFound       = DefByModule(ModuleMCF, http.StatusNotFound, "01", CodeMCFNotFound, "maintenance check flight not found")
+	ErrMCFInvalidJSON    = DefByModule(ModuleMCF, http.StatusBadRequest, "02", CodeMCFInvalidJSON, "invalid json payload")
+	ErrMCFInvalidUUID    = DefByModule(ModuleMCF, http.StatusUnprocessableEntity, "03", CodeMCFInvalidUUID, "mcf uuid is invalid")
+	ErrMCFInvalidPayload = DefByModule(ModuleMCF, http.StatusUnprocessableEntity, "04", CodeMCFInvalidPayload, "invalid mcf payload")
+	ErrMCFCreateFailed   = DefByModule(ModuleMCF, http.StatusBadRequest, "05", CodeMCFCreateFailed, "failed to create mcf")
+	ErrMCFCompleteFailed = DefByModule(ModuleMCF, http.StatusBadRequest, "06", CodeMCFCompleteFailed, "failed to complete mcf")
+	ErrMCFListFailed     = DefByModule(ModuleMCF, http.StatusBadRequest, "08", CodeMCFListFailed, "failed to list mcf data")
+	ErrMCFNoOpen         = DefByModule(ModuleMCF, http.StatusConflict, "09", CodeMCFNoOpen, "helicopter has no open mcf to complete")
+	ErrMCFHelicopterHasOpen = DefByModuleWithTitle(ModuleMCF, http.StatusConflict, "10", CodeMCFHelicopterHasOpen, "Helicopter already has an open MCF", "helicopter already has an open (unsigned) mcf; complete it first")
+
+	// Mission
+	ErrMissionNotFound                    = DefByModule(ModuleMissionOps, http.StatusNotFound, CaseMissionNotFound, CodeMissionNotFound, "mission not found")
+	ErrMissionInvalidPayload              = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseMissionInvalidPayload, CodeMissionInvalidPayload, "invalid mission payload")
+	ErrMissionInvalidJSON                 = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseMissionInvalidJSON, CodeMissionInvalidJSON, "invalid json payload")
+	ErrMissionInvalidFlightUUID           = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseMissionInvalidFlightUUID, CodeMissionInvalidFlightUUID, "flight uuid is invalid")
+	ErrMissionInvalidMissionUUID          = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseMissionInvalidMissionUUID, CodeMissionInvalidMissionUUID, "mission uuid is invalid")
+	ErrMissionFlightIDRequired            = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseMissionFlightIDRequired, CodeMissionFlightIDRequired, "flight_id is required")
+	ErrMissionMissionIDRequired           = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseMissionMissionIDRequired, CodeMissionMissionIDRequired, "mission_id is required")
+	ErrMissionTypeInvalid                 = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseMissionTypeInvalid, CodeMissionTypeInvalid, "mission type is invalid")
+	ErrMissionSubtypeRequired             = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseMissionSubtypeRequired, CodeMissionSubtypeRequired, "subtype_id is required")
+	ErrMissionSubtypeInvalid              = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseMissionSubtypeInvalid, CodeMissionSubtypeInvalid, "subtype_id is invalid")
+	ErrMissionSubtypeForbidden            = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseMissionSubtypeForbidden, CodeMissionSubtypeForbidden, "subtype_id is forbidden")
+	ErrMissionDuplicateFlight             = DefByModule(ModuleMissionOps, http.StatusConflict, CaseMissionDuplicateFlight, CodeMissionDuplicateFlight, "mission for this flight already exists")
+	ErrMissionCreateFailed                = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseMissionCreateFailed, CodeMissionCreateFailed, "failed to create mission")
+	ErrMissionUpdateFailed                = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseMissionUpdateFailed, CodeMissionUpdateFailed, "failed to update mission")
+	ErrMissionDeleteFailed                = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseMissionDeleteFailed, CodeMissionDeleteFailed, "failed to delete mission")
+	ErrMissionGetFailed                   = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseMissionGetFailed, CodeMissionGetFailed, "failed to get mission")
+	ErrMissionListFailed                  = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseMissionListFailed, CodeMissionListFailed, "failed to list mission data")
+	ErrMissionLockedAfterFlightInspection = DefByModule(ModuleMissionOps, http.StatusLocked, CaseMissionAfterFlightLocked, CodeMissionAfterFlightLocked, "mission is locked because after flight inspection already exists")
+	ErrMissionFileInvalidJSON             = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseMissionFileInvalidJSON, CodeMissionFileInvalidJSON, "invalid mission file json payload")
+	ErrMissionFileValidation              = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseMissionFileValidation, CodeMissionFileValidation, "mission file validation failed")
+	ErrMissionFileInvalidMissionUUID      = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseMissionFileInvalidMissionUUID, CodeMissionFileInvalidMissionUUID, "mission file mission_uuid is invalid")
+	ErrMissionFileMissionNotFound         = DefByModule(ModuleMissionOps, http.StatusNotFound, CaseMissionFileMissionNotFound, CodeMissionFileMissionNotFound, "mission for the file was not found")
+	ErrMissionFileServiceUnavailable      = DefByModule(ModuleMissionOps, http.StatusServiceUnavailable, CaseMissionFileServiceUnavailable, CodeMissionFileServiceUnavailable, "mission service is unavailable for file linking")
+	ErrMissionFileActionFailed            = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseMissionFileActionFailed, CodeMissionFileActionFailed, "failed to create or attach mission file")
+
+	// HEMS Operation
+	ErrHEMSOperationNotFound                 = DefByModule(ModuleMissionOps, http.StatusNotFound, CaseHEMSOperationNotFound, CodeHEMSOperationNotFound, "hems operation not found")
+	ErrHEMSOperationInvalidPayload           = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseHEMSOperationInvalidPayload, CodeHEMSOperationInvalidPayload, "invalid hems operation payload")
+	ErrHEMSOperationInvalidJSON              = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseHEMSOperationInvalidJSON, CodeHEMSOperationInvalidJSON, "invalid json payload")
+	ErrHEMSOperationInvalidUUID              = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseHEMSOperationInvalidUUID, CodeHEMSOperationInvalidUUID, "hems operation uuid is invalid")
+	ErrHEMSOperationAttributesRequired       = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseHEMSOperationAttributesRequired, CodeHEMSOperationAttributesRequired, "at least one hems operation attribute must be provided")
+	ErrHEMSOperationDateInvalidRFC3339       = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseHEMSOperationDateInvalidRFC3339, CodeHEMSOperationDateInvalidRFC3339, "date must be in RFC3339 format")
+	ErrHEMSOperationRelationReferenceInvalid = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseHEMSOperationRelationReferenceInvalid, CodeHEMSOperationRelationReferenceInvalid, "relation reference is invalid")
+	ErrHEMSOperationCreateFailed             = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseHEMSOperationCreateFailed, CodeHEMSOperationCreateFailed, "failed to create hems operation")
+	ErrHEMSOperationUpdateFailed             = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseHEMSOperationUpdateFailed, CodeHEMSOperationUpdateFailed, "failed to update hems operation")
+	ErrHEMSOperationDeleteFailed             = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseHEMSOperationDeleteFailed, CodeHEMSOperationDeleteFailed, "failed to delete hems operation")
+	ErrHEMSOperationListFailed               = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseHEMSOperationListFailed, CodeHEMSOperationListFailed, "failed to list hems operation")
+	ErrForcesPresentNotFound                 = DefByModule(ModuleMissionOps, http.StatusNotFound, CaseForcesPresentNotFound, CodeForcesPresentNotFound, "forces present not found")
+	ErrForcesPresentRelationDelete           = DefByModule(ModuleMissionOps, http.StatusConflict, CaseForcesPresentRelationDelete, CodeForcesPresentRelationDelete, "cannot delete forces present due to active relations")
+	ErrForcesPresentInvalidPayload           = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseForcesPresentInvalidPayload, CodeForcesPresentInvalidPayload, "invalid forces present payload")
+	ErrForcesPresentInvalidJSON              = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseForcesPresentInvalidJSON, CodeForcesPresentInvalidJSON, "invalid json payload")
+	ErrForcesPresentInvalidUUID              = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseForcesPresentInvalidUUID, CodeForcesPresentInvalidUUID, "forces present uuid is invalid")
+	ErrForcesPresentIDRequired               = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseForcesPresentIDRequired, CodeForcesPresentIDRequired, "forces present id is required")
+	ErrForcesPresentIDMismatch               = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseForcesPresentIDMismatch, CodeForcesPresentIDMismatch, "forces present id mismatch")
+	ErrForcesPresentAttributesRequired       = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseForcesPresentAttributesRequired, CodeForcesPresentAttributesRequired, "at least one forces present attribute must be provided")
+	ErrForcesPresentNameRequired             = DefByModule(ModuleMissionOps, http.StatusUnprocessableEntity, CaseForcesPresentNameRequired, CodeForcesPresentNameRequired, "forces present name is required")
+	ErrForcesPresentCreateFailed             = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseForcesPresentCreateFailed, CodeForcesPresentCreateFailed, "failed to create forces present")
+	ErrForcesPresentUpdateFailed             = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseForcesPresentUpdateFailed, CodeForcesPresentUpdateFailed, "failed to update forces present")
+	ErrForcesPresentDeleteFailed             = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseForcesPresentDeleteFailed, CodeForcesPresentDeleteFailed, "failed to delete forces present")
+	ErrForcesPresentListFailed               = DefByModule(ModuleMissionOps, http.StatusBadRequest, CaseForcesPresentListFailed, CodeForcesPresentListFailed, "failed to list forces present data")
+
+	// Contact
+	ErrContactNotFound                          = DefByModule(ModuleContact, http.StatusNotFound, CaseContactNotFound, CodeContactNotFound, "contact not found")
+	ErrContactInvalidPayload                    = DefByModule(ModuleContact, http.StatusUnprocessableEntity, CaseContactInvalidPayload, CodeContactInvalidPayload, "invalid contact payload")
+	ErrContactInvalidJSON                       = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactInvalidJSON, CodeContactInvalidJSON, "invalid json payload")
+	ErrContactInvalidUserID                     = DefByModule(ModuleContact, http.StatusUnprocessableEntity, CaseContactInvalidUserID, CodeContactInvalidUserID, "user_id is invalid uuid")
+	ErrContactValidationFailed                  = DefByModule(ModuleContact, http.StatusUnprocessableEntity, CaseContactValidationFailed, CodeContactValidationFailed, "contact validation failed")
+	ErrContactCreateFailed                      = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactCreateFailed, CodeContactCreateFailed, "failed to create contact")
+	ErrContactGetFailed                         = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactGetFailed, CodeContactGetFailed, "failed to get contact")
+	ErrContactUpdateFailed                      = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactUpdateFailed, CodeContactUpdateFailed, "failed to update contact")
+	ErrContactUsernameConflict                  = DefByModule(ModuleContact, http.StatusConflict, CaseContactUsernameConflict, CodeContactUsernameConflict, "username already exists")
+	ErrContactDeleteFailed                      = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactDeleteFailed, CodeContactDeleteFailed, "failed to delete contact")
+	ErrContactUpdateStatusFailed                = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactUpdateStatusFailed, CodeContactUpdateStatusFailed, "failed to update contact status")
+	ErrContactUpdateRoleFailed                  = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactUpdateRoleFailed, CodeContactUpdateRoleFailed, "failed to update contact role")
+	ErrContactUpdatePilotCategoryFailed         = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactUpdatePilotCategoryFailed, CodeContactUpdatePilotCategoryFailed, "failed to update contact pilot category")
+	ErrContactUpdateLicenseFailed               = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactUpdateLicenseFailed, CodeContactUpdateLicenseFailed, "failed to update contact license")
+	ErrContactUpdateChiefFlagsFailed            = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactUpdateChiefFlagsFailed, CodeContactUpdateChiefFlagsFailed, "failed to update contact chief flags")
+	ErrContactUpdateResponsibleComplaintsFailed = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactUpdateResponsibleComplaintsFailed, CodeContactUpdateResponsibleComplaintsFailed, "failed to update contact responsible complaints")
+	ErrContactBulkUpdateFailed                  = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactBulkUpdateFailed, CodeContactBulkUpdateFailed, "failed to bulk update contacts")
+	ErrContactListFailed                        = DefByModule(ModuleContact, http.StatusBadRequest, CaseContactListFailed, CodeContactListFailed, "failed to list contacts")
+)
+
+// PublicDetail returns the sanitized message that can be exposed over HTTP.
+// The underlying AppError.Cause remains available for logs and observability.
+func PublicDetail(status int) string {
+	switch status {
+	case http.StatusBadRequest:
+		return "invalid request"
+	case http.StatusUnauthorized:
+		return "unauthorized"
+	case http.StatusForbidden:
+		return "forbidden"
+	case http.StatusNotFound:
+		return "not found"
+	case http.StatusConflict:
+		return "conflict"
+	case http.StatusUnprocessableEntity:
+		return "validation failed"
+	case http.StatusTooManyRequests:
+		return "too many requests"
+	default:
+		return "an internal error occurred"
+	}
+}
+
+// After Flight Inspection (Module 37)
+const (
+	CodeAfterFlightInvalidID                = "AFTER_FLIGHT_INVALID_ID"
+	CodeAfterFlightFlightInspectionNotFound = "AFTER_FLIGHT_FLIGHT_INSPECTION_NOT_FOUND"
+	CodeAfterFlightInspectionNotFound       = "AFTER_FLIGHT_INSPECTION_NOT_FOUND"
+	CodeAfterFlightCapabilitiesUnavailable  = "AFTER_FLIGHT_CAPABILITIES_UNAVAILABLE"
+	CodeAfterFlightNR1Required              = "AFTER_FLIGHT_NR1_REQUIRED"
+	CodeAfterFlightNR1NotAvailable          = "AFTER_FLIGHT_NR1_NOT_AVAILABLE"
+	CodeAfterFlightNR2Required              = "AFTER_FLIGHT_NR2_REQUIRED"
+	CodeAfterFlightNR2NotAvailable          = "AFTER_FLIGHT_NR2_NOT_AVAILABLE"
+	CodeAfterFlightLHRequired               = "AFTER_FLIGHT_LH_REQUIRED"
+	CodeAfterFlightLHNotAvailable           = "AFTER_FLIGHT_LH_NOT_AVAILABLE"
+	CodeAfterFlightRHRequired               = "AFTER_FLIGHT_RH_REQUIRED"
+	CodeAfterFlightRHNotAvailable           = "AFTER_FLIGHT_RH_NOT_AVAILABLE"
+	CodeAfterFlightMGBRequired              = "AFTER_FLIGHT_MGB_REQUIRED"
+	CodeAfterFlightMGBNotAvailable          = "AFTER_FLIGHT_MGB_NOT_AVAILABLE"
+	CodeAfterFlightIGBRequired              = "AFTER_FLIGHT_IGB_REQUIRED"
+	CodeAfterFlightIGBNotAvailable          = "AFTER_FLIGHT_IGB_NOT_AVAILABLE"
+	CodeAfterFlightTGBRequired              = "AFTER_FLIGHT_TGB_REQUIRED"
+	CodeAfterFlightTGBNotAvailable          = "AFTER_FLIGHT_TGB_NOT_AVAILABLE"
+	CodeAfterFlightInvalidJSON              = "AFTER_FLIGHT_INVALID_JSON"
+)
+
+const (
+	CaseAfterFlightInvalidID                = "01"
+	CaseAfterFlightFlightInspectionNotFound = "02"
+	CaseAfterFlightInspectionNotFound       = "03"
+	CaseAfterFlightCapabilitiesUnavailable  = "04"
+	CaseAfterFlightNR1Required              = "05"
+	CaseAfterFlightNR1NotAvailable          = "06"
+	CaseAfterFlightNR2Required              = "07"
+	CaseAfterFlightNR2NotAvailable          = "08"
+	CaseAfterFlightLHRequired               = "09"
+	CaseAfterFlightLHNotAvailable           = "10"
+	CaseAfterFlightRHRequired               = "11"
+	CaseAfterFlightRHNotAvailable           = "12"
+	CaseAfterFlightMGBRequired              = "13"
+	CaseAfterFlightMGBNotAvailable          = "14"
+	CaseAfterFlightIGBRequired              = "15"
+	CaseAfterFlightIGBNotAvailable          = "16"
+	CaseAfterFlightTGBRequired              = "17"
+	CaseAfterFlightTGBNotAvailable          = "18"
+	CaseAfterFlightInvalidJSON              = "19"
+)
+
+var (
+	ErrAfterFlightInvalidID                = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightInvalidID, CodeAfterFlightInvalidID, "flight_inspection_id is invalid")
+	ErrAfterFlightFlightInspectionNotFound = DefByModule(ModuleAfterFlightInspection, http.StatusNotFound, CaseAfterFlightFlightInspectionNotFound, CodeAfterFlightFlightInspectionNotFound, "flight inspection not found")
+	ErrAfterFlightInspectionNotFound       = DefByModule(ModuleAfterFlightInspection, http.StatusNotFound, CaseAfterFlightInspectionNotFound, CodeAfterFlightInspectionNotFound, "after flight inspection not found")
+	ErrAfterFlightCapabilitiesUnavailable  = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightCapabilitiesUnavailable, CodeAfterFlightCapabilitiesUnavailable, "helicopter capabilities could not be resolved")
+	ErrAfterFlightNR1Required              = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightNR1Required, CodeAfterFlightNR1Required, "oil_engine_nr1_checked is required for this helicopter")
+	ErrAfterFlightNR1NotAvailable          = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightNR1NotAvailable, CodeAfterFlightNR1NotAvailable, "NR1 capability not available on this helicopter")
+	ErrAfterFlightNR2Required              = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightNR2Required, CodeAfterFlightNR2Required, "oil_engine_nr2_checked is required for this helicopter")
+	ErrAfterFlightNR2NotAvailable          = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightNR2NotAvailable, CodeAfterFlightNR2NotAvailable, "NR2 capability not available on this helicopter")
+	ErrAfterFlightLHRequired               = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightLHRequired, CodeAfterFlightLHRequired, "hydraulic_lh_checked is required for this helicopter")
+	ErrAfterFlightLHNotAvailable           = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightLHNotAvailable, CodeAfterFlightLHNotAvailable, "LH capability not available on this helicopter")
+	ErrAfterFlightRHRequired               = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightRHRequired, CodeAfterFlightRHRequired, "hydraulic_rh_checked is required for this helicopter")
+	ErrAfterFlightRHNotAvailable           = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightRHNotAvailable, CodeAfterFlightRHNotAvailable, "RH capability not available on this helicopter")
+	ErrAfterFlightMGBRequired              = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightMGBRequired, CodeAfterFlightMGBRequired, "oil_transmission_mgb_checked is required for this helicopter")
+	ErrAfterFlightMGBNotAvailable          = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightMGBNotAvailable, CodeAfterFlightMGBNotAvailable, "MGB capability not available on this helicopter")
+	ErrAfterFlightIGBRequired              = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightIGBRequired, CodeAfterFlightIGBRequired, "oil_transmission_igb_checked is required for this helicopter")
+	ErrAfterFlightIGBNotAvailable          = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightIGBNotAvailable, CodeAfterFlightIGBNotAvailable, "IGB capability not available on this helicopter")
+	ErrAfterFlightTGBRequired              = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightTGBRequired, CodeAfterFlightTGBRequired, "oil_transmission_tgb_checked is required for this helicopter")
+	ErrAfterFlightTGBNotAvailable          = DefByModule(ModuleAfterFlightInspection, http.StatusUnprocessableEntity, CaseAfterFlightTGBNotAvailable, CodeAfterFlightTGBNotAvailable, "TGB capability not available on this helicopter")
+	ErrAfterFlightInvalidJSON              = DefByModule(ModuleAfterFlightInspection, http.StatusBadRequest, CaseAfterFlightInvalidJSON, CodeAfterFlightInvalidJSON, "invalid json payload")
+)
+
+var Registry = []Def{
+	ErrInvalidRequest,
+	ErrInvalidDataType,
+	ErrDataNotFound,
+	ErrValidation,
+	ErrBusinessRuleFailed,
+	ErrInternal,
+	ErrSessionExpired,
+	ErrTokenInvalid,
+	ErrUserUnauthorized,
+	ErrForbiddenAccess,
+	ErrAuthInvalidJSON,
+	ErrAuthRegistrationDisabled,
+	ErrAuthRoleNotFound,
+	ErrAuthRegistrationFailed,
+	ErrAuthInviteFailed,
+	ErrAuthSetPasswordFailed,
+	ErrAuthSetPasswordTokenInvalid,
+	ErrAuthUsernameAlreadyRegistered,
+	ErrAuthResetPasswordInvalidLink,
+	ErrAuthResetPasswordFailed,
+	ErrPINVerificationRequired202,
+	ErrPINIncorrect,
+	ErrPINBlocked,
+	ErrPINNotSet,
+	ErrPINNotBlocked,
+	ErrPINValidationFailed,
+	ErrPINAttemptLimitReached,
+	ErrHelicopterNotFound,
+	ErrHelicopterDuplicate,
+	ErrHelicopterRelationDelete,
+	ErrHelicopterInvalidPayload,
+	ErrHelicopterInvalidType,
+	ErrHelicopterInvalidJSON,
+	ErrHelicopterInvalidID,
+	ErrHelicopterIDRequired,
+	ErrHelicopterIDMismatch,
+	ErrHelicopterAttributesRequired,
+	ErrHelicopterCreateFailed,
+	ErrHelicopterUpdateFailed,
+	ErrHelicopterDeleteFailed,
+	ErrHelicopterGenerateFailed,
+	ErrHelicopterListFailed,
+	ErrHelicopterPinVerificationRequired,
+	ErrHelicopterUnauthorized,
+	ErrHelicopterFileNotFound,
+	ErrHelicopterFileInvalidPayload,
+	ErrHelicopterFileInvalidJSON,
+	ErrHelicopterFileInvalidUUID,
+	ErrHelicopterFileSectionInvalid,
+	ErrHelicopterFileFileNameRequired,
+	ErrHelicopterFileCreateFailed,
+	ErrHelicopterFileUpdateFailed,
+	ErrHelicopterFileDeleteFailed,
+	ErrHelicopterFileGetFailed,
+	ErrHelicopterFileListFailed,
+	ErrHelicopterUsageNotFound,
+	ErrHelicopterUsageDuplicate,
+	ErrHelicopterUsageRelationDelete,
+	ErrHelicopterUsageInvalidPayload,
+	ErrHelicopterUsageInvalidJSON,
+	ErrHelicopterUsageInvalidUUID,
+	ErrHelicopterUsageIDRequired,
+	ErrHelicopterUsageIDMismatch,
+	ErrHelicopterUsageAttributesRequired,
+	ErrHelicopterUsageCreateFailed,
+	ErrHelicopterUsageGetFailed,
+	ErrHelicopterUsageUpdateFailed,
+	ErrHelicopterUsageDeleteFailed,
+	ErrHelicopterUsageListFailed,
+	ErrUserNotFound,
+	ErrUserInvalidPayload,
+	ErrUserInvalidJSON,
+	ErrUserInvalidUUID,
+	ErrUserValidationFailed,
+	ErrUserCreateFailed,
+	ErrUserUpdateFailed,
+	ErrUserDeleteFailed,
+	ErrUserListFailed,
+	ErrUserTimezoneInvalid,
+	ErrUserRoleIDsInvalid,
+	ErrUserRoleIDsRequired,
+	ErrUserPrimaryRoleInvalid,
+	ErrMasterDataNotFound,
+	ErrMasterDataInvalidPayload,
+	ErrMasterDataInvalidJSON,
+	ErrMasterDataValidationFailed,
+	ErrMasterDataCreateFailed,
+	ErrMasterDataUpdateFailed,
+	ErrMasterDataDeleteFailed,
+	ErrMasterDataListFailed,
+	ErrDutyRosterNotFound,
+	ErrDutyRosterInvalidPayload,
+	ErrDutyRosterInvalidJSON,
+	ErrDutyRosterInvalidUUID,
+	ErrDutyRosterValidationFailed,
+	ErrDutyRosterConflict,
+	ErrDutyRosterCreateFailed,
+	ErrDutyRosterUpdateFailed,
+	ErrDutyRosterDeleteFailed,
+	ErrDutyRosterListFailed,
+	ErrDutyRosterUnauthorized,
+	ErrDutyRosterBaseTypeInvalid,
+	ErrDutyRosterRelationDeleteConflict,
+	ErrFlightNotFound,
+	ErrFlightInvalidPayload,
+	ErrFlightInvalidJSON,
+	ErrFlightInvalidUUID,
+	ErrFlightValidationFailed,
+	ErrFlightCreateFailed,
+	ErrFlightGetFailed,
+	ErrFlightListFailed,
+	ErrFlightUnauthorized,
+	ErrFlightDateInvalid,
+	ErrNoIcaoCodeNotFound,
+	ErrNoIcaoCodeRelationDelete,
+	ErrNoIcaoCodeInvalidPayload,
+	ErrNoIcaoCodeInvalidJSON,
+	ErrNoIcaoCodeInvalidUUID,
+	ErrNoIcaoCodeIDRequired,
+	ErrNoIcaoCodeIDMismatch,
+	ErrNoIcaoCodeAttributesRequired,
+	ErrNoIcaoCodeNameRequired,
+	ErrNoIcaoCodeCreateFailed,
+	ErrNoIcaoCodeUpdateFailed,
+	ErrNoIcaoCodeDeleteFailed,
+	ErrNoIcaoCodeListFailed,
+	ErrBaseNotFound,
+	ErrBaseRelationDelete,
+	ErrBaseInvalidPayload,
+	ErrBaseInvalidJSON,
+	ErrBaseInvalidUUID,
+	ErrBaseInvalidCategory,
+	ErrBaseAttributesRequired,
+	ErrBaseNameRequired,
+	ErrBaseDefaultShiftStartRequired,
+	ErrBaseDefaultShiftEndRequired,
+	ErrBaseCreateFailed,
+	ErrBaseUpdateFailed,
+	ErrBaseDeleteFailed,
+	ErrBaseListFailed,
+	ErrBaseInvalidContactIDs,
+	ErrBaseInvalidTime,
+	ErrFacilityNotFound,
+	ErrFacilityRelationDelete,
+	ErrFacilityInvalidPayload,
+	ErrFacilityInvalidJSON,
+	ErrFacilityInvalidUUID,
+	ErrFacilityAttributesRequired,
+	ErrFacilityCategoryRequired,
+	ErrFacilityNameRequired,
+	ErrFacilityTypeRequired,
+	ErrFacilityCreateFailed,
+	ErrFacilityUpdateFailed,
+	ErrFacilityDeleteFailed,
+	ErrFacilityListFailed,
+	ErrFederalStateNotFound,
+	ErrFederalStateRelationDelete,
+	ErrFederalStateInvalidPayload,
+	ErrFederalStateInvalidJSON,
+	ErrFederalStateInvalidID,
+	ErrFederalStateLandIDInvalid,
+	ErrFederalStateIDRequired,
+	ErrFederalStateIDMismatch,
+	ErrFederalStateAttributesRequired,
+	ErrFederalStateNameRequired,
+	ErrFederalStateCreateFailed,
+	ErrFederalStateUpdateFailed,
+	ErrFederalStateDeleteFailed,
+	ErrFederalStateListFailed,
+	ErrNationalityNotFound,
+	ErrNationalityRelationDelete,
+	ErrNationalityInvalidPayload,
+	ErrNationalityInvalidJSON,
+	ErrNationalityInvalidUUID,
+	ErrNationalityIDRequired,
+	ErrNationalityIDMismatch,
+	ErrNationalityAttributesRequired,
+	ErrNationalityNameRequired,
+	ErrNationalityCreateFailed,
+	ErrNationalityUpdateFailed,
+	ErrNationalityDeleteFailed,
+	ErrNationalityListFailed,
+	ErrCountryNotFound,
+	ErrCountryRelationDelete,
+	ErrCountryInvalidPayload,
+	ErrCountryInvalidJSON,
+	ErrCountryInvalidID,
+	ErrCountryIDRequired,
+	ErrCountryIDMismatch,
+	ErrCountryAttributesRequired,
+	ErrCountryNameRequired,
+	ErrCountryISOCodeInvalid,
+	ErrCountryISOCodeDuplicate,
+	ErrCountryCreateFailed,
+	ErrCountryUpdateFailed,
+	ErrCountryDeleteFailed,
+	ErrCountryListFailed,
+	ErrICAONotFound,
+	ErrICAORelationDelete,
+	ErrICAOInvalidPayload,
+	ErrICAOInvalidJSON,
+	ErrICAOInvalidUUID,
+	ErrICAOIDRequired,
+	ErrICAOIDMismatch,
+	ErrICAOAttributesRequired,
+	ErrICAOCodeRequired,
+	ErrICAOLandIDInvalid,
+	ErrICAOFederalStateInvalid,
+	ErrICAOCreateFailed,
+	ErrICAOUpdateFailed,
+	ErrICAODeleteFailed,
+	ErrICAOListFailed,
+	ErrVocationNotFound,
+	ErrVocationRelationDelete,
+	ErrVocationInvalidPayload,
+	ErrVocationInvalidJSON,
+	ErrVocationInvalidUUID,
+	ErrVocationIDRequired,
+	ErrVocationIDMismatch,
+	ErrVocationAttributesRequired,
+	ErrVocationNameRequired,
+	ErrVocationCreateFailed,
+	ErrVocationUpdateFailed,
+	ErrVocationDeleteFailed,
+	ErrVocationListFailed,
+	ErrHealthInsuranceNotFound,
+	ErrHealthInsuranceRelationDelete,
+	ErrHealthInsuranceInvalidPayload,
+	ErrHealthInsuranceInvalidJSON,
+	ErrHealthInsuranceInvalidUUID,
+	ErrHealthInsuranceIDRequired,
+	ErrHealthInsuranceIDMismatch,
+	ErrHealthInsuranceAttributesRequired,
+	ErrHealthInsuranceNameRequired,
+	ErrHealthInsuranceLandIDInvalid,
+	ErrHealthInsuranceCreateFailed,
+	ErrHealthInsuranceUpdateFailed,
+	ErrHealthInsuranceDeleteFailed,
+	ErrHealthInsuranceListFailed,
+	ErrMedicineNotFound,
+	ErrMedicineRelationDelete,
+	ErrMedicineInvalidPayload,
+	ErrMedicineInvalidJSON,
+	ErrMedicineInvalidUUID,
+	ErrMedicineIDRequired,
+	ErrMedicineIDMismatch,
+	ErrMedicineAttributesRequired,
+	ErrMedicineNameRequired,
+	ErrMedicineGroupIDInvalid,
+	ErrMedicineMotorReactionIDInvalid,
+	ErrMedicineMotorReactionIDsInvalid,
+	ErrMedicineCreateFailed,
+	ErrMedicineUpdateFailed,
+	ErrMedicineDeleteFailed,
+	ErrMedicineListFailed,
+	ErrMasterSettingsNotFound,
+	ErrMasterSettingsInvalidPayload,
+	ErrMasterSettingsInvalidJSON,
+	ErrMasterSettingsInvalidUUID,
+	ErrMasterSettingsIDRequired,
+	ErrMasterSettingsIDMismatch,
+	ErrMasterSettingsAttributesRequired,
+	ErrMasterSettingsCompanyNameRequired,
+	ErrMasterSettingsLogoFileInvalid,
+	ErrMasterSettingsCoverFileInvalid,
+	ErrMasterSettingsCreateFailed,
+	ErrMasterSettingsUpdateFailed,
+	ErrMasterSettingsDeleteFailed,
+	ErrMasterSettingsGetFailed,
+	ErrMasterSettingsMicrosoftUpsert,
+	ErrBrandingLogoFetchFailed,
+	ErrBrandingCoverFetchFailed,
+	ErrBrandingEmailLogoFetchFailed,
+	ErrBrandingContentFetchFailed,
+	ErrBrandingStorageUnavailable,
+	ErrBrandingFileManagerUnavailable,
+	ErrFileManagerStorageUnavailable,
+	ErrFileManagerQueueUnavailable,
+	ErrFileManagerUploadIntentUnavailable,
+	ErrFileManagerAttachmentServiceUnavailable,
+	ErrFileManagerFolderNotFound,
+	ErrFileManagerFileNotFound,
+	ErrFileManagerAttachmentNotFound,
+	ErrFileManagerUploadIntentNotFound,
+	ErrFileManagerStatusConflict,
+	ErrFileManagerUploadIntentConflict,
+	ErrFileManagerValidationFailed,
+	ErrFileManagerActionFailed,
+	ErrFileManagerWOPIServiceUnavailable,
+	ErrFileManagerWOPIInvalidFileID,
+	ErrFileManagerWOPIInvalidToken,
+	ErrFileManagerWOPIInvalidProof,
+	ErrFileManagerWOPIPermissionDenied,
+	ErrFileManagerWOPIFileNotFound,
+	ErrFileManagerWOPILockConflict,
+	ErrFileManagerWOPIStaleTimestamp,
+	ErrFileManagerWOPIValidationFailed,
+	ErrOPCNotFound,
+	ErrOPCRelationDelete,
+	ErrOPCInvalidPayload,
+	ErrOPCInvalidJSON,
+	ErrOPCInvalidUUID,
+	ErrOPCIDRequired,
+	ErrOPCIDMismatch,
+	ErrOPCAttributesRequired,
+	ErrOPCTitleRequired,
+	ErrOPCCreateFailed,
+	ErrOPCUpdateFailed,
+	ErrOPCDeleteFailed,
+	ErrOPCListFailed,
+	ErrInsurancePatientDataNotFound,
+	ErrInsurancePatientDataRelationDelete,
+	ErrInsurancePatientDataInvalidPayload,
+	ErrInsurancePatientDataInvalidJSON,
+	ErrInsurancePatientDataInvalidUUID,
+	ErrInsurancePatientDataIDRequired,
+	ErrInsurancePatientDataIDMismatch,
+	ErrInsurancePatientDataAttributesRequired,
+	ErrInsurancePatientDataHealthInsuranceIDInvalid,
+	ErrInsurancePatientDataFederalStateIDInvalid,
+	ErrInsurancePatientDataCreateFailed,
+	ErrInsurancePatientDataUpdateFailed,
+	ErrInsurancePatientDataDeleteFailed,
+	ErrInsurancePatientDataListFailed,
+	ErrPatientDataNotFound,
+	ErrPatientDataRelationDelete,
+	ErrPatientDataInvalidPayload,
+	ErrPatientDataInvalidJSON,
+	ErrPatientDataInvalidUUID,
+	ErrPatientDataIDRequired,
+	ErrPatientDataIDMismatch,
+	ErrPatientDataAttributesRequired,
+	ErrPatientDataFamilyNameRequired,
+	ErrPatientDataFirstNameRequired,
+	ErrPatientDataBirthDateInvalid,
+	ErrPatientDataGenderInvalid,
+	ErrPatientDataOPCIDInvalid,
+	ErrPatientDataInsurancePatientDataIDInvalid,
+	ErrPatientDataCreateFailed,
+	ErrPatientDataUpdateFailed,
+	ErrPatientDataDeleteFailed,
+	ErrPatientDataListFailed,
+	ErrRoleNotFound,
+	ErrRolePermissionNotFound,
+	ErrRoleRelationDelete,
+	ErrRoleInvalidPayload,
+	ErrRoleInvalidJSON,
+	ErrRoleInvalidUUID,
+	ErrRoleInvalidPermissionUUID,
+	ErrRoleIDRequired,
+	ErrRoleIDMismatch,
+	ErrRoleAttributesRequired,
+	ErrRoleNameRequired,
+	ErrRolePermissionIDRequired,
+	ErrRolePermissionIDsEmpty,
+	ErrRoleCreateFailed,
+	ErrRoleUpdateFailed,
+	ErrRoleDeleteFailed,
+	ErrRoleAssignFailed,
+	ErrRoleRemoveFailed,
+	ErrRoleListFailed,
+	ErrRolePermissionListFailed,
+	ErrRolePermissionUpdateFailed,
+	ErrRolePermissionRequiresPINReq,
+	ErrMissionNotFound,
+	ErrMissionInvalidPayload,
+	ErrMissionInvalidJSON,
+	ErrMissionInvalidFlightUUID,
+	ErrMissionInvalidMissionUUID,
+	ErrMissionFlightIDRequired,
+	ErrMissionMissionIDRequired,
+	ErrMissionTypeInvalid,
+	ErrMissionSubtypeRequired,
+	ErrMissionSubtypeInvalid,
+	ErrMissionSubtypeForbidden,
+	ErrMissionDuplicateFlight,
+	ErrMissionCreateFailed,
+	ErrMissionUpdateFailed,
+	ErrMissionDeleteFailed,
+	ErrMissionGetFailed,
+	ErrMissionListFailed,
+	ErrMissionLockedAfterFlightInspection,
+	ErrMissionFileInvalidJSON,
+	ErrMissionFileValidation,
+	ErrMissionFileInvalidMissionUUID,
+	ErrMissionFileMissionNotFound,
+	ErrMissionFileServiceUnavailable,
+	ErrMissionFileActionFailed,
+	ErrFlightDataNotFound,
+	ErrFlightDataInvalidPayload,
+	ErrFlightDataInvalidJSON,
+	ErrFlightDataInvalidPathUUID,
+	ErrFlightDataMissionIDRequired,
+	ErrFlightDataPilotIDRequired,
+	ErrFlightDataPilotReference,
+	ErrFlightDataInvalidUUID,
+	ErrFlightDataInvalidRFC3339,
+	ErrFlightDataOriginLocationReference,
+	ErrFlightDataDestinationLocationReference,
+	ErrFlightDataFacilityReference,
+	ErrFlightDataRequired,
+	ErrFlightDataCreateFailed,
+	ErrFlightDataGetFailed,
+	ErrFlightDataAfterFlightIncomplete,
+	ErrFlightDataLockedAfterFlightInspection,
+	ErrAirRescuerChecklistNotFound,
+	ErrAirRescuerChecklistItemNotFound,
+	ErrAirRescuerChecklistInvalidPayload,
+	ErrAirRescuerChecklistInvalidJSON,
+	ErrAirRescuerChecklistInvalidUUID,
+	ErrAirRescuerChecklistIDMismatch,
+	ErrAirRescuerChecklistScopeInvalid,
+	ErrAirRescuerChecklistScopeRequired,
+	ErrAirRescuerChecklistTitleRequired,
+	ErrAirRescuerChecklistNameRequired,
+	ErrAirRescuerChecklistBaseNotFound,
+	ErrAirRescuerChecklistCreateFailed,
+	ErrAirRescuerChecklistUpdateFailed,
+	ErrAirRescuerChecklistDeleteFailed,
+	ErrAirRescuerChecklistListFailed,
+	ErrAirRescuerChecklistReorderFailed,
+	ErrAirRescuerChecklistValidationFailed,
+	ErrTakeoverNotFound,
+	ErrTakeoverInvalidPayload,
+	ErrTakeoverInvalidJSON,
+	ErrTakeoverInvalidUUID,
+	ErrTakeoverIDRequired,
+	ErrTakeoverIDMismatch,
+	ErrTakeoverFileSectionInvalid,
+	ErrTakeoverCreateFailed,
+	ErrTakeoverUpdateFailed,
+	ErrTakeoverDeleteFailed,
+	ErrTakeoverGetFailed,
+	ErrTakeoverListFailed,
+	ErrTakeoverHelicopterInUse,
+	ErrTakeoverHelicopterAOG,
+	ErrTakeoverHelicopterMCF,
+	ErrFleetStatusNotFound,
+	ErrFleetStatusInvalidPayload,
+	ErrFleetStatusInvalidJSON,
+	ErrFleetStatusInvalidID,
+	ErrFleetStatusIDRequired,
+	ErrFleetStatusIDMismatch,
+	ErrFleetStatusHelicopterRequired,
+	ErrFleetStatusHelicopterInvalid,
+	ErrFleetStatusDuplicate,
+	ErrFleetStatusRelationDelete,
+	ErrFleetStatusCreateFailed,
+	ErrFleetStatusUpdateFailed,
+	ErrFleetStatusDeleteFailed,
+	ErrFleetStatusListFailed,
+	ErrFleetStatusMarkServicedFailed,
+	ErrFleetStatusFileInvalidJSON,
+	ErrFleetStatusFileInvalidPayload,
+	ErrFleetStatusFileUploadIntentInvalid,
+	ErrFleetStatusFileStorageUnavailable,
+	ErrFleetStatusFileFailed,
+	ErrHEMSOperationNotFound,
+	ErrHEMSOperationInvalidPayload,
+	ErrHEMSOperationInvalidJSON,
+	ErrHEMSOperationInvalidUUID,
+	ErrHEMSOperationAttributesRequired,
+	ErrHEMSOperationDateInvalidRFC3339,
+	ErrHEMSOperationRelationReferenceInvalid,
+	ErrHEMSOperationCreateFailed,
+	ErrHEMSOperationUpdateFailed,
+	ErrHEMSOperationDeleteFailed,
+	ErrHEMSOperationListFailed,
+	ErrForcesPresentNotFound,
+	ErrForcesPresentRelationDelete,
+	ErrForcesPresentInvalidPayload,
+	ErrForcesPresentInvalidJSON,
+	ErrForcesPresentInvalidUUID,
+	ErrForcesPresentIDRequired,
+	ErrForcesPresentIDMismatch,
+	ErrForcesPresentAttributesRequired,
+	ErrForcesPresentNameRequired,
+	ErrForcesPresentCreateFailed,
+	ErrForcesPresentUpdateFailed,
+	ErrForcesPresentDeleteFailed,
+	ErrForcesPresentListFailed,
+	ErrContactNotFound,
+	ErrContactInvalidPayload,
+	ErrContactInvalidJSON,
+	ErrContactInvalidUserID,
+	ErrContactValidationFailed,
+	ErrContactCreateFailed,
+	ErrContactGetFailed,
+	ErrContactUpdateFailed,
+	ErrContactUsernameConflict,
+	ErrContactDeleteFailed,
+	ErrContactUpdateStatusFailed,
+	ErrContactUpdateRoleFailed,
+	ErrContactUpdatePilotCategoryFailed,
+	ErrContactUpdateLicenseFailed,
+	ErrContactUpdateChiefFlagsFailed,
+	ErrContactUpdateResponsibleComplaintsFailed,
+	ErrContactBulkUpdateFailed,
+	ErrContactListFailed,
+	ErrComplaintNotFound,
+	ErrComplaintInvalidPayload,
+	ErrComplaintInvalidJSON,
+	ErrComplaintInvalidUUID,
+	ErrComplaintIDRequired,
+	ErrComplaintIDMismatch,
+	ErrComplaintCreateFailed,
+	ErrComplaintUpdateFailed,
+	ErrComplaintDeleteFailed,
+	ErrComplaintListFailed,
+	ErrComplaintGroupedListFailed,
+	ErrComplaintRelationDelete,
+	ErrComplaintInvalidHelicopterID,
+	ErrComplaintActionSignedLocked,
+	ErrEASAReleaseNotFound,
+	ErrEASAReleaseInvalidJSON,
+	ErrEASAReleaseInvalidUUID,
+	ErrEASAReleaseInvalidPayload,
+	ErrEASAReleaseCreateFailed,
+	ErrEASAReleaseUpdateFailed,
+	ErrEASAReleaseDeleteFailed,
+	ErrEASAReleaseListFailed,
+	ErrEASAReleaseSignFailed,
+	ErrEASAReleaseAlreadySigned,
+	ErrEASAReleaseIncompleteForSign,
+	ErrEASAReleaseSignoffRequired,
+	ErrActionSignoffNotFound,
+	ErrActionSignoffInvalidUUID,
+	ErrActionSignoffInvalidJSON,
+	ErrActionSignoffSignFailed,
+	ErrActionSignoffUnsignFailed,
+	ErrMCFNotFound,
+	ErrMCFInvalidJSON,
+	ErrMCFInvalidUUID,
+	ErrMCFInvalidPayload,
+	ErrMCFCreateFailed,
+	ErrMCFCompleteFailed,
+	ErrMCFNoOpen,
+	ErrMCFListFailed,
+	ErrMCFHelicopterHasOpen,
+	ErrAfterFlightInvalidID,
+	ErrAfterFlightFlightInspectionNotFound,
+	ErrAfterFlightInspectionNotFound,
+	ErrAfterFlightCapabilitiesUnavailable,
+	ErrAfterFlightNR1Required,
+	ErrAfterFlightNR1NotAvailable,
+	ErrAfterFlightNR2Required,
+	ErrAfterFlightNR2NotAvailable,
+	ErrAfterFlightLHRequired,
+	ErrAfterFlightLHNotAvailable,
+	ErrAfterFlightRHRequired,
+	ErrAfterFlightRHNotAvailable,
+	ErrAfterFlightMGBRequired,
+	ErrAfterFlightMGBNotAvailable,
+	ErrAfterFlightIGBRequired,
+	ErrAfterFlightIGBNotAvailable,
+	ErrAfterFlightTGBRequired,
+	ErrAfterFlightTGBNotAvailable,
+	ErrAfterFlightInvalidJSON,
+}
diff --git a/internal/shared/pkg/apperrorsx/enrich.go b/internal/shared/pkg/apperrorsx/enrich.go
new file mode 100644
index 0000000..c87aab2
--- /dev/null
+++ b/internal/shared/pkg/apperrorsx/enrich.go
@@ -0,0 +1,106 @@
+package apperrorsx
+
+import (
+	"strconv"
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/transport/http/jsonapi"
+)
+
+var (
+	registryByCode      map[string]Def
+	registryByErrorCode map[string]Def
+)
+
+func init() {
+	registryByCode = make(map[string]Def, len(Registry))
+	registryByErrorCode = make(map[string]Def, len(Registry))
+	for _, def := range Registry {
+		registryByCode[def.Code] = def
+		registryByErrorCode[def.ErrorCode] = def
+	}
+}
+
+func EnrichErrorObjects(status int, errs []jsonapi.ErrorObject) []jsonapi.ErrorObject {
+	out := make([]jsonapi.ErrorObject, 0, len(errs))
+	for i := range errs {
+		obj := errs[i]
+		obj.Status = strconv.Itoa(status)
+
+		def := inferDef(status, obj)
+		if obj.Code == "" && def.Code != "" {
+			obj.Code = def.Code
+		}
+		if obj.ErrorCode == "" && def.ErrorCode != "" {
+			obj.ErrorCode = def.ErrorCode
+		}
+		if obj.Title == "" && def.Title != "" {
+			obj.Title = def.Title
+		}
+		out = append(out, obj)
+	}
+	return out
+}
+
+func inferDef(status int, obj jsonapi.ErrorObject) Def {
+	if obj.Code != "" {
+		if def, ok := registryByCode[obj.Code]; ok {
+			def.Status = status
+			def.ErrorCode = Build(status, moduleFromErrorCode(def.ErrorCode), caseFromErrorCode(def.ErrorCode), def.Code, def.Message).ErrorCode
+			return def
+		}
+	}
+	if obj.ErrorCode != "" {
+		if def, ok := registryByErrorCode[obj.ErrorCode]; ok {
+			return def
+		}
+	}
+
+	switch status {
+	case fiber.StatusBadRequest:
+		return ErrInvalidRequest
+	case fiber.StatusUnauthorized:
+		return ErrUserUnauthorized
+	case fiber.StatusForbidden:
+		return ErrForbiddenAccess
+	case fiber.StatusNotFound:
+		return ErrDataNotFound
+	case fiber.StatusConflict:
+		return ErrBusinessRuleFailed
+	case fiber.StatusUnprocessableEntity:
+		return ErrValidation
+	case fiber.StatusTooManyRequests:
+		return ErrPINAttemptLimitReached
+	default:
+		msg := strings.ToLower(strings.TrimSpace(obj.Detail))
+		if strings.Contains(msg, "not found") {
+			return ErrDataNotFound
+		}
+		if strings.Contains(msg, "unauthorized") {
+			return ErrUserUnauthorized
+		}
+		if strings.Contains(msg, "forbidden") {
+			return ErrForbiddenAccess
+		}
+		if strings.Contains(msg, "validation") || strings.Contains(msg, "invalid") {
+			return ErrValidation
+		}
+		return ErrInternal
+	}
+}
+
+func moduleFromErrorCode(errorCode string) string {
+	if len(errorCode) >= 5 {
+		return errorCode[3:5]
+	}
+	return ModuleGeneral
+}
+
+func caseFromErrorCode(errorCode string) string {
+	if len(errorCode) >= 7 {
+		return errorCode[5:7]
+	}
+	return CaseGeneralInternalError
+}
diff --git a/internal/shared/pkg/apperrorsx/mysql_map.go b/internal/shared/pkg/apperrorsx/mysql_map.go
new file mode 100644
index 0000000..6019936
--- /dev/null
+++ b/internal/shared/pkg/apperrorsx/mysql_map.go
@@ -0,0 +1,141 @@
+package apperrorsx
+
+import (
+	"errors"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+)
+
+const (
+	mysqlErrAccessDenied            uint16 = 1045
+	mysqlErrDuplicateEntry          uint16 = 1062
+	mysqlErrCommandDenied           uint16 = 1142
+	mysqlErrLockWaitTimeout         uint16 = 1205
+	mysqlErrDeadlockFound           uint16 = 1213
+	mysqlErrSpecificAccessDenied    uint16 = 1227
+	mysqlErrColumnCannotBeNull      uint16 = 1048
+	mysqlErrTruncatedWrongValue     uint16 = 1292
+	mysqlErrIncorrectValue          uint16 = 1366
+	mysqlErrServerGone              uint16 = 2006
+	mysqlErrFkParentStillReferenced uint16 = 1451
+	mysqlErrFkChildNotFound         uint16 = 1452
+	mysqlErrCheckConstraintViolated uint16 = 3819
+	mysqlErrConstraintFailed        uint16 = 4025
+)
+
+func mapMySQLError(module string, err error) *AppError {
+	var mysqlErr *mysqldriver.MySQLError
+	if !errors.As(err, &mysqlErr) {
+		return nil
+	}
+
+	switch module {
+	case ModuleHelicopter:
+		return mapMySQLErrorHelicopter(mysqlErr, err)
+	case ModuleHospital:
+		return mapMySQLErrorHospital(mysqlErr, err)
+	case ModuleFleetStatus:
+		return mapMySQLErrorFleetStatus(mysqlErr, err)
+	case ModuleComplaint:
+		return mapMySQLErrorComplaint(mysqlErr, err)
+	default:
+		return mapMySQLErrorGeneral(mysqlErr, err)
+	}
+}
+
+func mapMySQLErrorFleetStatus(mysqlErr *mysqldriver.MySQLError, cause error) *AppError {
+	switch mysqlErr.Number {
+	case mysqlErrDuplicateEntry:
+		return New(ErrFleetStatusDuplicate).WithCause(cause)
+	case mysqlErrFkParentStillReferenced:
+		return New(ErrFleetStatusRelationDelete).WithCause(cause)
+	case mysqlErrFkChildNotFound:
+		// fleet_status.helicopter_id references a non-existent helicopter.
+		return New(ErrFleetStatusHelicopterInvalid).WithCause(cause)
+	case mysqlErrColumnCannotBeNull,
+		mysqlErrTruncatedWrongValue,
+		mysqlErrIncorrectValue,
+		mysqlErrCheckConstraintViolated,
+		mysqlErrConstraintFailed:
+		return New(ErrFleetStatusInvalidPayload).WithCause(cause)
+	default:
+		return nil
+	}
+}
+
+func mapMySQLErrorGeneral(mysqlErr *mysqldriver.MySQLError, cause error) *AppError {
+	switch mysqlErr.Number {
+	case mysqlErrAccessDenied:
+		return New(ErrUserUnauthorized).WithCause(cause)
+	case mysqlErrCommandDenied, mysqlErrSpecificAccessDenied:
+		return New(ErrForbiddenAccess).WithCause(cause)
+	case mysqlErrLockWaitTimeout, mysqlErrDeadlockFound:
+		return New(ErrBusinessRuleFailed).WithCause(cause)
+	case mysqlErrServerGone:
+		return New(ErrInternal).WithCause(cause)
+	case mysqlErrDuplicateEntry, mysqlErrFkParentStillReferenced:
+		return New(ErrBusinessRuleFailed).WithCause(cause)
+	case mysqlErrColumnCannotBeNull,
+		mysqlErrTruncatedWrongValue,
+		mysqlErrIncorrectValue,
+		mysqlErrFkChildNotFound,
+		mysqlErrCheckConstraintViolated,
+		mysqlErrConstraintFailed:
+		return New(ErrValidation).WithCause(cause)
+	default:
+		return nil
+	}
+}
+
+func mapMySQLErrorHelicopter(mysqlErr *mysqldriver.MySQLError, cause error) *AppError {
+	switch mysqlErr.Number {
+	case mysqlErrDuplicateEntry:
+		return New(ErrHelicopterDuplicate).WithCause(cause)
+	case mysqlErrFkParentStillReferenced:
+		return New(ErrHelicopterRelationDelete).WithCause(cause)
+	case mysqlErrColumnCannotBeNull,
+		mysqlErrTruncatedWrongValue,
+		mysqlErrIncorrectValue,
+		mysqlErrFkChildNotFound,
+		mysqlErrCheckConstraintViolated,
+		mysqlErrConstraintFailed:
+		return New(ErrHelicopterInvalidPayload).WithCause(cause)
+	default:
+		return nil
+	}
+}
+
+func mapMySQLErrorHospital(mysqlErr *mysqldriver.MySQLError, cause error) *AppError {
+	switch mysqlErr.Number {
+	case mysqlErrFkParentStillReferenced:
+		return New(ErrHospitalRelationDelete).WithCause(cause)
+	case mysqlErrColumnCannotBeNull,
+		mysqlErrTruncatedWrongValue,
+		mysqlErrIncorrectValue,
+		mysqlErrFkChildNotFound,
+		mysqlErrCheckConstraintViolated,
+		mysqlErrConstraintFailed:
+		return New(ErrHospitalInvalidPayload).WithCause(cause)
+	default:
+		return nil
+	}
+}
+
+func mapMySQLErrorComplaint(mysqlErr *mysqldriver.MySQLError, cause error) *AppError {
+	switch mysqlErr.Number {
+	case mysqlErrDuplicateEntry:
+		return New(ErrComplaintInvalidPayload).WithCause(cause)
+	case mysqlErrFkParentStillReferenced:
+		return New(ErrComplaintRelationDelete).WithCause(cause)
+	case mysqlErrFkChildNotFound:
+		return New(ErrComplaintInvalidHelicopterID).WithCause(cause)
+	case mysqlErrColumnCannotBeNull,
+		mysqlErrTruncatedWrongValue,
+		mysqlErrIncorrectValue,
+		mysqlErrCheckConstraintViolated,
+		mysqlErrConstraintFailed:
+		return New(ErrComplaintInvalidPayload).WithCause(cause)
+	default:
+		return nil
+	}
+}
diff --git a/internal/shared/pkg/apperrorsx/registry_test.go b/internal/shared/pkg/apperrorsx/registry_test.go
new file mode 100644
index 0000000..46b4c6d
--- /dev/null
+++ b/internal/shared/pkg/apperrorsx/registry_test.go
@@ -0,0 +1,33 @@
+package apperrorsx
+
+import "testing"
+
+func TestRegistry_UniqueCodeAndErrorCode(t *testing.T) {
+	seenCode := map[string]struct{}{}
+	seenErrorCode := map[string]struct{}{}
+	seenModuleCase := map[string]struct{}{}
+	for _, d := range Registry {
+		if d.Code == "" {
+			t.Fatalf("empty code in registry: %#v", d)
+		}
+		if d.ErrorCode == "" {
+			t.Fatalf("empty error_code in registry: %#v", d)
+		}
+		if _, ok := seenCode[d.Code]; ok {
+			t.Fatalf("duplicate code: %s", d.Code)
+		}
+		if _, ok := seenErrorCode[d.ErrorCode]; ok {
+			t.Fatalf("duplicate error_code: %s", d.ErrorCode)
+		}
+		if len(d.ErrorCode) != 7 {
+			t.Fatalf("invalid error_code length for %s: %s", d.Code, d.ErrorCode)
+		}
+		moduleCase := d.ErrorCode[3:]
+		if _, ok := seenModuleCase[moduleCase]; ok {
+			t.Fatalf("duplicate module+case detected: %s (error_code=%s)", moduleCase, d.ErrorCode)
+		}
+		seenCode[d.Code] = struct{}{}
+		seenErrorCode[d.ErrorCode] = struct{}{}
+		seenModuleCase[moduleCase] = struct{}{}
+	}
+}
diff --git a/internal/shared/pkg/apperrorsx/response.go b/internal/shared/pkg/apperrorsx/response.go
new file mode 100644
index 0000000..3ed8da6
--- /dev/null
+++ b/internal/shared/pkg/apperrorsx/response.go
@@ -0,0 +1,68 @@
+package apperrorsx
+
+import (
+	"strconv"
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/transport/http/jsonapi"
+)
+
+func Write(c *fiber.Ctx, e *AppError) error {
+	if e == nil {
+		e = New(ErrInternal)
+	}
+	if e.Status == 0 {
+		e.Status = fiber.StatusInternalServerError
+	}
+	if e.Title == "" {
+		e.Title = defaultTitle(e.Status)
+	}
+	if detail := publicLogDetail(e.Message, e.Cause, e.Title); detail != "" {
+		c.Locals(ContextKeyHTTPErrorDetail, detail)
+	}
+
+	obj := jsonapi.ErrorObject{
+		Status:    strconv.Itoa(e.Status),
+		Code:      e.Code,
+		ErrorCode: e.ErrorCode,
+		Title:     e.Title,
+		Detail:    PublicDetail(e.Status),
+		Source:    e.Source,
+	}
+	return jsonapi.WriteErrors(c, e.Status, []jsonapi.ErrorObject{obj})
+}
+
+func publicLogDetail(message string, cause error, fallback string) string {
+	if cause != nil {
+		if trimmed := strings.TrimSpace(cause.Error()); trimmed != "" {
+			return trimmed
+		}
+	}
+	if trimmed := strings.TrimSpace(message); trimmed != "" {
+		return trimmed
+	}
+	return strings.TrimSpace(fallback)
+}
+
+func defaultTitle(status int) string {
+	switch status {
+	case fiber.StatusBadRequest:
+		return "Bad Request"
+	case fiber.StatusUnauthorized:
+		return "Unauthorized"
+	case fiber.StatusForbidden:
+		return "Forbidden"
+	case fiber.StatusNotFound:
+		return "Not found"
+	case fiber.StatusConflict:
+		return "Conflict"
+	case fiber.StatusUnprocessableEntity:
+		return "Validation error"
+	case fiber.StatusTooManyRequests:
+		return "Too many requests"
+	default:
+		return "Internal server error"
+	}
+}
diff --git a/internal/shared/pkg/apperrorsx/response_test.go b/internal/shared/pkg/apperrorsx/response_test.go
new file mode 100644
index 0000000..683875c
--- /dev/null
+++ b/internal/shared/pkg/apperrorsx/response_test.go
@@ -0,0 +1,54 @@
+package apperrorsx
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"testing"
+
+	"github.com/gofiber/fiber/v2"
+)
+
+func TestPublicDetail(t *testing.T) {
+	tests := []struct {
+		status int
+		want   string
+	}{
+		{http.StatusBadRequest, "invalid request"},
+		{http.StatusUnauthorized, "unauthorized"},
+		{http.StatusForbidden, "forbidden"},
+		{http.StatusNotFound, "not found"},
+		{http.StatusConflict, "conflict"},
+		{http.StatusUnprocessableEntity, "validation failed"},
+		{http.StatusTooManyRequests, "too many requests"},
+		{http.StatusInternalServerError, "an internal error occurred"},
+	}
+
+	for _, tc := range tests {
+		if got := PublicDetail(tc.status); got != tc.want {
+			t.Fatalf("status %d: expected %q, got %q", tc.status, tc.want, got)
+		}
+	}
+}
+
+func TestWriteSanitizesDetail(t *testing.T) {
+	app := fiber.New()
+	app.Get("/", func(c *fiber.Ctx) error {
+		err := New(ErrInternal)
+		err.Message = "raw database message"
+		return Write(c, err)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if bytes.Contains(body, []byte("raw database message")) {
+		t.Fatalf("expected sanitized detail, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"detail":"an internal error occurred"`)) {
+		t.Fatalf("expected generic detail, got %s", string(body))
+	}
+}
diff --git a/internal/shared/pkg/apperrorsx/translator.go b/internal/shared/pkg/apperrorsx/translator.go
new file mode 100644
index 0000000..81ce38c
--- /dev/null
+++ b/internal/shared/pkg/apperrorsx/translator.go
@@ -0,0 +1,221 @@
+package apperrorsx
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/apperrors"
+)
+
+// Translate is the single entrypoint for mapping domain/service errors to AppError.
+func Translate(module string, err error) *AppError {
+	if err == nil {
+		return nil
+	}
+
+	switch module {
+	case ModuleAuth, ModulePIN:
+		if mapped := mapAuthPIN(err); mapped != nil {
+			return mapped
+		}
+	case ModuleHelicopter:
+		if mapped := mapHelicopter(err); mapped != nil {
+			return mapped
+		}
+	case ModuleHospital:
+		if mapped := mapHospital(err); mapped != nil {
+			return mapped
+		}
+	case ModuleTakeover:
+		if mapped := mapTakeover(err); mapped != nil {
+			return mapped
+		}
+	case ModuleFleetStatus:
+		if mapped := mapFleetStatus(err); mapped != nil {
+			return mapped
+		}
+	case ModuleComplaint:
+		if mapped := mapComplaint(err); mapped != nil {
+			return mapped
+		}
+	case ModuleAfterFlightInspection:
+		if mapped := mapAfterFlightInspection(err); mapped != nil {
+			return mapped
+		}
+	}
+
+	return mapGeneral(err)
+}
+
+func mapAfterFlightInspection(err error) *AppError {
+	switch {
+	case errors.Is(err, afterflightinspection.ErrInvalidFlightInspectionID):
+		return New(ErrAfterFlightInvalidID).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrFlightInspectionNotFound):
+		return New(ErrAfterFlightFlightInspectionNotFound).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrCapabilitiesUnavailable):
+		return New(ErrAfterFlightCapabilitiesUnavailable).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrNR1Required):
+		return New(ErrAfterFlightNR1Required).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrNR1NotAvailable):
+		return New(ErrAfterFlightNR1NotAvailable).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrNR2Required):
+		return New(ErrAfterFlightNR2Required).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrNR2NotAvailable):
+		return New(ErrAfterFlightNR2NotAvailable).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrLHRequired):
+		return New(ErrAfterFlightLHRequired).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrLHNotAvailable):
+		return New(ErrAfterFlightLHNotAvailable).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrRHRequired):
+		return New(ErrAfterFlightRHRequired).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrRHNotAvailable):
+		return New(ErrAfterFlightRHNotAvailable).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrMGBRequired):
+		return New(ErrAfterFlightMGBRequired).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrMGBNotAvailable):
+		return New(ErrAfterFlightMGBNotAvailable).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrIGBRequired):
+		return New(ErrAfterFlightIGBRequired).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrIGBNotAvailable):
+		return New(ErrAfterFlightIGBNotAvailable).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrTGBRequired):
+		return New(ErrAfterFlightTGBRequired).WithCause(err)
+	case errors.Is(err, afterflightinspection.ErrTGBNotAvailable):
+		return New(ErrAfterFlightTGBNotAvailable).WithCause(err)
+	}
+
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return New(ErrAfterFlightInspectionNotFound).WithCause(err)
+	}
+
+	if mapped := mapMySQLError(ModuleAfterFlightInspection, err); mapped != nil {
+		return mapped
+	}
+
+	return nil
+}
+
+func mapFleetStatus(err error) *AppError {
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return New(ErrFleetStatusNotFound).WithCause(err)
+	}
+
+	if _, ok := apperrors.AsDeleteConflict(err); ok {
+		return New(ErrFleetStatusRelationDelete).WithCause(err)
+	}
+
+	if mapped := mapMySQLError(ModuleFleetStatus, err); mapped != nil {
+		return mapped
+	}
+
+	return nil
+}
+
+func mapComplaint(err error) *AppError {
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return New(ErrComplaintNotFound).WithCause(err)
+	}
+
+	if mapped := mapMySQLError(ModuleComplaint, err); mapped != nil {
+		return mapped
+	}
+
+	return nil
+}
+
+func mapGeneral(err error) *AppError {
+	switch {
+	case errors.Is(err, gorm.ErrRecordNotFound):
+		return New(ErrDataNotFound).WithCause(err)
+	case errors.Is(err, context.Canceled), errors.Is(err, context.DeadlineExceeded):
+		return New(ErrInvalidRequest).WithCause(err)
+	}
+
+	if mapped := mapMySQLError(ModuleGeneral, err); mapped != nil {
+		return mapped
+	}
+
+	switch {
+	case errors.Is(err, service.ErrInvalidReauthMethod):
+		return New(ErrValidation).WithCause(err)
+	default:
+		return New(ErrInternal).WithCause(err)
+	}
+}
+
+func mapAuthPIN(err error) *AppError {
+	switch {
+	case errors.Is(err, service.ErrInvalidToken):
+		return New(ErrTokenInvalid).WithCause(err)
+	case errors.Is(err, service.ErrInvalidCredentials):
+		return New(ErrUserUnauthorized).WithCause(err)
+	case errors.Is(err, service.ErrSecurityPINNotSet):
+		return New(ErrPINNotSet).WithCause(err)
+	case errors.Is(err, service.ErrSecurityPINLocked), errors.Is(err, service.ErrSecurityPINResetRequired):
+		return New(ErrPINBlocked).WithCause(err)
+	case errors.Is(err, service.ErrSecurityPINAttemptLimit):
+		return New(ErrPINBlocked).WithCause(err)
+	case errors.Is(err, service.ErrInvalidSecurityPIN):
+		return New(ErrPINIncorrect).WithCause(err)
+	case errors.Is(err, service.ErrInvalidPINAction):
+		return New(ErrPINVerificationRequired202).WithCause(err)
+	case errors.Is(err, service.ErrInvalidReauthMethod):
+		return New(ErrValidation).WithCause(err)
+	default:
+		return nil
+	}
+}
+
+func mapHelicopter(err error) *AppError {
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return New(ErrHelicopterNotFound).WithCause(err)
+	}
+
+	if _, ok := apperrors.AsDeleteConflict(err); ok {
+		return New(ErrHelicopterRelationDelete).WithCause(err)
+	}
+
+	if mapped := mapMySQLError(ModuleHelicopter, err); mapped != nil {
+		return mapped
+	}
+
+	switch {
+	case errors.Is(err, service.ErrInvalidReauthMethod):
+		return New(ErrHelicopterInvalidPayload).WithCause(err)
+	default:
+		return nil
+	}
+}
+
+func mapHospital(err error) *AppError {
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return New(ErrHospitalNotFound).WithCause(err)
+	}
+
+	if _, ok := apperrors.AsDeleteConflict(err); ok {
+		return New(ErrHospitalRelationDelete).WithCause(err)
+	}
+
+	if mapped := mapMySQLError(ModuleHospital, err); mapped != nil {
+		return mapped
+	}
+
+	return nil
+}
+
+func mapTakeover(err error) *AppError {
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return New(ErrTakeoverNotFound).WithCause(err)
+	}
+
+	if mapped := mapMySQLError(ModuleTakeover, err); mapped != nil {
+		return mapped
+	}
+
+	return nil
+}
diff --git a/internal/shared/pkg/apperrorsx/translator_test.go b/internal/shared/pkg/apperrorsx/translator_test.go
new file mode 100644
index 0000000..ad83057
--- /dev/null
+++ b/internal/shared/pkg/apperrorsx/translator_test.go
@@ -0,0 +1,40 @@
+package apperrorsx
+
+import (
+	"errors"
+	"testing"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+	"gorm.io/gorm"
+
+	"wucher/internal/service"
+)
+
+func TestTranslate_AuthPIN(t *testing.T) {
+	got := Translate(ModulePIN, service.ErrInvalidSecurityPIN)
+	if got == nil || got.Code != CodePINIncorrect {
+		t.Fatalf("expected %s, got %#v", CodePINIncorrect, got)
+	}
+
+	got = Translate(ModuleAuth, service.ErrInvalidToken)
+	if got == nil || got.Code != CodeTokenInvalid {
+		t.Fatalf("expected %s, got %#v", CodeTokenInvalid, got)
+	}
+}
+
+func TestTranslate_HelicopterAndFallback(t *testing.T) {
+	got := Translate(ModuleHelicopter, gorm.ErrRecordNotFound)
+	if got == nil || got.Code != CodeHelicopterNotFound {
+		t.Fatalf("expected %s, got %#v", CodeHelicopterNotFound, got)
+	}
+
+	got = Translate(ModuleHelicopter, &mysqldriver.MySQLError{Number: 1062, Message: "duplicate"})
+	if got == nil || got.Code != CodeHelicopterDuplicate {
+		t.Fatalf("expected %s, got %#v", CodeHelicopterDuplicate, got)
+	}
+
+	got = Translate("99", errors.New("unknown issue"))
+	if got == nil || got.Code != CodeInternalServerError {
+		t.Fatalf("expected %s, got %#v", CodeInternalServerError, got)
+	}
+}
diff --git a/internal/shared/pkg/attachmentresolver/resolver.go b/internal/shared/pkg/attachmentresolver/resolver.go
new file mode 100644
index 0000000..3859b7e
--- /dev/null
+++ b/internal/shared/pkg/attachmentresolver/resolver.go
@@ -0,0 +1,251 @@
+package attachmentresolver
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type ErrorCode string
+
+const (
+	ErrorInvalidAttachmentUUID     ErrorCode = "invalid_attachment_uuid"
+	ErrorInvalidFileUUID           ErrorCode = "invalid_file_uuid"
+	ErrorAttachmentNotFound        ErrorCode = "attachment_not_found"
+	ErrorRequireValue              ErrorCode = "require_value"
+	ErrorFileManagerUnavailable    ErrorCode = "file_manager_unavailable"
+	ErrorFileNotReadyForAttachment ErrorCode = "file_not_ready_for_attachment"
+	ErrorCannotResolveFromFile     ErrorCode = "cannot_resolve_from_file"
+)
+
+const (
+	notReadyRetryAttempts = 2
+	notReadyRetryDelay    = 150 * time.Millisecond
+)
+
+type ResolveError struct {
+	Code ErrorCode
+
+	AttachmentField string
+	FileField       string
+
+	Cause error
+}
+
+func (e *ResolveError) Error() string {
+	if e == nil {
+		return ""
+	}
+	switch e.Code {
+	case ErrorInvalidAttachmentUUID:
+		return fmt.Sprintf("%s is invalid UUID", fallbackField(e.AttachmentField, "attachment_id"))
+	case ErrorInvalidFileUUID:
+		return fmt.Sprintf("%s is invalid UUID", fallbackField(e.FileField, "file_id"))
+	case ErrorAttachmentNotFound:
+		return fmt.Sprintf("%s not found", fallbackField(e.AttachmentField, "attachment_id"))
+	case ErrorRequireValue:
+		return fmt.Sprintf(
+			"%s or %s is required",
+			fallbackField(e.AttachmentField, "attachment_id"),
+			fallbackField(e.FileField, "file_id"),
+		)
+	case ErrorFileManagerUnavailable:
+		return "file manager service is not configured"
+	case ErrorFileNotReadyForAttachment:
+		return "file is not ready for attachment"
+	case ErrorCannotResolveFromFile:
+		return fmt.Sprintf("cannot resolve attachment from %s", fallbackField(e.FileField, "file_id"))
+	default:
+		if e.Cause != nil {
+			return e.Cause.Error()
+		}
+		return "attachment resolve failed"
+	}
+}
+
+func (e *ResolveError) Unwrap() error { return e.Cause }
+
+type Params struct {
+	FileManager filemanager.Service
+
+	RawAttachmentID *string
+	RawFileID       *string
+
+	AttachmentField string
+	FileField       string
+
+	RequireValue bool
+
+	RefType  string
+	RefID    string
+	Category *string
+
+	IsPrimary bool
+	ActorID   []byte
+
+	ValidateAttachmentExists bool
+	AttachmentExists         func(ctx context.Context, attachmentID []byte) (bool, error)
+}
+
+func Resolve(ctx context.Context, p Params) ([]byte, error) {
+	if p.RawAttachmentID != nil && strings.TrimSpace(*p.RawAttachmentID) != "" {
+		attachmentID, parseErr := uuidv7.ParseString(strings.TrimSpace(*p.RawAttachmentID))
+		if parseErr != nil {
+			return nil, &ResolveError{
+				Code:            ErrorInvalidAttachmentUUID,
+				AttachmentField: p.AttachmentField,
+				FileField:       p.FileField,
+				Cause:           parseErr,
+			}
+		}
+
+		if p.ValidateAttachmentExists {
+			exists, existsErr := resolveAttachmentExists(ctx, p, attachmentID)
+			if existsErr != nil {
+				return nil, existsErr
+			}
+			if !exists {
+				return nil, &ResolveError{
+					Code:            ErrorAttachmentNotFound,
+					AttachmentField: p.AttachmentField,
+					FileField:       p.FileField,
+				}
+			}
+		}
+		return attachmentID, nil
+	}
+
+	if p.RawFileID != nil && strings.TrimSpace(*p.RawFileID) != "" {
+		if p.FileManager == nil {
+			return nil, &ResolveError{
+				Code:            ErrorFileManagerUnavailable,
+				AttachmentField: p.AttachmentField,
+				FileField:       p.FileField,
+			}
+		}
+
+		fileID, parseErr := uuidv7.ParseString(strings.TrimSpace(*p.RawFileID))
+		if parseErr != nil {
+			return nil, &ResolveError{
+				Code:            ErrorInvalidFileUUID,
+				AttachmentField: p.AttachmentField,
+				FileField:       p.FileField,
+				Cause:           parseErr,
+			}
+		}
+
+		created, createErr := p.FileManager.CreateAttachment(ctx, filemanager.CreateAttachmentParams{
+			FileID:    fileID,
+			RefType:   p.RefType,
+			RefID:     p.RefID,
+			Category:  p.Category,
+			SortOrder: 0,
+			IsPrimary: p.IsPrimary,
+			ActorID:   p.ActorID,
+		})
+		if createErr == nil && created != nil && len(created.ID) == 16 {
+			return created.ID, nil
+		}
+		if createErr != nil &&
+			!errors.Is(createErr, filemanager.ErrAttachmentAlreadyExists) &&
+			!errors.Is(createErr, filemanager.ErrFileNotReadyForAttachment) {
+			return nil, createErr
+		}
+		if failed, failureErr := fileIsFailed(ctx, p.FileManager, fileID); failureErr != nil {
+			return nil, failureErr
+		} else if failed {
+			return nil, &ResolveError{
+				Code:            ErrorCannotResolveFromFile,
+				AttachmentField: p.AttachmentField,
+				FileField:       p.FileField,
+			}
+		}
+		if errors.Is(createErr, filemanager.ErrFileNotReadyForAttachment) {
+			return nil, &ResolveError{
+				Code:            ErrorFileNotReadyForAttachment,
+				AttachmentField: p.AttachmentField,
+				FileField:       p.FileField,
+			}
+		}
+
+		rows, _, listErr := p.FileManager.ListAttachmentsByReference(ctx, filemanager.ListAttachmentsParams{
+			RefType: p.RefType,
+			RefID:   p.RefID,
+			Limit:   100,
+			Offset:  0,
+		})
+		if listErr != nil {
+			return nil, listErr
+		}
+		for i := range rows {
+			if string(rows[i].FileID) == string(fileID) {
+				return rows[i].ID, nil
+			}
+		}
+		return nil, &ResolveError{
+			Code:            ErrorCannotResolveFromFile,
+			AttachmentField: p.AttachmentField,
+			FileField:       p.FileField,
+		}
+	}
+
+	if p.RequireValue {
+		return nil, &ResolveError{
+			Code:            ErrorRequireValue,
+			AttachmentField: p.AttachmentField,
+			FileField:       p.FileField,
+		}
+	}
+	return nil, nil
+}
+
+func resolveAttachmentExists(ctx context.Context, p Params, attachmentID []byte) (bool, error) {
+	if p.AttachmentExists != nil {
+		return p.AttachmentExists(ctx, attachmentID)
+	}
+	if p.FileManager != nil {
+		row, err := p.FileManager.GetAttachmentByID(ctx, attachmentID)
+		if err != nil {
+			return false, err
+		}
+		return row != nil, nil
+	}
+	return true, nil
+}
+
+func fileIsFailed(ctx context.Context, fm filemanager.Service, fileID []byte) (bool, error) {
+	if fm == nil || len(fileID) == 0 {
+		return false, nil
+	}
+	file, err := fm.GetFileByID(ctx, fileID)
+	if err != nil {
+		return false, err
+	}
+	if file == nil {
+		return false, nil
+	}
+	return filemanager.NormalizeFileStatus(file.Status) == filemanager.FileStatusFailed, nil
+}
+
+func fallbackField(v string, fallback string) string {
+	if strings.TrimSpace(v) == "" {
+		return fallback
+	}
+	return strings.TrimSpace(v)
+}
+
+func sleepWithContext(ctx context.Context, d time.Duration) error {
+	timer := time.NewTimer(d)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
diff --git a/internal/shared/pkg/logger/logger.go b/internal/shared/pkg/logger/logger.go
new file mode 100644
index 0000000..09bf1f6
--- /dev/null
+++ b/internal/shared/pkg/logger/logger.go
@@ -0,0 +1,41 @@
+package logger
+
+import (
+	"io"
+	"log/slog"
+	"os"
+	"strings"
+
+	"wucher/internal/config"
+)
+
+func New(cfg config.LoggingConfig) *slog.Logger {
+	level := parseLevel(cfg.Level)
+	options := &slog.HandlerOptions{Level: level}
+
+	var handler slog.Handler
+	switch strings.ToLower(strings.TrimSpace(cfg.Format)) {
+	case "text":
+		handler = slog.NewTextHandler(os.Stdout, options)
+	default:
+		handler = slog.NewJSONHandler(os.Stdout, options)
+	}
+	return slog.New(handler)
+}
+
+func NewDiscard() *slog.Logger {
+	return slog.New(slog.NewJSONHandler(io.Discard, nil))
+}
+
+func parseLevel(raw string) slog.Leveler {
+	switch strings.ToLower(strings.TrimSpace(raw)) {
+	case "debug":
+		return slog.LevelDebug
+	case "warn", "warning":
+		return slog.LevelWarn
+	case "error":
+		return slog.LevelError
+	default:
+		return slog.LevelInfo
+	}
+}
diff --git a/internal/shared/pkg/metricparse/metricparse.go b/internal/shared/pkg/metricparse/metricparse.go
new file mode 100644
index 0000000..0402b0b
--- /dev/null
+++ b/internal/shared/pkg/metricparse/metricparse.go
@@ -0,0 +1,74 @@
+// Package metricparse extracts a numeric value from the free-text engine/metric strings
+// used across FM reports (e.g. "GPC/N1 63.2"). The same parser MUST be used both when
+// aggregating totals and when deriving a single report's "today" contribution, otherwise
+// prev = total - today would not reconcile.
+package metricparse
+
+import (
+	"regexp"
+	"strconv"
+	"strings"
+	"unicode"
+)
+
+// numberToken matches a signed decimal number (integer or fractional).
+var numberToken = regexp.MustCompile(`[-+]?\d*\.?\d+`)
+
+// Parse returns ParseString(*v), or 0 when v is nil.
+func Parse(v *string) float64 {
+	if v == nil {
+		return 0
+	}
+	return ParseString(*v)
+}
+
+// ParseString pulls the numeric VALUE out of a metric label string:
+//
+//	"GPC/N1 63.2" -> 63.2   "PTC/N2 61.8" -> 61.8   "63.2" -> 63.2
+//	"63,2" -> 63.2          "  -5 "       -> -5      "N1" -> 0 (label only)
+//
+// It ignores digits fused to a label letter (the "1" in "N1", the "2" in "N2") by skipping
+// any number immediately preceded by a letter, and prefers a token that carries a decimal
+// point when several stand-alone numbers are present.
+func ParseString(s string) float64 {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return 0
+	}
+	// Normalize a decimal comma ("63,2") to a dot when it is the sole separator.
+	if !strings.Contains(s, ".") {
+		if i := strings.IndexByte(s, ','); i > 0 && i+1 < len(s) &&
+			isASCIIDigit(s[i-1]) && isASCIIDigit(s[i+1]) {
+			s = s[:i] + "." + s[i+1:]
+		}
+	}
+
+	locs := numberToken.FindAllStringIndex(s, -1)
+	candidates := make([]string, 0, len(locs))
+	for _, loc := range locs {
+		// A value is never glued to a preceding letter; that only happens for labels
+		// like N1/N2. Real values start the string or follow a space/slash/colon/etc.
+		if loc[0] > 0 && unicode.IsLetter(rune(s[loc[0]-1])) {
+			continue
+		}
+		candidates = append(candidates, s[loc[0]:loc[1]])
+	}
+	if len(candidates) == 0 {
+		return 0
+	}
+
+	chosen := candidates[0]
+	for _, c := range candidates {
+		if strings.Contains(c, ".") {
+			chosen = c
+			break
+		}
+	}
+	n, err := strconv.ParseFloat(chosen, 64)
+	if err != nil {
+		return 0
+	}
+	return n
+}
+
+func isASCIIDigit(b byte) bool { return b >= '0' && b <= '9' }
diff --git a/internal/shared/pkg/metricparse/metricparse_test.go b/internal/shared/pkg/metricparse/metricparse_test.go
new file mode 100644
index 0000000..9cda8be
--- /dev/null
+++ b/internal/shared/pkg/metricparse/metricparse_test.go
@@ -0,0 +1,43 @@
+package metricparse
+
+import "testing"
+
+func TestParseString(t *testing.T) {
+	cases := []struct {
+		in   string
+		want float64
+	}{
+		{"GPC/N1 63.2", 63.2},   // the "1" in N1 must NOT win
+		{"PTC/N2 61.8", 61.8},   // the "2" in N2 must NOT win
+		{"GPC/NG/N1 105.3", 105.3},
+		{"63.2", 63.2},
+		{"  63.2  ", 63.2},
+		{"63", 63},
+		{"63,2", 63.2},          // decimal comma
+		{"GPC/N1: 63.2 %", 63.2}, // colon + trailing unit
+		{"GPC/N1 63.2 / N2 61.5", 63.2}, // first standalone decimal
+		{"-5", -5},
+		{"+7.5", 7.5},
+		{".5", 0.5},
+		{"N1", 0},   // label only, no value
+		{"N2", 0},   // label only
+		{"", 0},
+		{"   ", 0},
+		{"no numbers here", 0},
+	}
+	for _, c := range cases {
+		if got := ParseString(c.in); got != c.want {
+			t.Errorf("ParseString(%q) = %v, want %v", c.in, got, c.want)
+		}
+	}
+}
+
+func TestParseNilAndPtr(t *testing.T) {
+	if got := Parse(nil); got != 0 {
+		t.Fatalf("Parse(nil) = %v, want 0", got)
+	}
+	s := "GPC/N1 63.2"
+	if got := Parse(&s); got != 63.2 {
+		t.Fatalf("Parse(&%q) = %v, want 63.2", s, got)
+	}
+}
diff --git a/internal/shared/pkg/metrics/prometheus.go b/internal/shared/pkg/metrics/prometheus.go
new file mode 100644
index 0000000..b5a7168
--- /dev/null
+++ b/internal/shared/pkg/metrics/prometheus.go
@@ -0,0 +1,384 @@
+package metrics
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"path"
+	"strings"
+	"sync"
+	"time"
+
+	smithyhttp "github.com/aws/smithy-go/transport/http"
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+var (
+	registerOnce sync.Once
+
+	awsRequestsTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_aws_requests_total",
+		Help: "Total number of AWS requests by component, service, operation, and result.",
+	}, []string{"component", "service", "operation", "result"})
+	awsRequestDurationSeconds = prometheus.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "app_aws_request_duration_seconds",
+		Help:    "AWS request duration in seconds by component, service, and operation.",
+		Buckets: prometheus.DefBuckets,
+	}, []string{"component", "service", "operation"})
+	awsErrorsTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_aws_errors_total",
+		Help: "Total number of AWS errors by class.",
+	}, []string{"component", "service", "operation", "error_class"})
+	awsTransferredBytesTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_aws_transferred_bytes_total",
+		Help: "Total AWS transferred bytes by component, service, operation, and direction.",
+	}, []string{"component", "service", "operation", "direction"})
+
+	queueMessagesReceivedTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_queue_messages_received_total",
+		Help: "Total number of queue messages received.",
+	}, []string{"component", "queue_name"})
+	queueMessagesDeletedTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_queue_messages_deleted_total",
+		Help: "Total number of queue messages deleted.",
+	}, []string{"component", "queue_name"})
+	queueVisibilityChangesTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_queue_visibility_changes_total",
+		Help: "Total number of queue visibility timeout changes.",
+	}, []string{"component", "queue_name", "result"})
+	queueSendTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_queue_send_total",
+		Help: "Total number of queue send attempts.",
+	}, []string{"component", "queue_name", "result"})
+	queueRetriesTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_queue_retries_total",
+		Help: "Total number of queue retry/requeue attempts.",
+	}, []string{"component", "queue_name", "result"})
+	queueMessageBytesTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_queue_message_bytes_total",
+		Help: "Total queue message bytes observed on send and receive.",
+	}, []string{"component", "queue_name", "direction"})
+	queueDepth = prometheus.NewGaugeVec(prometheus.GaugeOpts{
+		Name: "app_queue_depth",
+		Help: "Approximate queue depth from SQS attributes.",
+	}, []string{"component", "queue_name"})
+
+	workerJobsProcessedTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_worker_jobs_processed_total",
+		Help: "Total number of worker jobs processed.",
+	}, []string{"component", "job_type", "result"})
+	workerJobDurationSeconds = prometheus.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "app_worker_job_duration_seconds",
+		Help:    "Worker job processing duration in seconds.",
+		Buckets: prometheus.DefBuckets,
+	}, []string{"component", "job_type"})
+
+	emailSendTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_email_send_total",
+		Help: "Total number of email send attempts.",
+	}, []string{"component", "provider", "result"})
+	emailSendDurationSeconds = prometheus.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "app_email_send_duration_seconds",
+		Help:    "Email send duration in seconds.",
+		Buckets: prometheus.DefBuckets,
+	}, []string{"component", "provider"})
+
+	fileUploadTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_file_upload_total",
+		Help: "Total number of file upload operations.",
+	}, []string{"component", "result"})
+	fileDeleteTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_file_delete_total",
+		Help: "Total number of file delete operations.",
+	}, []string{"component", "result"})
+	fileHeadTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_file_head_total",
+		Help: "Total number of file head operations.",
+	}, []string{"component", "result"})
+	filePresignDownloadTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_file_presign_download_total",
+		Help: "Total number of file presign download operations.",
+	}, []string{"component", "result"})
+	brandingLogoFetchTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_branding_logo_fetch_total",
+		Help: "Total number of branding logo fetch operations.",
+	}, []string{"component", "source", "result"})
+	brandingLogoFetchDurationSeconds = prometheus.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "app_branding_logo_fetch_duration_seconds",
+		Help:    "Branding logo fetch duration in seconds.",
+		Buckets: prometheus.DefBuckets,
+	}, []string{"component", "source"})
+	brandingRequestsTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "app_branding_requests_total",
+		Help: "Total number of branding endpoint requests by endpoint, source, status, and result.",
+	}, []string{"component", "endpoint", "source", "status_code", "result"})
+	brandingRequestDurationSeconds = prometheus.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "app_branding_request_duration_seconds",
+		Help:    "Branding endpoint request duration in seconds.",
+		Buckets: prometheus.DefBuckets,
+	}, []string{"component", "endpoint"})
+)
+
+func Register() {
+	registerOnce.Do(func() {
+		collectors := []prometheus.Collector{
+			awsRequestsTotal,
+			awsRequestDurationSeconds,
+			awsErrorsTotal,
+			awsTransferredBytesTotal,
+			queueMessagesReceivedTotal,
+			queueMessagesDeletedTotal,
+			queueVisibilityChangesTotal,
+			queueSendTotal,
+			queueRetriesTotal,
+			queueMessageBytesTotal,
+			queueDepth,
+			workerJobsProcessedTotal,
+			workerJobDurationSeconds,
+			emailSendTotal,
+			emailSendDurationSeconds,
+			fileUploadTotal,
+			fileDeleteTotal,
+			fileHeadTotal,
+			filePresignDownloadTotal,
+			brandingLogoFetchTotal,
+			brandingLogoFetchDurationSeconds,
+			brandingRequestsTotal,
+			brandingRequestDurationSeconds,
+		}
+		for _, collector := range collectors {
+			registerCollector(collector)
+		}
+	})
+}
+
+func PromHTTPHandler() http.Handler {
+	Register()
+	return promhttp.Handler()
+}
+
+func ObserveAWSRequest(component, service, operation string, err error, started time.Time) {
+	Register()
+	component = normalizeLabel(component, "worker")
+	service = normalizeLabel(service, "unknown")
+	operation = normalizeLabel(operation, "unknown")
+	result := resultLabel(err)
+
+	awsRequestsTotal.WithLabelValues(component, service, operation, result).Inc()
+	awsRequestDurationSeconds.WithLabelValues(component, service, operation).Observe(time.Since(started).Seconds())
+	if err != nil {
+		awsErrorsTotal.WithLabelValues(component, service, operation, errorClass(err)).Inc()
+	}
+}
+
+func ObserveAWSTransferredBytes(component, service, operation, direction string, bytes int64) {
+	Register()
+	if bytes <= 0 {
+		return
+	}
+	component = normalizeLabel(component, "worker")
+	service = normalizeLabel(service, "unknown")
+	operation = normalizeLabel(operation, "unknown")
+	direction = normalizeLabel(direction, "unknown")
+	awsTransferredBytesTotal.WithLabelValues(component, service, operation, direction).Add(float64(bytes))
+}
+
+func ObserveQueueReceive(component, queueName string, messageCount int, messageBytes int64, err error, started time.Time) {
+	ObserveAWSRequest(component, "sqs", "ReceiveMessage", err, started)
+	if err != nil || messageCount <= 0 {
+		return
+	}
+	component = normalizeLabel(component, "worker")
+	queueName = normalizeLabel(queueName, "unknown")
+	queueMessagesReceivedTotal.WithLabelValues(component, queueName).Add(float64(messageCount))
+	if messageBytes > 0 {
+		queueMessageBytesTotal.WithLabelValues(component, queueName, "receive").Add(float64(messageBytes))
+	}
+}
+
+func ObserveQueueDeleteBatch(component, queueName string, deletedCount int, err error, started time.Time) {
+	ObserveAWSRequest(component, "sqs", "DeleteMessageBatch", err, started)
+	if deletedCount <= 0 {
+		return
+	}
+	component = normalizeLabel(component, "worker")
+	queueName = normalizeLabel(queueName, "unknown")
+	queueMessagesDeletedTotal.WithLabelValues(component, queueName).Add(float64(deletedCount))
+}
+
+func ObserveQueueVisibilityChange(component, queueName string, err error, started time.Time) {
+	ObserveAWSRequest(component, "sqs", "ChangeMessageVisibility", err, started)
+	component = normalizeLabel(component, "worker")
+	queueName = normalizeLabel(queueName, "unknown")
+	result := resultLabel(err)
+	queueVisibilityChangesTotal.WithLabelValues(component, queueName, result).Inc()
+	queueRetriesTotal.WithLabelValues(component, queueName, result).Inc()
+}
+
+func ObserveQueueSend(component, queueName string, messageBytes int64, err error, started time.Time) {
+	ObserveAWSRequest(component, "sqs", "SendMessage", err, started)
+	component = normalizeLabel(component, "worker")
+	queueName = normalizeLabel(queueName, "unknown")
+	result := resultLabel(err)
+	queueSendTotal.WithLabelValues(component, queueName, result).Inc()
+	if err == nil && messageBytes > 0 {
+		queueMessageBytesTotal.WithLabelValues(component, queueName, "send").Add(float64(messageBytes))
+	}
+}
+
+func ObserveQueueDepth(component, queueName string, depth int64, err error, started time.Time) {
+	ObserveAWSRequest(component, "sqs", "GetQueueAttributes", err, started)
+	if err != nil {
+		return
+	}
+	component = normalizeLabel(component, "worker")
+	queueName = normalizeLabel(queueName, "unknown")
+	queueDepth.WithLabelValues(component, queueName).Set(float64(depth))
+}
+
+func InitializeQueueSeries(component, queueName string) {
+	Register()
+	component = normalizeLabel(component, "worker")
+	queueName = normalizeLabel(queueName, "unknown")
+
+	queueMessagesReceivedTotal.WithLabelValues(component, queueName).Add(0)
+	queueMessagesDeletedTotal.WithLabelValues(component, queueName).Add(0)
+	queueVisibilityChangesTotal.WithLabelValues(component, queueName, "success").Add(0)
+	queueVisibilityChangesTotal.WithLabelValues(component, queueName, "error").Add(0)
+	queueSendTotal.WithLabelValues(component, queueName, "success").Add(0)
+	queueSendTotal.WithLabelValues(component, queueName, "error").Add(0)
+	queueRetriesTotal.WithLabelValues(component, queueName, "success").Add(0)
+	queueRetriesTotal.WithLabelValues(component, queueName, "error").Add(0)
+	queueMessageBytesTotal.WithLabelValues(component, queueName, "send").Add(0)
+	queueMessageBytesTotal.WithLabelValues(component, queueName, "receive").Add(0)
+	queueDepth.WithLabelValues(component, queueName).Set(0)
+}
+
+func ObserveWorkerJob(component, jobType string, err error, started time.Time) {
+	Register()
+	component = normalizeLabel(component, "worker")
+	jobType = normalizeLabel(jobType, "unknown")
+	workerJobsProcessedTotal.WithLabelValues(component, jobType, resultLabel(err)).Inc()
+	workerJobDurationSeconds.WithLabelValues(component, jobType).Observe(time.Since(started).Seconds())
+}
+
+func ObserveEmailSend(component, provider string, err error, started time.Time) {
+	Register()
+	component = normalizeLabel(component, "worker")
+	provider = normalizeLabel(provider, "unknown")
+	emailSendTotal.WithLabelValues(component, provider, resultLabel(err)).Inc()
+	emailSendDurationSeconds.WithLabelValues(component, provider).Observe(time.Since(started).Seconds())
+}
+
+func ObserveFileUpload(component string, err error) {
+	Register()
+	fileUploadTotal.WithLabelValues(normalizeLabel(component, "api"), resultLabel(err)).Inc()
+}
+
+func ObserveFileDelete(component string, err error) {
+	Register()
+	fileDeleteTotal.WithLabelValues(normalizeLabel(component, "api"), resultLabel(err)).Inc()
+}
+
+func ObserveFileHead(component string, err error) {
+	Register()
+	fileHeadTotal.WithLabelValues(normalizeLabel(component, "api"), resultLabel(err)).Inc()
+}
+
+func ObserveFilePresignDownload(component string, err error) {
+	Register()
+	filePresignDownloadTotal.WithLabelValues(normalizeLabel(component, "api"), resultLabel(err)).Inc()
+}
+
+func ObserveBrandingLogoFetch(component, source string, err error, started time.Time) {
+	Register()
+	component = normalizeLabel(component, "api")
+	source = normalizeLabel(source, "unknown")
+	brandingLogoFetchTotal.WithLabelValues(component, source, resultLabel(err)).Inc()
+	brandingLogoFetchDurationSeconds.WithLabelValues(component, source).Observe(time.Since(started).Seconds())
+}
+
+func ObserveBrandingRequest(component, endpoint, source string, statusCode int, err error, started time.Time) {
+	Register()
+	component = normalizeLabel(component, "api")
+	endpoint = normalizeLabel(endpoint, "unknown")
+	source = normalizeLabel(source, "unknown")
+	status := "0"
+	if statusCode > 0 {
+		status = normalizeLabel(fmt.Sprintf("%d", statusCode), "0")
+	}
+	brandingRequestsTotal.WithLabelValues(component, endpoint, source, status, resultLabel(err)).Inc()
+	brandingRequestDurationSeconds.WithLabelValues(component, endpoint).Observe(time.Since(started).Seconds())
+}
+
+func QueueNameFromURL(queueURL string) string {
+	raw := strings.TrimSpace(queueURL)
+	if raw == "" {
+		return "unknown"
+	}
+	parsed, err := url.Parse(raw)
+	if err != nil {
+		return "unknown"
+	}
+	name := strings.TrimSpace(path.Base(parsed.Path))
+	if name == "" || name == "." || name == "/" {
+		return "unknown"
+	}
+	return name
+}
+
+func registerCollector(collector prometheus.Collector) {
+	if err := prometheus.Register(collector); err != nil {
+		var alreadyRegistered prometheus.AlreadyRegisteredError
+		if errors.As(err, &alreadyRegistered) {
+			return
+		}
+		panic(err)
+	}
+}
+
+func errorClass(err error) string {
+	statusCode := statusCodeFromError(err)
+	if statusCode >= 400 && statusCode < 500 {
+		return "4xx"
+	}
+	if statusCode >= 500 && statusCode < 600 {
+		return "5xx"
+	}
+	return "other"
+}
+
+func statusCodeFromError(err error) int {
+	if err == nil {
+		return 0
+	}
+	type statusCoder interface {
+		HTTPStatusCode() int
+	}
+	var sc statusCoder
+	if errors.As(err, &sc) {
+		return sc.HTTPStatusCode()
+	}
+	var respErr *smithyhttp.ResponseError
+	if errors.As(err, &respErr) {
+		return respErr.HTTPStatusCode()
+	}
+	return 0
+}
+
+func normalizeLabel(value, fallback string) string {
+	value = strings.ToLower(strings.TrimSpace(value))
+	if value == "" {
+		return fallback
+	}
+	return value
+}
+
+func resultLabel(err error) string {
+	if err != nil {
+		return "error"
+	}
+	return "success"
+}
diff --git a/internal/shared/pkg/missioncode/mission_code.go b/internal/shared/pkg/missioncode/mission_code.go
new file mode 100644
index 0000000..ec62256
--- /dev/null
+++ b/internal/shared/pkg/missioncode/mission_code.go
@@ -0,0 +1,32 @@
+package missioncode
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const (
+	prefixStatic = "M-"
+	suffixWidth  = 3
+)
+
+// BuildPrefix returns the daily mission code prefix, e.g. M-042426-
+func BuildPrefix(t time.Time) string {
+	return prefixStatic + t.Format("010206") + "-"
+}
+
+// NextFromLatest returns next code in sequence using latest code for a day.
+// If latest is empty/invalid, sequence starts from 001.
+func NextFromLatest(prefix string, latest string) string {
+	next := 1
+	latest = strings.TrimSpace(latest)
+	if strings.HasPrefix(latest, prefix) {
+		suffix := strings.TrimPrefix(latest, prefix)
+		if n, err := strconv.Atoi(suffix); err == nil && n > 0 {
+			next = n + 1
+		}
+	}
+	return fmt.Sprintf("%s%0*d", prefix, suffixWidth, next)
+}
diff --git a/internal/shared/pkg/nextdue/parser.go b/internal/shared/pkg/nextdue/parser.go
new file mode 100644
index 0000000..58a6736
--- /dev/null
+++ b/internal/shared/pkg/nextdue/parser.go
@@ -0,0 +1,82 @@
+package nextdue
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+)
+
+type ValueKind string
+
+const (
+	ValueKindUnknown ValueKind = ""
+	ValueKindHours   ValueKind = "hours"
+	ValueKindDate    ValueKind = "date"
+)
+
+type Value struct {
+	Kind  ValueKind
+	Raw   string
+	Hours *float64
+	Date  *time.Time
+}
+
+type ParseError struct {
+	Field string
+	Raw   string
+	Msg   string
+}
+
+func (e *ParseError) Error() string {
+	if e == nil {
+		return ""
+	}
+	if strings.TrimSpace(e.Field) == "" {
+		return e.Msg
+	}
+	return fmt.Sprintf("%s: %s", e.Field, e.Msg)
+}
+
+type Parser struct {
+	DateLayout string
+}
+
+func NewParser() Parser { return Parser{DateLayout: "2006-01-02"} }
+
+func (p Parser) Parse(field, raw string) (Value, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return Value{Kind: ValueKindUnknown, Raw: ""}, nil
+	}
+	if d, err := time.Parse(p.dateLayout(), raw); err == nil {
+		dd := d.UTC()
+		return Value{Kind: ValueKindDate, Raw: raw, Date: &dd}, nil
+	}
+	if h, err := strconv.ParseFloat(raw, 64); err == nil {
+		return Value{Kind: ValueKindHours, Raw: raw, Hours: &h}, nil
+	}
+	return Value{}, &ParseError{Field: field, Raw: raw, Msg: "must be either an ISO date (YYYY-MM-DD) or a numeric hour value"}
+}
+
+func IsUnset(v Value) bool {
+	switch v.Kind {
+	case ValueKindHours:
+		return v.Hours == nil || *v.Hours <= 0
+	case ValueKindDate:
+		return v.Date == nil || v.Date.IsZero()
+	default:
+		return true
+	}
+}
+
+func (p Parser) dateLayout() string {
+	if strings.TrimSpace(p.DateLayout) == "" {
+		return "2006-01-02"
+	}
+	return p.DateLayout
+}
+
+func NormalizeDate(t time.Time) time.Time {
+	return time.Date(t.UTC().Year(), t.UTC().Month(), t.UTC().Day(), 0, 0, 0, 0, time.UTC)
+}
diff --git a/internal/shared/pkg/nextdue/parser_test.go b/internal/shared/pkg/nextdue/parser_test.go
new file mode 100644
index 0000000..dc3458b
--- /dev/null
+++ b/internal/shared/pkg/nextdue/parser_test.go
@@ -0,0 +1,77 @@
+package nextdue
+
+import "testing"
+
+func TestParseErrorError(t *testing.T) {
+	var nilErr *ParseError
+	if nilErr.Error() != "" {
+		t.Fatal("nil ParseError should produce empty string")
+	}
+	if (&ParseError{Msg: "boom"}).Error() != "boom" {
+		t.Fatal("fieldless error should be just the message")
+	}
+	if (&ParseError{Field: "due", Msg: "boom"}).Error() != "due: boom" {
+		t.Fatal("field error should be 'field: msg'")
+	}
+}
+
+func TestParseDefaultDateLayout(t *testing.T) {
+	p := Parser{} // empty DateLayout -> falls back to default
+	v, err := p.Parse("due", "2026-06-17")
+	if err != nil || v.Kind != ValueKindDate {
+		t.Fatalf("default layout should parse date, got kind=%q err=%v", v.Kind, err)
+	}
+}
+
+func TestParse(t *testing.T) {
+	p := NewParser()
+	cases := []struct {
+		raw  string
+		kind ValueKind
+		ok   bool
+	}{
+		{"", ValueKindUnknown, true},
+		{"1200", ValueKindHours, true},
+		{"1200.5", ValueKindHours, true},
+		{"2026-06-17", ValueKindDate, true},
+		{"1200 FH", ValueKindUnknown, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.raw, func(t *testing.T) {
+			v, err := p.Parse("due", tc.raw)
+			if tc.ok && err != nil {
+				t.Fatalf("Parse(%q) err = %v", tc.raw, err)
+			}
+			if !tc.ok && err == nil {
+				t.Fatalf("Parse(%q) expected error", tc.raw)
+			}
+			if tc.ok && v.Kind != tc.kind {
+				t.Fatalf("Parse(%q) kind = %q, want %q", tc.raw, v.Kind, tc.kind)
+			}
+		})
+	}
+}
+
+func TestIsUnset(t *testing.T) {
+	p := NewParser()
+	cases := []struct {
+		raw   string
+		unset bool
+	}{
+		{"", true},
+		{"0", true},
+		{"100", false},
+		{"2026-06-17", false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.raw, func(t *testing.T) {
+			v, err := p.Parse("due", tc.raw)
+			if err != nil {
+				t.Fatalf("Parse(%q) err = %v", tc.raw, err)
+			}
+			if IsUnset(v) != tc.unset {
+				t.Fatalf("IsUnset(%q) = %v, want %v", tc.raw, IsUnset(v), tc.unset)
+			}
+		})
+	}
+}
diff --git a/internal/shared/pkg/reserveacutil/status.go b/internal/shared/pkg/reserveacutil/status.go
new file mode 100644
index 0000000..5ab26f6
--- /dev/null
+++ b/internal/shared/pkg/reserveacutil/status.go
@@ -0,0 +1,33 @@
+package reserveacutil
+
+import "strings"
+
+const (
+	StatusPending    = "pending"
+	StatusApproved   = "approved"
+	StatusOnProgress = "onprogress"
+)
+
+func NormalizeStatus(v string) string {
+	switch strings.ToLower(strings.TrimSpace(v)) {
+	case StatusApproved:
+		return StatusApproved
+	case StatusOnProgress:
+		return StatusOnProgress
+	default:
+		return StatusPending
+	}
+}
+
+func IsValidStatus(v string) bool {
+	switch strings.ToLower(strings.TrimSpace(v)) {
+	case StatusPending, StatusApproved, StatusOnProgress:
+		return true
+	default:
+		return false
+	}
+}
+
+func AllowedStatusText() string {
+	return "pending, approved, onprogress"
+}
diff --git a/internal/shared/pkg/sortkey/sortkey.go b/internal/shared/pkg/sortkey/sortkey.go
new file mode 100644
index 0000000..95e27bc
--- /dev/null
+++ b/internal/shared/pkg/sortkey/sortkey.go
@@ -0,0 +1,32 @@
+package sortkey
+
+import "fmt"
+
+// ActivePositiveSortClauses builds ORDER BY clauses where non-negative sort keys
+// are treated as prioritized values. NULL/negative are grouped as empty values.
+func ActivePositiveSortClauses(tableAlias, activeColumn, sortKeyColumn, fallbackColumn string, descending bool) []string {
+	active := qualify(tableAlias, activeColumn)
+	sortKey := qualify(tableAlias, sortKeyColumn)
+	fallback := qualify(tableAlias, fallbackColumn)
+
+	valid := fmt.Sprintf("%s = 1 AND %s IS NOT NULL AND %s >= 0", active, sortKey, sortKey)
+
+	direction := "ASC"
+	if descending {
+		direction = "DESC"
+	}
+
+	return []string{
+		fmt.Sprintf("%s DESC", active),
+		fmt.Sprintf("CASE WHEN %s THEN 0 ELSE 1 END ASC", valid),
+		fmt.Sprintf("CASE WHEN %s THEN %s END %s", valid, sortKey, direction),
+		fmt.Sprintf("%s ASC", fallback),
+	}
+}
+
+func qualify(tableAlias, column string) string {
+	if tableAlias == "" {
+		return column
+	}
+	return tableAlias + "." + column
+}
diff --git a/internal/shared/pkg/sortkey/sortkey_test.go b/internal/shared/pkg/sortkey/sortkey_test.go
new file mode 100644
index 0000000..9b2972f
--- /dev/null
+++ b/internal/shared/pkg/sortkey/sortkey_test.go
@@ -0,0 +1,34 @@
+package sortkey
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestActivePositiveSortClauses(t *testing.T) {
+	t.Run("ascending without alias", func(t *testing.T) {
+		got := ActivePositiveSortClauses("", "is_active", "sortkey", "designation", false)
+		want := []string{
+			"is_active DESC",
+			"CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC",
+			"CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END ASC",
+			"designation ASC",
+		}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("unexpected clauses: got=%v want=%v", got, want)
+		}
+	})
+
+	t.Run("descending with alias", func(t *testing.T) {
+		got := ActivePositiveSortClauses("helicopters", "is_active", "sortkey", "designation", true)
+		want := []string{
+			"helicopters.is_active DESC",
+			"CASE WHEN helicopters.is_active = 1 AND helicopters.sortkey IS NOT NULL AND helicopters.sortkey >= 0 THEN 0 ELSE 1 END ASC",
+			"CASE WHEN helicopters.is_active = 1 AND helicopters.sortkey IS NOT NULL AND helicopters.sortkey >= 0 THEN helicopters.sortkey END DESC",
+			"helicopters.designation ASC",
+		}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("unexpected clauses: got=%v want=%v", got, want)
+		}
+	})
+}
diff --git a/internal/shared/pkg/suncalc/suncalc.go b/internal/shared/pkg/suncalc/suncalc.go
new file mode 100644
index 0000000..afc85ac
--- /dev/null
+++ b/internal/shared/pkg/suncalc/suncalc.go
@@ -0,0 +1,108 @@
+package suncalc
+
+import (
+	"errors"
+	"math"
+	"time"
+)
+
+const (
+	dayMs = 1000 * 60 * 60 * 24
+	j1970 = 2440588
+	j2000 = 2451545
+	rad   = math.Pi / 180
+	e     = rad * 23.4397
+)
+
+var ErrNoCivilTwilight = errors.New("civil twilight is not available for the selected date and location")
+
+type CivilTwilight struct {
+	Dawn time.Time
+	Dusk time.Time
+}
+
+func GetCivilTwilight(date time.Time, lat, lng float64) (CivilTwilight, error) {
+	if math.IsNaN(lat) || math.IsNaN(lng) || lat < -90 || lat > 90 || lng < -180 || lng > 180 {
+		return CivilTwilight{}, errors.New("invalid coordinates")
+	}
+
+	d := toDays(date)
+	lw := -lng * rad
+	phi := lat * rad
+	n := julianCycle(d, lw)
+	ds := approxTransit(0, lw, n)
+	M := solarMeanAnomaly(ds)
+	L := eclipticLongitude(M)
+	dec := declination(L, 0)
+	noonJ := solarTransitJ(ds, M, L)
+
+	duskJ, ok := getSetJ(-6*rad, lw, phi, dec, n, M, L)
+	if !ok {
+		return CivilTwilight{}, ErrNoCivilTwilight
+	}
+	dawnJ := 2*noonJ - duskJ
+
+	return CivilTwilight{
+		Dawn: fromJulian(dawnJ),
+		Dusk: fromJulian(duskJ),
+	}, nil
+}
+
+func toJulian(date time.Time) float64 {
+	return float64(date.UTC().Unix())/86400 - 0.5 + j1970
+}
+
+func fromJulian(j float64) time.Time {
+	return time.Unix(int64((j+0.5-float64(j1970))*86400), 0).UTC()
+}
+
+func toDays(date time.Time) float64 {
+	return toJulian(date) - j2000
+}
+
+func rightAscension(l, b float64) float64 {
+	return math.Atan2(math.Sin(l)*math.Cos(e)-math.Tan(b)*math.Sin(e), math.Cos(l))
+}
+
+func declination(l, b float64) float64 {
+	return math.Asin(math.Sin(b)*math.Cos(e) + math.Cos(b)*math.Sin(e)*math.Sin(l))
+}
+
+func solarMeanAnomaly(d float64) float64 {
+	return rad * (357.5291 + 0.98560028*d)
+}
+
+func eclipticLongitude(M float64) float64 {
+	C := rad * (1.9148*math.Sin(M) + 0.02*math.Sin(2*M) + 0.0003*math.Sin(3*M))
+	P := rad * 102.9372
+	return M + C + P + math.Pi
+}
+
+func julianCycle(d, lw float64) float64 {
+	return math.Round(d - 0.0009 - lw/(2*math.Pi))
+}
+
+func approxTransit(Ht, lw, n float64) float64 {
+	return 0.0009 + (Ht+lw)/(2*math.Pi) + n
+}
+
+func solarTransitJ(ds, M, L float64) float64 {
+	return j2000 + ds + 0.0053*math.Sin(M) - 0.0069*math.Sin(2*L)
+}
+
+func hourAngle(h, phi, d float64) float64 {
+	cosH := (math.Sin(h) - math.Sin(phi)*math.Sin(d)) / (math.Cos(phi) * math.Cos(d))
+	if cosH < -1 || cosH > 1 {
+		return math.NaN()
+	}
+	return math.Acos(cosH)
+}
+
+func getSetJ(h, lw, phi, dec, n, M, L float64) (float64, bool) {
+	w := hourAngle(h, phi, dec)
+	if math.IsNaN(w) {
+		return 0, false
+	}
+	a := approxTransit(w, lw, n)
+	return solarTransitJ(a, M, L), true
+}
diff --git a/internal/shared/pkg/timezone/timezone.go b/internal/shared/pkg/timezone/timezone.go
new file mode 100644
index 0000000..145f517
--- /dev/null
+++ b/internal/shared/pkg/timezone/timezone.go
@@ -0,0 +1,35 @@
+package timezone
+
+import (
+	"errors"
+	"strings"
+	"time"
+)
+
+const Default = "UTC"
+
+var (
+	ErrEmpty   = errors.New("timezone is required")
+	ErrInvalid = errors.New("timezone must be a valid IANA timezone")
+)
+
+func Normalize(name string) (string, error) {
+	tz := strings.TrimSpace(name)
+	if tz == "" {
+		return "", ErrEmpty
+	}
+
+	loc, err := time.LoadLocation(tz)
+	if err != nil {
+		return "", ErrInvalid
+	}
+	return loc.String(), nil
+}
+
+func WithDefault(name string) string {
+	tz := strings.TrimSpace(name)
+	if tz == "" {
+		return Default
+	}
+	return tz
+}
diff --git a/internal/shared/pkg/txctx/txctx.go b/internal/shared/pkg/txctx/txctx.go
new file mode 100644
index 0000000..333a5e2
--- /dev/null
+++ b/internal/shared/pkg/txctx/txctx.go
@@ -0,0 +1,29 @@
+// Package txctx propagates a GORM transaction through a context.Context so that
+// repositories transparently join a caller's transaction. A service starts a
+// transaction, stashes the *gorm.DB tx with With, and calls its existing
+// repository methods unchanged; those repositories resolve the handle with DB.
+package txctx
+
+import (
+	"context"
+
+	"gorm.io/gorm"
+)
+
+type key struct{}
+
+// With returns a context carrying the given transaction handle.
+func With(ctx context.Context, tx *gorm.DB) context.Context {
+	return context.WithValue(ctx, key{}, tx)
+}
+
+// DB returns the transaction bound to ctx when present, otherwise the fallback
+// db scoped to ctx. Repositories should use this instead of their raw db handle
+// so a single statement runs standalone while orchestrated writes join the
+// caller's transaction.
+func DB(ctx context.Context, fallback *gorm.DB) *gorm.DB {
+	if tx, ok := ctx.Value(key{}).(*gorm.DB); ok && tx != nil {
+		return tx
+	}
+	return fallback.WithContext(ctx)
+}
diff --git a/internal/shared/pkg/userctx/user_name_cache.go b/internal/shared/pkg/userctx/user_name_cache.go
new file mode 100644
index 0000000..e5edc6c
--- /dev/null
+++ b/internal/shared/pkg/userctx/user_name_cache.go
@@ -0,0 +1,346 @@
+package userctx
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"time"
+
+	"wucher/internal/domain/user"
+)
+
+// UserNameGetter is the interface used by handlers to resolve user IDs to names.
+type UserNameGetter interface {
+	GetLastName(ctx context.Context, userID []byte) (string, error)
+}
+
+// UserFullNameGetter is an optional extension for getters that can resolve
+// full names (first + last). Code should prefer this when available.
+type UserFullNameGetter interface {
+	GetFullName(ctx context.Context, userID []byte) (string, error)
+}
+
+// UserShortNameGetter is an optional extension for getters that can resolve a
+// user's short name (profile 3-letter code, e.g. "GAN"). Code should prefer
+// this when available, falling back to initials from the display name.
+type UserShortNameGetter interface {
+	GetShortName(ctx context.Context, userID []byte) (string, error)
+}
+
+// shortNameRepo is the optional repository capability used by UserNameCache to
+// look up a profile short name. Only the concrete MySQL repo implements it;
+// keeping it out of user.Repository avoids churning every mock.
+type shortNameRepo interface {
+	GetShortNameByID(ctx context.Context, id []byte) (string, error)
+}
+
+// initialsFromFullName derives an uppercase initials short name from a full
+// name: "System Admin" → "SA", "Gantner" → "G". Empty when there is no name.
+func initialsFromFullName(fullName string) string {
+	parts := strings.Fields(strings.TrimSpace(fullName))
+	if len(parts) == 0 {
+		return ""
+	}
+	if len(parts) == 1 {
+		r := []rune(parts[0])
+		if len(r) == 0 {
+			return ""
+		}
+		return strings.ToUpper(string(r[0]))
+	}
+	first := []rune(parts[0])
+	last := []rune(parts[len(parts)-1])
+	if len(first) == 0 || len(last) == 0 {
+		return ""
+	}
+	return strings.ToUpper(string(first[0]) + string(last[0]))
+}
+
+// GlobalUserNameGetter is set once at application startup via WireUserNameGetter.
+// It is used by uuidStringOrEmpty helpers across packages.
+var GlobalUserNameGetter UserNameGetter
+
+// WireUserNameGetter configures the global user name getter.
+// Call this once during application startup (e.g. in main.go).
+func WireUserNameGetter(getter UserNameGetter) {
+	GlobalUserNameGetter = getter
+}
+
+// contextKey for storing the getter in context.
+type contextKey string
+
+const getterKey contextKey = "userctx-getter"
+
+// WithGetter stores a UserNameGetter in the context.
+func WithGetter(ctx context.Context, getter UserNameGetter) context.Context {
+	return context.WithValue(ctx, getterKey, getter)
+}
+
+// GetGetter retrieves the UserNameGetter from context.
+func GetGetter(ctx context.Context) UserNameGetter {
+	if ctx == nil {
+		return nil
+	}
+	if getter, ok := any(ctx).(interface{ UserValue(any) any }); ok {
+		raw := getter.UserValue(string(getterKey))
+		if raw != nil {
+			return raw.(UserNameGetter)
+		}
+	}
+	v := ctx.Value(getterKey)
+	if v == nil {
+		return nil
+	}
+	g, _ := v.(UserNameGetter)
+	return g
+}
+
+// GetDisplayName resolves a user ID to a display name.
+// Priority:
+// 1) full name from context getter (if supported)
+// 2) last name from context getter
+// 3) full name from global getter (if supported)
+// 4) last name from global getter
+func GetDisplayName(ctx context.Context, userID []byte) string {
+	if len(userID) == 0 {
+		return ""
+	}
+	type userNameGetter interface {
+		GetLastName(context.Context, []byte) (string, error)
+	}
+	type userFullNameGetter interface {
+		GetFullName(context.Context, []byte) (string, error)
+	}
+	// Backward compatibility: some call sites pass a context-like object that
+	// implements getter methods directly.
+	if fullGetter, ok := any(ctx).(userFullNameGetter); ok {
+		if name, err := fullGetter.GetFullName(ctx, userID); err == nil && name != "" {
+			return name
+		}
+	}
+	if getter, ok := any(ctx).(userNameGetter); ok {
+		if name, err := getter.GetLastName(ctx, userID); err == nil && name != "" {
+			return name
+		}
+	}
+	if getter := GetGetter(ctx); getter != nil {
+		if fullGetter, ok := getter.(UserFullNameGetter); ok {
+			if name, err := fullGetter.GetFullName(ctx, userID); err == nil && name != "" {
+				return name
+			}
+		}
+		if name, err := getter.GetLastName(ctx, userID); err == nil && name != "" {
+			return name
+		}
+	}
+	if GlobalUserNameGetter != nil {
+		if fullGetter, ok := GlobalUserNameGetter.(UserFullNameGetter); ok {
+			if name, err := fullGetter.GetFullName(ctx, userID); err == nil && name != "" {
+				return name
+			}
+		}
+		if name, err := GlobalUserNameGetter.GetLastName(ctx, userID); err == nil && name != "" {
+			return name
+		}
+	}
+	return ""
+}
+
+// GetShortName resolves a user ID to a short name (profile 3-letter code, e.g.
+// "GAN"), falling back to initials derived from the user's display name.
+// Priority mirrors GetDisplayName: context getter, then global getter, then a
+// display-name-initials fallback so it always returns something short.
+func GetShortName(ctx context.Context, userID []byte) string {
+	if len(userID) == 0 {
+		return ""
+	}
+	type shortGetter interface {
+		GetShortName(context.Context, []byte) (string, error)
+	}
+	// Backward compatibility: a context-like object implementing the getter.
+	if g, ok := any(ctx).(shortGetter); ok {
+		if s, err := g.GetShortName(ctx, userID); err == nil && s != "" {
+			return s
+		}
+	}
+	if getter := GetGetter(ctx); getter != nil {
+		if sg, ok := getter.(UserShortNameGetter); ok {
+			if s, err := sg.GetShortName(ctx, userID); err == nil && s != "" {
+				return s
+			}
+		}
+	}
+	if GlobalUserNameGetter != nil {
+		if sg, ok := GlobalUserNameGetter.(UserShortNameGetter); ok {
+			if s, err := sg.GetShortName(ctx, userID); err == nil && s != "" {
+				return s
+			}
+		}
+	}
+	// Universal fallback: initials from whatever display name we can resolve.
+	return initialsFromFullName(GetDisplayName(ctx, userID))
+}
+
+// GetLastName resolves a user ID to their last name using the getter from context.
+// Returns an empty string if no getter is available or if userID is nil/empty.
+func GetLastName(ctx context.Context, userID []byte) string {
+	if len(userID) == 0 {
+		return ""
+	}
+	getter := GetGetter(ctx)
+	if getter == nil {
+		return ""
+	}
+	name, err := getter.GetLastName(ctx, userID)
+	if err != nil {
+		return ""
+	}
+	return name
+}
+
+// cacheEntry holds a cached last name with expiry time.
+type cacheEntry struct {
+	lastName string
+	expires  time.Time
+}
+
+// UserNameCache is an in-memory TTL cache backed by a user.Repository.
+type UserNameCache struct {
+	repo       user.Repository
+	cache      map[string]cacheEntry
+	shortCache map[string]cacheEntry
+	mu         sync.RWMutex
+	ttl        time.Duration
+}
+
+// NewUserNameCache creates a UserNameCache with the given TTL (default 5 minutes).
+func NewUserNameCache(repo user.Repository, ttl time.Duration) *UserNameCache {
+	if ttl <= 0 {
+		ttl = 5 * time.Minute
+	}
+	c := &UserNameCache{
+		repo:       repo,
+		cache:      make(map[string]cacheEntry),
+		shortCache: make(map[string]cacheEntry),
+		ttl:        ttl,
+	}
+	go c.cleanupLoop()
+	return c
+}
+
+// GetShortName resolves a user ID to their profile short name (3-letter code),
+// falling back to initials derived from their full name. Cached with the same
+// TTL as names. (The cacheEntry.lastName field stores the short name here.)
+func (c *UserNameCache) GetShortName(ctx context.Context, userID []byte) (string, error) {
+	if len(userID) == 0 {
+		return "", nil
+	}
+
+	key := string(userID)
+
+	c.mu.RLock()
+	entry, ok := c.shortCache[key]
+	c.mu.RUnlock()
+
+	if ok && time.Now().Before(entry.expires) {
+		return entry.lastName, nil
+	}
+
+	short := ""
+	if sr, ok := c.repo.(shortNameRepo); ok {
+		s, err := sr.GetShortNameByID(ctx, userID)
+		if err != nil {
+			return "", err
+		}
+		short = strings.TrimSpace(s)
+	}
+	if short == "" {
+		// Fallback: initials derived from the full name.
+		if full, err := c.GetFullName(ctx, userID); err == nil {
+			short = initialsFromFullName(full)
+		}
+	}
+
+	c.mu.Lock()
+	c.shortCache[key] = cacheEntry{lastName: short, expires: time.Now().Add(c.ttl)}
+	c.mu.Unlock()
+
+	return short, nil
+}
+
+func (c *UserNameCache) GetLastName(ctx context.Context, userID []byte) (string, error) {
+	if len(userID) == 0 {
+		return "", nil
+	}
+
+	key := string(userID)
+
+	c.mu.RLock()
+	entry, ok := c.cache[key]
+	c.mu.RUnlock()
+
+	if ok && time.Now().Before(entry.expires) {
+		return entry.lastName, nil
+	}
+
+	lastName, err := c.repo.GetLastNameByID(ctx, userID)
+	if err != nil {
+		return "", err
+	}
+	if lastName == "" {
+		lastName = "(Unknown)"
+	}
+
+	c.mu.Lock()
+	c.cache[key] = cacheEntry{lastName: lastName, expires: time.Now().Add(c.ttl)}
+	c.mu.Unlock()
+
+	return lastName, nil
+}
+
+func (c *UserNameCache) GetFullName(ctx context.Context, userID []byte) (string, error) {
+	if len(userID) == 0 {
+		return "", nil
+	}
+	u, err := c.repo.GetByID(ctx, userID)
+	if err != nil {
+		return "", err
+	}
+	if u == nil {
+		return "", nil
+	}
+	first := ""
+	last := ""
+	if u.FirstName != "" {
+		first = u.FirstName
+	}
+	if u.LastName != "" {
+		last = u.LastName
+	}
+	if first == "" {
+		return last, nil
+	}
+	if last == "" {
+		return first, nil
+	}
+	return first + " " + last, nil
+}
+
+func (c *UserNameCache) cleanupLoop() {
+	ticker := time.NewTicker(c.ttl * 2)
+	for range ticker.C {
+		c.mu.Lock()
+		now := time.Now()
+		for k, v := range c.cache {
+			if now.After(v.expires) {
+				delete(c.cache, k)
+			}
+		}
+		for k, v := range c.shortCache {
+			if now.After(v.expires) {
+				delete(c.shortCache, k)
+			}
+		}
+		c.mu.Unlock()
+	}
+}
diff --git a/internal/shared/pkg/util/shift_clock.go b/internal/shared/pkg/util/shift_clock.go
new file mode 100644
index 0000000..3285cdc
--- /dev/null
+++ b/internal/shared/pkg/util/shift_clock.go
@@ -0,0 +1,244 @@
+package util
+
+import (
+	"errors"
+	"fmt"
+	"math"
+	"strings"
+	"time"
+
+	basedomain "wucher/internal/domain/base"
+	"wucher/internal/shared/pkg/suncalc"
+)
+
+var (
+	ErrShiftScheduleMissing    = errors.New("base shift schedule not found")
+	ErrShiftTwilightMissing    = errors.New("base twilight time not available")
+	ErrShiftCoordinatesInvalid = errors.New("base coordinates invalid")
+)
+
+func ResolveShiftWindow(b *basedomain.Base, date time.Time) (string, string, error) {
+	if b == nil || date.IsZero() {
+		return "", "", ErrShiftScheduleMissing
+	}
+
+	shift := PickShiftForDate(b, date)
+	loc := LocationFromUTCOffset(b.UTC)
+	scheduleDay := calendarDate(date)
+	scheduleDate := time.Date(scheduleDay.Year(), scheduleDay.Month(), scheduleDay.Day(), 12, 0, 0, 0, loc)
+
+	if shift == nil {
+		if shiftWindowNeedsCoordinates(b.DefaultStartTimeType, b.DefaultEndTimeType) && !ValidCoordinates(b.Latitude, b.Longitude) {
+			return "", "", ErrShiftCoordinatesInvalid
+		}
+		return resolveBaseDefaultShiftWindow(b, scheduleDate, loc)
+	}
+	if shiftWindowNeedsCoordinates(shift.StartTimeType, shift.EndTimeType) && !ValidCoordinates(b.Latitude, b.Longitude) {
+		return "", "", ErrShiftCoordinatesInvalid
+	}
+
+	start, err := resolveShiftClock(scheduleDate, loc, b, shift.StartTimeType, shift.ShiftStart, true)
+	if err != nil {
+		return "", "", err
+	}
+	end, err := resolveShiftClock(scheduleDate, loc, b, shift.EndTimeType, shift.ShiftEnd, false)
+	if err != nil {
+		return "", "", err
+	}
+	return start, end, nil
+}
+
+func shiftWindowNeedsCoordinates(startTimeType, endTimeType string) bool {
+	return NormalizeShiftTimeType(startTimeType) != basedomain.ShiftTimeTypeFixed ||
+		NormalizeShiftTimeType(endTimeType) != basedomain.ShiftTimeTypeFixed
+}
+
+func resolveBaseDefaultShiftWindow(b *basedomain.Base, scheduleDate time.Time, loc *time.Location) (string, string, error) {
+	start, err := resolveShiftClock(scheduleDate, loc, b, b.DefaultStartTimeType, b.DefaultShiftStart, true)
+	if err != nil {
+		return "", "", err
+	}
+	end, err := resolveShiftClock(scheduleDate, loc, b, b.DefaultEndTimeType, b.DefaultShiftEnd, false)
+	if err != nil {
+		return "", "", err
+	}
+	if start == "" || end == "" {
+		return "", "", ErrShiftScheduleMissing
+	}
+	return start, end, nil
+}
+
+func PickShiftForDate(b *basedomain.Base, date time.Time) *basedomain.BaseOperationalShiftTime {
+	if b == nil {
+		return nil
+	}
+	day := calendarDate(date)
+	for i := range b.OperationalShiftTimes {
+		row := &b.OperationalShiftTimes[i]
+		if row.DateStart == nil || row.DateEnd == nil {
+			continue
+		}
+		start := calendarDate(*row.DateStart)
+		end := calendarDate(*row.DateEnd)
+		if (day.Equal(start) || day.After(start)) && (day.Equal(end) || day.Before(end.Add(24*time.Hour))) {
+			return row
+		}
+	}
+	return nil
+}
+
+func calendarDate(t time.Time) time.Time {
+	return time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, time.UTC)
+}
+
+func DefaultShiftWindow(b *basedomain.Base) (string, string, error) {
+	if b == nil {
+		return "", "", ErrShiftScheduleMissing
+	}
+	start := NormalizeClockValue(b.DefaultShiftStart)
+	end := NormalizeClockValue(b.DefaultShiftEnd)
+	if start == "" || end == "" {
+		return "", "", ErrShiftScheduleMissing
+	}
+	return start, end, nil
+}
+
+func resolveShiftClock(date time.Time, loc *time.Location, b *basedomain.Base, timeType, fixedValue string, morning bool) (string, error) {
+	switch NormalizeShiftTimeType(timeType) {
+	case basedomain.ShiftTimeTypeFixed:
+		clock := NormalizeClockValue(fixedValue)
+		if clock == "" {
+			return "", ErrShiftScheduleMissing
+		}
+		return clock, nil
+	case basedomain.ShiftTimeTypeBMCT:
+		return resolveSunCalcClock(date, loc, b, true)
+	case basedomain.ShiftTimeTypeECET:
+		return resolveSunCalcClock(date, loc, b, false)
+	default:
+		return "", fmt.Errorf("invalid shift time type %q", timeType)
+	}
+}
+
+func resolveSunCalcClock(date time.Time, loc *time.Location, b *basedomain.Base, morning bool) (string, error) {
+	twilight, err := suncalc.GetCivilTwilight(date, b.Latitude, b.Longitude)
+	if err != nil {
+		return "", ErrShiftTwilightMissing
+	}
+	var resolved time.Time
+	if morning {
+		resolved = twilight.Dawn
+	} else {
+		resolved = twilight.Dusk
+	}
+	if resolved.IsZero() {
+		return "", ErrShiftTwilightMissing
+	}
+	if loc == nil {
+		loc = time.UTC
+	}
+	return resolved.In(loc).Format("15:04"), nil
+}
+
+func NormalizeClockValue(raw string) string {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" {
+		return ""
+	}
+	if len(trimmed) == 5 {
+		trimmed += ":00"
+	}
+	layouts := []string{
+		"15:04:05",
+		"15:04",
+		"2006-01-02 15:04:05",
+		"2006-01-02 15:04",
+		time.RFC3339,
+		time.RFC3339Nano,
+	}
+	for _, layout := range layouts {
+		parsed, err := time.Parse(layout, trimmed)
+		if err == nil {
+			return parsed.UTC().Format("15:04")
+		}
+	}
+	return ""
+}
+
+func LocationFromUTCOffset(raw string) *time.Location {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" || trimmed == "0" {
+		return time.UTC
+	}
+	if loc, err := time.LoadLocation(trimmed); err == nil {
+		return loc
+	}
+	if offset, ok := parseUTCOffset(trimmed); ok {
+		return time.FixedZone("UTC", offset)
+	}
+	return time.UTC
+}
+
+func parseUTCOffset(raw string) (int, bool) {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" {
+		return 0, false
+	}
+	sign := 1
+	switch {
+	case strings.HasPrefix(trimmed, "+"):
+		trimmed = strings.TrimPrefix(trimmed, "+")
+	case strings.HasPrefix(trimmed, "-"):
+		sign = -1
+		trimmed = strings.TrimPrefix(trimmed, "-")
+	}
+	trimmed = strings.TrimPrefix(strings.ToUpper(trimmed), "UTC")
+	trimmed = strings.TrimSpace(trimmed)
+	switch {
+	case strings.HasPrefix(trimmed, "+"):
+		trimmed = strings.TrimPrefix(trimmed, "+")
+	case strings.HasPrefix(trimmed, "-"):
+		sign = -1
+		trimmed = strings.TrimPrefix(trimmed, "-")
+	}
+	if trimmed == "" {
+		return 0, false
+	}
+	parts := strings.Split(trimmed, ":")
+	hours := 0
+	minutes := 0
+	switch len(parts) {
+	case 1:
+		if _, err := fmt.Sscanf(parts[0], "%d", &hours); err != nil {
+			return 0, false
+		}
+	case 2:
+		if _, err := fmt.Sscanf(parts[0], "%d", &hours); err != nil {
+			return 0, false
+		}
+		if _, err := fmt.Sscanf(parts[1], "%d", &minutes); err != nil {
+			return 0, false
+		}
+	default:
+		return 0, false
+	}
+	total := ((hours * 3600) + (minutes * 60)) * sign
+	return total, true
+}
+
+func ValidCoordinates(lat, lon float64) bool {
+	return !math.IsNaN(lat) && !math.IsNaN(lon) && lat >= -90 && lat <= 90 && lon >= -180 && lon <= 180
+}
+
+func NormalizeShiftTimeType(raw string) string {
+	switch strings.ToUpper(strings.TrimSpace(raw)) {
+	case "", basedomain.ShiftTimeTypeFixed:
+		return basedomain.ShiftTimeTypeFixed
+	case basedomain.ShiftTimeTypeBMCT:
+		return basedomain.ShiftTimeTypeBMCT
+	case basedomain.ShiftTimeTypeECET:
+		return basedomain.ShiftTimeTypeECET
+	default:
+		return strings.ToUpper(strings.TrimSpace(raw))
+	}
+}
diff --git a/internal/shared/pkg/util/shift_clock_test.go b/internal/shared/pkg/util/shift_clock_test.go
new file mode 100644
index 0000000..a300303
--- /dev/null
+++ b/internal/shared/pkg/util/shift_clock_test.go
@@ -0,0 +1,70 @@
+package util
+
+import (
+	"testing"
+	"time"
+
+	basedomain "wucher/internal/domain/base"
+)
+
+func TestResolveShiftWindowUsesOperationalShiftWithinDateRange(t *testing.T) {
+	base := &basedomain.Base{
+		DefaultStartTimeType: basedomain.ShiftTimeTypeFixed,
+		DefaultEndTimeType:   basedomain.ShiftTimeTypeFixed,
+		DefaultShiftStart:    "09:00",
+		DefaultShiftEnd:      "21:00",
+		OperationalShiftTimes: []basedomain.BaseOperationalShiftTime{
+			{
+				DateStart:     timePtr(time.Date(2026, time.June, 1, 0, 0, 0, 0, time.UTC)),
+				DateEnd:       timePtr(time.Date(2026, time.June, 30, 0, 0, 0, 0, time.UTC)),
+				StartTimeType: basedomain.ShiftTimeTypeFixed,
+				EndTimeType:   basedomain.ShiftTimeTypeFixed,
+				ShiftStart:    "10:00",
+				ShiftEnd:      "22:00",
+			},
+		},
+	}
+
+	start, end, err := ResolveShiftWindow(base, time.Date(2026, time.June, 15, 0, 0, 0, 0, time.UTC))
+	if err != nil {
+		t.Fatalf("ResolveShiftWindow returned error: %v", err)
+	}
+	if start != "10:00" || end != "22:00" {
+		t.Fatalf("expected operational shift 10:00-22:00, got %s-%s", start, end)
+	}
+
+	start, end, err = ResolveShiftWindow(base, time.Date(2026, time.July, 1, 0, 0, 0, 0, time.UTC))
+	if err != nil {
+		t.Fatalf("ResolveShiftWindow returned error: %v", err)
+	}
+	if start != "09:00" || end != "21:00" {
+		t.Fatalf("expected default shift 09:00-21:00, got %s-%s", start, end)
+	}
+}
+
+func TestPickShiftForDatePreservesCalendarDateFromLocalTimezone(t *testing.T) {
+	jakarta := time.FixedZone("UTC+7", 7*60*60)
+	shift := basedomain.BaseOperationalShiftTime{
+		DateStart:     timePtr(time.Date(2026, time.June, 1, 0, 0, 0, 0, jakarta)),
+		DateEnd:       timePtr(time.Date(2026, time.June, 30, 0, 0, 0, 0, jakarta)),
+		StartTimeType: basedomain.ShiftTimeTypeFixed,
+		EndTimeType:   basedomain.ShiftTimeTypeFixed,
+		ShiftStart:    "10:00",
+		ShiftEnd:      "22:00",
+	}
+	base := &basedomain.Base{
+		OperationalShiftTimes: []basedomain.BaseOperationalShiftTime{shift},
+	}
+
+	picked := PickShiftForDate(base, time.Date(2026, time.June, 1, 0, 0, 0, 0, time.UTC))
+	if picked == nil {
+		t.Fatalf("expected operational shift to match calendar date from local timezone")
+	}
+	if picked.ShiftStart != "10:00" || picked.ShiftEnd != "22:00" {
+		t.Fatalf("unexpected picked shift %s-%s", picked.ShiftStart, picked.ShiftEnd)
+	}
+}
+
+func timePtr(v time.Time) *time.Time {
+	return &v
+}
diff --git a/internal/shared/pkg/uuidv7/uuidv7.go b/internal/shared/pkg/uuidv7/uuidv7.go
new file mode 100644
index 0000000..b772bb5
--- /dev/null
+++ b/internal/shared/pkg/uuidv7/uuidv7.go
@@ -0,0 +1,201 @@
+package uuidv7
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// New returns a UUIDv7 (RFC 9562) as a 16-byte array.
+func New() ([16]byte, error) {
+	var out [16]byte
+
+	var r [10]byte
+	if _, err := rand.Read(r[:]); err != nil {
+		return out, err
+	}
+
+	// 48-bit Unix epoch milliseconds
+	ms := uint64(time.Now().UnixNano() / int64(time.Millisecond))
+	out[0] = byte(ms >> 40)
+	out[1] = byte(ms >> 32)
+	out[2] = byte(ms >> 24)
+	out[3] = byte(ms >> 16)
+	out[4] = byte(ms >> 8)
+	out[5] = byte(ms)
+
+	// Version (0111) in high 4 bits of byte 6
+	out[6] = (r[0] & 0x0f) | 0x70
+	out[7] = r[1]
+
+	// Variant (10) in high 2 bits of byte 8
+	out[8] = (r[2] & 0x3f) | 0x80
+	out[9] = r[3]
+	out[10] = r[4]
+	out[11] = r[5]
+	out[12] = r[6]
+	out[13] = r[7]
+	out[14] = r[8]
+	out[15] = r[9]
+
+	return out, nil
+}
+
+// MustNew panics if UUID generation fails.
+func MustNew() [16]byte {
+	u, err := New()
+	if err != nil {
+		panic(err)
+	}
+	return u
+}
+
+// Bytes returns a new UUIDv7 as []byte for BINARY(16) columns.
+func Bytes() ([]byte, error) {
+	u, err := New()
+	if err != nil {
+		return nil, err
+	}
+	b := make([]byte, 16)
+	copy(b, u[:])
+	return b, nil
+}
+
+// MustBytes panics if UUID generation fails.
+func MustBytes() []byte {
+	u := MustNew()
+	b := make([]byte, 16)
+	copy(b, u[:])
+	return b
+}
+
+// String formats a UUID as a canonical string (8-4-4-4-12).
+func String(u [16]byte) (string, error) {
+	if len(u) != 16 {
+		return "", errors.New("invalid uuid length")
+	}
+	dst := make([]byte, 36)
+	hex.Encode(dst[0:8], u[0:4])
+	dst[8] = '-'
+	hex.Encode(dst[9:13], u[4:6])
+	dst[13] = '-'
+	hex.Encode(dst[14:18], u[6:8])
+	dst[18] = '-'
+	hex.Encode(dst[19:23], u[8:10])
+	dst[23] = '-'
+	hex.Encode(dst[24:36], u[10:16])
+	return string(dst), nil
+}
+
+// BytesToString formats a UUID stored in []byte as a canonical string.
+func BytesToString(b []byte) (string, error) {
+	if len(b) != 16 {
+		return "", errors.New("invalid uuid length")
+	}
+	var u [16]byte
+	copy(u[:], b)
+	return String(u)
+}
+
+// ParseString parses a canonical UUID string into []byte (16 bytes).
+func ParseString(s string) ([]byte, error) {
+	if len(s) != 36 {
+		return nil, errors.New("invalid uuid string length")
+	}
+	buf := make([]byte, 16)
+	_, err := hex.Decode(buf[0:4], []byte(s[0:8]))
+	if err != nil {
+		return nil, err
+	}
+	_, err = hex.Decode(buf[4:6], []byte(s[9:13]))
+	if err != nil {
+		return nil, err
+	}
+	_, err = hex.Decode(buf[6:8], []byte(s[14:18]))
+	if err != nil {
+		return nil, err
+	}
+	_, err = hex.Decode(buf[8:10], []byte(s[19:23]))
+	if err != nil {
+		return nil, err
+	}
+	_, err = hex.Decode(buf[10:16], []byte(s[24:36]))
+	if err != nil {
+		return nil, err
+	}
+	return buf, nil
+}
+
+// ParsePathLikeString parses a UUID from a path-like value. This is useful for
+// URL params that may arrive escaped, wrapped in a full URL, or with a trailing slash.
+func ParsePathLikeString(raw string) ([]byte, error) {
+	for _, candidate := range candidateUUIDStrings(raw) {
+		if parsed, err := ParseString(candidate); err == nil {
+			return parsed, nil
+		}
+	}
+	return nil, errors.New("invalid uuid string")
+}
+
+func candidateUUIDStrings(raw string) []string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return nil
+	}
+
+	candidates := make([]string, 0, 6)
+	seen := make(map[string]struct{}, 6)
+	push := func(value string) {
+		value = strings.TrimSpace(value)
+		if value == "" {
+			return
+		}
+		if _, ok := seen[value]; ok {
+			return
+		}
+		seen[value] = struct{}{}
+		candidates = append(candidates, value)
+	}
+
+	push(raw)
+	if decoded, err := url.PathUnescape(raw); err == nil && decoded != raw {
+		push(decoded)
+	}
+	if decoded, err := url.QueryUnescape(raw); err == nil && decoded != raw {
+		push(decoded)
+	}
+
+	for i := 0; i < len(candidates); i++ {
+		value := candidates[i]
+		value = strings.TrimSuffix(value, "/")
+		push(value)
+
+		if idx := strings.IndexAny(value, "?#"); idx >= 0 {
+			push(value[:idx])
+		}
+		if idx := strings.LastIndex(value, "/"); idx >= 0 && idx+1 < len(value) {
+			push(value[idx+1:])
+		}
+		if idx := strings.LastIndex(value, "="); idx >= 0 && idx+1 < len(value) {
+			push(value[idx+1:])
+		}
+		for _, part := range strings.Split(value, "/") {
+			push(part)
+		}
+		for _, part := range strings.FieldsFunc(value, func(r rune) bool {
+			switch r {
+			case '/', '?', '#', '&', '=':
+				return true
+			default:
+				return false
+			}
+		}) {
+			push(part)
+		}
+	}
+
+	return candidates
+}
diff --git a/internal/shared/pkg/uuidv7/uuidv7_test.go b/internal/shared/pkg/uuidv7/uuidv7_test.go
new file mode 100644
index 0000000..484c18c
--- /dev/null
+++ b/internal/shared/pkg/uuidv7/uuidv7_test.go
@@ -0,0 +1,38 @@
+package uuidv7
+
+import "testing"
+
+func TestParsePathLikeString(t *testing.T) {
+	t.Parallel()
+
+	want := "019f1b8b-040d-7669-800c-d2ae52a53646"
+	cases := []string{
+		want,
+		want + "/",
+		"https://api-wfm-dev.mybit.co.id/wopi/files/" + want,
+		"https://api-wfm-dev.mybit.co.id/wopi/files/" + want + "/contents",
+		"https%3A%2F%2Fapi-wfm-dev.mybit.co.id%2Fwopi%2Ffiles%2F" + want,
+		"https%3A%2F%2Fapi-wfm-dev.mybit.co.id%2Fwopi%2Ffiles%2F" + want + "%2Fcontents",
+		"WOPISrc=https%3A%2F%2Fapi-wfm-dev.mybit.co.id%2Fwopi%2Ffiles%2F" + want,
+		"/wopi/files/" + want + "/contents",
+	}
+
+	for _, tc := range cases {
+		tc := tc
+		t.Run(tc, func(t *testing.T) {
+			t.Parallel()
+
+			parsed, err := ParsePathLikeString(tc)
+			if err != nil {
+				t.Fatalf("ParsePathLikeString(%q) error = %v", tc, err)
+			}
+			got, err := BytesToString(parsed)
+			if err != nil {
+				t.Fatalf("BytesToString error = %v", err)
+			}
+			if got != want {
+				t.Fatalf("ParsePathLikeString(%q) = %q, want %q", tc, got, want)
+			}
+		})
+	}
+}
diff --git a/internal/transport/http/dto/after_flight_inspection_dto.go b/internal/transport/http/dto/after_flight_inspection_dto.go
new file mode 100644
index 0000000..47eef48
--- /dev/null
+++ b/internal/transport/http/dto/after_flight_inspection_dto.go
@@ -0,0 +1,67 @@
+package dto
+
+import responsedto "wucher/internal/transport/http/dto/response"
+
+type AfterFlightInspectionAttributes struct {
+	ID                        string                                   `json:"id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	FlightInspectionID        string                                   `json:"flight_inspection_id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	FlightInspection          *FlightInspectionResource                `json:"flight_inspection,omitempty"`
+	Helicopter                *responsedto.HelicopterResource          `json:"helicopter,omitempty"`
+	MissionCode               string                                   `json:"mission_code,omitempty" example:"M-2026-001"`
+	MissionType               []string                                 `json:"mission_type,omitempty"`
+	TotalFlight               int                                      `json:"total_flight" example:"3"`
+	FlightDataCount           int                                      `json:"flight_data_count" example:"2"`
+	FlightTimeSeconds         int64                                    `json:"flight_time_seconds" example:"9000"`
+	Route                     []string                                 `json:"route"`
+	OilEngineNR1Checked       *string                                  `json:"oil_engine_nr1_checked" example:"1"`
+	OilEngineNR2Checked       *string                                  `json:"oil_engine_nr2_checked" example:"1"`
+	HydraulicLHChecked        *string                                  `json:"hydraulic_lh_checked" example:"1"`
+	HydraulicRHChecked        *string                                  `json:"hydraulic_rh_checked" example:"1"`
+	OilTransmissionMGBChecked *string                                  `json:"oil_transmission_mgb_checked" example:"1"`
+	OilTransmissionIGBChecked *string                                  `json:"oil_transmission_igb_checked" example:"1"`
+	OilTransmissionTGBChecked *string                                  `json:"oil_transmission_tgb_checked" example:"1"`
+	Note                      *string                                  `json:"note" example:"All checks completed"`
+	Total                     int                                      `json:"total" example:"3"`
+	Completed                 int                                      `json:"completed" example:"1"`
+	DoneFileChecklist         []AfterFlightInspectionFileChecklistItem `json:"done_file_checklist,omitempty"`
+	FileChecklist             []AfterFlightInspectionFileChecklistItem `json:"file_checklist"`
+	CreatedAt                 string                                   `json:"created_at,omitempty" example:"2026-04-09T05:00:00Z"`
+	UpdatedAt                 string                                   `json:"updated_at,omitempty" example:"2026-04-09T05:00:00Z"`
+}
+
+type AfterFlightInspectionFileChecklistItem struct {
+	HelicopterFileID string `json:"helicopter_file_id" example:"019d7000-aaaa-7bbb-8ccc-111111111111"`
+	FileName         string `json:"file_name,omitempty" example:"After Flight Checklist.pdf"`
+	DownloadURL      string `json:"download_url,omitempty" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."`
+	IsDone           bool   `json:"is_done" example:"false"`
+}
+
+type AfterFlightInspectionResource struct {
+	Type       string                          `json:"type" example:"after_flight_inspection"`
+	ID         string                          `json:"id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	Attributes AfterFlightInspectionAttributes `json:"attributes"`
+}
+
+type AfterFlightInspectionResponse struct {
+	Data AfterFlightInspectionResource `json:"data"`
+}
+
+type AfterFlightInspectionUpsertAttributes struct {
+	OilEngineNR1Checked       *string `json:"oil_engine_nr1_checked,omitempty"`
+	OilEngineNR2Checked       *string `json:"oil_engine_nr2_checked,omitempty"`
+	HydraulicLHChecked        *string `json:"hydraulic_lh_checked,omitempty"`
+	HydraulicRHChecked        *string `json:"hydraulic_rh_checked,omitempty"`
+	OilTransmissionMGBChecked *string `json:"oil_transmission_mgb_checked,omitempty"`
+	OilTransmissionIGBChecked *string `json:"oil_transmission_igb_checked,omitempty"`
+	OilTransmissionTGBChecked *string `json:"oil_transmission_tgb_checked,omitempty"`
+	Note                      *string `json:"note,omitempty"`
+}
+
+type AfterFlightInspectionUpsertData struct {
+	Type       string                                `json:"type" validate:"required,oneof=after_flight_inspection_upsert after_flight_inspection"`
+	Attributes AfterFlightInspectionUpsertAttributes `json:"attributes" validate:"required"`
+}
+
+type AfterFlightInspectionUpsertRequest struct {
+	Data AfterFlightInspectionUpsertData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/audit_dto.go b/internal/transport/http/dto/audit_dto.go
new file mode 100644
index 0000000..d65a45e
--- /dev/null
+++ b/internal/transport/http/dto/audit_dto.go
@@ -0,0 +1,35 @@
+package dto
+
+// JSON:API Audit DTOs
+
+type AuditLogAttributes struct {
+	RequestID   string      `json:"request_id,omitempty" example:"req-12345"`
+	ActorUserID string      `json:"actor_user_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Layer       string      `json:"layer" example:"api"`
+	Module      string      `json:"module" example:"reserve_ac"`
+	Action      string      `json:"action" example:"http.request"`
+	Method      string      `json:"method,omitempty" example:"GET"`
+	Path        string      `json:"path,omitempty" example:"/api/v1/users/get-all"`
+	StatusCode  int         `json:"status_code,omitempty" example:"200"`
+	Success     bool        `json:"success" example:"true"`
+	IP          string      `json:"ip,omitempty" example:"127.0.0.1"`
+	UserAgent   string      `json:"user_agent,omitempty" example:"Mozilla/5.0"`
+	Message     string      `json:"message,omitempty" example:"HTTP 200"`
+	Metadata    interface{} `json:"metadata,omitempty"`
+	CreatedAt   string      `json:"created_at,omitempty" example:"2026-03-11T12:00:00Z"`
+}
+
+type AuditLogResource struct {
+	Type       string             `json:"type" example:"audit_log"`
+	ID         string             `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes AuditLogAttributes `json:"attributes"`
+}
+
+type AuditLogListResponse struct {
+	Data []AuditLogResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/auth_dto.go b/internal/transport/http/dto/auth_dto.go
new file mode 100644
index 0000000..21b94df
--- /dev/null
+++ b/internal/transport/http/dto/auth_dto.go
@@ -0,0 +1,813 @@
+package dto
+
+import "encoding/json"
+
+// JSON:API Request/Response DTOs for Auth
+
+// Register
+type RegisterAttributes struct {
+	Email       string `json:"email" validate:"required,email" example:"user@example.com"`
+	Username    string `json:"username" validate:"required,min=3,max=100" example:"john.doe"`
+	Password    string `json:"password" validate:"required,min=8" example:"StrongP@ssw0rd"`
+	FirstName   string `json:"first_name" validate:"required" example:"John"`
+	LastName    string `json:"last_name" validate:"required" example:"Doe"`
+	MobilePhone string `json:"mobile_phone,omitempty" example:"+628123456789"`
+}
+
+type RegisterData struct {
+	Type       string             `json:"type" validate:"required,eq=auth_register" example:"auth_register"`
+	Attributes RegisterAttributes `json:"attributes" validate:"required"`
+}
+
+type RegisterRequest struct {
+	Data RegisterData `json:"data" validate:"required"`
+}
+
+// Invite user
+type InviteAttributes struct {
+	Email       string   `json:"email" validate:"required,email" example:"user@example.com"`
+	Username    string   `json:"username" validate:"required,min=3,max=100" example:"john.doe"`
+	FirstName   string   `json:"first_name" validate:"required" example:"John"`
+	LastName    string   `json:"last_name" validate:"required" example:"Doe"`
+	MobilePhone string   `json:"mobile_phone,omitempty" example:"+628123456789"`
+	RoleID      string   `json:"role_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	RoleIDs     []string `json:"role_ids,omitempty" example:"[\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d\",\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e\"]"`
+}
+
+type InviteData struct {
+	Type       string           `json:"type" validate:"required,eq=auth_invite" example:"auth_invite"`
+	Attributes InviteAttributes `json:"attributes" validate:"required"`
+}
+
+type InviteRequest struct {
+	Data InviteData `json:"data" validate:"required"`
+}
+
+// Set password from invite token
+type SetPasswordAttributes struct {
+	Token    string `json:"token" validate:"required" example:"kP8k2..."`
+	Password string `json:"password" validate:"required,min=8" example:"StrongP@ssw0rd"`
+}
+
+type SetPasswordData struct {
+	Type       string                `json:"type" validate:"required,eq=auth_set_password" example:"auth_set_password"`
+	Attributes SetPasswordAttributes `json:"attributes" validate:"required"`
+}
+
+type SetPasswordRequest struct {
+	Data SetPasswordData `json:"data" validate:"required"`
+}
+
+// Resend set-password invite
+type ResendSetPasswordInviteAttributes struct {
+	UserID string `json:"user_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type ResendSetPasswordInviteData struct {
+	Type       string                            `json:"type" validate:"required,eq=auth_resend_set_password" example:"auth_resend_set_password"`
+	Attributes ResendSetPasswordInviteAttributes `json:"attributes" validate:"required"`
+}
+
+type ResendSetPasswordInviteRequest struct {
+	Data ResendSetPasswordInviteData `json:"data" validate:"required"`
+}
+
+// Forgot password
+type ForgotPasswordAttributes struct {
+	Email string `json:"email" validate:"required,email" example:"user@example.com"`
+}
+
+type ForgotPasswordData struct {
+	Type       string                   `json:"type" validate:"required,eq=auth_forgot_password" example:"auth_forgot_password"`
+	Attributes ForgotPasswordAttributes `json:"attributes" validate:"required"`
+}
+
+type ForgotPasswordRequest struct {
+	Data ForgotPasswordData `json:"data" validate:"required"`
+}
+
+// Reset password
+type ResetPasswordAttributes struct {
+	Token           string `json:"token" validate:"required" example:"kP8k2..."`
+	NewPassword     string `json:"new_password" validate:"required,min=8" example:"StrongP@ssw0rd!LongPassphrase"`
+	ConfirmPassword string `json:"confirm_password" validate:"required,min=8" example:"StrongP@ssw0rd!LongPassphrase"`
+}
+
+type ResetPasswordData struct {
+	Type       string                  `json:"type" validate:"required,eq=auth_reset_password" example:"auth_reset_password"`
+	Attributes ResetPasswordAttributes `json:"attributes" validate:"required"`
+}
+
+type ResetPasswordRequest struct {
+	Data ResetPasswordData `json:"data" validate:"required"`
+}
+
+// Setup security PIN
+type SecurityPINSetupAttributes struct {
+	PIN        string `json:"pin" validate:"required,len=6,numeric" example:"123456"`
+	ConfirmPIN string `json:"confirm_pin" validate:"required,len=6,numeric" example:"123456"`
+}
+
+type SecurityPINSetupData struct {
+	Type       string                     `json:"type" validate:"required,eq=auth_pin_setup" example:"auth_pin_setup"`
+	Attributes SecurityPINSetupAttributes `json:"attributes" validate:"required"`
+}
+
+type SecurityPINSetupRequest struct {
+	Data SecurityPINSetupData `json:"data" validate:"required"`
+}
+
+type SecurityPINSetupResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_pin_setup"`
+		Attributes struct {
+			Configured bool `json:"configured" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// Verify security PIN
+type SecurityPINVerifyAttributes struct {
+	PIN    string `json:"pin" validate:"required,len=6,numeric" example:"123456"`
+	Action string `json:"action" validate:"required,uuid4" example:"a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"`
+}
+
+type SecurityPINVerifyData struct {
+	Type       string                      `json:"type" validate:"required,eq=auth_pin_verify" example:"auth_pin_verify"`
+	Attributes SecurityPINVerifyAttributes `json:"attributes" validate:"required"`
+}
+
+type SecurityPINVerifyRequest struct {
+	Data SecurityPINVerifyData `json:"data" validate:"required"`
+}
+
+type SecurityPINVerifyResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_pin_verify"`
+		Attributes struct {
+			Verified         bool   `json:"verified" example:"true"`
+			ActionToken      string `json:"action_token" example:"pinv_1234567890abcdef"`
+			ActionTokenTTLMS int64  `json:"action_token_ttl_ms" example:"900000"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// Change security PIN
+type SecurityPINChangeAttributes struct {
+	CurrentPIN string `json:"current_pin" validate:"required,len=6,numeric" example:"123456"`
+	NewPIN     string `json:"new_pin" validate:"required,len=6,numeric" example:"654321"`
+	ConfirmPIN string `json:"confirm_pin" validate:"required,len=6,numeric" example:"654321"`
+}
+
+type SecurityPINChangeData struct {
+	Type       string                      `json:"type" validate:"required,eq=auth_pin_change" example:"auth_pin_change"`
+	Attributes SecurityPINChangeAttributes `json:"attributes" validate:"required"`
+}
+
+type SecurityPINChangeRequest struct {
+	Data SecurityPINChangeData `json:"data" validate:"required"`
+}
+
+// Forgot security PIN
+type ForgotSecurityPINAttributes struct {
+	Email string `json:"email" validate:"required,email" example:"user@example.com"`
+}
+
+type ForgotSecurityPINData struct {
+	Type       string                      `json:"type" validate:"required,eq=auth_forgot_pin" example:"auth_forgot_pin"`
+	Attributes ForgotSecurityPINAttributes `json:"attributes" validate:"required"`
+}
+
+type ForgotSecurityPINRequest struct {
+	Data ForgotSecurityPINData `json:"data" validate:"required"`
+}
+
+// Request security PIN reset
+type RequestSecurityPINAttributes struct {
+	Method      string `json:"method,omitempty" example:"password"`
+	Password    string `json:"password,omitempty" example:"StrongP@ssw0rd"`
+	ReauthToken string `json:"reauth_token,omitempty" example:"sso_reauth_1234567890abcdef"`
+}
+
+type RequestSecurityPINData struct {
+	Type       string                       `json:"type" validate:"required,eq=auth_pin_request_reset" example:"auth_pin_request_reset"`
+	Attributes RequestSecurityPINAttributes `json:"attributes" validate:"required"`
+}
+
+type RequestSecurityPINRequest struct {
+	Data RequestSecurityPINData `json:"data" validate:"required"`
+}
+
+type RequestSecurityPINResetResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_pin_request_reset"`
+		Attributes struct {
+			Message string `json:"message" example:"If allowed, a security PIN reset link has been sent to your email."`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// Reset security PIN
+type ResetSecurityPINAttributes struct {
+	Token       string `json:"token,omitempty" example:"kP8k2..."`
+	Method      string `json:"method,omitempty" example:"password"`
+	Password    string `json:"password,omitempty" example:"StrongP@ssw0rd"`
+	ReauthToken string `json:"reauth_token,omitempty" example:"sso_reauth_1234567890abcdef"`
+	NewPIN      string `json:"new_pin" validate:"required,len=6,numeric" example:"123456"`
+	ConfirmPIN  string `json:"confirm_pin" validate:"required,len=6,numeric" example:"123456"`
+}
+
+type ResetSecurityPINData struct {
+	Type       string                     `json:"type" validate:"required,eq=auth_reset_pin" example:"auth_reset_pin"`
+	Attributes ResetSecurityPINAttributes `json:"attributes" validate:"required"`
+}
+
+type ResetSecurityPINRequest struct {
+	Data ResetSecurityPINData `json:"data" validate:"required"`
+}
+
+// Login
+type LoginAttributes struct {
+	Email    string `json:"email" validate:"required,email" example:"user@example.com"`
+	Password string `json:"password" validate:"required" example:"StrongP@ssw0rd"`
+}
+
+type LoginData struct {
+	Type       string          `json:"type" validate:"required,eq=auth_login" example:"auth_login"`
+	Attributes LoginAttributes `json:"attributes" validate:"required"`
+}
+
+type LoginRequest struct {
+	Data LoginData `json:"data" validate:"required"`
+}
+
+// Exchange frontend Microsoft token result into backend session tokens
+type ExchangeIDTokenClaims struct {
+	Aud               string `json:"aud,omitempty" example:"12345678-1234-1234-1234-123456789012"`
+	Iss               string `json:"iss,omitempty" example:"https://login.microsoftonline.com/abc-tenant-id/v2.0"`
+	Iat               int64  `json:"iat,omitempty" example:"1715600000"`
+	Nbf               int64  `json:"nbf,omitempty" example:"1715600000"`
+	Exp               int64  `json:"exp,omitempty" example:"1715603600"`
+	Name              string `json:"name,omitempty" example:"Andrio Effendi"`
+	PreferredUsername string `json:"preferred_username,omitempty" example:"andrio@mybit-innovation.com"`
+	Email             string `json:"email,omitempty" example:"andrio@mybit-innovation.com"`
+	OID               string `json:"oid,omitempty" example:"00000000-0000-0000-1234-567890abcdef"`
+	Sub               string `json:"sub,omitempty" example:"AbCdEfGhIjKlMnOpQrStUvWxYz"`
+	TID               string `json:"tid,omitempty" example:"abc-tenant-id"`
+	Ver               string `json:"ver,omitempty" example:"2.0"`
+}
+
+type ExchangeAttributes struct {
+	AccessToken   string                `json:"access_token" validate:"required" example:"eyJ0eXAiOiJKV1Qi..."`
+	IDToken       string                `json:"id_token" validate:"required" example:"eyJ0eXAiOiJKV1Qi..."`
+	IDTokenClaims ExchangeIDTokenClaims `json:"id_token_claims"`
+}
+
+type ExchangeData struct {
+	Type       string             `json:"type" validate:"required,eq=auth_exchange" example:"auth_exchange"`
+	Attributes ExchangeAttributes `json:"attributes" validate:"required"`
+}
+
+type ExchangeRequest struct {
+	Data ExchangeData `json:"data" validate:"required"`
+}
+
+func (c ExchangeIDTokenClaims) ToMap() map[string]any {
+	out := map[string]any{}
+	if c.Aud != "" {
+		out["aud"] = c.Aud
+	}
+	if c.Iss != "" {
+		out["iss"] = c.Iss
+	}
+	if c.Iat > 0 {
+		out["iat"] = c.Iat
+	}
+	if c.Nbf > 0 {
+		out["nbf"] = c.Nbf
+	}
+	if c.Exp > 0 {
+		out["exp"] = c.Exp
+	}
+	if c.Name != "" {
+		out["name"] = c.Name
+	}
+	if c.PreferredUsername != "" {
+		out["preferred_username"] = c.PreferredUsername
+	}
+	if c.Email != "" {
+		out["email"] = c.Email
+	}
+	if c.OID != "" {
+		out["oid"] = c.OID
+	}
+	if c.Sub != "" {
+		out["sub"] = c.Sub
+	}
+	if c.TID != "" {
+		out["tid"] = c.TID
+	}
+	if c.Ver != "" {
+		out["ver"] = c.Ver
+	}
+	return out
+}
+
+// WebAuthn register begin
+type WebAuthnRegisterBeginData struct {
+	Type string `json:"type" validate:"required,eq=auth_webauthn_register_begin" example:"auth_webauthn_register_begin"`
+}
+
+type WebAuthnRegisterBeginRequest struct {
+	Data WebAuthnRegisterBeginData `json:"data" validate:"required"`
+}
+
+// WebAuthn register finish
+type WebAuthnRegisterFinishAttributes struct {
+	ChallengeToken string          `json:"challenge_token" validate:"required" example:"kP8k2..."`
+	Credential     json.RawMessage `json:"credential" validate:"required"`
+	Name           string          `json:"name,omitempty" validate:"omitempty,max=100" example:"MacBook Touch ID"`
+}
+
+type WebAuthnRegisterFinishData struct {
+	Type       string                           `json:"type" validate:"required,eq=auth_webauthn_register_finish" example:"auth_webauthn_register_finish"`
+	Attributes WebAuthnRegisterFinishAttributes `json:"attributes" validate:"required"`
+}
+
+type WebAuthnRegisterFinishRequest struct {
+	Data WebAuthnRegisterFinishData `json:"data" validate:"required"`
+}
+
+// WebAuthn login begin
+type WebAuthnLoginBeginAttributes struct {
+	Email string `json:"email" validate:"required,email" example:"user@example.com"`
+}
+
+type WebAuthnLoginBeginData struct {
+	Type       string                       `json:"type" validate:"required,eq=auth_webauthn_login_begin" example:"auth_webauthn_login_begin"`
+	Attributes WebAuthnLoginBeginAttributes `json:"attributes" validate:"required"`
+}
+
+type WebAuthnLoginBeginRequest struct {
+	Data WebAuthnLoginBeginData `json:"data" validate:"required"`
+}
+
+// WebAuthn login finish
+type WebAuthnLoginFinishAttributes struct {
+	ChallengeToken string          `json:"challenge_token" validate:"required" example:"kP8k2..."`
+	Credential     json.RawMessage `json:"credential" validate:"required"`
+}
+
+type WebAuthnLoginFinishData struct {
+	Type       string                        `json:"type" validate:"required,eq=auth_webauthn_login_finish" example:"auth_webauthn_login_finish"`
+	Attributes WebAuthnLoginFinishAttributes `json:"attributes" validate:"required"`
+}
+
+type WebAuthnLoginFinishRequest struct {
+	Data WebAuthnLoginFinishData `json:"data" validate:"required"`
+}
+
+// Sensitive-action re-auth attributes
+type ReauthAttributes struct {
+	Method   string `json:"method" validate:"required,oneof=pin password" example:"pin"`
+	Password string `json:"password,omitempty" validate:"omitempty,min=1" example:"StrongP@ssw0rd"`
+}
+
+// WebAuthn reset setup
+type WebAuthnResetSetupData struct {
+	Type       string           `json:"type" validate:"required,eq=auth_webauthn_reset_setup" example:"auth_webauthn_reset_setup"`
+	Attributes ReauthAttributes `json:"attributes" validate:"required"`
+}
+
+type WebAuthnResetSetupRequest struct {
+	Data WebAuthnResetSetupData `json:"data" validate:"required"`
+}
+
+type WebAuthnResetSetupResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_webauthn_reset_setup"`
+		Attributes struct {
+			Reset bool `json:"reset" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// Login response when TOTP required
+type LoginTOTPRequiredResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_totp_required"`
+		Attributes struct {
+			RequiresTOTP              bool   `json:"requires_totp" example:"true"`
+			ChallengeToken            string `json:"challenge_token" example:"kP8k2..."`
+			TOTPEnabled               bool   `json:"totp_enabled" example:"true"`
+			EmailOTPEnabled           bool   `json:"email_otp_enabled" example:"false"`
+			EmailOTPChallengeToken    string `json:"email_otp_challenge_token,omitempty" example:"qA9j1..."`
+			EmailOTPResendCooldownSec int    `json:"email_otp_resend_cooldown_seconds,omitempty" example:"60"`
+			EmailOTPMaxResendPerHour  int    `json:"email_otp_max_resend_per_hour,omitempty" example:"5"`
+			WebAuthnConfigured        bool   `json:"webauthn_configured" example:"false"`
+			LinkedSSO                 bool   `json:"linked_sso" example:"false"`
+			PINConfigured             bool   `json:"pin_configured" example:"false"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type LoginEmailOTPRequiredResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_email_otp_required"`
+		Attributes struct {
+			RequiresEmailOTP      bool   `json:"requires_email_otp" example:"true"`
+			ChallengeToken        string `json:"challenge_token" example:"kP8k2..."`
+			ResendCooldownSeconds int    `json:"resend_cooldown_seconds" example:"60"`
+			MaxResendPerHour      int    `json:"max_resend_per_hour" example:"5"`
+			RequiresTOTPSetup     bool   `json:"requires_totp_setup" example:"true"`
+			WebAuthnConfigured    bool   `json:"webauthn_configured" example:"false"`
+			LinkedSSO             bool   `json:"linked_sso" example:"false"`
+			PINConfigured         bool   `json:"pin_configured" example:"false"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type EmailOTPSendAttributes struct {
+	ChallengeToken string `json:"challenge_token" validate:"required" example:"kP8k2..."`
+}
+
+type EmailOTPSendData struct {
+	Type       string                 `json:"type" validate:"required,eq=auth_email_otp_send" example:"auth_email_otp_send"`
+	Attributes EmailOTPSendAttributes `json:"attributes" validate:"required"`
+}
+
+type EmailOTPSendRequest struct {
+	Data EmailOTPSendData `json:"data" validate:"required"`
+}
+
+type EmailOTPVerifyAttributes struct {
+	ChallengeToken string `json:"challenge_token" validate:"required" example:"kP8k2..."`
+	Code           string `json:"code" validate:"required,len=6,numeric" example:"123456"`
+}
+
+type EmailOTPVerifyData struct {
+	Type       string                   `json:"type" validate:"required,eq=auth_email_otp_verify" example:"auth_email_otp_verify"`
+	Attributes EmailOTPVerifyAttributes `json:"attributes" validate:"required"`
+}
+
+type EmailOTPVerifyRequest struct {
+	Data EmailOTPVerifyData `json:"data" validate:"required"`
+}
+
+type EmailOTPSendResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_email_otp_send"`
+		Attributes struct {
+			Sent bool `json:"sent" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type EmailOTPVerifyResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_email_otp_verify"`
+		Attributes struct {
+			Verified          bool `json:"verified" example:"true"`
+			RequiresTOTPSetup bool `json:"requires_totp_setup" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// Email verify response
+type VerifyEmailResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_verify_email"`
+		Attributes struct {
+			Verified bool `json:"verified" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// Microsoft login
+type MicrosoftLoginResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_microsoft_url"`
+		Attributes struct {
+			URL         string `json:"url" example:"https://login.microsoftonline.com/..."`
+			RedirectURL string `json:"redirect_url" example:"https://login.microsoftonline.com/..."`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// Microsoft callback
+type MicrosoftCallbackResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_identity"`
+		ID         string `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+		Attributes struct {
+			Provider        string `json:"provider" example:"microsoft"`
+			ProviderSubject string `json:"provider_subject" example:"00000000-0000-0000-0000-000000000000"`
+			Email           string `json:"email" example:"user@example.com"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type SSOLinkAttributes struct {
+	Provider string `json:"provider" validate:"required,eq=microsoft" example:"microsoft"`
+	Code     string `json:"code" validate:"required" example:"0.AXkA..."`
+}
+
+type SSOLinkData struct {
+	Type       string            `json:"type" validate:"required,eq=auth_sso_link" example:"auth_sso_link"`
+	Attributes SSOLinkAttributes `json:"attributes" validate:"required"`
+}
+
+type SSOLinkRequest struct {
+	Data SSOLinkData `json:"data" validate:"required"`
+}
+
+type SSOLinkResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_sso_link"`
+		Attributes struct {
+			Provider        string `json:"provider" example:"microsoft"`
+			ProviderSubject string `json:"provider_subject" example:"00000000-0000-0000-0000-000000000000"`
+			Email           string `json:"email" example:"user@example.com"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type SSOUnlinkAttributes struct {
+	Provider string `json:"provider" validate:"required,eq=microsoft" example:"microsoft"`
+}
+
+type SSOUnlinkData struct {
+	Type       string              `json:"type" validate:"required,eq=auth_sso_unlink" example:"auth_sso_unlink"`
+	Attributes SSOUnlinkAttributes `json:"attributes" validate:"required"`
+}
+
+type SSOUnlinkRequest struct {
+	Data SSOUnlinkData `json:"data" validate:"required"`
+}
+
+type SSOUnlinkResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_sso_unlink"`
+		Attributes struct {
+			Provider string `json:"provider" example:"microsoft"`
+			Unlinked bool   `json:"unlinked" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// WebAuthn begin response
+type WebAuthnBeginResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_webauthn_register_options"`
+		Attributes struct {
+			ChallengeToken string                 `json:"challenge_token" example:"kP8k2..."`
+			ChallengeTTLMS int64                  `json:"challenge_ttl_ms" example:"300000"`
+			PublicKey      map[string]interface{} `json:"public_key"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// TOTP setup
+type TOTPSetupAttributes struct {
+	UserID string `json:"user_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Email  string `json:"email" validate:"required,email" example:"user@example.com"`
+}
+
+type TOTPSetupData struct {
+	Type       string              `json:"type" validate:"required,eq=auth_totp_setup" example:"auth_totp_setup"`
+	Attributes TOTPSetupAttributes `json:"attributes" validate:"required"`
+}
+
+type TOTPSetupRequest struct {
+	Data TOTPSetupData `json:"data" validate:"required"`
+}
+
+type TOTPSetupResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_totp_setup"`
+		Attributes struct {
+			Secret     string `json:"secret" example:"JBSWY3DPEHPK3PXP"`
+			OtpauthURL string `json:"otpauth_url" example:"otpauth://totp/Wucher:user@example.com?..."`
+			Issuer     string `json:"issuer" example:"Wucher"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// TOTP verify
+type TOTPVerifyAttributes struct {
+	ChallengeToken string `json:"challenge_token" validate:"required" example:"kP8k2..."`
+	Code           string `json:"code" validate:"required,len=6" example:"123456"`
+}
+
+type TOTPVerifyData struct {
+	Type       string               `json:"type" validate:"required,eq=auth_totp_verify" example:"auth_totp_verify"`
+	Attributes TOTPVerifyAttributes `json:"attributes" validate:"required"`
+}
+
+type TOTPVerifyRequest struct {
+	Data TOTPVerifyData `json:"data" validate:"required"`
+}
+
+// TOTP confirm (enable)
+type TOTPConfirmAttributes struct {
+	UserID string `json:"user_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Code   string `json:"code" validate:"required,len=6" example:"123456"`
+}
+
+type TOTPConfirmData struct {
+	Type       string                `json:"type" validate:"required,eq=auth_totp_confirm" example:"auth_totp_confirm"`
+	Attributes TOTPConfirmAttributes `json:"attributes" validate:"required"`
+}
+
+type TOTPConfirmRequest struct {
+	Data TOTPConfirmData `json:"data" validate:"required"`
+}
+
+// Disable TOTP
+type TOTPDisableAttributes struct {
+	UserID string `json:"user_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type TOTPDisableData struct {
+	Type       string                `json:"type" validate:"required,eq=auth_totp_disable" example:"auth_totp_disable"`
+	Attributes TOTPDisableAttributes `json:"attributes" validate:"required"`
+}
+
+type TOTPDisableRequest struct {
+	Data TOTPDisableData `json:"data" validate:"required"`
+}
+
+// TOTP reset setup
+type TOTPResetSetupData struct {
+	Type       string           `json:"type" validate:"required,eq=auth_totp_reset_setup" example:"auth_totp_reset_setup"`
+	Attributes ReauthAttributes `json:"attributes" validate:"required"`
+}
+
+type TOTPResetSetupRequest struct {
+	Data TOTPResetSetupData `json:"data" validate:"required"`
+}
+
+type TOTPResetSetupResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_totp_reset_setup"`
+		Attributes struct {
+			Reset bool `json:"reset" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type AuthSessionItem struct {
+	ID           string `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeviceName   string `json:"device_name" example:"Chrome on macOS"`
+	UserAgent    string `json:"user_agent,omitempty" example:"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ..."`
+	IPAddress    string `json:"ip_address,omitempty" example:"127.0.0.1"`
+	CreatedAt    string `json:"created_at" example:"2026-03-13T12:00:00Z"`
+	LastActiveAt string `json:"last_active_at" example:"2026-03-13T12:10:00Z"`
+	ActiveNow    bool   `json:"active_now" example:"true"`
+}
+
+type AuthSessionsResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_sessions"`
+		Attributes struct {
+			Sessions []AuthSessionItem `json:"sessions"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type AuthSessionDeleteResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_session_delete"`
+		Attributes struct {
+			Deleted bool `json:"deleted" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// Update timezone
+type TimezoneUpdateAttributes struct {
+	Timezone string `json:"timezone" validate:"required" example:"Asia/Jakarta"`
+}
+
+type TimezoneUpdateData struct {
+	Type       string                   `json:"type" validate:"required,eq=auth_timezone_update" example:"auth_timezone_update"`
+	Attributes TimezoneUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type TimezoneUpdateRequest struct {
+	Data TimezoneUpdateData `json:"data" validate:"required"`
+}
+
+// Token response
+type TokenResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"auth_tokens"`
+		Attributes struct {
+			AccessTokenExpiresIn  int64 `json:"access_expires_in" example:"900"`
+			RefreshTokenExpiresIn int64 `json:"refresh_expires_in" example:"2592000"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// User response
+type UserAttributes struct {
+	Email                  string     `json:"email" example:"user@example.com"`
+	Username               string     `json:"username,omitempty" example:"john.doe"`
+	FirstName              string     `json:"first_name" example:"John"`
+	LastName               string     `json:"last_name" example:"Doe"`
+	MobilePhone            string     `json:"mobile_phone,omitempty" example:"+628123456789"`
+	Timezone               string     `json:"timezone" example:"Asia/Jakarta"`
+	ProfilePicture         *UserImage `json:"profile_picture,omitempty"`
+	RoleID                 string     `json:"role_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	RoleIDs                []string   `json:"role_ids,omitempty" example:"[\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d\",\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e\"]"`
+	CreatedBy              string     `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	EmailVerifiedAt        string     `json:"email_verified_at,omitempty" example:"2026-02-05T10:00:00Z"`
+	TOTPEnabled            bool       `json:"totp_enabled" example:"false"`
+	IsPreviouslyConfigured bool       `json:"is_previously_configured" example:"false"`
+	WebAuthnConfigured     bool       `json:"webauthn_configured" example:"false"`
+	LinkedSSO              bool       `json:"linked_sso" example:"false"`
+	PINConfigured          bool       `json:"pin_configured" example:"false"`
+	Role                   RoleMini   `json:"role,omitempty"`
+	Roles                  []RoleMini `json:"roles,omitempty"`
+}
+
+type UserImage struct {
+	UUID                 string `json:"uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f"`
+	DownloadURL          string `json:"download_url,omitempty" example:"https://example.com/presigned-url"`
+	ThumbnailDownloadURL string `json:"thumbnail_download_url,omitempty" example:"https://example.com/presigned-thumb-url"`
+	OriginalSizeBytes    *int64 `json:"original_size_bytes,omitempty" example:"1024000"`
+}
+
+type UserFoto struct {
+	UUID                 string `json:"uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f"`
+	DownloadURL          string `json:"download_url,omitempty" example:"https://storage.example.com/base/lude.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=abc123"`
+	ThumbnailDownloadURL string `json:"thumbnail_download_url,omitempty" example:"https://storage.example.com/base/lude.thumb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=abc123"`
+	OriginalSizeBytes    *int64 `json:"original_size_bytes,omitempty" example:"1024000"`
+}
+
+type RoleMini struct {
+	ID          string `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name        string `json:"name" example:"admin"`
+	Description string `json:"description,omitempty" example:"Full access to all resources."`
+}
+
+type PermissionMini struct {
+	ID          string `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9a"`
+	Name        string `json:"name" example:"View Users"`
+	Key         string `json:"key" example:"users.read"`
+	Description string `json:"description,omitempty" example:"Permission to view users."`
+	RequiresPIN bool   `json:"requires_pin" example:"false"`
+}
+
+// Auth current-user payload used by /auth/login and /auth/me endpoints.
+type AuthCurrentUserAttributes struct {
+	Email                  string                    `json:"email" example:"user@example.com"`
+	EmailSSO               string                    `json:"email_sso,omitempty" example:"user.sso@example.com"`
+	FirstName              string                    `json:"first_name" example:"John"`
+	LastName               string                    `json:"last_name" example:"Doe"`
+	MobilePhone            string                    `json:"mobile_phone,omitempty" example:"+628123456789"`
+	Timezone               string                    `json:"timezone" example:"Asia/Jakarta"`
+	Foto                   *UserFoto                 `json:"foto,omitempty"`
+	EmailVerifiedAt        string                    `json:"email_verified_at,omitempty" example:"2026-02-05T10:00:00Z"`
+	Roles                  []RoleMini                `json:"roles,omitempty"`
+	Permissions            []PermissionMini          `json:"permissions,omitempty"`
+	PermissionModules      []PermissionGroupResource `json:"permission_modules,omitempty"`
+	TOTPEnabled            bool                      `json:"totp_enabled" example:"false"`
+	IsPreviouslyConfigured bool                      `json:"is_previously_configured" example:"false"`
+	WebAuthnConfigured     bool                      `json:"webauthn_configured" example:"false"`
+	LinkedSSO              bool                      `json:"linked_sso" example:"false"`
+	PINConfigured          bool                      `json:"pin_configured" example:"false"`
+	PINBlocked             bool                      `json:"pin_blocked" example:"false"`
+	LoginMethod            string                    `json:"login_method,omitempty" example:"email"`
+	AuthProvider           string                    `json:"auth_provider,omitempty" example:"email"`
+	MicrosoftScope         string                    `json:"microsoft_scope,omitempty" example:"openid profile email offline_access User.Read"`
+	DULBases               []DULBase                 `json:"dul_bases,omitempty"`
+}
+
+type AuthCurrentUserResponse struct {
+	Data struct {
+		Type       string                    `json:"type" example:"user"`
+		ID         string                    `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+		Attributes AuthCurrentUserAttributes `json:"attributes"`
+	} `json:"data"`
+}
+
+type UserResponse struct {
+	Data struct {
+		Type       string         `json:"type" example:"user"`
+		ID         string         `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+		Attributes UserAttributes `json:"attributes"`
+	} `json:"data"`
+}
+
+// Error response for Swagger
+type ErrorResponse struct {
+	Errors []struct {
+		Status string `json:"status" example:"422"`
+		Title  string `json:"title" example:"Validation error"`
+		Detail string `json:"detail" example:"email is required"`
+		Source struct {
+			Pointer string `json:"pointer" example:"/data/attributes/email"`
+		} `json:"source"`
+	} `json:"errors"`
+}
diff --git a/internal/transport/http/dto/base_dto.go b/internal/transport/http/dto/base_dto.go
new file mode 100644
index 0000000..e777d85
--- /dev/null
+++ b/internal/transport/http/dto/base_dto.go
@@ -0,0 +1,569 @@
+package dto
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"wucher/internal/domain/base"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+// JSON:API Base DTOs
+
+type BaseAttributes struct {
+	BaseName                           string                     `json:"base" example:"Lude"`
+	BaseAbbreviation                   string                     `json:"base_abbreviation,omitempty" example:"LOIG"`
+	BaseCategory                       string                     `json:"base_category,omitempty" example:"regular" enums:"regular,hems"`
+	Address                            string                     `json:"address,omitempty" example:"Lude Airfield"`
+	Latitude                           float64                    `json:"latitude" example:"47.3769"`
+	Longitude                          float64                    `json:"longitude" example:"8.5417"`
+	LandlineNumber                     string                     `json:"landline_number,omitempty" example:"+62-21-1234"`
+	MobileNumber                       string                     `json:"mobile_number,omitempty" example:"+62-812-1234"`
+	Email                              string                     `json:"email,omitempty" example:"lude@wucher.local"`
+	SortKey                            *int                       `json:"sortkey" example:"1"`
+	SMSAlert                           bool                       `json:"sms_alert" example:"false"`
+	Checklist                          bool                       `json:"checklist" example:"false"`
+	LegTime                            string                     `json:"leg_time,omitempty" example:"00:20"`
+	DefaultStartTimeType               string                     `json:"default_start_time_type,omitempty" example:"FIXED" enums:"FIXED,BMCT,ECET"`
+	DefaultEndTimeType                 string                     `json:"default_end_time_type,omitempty" example:"FIXED" enums:"FIXED,BMCT,ECET"`
+	ShiftTime                          BaseShiftTime              `json:"shift_time"`
+	UTC                                string                     `json:"utc" example:"0"`
+	Foto                               *BaseFoto                  `json:"foto,omitempty"`
+	Dry                                bool                       `json:"dry" example:"false"`
+	ControlCenter                      bool                       `json:"control_center" example:"false"`
+	DUL                                bool                       `json:"dul" example:"false"`
+	Notes                              string                     `json:"notes,omitempty" example:"Main base"`
+	HEMSEDCContactIDs []string      `json:"hems_edc_contact_ids,omitempty"`
+	HEMSEDCs          []BaseContact `json:"hems_edc,omitempty"`
+	MedPaxContactIDs  []string      `json:"med_pax_contact_ids,omitempty"`
+	MedPax            []BaseContact `json:"med_pax,omitempty"`
+	ResponsiblePilotContactIDs         []string                   `json:"responsible_pilot_contact_ids,omitempty"`
+	ResponsiblePilots                  []BaseContact              `json:"responsible_pilots,omitempty"`
+	OperationalShiftTimes              []BaseOperationalShiftTime `json:"operational_shift_times,omitempty"`
+	IsActive                           bool                       `json:"is_active" example:"true"`
+	CreatedBy                          string                     `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedBy                          string                     `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt                          string                     `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt                          string                     `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedAt                          string                     `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z" swaggerignore:"true"`
+	DeletedBy                          string                     `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d" swaggerignore:"true"`
+}
+
+type BaseContact struct {
+	ID        string `json:"id"`
+	FirstName string `json:"first_name,omitempty"`
+	LastName  string `json:"last_name,omitempty"`
+}
+
+type BaseShiftTime struct {
+	Start string `json:"start,omitempty" example:"06:00"`
+	End   string `json:"end,omitempty" example:"21:00"`
+}
+
+type BaseOperationalShiftTime struct {
+	DateStart     string        `json:"date_start" example:"2026-04-12"`
+	DateEnd       string        `json:"date_end" example:"2026-04-12"`
+	StartTimeType string        `json:"start_time_type,omitempty" example:"FIXED" enums:"FIXED,BMCT,ECET"`
+	EndTimeType   string        `json:"end_time_type,omitempty" example:"FIXED" enums:"FIXED,BMCT,ECET"`
+	ShiftTime     BaseShiftTime `json:"shift_time"`
+}
+
+type BaseFoto struct {
+	UUID                 string `json:"uuid" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DownloadURL          string `json:"download_url" example:"https://storage.example.com/base/lude.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=abc123"`
+	ThumbnailDownloadURL string `json:"thumbnail_download_url,omitempty" example:"https://storage.example.com/base/lude.thumb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=abc123"`
+	OriginalSizeBytes    *int64 `json:"original_size_bytes,omitempty" example:"1024000"`
+}
+
+type BaseResource struct {
+	Type       string         `json:"type" example:"base"`
+	ID         string         `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes BaseAttributes `json:"attributes"`
+}
+
+type BaseResponse struct {
+	Data BaseResource `json:"data"`
+}
+
+type BaseListResponse struct {
+	Data []BaseResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type BaseDataTableResponse struct {
+	Data []BaseResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type BaseCreateAttributes struct {
+	BaseName                           string                     `json:"base" validate:"required" example:"Lude"`
+	BaseAbbreviation                   *string                    `json:"base_abbreviation,omitempty" example:"LOIG"`
+	BaseCategory                       *string                    `json:"base_category,omitempty" example:"regular" enums:"regular,hems"`
+	Address                            *string                    `json:"address,omitempty" example:"Lude Airfield"`
+	Latitude                           *float64                   `json:"latitude" validate:"required,gte=-90,lte=90" example:"47.3769"`
+	Longitude                          *float64                   `json:"longitude" validate:"required,gte=-180,lte=180" example:"8.5417"`
+	LandlineNumber                     *string                    `json:"landline_number,omitempty" example:"+62-21-1234"`
+	MobileNumber                       *string                    `json:"mobile_number,omitempty" example:"+62-812-1234"`
+	Email                              *string                    `json:"email,omitempty" example:"lude@wucher.local"`
+	SortKey                            *int                       `json:"sortkey" example:"1"`
+	SMSAlert                           *bool                      `json:"sms_alert,omitempty" example:"false"`
+	Checklist                          *bool                      `json:"checklist,omitempty" example:"false"`
+	LegTime                            *string                    `json:"leg_time,omitempty" example:"00:20"`
+	DefaultStartTimeType               *string                    `json:"default_start_time_type,omitempty" example:"FIXED" enums:"FIXED,BMCT,ECET"`
+	DefaultEndTimeType                 *string                    `json:"default_end_time_type,omitempty" example:"FIXED" enums:"FIXED,BMCT,ECET"`
+	ShiftTime                          *BaseShiftTime             `json:"shift_time,omitempty"`
+	DefaultShiftStart                  *string                    `json:"default_shift_start,omitempty" example:"06:00:00"`
+	DefaultShiftEnd                    *string                    `json:"default_shift_end,omitempty" example:"21:00:00"`
+	DefaultShiftTime                   *string                    `json:"default_shift_time,omitempty" example:"12:00"`
+	UTC                                *string                    `json:"utc,omitempty" example:"0"`
+	FileUUID                           *string                    `json:"file_uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"`
+	Dry                                *bool                      `json:"dry,omitempty" example:"false"`
+	ControlCenter                      *bool                      `json:"control_center,omitempty" example:"false"`
+	DUL                                *bool                      `json:"dul,omitempty" example:"false"`
+	Notes                              *string                    `json:"notes,omitempty" example:"Main base"`
+	HEMSEDCContactIDs []string `json:"hems_edc_contact_ids,omitempty"`
+	MedPaxContactIDs  []string `json:"med_pax_contact_ids,omitempty"`
+	ResponsiblePilotContactIDs         []string                   `json:"responsible_pilot_contact_ids,omitempty"`
+	OperationalShiftTimes              []BaseOperationalShiftTime `json:"operational_shift_times,omitempty"`
+	IsActive                           *bool                      `json:"is_active,omitempty" example:"true"`
+	CreatedBy                          *string                    `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d" swaggerignore:"true"`
+	UpdatedBy                          *string                    `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d" swaggerignore:"true"`
+}
+
+type BaseCreateData struct {
+	Type       string               `json:"type" validate:"required,oneof=base_create base hems_base" enums:"base" example:"base"`
+	Attributes BaseCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type BaseCreateRequest struct {
+	Data BaseCreateData `json:"data" validate:"required"`
+}
+
+type BaseUpdateAttributes struct {
+	BaseName                           *string                    `json:"base,omitempty" example:"Lude"`
+	BaseAbbreviation                   *string                    `json:"base_abbreviation,omitempty" example:"LOIG"`
+	BaseCategory                       *string                    `json:"base_category,omitempty" example:"regular" enums:"regular,hems"`
+	Address                            *string                    `json:"address,omitempty" example:"Lude Airfield"`
+	Latitude                           *float64                   `json:"latitude,omitempty" validate:"omitempty,gte=-90,lte=90" example:"47.3769"`
+	Longitude                          *float64                   `json:"longitude,omitempty" validate:"omitempty,gte=-180,lte=180" example:"8.5417"`
+	LandlineNumber                     *string                    `json:"landline_number,omitempty" example:"+62-21-1234"`
+	MobileNumber                       *string                    `json:"mobile_number,omitempty" example:"+62-812-1234"`
+	Email                              *string                    `json:"email,omitempty" example:"lude@wucher.local"`
+	SortKey                            NullInt                    `json:"sortkey,omitempty" swaggertype:"integer" example:"1"`
+	SMSAlert                           *bool                      `json:"sms_alert,omitempty" example:"false"`
+	Checklist                          *bool                      `json:"checklist,omitempty" example:"false"`
+	LegTime                            *string                    `json:"leg_time,omitempty" example:"00:20"`
+	DefaultStartTimeType               *string                    `json:"default_start_time_type,omitempty" example:"FIXED" enums:"FIXED,BMCT,ECET"`
+	DefaultEndTimeType                 *string                    `json:"default_end_time_type,omitempty" example:"FIXED" enums:"FIXED,BMCT,ECET"`
+	DefaultShiftStart                  *string                    `json:"default_shift_start,omitempty" example:"06:00:00"`
+	DefaultShiftEnd                    *string                    `json:"default_shift_end,omitempty" example:"21:00:00"`
+	DefaultShiftTime                   *string                    `json:"default_shift_time,omitempty" example:"12:00"`
+	ShiftTime                          *BaseShiftTime             `json:"shift_time,omitempty"`
+	UTC                                *string                    `json:"utc,omitempty" example:"0"`
+	FileUUID                           *string                    `json:"file_uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"`
+	Dry                                *bool                      `json:"dry,omitempty" example:"false"`
+	ControlCenter                      *bool                      `json:"control_center,omitempty" example:"false"`
+	DUL                                *bool                      `json:"dul,omitempty" example:"false"`
+	Notes                              *string                    `json:"notes,omitempty" example:"Main base"`
+	HEMSEDCContactIDs *[]string `json:"hems_edc_contact_ids,omitempty"`
+	MedPaxContactIDs  *[]string `json:"med_pax_contact_ids,omitempty"`
+	ResponsiblePilotContactIDs         *[]string                  `json:"responsible_pilot_contact_ids,omitempty"`
+	OperationalShiftTimes              []BaseOperationalShiftTime `json:"operational_shift_times,omitempty"`
+	IsActive                           *bool                      `json:"is_active,omitempty" example:"true"`
+	CreatedBy                          *string                    `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d" swaggerignore:"true"`
+	UpdatedBy                          *string                    `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d" swaggerignore:"true"`
+}
+
+type BaseUpdateData struct {
+	Type       string               `json:"type" validate:"required,oneof=base_update base hems_base" enums:"base_update" example:"base_update"`
+	ID         string               `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes BaseUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type BaseUpdateRequest struct {
+	Data BaseUpdateData `json:"data" validate:"required"`
+}
+
+type BaseDeleteAttributes struct {
+	Deleted bool `json:"deleted" example:"true"`
+}
+
+type BaseDeleteResource struct {
+	Type       string               `json:"type" example:"base_delete"`
+	ID         string               `json:"id" example:"019d6b10-a385-7e9e-a553-8e892bcec0ef"`
+	Attributes BaseDeleteAttributes `json:"attributes"`
+}
+
+type BaseDeleteResponse struct {
+	Data BaseDeleteResource `json:"data"`
+}
+
+type BaseResponseMappingInput struct {
+	ResourceType                       string
+	BaseCategory                       string
+	ID                                 string
+	DefaultStartTimeType               string
+	DefaultEndTimeType                 string
+	ShiftTime                          BaseShiftTime
+	Foto                               *BaseFoto
+	Latitude                           float64
+	Longitude                          float64
+	HEMSEDCContactIDs []string
+	HEMSEDCs          []BaseContact
+	MedPaxContactIDs  []string
+	MedPax            []BaseContact
+	ResponsiblePilotContactIDs         []string
+	ResponsiblePilots                  []BaseContact
+	OperationalShiftTimes              []BaseOperationalShiftTime
+}
+
+func MapBaseCreateAttributesToDomain(attrs BaseCreateAttributes) *base.Base {
+	row := &base.Base{}
+	row.BaseName = strings.TrimSpace(attrs.BaseName)
+	row.BaseAbbreviation = strings.TrimSpace(stringOrDefault(attrs.BaseAbbreviation, ""))
+	row.Address = strings.TrimSpace(stringOrDefault(attrs.Address, ""))
+	row.Latitude = floatOrDefault(attrs.Latitude, 0)
+	row.Longitude = floatOrDefault(attrs.Longitude, 0)
+	row.LandlineNumber = strings.TrimSpace(stringOrDefault(attrs.LandlineNumber, ""))
+	row.MobileNumber = strings.TrimSpace(stringOrDefault(attrs.MobileNumber, ""))
+	row.Email = strings.TrimSpace(stringOrDefault(attrs.Email, ""))
+	row.SortKey = cloneIntPtr(attrs.SortKey)
+	row.SMSAlert = boolOrDefault(attrs.SMSAlert, false)
+	row.Checklist = boolOrDefault(attrs.Checklist, false)
+	row.LegTime = strings.TrimSpace(stringOrDefault(attrs.LegTime, ""))
+	row.DefaultStartTimeType = normalizeShiftTimeType(stringOrDefault(attrs.DefaultStartTimeType, ""))
+	row.DefaultEndTimeType = normalizeShiftTimeType(stringOrDefault(attrs.DefaultEndTimeType, ""))
+	row.UTC = normalizeUTC(attrs.UTC)
+	row.Dry = boolOrDefault(attrs.Dry, false)
+	row.ControlCenter = boolOrDefault(attrs.ControlCenter, false)
+	row.DUL = boolOrDefault(attrs.DUL, false)
+	row.Notes = strings.TrimSpace(stringOrDefault(attrs.Notes, ""))
+	row.IsActive = boolOrDefault(attrs.IsActive, true)
+	row.OperationalShiftTimes = mapBaseOperationalShiftTimesToDomain(attrs.OperationalShiftTimes)
+	return row
+}
+
+func ApplyBaseUpdateAttributesToDomain(row *base.Base, attrs BaseUpdateAttributes) {
+	if attrs.BaseName != nil {
+		row.BaseName = strings.TrimSpace(*attrs.BaseName)
+	}
+	if attrs.BaseAbbreviation != nil {
+		row.BaseAbbreviation = strings.TrimSpace(*attrs.BaseAbbreviation)
+	}
+	if attrs.Address != nil {
+		row.Address = strings.TrimSpace(*attrs.Address)
+	}
+	if attrs.Latitude != nil {
+		row.Latitude = *attrs.Latitude
+	}
+	if attrs.Longitude != nil {
+		row.Longitude = *attrs.Longitude
+	}
+	if attrs.LandlineNumber != nil {
+		row.LandlineNumber = strings.TrimSpace(*attrs.LandlineNumber)
+	}
+	if attrs.MobileNumber != nil {
+		row.MobileNumber = strings.TrimSpace(*attrs.MobileNumber)
+	}
+	if attrs.Email != nil {
+		row.Email = strings.TrimSpace(*attrs.Email)
+	}
+	if attrs.SortKey.Set {
+		if attrs.SortKey.Valid {
+			v := attrs.SortKey.Value
+			row.SortKey = &v
+		} else {
+			row.SortKey = nil
+		}
+	}
+	if attrs.SMSAlert != nil {
+		row.SMSAlert = *attrs.SMSAlert
+	}
+	if attrs.Checklist != nil {
+		row.Checklist = *attrs.Checklist
+	}
+	if attrs.LegTime != nil {
+		row.LegTime = strings.TrimSpace(*attrs.LegTime)
+	}
+	if attrs.DefaultStartTimeType != nil {
+		row.DefaultStartTimeType = normalizeShiftTimeType(*attrs.DefaultStartTimeType)
+	}
+	if attrs.DefaultEndTimeType != nil {
+		row.DefaultEndTimeType = normalizeShiftTimeType(*attrs.DefaultEndTimeType)
+	}
+	if attrs.UTC != nil {
+		row.UTC = normalizeUTC(attrs.UTC)
+	}
+	if attrs.Dry != nil {
+		row.Dry = *attrs.Dry
+	}
+	if attrs.ControlCenter != nil {
+		row.ControlCenter = *attrs.ControlCenter
+	}
+	if attrs.DUL != nil {
+		row.DUL = *attrs.DUL
+	}
+	if attrs.Notes != nil {
+		row.Notes = strings.TrimSpace(*attrs.Notes)
+	}
+	if attrs.IsActive != nil {
+		row.IsActive = *attrs.IsActive
+	}
+}
+
+func mapBaseOperationalShiftTimesToDomain(items []BaseOperationalShiftTime) []base.BaseOperationalShiftTime {
+	if len(items) == 0 {
+		return nil
+	}
+	out := make([]base.BaseOperationalShiftTime, 0, len(items))
+	for i := range items {
+		dateStart := parseBaseOperationDatePtr(items[i].DateStart)
+		dateEnd := parseBaseOperationDatePtr(items[i].DateEnd)
+		out = append(out, base.BaseOperationalShiftTime{
+			DateStart:     dateStart,
+			DateEnd:       dateEnd,
+			StartTimeType: normalizeShiftTimeType(items[i].StartTimeType),
+			EndTimeType:   normalizeShiftTimeType(items[i].EndTimeType),
+			ShiftStart:    normalizeBaseClockValue(items[i].ShiftTime.Start),
+			ShiftEnd:      normalizeBaseClockValue(items[i].ShiftTime.End),
+		})
+	}
+	return out
+}
+
+func MapBaseOperationalShiftTimesToDTO(items []base.BaseOperationalShiftTime) []BaseOperationalShiftTime {
+	if len(items) == 0 {
+		return nil
+	}
+	out := make([]BaseOperationalShiftTime, 0, len(items))
+	for i := range items {
+		out = append(out, BaseOperationalShiftTime{
+			DateStart:     timePtrToDateString(items[i].DateStart),
+			DateEnd:       timePtrToDateString(items[i].DateEnd),
+			StartTimeType: normalizeShiftTimeType(items[i].StartTimeType),
+			EndTimeType:   normalizeShiftTimeType(items[i].EndTimeType),
+			ShiftTime: BaseShiftTime{
+				Start: DisplayBaseShiftValue(items[i].StartTimeType, items[i].ShiftStart),
+				End:   DisplayBaseShiftValue(items[i].EndTimeType, items[i].ShiftEnd),
+			},
+		})
+	}
+	return out
+}
+
+func parseBaseOperationDate(raw string) time.Time {
+	parsed, err := time.Parse("2006-01-02", strings.TrimSpace(raw))
+	if err != nil {
+		return time.Time{}
+	}
+	return parsed.UTC()
+}
+
+func parseBaseOperationDatePtr(raw string) *time.Time {
+	parsed := parseBaseOperationDate(raw)
+	if parsed.IsZero() {
+		return nil
+	}
+	return &parsed
+}
+
+func timePtrToDateString(v *time.Time) string {
+	if v == nil || v.IsZero() {
+		return ""
+	}
+	return v.UTC().Format("2006-01-02")
+}
+
+func normalizeBaseClockValue(raw string) string {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" {
+		return ""
+	}
+	if len(trimmed) == 5 {
+		trimmed += ":00"
+	}
+	parsed, err := time.Parse("15:04:05", trimmed)
+	if err != nil {
+		return ""
+	}
+	return parsed.UTC().Format("15:04:05")
+}
+
+func normalizeBaseShiftDisplay(raw string) string {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return s
+	}
+	layouts := []string{
+		"15:04:05",
+		"15:04",
+		"2006-01-02 15:04:05",
+		"2006-01-02 15:04",
+		time.RFC3339,
+		time.RFC3339Nano,
+	}
+	for _, layout := range layouts {
+		if parsed, err := time.Parse(layout, s); err == nil {
+			return parsed.UTC().Format("15:04")
+		}
+	}
+	if len(s) >= 5 && isDigitBaseClock(s[0]) && isDigitBaseClock(s[1]) && s[2] == ':' && isDigitBaseClock(s[3]) && isDigitBaseClock(s[4]) {
+		return s[:5]
+	}
+	return s
+}
+
+// DisplayBaseShiftValue returns the user-facing representation for a shift value.
+// Fixed shifts are shown as HH:MM, while BMCT/ECET are shown as labels.
+func DisplayBaseShiftValue(timeType, raw string) string {
+	switch normalizeShiftTimeType(timeType) {
+	case "BMCT", "ECET":
+		return normalizeShiftTimeType(timeType)
+	default:
+		return normalizeBaseShiftDisplay(raw)
+	}
+}
+
+func normalizeShiftTimeType(raw string) string {
+	switch strings.ToUpper(strings.TrimSpace(raw)) {
+	case "", "FIXED":
+		return "FIXED"
+	case "BMCT":
+		return "BMCT"
+	case "ECET":
+		return "ECET"
+	default:
+		return strings.ToUpper(strings.TrimSpace(raw))
+	}
+}
+
+func isDigitBaseClock(b byte) bool {
+	return b >= '0' && b <= '9'
+}
+
+func MapBaseToResource(row *base.Base, in BaseResponseMappingInput) BaseResource {
+	if row == nil {
+		return BaseResource{
+			Type: in.ResourceType,
+			Attributes: BaseAttributes{
+				BaseCategory:          in.BaseCategory,
+				DefaultStartTimeType:  normalizeShiftTimeType(in.DefaultStartTimeType),
+				DefaultEndTimeType:    normalizeShiftTimeType(in.DefaultEndTimeType),
+				ShiftTime:             in.ShiftTime,
+				OperationalShiftTimes: in.OperationalShiftTimes,
+				Latitude:              in.Latitude,
+				Longitude:             in.Longitude,
+			},
+		}
+	}
+	return BaseResource{
+		Type: in.ResourceType,
+		ID:   in.ID,
+		Attributes: BaseAttributes{
+			BaseName:                           row.BaseName,
+			BaseAbbreviation:                   row.BaseAbbreviation,
+			BaseCategory:                       in.BaseCategory,
+			Address:                            row.Address,
+			Latitude:                           row.Latitude,
+			Longitude:                          row.Longitude,
+			LandlineNumber:                     row.LandlineNumber,
+			MobileNumber:                       row.MobileNumber,
+			Email:                              row.Email,
+			SortKey:                            cloneIntPtr(row.SortKey),
+			SMSAlert:                           row.SMSAlert,
+			Checklist:                          row.Checklist,
+			LegTime:                            row.LegTime,
+			DefaultStartTimeType:               normalizeShiftTimeType(row.DefaultStartTimeType),
+			DefaultEndTimeType:                 normalizeShiftTimeType(row.DefaultEndTimeType),
+			ShiftTime:                          in.ShiftTime,
+			UTC:                                row.UTC,
+			Foto:                               in.Foto,
+			Dry:                                row.Dry,
+			ControlCenter:                      row.ControlCenter,
+			DUL:                                row.DUL,
+			Notes:                              row.Notes,
+			HEMSEDCContactIDs: in.HEMSEDCContactIDs,
+			HEMSEDCs:          in.HEMSEDCs,
+			MedPaxContactIDs:  in.MedPaxContactIDs,
+			MedPax:            in.MedPax,
+			ResponsiblePilotContactIDs:         in.ResponsiblePilotContactIDs,
+			ResponsiblePilots:                  in.ResponsiblePilots,
+			OperationalShiftTimes:              in.OperationalShiftTimes,
+			IsActive:                           row.IsActive,
+			CreatedBy:                          bytesToUUID(row.CreatedBy),
+			UpdatedBy:                          bytesToUUID(row.UpdatedBy),
+			CreatedAt:                          row.CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedAt:                          row.UpdatedAt.UTC().Format(time.RFC3339),
+			DeletedAt:                          timePtrToString(row.DeletedAt),
+			DeletedBy:                          bytesToUUID(row.DeletedBy),
+		},
+	}
+}
+
+func stringOrDefault(v *string, d string) string {
+	if v == nil {
+		return d
+	}
+	return *v
+}
+
+func boolOrDefault(v *bool, d bool) bool {
+	if v == nil {
+		return d
+	}
+	return *v
+}
+
+func normalizeUTC(v *string) string {
+	s := strings.TrimSpace(stringOrDefault(v, "0"))
+	if s == "" {
+		return "0"
+	}
+	return s
+}
+
+func floatOrDefault(v *float64, d float64) float64 {
+	if v == nil {
+		return d
+	}
+	return *v
+}
+
+func cloneIntPtr(v *int) *int {
+	if v == nil {
+		return nil
+	}
+	x := *v
+	return &x
+}
+
+func bytesToUUID(v []byte) string {
+	if len(v) == 0 {
+		return ""
+	}
+	if name := userctx.GetDisplayName(context.TODO(), v); name != "" {
+		return name
+	}
+	s, err := uuidv7.BytesToString(v)
+	if err != nil {
+		return ""
+	}
+	return s
+}
+
+func timePtrToString(v *time.Time) string {
+	if v == nil {
+		return ""
+	}
+	return v.UTC().Format(time.RFC3339)
+}
diff --git a/internal/transport/http/dto/before_flight_inspection_dto.go b/internal/transport/http/dto/before_flight_inspection_dto.go
new file mode 100644
index 0000000..a91b25c
--- /dev/null
+++ b/internal/transport/http/dto/before_flight_inspection_dto.go
@@ -0,0 +1,53 @@
+package dto
+
+type BeforeFlightInspectionAttributes struct {
+	ID                        string                    `json:"id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	FlightInspectionID        string                    `json:"flight_inspection_id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	FlightInspection          *FlightInspectionResource `json:"flight_inspection,omitempty"`
+	OilEngineNR1Checked       *bool                     `json:"oil_engine_nr1_checked,omitempty"`
+	OilEngineNR2Checked       *bool                     `json:"oil_engine_nr2_checked,omitempty"`
+	HydraulicLHChecked        *bool                     `json:"hydraulic_lh_checked,omitempty"`
+	HydraulicRHChecked        *bool                     `json:"hydraulic_rh_checked,omitempty"`
+	OilTransmissionMGBChecked *bool                     `json:"oil_transmission_mgb_checked,omitempty"`
+	OilTransmissionIGBChecked *bool                     `json:"oil_transmission_igb_checked,omitempty"`
+	OilTransmissionTGBChecked *bool                     `json:"oil_transmission_tgb_checked,omitempty"`
+	FuelAmount                *float64                  `json:"fuel_amount,omitempty" example:"500.5"`
+	FuelUnit                  string                    `json:"fuel_unit,omitempty" example:"LT"`
+	FuelAddedAmount           *float64                  `json:"fuel_added_amount,omitempty" example:"100.0"`
+	Note                      *string                   `json:"note,omitempty" example:"All checks completed"`
+	CreatedAt                 string                    `json:"created_at,omitempty" example:"2026-04-09T05:00:00Z"`
+	UpdatedAt                 string                    `json:"updated_at,omitempty" example:"2026-04-09T05:00:00Z"`
+}
+
+type BeforeFlightInspectionResource struct {
+	Type       string                           `json:"type" example:"before_flight_inspection"`
+	ID         string                           `json:"id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	Attributes BeforeFlightInspectionAttributes `json:"attributes"`
+}
+
+type BeforeFlightInspectionResponse struct {
+	Data BeforeFlightInspectionResource `json:"data"`
+}
+
+type BeforeFlightInspectionUpsertAttributes struct {
+	OilEngineNR1Checked       *bool    `json:"oil_engine_nr1_checked,omitempty"`
+	OilEngineNR2Checked       *bool    `json:"oil_engine_nr2_checked,omitempty"`
+	HydraulicLHChecked        *bool    `json:"hydraulic_lh_checked,omitempty"`
+	HydraulicRHChecked        *bool    `json:"hydraulic_rh_checked,omitempty"`
+	OilTransmissionMGBChecked *bool    `json:"oil_transmission_mgb_checked,omitempty"`
+	OilTransmissionIGBChecked *bool    `json:"oil_transmission_igb_checked,omitempty"`
+	OilTransmissionTGBChecked *bool    `json:"oil_transmission_tgb_checked,omitempty"`
+	FuelAmount                *float64 `json:"fuel_amount,omitempty" validate:"omitempty,gte=0"`
+	FuelUnit                  *string  `json:"fuel_unit,omitempty" validate:"omitempty,oneof=LT KG POUND"`
+	FuelAddedAmount           *float64 `json:"fuel_added_amount,omitempty" validate:"omitempty,gte=0"`
+	Note                      *string  `json:"note,omitempty"`
+}
+
+type BeforeFlightInspectionUpsertData struct {
+	Type       string                                 `json:"type" validate:"required,oneof=before_flight_inspection_upsert before_flight_inspection"`
+	Attributes BeforeFlightInspectionUpsertAttributes `json:"attributes" validate:"required"`
+}
+
+type BeforeFlightInspectionUpsertRequest struct {
+	Data BeforeFlightInspectionUpsertData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/contacts_dto.go b/internal/transport/http/dto/contacts_dto.go
new file mode 100644
index 0000000..1f96e4f
--- /dev/null
+++ b/internal/transport/http/dto/contacts_dto.go
@@ -0,0 +1,423 @@
+package dto
+
+import "time"
+
+type ContactBaseAttributes struct {
+	Email       string `json:"email,omitempty" validate:"omitempty,email"`
+	SSOEmail    string `json:"sso_email,omitempty" validate:"omitempty,email"`
+	IsAdmin     *bool  `json:"is_admin,omitempty"`
+	Username    string `json:"username,omitempty" validate:"omitempty,max=100"`
+	FirstName   string `json:"first_name,omitempty" validate:"omitempty,max=100"`
+	LastName    string `json:"last_name,omitempty" validate:"omitempty,max=100"`
+	MobilePhone string `json:"mobile_phone,omitempty" validate:"omitempty,max=32"`
+	Timezone    string `json:"timezone,omitempty" validate:"omitempty,max=64"`
+	FileUUID    string `json:"file_uuid,omitempty" validate:"omitempty,max=64"`
+	SortKey     *int   `json:"sortkey"`
+	IsActive    *bool  `json:"is_active,omitempty"`
+}
+
+type PilotProfileAttributes struct {
+	PilotCategory           string     `json:"pilot_category,omitempty" validate:"omitempty,oneof=regular freelance dry_lease"`
+	ShortName               string     `json:"short_name,omitempty" validate:"omitempty,max=120"`
+	LicenseNo               string     `json:"license_no,omitempty" validate:"omitempty,max=120"`
+	LicenseIssuedAt         *time.Time `json:"license_issued_at,omitempty"`
+	LicenseExpiredAt        *time.Time `json:"license_expired_at,omitempty"`
+	TechnicianLicenseNo     string     `json:"technician_license_no,omitempty" validate:"omitempty,max=120"`
+	HasIFRQualification     *bool      `json:"has_ifr_qualification,omitempty"`
+	IsChiefPilot            *bool      `json:"is_chief_pilot,omitempty"`
+	DULBaseIDs              []string   `json:"dul_base_ids,omitempty" validate:"omitempty,dive,uuid" swaggerignore:"true"`
+	DULBase                 []DULBase  `json:"dul_base,omitempty"`
+	TotalFlightMinutes      *int       `json:"total_flight_minutes,omitempty"`
+	ResponsiblePilotMinutes *int       `json:"responsible_pilot_minutes,omitempty"`
+	SecondPilotMinutes      *int       `json:"second_pilot_minutes,omitempty"`
+	DoubleCommandMinutes    *int       `json:"double_command_minutes,omitempty"`
+	FlightInstructorMinutes *int       `json:"flight_instructor_minutes,omitempty"`
+	NightFlightMinutes      *int       `json:"night_flight_minutes,omitempty"`
+	IFRFlightMinutes        *int       `json:"ifr_flight_minutes,omitempty"`
+	Location                string     `json:"location,omitempty" validate:"omitempty,max=255"`
+	Postcode                string     `json:"postcode,omitempty" validate:"omitempty,max=32"`
+	StreetLine              string     `json:"street_line,omitempty" validate:"omitempty,max=255"`
+	Note                    string     `json:"note,omitempty"`
+	WeightKG                *float64   `json:"weight_kg,omitempty"`
+}
+
+type DULBase struct {
+	ID       string `json:"id" example:"0197f3b2-c4d8-4b12-a1f9-c1de23456789"`
+	Name     string `json:"name" example:"Halim Base"`
+	Category string `json:"category" example:"hems"`
+}
+
+type DoctorProfileAttributes struct {
+	ShortName         string `json:"short_name,omitempty" validate:"omitempty,max=120"`
+	Specialization    string `json:"specialization,omitempty" validate:"omitempty,max=120"`
+	SubSpecialization string `json:"sub_specialization,omitempty" validate:"omitempty,max=120"`
+	IsChiefPhysician  *bool  `json:"is_chief_physician,omitempty"`
+	Location          string `json:"location,omitempty" validate:"omitempty,max=255"`
+	Postcode          string `json:"postcode,omitempty" validate:"omitempty,max=32"`
+	StreetLine        string `json:"street_line,omitempty" validate:"omitempty,max=255"`
+	Note              string `json:"note,omitempty"`
+}
+
+type AirRescuerProfileAttributes struct {
+	ShortName                string `json:"short_name,omitempty" validate:"omitempty,max=120"`
+	ResponsibleFlightRescuer *bool  `json:"responsible_flight_rescuer,omitempty"`
+	Location                 string `json:"location,omitempty" validate:"omitempty,max=255"`
+	Postcode                 string `json:"postcode,omitempty" validate:"omitempty,max=32"`
+	StreetLine               string `json:"street_line,omitempty" validate:"omitempty,max=255"`
+	Note                     string `json:"note,omitempty"`
+}
+
+type TechnicianProfileAttributes struct {
+	ShortName               string `json:"short_name,omitempty" validate:"omitempty,max=120"`
+	LicenseNo               string `json:"license_no,omitempty" validate:"omitempty,max=120"`
+	IsChiefTechnician       *bool  `json:"is_chief_technician,omitempty"`
+	IsResponsibleComplaints *bool  `json:"is_responsible_complaints,omitempty"`
+	Location                string `json:"location,omitempty" validate:"omitempty,max=255"`
+	Postcode                string `json:"postcode,omitempty" validate:"omitempty,max=32"`
+	StreetLine              string `json:"street_line,omitempty" validate:"omitempty,max=255"`
+	Note                    string `json:"note,omitempty"`
+}
+
+type FlightAssistantProfileAttributes struct {
+	ShortName  string `json:"short_name,omitempty" validate:"omitempty,max=120"`
+	Location   string `json:"location,omitempty" validate:"omitempty,max=255"`
+	Postcode   string `json:"postcode,omitempty" validate:"omitempty,max=32"`
+	StreetLine string `json:"street_line,omitempty" validate:"omitempty,max=255"`
+	Note       string `json:"note,omitempty"`
+}
+
+type StaffProfileAttributes struct {
+	ShortName  string `json:"short_name,omitempty" validate:"omitempty,max=120"`
+	RoleLabel  string `json:"role_label,omitempty" validate:"omitempty,max=120"`
+	Location   string `json:"location,omitempty" validate:"omitempty,max=255"`
+	Postcode   string `json:"postcode,omitempty" validate:"omitempty,max=32"`
+	StreetLine string `json:"street_line,omitempty" validate:"omitempty,max=255"`
+	Note       string `json:"note,omitempty"`
+}
+
+type ContactCreateAttributes struct {
+	RoleID  string   `json:"role_id,omitempty" example:"0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1"`
+	RoleIDs []string `json:"role_ids,omitempty" example:"0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1,0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d2"`
+	ContactBaseAttributes
+	AirRescuer      *AirRescuerProfileAttributes      `json:"air_rescuer,omitempty"`
+	Doctor          *DoctorProfileAttributes          `json:"doctor,omitempty"`
+	FlightAssistant *FlightAssistantProfileAttributes `json:"flight_assistant,omitempty"`
+	Pilot           *PilotProfileAttributes           `json:"pilot,omitempty"`
+	Staff           *StaffProfileAttributes           `json:"staff,omitempty"`
+	Technician      *TechnicianProfileAttributes      `json:"technician,omitempty"`
+}
+
+type ContactCreateData struct {
+	Type       string                  `json:"type" validate:"required" example:"contact_create"`
+	Attributes ContactCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type ContactCreateRequest struct {
+	Data ContactCreateData `json:"data" validate:"required"`
+}
+
+type PilotProfileUpdateAttributes struct {
+	PilotCategory           *string    `json:"pilot_category,omitempty" validate:"omitempty,oneof=regular freelance dry_lease"`
+	ShortName               *string    `json:"short_name,omitempty" validate:"omitempty,max=120"`
+	LicenseNo               *string    `json:"license_no,omitempty" validate:"omitempty,max=120"`
+	LicenseIssuedAt         *time.Time `json:"license_issued_at,omitempty"`
+	LicenseExpiredAt        *time.Time `json:"license_expired_at,omitempty"`
+	TechnicianLicenseNo     *string    `json:"technician_license_no,omitempty" validate:"omitempty,max=120"`
+	HasIFRQualification     *bool      `json:"has_ifr_qualification,omitempty"`
+	IsChiefPilot            *bool      `json:"is_chief_pilot,omitempty"`
+	DULBaseIDs              []string   `json:"dul_base_ids,omitempty" validate:"omitempty,dive,uuid" swaggerignore:"true"`
+	DULBase                 []DULBase  `json:"dul_base,omitempty"`
+	TotalFlightMinutes      *int       `json:"total_flight_minutes,omitempty"`
+	ResponsiblePilotMinutes *int       `json:"responsible_pilot_minutes,omitempty"`
+	SecondPilotMinutes      *int       `json:"second_pilot_minutes,omitempty"`
+	DoubleCommandMinutes    *int       `json:"double_command_minutes,omitempty"`
+	FlightInstructorMinutes *int       `json:"flight_instructor_minutes,omitempty"`
+	NightFlightMinutes      *int       `json:"night_flight_minutes,omitempty"`
+	IFRFlightMinutes        *int       `json:"ifr_flight_minutes,omitempty"`
+	Location                *string    `json:"location,omitempty" validate:"omitempty,max=255"`
+	Postcode                *string    `json:"postcode,omitempty" validate:"omitempty,max=32"`
+	StreetLine              *string    `json:"street_line,omitempty" validate:"omitempty,max=255"`
+	Note                    *string    `json:"note,omitempty"`
+	WeightKG                *float64   `json:"weight_kg,omitempty"`
+}
+
+type DoctorProfileUpdateAttributes struct {
+	ShortName         *string `json:"short_name,omitempty" validate:"omitempty,max=120"`
+	Specialization    *string `json:"specialization,omitempty" validate:"omitempty,max=120"`
+	SubSpecialization *string `json:"sub_specialization,omitempty" validate:"omitempty,max=120"`
+	IsChiefPhysician  *bool   `json:"is_chief_physician,omitempty"`
+	Location          *string `json:"location,omitempty" validate:"omitempty,max=255"`
+	Postcode          *string `json:"postcode,omitempty" validate:"omitempty,max=32"`
+	StreetLine        *string `json:"street_line,omitempty" validate:"omitempty,max=255"`
+	Note              *string `json:"note,omitempty"`
+}
+
+type AirRescuerProfileUpdateAttributes struct {
+	ShortName                *string `json:"short_name,omitempty" validate:"omitempty,max=120"`
+	ResponsibleFlightRescuer *bool   `json:"responsible_flight_rescuer,omitempty"`
+	Location                 *string `json:"location,omitempty" validate:"omitempty,max=255"`
+	Postcode                 *string `json:"postcode,omitempty" validate:"omitempty,max=32"`
+	StreetLine               *string `json:"street_line,omitempty" validate:"omitempty,max=255"`
+	Note                     *string `json:"note,omitempty"`
+}
+
+type TechnicianProfileUpdateAttributes struct {
+	ShortName               *string `json:"short_name,omitempty" validate:"omitempty,max=120"`
+	LicenseNo               *string `json:"license_no,omitempty" validate:"omitempty,max=120"`
+	IsChiefTechnician       *bool   `json:"is_chief_technician,omitempty"`
+	IsResponsibleComplaints *bool   `json:"is_responsible_complaints,omitempty"`
+	Location                *string `json:"location,omitempty" validate:"omitempty,max=255"`
+	Postcode                *string `json:"postcode,omitempty" validate:"omitempty,max=32"`
+	StreetLine              *string `json:"street_line,omitempty" validate:"omitempty,max=255"`
+	Note                    *string `json:"note,omitempty"`
+}
+
+type FlightAssistantProfileUpdateAttributes struct {
+	ShortName  *string `json:"short_name,omitempty" validate:"omitempty,max=120"`
+	Location   *string `json:"location,omitempty" validate:"omitempty,max=255"`
+	Postcode   *string `json:"postcode,omitempty" validate:"omitempty,max=32"`
+	StreetLine *string `json:"street_line,omitempty" validate:"omitempty,max=255"`
+	Note       *string `json:"note,omitempty"`
+}
+
+type StaffProfileUpdateAttributes struct {
+	ShortName  *string `json:"short_name,omitempty" validate:"omitempty,max=120"`
+	RoleLabel  *string `json:"role_label,omitempty" validate:"omitempty,max=120"`
+	Location   *string `json:"location,omitempty" validate:"omitempty,max=255"`
+	Postcode   *string `json:"postcode,omitempty" validate:"omitempty,max=32"`
+	StreetLine *string `json:"street_line,omitempty" validate:"omitempty,max=255"`
+	Note       *string `json:"note,omitempty"`
+}
+
+type ContactUpdateAttributes struct {
+	RoleID          *string                                 `json:"role_id,omitempty" example:"0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1"`
+	RoleIDs         []string                                `json:"role_ids,omitempty" example:"0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1,0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d2"`
+	Email           *string                                 `json:"email,omitempty" validate:"omitempty,email"`
+	SSOEmail        *string                                 `json:"sso_email,omitempty" validate:"omitempty,email"`
+	IsAdmin         *bool                                   `json:"is_admin,omitempty"`
+	Username        *string                                 `json:"username,omitempty" validate:"omitempty,max=100"`
+	FirstName       *string                                 `json:"first_name,omitempty" validate:"omitempty,max=100"`
+	LastName        *string                                 `json:"last_name,omitempty" validate:"omitempty,max=100"`
+	MobilePhone     *string                                 `json:"mobile_phone,omitempty" validate:"omitempty,max=32"`
+	Timezone        *string                                 `json:"timezone,omitempty" validate:"omitempty,max=64"`
+	FileUUID        *string                                 `json:"file_uuid,omitempty" validate:"omitempty,max=64"`
+	SortKey         NullInt                                 `json:"sortkey,omitempty" swaggertype:"integer"`
+	IsActive        *bool                                   `json:"is_active,omitempty"`
+	AirRescuer      *AirRescuerProfileUpdateAttributes      `json:"air_rescuer,omitempty"`
+	Doctor          *DoctorProfileUpdateAttributes          `json:"doctor,omitempty"`
+	FlightAssistant *FlightAssistantProfileUpdateAttributes `json:"flight_assistant,omitempty"`
+	Pilot           *PilotProfileUpdateAttributes           `json:"pilot,omitempty"`
+	Staff           *StaffProfileUpdateAttributes           `json:"staff,omitempty"`
+	Technician      *TechnicianProfileUpdateAttributes      `json:"technician,omitempty"`
+}
+
+type ContactUpdateData struct {
+	Type       string                  `json:"type" validate:"required" example:"contact_update"`
+	Attributes ContactUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type ContactUpdateRequest struct {
+	Data ContactUpdateData `json:"data" validate:"required"`
+}
+
+type ContactListQuery struct {
+	Role          string `query:"role" validate:"omitempty,oneof=pilot doctor air_rescuer technician flight_assistant staff"`
+	PilotCategory string `query:"pilot_category" validate:"omitempty,oneof=regular freelance dry_lease"`
+	Search        string `query:"search"`
+	Sort          string `query:"sort"`
+	Limit         int    `query:"limit" validate:"omitempty,min=1,max=200"`
+	Offset        int    `query:"offset" validate:"omitempty,min=0"`
+}
+
+type ContactListItem struct {
+	ID            string `json:"id"`
+	CreatedBy     string `json:"created_by,omitempty"`
+	UpdatedBy     string `json:"updated_by,omitempty"`
+	CreatedAt     string `json:"created_at,omitempty"`
+	UpdatedAt     string `json:"updated_at,omitempty"`
+	RoleCode      string `json:"role_code"`
+	RoleName      string `json:"role_name"`
+	PilotCategory string `json:"pilot_category,omitempty"`
+	Username      string `json:"username,omitempty"`
+	Email         string `json:"email"`
+	IsAdmin       bool   `json:"is_admin"`
+	FirstName     string `json:"first_name"`
+	LastName      string `json:"last_name"`
+	ShortName     string `json:"short_name,omitempty"`
+	LicenseNo     string `json:"license_no,omitempty"`
+	Location      string `json:"location,omitempty"`
+	MobilePhone   string `json:"mobile_phone,omitempty"`
+	SortKey       *int   `json:"sortkey"`
+	Note          string `json:"note,omitempty"`
+	IsActive      bool   `json:"is_active"`
+	SetPassword   bool   `json:"set_password"`
+}
+
+type ContactBaseRole struct {
+	BaseID   string `json:"base_id"`
+	BaseName string `json:"base_name"`
+	RoleCode string `json:"role_code"`
+}
+
+type ContactRole struct {
+	ID       string `json:"id"`
+	RoleCode string `json:"role_code"`
+	RoleName string `json:"role_name"`
+}
+
+type ContactListAttributes struct {
+	Email           string                            `json:"email,omitempty"`
+	Username        string                            `json:"username,omitempty"`
+	FirstName       string                            `json:"first_name,omitempty"`
+	LastName        string                            `json:"last_name,omitempty"`
+	MobilePhone     string                            `json:"mobile_phone,omitempty"`
+	IsAdmin         bool                              `json:"is_admin"`
+	IsActive        bool                              `json:"is_active"`
+	SetPassword     bool                              `json:"set_password"`
+	SortKey         *int                              `json:"sortkey"`
+	SSOEmail        *string                           `json:"sso_email"`
+	CreatedAt       string                            `json:"created_at,omitempty"`
+	CreatedBy       string                            `json:"created_by,omitempty"`
+	UpdatedAt       string                            `json:"updated_at,omitempty"`
+	UpdatedBy       string                            `json:"updated_by,omitempty"`
+	BaseRoles       []ContactBaseRole                 `json:"base_roles"`
+	RoleCode        string                            `json:"role_code,omitempty"`
+	RoleName        string                            `json:"role_name,omitempty"`
+	Roles           []ContactRole                     `json:"roles"`
+	PilotCategory   string                            `json:"pilot_category,omitempty"`
+	ShortName       string                            `json:"short_name,omitempty"`
+	LicenseNo       string                            `json:"license_no,omitempty"`
+	Location        string                            `json:"location,omitempty"`
+	Note            string                            `json:"note,omitempty"`
+	Pilot           *PilotProfileAttributes           `json:"pilot,omitempty"`
+	Doctor          *DoctorProfileAttributes          `json:"doctor,omitempty"`
+	AirRescuer      *AirRescuerProfileAttributes      `json:"air_rescuer,omitempty"`
+	Technician      *TechnicianProfileAttributes      `json:"technician,omitempty"`
+	FlightAssistant *FlightAssistantProfileAttributes `json:"flight_assistant,omitempty"`
+	Staff           *StaffProfileAttributes           `json:"staff,omitempty"`
+}
+
+type ContactListResponse struct {
+	Data []struct {
+		Type       string                `json:"type" example:"contact"`
+		ID         string                `json:"id" example:"019dcce4-f15e-7685-8e4c-76f8ad20594b"`
+		Attributes ContactListAttributes `json:"attributes"`
+	} `json:"data"`
+	Meta struct {
+		Total  int64 `json:"total"`
+		Limit  int   `json:"limit"`
+		Offset int   `json:"offset"`
+	} `json:"meta"`
+}
+
+type ContactDataTableResponse struct {
+	Data []ContactListItem `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type SensitiveActionRequiredResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"pin_verification_required"`
+		Attributes struct {
+			Required bool   `json:"required" example:"true"`
+			Action   string `json:"action"`
+			Method   string `json:"method" example:"pin"`
+			Status   int    `json:"status" example:"202"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type ContactStatusUpdateData struct {
+	Type       string `json:"type" validate:"required,eq=contact_status_update"`
+	Attributes struct {
+		IsActive bool `json:"is_active"`
+	} `json:"attributes" validate:"required"`
+}
+
+type ContactStatusUpdateRequest struct {
+	Data ContactStatusUpdateData `json:"data" validate:"required"`
+}
+
+type ContactRoleUpdateData struct {
+	Type       string `json:"type" validate:"required,eq=contact_role_update"`
+	Attributes struct {
+		RoleCode string `json:"role_code" validate:"required,oneof=pilot doctor air_rescuer technician flight_assistant staff"`
+	} `json:"attributes" validate:"required"`
+}
+
+type ContactRoleUpdateRequest struct {
+	Data ContactRoleUpdateData `json:"data" validate:"required"`
+}
+
+type ContactPilotCategoryUpdateData struct {
+	Type       string `json:"type" validate:"required,eq=contact_pilot_category_update"`
+	Attributes struct {
+		PilotCategory string `json:"pilot_category" validate:"required,oneof=regular freelance dry_lease"`
+	} `json:"attributes" validate:"required"`
+}
+
+type ContactPilotCategoryUpdateRequest struct {
+	Data ContactPilotCategoryUpdateData `json:"data" validate:"required"`
+}
+
+type ContactLicenseUpdateData struct {
+	Type       string `json:"type" validate:"required,eq=contact_license_update"`
+	Attributes struct {
+		LicenseNo *string `json:"license_no,omitempty"`
+	} `json:"attributes" validate:"required"`
+}
+
+type ContactLicenseUpdateRequest struct {
+	Data ContactLicenseUpdateData `json:"data" validate:"required"`
+}
+
+type ContactChiefFlagsUpdateData struct {
+	Type       string `json:"type" validate:"required,eq=contact_chief_flags_update"`
+	Attributes struct {
+		IsChiefPilot             *bool `json:"is_chief_pilot,omitempty"`
+		IsChiefPhysician  *bool `json:"is_chief_physician,omitempty"`
+		IsChiefTechnician *bool `json:"is_chief_technician,omitempty"`
+	} `json:"attributes" validate:"required"`
+}
+
+type ContactChiefFlagsUpdateRequest struct {
+	Data ContactChiefFlagsUpdateData `json:"data" validate:"required"`
+}
+
+type ContactResponsibleComplaintsData struct {
+	Type       string `json:"type" validate:"required,eq=contact_responsible_complaints_update"`
+	Attributes struct {
+		IsResponsibleComplaints bool `json:"is_responsible_complaints"`
+	} `json:"attributes" validate:"required"`
+}
+
+type ContactResponsibleComplaintsRequest struct {
+	Data ContactResponsibleComplaintsData `json:"data" validate:"required"`
+}
+
+type ContactBulkUpdateData struct {
+	Type       string `json:"type" validate:"required,eq=contact_bulk_update" example:"contact_bulk_update"`
+	Attributes struct {
+		UserIDs  []string `json:"user_ids" validate:"required,min=1,dive,required" example:"0195f6f8-0f8d-7e3e-b8f2-8abff9b5c1d1"`
+		IsActive bool     `json:"is_active" example:"true"`
+	} `json:"attributes" validate:"required"`
+}
+
+type ContactBulkUpdateRequest struct {
+	Data ContactBulkUpdateData `json:"data" validate:"required"`
+}
+
+type ContactSimpleSuccessResponse struct {
+	Data struct {
+		Type       string `json:"type"`
+		Attributes struct {
+			Updated bool  `json:"updated,omitempty"`
+			Deleted bool  `json:"deleted,omitempty"`
+			Count   int64 `json:"count,omitempty"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
diff --git a/internal/transport/http/dto/delete_dto.go b/internal/transport/http/dto/delete_dto.go
new file mode 100644
index 0000000..493a8e4
--- /dev/null
+++ b/internal/transport/http/dto/delete_dto.go
@@ -0,0 +1,26 @@
+package dto
+
+// GenericDeleteResponse is a common success payload for DELETE endpoints.
+type GenericDeleteResponse struct {
+	Data GenericDeleteResponseData `json:"data"`
+}
+
+type GenericDeleteResponseData struct {
+	Type       string                  `json:"type" example:"delete_result"`
+	Attributes GenericDeleteAttributes `json:"attributes"`
+}
+
+type GenericDeleteAttributes struct {
+	Deleted bool `json:"deleted" example:"true"`
+}
+
+func NewGenericDeleteResponse(resourceType string) GenericDeleteResponse {
+	return GenericDeleteResponse{
+		Data: GenericDeleteResponseData{
+			Type: resourceType,
+			Attributes: GenericDeleteAttributes{
+				Deleted: true,
+			},
+		},
+	}
+}
diff --git a/internal/transport/http/dto/dul_request_dto.go b/internal/transport/http/dto/dul_request_dto.go
new file mode 100644
index 0000000..c2c79c9
--- /dev/null
+++ b/internal/transport/http/dto/dul_request_dto.go
@@ -0,0 +1,38 @@
+package dto
+
+type DULCreateAttributes struct {
+	Name               string   `json:"name" validate:"required,max=128"`
+	Date               string   `json:"date" validate:"required" example:"2026-05-25"`
+	Info               *string  `json:"info,omitempty"`
+	BaseID             string   `json:"base_id" validate:"required" example:"019e3ec1-94f6-7b6b-9cc5-1b5d05f46d74"`
+	FileUUID           []string `json:"file_uuid,omitempty"`
+	ImageAttachmentIDs []string `json:"image_attachment_ids,omitempty" swaggerignore:"true"`
+}
+
+type DULCreateData struct {
+	Type       string              `json:"type" validate:"required,oneof=dul_create dul"`
+	Attributes DULCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type DULCreateRequest struct {
+	Data DULCreateData `json:"data" validate:"required"`
+}
+
+type DULUpdateAttributes struct {
+	Name               *string  `json:"name,omitempty"`
+	Date               *string  `json:"date,omitempty" example:"2026-05-25"`
+	Info               *string  `json:"info,omitempty"`
+	BaseID             *string  `json:"base_id,omitempty"`
+	FileUUID           []string `json:"file_uuid,omitempty"`
+	ImageAttachmentIDs []string `json:"image_attachment_ids,omitempty" swaggerignore:"true"`
+}
+
+type DULUpdateData struct {
+	Type       string              `json:"type" validate:"required,oneof=dul_update dul"`
+	ID         string              `json:"id" swaggerignore:"true"`
+	Attributes DULUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type DULUpdateRequest struct {
+	Data DULUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/dul_response_dto.go b/internal/transport/http/dto/dul_response_dto.go
new file mode 100644
index 0000000..ba6949b
--- /dev/null
+++ b/internal/transport/http/dto/dul_response_dto.go
@@ -0,0 +1,74 @@
+package dto
+
+type DULImage struct {
+	UUID                 string `json:"uuid"`
+	DownloadURL          string `json:"download_url,omitempty"`
+	OriginalSizeBytes    int64  `json:"original_size_bytes,omitempty"`
+	ThumbnailDownloadURL string `json:"thumbnail_download_url,omitempty"`
+}
+
+type DULAttributes struct {
+	No        uint64     `json:"no"`
+	Name      string     `json:"name"`
+	Date      string     `json:"date" example:"2026-05-25"`
+	Info      string     `json:"info,omitempty"`
+	Base      DULBaseRef `json:"base"`
+	Images    []DULImage `json:"images"`
+	CreatedAt string     `json:"created_at,omitempty"`
+	CreatedBy string     `json:"created_by,omitempty"`
+	UpdatedAt string     `json:"updated_at,omitempty"`
+	UpdatedBy string     `json:"updated_by,omitempty"`
+}
+
+type DULBaseRef struct {
+	ID       string `json:"id"`
+	Name     string `json:"name"`
+	Category string `json:"category,omitempty"`
+}
+
+type DULResource struct {
+	Type       string        `json:"type"`
+	ID         string        `json:"id"`
+	Attributes DULAttributes `json:"attributes"`
+}
+
+type DULResponse struct {
+	Data DULResource `json:"data"`
+}
+
+type DULDeleteResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"dul_delete"`
+		Attributes struct {
+			Deleted bool `json:"deleted" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type DULGroup struct {
+	Base DULBaseRef    `json:"base"`
+	DULs []DULResource `json:"duls"`
+}
+
+type DULListResponse struct {
+	Data []DULGroup `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+		TotalBases int   `json:"total_bases" example:"8"`
+	} `json:"meta"`
+}
+
+type DULDataTableResponse struct {
+	Data []DULGroup `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		PageNumber      int   `json:"page_number" example:"1"`
+		PageSize        int   `json:"page_size" example:"20"`
+		Total           int64 `json:"total" example:"120"`
+		TotalBases      int   `json:"total_bases" example:"8"`
+		RecordsTotal    int64 `json:"records_total,omitempty" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered,omitempty" example:"120"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/facility_dto.go b/internal/transport/http/dto/facility_dto.go
new file mode 100644
index 0000000..ce1133f
--- /dev/null
+++ b/internal/transport/http/dto/facility_dto.go
@@ -0,0 +1,99 @@
+package dto
+
+// JSON:API Facility DTOs
+
+type FacilityAttributes struct {
+	Category  string `json:"category" example:"heslo-rope-label"`
+	Name      string `json:"name" example:"Fuel Truck Rope Label"`
+	Type      string `json:"type" example:"Sling"`
+	SortKey   *int   `json:"sortkey" example:"1"`
+	Length    string `json:"length,omitempty" example:"10m"`
+	Weight    string `json:"weight,omitempty" example:"10kg"`
+	Electric  string `json:"electric" example:"available"`
+	Note      string `json:"note,omitempty" example:"Dry lease fuel truck"`
+	IsActive  bool   `json:"is_active" example:"true"`
+	CreatedBy string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedBy string `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+}
+
+type FacilityResource struct {
+	Type       string             `json:"type" example:"facility"`
+	ID         string             `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes FacilityAttributes `json:"attributes"`
+}
+
+type FacilityResponse struct {
+	Data FacilityResource `json:"data"`
+}
+
+type FacilityDeleteResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"facility_delete"`
+		Attributes struct {
+			Deleted bool `json:"deleted" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type FacilityListResponse struct {
+	Data []FacilityResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type FacilityDataTableResponse struct {
+	Data []FacilityResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type FacilityCreateAttributes struct {
+	Category string  `json:"category" validate:"required" example:"heslo-rope-label"`
+	Name     string  `json:"name" validate:"required" example:"Fuel Truck Rope Label"`
+	Type     string  `json:"type" example:"Sling"`
+	SortKey  *int    `json:"sortkey" example:"1"`
+	Length   *string `json:"length,omitempty" example:"10m"`
+	Weight   *string `json:"weight,omitempty" example:"10kg"`
+	Electric *string `json:"electric,omitempty" example:"available"`
+	Note     *string `json:"note,omitempty" example:"Dry lease fuel truck"`
+	IsActive *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type FacilityCreateData struct {
+	Type       string                   `json:"type" validate:"required,oneof=facility_create facility" example:"facility_create"`
+	Attributes FacilityCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FacilityCreateRequest struct {
+	Data FacilityCreateData `json:"data" validate:"required"`
+}
+
+type FacilityUpdateAttributes struct {
+	Category *string `json:"category,omitempty" example:"heslo-rope-label"`
+	Name     *string `json:"name,omitempty" example:"Fuel Truck Rope Label"`
+	Type     *string `json:"type,omitempty" example:"Sling"`
+	SortKey  NullInt `json:"sortkey,omitempty" swaggertype:"integer" example:"1"`
+	Length   *string `json:"length,omitempty" example:"10m"`
+	Weight   *string `json:"weight,omitempty" example:"10kg"`
+	Electric *string `json:"electric,omitempty" example:"available"`
+	Note     *string `json:"note,omitempty" example:"Dry lease fuel truck"`
+	IsActive *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type FacilityUpdateData struct {
+	Type       string                   `json:"type" validate:"required,oneof=facility_update facility" example:"facility_update"`
+	ID         string                   `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes FacilityUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type FacilityUpdateRequest struct {
+	Data FacilityUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/federal_state_dto.go b/internal/transport/http/dto/federal_state_dto.go
new file mode 100644
index 0000000..30af002
--- /dev/null
+++ b/internal/transport/http/dto/federal_state_dto.go
@@ -0,0 +1,91 @@
+package dto
+
+// JSON:API Federal State DTOs
+
+type FederalStateAttributes struct {
+	Name        string `json:"name" example:"Bayern"`
+	Note        string `json:"note,omitempty" example:"Central region"`
+	LandID      string `json:"land_id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	LandName    string `json:"land_name,omitempty" example:"Germany"`
+	LandISOCode string `json:"land_iso_code,omitempty" example:"DE"`
+	SortKey     *int   `json:"sortkey" example:"1"`
+	IsActive    bool   `json:"is_active" example:"true"`
+	CreatedAt   string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy   string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt   string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy   string `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt   string `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy   string `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FederalStateResource struct {
+	Type       string                 `json:"type" example:"federal_state"`
+	ID         string                 `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes FederalStateAttributes `json:"attributes"`
+}
+
+type FederalStateResponse struct {
+	Data FederalStateResource `json:"data"`
+}
+
+type FederalStateDeleteResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"federal_state_delete"`
+		Attributes struct {
+			Deleted bool `json:"deleted" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type FederalStateListResponse struct {
+	Data []FederalStateResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type FederalStateDataTableResponse struct {
+	Data []FederalStateResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type FederalStateCreateAttributes struct {
+	Name     string  `json:"name" validate:"required" example:"Bayern"`
+	Note     *string `json:"note,omitempty" example:"Central region"`
+	LandID   string  `json:"land_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	SortKey  *int    `json:"sortkey" example:"1"`
+	IsActive *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type FederalStateCreateData struct {
+	Type       string                       `json:"type" validate:"required,oneof=federal_state_create federal_state" example:"federal_state_create"`
+	Attributes FederalStateCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FederalStateCreateRequest struct {
+	Data FederalStateCreateData `json:"data" validate:"required"`
+}
+
+type FederalStateUpdateAttributes struct {
+	Name     *string `json:"name,omitempty" example:"Bayern"`
+	Note     *string `json:"note,omitempty" example:"Central region"`
+	LandID   *string `json:"land_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	SortKey  NullInt `json:"sortkey,omitempty" swaggertype:"integer" example:"1"`
+	IsActive *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type FederalStateUpdateData struct {
+	Type       string                       `json:"type" validate:"required,oneof=federal_state_update federal_state" example:"federal_state_update"`
+	ID         string                       `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes FederalStateUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type FederalStateUpdateRequest struct {
+	Data FederalStateUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/flight_inspection_dto.go b/internal/transport/http/dto/flight_inspection_dto.go
new file mode 100644
index 0000000..100704d
--- /dev/null
+++ b/internal/transport/http/dto/flight_inspection_dto.go
@@ -0,0 +1,57 @@
+package dto
+
+type FlightInspectionAttributes struct {
+	InspectionDate string `json:"inspection_date,omitempty" example:"2026-04-09"`
+	Status         string `json:"status,omitempty" example:"Draft"`
+	CreatedAt      string `json:"created_at,omitempty" example:"2026-04-09T05:00:00Z"`
+	CreatedBy      string `json:"created_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	UpdatedAt      string `json:"updated_at,omitempty" example:"2026-04-09T05:00:00Z"`
+	UpdatedBy      string `json:"updated_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+}
+
+type FlightInspectionResource struct {
+	Type       string                     `json:"type" example:"flight_inspection"`
+	ID         string                     `json:"id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	Attributes FlightInspectionAttributes `json:"attributes"`
+}
+
+type FlightInspectionResponse struct {
+	Data FlightInspectionResource `json:"data"`
+}
+
+type FlightInspectionListResponse struct {
+	Data []FlightInspectionResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
+
+type FlightInspectionCreateAttributes struct {
+	InspectionDate string `json:"inspection_date" validate:"required" example:"2026-04-09"`
+}
+
+type FlightInspectionCreateData struct {
+	Type       string                           `json:"type" validate:"required,oneof=flight_inspection_create flight_inspection"`
+	Attributes FlightInspectionCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FlightInspectionCreateRequest struct {
+	Data FlightInspectionCreateData `json:"data" validate:"required"`
+}
+
+type FlightInspectionUpdateAttributes struct {
+	InspectionDate *string `json:"inspection_date,omitempty" example:"2026-04-09"`
+	Status         *string `json:"status,omitempty" example:"InProgress"`
+}
+
+type FlightInspectionUpdateData struct {
+	Type       string                           `json:"type" validate:"required,oneof=flight_inspection_update flight_inspection"`
+	ID         string                           `json:"id" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	Attributes FlightInspectionUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type FlightInspectionUpdateRequest struct {
+	Data FlightInspectionUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/flight_prep_check_dto.go b/internal/transport/http/dto/flight_prep_check_dto.go
new file mode 100644
index 0000000..3672edb
--- /dev/null
+++ b/internal/transport/http/dto/flight_prep_check_dto.go
@@ -0,0 +1,73 @@
+package dto
+
+import (
+	"time"
+
+	flightprepcheck "wucher/internal/domain/flight_prep_check"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type FlightPrepCheckAttributes struct {
+	ID                    string `json:"id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	FlightInspectionID    string `json:"flight_inspection_id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	NotamBriefing         bool   `json:"notam_briefing" example:"true"`
+	WeatherBriefing       bool   `json:"weather_briefing" example:"false"`
+	OperationalFlightPlan bool   `json:"operational_flight_plan" example:"true"`
+	CreatedAt             string `json:"created_at,omitempty" example:"2026-04-09T05:00:00Z"`
+	UpdatedAt             string `json:"updated_at,omitempty" example:"2026-04-09T05:00:00Z"`
+}
+
+type FlightPrepCheckResource struct {
+	Type       string                    `json:"type" example:"flight_prep_check"`
+	ID         string                    `json:"id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	Attributes FlightPrepCheckAttributes `json:"attributes"`
+}
+
+type FlightPrepCheckResponse struct {
+	Data FlightPrepCheckResource `json:"data"`
+}
+
+type FlightPrepCheckUpsertRequest struct {
+	Data struct {
+		Type       string                          `json:"type" validate:"required,oneof=flight_prep_check_upsert flight_prep_check" example:"flight_prep_check_upsert"`
+		Attributes FlightPrepCheckUpsertAttributes `json:"attributes" validate:"required"`
+	} `json:"data" validate:"required"`
+}
+
+type FlightPrepCheckUpsertAttributes struct {
+	NotamBriefing         *bool `json:"notam_briefing,omitempty" example:"true"`
+	WeatherBriefing       *bool `json:"weather_briefing,omitempty" example:"true"`
+	OperationalFlightPlan *bool `json:"operational_flight_plan,omitempty" example:"false"`
+}
+
+func ToFlightPrepCheckDTO(check *flightprepcheck.FlightPrepCheck) *FlightPrepCheckResource {
+	if check == nil {
+		return nil
+	}
+
+	idStr, _ := uuidv7.BytesToString(check.ID)
+	flightInspectionIDStr, _ := uuidv7.BytesToString(check.FlightInspectionID)
+
+	createdAt := ""
+	updatedAt := ""
+	if !check.CreatedAt.IsZero() {
+		createdAt = check.CreatedAt.UTC().Format(time.RFC3339)
+	}
+	if !check.UpdatedAt.IsZero() {
+		updatedAt = check.UpdatedAt.UTC().Format(time.RFC3339)
+	}
+
+	return &FlightPrepCheckResource{
+		Type: "flight_prep_check",
+		ID:   idStr,
+		Attributes: FlightPrepCheckAttributes{
+			ID:                    idStr,
+			FlightInspectionID:    flightInspectionIDStr,
+			NotamBriefing:         check.NOTAMBriefing,
+			WeatherBriefing:       check.WeatherBriefing,
+			OperationalFlightPlan: check.OperationalFlightPlan,
+			CreatedAt:             createdAt,
+			UpdatedAt:             updatedAt,
+		},
+	}
+}
diff --git a/internal/transport/http/dto/fm_report_dto.go b/internal/transport/http/dto/fm_report_dto.go
new file mode 100644
index 0000000..1b72506
--- /dev/null
+++ b/internal/transport/http/dto/fm_report_dto.go
@@ -0,0 +1,100 @@
+package dto
+
+import responsedto "wucher/internal/transport/http/dto/response"
+
+type FMReportAttributes struct {
+	ID                    string                             `json:"id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	ReportCode            *string                            `json:"report_code" example:"EC-135-1"`
+	TakeoverID            string                             `json:"takeover_id,omitempty" example:"019e8713-aa19-7fb7-a510-a0332dc69697"`
+	FlightID              string                             `json:"flight_id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	FlightInspectionID    string                             `json:"flight_inspection_id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	Engine1GpcN1          *string                            `json:"engine1_gpc_n1" example:"GPC/N1 63.2"`
+	Engine1PtcN2          *string                            `json:"engine1_ptc_n2" example:"PTC/N2 61.8"`
+	Engine2GpcN1          *string                            `json:"engine2_gpc_n1" example:"GPC/N1 62.9"`
+	Engine2PtcN2          *string                            `json:"engine2_ptc_n2" example:"PTC/N2 61.5"`
+	CompletedAt           string                             `json:"completed_at,omitempty" example:"2026-04-20T10:15:00Z"`
+	CompletedBy           string                             `json:"completed_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	PilotName             *string                            `json:"pilot_name,omitempty" example:"John Doe"`
+	HelicopterIdentifier  *string                            `json:"helicopter_identifier,omitempty" example:"OE-TEST"`
+	Flight                *responsedto.FlightResource        `json:"flight,omitempty"`
+	Missions              []responsedto.MissionResource      `json:"missions,omitempty"`
+	FlightInspection      *FlightInspectionResource          `json:"flight_inspection,omitempty"`
+	AfterFlightInspection *AfterFlightInspectionResource     `json:"after_flight_inspection,omitempty"`
+	FleetStatus           *responsedto.FleetStatusResource   `json:"fleet_status,omitempty"`
+	HelicopterUsage       *HelicopterUsageResource           `json:"helicopter_usage,omitempty"`
+	UsageBreakdown        *FMReportUsageBreakdown            `json:"usage_breakdown,omitempty"`
+	TakeoverFiles         []responsedto.TakeoverFileResource `json:"takeover_files,omitempty"`
+	FMReportAttachments   *FMReportAttachments               `json:"fm_report_attachments,omitempty"`
+	CreatedAt             string                             `json:"created_at,omitempty" example:"2026-04-20T08:00:00Z"`
+	UpdatedAt             string                             `json:"updated_at,omitempty" example:"2026-04-20T08:00:00Z"`
+}
+
+type FMReportAirframeValues struct {
+	Hours  float64 `json:"hours" example:"1523.5"`
+	Cycles float64 `json:"cycles" example:"320"`
+}
+
+type FMReportEngineValues struct {
+	Hours   float64 `json:"hours" example:"1523.5"`
+	GpcNgN1 float64 `json:"gpc_ng_n1" example:"63.2"`
+	PtcNfN2 float64 `json:"ptc_nf_n2" example:"61.8"`
+	Ccc     float64 `json:"ccc" example:"44"`
+}
+
+// FMReportCountersValues are the "Landings, Complaints & Sign-off" counters.
+type FMReportCountersValues struct {
+	Landings         float64 `json:"landings" example:"120"`
+	FlightReports    float64 `json:"flight_reports" example:"80"`
+	HookReleases     float64 `json:"hook_releases" example:"10"`
+	RotorBrakeCycles float64 `json:"rotor_brake_cycles" example:"8"`
+}
+
+// FMReportUsageSnapshot is one row of the breakdown table (all columns for a single
+// prev/today/total bucket). An absent engine (single-engine aircraft) stays zero-valued.
+type FMReportUsageSnapshot struct {
+	Airframe FMReportAirframeValues `json:"airframe"`
+	Engine1  FMReportEngineValues   `json:"engine_1"`
+	Engine2  FMReportEngineValues   `json:"engine_2"`
+	Counters FMReportCountersValues `json:"counters"`
+}
+
+// FMReportUsageBreakdown is the prev/today/total table shown on the FM report page,
+// grouped by row: prev = total - today (the prior-day cumulative), today = this flight's
+// contribution, total = the cumulative to date.
+type FMReportUsageBreakdown struct {
+	Prev  FMReportUsageSnapshot `json:"prev"`
+	Today FMReportUsageSnapshot `json:"today"`
+	Total FMReportUsageSnapshot `json:"total"`
+}
+
+type FMReportAttachments struct {
+	AdditionalFMReport []FMReportAttachmentItem `json:"additional_fm_report,omitempty"`
+	Briefing           []FMReportAttachmentItem `json:"briefing,omitempty"`
+	WeightBalance      []FMReportAttachmentItem `json:"weight_balance,omitempty"`
+	OFP                []FMReportAttachmentItem `json:"ofp,omitempty"`
+}
+
+type FMReportAttachmentItem struct {
+	ID          string  `json:"id"`
+	FileID      string  `json:"file_id"`
+	DownloadURL *string `json:"download_url,omitempty"`
+}
+
+type FMReportResource struct {
+	Type       string             `json:"type" example:"fm_report"`
+	ID         string             `json:"id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	Attributes FMReportAttributes `json:"attributes"`
+}
+
+type FMReportResponse struct {
+	Data FMReportResource `json:"data"`
+}
+
+type FMReportListResponse struct {
+	Data []FMReportResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/forces_present_dto.go b/internal/transport/http/dto/forces_present_dto.go
new file mode 100644
index 0000000..329950a
--- /dev/null
+++ b/internal/transport/http/dto/forces_present_dto.go
@@ -0,0 +1,77 @@
+package dto
+
+// JSON:API Forces Present DTOs
+
+type ForcesPresentAttributes struct {
+	Name      string `json:"name" example:"Firefighter Team A"`
+	SortKey   *int   `json:"sortkey" example:"1"`
+	Note      string `json:"note,omitempty" example:"On-site responders"`
+	IsActive  bool   `json:"is_active" example:"true"`
+	CreatedAt string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy string `json:"created_by" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy string `json:"updated_by" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt string `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy string `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type ForcesPresentResource struct {
+	Type       string                  `json:"type" example:"forces_present"`
+	ID         string                  `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes ForcesPresentAttributes `json:"attributes"`
+}
+
+type ForcesPresentResponse struct {
+	Data ForcesPresentResource `json:"data"`
+}
+
+type ForcesPresentListResponse struct {
+	Data []ForcesPresentResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type ForcesPresentDataTableResponse struct {
+	Data []ForcesPresentResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type ForcesPresentCreateAttributes struct {
+	Name     string  `json:"name" validate:"required" example:"Firefighter Team A"`
+	SortKey  *int    `json:"sortkey" example:"1"`
+	Note     *string `json:"note,omitempty" example:"On-site responders"`
+	IsActive *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type ForcesPresentCreateData struct {
+	Type       string                        `json:"type" validate:"required,oneof=forces_present_create forces_present" example:"forces_present_create"`
+	Attributes ForcesPresentCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type ForcesPresentCreateRequest struct {
+	Data ForcesPresentCreateData `json:"data" validate:"required"`
+}
+
+type ForcesPresentUpdateAttributes struct {
+	Name     *string `json:"name,omitempty" example:"Firefighter Team A"`
+	SortKey  NullInt `json:"sortkey,omitempty" swaggertype:"integer" example:"1"`
+	Note     *string `json:"note,omitempty" example:"On-site responders"`
+	IsActive *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type ForcesPresentUpdateData struct {
+	Type       string                        `json:"type" validate:"required,oneof=forces_present_update forces_present" example:"forces_present_update"`
+	ID         string                        `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes ForcesPresentUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type ForcesPresentUpdateRequest struct {
+	Data ForcesPresentUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/health_insurance_companies_dto.go b/internal/transport/http/dto/health_insurance_companies_dto.go
new file mode 100644
index 0000000..87af9ef
--- /dev/null
+++ b/internal/transport/http/dto/health_insurance_companies_dto.go
@@ -0,0 +1,96 @@
+package dto
+
+// JSON:API Health Insurance Companies DTOs
+
+type HealthInsuranceCompanyAttributes struct {
+	LandID         string `json:"land_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FederalStateID string `json:"federal_state_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FederalState   string `json:"federal_state,omitempty" example:"Bayern"`
+	LandName       string `json:"land_name" example:"Germany"`
+	LandISOCode    string `json:"land_iso_code,omitempty" example:"DE"`
+	Name           string `json:"name" example:"ABC Insurance"`
+	SortKey        *int   `json:"sortkey" example:"1"`
+	State          string `json:"state,omitempty" example:"Berlin"`
+	Address        string `json:"address,omitempty" example:"Main Street 10"`
+	MobileNumber   string `json:"mobile_number,omitempty" example:"+4912345678"`
+	Email          string `json:"email,omitempty" example:"info@abc-insurance.local"`
+	Note           string `json:"note,omitempty" example:"Preferred insurance provider"`
+	IsActive       bool   `json:"is_active" example:"true"`
+	CreatedAt      string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy      string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt      string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy      string `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt      string `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy      string `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type HealthInsuranceCompanyResource struct {
+	Type       string                           `json:"type" example:"health_insurance_company"`
+	ID         string                           `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes HealthInsuranceCompanyAttributes `json:"attributes"`
+}
+
+type HealthInsuranceCompanyResponse struct {
+	Data HealthInsuranceCompanyResource `json:"data"`
+}
+
+type HealthInsuranceCompanyListResponse struct {
+	Data []HealthInsuranceCompanyResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type HealthInsuranceCompanyDataTableResponse struct {
+	Data []HealthInsuranceCompanyResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type HealthInsuranceCompanyCreateAttributes struct {
+	Name         string  `json:"name" validate:"required" example:"ABC Insurance"`
+	SortKey      *int    `json:"sortkey" example:"1"`
+	LandID       *string `json:"land_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	State        *string `json:"state,omitempty" example:"Berlin"`
+	Address      *string `json:"address,omitempty" example:"Main Street 10"`
+	MobileNumber *string `json:"mobile_number,omitempty" example:"+4912345678"`
+	Email        *string `json:"email,omitempty" example:"info@abc-insurance.local"`
+	Note         *string `json:"note,omitempty" example:"Preferred insurance provider"`
+	IsActive     *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type HealthInsuranceCompanyCreateData struct {
+	Type       string                                 `json:"type" validate:"required,oneof=health_insurance_company_create health_insurance_company" example:"health_insurance_company_create"`
+	Attributes HealthInsuranceCompanyCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type HealthInsuranceCompanyCreateRequest struct {
+	Data HealthInsuranceCompanyCreateData `json:"data" validate:"required"`
+}
+
+type HealthInsuranceCompanyUpdateAttributes struct {
+	Name         *string `json:"name,omitempty" example:"ABC Insurance"`
+	SortKey      NullInt `json:"sortkey,omitempty" swaggertype:"integer" example:"1"`
+	LandID       *string `json:"land_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	State        *string `json:"state,omitempty" example:"Berlin"`
+	Address      *string `json:"address,omitempty" example:"Main Street 10"`
+	MobileNumber *string `json:"mobile_number,omitempty" example:"+4912345678"`
+	Email        *string `json:"email,omitempty" example:"info@abc-insurance.local"`
+	Note         *string `json:"note,omitempty" example:"Preferred insurance provider"`
+	IsActive     *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type HealthInsuranceCompanyUpdateData struct {
+	Type       string                                 `json:"type" validate:"required,oneof=health_insurance_company_update health_insurance_company" example:"health_insurance_company_update"`
+	ID         string                                 `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes HealthInsuranceCompanyUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type HealthInsuranceCompanyUpdateRequest struct {
+	Data HealthInsuranceCompanyUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/helicopter_usage_dto.go b/internal/transport/http/dto/helicopter_usage_dto.go
new file mode 100644
index 0000000..4574a01
--- /dev/null
+++ b/internal/transport/http/dto/helicopter_usage_dto.go
@@ -0,0 +1,101 @@
+package dto
+
+// JSON:API Helicopter Usage DTOs
+
+type HelicopterUsageAttributes struct {
+	HelicopterID         string  `json:"helicopter_id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	TotalLanding         float64     `json:"total_landing" example:"120"`
+	TotalAirframeHours   float64 `json:"total_airframe_hours" example:"1523.5"`
+	TotalAirframeCycles  float64     `json:"total_airframe_cycles" example:"320"`
+	TotalEngine1Hours    float64 `json:"total_engine_1_hours" example:"1523.5"`
+	TotalEngine1GpcNgN1  float64 `json:"total_engine_1_gpc_ng_n1" example:"98.7"`
+	TotalEngine1PtcNfN2  float64 `json:"total_engine_1_ptc_nf_n2" example:"97.2"`
+	TotalEngine1Ccc      float64     `json:"total_engine_1_ccc" example:"44"`
+	TotalEngine2Hours    float64 `json:"total_engine_2_hours" example:"1523.5"`
+	TotalEngine2GpcNgN1  float64 `json:"total_engine_2_gpc_ng_n1" example:"98.7"`
+	TotalEngine2PtcNfN2  float64 `json:"total_engine_2_ptc_nf_n2" example:"97.2"`
+	TotalEngine2Ccc      float64     `json:"total_engine_2_ccc" example:"44"`
+	TotalFlightReport    float64     `json:"total_flight_report" example:"80"`
+	TotalHookRelease     float64     `json:"total_hook_release" example:"10"`
+	TotalRotorBrakeCycle float64     `json:"total_rotor_brake_cycle" example:"8"`
+	CreatedAt            string  `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy            string  `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt            string  `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy            string  `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt            string  `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy            string  `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type HelicopterUsageResource struct {
+	Type       string                    `json:"type" example:"helicopter_usage"`
+	ID         string                    `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes HelicopterUsageAttributes `json:"attributes"`
+}
+
+type HelicopterUsageResponse struct {
+	Data HelicopterUsageResource `json:"data"`
+}
+
+type HelicopterUsageListResponse struct {
+	Data []HelicopterUsageResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type HelicopterUsageCreateAttributes struct {
+	HelicopterID         string   `json:"helicopter_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	TotalLanding         *float64     `json:"total_landing,omitempty" example:"120"`
+	TotalAirframeHours   *float64 `json:"total_airframe_hours,omitempty" example:"1523.5"`
+	TotalAirframeCycles  *float64     `json:"total_airframe_cycles,omitempty" example:"320"`
+	TotalEngine1Hours    *float64 `json:"total_engine_1_hours,omitempty" example:"1523.5"`
+	TotalEngine1GpcNgN1  *float64 `json:"total_engine_1_gpc_ng_n1,omitempty" example:"98.7"`
+	TotalEngine1PtcNfN2  *float64 `json:"total_engine_1_ptc_nf_n2,omitempty" example:"97.2"`
+	TotalEngine1Ccc      *float64     `json:"total_engine_1_ccc,omitempty" example:"44"`
+	TotalEngine2Hours    *float64 `json:"total_engine_2_hours,omitempty" example:"1523.5"`
+	TotalEngine2GpcNgN1  *float64 `json:"total_engine_2_gpc_ng_n1,omitempty" example:"98.7"`
+	TotalEngine2PtcNfN2  *float64 `json:"total_engine_2_ptc_nf_n2,omitempty" example:"97.2"`
+	TotalEngine2Ccc      *float64     `json:"total_engine_2_ccc,omitempty" example:"44"`
+	TotalFlightReport    *float64     `json:"total_flight_report,omitempty" example:"80"`
+	TotalHookRelease     *float64     `json:"total_hook_release,omitempty" example:"10"`
+	TotalRotorBrakeCycle *float64     `json:"total_rotor_brake_cycle,omitempty" example:"8"`
+}
+
+type HelicopterUsageCreateData struct {
+	Type       string                          `json:"type" validate:"required,oneof=helicopter_usage_create helicopter_usage" example:"helicopter_usage_create"`
+	Attributes HelicopterUsageCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type HelicopterUsageCreateRequest struct {
+	Data HelicopterUsageCreateData `json:"data" validate:"required"`
+}
+
+type HelicopterUsageUpdateAttributes struct {
+	HelicopterID         *string  `json:"helicopter_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	TotalLanding         *float64     `json:"total_landing,omitempty" example:"120"`
+	TotalAirframeHours   *float64 `json:"total_airframe_hours,omitempty" example:"1523.5"`
+	TotalAirframeCycles  *float64     `json:"total_airframe_cycles,omitempty" example:"320"`
+	TotalEngine1Hours    *float64 `json:"total_engine_1_hours,omitempty" example:"1523.5"`
+	TotalEngine1GpcNgN1  *float64 `json:"total_engine_1_gpc_ng_n1,omitempty" example:"98.7"`
+	TotalEngine1PtcNfN2  *float64 `json:"total_engine_1_ptc_nf_n2,omitempty" example:"97.2"`
+	TotalEngine1Ccc      *float64     `json:"total_engine_1_ccc,omitempty" example:"44"`
+	TotalEngine2Hours    *float64 `json:"total_engine_2_hours,omitempty" example:"1523.5"`
+	TotalEngine2GpcNgN1  *float64 `json:"total_engine_2_gpc_ng_n1,omitempty" example:"98.7"`
+	TotalEngine2PtcNfN2  *float64 `json:"total_engine_2_ptc_nf_n2,omitempty" example:"97.2"`
+	TotalEngine2Ccc      *float64     `json:"total_engine_2_ccc,omitempty" example:"44"`
+	TotalFlightReport    *float64     `json:"total_flight_report,omitempty" example:"80"`
+	TotalHookRelease     *float64     `json:"total_hook_release,omitempty" example:"10"`
+	TotalRotorBrakeCycle *float64     `json:"total_rotor_brake_cycle,omitempty" example:"8"`
+}
+
+type HelicopterUsageUpdateData struct {
+	Type       string                          `json:"type" validate:"required,oneof=helicopter_usage_update helicopter_usage" example:"helicopter_usage_update"`
+	ID         string                          `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes HelicopterUsageUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type HelicopterUsageUpdateRequest struct {
+	Data HelicopterUsageUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/hems_operation_category_dto.go b/internal/transport/http/dto/hems_operation_category_dto.go
new file mode 100644
index 0000000..bc4d6fa
--- /dev/null
+++ b/internal/transport/http/dto/hems_operation_category_dto.go
@@ -0,0 +1,70 @@
+package dto
+
+// JSON:API HEMS Operation Category DTOs
+
+type HEMSOperationCategoryAttributes struct {
+	Name      string `json:"name" example:"Firefighting"`
+	Type      string `json:"type" example:"first"`
+	CreatedAt string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy string `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt string `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy string `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type HEMSOperationCategoryResource struct {
+	Type       string                          `json:"type" example:"hems_operation_category"`
+	ID         string                          `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes HEMSOperationCategoryAttributes `json:"attributes"`
+}
+
+type HEMSOperationCategoryResponse struct {
+	Data HEMSOperationCategoryResource `json:"data"`
+}
+
+type HEMSOperationCategoryListResponse struct {
+	Data []HEMSOperationCategoryResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type HEMSOperationCategoryDataTableResponse struct {
+	Data []HEMSOperationCategoryResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type HEMSOperationCategoryCreateAttributes struct {
+	Name string `json:"name" validate:"required" example:"Firefighting"`
+	Type string `json:"type" validate:"required,oneof=first secondary misuse" example:"first"`
+}
+
+type HEMSOperationCategoryCreateData struct {
+	Type       string                                `json:"type" validate:"required,oneof=hems_operation_category_create hems_operation_category" example:"hems_operation_category_create"`
+	Attributes HEMSOperationCategoryCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type HEMSOperationCategoryCreateRequest struct {
+	Data HEMSOperationCategoryCreateData `json:"data" validate:"required"`
+}
+
+type HEMSOperationCategoryUpdateAttributes struct {
+	Name *string `json:"name,omitempty" example:"Firefighting"`
+	Type *string `json:"type,omitempty" validate:"omitempty,oneof=first secondary misuse" example:"first"`
+}
+
+type HEMSOperationCategoryUpdateData struct {
+	Type       string                                `json:"type" validate:"required,oneof=hems_operation_category_update hems_operation_category" example:"hems_operation_category_update"`
+	Attributes HEMSOperationCategoryUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type HEMSOperationCategoryUpdateRequest struct {
+	Data HEMSOperationCategoryUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/hems_operation_dto.go b/internal/transport/http/dto/hems_operation_dto.go
new file mode 100644
index 0000000..5f8a580
--- /dev/null
+++ b/internal/transport/http/dto/hems_operation_dto.go
@@ -0,0 +1,95 @@
+package dto
+
+// JSON:API HEMS Operation DTOs
+
+type HEMSOperationOperationalDataRef struct {
+	ID string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type HEMSOperationCategoryRef struct {
+	ID   string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name string `json:"name,omitempty" example:"Firefighting"`
+	Type string `json:"type,omitempty" example:"first"`
+}
+
+type HEMSOperationMissionRef struct {
+	ID       string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FlightID string `json:"flight_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Type     string `json:"type,omitempty" example:"HEMS"`
+}
+
+type HEMSOperationAttributes struct {
+	Date                    string                           `json:"date" example:"2026-03-12T03:04:05Z"`
+	OperationalDataID       string                           `json:"operational_data_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	MissionID               string                           `json:"mission_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	HEMSOperationCategoryID string                           `json:"hems_operation_category_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	OperationalData         *HEMSOperationOperationalDataRef `json:"operational_data,omitempty"`
+	Mission                 *HEMSOperationMissionRef         `json:"mission,omitempty"`
+	HEMSOperationCategory   *HEMSOperationCategoryRef        `json:"hems_operation_category,omitempty"`
+	CreatedAt               string                           `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy               string                           `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt               string                           `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy               string                           `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt               string                           `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy               string                           `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type HEMSOperationResource struct {
+	Type       string                  `json:"type" example:"hems_operation"`
+	ID         string                  `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes HEMSOperationAttributes `json:"attributes"`
+}
+
+type HEMSOperationResponse struct {
+	Data HEMSOperationResource `json:"data"`
+}
+
+type HEMSOperationListResponse struct {
+	Data []HEMSOperationResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type HEMSOperationDataTableResponse struct {
+	Data []HEMSOperationResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type HEMSOperationCreateAttributes struct {
+	Date                    string  `json:"date" validate:"required" example:"2026-03-12T03:04:05Z"`
+	OperationalDataID       *string `json:"operational_data_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	MissionID               *string `json:"mission_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	HEMSOperationCategoryID *string `json:"hems_operation_category_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type HEMSOperationCreateData struct {
+	Type       string                        `json:"type" validate:"required,oneof=hems_operation_create hems_operation" example:"hems_operation_create"`
+	Attributes HEMSOperationCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type HEMSOperationCreateRequest struct {
+	Data HEMSOperationCreateData `json:"data" validate:"required"`
+}
+
+type HEMSOperationUpdateAttributes struct {
+	Date                    *string `json:"date,omitempty" example:"2026-03-12T03:04:05Z"`
+	OperationalDataID       *string `json:"operational_data_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	MissionID               *string `json:"mission_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	HEMSOperationCategoryID *string `json:"hems_operation_category_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type HEMSOperationUpdateData struct {
+	Type       string                        `json:"type" validate:"required,oneof=hems_operation_update hems_operation" example:"hems_operation_update"`
+	Attributes HEMSOperationUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type HEMSOperationUpdateRequest struct {
+	Data HEMSOperationUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/hems_operational_data_dto.go b/internal/transport/http/dto/hems_operational_data_dto.go
new file mode 100644
index 0000000..ee4bd28
--- /dev/null
+++ b/internal/transport/http/dto/hems_operational_data_dto.go
@@ -0,0 +1,141 @@
+package dto
+
+// JSON:API HEMS Operational Data DTOs
+
+type HEMSOperationalDataFileAttributes struct {
+	ID               string `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FileAttachmentID string `json:"file_attachment_id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type HEMSOperationalDataAttributes struct {
+	Time              string                              `json:"time" example:"2026-03-12T03:04:05Z"`
+	LandID            string                              `json:"land_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	VocationID        string                              `json:"vocation_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	ForcePresentIDs   []string                            `json:"force_present_ids,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	StateID           string                              `json:"state_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Location          string                              `json:"location" example:"123 Main St, Anytown, USA"`
+	Postcode          string                              `json:"postcode,omitempty" example:"12345"`
+	Notes             string                              `json:"notes" example:"Notes about the operational data"`
+	Darkness          bool                                `json:"darkness"`
+	FalseInformation  bool                                `json:"false_information"`
+	Fog               bool                                `json:"fog"`
+	Precipitation     bool                                `json:"precipitation"`
+	MountainUse       bool                                `json:"mountain_use"`
+	Wind              bool                                `json:"wind"`
+	NFOSearch         bool                                `json:"nfo_search"`
+	LandingSiteSearch bool                                `json:"landing_site_search"`
+	Temperature       float64                             `json:"temperature" example:"23.5"`
+	Altitude          float64                             `json:"altitude" example:"5.2"`
+	TerrainIndex      string                              `json:"terrain_index" example:"Only helicopter landing"`
+	RopeRecovery      bool                                `json:"rope_recovery"`
+	NightFlight       bool                                `json:"night_flight"`
+	InstrumentFlight  bool                                `json:"instrument_flight"`
+	AdditionalInfo    string                              `json:"additional_info" example:"Additional information about the operational data"`
+	Files             []HEMSOperationalDataFileAttributes `json:"files,omitempty"`
+	CreatedAt         string                              `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy         string                              `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt         string                              `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy         string                              `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt         string                              `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy         string                              `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type HEMSOperationalDataResource struct {
+	Type       string                        `json:"type" example:"hems_operational_data"`
+	ID         string                        `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes HEMSOperationalDataAttributes `json:"attributes"`
+}
+
+type HEMSOperationalDataResponse struct {
+	Data HEMSOperationalDataResource `json:"data"`
+}
+
+type HEMSOperationalDataListResponse struct {
+	Data []HEMSOperationalDataResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type HEMSOperationalDataDataTableResponse struct {
+	Data []HEMSOperationalDataResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type HEMSOperationalDataCreateAttributes struct {
+	Time              string   `json:"time" validate:"required" example:"2026-03-12T03:04:05Z"`
+	LandID            *string  `json:"land_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	VocationID        *string  `json:"vocation_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	ForcePresentIDs   []string `json:"force_present_ids,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	StateID           *string  `json:"state_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Location          string   `json:"location" validate:"required" example:"123 Main St, Anytown, USA"`
+	Postcode          *string  `json:"postcode,omitempty" example:"12345"`
+	Notes             *string  `json:"notes,omitempty" example:"Notes about the operational data"`
+	Darkness          *bool    `json:"darkness,omitempty"`
+	FalseInformation  *bool    `json:"false_information,omitempty"`
+	Fog               *bool    `json:"fog,omitempty"`
+	Precipitation     *bool    `json:"precipitation,omitempty"`
+	MountainUse       *bool    `json:"mountain_use,omitempty"`
+	Wind              *bool    `json:"wind,omitempty"`
+	NFOSearch         *bool    `json:"nfo_search,omitempty"`
+	LandingSiteSearch *bool    `json:"landing_site_search,omitempty"`
+	Temperature       *float64 `json:"temperature,omitempty" example:"23.5"`
+	Altitude          *float64 `json:"altitude,omitempty" example:"5.2"`
+	TerrainIndex      *string  `json:"terrain_index,omitempty" example:"Only helicopter landing"`
+	RopeRecovery      *bool    `json:"rope_recovery,omitempty"`
+	NightFlight       *bool    `json:"night_flight,omitempty"`
+	InstrumentFlight  *bool    `json:"instrument_flight,omitempty"`
+	AdditionalInfo    *string  `json:"additional_info,omitempty" example:"Additional information about the operational data"`
+	FileAttachmentIDs []string `json:"file_attachment_ids,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type HEMSOperationalDataCreateData struct {
+	Type       string                              `json:"type" validate:"required,oneof=hems_operational_data_create hems_operational_data" example:"hems_operational_data_create"`
+	Attributes HEMSOperationalDataCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type HEMSOperationalDataCreateRequest struct {
+	Data HEMSOperationalDataCreateData `json:"data" validate:"required"`
+}
+
+type HEMSOperationalDataUpdateAttributes struct {
+	Time              *string   `json:"time,omitempty" example:"2026-03-12T03:04:05Z"`
+	LandID            *string   `json:"land_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	VocationID        *string   `json:"vocation_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	ForcePresentIDs   *[]string `json:"force_present_ids,omitempty"`
+	StateID           *string   `json:"state_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Location          *string   `json:"location,omitempty" example:"123 Main St, Anytown, USA"`
+	Postcode          *string   `json:"postcode,omitempty" example:"12345"`
+	Notes             *string   `json:"notes,omitempty" example:"Notes about the operational data"`
+	Darkness          *bool     `json:"darkness,omitempty"`
+	FalseInformation  *bool     `json:"false_information,omitempty"`
+	Fog               *bool     `json:"fog,omitempty"`
+	Precipitation     *bool     `json:"precipitation,omitempty"`
+	MountainUse       *bool     `json:"mountain_use,omitempty"`
+	Wind              *bool     `json:"wind,omitempty"`
+	NFOSearch         *bool     `json:"nfo_search,omitempty"`
+	LandingSiteSearch *bool     `json:"landing_site_search,omitempty"`
+	Temperature       *float64  `json:"temperature,omitempty" example:"23.5"`
+	Altitude          *float64  `json:"altitude,omitempty" example:"5.2"`
+	TerrainIndex      *string   `json:"terrain_index,omitempty" example:"Only helicopter landing"`
+	RopeRecovery      *bool     `json:"rope_recovery,omitempty"`
+	NightFlight       *bool     `json:"night_flight,omitempty"`
+	InstrumentFlight  *bool     `json:"instrument_flight,omitempty"`
+	AdditionalInfo    *string   `json:"additional_info,omitempty" example:"Additional information about the operational data"`
+	FileAttachmentIDs *[]string `json:"file_attachment_ids,omitempty"`
+}
+
+type HEMSOperationalDataUpdateData struct {
+	Type       string                              `json:"type" validate:"required,oneof=hems_operational_data_update hems_operational_data" example:"hems_operational_data_update"`
+	Attributes HEMSOperationalDataUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type HEMSOperationalDataUpdateRequest struct {
+	Data HEMSOperationalDataUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/hospital_dto.go b/internal/transport/http/dto/hospital_dto.go
new file mode 100644
index 0000000..db67e2b
--- /dev/null
+++ b/internal/transport/http/dto/hospital_dto.go
@@ -0,0 +1,89 @@
+package dto
+
+// JSON:API Hospital DTOs
+
+type HospitalAttributes struct {
+	Name           string `json:"name" example:"RSUD Kota"`
+	SortKey        *int   `json:"sortkey" example:"1"`
+	Address        string `json:"address,omitempty" example:"Jl. Merdeka No. 10"`
+	LandlineNumber string `json:"landline_number,omitempty" example:"0211234567"`
+	MobileNumber   string `json:"mobile_number,omitempty" example:"08123456789"`
+	Email          string `json:"email,omitempty" example:"info@hospital.local"`
+	Note           string `json:"note,omitempty" example:"Nearest trauma center"`
+	IsActive       bool   `json:"is_active" example:"true"`
+	CreatedAt      string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy      string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt      string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy      string `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt      string `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy      string `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type HospitalResource struct {
+	Type       string             `json:"type" example:"hospital"`
+	ID         string             `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes HospitalAttributes `json:"attributes"`
+}
+
+type HospitalResponse struct {
+	Data HospitalResource `json:"data"`
+}
+
+type HospitalListResponse struct {
+	Data []HospitalResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type HospitalDataTableResponse struct {
+	Data []HospitalResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type HospitalCreateAttributes struct {
+	Name           string  `json:"name" validate:"required" example:"RSUD Kota"`
+	SortKey        *int    `json:"sortkey" example:"1"`
+	Address        *string `json:"address,omitempty" example:"Jl. Merdeka No. 10"`
+	LandlineNumber *string `json:"landline_number,omitempty" example:"0211234567"`
+	MobileNumber   *string `json:"mobile_number,omitempty" example:"08123456789"`
+	Email          *string `json:"email,omitempty" example:"info@hospital.local"`
+	Note           *string `json:"note,omitempty" example:"Nearest trauma center"`
+	IsActive       *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type HospitalCreateData struct {
+	Type       string                   `json:"type" validate:"required,oneof=hospital_create hospital" example:"hospital_create"`
+	Attributes HospitalCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type HospitalCreateRequest struct {
+	Data HospitalCreateData `json:"data" validate:"required"`
+}
+
+type HospitalUpdateAttributes struct {
+	Name           *string `json:"name,omitempty" example:"RSUD Kota"`
+	SortKey        NullInt `json:"sortkey,omitempty" swaggertype:"integer" example:"1"`
+	Address        *string `json:"address,omitempty" example:"Jl. Merdeka No. 10"`
+	LandlineNumber *string `json:"landline_number,omitempty" example:"0211234567"`
+	MobileNumber   *string `json:"mobile_number,omitempty" example:"08123456789"`
+	Email          *string `json:"email,omitempty" example:"info@hospital.local"`
+	Note           *string `json:"note,omitempty" example:"Nearest trauma center"`
+	IsActive       *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type HospitalUpdateData struct {
+	Type       string                   `json:"type" validate:"required,oneof=hospital_update hospital" example:"hospital_update"`
+	ID         string                   `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes HospitalUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type HospitalUpdateRequest struct {
+	Data HospitalUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/icao_dto.go b/internal/transport/http/dto/icao_dto.go
new file mode 100644
index 0000000..5456555
--- /dev/null
+++ b/internal/transport/http/dto/icao_dto.go
@@ -0,0 +1,101 @@
+package dto
+
+// JSON:API ICAO DTOs
+
+type ICAOAttributes struct {
+	LandID         string `json:"land_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FederalStateID string `json:"federal_state_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FederalState   string `json:"federal_state,omitempty" example:"Bayern"`
+	LandName       string `json:"land_name,omitempty" example:"Germany"`
+	LandISOCode    string `json:"land_iso_code,omitempty" example:"DE"`
+	ICAOCode       string `json:"icao_code" example:"EDDB"`
+	Name           string `json:"name,omitempty" example:"Berlin Base"`
+	SortKey        *int   `json:"sortkey" example:"1"`
+	Address        string `json:"address,omitempty" example:"Muehlenstrasse 1"`
+	LandlineNumber string `json:"landline_number,omitempty" example:"030123456"`
+	MobileNumber   string `json:"mobile_number,omitempty" example:"0170123456"`
+	Email          string `json:"email,omitempty" example:"ops@example.local"`
+	Note           string `json:"note,omitempty" example:"Night operations supported"`
+	IsActive       bool   `json:"is_active" example:"true"`
+	CreatedAt      string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy      string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt      string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy      string `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt      string `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy      string `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type ICAOResource struct {
+	Type       string         `json:"type" example:"icao"`
+	ID         string         `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes ICAOAttributes `json:"attributes"`
+}
+
+type ICAOResponse struct {
+	Data ICAOResource `json:"data"`
+}
+
+type ICAOListResponse struct {
+	Data []ICAOResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type ICAODataTableResponse struct {
+	Data []ICAOResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type ICAOCreateAttributes struct {
+	LandID         *string `json:"land_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FederalStateID *string `json:"federal_state_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	ICAOCode       string  `json:"icao_code" validate:"required" example:"EDDB"`
+	Name           *string `json:"name,omitempty" example:"Berlin Base"`
+	SortKey        *int    `json:"sortkey" example:"1"`
+	Address        *string `json:"address,omitempty" example:"Muehlenstrasse 1"`
+	LandlineNumber *string `json:"landline_number,omitempty" example:"030123456"`
+	MobileNumber   *string `json:"mobile_number,omitempty" example:"0170123456"`
+	Email          *string `json:"email,omitempty" example:"ops@example.local"`
+	Note           *string `json:"note,omitempty" example:"Night operations supported"`
+	IsActive       *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type ICAOCreateData struct {
+	Type       string               `json:"type" validate:"required,oneof=icao_create icao" example:"icao_create"`
+	Attributes ICAOCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type ICAOCreateRequest struct {
+	Data ICAOCreateData `json:"data" validate:"required"`
+}
+
+type ICAOUpdateAttributes struct {
+	LandID         *string `json:"land_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FederalStateID *string `json:"federal_state_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	ICAOCode       *string `json:"icao_code,omitempty" example:"EDDB"`
+	Name           *string `json:"name,omitempty" example:"Berlin Base"`
+	SortKey        NullInt `json:"sortkey,omitempty" swaggertype:"integer" example:"1"`
+	Address        *string `json:"address,omitempty" example:"Muehlenstrasse 1"`
+	LandlineNumber *string `json:"landline_number,omitempty" example:"030123456"`
+	MobileNumber   *string `json:"mobile_number,omitempty" example:"0170123456"`
+	Email          *string `json:"email,omitempty" example:"ops@example.local"`
+	Note           *string `json:"note,omitempty" example:"Night operations supported"`
+	IsActive       *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type ICAOUpdateData struct {
+	Type       string               `json:"type" validate:"required,oneof=icao_update icao" example:"icao_update"`
+	ID         string               `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes ICAOUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type ICAOUpdateRequest struct {
+	Data ICAOUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/insurance_patient_data_dto.go b/internal/transport/http/dto/insurance_patient_data_dto.go
new file mode 100644
index 0000000..ddef8a9
--- /dev/null
+++ b/internal/transport/http/dto/insurance_patient_data_dto.go
@@ -0,0 +1,87 @@
+package dto
+
+// JSON:API InsurancePatientData DTOs
+
+type InsurancePatientDataHealthInsuranceCompany struct {
+	ID           string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name         string `json:"name,omitempty" example:"ABC Insurance"`
+	State        string `json:"state,omitempty" example:"Berlin"`
+	Address      string `json:"address,omitempty" example:"Main Street 10"`
+	MobileNumber string `json:"mobile_number,omitempty" example:"+4912345678"`
+	Email        string `json:"email,omitempty" example:"info@abc-insurance.local"`
+}
+
+type InsurancePatientDataFederalState struct {
+	ID   string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name string `json:"name,omitempty" example:"Bayern"`
+}
+
+type InsurancePatientDataAttributes struct {
+	HealthInsuranceCompaniesId string                                      `json:"health_insurance_companies_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FederalStateId             string                                      `json:"federal_state_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	HealthInsuranceCompany     *InsurancePatientDataHealthInsuranceCompany `json:"health_insurance_company,omitempty"`
+	FederalState               *InsurancePatientDataFederalState           `json:"federal_state,omitempty"`
+	CreatedAt                  string                                      `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy                  string                                      `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt                  string                                      `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy                  string                                      `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt                  string                                      `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy                  string                                      `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type InsurancePatientDataResource struct {
+	Type       string                         `json:"type" example:"insurance_patient_data"`
+	ID         string                         `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes InsurancePatientDataAttributes `json:"attributes"`
+}
+
+type InsurancePatientDataResponse struct {
+	Data InsurancePatientDataResource `json:"data"`
+}
+
+type InsurancePatientDataListResponse struct {
+	Data []InsurancePatientDataResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type InsurancePatientDataDataTableResponse struct {
+	Data []InsurancePatientDataResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type InsurancePatientDataCreateAttributes struct {
+	HealthInsuranceCompaniesId string `json:"health_insurance_companies_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FederalStateId             string `json:"federal_state_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type InsurancePatientDataCreateData struct {
+	Type       string                               `json:"type" validate:"required,oneof=insurance_patient_data_create insurance_patient_data" example:"insurance_patient_data_create"`
+	Attributes InsurancePatientDataCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type InsurancePatientDataCreateRequest struct {
+	Data InsurancePatientDataCreateData `json:"data" validate:"required"`
+}
+
+type InsurancePatientDataUpdateAttributes struct {
+	HealthInsuranceCompaniesId *string `json:"health_insurance_companies_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FederalStateId             *string `json:"federal_state_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type InsurancePatientDataUpdateData struct {
+	Type       string                               `json:"type" validate:"required,oneof=insurance_patient_data_update insurance_patient_data" example:"insurance_patient_data_update"`
+	ID         string                               `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes InsurancePatientDataUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type InsurancePatientDataUpdateRequest struct {
+	Data InsurancePatientDataUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/land_dto.go b/internal/transport/http/dto/land_dto.go
new file mode 100644
index 0000000..d9ae200
--- /dev/null
+++ b/internal/transport/http/dto/land_dto.go
@@ -0,0 +1,103 @@
+package dto
+
+import "wucher/internal/domain/land"
+
+// JSON:API Land DTOs
+
+type LandAttributes struct {
+	Name              string                `json:"name" example:"Germany"`
+	Note              string                `json:"note,omitempty" example:"Central Europe"`
+	ISOCode           string                `json:"iso_code,omitempty" example:"DE"`
+	BMDExportID       *string               `json:"bmd_export_id,omitempty" example:"DE001"`
+	FederalStateTotal int                   `json:"federal_state_total" example:"2"`
+	FederalStateList  []LandFederalStateDTO `json:"federal_state_list,omitempty"`
+	SortKey           *int                  `json:"sortkey" example:"1"`
+	IsActive          bool                  `json:"is_active" example:"true"`
+	CreatedAt         string                `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy         string                `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt         string                `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy         string                `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt         string                `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy         string                `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type LandFederalStateDTO struct {
+	ID   string `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name string `json:"name" example:"Bayern"`
+}
+
+type LandFederalStateView struct {
+	ID   []byte
+	Name string
+}
+
+type LandView struct {
+	Row               land.Land
+	FederalStateTotal int
+	FederalStateList  []LandFederalStateView
+}
+
+type LandResource struct {
+	Type       string         `json:"type" example:"land"`
+	ID         string         `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes LandAttributes `json:"attributes"`
+}
+
+type LandResponse struct {
+	Data LandResource `json:"data"`
+}
+
+type LandListResponse struct {
+	Data []LandResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type LandDataTableResponse struct {
+	Data []LandResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type LandCreateAttributes struct {
+	Name        string  `json:"name" validate:"required" example:"Germany"`
+	Note        *string `json:"note,omitempty" example:"Central Europe"`
+	ISOCode     string  `json:"iso_code,omitempty" example:"DE"`
+	BMDExportID *string `json:"bmd_export_id,omitempty" example:"DE001"`
+	SortKey     *int    `json:"sortkey" example:"1"`
+	IsActive    *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type LandCreateData struct {
+	Type       string               `json:"type" validate:"required,oneof=land_create land" example:"land_create"`
+	Attributes LandCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type LandCreateRequest struct {
+	Data LandCreateData `json:"data" validate:"required"`
+}
+
+type LandUpdateAttributes struct {
+	Name        *string `json:"name,omitempty" example:"Germany"`
+	Note        *string `json:"note,omitempty" example:"Central Europe"`
+	ISOCode     *string `json:"iso_code,omitempty" example:"DE"`
+	BMDExportID *string `json:"bmd_export_id,omitempty" example:"DE001"`
+	SortKey     NullInt `json:"sortkey,omitempty" swaggertype:"integer" example:"1"`
+	IsActive    *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type LandUpdateData struct {
+	Type       string               `json:"type" validate:"required,oneof=land_update land" example:"land_update"`
+	ID         string               `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes LandUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type LandUpdateRequest struct {
+	Data LandUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/medicine_dto.go b/internal/transport/http/dto/medicine_dto.go
new file mode 100644
index 0000000..6c8c1af
--- /dev/null
+++ b/internal/transport/http/dto/medicine_dto.go
@@ -0,0 +1,263 @@
+package dto
+
+import (
+	"bytes"
+	"encoding/json"
+)
+
+// JSON:API Medicine DTOs
+
+type MedicineAttributes struct {
+	Name             string                  `json:"name" example:"Paracetamol"`
+	SortKey          *int                    `json:"sortkey" example:"1"`
+	Note             string                  `json:"note,omitempty" example:"Main stock medicine"`
+	Pack             string                  `json:"pack,omitempty" example:"500mg"`
+	Unit             string                  `json:"unit,omitempty" example:"tablet"`
+	Column           int64                   `json:"column" example:"1"`
+	MedicineGroupID  string                  `json:"medicine_group_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	MotorReactionID  string                  `json:"motor_reaction_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	MotorReactionIDs []string                `json:"motor_reaction_ids,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	MedicineGroup    *MedicineGroupResource  `json:"medicine_group,omitempty"`
+	MotorReaction    *MotorReactionResource  `json:"motor_reaction,omitempty"`
+	MotorReactions   []MotorReactionResource `json:"motor_reactions,omitempty"`
+	IsActive         bool                    `json:"is_active" example:"true"`
+	CreatedAt        string                  `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy        string                  `json:"created_by" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt        string                  `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy        string                  `json:"updated_by" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt        string                  `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy        string                  `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type MedicineResource struct {
+	Type       string             `json:"type" example:"medicine"`
+	ID         string             `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes MedicineAttributes `json:"attributes"`
+}
+
+type MedicineResponse struct {
+	Data MedicineResource `json:"data"`
+}
+
+type MedicineListResponse struct {
+	Data []MedicineResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type MedicineDataTableResponse struct {
+	Data []MedicineResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type MedicineCreateAttributes struct {
+	Name             string   `json:"name" validate:"required" example:"Paracetamol"`
+	SortKey          *int     `json:"sortkey" example:"1"`
+	Note             *string  `json:"note,omitempty" example:"Main stock medicine"`
+	Pack             *string  `json:"pack,omitempty" example:"500mg"`
+	Unit             *string  `json:"unit,omitempty" validate:"omitempty,max=50" example:"tablet"`
+	Column           *int64   `json:"column,omitempty" example:"1"`
+	MedicineGroupID  *string  `json:"medicine_group_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	MotorReactionID  *string  `json:"motor_reaction_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	MotorReactionIDs []string `json:"motor_reaction_ids,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	IsActive         *bool    `json:"is_active,omitempty" example:"true"`
+}
+
+type MedicineCreateData struct {
+	Type       string                   `json:"type" validate:"required,oneof=medicine_create medicine" example:"medicine_create"`
+	Attributes MedicineCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type MedicineCreateRequest struct {
+	Data MedicineCreateData `json:"data" validate:"required"`
+}
+
+type MedicineUpdateAttributes struct {
+	Name             *string    `json:"name,omitempty" example:"Paracetamol"`
+	SortKey          NullInt    `json:"sortkey,omitempty" swaggertype:"integer" example:"1"`
+	Note             *string    `json:"note,omitempty" example:"Main stock medicine"`
+	Pack             *string    `json:"pack,omitempty" example:"500mg"`
+	Unit             *string    `json:"unit,omitempty" validate:"omitempty,max=50" example:"tablet"`
+	Column           *int64     `json:"column,omitempty" example:"1"`
+	MedicineGroupID  NullString `json:"medicine_group_id,omitempty" swaggertype:"string" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	MotorReactionID  NullString `json:"motor_reaction_id,omitempty" swaggertype:"string" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	MotorReactionIDs []string   `json:"motor_reaction_ids,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	IsActive         *bool      `json:"is_active,omitempty" example:"true"`
+}
+
+type MedicineUpdateData struct {
+	Type       string                   `json:"type" validate:"required,oneof=medicine_update medicine" example:"medicine_update"`
+	ID         string                   `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes MedicineUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type MedicineUpdateRequest struct {
+	Data MedicineUpdateData `json:"data" validate:"required"`
+}
+
+type MedicineGroupAttributes struct {
+	Name      string `json:"name" example:"Spritze"`
+	CreatedAt string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy string `json:"created_by" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy string `json:"updated_by" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt string `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy string `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type MedicineGroupResource struct {
+	Type       string                  `json:"type" example:"medicine_group"`
+	ID         string                  `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes MedicineGroupAttributes `json:"attributes"`
+}
+
+type MedicineGroupResponse struct {
+	Data MedicineGroupResource `json:"data"`
+}
+
+type MedicineGroupListResponse struct {
+	Data []MedicineGroupResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type MedicineGroupDataTableResponse struct {
+	Data []MedicineGroupResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type MedicineGroupCreateAttributes struct {
+	Name string `json:"name" validate:"required" example:"Spritze"`
+}
+
+type MedicineGroupCreateData struct {
+	Type       string                        `json:"type" validate:"required,oneof=medicine_group_create medicine_group" example:"medicine_group_create"`
+	Attributes MedicineGroupCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type MedicineGroupCreateRequest struct {
+	Data MedicineGroupCreateData `json:"data" validate:"required"`
+}
+
+type MedicineGroupUpdateAttributes struct {
+	Name *string `json:"name,omitempty" example:"Spritze"`
+}
+
+type MedicineGroupUpdateData struct {
+	Type       string                        `json:"type" validate:"required,oneof=medicine_group_update medicine_group" example:"medicine_group_update"`
+	ID         string                        `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes MedicineGroupUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type MedicineGroupUpdateRequest struct {
+	Data MedicineGroupUpdateData `json:"data" validate:"required"`
+}
+
+type MotorReactionAttributes struct {
+	Name      string `json:"name" example:"gezielt auf Schmerzreiz"`
+	Score     *int64 `json:"score" example:"5"`
+	CreatedAt string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy string `json:"created_by" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy string `json:"updated_by" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt string `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy string `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type MotorReactionResource struct {
+	Type       string                  `json:"type" example:"motor_reaction"`
+	ID         string                  `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes MotorReactionAttributes `json:"attributes"`
+}
+
+type MotorReactionResponse struct {
+	Data MotorReactionResource `json:"data"`
+}
+
+type MotorReactionListResponse struct {
+	Data []MotorReactionResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type MotorReactionDataTableResponse struct {
+	Data []MotorReactionResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type MotorReactionCreateAttributes struct {
+	Name  string `json:"name" validate:"required" example:"gezielt auf Schmerzreiz"`
+	Score *int64 `json:"score,omitempty" example:"5"`
+}
+
+type MotorReactionCreateData struct {
+	Type       string                        `json:"type" validate:"required,oneof=motor_reaction_create motor_reaction" example:"motor_reaction_create"`
+	Attributes MotorReactionCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type MotorReactionCreateRequest struct {
+	Data MotorReactionCreateData `json:"data" validate:"required"`
+}
+
+type MotorReactionUpdateAttributes struct {
+	Name  *string   `json:"name,omitempty" example:"gezielt auf Schmerzreiz"`
+	Score NullInt64 `json:"score,omitempty" swaggertype:"integer" example:"5"`
+}
+
+// NullInt64 allows PATCH semantics:
+// - field omitted  => Set=false (no change)
+// - value null     => Set=true, Valid=false (set DB NULL)
+// - value number   => Set=true, Valid=true, Value=<number>
+type NullInt64 struct {
+	Set   bool
+	Valid bool
+	Value int64
+}
+
+func (n *NullInt64) UnmarshalJSON(data []byte) error {
+	n.Set = true
+	trimmed := bytes.TrimSpace(data)
+	if bytes.Equal(trimmed, []byte("null")) {
+		n.Valid = false
+		n.Value = 0
+		return nil
+	}
+	var v int64
+	if err := json.Unmarshal(trimmed, &v); err != nil {
+		return err
+	}
+	n.Valid = true
+	n.Value = v
+	return nil
+}
+
+type MotorReactionUpdateData struct {
+	Type       string                        `json:"type" validate:"required,oneof=motor_reaction_update motor_reaction" example:"motor_reaction_update"`
+	ID         string                        `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes MotorReactionUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type MotorReactionUpdateRequest struct {
+	Data MotorReactionUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/null_int.go b/internal/transport/http/dto/null_int.go
new file mode 100644
index 0000000..505e580
--- /dev/null
+++ b/internal/transport/http/dto/null_int.go
@@ -0,0 +1,33 @@
+package dto
+
+import (
+	"bytes"
+	"encoding/json"
+)
+
+// NullInt allows PATCH semantics:
+// - field omitted  => Set=false (no change)
+// - value null     => Set=true, Valid=false (set DB NULL)
+// - value number   => Set=true, Valid=true, Value=<number>
+type NullInt struct {
+	Set   bool
+	Valid bool
+	Value int
+}
+
+func (n *NullInt) UnmarshalJSON(data []byte) error {
+	n.Set = true
+	trimmed := bytes.TrimSpace(data)
+	if bytes.Equal(trimmed, []byte("null")) {
+		n.Valid = false
+		n.Value = 0
+		return nil
+	}
+	var v int
+	if err := json.Unmarshal(trimmed, &v); err != nil {
+		return err
+	}
+	n.Valid = true
+	n.Value = v
+	return nil
+}
diff --git a/internal/transport/http/dto/opc_dto.go b/internal/transport/http/dto/opc_dto.go
new file mode 100644
index 0000000..997d7bf
--- /dev/null
+++ b/internal/transport/http/dto/opc_dto.go
@@ -0,0 +1,77 @@
+package dto
+
+// JSON:API OPC DTOs
+
+type OpcAttributes struct {
+	Title     string `json:"title" example:"Main OPC Base"`
+	SortKey   *int   `json:"sortkey" example:"1"`
+	Note      string `json:"note,omitempty" example:"Primary operation control center"`
+	IsActive  bool   `json:"is_active" example:"true"`
+	CreatedAt string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy string `json:"created_by" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy string `json:"updated_by" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt string `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy string `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type OpcResource struct {
+	Type       string        `json:"type" example:"opc"`
+	ID         string        `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes OpcAttributes `json:"attributes"`
+}
+
+type OpcResponse struct {
+	Data OpcResource `json:"data"`
+}
+
+type OpcListResponse struct {
+	Data []OpcResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type OpcDataTableResponse struct {
+	Data []OpcResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type OpcCreateAttributes struct {
+	Title    string  `json:"title" validate:"required" example:"Main OPC Base"`
+	SortKey  *int    `json:"sortkey" example:"1"`
+	Note     *string `json:"note,omitempty" example:"Primary operation control center"`
+	IsActive *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type OpcCreateData struct {
+	Type       string              `json:"type" validate:"required,oneof=opc_create opc" example:"opc_create"`
+	Attributes OpcCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type OpcCreateRequest struct {
+	Data OpcCreateData `json:"data" validate:"required"`
+}
+
+type OpcUpdateAttributes struct {
+	Title    *string `json:"title,omitempty" example:"Main OPC Base"`
+	SortKey  NullInt `json:"sortkey,omitempty" swaggertype:"integer" example:"1"`
+	Note     *string `json:"note,omitempty" example:"Primary operation control center"`
+	IsActive *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type OpcUpdateData struct {
+	Type       string              `json:"type" validate:"required,oneof=opc_update opc" example:"opc_update"`
+	ID         string              `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes OpcUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type OpcUpdateRequest struct {
+	Data OpcUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/patient_data_dto.go b/internal/transport/http/dto/patient_data_dto.go
new file mode 100644
index 0000000..725385c
--- /dev/null
+++ b/internal/transport/http/dto/patient_data_dto.go
@@ -0,0 +1,114 @@
+package dto
+
+// JSON:API PatientData DTOs
+
+type PatientDataOPC struct {
+	ID    string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Title string `json:"title,omitempty" example:"Primary OPC"`
+}
+
+type PatientDataInsuranceDetail struct {
+	ID                       string                                      `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	HealthInsuranceCompanyID string                                      `json:"health_insurance_companies_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FederalStateID           string                                      `json:"federal_state_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	HealthInsuranceCompany   *InsurancePatientDataHealthInsuranceCompany `json:"health_insurance_company,omitempty"`
+	FederalState             *InsurancePatientDataFederalState           `json:"federal_state,omitempty"`
+}
+
+type PatientDataAttributes struct {
+	FamilyName             string                      `json:"family_name" example:"Muster"`
+	FirstName              string                      `json:"first_name" example:"Max"`
+	OPCId                  string                      `json:"opc_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	BirthDate              string                      `json:"birth_date,omitempty" example:"1990-01-15"`
+	Age                    *int                        `json:"age,omitempty" example:"35"`
+	Gender                 string                      `json:"gender" example:"male"`
+	Street                 string                      `json:"street,omitempty" example:"Hauptstraße 1"`
+	SVNR                   string                      `json:"svnr,omitempty" example:"1234150190"`
+	Email                  string                      `json:"email,omitempty" example:"max.muster@example.com"`
+	Phone                  string                      `json:"phone,omitempty" example:"+431234567"`
+	CoInsured              bool                        `json:"co_insured" example:"false"`
+	InsurancePatientDataId string                      `json:"insurance_patient_data_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	OPC                    *PatientDataOPC             `json:"opc,omitempty"`
+	InsurancePatientData   *PatientDataInsuranceDetail `json:"insurance_patient_data,omitempty"`
+	CreatedAt              string                      `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy              string                      `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt              string                      `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy              string                      `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt              string                      `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy              string                      `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type PatientDataResource struct {
+	Type       string                `json:"type" example:"patient_data"`
+	ID         string                `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes PatientDataAttributes `json:"attributes"`
+}
+
+type PatientDataResponse struct {
+	Data PatientDataResource `json:"data"`
+}
+
+type PatientDataListResponse struct {
+	Data []PatientDataResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type PatientDataDataTableResponse struct {
+	Data []PatientDataResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type PatientDataCreateAttributes struct {
+	FamilyName             string  `json:"family_name" validate:"required" example:"Muster"`
+	FirstName              string  `json:"first_name" validate:"required" example:"Max"`
+	OPCId                  *string `json:"opc_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	BirthDate              *string `json:"birth_date,omitempty" example:"1990-01-15"`
+	Gender                 string  `json:"gender" validate:"required,oneof=male female" example:"male"`
+	Street                 *string `json:"street,omitempty" example:"Hauptstraße 1"`
+	SVNR                   *string `json:"svnr,omitempty" example:"1234150190"`
+	Email                  *string `json:"email,omitempty" example:"max.muster@example.com"`
+	Phone                  *string `json:"phone,omitempty" example:"+431234567"`
+	CoInsured              *bool   `json:"co_insured,omitempty" example:"false"`
+	InsurancePatientDataId *string `json:"insurance_patient_data_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type PatientDataCreateData struct {
+	Type       string                      `json:"type" validate:"required,oneof=patient_data_create patient_data" example:"patient_data_create"`
+	Attributes PatientDataCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type PatientDataCreateRequest struct {
+	Data PatientDataCreateData `json:"data" validate:"required"`
+}
+
+type PatientDataUpdateAttributes struct {
+	FamilyName             *string `json:"family_name,omitempty" example:"Muster"`
+	FirstName              *string `json:"first_name,omitempty" example:"Max"`
+	OPCId                  *string `json:"opc_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	BirthDate              *string `json:"birth_date,omitempty" example:"1990-01-15"`
+	Gender                 *string `json:"gender,omitempty" example:"male"`
+	Street                 *string `json:"street,omitempty" example:"Hauptstraße 1"`
+	SVNR                   *string `json:"svnr,omitempty" example:"1234150190"`
+	Email                  *string `json:"email,omitempty" example:"max.muster@example.com"`
+	Phone                  *string `json:"phone,omitempty" example:"+431234567"`
+	CoInsured              *bool   `json:"co_insured,omitempty" example:"false"`
+	InsurancePatientDataId *string `json:"insurance_patient_data_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type PatientDataUpdateData struct {
+	Type       string                      `json:"type" validate:"required,oneof=patient_data_update patient_data" example:"patient_data_update"`
+	ID         string                      `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes PatientDataUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type PatientDataUpdateRequest struct {
+	Data PatientDataUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/action_signoff_request.go b/internal/transport/http/dto/request/action_signoff_request.go
new file mode 100644
index 0000000..373815c
--- /dev/null
+++ b/internal/transport/http/dto/request/action_signoff_request.go
@@ -0,0 +1,27 @@
+package request
+
+// ActionSignoffSignAttributes — optional fields for the sign-off.
+//   - ComplaintID: when set, the sign-off marks that complaint's corrective action as
+//     signed off (the complaint must already have action_taken recorded, else 422).
+//   - When ComplaintID is omitted it is a complaint-independent (fleet) sign-off, which
+//     still allows an EASA release.
+type ActionSignoffSignAttributes struct {
+	// Sign toggles the sign-off: true (or omitted) signs it, false unsigns (clears the
+	// signature). Combine with complaint_id to toggle a specific complaint's sign-off.
+	Sign        *bool   `json:"sign,omitempty" example:"true"`
+	ComplaintID *string `json:"complaint_id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	// FlightID — REQUIRED for the fleet (complaint-independent) sign-off; scopes it to a
+	// flight so it no longer leaks across takeovers of the same aircraft. Ignored when
+	// complaint_id is set (that sign-off is keyed by the complaint).
+	FlightID *string `json:"flight_id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+}
+
+type ActionSignoffSignData struct {
+	Type       string                      `json:"type,omitempty" example:"action_signoff"`
+	Attributes ActionSignoffSignAttributes `json:"attributes"`
+}
+
+// ActionSignoffSignRequest — body is OPTIONAL for the sign endpoint.
+type ActionSignoffSignRequest struct {
+	Data ActionSignoffSignData `json:"data"`
+}
diff --git a/internal/transport/http/dto/request/air_rescuer_checklist_request.go b/internal/transport/http/dto/request/air_rescuer_checklist_request.go
new file mode 100644
index 0000000..fca4b1e
--- /dev/null
+++ b/internal/transport/http/dto/request/air_rescuer_checklist_request.go
@@ -0,0 +1,87 @@
+package request
+
+import shareddto "wucher/internal/transport/http/dto/shared"
+
+type AirRescuerChecklistCreateEntry struct {
+	ScopeCode string                                   `json:"scope_code" validate:"required" example:"MO"`
+	Title     string                                   `json:"title" validate:"required" example:"Monday Checklist"`
+	Position  *int                                     `json:"position,omitempty" example:"1"`
+	Items     []shareddto.AirRescuerChecklistItemInput `json:"items,omitempty" validate:"omitempty,dive"`
+}
+
+type AirRescuerChecklistCreateAttributes struct {
+	BaseID     string                           `json:"base_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Checklists []AirRescuerChecklistCreateEntry `json:"checklists" validate:"required,min=1,dive"`
+}
+
+type AirRescuerChecklistCreateData struct {
+	Type       string                              `json:"type" validate:"required,oneof=air_rescuer_checklist_create"`
+	Attributes AirRescuerChecklistCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type AirRescuerChecklistCreateRequest struct {
+	Data AirRescuerChecklistCreateData `json:"data" validate:"required"`
+}
+
+type AirRescuerChecklistUpdateAttributes struct {
+	ScopeCode *string                                  `json:"scope_code,omitempty" example:"MO"`
+	Title     *string                                  `json:"title,omitempty" example:"Monday Checklist Updated"`
+	Position  *int                                     `json:"position,omitempty" example:"1"`
+	NewItems  []shareddto.AirRescuerChecklistItemInput `json:"new_items,omitempty" validate:"omitempty,dive"`
+}
+
+type AirRescuerChecklistUpdateData struct {
+	Type       string                              `json:"type" validate:"required,oneof=air_rescuer_checklist_update"`
+	ID         string                              `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes AirRescuerChecklistUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type AirRescuerChecklistUpdateRequest struct {
+	Data AirRescuerChecklistUpdateData `json:"data" validate:"required"`
+}
+
+type AirRescuerChecklistItemCreateAttributes struct {
+	Items []shareddto.AirRescuerChecklistItemInput `json:"items" validate:"required,min=1,dive"`
+}
+
+type AirRescuerChecklistItemCreateData struct {
+	Type       string                                  `json:"type" validate:"required,oneof=air_rescuer_checklist_item_create"`
+	Attributes AirRescuerChecklistItemCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type AirRescuerChecklistItemCreateRequest struct {
+	Data AirRescuerChecklistItemCreateData `json:"data" validate:"required"`
+}
+
+type AirRescuerChecklistItemUpdateAttributes struct {
+	Name     *string `json:"name,omitempty" example:"Check radio"`
+	Position *int    `json:"position,omitempty" example:"2"`
+}
+
+type AirRescuerChecklistItemUpdateData struct {
+	Type       string                                  `json:"type" validate:"required,oneof=air_rescuer_checklist_item_update"`
+	ID         string                                  `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes AirRescuerChecklistItemUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type AirRescuerChecklistItemUpdateRequest struct {
+	Data AirRescuerChecklistItemUpdateData `json:"data" validate:"required"`
+}
+
+type AirRescuerChecklistItemReorderEntry struct {
+	ItemUUID string `json:"item_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Position *int   `json:"position" validate:"required" example:"2"`
+}
+
+type AirRescuerChecklistItemReorderAttributes struct {
+	Items []AirRescuerChecklistItemReorderEntry `json:"items" validate:"required,min=1,dive"`
+}
+
+type AirRescuerChecklistItemReorderData struct {
+	Type       string                                   `json:"type" validate:"required,oneof=air_rescuer_checklist_item_reorder"`
+	Attributes AirRescuerChecklistItemReorderAttributes `json:"attributes" validate:"required"`
+}
+
+type AirRescuerChecklistItemReorderRequest struct {
+	Data AirRescuerChecklistItemReorderData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/complaint_request.go b/internal/transport/http/dto/request/complaint_request.go
new file mode 100644
index 0000000..da83225
--- /dev/null
+++ b/internal/transport/http/dto/request/complaint_request.go
@@ -0,0 +1,82 @@
+package request
+
+type ComplaintCreateAttributes struct {
+	// HelicopterID — the helicopter this complaint is filed against. REQUIRED.
+	HelicopterID string `json:"helicopter_id" validate:"required,uuid" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	// FlightID — the flight/report this complaint was filed in (attribution). OPTIONAL;
+	// open-defect tracking stays per-helicopter so defects carry forward across flights.
+	FlightID string `json:"flight_id,omitempty" validate:"omitempty,uuid" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	// Description — the defect description. REQUIRED.
+	Description string `json:"description" validate:"required" example:"Engine 2 N2 vibration intermittent during cruise above 110 KIAS"`
+	// MELSeverity — MEL (Minimum Equipment List) classification. OPTIONAL at creation:
+	// omit it to file the complaint as "pending_mel" and classify later. It MUST be
+	// classified (via update) before recording action taken. A pending complaint does
+	// NOT ground the aircraft — grounding starts at classification. Values: 0 = NON-MEL
+	// (grounds immediately), 1 = A (grace 1 day), 2 = B (3 days), 3 = C (10 days), 4 = D (120 days).
+	MELSeverity *int8 `json:"mel_severity,omitempty" validate:"omitempty,oneof=0 1 2 3 4" enums:"0,1,2,3,4" example:"2"`
+	// AircraftHoursAtReport — OPTIONAL airframe hours recorded when the defect was reported.
+	AircraftHoursAtReport *string `json:"aircraft_hours_at_report,omitempty" example:"1245.3"`
+	// NSR is no longer set here — it is its own flow: POST /complaints/nsr/sign/{id}.
+}
+
+type ComplaintCreateData struct {
+	Type       string                    `json:"type" validate:"required,oneof=complaint_create complaint" example:"complaint_create"`
+	Attributes ComplaintCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type ComplaintCreateRequest struct {
+	Data ComplaintCreateData `json:"data" validate:"required"`
+}
+
+type ComplaintUpdateAttributes struct {
+	// Description — defect description.
+	Description *string `json:"description,omitempty" example:"Engine 2 vibration confirmed"`
+	// MELSeverity — MEL classification. 0 = NON-MEL (immediate AOG), 1 = A (1 day),
+	// 2 = B (3 days), 3 = C (10 days), 4 = D (120 days). AOG after grace passes.
+	MELSeverity *int8 `json:"mel_severity,omitempty" validate:"omitempty,oneof=0 1 2 3 4" enums:"0,1,2,3,4" example:"2"`
+	// AircraftHoursAtReport — airframe hours at report time.
+	AircraftHoursAtReport *string `json:"aircraft_hours_at_report,omitempty" example:"1245.3"`
+	// NSR is no longer set here — it is its own flow: POST /complaints/nsr/sign/{id}.
+}
+
+// ComplaintNSRSignAttributes carries the (optional) justification for a Non-Safety
+// Release decision. NSR is signed via its own endpoint, separate from complaint update.
+type ComplaintNSRSignAttributes struct {
+	// NSRReason — OPTIONAL free-text justification for the NSR (MEL deferral) decision.
+	NSRReason *string `json:"nsr_reason,omitempty" example:"Released under MEL A, defect deferred"`
+}
+
+type ComplaintNSRSignData struct {
+	Type       string                     `json:"type" validate:"omitempty,oneof=complaint_nsr_sign complaint_nsr" example:"complaint_nsr_sign"`
+	Attributes ComplaintNSRSignAttributes `json:"attributes"`
+}
+
+type ComplaintNSRSignRequest struct {
+	Data ComplaintNSRSignData `json:"data"`
+}
+
+type ComplaintUpdateData struct {
+	Type       string                    `json:"type" validate:"required,oneof=complaint_update complaint" example:"complaint_update"`
+	ID         string                    `json:"id" validate:"required" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Attributes ComplaintUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type ComplaintUpdateRequest struct {
+	Data ComplaintUpdateData `json:"data" validate:"required"`
+}
+
+type ComplaintActionTakenAttributes struct {
+	// ActionTaken — corrective action text. Required when recording (create); on update an
+	// empty value clears it (allowed only while the action has not been signed off).
+	ActionTaken        string  `json:"action_taken" example:"Tightened engine mount and rechecked torque"`
+	AircraftHoursAtFix *string `json:"aircraft_hours_at_fix,omitempty" example:"1250.1"`
+}
+
+type ComplaintActionTakenData struct {
+	Type       string                         `json:"type" validate:"required,oneof=complaint_action_taken complaint" example:"complaint_action_taken"`
+	Attributes ComplaintActionTakenAttributes `json:"attributes" validate:"required"`
+}
+
+type ComplaintActionTakenRequest struct {
+	Data ComplaintActionTakenData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/duty_roster_request.go b/internal/transport/http/dto/request/duty_roster_request.go
new file mode 100644
index 0000000..f60be9d
--- /dev/null
+++ b/internal/transport/http/dto/request/duty_roster_request.go
@@ -0,0 +1,143 @@
+package request
+
+type DutyRosterShiftTime struct {
+	ShiftStart string `json:"shift_start,omitempty" example:"06:00"`
+	ShiftEnd   string `json:"shift_end,omitempty" example:"21:00"`
+}
+
+type DutyRosterShiftDate struct {
+	DateStart string `json:"date_start,omitempty" example:"2026-03-16"`
+	DateEnd   string `json:"date_end,omitempty" example:"2026-03-16"`
+}
+
+type DutyRosterCrewInput struct {
+	ID        string               `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	ShiftDate *DutyRosterShiftDate `json:"shift_date,omitempty"`
+}
+
+type DutyRosterPilotCrewInput struct {
+	ID               string               `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	ShiftDate        *DutyRosterShiftDate `json:"shift_date,omitempty"`
+	FlightInstructor bool                 `json:"flight_instructor,omitempty"`
+	LineChecker      bool                 `json:"line_checker,omitempty"`
+	Supervisor       bool                 `json:"supervisor,omitempty"`
+	Examiner         bool                 `json:"examiner,omitempty"`
+	CoPilot          bool                 `json:"co_pilot,omitempty"`
+	CrewType         string               `json:"crew_type,omitempty" example:"main" enums:"main,additional"`
+}
+
+type DutyRosterOtherPersonInput struct {
+	// OtherPersonID — OPTIONAL master person id to reuse (from GET /contact/other).
+	// When set, name/mobile_phone/email are snapshotted from the master (may be omitted).
+	OtherPersonID string `json:"other_person_id,omitempty" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Name          string `json:"name,omitempty" example:"Guest Person"`
+	MobilePhone   string `json:"mobile_phone,omitempty" example:"+43-1234"`
+	Email         string `json:"email,omitempty" example:"guest@example.com"`
+}
+
+type DutyRosterDetailsInput struct {
+	Pilot       []DutyRosterPilotCrewInput   `json:"pilot"`
+	Doctor      []DutyRosterCrewInput        `json:"doctor"`
+	Rescuer     []DutyRosterCrewInput        `json:"rescuer"`
+	Helper      []DutyRosterCrewInput        `json:"helper"`
+	OtherPerson []DutyRosterOtherPersonInput `json:"other_person"`
+}
+
+type DutyRosterCreateAttributes struct {
+	BaseID    string                 `json:"base_id" validate:"required"`
+	DutyDate  string                 `json:"duty_date" validate:"required"`
+	ShiftTime DutyRosterShiftTime    `json:"shift_time"`
+	Detail    DutyRosterDetailsInput `json:"roster_detail"`
+}
+
+type DutyRosterCreateData struct {
+	Type       string                     `json:"type" validate:"required,oneof=duty_roster_create duty_roster"`
+	Attributes DutyRosterCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type DutyRosterCreateRequest struct {
+	Data DutyRosterCreateData `json:"data" validate:"required"`
+}
+
+type DutyRosterUpdateAttributes struct {
+	BaseID    *string                 `json:"base_id,omitempty"`
+	DutyDate  *string                 `json:"duty_date,omitempty"`
+	ShiftTime *DutyRosterShiftTime    `json:"shift_time,omitempty"`
+	Detail    *DutyRosterDetailsInput `json:"roster_detail,omitempty"`
+}
+
+type DutyRosterUpdateData struct {
+	Type       string                     `json:"type" validate:"required,oneof=duty_roster_update duty_roster"`
+	ID         string                     `json:"id"`
+	Attributes DutyRosterUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type DutyRosterUpdateRequest struct {
+	Data DutyRosterUpdateData `json:"data" validate:"required"`
+}
+
+type DutyRosterDeleteCrewAttributes struct {
+	Detail DutyRosterDetailsInput `json:"roster_detail"`
+}
+
+type DutyRosterDeleteCrewData struct {
+	Type       string                         `json:"type" validate:"required,oneof=duty_roster_crew_delete duty_roster_update duty_roster"`
+	Attributes DutyRosterDeleteCrewAttributes `json:"attributes" validate:"required"`
+}
+
+type DutyRosterDeleteCrewRequest struct {
+	Data DutyRosterDeleteCrewData `json:"data" validate:"required"`
+}
+
+type DutyRosterDeleteCrewByIDAttributes struct {
+	RosterID string `json:"roster_id" validate:"required"`
+	CrewID   string `json:"crew_id" validate:"required"`
+}
+
+type DutyRosterDeleteCrewByIDData struct {
+	Type       string                             `json:"type" validate:"required,oneof=duty_roster_crew_delete duty_roster_update duty_roster"`
+	Attributes DutyRosterDeleteCrewByIDAttributes `json:"attributes" validate:"required"`
+}
+
+type DutyRosterDeleteCrewByIDRequest struct {
+	Data DutyRosterDeleteCrewByIDData `json:"data" validate:"required"`
+}
+
+type DutyRosterAnyDeleteData struct {
+	ID string `json:"id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type DutyRosterAnyDeleteRequest struct {
+	Data DutyRosterAnyDeleteData `json:"data" validate:"required"`
+}
+
+// DutyRosterAnyCreateRequestDoc is documentation-only schema for cleaner Swagger examples.
+type DutyRosterAnyCreateRequestDoc struct {
+	Data DutyRosterAnyCreateDataDoc `json:"data"`
+}
+
+type DutyRosterAnyCreateDataDoc struct {
+	Type       string                           `json:"type" example:"duty_roster_create" enums:"duty_roster_create,duty_roster"`
+	Attributes DutyRosterAnyCreateAttributesDoc `json:"attributes"`
+}
+
+type DutyRosterAnyCreateAttributesDoc struct {
+	BaseID    string                       `json:"base_id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DutyDate  string                       `json:"duty_date" example:"2026-03-16"`
+	ShiftTime DutyRosterShiftTime          `json:"shift_time"`
+	Detail    DutyRosterAnyCreateDetailDoc `json:"roster_detail"`
+}
+
+type DutyRosterAnyCreateDetailDoc struct {
+	Pilot       []DutyRosterPilotAdditionalExampleDoc `json:"pilot"`
+	Doctor      []DutyRosterCrewInput                 `json:"doctor"`
+	Rescuer     []DutyRosterCrewInput                 `json:"rescuer"`
+	Helper      []DutyRosterCrewInput                 `json:"helper"`
+	OtherPerson []DutyRosterOtherPersonInput          `json:"other_person"`
+}
+
+type DutyRosterPilotAdditionalExampleDoc struct {
+	ID               string `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CrewType         string `json:"crew_type" example:"additional" enums:"main,additional"`
+	FlightInstructor bool   `json:"flight_instructor" example:"true"`
+}
diff --git a/internal/transport/http/dto/request/easa_release_request.go b/internal/transport/http/dto/request/easa_release_request.go
new file mode 100644
index 0000000..fe86f6a
--- /dev/null
+++ b/internal/transport/http/dto/request/easa_release_request.go
@@ -0,0 +1,53 @@
+package request
+
+type EASAReleaseCreateAttributes struct {
+	HelicopterID string `json:"helicopter_id" validate:"required,uuid" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	// ComplaintID — OPTIONAL complaint (UUIDv7) this release closes. Set it to scope the
+	// release to a specific defect; leave empty for a standalone (aircraft-clear) release.
+	ComplaintID string `json:"complaint_id,omitempty" validate:"omitempty,uuid" example:"019d6774-1111-7fba-9ef4-3795c0da8a13"`
+	// FlightID — OPTIONAL flight context. Used for the standalone (no-complaint) sign-off gate.
+	FlightID                   string  `json:"flight_id,omitempty" validate:"omitempty,uuid" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	EASADate                   *string `json:"easa_date,omitempty" example:"2026-06-16"`
+	EASAACHours                *string `json:"easa_ac_hours,omitempty" example:"1245.3"`
+	EASALocation               *string `json:"easa_location,omitempty" example:"LOWI"`
+	EASAWONo                   *string `json:"easa_wo_no,omitempty" example:"WO-2026-001"`
+	EASAMaintManualRevAirframe *string `json:"easa_maint_manual_rev_airframe,omitempty" example:"Rev 12"`
+	EASAMaintManualRevEngine   *string `json:"easa_maint_manual_rev_engine,omitempty" example:"Rev 8"`
+	// EASASignerID — OPTIONAL contact id (UUIDv7) of the signer/technician. Required only to sign.
+	EASASignerID *string `json:"easa_signer_id,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	EASAPermitNo *string `json:"easa_permit_no,omitempty" example:"145.A.50"`
+	// Sign, when true, signs the release immediately at creation. Requires all
+	// required fields to be present; otherwise the request is rejected.
+	Sign bool `json:"sign,omitempty" example:"false"`
+}
+
+type EASAReleaseCreateData struct {
+	Type       string                      `json:"type" validate:"required,oneof=easa_release_create easa_release" example:"easa_release_create"`
+	Attributes EASAReleaseCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type EASAReleaseCreateRequest struct {
+	Data EASAReleaseCreateData `json:"data" validate:"required"`
+}
+
+type EASAReleaseUpdateAttributes struct {
+	EASADate                   *string `json:"easa_date,omitempty" example:"2026-06-16"`
+	EASAACHours                *string `json:"easa_ac_hours,omitempty" example:"1245.3"`
+	EASALocation               *string `json:"easa_location,omitempty" example:"LOWI"`
+	EASAWONo                   *string `json:"easa_wo_no,omitempty" example:"WO-2026-001"`
+	EASAMaintManualRevAirframe *string `json:"easa_maint_manual_rev_airframe,omitempty" example:"Rev 12"`
+	EASAMaintManualRevEngine   *string `json:"easa_maint_manual_rev_engine,omitempty" example:"Rev 8"`
+	// EASASignerID — OPTIONAL contact id (UUIDv7) of the signer/technician. Required only to sign.
+	EASASignerID *string `json:"easa_signer_id,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	EASAPermitNo *string `json:"easa_permit_no,omitempty" example:"145.A.50"`
+}
+
+type EASAReleaseUpdateData struct {
+	Type       string                      `json:"type" validate:"required,oneof=easa_release_update easa_release" example:"easa_release_update"`
+	ID         string                      `json:"id" validate:"required" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Attributes EASAReleaseUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type EASAReleaseUpdateRequest struct {
+	Data EASAReleaseUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/file_manager_attachment_request.go b/internal/transport/http/dto/request/file_manager_attachment_request.go
new file mode 100644
index 0000000..8eb70e8
--- /dev/null
+++ b/internal/transport/http/dto/request/file_manager_attachment_request.go
@@ -0,0 +1,19 @@
+package request
+
+type FileManagerAttachmentCreateAttributes struct {
+	FileID    string  `json:"file_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	RefType   string  `json:"ref_type" validate:"required" example:"helicopter"`
+	RefID     string  `json:"ref_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Category  *string `json:"category,omitempty" example:"document"`
+	SortOrder *int    `json:"sort_order,omitempty" example:"0"`
+	IsPrimary *bool   `json:"is_primary,omitempty" example:"false"`
+}
+
+type FileManagerAttachmentCreateData struct {
+	Type       string                                `json:"type" validate:"required,oneof=file_manager_attachment_create file_manager_attachment" example:"file_manager_attachment_create"`
+	Attributes FileManagerAttachmentCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerAttachmentCreateRequest struct {
+	Data FileManagerAttachmentCreateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/file_manager_file_request.go b/internal/transport/http/dto/request/file_manager_file_request.go
new file mode 100644
index 0000000..7a498be
--- /dev/null
+++ b/internal/transport/http/dto/request/file_manager_file_request.go
@@ -0,0 +1,197 @@
+package request
+
+type FileManagerFileCreateAttributes struct {
+	UploadIntentUUID string  `json:"upload_intent_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FolderID         *string `json:"folder_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name             string  `json:"name" validate:"required" example:"policy-final.pdf"`
+}
+
+type FileManagerFileUploadIntentAttributes struct {
+	Name        string `json:"name" validate:"required" example:"policy-final.pdf"`
+	ContentType string `json:"content_type" validate:"required" example:"application/pdf"`
+	SizeBytes   int64  `json:"size_bytes" validate:"required,gte=0" example:"1024"`
+}
+
+type FileManagerFileUploadIntentData struct {
+	Type       string                                `json:"type" validate:"required,oneof=file_manager_file_upload_intent" example:"file_manager_file_upload_intent"`
+	Attributes FileManagerFileUploadIntentAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFileUploadIntentRequest struct {
+	Data FileManagerFileUploadIntentData `json:"data" validate:"required"`
+}
+
+type FileManagerFileUploadIntentBulkRequest struct {
+	Data []FileManagerFileUploadIntentData `json:"data" validate:"required,min=1"`
+}
+
+type FileManagerFileCancelUploadAttributes struct {
+	UploadIntentUUID string `json:"upload_intent_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FileManagerFileCancelUploadData struct {
+	Type       string                                `json:"type" validate:"required,oneof=file_manager_file_cancel_upload" example:"file_manager_file_cancel_upload"`
+	Attributes FileManagerFileCancelUploadAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFileCancelUploadBulkRequest struct {
+	Data []FileManagerFileCancelUploadData `json:"data" validate:"required,min=1"`
+}
+
+type FileManagerFileUploadCompleteAttributes struct {
+	UploadIntentUUID string `json:"upload_intent_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FileManagerFileUploadCompleteData struct {
+	Type       string                                  `json:"type" validate:"required,oneof=file_manager_file_upload_complete" example:"file_manager_file_upload_complete"`
+	Attributes FileManagerFileUploadCompleteAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFileUploadCompleteRequest struct {
+	Data FileManagerFileUploadCompleteData `json:"data" validate:"required"`
+}
+
+type FileManagerFileCreateData struct {
+	Type       string                          `json:"type" validate:"required,oneof=file_manager_file_create file_manager_file" example:"file_manager_file_create"`
+	Attributes FileManagerFileCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFileCreateRequest struct {
+	Data FileManagerFileCreateData `json:"data" validate:"required"`
+}
+
+// FileManagerFileCreateFlexibleRequest is used for swagger documentation.
+// Runtime accepts:
+// - single: {"data": { ...FileManagerFileCreateData }}
+// - bulk:   {"data": [ ...FileManagerFileBulkCreateItem ]}
+type FileManagerFileCreateFlexibleRequest struct {
+	Data interface{} `json:"data"`
+}
+
+type FileManagerFileBulkCreateItem struct {
+	Type       string                          `json:"type" validate:"required,oneof=file_manager_file_create file_manager_file" example:"file_manager_file_create"`
+	Attributes FileManagerFileCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFileBulkCreateRequest struct {
+	Data []FileManagerFileBulkCreateItem `json:"data" validate:"required,min=1"`
+}
+
+type FileManagerFileUserCreateAttributes struct {
+	UploadIntentUUID string `json:"upload_intent_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UserUUID         string `json:"user_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name             string `json:"name" validate:"required" example:"profile.jpg"`
+}
+
+type FileManagerFileUserBulkCreateItem struct {
+	Type       string                              `json:"type" validate:"required,oneof=file_manager_file_create file_manager_file" example:"file_manager_file_create"`
+	Attributes FileManagerFileUserCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFileUserBulkCreateRequest struct {
+	Data []FileManagerFileUserBulkCreateItem `json:"data" validate:"required,min=1"`
+}
+
+type FileManagerFileAircraftCreateAttributes struct {
+	UploadIntentUUID string `json:"upload_intent_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	AircraftUUID     string `json:"aircraft_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name             string `json:"name" validate:"required" example:"aircraft.jpg"`
+}
+
+type FileManagerFileAircraftBulkCreateItem struct {
+	Type       string                                  `json:"type" validate:"required,oneof=file_manager_file_create file_manager_file" example:"file_manager_file_create"`
+	Attributes FileManagerFileAircraftCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFileAircraftBulkCreateRequest struct {
+	Data []FileManagerFileAircraftBulkCreateItem `json:"data" validate:"required,min=1"`
+}
+
+type FileManagerFileBaseCreateAttributes struct {
+	UploadIntentUUID string `json:"upload_intent_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	BaseUUID         string `json:"base_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name             string `json:"name" validate:"required" example:"base.jpg"`
+}
+
+type FileManagerFileBaseBulkCreateItem struct {
+	Type       string                              `json:"type" validate:"required,oneof=file_manager_file_create file_manager_file" example:"file_manager_file_create"`
+	Attributes FileManagerFileBaseCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFileBaseBulkCreateRequest struct {
+	Data []FileManagerFileBaseBulkCreateItem `json:"data" validate:"required,min=1"`
+}
+
+type FileManagerFileDULCreateAttributes struct {
+	UploadIntentUUID string `json:"upload_intent_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DULUUID          string `json:"dul_uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name             string `json:"name" validate:"required" example:"dul.jpg"`
+}
+
+type FileManagerFileDULBulkCreateItem struct {
+	Type       string                             `json:"type" validate:"required,oneof=file_manager_file_create file_manager_file" example:"file_manager_file_create"`
+	Attributes FileManagerFileDULCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFileDULBulkCreateRequest struct {
+	Data []FileManagerFileDULBulkCreateItem `json:"data" validate:"required,min=1"`
+}
+
+type FileManagerFileTakeoverCreateAttributes struct {
+	UploadIntentUUID string `json:"upload_intent_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	TakeoverUUID     string `json:"takeover_uuid,omitempty" example:"019e8713-aa19-7fb7-a510-a0332dc69697"`
+	Name             string `json:"name" validate:"required" example:"takeover-report.pdf"`
+}
+
+type FileManagerFileTakeoverBulkCreateItem struct {
+	Type       string                                  `json:"type" validate:"required,oneof=file_manager_file_create file_manager_file" example:"file_manager_file_create"`
+	Attributes FileManagerFileTakeoverCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFileTakeoverBulkCreateRequest struct {
+	Data []FileManagerFileTakeoverBulkCreateItem `json:"data" validate:"required,min=1"`
+}
+
+type FileManagerFileTemplateCreateAttributes struct {
+	TemplateUUID string `json:"template_uuid" validate:"required" example:"019f0386-0a00-7a4a-a2d8-30afc0e0c3ad"`
+	HelicopterID string `json:"helicopter_id" validate:"required" example:"019e8713-aa19-7fb7-a510-a0332dc69697"`
+	TakeoverID   string `json:"takeover_id,omitempty" example:"019e8713-aa19-7fb7-a510-a0332dc69697"`
+	Name         string `json:"name" validate:"required" example:"collabora-draft.docx"`
+}
+
+type FileManagerFileTemplateCreateRequest struct {
+	Data struct {
+		Type       string                                  `json:"type" validate:"required,oneof=file_manager_file_create_from_template file_manager_file_create"`
+		Attributes FileManagerFileTemplateCreateAttributes `json:"attributes" validate:"required"`
+	} `json:"data" validate:"required"`
+}
+
+type FileManagerFileMissionCreateAttributes struct {
+	UploadIntentUUID string `json:"upload_intent_uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	MissionUUID      string `json:"mission_uuid" validate:"required" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	Name             string `json:"name" validate:"required" example:"mission-brief.pdf"`
+}
+
+type FileManagerFileMissionBulkCreateItem struct {
+	Type       string                                 `json:"type" validate:"required,oneof=file_manager_file_create file_manager_file" example:"file_manager_file_create"`
+	Attributes FileManagerFileMissionCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFileMissionBulkCreateRequest struct {
+	Data []FileManagerFileMissionBulkCreateItem `json:"data" validate:"required,min=1"`
+}
+
+type FileManagerFileUpdateAttributes struct {
+	FolderID *string `json:"folder_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name     *string `json:"name,omitempty" example:"policy-v2.pdf"`
+}
+
+type FileManagerFileUpdateData struct {
+	Type       string                          `json:"type" validate:"required,oneof=file_manager_file_update file_manager_file" example:"file_manager_file_update"`
+	ID         string                          `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes FileManagerFileUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFileUpdateRequest struct {
+	Data FileManagerFileUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/file_manager_folder_request.go b/internal/transport/http/dto/request/file_manager_folder_request.go
new file mode 100644
index 0000000..b627473
--- /dev/null
+++ b/internal/transport/http/dto/request/file_manager_folder_request.go
@@ -0,0 +1,47 @@
+package request
+
+type FileManagerFolderCreateAttributes struct {
+	ParentID *string `json:"parent_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name     string  `json:"name" validate:"required" example:"operations"`
+}
+
+type FileManagerFolderCreateData struct {
+	Type       string                            `json:"type" validate:"required,oneof=file_manager_folder_create file_manager_folder" example:"file_manager_folder_create"`
+	Attributes FileManagerFolderCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFolderCreateRequest struct {
+	Data FileManagerFolderCreateData `json:"data" validate:"required"`
+}
+
+type FileManagerFolderUpdateAttributes struct {
+	Name     *string `json:"name,omitempty" example:"operations-updated"`
+	ParentID *string `json:"parent_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FileManagerFolderUpdateData struct {
+	Type       string                            `json:"type" validate:"required,oneof=file_manager_folder_update file_manager_folder" example:"file_manager_folder_update"`
+	ID         string                            `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes FileManagerFolderUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type FileManagerFolderUpdateRequest struct {
+	Data FileManagerFolderUpdateData `json:"data" validate:"required"`
+}
+
+type FileManagerNodeMoveItem struct {
+	UUID                  string  `json:"uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DestinationFolderUUID *string `json:"destination_folder_uuid" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FileManagerNodeMoveBulkRequest struct {
+	Data []FileManagerNodeMoveItem `json:"data" validate:"required,min=1"`
+}
+
+type FileManagerNodePurgeItem struct {
+	UUID string `json:"uuid" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FileManagerNodePurgeBulkRequest struct {
+	Data []FileManagerNodePurgeItem `json:"data" validate:"required,min=1"`
+}
diff --git a/internal/transport/http/dto/request/file_manager_restore_request.go b/internal/transport/http/dto/request/file_manager_restore_request.go
new file mode 100644
index 0000000..7bcf2f3
--- /dev/null
+++ b/internal/transport/http/dto/request/file_manager_restore_request.go
@@ -0,0 +1,13 @@
+package request
+
+type FileManagerRestoreTargetAttributes struct {
+	TargetFolderID *string `json:"target_folder_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FileManagerRestoreTargetData struct {
+	Attributes FileManagerRestoreTargetAttributes `json:"attributes"`
+}
+
+type FileManagerRestoreTargetRequest struct {
+	Data *FileManagerRestoreTargetData `json:"data,omitempty"`
+}
diff --git a/internal/transport/http/dto/request/fleet_status_request.go b/internal/transport/http/dto/request/fleet_status_request.go
new file mode 100644
index 0000000..e40157a
--- /dev/null
+++ b/internal/transport/http/dto/request/fleet_status_request.go
@@ -0,0 +1,70 @@
+package request
+
+import shared "wucher/internal/transport/http/dto/shared"
+
+type FleetStatusMarkServicedAttributes struct {
+	ServicedAt string `json:"serviced_at,omitempty" example:"2026-05-29T07:43:06Z"`
+}
+
+type FleetStatusMarkServicedData struct {
+	Type       string                            `json:"type" validate:"required,oneof=fleet_status_mark_serviced fleet_status" example:"fleet_status_mark_serviced"`
+	Attributes FleetStatusMarkServicedAttributes `json:"attributes"`
+}
+
+type FleetStatusMarkServicedRequest struct {
+	Data FleetStatusMarkServicedData `json:"data" validate:"required"`
+}
+
+type FleetStatusCreateAttributes struct {
+	HelicopterID         string                                 `json:"helicopter_id" validate:"required" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	MaintenanceSchedules []shared.MaintenanceScheduleAttributes `json:"maintenance_schedules" validate:"omitempty,dive"`
+	Files                []shared.FleetStatusFileAttributes     `json:"files"`
+}
+
+type FleetStatusCreateData struct {
+	Type       string                      `json:"type" validate:"required,oneof=fleet_status_create fleet_status" example:"fleet_status_create"`
+	Attributes FleetStatusCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FleetStatusCreateRequest struct {
+	Data FleetStatusCreateData `json:"data" validate:"required"`
+}
+
+type FleetStatusUpdateAttributes struct {
+	HelicopterID         *string                                `json:"helicopter_id,omitempty"`
+	MaintenanceSchedules []shared.MaintenanceScheduleAttributes `json:"maintenance_schedules" validate:"omitempty,dive"`
+	Files                []shared.FleetStatusFileAttributes     `json:"files"`
+	Summary              *FleetStatusSummaryUpdate              `json:"summary,omitempty"`
+}
+
+type FleetStatusSummaryUpdate struct {
+	Airframe         *FleetStatusSummaryAirframeUpdate `json:"airframe,omitempty"`
+	Engine1          *FleetStatusSummaryEngineUpdate   `json:"engine_1,omitempty"`
+	Engine2          *FleetStatusSummaryEngineUpdate   `json:"engine_2,omitempty"`
+	Landings         *float64                          `json:"landings,omitempty" example:"120"`
+	FlightReports    *float64                          `json:"flight_reports,omitempty" example:"80"`
+	RotorBrakeCycles *float64                          `json:"rotor_brake_cycles,omitempty" example:"8"`
+	HookReleases     *float64                          `json:"hook_releases,omitempty" example:"10"`
+}
+
+type FleetStatusSummaryAirframeUpdate struct {
+	Hours  *float64 `json:"hours,omitempty" example:"6610.5"`
+	Cycles *float64 `json:"cycles,omitempty" example:"320"`
+}
+
+type FleetStatusSummaryEngineUpdate struct {
+	Hours   *float64 `json:"hours,omitempty" example:"8001.7"`
+	GpcNgN1 *float64 `json:"gpc_ng_n1,omitempty" example:"98.7"`
+	PtcNfN2 *float64 `json:"ptc_nf_n2,omitempty" example:"97.2"`
+	Ccc     *float64 `json:"ccc,omitempty" example:"44"`
+}
+
+type FleetStatusUpdateData struct {
+	Type       string                      `json:"type" validate:"required,oneof=fleet_status_update fleet_status" example:"fleet_status_update"`
+	ID         string                      `json:"id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Attributes FleetStatusUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type FleetStatusUpdateRequest struct {
+	Data FleetStatusUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/flight_data_request.go b/internal/transport/http/dto/request/flight_data_request.go
new file mode 100644
index 0000000..d74cc44
--- /dev/null
+++ b/internal/transport/http/dto/request/flight_data_request.go
@@ -0,0 +1,135 @@
+package request
+
+type FlightDataCreateAttributes struct {
+	MissionID            string                                `json:"mission_id" validate:"required"`
+	CoPilotID            *string                               `json:"co_pilot_id,omitempty"`
+	FromICAOID           *string                               `json:"from_icao_id,omitempty"`
+	FromHospitalID       *string                               `json:"from_hospital_id,omitempty"`
+	ToICAOID             *string                               `json:"to_icao_id,omitempty"`
+	ToHospitalID         *string                               `json:"to_hospital_id,omitempty"`
+	FlightTakeOff        *string                               `json:"flight_take_off,omitempty"`
+	FlightLanding        *string                               `json:"flight_landing,omitempty"`
+	FlightDurationSecs   *int64                                `json:"flight_duration_seconds,omitempty"`
+	FlightREDSecs        *int64                                `json:"flight_red_seconds,omitempty"`
+	MaxN1                *float64                              `json:"max_n1,omitempty"`
+	MaxN2                *float64                              `json:"max_n2,omitempty"`
+	PaxCount             *int                                  `json:"pax_count,omitempty"`
+	LandingCount         *int                                  `json:"landing_count,omitempty"`
+	RotorBrakeCycle      *int                                  `json:"rotor_brake_cycle,omitempty"`
+	HookReleases         *int                                  `json:"hook_releases,omitempty"`
+	TicketNo             *string                               `json:"ticket_no,omitempty"`
+	Engine               *string                               `json:"engine,omitempty"`
+	DeliveryNoteNumber   *string                               `json:"delivery_note_number,omitempty"`
+	CustomerName         *string                               `json:"customer_name,omitempty"`
+	FlightPlanDistance   *float64                              `json:"flight_plan_distance,omitempty"`
+	FlightPlanTimeSecs   *int64                                `json:"flight_plan_time_seconds,omitempty"`
+	FlightPlanTrueCourse *float64                              `json:"flight_plan_true_course,omitempty"`
+	FuelBeforeFlight     *float64                              `json:"fuel_before_flight,omitempty"`
+	FuelUpload           *float64                              `json:"fuel_upload,omitempty"`
+	FuelAfterFlight      *float64                              `json:"fuel_after_flight,omitempty"`
+	FuelPlanning         *float64                              `json:"fuel_planning,omitempty"`
+	FlightPositioning    *bool                                 `json:"flight_positioning,omitempty" example:"false"`
+	HESLO                *FlightDataCreateSPOHESLOAttributes   `json:"heslo,omitempty"`
+	Logging              *FlightDataCreateSPOLoggingAttributes `json:"logging,omitempty"`
+	HEC                  *FlightDataCreateSPOHECAttributes     `json:"hec,omitempty"`
+	OtherInformation     *string                               `json:"other_information,omitempty"`
+}
+
+type FlightDataCreateSPOHESLOAttributes struct {
+	Flights []FlightDataCreateSPOHESLOFlight `json:"flights,omitempty"`
+}
+
+type FlightDataCreateSPOHESLOFlight struct {
+	ROT int `json:"rot" example:"0"`
+	// Facility category: heslo-rope-label.
+	HESLORopeLabelID   string `json:"heslo_rope_label_id,omitempty" example:"string"`
+	HESLORopeLabelName string `json:"heslo_rope_label_name,omitempty" example:"string"`
+	// Facility category: heslo-rope-length.
+	Slings []FlightDataCreateSPOHESLOSling `json:"slings,omitempty"`
+}
+
+type FlightDataCreateSPOHESLOSling struct {
+	// Facility category: heslo-rope-length.
+	SlingID   string `json:"sling_id,omitempty" example:"string"`
+	SlingName string `json:"sling_name,omitempty" example:"string"`
+}
+
+type FlightDataCreateSPOLoggingAttributes struct {
+	Slings []FlightDataCreateSPOLoggingSling `json:"slings,omitempty"`
+}
+
+type FlightDataCreateSPOLoggingSling struct {
+	// Facility category: heslo-hook.
+	SlingID   string `json:"sling_id,omitempty" example:"string"`
+	SlingName string `json:"sling_name,omitempty" example:"string"`
+}
+
+type FlightDataCreateSPOHECAttributes struct {
+	Flights []FlightDataCreateSPOHECFlight `json:"flights,omitempty"`
+	Loads   []FlightDataCreateSPOHECLoad   `json:"loads,omitempty"`
+	Slings  []FlightDataCreateSPOHECSling  `json:"slings,omitempty"`
+}
+
+type FlightDataCreateSPOHECFlight struct {
+	// Facility category: hec-rope-label.
+	EquipmentID   string `json:"equipment_id,omitempty" example:"string"`
+	EquipmentName string `json:"equipment_name,omitempty" example:"string"`
+	HECCycle      int    `json:"hec_cycle" example:"0"`
+	ROT           int    `json:"rot" example:"0"`
+}
+
+type FlightDataCreateSPOHECLoad struct {
+	// Weight band for the HEC load, e.g. "bis 199 kg", "200-600 kg", "600-800 kg", "800-1000 kg".
+	LoadCategory string `json:"load_category,omitempty" example:"200-600 kg"`
+	Quantity     int    `json:"quantity" example:"3"`
+}
+
+type FlightDataCreateSPOHECSling struct {
+	// Facility category: hec-rope-length.
+	SlingID   string `json:"sling_id,omitempty" example:"string"`
+	SlingName string `json:"sling_name,omitempty" example:"string"`
+}
+
+type FlightDataCreateData struct {
+	Type       string                     `json:"type" validate:"required,oneof=flight_data_create flight_data" example:"flight_data_create"`
+	Attributes FlightDataCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FlightDataCreateRequest struct {
+	Data FlightDataCreateData `json:"data" validate:"required"`
+}
+
+type FlightDataUpdateData struct {
+	Type       string                     `json:"type" validate:"required,oneof=flight_data_update" example:"flight_data_update"`
+	Attributes FlightDataCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FlightDataUpdateRequest struct {
+	Data FlightDataUpdateData `json:"data" validate:"required"`
+}
+
+// FlightDataCreateSPOExampleRequest is used only for Swagger examples.
+// Runtime parsing still uses FlightDataCreateRequest.
+type FlightDataCreateSPOExampleRequest struct {
+	Data FlightDataCreateSPOExampleData `json:"data"`
+}
+
+type FlightDataCreateSPOExampleData struct {
+	Type       string                               `json:"type" example:"flight_data_create"`
+	Attributes FlightDataCreateSPOExampleAttributes `json:"attributes"`
+}
+
+type FlightDataCreateSPOExampleAttributes struct {
+	MissionID          string `json:"mission_id" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	CoPilotID          string `json:"co_pilot_id,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	FlightTakeOff      string `json:"flight_take_off,omitempty" example:"2026-04-20T08:00:00Z"`
+	FlightLanding      string `json:"flight_landing,omitempty" example:"2026-04-20T09:15:00Z"`
+	FromICAOID         string `json:"from_icao_id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	ToICAOID           string `json:"to_icao_id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	HookReleases       int    `json:"hook_releases,omitempty" example:"0"`
+	TicketNo           string `json:"ticket_no,omitempty" example:"SPO-001"`
+	Engine             string `json:"engine,omitempty" example:"AIRBUS H145"`
+	DeliveryNoteNumber string `json:"delivery_note_number,omitempty" example:"DN-2026-0001"`
+	CustomerName       string `json:"customer_name,omitempty" example:"Patient Transfer"`
+	OtherInformation   string `json:"other_information,omitempty" example:"SPO mission sample"`
+}
diff --git a/internal/transport/http/dto/request/flight_inspection_file_checklist_request.go b/internal/transport/http/dto/request/flight_inspection_file_checklist_request.go
new file mode 100644
index 0000000..a5cb003
--- /dev/null
+++ b/internal/transport/http/dto/request/flight_inspection_file_checklist_request.go
@@ -0,0 +1,32 @@
+package request
+
+type FlightInspectionFileChecklistCreateAttributes struct {
+	IsDone             *bool  `json:"is_done,omitempty" example:"false"`
+	HelicopterFileID   string `json:"helicopter_file_id" validate:"required" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	FlightInspectionID string `json:"flight_inspection_id" validate:"required" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+}
+
+type FlightInspectionFileChecklistCreateData struct {
+	Type       string                                        `json:"type" validate:"required,oneof=flight_inspection_file_checklist_create flight_inspection_file_checklist" example:"flight_inspection_file_checklist_create"`
+	Attributes FlightInspectionFileChecklistCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FlightInspectionFileChecklistCreateRequest struct {
+	Data FlightInspectionFileChecklistCreateData `json:"data" validate:"required"`
+}
+
+type FlightInspectionFileChecklistUpdateAttributes struct {
+	IsDone             *bool   `json:"is_done,omitempty" example:"true"`
+	HelicopterFileID   *string `json:"helicopter_file_id,omitempty" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	FlightInspectionID *string `json:"flight_inspection_id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+}
+
+type FlightInspectionFileChecklistUpdateData struct {
+	Type       string                                        `json:"type" validate:"required,oneof=flight_inspection_file_checklist_update flight_inspection_file_checklist" example:"flight_inspection_file_checklist_update"`
+	ID         string                                        `json:"id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Attributes FlightInspectionFileChecklistUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type FlightInspectionFileChecklistUpdateRequest struct {
+	Data FlightInspectionFileChecklistUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/flight_request.go b/internal/transport/http/dto/request/flight_request.go
new file mode 100644
index 0000000..5a7fae0
--- /dev/null
+++ b/internal/transport/http/dto/request/flight_request.go
@@ -0,0 +1,32 @@
+package request
+
+type FlightCreateAttributes struct {
+	Date         string  `json:"date" validate:"required" example:"2026-04-14"`
+	DutyRosterID *string `json:"duty_roster_id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	ReserveAcID  *string `json:"reserve_ac_id,omitempty" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+}
+
+type FlightCreateData struct {
+	Type       string                 `json:"type" validate:"required,oneof=flight_create flight" example:"flight_create"`
+	Attributes FlightCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type FlightCreateRequest struct {
+	Data FlightCreateData `json:"data" validate:"required"`
+}
+
+type FlightUpdateAttributes struct {
+	Date         *string `json:"date,omitempty" example:"2026-04-14"`
+	DutyRosterID *string `json:"duty_roster_id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	ReserveAcID  *string `json:"reserve_ac_id,omitempty" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+}
+
+type FlightUpdateData struct {
+	Type       string                 `json:"type" validate:"required,oneof=flight_update flight" example:"flight_update"`
+	ID         string                 `json:"id" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	Attributes FlightUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type FlightUpdateRequest struct {
+	Data FlightUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/fm_report_request.go b/internal/transport/http/dto/request/fm_report_request.go
new file mode 100644
index 0000000..8380ea2
--- /dev/null
+++ b/internal/transport/http/dto/request/fm_report_request.go
@@ -0,0 +1,21 @@
+package request
+
+type FMReportUpdateAttributes struct {
+	// Engine1GpcN1 - GPC/N1 value for engine 1. Optional.
+	Engine1GpcN1 *string `json:"engine1_gpc_n1,omitempty" example:"GPC/N1 63.2"`
+	// Engine1PtcN2 - PTC/N2 value for engine 1. Optional.
+	Engine1PtcN2 *string `json:"engine1_ptc_n2,omitempty" example:"PTC/N2 61.8"`
+	// Engine2GpcN1 - GPC/N1 value for engine 2. Optional.
+	Engine2GpcN1 *string `json:"engine2_gpc_n1,omitempty" example:"GPC/N1 63.2"`
+	// Engine2PtcN2 - PTC/N2 value for engine 2. Optional.
+	Engine2PtcN2 *string `json:"engine2_ptc_n2,omitempty" example:"PTC/N2 61.8"`
+}
+
+type FMReportUpdateData struct {
+	Type       string                   `json:"type" validate:"required,oneof=fm_report_update fm_report" example:"fm_report_update"`
+	Attributes FMReportUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type FMReportUpdateRequest struct {
+	Data FMReportUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/helicopter_file_request.go b/internal/transport/http/dto/request/helicopter_file_request.go
new file mode 100644
index 0000000..7b35aba
--- /dev/null
+++ b/internal/transport/http/dto/request/helicopter_file_request.go
@@ -0,0 +1,87 @@
+package request
+
+type HelicopterFileCreateAttributes struct {
+	Section          string  `json:"section" validate:"required,oneof=bfi fpwb afi" enums:"bfi,fpwb,afi" example:"bfi"`
+	Position         *int    `json:"position,omitempty" example:"1"`
+	IsMandatory     *bool   `json:"is_mandatory,omitempty" example:"true"`
+	HelicopterID     string  `json:"helicopter_id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	UploadIntentUUID string  `json:"upload_intent_uuid" validate:"required" example:"019d6d0d-2de2-7db1-80a2-2862d43af620"`
+	FileName         string  `json:"file_name" validate:"required" example:"Before Flight Checklist.pdf"`
+	FolderUUID       *string `json:"folder_uuid,omitempty" example:"019d6d0d-8c24-72e3-9f58-c9ea0fbf0bb1"`
+}
+
+type HelicopterFileUploadAttributes struct {
+	Name        string `json:"name" validate:"required" example:"Before Flight Checklist.pdf"`
+	ContentType string `json:"content_type" validate:"required" example:"application/pdf"`
+	SizeBytes   int64  `json:"size_bytes" validate:"required,gte=0" example:"1024"`
+}
+
+type HelicopterFileUploadData struct {
+	Type       string                         `json:"type" validate:"required,oneof=helicopter_file_upload" example:"helicopter_file_upload"`
+	Attributes HelicopterFileUploadAttributes `json:"attributes" validate:"required"`
+}
+
+type HelicopterFileUploadRequest struct {
+	Data HelicopterFileUploadData `json:"data" validate:"required"`
+}
+
+type HelicopterFileUploadBulkRequest struct {
+	Data []HelicopterFileUploadData `json:"data" validate:"required,min=1"`
+}
+
+type HelicopterFileCancelUploadAttributes struct {
+	UploadIntentUUID string `json:"upload_intent_uuid" validate:"required" example:"019d6d0d-2de2-7db1-80a2-2862d43af620"`
+}
+
+type HelicopterFileCancelUploadData struct {
+	Type       string                               `json:"type" validate:"required,oneof=helicopter_file_cancel_upload" example:"helicopter_file_cancel_upload"`
+	Attributes HelicopterFileCancelUploadAttributes `json:"attributes" validate:"required"`
+}
+
+type HelicopterFileCancelUploadBulkRequest struct {
+	Data []HelicopterFileCancelUploadData `json:"data" validate:"required,min=1"`
+}
+
+type HelicopterFileCreateData struct {
+	Type       string                         `json:"type" validate:"required,oneof=helicopter_file_create helicopter_file" example:"helicopter_file_create"`
+	Attributes HelicopterFileCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type HelicopterFileCreateRequest struct {
+	Data HelicopterFileCreateData `json:"data" validate:"required"`
+}
+
+type HelicopterFileCreateBulkRequest struct {
+	Data []HelicopterFileCreateData `json:"data" validate:"required,min=1"`
+}
+
+type HelicopterFileUpdateAttributes struct {
+	Section      *string `json:"section,omitempty" validate:"omitempty,oneof=bfi fpwb afi" enums:"bfi,fpwb,afi" example:"fpwb"`
+	Position     *int    `json:"position,omitempty" example:"1"`
+	IsMandatory *bool   `json:"is_mandatory,omitempty" example:"true"`
+	HelicopterID *string `json:"helicopter_id,omitempty" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	FileName     *string `json:"file_name,omitempty" example:"Before Flight Checklist v2.pdf"`
+}
+
+type HelicopterFileUpdateData struct {
+	Type       string                         `json:"type" validate:"required,oneof=helicopter_file_update helicopter_file" example:"helicopter_file_update"`
+	ID         string                         `json:"id" validate:"required" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Attributes HelicopterFileUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type HelicopterFileUpdateRequest struct {
+	Data HelicopterFileUpdateData `json:"data" validate:"required"`
+}
+
+type HelicopterFileUpdateBulkRequest struct {
+	Data []HelicopterFileUpdateData `json:"data" validate:"required,min=1"`
+}
+
+type HelicopterFileDeleteData struct {
+	Type string `json:"type" validate:"required,oneof=helicopter_file_delete helicopter_file" example:"helicopter_file_delete"`
+	ID   string `json:"id" validate:"required" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+}
+
+type HelicopterFileDeleteRequest struct {
+	Data HelicopterFileDeleteData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/helicopter_request.go b/internal/transport/http/dto/request/helicopter_request.go
new file mode 100644
index 0000000..233c081
--- /dev/null
+++ b/internal/transport/http/dto/request/helicopter_request.go
@@ -0,0 +1,70 @@
+package request
+
+import "wucher/internal/transport/http/dto"
+
+type HelicopterCreateAttributes struct {
+	Designation string   `json:"designation" validate:"required" example:"OE-XHZ"`
+	Identifier  string   `json:"identifier" validate:"required" example:"ABC"`
+	Type        string   `json:"type" validate:"required" example:"EC-135"`
+	SortKey     *int     `json:"sortkey" example:"10"`
+	Engine1     *string  `json:"engine_1,omitempty" example:"TM"`
+	Engine2     *string  `json:"engine_2,omitempty" example:"TM"`
+	Consumption *float64 `json:"consumption_lt_min,omitempty" example:"4.1"`
+	NR1         *bool    `json:"nr1,omitempty" example:"true"`
+	NR2         *bool    `json:"nr2,omitempty" example:"true"`
+	LH          *bool    `json:"lh,omitempty" example:"true"`
+	RH          *bool    `json:"rh,omitempty" example:"true"`
+	MGB         *bool    `json:"mgb,omitempty" example:"true"`
+	IGB         *bool    `json:"igb,omitempty" example:"false"`
+	TGB         *bool    `json:"tgb,omitempty" example:"true"`
+	UTCOffset   *int     `json:"utc_offset,omitempty" example:"-1"`
+	FileUUID    *string  `json:"file_uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"`
+	Dry         *bool    `json:"dry,omitempty" example:"false"`
+	AOG         *bool    `json:"aog,omitempty" example:"false"`
+	AOGReason   *string  `json:"aog_reason,omitempty" example:"Main rotor gearbox fault"`
+	Note        *string  `json:"note,omitempty" example:"Primary HEMS helicopter"`
+	IsActive    *bool    `json:"is_active,omitempty" example:"true"`
+}
+
+type HelicopterCreateData struct {
+	Type       string                     `json:"type" validate:"required,oneof=helicopter_create helicopter" example:"helicopter_create"`
+	Attributes HelicopterCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type HelicopterCreateRequest struct {
+	Data HelicopterCreateData `json:"data" validate:"required"`
+}
+
+type HelicopterUpdateAttributes struct {
+	Designation *string     `json:"designation,omitempty" example:"OE-XHZ"`
+	Identifier  *string     `json:"identifier,omitempty" example:"ABC"`
+	Type        *string     `json:"type,omitempty" example:"EC-135"`
+	SortKey     dto.NullInt `json:"sortkey,omitempty" swaggertype:"integer" example:"10"`
+	Engine1     *string     `json:"engine_1,omitempty" example:"TM"`
+	Engine2     *string     `json:"engine_2,omitempty" example:"TM"`
+	Consumption *float64    `json:"consumption_lt_min,omitempty" example:"4.1"`
+	NR1         *bool       `json:"nr1,omitempty" example:"true"`
+	NR2         *bool       `json:"nr2,omitempty" example:"true"`
+	LH          *bool       `json:"lh,omitempty" example:"true"`
+	RH          *bool       `json:"rh,omitempty" example:"true"`
+	MGB         *bool       `json:"mgb,omitempty" example:"true"`
+	IGB         *bool       `json:"igb,omitempty" example:"false"`
+	TGB         *bool       `json:"tgb,omitempty" example:"true"`
+	UTCOffset   *int        `json:"utc_offset,omitempty" example:"-1"`
+	FileUUID    *string     `json:"file_uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"`
+	Dry         *bool       `json:"dry,omitempty" example:"false"`
+	AOG         *bool       `json:"aog,omitempty" example:"false"`
+	AOGReason   *string     `json:"aog_reason,omitempty" example:"Main rotor gearbox fault"`
+	Note        *string     `json:"note,omitempty" example:"Primary HEMS helicopter"`
+	IsActive    *bool       `json:"is_active,omitempty" example:"true"`
+}
+
+type HelicopterUpdateData struct {
+	Type       string                     `json:"type" validate:"required,oneof=helicopter_update helicopter" example:"helicopter_update"`
+	ID         string                     `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes HelicopterUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type HelicopterUpdateRequest struct {
+	Data HelicopterUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/master_settings_microsoft_entra_request.go b/internal/transport/http/dto/request/master_settings_microsoft_entra_request.go
new file mode 100644
index 0000000..9b1aa7b
--- /dev/null
+++ b/internal/transport/http/dto/request/master_settings_microsoft_entra_request.go
@@ -0,0 +1,19 @@
+package request
+
+type MasterSettingsMicrosoftEntraUpsertAttributes struct {
+	TenantID     string `json:"MS_ENTRA_TENANT_ID" validate:"required" example:"your-tenant-id"`
+	ClientID     string `json:"MS_ENTRA_CLIENT_ID" validate:"required" example:"your-client-id"`
+	ClientSecret string `json:"MS_ENTRA_CLIENT_SECRET" example:"********"`
+	RedirectURL  string `json:"MS_ENTRA_REDIRECT_URL" validate:"required" example:"https://example.com/api/v1/auth/microsoft/callback"`
+	Authority    string `json:"MS_ENTRA_AUTHORITY" validate:"required" example:"https://login.microsoftonline.com/"`
+	Scopes       string `json:"MS_ENTRA_SCOPES" validate:"required" example:"openid,profile,email"`
+}
+
+type MasterSettingsMicrosoftEntraUpsertData struct {
+	Type       string                                       `json:"type" validate:"required,oneof=master_settings_microsoft_entra_upsert master_settings" example:"master_settings_microsoft_entra_upsert"`
+	Attributes MasterSettingsMicrosoftEntraUpsertAttributes `json:"attributes" validate:"required"`
+}
+
+type MasterSettingsMicrosoftEntraUpsertRequest struct {
+	Data MasterSettingsMicrosoftEntraUpsertData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/master_settings_request.go b/internal/transport/http/dto/request/master_settings_request.go
new file mode 100644
index 0000000..5337c93
--- /dev/null
+++ b/internal/transport/http/dto/request/master_settings_request.go
@@ -0,0 +1,36 @@
+package request
+
+type MasterSettingsCreateAttributes struct {
+	CompanyName   string  `json:"company_name" validate:"required" example:"Wucher"`
+	Title         *string `json:"title,omitempty" example:"Welcome to Wucher"`
+	Subtitle      *string `json:"subtitle,omitempty" example:"Flight operations platform"`
+	LogoFileUUID  *string `json:"logo_file_uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CoverFileUUID *string `json:"cover_file_uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type MasterSettingsCreateData struct {
+	Type       string                         `json:"type" validate:"required,oneof=master_settings_create master_settings" example:"master_settings_create"`
+	Attributes MasterSettingsCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type MasterSettingsCreateRequest struct {
+	Data MasterSettingsCreateData `json:"data" validate:"required"`
+}
+
+type MasterSettingsUpdateAttributes struct {
+	CompanyName   *string `json:"company_name,omitempty" example:"Wucher"`
+	Title         *string `json:"title,omitempty" example:"Welcome to Wucher"`
+	Subtitle      *string `json:"subtitle,omitempty" example:"Flight operations platform"`
+	LogoFileUUID  *string `json:"logo_file_uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CoverFileUUID *string `json:"cover_file_uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type MasterSettingsUpdateData struct {
+	Type       string                         `json:"type" validate:"required,oneof=master_settings_update master_settings" example:"master_settings_update"`
+	ID         string                         `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes MasterSettingsUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type MasterSettingsUpdateRequest struct {
+	Data MasterSettingsUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/mcf_request.go b/internal/transport/http/dto/request/mcf_request.go
new file mode 100644
index 0000000..612bcdf
--- /dev/null
+++ b/internal/transport/http/dto/request/mcf_request.go
@@ -0,0 +1,52 @@
+package request
+
+// MCFSetAttributes toggles a helicopter's MCF (Yes/No) and is the DRAFT work endpoint.
+// active=true (or omitted) ACTIVATES it — creates the draft MCF if none is open, or
+// UPDATES the open draft with the provided check-flight fields (all optional; partial
+// edits allowed). Finalize it later via POST /mcf/sign (sign:true).
+// active=false DEACTIVATES it — cancels the open draft ("tidak jadi") and releases the
+// MCF status; the cancelled record stays in the list. A signed MCF is a real event and
+// is not cancelled by this.
+type MCFSetAttributes struct {
+	Active *bool `json:"active,omitempty" example:"true"`
+	// FlightID — OPTIONAL flight this check flight is performed on (on activate).
+	FlightID     string  `json:"flight_id,omitempty" validate:"omitempty,uuid" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	AFHours      string  `json:"af_hours,omitempty" example:"1245.3"`
+	LandingCount *int    `json:"landing_count,omitempty" example:"3"`
+	UTCTime      string  `json:"utc_time,omitempty" example:"2026-06-17T08:30:00Z"`
+	Date         string  `json:"date,omitempty" example:"2026-06-17"`
+	Result       string  `json:"result,omitempty" validate:"omitempty,oneof=passed failed" enums:"passed,failed" example:"passed"`
+	Notes        *string `json:"notes,omitempty" example:"MCF required after engine mount work"`
+}
+
+type MCFSetData struct {
+	Type       string           `json:"type" validate:"required,oneof=mcf_set mcf" example:"mcf_set"`
+	Attributes MCFSetAttributes `json:"attributes" validate:"required"`
+}
+
+type MCFSetRequest struct {
+	Data MCFSetData `json:"data" validate:"required"`
+}
+
+// MCFCompleteAttributes signs (completes) or unsigns an MCF. sign toggles the state:
+//   - sign=true (or omitted) SIGNS it — af_hours, landing_count, utc_time, date and
+//     result are required. "passed" clears the aircraft; "failed" keeps it grounded.
+//   - sign=false UNSIGNS it — reverts the MCF to a draft (the fields below are ignored).
+type MCFCompleteAttributes struct {
+	Sign         *bool   `json:"sign,omitempty" example:"true"`
+	AFHours      string  `json:"af_hours,omitempty" example:"1245.3"`
+	LandingCount *int    `json:"landing_count,omitempty" example:"3"`
+	UTCTime      string  `json:"utc_time,omitempty" example:"2026-06-17T08:30:00Z"`
+	Date         string  `json:"date,omitempty" example:"2026-06-17"`
+	Result       string  `json:"result,omitempty" validate:"omitempty,oneof=passed failed" enums:"passed,failed" example:"passed"`
+	Notes        *string `json:"notes,omitempty" example:"Vibration within limits after check flight"`
+}
+
+type MCFCompleteData struct {
+	Type       string                `json:"type" validate:"required,oneof=mcf_complete mcf_sign mcf" example:"mcf_sign"`
+	Attributes MCFCompleteAttributes `json:"attributes" validate:"required"`
+}
+
+type MCFCompleteRequest struct {
+	Data MCFCompleteData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/mission_request.go b/internal/transport/http/dto/request/mission_request.go
new file mode 100644
index 0000000..1b5729c
--- /dev/null
+++ b/internal/transport/http/dto/request/mission_request.go
@@ -0,0 +1,53 @@
+package request
+
+type MissionFileInput struct {
+	UploadIntentUUID string `json:"upload_intent_uuid" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name             string `json:"name" example:"mission-brief.pdf"`
+}
+
+type MissionCreateAttributes struct {
+	FlightID  string             `json:"flight_id" validate:"required" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	Type      string             `json:"type" validate:"required" example:"HEMS"`
+	SubtypeID string             `json:"subtype_id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a99"`
+	Note      string             `json:"note,omitempty" example:"Mission note"`
+	Files     []MissionFileInput `json:"files,omitempty"`
+}
+
+type MissionCreateData struct {
+	Type       string                  `json:"type" validate:"required,oneof=mission_create mission" example:"mission_create"`
+	Attributes MissionCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type MissionCreateRequest struct {
+	Data MissionCreateData `json:"data" validate:"required"`
+}
+
+type MissionUpdateAttributes struct {
+	Type      string             `json:"type" validate:"required" example:"SPO"`
+	SubtypeID string             `json:"subtype_id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a99"`
+	Note      string             `json:"note,omitempty" example:"Mission note"`
+	Files     []MissionFileInput `json:"files,omitempty"`
+}
+
+type MissionUpdateData struct {
+	Type       string                  `json:"type" validate:"required,oneof=mission_update mission" example:"mission_update"`
+	Attributes MissionUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type MissionUpdateRequest struct {
+	Data MissionUpdateData `json:"data" validate:"required"`
+}
+
+type MissionTypeCreateAttributes struct {
+	CodeType string `json:"code_type" validate:"required" example:"HEMS"`
+	TypeName string `json:"name" validate:"required" example:"HEMS"`
+}
+
+type MissionTypeCreateData struct {
+	Type       string                      `json:"type" validate:"required,oneof=mission_type_create mission_type" example:"mission_type_create"`
+	Attributes MissionTypeCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type MissionTypeCreateRequest struct {
+	Data MissionTypeCreateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/request/other_person_request.go b/internal/transport/http/dto/request/other_person_request.go
new file mode 100644
index 0000000..9d41b0f
--- /dev/null
+++ b/internal/transport/http/dto/request/other_person_request.go
@@ -0,0 +1,18 @@
+package request
+
+// OtherPersonAttributesInput carries the editable fields of a reusable non-staff person.
+type OtherPersonAttributesInput struct {
+	Name        string `json:"name" example:"Guest Person"`
+	MobilePhone string `json:"mobile_phone,omitempty" example:"+43-1234"`
+	Email       string `json:"email,omitempty" example:"guest@example.com"`
+}
+
+type OtherPersonRequestData struct {
+	Type       string                     `json:"type,omitempty" example:"other_person"`
+	Attributes OtherPersonAttributesInput `json:"attributes"`
+}
+
+// OtherPersonRequest is the JSON:API body for create/update of the other-people master.
+type OtherPersonRequest struct {
+	Data OtherPersonRequestData `json:"data"`
+}
diff --git a/internal/transport/http/dto/request/reserve_ac_request.go b/internal/transport/http/dto/request/reserve_ac_request.go
new file mode 100644
index 0000000..b138e35
--- /dev/null
+++ b/internal/transport/http/dto/request/reserve_ac_request.go
@@ -0,0 +1,249 @@
+package request
+
+import "encoding/json"
+
+type ReserveAcCreateAttributes struct {
+	AircraftID string                              `json:"helicopter_id" validate:"required" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	FlightID   string                              `json:"flight_id" validate:"required" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Inspection ReserveAcInspectionCreateAttributes `json:"inspection" validate:"required"`
+}
+
+type ReserveAcInspectionCreateAttributes struct {
+	InspectionDate  string                               `json:"inspection_date" validate:"required" example:"2026-04-15"`
+	Before          ReserveAcBeforeInspectionAttributes  `json:"before" validate:"required"`
+	Prepare         ReserveAcPrepareInspectionAttributes `json:"prepare" validate:"required"`
+	FleetStatusFile ReserveAcFleetStatusFileAttributes   `json:"fleet_status_file,omitempty"`
+}
+
+type ReserveAcBeforeInspectionAttributes struct {
+	OilEngineNR1Checked       *bool                        `json:"oil_engine_nr1_checked,omitempty"`
+	OilEngineNR2Checked       *bool                        `json:"oil_engine_nr2_checked,omitempty"`
+	HydraulicLHChecked        *bool                        `json:"hydraulic_lh_checked,omitempty"`
+	HydraulicRHChecked        *bool                        `json:"hydraulic_rh_checked,omitempty"`
+	OilTransmissionMGBChecked *bool                        `json:"oil_transmission_mgb_checked,omitempty"`
+	OilTransmissionIGBChecked *bool                        `json:"oil_transmission_igb_checked,omitempty"`
+	OilTransmissionTGBChecked *bool                        `json:"oil_transmission_tgb_checked,omitempty"`
+	FuelAmount                *float64                     `json:"fuel_amount,omitempty"`
+	FuelUnit                  *string                      `json:"fuel_unit,omitempty"`
+	FuelAddedAmount           *float64                     `json:"fuel_added_amount,omitempty"`
+	Note                      *string                      `json:"note,omitempty"`
+	FileChecklist             []ReserveAcFileChecklistItem `json:"file_checklist,omitempty"`
+}
+
+type ReserveAcFileChecklistItem struct {
+	HelicopterFileID string `json:"helicopter_file_id" validate:"required" example:"019d7000-aaaa-7bbb-8ccc-111111111111"`
+	IsDone           bool   `json:"is_done" example:"true"`
+}
+
+type ReserveAcPrepareInspectionAttributes struct {
+	NotamBriefing         *bool                        `json:"notam_briefing,omitempty"`
+	WeatherBriefing       *bool                        `json:"weather_briefing,omitempty"`
+	OperationalFlightPlan *bool                        `json:"operational_flight_plan,omitempty"`
+	FileChecklist         []ReserveAcFileChecklistItem `json:"file_checklist,omitempty"`
+}
+
+type ReserveAcFleetStatusFileAttributes struct {
+	FileChecklist []ReserveAcFileChecklistItem `json:"file_checklist,omitempty"`
+}
+
+type ReserveAcAfterFlightInspectionAttributes struct {
+	OilEngineNR1Checked       *string                      `json:"oil_engine_nr1_checked,omitempty"`
+	OilEngineNR2Checked       *string                      `json:"oil_engine_nr2_checked,omitempty"`
+	HydraulicLHChecked        *string                      `json:"hydraulic_lh_checked,omitempty"`
+	HydraulicRHChecked        *string                      `json:"hydraulic_rh_checked,omitempty"`
+	OilTransmissionMGBChecked *string                      `json:"oil_transmission_mgb_checked,omitempty"`
+	OilTransmissionIGBChecked *string                      `json:"oil_transmission_igb_checked,omitempty"`
+	OilTransmissionTGBChecked *string                      `json:"oil_transmission_tgb_checked,omitempty"`
+	Note                      *string                      `json:"note,omitempty"`
+	FileChecklist             []ReserveAcFileChecklistItem `json:"file_checklist,omitempty"`
+}
+
+type ReserveAcAfterFlightInspectionUpsertData struct {
+	Type       string                                   `json:"type" validate:"required,oneof=after_flight_inspection_upsert after_flight_inspection"`
+	Attributes ReserveAcAfterFlightInspectionAttributes `json:"attributes" validate:"required"`
+}
+
+type ReserveAcAfterFlightInspectionUpsertRequest struct {
+	Data ReserveAcAfterFlightInspectionUpsertData `json:"data" validate:"required"`
+}
+
+type LastFlightsInspectionUpsertAttributes struct {
+	FlightInspectionID string `json:"flight_inspection_id" validate:"required"`
+	ReserveAcAfterFlightInspectionAttributes
+}
+
+type LastFlightsInspectionCreateData struct {
+	Type       string                                `json:"type" validate:"required,oneof=last_flights_inspection_create last_flights_inspection"`
+	Attributes LastFlightsInspectionUpsertAttributes `json:"attributes" validate:"required"`
+}
+
+type LastFlightsInspectionCreateRequest struct {
+	Data LastFlightsInspectionCreateData `json:"data" validate:"required"`
+}
+
+type LastFlightsInspectionUpdateData struct {
+	Type       string                                `json:"type" validate:"required,oneof=last_flights_inspection_update last_flights_inspection"`
+	Attributes LastFlightsInspectionUpsertAttributes `json:"attributes" validate:"required"`
+}
+
+type LastFlightsInspectionUpdateRequest struct {
+	Data LastFlightsInspectionUpdateData `json:"data" validate:"required"`
+}
+
+type LastFlightsInspectionDeleteAttributes struct {
+	FlightInspectionID string `json:"flight_inspection_id" validate:"required"`
+}
+
+type LastFlightsInspectionDeleteData struct {
+	Type       string                                `json:"type" validate:"required,oneof=last_flights_inspection_delete last_flights_inspection"`
+	Attributes LastFlightsInspectionDeleteAttributes `json:"attributes" validate:"required"`
+}
+
+type LastFlightsInspectionDeleteRequest struct {
+	Data LastFlightsInspectionDeleteData `json:"data" validate:"required"`
+}
+
+type ReserveAcCreateData struct {
+	Type       string                    `json:"type" validate:"required,oneof=reserve_ac_create reserve_ac" example:"reserve_ac_create"`
+	Attributes ReserveAcCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type ReserveAcCreateRequest struct {
+	Data ReserveAcCreateData `json:"data" validate:"required"`
+}
+
+type ReserveAcUpdateAttributes struct {
+	AircraftID *string                              `json:"helicopter_id,omitempty" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	FlightID   *string                              `json:"flight_id,omitempty" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Inspection *ReserveAcInspectionUpdateAttributes `json:"inspection,omitempty"`
+}
+
+type ReserveAcInspectionUpdateAttributes struct {
+	InspectionDate *string                               `json:"inspection_date,omitempty" example:"2026-04-15"`
+	Before         *ReserveAcBeforeInspectionAttributes  `json:"before,omitempty"`
+	Prepare        *ReserveAcPrepareInspectionAttributes `json:"prepare,omitempty"`
+}
+
+type ReserveAcUpdateData struct {
+	Type       string                    `json:"type" validate:"required,oneof=reserve_ac_update reserve_ac" example:"reserve_ac_update"`
+	ID         string                    `json:"id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Attributes ReserveAcUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type ReserveAcUpdateRequest struct {
+	Data ReserveAcUpdateData `json:"data" validate:"required"`
+}
+
+type ReserveAcDeleteData struct {
+	ID string `json:"id" validate:"required" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+}
+
+type ReserveAcDeleteRequest struct {
+	Data ReserveAcDeleteData `json:"data" validate:"required"`
+}
+
+type TakeoverCreateAttributes struct {
+	BaseID                *string                              `json:"base_id,omitempty"`
+	DutyDate              string                               `json:"duty_date" validate:"required"`
+	Notes                 *string                              `json:"notes,omitempty"`
+	Detail                *TakeoverRosterDetailsInput          `json:"roster_detail,omitempty"`
+	AircraftID            *string                              `json:"helicopter_id,omitempty"`
+	Inspection            *ReserveAcInspectionCreateAttributes `json:"inspection,omitempty"`
+	Files                 []TakeoverCreateFileInput            `json:"files,omitempty" validate:"omitempty,dive"`
+	EditedTemplateFileIDs []string                             `json:"edited_template_file_ids,omitempty" validate:"omitempty,dive,uuid"`
+}
+
+type TakeoverCreateData struct {
+	Type       string                   `json:"type" validate:"required,oneof=takeover_create takeover"`
+	Attributes TakeoverCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type TakeoverCreateRequest struct {
+	Data TakeoverCreateData `json:"data" validate:"required"`
+}
+
+type TakeoverCreateFileInput struct {
+	FileID           string `json:"file_id,omitempty" validate:"omitempty,uuid" example:"019e8713-aa19-7fb7-a510-a0332dc69697"`
+	UploadIntentUUID string `json:"upload_intent_uuid,omitempty" validate:"omitempty,uuid" example:"019e8713-aa19-7fb7-a510-a0332dc69697"`
+	Name             string `json:"name,omitempty" example:"takeover-report.pdf"`
+}
+
+type TakeoverUpdateAttributes struct {
+	BaseID       *string                              `json:"base_id,omitempty"`
+	Bases        *TakeoverBaseRef                     `json:"bases,omitempty"`
+	DutyDate     *string                              `json:"duty_date,omitempty"`
+	Notes        *string                              `json:"notes,omitempty"`
+	Detail       *TakeoverRosterDetailsInput          `json:"roster_detail,omitempty"`
+	RosterDetail *TakeoverRosterDetailsInput          `json:"roster_details,omitempty"`
+	AircraftID   *string                              `json:"helicopter_id,omitempty"`
+	Inspection   *ReserveAcInspectionCreateAttributes `json:"inspection,omitempty"`
+	Files        []TakeoverCreateFileInput            `json:"files,omitempty" validate:"omitempty,dive"`
+	FilesAdd     []TakeoverCreateFileInput            `json:"files_add,omitempty" validate:"omitempty,dive"`
+	FilesRemove  []string                             `json:"files_remove,omitempty" validate:"omitempty,dive,uuid"`
+	FilesReplace []TakeoverCreateFileInput            `json:"files_replace,omitempty" validate:"omitempty,dive"`
+}
+
+type TakeoverUpdateData struct {
+	Type       string                   `json:"type" validate:"required,oneof=takeover_update takeover"`
+	ID         string                   `json:"id"`
+	Attributes TakeoverUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type TakeoverUpdateRequest struct {
+	Data TakeoverUpdateData `json:"data" validate:"required"`
+}
+
+func (a *TakeoverUpdateAttributes) UnmarshalJSON(data []byte) error {
+	type alias TakeoverUpdateAttributes
+	var raw struct {
+		alias
+		Bases        *TakeoverBaseRef            `json:"bases,omitempty"`
+		RosterDetail *TakeoverRosterDetailsInput `json:"roster_details,omitempty"`
+	}
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+	*a = TakeoverUpdateAttributes(raw.alias)
+	if a.BaseID == nil && raw.Bases != nil && raw.Bases.ID != "" {
+		id := raw.Bases.ID
+		a.BaseID = &id
+	}
+	if a.Detail == nil && raw.RosterDetail != nil {
+		a.Detail = raw.RosterDetail
+	}
+	return nil
+}
+
+type TakeoverBaseRef struct {
+	ID string `json:"id,omitempty"`
+}
+
+type TakeoverRosterCrewInput struct {
+	ID string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type TakeoverRosterPilotInput struct {
+	ID               string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FlightInstructor bool   `json:"flight_instructor,omitempty"`
+	LineChecker      bool   `json:"line_checker,omitempty"`
+	Supervisor       bool   `json:"supervisor,omitempty"`
+	Examiner         bool   `json:"examiner,omitempty"`
+	CoPilot          bool   `json:"co_pilot,omitempty"`
+	CrewType         string `json:"crew_type,omitempty" example:"main" enums:"main,additional"`
+}
+
+type TakeoverRosterOtherPersonInput struct {
+	// OtherPersonID — OPTIONAL master person id to reuse (from GET /contact/other).
+	OtherPersonID string `json:"other_person_id,omitempty" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Name          string `json:"name,omitempty" example:"Guest Person"`
+	MobilePhone   string `json:"mobile_phone,omitempty" example:"+43-1234"`
+	Email         string `json:"email,omitempty" example:"guest@example.com"`
+}
+
+type TakeoverRosterDetailsInput struct {
+	Pilot       []TakeoverRosterPilotInput       `json:"pilot"`
+	Doctor      []TakeoverRosterCrewInput        `json:"doctor"`
+	Rescuer     []TakeoverRosterCrewInput        `json:"rescuer"`
+	Helper      []TakeoverRosterCrewInput        `json:"helper"`
+	OtherPerson []TakeoverRosterOtherPersonInput `json:"other_person"`
+}
diff --git a/internal/transport/http/dto/response/action_signoff_response.go b/internal/transport/http/dto/response/action_signoff_response.go
new file mode 100644
index 0000000..e6b254f
--- /dev/null
+++ b/internal/transport/http/dto/response/action_signoff_response.go
@@ -0,0 +1,26 @@
+package response
+
+type ActionSignoffAttributes struct {
+	HelicopterID string `json:"helicopter_id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	FlightID     string `json:"flight_id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	// Signed — true once checked; gates the maintenance release form.
+	Signed bool `json:"signed" example:"false"`
+	// SignedAt / SignedBy — when/who signed; empty until signed.
+	SignedAt *string `json:"signed_at,omitempty" example:"2026-06-16T03:04:05Z"`
+	SignedBy string  `json:"signed_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	// SignedByName / SignedByShort — resolved display name + 3-letter short of the signer.
+	SignedByName  *string `json:"signed_by_name,omitempty" example:"John Doe"`
+	SignedByShort *string `json:"signed_by_short,omitempty" example:"JDO"`
+	CreatedAt     string  `json:"created_at,omitempty" example:"2026-06-16T03:04:05Z"`
+	UpdatedAt    string  `json:"updated_at,omitempty" example:"2026-06-16T03:04:05Z"`
+}
+
+type ActionSignoffResource struct {
+	Type       string                  `json:"type" example:"action_signoff"`
+	ID         string                  `json:"id,omitempty" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Attributes ActionSignoffAttributes `json:"attributes"`
+}
+
+type ActionSignoffResponse struct {
+	Data ActionSignoffResource `json:"data"`
+}
diff --git a/internal/transport/http/dto/response/air_rescuer_checklist_response.go b/internal/transport/http/dto/response/air_rescuer_checklist_response.go
new file mode 100644
index 0000000..3eff448
--- /dev/null
+++ b/internal/transport/http/dto/response/air_rescuer_checklist_response.go
@@ -0,0 +1,124 @@
+package response
+
+import shareddto "wucher/internal/transport/http/dto/shared"
+
+type AirRescuerChecklistItemResource struct {
+	ID        string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name      string `json:"name,omitempty" example:"Oxygen supply check"`
+	Position  int    `json:"position,omitempty" example:"1"`
+	CreatedBy string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+}
+
+type AirRescuerChecklistAttributes struct {
+	Bases       shareddto.AirRescuerChecklistBaseInfo `json:"bases"`
+	ScopeCode   string                                `json:"scope_code,omitempty" example:"TU"`
+	ScopeCodeDe string                                `json:"scope_code_de,omitempty" example:"DI"`
+	Title       string                                `json:"title,omitempty" example:"Monday Checklist"`
+	Position    int                                   `json:"position,omitempty" example:"1"`
+	Items       []AirRescuerChecklistItemResource     `json:"items"`
+	CreatedBy   string                                `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt   string                                `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt   string                                `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+}
+
+type AirRescuerChecklistResource struct {
+	Type       string                        `json:"type" example:"air_rescuer_checklist"`
+	ID         string                        `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes AirRescuerChecklistAttributes `json:"attributes"`
+}
+
+type AirRescuerChecklistResponse struct {
+	Data AirRescuerChecklistResource `json:"data"`
+}
+
+type AirRescuerChecklistBulkResponse struct {
+	Data []AirRescuerChecklistResource `json:"data"`
+}
+
+type AirRescuerChecklistItemAttributes struct {
+	ChecklistID string `json:"checklist_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name        string `json:"name,omitempty" example:"Check radio"`
+	Position    int    `json:"position,omitempty" example:"1"`
+	CreatedBy   string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt   string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt   string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+}
+
+type AirRescuerChecklistItemData struct {
+	Type       string                            `json:"type" example:"air_rescuer_checklist_item"`
+	ID         string                            `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes AirRescuerChecklistItemAttributes `json:"attributes"`
+}
+
+type AirRescuerChecklistItemResponse struct {
+	Data AirRescuerChecklistItemData `json:"data"`
+}
+
+type AirRescuerChecklistItemBulkResponse struct {
+	Data []AirRescuerChecklistItemData `json:"data"`
+}
+
+type AirRescuerChecklistCATChecklistSummary struct {
+	ID        string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Title     string `json:"title,omitempty" example:"Cockpit Flugretter"`
+	Position  int    `json:"position,omitempty" example:"1"`
+	CreatedBy string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+}
+
+type AirRescuerChecklistCATGroup struct {
+	ScopeCode       string                                   `json:"scope_code,omitempty" example:"DA"`
+	ScopeCodeDe     string                                   `json:"scope_code_de,omitempty" example:"TA"`
+	ScopeCodeName   string                                   `json:"scope_code_name,omitempty" example:"Daily"`
+	ScopeCodeNameDe string                                   `json:"scope_code_name_de,omitempty" example:"Taeglich"`
+	Checklists      []AirRescuerChecklistCATChecklistSummary `json:"checklists"`
+}
+
+type AirRescuerChecklistTabChecklistDetail struct {
+	ID             string                            `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Title          string                            `json:"title,omitempty" example:"Monday Checklist"`
+	Position       int                               `json:"position,omitempty" example:"1"`
+	ChecklistItems []AirRescuerChecklistItemResource `json:"checklist_items"`
+	CreatedBy      string                            `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt      string                            `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt      string                            `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+}
+
+type AirRescuerChecklistTabResource struct {
+	ScopeCode       string                                   `json:"scope_code,omitempty" example:"DA"`
+	ScopeCodeDe     string                                   `json:"scope_code_de,omitempty" example:"TA"`
+	ScopeCodeName   string                                   `json:"scope_code_name,omitempty" example:"Daily"`
+	ScopeCodeNameDe string                                   `json:"scope_code_name_de,omitempty" example:"Taeglich"`
+	Groups          []AirRescuerChecklistCATGroup            `json:"groups,omitempty"`
+	Checklists      *[]AirRescuerChecklistTabChecklistDetail `json:"checklists,omitempty"`
+}
+
+type AirRescuerChecklistBaseGroupAttributes struct {
+	Bases shareddto.AirRescuerChecklistBaseInfo `json:"bases"`
+	Tabs  []AirRescuerChecklistTabResource      `json:"tabs"`
+}
+
+type AirRescuerChecklistBaseGroupResource struct {
+	Type       string                                 `json:"type" example:"air_rescuer_checklist_group"`
+	ID         string                                 `json:"id,omitempty" example:"base-018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes AirRescuerChecklistBaseGroupAttributes `json:"attributes"`
+}
+
+type AirRescuerChecklistGroupedListResponse struct {
+	Data []AirRescuerChecklistBaseGroupResource `json:"data"`
+	Meta struct {
+		TotalBases int `json:"total_bases" example:"8"`
+	} `json:"meta"`
+}
+
+type AirRescuerChecklistGroupedDataTableResponse struct {
+	Data []AirRescuerChecklistBaseGroupResource `json:"data"`
+	Meta struct {
+		Draw            int `json:"draw" example:"1"`
+		RecordsTotal    int `json:"records_total" example:"8"`
+		RecordsFiltered int `json:"records_filtered" example:"8"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/complaint_response.go b/internal/transport/http/dto/response/complaint_response.go
new file mode 100644
index 0000000..2a18895
--- /dev/null
+++ b/internal/transport/http/dto/response/complaint_response.go
@@ -0,0 +1,98 @@
+package response
+
+import shareddto "wucher/internal/transport/http/dto/shared"
+
+// ComplaintMEL groups the MEL deferral attributes. All fields are always present
+// (null when not set) so the response shape is predictable for clients.
+type ComplaintMEL struct {
+	// Severity — MEL class: 0=NON-MEL, 1=A, 2=B, 3=C, 4=D. Always set (classification is required at creation).
+	Severity int8 `json:"severity" example:"2" enums:"0,1,2,3,4"`
+	// SeverityLabel — human label of the severity (NON-MEL/A/B/C/D).
+	SeverityLabel *string `json:"severity_label" example:"B"`
+	// ClassifiedAt / ClassifiedByName / ClassifiedByShort — when/who classified the MEL.
+	ClassifiedAt      *string `json:"classified_at" example:"2026-06-15T03:04:05Z"`
+	ClassifiedByName  *string `json:"classified_by_name" example:"John Doe"`
+	ClassifiedByShort *string `json:"classified_by_short" example:"JDO"`
+	// Deadline — grace deadline; after this the aircraft is AOG. null for NON-MEL.
+	Deadline *string `json:"deadline" example:"2026-06-18T03:04:05Z"`
+}
+
+type ComplaintNSR struct {
+	// IsNSR — Non-Safety Release: true = aircraft released to fly despite the open defect.
+	IsNSR bool `json:"is_nsr" example:"false"`
+	// Reason — optional justification for the NSR decision.
+	Reason *string `json:"reason" example:"not required"`
+	// DecidedAt / DecidedByName / DecidedByShort — when/who decided NSR (may differ from the reporter).
+	DecidedAt      *string `json:"decided_at" example:"2026-06-15T03:04:05Z"`
+	DecidedByName  *string `json:"decided_by_name" example:"John Doe"`
+	DecidedByShort *string `json:"decided_by_short" example:"JDO"`
+}
+
+type ComplaintAttributes struct {
+	HelicopterID          string                           `json:"helicopter_id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	FlightID              string                           `json:"flight_id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	Description           string                           `json:"description" example:"Engine 2 N2 vibration intermittent during cruise above 110 KIAS"`
+	Helicopter            *shareddto.FleetStatusHelicopter `json:"helicopter,omitempty"`
+	ReportedBy            string                           `json:"reported_by" example:"John Doe"`
+	ReportedByShort       string                           `json:"reported_by_short,omitempty" example:"JDO"`
+	ReportedAt            string                           `json:"reported_at" example:"2026-06-15T03:04:05Z"`
+	AircraftHoursAtReport *string                          `json:"aircraft_hours_at_report" example:"1245.3"`
+	MEL                   ComplaintMEL                     `json:"mel"`
+	NSR                   ComplaintNSR                     `json:"nsr"`
+	ActionSigned          bool                             `json:"action_signed" example:"true"`
+	ActionTaken           *string                          `json:"action_taken" example:"tightened mount"`
+	ActionSignedAt        *string                          `json:"action_signed_at" example:"2026-06-15T03:04:05Z"`
+	ActionSignedByName    *string                          `json:"action_signed_by_name" example:"John Doe"`
+	ActionSignedByShort   *string                          `json:"action_signed_by_short" example:"JDO"`
+	AircraftHoursAtFix    *string                          `json:"aircraft_hours_at_fix" example:"1250.1"`
+	Status                string                           `json:"status" example:"active_mel" enums:"active_non_mel,active_mel,serviced"`
+	CreatedAt             string                           `json:"created_at" example:"2026-06-15T03:04:05Z"`
+	UpdatedAt             string                           `json:"updated_at" example:"2026-06-15T03:04:05Z"`
+}
+
+type ComplaintResource struct {
+	Type       string              `json:"type" example:"complaint"`
+	ID         string              `json:"id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Attributes ComplaintAttributes `json:"attributes"`
+}
+
+type ComplaintResponse struct {
+	Data ComplaintResource `json:"data"`
+}
+
+type ComplaintListResponse struct {
+	Data []ComplaintResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
+
+type ComplaintHelicopterGroupAttributes struct {
+	Helicopter *shareddto.FleetStatusHelicopter `json:"helicopter"`
+	Complaints []ComplaintResource              `json:"complaints"`
+}
+
+type ComplaintHelicopterGroupResource struct {
+	Type       string                             `json:"type" example:"complaint_helicopter_group"`
+	Attributes ComplaintHelicopterGroupAttributes `json:"attributes"`
+}
+
+type ComplaintGroupedListResponse struct {
+	Data []ComplaintHelicopterGroupResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
+
+type ComplaintGroupedDataTableResponse struct {
+	Data []ComplaintHelicopterGroupResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"1"`
+		RecordsFiltered int64 `json:"records_filtered" example:"1"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/duty_roster_response.go b/internal/transport/http/dto/response/duty_roster_response.go
new file mode 100644
index 0000000..433e44d
--- /dev/null
+++ b/internal/transport/http/dto/response/duty_roster_response.go
@@ -0,0 +1,227 @@
+package response
+
+type DutyRosterShiftTime struct {
+	ShiftStart string `json:"shift_start,omitempty" example:"06:00"`
+	ShiftEnd   string `json:"shift_end,omitempty" example:"21:00"`
+}
+
+type DutyRosterShiftDate struct {
+	DateStart string `json:"date_start,omitempty" example:"2026-03-16"`
+	DateEnd   string `json:"date_end,omitempty" example:"2026-03-16"`
+}
+
+type DutyRosterCrew struct {
+	ID          string               `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name        string               `json:"name,omitempty" example:"Hunter Wolfgang"`
+	Role        string               `json:"role,omitempty" example:"doctor"`
+	MobilePhone string               `json:"mobile_phone,omitempty" example:"+43-1234"`
+	Email       string               `json:"email,omitempty" example:"doctor@example.com"`
+	ShiftDate   *DutyRosterShiftDate `json:"shift_date,omitempty"`
+	ShiftTime   *DutyRosterShiftTime `json:"shift_time,omitempty"`
+}
+
+type DutyRosterPilotCrew struct {
+	ID               string               `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name             string               `json:"name,omitempty" example:"Hunter Wolfgang"`
+	Role             string               `json:"role,omitempty" example:"pilot"`
+	MobilePhone      string               `json:"mobile_phone,omitempty" example:"+43-1234"`
+	Email            string               `json:"email,omitempty" example:"pilot@example.com"`
+	ShiftDate        *DutyRosterShiftDate `json:"shift_date,omitempty"`
+	CrewType         string               `json:"crew_type,omitempty" example:"main"`
+	FlightInstructor *bool                `json:"flight_instructor,omitempty"`
+	LineChecker      *bool                `json:"line_checker,omitempty"`
+	Supervisor       *bool                `json:"supervisor,omitempty"`
+	Examiner         *bool                `json:"examiner,omitempty"`
+	CoPilot          *bool                `json:"co_pilot,omitempty"`
+}
+
+type DutyRosterDetailsResponse struct {
+	Pilot       []DutyRosterPilotCrew `json:"pilot"`
+	Doctor      []DutyRosterCrew      `json:"doctor"`
+	Rescuer     []DutyRosterCrew      `json:"rescuer"`
+	Helper      []DutyRosterCrew      `json:"helper"`
+	OtherPerson []DutyRosterCrew      `json:"other_person"`
+}
+
+type DutyRosterBaseInfo struct {
+	ID               string              `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Type             string              `json:"type,omitempty" example:"hems"`
+	BaseName         string              `json:"base_name,omitempty" example:"Gallus 1 - Zurs Lech"`
+	BaseAbbreviation string              `json:"base_abbreviation,omitempty" example:"G1"`
+	ShiftTime        DutyRosterShiftTime `json:"shift_time,omitempty"`
+}
+
+type DutyRosterHelicopterSummary struct {
+	ID          string `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Designation string `json:"designation" example:"OE-XHZ"`
+	Identifier  string `json:"identifier" example:"1234"`
+	Type        string `json:"type" example:"EC-135"`
+}
+
+type DutyRosterAttributes struct {
+	Bases      DutyRosterBaseInfo          `json:"bases"`
+	FlightID   string                      `json:"flight_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Helicopter DutyRosterHelicopterSummary `json:"helicopter"`
+	DutyDate   string                      `json:"duty_date,omitempty" example:"2026-03-16"`
+	ShiftTime  DutyRosterShiftTime         `json:"shift_time"`
+	Detail     DutyRosterDetailsResponse   `json:"roster_detail"`
+	CreatedBy  string                      `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt  string                      `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt  string                      `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+}
+
+type DutyRosterResource struct {
+	Type       string               `json:"type" example:"duty_roster"`
+	ID         string               `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes DutyRosterAttributes `json:"attributes"`
+}
+
+type DutyRosterResponse struct {
+	Data DutyRosterResource `json:"data"`
+}
+
+type DutyRosterListResponse struct {
+	Data []DutyRosterResource `json:"data"`
+	Meta struct {
+		Total int `json:"total" example:"31"`
+	} `json:"meta"`
+}
+
+type DutyRosterGetAllMeta struct {
+	PageNumber      int    `json:"page_number"`
+	PageSize        int    `json:"page_size"`
+	RecordsTotal    int    `json:"records_total"`
+	RecordsFiltered int    `json:"records_filtered"`
+	From            string `json:"from"`
+	To              string `json:"to"`
+	Timezone        string `json:"timezone"`
+	Total           int    `json:"total"`
+}
+
+type DutyRosterGetAllData struct {
+	HEMS []DutyRosterBaseGroupResource `json:"hems_base"`
+	Base []DutyRosterBaseGroupResource `json:"base"`
+}
+
+type DutyRosterGetAllResponse struct {
+	Data DutyRosterGetAllData `json:"data"`
+	Meta DutyRosterGetAllMeta `json:"meta"`
+}
+
+type DutyRosterAnyResource struct {
+	Type       string         `json:"type"`
+	ID         string         `json:"id,omitempty"`
+	Attributes map[string]any `json:"attributes"`
+}
+
+type DutyRosterAnyResponse struct {
+	Data DutyRosterAnyResource `json:"data"`
+}
+
+type DutyRosterAnyListResponse struct {
+	Data []DutyRosterAnyResource `json:"data"`
+	Meta struct {
+		Total int `json:"total" example:"31"`
+	} `json:"meta"`
+}
+
+type DutyRosterAnyDeleteResponse struct {
+	Data DutyRosterAnyDeleteResource `json:"data"`
+}
+
+type DutyRosterAnyDeleteResource struct {
+	Type       string                        `json:"type" example:"duty_roster_delete"`
+	Attributes DutyRosterAnyDeleteAttributes `json:"attributes"`
+}
+
+type DutyRosterAnyDeleteAttributes struct {
+	Deleted bool               `json:"deleted" example:"true"`
+	ID      string             `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Base    DutyRosterBaseInfo `json:"base"`
+}
+
+type DutyRosterUnifiedDataTableResponse struct {
+	Data DutyRosterGetAllData           `json:"data"`
+	Meta DutyRosterUnifiedDataTableMeta `json:"meta"`
+}
+
+type DutyRosterUnifiedDataTableMeta struct {
+	Draw            int    `json:"draw" example:"1"`
+	RecordsTotal    int    `json:"records_total" example:"20"`
+	RecordsFiltered int    `json:"records_filtered" example:"20"`
+	PageNumber      int    `json:"page_number" example:"1"`
+	PageSize        int    `json:"page_size" example:"20"`
+	From            string `json:"from" example:"2026-03-01"`
+	To              string `json:"to" example:"2026-03-31"`
+	Timezone        string `json:"timezone" example:"UTC"`
+	Total           int    `json:"total" example:"20"`
+	TotalGroups     int    `json:"total_groups" example:"20"`
+	TotalRosters    int    `json:"total_rosters" example:"45"`
+	NonEmptyGroups  int    `json:"non_empty_groups" example:"18"`
+}
+
+type DutyRosterGroupRoster struct {
+	ID         string                      `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FlightID   string                      `json:"flight_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DutyDate   string                      `json:"duty_date,omitempty" example:"2026-03-16"`
+	ShiftTime  DutyRosterShiftTime         `json:"shift_time"`
+	Helicopter DutyRosterHelicopterSummary `json:"helicopter"`
+	Detail     DutyRosterDetailsResponse   `json:"roster_detail"`
+	CreatedBy  string                      `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt  string                      `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt  string                      `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+}
+
+type DutyRosterBaseGroupAttributes struct {
+	Bases   DutyRosterBaseInfo      `json:"bases"`
+	Rosters []DutyRosterGroupRoster `json:"rosters"`
+}
+
+type DutyRosterBaseGroupResource struct {
+	Type       string                        `json:"type" example:"hems_base_roster_group"`
+	Attributes DutyRosterBaseGroupAttributes `json:"attributes"`
+}
+
+type DutyRosterGroupedListResponse struct {
+	Data []DutyRosterBaseGroupResource `json:"data"`
+	Meta struct {
+		From       string `json:"from,omitempty" example:"2026-03-16"`
+		To         string `json:"to,omitempty" example:"2026-04-15"`
+		TotalBases int    `json:"total_bases" example:"8"`
+	} `json:"meta"`
+}
+
+type DutyRosterGroupedDataTableResponse struct {
+	Data []DutyRosterBaseGroupResource `json:"data"`
+	Meta struct {
+		Draw            int `json:"draw" example:"1"`
+		RecordsTotal    int `json:"records_total" example:"8"`
+		RecordsFiltered int `json:"records_filtered" example:"8"`
+	} `json:"meta"`
+}
+
+type DutyRosterDeletedCrewItem struct {
+	ID        string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	RosterID  string `json:"roster_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UserID    string `json:"user_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name      string `json:"name,omitempty" example:"Pilot One"`
+	RoleCode  string `json:"role_code,omitempty" example:"pilot"`
+	CrewType  string `json:"crew_type,omitempty" example:"main"`
+	DateStart string `json:"date_start,omitempty" example:"2026-03-20"`
+	DateEnd   string `json:"date_end,omitempty" example:"2026-03-22"`
+}
+
+type DutyRosterCrewDeleteAttributes struct {
+	Deleted      bool                        `json:"deleted" example:"true"`
+	DeletedCount int                         `json:"deleted_count" example:"1"`
+	DeletedItems []DutyRosterDeletedCrewItem `json:"deleted_items"`
+}
+
+type DutyRosterCrewDeleteResource struct {
+	Type       string                         `json:"type" example:"duty_roster_crew_delete"`
+	Attributes DutyRosterCrewDeleteAttributes `json:"attributes"`
+}
+
+type DutyRosterCrewDeleteResponse struct {
+	Data DutyRosterCrewDeleteResource `json:"data"`
+}
diff --git a/internal/transport/http/dto/response/easa_release_response.go b/internal/transport/http/dto/response/easa_release_response.go
new file mode 100644
index 0000000..01eb03a
--- /dev/null
+++ b/internal/transport/http/dto/response/easa_release_response.go
@@ -0,0 +1,55 @@
+package response
+
+type EASAReleaseAttributes struct {
+	HelicopterID               string  `json:"helicopter_id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	ComplaintID                string  `json:"complaint_id,omitempty" example:"019d6774-1111-7fba-9ef4-3795c0da8a13"`
+	FlightID                   string  `json:"flight_id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	EASADate                   *string `json:"easa_date,omitempty" example:"2026-06-16"`
+	EASAACHours                *string `json:"easa_ac_hours,omitempty" example:"1245.3"`
+	EASALocation               *string `json:"easa_location,omitempty" example:"LOWI"`
+	EASAWONo                   *string `json:"easa_wo_no,omitempty" example:"WO-2026-001"`
+	EASAMaintManualRevAirframe *string `json:"easa_maint_manual_rev_airframe,omitempty" example:"Rev 12"`
+	EASAMaintManualRevEngine   *string `json:"easa_maint_manual_rev_engine,omitempty" example:"Rev 8"`
+	// EASASignerID — contact id (UUIDv7) of the signer/technician.
+	EASASignerID *string `json:"easa_signer_id,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	// EASASignerName / EASASignerShort — resolved display name + 3-letter short of the signer contact.
+	EASASignerName  *string `json:"easa_signer_name,omitempty" example:"John Doe"`
+	EASASignerShort *string `json:"easa_signer_short,omitempty" example:"JDO"`
+	EASAPermitNo    *string `json:"easa_permit_no,omitempty" example:"145.A.50"`
+	// IsSigned — true once the release is signed (Release to Service); then the complaint becomes fixed.
+	IsSigned bool `json:"is_signed" example:"false"`
+	// SignedAt / SignedBy — when/who signed; empty until signed.
+	SignedAt *string `json:"signed_at,omitempty" example:"2026-06-16T03:04:05Z"`
+	SignedBy string  `json:"signed_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	// MissingSignFields — required fields still empty; must all be filled before it can be signed.
+	MissingSignFields []string `json:"missing_sign_fields,omitempty"`
+	CreatedAt         string   `json:"created_at" example:"2026-06-16T03:04:05Z"`
+	UpdatedAt         string   `json:"updated_at" example:"2026-06-16T03:04:05Z"`
+}
+
+type EASAReleaseResource struct {
+	Type       string                `json:"type" example:"easa_release"`
+	ID         string                `json:"id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Attributes EASAReleaseAttributes `json:"attributes"`
+}
+
+type EASAReleaseResponse struct {
+	Data EASAReleaseResource `json:"data"`
+}
+
+// EASAReleaseDeleteResponse is the ack returned when an EASA release is voided/deleted.
+type EASAReleaseDeleteResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"easa_release_delete"`
+		Attributes struct {
+			Deleted bool `json:"deleted" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type EASAReleaseListResponse struct {
+	Data []EASAReleaseResource `json:"data"`
+	Meta struct {
+		Total int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/file_manager_action_response.go b/internal/transport/http/dto/response/file_manager_action_response.go
new file mode 100644
index 0000000..04f0c18
--- /dev/null
+++ b/internal/transport/http/dto/response/file_manager_action_response.go
@@ -0,0 +1,85 @@
+package response
+
+type FileManagerActionLocation struct {
+	FolderID string `json:"folder_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FileManagerActionResultAttributes struct {
+	Status   string                     `json:"status" example:"trashed"`
+	Location *FileManagerActionLocation `json:"location,omitempty"`
+}
+
+type FileManagerActionResultResource struct {
+	Type       string                            `json:"type" example:"file_manager_delete_result"`
+	ID         string                            `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes FileManagerActionResultAttributes `json:"attributes"`
+}
+
+type FileManagerActionResultResponse struct {
+	Data FileManagerActionResultResource `json:"data"`
+}
+
+type FileManagerMoveNodeResultAttributes struct {
+	NodeType string                     `json:"node_type" example:"folder"`
+	Status   string                     `json:"status" example:"moved"`
+	Location *FileManagerActionLocation `json:"location,omitempty"`
+}
+
+type FileManagerMoveNodeResultResource struct {
+	Type       string                              `json:"type" example:"file_manager_move_result"`
+	ID         string                              `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes FileManagerMoveNodeResultAttributes `json:"attributes"`
+}
+
+type FileManagerActionBulkError struct {
+	Status    int    `json:"status" example:"422"`
+	Code      string `json:"code,omitempty" example:"FILE_MANAGER_VALIDATION_FAILED"`
+	ErrorCode string `json:"error_code,omitempty" example:"4222111"`
+	Title     string `json:"title" example:"Validation error"`
+	Detail    string `json:"detail" example:"duplicate name in target folder"`
+}
+
+type FileManagerMoveNodeBulkItem struct {
+	Index    int                                `json:"index" example:"0"`
+	Success  bool                               `json:"success" example:"true"`
+	Resource *FileManagerMoveNodeResultResource `json:"resource,omitempty"`
+	Error    *FileManagerActionBulkError        `json:"error,omitempty"`
+}
+
+type FileManagerMoveNodeBulkResponse struct {
+	Data []FileManagerMoveNodeBulkItem `json:"data"`
+	Meta struct {
+		Total          int  `json:"total" example:"3"`
+		Success        int  `json:"success" example:"2"`
+		Failed         int  `json:"failed" example:"1"`
+		PartialSuccess bool `json:"partial_success" example:"true"`
+	} `json:"meta"`
+}
+
+type FileManagerPurgeNodeResultAttributes struct {
+	NodeType string `json:"node_type" example:"folder"`
+	Status   string `json:"status" example:"purged"`
+}
+
+type FileManagerPurgeNodeResultResource struct {
+	Type       string                               `json:"type" example:"file_manager_purge_result"`
+	ID         string                               `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes FileManagerPurgeNodeResultAttributes `json:"attributes"`
+}
+
+type FileManagerPurgeNodeBulkItem struct {
+	Index    int                                 `json:"index" example:"0"`
+	Success  bool                                `json:"success" example:"true"`
+	Resource *FileManagerPurgeNodeResultResource `json:"resource,omitempty"`
+	Error    *FileManagerActionBulkError         `json:"error,omitempty"`
+}
+
+type FileManagerPurgeNodeBulkResponse struct {
+	Data []FileManagerPurgeNodeBulkItem `json:"data"`
+	Meta struct {
+		Total          int  `json:"total" example:"3"`
+		Success        int  `json:"success" example:"2"`
+		Failed         int  `json:"failed" example:"1"`
+		PartialSuccess bool `json:"partial_success" example:"true"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/file_manager_attachment_response.go b/internal/transport/http/dto/response/file_manager_attachment_response.go
new file mode 100644
index 0000000..8ae7738
--- /dev/null
+++ b/internal/transport/http/dto/response/file_manager_attachment_response.go
@@ -0,0 +1,22 @@
+package response
+
+import shareddto "wucher/internal/transport/http/dto/shared"
+
+type FileManagerAttachmentResource struct {
+	Type       string                                    `json:"type" example:"file_manager_attachment"`
+	ID         string                                    `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes shareddto.FileManagerAttachmentAttributes `json:"attributes"`
+}
+
+type FileManagerAttachmentResponse struct {
+	Data FileManagerAttachmentResource `json:"data"`
+}
+
+type FileManagerAttachmentListResponse struct {
+	Data []FileManagerAttachmentResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/file_manager_event_sse_dto.go b/internal/transport/http/dto/response/file_manager_event_sse_dto.go
new file mode 100644
index 0000000..0befa26
--- /dev/null
+++ b/internal/transport/http/dto/response/file_manager_event_sse_dto.go
@@ -0,0 +1,10 @@
+package response
+
+type FileManagerFileUpdatedSSEPayload struct {
+	FileID    string  `json:"file_id"`
+	Status    string  `json:"status"`
+	FolderID  *string `json:"folder_id"`
+	Name      string  `json:"name"`
+	MimeType  string  `json:"mime_type"`
+	UpdatedAt string  `json:"updated_at"`
+}
diff --git a/internal/transport/http/dto/response/file_manager_file_response.go b/internal/transport/http/dto/response/file_manager_file_response.go
new file mode 100644
index 0000000..daf396d
--- /dev/null
+++ b/internal/transport/http/dto/response/file_manager_file_response.go
@@ -0,0 +1,145 @@
+package response
+
+import shareddto "wucher/internal/transport/http/dto/shared"
+
+type FileManagerFileResource struct {
+	Type       string                              `json:"type" example:"file_manager_file"`
+	ID         string                              `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes shareddto.FileManagerFileAttributes `json:"attributes"`
+}
+
+type FileManagerFileListResource struct {
+	Type       string                                  `json:"type" example:"file_manager_file"`
+	ID         string                                  `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes shareddto.FileManagerFileListAttributes `json:"attributes"`
+}
+
+type FileManagerFileResponse struct {
+	Data struct {
+		Type       string                              `json:"type" example:"file_manager_file"`
+		ID         string                              `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+		Attributes shareddto.FileManagerFileAttributes `json:"attributes"`
+	} `json:"data"`
+}
+
+type FileManagerFileDetailResource struct {
+	Type       string                                    `json:"type" example:"file_manager_file"`
+	ID         string                                    `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes shareddto.FileManagerFileDetailAttributes `json:"attributes"`
+}
+
+type FileManagerFileDetailResponse struct {
+	Data FileManagerFileDetailResource `json:"data"`
+}
+
+type FileManagerFileListResponse struct {
+	Data []FileManagerFileListResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type FileManagerFileDownloadURLResponse struct {
+	Data struct {
+		Type       string                                      `json:"type" example:"file_manager_file_download"`
+		ID         string                                      `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+		Attributes shareddto.FileManagerFileDownloadAttributes `json:"attributes"`
+	} `json:"data"`
+}
+
+type FileManagerFileUploadIntentResponse struct {
+	Data struct {
+		Type       string                                          `json:"type" example:"file_manager_file_upload_intent"`
+		ID         string                                          `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+		Attributes shareddto.FileManagerFileUploadIntentAttributes `json:"attributes"`
+	} `json:"data"`
+}
+
+type FileManagerFileUploadIntentResource struct {
+	Type       string                                          `json:"type" example:"file_manager_file_upload_intent"`
+	ID         string                                          `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes shareddto.FileManagerFileUploadIntentAttributes `json:"attributes"`
+}
+
+type FileManagerFileWOPISessionData struct {
+	FileID          string `json:"file_id" example:"019f0386-0a00-7a4a-a2d8-30afc0e0c3ad"`
+	CollaboraAction string `json:"collabora_action" example:"https://collabora.example.com/browser/123?WOPISrc=..."`
+	AccessToken     string `json:"access_token" example:"eyJhbGciOiJIUzI1NiIs..."`
+	// AccessTokenTTL is the access token's absolute expiry time, in epoch
+	// milliseconds (equal to the JWT exp claim), as required by WOPI/Collabora.
+	AccessTokenTTL  int64  `json:"access_token_ttl" example:"1782971996000"`
+}
+
+type FileManagerFileWOPISessionResponse struct {
+	Data FileManagerFileWOPISessionData `json:"data"`
+}
+
+type FileManagerFileBulkError struct {
+	Status    int    `json:"status" example:"422"`
+	Code      string `json:"code,omitempty" example:"FILE_MANAGER_VALIDATION_FAILED"`
+	ErrorCode string `json:"error_code,omitempty" example:"4222111"`
+	Title     string `json:"title" example:"Validation error"`
+	Detail    string `json:"detail" example:"duplicate name in target folder"`
+}
+
+type FileManagerFileBulkItem struct {
+	Index    int                       `json:"index" example:"0"`
+	Success  bool                      `json:"success" example:"true"`
+	Message  string                    `json:"message,omitempty" example:"created"`
+	Resource *FileManagerFileResource  `json:"resource,omitempty"`
+	Error    *FileManagerFileBulkError `json:"error,omitempty"`
+}
+
+type FileManagerFileBulkResponse struct {
+	Data []FileManagerFileBulkItem `json:"data"`
+	Meta struct {
+		Total          int  `json:"total" example:"3"`
+		Success        int  `json:"success" example:"2"`
+		Failed         int  `json:"failed" example:"1"`
+		PartialSuccess bool `json:"partial_success" example:"true"`
+	} `json:"meta"`
+}
+
+type FileManagerFileUploadIntentBulkItem struct {
+	Index    int                                  `json:"index" example:"0"`
+	Success  bool                                 `json:"success" example:"true"`
+	Resource *FileManagerFileUploadIntentResource `json:"resource,omitempty"`
+	Error    *FileManagerFileBulkError            `json:"error,omitempty"`
+}
+
+type FileManagerFileUploadIntentBulkResponse struct {
+	Data []FileManagerFileUploadIntentBulkItem `json:"data"`
+	Meta struct {
+		Total          int  `json:"total" example:"3"`
+		Success        int  `json:"success" example:"2"`
+		Failed         int  `json:"failed" example:"1"`
+		PartialSuccess bool `json:"partial_success" example:"true"`
+	} `json:"meta"`
+}
+
+type FileManagerFileCancelUploadResource struct {
+	Type       string `json:"type" example:"file_manager_file_cancel_upload_result"`
+	ID         string `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes struct {
+		Status string `json:"status" example:"canceled"`
+	} `json:"attributes"`
+}
+
+type FileManagerFileCancelUploadBulkItem struct {
+	Index    int                                  `json:"index" example:"0"`
+	Success  bool                                 `json:"success" example:"true"`
+	Resource *FileManagerFileCancelUploadResource `json:"resource,omitempty"`
+	Error    *FileManagerFileBulkError            `json:"error,omitempty"`
+}
+
+type FileManagerFileCancelUploadBulkResponse struct {
+	Data []FileManagerFileCancelUploadBulkItem `json:"data"`
+	Meta struct {
+		Total          int  `json:"total" example:"3"`
+		Success        int  `json:"success" example:"2"`
+		Failed         int  `json:"failed" example:"1"`
+		PartialSuccess bool `json:"partial_success" example:"true"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/file_manager_folder_response.go b/internal/transport/http/dto/response/file_manager_folder_response.go
new file mode 100644
index 0000000..39fb172
--- /dev/null
+++ b/internal/transport/http/dto/response/file_manager_folder_response.go
@@ -0,0 +1,99 @@
+package response
+
+import shareddto "wucher/internal/transport/http/dto/shared"
+
+type FileManagerFolderResource struct {
+	Type       string                                `json:"type" example:"file_manager_folder"`
+	ID         string                                `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes shareddto.FileManagerFolderAttributes `json:"attributes"`
+}
+
+type FileManagerFolderResponse struct {
+	Data FileManagerFolderResource `json:"data"`
+}
+
+type FileManagerFolderDetailResource struct {
+	Type       string                                      `json:"type" example:"file_manager_folder"`
+	ID         string                                      `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes shareddto.FileManagerFolderDetailAttributes `json:"attributes"`
+}
+
+type FileManagerFolderDetailResponse struct {
+	Data FileManagerFolderDetailResource `json:"data"`
+}
+
+type FileManagerFolderListResponse struct {
+	Data []FileManagerFolderResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type FileManagerNodeAttributes struct {
+	NodeType    string  `json:"node_type" example:"folder"`
+	ParentID    *string `json:"parent_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name        string  `json:"name" example:"operations"`
+	Extension   string  `json:"extension,omitempty" example:"pdf"`
+	SizeBytes   int64   `json:"size_bytes,omitempty" example:"1024"`
+	MimeType    string  `json:"mime_type,omitempty" example:"application/pdf"`
+	DownloadURL string  `json:"download_url,omitempty" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."`
+	Status      string  `json:"status" example:"ready"`
+	PathCache   string  `json:"path_cache,omitempty" example:"/root/operations"`
+	CreatedAt   string  `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt   string  `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+}
+
+type FileManagerNodeResource struct {
+	Type       string                    `json:"type" example:"file_manager_node"`
+	ID         string                    `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes FileManagerNodeAttributes `json:"attributes"`
+}
+
+type FileManagerNodeListResponse struct {
+	Data []FileManagerNodeResource `json:"data"`
+	Meta struct {
+		ParentUUID *string                     `json:"parent_uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+		Breadcrumb []FileManagerBreadcrumbItem `json:"breadcrumb,omitempty"`
+		IsRoot     bool                        `json:"is_root" example:"true"`
+		Folders    int                         `json:"folders" example:"4"`
+		Files      int                         `json:"files" example:"8"`
+		Total      int                         `json:"total" example:"12"`
+	} `json:"meta"`
+}
+
+type FileManagerBreadcrumbItem struct {
+	ID   string `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name string `json:"name" example:"operations"`
+}
+
+type FileManagerTrashNodeAttributes struct {
+	NodeType    string `json:"node_type" example:"folder"`
+	Name        string `json:"name" example:"Documents"`
+	Extension   string `json:"extension,omitempty" example:"pdf"`
+	SizeBytes   int64  `json:"size_bytes,omitempty" example:"123456"`
+	MimeType    string `json:"mime_type,omitempty" example:"application/pdf"`
+	DownloadURL string `json:"download_url,omitempty" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."`
+	PathCache   string `json:"path_cache,omitempty" example:"/Documents"`
+	TrashedAt   string `json:"trashed_at" example:"2026-04-01T10:00:00Z"`
+	CreatedAt   string `json:"created_at,omitempty" example:"2026-03-31T08:52:03Z"`
+	UpdatedAt   string `json:"updated_at,omitempty" example:"2026-03-31T08:52:03Z"`
+}
+
+type FileManagerTrashNodeResource struct {
+	Type       string                         `json:"type" example:"file_manager_trash_node"`
+	ID         string                         `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes FileManagerTrashNodeAttributes `json:"attributes"`
+}
+
+type FileManagerTrashListResponse struct {
+	Data []FileManagerTrashNodeResource `json:"data"`
+	Meta struct {
+		PageNumber int `json:"page_number" example:"1"`
+		PageSize   int `json:"page_size" example:"20"`
+		Total      int `json:"total" example:"120"`
+		Folders    int `json:"folders" example:"50"`
+		Files      int `json:"files" example:"70"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/fleet_history_response.go b/internal/transport/http/dto/response/fleet_history_response.go
new file mode 100644
index 0000000..952d84c
--- /dev/null
+++ b/internal/transport/http/dto/response/fleet_history_response.go
@@ -0,0 +1,22 @@
+package response
+
+// FleetHistoryEntry is one event in a helicopter's unified timeline (complaint /
+// MEL / NSR / action / MCF / EASA / AOG events plus maintenance servicing).
+type FleetHistoryEntry struct {
+	At         string `json:"at" example:"2026-06-17T10:15:00Z"`
+	EntityType string `json:"entity_type" example:"easa_release"`
+	EntityID   string `json:"entity_id,omitempty" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Action     string `json:"action" example:"easa_signed"`
+	Message    string `json:"message" example:"Release to Service (EASA signed)"`
+	Actor      string `json:"actor,omitempty" example:"019e91e6-2908-7f37-93e6-015ed1b7587d"`
+	ActorName  string `json:"actor_name,omitempty" example:"John Doe"`
+}
+
+type FleetHistoryListResponse struct {
+	Data []FleetHistoryEntry `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/fleet_status_response.go b/internal/transport/http/dto/response/fleet_status_response.go
new file mode 100644
index 0000000..9c315f2
--- /dev/null
+++ b/internal/transport/http/dto/response/fleet_status_response.go
@@ -0,0 +1,107 @@
+package response
+
+import shareddto "wucher/internal/transport/http/dto/shared"
+
+type FleetStatusAttributes struct {
+	Helicopter           *shareddto.FleetStatusHelicopter          `json:"helicopter,omitempty"`
+	Status               string                                    `json:"status" example:"active" enums:"active,serviced"`
+	ServicedAt           string                                    `json:"serviced_at,omitempty" example:"2026-05-29T07:43:06Z"`
+	MaintenanceSchedules []shareddto.MaintenanceScheduleAttributes `json:"maintenance_schedules"`
+	Files                []FleetStatusFile                         `json:"files"`
+	Summary              shareddto.FleetStatusSummary              `json:"summary"`
+	MCF                  *shareddto.FleetStatusMCF                 `json:"mcf,omitempty"`
+	Complaints           []shareddto.FleetStatusComplaint          `json:"complaints,omitempty"`
+	EASARelease          *shareddto.FleetStatusEASARelease         `json:"easa_release,omitempty"`
+	CreatedAt            string                                    `json:"created_at,omitempty" example:"2026-05-29T07:43:06Z"`
+	CreatedBy            string                                    `json:"created_by,omitempty" example:"John Doe"`
+	UpdatedAt            string                                    `json:"updated_at,omitempty" example:"2026-05-29T07:43:06Z"`
+	UpdatedBy            string                                    `json:"updated_by,omitempty" example:"John Doe"`
+}
+
+type FleetStatusFile struct {
+	ID                   string `json:"id,omitempty" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	FileAttachmentID     string `json:"file_attachment_id" example:"019d7000-aaaa-7bbb-8ccc-111111111111"`
+	Category             string `json:"category" example:"wb"`
+	IsMandatory          bool   `json:"is_mandatory" example:"true"`
+	Name                 string `json:"name,omitempty" example:"weight_balance.pdf"`
+	DownloadURL          string `json:"download_url,omitempty" example:"https://storage.example.com/fleet/wb.pdf?X-Amz-Signature=abc123"`
+	ThumbnailDownloadURL string `json:"thumbnail_download_url,omitempty" example:"https://storage.example.com/fleet/wb.thumb.jpg?X-Amz-Signature=abc123"`
+	SizeBytes            *int64 `json:"size_bytes,omitempty" example:"1024000"`
+}
+
+type FleetStatusResource struct {
+	Type       string                `json:"type" example:"fleet_status"`
+	ID         string                `json:"id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Attributes FleetStatusAttributes `json:"attributes"`
+}
+
+type FleetStatusResponse struct {
+	Data FleetStatusResource `json:"data"`
+}
+
+type FleetStatusListResponse struct {
+	Data []FleetStatusResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"100"`
+	} `json:"meta"`
+}
+
+type FleetStatusDataTableResponse struct {
+	Data []FleetStatusResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"100"`
+		RecordsFiltered int64 `json:"records_filtered" example:"20"`
+	} `json:"meta"`
+}
+
+// FleetStatusDeleteResponse is the ack returned when a fleet status is deleted.
+type FleetStatusDeleteResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"fleet_status_delete"`
+		Attributes struct {
+			Deleted bool `json:"deleted" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+// FleetStatusMarkServicedResponse is the ack returned when a fleet status is marked serviced.
+type FleetStatusMarkServicedResponse struct {
+	Data struct {
+		Type       string `json:"type" example:"fleet_status_mark_serviced"`
+		Attributes struct {
+			Serviced bool `json:"serviced" example:"true"`
+		} `json:"attributes"`
+	} `json:"data"`
+}
+
+type FleetStatusServiceLogAttributes struct {
+	FleetStatusID     string                           `json:"fleet_status_id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	HelicopterID      string                           `json:"helicopter_id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Helicopter        *shareddto.FleetStatusHelicopter `json:"helicopter,omitempty"`
+	FleetStatusStatus string                           `json:"fleet_status_status,omitempty" example:"serviced"`
+	InspectionType    string                           `json:"inspection_type" example:"A/F"`
+	Type              string                           `json:"type" example:"100H"`
+	Due               string                           `json:"due" example:"1200 FH"`
+	Ext               string                           `json:"ext" example:"1300 FH"`
+	ServicedAt        string                           `json:"serviced_at" example:"2026-05-29T07:43:06Z"`
+	CreatedAt         string                           `json:"created_at" example:"2026-05-29T07:43:06Z"`
+	CreatedBy         string                           `json:"created_by" example:"John Doe"`
+}
+
+type FleetStatusServiceLogResource struct {
+	Type       string                          `json:"type" example:"fleet_status_service_log"`
+	ID         string                          `json:"id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Attributes FleetStatusServiceLogAttributes `json:"attributes"`
+}
+
+type FleetStatusServiceLogListResponse struct {
+	Data []FleetStatusServiceLogResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"100"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/flight_data_response.go b/internal/transport/http/dto/response/flight_data_response.go
new file mode 100644
index 0000000..602868f
--- /dev/null
+++ b/internal/transport/http/dto/response/flight_data_response.go
@@ -0,0 +1,139 @@
+package response
+
+type FlightDataAttributes struct {
+	Status                string                             `json:"status" example:"in_progress"`
+	Mission               *FlightDataMissionRef              `json:"mission,omitempty"`
+	RosterDetails         *TakeoverDutyRosterDetailsResponse `json:"roster_details,omitempty"`
+	HESLO                 *FlightDataSPOHESLODetails         `json:"heslo,omitempty" extensions:"x-note=Only returned for SPO missions"`
+	Logging               *FlightDataSPOLoggingDetails       `json:"logging,omitempty" extensions:"x-note=Only returned for SPO missions"`
+	HEC                   *FlightDataSPOHECDetails           `json:"hec,omitempty" extensions:"x-note=Only returned for SPO missions"`
+	CoPilot               *FlightDataCoPilotRef              `json:"co_pilot,omitempty"`
+	From                  *FlightDataLocationRef             `json:"from,omitempty"`
+	To                    *FlightDataLocationRef             `json:"to,omitempty"`
+	FlightTakeOff         string                             `json:"flight_take_off,omitempty" example:"2026-04-20T08:00:00Z"`
+	FlightLanding         string                             `json:"flight_landing,omitempty" example:"2026-04-20T09:15:00Z"`
+	FlightDuration        int64                              `json:"flight_duration_seconds" example:"4500"`
+	FlightRED             int64                              `json:"flight_red_seconds" example:"300"`
+	MaxN1                 float64                            `json:"max_n1" example:"97.5"`
+	MaxN2                 float64                            `json:"max_n2" example:"98.1"`
+	PaxCount              int                                `json:"pax_count" example:"4"`
+	LandingCount          int                                `json:"landing_count" example:"1"`
+	RotorBrakeCycle       int                                `json:"rotor_brake_cycle" example:"1"`
+	HookReleases          int                                `json:"hook_releases" example:"0"`
+	TicketNo              string                             `json:"ticket_no,omitempty" example:"TKT-001"`
+	Engine                string                             `json:"engine,omitempty" example:"PW207D1"`
+	DeliveryNoteNumber    string                             `json:"delivery_note_number,omitempty" example:"DN-1001"`
+	CustomerName          string                             `json:"customer_name,omitempty" example:"Air Service"`
+	FlightPlanDistance    float64                            `json:"flight_plan_distance" example:"120.5"`
+	FlightPlanTimeSeconds int64                              `json:"flight_plan_time_seconds" example:"4200"`
+	FlightPlanTrueCourse  float64                            `json:"flight_plan_true_course" example:"182.3"`
+	FuelBeforeFlight      float64                            `json:"fuel_before_flight" example:"420"`
+	FuelUpload            float64                            `json:"fuel_upload" example:"100"`
+	FuelAfterFlight       float64                            `json:"fuel_after_flight" example:"280"`
+	FuelPlanning          float64                            `json:"fuel_planning" example:"390"`
+	FlightPositioning     bool                               `json:"flight_positioning" example:"false"`
+	OtherInformation      string                             `json:"other_information,omitempty"`
+	CreatedAt             string                             `json:"created_at,omitempty" example:"2026-04-20T08:00:00Z"`
+	CreatedBy             string                             `json:"created_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	UpdatedAt             string                             `json:"updated_at,omitempty" example:"2026-04-20T08:00:00Z"`
+	UpdatedBy             string                             `json:"updated_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+}
+
+type FlightDataSPOHESLODetails struct {
+	Flights []FlightDataSPOHESLOFlight `json:"flights"`
+}
+
+type FlightDataSPOHESLOFlight struct {
+	ID  string `json:"id"`
+	ROT int    `json:"rot"`
+	// Facility category: heslo-rope-label.
+	HESLORopeLabelID   string                    `json:"heslo_rope_label_id,omitempty"`
+	HESLORopeLabelName string                    `json:"heslo_rope_label_name,omitempty"`
+	Slings             []FlightDataSPOHESLOSling `json:"slings"`
+}
+
+type FlightDataSPOHESLOSling struct {
+	ID string `json:"id"`
+	// Facility category: heslo-rope-length.
+	SlingID   string `json:"sling_id,omitempty"`
+	SlingName string `json:"sling_name,omitempty"`
+}
+
+type FlightDataSPOLoggingDetails struct {
+	Slings []FlightDataSPOLoggingSling `json:"slings"`
+}
+
+type FlightDataSPOLoggingSling struct {
+	ID string `json:"id"`
+	// Facility category: heslo-hook.
+	SlingID   string `json:"sling_id,omitempty"`
+	SlingName string `json:"sling_name,omitempty"`
+}
+
+type FlightDataSPOHECDetails struct {
+	Flights []FlightDataSPOHECFlight `json:"flights"`
+	Slings  []FlightDataSPOHECSling  `json:"slings"`
+	Loads   []FlightDataSPOHECLoad   `json:"loads"`
+}
+
+type FlightDataSPOHECFlight struct {
+	ID       string `json:"id"`
+	ROT      int    `json:"rot"`
+	HECCycle int    `json:"hec_cycle"`
+	// Facility category: hec-rope-label.
+	EquipmentID   string `json:"equipment_id,omitempty"`
+	EquipmentName string `json:"equipment_name,omitempty"`
+}
+
+type FlightDataSPOHECSling struct {
+	ID string `json:"id"`
+	// Facility category: hec-rope-length.
+	SlingID   string `json:"sling_id,omitempty"`
+	SlingName string `json:"sling_name,omitempty"`
+}
+
+type FlightDataSPOHECLoad struct {
+	ID string `json:"id"`
+	// Weight band for the HEC load, e.g. "bis 199 kg", "200-600 kg", "600-800 kg", "800-1000 kg".
+	LoadCategory string `json:"load_category,omitempty" example:"200-600 kg"`
+	Quantity     int    `json:"quantity" example:"3"`
+}
+
+type FlightDataMissionRef struct {
+	ID   string `json:"id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	Type string `json:"type,omitempty" example:"HEMS"`
+}
+
+type FlightDataCoPilotRef struct {
+	ID        string `json:"id,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	FirstName string `json:"first_name,omitempty" example:"John"`
+	LastName  string `json:"last_name,omitempty" example:"Doe"`
+	Email     string `json:"email,omitempty" example:"john.doe@example.com"`
+}
+
+type FlightDataLocationRef struct {
+	Type  string `json:"type,omitempty" example:"icao"`
+	ID    string `json:"id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	Code  string `json:"code,omitempty" example:"WIII"`
+	Name  string `json:"name,omitempty" example:"General Hospital"`
+	Label string `json:"label,omitempty" example:"WIII"`
+}
+
+type FlightDataResource struct {
+	Type       string               `json:"type" example:"flight_data"`
+	ID         string               `json:"id" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	Attributes FlightDataAttributes `json:"attributes"`
+}
+
+type FlightDataResponse struct {
+	Data FlightDataResource `json:"data"`
+}
+
+type FlightDataListResponse struct {
+	Data []FlightDataResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/flight_inspection_file_checklist_response.go b/internal/transport/http/dto/response/flight_inspection_file_checklist_response.go
new file mode 100644
index 0000000..49d7cfa
--- /dev/null
+++ b/internal/transport/http/dto/response/flight_inspection_file_checklist_response.go
@@ -0,0 +1,22 @@
+package response
+
+import shareddto "wucher/internal/transport/http/dto/shared"
+
+type FlightInspectionFileChecklistResource struct {
+	Type       string                                            `json:"type" example:"flight_inspection_file_checklist"`
+	ID         string                                            `json:"id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Attributes shareddto.FlightInspectionFileChecklistAttributes `json:"attributes"`
+}
+
+type FlightInspectionFileChecklistResponse struct {
+	Data FlightInspectionFileChecklistResource `json:"data"`
+}
+
+type FlightInspectionFileChecklistListResponse struct {
+	Data []FlightInspectionFileChecklistResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/flight_response.go b/internal/transport/http/dto/response/flight_response.go
new file mode 100644
index 0000000..c383a90
--- /dev/null
+++ b/internal/transport/http/dto/response/flight_response.go
@@ -0,0 +1,91 @@
+package response
+
+type FlightAttributes struct {
+	Status     string                 `json:"status" example:"draft"`
+	MissionID  string                 `json:"mission_id,omitempty" example:"019e9640-f7af-7940-80e8-1e9a83013afb"`
+	Code       string                 `json:"code" example:"M-062226-001"`
+	Date       string                 `json:"date" example:"2026-04-14"`
+	TotalDraft int                    `json:"total_draft" example:"6"`
+	Takeover   *FlightTakeoverSummary `json:"takeover,omitempty"`
+	Steps      []FlightStepItem       `json:"steps"`
+	Draft      []FlightDraftGroup     `json:"draft,omitempty"`
+	CreatedAt  string                 `json:"created_at,omitempty" example:"2026-04-14T08:00:00Z"`
+	CreatedBy  *UserRef               `json:"created_by,omitempty"`
+	UpdatedAt  string                 `json:"updated_at,omitempty" example:"2026-04-14T08:00:00Z"`
+	UpdatedBy  *UserRef               `json:"updated_by,omitempty"`
+	DeletedAt  string                 `json:"deleted_at,omitempty" example:"2026-04-14T08:00:00Z"`
+	DeletedBy  *UserRef               `json:"deleted_by,omitempty"`
+}
+
+type FlightStepItem struct {
+	Phase       string                     `json:"phase" example:"duty_roster"`
+	Position    string                     `json:"position,omitempty" example:"takeover"`
+	Step        int                        `json:"step,omitempty" example:"1"`
+	Complete    bool                       `json:"complete" example:"true"`
+	ID          string                     `json:"id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	Status      string                     `json:"status" example:"completed"`
+	MissionType []FlightMissionTypeSummary `json:"mission_type,omitempty"`
+	CompletedAt string                     `json:"completed_at" example:"2026-04-14T08:00:00Z"`
+	CompletedBy string                     `json:"completed_by" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+}
+
+type FlightHelicopterSummary struct {
+	AOG         bool   `json:"aog" example:"false"`
+	Designation string `json:"designation" example:"AIRBUS H145"`
+	ID          string `json:"id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Identifier  string `json:"identifier" example:"D-HYAR"`
+	IsActive    bool   `json:"is_active" example:"true"`
+	Type        string `json:"type" example:"H145"`
+}
+
+type FlightTakeoverSummary struct {
+	ID              string                             `json:"id,omitempty" example:"019e8713-aa19-7fb7-a510-a0332dc69697"`
+	Helicopter      *FlightHelicopterSummary           `json:"helicopter,omitempty"`
+	DailyInspection *FlightDailyInspectionSummary      `json:"daily_inspection,omitempty"`
+	RosterDetail    *TakeoverDutyRosterDetailsResponse `json:"roster_detail,omitempty"`
+}
+
+type FlightDailyInspectionSummary struct {
+	ID        string `json:"id" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	Name      string `json:"name" example:"Ganahl Stefan"`
+	ShortName string `json:"short_name" example:"GAN"`
+	Date      string `json:"date" example:"17.04.2026"`
+	UTCTime   string `json:"utc_time" example:"10:57"`
+}
+
+type FlightDraftItem struct {
+	ID           string `json:"id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	Type         string `json:"type" example:"HEMS"`
+	Status       string `json:"status" example:"draft"`
+	FlightDataID string `json:"flight_data_id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a55"`
+}
+
+type FlightDraftGroup struct {
+	Type  string            `json:"type" example:"HEMS"`
+	Items []FlightDraftItem `json:"items"`
+}
+
+type FlightMissionTypeSummary struct {
+	Type      string `json:"type" example:"HEMS"`
+	Draft     int    `json:"draft" example:"5"`
+	Completed int    `json:"completed" example:"0"`
+}
+
+type FlightResource struct {
+	Type       string           `json:"type" example:"flight"`
+	ID         string           `json:"id" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	Attributes FlightAttributes `json:"attributes"`
+}
+
+type FlightResponse struct {
+	Data FlightResource `json:"data"`
+}
+
+type FlightListResponse struct {
+	Data []FlightResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/helicopter_file_response.go b/internal/transport/http/dto/response/helicopter_file_response.go
new file mode 100644
index 0000000..04ae251
--- /dev/null
+++ b/internal/transport/http/dto/response/helicopter_file_response.go
@@ -0,0 +1,170 @@
+package response
+
+import (
+	shareddto "wucher/internal/transport/http/dto/shared"
+	"wucher/internal/transport/http/jsonapi"
+)
+
+type HelicopterFileResource struct {
+	Type       string                             `json:"type" example:"helicopter_file"`
+	ID         string                             `json:"id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Attributes shareddto.HelicopterFileAttributes `json:"attributes"`
+}
+
+type HelicopterFileResponse struct {
+	Data HelicopterFileResource `json:"data"`
+}
+
+type HelicopterFileListResponse struct {
+	Data []HelicopterFileResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
+
+type HelicopterFileCollectionHelicopter struct {
+	ID   string `json:"id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Name string `json:"name" example:"AIRBUS H145"`
+}
+
+type HelicopterFileCollectionAttachment struct {
+	ID          string `json:"id" example:"019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e"`
+	FileName    string `json:"file_name" example:"Before Flight Checklist.pdf"`
+	DownloadURL string `json:"download_url" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."`
+}
+
+type HelicopterFileCollectionItem struct {
+	HelicopterFileID  string                             `json:"helicopter_file_id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Section           string                             `json:"section" example:"bfi"`
+	Position          int                                `json:"position" example:"1"`
+	IsMandatory       bool                               `json:"is_mandatory" example:"true"`
+	IsTemplate        bool                               `json:"is_template" example:"true"`
+	AttachmentPending bool                               `json:"attachment_pending" example:"true"`
+	Attachment        HelicopterFileCollectionAttachment `json:"attachment"`
+	CreatedAt         string                             `json:"created_at" example:"2026-04-14T08:00:00Z"`
+	CreatedBy         string                             `json:"created_by" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	UpdatedAt         string                             `json:"updated_at" example:"2026-04-14T08:00:00Z"`
+	UpdatedBy         string                             `json:"updated_by" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+}
+
+type HelicopterFileCollectionSections struct {
+	Before  []HelicopterFileCollectionItem `json:"before"`
+	Prepare []HelicopterFileCollectionItem `json:"prepare"`
+	After   []HelicopterFileCollectionItem `json:"after"`
+}
+
+type HelicopterFileCollectionAttributes struct {
+	Helicopter HelicopterFileCollectionHelicopter `json:"helicopter"`
+	Files      HelicopterFileCollectionSections   `json:"files"`
+}
+
+type HelicopterFileCollectionResponse struct {
+	Type       string                             `json:"type" example:"helicopter_file_collection"`
+	Attributes HelicopterFileCollectionAttributes `json:"attributes"`
+}
+
+type HelicopterFileCollectionListResponse struct {
+	Data []HelicopterFileCollectionResponse `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
+
+type HelicopterFileDeleteAttributes struct {
+	Deleted bool `json:"deleted" example:"true"`
+}
+
+type HelicopterFileDeleteResource struct {
+	Type       string                         `json:"type" example:"helicopter_file_delete"`
+	Attributes HelicopterFileDeleteAttributes `json:"attributes"`
+}
+
+type HelicopterFileDeleteResponse struct {
+	Data HelicopterFileDeleteResource `json:"data"`
+}
+
+type HelicopterFileUploadIntentResource struct {
+	Type       string                                          `json:"type" example:"helicopter_file_upload_intent"`
+	ID         string                                          `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes shareddto.FileManagerFileUploadIntentAttributes `json:"attributes"`
+}
+
+type HelicopterFileUploadIntentResponse struct {
+	Data HelicopterFileUploadIntentResource `json:"data"`
+}
+
+type HelicopterFileBulkError struct {
+	Status    int    `json:"status" example:"422"`
+	Code      string `json:"code,omitempty" example:"HELICOPTER_FILE_INVALID_PAYLOAD"`
+	ErrorCode string `json:"error_code,omitempty" example:"4220318"`
+	Title     string `json:"title" example:"Validation error"`
+	Detail    string `json:"detail" example:"helicopter_id is invalid UUID"`
+}
+
+type HelicopterFileUploadIntentBulkItem struct {
+	Index    int                                 `json:"index" example:"0"`
+	Success  bool                                `json:"success" example:"true"`
+	Resource *HelicopterFileUploadIntentResource `json:"resource,omitempty"`
+	Error    *HelicopterFileBulkError            `json:"error,omitempty"`
+}
+
+type HelicopterFileUploadIntentBulkResponse struct {
+	Data []HelicopterFileUploadIntentBulkItem `json:"data"`
+	Meta struct {
+		Total          int  `json:"total" example:"3"`
+		Success        int  `json:"success" example:"2"`
+		Failed         int  `json:"failed" example:"1"`
+		PartialSuccess bool `json:"partial_success" example:"true"`
+	} `json:"meta"`
+}
+
+type HelicopterFileCreateBulkItem struct {
+	Index    int                      `json:"index" example:"0"`
+	Success  bool                     `json:"success" example:"true"`
+	Resource *jsonapi.Resource        `json:"resource,omitempty"`
+	Error    *HelicopterFileBulkError `json:"error,omitempty"`
+}
+
+type HelicopterFileCreateBulkResponse struct {
+	Data []HelicopterFileCreateBulkItem `json:"data"`
+	Meta struct {
+		Total          int  `json:"total" example:"3"`
+		Success        int  `json:"success" example:"2"`
+		Failed         int  `json:"failed" example:"1"`
+		PartialSuccess bool `json:"partial_success" example:"true"`
+	} `json:"meta"`
+}
+
+type HelicopterFileUpdateBulkItem struct {
+	Index    int                      `json:"index" example:"0"`
+	Success  bool                     `json:"success" example:"true"`
+	Resource *jsonapi.Resource        `json:"resource,omitempty"`
+	Error    *HelicopterFileBulkError `json:"error,omitempty"`
+}
+
+type HelicopterFileUpdateBulkResponse struct {
+	Data []HelicopterFileUpdateBulkItem `json:"data"`
+	Meta struct {
+		Total          int  `json:"total" example:"3"`
+		Success        int  `json:"success" example:"2"`
+		Failed         int  `json:"failed" example:"1"`
+		PartialSuccess bool `json:"partial_success" example:"true"`
+	} `json:"meta"`
+}
+
+type HelicopterFileCreatedSSEPayload struct {
+	HelicopterID      string `json:"helicopter_id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	HelicopterFileID  string `json:"helicopter_file_id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	FileID            string `json:"file_id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Section           string `json:"section" example:"fpwb"`
+	Position          int    `json:"position" example:"1"`
+	IsMandatory       bool   `json:"is_mandatory" example:"true"`
+	AttachmentPending bool   `json:"attachment_pending" example:"true"`
+	Name              string `json:"name" example:"Before Flight Checklist.pdf"`
+	MimeType          string `json:"mime_type,omitempty" example:"application/pdf"`
+	UpdatedAt         string `json:"updated_at" example:"2026-07-01T06:00:00Z"`
+}
diff --git a/internal/transport/http/dto/response/helicopter_response.go b/internal/transport/http/dto/response/helicopter_response.go
new file mode 100644
index 0000000..c1202fd
--- /dev/null
+++ b/internal/transport/http/dto/response/helicopter_response.go
@@ -0,0 +1,88 @@
+package response
+
+import shareddto "wucher/internal/transport/http/dto/shared"
+
+// JSON:API Helicopter response DTOs
+
+type HelicopterAttributes struct {
+	Designation string                    `json:"designation" example:"OE-XHZ"`
+	Identifier  string                    `json:"identifier" example:"ABC-0001"`
+	Type        string                    `json:"type" example:"EC-135"`
+	SortKey     *int                      `json:"sortkey" example:"10"`
+	Engine1     string                    `json:"engine_1,omitempty" example:"TM"`
+	Engine2     string                    `json:"engine_2,omitempty" example:"TM"`
+	Consumption float64                   `json:"consumption_lt_min" example:"4.1"`
+	NR1         bool                      `json:"nr1" example:"true"`
+	NR2         bool                      `json:"nr2" example:"true"`
+	LH          bool                      `json:"lh" example:"true"`
+	RH          bool                      `json:"rh" example:"true"`
+	MGB         bool                      `json:"mgb" example:"true"`
+	IGB         bool                      `json:"igb" example:"false"`
+	TGB         bool                      `json:"tgb" example:"true"`
+	UTCOffset   int                       `json:"utc_offset" example:"-1"`
+	Foto        *shareddto.HelicopterFoto `json:"foto,omitempty"`
+	Dry         bool                      `json:"dry" example:"false"`
+	AOG         bool                      `json:"aog" example:"false"`
+	IsInUse     bool                      `json:"is_in_use" example:"false"`
+	// Status is the operational status of the helicopter (read-time derived).
+	// Values: "available", "booked", "aog", "mcf". Precedence: mcf > aog > booked > available.
+	// "booked" = active flight assignment; "aog" = air_on_ground flag OR an open complaint
+	// grounding it (non-MEL, or MEL past its grace deadline); "mcf" = a pending maintenance
+	// check flight (MCF created, not yet passed).
+	Status              string                                   `json:"status" example:"available" enums:"available,booked,aog,mcf"`
+	AOGReason           string                                   `json:"aog_reason,omitempty" example:"Main rotor gearbox fault"`
+	Note                string                                   `json:"note,omitempty" example:"Primary HEMS helicopter"`
+	IsActive            bool                                     `json:"is_active" example:"true"`
+	CreatedBy           *shareddto.HelicopterAuditUser           `json:"created_by,omitempty"`
+	CreatedAt           string                                   `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy           *shareddto.HelicopterAuditUser           `json:"updated_by,omitempty"`
+	UpdatedAt           string                                   `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	LastDailyInspection *shareddto.HelicopterLastDailyInspection `json:"last_daily_inspection"`
+	// MaintenanceSchedules mirrors the helicopter's latest fleet status. It
+	// always lists every inspection type; entries without data are empty.
+	MaintenanceSchedules []shareddto.MaintenanceScheduleAttributes `json:"maintenance_schedules"`
+}
+
+type HelicopterResource struct {
+	Type       string               `json:"type" example:"helicopter"`
+	ID         string               `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes HelicopterAttributes `json:"attributes"`
+}
+
+type HelicopterResponse struct {
+	Data HelicopterResource `json:"data"`
+}
+
+type HelicopterListResponse struct {
+	Data []HelicopterResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type HelicopterDataTableResponse struct {
+	Data []HelicopterResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type HelicopterNextReportNumberAttributes struct {
+	Identifier   string `json:"identifier" example:"ABC"`
+	Sequence     int    `json:"sequence" example:"1"`
+	ReportNumber string `json:"report_number" example:"ABC-0001"`
+}
+
+type HelicopterNextReportNumberResource struct {
+	Type       string                               `json:"type" example:"helicopter_report_number"`
+	ID         string                               `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes HelicopterNextReportNumberAttributes `json:"attributes"`
+}
+
+type HelicopterNextReportNumberResponse struct {
+	Data HelicopterNextReportNumberResource `json:"data"`
+}
diff --git a/internal/transport/http/dto/response/master_settings_microsoft_entra_response.go b/internal/transport/http/dto/response/master_settings_microsoft_entra_response.go
new file mode 100644
index 0000000..0d671ca
--- /dev/null
+++ b/internal/transport/http/dto/response/master_settings_microsoft_entra_response.go
@@ -0,0 +1,19 @@
+package response
+
+type MasterSettingsMicrosoftEntraAttributes struct {
+	TenantID           string `json:"MS_ENTRA_TENANT_ID" example:"your-tenant-id"`
+	ClientID           string `json:"MS_ENTRA_CLIENT_ID" example:"your-client-id"`
+	ClientSecretMasked string `json:"MS_ENTRA_CLIENT_SECRET" example:"********"`
+	RedirectURL        string `json:"MS_ENTRA_REDIRECT_URL" example:"https://example.com/api/v1/auth/microsoft/callback"`
+	Authority          string `json:"MS_ENTRA_AUTHORITY" example:"https://login.microsoftonline.com/"`
+	Scopes             string `json:"MS_ENTRA_SCOPES" example:"openid,profile,email"`
+}
+
+type MasterSettingsMicrosoftEntraResource struct {
+	Type       string                                 `json:"type" example:"master_settings_microsoft_entra_sso"`
+	Attributes MasterSettingsMicrosoftEntraAttributes `json:"attributes"`
+}
+
+type MasterSettingsMicrosoftEntraResponse struct {
+	Data MasterSettingsMicrosoftEntraResource `json:"data"`
+}
diff --git a/internal/transport/http/dto/response/master_settings_response.go b/internal/transport/http/dto/response/master_settings_response.go
new file mode 100644
index 0000000..9af4b43
--- /dev/null
+++ b/internal/transport/http/dto/response/master_settings_response.go
@@ -0,0 +1,49 @@
+package response
+
+type MasterSettingsAttributes struct {
+	CompanyName    string  `json:"company_name" example:"Wucher"`
+	Title          string  `json:"title,omitempty" example:"Welcome to Wucher"`
+	Subtitle       string  `json:"subtitle,omitempty" example:"Flight operations platform"`
+	LogoFileUUID   *string `json:"logo_file_uuid" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	LogoURL        *string `json:"logo_url" example:"https://cdn.example.com/logo.png"`
+	LogoThumbURL   *string `json:"logo_thumbnail_url,omitempty" example:"https://cdn.example.com/logo.thumb.png"`
+	LogoSizeBytes  *int64  `json:"logo_original_size_bytes,omitempty" example:"1024000"`
+	CoverFileUUID  *string `json:"cover_file_uuid" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CoverURL       *string `json:"cover_url" example:"https://cdn.example.com/cover.png"`
+	CoverThumbURL  *string `json:"cover_thumbnail_url,omitempty" example:"https://cdn.example.com/cover.thumb.png"`
+	CoverSizeBytes *int64  `json:"cover_original_size_bytes,omitempty" example:"2048000"`
+	CreatedAt      string  `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy      string  `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt      string  `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy      string  `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt      string  `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy      string  `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type MasterSettingsResource struct {
+	Type       string                   `json:"type" example:"master_settings"`
+	ID         string                   `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes MasterSettingsAttributes `json:"attributes"`
+}
+
+type MasterSettingsResponse struct {
+	Data MasterSettingsResource `json:"data"`
+}
+
+type MasterSettingsListResponse struct {
+	Data []MasterSettingsResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type MasterSettingsDataTableResponse struct {
+	Data []MasterSettingsResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/mcf_response.go b/internal/transport/http/dto/response/mcf_response.go
new file mode 100644
index 0000000..8f7fe30
--- /dev/null
+++ b/internal/transport/http/dto/response/mcf_response.go
@@ -0,0 +1,40 @@
+package response
+
+type MCFAttributes struct {
+	HelicopterID string  `json:"helicopter_id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	FlightID     string  `json:"flight_id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	Date         string  `json:"date" example:"2026-06-17"`
+	AFHours      string  `json:"af_hours,omitempty" example:"1245.3"`
+	LandingCount int     `json:"landing_count" example:"3"`
+	UTCTime      *string `json:"utc_time,omitempty" example:"2026-06-17T08:30:00Z"`
+	DecidedBy    string  `json:"decided_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	DecidedAt    *string `json:"decided_at,omitempty" example:"2026-06-16T03:04:05Z"`
+	Result       *string `json:"result,omitempty" example:"passed" enums:"passed,failed"`
+
+	Notes       *string `json:"notes,omitempty" example:"Vibration within limits"`
+	CompletedBy string  `json:"completed_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	CompletedAt *string `json:"completed_at,omitempty" example:"2026-06-16T03:04:05Z"`
+
+	IsComplete bool   `json:"is_complete" example:"false"`
+	IsCleared  bool   `json:"is_cleared" example:"false"`
+	IsPending  bool   `json:"is_pending" example:"true"`
+	CreatedAt  string `json:"created_at,omitempty" example:"2026-06-16T03:04:05Z"`
+	UpdatedAt  string `json:"updated_at,omitempty" example:"2026-06-16T03:04:05Z"`
+}
+
+type MCFResource struct {
+	Type       string        `json:"type" example:"mcf"`
+	ID         string        `json:"id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Attributes MCFAttributes `json:"attributes"`
+}
+
+type MCFResponse struct {
+	Data MCFResource `json:"data"`
+}
+
+type MCFListResponse struct {
+	Data []MCFResource `json:"data"`
+	Meta struct {
+		Total int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
diff --git a/internal/transport/http/dto/response/mission_response.go b/internal/transport/http/dto/response/mission_response.go
new file mode 100644
index 0000000..18e4fe2
--- /dev/null
+++ b/internal/transport/http/dto/response/mission_response.go
@@ -0,0 +1,93 @@
+package response
+
+type MissionAttributes struct {
+	Flight      *MissionFlightRef  `json:"flight,omitempty"`
+	Type        string             `json:"type" example:"HEMS"`
+	MissionCode string             `json:"mission_code" example:"HEMS-26-1"`
+	Subtypes    *MissionSubtypeRef `json:"subtypes,omitempty"`
+	Note        string             `json:"note,omitempty" example:"Mission note"`
+	StartTime   string             `json:"start_time,omitempty" example:"04:49"`
+	EndTime     string             `json:"end_time,omitempty" example:"22:05"`
+	Status      string             `json:"status" example:"completed"`
+	Forms       *MissionForms      `json:"forms,omitempty"`
+	Files       []MissionFileItem  `json:"files,omitempty"`
+	CreatedAt   string             `json:"created_at,omitempty" example:"2026-04-20T08:00:00Z"`
+	CreatedBy   string             `json:"created_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	UpdatedAt   string             `json:"updated_at,omitempty" example:"2026-04-20T08:00:00Z"`
+	UpdatedBy   string             `json:"updated_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+}
+
+type MissionForms struct {
+	FlightData []FlightDataResource `json:"flight_data,omitempty"`
+}
+
+type MissionFileItem struct {
+	ID           string `json:"id" example:"019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e"`
+	AttachmentID string `json:"attachment_id,omitempty" example:"019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e"`
+	FileName     string `json:"file_name,omitempty" example:"mission-brief.pdf"`
+	DownloadURL  string `json:"download_url,omitempty" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/brief.pdf?X-Amz-Signature=..."`
+	ThumbnailURL string `json:"thumbnail_url,omitempty" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/thumbnails/2026/04/05/brief.png?X-Amz-Signature=..."`
+}
+
+type MissionFlightRef struct {
+	ID   string `json:"id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	Code string `json:"code,omitempty" example:"M-062226-001"`
+	Date string `json:"date,omitempty" example:"2026-04-20"`
+}
+
+type MissionSubtypeRef struct {
+	ID          string `json:"id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a99"`
+	Subtype     string `json:"subtype,omitempty" example:"PRIM"`
+	SubtypeName string `json:"subtype_name,omitempty" example:"Nicht transportfaehig"`
+}
+
+type MissionResource struct {
+	Type       string            `json:"type" example:"mission"`
+	ID         string            `json:"id" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	Attributes MissionAttributes `json:"attributes"`
+}
+
+type MissionResponse struct {
+	Data MissionResource `json:"data"`
+}
+
+type MissionListResponse struct {
+	Data []MissionResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type MissionDataTableResponse struct {
+	Data []MissionResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"42"`
+	} `json:"meta"`
+}
+
+type MissionTypeSubtypeItem struct {
+	ID       string `json:"id" example:"019d6774-98e8-7fba-9ef4-3795c0da8a99"`
+	Code     string `json:"code" example:"PRIM"`
+	Name     string `json:"name" example:"Primary"`
+	TaskName string `json:"task_name" example:"Nicht transportfaehig"`
+}
+
+type MissionTypeAttributes struct {
+	Code     string                   `json:"code" example:"HEMS"`
+	Name     string                   `json:"name" example:"HEMS"`
+	Subtypes []MissionTypeSubtypeItem `json:"subtypes,omitempty"`
+}
+
+type MissionTypeResource struct {
+	Type       string                `json:"type" example:"mission_type"`
+	ID         string                `json:"id" example:"019d6774-98e8-7fba-9ef4-3795c0da8a77"`
+	Attributes MissionTypeAttributes `json:"attributes"`
+}
+
+type MissionTypeListResponse struct {
+	Data []MissionTypeResource `json:"data"`
+}
diff --git a/internal/transport/http/dto/response/other_person_response.go b/internal/transport/http/dto/response/other_person_response.go
new file mode 100644
index 0000000..2fc5270
--- /dev/null
+++ b/internal/transport/http/dto/response/other_person_response.go
@@ -0,0 +1,24 @@
+package response
+
+type OtherPersonAttributes struct {
+	Name        string `json:"name" example:"Guest Person"`
+	MobilePhone string `json:"mobile_phone,omitempty" example:"+43-1234"`
+	Email       string `json:"email,omitempty" example:"guest@example.com"`
+}
+
+type OtherPersonResource struct {
+	Type       string                `json:"type" example:"other_person"`
+	ID         string                `json:"id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Attributes OtherPersonAttributes `json:"attributes"`
+}
+
+type OtherPersonListResponse struct {
+	Data []OtherPersonResource `json:"data"`
+	Meta struct {
+		Total int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
+
+type OtherPersonResponse struct {
+	Data OtherPersonResource `json:"data"`
+}
diff --git a/internal/transport/http/dto/response/reserve_ac_response.go b/internal/transport/http/dto/response/reserve_ac_response.go
new file mode 100644
index 0000000..def8ff2
--- /dev/null
+++ b/internal/transport/http/dto/response/reserve_ac_response.go
@@ -0,0 +1,98 @@
+package response
+
+import shareddto "wucher/internal/transport/http/dto/shared"
+
+type ReserveAcResource struct {
+	Type       string                        `json:"type" example:"reserve_ac"`
+	ID         string                        `json:"id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Attributes shareddto.ReserveAcAttributes `json:"attributes"`
+}
+
+type ReserveAcResponse struct {
+	Data ReserveAcResource `json:"data"`
+}
+
+type ReserveAcListResponse struct {
+	Data []ReserveAcResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"1"`
+	} `json:"meta"`
+}
+
+type ReserveAcHelicopterGroupResource struct {
+	Type       string                             `json:"type"`
+	Attributes ReserveAcHelicopterGroupAttributes `json:"attributes"`
+}
+
+type ReserveAcHelicopterGroupAttributes struct {
+	Helicopter          ReserveAcHelicopterIdentity     `json:"helicopter"`
+	LastDailyInspection ReserveAcLastDailyInspectionDTO `json:"last_daily_inspection"`
+	BFI                 ReserveAcBFISection             `json:"bfi"`
+	FPWB                ReserveAcFPWBSection            `json:"fpwb"`
+}
+
+type ReserveAcHelicopterIdentity struct {
+	ID             string                      `json:"id"`
+	Designation    string                      `json:"designation"`
+	Identifier     string                      `json:"identifier"`
+	Type           string                      `json:"type"`
+	Status         string                      `json:"status"`
+	BookingDetails *ReserveAcBookingDetailsDTO `json:"booking_details,omitempty"`
+}
+
+type ReserveAcLastDailyInspectionDTO struct {
+	ID           any                          `json:"id"`
+	InspectionBy ReserveAcInspectionBySummary `json:"inspection_by"`
+	InspectionAt any                          `json:"inspection_at"`
+}
+
+type ReserveAcInspectionBySummary struct {
+	ID        any    `json:"id"`
+	Name      string `json:"name"`
+	ShortName string `json:"short_name"`
+}
+
+type ReserveAcBookingDetailsDTO struct {
+	ReserveAcID any            `json:"reserve_ac_id,omitempty"`
+	FlightID    any            `json:"flight_id,omitempty"`
+	MissionCode any            `json:"mission_code,omitempty"`
+	DutyDate    any            `json:"duty_date,omitempty"`
+	BookedAt    any            `json:"booked_at,omitempty"`
+	BookedBy    map[string]any `json:"booked_by,omitempty"`
+}
+
+type ReserveAcHelicopterFileItem struct {
+	ID         string `json:"id"`
+	FileName   string `json:"file_name"`
+	URL        string `json:"url"`
+	UploadedAt string `json:"uploaded_at"`
+	UploadedBy string `json:"uploaded_by"`
+}
+
+type ReserveAcHelicopterFileSection struct {
+	Files []ReserveAcHelicopterFileItem `json:"files"`
+}
+
+type ReserveAcBFISection struct {
+	FuelAddedAmount           *float64                      `json:"fuel_added_amount,omitempty"`
+	FuelAmount                *float64                      `json:"fuel_amount,omitempty"`
+	FuelUnit                  string                        `json:"fuel_unit,omitempty"`
+	HydraulicLHChecked        *bool                         `json:"hydraulic_lh_checked,omitempty"`
+	HydraulicRHChecked        *bool                         `json:"hydraulic_rh_checked,omitempty"`
+	Note                      *string                       `json:"note,omitempty"`
+	OilEngineNR1Checked       *bool                         `json:"oil_engine_nr1_checked,omitempty"`
+	OilEngineNR2Checked       *bool                         `json:"oil_engine_nr2_checked,omitempty"`
+	OilTransmissionIGBChecked *bool                         `json:"oil_transmission_igb_checked,omitempty"`
+	OilTransmissionMGBChecked *bool                         `json:"oil_transmission_mgb_checked,omitempty"`
+	OilTransmissionTGBChecked *bool                         `json:"oil_transmission_tgb_checked,omitempty"`
+	Files                     []ReserveAcHelicopterFileItem `json:"files"`
+}
+
+type ReserveAcFPWBSection struct {
+	NotamBriefing         *bool                         `json:"notam_briefing,omitempty"`
+	WeatherBriefing       *bool                         `json:"weather_briefing,omitempty"`
+	OperationalFlightPlan *bool                         `json:"operational_flight_plan,omitempty"`
+	Files                 []ReserveAcHelicopterFileItem `json:"files"`
+}
diff --git a/internal/transport/http/dto/response/takeover_response.go b/internal/transport/http/dto/response/takeover_response.go
new file mode 100644
index 0000000..70be54f
--- /dev/null
+++ b/internal/transport/http/dto/response/takeover_response.go
@@ -0,0 +1,112 @@
+package response
+
+import (
+	shareddto "wucher/internal/transport/http/dto/shared"
+)
+
+type TakeoverResponseAttributes struct {
+	ID                 string                               `json:"id,omitempty"`
+	FlightID           string                               `json:"flight_id,omitempty"`
+	ReserveAcID        string                               `json:"reserve_ac_id,omitempty"`
+	FlightInspectionID string                               `json:"flight_inspection_id,omitempty"`
+	ShiftStart         string                               `json:"shift_start,omitempty"`
+	ShiftEnd           string                               `json:"shift_end,omitempty"`
+	BaseID             string                               `json:"base_id,omitempty"`
+	Base               *DutyRosterBaseInfo                  `json:"base,omitempty"`
+	DutyDate           string                               `json:"duty_date,omitempty"`
+	HelicopterID       string                               `json:"helicopter_id,omitempty"`
+	Helicopter         *TakeoverHelicopter                  `json:"helicopter,omitempty"`
+	Notes              *string                              `json:"notes,omitempty"`
+	CreatedBy          string                               `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedBy          string                               `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt          string                               `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt          string                               `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	RosterDetail       TakeoverDutyRosterDetailsResponse    `json:"roster_detail"`
+	Inspection         shareddto.ReserveAcInspectionSummary `json:"inspection"`
+	Files              []TakeoverFileResource               `json:"files,omitempty"`
+}
+
+// TakeoverHelicopter is the selected helicopter shown on a takeover, enriched
+// with its last daily inspection and its maintenance schedule (the "next due"
+// per inspection type) from the helicopter's latest fleet status.
+type TakeoverHelicopter struct {
+	ID                   string                                    `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Designation          string                                    `json:"designation" example:"OE-XHZ"`
+	Identifier           string                                    `json:"identifier" example:"1234"`
+	Type                 string                                    `json:"type" example:"EC-135"`
+	LastDailyInspection  *shareddto.HelicopterLastDailyInspection  `json:"last_daily_inspection"`
+	MaintenanceSchedules []shareddto.MaintenanceScheduleAttributes `json:"maintenance_schedules"`
+}
+
+type TakeoverDutyRosterAttributes struct {
+	Bases      DutyRosterBaseInfo                `json:"bases"`
+	FlightID   string                            `json:"flight_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Helicopter DutyRosterHelicopterSummary       `json:"helicopter"`
+	DutyDate   string                            `json:"duty_date,omitempty" example:"2026-03-16"`
+	Detail     TakeoverDutyRosterDetailsResponse `json:"roster_detail"`
+	CreatedBy  string                            `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt  string                            `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt  string                            `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+}
+
+type TakeoverDutyRosterResource struct {
+	Type       string                       `json:"type" example:"duty_roster"`
+	ID         string                       `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes TakeoverDutyRosterAttributes `json:"attributes"`
+}
+
+type TakeoverDutyRosterCrew struct {
+	ID          string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name        string `json:"name,omitempty" example:"Hunter Wolfgang"`
+	Role        string `json:"role,omitempty" example:"doctor"`
+	MobilePhone string `json:"mobile_phone,omitempty" example:"+43-1234"`
+	Email       string `json:"email,omitempty" example:"doctor@example.com"`
+}
+
+type TakeoverDutyRosterPilotCrew struct {
+	ID               string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name             string `json:"name,omitempty" example:"Hunter Wolfgang"`
+	Role             string `json:"role,omitempty" example:"pilot"`
+	MobilePhone      string `json:"mobile_phone,omitempty" example:"+43-1234"`
+	Email            string `json:"email,omitempty" example:"pilot@example.com"`
+	CrewType         string `json:"crew_type,omitempty" example:"main"`
+	FlightInstructor *bool  `json:"flight_instructor,omitempty"`
+	LineChecker      *bool  `json:"line_checker,omitempty"`
+	Supervisor       *bool  `json:"supervisor,omitempty"`
+	Examiner         *bool  `json:"examiner,omitempty"`
+	CoPilot          *bool  `json:"co_pilot,omitempty"`
+}
+
+type TakeoverDutyRosterDetailsResponse struct {
+	Pilot       []TakeoverDutyRosterPilotCrew `json:"pilot"`
+	Doctor      []TakeoverDutyRosterCrew      `json:"doctor"`
+	Rescuer     []TakeoverDutyRosterCrew      `json:"rescuer"`
+	Helper      []TakeoverDutyRosterCrew      `json:"helper"`
+	OtherPerson []TakeoverDutyRosterCrew      `json:"other_person"`
+}
+
+type TakeoverResource struct {
+	Type       string                     `json:"type" example:"takeover"`
+	Attributes TakeoverResponseAttributes `json:"attributes"`
+}
+
+type TakeoverFileAttributes struct {
+	FileAttachmentID string `json:"file_attachment_id" example:"019d7000-aaaa-7bbb-8ccc-222222222222"`
+	FileName         string `json:"file_name,omitempty" example:"takeover-report.pdf"`
+	DownloadURL      string `json:"download_url,omitempty" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/takeover-report.pdf?X-Amz-Signature=..."`
+}
+
+type TakeoverFileResource struct {
+	Type       string                 `json:"type" example:"takeover_file"`
+	ID         string                 `json:"id,omitempty" example:"019d7000-aaaa-7bbb-8ccc-111111111111"`
+	Attributes TakeoverFileAttributes `json:"attributes"`
+}
+
+type TakeoverResponse struct {
+	Data TakeoverResource `json:"data"`
+}
+
+type TakeoverListResponse struct {
+	Data []TakeoverResource `json:"data"`
+	Meta map[string]any     `json:"meta,omitempty"`
+}
diff --git a/internal/transport/http/dto/response/user_ref.go b/internal/transport/http/dto/response/user_ref.go
new file mode 100644
index 0000000..1a65394
--- /dev/null
+++ b/internal/transport/http/dto/response/user_ref.go
@@ -0,0 +1,8 @@
+package response
+
+// UserRef is an audit user reference exposing both the raw UUID and a resolved
+// display name, e.g. for created_by / updated_by fields.
+type UserRef struct {
+	UUID string `json:"uuid" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	Name string `json:"name,omitempty" example:"Ganahl Stefan"`
+}
diff --git a/internal/transport/http/dto/role_dto.go b/internal/transport/http/dto/role_dto.go
new file mode 100644
index 0000000..709dcb7
--- /dev/null
+++ b/internal/transport/http/dto/role_dto.go
@@ -0,0 +1,174 @@
+package dto
+
+// JSON:API Role DTOs
+
+type RoleAttributes struct {
+	Name        string `json:"name" example:"admin"`
+	Description string `json:"description,omitempty" example:"Full access to all resources."`
+	CreatedBy   string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt   string `json:"created_at,omitempty" example:"2026-02-05T10:00:00Z"`
+	UpdatedAt   string `json:"updated_at,omitempty" example:"2026-02-05T10:00:00Z"`
+}
+
+type RoleResource struct {
+	Type        string               `json:"type" example:"role"`
+	ID          string               `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes  RoleAttributes       `json:"attributes"`
+	Permissions []PermissionResource `json:"permissions,omitempty"`
+}
+
+type RoleResponse struct {
+	Data RoleResource `json:"data"`
+}
+
+type RoleListResponse struct {
+	Data []RoleResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type RoleDataTableResponse struct {
+	Data []RoleResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type PermissionAttributes struct {
+	Name        string `json:"name" example:"User Management"`
+	Key         string `json:"key" example:"user.manage"`
+	Description string `json:"description,omitempty" example:"Allows managing users."`
+	RequiresPIN bool   `json:"requires_pin" example:"true"`
+	CreatedAt   string `json:"created_at,omitempty" example:"2026-02-05T10:00:00Z"`
+	UpdatedAt   string `json:"updated_at,omitempty" example:"2026-02-05T10:00:00Z"`
+}
+
+type PermissionResource struct {
+	Type       string               `json:"type" example:"permission"`
+	ID         string               `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes PermissionAttributes `json:"attributes"`
+}
+
+type PermissionListResponse struct {
+	Data []PermissionResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type PermissionGroupResource struct {
+	Module      string               `json:"module" example:"dul"`
+	ModuleLabel string               `json:"module_label" example:"DUL"`
+	Permissions []PermissionResource `json:"permissions"`
+}
+
+type PermissionGroupedResponse struct {
+	Data []PermissionGroupResource `json:"data"`
+}
+
+// Create
+type RoleCreateAttributes struct {
+	Name        string `json:"name" validate:"required" example:"admin"`
+	Description string `json:"description,omitempty" example:"Full access to all resources."`
+}
+
+type RoleCreateData struct {
+	Type       string               `json:"type" validate:"required,oneof=role_create role" example:"role_create"`
+	Attributes RoleCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type RoleCreateRequest struct {
+	Data RoleCreateData `json:"data" validate:"required"`
+}
+
+// Update
+type RoleUpdateAttributes struct {
+	Name        *string `json:"name,omitempty" example:"admin"`
+	Description *string `json:"description,omitempty" example:"Full access to all resources."`
+}
+
+type RoleUpdateData struct {
+	Type       string               `json:"type" validate:"required,oneof=role_update role" example:"role_update"`
+	ID         string               `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes RoleUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type RoleUpdateRequest struct {
+	Data RoleUpdateData `json:"data" validate:"required"`
+}
+
+// Role-Permission
+type RolePermissionAttributes struct {
+	RoleID       string `json:"role_id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	PermissionID string `json:"permission_id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e"`
+}
+
+type RolePermissionResource struct {
+	Type       string                   `json:"type" example:"role_permission"`
+	ID         string                   `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f"`
+	Attributes RolePermissionAttributes `json:"attributes"`
+}
+
+type RolePermissionResponse struct {
+	Data RolePermissionResource `json:"data"`
+}
+
+type RolePermissionListResponse struct {
+	Data []RolePermissionResource `json:"data"`
+}
+
+type RolePermissionAssignAttributes struct {
+	PermissionID string `json:"permission_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e"`
+}
+
+type RolePermissionAssignData struct {
+	Type       string                         `json:"type" validate:"required,eq=role_permission" example:"role_permission"`
+	Attributes RolePermissionAssignAttributes `json:"attributes" validate:"required"`
+}
+
+type RolePermissionAssignRequest struct {
+	Data RolePermissionAssignData `json:"data" validate:"required"`
+}
+
+type RolePermissionBulkAttributes struct {
+	PermissionIDs []string `json:"permission_ids" validate:"required" example:"[\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e\",\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9f\"]"`
+}
+
+type RolePermissionAssignBulkData struct {
+	Type       string                       `json:"type" validate:"required,eq=role_assign_permission_bulk" example:"role_assign_permission_bulk"`
+	Attributes RolePermissionBulkAttributes `json:"attributes" validate:"required"`
+}
+
+type RolePermissionAssignBulkRequest struct {
+	Data RolePermissionAssignBulkData `json:"data" validate:"required"`
+}
+
+type RolePermissionRemoveBulkData struct {
+	Type       string                       `json:"type" validate:"required,eq=role_remove_permission_bulk" example:"role_remove_permission_bulk"`
+	Attributes RolePermissionBulkAttributes `json:"attributes" validate:"required"`
+}
+
+type RolePermissionRemoveBulkRequest struct {
+	Data RolePermissionRemoveBulkData `json:"data" validate:"required"`
+}
+
+type PermissionUpdateAttributes struct {
+	RequiresPIN *bool `json:"requires_pin" validate:"required" example:"true"`
+}
+
+type PermissionUpdateData struct {
+	Type       string                     `json:"type" validate:"required,oneof=permission_update permission" example:"permission_update"`
+	ID         string                     `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes PermissionUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type PermissionUpdateRequest struct {
+	Data PermissionUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/shared/air_rescuer_checklist_shared.go b/internal/transport/http/dto/shared/air_rescuer_checklist_shared.go
new file mode 100644
index 0000000..c808979
--- /dev/null
+++ b/internal/transport/http/dto/shared/air_rescuer_checklist_shared.go
@@ -0,0 +1,13 @@
+package shared
+
+type AirRescuerChecklistBaseInfo struct {
+	ID               string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	BaseName         string `json:"base_name,omitempty" example:"Gallus 1 - Zurs Lech"`
+	BaseAbbreviation string `json:"base_abbreviation,omitempty" example:"G1"`
+	BaseCategory     string `json:"base_category,omitempty" example:"hems"`
+}
+
+type AirRescuerChecklistItemInput struct {
+	Name     string `json:"name" validate:"required" example:"Oxygen supply check"`
+	Position *int   `json:"position,omitempty" example:"1"`
+}
diff --git a/internal/transport/http/dto/shared/file_manager_attachment_shared.go b/internal/transport/http/dto/shared/file_manager_attachment_shared.go
new file mode 100644
index 0000000..d15cc87
--- /dev/null
+++ b/internal/transport/http/dto/shared/file_manager_attachment_shared.go
@@ -0,0 +1,13 @@
+package shared
+
+type FileManagerAttachmentAttributes struct {
+	FileID     string `json:"file_id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	RefType    string `json:"ref_type" example:"helicopter"`
+	RefID      string `json:"ref_id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Category   string `json:"category,omitempty" example:"document"`
+	SortOrder  int    `json:"sort_order" example:"0"`
+	IsPrimary  bool   `json:"is_primary" example:"false"`
+	AttachedBy string `json:"attached_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	CreatedAt  string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedAt  string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+}
diff --git a/internal/transport/http/dto/shared/file_manager_file_shared.go b/internal/transport/http/dto/shared/file_manager_file_shared.go
new file mode 100644
index 0000000..c0cb572
--- /dev/null
+++ b/internal/transport/http/dto/shared/file_manager_file_shared.go
@@ -0,0 +1,104 @@
+package shared
+
+type FileManagerFileAttributes struct {
+	FileUUID            string `json:"file_uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	FolderID            string `json:"folder_id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name                string `json:"name" example:"policy.pdf"`
+	NameNormalized      string `json:"name_normalized,omitempty" example:"policy.pdf"`
+	Extension           string `json:"extension,omitempty" example:"pdf"`
+	SizeBytes           int64  `json:"size_bytes" example:"1024"`
+	MimeType            string `json:"mime_type" example:"application/pdf"`
+	IsTemplate          bool   `json:"is_template" example:"true"`
+	DownloadURL         string `json:"download_url,omitempty" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."`
+	Status              string `json:"status" example:"validated"`
+	FailureReason       string `json:"failure_reason,omitempty" example:""`
+	UploadError         string `json:"upload_error,omitempty" example:""`
+	ProcessingStartedAt string `json:"processing_started_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	ProcessedAt         string `json:"processed_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	ValidatedAt         string `json:"validated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	FailedAt            string `json:"failed_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedAt           string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy           string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt           string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy           string `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt           string `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy           string `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	TrashedAt           string `json:"trashed_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	PurgeAt             string `json:"purge_at,omitempty" example:"2026-04-12T03:04:05Z"`
+}
+
+type FileManagerFileListAttributes struct {
+	Name           string `json:"name" example:"policy.pdf"`
+	NameNormalized string `json:"name_normalized,omitempty" example:"policy.pdf"`
+	Extension      string `json:"extension,omitempty" example:"pdf"`
+	SizeBytes      int64  `json:"size_bytes" example:"1024"`
+	MimeType       string `json:"mime_type" example:"application/pdf"`
+	IsTemplate     bool   `json:"is_template" example:"true"`
+	DownloadURL    string `json:"download_url,omitempty" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."`
+	Status         string `json:"status" example:"ready"`
+	CreatedAt      string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy      string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt      string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy      string `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FileManagerFileLocationAttributes struct {
+	FolderID string `json:"folder_id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FileManagerFileProcessingAttributes struct {
+	ProcessingStartedAt string `json:"processing_started_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	ProcessedAt         string `json:"processed_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	ValidatedAt         string `json:"validated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	FailedAt            string `json:"failed_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	FailureReason       string `json:"failure_reason,omitempty" example:"processing validation failed"`
+}
+
+type FileManagerFileAuditAttributes struct {
+	CreatedAt string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy string `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FileManagerFileDetailAttributes struct {
+	Name           string                               `json:"name" example:"policy.pdf"`
+	NameNormalized string                               `json:"name_normalized,omitempty" example:"policy.pdf"`
+	Extension      string                               `json:"extension,omitempty" example:"pdf"`
+	SizeBytes      int64                                `json:"size_bytes" example:"1024"`
+	MimeType       string                               `json:"mime_type" example:"application/pdf"`
+	IsTemplate     bool                                 `json:"is_template" example:"true"`
+	DownloadURL    string                               `json:"download_url,omitempty" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."`
+	PreviewURL     string                               `json:"preview_url,omitempty" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.preview.pdf?X-Amz-Signature=..."`
+	Status         string                               `json:"status" example:"ready"`
+	Location       *FileManagerFileLocationAttributes   `json:"location,omitempty"`
+	Processing     *FileManagerFileProcessingAttributes `json:"processing,omitempty"`
+	Audit          FileManagerFileAuditAttributes       `json:"audit"`
+}
+
+type FileManagerFileDownloadAttributes struct {
+	URL             string `json:"url" example:"https://s3.localhost.localstack.cloud:4566/..."`
+	ExpiresInSecond int64  `json:"expires_in_second" example:"900"`
+}
+
+type FileManagerFileUploadIntentAttributes struct {
+	UploadIntentID   string            `json:"upload_intent_uuid" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UploadURL        string            `json:"upload_url" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/..."`
+	Method           string            `json:"method" example:"PUT"`
+	RequiredHeaders  map[string]string `json:"required_headers,omitempty"`
+	Object           FileUploadObject  `json:"object"`
+	File             FileUploadFile    `json:"file"`
+	ExpiresAt        string            `json:"expires_at" example:"2026-04-05T07:29:34Z"`
+	ExpiresInSeconds int64             `json:"expires_in_seconds" example:"900"`
+}
+
+type FileUploadObject struct {
+	Bucket string `json:"bucket" example:"wucher-file-dev"`
+	Key    string `json:"key" example:"files/2026/04/05/018f3a5c7a6f7c2a8d4a4b5b1f6c8e9d.pdf"`
+}
+
+type FileUploadFile struct {
+	Name      string `json:"name" example:"policy-final.pdf"`
+	MimeType  string `json:"mime_type" example:"application/pdf"`
+	SizeBytes int64  `json:"size_bytes" example:"1024"`
+}
diff --git a/internal/transport/http/dto/shared/file_manager_folder_shared.go b/internal/transport/http/dto/shared/file_manager_folder_shared.go
new file mode 100644
index 0000000..f5cc16a
--- /dev/null
+++ b/internal/transport/http/dto/shared/file_manager_folder_shared.go
@@ -0,0 +1,36 @@
+package shared
+
+type FileManagerFolderAttributes struct {
+	ParentID       string `json:"parent_id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name           string `json:"name" example:"operations"`
+	NameNormalized string `json:"name_normalized,omitempty" example:"operations"`
+	Depth          int    `json:"depth" example:"1"`
+	PathCache      string `json:"path_cache,omitempty" example:"/root/operations"`
+	CreatedAt      string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy      string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt      string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy      string `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt      string `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy      string `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	PurgeAt        string `json:"purge_at,omitempty" example:"2026-04-12T03:04:05Z"`
+}
+
+type FileManagerFolderLocationAttributes struct {
+	ParentID string `json:"parent_id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FileManagerFolderAuditAttributes struct {
+	CreatedAt string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy string `json:"created_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy string `json:"updated_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type FileManagerFolderDetailAttributes struct {
+	Name           string                               `json:"name" example:"operations"`
+	NameNormalized string                               `json:"name_normalized,omitempty" example:"operations"`
+	Depth          *int                                 `json:"depth,omitempty" example:"1"`
+	PathCache      string                               `json:"path_cache,omitempty" example:"/root/operations"`
+	Location       *FileManagerFolderLocationAttributes `json:"location,omitempty"`
+	Audit          FileManagerFolderAuditAttributes     `json:"audit"`
+}
diff --git a/internal/transport/http/dto/shared/fleet_status_shared.go b/internal/transport/http/dto/shared/fleet_status_shared.go
new file mode 100644
index 0000000..bab16f3
--- /dev/null
+++ b/internal/transport/http/dto/shared/fleet_status_shared.go
@@ -0,0 +1,174 @@
+package shared
+
+type FleetStatusHelicopter struct {
+	ID          string `json:"id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Designation string `json:"designation,omitempty" example:"AIRBUS H145"`
+	Identifier  string `json:"identifier,omitempty" example:"D-HEMS"`
+	Type        string `json:"type,omitempty" example:"EC-135"`
+	Status      string `json:"status,omitempty" example:"available" enums:"available,booked,aog,mcf"`
+	// FlightID — id of the aircraft's current active flight (present only when it is in
+	// use / booked). The fleet page uses it to create an EASA release scoped to the flight.
+	FlightID      string                        `json:"flight_id,omitempty" example:"019d6774-98e8-7fba-9ef4-3795c0da8a13"`
+	StatusReasons []FleetStatusHelicopterReason `json:"status_reasons,omitempty"`
+}
+
+// FleetStatusMCF is the helicopter's maintenance check flight shown on the fleet page.
+// When the helicopter has no MCF yet, id is empty and sign is false. af_hours /
+// landing_count are the SIGNED check-flight values — present only once the MCF is signed.
+type FleetStatusMCF struct {
+	// Active — true when the helicopter is currently in MCF (an open draft, or a signed
+	// but failed MCF still needing a re-flight); false when cleared/cancelled/none.
+	Active bool    `json:"active"`
+	ID     string  `json:"id"`
+	Date   *string `json:"date"`
+	// AFHours / LandingCount present only once the MCF is signed; omitted for none/draft/cancelled.
+	AFHours      *string `json:"af_hours,omitempty"`
+	LandingCount *int    `json:"landing_count,omitempty"`
+	// Sign — true once the MCF is completed/signed; false while it is still a draft.
+	Sign bool `json:"sign"`
+	// SignedBy / SignedByName / SignedByShort — who signed (completed) the MCF; empty while unsigned.
+	SignedBy      string  `json:"signed_by,omitempty"`
+	SignedByName  *string `json:"signed_by_name,omitempty"`
+	SignedByShort *string `json:"signed_by_short,omitempty"`
+}
+
+type MaintenanceScheduleAttributes struct {
+	InspectionType string `json:"inspection_type" example:"A/F"`
+	Type           string `json:"type" example:"100H"`
+	Due            string `json:"due" validate:"omitempty,hours_or_date" example:"1200"`
+	Ext            string `json:"ext" validate:"omitempty,hours_or_date" example:"1300"`
+}
+
+type FleetStatusFileAttributes struct {
+	FileID   string `json:"file_id" validate:"required" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Category string `json:"category" validate:"required,oneof=wb bfi" example:"wb"`
+	// IsMandatory — when true, this file must be checked (is_done) during takeover.
+	IsMandatory *bool `json:"is_mandatory,omitempty" example:"true"`
+}
+
+type FleetStatusSummaryAirframe struct {
+	Hours  *float64 `json:"hours"`
+	Cycles *float64 `json:"cycles"`
+}
+
+type FleetStatusSummaryEngine struct {
+	Hours   *float64 `json:"hours"`
+	GpcNgN1 *float64 `json:"gpc_ng_n1"`
+	PtcNfN2 *float64 `json:"ptc_nf_n2"`
+	Ccc     *float64 `json:"ccc"`
+}
+
+type FleetStatusSummary struct {
+	Airframe         FleetStatusSummaryAirframe `json:"airframe"`
+	Engine1          FleetStatusSummaryEngine   `json:"engine_1"`
+	Engine2          FleetStatusSummaryEngine   `json:"engine_2"`
+	Landings         *float64                   `json:"landings"`
+	FlightReports    *float64                   `json:"flight_reports"`
+	RotorBrakeCycles *float64                   `json:"rotor_brake_cycles"`
+	HookReleases     *float64                   `json:"hook_releases"`
+}
+
+type FleetStatusServiceLogAttributes struct {
+	FleetStatusID     string                 `json:"fleet_status_id" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	HelicopterID      string                 `json:"helicopter_id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Helicopter        *FleetStatusHelicopter `json:"helicopter,omitempty"`
+	FleetStatusStatus string                 `json:"fleet_status_status,omitempty" example:"serviced"`
+	InspectionType    string                 `json:"inspection_type" example:"A/F"`
+	Type              string                 `json:"type" example:"100H"`
+	Due               string                 `json:"due" example:"1200 FH"`
+	Ext               string                 `json:"ext" example:"1300 FH"`
+	ServicedAt        string                 `json:"serviced_at" example:"2026-05-29T07:43:06Z"`
+	CreatedAt         string                 `json:"created_at" example:"2026-05-29T07:43:06Z"`
+	CreatedBy         string                 `json:"created_by" example:"John Doe"`
+}
+
+const (
+	ReasonCodeManualAOG         = "manual_aog"
+	ReasonCodeMELExpired        = "mel_expired"
+	ReasonCodeNonMELPending     = "non_mel_pending"
+	ReasonCodeInspectionOverdue = "inspection_overdue"
+)
+
+type FleetStatusComplaint struct {
+	ID                    string                     `json:"id"`
+	FlightID              string                     `json:"flight_id,omitempty"`
+	Description           string                     `json:"description"`
+	Status                string                     `json:"status" enums:"active_non_mel,active_mel,serviced"`
+	ReportedAt            string                     `json:"reported_at"`
+	ReportedBy            string                     `json:"reported_by,omitempty"`
+	ReportedByName        string                     `json:"reported_by_name,omitempty"`
+	ReportedByShort       string                     `json:"reported_by_short,omitempty"`
+	AircraftHoursAtReport *string                    `json:"aircraft_hours_at_report,omitempty"`
+	MEL                   FleetStatusComplaintMEL    `json:"mel"`
+	NSR                   FleetStatusComplaintNSR    `json:"nsr"`
+	Action                FleetStatusComplaintAction `json:"action"`
+}
+
+type FleetStatusComplaintMEL struct {
+	Severity         int8    `json:"severity" enums:"0,1,2,3,4"`
+	SeverityLabel    *string `json:"severity_label"`
+	ClassifiedAt     *string `json:"classified_at,omitempty"`
+	ClassifiedBy      string  `json:"classified_by,omitempty"`
+	ClassifiedByName  string  `json:"classified_by_name,omitempty"`
+	ClassifiedByShort string  `json:"classified_by_short,omitempty"`
+	Deadline          *string `json:"deadline,omitempty"`
+}
+
+type FleetStatusComplaintNSR struct {
+	IsNSR         bool    `json:"is_nsr"`
+	DecidedAt     *string `json:"decided_at,omitempty"`
+	DecidedBy      string  `json:"decided_by,omitempty"`
+	DecidedByName  string  `json:"decided_by_name,omitempty"`
+	DecidedByShort string  `json:"decided_by_short,omitempty"`
+	Reason         *string `json:"reason,omitempty"`
+}
+
+type FleetStatusComplaintAction struct {
+	Taken              *string `json:"taken"`
+	SignedAt           *string `json:"signed_at,omitempty"`
+	SignedBy           string  `json:"signed_by,omitempty"`
+	SignedByName       string  `json:"signed_by_name,omitempty"`
+	SignedByShort      string  `json:"signed_by_short,omitempty"`
+	AircraftHoursAtFix *string `json:"aircraft_hours_at_fix,omitempty"`
+}
+
+type FleetStatusEASARelease struct {
+	ID                         string   `json:"id"`
+	IsSigned                   bool     `json:"is_signed"`
+	EASADate                   *string  `json:"easa_date,omitempty"`
+	EASAACHours                *string  `json:"easa_ac_hours,omitempty"`
+	EASALocation               *string  `json:"easa_location,omitempty"`
+	EASAWONo                   *string  `json:"easa_wo_no,omitempty"`
+	EASAMaintManualRevAirframe *string  `json:"easa_maint_manual_rev_airframe,omitempty"`
+	EASAMaintManualRevEngine   *string  `json:"easa_maint_manual_rev_engine,omitempty"`
+	EASASignerID               *string  `json:"easa_signer_id,omitempty"`
+	EASAPermitNo               *string  `json:"easa_permit_no,omitempty"`
+	SignedAt                   *string  `json:"signed_at,omitempty"`
+	SignedBy                   string   `json:"signed_by,omitempty"`
+	SignedByName               string   `json:"signed_by_name,omitempty"`
+	SignedByShort              string   `json:"signed_by_short,omitempty"`
+	MissingSignFields          []string `json:"missing_sign_fields,omitempty"`
+}
+
+func MELLabel(severity int8) string {
+	switch severity {
+	case 1:
+		return "A"
+	case 2:
+		return "B"
+	case 3:
+		return "C"
+	case 4:
+		return "D"
+	default:
+		return ""
+	}
+}
+
+type FleetStatusHelicopterReason struct {
+	Code        string  `json:"code" enums:"manual_aog,mel_expired,non_mel_pending,inspection_overdue"`
+	Detail      string  `json:"detail"`
+	Since       *string `json:"since,omitempty"`
+	ComplaintID string  `json:"complaint_id,omitempty"`
+	ScheduleID  string  `json:"schedule_id,omitempty"`
+}
diff --git a/internal/transport/http/dto/shared/flight_inspection_file_checklist_shared.go b/internal/transport/http/dto/shared/flight_inspection_file_checklist_shared.go
new file mode 100644
index 0000000..02e62cf
--- /dev/null
+++ b/internal/transport/http/dto/shared/flight_inspection_file_checklist_shared.go
@@ -0,0 +1,11 @@
+package shared
+
+type FlightInspectionFileChecklistAttributes struct {
+	IsDone             bool   `json:"is_done" example:"false"`
+	HelicopterFileID   string `json:"helicopter_file_id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	FlightInspectionID string `json:"flight_inspection_id" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	CreatedAt          string `json:"created_at,omitempty" example:"2026-04-14T08:00:00Z"`
+	CreatedBy          string `json:"created_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	UpdatedAt          string `json:"updated_at,omitempty" example:"2026-04-14T08:00:00Z"`
+	UpdatedBy          string `json:"updated_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+}
diff --git a/internal/transport/http/dto/shared/helicopter_file_shared.go b/internal/transport/http/dto/shared/helicopter_file_shared.go
new file mode 100644
index 0000000..8fe9b4e
--- /dev/null
+++ b/internal/transport/http/dto/shared/helicopter_file_shared.go
@@ -0,0 +1,18 @@
+package shared
+
+type HelicopterFileAttributes struct {
+	Section           string `json:"section" example:"bfi"`
+	Position          int    `json:"position" example:"1"`
+	IsMandatory       bool   `json:"is_mandatory" example:"true"`
+	IsTemplate        bool   `json:"is_template" example:"true"`
+	HelicopterID      string `json:"helicopter_id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	HelicopterName    string `json:"helicopter_name,omitempty" example:"AIRBUS H145"`
+	FileAttachmentID  string `json:"file_attachment_id" example:"019d6771-6c8e-7a2d-a7b8-03bcb65fcb3e"`
+	AttachmentPending bool   `json:"attachment_pending" example:"true"`
+	FileName          string `json:"file_name,omitempty" example:"Before Flight Checklist.pdf"`
+	DownloadURL       string `json:"download_url,omitempty" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."`
+	CreatedAt         string `json:"created_at,omitempty" example:"2026-04-14T08:00:00Z"`
+	CreatedBy         string `json:"created_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	UpdatedAt         string `json:"updated_at,omitempty" example:"2026-04-14T08:00:00Z"`
+	UpdatedBy         string `json:"updated_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+}
diff --git a/internal/transport/http/dto/shared/helicopter_shared.go b/internal/transport/http/dto/shared/helicopter_shared.go
new file mode 100644
index 0000000..4260209
--- /dev/null
+++ b/internal/transport/http/dto/shared/helicopter_shared.go
@@ -0,0 +1,45 @@
+package shared
+
+// Helicopter nested value objects reused as building blocks by helicopter
+// response DTOs (and available to any other module that embeds helicopter
+// summaries).
+
+type HelicopterLastDailyInspection struct {
+	InspectionID             string                             `json:"inspection_id,omitempty" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	Status                   string                             `json:"status" example:"inspected_cleared"`
+	Inspector                HelicopterLastDailyInspector       `json:"inspector"`
+	Base                     HelicopterLastDailyBase            `json:"base"`
+	InspectedAt              string                             `json:"inspected_at,omitempty" example:"2026-05-25T07:47:00Z"`
+	UTCTime                  string                             `json:"utc_time,omitempty" example:"07:47"`
+	InspectionFilesChecklist HelicopterInspectionFilesChecklist `json:"inspection_files_checklist"`
+}
+
+type HelicopterLastDailyInspector struct {
+	ID        string `json:"id,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	Name      string `json:"name,omitempty" example:"Teodora Lesmana"`
+	LicenseNo string `json:"license_no,omitempty" example:"4521"`
+}
+
+type HelicopterLastDailyBase struct {
+	ID               string `json:"id,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	BaseAbbreviation string `json:"base_abbreviation,omitempty" example:"G1"`
+	BaseName         string `json:"base_name,omitempty" example:"Gallus 1 - Zurs Lech"`
+	Type             string `json:"type,omitempty" example:"hems"`
+}
+
+type HelicopterInspectionFilesChecklist struct {
+	Completed int `json:"completed" example:"47"`
+	Total     int `json:"total" example:"47"`
+}
+
+type HelicopterFoto struct {
+	UUID                 string `json:"uuid" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DownloadURL          string `json:"download_url" example:"https://storage.example.com/helicopter/foto.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=abc123"`
+	ThumbnailDownloadURL string `json:"thumbnail_download_url,omitempty" example:"https://storage.example.com/helicopter/foto.thumb.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=abc123"`
+	OriginalSizeBytes    *int64 `json:"original_size_bytes,omitempty" example:"1024000"`
+}
+
+type HelicopterAuditUser struct {
+	ID   string `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Name string `json:"name" example:"John Doe"`
+}
diff --git a/internal/transport/http/dto/shared/reserve_ac_shared.go b/internal/transport/http/dto/shared/reserve_ac_shared.go
new file mode 100644
index 0000000..216df5f
--- /dev/null
+++ b/internal/transport/http/dto/shared/reserve_ac_shared.go
@@ -0,0 +1,120 @@
+package shared
+
+import "time"
+
+type ReserveAcAttributes struct {
+	Status     string                      `json:"status" example:"pending"`
+	AircraftID string                      `json:"helicopter_id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Aircraft   *ReserveAcAircraftSummary   `json:"helicopter,omitempty"`
+	LastDaily  *ReserveAcLastDailyInfo     `json:"last_daily_inspection,omitempty"`
+	FlightID   string                      `json:"flight_id,omitempty" example:"019d6773-ccca-71dd-b9c7-8e6f531deb90"`
+	Inspection *ReserveAcInspectionSummary `json:"inspection,omitempty"`
+	CreatedAt  string                      `json:"created_at,omitempty" example:"2026-04-14T08:00:00Z"`
+	CreatedBy  string                      `json:"created_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	UpdatedAt  string                      `json:"updated_at,omitempty" example:"2026-04-14T08:00:00Z"`
+	UpdatedBy  string                      `json:"updated_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+	DeletedAt  string                      `json:"deleted_at,omitempty" example:"2026-04-14T08:00:00Z"`
+	DeletedBy  string                      `json:"deleted_by,omitempty" example:"019d61db-53c6-7280-87ec-e65f205c6d3b"`
+}
+
+type ReserveAcLastDailyInfo struct {
+	Name      string `json:"name" example:"Ganahl Stefan"`
+	ShortName string `json:"short_name" example:"GAN"`
+	Date      string `json:"date" example:"17.04.2026"`
+	UTCTime   string `json:"utc_time" example:"10:57"`
+}
+
+type ReserveAcAircraftSummary struct {
+	ID          string `json:"id" example:"019d6771-5fb5-7337-837f-bc5ed85181a1"`
+	Designation string `json:"designation" example:"AIRBUS H145"`
+	Identifier  string `json:"identifier" example:"D-HYAR"`
+	Type        string `json:"type" example:"H145"`
+	AOG         bool   `json:"aog" example:"false"`
+	IsActive    bool   `json:"is_active" example:"true"`
+}
+
+type ReserveAcInspectionSummary struct {
+	ID              string                             `json:"id" example:"019d6772-471c-7b70-b42a-d94020ef61e4"`
+	InspectionDate  string                             `json:"inspection_date,omitempty" example:"2026-04-15"`
+	Before          ReserveAcBeforeSectionDTO          `json:"before"`
+	Prepare         ReserveAcPrepareSectionDTO         `json:"prepare"`
+	FleetStatusFile ReserveAcFleetStatusFileSectionDTO `json:"fleet_status_file"`
+}
+
+type ReserveAcBeforeSectionDTO struct {
+	Total         int                              `json:"total" example:"3"`
+	Completed     int                              `json:"completed" example:"1"`
+	DoneFiles     []ReserveAcFileChecklistItemDTO  `json:"done_file_checklist,omitempty"`
+	Fields        *ReserveAcBeforeInspectionFields `json:"fields,omitempty"`
+	FileChecklist []ReserveAcFileChecklistItemDTO  `json:"file_checklist"`
+}
+
+type ReserveAcPrepareSectionDTO struct {
+	Total         int                             `json:"total" example:"3"`
+	Completed     int                             `json:"completed" example:"1"`
+	DoneFiles     []ReserveAcFileChecklistItemDTO `json:"done_file_checklist,omitempty"`
+	PrepareFields *ReserveAcPrepareFields         `json:"prepare_fields,omitempty"`
+	FileChecklist []ReserveAcFileChecklistItemDTO `json:"file_checklist"`
+}
+
+type ReserveAcFleetStatusFileSectionDTO struct {
+	Total         int                             `json:"total" example:"2"`
+	Completed     int                             `json:"completed" example:"1"`
+	DoneFiles     []ReserveAcFileChecklistItemDTO `json:"done_file_checklist,omitempty"`
+	FileChecklist []ReserveAcFileChecklistItemDTO `json:"file_checklist"`
+}
+
+type ReserveAcFileChecklistItemDTO struct {
+	HelicopterFileID string `json:"helicopter_file_id" example:"019d7000-aaaa-7bbb-8ccc-111111111111"`
+	FileAttachmentID string `json:"file_attachment_id,omitempty" example:"019d7000-aaaa-7bbb-8ccc-222222222222"`
+	FileName         string `json:"file_name,omitempty" example:"Before Flight Checklist.pdf"`
+	DownloadURL      string `json:"download_url,omitempty" example:"https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/policy.pdf?X-Amz-Signature=..."`
+	IsDone           bool   `json:"is_done" example:"false"`
+	IsMandatory      bool   `json:"is_mandatory" example:"true"`
+}
+
+type ReserveAcBeforeInspectionFields struct {
+	OilEngineNR1Checked       *bool    `json:"oil_engine_nr1_checked,omitempty"`
+	OilEngineNR2Checked       *bool    `json:"oil_engine_nr2_checked,omitempty"`
+	HydraulicLHChecked        *bool    `json:"hydraulic_lh_checked,omitempty"`
+	HydraulicRHChecked        *bool    `json:"hydraulic_rh_checked,omitempty"`
+	OilTransmissionMGBChecked *bool    `json:"oil_transmission_mgb_checked,omitempty"`
+	OilTransmissionIGBChecked *bool    `json:"oil_transmission_igb_checked,omitempty"`
+	OilTransmissionTGBChecked *bool    `json:"oil_transmission_tgb_checked,omitempty"`
+	FuelAmount                *float64 `json:"fuel_amount,omitempty"`
+	FuelUnit                  string   `json:"fuel_unit,omitempty"`
+	FuelAddedAmount           *float64 `json:"fuel_added_amount,omitempty"`
+	Note                      *string  `json:"note,omitempty"`
+}
+
+type ReserveAcPrepareFields struct {
+	NotamBriefing         *bool `json:"notam_briefing,omitempty"`
+	WeatherBriefing       *bool `json:"weather_briefing,omitempty"`
+	OperationalFlightPlan *bool `json:"operational_flight_plan,omitempty"`
+}
+
+type LastDailyInspection struct {
+	ID        []byte
+	Name      string
+	ShortName string
+	At        time.Time
+}
+
+type LastDailyInspectionSummary struct {
+	InspectionID string
+	Status       string
+
+	InspectorID        string
+	InspectorName      string
+	InspectorLicenseNo string
+
+	BaseID           string
+	BaseName         string
+	BaseAbbreviation string
+	BaseType         string
+
+	InspectedAt time.Time
+
+	InspectionFilesChecklistCompleted int
+	InspectionFilesChecklistTotal     int
+}
diff --git a/internal/transport/http/dto/user_dto.go b/internal/transport/http/dto/user_dto.go
new file mode 100644
index 0000000..defe1c4
--- /dev/null
+++ b/internal/transport/http/dto/user_dto.go
@@ -0,0 +1,103 @@
+package dto
+
+import (
+	"bytes"
+	"encoding/json"
+)
+
+// JSON:API User DTOs
+
+type UserResource struct {
+	Type       string         `json:"type" example:"user"`
+	ID         string         `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes UserAttributes `json:"attributes"`
+}
+
+type UserListResponse struct {
+	Data []UserResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type UserDataTableResponse struct {
+	Data []UserResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+// Create
+
+type UserCreateAttributes struct {
+	Email       string   `json:"email" validate:"required,email" example:"user@example.com"`
+	Username    string   `json:"username" validate:"required,min=3,max=100" example:"john.doe"`
+	FirstName   string   `json:"first_name" validate:"required" example:"John"`
+	LastName    string   `json:"last_name" validate:"required" example:"Doe"`
+	MobilePhone string   `json:"mobile_phone,omitempty" example:"+628123456789"`
+	Timezone    *string  `json:"timezone,omitempty" example:"Asia/Jakarta"`
+	ImageUUID   *string  `json:"image_uuid,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"`
+	RoleID      string   `json:"role_id" validate:"required" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	RoleIDs     []string `json:"role_ids,omitempty" example:"[\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d\",\"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9e\"]"`
+}
+
+type UserCreateData struct {
+	Type       string               `json:"type" validate:"required,oneof=user_create user" example:"user_create"`
+	Attributes UserCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type UserCreateRequest struct {
+	Data UserCreateData `json:"data" validate:"required"`
+}
+
+// Update
+
+type UserUpdateAttributes struct {
+	Email       *string    `json:"email,omitempty" validate:"omitempty,email" example:"user@example.com"`
+	FirstName   *string    `json:"first_name,omitempty" example:"John"`
+	LastName    *string    `json:"last_name,omitempty" example:"Doe"`
+	MobilePhone *string    `json:"mobile_phone,omitempty" example:"+628123456789"`
+	Timezone    *string    `json:"timezone,omitempty" example:"Asia/Jakarta"`
+	ImageUUID   NullString `json:"image_uuid,omitempty" swaggertype:"string" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e90"`
+}
+
+// NullString allows PATCH semantics:
+// - field omitted => Set=false (no change)
+// - value null    => Set=true, Valid=false (clear value)
+// - value string  => Set=true, Valid=true, Value=<string>
+type NullString struct {
+	Set   bool
+	Valid bool
+	Value string
+}
+
+func (n *NullString) UnmarshalJSON(data []byte) error {
+	n.Set = true
+	trimmed := bytes.TrimSpace(data)
+	if bytes.Equal(trimmed, []byte("null")) {
+		n.Valid = false
+		n.Value = ""
+		return nil
+	}
+	var v string
+	if err := json.Unmarshal(trimmed, &v); err != nil {
+		return err
+	}
+	n.Valid = true
+	n.Value = v
+	return nil
+}
+
+type UserUpdateData struct {
+	Type       string               `json:"type" validate:"required,oneof=user_update user" example:"user_update"`
+	ID         string               `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes UserUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type UserUpdateRequest struct {
+	Data UserUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/dto/vocation_dto.go b/internal/transport/http/dto/vocation_dto.go
new file mode 100644
index 0000000..0c481b7
--- /dev/null
+++ b/internal/transport/http/dto/vocation_dto.go
@@ -0,0 +1,77 @@
+package dto
+
+// JSON:API Vocation DTOs
+
+type VocationAttributes struct {
+	Name      string `json:"name" example:"Pilot"`
+	SortKey   *int   `json:"sortkey" example:"1"`
+	Note      string `json:"note,omitempty" example:"Helicopter pilot vocation"`
+	IsActive  bool   `json:"is_active" example:"true"`
+	CreatedAt string `json:"created_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	CreatedBy string `json:"created_by" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	UpdatedAt string `json:"updated_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	UpdatedBy string `json:"updated_by" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	DeletedAt string `json:"deleted_at,omitempty" example:"2026-03-12T03:04:05Z"`
+	DeletedBy string `json:"deleted_by,omitempty" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+}
+
+type VocationResource struct {
+	Type       string             `json:"type" example:"vocation"`
+	ID         string             `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes VocationAttributes `json:"attributes"`
+}
+
+type VocationResponse struct {
+	Data VocationResource `json:"data"`
+}
+
+type VocationListResponse struct {
+	Data []VocationResource `json:"data"`
+	Meta struct {
+		PageNumber int   `json:"page_number" example:"1"`
+		PageSize   int   `json:"page_size" example:"20"`
+		Total      int64 `json:"total" example:"120"`
+	} `json:"meta"`
+}
+
+type VocationDataTableResponse struct {
+	Data []VocationResource `json:"data"`
+	Meta struct {
+		Draw            int   `json:"draw" example:"1"`
+		RecordsTotal    int64 `json:"records_total" example:"120"`
+		RecordsFiltered int64 `json:"records_filtered" example:"12"`
+	} `json:"meta"`
+}
+
+type VocationCreateAttributes struct {
+	Name     string  `json:"name" validate:"required" example:"Pilot"`
+	SortKey  *int    `json:"sortkey" example:"1"`
+	Note     *string `json:"note,omitempty" example:"Helicopter pilot vocation"`
+	IsActive *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type VocationCreateData struct {
+	Type       string                   `json:"type" validate:"required,oneof=vocation_create vocation" example:"vocation_create"`
+	Attributes VocationCreateAttributes `json:"attributes" validate:"required"`
+}
+
+type VocationCreateRequest struct {
+	Data VocationCreateData `json:"data" validate:"required"`
+}
+
+type VocationUpdateAttributes struct {
+	Name     *string `json:"name,omitempty" example:"Pilot"`
+	SortKey  NullInt `json:"sortkey,omitempty" swaggertype:"integer" example:"1"`
+	Note     *string `json:"note,omitempty" example:"Helicopter pilot vocation"`
+	IsActive *bool   `json:"is_active,omitempty" example:"true"`
+}
+
+type VocationUpdateData struct {
+	Type       string                   `json:"type" validate:"required,oneof=vocation_update vocation" example:"vocation_update"`
+	ID         string                   `json:"id" example:"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"`
+	Attributes VocationUpdateAttributes `json:"attributes" validate:"required"`
+}
+
+type VocationUpdateRequest struct {
+	Data VocationUpdateData `json:"data" validate:"required"`
+}
diff --git a/internal/transport/http/handlers/action_signoff_handler.go b/internal/transport/http/handlers/action_signoff_handler.go
new file mode 100644
index 0000000..9c7e622
--- /dev/null
+++ b/internal/transport/http/handlers/action_signoff_handler.go
@@ -0,0 +1,256 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	actionsignoff "wucher/internal/domain/action_signoff"
+	complaint "wucher/internal/domain/complaint"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+)
+
+// ActionSignoffHandler serves the corrective-action sign-off (sign/unsign) for a
+// helicopter — both complaint-linked and complaint-independent.
+type ActionSignoffHandler struct {
+	svc          actionsignoff.Service
+	complaintSvc actionSignoffComplaintLookup
+}
+
+type actionSignoffComplaintLookup interface {
+	GetByID(ctx context.Context, id []byte) (*complaint.Complaint, error)
+}
+
+func NewActionSignoffHandler(svc actionsignoff.Service) *ActionSignoffHandler {
+	return &ActionSignoffHandler{svc: svc}
+}
+
+// WithComplaintService wires the complaint lookup used to validate a complaint-linked
+// sign-off (complaint exists and has action_taken recorded).
+func (h *ActionSignoffHandler) WithComplaintService(svc actionSignoffComplaintLookup) *ActionSignoffHandler {
+	h.complaintSvc = svc
+	return h
+}
+
+func (h *ActionSignoffHandler) resource(ctx context.Context, row *actionsignoff.ActionSignoff) responsedto.ActionSignoffResource {
+	if row == nil {
+		return responsedto.ActionSignoffResource{}
+	}
+	id, _ := uuidv7.BytesToString(row.ID)
+	out := responsedto.ActionSignoffResource{
+		Type: "action_signoff",
+		ID:   id,
+		Attributes: responsedto.ActionSignoffAttributes{
+			HelicopterID: idString(row.HelicopterID),
+			FlightID:     idString(row.FlightID),
+			Signed:       row.IsSigned(),
+			SignedBy:     idString(row.SignedBy),
+		},
+	}
+	if row.SignedAt != nil {
+		v := row.SignedAt.UTC().Format(time.RFC3339)
+		out.Attributes.SignedAt = &v
+	}
+	if n := userctx.GetDisplayName(ctx, row.SignedBy); n != "" {
+		out.Attributes.SignedByName = &n
+	}
+	if s := userctx.GetShortName(ctx, row.SignedBy); s != "" {
+		out.Attributes.SignedByShort = &s
+	}
+	if !row.CreatedAt.IsZero() {
+		out.Attributes.CreatedAt = row.CreatedAt.UTC().Format(time.RFC3339)
+	}
+	if !row.UpdatedAt.IsZero() {
+		out.Attributes.UpdatedAt = row.UpdatedAt.UTC().Format(time.RFC3339)
+	}
+	return out
+}
+
+func actionSignoffHelicopterID(c *fiber.Ctx) ([]byte, *apperrorsx.AppError) {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("helicopter_id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrActionSignoffInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/helicopter_id"}
+		return nil, appErr
+	}
+	return id, nil
+}
+
+func actionSignoffFlightID(c *fiber.Ctx) ([]byte, *apperrorsx.AppError) {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("flight_id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrActionSignoffInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/flight_id"}
+		return nil, appErr
+	}
+	return id, nil
+}
+
+// actionSignoffBodyFlightID parses the REQUIRED flight_id from the sign body — the
+// flight the sign-off is attributed to (standalone) or performed in (complaint-linked).
+func actionSignoffBodyFlightID(req requestdto.ActionSignoffSignRequest) ([]byte, *apperrorsx.AppError) {
+	raw := ""
+	if req.Data.Attributes.FlightID != nil {
+		raw = strings.TrimSpace(*req.Data.Attributes.FlightID)
+	}
+	if raw == "" {
+		appErr := apperrorsx.New(apperrorsx.ErrActionSignoffInvalidUUID)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_id"}
+		return nil, appErr
+	}
+	id, err := uuidv7.ParseString(raw)
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrActionSignoffInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_id"}
+		return nil, appErr
+	}
+	return id, nil
+}
+
+// GetByHelicopter godoc
+// @Summary Get the current corrective-action sign-off for a helicopter
+// @Description Returns the fleet-level (complaint-independent) corrective-action sign-off state for a helicopter — `signed`, `signed_at`, `signed_by`. When none exists yet it returns an unsigned placeholder. A signed sign-off is what gates the EASA maintenance release.
+// @Tags Complaints - Sign Off
+// @Produce json
+// @Param flight_id path string true "Flight ID (UUIDv7)"
+// @Success 200 {object} responsedto.ActionSignoffResponse
+// @Router /api/v1/action-signoffs/get-by-flight/{flight_id} [get]
+func (h *ActionSignoffHandler) GetByFlight(c *fiber.Ctx) error {
+	flightID, aerr := actionSignoffFlightID(c)
+	if aerr != nil {
+		return apperrorsx.Write(c, aerr)
+	}
+	row, err := h.svc.GetByFlight(c.UserContext(), flightID)
+	if err != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrActionSignoffNotFound).WithCause(err))
+	}
+	if row == nil {
+		// No row yet: return an unsigned placeholder so the client can render.
+		return response.Write(c, fiber.StatusOK, responsedto.ActionSignoffResource{
+			Type: "action_signoff",
+			Attributes: responsedto.ActionSignoffAttributes{
+				FlightID: idString(flightID),
+				Signed:   false,
+			},
+		})
+	}
+	return response.Write(c, fiber.StatusOK, h.resource(c.UserContext(), row))
+}
+
+// Sign godoc
+// @Summary Toggle the corrective-action sign-off (per complaint or fleet-wide)
+// @Description Toggles the corrective-action sign-off for a helicopter. `sign` (optional, default true) chooses the direction: true signs, false unsigns. Send `complaint_id` to target a specific complaint's sign-off — signing it requires `action_taken` recorded (else 422 `ACTION_SIGNOFF_ACTION_REQUIRED`), and 404 `ACTION_SIGNOFF_COMPLAINT_NOT_FOUND` if the complaint does not exist. Omit `complaint_id` for a fleet-wide (complaint-independent) sign-off. A signed sign-off is what allows an EASA maintenance release to be created for the helicopter.
+// @Tags Complaints - Sign Off
+// @Accept json
+// @Produce json
+// @Param helicopter_id path string true "Helicopter ID (UUIDv7)"
+// @Param request body requestdto.ActionSignoffSignRequest false "Optional complaint_id + note"
+// @Success 200 {object} responsedto.ActionSignoffResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/action-signoffs/sign/{helicopter_id} [post]
+func (h *ActionSignoffHandler) Sign(c *fiber.Ctx) error {
+	helicopterID, err := actionSignoffHelicopterID(c)
+	if err != nil {
+		return apperrorsx.Write(c, err)
+	}
+	// Body is optional — the sign-off can be checked with nothing filled.
+	var req requestdto.ActionSignoffSignRequest
+	_ = c.BodyParser(&req)
+	actor := actorUserID(c)
+	// sign toggles the state: true (or omitted) signs, false unsigns.
+	signWanted := req.Data.Attributes.Sign == nil || *req.Data.Attributes.Sign
+
+	complaintIDRaw := ""
+	if req.Data.Attributes.ComplaintID != nil {
+		complaintIDRaw = strings.TrimSpace(*req.Data.Attributes.ComplaintID)
+	}
+
+	// Complaint-linked toggle: sign/unsign that complaint's corrective action.
+	if complaintIDRaw != "" {
+		complaintID, perr := uuidv7.ParseString(complaintIDRaw)
+		if perr != nil {
+			appErr := apperrorsx.New(apperrorsx.ErrActionSignoffInvalidUUID).WithCause(perr)
+			appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/complaint_id"}
+			return apperrorsx.Write(c, appErr)
+		}
+		if !signWanted {
+			row, serr := h.svc.UnsignByComplaint(c.UserContext(), complaintID)
+			if serr != nil {
+				return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrActionSignoffUnsignFailed).WithCause(serr))
+			}
+			if row == nil {
+				return response.Write(c, fiber.StatusOK, unsignedActionSignoffPlaceholder(helicopterID))
+			}
+			return response.Write(c, fiber.StatusOK, h.resource(c.UserContext(), row))
+		}
+		if h.complaintSvc == nil {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrActionSignoffSignFailed))
+		}
+		comp, cerr := h.complaintSvc.GetByID(c.UserContext(), complaintID)
+		if cerr != nil {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrActionSignoffSignFailed).WithCause(cerr))
+		}
+		if comp == nil {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrActionSignoffComplaintNotFound))
+		}
+		// The complaint's corrective action must be recorded before it can be signed off.
+		if comp.ActionTaken == nil || strings.TrimSpace(*comp.ActionTaken) == "" {
+			appErr := apperrorsx.New(apperrorsx.ErrActionSignoffActionRequired)
+			appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/complaint_id"}
+			return apperrorsx.Write(c, appErr)
+		}
+		flightID, ferr := actionSignoffBodyFlightID(req)
+		if ferr != nil {
+			return apperrorsx.Write(c, ferr)
+		}
+		row, serr := h.svc.SignForComplaint(c.UserContext(), complaintID, flightID, comp.HelicopterID, actor)
+		if serr != nil {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrActionSignoffSignFailed).WithCause(serr))
+		}
+		return response.Write(c, fiber.StatusOK, h.resource(c.UserContext(), row))
+	}
+
+	// Complaint-independent (fleet) toggle — scoped to a flight.
+	flightID, ferr := actionSignoffBodyFlightID(req)
+	if ferr != nil {
+		return apperrorsx.Write(c, ferr)
+	}
+	if !signWanted {
+		row, serr := h.svc.Unsign(c.UserContext(), flightID, actor)
+		if errors.Is(serr, actionsignoff.ErrNotFound) {
+			return response.Write(c, fiber.StatusOK, unsignedActionSignoffPlaceholder(helicopterID))
+		}
+		if serr != nil {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrActionSignoffUnsignFailed).WithCause(serr))
+		}
+		return response.Write(c, fiber.StatusOK, h.resource(c.UserContext(), row))
+	}
+	// Signing a fleet sign-off — this is what allows an EASA release for the flight.
+	row, serr := h.svc.Sign(c.UserContext(), flightID, helicopterID, actor)
+	if serr != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrActionSignoffSignFailed).WithCause(serr))
+	}
+	return response.Write(c, fiber.StatusOK, h.resource(c.UserContext(), row))
+}
+
+// unsignedActionSignoffPlaceholder renders an unsigned resource for a helicopter that
+// has no sign-off row (e.g. unsigning something that was never signed).
+func unsignedActionSignoffPlaceholder(helicopterID []byte) responsedto.ActionSignoffResource {
+	return responsedto.ActionSignoffResource{
+		Type: "action_signoff",
+		Attributes: responsedto.ActionSignoffAttributes{
+			HelicopterID: idString(helicopterID),
+			Signed:       false,
+		},
+	}
+}
diff --git a/internal/transport/http/handlers/action_signoff_handler_test.go b/internal/transport/http/handlers/action_signoff_handler_test.go
new file mode 100644
index 0000000..fba8740
--- /dev/null
+++ b/internal/transport/http/handlers/action_signoff_handler_test.go
@@ -0,0 +1,367 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	actionsignoff "wucher/internal/domain/action_signoff"
+	complaint "wucher/internal/domain/complaint"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type actionSignoffComplaintMock struct {
+	getByIDFn func(context.Context, []byte) (*complaint.Complaint, error)
+}
+
+func (m *actionSignoffComplaintMock) GetByID(ctx context.Context, id []byte) (*complaint.Complaint, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+type actionSignoffServiceMock struct {
+	getByHelicopterFn   func(context.Context, []byte) (*actionsignoff.ActionSignoff, error)
+	getByComplaintFn    func(context.Context, []byte) (*actionsignoff.ActionSignoff, error)
+	getByComplaintIDsFn func(context.Context, [][]byte) (map[string]*actionsignoff.ActionSignoff, error)
+	signFn              func(context.Context, []byte, []byte) (*actionsignoff.ActionSignoff, error)
+	signForComplaintFn  func(context.Context, []byte, []byte, []byte) (*actionsignoff.ActionSignoff, error)
+	unsignFn            func(context.Context, []byte, []byte) (*actionsignoff.ActionSignoff, error)
+	unsignByComplaintFn func(context.Context, []byte) (*actionsignoff.ActionSignoff, error)
+}
+
+func (m *actionSignoffServiceMock) GetByFlight(ctx context.Context, flightID []byte) (*actionsignoff.ActionSignoff, error) {
+	if m.getByHelicopterFn != nil {
+		return m.getByHelicopterFn(ctx, flightID)
+	}
+	return nil, nil
+}
+
+func (m *actionSignoffServiceMock) GetByComplaint(ctx context.Context, complaintID []byte) (*actionsignoff.ActionSignoff, error) {
+	if m.getByComplaintFn != nil {
+		return m.getByComplaintFn(ctx, complaintID)
+	}
+	return nil, nil
+}
+
+func (m *actionSignoffServiceMock) GetByComplaintIDs(ctx context.Context, complaintIDs [][]byte) (map[string]*actionsignoff.ActionSignoff, error) {
+	if m.getByComplaintIDsFn != nil {
+		return m.getByComplaintIDsFn(ctx, complaintIDs)
+	}
+	return map[string]*actionsignoff.ActionSignoff{}, nil
+}
+
+func (m *actionSignoffServiceMock) SignForComplaint(ctx context.Context, complaintID, _ []byte, helicopterID []byte, signer []byte) (*actionsignoff.ActionSignoff, error) {
+	if m.signForComplaintFn != nil {
+		return m.signForComplaintFn(ctx, complaintID, helicopterID, signer)
+	}
+	return nil, nil
+}
+
+func (m *actionSignoffServiceMock) Sign(ctx context.Context, _ []byte, helicopterID []byte, signer []byte) (*actionsignoff.ActionSignoff, error) {
+	if m.signFn != nil {
+		return m.signFn(ctx, helicopterID, signer)
+	}
+	return nil, nil
+}
+
+func (m *actionSignoffServiceMock) Unsign(ctx context.Context, helicopterID []byte, actor []byte) (*actionsignoff.ActionSignoff, error) {
+	if m.unsignFn != nil {
+		return m.unsignFn(ctx, helicopterID, actor)
+	}
+	return nil, nil
+}
+
+func (m *actionSignoffServiceMock) UnsignByComplaint(ctx context.Context, complaintID []byte) (*actionsignoff.ActionSignoff, error) {
+	if m.unsignByComplaintFn != nil {
+		return m.unsignByComplaintFn(ctx, complaintID)
+	}
+	return nil, nil
+}
+
+func newActionSignoffApp(h *ActionSignoffHandler) *fiber.App {
+	app := fiber.New()
+	app.Get("/api/v1/action-signoffs/get-by-flight/:flight_id", h.GetByFlight)
+	app.Post("/api/v1/action-signoffs/sign/:helicopter_id", h.Sign)
+	return app
+}
+
+func TestActionSignoffSign_ComplaintLinked_RequiresActionTaken(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	heliID := uuidv7.MustBytes()
+	heliStr, _ := uuidv7.BytesToString(heliID)
+
+	svc := &actionSignoffServiceMock{
+		signForComplaintFn: func(context.Context, []byte, []byte, []byte) (*actionsignoff.ActionSignoff, error) {
+			t.Fatal("must not sign a complaint whose action_taken is empty")
+			return nil, nil
+		},
+	}
+	comp := &actionSignoffComplaintMock{
+		getByIDFn: func(context.Context, []byte) (*complaint.Complaint, error) {
+			// Complaint exists but action_taken not recorded yet.
+			return &complaint.Complaint{ID: complaintID, HelicopterID: heliID}, nil
+		},
+	}
+	app := newActionSignoffApp(NewActionSignoffHandler(svc).WithComplaintService(comp))
+
+	body := `{"data":{"attributes":{"complaint_id":"` + complaintIDStr + `"}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/action-signoffs/sign/"+heliStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bodyBytes, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	var payload map[string]any
+	_ = json.Unmarshal(bodyBytes, &payload)
+	errs, _ := payload["errors"].([]any)
+	if len(errs) == 0 || errs[0].(map[string]any)["code"] != "ACTION_SIGNOFF_ACTION_REQUIRED" {
+		t.Fatalf("expected ACTION_SIGNOFF_ACTION_REQUIRED, got %s", string(bodyBytes))
+	}
+}
+
+func TestActionSignoffSign_ComplaintLinked_Signs(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	heliID := uuidv7.MustBytes()
+	heliStr, _ := uuidv7.BytesToString(heliID)
+	action := "tightened mount"
+
+	var signedComplaint []byte
+	svc := &actionSignoffServiceMock{
+		signForComplaintFn: func(_ context.Context, cid, hid []byte, _ []byte) (*actionsignoff.ActionSignoff, error) {
+			signedComplaint = cid
+			if string(hid) != string(heliID) {
+				t.Fatalf("unexpected helicopter id: %x", hid)
+			}
+			now := time.Now().UTC()
+			return &actionsignoff.ActionSignoff{HelicopterID: hid, ComplaintID: cid, SignedAt: &now}, nil
+		},
+	}
+	comp := &actionSignoffComplaintMock{
+		getByIDFn: func(context.Context, []byte) (*complaint.Complaint, error) {
+			return &complaint.Complaint{ID: complaintID, HelicopterID: heliID, ActionTaken: &action}, nil
+		},
+	}
+	app := newActionSignoffApp(NewActionSignoffHandler(svc).WithComplaintService(comp))
+
+	flightStr, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	body := `{"data":{"attributes":{"complaint_id":"` + complaintIDStr + `","flight_id":"` + flightStr + `"}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/action-signoffs/sign/"+heliStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		bodyBytes, _ := io.ReadAll(resp.Body)
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	if string(signedComplaint) != string(complaintID) {
+		t.Fatalf("expected SignForComplaint with complaint id, got %x", signedComplaint)
+	}
+}
+
+func TestActionSignoffSign_Standalone_NoComplaint(t *testing.T) {
+	heliID := uuidv7.MustBytes()
+	heliStr, _ := uuidv7.BytesToString(heliID)
+
+	var standaloneSigned bool
+	svc := &actionSignoffServiceMock{
+		signFn: func(_ context.Context, hid []byte, _ []byte) (*actionsignoff.ActionSignoff, error) {
+			standaloneSigned = true
+			now := time.Now().UTC()
+			return &actionsignoff.ActionSignoff{HelicopterID: hid, SignedAt: &now}, nil
+		},
+		signForComplaintFn: func(context.Context, []byte, []byte, []byte) (*actionsignoff.ActionSignoff, error) {
+			t.Fatal("standalone sign must not call SignForComplaint")
+			return nil, nil
+		},
+	}
+	app := newActionSignoffApp(NewActionSignoffHandler(svc))
+
+	// No complaint_id → standalone fleet sign-off (scoped to a flight).
+	flightStr, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	body := `{"data":{"attributes":{"flight_id":"` + flightStr + `"}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/action-signoffs/sign/"+heliStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusOK || !standaloneSigned {
+		t.Fatalf("expected standalone sign, status=%d signed=%v", resp.StatusCode, standaloneSigned)
+	}
+}
+
+func TestActionSignoffSign_ComplaintLinked_Unsign(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	heliID := uuidv7.MustBytes()
+	heliStr, _ := uuidv7.BytesToString(heliID)
+
+	var unsigned []byte
+	svc := &actionSignoffServiceMock{
+		unsignByComplaintFn: func(_ context.Context, cid []byte) (*actionsignoff.ActionSignoff, error) {
+			unsigned = cid
+			return &actionsignoff.ActionSignoff{HelicopterID: heliID, ComplaintID: cid}, nil // SignedAt nil → unsigned
+		},
+		signForComplaintFn: func(context.Context, []byte, []byte, []byte) (*actionsignoff.ActionSignoff, error) {
+			t.Fatal("sign:false must not call SignForComplaint")
+			return nil, nil
+		},
+	}
+	app := newActionSignoffApp(NewActionSignoffHandler(svc))
+
+	body := `{"data":{"attributes":{"sign":false,"complaint_id":"` + complaintIDStr + `"}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/action-signoffs/sign/"+heliStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bodyBytes, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	if string(unsigned) != string(complaintID) {
+		t.Fatalf("expected UnsignByComplaint with complaint id, got %x", unsigned)
+	}
+}
+
+func TestActionSignoffSign_Standalone_Unsign(t *testing.T) {
+	heliID := uuidv7.MustBytes()
+	heliStr, _ := uuidv7.BytesToString(heliID)
+	flightID := uuidv7.MustBytes()
+	flightStr, _ := uuidv7.BytesToString(flightID)
+
+	var unsignedFlight []byte
+	svc := &actionSignoffServiceMock{
+		unsignFn: func(_ context.Context, fid []byte, _ []byte) (*actionsignoff.ActionSignoff, error) {
+			unsignedFlight = fid
+			return &actionsignoff.ActionSignoff{HelicopterID: heliID}, nil // unsigned
+		},
+		signFn: func(context.Context, []byte, []byte) (*actionsignoff.ActionSignoff, error) {
+			t.Fatal("sign:false must not call Sign")
+			return nil, nil
+		},
+	}
+	app := newActionSignoffApp(NewActionSignoffHandler(svc))
+
+	body := `{"data":{"attributes":{"sign":false,"flight_id":"` + flightStr + `"}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/action-signoffs/sign/"+heliStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusOK || string(unsignedFlight) != string(flightID) {
+		b, _ := io.ReadAll(resp.Body)
+		t.Fatalf("expected standalone unsign, status=%d body=%s", resp.StatusCode, string(b))
+	}
+}
+
+// The response must be single-`data` enveloped (response.Write/jsonapi adds the
+// envelope). Wrapping the resource in ActionSignoffResponse here would double-nest
+// it as {"data":{"data":...}}, which the frontend mapper reads as unsigned —
+// leaving the SIGN checkbox unchecked even after a successful sign.
+func TestActionSignoffGetByHelicopterIsSingleDataEnvelope(t *testing.T) {
+	signedAt := time.Date(2026, 6, 30, 13, 18, 58, 0, time.UTC)
+	heliID := uuidv7.MustBytes()
+	heliStr, _ := uuidv7.BytesToString(heliID)
+
+	svc := &actionSignoffServiceMock{
+		getByHelicopterFn: func(_ context.Context, _ []byte) (*actionsignoff.ActionSignoff, error) {
+			return &actionsignoff.ActionSignoff{
+				ID:           uuidv7.MustBytes(),
+				HelicopterID: heliID,
+				SignedAt:     &signedAt,
+				SignedBy:     uuidv7.MustBytes(),
+			}, nil
+		},
+	}
+	app := newActionSignoffApp(NewActionSignoffHandler(svc))
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/action-signoffs/get-by-flight/"+heliStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(body))
+	}
+
+	var body map[string]any
+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+		t.Fatal(err)
+	}
+	data, ok := body["data"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected object at data, got %#v", body["data"])
+	}
+	// Regression guard: there must be no nested data.data.
+	if _, nested := data["data"]; nested {
+		t.Fatalf("response is double-wrapped (data.data present): %#v", data)
+	}
+	attrs, ok := data["attributes"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected data.attributes object, got %#v", data["attributes"])
+	}
+	if signed, _ := attrs["signed"].(bool); !signed {
+		t.Fatalf("expected attributes.signed=true, got %#v", attrs["signed"])
+	}
+}
+
+// Placeholder (no row yet) must also be single-`data` enveloped.
+func TestActionSignoffGetByHelicopterPlaceholderIsSingleDataEnvelope(t *testing.T) {
+	heliID := uuidv7.MustBytes()
+	heliStr, _ := uuidv7.BytesToString(heliID)
+
+	svc := &actionSignoffServiceMock{
+		getByHelicopterFn: func(_ context.Context, _ []byte) (*actionsignoff.ActionSignoff, error) {
+			return nil, nil
+		},
+	}
+	app := newActionSignoffApp(NewActionSignoffHandler(svc))
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/action-signoffs/get-by-flight/"+heliStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	var body map[string]any
+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+		t.Fatal(err)
+	}
+	data, ok := body["data"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected object at data, got %#v", body["data"])
+	}
+	if _, nested := data["data"]; nested {
+		t.Fatalf("placeholder is double-wrapped (data.data present): %#v", data)
+	}
+	attrs, ok := data["attributes"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected data.attributes object, got %#v", data["attributes"])
+	}
+	if signed, _ := attrs["signed"].(bool); signed {
+		t.Fatalf("expected placeholder attributes.signed=false, got %#v", attrs["signed"])
+	}
+}
diff --git a/internal/transport/http/handlers/after_flight_inspection_handler.go b/internal/transport/http/handlers/after_flight_inspection_handler.go
new file mode 100644
index 0000000..a28e5fa
--- /dev/null
+++ b/internal/transport/http/handlers/after_flight_inspection_handler.go
@@ -0,0 +1,215 @@
+package handlers
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type AfterFlightInspectionHandler struct {
+	svc       afterflightinspection.Service
+	flightSvc flightinspection.FlightInspectionService
+	validate  *validators.Validator
+}
+
+func NewAfterFlightInspectionHandler(svc afterflightinspection.Service, flightSvc flightinspection.FlightInspectionService) *AfterFlightInspectionHandler {
+	return &AfterFlightInspectionHandler{
+		svc:       svc,
+		flightSvc: flightSvc,
+		validate:  validators.New(),
+	}
+}
+
+// GetAfterFlightInspection godoc
+// @Summary Get after flight inspection by flight inspection ID
+// @Tags Flights - After Flight Inspection
+// @Accept json
+// @Produce json
+// @Param id path string true "Flight Inspection ID"
+// @Success 200 {object} dto.AfterFlightInspectionResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Public route disabled (managed via reserve AC flow).
+func (h *AfterFlightInspectionHandler) Get(c *fiber.Ctx) error {
+	flightInspectionID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		return writeAfterFlightAppError(c, apperrorsx.ErrAfterFlightInvalidID, &jsonapi.ErrorSource{Pointer: "/path/id"})
+	}
+
+	row, err := h.svc.GetByFlightInspectionID(c.Context(), flightInspectionID)
+	if err != nil {
+		return writeAfterFlightServiceError(c, err)
+	}
+
+	if row == nil {
+		return writeAfterFlightAppError(c, apperrorsx.ErrAfterFlightInspectionNotFound, nil)
+	}
+
+	flightInspectionData, err := h.getFlightInspectionResource(c.Context(), flightInspectionID)
+	if err != nil {
+		return writeAfterFlightServiceError(c, err)
+	}
+
+	resp := dto.AfterFlightInspectionResponse{
+		Data: dto.AfterFlightInspectionResource{
+			Type: "after_flight_inspection",
+			Attributes: dto.AfterFlightInspectionAttributes{
+				FlightInspection:          flightInspectionData,
+				OilEngineNR1Checked:       row.OilEngineNR1Checked,
+				OilEngineNR2Checked:       row.OilEngineNR2Checked,
+				HydraulicLHChecked:        row.HydraulicLHChecked,
+				HydraulicRHChecked:        row.HydraulicRHChecked,
+				OilTransmissionMGBChecked: row.OilTransmissionMGBChecked,
+				OilTransmissionIGBChecked: row.OilTransmissionIGBChecked,
+				OilTransmissionTGBChecked: row.OilTransmissionTGBChecked,
+				Note:                      row.Note,
+				CreatedAt:                 row.CreatedAt.Format(time.RFC3339),
+				UpdatedAt:                 row.UpdatedAt.Format(time.RFC3339),
+			},
+		},
+	}
+
+	idStr, _ := uuidv7.BytesToString(row.ID)
+	flightInspectionIDStr, _ := uuidv7.BytesToString(row.FlightInspectionID)
+	resp.Data.ID = idStr
+	resp.Data.Attributes.ID = idStr
+	resp.Data.Attributes.FlightInspectionID = flightInspectionIDStr
+
+	return c.JSON(resp)
+}
+
+// UpsertAfterFlightInspection godoc
+// @Summary Upsert after flight inspection by flight inspection ID
+// @Tags Flights - After Flight Inspection
+// @Accept json
+// @Produce json
+// @Param id path string true "Flight Inspection ID"
+// @Param request body dto.AfterFlightInspectionUpsertRequest true "JSON:API after flight inspection upsert request"
+// @Success 200 {object} dto.AfterFlightInspectionResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Public route disabled (managed via reserve AC flow).
+func (h *AfterFlightInspectionHandler) Upsert(c *fiber.Ctx) error {
+	flightInspectionID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		return writeAfterFlightAppError(c, apperrorsx.ErrAfterFlightInvalidID, &jsonapi.ErrorSource{Pointer: "/path/id"})
+	}
+
+	var req dto.AfterFlightInspectionUpsertRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAfterFlightAppError(c, apperrorsx.ErrAfterFlightInvalidJSON, nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	upsertReq := &afterflightinspection.UpsertRequest{
+		OilEngineNR1Checked:       req.Data.Attributes.OilEngineNR1Checked,
+		OilEngineNR2Checked:       req.Data.Attributes.OilEngineNR2Checked,
+		HydraulicLHChecked:        req.Data.Attributes.HydraulicLHChecked,
+		HydraulicRHChecked:        req.Data.Attributes.HydraulicRHChecked,
+		OilTransmissionMGBChecked: req.Data.Attributes.OilTransmissionMGBChecked,
+		OilTransmissionIGBChecked: req.Data.Attributes.OilTransmissionIGBChecked,
+		OilTransmissionTGBChecked: req.Data.Attributes.OilTransmissionTGBChecked,
+		Note:                      req.Data.Attributes.Note,
+	}
+
+	row, err := h.svc.Upsert(c.Context(), flightInspectionID, upsertReq)
+	if err != nil {
+		return writeAfterFlightServiceError(c, err)
+	}
+
+	flightInspectionData, err := h.getFlightInspectionResource(c.Context(), flightInspectionID)
+	if err != nil {
+		return writeAfterFlightServiceError(c, err)
+	}
+
+	idStr, _ := uuidv7.BytesToString(row.ID)
+	flightInspectionIDStr, _ := uuidv7.BytesToString(row.FlightInspectionID)
+	resp := dto.AfterFlightInspectionResponse{
+		Data: dto.AfterFlightInspectionResource{
+			Type: "after_flight_inspection",
+			ID:   idStr,
+			Attributes: dto.AfterFlightInspectionAttributes{
+				ID:                        idStr,
+				FlightInspectionID:        flightInspectionIDStr,
+				FlightInspection:          flightInspectionData,
+				OilEngineNR1Checked:       row.OilEngineNR1Checked,
+				OilEngineNR2Checked:       row.OilEngineNR2Checked,
+				HydraulicLHChecked:        row.HydraulicLHChecked,
+				HydraulicRHChecked:        row.HydraulicRHChecked,
+				OilTransmissionMGBChecked: row.OilTransmissionMGBChecked,
+				OilTransmissionIGBChecked: row.OilTransmissionIGBChecked,
+				OilTransmissionTGBChecked: row.OilTransmissionTGBChecked,
+				Note:                      row.Note,
+				CreatedAt:                 row.CreatedAt.Format(time.RFC3339),
+				UpdatedAt:                 row.UpdatedAt.Format(time.RFC3339),
+			},
+		},
+	}
+
+	return c.JSON(resp)
+}
+
+func (h *AfterFlightInspectionHandler) getFlightInspectionResource(ctx context.Context, flightInspectionID []byte) (*dto.FlightInspectionResource, error) {
+	if h.flightSvc == nil {
+		return nil, nil
+	}
+
+	row, err := h.flightSvc.GetByID(ctx, flightInspectionID)
+	if err != nil {
+		return nil, err
+	}
+	if row == nil {
+		return nil, nil
+	}
+
+	return afterFlightInspectionResource(row), nil
+}
+
+// writeAfterFlightAppError writes a known apperrorsx definition, optionally
+// attaching a JSON:API source pointer.
+func writeAfterFlightAppError(c *fiber.Ctx, def apperrorsx.Def, source *jsonapi.ErrorSource) error {
+	appErr := apperrorsx.New(def)
+	if source != nil {
+		appErr.Source = source
+	}
+	return apperrorsx.Write(c, appErr)
+}
+
+// writeAfterFlightServiceError translates a domain/service error into its
+// apperrorsx definition; unknown errors fall back to a generic internal error.
+func writeAfterFlightServiceError(c *fiber.Ctx, err error) error {
+	if mapped := apperrorsx.Translate(apperrorsx.ModuleAfterFlightInspection, err); mapped != nil && mapped.Code != apperrorsx.CodeInternalServerError {
+		return apperrorsx.Write(c, mapped)
+	}
+	return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrInternal))
+}
+
+func afterFlightInspectionResource(row *flightinspection.FlightInspection) *dto.FlightInspectionResource {
+	id, _ := uuidv7.BytesToString(row.ID)
+	return &dto.FlightInspectionResource{
+		Type: "flight_inspection",
+		ID:   id,
+		Attributes: dto.FlightInspectionAttributes{
+			InspectionDate: row.InspectionDate.UTC().Format("2006-01-02"),
+			Status:         row.Status,
+			CreatedAt:      row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:      uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:      row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:      uuidStringOrEmpty(row.UpdatedBy),
+		},
+	}
+}
diff --git a/internal/transport/http/handlers/air_rescuer_checklist_handler.go b/internal/transport/http/handlers/air_rescuer_checklist_handler.go
new file mode 100644
index 0000000..31c32d7
--- /dev/null
+++ b/internal/transport/http/handlers/air_rescuer_checklist_handler.go
@@ -0,0 +1,894 @@
+package handlers
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	airrescuechecklist "wucher/internal/domain/air_rescue_checklist"
+	basedomain "wucher/internal/domain/base"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type AirRescuerChecklistHandler struct {
+	svc      airrescuechecklist.Service
+	validate *validators.Validator
+}
+
+func NewAirRescuerChecklistHandler(svc airrescuechecklist.Service) *AirRescuerChecklistHandler {
+	return &AirRescuerChecklistHandler{svc: svc, validate: validators.New()}
+}
+
+// Create godoc
+// @Summary Create air rescuer checklist (bulk)
+// @Description Create one or more checklist headers for a single base.
+// @Description Request uses `base_id`.
+// @Description Each checklist can be created with or without initial `items`.
+// @Description `scope_code` accepts persisted codes and English aliases. Stored codes remain: `TA`, `MO`, `DI`, `MI`, `DO`, `FR`, `SA`, `SO`, `M10`, `M15`, `M20`, `M25`, `DS`.
+// @Description Example aliases: `DAILY` -> `TA`, `TU/TUE/TUESDAY` -> `DI`, `WE/WED/WEDNESDAY` -> `MI`, `TH/THU/THURSDAY` -> `DO`, `SU/SUN/SUNDAY` -> `SO`, `DEADLINE` -> `DS`.
+// @Description `CAT` is a virtual overview tab and is not allowed for create/update payloads.
+// @Description Duplicate `position` is allowed for both checklist headers and checklist items.
+// @Description Display order is stable: checklist headers `position ASC, title ASC`; checklist_items `position ASC, name ASC`.
+// @Description Request is transactional: if one checklist/item fails, the whole batch is rolled back.
+// @Tags Air Rescuer Checklist
+// @Accept json
+// @Produce json
+// @Param request body requestdto.AirRescuerChecklistCreateRequest true "Bulk checklist create payload"
+// @Success 201 {object} responsedto.AirRescuerChecklistBulkResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 409 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/air-rescuer-checklist/create [post]
+func (h *AirRescuerChecklistHandler) Create(c *fiber.Ctx) error {
+	var req requestdto.AirRescuerChecklistCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	baseID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.BaseID))
+	if err != nil {
+		return validationError(c, "/data/attributes/base_id", "base_id is invalid UUID")
+	}
+
+	baseRows, err := h.svc.ListHEMSBases(c.UserContext(), airrescuechecklist.HEMSBaseFilter{HEMSBaseID: baseID})
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Create failed", err, "")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if len(baseRows) == 0 {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "base not found",
+		}})
+	}
+
+	rows := make([]airrescuechecklist.ChecklistCreateInput, 0, len(req.Data.Attributes.Checklists))
+	actor := actorUserID(c)
+	for i := range req.Data.Attributes.Checklists {
+		scopeCode := airrescuechecklist.CanonicalizeAirRescuerChecklistScope(req.Data.Attributes.Checklists[i].ScopeCode)
+		if scopeCode == "" {
+			return validationError(c, fmt.Sprintf("/data/attributes/checklists/%d/scope_code", i), "scope_code is required")
+		}
+		if !airrescuechecklist.IsAirRescuerChecklistPersistedScope(scopeCode) {
+			return validationError(c, fmt.Sprintf("/data/attributes/checklists/%d/scope_code", i), "scope_code is invalid")
+		}
+
+		title := strings.TrimSpace(req.Data.Attributes.Checklists[i].Title)
+		if title == "" {
+			return validationError(c, fmt.Sprintf("/data/attributes/checklists/%d/title", i), "title is required")
+		}
+
+		position := checklistPositionOrZero(req.Data.Attributes.Checklists[i].Position)
+
+		items := make([]airrescuechecklist.AirRescuerChecklistItem, 0, len(req.Data.Attributes.Checklists[i].Items))
+		for j := range req.Data.Attributes.Checklists[i].Items {
+			itemName := strings.TrimSpace(req.Data.Attributes.Checklists[i].Items[j].Name)
+			if itemName == "" {
+				return validationError(c, fmt.Sprintf("/data/attributes/checklists/%d/items/%d/name", i, j), "name is required")
+			}
+			items = append(items, airrescuechecklist.AirRescuerChecklistItem{
+				Name:      itemName,
+				Position:  checklistPositionOrZero(req.Data.Attributes.Checklists[i].Items[j].Position),
+				CreatedBy: actor,
+				UpdatedBy: actor,
+			})
+		}
+
+		rows = append(rows, airrescuechecklist.ChecklistCreateInput{
+			Checklist: airrescuechecklist.AirRescuerChecklist{
+				HEMSBaseID: baseID,
+				ScopeCode:  scopeCode,
+				Title:      title,
+				Position:   position,
+				CreatedBy:  actor,
+				UpdatedBy:  actor,
+			},
+			Items: items,
+		})
+	}
+
+	if err := h.svc.CreateBulk(c.UserContext(), rows); err != nil {
+		status, errObj := buildServiceErrorObject("Create failed", err, "")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+
+	data := make([]responsedto.AirRescuerChecklistResource, 0, len(rows))
+	for i := range rows {
+		resource, found, err := h.loadChecklistResource(c.UserContext(), rows[i].Checklist.ID)
+		if err != nil {
+			status, errObj := buildServiceErrorObject("Create failed", err, "")
+			return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+		}
+		if found {
+			data = append(data, resource)
+		}
+	}
+
+	return response.Write(c, fiber.StatusCreated, data)
+}
+
+// Get godoc
+// @Summary Get air rescuer checklist by UUID
+// @Description Return one checklist detail by UUID.
+// @Description Includes checklist header, base info, and `items` (`checklist_items`).
+// @Tags Air Rescuer Checklist
+// @Produce json
+// @Param uuid path string true "Checklist UUID"
+// @Success 200 {object} responsedto.AirRescuerChecklistResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/air-rescuer-checklist/get/{uuid} [get]
+func (h *AirRescuerChecklistHandler) Get(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return validationError(c, "/path/uuid", "uuid is invalid UUID")
+	}
+	return h.respondChecklistByID(c, fiber.StatusOK, id)
+}
+
+// Update godoc
+// @Summary Update air rescuer checklist header and append new items
+// @Description Update checklist header fields (`scope_code`, `title`, `position`) and/or append `new_items`.
+// @Description `new_items` is append-only. Existing items are not updated/deleted by this endpoint.
+// @Description Item update/delete lifecycle must use dedicated item endpoints.
+// @Description `scope_code` accepts persisted codes and English aliases, but `CAT` (or `OVERVIEW`) is not allowed for update payload.
+// @Description Duplicate `position` is allowed.
+// @Description Request is transactional.
+// @Tags Air Rescuer Checklist
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Checklist UUID"
+// @Param request body requestdto.AirRescuerChecklistUpdateRequest true "Checklist update payload"
+// @Success 200 {object} responsedto.AirRescuerChecklistResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 409 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/air-rescuer-checklist/update/{uuid} [patch]
+func (h *AirRescuerChecklistHandler) Update(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return validationError(c, "/path/uuid", "uuid is invalid UUID")
+	}
+
+	var req requestdto.AirRescuerChecklistUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) != "" {
+		reqID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.ID))
+		if err != nil {
+			return validationError(c, "/data/id", "id is invalid UUID")
+		}
+		if !bytesEqualUUID(reqID, id) {
+			return validationError(c, "/data/id", "id does not match path uuid")
+		}
+	}
+
+	existing, err := h.svc.GetChecklistByID(c.UserContext(), id)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Update failed", err, "")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if existing == nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "air rescuer checklist not found",
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	hasHeaderUpdate := attrs.ScopeCode != nil || attrs.Title != nil || attrs.Position != nil
+	if attrs.NewItems != nil && len(attrs.NewItems) == 0 {
+		return validationError(c, "/data/attributes/new_items", "new_items must contain at least 1 item")
+	}
+	hasNewItems := len(attrs.NewItems) > 0
+	if !hasHeaderUpdate && !hasNewItems {
+		return validationError(c, "/data/attributes", "at least one attribute must be provided")
+	}
+
+	actor := actorUserID(c)
+
+	var row *airrescuechecklist.AirRescuerChecklist
+	if hasHeaderUpdate {
+		scopeCode := airrescuechecklist.CanonicalizeAirRescuerChecklistScope(existing.ScopeCode)
+		if attrs.ScopeCode != nil {
+			scopeCode = airrescuechecklist.CanonicalizeAirRescuerChecklistScope(*attrs.ScopeCode)
+			if scopeCode == "" {
+				return validationError(c, "/data/attributes/scope_code", "scope_code is required")
+			}
+			if !airrescuechecklist.IsAirRescuerChecklistPersistedScope(scopeCode) {
+				return validationError(c, "/data/attributes/scope_code", "scope_code is invalid")
+			}
+		}
+
+		title := strings.TrimSpace(existing.Title)
+		if attrs.Title != nil {
+			title = strings.TrimSpace(*attrs.Title)
+			if title == "" {
+				return validationError(c, "/data/attributes/title", "title is required")
+			}
+		}
+
+		position := existing.Position
+		if attrs.Position != nil {
+			position = checklistPositionOrDefault(attrs.Position)
+		}
+
+		row = &airrescuechecklist.AirRescuerChecklist{
+			ID:        id,
+			ScopeCode: scopeCode,
+			Title:     title,
+			Position:  position,
+			UpdatedBy: actor,
+		}
+	}
+
+	newItems := make([]airrescuechecklist.AirRescuerChecklistItem, 0, len(attrs.NewItems))
+	for i := range attrs.NewItems {
+		name := strings.TrimSpace(attrs.NewItems[i].Name)
+		if name == "" {
+			return validationError(c, fmt.Sprintf("/data/attributes/new_items/%d/name", i), "name is required")
+		}
+		newItems = append(newItems, airrescuechecklist.AirRescuerChecklistItem{
+			ChecklistID: id,
+			Name:        name,
+			Position:    checklistPositionOrZero(attrs.NewItems[i].Position),
+			CreatedBy:   actor,
+			UpdatedBy:   actor,
+		})
+	}
+
+	if err := h.svc.UpdateChecklistWithNewItems(c.UserContext(), row, newItems); err != nil {
+		status, errObj := buildServiceErrorObject("Update failed", err, "air rescuer checklist not found")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+
+	return h.respondChecklistByID(c, fiber.StatusOK, id)
+}
+
+// Delete godoc
+// @Summary Delete air rescuer checklist
+// @Description Delete one checklist header by UUID.
+// @Description Related checklist items are removed together following current implementation behavior.
+// @Tags Air Rescuer Checklist
+// @Produce json
+// @Param uuid path string true "Checklist UUID"
+// @Success 200 {object} responsedto.AirRescuerChecklistGroupedListResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/air-rescuer-checklist/delete/{uuid} [delete]
+func (h *AirRescuerChecklistHandler) Delete(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return validationError(c, "/path/uuid", "uuid is invalid UUID")
+	}
+	if err := h.svc.DeleteChecklist(c.UserContext(), id, actorUserID(c)); err != nil {
+		status, errObj := buildServiceErrorObject("Delete failed", err, "air rescuer checklist not found")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "air_rescuer_checklist_delete", Attributes: map[string]any{"deleted": true}})
+}
+
+// List godoc
+// @Summary List air rescuer checklist grouped by base
+// @Description Grouped by base and returned in `data[].attributes.bases`.
+// @Description Response includes `tabs[]` with default tab order: `CAT`, `TA`, `MO`, `DI`, `MI`, `DO`, `FR`, `SA`, `SO`, `M10`, `M15`, `M20`, `M25`, `DS`.
+// @Description `CAT` is a virtual overview tab (not persisted in DB).
+// @Description `CAT.groups[]` only includes non-empty persisted scopes and does not include `checklist_items`.
+// @Description Normal tabs are always present. Empty normal tabs are explicitly returned as `checklists: []`.
+// @Description Scope display names: `CAT=Category`, `TA=Daily`, `MO=Monday`, `DI=Tuesday`, `MI=Wednesday`, `DO=Thursday`, `FR=Friday`, `SA=Saturday`, `SO=Sunday`, `M10=M10`, `M15=M15`, `M20=M20`, `M25=M25`, `DS=Deadline`.
+// @Description Duplicate `position` is allowed. Display order is stable: checklist headers `position ASC, title ASC`; checklist_items `position ASC, name ASC`.
+// @Description Optional filters: `base_id`, `category_type` (`regular|hems`), `base_name`, `base_abbreviation`, `scope_code` (`CAT`/`OVERVIEW` or persisted scope / aliases).
+// @Tags Air Rescuer Checklist
+// @Produce json
+// @Param base_id query string false "Filter by base UUID"
+// @Param category_type query string false "Filter by base category" Enums(regular,hems)
+// @Param base_name query string false "Filter by base name (contains, case-insensitive)"
+// @Param base_abbreviation query string false "Filter by base abbreviation (contains, case-insensitive)"
+// @Param scope_code query string false "Filter by scope code. Allowed canonical: CAT, TA, MO, DI, MI, DO, FR, SA, SO, M10, M15, M20, M25, DS. English aliases are also accepted."
+// @Success 200 {object} responsedto.AirRescuerChecklistGroupedDataTableResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/air-rescuer-checklist/get-all [get]
+func (h *AirRescuerChecklistHandler) List(c *fiber.Ctx) error {
+	headerFilter, baseFilter, requestedScope, _ := parseAirRescuerChecklistFilters(c)
+	if c.Response().StatusCode() >= fiber.StatusBadRequest {
+		return nil
+	}
+
+	groups, err := h.loadChecklistGroups(c.UserContext(), headerFilter, baseFilter, requestedScope)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("List failed", err, "")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	meta := map[string]any{"total_bases": len(groups)}
+	return response.WriteWithMeta(c, fiber.StatusOK, groups, meta)
+}
+
+// ListDatatable godoc
+// @Summary List air rescuer checklist grouped by base (datatable)
+// @Description Datatable variant for grouped air rescuer checklist data.
+// @Description Semantic data is the same as `get-all`: grouped by base with `tabs[]`, virtual `CAT`, and normal tabs always present.
+// @Description `CAT.groups[]` only includes non-empty persisted scopes and does not include `checklist_items`.
+// @Description Empty normal tabs are explicitly returned as `checklists: []`.
+// @Description Scope display names: `CAT=Category`, `TA=Daily`, `MO=Monday`, `DI=Tuesday`, `MI=Wednesday`, `DO=Thursday`, `FR=Friday`, `SA=Saturday`, `SO=Sunday`, `M10=M10`, `M15=M15`, `M20=M20`, `M25=M25`, `DS=Deadline`.
+// @Description Duplicate `position` is allowed. Display order is stable: checklist headers `position ASC, title ASC`; checklist_items `position ASC, name ASC`.
+// @Description Optional filters: `base_id`, `category_type` (`regular|hems`), `base_name`, `base_abbreviation`, `scope_code`.
+// @Description Pagination/query controls: `page`, `size`, `limit`, `draw`.
+// @Tags Air Rescuer Checklist
+// @Produce json
+// @Param base_id query string false "Filter by base UUID"
+// @Param category_type query string false "Filter by base category" Enums(regular,hems)
+// @Param base_name query string false "Filter by base name (contains, case-insensitive)"
+// @Param base_abbreviation query string false "Filter by base abbreviation (contains, case-insensitive)"
+// @Param scope_code query string false "Filter by scope code. Allowed canonical: CAT, TA, MO, DI, MI, DO, FR, SA, SO, M10, M15, M20, M25, DS. English aliases are also accepted."
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20)"
+// @Param limit query int false "Page size override (max 100)"
+// @Param draw query int false "Datatable draw counter"
+// @Success 200 {object} responsedto.AirRescuerChecklistGroupedDataTableResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/air-rescuer-checklist/get-all/dt [get]
+func (h *AirRescuerChecklistHandler) ListDatatable(c *fiber.Ctx) error {
+	headerFilter, baseFilter, requestedScope, _ := parseAirRescuerChecklistFilters(c)
+	if c.Response().StatusCode() >= fiber.StatusBadRequest {
+		return nil
+	}
+
+	groups, err := h.loadChecklistGroups(c.UserContext(), headerFilter, baseFilter, requestedScope)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("List failed", err, "")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+
+	pagedGroups, total := paginateAirRescuerChecklistGroups(groups, start, length)
+	meta := map[string]any{"draw": draw, "records_total": total, "records_filtered": total}
+	return response.WriteWithMeta(c, fiber.StatusOK, pagedGroups, meta)
+}
+
+// CreateItem godoc
+// @Summary Create checklist items (bulk)
+// @Description Create one or more items for an existing checklist.
+// @Description Parent checklist is taken from path `uuid`.
+// @Description Duplicate `position` is allowed. Display order for checklist_items is `position ASC, name ASC`.
+// @Description Request is transactional: if one item fails, all item inserts in the batch are rolled back.
+// @Tags Air Rescuer Checklist
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Checklist UUID"
+// @Param request body requestdto.AirRescuerChecklistItemCreateRequest true "Bulk checklist item create payload"
+// @Success 201 {object} responsedto.AirRescuerChecklistItemBulkResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 409 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/air-rescuer-checklist/{uuid}/items/create [post]
+func (h *AirRescuerChecklistHandler) CreateItem(c *fiber.Ctx) error {
+	checklistID, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return validationError(c, "/path/uuid", "uuid is invalid UUID")
+	}
+
+	var req requestdto.AirRescuerChecklistItemCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	actor := actorUserID(c)
+	rows := make([]airrescuechecklist.AirRescuerChecklistItem, 0, len(req.Data.Attributes.Items))
+	for i := range req.Data.Attributes.Items {
+		name := strings.TrimSpace(req.Data.Attributes.Items[i].Name)
+		if name == "" {
+			return validationError(c, fmt.Sprintf("/data/attributes/items/%d/name", i), "name is required")
+		}
+		rows = append(rows, airrescuechecklist.AirRescuerChecklistItem{
+			ChecklistID: checklistID,
+			Name:        name,
+			Position:    checklistPositionOrZero(req.Data.Attributes.Items[i].Position),
+			CreatedBy:   actor,
+			UpdatedBy:   actor,
+		})
+	}
+
+	if err := h.svc.CreateChecklistItems(c.UserContext(), checklistID, rows); err != nil {
+		status, errObj := buildServiceErrorObject("Create failed", err, "air rescuer checklist not found")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+
+	data := make([]responsedto.AirRescuerChecklistItemData, 0, len(rows))
+	for i := range rows {
+		created, err := h.svc.GetChecklistItemByID(c.UserContext(), rows[i].ID)
+		if err != nil {
+			status, errObj := buildServiceErrorObject("Create failed", err, "")
+			return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+		}
+		if created == nil {
+			data = append(data, responsedto.AirRescuerChecklistItemData{
+				Type: "air_rescuer_checklist_item",
+				ID:   idString(rows[i].ID),
+				Attributes: responsedto.AirRescuerChecklistItemAttributes{
+					ChecklistID: idString(checklistID),
+					Name:        rows[i].Name,
+					Position:    rows[i].Position,
+				},
+			})
+			continue
+		}
+		data = append(data, airRescuerChecklistItemResponseData(*created))
+	}
+
+	return response.Write(c, fiber.StatusCreated, data)
+}
+
+// ReorderItems godoc
+// @Summary Reorder checklist items in one request
+// @Description Reorder one or more checklist items for the checklist in path `uuid`.
+// @Description Use this endpoint to swap or reorder positions with a single PIN validation.
+// @Description Duplicate `position` values remain allowed by domain rules.
+// @Description Request is transactional: if one item fails, all position updates are rolled back.
+// @Tags Air Rescuer Checklist
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Checklist UUID"
+// @Param request body requestdto.AirRescuerChecklistItemReorderRequest true "Checklist item reorder payload"
+// @Success 200 {object} responsedto.AirRescuerChecklistResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 409 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/air-rescuer-checklist/{uuid}/items/reorder [patch]
+func (h *AirRescuerChecklistHandler) ReorderItems(c *fiber.Ctx) error {
+	checklistID, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return validationError(c, "/path/uuid", "uuid is invalid UUID")
+	}
+
+	var req requestdto.AirRescuerChecklistItemReorderRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	seen := make(map[string]struct{}, len(req.Data.Attributes.Items))
+	rows := make([]airrescuechecklist.ChecklistItemReorderInput, 0, len(req.Data.Attributes.Items))
+	for i := range req.Data.Attributes.Items {
+		itemUUID := strings.TrimSpace(req.Data.Attributes.Items[i].ItemUUID)
+		itemID, err := uuidv7.ParseString(itemUUID)
+		if err != nil {
+			return validationError(c, fmt.Sprintf("/data/attributes/items/%d/item_uuid", i), "item_uuid is invalid UUID")
+		}
+
+		itemKey := idString(itemID)
+		if _, exists := seen[itemKey]; exists {
+			return validationError(c, fmt.Sprintf("/data/attributes/items/%d/item_uuid", i), "item_uuid must be unique")
+		}
+		seen[itemKey] = struct{}{}
+
+		rows = append(rows, airrescuechecklist.ChecklistItemReorderInput{
+			ID:       itemID,
+			Position: checklistPositionOrDefault(req.Data.Attributes.Items[i].Position),
+		})
+	}
+
+	if err := h.svc.ReorderChecklistItems(c.UserContext(), checklistID, rows, actorUserID(c)); err != nil {
+		status, errObj := buildServiceErrorObject("Reorder failed", err, "air rescuer checklist item not found")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+
+	return h.respondChecklistByID(c, fiber.StatusOK, checklistID)
+}
+
+// UpdateItem godoc
+// @Summary Update one checklist item
+// @Description Update one existing checklist item by `item_uuid`.
+// @Description This endpoint only affects the selected item.
+// @Description Duplicate `position` is allowed.
+// @Tags Air Rescuer Checklist
+// @Accept json
+// @Produce json
+// @Param item_uuid path string true "Checklist item UUID"
+// @Param request body requestdto.AirRescuerChecklistItemUpdateRequest true "Checklist item update payload"
+// @Success 200 {object} responsedto.AirRescuerChecklistItemResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 409 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/air-rescuer-checklist/items/update/{item_uuid} [patch]
+func (h *AirRescuerChecklistHandler) UpdateItem(c *fiber.Ctx) error {
+	itemID, err := uuidv7.ParseString(c.Params("item_uuid"))
+	if err != nil {
+		return validationError(c, "/path/item_uuid", "item_uuid is invalid UUID")
+	}
+
+	var req requestdto.AirRescuerChecklistItemUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if strings.TrimSpace(req.Data.ID) != "" {
+		reqID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.ID))
+		if err != nil {
+			return validationError(c, "/data/id", "id is invalid UUID")
+		}
+		if !bytesEqualUUID(reqID, itemID) {
+			return validationError(c, "/data/id", "id does not match path item_uuid")
+		}
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Name == nil && attrs.Position == nil {
+		return validationError(c, "/data/attributes", "at least one attribute must be provided")
+	}
+
+	existing, err := h.svc.GetChecklistItemByID(c.UserContext(), itemID)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Update failed", err, "")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if existing == nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "air rescuer checklist item not found",
+		}})
+	}
+
+	name := strings.TrimSpace(existing.Name)
+	if attrs.Name != nil {
+		name = strings.TrimSpace(*attrs.Name)
+		if name == "" {
+			return validationError(c, "/data/attributes/name", "name is required")
+		}
+	}
+
+	position := existing.Position
+	if attrs.Position != nil {
+		position = checklistPositionOrDefault(attrs.Position)
+	}
+
+	row := &airrescuechecklist.AirRescuerChecklistItem{
+		ID:        itemID,
+		Name:      name,
+		Position:  position,
+		UpdatedBy: actorUserID(c),
+	}
+	if err := h.svc.UpdateChecklistItem(c.UserContext(), row); err != nil {
+		status, errObj := buildServiceErrorObject("Update failed", err, "air rescuer checklist item not found")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+
+	updated, err := h.svc.GetChecklistItemByID(c.UserContext(), itemID)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Update failed", err, "")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if updated == nil {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "air rescuer checklist item not found",
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, airRescuerChecklistItemResponseData(*updated))
+}
+
+// DeleteItem godoc
+// @Summary Delete one checklist item
+// @Description Delete one existing checklist item by `item_uuid`.
+// @Tags Air Rescuer Checklist
+// @Produce json
+// @Param item_uuid path string true "Checklist item UUID"
+// @Success 200 {object} jsonapi.Document
+// @Failure 409 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/air-rescuer-checklist/items/delete/{item_uuid} [delete]
+func (h *AirRescuerChecklistHandler) DeleteItem(c *fiber.Ctx) error {
+	itemID, err := uuidv7.ParseString(c.Params("item_uuid"))
+	if err != nil {
+		return validationError(c, "/path/item_uuid", "item_uuid is invalid UUID")
+	}
+
+	if err := h.svc.DeleteChecklistItem(c.UserContext(), itemID, actorUserID(c)); err != nil {
+		status, errObj := buildServiceErrorObject("Delete failed", err, "air rescuer checklist item not found")
+		return writeAirRescuerChecklistErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "air_rescuer_checklist_item_delete", Attributes: map[string]any{"deleted": true}})
+}
+
+func (h *AirRescuerChecklistHandler) respondChecklistByID(c *fiber.Ctx, status int, id []byte) error {
+	resource, found, err := h.loadChecklistResource(c.UserContext(), id)
+	if err != nil {
+		statusCode, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeAirRescuerChecklistErrors(c, statusCode, []jsonapi.ErrorObject{errObj})
+	}
+	if !found {
+		return writeAirRescuerChecklistErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "air rescuer checklist not found",
+		}})
+	}
+	return response.Write(c, status, resource)
+}
+
+func (h *AirRescuerChecklistHandler) loadChecklistResource(ctx context.Context, id []byte) (responsedto.AirRescuerChecklistResource, bool, error) {
+	head, err := h.svc.GetChecklistByID(ctx, id)
+	if err != nil {
+		return responsedto.AirRescuerChecklistResource{}, false, err
+	}
+	if head == nil {
+		return responsedto.AirRescuerChecklistResource{}, false, nil
+	}
+	itemRows, err := h.svc.ListChecklistItemsByChecklistIDs(ctx, [][]byte{id})
+	if err != nil {
+		return responsedto.AirRescuerChecklistResource{}, false, err
+	}
+	return airRescuerChecklistResource(*head, itemRows), true, nil
+}
+
+func (h *AirRescuerChecklistHandler) loadChecklistGroups(
+	ctx context.Context,
+	headerFilter airrescuechecklist.ChecklistHeaderFilter,
+	baseFilter airrescuechecklist.HEMSBaseFilter,
+	requestedScope string,
+) ([]responsedto.AirRescuerChecklistBaseGroupResource, error) {
+	bases, err := h.svc.ListHEMSBases(ctx, baseFilter)
+	if err != nil {
+		return nil, err
+	}
+	headers, err := h.svc.ListChecklistHeaders(ctx, headerFilter)
+	if err != nil {
+		return nil, err
+	}
+	ids := make([][]byte, 0, len(headers))
+	for i := range headers {
+		ids = append(ids, headers[i].ID)
+	}
+	items, err := h.svc.ListChecklistItemsByChecklistIDs(ctx, ids)
+	if err != nil {
+		return nil, err
+	}
+	return buildAirRescuerChecklistGroups(bases, headers, items, requestedScope), nil
+}
+
+func parseAirRescuerChecklistFilters(c *fiber.Ctx) (airrescuechecklist.ChecklistHeaderFilter, airrescuechecklist.HEMSBaseFilter, string, error) {
+	headerFilter := airrescuechecklist.ChecklistHeaderFilter{}
+	baseFilter := airrescuechecklist.HEMSBaseFilter{}
+	requestedScope := ""
+
+	if categoryType, hasAnyCategory, ok := normalizeAirRescuerChecklistCategoryFromQuery(c); hasAnyCategory {
+		if !ok {
+			return headerFilter, baseFilter, requestedScope, validationError(c, "/query/category_type", "category_type/base_category must be one of: regular, hems")
+		}
+		headerFilter.CategoryType = categoryType
+		baseFilter.CategoryType = categoryType
+	}
+
+	baseRaw := strings.TrimSpace(c.Query("base_id"))
+	if baseRaw != "" {
+		baseID, err := uuidv7.ParseString(baseRaw)
+		if err != nil {
+			return headerFilter, baseFilter, requestedScope, validationError(c, "/query/base_id", "base_id is invalid UUID")
+		}
+		headerFilter.HEMSBaseID = baseID
+		baseFilter.HEMSBaseID = baseID
+	}
+
+	headerFilter.BaseName = strings.TrimSpace(c.Query("base_name"))
+	headerFilter.BaseAbbreviation = strings.TrimSpace(c.Query("base_abbreviation"))
+	baseFilter.BaseName = headerFilter.BaseName
+	baseFilter.BaseAbbreviation = headerFilter.BaseAbbreviation
+
+	scopeCode := airrescuechecklist.CanonicalizeAirRescuerChecklistScope(c.Query("scope_code"))
+	if scopeCode != "" {
+		if !airrescuechecklist.IsAirRescuerChecklistQueryScope(scopeCode) {
+			return headerFilter, baseFilter, requestedScope, validationError(c, "/query/scope_code", "scope_code is invalid")
+		}
+		requestedScope = scopeCode
+		if airrescuechecklist.IsAirRescuerChecklistPersistedScope(scopeCode) {
+			headerFilter.ScopeCode = scopeCode
+		}
+	}
+
+	return headerFilter, baseFilter, requestedScope, nil
+}
+
+func normalizeAirRescuerChecklistCategoryFromQuery(c *fiber.Ctx) (categoryType string, hasAny bool, ok bool) {
+	// Prefer new alias first, then backward-compatible query key.
+	candidates := []string{
+		strings.TrimSpace(c.Query("base_category")),
+		strings.TrimSpace(c.Query("category_type")),
+	}
+	for _, raw := range candidates {
+		if raw == "" {
+			continue
+		}
+		hasAny = true
+		if normalized, valid := basedomain.NormalizeCategoryType(raw); valid {
+			return normalized, true, true
+		}
+	}
+	return "", hasAny, false
+}
+
+func checklistPositionOrDefault(v *int) int {
+	if v == nil || *v <= 0 {
+		return 1
+	}
+	return *v
+}
+
+func checklistPositionOrZero(v *int) int {
+	if v == nil || *v <= 0 {
+		return 0
+	}
+	return *v
+}
+
+func writeAirRescuerChecklistErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		if strings.TrimSpace(e.Code) == "" || strings.TrimSpace(e.ErrorCode) == "" {
+			code, errorCode := inferAirRescuerChecklistErrorCode(status, e.Title, e.Detail)
+			if strings.TrimSpace(e.Code) == "" {
+				e.Code = code
+			}
+			if strings.TrimSpace(e.ErrorCode) == "" {
+				e.ErrorCode = errorCode
+			}
+		}
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferAirRescuerChecklistErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		switch {
+		case strings.Contains(lowerDetail, "item not found"):
+			return apperrorsx.CodeAirRescuerChecklistItemNotFound, apperrorsx.ErrAirRescuerChecklistItemNotFound.ErrorCode
+		case strings.Contains(lowerDetail, "base not found"):
+			return apperrorsx.CodeAirRescuerChecklistBaseNotFound, apperrorsx.ErrAirRescuerChecklistBaseNotFound.ErrorCode
+		default:
+			return apperrorsx.CodeAirRescuerChecklistNotFound, apperrorsx.ErrAirRescuerChecklistNotFound.ErrorCode
+		}
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "scope_code is required"):
+			return apperrorsx.CodeAirRescuerChecklistScopeRequired, apperrorsx.ErrAirRescuerChecklistScopeRequired.ErrorCode
+		case strings.Contains(lowerDetail, "scope_code is invalid"):
+			return apperrorsx.CodeAirRescuerChecklistScopeInvalid, apperrorsx.ErrAirRescuerChecklistScopeInvalid.ErrorCode
+		case strings.Contains(lowerDetail, "title is required"):
+			return apperrorsx.CodeAirRescuerChecklistTitleRequired, apperrorsx.ErrAirRescuerChecklistTitleRequired.ErrorCode
+		case strings.Contains(lowerDetail, "name is required"):
+			return apperrorsx.CodeAirRescuerChecklistNameRequired, apperrorsx.ErrAirRescuerChecklistNameRequired.ErrorCode
+		case strings.Contains(lowerDetail, "id does not match path"):
+			return apperrorsx.CodeAirRescuerChecklistIDMismatch, apperrorsx.ErrAirRescuerChecklistIDMismatch.ErrorCode
+		case strings.Contains(lowerDetail, "invalid uuid"):
+			return apperrorsx.CodeAirRescuerChecklistInvalidUUID, apperrorsx.ErrAirRescuerChecklistInvalidUUID.ErrorCode
+		default:
+			return apperrorsx.CodeAirRescuerChecklistValidationFailed, apperrorsx.ErrAirRescuerChecklistValidationFailed.ErrorCode
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.CodeAirRescuerChecklistInvalidJSON, apperrorsx.ErrAirRescuerChecklistInvalidJSON.ErrorCode
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.CodeAirRescuerChecklistCreateFailed, apperrorsx.ErrAirRescuerChecklistCreateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.CodeAirRescuerChecklistUpdateFailed, apperrorsx.ErrAirRescuerChecklistUpdateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.CodeAirRescuerChecklistDeleteFailed, apperrorsx.ErrAirRescuerChecklistDeleteFailed.ErrorCode
+		case strings.Contains(lowerTitle, "list failed"), strings.Contains(lowerTitle, "get failed"):
+			return apperrorsx.CodeAirRescuerChecklistListFailed, apperrorsx.ErrAirRescuerChecklistListFailed.ErrorCode
+		case strings.Contains(lowerTitle, "reorder failed"):
+			return apperrorsx.CodeAirRescuerChecklistReorderFailed, apperrorsx.ErrAirRescuerChecklistReorderFailed.ErrorCode
+		default:
+			return apperrorsx.CodeAirRescuerChecklistInvalidPayload, apperrorsx.ErrAirRescuerChecklistInvalidPayload.ErrorCode
+		}
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
+
+func validationError(c *fiber.Ctx, pointer, detail string) error {
+	return writeAirRescuerChecklistErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+		Status: "422",
+		Title:  "Validation error",
+		Detail: detail,
+		Source: &jsonapi.ErrorSource{Pointer: pointer},
+	}})
+}
diff --git a/internal/transport/http/handlers/air_rescuer_checklist_handler_test.go b/internal/transport/http/handlers/air_rescuer_checklist_handler_test.go
new file mode 100644
index 0000000..4c51bc3
--- /dev/null
+++ b/internal/transport/http/handlers/air_rescuer_checklist_handler_test.go
@@ -0,0 +1,1410 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	airrescuechecklist "wucher/internal/domain/air_rescue_checklist"
+	basedomain "wucher/internal/domain/base"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type checklistServiceMock struct {
+	listHEMSBasesRows []airrescuechecklist.HEMSBaseView
+	getChecklistRow   *airrescuechecklist.ChecklistHeaderView
+
+	createBulkCalled               bool
+	updateChecklistWithItemsCalled bool
+	reorderChecklistItemsCalled    bool
+}
+
+func (m *checklistServiceMock) CreateBulk(_ context.Context, _ []airrescuechecklist.ChecklistCreateInput) error {
+	m.createBulkCalled = true
+	return nil
+}
+
+func (m *checklistServiceMock) UpdateChecklist(_ context.Context, _ *airrescuechecklist.AirRescuerChecklist) error {
+	return nil
+}
+
+func (m *checklistServiceMock) UpdateChecklistWithNewItems(_ context.Context, _ *airrescuechecklist.AirRescuerChecklist, _ []airrescuechecklist.AirRescuerChecklistItem) error {
+	m.updateChecklistWithItemsCalled = true
+	return nil
+}
+
+func (m *checklistServiceMock) DeleteChecklist(_ context.Context, _ []byte, _ []byte) error {
+	return nil
+}
+
+func (m *checklistServiceMock) CreateChecklistItem(_ context.Context, _ *airrescuechecklist.AirRescuerChecklistItem) error {
+	return nil
+}
+
+func (m *checklistServiceMock) CreateChecklistItems(_ context.Context, _ []byte, _ []airrescuechecklist.AirRescuerChecklistItem) error {
+	return nil
+}
+
+func (m *checklistServiceMock) ReorderChecklistItems(_ context.Context, _ []byte, _ []airrescuechecklist.ChecklistItemReorderInput, _ []byte) error {
+	m.reorderChecklistItemsCalled = true
+	return nil
+}
+
+func (m *checklistServiceMock) UpdateChecklistItem(_ context.Context, _ *airrescuechecklist.AirRescuerChecklistItem) error {
+	return nil
+}
+
+func (m *checklistServiceMock) DeleteChecklistItem(_ context.Context, _ []byte, _ []byte) error {
+	return nil
+}
+
+func (m *checklistServiceMock) GetChecklistByID(_ context.Context, _ []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+	return m.getChecklistRow, nil
+}
+
+func (m *checklistServiceMock) GetChecklistItemByID(_ context.Context, _ []byte) (*airrescuechecklist.ChecklistItemView, error) {
+	return nil, nil
+}
+
+func (m *checklistServiceMock) ListChecklistHeaders(_ context.Context, _ airrescuechecklist.ChecklistHeaderFilter) ([]airrescuechecklist.ChecklistHeaderView, error) {
+	return nil, nil
+}
+
+func (m *checklistServiceMock) ListChecklistItemsByChecklistIDs(_ context.Context, _ [][]byte) ([]airrescuechecklist.ChecklistItemView, error) {
+	return nil, nil
+}
+
+func (m *checklistServiceMock) ListHEMSBases(_ context.Context, _ airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+	return m.listHEMSBasesRows, nil
+}
+
+func TestAirRescuerChecklistHandlerCreateRejectsCATScope(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	baseIDStr, _ := uuidv7.BytesToString(baseID)
+	svc := &checklistServiceMock{
+		listHEMSBasesRows: []airrescuechecklist.HEMSBaseView{{ID: baseID, BaseName: "Gallus 1 - Zurs Lech", BaseAbbreviation: "G1"}},
+	}
+	h := NewAirRescuerChecklistHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/air-rescuer-checklist/create", h.Create)
+
+	body := []byte(`{
+		"data": {
+			"type": "air_rescuer_checklist_create",
+			"attributes": {
+				"base_id": "` + baseIDStr + `",
+				"checklists": [
+					{"scope_code": "` + airrescuechecklist.AirRescuerChecklistScopeCAT + `", "title": "Overview Section"}
+				]
+			}
+		}
+	}`)
+
+	resp, respBody := doChecklistJSONRequest(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", body)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+	if !bytes.Contains(respBody, []byte("scope_code is invalid")) {
+		t.Fatalf("expected scope validation error, got %s", string(respBody))
+	}
+	if svc.createBulkCalled {
+		t.Fatalf("CreateBulk should not be called when CAT scope is rejected")
+	}
+}
+
+func TestAirRescuerChecklistHandlerUpdateRejectsCATScope(t *testing.T) {
+	checklistID := uuidv7.MustBytes()
+	checklistIDStr, _ := uuidv7.BytesToString(checklistID)
+	svc := &checklistServiceMock{
+		getChecklistRow: &airrescuechecklist.ChecklistHeaderView{
+			ID:        checklistID,
+			ScopeCode: airrescuechecklist.AirRescuerChecklistScopeTA,
+			Title:     "Cockpit Flugretter",
+			Position:  1,
+		},
+	}
+	h := NewAirRescuerChecklistHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/air-rescuer-checklist/update/:uuid", h.Update)
+
+	body := []byte(`{
+		"data": {
+			"type": "air_rescuer_checklist_update",
+			"id": "` + checklistIDStr + `",
+			"attributes": {
+				"scope_code": "` + airrescuechecklist.AirRescuerChecklistScopeCAT + `"
+			}
+		}
+	}`)
+
+	resp, respBody := doChecklistJSONRequest(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, body)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+	if !bytes.Contains(respBody, []byte("scope_code is invalid")) {
+		t.Fatalf("expected scope validation error, got %s", string(respBody))
+	}
+	if svc.updateChecklistWithItemsCalled {
+		t.Fatalf("UpdateChecklistWithNewItems should not be called when CAT scope is rejected")
+	}
+}
+
+func doChecklistJSONRequest(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+type checklistServiceFullMock struct {
+	createBulkFn                  func(context.Context, []airrescuechecklist.ChecklistCreateInput) error
+	updateChecklistFn             func(context.Context, *airrescuechecklist.AirRescuerChecklist) error
+	updateChecklistWithNewItemsFn func(context.Context, *airrescuechecklist.AirRescuerChecklist, []airrescuechecklist.AirRescuerChecklistItem) error
+	deleteChecklistFn             func(context.Context, []byte, []byte) error
+	createChecklistItemFn         func(context.Context, *airrescuechecklist.AirRescuerChecklistItem) error
+	createChecklistItemsFn        func(context.Context, []byte, []airrescuechecklist.AirRescuerChecklistItem) error
+	reorderChecklistItemsFn       func(context.Context, []byte, []airrescuechecklist.ChecklistItemReorderInput, []byte) error
+	updateChecklistItemFn         func(context.Context, *airrescuechecklist.AirRescuerChecklistItem) error
+	deleteChecklistItemFn         func(context.Context, []byte, []byte) error
+	getChecklistByIDFn            func(context.Context, []byte) (*airrescuechecklist.ChecklistHeaderView, error)
+	getChecklistItemByIDFn        func(context.Context, []byte) (*airrescuechecklist.ChecklistItemView, error)
+	listChecklistHeadersFn        func(context.Context, airrescuechecklist.ChecklistHeaderFilter) ([]airrescuechecklist.ChecklistHeaderView, error)
+	listChecklistItemsFn          func(context.Context, [][]byte) ([]airrescuechecklist.ChecklistItemView, error)
+	listHEMSBasesFn               func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error)
+
+	createBulkRows            []airrescuechecklist.ChecklistCreateInput
+	updateChecklistWithRow    *airrescuechecklist.AirRescuerChecklist
+	updateChecklistWithItems  []airrescuechecklist.AirRescuerChecklistItem
+	createChecklistItemsArgID []byte
+	createChecklistItemsRows  []airrescuechecklist.AirRescuerChecklistItem
+	reorderChecklistArgID     []byte
+	reorderChecklistRows      []airrescuechecklist.ChecklistItemReorderInput
+	listHeaderFilter          airrescuechecklist.ChecklistHeaderFilter
+	listBaseFilter            airrescuechecklist.HEMSBaseFilter
+}
+
+func (m *checklistServiceFullMock) CreateBulk(ctx context.Context, rows []airrescuechecklist.ChecklistCreateInput) error {
+	m.createBulkRows = append([]airrescuechecklist.ChecklistCreateInput(nil), rows...)
+	if m.createBulkFn != nil {
+		return m.createBulkFn(ctx, rows)
+	}
+	return nil
+}
+
+func (m *checklistServiceFullMock) UpdateChecklist(ctx context.Context, row *airrescuechecklist.AirRescuerChecklist) error {
+	if m.updateChecklistFn != nil {
+		return m.updateChecklistFn(ctx, row)
+	}
+	return nil
+}
+
+func (m *checklistServiceFullMock) UpdateChecklistWithNewItems(ctx context.Context, row *airrescuechecklist.AirRescuerChecklist, newItems []airrescuechecklist.AirRescuerChecklistItem) error {
+	m.updateChecklistWithRow = row
+	m.updateChecklistWithItems = append([]airrescuechecklist.AirRescuerChecklistItem(nil), newItems...)
+	if m.updateChecklistWithNewItemsFn != nil {
+		return m.updateChecklistWithNewItemsFn(ctx, row, newItems)
+	}
+	return nil
+}
+
+func (m *checklistServiceFullMock) DeleteChecklist(ctx context.Context, id []byte, deletedBy []byte) error {
+	if m.deleteChecklistFn != nil {
+		return m.deleteChecklistFn(ctx, id, deletedBy)
+	}
+	return nil
+}
+
+func (m *checklistServiceFullMock) CreateChecklistItem(ctx context.Context, row *airrescuechecklist.AirRescuerChecklistItem) error {
+	if m.createChecklistItemFn != nil {
+		return m.createChecklistItemFn(ctx, row)
+	}
+	return nil
+}
+
+func (m *checklistServiceFullMock) CreateChecklistItems(ctx context.Context, checklistID []byte, rows []airrescuechecklist.AirRescuerChecklistItem) error {
+	m.createChecklistItemsArgID = append([]byte(nil), checklistID...)
+	m.createChecklistItemsRows = append([]airrescuechecklist.AirRescuerChecklistItem(nil), rows...)
+	if m.createChecklistItemsFn != nil {
+		return m.createChecklistItemsFn(ctx, checklistID, rows)
+	}
+	return nil
+}
+
+func (m *checklistServiceFullMock) ReorderChecklistItems(ctx context.Context, checklistID []byte, rows []airrescuechecklist.ChecklistItemReorderInput, updatedBy []byte) error {
+	m.reorderChecklistArgID = append([]byte(nil), checklistID...)
+	m.reorderChecklistRows = append([]airrescuechecklist.ChecklistItemReorderInput(nil), rows...)
+	if m.reorderChecklistItemsFn != nil {
+		return m.reorderChecklistItemsFn(ctx, checklistID, rows, updatedBy)
+	}
+	return nil
+}
+
+func (m *checklistServiceFullMock) UpdateChecklistItem(ctx context.Context, row *airrescuechecklist.AirRescuerChecklistItem) error {
+	if m.updateChecklistItemFn != nil {
+		return m.updateChecklistItemFn(ctx, row)
+	}
+	return nil
+}
+
+func (m *checklistServiceFullMock) DeleteChecklistItem(ctx context.Context, id []byte, deletedBy []byte) error {
+	if m.deleteChecklistItemFn != nil {
+		return m.deleteChecklistItemFn(ctx, id, deletedBy)
+	}
+	return nil
+}
+
+func (m *checklistServiceFullMock) GetChecklistByID(ctx context.Context, id []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+	if m.getChecklistByIDFn != nil {
+		return m.getChecklistByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *checklistServiceFullMock) GetChecklistItemByID(ctx context.Context, id []byte) (*airrescuechecklist.ChecklistItemView, error) {
+	if m.getChecklistItemByIDFn != nil {
+		return m.getChecklistItemByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *checklistServiceFullMock) ListChecklistHeaders(ctx context.Context, filter airrescuechecklist.ChecklistHeaderFilter) ([]airrescuechecklist.ChecklistHeaderView, error) {
+	m.listHeaderFilter = filter
+	if m.listChecklistHeadersFn != nil {
+		return m.listChecklistHeadersFn(ctx, filter)
+	}
+	return []airrescuechecklist.ChecklistHeaderView{}, nil
+}
+
+func (m *checklistServiceFullMock) ListChecklistItemsByChecklistIDs(ctx context.Context, checklistIDs [][]byte) ([]airrescuechecklist.ChecklistItemView, error) {
+	if m.listChecklistItemsFn != nil {
+		return m.listChecklistItemsFn(ctx, checklistIDs)
+	}
+	return []airrescuechecklist.ChecklistItemView{}, nil
+}
+
+func (m *checklistServiceFullMock) ListHEMSBases(ctx context.Context, filter airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+	m.listBaseFilter = filter
+	if m.listHEMSBasesFn != nil {
+		return m.listHEMSBasesFn(ctx, filter)
+	}
+	return []airrescuechecklist.HEMSBaseView{}, nil
+}
+
+func newAirRescuerChecklistFullTestApp(h *AirRescuerChecklistHandler) *fiber.App {
+	app := fiber.New()
+	app.Post("/api/v1/air-rescuer-checklist/create", h.Create)
+	app.Get("/api/v1/air-rescuer-checklist/get/:uuid", h.Get)
+	app.Patch("/api/v1/air-rescuer-checklist/update/:uuid", h.Update)
+	app.Delete("/api/v1/air-rescuer-checklist/delete/:uuid", h.Delete)
+	app.Get("/api/v1/air-rescuer-checklist/get-all", h.List)
+	app.Get("/api/v1/air-rescuer-checklist/get-all/dt", h.ListDatatable)
+	app.Post("/api/v1/air-rescuer-checklist/:uuid/items/create", h.CreateItem)
+	app.Patch("/api/v1/air-rescuer-checklist/:uuid/items/reorder", h.ReorderItems)
+	app.Patch("/api/v1/air-rescuer-checklist/items/update/:item_uuid", h.UpdateItem)
+	app.Delete("/api/v1/air-rescuer-checklist/items/delete/:item_uuid", h.DeleteItem)
+	return app
+}
+
+func doChecklistJSONRequestFull(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	raw, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, raw
+}
+
+func mustUUIDStringChecklist(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestAirRescuerChecklistHandlerCreateBranches(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	baseIDStr := mustUUIDStringChecklist(t, baseID)
+
+	validBody := []byte(`{
+		"data": {
+			"type": "air_rescuer_checklist_create",
+			"attributes": {
+				"base_id": "` + baseIDStr + `",
+				"checklists": [{"scope_code":"TA","title":"Daily","position":1,"items":[{"name":"Battery","position":1}]}]
+			}
+		}
+	}`)
+
+	t.Run("invalid json", func(t *testing.T) {
+		h := NewAirRescuerChecklistHandler(&checklistServiceFullMock{})
+		app := newAirRescuerChecklistFullTestApp(h)
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation failed", func(t *testing.T) {
+		h := NewAirRescuerChecklistHandler(&checklistServiceFullMock{})
+		app := newAirRescuerChecklistFullTestApp(h)
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", []byte(`{"data":{"type":"wrong","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("base lookup error", func(t *testing.T) {
+		svc := &checklistServiceFullMock{
+			listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+				return nil, errors.New("db down")
+			},
+		}
+		h := NewAirRescuerChecklistHandler(svc)
+		app := newAirRescuerChecklistFullTestApp(h)
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", validBody)
+		if resp.StatusCode == http.StatusCreated {
+			t.Fatalf("expected create to fail")
+		}
+	})
+
+	t.Run("base not found", func(t *testing.T) {
+		h := NewAirRescuerChecklistHandler(&checklistServiceFullMock{})
+		app := newAirRescuerChecklistFullTestApp(h)
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", validBody)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create service error", func(t *testing.T) {
+		svc := &checklistServiceFullMock{
+			listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+				return []airrescuechecklist.HEMSBaseView{{ID: baseID, BaseName: "Gallus 1 - Zurs Lech", BaseAbbreviation: "G1"}}, nil
+			},
+			createBulkFn: func(context.Context, []airrescuechecklist.ChecklistCreateInput) error {
+				return errors.New("create failed")
+			},
+		}
+		h := NewAirRescuerChecklistHandler(svc)
+		app := newAirRescuerChecklistFullTestApp(h)
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", validBody)
+		if resp.StatusCode == http.StatusCreated {
+			t.Fatalf("expected create failure")
+		}
+	})
+
+	t.Run("load created resource error", func(t *testing.T) {
+		checklistID := uuidv7.MustBytes()
+		svc := &checklistServiceFullMock{
+			listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+				return []airrescuechecklist.HEMSBaseView{{ID: baseID, BaseName: "Gallus 1 - Zurs Lech", BaseAbbreviation: "G1"}}, nil
+			},
+			createBulkFn: func(_ context.Context, rows []airrescuechecklist.ChecklistCreateInput) error {
+				rows[0].Checklist.ID = append([]byte(nil), checklistID...)
+				return nil
+			},
+			getChecklistByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+				return nil, errors.New("load failed")
+			},
+		}
+		h := NewAirRescuerChecklistHandler(svc)
+		app := newAirRescuerChecklistFullTestApp(h)
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", validBody)
+		if resp.StatusCode == http.StatusCreated {
+			t.Fatalf("expected create response to fail when reloading resource fails")
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		checklistID := uuidv7.MustBytes()
+		itemID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+
+		svc := &checklistServiceFullMock{
+			listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+				return []airrescuechecklist.HEMSBaseView{{ID: baseID, BaseName: "Gallus 1 - Zurs Lech", BaseAbbreviation: "G1"}}, nil
+			},
+			createBulkFn: func(_ context.Context, rows []airrescuechecklist.ChecklistCreateInput) error {
+				rows[0].Checklist.ID = append([]byte(nil), checklistID...)
+				rows[0].Items[0].ID = append([]byte(nil), itemID...)
+				return nil
+			},
+			getChecklistByIDFn: func(_ context.Context, id []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+				return &airrescuechecklist.ChecklistHeaderView{
+					ID:               append([]byte(nil), id...),
+					HEMSBaseID:       append([]byte(nil), baseID...),
+					BaseName:         "Gallus 1 - Zurs Lech",
+					BaseAbbreviation: "G1",
+					ScopeCode:        airrescuechecklist.AirRescuerChecklistScopeTA,
+					Title:            "Daily",
+					Position:         1,
+					CreatedAt:        now,
+					UpdatedAt:        now,
+				}, nil
+			},
+			listChecklistItemsFn: func(context.Context, [][]byte) ([]airrescuechecklist.ChecklistItemView, error) {
+				return []airrescuechecklist.ChecklistItemView{{
+					ID:          append([]byte(nil), itemID...),
+					ChecklistID: append([]byte(nil), checklistID...),
+					Name:        "Battery",
+					Position:    1,
+					CreatedAt:   now,
+					UpdatedAt:   now,
+				}}, nil
+			},
+		}
+		h := NewAirRescuerChecklistHandler(svc)
+		app := newAirRescuerChecklistFullTestApp(h)
+		resp, body := doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", validBody)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d, body=%s", resp.StatusCode, string(body))
+		}
+		if len(svc.createBulkRows) != 1 {
+			t.Fatalf("expected create bulk called once")
+		}
+		if !bytes.Contains(body, []byte(`"type":"air_rescuer_checklist"`)) {
+			t.Fatalf("unexpected response body: %s", string(body))
+		}
+	})
+
+	t.Run("success with english scope alias", func(t *testing.T) {
+		checklistID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+
+		aliasBody := []byte(`{
+			"data": {
+				"type": "air_rescuer_checklist_create",
+				"attributes": {
+					"base_id": "` + baseIDStr + `",
+					"checklists": [{"scope_code":"TU","title":"Tuesday","position":1}]
+				}
+			}
+		}`)
+
+		svc := &checklistServiceFullMock{
+			listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+				return []airrescuechecklist.HEMSBaseView{{ID: baseID, BaseName: "Gallus 1 - Zurs Lech", BaseAbbreviation: "G1"}}, nil
+			},
+			createBulkFn: func(_ context.Context, rows []airrescuechecklist.ChecklistCreateInput) error {
+				rows[0].Checklist.ID = append([]byte(nil), checklistID...)
+				return nil
+			},
+			getChecklistByIDFn: func(_ context.Context, id []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+				return &airrescuechecklist.ChecklistHeaderView{
+					ID:               append([]byte(nil), id...),
+					HEMSBaseID:       append([]byte(nil), baseID...),
+					BaseName:         "Gallus 1 - Zurs Lech",
+					BaseAbbreviation: "G1",
+					ScopeCode:        airrescuechecklist.AirRescuerChecklistScopeDI,
+					Title:            "Tuesday",
+					Position:         1,
+					CreatedAt:        now,
+					UpdatedAt:        now,
+				}, nil
+			},
+			listChecklistItemsFn: func(context.Context, [][]byte) ([]airrescuechecklist.ChecklistItemView, error) {
+				return []airrescuechecklist.ChecklistItemView{}, nil
+			},
+		}
+
+		h := NewAirRescuerChecklistHandler(svc)
+		app := newAirRescuerChecklistFullTestApp(h)
+		resp, body := doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", aliasBody)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d, body=%s", resp.StatusCode, string(body))
+		}
+		if len(svc.createBulkRows) != 1 {
+			t.Fatalf("expected create bulk called once")
+		}
+		if svc.createBulkRows[0].Checklist.ScopeCode != airrescuechecklist.AirRescuerChecklistScopeDI {
+			t.Fatalf("expected TU alias to be normalized into DI, got %s", svc.createBulkRows[0].Checklist.ScopeCode)
+		}
+	})
+}
+
+func TestAirRescuerChecklistHandlerGetUpdateDeleteAndList(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	checklistID := uuidv7.MustBytes()
+	itemID := uuidv7.MustBytes()
+	now := time.Now().UTC()
+
+	base := airrescuechecklist.HEMSBaseView{ID: baseID, BaseName: "Gallus 1 - Zurs Lech", BaseAbbreviation: "G1", Position: 1}
+	header := airrescuechecklist.ChecklistHeaderView{
+		ID:               checklistID,
+		HEMSBaseID:       baseID,
+		BaseName:         base.BaseName,
+		BaseAbbreviation: base.BaseAbbreviation,
+		ScopeCode:        airrescuechecklist.AirRescuerChecklistScopeTA,
+		Title:            "Daily",
+		Position:         1,
+		CreatedAt:        now,
+		UpdatedAt:        now,
+	}
+	item := airrescuechecklist.ChecklistItemView{
+		ID:          itemID,
+		ChecklistID: checklistID,
+		Name:        "Battery",
+		Position:    1,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	}
+
+	svc := &checklistServiceFullMock{
+		getChecklistByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+			return &header, nil
+		},
+		listChecklistItemsFn: func(context.Context, [][]byte) ([]airrescuechecklist.ChecklistItemView, error) {
+			return []airrescuechecklist.ChecklistItemView{item}, nil
+		},
+		updateChecklistWithNewItemsFn: func(context.Context, *airrescuechecklist.AirRescuerChecklist, []airrescuechecklist.AirRescuerChecklistItem) error {
+			return nil
+		},
+		listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+			return []airrescuechecklist.HEMSBaseView{base}, nil
+		},
+		listChecklistHeadersFn: func(context.Context, airrescuechecklist.ChecklistHeaderFilter) ([]airrescuechecklist.ChecklistHeaderView, error) {
+			return []airrescuechecklist.ChecklistHeaderView{header}, nil
+		},
+	}
+
+	h := NewAirRescuerChecklistHandler(svc)
+	app := newAirRescuerChecklistFullTestApp(h)
+	checklistIDStr := mustUUIDStringChecklist(t, checklistID)
+
+	t.Run("get success", func(t *testing.T) {
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get/"+checklistIDStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update success with header and new_items", func(t *testing.T) {
+		body := []byte(`{
+			"data": {
+				"type": "air_rescuer_checklist_update",
+				"id": "` + checklistIDStr + `",
+				"attributes": {
+					"scope_code": "MO",
+					"title": "Monday",
+					"position": 2,
+					"new_items": [{"name":"Radio","position":2}]
+				}
+			}
+		}`)
+		resp, raw := doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(raw))
+		}
+		if svc.updateChecklistWithRow == nil || svc.updateChecklistWithRow.ScopeCode != "MO" {
+			t.Fatalf("expected header update row to be built")
+		}
+		if len(svc.updateChecklistWithItems) != 1 || svc.updateChecklistWithItems[0].Name != "Radio" {
+			t.Fatalf("expected new_items append payload")
+		}
+	})
+
+	t.Run("update success with english scope alias", func(t *testing.T) {
+		body := []byte(`{
+			"data": {
+				"type": "air_rescuer_checklist_update",
+				"id": "` + checklistIDStr + `",
+				"attributes": {
+					"scope_code": "THU"
+				}
+			}
+		}`)
+		resp, raw := doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(raw))
+		}
+		if svc.updateChecklistWithRow == nil || svc.updateChecklistWithRow.ScopeCode != airrescuechecklist.AirRescuerChecklistScopeDO {
+			t.Fatalf("expected THU alias to be normalized into DO")
+		}
+	})
+
+	t.Run("delete success", func(t *testing.T) {
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodDelete, "/api/v1/air-rescuer-checklist/delete/"+checklistIDStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("list success", func(t *testing.T) {
+		resp, raw := doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all?scope_code=CAT", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if !bytes.Contains(raw, []byte(`"total_bases"`)) {
+			t.Fatalf("expected grouped list meta")
+		}
+	})
+
+	t.Run("list success with persisted scope and base filter", func(t *testing.T) {
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all?base_id="+mustUUIDStringChecklist(t, baseID)+"&category_type=hems&scope_code=TA&base_name=gallus&base_abbreviation=g1", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if !bytes.Equal(svc.listHeaderFilter.HEMSBaseID, baseID) {
+			t.Fatalf("expected header filter base_id to be parsed")
+		}
+		if svc.listHeaderFilter.ScopeCode != airrescuechecklist.AirRescuerChecklistScopeTA {
+			t.Fatalf("expected persisted scope filter to be parsed")
+		}
+		if !bytes.Equal(svc.listBaseFilter.HEMSBaseID, baseID) {
+			t.Fatalf("expected base filter base_id to be parsed")
+		}
+		if svc.listHeaderFilter.CategoryType != basedomain.CategoryKeyHEMS || svc.listBaseFilter.CategoryType != basedomain.CategoryKeyHEMS {
+			t.Fatalf("expected category_type filter to be parsed as hems")
+		}
+	})
+
+	t.Run("list success with english scope alias", func(t *testing.T) {
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all?scope_code=SU", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.listHeaderFilter.ScopeCode != airrescuechecklist.AirRescuerChecklistScopeSO {
+			t.Fatalf("expected SU alias to be normalized into SO")
+		}
+	})
+
+	t.Run("list datatable success", func(t *testing.T) {
+		resp, raw := doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all/dt?page=0&size=0&limit=200&draw=7", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if !bytes.Contains(raw, []byte(`"records_total"`)) {
+			t.Fatalf("expected datatable meta")
+		}
+	})
+
+	t.Run("list invalid category_type", func(t *testing.T) {
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all?category_type=oops", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("list accepts base_category alias", func(t *testing.T) {
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all?base_category=hems", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.listHeaderFilter.CategoryType != basedomain.CategoryKeyHEMS || svc.listBaseFilter.CategoryType != basedomain.CategoryKeyHEMS {
+			t.Fatalf("expected base_category alias parsed as hems")
+		}
+	})
+}
+
+func TestAirRescuerChecklistHandlerItemEndpoints(t *testing.T) {
+	checklistID := uuidv7.MustBytes()
+	itemID := uuidv7.MustBytes()
+	now := time.Now().UTC()
+
+	itemIDStr := mustUUIDStringChecklist(t, itemID)
+	checklistIDStr := mustUUIDStringChecklist(t, checklistID)
+
+	createdItemCall := 0
+	svc := &checklistServiceFullMock{
+		createChecklistItemsFn: func(_ context.Context, _ []byte, rows []airrescuechecklist.AirRescuerChecklistItem) error {
+			for i := range rows {
+				rows[i].ID = uuidv7.MustBytes()
+			}
+			return nil
+		},
+		getChecklistItemByIDFn: func(_ context.Context, _ []byte) (*airrescuechecklist.ChecklistItemView, error) {
+			createdItemCall++
+			if createdItemCall == 1 {
+				return nil, nil
+			}
+			return &airrescuechecklist.ChecklistItemView{
+				ID:          itemID,
+				ChecklistID: checklistID,
+				Name:        "Battery",
+				Position:    1,
+				CreatedAt:   now,
+				UpdatedAt:   now,
+			}, nil
+		},
+		getChecklistByIDFn: func(_ context.Context, id []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+			return &airrescuechecklist.ChecklistHeaderView{
+				ID:               append([]byte(nil), id...),
+				HEMSBaseID:       uuidv7.MustBytes(),
+				BaseName:         "Gallus 1 - Zurs Lech",
+				BaseAbbreviation: "G1",
+				ScopeCode:        airrescuechecklist.AirRescuerChecklistScopeTA,
+				Title:            "Daily",
+				Position:         1,
+				CreatedAt:        now,
+				UpdatedAt:        now,
+			}, nil
+		},
+		listChecklistItemsFn: func(_ context.Context, _ [][]byte) ([]airrescuechecklist.ChecklistItemView, error) {
+			return []airrescuechecklist.ChecklistItemView{{
+				ID:          itemID,
+				ChecklistID: checklistID,
+				Name:        "Battery",
+				Position:    1,
+				CreatedAt:   now,
+				UpdatedAt:   now,
+			}}, nil
+		},
+		updateChecklistItemFn: func(context.Context, *airrescuechecklist.AirRescuerChecklistItem) error {
+			return nil
+		},
+	}
+	h := NewAirRescuerChecklistHandler(svc)
+	app := newAirRescuerChecklistFullTestApp(h)
+
+	t.Run("create item bulk success with fallback and fetched item", func(t *testing.T) {
+		body := []byte(`{
+			"data": {
+				"type": "air_rescuer_checklist_item_create",
+				"attributes": {
+					"items": [{"name":"Radio","position":2},{"name":"Battery","position":1}]
+				}
+			}
+		}`)
+		resp, raw := doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d body=%s", resp.StatusCode, string(raw))
+		}
+		if !bytes.Equal(svc.createChecklistItemsArgID, checklistID) {
+			t.Fatalf("expected checklist id taken from path")
+		}
+		if len(svc.createChecklistItemsRows) != 2 {
+			t.Fatalf("expected 2 item rows")
+		}
+	})
+
+	t.Run("update item success", func(t *testing.T) {
+		body := []byte(`{
+			"data": {
+				"type": "air_rescuer_checklist_item_update",
+				"id": "` + itemIDStr + `",
+				"attributes": {"name":"Battery Updated","position":3}
+			}
+		}`)
+		resp, raw := doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/"+itemIDStr, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(raw))
+		}
+	})
+
+	t.Run("reorder items success", func(t *testing.T) {
+		body := []byte(`{
+			"data": {
+				"type": "air_rescuer_checklist_item_reorder",
+				"attributes": {
+					"items": [
+						{"item_uuid":"` + itemIDStr + `","position":2},
+						{"item_uuid":"` + mustUUIDStringChecklist(t, uuidv7.MustBytes()) + `","position":1}
+					]
+				}
+			}
+		}`)
+		resp, raw := doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/reorder", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(raw))
+		}
+		if !bytes.Equal(svc.reorderChecklistArgID, checklistID) {
+			t.Fatalf("expected reorder checklist id from path")
+		}
+		if len(svc.reorderChecklistRows) != 2 {
+			t.Fatalf("expected 2 reorder rows")
+		}
+	})
+
+	t.Run("delete item success", func(t *testing.T) {
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodDelete, "/api/v1/air-rescuer-checklist/items/delete/"+itemIDStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAirRescuerChecklistHandlerErrorBranches(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	baseIDStr := mustUUIDStringChecklist(t, baseID)
+	checklistID := uuidv7.MustBytes()
+	checklistIDStr := mustUUIDStringChecklist(t, checklistID)
+	itemID := uuidv7.MustBytes()
+	itemIDStr := mustUUIDStringChecklist(t, itemID)
+
+	t.Run("get invalid uuid", func(t *testing.T) {
+		app := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(&checklistServiceFullMock{}))
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("get not found and service error", func(t *testing.T) {
+		svcNotFound := &checklistServiceFullMock{}
+		app := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcNotFound))
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get/"+checklistIDStr, nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+
+		svcErr := &checklistServiceFullMock{
+			getChecklistByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+				return nil, errors.New("boom")
+			},
+		}
+		app = newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcErr))
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get/"+checklistIDStr, nil)
+		if resp.StatusCode == http.StatusOK {
+			t.Fatalf("expected non-200 for service error")
+		}
+	})
+
+	t.Run("update validation and failure branches", func(t *testing.T) {
+		appGetErr := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(&checklistServiceFullMock{
+			getChecklistByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+				return nil, errors.New("get failed")
+			},
+		}))
+		resp, _ := doChecklistJSONRequestFull(t, appGetErr, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_update","attributes":{"title":"x"}}}`))
+		if resp.StatusCode == http.StatusOK {
+			t.Fatalf("expected update to fail when loading existing checklist fails")
+		}
+
+		appNotFound := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(&checklistServiceFullMock{}))
+		resp, _ = doChecklistJSONRequestFull(t, appNotFound, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_update","attributes":{"title":"x"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 when checklist not found, got %d", resp.StatusCode)
+		}
+
+		svc := &checklistServiceFullMock{
+			getChecklistByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+				return &airrescuechecklist.ChecklistHeaderView{ID: checklistID, ScopeCode: "TA", Title: "Old", Position: 1}, nil
+			},
+			updateChecklistWithNewItemsFn: func(context.Context, *airrescuechecklist.AirRescuerChecklist, []airrescuechecklist.AirRescuerChecklistItem) error {
+				return gorm.ErrRecordNotFound
+			},
+		}
+		app := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svc))
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for invalid path uuid, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 for invalid json, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{"data":{"type":"wrong","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for validator, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_update","id":"bad-uuid","attributes":{"title":"x"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for invalid body id, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_update","id":"`+mustUUIDStringChecklist(t, uuidv7.MustBytes())+`","attributes":{"title":"x"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for id mismatch, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_update","attributes":{"new_items":[]}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for empty new_items, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_update","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for empty attrs, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_update","attributes":{"scope_code":" "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for blank scope, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_update","attributes":{"scope_code":"CAT"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for CAT scope, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_update","attributes":{"title":" "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for blank title, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_update","attributes":{"new_items":[{"name":" "}]}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for blank new item name, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/update/"+checklistIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_update","attributes":{"title":"Updated"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 from service not found, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete branches", func(t *testing.T) {
+		svc := &checklistServiceFullMock{
+			deleteChecklistFn: func(context.Context, []byte, []byte) error { return gorm.ErrRecordNotFound },
+		}
+		app := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svc))
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodDelete, "/api/v1/air-rescuer-checklist/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid uuid, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodDelete, "/api/v1/air-rescuer-checklist/delete/"+checklistIDStr, nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 from delete service, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("list invalid filters and service failures", func(t *testing.T) {
+		svc := &checklistServiceFullMock{
+			listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+				return nil, errors.New("base list failed")
+			},
+		}
+		app := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svc))
+
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all?base_id=bad", nil)
+		if resp.StatusCode == http.StatusOK {
+			t.Fatalf("expected invalid base id filter to fail, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all?scope_code=bad", nil)
+		if resp.StatusCode == http.StatusOK {
+			t.Fatalf("expected invalid scope filter to fail, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all", nil)
+		if resp.StatusCode == http.StatusOK {
+			t.Fatalf("expected list service failure")
+		}
+	})
+
+	t.Run("list datatable error and length fallback", func(t *testing.T) {
+		svcErr := &checklistServiceFullMock{
+			listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+				return nil, errors.New("base list failed")
+			},
+		}
+		app := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcErr))
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all/dt?base_id=bad", nil)
+		if resp.StatusCode == http.StatusOK {
+			t.Fatalf("expected invalid datatable filter to fail")
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all/dt?scope_code=bad", nil)
+		if resp.StatusCode == http.StatusOK {
+			t.Fatalf("expected invalid datatable scope filter to fail")
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all/dt", nil)
+		if resp.StatusCode == http.StatusOK {
+			t.Fatalf("expected datatable list failure")
+		}
+
+		base := airrescuechecklist.HEMSBaseView{ID: baseID, BaseName: "Gallus 1", BaseAbbreviation: "G1", Position: 1}
+		svcOK := &checklistServiceFullMock{
+			listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+				return []airrescuechecklist.HEMSBaseView{base}, nil
+			},
+			listChecklistHeadersFn: func(context.Context, airrescuechecklist.ChecklistHeaderFilter) ([]airrescuechecklist.ChecklistHeaderView, error) {
+				return nil, nil
+			},
+		}
+		app = newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcOK))
+		resp, body := doChecklistJSONRequestFull(t, app, http.MethodGet, "/api/v1/air-rescuer-checklist/get-all/dt?page=0&limit=-1&size=0&draw=1", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 datatable fallback, got %d", resp.StatusCode)
+		}
+		if !bytes.Contains(body, []byte(`"records_filtered"`)) {
+			t.Fatalf("expected datatable meta in response")
+		}
+	})
+
+	t.Run("create item failures", func(t *testing.T) {
+		app := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(&checklistServiceFullMock{}))
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/not-uuid/items/create", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid path uuid, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/create", []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid json, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/create", []byte(`{"data":{"type":"wrong","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 validator, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/create", []byte(`{"data":{"type":"air_rescuer_checklist_item_create","attributes":{"items":[]}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 empty items, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/create", []byte(`{"data":{"type":"air_rescuer_checklist_item_create","attributes":{"items":[{"name":" "}]}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 blank name, got %d", resp.StatusCode)
+		}
+
+		svcErr := &checklistServiceFullMock{
+			createChecklistItemsFn: func(context.Context, []byte, []airrescuechecklist.AirRescuerChecklistItem) error {
+				return gorm.ErrRecordNotFound
+			},
+		}
+		app = newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcErr))
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/create", []byte(`{"data":{"type":"air_rescuer_checklist_item_create","attributes":{"items":[{"name":"ok"}]}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 create items service error, got %d", resp.StatusCode)
+		}
+
+		svcGetErr := &checklistServiceFullMock{
+			createChecklistItemsFn: func(_ context.Context, _ []byte, rows []airrescuechecklist.AirRescuerChecklistItem) error {
+				rows[0].ID = uuidv7.MustBytes()
+				return nil
+			},
+			getChecklistItemByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistItemView, error) {
+				return nil, errors.New("get item failed")
+			},
+		}
+		app = newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcGetErr))
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/create", []byte(`{"data":{"type":"air_rescuer_checklist_item_create","attributes":{"items":[{"name":"ok"}]}}}`))
+		if resp.StatusCode == http.StatusCreated {
+			t.Fatalf("expected failure when loading created item fails")
+		}
+	})
+
+	t.Run("update item failure branches", func(t *testing.T) {
+		app := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(&checklistServiceFullMock{}))
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid path item_uuid, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/"+itemIDStr, []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid json, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/"+itemIDStr, []byte(`{"data":{"type":"wrong","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 validator, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/"+itemIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_item_update","id":"bad","attributes":{"name":"x"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid body id, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/"+itemIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_item_update","id":"`+mustUUIDStringChecklist(t, uuidv7.MustBytes())+`","attributes":{"name":"x"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 id mismatch, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/"+itemIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_item_update","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 empty attrs, got %d", resp.StatusCode)
+		}
+
+		svcGetErr := &checklistServiceFullMock{
+			getChecklistItemByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistItemView, error) {
+				return nil, errors.New("boom")
+			},
+		}
+		app = newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcGetErr))
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/"+itemIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_item_update","attributes":{"name":"x"}}}`))
+		if resp.StatusCode == http.StatusOK {
+			t.Fatalf("expected non-200 when get existing fails")
+		}
+
+		svcNotFound := &checklistServiceFullMock{}
+		app = newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcNotFound))
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/"+itemIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_item_update","attributes":{"name":"x"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 item not found, got %d", resp.StatusCode)
+		}
+
+		svcBlankName := &checklistServiceFullMock{
+			getChecklistItemByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistItemView, error) {
+				return &airrescuechecklist.ChecklistItemView{ID: itemID, Name: "Old", Position: 1}, nil
+			},
+		}
+		app = newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcBlankName))
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/"+itemIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_item_update","attributes":{"name":" "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 blank update name, got %d", resp.StatusCode)
+		}
+
+		svcUpdateErr := &checklistServiceFullMock{
+			getChecklistItemByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistItemView, error) {
+				return &airrescuechecklist.ChecklistItemView{ID: itemID, Name: "Old", Position: 1}, nil
+			},
+			updateChecklistItemFn: func(context.Context, *airrescuechecklist.AirRescuerChecklistItem) error {
+				return gorm.ErrRecordNotFound
+			},
+		}
+		app = newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcUpdateErr))
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/"+itemIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_item_update","attributes":{"name":"ok"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 update item service error, got %d", resp.StatusCode)
+		}
+
+		callCount := 0
+		svcUpdatedMissing := &checklistServiceFullMock{
+			getChecklistItemByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistItemView, error) {
+				callCount++
+				if callCount == 1 {
+					return &airrescuechecklist.ChecklistItemView{ID: itemID, Name: "Old", Position: 1}, nil
+				}
+				return nil, nil
+			},
+		}
+		app = newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcUpdatedMissing))
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/"+itemIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_item_update","attributes":{"name":"ok"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 when updated row missing, got %d", resp.StatusCode)
+		}
+
+		callCount = 0
+		svcUpdatedGetErr := &checklistServiceFullMock{
+			getChecklistItemByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistItemView, error) {
+				callCount++
+				if callCount == 1 {
+					return &airrescuechecklist.ChecklistItemView{ID: itemID, Name: "Old", Position: 1}, nil
+				}
+				return nil, errors.New("refresh failed")
+			},
+		}
+		app = newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcUpdatedGetErr))
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/items/update/"+itemIDStr, []byte(`{"data":{"type":"air_rescuer_checklist_item_update","attributes":{"name":"ok"}}}`))
+		if resp.StatusCode == http.StatusOK {
+			t.Fatalf("expected failure when reloading updated item fails")
+		}
+	})
+
+	t.Run("reorder item failure branches", func(t *testing.T) {
+		app := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(&checklistServiceFullMock{}))
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/not-uuid/items/reorder", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid path uuid, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/reorder", []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid json, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/reorder", []byte(`{"data":{"type":"wrong","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 validator, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/reorder", []byte(`{
+			"data":{"type":"air_rescuer_checklist_item_reorder","attributes":{"items":[{"item_uuid":"bad-uuid","position":1}]}}
+		}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid item_uuid, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/reorder", []byte(`{
+			"data":{"type":"air_rescuer_checklist_item_reorder","attributes":{"items":[{"item_uuid":"`+itemIDStr+`","position":1},{"item_uuid":"`+itemIDStr+`","position":2}]}}
+		}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 duplicate item_uuid, got %d", resp.StatusCode)
+		}
+
+		svcNotFound := &checklistServiceFullMock{
+			reorderChecklistItemsFn: func(context.Context, []byte, []airrescuechecklist.ChecklistItemReorderInput, []byte) error {
+				return gorm.ErrRecordNotFound
+			},
+		}
+		app = newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svcNotFound))
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPatch, "/api/v1/air-rescuer-checklist/"+checklistIDStr+"/items/reorder", []byte(`{
+			"data":{"type":"air_rescuer_checklist_item_reorder","attributes":{"items":[{"item_uuid":"`+itemIDStr+`","position":1}]}}
+		}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 reorder service error, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete item branches", func(t *testing.T) {
+		svc := &checklistServiceFullMock{
+			deleteChecklistItemFn: func(context.Context, []byte, []byte) error { return gorm.ErrRecordNotFound },
+		}
+		app := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svc))
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodDelete, "/api/v1/air-rescuer-checklist/items/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid item uuid, got %d", resp.StatusCode)
+		}
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodDelete, "/api/v1/air-rescuer-checklist/items/delete/"+itemIDStr, nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 item delete service error, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create parse-level validation branches", func(t *testing.T) {
+		svc := &checklistServiceFullMock{
+			listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+				return []airrescuechecklist.HEMSBaseView{{ID: baseID, BaseName: "Gallus 1", BaseAbbreviation: "G1"}}, nil
+			},
+		}
+		app := newAirRescuerChecklistFullTestApp(NewAirRescuerChecklistHandler(svc))
+
+		resp, _ := doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", []byte(`{
+			"data":{"type":"air_rescuer_checklist_create","attributes":{"base_id":"bad","checklists":[{"scope_code":"TA","title":"x"}]}}
+		}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid base uuid, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", []byte(`{
+			"data":{"type":"air_rescuer_checklist_create","attributes":{"base_id":"`+baseIDStr+`","checklists":[]}}
+		}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 empty checklists, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", []byte(`{
+			"data":{"type":"air_rescuer_checklist_create","attributes":{"base_id":"`+baseIDStr+`","checklists":[{"scope_code":" ","title":"x"}]}}
+		}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 blank scope, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", []byte(`{
+			"data":{"type":"air_rescuer_checklist_create","attributes":{"base_id":"`+baseIDStr+`","checklists":[{"scope_code":"CAT","title":"x"}]}}
+		}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid scope, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", []byte(`{
+			"data":{"type":"air_rescuer_checklist_create","attributes":{"base_id":"`+baseIDStr+`","checklists":[{"scope_code":"TA","title":" "}]}}
+		}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 blank title, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doChecklistJSONRequestFull(t, app, http.MethodPost, "/api/v1/air-rescuer-checklist/create", []byte(`{
+			"data":{"type":"air_rescuer_checklist_create","attributes":{"base_id":"`+baseIDStr+`","checklists":[{"scope_code":"TA","title":"ok","items":[{"name":" "}]}]}}
+		}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 blank item name, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAirRescuerChecklistHandlerLoadHelpersAndPosition(t *testing.T) {
+	checklistID := uuidv7.MustBytes()
+	baseID := uuidv7.MustBytes()
+	now := time.Now().UTC()
+
+	t.Run("load checklist resource branches", func(t *testing.T) {
+		h := NewAirRescuerChecklistHandler(&checklistServiceFullMock{
+			getChecklistByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+				return nil, errors.New("get failed")
+			},
+		})
+		_, found, err := h.loadChecklistResource(context.Background(), checklistID)
+		if err == nil || found {
+			t.Fatalf("expected get error branch")
+		}
+
+		h = NewAirRescuerChecklistHandler(&checklistServiceFullMock{})
+		_, found, err = h.loadChecklistResource(context.Background(), checklistID)
+		if err != nil || found {
+			t.Fatalf("expected not found branch")
+		}
+
+		h = NewAirRescuerChecklistHandler(&checklistServiceFullMock{
+			getChecklistByIDFn: func(context.Context, []byte) (*airrescuechecklist.ChecklistHeaderView, error) {
+				return &airrescuechecklist.ChecklistHeaderView{ID: checklistID, HEMSBaseID: baseID, ScopeCode: "TA", Title: "Daily", CreatedAt: now, UpdatedAt: now}, nil
+			},
+			listChecklistItemsFn: func(context.Context, [][]byte) ([]airrescuechecklist.ChecklistItemView, error) {
+				return nil, errors.New("items failed")
+			},
+		})
+		_, found, err = h.loadChecklistResource(context.Background(), checklistID)
+		if err == nil || found {
+			t.Fatalf("expected item list error branch")
+		}
+	})
+
+	t.Run("load checklist groups branches", func(t *testing.T) {
+		h := NewAirRescuerChecklistHandler(&checklistServiceFullMock{
+			listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+				return nil, errors.New("base failed")
+			},
+		})
+		_, err := h.loadChecklistGroups(context.Background(), airrescuechecklist.ChecklistHeaderFilter{}, airrescuechecklist.HEMSBaseFilter{}, "")
+		if err == nil {
+			t.Fatalf("expected base error")
+		}
+
+		h = NewAirRescuerChecklistHandler(&checklistServiceFullMock{
+			listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+				return []airrescuechecklist.HEMSBaseView{{ID: baseID, BaseName: "Base", BaseAbbreviation: "B1"}}, nil
+			},
+			listChecklistHeadersFn: func(context.Context, airrescuechecklist.ChecklistHeaderFilter) ([]airrescuechecklist.ChecklistHeaderView, error) {
+				return nil, errors.New("header failed")
+			},
+		})
+		_, err = h.loadChecklistGroups(context.Background(), airrescuechecklist.ChecklistHeaderFilter{}, airrescuechecklist.HEMSBaseFilter{}, "")
+		if err == nil {
+			t.Fatalf("expected header error")
+		}
+
+		h = NewAirRescuerChecklistHandler(&checklistServiceFullMock{
+			listHEMSBasesFn: func(context.Context, airrescuechecklist.HEMSBaseFilter) ([]airrescuechecklist.HEMSBaseView, error) {
+				return []airrescuechecklist.HEMSBaseView{{ID: baseID, BaseName: "Base", BaseAbbreviation: "B1"}}, nil
+			},
+			listChecklistHeadersFn: func(context.Context, airrescuechecklist.ChecklistHeaderFilter) ([]airrescuechecklist.ChecklistHeaderView, error) {
+				return []airrescuechecklist.ChecklistHeaderView{{ID: checklistID, HEMSBaseID: baseID, ScopeCode: "TA", Title: "Daily", Position: 1, CreatedAt: now, UpdatedAt: now}}, nil
+			},
+			listChecklistItemsFn: func(context.Context, [][]byte) ([]airrescuechecklist.ChecklistItemView, error) {
+				return nil, errors.New("items failed")
+			},
+		})
+		_, err = h.loadChecklistGroups(context.Background(), airrescuechecklist.ChecklistHeaderFilter{}, airrescuechecklist.HEMSBaseFilter{}, "")
+		if err == nil {
+			t.Fatalf("expected item list error")
+		}
+	})
+
+	if checklistPositionOrDefault(nil) != 1 {
+		t.Fatalf("nil position should default to 1")
+	}
+	zero := 0
+	if checklistPositionOrDefault(&zero) != 1 {
+		t.Fatalf("zero position should default to 1")
+	}
+	two := 2
+	if checklistPositionOrDefault(&two) != 2 {
+		t.Fatalf("positive position should be preserved")
+	}
+}
diff --git a/internal/transport/http/handlers/air_rescuer_checklist_mapper.go b/internal/transport/http/handlers/air_rescuer_checklist_mapper.go
new file mode 100644
index 0000000..6c82bb7
--- /dev/null
+++ b/internal/transport/http/handlers/air_rescuer_checklist_mapper.go
@@ -0,0 +1,215 @@
+package handlers
+
+import (
+	"strings"
+	"time"
+
+	airrescuechecklist "wucher/internal/domain/air_rescue_checklist"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+)
+
+func airRescuerChecklistResource(header airrescuechecklist.ChecklistHeaderView, items []airrescuechecklist.ChecklistItemView) responsedto.AirRescuerChecklistResource {
+	return responsedto.AirRescuerChecklistResource{
+		Type: "air_rescuer_checklist",
+		ID:   idString(header.ID),
+		Attributes: responsedto.AirRescuerChecklistAttributes{
+			Bases: shareddto.AirRescuerChecklistBaseInfo{
+				ID:               idString(header.HEMSBaseID),
+				BaseName:         strings.TrimSpace(header.BaseName),
+				BaseAbbreviation: strings.TrimSpace(header.BaseAbbreviation),
+				BaseCategory:     strings.TrimSpace(header.BaseCategory),
+			},
+			ScopeCode:   airrescuechecklist.AirRescuerChecklistScopeCodeEN(header.ScopeCode),
+			ScopeCodeDe: airrescuechecklist.AirRescuerChecklistScopeCodeDE(header.ScopeCode),
+			Title:       strings.TrimSpace(header.Title),
+			Position:    header.Position,
+			Items:       mapAirRescuerChecklistItemResources(items),
+			CreatedBy:   uuidStringOrEmpty(header.CreatedBy),
+			CreatedAt:   header.CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedAt:   header.UpdatedAt.UTC().Format(time.RFC3339),
+		},
+	}
+}
+
+func airRescuerChecklistItemResponseData(item airrescuechecklist.ChecklistItemView) responsedto.AirRescuerChecklistItemData {
+	return responsedto.AirRescuerChecklistItemData{
+		Type: "air_rescuer_checklist_item",
+		ID:   idString(item.ID),
+		Attributes: responsedto.AirRescuerChecklistItemAttributes{
+			ChecklistID: idString(item.ChecklistID),
+			Name:        strings.TrimSpace(item.Name),
+			Position:    item.Position,
+			CreatedBy:   uuidStringOrEmpty(item.CreatedBy),
+			CreatedAt:   item.CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedAt:   item.UpdatedAt.UTC().Format(time.RFC3339),
+		},
+	}
+}
+
+func buildAirRescuerChecklistGroups(
+	bases []airrescuechecklist.HEMSBaseView,
+	headers []airrescuechecklist.ChecklistHeaderView,
+	items []airrescuechecklist.ChecklistItemView,
+	requestedScope string,
+) []responsedto.AirRescuerChecklistBaseGroupResource {
+	itemsByChecklist := make(map[string][]airrescuechecklist.ChecklistItemView, len(items))
+	for i := range items {
+		key := idString(items[i].ChecklistID)
+		itemsByChecklist[key] = append(itemsByChecklist[key], items[i])
+	}
+
+	headersByBaseScope := make(map[string]map[string][]airrescuechecklist.ChecklistHeaderView)
+	for i := range headers {
+		baseKey := idString(headers[i].HEMSBaseID)
+		scopeCode := strings.ToUpper(strings.TrimSpace(headers[i].ScopeCode))
+		if headersByBaseScope[baseKey] == nil {
+			headersByBaseScope[baseKey] = map[string][]airrescuechecklist.ChecklistHeaderView{}
+		}
+		headersByBaseScope[baseKey][scopeCode] = append(headersByBaseScope[baseKey][scopeCode], headers[i])
+	}
+
+	groups := make([]responsedto.AirRescuerChecklistBaseGroupResource, 0, len(bases))
+	for i := range bases {
+		baseID := idString(bases[i].ID)
+		groups = append(groups, responsedto.AirRescuerChecklistBaseGroupResource{
+			Type: "air_rescuer_checklist_group",
+			ID:   "base-" + baseID,
+			Attributes: responsedto.AirRescuerChecklistBaseGroupAttributes{
+				Bases: shareddto.AirRescuerChecklistBaseInfo{
+					ID:               baseID,
+					BaseName:         strings.TrimSpace(bases[i].BaseName),
+					BaseAbbreviation: strings.TrimSpace(bases[i].BaseAbbreviation),
+					BaseCategory:     strings.TrimSpace(bases[i].BaseCategory),
+				},
+				Tabs: buildAirRescuerChecklistTabs(headersByBaseScope[baseID], itemsByChecklist, requestedScope),
+			},
+		})
+	}
+
+	return groups
+}
+
+func buildAirRescuerChecklistTabs(
+	headersByScope map[string][]airrescuechecklist.ChecklistHeaderView,
+	itemsByChecklist map[string][]airrescuechecklist.ChecklistItemView,
+	requestedScope string,
+) []responsedto.AirRescuerChecklistTabResource {
+	normalizedScope := strings.ToUpper(strings.TrimSpace(requestedScope))
+	if normalizedScope == airrescuechecklist.AirRescuerChecklistScopeCAT {
+		return []responsedto.AirRescuerChecklistTabResource{
+			buildAirRescuerChecklistCATTab(headersByScope),
+		}
+	}
+	if airrescuechecklist.IsAirRescuerChecklistPersistedScope(normalizedScope) {
+		return []responsedto.AirRescuerChecklistTabResource{
+			buildAirRescuerChecklistDetailTab(headersByScope, itemsByChecklist, normalizedScope),
+		}
+	}
+
+	scopeOrder := airrescuechecklist.AirRescuerChecklistPersistedScopeOrder()
+	tabs := make([]responsedto.AirRescuerChecklistTabResource, 0, 1+len(scopeOrder))
+	tabs = append(tabs, buildAirRescuerChecklistCATTab(headersByScope))
+	for i := range scopeOrder {
+		tabs = append(tabs, buildAirRescuerChecklistDetailTab(headersByScope, itemsByChecklist, scopeOrder[i]))
+	}
+	return tabs
+}
+
+func buildAirRescuerChecklistCATTab(
+	headersByScope map[string][]airrescuechecklist.ChecklistHeaderView,
+) responsedto.AirRescuerChecklistTabResource {
+	scopeOrder := airrescuechecklist.AirRescuerChecklistPersistedScopeOrder()
+	groups := make([]responsedto.AirRescuerChecklistCATGroup, 0, len(scopeOrder))
+	for i := range scopeOrder {
+		scopeCode := scopeOrder[i]
+		headers := headersByScope[scopeCode]
+		if len(headers) == 0 {
+			continue
+		}
+		checklists := make([]responsedto.AirRescuerChecklistCATChecklistSummary, 0, len(headers))
+		for j := range headers {
+			checklists = append(checklists, responsedto.AirRescuerChecklistCATChecklistSummary{
+				ID:        idString(headers[j].ID),
+				Title:     strings.TrimSpace(headers[j].Title),
+				Position:  headers[j].Position,
+				CreatedBy: uuidStringOrEmpty(headers[j].CreatedBy),
+				CreatedAt: headers[j].CreatedAt.UTC().Format(time.RFC3339),
+				UpdatedAt: headers[j].UpdatedAt.UTC().Format(time.RFC3339),
+			})
+		}
+		groups = append(groups, responsedto.AirRescuerChecklistCATGroup{
+			ScopeCode:       airrescuechecklist.AirRescuerChecklistScopeCodeEN(scopeCode),
+			ScopeCodeDe:     airrescuechecklist.AirRescuerChecklistScopeCodeDE(scopeCode),
+			ScopeCodeName:   airrescuechecklist.AirRescuerChecklistScopeDisplayName(scopeCode),
+			ScopeCodeNameDe: airrescuechecklist.AirRescuerChecklistScopeDisplayNameDE(scopeCode),
+			Checklists:      checklists,
+		})
+	}
+	return responsedto.AirRescuerChecklistTabResource{
+		ScopeCode:       airrescuechecklist.AirRescuerChecklistScopeCodeEN(airrescuechecklist.AirRescuerChecklistScopeCAT),
+		ScopeCodeDe:     airrescuechecklist.AirRescuerChecklistScopeCodeDE(airrescuechecklist.AirRescuerChecklistScopeCAT),
+		ScopeCodeName:   airrescuechecklist.AirRescuerChecklistScopeDisplayName(airrescuechecklist.AirRescuerChecklistScopeCAT),
+		ScopeCodeNameDe: airrescuechecklist.AirRescuerChecklistScopeDisplayNameDE(airrescuechecklist.AirRescuerChecklistScopeCAT),
+		Groups:          groups,
+	}
+}
+
+func buildAirRescuerChecklistDetailTab(
+	headersByScope map[string][]airrescuechecklist.ChecklistHeaderView,
+	itemsByChecklist map[string][]airrescuechecklist.ChecklistItemView,
+	scopeCode string,
+) responsedto.AirRescuerChecklistTabResource {
+	headers := headersByScope[scopeCode]
+	checklists := make([]responsedto.AirRescuerChecklistTabChecklistDetail, 0, len(headers))
+	for i := range headers {
+		key := idString(headers[i].ID)
+		checklists = append(checklists, responsedto.AirRescuerChecklistTabChecklistDetail{
+			ID:             idString(headers[i].ID),
+			Title:          strings.TrimSpace(headers[i].Title),
+			Position:       headers[i].Position,
+			ChecklistItems: mapAirRescuerChecklistItemResources(itemsByChecklist[key]),
+			CreatedBy:      uuidStringOrEmpty(headers[i].CreatedBy),
+			CreatedAt:      headers[i].CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedAt:      headers[i].UpdatedAt.UTC().Format(time.RFC3339),
+		})
+	}
+	return responsedto.AirRescuerChecklistTabResource{
+		ScopeCode:       airrescuechecklist.AirRescuerChecklistScopeCodeEN(scopeCode),
+		ScopeCodeDe:     airrescuechecklist.AirRescuerChecklistScopeCodeDE(scopeCode),
+		ScopeCodeName:   airrescuechecklist.AirRescuerChecklistScopeDisplayName(scopeCode),
+		ScopeCodeNameDe: airrescuechecklist.AirRescuerChecklistScopeDisplayNameDE(scopeCode),
+		Checklists:      &checklists,
+	}
+}
+
+func mapAirRescuerChecklistItemResources(items []airrescuechecklist.ChecklistItemView) []responsedto.AirRescuerChecklistItemResource {
+	out := make([]responsedto.AirRescuerChecklistItemResource, 0, len(items))
+	for i := range items {
+		out = append(out, responsedto.AirRescuerChecklistItemResource{
+			ID:        idString(items[i].ID),
+			Name:      strings.TrimSpace(items[i].Name),
+			Position:  items[i].Position,
+			CreatedBy: uuidStringOrEmpty(items[i].CreatedBy),
+			CreatedAt: items[i].CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedAt: items[i].UpdatedAt.UTC().Format(time.RFC3339),
+		})
+	}
+	return out
+}
+
+func paginateAirRescuerChecklistGroups(
+	groups []responsedto.AirRescuerChecklistBaseGroupResource,
+	start,
+	length int,
+) ([]responsedto.AirRescuerChecklistBaseGroupResource, int) {
+	total := len(groups)
+	if start > total {
+		start = total
+	}
+	end := start + length
+	if end > total {
+		end = total
+	}
+	return groups[start:end], total
+}
diff --git a/internal/transport/http/handlers/air_rescuer_checklist_mapper_test.go b/internal/transport/http/handlers/air_rescuer_checklist_mapper_test.go
new file mode 100644
index 0000000..cf63432
--- /dev/null
+++ b/internal/transport/http/handlers/air_rescuer_checklist_mapper_test.go
@@ -0,0 +1,359 @@
+package handlers
+
+import (
+	"bytes"
+	"encoding/json"
+	"testing"
+	"time"
+
+	airrescuechecklist "wucher/internal/domain/air_rescue_checklist"
+	"wucher/internal/shared/pkg/uuidv7"
+	responsedto "wucher/internal/transport/http/dto/response"
+)
+
+func TestBuildAirRescuerChecklistGroups_DefaultTabsIncludeCATAndDetail(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	checklistTA := uuidv7.MustBytes()
+	checklistMO := uuidv7.MustBytes()
+	itemTA := uuidv7.MustBytes()
+	now := time.Now().UTC()
+
+	bases := []airrescuechecklist.HEMSBaseView{
+		{ID: baseID, BaseName: "Gallus 1 - Zurs Lech", BaseAbbreviation: "G1"},
+	}
+	headers := []airrescuechecklist.ChecklistHeaderView{
+		{ID: checklistTA, HEMSBaseID: baseID, ScopeCode: airrescuechecklist.AirRescuerChecklistScopeTA, Title: "Cockpit Flugretter", Position: 1, CreatedAt: now, UpdatedAt: now},
+		{ID: checklistMO, HEMSBaseID: baseID, ScopeCode: airrescuechecklist.AirRescuerChecklistScopeMO, Title: "Monday Checklist", Position: 2, CreatedAt: now, UpdatedAt: now},
+	}
+	items := []airrescuechecklist.ChecklistItemView{
+		{ID: itemTA, ChecklistID: checklistTA, Name: "Kartenmaterial", Position: 1, CreatedAt: now, UpdatedAt: now},
+	}
+
+	groups := buildAirRescuerChecklistGroups(bases, headers, items, "")
+	if len(groups) != 1 {
+		t.Fatalf("expected 1 base group, got %d", len(groups))
+	}
+
+	tabs := groups[0].Attributes.Tabs
+	if len(tabs) != 1+len(airrescuechecklist.AirRescuerChecklistPersistedScopeOrder()) {
+		t.Fatalf("unexpected tabs count: %d", len(tabs))
+	}
+
+	cat := mustFindChecklistTab(t, tabs, airrescuechecklist.AirRescuerChecklistScopeCAT)
+	if cat.ScopeCodeName != "Category" || cat.ScopeCodeNameDe != "Category" {
+		t.Fatalf("unexpected CAT scope names: en=%q de=%q", cat.ScopeCodeName, cat.ScopeCodeNameDe)
+	}
+	if len(cat.Groups) != 2 {
+		t.Fatalf("expected CAT to include only non-empty scopes, got %d groups", len(cat.Groups))
+	}
+	for i := range cat.Groups {
+		if len(cat.Groups[i].Checklists) == 0 {
+			t.Fatalf("CAT group must have checklists")
+		}
+	}
+	if cat.Groups[0].ScopeCodeDe == airrescuechecklist.AirRescuerChecklistScopeTA &&
+		(cat.Groups[0].ScopeCodeName != "Daily" || cat.Groups[0].ScopeCodeNameDe != "Taeglich") {
+		t.Fatalf("unexpected TA group scope names: en=%q de=%q", cat.Groups[0].ScopeCodeName, cat.Groups[0].ScopeCodeNameDe)
+	}
+
+	ta := mustFindChecklistTab(t, tabs, airrescuechecklist.AirRescuerChecklistScopeTA)
+	if ta.ScopeCodeName != "Daily" || ta.ScopeCodeNameDe != "Taeglich" {
+		t.Fatalf("unexpected TA scope names: en=%q de=%q", ta.ScopeCodeName, ta.ScopeCodeNameDe)
+	}
+	if ta.Checklists == nil || len(*ta.Checklists) != 1 {
+		t.Fatalf("expected TA detail to have 1 checklist")
+	}
+	if len((*ta.Checklists)[0].ChecklistItems) != 1 {
+		t.Fatalf("expected TA detail checklist to include items")
+	}
+
+	di := mustFindChecklistTab(t, tabs, airrescuechecklist.AirRescuerChecklistScopeDI)
+	if di.Checklists == nil || len(*di.Checklists) != 0 {
+		t.Fatalf("expected empty scope detail tab to return checklists: []")
+	}
+
+	raw, err := json.Marshal(groups)
+	if err != nil {
+		t.Fatalf("marshal groups: %v", err)
+	}
+	if !jsonContainsTabWithEmptyChecklists(raw, airrescuechecklist.AirRescuerChecklistScopeDI) {
+		t.Fatalf("expected DI tab serialized with checklists: []")
+	}
+}
+
+func TestBuildAirRescuerChecklistGroups_CATOnlyRequest(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	checklistTA := uuidv7.MustBytes()
+	now := time.Now().UTC()
+
+	bases := []airrescuechecklist.HEMSBaseView{
+		{ID: baseID, BaseName: "Gallus 1 - Zurs Lech", BaseAbbreviation: "G1"},
+	}
+	headers := []airrescuechecklist.ChecklistHeaderView{
+		{ID: checklistTA, HEMSBaseID: baseID, ScopeCode: airrescuechecklist.AirRescuerChecklistScopeTA, Title: "Cockpit Flugretter", Position: 1, CreatedAt: now, UpdatedAt: now},
+	}
+
+	groups := buildAirRescuerChecklistGroups(bases, headers, nil, airrescuechecklist.AirRescuerChecklistScopeCAT)
+	if len(groups) != 1 {
+		t.Fatalf("expected 1 base group, got %d", len(groups))
+	}
+	if len(groups[0].Attributes.Tabs) != 1 {
+		t.Fatalf("expected CAT query to return only CAT tab")
+	}
+	cat := groups[0].Attributes.Tabs[0]
+	if cat.ScopeCodeDe != airrescuechecklist.AirRescuerChecklistScopeCAT {
+		t.Fatalf("expected CAT tab")
+	}
+	if cat.ScopeCodeName != "Category" || cat.ScopeCodeNameDe != "Category" {
+		t.Fatalf("unexpected CAT scope names: en=%q de=%q", cat.ScopeCodeName, cat.ScopeCodeNameDe)
+	}
+	if len(cat.Groups) != 1 || cat.Groups[0].ScopeCodeDe != airrescuechecklist.AirRescuerChecklistScopeTA {
+		t.Fatalf("expected CAT to include only non-empty TA group")
+	}
+	if cat.Groups[0].ScopeCodeName != "Daily" || cat.Groups[0].ScopeCodeNameDe != "Taeglich" {
+		t.Fatalf("unexpected TA group scope names: en=%q de=%q", cat.Groups[0].ScopeCodeName, cat.Groups[0].ScopeCodeNameDe)
+	}
+	if cat.Checklists != nil {
+		t.Fatalf("expected CAT tab to omit detail checklists")
+	}
+}
+
+func TestBuildAirRescuerChecklistGroups_RequestedPersistedScopeCanBeEmpty(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	bases := []airrescuechecklist.HEMSBaseView{
+		{ID: baseID, BaseName: "Gallus 1 - Zurs Lech", BaseAbbreviation: "G1"},
+	}
+
+	groups := buildAirRescuerChecklistGroups(bases, nil, nil, airrescuechecklist.AirRescuerChecklistScopeM10)
+	if len(groups) != 1 {
+		t.Fatalf("expected 1 base group, got %d", len(groups))
+	}
+	if len(groups[0].Attributes.Tabs) != 1 {
+		t.Fatalf("expected one requested tab")
+	}
+	tab := groups[0].Attributes.Tabs[0]
+	if tab.ScopeCodeDe != airrescuechecklist.AirRescuerChecklistScopeM10 {
+		t.Fatalf("expected M10 tab, got %s", tab.ScopeCodeDe)
+	}
+	if tab.ScopeCodeName != "M10" || tab.ScopeCodeNameDe != "M10" {
+		t.Fatalf("unexpected M10 scope names: en=%q de=%q", tab.ScopeCodeName, tab.ScopeCodeNameDe)
+	}
+	if tab.Checklists == nil || len(*tab.Checklists) != 0 {
+		t.Fatalf("expected requested empty persisted tab to return checklists: []")
+	}
+}
+
+func TestBuildAirRescuerChecklistGroups_CATAndDetailOrderingWithDuplicatePosition(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	taChecklistAlpha := uuidv7.MustBytes()
+	taChecklistBravo := uuidv7.MustBytes()
+	taChecklistCharlie := uuidv7.MustBytes()
+	moChecklist := uuidv7.MustBytes()
+	now := time.Now().UTC()
+
+	bases := []airrescuechecklist.HEMSBaseView{
+		{ID: baseID, BaseName: "Gallus 1 - Zurs Lech", BaseAbbreviation: "G1"},
+	}
+
+	// Header order here follows repository contract: position ASC, title ASC.
+	headers := []airrescuechecklist.ChecklistHeaderView{
+		{ID: taChecklistAlpha, HEMSBaseID: baseID, ScopeCode: airrescuechecklist.AirRescuerChecklistScopeTA, Title: "Alpha", Position: 1, CreatedAt: now, UpdatedAt: now},
+		{ID: taChecklistBravo, HEMSBaseID: baseID, ScopeCode: airrescuechecklist.AirRescuerChecklistScopeTA, Title: "Bravo", Position: 1, CreatedAt: now, UpdatedAt: now},
+		{ID: moChecklist, HEMSBaseID: baseID, ScopeCode: airrescuechecklist.AirRescuerChecklistScopeMO, Title: "Lagerbestand", Position: 1, CreatedAt: now, UpdatedAt: now},
+		{ID: taChecklistCharlie, HEMSBaseID: baseID, ScopeCode: airrescuechecklist.AirRescuerChecklistScopeTA, Title: "Charlie", Position: 2, CreatedAt: now, UpdatedAt: now},
+	}
+
+	// Item order here follows repository contract: position ASC, name ASC.
+	items := []airrescuechecklist.ChecklistItemView{
+		{ID: uuidv7.MustBytes(), ChecklistID: taChecklistAlpha, Name: "Oxygen", Position: 1, CreatedAt: now, UpdatedAt: now},
+		{ID: uuidv7.MustBytes(), ChecklistID: taChecklistAlpha, Name: "Battery", Position: 2, CreatedAt: now, UpdatedAt: now},
+		{ID: uuidv7.MustBytes(), ChecklistID: taChecklistAlpha, Name: "Radio", Position: 2, CreatedAt: now, UpdatedAt: now},
+	}
+
+	groups := buildAirRescuerChecklistGroups(bases, headers, items, "")
+	if len(groups) != 1 {
+		t.Fatalf("expected 1 base group, got %d", len(groups))
+	}
+	tabs := groups[0].Attributes.Tabs
+
+	cat := mustFindChecklistTab(t, tabs, airrescuechecklist.AirRescuerChecklistScopeCAT)
+	if cat.Checklists != nil {
+		t.Fatalf("expected CAT tab to omit detail checklists")
+	}
+	if len(cat.Groups) != 2 {
+		t.Fatalf("expected CAT to include only non-empty TA and MO groups, got %d groups", len(cat.Groups))
+	}
+	if cat.Groups[0].ScopeCodeDe != airrescuechecklist.AirRescuerChecklistScopeTA || cat.Groups[1].ScopeCodeDe != airrescuechecklist.AirRescuerChecklistScopeMO {
+		t.Fatalf("unexpected CAT group order: %+v", cat.Groups)
+	}
+	if len(cat.Groups[0].Checklists) != 3 {
+		t.Fatalf("expected CAT TA group to include 3 checklist summaries")
+	}
+	if cat.Groups[0].Checklists[0].Title != "Alpha" || cat.Groups[0].Checklists[1].Title != "Bravo" || cat.Groups[0].Checklists[2].Title != "Charlie" {
+		t.Fatalf("unexpected CAT TA checklist order: %+v", cat.Groups[0].Checklists)
+	}
+
+	catJSON, err := json.Marshal(cat)
+	if err != nil {
+		t.Fatalf("marshal CAT tab: %v", err)
+	}
+	if jsonContainsChecklistItemsField(catJSON) {
+		t.Fatalf("expected CAT summary payload without checklist_items")
+	}
+
+	ta := mustFindChecklistTab(t, tabs, airrescuechecklist.AirRescuerChecklistScopeTA)
+	if ta.Checklists == nil || len(*ta.Checklists) != 3 {
+		t.Fatalf("expected TA detail to include 3 checklists")
+	}
+	if (*ta.Checklists)[0].Title != "Alpha" || (*ta.Checklists)[1].Title != "Bravo" || (*ta.Checklists)[2].Title != "Charlie" {
+		t.Fatalf("unexpected TA detail checklist order: %+v", *ta.Checklists)
+	}
+	if len((*ta.Checklists)[0].ChecklistItems) != 3 {
+		t.Fatalf("expected Alpha checklist to include 3 items")
+	}
+	if (*ta.Checklists)[0].ChecklistItems[0].Name != "Oxygen" || (*ta.Checklists)[0].ChecklistItems[1].Name != "Battery" || (*ta.Checklists)[0].ChecklistItems[2].Name != "Radio" {
+		t.Fatalf("unexpected TA checklist item order: %+v", (*ta.Checklists)[0].ChecklistItems)
+	}
+}
+
+func mustFindChecklistTab(t *testing.T, tabs []responsedto.AirRescuerChecklistTabResource, scopeCode string) responsedto.AirRescuerChecklistTabResource {
+	t.Helper()
+	for i := range tabs {
+		if tabs[i].ScopeCodeDe == scopeCode {
+			return tabs[i]
+		}
+	}
+	t.Fatalf("scope tab %s not found", scopeCode)
+	return responsedto.AirRescuerChecklistTabResource{}
+}
+
+func jsonContainsTabWithEmptyChecklists(raw []byte, scopeCode string) bool {
+	var payload []map[string]any
+	if err := json.Unmarshal(raw, &payload); err != nil {
+		return false
+	}
+	for _, group := range payload {
+		attrsRaw, ok := group["attributes"].(map[string]any)
+		if !ok {
+			continue
+		}
+		tabsRaw, ok := attrsRaw["tabs"].([]any)
+		if !ok {
+			continue
+		}
+		for _, tab := range tabsRaw {
+			tabMap, ok := tab.(map[string]any)
+			if !ok {
+				continue
+			}
+			if tabMap["scope_code_de"] != scopeCode {
+				continue
+			}
+			checklists, ok := tabMap["checklists"].([]any)
+			return ok && len(checklists) == 0
+		}
+	}
+	return false
+}
+
+func jsonContainsChecklistItemsField(raw []byte) bool {
+	return bytes.Contains(raw, []byte(`"checklist_items"`))
+}
+
+func TestAirRescuerChecklistMapperResourceAndItemData(t *testing.T) {
+	now := time.Date(2026, 3, 25, 8, 0, 0, 0, time.UTC)
+	baseID := []byte("1234567890123456")
+	checklistID := []byte("abcdefghijklmnop")
+	itemID := []byte("itemitemitemitem")
+	creatorID := uuidv7.MustBytes()
+
+	resource := airRescuerChecklistResource(airrescuechecklist.ChecklistHeaderView{
+		ID:               checklistID,
+		HEMSBaseID:       baseID,
+		BaseName:         "  Gallus 1 - Zurs Lech  ",
+		BaseAbbreviation: " G1 ",
+		BaseCategory:     " regular ",
+		ScopeCode:        " TA ",
+		Title:            " Daily Tasks ",
+		Position:         2,
+		CreatedBy:        creatorID,
+		CreatedAt:        now,
+		UpdatedAt:        now,
+	}, []airrescuechecklist.ChecklistItemView{{
+		ID:          itemID,
+		ChecklistID: checklistID,
+		Name:        "  Battery  ",
+		Position:    1,
+		CreatedBy:   creatorID,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	}})
+
+	if resource.Type != "air_rescuer_checklist" {
+		t.Fatalf("unexpected type: %s", resource.Type)
+	}
+	if resource.Attributes.Bases.BaseName != "Gallus 1 - Zurs Lech" {
+		t.Fatalf("expected trimmed base name, got %q", resource.Attributes.Bases.BaseName)
+	}
+	if resource.Attributes.Bases.BaseCategory != "regular" {
+		t.Fatalf("expected base_category regular, got %q", resource.Attributes.Bases.BaseCategory)
+	}
+	if resource.Attributes.ScopeCode != "DA" || resource.Attributes.ScopeCodeDe != "TA" || resource.Attributes.Title != "Daily Tasks" {
+		t.Fatalf("expected mapped scope/title, got scope=%q scope_de=%q title=%q", resource.Attributes.ScopeCode, resource.Attributes.ScopeCodeDe, resource.Attributes.Title)
+	}
+	if len(resource.Attributes.Items) != 1 || resource.Attributes.Items[0].Name != "Battery" {
+		t.Fatalf("expected mapped and trimmed items")
+	}
+	if resource.Attributes.CreatedAt != "2026-03-25T08:00:00Z" {
+		t.Fatalf("unexpected created_at: %s", resource.Attributes.CreatedAt)
+	}
+	if resource.Attributes.CreatedBy == "" || resource.Attributes.Items[0].CreatedBy == "" {
+		t.Fatalf("expected created_by on checklist resource and item")
+	}
+
+	itemData := airRescuerChecklistItemResponseData(airrescuechecklist.ChecklistItemView{
+		ID:          itemID,
+		ChecklistID: checklistID,
+		Name:        "  Radio  ",
+		Position:    3,
+		CreatedBy:   creatorID,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	})
+	if itemData.Type != "air_rescuer_checklist_item" {
+		t.Fatalf("unexpected item type: %s", itemData.Type)
+	}
+	if itemData.Attributes.Name != "Radio" {
+		t.Fatalf("expected trimmed item name, got %q", itemData.Attributes.Name)
+	}
+	if itemData.Attributes.Position != 3 {
+		t.Fatalf("expected position=3, got %d", itemData.Attributes.Position)
+	}
+	if itemData.Attributes.CreatedBy == "" {
+		t.Fatalf("expected created_by on item response")
+	}
+}
+
+func TestPaginateAirRescuerChecklistGroups(t *testing.T) {
+	groups := []responsedto.AirRescuerChecklistBaseGroupResource{
+		{ID: "base-1"},
+		{ID: "base-2"},
+		{ID: "base-3"},
+	}
+
+	got, total := paginateAirRescuerChecklistGroups(groups, 10, 2)
+	if total != 3 {
+		t.Fatalf("expected total=3, got %d", total)
+	}
+	if len(got) != 0 {
+		t.Fatalf("expected empty page when start exceeds total")
+	}
+
+	got, total = paginateAirRescuerChecklistGroups(groups, 1, 5)
+	if total != 3 {
+		t.Fatalf("expected total=3, got %d", total)
+	}
+	if len(got) != 2 || got[0].ID != "base-2" || got[1].ID != "base-3" {
+		t.Fatalf("unexpected paged groups: %+v", got)
+	}
+}
diff --git a/internal/transport/http/handlers/attachment_resolver.go b/internal/transport/http/handlers/attachment_resolver.go
new file mode 100644
index 0000000..fce5c92
--- /dev/null
+++ b/internal/transport/http/handlers/attachment_resolver.go
@@ -0,0 +1,85 @@
+package handlers
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/shared/pkg/attachmentresolver"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+)
+
+func resolveAttachmentIDFromInput(c *fiber.Ctx, params attachmentresolver.Params, errorTitle string) ([]byte, bool) {
+	attachmentID, err := attachmentresolver.Resolve(c.UserContext(), params)
+	if err == nil {
+		return attachmentID, false
+	}
+
+	var resolveErr *attachmentresolver.ResolveError
+	if errors.As(err, &resolveErr) {
+		switch resolveErr.Code {
+		case attachmentresolver.ErrorInvalidAttachmentUUID:
+			writeValidationError(c, fmt.Sprintf("%s is invalid UUID", fieldOrDefault(resolveErr.AttachmentField, "attachment_id")), "/data/attributes/"+fieldOrDefault(resolveErr.AttachmentField, "attachment_id"))
+			return nil, true
+		case attachmentresolver.ErrorInvalidFileUUID:
+			writeValidationError(c, fmt.Sprintf("%s is invalid UUID", fieldOrDefault(resolveErr.FileField, "file_id")), "/data/attributes/"+fieldOrDefault(resolveErr.FileField, "file_id"))
+			return nil, true
+		case attachmentresolver.ErrorAttachmentNotFound:
+			writeValidationError(c, fmt.Sprintf("%s not found", fieldOrDefault(resolveErr.AttachmentField, "attachment_id")), "/data/attributes/"+fieldOrDefault(resolveErr.AttachmentField, "attachment_id"))
+			return nil, true
+		case attachmentresolver.ErrorRequireValue:
+			writeValidationError(c, fmt.Sprintf("%s or %s is required", fieldOrDefault(resolveErr.AttachmentField, "attachment_id"), fieldOrDefault(resolveErr.FileField, "file_id")), "/data/attributes")
+			return nil, true
+		case attachmentresolver.ErrorCannotResolveFromFile:
+			writeValidationError(c, fmt.Sprintf("cannot resolve attachment from %s", fieldOrDefault(resolveErr.FileField, "file_id")), "/data/attributes/"+fieldOrDefault(resolveErr.FileField, "file_id"))
+			return nil, true
+		case attachmentresolver.ErrorFileNotReadyForAttachment:
+			writeValidationError(c, fmt.Sprintf("%s is not ready yet; wait for file.updated SSE event", fieldOrDefault(resolveErr.FileField, "file_id")), "/data/attributes/"+fieldOrDefault(resolveErr.FileField, "file_id"))
+			return nil, true
+		case attachmentresolver.ErrorFileManagerUnavailable:
+			writeBadRequestError(c, errorTitle, resolveErr.Error())
+			return nil, true
+		}
+	}
+
+	writeBadRequestError(c, errorTitle, err.Error())
+	return nil, true
+}
+
+func writeValidationError(c *fiber.Ctx, detail, pointer string) {
+	_ = response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+		Status: "422",
+		Title:  "Validation error",
+		Detail: detail,
+		Source: &jsonapi.ErrorSource{Pointer: pointer},
+	}})
+}
+
+func writeBadRequestError(c *fiber.Ctx, title, detail string) {
+	if title == "" {
+		title = "Request failed"
+	}
+	_ = response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+		Status: "400",
+		Title:  title,
+		Detail: detail,
+	}})
+}
+
+func fieldOrDefault(v string, fallback string) string {
+	if v == "" {
+		return fallback
+	}
+	return v
+}
+
+func hasNonEmptyOptionalString(v *string) bool {
+	return v != nil && strings.TrimSpace(*v) != ""
+}
+
+func hasBlankOptionalString(v *string) bool {
+	return v != nil && strings.TrimSpace(*v) == ""
+}
diff --git a/internal/transport/http/handlers/attachment_resolver_test.go b/internal/transport/http/handlers/attachment_resolver_test.go
new file mode 100644
index 0000000..65471e5
--- /dev/null
+++ b/internal/transport/http/handlers/attachment_resolver_test.go
@@ -0,0 +1,119 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/attachmentresolver"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func TestAttachmentResolverHelpers(t *testing.T) {
+	app := fiber.New()
+	app.Get("/invalid-attachment", func(c *fiber.Ctx) error {
+		raw := "bad"
+		_, handled := resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+			RawAttachmentID: &raw,
+			AttachmentField: "attachment_id",
+			FileField:       "file_uuid",
+		}, "Update failed")
+		if !handled {
+			t.Fatalf("expected handled invalid attachment")
+		}
+		return nil
+	})
+	app.Get("/invalid-file", func(c *fiber.Ctx) error {
+		raw := "bad"
+		_, handled := resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+			RawFileID:   &raw,
+			FileManager: &fileManagerAttachmentHandlerServiceMock{},
+		}, "Update failed")
+		if !handled {
+			t.Fatalf("expected handled invalid file")
+		}
+		return nil
+	})
+	app.Get("/cannot-resolve", func(c *fiber.Ctx) error {
+		raw := mustUUIDStringContact(t, uuidv7.MustBytes())
+		_, handled := resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+			RawFileID: &raw,
+			FileManager: &fileManagerAttachmentHandlerServiceMock{
+				createAttachmentFn: func(context.Context, filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+					return nil, filemanager.ErrAttachmentAlreadyExists
+				},
+				listAttachmentsFn: func(context.Context, filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error) {
+					return nil, 0, nil
+				},
+			},
+		}, "Update failed")
+		if !handled {
+			t.Fatalf("expected handled cannot resolve")
+		}
+		return nil
+	})
+	app.Get("/not-ready", func(c *fiber.Ctx) error {
+		raw := mustUUIDStringContact(t, uuidv7.MustBytes())
+		_, handled := resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+			RawFileID: &raw,
+			FileManager: &fileManagerAttachmentHandlerServiceMock{
+				createAttachmentFn: func(context.Context, filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+					return nil, filemanager.ErrFileNotReadyForAttachment
+				},
+				getFileFn: func(context.Context, []byte) (*filemanager.File, error) {
+					return &filemanager.File{Status: filemanager.FileStatusUploaded}, nil
+				},
+			},
+		}, "Update failed")
+		if !handled {
+			t.Fatalf("expected handled file-not-ready")
+		}
+		return nil
+	})
+	app.Get("/bad-request", func(c *fiber.Ctx) error {
+		raw := mustUUIDStringContact(t, uuidv7.MustBytes())
+		_, handled := resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+			RawAttachmentID:          &raw,
+			ValidateAttachmentExists: true,
+			AttachmentExists: func(context.Context, []byte) (bool, error) {
+				return false, errors.New("db down")
+			},
+		}, "Update failed")
+		if !handled {
+			t.Fatalf("expected handled bad request")
+		}
+		return nil
+	})
+
+	for _, path := range []string{"/invalid-attachment", "/invalid-file", "/cannot-resolve", "/not-ready", "/bad-request"} {
+		resp, err := app.Test(httptest.NewRequest(http.MethodGet, path, nil), 30000)
+		if err != nil {
+			t.Fatalf("%s err: %v", path, err)
+		}
+		if resp.StatusCode == http.StatusOK {
+			t.Fatalf("expected non-200 for %s", path)
+		}
+	}
+}
+
+func TestOptionalStringHelpers(t *testing.T) {
+	if hasNonEmptyOptionalString(nil) || hasBlankOptionalString(nil) {
+		t.Fatalf("nil optional helpers should be false")
+	}
+	blank := " "
+	if hasNonEmptyOptionalString(&blank) || !hasBlankOptionalString(&blank) {
+		t.Fatalf("blank optional helper mismatch")
+	}
+	val := "x"
+	if !hasNonEmptyOptionalString(&val) || hasBlankOptionalString(&val) {
+		t.Fatalf("non-blank optional helper mismatch")
+	}
+	if fieldOrDefault("", "a") != "a" || fieldOrDefault("x", "a") != "x" {
+		t.Fatalf("fieldOrDefault mismatch")
+	}
+}
diff --git a/internal/transport/http/handlers/audit_fields.go b/internal/transport/http/handlers/audit_fields.go
new file mode 100644
index 0000000..16a830d
--- /dev/null
+++ b/internal/transport/http/handlers/audit_fields.go
@@ -0,0 +1,93 @@
+package handlers
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	responsedto "wucher/internal/transport/http/dto/response"
+)
+
+func userRef(id []byte, name string) *responsedto.UserRef {
+	trimmed := strings.TrimSpace(name)
+	if len(id) == 0 && trimmed == "" {
+		return nil
+	}
+	if trimmed == "" && len(id) > 0 {
+		trimmed = userctx.GetDisplayName(context.TODO(), id)
+	}
+	return &responsedto.UserRef{
+		UUID: idString(id),
+		Name: trimmed,
+	}
+}
+
+// updatedAuditOrCreated returns the "last modified" timestamp (RFC3339) and actor for an
+// audited row, falling back to the creation timestamp/actor when the row was never
+// updated after creation (updated_by unset — e.g. seed/legacy rows). This guarantees an
+// updated_at/updated_by is always presentable instead of silently omitted.
+func updatedAuditOrCreated(updatedAt, createdAt time.Time, updatedBy []byte, updatedByName string, createdBy []byte, createdByName string) (string, *responsedto.UserRef) {
+	if len(updatedBy) == 0 {
+		updatedBy, updatedByName = createdBy, createdByName
+	}
+	if updatedAt.IsZero() {
+		updatedAt = createdAt
+	}
+	at := ""
+	if !updatedAt.IsZero() {
+		at = updatedAt.UTC().Format(time.RFC3339)
+	}
+	return at, userRef(updatedBy, updatedByName)
+}
+
+func actorUserID(c *fiber.Ctx) []byte {
+	raw := c.Locals("user_id")
+	userID, ok := raw.([]byte)
+	if !ok || len(userID) == 0 {
+		return nil
+	}
+	// Return a copy to avoid accidental mutation of local context values.
+	return append([]byte(nil), userID...)
+}
+
+// uuidStringOrEmpty resolves a user ID to their last name using the global userctx getter
+// if set; otherwise falls back to the UUID string representation.
+func uuidStringOrEmpty(id []byte) string {
+	if len(id) == 0 {
+		return ""
+	}
+	if name := userctx.GetDisplayName(context.TODO(), id); name != "" {
+		return name
+	}
+	// Fallback to UUID string when no getter is available or user not found.
+	val, err := uuidv7.BytesToString(id)
+	if err != nil {
+		return ""
+	}
+	return val
+}
+
+// idString converts a resource ID byte slice to a UUID string.
+// Unlike uuidStringOrEmpty, this does not attempt user name resolution.
+// Use this for primary keys and resource IDs, not for audit/user reference fields.
+func idString(id []byte) string {
+	if len(id) == 0 {
+		return ""
+	}
+	val, err := uuidv7.BytesToString(id)
+	if err != nil {
+		return ""
+	}
+	return val
+}
+
+func timeStringOrEmpty(t *time.Time) string {
+	if t == nil || t.IsZero() {
+		return ""
+	}
+	return t.UTC().Format(time.RFC3339)
+}
diff --git a/internal/transport/http/handlers/audit_handler.go b/internal/transport/http/handlers/audit_handler.go
new file mode 100644
index 0000000..ffbd912
--- /dev/null
+++ b/internal/transport/http/handlers/audit_handler.go
@@ -0,0 +1,359 @@
+package handlers
+
+import (
+	"encoding/json"
+	"fmt"
+	"slices"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/audit"
+	"wucher/internal/service"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+)
+
+type AuditHandler struct {
+	svc *service.AuditLogService
+}
+
+func NewAuditHandler(svc *service.AuditLogService) *AuditHandler {
+	return &AuditHandler{svc: svc}
+}
+
+// ListAuditLogs godoc
+// @Summary List audit logs
+// @Description JSON:API list with pagination, filtering and sorting.
+// @Tags Audit Logs
+// @Produce json
+// @Param filter[search] query string false "Search by request_id/layer/action/method/path/message (contains)"
+// @Param filter[method] query string false "Method filter; single/comma-separated values or ALL/*" Enums(POST,PUT,PATCH,DELETE,UPDATE,ALL,*)
+// @Param method query string false "Alias for filter[method]" Enums(POST,PUT,PATCH,DELETE,UPDATE,ALL,*)
+// @Param filter[module] query string false "Module filter; single/comma-separated values or ALL/*" Enums(air_rescuer_checklist,audit_log,auth,base,base_regular,base_hems,base_roster,branding,contact,duty_roster,facility,federal_state,file_manager,flight,flight_data,forces_present,health_insurance_company,helicopter,helicopter_file,hems_roster,hospital,icao,insurance_patient_data,land,master_setting,medicine,mission,opc,patient_data,reserve_ac,role,user,vocation,unknown,ALL,*)
+// @Param module query string false "Alias for filter[module]" Enums(air_rescuer_checklist,audit_log,auth,base,base_regular,base_hems,base_roster,branding,contact,duty_roster,facility,federal_state,file_manager,flight,flight_data,forces_present,health_insurance_company,helicopter,helicopter_file,hems_roster,hospital,icao,insurance_patient_data,land,master_setting,medicine,mission,opc,patient_data,reserve_ac,role,user,vocation,unknown,ALL,*)
+// @Param filter[action] query string false "Action filter; single/comma-separated values or ALL/*" Enums(list,get,create,update,delete,export,custom,ALL,*)
+// @Param action query string false "Alias for filter[action]" Enums(list,get,create,update,delete,export,custom,ALL,*)
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 200)"
+// @Param sort query string false "Sort order" Enums(created_at,-created_at,module,-module,action,-action,layer,-layer,status_code,-status_code,success,-success)
+// @Success 200 {object} jsonapi.Document
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/audit-logs/get-all [get]
+func (h *AuditHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("filter[action]")
+	}
+	if filter == "" {
+		filter = c.Query("filter[layer]")
+	}
+	methodFilter := c.Query("filter[method]")
+	if methodFilter == "" {
+		methodFilter = c.Query("method")
+	}
+	methods := parseAuditMethodFilter(methodFilter)
+	moduleFilter := c.Query("filter[module]")
+	if moduleFilter == "" {
+		moduleFilter = c.Query("module")
+	}
+	modules := parseAuditTokenFilter(moduleFilter)
+	actionFilter := c.Query("filter[action]")
+	if actionFilter == "" {
+		actionFilter = c.Query("action")
+	}
+	actions := parseAuditTokenFilter(actionFilter)
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 1)
+	pageSize := parseIntDefault(c.Query("page[size]"), 20)
+	if pageSize > 200 {
+		pageSize = 200
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+	if errObj := validateAuditListQuery(methods, modules, actions, sort); errObj != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	logs, total, err := h.svc.List(c.UserContext(), filter, methods, modules, actions, sort, 0, 0)
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.AuditLogResource, 0, len(logs))
+	for i := range logs {
+		data = append(data, auditLogResource(&logs[i]))
+	}
+
+	meta := map[string]any{
+		"total": total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func parseAuditMethodFilter(raw string) []string {
+	v := strings.TrimSpace(raw)
+	if v == "" {
+		return nil
+	}
+	parts := strings.Split(v, ",")
+	out := make([]string, 0, len(parts))
+	for _, part := range parts {
+		token := strings.TrimSpace(part)
+		if token == "" {
+			continue
+		}
+		out = append(out, token)
+	}
+	return out
+}
+
+func auditLogResource(v *audit.AuditLog) dto.AuditLogResource {
+	id, _ := uuidv7.BytesToString(v.ID)
+	actorID := ""
+	if len(v.ActorUserID) == 16 {
+		actorID, _ = uuidv7.BytesToString(v.ActorUserID)
+	}
+
+	var metadata any
+	if len(v.Metadata) > 0 {
+		_ = json.Unmarshal(v.Metadata, &metadata)
+	}
+	module := strings.TrimSpace(v.Module)
+	if module == "" {
+		module = inferAuditModuleFromPath(strings.TrimSpace(v.Path))
+	}
+
+	return dto.AuditLogResource{
+		Type: "audit_log",
+		ID:   id,
+		Attributes: dto.AuditLogAttributes{
+			RequestID:   strings.TrimSpace(v.RequestID),
+			ActorUserID: actorID,
+			Layer:       strings.TrimSpace(v.Layer),
+			Module:      module,
+			Action:      strings.TrimSpace(v.Action),
+			Method:      strings.TrimSpace(v.Method),
+			Path:        strings.TrimSpace(v.Path),
+			StatusCode:  v.StatusCode,
+			Success:     v.Success,
+			IP:          strings.TrimSpace(v.IP),
+			UserAgent:   strings.TrimSpace(v.UserAgent),
+			Message:     strings.TrimSpace(v.Message),
+			Metadata:    metadata,
+			CreatedAt:   v.CreatedAt.UTC().Format(time.RFC3339),
+		},
+	}
+}
+
+func inferAuditModuleFromPath(path string) string {
+	parts := strings.Split(strings.Trim(strings.ToLower(strings.TrimSpace(path)), "/"), "/")
+	if len(parts) < 3 || parts[0] != "api" || parts[1] != "v1" {
+		return sharedconst.AuditModuleUnknown
+	}
+	switch parts[2] {
+	case "air-rescuer-checklist":
+		return sharedconst.AuditModuleAirRescuerChecklist
+	case "audit-logs":
+		return sharedconst.AuditModuleAuditLog
+	case "auth":
+		return sharedconst.AuditModuleAuth
+	case "bases":
+		return sharedconst.AuditModuleBase
+	case "branding", "public":
+		return sharedconst.AuditModuleBranding
+	case "contacts":
+		return sharedconst.AuditModuleContact
+	case "duty-roster":
+		return sharedconst.AuditModuleDutyRoster
+	case "dul":
+		return sharedconst.AuditModuleDUL
+	case "facilities":
+		return sharedconst.AuditModuleFacility
+	case "federal-state":
+		return sharedconst.AuditModuleFederalState
+	case "file-manager":
+		return sharedconst.AuditModuleFileManager
+	case "flight-data":
+		return sharedconst.AuditModuleFlightData
+	case "flights":
+		return sharedconst.AuditModuleFlight
+	case "forces-present":
+		return sharedconst.AuditModuleForcesPresent
+	case "health-insurance-companies":
+		return sharedconst.AuditModuleHealthInsuranceCompany
+	case "helicopter-files":
+		return sharedconst.AuditModuleHelicopterFile
+	case "helicopters":
+		return sharedconst.AuditModuleHelicopter
+	case "hems-operation", "hems-operation-category", "hems-operational-data":
+		return sharedconst.AuditModuleUnknown
+	case "hospital":
+		return sharedconst.AuditModuleHospital
+	case "icao":
+		return sharedconst.AuditModuleICAO
+	case "insurance-patient-data":
+		return sharedconst.AuditModuleInsurancePatientData
+	case "land":
+		return sharedconst.AuditModuleLand
+	case "master-settings":
+		return sharedconst.AuditModuleMasterSetting
+	case "medicine":
+		return sharedconst.AuditModuleMedicine
+	case "mission":
+		return sharedconst.AuditModuleMission
+	case "opc":
+		return sharedconst.AuditModuleOPC
+	case "patient-data":
+		return sharedconst.AuditModulePatientData
+	case "reserve-acs":
+		return sharedconst.AuditModuleReserveAC
+	case "roles":
+		return sharedconst.AuditModuleRole
+	case "users":
+		return sharedconst.AuditModuleUser
+	case "vocation":
+		return sharedconst.AuditModuleVocation
+	default:
+		return sharedconst.AuditModuleUnknown
+	}
+}
+
+func parseAuditTokenFilter(raw string) []string {
+	v := strings.TrimSpace(raw)
+	if v == "" {
+		return nil
+	}
+	parts := strings.Split(v, ",")
+	out := make([]string, 0, len(parts))
+	for _, part := range parts {
+		token := strings.TrimSpace(part)
+		if token == "" {
+			continue
+		}
+		out = append(out, token)
+	}
+	return out
+}
+
+func validateAuditListQuery(methods, modules, actions []string, sort string) *jsonapi.ErrorObject {
+	for _, method := range methods {
+		v := strings.ToUpper(strings.TrimSpace(method))
+		if v == "" || v == "ALL" || v == "*" {
+			continue
+		}
+		if !slices.Contains([]string{"POST", "PUT", "PATCH", "DELETE", "UPDATE"}, v) {
+			return &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("invalid method filter: %s", method),
+				Source: &jsonapi.ErrorSource{Pointer: "/query/method"},
+			}
+		}
+	}
+	validModules := []string{
+		sharedconst.AuditModuleAirRescuerChecklist,
+		sharedconst.AuditModuleAuditLog,
+		sharedconst.AuditModuleAuth,
+		sharedconst.AuditModuleBase,
+		sharedconst.AuditModuleBaseRegular,
+		sharedconst.AuditModuleBaseHEMS,
+		sharedconst.AuditModuleBranding,
+		sharedconst.AuditModuleContact,
+		sharedconst.AuditModuleDutyRoster,
+		sharedconst.AuditModuleDUL,
+		sharedconst.AuditModuleFacility,
+		sharedconst.AuditModuleFederalState,
+		sharedconst.AuditModuleFileManager,
+		sharedconst.AuditModuleFlightData,
+		sharedconst.AuditModuleFlight,
+		sharedconst.AuditModuleForcesPresent,
+		sharedconst.AuditModuleHealthInsuranceCompany,
+		sharedconst.AuditModuleHelicopterFile,
+		sharedconst.AuditModuleHelicopter,
+		sharedconst.AuditModuleHospital,
+		sharedconst.AuditModuleICAO,
+		sharedconst.AuditModuleInsurancePatientData,
+		sharedconst.AuditModuleLand,
+		sharedconst.AuditModuleMasterSetting,
+		sharedconst.AuditModuleMedicine,
+		sharedconst.AuditModuleMission,
+		sharedconst.AuditModuleOPC,
+		sharedconst.AuditModulePatientData,
+		sharedconst.AuditModuleReserveAC,
+		sharedconst.AuditModuleRole,
+		sharedconst.AuditModuleUser,
+		sharedconst.AuditModuleVocation,
+		sharedconst.AuditModuleUnknown,
+	}
+	for _, module := range modules {
+		v := strings.ToLower(strings.TrimSpace(module))
+		if v == "" || v == "all" || v == "*" {
+			continue
+		}
+		if !slices.Contains(validModules, v) {
+			return &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("invalid module filter: %s", module),
+				Source: &jsonapi.ErrorSource{Pointer: "/query/module"},
+			}
+		}
+	}
+	validActions := []string{
+		sharedconst.AuditActionList,
+		sharedconst.AuditActionGet,
+		sharedconst.AuditActionCreate,
+		sharedconst.AuditActionUpdate,
+		sharedconst.AuditActionDelete,
+		sharedconst.AuditActionExport,
+		sharedconst.AuditActionCustom,
+	}
+	for _, action := range actions {
+		v := strings.ToLower(strings.TrimSpace(action))
+		if v == "" || v == "all" || v == "*" {
+			continue
+		}
+		if !slices.Contains(validActions, v) {
+			return &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("invalid action filter: %s", action),
+				Source: &jsonapi.ErrorSource{Pointer: "/query/action"},
+			}
+		}
+	}
+	if strings.TrimSpace(sort) != "" {
+		allowed := map[string]struct{}{
+			"created_at": {}, "-created_at": {},
+			"module": {}, "-module": {},
+			"action": {}, "-action": {},
+			"layer": {}, "-layer": {},
+			"status_code": {}, "-status_code": {},
+			"success": {}, "-success": {},
+		}
+		if _, ok := allowed[strings.TrimSpace(sort)]; !ok {
+			return &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("invalid sort: %s", sort),
+				Source: &jsonapi.ErrorSource{Pointer: "/query/sort"},
+			}
+		}
+	}
+	return nil
+}
diff --git a/internal/transport/http/handlers/audit_handler_test.go b/internal/transport/http/handlers/audit_handler_test.go
new file mode 100644
index 0000000..9414a8b
--- /dev/null
+++ b/internal/transport/http/handlers/audit_handler_test.go
@@ -0,0 +1,286 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/audit"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type mockAuditListRepo struct {
+	mu          sync.Mutex
+	rows        []audit.AuditLog
+	total       int64
+	err         error
+	lastFilter  string
+	lastMethods []string
+	lastModules []string
+	lastActions []string
+	lastSort    string
+	lastLimit   int
+	lastOffset  int
+}
+
+func (m *mockAuditListRepo) Create(_ context.Context, _ *audit.AuditLog) error { return nil }
+
+func (m *mockAuditListRepo) List(_ context.Context, filter string, methods []string, modules []string, actions []string, sort string, limit, offset int) ([]audit.AuditLog, int64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.lastFilter = filter
+	m.lastMethods = append([]string(nil), methods...)
+	m.lastModules = append([]string(nil), modules...)
+	m.lastActions = append([]string(nil), actions...)
+	m.lastSort = sort
+	m.lastLimit = limit
+	m.lastOffset = offset
+	if m.err != nil {
+		return nil, 0, m.err
+	}
+	out := make([]audit.AuditLog, len(m.rows))
+	copy(out, m.rows)
+	return out, m.total, nil
+}
+
+func TestAuditHandler_List(t *testing.T) {
+	repo := &mockAuditListRepo{
+		rows: []audit.AuditLog{
+			{
+				ID:         uuidv7.MustBytes(),
+				Layer:      "api",
+				Module:     "users",
+				Action:     "list",
+				Method:     "GET",
+				Path:       "/api/v1/users/get-all",
+				StatusCode: 200,
+				Success:    true,
+				IP:         "127.0.0.1",
+				CreatedAt:  time.Now().UTC(),
+			},
+		},
+		total: 1,
+	}
+	svc := service.NewAuditLogService(repo, service.AuditLogServiceDependencies{QueueSize: 8, Workers: 1})
+
+	h := NewAuditHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/audit-logs/get-all", h.List)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/audit-logs/get-all?filter[search]=http&method=UPDATE&filter[module]=user&filter[action]=list&sort=-created_at&page[number]=1&page[size]=20", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	body, _ := io.ReadAll(resp.Body)
+	bodyStr := string(body)
+	if !containsAll(bodyStr, `"type":"audit_log"`, `"total":1`, `"ip":"127.0.0.1"`) {
+		t.Fatalf("unexpected body: %s", bodyStr)
+	}
+
+	repo.mu.Lock()
+	defer repo.mu.Unlock()
+	if repo.lastFilter != "http" {
+		t.Fatalf("expected filter to be propagated, got %q", repo.lastFilter)
+	}
+	if repo.lastSort != "created_at DESC" {
+		t.Fatalf("expected normalized sort, got %q", repo.lastSort)
+	}
+	if len(repo.lastMethods) != 2 || repo.lastMethods[0] != "PUT" || repo.lastMethods[1] != "PATCH" {
+		t.Fatalf("expected method filter [PUT PATCH], got %#v", repo.lastMethods)
+	}
+	if len(repo.lastModules) != 1 || repo.lastModules[0] != "user" {
+		t.Fatalf("expected module filter [user], got %#v", repo.lastModules)
+	}
+	if len(repo.lastActions) != 3 || repo.lastActions[0] != "create" || repo.lastActions[1] != "update" || repo.lastActions[2] != "delete" {
+		t.Fatalf("expected action filter [create update delete], got %#v", repo.lastActions)
+	}
+	if repo.lastLimit != 0 || repo.lastOffset != 0 {
+		t.Fatalf("unexpected paging limit=%d offset=%d", repo.lastLimit, repo.lastOffset)
+	}
+}
+
+func containsAll(v string, terms ...string) bool {
+	for i := range terms {
+		if !strings.Contains(v, terms[i]) {
+			return false
+		}
+	}
+	return true
+}
+
+func TestAuditHandler_List_Branches(t *testing.T) {
+	t.Run("fallback filter action and clamp page", func(t *testing.T) {
+		repo := &mockAuditListRepo{
+			rows:  []audit.AuditLog{{ID: uuidv7.MustBytes(), Action: "create", CreatedAt: time.Now().UTC()}},
+			total: 1,
+		}
+		svc := service.NewAuditLogService(repo, service.AuditLogServiceDependencies{QueueSize: 8, Workers: 1})
+		h := NewAuditHandler(svc)
+		app := fiber.New()
+		app.Get("/api/v1/audit-logs/get-all", h.List)
+
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/audit-logs/get-all?filter[action]=create&page[number]=0&page[size]=500&sort=action", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+
+		repo.mu.Lock()
+		defer repo.mu.Unlock()
+		if repo.lastFilter != "create" {
+			t.Fatalf("expected action fallback filter, got %q", repo.lastFilter)
+		}
+		if repo.lastSort != "action ASC" {
+			t.Fatalf("expected normalized sort, got %q", repo.lastSort)
+		}
+		if repo.lastLimit != 0 || repo.lastOffset != 0 {
+			t.Fatalf("unexpected paging limit=%d offset=%d", repo.lastLimit, repo.lastOffset)
+		}
+	})
+
+	t.Run("fallback filter layer", func(t *testing.T) {
+		repo := &mockAuditListRepo{
+			rows:  []audit.AuditLog{{ID: uuidv7.MustBytes(), Layer: "service", CreatedAt: time.Now().UTC()}},
+			total: 1,
+		}
+		svc := service.NewAuditLogService(repo, service.AuditLogServiceDependencies{QueueSize: 8, Workers: 1})
+		h := NewAuditHandler(svc)
+		app := fiber.New()
+		app.Get("/api/v1/audit-logs/get-all", h.List)
+
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/audit-logs/get-all?filter[layer]=service&page[number]=1&page[size]=20", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+
+		repo.mu.Lock()
+		defer repo.mu.Unlock()
+		if repo.lastFilter != "service" {
+			t.Fatalf("expected layer fallback filter, got %q", repo.lastFilter)
+		}
+	})
+
+	t.Run("list error", func(t *testing.T) {
+		repo := &mockAuditListRepo{err: errors.New("list failed")}
+		svc := service.NewAuditLogService(repo, service.AuditLogServiceDependencies{QueueSize: 8, Workers: 1})
+		h := NewAuditHandler(svc)
+		app := fiber.New()
+		app.Get("/api/v1/audit-logs/get-all", h.List)
+
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/audit-logs/get-all", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("default mutation filter applied when query is empty", func(t *testing.T) {
+		repo := &mockAuditListRepo{
+			rows:  []audit.AuditLog{{ID: uuidv7.MustBytes(), Action: "update", Method: "PATCH", CreatedAt: time.Now().UTC()}},
+			total: 1,
+		}
+		svc := service.NewAuditLogService(repo, service.AuditLogServiceDependencies{QueueSize: 8, Workers: 1})
+		h := NewAuditHandler(svc)
+		app := fiber.New()
+		app.Get("/api/v1/audit-logs/get-all", h.List)
+
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/audit-logs/get-all", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+
+		repo.mu.Lock()
+		defer repo.mu.Unlock()
+		if len(repo.lastMethods) != 4 || repo.lastMethods[0] != "POST" || repo.lastMethods[1] != "PUT" || repo.lastMethods[2] != "PATCH" || repo.lastMethods[3] != "DELETE" {
+			t.Fatalf("expected default method filter [POST PUT PATCH DELETE], got %#v", repo.lastMethods)
+		}
+		if len(repo.lastActions) != 3 || repo.lastActions[0] != "create" || repo.lastActions[1] != "update" || repo.lastActions[2] != "delete" {
+			t.Fatalf("expected default action filter [create update delete], got %#v", repo.lastActions)
+		}
+	})
+
+	t.Run("invalid module query returns 422", func(t *testing.T) {
+		repo := &mockAuditListRepo{}
+		svc := service.NewAuditLogService(repo, service.AuditLogServiceDependencies{QueueSize: 8, Workers: 1})
+		h := NewAuditHandler(svc)
+		app := fiber.New()
+		app.Get("/api/v1/audit-logs/get-all", h.List)
+
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/audit-logs/get-all?module=bad-module", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuditLogResource_Branches(t *testing.T) {
+	now := time.Now().UTC().Truncate(time.Second)
+	row := &audit.AuditLog{
+		ID:          uuidv7.MustBytes(),
+		RequestID:   " req-1 ",
+		ActorUserID: uuidv7.MustBytes(),
+		Layer:       " service ",
+		Action:      " create ",
+		Method:      " POST ",
+		Path:        " /api/v1/reserve-acs/get-all ",
+		StatusCode:  201,
+		Success:     true,
+		IP:          " 127.0.0.1 ",
+		UserAgent:   " ua ",
+		Message:     " ok ",
+		Metadata:    []byte(`{"module":"auth","count":2}`),
+		CreatedAt:   now,
+	}
+
+	res := auditLogResource(row)
+	if res.Type != "audit_log" || res.ID == "" {
+		t.Fatalf("expected audit resource type/id")
+	}
+	if res.Attributes.ActorUserID == "" {
+		t.Fatalf("expected actor_user_id to be encoded")
+	}
+	if res.Attributes.RequestID != "req-1" || res.Attributes.Layer != "service" || res.Attributes.Action != "create" {
+		t.Fatalf("expected trimmed string attributes")
+	}
+	if res.Attributes.Module != "reserve_ac" {
+		t.Fatalf("expected inferred module reserve_ac, got %q", res.Attributes.Module)
+	}
+	md, ok := res.Attributes.Metadata.(map[string]any)
+	if !ok || md["module"] != "auth" {
+		t.Fatalf("expected metadata map decoded, got %#v", res.Attributes.Metadata)
+	}
+	if res.Attributes.CreatedAt == "" {
+		t.Fatalf("expected created_at in resource")
+	}
+}
diff --git a/internal/transport/http/handlers/auth_handler.go b/internal/transport/http/handlers/auth_handler.go
new file mode 100644
index 0000000..1ae9255
--- /dev/null
+++ b/internal/transport/http/handlers/auth_handler.go
@@ -0,0 +1,3608 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/url"
+	"strconv"
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/contact"
+	"wucher/internal/service"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/apperrorsx"
+	tzpkg "wucher/internal/shared/pkg/timezone"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type AuthHandler struct {
+	svc        *service.AuthService
+	contactSvc contact.Service
+	storage    fileManagerDownloadURLStorage
+	validate   *validators.Validator
+}
+
+const (
+	pinVerificationHeader = "X-PIN-Verification-Token"
+	deviceTypeHeader      = "X-Device-Type"
+)
+
+func NewAuthHandler(svc *service.AuthService) *AuthHandler {
+	return &AuthHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+func (h *AuthHandler) WithFileStorage(storage fileManagerDownloadURLStorage) *AuthHandler {
+	h.storage = storage
+	return h
+}
+
+func (h *AuthHandler) WithContactService(contactSvc contact.Service) *AuthHandler {
+	h.contactSvc = contactSvc
+	return h
+}
+
+// Register godoc
+// @Summary Register user with email & password
+// @Description Creates user (public role: from AUTH_DEFAULT_ROLE, fallback: user) and sends verification link to email without issuing an auth session.
+// @Description Next: open verify link -> then login.
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.RegisterRequest true "JSON:API Register request"
+// @Success 201 {object} dto.UserResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/register [post]
+func (h *AuthHandler) Register(c *fiber.Ctx) error {
+	if h.svc.RegisterDisabled() {
+		return writeAuthErrors(c, fiber.StatusForbidden, []jsonapi.ErrorObject{{
+			Status: "403",
+			Title:  "Registration disabled",
+			Detail: "registration is disabled in this environment",
+		}})
+	}
+
+	var req dto.RegisterRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if strings.TrimSpace(req.Data.Attributes.Username) == "" {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "username is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/username"},
+		}})
+	}
+
+	defaultRoleName := strings.TrimSpace(h.svc.DefaultRoleName())
+	if defaultRoleName == "" {
+		defaultRoleName = "user"
+	}
+
+	roleID, err := h.svc.GetRoleIDByName(c.UserContext(), defaultRoleName)
+	if err != nil {
+		return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "AuthHandler.Register.GetRoleIDByName", err)
+	}
+
+	user, err := h.svc.RegisterWithEmail(
+		c.UserContext(),
+		req.Data.Attributes.Email,
+		req.Data.Attributes.Username,
+		req.Data.Attributes.FirstName,
+		req.Data.Attributes.LastName,
+		strings.TrimSpace(req.Data.Attributes.MobilePhone),
+		req.Data.Attributes.Password,
+		roleID,
+	)
+	if err != nil {
+		return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "AuthHandler.Register", err)
+	}
+
+	id, _ := uuidv7.BytesToString(user.ID)
+	roleIDStr, _ := uuidv7.BytesToString(roleID)
+	resp := jsonapi.Resource{
+		Type: "user",
+		ID:   id,
+		Attributes: map[string]any{
+			"email":        user.Email,
+			"username":     derefString(user.Username),
+			"first_name":   user.FirstName,
+			"last_name":    user.LastName,
+			"role_id":      roleIDStr,
+			"role_ids":     []string{roleIDStr},
+			"mobile_phone": user.MobilePhone,
+			"timezone":     tzpkg.WithDefault(user.Timezone),
+			"registered":   true,
+		},
+	}
+	return response.Write(c, fiber.StatusCreated, resp)
+}
+
+// Invite godoc
+// @Summary Invite user
+// @Description Creates user without password and sends set-password link to email.
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.InviteRequest true "JSON:API Invite request"
+// @Success 201 {object} dto.UserResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/invite [post]
+func (h *AuthHandler) Invite(c *fiber.Ctx) error {
+	var req dto.InviteRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if strings.TrimSpace(req.Data.Attributes.Username) == "" {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "username is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/username"},
+		}})
+	}
+
+	roleID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.RoleID))
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "role_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/role_id"},
+		}})
+	}
+	roleIDs, roleErrs := parseRoleIDs(req.Data.Attributes.RoleIDs, "/data/attributes/role_ids")
+	if len(roleErrs) > 0 {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, roleErrs)
+	}
+	roleIDs = normalizeRoleIDs(roleID, roleIDs)
+
+	user, err := h.svc.InviteUserWithRoles(
+		c.UserContext(),
+		req.Data.Attributes.Email,
+		req.Data.Attributes.Username,
+		req.Data.Attributes.FirstName,
+		req.Data.Attributes.LastName,
+		strings.TrimSpace(req.Data.Attributes.MobilePhone),
+		roleID,
+		roleIDs,
+	)
+	if err != nil {
+		return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "AuthHandler.Invite", err)
+	}
+
+	id, _ := uuidv7.BytesToString(user.ID)
+	_, roles := authRoleResponseData(h.svc, c, user)
+	roleIDStr, roleIDList := roleResponseIDFields(roles)
+	resp := jsonapi.Resource{
+		Type: "user",
+		ID:   id,
+		Attributes: map[string]any{
+			"email":        user.Email,
+			"username":     derefString(user.Username),
+			"first_name":   user.FirstName,
+			"last_name":    user.LastName,
+			"mobile_phone": user.MobilePhone,
+			"role_id":      roleIDStr,
+			"role_ids":     roleIDList,
+			"timezone":     tzpkg.WithDefault(user.Timezone),
+		},
+	}
+	return response.Write(c, fiber.StatusCreated, resp)
+}
+
+// SetPassword godoc
+// @Summary Set password from invite token
+// @Description Sets first password for invited user and marks email as verified.
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.SetPasswordRequest true "JSON:API Set password request"
+// @Success 200 {object} dto.WebAuthnResetSetupResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/set-password [post]
+func (h *AuthHandler) SetPassword(c *fiber.Ctx) error {
+	var req dto.SetPasswordRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if err := h.svc.SetPasswordWithInviteToken(c.UserContext(), req.Data.Attributes.Token, req.Data.Attributes.Password); err != nil {
+		return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "AuthHandler.SetPassword", err)
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_set_password",
+		Attributes: map[string]any{
+			"success": true,
+		},
+	})
+}
+
+// ResendSetPasswordInvite godoc
+// @Summary Resend set-password invite
+// @Description Triggers a new set-password invite email for an invited user by user_id. Response is generic for security.
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.ResendSetPasswordInviteRequest true "JSON:API resend set-password invite request"
+// @Success 200 {object} dto.AuthSessionsResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/invite/resend-set-password [post]
+func (h *AuthHandler) ResendSetPasswordInvite(c *fiber.Ctx) error {
+	var req dto.ResendSetPasswordInviteRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	userID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.UserID))
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "user_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/user_id"},
+		}})
+	}
+
+	h.svc.ResendInviteSetPassword(c.UserContext(), userID)
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_resend_set_password",
+		Attributes: map[string]any{
+			"message": "If allowed, a set-password invite email has been sent.",
+		},
+	})
+}
+
+// ForgotPassword godoc
+// @Summary Forgot password
+// @Description Always returns a generic success response.
+// @Tags Auth - Forgot Password
+// @Accept json
+// @Produce json
+// @Param request body dto.ForgotPasswordRequest true "JSON:API Forgot password request"
+// @Success 200 {object} dto.AuthSessionsResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/forgot-password [post]
+func (h *AuthHandler) ForgotPassword(c *fiber.Ctx) error {
+	var req dto.ForgotPasswordRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	h.svc.ForgotPassword(
+		c.UserContext(),
+		req.Data.Attributes.Email,
+		c.IP(),
+		c.Get(fiber.HeaderUserAgent),
+	)
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_forgot_password",
+		Attributes: map[string]any{
+			"message": "If the account exists, a password reset link has been sent.",
+		},
+	})
+}
+
+// ResetPassword godoc
+// @Summary Reset password
+// @Description Resets password using a single-use reset token.
+// @Tags Auth - Forgot Password
+// @Accept json
+// @Produce json
+// @Param request body dto.ResetPasswordRequest true "JSON:API Reset password request"
+// @Success 200 {object} dto.AuthSessionDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/reset-password [post]
+func (h *AuthHandler) ResetPassword(c *fiber.Ctx) error {
+	var req dto.ResetPasswordRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if req.Data.Attributes.NewPassword != req.Data.Attributes.ConfirmPassword {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "confirm_password must match new_password",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/confirm_password"},
+		}})
+	}
+
+	if err := h.svc.ResetPassword(c.UserContext(), req.Data.Attributes.Token, req.Data.Attributes.NewPassword); err != nil {
+		if errors.Is(err, service.ErrInvalidResetLink) || errors.Is(err, service.ErrInvalidToken) {
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Invalid reset link",
+				Detail: "This reset link is invalid or expired.",
+			}})
+		}
+		return writeAuthErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Reset password failed",
+			Detail: "unable to reset password at this time",
+		}})
+	}
+
+	clearAuthCookies(c, h.svc)
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_reset_password",
+		Attributes: map[string]any{
+			"message": "Password has been reset successfully. Please log in again.",
+		},
+	})
+}
+
+// SetupSecurityPIN godoc
+// @Summary Setup security PIN
+// @Description Creates a 6-digit security PIN for sensitive actions.
+// @Tags Auth - PIN
+// @Accept json
+// @Produce json
+// @Param request body dto.SecurityPINSetupRequest true "JSON:API security PIN setup request"
+// @Success 200 {object} dto.SecurityPINSetupResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 409 {object} dto.ErrorResponse
+// @Router /api/v1/auth/pin/setup [post]
+func (h *AuthHandler) SetupSecurityPIN(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		e := apperrorsx.New(apperrorsx.ErrUserUnauthorized)
+		e.Message = "missing auth context"
+		return apperrorsx.Write(c, e)
+	}
+
+	var req dto.SecurityPINSetupRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if req.Data.Attributes.PIN != req.Data.Attributes.ConfirmPIN {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "confirm_pin must match pin",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/confirm_pin"},
+		}})
+	}
+
+	if err := h.svc.SetSecurityPIN(c.UserContext(), userID, req.Data.Attributes.PIN); err != nil {
+		switch {
+		case errors.Is(err, service.ErrSecurityPINAlreadySet):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINNotSet))
+		case errors.Is(err, service.ErrInvalidSecurityPIN):
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "pin must be exactly 6 digits",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/pin"},
+			}})
+		default:
+			return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "AuthHandler.SetupSecurityPIN", err)
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_pin_setup",
+		Attributes: map[string]any{
+			"configured": true,
+		},
+	})
+}
+
+func derefString(v *string) string {
+	if v == nil {
+		return ""
+	}
+	return strings.TrimSpace(*v)
+}
+
+// VerifySecurityPIN godoc
+// @Summary Verify security PIN for sensitive action
+// @Description Verifies PIN and returns a short-lived one-time action token.
+// @Tags Auth - PIN
+// @Accept json
+// @Produce json
+// @Param request body dto.SecurityPINVerifyRequest true "JSON:API security PIN verify request"
+// @Success 200 {object} dto.SecurityPINVerifyResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 409 {object} dto.ErrorResponse
+// @Failure 429 {object} dto.ErrorResponse
+// @Router /api/v1/auth/pin/verify [post]
+func (h *AuthHandler) VerifySecurityPIN(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		e := apperrorsx.New(apperrorsx.ErrUserUnauthorized)
+		e.Message = "missing auth context"
+		return apperrorsx.Write(c, e)
+	}
+
+	var req dto.SecurityPINVerifyRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	sessionID := ""
+	if accessToken := readValidAccessToken(c, h.svc); accessToken != "" {
+		sid, err := h.svc.ParseAccessTokenSessionID(c.UserContext(), accessToken)
+		if err != nil {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTokenInvalid))
+		}
+		sessionID = sid
+	}
+
+	token, err := h.svc.VerifySecurityPINForActionInSession(c.UserContext(), userID, req.Data.Attributes.PIN, req.Data.Attributes.Action, sessionID)
+	if err != nil {
+		switch {
+		case errors.Is(err, service.ErrSecurityPINNotSet):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINNotSet))
+		case errors.Is(err, service.ErrSecurityPINLocked):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINBlocked))
+		case errors.Is(err, service.ErrSecurityPINAttemptLimit):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINBlocked))
+		case errors.Is(err, service.ErrSecurityPINResetRequired):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINBlocked))
+		case errors.Is(err, service.ErrInvalidSecurityPIN):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINIncorrect))
+		default:
+			return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "AuthHandler.VerifySecurityPIN", err)
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_pin_verify",
+		Attributes: map[string]any{
+			"verified":            true,
+			"action_token":        token,
+			"action_token_ttl_ms": h.svc.SecurityPINTokenTTL().Milliseconds(),
+		},
+	})
+}
+
+// ChangeSecurityPIN godoc
+// @Summary Change security PIN
+// @Tags Auth - PIN
+// @Accept json
+// @Produce json
+// @Param request body dto.SecurityPINChangeRequest true "JSON:API security PIN change request"
+// @Success 200 {object} dto.AuthSessionsResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 429 {object} dto.ErrorResponse
+// @Router /api/v1/auth/pin/change [post]
+func (h *AuthHandler) ChangeSecurityPIN(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		e := apperrorsx.New(apperrorsx.ErrUserUnauthorized)
+		e.Message = "missing auth context"
+		return apperrorsx.Write(c, e)
+	}
+
+	var req dto.SecurityPINChangeRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if req.Data.Attributes.NewPIN != req.Data.Attributes.ConfirmPIN {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "confirm_pin must match new_pin",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/confirm_pin"},
+		}})
+	}
+
+	if err := h.svc.ChangeSecurityPIN(c.UserContext(), userID, req.Data.Attributes.CurrentPIN, req.Data.Attributes.NewPIN); err != nil {
+		switch {
+		case errors.Is(err, service.ErrSecurityPINNotSet):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINNotSet))
+		case errors.Is(err, service.ErrSecurityPINLocked):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINBlocked))
+		case errors.Is(err, service.ErrSecurityPINAttemptLimit):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINBlocked))
+		case errors.Is(err, service.ErrSecurityPINResetRequired):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINBlocked))
+		case errors.Is(err, service.ErrInvalidSecurityPIN):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINIncorrect))
+		default:
+			return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "AuthHandler.ChangeSecurityPIN", err)
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_pin_change",
+		Attributes: map[string]any{
+			"updated": true,
+		},
+	})
+}
+
+// ForgotSecurityPIN godoc
+// @Summary Forgot security PIN
+// @Description Always returns a generic success response.
+// @Tags Auth - PIN
+// @Accept json
+// @Produce json
+// @Param request body dto.ForgotSecurityPINRequest true "JSON:API forgot security PIN request"
+// @Success 200 {object} dto.AuthSessionDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/pin/forgot [post]
+func (h *AuthHandler) ForgotSecurityPIN(c *fiber.Ctx) error {
+	var req dto.ForgotSecurityPINRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	h.svc.ForgotSecurityPIN(
+		c.UserContext(),
+		req.Data.Attributes.Email,
+		c.IP(),
+		c.Get(fiber.HeaderUserAgent),
+	)
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_forgot_pin",
+		Attributes: map[string]any{
+			"message": "If the account exists, a security PIN reset link has been sent.",
+		},
+	})
+}
+
+// RequestSecurityPINReset godoc
+// @Summary Request security PIN reset email for blocked PIN
+// @Description Verifies current account password, then sends PIN reset email to currently logged-in user when PIN is blocked.
+// @Tags Auth - PIN
+// @Accept json
+// @Produce json
+// @Param request body dto.RequestSecurityPINRequest true "JSON:API request security PIN reset payload"
+// @Success 200 {object} dto.RequestSecurityPINResetResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 409 {object} dto.ErrorResponse
+// @Failure 429 {object} dto.ErrorResponse
+// @Failure 500 {object} dto.ErrorResponse
+// @Router /api/v1/auth/pin/request-reset [post]
+func (h *AuthHandler) RequestSecurityPINReset(c *fiber.Ctx) error {
+	var req dto.RequestSecurityPINRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		e := apperrorsx.New(apperrorsx.ErrUserUnauthorized)
+		e.Message = "missing auth context"
+		return apperrorsx.Write(c, e)
+	}
+
+	method := strings.ToLower(strings.TrimSpace(req.Data.Attributes.Method))
+	if method == "" {
+		method = "password"
+	}
+	switch method {
+	case "password":
+		if strings.TrimSpace(req.Data.Attributes.Password) == "" {
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "password is required when method is password",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/password"},
+			}})
+		}
+	case "microsoft":
+		if strings.TrimSpace(req.Data.Attributes.ReauthToken) == "" {
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "reauth_token is required when method is microsoft",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/reauth_token"},
+			}})
+		}
+	default:
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "method must be one of: password, microsoft",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/method"},
+		}})
+	}
+
+	if err := h.svc.RequestSecurityPINReset(c.UserContext(), userID, method, req.Data.Attributes.Password, req.Data.Attributes.ReauthToken, c.IP(), c.Get(fiber.HeaderUserAgent)); err != nil {
+		switch {
+		case errors.Is(err, service.ErrInvalidPINResetPassword):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrUserUnauthorized))
+		case errors.Is(err, service.ErrInvalidSSOReauth):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTokenInvalid))
+		case errors.Is(err, service.ErrInvalidReauthMethod):
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "method must be one of: password, microsoft",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/method"},
+			}})
+		case errors.Is(err, service.ErrSecurityPINNotBlocked):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINNotBlocked))
+		case errors.Is(err, service.ErrSecurityPINResetRatelimit):
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINAttemptLimitReached))
+		default:
+			return writeAuthErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+				Status: "500",
+				Title:  "Reset request failed",
+				Detail: "unable to send reset email at this time",
+			}})
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_pin_request_reset",
+		Attributes: map[string]any{
+			"message": "If allowed, a security PIN reset link has been sent to your email.",
+		},
+	})
+}
+
+// ResetSecurityPIN godoc
+// @Summary Reset security PIN
+// @Description Resets security PIN using a re-auth method. For method=password, send the single-use reset token from the email link plus password. For method=microsoft, send only reauth_token from Microsoft re-auth.
+// @Tags Auth - PIN
+// @Accept json
+// @Produce json
+// @Param request body dto.ResetSecurityPINRequest true "JSON:API reset security PIN request"
+// @Success 200 {object} dto.AuthSessionsResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/pin/reset [post]
+func (h *AuthHandler) ResetSecurityPIN(c *fiber.Ctx) error {
+	var req dto.ResetSecurityPINRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if req.Data.Attributes.NewPIN != req.Data.Attributes.ConfirmPIN {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "confirm_pin must match new_pin",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/confirm_pin"},
+		}})
+	}
+
+	method := strings.ToLower(strings.TrimSpace(req.Data.Attributes.Method))
+	if method == "" {
+		method = "password"
+	}
+	switch method {
+	case "password":
+		if strings.TrimSpace(req.Data.Attributes.Token) == "" {
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "token is required when method is password",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/token"},
+			}})
+		}
+		if strings.TrimSpace(req.Data.Attributes.Password) == "" {
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "password is required when method is password",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/password"},
+			}})
+		}
+	case "microsoft":
+		if strings.TrimSpace(req.Data.Attributes.ReauthToken) == "" {
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "reauth_token is required when method is microsoft",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/reauth_token"},
+			}})
+		}
+	default:
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "method must be one of: password, microsoft",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/method"},
+		}})
+	}
+
+	if err := h.svc.ResetSecurityPIN(c.UserContext(), req.Data.Attributes.Token, method, req.Data.Attributes.Password, req.Data.Attributes.ReauthToken, req.Data.Attributes.NewPIN); err != nil {
+		if errors.Is(err, service.ErrInvalidResetLink) {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrInvalidRequest))
+		}
+		if errors.Is(err, service.ErrInvalidPINResetPassword) {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrUserUnauthorized))
+		}
+		if errors.Is(err, service.ErrInvalidSSOReauth) {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTokenInvalid))
+		}
+		if errors.Is(err, service.ErrInvalidReauthMethod) {
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "method must be one of: password, microsoft",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/method"},
+			}})
+		}
+		if errors.Is(err, service.ErrInvalidSecurityPIN) {
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "new_pin must be exactly 6 digits",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/new_pin"},
+			}})
+		}
+		return writeAuthErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Reset security PIN failed",
+			Detail: "unable to reset security PIN at this time",
+		}})
+	}
+
+	attrs := map[string]any{
+		"message":       "Security PIN has been reset successfully.",
+		"reset_success": true,
+	}
+	if redirectURL := strings.TrimSpace(h.svc.SSOSuccessRedirectURL()); redirectURL != "" {
+		attrs["redirect_url"] = redirectURL
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type:       "auth_reset_pin",
+		Attributes: attrs,
+	})
+}
+
+// Login godoc
+// @Summary Login with email & password
+// @Description If TOTP enabled, returns 202 + challenge_token (use /auth/totp/verify).
+// @Description If TOTP is not enabled, returns 202 + email OTP challenge_token (use /auth/email-otp/send then /auth/email-otp/verify).
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.LoginRequest true "JSON:API Login request"
+// @Success 200 {object} dto.AuthCurrentUserResponse
+// @Success 202 {object} dto.LoginTOTPRequiredResponse
+// @Success 202 {object} dto.LoginEmailOTPRequiredResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/login [post]
+func (h *AuthHandler) Login(c *fiber.Ctx) error {
+	var req dto.LoginRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	user, err := h.svc.LoginWithEmailPassword(c.UserContext(), req.Data.Attributes.Email, req.Data.Attributes.Password)
+	if err != nil {
+		return apperrorsx.Write(c, apperrorsx.Translate(apperrorsx.ModuleAuth, err))
+	}
+
+	totpEnabled, _ := h.svc.IsTOTPEnabled(c.UserContext(), user.ID)
+	webauthnConfigured, _ := h.svc.IsWebAuthnConfigured(c.UserContext(), user.ID)
+	linkedSSO, _ := h.svc.IsSSOLinked(c.UserContext(), user.ID)
+	pinConfigured := len(user.SecurityPINHash) > 0
+	if totpEnabled {
+		token, err := h.svc.CreateTOTPChallenge(c.UserContext(), user.ID)
+		if err != nil {
+			return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "AuthHandler.Login.CreateTOTPChallenge", err)
+		}
+
+		attrs := map[string]any{
+			"requires_totp":       true,
+			"challenge_token":     token,
+			"totp_enabled":        true,
+			"email_otp_enabled":   false,
+			"webauthn_configured": webauthnConfigured,
+			"linked_sso":          linkedSSO,
+			"pin_configured":      pinConfigured,
+		}
+
+		// When email OTP is enabled globally, mint a parallel email-OTP challenge
+		// so the user can fall back to email verification without re-submitting credentials.
+		if h.svc.IsLoginEmailOTPEnabled(c.UserContext()) {
+			emailToken, emailErr := h.svc.CreateEmailOTPChallenge(c.UserContext(), user.ID)
+			if emailErr == nil {
+				attrs["email_otp_enabled"] = true
+				attrs["email_otp_challenge_token"] = emailToken
+				attrs["email_otp_resend_cooldown_seconds"] = int(h.svc.EmailOTPResendCooldown().Seconds())
+				attrs["email_otp_max_resend_per_hour"] = h.svc.EmailOTPMaxResendPerHour()
+			}
+		}
+
+		return response.Write(c, fiber.StatusAccepted, jsonapi.Resource{
+			Type:       "auth_totp_required",
+			Attributes: attrs,
+		})
+	}
+
+	if !h.svc.IsLoginEmailOTPEnabled(c.UserContext()) {
+		tokens, err := h.svc.IssueTokensWithClientAndDeviceType(
+			c.UserContext(),
+			user,
+			c.Get(fiber.HeaderUserAgent),
+			c.IP(),
+			readDeviceTypeHint(c),
+		)
+		if err != nil {
+			return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "AuthHandler.Login.IssueTokens", err)
+		}
+		setAuthCookies(c, h.svc, tokens)
+		return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+			Type: "auth_tokens",
+			Attributes: map[string]any{
+				"access_expires_in":   int64(h.svc.AccessTTL().Seconds()),
+				"refresh_expires_in":  int64(tokens.RefreshTTL.Seconds()),
+				"requires_totp_setup": true,
+				"email_otp_enabled":   false,
+			},
+		})
+	}
+
+	emailChallengeToken, err := h.svc.CreateEmailOTPChallenge(c.UserContext(), user.ID)
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Email OTP challenge failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	return response.Write(c, fiber.StatusAccepted, jsonapi.Resource{
+		Type: "auth_email_otp_required",
+		Attributes: map[string]any{
+			"requires_email_otp":      true,
+			"challenge_token":         emailChallengeToken,
+			"resend_cooldown_seconds": int(h.svc.EmailOTPResendCooldown().Seconds()),
+			"max_resend_per_hour":     h.svc.EmailOTPMaxResendPerHour(),
+			"requires_totp_setup":     true,
+			"webauthn_configured":     webauthnConfigured,
+			"linked_sso":              linkedSSO,
+			"pin_configured":          pinConfigured,
+		},
+	})
+}
+
+// Exchange godoc
+// @Summary Exchange frontend Microsoft SSO token into backend session
+// @Description Accepts Microsoft token payload from frontend ssoSilent and issues backend auth cookies.
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.ExchangeRequest true "JSON:API Exchange request"
+// @Success 200 {object} dto.TokenResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/exchange [post]
+func (h *AuthHandler) Exchange(c *fiber.Ctx) error {
+	var req dto.ExchangeRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	identity, err := h.svc.ExchangeMicrosoftToken(
+		c.UserContext(),
+		req.Data.Attributes.AccessToken,
+		req.Data.Attributes.IDToken,
+		req.Data.Attributes.IDTokenClaims.ToMap(),
+	)
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	user, err := h.svc.GetUserByID(c.UserContext(), identity.UserID)
+	if err != nil || user == nil {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "linked user is not found",
+		}})
+	}
+
+	// Issue internal session tokens. Keep auth provider as local since FE-managed ssoSilent
+	// does not provide backend-managed Microsoft refresh token.
+	tokens, err := h.svc.IssueTokensWithClientAndDeviceType(
+		c.UserContext(),
+		user,
+		c.Get(fiber.HeaderUserAgent),
+		c.IP(),
+		readDeviceTypeHint(c),
+	)
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Token issue failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	setAuthCookies(c, h.svc, tokens)
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_tokens",
+		Attributes: map[string]any{
+			"access_expires_in":  int64(h.svc.AccessTTL().Seconds()),
+			"refresh_expires_in": int64(tokens.RefreshTTL.Seconds()),
+		},
+	})
+}
+
+// VerifyEmail godoc
+// @Summary Verify email
+// @Description Confirms email verification after register.
+// @Tags Auth
+// @Produce json
+// @Param token query string true "Verification token"
+// @Success 200 {object} dto.AuthSessionDeleteResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/verify-email [get]
+func (h *AuthHandler) VerifyEmail(c *fiber.Ctx) error {
+	token := c.Query("token")
+	if token == "" {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid token",
+			Detail: "token is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/query/token"},
+		}})
+	}
+	if err := h.svc.VerifyEmail(c.UserContext(), token); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid token",
+			Detail: "an internal error occurred",
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_verify_email",
+		Attributes: map[string]any{
+			"verified": true,
+		},
+	})
+}
+
+// MicrosoftLogin godoc
+// @Summary Microsoft Entra SSO login
+// @Description Returns JSON:API payload containing Microsoft authorization URL.
+// @Description Backend starts with silent session-check (`prompt=none`). If Microsoft session is inactive, callback automatically falls back to interactive login.
+// @Tags Auth
+// @Produce json
+// @Success 200 {object} dto.MicrosoftLoginResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/microsoft/login [get]
+func (h *AuthHandler) MicrosoftLogin(c *fiber.Ctx) error {
+	// Interactive sign-in for an explicit "Login with Microsoft" action. Silent session
+	// checks (prompt=none) are served separately by /microsoft/login-check.
+	urlStr, err := h.svc.BeginMicrosoftLogin(c.UserContext())
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "SSO not configured",
+			Detail: "an internal error occurred",
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_microsoft_url",
+		Attributes: map[string]any{
+			"url":          urlStr,
+			"redirect_url": urlStr,
+		},
+	})
+}
+
+// MicrosoftLoginCheck godoc
+// @Summary Microsoft Entra silent session check URL
+// @Description Returns JSON:API payload containing Microsoft authorization URL with prompt=none for strict session check.
+// @Tags Auth
+// @Produce json
+// @Success 200 {object} dto.MicrosoftLoginResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/microsoft/login-check [get]
+func (h *AuthHandler) MicrosoftLoginCheck(c *fiber.Ctx) error {
+	urlStr, err := h.svc.BeginMicrosoftSessionCheckStrict(c.UserContext())
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "SSO not configured",
+			Detail: "an internal error occurred",
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_microsoft_url",
+		Attributes: map[string]any{
+			"url":          urlStr,
+			"redirect_url": urlStr,
+		},
+	})
+}
+
+// MicrosoftLink godoc
+// @Summary Microsoft Entra SSO link URL
+// @Description Returns JSON:API payload containing Microsoft authorization URL for linking SSO to the current authenticated user.
+// @Tags Auth
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} dto.MicrosoftLoginResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Router /api/v1/auth/microsoft/link [get]
+func (h *AuthHandler) MicrosoftLink(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+	urlStr, err := h.svc.BeginMicrosoftLink(c.UserContext(), userID)
+	if err != nil {
+		status := fiber.StatusBadRequest
+		title := "SSO link failed"
+		detail := "an internal error occurred"
+		if errors.Is(err, service.ErrUserNotFound) {
+			status = fiber.StatusNotFound
+			title = "User not found"
+			detail = "user not found"
+		}
+		return writeAuthErrors(c, status, []jsonapi.ErrorObject{{
+			Status: strconv.Itoa(status),
+			Title:  title,
+			Detail: detail,
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_microsoft_url",
+		Attributes: map[string]any{
+			"url":          urlStr,
+			"redirect_url": urlStr,
+		},
+	})
+}
+
+// MicrosoftReauth godoc
+// @Summary Microsoft Entra SSO reauth URL
+// @Description Starts a Microsoft reauthentication flow for supported sensitive actions.
+// @Tags Auth
+// @Produce json
+// @Param purpose query string true "Supported values: pin_reset_request, pin_reset_confirm"
+// @Param token query string false "Required when purpose=pin_reset_confirm"
+// @Success 200 {object} dto.MicrosoftLoginResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Router /api/v1/auth/microsoft/reauth [get]
+func (h *AuthHandler) MicrosoftReauth(c *fiber.Ctx) error {
+	purpose := strings.TrimSpace(c.Query("purpose"))
+	var (
+		urlStr string
+		err    error
+	)
+
+	switch purpose {
+	case "pin_reset_request":
+		userID, ok := c.Locals("user_id").([]byte)
+		if !ok || len(userID) == 0 {
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Unauthorized",
+				Detail: "missing auth context",
+			}})
+		}
+		urlStr, err = h.svc.BeginMicrosoftReauth(c.UserContext(), userID, purpose)
+	case "pin_reset_confirm":
+		urlStr, err = h.svc.BeginMicrosoftPINResetReauth(c.UserContext(), c.Query("token"))
+	default:
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid reauth request",
+			Detail: "purpose must be one of: pin_reset_request, pin_reset_confirm",
+		}})
+	}
+	if err != nil {
+		status := fiber.StatusBadRequest
+		title := "SSO reauth failed"
+		detail := "an internal error occurred"
+		if errors.Is(err, service.ErrInvalidResetLink) {
+			title = "Invalid reset link"
+			detail = "This reset link is invalid or expired."
+		}
+		return writeAuthErrors(c, status, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  title,
+			Detail: detail,
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_microsoft_url",
+		Attributes: map[string]any{
+			"url":          urlStr,
+			"redirect_url": urlStr,
+			"purpose":      purpose,
+		},
+	})
+}
+
+// MicrosoftCallback godoc
+// @Summary Microsoft Entra SSO callback
+// @Description Completes Microsoft SSO login. Login succeeds only when SSO identity is already linked to an existing user.
+// @Tags Auth
+// @Produce json
+// @Param code query string true "Authorization code"
+// @Param state query string true "State"
+// @Success 200 {object} dto.MicrosoftCallbackResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/auth/microsoft/callback [get]
+func (h *AuthHandler) MicrosoftCallback(c *fiber.Ctx) error {
+	requestID := strings.TrimSpace(c.GetRespHeader(fiber.HeaderXRequestID))
+	if requestID == "" {
+		requestID = strings.TrimSpace(c.Get(fiber.HeaderXRequestID))
+	}
+	if requestID == "" {
+		requestID = strings.TrimSpace(c.Get("X-Request-Id"))
+	}
+	if requestID == "" {
+		requestID = strings.TrimSpace(c.Get("X-Request-ID"))
+	}
+	if requestID == "" {
+		requestID = strings.TrimSpace(c.Get("x-request-id"))
+	}
+	if requestID == "" {
+		requestID = strings.TrimSpace(c.Get("x-requestid"))
+	}
+	if requestID == "" {
+		if v := c.Locals("requestid"); v != nil {
+			requestID = strings.TrimSpace(fmt.Sprint(v))
+		}
+	}
+
+	logCallbackFailure := func(status int, reason, title, detail string, cause error) {
+		args := []any{
+			slog.String("request_id", requestID),
+			slog.Int("status", status),
+			slog.String("reason", strings.TrimSpace(reason)),
+			slog.String("title", strings.TrimSpace(title)),
+			slog.String("detail", strings.TrimSpace(detail)),
+			slog.String("path", c.Path()),
+			slog.String("mode", strings.TrimSpace(c.Query("mode"))),
+			slog.String("state", strings.TrimSpace(c.Query("state"))),
+			slog.String("microsoft_error", strings.TrimSpace(c.Query("error"))),
+			slog.Bool("has_code", strings.TrimSpace(c.Query("code")) != ""),
+		}
+		if cause != nil {
+			args = append(args, slog.Any("cause", cause))
+		}
+		slog.WarnContext(c.UserContext(), "microsoft callback failed", args...)
+	}
+
+	writeCallbackError := func(status int, title, detail, reason string, source *jsonapi.ErrorSource) error {
+		logCallbackFailure(status, reason, title, detail, nil)
+		if redirect := strings.TrimSpace(h.svc.SSOSuccessRedirectURL()); redirect != "" && shouldUseBrowserRedirect(c) {
+			if redirectURL, parseErr := url.Parse(redirect); parseErr == nil {
+				q := redirectURL.Query()
+				q.Set("sso", "error")
+				q.Set("status", strconv.Itoa(status))
+				if strings.TrimSpace(reason) != "" {
+					q.Set("reason", strings.TrimSpace(reason))
+				}
+				if strings.TrimSpace(title) != "" {
+					q.Set("title", strings.TrimSpace(title))
+				}
+				redirectURL.RawQuery = q.Encode()
+				return c.Redirect(redirectURL.String(), fiber.StatusFound)
+			}
+		}
+		errObj := jsonapi.ErrorObject{
+			Status: strconv.Itoa(status),
+			Title:  title,
+			Detail: detail,
+			Source: source,
+		}
+		return writeAuthErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+
+	code := strings.TrimSpace(c.Query("code"))
+	state := strings.TrimSpace(c.Query("state"))
+	if state == "" {
+		return writeCallbackError(fiber.StatusBadRequest, "Invalid callback", "state is required", "invalid_callback", nil)
+	}
+	mode, err := h.svc.MicrosoftStateMode(c.UserContext(), state)
+	if err != nil {
+		logCallbackFailure(
+			fiber.StatusBadRequest,
+			"invalid_callback_state",
+			"Invalid callback state",
+			err.Error(),
+			err,
+		)
+		return writeCallbackError(
+			fiber.StatusBadRequest,
+			"Invalid callback state",
+			"an internal error occurred",
+			"invalid_callback_state",
+			&jsonapi.ErrorSource{Pointer: "/query/state"},
+		)
+	}
+	if code == "" {
+		ssoErr := strings.TrimSpace(c.Query("error"))
+		if mode == "login_check" {
+			h.svc.ClearMicrosoftState(c.UserContext(), state)
+			if ssoErr != "" {
+				urlStr, loginErr := h.svc.BeginMicrosoftLogin(c.UserContext())
+				if loginErr != nil {
+					return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+						Status: "401",
+						Title:  "Microsoft session not active",
+						Detail: "microsoft sso session is not active: " + ssoErr,
+					}})
+				}
+				if shouldUseBrowserRedirect(c) {
+					return c.Redirect(urlStr, fiber.StatusFound)
+				}
+				return response.Write(c, fiber.StatusUnauthorized, jsonapi.Resource{
+					Type: "auth_microsoft_url",
+					Attributes: map[string]any{
+						"url":                  urlStr,
+						"redirect_url":         urlStr,
+						"interaction_required": true,
+						"microsoft_error":      ssoErr,
+					},
+				})
+			}
+		}
+		if mode == "login_check_strict" && isMicrosoftInteractionRequiredError(ssoErr) {
+			h.svc.ClearMicrosoftState(c.UserContext(), state)
+			urlStr, loginErr := h.svc.BeginMicrosoftLogin(c.UserContext())
+			if loginErr != nil {
+				return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+					Status: "401",
+					Title:  "Microsoft session not active",
+					Detail: "microsoft sso session is not active: " + ssoErr,
+				}})
+			}
+			if shouldUseBrowserRedirect(c) {
+				return c.Redirect(urlStr, fiber.StatusFound)
+			}
+			return response.Write(c, fiber.StatusUnauthorized, jsonapi.Resource{
+				Type: "auth_microsoft_url",
+				Attributes: map[string]any{
+					"url":                  urlStr,
+					"redirect_url":         urlStr,
+					"interaction_required": true,
+					"microsoft_error":      ssoErr,
+				},
+			})
+		}
+		if mode == "login_check_strict" {
+			h.svc.ClearMicrosoftState(c.UserContext(), state)
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Microsoft session not active",
+				Detail: "microsoft sso session is not active",
+			}})
+		}
+		return writeCallbackError(fiber.StatusBadRequest, "Invalid callback", "code is required", "missing_code", nil)
+	}
+
+	if mode == "reauth" {
+		reauthToken, purpose, err := h.svc.CompleteMicrosoftReauth(c.UserContext(), code, state)
+		if err != nil {
+			status := fiber.StatusBadRequest
+			title := "SSO reauth failed"
+			if errors.Is(err, service.ErrInvalidSSOState) {
+				title = "Invalid callback state"
+			}
+			if errors.Is(err, service.ErrInvalidSSOReauth) {
+				status = fiber.StatusUnauthorized
+			}
+			reason := "sso_reauth_failed"
+			if status == fiber.StatusUnauthorized {
+				reason = "invalid_sso_reauth"
+			}
+			logCallbackFailure(status, reason, title, err.Error(), err)
+			return writeCallbackError(status, title, "an internal error occurred", reason, nil)
+		}
+		if redirect := strings.TrimSpace(h.svc.SSOSuccessRedirectURL()); redirect != "" && shouldUseBrowserRedirect(c) {
+			redirectURL, parseErr := url.Parse(redirect)
+			if parseErr == nil {
+				q := redirectURL.Query()
+				q.Set("sso_reauth", "1")
+				q.Set("purpose", purpose)
+				q.Set("reauth_token", reauthToken)
+				redirectURL.RawQuery = q.Encode()
+				return c.Redirect(redirectURL.String(), fiber.StatusFound)
+			}
+		}
+		return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+			Type: "auth_microsoft_reauth",
+			Attributes: map[string]any{
+				"purpose":      purpose,
+				"reauth_token": reauthToken,
+			},
+		})
+	}
+
+	if mode == "link" {
+		identity, err := h.svc.CompleteMicrosoftLink(c.UserContext(), code, state)
+		if err != nil {
+			logCallbackFailure(fiber.StatusBadRequest, "sso_link_failed", "SSO link failed", err.Error(), err)
+			switch {
+			case errors.Is(err, service.ErrInvalidSSOState):
+				return writeCallbackError(
+					fiber.StatusBadRequest,
+					"Invalid callback state",
+					"an internal error occurred",
+					"invalid_callback_state",
+					&jsonapi.ErrorSource{Pointer: "/query/state"},
+				)
+			case errors.Is(err, service.ErrUserNotFound):
+				return writeCallbackError(fiber.StatusNotFound, "User not found", "user not found", "user_not_found", nil)
+			case errors.Is(err, service.ErrSSOAlreadyLinked):
+				return writeCallbackError(
+					fiber.StatusConflict,
+					"SSO already linked",
+					"user already has an sso mapping",
+					"sso_already_linked",
+					nil,
+				)
+			case errors.Is(err, service.ErrSSOLinkedToAnotherUser):
+				return writeCallbackError(
+					fiber.StatusConflict,
+					"SSO linked to another user",
+					"this sso account is already linked to another user",
+					"sso_linked_to_another_user",
+					nil,
+				)
+			default:
+				return writeCallbackError(fiber.StatusBadRequest, "SSO link failed", "an internal error occurred", "sso_link_failed", nil)
+			}
+		}
+		if redirect := strings.TrimSpace(h.svc.SSOSuccessRedirectURL()); redirect != "" && shouldUseBrowserRedirect(c) {
+			redirectURL, parseErr := url.Parse(redirect)
+			if parseErr == nil {
+				q := redirectURL.Query()
+				q.Set("sso_link", "1")
+				q.Set("provider", identity.Provider)
+				redirectURL.RawQuery = q.Encode()
+				return c.Redirect(redirectURL.String(), fiber.StatusFound)
+			}
+		}
+		return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+			Type: "auth_sso_link",
+			Attributes: map[string]any{
+				"provider":         identity.Provider,
+				"provider_subject": identity.ProviderSubject,
+				"email":            identity.Email,
+			},
+		})
+	}
+
+	if mode == "login_check_strict" {
+		if _, _, err := h.svc.CompleteMicrosoftLogin(c.UserContext(), code, state); err != nil {
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Microsoft session not active",
+				Detail: "microsoft sso session is not active",
+			}})
+		}
+		return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+			Type: "auth_microsoft_session",
+			Attributes: map[string]any{
+				"active": true,
+			},
+		})
+	}
+
+	identity, microsoftSessionID, err := h.svc.CompleteMicrosoftLogin(c.UserContext(), code, state)
+	if err != nil {
+		logCallbackFailure(fiber.StatusBadRequest, "sso_login_failed", "SSO login failed", err.Error(), err)
+		switch {
+		case errors.Is(err, service.ErrInvalidSSOState):
+			return writeCallbackError(
+				fiber.StatusBadRequest,
+				"Invalid callback state",
+				"an internal error occurred",
+				"invalid_callback_state",
+				&jsonapi.ErrorSource{Pointer: "/query/state"},
+			)
+		case errors.Is(err, service.ErrSSONotLinked):
+			return writeCallbackError(
+				fiber.StatusUnauthorized,
+				"SSO not linked",
+				"sso identity is not linked to any user",
+				"sso_not_linked",
+				nil,
+			)
+		case errors.Is(err, service.ErrSSOEmailNotFound):
+			return writeCallbackError(
+				fiber.StatusUnauthorized,
+				"SSO email not found",
+				"sso account email is not registered",
+				"sso_email_not_found",
+				nil,
+			)
+		case errors.Is(err, service.ErrUserNotFound):
+			return writeCallbackError(fiber.StatusNotFound, "User not found", "linked user is not found", "user_not_found", nil)
+		default:
+			return writeCallbackError(fiber.StatusBadRequest, "SSO login failed", "an internal error occurred", "sso_login_failed", nil)
+		}
+	}
+
+	// Issue cookies and redirect to FE if configured
+	user, err := h.svc.GetUserByID(c.UserContext(), identity.UserID)
+	if err == nil && user != nil {
+		tokens, err := h.svc.IssueTokensWithClientForProviderAndMicrosoftSID(
+			c.UserContext(),
+			user,
+			c.Get(fiber.HeaderUserAgent),
+			c.IP(),
+			"microsoft",
+			microsoftSessionID,
+		)
+		if err == nil {
+			setAuthCookiesForProvider(c, h.svc, tokens, "microsoft")
+		}
+	}
+
+	if redirect := h.svc.SSOSuccessRedirectURL(); redirect != "" {
+		if shouldUseBrowserRedirect(c) {
+			return c.Redirect(redirect, fiber.StatusFound)
+		}
+	}
+
+	id, _ := uuidv7.BytesToString(identity.ID)
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_identity",
+		ID:   id,
+		Attributes: map[string]any{
+			"provider":         identity.Provider,
+			"provider_subject": identity.ProviderSubject,
+			"email":            identity.Email,
+		},
+	})
+}
+
+func isMicrosoftInteractionRequiredError(raw string) bool {
+	code := strings.ToLower(strings.TrimSpace(raw))
+	if code == "" {
+		return false
+	}
+	return strings.Contains(code, "aadsts16000") ||
+		code == "login_required" ||
+		code == "interaction_required" ||
+		code == "account_selection_required" ||
+		code == "consent_required"
+}
+
+// SSOLink godoc
+// @Summary Link Microsoft SSO to current user
+// @Description Link Microsoft SSO identity to the authenticated user. SSO login will only work after successful link.
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param request body dto.SSOLinkRequest true "JSON:API SSO link request"
+// @Success 200 {object} dto.SSOLinkResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 409 {object} dto.ErrorResponse
+// @Router /api/v1/auth/sso/link [post]
+func (h *AuthHandler) SSOLink(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	var req dto.SSOLinkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	identity, err := h.svc.LinkSSOForUser(c.UserContext(), userID, req.Data.Attributes.Provider, req.Data.Attributes.Code)
+	if err != nil {
+		switch {
+		case errors.Is(err, service.ErrUserNotFound):
+			return writeAuthErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "User not found",
+				Detail: "user not found",
+			}})
+		case errors.Is(err, service.ErrSSOAlreadyLinked):
+			return writeAuthErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "SSO already linked",
+				Detail: "user already has an sso mapping",
+			}})
+		case errors.Is(err, service.ErrSSOLinkedToAnotherUser):
+			return writeAuthErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "SSO linked to another user",
+				Detail: "this sso account is already linked to another user",
+			}})
+		case errors.Is(err, service.ErrUnsupportedSSOProvider):
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Unsupported SSO provider",
+				Detail: "unsupported sso provider",
+			}})
+		default:
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "SSO link failed",
+				Detail: "an internal error occurred",
+			}})
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_sso_link",
+		Attributes: map[string]any{
+			"provider":         identity.Provider,
+			"provider_subject": identity.ProviderSubject,
+			"email":            identity.Email,
+		},
+	})
+}
+
+// SSOUnlink godoc
+// @Summary Unlink Microsoft SSO from current user
+// @Description Remove Microsoft SSO mapping from authenticated user.
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param request body dto.SSOUnlinkRequest true "JSON:API SSO unlink request"
+// @Success 200 {object} dto.SSOUnlinkResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/auth/sso/unlink [delete]
+func (h *AuthHandler) SSOUnlink(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	var req dto.SSOUnlinkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if err := h.svc.UnlinkSSOForUser(c.UserContext(), userID, req.Data.Attributes.Provider); err != nil {
+		switch {
+		case errors.Is(err, service.ErrUserNotFound):
+			return writeAuthErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "User not found",
+				Detail: "user not found",
+			}})
+		case errors.Is(err, service.ErrSSONotLinked):
+			return writeAuthErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "SSO not linked",
+				Detail: "sso is not linked to this user",
+			}})
+		case errors.Is(err, service.ErrUnsupportedSSOProvider):
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Unsupported SSO provider",
+				Detail: "unsupported sso provider",
+			}})
+		default:
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "SSO unlink failed",
+				Detail: "an internal error occurred",
+			}})
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_sso_unlink",
+		Attributes: map[string]any{
+			"provider": req.Data.Attributes.Provider,
+			"unlinked": true,
+		},
+	})
+}
+
+func shouldUseBrowserRedirect(c *fiber.Ctx) bool {
+	if strings.EqualFold(strings.TrimSpace(c.Get("X-Requested-With")), "XMLHttpRequest") {
+		return false
+	}
+
+	mode := strings.ToLower(strings.TrimSpace(c.Get("Sec-Fetch-Mode")))
+	dest := strings.ToLower(strings.TrimSpace(c.Get("Sec-Fetch-Dest")))
+	if dest == "empty" || mode == "cors" || mode == "same-origin" {
+		return false
+	}
+
+	accept := strings.ToLower(strings.TrimSpace(c.Get(fiber.HeaderAccept)))
+	return !strings.Contains(accept, "application/json")
+}
+
+// WebAuthnRegisterBegin godoc
+// @Summary Begin WebAuthn registration
+// @Description Creates WebAuthn registration options for the authenticated user.
+// @Tags Auth - WebAuthn
+// @Accept json
+// @Produce json
+// @Param request body dto.WebAuthnRegisterBeginRequest true "JSON:API WebAuthn register begin request"
+// @Success 200 {object} dto.WebAuthnBeginResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 409 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/webauthn/register/begin [post]
+func (h *AuthHandler) WebAuthnRegisterBegin(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	var req dto.WebAuthnRegisterBeginRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	options, challengeToken, err := h.svc.BeginWebAuthnRegistration(c.UserContext(), userID)
+	if err != nil {
+		switch {
+		case errors.Is(err, service.ErrWebAuthnNotConfigured):
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "WebAuthn not configured",
+				Detail: "webauthn is not configured",
+			}})
+		default:
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "WebAuthn begin failed",
+				Detail: "an internal error occurred",
+			}})
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_webauthn_register_options",
+		Attributes: map[string]any{
+			"challenge_token":  challengeToken,
+			"challenge_ttl_ms": h.svc.WebAuthnChallengeTTL().Milliseconds(),
+			"public_key":       options.Response,
+		},
+	})
+}
+
+// WebAuthnRegisterFinish godoc
+// @Summary Finish WebAuthn registration
+// @Description Verifies WebAuthn registration response and stores the credential.
+// @Tags Auth - WebAuthn
+// @Accept json
+// @Produce json
+// @Param request body dto.WebAuthnRegisterFinishRequest true "JSON:API WebAuthn register finish request"
+// @Success 200 {object} dto.AuthSessionsResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 409 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/webauthn/register/finish [post]
+func (h *AuthHandler) WebAuthnRegisterFinish(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	var req dto.WebAuthnRegisterFinishRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if err := h.svc.FinishWebAuthnRegistration(c.UserContext(), userID, req.Data.Attributes.ChallengeToken, req.Data.Attributes.Credential, req.Data.Attributes.Name); err != nil {
+		switch {
+		case errors.Is(err, service.ErrWebAuthnNotConfigured):
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "WebAuthn not configured",
+				Detail: "webauthn is not configured",
+			}})
+		case errors.Is(err, service.ErrWebAuthnChallengeInvalid):
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Invalid challenge",
+				Detail: "challenge token is invalid or expired",
+			}})
+		case errors.Is(err, service.ErrWebAuthnPayloadInvalid):
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "credential payload is invalid",
+				Source: &jsonapi.ErrorSource{
+					Pointer: "/data/attributes/credential",
+				},
+			}})
+		case errors.Is(err, service.ErrWebAuthnCredentialExists):
+			return writeAuthErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "Credential already exists",
+				Detail: "credential has already been registered",
+			}})
+		case errors.Is(err, service.ErrWebAuthnVerificationFailed):
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Verification failed",
+				Detail: "unable to verify webauthn credential",
+			}})
+		default:
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "WebAuthn registration failed",
+				Detail: "an internal error occurred",
+			}})
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_webauthn_register",
+		Attributes: map[string]any{
+			"registered": true,
+		},
+	})
+}
+
+// WebAuthnLoginBegin godoc
+// @Summary Begin WebAuthn login
+// @Description Creates WebAuthn assertion options for a user email.
+// @Tags Auth - WebAuthn
+// @Accept json
+// @Produce json
+// @Param request body dto.WebAuthnLoginBeginRequest true "JSON:API WebAuthn login begin request"
+// @Success 200 {object} dto.WebAuthnBeginResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 409 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/webauthn/login/begin [post]
+func (h *AuthHandler) WebAuthnLoginBegin(c *fiber.Ctx) error {
+	var req dto.WebAuthnLoginBeginRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	options, challengeToken, err := h.svc.BeginWebAuthnLogin(c.UserContext(), req.Data.Attributes.Email)
+	if err != nil {
+		switch {
+		case errors.Is(err, service.ErrInvalidCredentials), errors.Is(err, service.ErrEmailNotVerified):
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Unauthorized",
+				Detail: "invalid credentials",
+			}})
+		case errors.Is(err, service.ErrWebAuthnCredentialUnavailable):
+			return writeAuthErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "No WebAuthn credential",
+				Detail: "webauthn credential is not configured for this account",
+			}})
+		case errors.Is(err, service.ErrWebAuthnNotConfigured):
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "WebAuthn not configured",
+				Detail: "webauthn is not configured",
+			}})
+		default:
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "WebAuthn begin failed",
+				Detail: "an internal error occurred",
+			}})
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_webauthn_login_options",
+		Attributes: map[string]any{
+			"challenge_token":  challengeToken,
+			"challenge_ttl_ms": h.svc.WebAuthnChallengeTTL().Milliseconds(),
+			"public_key":       options.Response,
+		},
+	})
+}
+
+// WebAuthnLoginFinish godoc
+// @Summary Finish WebAuthn login
+// @Description Verifies WebAuthn assertion and issues auth cookies.
+// @Tags Auth - WebAuthn
+// @Accept json
+// @Produce json
+// @Param request body dto.WebAuthnLoginFinishRequest true "JSON:API WebAuthn login finish request"
+// @Success 200 {object} dto.TokenResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 409 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/webauthn/login/finish [post]
+func (h *AuthHandler) WebAuthnLoginFinish(c *fiber.Ctx) error {
+	var req dto.WebAuthnLoginFinishRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	user, err := h.svc.FinishWebAuthnLogin(c.UserContext(), req.Data.Attributes.ChallengeToken, req.Data.Attributes.Credential)
+	if err != nil {
+		switch {
+		case errors.Is(err, service.ErrWebAuthnChallengeInvalid):
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Invalid challenge",
+				Detail: "challenge token is invalid or expired",
+			}})
+		case errors.Is(err, service.ErrWebAuthnPayloadInvalid):
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "credential payload is invalid",
+				Source: &jsonapi.ErrorSource{
+					Pointer: "/data/attributes/credential",
+				},
+			}})
+		case errors.Is(err, service.ErrWebAuthnVerificationFailed), errors.Is(err, service.ErrInvalidCredentials):
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Unauthorized",
+				Detail: "invalid webauthn assertion",
+			}})
+		case errors.Is(err, service.ErrWebAuthnCredentialUnavailable):
+			return writeAuthErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "No WebAuthn credential",
+				Detail: "webauthn credential is not configured for this account",
+			}})
+		case errors.Is(err, service.ErrWebAuthnNotConfigured):
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "WebAuthn not configured",
+				Detail: "webauthn is not configured",
+			}})
+		default:
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "WebAuthn login failed",
+				Detail: "an internal error occurred",
+			}})
+		}
+	}
+
+	tokens, err := h.svc.IssueTokensWithClientAndDeviceType(
+		c.UserContext(),
+		user,
+		c.Get(fiber.HeaderUserAgent),
+		c.IP(),
+		readDeviceTypeHint(c),
+	)
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Token issue failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	setAuthCookies(c, h.svc, tokens)
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_tokens",
+		Attributes: map[string]any{
+			"access_expires_in":  int64(h.svc.AccessTTL().Seconds()),
+			"refresh_expires_in": int64(tokens.RefreshTTL.Seconds()),
+		},
+	})
+}
+
+// WebAuthnResetSetup godoc
+// @Summary Reset WebAuthn setup
+// @Description Removes all registered WebAuthn credentials so the user can re-setup passkeys.
+// @Description For method=pin, obtain token from /auth/pin/verify with action=1f7d457e-0a19-4a36-8d9f-2c66fd2369ab and send it in X-PIN-Verification-Token header.
+// @Tags Auth - WebAuthn
+// @Accept json
+// @Produce json
+// @Param request body dto.WebAuthnResetSetupRequest true "JSON:API WebAuthn reset setup request"
+// @Success 200 {object} dto.AuthSessionDeleteResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 409 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 429 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/webauthn/reset-setup [post]
+func (h *AuthHandler) WebAuthnResetSetup(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	var req dto.WebAuthnResetSetupRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	method := strings.ToLower(strings.TrimSpace(req.Data.Attributes.Method))
+	switch method {
+	case "pin":
+		sessionID := ""
+		if accessToken := readValidAccessToken(c, h.svc); accessToken != "" {
+			sid, err := h.svc.ParseAccessTokenSessionID(c.UserContext(), accessToken)
+			if err != nil {
+				return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+					Status: "401",
+					Title:  "Unauthorized",
+					Detail: "invalid or expired token",
+				}})
+			}
+			sessionID = sid
+		}
+		token := c.Get(pinVerificationHeader)
+		if err := h.svc.ConsumeSecurityPINActionTokenInSession(c.UserContext(), userID, sharedconst.PinActionWebAuthnResetSetup, token, sessionID); err != nil {
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "PIN verification required",
+				Detail: "valid PIN action token is required",
+				Source: &jsonapi.ErrorSource{Pointer: "/headers/X-PIN-Verification-Token"},
+			}})
+		}
+		if err := h.svc.DeleteWebAuthnSetup(c.UserContext(), userID); err != nil {
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "WebAuthn reset setup failed",
+				Detail: "an internal error occurred",
+			}})
+		}
+		return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+			Type: "auth_webauthn_reset_setup",
+			Attributes: map[string]any{
+				"reset": true,
+			},
+		})
+	case "password":
+		if req.Data.Attributes.Password == "" {
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "password is required when method is password",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/password"},
+			}})
+		}
+	default:
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "method must be one of: pin, password",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/method"},
+		}})
+	}
+
+	if err := h.svc.ResetWebAuthnSetup(c.UserContext(), userID, method, "", req.Data.Attributes.Password); err != nil {
+		switch {
+		case errors.Is(err, service.ErrInvalidReauthMethod):
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "method must be one of: pin, password",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/method"},
+			}})
+		case errors.Is(err, service.ErrInvalidCredentials), errors.Is(err, service.ErrInvalidSecurityPIN):
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Unauthorized",
+				Detail: "invalid authentication factor",
+			}})
+		case errors.Is(err, service.ErrSecurityPINNotSet):
+			return writeAuthErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "PIN not configured",
+				Detail: "security PIN is not set",
+			}})
+		case errors.Is(err, service.ErrSecurityPINAttemptLimit):
+			return writeAuthErrors(c, fiber.StatusLocked, []jsonapi.ErrorObject{{
+				Status: "423",
+				Title:  "PIN blocked",
+				Detail: "security PIN is blocked. reset PIN is required.",
+			}})
+		case errors.Is(err, service.ErrSecurityPINLocked), errors.Is(err, service.ErrSecurityPINResetRequired):
+			return writeAuthErrors(c, fiber.StatusLocked, []jsonapi.ErrorObject{{
+				Status: "423",
+				Title:  "PIN blocked",
+				Detail: "security PIN is blocked. reset PIN is required.",
+			}})
+		case errors.Is(err, service.ErrInvalidToken):
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Unauthorized",
+				Detail: "user not found",
+			}})
+		default:
+			return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "WebAuthn reset setup failed",
+				Detail: "an internal error occurred",
+			}})
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_webauthn_reset_setup",
+		Attributes: map[string]any{
+			"reset": true,
+		},
+	})
+}
+
+// Me godoc
+// @Summary Get current user
+// @Tags Auth
+// @Produce json
+// @Success 200 {object} dto.AuthCurrentUserResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Router /api/v1/auth/me [get]
+func (h *AuthHandler) Me(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	user, err := h.svc.GetUserByID(c.UserContext(), userID)
+	if err != nil || user == nil {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "user not found",
+		}})
+	}
+
+	id, _ := uuidv7.BytesToString(user.ID)
+	var emailVerifiedAt string
+	if user.EmailVerifiedAt != nil {
+		emailVerifiedAt = user.EmailVerifiedAt.UTC().Format("2006-01-02T15:04:05Z07:00")
+	}
+	totpEnabled, _ := h.svc.IsTOTPEnabled(c.UserContext(), user.ID)
+	isPreviouslyConfigured, _ := h.svc.IsTOTPPreviouslyConfigured(c.UserContext(), user.ID)
+	webauthnConfigured, _ := h.svc.IsWebAuthnConfigured(c.UserContext(), user.ID)
+	linkedSSO, _ := h.svc.IsSSOLinked(c.UserContext(), user.ID)
+	microsoftScope, _ := h.svc.GetMicrosoftScopeByUserID(c.UserContext(), user.ID)
+	pinConfigured := len(user.SecurityPINHash) > 0
+	pinBlocked := h.svc.IsSecurityPINBlocked(c.UserContext(), user.ID)
+	loginMethod := "unknown"
+	authProvider := "unknown"
+	if accessToken := readValidAccessToken(c, h.svc); accessToken != "" {
+		if method, provider, err := h.svc.GetSessionAuthContextFromAccessToken(c.UserContext(), accessToken); err == nil {
+			loginMethod = method
+			authProvider = provider
+		}
+	}
+	_, roles := authRoleResponseData(h.svc, c, user)
+	permissions := permissionAttrs(h.svc, c, user.ID)
+	permissionModules := permissionModuleGroups(h.svc, c, user.ID)
+	foto := authUserFoto(c.UserContext(), h.storage, user)
+	dulBases := make([]map[string]any, 0)
+	if h.contactSvc != nil {
+		contactRow, contactErr := h.contactSvc.GetContactByID(c.UserContext(), user.ID)
+		if contactErr == nil && isPilotRoleContact(contactRow) {
+			if parsed := contactDULBases(contactRow.BaseRolesRaw); len(parsed) > 0 {
+				dulBases = parsed
+			}
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "user",
+		ID:   id,
+		Attributes: map[string]any{
+			"email":                    user.Email,
+			"email_sso":                derefString(user.SSOEmail),
+			"first_name":               user.FirstName,
+			"last_name":                user.LastName,
+			"mobile_phone":             user.MobilePhone,
+			"timezone":                 tzpkg.WithDefault(user.Timezone),
+			"foto":                     foto,
+			"email_verified_at":        emailVerifiedAt,
+			"roles":                    roles,
+			"permissions":              permissions,
+			"permission_modules":       permissionModules,
+			"totp_enabled":             totpEnabled,
+			"is_previously_configured": isPreviouslyConfigured,
+			"webauthn_configured":      webauthnConfigured,
+			"linked_sso":               linkedSSO,
+			"pin_configured":           pinConfigured,
+			"pin_blocked":              pinBlocked,
+			"login_method":             loginMethod,
+			"auth_provider":            authProvider,
+			"microsoft_scope":          microsoftScope,
+			"dul_bases":                dulBases,
+		},
+	})
+}
+
+// UpdateTimezone godoc
+// @Summary Update current user timezone
+// @Tags Auth
+// @Accept json
+// @Produce json
+// @Param request body dto.TimezoneUpdateRequest true "JSON:API timezone update request"
+// @Success 200 {object} dto.AuthCurrentUserResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/me/timezone [patch]
+func (h *AuthHandler) UpdateTimezone(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	var req dto.TimezoneUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	normalizedTimezone, err := tzpkg.Normalize(req.Data.Attributes.Timezone)
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, timezoneValidationError("/data/attributes/timezone", err))
+	}
+	if _, err := h.svc.UpdateUserTimezone(c.UserContext(), userID, normalizedTimezone); err != nil {
+		if errors.Is(err, tzpkg.ErrEmpty) || errors.Is(err, tzpkg.ErrInvalid) {
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, timezoneValidationError("/data/attributes/timezone", err))
+		}
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	user, err := h.svc.GetUserByID(c.UserContext(), userID)
+	if err != nil || user == nil {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "user not found",
+		}})
+	}
+
+	id, _ := uuidv7.BytesToString(user.ID)
+	var emailVerifiedAt string
+	if user.EmailVerifiedAt != nil {
+		emailVerifiedAt = user.EmailVerifiedAt.UTC().Format("2006-01-02T15:04:05Z07:00")
+	}
+
+	_, roles := authRoleResponseData(h.svc, c, user)
+	permissions := permissionAttrs(h.svc, c, user.ID)
+	permissionModules := permissionModuleGroups(h.svc, c, user.ID)
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "user",
+		ID:   id,
+		Attributes: map[string]any{
+			"email":              user.Email,
+			"first_name":         user.FirstName,
+			"last_name":          user.LastName,
+			"mobile_phone":       user.MobilePhone,
+			"timezone":           tzpkg.WithDefault(user.Timezone),
+			"email_verified_at":  emailVerifiedAt,
+			"roles":              roles,
+			"permissions":        permissions,
+			"permission_modules": permissionModules,
+		},
+	})
+}
+
+// Refresh godoc
+// @Summary Refresh access token
+// @Tags Auth - Refresh
+// @Produce json
+// @Success 200 {object} dto.TokenResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Router /api/v1/auth/refresh [post]
+func (h *AuthHandler) Refresh(c *fiber.Ctx) error {
+	var (
+		tokens service.TokenPair
+		err    error
+	)
+	refreshCandidates := service.CookieValues(c.Get(fiber.HeaderCookie), h.svc.RefreshCookieName())
+	if len(refreshCandidates) == 0 {
+		refreshCandidates = []string{strings.TrimSpace(c.Cookies(h.svc.RefreshCookieName()))}
+	}
+	for _, refreshToken := range refreshCandidates {
+		tokens, err = h.svc.RefreshTokensWithClientAndDeviceType(
+			c.UserContext(),
+			refreshToken,
+			c.Get(fiber.HeaderUserAgent),
+			c.IP(),
+			readDeviceTypeHint(c),
+		)
+		if err == nil {
+			break
+		}
+	}
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "an internal error occurred",
+		}})
+	}
+	setAuthCookies(c, h.svc, tokens)
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_tokens",
+		Attributes: map[string]any{
+			"access_expires_in":  int64(h.svc.AccessTTL().Seconds()),
+			"refresh_expires_in": int64(tokens.RefreshTTL.Seconds()),
+			"microsoft": map[string]any{
+				"status": "checked_during_refresh",
+				"token":  map[string]any{},
+			},
+		},
+	})
+}
+
+// Logout godoc
+// @Summary Logout (revoke refresh)
+// @Tags Auth - Refresh
+// @Produce json
+// @Success 200 {object} dto.VerifyEmailResponse
+// @Router /api/v1/auth/logout [post]
+func (h *AuthHandler) Logout(c *fiber.Ctx) error {
+	accessToken := readValidAccessToken(c, h.svc)
+	refreshToken := readValidRefreshToken(c, h.svc)
+	if accessToken != "" {
+		if userID, err := h.svc.ParseAccessToken(c.UserContext(), accessToken); err == nil && len(userID) == 16 {
+			_ = h.svc.RevokeAllUserSessions(c.UserContext(), userID)
+		}
+	}
+	_ = h.svc.RevokeRefreshToken(c.UserContext(), refreshToken)
+	clearAuthCookies(c, h.svc)
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_logout",
+		Attributes: map[string]any{
+			"logged_out": true,
+		},
+	})
+}
+
+// MicrosoftRefresh godoc
+// @Summary Refresh Microsoft access token
+// @Tags Auth - SSO
+// @Produce json
+// @Success 200 {object} dto.TokenResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 428 {object} dto.ErrorResponse
+// @Router /api/v1/auth/microsoft/refresh [post]
+func (h *AuthHandler) MicrosoftRefresh(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+	tokenSet, err := h.svc.RefreshMicrosoftAccessToken(c.UserContext(), userID)
+	if err != nil {
+		if errors.Is(err, service.ErrMicrosoftReauthRequired) {
+			return writeAuthErrors(c, fiber.StatusPreconditionRequired, []jsonapi.ErrorObject{{
+				Status: "428",
+				Title:  "Reauthentication required",
+				Detail: "microsoft session requires reauthentication",
+			}})
+		}
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "an internal error occurred",
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_microsoft_tokens",
+		Attributes: map[string]any{
+			"access_token": tokenSet.AccessToken,
+			"token_type":   tokenSet.TokenType,
+			"scope":        tokenSet.Scope,
+			"expires_in":   tokenSet.ExpiresIn,
+		},
+	})
+}
+
+// MicrosoftLogout godoc
+// @Summary Logout Microsoft OAuth session
+// @Tags Auth - SSO
+// @Produce json
+// @Success 200 {object} dto.VerifyEmailResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Router /api/v1/auth/microsoft/logout [post]
+func (h *AuthHandler) MicrosoftLogout(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+	if err := h.svc.LogoutMicrosoft(c.UserContext(), userID); err != nil {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "an internal error occurred",
+		}})
+	}
+	_ = h.svc.RevokeRefreshToken(c.UserContext(), readValidRefreshToken(c, h.svc))
+	clearAuthCookies(c, h.svc)
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_microsoft_logout",
+		Attributes: map[string]any{
+			"logged_out": true,
+		},
+	})
+}
+
+// MicrosoftFrontChannelLogout godoc
+// @Summary Microsoft front-channel logout callback
+// @Description OIDC front-channel logout endpoint. Configure this URL as the "Front-channel logout URL" in Microsoft Entra. Microsoft loads it in a hidden iframe when the user signs out at the IdP (or from another RP). It clears local auth cookies and revokes the server-side session plus the stored Microsoft refresh token for the browser that owns the request. It never redirects and always returns 200 so the IdP logout flow can complete.
+// @Tags Auth - SSO
+// @Produce html
+// @Success 200 {string} string "logged out"
+// @Router /api/v1/auth/microsoft/front-channel-logout [get]
+func (h *AuthHandler) MicrosoftFrontChannelLogout(c *fiber.Ctx) error {
+	// This endpoint is loaded by the IdP inside an iframe. Responses must not be
+	// cached and must not redirect (a redirect would break the IdP logout flow).
+	c.Set(fiber.HeaderCacheControl, "no-store, max-age=0")
+	c.Set(fiber.HeaderPragma, "no-cache")
+	c.Set(fiber.HeaderXFrameOptions, "")
+	c.Set("Content-Security-Policy", "frame-ancestors https://login.microsoftonline.com https://*.microsoftonline.com https://login.live.com")
+
+	// OIDC front-channel logout MAY include iss (issuer) and sid (session id). When an
+	// issuer is supplied it must look like a Microsoft issuer; otherwise ignore the
+	// request body but still answer 200 as the spec requires.
+	if iss := strings.TrimSpace(c.Query("iss")); iss != "" && !isMicrosoftIssuer(iss) {
+		return sendFrontChannelLogoutOK(c)
+	}
+
+	revoked := false
+	if sid := strings.TrimSpace(c.Query("sid")); sid != "" {
+		if err := h.svc.RevokeMicrosoftSessionBySID(c.UserContext(), sid); err == nil {
+			revoked = true
+		}
+	}
+
+	// Cookie-based revocation remains as a fallback for browsers that still
+	// send the app cookies inside the front-channel iframe.
+	if accessToken := readValidAccessToken(c, h.svc); accessToken != "" {
+		if userID, err := h.svc.ParseAccessToken(c.UserContext(), accessToken); err == nil && len(userID) == 16 {
+			_ = h.svc.RevokeAllUserSessions(c.UserContext(), userID)
+			_ = h.svc.LogoutMicrosoft(c.UserContext(), userID)
+			revoked = true
+		}
+	}
+	if refreshToken := readValidRefreshToken(c, h.svc); refreshToken != "" {
+		_ = h.svc.RevokeRefreshToken(c.UserContext(), refreshToken)
+		revoked = true
+	}
+	clearAuthCookiesForFrontChannel(c, h.svc)
+	_ = revoked
+	return sendFrontChannelLogoutOK(c)
+}
+
+func sendFrontChannelLogoutOK(c *fiber.Ctx) error {
+	c.Set(fiber.HeaderContentType, "text/html; charset=utf-8")
+	return c.Status(fiber.StatusOK).SendString(`<!doctype html><meta charset="utf-8"><title>Logged out</title>`)
+}
+
+// isMicrosoftIssuer reports whether iss is a plausible Microsoft Entra issuer URL.
+func isMicrosoftIssuer(iss string) bool {
+	iss = strings.TrimSpace(iss)
+	if iss == "" {
+		return false
+	}
+	u, err := url.Parse(iss)
+	if err != nil || u.Scheme != "https" {
+		return false
+	}
+	host := strings.ToLower(u.Hostname())
+	return host == "login.microsoftonline.com" ||
+		host == "sts.windows.net" ||
+		strings.HasSuffix(host, ".microsoftonline.com") ||
+		strings.HasSuffix(host, ".windows.net")
+}
+
+// Sessions godoc
+// @Summary List active sessions
+// @Description Lists all active sessions/devices for current user.
+// @Tags Auth - Refresh
+// @Produce json
+// @Success 200 {object} dto.AuthSessionsResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Router /api/v1/auth/sessions [get]
+func (h *AuthHandler) Sessions(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	currentSessionID := ""
+	if accessToken := readValidAccessToken(c, h.svc); strings.TrimSpace(accessToken) != "" {
+		sid, err := h.svc.ParseAccessTokenSessionID(c.UserContext(), accessToken)
+		if err == nil {
+			currentSessionID = sid
+		}
+	}
+
+	sessions, err := h.svc.ListUserSessions(c.UserContext(), userID, currentSessionID)
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List sessions failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_sessions",
+		Attributes: map[string]any{
+			"sessions": sessions,
+		},
+	})
+}
+
+// DeleteSession godoc
+// @Summary Delete one session
+// @Description Revokes one session/device immediately. Requires PIN action token (header X-PIN-Verification-Token) with action=3d7d1d5f-ec48-4eca-a7ea-37f4f7927d06.
+// @Tags Auth - Refresh
+// @Produce json
+// @Param session_id path string true "Session ID"
+// @Success 200 {object} dto.AuthSessionDeleteResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/sessions/{session_id} [delete]
+func (h *AuthHandler) DeleteSession(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	sessionID := strings.TrimSpace(c.Params("session_id"))
+	if _, err := uuidv7.ParseString(sessionID); err != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "session_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/session_id"},
+		}})
+	}
+
+	if err := h.svc.RevokeUserSession(c.UserContext(), userID, sessionID); err != nil {
+		switch {
+		case errors.Is(err, service.ErrSessionNotFound):
+			return writeHandlerErrorDef(c, "AuthHandler.DeleteSession.SessionNotFound", apperrorsx.ErrDataNotFound, err)
+		case errors.Is(err, service.ErrInvalidToken):
+			return writeHandlerErrorDef(c, "AuthHandler.DeleteSession.InvalidToken", apperrorsx.ErrUserUnauthorized, err)
+		default:
+			return writeHandlerErrorDefWithStatus(c, "AuthHandler.DeleteSession", fiber.StatusBadRequest, apperrorsx.ErrInternal, err)
+		}
+	}
+
+	if accessToken := readValidAccessToken(c, h.svc); strings.TrimSpace(accessToken) != "" {
+		sid, err := h.svc.ParseAccessTokenSessionID(c.UserContext(), accessToken)
+		if err == nil && sid == sessionID {
+			clearAuthCookies(c, h.svc)
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_session_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// TOTPSetup godoc
+// @Summary Setup TOTP
+// @Description Generates secret and otpauth URL. TOTP is NOT enabled until confirmed.
+// @Tags Auth - TOTP
+// @Accept json
+// @Produce json
+// @Param request body dto.TOTPSetupRequest true "JSON:API TOTP setup request"
+// @Success 200 {object} dto.TOTPSetupResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/totp/setup [post]
+func (h *AuthHandler) TOTPSetup(c *fiber.Ctx) error {
+	authUserID := actorUserID(c)
+	if len(authUserID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	var req dto.TOTPSetupRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHandlerErrorDef(c, "AuthHandler.TOTPSetup.BodyParser", apperrorsx.ErrAuthInvalidJSON, err)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	userID, err := uuidv7.ParseString(req.Data.Attributes.UserID)
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "user_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/user_id"},
+		}})
+	}
+	if !bytes.Equal(userID, authUserID) {
+		return writeAuthErrors(c, fiber.StatusForbidden, []jsonapi.ErrorObject{{
+			Status: "403",
+			Title:  "Forbidden",
+			Detail: "user_id does not match authenticated user",
+		}})
+	}
+
+	user, err := h.svc.GetUserByID(c.UserContext(), authUserID)
+	if err != nil || user == nil {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "authenticated user not found",
+		}})
+	}
+
+	secret, otpURL, issuer, err := h.svc.SetupTOTP(c.UserContext(), authUserID, user.Email)
+	if err != nil {
+		return writeHandlerErrorDefWithStatus(c, "AuthHandler.TOTPSetup", fiber.StatusBadRequest, apperrorsx.ErrInternal, err)
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_totp_setup",
+		Attributes: map[string]any{
+			"secret":      secret,
+			"otpauth_url": otpURL,
+			"issuer":      issuer,
+		},
+	})
+}
+
+// TOTPConfirm godoc
+// @Summary Confirm TOTP setup
+// @Description Validates initial TOTP code and enables TOTP for future logins.
+// @Tags Auth - TOTP
+// @Accept json
+// @Produce json
+// @Param request body dto.TOTPConfirmRequest true "JSON:API TOTP confirm request"
+// @Success 200 {object} dto.VerifyEmailResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/totp/confirm [post]
+func (h *AuthHandler) TOTPConfirm(c *fiber.Ctx) error {
+	authUserID := actorUserID(c)
+	if len(authUserID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	var req dto.TOTPConfirmRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHandlerErrorDef(c, "AuthHandler.TOTPConfirm.BodyParser", apperrorsx.ErrAuthInvalidJSON, err)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	userID, err := uuidv7.ParseString(req.Data.Attributes.UserID)
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "user_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/user_id"},
+		}})
+	}
+	if !bytes.Equal(userID, authUserID) {
+		return writeAuthErrors(c, fiber.StatusForbidden, []jsonapi.ErrorObject{{
+			Status: "403",
+			Title:  "Forbidden",
+			Detail: "user_id does not match authenticated user",
+		}})
+	}
+
+	ok, err := h.svc.ConfirmTOTP(c.UserContext(), authUserID, strings.TrimSpace(req.Data.Attributes.Code))
+	if err != nil || !ok {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Invalid TOTP",
+			Detail: "code is invalid or expired",
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_totp_confirm",
+		Attributes: map[string]any{
+			"confirmed": true,
+		},
+	})
+}
+
+// TOTPVerify godoc
+// @Summary Verify TOTP code
+// @Description Completes login when TOTP is enabled and returns auth cookies.
+// @Tags Auth - TOTP
+// @Accept json
+// @Produce json
+// @Param request body dto.TOTPVerifyRequest true "JSON:API TOTP verify request"
+// @Success 200 {object} dto.TokenResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/totp/verify [post]
+func (h *AuthHandler) TOTPVerify(c *fiber.Ctx) error {
+	var req dto.TOTPVerifyRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHandlerErrorDef(c, "AuthHandler.TOTPVerify.BodyParser", apperrorsx.ErrAuthInvalidJSON, err)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	challengeToken := strings.TrimSpace(req.Data.Attributes.ChallengeToken)
+	userID, err := h.svc.ResolveTOTPChallenge(c.UserContext(), challengeToken)
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Invalid challenge",
+			Detail: "challenge token is invalid or expired",
+		}})
+	}
+
+	ok, err := h.svc.VerifyTOTP(c.UserContext(), userID, strings.TrimSpace(req.Data.Attributes.Code))
+	if err != nil || !ok {
+		if _, attemptErr := h.svc.RegisterFailedTOTPChallengeAttempt(c.UserContext(), challengeToken); attemptErr != nil {
+			if errors.Is(attemptErr, service.ErrTOTPChallengeAttemptLimit) {
+				return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+					Status: "401",
+					Title:  "Invalid challenge",
+					Detail: "challenge token is invalid or expired",
+				}})
+			}
+		}
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Invalid TOTP",
+			Detail: "code is invalid or expired",
+		}})
+	}
+	h.svc.InvalidateTOTPChallenge(c.UserContext(), challengeToken)
+
+	user, err := h.svc.GetUserByID(c.UserContext(), userID)
+	if err != nil || user == nil {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "user not found",
+		}})
+	}
+
+	tokens, err := h.svc.IssueTokensAfterTOTPWithClientAndDeviceType(
+		c.UserContext(),
+		user,
+		c.Get(fiber.HeaderUserAgent),
+		c.IP(),
+		readDeviceTypeHint(c),
+	)
+	if err != nil {
+		return writeHandlerErrorDefWithStatus(c, "AuthHandler.TOTPVerify.IssueTokens", fiber.StatusBadRequest, apperrorsx.ErrInternal, err)
+	}
+	setAuthCookies(c, h.svc, tokens)
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_tokens",
+		Attributes: map[string]any{
+			"access_expires_in":  int64(h.svc.AccessTTL().Seconds()),
+			"refresh_expires_in": int64(tokens.RefreshTTL.Seconds()),
+		},
+	})
+}
+
+// SendEmailOTP godoc
+// @Summary Send login OTP to email
+// @Description Sends a one-time 6-digit OTP to user email using login challenge token from /auth/login.
+// @Description Security controls: old OTP is invalidated, resend cooldown is enforced, and resend/hour quota is enforced.
+// @Tags Auth - Email OTP
+// @Accept json
+// @Produce json
+// @Param request body dto.EmailOTPSendRequest true "JSON:API Email OTP send request"
+// @Success 200 {object} dto.EmailOTPSendResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 429 {object} dto.ErrorResponse
+// @Router /api/v1/auth/email-otp/send [post]
+func (h *AuthHandler) SendEmailOTP(c *fiber.Ctx) error {
+	if !h.svc.IsLoginEmailOTPEnabled(c.UserContext()) {
+		return writeAuthErrors(c, fiber.StatusForbidden, []jsonapi.ErrorObject{{
+			Status: "403",
+			Title:  "Email OTP disabled",
+			Detail: "email otp login is disabled",
+		}})
+	}
+	var req dto.EmailOTPSendRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHandlerErrorDef(c, "AuthHandler.SendEmailOTP.BodyParser", apperrorsx.ErrAuthInvalidJSON, err)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if err := h.svc.SendLoginEmailOTP(c.UserContext(), strings.TrimSpace(req.Data.Attributes.ChallengeToken)); err != nil {
+		if errors.Is(err, service.ErrEmailOTPRateLimited) || errors.Is(err, service.ErrEmailOTPResendExceeded) {
+			return writeHandlerErrorDefWithStatus(c, "AuthHandler.SendEmailOTP.RateLimited", fiber.StatusTooManyRequests, apperrorsx.ErrBusinessRuleFailed, err)
+		}
+		return writeHandlerErrorDefWithStatus(c, "AuthHandler.SendEmailOTP", fiber.StatusBadRequest, apperrorsx.ErrInternal, err)
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_email_otp_send",
+		Attributes: map[string]any{
+			"sent": true,
+		},
+	})
+}
+
+// VerifyEmailOTP godoc
+// @Summary Verify login OTP from email
+// @Description Verifies one-time OTP and completes login by issuing auth cookies.
+// @Description OTP is one-time use, expires automatically, and failed attempts are limited and audited.
+// @Tags Auth - Email OTP
+// @Accept json
+// @Produce json
+// @Param request body dto.EmailOTPVerifyRequest true "JSON:API Email OTP verify request"
+// @Success 200 {object} dto.EmailOTPVerifyResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/email-otp/verify [post]
+func (h *AuthHandler) VerifyEmailOTP(c *fiber.Ctx) error {
+	if !h.svc.IsLoginEmailOTPEnabled(c.UserContext()) {
+		return writeAuthErrors(c, fiber.StatusForbidden, []jsonapi.ErrorObject{{
+			Status: "403",
+			Title:  "Email OTP disabled",
+			Detail: "email otp login is disabled",
+		}})
+	}
+	var req dto.EmailOTPVerifyRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHandlerErrorDef(c, "AuthHandler.VerifyEmailOTP.BodyParser", apperrorsx.ErrAuthInvalidJSON, err)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	user, err := h.svc.VerifyLoginEmailOTP(c.UserContext(), strings.TrimSpace(req.Data.Attributes.ChallengeToken), strings.TrimSpace(req.Data.Attributes.Code))
+	if err != nil {
+		if errors.Is(err, service.ErrInvalidEmailOTP) {
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Unauthorized",
+				Detail: "invalid otp code",
+			}})
+		}
+		return writeHandlerErrorDefWithStatus(c, "AuthHandler.VerifyEmailOTP", fiber.StatusBadRequest, apperrorsx.ErrInternal, err)
+	}
+	tokens, err := h.svc.IssueTokensAfterTOTPWithClientAndDeviceType(
+		c.UserContext(),
+		user,
+		c.Get(fiber.HeaderUserAgent),
+		c.IP(),
+		readDeviceTypeHint(c),
+	)
+	if err != nil {
+		return writeHandlerErrorDefWithStatus(c, "AuthHandler.VerifyEmailOTP.IssueTokens", fiber.StatusBadRequest, apperrorsx.ErrInternal, err)
+	}
+	setAuthCookies(c, h.svc, tokens)
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_email_otp_verify",
+		Attributes: map[string]any{
+			"verified":            true,
+			"requires_totp_setup": true,
+		},
+	})
+}
+
+// TOTPDisable godoc
+// @Summary Disable TOTP
+// @Tags Auth - TOTP
+// @Accept json
+// @Produce json
+// @Param request body dto.TOTPDisableRequest true "JSON:API TOTP disable request"
+// @Success 200 {object} dto.VerifyEmailResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/auth/totp/disable [post]
+func (h *AuthHandler) TOTPDisable(c *fiber.Ctx) error {
+	authUserID := actorUserID(c)
+	if len(authUserID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	var req dto.TOTPDisableRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHandlerErrorDef(c, "AuthHandler.TOTPDisable.BodyParser", apperrorsx.ErrAuthInvalidJSON, err)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	userID, err := uuidv7.ParseString(req.Data.Attributes.UserID)
+	if err != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "user_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/user_id"},
+		}})
+	}
+	if !bytes.Equal(userID, authUserID) {
+		return writeAuthErrors(c, fiber.StatusForbidden, []jsonapi.ErrorObject{{
+			Status: "403",
+			Title:  "Forbidden",
+			Detail: "user_id does not match authenticated user",
+		}})
+	}
+
+	if err := h.svc.DisableTOTP(c.UserContext(), authUserID); err != nil {
+		return writeHandlerErrorDefWithStatus(c, "AuthHandler.TOTPDisable", fiber.StatusBadRequest, apperrorsx.ErrInternal, err)
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_totp_disable",
+		Attributes: map[string]any{
+			"disabled": true,
+		},
+	})
+}
+
+// TOTPResetSetup godoc
+// @Summary Reset TOTP setup
+// @Description Removes TOTP setup so the user can re-setup authenticator.
+// @Description For method=pin, obtain token from /auth/pin/verify with action=0b5409b5-94f3-4aab-9de2-44b0ad5858f1 and send it in X-PIN-Verification-Token header.
+// @Tags Auth - TOTP
+// @Accept json
+// @Produce json
+// @Param request body dto.TOTPResetSetupRequest true "JSON:API TOTP reset setup request"
+// @Success 200 {object} dto.VerifyEmailResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 409 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 429 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/auth/totp/reset-setup [post]
+func (h *AuthHandler) TOTPResetSetup(c *fiber.Ctx) error {
+	userID, ok := c.Locals("user_id").([]byte)
+	if !ok || len(userID) == 0 {
+		return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	var req dto.TOTPResetSetupRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHandlerErrorDef(c, "AuthHandler.TOTPResetSetup.BodyParser", apperrorsx.ErrAuthInvalidJSON, err)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	method := strings.ToLower(strings.TrimSpace(req.Data.Attributes.Method))
+	switch method {
+	case "pin":
+		sessionID := ""
+		if accessToken := readValidAccessToken(c, h.svc); accessToken != "" {
+			sid, err := h.svc.ParseAccessTokenSessionID(c.UserContext(), accessToken)
+			if err != nil {
+				return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+					Status: "401",
+					Title:  "Unauthorized",
+					Detail: "invalid or expired token",
+				}})
+			}
+			sessionID = sid
+		}
+		token := c.Get(pinVerificationHeader)
+		if err := h.svc.ConsumeSecurityPINActionTokenInSession(c.UserContext(), userID, sharedconst.PinActionTOTPResetSetup, token, sessionID); err != nil {
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "PIN verification required",
+				Detail: "valid PIN action token is required",
+				Source: &jsonapi.ErrorSource{Pointer: "/headers/X-PIN-Verification-Token"},
+			}})
+		}
+		if err := h.svc.DeleteTOTPSetup(c.UserContext(), userID); err != nil {
+			return writeHandlerErrorDefWithStatus(c, "AuthHandler.TOTPResetSetup.Delete", fiber.StatusBadRequest, apperrorsx.ErrInternal, err)
+		}
+		return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+			Type: "auth_totp_reset_setup",
+			Attributes: map[string]any{
+				"reset": true,
+			},
+		})
+	case "password":
+		if req.Data.Attributes.Password == "" {
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "password is required when method is password",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/password"},
+			}})
+		}
+	default:
+		return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "method must be one of: pin, password",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/method"},
+		}})
+	}
+
+	if err := h.svc.ResetTOTPSetup(c.UserContext(), userID, method, "", req.Data.Attributes.Password); err != nil {
+		switch {
+		case errors.Is(err, service.ErrInvalidReauthMethod):
+			return writeAuthErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "method must be one of: pin, password",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/method"},
+			}})
+		case errors.Is(err, service.ErrInvalidCredentials), errors.Is(err, service.ErrInvalidSecurityPIN):
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Unauthorized",
+				Detail: "invalid authentication factor",
+			}})
+		case errors.Is(err, service.ErrSecurityPINNotSet):
+			return writeAuthErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "PIN not configured",
+				Detail: "security PIN is not set",
+			}})
+		case errors.Is(err, service.ErrSecurityPINAttemptLimit):
+			return writeAuthErrors(c, fiber.StatusLocked, []jsonapi.ErrorObject{{
+				Status: "423",
+				Title:  "PIN blocked",
+				Detail: "security PIN is blocked. reset PIN is required.",
+			}})
+		case errors.Is(err, service.ErrSecurityPINLocked), errors.Is(err, service.ErrSecurityPINResetRequired):
+			return writeAuthErrors(c, fiber.StatusLocked, []jsonapi.ErrorObject{{
+				Status: "423",
+				Title:  "PIN blocked",
+				Detail: "security PIN is blocked. reset PIN is required.",
+			}})
+		case errors.Is(err, service.ErrInvalidToken):
+			return writeAuthErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Unauthorized",
+				Detail: "user not found",
+			}})
+		default:
+			return writeHandlerErrorDefWithStatus(c, "AuthHandler.TOTPResetSetup", fiber.StatusBadRequest, apperrorsx.ErrInternal, err)
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "auth_totp_reset_setup",
+		Attributes: map[string]any{
+			"reset": true,
+		},
+	})
+}
+
+func permissionAttrs(svc *service.AuthService, c *fiber.Ctx, userID []byte) []map[string]any {
+	perms, err := svc.GetPermissionsByUserID(c.UserContext(), userID)
+	if err != nil {
+		return []map[string]any{}
+	}
+	out := make([]map[string]any, 0, len(perms))
+	for i := range perms {
+		pid, _ := uuidv7.BytesToString(perms[i].ID)
+		out = append(out, map[string]any{
+			"id":           pid,
+			"name":         perms[i].Name,
+			"key":          perms[i].Key,
+			"description":  perms[i].Description,
+			"requires_pin": perms[i].RequiresPIN,
+		})
+	}
+	return out
+}
+
+// permissionModuleGroups returns the user's permissions grouped by module, in the
+// same shape as GET /roles/permissions/get-all.
+// TODO: remove permissionAttrs (the flat "permissions" field) once the frontend
+// migrates to "permission_modules".
+func permissionModuleGroups(svc *service.AuthService, c *fiber.Ctx, userID []byte) []dto.PermissionGroupResource {
+	perms, err := svc.GetPermissionsByUserID(c.UserContext(), userID)
+	if err != nil {
+		return []dto.PermissionGroupResource{}
+	}
+	return groupPermissionsByModule(perms)
+}
+
+func authRoleResponseData(svc *service.AuthService, c *fiber.Ctx, user *auth.User) (any, []map[string]any) {
+	roleIDs := make([]string, 0, len(user.RoleIDs)+1)
+	roles := make([]map[string]any, 0, len(user.Roles)+1)
+	seen := make(map[string]struct{}, len(user.RoleIDs)+1)
+
+	appendRole := func(roleID []byte, name, description string) {
+		if len(roleID) != 16 {
+			return
+		}
+		roleIDStr, _ := uuidv7.BytesToString(roleID)
+		if _, exists := seen[roleIDStr]; exists {
+			return
+		}
+		seen[roleIDStr] = struct{}{}
+		roleIDs = append(roleIDs, roleIDStr)
+		roles = append(roles, map[string]any{
+			"id":          roleIDStr,
+			"name":        name,
+			"description": description,
+		})
+	}
+
+	primaryRole := findAuthRoleByID(user, user.RoleID)
+	if primaryRole == nil && len(user.RoleID) == 16 {
+		primaryRole, _ = svc.GetRoleByID(c.UserContext(), user.RoleID)
+	}
+	if primaryRole != nil {
+		appendRole(primaryRole.ID, primaryRole.Name, primaryRole.Description)
+	}
+
+	for i := range user.Roles {
+		appendRole(user.Roles[i].ID, user.Roles[i].Name, user.Roles[i].Description)
+	}
+	for i := range user.RoleIDs {
+		appendRole(user.RoleIDs[i], "", "")
+	}
+	if len(roles) == 0 && len(user.RoleID) == 16 {
+		appendRole(user.RoleID, "", "")
+	}
+
+	// primaryRoleID := ""
+	var primaryRoleAttrs any
+	if len(roles) > 0 {
+		// primaryRoleID = roleIDs[0]
+		primaryRoleAttrs = roles[0]
+	}
+
+	return primaryRoleAttrs, roles
+}
+
+func roleResponseIDFields(roles []map[string]any) (any, []string) {
+	roleIDs := make([]string, 0, len(roles))
+	for i := range roles {
+		if roleID, ok := roles[i]["id"].(string); ok && roleID != "" {
+			roleIDs = append(roleIDs, roleID)
+		}
+	}
+	if len(roleIDs) == 0 {
+		return nil, roleIDs
+	}
+	return roleIDs[0], roleIDs
+}
+
+func findAuthRoleByID(user *auth.User, roleID []byte) *auth.Role {
+	if user == nil || len(roleID) != 16 {
+		return nil
+	}
+	target := string(roleID)
+	for i := range user.Roles {
+		if string(user.Roles[i].ID) == target {
+			role := user.Roles[i]
+			return &role
+		}
+	}
+	return nil
+}
+
+func setAuthCookies(c *fiber.Ctx, svc *service.AuthService, tokens service.TokenPair) {
+	setAuthCookiesWithSameSite(c, svc, tokens, parseSameSite(svc.CookieSameSite()), svc.CookieSecure())
+}
+
+func setAuthCookiesForProvider(c *fiber.Ctx, svc *service.AuthService, tokens service.TokenPair, authProvider string) {
+	sameSite := parseSameSite(svc.CookieSameSite())
+	secure := svc.CookieSecure()
+	if strings.EqualFold(strings.TrimSpace(authProvider), "microsoft") && secure {
+		sameSite = "None"
+	}
+	setAuthCookiesWithSameSite(c, svc, tokens, sameSite, secure)
+}
+
+func setAuthCookiesWithSameSite(c *fiber.Ctx, svc *service.AuthService, tokens service.TokenPair, sameSite string, secure bool) {
+	refreshTTL := tokens.RefreshTTL
+	if refreshTTL <= 0 {
+		refreshTTL = svc.RefreshTTL()
+	}
+	clearAuthCookieScopes(c, svc, sameSite, secure)
+	c.Cookie(&fiber.Cookie{
+		Name:     svc.AccessCookieName(),
+		Value:    tokens.AccessToken,
+		HTTPOnly: true,
+		Secure:   secure,
+		SameSite: sameSite,
+		Domain:   svc.CookieDomain(),
+		Path:     "/",
+		MaxAge:   int(svc.AccessTTL().Seconds()),
+	})
+	c.Cookie(&fiber.Cookie{
+		Name:     svc.RefreshCookieName(),
+		Value:    tokens.RefreshToken,
+		HTTPOnly: true,
+		Secure:   secure,
+		SameSite: sameSite,
+		Domain:   svc.CookieDomain(),
+		Path:     "/api/v1/auth/refresh",
+		MaxAge:   int(refreshTTL.Seconds()),
+	})
+}
+
+func clearAuthCookieScopes(c *fiber.Ctx, svc *service.AuthService, sameSite string, secure bool) {
+	name := svc.AccessCookieName()
+	refreshName := svc.RefreshCookieName()
+	domain := strings.TrimSpace(svc.CookieDomain())
+
+	c.Cookie(&fiber.Cookie{
+		Name:     name,
+		Value:    "",
+		HTTPOnly: true,
+		Secure:   secure,
+		SameSite: sameSite,
+		Domain:   domain,
+		Path:     "/",
+		MaxAge:   -1,
+	})
+	c.Cookie(&fiber.Cookie{
+		Name:     refreshName,
+		Value:    "",
+		HTTPOnly: true,
+		Secure:   secure,
+		SameSite: sameSite,
+		Domain:   domain,
+		Path:     "/api/v1/auth/refresh",
+		MaxAge:   -1,
+	})
+	if domain != "" {
+		c.Cookie(&fiber.Cookie{
+			Name:     name,
+			Value:    "",
+			HTTPOnly: true,
+			Secure:   secure,
+			SameSite: sameSite,
+			Path:     "/",
+			MaxAge:   -1,
+		})
+		c.Cookie(&fiber.Cookie{
+			Name:     refreshName,
+			Value:    "",
+			HTTPOnly: true,
+			Secure:   secure,
+			SameSite: sameSite,
+			Path:     "/api/v1/auth/refresh",
+			MaxAge:   -1,
+		})
+	}
+}
+
+func readValidAccessToken(c *fiber.Ctx, svc *service.AuthService) string {
+	if c == nil || svc == nil {
+		return ""
+	}
+	candidates := service.CookieValues(c.Get(fiber.HeaderCookie), svc.AccessCookieName())
+	for _, token := range candidates {
+		if _, err := svc.ParseAccessToken(c.UserContext(), token); err == nil {
+			return token
+		}
+	}
+	return strings.TrimSpace(c.Cookies(svc.AccessCookieName()))
+}
+
+func readValidRefreshToken(c *fiber.Ctx, svc *service.AuthService) string {
+	if c == nil || svc == nil {
+		return ""
+	}
+	candidates := service.CookieValues(c.Get(fiber.HeaderCookie), svc.RefreshCookieName())
+	if len(candidates) == 0 {
+		return strings.TrimSpace(c.Cookies(svc.RefreshCookieName()))
+	}
+	return candidates[0]
+}
+
+func writeAuthErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	for i := range errs {
+		e := errs[i]
+		if strings.TrimSpace(e.Code) == "" || strings.TrimSpace(e.ErrorCode) == "" {
+			code, errorCode := inferAuthErrorCode(status, e.Title, e.Detail)
+			if strings.TrimSpace(e.Code) == "" {
+				e.Code = code
+			}
+			if strings.TrimSpace(e.ErrorCode) == "" {
+				e.ErrorCode = errorCode
+			}
+		}
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferAuthErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+
+	switch status {
+	case fiber.StatusAccepted:
+		if strings.Contains(lowerTitle, "pin verification") || strings.Contains(lowerDetail, "pin action token") {
+			return apperrorsx.CodePINVerificationRequired, apperrorsx.ErrPINVerificationRequired202.ErrorCode
+		}
+		return apperrorsx.CodeInvalidRequest, apperrorsx.ErrInvalidRequest.ErrorCode
+	case fiber.StatusUnauthorized:
+		if strings.Contains(lowerDetail, "token") || strings.Contains(lowerTitle, "invalid challenge") {
+			return apperrorsx.CodeTokenInvalid, apperrorsx.ErrTokenInvalid.ErrorCode
+		}
+		if strings.Contains(lowerDetail, "pin") {
+			return apperrorsx.CodePINIncorrect, apperrorsx.ErrPINIncorrect.ErrorCode
+		}
+		if strings.Contains(lowerDetail, "credentials") || strings.Contains(lowerTitle, "unauthorized") {
+			return apperrorsx.CodeUserUnauthorized, apperrorsx.ErrUserUnauthorized.ErrorCode
+		}
+		return apperrorsx.CodeUserUnauthorized, apperrorsx.ErrUserUnauthorized.ErrorCode
+	case fiber.StatusForbidden:
+		if strings.Contains(lowerTitle, "registration disabled") {
+			return apperrorsx.CodeAuthRegistrationDisabled, apperrorsx.ErrAuthRegistrationDisabled.ErrorCode
+		}
+		if strings.Contains(lowerDetail, "permission") || strings.Contains(lowerDetail, "forbidden") {
+			return apperrorsx.CodeForbiddenAccess, apperrorsx.ErrForbiddenAccess.ErrorCode
+		}
+		return apperrorsx.CodeForbiddenAccess, apperrorsx.ErrForbiddenAccess.ErrorCode
+	case fiber.StatusNotFound:
+		if strings.Contains(lowerDetail, "user not found") || strings.Contains(lowerDetail, "session is not found") {
+			return apperrorsx.CodeDataNotFound, apperrorsx.ErrDataNotFound.ErrorCode
+		}
+		return apperrorsx.CodeDataNotFound, apperrorsx.ErrDataNotFound.ErrorCode
+	case fiber.StatusConflict:
+		if strings.Contains(lowerDetail, "pin") {
+			return apperrorsx.CodePINNotSet, apperrorsx.ErrPINNotSet.ErrorCode
+		}
+		return apperrorsx.CodeBusinessRuleFailed, apperrorsx.ErrBusinessRuleFailed.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		if strings.Contains(lowerDetail, "pin") {
+			return apperrorsx.CodePINValidationFailed, apperrorsx.ErrPINValidationFailed.ErrorCode
+		}
+		if strings.Contains(lowerTitle, "validation") {
+			return apperrorsx.CodeValidationError, apperrorsx.ErrValidation.ErrorCode
+		}
+		return apperrorsx.CodeValidationError, apperrorsx.ErrValidation.ErrorCode
+	case fiber.StatusTooManyRequests:
+		if strings.Contains(lowerDetail, "blocked") || strings.Contains(lowerTitle, "pin blocked") {
+			return apperrorsx.CodePINBlocked, apperrorsx.ErrPINBlocked.ErrorCode
+		}
+		if strings.Contains(lowerDetail, "pin") || strings.Contains(lowerTitle, "too many attempts") {
+			return apperrorsx.CodePINAttemptLimitReached, apperrorsx.ErrPINAttemptLimitReached.ErrorCode
+		}
+		return apperrorsx.CodeBusinessRuleFailed, apperrorsx.ErrBusinessRuleFailed.ErrorCode
+	case fiber.StatusInternalServerError:
+		if strings.Contains(lowerTitle, "reset password failed") {
+			return apperrorsx.CodeAuthResetPasswordFailed, apperrorsx.ErrAuthResetPasswordFailed.ErrorCode
+		}
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	case fiber.StatusBadRequest:
+		if strings.Contains(lowerTitle, "invalid json") {
+			return apperrorsx.CodeAuthInvalidJSON, apperrorsx.ErrAuthInvalidJSON.ErrorCode
+		}
+		if strings.Contains(lowerTitle, "role not found") {
+			return apperrorsx.CodeAuthRoleNotFound, apperrorsx.ErrAuthRoleNotFound.ErrorCode
+		}
+		if strings.Contains(lowerTitle, "registration failed") {
+			if strings.Contains(lowerDetail, "already registered") {
+				return apperrorsx.CodeAuthUsernameAlreadyRegistered, apperrorsx.ErrAuthUsernameAlreadyRegistered.ErrorCode
+			}
+			return apperrorsx.CodeAuthRegistrationFailed, apperrorsx.ErrAuthRegistrationFailed.ErrorCode
+		}
+		if strings.Contains(lowerTitle, "invite failed") {
+			return apperrorsx.CodeAuthInviteFailed, apperrorsx.ErrAuthInviteFailed.ErrorCode
+		}
+		if strings.Contains(lowerTitle, "set password failed") {
+			if strings.Contains(lowerDetail, "invalid or expired token") {
+				return apperrorsx.CodeAuthSetPasswordTokenInvalid, apperrorsx.ErrAuthSetPasswordTokenInvalid.ErrorCode
+			}
+			return apperrorsx.CodeAuthSetPasswordFailed, apperrorsx.ErrAuthSetPasswordFailed.ErrorCode
+		}
+		if strings.Contains(lowerTitle, "invalid reset link") {
+			return apperrorsx.CodeAuthResetPasswordInvalidLink, apperrorsx.ErrAuthResetPasswordInvalidLink.ErrorCode
+		}
+		return apperrorsx.CodeInvalidRequest, apperrorsx.ErrInvalidRequest.ErrorCode
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
+
+func clearAuthCookies(c *fiber.Ctx, svc *service.AuthService) {
+	clearAuthCookieScopes(c, svc, parseSameSite(svc.CookieSameSite()), svc.CookieSecure())
+}
+
+func clearAuthCookiesForFrontChannel(c *fiber.Ctx, svc *service.AuthService) {
+	clearAuthCookieScopes(c, svc, "None", true)
+}
+
+func parseSameSite(v string) string {
+	switch strings.ToLower(v) {
+	case "strict":
+		return "Strict"
+	case "none":
+		return "None"
+	default:
+		return "Lax"
+	}
+}
+
+func readDeviceTypeHint(c *fiber.Ctx) string {
+	if c == nil {
+		return ""
+	}
+	return strings.TrimSpace(strings.ToLower(c.Get(deviceTypeHeader)))
+}
+
+func authUserFoto(ctx context.Context, storage fileManagerDownloadURLStorage, u *auth.User) *dto.UserFoto {
+	if u == nil {
+		return nil
+	}
+	fotoUUID := uuidBytesToStringOrEmpty(u.ProfileAttachmentID)
+	fotoDownloadURL := ""
+	fotoThumbnailURL := ""
+	var fotoOriginalSizeBytes *int64
+	if u.ProfileAttachment != nil && u.ProfileAttachment.File != nil {
+		asset := resolveFileManagerDownloadURLs(ctx, storage, u.ProfileAttachment.File)
+		fotoDownloadURL = strings.TrimSpace(asset.OriginalURL)
+		fotoThumbnailURL = strings.TrimSpace(asset.ThumbnailURL)
+		fotoOriginalSizeBytes = int64Ptr(asset.OriginalSizeBytes)
+	}
+	if fotoUUID == "" && fotoDownloadURL == "" && fotoThumbnailURL == "" && fotoOriginalSizeBytes == nil {
+		return nil
+	}
+	return &dto.UserFoto{
+		UUID:                 fotoUUID,
+		DownloadURL:          fotoDownloadURL,
+		ThumbnailDownloadURL: fotoThumbnailURL,
+		OriginalSizeBytes:    fotoOriginalSizeBytes,
+	}
+}
diff --git a/internal/transport/http/handlers/auth_handler_test.go b/internal/transport/http/handlers/auth_handler_test.go
new file mode 100644
index 0000000..2b8c5b8
--- /dev/null
+++ b/internal/transport/http/handlers/auth_handler_test.go
@@ -0,0 +1,6354 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	webauthnlib "github.com/go-webauthn/webauthn/webauthn"
+	"github.com/gofiber/fiber/v2"
+	"github.com/pquerna/otp/totp"
+
+	"wucher/internal/config"
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/contact"
+	"wucher/internal/service"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+)
+
+type memTokenStore struct {
+	store   map[string][]byte
+	lastKey string
+}
+
+func newMemTokenStore() *memTokenStore {
+	return &memTokenStore{store: map[string][]byte{}}
+}
+
+func (m *memTokenStore) Set(_ context.Context, key string, value []byte, _ time.Duration) error {
+	m.store[key] = value
+	m.lastKey = key
+	return nil
+}
+
+func (m *memTokenStore) SetIfNotExists(_ context.Context, key string, value []byte, _ time.Duration) (bool, error) {
+	if _, ok := m.store[key]; ok {
+		return false, nil
+	}
+	m.store[key] = value
+	m.lastKey = key
+	return true, nil
+}
+
+func (m *memTokenStore) Get(_ context.Context, key string) ([]byte, error) {
+	v, ok := m.store[key]
+	if !ok {
+		return nil, nil
+	}
+	return v, nil
+}
+
+func (m *memTokenStore) Delete(_ context.Context, key string) error {
+	delete(m.store, key)
+	return nil
+}
+
+type memRepo struct {
+	users                  map[string]*auth.User
+	usersByMail            map[string]*auth.User
+	usersByUsername        map[string]*auth.User
+	identities             map[string]*auth.UserIdentity
+	totp                   map[string]*auth.UserTOTP
+	webauthnCredentials    map[string][]auth.UserWebAuthnCredential
+	resetTokens            map[string]*auth.PasswordResetToken
+	securityPINResetTokens map[string]*auth.SecurityPINResetToken
+	emailLoginOTPs         map[string]*auth.UserEmailLoginOTP
+	rolesByName            map[string]*auth.Role
+	rolesByID              map[string]*auth.Role
+	permsByRole            map[string][]auth.Permission
+	permsErr               error
+
+	consumeResetErr    error
+	consumePINResetErr error
+	deleteTOTPErr      error
+	deleteWebAuthnErr  error
+}
+
+func newMemRepo() *memRepo {
+	return &memRepo{
+		users:                  map[string]*auth.User{},
+		usersByMail:            map[string]*auth.User{},
+		usersByUsername:        map[string]*auth.User{},
+		identities:             map[string]*auth.UserIdentity{},
+		totp:                   map[string]*auth.UserTOTP{},
+		webauthnCredentials:    map[string][]auth.UserWebAuthnCredential{},
+		resetTokens:            map[string]*auth.PasswordResetToken{},
+		securityPINResetTokens: map[string]*auth.SecurityPINResetToken{},
+		emailLoginOTPs:         map[string]*auth.UserEmailLoginOTP{},
+		rolesByName:            map[string]*auth.Role{},
+		rolesByID:              map[string]*auth.Role{},
+		permsByRole:            map[string][]auth.Permission{},
+	}
+}
+
+func (r *memRepo) CreateUser(_ context.Context, user *auth.User) error {
+	if user != nil && !user.IsActive {
+		user.IsActive = true
+	}
+	r.users[string(user.ID)] = user
+	r.usersByMail[user.Email] = user
+	if user.Username != nil {
+		r.usersByUsername[*user.Username] = user
+	}
+	return nil
+}
+func (r *memRepo) GetUserByID(_ context.Context, id []byte) (*auth.User, error) {
+	return r.users[string(id)], nil
+}
+func (r *memRepo) GetUserByEmail(_ context.Context, email string) (*auth.User, error) {
+	return r.usersByMail[email], nil
+}
+func (r *memRepo) GetUserBySSOEmail(_ context.Context, ssoEmail string) (*auth.User, error) {
+	return r.usersByMail[ssoEmail], nil
+}
+func (r *memRepo) GetUserByUsername(_ context.Context, username string) (*auth.User, error) {
+	return r.usersByUsername[username], nil
+}
+func (r *memRepo) UpdateUserTimezone(_ context.Context, id []byte, timezoneName string) error {
+	u := r.users[string(id)]
+	if u == nil {
+		return nil
+	}
+	u.Timezone = timezoneName
+	return nil
+}
+func (r *memRepo) SetUserPassword(_ context.Context, id []byte, passwordHash, salt []byte) error {
+	u := r.users[string(id)]
+	if u == nil {
+		return nil
+	}
+	u.PasswordHash = passwordHash
+	u.SaltValue = salt
+	return nil
+}
+func (r *memRepo) SetUserSecurityPIN(_ context.Context, id []byte, pinHash []byte, setAt time.Time) error {
+	u := r.users[string(id)]
+	if u == nil {
+		return nil
+	}
+	u.SecurityPINHash = append([]byte(nil), pinHash...)
+	ts := setAt
+	u.SecurityPINSetAt = &ts
+	return nil
+}
+func (r *memRepo) MarkEmailVerified(_ context.Context, id []byte) error {
+	u := r.users[string(id)]
+	now := time.Now()
+	u.EmailVerifiedAt = &now
+	return nil
+}
+func (r *memRepo) CreatePasswordResetToken(_ context.Context, token *auth.PasswordResetToken) error {
+	if token == nil {
+		return nil
+	}
+	cp := *token
+	if len(cp.ID) == 0 {
+		cp.ID = uuidv7.MustBytes()
+	}
+	r.resetTokens[string(cp.TokenHash)] = &cp
+	return nil
+}
+func (r *memRepo) InvalidateActivePasswordResetTokensByUserID(_ context.Context, userID []byte, usedAt time.Time) error {
+	for _, rec := range r.resetTokens {
+		if string(rec.UserID) == string(userID) && rec.UsedAt == nil && rec.ExpiresAt.After(usedAt) {
+			ts := usedAt
+			rec.UsedAt = &ts
+		}
+	}
+	return nil
+}
+func (r *memRepo) ConsumePasswordResetTokenAndSetPassword(_ context.Context, tokenHash, passwordHash, salt []byte, usedAt time.Time) ([]byte, bool, error) {
+	if r.consumeResetErr != nil {
+		return nil, false, r.consumeResetErr
+	}
+	rec := r.resetTokens[string(tokenHash)]
+	if rec == nil || rec.UsedAt != nil || !rec.ExpiresAt.After(usedAt) {
+		return nil, false, nil
+	}
+	u := r.users[string(rec.UserID)]
+	if u == nil {
+		return nil, false, nil
+	}
+	u.PasswordHash = passwordHash
+	u.SaltValue = salt
+	ts := usedAt
+	rec.UsedAt = &ts
+	for _, other := range r.resetTokens {
+		if string(other.UserID) == string(rec.UserID) && string(other.ID) != string(rec.ID) && other.UsedAt == nil && other.ExpiresAt.After(usedAt) {
+			otherTS := usedAt
+			other.UsedAt = &otherTS
+		}
+	}
+	return rec.UserID, true, nil
+}
+func (r *memRepo) CreateSecurityPINResetToken(_ context.Context, token *auth.SecurityPINResetToken) error {
+	if token == nil {
+		return nil
+	}
+	cp := *token
+	if len(cp.ID) == 0 {
+		cp.ID = uuidv7.MustBytes()
+	}
+	r.securityPINResetTokens[string(cp.TokenHash)] = &cp
+	return nil
+}
+func (r *memRepo) InvalidateActiveSecurityPINResetTokensByUserID(_ context.Context, userID []byte, usedAt time.Time) error {
+	for _, rec := range r.securityPINResetTokens {
+		if string(rec.UserID) == string(userID) && rec.UsedAt == nil && rec.ExpiresAt.After(usedAt) {
+			ts := usedAt
+			rec.UsedAt = &ts
+		}
+	}
+	return nil
+}
+func (r *memRepo) GetActiveSecurityPINResetTokenUser(_ context.Context, tokenHash []byte, now time.Time) (*auth.User, error) {
+	rec := r.securityPINResetTokens[string(tokenHash)]
+	if rec == nil || rec.UsedAt != nil || !rec.ExpiresAt.After(now) {
+		return nil, nil
+	}
+	return r.users[string(rec.UserID)], nil
+}
+func (r *memRepo) ConsumeSecurityPINResetTokenAndSetPIN(_ context.Context, tokenHash, pinHash []byte, usedAt time.Time) ([]byte, bool, error) {
+	if r.consumePINResetErr != nil {
+		return nil, false, r.consumePINResetErr
+	}
+	rec := r.securityPINResetTokens[string(tokenHash)]
+	if rec == nil || rec.UsedAt != nil || !rec.ExpiresAt.After(usedAt) {
+		return nil, false, nil
+	}
+	u := r.users[string(rec.UserID)]
+	if u == nil {
+		return nil, false, nil
+	}
+	u.SecurityPINHash = append([]byte(nil), pinHash...)
+	ts := usedAt
+	u.SecurityPINSetAt = &ts
+	rec.UsedAt = &ts
+	return rec.UserID, true, nil
+}
+func (r *memRepo) UpsertIdentity(_ context.Context, identity *auth.UserIdentity) error {
+	r.identities[identity.Provider+"|"+identity.ProviderSubject] = identity
+	return nil
+}
+func (r *memRepo) CreateIdentity(_ context.Context, identity *auth.UserIdentity) error {
+	r.identities[identity.Provider+"|"+identity.ProviderSubject] = identity
+	return nil
+}
+func (r *memRepo) GetIdentityByProviderSubject(_ context.Context, provider, subject string) (*auth.UserIdentity, error) {
+	return r.identities[provider+"|"+subject], nil
+}
+func (r *memRepo) GetIdentityByUserID(_ context.Context, userID []byte) (*auth.UserIdentity, error) {
+	for _, identity := range r.identities {
+		if bytes.Equal(identity.UserID, userID) {
+			return identity, nil
+		}
+	}
+	return nil, nil
+}
+func (r *memRepo) DeleteIdentityByUserIDProvider(_ context.Context, userID []byte, provider string) (bool, error) {
+	for key, identity := range r.identities {
+		if bytes.Equal(identity.UserID, userID) && identity.Provider == provider {
+			delete(r.identities, key)
+			return true, nil
+		}
+	}
+	return false, nil
+}
+func (r *memRepo) GetUserTOTP(_ context.Context, userID []byte) (*auth.UserTOTP, error) {
+	return r.totp[string(userID)], nil
+}
+func (r *memRepo) UpsertUserTOTP(_ context.Context, rec *auth.UserTOTP) error {
+	r.totp[string(rec.UserID)] = rec
+	return nil
+}
+func (r *memRepo) DisableUserTOTP(_ context.Context, userID []byte) error {
+	if r.totp[string(userID)] != nil {
+		r.totp[string(userID)].Enabled = false
+	}
+	return nil
+}
+func (r *memRepo) DeleteUserTOTPSetup(_ context.Context, userID []byte) error {
+	if r.deleteTOTPErr != nil {
+		return r.deleteTOTPErr
+	}
+	delete(r.totp, string(userID))
+	return nil
+}
+func (r *memRepo) UpdateUserTOTPLastUsed(_ context.Context, userID []byte) error { return nil }
+func (r *memRepo) GetActiveUserEmailLoginOTP(_ context.Context, userID []byte, now time.Time) (*auth.UserEmailLoginOTP, error) {
+	rec := r.emailLoginOTPs[string(userID)]
+	if rec == nil || rec.UsedAt != nil || !rec.ExpiresAt.After(now) {
+		return nil, nil
+	}
+	return rec, nil
+}
+func (r *memRepo) CountUserEmailLoginOTPSince(_ context.Context, userID []byte, since time.Time) (int64, error) {
+	rec := r.emailLoginOTPs[string(userID)]
+	if rec == nil || rec.CreatedAt.Before(since) {
+		return 0, nil
+	}
+	return 1, nil
+}
+func (r *memRepo) CreateUserEmailLoginOTP(_ context.Context, otp *auth.UserEmailLoginOTP) error {
+	if otp == nil {
+		return nil
+	}
+	cp := *otp
+	if cp.CreatedAt.IsZero() {
+		cp.CreatedAt = time.Now().UTC()
+	}
+	r.emailLoginOTPs[string(cp.UserID)] = &cp
+	return nil
+}
+func (r *memRepo) InvalidateActiveUserEmailLoginOTPs(_ context.Context, userID []byte, usedAt time.Time) error {
+	rec := r.emailLoginOTPs[string(userID)]
+	if rec != nil && rec.UsedAt == nil && rec.ExpiresAt.After(usedAt) {
+		ts := usedAt
+		rec.UsedAt = &ts
+	}
+	return nil
+}
+func (r *memRepo) ConsumeUserEmailLoginOTP(_ context.Context, userID, otpHash []byte, now time.Time) (bool, int, error) {
+	rec := r.emailLoginOTPs[string(userID)]
+	if rec == nil || rec.UsedAt != nil || !rec.ExpiresAt.After(now) {
+		return false, 0, nil
+	}
+	if bytes.Equal(rec.OTPHash, otpHash) {
+		ts := now
+		rec.UsedAt = &ts
+		return true, max(0, rec.MaxAttempts-rec.AttemptCount), nil
+	}
+	rec.AttemptCount++
+	left := max(0, rec.MaxAttempts-rec.AttemptCount)
+	if rec.AttemptCount >= rec.MaxAttempts {
+		ts := now
+		rec.UsedAt = &ts
+	}
+	return false, left, nil
+}
+func (r *memRepo) ListUserWebAuthnCredentials(_ context.Context, userID []byte) ([]auth.UserWebAuthnCredential, error) {
+	list := r.webauthnCredentials[string(userID)]
+	out := make([]auth.UserWebAuthnCredential, len(list))
+	copy(out, list)
+	return out, nil
+}
+func (r *memRepo) CreateUserWebAuthnCredential(_ context.Context, credential *auth.UserWebAuthnCredential) error {
+	if credential == nil {
+		return nil
+	}
+	cp := *credential
+	if len(cp.ID) == 0 {
+		cp.ID = uuidv7.MustBytes()
+	}
+	key := string(cp.UserID)
+	r.webauthnCredentials[key] = append(r.webauthnCredentials[key], cp)
+	return nil
+}
+func (r *memRepo) UpdateUserWebAuthnCredential(_ context.Context, userID, credentialID, credentialJSON []byte, usedAt time.Time) error {
+	key := string(userID)
+	list := r.webauthnCredentials[key]
+	for i := range list {
+		if bytes.Equal(list[i].CredentialID, credentialID) {
+			list[i].CredentialJSON = append([]byte(nil), credentialJSON...)
+			ts := usedAt
+			list[i].LastUsedAt = &ts
+			r.webauthnCredentials[key] = list
+			return nil
+		}
+	}
+	return nil
+}
+func (r *memRepo) DeleteAllUserWebAuthnCredentials(_ context.Context, userID []byte) error {
+	if r.deleteWebAuthnErr != nil {
+		return r.deleteWebAuthnErr
+	}
+	delete(r.webauthnCredentials, string(userID))
+	return nil
+}
+
+func (r *memRepo) CreateRole(_ context.Context, role *auth.Role) error { return nil }
+func (r *memRepo) UpdateRole(_ context.Context, role *auth.Role) error { return nil }
+func (r *memRepo) DeleteRole(_ context.Context, id []byte) error       { return nil }
+func (r *memRepo) GetRoleByID(_ context.Context, id []byte) (*auth.Role, error) {
+	return r.rolesByID[string(id)], nil
+}
+func (r *memRepo) GetRoleByName(_ context.Context, name string) (*auth.Role, error) {
+	return r.rolesByName[name], nil
+}
+func (r *memRepo) ListRoles(_ context.Context, _ string, _ string, _ int, _ int) ([]auth.Role, int64, error) {
+	return nil, 0, nil
+}
+func (r *memRepo) ListPermissions(_ context.Context, _ string, _ string, _ int, _ int) ([]auth.Permission, int64, error) {
+	return nil, 0, nil
+}
+func (r *memRepo) ListPermissionsByRoleID(_ context.Context, roleID []byte) ([]auth.Permission, error) {
+	return r.permsByRole[string(roleID)], r.permsErr
+}
+func (r *memRepo) HasRolePermission(_ context.Context, _ []byte, _ string) (bool, error) {
+	return true, nil
+}
+func (r *memRepo) GetPermissionByID(_ context.Context, _ []byte) (*auth.Permission, error) {
+	return nil, nil
+}
+func (r *memRepo) GetPermissionByKey(_ context.Context, _ string) (*auth.Permission, error) {
+	return nil, nil
+}
+func (r *memRepo) UpdatePermission(_ context.Context, _ *auth.Permission) error { return nil }
+func (r *memRepo) AssignPermission(_ context.Context, roleID, permissionID []byte) (*auth.RolePermission, error) {
+	return &auth.RolePermission{RoleID: roleID, PermissionID: permissionID}, nil
+}
+func (r *memRepo) RemovePermission(_ context.Context, _ []byte, _ []byte) error { return nil }
+
+const (
+	testWebAuthnCreationResponseJSON = `{
+	"id":"6xrtBhJQW6QU4tOaB4rrHaS2Ks0yDDL_q8jDC16DEjZ-VLVf4kCRkvl2xp2D71sTPYns-exsHQHTy3G-zJRK8g",
+	"rawId":"6xrtBhJQW6QU4tOaB4rrHaS2Ks0yDDL_q8jDC16DEjZ-VLVf4kCRkvl2xp2D71sTPYns-exsHQHTy3G-zJRK8g",
+	"type":"public-key",
+	"authenticatorAttachment":"platform",
+	"clientExtensionResults":{"appid":true},
+	"response":{
+		"attestationObject":"o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVjEdKbqkhPJnC90siSSsyDPQCYqlMGpUKA5fyklC2CEHvBBAAAAAAAAAAAAAAAAAAAAAAAAAAAAQOsa7QYSUFukFOLTmgeK6x2ktirNMgwy_6vIwwtegxI2flS1X-JAkZL5dsadg-9bEz2J7PnsbB0B08txvsyUSvKlAQIDJiABIVggLKF5xS0_BntttUIrm2Z2tgZ4uQDwllbdIfrrBMABCNciWCDHwin8Zdkr56iSIh0MrB5qZiEzYLQpEOREhMUkY6q4Vw",
+		"clientDataJSON":"eyJjaGFsbGVuZ2UiOiJXOEd6RlU4cEdqaG9SYldyTERsYW1BZnFfeTRTMUNaRzFWdW9lUkxBUnJFIiwib3JpZ2luIjoiaHR0cHM6Ly93ZWJhdXRobi5pbyIsInR5cGUiOiJ3ZWJhdXRobi5jcmVhdGUifQ",
+		"transports":["usb","nfc","fake"]
+	}
+}`
+	testWebAuthnAssertionResponseTemplate = `{
+	"id":"AI7D5q2P0LS-Fal9ZT7CHM2N5BLbUunF92T8b6iYC199bO2kagSuU05-5dZGqb1SP0A0lyTWng",
+	"rawId":"AI7D5q2P0LS-Fal9ZT7CHM2N5BLbUunF92T8b6iYC199bO2kagSuU05-5dZGqb1SP0A0lyTWng",
+	"clientExtensionResults":{"appID":"example.com"},
+	"type":"public-key",
+	"response":{
+		"authenticatorData":"dKbqkhPJnC90siSSsyDPQCYqlMGpUKA5fyklC2CEHvBFXJJiGa3OAAI1vMYKZIsLJfHwVQMANwCOw-atj9C0vhWpfWU-whzNjeQS21Lpxfdk_G-omAtffWztpGoErlNOfuXWRqm9Uj9ANJck1p6lAQIDJiABIVggKAhfsdHcBIc0KPgAcRyAIK_-Vi-nCXHkRHPNaCMBZ-4iWCBxB8fGYQSBONi9uvq0gv95dGWlhJrBwCsj_a4LJQKVHQ",
+		"clientDataJSON":"eyJjaGFsbGVuZ2UiOiJFNFBUY0lIX0hmWDFwQzZTaWdrMVNDOU5BbGdlenROMDQzOXZpOHpfYzlrIiwibmV3X2tleXNfbWF5X2JlX2FkZGVkX2hlcmUiOiJkbyBub3QgY29tcGFyZSBjbGllbnREYXRhSlNPTiBhZ2FpbnN0IGEgdGVtcGxhdGUuIFNlZSBodHRwczovL2dvby5nbC95YWJQZXgiLCJvcmlnaW4iOiJodHRwczovL3dlYmF1dGhuLmlvIiwidHlwZSI6IndlYmF1dGhuLmdldCJ9",
+		"signature":"MEUCIBtIVOQxzFYdyWQyxaLR0tik1TnuPhGVhXVSNgFwLmN5AiEAnxXdCq0UeAVGWxOaFcjBZ_mEZoXqNboY5IkQDdlWZYc",
+		"userHandle":"%s"
+	}
+}`
+	testWebAuthnRegistrationChallenge = "W8GzFU8pGjhoRbWrLDlamAfq_y4S1CZG1VuoeRLARrE"
+	testWebAuthnLoginChallenge        = "E4PTcIH_HfX1pC6Sigk1SC9NAlgeztN0439vi8z_c9k"
+)
+
+type testWebAuthnChallengeEnvelope struct {
+	Ceremony string                  `json:"ceremony"`
+	UserID   []byte                  `json:"user_id"`
+	Session  webauthnlib.SessionData `json:"session"`
+}
+
+func newWebAuthnAuthService(repo *memRepo, store *memTokenStore, withJWT bool) *service.AuthService {
+	cfg := config.AuthConfig{
+		WebAuthnRPID:          "webauthn.io",
+		WebAuthnRPDisplayName: "Wucher Test",
+		WebAuthnRPOrigins:     []string{"https://webauthn.io"},
+		WebAuthnChallengeTTL:  2 * time.Minute,
+	}
+	if withJWT {
+		cfg.JWTAccessSecret = "access"
+		cfg.JWTRefreshSecret = "refresh"
+		cfg.JWTAccessTTL = time.Minute
+		cfg.JWTRefreshTTL = time.Hour
+	}
+	return service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+}
+
+func seedWebAuthnUser(repo *memRepo, email string, verified bool) []byte {
+	userID := uuidv7.MustBytes()
+	row := &auth.User{
+		ID:       userID,
+		Email:    email,
+		RoleID:   uuidv7.MustBytes(),
+		IsActive: true,
+	}
+	if verified {
+		now := time.Now().UTC()
+		row.EmailVerifiedAt = &now
+	}
+	repo.users[string(userID)] = row
+	repo.usersByMail[email] = row
+	return userID
+}
+
+func putWebAuthnChallenge(t *testing.T, store *memTokenStore, token, ceremony string, userID []byte, session webauthnlib.SessionData) {
+	t.Helper()
+	envelope := testWebAuthnChallengeEnvelope{
+		Ceremony: ceremony,
+		UserID:   append([]byte(nil), userID...),
+		Session:  session,
+	}
+	raw, err := json.Marshal(envelope)
+	if err != nil {
+		t.Fatalf("marshal challenge envelope: %v", err)
+	}
+	store.store["auth:webauthn:challenge:"+token] = raw
+}
+
+func seedWebAuthnLoginCredential(t *testing.T, repo *memRepo, userID []byte) {
+	t.Helper()
+	credentialID, err := base64.RawURLEncoding.DecodeString("AI7D5q2P0LS-Fal9ZT7CHM2N5BLbUunF92T8b6iYC199bO2kagSuU05-5dZGqb1SP0A0lyTWng")
+	if err != nil {
+		t.Fatalf("decode credential id: %v", err)
+	}
+	publicKey, err := base64.RawURLEncoding.DecodeString("pQMmIAEhWCAoCF-x0dwEhzQo-ABxHIAgr_5WL6cJceREc81oIwFn7iJYIHEHx8ZhBIE42L26-rSC_3l0ZaWEmsHAKyP9rgslApUdAQI")
+	if err != nil {
+		t.Fatalf("decode public key: %v", err)
+	}
+	payload, err := json.Marshal(webauthnlib.Credential{
+		ID:              credentialID,
+		PublicKey:       publicKey,
+		AttestationType: "none",
+		Authenticator: webauthnlib.Authenticator{
+			SignCount: 1553097240,
+		},
+	})
+	if err != nil {
+		t.Fatalf("marshal credential: %v", err)
+	}
+	repo.webauthnCredentials[string(userID)] = []auth.UserWebAuthnCredential{{
+		UserID:         userID,
+		CredentialID:   credentialID,
+		CredentialJSON: payload,
+	}}
+}
+
+func seedWebAuthnRegistrationExistingCredential(t *testing.T, repo *memRepo, userID []byte) {
+	t.Helper()
+	credentialID, err := base64.RawURLEncoding.DecodeString("6xrtBhJQW6QU4tOaB4rrHaS2Ks0yDDL_q8jDC16DEjZ-VLVf4kCRkvl2xp2D71sTPYns-exsHQHTy3G-zJRK8g")
+	if err != nil {
+		t.Fatalf("decode credential id: %v", err)
+	}
+	payload, err := json.Marshal(webauthnlib.Credential{ID: credentialID})
+	if err != nil {
+		t.Fatalf("marshal credential: %v", err)
+	}
+	repo.webauthnCredentials[string(userID)] = []auth.UserWebAuthnCredential{{
+		UserID:         userID,
+		CredentialID:   credentialID,
+		CredentialJSON: payload,
+	}}
+}
+
+func webAuthnAssertionPayloadForUser(userID []byte) []byte {
+	handle := base64.RawURLEncoding.EncodeToString(userID)
+	return []byte(fmt.Sprintf(testWebAuthnAssertionResponseTemplate, handle))
+}
+
+func TestAuthHandler_Login_TOTPChallenge(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+		TOTPChallengeTTL: time.Minute,
+		TOTPIssuer:       "Wucher",
+		DefaultRoleName:  "admin",
+	}
+
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+
+	user, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+	if err != nil {
+		t.Fatalf("register failed: %v", err)
+	}
+	if err := repo.MarkEmailVerified(context.Background(), user.ID); err != nil {
+		t.Fatalf("mark email verified: %v", err)
+	}
+
+	// enable TOTP
+	secret, _, _, _ := svc.SetupTOTP(context.Background(), user.ID, user.Email)
+	code, _ := totp.GenerateCode(secret, time.Now().UTC())
+	_, _ = svc.ConfirmTOTP(context.Background(), user.ID, code)
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/login", h.Login)
+
+	payload := []byte(`{"data":{"type":"auth_login","attributes":{"email":"user@example.com","password":"Password123!"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/login", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusAccepted {
+		t.Fatalf("expected 202, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !bytes.Contains(body, []byte(`"totp_enabled":true`)) {
+		t.Fatalf("expected totp_enabled true in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"webauthn_configured":false`)) {
+		t.Fatalf("expected webauthn_configured false in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"linked_sso":false`)) {
+		t.Fatalf("expected linked_sso false in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"pin_configured":false`)) {
+		t.Fatalf("expected pin_configured false in response, got %s", string(body))
+	}
+}
+
+func TestAuthHandler_Register_Disabled(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	cfg := config.AuthConfig{
+		DisableRegister: true,
+		DefaultRoleName: "admin",
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/register", h.Register)
+
+	payload := []byte(`{\"data\":{\"type\":\"auth_register\",\"attributes\":{\"email\":\"user@example.com\",\"username\":\"john.doe\",\"password\":\"Password123!\",\"first_name\":\"John\",\"last_name\":\"Doe\"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/register", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("expected 403, got %d", resp.StatusCode)
+	}
+}
+
+func TestPermissionAttrs_WithPermissions(t *testing.T) {
+	repo := newMemRepo()
+	userID := uuidv7.MustBytes()
+	roleID := uuidv7.MustBytes()
+	repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID, RoleIDs: [][]byte{roleID}}
+	repo.permsByRole[string(roleID)] = []auth.Permission{
+		{ID: uuidv7.MustBytes(), Name: "Read User", Key: "user.read", Description: "Read users"},
+	}
+
+	svc := service.NewAuthService(repo, repo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	app := fiber.New()
+	var got []map[string]any
+	app.Get("/t", func(c *fiber.Ctx) error {
+		got = permissionAttrs(svc, c, userID)
+		return c.SendStatus(http.StatusOK)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/t", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if len(got) != 1 || got[0]["key"] != "user.read" {
+		t.Fatalf("unexpected permissions: %#v", got)
+	}
+}
+
+func TestPermissionModuleGroups_WithPermissions(t *testing.T) {
+	repo := newMemRepo()
+	userID := uuidv7.MustBytes()
+	roleID := uuidv7.MustBytes()
+	repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID, RoleIDs: [][]byte{roleID}}
+	repo.permsByRole[string(roleID)] = []auth.Permission{
+		{ID: uuidv7.MustBytes(), Name: "Read User", Key: "user.read", Description: "Read users"},
+		{ID: uuidv7.MustBytes(), Name: "Read Role", Key: "role.read", Description: "Read roles"},
+	}
+
+	svc := service.NewAuthService(repo, repo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	app := fiber.New()
+	var got []dto.PermissionGroupResource
+	app.Get("/t", func(c *fiber.Ctx) error {
+		got = permissionModuleGroups(svc, c, userID)
+		return c.SendStatus(http.StatusOK)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/t", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if len(got) != 2 || got[0].Module != "user" || got[1].Module != "role" {
+		t.Fatalf("unexpected grouped permissions: %#v", got)
+	}
+	if len(got[0].Permissions) != 1 || got[0].Permissions[0].Attributes.Key != "user.read" {
+		t.Fatalf("unexpected user module permissions: %#v", got[0])
+	}
+}
+
+func TestPermissionAttrs_OnError(t *testing.T) {
+	repo := newMemRepo()
+	repo.permsErr = errors.New("db error")
+	userID := uuidv7.MustBytes()
+	roleID := uuidv7.MustBytes()
+	repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID, RoleIDs: [][]byte{roleID}}
+
+	svc := service.NewAuthService(repo, repo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	app := fiber.New()
+	var got []map[string]any
+	app.Get("/t", func(c *fiber.Ctx) error {
+		got = permissionAttrs(svc, c, userID)
+		return c.SendStatus(http.StatusOK)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/t", nil)
+	_, _ = app.Test(req)
+	if len(got) != 0 {
+		t.Fatalf("expected empty permissions on error, got %#v", got)
+	}
+}
+
+func TestAuthHandler_Register_Success(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+		DefaultRoleName:  "admin",
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/register", h.Register)
+
+	payload := []byte(`{"data":{"type":"auth_register","attributes":{"email":"user@example.com","username":"john.doe","password":"Password123!","first_name":"John","last_name":"Doe"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/register", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !bytes.Contains(body, []byte(`"username":"john.doe"`)) {
+		t.Fatalf("expected response to include username, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"role_id":"`)) {
+		t.Fatalf("expected response to include role_id, got %s", string(body))
+	}
+	if len(resp.Header.Values("Set-Cookie")) != 0 {
+		t.Fatalf("expected register to not issue auth cookies")
+	}
+}
+
+func TestAuthHandler_ForgotPassword_SameResponseExistingAndMissingEmail(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	cfg := config.AuthConfig{
+		PasswordPepper:              "pepper",
+		HashTime:                    1,
+		HashMemoryKB:                64 * 1024,
+		HashThreads:                 4,
+		HashKeyLen:                  32,
+		PasswordResetURL:            "http://localhost:3000/reset-password",
+		PasswordResetTTL:            20 * time.Minute,
+		ForgotPasswordEmailCooldown: 0,
+		ForgotPasswordMinDuration:   0,
+		ForgotPasswordIPRateMax:     10,
+		ForgotPasswordIPRateWindow:  time.Minute,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "exists@example.com",
+		FirstName: "John",
+		LastName:  "Doe",
+		RoleID:    uuidv7.MustBytes(),
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/forgot-password", h.ForgotPassword)
+
+	existingPayload := []byte(`{"data":{"type":"auth_forgot_password","attributes":{"email":"exists@example.com"}}}`)
+	missingPayload := []byte(`{"data":{"type":"auth_forgot_password","attributes":{"email":"missing@example.com"}}}`)
+
+	req1, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/forgot-password", bytes.NewReader(existingPayload))
+	req1.Header.Set("Content-Type", "application/json")
+	resp1, err := app.Test(req1)
+	if err != nil {
+		t.Fatalf("existing app.Test: %v", err)
+	}
+	body1, _ := io.ReadAll(resp1.Body)
+
+	req2, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/forgot-password", bytes.NewReader(missingPayload))
+	req2.Header.Set("Content-Type", "application/json")
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("missing app.Test: %v", err)
+	}
+	body2, _ := io.ReadAll(resp2.Body)
+
+	if resp1.StatusCode != http.StatusOK || resp2.StatusCode != http.StatusOK {
+		t.Fatalf("expected both 200, got %d and %d", resp1.StatusCode, resp2.StatusCode)
+	}
+	if string(body1) != string(body2) {
+		t.Fatalf("forgot-password responses should match, got existing=%s missing=%s", string(body1), string(body2))
+	}
+}
+
+func TestAuthHandler_ForgotPassword_InvalidJSON(t *testing.T) {
+	repo := newMemRepo()
+	svc := service.NewAuthService(repo, repo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/forgot-password", h.ForgotPassword)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/forgot-password", bytes.NewReader([]byte(`{"data":`)))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_ForgotPassword_ValidationError(t *testing.T) {
+	repo := newMemRepo()
+	svc := service.NewAuthService(repo, repo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/forgot-password", h.ForgotPassword)
+
+	payload := []byte(`{"data":{"type":"auth_forgot_password","attributes":{"email":"invalid-email"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/forgot-password", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_ResetPassword_InvalidTokenGenericMessage(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		PasswordResetTTL: 20 * time.Minute,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/reset-password", h.ResetPassword)
+
+	payload := []byte(`{"data":{"type":"auth_reset_password","attributes":{"token":"missing-token","new_password":"Password123!Long","confirm_password":"Password123!Long"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/reset-password", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !bytes.Contains(body, []byte("This reset link is invalid or expired.")) {
+		t.Fatalf("expected generic invalid token message, got %s", string(body))
+	}
+}
+
+func TestAuthHandler_ResetPassword_InvalidJSON(t *testing.T) {
+	repo := newMemRepo()
+	cfg := config.AuthConfig{
+		PasswordPepper: "pepper",
+		HashTime:       1,
+		HashMemoryKB:   64 * 1024,
+		HashThreads:    4,
+		HashKeyLen:     32,
+	}
+	svc := service.NewAuthService(repo, repo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/reset-password", h.ResetPassword)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/reset-password", bytes.NewReader([]byte(`{"data":`)))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_ResetPassword_ValidationError(t *testing.T) {
+	repo := newMemRepo()
+	cfg := config.AuthConfig{
+		PasswordPepper: "pepper",
+		HashTime:       1,
+		HashMemoryKB:   64 * 1024,
+		HashThreads:    4,
+		HashKeyLen:     32,
+	}
+	svc := service.NewAuthService(repo, repo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/reset-password", h.ResetPassword)
+
+	payload := []byte(`{"data":{"type":"auth_reset_password","attributes":{"token":"","new_password":"short","confirm_password":"short"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/reset-password", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_ResetPassword_ConfirmMismatch(t *testing.T) {
+	repo := newMemRepo()
+	cfg := config.AuthConfig{
+		PasswordPepper: "pepper",
+		HashTime:       1,
+		HashMemoryKB:   64 * 1024,
+		HashThreads:    4,
+		HashKeyLen:     32,
+	}
+	svc := service.NewAuthService(repo, repo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/reset-password", h.ResetPassword)
+
+	payload := []byte(`{"data":{"type":"auth_reset_password","attributes":{"token":"token-x","new_password":"Password123!Long","confirm_password":"Different123!Long"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/reset-password", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !bytes.Contains(body, []byte("confirm_password must match new_password")) {
+		t.Fatalf("expected confirm mismatch message, got %s", string(body))
+	}
+}
+
+func TestAuthHandler_ResetPassword_InternalError(t *testing.T) {
+	repo := newMemRepo()
+	repo.consumeResetErr = errors.New("db unavailable")
+	cfg := config.AuthConfig{
+		PasswordPepper: "pepper",
+		HashTime:       1,
+		HashMemoryKB:   64 * 1024,
+		HashThreads:    4,
+		HashKeyLen:     32,
+	}
+	svc := service.NewAuthService(repo, repo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/reset-password", h.ResetPassword)
+
+	payload := []byte(`{"data":{"type":"auth_reset_password","attributes":{"token":"token-x","new_password":"Password123!Long","confirm_password":"Password123!Long"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/reset-password", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusInternalServerError {
+		t.Fatalf("expected 500, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_ResetPassword_Success(t *testing.T) {
+	repo := newMemRepo()
+	cfg := config.AuthConfig{
+		PasswordPepper: "pepper",
+		HashTime:       1,
+		HashMemoryKB:   64 * 1024,
+		HashThreads:    4,
+		HashKeyLen:     32,
+	}
+	svc := service.NewAuthService(repo, repo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	user := &auth.User{
+		ID:    uuidv7.MustBytes(),
+		Email: "user@example.com",
+	}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	rawToken := "valid-reset-token"
+	tokenHash := sha256.Sum256([]byte(rawToken))
+	repo.resetTokens[string(tokenHash[:])] = &auth.PasswordResetToken{
+		ID:        uuidv7.MustBytes(),
+		UserID:    user.ID,
+		TokenHash: tokenHash[:],
+		ExpiresAt: time.Now().UTC().Add(20 * time.Minute),
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/reset-password", h.ResetPassword)
+
+	payload := []byte(`{"data":{"type":"auth_reset_password","attributes":{"token":"valid-reset-token","new_password":"Password123!Long","confirm_password":"Password123!Long"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/reset-password", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if len(user.PasswordHash) == 0 || len(user.SaltValue) == 0 {
+		t.Fatalf("expected password hash and salt to be updated")
+	}
+}
+
+func TestAuthHandler_VerifyEmail(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:  "pepper",
+		HashTime:        1,
+		HashMemoryKB:    64 * 1024,
+		HashThreads:     4,
+		HashKeyLen:      32,
+		EmailVerifyTTL:  time.Hour,
+		EmailVerifyURL:  "http://localhost/verify",
+		DefaultRoleName: "admin",
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user, _ := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+
+	// token stored in mock
+	key := store.lastKey[len("auth:email_verify:"):]
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/verify-email", h.VerifyEmail)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/verify-email?token="+key, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if user.EmailVerifiedAt == nil {
+		t.Fatalf("expected email verified")
+	}
+}
+
+func TestAuthHandler_Login_Success(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+		DefaultRoleName:  "admin",
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user, _ := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+	if err := repo.MarkEmailVerified(context.Background(), user.ID); err != nil {
+		t.Fatalf("mark email verified: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/login", h.Login)
+
+	payload := []byte(`{"data":{"type":"auth_login","attributes":{"email":"user@example.com","password":"Password123!"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/login", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusAccepted {
+		t.Fatalf("expected 202, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !bytes.Contains(body, []byte(`"requires_email_otp":true`)) {
+		t.Fatalf("expected requires_email_otp true in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"requires_totp_setup":true`)) {
+		t.Fatalf("expected requires_totp_setup true in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"resend_cooldown_seconds"`)) {
+		t.Fatalf("expected resend_cooldown_seconds in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"max_resend_per_hour"`)) {
+		t.Fatalf("expected max_resend_per_hour in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"challenge_token"`)) {
+		t.Fatalf("expected challenge_token in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"webauthn_configured":false`)) {
+		t.Fatalf("expected webauthn_configured false in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"linked_sso":false`)) {
+		t.Fatalf("expected linked_sso false in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"pin_configured":false`)) {
+		t.Fatalf("expected pin_configured false in response, got %s", string(body))
+	}
+
+	_ = repo.CreateIdentity(context.Background(), &auth.UserIdentity{
+		ID:              uuidv7.MustBytes(),
+		UserID:          user.ID,
+		Provider:        "microsoft",
+		ProviderSubject: "sub",
+		Email:           user.Email,
+	})
+	resp2, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp2.StatusCode != http.StatusAccepted {
+		t.Fatalf("expected 202, got %d", resp2.StatusCode)
+	}
+	body2, _ := io.ReadAll(resp2.Body)
+	if !bytes.Contains(body2, []byte(`"linked_sso":true`)) {
+		t.Fatalf("expected linked_sso true in response, got %s", string(body2))
+	}
+}
+
+func TestAuthHandler_Refresh_And_Logout(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+		DefaultRoleName:  "admin",
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user, _ := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+	if err := repo.MarkEmailVerified(context.Background(), user.ID); err != nil {
+		t.Fatalf("mark email verified: %v", err)
+	}
+	pair, _ := svc.IssueTokens(context.Background(), user)
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/refresh", h.Refresh)
+	app.Post("/api/v1/auth/logout", h.Logout)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/refresh", nil)
+	req.AddCookie(&http.Cookie{Name: svc.RefreshCookieName(), Value: pair.RefreshToken})
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	req2, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/logout", nil)
+	req2.AddCookie(&http.Cookie{Name: svc.RefreshCookieName(), Value: pair.RefreshToken})
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp2.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp2.StatusCode)
+	}
+	if _, err := svc.RefreshTokens(context.Background(), pair.RefreshToken); !errors.Is(err, service.ErrInvalidToken) {
+		t.Fatalf("expected refresh token invalid after logout, got %v", err)
+	}
+	if _, err := svc.ParseAccessToken(context.Background(), pair.AccessToken); !errors.Is(err, service.ErrInvalidToken) {
+		t.Fatalf("expected access token invalid after logout, got %v", err)
+	}
+	sessions, err := svc.ListUserSessions(context.Background(), user.ID, "")
+	if err != nil {
+		t.Fatalf("list sessions after logout: %v", err)
+	}
+	if len(sessions) != 0 {
+		t.Fatalf("expected session removed after logout, got %#v", sessions)
+	}
+}
+
+func TestAuthHandler_MicrosoftFrontChannelLogout(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+		DefaultRoleName:  "admin",
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user, _ := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+	if err := repo.MarkEmailVerified(context.Background(), user.ID); err != nil {
+		t.Fatalf("mark email verified: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/front-channel-logout", h.MicrosoftFrontChannelLogout)
+
+	// A request carrying a foreign issuer must NOT revoke the session.
+	pairForeign, _ := svc.IssueTokens(context.Background(), user)
+	reqForeign, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/front-channel-logout?iss=https://evil.example.com", nil)
+	reqForeign.AddCookie(&http.Cookie{Name: svc.AccessCookieName(), Value: pairForeign.AccessToken})
+	reqForeign.AddCookie(&http.Cookie{Name: svc.RefreshCookieName(), Value: pairForeign.RefreshToken})
+	respForeign, err := app.Test(reqForeign)
+	if err != nil {
+		t.Fatalf("app.Test (foreign iss): %v", err)
+	}
+	if respForeign.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 for foreign iss, got %d", respForeign.StatusCode)
+	}
+	if _, err := svc.RefreshTokens(context.Background(), pairForeign.RefreshToken); err != nil {
+		t.Fatalf("expected session to survive foreign issuer logout, got %v", err)
+	}
+
+	// A legitimate front-channel logout revokes the caller's session and tokens.
+	pair, _ := svc.IssueTokens(context.Background(), user)
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/front-channel-logout?iss=https://login.microsoftonline.com/tenant/v2.0&sid=abc", nil)
+	req.AddCookie(&http.Cookie{Name: svc.AccessCookieName(), Value: pair.AccessToken})
+	req.AddCookie(&http.Cookie{Name: svc.RefreshCookieName(), Value: pair.RefreshToken})
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if cc := resp.Header.Get("Cache-Control"); !strings.Contains(cc, "no-store") {
+		t.Fatalf("expected no-store cache header, got %q", cc)
+	}
+	if got := resp.Header.Get("Content-Security-Policy"); !strings.Contains(got, "frame-ancestors") {
+		t.Fatalf("expected frame-ancestors CSP, got %q", got)
+	}
+	if _, err := svc.RefreshTokens(context.Background(), pair.RefreshToken); !errors.Is(err, service.ErrInvalidToken) {
+		t.Fatalf("expected refresh token invalid after front-channel logout, got %v", err)
+	}
+	if _, err := svc.ParseAccessToken(context.Background(), pair.AccessToken); !errors.Is(err, service.ErrInvalidToken) {
+		t.Fatalf("expected access token invalid after front-channel logout, got %v", err)
+	}
+	sessions, err := svc.ListUserSessions(context.Background(), user.ID, "")
+	if err != nil {
+		t.Fatalf("list sessions after logout: %v", err)
+	}
+	if len(sessions) != 0 {
+		t.Fatalf("expected sessions revoked after front-channel logout, got %#v", sessions)
+	}
+}
+
+func TestAuthHandler_MicrosoftFrontChannelLogout_UsesSidWithoutCookies(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+		DefaultRoleName:  "admin",
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user, _ := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+	if err := repo.MarkEmailVerified(context.Background(), user.ID); err != nil {
+		t.Fatalf("mark email verified: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/front-channel-logout", h.MicrosoftFrontChannelLogout)
+
+	const microsoftSID = "ms-session-abc"
+	pair, err := svc.IssueTokensWithClientForProviderAndMicrosoftSID(context.Background(), user, "", "", "microsoft", microsoftSID)
+	if err != nil {
+		t.Fatalf("issue microsoft tokens: %v", err)
+	}
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/front-channel-logout?iss=https://login.microsoftonline.com/tenant/v2.0&sid="+microsoftSID, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if _, err := svc.RefreshTokens(context.Background(), pair.RefreshToken); !errors.Is(err, service.ErrInvalidToken) {
+		t.Fatalf("expected refresh token invalid after sid logout, got %v", err)
+	}
+	if _, err := svc.ParseAccessToken(context.Background(), pair.AccessToken); !errors.Is(err, service.ErrInvalidToken) {
+		t.Fatalf("expected access token invalid after sid logout, got %v", err)
+	}
+}
+
+func TestAuthHandler_SetAuthCookiesForMicrosoftUsesNoneSecure(t *testing.T) {
+	svc := service.NewAuthService(newMemRepo(), newMemRepo(), newMemTokenStore(), nil, service.AuthServiceDependencies{
+		SSO: nil,
+		Protector: nil,
+		Config: config.AuthConfig{
+			JWTAccessSecret:   "access",
+			JWTRefreshSecret:  "refresh",
+			JWTAccessTTL:      time.Minute,
+			JWTRefreshTTL:     time.Hour,
+			JWTCookieSecure:   true,
+			JWTCookieSameSite: "Lax",
+		},
+	})
+
+	app := fiber.New()
+	app.Get("/cookie", func(c *fiber.Ctx) error {
+		setAuthCookiesForProvider(c, svc, service.TokenPair{
+			AccessToken:  "a",
+			RefreshToken: "r",
+			RefreshTTL:   time.Hour,
+		}, "microsoft")
+		return c.SendStatus(http.StatusOK)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/cookie", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	cookies := resp.Header.Values("Set-Cookie")
+	if len(cookies) == 0 {
+		t.Fatalf("expected Set-Cookie headers")
+	}
+	for _, raw := range cookies {
+		if !strings.Contains(raw, "SameSite=None") {
+			t.Fatalf("expected SameSite=None for microsoft cookie, got %q", raw)
+		}
+		if !strings.Contains(strings.ToLower(raw), "secure") {
+			t.Fatalf("expected Secure for microsoft cookie, got %q", raw)
+		}
+	}
+}
+
+func TestAuthHandler_SetAuthCookiesForMicrosoftFallsBackWhenInsecure(t *testing.T) {
+	svc := service.NewAuthService(newMemRepo(), newMemRepo(), newMemTokenStore(), nil, service.AuthServiceDependencies{
+		SSO: nil,
+		Protector: nil,
+		Config: config.AuthConfig{
+			JWTAccessSecret:   "access",
+			JWTRefreshSecret:  "refresh",
+			JWTAccessTTL:      time.Minute,
+			JWTRefreshTTL:     time.Hour,
+			JWTCookieSecure:   false,
+			JWTCookieSameSite: "Lax",
+		},
+	})
+
+	app := fiber.New()
+	app.Get("/cookie", func(c *fiber.Ctx) error {
+		setAuthCookiesForProvider(c, svc, service.TokenPair{
+			AccessToken:  "a",
+			RefreshToken: "r",
+			RefreshTTL:   time.Hour,
+		}, "microsoft")
+		return c.SendStatus(http.StatusOK)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/cookie", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	cookies := resp.Header.Values("Set-Cookie")
+	if len(cookies) == 0 {
+		t.Fatalf("expected Set-Cookie headers")
+	}
+	for _, raw := range cookies {
+		if strings.Contains(raw, "SameSite=None") {
+			t.Fatalf("expected fallback same-site for insecure microsoft cookie, got %q", raw)
+		}
+		if strings.Contains(strings.ToLower(raw), "secure") {
+			t.Fatalf("expected insecure microsoft cookie fallback, got %q", raw)
+		}
+	}
+}
+
+
+func TestAuthHandler_Logout_DoesNotRedirectToSSO(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:        "pepper",
+		HashTime:              1,
+		HashMemoryKB:          64 * 1024,
+		HashThreads:           4,
+		HashKeyLen:            32,
+		JWTAccessSecret:       "access",
+		JWTRefreshSecret:      "refresh",
+		JWTAccessTTL:          time.Minute,
+		JWTRefreshTTL:         time.Hour,
+		DefaultRoleName:       "admin",
+		SSOSuccessRedirectURL: "http://localhost/logout-done",
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{
+		SSO:       &serviceMockSSO{},
+		Protector: nil,
+		Config:    cfg,
+	})
+	user, _ := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+	_ = repo.MarkEmailVerified(context.Background(), user.ID)
+	pair, _ := svc.IssueTokens(context.Background(), user)
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/logout", h.Logout)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/logout", nil)
+	req.Header.Set("Accept", "text/html")
+	req.AddCookie(&http.Cookie{Name: svc.RefreshCookieName(), Value: pair.RefreshToken})
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_Logout_DoesNotReturnSSOLogoutURL(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:        "pepper",
+		HashTime:              1,
+		HashMemoryKB:          64 * 1024,
+		HashThreads:           4,
+		HashKeyLen:            32,
+		JWTAccessSecret:       "access",
+		JWTRefreshSecret:      "refresh",
+		JWTAccessTTL:          time.Minute,
+		JWTRefreshTTL:         time.Hour,
+		DefaultRoleName:       "admin",
+		SSOSuccessRedirectURL: "http://localhost/logout-done",
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{
+		SSO:       &serviceMockSSO{},
+		Protector: nil,
+		Config:    cfg,
+	})
+	user, _ := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+	_ = repo.MarkEmailVerified(context.Background(), user.ID)
+	pair, _ := svc.IssueTokens(context.Background(), user)
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/logout", h.Logout)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/logout", nil)
+	req.Header.Set("X-Requested-With", "XMLHttpRequest")
+	req.AddCookie(&http.Cookie{Name: svc.RefreshCookieName(), Value: pair.RefreshToken})
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if bytes.Contains(body, []byte(`sso_logout_url`)) {
+		t.Fatalf("did not expect sso logout url in body, got %s", string(body))
+	}
+}
+
+func TestAuthHandler_Me(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByID[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	ssoEmail := "u.sso@e.com"
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com", SSOEmail: &ssoEmail, RoleID: roleID}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/me", func(c *fiber.Ctx) error {
+		c.Locals("user_id", user.ID)
+		return h.Me(c)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/me", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !bytes.Contains(body, []byte(`"totp_enabled":false`)) {
+		t.Fatalf("expected totp_enabled false in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"webauthn_configured":false`)) {
+		t.Fatalf("expected webauthn_configured false in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"pin_configured":false`)) {
+		t.Fatalf("expected pin_configured false in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"pin_blocked":false`)) {
+		t.Fatalf("expected pin_blocked false in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"email_sso":"u.sso@e.com"`)) {
+		t.Fatalf("expected email_sso in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"microsoft_scope":""`)) {
+		t.Fatalf("expected microsoft_scope in response, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"dul_bases":[]`)) {
+		t.Fatalf("expected dul_bases empty array in response, got %s", string(body))
+	}
+}
+
+func TestAuthHandler_Me_PilotDULBases(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByID[string(roleID)] = &auth.Role{ID: roleID, Name: "pilot"}
+
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "pilot@e.com", RoleID: roleID}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	baseID := uuidv7.MustBytes()
+	raw := strings.ToLower(hex.EncodeToString(baseID)) + "|" +
+		strings.ToLower(hex.EncodeToString([]byte("Halim Base"))) + "|dul|" +
+		strings.ToLower(hex.EncodeToString([]byte("hems")))
+	contactSvc := &stubContactService{
+		getItem: &contact.ContactListItem{
+			UserID:       user.ID,
+			RoleCode:     "pilot",
+			BaseRolesRaw: &raw,
+		},
+	}
+
+	h := NewAuthHandler(svc).WithContactService(contactSvc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/me", func(c *fiber.Ctx) error {
+		c.Locals("user_id", user.ID)
+		return h.Me(c)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/me", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !bytes.Contains(body, []byte(`"dul_bases":[`)) ||
+		!bytes.Contains(body, []byte(`"name":"Halim Base"`)) ||
+		!bytes.Contains(body, []byte(`"category":"hems"`)) {
+		t.Fatalf("expected pilot dul_bases payload, got %s", string(body))
+	}
+}
+
+func TestAuthHandler_Me_WithSessionAuthContext(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	roleID := uuidv7.MustBytes()
+	repo.rolesByID[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com", RoleID: roleID, IsActive: true}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	t.Run("email session", func(t *testing.T) {
+		pair, err := svc.IssueTokensWithClient(context.Background(), user, "Mozilla/5.0", "127.0.0.1")
+		if err != nil {
+			t.Fatalf("issue tokens: %v", err)
+		}
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Get("/api/v1/auth/me", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.Me(c)
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/me", nil)
+		req.AddCookie(&http.Cookie{Name: svc.AccessCookieName(), Value: pair.AccessToken})
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if !bytes.Contains(body, []byte(`"login_method":"email"`)) {
+			t.Fatalf("expected login_method email in response, got %s", string(body))
+		}
+		if !bytes.Contains(body, []byte(`"auth_provider":"email"`)) {
+			t.Fatalf("expected auth_provider email in response, got %s", string(body))
+		}
+	})
+
+	t.Run("microsoft session", func(t *testing.T) {
+		pair, err := svc.IssueTokensWithClientForProvider(context.Background(), user, "Mozilla/5.0", "127.0.0.1", "microsoft")
+		if err != nil {
+			t.Fatalf("issue provider tokens: %v", err)
+		}
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Get("/api/v1/auth/me", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.Me(c)
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/me", nil)
+		req.AddCookie(&http.Cookie{Name: svc.AccessCookieName(), Value: pair.AccessToken})
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if !bytes.Contains(body, []byte(`"login_method":"sso"`)) {
+			t.Fatalf("expected login_method sso in response, got %s", string(body))
+		}
+		if !bytes.Contains(body, []byte(`"auth_provider":"microsoft"`)) {
+			t.Fatalf("expected auth_provider microsoft in response, got %s", string(body))
+		}
+	})
+}
+
+func TestAuthHandler_UpdateTimezone(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByID[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user := &auth.User{ID: uuidv7.MustBytes(), Email: "u@e.com", RoleID: roleID, Timezone: "UTC"}
+	if err := repo.CreateUser(context.Background(), user); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/auth/me/timezone", func(c *fiber.Ctx) error {
+		c.Locals("user_id", user.ID)
+		return h.UpdateTimezone(c)
+	})
+
+	t.Run("success", func(t *testing.T) {
+		payload := []byte(`{"data":{"type":"auth_timezone_update","attributes":{"timezone":"Asia/Jakarta"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/auth/me/timezone", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if got := repo.users[string(user.ID)].Timezone; got != "Asia/Jakarta" {
+			t.Fatalf("expected timezone updated, got %q", got)
+		}
+	})
+
+	t.Run("invalid timezone", func(t *testing.T) {
+		payload := []byte(`{"data":{"type":"auth_timezone_update","attributes":{"timezone":"UTC+7"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/auth/me/timezone", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("empty timezone", func(t *testing.T) {
+		payload := []byte(`{"data":{"type":"auth_timezone_update","attributes":{"timezone":"   "}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/auth/me/timezone", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/auth/me/timezone", bytes.NewReader([]byte(`{\"data\":`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("unauthorized missing auth context", func(t *testing.T) {
+		appNoAuth := fiber.New()
+		appNoAuth.Patch("/api/v1/auth/me/timezone", h.UpdateTimezone)
+		payload := []byte(`{"data":{"type":"auth_timezone_update","attributes":{"timezone":"Asia/Jakarta"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/auth/me/timezone", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := appNoAuth.Test(req)
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_TOTPSetup_Confirm_Disable(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	cfg := config.AuthConfig{
+		TOTPIssuer:       "Wucher",
+		TOTPChallengeTTL: time.Minute,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	userID := uuidv7.MustBytes()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", append([]byte(nil), userID...))
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/totp/setup", h.TOTPSetup)
+	app.Post("/api/v1/auth/totp/confirm", h.TOTPConfirm)
+	app.Post("/api/v1/auth/totp/disable", h.TOTPDisable)
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       userID,
+		Email:    "user@example.com",
+		RoleID:   uuidv7.MustBytes(),
+		IsActive: true,
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	payload := []byte(fmt.Sprintf(`{"data":{"type":"auth_totp_setup","attributes":{"user_id":"%s","email":"user@example.com"}}}`, func() string { s, _ := uuidv7.BytesToString(userID); return s }()))
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/setup", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	// confirm
+	secretRec, _ := repo.GetUserTOTP(context.Background(), userID)
+	secret, _ := protector.Decrypt(secretRec.SecretEncrypted)
+	code, _ := totp.GenerateCode(string(secret), time.Now().UTC())
+
+	payload2 := []byte(fmt.Sprintf(`{"data":{"type":"auth_totp_confirm","attributes":{"user_id":"%s","code":"%s"}}}`, func() string { s, _ := uuidv7.BytesToString(userID); return s }(), code))
+	req2, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/confirm", bytes.NewReader(payload2))
+	req2.Header.Set("Content-Type", "application/json")
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp2.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp2.StatusCode)
+	}
+
+	// disable
+	payload3 := []byte(fmt.Sprintf(`{"data":{"type":"auth_totp_disable","attributes":{"user_id":"%s"}}}`, func() string { s, _ := uuidv7.BytesToString(userID); return s }()))
+	req3, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/disable", bytes.NewReader(payload3))
+	req3.Header.Set("Content-Type", "application/json")
+	resp3, err := app.Test(req3)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp3.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp3.StatusCode)
+	}
+}
+
+func TestAuthHandler_TOTPResetSetup_WithPassword(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:  "pepper",
+		HashTime:        1,
+		HashMemoryKB:    64 * 1024,
+		HashThreads:     4,
+		HashKeyLen:      32,
+		DefaultRoleName: "admin",
+		TOTPIssuer:      "Wucher",
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+	user, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+	if err != nil {
+		t.Fatalf("register failed: %v", err)
+	}
+	if _, _, _, err := svc.SetupTOTP(context.Background(), user.ID, user.Email); err != nil {
+		t.Fatalf("setup totp failed: %v", err)
+	}
+	if repo.totp[string(user.ID)] == nil {
+		t.Fatalf("expected totp setup to exist")
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/totp/reset-setup", func(c *fiber.Ctx) error {
+		c.Locals("user_id", user.ID)
+		return h.TOTPResetSetup(c)
+	})
+
+	payload := []byte(`{"data":{"type":"auth_totp_reset_setup","attributes":{"method":"password","password":"Password123!"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/reset-setup", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if repo.totp[string(user.ID)] != nil {
+		t.Fatalf("expected totp setup to be removed")
+	}
+}
+
+func TestAuthHandler_TOTPResetSetup_Branches(t *testing.T) {
+	newFixture := func(t *testing.T) (*memRepo, *service.AuthService, *auth.User) {
+		t.Helper()
+
+		repo := newMemRepo()
+		store := newMemTokenStore()
+
+		key := make([]byte, 32)
+		for i := range key {
+			key[i] = byte(i + 1)
+		}
+		protector, err := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+		if err != nil {
+			t.Fatalf("protector: %v", err)
+		}
+
+		roleID := uuidv7.MustBytes()
+		repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+		repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+		cfg := config.AuthConfig{
+			PasswordPepper:            "pepper",
+			HashTime:                  1,
+			HashMemoryKB:              64 * 1024,
+			HashThreads:               4,
+			HashKeyLen:                32,
+			DefaultRoleName:           "admin",
+			TOTPIssuer:                "Wucher",
+			SecurityPINMaxAttempts:    3,
+			SecurityPINLockDuration:   time.Minute,
+			SecurityPINActionTokenTTL: time.Minute,
+		}
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+		user, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+		if err != nil {
+			t.Fatalf("register failed: %v", err)
+		}
+		if _, _, _, err := svc.SetupTOTP(context.Background(), user.ID, user.Email); err != nil {
+			t.Fatalf("setup totp failed: %v", err)
+		}
+		return repo, svc, user
+	}
+
+	t.Run("missing auth context", func(t *testing.T) {
+		_, svc, _ := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/totp/reset-setup", h.TOTPResetSetup)
+
+		payload := []byte(`{"data":{"type":"auth_totp_reset_setup","attributes":{"method":"password","password":"Password123!"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		_, svc, user := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/totp/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.TOTPResetSetup(c)
+		})
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/reset-setup", bytes.NewReader([]byte(`{"data":`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		_, svc, user := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/totp/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.TOTPResetSetup(c)
+		})
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/reset-setup", bytes.NewReader([]byte(`{}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("password required", func(t *testing.T) {
+		_, svc, user := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/totp/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.TOTPResetSetup(c)
+		})
+
+		payload := []byte(`{"data":{"type":"auth_totp_reset_setup","attributes":{"method":"password"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("wrong password", func(t *testing.T) {
+		_, svc, user := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/totp/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.TOTPResetSetup(c)
+		})
+
+		payload := []byte(`{"data":{"type":"auth_totp_reset_setup","attributes":{"method":"password","password":"WrongPassword!"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("user not found", func(t *testing.T) {
+		_, svc, _ := newFixture(t)
+		h := NewAuthHandler(svc)
+		missingUserID := uuidv7.MustBytes()
+		app := fiber.New()
+		app.Post("/api/v1/auth/totp/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", missingUserID)
+			return h.TOTPResetSetup(c)
+		})
+
+		payload := []byte(`{"data":{"type":"auth_totp_reset_setup","attributes":{"method":"password","password":"Password123!"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("pin invalid token", func(t *testing.T) {
+		_, svc, user := newFixture(t)
+		if err := svc.SetSecurityPIN(context.Background(), user.ID, "123456"); err != nil {
+			t.Fatalf("set pin: %v", err)
+		}
+
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/totp/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.TOTPResetSetup(c)
+		})
+
+		payload := []byte(`{"data":{"type":"auth_totp_reset_setup","attributes":{"method":"pin"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set(pinVerificationHeader, "bad-token")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("pin success", func(t *testing.T) {
+		repo, svc, user := newFixture(t)
+		if err := svc.SetSecurityPIN(context.Background(), user.ID, "123456"); err != nil {
+			t.Fatalf("set pin: %v", err)
+		}
+		actionToken, err := svc.VerifySecurityPINForAction(context.Background(), user.ID, "123456", sharedconst.PinActionTOTPResetSetup)
+		if err != nil {
+			t.Fatalf("verify pin: %v", err)
+		}
+
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/totp/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.TOTPResetSetup(c)
+		})
+
+		payload := []byte(`{"data":{"type":"auth_totp_reset_setup","attributes":{"method":"pin"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set(pinVerificationHeader, actionToken)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.totp[string(user.ID)] != nil {
+			t.Fatalf("expected totp setup removed after pin reset")
+		}
+	})
+
+	t.Run("pin delete setup error", func(t *testing.T) {
+		repo, svc, user := newFixture(t)
+		repo.deleteTOTPErr = errors.New("delete failed")
+		if err := svc.SetSecurityPIN(context.Background(), user.ID, "123456"); err != nil {
+			t.Fatalf("set pin: %v", err)
+		}
+		actionToken, err := svc.VerifySecurityPINForAction(context.Background(), user.ID, "123456", sharedconst.PinActionTOTPResetSetup)
+		if err != nil {
+			t.Fatalf("verify pin: %v", err)
+		}
+
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/totp/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.TOTPResetSetup(c)
+		})
+
+		payload := []byte(`{"data":{"type":"auth_totp_reset_setup","attributes":{"method":"pin"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set(pinVerificationHeader, actionToken)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_WebAuthnResetSetup_WithPIN(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:  "pepper",
+		HashTime:        1,
+		HashMemoryKB:    64 * 1024,
+		HashThreads:     4,
+		HashKeyLen:      32,
+		DefaultRoleName: "admin",
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+	user, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+	if err != nil {
+		t.Fatalf("register failed: %v", err)
+	}
+	if err := svc.SetSecurityPIN(context.Background(), user.ID, "123456"); err != nil {
+		t.Fatalf("set pin failed: %v", err)
+	}
+	actionToken, err := svc.VerifySecurityPINForAction(context.Background(), user.ID, "123456", sharedconst.PinActionWebAuthnResetSetup)
+	if err != nil {
+		t.Fatalf("pin verify for action failed: %v", err)
+	}
+	seedWebAuthnLoginCredential(t, repo, user.ID)
+	if len(repo.webauthnCredentials[string(user.ID)]) == 0 {
+		t.Fatalf("expected webauthn credentials to exist")
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/webauthn/reset-setup", func(c *fiber.Ctx) error {
+		c.Locals("user_id", user.ID)
+		return h.WebAuthnResetSetup(c)
+	})
+
+	payload := []byte(`{"data":{"type":"auth_webauthn_reset_setup","attributes":{"method":"pin"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/reset-setup", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set(pinVerificationHeader, actionToken)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if len(repo.webauthnCredentials[string(user.ID)]) != 0 {
+		t.Fatalf("expected webauthn credentials to be removed")
+	}
+}
+
+func TestAuthHandler_WebAuthnResetSetup_Branches(t *testing.T) {
+	newFixture := func(t *testing.T) (*memRepo, *service.AuthService, *auth.User) {
+		t.Helper()
+
+		repo := newMemRepo()
+		store := newMemTokenStore()
+
+		key := make([]byte, 32)
+		for i := range key {
+			key[i] = byte(i + 1)
+		}
+		protector, err := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+		if err != nil {
+			t.Fatalf("protector: %v", err)
+		}
+
+		roleID := uuidv7.MustBytes()
+		repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+		repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+		cfg := config.AuthConfig{
+			PasswordPepper:            "pepper",
+			HashTime:                  1,
+			HashMemoryKB:              64 * 1024,
+			HashThreads:               4,
+			HashKeyLen:                32,
+			DefaultRoleName:           "admin",
+			SecurityPINMaxAttempts:    3,
+			SecurityPINLockDuration:   time.Minute,
+			SecurityPINActionTokenTTL: time.Minute,
+		}
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+		user, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+		if err != nil {
+			t.Fatalf("register failed: %v", err)
+		}
+		seedWebAuthnLoginCredential(t, repo, user.ID)
+		return repo, svc, user
+	}
+
+	t.Run("missing auth context", func(t *testing.T) {
+		_, svc, _ := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/reset-setup", h.WebAuthnResetSetup)
+
+		payload := []byte(`{"data":{"type":"auth_webauthn_reset_setup","attributes":{"method":"password","password":"Password123!"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		_, svc, user := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.WebAuthnResetSetup(c)
+		})
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/reset-setup", bytes.NewReader([]byte(`{"data":`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		_, svc, user := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.WebAuthnResetSetup(c)
+		})
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/reset-setup", bytes.NewReader([]byte(`{}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("password required", func(t *testing.T) {
+		_, svc, user := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.WebAuthnResetSetup(c)
+		})
+
+		payload := []byte(`{"data":{"type":"auth_webauthn_reset_setup","attributes":{"method":"password"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("wrong password", func(t *testing.T) {
+		_, svc, user := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.WebAuthnResetSetup(c)
+		})
+
+		payload := []byte(`{"data":{"type":"auth_webauthn_reset_setup","attributes":{"method":"password","password":"WrongPassword!"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("user not found", func(t *testing.T) {
+		_, svc, _ := newFixture(t)
+		h := NewAuthHandler(svc)
+		missingUserID := uuidv7.MustBytes()
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", missingUserID)
+			return h.WebAuthnResetSetup(c)
+		})
+
+		payload := []byte(`{"data":{"type":"auth_webauthn_reset_setup","attributes":{"method":"password","password":"Password123!"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("pin invalid token", func(t *testing.T) {
+		_, svc, user := newFixture(t)
+		if err := svc.SetSecurityPIN(context.Background(), user.ID, "123456"); err != nil {
+			t.Fatalf("set pin: %v", err)
+		}
+
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.WebAuthnResetSetup(c)
+		})
+
+		payload := []byte(`{"data":{"type":"auth_webauthn_reset_setup","attributes":{"method":"pin"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set(pinVerificationHeader, "bad-token")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("pin delete setup error", func(t *testing.T) {
+		repo, svc, user := newFixture(t)
+		repo.deleteWebAuthnErr = errors.New("delete failed")
+		if err := svc.SetSecurityPIN(context.Background(), user.ID, "123456"); err != nil {
+			t.Fatalf("set pin: %v", err)
+		}
+		actionToken, err := svc.VerifySecurityPINForAction(context.Background(), user.ID, "123456", sharedconst.PinActionWebAuthnResetSetup)
+		if err != nil {
+			t.Fatalf("verify pin: %v", err)
+		}
+
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.WebAuthnResetSetup(c)
+		})
+
+		payload := []byte(`{"data":{"type":"auth_webauthn_reset_setup","attributes":{"method":"pin"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set(pinVerificationHeader, actionToken)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("password success", func(t *testing.T) {
+		repo, svc, user := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/reset-setup", func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return h.WebAuthnResetSetup(c)
+		})
+
+		payload := []byte(`{"data":{"type":"auth_webauthn_reset_setup","attributes":{"method":"password","password":"Password123!"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/reset-setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if len(repo.webauthnCredentials[string(user.ID)]) != 0 {
+			t.Fatalf("expected webauthn credentials removed")
+		}
+	})
+}
+
+func TestAuthHandler_MicrosoftLogin_Callback(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["user"] = &auth.Role{ID: roleID, Name: "user"}
+
+	cfg := config.AuthConfig{
+		SSOStateTTL:           time.Minute,
+		JWTAccessSecret:       "access",
+		JWTRefreshSecret:      "refresh",
+		JWTAccessTTL:          time.Minute,
+		JWTRefreshTTL:         time.Hour,
+		SSOSuccessRedirectURL: "http://localhost/cb",
+	}
+	sso := &serviceMockSSO{claims: service.MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane Doe"}}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       userID,
+		Email:    "user@example.com",
+		RoleID:   roleID,
+		Timezone: "UTC",
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	_ = repo.CreateIdentity(context.Background(), &auth.UserIdentity{
+		ID:              uuidv7.MustBytes(),
+		UserID:          userID,
+		Provider:        "microsoft",
+		ProviderSubject: "sub",
+		Email:           "user@example.com",
+	})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/login", h.MicrosoftLogin)
+	app.Get("/api/v1/auth/microsoft/callback", h.MicrosoftCallback)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/login", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !bytes.Contains(body, []byte(`"type":"auth_microsoft_url"`)) {
+		t.Fatalf("expected JSON:API type auth_microsoft_url, got body: %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"url":"http://example.com?`)) || !bytes.Contains(body, []byte(`state=`)) {
+		t.Fatalf("expected oauth redirect url in response body, got body: %s", string(body))
+	}
+
+	// Extract state from token store
+	state := store.lastKey[len("auth:sso_state:"):]
+	req2, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/callback?code=code&state="+state, nil)
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp2.StatusCode != http.StatusFound {
+		t.Fatalf("expected 302, got %d", resp2.StatusCode)
+	}
+}
+
+func TestAuthHandler_Exchange(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["user"] = &auth.Role{ID: roleID, Name: "user"}
+
+	cfg := config.AuthConfig{
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{Config: cfg})
+
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       userID,
+		Email:    "user@example.com",
+		RoleID:   roleID,
+		Timezone: "UTC",
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/exchange", h.Exchange)
+
+	t.Run("success", func(t *testing.T) {
+		exp := time.Now().UTC().Add(5 * time.Minute).Unix()
+		payload := fmt.Sprintf(`{"data":{"type":"auth_exchange","attributes":{"access_token":"at","id_token":"it","id_token_claims":{"sub":"sub-123","preferred_username":"user@example.com","name":"User Name","exp":%d,"tid":"tenant-1","oid":"obj-1"}}}}`, exp)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/exchange", strings.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			body, _ := io.ReadAll(resp.Body)
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(body))
+		}
+	})
+
+	t.Run("expired id token claim", func(t *testing.T) {
+		exp := time.Now().UTC().Add(-5 * time.Minute).Unix()
+		payload := fmt.Sprintf(`{"data":{"type":"auth_exchange","attributes":{"access_token":"at","id_token":"it","id_token_claims":{"sub":"sub-123","preferred_username":"user@example.com","exp":%d}}}}`, exp)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/exchange", strings.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_MicrosoftLogin_CallbackXHR_NoRedirect(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["user"] = &auth.Role{ID: roleID, Name: "user"}
+
+	cfg := config.AuthConfig{
+		SSOStateTTL:           time.Minute,
+		JWTAccessSecret:       "access",
+		JWTRefreshSecret:      "refresh",
+		JWTAccessTTL:          time.Minute,
+		JWTRefreshTTL:         time.Hour,
+		SSOSuccessRedirectURL: "http://localhost:3000/challenge/msentra",
+	}
+	sso := &serviceMockSSO{claims: service.MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane Doe"}}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       userID,
+		Email:    "user@example.com",
+		RoleID:   roleID,
+		Timezone: "UTC",
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	_ = repo.CreateIdentity(context.Background(), &auth.UserIdentity{
+		ID:              uuidv7.MustBytes(),
+		UserID:          userID,
+		Provider:        "microsoft",
+		ProviderSubject: "sub",
+		Email:           "user@example.com",
+	})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/login", h.MicrosoftLogin)
+	app.Get("/api/v1/auth/microsoft/callback", h.MicrosoftCallback)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/login", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	state := store.lastKey[len("auth:sso_state:"):]
+	req2, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/callback?code=code&state="+state, nil)
+	req2.Header.Set("Accept", "application/json")
+	req2.Header.Set("Sec-Fetch-Mode", "cors")
+	req2.Header.Set("Sec-Fetch-Dest", "empty")
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp2.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp2.StatusCode)
+	}
+	body, _ := io.ReadAll(resp2.Body)
+	if !bytes.Contains(body, []byte(`"type":"auth_identity"`)) {
+		t.Fatalf("expected auth_identity response, got body: %s", string(body))
+	}
+}
+
+func TestAuthHandler_MicrosoftLogin_UsesInteractivePromptByDefault(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	sso := &serviceMockSSO{authURL: "http://example.com?state=%s&prompt=select_account"}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{
+		SSO:       sso,
+		Protector: nil,
+		Config:    config.AuthConfig{SSOStateTTL: time.Minute},
+	})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/login", h.MicrosoftLogin)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/login", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	// /microsoft/login is now an interactive sign-in; silent prompt=none belongs to
+	// /microsoft/login-check only.
+	if !bytes.Contains(body, []byte(`prompt=select_account`)) {
+		t.Fatalf("expected interactive prompt=select_account in response body, got: %s", string(body))
+	}
+	if bytes.Contains(body, []byte(`prompt=none`)) {
+		t.Fatalf("expected interactive login, but response used silent prompt=none: %s", string(body))
+	}
+}
+
+func TestAuthHandler_MicrosoftCallback_LoginCheck_NoMicrosoftSession(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	sso := &serviceMockSSO{claims: service.MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane"}}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{
+		SSO:       sso,
+		Protector: nil,
+		Config:    config.AuthConfig{SSOStateTTL: time.Minute},
+	})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/callback", h.MicrosoftCallback)
+
+	// The silent login_check flow is seeded by the session-check entrypoint (no longer by
+	// /microsoft/login, which is now an interactive sign-in).
+	if _, err := svc.BeginMicrosoftSessionCheck(context.Background()); err != nil {
+		t.Fatalf("begin session check: %v", err)
+	}
+
+	state := store.lastKey[len("auth:sso_state:"):]
+	req2, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/callback?state="+state+"&error=login_required", nil)
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("app.Test callback: %v", err)
+	}
+	if resp2.StatusCode != http.StatusFound {
+		t.Fatalf("expected 302, got %d", resp2.StatusCode)
+	}
+	location := resp2.Header.Get("Location")
+	if !strings.Contains(location, "http://example.com?") || !strings.Contains(location, "state=") {
+		t.Fatalf("expected redirect to interactive microsoft auth url, got: %s", location)
+	}
+	if !strings.Contains(location, "prompt=select_account") {
+		t.Fatalf("expected interactive fallback with prompt=select_account, got: %s", location)
+	}
+	if _, ok := store.store["auth:sso_state:"+state]; ok {
+		t.Fatalf("expected state to be cleared for failed login_check flow")
+	}
+}
+
+func TestAuthHandler_MicrosoftCallback_LoginCheckStrict_NoMicrosoftSession(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	sso := &serviceMockSSO{claims: service.MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane"}}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{
+		SSO:       sso,
+		Protector: nil,
+		Config:    config.AuthConfig{SSOStateTTL: time.Minute},
+	})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/login-check", h.MicrosoftLoginCheck)
+	app.Get("/api/v1/auth/microsoft/callback", h.MicrosoftCallback)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/login-check", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	state := store.lastKey[len("auth:sso_state:"):]
+	req2, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/callback?state="+state+"&error=login_required", nil)
+	req2.Header.Set("Accept", "application/json")
+	req2.Header.Set("Sec-Fetch-Mode", "cors")
+	req2.Header.Set("Sec-Fetch-Dest", "empty")
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("app.Test callback: %v", err)
+	}
+	if resp2.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("expected 401, got %d", resp2.StatusCode)
+	}
+}
+
+func TestAuthHandler_MicrosoftCallback_LoginCheckStrict_ActiveSession(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	sso := &serviceMockSSO{claims: service.MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane"}}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{
+		SSO:       sso,
+		Protector: nil,
+		Config:    config.AuthConfig{SSOStateTTL: time.Minute},
+	})
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["user"] = &auth.Role{ID: roleID, Name: "user"}
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: roleID, Timezone: "UTC"}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	_ = repo.CreateIdentity(context.Background(), &auth.UserIdentity{
+		ID:              uuidv7.MustBytes(),
+		UserID:          userID,
+		Provider:        "microsoft",
+		ProviderSubject: "sub",
+		Email:           "user@example.com",
+	})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/login-check", h.MicrosoftLoginCheck)
+	app.Get("/api/v1/auth/microsoft/callback", h.MicrosoftCallback)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/login-check", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	state := store.lastKey[len("auth:sso_state:"):]
+	req2, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/callback?code=code&state="+state, nil)
+	req2.Header.Set("Accept", "application/json")
+	req2.Header.Set("Sec-Fetch-Mode", "cors")
+	req2.Header.Set("Sec-Fetch-Dest", "empty")
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("app.Test callback: %v", err)
+	}
+	if resp2.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp2.StatusCode)
+	}
+	body, _ := io.ReadAll(resp2.Body)
+	if !bytes.Contains(body, []byte(`"type":"auth_microsoft_session"`)) {
+		t.Fatalf("expected auth_microsoft_session response, got body: %s", string(body))
+	}
+}
+
+func TestAuthHandler_MicrosoftReauth_Callback(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["user"] = &auth.Role{ID: roleID, Name: "user"}
+
+	cfg := config.AuthConfig{
+		SSOStateTTL:           time.Minute,
+		SSOSuccessRedirectURL: "http://localhost/cb",
+	}
+	sso := &serviceMockSSO{claims: service.MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane Doe"}}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+
+	identity := &auth.UserIdentity{
+		ID:              uuidv7.MustBytes(),
+		UserID:          uuidv7.MustBytes(),
+		Provider:        "microsoft",
+		ProviderSubject: "sub",
+		Email:           "user@example.com",
+	}
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       identity.UserID,
+		Email:    "user@example.com",
+		RoleID:   roleID,
+		Timezone: "UTC",
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	_ = repo.CreateIdentity(context.Background(), identity)
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", identity.UserID)
+		return c.Next()
+	})
+	app.Get("/api/v1/auth/microsoft/reauth", h.MicrosoftReauth)
+	app.Get("/api/v1/auth/microsoft/callback", h.MicrosoftCallback)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/reauth?purpose=pin_reset_request", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	state := store.lastKey[len("auth:sso_state:"):]
+	req2, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/callback?code=code&state="+state, nil)
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("callback app.Test: %v", err)
+	}
+	if resp2.StatusCode != http.StatusFound {
+		t.Fatalf("expected 302, got %d", resp2.StatusCode)
+	}
+	location, err := url.Parse(resp2.Header.Get("Location"))
+	if err != nil {
+		t.Fatalf("parse location: %v", err)
+	}
+	if location.Query().Get("sso_reauth") != "1" {
+		t.Fatalf("expected sso_reauth marker in redirect")
+	}
+	if location.Query().Get("purpose") != "pin_reset_request" {
+		t.Fatalf("unexpected purpose in redirect: %s", location.Query().Get("purpose"))
+	}
+	if location.Query().Get("reauth_token") == "" {
+		t.Fatalf("expected reauth_token in redirect")
+	}
+}
+
+func TestAuthHandler_MicrosoftLink_Callback(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["user"] = &auth.Role{ID: roleID, Name: "user"}
+
+	cfg := config.AuthConfig{
+		SSOStateTTL:           time.Minute,
+		SSOSuccessRedirectURL: "http://localhost/cb",
+	}
+	sso := &serviceMockSSO{claims: service.MicrosoftClaims{Subject: "sub-link", Email: "user@example.com", Name: "Jane Doe"}}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       userID,
+		Email:    "user@example.com",
+		RoleID:   roleID,
+		Timezone: "UTC",
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", userID)
+		return c.Next()
+	})
+	app.Get("/api/v1/auth/microsoft/link", h.MicrosoftLink)
+	app.Get("/api/v1/auth/microsoft/callback", h.MicrosoftCallback)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/link", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	state := store.lastKey[len("auth:sso_state:"):]
+	req2, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/callback?code=code&state="+state, nil)
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("callback app.Test: %v", err)
+	}
+	if resp2.StatusCode != http.StatusFound {
+		t.Fatalf("expected 302, got %d", resp2.StatusCode)
+	}
+	location, err := url.Parse(resp2.Header.Get("Location"))
+	if err != nil {
+		t.Fatalf("parse location: %v", err)
+	}
+	if location.Query().Get("sso_link") != "1" {
+		t.Fatalf("expected sso_link marker in redirect")
+	}
+	if location.Query().Get("provider") != "microsoft" {
+		t.Fatalf("unexpected provider in redirect: %s", location.Query().Get("provider"))
+	}
+}
+
+type serviceMockSSO struct {
+	claims  service.MicrosoftClaims
+	authURL string
+}
+
+func (m *serviceMockSSO) AuthCodeURL(state string) string {
+	if strings.TrimSpace(m.authURL) != "" {
+		return fmt.Sprintf(m.authURL, state)
+	}
+	return "http://example.com?state=" + state
+}
+func (m *serviceMockSSO) LogoutURL(postLogoutRedirectURL string) string {
+	if strings.TrimSpace(postLogoutRedirectURL) == "" {
+		return "http://example.com/logout"
+	}
+	return "http://example.com/logout?post_logout_redirect_uri=" + url.QueryEscape(postLogoutRedirectURL)
+}
+func (m *serviceMockSSO) ExchangeCode(ctx context.Context, code string) (service.MicrosoftClaims, error) {
+	return m.claims, nil
+}
+
+func TestAuthHandler_Register_InvalidJSON(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/register", h.Register)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/register", bytes.NewReader([]byte("{bad")))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_Register_RoleNotFound(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	cfg := config.AuthConfig{
+		PasswordPepper:  "pepper",
+		HashTime:        1,
+		HashMemoryKB:    64 * 1024,
+		HashThreads:     4,
+		HashKeyLen:      32,
+		DefaultRoleName: "admin",
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/register", h.Register)
+
+	payload := []byte(`{"data":{"type":"auth_register","attributes":{"email":"user@example.com","username":"john.doe","password":"Password123!","first_name":"John","last_name":"Doe"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/register", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_VerifyEmail_MissingToken(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/verify-email", h.VerifyEmail)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/verify-email", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_Login_InvalidJSON(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/login", h.Login)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/login", bytes.NewReader([]byte("{bad")))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_MicrosoftLogin_NotConfigured(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/login", h.MicrosoftLogin)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/login", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_MicrosoftCallback_Invalid(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/callback", h.MicrosoftCallback)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/callback", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_MicrosoftCallback_InvalidState(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	sso := &serviceMockSSO{claims: service.MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane Doe"}}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: sso, Protector: nil, Config: config.AuthConfig{SSOStateTTL: time.Minute}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/callback", h.MicrosoftCallback)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/callback?code=code&state=missing", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_MicrosoftCallback_SSONotLinked(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	sso := &serviceMockSSO{claims: service.MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane Doe"}}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: sso, Protector: nil, Config: config.AuthConfig{SSOStateTTL: time.Minute}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/login", h.MicrosoftLogin)
+	app.Get("/api/v1/auth/microsoft/callback", h.MicrosoftCallback)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/login", nil)
+	_, _ = app.Test(req)
+	state := store.lastKey[len("auth:sso_state:"):]
+
+	req2, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/callback?code=code&state="+state, nil)
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp2.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("expected 401, got %d", resp2.StatusCode)
+	}
+	body, _ := io.ReadAll(resp2.Body)
+	if !bytes.Contains(body, []byte(`"title":"SSO not linked"`)) {
+		t.Fatalf("expected sso not linked response, got %s", string(body))
+	}
+}
+
+func TestAuthHandler_MicrosoftCallback_SSONotLinked_BrowserRedirectsToFrontendError(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	cfg := config.AuthConfig{
+		SSOStateTTL:           time.Minute,
+		SSOSuccessRedirectURL: "http://localhost:3000/en/challenge/msentra",
+	}
+	sso := &serviceMockSSO{claims: service.MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane Doe"}}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: sso, Protector: nil, Config: cfg})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/auth/microsoft/login", h.MicrosoftLogin)
+	app.Get("/api/v1/auth/microsoft/callback", h.MicrosoftCallback)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/login", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test login: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	state := store.lastKey[len("auth:sso_state:"):]
+	req2, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/microsoft/callback?code=code&state="+state, nil)
+	req2.Header.Set("Accept", "text/html")
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("app.Test callback: %v", err)
+	}
+	if resp2.StatusCode != http.StatusFound {
+		t.Fatalf("expected 302, got %d", resp2.StatusCode)
+	}
+	location := resp2.Header.Get("Location")
+	if !strings.Contains(location, "http://localhost:3000/en/challenge/msentra?") {
+		t.Fatalf("expected frontend redirect, got %q", location)
+	}
+	if !strings.Contains(location, "sso=error") || !strings.Contains(location, "reason=sso_not_linked") {
+		t.Fatalf("expected error query params in redirect, got %q", location)
+	}
+}
+
+func TestAuthHandler_SSOLinkAndUnlink(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["user"] = &auth.Role{ID: roleID, Name: "user"}
+
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:       userID,
+		Email:    "user@example.com",
+		RoleID:   roleID,
+		Timezone: "UTC",
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	sso := &serviceMockSSO{claims: service.MicrosoftClaims{Subject: "sub", Email: "user@example.com", Name: "Jane Doe"}}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: sso, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", userID)
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/sso/link", h.SSOLink)
+	app.Delete("/api/v1/auth/sso/unlink", h.SSOUnlink)
+
+	linkPayload := []byte(`{"data":{"type":"auth_sso_link","attributes":{"provider":"microsoft","code":"code"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/sso/link", bytes.NewReader(linkPayload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	unlinkPayload := []byte(`{"data":{"type":"auth_sso_unlink","attributes":{"provider":"microsoft"}}}`)
+	req2, _ := http.NewRequest(http.MethodDelete, "/api/v1/auth/sso/unlink", bytes.NewReader(unlinkPayload))
+	req2.Header.Set("Content-Type", "application/json")
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp2.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp2.StatusCode)
+	}
+}
+
+func TestAuthHandler_TOTPSetup_InvalidUserID(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	userID := uuidv7.MustBytes()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", append([]byte(nil), userID...))
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/totp/setup", h.TOTPSetup)
+
+	payload := []byte(`{"data":{"type":"auth_totp_setup","attributes":{"user_id":"bad","email":"user@example.com"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/setup", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_TOTPSetup_InvalidJSON(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	userID := uuidv7.MustBytes()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", append([]byte(nil), userID...))
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/totp/setup", h.TOTPSetup)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/setup", bytes.NewReader([]byte("{bad")))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_Invite_InvalidJSON(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/invite", h.Invite)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/invite", bytes.NewReader([]byte("{bad")))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_Invite_InvalidRoleID(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/invite", h.Invite)
+
+	payload := []byte(`{"data":{"type":"auth_invite","attributes":{"email":"user@example.com","username":"john.doe","first_name":"John","last_name":"Doe","role_id":"bad-uuid"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/invite", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_Invite_InvalidRoleIDs(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/invite", h.Invite)
+
+	roleID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	payload := []byte(fmt.Sprintf(`{"data":{"type":"auth_invite","attributes":{"email":"user@example.com","username":"john.doe","first_name":"John","last_name":"Doe","role_id":"%s","role_ids":["bad-uuid"]}}}`, roleID))
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/invite", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_Invite_ServiceError(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	roleID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{
+		ID:        uuidv7.MustBytes(),
+		Email:     "user@example.com",
+		FirstName: "Jane",
+		LastName:  "Doe",
+		RoleID:    roleID,
+	}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	roleIDStr, _ := uuidv7.BytesToString(roleID)
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/invite", h.Invite)
+
+	payload := []byte(fmt.Sprintf(`{"data":{"type":"auth_invite","attributes":{"email":"user@example.com","username":"john.doe","first_name":"John","last_name":"Doe","role_id":"%s"}}}`, roleIDStr))
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/invite", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_Invite_Success(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	cfg := config.AuthConfig{
+		SetPasswordURL: "http://localhost/set-password",
+		InviteTTL:      time.Hour,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	roleID := uuidv7.MustBytes()
+	roleIDStr, _ := uuidv7.BytesToString(roleID)
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/invite", h.Invite)
+
+	payload := []byte(fmt.Sprintf(`{"data":{"type":"auth_invite","attributes":{"email":"new-user@example.com","username":"new.user","first_name":"John","last_name":"Doe","mobile_phone":"  +6281234  ","role_id":"%s"}}}`, roleIDStr))
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/invite", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201, got %d", resp.StatusCode)
+	}
+	if store.lastKey == "" {
+		t.Fatalf("expected invite token to be stored")
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !bytes.Contains(body, []byte(`"username":"new.user"`)) {
+		t.Fatalf("expected response to include username, got %s", string(body))
+	}
+}
+
+func TestAuthHandler_Invite_SuccessWithRoleIDs(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	cfg := config.AuthConfig{
+		SetPasswordURL: "http://localhost/set-password",
+		InviteTTL:      time.Hour,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	roleID := uuidv7.MustBytes()
+	extraRoleID := uuidv7.MustBytes()
+	roleIDStr, _ := uuidv7.BytesToString(roleID)
+	extraRoleIDStr, _ := uuidv7.BytesToString(extraRoleID)
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/invite", h.Invite)
+
+	payload := []byte(fmt.Sprintf(`{"data":{"type":"auth_invite","attributes":{"email":"multi-role@example.com","username":"multi.role","first_name":"John","last_name":"Doe","role_id":"%s","role_ids":["%s","%s"]}}}`, roleIDStr, roleIDStr, extraRoleIDStr))
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/invite", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201, got %d", resp.StatusCode)
+	}
+	found := false
+	for _, created := range repo.users {
+		if created.Email != "multi-role@example.com" {
+			continue
+		}
+		found = true
+		if len(created.RoleIDs) != 2 {
+			t.Fatalf("expected 2 role ids stored, got %d", len(created.RoleIDs))
+		}
+	}
+	if !found {
+		t.Fatalf("expected invited user stored in repo")
+	}
+}
+
+func TestAuthHandler_SetPassword_InvalidJSON(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/set-password", h.SetPassword)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/set-password", bytes.NewReader([]byte("{bad")))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_SetPassword_ValidationError(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/set-password", h.SetPassword)
+
+	payload := []byte(`{"data":{"type":"auth_set_password","attributes":{"token":"abc","password":"123"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/set-password", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_SetPassword_InvalidToken(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	cfg := config.AuthConfig{
+		PasswordPepper: "pepper",
+		HashTime:       1,
+		HashMemoryKB:   64 * 1024,
+		HashThreads:    4,
+		HashKeyLen:     32,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/set-password", h.SetPassword)
+
+	payload := []byte(`{"data":{"type":"auth_set_password","attributes":{"token":"missing-token","password":"Password123!"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/set-password", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_SetPassword_Success(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	cfg := config.AuthConfig{
+		PasswordPepper: "pepper",
+		HashTime:       1,
+		HashMemoryKB:   64 * 1024,
+		HashThreads:    4,
+		HashKeyLen:     32,
+		SetPasswordURL: "http://localhost/set-password",
+		InviteTTL:      time.Hour,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	roleID := uuidv7.MustBytes()
+	user, err := svc.InviteUser(context.Background(), "invitee@example.com", "invitee", "John", "Doe", "", roleID)
+	if err != nil {
+		t.Fatalf("invite user: %v", err)
+	}
+	inviteToken := store.lastKey[len("auth:invite:"):]
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/set-password", h.SetPassword)
+
+	payload := []byte(fmt.Sprintf(`{"data":{"type":"auth_set_password","attributes":{"token":"%s","password":"Password123!"}}}`, inviteToken))
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/set-password", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	savedUser, err := repo.GetUserByID(context.Background(), user.ID)
+	if err != nil {
+		t.Fatalf("get user: %v", err)
+	}
+	if savedUser == nil {
+		t.Fatalf("expected user to exist")
+	}
+	if len(savedUser.PasswordHash) == 0 || len(savedUser.SaltValue) == 0 {
+		t.Fatalf("expected password hash and salt to be set")
+	}
+	if savedUser.EmailVerifiedAt == nil {
+		t.Fatalf("expected email verified at to be set")
+	}
+}
+
+func TestAuthHandler_ResendSetPasswordInvite(t *testing.T) {
+	t.Run("validation error invalid user_id", func(t *testing.T) {
+		h := NewAuthHandler(service.NewAuthService(newMemRepo(), nil, newMemTokenStore(), nil, service.AuthServiceDependencies{
+			Config: config.AuthConfig{
+				SetPasswordURL:            "http://localhost/set-password",
+				ForgotPasswordMinDuration: 0,
+			},
+		}))
+		app := fiber.New()
+		app.Post("/api/v1/auth/invite/resend-set-password", h.ResendSetPasswordInvite)
+
+		payload := []byte(`{"data":{"type":"auth_resend_set_password","attributes":{"user_id":"bad"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/invite/resend-set-password", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("generic success and enqueue when user has no password", func(t *testing.T) {
+		repo := newMemRepo()
+		tokens := newMemTokenStore()
+		cfg := config.AuthConfig{
+			SetPasswordURL:              "http://localhost/set-password",
+			InviteTTL:                   time.Hour,
+			ForgotPasswordMinDuration:   0,
+			ForgotPasswordEmailCooldown: time.Minute,
+		}
+		svc := service.NewAuthService(repo, nil, tokens, nil, service.AuthServiceDependencies{Config: cfg})
+		h := NewAuthHandler(svc)
+
+		userID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{
+			ID:        userID,
+			Email:     "invitee@example.com",
+			FirstName: "Invitee",
+			LastName:  "User",
+			IsActive:  true,
+		}
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/invite/resend-set-password", h.ResendSetPasswordInvite)
+
+		userIDStr, _ := uuidv7.BytesToString(userID)
+		payload := []byte(fmt.Sprintf(`{"data":{"type":"auth_resend_set_password","attributes":{"user_id":"%s"}}}`, userIDStr))
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/invite/resend-set-password", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if tokens.lastKey == "" || !strings.HasPrefix(tokens.lastKey, "auth:invite:resend:cooldown:") {
+			t.Fatalf("expected resend cooldown key, got %q", tokens.lastKey)
+		}
+	})
+}
+
+func TestAuthHandler_TOTPConfirm_InvalidCode(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	cfg := config.AuthConfig{TOTPIssuer: "Wucher"}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	userID := uuidv7.MustBytes()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", append([]byte(nil), userID...))
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/totp/confirm", h.TOTPConfirm)
+	_, _, _, _ = svc.SetupTOTP(context.Background(), userID, "user@example.com")
+	payload := []byte(fmt.Sprintf(`{"data":{"type":"auth_totp_confirm","attributes":{"user_id":"%s","code":"000000"}}}`, func() string { s, _ := uuidv7.BytesToString(userID); return s }()))
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/confirm", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("expected 401, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_TOTPConfirm_InvalidUserID(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	userID := uuidv7.MustBytes()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", append([]byte(nil), userID...))
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/totp/confirm", h.TOTPConfirm)
+
+	payload := []byte(`{"data":{"type":"auth_totp_confirm","attributes":{"user_id":"bad","code":"123456"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/confirm", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_TOTPConfirm_InvalidJSON(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	userID := uuidv7.MustBytes()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", append([]byte(nil), userID...))
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/totp/confirm", h.TOTPConfirm)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/confirm", bytes.NewReader([]byte("{bad")))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_TOTPVerify_InvalidChallenge(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/totp/verify", h.TOTPVerify)
+
+	payload := []byte(`{"data":{"type":"auth_totp_verify","attributes":{"challenge_token":"bad","code":"123456"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/verify", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("expected 401, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !strings.Contains(string(body), `"code":"TOKEN_INVALID"`) {
+		t.Fatalf("expected TOKEN_INVALID code, got body=%s", string(body))
+	}
+}
+
+func TestAuthHandler_TOTPVerify_InvalidJSON(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/totp/verify", h.TOTPVerify)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/verify", bytes.NewReader([]byte("{bad")))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_TOTPVerify_TokenIssueError(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	cfg := config.AuthConfig{
+		TOTPIssuer:       "Wucher",
+		TOTPChallengeTTL: time.Minute,
+		// No JWT secrets to force token issue error
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+
+	// prepare user + totp
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "u@e.com", RoleID: uuidv7.MustBytes()}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+	secret, _, _, _ := svc.SetupTOTP(context.Background(), userID, "u@e.com")
+	code, _ := totp.GenerateCode(secret, time.Now().UTC())
+	_, _ = svc.ConfirmTOTP(context.Background(), userID, code)
+	challenge, _ := svc.CreateTOTPChallenge(context.Background(), userID)
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/totp/verify", h.TOTPVerify)
+
+	payload := []byte(fmt.Sprintf(`{"data":{"type":"auth_totp_verify","attributes":{"challenge_token":"%s","code":"%s"}}}`, challenge, code))
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/verify", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_TOTPDisable_InvalidUserID(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	userID := uuidv7.MustBytes()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", append([]byte(nil), userID...))
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/totp/disable", h.TOTPDisable)
+
+	payload := []byte(`{"data":{"type":"auth_totp_disable","attributes":{"user_id":"bad"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/disable", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_TOTPDisable_InvalidJSON(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	userID := uuidv7.MustBytes()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", append([]byte(nil), userID...))
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/totp/disable", h.TOTPDisable)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/disable", bytes.NewReader([]byte("{bad")))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_ParseSameSite_All(t *testing.T) {
+	if parseSameSite("Strict") != "Strict" {
+		t.Fatalf("expected strict")
+	}
+	if parseSameSite("None") != "None" {
+		t.Fatalf("expected none")
+	}
+	if parseSameSite("Lax") != "Lax" {
+		t.Fatalf("expected lax")
+	}
+}
+
+func TestAuthHandler_TOTPVerify_SetsCookies(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+		TOTPChallengeTTL: time.Minute,
+		TOTPIssuer:       "Wucher",
+		DefaultRoleName:  "admin",
+	}
+
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+	user, _ := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", roleID)
+	if err := repo.MarkEmailVerified(context.Background(), user.ID); err != nil {
+		t.Fatalf("mark email verified: %v", err)
+	}
+
+	secret, _, _, _ := svc.SetupTOTP(context.Background(), user.ID, user.Email)
+	code, _ := totp.GenerateCode(secret, time.Now().UTC())
+	_, _ = svc.ConfirmTOTP(context.Background(), user.ID, code)
+
+	challenge, _ := svc.CreateTOTPChallenge(context.Background(), user.ID)
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/totp/verify", h.TOTPVerify)
+
+	payload := []byte(fmt.Sprintf(`{"data":{"type":"auth_totp_verify","attributes":{"challenge_token":"%s","code":"%s"}}}`, challenge, code))
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/verify", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_TOTPVerify_WrongThenCorrectSameChallenge(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	roleID := uuidv7.MustBytes()
+	repo.rolesByName["admin"] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.rolesByID[string(roleID)] = repo.rolesByName["admin"]
+
+	cfg := config.AuthConfig{
+		PasswordPepper:   "pepper",
+		HashTime:         1,
+		HashMemoryKB:     64 * 1024,
+		HashThreads:      4,
+		HashKeyLen:       32,
+		JWTAccessSecret:  "access",
+		JWTRefreshSecret: "refresh",
+		JWTAccessTTL:     time.Minute,
+		JWTRefreshTTL:    time.Hour,
+		TOTPChallengeTTL: time.Minute,
+		TOTPIssuer:       "Wucher",
+		DefaultRoleName:  "admin",
+	}
+
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: cfg})
+	user, _ := svc.RegisterWithEmail(context.Background(), "user2@example.com", "john.doe.2", "John", "Doe", "", "Password123!", roleID)
+	if err := repo.MarkEmailVerified(context.Background(), user.ID); err != nil {
+		t.Fatalf("mark email verified: %v", err)
+	}
+
+	secret, _, _, _ := svc.SetupTOTP(context.Background(), user.ID, user.Email)
+	code, _ := totp.GenerateCode(secret, time.Now().UTC())
+	_, _ = svc.ConfirmTOTP(context.Background(), user.ID, code)
+	challenge, _ := svc.CreateTOTPChallenge(context.Background(), user.ID)
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/totp/verify", h.TOTPVerify)
+
+	wrongPayload := []byte(fmt.Sprintf(`{"data":{"type":"auth_totp_verify","attributes":{"challenge_token":"%s","code":"000000"}}}`, challenge))
+	wrongReq, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/verify", bytes.NewReader(wrongPayload))
+	wrongReq.Header.Set("Content-Type", "application/json")
+	wrongResp, err := app.Test(wrongReq)
+	if err != nil {
+		t.Fatalf("app.Test wrong attempt: %v", err)
+	}
+	if wrongResp.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("expected 401 for wrong code, got %d", wrongResp.StatusCode)
+	}
+	wrongBody, _ := io.ReadAll(wrongResp.Body)
+	if !strings.Contains(string(wrongBody), `"code":"USER_UNAUTHORIZED"`) {
+		t.Fatalf("expected USER_UNAUTHORIZED code on wrong totp, got body=%s", string(wrongBody))
+	}
+
+	okPayload := []byte(fmt.Sprintf(`{"data":{"type":"auth_totp_verify","attributes":{"challenge_token":"%s","code":"%s"}}}`, challenge, code))
+	okReq, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/totp/verify", bytes.NewReader(okPayload))
+	okReq.Header.Set("Content-Type", "application/json")
+	okResp, err := app.Test(okReq)
+	if err != nil {
+		t.Fatalf("app.Test correct attempt: %v", err)
+	}
+	if okResp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 after retry with same challenge, got %d", okResp.StatusCode)
+	}
+}
+
+func TestAuthHandler_SetupSecurityPIN(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{}})
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", userID)
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/pin/setup", h.SetupSecurityPIN)
+
+	payload := []byte(`{"data":{"type":"auth_pin_setup","attributes":{"pin":"123456","confirm_pin":"123456"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/setup", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if len(repo.users[string(userID)].SecurityPINHash) == 0 {
+		t.Fatalf("expected encrypted PIN to be stored")
+	}
+}
+
+func TestAuthHandler_VerifySecurityPIN(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{
+		SecurityPINActionTokenTTL: time.Minute,
+	}})
+	if err := svc.SetSecurityPIN(context.Background(), userID, "123456"); err != nil {
+		t.Fatalf("set pin: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", userID)
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/pin/verify", h.VerifySecurityPIN)
+
+	payload := []byte(`{"data":{"type":"auth_pin_verify","attributes":{"pin":"123456","action":"a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/verify", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !bytes.Contains(body, []byte("action_token")) {
+		t.Fatalf("expected action_token in response body, got %s", string(body))
+	}
+}
+
+func TestAuthHandler_ChangeSecurityPIN_InvalidCurrent(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	userID := uuidv7.MustBytes()
+	if err := repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()}); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{}})
+	if err := svc.SetSecurityPIN(context.Background(), userID, "123456"); err != nil {
+		t.Fatalf("set pin: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", userID)
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/pin/change", h.ChangeSecurityPIN)
+
+	payload := []byte(`{"data":{"type":"auth_pin_change","attributes":{"current_pin":"000000","new_pin":"654321","confirm_pin":"654321"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/change", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("expected 401, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_ForgotSecurityPIN_GenericResponse(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	cfg := config.AuthConfig{
+		SecurityPINResetURL:       "https://app.example.com/reset-pin",
+		SecurityPINResetTTL:       20 * time.Minute,
+		ForgotSecurityPINCooldown: time.Minute,
+	}
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: cfg})
+
+	existing := &auth.User{ID: uuidv7.MustBytes(), Email: "exists@example.com", RoleID: uuidv7.MustBytes()}
+	if err := repo.CreateUser(context.Background(), existing); err != nil {
+		t.Fatalf("create user: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/pin/forgot", h.ForgotSecurityPIN)
+
+	existingPayload := []byte(`{"data":{"type":"auth_forgot_pin","attributes":{"email":"exists@example.com"}}}`)
+	missingPayload := []byte(`{"data":{"type":"auth_forgot_pin","attributes":{"email":"missing@example.com"}}}`)
+
+	req1, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/forgot", bytes.NewReader(existingPayload))
+	req1.Header.Set("Content-Type", "application/json")
+	resp1, err := app.Test(req1)
+	if err != nil {
+		t.Fatalf("first app.Test: %v", err)
+	}
+	req2, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/forgot", bytes.NewReader(missingPayload))
+	req2.Header.Set("Content-Type", "application/json")
+	resp2, err := app.Test(req2)
+	if err != nil {
+		t.Fatalf("second app.Test: %v", err)
+	}
+	if resp1.StatusCode != http.StatusOK || resp2.StatusCode != http.StatusOK {
+		t.Fatalf("expected both responses 200, got %d and %d", resp1.StatusCode, resp2.StatusCode)
+	}
+	body1, _ := io.ReadAll(resp1.Body)
+	body2, _ := io.ReadAll(resp2.Body)
+	if !bytes.Equal(body1, body2) {
+		t.Fatalf("forgot-pin responses should match, got existing=%s missing=%s", string(body1), string(body2))
+	}
+}
+
+func TestAuthHandler_RequestSecurityPINReset(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+		SecurityPINResetURL:       "https://app.example.com/reset-pin",
+		SecurityPINResetTTL:       20 * time.Minute,
+		ForgotSecurityPINCooldown: time.Minute,
+		SecurityPINLockDuration:   0,
+		PasswordPepper:            "pepper",
+		HashTime:                  1,
+		HashMemoryKB:              64 * 1024,
+		HashThreads:               4,
+		HashKeyLen:                32,
+	}})
+	h := NewAuthHandler(svc)
+
+	user, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", uuidv7.MustBytes())
+	if err != nil {
+		t.Fatalf("register user: %v", err)
+	}
+	userID := user.ID
+	payload := []byte(`{"data":{"type":"auth_pin_request_reset","attributes":{"password":"Password123!"}}}`)
+
+	t.Run("missing auth context", func(t *testing.T) {
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/request-reset", h.RequestSecurityPINReset)
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/request-reset", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not blocked", func(t *testing.T) {
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/request-reset", h.RequestSecurityPINReset)
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/request-reset", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409, got %d", resp.StatusCode)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if !bytes.Contains(body, []byte(`"title":"PIN not blocked"`)) {
+			t.Fatalf("expected PIN not blocked title, got %s", string(body))
+		}
+		if !bytes.Contains(body, []byte(`"detail":"security PIN is not blocked"`)) {
+			t.Fatalf("expected security PIN is not blocked detail, got %s", string(body))
+		}
+	})
+
+	t.Run("blocked and reset requested", func(t *testing.T) {
+		userIDStr, _ := uuidv7.BytesToString(userID)
+		store.store["auth:security_pin:lock:"+userIDStr] = []byte("1")
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/request-reset", h.RequestSecurityPINReset)
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/request-reset", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid password", func(t *testing.T) {
+		userIDStr, _ := uuidv7.BytesToString(userID)
+		store.store["auth:security_pin:lock:"+userIDStr] = []byte("1")
+		delete(store.store, "auth:security_pin:cooldown:user@example.com")
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/request-reset", h.RequestSecurityPINReset)
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/request-reset", bytes.NewReader([]byte(`{"data":{"type":"auth_pin_request_reset","attributes":{"password":"wrong-password"}}}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_ResetSecurityPIN(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{
+		PasswordPepper: "pepper",
+		HashTime:       1,
+		HashMemoryKB:   64 * 1024,
+		HashThreads:    4,
+		HashKeyLen:     32,
+	}})
+	user, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", uuidv7.MustBytes())
+	if err != nil {
+		t.Fatalf("register user: %v", err)
+	}
+
+	rawToken := "pin-reset-token"
+	tokenHash := sha256.Sum256([]byte(rawToken))
+	repo.securityPINResetTokens[string(tokenHash[:])] = &auth.SecurityPINResetToken{
+		ID:        uuidv7.MustBytes(),
+		UserID:    user.ID,
+		TokenHash: tokenHash[:],
+		ExpiresAt: time.Now().Add(10 * time.Minute),
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/auth/pin/reset", h.ResetSecurityPIN)
+
+	payload := []byte(`{"data":{"type":"auth_reset_pin","attributes":{"token":"pin-reset-token","password":"Password123!","new_pin":"654321","confirm_pin":"654321"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/reset", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	enc := repo.users[string(user.ID)].SecurityPINHash
+	if len(enc) == 0 {
+		t.Fatalf("expected hashed pin record on user")
+	}
+	if _, err := svc.VerifySecurityPINForAction(context.Background(), user.ID, "654321", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"); err != nil {
+		t.Fatalf("expected updated pin to verify, got %v", err)
+	}
+}
+
+func TestAuthHandler_SetupSecurityPIN_Branches(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	h := NewAuthHandler(svc)
+
+	t.Run("missing auth context", func(t *testing.T) {
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/setup", h.SetupSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_pin_setup","attributes":{"pin":"123456","confirm_pin":"123456"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("confirm mismatch", func(t *testing.T) {
+		userID := uuidv7.MustBytes()
+		_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/setup", h.SetupSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_pin_setup","attributes":{"pin":"123456","confirm_pin":"123455"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_VerifySecurityPIN_Branches(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	userID := uuidv7.MustBytes()
+	_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{
+		SecurityPINMaxAttempts:    1,
+		SecurityPINLockDuration:   time.Minute,
+		SecurityPINActionTokenTTL: time.Minute,
+	}})
+	h := NewAuthHandler(svc)
+
+	t.Run("missing auth context", func(t *testing.T) {
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/verify", h.VerifySecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_pin_verify","attributes":{"pin":"123456","action":"a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/verify", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("pin not set", func(t *testing.T) {
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/verify", h.VerifySecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_pin_verify","attributes":{"pin":"123456","action":"a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/verify", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("locked response", func(t *testing.T) {
+		if err := svc.SetSecurityPIN(context.Background(), userID, "123456"); err != nil {
+			t.Fatalf("set pin: %v", err)
+		}
+		_, _ = svc.VerifySecurityPINForAction(context.Background(), userID, "000000", "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74")
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/verify", h.VerifySecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_pin_verify","attributes":{"pin":"123456","action":"a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/verify", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusLocked {
+			t.Fatalf("expected 423, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_Sessions_Branches(t *testing.T) {
+	t.Run("missing auth context", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			JWTAccessSecret:  "access",
+			JWTRefreshSecret: "refresh",
+			JWTAccessTTL:     time.Minute,
+			JWTRefreshTTL:    time.Hour,
+		}})
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Get("/api/v1/auth/sessions", h.Sessions)
+
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/sessions", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service error on invalid user id", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			JWTAccessSecret:  "access",
+			JWTRefreshSecret: "refresh",
+			JWTAccessTTL:     time.Minute,
+			JWTRefreshTTL:    time.Hour,
+		}})
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", []byte("short"))
+			return c.Next()
+		})
+		app.Get("/api/v1/auth/sessions", h.Sessions)
+
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/sessions", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success returns only current active session", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			JWTAccessSecret:  "access",
+			JWTRefreshSecret: "refresh",
+			JWTAccessTTL:     time.Minute,
+			JWTRefreshTTL:    time.Hour,
+		}})
+		user := &auth.User{ID: uuidv7.MustBytes(), Email: "user@example.com", RoleID: uuidv7.MustBytes()}
+		if err := repo.CreateUser(context.Background(), user); err != nil {
+			t.Fatalf("create user: %v", err)
+		}
+		first, err := svc.IssueTokensWithClient(context.Background(), user, "Mozilla/5.0 (Macintosh)", "127.0.0.1")
+		if err != nil {
+			t.Fatalf("issue first token: %v", err)
+		}
+		second, err := svc.IssueTokensWithClient(context.Background(), user, "Mozilla/5.0 (Windows)", "127.0.0.2")
+		if err != nil {
+			t.Fatalf("issue second token: %v", err)
+		}
+		if _, err := svc.ParseAccessToken(context.Background(), first.AccessToken); !errors.Is(err, service.ErrInvalidToken) {
+			t.Fatalf("expected first token invalid after second login, got %v", err)
+		}
+
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return c.Next()
+		})
+		app.Get("/api/v1/auth/sessions", h.Sessions)
+
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/auth/sessions", nil)
+		req.AddCookie(&http.Cookie{Name: svc.AccessCookieName(), Value: second.AccessToken})
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+
+		body, err := io.ReadAll(resp.Body)
+		if err != nil {
+			t.Fatalf("read body: %v", err)
+		}
+
+		var payload map[string]any
+		if err := json.Unmarshal(body, &payload); err != nil {
+			t.Fatalf("unmarshal body: %v", err)
+		}
+		data := payload["data"].(map[string]any)
+		attrs := data["attributes"].(map[string]any)
+		sessions := attrs["sessions"].([]any)
+		if len(sessions) != 1 {
+			t.Fatalf("expected only one active session, got %d", len(sessions))
+		}
+		session := sessions[0].(map[string]any)
+		if session["id"] != second.SessionID || session["active_now"] != true {
+			t.Fatalf("expected current session flagged active_now, got %#v", session)
+		}
+	})
+}
+
+func TestAuthHandler_DeleteSession_Branches(t *testing.T) {
+	newFixture := func(t *testing.T) (*memRepo, *service.AuthService, *auth.User, service.TokenPair, service.TokenPair) {
+		t.Helper()
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			JWTAccessSecret:  "access",
+			JWTRefreshSecret: "refresh",
+			JWTAccessTTL:     time.Minute,
+			JWTRefreshTTL:    time.Hour,
+		}})
+		user := &auth.User{ID: uuidv7.MustBytes(), Email: "user@example.com", RoleID: uuidv7.MustBytes()}
+		if err := repo.CreateUser(context.Background(), user); err != nil {
+			t.Fatalf("create user: %v", err)
+		}
+		first, err := svc.IssueTokensWithClient(context.Background(), user, "Mozilla/5.0 (Macintosh)", "127.0.0.1")
+		if err != nil {
+			t.Fatalf("issue first token: %v", err)
+		}
+		second, err := svc.IssueTokensWithClient(context.Background(), user, "Mozilla/5.0 (Windows)", "127.0.0.2")
+		if err != nil {
+			t.Fatalf("issue second token: %v", err)
+		}
+		return repo, svc, user, first, second
+	}
+
+	t.Run("missing auth context", func(t *testing.T) {
+		_, svc, _, _, _ := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Delete("/api/v1/auth/sessions/:session_id", h.DeleteSession)
+
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/auth/sessions/"+mustUUIDStringForcesPresent(t, uuidv7.MustBytes()), nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid session id", func(t *testing.T) {
+		_, svc, user, _, _ := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return c.Next()
+		})
+		app.Delete("/api/v1/auth/sessions/:session_id", h.DeleteSession)
+
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/auth/sessions/not-uuid", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("session not found", func(t *testing.T) {
+		_, svc, user, _, _ := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return c.Next()
+		})
+		app.Delete("/api/v1/auth/sessions/:session_id", h.DeleteSession)
+
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/auth/sessions/"+mustUUIDStringForcesPresent(t, uuidv7.MustBytes()), nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("session belongs to another user", func(t *testing.T) {
+		_, svc, _, _, second := newFixture(t)
+		otherUser := &auth.User{ID: uuidv7.MustBytes(), Email: "other@example.com", RoleID: uuidv7.MustBytes()}
+		repo := newMemRepo()
+		_ = repo
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", otherUser.ID)
+			return c.Next()
+		})
+		app.Delete("/api/v1/auth/sessions/:session_id", h.DeleteSession)
+
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/auth/sessions/"+second.SessionID, nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success deletes one session", func(t *testing.T) {
+		_, svc, user, first, second := newFixture(t)
+		h := NewAuthHandler(svc)
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", user.ID)
+			return c.Next()
+		})
+		app.Delete("/api/v1/auth/sessions/:session_id", h.DeleteSession)
+
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/auth/sessions/"+second.SessionID, nil)
+		req.AddCookie(&http.Cookie{Name: svc.AccessCookieName(), Value: first.AccessToken})
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if _, err := svc.RefreshTokens(context.Background(), second.RefreshToken); !errors.Is(err, service.ErrInvalidToken) {
+			t.Fatalf("expected revoked session refresh token invalid, got %v", err)
+		}
+	})
+}
+
+func TestAuthHandler_ChangeSecurityPIN_Branches(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	h := NewAuthHandler(svc)
+
+	t.Run("missing auth context", func(t *testing.T) {
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/change", h.ChangeSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_pin_change","attributes":{"current_pin":"123456","new_pin":"654321","confirm_pin":"654321"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/change", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("confirm mismatch", func(t *testing.T) {
+		userID := uuidv7.MustBytes()
+		_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/change", h.ChangeSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_pin_change","attributes":{"current_pin":"123456","new_pin":"654321","confirm_pin":"654322"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/change", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_ForgotAndResetSecurityPIN_Branches(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	h := NewAuthHandler(svc)
+
+	t.Run("forgot invalid json", func(t *testing.T) {
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/forgot", h.ForgotSecurityPIN)
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/forgot", bytes.NewReader([]byte("{bad")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("reset invalid json", func(t *testing.T) {
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/reset", h.ResetSecurityPIN)
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/reset", bytes.NewReader([]byte("{bad")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("reset invalid link", func(t *testing.T) {
+		key := make([]byte, 32)
+		for i := range key {
+			key[i] = byte(i + 1)
+		}
+		protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+		svc2 := service.NewAuthService(newMemRepo(), newMemRepo(), newMemTokenStore(), nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{}})
+		h2 := NewAuthHandler(svc2)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/reset", h2.ResetSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_reset_pin","attributes":{"token":"missing","password":"Password123!","new_pin":"123456","confirm_pin":"123456"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/reset", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("reset invalid password", func(t *testing.T) {
+		key := make([]byte, 32)
+		for i := range key {
+			key[i] = byte(i + 1)
+		}
+		protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+		repo2 := newMemRepo()
+		svc2 := service.NewAuthService(repo2, repo2, newMemTokenStore(), nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{
+			PasswordPepper: "pepper",
+			HashTime:       1,
+			HashMemoryKB:   64 * 1024,
+			HashThreads:    4,
+			HashKeyLen:     32,
+		}})
+		user, err := svc2.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("register user: %v", err)
+		}
+		hash := sha256.Sum256([]byte("token-invalid-password"))
+		repo2.securityPINResetTokens[string(hash[:])] = &auth.SecurityPINResetToken{
+			ID:        uuidv7.MustBytes(),
+			UserID:    user.ID,
+			TokenHash: hash[:],
+			ExpiresAt: time.Now().Add(time.Minute),
+		}
+		h2 := NewAuthHandler(svc2)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/reset", h2.ResetSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_reset_pin","attributes":{"token":"token-invalid-password","password":"WrongPassword","new_pin":"123456","confirm_pin":"123456"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/reset", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("reset service error returns 500", func(t *testing.T) {
+		key := make([]byte, 32)
+		for i := range key {
+			key[i] = byte(i + 1)
+		}
+		protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+		repo2 := newMemRepo()
+		svc2 := service.NewAuthService(repo2, repo2, newMemTokenStore(), nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{
+			PasswordPepper: "pepper",
+			HashTime:       1,
+			HashMemoryKB:   64 * 1024,
+			HashThreads:    4,
+			HashKeyLen:     32,
+		}})
+		user, err := svc2.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("register user: %v", err)
+		}
+		repo2.consumePINResetErr = errors.New("db fail")
+		hash := sha256.Sum256([]byte("token-err"))
+		repo2.securityPINResetTokens[string(hash[:])] = &auth.SecurityPINResetToken{
+			ID:        uuidv7.MustBytes(),
+			UserID:    user.ID,
+			TokenHash: hash[:],
+			ExpiresAt: time.Now().Add(time.Minute),
+		}
+		h2 := NewAuthHandler(svc2)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/reset", h2.ResetSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_reset_pin","attributes":{"token":"token-err","password":"Password123!","new_pin":"123456","confirm_pin":"123456"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/reset", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusInternalServerError {
+			t.Fatalf("expected 500, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_SetupSecurityPIN_AlreadySet(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	userID := uuidv7.MustBytes()
+	_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{}})
+	if err := svc.SetSecurityPIN(context.Background(), userID, "123456"); err != nil {
+		t.Fatalf("set initial pin: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", userID)
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/pin/setup", h.SetupSecurityPIN)
+
+	payload := []byte(`{"data":{"type":"auth_pin_setup","attributes":{"pin":"123456","confirm_pin":"123456"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/setup", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusConflict {
+		t.Fatalf("expected 409, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_VerifySecurityPIN_InvalidPIN(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	userID := uuidv7.MustBytes()
+	_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{
+		SecurityPINMaxAttempts:    5,
+		SecurityPINLockDuration:   time.Minute,
+		SecurityPINActionTokenTTL: time.Minute,
+	}})
+	if err := svc.SetSecurityPIN(context.Background(), userID, "123456"); err != nil {
+		t.Fatalf("set pin: %v", err)
+	}
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", userID)
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/pin/verify", h.VerifySecurityPIN)
+
+	payload := []byte(`{"data":{"type":"auth_pin_verify","attributes":{"pin":"000000","action":"a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/verify", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("expected 401, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_ChangeSecurityPIN_NotSet(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	userID := uuidv7.MustBytes()
+	_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{}})
+
+	h := NewAuthHandler(svc)
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", userID)
+		return c.Next()
+	})
+	app.Post("/api/v1/auth/pin/change", h.ChangeSecurityPIN)
+
+	payload := []byte(`{"data":{"type":"auth_pin_change","attributes":{"current_pin":"123456","new_pin":"654321","confirm_pin":"654321"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/change", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusConflict {
+		t.Fatalf("expected 409, got %d", resp.StatusCode)
+	}
+}
+
+func TestAuthHandler_ResetSecurityPIN_ValidationBranches(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{}})
+	h := NewAuthHandler(svc)
+
+	t.Run("confirm mismatch", func(t *testing.T) {
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/reset", h.ResetSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_reset_pin","attributes":{"token":"x","password":"Password123!","new_pin":"123456","confirm_pin":"123455"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/reset", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("missing token for password method", func(t *testing.T) {
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/reset", h.ResetSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_reset_pin","attributes":{"password":"Password123!","new_pin":"123456","confirm_pin":"123456"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/reset", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("missing password", func(t *testing.T) {
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/reset", h.ResetSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_reset_pin","attributes":{"token":"x","password":"","new_pin":"123456","confirm_pin":"123456"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/reset", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid pin format", func(t *testing.T) {
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/reset", h.ResetSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_reset_pin","attributes":{"token":"x","password":"Password123!","new_pin":"12345a","confirm_pin":"12345a"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/reset", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("microsoft does not require token", func(t *testing.T) {
+		userID := uuidv7.MustBytes()
+		userIDStr, err := uuidv7.BytesToString(userID)
+		if err != nil {
+			t.Fatalf("user id to string: %v", err)
+		}
+		token := "reauth-direct"
+		store.store["auth:microsoft_reauth:"+token] = []byte(userIDStr + "|pin_reset_request")
+		_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/pin/reset", h.ResetSecurityPIN)
+
+		payload := []byte(fmt.Sprintf(`{"data":{"type":"auth_reset_pin","attributes":{"method":"microsoft","reauth_token":"%s","new_pin":"123456","confirm_pin":"123456"}}}`, token))
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/reset", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_SetupSecurityPIN_ErrorBranches(t *testing.T) {
+	repo := newMemRepo()
+	store := newMemTokenStore()
+	svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+	h := NewAuthHandler(svc)
+
+	t.Run("invalid json", func(t *testing.T) {
+		app := fiber.New()
+		userID := uuidv7.MustBytes()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/setup", h.SetupSecurityPIN)
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/setup", bytes.NewReader([]byte("{bad")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service default branch", func(t *testing.T) {
+		userID := uuidv7.MustBytes()
+		_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/setup", h.SetupSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_pin_setup","attributes":{"pin":"123456","confirm_pin":"123456"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/setup", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_ChangeSecurityPIN_SuccessAndBranches(t *testing.T) {
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i + 1)
+	}
+	protector, _ := service.NewAESGCMProtectorFromBase64(base64.StdEncoding.EncodeToString(key))
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{}})
+		h := NewAuthHandler(svc)
+
+		userID := uuidv7.MustBytes()
+		_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+		_ = svc.SetSecurityPIN(context.Background(), userID, "123456")
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/change", h.ChangeSecurityPIN)
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/change", bytes.NewReader([]byte("{bad")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("locked branch", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{
+			SecurityPINMaxAttempts:  1,
+			SecurityPINLockDuration: time.Minute,
+		}})
+		h := NewAuthHandler(svc)
+
+		userID := uuidv7.MustBytes()
+		_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+		_ = svc.SetSecurityPIN(context.Background(), userID, "123456")
+		_, _ = svc.VerifySecurityPINForAction(context.Background(), userID, "000000", "428fdf48-3f99-46ea-bc47-8fb2e312be08")
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/change", h.ChangeSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_pin_change","attributes":{"current_pin":"123456","new_pin":"654321","confirm_pin":"654321"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/change", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusLocked {
+			t.Fatalf("expected 423, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: protector, Config: config.AuthConfig{}})
+		h := NewAuthHandler(svc)
+
+		userID := uuidv7.MustBytes()
+		_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+		_ = svc.SetSecurityPIN(context.Background(), userID, "123456")
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/change", h.ChangeSecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_pin_change","attributes":{"current_pin":"123456","new_pin":"654321","confirm_pin":"654321"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/change", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_VerifySecurityPIN_ErrorBranches(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		h := NewAuthHandler(svc)
+		userID := uuidv7.MustBytes()
+		_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/verify", h.VerifySecurityPIN)
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/verify", bytes.NewReader([]byte("{bad")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		h := NewAuthHandler(svc)
+		userID := uuidv7.MustBytes()
+		_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/verify", h.VerifySecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_pin_verify","attributes":{"pin":"","action":""}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/verify", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service default branch returns 400", func(t *testing.T) {
+		repo := newMemRepo()
+		userID := uuidv7.MustBytes()
+		_ = repo.CreateUser(context.Background(), &auth.User{ID: userID, Email: "user@example.com", RoleID: uuidv7.MustBytes()})
+		svc := service.NewAuthService(repo, repo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			SecurityPINActionTokenTTL: time.Minute,
+		}})
+		if err := svc.SetSecurityPIN(context.Background(), userID, "123456"); err != nil {
+			t.Fatalf("set pin: %v", err)
+		}
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/verify", h.VerifySecurityPIN)
+
+		payload := []byte(`{"data":{"type":"auth_pin_verify","attributes":{"pin":"123456","action":"a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/verify", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_RequestSecurityPINReset_ErrorBranches(t *testing.T) {
+	t.Run("rate limited after successful request", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			SecurityPINResetURL:       "https://app.example.com/reset-pin",
+			SecurityPINResetTTL:       20 * time.Minute,
+			ForgotSecurityPINCooldown: time.Minute,
+			PasswordPepper:            "pepper",
+			HashTime:                  1,
+			HashMemoryKB:              64 * 1024,
+			HashThreads:               4,
+			HashKeyLen:                32,
+		}})
+		h := NewAuthHandler(svc)
+
+		user, err := svc.RegisterWithEmail(context.Background(), "user@example.com", "john.doe", "John", "Doe", "", "Password123!", uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("register user: %v", err)
+		}
+		userID := user.ID
+		userIDStr, _ := uuidv7.BytesToString(userID)
+		store.store["auth:security_pin:lock:"+userIDStr] = []byte("1")
+		payload := []byte(`{"data":{"type":"auth_pin_request_reset","attributes":{"password":"Password123!"}}}`)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/request-reset", h.RequestSecurityPINReset)
+
+		req1, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/request-reset", bytes.NewReader(payload))
+		req1.Header.Set("Content-Type", "application/json")
+		resp1, err := app.Test(req1)
+		if err != nil {
+			t.Fatalf("first app.Test: %v", err)
+		}
+		if resp1.StatusCode != http.StatusOK {
+			t.Fatalf("expected first request 200, got %d", resp1.StatusCode)
+		}
+
+		req2, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/request-reset", bytes.NewReader(payload))
+		req2.Header.Set("Content-Type", "application/json")
+		resp2, err := app.Test(req2)
+		if err != nil {
+			t.Fatalf("second app.Test: %v", err)
+		}
+		if resp2.StatusCode != http.StatusTooManyRequests {
+			t.Fatalf("expected second request 429, got %d", resp2.StatusCode)
+		}
+	})
+
+	t.Run("default branch returns 500", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", []byte("bad"))
+			return c.Next()
+		})
+		app.Post("/api/v1/auth/pin/request-reset", h.RequestSecurityPINReset)
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/pin/request-reset", bytes.NewReader([]byte(`{"data":{"type":"auth_pin_request_reset","attributes":{"password":"Password123!"}}}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusInternalServerError {
+			t.Fatalf("expected 500, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestAuthHandler_WebAuthnRegisterBegin(t *testing.T) {
+	validPayload := []byte(`{"data":{"type":"auth_webauthn_register_begin"}}`)
+
+	t.Run("missing auth context", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/register/begin", h.WebAuthnRegisterBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/begin", bytes.NewReader(validPayload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", userID); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/begin", h.WebAuthnRegisterBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/begin", bytes.NewReader([]byte(`{"data":`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", userID); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/begin", h.WebAuthnRegisterBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/begin", bytes.NewReader([]byte(`{"data":{"type":"wrong"}}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not configured", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", userID); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/begin", h.WebAuthnRegisterBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/begin", bytes.NewReader(validPayload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service default branch", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", []byte("short")); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/begin", h.WebAuthnRegisterBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/begin", bytes.NewReader(validPayload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", userID); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/begin", h.WebAuthnRegisterBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/begin", bytes.NewReader(validPayload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if !bytes.Contains(body, []byte(`"challenge_token"`)) || !bytes.Contains(body, []byte(`"public_key"`)) {
+			t.Fatalf("unexpected response body: %s", string(body))
+		}
+	})
+}
+
+func TestAuthHandler_WebAuthnRegisterFinish(t *testing.T) {
+	validPayload := func(token string, credential []byte, name string) []byte {
+		return []byte(fmt.Sprintf(`{"data":{"type":"auth_webauthn_register_finish","attributes":{"challenge_token":"%s","credential":%s,"name":"%s"}}}`, token, string(credential), name))
+	}
+
+	t.Run("missing auth context", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/register/finish", h.WebAuthnRegisterFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/finish", bytes.NewReader(validPayload("tok", []byte(`{}`), "")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", userID); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/finish", h.WebAuthnRegisterFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/finish", bytes.NewReader([]byte(`{"data":`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", userID); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/finish", h.WebAuthnRegisterFinish)
+		payload := []byte(`{"data":{"type":"auth_webauthn_register_finish","attributes":{"challenge_token":"","credential":null}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/finish", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not configured", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", userID); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/finish", h.WebAuthnRegisterFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/finish", bytes.NewReader(validPayload("tok", []byte(`{}`), "")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid challenge", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", userID); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/finish", h.WebAuthnRegisterFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/finish", bytes.NewReader(validPayload("missing", []byte(testWebAuthnCreationResponseJSON), "")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("payload invalid", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+		putWebAuthnChallenge(t, store, "tok-payload", "registration", userID, webauthnlib.SessionData{
+			Challenge:      testWebAuthnRegistrationChallenge,
+			RelyingPartyID: "webauthn.io",
+			UserID:         userID,
+			Expires:        time.Now().UTC().Add(time.Minute),
+			CredParams:     webauthnlib.CredentialParametersDefault(),
+		})
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", userID); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/finish", h.WebAuthnRegisterFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/finish", bytes.NewReader(validPayload("tok-payload", []byte(`{}`), "")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("verification failed", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+		putWebAuthnChallenge(t, store, "tok-verify", "registration", userID, webauthnlib.SessionData{
+			Challenge:      "invalid-challenge",
+			RelyingPartyID: "webauthn.io",
+			UserID:         userID,
+			Expires:        time.Now().UTC().Add(time.Minute),
+			CredParams:     webauthnlib.CredentialParametersDefault(),
+		})
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", userID); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/finish", h.WebAuthnRegisterFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/finish", bytes.NewReader(validPayload("tok-verify", []byte(testWebAuthnCreationResponseJSON), "")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("credential exists", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+		seedWebAuthnRegistrationExistingCredential(t, repo, userID)
+		putWebAuthnChallenge(t, store, "tok-exists", "registration", userID, webauthnlib.SessionData{
+			Challenge:      testWebAuthnRegistrationChallenge,
+			RelyingPartyID: "webauthn.io",
+			UserID:         userID,
+			Expires:        time.Now().UTC().Add(time.Minute),
+			CredParams:     webauthnlib.CredentialParametersDefault(),
+		})
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", userID); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/finish", h.WebAuthnRegisterFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/finish", bytes.NewReader(validPayload("tok-exists", []byte(testWebAuthnCreationResponseJSON), "")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service default branch", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", []byte("short")); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/finish", h.WebAuthnRegisterFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/finish", bytes.NewReader(validPayload("tok", []byte(testWebAuthnCreationResponseJSON), "")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+		putWebAuthnChallenge(t, store, "tok-success", "registration", userID, webauthnlib.SessionData{
+			Challenge:      testWebAuthnRegistrationChallenge,
+			RelyingPartyID: "webauthn.io",
+			UserID:         userID,
+			Expires:        time.Now().UTC().Add(time.Minute),
+			CredParams:     webauthnlib.CredentialParametersDefault(),
+		})
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", userID); return c.Next() })
+		app.Post("/api/v1/auth/webauthn/register/finish", h.WebAuthnRegisterFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/register/finish", bytes.NewReader(validPayload("tok-success", []byte(testWebAuthnCreationResponseJSON), "Device A")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if !bytes.Contains(body, []byte(`"registered":true`)) {
+			t.Fatalf("unexpected response body: %s", string(body))
+		}
+	})
+}
+
+func TestAuthHandler_WebAuthnLoginBegin(t *testing.T) {
+	validPayload := func(email string) []byte {
+		return []byte(fmt.Sprintf(`{"data":{"type":"auth_webauthn_login_begin","attributes":{"email":"%s"}}}`, email))
+	}
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/begin", h.WebAuthnLoginBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/begin", bytes.NewReader([]byte(`{"data":`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/begin", h.WebAuthnLoginBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/begin", bytes.NewReader([]byte(`{"data":{"type":"auth_webauthn_login_begin","attributes":{"email":"invalid"}}}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid credentials", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/begin", h.WebAuthnLoginBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/begin", bytes.NewReader(validPayload("missing@example.com")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("email not verified", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		seedWebAuthnUser(repo, "user@example.com", false)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/begin", h.WebAuthnLoginBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/begin", bytes.NewReader(validPayload("user@example.com")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("credential unavailable", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		seedWebAuthnUser(repo, "user@example.com", true)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/begin", h.WebAuthnLoginBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/begin", bytes.NewReader(validPayload("user@example.com")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not configured", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		h := NewAuthHandler(svc)
+		seedWebAuthnUser(repo, "user@example.com", true)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/begin", h.WebAuthnLoginBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/begin", bytes.NewReader(validPayload("user@example.com")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service default branch", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+		repo.webauthnCredentials[string(userID)] = []auth.UserWebAuthnCredential{{
+			UserID:         userID,
+			CredentialID:   []byte{1},
+			CredentialJSON: []byte("{bad"),
+		}}
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/begin", h.WebAuthnLoginBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/begin", bytes.NewReader(validPayload("user@example.com")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+		seedWebAuthnLoginCredential(t, repo, userID)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/begin", h.WebAuthnLoginBegin)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/begin", bytes.NewReader(validPayload("user@example.com")))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if !bytes.Contains(body, []byte(`"challenge_token"`)) || !bytes.Contains(body, []byte(`"public_key"`)) {
+			t.Fatalf("unexpected response body: %s", string(body))
+		}
+	})
+}
+
+func TestAuthHandler_WebAuthnLoginFinish(t *testing.T) {
+	validPayload := func(token string, credential []byte) []byte {
+		return []byte(fmt.Sprintf(`{"data":{"type":"auth_webauthn_login_finish","attributes":{"challenge_token":"%s","credential":%s}}}`, token, string(credential)))
+	}
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, true)
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/finish", h.WebAuthnLoginFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/finish", bytes.NewReader([]byte(`{"data":`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, true)
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/finish", h.WebAuthnLoginFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/finish", bytes.NewReader([]byte(`{"data":{"type":"auth_webauthn_login_finish","attributes":{"challenge_token":"","credential":null}}}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not configured", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := service.NewAuthService(repo, repo, store, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			JWTAccessSecret:  "access",
+			JWTRefreshSecret: "refresh",
+			JWTAccessTTL:     time.Minute,
+			JWTRefreshTTL:    time.Hour,
+		}})
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/finish", h.WebAuthnLoginFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/finish", bytes.NewReader(validPayload("tok", webAuthnAssertionPayloadForUser(uuidv7.MustBytes()))))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid challenge", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, true)
+		h := NewAuthHandler(svc)
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/finish", h.WebAuthnLoginFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/finish", bytes.NewReader(validPayload("missing", webAuthnAssertionPayloadForUser(uuidv7.MustBytes()))))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("payload invalid", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, true)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+		seedWebAuthnLoginCredential(t, repo, userID)
+		putWebAuthnChallenge(t, store, "tok-payload", "login", userID, webauthnlib.SessionData{
+			Challenge:      testWebAuthnLoginChallenge,
+			RelyingPartyID: "webauthn.io",
+			UserID:         userID,
+			Expires:        time.Now().UTC().Add(time.Minute),
+		})
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/finish", h.WebAuthnLoginFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/finish", bytes.NewReader(validPayload("tok-payload", []byte(`{}`))))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid credentials", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, true)
+		h := NewAuthHandler(svc)
+		userID := uuidv7.MustBytes()
+		putWebAuthnChallenge(t, store, "tok-invalid-credentials", "login", userID, webauthnlib.SessionData{
+			Challenge:      testWebAuthnLoginChallenge,
+			RelyingPartyID: "webauthn.io",
+			UserID:         userID,
+			Expires:        time.Now().UTC().Add(time.Minute),
+		})
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/finish", h.WebAuthnLoginFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/finish", bytes.NewReader(validPayload("tok-invalid-credentials", webAuthnAssertionPayloadForUser(userID))))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("credential unavailable", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, true)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+		putWebAuthnChallenge(t, store, "tok-no-cred", "login", userID, webauthnlib.SessionData{
+			Challenge:      testWebAuthnLoginChallenge,
+			RelyingPartyID: "webauthn.io",
+			UserID:         userID,
+			Expires:        time.Now().UTC().Add(time.Minute),
+		})
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/finish", h.WebAuthnLoginFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/finish", bytes.NewReader(validPayload("tok-no-cred", webAuthnAssertionPayloadForUser(userID))))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("verification failed", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, true)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+		seedWebAuthnLoginCredential(t, repo, userID)
+		putWebAuthnChallenge(t, store, "tok-verify", "login", userID, webauthnlib.SessionData{
+			Challenge:      "wrong-challenge",
+			RelyingPartyID: "webauthn.io",
+			UserID:         userID,
+			Expires:        time.Now().UTC().Add(time.Minute),
+		})
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/finish", h.WebAuthnLoginFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/finish", bytes.NewReader(validPayload("tok-verify", webAuthnAssertionPayloadForUser(userID))))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service default branch", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, true)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+		repo.webauthnCredentials[string(userID)] = []auth.UserWebAuthnCredential{{
+			UserID:         userID,
+			CredentialID:   []byte{1},
+			CredentialJSON: []byte("{bad"),
+		}}
+		putWebAuthnChallenge(t, store, "tok-default", "login", userID, webauthnlib.SessionData{
+			Challenge:      testWebAuthnLoginChallenge,
+			RelyingPartyID: "webauthn.io",
+			UserID:         userID,
+			Expires:        time.Now().UTC().Add(time.Minute),
+		})
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/finish", h.WebAuthnLoginFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/finish", bytes.NewReader(validPayload("tok-default", webAuthnAssertionPayloadForUser(userID))))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("token issue failed", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, false)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+		seedWebAuthnLoginCredential(t, repo, userID)
+		putWebAuthnChallenge(t, store, "tok-token-fail", "login", userID, webauthnlib.SessionData{
+			Challenge:      testWebAuthnLoginChallenge,
+			RelyingPartyID: "webauthn.io",
+			UserID:         userID,
+			Expires:        time.Now().UTC().Add(time.Minute),
+		})
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/finish", h.WebAuthnLoginFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/finish", bytes.NewReader(validPayload("tok-token-fail", webAuthnAssertionPayloadForUser(userID))))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemRepo()
+		store := newMemTokenStore()
+		svc := newWebAuthnAuthService(repo, store, true)
+		h := NewAuthHandler(svc)
+		userID := seedWebAuthnUser(repo, "user@example.com", true)
+		seedWebAuthnLoginCredential(t, repo, userID)
+		putWebAuthnChallenge(t, store, "tok-success", "login", userID, webauthnlib.SessionData{
+			Challenge:      testWebAuthnLoginChallenge,
+			RelyingPartyID: "webauthn.io",
+			UserID:         userID,
+			Expires:        time.Now().UTC().Add(time.Minute),
+		})
+
+		app := fiber.New()
+		app.Post("/api/v1/auth/webauthn/login/finish", h.WebAuthnLoginFinish)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/auth/webauthn/login/finish", bytes.NewReader(validPayload("tok-success", webAuthnAssertionPayloadForUser(userID))))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if !bytes.Contains(body, []byte(`"access_expires_in"`)) {
+			t.Fatalf("unexpected response body: %s", string(body))
+		}
+		if len(resp.Header.Values("Set-Cookie")) == 0 {
+			t.Fatalf("expected auth cookies to be set")
+		}
+	})
+}
diff --git a/internal/transport/http/handlers/base_handler.go b/internal/transport/http/handlers/base_handler.go
new file mode 100644
index 0000000..0783344
--- /dev/null
+++ b/internal/transport/http/handlers/base_handler.go
@@ -0,0 +1,2070 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"math"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/base"
+	filemanager "wucher/internal/domain/file_manager"
+	appservice "wucher/internal/service"
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/attachmentresolver"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+const (
+	basePhotoAttachmentRefType  = "base_photo"
+	basePhotoAttachmentCategory = "photo"
+)
+
+type basePresignStorage interface {
+	PresignGetObject(ctx context.Context, objectKey string, ttl time.Duration) (string, error)
+}
+
+type BaseHandler struct {
+	svc         base.Service
+	validate    *validators.Validator
+	fileManager filemanager.Service
+	storage     basePresignStorage
+}
+
+type baseDetailedWriter interface {
+	CreateDetailed(context.Context, appservice.BaseCreateInput) (*appservice.BaseWriteResult, error)
+	UpdateDetailed(context.Context, appservice.BaseUpdateInput) (*appservice.BaseWriteResult, error)
+}
+
+func NewBaseHandler(svc base.Service) *BaseHandler {
+	return &BaseHandler{svc: svc, validate: validators.New()}
+}
+
+func (h *BaseHandler) WithFileManagerService(fileManager filemanager.Service) *BaseHandler {
+	h.fileManager = fileManager
+	return h
+}
+
+func (h *BaseHandler) WithFileStorage(storage basePresignStorage) *BaseHandler {
+	h.storage = storage
+	return h
+}
+
+func (h *BaseHandler) WithFileResolver(fileManager filemanager.Service, storage basePresignStorage) *BaseHandler {
+	h.fileManager = fileManager
+	h.storage = storage
+	return h
+}
+
+func (h *BaseHandler) createBaseWithService(c *fiber.Ctx, svc baseDetailedWriter) bool {
+	var req dto.BaseCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		_ = writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+		return true
+	}
+
+	categoryType, errObj := resolveBaseCategoryType(c, req.Data.Attributes.BaseCategory, "/data/attributes/base_category")
+	if errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+	if errObj := validateBaseCoordinates(req.Data.Attributes.Latitude, req.Data.Attributes.Longitude, "/data/attributes/latitude", "/data/attributes/longitude"); errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+	baseName := strings.TrimSpace(req.Data.Attributes.BaseName)
+	if baseName == "" {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "base is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/base"},
+		}})
+		return true
+	}
+	createdBy, errObj := parseOptionalUUID(req.Data.Attributes.CreatedBy, "/data/attributes/created_by")
+	if errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+	updatedBy, errObj := parseOptionalUUID(req.Data.Attributes.UpdatedBy, "/data/attributes/updated_by")
+	if errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+	defaultStartTimeType, errObj := normalizeBaseShiftTimeType(stringOrDefault(req.Data.Attributes.DefaultStartTimeType, ""), "/data/attributes/default_start_time_type")
+	if errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+	defaultEndTimeType, errObj := normalizeBaseShiftTimeType(stringOrDefault(req.Data.Attributes.DefaultEndTimeType, ""), "/data/attributes/default_end_time_type")
+	if errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+	defaultShiftStart, defaultShiftEnd, errObj := parseBaseDefaultShiftRange(
+		req.Data.Attributes.DefaultShiftStart,
+		req.Data.Attributes.DefaultShiftEnd,
+		req.Data.Attributes.DefaultShiftTime,
+		defaultStartTimeType,
+		defaultEndTimeType,
+		true,
+		"/data/attributes/default_shift_start",
+		"/data/attributes/default_shift_end",
+		"/data/attributes/default_shift_time",
+	)
+	if errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+	operationalShiftTimes, errObj := parseBaseOperationalShiftTimes(req.Data.Attributes.OperationalShiftTimes, "/data/attributes/operational_shift_times")
+	if errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+	hemsEDCIDs, errObj := parseUUIDList(req.Data.Attributes.HEMSEDCContactIDs, "/data/attributes/hems_edc_contact_ids")
+	if errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+	medPaxIDs, errObj := parseUUIDList(req.Data.Attributes.MedPaxContactIDs, "/data/attributes/med_pax_contact_ids")
+	if errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+	pilotIDs, errObj := parseUUIDList(req.Data.Attributes.ResponsiblePilotContactIDs, "/data/attributes/responsible_pilot_contact_ids")
+	if errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+
+	modelID := uuidv7.MustBytes()
+	fotoAttachmentID := []byte(nil)
+	if req.Data.Attributes.FileUUID != nil {
+		resolved, handled := h.resolveBaseFotoAttachmentID(c, modelID, req.Data.Attributes.FileUUID)
+		if handled {
+			return true
+		}
+		fotoAttachmentID = resolved
+	}
+	res, err := svc.CreateDetailed(c.UserContext(), appservice.BaseCreateInput{
+		ID:                                 modelID,
+		CategoryType:                       categoryType,
+		BaseName:                           baseName,
+		BaseAbbreviation:                   stringOrDefault(req.Data.Attributes.BaseAbbreviation, ""),
+		Address:                            stringOrDefault(req.Data.Attributes.Address, ""),
+		Latitude:                           float64OrDefault(req.Data.Attributes.Latitude, 0),
+		Longitude:                          float64OrDefault(req.Data.Attributes.Longitude, 0),
+		LandlineNumber:                     stringOrDefault(req.Data.Attributes.LandlineNumber, ""),
+		MobileNumber:                       stringOrDefault(req.Data.Attributes.MobileNumber, ""),
+		Email:                              stringOrDefault(req.Data.Attributes.Email, ""),
+		SortKey:                            req.Data.Attributes.SortKey,
+		SMSAlert:                           boolOrDefault(req.Data.Attributes.SMSAlert, false),
+		Checklist:                          boolOrDefault(req.Data.Attributes.Checklist, false),
+		LegTime:                            stringOrDefault(req.Data.Attributes.LegTime, ""),
+		DefaultStartTimeType:               defaultStartTimeType,
+		DefaultEndTimeType:                 defaultEndTimeType,
+		DefaultShiftStart:                  defaultShiftStart,
+		DefaultShiftEnd:                    defaultShiftEnd,
+		UTC:                                stringOrDefault(req.Data.Attributes.UTC, ""),
+		Dry:                                boolOrDefault(req.Data.Attributes.Dry, false),
+		ControlCenter:                      boolOrDefault(req.Data.Attributes.ControlCenter, false),
+		DUL:                                boolOrDefault(req.Data.Attributes.DUL, false),
+		Notes:                              stringOrDefault(req.Data.Attributes.Notes, ""),
+		HEMSEDCContactIDs:          hemsEDCIDs,
+		MedPaxContactIDs:           medPaxIDs,
+		ResponsiblePilotContactIDs: pilotIDs,
+		OperationalShiftTimes:              operationalShiftTimes,
+		IsActive:                           boolOrDefault(req.Data.Attributes.IsActive, true),
+		CreatedBy:                          createdBy,
+		UpdatedBy:                          updatedBy,
+		FotoAttachmentID:                   fotoAttachmentID,
+	})
+	if err != nil {
+		var writeErr *appservice.BaseWriteError
+		if errors.As(err, &writeErr) {
+			errObj := jsonapi.ErrorObject{
+				Status: strconv.Itoa(writeErr.Status),
+				Title:  writeErr.Title,
+				Detail: writeErr.Detail,
+			}
+			if strings.TrimSpace(writeErr.Pointer) != "" {
+				errObj.Source = &jsonapi.ErrorSource{Pointer: writeErr.Pointer}
+			}
+			_ = writeBaseErrors(c, writeErr.Status, []jsonapi.ErrorObject{{
+				Status: errObj.Status, Title: errObj.Title, Detail: errObj.Detail, Source: errObj.Source,
+			}})
+			return true
+		}
+		_ = writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+		return true
+	}
+	if len(res.PreviousFotoAttachmentID) == 16 {
+		_ = syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, res.PreviousFotoAttachmentID, res.Row.FotoAttachmentID, actorUserID(c))
+	}
+	_ = response.Write(c, fiber.StatusCreated, h.baseResourceByCategory(c.UserContext(), res.Row, res.CategoryType))
+	return true
+}
+
+func (h *BaseHandler) updateBaseWithService(c *fiber.Ctx, svc baseDetailedWriter) bool {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+		return true
+	}
+
+	var req dto.BaseUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		_ = writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+		return true
+	}
+
+	attrs := req.Data.Attributes
+	categoryType, errObj := resolveBaseCategoryType(c, attrs.BaseCategory, "/data/attributes/base_category")
+	if errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+	if errObj := validateOptionalBaseCoordinates(attrs.Latitude, attrs.Longitude, "/data/attributes/latitude", "/data/attributes/longitude"); errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+	if attrs.BaseName == nil && attrs.BaseAbbreviation == nil && attrs.Address == nil && attrs.Latitude == nil && attrs.Longitude == nil && attrs.LandlineNumber == nil &&
+		attrs.MobileNumber == nil && attrs.Email == nil && attrs.SMSAlert == nil && attrs.Checklist == nil &&
+		!attrs.SortKey.Set &&
+		attrs.LegTime == nil && attrs.DefaultStartTimeType == nil && attrs.DefaultEndTimeType == nil &&
+		attrs.DefaultShiftStart == nil && attrs.DefaultShiftEnd == nil && attrs.DefaultShiftTime == nil && attrs.ShiftTime == nil &&
+		attrs.UTC == nil && attrs.FileUUID == nil && attrs.Dry == nil &&
+		attrs.ControlCenter == nil && attrs.DUL == nil && attrs.Notes == nil && attrs.IsActive == nil &&
+		attrs.HEMSEDCContactIDs == nil && attrs.MedPaxContactIDs == nil &&
+		attrs.ResponsiblePilotContactIDs == nil &&
+		attrs.OperationalShiftTimes == nil &&
+		attrs.CreatedBy == nil && attrs.UpdatedBy == nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+		return true
+	}
+
+	var defaultShiftStart *time.Time
+	var defaultShiftEnd *time.Time
+	var defaultStartTimeType *string
+	var defaultEndTimeType *string
+	if attrs.DefaultStartTimeType != nil || attrs.DefaultEndTimeType != nil || attrs.DefaultShiftStart != nil || attrs.DefaultShiftEnd != nil || attrs.DefaultShiftTime != nil {
+		startType, errObj := normalizeBaseShiftTimeType(stringOrDefault(attrs.DefaultStartTimeType, ""), "/data/attributes/default_start_time_type")
+		if errObj != nil {
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+			return true
+		}
+		endType, errObj := normalizeBaseShiftTimeType(stringOrDefault(attrs.DefaultEndTimeType, ""), "/data/attributes/default_end_time_type")
+		if errObj != nil {
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+			return true
+		}
+		parsedStart, parsedEnd, errObj := parseBaseDefaultShiftRange(
+			attrs.DefaultShiftStart,
+			attrs.DefaultShiftEnd,
+			attrs.DefaultShiftTime,
+			startType,
+			endType,
+			false,
+			"/data/attributes/default_shift_start",
+			"/data/attributes/default_shift_end",
+			"/data/attributes/default_shift_time",
+		)
+		if errObj != nil {
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+			return true
+		}
+		if attrs.DefaultShiftStart != nil || attrs.DefaultShiftTime != nil {
+			defaultShiftStart = parsedStart
+		}
+		if attrs.DefaultShiftEnd != nil || attrs.DefaultShiftTime != nil {
+			defaultShiftEnd = parsedEnd
+		}
+		if attrs.DefaultStartTimeType != nil {
+			defaultStartTimeType = &startType
+		}
+		if attrs.DefaultEndTimeType != nil {
+			defaultEndTimeType = &endType
+		}
+	}
+	if attrs.ShiftTime != nil && (strings.TrimSpace(attrs.ShiftTime.Start) != "" || strings.TrimSpace(attrs.ShiftTime.End) != "") {
+		if strings.TrimSpace(attrs.ShiftTime.Start) != "" {
+			start, errObj := parseOptionalClock(&attrs.ShiftTime.Start, "/data/attributes/shift_time/start")
+			if errObj != nil {
+				_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+				return true
+			}
+			defaultShiftStart = start
+		}
+		if strings.TrimSpace(attrs.ShiftTime.End) != "" {
+			end, errObj := parseOptionalClock(&attrs.ShiftTime.End, "/data/attributes/shift_time/end")
+			if errObj != nil {
+				_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+				return true
+			}
+			defaultShiftEnd = end
+		}
+	}
+	operationalShiftTimesSet := attrs.OperationalShiftTimes != nil
+	operationalShiftTimes, errObj := parseBaseOperationalShiftTimes(attrs.OperationalShiftTimes, "/data/attributes/operational_shift_times")
+	if errObj != nil {
+		_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		return true
+	}
+
+	var fotoAttachmentID []byte
+	fotoAttachmentSet := false
+	if attrs.FileUUID != nil {
+		fotoAttachmentSet = true
+		if hasBlankOptionalString(attrs.FileUUID) {
+			fotoAttachmentID = nil
+		} else {
+			resolved, handled := h.resolveExistingBaseFotoAttachmentOrFileID(c, id, attrs.FileUUID)
+			if handled {
+				return true
+			}
+			fotoAttachmentID = resolved
+		}
+	}
+
+	hemsEDCSet := attrs.HEMSEDCContactIDs != nil
+	medPaxSet := attrs.MedPaxContactIDs != nil
+	pilotSet := attrs.ResponsiblePilotContactIDs != nil
+	var hemsEDCIDs [][]byte
+	var medPaxIDs [][]byte
+	var pilotIDs [][]byte
+	if hemsEDCSet {
+		var errObj *jsonapi.ErrorObject
+		hemsEDCIDs, errObj = parseUUIDList(*attrs.HEMSEDCContactIDs, "/data/attributes/hems_edc_contact_ids")
+		if errObj != nil {
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+			return true
+		}
+	}
+	if medPaxSet {
+		var errObj *jsonapi.ErrorObject
+		medPaxIDs, errObj = parseUUIDList(*attrs.MedPaxContactIDs, "/data/attributes/med_pax_contact_ids")
+		if errObj != nil {
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+			return true
+		}
+	}
+	if pilotSet {
+		var errObj *jsonapi.ErrorObject
+		pilotIDs, errObj = parseUUIDList(*attrs.ResponsiblePilotContactIDs, "/data/attributes/responsible_pilot_contact_ids")
+		if errObj != nil {
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+			return true
+		}
+	}
+
+	var sortKeyValue *int
+	sortKeyValid := false
+	if attrs.SortKey.Set {
+		sortKeyVal := attrs.SortKey.Value
+		sortKeyValue = &sortKeyVal
+		sortKeyValid = attrs.SortKey.Valid
+	}
+
+	createdBySet := attrs.CreatedBy != nil
+	updatedBySet := attrs.UpdatedBy != nil
+	var createdBy []byte
+	var updatedBy []byte
+	if createdBySet {
+		parsed, errObj := parseUUIDOrClear(*attrs.CreatedBy, "/data/attributes/created_by")
+		if errObj != nil {
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+			return true
+		}
+		createdBy = parsed
+	}
+	if updatedBySet {
+		parsed, errObj := parseUUIDOrClear(*attrs.UpdatedBy, "/data/attributes/updated_by")
+		if errObj != nil {
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+			return true
+		}
+		updatedBy = parsed
+	}
+
+	res, err := svc.UpdateDetailed(c.UserContext(), appservice.BaseUpdateInput{
+		ID:                                    id,
+		CategoryType:                          categoryType,
+		BaseName:                              attrs.BaseName,
+		BaseAbbreviation:                      attrs.BaseAbbreviation,
+		Address:                               attrs.Address,
+		Latitude:                              attrs.Latitude,
+		Longitude:                             attrs.Longitude,
+		LandlineNumber:                        attrs.LandlineNumber,
+		MobileNumber:                          attrs.MobileNumber,
+		Email:                                 attrs.Email,
+		SortKeySet:                            attrs.SortKey.Set,
+		SortKeyValid:                          sortKeyValid,
+		SortKeyValue:                          sortKeyValue,
+		SMSAlert:                              attrs.SMSAlert,
+		Checklist:                             attrs.Checklist,
+		LegTime:                               attrs.LegTime,
+		DefaultStartTimeType:                  defaultStartTimeType,
+		DefaultEndTimeType:                    defaultEndTimeType,
+		DefaultShiftStart:                     defaultShiftStart,
+		DefaultShiftEnd:                       defaultShiftEnd,
+		UTC:                                   attrs.UTC,
+		Dry:                                   attrs.Dry,
+		ControlCenter:                         attrs.ControlCenter,
+		DUL:                                   attrs.DUL,
+		Notes:                                 attrs.Notes,
+		HEMSEDCContactIDs:    hemsEDCIDs,
+		HEMSEDCContactIDsSet: hemsEDCSet,
+		MedPaxContactIDs:     medPaxIDs,
+		MedPaxContactIDsSet:  medPaxSet,
+		ResponsiblePilotContactIDs:            pilotIDs,
+		ResponsiblePilotContactIDsSet:         pilotSet,
+		OperationalShiftTimes:                 operationalShiftTimes,
+		OperationalShiftTimesSet:              operationalShiftTimesSet,
+		IsActive:                              attrs.IsActive,
+		CreatedBy:                             createdBy,
+		CreatedBySet:                          createdBySet,
+		UpdatedBy:                             updatedBy,
+		UpdatedBySet:                          updatedBySet,
+		FotoAttachmentID:                      fotoAttachmentID,
+		FotoAttachmentSet:                     fotoAttachmentSet,
+	})
+	if err != nil {
+		var writeErr *appservice.BaseWriteError
+		if errors.As(err, &writeErr) {
+			errObj := jsonapi.ErrorObject{
+				Status: strconv.Itoa(writeErr.Status),
+				Title:  writeErr.Title,
+				Detail: writeErr.Detail,
+			}
+			if strings.TrimSpace(writeErr.Pointer) != "" {
+				errObj.Source = &jsonapi.ErrorSource{Pointer: writeErr.Pointer}
+			}
+			_ = writeBaseErrors(c, writeErr.Status, []jsonapi.ErrorObject{errObj})
+			return true
+		}
+		_ = writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+		return true
+	}
+	if err := syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, res.PreviousFotoAttachmentID, res.Row.FotoAttachmentID, actorUserID(c)); err != nil {
+		_ = writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+		return true
+	}
+	_ = response.Write(c, fiber.StatusOK, h.baseResourceByCategory(c.UserContext(), res.Row, res.CategoryType))
+	return true
+}
+
+// CreateBase godoc
+// @Summary Create base
+// @Tags Bases
+// @Accept json
+// @Produce json
+// @Description Example request:
+// @Description {"data":{"type":"base","attributes":{"base":"Lude Testing 2","base_abbreviation":"LOIG","base_category":"regular","address":"Lude Airfield","latitude":47.3769,"longitude":8.5417,"sortkey":1,"sms_alert":false,"checklist":false,"leg_time":"00:20","default_start_time_type":"FIXED","default_end_time_type":"FIXED","default_shift_start":"06:00","default_shift_end":"21:00","utc":"0","notes":"Main base","operational_shift_times":[{"date_start":"2026-06-15","date_end":"2026-06-15","start_time_type":"BMCT","end_time_type":"ECET"}]}}}
+// @Param request body dto.BaseCreateRequest true "JSON:API base create request"
+// @Success 201 {object} dto.BaseResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/bases/create [post]
+func (h *BaseHandler) CreateBase(c *fiber.Ctx) error {
+	svc, ok := h.svc.(baseDetailedWriter)
+	if !ok {
+		return writeBaseErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Create failed",
+			Detail: "base service is not configured",
+		}})
+	}
+	if h.createBaseWithService(c, svc) {
+		return nil
+	}
+
+	var req dto.BaseCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	categoryType, errObj := resolveBaseCategoryType(c, req.Data.Attributes.BaseCategory, "/data/attributes/base_category")
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	if errObj := validateBaseCoordinates(req.Data.Attributes.Latitude, req.Data.Attributes.Longitude, "/data/attributes/latitude", "/data/attributes/longitude"); errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	baseName := strings.TrimSpace(req.Data.Attributes.BaseName)
+	if baseName == "" {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "base is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/base"},
+		}})
+	}
+
+	createdBy, errObj := parseOptionalUUID(req.Data.Attributes.CreatedBy, "/data/attributes/created_by")
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	updatedBy, errObj := parseOptionalUUID(req.Data.Attributes.UpdatedBy, "/data/attributes/updated_by")
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	defaultStartTimeType, errObj := normalizeBaseShiftTimeType(stringOrDefault(req.Data.Attributes.DefaultStartTimeType, ""), "/data/attributes/default_start_time_type")
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	defaultEndTimeType, errObj := normalizeBaseShiftTimeType(stringOrDefault(req.Data.Attributes.DefaultEndTimeType, ""), "/data/attributes/default_end_time_type")
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	defaultShiftStart, defaultShiftEnd, errObj := parseBaseDefaultShiftRange(
+		req.Data.Attributes.DefaultShiftStart,
+		req.Data.Attributes.DefaultShiftEnd,
+		req.Data.Attributes.DefaultShiftTime,
+		defaultStartTimeType,
+		defaultEndTimeType,
+		true,
+		"/data/attributes/default_shift_start",
+		"/data/attributes/default_shift_end",
+		"/data/attributes/default_shift_time",
+	)
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	row := &base.Base{ID: uuidv7.MustBytes()}
+	*row = *dto.MapBaseCreateAttributesToDomain(req.Data.Attributes)
+	row.ID = uuidv7.MustBytes()
+	row.BaseName = baseName
+	row.DefaultStartTimeType = defaultStartTimeType
+	row.DefaultEndTimeType = defaultEndTimeType
+	row.DefaultShiftStart = clockStringOrEmpty(defaultShiftStart)
+	row.DefaultShiftEnd = clockStringOrEmpty(defaultShiftEnd)
+	if req.Data.Attributes.FileUUID != nil {
+		fotoAttachmentID, resolveErr := h.resolveBaseFotoAttachmentID(c, row.ID, req.Data.Attributes.FileUUID)
+		if resolveErr {
+			return nil
+		}
+		row.FotoAttachmentID = fotoAttachmentID
+	}
+	hemsEDCIDs, errObj := parseUUIDList(req.Data.Attributes.HEMSEDCContactIDs, "/data/attributes/hems_edc_contact_ids")
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	medPaxIDs, errObj := parseUUIDList(req.Data.Attributes.MedPaxContactIDs, "/data/attributes/med_pax_contact_ids")
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	pilotIDs, errObj := parseUUIDList(req.Data.Attributes.ResponsiblePilotContactIDs, "/data/attributes/responsible_pilot_contact_ids")
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	row.HEMSEDCContactIDs = hemsEDCIDs
+	row.MedPaxContactIDs = medPaxIDs
+	row.ResponsiblePilotContactIDs = pilotIDs
+	row.CreatedBy = createdBy
+	row.UpdatedBy = updatedBy
+
+	if err := h.svc.CreateBase(c.UserContext(), row, categoryType); err != nil {
+		return writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if len(row.FotoAttachmentID) == 16 {
+		if err := syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, nil, row.FotoAttachmentID, actorUserID(c)); err != nil {
+			return writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Create failed",
+				Detail: safeInternalDetail(),
+			}})
+		}
+	}
+
+	created, err := h.svc.GetBaseByID(c.UserContext(), row.ID, categoryType)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, h.baseResourceByCategory(c.UserContext(), created, categoryType))
+	}
+	return response.Write(c, fiber.StatusCreated, h.baseResourceByCategory(c.UserContext(), row, categoryType))
+}
+
+// UpdateBase godoc
+// @Summary Update base
+// @Tags Bases
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Base UUID (UUIDv7)"
+// @Description Example request:
+// @Description {"data":{"type":"hems_base","id":"<uuid>","attributes":{"base":"Lude Testing 2","base_abbreviation":"LOIG","base_category":"regular","address":"Lude Airfield","latitude":47.3769,"longitude":8.5417,"sortkey":1,"sms_alert":false,"checklist":false,"leg_time":"00:20","default_start_time_type":"FIXED","default_end_time_type":"FIXED","default_shift_start":"06:00","default_shift_end":"21:00","utc":"0","notes":"Main base","operational_shift_times":[{"date_start":"2026-06-15","date_end":"2026-06-15","start_time_type":"BMCT","end_time_type":"ECET"}]}}}
+// @Param request body dto.BaseUpdateRequest true "JSON:API base update request"
+// @Success 200 {object} dto.BaseResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/bases/update/{uuid} [patch]
+func (h *BaseHandler) UpdateBase(c *fiber.Ctx) error {
+	svc, ok := h.svc.(baseDetailedWriter)
+	if !ok {
+		return writeBaseErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Update failed",
+			Detail: "base service is not configured",
+		}})
+	}
+	if h.updateBaseWithService(c, svc) {
+		return nil
+	}
+
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.BaseUpdateRequest
+	rawBody := append([]byte(nil), c.Body()...)
+	if err := c.BodyParser(&req); err != nil {
+		return writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.ShiftTime == nil {
+		attrs.ShiftTime = extractBaseShiftTimeFromUpdateBody(rawBody)
+	}
+	categoryType, errObj := resolveBaseCategoryType(c, attrs.BaseCategory, "/data/attributes/base_category")
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	if errObj := validateOptionalBaseCoordinates(attrs.Latitude, attrs.Longitude, "/data/attributes/latitude", "/data/attributes/longitude"); errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	if attrs.BaseName == nil && attrs.BaseAbbreviation == nil && attrs.Address == nil && attrs.LandlineNumber == nil &&
+		attrs.MobileNumber == nil && attrs.Email == nil && attrs.SMSAlert == nil && attrs.Checklist == nil &&
+		!attrs.SortKey.Set &&
+		attrs.LegTime == nil && attrs.DefaultStartTimeType == nil && attrs.DefaultEndTimeType == nil &&
+		attrs.DefaultShiftStart == nil && attrs.DefaultShiftEnd == nil && attrs.DefaultShiftTime == nil && attrs.ShiftTime == nil &&
+		attrs.UTC == nil && attrs.FileUUID == nil && attrs.Dry == nil &&
+		attrs.ControlCenter == nil && attrs.DUL == nil && attrs.Notes == nil && attrs.IsActive == nil &&
+		attrs.HEMSEDCContactIDs == nil && attrs.MedPaxContactIDs == nil &&
+		attrs.ResponsiblePilotContactIDs == nil &&
+		attrs.CreatedBy == nil && attrs.UpdatedBy == nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetBaseByID(c.UserContext(), id, categoryType)
+	if err != nil || existing == nil {
+		return writeBaseErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: categoryNotFoundDetail(categoryType),
+		}})
+	}
+	prevFotoAttachmentID := append([]byte(nil), existing.FotoAttachmentID...)
+
+	if attrs.BaseName != nil {
+		v := strings.TrimSpace(*attrs.BaseName)
+		if v == "" {
+			return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "base cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/base"},
+			}})
+		}
+		existing.BaseName = v
+	}
+	dto.ApplyBaseUpdateAttributesToDomain(existing, attrs)
+	if attrs.DefaultStartTimeType != nil {
+		parsed, errObj := normalizeBaseShiftTimeType(*attrs.DefaultStartTimeType, "/data/attributes/default_start_time_type")
+		if errObj != nil {
+			return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.DefaultStartTimeType = parsed
+	}
+	if attrs.DefaultEndTimeType != nil {
+		parsed, errObj := normalizeBaseShiftTimeType(*attrs.DefaultEndTimeType, "/data/attributes/default_end_time_type")
+		if errObj != nil {
+			return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.DefaultEndTimeType = parsed
+	}
+	if attrs.DefaultShiftStart != nil || attrs.DefaultShiftEnd != nil || attrs.DefaultShiftTime != nil {
+		parsedStart, parsedEnd, errObj := parseBaseDefaultShiftRange(
+			attrs.DefaultShiftStart,
+			attrs.DefaultShiftEnd,
+			attrs.DefaultShiftTime,
+			normalizeBaseShiftTimeTypeOrFixed(existing.DefaultStartTimeType),
+			normalizeBaseShiftTimeTypeOrFixed(existing.DefaultEndTimeType),
+			false,
+			"/data/attributes/default_shift_start",
+			"/data/attributes/default_shift_end",
+			"/data/attributes/default_shift_time",
+		)
+		if errObj != nil {
+			return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		if attrs.DefaultShiftStart != nil || attrs.DefaultShiftTime != nil {
+			existing.DefaultShiftStart = clockStringOrEmpty(parsedStart)
+		}
+		if attrs.DefaultShiftEnd != nil || attrs.DefaultShiftTime != nil {
+			existing.DefaultShiftEnd = clockStringOrEmpty(parsedEnd)
+		}
+	}
+	if normalizeBaseShiftTimeTypeOrFixed(existing.DefaultStartTimeType) != base.ShiftTimeTypeFixed {
+		existing.DefaultShiftStart = ""
+	}
+	if normalizeBaseShiftTimeTypeOrFixed(existing.DefaultEndTimeType) != base.ShiftTimeTypeFixed {
+		existing.DefaultShiftEnd = ""
+	}
+	if attrs.FileUUID != nil {
+		if hasBlankOptionalString(attrs.FileUUID) {
+			existing.FotoAttachmentID = nil
+		} else {
+			fotoAttachmentID, resolveErr := h.resolveExistingBaseFotoAttachmentOrFileID(c, existing.ID, attrs.FileUUID)
+			if resolveErr {
+				return nil
+			}
+			existing.FotoAttachmentID = fotoAttachmentID
+		}
+	}
+	if attrs.HEMSEDCContactIDs != nil {
+		parsed, errObj := parseUUIDList(*attrs.HEMSEDCContactIDs, "/data/attributes/hems_edc_contact_ids")
+		if errObj != nil {
+			return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.HEMSEDCContactIDs = parsed
+	}
+	if attrs.MedPaxContactIDs != nil {
+		parsed, errObj := parseUUIDList(*attrs.MedPaxContactIDs, "/data/attributes/med_pax_contact_ids")
+		if errObj != nil {
+			return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.MedPaxContactIDs = parsed
+	}
+	if attrs.ResponsiblePilotContactIDs != nil {
+		parsed, errObj := parseUUIDList(*attrs.ResponsiblePilotContactIDs, "/data/attributes/responsible_pilot_contact_ids")
+		if errObj != nil {
+			return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.ResponsiblePilotContactIDs = parsed
+	}
+	if attrs.CreatedBy != nil {
+		parsed, errObj := parseUUIDOrClear(*attrs.CreatedBy, "/data/attributes/created_by")
+		if errObj != nil {
+			return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.CreatedBy = parsed
+	}
+	if attrs.UpdatedBy != nil {
+		parsed, errObj := parseUUIDOrClear(*attrs.UpdatedBy, "/data/attributes/updated_by")
+		if errObj != nil {
+			return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.UpdatedBy = parsed
+	}
+
+	// Convert shift_time object to individual fields (handler responsibility for HTTP format translation)
+	if attrs.ShiftTime != nil && (attrs.ShiftTime.Start != "" || attrs.ShiftTime.End != "") {
+		if attrs.ShiftTime.Start != "" {
+			start, errObj := parseOptionalClock(&attrs.ShiftTime.Start, "/data/attributes/shift_time/start")
+			if errObj != nil {
+				return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+			}
+			existing.DefaultShiftStart = clockStringOrEmpty(start)
+		}
+		if attrs.ShiftTime.End != "" {
+			end, errObj := parseOptionalClock(&attrs.ShiftTime.End, "/data/attributes/shift_time/end")
+			if errObj != nil {
+				return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+			}
+			existing.DefaultShiftEnd = clockStringOrEmpty(end)
+		}
+	}
+
+	if err := h.svc.UpdateBase(c.UserContext(), existing, categoryType); err != nil {
+		return writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if err := syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, prevFotoAttachmentID, existing.FotoAttachmentID, actorUserID(c)); err != nil {
+		return writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetBaseByID(c.UserContext(), existing.ID, categoryType)
+	if err == nil && updated != nil {
+		if attrs.ShiftTime != nil && (attrs.ShiftTime.Start != "" || attrs.ShiftTime.End != "") {
+			updated.DefaultShiftStart = existing.DefaultShiftStart
+			updated.DefaultShiftEnd = existing.DefaultShiftEnd
+		}
+		if attrs.OperationalShiftTimes != nil {
+			updated.OperationalShiftTimes = existing.OperationalShiftTimes
+		}
+		return response.Write(c, fiber.StatusOK, h.baseResourceByCategory(c.UserContext(), updated, categoryType))
+	}
+	return response.Write(c, fiber.StatusOK, h.baseResourceByCategory(c.UserContext(), existing, categoryType))
+}
+
+// DeleteBase godoc
+// @Summary Delete base
+// @Tags Bases
+// @Produce json
+// @Param uuid path string true "Base UUID (UUIDv7)"
+// @Success 200 {object} dto.BaseDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/bases/delete/{uuid} [delete]
+func (h *BaseHandler) DeleteBase(c *fiber.Ctx) error {
+	categoryType, errObj := parseBaseCategoryTypeQuery(c)
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	row, err := h.svc.DeleteBase(c.UserContext(), id, categoryType)
+	if err != nil {
+		if _, ok := apperrors.AsDeleteConflict(err); ok {
+			def := apperrorsx.ErrBaseRelationDelete
+			return jsonapi.WriteErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status:    "409",
+				Code:      def.Code,
+				ErrorCode: def.ErrorCode,
+				Title:     def.Title,
+				Detail:    err.Error(),
+			}})
+		}
+		return writeDeleteError(c, err)
+	}
+	if row == nil {
+		return writeBaseErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "base not found",
+		}})
+	}
+	if row == nil {
+		return writeBaseErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: categoryNotFoundDetail(categoryType),
+		}})
+	}
+	if row != nil && len(row.FotoAttachmentID) == 16 {
+		if err := syncAttachmentLifecycleClear(c.UserContext(), h.fileManager, row.FotoAttachmentID, actorUserID(c)); err != nil {
+			return writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Delete failed",
+				Detail: safeInternalDetail(),
+			}})
+		}
+	}
+
+	deleteType := "base_delete"
+	if categoryType == base.CategoryKeyHEMS {
+		deleteType = "hems_base_delete"
+	}
+
+	idStr, _ := uuidv7.BytesToString(id)
+	if row == nil {
+		// fallback minimal response when no row is available
+		return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+			Type:       deleteType,
+			ID:         idStr,
+			Attributes: map[string]any{"deleted": true},
+		})
+	}
+
+	// minimal attributes required for delete response per request
+	attrs := map[string]any{
+		"base":              row.BaseName,
+		"base_abbreviation": row.BaseAbbreviation,
+		"base_category":     baseCategoryFromRowOrType(row, categoryType),
+		"created_at":        row.CreatedAt.UTC().Format(time.RFC3339),
+		"created_by":        bytesUUIDToString(row.CreatedBy),
+		"updated_at":        row.UpdatedAt.UTC().Format(time.RFC3339),
+		"updated_by":        bytesUUIDToString(row.UpdatedBy),
+		"deleted_at":        timeStringOrEmpty(row.DeletedAt),
+		"deleted_by":        bytesUUIDToString(row.DeletedBy),
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type:       deleteType,
+		ID:         idStr,
+		Attributes: attrs,
+	})
+}
+
+// GetBaseByID godoc
+// @Summary Get base by ID
+// @Tags Bases
+// @Produce json
+// @Param uuid path string true "Base UUID (UUIDv7)"
+// @Success 200 {object} dto.BaseResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/bases/get/{uuid} [get]
+func (h *BaseHandler) GetBase(c *fiber.Ctx) error {
+	categoryType, errObj := parseBaseCategoryTypeQuery(c)
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	row, err := h.svc.GetBaseByID(c.UserContext(), id, categoryType)
+	if err != nil || row == nil {
+		return writeBaseErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: categoryNotFoundDetail(categoryType),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, h.baseResourceByCategory(c.UserContext(), row, categoryType))
+}
+
+// ListBases godoc
+// @Summary List bases
+// @Description JSON:API list with filtering and sorting. This endpoint returns all bases.
+// @Tags Bases
+// @Produce json
+// @Param category_type query string false "Base category" Enums(regular,hems)
+// @Param base_category query string false "Alias filter for base category" Enums(regular,hems)
+// @Param search query string false "Search by base/base_abbreviation/address/email/phone"
+// @Param dul query boolean false "Filter by DUL flag (true/false)"
+// @Param page query int false "Ignored"
+// @Param size query int false "Ignored"
+// @Param limit query int false "Ignored"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.BaseListResponse
+// @Router /api/v1/bases/get-all [get]
+func (h *BaseHandler) ListBases(c *fiber.Ctx) error {
+	categoryType, errObj := parseOptionalBaseCategoryTypeQuery(c)
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	dulFilter, errObj := parseOptionalBoolQueryParam(c, "dul")
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	filter := c.Query("search")
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.ListBases(c.UserContext(), filter, sort, 0, 0, categoryType, dulFilter)
+	if err != nil {
+		return writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.BaseResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, h.baseResourceByCategory(c.UserContext(), &rows[i], categoryType))
+	}
+
+	meta := map[string]any{
+		"total": total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListBasesDatatable godoc
+// @Summary List bases (datatable)
+// @Tags Bases
+// @Produce json
+// @Param category_type query string false "Base category" Enums(regular,hems)
+// @Param base_category query string false "Alias filter for base category" Enums(regular,hems)
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Param dul query boolean false "Filter by DUL flag (true/false)"
+// @Success 200 {object} dto.BaseDataTableResponse
+// @Router /api/v1/bases/get-all/dt [get]
+func (h *BaseHandler) ListBasesDatatable(c *fiber.Ctx) error {
+	categoryType, errObj := parseOptionalBaseCategoryTypeQuery(c)
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	dulFilter, errObj := parseOptionalBoolQueryParam(c, "dul")
+	if errObj != nil {
+		return writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.svc.ListBases(c.UserContext(), search, "", length, start, categoryType, dulFilter)
+	if err != nil {
+		return writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.BaseResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, h.baseResourceByCategory(c.UserContext(), &rows[i], categoryType))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func (h *BaseHandler) baseResource(ctx context.Context, row *base.Base, categoryType string) dto.BaseResource {
+	baseRow := row
+	id := ""
+	defaultShiftStart := ""
+	defaultShiftEnd := ""
+	defaultStartTimeType := base.ShiftTimeTypeFixed
+	defaultEndTimeType := base.ShiftTimeTypeFixed
+	if baseRow != nil {
+		id, _ = uuidv7.BytesToString(baseRow.ID)
+		defaultStartTimeType = normalizeBaseShiftTimeTypeOrFixed(baseRow.DefaultStartTimeType)
+		defaultEndTimeType = normalizeBaseShiftTimeTypeOrFixed(baseRow.DefaultEndTimeType)
+		defaultShiftStart = dto.DisplayBaseShiftValue(defaultStartTimeType, baseRow.DefaultShiftStart)
+		defaultShiftEnd = dto.DisplayBaseShiftValue(defaultEndTimeType, baseRow.DefaultShiftEnd)
+	}
+	baseCategory := baseCategoryFromRowOrType(baseRow, categoryType)
+	resourceType := "base"
+	if baseCategory == base.CategoryKeyHEMS {
+		resourceType = "hems_base"
+	}
+	var foto *dto.BaseFoto
+	fotoUUID := ""
+	if baseRow != nil {
+		fotoUUID = idString(baseRow.FotoAttachmentID)
+	}
+	fotoDownloadURL := ""
+	fotoThumbnailURL := ""
+	var fotoOriginalSizeBytes *int64
+	if baseRow != nil && baseRow.FotoAttachment != nil && baseRow.FotoAttachment.File != nil {
+		asset := resolveFileManagerDownloadURLs(ctx, h.storage, baseRow.FotoAttachment.File)
+		fotoDownloadURL = strings.TrimSpace(asset.OriginalURL)
+		fotoThumbnailURL = strings.TrimSpace(asset.ThumbnailURL)
+		fotoOriginalSizeBytes = int64Ptr(asset.OriginalSizeBytes)
+	}
+	if fotoUUID != "" || fotoDownloadURL != "" || fotoThumbnailURL != "" || fotoOriginalSizeBytes != nil {
+		foto = &dto.BaseFoto{
+			UUID:                 fotoUUID,
+			DownloadURL:          fotoDownloadURL,
+			ThumbnailDownloadURL: fotoThumbnailURL,
+			OriginalSizeBytes:    fotoOriginalSizeBytes,
+		}
+	}
+	var hemsEDCIDs []string
+	var hemsEDCs []dto.BaseContact
+	var medPaxIDs []string
+	var medPax []dto.BaseContact
+	var pilotIDs []string
+	var pilots []dto.BaseContact
+	if baseRow != nil {
+		hemsEDCIDs = uuidListToStrings(baseRow.HEMSEDCContactIDs)
+		hemsEDCs = baseContactResources(baseRow.HEMSEDCs)
+		medPaxIDs = uuidListToStrings(baseRow.MedPaxContactIDs)
+		medPax = baseContactResources(baseRow.MedPax)
+		pilotIDs = uuidListToStrings(baseRow.ResponsiblePilotContactIDs)
+		pilots = baseContactResources(baseRow.ResponsiblePilots)
+	}
+	operationalShiftTimes := []dto.BaseOperationalShiftTime(nil)
+	if baseRow != nil {
+		operationalShiftTimes = dto.MapBaseOperationalShiftTimesToDTO(baseRow.OperationalShiftTimes)
+	}
+
+	return dto.MapBaseToResource(baseRow, dto.BaseResponseMappingInput{
+		ResourceType:                       resourceType,
+		BaseCategory:                       baseCategory,
+		ID:                                 id,
+		DefaultStartTimeType:               defaultStartTimeType,
+		DefaultEndTimeType:                 defaultEndTimeType,
+		ShiftTime:                          dto.BaseShiftTime{Start: defaultShiftStart, End: defaultShiftEnd},
+		Foto:                               foto,
+		Latitude:                           float64FromBase(baseRow),
+		Longitude:                          float64FromBaseLongitude(baseRow),
+		HEMSEDCContactIDs:  hemsEDCIDs,
+		HEMSEDCs:           hemsEDCs,
+		MedPaxContactIDs:   medPaxIDs,
+		MedPax:             medPax,
+		ResponsiblePilotContactIDs: pilotIDs,
+		ResponsiblePilots:          pilots,
+		OperationalShiftTimes:              operationalShiftTimes,
+	})
+}
+
+func float64FromBase(row *base.Base) float64 {
+	if row == nil {
+		return 0
+	}
+	return row.Latitude
+}
+
+func float64FromBaseLongitude(row *base.Base) float64 {
+	if row == nil {
+		return 0
+	}
+	return row.Longitude
+}
+
+func cloneIntPointerBase(v *int) *int {
+	if v == nil {
+		return nil
+	}
+	copied := *v
+	return &copied
+}
+
+func preferStringPtr(primary, fallback *string) *string {
+	if primary != nil {
+		return primary
+	}
+	return fallback
+}
+
+func parseUUIDList(values []string, pointer string) ([][]byte, *jsonapi.ErrorObject) {
+	out := make([][]byte, 0, len(values))
+	seen := map[string]struct{}{}
+	for i := range values {
+		v := strings.TrimSpace(values[i])
+		if v == "" {
+			continue
+		}
+		id, err := uuidv7.ParseString(v)
+		if err != nil {
+			return nil, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "value is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: pointer},
+			}
+		}
+		key := string(id)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		out = append(out, id)
+	}
+	return out, nil
+}
+
+func uuidListToStrings(values [][]byte) []string {
+	if len(values) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(values))
+	for i := range values {
+		id, err := uuidv7.BytesToString(values[i])
+		if err != nil {
+			continue
+		}
+		out = append(out, id)
+	}
+	return out
+}
+
+func baseContactResources(values []base.BaseContactPerson) []dto.BaseContact {
+	if len(values) == 0 {
+		return nil
+	}
+	out := make([]dto.BaseContact, 0, len(values))
+	for i := range values {
+		id, err := uuidv7.BytesToString(values[i].ContactID)
+		if err != nil || strings.TrimSpace(id) == "" {
+			continue
+		}
+		out = append(out, dto.BaseContact{
+			ID:        id,
+			FirstName: values[i].FirstName,
+			LastName:  values[i].LastName,
+		})
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func (h *BaseHandler) baseResourceByCategory(ctx context.Context, row *base.Base, categoryType string) dto.BaseResource {
+	return h.baseResource(ctx, row, categoryType)
+}
+
+func (h *BaseHandler) resolveBaseFotoAttachmentID(
+	c *fiber.Ctx,
+	baseID []byte,
+	rawFileUUID *string,
+) ([]byte, bool) {
+	return h.resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+		FileManager: h.fileManager,
+
+		RawFileID: rawFileUUID,
+
+		FileField: "file_uuid",
+
+		RequireValue: false,
+
+		RefType:  basePhotoAttachmentRefType,
+		RefID:    idString(baseID),
+		Category: ptrString(basePhotoAttachmentCategory),
+
+		IsPrimary: true,
+		ActorID:   actorUserID(c),
+
+		ValidateAttachmentExists: false,
+	}, "Update failed")
+}
+
+func (h *BaseHandler) resolveExistingBaseFotoAttachmentOrFileID(
+	c *fiber.Ctx,
+	baseID []byte,
+	rawUUID *string,
+) ([]byte, bool) {
+	if hasNonEmptyOptionalString(rawUUID) && h.fileManager != nil {
+		candidateID, err := uuidv7.ParseString(strings.TrimSpace(*rawUUID))
+		if err == nil {
+			attachment, getErr := h.fileManager.GetAttachmentByID(c.UserContext(), candidateID)
+			if getErr != nil {
+				_ = writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+					Status: "400",
+					Title:  "Update failed",
+					Detail: getErr.Error(),
+				}})
+				return nil, true
+			}
+			if attachment != nil {
+				return candidateID, false
+			}
+		}
+	}
+	return h.resolveBaseFotoAttachmentID(c, baseID, rawUUID)
+}
+
+func (h *BaseHandler) resolveAttachmentIDFromInput(
+	c *fiber.Ctx,
+	params attachmentresolver.Params,
+	errorTitle string,
+) ([]byte, bool) {
+	attachmentID, err := attachmentresolver.Resolve(c.UserContext(), params)
+	if err == nil {
+		return attachmentID, false
+	}
+
+	var resolveErr *attachmentresolver.ResolveError
+	if errors.As(err, &resolveErr) {
+		switch resolveErr.Code {
+		case attachmentresolver.ErrorInvalidAttachmentUUID:
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("%s is invalid UUID", fieldOrDefault(resolveErr.AttachmentField, "attachment_id")),
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/" + fieldOrDefault(resolveErr.AttachmentField, "attachment_id")},
+			}})
+			return nil, true
+		case attachmentresolver.ErrorInvalidFileUUID:
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("%s is invalid UUID", fieldOrDefault(resolveErr.FileField, "file_id")),
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/" + fieldOrDefault(resolveErr.FileField, "file_id")},
+			}})
+			return nil, true
+		case attachmentresolver.ErrorAttachmentNotFound:
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("%s not found", fieldOrDefault(resolveErr.AttachmentField, "attachment_id")),
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/" + fieldOrDefault(resolveErr.AttachmentField, "attachment_id")},
+			}})
+			return nil, true
+		case attachmentresolver.ErrorRequireValue:
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("%s or %s is required", fieldOrDefault(resolveErr.AttachmentField, "attachment_id"), fieldOrDefault(resolveErr.FileField, "file_id")),
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+			}})
+			return nil, true
+		case attachmentresolver.ErrorCannotResolveFromFile:
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("cannot resolve attachment from %s", fieldOrDefault(resolveErr.FileField, "file_id")),
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/" + fieldOrDefault(resolveErr.FileField, "file_id")},
+			}})
+			return nil, true
+		case attachmentresolver.ErrorFileNotReadyForAttachment:
+			_ = writeBaseErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("%s is not ready yet; wait for file.updated SSE event", fieldOrDefault(resolveErr.FileField, "file_id")),
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/" + fieldOrDefault(resolveErr.FileField, "file_id")},
+			}})
+			return nil, true
+		case attachmentresolver.ErrorFileManagerUnavailable:
+			_ = writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  errorTitle,
+				Detail: resolveErr.Error(),
+			}})
+			return nil, true
+		}
+	}
+
+	_ = writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+		Status: "400",
+		Title:  errorTitle,
+		Detail: safeInternalDetail(),
+	}})
+	return nil, true
+}
+
+func parseBaseShiftRange(
+	startRaw *string,
+	endRaw *string,
+	legacyRaw *string,
+	startPointer string,
+	endPointer string,
+	legacyPointer string,
+) (*time.Time, *time.Time, *jsonapi.ErrorObject) {
+	start, errObj := parseOptionalClock(startRaw, startPointer)
+	if errObj != nil {
+		return nil, nil, errObj
+	}
+	end, errObj := parseOptionalClock(endRaw, endPointer)
+	if errObj != nil {
+		return nil, nil, errObj
+	}
+	if legacyRaw == nil {
+		return start, end, nil
+	}
+
+	legacy := strings.TrimSpace(*legacyRaw)
+	if legacy == "" {
+		return start, end, nil
+	}
+	legacyStartRaw, legacyEndRaw := extractBaseShiftRangeTokens(legacy)
+	if legacyStartRaw == "" && legacyEndRaw == "" {
+		return nil, nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "default_shift_time must contain HH:MM or HH:MM:SS range",
+			Source: &jsonapi.ErrorSource{Pointer: legacyPointer},
+		}
+	}
+	if startRaw == nil && legacyStartRaw != "" {
+		start, errObj = parseOptionalClock(&legacyStartRaw, legacyPointer)
+		if errObj != nil {
+			return nil, nil, errObj
+		}
+	}
+	if endRaw == nil && legacyEndRaw != "" {
+		end, errObj = parseOptionalClock(&legacyEndRaw, legacyPointer)
+		if errObj != nil {
+			return nil, nil, errObj
+		}
+	}
+	return start, end, nil
+}
+
+func parseBaseDefaultShiftRange(
+	startRaw *string,
+	endRaw *string,
+	legacyRaw *string,
+	startTimeType string,
+	endTimeType string,
+	requireFixedTimes bool,
+	startPointer string,
+	endPointer string,
+	legacyPointer string,
+) (*time.Time, *time.Time, *jsonapi.ErrorObject) {
+	start, end, errObj := parseBaseShiftRange(startRaw, endRaw, legacyRaw, startPointer, endPointer, legacyPointer)
+	if errObj != nil {
+		return nil, nil, errObj
+	}
+	startTimeType = normalizeBaseShiftTimeTypeOrFixed(startTimeType)
+	endTimeType = normalizeBaseShiftTimeTypeOrFixed(endTimeType)
+	if requireFixedTimes && startTimeType == base.ShiftTimeTypeFixed && start == nil {
+		return nil, nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "default_shift_start is required when default_start_time_type is FIXED",
+			Source: &jsonapi.ErrorSource{Pointer: startPointer},
+		}
+	}
+	if requireFixedTimes && endTimeType == base.ShiftTimeTypeFixed && end == nil {
+		return nil, nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "default_shift_end is required when default_end_time_type is FIXED",
+			Source: &jsonapi.ErrorSource{Pointer: endPointer},
+		}
+	}
+	if start != nil && end != nil && start.After(*end) {
+		return nil, nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "default_shift_start must be earlier than default_shift_end",
+			Source: &jsonapi.ErrorSource{Pointer: legacyPointer},
+		}
+	}
+	if startTimeType != base.ShiftTimeTypeFixed {
+		start = nil
+	}
+	if endTimeType != base.ShiftTimeTypeFixed {
+		end = nil
+	}
+	return start, end, nil
+}
+
+func parseBaseOperationalShiftTimes(items []dto.BaseOperationalShiftTime, basePointer string) ([]appservice.BaseOperationalShiftTimeInput, *jsonapi.ErrorObject) {
+	if len(items) == 0 {
+		return nil, nil
+	}
+	out := make([]appservice.BaseOperationalShiftTimeInput, 0, len(items))
+	for i := range items {
+		idxPointer := fmt.Sprintf("%s/%d", basePointer, i)
+		startRaw := strings.TrimSpace(items[i].DateStart)
+		endRaw := strings.TrimSpace(items[i].DateEnd)
+		if startRaw == "" || endRaw == "" {
+			return nil, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "date_start and date_end are required",
+				Source: &jsonapi.ErrorSource{Pointer: idxPointer + "/date_start"},
+			}
+		}
+		dateStart, err := time.Parse("2006-01-02", startRaw)
+		if err != nil {
+			return nil, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "date_start must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: idxPointer + "/date_start"},
+			}
+		}
+		dateEnd, err := time.Parse("2006-01-02", endRaw)
+		if err != nil {
+			return nil, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "date_end must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: idxPointer + "/date_end"},
+			}
+		}
+		if dateEnd.Before(dateStart) {
+			return nil, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "date_end must be >= date_start",
+				Source: &jsonapi.ErrorSource{Pointer: idxPointer + "/date_end"},
+			}
+		}
+		shiftStartRaw := strings.TrimSpace(items[i].ShiftTime.Start)
+		shiftEndRaw := strings.TrimSpace(items[i].ShiftTime.End)
+		startTimeType, errObj := normalizeBaseShiftTimeType(items[i].StartTimeType, idxPointer+"/start_time_type")
+		if errObj != nil {
+			return nil, errObj
+		}
+		endTimeType, errObj := normalizeBaseShiftTimeType(items[i].EndTimeType, idxPointer+"/end_time_type")
+		if errObj != nil {
+			return nil, errObj
+		}
+		if startTimeType == base.ShiftTimeTypeFixed && shiftStartRaw == "" {
+			return nil, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "shift_time.start is required when start_time_type is FIXED",
+				Source: &jsonapi.ErrorSource{Pointer: idxPointer + "/shift_time/start"},
+			}
+		}
+		if endTimeType == base.ShiftTimeTypeFixed && shiftEndRaw == "" {
+			return nil, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "shift_time.end is required when end_time_type is FIXED",
+				Source: &jsonapi.ErrorSource{Pointer: idxPointer + "/shift_time/end"},
+			}
+		}
+		var start *time.Time
+		var end *time.Time
+		var clockErr *jsonapi.ErrorObject
+		if shiftStartRaw != "" {
+			start, clockErr = parseOptionalClock(&shiftStartRaw, idxPointer+"/shift_time/start")
+			if clockErr != nil {
+				return nil, clockErr
+			}
+		}
+		if shiftEndRaw != "" {
+			end, clockErr = parseOptionalClock(&shiftEndRaw, idxPointer+"/shift_time/end")
+			if clockErr != nil {
+				return nil, clockErr
+			}
+		}
+		if start != nil && end != nil && start.After(*end) {
+			return nil, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "shift_time.start must be earlier than shift_time.end",
+				Source: &jsonapi.ErrorSource{Pointer: idxPointer + "/shift_time"},
+			}
+		}
+		out = append(out, appservice.BaseOperationalShiftTimeInput{
+			DateStart:     dateStart.UTC(),
+			DateEnd:       dateEnd.UTC(),
+			StartTimeType: startTimeType,
+			EndTimeType:   endTimeType,
+			ShiftStart:    start,
+			ShiftEnd:      end,
+		})
+	}
+	return out, nil
+}
+
+func validateBaseCoordinates(lat, lon *float64, latPointer, lonPointer string) *jsonapi.ErrorObject {
+	if lat == nil || lon == nil {
+		return &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "latitude and longitude are required",
+			Source: &jsonapi.ErrorSource{Pointer: latPointer},
+		}
+	}
+	if errObj := validateCoordinateRange(*lat, -90, 90, "latitude", latPointer); errObj != nil {
+		return errObj
+	}
+	if errObj := validateCoordinateRange(*lon, -180, 180, "longitude", lonPointer); errObj != nil {
+		return errObj
+	}
+	return nil
+}
+
+func validateOptionalBaseCoordinates(lat, lon *float64, latPointer, lonPointer string) *jsonapi.ErrorObject {
+	if lat == nil && lon == nil {
+		return nil
+	}
+	if lat == nil || lon == nil {
+		pointer := latPointer
+		if lat == nil {
+			pointer = latPointer
+		} else {
+			pointer = lonPointer
+		}
+		return &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "latitude and longitude must be provided together",
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	if errObj := validateCoordinateRange(*lat, -90, 90, "latitude", latPointer); errObj != nil {
+		return errObj
+	}
+	if errObj := validateCoordinateRange(*lon, -180, 180, "longitude", lonPointer); errObj != nil {
+		return errObj
+	}
+	return nil
+}
+
+func validateCoordinateRange(value, min, max float64, label, pointer string) *jsonapi.ErrorObject {
+	if math.IsNaN(value) || value < min || value > max {
+		return &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: fmt.Sprintf("%s must be between %.0f and %.0f", label, min, max),
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	return nil
+}
+
+func extractBaseShiftTimeFromUpdateBody(body []byte) *dto.BaseShiftTime {
+	var payload struct {
+		Data struct {
+			Attributes struct {
+				ShiftTime *dto.BaseShiftTime `json:"shift_time"`
+			} `json:"attributes"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		return nil
+	}
+	return payload.Data.Attributes.ShiftTime
+}
+
+func parseOptionalClock(v *string, pointer string) (*time.Time, *jsonapi.ErrorObject) {
+	if v == nil {
+		return nil, nil
+	}
+	s := strings.TrimSpace(*v)
+	if s == "" {
+		return nil, nil
+	}
+	if len(s) == 5 {
+		s += ":00"
+	}
+	parsed, err := time.Parse("15:04:05", s)
+	if err != nil {
+		return nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "time must be HH:MM or HH:MM:SS",
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	val := time.Date(2000, 1, 1, parsed.Hour(), parsed.Minute(), parsed.Second(), 0, time.UTC)
+	return &val, nil
+}
+
+func normalizeBaseShiftTimeType(raw string, pointer string) (string, *jsonapi.ErrorObject) {
+	switch strings.ToUpper(strings.TrimSpace(raw)) {
+	case "", base.ShiftTimeTypeFixed:
+		return base.ShiftTimeTypeFixed, nil
+	case base.ShiftTimeTypeBMCT:
+		return base.ShiftTimeTypeBMCT, nil
+	case base.ShiftTimeTypeECET:
+		return base.ShiftTimeTypeECET, nil
+	default:
+		return "", &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "start_time_type and end_time_type must be FIXED, BMCT, or ECET",
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+}
+
+func normalizeBaseShiftTimeTypeOrFixed(raw string) string {
+	value, errObj := normalizeBaseShiftTimeType(raw, "")
+	if errObj != nil {
+		return strings.ToUpper(strings.TrimSpace(raw))
+	}
+	return value
+}
+
+func float64OrDefault(v *float64, d float64) float64 {
+	if v == nil {
+		return d
+	}
+	return *v
+}
+
+func extractBaseShiftRangeTokens(raw string) (string, string) {
+	tokens := extractBaseShiftClockTokens(raw)
+	if len(tokens) == 0 {
+		return "", ""
+	}
+	if len(tokens) == 1 {
+		return tokens[0], tokens[0]
+	}
+	return tokens[0], tokens[1]
+}
+
+func extractBaseShiftClockTokens(raw string) []string {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return nil
+	}
+	out := make([]string, 0, 2)
+	for i := 0; i < len(s) && len(out) < 2; i++ {
+		if i+5 > len(s) || !isDigitBaseClock(s[i]) || !isDigitBaseClock(s[i+1]) || s[i+2] != ':' || !isDigitBaseClock(s[i+3]) || !isDigitBaseClock(s[i+4]) {
+			continue
+		}
+		token := s[i : i+5]
+		if i+8 <= len(s) && s[i+5] == ':' && isDigitBaseClock(s[i+6]) && isDigitBaseClock(s[i+7]) {
+			token = s[i : i+8]
+		}
+		out = append(out, token)
+	}
+	return out
+}
+
+func isDigitBaseClock(b byte) bool {
+	return b >= '0' && b <= '9'
+}
+
+func clockStringOrEmpty(v any) string {
+	switch t := v.(type) {
+	case nil:
+		return ""
+	case string:
+		return normalizeBaseShiftDisplay(t)
+	case *time.Time:
+		if t == nil {
+			return ""
+		}
+		return normalizeBaseShiftDisplay(t.Format("15:04:05"))
+	default:
+		return ""
+	}
+}
+
+func normalizeBaseShiftDisplay(raw string) string {
+	s := strings.TrimSpace(raw)
+	if len(s) >= 5 && isDigitBaseClock(s[0]) && isDigitBaseClock(s[1]) && s[2] == ':' && isDigitBaseClock(s[3]) && isDigitBaseClock(s[4]) {
+		return s[:5]
+	}
+	return s
+}
+
+func baseCategoryFromRowOrType(row *base.Base, categoryType string) string {
+	if row != nil {
+		key := strings.TrimSpace(row.BaseCategory.Key)
+		if key != "" {
+			if fromRelation, ok := base.NormalizeCategoryType(key); ok {
+				return fromRelation
+			}
+		}
+	}
+	if fromType, ok := base.NormalizeCategoryType(categoryType); ok {
+		return fromType
+	}
+	return base.CategoryKeyRegular
+}
+
+func parseBaseCategoryTypeQuery(c *fiber.Ctx) (string, *jsonapi.ErrorObject) {
+	raw := baseCategoryQueryValue(c)
+	categoryType, ok := base.NormalizeCategoryType(raw)
+	if !ok {
+		return "", &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "category_type/base_category must be one of: regular, hems",
+			Source: &jsonapi.ErrorSource{Pointer: "/query/category_type"},
+		}
+	}
+	return categoryType, nil
+}
+
+func parseOptionalBaseCategoryTypeQuery(c *fiber.Ctx) (string, *jsonapi.ErrorObject) {
+	raw := baseCategoryQueryValue(c)
+	if raw == "" {
+		return "", nil
+	}
+	categoryType, ok := base.NormalizeCategoryType(raw)
+	if !ok {
+		return "", &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "category_type/base_category must be one of: regular, hems",
+			Source: &jsonapi.ErrorSource{Pointer: "/query/category_type"},
+		}
+	}
+	return categoryType, nil
+}
+
+func parseOptionalBoolQueryParam(c *fiber.Ctx, queryKey string) (*bool, *jsonapi.ErrorObject) {
+	raw := strings.TrimSpace(c.Query(queryKey))
+	if raw == "" {
+		return nil, nil
+	}
+	switch strings.ToLower(raw) {
+	case "true", "1":
+		v := true
+		return &v, nil
+	case "false", "0":
+		v := false
+		return &v, nil
+	default:
+		return nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: queryKey + " must be true or false",
+			Source: &jsonapi.ErrorSource{Pointer: "/query/" + queryKey},
+		}
+	}
+}
+
+func baseCategoryQueryValue(c *fiber.Ctx) string {
+	raw := strings.TrimSpace(c.Query("category_type"))
+	if raw == "" {
+		raw = strings.TrimSpace(c.Query("base_category"))
+	}
+	if raw == "" {
+		raw = strings.TrimSpace(c.Query("category"))
+	}
+	return raw
+}
+
+func resolveBaseCategoryType(c *fiber.Ctx, bodyCategory *string, pointer string) (string, *jsonapi.ErrorObject) {
+	if bodyCategory != nil {
+		categoryType, ok := base.NormalizeCategoryType(*bodyCategory)
+		if !ok {
+			return "", &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "base_category must be one of: regular, hems",
+				Source: &jsonapi.ErrorSource{Pointer: pointer},
+			}
+		}
+		return categoryType, nil
+	}
+	return parseBaseCategoryTypeQuery(c)
+}
+
+func categoryNotFoundDetail(categoryType string) string {
+	if categoryType == base.CategoryKeyHEMS {
+		return "hems base not found"
+	}
+	return "base not found"
+}
+
+func parseOptionalUUID(v *string, pointer string) ([]byte, *jsonapi.ErrorObject) {
+	if v == nil {
+		return nil, nil
+	}
+	s := strings.TrimSpace(*v)
+	if s == "" {
+		return nil, nil
+	}
+	parsed, err := uuidv7.ParseString(s)
+	if err != nil {
+		return nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	return parsed, nil
+}
+
+func parseUUIDOrClear(v string, pointer string) ([]byte, *jsonapi.ErrorObject) {
+	s := strings.TrimSpace(v)
+	if s == "" {
+		return nil, nil
+	}
+	parsed, err := uuidv7.ParseString(s)
+	if err != nil {
+		return nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	return parsed, nil
+}
+
+func bytesUUIDToString(raw []byte) string {
+	if len(raw) == 0 {
+		return ""
+	}
+	if name := userctx.GetDisplayName(context.TODO(), raw); name != "" {
+		return name
+	}
+	s, err := uuidv7.BytesToString(raw)
+	if err != nil {
+		return ""
+	}
+	return s
+}
+
+func writeBaseErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	statusStr := strconv.Itoa(status)
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferBaseDef(status, e.Title, e.Detail)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		if strings.TrimSpace(e.Title) == "" {
+			e.Title = def.Title
+		}
+		if e.Source != nil && shouldPreserveBaseDetail(e.Source.Pointer) {
+			if strings.TrimSpace(e.Detail) == "" {
+				e.Detail = def.Message
+			}
+		} else {
+			e.Detail = def.Message
+		}
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func shouldPreserveBaseDetail(pointer string) bool {
+	lowerPointer := strings.ToLower(strings.TrimSpace(pointer))
+	return strings.Contains(lowerPointer, "operational_shift_times") ||
+		strings.Contains(lowerPointer, "latitude") ||
+		strings.Contains(lowerPointer, "longitude") ||
+		strings.Contains(lowerPointer, "twilight") ||
+		strings.Contains(lowerPointer, "shift_time")
+}
+
+func inferBaseDef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.ErrBaseNotFound
+	case fiber.StatusConflict:
+		return apperrorsx.ErrBaseRelationDelete
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid uuid"), strings.Contains(lowerDetail, "invalid uuid"):
+			return apperrorsx.ErrBaseInvalidUUID
+		case strings.Contains(lowerDetail, "base_category must be one of"),
+			strings.Contains(lowerDetail, "category_type/base_category must be one of"):
+			return apperrorsx.ErrBaseInvalidCategory
+		case strings.Contains(lowerDetail, "at least one attribute must be provided"):
+			return apperrorsx.ErrBaseAttributesRequired
+		case strings.Contains(lowerDetail, "base is required"), strings.Contains(lowerDetail, "base cannot be empty"):
+			return apperrorsx.ErrBaseNameRequired
+		case strings.Contains(lowerDetail, "default_shift_start is required"):
+			return apperrorsx.ErrBaseDefaultShiftStartRequired
+		case strings.Contains(lowerDetail, "default_shift_end is required"):
+			return apperrorsx.ErrBaseDefaultShiftEndRequired
+		case strings.Contains(lowerDetail, "time must be"), strings.Contains(lowerDetail, "default_shift_time must contain"):
+			return apperrorsx.ErrBaseInvalidTime
+		case strings.Contains(lowerDetail, "contact id"), strings.Contains(lowerDetail, "value is invalid uuid"):
+			return apperrorsx.ErrBaseInvalidContactIDs
+		case strings.Contains(lowerDetail, "shift_time.start must be earlier than shift_time.end"),
+			strings.Contains(lowerDetail, "shift_time.start is required when start_time_type is fixed"),
+			strings.Contains(lowerDetail, "shift_time.end is required when end_time_type is fixed"),
+			strings.Contains(lowerDetail, "latitude"),
+			strings.Contains(lowerDetail, "longitude"),
+			strings.Contains(lowerDetail, "coordinates"),
+			strings.Contains(lowerDetail, "twilight"):
+			def := apperrorsx.ErrBaseInvalidPayload
+			def.Message = detail
+			return def
+		default:
+			return apperrorsx.ErrBaseInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrBaseInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.ErrBaseCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrBaseUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrBaseDeleteFailed
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.ErrBaseListFailed
+		default:
+			return apperrorsx.ErrBaseInvalidPayload
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
+
+func inferBaseErrorCode(status int, title, detail string) (string, string) {
+	def := inferBaseDef(status, title, detail)
+	return def.Code, def.ErrorCode
+}
diff --git a/internal/transport/http/handlers/base_handler_test.go b/internal/transport/http/handlers/base_handler_test.go
new file mode 100644
index 0000000..07c21ad
--- /dev/null
+++ b/internal/transport/http/handlers/base_handler_test.go
@@ -0,0 +1,999 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"github.com/valyala/fasthttp"
+
+	"wucher/internal/domain/base"
+	filemanager "wucher/internal/domain/file_manager"
+	filemanagerrealtime "wucher/internal/realtime/filemanager"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/shared/pkg/attachmentresolver"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/jsonapi"
+)
+
+var (
+	testBaseShiftStart = "06:00:00"
+	testBaseShiftEnd   = "21:00:00"
+)
+
+type memBaseRepo struct {
+	rows map[string]map[string]*base.Base
+
+	createBaseErr  error
+	updateBaseErr  error
+	deleteBaseErr  error
+	getBaseByIDErr error
+	listBasesErr   error
+
+	listRows  []base.Base
+	listTotal int64
+
+	lastCreateBase     *base.Base
+	lastCreateCategory string
+	lastUpdateBase     *base.Base
+	lastUpdateCategory string
+	lastDeleteID       []byte
+	lastDeleteCategory string
+	lastGetID          []byte
+	lastGetCategory    string
+	lastListFilter     string
+	lastListSort       string
+	lastListLimit      int
+	lastListOffset     int
+	lastListCategory   string
+	lastListDUL        *bool
+}
+
+type basePresignStorageMock struct {
+	url string
+	err error
+}
+
+func (m *basePresignStorageMock) PresignGetObject(_ context.Context, _ string, _ time.Duration) (string, error) {
+	if m.err != nil {
+		return "", m.err
+	}
+	return m.url, nil
+}
+
+func newMemBaseRepo() *memBaseRepo {
+	return &memBaseRepo{
+		rows: map[string]map[string]*base.Base{
+			base.CategoryKeyRegular: {},
+			base.CategoryKeyHEMS:    {},
+		},
+	}
+}
+
+func (r *memBaseRepo) CreateBase(_ context.Context, row *base.Base, categoryType string) error {
+	if r.createBaseErr != nil {
+		return r.createBaseErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.lastCreateBase = row
+	r.lastCreateCategory = categoryType
+	if _, ok := r.rows[categoryType]; !ok {
+		r.rows[categoryType] = map[string]*base.Base{}
+	}
+	r.rows[categoryType][string(row.ID)] = row
+	return nil
+}
+
+func (r *memBaseRepo) UpdateBase(_ context.Context, row *base.Base, categoryType string) error {
+	if r.updateBaseErr != nil {
+		return r.updateBaseErr
+	}
+	r.lastUpdateBase = row
+	r.lastUpdateCategory = categoryType
+	if _, ok := r.rows[categoryType]; !ok {
+		r.rows[categoryType] = map[string]*base.Base{}
+	}
+	r.rows[categoryType][string(row.ID)] = row
+	return nil
+}
+
+func (r *memBaseRepo) DeleteBase(_ context.Context, id []byte, categoryType string) error {
+	if r.deleteBaseErr != nil {
+		return r.deleteBaseErr
+	}
+	r.lastDeleteID = append([]byte(nil), id...)
+	r.lastDeleteCategory = categoryType
+	if m, ok := r.rows[categoryType]; ok {
+		delete(m, string(id))
+	}
+	return nil
+}
+
+func (r *memBaseRepo) GetBaseByID(_ context.Context, id []byte, categoryType string) (*base.Base, error) {
+	if r.getBaseByIDErr != nil {
+		return nil, r.getBaseByIDErr
+	}
+	r.lastGetID = append([]byte(nil), id...)
+	r.lastGetCategory = categoryType
+	if m, ok := r.rows[categoryType]; ok {
+		return m[string(id)], nil
+	}
+	return nil, nil
+}
+
+func (r *memBaseRepo) ListBases(_ context.Context, filter, sort string, limit, offset int, categoryType string, dul *bool) ([]base.Base, int64, error) {
+	if r.listBasesErr != nil {
+		return nil, 0, r.listBasesErr
+	}
+	r.lastListFilter = filter
+	r.lastListSort = sort
+	r.lastListLimit = limit
+	r.lastListOffset = offset
+	r.lastListCategory = categoryType
+	r.lastListDUL = dul
+	if r.listRows != nil {
+		return r.listRows, r.listTotal, nil
+	}
+	out := make([]base.Base, 0)
+	for _, row := range r.rows[categoryType] {
+		out = append(out, *row)
+	}
+	return out, int64(len(out)), nil
+}
+
+func newBaseTestApp(h *BaseHandler) *fiber.App {
+	app := fiber.New()
+	app.Post("/api/v1/bases/create", h.CreateBase)
+	app.Patch("/api/v1/bases/update/:uuid", h.UpdateBase)
+	app.Delete("/api/v1/bases/delete/:uuid", h.DeleteBase)
+	app.Get("/api/v1/bases/get/:uuid", h.GetBase)
+	app.Get("/api/v1/bases/get-all", h.ListBases)
+	app.Get("/api/v1/bases/get-all/dt", h.ListBasesDatatable)
+	return app
+}
+
+func newBaseEventsTestApp(h *FileManagerEventsHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if actor != nil {
+			c.Locals("user_id", append([]byte(nil), actor...))
+		}
+		return c.Next()
+	})
+	app.Get("/api/v1/bases/events", h.Stream)
+	return app
+}
+
+func doJSONRequestBase(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDStringBase(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestNewBaseHandler(t *testing.T) {
+	h := NewBaseHandler(service.NewBaseService(newMemBaseRepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+	h = h.WithFileManagerService(nil)
+	h = h.WithFileResolver(nil, nil)
+	if h == nil {
+		t.Fatalf("expected chain methods return handler")
+	}
+}
+
+func TestBaseHandlerCreateBase(t *testing.T) {
+	t.Run("invalid category", func(t *testing.T) {
+		repo := newMemBaseRepo()
+		h := NewBaseHandler(service.NewBaseService(repo))
+		app := newBaseTestApp(h)
+
+		resp, _ := doJSONRequestBase(t, app, http.MethodPost, "/api/v1/bases/create?category_type=oops", []byte(`{"data":{"type":"base","attributes":{"base":"A","latitude":47.3769,"longitude":8.5417}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("missing coordinates", func(t *testing.T) {
+		repo := newMemBaseRepo()
+		h := NewBaseHandler(service.NewBaseService(repo))
+		app := newBaseTestApp(h)
+
+		resp, _ := doJSONRequestBase(t, app, http.MethodPost, "/api/v1/bases/create", []byte(`{"data":{"type":"base","attributes":{"base":"No coords"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid coordinates", func(t *testing.T) {
+		repo := newMemBaseRepo()
+		h := NewBaseHandler(service.NewBaseService(repo))
+		app := newBaseTestApp(h)
+
+		resp, _ := doJSONRequestBase(t, app, http.MethodPost, "/api/v1/bases/create", []byte(`{"data":{"type":"base","attributes":{"base":"Bad coords","latitude":91,"longitude":181}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("regular success", func(t *testing.T) {
+		repo := newMemBaseRepo()
+		h := NewBaseHandler(service.NewBaseService(repo))
+		app := newBaseTestApp(h)
+
+		resp, body := doJSONRequestBase(t, app, http.MethodPost, "/api/v1/bases/create", []byte(`{"data":{"type":"base","attributes":{"base":"Regular A","latitude":47.3769,"longitude":8.5417,"default_shift_start":"`+testBaseShiftStart+`","default_shift_end":"`+testBaseShiftEnd+`","sortkey":3,"notes":"Primary note","is_active":false}}}`))
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreateCategory != base.CategoryKeyRegular {
+			t.Fatalf("expected regular category, got %q", repo.lastCreateCategory)
+		}
+		if repo.lastCreateBase == nil || repo.lastCreateBase.SortKey == nil || *repo.lastCreateBase.SortKey != 3 {
+			t.Fatalf("expected sortkey mapped on create")
+		}
+		if repo.lastCreateBase.Notes != "Primary note" || repo.lastCreateBase.IsActive {
+			t.Fatalf("expected notes/is_active mapped on create")
+		}
+		if !bytes.Contains(body, []byte(`"type":"base"`)) {
+			t.Fatalf("expected base resource type, body=%s", string(body))
+		}
+	})
+
+	t.Run("operational shift times success", func(t *testing.T) {
+		repo := newMemBaseRepo()
+		h := NewBaseHandler(service.NewBaseService(repo))
+		app := newBaseTestApp(h)
+
+		resp, body := doJSONRequestBase(t, app, http.MethodPost, "/api/v1/bases/create", []byte(`{"data":{"type":"base","attributes":{"base":"Base with ops","latitude":47.3769,"longitude":8.5417,"default_shift_start":"`+testBaseShiftStart+`","default_shift_end":"`+testBaseShiftEnd+`","operational_shift_times":[{"date_start":"2026-04-12","date_end":"2026-04-12","shift_time":{"start":"09:00","end":"18:00"}},{"date_start":"2026-04-13","date_end":"2026-04-13","shift_time":{"start":"09:00","end":"17:00"}}]}}}`))
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreateBase == nil || len(repo.lastCreateBase.OperationalShiftTimes) != 2 {
+			t.Fatalf("expected operational shift times mapped on create")
+		}
+		if got := repo.lastCreateBase.OperationalShiftTimes[1].DateStart.Format("2006-01-02"); got != "2026-04-13" {
+			t.Fatalf("unexpected operational shift date start: %s", got)
+		}
+		if got := repo.lastCreateBase.OperationalShiftTimes[1].DateEnd.Format("2006-01-02"); got != "2026-04-13" {
+			t.Fatalf("unexpected operational shift date end: %s", got)
+		}
+		if repo.lastCreateBase.OperationalShiftTimes[0].ShiftStart != "09:00:00" || repo.lastCreateBase.OperationalShiftTimes[1].ShiftEnd != "17:00:00" {
+			t.Fatalf("expected both operational shift times mapped on create, got %#v", repo.lastCreateBase.OperationalShiftTimes)
+		}
+		if !bytes.Contains(body, []byte(`"date_start":"2026-04-12"`)) || !bytes.Contains(body, []byte(`"date_end":"2026-04-12"`)) || !bytes.Contains(body, []byte(`"date_start":"2026-04-13"`)) || !bytes.Contains(body, []byte(`"date_end":"2026-04-13"`)) {
+			t.Fatalf("expected operational shift dates in response, body=%s", string(body))
+		}
+		if !bytes.Contains(body, []byte(`"operational_shift_times":[`)) {
+			t.Fatalf("expected operational_shift_times in response, body=%s", string(body))
+		}
+	})
+
+	t.Run("operational shift times fixed response includes values", func(t *testing.T) {
+		repo := newMemBaseRepo()
+		h := NewBaseHandler(service.NewBaseService(repo))
+		app := newBaseTestApp(h)
+
+		resp, body := doJSONRequestBase(t, app, http.MethodPost, "/api/v1/bases/create", []byte(`{"data":{"type":"base","attributes":{"base":"Base with fixed ops","latitude":47.3769,"longitude":8.5417,"default_shift_start":"`+testBaseShiftStart+`","default_shift_end":"`+testBaseShiftEnd+`","operational_shift_times":[{"date_start":"2026-06-03","date_end":"2026-06-04","start_time_type":"FIXED","end_time_type":"FIXED","shift_time":{"start":"03:00","end":"05:00"}}]}}}`))
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if !bytes.Contains(body, []byte(`"shift_time":{"start":"03:00","end":"05:00"}`)) {
+			t.Fatalf("expected fixed operational shift_time values in response, body=%s", string(body))
+		}
+	})
+
+	t.Run("operational shift times invalid order", func(t *testing.T) {
+		repo := newMemBaseRepo()
+		h := NewBaseHandler(service.NewBaseService(repo))
+		app := newBaseTestApp(h)
+
+		resp, body := doJSONRequestBase(t, app, http.MethodPost, "/api/v1/bases/create", []byte(`{"data":{"type":"base","attributes":{"base":"Base with bad ops","latitude":47.3769,"longitude":8.5417,"default_shift_start":"`+testBaseShiftStart+`","default_shift_end":"`+testBaseShiftEnd+`","operational_shift_times":[{"date_start":"2026-04-12","date_end":"2026-04-12","shift_time":{"start":"18:00","end":"09:00"}}]}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+		if !bytes.Contains(body, []byte(`shift_time.start must be earlier than shift_time.end`)) {
+			t.Fatalf("expected shift order validation error, body=%s", string(body))
+		}
+		if repo.lastCreateBase != nil {
+			t.Fatalf("expected create not to reach repo on invalid shift order")
+		}
+	})
+
+	t.Run("hems success", func(t *testing.T) {
+		repo := newMemBaseRepo()
+		h := NewBaseHandler(service.NewBaseService(repo))
+		app := newBaseTestApp(h)
+
+		resp, body := doJSONRequestBase(t, app, http.MethodPost, "/api/v1/bases/create?category_type=hems", []byte(`{"data":{"type":"hems_base","attributes":{"base":"HEMS A","latitude":47.3769,"longitude":8.5417,"default_shift_start":"`+testBaseShiftStart+`","default_shift_end":"`+testBaseShiftEnd+`"}}}`))
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreateCategory != base.CategoryKeyHEMS {
+			t.Fatalf("expected hems category, got %q", repo.lastCreateCategory)
+		}
+		if !bytes.Contains(body, []byte(`"type":"hems_base"`)) {
+			t.Fatalf("expected hems_base resource type, body=%s", string(body))
+		}
+	})
+
+	t.Run("hems success from body base_category without query", func(t *testing.T) {
+		repo := newMemBaseRepo()
+		h := NewBaseHandler(service.NewBaseService(repo))
+		app := newBaseTestApp(h)
+
+		resp, body := doJSONRequestBase(t, app, http.MethodPost, "/api/v1/bases/create", []byte(`{"data":{"type":"base","attributes":{"base":"HEMS from body","base_category":"hems","latitude":47.3769,"longitude":8.5417,"default_shift_start":"`+testBaseShiftStart+`","default_shift_end":"`+testBaseShiftEnd+`"}}}`))
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreateCategory != base.CategoryKeyHEMS {
+			t.Fatalf("expected hems category, got %q", repo.lastCreateCategory)
+		}
+		if !bytes.Contains(body, []byte(`"base_category":"hems"`)) {
+			t.Fatalf("expected base_category hems, body=%s", string(body))
+		}
+	})
+
+}
+
+func TestBaseHandlerGetBase(t *testing.T) {
+	repo := newMemBaseRepo()
+	hemsID := uuidv7.MustBytes()
+	fotoID := uuidv7.MustBytes()
+	repo.rows[base.CategoryKeyHEMS][string(hemsID)] = &base.Base{ID: hemsID, BaseName: "HEMS 1", FotoAttachmentID: fotoID, CreatedAt: time.Now(), UpdatedAt: time.Now()}
+	h := NewBaseHandler(service.NewBaseService(repo))
+	app := newBaseTestApp(h)
+
+	resp, body := doJSONRequestBase(t, app, http.MethodGet, "/api/v1/bases/get/"+mustUUIDStringBase(t, hemsID)+"?category_type=hems", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if repo.lastGetCategory != base.CategoryKeyHEMS {
+		t.Fatalf("expected hems category forwarded")
+	}
+	if !bytes.Contains(body, []byte(`"type":"hems_base"`)) {
+		t.Fatalf("expected hems_base type")
+	}
+	if !bytes.Contains(body, []byte(`"base_category":"hems"`)) {
+		t.Fatalf("expected base_category hems")
+	}
+	fotoIDStr, _ := uuidv7.BytesToString(fotoID)
+	bodyStr := string(body)
+	if !strings.Contains(bodyStr, `"uuid":"`+fotoIDStr+`"`) {
+		t.Fatalf("expected foto uuid when storage unavailable, body=%s", bodyStr)
+	}
+	if !strings.Contains(bodyStr, `"download_url":""`) {
+		t.Fatalf("expected empty download_url when storage unavailable, body=%s", bodyStr)
+	}
+}
+
+func TestBaseHelperFunctions(t *testing.T) {
+	t.Run("cloneIntPointerBase and preferStringPtr", func(t *testing.T) {
+		v := 7
+		cp := cloneIntPointerBase(&v)
+		if cp == nil || *cp != 7 || cp == &v {
+			t.Fatalf("cloneIntPointerBase invalid clone")
+		}
+		if cloneIntPointerBase(nil) != nil {
+			t.Fatalf("expected nil clone for nil input")
+		}
+		a, b := "a", "b"
+		if got := preferStringPtr(&a, &b); got == nil || *got != "a" {
+			t.Fatalf("preferStringPtr should prioritize primary")
+		}
+		if got := preferStringPtr(nil, &b); got == nil || *got != "b" {
+			t.Fatalf("preferStringPtr should use fallback")
+		}
+	})
+
+	t.Run("parseUUIDList and uuidListToStrings", func(t *testing.T) {
+		id1 := mustUUIDStringBase(t, uuidv7.MustBytes())
+		id2 := mustUUIDStringBase(t, uuidv7.MustBytes())
+		got, errObj := parseUUIDList([]string{" ", id1, id1, id2}, "/x")
+		if errObj != nil || len(got) != 2 {
+			t.Fatalf("expected deduped parsed ids, got len=%d err=%v", len(got), errObj)
+		}
+		if _, errObj = parseUUIDList([]string{"not-uuid"}, "/x"); errObj == nil {
+			t.Fatalf("expected validation error for invalid uuid")
+		}
+		strs := uuidListToStrings(got)
+		if len(strs) != 2 {
+			t.Fatalf("uuidListToStrings expected 2 got %d", len(strs))
+		}
+		if uuidListToStrings(nil) != nil {
+			t.Fatalf("uuidListToStrings nil input should be nil")
+		}
+	})
+
+	t.Run("baseContactResources", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		rows := []base.BaseContactPerson{
+			{ContactID: id, FirstName: "A", LastName: "B"},
+			{ContactID: []byte{1, 2}, FirstName: "X"},
+		}
+		out := baseContactResources(rows)
+		if len(out) != 1 || out[0].FirstName != "A" {
+			t.Fatalf("expected single valid contact resource")
+		}
+		if baseContactResources(nil) != nil {
+			t.Fatalf("nil input should return nil")
+		}
+	})
+
+	t.Run("shift parsing helpers", func(t *testing.T) {
+		startRaw := "07:30"
+		endRaw := "16:45:30"
+		start, end, errObj := parseBaseShiftRange(&startRaw, &endRaw, nil, "/s", "/e", "/l")
+		if errObj != nil || start == nil || end == nil {
+			t.Fatalf("expected valid shift parse")
+		}
+		legacy := "09:00-18:00"
+		start, end, errObj = parseBaseShiftRange(nil, nil, &legacy, "/s", "/e", "/l")
+		if errObj != nil || start == nil || end == nil || start.Format("15:04") != "09:00" {
+			t.Fatalf("expected legacy shift parse")
+		}
+		bad := "invalid"
+		_, _, errObj = parseBaseShiftRange(nil, nil, &bad, "/s", "/e", "/l")
+		if errObj == nil {
+			t.Fatalf("expected error for invalid legacy shift")
+		}
+		if tokens := extractBaseShiftClockTokens("x 01:02:03 y 14:15"); len(tokens) != 2 {
+			t.Fatalf("expected two extracted tokens")
+		}
+		a, b := extractBaseShiftRangeTokens("10:10")
+		if a != "10:10" || b != "10:10" {
+			t.Fatalf("single token should duplicate")
+		}
+	})
+
+	t.Run("query and category helpers", func(t *testing.T) {
+		app := fiber.New()
+		ctx := app.AcquireCtx(&fasthttp.RequestCtx{})
+		defer app.ReleaseCtx(ctx)
+		ctx.Request().URI().SetQueryString("dul=true&category_type=hems")
+		dul, errObj := parseOptionalBoolQueryParam(ctx, "dul")
+		if errObj != nil || dul == nil || !*dul {
+			t.Fatalf("expected dul=true parsed")
+		}
+		ctx.Request().URI().SetQueryString("dul=oops")
+		if _, errObj = parseOptionalBoolQueryParam(ctx, "dul"); errObj == nil {
+			t.Fatalf("expected bool validation error")
+		}
+		ctx.Request().URI().SetQueryString("category=hems")
+		if got := baseCategoryQueryValue(ctx); got != "hems" {
+			t.Fatalf("expected category fallback value")
+		}
+		if categoryNotFoundDetail(base.CategoryKeyHEMS) != "hems base not found" {
+			t.Fatalf("unexpected category detail for hems")
+		}
+	})
+
+	t.Run("uuid parser and converter helpers", func(t *testing.T) {
+		idStr := mustUUIDStringBase(t, uuidv7.MustBytes())
+		if got, errObj := parseUUIDOrClear(idStr, "/p"); errObj != nil || len(got) != 16 {
+			t.Fatalf("parseUUIDOrClear should parse valid uuid")
+		}
+		if got, errObj := parseUUIDOrClear(" ", "/p"); errObj != nil || got != nil {
+			t.Fatalf("parseUUIDOrClear should clear blank")
+		}
+		if _, errObj := parseUUIDOrClear("bad", "/p"); errObj == nil {
+			t.Fatalf("expected parseUUIDOrClear error")
+		}
+		if bytesUUIDToString(nil) != "" {
+			t.Fatalf("empty bytes should return empty")
+		}
+		if bytesUUIDToString([]byte{1, 2}) != "" {
+			t.Fatalf("invalid bytes should return empty")
+		}
+	})
+
+	t.Run("inferBaseErrorCode branches", func(t *testing.T) {
+		cases := []struct {
+			status int
+			title  string
+			detail string
+		}{
+			{fiber.StatusNotFound, "", ""},
+			{fiber.StatusConflict, "", ""},
+			{fiber.StatusUnprocessableEntity, "Validation error", "invalid uuid"},
+			{fiber.StatusUnprocessableEntity, "Validation error", "category_type/base_category must be one of"},
+			{fiber.StatusUnprocessableEntity, "Validation error", "time must be HH:MM"},
+			{fiber.StatusBadRequest, "Invalid JSON", ""},
+			{fiber.StatusBadRequest, "Create failed", ""},
+			{fiber.StatusBadRequest, "Update failed", ""},
+			{fiber.StatusBadRequest, "Delete failed", ""},
+			{fiber.StatusBadRequest, "List failed", ""},
+			{fiber.StatusInternalServerError, "", ""},
+		}
+		for _, tc := range cases {
+			code, errCode := inferBaseErrorCode(tc.status, tc.title, tc.detail)
+			if strings.TrimSpace(code) == "" || strings.TrimSpace(errCode) == "" {
+				t.Fatalf("expected non-empty codes for status=%d title=%q", tc.status, tc.title)
+			}
+		}
+	})
+
+	t.Run("writeBaseErrors populates status and code", func(t *testing.T) {
+		app := fiber.New()
+		app.Get("/", func(c *fiber.Ctx) error {
+			return writeBaseErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Title: "Invalid JSON", Detail: "oops"}})
+		})
+		req := httptest.NewRequest(http.MethodGet, "/", nil)
+		resp, err := app.Test(req)
+		if err != nil || resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("writeBaseErrors failed err=%v status=%d", err, resp.StatusCode)
+		}
+	})
+
+	t.Run("base attachment resolver branches", func(t *testing.T) {
+		handler := NewBaseHandler(service.NewBaseService(newMemBaseRepo())).WithFileManagerService(&fileManagerAttachmentHandlerServiceMock{})
+		baseID := uuidv7.MustBytes()
+		app := fiber.New()
+		app.Get("/invalid-attachment", func(c *fiber.Ctx) error {
+			raw := "bad"
+			_, handled := handler.resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+				RawAttachmentID: &raw,
+				AttachmentField: "attachment_id",
+				FileField:       "file_uuid",
+			}, "Update failed")
+			if !handled {
+				t.Fatalf("expected handled for invalid attachment")
+			}
+			return nil
+		})
+		app.Get("/invalid-file", func(c *fiber.Ctx) error {
+			raw := "bad"
+			_, handled := handler.resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+				RawFileID:       &raw,
+				AttachmentField: "attachment_id",
+				FileField:       "file_uuid",
+				FileManager:     nil,
+			}, "Update failed")
+			if !handled {
+				t.Fatalf("expected handled for invalid file path")
+			}
+			return nil
+		})
+		app.Get("/require", func(c *fiber.Ctx) error {
+			_, handled := handler.resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+				RequireValue:    true,
+				AttachmentField: "attachment_id",
+				FileField:       "file_uuid",
+			}, "Update failed")
+			if !handled {
+				t.Fatalf("expected handled for require value")
+			}
+			return nil
+		})
+		app.Get("/not-found", func(c *fiber.Ctx) error {
+			id := mustUUIDStringBase(t, uuidv7.MustBytes())
+			_, handled := handler.resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+				RawAttachmentID:          &id,
+				AttachmentField:          "attachment_id",
+				FileField:                "file_uuid",
+				ValidateAttachmentExists: true,
+				AttachmentExists: func(context.Context, []byte) (bool, error) {
+					return false, nil
+				},
+			}, "Update failed")
+			if !handled {
+				t.Fatalf("expected handled for attachment not found")
+			}
+			return nil
+		})
+		app.Get("/existing-or-file", func(c *fiber.Ctx) error {
+			raw := mustUUIDStringBase(t, uuidv7.MustBytes())
+			mock := &fileManagerAttachmentHandlerServiceMock{
+				getAttachmentFn: func(context.Context, []byte) (*filemanager.Attachment, error) {
+					return &filemanager.Attachment{ID: uuidv7.MustBytes()}, nil
+				},
+			}
+			h2 := NewBaseHandler(service.NewBaseService(newMemBaseRepo())).WithFileManagerService(mock)
+			id, handled := h2.resolveExistingBaseFotoAttachmentOrFileID(c, baseID, &raw)
+			if handled || len(id) != 16 {
+				t.Fatalf("expected existing attachment id")
+			}
+			return nil
+		})
+		app.Get("/existing-error", func(c *fiber.Ctx) error {
+			raw := mustUUIDStringBase(t, uuidv7.MustBytes())
+			mock := &fileManagerAttachmentHandlerServiceMock{
+				getAttachmentFn: func(context.Context, []byte) (*filemanager.Attachment, error) {
+					return nil, errors.New("lookup failed")
+				},
+			}
+			h2 := NewBaseHandler(service.NewBaseService(newMemBaseRepo())).WithFileManagerService(mock)
+			_, handled := h2.resolveExistingBaseFotoAttachmentOrFileID(c, baseID, &raw)
+			if !handled {
+				t.Fatalf("expected handled error for existing attachment lookup")
+			}
+			return nil
+		})
+		app.Get("/resolve-base-foto", func(c *fiber.Ctx) error {
+			_, handled := handler.resolveBaseFotoAttachmentID(c, baseID, nil)
+			if handled {
+				t.Fatalf("nil raw should not be handled as error")
+			}
+			return nil
+		})
+
+		for _, path := range []string{"/invalid-attachment", "/invalid-file", "/require", "/not-found", "/existing-or-file", "/existing-error", "/resolve-base-foto"} {
+			req := httptest.NewRequest(http.MethodGet, path, nil)
+			resp, err := app.Test(req)
+			if err != nil {
+				t.Fatalf("request %s err=%v", path, err)
+			}
+			if path != "/existing-or-file" && path != "/resolve-base-foto" && resp.StatusCode == http.StatusOK {
+				t.Fatalf("expected error status for %s", path)
+			}
+		}
+	})
+}
+
+func TestBaseHandlerGetBase_UsesDirectPresignURLWhenStorageAvailable(t *testing.T) {
+	repo := newMemBaseRepo()
+	hemsID := uuidv7.MustBytes()
+	fotoID := uuidv7.MustBytes()
+	repo.rows[base.CategoryKeyHEMS][string(hemsID)] = &base.Base{
+		ID:               hemsID,
+		BaseName:         "HEMS 1",
+		FotoAttachmentID: fotoID,
+		FotoAttachment: &filemanager.Attachment{
+			ID:     fotoID,
+			FileID: uuidv7.MustBytes(),
+			File:   &filemanager.File{ID: uuidv7.MustBytes(), ObjectKey: "base/hems-1.jpg"},
+		},
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+	h := NewBaseHandler(service.NewBaseService(repo)).WithFileStorage(
+		&basePresignStorageMock{url: "https://signed.example/base/hems-1.jpg?sig=abc"},
+	)
+	app := newBaseTestApp(h)
+
+	resp, body := doJSONRequestBase(t, app, http.MethodGet, "/api/v1/bases/get/"+mustUUIDStringBase(t, hemsID)+"?category_type=hems", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if !bytes.Contains(body, []byte(`"download_url":"https://signed.example/base/hems-1.jpg?sig=abc"`)) {
+		t.Fatalf("expected direct presigned URL, body=%s", string(body))
+	}
+}
+
+func TestBaseHandlerUpdateDelete(t *testing.T) {
+	repo := newMemBaseRepo()
+	id := uuidv7.MustBytes()
+	repo.rows[base.CategoryKeyHEMS][string(id)] = &base.Base{ID: id, BaseName: "Old", DefaultShiftStart: "06:00:00", DefaultShiftEnd: "21:00:00", CreatedAt: time.Now(), UpdatedAt: time.Now()}
+	h := NewBaseHandler(service.NewBaseService(repo))
+	app := newBaseTestApp(h)
+	idStr := mustUUIDStringBase(t, id)
+
+	resp, _ := doJSONRequestBase(t, app, http.MethodPatch, "/api/v1/bases/update/"+idStr+"?category_type=hems", []byte(`{"data":{"type":"hems_base","id":"`+idStr+`","attributes":{"base":"New","latitude":47.3769,"longitude":8.5417}}}`))
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if repo.lastUpdateCategory != base.CategoryKeyHEMS {
+		t.Fatalf("expected hems category update")
+	}
+
+	fotoID := uuidv7.MustBytes()
+	repo.rows[base.CategoryKeyHEMS][string(id)].FotoAttachmentID = append([]byte(nil), fotoID...)
+	resp, _ = doJSONRequestBase(t, app, http.MethodPatch, "/api/v1/bases/update/"+idStr+"?category_type=hems", []byte(`{"data":{"type":"hems_base","id":"`+idStr+`","attributes":{"base":"Still New","latitude":47.3769,"longitude":8.5417,"file_uuid":""}}}`))
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if repo.rows[base.CategoryKeyHEMS][string(id)].FotoAttachmentID != nil {
+		t.Fatalf("expected foto attachment to be cleared")
+	}
+
+	resp, updateBody := doJSONRequestBase(t, app, http.MethodPatch, "/api/v1/bases/update/"+idStr+"?category_type=hems", []byte(`{"data":{"type":"hems_base","id":"`+idStr+`","attributes":{"base":"With Ops","latitude":47.3769,"longitude":8.5417,"operational_shift_times":[{"date_start":"2026-04-12","date_end":"2026-04-12","shift_time":{"start":"09:00","end":"18:00"}},{"date_start":"2026-04-13","date_end":"2026-04-13","shift_time":{"start":"09:00","end":"17:00"}}]}}}`))
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if repo.lastUpdateBase == nil || len(repo.lastUpdateBase.OperationalShiftTimes) != 2 {
+		t.Fatalf("expected operational shift times mapped on update")
+	}
+	if repo.lastUpdateBase.OperationalShiftTimes[0].ShiftStart != "09:00:00" || repo.lastUpdateBase.OperationalShiftTimes[1].ShiftEnd != "17:00:00" {
+		t.Fatalf("expected operational shift mapping on update, got %#v", repo.lastUpdateBase.OperationalShiftTimes)
+	}
+	if !bytes.Contains(updateBody, []byte(`"date_start":"2026-04-12"`)) || !bytes.Contains(updateBody, []byte(`"date_end":"2026-04-12"`)) || !bytes.Contains(updateBody, []byte(`"date_start":"2026-04-13"`)) || !bytes.Contains(updateBody, []byte(`"date_end":"2026-04-13"`)) {
+		t.Fatalf("expected operational shift dates in update response, body=%s", string(updateBody))
+	}
+
+	resp, fixedBody := doJSONRequestBase(t, app, http.MethodPatch, "/api/v1/bases/update/"+idStr+"?category_type=hems", []byte(`{"data":{"type":"hems_base","id":"`+idStr+`","attributes":{"base":"With Ops Fixed","latitude":47.3769,"longitude":8.5417,"operational_shift_times":[{"date_start":"2026-06-03","date_end":"2026-06-04","start_time_type":"FIXED","end_time_type":"FIXED","shift_time":{"start":"03:00","end":"05:00"}}]}}}`))
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if !bytes.Contains(fixedBody, []byte(`"shift_time":{"start":"03:00","end":"05:00"}`)) {
+		t.Fatalf("expected fixed operational shift_time values in update response, body=%s", string(fixedBody))
+	}
+
+	resp, _ = doJSONRequestBase(t, app, http.MethodPatch, "/api/v1/bases/update/"+idStr+"?category_type=hems", []byte(`{"data":{"type":"hems_base","id":"`+idStr+`","attributes":{"latitude":47.3769,"longitude":8.5417,"operational_shift_times":[]}}}`))
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if repo.lastUpdateBase == nil || repo.lastUpdateBase.OperationalShiftTimes == nil || len(repo.lastUpdateBase.OperationalShiftTimes) != 0 {
+		t.Fatalf("expected explicit empty operational_shift_times to clear rows")
+	}
+
+	resp, body := doJSONRequestBase(t, app, http.MethodDelete, "/api/v1/bases/delete/"+idStr+"?category_type=hems", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if repo.lastDeleteCategory != base.CategoryKeyHEMS {
+		t.Fatalf("expected hems category delete")
+	}
+	if !strings.Contains(string(body), "hems_base_delete") {
+		t.Fatalf("expected hems delete resource type")
+	}
+
+	resp, body = doJSONRequestBase(t, app, http.MethodDelete, "/api/v1/bases/delete/"+mustUUIDStringBase(t, uuidv7.MustBytes())+"?category_type=hems", nil)
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404 for missing base delete, got %d body=%s", resp.StatusCode, string(body))
+	}
+}
+
+func TestBaseHandlerUpdateShiftTimeOnly(t *testing.T) {
+	repo := newMemBaseRepo()
+	id := uuidv7.MustBytes()
+	repo.rows[base.CategoryKeyRegular][string(id)] = &base.Base{
+		ID:                id,
+		BaseName:          "Old",
+		DefaultShiftStart: "06:00:00",
+		DefaultShiftEnd:   "21:00:00",
+		CreatedAt:         time.Now(),
+		UpdatedAt:         time.Now(),
+	}
+	h := NewBaseHandler(service.NewBaseService(repo))
+	app := newBaseTestApp(h)
+	idStr := mustUUIDStringBase(t, id)
+
+	resp, body := doJSONRequestBase(t, app, http.MethodPatch, "/api/v1/bases/update/"+idStr, []byte(`{"data":{"type":"base","id":"`+idStr+`","attributes":{"shift_time":{"start":"07:00","end":"20:00"}}}}`))
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if repo.lastUpdateBase == nil || repo.lastUpdateBase.DefaultShiftStart == "" || repo.lastUpdateBase.DefaultShiftEnd == "" {
+		t.Fatalf("expected shift_time applied to repo update row")
+	}
+	if got := repo.lastUpdateBase.DefaultShiftStart; got != "07:00:00" {
+		t.Fatalf("expected updated start 07:00:00, got %s", got)
+	}
+	if got := repo.lastUpdateBase.DefaultShiftEnd; got != "20:00:00" {
+		t.Fatalf("expected updated end 20:00:00, got %s", got)
+	}
+	if !bytes.Contains(body, []byte(`"shift_time":{"start":"07:00","end":"20:00"}`)) {
+		t.Fatalf("expected response shift_time to update, body=%s", string(body))
+	}
+}
+
+func TestBaseHandlerDelete_NotFoundAndConflict(t *testing.T) {
+	t.Run("not found returns 404", func(t *testing.T) {
+		repo := newMemBaseRepo()
+		h := NewBaseHandler(service.NewBaseService(repo))
+		app := newBaseTestApp(h)
+
+		resp, body := doJSONRequestBase(t, app, http.MethodDelete, "/api/v1/bases/delete/"+mustUUIDStringBase(t, uuidv7.MustBytes())+"?category_type=hems", nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+		if !bytes.Contains(body, []byte(`"BASE_NOT_FOUND"`)) {
+			t.Fatalf("expected base not found code, body=%s", string(body))
+		}
+	})
+
+	t.Run("relation conflict returns 409", func(t *testing.T) {
+		repo := newMemBaseRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[base.CategoryKeyHEMS][string(id)] = &base.Base{ID: id, BaseName: "Has refs", DefaultShiftStart: "06:00:00", DefaultShiftEnd: "21:00:00", CreatedAt: time.Now(), UpdatedAt: time.Now()}
+		repo.deleteBaseErr = apperrors.NewDeleteConflictError("takeover")
+		h := NewBaseHandler(service.NewBaseService(repo))
+		app := newBaseTestApp(h)
+
+		resp, body := doJSONRequestBase(t, app, http.MethodDelete, "/api/v1/bases/delete/"+mustUUIDStringBase(t, id)+"?category_type=hems", nil)
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409, got %d", resp.StatusCode)
+		}
+		if !bytes.Contains(body, []byte(`"code":"BASE_DELETE_CONFLICT"`)) {
+			t.Fatalf("expected specific base delete conflict code, body=%s", string(body))
+		}
+		if !bytes.Contains(body, []byte(`"error_code":"4091615"`)) {
+			t.Fatalf("expected specific base delete conflict error_code, body=%s", string(body))
+		}
+		if !bytes.Contains(body, []byte(`takeover`)) {
+			t.Fatalf("expected relation detail to mention takeover, body=%s", string(body))
+		}
+	})
+}
+
+func TestBaseHandlerListBases(t *testing.T) {
+	repo := newMemBaseRepo()
+	repo.listRows = []base.Base{{
+		ID:                uuidv7.MustBytes(),
+		BaseName:          "Lude",
+		DefaultShiftStart: "06:00:00",
+		DefaultShiftEnd:   "21:00:00",
+		CreatedAt:         time.Now(),
+		UpdatedAt:         time.Now(),
+	}}
+	repo.listTotal = 1
+	h := NewBaseHandler(service.NewBaseService(repo))
+	app := newBaseTestApp(h)
+
+	resp, body := doJSONRequestBase(t, app, http.MethodGet, "/api/v1/bases/get-all?category_type=hems&search=abc&page=0&limit=101&sort=-base", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if repo.lastListCategory != base.CategoryKeyHEMS || repo.lastListFilter != "abc" || repo.lastListSort != "base DESC" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+		t.Fatalf("unexpected forwarded list args")
+	}
+	resp, _ = doJSONRequestBase(t, app, http.MethodGet, "/api/v1/bases/get-all?category_type=hems&sort=-sortkey", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, base ASC" {
+		t.Fatalf("unexpected sortkey sort forwarding: %q", repo.lastListSort)
+	}
+	if !bytes.Contains(body, []byte(`"type":"hems_base"`)) {
+		t.Fatalf("expected hems_base list resource type")
+	}
+	if !bytes.Contains(body, []byte(`"base_category":"hems"`)) {
+		t.Fatalf("expected base_category hems")
+	}
+	if !bytes.Contains(body, []byte(`"shift_time":{"start":"06:00","end":"21:00"}`)) {
+		t.Fatalf("expected shift_time start/end in HH:MM format, body=%s", string(body))
+	}
+	if bytes.Contains(body, []byte(`"default_shift_start"`)) || bytes.Contains(body, []byte(`"default_shift_end"`)) || bytes.Contains(body, []byte(`"default_shift_time"`)) {
+		t.Fatalf("expected old default_shift_* fields removed, body=%s", string(body))
+	}
+
+	resp, _ = doJSONRequestBase(t, app, http.MethodGet, "/api/v1/bases/get-all?base_category=regular", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 for base_category alias, got %d", resp.StatusCode)
+	}
+	if repo.lastListCategory != base.CategoryKeyRegular {
+		t.Fatalf("expected regular category from base_category alias, got %q", repo.lastListCategory)
+	}
+
+	resp, _ = doJSONRequestBase(t, app, http.MethodGet, "/api/v1/bases/get-all?base_category=hems", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 for base_category hems alias, got %d", resp.StatusCode)
+	}
+	if repo.lastListCategory != base.CategoryKeyHEMS {
+		t.Fatalf("expected hems category from base_category alias, got %q", repo.lastListCategory)
+	}
+}
+
+func TestBaseHandlerBaseResource_ShiftLabelsForNonFixedTypes(t *testing.T) {
+	repo := newMemBaseRepo()
+	id := uuidv7.MustBytes()
+	repo.rows[base.CategoryKeyRegular][string(id)] = &base.Base{
+		ID:                   id,
+		BaseName:             "Twilight Base",
+		DefaultStartTimeType: base.ShiftTimeTypeBMCT,
+		DefaultEndTimeType:   base.ShiftTimeTypeECET,
+		OperationalShiftTimes: []base.BaseOperationalShiftTime{
+			{
+				StartTimeType: base.ShiftTimeTypeBMCT,
+				EndTimeType:   base.ShiftTimeTypeECET,
+			},
+		},
+		CreatedAt: time.Now(),
+		UpdatedAt: time.Now(),
+	}
+	h := NewBaseHandler(service.NewBaseService(repo))
+	app := newBaseTestApp(h)
+
+	resp, body := doJSONRequestBase(t, app, http.MethodGet, "/api/v1/bases/get/"+mustUUIDStringBase(t, id)+"?category_type=regular", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if !bytes.Contains(body, []byte(`"shift_time":{"start":"BMCT","end":"ECET"}`)) {
+		t.Fatalf("expected BMCT/ECET shift labels in response, body=%s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"operational_shift_times":[{"date_start":"","date_end":"","start_time_type":"BMCT","end_time_type":"ECET","shift_time":{"start":"BMCT","end":"ECET"}}]`)) {
+		t.Fatalf("expected operational shift labels in response, body=%s", string(body))
+	}
+}
+
+func TestBaseHandlerListBasesDatatable(t *testing.T) {
+	repo := newMemBaseRepo()
+	repo.listRows = []base.Base{{ID: uuidv7.MustBytes(), BaseName: "Reg", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+	repo.listTotal = 1
+	h := NewBaseHandler(service.NewBaseService(repo))
+	app := newBaseTestApp(h)
+
+	resp, _ := doJSONRequestBase(t, app, http.MethodGet, "/api/v1/bases/get-all/dt?page=0&limit=0&size=101&draw=7&search=abc", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if repo.lastListCategory != "" || repo.lastListSort != "" || repo.lastListLimit != 100 || repo.lastListOffset != 0 {
+		t.Fatalf("unexpected datatable args")
+	}
+}
+
+func TestBaseHandlerListAndCreateError(t *testing.T) {
+	repo := newMemBaseRepo()
+	repo.listBasesErr = errors.New("list failed")
+	repo.createBaseErr = errors.New("create failed")
+	h := NewBaseHandler(service.NewBaseService(repo))
+	app := newBaseTestApp(h)
+
+	resp, _ := doJSONRequestBase(t, app, http.MethodGet, "/api/v1/bases/get-all", nil)
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 list, got %d", resp.StatusCode)
+	}
+
+	resp, _ = doJSONRequestBase(t, app, http.MethodPost, "/api/v1/bases/create", []byte(`{"data":{"type":"base","attributes":{"base":"A","latitude":47.3769,"longitude":8.5417,"default_shift_start":"`+testBaseShiftStart+`","default_shift_end":"`+testBaseShiftEnd+`"}}}`))
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 create, got %d", resp.StatusCode)
+	}
+}
+
+func TestBaseEventsStream(t *testing.T) {
+	hub := filemanagerrealtime.NewHub(1, nil)
+	actor := uuidv7.MustBytes()
+	userUUID, _ := uuidv7.BytesToString(actor)
+
+	app := fiber.New()
+	fctx := &fasthttp.RequestCtx{}
+	fctx.Request.SetRequestURI("/api/v1/bases/events")
+	c := app.AcquireCtx(fctx)
+	c.Locals("user_id", actor)
+	if err := NewFileManagerEventsHandler(hub).Stream(c); err != nil {
+		t.Fatalf("unexpected stream setup error: %v", err)
+	}
+
+	hub.PublishToUsers([]string{userUUID}, filemanagerrealtime.FileStatusEvent{
+		FileUUID:  mustUUIDStringBase(t, uuidv7.MustBytes()),
+		Status:    "ready",
+		Name:      "base.png",
+		MimeType:  "image/png",
+		UpdatedAt: time.Now().UTC().Format(time.RFC3339),
+	})
+	go func() {
+		time.Sleep(10 * time.Millisecond)
+		closeFirstHubSubscriberForUser(hub, userUUID)
+	}()
+
+	bodyStr := c.Context().Response.String()
+	app.ReleaseCtx(c)
+	if !strings.Contains(bodyStr, ": connected") {
+		t.Fatalf("expected connected comment in body: %q", bodyStr)
+	}
+	if !strings.Contains(bodyStr, "event: file.updated") {
+		t.Fatalf("expected file.updated event in body: %q", bodyStr)
+	}
+	if !strings.Contains(bodyStr, "\"file_id\"") || !strings.Contains(bodyStr, "\"status\":\"ready\"") {
+		t.Fatalf("expected file.updated payload in body: %q", bodyStr)
+	}
+}
diff --git a/internal/transport/http/handlers/before_flight_inspection_handler.go b/internal/transport/http/handlers/before_flight_inspection_handler.go
new file mode 100644
index 0000000..f42c949
--- /dev/null
+++ b/internal/transport/http/handlers/before_flight_inspection_handler.go
@@ -0,0 +1,231 @@
+package handlers
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	beforeflightinspection "wucher/internal/domain/before_flight_inspection"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type BeforeFlightInspectionHandler struct {
+	svc       beforeflightinspection.Service
+	flightSvc flightinspection.FlightInspectionService
+	validate  *validators.Validator
+}
+
+func NewBeforeFlightInspectionHandler(svc beforeflightinspection.Service, flightSvc flightinspection.FlightInspectionService) *BeforeFlightInspectionHandler {
+	return &BeforeFlightInspectionHandler{
+		svc:       svc,
+		flightSvc: flightSvc,
+		validate:  validators.New(),
+	}
+}
+
+// Get returns before-flight inspection payload by inspection id.
+func (h *BeforeFlightInspectionHandler) Get(c *fiber.Ctx) error {
+	flightInspectionID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	row, err := h.svc.GetByFlightInspectionID(c.Context(), flightInspectionID)
+	if err != nil {
+		if ve, ok := err.(*beforeflightinspection.ValidationError); ok {
+			return response.WriteErrors(c, ve.Status, []jsonapi.ErrorObject{{
+				Status: fmt.Sprintf("%d", ve.Status),
+				Title:  ve.Title,
+				Detail: ve.Detail,
+			}})
+		}
+		return response.WriteErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Internal Server Error",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	if row == nil {
+		return response.WriteErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "before flight inspection not found",
+		}})
+	}
+
+	flightInspectionData, err := h.getFlightInspectionResource(c.Context(), flightInspectionID)
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Internal Server Error",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	resp := dto.BeforeFlightInspectionResponse{
+		Data: dto.BeforeFlightInspectionResource{
+			Type: "before_flight_inspection",
+			Attributes: dto.BeforeFlightInspectionAttributes{
+				FlightInspection:          flightInspectionData,
+				OilEngineNR1Checked:       row.OilEngineNR1Checked,
+				OilEngineNR2Checked:       row.OilEngineNR2Checked,
+				HydraulicLHChecked:        row.HydraulicLHChecked,
+				HydraulicRHChecked:        row.HydraulicRHChecked,
+				OilTransmissionMGBChecked: row.OilTransmissionMGBChecked,
+				OilTransmissionIGBChecked: row.OilTransmissionIGBChecked,
+				OilTransmissionTGBChecked: row.OilTransmissionTGBChecked,
+				FuelAmount:                row.FuelAmount,
+				FuelUnit:                  row.FuelUnit,
+				FuelAddedAmount:           row.FuelAddedAmount,
+				CreatedAt:                 row.CreatedAt.Format(time.RFC3339),
+				UpdatedAt:                 row.UpdatedAt.Format(time.RFC3339),
+			},
+		},
+	}
+
+	idStr, _ := uuidv7.BytesToString(row.ID)
+	flightInspectionIDStr, _ := uuidv7.BytesToString(row.FlightInspectionID)
+	resp.Data.ID = idStr
+	resp.Data.Attributes.ID = idStr
+	resp.Data.Attributes.FlightInspectionID = flightInspectionIDStr
+
+	return c.JSON(resp)
+}
+
+// Upsert stores before-flight inspection payload by inspection id.
+func (h *BeforeFlightInspectionHandler) Upsert(c *fiber.Ctx) error {
+	flightInspectionID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	var req dto.BeforeFlightInspectionUpsertRequest
+	if err := c.BodyParser(&req); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	upsertReq := &beforeflightinspection.UpsertRequest{
+		OilEngineNR1Checked:       req.Data.Attributes.OilEngineNR1Checked,
+		OilEngineNR2Checked:       req.Data.Attributes.OilEngineNR2Checked,
+		HydraulicLHChecked:        req.Data.Attributes.HydraulicLHChecked,
+		HydraulicRHChecked:        req.Data.Attributes.HydraulicRHChecked,
+		OilTransmissionMGBChecked: req.Data.Attributes.OilTransmissionMGBChecked,
+		OilTransmissionIGBChecked: req.Data.Attributes.OilTransmissionIGBChecked,
+		OilTransmissionTGBChecked: req.Data.Attributes.OilTransmissionTGBChecked,
+		FuelAmount:                req.Data.Attributes.FuelAmount,
+		FuelUnit:                  req.Data.Attributes.FuelUnit,
+		FuelAddedAmount:           req.Data.Attributes.FuelAddedAmount,
+		Note:                      req.Data.Attributes.Note,
+	}
+
+	row, err := h.svc.Upsert(c.Context(), flightInspectionID, upsertReq)
+	if err != nil {
+		if ve, ok := err.(*beforeflightinspection.ValidationError); ok {
+			return response.WriteErrors(c, ve.Status, []jsonapi.ErrorObject{{
+				Status: fmt.Sprintf("%d", ve.Status),
+				Title:  ve.Title,
+				Detail: ve.Detail,
+			}})
+		}
+		return response.WriteErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Internal Server Error",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	flightInspectionData, err := h.getFlightInspectionResource(c.Context(), flightInspectionID)
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Internal Server Error",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	idStr, _ := uuidv7.BytesToString(row.ID)
+	flightInspectionIDStr, _ := uuidv7.BytesToString(row.FlightInspectionID)
+	resp := dto.BeforeFlightInspectionResponse{
+		Data: dto.BeforeFlightInspectionResource{
+			Type: "before_flight_inspection",
+			ID:   idStr,
+			Attributes: dto.BeforeFlightInspectionAttributes{
+				ID:                        idStr,
+				FlightInspectionID:        flightInspectionIDStr,
+				FlightInspection:          flightInspectionData,
+				OilEngineNR1Checked:       row.OilEngineNR1Checked,
+				OilEngineNR2Checked:       row.OilEngineNR2Checked,
+				HydraulicLHChecked:        row.HydraulicLHChecked,
+				HydraulicRHChecked:        row.HydraulicRHChecked,
+				OilTransmissionMGBChecked: row.OilTransmissionMGBChecked,
+				OilTransmissionIGBChecked: row.OilTransmissionIGBChecked,
+				OilTransmissionTGBChecked: row.OilTransmissionTGBChecked,
+				FuelAmount:                row.FuelAmount,
+				FuelUnit:                  row.FuelUnit,
+				FuelAddedAmount:           row.FuelAddedAmount,
+				CreatedAt:                 row.CreatedAt.Format(time.RFC3339),
+				UpdatedAt:                 row.UpdatedAt.Format(time.RFC3339),
+			},
+		},
+	}
+
+	return c.JSON(resp)
+}
+
+func (h *BeforeFlightInspectionHandler) getFlightInspectionResource(ctx context.Context, flightInspectionID []byte) (*dto.FlightInspectionResource, error) {
+	if h.flightSvc == nil {
+		return nil, nil
+	}
+
+	row, err := h.flightSvc.GetByID(ctx, flightInspectionID)
+	if err != nil {
+		return nil, err
+	}
+	if row == nil {
+		return nil, nil
+	}
+
+	return beforeFlightInspectionResource(row), nil
+}
+
+func beforeFlightInspectionResource(row *flightinspection.FlightInspection) *dto.FlightInspectionResource {
+	id, _ := uuidv7.BytesToString(row.ID)
+	return &dto.FlightInspectionResource{
+		Type: "flight_inspection",
+		ID:   id,
+		Attributes: dto.FlightInspectionAttributes{
+			InspectionDate: row.InspectionDate.UTC().Format("2006-01-02"),
+			Status:         row.Status,
+			CreatedAt:      row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:      uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:      row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:      uuidStringOrEmpty(row.UpdatedBy),
+		},
+	}
+}
diff --git a/internal/transport/http/handlers/branding_handler.go b/internal/transport/http/handlers/branding_handler.go
new file mode 100644
index 0000000..e0b38f7
--- /dev/null
+++ b/internal/transport/http/handlers/branding_handler.go
@@ -0,0 +1,571 @@
+package handlers
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"image"
+	"image/color"
+	"image/draw"
+	"image/png"
+	"io"
+	"log/slog"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanager "wucher/internal/domain/file_manager"
+	mastersettings "wucher/internal/domain/master_settings"
+	"wucher/internal/shared/pkg/metrics"
+	"wucher/internal/transport/http/jsonapi"
+)
+
+const (
+	brandingLogoManagedCacheControl  = "public, max-age=300, stale-while-revalidate=86400"
+	brandingCoverManagedCacheControl = "public, max-age=300, stale-while-revalidate=86400"
+	brandingContentCacheControl      = "public, max-age=60, stale-while-revalidate=300"
+	brandingFallbackCache            = "public, max-age=60, stale-while-revalidate=300"
+	brandingPresignTTL               = time.Minute
+	brandingFetchTimeout             = 10 * time.Second
+	brandingMaxBytes                 = 5 << 20
+	brandingCORPMode                 = "same-site"
+	brandingLoginTitleDefault        = "Welcome back"
+	brandingLoginSubtitleDefault     = "Sign in to continue"
+)
+
+var brandingDefaultLastModified = time.Date(2026, time.January, 1, 0, 0, 0, 0, time.UTC)
+var _ = jsonapi.ErrorDocument{}
+var brandingDefaultEmailLogoPNG = mustBuildDefaultEmailLogoPNG()
+
+const brandingDefaultLogoSVG = `<svg xmlns="http://www.w3.org/2000/svg" width="220" height="48" viewBox="0 0 220 48" role="img" aria-label="Company Logo"><rect width="220" height="48" rx="8" fill="#0F172A"/><text x="20" y="31" font-family="Arial, Helvetica, sans-serif" font-size="18" font-weight="700" fill="#F8FAFC">COMPANY</text></svg>`
+const brandingDefaultCoverSVG = `<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="900" viewBox="0 0 1600 900" role="img" aria-label="Login Background"><defs><linearGradient id="g" x1="0" x2="1" y1="0" y2="1"><stop offset="0%" stop-color="#0F172A"/><stop offset="100%" stop-color="#1D4ED8"/></linearGradient></defs><rect width="1600" height="900" fill="url(#g)"/><circle cx="1300" cy="120" r="180" fill="#FFFFFF" fill-opacity="0.08"/><circle cx="200" cy="760" r="260" fill="#FFFFFF" fill-opacity="0.06"/></svg>`
+
+type brandingLogoPayload struct {
+	Body         []byte
+	ContentType  string
+	ETag         string
+	LastModified time.Time
+	CacheControl string
+	Source       string
+}
+
+type loginBrandingContentDocument struct {
+	Data loginBrandingContentData `json:"data"`
+}
+
+type loginBrandingContentData struct {
+	Type       string                       `json:"type"`
+	Attributes loginBrandingContentAttrsDTO `json:"attributes"`
+}
+
+type loginBrandingContentAttrsDTO struct {
+	Title     string `json:"title"`
+	Subtitle  string `json:"subtitle"`
+	UpdatedAt string `json:"updated_at"`
+	Version   string `json:"version"`
+}
+
+type BrandingHandler struct {
+	masterSvc  mastersettings.Service
+	fileSvc    filemanager.Service
+	storage    filemanager.ObjectStorage
+	httpClient *http.Client
+	logger     *slog.Logger
+}
+
+func NewBrandingHandler(masterSvc mastersettings.Service, fileSvc filemanager.Service, storage filemanager.ObjectStorage) *BrandingHandler {
+	return &BrandingHandler{
+		masterSvc: masterSvc,
+		fileSvc:   fileSvc,
+		storage:   storage,
+		httpClient: &http.Client{
+			Timeout: brandingFetchTimeout,
+		},
+		logger: slog.Default(),
+	}
+}
+
+// GetBrandingLogo godoc
+// @Summary Get branding logo
+// @Description Return a stable company logo asset for frontend consumption.
+// @Description Backend resolves private object storage internally (no presigned URL exposure) and serves fallback logo when managed logo is unavailable.
+// @Description Supports conditional requests with `If-None-Match` / `If-Modified-Since`.
+// @Tags Branding
+// @Produce image/png,image/jpeg,image/webp,image/svg+xml,application/octet-stream
+// @Success 200 {file} file "Branding logo binary"
+// @Success 304 {string} string "Not Modified"
+// @Router /api/v1/branding/logo [get]
+func (h *BrandingHandler) GetLogo(c *fiber.Ctx) error {
+	started := time.Now()
+	payload, fetchErr := h.loadLogo(c.UserContext())
+	if fetchErr != nil {
+		h.logger.Warn("branding logo fetch degraded to fallback", "error", fetchErr)
+	}
+	statusCode := fiber.StatusOK
+	h.writeImageCacheHeaders(c, payload)
+	if brandingNotModified(c, payload.ETag, payload.LastModified) {
+		statusCode = fiber.StatusNotModified
+		metrics.ObserveBrandingRequest("api", "logo", payload.Source, statusCode, fetchErr, started)
+		return c.SendStatus(statusCode)
+	}
+	metrics.ObserveBrandingRequest("api", "logo", payload.Source, statusCode, fetchErr, started)
+	return c.Status(statusCode).Send(payload.Body)
+}
+
+// GetBrandingEmailLogo godoc
+// @Summary Get email-safe branding logo
+// @Description Return a stable company logo optimized for email clients like Outlook.
+// @Description Backend prefers managed raster thumbnail/logo and falls back to backend-generated PNG when necessary.
+// @Description Supports conditional requests with `If-None-Match` / `If-Modified-Since`.
+// @Tags Branding
+// @Produce image/png,image/jpeg,image/gif,application/octet-stream
+// @Success 200 {file} file "Email-safe branding logo binary"
+// @Success 304 {string} string "Not Modified"
+// @Router /api/v1/public/branding/email-logo [get]
+func (h *BrandingHandler) GetEmailLogo(c *fiber.Ctx) error {
+	started := time.Now()
+	payload, fetchErr := h.loadEmailLogo(c.UserContext())
+	if fetchErr != nil {
+		h.logger.Warn("branding email logo fetch degraded to fallback", "error", fetchErr)
+	}
+	statusCode := fiber.StatusOK
+	h.writeImageCacheHeaders(c, payload)
+	h.relaxEmailLogoSecurityHeaders(c)
+	if brandingNotModified(c, payload.ETag, payload.LastModified) {
+		statusCode = fiber.StatusNotModified
+		metrics.ObserveBrandingRequest("api", "email_logo", payload.Source, statusCode, fetchErr, started)
+		return c.SendStatus(statusCode)
+	}
+	metrics.ObserveBrandingRequest("api", "email_logo", payload.Source, statusCode, fetchErr, started)
+	return c.Status(statusCode).Send(payload.Body)
+}
+
+// GetBrandingLoginCover godoc
+// @Summary Get login cover image
+// @Description Return public stable login cover image for sign-in page.
+// @Description Supports conditional requests with `If-None-Match` / `If-Modified-Since`.
+// @Tags Branding
+// @Produce image/png,image/jpeg,image/webp,image/svg+xml,application/octet-stream
+// @Success 200 {file} file "Login cover image binary"
+// @Success 304 {string} string "Not Modified"
+// @Router /api/v1/branding/login-cover [get]
+func (h *BrandingHandler) GetLoginCover(c *fiber.Ctx) error {
+	started := time.Now()
+	payload, fetchErr := h.loadLoginCover(c.UserContext())
+	if fetchErr != nil {
+		h.logger.Warn("branding login cover fetch degraded to fallback", "error", fetchErr)
+	}
+
+	statusCode := fiber.StatusOK
+	h.writeImageCacheHeaders(c, payload)
+	c.Set("Cross-Origin-Resource-Policy", brandingCORPMode)
+	if brandingNotModified(c, payload.ETag, payload.LastModified) {
+		statusCode = fiber.StatusNotModified
+		metrics.ObserveBrandingRequest("api", "login_cover", payload.Source, statusCode, fetchErr, started)
+		return c.SendStatus(statusCode)
+	}
+	metrics.ObserveBrandingRequest("api", "login_cover", payload.Source, statusCode, fetchErr, started)
+	return c.Status(statusCode).Send(payload.Body)
+}
+
+// GetBrandingLoginContent godoc
+// @Summary Get login content
+// @Description Return public stable login title and subtitle from active master settings with backend defaults.
+// @Description Supports conditional requests with `If-None-Match` / `If-Modified-Since`.
+// @Tags Branding
+// @Produce json
+// @Success 200 {object} loginBrandingContentDocument
+// @Success 304 {string} string "Not Modified"
+// @Router /api/v1/branding/login-content [get]
+func (h *BrandingHandler) GetLoginContent(c *fiber.Ctx) error {
+	started := time.Now()
+	doc, etag, lastModified, source, err := h.loadLoginContent(c.UserContext())
+	if err != nil {
+		h.logger.Warn("branding login content degraded to defaults", "error", err)
+	}
+
+	statusCode := fiber.StatusOK
+	h.writeJSONCacheHeaders(c, etag, lastModified, brandingContentCacheControl)
+	if brandingNotModified(c, etag, lastModified) {
+		statusCode = fiber.StatusNotModified
+		metrics.ObserveBrandingRequest("api", "login_content", source, statusCode, err, started)
+		return c.SendStatus(statusCode)
+	}
+	metrics.ObserveBrandingRequest("api", "login_content", source, statusCode, err, started)
+	return c.Status(statusCode).JSON(doc)
+}
+
+func (h *BrandingHandler) loadLogo(ctx context.Context) (brandingLogoPayload, error) {
+	row, err := h.getActiveMasterSettings(ctx)
+	if err != nil {
+		return h.defaultLogoPayload(), err
+	}
+	if row == nil || len(row.LogoFileID) == 0 {
+		return h.defaultLogoPayload(), nil
+	}
+	return h.loadManagedImage(ctx, row, row.LogoFileID, h.defaultLogoPayload(), "logo", brandingLogoManagedCacheControl, false)
+}
+
+func (h *BrandingHandler) loadLoginCover(ctx context.Context) (brandingLogoPayload, error) {
+	row, err := h.getActiveMasterSettings(ctx)
+	if err != nil {
+		return h.defaultCoverPayload(), err
+	}
+	if row == nil || len(row.CoverFileID) == 0 {
+		return h.defaultCoverPayload(), nil
+	}
+	return h.loadManagedImage(ctx, row, row.CoverFileID, h.defaultCoverPayload(), "login_cover", brandingCoverManagedCacheControl, false)
+}
+
+func (h *BrandingHandler) loadEmailLogo(ctx context.Context) (brandingLogoPayload, error) {
+	row, err := h.getActiveMasterSettings(ctx)
+	if err != nil {
+		return h.defaultEmailLogoPayload(), err
+	}
+	if row == nil || len(row.LogoFileID) == 0 {
+		return h.defaultEmailLogoPayload(), nil
+	}
+	return h.loadManagedImage(ctx, row, row.LogoFileID, h.defaultEmailLogoPayload(), "email_logo", brandingLogoManagedCacheControl, true)
+}
+
+func (h *BrandingHandler) loadManagedImage(
+	ctx context.Context,
+	ms *mastersettings.MasterSettings,
+	fileID []byte,
+	fallback brandingLogoPayload,
+	resourceType string,
+	cacheControl string,
+	emailSafe bool,
+) (brandingLogoPayload, error) {
+	if h.fileSvc == nil {
+		return fallback, errors.New("file manager service is not configured")
+	}
+	if h.storage == nil {
+		return fallback, errors.New("object storage is not configured")
+	}
+
+	fileRow, err := h.fileSvc.GetFileByID(ctx, fileID)
+	if err != nil {
+		return fallback, fmt.Errorf("get managed branding file: %w", err)
+	}
+	if fileRow == nil {
+		return fallback, errors.New("managed branding file not found")
+	}
+	if !strings.EqualFold(strings.TrimSpace(fileRow.Status), filemanager.FileStatusReady) {
+		return fallback, errors.New("managed branding file is not ready")
+	}
+
+	payload, err := h.downloadManagedImage(ctx, ms, fileRow, resourceType, cacheControl, emailSafe)
+	if err != nil {
+		return fallback, err
+	}
+	return payload, nil
+}
+
+func (h *BrandingHandler) defaultLogoPayload() brandingLogoPayload {
+	body := []byte(brandingDefaultLogoSVG)
+	return brandingLogoPayload{
+		Body:         body,
+		ContentType:  "image/svg+xml; charset=utf-8",
+		ETag:         quotedSHA256("branding-default:" + string(body)),
+		LastModified: brandingDefaultLastModified,
+		CacheControl: brandingFallbackCache,
+		Source:       "default_logo",
+	}
+}
+
+func (h *BrandingHandler) defaultEmailLogoPayload() brandingLogoPayload {
+	body := append([]byte(nil), brandingDefaultEmailLogoPNG...)
+	return brandingLogoPayload{
+		Body:         body,
+		ContentType:  "image/png",
+		ETag:         quotedSHA256("branding-email-default:" + string(body)),
+		LastModified: brandingDefaultLastModified,
+		CacheControl: brandingFallbackCache,
+		Source:       "default_email_logo",
+	}
+}
+
+func (h *BrandingHandler) defaultCoverPayload() brandingLogoPayload {
+	body := []byte(brandingDefaultCoverSVG)
+	return brandingLogoPayload{
+		Body:         body,
+		ContentType:  "image/svg+xml; charset=utf-8",
+		ETag:         quotedSHA256("branding-cover-default:" + string(body)),
+		LastModified: brandingDefaultLastModified,
+		CacheControl: brandingFallbackCache,
+		Source:       "default_cover",
+	}
+}
+
+func (h *BrandingHandler) downloadManagedImage(ctx context.Context, ms *mastersettings.MasterSettings, logoFile *filemanager.File, resourceType, cacheControl string, emailSafe bool) (brandingLogoPayload, error) {
+	objectKey, declaredContentType, err := selectBrandingObjectVariant(logoFile, emailSafe)
+	if err != nil {
+		return brandingLogoPayload{}, err
+	}
+	if objectKey == "" {
+		return brandingLogoPayload{}, errors.New("managed branding object key is empty")
+	}
+
+	presigned, err := h.storage.PresignGetObject(ctx, objectKey, brandingPresignTTL)
+	if err != nil {
+		return brandingLogoPayload{}, fmt.Errorf("presign managed branding object: %w", err)
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, presigned, nil)
+	if err != nil {
+		return brandingLogoPayload{}, fmt.Errorf("build object request: %w", err)
+	}
+	resp, err := h.httpClient.Do(req)
+	if err != nil {
+		return brandingLogoPayload{}, fmt.Errorf("download logo object: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return brandingLogoPayload{}, fmt.Errorf("object storage returned status %d", resp.StatusCode)
+	}
+
+	limited := io.LimitReader(resp.Body, brandingMaxBytes+1)
+	body, err := io.ReadAll(limited)
+	if err != nil {
+		return brandingLogoPayload{}, fmt.Errorf("read logo object body: %w", err)
+	}
+	if len(body) == 0 {
+		return brandingLogoPayload{}, errors.New("logo object body is empty")
+	}
+	if len(body) > brandingMaxBytes {
+		return brandingLogoPayload{}, errors.New("logo object exceeds max allowed size")
+	}
+
+	contentType := strings.TrimSpace(resp.Header.Get(fiber.HeaderContentType))
+	if contentType == "" {
+		contentType = declaredContentType
+	}
+	if contentType == "" {
+		contentType = "application/octet-stream"
+	}
+	if emailSafe && !isEmailSafeImageContentType(contentType) {
+		return brandingLogoPayload{}, errors.New("managed branding asset is not email-safe")
+	}
+
+	lastModified := ms.UpdatedAt
+	if lastModified.IsZero() || (!logoFile.UpdatedAt.IsZero() && logoFile.UpdatedAt.After(lastModified)) {
+		lastModified = logoFile.UpdatedAt
+	}
+	if lastModified.IsZero() {
+		lastModified = time.Now().UTC()
+	}
+
+	etagSeed := strings.Join([]string{
+		"branding-managed-" + resourceType,
+		idString(ms.ID),
+		idString(logoFile.ID),
+		lastModified.UTC().Format(time.RFC3339Nano),
+		strings.TrimSpace(logoFile.ETag),
+		strings.TrimSpace(logoFile.ObjectVersion),
+	}, "|")
+
+	return brandingLogoPayload{
+		Body:         body,
+		ContentType:  contentType,
+		ETag:         quotedSHA256(etagSeed),
+		LastModified: lastModified.UTC(),
+		CacheControl: cacheControl,
+		Source:       "managed_" + resourceType,
+	}, nil
+}
+
+func selectBrandingObjectVariant(fileRow *filemanager.File, emailSafe bool) (string, string, error) {
+	if fileRow == nil {
+		return "", "", errors.New("managed branding file is missing")
+	}
+	if emailSafe {
+		if fileRow.ThumbnailObjectKey != nil {
+			thumbKey := strings.TrimSpace(*fileRow.ThumbnailObjectKey)
+			thumbType := strings.TrimSpace(ptrStringValue(fileRow.ThumbnailMimeType))
+			if thumbKey != "" && isEmailSafeImageContentType(thumbType) {
+				return thumbKey, thumbType, nil
+			}
+		}
+		originalKey := strings.TrimSpace(fileRow.ObjectKey)
+		originalType := strings.TrimSpace(fileRow.MimeType)
+		if originalKey != "" && isEmailSafeImageContentType(originalType) {
+			return originalKey, originalType, nil
+		}
+		return "", "", errors.New("managed branding file has no email-safe variant")
+	}
+	return strings.TrimSpace(fileRow.ObjectKey), strings.TrimSpace(fileRow.MimeType), nil
+}
+
+func isEmailSafeImageContentType(contentType string) bool {
+	contentType = strings.ToLower(strings.TrimSpace(contentType))
+	if idx := strings.Index(contentType, ";"); idx >= 0 {
+		contentType = strings.TrimSpace(contentType[:idx])
+	}
+	switch contentType {
+	case "image/png", "image/jpeg", "image/jpg", "image/gif":
+		return true
+	default:
+		return false
+	}
+}
+
+func ptrStringValue(v *string) string {
+	if v == nil {
+		return ""
+	}
+	return *v
+}
+
+func mustBuildDefaultEmailLogoPNG() []byte {
+	var buf strings.Builder
+	_ = buf
+	img := image.NewRGBA(image.Rect(0, 0, 220, 48))
+	draw.Draw(img, img.Bounds(), &image.Uniform{C: color.RGBA{R: 15, G: 23, B: 42, A: 255}}, image.Point{}, draw.Src)
+	draw.Draw(img, image.Rect(0, 0, 220, 4), &image.Uniform{C: color.RGBA{R: 148, G: 163, B: 184, A: 255}}, image.Point{}, draw.Src)
+	draw.Draw(img, image.Rect(16, 14, 48, 34), &image.Uniform{C: color.RGBA{R: 255, G: 255, B: 255, A: 255}}, image.Point{}, draw.Src)
+	var out strings.Builder
+	_ = out
+	var pngBuf []byte
+	w := &sliceWriter{buf: &pngBuf}
+	if err := png.Encode(w, img); err != nil {
+		panic(err)
+	}
+	return pngBuf
+}
+
+type sliceWriter struct {
+	buf *[]byte
+}
+
+func (w *sliceWriter) Write(p []byte) (int, error) {
+	*w.buf = append(*w.buf, p...)
+	return len(p), nil
+}
+
+func (h *BrandingHandler) loadLoginContent(ctx context.Context) (loginBrandingContentDocument, string, time.Time, string, error) {
+	row, err := h.getActiveMasterSettings(ctx)
+	source := "default_content"
+	updatedAt := brandingDefaultLastModified
+	title := brandingLoginTitleDefault
+	subtitle := brandingLoginSubtitleDefault
+
+	if err == nil && row != nil {
+		if strings.TrimSpace(row.Title) != "" {
+			title = strings.TrimSpace(row.Title)
+		}
+		if strings.TrimSpace(row.Subtitle) != "" {
+			subtitle = strings.TrimSpace(row.Subtitle)
+		}
+		if !row.UpdatedAt.IsZero() {
+			updatedAt = row.UpdatedAt.UTC()
+		}
+		source = "managed_content"
+	}
+
+	version := updatedAt.Format(time.RFC3339)
+	doc := loginBrandingContentDocument{
+		Data: loginBrandingContentData{
+			Type: "login_branding",
+			Attributes: loginBrandingContentAttrsDTO{
+				Title:     title,
+				Subtitle:  subtitle,
+				UpdatedAt: version,
+				Version:   version,
+			},
+		},
+	}
+	etagSeed := strings.Join([]string{
+		"branding-login-content",
+		title,
+		subtitle,
+		version,
+	}, "|")
+	return doc, quotedSHA256(etagSeed), updatedAt, source, err
+}
+
+func (h *BrandingHandler) getActiveMasterSettings(ctx context.Context) (*mastersettings.MasterSettings, error) {
+	if h.masterSvc == nil {
+		return nil, errors.New("master settings service is not configured")
+	}
+	rows, _, err := h.masterSvc.List(ctx, "", "-updated_at", 1, 0)
+	if err != nil {
+		return nil, fmt.Errorf("list master settings: %w", err)
+	}
+	if len(rows) == 0 {
+		return nil, nil
+	}
+	return &rows[0], nil
+}
+
+func (h *BrandingHandler) writeImageCacheHeaders(c *fiber.Ctx, payload brandingLogoPayload) {
+	c.Set(fiber.HeaderContentType, payload.ContentType)
+	c.Set(fiber.HeaderCacheControl, payload.CacheControl)
+	c.Set(fiber.HeaderETag, payload.ETag)
+	c.Set(fiber.HeaderLastModified, payload.LastModified.UTC().Format(http.TimeFormat))
+	c.Set(fiber.HeaderVary, "Origin")
+	c.Set(fiber.HeaderXContentTypeOptions, "nosniff")
+}
+
+func (h *BrandingHandler) writeJSONCacheHeaders(c *fiber.Ctx, etag string, lastModified time.Time, cacheControl string) {
+	c.Set(fiber.HeaderCacheControl, cacheControl)
+	c.Set(fiber.HeaderETag, etag)
+	c.Set(fiber.HeaderLastModified, lastModified.UTC().Format(http.TimeFormat))
+	c.Set(fiber.HeaderVary, "Origin")
+}
+
+func (h *BrandingHandler) relaxEmailLogoSecurityHeaders(c *fiber.Ctx) {
+	c.Set("Cross-Origin-Resource-Policy", "cross-origin")
+	c.Response().Header.Del("Cross-Origin-Embedder-Policy")
+	c.Response().Header.Del("Cross-Origin-Opener-Policy")
+	c.Response().Header.Del("Origin-Agent-Cluster")
+}
+
+func brandingNotModified(c *fiber.Ctx, etag string, lastModified time.Time) bool {
+	if etagMatches(c.Get(fiber.HeaderIfNoneMatch), etag) {
+		return true
+	}
+	rawIfModifiedSince := strings.TrimSpace(c.Get(fiber.HeaderIfModifiedSince))
+	if rawIfModifiedSince == "" || lastModified.IsZero() {
+		return false
+	}
+	ifModifiedSince, err := http.ParseTime(rawIfModifiedSince)
+	if err != nil {
+		return false
+	}
+	return !lastModified.UTC().Truncate(time.Second).After(ifModifiedSince.UTC().Truncate(time.Second))
+}
+
+func etagMatches(rawHeader, currentETag string) bool {
+	rawHeader = strings.TrimSpace(rawHeader)
+	if rawHeader == "" || strings.TrimSpace(currentETag) == "" {
+		return false
+	}
+	if rawHeader == "*" {
+		return true
+	}
+	currentNormalized := normalizeETag(currentETag)
+	parts := strings.Split(rawHeader, ",")
+	for i := range parts {
+		if normalizeETag(parts[i]) == currentNormalized {
+			return true
+		}
+	}
+	return false
+}
+
+func normalizeETag(raw string) string {
+	raw = strings.TrimSpace(raw)
+	raw = strings.TrimPrefix(raw, "W/")
+	raw = strings.TrimPrefix(raw, "w/")
+	return strings.TrimSpace(raw)
+}
+
+func quotedSHA256(input string) string {
+	sum := sha256.Sum256([]byte(input))
+	return `"` + hex.EncodeToString(sum[:]) + `"`
+}
diff --git a/internal/transport/http/handlers/branding_handler_test.go b/internal/transport/http/handlers/branding_handler_test.go
new file mode 100644
index 0000000..2063a44
--- /dev/null
+++ b/internal/transport/http/handlers/branding_handler_test.go
@@ -0,0 +1,481 @@
+package handlers
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanager "wucher/internal/domain/file_manager"
+	mastersettings "wucher/internal/domain/master_settings"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func newBrandingTestApp(h *BrandingHandler) *fiber.App {
+	app := fiber.New()
+	app.Get("/api/v1/branding/logo", h.GetLogo)
+	app.Get("/api/v1/branding/login-cover", h.GetLoginCover)
+	app.Get("/api/v1/branding/login-content", h.GetLoginContent)
+	app.Get("/api/v1/public/branding/email-logo", h.GetEmailLogo)
+	return app
+}
+
+func doBrandingRequest(t *testing.T, app *fiber.App, req *http.Request) (*http.Response, []byte) {
+	t.Helper()
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, body
+}
+
+func TestBrandingHandlerGetLogoManagedSuccess(t *testing.T) {
+	logoBytes := []byte("PNGDATA")
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/png")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(logoBytes)
+	}))
+	defer upstream.Close()
+
+	logoFileID := uuidv7.MustBytes()
+	msSvc := &masterSettingsServiceMock{
+		listRows: []mastersettings.MasterSettings{{
+			ID:         uuidv7.MustBytes(),
+			LogoFileID: logoFileID,
+			UpdatedAt:  time.Date(2026, time.April, 1, 0, 0, 0, 0, time.UTC),
+		}},
+	}
+	fileRepo := &masterSettingsFileRepoMock{
+		getByIDRow: &filemanager.File{
+			ID:            logoFileID,
+			ObjectKey:     "branding/company-logo.png",
+			Status:        filemanager.FileStatusReady,
+			MimeType:      "image/png",
+			ETag:          "etag-1",
+			ObjectVersion: "v1",
+			UpdatedAt:     time.Date(2026, time.April, 2, 0, 0, 0, 0, time.UTC),
+		},
+	}
+	storage := &masterSettingsStorageMock{presignURL: upstream.URL}
+
+	h := NewBrandingHandler(msSvc, newMasterSettingsFileService(fileRepo), storage)
+	app := newBrandingTestApp(h)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/branding/logo", nil)
+	resp, body := doBrandingRequest(t, app, req)
+
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if !bytes.Equal(body, logoBytes) {
+		t.Fatalf("unexpected logo body: %q", string(body))
+	}
+	if got := resp.Header.Get("Content-Type"); !strings.Contains(got, "image/png") {
+		t.Fatalf("expected image/png, got %q", got)
+	}
+	if got := resp.Header.Get("Cache-Control"); got != brandingLogoManagedCacheControl {
+		t.Fatalf("expected managed cache-control, got %q", got)
+	}
+	if got := strings.TrimSpace(resp.Header.Get("ETag")); got == "" {
+		t.Fatalf("expected ETag header")
+	}
+	if got := resp.Header.Get("Last-Modified"); strings.TrimSpace(got) == "" {
+		t.Fatalf("expected Last-Modified header")
+	}
+	if got := resp.Header.Get("Vary"); !strings.Contains(got, "Origin") {
+		t.Fatalf("expected Origin in Vary, got %q", got)
+	}
+	if storage.lastKey != "branding/company-logo.png" {
+		t.Fatalf("expected object key passed to presign, got %q", storage.lastKey)
+	}
+}
+
+func TestBrandingHandlerGetLogoNotModifiedByETag(t *testing.T) {
+	logoBytes := []byte("PNGDATA")
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/png")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(logoBytes)
+	}))
+	defer upstream.Close()
+
+	logoFileID := uuidv7.MustBytes()
+	msSvc := &masterSettingsServiceMock{
+		listRows: []mastersettings.MasterSettings{{
+			ID:         uuidv7.MustBytes(),
+			LogoFileID: logoFileID,
+			UpdatedAt:  time.Date(2026, time.April, 1, 0, 0, 0, 0, time.UTC),
+		}},
+	}
+	fileRepo := &masterSettingsFileRepoMock{
+		getByIDRow: &filemanager.File{
+			ID:            logoFileID,
+			ObjectKey:     "branding/company-logo.png",
+			Status:        filemanager.FileStatusReady,
+			MimeType:      "image/png",
+			ETag:          "etag-1",
+			ObjectVersion: "v1",
+			UpdatedAt:     time.Date(2026, time.April, 2, 0, 0, 0, 0, time.UTC),
+		},
+	}
+	storage := &masterSettingsStorageMock{presignURL: upstream.URL}
+
+	h := NewBrandingHandler(msSvc, newMasterSettingsFileService(fileRepo), storage)
+	app := newBrandingTestApp(h)
+
+	req1, _ := http.NewRequest(http.MethodGet, "/api/v1/branding/logo", nil)
+	resp1, _ := doBrandingRequest(t, app, req1)
+	if resp1.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp1.StatusCode)
+	}
+	etag := resp1.Header.Get("ETag")
+	if strings.TrimSpace(etag) == "" {
+		t.Fatalf("expected etag header")
+	}
+
+	req2, _ := http.NewRequest(http.MethodGet, "/api/v1/branding/logo", nil)
+	req2.Header.Set("If-None-Match", etag)
+	resp2, body2 := doBrandingRequest(t, app, req2)
+	if resp2.StatusCode != http.StatusNotModified {
+		t.Fatalf("expected 304, got %d", resp2.StatusCode)
+	}
+	if len(body2) != 0 {
+		t.Fatalf("expected empty body for 304, got %d bytes", len(body2))
+	}
+}
+
+func TestBrandingHandlerGetLogoFallbackWhenNoLogoConfigured(t *testing.T) {
+	msSvc := &masterSettingsServiceMock{listRows: []mastersettings.MasterSettings{}}
+	h := NewBrandingHandler(msSvc, nil, nil)
+	app := newBrandingTestApp(h)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/branding/logo", nil)
+	resp, body := doBrandingRequest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if got := resp.Header.Get("Cache-Control"); got != brandingFallbackCache {
+		t.Fatalf("expected fallback cache-control, got %q", got)
+	}
+	if got := resp.Header.Get("Content-Type"); !strings.Contains(got, "image/svg+xml") {
+		t.Fatalf("expected svg content-type, got %q", got)
+	}
+	if !strings.Contains(string(body), "COMPANY") {
+		t.Fatalf("expected default logo body, got %q", string(body))
+	}
+}
+
+func TestBrandingHandlerGetEmailLogoAlias(t *testing.T) {
+	msSvc := &masterSettingsServiceMock{listRows: []mastersettings.MasterSettings{}}
+	h := NewBrandingHandler(msSvc, nil, nil)
+	app := newBrandingTestApp(h)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/public/branding/email-logo", nil)
+	resp, body := doBrandingRequest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if got := resp.Header.Get("Content-Type"); !strings.Contains(got, "image/png") {
+		t.Fatalf("expected png content-type, got %q", got)
+	}
+	if len(body) == 0 {
+		t.Fatalf("expected default logo body")
+	}
+	if got := resp.Header.Get("Cross-Origin-Resource-Policy"); got != "cross-origin" {
+		t.Fatalf("expected cross-origin CORP header, got %q", got)
+	}
+	if got := resp.Header.Get("Cross-Origin-Embedder-Policy"); got != "" {
+		t.Fatalf("expected no COEP header, got %q", got)
+	}
+	if got := resp.Header.Get("Cross-Origin-Opener-Policy"); got != "" {
+		t.Fatalf("expected no COOP header, got %q", got)
+	}
+}
+
+func TestBrandingHandlerGetEmailLogoPrefersThumbnail(t *testing.T) {
+	logoBytes := []byte("PNGDATA")
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/png")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(logoBytes)
+	}))
+	defer upstream.Close()
+
+	logoFileID := uuidv7.MustBytes()
+	thumbMime := "image/png"
+	thumbKey := "branding/company-logo-thumb.png"
+	msSvc := &masterSettingsServiceMock{
+		listRows: []mastersettings.MasterSettings{{
+			ID:         uuidv7.MustBytes(),
+			LogoFileID: logoFileID,
+			UpdatedAt:  time.Date(2026, time.April, 1, 0, 0, 0, 0, time.UTC),
+		}},
+	}
+	fileRepo := &masterSettingsFileRepoMock{
+		getByIDRow: &filemanager.File{
+			ID:                 logoFileID,
+			ObjectKey:          "branding/company-logo.svg",
+			Status:             filemanager.FileStatusReady,
+			MimeType:           "image/svg+xml",
+			ThumbnailMimeType:  &thumbMime,
+			ThumbnailObjectKey: &thumbKey,
+			UpdatedAt:          time.Date(2026, time.April, 2, 0, 0, 0, 0, time.UTC),
+		},
+	}
+	storage := &masterSettingsStorageMock{presignURL: upstream.URL}
+
+	h := NewBrandingHandler(msSvc, newMasterSettingsFileService(fileRepo), storage)
+	app := newBrandingTestApp(h)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/public/branding/email-logo", nil)
+	resp, body := doBrandingRequest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if !bytes.Equal(body, logoBytes) {
+		t.Fatalf("unexpected email logo body: %q", string(body))
+	}
+	if got := resp.Header.Get("Content-Type"); !strings.Contains(got, "image/png") {
+		t.Fatalf("expected image/png, got %q", got)
+	}
+	if storage.lastKey != thumbKey {
+		t.Fatalf("expected thumbnail object key, got %q", storage.lastKey)
+	}
+}
+
+func TestBrandingHandlerGetEmailLogoFallsBackFromSVG(t *testing.T) {
+	logoFileID := uuidv7.MustBytes()
+	msSvc := &masterSettingsServiceMock{
+		listRows: []mastersettings.MasterSettings{{
+			ID:         uuidv7.MustBytes(),
+			LogoFileID: logoFileID,
+			UpdatedAt:  time.Date(2026, time.April, 1, 0, 0, 0, 0, time.UTC),
+		}},
+	}
+	fileRepo := &masterSettingsFileRepoMock{
+		getByIDRow: &filemanager.File{
+			ID:        logoFileID,
+			ObjectKey: "branding/company-logo.svg",
+			Status:    filemanager.FileStatusReady,
+			MimeType:  "image/svg+xml",
+			UpdatedAt: time.Date(2026, time.April, 2, 0, 0, 0, 0, time.UTC),
+		},
+	}
+	h := NewBrandingHandler(msSvc, newMasterSettingsFileService(fileRepo), &masterSettingsStorageMock{})
+	app := newBrandingTestApp(h)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/public/branding/email-logo", nil)
+	resp, body := doBrandingRequest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if got := resp.Header.Get("Content-Type"); !strings.Contains(got, "image/png") {
+		t.Fatalf("expected image/png fallback, got %q", got)
+	}
+	if len(body) == 0 {
+		t.Fatalf("expected png fallback body")
+	}
+}
+
+func TestBrandingHandlerGetLogoFallbackWhenPresignFails(t *testing.T) {
+	logoFileID := uuidv7.MustBytes()
+	msSvc := &masterSettingsServiceMock{
+		listRows: []mastersettings.MasterSettings{{
+			ID:         uuidv7.MustBytes(),
+			LogoFileID: logoFileID,
+			UpdatedAt:  time.Date(2026, time.April, 1, 0, 0, 0, 0, time.UTC),
+		}},
+	}
+	fileRepo := &masterSettingsFileRepoMock{
+		getByIDRow: &filemanager.File{
+			ID:        logoFileID,
+			ObjectKey: "branding/company-logo.png",
+			Status:    filemanager.FileStatusReady,
+			MimeType:  "image/png",
+		},
+	}
+	storage := &masterSettingsStorageMock{presignErr: errors.New("presign failed")}
+	h := NewBrandingHandler(msSvc, newMasterSettingsFileService(fileRepo), storage)
+	app := newBrandingTestApp(h)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/branding/logo", nil)
+	resp, body := doBrandingRequest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if got := resp.Header.Get("Cache-Control"); got != brandingFallbackCache {
+		t.Fatalf("expected fallback cache-control, got %q", got)
+	}
+	if !strings.Contains(string(body), "COMPANY") {
+		t.Fatalf("expected default logo body, got %q", string(body))
+	}
+}
+
+func TestBrandingHandlerGetLoginCoverManagedSuccess(t *testing.T) {
+	coverBytes := []byte("COVERDATA")
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/jpeg")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(coverBytes)
+	}))
+	defer upstream.Close()
+
+	coverFileID := uuidv7.MustBytes()
+	msSvc := &masterSettingsServiceMock{
+		listRows: []mastersettings.MasterSettings{{
+			ID:          uuidv7.MustBytes(),
+			CoverFileID: coverFileID,
+			UpdatedAt:   time.Date(2026, time.April, 1, 0, 0, 0, 0, time.UTC),
+		}},
+	}
+	fileRepo := &masterSettingsFileRepoMock{
+		getByIDRow: &filemanager.File{
+			ID:            coverFileID,
+			ObjectKey:     "branding/login-cover.jpg",
+			Status:        filemanager.FileStatusReady,
+			MimeType:      "image/jpeg",
+			ETag:          "etag-cover-1",
+			ObjectVersion: "v1",
+			UpdatedAt:     time.Date(2026, time.April, 2, 0, 0, 0, 0, time.UTC),
+		},
+	}
+	storage := &masterSettingsStorageMock{presignURL: upstream.URL}
+	h := NewBrandingHandler(msSvc, newMasterSettingsFileService(fileRepo), storage)
+	app := newBrandingTestApp(h)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/branding/login-cover", nil)
+	resp, body := doBrandingRequest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if !bytes.Equal(body, coverBytes) {
+		t.Fatalf("unexpected cover body: %q", string(body))
+	}
+	if got := resp.Header.Get("Cache-Control"); got != brandingCoverManagedCacheControl {
+		t.Fatalf("expected managed cover cache-control, got %q", got)
+	}
+	if got := resp.Header.Get("Cross-Origin-Resource-Policy"); got != brandingCORPMode {
+		t.Fatalf("expected CORP header %q, got %q", brandingCORPMode, got)
+	}
+}
+
+func TestBrandingHandlerGetLoginCoverNotModifiedByLastModified(t *testing.T) {
+	coverBytes := []byte("COVERDATA")
+	upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/jpeg")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(coverBytes)
+	}))
+	defer upstream.Close()
+
+	coverFileID := uuidv7.MustBytes()
+	lastUpdated := time.Date(2026, time.April, 2, 10, 0, 0, 0, time.UTC)
+	msSvc := &masterSettingsServiceMock{
+		listRows: []mastersettings.MasterSettings{{
+			ID:          uuidv7.MustBytes(),
+			CoverFileID: coverFileID,
+			UpdatedAt:   lastUpdated,
+		}},
+	}
+	fileRepo := &masterSettingsFileRepoMock{
+		getByIDRow: &filemanager.File{
+			ID:        coverFileID,
+			ObjectKey: "branding/login-cover.jpg",
+			Status:    filemanager.FileStatusReady,
+			MimeType:  "image/jpeg",
+			UpdatedAt: lastUpdated,
+		},
+	}
+	storage := &masterSettingsStorageMock{presignURL: upstream.URL}
+	h := NewBrandingHandler(msSvc, newMasterSettingsFileService(fileRepo), storage)
+	app := newBrandingTestApp(h)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/branding/login-cover", nil)
+	req.Header.Set("If-Modified-Since", lastUpdated.Format(http.TimeFormat))
+	resp, body := doBrandingRequest(t, app, req)
+	if resp.StatusCode != http.StatusNotModified {
+		t.Fatalf("expected 304, got %d", resp.StatusCode)
+	}
+	if len(body) != 0 {
+		t.Fatalf("expected empty body, got %d bytes", len(body))
+	}
+}
+
+func TestBrandingHandlerGetLoginContentSuccessAndNotModified(t *testing.T) {
+	updatedAt := time.Date(2026, time.April, 16, 10, 30, 0, 0, time.UTC)
+	msSvc := &masterSettingsServiceMock{
+		listRows: []mastersettings.MasterSettings{{
+			ID:        uuidv7.MustBytes(),
+			Title:     "Welcome back",
+			Subtitle:  "Sign in to continue",
+			UpdatedAt: updatedAt,
+		}},
+	}
+	h := NewBrandingHandler(msSvc, nil, nil)
+	app := newBrandingTestApp(h)
+
+	req1, _ := http.NewRequest(http.MethodGet, "/api/v1/branding/login-content", nil)
+	resp1, body1 := doBrandingRequest(t, app, req1)
+	if resp1.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp1.StatusCode)
+	}
+	if !strings.Contains(string(body1), `"type":"login_branding"`) {
+		t.Fatalf("unexpected body: %s", string(body1))
+	}
+	if !strings.Contains(string(body1), `"version":"2026-04-16T10:30:00Z"`) {
+		t.Fatalf("expected version in body: %s", string(body1))
+	}
+	etag := strings.TrimSpace(resp1.Header.Get("ETag"))
+	if etag == "" {
+		t.Fatalf("expected etag header")
+	}
+
+	req2, _ := http.NewRequest(http.MethodGet, "/api/v1/branding/login-content", nil)
+	req2.Header.Set("If-None-Match", etag)
+	resp2, body2 := doBrandingRequest(t, app, req2)
+	if resp2.StatusCode != http.StatusNotModified {
+		t.Fatalf("expected 304, got %d", resp2.StatusCode)
+	}
+	if len(body2) != 0 {
+		t.Fatalf("expected empty body for 304, got %d bytes", len(body2))
+	}
+}
+
+func TestBrandingHandlerGetLoginContentFallbackDefaults(t *testing.T) {
+	msSvc := &masterSettingsServiceMock{
+		listRows: []mastersettings.MasterSettings{{
+			ID:        uuidv7.MustBytes(),
+			Title:     "",
+			Subtitle:  "",
+			UpdatedAt: time.Date(2026, time.April, 16, 10, 30, 0, 0, time.UTC),
+		}},
+	}
+	h := NewBrandingHandler(msSvc, nil, nil)
+	app := newBrandingTestApp(h)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/branding/login-content", nil)
+	resp, body := doBrandingRequest(t, app, req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if !strings.Contains(string(body), `"title":"Welcome back"`) {
+		t.Fatalf("expected default title, got %s", string(body))
+	}
+	if !strings.Contains(string(body), `"subtitle":"Sign in to continue"`) {
+		t.Fatalf("expected default subtitle, got %s", string(body))
+	}
+	if got := resp.Header.Get("Cache-Control"); got != brandingContentCacheControl {
+		t.Fatalf("expected content cache-control %q, got %q", brandingContentCacheControl, got)
+	}
+}
diff --git a/internal/transport/http/handlers/build_info_handler.go b/internal/transport/http/handlers/build_info_handler.go
new file mode 100644
index 0000000..ed7eeef
--- /dev/null
+++ b/internal/transport/http/handlers/build_info_handler.go
@@ -0,0 +1,21 @@
+package handlers
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/buildinfo"
+)
+
+type BuildInfoHandler struct{}
+
+func NewBuildInfoHandler() *BuildInfoHandler {
+	return &BuildInfoHandler{}
+}
+
+func (h *BuildInfoHandler) Handle(c *fiber.Ctx) error {
+	return c.Status(fiber.StatusOK).JSON(fiber.Map{
+		"version":   buildinfo.Version,
+		"commit":    buildinfo.Commit,
+		"buildTime": buildinfo.BuildTime,
+	})
+}
diff --git a/internal/transport/http/handlers/build_info_handler_test.go b/internal/transport/http/handlers/build_info_handler_test.go
new file mode 100644
index 0000000..9fa4dcc
--- /dev/null
+++ b/internal/transport/http/handlers/build_info_handler_test.go
@@ -0,0 +1,60 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/buildinfo"
+)
+
+func TestNewBuildInfoHandler(t *testing.T) {
+	h := NewBuildInfoHandler()
+	if h == nil {
+		t.Fatalf("expected build info handler instance")
+	}
+}
+
+func TestBuildInfoHandler_Handle(t *testing.T) {
+	origVersion := buildinfo.Version
+	origCommit := buildinfo.Commit
+	origBuildTime := buildinfo.BuildTime
+	t.Cleanup(func() {
+		buildinfo.Version = origVersion
+		buildinfo.Commit = origCommit
+		buildinfo.BuildTime = origBuildTime
+	})
+
+	buildinfo.Version = "dev"
+	buildinfo.Commit = "unknown"
+	buildinfo.BuildTime = "unknown"
+
+	h := NewBuildInfoHandler()
+	app := fiber.New()
+	app.Get("/api/build-info", h.Handle)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/build-info", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	var got map[string]string
+	if err := json.NewDecoder(resp.Body).Decode(&got); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if got["version"] != "dev" {
+		t.Fatalf("expected version dev, got %q", got["version"])
+	}
+	if got["commit"] != "unknown" {
+		t.Fatalf("expected commit unknown, got %q", got["commit"])
+	}
+	if got["buildTime"] != "unknown" {
+		t.Fatalf("expected buildTime unknown, got %q", got["buildTime"])
+	}
+}
diff --git a/internal/transport/http/handlers/complaint_handler.go b/internal/transport/http/handlers/complaint_handler.go
new file mode 100644
index 0000000..5dd39a8
--- /dev/null
+++ b/internal/transport/http/handlers/complaint_handler.go
@@ -0,0 +1,1341 @@
+package handlers
+
+import (
+	"context"
+	"log/slog"
+	"runtime/debug"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	actionsignoff "wucher/internal/domain/action_signoff"
+	complaint "wucher/internal/domain/complaint"
+	fleethistory "wucher/internal/domain/fleet_history"
+	"wucher/internal/domain/helicopter"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type ComplaintHandler struct {
+	svc           complaint.Service
+	helicopterSvc helicopter.Service
+	mcfSvc        mcfPendingChecker
+	historySvc    fleetHistoryRecorder
+	aogRecalc     aogRecalculator
+	signoffSvc    complaintSignoffManager
+	validate      *validators.Validator
+}
+
+// complaintSignoffLookup batch-loads the corrective-action sign-offs for complaints,
+// keyed by complaint id — the sign state now lives in action_signoff, not on the complaint.
+type complaintSignoffLookup interface {
+	GetByComplaintIDs(ctx context.Context, complaintIDs [][]byte) (map[string]*actionsignoff.ActionSignoff, error)
+}
+
+// complaintSignoffManager adds the write used when a complaint is updated: reopening a
+// (previously signed) complaint invalidates its sign-off, so it is unsigned.
+type complaintSignoffManager interface {
+	complaintSignoffLookup
+	UnsignByComplaint(ctx context.Context, complaintID []byte) (*actionsignoff.ActionSignoff, error)
+}
+
+type mcfPendingChecker interface {
+	PendingHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]bool, error)
+}
+
+type aogRecalculator interface {
+	RecalculateAOGByHelicopter(ctx context.Context, helicopterID []byte) error
+}
+
+func mcfPendingHelicopterSet(ctx context.Context, svc mcfPendingChecker, ids [][]byte) map[string]bool {
+	if svc == nil || len(ids) == 0 {
+		return map[string]bool{}
+	}
+	if set, err := svc.PendingHelicopterIDs(ctx, ids); err == nil && set != nil {
+		return set
+	}
+	return map[string]bool{}
+}
+
+func NewComplaintHandler(svc complaint.Service) *ComplaintHandler {
+	return &ComplaintHandler{svc: svc, validate: validators.New()}
+}
+
+func (h *ComplaintHandler) WithHelicopterService(svc helicopter.Service) *ComplaintHandler {
+	h.helicopterSvc = svc
+	return h
+}
+
+func (h *ComplaintHandler) WithMCFService(svc mcfPendingChecker) *ComplaintHandler {
+	h.mcfSvc = svc
+	return h
+}
+
+func (h *ComplaintHandler) WithAOGRecalculator(svc aogRecalculator) *ComplaintHandler {
+	h.aogRecalc = svc
+	return h
+}
+
+func (h *ComplaintHandler) WithHistoryService(svc fleetHistoryRecorder) *ComplaintHandler {
+	h.historySvc = svc
+	return h
+}
+
+func (h *ComplaintHandler) WithActionSignoffService(svc complaintSignoffManager) *ComplaintHandler {
+	h.signoffSvc = svc
+	return h
+}
+
+func (h *ComplaintHandler) complaintResource(ctx context.Context, row *complaint.Complaint, names map[string]string, signoffs map[string]*actionsignoff.ActionSignoff) responsedto.ComplaintResource {
+	if row == nil {
+		return responsedto.ComplaintResource{}
+	}
+	signoff := signoffs[string(row.ID)]
+	id, _ := uuidv7.BytesToString(row.ID)
+	reportedAt := ""
+	if !row.ReportedAt.IsZero() {
+		reportedAt = row.ReportedAt.UTC().Format(time.RFC3339)
+	}
+	createdAt := ""
+	if !row.CreatedAt.IsZero() {
+		createdAt = row.CreatedAt.UTC().Format(time.RFC3339)
+	}
+	updatedAt := ""
+	if !row.UpdatedAt.IsZero() {
+		updatedAt = row.UpdatedAt.UTC().Format(time.RFC3339)
+	}
+	out := responsedto.ComplaintResource{
+		Type: "complaint",
+		ID:   id,
+		Attributes: responsedto.ComplaintAttributes{
+			HelicopterID:          idString(row.HelicopterID),
+			FlightID:              idString(row.FlightID),
+			Description:           row.Description,
+			ReportedBy:            names[string(row.ReportedBy)],
+			ReportedByShort:       userctx.GetShortName(ctx, row.ReportedBy),
+			ReportedAt:            reportedAt,
+			AircraftHoursAtReport: row.AircraftHoursAtReport,
+			MEL: responsedto.ComplaintMEL{
+				Severity: row.MELSeverity,
+			},
+			NSR: responsedto.ComplaintNSR{
+				IsNSR:  row.IsNSR,
+				Reason: row.NSRReason,
+			},
+			ActionSigned:       signoff.IsSigned(),
+			ActionTaken:        row.ActionTaken,
+			AircraftHoursAtFix: row.AircraftHoursAtFix,
+			Status:             row.Status(),
+			CreatedAt:          createdAt,
+			UpdatedAt:          updatedAt,
+		},
+	}
+	if n := names[string(row.MELClassifiedBy)]; n != "" {
+		out.Attributes.MEL.ClassifiedByName = &n
+	}
+	if s := userctx.GetShortName(ctx, row.MELClassifiedBy); s != "" {
+		out.Attributes.MEL.ClassifiedByShort = &s
+	}
+	if signoff != nil {
+		if n := names[string(signoff.SignedBy)]; n != "" {
+			out.Attributes.ActionSignedByName = &n
+		}
+		if s := userctx.GetShortName(ctx, signoff.SignedBy); s != "" {
+			out.Attributes.ActionSignedByShort = &s
+		}
+	}
+	// Only show a severity label once classified — a pending complaint's severity 0 is a
+	// default, not a "Non-MEL" decision, so it must not render as such.
+	if row.MELClassifiedAt != nil {
+		v := row.MELClassifiedAt.UTC().Format(time.RFC3339)
+		out.Attributes.MEL.ClassifiedAt = &v
+		if label := complaintSeverityLabel(row.MELSeverity); label != "" {
+			out.Attributes.MEL.SeverityLabel = &label
+		}
+	}
+	if dl := row.MELDeadline(); dl != nil {
+		v := dl.UTC().Format(time.RFC3339)
+		out.Attributes.MEL.Deadline = &v
+	}
+	if row.NSRDecidedAt != nil {
+		v := row.NSRDecidedAt.UTC().Format(time.RFC3339)
+		out.Attributes.NSR.DecidedAt = &v
+	}
+	if n := names[string(row.NSRDecidedBy)]; n != "" {
+		out.Attributes.NSR.DecidedByName = &n
+	}
+	if s := userctx.GetShortName(ctx, row.NSRDecidedBy); s != "" {
+		out.Attributes.NSR.DecidedByShort = &s
+	}
+	if signoff != nil && signoff.SignedAt != nil {
+		v := signoff.SignedAt.UTC().Format(time.RFC3339)
+		out.Attributes.ActionSignedAt = &v
+	}
+	return out
+}
+
+func complaintHelicopterKey(row *complaint.Complaint) string {
+	if row == nil || len(row.HelicopterID) == 0 {
+		return "unknown"
+	}
+	return string(row.HelicopterID)
+}
+
+// CreateComplaint godoc
+// @Summary Create complaint
+// @Description Create a complaint (defect) for a flight inspection.
+// @Description MEL severity (mel_severity, OPTIONAL): omit it to file a "pending_mel" complaint and classify later (via PATCH /complaints/update/{id}); it MUST be classified before recording action taken. A pending complaint does NOT ground the aircraft — grounding starts at classification. Values: 0 = NON-MEL (grounds immediately); 1 = A (1 day grace); 2 = B (3 days); 3 = C (10 days); 4 = D (120 days). After the grace period passes without action the aircraft becomes AOG.
+// @Description NSR (Non-Safety Release) is its own flow — sign it at POST /api/v1/complaints/nsr/sign/{id} (cancel at /nsr/unsign/{id}); it is no longer set via create/update.
+// @Description Optional fields: aircraft_hours_at_report.
+// @Description To record the corrective action, use POST /api/v1/complaints/action-taken/create/{id} (a separate, explicitly-signed step) — it is no longer part of create/update.
+// @Tags Complaints
+// @Accept json
+// @Produce json
+// @Param request body requestdto.ComplaintCreateRequest true "JSON:API complaint create request"
+// @Success 201 {object} responsedto.ComplaintResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/complaints/create [post]
+func (h *ComplaintHandler) Create(c *fiber.Ctx) error {
+	var req requestdto.ComplaintCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeBodyParseError(c, err, apperrorsx.ErrComplaintInvalidJSON)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeComplaintErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	helicopterID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.HelicopterID))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/helicopter_id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	var flightID []byte
+	if raw := strings.TrimSpace(req.Data.Attributes.FlightID); raw != "" {
+		flightID, err = uuidv7.ParseString(raw)
+		if err != nil {
+			appErr := apperrorsx.New(apperrorsx.ErrComplaintInvalidUUID).WithCause(err)
+			appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_id"}
+			return apperrorsx.Write(c, appErr)
+		}
+	}
+	// An aircraft may carry several open defects at once (each its own hold item with
+	// its own MEL grace), so a new complaint is NOT blocked by existing open ones —
+	// consistent with the AOG/gate logic which already handles a list of open complaints.
+	// NSR is not decided here — it is its own flow (POST /complaints/nsr/sign/{id}).
+	row := &complaint.Complaint{
+		HelicopterID:          helicopterID,
+		FlightID:              flightID,
+		Description:           strings.TrimSpace(req.Data.Attributes.Description),
+		ReportedBy:            actorUserID(c),
+		ReportedAt:            time.Now().UTC(),
+		AircraftHoursAtReport: req.Data.Attributes.AircraftHoursAtReport,
+		CreatedBy:             actorUserID(c),
+		UpdatedBy:             actorUserID(c),
+	}
+	if row.Description == "" {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintInvalidPayload)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/description"}
+		return apperrorsx.Write(c, appErr)
+	}
+	now := time.Now().UTC()
+	actor := actorUserID(c)
+	// mel_severity is optional at creation: when provided the complaint is classified
+	// immediately; when omitted it stays "pending_mel" (mel_classified_at NULL) — it does
+	// NOT ground the aircraft yet (an unassessed report isn't a grounding defect), and it
+	// must be classified before action taken can be recorded.
+	if req.Data.Attributes.MELSeverity != nil {
+		row.MELSeverity = *req.Data.Attributes.MELSeverity
+		row.MELClassifiedAt = &now
+		row.MELClassifiedBy = append([]byte(nil), actor...)
+	}
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintCreateFailed))
+	}
+	created, _ := h.svc.GetByID(c.UserContext(), row.ID)
+	if created == nil {
+		created = row
+	}
+	h.recordComplaintFiled(c, created)
+	if h.aogRecalc != nil {
+		_ = h.aogRecalc.RecalculateAOGByHelicopter(c.UserContext(), created.HelicopterID)
+	}
+	names := h.resolveComplaintNames(c.UserContext(), []complaint.Complaint{*created})
+	signoffs := h.resolveComplaintSignoffs(c.UserContext(), []complaint.Complaint{*created}, names)
+	res := h.complaintResource(c.UserContext(), created, names, signoffs)
+	res.Attributes.Helicopter = h.complaintHelicopterObject(c.UserContext(), created.HelicopterID)
+	return response.Write(c, fiber.StatusCreated, responsedto.ComplaintResponse{Data: res})
+}
+
+// GetComplaint godoc
+// @Summary Get complaint by ID
+// @Tags Complaints
+// @Produce json
+// @Param id path string true "Complaint ID (UUIDv7)"
+// @Success 200 {object} responsedto.ComplaintResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/complaints/get/{id} [get]
+func (h *ComplaintHandler) GetByID(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		return writeComplaintErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "id is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/path/id"}}})
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintNotFound))
+	}
+	if row == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintNotFound))
+	}
+	names := h.resolveComplaintNames(c.UserContext(), []complaint.Complaint{*row})
+	signoffs := h.resolveComplaintSignoffs(c.UserContext(), []complaint.Complaint{*row}, names)
+	res := h.complaintResource(c.UserContext(), row, names, signoffs)
+	res.Attributes.Helicopter = h.complaintHelicopterObject(c.UserContext(), row.HelicopterID)
+	return response.Write(c, fiber.StatusOK, responsedto.ComplaintResponse{Data: res})
+}
+
+// UpdateComplaint godoc
+// @Summary Update complaint
+// @Description Update a complaint. All attributes optional; only provided fields change.
+// @Description mel_severity: 0 = NON-MEL (immediate AOG); 1 = A (1 day); 2 = B (3 days); 3 = C (10 days); 4 = D (120 days) — AOG after grace passes.
+// @Description NSR is not set here — it is its own flow: POST /api/v1/complaints/nsr/sign/{id} (and /nsr/unsign/{id}).
+// @Description Note: the corrective action is recorded via POST /api/v1/complaints/action-taken/create/{id} (a separate, signed step), not here.
+// @Tags Complaints
+// @Accept json
+// @Produce json
+// @Param id path string true "Complaint ID (UUIDv7)"
+// @Param request body requestdto.ComplaintUpdateRequest true "JSON:API complaint update request"
+// @Success 200 {object} responsedto.ComplaintResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/complaints/update/{id} [patch]
+func (h *ComplaintHandler) Update(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	var req requestdto.ComplaintUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		if appErr := bodyParseError(err); appErr != nil {
+			return apperrorsx.Write(c, appErr)
+		}
+		return writeComplaintErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeComplaintErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if strings.TrimSpace(req.Data.ID) == "" {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintIDRequired)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	if strings.TrimSpace(req.Data.ID) != strings.TrimSpace(c.Params("id")) {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintIDMismatch)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintNotFound))
+	}
+	if row == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintNotFound))
+	}
+	// NSR is decided via its own endpoint (POST /complaints/nsr/sign|unsign/{id}); the
+	// shared update no longer touches it.
+	if req.Data.Attributes.Description != nil {
+		v := strings.TrimSpace(*req.Data.Attributes.Description)
+		if v == "" {
+			appErr := apperrorsx.New(apperrorsx.ErrComplaintInvalidPayload)
+			appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/description"}
+			return apperrorsx.Write(c, appErr)
+		}
+		row.Description = v
+	}
+	if req.Data.Attributes.MELSeverity != nil {
+		row.MELSeverity = *req.Data.Attributes.MELSeverity
+		now := time.Now().UTC()
+		row.MELClassifiedAt = &now
+		row.MELClassifiedBy = append([]byte(nil), actorUserID(c)...)
+	}
+	if req.Data.Attributes.AircraftHoursAtReport != nil {
+		row.AircraftHoursAtReport = req.Data.Attributes.AircraftHoursAtReport
+	}
+	row.UpdatedBy = actorUserID(c)
+	// Updating a complaint reopens its lifecycle: a previously closed complaint is
+	// unfixed (AOG is recomputed below, re-grounding the aircraft) so a new EASA
+	// release is required; the old release stays as history.
+	if row.FixedAt != nil {
+		row.FixedAt = nil
+		row.FixedByEASAID = nil
+	}
+	if err := h.svc.Update(c.UserContext(), row); err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintUpdateFailed))
+	}
+	// The change invalidates any corrective-action sign-off: it must be re-recorded and
+	// re-signed. No-op when the complaint was never signed off.
+	if h.signoffSvc != nil {
+		_, _ = h.signoffSvc.UnsignByComplaint(c.UserContext(), row.ID)
+	}
+	if h.aogRecalc != nil {
+		_ = h.aogRecalc.RecalculateAOGByHelicopter(c.UserContext(), row.HelicopterID)
+	}
+	updated, _ := h.svc.GetByID(c.UserContext(), id)
+	if updated == nil {
+		updated = row
+	}
+	h.recordComplaintUpdate(c, req.Data.Attributes, updated)
+	names := h.resolveComplaintNames(c.UserContext(), []complaint.Complaint{*updated})
+	signoffs := h.resolveComplaintSignoffs(c.UserContext(), []complaint.Complaint{*updated}, names)
+	res := h.complaintResource(c.UserContext(), updated, names, signoffs)
+	res.Attributes.Helicopter = h.complaintHelicopterObject(c.UserContext(), updated.HelicopterID)
+	return response.Write(c, fiber.StatusOK, responsedto.ComplaintResponse{Data: res})
+}
+
+// ComplaintActionTaken godoc
+// @Summary Record the corrective action for a complaint
+// @Description Records the corrective action text taken for a complaint. Recording the action does NOT sign it and does NOT lift the AOG grounding: signing the action is a separate step at POST /api/v1/action-signoffs/sign/{helicopter_id} (send complaint_id), and returning the aircraft to service requires a formal release (a signed EASA release / CRS, or an NSR). The complaint stays open until an EASA release fixes it.
+// @Tags Complaints
+// @Accept json
+// @Produce json
+// @Param id path string true "Complaint ID (UUIDv7)"
+// @Param request body requestdto.ComplaintActionTakenRequest true "Action taken payload"
+// @Success 200 {object} responsedto.ComplaintResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/complaints/action-taken/create/{id} [post]
+func (h *ComplaintHandler) ActionTaken(c *fiber.Ctx) error {
+	return h.applyActionTaken(c, false)
+}
+
+// UpdateComplaintActionTaken godoc
+// @Summary Update the recorded corrective action for a complaint
+// @Description Updates the previously-recorded corrective action text of a complaint. Recording/updating the action does NOT sign it — signing is a separate step at POST /api/v1/action-signoffs/sign/{helicopter_id} (send complaint_id).
+// @Tags Complaints
+// @Accept json
+// @Produce json
+// @Param id path string true "Complaint ID (UUIDv7)"
+// @Param request body requestdto.ComplaintActionTakenRequest true "Action taken payload"
+// @Success 200 {object} responsedto.ComplaintResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/complaints/action-taken/update/{id} [patch]
+func (h *ComplaintHandler) UpdateActionTaken(c *fiber.Ctx) error {
+	return h.applyActionTaken(c, true)
+}
+
+func (h *ComplaintHandler) applyActionTaken(c *fiber.Ctx, allowClear bool) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	var req requestdto.ComplaintActionTakenRequest
+	if err := c.BodyParser(&req); err != nil {
+		if appErr := bodyParseError(err); appErr != nil {
+			return apperrorsx.Write(c, appErr)
+		}
+		return writeComplaintErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeComplaintErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	action := strings.TrimSpace(req.Data.Attributes.ActionTaken)
+	// Empty action_taken clears it. Clearing is allowed only on update and only while the
+	// action has not been signed off yet; recording (create) still requires a value.
+	if action == "" && !allowClear {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintInvalidPayload)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/action_taken"}
+		return apperrorsx.Write(c, appErr)
+	}
+
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintNotFound))
+	}
+	if row == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintNotFound))
+	}
+	// MEL must be classified before a corrective action can be recorded: a "pending_mel"
+	// defect has no agreed severity/deferral, so acting on it is premature. Classify it
+	// first via PATCH /complaints/update/{id} (mel_severity).
+	if row.MELClassifiedAt == nil {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintMELRequired)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/mel_severity"}
+		return apperrorsx.Write(c, appErr)
+	}
+
+	actor := actorUserID(c)
+	// Record only the action text here; signing is done at POST /action-signoffs/sign
+	// (with complaint_id). Empty clears it — but a signed-off action cannot be cleared.
+	if action == "" {
+		if h.signoffSvc != nil {
+			if signoffs, serr := h.signoffSvc.GetByComplaintIDs(c.UserContext(), [][]byte{id}); serr == nil {
+				if so := signoffs[string(id)]; so != nil && so.IsSigned() {
+					appErr := apperrorsx.New(apperrorsx.ErrComplaintActionSignedLocked)
+					appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/action_taken"}
+					return apperrorsx.Write(c, appErr)
+				}
+			}
+		}
+		row.ActionTaken = nil
+	} else {
+		row.ActionTaken = &action
+	}
+	if req.Data.Attributes.AircraftHoursAtFix != nil {
+		row.AircraftHoursAtFix = emptyToNilString(req.Data.Attributes.AircraftHoursAtFix)
+	}
+	row.UpdatedBy = actor
+	if err := h.svc.Update(c.UserContext(), row); err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintUpdateFailed))
+	}
+	if h.aogRecalc != nil {
+		_ = h.aogRecalc.RecalculateAOGByHelicopter(c.UserContext(), row.HelicopterID)
+	}
+	updated, _ := h.svc.GetByID(c.UserContext(), id)
+	if updated == nil {
+		updated = row
+	}
+	if h.historySvc != nil {
+		msg := "Action taken cleared"
+		if action != "" {
+			msg = "Action taken — " + action
+		}
+		_ = h.historySvc.Record(c.UserContext(), updated.HelicopterID, fleethistory.EntityComplaint, updated.ID, fleethistory.ActionActionTaken, msg, actor)
+	}
+	names := h.resolveComplaintNames(c.UserContext(), []complaint.Complaint{*updated})
+	signoffs := h.resolveComplaintSignoffs(c.UserContext(), []complaint.Complaint{*updated}, names)
+	res := h.complaintResource(c.UserContext(), updated, names, signoffs)
+	res.Attributes.Helicopter = h.complaintHelicopterObject(c.UserContext(), updated.HelicopterID)
+	return response.Write(c, fiber.StatusOK, responsedto.ComplaintResponse{Data: res})
+}
+
+// NSRSign godoc
+// @Summary Sign a Non-Safety Release (NSR / MEL deferral) for a complaint
+// @Description Records an NSR decision on its own flow (separate from complaint update): the aircraft is released to fly despite the open defect and is no longer grounded by it. MEL must be classified first — an unassessed (pending_mel) defect cannot be deferred, so a pending complaint returns 422. The complaint stays OPEN and is only closed by a signed EASA release. Requires the complaint.nsr permission.
+// @Tags Complaints
+// @Accept json
+// @Produce json
+// @Param id path string true "Complaint ID (UUIDv7)"
+// @Param request body requestdto.ComplaintNSRSignRequest false "Optional NSR reason"
+// @Success 200 {object} responsedto.ComplaintResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/complaints/nsr/sign/{id} [post]
+func (h *ComplaintHandler) NSRSign(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	var req requestdto.ComplaintNSRSignRequest
+	// Body is optional (reason only); tolerate an empty body.
+	_ = c.BodyParser(&req)
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintNotFound))
+	}
+	if row == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintNotFound))
+	}
+	// NSR is a MEL deferral: the defect must be classified before it can be deferred.
+	if row.MELClassifiedAt == nil {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintMELRequired)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/mel_severity"}
+		return apperrorsx.Write(c, appErr)
+	}
+	now := time.Now().UTC()
+	actor := actorUserID(c)
+	row.IsNSR = true
+	row.NSRDecidedAt = &now
+	row.NSRDecidedBy = append([]byte(nil), actor...)
+	if req.Data.Attributes.NSRReason != nil {
+		row.NSRReason = emptyToNilString(req.Data.Attributes.NSRReason)
+	}
+	row.UpdatedBy = actor
+	if err := h.svc.Update(c.UserContext(), row); err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintUpdateFailed))
+	}
+	if h.aogRecalc != nil {
+		_ = h.aogRecalc.RecalculateAOGByHelicopter(c.UserContext(), row.HelicopterID)
+	}
+	updated, _ := h.svc.GetByID(c.UserContext(), id)
+	if updated == nil {
+		updated = row
+	}
+	if h.historySvc != nil {
+		_ = h.historySvc.Record(c.UserContext(), updated.HelicopterID, fleethistory.EntityComplaint, updated.ID, fleethistory.ActionNSRDone, nsrLogMessage(updated), actor)
+	}
+	names := h.resolveComplaintNames(c.UserContext(), []complaint.Complaint{*updated})
+	signoffs := h.resolveComplaintSignoffs(c.UserContext(), []complaint.Complaint{*updated}, names)
+	res := h.complaintResource(c.UserContext(), updated, names, signoffs)
+	res.Attributes.Helicopter = h.complaintHelicopterObject(c.UserContext(), updated.HelicopterID)
+	return response.Write(c, fiber.StatusOK, responsedto.ComplaintResponse{Data: res})
+}
+
+// NSRUnsign godoc
+// @Summary Cancel a Non-Safety Release for a complaint
+// @Description Revokes the NSR decision: the deferral is lifted, so the still-open defect grounds the aircraft again (AOG is recomputed). Requires the complaint.nsr permission.
+// @Tags Complaints
+// @Produce json
+// @Param id path string true "Complaint ID (UUIDv7)"
+// @Success 200 {object} responsedto.ComplaintResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Router /api/v1/complaints/nsr/unsign/{id} [post]
+func (h *ComplaintHandler) NSRUnsign(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintNotFound))
+	}
+	if row == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintNotFound))
+	}
+	actor := actorUserID(c)
+	row.IsNSR = false
+	row.NSRDecidedAt = nil
+	row.NSRDecidedBy = nil
+	row.NSRReason = nil
+	row.UpdatedBy = actor
+	if err := h.svc.Update(c.UserContext(), row); err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintUpdateFailed))
+	}
+	if h.aogRecalc != nil {
+		_ = h.aogRecalc.RecalculateAOGByHelicopter(c.UserContext(), row.HelicopterID)
+	}
+	updated, _ := h.svc.GetByID(c.UserContext(), id)
+	if updated == nil {
+		updated = row
+	}
+	if h.historySvc != nil {
+		_ = h.historySvc.Record(c.UserContext(), updated.HelicopterID, fleethistory.EntityComplaint, updated.ID, fleethistory.ActionNSRCancelled, "NSR cancelled", actor)
+	}
+	names := h.resolveComplaintNames(c.UserContext(), []complaint.Complaint{*updated})
+	signoffs := h.resolveComplaintSignoffs(c.UserContext(), []complaint.Complaint{*updated}, names)
+	res := h.complaintResource(c.UserContext(), updated, names, signoffs)
+	res.Attributes.Helicopter = h.complaintHelicopterObject(c.UserContext(), updated.HelicopterID)
+	return response.Write(c, fiber.StatusOK, responsedto.ComplaintResponse{Data: res})
+}
+
+// DeleteComplaint godoc
+// @Summary Delete complaint
+// @Tags Complaints
+// @Produce json
+// @Param id path string true "Complaint ID (UUIDv7)"
+// @Success 200 {object} jsonapi.Document
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Router /api/v1/complaints/delete/{id} [delete]
+func (h *ComplaintHandler) Delete(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	existing, _ := h.svc.GetByID(c.UserContext(), id)
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintDeleteFailed))
+	}
+	if h.aogRecalc != nil && existing != nil {
+		_ = h.aogRecalc.RecalculateAOGByHelicopter(c.UserContext(), existing.HelicopterID)
+	}
+	return response.Write(c, fiber.StatusOK, map[string]any{"data": map[string]any{"type": "complaint_delete", "attributes": map[string]bool{"deleted": true}}})
+}
+
+// ListComplaints godoc
+// @Summary List complaints
+// @Description Lists complaints grouped by helicopter. Filter by date range on the reported date, by the name of an involved person (reporter / MEL classifier / action signer / NSR decider — i.e. pilot/techniker), and by free-text search on the complaint description.
+// @Tags Complaints
+// @Produce json
+// @Param search query string false "Search complaint description"
+// @Param date_from query string false "Reported date lower bound (YYYY-MM-DD)"
+// @Param date_to query string false "Reported date upper bound (YYYY-MM-DD)"
+// @Param person query string false "Involved person name (pilot/techniker, partial match)"
+// @Param helicopter_id query string false "Filter by helicopter ID (UUIDv7)"
+// @Param sort query string false "Sort complaints"
+// @Param page query int false "Page number" default(1)
+// @Param page_size query int false "Page size" default(20)
+// @Success 200 {object} responsedto.ComplaintGroupedListResponse
+// @Router /api/v1/complaints/get-all [get]
+func (h *ComplaintHandler) List(c *fiber.Ctx) (err error) {
+	if h == nil || h.svc == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintListFailed))
+	}
+	defer func() {
+		if r := recover(); r != nil {
+			slog.ErrorContext(c.UserContext(), "complaint list panic", "panic", r, "stack", string(debug.Stack()), "path", c.Path())
+			err = apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintListFailed).WithCause(nil))
+		}
+	}()
+	page := intOrDefaultFromString(c.Query("page"), 1)
+	if page < 1 {
+		page = 1
+	}
+	size := intOrDefaultFromString(c.Query("page_size"), 20)
+	if size < 1 {
+		size = 20
+	}
+	filter, verr := complaintListFilterFromQuery(c)
+	if verr != nil {
+		return writeComplaintErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*verr})
+	}
+	groups, total, err := h.groupedList(c.UserContext(), filter, strings.TrimSpace(c.Query("sort")), 0, 0, nil)
+	if err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintListFailed))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, groups, map[string]any{
+		"page_number": page,
+		"page_size":   size,
+		"total":       total,
+	})
+}
+
+// ListHoldItems godoc
+// @Summary List hold items (open MEL-deferred defects)
+// @Description Returns the Hold Item List (HIL): complaints that are still OPEN (not yet fixed by an EASA release) AND MEL-deferred (mel_severity > 0). Non-MEL defects (which ground the aircraft immediately) and already-serviced complaints are excluded. Same grouped shape and filters as get-all.
+// @Tags Complaints
+// @Produce json
+// @Param date_from query string false "From date — reported_at >= (YYYY-MM-DD). Legacy 'Von'."
+// @Param date_to query string false "To date — reported_at <= (YYYY-MM-DD). Legacy 'bis'."
+// @Param person query string false "Pilot/Technician name — matches reporter or action signer. Legacy 'Pilot/Techniker'."
+// @Param search query string false "Search complaint description / MEL. Legacy 'Complains'."
+// @Param helicopter_id query string false "Helicopter ID (UUIDv7)"
+// @Param page query int false "Page number (default 1)"
+// @Param page_size query int false "Page size (default 20)"
+// @Param sort query string false "Sort expression (e.g. reported_at DESC)"
+// @Success 200 {object} responsedto.ComplaintGroupedListResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/complaints/hold-items/get-all [get]
+func (h *ComplaintHandler) ListHoldItems(c *fiber.Ctx) (err error) {
+	if h == nil || h.svc == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintListFailed))
+	}
+	defer func() {
+		if r := recover(); r != nil {
+			slog.ErrorContext(c.UserContext(), "complaint hold-items panic", "panic", r, "stack", string(debug.Stack()), "path", c.Path())
+			err = apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintListFailed).WithCause(nil))
+		}
+	}()
+	page := intOrDefaultFromString(c.Query("page"), 1)
+	if page < 1 {
+		page = 1
+	}
+	size := intOrDefaultFromString(c.Query("page_size"), 20)
+	if size < 1 {
+		size = 20
+	}
+	filter, verr := complaintListFilterFromQuery(c)
+	if verr != nil {
+		return writeComplaintErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*verr})
+	}
+	filter.HoldItemsOnly = true
+	groups, total, err := h.groupedList(c.UserContext(), filter, strings.TrimSpace(c.Query("sort")), 0, 0, nil)
+	if err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintListFailed))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, groups, map[string]any{
+		"page_number": page,
+		"page_size":   size,
+		"total":       total,
+	})
+}
+
+// ListHoldItemsDatatable godoc
+// @Summary List hold items (open MEL-deferred defects) — datatable
+// @Description Datatable variant of the Hold Item List (open + MEL-deferred complaints). Same filters as /hold-items/get-all (date_from, date_to, person, search, helicopter_id) plus DataTables params (start, length, draw).
+// @Tags Complaints
+// @Produce json
+// @Param date_from query string false "From date — reported_at >= (YYYY-MM-DD). Legacy 'Von'."
+// @Param date_to query string false "To date — reported_at <= (YYYY-MM-DD). Legacy 'bis'."
+// @Param person query string false "Pilot/Technician name — matches reporter or action signer."
+// @Param search query string false "Search complaint description / MEL."
+// @Param helicopter_id query string false "Helicopter ID (UUIDv7)"
+// @Param start query int false "DataTables start offset"
+// @Param length query int false "DataTables page length"
+// @Param draw query int false "DataTables draw counter"
+// @Success 200 {object} responsedto.ComplaintGroupedListResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/complaints/hold-items/get-all/dt [get]
+func (h *ComplaintHandler) ListHoldItemsDatatable(c *fiber.Ctx) (err error) {
+	if h == nil || h.svc == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintListFailed))
+	}
+	defer func() {
+		if r := recover(); r != nil {
+			slog.ErrorContext(c.UserContext(), "complaint hold-items datatable panic", "panic", r, "stack", string(debug.Stack()), "path", c.Path())
+			err = apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintListFailed).WithCause(nil))
+		}
+	}()
+	start := intOrDefaultFromString(c.Query("start"), 0)
+	length := intOrDefaultFromString(c.Query("length"), 10)
+	draw := intOrDefaultFromString(c.Query("draw"), 1)
+	filter, verr := complaintListFilterFromQuery(c)
+	if verr != nil {
+		return writeComplaintErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*verr})
+	}
+	filter.HoldItemsOnly = true
+	groups, total, err := h.groupedList(c.UserContext(), filter, strings.TrimSpace(c.Query("sort")), length, start, nil)
+	if err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintListFailed))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, groups, map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	})
+}
+
+// @Summary List complaints grouped by helicopter (datatable)
+// @Tags Complaints
+// @Produce json
+// @Param search query string false "Search complaint description"
+// @Param date_from query string false "Reported date lower bound (YYYY-MM-DD)"
+// @Param date_to query string false "Reported date upper bound (YYYY-MM-DD)"
+// @Param person query string false "Involved person name (pilot/techniker, partial match)"
+// @Param helicopter_id query string false "Filter by helicopter ID (UUIDv7)"
+// @Param sort query string false "Sort complaints"
+// @Param draw query int false "Datatable draw counter" default(1)
+// @Param start query int false "Datatable start offset" default(0)
+// @Param length query int false "Datatable page length" default(10)
+// @Success 200 {object} responsedto.ComplaintGroupedDataTableResponse
+// @Router /api/v1/complaints/get-all/dt [get]
+func (h *ComplaintHandler) ListDatatable(c *fiber.Ctx) (err error) {
+	if h == nil || h.svc == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintListFailed))
+	}
+	defer func() {
+		if r := recover(); r != nil {
+			slog.ErrorContext(c.UserContext(), "complaint datatable panic", "panic", r, "stack", string(debug.Stack()), "path", c.Path())
+			err = apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintListFailed).WithCause(nil))
+		}
+	}()
+	start := intOrDefaultFromString(c.Query("start"), 0)
+	length := intOrDefaultFromString(c.Query("length"), 10)
+	draw := intOrDefaultFromString(c.Query("draw"), 1)
+	filter, verr := complaintListFilterFromQuery(c)
+	if verr != nil {
+		return writeComplaintErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*verr})
+	}
+	groups, total, err := h.groupedList(c.UserContext(), filter, strings.TrimSpace(c.Query("sort")), length, start, nil)
+	if err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintListFailed))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, groups, map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	})
+}
+
+// @Summary List complaints by helicopter
+// @Tags Complaints
+// @Produce json
+// @Param helicopter_id path string true "Helicopter ID"
+// @Success 200 {object} responsedto.ComplaintGroupedListResponse
+// @Router /api/v1/complaints/get-by-helicopter/{helicopter_id} [get]
+func (h *ComplaintHandler) ListByHelicopter(c *fiber.Ctx) (err error) {
+	if h == nil || h.svc == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintGroupedListFailed))
+	}
+	defer func() {
+		if r := recover(); r != nil {
+			slog.ErrorContext(c.UserContext(), "complaint list by helicopter panic", "panic", r, "stack", string(debug.Stack()), "path", c.Path())
+			err = apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrComplaintGroupedListFailed).WithCause(nil))
+		}
+	}()
+	helicopterID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("helicopter_id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrComplaintInvalidHelicopterID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/helicopter_id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	page := intOrDefaultFromString(c.Query("page"), 1)
+	if page < 1 {
+		page = 1
+	}
+	size := intOrDefaultFromString(c.Query("page_size"), 20)
+	if size < 1 {
+		size = 20
+	}
+	groups, total, err := h.groupedList(c.UserContext(), complaint.ListFilter{Search: strings.TrimSpace(c.Query("filter"))}, strings.TrimSpace(c.Query("sort")), 0, 0, helicopterID)
+	if err != nil {
+		return apperrorsx.Write(c, mapComplaintServiceErrorWithFallback(err, apperrorsx.ErrComplaintGroupedListFailed))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, groups, map[string]any{
+		"page_number": page,
+		"page_size":   size,
+		"total":       total,
+	})
+}
+
+// complaintListFilterFromQuery builds the list filter from query params, supporting
+// plain query params (search, date_from, date_to, person, helicopter_id), with the
+// legacy `filter` key kept as an alias for search.
+// Returns a 422 error object when a date param is not YYYY-MM-DD.
+func complaintListFilterFromQuery(c *fiber.Ctx) (complaint.ListFilter, *jsonapi.ErrorObject) {
+	q := func(keys ...string) string {
+		for _, k := range keys {
+			if v := strings.TrimSpace(c.Query(k)); v != "" {
+				return v
+			}
+		}
+		return ""
+	}
+	f := complaint.ListFilter{
+		Search:   q("search", "filter"),
+		DateFrom: q("date_from"),
+		DateTo:   q("date_to"),
+		Person:   q("person"),
+	}
+	if heliRaw := q("helicopter_id"); heliRaw != "" {
+		helicopterID, err := uuidv7.ParseString(heliRaw)
+		if err != nil {
+			return f, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "helicopter_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/helicopter_id"},
+			}
+		}
+		f.HelicopterID = helicopterID
+	}
+	if flightRaw := q("flight_id"); flightRaw != "" {
+		flightID, err := uuidv7.ParseString(flightRaw)
+		if err != nil {
+			return f, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "flight_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/flight_id"},
+			}
+		}
+		f.FlightID = flightID
+	}
+	for _, d := range []struct {
+		field string
+		value string
+	}{{"date_from", f.DateFrom}, {"date_to", f.DateTo}} {
+		if d.value == "" {
+			continue
+		}
+		if _, err := time.Parse("2006-01-02", d.value); err != nil {
+			return f, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: d.field + " must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: "/" + d.field},
+			}
+		}
+	}
+	return f, nil
+}
+
+func (h *ComplaintHandler) groupedList(ctx context.Context, filter complaint.ListFilter, sort string, limit, offset int, helicopterID []byte) ([]responsedto.ComplaintHelicopterGroupResource, int64, error) {
+	if h == nil || h.svc == nil {
+		return nil, 0, apperrorsx.New(apperrorsx.ErrComplaintListFailed)
+	}
+	if len(helicopterID) > 0 {
+		rows, total, err := h.svc.ListByHelicopter(ctx, helicopterID, limit, offset)
+		if err != nil {
+			return nil, 0, err
+		}
+		return h.groupComplaints(ctx, rows), total, nil
+	}
+	rows, total, err := h.svc.List(ctx, filter, sort, limit, offset)
+	if err != nil {
+		return nil, 0, err
+	}
+	return h.groupComplaints(ctx, rows), total, nil
+}
+
+func (h *ComplaintHandler) groupComplaints(ctx context.Context, rows []complaint.Complaint) []responsedto.ComplaintHelicopterGroupResource {
+	if len(rows) == 0 {
+		return []responsedto.ComplaintHelicopterGroupResource{}
+	}
+	names := h.resolveComplaintNames(ctx, rows)
+	signoffs := h.resolveComplaintSignoffs(ctx, rows, names)
+	grouped := map[string]*responsedto.ComplaintHelicopterGroupResource{}
+	groupRows := map[string][]complaint.Complaint{}
+	order := make([]string, 0)
+	for i := range rows {
+		row := rows[i]
+		key := complaintHelicopterKey(&row)
+		g, ok := grouped[key]
+		if !ok {
+			g = &responsedto.ComplaintHelicopterGroupResource{
+				Type: "complaint_helicopter_group",
+				Attributes: responsedto.ComplaintHelicopterGroupAttributes{
+					Complaints: []responsedto.ComplaintResource{},
+				},
+			}
+			grouped[key] = g
+			order = append(order, key)
+		}
+		res := h.complaintResource(ctx, &row, names, signoffs)
+		g.Attributes.Complaints = append(g.Attributes.Complaints, res)
+		groupRows[key] = append(groupRows[key], row)
+	}
+	inUse := h.helicopterInUse(ctx, order)
+	helIDs := make([][]byte, 0, len(order))
+	for _, key := range order {
+		if len(key) == 16 {
+			helIDs = append(helIDs, []byte(key))
+		}
+	}
+	mcfPending := mcfPendingHelicopterSet(ctx, h.mcfSvc, helIDs)
+	for _, key := range order {
+		grouped[key].Attributes.Helicopter = h.complaintHelicopterResource(ctx, []byte(key), groupRows[key], inUse[key], mcfPending[key])
+	}
+	out := make([]responsedto.ComplaintHelicopterGroupResource, 0, len(order))
+	for _, key := range order {
+		out = append(out, *grouped[key])
+	}
+	// Order the helicopter groups by operational status: MCF, AOG, Booked, Available.
+	sort.SliceStable(out, func(i, j int) bool {
+		return helicopter.StatusRank(complaintGroupStatus(out[i])) < helicopter.StatusRank(complaintGroupStatus(out[j]))
+	})
+	return out
+}
+
+func complaintGroupStatus(g responsedto.ComplaintHelicopterGroupResource) string {
+	if g.Attributes.Helicopter != nil {
+		return g.Attributes.Helicopter.Status
+	}
+	return ""
+}
+
+// resolveComplaintNames resolves reporter display names for the given complaints,
+// keyed by the raw user-id bytes (as string). Returns an empty map on any failure
+// so callers can index without nil checks.
+func (h *ComplaintHandler) resolveComplaintNames(ctx context.Context, rows []complaint.Complaint) map[string]string {
+	if h == nil || h.svc == nil || len(rows) == 0 {
+		return map[string]string{}
+	}
+	if names, err := h.svc.ResolveUserNames(ctx, rows); err == nil && names != nil {
+		return names
+	}
+	return map[string]string{}
+}
+
+func (h *ComplaintHandler) resolveComplaintSignoffs(ctx context.Context, rows []complaint.Complaint, names map[string]string) map[string]*actionsignoff.ActionSignoff {
+	if h == nil {
+		return map[string]*actionsignoff.ActionSignoff{}
+	}
+	return resolveSignoffsByComplaint(ctx, h.signoffSvc, rows, names)
+}
+
+// resolveSignoffsByComplaint batch-loads the corrective-action sign-offs for the given
+// complaints (keyed by complaint id bytes as string) and folds each signer's display
+// name into names so the resource mappers can render it. Returns an empty map on any
+// failure or when svc is nil (sign state simply renders as unsigned).
+func resolveSignoffsByComplaint(ctx context.Context, svc complaintSignoffLookup, rows []complaint.Complaint, names map[string]string) map[string]*actionsignoff.ActionSignoff {
+	if svc == nil || len(rows) == 0 {
+		return map[string]*actionsignoff.ActionSignoff{}
+	}
+	ids := make([][]byte, 0, len(rows))
+	for i := range rows {
+		if len(rows[i].ID) == 16 {
+			ids = append(ids, rows[i].ID)
+		}
+	}
+	m, err := svc.GetByComplaintIDs(ctx, ids)
+	if err != nil || m == nil {
+		return map[string]*actionsignoff.ActionSignoff{}
+	}
+	for _, so := range m {
+		if so == nil || len(so.SignedBy) == 0 {
+			continue
+		}
+		if _, ok := names[string(so.SignedBy)]; !ok {
+			if n := userctx.GetDisplayName(ctx, so.SignedBy); n != "" {
+				names[string(so.SignedBy)] = n
+			}
+		}
+	}
+	return m
+}
+
+// helicopterInUse batch-resolves the in-use (booked) flag for the helicopter group
+// keys (raw id bytes as string). Non-uuid keys (e.g. "unknown") are skipped.
+func (h *ComplaintHandler) helicopterInUse(ctx context.Context, keys []string) map[string]bool {
+	if h == nil || h.helicopterSvc == nil {
+		return map[string]bool{}
+	}
+	ids := make([][]byte, 0, len(keys))
+	for _, k := range keys {
+		if len(k) == 16 {
+			ids = append(ids, []byte(k))
+		}
+	}
+	if len(ids) == 0 {
+		return map[string]bool{}
+	}
+	if inUse, err := h.helicopterSvc.InUseByAircraftIDs(ctx, ids); err == nil && inUse != nil {
+		return inUse
+	}
+	return map[string]bool{}
+}
+
+// complaintHelicopterResource builds the embedded helicopter object for a group:
+// full master data (designation/identifier/type), the derived operational status,
+// and complaint-derived status reasons. Falls back to an id-only object when the
+// helicopter service is unavailable or the lookup fails.
+func (h *ComplaintHandler) complaintHelicopterResource(ctx context.Context, helicopterID []byte, complaints []complaint.Complaint, inUse bool, mcfPending bool) *shareddto.FleetStatusHelicopter {
+	heliID := idString(helicopterID)
+	if heliID == "" {
+		return nil
+	}
+	if h == nil || h.helicopterSvc == nil {
+		return &shareddto.FleetStatusHelicopter{ID: heliID}
+	}
+	heli, err := h.helicopterSvc.GetByID(ctx, helicopterID)
+	if err != nil || heli == nil {
+		return &shareddto.FleetStatusHelicopter{ID: heliID}
+	}
+	now := time.Now().UTC()
+	status := heli.DeriveStatus(helicopter.StatusInput{
+		IsBook:            inUse,
+		IsMCF:             mcfPending,
+		ComplaintGrounded: anyGrounding(complaints, now),
+	})
+	res := fleetStatusHelicopterResource(heli, status)
+	if res != nil {
+		res.StatusReasons = manualAOGReasons(heli)
+	}
+	return res
+}
+
+// complaintHelicopterObject builds the full helicopter object for a single complaint
+// response. It pulls the helicopter's open complaints so the derived status (AOG/MCF/
+// booked/available) reflects the whole aircraft, not just this one complaint.
+func (h *ComplaintHandler) complaintHelicopterObject(ctx context.Context, helicopterID []byte) *shareddto.FleetStatusHelicopter {
+	if h == nil || len(helicopterID) != 16 {
+		return nil
+	}
+	var complaints []complaint.Complaint
+	if h.svc != nil {
+		if rows, _, err := h.svc.ListByHelicopter(ctx, helicopterID, 100, 0); err == nil {
+			complaints = rows
+		}
+	}
+	inUse := h.helicopterInUse(ctx, []string{string(helicopterID)})[string(helicopterID)]
+	mcfPending := mcfPendingHelicopterSet(ctx, h.mcfSvc, [][]byte{helicopterID})[string(helicopterID)]
+	return h.complaintHelicopterResource(ctx, helicopterID, complaints, inUse, mcfPending)
+}
+
+// recordComplaintFiled logs the filing event (and an NSR event when filed as NSR).
+func (h *ComplaintHandler) recordComplaintFiled(c *fiber.Ctx, row *complaint.Complaint) {
+	if h.historySvc == nil || row == nil {
+		return
+	}
+	msg := "Complaint filed: " + row.Description
+	if lbl := complaintSeverityLabel(row.MELSeverity); lbl != "" {
+		msg += " (MEL " + lbl + ")"
+	}
+	actor := actorUserID(c)
+	_ = h.historySvc.Record(c.UserContext(), row.HelicopterID, fleethistory.EntityComplaint, row.ID, fleethistory.ActionComplaintFiled, msg, actor)
+	if row.ActionTaken != nil {
+		_ = h.historySvc.Record(c.UserContext(), row.HelicopterID, fleethistory.EntityComplaint, row.ID, fleethistory.ActionActionTaken, "Action taken — "+*row.ActionTaken, actor)
+	}
+}
+
+// recordComplaintUpdate logs MEL classification, NSR done/cancel, and action-taken
+// events based on which attributes were present in the update request.
+func (h *ComplaintHandler) recordComplaintUpdate(c *fiber.Ctx, attrs requestdto.ComplaintUpdateAttributes, row *complaint.Complaint) {
+	if h.historySvc == nil || row == nil {
+		return
+	}
+	actor := actorUserID(c)
+	if attrs.MELSeverity != nil {
+		msg := "MEL classified"
+		if lbl := complaintSeverityLabel(*attrs.MELSeverity); lbl != "" {
+			msg = "MEL classified as " + lbl
+		}
+		_ = h.historySvc.Record(c.UserContext(), row.HelicopterID, fleethistory.EntityComplaint, row.ID, fleethistory.ActionMELClassified, msg, actor)
+	}
+}
+
+func nsrLogMessage(row *complaint.Complaint) string {
+	if row != nil && row.NSRReason != nil && strings.TrimSpace(*row.NSRReason) != "" {
+		return "NSR done — " + strings.TrimSpace(*row.NSRReason)
+	}
+	return "NSR done"
+}
+
+// anyGrounding reports whether any complaint currently grounds the aircraft (AOG):
+// a non-MEL defect (immediately) or a MEL past its grace deadline. EASA-fixed
+// complaints (signed set) are skipped.
+func anyGrounding(rows []complaint.Complaint, now time.Time) bool {
+	for i := range rows {
+		if rows[i].IsGrounding(now) {
+			return true
+		}
+	}
+	return false
+}
+
+// complaintGroundingLister fetches open grounding-candidate complaints (non-MEL, or MEL
+// not yet released/fixed) for a set of helicopters so any view can derive read-time
+// AOG without coupling to the full complaint service.
+type complaintGroundingLister interface {
+	ActiveGroundingByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) ([]complaint.Complaint, error)
+}
+
+// groundingHelicopterSet returns the set of helicopter ids (raw-bytes string key) that
+// have at least one complaint currently grounding the aircraft: a non-MEL defect
+// (immediately) or a MEL past its grace deadline.
+func groundingHelicopterSet(ctx context.Context, svc complaintGroundingLister, ids [][]byte, now time.Time) map[string]bool {
+	out := map[string]bool{}
+	if svc == nil || len(ids) == 0 {
+		return out
+	}
+	rows, err := svc.ActiveGroundingByHelicopterIDs(ctx, ids)
+	if err != nil {
+		return out
+	}
+	for i := range rows {
+		if rows[i].IsGrounding(now) {
+			out[string(rows[i].HelicopterID)] = true
+		}
+	}
+	return out
+}
+
+// groundedHelicopterIDs returns the ids of every helicopter currently grounded by an
+// open complaint (per IsGrounding). It lets status filters be AOG-aware, since
+// complaint grounding is computed at read time and not persisted in air_on_ground.
+func groundedHelicopterIDs(ctx context.Context, svc complaintGroundingLister, now time.Time) [][]byte {
+	if svc == nil {
+		return nil
+	}
+	rows, err := svc.ActiveGroundingByHelicopterIDs(ctx, nil)
+	if err != nil {
+		return nil
+	}
+	seen := make(map[string]struct{}, len(rows))
+	out := make([][]byte, 0, len(rows))
+	for i := range rows {
+		if !rows[i].IsGrounding(now) {
+			continue
+		}
+		key := string(rows[i].HelicopterID)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		out = append(out, append([]byte(nil), rows[i].HelicopterID...))
+	}
+	return out
+}
+
+// complaintGroundingReason builds a user-facing grounding reason, distinguishing an
+// expired MEL grace period (with its A/B/C/D class) from an immediate non-MEL defect.
+func complaintGroundingReason(c complaint.Complaint) string {
+	if c.MELSeverity > complaint.MELSeverityNonMEL {
+		return "Grounded due to an open complaint — MEL " + shareddto.MELLabel(c.MELSeverity) + " grace period expired"
+	}
+	return "Grounded due to an open non-MEL complaint"
+}
+
+// groundingReasonHelicopterSet maps each grounded helicopter id (raw-bytes string key)
+// to a human-readable grounding reason. An absent key means the helicopter is not grounded.
+func groundingReasonHelicopterSet(ctx context.Context, svc complaintGroundingLister, ids [][]byte, now time.Time) map[string]string {
+	out := map[string]string{}
+	if svc == nil || len(ids) == 0 {
+		return out
+	}
+	rows, err := svc.ActiveGroundingByHelicopterIDs(ctx, ids)
+	if err != nil {
+		return out
+	}
+	for i := range rows {
+		if !rows[i].IsGrounding(now) {
+			continue
+		}
+		key := string(rows[i].HelicopterID)
+		if _, exists := out[key]; !exists {
+			out[key] = complaintGroundingReason(rows[i])
+		}
+	}
+	return out
+}
+
+// manualAOGReasons returns status reasons for the embedded helicopter. Automatic
+// grounding (expired MEL) is conveyed by the derived status alone; only a manual
+// AOG carries an explanatory reason.
+func manualAOGReasons(heli *helicopter.Helicopter) []shareddto.FleetStatusHelicopterReason {
+	if heli == nil || !heli.AirOnGround || heli.AOGSource != helicopter.AOGSourceManual {
+		return nil
+	}
+	detail := strings.TrimSpace(heli.AOGReason)
+	if detail == "" {
+		detail = "Manual AOG"
+	}
+	return []shareddto.FleetStatusHelicopterReason{{Code: shareddto.ReasonCodeManualAOG, Detail: detail}}
+}
+
+// mapComplaintServiceErrorWithFallback translates a raw service/repo error into a
+// dedicated complaint AppError. Specific mapped codes (not found, relation delete,
+// invalid helicopter reference, invalid payload) pass through with their proper HTTP
+// status; anything else collapses to the operation-specific fallback (create/update/...).
+func mapComplaintServiceErrorWithFallback(err error, fallback apperrorsx.Def) *apperrorsx.AppError {
+	mapped := apperrorsx.Translate(apperrorsx.ModuleComplaint, err)
+	if mapped == nil {
+		return apperrorsx.New(fallback).WithCause(err)
+	}
+	switch mapped.Code {
+	case apperrorsx.CodeComplaintNotFound,
+		apperrorsx.CodeComplaintRelationDelete,
+		apperrorsx.CodeComplaintInvalidHelicopterID,
+		apperrorsx.CodeComplaintInvalidPayload:
+		return mapped
+	default:
+		return apperrorsx.New(fallback).WithCause(err)
+	}
+}
+
+func writeComplaintErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	return jsonapi.WriteErrors(c, status, errs)
+}
+
+func intOrDefaultFromString(raw string, def int) int {
+	if v, err := strconv.Atoi(strings.TrimSpace(raw)); err == nil {
+		return v
+	}
+	return def
+}
+
+func emptyToNilString(v *string) *string {
+	if v == nil {
+		return nil
+	}
+	if strings.TrimSpace(*v) == "" {
+		return nil
+	}
+	out := strings.TrimSpace(*v)
+	return &out
+}
diff --git a/internal/transport/http/handlers/complaint_handler_test.go b/internal/transport/http/handlers/complaint_handler_test.go
new file mode 100644
index 0000000..51c6107
--- /dev/null
+++ b/internal/transport/http/handlers/complaint_handler_test.go
@@ -0,0 +1,615 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	actionsignoff "wucher/internal/domain/action_signoff"
+	"wucher/internal/domain/complaint"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type complaintSignoffMock struct {
+	getByComplaintIDsFn func(context.Context, [][]byte) (map[string]*actionsignoff.ActionSignoff, error)
+	unsignByComplaintFn func(context.Context, []byte) (*actionsignoff.ActionSignoff, error)
+}
+
+func (m *complaintSignoffMock) GetByComplaintIDs(ctx context.Context, ids [][]byte) (map[string]*actionsignoff.ActionSignoff, error) {
+	if m.getByComplaintIDsFn != nil {
+		return m.getByComplaintIDsFn(ctx, ids)
+	}
+	return map[string]*actionsignoff.ActionSignoff{}, nil
+}
+
+func (m *complaintSignoffMock) UnsignByComplaint(ctx context.Context, complaintID []byte) (*actionsignoff.ActionSignoff, error) {
+	if m.unsignByComplaintFn != nil {
+		return m.unsignByComplaintFn(ctx, complaintID)
+	}
+	return nil, nil
+}
+
+type complaintServiceMock struct {
+	createFn           func(context.Context, *complaint.Complaint) error
+	updateFn           func(context.Context, *complaint.Complaint) error
+	getByIDFn          func(context.Context, []byte) (*complaint.Complaint, error)
+	hasOpenFn          func(context.Context, []byte) (bool, error)
+	listFn             func(context.Context, complaint.ListFilter, string, int, int) ([]complaint.Complaint, int64, error)
+	listByHelicopterFn func(context.Context, []byte, int, int) ([]complaint.Complaint, int64, error)
+	resolveNamesFn     func(context.Context, []complaint.Complaint) (map[string]string, error)
+}
+
+func (m *complaintServiceMock) Create(ctx context.Context, row *complaint.Complaint) error {
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return nil
+}
+
+func (m *complaintServiceMock) Update(ctx context.Context, row *complaint.Complaint) error {
+	if m.updateFn != nil {
+		return m.updateFn(ctx, row)
+	}
+	return nil
+}
+
+func (m *complaintServiceMock) Delete(context.Context, []byte, []byte) error { return nil }
+
+func (m *complaintServiceMock) GetByID(ctx context.Context, id []byte) (*complaint.Complaint, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *complaintServiceMock) ListByHelicopter(ctx context.Context, helicopterID []byte, limit, offset int) ([]complaint.Complaint, int64, error) {
+	if m.listByHelicopterFn != nil {
+		return m.listByHelicopterFn(ctx, helicopterID, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func (m *complaintServiceMock) List(ctx context.Context, filter complaint.ListFilter, sort string, limit, offset int) ([]complaint.Complaint, int64, error) {
+	if m.listFn != nil {
+		return m.listFn(ctx, filter, sort, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func (m *complaintServiceMock) HelicopterHasOpenComplaint(ctx context.Context, helicopterID []byte) (bool, error) {
+	if m.hasOpenFn != nil {
+		return m.hasOpenFn(ctx, helicopterID)
+	}
+	return false, nil
+}
+
+func (m *complaintServiceMock) ActiveGroundingByHelicopterIDs(context.Context, [][]byte) ([]complaint.Complaint, error) {
+	return nil, nil
+}
+func (m *complaintServiceMock) OpenByHelicopterIDs(context.Context, [][]byte) ([]complaint.Complaint, error) {
+	return nil, nil
+}
+
+func (m *complaintServiceMock) HelicopterHasUnactionedComplaint(context.Context, []byte) (bool, error) {
+	return false, nil
+}
+
+func (m *complaintServiceMock) MarkFixedByHelicopter(context.Context, []byte, []byte, []byte) error {
+	return nil
+}
+
+func (m *complaintServiceMock) MarkFixedByComplaint(context.Context, []byte, []byte, []byte) error {
+	return nil
+}
+
+func (m *complaintServiceMock) MarkFixedByFlight(context.Context, []byte, []byte, []byte) error {
+	return nil
+}
+
+func (m *complaintServiceMock) ResolveUserNames(ctx context.Context, rows []complaint.Complaint) (map[string]string, error) {
+	if m.resolveNamesFn != nil {
+		return m.resolveNamesFn(ctx, rows)
+	}
+	return map[string]string{}, nil
+}
+
+func newComplaintApp(h *ComplaintHandler, userID []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", userID)
+		return c.Next()
+	})
+	app.Post("/api/v1/complaints/create", h.Create)
+	app.Get("/api/v1/complaints/get/:id", h.GetByID)
+	app.Patch("/api/v1/complaints/update/:id", h.Update)
+	app.Post("/api/v1/complaints/action-taken/create/:id", h.ActionTaken)
+	app.Patch("/api/v1/complaints/action-taken/update/:id", h.UpdateActionTaken)
+	app.Post("/api/v1/complaints/nsr/sign/:id", h.NSRSign)
+	app.Post("/api/v1/complaints/nsr/unsign/:id", h.NSRUnsign)
+	app.Get("/api/v1/complaints/hold-items/get-all", h.ListHoldItems)
+	app.Get("/api/v1/complaints/hold-items/get-all/dt", h.ListHoldItemsDatatable)
+	return app
+}
+
+func TestComplaintHandler_ListHoldItems_FiltersOpenMEL(t *testing.T) {
+	var got complaint.ListFilter
+	svc := &complaintServiceMock{
+		listFn: func(_ context.Context, filter complaint.ListFilter, _ string, _, _ int) ([]complaint.Complaint, int64, error) {
+			got = filter
+			return nil, 0, nil
+		},
+	}
+	app := newComplaintApp(NewComplaintHandler(svc), uuidv7.MustBytes())
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/complaints/hold-items/get-all?date_from=2026-06-01&date_to=2026-06-30&person=Ganahl&search=vibration", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bodyBytes, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	if !got.HoldItemsOnly {
+		t.Fatalf("expected HoldItemsOnly=true in filter, got %#v", got)
+	}
+	if got.DateFrom != "2026-06-01" || got.DateTo != "2026-06-30" || got.Person != "Ganahl" || got.Search != "vibration" {
+		t.Fatalf("expected Von/bis/person/search filters passed, got %#v", got)
+	}
+}
+
+// Action-taken now only records the corrective action TEXT — signing moved to
+// POST /action-signoffs/sign (with complaint_id). No sign field, no 422.
+func TestComplaintHandler_ActionTaken_RecordsTextWithoutSign(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	helicopterID := uuidv7.MustBytes()
+
+	var recorded *complaint.Complaint
+	svc := &complaintServiceMock{
+		getByIDFn: func(context.Context, []byte) (*complaint.Complaint, error) {
+			if recorded != nil {
+				return recorded, nil
+			}
+			return &complaint.Complaint{ID: complaintID, HelicopterID: helicopterID, Description: "vibration", MELSeverity: 2, MELClassifiedAt: func() *time.Time { t := time.Now().UTC(); return &t }()}, nil
+		},
+		updateFn: func(_ context.Context, row *complaint.Complaint) error {
+			if row.ActionTaken == nil || *row.ActionTaken != "tightened mount" {
+				t.Fatalf("unexpected action_taken: %#v", row.ActionTaken)
+			}
+			recorded = row
+			return nil
+		},
+	}
+	app := newComplaintApp(NewComplaintHandler(svc), uuidv7.MustBytes())
+
+	// No `sign` field anymore.
+	body := `{"data":{"type":"complaint_action_taken","attributes":{"action_taken":"tightened mount"}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/complaints/action-taken/create/"+complaintIDStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bodyBytes, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	if recorded == nil {
+		t.Fatal("expected update to be called recording the action text")
+	}
+}
+
+// A pending (unclassified) complaint — mel_classified_at NULL — cannot record action
+// taken until MEL is classified; the gate returns 422 and never touches the row.
+func TestComplaintHandler_ActionTaken_BlockedWhenMELPending(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	helicopterID := uuidv7.MustBytes()
+
+	svc := &complaintServiceMock{
+		getByIDFn: func(context.Context, []byte) (*complaint.Complaint, error) {
+			// Pending: no MELClassifiedAt.
+			return &complaint.Complaint{ID: complaintID, HelicopterID: helicopterID, Description: "vibration"}, nil
+		},
+		updateFn: func(context.Context, *complaint.Complaint) error {
+			t.Fatal("update must not be called while MEL is pending")
+			return nil
+		},
+	}
+	app := newComplaintApp(NewComplaintHandler(svc), uuidv7.MustBytes())
+
+	body := `{"data":{"type":"complaint_action_taken","attributes":{"action_taken":"tightened mount"}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/complaints/action-taken/create/"+complaintIDStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		bodyBytes, _ := io.ReadAll(resp.Body)
+		t.Fatalf("expected 422 (classify MEL first), got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+}
+
+// NSR is its own flow: nsr/sign sets the deferral on a classified complaint; a pending
+// (unclassified) complaint cannot be deferred and returns 422.
+func TestComplaintHandler_NSRSign_SetsDeferralWhenClassified(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	helicopterID := uuidv7.MustBytes()
+	classified := time.Now().UTC()
+
+	var saved *complaint.Complaint
+	svc := &complaintServiceMock{
+		getByIDFn: func(context.Context, []byte) (*complaint.Complaint, error) {
+			if saved != nil {
+				return saved, nil
+			}
+			return &complaint.Complaint{ID: complaintID, HelicopterID: helicopterID, Description: "vibration", MELSeverity: 2, MELClassifiedAt: &classified}, nil
+		},
+		updateFn: func(_ context.Context, row *complaint.Complaint) error {
+			if !row.IsNSR || row.NSRDecidedAt == nil {
+				t.Fatalf("expected NSR set with decided_at, got %#v", row)
+			}
+			saved = row
+			return nil
+		},
+	}
+	app := newComplaintApp(NewComplaintHandler(svc), uuidv7.MustBytes())
+
+	body := `{"data":{"type":"complaint_nsr_sign","attributes":{"nsr_reason":"deferred under MEL B"}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/complaints/nsr/sign/"+complaintIDStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		b, _ := io.ReadAll(resp.Body)
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(b))
+	}
+	if saved == nil || !saved.IsNSR {
+		t.Fatal("expected NSR to be recorded")
+	}
+}
+
+func TestComplaintHandler_NSRSign_BlockedWhenMELPending(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	helicopterID := uuidv7.MustBytes()
+
+	svc := &complaintServiceMock{
+		getByIDFn: func(context.Context, []byte) (*complaint.Complaint, error) {
+			// Pending: no MELClassifiedAt.
+			return &complaint.Complaint{ID: complaintID, HelicopterID: helicopterID, Description: "vibration"}, nil
+		},
+		updateFn: func(context.Context, *complaint.Complaint) error {
+			t.Fatal("update must not be called: cannot defer a pending complaint")
+			return nil
+		},
+	}
+	app := newComplaintApp(NewComplaintHandler(svc), uuidv7.MustBytes())
+
+	body := `{"data":{"type":"complaint_nsr_sign","attributes":{}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/complaints/nsr/sign/"+complaintIDStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		b, _ := io.ReadAll(resp.Body)
+		t.Fatalf("expected 422 (classify MEL first), got %d body=%s", resp.StatusCode, string(b))
+	}
+}
+
+func TestComplaintHandler_NSRUnsign_ClearsDeferral(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	helicopterID := uuidv7.MustBytes()
+	classified := time.Now().UTC()
+
+	var saved *complaint.Complaint
+	svc := &complaintServiceMock{
+		getByIDFn: func(context.Context, []byte) (*complaint.Complaint, error) {
+			if saved != nil {
+				return saved, nil
+			}
+			return &complaint.Complaint{ID: complaintID, HelicopterID: helicopterID, Description: "vibration", MELSeverity: 2, MELClassifiedAt: &classified, IsNSR: true, NSRDecidedAt: &classified}, nil
+		},
+		updateFn: func(_ context.Context, row *complaint.Complaint) error {
+			if row.IsNSR || row.NSRDecidedAt != nil {
+				t.Fatalf("expected NSR cleared, got %#v", row)
+			}
+			saved = row
+			return nil
+		},
+	}
+	app := newComplaintApp(NewComplaintHandler(svc), uuidv7.MustBytes())
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/complaints/nsr/unsign/"+complaintIDStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		b, _ := io.ReadAll(resp.Body)
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(b))
+	}
+	if saved == nil || saved.IsNSR {
+		t.Fatal("expected NSR to be cleared")
+	}
+}
+
+func TestComplaintHandler_UpdateActionTaken_RecordsTextWithoutSign(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	helicopterID := uuidv7.MustBytes()
+
+	var recorded *complaint.Complaint
+	svc := &complaintServiceMock{
+		getByIDFn: func(context.Context, []byte) (*complaint.Complaint, error) {
+			if recorded != nil {
+				return recorded, nil
+			}
+			return &complaint.Complaint{ID: complaintID, HelicopterID: helicopterID, Description: "vibration", MELSeverity: 2, MELClassifiedAt: func() *time.Time { t := time.Now().UTC(); return &t }()}, nil
+		},
+		updateFn: func(_ context.Context, row *complaint.Complaint) error {
+			if row.ActionTaken == nil || *row.ActionTaken != "re-torqued mount" {
+				t.Fatalf("unexpected action_taken: %#v", row.ActionTaken)
+			}
+			recorded = row
+			return nil
+		},
+	}
+	app := newComplaintApp(NewComplaintHandler(svc), uuidv7.MustBytes())
+
+	body := `{"data":{"type":"complaint_action_taken","attributes":{"action_taken":"re-torqued mount"}}}`
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/complaints/action-taken/update/"+complaintIDStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bodyBytes, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	if recorded == nil {
+		t.Fatal("expected update to be called recording the action text")
+	}
+}
+
+// The complaint response reads its action-sign state from action_signoff (by
+// complaint_id), not from the (now-unset) complaint.ActionSignedAt/By columns.
+func TestComplaintHandler_GetByID_ReadsSignFromSignoff(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	helicopterID := uuidv7.MustBytes()
+	signer := uuidv7.MustBytes()
+	signedAt := time.Now().UTC()
+
+	action := "replaced part"
+	svc := &complaintServiceMock{
+		getByIDFn: func(context.Context, []byte) (*complaint.Complaint, error) {
+			return &complaint.Complaint{ID: complaintID, HelicopterID: helicopterID, Description: "vibration", MELSeverity: 2, ActionTaken: &action}, nil
+		},
+	}
+	var lookedUp [][]byte
+	signoffSvc := &complaintSignoffMock{
+		getByComplaintIDsFn: func(_ context.Context, ids [][]byte) (map[string]*actionsignoff.ActionSignoff, error) {
+			lookedUp = ids
+			return map[string]*actionsignoff.ActionSignoff{
+				string(complaintID): {ComplaintID: complaintID, HelicopterID: helicopterID, SignedAt: &signedAt, SignedBy: signer},
+			}, nil
+		},
+	}
+	app := newComplaintApp(NewComplaintHandler(svc).WithActionSignoffService(signoffSvc), uuidv7.MustBytes())
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/complaints/get/"+complaintIDStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bodyBytes, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	if len(lookedUp) != 1 || string(lookedUp[0]) != string(complaintID) {
+		t.Fatalf("expected signoff lookup by complaint id, got %#v", lookedUp)
+	}
+	attrs := struct {
+		ActionSigned   bool    `json:"action_signed"`
+		ActionSignedAt *string `json:"action_signed_at"`
+	}{}
+	var payload struct {
+		Data struct {
+			Data struct {
+				Attributes json.RawMessage `json:"attributes"`
+			} `json:"data"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(bodyBytes, &payload); err != nil {
+		t.Fatalf("bad json: %v body=%s", err, string(bodyBytes))
+	}
+	if err := json.Unmarshal(payload.Data.Data.Attributes, &attrs); err != nil {
+		t.Fatalf("bad attributes json: %v body=%s", err, string(bodyBytes))
+	}
+	if !attrs.ActionSigned {
+		t.Fatalf("expected action_signed=true from signoff, got body=%s", string(bodyBytes))
+	}
+	if attrs.ActionSignedAt == nil {
+		t.Fatalf("expected action_signed_at from signoff, got body=%s", string(bodyBytes))
+	}
+}
+
+type complaintAOGRecalcMock struct {
+	fn func(context.Context, []byte) error
+}
+
+func (m *complaintAOGRecalcMock) RecalculateAOGByHelicopter(ctx context.Context, helicopterID []byte) error {
+	if m.fn != nil {
+		return m.fn(ctx, helicopterID)
+	}
+	return nil
+}
+
+// Updating a complaint that was already closed reopens its lifecycle: the complaint is
+// unfixed, its corrective-action sign-off is unsigned, and AOG is recomputed.
+func TestComplaintHandler_Update_ReopensAndUnsignsWhenClosed(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	helicopterID := uuidv7.MustBytes()
+	easaID := uuidv7.MustBytes()
+	fixedAt := time.Now().UTC()
+
+	var updatedRow *complaint.Complaint
+	svc := &complaintServiceMock{
+		getByIDFn: func(context.Context, []byte) (*complaint.Complaint, error) {
+			// A fresh CLOSED complaint on each call (fixed by a past EASA release).
+			return &complaint.Complaint{ID: complaintID, HelicopterID: helicopterID, Description: "vibration", MELSeverity: 2, FixedAt: &fixedAt, FixedByEASAID: easaID}, nil
+		},
+		updateFn: func(_ context.Context, row *complaint.Complaint) error {
+			updatedRow = row
+			return nil
+		},
+	}
+	var unsignedComplaint []byte
+	signoffSvc := &complaintSignoffMock{
+		unsignByComplaintFn: func(_ context.Context, cid []byte) (*actionsignoff.ActionSignoff, error) {
+			unsignedComplaint = cid
+			return nil, nil
+		},
+	}
+	var recalced []byte
+	aog := &complaintAOGRecalcMock{fn: func(_ context.Context, id []byte) error { recalced = id; return nil }}
+
+	h := NewComplaintHandler(svc).WithActionSignoffService(signoffSvc).WithAOGRecalculator(aog)
+	app := newComplaintApp(h, uuidv7.MustBytes())
+
+	body := `{"data":{"type":"complaint_update","id":"` + complaintIDStr + `","attributes":{"description":"vibration + extra work"}}}`
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/complaints/update/"+complaintIDStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bodyBytes, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	if updatedRow == nil {
+		t.Fatal("expected update to be called")
+	}
+	if updatedRow.FixedAt != nil || len(updatedRow.FixedByEASAID) != 0 {
+		t.Fatalf("expected complaint reopened (fixed_at/by cleared), got at=%v by=%x", updatedRow.FixedAt, updatedRow.FixedByEASAID)
+	}
+	if string(unsignedComplaint) != string(complaintID) {
+		t.Fatalf("expected sign-off unsigned for complaint, got %x", unsignedComplaint)
+	}
+	if string(recalced) != string(helicopterID) {
+		t.Fatalf("expected AOG recomputed for helicopter, got %x", recalced)
+	}
+}
+
+func TestComplaintHandler_UpdateActionTaken_ClearWhenNotSigned(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	action := "old action"
+	now := time.Now().UTC()
+
+	var cleared bool
+	svc := &complaintServiceMock{
+		getByIDFn: func(context.Context, []byte) (*complaint.Complaint, error) {
+			return &complaint.Complaint{ID: complaintID, HelicopterID: uuidv7.MustBytes(), MELSeverity: 2, MELClassifiedAt: &now, ActionTaken: &action}, nil
+		},
+		updateFn: func(_ context.Context, row *complaint.Complaint) error {
+			if row.ActionTaken != nil {
+				t.Fatalf("expected action_taken cleared to nil, got %v", *row.ActionTaken)
+			}
+			cleared = true
+			return nil
+		},
+	}
+	// unsigned sign-off → clearing allowed
+	app := newComplaintApp(NewComplaintHandler(svc).WithActionSignoffService(&complaintSignoffMock{}), uuidv7.MustBytes())
+
+	body := `{"data":{"type":"complaint_action_taken","attributes":{"action_taken":""}}}`
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/complaints/action-taken/update/"+complaintIDStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bodyBytes, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	if !cleared {
+		t.Fatal("expected action_taken to be cleared")
+	}
+}
+
+func TestComplaintHandler_UpdateActionTaken_ClearBlockedWhenSigned(t *testing.T) {
+	complaintID := uuidv7.MustBytes()
+	complaintIDStr, _ := uuidv7.BytesToString(complaintID)
+	action := "old action"
+	now := time.Now().UTC()
+
+	svc := &complaintServiceMock{
+		getByIDFn: func(context.Context, []byte) (*complaint.Complaint, error) {
+			return &complaint.Complaint{ID: complaintID, HelicopterID: uuidv7.MustBytes(), MELSeverity: 2, MELClassifiedAt: &now, ActionTaken: &action}, nil
+		},
+		updateFn: func(context.Context, *complaint.Complaint) error {
+			t.Fatal("must not update when clearing a signed action")
+			return nil
+		},
+	}
+	signoffSvc := &complaintSignoffMock{
+		getByComplaintIDsFn: func(_ context.Context, _ [][]byte) (map[string]*actionsignoff.ActionSignoff, error) {
+			return map[string]*actionsignoff.ActionSignoff{
+				string(complaintID): {ComplaintID: complaintID, SignedAt: &now},
+			}, nil
+		},
+	}
+	app := newComplaintApp(NewComplaintHandler(svc).WithActionSignoffService(signoffSvc), uuidv7.MustBytes())
+
+	body := `{"data":{"type":"complaint_action_taken","attributes":{"action_taken":""}}}`
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/complaints/action-taken/update/"+complaintIDStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bodyBytes, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusConflict {
+		t.Fatalf("expected 409, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	if !strings.Contains(string(bodyBytes), "COMPLAINT_ACTION_SIGNED_LOCKED") {
+		t.Fatalf("expected COMPLAINT_ACTION_SIGNED_LOCKED, got %s", string(bodyBytes))
+	}
+}
+
+func TestComplaintHandler_ActionTaken_CreateStillRequiresText(t *testing.T) {
+	complaintIDStr, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	app := newComplaintApp(NewComplaintHandler(&complaintServiceMock{}), uuidv7.MustBytes())
+
+	body := `{"data":{"type":"complaint_action_taken","attributes":{"action_taken":""}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/complaints/action-taken/create/"+complaintIDStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		bodyBytes, _ := io.ReadAll(resp.Body)
+		t.Fatalf("create with empty action_taken must be 422, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+}
diff --git a/internal/transport/http/handlers/contact_handler.go b/internal/transport/http/handlers/contact_handler.go
new file mode 100644
index 0000000..f63cd2d
--- /dev/null
+++ b/internal/transport/http/handlers/contact_handler.go
@@ -0,0 +1,1962 @@
+package handlers
+
+import (
+	"context"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/domain/contact"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/attachmentresolver"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+const (
+	contactProfileAttachmentRefType  = "user_profile"
+	contactProfileAttachmentCategory = "profile_picture"
+	contactListMaxLimit              = 1000
+)
+
+type ContactHandler struct {
+	svc         contact.Service
+	fileManager filemanager.Service
+	storage     fileManagerDownloadURLStorage
+	inviter     contactInviter
+	validate    *validators.Validator
+}
+
+type contactInviter interface {
+	SendInviteSetPasswordForUser(ctx context.Context, userID []byte) error
+}
+
+func NewContactHandler(svc contact.Service, inviter contactInviter) *ContactHandler {
+	return &ContactHandler{svc: svc, inviter: inviter, validate: validators.New()}
+}
+
+func (h *ContactHandler) WithFileManagerService(fileManager filemanager.Service) *ContactHandler {
+	h.fileManager = fileManager
+	return h
+}
+
+func (h *ContactHandler) WithFileStorage(storage fileManagerDownloadURLStorage) *ContactHandler {
+	h.storage = storage
+	return h
+}
+
+type contactProfilePayload struct {
+	roleCode string
+	field    string
+	present  bool
+}
+
+// CreateContact 	godoc
+// @Summary Create contact
+// @Description Create new contact user and role-specific profile.
+// @Description `data.type` must be `contact_create`.
+// @Description `role_ids` determines roles (use `role_id` only for backward compatibility). Every selected role must include its matching role-specific profile object in `attributes`.
+// @Tags Contacts
+// @Accept json
+// @Produce json
+// @Param request body dto.ContactCreateRequest true "JSON:API Contact create request"
+// @Success 201 {object} dto.ContactListResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/contacts/create [post]
+func (h *ContactHandler) Create(c *fiber.Ctx) error {
+	var req dto.ContactCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if errs := validatePilotDULBaseCreateInput(req.Data.Attributes); len(errs) > 0 {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	primaryRoleID, roleIDs, errObjs := parseContactCreateRoleIDs(req.Data.Attributes)
+	if len(errObjs) > 0 {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errObjs)
+	}
+	roleCodes := make([]string, 0, len(roleIDs))
+	for i := range roleIDs {
+		roleCode, err := h.svc.ResolveRoleCodeByID(c.UserContext(), roleIDs[i])
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return writeContactErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{
+					contactValidationError("/data/attributes/role_ids", "one or more role_ids do not exist"),
+				})
+			}
+			return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Create failed", Detail: "an internal error occurred"}})
+		}
+		roleCodes = append(roleCodes, roleCode)
+	}
+	if len(roleCodes) == 0 {
+		roleCodes = inferContactCreateRoleCodes(req.Data.Attributes)
+	}
+	if errs := validateContactCreatePayload(req.Data.Type, roleCodes, req.Data.Attributes); len(errs) > 0 {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	in := contact.CreateInput{
+		RoleID:  primaryRoleID,
+		RoleIDs: roleIDs,
+		User: contact.UserPatch{
+			Email:       strPtr(strings.TrimSpace(req.Data.Attributes.Email)),
+			SSOEmail:    emptyToNil(strings.TrimSpace(req.Data.Attributes.SSOEmail)),
+			IsAdmin:     req.Data.Attributes.IsAdmin,
+			Username:    strPtr(strings.TrimSpace(req.Data.Attributes.Username)),
+			FirstName:   strPtr(strings.TrimSpace(req.Data.Attributes.FirstName)),
+			LastName:    strPtr(strings.TrimSpace(req.Data.Attributes.LastName)),
+			MobilePhone: strPtr(strings.TrimSpace(req.Data.Attributes.MobilePhone)),
+			Timezone:    strPtr(strings.TrimSpace(req.Data.Attributes.Timezone)),
+			SortKey:     cloneIntPointer(req.Data.Attributes.SortKey),
+			IsActive:    req.Data.Attributes.IsActive,
+		},
+	}
+	for i := range roleCodes {
+		in.Profiles = append(in.Profiles, contact.CreateRoleProfile{
+			RoleCode: roleCodes[i],
+			Patch:    profilePatchFromCreate(roleCodes[i], req.Data.Attributes),
+		})
+	}
+	if len(in.Profiles) > 0 {
+		in.Profile = in.Profiles[0].Patch
+	}
+
+	userID, err := h.svc.CreateContact(c.UserContext(), in)
+	if err != nil {
+		if errors.Is(err, contact.ErrUsernameAlreadyExists) {
+			return writeContactErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "Conflict",
+				Detail: "username already exists",
+			}})
+		}
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	if rawFileUUID := strings.TrimSpace(req.Data.Attributes.FileUUID); rawFileUUID != "" {
+		attachmentID, handled := h.resolveContactProfileAttachmentID(c, userID, &rawFileUUID)
+		if handled {
+			return nil
+		}
+		if err := h.svc.UpdateContact(c.UserContext(), contact.UpdateInput{
+			UserID: userID,
+			User: contact.UserPatch{
+				ProfileAttachmentID: &attachmentID,
+			},
+		}); err != nil {
+			return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Create failed",
+				Detail: "an internal error occurred",
+			}})
+		}
+	}
+
+	inviteSent := false
+	inviteError := ""
+	if h.inviter != nil {
+		if err := h.inviter.SendInviteSetPasswordForUser(c.UserContext(), userID); err != nil {
+			inviteError = "an internal error occurred"
+		} else {
+			inviteSent = true
+		}
+	}
+
+	item, err := h.svc.GetContactByID(c.UserContext(), userID)
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if item == nil {
+		return response.Write(c, fiber.StatusCreated, jsonapi.Resource{
+			Type: "contact",
+			ID:   contactUUIDString(userID),
+			Attributes: map[string]any{
+				"created":      true,
+				"invite_sent":  inviteSent,
+				"invite_error": inviteError,
+			},
+		})
+	}
+
+	isAdmin, err := h.svc.IsActorAdmin(c.UserContext())
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Create failed", Detail: "an internal error occurred"}})
+	}
+	attrs := contactAttributes(item, isAdmin)
+	h.applyContactFoto(c.UserContext(), item, attrs)
+	attrs["invite_sent"] = inviteSent
+	attrs["invite_error"] = inviteError
+	return response.Write(c, fiber.StatusCreated, jsonapi.Resource{
+		Type:       "contact",
+		ID:         contactUUIDString(item.UserID),
+		Attributes: attrs,
+	})
+}
+
+// ListContacts godoc
+// @Summary List contacts
+// @Description Filter contacts by role and pilot_category. Sort values: name, -name, first_name, -first_name, last_name, -last_name, email, -email, sortkey, -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.
+// @Tags Contacts
+// @Produce json
+// @Param role query string false "Role: pilot|doctor|air_rescuer|technician|flight_assistant|staff"
+// @Param pilot_category query string false "Pilot category: regular|freelance|dry_lease"
+// @Param chief_doctor query bool false "Filter doctor chief flag"
+// @Param chief_technician query bool false "Filter technician chief flag"
+// @Param responsible_complaint query bool false "Filter responsible complaint flag"
+// @Param chief_pilot query bool false "Filter pilot chief flag"
+// @Param ifr_qualified query bool false "Filter IFR qualified flag"
+// @Param search query string false "Search by username/email/name"
+// @Param sort query string false "Sort order"
+// @Param limit query int false "Limit (default 20)"
+// @Param offset query int false "Offset (default 0)"
+// @Success 200 {object} dto.ContactListResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/contacts/get-all [get]
+func (h *ContactHandler) List(c *fiber.Ctx) error {
+	isAdmin, err := h.svc.IsActorAdmin(c.UserContext())
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	limit := 0
+	offset := 0
+
+	filter := contact.ListFilter{
+		Role:                 normalizeContactRoleFilter(c.Query("role")),
+		PilotCategory:        strings.TrimSpace(c.Query("pilot_category")),
+		ChiefDoctor:          parseOptionalBoolQuery(c.Query("chief_doctor")),
+		ChiefTechnician:      parseOptionalBoolQuery(c.Query("chief_technician")),
+		ResponsibleComplaint: parseOptionalBoolQuery(c.Query("responsible_complaint")),
+		ChiefPilot:           parseOptionalBoolQuery(c.Query("chief_pilot")),
+		IFRQualified:         parseOptionalBoolQuery(c.Query("ifr_qualified")),
+		Search:               strings.TrimSpace(c.Query("search")),
+		Sort:                 strings.TrimSpace(c.Query("sort")),
+		Limit:                limit,
+		Offset:               offset,
+	}
+	items, total, err := h.svc.ListContacts(c.UserContext(), filter)
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	out := make([]jsonapi.Resource, 0, len(items))
+	for i := range items {
+		attrs := contactAttributes(&items[i], isAdmin)
+		h.applyContactFoto(c.UserContext(), &items[i], attrs)
+		out = append(out, jsonapi.Resource{
+			Type:       "contact",
+			ID:         contactUUIDString(items[i].UserID),
+			Attributes: attrs,
+		})
+	}
+	meta := map[string]any{"total": total, "limit": limit, "offset": offset}
+	return response.WriteWithMeta(c, fiber.StatusOK, out, meta)
+}
+
+// ListContactsDatatable godoc
+// @Summary List contacts (datatable)
+// @Description Datatable response with pagination params.
+// @Tags Contacts
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 1000)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Param role query string false "Role filter"
+// @Param pilot_category query string false "Pilot category filter"
+// @Param chief_doctor query bool false "Filter doctor chief flag"
+// @Param chief_technician query bool false "Filter technician chief flag"
+// @Param responsible_complaint query bool false "Filter responsible complaint flag"
+// @Param chief_pilot query bool false "Filter pilot chief flag"
+// @Param ifr_qualified query bool false "Filter IFR qualified flag"
+// @Success 200 {object} dto.ContactDataTableResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/contacts/get-all/dt [get]
+func (h *ContactHandler) ListDatatable(c *fiber.Ctx) error {
+	isAdmin, err := h.svc.IsActorAdmin(c.UserContext())
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > contactListMaxLimit {
+		length = contactListMaxLimit
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+
+	filter := contact.ListFilter{
+		Role:                 normalizeContactRoleFilter(c.Query("role")),
+		PilotCategory:        strings.TrimSpace(c.Query("pilot_category")),
+		ChiefDoctor:          parseOptionalBoolQuery(c.Query("chief_doctor")),
+		ChiefTechnician:      parseOptionalBoolQuery(c.Query("chief_technician")),
+		ResponsibleComplaint: parseOptionalBoolQuery(c.Query("responsible_complaint")),
+		ChiefPilot:           parseOptionalBoolQuery(c.Query("chief_pilot")),
+		IFRQualified:         parseOptionalBoolQuery(c.Query("ifr_qualified")),
+		Search:               strings.TrimSpace(c.Query("search")),
+		Sort:                 strings.TrimSpace(c.Query("sort")),
+		Limit:                length,
+		Offset:               start,
+	}
+	items, total, err := h.svc.ListContacts(c.UserContext(), filter)
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	out := make([]jsonapi.Resource, 0, len(items))
+	for i := range items {
+		attrs := contactAttributes(&items[i], isAdmin)
+		h.applyContactFoto(c.UserContext(), &items[i], attrs)
+		out = append(out, jsonapi.Resource{
+			Type:       "contact",
+			ID:         contactUUIDString(items[i].UserID),
+			Attributes: attrs,
+		})
+	}
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, out, meta)
+}
+
+// GetContact godoc
+// @Summary Get contact
+// @Tags Contacts
+// @Produce json
+// @Param user_id path string true "User UUID"
+// @Success 200 {object} dto.ContactListResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/contacts/{user_id} [get]
+func (h *ContactHandler) Get(c *fiber.Ctx) error {
+	userID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("user_id")))
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422", Title: "Validation error", Detail: "user_id is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/path/user_id"},
+		}})
+	}
+
+	return h.writeContactByID(c, userID)
+}
+
+func (h *ContactHandler) writeContactByID(c *fiber.Ctx, userID []byte) error {
+	item, err := h.svc.GetContactByID(c.UserContext(), userID)
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Get failed", Detail: "an internal error occurred"}})
+	}
+	if item == nil {
+		return writeContactErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "contact not found"}})
+	}
+	isAdmin, err := h.svc.IsActorAdmin(c.UserContext())
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Get failed", Detail: "an internal error occurred"}})
+	}
+	attrs := contactAttributes(item, isAdmin)
+	h.applyContactFoto(c.UserContext(), item, attrs)
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "contact", ID: contactUUIDString(item.UserID), Attributes: attrs})
+}
+
+// UpdateContact godoc
+// @Summary Update contact
+// @Description `data.type` must be `contact_update`.
+// @Description Supports updating `role_id` and `role_ids` (multiple roles) in the same request. Sending `role_ids: []` clears all assigned roles.
+// @Description Only one role-specific profile object is allowed in `attributes`. If provided, it must match one of the contact's assigned roles.
+// @Tags Contacts
+// @Accept json
+// @Produce json
+// @Param user_id path string true "User UUID"
+// @Param request body dto.ContactUpdateRequest true "JSON:API Contact update request"
+// @Success 200 {object} dto.ContactListResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/contacts/{user_id} [patch]
+func (h *ContactHandler) Update(c *fiber.Ctx) error {
+	userID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("user_id")))
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422", Title: "Validation error", Detail: "user_id is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/path/user_id"},
+		}})
+	}
+
+	var req dto.ContactUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	ssoEmailCleared := normalizeContactUpdateSSOEmailForValidation(&req)
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if errs := validatePilotDULBaseUpdateInput(req.Data.Attributes); len(errs) > 0 {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if ssoEmailCleared {
+		empty := ""
+		req.Data.Attributes.SSOEmail = &empty
+	}
+	if strings.TrimSpace(req.Data.Type) != contactUpdateType() {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{
+			contactValidationError("/data/type", fmt.Sprintf("type must be %s", contactUpdateType())),
+		})
+	}
+	current, err := h.svc.GetContactByID(c.UserContext(), userID)
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Get failed", Detail: "an internal error occurred"}})
+	}
+	if current == nil {
+		return writeContactErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "contact not found"}})
+	}
+	currentRoleCode := normalizeContactRoleCode(current.RoleCode)
+	nextPrimaryRoleID, nextRoleIDs, nextRoleCodes, updateRoles, roleErrs := h.parseContactUpdateRoleIDs(c, current, req.Data.Attributes)
+	if len(roleErrs) > 0 {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, roleErrs)
+	}
+	allowedRoleCodes := assignedContactRoleCodes(current)
+	if updateRoles {
+		allowedRoleCodes = nextRoleCodes
+		if errs := validateRoleSpecificCreatePayload(nextRoleCodes, req.Data.Type, profilePayloadsFromUpdate(req.Data.Attributes)); len(errs) > 0 {
+			return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+		}
+	}
+	requestedProfileRoleCodes, errs := validateRoleSpecificPayload(allowedRoleCodes, req.Data.Type, profilePayloadsFromUpdate(req.Data.Attributes))
+	if len(errs) > 0 {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	roleCodeForAdminValidation := currentRoleCode
+	if len(requestedProfileRoleCodes) > 0 {
+		roleCodeForAdminValidation = requestedProfileRoleCodes[0]
+	}
+	_ = updateRoles
+
+	profiles := make([]contact.CreateRoleProfile, 0, len(requestedProfileRoleCodes))
+	for i := range requestedProfileRoleCodes {
+		profiles = append(profiles, contact.CreateRoleProfile{
+			RoleCode: requestedProfileRoleCodes[i],
+			Patch:    profilePatchFromUpdate(requestedProfileRoleCodes[i], req.Data.Attributes),
+		})
+	}
+
+	in := contact.UpdateInput{
+		UserID: userID,
+		User: contact.UserPatch{
+			Email:       req.Data.Attributes.Email,
+			SSOEmail:    req.Data.Attributes.SSOEmail,
+			IsAdmin:     req.Data.Attributes.IsAdmin,
+			Username:    req.Data.Attributes.Username,
+			FirstName:   req.Data.Attributes.FirstName,
+			LastName:    req.Data.Attributes.LastName,
+			MobilePhone: req.Data.Attributes.MobilePhone,
+			Timezone:    req.Data.Attributes.Timezone,
+			SortKeySet:  req.Data.Attributes.SortKey.Set,
+			IsActive:    req.Data.Attributes.IsActive,
+		},
+		RoleID:            nextPrimaryRoleID,
+		RoleIDs:           nextRoleIDs,
+		UpdateRoles:       updateRoles,
+		Profile:           profilePatchFromUpdate(roleCodeForAdminValidation, req.Data.Attributes),
+		Profiles:          profiles,
+		TargetProfileRole: roleCodeForAdminValidation,
+	}
+	if req.Data.Attributes.SortKey.Set && req.Data.Attributes.SortKey.Valid {
+		sortKey := req.Data.Attributes.SortKey.Value
+		in.User.SortKey = &sortKey
+	}
+
+	if req.Data.Attributes.FileUUID != nil {
+		rawFileUUID := strings.TrimSpace(*req.Data.Attributes.FileUUID)
+		if rawFileUUID == "" {
+			empty := []byte(nil)
+			in.User.ProfileAttachmentID = &empty
+		} else {
+			attachmentID, handled := h.resolveContactProfileAttachmentID(c, userID, &rawFileUUID)
+			if handled {
+				return nil
+			}
+			in.User.ProfileAttachmentID = &attachmentID
+		}
+	}
+
+	if err := h.svc.UpdateContact(c.UserContext(), in); err != nil {
+		status := fiber.StatusBadRequest
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			status = fiber.StatusNotFound
+		} else if errors.Is(err, contact.ErrUsernameAlreadyExists) {
+			status = fiber.StatusConflict
+		}
+		title := "Update failed"
+		if status == fiber.StatusConflict {
+			title = "Conflict"
+		}
+		return writeContactErrors(c, status, []jsonapi.ErrorObject{{Status: intStatus(status), Title: title, Detail: "an internal error occurred"}})
+	}
+	return h.writeContactByID(c, userID)
+}
+
+// DeleteContact godoc
+// @Summary Delete contact
+// @Tags Contacts
+// @Produce json
+// @Param user_id path string true "User UUID"
+// @Success 200 {object} dto.ContactListResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/contacts/{user_id} [delete]
+func (h *ContactHandler) Delete(c *fiber.Ctx) error {
+	userID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("user_id")))
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "user_id is invalid UUID"}})
+	}
+	if err := h.svc.DeleteContact(c.UserContext(), userID); err != nil {
+		status := fiber.StatusBadRequest
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			status = fiber.StatusNotFound
+		}
+		return writeContactErrors(c, status, []jsonapi.ErrorObject{{Status: intStatus(status), Title: "Delete failed", Detail: "an internal error occurred"}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "contact_delete", Attributes: map[string]any{"deleted": true}})
+}
+
+// UpdateContactStatus godoc
+// @Summary Update contact active status
+// @Tags Contacts
+// @Accept json
+// @Produce json
+// @Param user_id path string true "User UUID"
+// @Param request body dto.ContactStatusUpdateRequest true "JSON:API status update request"
+// @Success 200 {object} dto.ContactSimpleSuccessResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/contacts/{user_id}/status [patch]
+func (h *ContactHandler) UpdateContactStatus(c *fiber.Ctx) error {
+	userID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("user_id")))
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "user_id is invalid UUID"}})
+	}
+	var req dto.ContactStatusUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if err := h.svc.UpdateContactStatus(c.UserContext(), userID, req.Data.Attributes.IsActive); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Update status failed", Detail: "an internal error occurred"}})
+	}
+	return h.writeContactByID(c, userID)
+}
+
+// UpdateContactRole godoc
+// @Summary Update contact role
+// @Tags Contacts
+// @Accept json
+// @Produce json
+// @Param user_id path string true "User UUID"
+// @Param request body dto.ContactRoleUpdateRequest true "JSON:API role update request"
+// @Success 200 {object} dto.ContactListResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/contacts/{user_id}/role [patch]
+func (h *ContactHandler) UpdateContactRole(c *fiber.Ctx) error {
+	userID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("user_id")))
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "user_id is invalid UUID"}})
+	}
+	var req dto.ContactRoleUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if err := h.svc.UpdateContactRole(c.UserContext(), userID, req.Data.Attributes.RoleCode); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Update role failed", Detail: "an internal error occurred"}})
+	}
+	return h.writeContactByID(c, userID)
+}
+
+// UpdatePilotCategory godoc
+// @Summary Update pilot category
+// @Tags Contacts
+// @Accept json
+// @Produce json
+// @Param user_id path string true "User UUID"
+// @Param request body dto.ContactPilotCategoryUpdateRequest true "JSON:API pilot category request"
+// @Success 200 {object} dto.ContactListResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/contacts/{user_id}/pilot-category [patch]
+func (h *ContactHandler) UpdatePilotCategory(c *fiber.Ctx) error {
+	userID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("user_id")))
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "user_id is invalid UUID"}})
+	}
+	var req dto.ContactPilotCategoryUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if err := h.svc.UpdatePilotCategory(c.UserContext(), userID, req.Data.Attributes.PilotCategory); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Update pilot category failed", Detail: "an internal error occurred"}})
+	}
+	return h.writeContactByID(c, userID)
+}
+
+// UpdateLicense godoc
+// @Summary Update contact license fields
+// @Tags Contacts
+// @Accept json
+// @Produce json
+// @Param user_id path string true "User UUID"
+// @Param request body dto.ContactLicenseUpdateRequest true "JSON:API license update request"
+// @Success 200 {object} dto.ContactListResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/contacts/{user_id}/license [patch]
+func (h *ContactHandler) UpdateLicense(c *fiber.Ctx) error {
+	userID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("user_id")))
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "user_id is invalid UUID"}})
+	}
+	var req dto.ContactLicenseUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if err := h.svc.UpdateLicense(c.UserContext(), userID, req.Data.Attributes.LicenseNo); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Update license failed", Detail: "an internal error occurred"}})
+	}
+	return h.writeContactByID(c, userID)
+}
+
+// UpdateChiefFlags godoc
+// @Summary Update chief flags
+// @Tags Contacts
+// @Accept json
+// @Produce json
+// @Param user_id path string true "User UUID"
+// @Param request body dto.ContactChiefFlagsUpdateRequest true "JSON:API chief flags request"
+// @Success 200 {object} dto.ContactListResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/contacts/{user_id}/chief-flags [patch]
+func (h *ContactHandler) UpdateChiefFlags(c *fiber.Ctx) error {
+	userID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("user_id")))
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "user_id is invalid UUID"}})
+	}
+	var req dto.ContactChiefFlagsUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	patch := contact.ProfilePatch{
+		IsChiefPilot:             req.Data.Attributes.IsChiefPilot,
+		IsChiefPhysician:         req.Data.Attributes.IsChiefPhysician,
+		IsChiefTechnician:        req.Data.Attributes.IsChiefTechnician,
+	}
+	if err := h.svc.UpdateChiefFlags(c.UserContext(), userID, patch); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Update chief flags failed", Detail: "an internal error occurred"}})
+	}
+	return h.writeContactByID(c, userID)
+}
+
+// BulkUpdateContacts godoc
+// @Summary Bulk update contacts status
+// @Tags Contacts
+// @Accept json
+// @Produce json
+// @Param request body dto.ContactBulkUpdateRequest true "JSON:API bulk update request"
+// @Success 200 {object} dto.ContactSimpleSuccessResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/contacts/bulk-update [post]
+func (h *ContactHandler) BulkUpdate(c *fiber.Ctx) error {
+	var req dto.ContactBulkUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeContactErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	ids := make([][]byte, 0, len(req.Data.Attributes.UserIDs))
+	for i := range req.Data.Attributes.UserIDs {
+		id, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.UserIDs[i]))
+		if err != nil {
+			return writeContactErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422", Title: "Validation error", Detail: "user_ids contains invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/user_ids"},
+			}})
+		}
+		ids = append(ids, id)
+	}
+
+	count, err := h.svc.BulkUpdateStatus(c.UserContext(), ids, req.Data.Attributes.IsActive)
+	if err != nil {
+		return writeContactErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Bulk update failed", Detail: "an internal error occurred"}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "contact_bulk_update", Attributes: map[string]any{"updated": true, "count": count}})
+}
+
+func profilePatchFromCreate(roleCode string, attrs dto.ContactCreateAttributes) contact.ProfilePatch {
+	p := contact.ProfilePatch{}
+	switch normalizeContactRoleCode(roleCode) {
+	case auth.RoleCodePilot:
+		fillPatchFromPilot(&p, attrs.Pilot)
+	case auth.RoleCodeDoctor:
+		fillPatchFromDoctor(&p, attrs.Doctor)
+	case auth.RoleCodeAirRescuer:
+		fillPatchFromAirRescuer(&p, attrs.AirRescuer)
+	case auth.RoleCodeTechnician:
+		fillPatchFromTechnician(&p, attrs.Technician)
+	case auth.RoleCodeFlightAssistant:
+		fillPatchFromFlightAssistant(&p, attrs.FlightAssistant)
+	case auth.RoleCodeStaff:
+		fillPatchFromStaff(&p, attrs.Staff)
+	}
+	return p
+}
+
+func profilePatchFromUpdate(roleCode string, attrs dto.ContactUpdateAttributes) contact.ProfilePatch {
+	p := contact.ProfilePatch{}
+	switch normalizeContactRoleCode(roleCode) {
+	case auth.RoleCodePilot:
+		fillPatchFromPilotUpdate(&p, attrs.Pilot)
+	case auth.RoleCodeDoctor:
+		fillPatchFromDoctorUpdate(&p, attrs.Doctor)
+	case auth.RoleCodeAirRescuer:
+		fillPatchFromAirRescuerUpdate(&p, attrs.AirRescuer)
+	case auth.RoleCodeTechnician:
+		fillPatchFromTechnicianUpdate(&p, attrs.Technician)
+	case auth.RoleCodeFlightAssistant:
+		fillPatchFromFlightAssistantUpdate(&p, attrs.FlightAssistant)
+	case auth.RoleCodeStaff:
+		fillPatchFromStaffUpdate(&p, attrs.Staff)
+	}
+	return p
+}
+
+func writeContactErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	return response.WriteErrors(c, status, apperrorsx.EnrichErrorObjects(status, errs))
+}
+
+func inferContactErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.CodeContactNotFound, apperrorsx.ErrContactNotFound.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "user_id is invalid uuid"):
+			return apperrorsx.CodeContactInvalidUserID, apperrorsx.ErrContactInvalidUserID.ErrorCode
+		default:
+			return apperrorsx.CodeContactValidationFailed, apperrorsx.ErrContactValidationFailed.ErrorCode
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.CodeContactInvalidJSON, apperrorsx.ErrContactInvalidJSON.ErrorCode
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.CodeContactCreateFailed, apperrorsx.ErrContactCreateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "get failed"):
+			return apperrorsx.CodeContactGetFailed, apperrorsx.ErrContactGetFailed.ErrorCode
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.CodeContactListFailed, apperrorsx.ErrContactListFailed.ErrorCode
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.CodeContactDeleteFailed, apperrorsx.ErrContactDeleteFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update status failed"):
+			return apperrorsx.CodeContactUpdateStatusFailed, apperrorsx.ErrContactUpdateStatusFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update role failed"):
+			return apperrorsx.CodeContactUpdateRoleFailed, apperrorsx.ErrContactUpdateRoleFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update pilot category failed"):
+			return apperrorsx.CodeContactUpdatePilotCategoryFailed, apperrorsx.ErrContactUpdatePilotCategoryFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update license failed"):
+			return apperrorsx.CodeContactUpdateLicenseFailed, apperrorsx.ErrContactUpdateLicenseFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update chief flags failed"):
+			return apperrorsx.CodeContactUpdateChiefFlagsFailed, apperrorsx.ErrContactUpdateChiefFlagsFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update responsible complaints failed"):
+			return apperrorsx.CodeContactUpdateResponsibleComplaintsFailed, apperrorsx.ErrContactUpdateResponsibleComplaintsFailed.ErrorCode
+		case strings.Contains(lowerTitle, "bulk update failed"):
+			return apperrorsx.CodeContactBulkUpdateFailed, apperrorsx.ErrContactBulkUpdateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.CodeContactUpdateFailed, apperrorsx.ErrContactUpdateFailed.ErrorCode
+		default:
+			if strings.Contains(lowerDetail, "duplicate") || strings.Contains(lowerDetail, "already") {
+				return apperrorsx.CodeContactInvalidPayload, apperrorsx.ErrContactInvalidPayload.ErrorCode
+			}
+			return apperrorsx.CodeContactInvalidPayload, apperrorsx.ErrContactInvalidPayload.ErrorCode
+		}
+	case fiber.StatusConflict:
+		switch {
+		case strings.Contains(lowerDetail, "username already exists"):
+			return apperrorsx.CodeContactUsernameConflict, apperrorsx.ErrContactUsernameConflict.ErrorCode
+		default:
+			return apperrorsx.CodeContactUsernameConflict, apperrorsx.ErrContactUsernameConflict.ErrorCode
+		}
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
+
+func validateContactCreatePayload(requestType string, resolvedRoleCodes []string, attrs dto.ContactCreateAttributes) []jsonapi.ErrorObject {
+	if strings.TrimSpace(requestType) != contactCreateType() {
+		return []jsonapi.ErrorObject{
+			contactValidationError("/data/type", fmt.Sprintf("type must be %s", contactCreateType())),
+		}
+	}
+	roleCodes := make([]string, 0, len(resolvedRoleCodes))
+	for i := range resolvedRoleCodes {
+		code := normalizeContactRoleCode(resolvedRoleCodes[i])
+		if !isSupportedContactRole(code) {
+			return []jsonapi.ErrorObject{
+				contactValidationError("/data/attributes/role_ids", "one or more role_ids are not supported contact roles"),
+			}
+		}
+		roleCodes = append(roleCodes, code)
+	}
+	errs := validateRoleSpecificCreatePayload(roleCodes, requestType, profilePayloadsFromCreate(attrs))
+	if len(errs) > 0 {
+		return errs
+	}
+	return errs
+}
+
+func validateRoleSpecificCreatePayload(expectedRoleCodes []string, requestType string, payloads []contactProfilePayload) []jsonapi.ErrorObject {
+	expected := make(map[string]struct{}, len(expectedRoleCodes))
+	for i := range expectedRoleCodes {
+		expected[normalizeContactRoleCode(expectedRoleCodes[i])] = struct{}{}
+	}
+	errs := make([]jsonapi.ErrorObject, 0)
+	for i := range payloads {
+		if !payloads[i].present {
+			continue
+		}
+		roleCode := normalizeContactRoleCode(payloads[i].roleCode)
+		if _, ok := expected[roleCode]; !ok {
+			errs = append(errs, contactValidationError("/data/attributes/"+payloads[i].field, fmt.Sprintf("%s payload is not allowed for type %s", payloads[i].field, strings.TrimSpace(requestType))))
+		}
+	}
+	for i := range payloads {
+		if _, ok := expected[normalizeContactRoleCode(payloads[i].roleCode)]; !ok {
+			continue
+		}
+		if !payloads[i].present {
+			errs = append(errs, contactValidationError("/data/attributes/"+payloads[i].field, fmt.Sprintf("%s payload is required when role is selected", payloads[i].field)))
+		}
+	}
+	return errs
+}
+
+func parseContactCreateRoleIDs(attrs dto.ContactCreateAttributes) ([]byte, [][]byte, []jsonapi.ErrorObject) {
+	raw := make([]string, 0, len(attrs.RoleIDs)+1)
+	for i := range attrs.RoleIDs {
+		roleID := strings.TrimSpace(attrs.RoleIDs[i])
+		if roleID != "" {
+			raw = append(raw, roleID)
+		}
+	}
+	if strings.TrimSpace(attrs.RoleID) != "" {
+		raw = append(raw, strings.TrimSpace(attrs.RoleID))
+	}
+	if len(raw) == 0 {
+		return nil, nil, nil
+	}
+	uniq := make([][]byte, 0, len(raw))
+	seen := make(map[string]struct{}, len(raw))
+	errs := make([]jsonapi.ErrorObject, 0)
+	for i := range raw {
+		roleID, err := uuidv7.ParseString(raw[i])
+		if err != nil {
+			errs = append(errs, contactValidationError("/data/attributes/role_ids", "role_ids contains invalid UUID"))
+			continue
+		}
+		key := string(roleID)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		uniq = append(uniq, roleID)
+	}
+	if len(errs) > 0 {
+		return nil, nil, errs
+	}
+	return uniq[0], uniq, nil
+}
+
+func (h *ContactHandler) parseContactUpdateRoleIDs(
+	c *fiber.Ctx,
+	current *contact.ContactListItem,
+	attrs dto.ContactUpdateAttributes,
+) ([]byte, [][]byte, []string, bool, []jsonapi.ErrorObject) {
+	roleIDProvided := attrs.RoleID != nil
+	roleIDsProvided := attrs.RoleIDs != nil
+	roleIDTrimmed := ""
+	roleIDExplicitClear := false
+	if roleIDProvided {
+		roleIDTrimmed = strings.TrimSpace(*attrs.RoleID)
+		if roleIDTrimmed == "" || strings.EqualFold(roleIDTrimmed, "null") {
+			roleIDExplicitClear = true
+			roleIDProvided = false
+		}
+	}
+	if !roleIDProvided && !roleIDsProvided {
+		if roleIDExplicitClear {
+			return nil, [][]byte{}, []string{}, true, nil
+		}
+		return nil, nil, nil, false, nil
+	}
+	if current == nil {
+		return nil, nil, nil, false, []jsonapi.ErrorObject{
+			contactValidationError("/data/attributes/role_ids", "contact not found"),
+		}
+	}
+
+	currentPrimaryRoleID, _ := roleIDBytesFromRoles(current)
+	currentRoleIDs := roleIDBytesListFromRoles(current)
+
+	primaryRoleID := currentPrimaryRoleID
+	if roleIDProvided {
+		parsedRoleID, err := uuidv7.ParseString(roleIDTrimmed)
+		if err != nil {
+			return nil, nil, nil, false, []jsonapi.ErrorObject{
+				contactValidationError("/data/attributes/role_id", "role_id is invalid UUID"),
+			}
+		}
+		primaryRoleID = parsedRoleID
+	}
+
+	roleIDs := currentRoleIDs
+	if roleIDsProvided {
+		if len(attrs.RoleIDs) == 0 {
+			if roleIDProvided {
+				return nil, nil, nil, false, []jsonapi.ErrorObject{
+					contactValidationError("/data/attributes/role_ids", "role_ids cannot be empty when role_id is provided"),
+				}
+			}
+			return nil, [][]byte{}, []string{}, true, nil
+		}
+		parsedRoleIDs := make([][]byte, 0, len(attrs.RoleIDs))
+		for i := range attrs.RoleIDs {
+			id, err := uuidv7.ParseString(strings.TrimSpace(attrs.RoleIDs[i]))
+			if err != nil {
+				return nil, nil, nil, false, []jsonapi.ErrorObject{
+					contactValidationError("/data/attributes/role_ids", "role_ids contains invalid UUID"),
+				}
+			}
+			parsedRoleIDs = append(parsedRoleIDs, id)
+		}
+		if !roleIDProvided && len(parsedRoleIDs) > 0 {
+			// When only role_ids is provided, treat the first role as the new primary.
+			primaryRoleID = parsedRoleIDs[0]
+		}
+		roleIDs = normalizeContactAssignedRoleIDs(primaryRoleID, parsedRoleIDs)
+	} else if roleIDProvided {
+		roleIDs = normalizeContactAssignedRoleIDs(primaryRoleID, currentRoleIDs)
+	}
+
+	if len(primaryRoleID) != 16 {
+		if len(roleIDs) > 0 {
+			primaryRoleID = roleIDs[0]
+		} else {
+			return nil, [][]byte{}, []string{}, true, nil
+		}
+	}
+	if !containsContactRoleID(roleIDs, primaryRoleID) {
+		roleIDs = normalizeContactAssignedRoleIDs(primaryRoleID, roleIDs)
+	}
+
+	roleCodes := make([]string, 0, len(roleIDs))
+	for i := range roleIDs {
+		code, err := h.svc.ResolveRoleCodeByID(c.UserContext(), roleIDs[i])
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return nil, nil, nil, false, []jsonapi.ErrorObject{
+					contactValidationError("/data/attributes/role_ids", "one or more role_ids do not exist"),
+				}
+			}
+			return nil, nil, nil, false, []jsonapi.ErrorObject{
+				{Status: "400", Title: "Update failed", Detail: "an internal error occurred"},
+			}
+		}
+		norm := normalizeContactRoleCode(code)
+		if !isSupportedContactRole(norm) {
+			return nil, nil, nil, false, []jsonapi.ErrorObject{
+				contactValidationError("/data/attributes/role_ids", "one or more role_ids are not supported contact roles"),
+			}
+		}
+		roleCodes = append(roleCodes, norm)
+	}
+	return primaryRoleID, roleIDs, roleCodes, true, nil
+}
+
+func normalizeContactAssignedRoleIDs(primaryRoleID []byte, roleIDs [][]byte) [][]byte {
+	out := make([][]byte, 0, len(roleIDs)+1)
+	seen := make(map[string]struct{}, len(roleIDs)+1)
+	appendRole := func(roleID []byte) {
+		if len(roleID) != 16 {
+			return
+		}
+		key := string(roleID)
+		if _, exists := seen[key]; exists {
+			return
+		}
+		seen[key] = struct{}{}
+		out = append(out, append([]byte(nil), roleID...))
+	}
+	appendRole(primaryRoleID)
+	for i := range roleIDs {
+		appendRole(roleIDs[i])
+	}
+	return out
+}
+
+func containsContactRoleID(roleIDs [][]byte, roleID []byte) bool {
+	if len(roleID) != 16 {
+		return false
+	}
+	target := string(roleID)
+	for i := range roleIDs {
+		if string(roleIDs[i]) == target {
+			return true
+		}
+	}
+	return false
+}
+
+func roleIDBytesFromRoles(item *contact.ContactListItem) ([]byte, bool) {
+	if item == nil || item.RolesRaw == nil {
+		return nil, false
+	}
+	roles := contactRoles(item.RolesRaw)
+	if len(roles) == 0 {
+		return nil, false
+	}
+	id, _ := roles[0]["id"].(string)
+	if strings.TrimSpace(id) == "" {
+		return nil, false
+	}
+	b, err := uuidv7.ParseString(strings.TrimSpace(id))
+	if err != nil {
+		return nil, false
+	}
+	return b, true
+}
+
+func roleIDBytesListFromRoles(item *contact.ContactListItem) [][]byte {
+	if item == nil || item.RolesRaw == nil {
+		return nil
+	}
+	roles := contactRoles(item.RolesRaw)
+	out := make([][]byte, 0, len(roles))
+	for i := range roles {
+		id, _ := roles[i]["id"].(string)
+		if strings.TrimSpace(id) == "" {
+			continue
+		}
+		b, err := uuidv7.ParseString(strings.TrimSpace(id))
+		if err != nil {
+			continue
+		}
+		out = append(out, b)
+	}
+	return out
+}
+
+func inferContactCreateRoleCodes(attrs dto.ContactCreateAttributes) []string {
+	payloads := profilePayloadsFromCreate(attrs)
+	roleCodes := make([]string, 0, len(payloads))
+	for i := range payloads {
+		if !payloads[i].present {
+			continue
+		}
+		roleCodes = append(roleCodes, normalizeContactRoleCode(payloads[i].roleCode))
+	}
+	return roleCodes
+}
+
+func validateRoleSpecificPayload(expectedRoleCodes []string, requestType string, payloads []contactProfilePayload) ([]string, []jsonapi.ErrorObject) {
+	expected := make(map[string]struct{}, len(expectedRoleCodes))
+	for i := range expectedRoleCodes {
+		code := normalizeContactRoleCode(expectedRoleCodes[i])
+		if code == "" {
+			continue
+		}
+		expected[code] = struct{}{}
+	}
+	requestedRoleCodes := make([]string, 0, len(payloads))
+	seenRequested := map[string]struct{}{}
+	errs := make([]jsonapi.ErrorObject, 0)
+	for i := range payloads {
+		if !payloads[i].present {
+			continue
+		}
+		code := normalizeContactRoleCode(payloads[i].roleCode)
+		if _, ok := seenRequested[code]; !ok {
+			seenRequested[code] = struct{}{}
+			requestedRoleCodes = append(requestedRoleCodes, code)
+		}
+	}
+	for i := range payloads {
+		if !payloads[i].present {
+			continue
+		}
+		roleCode := normalizeContactRoleCode(payloads[i].roleCode)
+		if _, ok := expected[roleCode]; !ok {
+			errs = append(errs, contactValidationError("/data/attributes/"+payloads[i].field, fmt.Sprintf("%s payload is not allowed for type %s", payloads[i].field, strings.TrimSpace(requestType))))
+		}
+	}
+	if len(errs) > 0 {
+		return nil, errs
+	}
+	return requestedRoleCodes, nil
+}
+
+func assignedContactRoleCodes(item *contact.ContactListItem) []string {
+	if item == nil {
+		return nil
+	}
+	seen := map[string]struct{}{}
+	out := make([]string, 0, 4)
+	add := func(code string) {
+		code = normalizeContactRoleCode(code)
+		if code == "" {
+			return
+		}
+		if _, ok := seen[code]; ok {
+			return
+		}
+		seen[code] = struct{}{}
+		out = append(out, code)
+	}
+	add(item.RoleCode)
+	for _, role := range contactRoles(item.RolesRaw) {
+		code, _ := role["role_code"].(string)
+		add(code)
+	}
+	return out
+}
+
+func profilePayloadsFromCreate(attrs dto.ContactCreateAttributes) []contactProfilePayload {
+	return []contactProfilePayload{
+		{roleCode: auth.RoleCodePilot, field: "pilot", present: attrs.Pilot != nil},
+		{roleCode: auth.RoleCodeDoctor, field: "doctor", present: attrs.Doctor != nil},
+		{roleCode: auth.RoleCodeAirRescuer, field: "air_rescuer", present: attrs.AirRescuer != nil},
+		{roleCode: auth.RoleCodeTechnician, field: "technician", present: attrs.Technician != nil},
+		{roleCode: auth.RoleCodeFlightAssistant, field: "flight_assistant", present: attrs.FlightAssistant != nil},
+		{roleCode: auth.RoleCodeStaff, field: "staff", present: attrs.Staff != nil},
+	}
+}
+
+func profilePayloadsFromUpdate(attrs dto.ContactUpdateAttributes) []contactProfilePayload {
+	return []contactProfilePayload{
+		{roleCode: auth.RoleCodePilot, field: "pilot", present: attrs.Pilot != nil},
+		{roleCode: auth.RoleCodeDoctor, field: "doctor", present: attrs.Doctor != nil},
+		{roleCode: auth.RoleCodeAirRescuer, field: "air_rescuer", present: attrs.AirRescuer != nil},
+		{roleCode: auth.RoleCodeTechnician, field: "technician", present: attrs.Technician != nil},
+		{roleCode: auth.RoleCodeFlightAssistant, field: "flight_assistant", present: attrs.FlightAssistant != nil},
+		{roleCode: auth.RoleCodeStaff, field: "staff", present: attrs.Staff != nil},
+	}
+}
+
+func normalizeContactRoleCode(roleCode string) string {
+	return strings.ToLower(strings.TrimSpace(roleCode))
+}
+
+func normalizeContactRoleFilter(role string) string {
+	v := normalizeContactRoleCode(role)
+	switch v {
+	case "technicians":
+		return auth.RoleCodeTechnician
+	default:
+		return v
+	}
+}
+
+func parseOptionalBoolQuery(value string) *bool {
+	v := strings.ToLower(strings.TrimSpace(value))
+	switch v {
+	case "", "null":
+		return nil
+	case "1", "true", "yes", "y":
+		out := true
+		return &out
+	case "0", "false", "no", "n":
+		out := false
+		return &out
+	default:
+		return nil
+	}
+}
+
+func contactCreateType() string {
+	return "contact_create"
+}
+
+func contactUpdateType() string {
+	return "contact_update"
+}
+
+func isSupportedContactRole(roleCode string) bool {
+	switch normalizeContactRoleCode(roleCode) {
+	case auth.RoleCodePilot, auth.RoleCodeDoctor, auth.RoleCodeAirRescuer, auth.RoleCodeTechnician, auth.RoleCodeFlightAssistant, auth.RoleCodeStaff:
+		return true
+	default:
+		return false
+	}
+}
+
+func contactValidationError(pointer string, detail string) jsonapi.ErrorObject {
+	return jsonapi.ErrorObject{
+		Status: "422",
+		Title:  "Validation error",
+		Detail: detail,
+		Source: &jsonapi.ErrorSource{Pointer: pointer},
+	}
+}
+
+func fillPatchFromPilot(out *contact.ProfilePatch, in *dto.PilotProfileAttributes) {
+	if out == nil || in == nil {
+		return
+	}
+	out.PilotCategory = optionalStr(in.PilotCategory)
+	out.ShortName = optionalStr(in.ShortName)
+	out.LicenseNo = optionalStr(in.LicenseNo)
+	out.LicenseIssuedAt = in.LicenseIssuedAt
+	out.LicenseExpiredAt = in.LicenseExpiredAt
+	out.TechnicianLicenseNo = optionalStr(in.TechnicianLicenseNo)
+	out.HasIFRQualification = in.HasIFRQualification
+	out.IsChiefPilot = in.IsChiefPilot
+	if in.DULBaseIDs != nil {
+		out.DULBaseIDsSet = true
+		out.DULBaseIDs = make([][]byte, 0, len(in.DULBaseIDs))
+		for i := range in.DULBaseIDs {
+			id, err := uuidv7.ParseString(strings.TrimSpace(in.DULBaseIDs[i]))
+			if err != nil {
+				continue
+			}
+			out.DULBaseIDs = append(out.DULBaseIDs, id)
+		}
+	} else if in.DULBase != nil {
+		// Support FE payload shape using dul_base object array.
+		out.DULBaseIDsSet = true
+		out.DULBaseIDs = make([][]byte, 0, len(in.DULBase))
+		for i := range in.DULBase {
+			id, err := uuidv7.ParseString(strings.TrimSpace(in.DULBase[i].ID))
+			if err != nil {
+				continue
+			}
+			out.DULBaseIDs = append(out.DULBaseIDs, id)
+		}
+	}
+	out.TotalFlightMinutes = in.TotalFlightMinutes
+	out.ResponsiblePilotMinutes = in.ResponsiblePilotMinutes
+	out.SecondPilotMinutes = in.SecondPilotMinutes
+	out.DoubleCommandMinutes = in.DoubleCommandMinutes
+	out.FlightInstructorMinutes = in.FlightInstructorMinutes
+	out.NightFlightMinutes = in.NightFlightMinutes
+	out.IFRFlightMinutes = in.IFRFlightMinutes
+	out.Location = optionalStr(in.Location)
+	out.Postcode = optionalStr(in.Postcode)
+	out.StreetLine = optionalStr(in.StreetLine)
+	out.Note = optionalStr(in.Note)
+	out.WeightKG = in.WeightKG
+}
+
+func fillPatchFromPilotUpdate(out *contact.ProfilePatch, in *dto.PilotProfileUpdateAttributes) {
+	if out == nil || in == nil {
+		return
+	}
+	out.PilotCategory = trimStringPointer(in.PilotCategory)
+	out.ShortName = trimStringPointer(in.ShortName)
+	out.LicenseNo = trimStringPointer(in.LicenseNo)
+	out.LicenseIssuedAt = in.LicenseIssuedAt
+	out.LicenseExpiredAt = in.LicenseExpiredAt
+	out.TechnicianLicenseNo = trimStringPointer(in.TechnicianLicenseNo)
+	out.HasIFRQualification = in.HasIFRQualification
+	out.IsChiefPilot = in.IsChiefPilot
+	if in.DULBaseIDs != nil {
+		out.DULBaseIDsSet = true
+		out.DULBaseIDs = make([][]byte, 0, len(in.DULBaseIDs))
+		for i := range in.DULBaseIDs {
+			id, err := uuidv7.ParseString(strings.TrimSpace(in.DULBaseIDs[i]))
+			if err != nil {
+				continue
+			}
+			out.DULBaseIDs = append(out.DULBaseIDs, id)
+		}
+	} else if in.DULBase != nil {
+		out.DULBaseIDsSet = true
+		out.DULBaseIDs = make([][]byte, 0, len(in.DULBase))
+		for i := range in.DULBase {
+			id, err := uuidv7.ParseString(strings.TrimSpace(in.DULBase[i].ID))
+			if err != nil {
+				continue
+			}
+			out.DULBaseIDs = append(out.DULBaseIDs, id)
+		}
+	}
+	out.TotalFlightMinutes = in.TotalFlightMinutes
+	out.ResponsiblePilotMinutes = in.ResponsiblePilotMinutes
+	out.SecondPilotMinutes = in.SecondPilotMinutes
+	out.DoubleCommandMinutes = in.DoubleCommandMinutes
+	out.FlightInstructorMinutes = in.FlightInstructorMinutes
+	out.NightFlightMinutes = in.NightFlightMinutes
+	out.IFRFlightMinutes = in.IFRFlightMinutes
+	out.Location = trimStringPointer(in.Location)
+	out.Postcode = trimStringPointer(in.Postcode)
+	out.StreetLine = trimStringPointer(in.StreetLine)
+	out.Note = trimStringPointer(in.Note)
+	out.WeightKG = in.WeightKG
+}
+
+func validatePilotDULBaseCreateInput(attrs dto.ContactCreateAttributes) []jsonapi.ErrorObject {
+	if attrs.Pilot == nil {
+		return nil
+	}
+	return validatePilotDULBaseValues(attrs.Pilot.DULBaseIDs, attrs.Pilot.DULBase)
+}
+
+func validatePilotDULBaseUpdateInput(attrs dto.ContactUpdateAttributes) []jsonapi.ErrorObject {
+	if attrs.Pilot == nil {
+		return nil
+	}
+	return validatePilotDULBaseValues(attrs.Pilot.DULBaseIDs, attrs.Pilot.DULBase)
+}
+
+func validatePilotDULBasePayload(pilot *dto.PilotProfileAttributes) []jsonapi.ErrorObject {
+	if pilot == nil {
+		return nil
+	}
+	return validatePilotDULBaseValues(pilot.DULBaseIDs, pilot.DULBase)
+}
+
+func validatePilotDULBaseValues(baseIDs []string, bases []dto.DULBase) []jsonapi.ErrorObject {
+	if baseIDs != nil && bases != nil {
+		return []jsonapi.ErrorObject{
+			contactValidationError("/data/attributes/pilot", "provide only one of dul_base_ids or dul_base"),
+		}
+	}
+	if baseIDs != nil {
+		for i := range baseIDs {
+			if _, err := uuidv7.ParseString(strings.TrimSpace(baseIDs[i])); err != nil {
+				return []jsonapi.ErrorObject{
+					contactValidationError("/data/attributes/pilot/dul_base_ids", "dul_base_ids contains invalid UUID"),
+				}
+			}
+		}
+	}
+	if bases != nil {
+		for i := range bases {
+			if _, err := uuidv7.ParseString(strings.TrimSpace(bases[i].ID)); err != nil {
+				return []jsonapi.ErrorObject{
+					contactValidationError("/data/attributes/pilot/dul_base", "dul_base contains invalid UUID"),
+				}
+			}
+		}
+	}
+	return nil
+}
+
+func validatePilotDULBasePayloadUpdate(pilot *dto.PilotProfileUpdateAttributes) []jsonapi.ErrorObject {
+	if pilot == nil {
+		return nil
+	}
+	return validatePilotDULBaseValues(pilot.DULBaseIDs, pilot.DULBase)
+}
+
+func fillPatchFromDoctor(out *contact.ProfilePatch, in *dto.DoctorProfileAttributes) {
+	if out == nil || in == nil {
+		return
+	}
+	out.ShortName = optionalStr(in.ShortName)
+	out.Specialization = optionalStr(in.Specialization)
+	out.SubSpecialization = optionalStr(in.SubSpecialization)
+	out.IsChiefPhysician = in.IsChiefPhysician
+	out.Location = optionalStr(in.Location)
+	out.Postcode = optionalStr(in.Postcode)
+	out.StreetLine = optionalStr(in.StreetLine)
+	out.Note = optionalStr(in.Note)
+}
+
+func fillPatchFromDoctorUpdate(out *contact.ProfilePatch, in *dto.DoctorProfileUpdateAttributes) {
+	if out == nil || in == nil {
+		return
+	}
+	out.ShortName = trimStringPointer(in.ShortName)
+	out.Specialization = trimStringPointer(in.Specialization)
+	out.SubSpecialization = trimStringPointer(in.SubSpecialization)
+	out.IsChiefPhysician = in.IsChiefPhysician
+	out.Location = trimStringPointer(in.Location)
+	out.Postcode = trimStringPointer(in.Postcode)
+	out.StreetLine = trimStringPointer(in.StreetLine)
+	out.Note = trimStringPointer(in.Note)
+}
+
+func fillPatchFromAirRescuer(out *contact.ProfilePatch, in *dto.AirRescuerProfileAttributes) {
+	if out == nil || in == nil {
+		return
+	}
+	out.ShortName = optionalStr(in.ShortName)
+	out.ResponsibleFlightRescuer = in.ResponsibleFlightRescuer
+	out.Location = optionalStr(in.Location)
+	out.Postcode = optionalStr(in.Postcode)
+	out.StreetLine = optionalStr(in.StreetLine)
+	out.Note = optionalStr(in.Note)
+}
+
+func fillPatchFromAirRescuerUpdate(out *contact.ProfilePatch, in *dto.AirRescuerProfileUpdateAttributes) {
+	if out == nil || in == nil {
+		return
+	}
+	out.ShortName = trimStringPointer(in.ShortName)
+	out.ResponsibleFlightRescuer = in.ResponsibleFlightRescuer
+	out.Location = trimStringPointer(in.Location)
+	out.Postcode = trimStringPointer(in.Postcode)
+	out.StreetLine = trimStringPointer(in.StreetLine)
+	out.Note = trimStringPointer(in.Note)
+}
+
+func fillPatchFromTechnician(out *contact.ProfilePatch, in *dto.TechnicianProfileAttributes) {
+	if out == nil || in == nil {
+		return
+	}
+	out.ShortName = optionalStr(in.ShortName)
+	out.LicenseNo = optionalStr(in.LicenseNo)
+	out.IsChiefTechnician = in.IsChiefTechnician
+	out.IsResponsibleComplaints = in.IsResponsibleComplaints
+	out.Location = optionalStr(in.Location)
+	out.Postcode = optionalStr(in.Postcode)
+	out.StreetLine = optionalStr(in.StreetLine)
+	out.Note = optionalStr(in.Note)
+}
+
+func fillPatchFromTechnicianUpdate(out *contact.ProfilePatch, in *dto.TechnicianProfileUpdateAttributes) {
+	if out == nil || in == nil {
+		return
+	}
+	out.ShortName = trimStringPointer(in.ShortName)
+	out.LicenseNo = trimStringPointer(in.LicenseNo)
+	out.IsChiefTechnician = in.IsChiefTechnician
+	out.IsResponsibleComplaints = in.IsResponsibleComplaints
+	out.Location = trimStringPointer(in.Location)
+	out.Postcode = trimStringPointer(in.Postcode)
+	out.StreetLine = trimStringPointer(in.StreetLine)
+	out.Note = trimStringPointer(in.Note)
+}
+
+func fillPatchFromFlightAssistant(out *contact.ProfilePatch, in *dto.FlightAssistantProfileAttributes) {
+	if out == nil || in == nil {
+		return
+	}
+	out.ShortName = optionalStr(in.ShortName)
+	out.Location = optionalStr(in.Location)
+	out.Postcode = optionalStr(in.Postcode)
+	out.StreetLine = optionalStr(in.StreetLine)
+	out.Note = optionalStr(in.Note)
+}
+
+func fillPatchFromFlightAssistantUpdate(out *contact.ProfilePatch, in *dto.FlightAssistantProfileUpdateAttributes) {
+	if out == nil || in == nil {
+		return
+	}
+	out.ShortName = trimStringPointer(in.ShortName)
+	out.Location = trimStringPointer(in.Location)
+	out.Postcode = trimStringPointer(in.Postcode)
+	out.StreetLine = trimStringPointer(in.StreetLine)
+	out.Note = trimStringPointer(in.Note)
+}
+
+func fillPatchFromStaff(out *contact.ProfilePatch, in *dto.StaffProfileAttributes) {
+	if out == nil || in == nil {
+		return
+	}
+	out.ShortName = optionalStr(in.ShortName)
+	out.RoleLabel = optionalStr(in.RoleLabel)
+	out.Location = optionalStr(in.Location)
+	out.Postcode = optionalStr(in.Postcode)
+	out.StreetLine = optionalStr(in.StreetLine)
+	out.Note = optionalStr(in.Note)
+}
+
+func fillPatchFromStaffUpdate(out *contact.ProfilePatch, in *dto.StaffProfileUpdateAttributes) {
+	if out == nil || in == nil {
+		return
+	}
+	out.ShortName = trimStringPointer(in.ShortName)
+	out.RoleLabel = trimStringPointer(in.RoleLabel)
+	out.Location = trimStringPointer(in.Location)
+	out.Postcode = trimStringPointer(in.Postcode)
+	out.StreetLine = trimStringPointer(in.StreetLine)
+	out.Note = trimStringPointer(in.Note)
+}
+
+func optionalStr(v string) *string {
+	t := strings.TrimSpace(v)
+	if t == "" {
+		return nil
+	}
+	return &t
+}
+
+func trimStringPointer(v *string) *string {
+	if v == nil {
+		return nil
+	}
+	trimmed := strings.TrimSpace(*v)
+	return &trimmed
+}
+
+func strPtr(v string) *string {
+	return &v
+}
+
+func emptyToNil(v string) *string {
+	if strings.TrimSpace(v) == "" {
+		return nil
+	}
+	return &v
+}
+
+func normalizeContactUpdateSSOEmailForValidation(req *dto.ContactUpdateRequest) bool {
+	if req == nil {
+		return false
+	}
+	if req.Data.Attributes.SSOEmail == nil {
+		return false
+	}
+	trimmed := strings.TrimSpace(*req.Data.Attributes.SSOEmail)
+	if trimmed == "" {
+		// For validation, empty SSO email should be treated as omitted.
+		// After validation succeeds, caller can restore explicit empty to clear DB value.
+		req.Data.Attributes.SSOEmail = nil
+		return true
+	}
+	req.Data.Attributes.SSOEmail = &trimmed
+	return false
+}
+
+func contactUUIDString(id []byte) string {
+	s, _ := uuidv7.BytesToString(id)
+	return s
+}
+
+func contactAttributes(item *contact.ContactListItem, includeSSOEmail bool) map[string]any {
+	if item == nil {
+		return map[string]any{}
+	}
+	roles := contactRoles(item.RolesRaw)
+	if roles == nil {
+		roles = []map[string]any{}
+	}
+	attrs := map[string]any{
+		"pilot_category":  item.PilotCategory,
+		"username":        item.Username,
+		"email":           item.Email,
+		"is_admin":        item.IsAdmin,
+		"first_name":      item.FirstName,
+		"last_name":       item.LastName,
+		"short_name":      item.ShortName,
+		"license_no":      item.LicenseNo,
+		"location":        item.Location,
+		"mobile_phone":    item.MobilePhone,
+		"set_password":    !item.HasPassword,
+		"sortkey":         cloneIntPointer(item.SortKey),
+		"note":            item.Note,
+		"is_active":       item.IsActive,
+		"created_by":      uuidStringOrEmpty(item.CreatedBy),
+		"updated_by":      uuidStringOrEmpty(item.UpdatedBy),
+		"created_at":      optionalTimeRFC3339(item.CreatedAt),
+		"updated_at":      optionalTimeRFC3339(item.UpdatedAt),
+		"base_roles":      contactBaseRoles(item.BaseRolesRaw),
+	}
+	attrs["roles"] = roles
+	if includeSSOEmail {
+		attrs["sso_email"] = item.SSOEmail
+	}
+	roleCodes := map[string]struct{}{normalizeContactRoleCode(item.RoleCode): {}}
+	for _, role := range roles {
+		code, _ := role["role_code"].(string)
+		if strings.TrimSpace(code) == "" {
+			continue
+		}
+		roleCodes[normalizeContactRoleCode(code)] = struct{}{}
+	}
+	if _, ok := roleCodes[auth.RoleCodePilot]; ok {
+		dulBases := contactDULBases(item.BaseRolesRaw)
+		if strings.TrimSpace(item.PilotCategory) != "" ||
+			item.PilotShortName != nil || item.PilotLicenseNo != nil || item.PilotLicenseIssuedAt != nil || item.PilotLicenseExpiredAt != nil ||
+			item.PilotTechnicianLicenseNo != nil || item.PilotHasIFRQualification != nil || item.PilotIsChiefPilot != nil || item.PilotIsDUL != nil ||
+			item.PilotTotalFlightMinutes != nil || item.PilotResponsiblePilotMinutes != nil ||
+			item.PilotSecondPilotMinutes != nil || item.PilotDoubleCommandMinutes != nil || item.PilotFlightInstructorMinutes != nil ||
+			item.PilotNightFlightMinutes != nil || item.PilotIFRFlightMinutes != nil || item.PilotLocation != nil || item.PilotPostcode != nil ||
+			item.PilotStreetLine != nil || item.PilotNote != nil || item.PilotWeightKG != nil || len(dulBases) > 0 {
+			attrs["pilot"] = map[string]any{
+				"pilot_category":            item.PilotCategory,
+				"short_name":                item.PilotShortName,
+				"license_no":                item.PilotLicenseNo,
+				"license_issued_at":         item.PilotLicenseIssuedAt,
+				"license_expired_at":        item.PilotLicenseExpiredAt,
+				"technician_license_no":     item.PilotTechnicianLicenseNo,
+				"has_ifr_qualification":     item.PilotHasIFRQualification,
+				"is_chief_pilot":            item.PilotIsChiefPilot,
+				"is_dul":                    item.PilotIsDUL,
+				"dul_base":                  dulBases,
+				"total_flight_minutes":      item.PilotTotalFlightMinutes,
+				"responsible_pilot_minutes": item.PilotResponsiblePilotMinutes,
+				"second_pilot_minutes":      item.PilotSecondPilotMinutes,
+				"double_command_minutes":    item.PilotDoubleCommandMinutes,
+				"flight_instructor_minutes": item.PilotFlightInstructorMinutes,
+				"night_flight_minutes":      item.PilotNightFlightMinutes,
+				"ifr_flight_minutes":        item.PilotIFRFlightMinutes,
+				"location":                  item.PilotLocation,
+				"postcode":                  item.PilotPostcode,
+				"street_line":               item.PilotStreetLine,
+				"note":                      item.PilotNote,
+				"weight_kg":                 item.PilotWeightKG,
+			}
+			removeContactAttributeKeys(attrs, "pilot_category", "short_name", "license_no", "location", "note")
+		}
+	}
+	if _, ok := roleCodes[auth.RoleCodeDoctor]; ok {
+		if item.DoctorShortName != nil || item.DoctorSpecialization != nil || item.DoctorSubSpecialization != nil ||
+			item.DoctorIsChiefPhysician != nil || item.DoctorLocation != nil || item.DoctorPostcode != nil ||
+			item.DoctorStreetLine != nil || item.DoctorNote != nil {
+			attrs["doctor"] = map[string]any{
+				"short_name":         item.DoctorShortName,
+				"specialization":     item.DoctorSpecialization,
+				"sub_specialization": item.DoctorSubSpecialization,
+				"is_chief_physician": item.DoctorIsChiefPhysician,
+				"location":           item.DoctorLocation,
+				"postcode":           item.DoctorPostcode,
+				"street_line":        item.DoctorStreetLine,
+				"note":               item.DoctorNote,
+			}
+			removeContactAttributeKeys(attrs, "short_name", "location", "note", "license_no", "pilot_category")
+		}
+	}
+	if _, ok := roleCodes[auth.RoleCodeAirRescuer]; ok {
+		if item.AirRescuerShortName != nil || item.AirRescuerResponsibleFlightRescuer != nil ||
+			item.AirRescuerLocation != nil || item.AirRescuerPostcode != nil || item.AirRescuerStreetLine != nil || item.AirRescuerNote != nil {
+			attrs["air_rescuer"] = map[string]any{
+				"short_name":                 item.AirRescuerShortName,
+				"responsible_flight_rescuer": item.AirRescuerResponsibleFlightRescuer,
+				"location":                   item.AirRescuerLocation,
+				"postcode":                   item.AirRescuerPostcode,
+				"street_line":                item.AirRescuerStreetLine,
+				"note":                       item.AirRescuerNote,
+			}
+			removeContactAttributeKeys(attrs, "short_name", "location", "note", "license_no", "pilot_category")
+		}
+	}
+	if _, ok := roleCodes[auth.RoleCodeTechnician]; ok {
+		if item.TechnicianShortName != nil || item.TechnicianLicenseNo != nil || item.TechnicianIsChiefTechnician != nil ||
+			item.TechnicianIsResponsibleComplaints != nil || item.TechnicianLocation != nil || item.TechnicianPostcode != nil ||
+			item.TechnicianStreetLine != nil || item.TechnicianNote != nil {
+			attrs["technician"] = map[string]any{
+				"short_name":                item.TechnicianShortName,
+				"license_no":                item.TechnicianLicenseNo,
+				"is_chief_technician":       item.TechnicianIsChiefTechnician,
+				"is_responsible_complaints": item.TechnicianIsResponsibleComplaints,
+				"location":                  item.TechnicianLocation,
+				"postcode":                  item.TechnicianPostcode,
+				"street_line":               item.TechnicianStreetLine,
+				"note":                      item.TechnicianNote,
+			}
+			removeContactAttributeKeys(attrs, "short_name", "license_no", "location", "note", "pilot_category")
+		}
+	}
+	if _, ok := roleCodes[auth.RoleCodeFlightAssistant]; ok {
+		if item.FlightAssistantShortName != nil || item.FlightAssistantLocation != nil || item.FlightAssistantPostcode != nil ||
+			item.FlightAssistantStreetLine != nil || item.FlightAssistantNote != nil {
+			attrs["flight_assistant"] = map[string]any{
+				"short_name":  item.FlightAssistantShortName,
+				"location":    item.FlightAssistantLocation,
+				"postcode":    item.FlightAssistantPostcode,
+				"street_line": item.FlightAssistantStreetLine,
+				"note":        item.FlightAssistantNote,
+			}
+			removeContactAttributeKeys(attrs, "short_name", "location", "note", "license_no", "pilot_category")
+		}
+	}
+	if _, ok := roleCodes[auth.RoleCodeStaff]; ok {
+		if item.StaffShortName != nil || item.StaffRoleLabel != nil || item.StaffLocation != nil ||
+			item.StaffPostcode != nil || item.StaffStreetLine != nil || item.StaffNote != nil {
+			attrs["staff"] = map[string]any{
+				"short_name":  item.StaffShortName,
+				"role_label":  item.StaffRoleLabel,
+				"location":    item.StaffLocation,
+				"postcode":    item.StaffPostcode,
+				"street_line": item.StaffStreetLine,
+				"note":        item.StaffNote,
+			}
+			removeContactAttributeKeys(attrs, "short_name", "location", "note", "license_no", "pilot_category")
+		}
+	}
+	return attrs
+}
+
+func removeContactAttributeKeys(attrs map[string]any, keys ...string) {
+	for _, key := range keys {
+		delete(attrs, key)
+	}
+}
+
+func (h *ContactHandler) resolveContactProfileAttachmentID(c *fiber.Ctx, userID []byte, rawFileUUID *string) ([]byte, bool) {
+	if rawFileUUID == nil {
+		return nil, false
+	}
+	if strings.TrimSpace(*rawFileUUID) == "" {
+		return nil, false
+	}
+	return resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+		FileManager: h.fileManager,
+
+		RawAttachmentID: nil,
+		RawFileID:       rawFileUUID,
+
+		AttachmentField: "profile_attachment_id",
+		FileField:       "file_uuid",
+
+		RequireValue: false,
+
+		RefType:  contactProfileAttachmentRefType,
+		RefID:    idString(userID),
+		Category: ptrString(contactProfileAttachmentCategory),
+
+		IsPrimary: true,
+		ActorID:   actorUserID(c),
+
+		ValidateAttachmentExists: false,
+	}, "Update failed")
+}
+
+func (h *ContactHandler) applyContactFoto(ctx context.Context, item *contact.ContactListItem, attrs map[string]any) {
+	if item == nil || attrs == nil || len(item.ProfileAttachmentID) != 16 {
+		return
+	}
+	fotoUUID := idString(item.ProfileAttachmentID)
+	fotoDownloadURL := ""
+	fotoThumbnailURL := ""
+	var fotoOriginalSizeBytes *int64
+	if h.fileManager != nil {
+		attachment, err := h.fileManager.GetAttachmentByID(ctx, item.ProfileAttachmentID)
+		if err == nil && attachment != nil {
+			fotoUUID = idString(attachment.ID)
+			if attachment.File != nil {
+				asset := resolveFileManagerDownloadURLs(ctx, h.storage, attachment.File)
+				fotoDownloadURL = strings.TrimSpace(asset.OriginalURL)
+				fotoThumbnailURL = strings.TrimSpace(asset.ThumbnailURL)
+				fotoOriginalSizeBytes = int64Ptr(asset.OriginalSizeBytes)
+			}
+		}
+	}
+	attrs["foto"] = map[string]any{
+		"uuid":                   fotoUUID,
+		"download_url":           fotoDownloadURL,
+		"thumbnail_download_url": fotoThumbnailURL,
+		"original_size_bytes":    fotoOriginalSizeBytes,
+	}
+}
+
+func (h *ContactHandler) ensureContactProfileAttachmentSet(ctx context.Context, userID []byte) error {
+	item, err := h.svc.GetContactByID(ctx, userID)
+	if err != nil {
+		return err
+	}
+	if item == nil || len(item.ProfileAttachmentID) != 16 {
+		return errors.New("failed to set profile photo")
+	}
+	if h.fileManager != nil {
+		attachment, err := h.fileManager.GetAttachmentByID(ctx, item.ProfileAttachmentID)
+		if err != nil || attachment == nil {
+			return errors.New("failed to set profile photo")
+		}
+	}
+	return nil
+}
+
+func contactBaseRoles(raw *string) []map[string]any {
+	if raw == nil || strings.TrimSpace(*raw) == "" {
+		return nil
+	}
+	parts := strings.Split(*raw, ",")
+	out := make([]map[string]any, 0, len(parts))
+	for i := range parts {
+		fields := strings.Split(parts[i], "|")
+		if len(fields) < 3 {
+			continue
+		}
+		hexID := strings.TrimSpace(fields[0])
+		baseNameHex := strings.TrimSpace(fields[1])
+		roleCode := strings.TrimSpace(fields[2])
+		baseCategoryHex := ""
+		if len(fields) >= 4 {
+			baseCategoryHex = strings.TrimSpace(fields[3])
+		}
+		if hexID == "" || roleCode == "" {
+			continue
+		}
+		idBytes, err := hex.DecodeString(hexID)
+		if err != nil {
+			continue
+		}
+		baseID, err := uuidv7.BytesToString(idBytes)
+		if err != nil {
+			continue
+		}
+		baseNameBytes, err := hex.DecodeString(baseNameHex)
+		if err != nil {
+			continue
+		}
+		item := map[string]any{
+			"base_id":   baseID,
+			"base_name": string(baseNameBytes),
+			"role_code": roleCode,
+		}
+		if baseCategoryHex != "" {
+			if baseCategoryBytes, err := hex.DecodeString(baseCategoryHex); err == nil {
+				item["base_category"] = string(baseCategoryBytes)
+			}
+		}
+		out = append(out, item)
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func contactDULBases(raw *string) []map[string]any {
+	roles := contactBaseRoles(raw)
+	if len(roles) == 0 {
+		return nil
+	}
+	out := make([]map[string]any, 0)
+	for i := range roles {
+		roleCode, _ := roles[i]["role_code"].(string)
+		if strings.TrimSpace(strings.ToLower(roleCode)) != "dul" {
+			continue
+		}
+		baseID, _ := roles[i]["base_id"].(string)
+		baseName, _ := roles[i]["base_name"].(string)
+		baseCategory, _ := roles[i]["base_category"].(string)
+		if strings.TrimSpace(baseID) == "" {
+			continue
+		}
+		out = append(out, map[string]any{
+			"id":       baseID,
+			"name":     baseName,
+			"category": baseCategory,
+		})
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func contactRoles(raw *string) []map[string]any {
+	if raw == nil || strings.TrimSpace(*raw) == "" {
+		return []map[string]any{}
+	}
+	parts := strings.Split(*raw, ",")
+	out := make([]map[string]any, 0, len(parts))
+	for i := range parts {
+		fields := strings.Split(parts[i], "|")
+		if len(fields) != 3 {
+			continue
+		}
+		roleIDHex := strings.TrimSpace(fields[0])
+		roleNameHex := strings.TrimSpace(fields[1])
+		roleCode := strings.TrimSpace(fields[2])
+		if roleIDHex == "" || roleCode == "" {
+			continue
+		}
+		roleIDBytes, err := hex.DecodeString(roleIDHex)
+		if err != nil {
+			continue
+		}
+		roleID, err := uuidv7.BytesToString(roleIDBytes)
+		if err != nil {
+			continue
+		}
+		roleNameBytes, err := hex.DecodeString(roleNameHex)
+		if err != nil {
+			continue
+		}
+		out = append(out, map[string]any{
+			"id":        roleID,
+			"role_code": roleCode,
+			"role_name": string(roleNameBytes),
+		})
+	}
+	if len(out) == 0 {
+		return []map[string]any{}
+	}
+	return out
+}
+
+func intStatus(status int) string {
+	if status == fiber.StatusNotFound {
+		return "404"
+	}
+	return "400"
+}
+
+func optionalTimeRFC3339(v time.Time) string {
+	if v.IsZero() {
+		return ""
+	}
+	return v.UTC().Format(time.RFC3339)
+}
diff --git a/internal/transport/http/handlers/contact_handler_test.go b/internal/transport/http/handlers/contact_handler_test.go
new file mode 100644
index 0000000..a3270c5
--- /dev/null
+++ b/internal/transport/http/handlers/contact_handler_test.go
@@ -0,0 +1,1841 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/hex"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/contact"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+)
+
+type stubContactService struct {
+	listItems  []contact.ContactListItem
+	listTotal  int64
+	listErr    error
+	lastFilter contact.ListFilter
+
+	getItem *contact.ContactListItem
+	getErr  error
+
+	resolveRoleCode     string
+	resolveRoleCodeByID map[string]string
+	resolveRoleErr      error
+	lastResolveID       []byte
+
+	createUserID []byte
+	createErr    error
+	lastCreate   contact.CreateInput
+
+	updateErr  error
+	lastUpdate contact.UpdateInput
+
+	deleteErr    error
+	lastDeleteID []byte
+
+	updateStatusErr    error
+	lastUpdateStatusID []byte
+	lastIsActive       bool
+
+	updateRoleErr    error
+	lastUpdateRoleID []byte
+	lastRoleCode     string
+
+	updatePilotCategoryErr error
+	lastUpdatePilotID      []byte
+	lastPilotCategory      string
+
+	updateLicenseErr    error
+	lastUpdateLicenseID []byte
+	lastLicenseNo       *string
+	updateChiefFlagsErr        error
+	lastUpdateChiefFlagsID     []byte
+	lastChiefFlags             contact.ProfilePatch
+	updateResponsibleErr       error
+	lastUpdateResponsibleID    []byte
+	lastResponsibleComplaints  bool
+	bulkUpdateErr              error
+	bulkUpdateCount            int64
+	lastBulkIDs                [][]byte
+	lastBulkIsActive           bool
+	checkSensitiveActionCalled bool
+	isActorAdmin               bool
+	isActorAdminErr            error
+}
+
+func (s *stubContactService) ListContacts(_ context.Context, filter contact.ListFilter) ([]contact.ContactListItem, int64, error) {
+	s.lastFilter = filter
+	if s.listErr != nil {
+		return nil, 0, s.listErr
+	}
+	return s.listItems, s.listTotal, nil
+}
+
+func (s *stubContactService) GetContactByID(_ context.Context, userID []byte) (*contact.ContactListItem, error) {
+	if s.getErr != nil {
+		return nil, s.getErr
+	}
+	if s.getItem != nil && len(s.getItem.UserID) == 0 {
+		copyItem := *s.getItem
+		copyItem.UserID = append([]byte(nil), userID...)
+		return &copyItem, nil
+	}
+	return s.getItem, nil
+}
+
+func (s *stubContactService) IsActorAdmin(_ context.Context) (bool, error) {
+	if s.isActorAdminErr != nil {
+		return false, s.isActorAdminErr
+	}
+	return s.isActorAdmin, nil
+}
+
+func (s *stubContactService) ResolveRoleCodeByID(_ context.Context, roleID []byte) (string, error) {
+	s.lastResolveID = append([]byte(nil), roleID...)
+	if s.resolveRoleErr != nil {
+		return "", s.resolveRoleErr
+	}
+	if s.resolveRoleCodeByID != nil {
+		if code, ok := s.resolveRoleCodeByID[string(roleID)]; ok {
+			return code, nil
+		}
+	}
+	return s.resolveRoleCode, nil
+}
+
+func (s *stubContactService) CreateContact(_ context.Context, in contact.CreateInput) ([]byte, error) {
+	s.lastCreate = in
+	if s.createErr != nil {
+		return nil, s.createErr
+	}
+	if len(s.createUserID) == 0 {
+		s.createUserID = uuidv7.MustBytes()
+	}
+	return s.createUserID, nil
+}
+
+func (s *stubContactService) UpdateContact(_ context.Context, in contact.UpdateInput) error {
+	s.lastUpdate = in
+	return s.updateErr
+}
+
+func (s *stubContactService) DeleteContact(_ context.Context, userID []byte) error {
+	s.lastDeleteID = append([]byte(nil), userID...)
+	return s.deleteErr
+}
+
+func (s *stubContactService) UpdateContactStatus(_ context.Context, userID []byte, isActive bool) error {
+	s.lastUpdateStatusID = append([]byte(nil), userID...)
+	s.lastIsActive = isActive
+	return s.updateStatusErr
+}
+
+func (s *stubContactService) UpdateContactRole(_ context.Context, userID []byte, roleCode string) error {
+	s.lastUpdateRoleID = append([]byte(nil), userID...)
+	s.lastRoleCode = roleCode
+	return s.updateRoleErr
+}
+
+func (s *stubContactService) UpdatePilotCategory(_ context.Context, userID []byte, category string) error {
+	s.lastUpdatePilotID = append([]byte(nil), userID...)
+	s.lastPilotCategory = category
+	return s.updatePilotCategoryErr
+}
+
+func (s *stubContactService) UpdateLicense(_ context.Context, userID []byte, licenseNo *string) error {
+	s.lastUpdateLicenseID = append([]byte(nil), userID...)
+	s.lastLicenseNo = licenseNo
+	return s.updateLicenseErr
+}
+
+func (s *stubContactService) UpdateChiefFlags(_ context.Context, userID []byte, patch contact.ProfilePatch) error {
+	s.lastUpdateChiefFlagsID = append([]byte(nil), userID...)
+	s.lastChiefFlags = patch
+	return s.updateChiefFlagsErr
+}
+
+func (s *stubContactService) UpdateResponsibleComplaints(_ context.Context, userID []byte, value bool) error {
+	s.lastUpdateResponsibleID = append([]byte(nil), userID...)
+	s.lastResponsibleComplaints = value
+	return s.updateResponsibleErr
+}
+
+func (s *stubContactService) BulkUpdateStatus(_ context.Context, userIDs [][]byte, isActive bool) (int64, error) {
+	s.lastBulkIDs = append([][]byte(nil), userIDs...)
+	s.lastBulkIsActive = isActive
+	if s.bulkUpdateErr != nil {
+		return 0, s.bulkUpdateErr
+	}
+	return s.bulkUpdateCount, nil
+}
+
+func (s *stubContactService) CheckSensitiveAction(_ context.Context, _ []byte, _ string, _ string) error {
+	s.checkSensitiveActionCalled = true
+	return nil
+}
+
+type stubContactInviter struct {
+	err        error
+	lastUserID []byte
+}
+
+func (s *stubContactInviter) SendInviteSetPasswordForUser(_ context.Context, userID []byte) error {
+	s.lastUserID = append([]byte(nil), userID...)
+	return s.err
+}
+
+func newContactTestApp(h *ContactHandler) *fiber.App {
+	app := fiber.New()
+	app.Post("/contacts/create", h.Create)
+	app.Get("/contacts", h.List)
+	app.Get("/contacts/dt", h.ListDatatable)
+	app.Get("/contacts/:user_id", h.Get)
+	app.Patch("/contacts/:user_id", h.Update)
+	app.Delete("/contacts/:user_id", h.Delete)
+	app.Patch("/contacts/:user_id/status", h.UpdateContactStatus)
+	app.Patch("/contacts/:user_id/role", h.UpdateContactRole)
+	app.Patch("/contacts/:user_id/pilot-category", h.UpdatePilotCategory)
+	app.Patch("/contacts/:user_id/license", h.UpdateLicense)
+	app.Patch("/contacts/:user_id/chief-flags", h.UpdateChiefFlags)
+	app.Post("/contacts/bulk-update", h.BulkUpdate)
+	return app
+}
+
+func doJSONRequestContact(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDStringContact(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func mustRoleRawContact(t *testing.T, roleID []byte, roleName, roleCode string) string {
+	t.Helper()
+	return strings.ToLower(hex.EncodeToString(roleID)) + "|" +
+		strings.ToLower(hex.EncodeToString([]byte(roleName))) + "|" + roleCode
+}
+
+func strPtrContact(v string) *string { return &v }
+func boolPtrContact(v bool) *bool    { return &v }
+func intPtrContact(v int) *int       { return &v }
+func floatPtrContact(v float64) *float64 {
+	return &v
+}
+
+func TestNewContactHandler(t *testing.T) {
+	h := NewContactHandler(&stubContactService{}, &stubContactInviter{})
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+	h = h.WithFileManagerService(nil).WithFileStorage(nil)
+	if h == nil {
+		t.Fatalf("expected chain methods return handler")
+	}
+}
+
+func TestContactHandlerCreate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid role id", func(t *testing.T) {
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		body := []byte(`{"data":{"type":"contact_create","attributes":{"role_id":"bad","email":"user@example.com"}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid create type", func(t *testing.T) {
+		svc := &stubContactService{resolveRoleCode: "doctor"}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		roleID := mustUUIDStringContact(t, uuidv7.MustBytes())
+		body := []byte(`{"data":{"type":"contact_pilot_create","attributes":{"role_id":"` + roleID + `","email":"user@example.com"}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("mismatched profile payload is rejected", func(t *testing.T) {
+		svc := &stubContactService{resolveRoleCode: "pilot"}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		roleID := mustUUIDStringContact(t, uuidv7.MustBytes())
+		body := []byte(`{"data":{"type":"contact_create","attributes":{"role_id":"` + roleID + `","email":"user@example.com","doctor":{"short_name":"Dr"}}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		svc := &stubContactService{resolveRoleCode: "pilot", createErr: errors.New("create failed")}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		roleID := mustUUIDStringContact(t, uuidv7.MustBytes())
+		body := []byte(`{"data":{"type":"contact_create","attributes":{"role_id":"` + roleID + `","email":"user@example.com","username":"john","pilot":{"pilot_category":"regular"}}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with invite and fetched item", func(t *testing.T) {
+		roleID := mustUUIDStringContact(t, uuidv7.MustBytes())
+		userID := uuidv7.MustBytes()
+		svc := &stubContactService{
+			resolveRoleCode: "pilot",
+			createUserID:    userID,
+			getItem: &contact.ContactListItem{
+				RoleCode:       "pilot",
+				RoleName:       "Pilot",
+				PilotCategory:  "regular",
+				Username:       " pilot.user ",
+				Email:          "pilot@example.com",
+				FirstName:      "John",
+				LastName:       "Doe",
+				IsActive:       true,
+				PilotShortName: strPtrContact("PJ"),
+			},
+		}
+		inviter := &stubContactInviter{}
+		app := newContactTestApp(NewContactHandler(svc, inviter))
+		body := []byte(`{"data":{"type":"contact_create","attributes":{"role_id":"` + roleID + `","email":"pilot@example.com","username":"pilot.user","first_name":" John ","last_name":" Doe ","mobile_phone":" 081 ","timezone":" Asia/Jakarta ","is_active":true,"pilot":{"pilot_category":"regular","short_name":" PJ ","license_no":" LIC-1 "}}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if svc.lastCreate.User.Email == nil || *svc.lastCreate.User.Email != "pilot@example.com" {
+			t.Fatalf("expected trimmed email, got %#v", svc.lastCreate.User.Email)
+		}
+		if svc.lastCreate.Profile.PilotCategory == nil || *svc.lastCreate.Profile.PilotCategory != "regular" {
+			t.Fatalf("expected pilot category patched")
+		}
+		if string(inviter.lastUserID) != string(userID) {
+			t.Fatalf("expected inviter called with created user id")
+		}
+	})
+
+	t.Run("success when invite fails and refetch nil", func(t *testing.T) {
+		roleID := mustUUIDStringContact(t, uuidv7.MustBytes())
+		userID := uuidv7.MustBytes()
+		svc := &stubContactService{resolveRoleCode: "staff", createUserID: userID}
+		inviter := &stubContactInviter{err: errors.New("ses down")}
+		app := newContactTestApp(NewContactHandler(svc, inviter))
+		body := []byte(`{"data":{"type":"contact_create","attributes":{"role_id":"` + roleID + `","email":"user@example.com","staff":{"short_name":"Dina"}}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("get after create error", func(t *testing.T) {
+		roleID := mustUUIDStringContact(t, uuidv7.MustBytes())
+		svc := &stubContactService{resolveRoleCode: "staff", createUserID: uuidv7.MustBytes(), getErr: errors.New("lookup failed")}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_create","attributes":{"role_id":"` + roleID + `","email":"user@example.com","staff":{"short_name":"Dina"}}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestContactHelperFunctions(t *testing.T) {
+	t.Run("contactBaseRoles and contactDULBases", func(t *testing.T) {
+		baseID := uuidv7.MustBytes()
+		baseHex := strings.ToLower(hex.EncodeToString(baseID))
+		nameHex := strings.ToLower(hex.EncodeToString([]byte("Halim Base")))
+		catHex := strings.ToLower(hex.EncodeToString([]byte("hems")))
+		raw := baseHex + "|" + nameHex + "|dul|" + catHex + "," + baseHex + "|" + nameHex + "|pilot|" + catHex
+		roles := contactBaseRoles(&raw)
+		if len(roles) != 2 {
+			t.Fatalf("expected 2 base roles, got %d", len(roles))
+		}
+		dulBases := contactDULBases(&raw)
+		if len(dulBases) != 1 {
+			t.Fatalf("expected only dul role base, got %d", len(dulBases))
+		}
+		if dulBases[0]["category"] != "hems" {
+			t.Fatalf("expected dul base category hems")
+		}
+		invalid := "invalid"
+		if got := contactBaseRoles(&invalid); got != nil {
+			t.Fatalf("invalid raw should return nil")
+		}
+		if got := contactDULBases(&invalid); got != nil {
+			t.Fatalf("invalid raw should return nil dul bases")
+		}
+	})
+
+	t.Run("contactRoles", func(t *testing.T) {
+		roleID := uuidv7.MustBytes()
+		roleRaw := strings.ToLower(hex.EncodeToString(roleID)) + "|" +
+			strings.ToLower(hex.EncodeToString([]byte("Pilot"))) + "|pilot"
+		out := contactRoles(&roleRaw)
+		if len(out) != 1 || out[0]["role_code"] != "pilot" {
+			t.Fatalf("expected pilot role parsed")
+		}
+		blank := " "
+		if got := contactRoles(&blank); len(got) != 0 {
+			t.Fatalf("blank raw should return empty slice")
+		}
+		bad := "abc"
+		if got := contactRoles(&bad); len(got) != 0 {
+			t.Fatalf("bad raw should return empty slice")
+		}
+	})
+
+	t.Run("applyContactFoto no attachment id", func(t *testing.T) {
+		h := NewContactHandler(&stubContactService{}, nil)
+		attrs := map[string]any{}
+		h.applyContactFoto(context.Background(), &contact.ContactListItem{}, attrs)
+		if _, ok := attrs["foto"]; ok {
+			t.Fatalf("foto should not be set without attachment id")
+		}
+	})
+
+	t.Run("resolveContactProfileAttachmentID and applyContactFoto success path", func(t *testing.T) {
+		raw := mustUUIDStringContact(t, uuidv7.MustBytes())
+		profileID := uuidv7.MustBytes()
+		thumb := "thumb-key"
+		h := NewContactHandler(&stubContactService{}, nil).
+			WithFileManagerService(&fileManagerAttachmentHandlerServiceMock{
+				createAttachmentFn: func(context.Context, filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+					return &filemanager.Attachment{ID: profileID}, nil
+				},
+				getAttachmentFn: func(context.Context, []byte) (*filemanager.Attachment, error) {
+					return &filemanager.Attachment{
+						ID: profileID,
+						File: &filemanager.File{
+							ObjectKey:          "photo-key",
+							SizeBytes:          100,
+							ThumbnailObjectKey: &thumb,
+							ThumbnailSizeBytes: 10,
+						},
+					}, nil
+				},
+			}).
+			WithFileStorage(&basePresignStorageMock{url: "https://example.com/signed"})
+
+		app := fiber.New()
+		app.Get("/x", func(c *fiber.Ctx) error {
+			c.Locals("user_id", uuidv7.MustBytes())
+			id, handled := h.resolveContactProfileAttachmentID(c, uuidv7.MustBytes(), &raw)
+			if handled || len(id) != 16 {
+				t.Fatalf("expected resolved attachment id")
+			}
+			return nil
+		})
+		resp, err := app.Test(httptest.NewRequest(http.MethodGet, "/x", nil))
+		if err != nil || resp.StatusCode != http.StatusOK {
+			t.Fatalf("unexpected resolveContactProfileAttachmentID result")
+		}
+
+		attrs := map[string]any{}
+		h.applyContactFoto(context.Background(), &contact.ContactListItem{ProfileAttachmentID: profileID}, attrs)
+		foto, ok := attrs["foto"].(map[string]any)
+		if !ok || strings.TrimSpace(foto["download_url"].(string)) == "" || strings.TrimSpace(foto["thumbnail_download_url"].(string)) == "" {
+			t.Fatalf("expected foto urls to be set")
+		}
+	})
+
+	t.Run("resolveContactProfileAttachmentID invalid uuid", func(t *testing.T) {
+		raw := "bad"
+		h := NewContactHandler(&stubContactService{}, nil).WithFileManagerService(&fileManagerAttachmentHandlerServiceMock{})
+		app := fiber.New()
+		app.Get("/x", func(c *fiber.Ctx) error {
+			_, handled := h.resolveContactProfileAttachmentID(c, uuidv7.MustBytes(), &raw)
+			if !handled {
+				t.Fatalf("expected handled invalid uuid")
+			}
+			return nil
+		})
+		resp, err := app.Test(httptest.NewRequest(http.MethodGet, "/x", nil))
+		if err != nil || resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for invalid uuid")
+		}
+	})
+
+	t.Run("ensureContactProfileAttachmentSet error when missing profile id", func(t *testing.T) {
+		svc := &stubContactService{getItem: &contact.ContactListItem{UserID: uuidv7.MustBytes()}}
+		h := NewContactHandler(svc, nil)
+		if err := h.ensureContactProfileAttachmentSet(context.Background(), uuidv7.MustBytes()); err == nil {
+			t.Fatalf("expected error when profile attachment id is missing")
+		}
+	})
+
+	t.Run("inferContactCreateRoleCodes", func(t *testing.T) {
+		codes := inferContactCreateRoleCodes(dto.ContactCreateAttributes{
+			Pilot: &dto.PilotProfileAttributes{},
+			Staff: &dto.StaffProfileAttributes{},
+		})
+		if len(codes) != 2 {
+			t.Fatalf("expected inferred role codes from payloads, got %d", len(codes))
+		}
+	})
+
+	t.Run("validatePilotDULBasePayload", func(t *testing.T) {
+		errs := validatePilotDULBasePayload(&dto.PilotProfileAttributes{
+			DULBaseIDs: []string{"bad-uuid"},
+		})
+		if len(errs) == 0 {
+			t.Fatalf("expected validation error for invalid dul_base_ids")
+		}
+
+		errs = validatePilotDULBasePayload(&dto.PilotProfileAttributes{
+			DULBase: []dto.DULBase{{ID: "bad-uuid"}},
+		})
+		if len(errs) == 0 {
+			t.Fatalf("expected validation error for invalid dul_base")
+		}
+
+		errs = validatePilotDULBasePayload(&dto.PilotProfileAttributes{
+			DULBaseIDs: []string{mustUUIDStringContact(t, uuidv7.MustBytes())},
+			DULBase:    []dto.DULBase{{ID: mustUUIDStringContact(t, uuidv7.MustBytes())}},
+		})
+		if len(errs) == 0 {
+			t.Fatalf("expected validation error when both dul_base_ids and dul_base are provided")
+		}
+	})
+}
+
+func TestContactHandlerList(t *testing.T) {
+	t.Run("success with normalized pagination", func(t *testing.T) {
+		userID := uuidv7.MustBytes()
+		svc := &stubContactService{
+			listItems: []contact.ContactListItem{{
+				UserID:    userID,
+				RoleCode:  "staff",
+				RoleName:  "Staff",
+				Email:     "staff@example.com",
+				FirstName: "Jane",
+				LastName:  "Doe",
+				IsActive:  true,
+			}},
+			listTotal: 1,
+		}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodGet, "/contacts?role=staff&pilot_category=regular&search=jane&sort=-sortkey&limit=500&offset=-4", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.lastFilter.Limit != 0 || svc.lastFilter.Offset != 0 {
+			t.Fatalf("expected normalized pagination, got %#v", svc.lastFilter)
+		}
+		if svc.lastFilter.Sort != "-sortkey" {
+			t.Fatalf("expected sort forwarded, got %#v", svc.lastFilter)
+		}
+	})
+
+	t.Run("supports role alias and special flag filters", func(t *testing.T) {
+		svc := &stubContactService{listTotal: 0}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		resp, _ := doJSONRequestContact(
+			t,
+			app,
+			http.MethodGet,
+			"/contacts?role=technicians&chief_doctor=true&chief_technician=1&responsible_complaint=yes&chief_pilot=true&ifr_qualified=true",
+			nil,
+		)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.lastFilter.Role != "technician" {
+			t.Fatalf("expected role alias normalized, got %q", svc.lastFilter.Role)
+		}
+		if svc.lastFilter.ChiefDoctor == nil || !*svc.lastFilter.ChiefDoctor {
+			t.Fatalf("expected chief_doctor=true")
+		}
+		if svc.lastFilter.ChiefTechnician == nil || !*svc.lastFilter.ChiefTechnician {
+			t.Fatalf("expected chief_technician=true")
+		}
+		if svc.lastFilter.ResponsibleComplaint == nil || !*svc.lastFilter.ResponsibleComplaint {
+			t.Fatalf("expected responsible_complaint=true")
+		}
+		if svc.lastFilter.ChiefPilot == nil || !*svc.lastFilter.ChiefPilot {
+			t.Fatalf("expected chief_pilot=true")
+		}
+		if svc.lastFilter.IFRQualified == nil || !*svc.lastFilter.IFRQualified {
+			t.Fatalf("expected ifr_qualified=true")
+		}
+	})
+
+	t.Run("list error", func(t *testing.T) {
+		svc := &stubContactService{listErr: errors.New("list failed")}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodGet, "/contacts", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestContactHandlerListDatatable(t *testing.T) {
+	t.Run("success with page size fallback", func(t *testing.T) {
+		svc := &stubContactService{listTotal: 2}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodGet, "/contacts/dt?page=0&size=0&draw=9&role=pilot&sort=note", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.lastFilter.Limit != 20 || svc.lastFilter.Offset != 0 || svc.lastFilter.Role != "pilot" {
+			t.Fatalf("unexpected filter %#v", svc.lastFilter)
+		}
+		if svc.lastFilter.Sort != "note" {
+			t.Fatalf("expected sort forwarded, got %#v", svc.lastFilter)
+		}
+	})
+
+	t.Run("supports special flag filters", func(t *testing.T) {
+		svc := &stubContactService{listTotal: 0}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		resp, _ := doJSONRequestContact(
+			t,
+			app,
+			http.MethodGet,
+			"/contacts/dt?chief_doctor=false&chief_technician=0&responsible_complaint=no&chief_pilot=false&ifr_qualified=false",
+			nil,
+		)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.lastFilter.ChiefDoctor == nil || *svc.lastFilter.ChiefDoctor {
+			t.Fatalf("expected chief_doctor=false")
+		}
+		if svc.lastFilter.ChiefTechnician == nil || *svc.lastFilter.ChiefTechnician {
+			t.Fatalf("expected chief_technician=false")
+		}
+		if svc.lastFilter.ResponsibleComplaint == nil || *svc.lastFilter.ResponsibleComplaint {
+			t.Fatalf("expected responsible_complaint=false")
+		}
+		if svc.lastFilter.ChiefPilot == nil || *svc.lastFilter.ChiefPilot {
+			t.Fatalf("expected chief_pilot=false")
+		}
+		if svc.lastFilter.IFRQualified == nil || *svc.lastFilter.IFRQualified {
+			t.Fatalf("expected ifr_qualified=false")
+		}
+	})
+
+	t.Run("list error", func(t *testing.T) {
+		svc := &stubContactService{listErr: errors.New("datatable failed")}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodGet, "/contacts/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestContactHandlerGetAndWriteByID(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodGet, "/contacts/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service error", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		svc := &stubContactService{getErr: errors.New("get failed")}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodGet, "/contacts/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodGet, "/contacts/"+id, nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		svc := &stubContactService{getItem: &contact.ContactListItem{
+			RoleCode:  "doctor",
+			RoleName:  "Doctor",
+			Email:     "doctor@example.com",
+			FirstName: "Doc",
+			LastName:  "Tor",
+			IsActive:  true,
+		}}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodGet, "/contacts/"+id, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestContactHandlerUpdate(t *testing.T) {
+	userID := uuidv7.MustBytes()
+	id := mustUUIDStringContact(t, userID)
+
+	t.Run("invalid uuid", func(t *testing.T) {
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		svc := &stubContactService{}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"first_name":"Jane"}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("type must be general contact_update", func(t *testing.T) {
+		svc := &stubContactService{getItem: &contact.ContactListItem{RoleCode: "staff", RoleName: "Staff"}}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_staff_update","attributes":{"first_name":"Jane"}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("mismatched profile payload is rejected", func(t *testing.T) {
+		svc := &stubContactService{getItem: &contact.ContactListItem{RoleCode: "staff", RoleName: "Staff"}}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"pilot":{"short_name":"PJ"}}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with multiple role specific payloads for assigned roles", func(t *testing.T) {
+		rolePilotID := uuidv7.MustBytes()
+		roleAirRescuerID := uuidv7.MustBytes()
+		rolesRaw := mustRoleRawContact(t, rolePilotID, "Pilot", "pilot") + "," +
+			mustRoleRawContact(t, roleAirRescuerID, "Air Rescuer", "air_rescuer")
+		svc := &stubContactService{
+			getItem: &contact.ContactListItem{
+				RoleCode: "pilot",
+				RoleName: "Pilot",
+				RolesRaw: &rolesRaw,
+			},
+			resolveRoleCodeByID: map[string]string{
+				string(rolePilotID):      "pilot",
+				string(roleAirRescuerID): "air_rescuer",
+			},
+		}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"role_id":"` +
+			mustUUIDStringContact(t, rolePilotID) + `","role_ids":["` + mustUUIDStringContact(t, rolePilotID) + `","` +
+			mustUUIDStringContact(t, roleAirRescuerID) + `"],"pilot":{"short_name":"P"},"air_rescuer":{"short_name":"AR"}}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if len(svc.lastUpdate.Profiles) != 2 {
+			t.Fatalf("expected 2 profile patches, got %d", len(svc.lastUpdate.Profiles))
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		svc := &stubContactService{getItem: &contact.ContactListItem{
+			RoleCode:  "staff",
+			RoleName:  "Staff",
+			Email:     "updated@example.com",
+			FirstName: "Jane",
+			LastName:  "Doe",
+		}}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"first_name":"Jane","staff":{"short_name":"PJ"}}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.lastUpdate.Profile.ShortName == nil || *svc.lastUpdate.Profile.ShortName != "PJ" {
+			t.Fatalf("expected profile patch on update")
+		}
+	})
+
+	t.Run("empty strings in update payload clear role profile fields", func(t *testing.T) {
+		svc := &stubContactService{getItem: &contact.ContactListItem{
+			RoleCode: "air_rescuer",
+			RoleName: "Air Rescuer",
+		}}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"air_rescuer":{"short_name":"","location":" ","note":"","postcode":"","street_line":""}}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.lastUpdate.Profile.ShortName == nil || *svc.lastUpdate.Profile.ShortName != "" {
+			t.Fatalf("expected short_name to be explicitly cleared, got %#v", svc.lastUpdate.Profile.ShortName)
+		}
+		if svc.lastUpdate.Profile.Location == nil || *svc.lastUpdate.Profile.Location != "" {
+			t.Fatalf("expected location to be explicitly cleared, got %#v", svc.lastUpdate.Profile.Location)
+		}
+		if svc.lastUpdate.Profile.Note == nil || *svc.lastUpdate.Profile.Note != "" {
+			t.Fatalf("expected note to be explicitly cleared, got %#v", svc.lastUpdate.Profile.Note)
+		}
+		if svc.lastUpdate.Profile.Postcode == nil || *svc.lastUpdate.Profile.Postcode != "" {
+			t.Fatalf("expected postcode to be explicitly cleared, got %#v", svc.lastUpdate.Profile.Postcode)
+		}
+		if svc.lastUpdate.Profile.StreetLine == nil || *svc.lastUpdate.Profile.StreetLine != "" {
+			t.Fatalf("expected street_line to be explicitly cleared, got %#v", svc.lastUpdate.Profile.StreetLine)
+		}
+	})
+
+	t.Run("success update role_ids and profile for assigned role", func(t *testing.T) {
+		roleStaffID := uuidv7.MustBytes()
+		roleAirRescuerID := uuidv7.MustBytes()
+		rolesRaw := mustRoleRawContact(t, roleStaffID, "Staff", "staff") + "," +
+			mustRoleRawContact(t, roleAirRescuerID, "Air Rescuer", "air_rescuer")
+		svc := &stubContactService{
+			getItem: &contact.ContactListItem{
+				RoleCode:  "staff",
+				RoleName:  "Staff",
+				Email:     "updated@example.com",
+				FirstName: "Jane",
+				LastName:  "Doe",
+				RolesRaw:  &rolesRaw,
+			},
+			resolveRoleCodeByID: map[string]string{
+				string(roleStaffID):      "staff",
+				string(roleAirRescuerID): "air_rescuer",
+			},
+		}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"role_id":"` +
+			mustUUIDStringContact(t, roleAirRescuerID) +
+			`","role_ids":["` + mustUUIDStringContact(t, roleAirRescuerID) + `","` + mustUUIDStringContact(t, roleStaffID) +
+			`"],"air_rescuer":{"short_name":"AR"},"staff":{"short_name":"S"}}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if !svc.lastUpdate.UpdateRoles {
+			t.Fatalf("expected role updates enabled")
+		}
+		if len(svc.lastUpdate.RoleID) != 16 || string(svc.lastUpdate.RoleID) != string(roleAirRescuerID) {
+			t.Fatalf("expected primary role updated to air_rescuer")
+		}
+		if len(svc.lastUpdate.RoleIDs) != 2 {
+			t.Fatalf("expected 2 role ids, got %d", len(svc.lastUpdate.RoleIDs))
+		}
+		if len(svc.lastUpdate.Profiles) != 2 {
+			t.Fatalf("expected two role profile patches")
+		}
+		foundAirRescuer := false
+		foundStaff := false
+		for i := range svc.lastUpdate.Profiles {
+			switch svc.lastUpdate.Profiles[i].RoleCode {
+			case "air_rescuer":
+				foundAirRescuer = svc.lastUpdate.Profiles[i].Patch.ShortName != nil && *svc.lastUpdate.Profiles[i].Patch.ShortName == "AR"
+			case "staff":
+				foundStaff = svc.lastUpdate.Profiles[i].Patch.ShortName != nil && *svc.lastUpdate.Profiles[i].Patch.ShortName == "S"
+			}
+		}
+		if !foundAirRescuer || !foundStaff {
+			t.Fatalf("expected air_rescuer and staff patches")
+		}
+	})
+
+	t.Run("success update role_ids only promotes first role_id as primary", func(t *testing.T) {
+		rolePilotID := uuidv7.MustBytes()
+		roleAirRescuerID := uuidv7.MustBytes()
+		rolesRaw := mustRoleRawContact(t, rolePilotID, "Pilot", "pilot") + "," +
+			mustRoleRawContact(t, roleAirRescuerID, "Air Rescuer", "air_rescuer")
+		svc := &stubContactService{
+			getItem: &contact.ContactListItem{
+				RoleCode:  "pilot",
+				RoleName:  "Pilot",
+				Email:     "updated@example.com",
+				FirstName: "Jane",
+				LastName:  "Doe",
+				RolesRaw:  &rolesRaw,
+			},
+			resolveRoleCodeByID: map[string]string{
+				string(rolePilotID):      "pilot",
+				string(roleAirRescuerID): "air_rescuer",
+			},
+		}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"role_ids":["` +
+			mustUUIDStringContact(t, roleAirRescuerID) + `","` + mustUUIDStringContact(t, rolePilotID) +
+			`"],"air_rescuer":{"short_name":"AR"},"pilot":{"short_name":"P"}}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if !svc.lastUpdate.UpdateRoles {
+			t.Fatalf("expected role updates enabled")
+		}
+		if len(svc.lastUpdate.RoleID) != 16 || string(svc.lastUpdate.RoleID) != string(roleAirRescuerID) {
+			t.Fatalf("expected primary role updated to first role_ids item (air_rescuer)")
+		}
+		if len(svc.lastUpdate.RoleIDs) != 2 {
+			t.Fatalf("expected 2 role ids, got %d", len(svc.lastUpdate.RoleIDs))
+		}
+	})
+
+	t.Run("role_ids update requires matching profile payloads", func(t *testing.T) {
+		roleStaffID := uuidv7.MustBytes()
+		roleAirRescuerID := uuidv7.MustBytes()
+		rolesRaw := mustRoleRawContact(t, roleStaffID, "Staff", "staff") + "," +
+			mustRoleRawContact(t, roleAirRescuerID, "Air Rescuer", "air_rescuer")
+		svc := &stubContactService{
+			getItem: &contact.ContactListItem{
+				RoleCode: "staff",
+				RoleName: "Staff",
+				RolesRaw: &rolesRaw,
+			},
+			resolveRoleCodeByID: map[string]string{
+				string(roleStaffID):      "staff",
+				string(roleAirRescuerID): "air_rescuer",
+			},
+		}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"role_ids":["` +
+			mustUUIDStringContact(t, roleAirRescuerID) + `","` + mustUUIDStringContact(t, roleStaffID) +
+			`"],"air_rescuer":{"short_name":"AR"}}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid role_id format", func(t *testing.T) {
+		svc := &stubContactService{
+			getItem: &contact.ContactListItem{RoleCode: "staff", RoleName: "Staff"},
+		}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"role_id":"bad"}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid role_ids format", func(t *testing.T) {
+		svc := &stubContactService{
+			getItem: &contact.ContactListItem{RoleCode: "staff", RoleName: "Staff"},
+		}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"role_ids":["bad"]}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success clear all roles with empty role_ids", func(t *testing.T) {
+		roleStaffID := uuidv7.MustBytes()
+		rolesRaw := mustRoleRawContact(t, roleStaffID, "Staff", "staff")
+		svc := &stubContactService{
+			getItem: &contact.ContactListItem{
+				RoleCode: "staff",
+				RoleName: "Staff",
+				RolesRaw: &rolesRaw,
+			},
+		}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"role_ids":[]}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if !svc.lastUpdate.UpdateRoles {
+			t.Fatalf("expected role updates enabled")
+		}
+		if len(svc.lastUpdate.RoleID) != 0 {
+			t.Fatalf("expected empty primary role id")
+		}
+		if len(svc.lastUpdate.RoleIDs) != 0 {
+			t.Fatalf("expected empty role ids")
+		}
+	})
+
+	t.Run("success clear all roles with empty role_id string", func(t *testing.T) {
+		roleStaffID := uuidv7.MustBytes()
+		rolesRaw := mustRoleRawContact(t, roleStaffID, "Staff", "staff")
+		svc := &stubContactService{
+			getItem: &contact.ContactListItem{
+				RoleCode: "staff",
+				RoleName: "Staff",
+				RolesRaw: &rolesRaw,
+			},
+		}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"role_id":"","role_ids":[]}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if !svc.lastUpdate.UpdateRoles {
+			t.Fatalf("expected role updates enabled")
+		}
+		if len(svc.lastUpdate.RoleID) != 0 {
+			t.Fatalf("expected empty primary role id")
+		}
+		if len(svc.lastUpdate.RoleIDs) != 0 {
+			t.Fatalf("expected empty role ids")
+		}
+	})
+
+	t.Run("success clear all roles with only empty role_id string", func(t *testing.T) {
+		roleStaffID := uuidv7.MustBytes()
+		rolesRaw := mustRoleRawContact(t, roleStaffID, "Staff", "staff")
+		svc := &stubContactService{
+			getItem: &contact.ContactListItem{
+				RoleCode: "staff",
+				RoleName: "Staff",
+				RolesRaw: &rolesRaw,
+			},
+		}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"role_id":""}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if !svc.lastUpdate.UpdateRoles || len(svc.lastUpdate.RoleID) != 0 || len(svc.lastUpdate.RoleIDs) != 0 {
+			t.Fatalf("expected clear roles request")
+		}
+	})
+
+	t.Run("success clear all roles with role_id null string", func(t *testing.T) {
+		roleStaffID := uuidv7.MustBytes()
+		rolesRaw := mustRoleRawContact(t, roleStaffID, "Staff", "staff")
+		svc := &stubContactService{
+			getItem: &contact.ContactListItem{
+				RoleCode: "staff",
+				RoleName: "Staff",
+				RolesRaw: &rolesRaw,
+			},
+		}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_update","attributes":{"role_id":"null"}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if !svc.lastUpdate.UpdateRoles || len(svc.lastUpdate.RoleID) != 0 || len(svc.lastUpdate.RoleIDs) != 0 {
+			t.Fatalf("expected clear roles request")
+		}
+	})
+}
+
+func TestContactHandlerDelete(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodDelete, "/contacts/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		svc := &stubContactService{deleteErr: gorm.ErrRecordNotFound}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodDelete, "/contacts/"+id, nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodDelete, "/contacts/"+id, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestContactHandlerSimpleMutations(t *testing.T) {
+	userID := mustUUIDStringContact(t, uuidv7.MustBytes())
+	getItem := &contact.ContactListItem{
+		RoleCode:  "technician",
+		RoleName:  "Technician",
+		Email:     "tech@example.com",
+		FirstName: "Tech",
+		LastName:  "Nician",
+		IsActive:  true,
+	}
+
+	tests := []struct {
+		name   string
+		method string
+		path   string
+		body   []byte
+		assert func(t *testing.T, svc *stubContactService)
+	}{
+		{
+			name:   "status success",
+			method: http.MethodPatch,
+			path:   "/contacts/" + userID + "/status",
+			body:   []byte(`{"data":{"type":"contact_status_update","attributes":{"is_active":true}}}`),
+			assert: func(t *testing.T, svc *stubContactService) {
+				if !svc.lastIsActive {
+					t.Fatalf("expected active flag true")
+				}
+			},
+		},
+		{
+			name:   "role success",
+			method: http.MethodPatch,
+			path:   "/contacts/" + userID + "/role",
+			body:   []byte(`{"data":{"type":"contact_role_update","attributes":{"role_code":"pilot"}}}`),
+			assert: func(t *testing.T, svc *stubContactService) {
+				if svc.lastRoleCode != "pilot" {
+					t.Fatalf("expected role code recorded")
+				}
+			},
+		},
+		{
+			name:   "pilot category success",
+			method: http.MethodPatch,
+			path:   "/contacts/" + userID + "/pilot-category",
+			body:   []byte(`{"data":{"type":"contact_pilot_category_update","attributes":{"pilot_category":"freelance"}}}`),
+			assert: func(t *testing.T, svc *stubContactService) {
+				if svc.lastPilotCategory != "freelance" {
+					t.Fatalf("expected pilot category recorded")
+				}
+			},
+		},
+		{
+			name:   "license success",
+			method: http.MethodPatch,
+			path:   "/contacts/" + userID + "/license",
+			body:   []byte(`{"data":{"type":"contact_license_update","attributes":{"license_no":"LIC"}}}`),
+			assert: func(t *testing.T, svc *stubContactService) {
+				if svc.lastLicenseNo == nil || *svc.lastLicenseNo != "LIC" {
+					t.Fatalf("expected license fields recorded")
+				}
+			},
+		},
+		{
+			name:   "chief flags success",
+			method: http.MethodPatch,
+			path:   "/contacts/" + userID + "/chief-flags",
+			body:   []byte(`{"data":{"type":"contact_chief_flags_update","attributes":{"is_chief_pilot":true,"is_chief_technician":false}}}`),
+			assert: func(t *testing.T, svc *stubContactService) {
+				if svc.lastChiefFlags.IsChiefPilot == nil || !*svc.lastChiefFlags.IsChiefPilot {
+					t.Fatalf("expected chief pilot flag recorded")
+				}
+			},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			svc := &stubContactService{getItem: getItem}
+			app := newContactTestApp(NewContactHandler(svc, nil))
+			resp, _ := doJSONRequestContact(t, app, tc.method, tc.path, tc.body)
+			if resp.StatusCode != http.StatusOK {
+				t.Fatalf("expected 200, got %d", resp.StatusCode)
+			}
+			tc.assert(t, svc)
+		})
+	}
+}
+
+func TestContactHandlerSimpleMutationsErrors(t *testing.T) {
+	t.Run("status invalid uuid", func(t *testing.T) {
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/not-uuid/status", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("status service error", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		svc := &stubContactService{updateStatusErr: errors.New("status failed")}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_status_update","attributes":{"is_active":false}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id+"/status", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("role invalid json", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id+"/role", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("role validation error", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		body := []byte(`{"data":{"type":"contact_role_update","attributes":{"role_code":"wrong"}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id+"/role", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("role service error", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		svc := &stubContactService{updateRoleErr: errors.New("role failed")}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_role_update","attributes":{"role_code":"pilot"}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id+"/role", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("pilot category invalid json", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id+"/pilot-category", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("pilot category validation error", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		body := []byte(`{"data":{"type":"contact_pilot_category_update","attributes":{"pilot_category":"wrong"}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id+"/pilot-category", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("pilot category service error", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		svc := &stubContactService{updatePilotCategoryErr: errors.New("pilot category failed")}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_pilot_category_update","attributes":{"pilot_category":"regular"}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id+"/pilot-category", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("license invalid json", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id+"/license", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("license service error", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		svc := &stubContactService{updateLicenseErr: errors.New("license failed")}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_license_update","attributes":{"license_no":"LIC"}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id+"/license", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("chief flags invalid json", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id+"/chief-flags", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("chief flags service error", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		svc := &stubContactService{updateChiefFlagsErr: errors.New("chief failed")}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_chief_flags_update","attributes":{"is_chief_physician":true}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPatch, "/contacts/"+id+"/chief-flags", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+}
+
+func TestContactHandlerBulkUpdate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/bulk-update", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/bulk-update", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid uuid", func(t *testing.T) {
+		app := newContactTestApp(NewContactHandler(&stubContactService{}, nil))
+		body := []byte(`{"data":{"type":"contact_bulk_update","attributes":{"user_ids":["bad"],"is_active":true}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/bulk-update", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service error", func(t *testing.T) {
+		id := mustUUIDStringContact(t, uuidv7.MustBytes())
+		svc := &stubContactService{bulkUpdateErr: errors.New("bulk failed")}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_bulk_update","attributes":{"user_ids":["` + id + `"],"is_active":false}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/bulk-update", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		id1 := mustUUIDStringContact(t, uuidv7.MustBytes())
+		id2 := mustUUIDStringContact(t, uuidv7.MustBytes())
+		svc := &stubContactService{bulkUpdateCount: 2}
+		app := newContactTestApp(NewContactHandler(svc, nil))
+		body := []byte(`{"data":{"type":"contact_bulk_update","attributes":{"user_ids":["` + id1 + `","` + id2 + `"],"is_active":true}}}`)
+		resp, _ := doJSONRequestContact(t, app, http.MethodPost, "/contacts/bulk-update", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if len(svc.lastBulkIDs) != 2 || !svc.lastBulkIsActive {
+			t.Fatalf("expected bulk update recorded")
+		}
+	})
+}
+
+func TestContactHandlerProfilePatchHelpers(t *testing.T) {
+	now := time.Now().UTC()
+	later := now.Add(24 * time.Hour)
+
+	createPatch := profilePatchFromCreate("pilot", dto.ContactCreateAttributes{
+		Pilot: &dto.PilotProfileAttributes{
+			PilotCategory:           "regular",
+			ShortName:               "P",
+			LicenseNo:               "L",
+			LicenseIssuedAt:         &now,
+			LicenseExpiredAt:        &later,
+			TechnicianLicenseNo:     "T",
+			HasIFRQualification:     boolPtrContact(true),
+			IsChiefPilot:            boolPtrContact(true),
+			DULBaseIDs:              []string{},
+			TotalFlightMinutes:      intPtrContact(1),
+			ResponsiblePilotMinutes: intPtrContact(2),
+			SecondPilotMinutes:      intPtrContact(3),
+			DoubleCommandMinutes:    intPtrContact(4),
+			FlightInstructorMinutes: intPtrContact(5),
+			NightFlightMinutes:      intPtrContact(6),
+			IFRFlightMinutes:        intPtrContact(7),
+			Location:                "Loc",
+			Postcode:                "123",
+			StreetLine:              "Street",
+			WeightKG:                floatPtrContact(70.5),
+		},
+		Doctor: &dto.DoctorProfileAttributes{
+			ShortName:         "D",
+			Specialization:    "Spec",
+			SubSpecialization: "Sub",
+			IsChiefPhysician:  boolPtrContact(true),
+			Location:          "DocLoc",
+			Postcode:          "456",
+			StreetLine:        "DocStreet",
+		},
+		AirRescuer: &dto.AirRescuerProfileAttributes{
+			ShortName:                "A",
+			ResponsibleFlightRescuer: boolPtrContact(true),
+			Location:                 "AirLoc",
+			Postcode:                 "789",
+			StreetLine:               "AirStreet",
+		},
+		Technician: &dto.TechnicianProfileAttributes{
+			ShortName:               "T",
+			LicenseNo:               "TEC",
+			IsChiefTechnician:       boolPtrContact(true),
+			IsResponsibleComplaints: boolPtrContact(true),
+			Location:                "TechLoc",
+			Postcode:                "101",
+			StreetLine:              "TechStreet",
+		},
+		FlightAssistant: &dto.FlightAssistantProfileAttributes{
+			ShortName:  "F",
+			Location:   "FlightLoc",
+			Postcode:   "202",
+			StreetLine: "FlightStreet",
+		},
+		Staff: &dto.StaffProfileAttributes{
+			ShortName:  "S",
+			RoleLabel:  "Admin",
+			Location:   "StaffLoc",
+			Postcode:   "303",
+			StreetLine: "StaffStreet",
+		},
+	})
+	if createPatch.WeightKG == nil || *createPatch.WeightKG != 70.5 {
+		t.Fatalf("expected pilot weight copied")
+	}
+	if createPatch.ResponsibleFlightRescuer != nil {
+		t.Fatalf("expected pilot responsible flight rescuer ignored on create")
+	}
+	if createPatch.RoleLabel != nil {
+		t.Fatalf("expected non-pilot fields to be ignored on create")
+	}
+
+	airRescuerPatch := profilePatchFromCreate("air_rescuer", dto.ContactCreateAttributes{
+		AirRescuer: &dto.AirRescuerProfileAttributes{
+			ShortName:                "Air",
+			ResponsibleFlightRescuer: boolPtrContact(true),
+		},
+	})
+	if airRescuerPatch.ResponsibleFlightRescuer == nil || !*airRescuerPatch.ResponsibleFlightRescuer {
+		t.Fatalf("expected air rescuer responsible flight rescuer copied on create")
+	}
+
+	updatePatch := profilePatchFromUpdate("staff", dto.ContactUpdateAttributes{
+		Pilot: &dto.PilotProfileUpdateAttributes{
+			PilotCategory: strPtrContact("dry_lease"),
+			ShortName:     strPtrContact("Pilot"),
+		},
+		Doctor: &dto.DoctorProfileUpdateAttributes{},
+		AirRescuer: &dto.AirRescuerProfileUpdateAttributes{
+			ResponsibleFlightRescuer: boolPtrContact(true),
+		},
+		Technician: &dto.TechnicianProfileUpdateAttributes{
+			IsResponsibleComplaints: boolPtrContact(true),
+		},
+		FlightAssistant: &dto.FlightAssistantProfileUpdateAttributes{ShortName: strPtrContact("FA")},
+		Staff: &dto.StaffProfileUpdateAttributes{
+			ShortName: strPtrContact("Staff"),
+			RoleLabel: strPtrContact("Coordinator"),
+		},
+	})
+	if updatePatch.ShortName == nil || *updatePatch.ShortName != "Staff" {
+		t.Fatalf("expected update profile patch")
+	}
+	if updatePatch.RoleLabel == nil || *updatePatch.RoleLabel != "Coordinator" {
+		t.Fatalf("expected staff fields copied on update")
+	}
+	if updatePatch.PilotCategory != nil || updatePatch.ResponsibleFlightRescuer != nil || updatePatch.IsResponsibleComplaints != nil {
+		t.Fatalf("expected non-staff fields to be ignored on update")
+	}
+
+	pilotPatch := contact.ProfilePatch{}
+	dulBaseID := mustUUIDStringContact(t, uuidv7.MustBytes())
+	fillPatchFromPilot(&pilotPatch, &dto.PilotProfileAttributes{
+		DULBase: []dto.DULBase{{ID: dulBaseID, Name: "Base A", Category: "hems"}},
+	})
+	if !pilotPatch.DULBaseIDsSet || len(pilotPatch.DULBaseIDs) != 1 {
+		t.Fatalf("expected dul_base object payload mapped to DUL base ids")
+	}
+
+	fillPatchFromPilot(nil, nil)
+	fillPatchFromDoctor(nil, nil)
+	fillPatchFromAirRescuer(nil, nil)
+	fillPatchFromTechnician(nil, nil)
+	fillPatchFromFlightAssistant(nil, nil)
+	fillPatchFromStaff(nil, nil)
+}
+
+func TestContactHandlerHelpers(t *testing.T) {
+	if optionalStr("   ") != nil {
+		t.Fatalf("expected nil optional string")
+	}
+	if got := optionalStr("  abc "); got == nil || *got != "abc" {
+		t.Fatalf("expected trimmed optional string")
+	}
+	if got := strPtr("x"); got == nil || *got != "x" {
+		t.Fatalf("expected string pointer")
+	}
+	if got := contactUUIDString([]byte("bad")); got != "" {
+		t.Fatalf("expected empty uuid string on invalid bytes")
+	}
+	if attrs := contactAttributes(nil, false); len(attrs) != 0 {
+		t.Fatalf("expected empty attrs for nil item")
+	}
+	if roles := contactRoles(nil); roles == nil || len(roles) != 0 {
+		t.Fatalf("expected empty roles for nil raw")
+	}
+	roleID := uuidv7.MustBytes()
+	roleIDHex := strings.ToLower(hex.EncodeToString(roleID))
+	roleNameHex := strings.ToLower(hex.EncodeToString([]byte("Pilot")))
+	raw := roleIDHex + "|" + roleNameHex + "|pilot"
+	roles := contactRoles(&raw)
+	if len(roles) != 1 {
+		t.Fatalf("expected one role, got %d", len(roles))
+	}
+	if roles[0]["role_code"] != "pilot" || roles[0]["role_name"] != "Pilot" {
+		t.Fatalf("unexpected role payload: %#v", roles[0])
+	}
+	if intStatus(http.StatusBadRequest) != "400" || intStatus(http.StatusNotFound) != "404" {
+		t.Fatalf("unexpected int status mapping")
+	}
+}
+
+func TestContactAttributesByRole(t *testing.T) {
+	now := time.Now().UTC()
+	creator := uuidv7.MustBytes()
+	str := "value"
+	yes := true
+	n := 10
+	kg := 80.5
+
+	cases := []contact.ContactListItem{
+		{
+			CreatedBy:                    creator,
+			RoleCode:                     "pilot",
+			RoleName:                     "Pilot",
+			Email:                        "p@example.com",
+			FirstName:                    "P",
+			LastName:                     "One",
+			PilotCategory:                "regular",
+			PilotShortName:               &str,
+			PilotLicenseNo:               &str,
+			PilotLicenseIssuedAt:         &now,
+			PilotLicenseExpiredAt:        &now,
+			PilotTechnicianLicenseNo:     &str,
+			PilotHasIFRQualification:     &yes,
+			PilotIsChiefPilot:            &yes,
+			PilotIsDUL:                   &yes,
+			PilotTotalFlightMinutes:      &n,
+			PilotResponsiblePilotMinutes: &n,
+			PilotSecondPilotMinutes:      &n,
+			PilotDoubleCommandMinutes:    &n,
+			PilotFlightInstructorMinutes: &n,
+			PilotNightFlightMinutes:      &n,
+			PilotIFRFlightMinutes:        &n,
+			PilotLocation:                &str,
+			PilotPostcode:                &str,
+			PilotStreetLine:              &str,
+			PilotWeightKG:                &kg,
+			PilotPhotoFileID:             &str,
+		},
+		{
+			CreatedBy:               creator,
+			RoleCode:                "doctor",
+			RoleName:                "Doctor",
+			Email:                   "d@example.com",
+			FirstName:               "D",
+			LastName:                "One",
+			DoctorShortName:         &str,
+			DoctorSpecialization:    &str,
+			DoctorSubSpecialization: &str,
+			DoctorIsChiefPhysician:  &yes,
+			DoctorLocation:          &str,
+			DoctorPostcode:          &str,
+			DoctorStreetLine:        &str,
+			DoctorPhotoFileID:       &str,
+		},
+		{
+			CreatedBy:                          creator,
+			RoleCode:                           "air_rescuer",
+			RoleName:                           "Air Rescuer",
+			Email:                              "a@example.com",
+			FirstName:                          "A",
+			LastName:                           "One",
+			AirRescuerShortName:                &str,
+			AirRescuerResponsibleFlightRescuer: &yes,
+			AirRescuerLocation:                 &str,
+			AirRescuerPostcode:                 &str,
+			AirRescuerStreetLine:               &str,
+			AirRescuerPhotoFileID:              &str,
+		},
+		{
+			CreatedBy:                         creator,
+			RoleCode:                          "technician",
+			RoleName:                          "Technician",
+			Email:                             "t@example.com",
+			FirstName:                         "T",
+			LastName:                          "One",
+			TechnicianShortName:               &str,
+			TechnicianLicenseNo:               &str,
+			TechnicianIsChiefTechnician:       &yes,
+			TechnicianIsResponsibleComplaints: &yes,
+			TechnicianLocation:                &str,
+			TechnicianPostcode:                &str,
+			TechnicianStreetLine:              &str,
+			TechnicianPhotoFileID:             &str,
+		},
+		{
+			CreatedBy:                  creator,
+			RoleCode:                   "flight_assistant",
+			RoleName:                   "Flight Assistant",
+			Email:                      "f@example.com",
+			FirstName:                  "F",
+			LastName:                   "One",
+			FlightAssistantShortName:   &str,
+			FlightAssistantLocation:    &str,
+			FlightAssistantPostcode:    &str,
+			FlightAssistantStreetLine:  &str,
+			FlightAssistantPhotoFileID: &str,
+		},
+		{
+			CreatedBy:        creator,
+			RoleCode:         "staff",
+			RoleName:         "Staff",
+			Email:            "s@example.com",
+			FirstName:        "S",
+			LastName:         "One",
+			StaffShortName:   &str,
+			StaffRoleLabel:   &str,
+			StaffLocation:    &str,
+			StaffPostcode:    &str,
+			StaffStreetLine:  &str,
+			StaffPhotoFileID: &str,
+		},
+	}
+
+	for _, item := range cases {
+		attrs := contactAttributes(&item, false)
+		if len(attrs) == 0 {
+			t.Fatalf("expected attrs for role %s", item.RoleCode)
+		}
+		if attrs["email"] == nil {
+			t.Fatalf("expected base attrs for role %s", item.RoleCode)
+		}
+		if _, ok := attrs["set_password"].(bool); !ok {
+			t.Fatalf("expected set_password bool for role %s", item.RoleCode)
+		}
+		if attrs["created_by"] == "" {
+			t.Fatalf("expected created_by for role %s", item.RoleCode)
+		}
+		if _, ok := attrs["updated_by"].(string); !ok {
+			t.Fatalf("expected updated_by string for role %s", item.RoleCode)
+		}
+		if _, ok := attrs["created_at"].(string); !ok {
+			t.Fatalf("expected created_at string for role %s", item.RoleCode)
+		}
+		if _, ok := attrs["updated_at"].(string); !ok {
+			t.Fatalf("expected updated_at string for role %s", item.RoleCode)
+		}
+		if item.RoleCode == "pilot" {
+			if profile, ok := attrs["pilot"].(map[string]any); ok && profile["responsible_flight_rescuer"] != nil {
+				t.Fatalf("expected pilot responsible_flight_rescuer removed from response")
+			}
+			if _, ok := attrs["license_no"]; ok {
+				t.Fatalf("expected top-level license_no removed for pilot")
+			}
+			if _, ok := attrs["pilot_category"]; ok {
+				t.Fatalf("expected top-level pilot_category removed for pilot")
+			}
+		}
+		if item.RoleCode == "doctor" {
+			if _, ok := attrs["medical_license"]; ok {
+				t.Fatalf("expected top-level medical_license removed for doctor")
+			}
+			if _, ok := attrs["license_no"]; ok {
+				t.Fatalf("expected top-level license_no removed for doctor")
+			}
+			if _, ok := attrs["pilot_category"]; ok {
+				t.Fatalf("expected top-level pilot_category removed for doctor")
+			}
+		}
+		if item.RoleCode == "air_rescuer" {
+			profile, ok := attrs["air_rescuer"].(map[string]any)
+			if !ok || profile["responsible_flight_rescuer"] == nil {
+				t.Fatalf("expected air rescuer responsible_flight_rescuer in response")
+			}
+			if _, ok := attrs["license_no"]; ok {
+				t.Fatalf("expected top-level license_no removed for air_rescuer")
+			}
+			if _, ok := attrs["medical_license"]; ok {
+				t.Fatalf("expected top-level medical_license removed for air_rescuer")
+			}
+			if _, ok := attrs["pilot_category"]; ok {
+				t.Fatalf("expected top-level pilot_category removed for air_rescuer")
+			}
+		}
+		if item.RoleCode == "flight_assistant" {
+			if _, ok := attrs["license_no"]; ok {
+				t.Fatalf("expected top-level license_no removed for flight_assistant")
+			}
+			if _, ok := attrs["medical_license"]; ok {
+				t.Fatalf("expected top-level medical_license removed for flight_assistant")
+			}
+			if _, ok := attrs["pilot_category"]; ok {
+				t.Fatalf("expected top-level pilot_category removed for flight_assistant")
+			}
+		}
+		if item.RoleCode == "technician" {
+			if _, ok := attrs["medical_license"]; ok {
+				t.Fatalf("expected top-level medical_license removed for technician")
+			}
+			if _, ok := attrs["pilot_category"]; ok {
+				t.Fatalf("expected top-level pilot_category removed for technician")
+			}
+		}
+		if item.RoleCode == "staff" {
+			if _, ok := attrs["license_no"]; ok {
+				t.Fatalf("expected top-level license_no removed for staff")
+			}
+			if _, ok := attrs["medical_license"]; ok {
+				t.Fatalf("expected top-level medical_license removed for staff")
+			}
+			if _, ok := attrs["pilot_category"]; ok {
+				t.Fatalf("expected top-level pilot_category removed for staff")
+			}
+		}
+	}
+
+	baseOnly := contactAttributes(&contact.ContactListItem{
+		RoleCode:  "pilot",
+		RoleName:  "Pilot",
+		Email:     "base@example.com",
+		FirstName: "Base",
+		LastName:  "Only",
+		SortKey:   intPtrContactHandler(2),
+		Note:      "base-note",
+	}, false)
+	if baseOnly["sortkey"] == nil || baseOnly["note"] != "base-note" {
+		t.Fatalf("expected sortkey and note in base attrs")
+	}
+	if baseOnly["set_password"] != true {
+		t.Fatalf("expected set_password=true when password is empty")
+	}
+	if _, ok := baseOnly["pilot"]; ok {
+		t.Fatalf("expected pilot branch skipped when profile fields nil")
+	}
+
+	categoryOnly := contactAttributes(&contact.ContactListItem{
+		RoleCode:      "pilot",
+		RoleName:      "Pilot",
+		Email:         "cat@example.com",
+		FirstName:     "Cat",
+		LastName:      "Only",
+		PilotCategory: "freelance",
+	}, false)
+	pilotProfile, ok := categoryOnly["pilot"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected pilot branch included when pilot_category is present")
+	}
+	if pilotProfile["pilot_category"] != "freelance" {
+		t.Fatalf("expected pilot_category propagated, got %#v", pilotProfile["pilot_category"])
+	}
+
+	pilotRoleID := uuidv7.MustBytes()
+	staffRoleID := uuidv7.MustBytes()
+	rolesRaw := strings.ToLower(hex.EncodeToString(pilotRoleID)) + "|" + strings.ToLower(hex.EncodeToString([]byte("Pilot"))) + "|pilot," +
+		strings.ToLower(hex.EncodeToString(staffRoleID)) + "|" + strings.ToLower(hex.EncodeToString([]byte("Staff"))) + "|staff"
+	multiRole := contactAttributes(&contact.ContactListItem{
+		RoleCode:        "staff",
+		RoleName:        "staff",
+		RolesRaw:        &rolesRaw,
+		Email:           "multi@example.com",
+		FirstName:       "Multi",
+		LastName:        "Role",
+		PilotCategory:   "regular",
+		PilotShortName:  strPtrContact("Pilot"),
+		StaffShortName:  strPtrContact("Staff"),
+		StaffRoleLabel:  strPtrContact("Ops"),
+		StaffLocation:   strPtrContact("Jakarta"),
+		StaffPostcode:   strPtrContact("12950"),
+		StaffStreetLine: strPtrContact("Jl"),
+	}, false)
+	if _, ok := multiRole["pilot"]; !ok {
+		t.Fatalf("expected pilot profile in multi-role payload")
+	}
+	if _, ok := multiRole["staff"]; !ok {
+		t.Fatalf("expected staff profile in multi-role payload")
+	}
+
+	pilotTechRolesRaw := strings.ToLower(hex.EncodeToString(pilotRoleID)) + "|" + strings.ToLower(hex.EncodeToString([]byte("Pilot"))) + "|pilot," +
+		strings.ToLower(hex.EncodeToString(staffRoleID)) + "|" + strings.ToLower(hex.EncodeToString([]byte("Technician"))) + "|technician"
+	pilotTechnician := contactAttributes(&contact.ContactListItem{
+		RoleCode:                          "pilot",
+		RoleName:                          "pilot",
+		RolesRaw:                          &pilotTechRolesRaw,
+		Email:                             "pilot-tech@example.com",
+		FirstName:                         "Pilot",
+		LastName:                          "Tech",
+		PilotCategory:                     "regular",
+		PilotShortName:                    strPtrContact("Pilot"),
+		TechnicianShortName:               strPtrContact("Tech"),
+		TechnicianLicenseNo:               strPtrContact("TECH-1"),
+		TechnicianIsChiefTechnician:       boolPtrContact(true),
+		TechnicianIsResponsibleComplaints: boolPtrContact(true),
+	}, false)
+	if _, ok := pilotTechnician["pilot"]; !ok {
+		t.Fatalf("expected pilot profile in pilot+technician payload")
+	}
+	if _, ok := pilotTechnician["technician"]; !ok {
+		t.Fatalf("expected technician profile in pilot+technician payload")
+	}
+}
+
+func intPtrContactHandler(v int) *int { return &v }
diff --git a/internal/transport/http/handlers/delete_error_mapper.go b/internal/transport/http/handlers/delete_error_mapper.go
new file mode 100644
index 0000000..e9382b0
--- /dev/null
+++ b/internal/transport/http/handlers/delete_error_mapper.go
@@ -0,0 +1,34 @@
+package handlers
+
+import (
+	"errors"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+)
+
+func writeDeleteError(c *fiber.Ctx, err error) error {
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return response.WriteErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "resource not found",
+		}})
+	}
+	if conflict, ok := apperrors.AsDeleteConflict(err); ok {
+		return response.WriteErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+			Status: "409",
+			Title:  "Conflict",
+			Detail: conflict.Error(),
+		}})
+	}
+	return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+		Status: "400",
+		Title:  "Delete failed",
+		Detail: safeInternalDetail(),
+	}})
+}
diff --git a/internal/transport/http/handlers/dul_handler.go b/internal/transport/http/handlers/dul_handler.go
new file mode 100644
index 0000000..6ae90e4
--- /dev/null
+++ b/internal/transport/http/handlers/dul_handler.go
@@ -0,0 +1,766 @@
+package handlers
+
+import (
+	"context"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/base"
+	"wucher/internal/domain/contact"
+	"wucher/internal/domain/dul"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type DULHandler struct {
+	svc         dul.Service
+	baseSvc     base.Service
+	contactSvc  contact.Service
+	fileManager filemanager.Service
+	storage     fileManagerDownloadURLStorage
+	validate    *validators.Validator
+}
+
+func NewDULHandler(svc dul.Service) *DULHandler {
+	return &DULHandler{svc: svc, validate: validators.New()}
+}
+
+func (h *DULHandler) WithFileManagerService(fileManager filemanager.Service) *DULHandler {
+	h.fileManager = fileManager
+	return h
+}
+
+func (h *DULHandler) WithBaseService(baseSvc base.Service) *DULHandler {
+	h.baseSvc = baseSvc
+	return h
+}
+
+func (h *DULHandler) WithContactService(contactSvc contact.Service) *DULHandler {
+	h.contactSvc = contactSvc
+	return h
+}
+
+func (h *DULHandler) WithFileStorage(storage fileManagerDownloadURLStorage) *DULHandler {
+	h.storage = storage
+	return h
+}
+
+// CreateDUL godoc
+// @Summary Create DUL
+// @Description Possible error code: DUL_INVALID_JSON, DUL_INVALID_UUID, DUL_DATE_INVALID, DUL_VALIDATION_FAILED, DUL_CREATE_FAILED.
+// @Tags DUL
+// @Accept json
+// @Produce json
+// @Param request body dto.DULCreateRequest true "DUL create request"
+// @Success 201 {object} dto.DULResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/dul/create [post]
+func (h *DULHandler) Create(c *fiber.Ctx) error {
+	var req dto.DULCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeDULErrors(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	baseID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.BaseID))
+	if err != nil {
+		return writeDULErrors(c, fiber.StatusUnprocessableEntity, "Validation error", "base_id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/data/attributes/base_id"})
+	}
+
+	dateValue, err := parseDULDate(strings.TrimSpace(req.Data.Attributes.Date))
+	if err != nil {
+		return writeDULErrors(c, fiber.StatusUnprocessableEntity, "Validation error", "date must use format YYYY-MM-DD", &jsonapi.ErrorSource{Pointer: "/data/attributes/date"})
+	}
+
+	row := &dul.DUL{
+		Name:      strings.TrimSpace(req.Data.Attributes.Name),
+		Date:      dateValue,
+		Info:      strings.TrimSpace(stringOrDefault(req.Data.Attributes.Info, "")),
+		BaseID:    baseID,
+		CreatedBy: actorUserID(c),
+		UpdatedBy: actorUserID(c),
+	}
+	if row.Name == "" {
+		return writeDULErrors(c, fiber.StatusUnprocessableEntity, "Validation error", "name is required", &jsonapi.ErrorSource{Pointer: "/data/attributes/name"})
+	}
+
+	fileUUIDs := req.Data.Attributes.FileUUID
+	if fileUUIDs == nil {
+		fileUUIDs = req.Data.Attributes.ImageAttachmentIDs
+	}
+	if err := h.validateDULImageFiles(c, fileUUIDs); err != nil {
+		return writeDULErrors(c, fiber.StatusBadRequest, "Create failed", err.Error(), nil)
+	}
+
+	createErr := h.withDULTransaction(c.UserContext(), func(txSvc dul.Service) error {
+		if err := txSvc.Create(c.UserContext(), row); err != nil {
+			return err
+		}
+		if err := h.syncImages(c, row.ID, fileUUIDs); err != nil {
+			return err
+		}
+		return nil
+	})
+	if createErr != nil {
+		return writeDULErrors(c, fiber.StatusBadRequest, "Create failed", createErr.Error(), nil)
+	}
+
+	created, _ := h.svc.GetByID(c.UserContext(), row.ID)
+	if created == nil {
+		created = row
+	}
+	return response.Write(c, fiber.StatusCreated, dto.DULResponse{Data: h.toResource(created)})
+}
+
+// UpdateDUL godoc
+// @Summary Update DUL
+// @Description Possible error code: DUL_INVALID_JSON, DUL_INVALID_UUID, DUL_DATE_INVALID, DUL_VALIDATION_FAILED, DUL_NOT_FOUND, DUL_UPDATE_FAILED.
+// @Tags DUL
+// @Accept json
+// @Produce json
+// @Param id path string true "DUL ID"
+// @Param request body dto.DULUpdateRequest true "DUL update request"
+// @Success 200 {object} dto.DULResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/dul/update/{id} [patch]
+func (h *DULHandler) Update(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("id"))
+	if err != nil {
+		return writeDULErrors(c, fiber.StatusUnprocessableEntity, "Validation error", "id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/path/id"})
+	}
+	var req dto.DULUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeDULErrors(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || row == nil {
+		return writeDULErrors(c, fiber.StatusNotFound, "Not found", "dul not found", nil)
+	}
+	if req.Data.Attributes.Name != nil {
+		row.Name = strings.TrimSpace(*req.Data.Attributes.Name)
+	}
+	if req.Data.Attributes.Date != nil {
+		dateValue, parseErr := parseDULDate(strings.TrimSpace(*req.Data.Attributes.Date))
+		if parseErr != nil {
+			return writeDULErrors(c, fiber.StatusUnprocessableEntity, "Validation error", "date must use format YYYY-MM-DD", &jsonapi.ErrorSource{Pointer: "/data/attributes/date"})
+		}
+		row.Date = dateValue
+	}
+	if req.Data.Attributes.Info != nil {
+		row.Info = strings.TrimSpace(*req.Data.Attributes.Info)
+	}
+	if req.Data.Attributes.BaseID != nil {
+		baseID, parseErr := uuidv7.ParseString(strings.TrimSpace(*req.Data.Attributes.BaseID))
+		if parseErr != nil {
+			return writeDULErrors(c, fiber.StatusUnprocessableEntity, "Validation error", "base_id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/data/attributes/base_id"})
+		}
+		row.BaseID = baseID
+	}
+	row.UpdatedBy = actorUserID(c)
+
+	fileUUIDPatch := req.Data.Attributes.FileUUID
+	if fileUUIDPatch == nil && req.Data.Attributes.ImageAttachmentIDs != nil {
+		fileUUIDPatch = req.Data.Attributes.ImageAttachmentIDs
+	}
+	if err := h.validateDULImageFiles(c, fileUUIDPatch); err != nil {
+		return writeDULErrors(c, fiber.StatusBadRequest, "Update failed", err.Error(), nil)
+	}
+	updateErr := h.withDULTransaction(c.UserContext(), func(txSvc dul.Service) error {
+		if err := txSvc.Update(c.UserContext(), row); err != nil {
+			return err
+		}
+		if fileUUIDPatch != nil {
+			if err := h.syncImages(c, row.ID, fileUUIDPatch); err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+	if updateErr != nil {
+		return writeDULErrors(c, fiber.StatusBadRequest, "Update failed", updateErr.Error(), nil)
+	}
+	updated, _ := h.svc.GetByID(c.UserContext(), row.ID)
+	if updated == nil {
+		updated = row
+	}
+	return response.Write(c, fiber.StatusOK, dto.DULResponse{Data: h.toResource(updated)})
+}
+
+// DeleteDUL godoc
+// @Summary Delete DUL
+// @Description Possible error code: DUL_INVALID_UUID, DUL_DELETE_FAILED.
+// @Tags DUL
+// @Produce json
+// @Param id path string true "DUL ID"
+// @Success 200 {object} dto.DULDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/dul/delete/{id} [delete]
+func (h *DULHandler) Delete(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("id"))
+	if err != nil {
+		return writeDULErrors(c, fiber.StatusUnprocessableEntity, "Validation error", "id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/path/id"})
+	}
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeDULErrors(c, fiber.StatusNotFound, "Not found", "dul not found", nil)
+		}
+		return writeDULErrors(c, fiber.StatusBadRequest, "Delete failed", err.Error(), nil)
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "dul_delete", Attributes: map[string]any{"deleted": true}})
+}
+
+// GetDUL godoc
+// @Summary Get DUL by ID
+// @Description Possible error code: DUL_INVALID_UUID, DUL_NOT_FOUND.
+// @Tags DUL
+// @Produce json
+// @Param id path string true "DUL ID"
+// @Success 200 {object} dto.DULResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/dul/get/{id} [get]
+func (h *DULHandler) Get(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("id"))
+	if err != nil {
+		return writeDULErrors(c, fiber.StatusUnprocessableEntity, "Validation error", "id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/path/id"})
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || row == nil {
+		return writeDULErrors(c, fiber.StatusNotFound, "Not found", "dul not found", nil)
+	}
+	return response.Write(c, fiber.StatusOK, dto.DULResponse{Data: h.toResource(row)})
+}
+
+// ListDUL godoc
+// @Summary List DUL grouped by base
+// @Description Possible error code: DUL_LIST_FAILED.
+// @Tags DUL
+// @Produce json
+// @Param search query string false "Search by name/info"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param page query int false "Page number alias"
+// @Param size query int false "Page size alias"
+// @Param limit query int false "Page size alias"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.DULListResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/dul/get-all [get]
+func (h *DULHandler) List(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	allowedBaseIDs, allowedBaseIDSet, err := h.resolveScopedDULBaseAccess(c)
+	if err != nil {
+		return writeDULErrors(c, fiber.StatusBadRequest, "List failed", err.Error(), nil)
+	}
+	rows, total, err := h.svc.List(c.UserContext(), c.Query("search"), c.Query("sort"), 0, 0, allowedBaseIDs)
+	if err != nil {
+		return writeDULErrors(c, fiber.StatusBadRequest, "List failed", err.Error(), nil)
+	}
+	grouped := h.groupRows(rows, allowedBaseIDSet)
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+		"total_bases": len(grouped),
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, grouped, meta)
+}
+
+// ListDULDatatable godoc
+// @Summary List DUL grouped by base (datatable)
+// @Description Possible error code: DUL_LIST_FAILED.
+// @Tags DUL
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search by name/info"
+// @Success 200 {object} dto.DULDataTableResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/dul/get-all/dt [get]
+func (h *DULHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+
+	start := (pageNumber - 1) * length
+	allowedBaseIDs, allowedBaseIDSet, err := h.resolveScopedDULBaseAccess(c)
+	if err != nil {
+		return writeDULErrors(c, fiber.StatusBadRequest, "List failed", err.Error(), nil)
+	}
+	rows, total, err := h.svc.List(c.UserContext(), c.Query("search"), c.Query("sort"), length, start, allowedBaseIDs)
+	if err != nil {
+		return writeDULErrors(c, fiber.StatusBadRequest, "List failed", err.Error(), nil)
+	}
+	grouped := h.groupRows(rows, allowedBaseIDSet)
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+		"page_number":      pageNumber,
+		"page_size":        length,
+		"total":            total,
+		"total_bases":      len(grouped),
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, grouped, meta)
+}
+
+func (h *DULHandler) groupRows(rows []dul.DUL, allowedBaseIDSet map[string]struct{}) []dto.DULGroup {
+	basesOrder := make([]string, 0)
+	groups := map[string]*dto.DULGroup{}
+
+	// Always seed groups with bases where dul=true so FE can always render all DUL bases.
+	if h.baseSvc != nil {
+		bases, _, err := h.baseSvc.ListBases(context.Background(), "", "", 0, 0, "", boolPtrDUL(true))
+		if err == nil {
+			for i := range bases {
+				if !bases[i].DUL {
+					continue
+				}
+				baseID, convErr := uuidv7.BytesToString(bases[i].ID)
+				if convErr != nil || strings.TrimSpace(baseID) == "" {
+					continue
+				}
+				if len(allowedBaseIDSet) > 0 {
+					if _, ok := allowedBaseIDSet[baseID]; !ok {
+						continue
+					}
+				}
+				if _, exists := groups[baseID]; exists {
+					continue
+				}
+				groups[baseID] = &dto.DULGroup{
+					Base: dto.DULBaseRef{
+						ID:       baseID,
+						Name:     bases[i].BaseName,
+						Category: bases[i].BaseCategory.Name,
+					},
+					DULs: []dto.DULResource{},
+				}
+				basesOrder = append(basesOrder, baseID)
+			}
+		}
+	}
+	for i := range rows {
+		item := rows[i]
+		baseID, _ := uuidv7.BytesToString(item.BaseID)
+		if strings.TrimSpace(baseID) == "" {
+			continue
+		}
+		if len(allowedBaseIDSet) > 0 {
+			if _, ok := allowedBaseIDSet[baseID]; !ok {
+				continue
+			}
+		}
+		g := groups[baseID]
+		if g == nil {
+			g = &dto.DULGroup{Base: dto.DULBaseRef{ID: baseID}}
+			if item.Base != nil {
+				g.Base.Name = item.Base.BaseName
+				g.Base.Category = item.Base.BaseCategory.Name
+			}
+			groups[baseID] = g
+			basesOrder = append(basesOrder, baseID)
+		}
+		g.DULs = append(g.DULs, h.toResource(&item))
+	}
+	out := make([]dto.DULGroup, 0, len(basesOrder))
+	for _, key := range basesOrder {
+		sort.Slice(groups[key].DULs, func(i, j int) bool { return groups[key].DULs[i].Attributes.No < groups[key].DULs[j].Attributes.No })
+		out = append(out, *groups[key])
+	}
+	return out
+}
+
+func (h *DULHandler) toResource(row *dul.DUL) dto.DULResource {
+	id, _ := uuidv7.BytesToString(row.ID)
+	baseID, _ := uuidv7.BytesToString(row.BaseID)
+	res := dto.DULResource{Type: "dul", ID: id, Attributes: dto.DULAttributes{Name: row.Name, Date: row.Date.Format("2006-01-02"), Info: row.Info, No: row.No, Base: dto.DULBaseRef{ID: baseID}, Images: []dto.DULImage{}, CreatedAt: row.CreatedAt.Format("2006-01-02T15:04:05Z"), UpdatedAt: row.UpdatedAt.Format("2006-01-02T15:04:05Z")}}
+	if row.Base != nil {
+		res.Attributes.Base.Name = row.Base.BaseName
+		res.Attributes.Base.Category = row.Base.BaseCategory.Name
+	}
+	res.Attributes.CreatedBy = idString(row.CreatedBy)
+	res.Attributes.UpdatedBy = idString(row.UpdatedBy)
+	for _, img := range row.Images {
+		if img == nil {
+			continue
+		}
+		attID, _ := uuidv7.BytesToString(img.ID)
+		it := dto.DULImage{UUID: attID}
+		if img.File != nil {
+			asset := resolveFileManagerDownloadURLs(context.Background(), h.storage, img.File)
+			it.DownloadURL = strings.TrimSpace(asset.OriginalURL)
+			it.OriginalSizeBytes = asset.OriginalSizeBytes
+			it.ThumbnailDownloadURL = strings.TrimSpace(asset.ThumbnailURL)
+		}
+		res.Attributes.Images = append(res.Attributes.Images, it)
+	}
+	return res
+}
+
+func (h *DULHandler) syncImages(c *fiber.Ctx, dulID []byte, attachmentIDs []string) error {
+	if h.fileManager == nil {
+		return nil
+	}
+	refID := idString(dulID)
+	desired, err := h.resolveDULImageFiles(c, attachmentIDs)
+	if err != nil {
+		return err
+	}
+
+	existing, _, err := h.fileManager.ListAttachmentsByReference(c.UserContext(), filemanager.ListAttachmentsParams{RefType: "dul", RefID: refID, Limit: 1000})
+	if err != nil {
+		return err
+	}
+	for i := range existing {
+		if delErr := h.fileManager.DeleteAttachment(c.UserContext(), existing[i].ID); delErr != nil {
+			return delErr
+		}
+	}
+	for idx, fileID := range desired {
+		if _, createErr := h.fileManager.CreateAttachment(c.UserContext(), filemanager.CreateAttachmentParams{FileID: fileID, RefType: "dul", RefID: refID, Category: ptrString("image"), SortOrder: idx, IsPrimary: idx == 0, ActorID: actorUserID(c)}); createErr != nil {
+			return createErr
+		}
+	}
+	return nil
+}
+
+func (h *DULHandler) validateDULImageFiles(c *fiber.Ctx, attachmentIDs []string) error {
+	_, err := h.resolveDULImageFiles(c, attachmentIDs)
+	return err
+}
+
+func (h *DULHandler) resolveDULImageFiles(c *fiber.Ctx, attachmentIDs []string) ([][]byte, error) {
+	if h.fileManager == nil {
+		return nil, nil
+	}
+	desired := make([][]byte, 0, len(attachmentIDs))
+	seenFile := make(map[string]struct{}, len(attachmentIDs))
+	for idx, raw := range attachmentIDs {
+		id, parseErr := uuidv7.ParseString(strings.TrimSpace(raw))
+		if parseErr != nil {
+			return nil, fmt.Errorf("file_uuid[%d] is invalid UUID", idx)
+		}
+		att, getErr := h.fileManager.GetAttachmentByID(c.UserContext(), id)
+		if getErr != nil {
+			return nil, fmt.Errorf("file_uuid[%d] not found", idx)
+		}
+
+		var fileID []byte
+		if att != nil && len(att.FileID) > 0 {
+			fileRow, fileErr := h.fileManager.GetFileByID(c.UserContext(), att.FileID)
+			if fileErr != nil || fileRow == nil {
+				return nil, fmt.Errorf("file_uuid[%d] not found", idx)
+			}
+			if filemanager.NormalizeFileStatus(fileRow.Status) != filemanager.FileStatusReady {
+				return nil, filemanager.ErrFileNotReadyForAttachment
+			}
+			fileID = append([]byte(nil), att.FileID...)
+		} else {
+			fileRow, fileErr := h.fileManager.GetFileByID(c.UserContext(), id)
+			if fileErr != nil || fileRow == nil {
+				return nil, fmt.Errorf("file_uuid[%d] not found", idx)
+			}
+			if filemanager.NormalizeFileStatus(fileRow.Status) != filemanager.FileStatusReady {
+				return nil, filemanager.ErrFileNotReadyForAttachment
+			}
+			fileID = append([]byte(nil), fileRow.ID...)
+		}
+
+		key := string(fileID)
+		if _, dup := seenFile[key]; dup {
+			continue
+		}
+		seenFile[key] = struct{}{}
+		desired = append(desired, fileID)
+	}
+	return desired, nil
+}
+
+type dulTransactionalService interface {
+	WithTransaction(ctx context.Context, fn func(dul.Service) error) error
+}
+
+func (h *DULHandler) withDULTransaction(ctx context.Context, fn func(dul.Service) error) error {
+	txSvc, ok := h.svc.(dulTransactionalService)
+	if !ok {
+		return fn(h.svc)
+	}
+	return txSvc.WithTransaction(ctx, fn)
+}
+
+func writeDULErrors(c *fiber.Ctx, status int, title, detail string, source *jsonapi.ErrorSource) error {
+	def := inferDULErrorDef(status, title, detail)
+	return response.WriteErrors(c, status, []jsonapi.ErrorObject{{
+		Status:    strconv.Itoa(status),
+		Title:     def.Title,
+		Detail:    def.Message,
+		Source:    source,
+		Code:      def.Code,
+		ErrorCode: def.ErrorCode,
+	}})
+}
+
+func inferDULErrorDef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.ErrDULNotFound
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "date"):
+			return apperrorsx.ErrDULDateInvalid
+		case strings.Contains(lowerDetail, "invalid uuid"), strings.Contains(lowerDetail, "invalid id"):
+			return apperrorsx.ErrDULInvalidUUID
+		case strings.Contains(lowerTitle, "validation error"):
+			return apperrorsx.ErrDULValidationFailed
+		default:
+			return apperrorsx.ErrDULInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrDULInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.ErrDULCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrDULUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrDULDeleteFailed
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.ErrDULListFailed
+		default:
+			return apperrorsx.ErrDULInvalidPayload
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
+
+func inferDULErrorCode(status int, title, detail string) (string, string) {
+	return inferDULErrorDef(status, title, detail).Code, inferDULErrorDef(status, title, detail).ErrorCode
+}
+
+func parseDULDate(raw string) (time.Time, error) {
+	return time.Parse("2006-01-02", raw)
+}
+
+func boolPtrDUL(v bool) *bool {
+	return &v
+}
+
+func (h *DULHandler) resolveScopedDULBaseAccess(c *fiber.Ctx) ([][]byte, map[string]struct{}, error) {
+	// Default scope for all roles: all bases with dul=true.
+	dulBaseIDs, dulBaseIDSet, err := h.dulEnabledBaseScope()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	// No contact service means no actor-role scoping.
+	if h.contactSvc == nil {
+		return dulBaseIDs, dulBaseIDSet, nil
+	}
+	isAdmin, err := h.contactSvc.IsActorAdmin(c.UserContext())
+	if err != nil {
+		return nil, nil, err
+	}
+	if isAdmin {
+		return dulBaseIDs, dulBaseIDSet, nil
+	}
+
+	actorID := actorUserID(c)
+	if len(actorID) != 16 {
+		return dulBaseIDs, dulBaseIDSet, nil
+	}
+	contactRow, err := h.contactSvc.GetContactByID(c.UserContext(), actorID)
+	if err != nil {
+		return nil, nil, err
+	}
+	if contactRow == nil {
+		return dulBaseIDs, dulBaseIDSet, nil
+	}
+	if !isPilotRoleContact(contactRow) {
+		return dulBaseIDs, dulBaseIDSet, nil
+	}
+
+	ids, set := parseDULBaseIDsFromRaw(contactRow.BaseRolesRaw)
+	if len(dulBaseIDSet) == 0 {
+		return ids, set, nil
+	}
+	// Pilot scope: all DUL data, but only within assigned DUL bases.
+	scopedIDs := make([][]byte, 0, len(ids))
+	scopedSet := map[string]struct{}{}
+	for i := range ids {
+		baseID, convErr := uuidv7.BytesToString(ids[i])
+		if convErr != nil || strings.TrimSpace(baseID) == "" {
+			continue
+		}
+		if _, ok := dulBaseIDSet[baseID]; !ok {
+			continue
+		}
+		if _, exists := scopedSet[baseID]; exists {
+			continue
+		}
+		copied := make([]byte, len(ids[i]))
+		copy(copied, ids[i])
+		scopedIDs = append(scopedIDs, copied)
+		scopedSet[baseID] = struct{}{}
+	}
+	return scopedIDs, scopedSet, nil
+}
+
+func (h *DULHandler) dulEnabledBaseScope() ([][]byte, map[string]struct{}, error) {
+	if h.baseSvc == nil {
+		return nil, nil, nil
+	}
+	bases, _, err := h.baseSvc.ListBases(context.Background(), "", "", 0, 0, "", boolPtrDUL(true))
+	if err != nil {
+		return nil, nil, err
+	}
+	baseIDs := make([][]byte, 0, len(bases))
+	baseIDSet := map[string]struct{}{}
+	for i := range bases {
+		if !bases[i].DUL || len(bases[i].ID) != 16 {
+			continue
+		}
+		baseID, convErr := uuidv7.BytesToString(bases[i].ID)
+		if convErr != nil || strings.TrimSpace(baseID) == "" {
+			continue
+		}
+		if _, exists := baseIDSet[baseID]; exists {
+			continue
+		}
+		copied := make([]byte, 16)
+		copy(copied, bases[i].ID)
+		baseIDs = append(baseIDs, copied)
+		baseIDSet[baseID] = struct{}{}
+	}
+	return baseIDs, baseIDSet, nil
+}
+
+func isPilotRoleContact(item *contact.ContactListItem) bool {
+	if item == nil {
+		return false
+	}
+	if strings.TrimSpace(strings.ToLower(item.RoleCode)) == "pilot" {
+		return true
+	}
+	if item.RolesRaw == nil || strings.TrimSpace(*item.RolesRaw) == "" {
+		return false
+	}
+	parts := strings.Split(*item.RolesRaw, ",")
+	for i := range parts {
+		fields := strings.Split(parts[i], "|")
+		if len(fields) != 3 {
+			continue
+		}
+		if strings.TrimSpace(strings.ToLower(fields[2])) == "pilot" {
+			return true
+		}
+	}
+	return false
+}
+
+func parseDULBaseIDsFromRaw(raw *string) ([][]byte, map[string]struct{}) {
+	if raw == nil || strings.TrimSpace(*raw) == "" {
+		return [][]byte{}, map[string]struct{}{}
+	}
+	out := make([][]byte, 0)
+	set := map[string]struct{}{}
+	parts := strings.Split(*raw, ",")
+	for i := range parts {
+		fields := strings.Split(parts[i], "|")
+		if len(fields) < 3 {
+			continue
+		}
+		if strings.TrimSpace(strings.ToLower(fields[2])) != "dul" {
+			continue
+		}
+		baseIDHex := strings.TrimSpace(fields[0])
+		if baseIDHex == "" {
+			continue
+		}
+		baseIDBytes, err := hex.DecodeString(baseIDHex)
+		if err != nil || len(baseIDBytes) != 16 {
+			continue
+		}
+		baseID, err := uuidv7.BytesToString(baseIDBytes)
+		if err != nil || strings.TrimSpace(baseID) == "" {
+			continue
+		}
+		if _, exists := set[baseID]; exists {
+			continue
+		}
+		set[baseID] = struct{}{}
+		copied := make([]byte, 16)
+		copy(copied, baseIDBytes)
+		out = append(out, copied)
+	}
+	return out, set
+}
diff --git a/internal/transport/http/handlers/dul_handler_test.go b/internal/transport/http/handlers/dul_handler_test.go
new file mode 100644
index 0000000..220dae5
--- /dev/null
+++ b/internal/transport/http/handlers/dul_handler_test.go
@@ -0,0 +1,931 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"github.com/valyala/fasthttp"
+
+	"wucher/internal/domain/base"
+	"wucher/internal/domain/contact"
+	"wucher/internal/domain/dul"
+	filemanager "wucher/internal/domain/file_manager"
+	filemanagerrealtime "wucher/internal/realtime/filemanager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type dulServiceMock struct {
+	createFn   func(context.Context, *dul.DUL) error
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getErr     error
+	listErr    error
+	getResult  *dul.DUL
+	listRows   []dul.DUL
+	listTotal  int64
+	lastListID [][]byte
+}
+
+func (m *dulServiceMock) Create(ctx context.Context, row *dul.DUL) error {
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	if m.createErr != nil {
+		return m.createErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+func (m *dulServiceMock) Update(_ context.Context, _ *dul.DUL) error { return m.updateErr }
+func (m *dulServiceMock) Delete(_ context.Context, _ []byte, _ []byte) error {
+	return m.deleteErr
+}
+func (m *dulServiceMock) GetByID(_ context.Context, _ []byte) (*dul.DUL, error) {
+	if m.getErr != nil {
+		return nil, m.getErr
+	}
+	return m.getResult, nil
+}
+func (m *dulServiceMock) List(_ context.Context, _ string, _ string, _ int, _ int, baseIDs [][]byte) ([]dul.DUL, int64, error) {
+	m.lastListID = baseIDs
+	if m.listErr != nil {
+		return nil, 0, m.listErr
+	}
+	return m.listRows, m.listTotal, nil
+}
+
+type baseServiceMock struct {
+	listRows []base.Base
+	listErr  error
+}
+
+func (m *baseServiceMock) CreateBase(_ context.Context, _ *base.Base, _ string) error { return nil }
+func (m *baseServiceMock) UpdateBase(_ context.Context, _ *base.Base, _ string) error { return nil }
+func (m *baseServiceMock) DeleteBase(_ context.Context, _ []byte, _ string) (*base.Base, error) {
+	return nil, nil
+}
+func (m *baseServiceMock) GetBaseByID(_ context.Context, _ []byte, _ string) (*base.Base, error) {
+	return nil, nil
+}
+func (m *baseServiceMock) ListBases(_ context.Context, _, _ string, _, _ int, _ string, _ *bool) ([]base.Base, int64, error) {
+	if m.listErr != nil {
+		return nil, 0, m.listErr
+	}
+	return m.listRows, int64(len(m.listRows)), nil
+}
+
+type contactServiceMock struct {
+	isAdmin  bool
+	adminErr error
+	item     *contact.ContactListItem
+	getErr   error
+}
+
+func (m *contactServiceMock) ListContacts(_ context.Context, _ contact.ListFilter) ([]contact.ContactListItem, int64, error) {
+	return nil, 0, nil
+}
+func (m *contactServiceMock) GetContactByID(_ context.Context, _ []byte) (*contact.ContactListItem, error) {
+	return m.item, m.getErr
+}
+func (m *contactServiceMock) IsActorAdmin(_ context.Context) (bool, error) {
+	return m.isAdmin, m.adminErr
+}
+func (m *contactServiceMock) ResolveRoleCodeByID(_ context.Context, _ []byte) (string, error) {
+	return "", nil
+}
+func (m *contactServiceMock) CreateContact(_ context.Context, _ contact.CreateInput) ([]byte, error) {
+	return nil, nil
+}
+func (m *contactServiceMock) UpdateContact(_ context.Context, _ contact.UpdateInput) error {
+	return nil
+}
+func (m *contactServiceMock) DeleteContact(_ context.Context, _ []byte) error { return nil }
+func (m *contactServiceMock) UpdateContactStatus(_ context.Context, _ []byte, _ bool) error {
+	return nil
+}
+func (m *contactServiceMock) UpdateContactRole(_ context.Context, _ []byte, _ string) error {
+	return nil
+}
+func (m *contactServiceMock) UpdatePilotCategory(_ context.Context, _ []byte, _ string) error {
+	return nil
+}
+func (m *contactServiceMock) UpdateLicense(_ context.Context, _ []byte, _ *string) error {
+	return nil
+}
+func (m *contactServiceMock) UpdateChiefFlags(_ context.Context, _ []byte, _ contact.ProfilePatch) error {
+	return nil
+}
+func (m *contactServiceMock) UpdateResponsibleComplaints(_ context.Context, _ []byte, _ bool) error {
+	return nil
+}
+func (m *contactServiceMock) BulkUpdateStatus(_ context.Context, _ [][]byte, _ bool) (int64, error) {
+	return 0, nil
+}
+func (m *contactServiceMock) CheckSensitiveAction(_ context.Context, _ []byte, _, _ string) error {
+	return nil
+}
+
+func newDULApp(h *DULHandler) *fiber.App {
+	app := fiber.New()
+	app.Post("/api/v1/dul/create", func(c *fiber.Ctx) error {
+		c.Locals("user_id", uuidv7.MustBytes())
+		return h.Create(c)
+	})
+	app.Patch("/api/v1/dul/update/:id", func(c *fiber.Ctx) error {
+		c.Locals("user_id", uuidv7.MustBytes())
+		return h.Update(c)
+	})
+	app.Delete("/api/v1/dul/delete/:id", func(c *fiber.Ctx) error {
+		c.Locals("user_id", uuidv7.MustBytes())
+		return h.Delete(c)
+	})
+	app.Get("/api/v1/dul/get/:id", h.Get)
+	app.Get("/api/v1/dul/get-all", func(c *fiber.Ctx) error {
+		c.Locals("user_id", uuidv7.MustBytes())
+		return h.List(c)
+	})
+	app.Get("/api/v1/dul/get-all/dt", func(c *fiber.Ctx) error {
+		c.Locals("user_id", uuidv7.MustBytes())
+		return h.ListDatatable(c)
+	})
+	return app
+}
+
+func newDULEventsApp(h *FileManagerEventsHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if actor != nil {
+			c.Locals("user_id", append([]byte(nil), actor...))
+		}
+		return c.Next()
+	})
+	app.Get("/api/v1/dul/events", h.Stream)
+	return app
+}
+
+func doReqDUL(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, map[string]any) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app test: %v", err)
+	}
+	raw, _ := io.ReadAll(resp.Body)
+	out := map[string]any{}
+	_ = json.Unmarshal(raw, &out)
+	return resp, out
+}
+
+func TestDULHandler_CRUDAndList(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	baseIDStr, _ := uuidv7.BytesToString(baseID)
+	dulID := uuidv7.MustBytes()
+	dulIDStr, _ := uuidv7.BytesToString(dulID)
+
+	svc := &dulServiceMock{
+		getResult: &dul.DUL{
+			ID:        dulID,
+			BaseID:    baseID,
+			Name:      "DUL A",
+			Date:      time.Date(2026, 5, 25, 0, 0, 0, 0, time.UTC),
+			CreatedAt: time.Now().UTC(),
+			UpdatedAt: time.Now().UTC(),
+			No:        1,
+		},
+		listRows: []dul.DUL{{
+			ID:        dulID,
+			BaseID:    baseID,
+			Name:      "DUL A",
+			Date:      time.Date(2026, 5, 25, 0, 0, 0, 0, time.UTC),
+			CreatedAt: time.Now().UTC(),
+			UpdatedAt: time.Now().UTC(),
+			No:        1,
+		}},
+		listTotal: 1,
+	}
+	bsvc := &baseServiceMock{
+		listRows: []base.Base{{
+			ID:       baseID,
+			BaseName: "Halim",
+			DUL:      true,
+			BaseCategory: base.BaseCategory{
+				Name: "hems",
+			},
+		}},
+	}
+	h := NewDULHandler(svc).WithBaseService(bsvc)
+	app := newDULApp(h)
+
+	createBody := []byte(`{"data":{"type":"dul_create","attributes":{"name":"DUL A","date":"2026-05-25","base_id":"` + baseIDStr + `"}}}`)
+	resp, _ := doReqDUL(t, app, http.MethodPost, "/api/v1/dul/create", createBody)
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201, got %d", resp.StatusCode)
+	}
+
+	updateBody := []byte(`{"data":{"type":"dul_update","attributes":{"name":"DUL B"}}}`)
+	resp, _ = doReqDUL(t, app, http.MethodPatch, "/api/v1/dul/update/"+dulIDStr, updateBody)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	resp, _ = doReqDUL(t, app, http.MethodGet, "/api/v1/dul/get/"+dulIDStr, nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 get, got %d", resp.StatusCode)
+	}
+
+	resp, body := doReqDUL(t, app, http.MethodGet, "/api/v1/dul/get-all?page=1&size=20", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 list, got %d", resp.StatusCode)
+	}
+	meta, _ := body["meta"].(map[string]any)
+	if meta == nil || meta["total_bases"] == nil {
+		t.Fatalf("expected meta total_bases")
+	}
+
+	resp, body = doReqDUL(t, app, http.MethodGet, "/api/v1/dul/get-all/dt?page=1&size=20&draw=1", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 dt, got %d", resp.StatusCode)
+	}
+	meta, _ = body["meta"].(map[string]any)
+	if meta == nil || meta["records_total"] == nil || meta["page_number"] == nil {
+		t.Fatalf("expected datatable meta fields")
+	}
+
+	resp, _ = doReqDUL(t, app, http.MethodDelete, "/api/v1/dul/delete/"+dulIDStr, nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 delete, got %d", resp.StatusCode)
+	}
+}
+
+func TestDULHandler_CreateUpdate_FileUUIDFlow(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	baseIDStr, _ := uuidv7.BytesToString(baseID)
+	dulID := uuidv7.MustBytes()
+	dulIDStr, _ := uuidv7.BytesToString(dulID)
+	fileID1 := uuidv7.MustBytes()
+	fileID1Str, _ := uuidv7.BytesToString(fileID1)
+	fileID2 := uuidv7.MustBytes()
+	fileID2Str, _ := uuidv7.BytesToString(fileID2)
+
+	svc := &dulServiceMock{
+		getResult: &dul.DUL{
+			ID:        dulID,
+			BaseID:    baseID,
+			Name:      "DUL A",
+			Date:      time.Date(2026, 5, 26, 0, 0, 0, 0, time.UTC),
+			CreatedAt: time.Now().UTC(),
+			UpdatedAt: time.Now().UTC(),
+			No:        1,
+		},
+	}
+
+	createCalls := make([]filemanager.CreateAttachmentParams, 0, 2)
+	mockFM := &fileManagerAttachmentHandlerServiceMock{
+		getAttachmentFn: func(_ context.Context, _ []byte) (*filemanager.Attachment, error) {
+			return nil, nil
+		},
+		getFileFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+			return &filemanager.File{ID: append([]byte(nil), id...), Status: filemanager.FileStatusReady}, nil
+		},
+		listAttachmentsFn: func(context.Context, filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error) {
+			return nil, 0, nil
+		},
+		createAttachmentFn: func(_ context.Context, p filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+			createCalls = append(createCalls, p)
+			return &filemanager.Attachment{ID: uuidv7.MustBytes(), FileID: append([]byte(nil), p.FileID...)}, nil
+		},
+	}
+
+	h := NewDULHandler(svc).WithFileManagerService(mockFM)
+	app := newDULApp(h)
+
+	t.Run("create accepts file_uuid", func(t *testing.T) {
+		body := []byte(`{"data":{"type":"dul_create","attributes":{"name":"DUL A","date":"2026-05-26","base_id":"` + baseIDStr + `","file_uuid":["` + fileID1Str + `"]}}}`)
+		resp, _ := doReqDUL(t, app, http.MethodPost, "/api/v1/dul/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if len(createCalls) != 1 {
+			t.Fatalf("expected 1 create attachment call, got %d", len(createCalls))
+		}
+		if !bytes.Equal(createCalls[0].FileID, fileID1) {
+			t.Fatalf("expected first attachment file id = file_uuid[0]")
+		}
+	})
+
+	t.Run("update accepts file_uuid", func(t *testing.T) {
+		body := []byte(`{"data":{"type":"dul_update","attributes":{"file_uuid":["` + fileID2Str + `"]}}}`)
+		resp, _ := doReqDUL(t, app, http.MethodPatch, "/api/v1/dul/update/"+dulIDStr, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if len(createCalls) != 2 {
+			t.Fatalf("expected 2 create attachment calls after update, got %d", len(createCalls))
+		}
+		if !bytes.Equal(createCalls[1].FileID, fileID2) {
+			t.Fatalf("expected second attachment file id = file_uuid[0]")
+		}
+	})
+
+	t.Run("update still supports image_attachment_ids for backward compatibility", func(t *testing.T) {
+		fileID3 := uuidv7.MustBytes()
+		fileID3Str, _ := uuidv7.BytesToString(fileID3)
+		body := []byte(`{"data":{"type":"dul_update","attributes":{"image_attachment_ids":["` + fileID3Str + `"]}}}`)
+		resp, _ := doReqDUL(t, app, http.MethodPatch, "/api/v1/dul/update/"+dulIDStr, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if len(createCalls) != 3 {
+			t.Fatalf("expected 3 create attachment calls after backward-compatible update, got %d", len(createCalls))
+		}
+		if !bytes.Equal(createCalls[2].FileID, fileID3) {
+			t.Fatalf("expected third attachment file id from image_attachment_ids fallback")
+		}
+	})
+}
+
+func TestDULHandler_CreateRejectsNotReadyFileBeforeCreatingRow(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	baseIDStr, _ := uuidv7.BytesToString(baseID)
+	fileID := uuidv7.MustBytes()
+	fileIDStr, _ := uuidv7.BytesToString(fileID)
+	created := false
+
+	svc := &dulServiceMock{
+		createFn: func(context.Context, *dul.DUL) error {
+			created = true
+			t.Fatal("DUL create must not be called when file is not ready")
+			return nil
+		},
+	}
+	mockFM := &fileManagerAttachmentHandlerServiceMock{
+		getAttachmentFn: func(context.Context, []byte) (*filemanager.Attachment, error) {
+			return nil, nil
+		},
+		getFileFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+			if !bytes.Equal(id, fileID) {
+				t.Fatalf("unexpected file id: %x", id)
+			}
+			return &filemanager.File{ID: append([]byte(nil), id...), Status: filemanager.FileStatusProcessing}, nil
+		},
+	}
+
+	h := NewDULHandler(svc).WithFileManagerService(mockFM)
+	app := newDULApp(h)
+
+	body := []byte(`{"data":{"type":"dul_create","attributes":{"name":"DUL A","date":"2026-05-27","base_id":"` + baseIDStr + `","file_uuid":["` + fileIDStr + `"]}}}`)
+	resp, respBody := doReqDUL(t, app, http.MethodPost, "/api/v1/dul/create", body)
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 for not-ready file, got %d body=%v", resp.StatusCode, respBody)
+	}
+	if created {
+		t.Fatal("expected DUL create to be skipped")
+	}
+}
+
+func TestDULHandler_ListScope_AdminVsPilot(t *testing.T) {
+	baseA := uuidv7.MustBytes()
+	baseB := uuidv7.MustBytes()
+	baseAHex := stringsLower(hex.EncodeToString(baseA))
+	baseANameHex := stringsLower(hex.EncodeToString([]byte("Base A")))
+
+	svc := &dulServiceMock{
+		listRows:  []dul.DUL{},
+		listTotal: 0,
+	}
+	bsvc := &baseServiceMock{
+		listRows: []base.Base{
+			{ID: baseA, BaseName: "Base A", DUL: true, BaseCategory: base.BaseCategory{Name: "hems"}},
+			{ID: baseB, BaseName: "Base B", DUL: true, BaseCategory: base.BaseCategory{Name: "regular"}},
+		},
+	}
+
+	// Admin => scoped to all bases where dul=true.
+	hAdmin := NewDULHandler(svc).WithBaseService(bsvc).WithContactService(&contactServiceMock{isAdmin: true})
+	app := fiber.New()
+	app.Get("/list", func(c *fiber.Ctx) error {
+		c.Locals("user_id", uuidv7.MustBytes())
+		return hAdmin.List(c)
+	})
+	req, _ := http.NewRequest(http.MethodGet, "/list", nil)
+	resp, _ := app.Test(req)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("admin list status=%d", resp.StatusCode)
+	}
+	if len(svc.lastListID) != 2 {
+		t.Fatalf("admin should see all dul bases, got scope size=%d", len(svc.lastListID))
+	}
+
+	// Pilot => scoped only to DUL base roles.
+	raw := baseAHex + "|" + baseANameHex + "|dul|" + stringsLower(hex.EncodeToString([]byte("hems")))
+	contactItem := &contact.ContactListItem{
+		RoleCode:     "pilot",
+		BaseRolesRaw: &raw,
+	}
+	hPilot := NewDULHandler(svc).WithBaseService(bsvc).WithContactService(&contactServiceMock{isAdmin: false, item: contactItem})
+	app2 := fiber.New()
+	app2.Get("/list", func(c *fiber.Ctx) error {
+		c.Locals("user_id", uuidv7.MustBytes())
+		return hPilot.List(c)
+	})
+	req2, _ := http.NewRequest(http.MethodGet, "/list", nil)
+	resp2, _ := app2.Test(req2)
+	if resp2.StatusCode != http.StatusOK {
+		t.Fatalf("pilot list status=%d", resp2.StatusCode)
+	}
+	if len(svc.lastListID) != 1 {
+		t.Fatalf("pilot should be scoped to one base, got %d", len(svc.lastListID))
+	}
+}
+
+func TestDULHandler_ListScope_Rules(t *testing.T) {
+	baseA := uuidv7.MustBytes()
+	baseB := uuidv7.MustBytes()
+	baseC := uuidv7.MustBytes()
+	baseAHex := stringsLower(hex.EncodeToString(baseA))
+	baseANameHex := stringsLower(hex.EncodeToString([]byte("Base A")))
+	baseBHex := stringsLower(hex.EncodeToString(baseB))
+	baseBNameHex := stringsLower(hex.EncodeToString([]byte("Base B")))
+	makeApp := func(h *DULHandler) *fiber.App {
+		app := fiber.New()
+		app.Get("/list", func(c *fiber.Ctx) error {
+			c.Locals("user_id", uuidv7.MustBytes())
+			return h.List(c)
+		})
+		return app
+	}
+	newSvc := func() *dulServiceMock {
+		return &dulServiceMock{listRows: []dul.DUL{}, listTotal: 0}
+	}
+	bsvc := &baseServiceMock{
+		listRows: []base.Base{
+			{ID: baseA, BaseName: "Base A", DUL: true, BaseCategory: base.BaseCategory{Name: "hems"}},
+			{ID: baseB, BaseName: "Base B", DUL: true, BaseCategory: base.BaseCategory{Name: "regular"}},
+			{ID: baseC, BaseName: "Base C", DUL: false, BaseCategory: base.BaseCategory{Name: "regular"}},
+		},
+	}
+
+	t.Run("admin sees all dul=true bases", func(t *testing.T) {
+		svc := newSvc()
+		h := NewDULHandler(svc).WithBaseService(bsvc).WithContactService(&contactServiceMock{isAdmin: true})
+		resp, _ := makeApp(h).Test(httpTestReq(http.MethodGet, "/list"))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("admin list status=%d", resp.StatusCode)
+		}
+		if len(svc.lastListID) != 2 {
+			t.Fatalf("expected admin scope size=2 dul bases, got %d", len(svc.lastListID))
+		}
+	})
+
+	t.Run("pilot sees only assigned dul bases", func(t *testing.T) {
+		svc := newSvc()
+		raw := baseAHex + "|" + baseANameHex + "|dul|" + stringsLower(hex.EncodeToString([]byte("hems"))) + "," +
+			baseBHex + "|" + baseBNameHex + "|pilot|" + stringsLower(hex.EncodeToString([]byte("regular")))
+		item := &contact.ContactListItem{RoleCode: "pilot", BaseRolesRaw: &raw}
+		h := NewDULHandler(svc).WithBaseService(bsvc).WithContactService(&contactServiceMock{isAdmin: false, item: item})
+		resp, _ := makeApp(h).Test(httpTestReq(http.MethodGet, "/list"))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("pilot list status=%d", resp.StatusCode)
+		}
+		if len(svc.lastListID) != 1 {
+			t.Fatalf("expected pilot scope size=1 assigned dul base, got %d", len(svc.lastListID))
+		}
+	})
+
+	t.Run("pilot with no assigned dul base gets empty list scope", func(t *testing.T) {
+		svc := newSvc()
+		raw := baseBHex + "|" + baseBNameHex + "|pilot|" + stringsLower(hex.EncodeToString([]byte("regular")))
+		item := &contact.ContactListItem{RoleCode: "pilot", BaseRolesRaw: &raw}
+		h := NewDULHandler(svc).WithBaseService(bsvc).WithContactService(&contactServiceMock{isAdmin: false, item: item})
+		resp, _ := makeApp(h).Test(httpTestReq(http.MethodGet, "/list"))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("pilot list status=%d", resp.StatusCode)
+		}
+		if len(svc.lastListID) != 0 {
+			t.Fatalf("expected pilot with no dul assignment scope size=0, got %d", len(svc.lastListID))
+		}
+	})
+
+	t.Run("non pilot falls back to all dul=true bases", func(t *testing.T) {
+		svc := newSvc()
+		item := &contact.ContactListItem{RoleCode: "staff"}
+		h := NewDULHandler(svc).WithBaseService(bsvc).WithContactService(&contactServiceMock{isAdmin: false, item: item})
+		resp, _ := makeApp(h).Test(httpTestReq(http.MethodGet, "/list"))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("staff list status=%d", resp.StatusCode)
+		}
+		if len(svc.lastListID) != 2 {
+			t.Fatalf("expected staff scope size=2 dul bases, got %d", len(svc.lastListID))
+		}
+	})
+
+	t.Run("without contact service falls back to all dul=true bases", func(t *testing.T) {
+		svc := newSvc()
+		h := NewDULHandler(svc).WithBaseService(bsvc)
+		resp, _ := makeApp(h).Test(httpTestReq(http.MethodGet, "/list"))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("list status=%d", resp.StatusCode)
+		}
+		if len(svc.lastListID) != 2 {
+			t.Fatalf("expected scope size=2 dul bases without contact service, got %d", len(svc.lastListID))
+		}
+	})
+
+	t.Run("base service error returns 400", func(t *testing.T) {
+		svc := newSvc()
+		h := NewDULHandler(svc).WithBaseService(&baseServiceMock{listErr: errors.New("base boom")}).WithContactService(&contactServiceMock{isAdmin: true})
+		resp, _ := makeApp(h).Test(httpTestReq(http.MethodGet, "/list"))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 when base scope resolution fails, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("contact admin check error returns 400", func(t *testing.T) {
+		svc := newSvc()
+		h := NewDULHandler(svc).WithBaseService(bsvc).WithContactService(&contactServiceMock{adminErr: errors.New("admin check boom")})
+		resp, _ := makeApp(h).Test(httpTestReq(http.MethodGet, "/list"))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 when admin check fails, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestDULHandler_ValidationAndHelpers(t *testing.T) {
+	svc := &dulServiceMock{createErr: errors.New("boom"), getResult: nil}
+	h := NewDULHandler(svc)
+	app := newDULApp(h)
+
+	resp, body := doReqDUL(t, app, http.MethodPost, "/api/v1/dul/create", []byte(`{`))
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 invalid json, got %d", resp.StatusCode)
+	}
+	errs, _ := body["errors"].([]any)
+	if len(errs) == 0 {
+		t.Fatalf("expected error payload")
+	}
+
+	if _, err := parseDULDate("2026-05-25"); err != nil {
+		t.Fatalf("expected valid date")
+	}
+	if _, err := parseDULDate("25-05-2026"); err == nil {
+		t.Fatalf("expected invalid date")
+	}
+
+	code, _ := inferDULErrorCode(fiber.StatusBadRequest, "Invalid JSON", "bad")
+	if code != "DUL_INVALID_JSON" {
+		t.Fatalf("unexpected code: %s", code)
+	}
+	code, _ = inferDULErrorCode(fiber.StatusUnprocessableEntity, "Validation error", "date must use format YYYY-MM-DD")
+	if code != "DUL_DATE_INVALID" {
+		t.Fatalf("unexpected code for date: %s", code)
+	}
+}
+
+func stringsLower(v string) string { return strings.ToLower(v) }
+
+func TestDULHelperFunctions(t *testing.T) {
+	t.Run("constructor chains", func(t *testing.T) {
+		h := NewDULHandler(&dulServiceMock{})
+		h = h.WithBaseService(&baseServiceMock{})
+		h = h.WithContactService(&contactServiceMock{})
+		h = h.WithFileManagerService(nil)
+		h = h.WithFileStorage(nil)
+		if h == nil {
+			t.Fatalf("expected handler not nil")
+		}
+	})
+
+	t.Run("toResource and image mapping", func(t *testing.T) {
+		now := time.Now().UTC()
+		row := &dul.DUL{
+			ID:        uuidv7.MustBytes(),
+			BaseID:    uuidv7.MustBytes(),
+			Name:      "DUL A",
+			Date:      time.Date(2026, 5, 25, 0, 0, 0, 0, time.UTC),
+			CreatedAt: now,
+			UpdatedAt: now,
+			No:        3,
+			Base:      &base.Base{BaseName: "Halim", BaseCategory: base.BaseCategory{Name: "hems"}},
+			Images: []*filemanager.Attachment{
+				{ID: uuidv7.MustBytes()},
+				nil,
+			},
+		}
+		res := NewDULHandler(&dulServiceMock{}).toResource(row)
+		if res.Type != "dul" || res.Attributes.Base.Name != "Halim" || len(res.Attributes.Images) != 1 {
+			t.Fatalf("unexpected mapped resource")
+		}
+	})
+
+	t.Run("inferDULErrorCode branches", func(t *testing.T) {
+		cases := []struct {
+			status int
+			title  string
+			detail string
+		}{
+			{fiber.StatusNotFound, "", ""},
+			{fiber.StatusUnprocessableEntity, "Validation error", "date invalid"},
+			{fiber.StatusUnprocessableEntity, "Validation error", "invalid uuid"},
+			{fiber.StatusUnprocessableEntity, "Validation error", "something"},
+			{fiber.StatusBadRequest, "Invalid JSON", ""},
+			{fiber.StatusBadRequest, "Create failed", ""},
+			{fiber.StatusBadRequest, "Update failed", ""},
+			{fiber.StatusBadRequest, "Delete failed", ""},
+			{fiber.StatusBadRequest, "List failed", ""},
+			{fiber.StatusInternalServerError, "", ""},
+		}
+		for _, tc := range cases {
+			code, errCode := inferDULErrorCode(tc.status, tc.title, tc.detail)
+			if strings.TrimSpace(code) == "" || strings.TrimSpace(errCode) == "" {
+				t.Fatalf("expected code for status=%d title=%q", tc.status, tc.title)
+			}
+		}
+	})
+
+	t.Run("isPilotRoleContact and parseDULBaseIDsFromRaw", func(t *testing.T) {
+		if isPilotRoleContact(nil) {
+			t.Fatalf("nil item should be false")
+		}
+		item := &contact.ContactListItem{RoleCode: "pilot"}
+		if !isPilotRoleContact(item) {
+			t.Fatalf("role_code pilot should be true")
+		}
+		rawRoles := "x|y|doctor," + mustRoleRawContact(t, uuidv7.MustBytes(), "Pilot", "pilot")
+		item2 := &contact.ContactListItem{RolesRaw: &rawRoles}
+		if !isPilotRoleContact(item2) {
+			t.Fatalf("roles raw pilot should be true")
+		}
+
+		baseID := uuidv7.MustBytes()
+		baseHex := stringsLower(hex.EncodeToString(baseID))
+		nameHex := stringsLower(hex.EncodeToString([]byte("Base A")))
+		raw := baseHex + "|" + nameHex + "|dul," + baseHex + "|" + nameHex + "|dul"
+		ids, set := parseDULBaseIDsFromRaw(&raw)
+		if len(ids) != 1 || len(set) != 1 {
+			t.Fatalf("expected deduped dul base ids")
+		}
+		bad := "invalid"
+		ids, set = parseDULBaseIDsFromRaw(&bad)
+		if len(ids) != 0 || len(set) != 0 {
+			t.Fatalf("invalid raw should produce empty ids")
+		}
+	})
+
+	t.Run("syncImages branches", func(t *testing.T) {
+		dulID := uuidv7.MustBytes()
+		existingID := uuidv7.MustBytes()
+		newFileID := uuidv7.MustBytes()
+		newAttachmentID := uuidv7.MustBytes()
+		created := 0
+
+		mock := &fileManagerAttachmentHandlerServiceMock{
+			listAttachmentsFn: func(context.Context, filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error) {
+				return []filemanager.Attachment{{ID: existingID}}, 1, nil
+			},
+			deleteAttachmentFn: func(context.Context, []byte) error { return nil },
+			getAttachmentFn: func(_ context.Context, _ []byte) (*filemanager.Attachment, error) {
+				return &filemanager.Attachment{ID: newAttachmentID, FileID: newFileID}, nil
+			},
+			createAttachmentFn: func(context.Context, filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+				created++
+				return &filemanager.Attachment{ID: uuidv7.MustBytes()}, nil
+			},
+		}
+		h := NewDULHandler(&dulServiceMock{}).WithFileManagerService(mock)
+
+		app := fiber.New()
+		app.Get("/ok", func(c *fiber.Ctx) error {
+			c.Locals("user_id", uuidv7.MustBytes())
+			raw := mustUUIDStringContact(t, newAttachmentID)
+			if err := h.syncImages(c, dulID, []string{raw}); err != nil {
+				t.Fatalf("unexpected syncImages err: %v", err)
+			}
+			return nil
+		})
+		resp, err := app.Test(httpTestReq(http.MethodGet, "/ok"))
+		if err != nil || resp.StatusCode != http.StatusOK || created != 1 {
+			t.Fatalf("syncImages success not executed")
+		}
+
+		app2 := fiber.New()
+		app2.Get("/bad", func(c *fiber.Ctx) error {
+			err := h.syncImages(c, dulID, []string{"bad-uuid"})
+			if err == nil {
+				t.Fatalf("expected invalid uuid error")
+			}
+			return nil
+		})
+		if _, err := app2.Test(httpTestReq(http.MethodGet, "/bad")); err != nil {
+			t.Fatalf("unexpected app2 err: %v", err)
+		}
+
+		t.Run("resubmit existing attachment uuid on update", func(t *testing.T) {
+			// FE pulls the DUL via GET (which returns image.uuid = attachment id),
+			// then PATCHes back the same uuid in image_attachment_ids. The bug we
+			// fixed deleted the attachment first, then could not resolve the now-gone
+			// uuid back to a file id and returned "image_attachment_ids[0] not found".
+			existingAttID := uuidv7.MustBytes()
+			existingFileID := uuidv7.MustBytes()
+			deletedIDs := make([][]byte, 0, 1)
+			createCalls := make([]filemanager.CreateAttachmentParams, 0, 1)
+			lookupOrder := make([]string, 0, 2)
+
+			mock := &fileManagerAttachmentHandlerServiceMock{
+				listAttachmentsFn: func(context.Context, filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error) {
+					lookupOrder = append(lookupOrder, "list")
+					return []filemanager.Attachment{{ID: existingAttID, FileID: existingFileID}}, 1, nil
+				},
+				deleteAttachmentFn: func(_ context.Context, id []byte) error {
+					lookupOrder = append(lookupOrder, "delete")
+					deletedIDs = append(deletedIDs, append([]byte(nil), id...))
+					return nil
+				},
+				getAttachmentFn: func(_ context.Context, id []byte) (*filemanager.Attachment, error) {
+					lookupOrder = append(lookupOrder, "getAtt")
+					if bytes.Equal(id, existingAttID) {
+						return &filemanager.Attachment{ID: existingAttID, FileID: existingFileID}, nil
+					}
+					return nil, nil
+				},
+				getFileFn: func(_ context.Context, _ []byte) (*filemanager.File, error) {
+					lookupOrder = append(lookupOrder, "getFile")
+					return nil, nil
+				},
+				createAttachmentFn: func(_ context.Context, p filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+					lookupOrder = append(lookupOrder, "create")
+					createCalls = append(createCalls, p)
+					return &filemanager.Attachment{ID: uuidv7.MustBytes(), FileID: append([]byte(nil), p.FileID...)}, nil
+				},
+			}
+			h := NewDULHandler(&dulServiceMock{}).WithFileManagerService(mock)
+			dulID := uuidv7.MustBytes()
+
+			app := fiber.New()
+			app.Get("/resubmit", func(c *fiber.Ctx) error {
+				c.Locals("user_id", uuidv7.MustBytes())
+				raw := mustUUIDStringContact(t, existingAttID)
+				if err := h.syncImages(c, dulID, []string{raw}); err != nil {
+					t.Fatalf("syncImages must succeed when resubmitting existing attachment uuid: %v", err)
+				}
+				return nil
+			})
+			resp, err := app.Test(httpTestReq(http.MethodGet, "/resubmit"))
+			if err != nil || resp.StatusCode != http.StatusOK {
+				t.Fatalf("unexpected resubmit response: err=%v status=%d", err, resp.StatusCode)
+			}
+			if len(createCalls) != 1 {
+				t.Fatalf("expected exactly one CreateAttachment call, got %d", len(createCalls))
+			}
+			if !bytes.Equal(createCalls[0].FileID, existingFileID) {
+				t.Fatalf("CreateAttachment must reuse the original file id")
+			}
+			if len(deletedIDs) != 1 || !bytes.Equal(deletedIDs[0], existingAttID) {
+				t.Fatalf("expected existing attachment to be deleted exactly once, got %v", deletedIDs)
+			}
+			// The lookup must happen BEFORE the delete; otherwise GetAttachmentByID
+			// would race with the delete and return nil.
+			getIdx, delIdx := -1, -1
+			for i, step := range lookupOrder {
+				if step == "getAtt" && getIdx == -1 {
+					getIdx = i
+				}
+				if step == "delete" && delIdx == -1 {
+					delIdx = i
+				}
+			}
+			if getIdx == -1 || delIdx == -1 || getIdx > delIdx {
+				t.Fatalf("expected GetAttachmentByID before DeleteAttachment, lookup order=%v", lookupOrder)
+			}
+		})
+
+		t.Run("dedupe resubmitted file ids", func(t *testing.T) {
+			// Sending the same file id twice must not violate the
+			// (ref_type, ref_id, file_id) unique constraint at the attachments table.
+			fileID := uuidv7.MustBytes()
+			createCount := 0
+			mock := &fileManagerAttachmentHandlerServiceMock{
+				listAttachmentsFn: func(context.Context, filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error) {
+					return nil, 0, nil
+				},
+				getAttachmentFn: func(_ context.Context, _ []byte) (*filemanager.Attachment, error) { return nil, nil },
+				getFileFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+					return &filemanager.File{ID: append([]byte(nil), id...), Status: filemanager.FileStatusReady}, nil
+				},
+				createAttachmentFn: func(_ context.Context, _ filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+					createCount++
+					return &filemanager.Attachment{ID: uuidv7.MustBytes()}, nil
+				},
+			}
+			h := NewDULHandler(&dulServiceMock{}).WithFileManagerService(mock)
+			dulID := uuidv7.MustBytes()
+			app := fiber.New()
+			app.Get("/dedupe", func(c *fiber.Ctx) error {
+				c.Locals("user_id", uuidv7.MustBytes())
+				raw := mustUUIDStringContact(t, fileID)
+				if err := h.syncImages(c, dulID, []string{raw, raw}); err != nil {
+					t.Fatalf("unexpected err on duplicate ids: %v", err)
+				}
+				return nil
+			})
+			if _, err := app.Test(httpTestReq(http.MethodGet, "/dedupe")); err != nil {
+				t.Fatalf("unexpected dedupe err: %v", err)
+			}
+			if createCount != 1 {
+				t.Fatalf("duplicate ids must collapse to one CreateAttachment call, got %d", createCount)
+			}
+		})
+
+		t.Run("accept file uuid fallback", func(t *testing.T) {
+			createdFallback := 0
+			mockFallback := &fileManagerAttachmentHandlerServiceMock{
+				listAttachmentsFn: func(context.Context, filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error) {
+					return nil, 0, nil
+				},
+				getAttachmentFn: func(_ context.Context, _ []byte) (*filemanager.Attachment, error) {
+					return nil, nil
+				},
+				getFileFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+					return &filemanager.File{ID: append([]byte(nil), id...), Status: filemanager.FileStatusReady}, nil
+				},
+				createAttachmentFn: func(_ context.Context, p filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+					createdFallback++
+					return &filemanager.Attachment{ID: uuidv7.MustBytes(), FileID: append([]byte(nil), p.FileID...)}, nil
+				},
+			}
+			hFallback := NewDULHandler(&dulServiceMock{}).WithFileManagerService(mockFallback)
+			appFallback := fiber.New()
+			appFallback.Get("/file-fallback", func(c *fiber.Ctx) error {
+				c.Locals("user_id", uuidv7.MustBytes())
+				raw := mustUUIDStringContact(t, newFileID)
+				if err := hFallback.syncImages(c, dulID, []string{raw}); err != nil {
+					t.Fatalf("unexpected fallback err: %v", err)
+				}
+				return nil
+			})
+			respFallback, err := appFallback.Test(httpTestReq(http.MethodGet, "/file-fallback"))
+			if err != nil || respFallback.StatusCode != http.StatusOK || createdFallback != 1 {
+				t.Fatalf("fallback path not executed")
+			}
+		})
+	})
+}
+
+func TestDULEventsStream(t *testing.T) {
+	hub := filemanagerrealtime.NewHub(1, nil)
+	actor := uuidv7.MustBytes()
+	userUUID, _ := uuidv7.BytesToString(actor)
+
+	app := fiber.New()
+	fctx := &fasthttp.RequestCtx{}
+	fctx.Request.SetRequestURI("/api/v1/dul/events")
+	c := app.AcquireCtx(fctx)
+	c.Locals("user_id", actor)
+	if err := NewFileManagerEventsHandler(hub).Stream(c); err != nil {
+		t.Fatalf("unexpected stream setup error: %v", err)
+	}
+
+	hub.PublishToUsers([]string{userUUID}, filemanagerrealtime.FileStatusEvent{
+		FileUUID:  mustUUIDStringContact(t, uuidv7.MustBytes()),
+		Status:    "ready",
+		Name:      "dul-image.png",
+		MimeType:  "image/png",
+		UpdatedAt: time.Now().UTC().Format(time.RFC3339),
+	})
+	go func() {
+		time.Sleep(10 * time.Millisecond)
+		closeFirstHubSubscriberForUser(hub, userUUID)
+	}()
+
+	bodyStr := c.Context().Response.String()
+	app.ReleaseCtx(c)
+	if !strings.Contains(bodyStr, ": connected") {
+		t.Fatalf("expected connected comment in body: %q", bodyStr)
+	}
+	if !strings.Contains(bodyStr, "event: file.updated") {
+		t.Fatalf("expected file.updated event in body: %q", bodyStr)
+	}
+	if !strings.Contains(bodyStr, "\"file_id\"") || !strings.Contains(bodyStr, "\"status\":\"ready\"") {
+		t.Fatalf("expected file.updated payload in body: %q", bodyStr)
+	}
+}
+
+func httpTestReq(method, path string) *http.Request {
+	req, _ := http.NewRequest(method, path, nil)
+	return req
+}
diff --git a/internal/transport/http/handlers/duty_roster_handler.go b/internal/transport/http/handlers/duty_roster_handler.go
new file mode 100644
index 0000000..4b18812
--- /dev/null
+++ b/internal/transport/http/handlers/duty_roster_handler.go
@@ -0,0 +1,2388 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	dutyroster "wucher/internal/domain/duty_roster"
+	"wucher/internal/domain/flight"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	dto "wucher/internal/transport/http/dto"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type DutyRosterHandler struct {
+	svc      dutyroster.Service
+	flight   flight.FlightService
+	validate *validators.Validator
+	audit    *service.AuditLogService
+}
+
+var _ responsedto.DutyRosterResponse
+var _ dto.ErrorResponse
+var _ dto.GenericDeleteResponse
+
+type rosterFlightMeta struct {
+	FlightID   string
+	Helicopter responsedto.DutyRosterHelicopterSummary
+}
+
+func toCoreDutyRosterDetailsInput(in requestdto.DutyRosterDetailsInput) requestdto.DutyRosterDetailsInput {
+	out := requestdto.DutyRosterDetailsInput{
+		Pilot:       make([]requestdto.DutyRosterPilotCrewInput, 0, len(in.Pilot)),
+		Doctor:      make([]requestdto.DutyRosterCrewInput, 0, len(in.Doctor)),
+		Rescuer:     make([]requestdto.DutyRosterCrewInput, 0, len(in.Rescuer)),
+		Helper:      make([]requestdto.DutyRosterCrewInput, 0, len(in.Helper)),
+		OtherPerson: make([]requestdto.DutyRosterOtherPersonInput, 0, len(in.OtherPerson)),
+	}
+	for i := range in.Pilot {
+		out.Pilot = append(out.Pilot, requestdto.DutyRosterPilotCrewInput{
+			ID:               in.Pilot[i].ID,
+			ShiftDate:        toCoreShiftDatePtr(in.Pilot[i].ShiftDate),
+			FlightInstructor: in.Pilot[i].FlightInstructor,
+			LineChecker:      in.Pilot[i].LineChecker,
+			Supervisor:       in.Pilot[i].Supervisor,
+			Examiner:         in.Pilot[i].Examiner,
+			CoPilot:          in.Pilot[i].CoPilot,
+			CrewType:         in.Pilot[i].CrewType,
+		})
+	}
+	for i := range in.Doctor {
+		out.Doctor = append(out.Doctor, toCoreCrewInput(in.Doctor[i]))
+	}
+	for i := range in.Rescuer {
+		out.Rescuer = append(out.Rescuer, toCoreCrewInput(in.Rescuer[i]))
+	}
+	for i := range in.Helper {
+		out.Helper = append(out.Helper, toCoreCrewInput(in.Helper[i]))
+	}
+	for i := range in.OtherPerson {
+		out.OtherPerson = append(out.OtherPerson, requestdto.DutyRosterOtherPersonInput{
+			Name:        in.OtherPerson[i].Name,
+			MobilePhone: in.OtherPerson[i].MobilePhone,
+			Email:       in.OtherPerson[i].Email,
+		})
+	}
+	return out
+}
+
+func toCoreDutyRosterDetailsInputPtr(in *requestdto.DutyRosterDetailsInput) *requestdto.DutyRosterDetailsInput {
+	if in == nil {
+		return nil
+	}
+	out := toCoreDutyRosterDetailsInput(*in)
+	return &out
+}
+
+func toCoreCrewInput(in requestdto.DutyRosterCrewInput) requestdto.DutyRosterCrewInput {
+	return requestdto.DutyRosterCrewInput{
+		ID:        in.ID,
+		ShiftDate: toCoreShiftDatePtr(in.ShiftDate),
+	}
+}
+
+func toCoreShiftDatePtr(in *requestdto.DutyRosterShiftDate) *requestdto.DutyRosterShiftDate {
+	if in == nil {
+		return nil
+	}
+	return &requestdto.DutyRosterShiftDate{
+		DateStart: in.DateStart,
+		DateEnd:   in.DateEnd,
+	}
+}
+
+func NewDutyRosterHandler(svc dutyroster.Service) *DutyRosterHandler {
+	return &DutyRosterHandler{svc: svc, validate: validators.New()}
+}
+
+func (h *DutyRosterHandler) WithAudit(auditSvc *service.AuditLogService) *DutyRosterHandler {
+	h.audit = auditSvc
+	return h
+}
+
+func (h *DutyRosterHandler) WithFlightService(flightSvc flight.FlightService) *DutyRosterHandler {
+	h.flight = flightSvc
+	return h
+}
+
+// CreateDutyRoster godoc
+// @Summary Create HEMS duty roster
+// @Description Create roster by `hems_base_id` and `duty_date`.
+// @Description HEMS endpoints use `hems_base_id` in request and `hems_bases` in response attributes.
+// @Description Time input accepts `HH:MM` or `HH:MM:SS` and is normalized.
+// @Description `roster_detail` buckets: `pilot`, `doctor`, `rescuer`, `helper`, `other_person`.
+// @Description For pilot: `crew_type` can be `main` or `additional`.
+// @Description Pilot flags (`flight_instructor`, `line_checker`, `supervisor`, `examiner`, `co_pilot`) are only applied when `crew_type=additional`; for `main` they are ignored.
+// @Description For doctor/rescuer/helper, `crew_type` is always treated as `main`.
+// @Description For `other_person`, `id` must be empty and `name` is required.
+// @Description If roster shift_time is omitted, system uses base default shift when available.
+// @Description `data.type` should be `duty_roster_create` (or `duty_roster`). Legacy `hems_duty_roster_create`/`hems_duty_roster` is still accepted for backward compatibility.
+// @Tags Flights - HEMS Duty Roster
+// @Accept json
+// @Produce json
+// @Param request body requestdto.DutyRosterCreateRequest true "Create request payload"
+// @Success 201 {object} responsedto.DutyRosterResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/hems-roster/create
+func (h *DutyRosterHandler) Create(c *fiber.Ctx) error {
+	var req requestdto.DutyRosterCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	baseID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.BaseID))
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "base_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/base_id"},
+		}})
+	}
+	dutyDate, err := service.ParseDutyRosterDateOnly(req.Data.Attributes.DutyDate)
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "duty_date must be YYYY-MM-DD",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/duty_date"},
+		}})
+	}
+
+	row := &dutyroster.DutyRoster{
+		BaseID:    baseID,
+		DutyDate:  dutyDate,
+		CreatedBy: actorUserID(c),
+		UpdatedBy: actorUserID(c),
+	}
+	defaultShiftStart, defaultShiftEnd, err := h.svc.ResolveBaseDefaultShiftRange(c.UserContext(), baseID, "hems")
+	if err != nil {
+		if wrote := h.writeBaseTypeValidationError(c, err, baseID, "hems", "/data/attributes/base_id"); wrote {
+			return nil
+		}
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	rowShiftStart, shiftErr := service.NormalizeDutyRosterClockInput(req.Data.Attributes.ShiftTime.ShiftStart, defaultShiftStart, "/data/attributes/shift_time/shift_start")
+	if shiftErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: shiftErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: shiftErr.Pointer},
+		}})
+	}
+	rowShiftEnd, shiftErr := service.NormalizeDutyRosterClockInput(req.Data.Attributes.ShiftTime.ShiftEnd, defaultShiftEnd, "/data/attributes/shift_time/shift_end")
+	if shiftErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: shiftErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: shiftErr.Pointer},
+		}})
+	}
+	_ = rowShiftStart
+	_ = rowShiftEnd
+	detail := toCoreDutyRosterDetailsInput(req.Data.Attributes.Detail)
+	crews, crewErr := service.BuildDutyRosterCrewRows(detail, actorUserID(c))
+	if crewErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: crewErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: crewErr.Pointer},
+		}})
+	}
+	clearCrewShiftDateForCreate(crews)
+
+	if err := h.svc.Create(c.UserContext(), row, crews); err != nil {
+		status, errObj := buildServiceErrorObject("Create failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	return h.respondByID(c, fiber.StatusCreated, row.ID)
+}
+
+// GetDutyRoster godoc
+// @Summary Get HEMS duty roster by UUID
+// @Tags Flights - HEMS Duty Roster
+// @Produce json
+// @Param uuid path string true "Roster UUID"
+// @Success 200 {object} responsedto.DutyRosterResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/hems-roster/get/{uuid}
+func (h *DutyRosterHandler) Get(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(dutyRosterPathID(c))
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	header, err := h.svc.GetHeaderByID(c.UserContext(), id)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if header != nil {
+		return h.respondByID(c, fiber.StatusOK, id)
+	}
+
+	// Backward-compatible fallback: allow :uuid as flight_uuid.
+	if h.flight != nil {
+		flightRow, flightErr := h.flight.GetByID(c.UserContext(), id)
+		if flightErr != nil {
+			status, errObj := buildServiceErrorObject("Get failed", flightErr, "")
+			return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+		}
+		if flightRow != nil && len(flightRow.DutyRosterID) == 16 {
+			return h.respondByID(c, fiber.StatusOK, flightRow.DutyRosterID)
+		}
+	}
+
+	return writeDutyRosterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+		Status: "404",
+		Title:  "Not found",
+		Detail: "hems duty roster not found",
+	}})
+}
+
+func (h *DutyRosterHandler) GetByAuthUser(c *fiber.Ctx) error {
+	userID := actorUserID(c)
+	if len(userID) == 0 {
+		return writeDutyRosterErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+	rosterID, err := h.findLatestRosterIDByUser(c.UserContext(), userID, "hems")
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if len(rosterID) != 16 {
+		return writeDutyRosterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "hems duty roster not found",
+		}})
+	}
+	return h.respondByID(c, fiber.StatusOK, rosterID)
+}
+
+// GetRosterByAuthUser godoc
+// @Summary Get latest roster for current auth user (HEMS/Base)
+// @Description Resolve latest roster linked to the authenticated user from flight assignments.
+// @Tags Flights - Duty Roster
+// @Produce json
+// @Success 200 {object} jsonapi.Document
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 500 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/duty-roster/get
+func (h *DutyRosterHandler) GetRosterByAuthUser(c *fiber.Ctx) error {
+	userID := actorUserID(c)
+	if len(userID) == 0 {
+		return writeDutyRosterErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+	if h.flight == nil {
+		return writeDutyRosterErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Get failed",
+			Detail: "flight service is not configured",
+		}})
+	}
+
+	rows, _, err := h.flight.ListByUserID(c.UserContext(), userID, 100, 0)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+
+	rosterIDs := make([][]byte, 0, len(rows))
+	seenRoster := make(map[string]struct{}, len(rows))
+	flightByRoster := make(map[string]rosterFlightMeta, len(rows))
+	for i := range rows {
+		if len(rows[i].DutyRosterID) != 16 {
+			continue
+		}
+		rosterKey := idString(rows[i].DutyRosterID)
+		if rosterKey == "" {
+			continue
+		}
+		if _, seen := seenRoster[rosterKey]; !seen {
+			seenRoster[rosterKey] = struct{}{}
+			rosterIDs = append(rosterIDs, append([]byte(nil), rows[i].DutyRosterID...))
+		}
+		next := rosterFlightMeta{
+			FlightID:   idString(rows[i].ID),
+			Helicopter: buildRosterHelicopter(rows[i]),
+		}
+		prev, exists := flightByRoster[rosterKey]
+		if !exists || shouldReplaceRosterFlightMeta(prev, next) {
+			flightByRoster[rosterKey] = next
+		}
+	}
+	if len(rosterIDs) == 0 {
+		return response.WriteWithMeta(c, fiber.StatusOK, []any{}, map[string]any{"total": 0})
+	}
+
+	crews, err := h.svc.GetCrewsByRosterIDs(c.UserContext(), rosterIDs)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	crewsByRoster := map[string][]dutyroster.CrewView{}
+	for i := range crews {
+		k := idString(crews[i].RosterID)
+		if k == "" {
+			continue
+		}
+		crewsByRoster[k] = append(crewsByRoster[k], crews[i])
+	}
+
+	data := make([]any, 0, len(rosterIDs))
+	for i := range rosterIDs {
+		rosterID := rosterIDs[i]
+		rosterKey := idString(rosterID)
+		rosterCrews := crewsByRoster[rosterKey]
+
+		headerHEMS, getErr := h.svc.GetHeaderByID(c.UserContext(), rosterID)
+		if getErr != nil {
+			status, errObj := buildServiceErrorObject("Get failed", getErr, "")
+			return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+		}
+		if headerHEMS != nil {
+			resource := dutyRosterResource(c.UserContext(), *headerHEMS, rosterCrews, "hems")
+			if flightMeta, ok := flightByRoster[rosterKey]; ok {
+				if strings.TrimSpace(flightMeta.FlightID) != "" {
+					resource.Attributes.FlightID = strings.TrimSpace(flightMeta.FlightID)
+				}
+				if !isEmptyRosterHelicopter(flightMeta.Helicopter) {
+					resource.Attributes.Helicopter = flightMeta.Helicopter
+				}
+			}
+			data = append(data, resource)
+			continue
+		}
+
+		headerBase, getErr := h.svc.GetHeaderByIDByBaseType(c.UserContext(), rosterID, "base")
+		if getErr != nil {
+			status, errObj := buildServiceErrorObject("Get failed", getErr, "")
+			return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+		}
+		if headerBase != nil {
+			resource := dutyRosterResource(c.UserContext(), *headerBase, rosterCrews, "base")
+			if flightMeta, ok := flightByRoster[rosterKey]; ok {
+				if strings.TrimSpace(flightMeta.FlightID) != "" {
+					resource.Attributes.FlightID = strings.TrimSpace(flightMeta.FlightID)
+				}
+				if !isEmptyRosterHelicopter(flightMeta.Helicopter) {
+					resource.Attributes.Helicopter = flightMeta.Helicopter
+				}
+			}
+			data = append(data, resource)
+		}
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{"total": len(data)})
+}
+
+// GetAllRosters godoc
+// @Summary List all rosters (HEMS + Base)
+// @Description Combined roster list across HEMS and Base for date range and optional base filters.
+// @Tags Flights - Duty Roster
+// @Produce json
+// @Param hems_base_id query string false "HEMS base UUID"
+// @Param base_id query string false "Base UUID"
+// @Param base_name query string false "Filter by base name (contains, case-insensitive)"
+// @Param from query string false "Start date (YYYY-MM-DD)"
+// @Param to query string false "End date (YYYY-MM-DD)"
+// @Success 200 {object} jsonapi.Document
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/duty-roster/get-all [get]
+func (h *DutyRosterHandler) GetAllRosters(c *fiber.Ctx) error {
+	hemsBaseRaw := strings.TrimSpace(c.Query("hems_base_id"))
+	baseRaw := strings.TrimSpace(c.Query("base_id"))
+	baseName := strings.TrimSpace(c.Query("base_name"))
+
+	var hemsBaseID []byte
+	if hemsBaseRaw != "" {
+		parsed, err := uuidv7.ParseString(hemsBaseRaw)
+		if err != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "hems_base_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/hems_base_id"},
+			}})
+		}
+		hemsBaseID = parsed
+	}
+
+	var baseID []byte
+	if baseRaw != "" {
+		parsed, err := uuidv7.ParseString(baseRaw)
+		if err != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "base_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/base_id"},
+			}})
+		}
+		baseID = parsed
+	}
+
+	from, to, rangeErr := service.ParseDutyRosterDateRangeOrDefault(c.Query("from"), c.Query("to"), time.Now().UTC())
+	if rangeErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: rangeErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: rangeErr.Pointer},
+		}})
+	}
+	if to.Before(from) {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "to must be >= from",
+			Source: &jsonapi.ErrorSource{Pointer: "/query/to"},
+		}})
+	}
+
+	hemsGroups, err := loadRosterGroups(c.UserContext(), h.svc, hemsBaseID, from, to, baseName, "hems")
+	if err != nil {
+		status, errObj := buildServiceErrorObject("List failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	h.attachFlightIDsToHEMSGroups(c.UserContext(), hemsGroups)
+
+	baseGroups, err := loadRosterGroups(c.UserContext(), h.svc, baseID, from, to, baseName, "base")
+	if err != nil {
+		status, errObj := buildServiceErrorObject("List failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	h.attachFlightIDsToBaseGroups(c.UserContext(), baseGroups)
+
+	return response.WriteWithMeta(c, fiber.StatusOK, map[string]any{
+		"hems": hemsGroups,
+		"base": baseGroups,
+	}, map[string]any{
+		"from":       from.UTC().Format("2006-01-02"),
+		"to":         to.UTC().Format("2006-01-02"),
+		"timezone":   "UTC",
+		"total_hems": len(hemsGroups),
+		"total_base": len(baseGroups),
+		"total":      len(hemsGroups) + len(baseGroups),
+	})
+}
+
+func (h *DutyRosterHandler) GetByFlightID(c *fiber.Ctx) error {
+	flightID, err := uuidv7.ParseString(strings.TrimSpace(dutyRosterPathFlightID(c)))
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "flight_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/flight_id"},
+		}})
+	}
+	if h.flight == nil {
+		return writeDutyRosterErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Get failed",
+			Detail: "flight service is not configured",
+		}})
+	}
+
+	flightRow, err := h.flight.GetByID(c.UserContext(), flightID)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if flightRow == nil {
+		return writeDutyRosterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "flight not found",
+		}})
+	}
+	if len(flightRow.DutyRosterID) != 16 {
+		return writeDutyRosterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "duty roster not linked to flight",
+		}})
+	}
+
+	// Try HEMS format first.
+	header, err := h.svc.GetHeaderByID(c.UserContext(), flightRow.DutyRosterID)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if header != nil {
+		return h.respondByID(c, fiber.StatusOK, flightRow.DutyRosterID)
+	}
+
+	// Fallback to base format.
+	return h.respondByIDBaseType(c, fiber.StatusOK, flightRow.DutyRosterID, "base")
+}
+
+// UpdateDutyRoster godoc
+// @Summary Update HEMS duty roster (partial)
+// @Description Update header fields and/or append/replace crew assignment by role+crew_type+user.
+// @Description `data.id` is optional; if provided it must match path `uuid`.
+// @Description If `roster_detail` is omitted, only header is updated.
+// @Description Crew update is additive by default; same role+crew_type+user in same roster is replaced.
+// @Description For pilot rows, extra flags (`flight_instructor`, `line_checker`, `supervisor`, `examiner`, `co_pilot`) are only applied for `crew_type=additional`.
+// @Description `data.type` should be `duty_roster_update` (or `duty_roster`). Legacy `hems_duty_roster_update`/`hems_duty_roster` is still accepted for backward compatibility.
+// @Tags Flights - HEMS Duty Roster
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Roster UUID"
+// @Param request body requestdto.DutyRosterUpdateRequest true "Update request payload"
+// @Success 200 {object} responsedto.DutyRosterResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/hems-roster/update/{uuid}
+func (h *DutyRosterHandler) Update(c *fiber.Ctx) error {
+	var req requestdto.DutyRosterUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	uuidStr := strings.TrimSpace(dutyRosterPathID(c))
+	bodyID := strings.TrimSpace(req.Data.ID)
+	if uuidStr == "" && bodyID == "" {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if uuidStr != "" && bodyID != "" && bodyID != uuidStr {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path id",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	targetID := bodyID
+	if targetID == "" {
+		targetID = uuidStr
+	}
+	id, err := h.resolveDutyRosterIDFromInput(c, targetID)
+	if err != nil {
+		sourcePtr := "/data/id"
+		if targetID == uuidStr && uuidStr != "" && bodyID == "" {
+			sourcePtr = "/path/id"
+		}
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: safeInternalDetail(),
+			Source: &jsonapi.ErrorSource{Pointer: sourcePtr},
+		}})
+	}
+
+	existing, err := h.svc.GetHeaderByID(c.UserContext(), id)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if existing == nil {
+		return writeDutyRosterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "hems duty roster not found",
+		}})
+	}
+
+	row := &dutyroster.DutyRoster{ID: id, BaseID: append([]byte(nil), existing.BaseID...), DutyDate: existing.DutyDate, UpdatedBy: actorUserID(c)}
+	attrs := req.Data.Attributes
+	if attrs.BaseID != nil && strings.TrimSpace(*attrs.BaseID) != "" {
+		baseID, err := uuidv7.ParseString(strings.TrimSpace(*attrs.BaseID))
+		if err != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "hems_base_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/hems_base_id"},
+			}})
+		}
+		row.BaseID = baseID
+	}
+	if attrs.DutyDate != nil && strings.TrimSpace(*attrs.DutyDate) != "" {
+		d, err := service.ParseDutyRosterDateOnly(*attrs.DutyDate)
+		if err != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "duty_date must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/duty_date"},
+			}})
+		}
+		row.DutyDate = d
+	}
+	if attrs.ShiftTime != nil {
+		defaultShiftStart, defaultShiftEnd, err := service.ResolveDutyRosterShiftDefaultsForUpdate(c.UserContext(), h.svc, row.BaseID, "hems", "", "")
+		if err != nil {
+			status, errObj := buildServiceErrorObject("Get failed", err, "")
+			return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+		}
+		shiftStart, shiftErr := service.NormalizeDutyRosterClockInput(attrs.ShiftTime.ShiftStart, defaultShiftStart, "/data/attributes/shift_time/shift_start")
+		if shiftErr != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: shiftErr.Detail,
+				Source: &jsonapi.ErrorSource{Pointer: shiftErr.Pointer},
+			}})
+		}
+		shiftEnd, shiftErr := service.NormalizeDutyRosterClockInput(attrs.ShiftTime.ShiftEnd, defaultShiftEnd, "/data/attributes/shift_time/shift_end")
+		if shiftErr != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: shiftErr.Detail,
+				Source: &jsonapi.ErrorSource{Pointer: shiftErr.Pointer},
+			}})
+		}
+		_ = shiftStart
+		_ = shiftEnd
+	}
+	crews := []dutyroster.DutyRosterCrew{}
+	if detail := toCoreDutyRosterDetailsInputPtr(attrs.Detail); detail != nil {
+		built, crewErr := service.BuildDutyRosterCrewRows(*detail, actorUserID(c))
+		if crewErr != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: crewErr.Detail,
+				Source: &jsonapi.ErrorSource{Pointer: crewErr.Pointer},
+			}})
+		}
+		crews = built
+	}
+	if err := h.svc.Update(c.UserContext(), row, crews); err != nil {
+		status, errObj := buildServiceErrorObject("Update failed", err, "hems duty roster not found")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	h.logCrewAudit(c, "duty_roster.crew.append", id, "hems", crews, "append crew assignments")
+	return h.respondByID(c, fiber.StatusOK, id)
+}
+
+// DeleteDutyRoster godoc
+// @Summary Delete HEMS duty roster
+// @Description Delete one roster header and all attached crews by roster UUID.
+// @Tags Flights - HEMS Duty Roster
+// @Produce json
+// @Param uuid path string true "Roster UUID"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/hems-roster/delete/{uuid}
+func (h *DutyRosterHandler) Delete(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(dutyRosterPathID(c))
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		status, errObj := buildServiceErrorObject("Delete failed", err, "hems duty roster not found")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "duty_roster_delete", Attributes: map[string]any{"deleted": true}})
+}
+
+// DeleteDutyRosterCrew godoc
+// @Summary Remove crew assignment from HEMS duty roster
+// @Description Remove selected crew rows from roster UUID by filter in `roster_detail`.
+// @Description This endpoint removes crew only; header roster stays.
+// @Description For operational roles (pilot/doctor/rescuer/helper), if one `shift_date` boundary is sent then both are required.
+// @Description If `shift_date` is omitted, filter applies to roster day only.
+// @Description `data.type` should be `duty_roster_crew_delete` (also accepts `duty_roster_update`/`duty_roster` and legacy `hems_*` variants).
+// @Tags Flights - HEMS Duty Roster
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Roster UUID"
+// @Param request body requestdto.DutyRosterDeleteCrewRequest true "Crew delete filter payload (use `roster_detail`)"
+// @Success 200 {object} responsedto.DutyRosterCrewDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/hems-roster/{uuid}/crew
+func (h *DutyRosterHandler) DeleteCrew(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(dutyRosterPathID(c))
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+	crews, parseErr := service.BuildDutyRosterDeleteCrews(c.Body(), actorUserID(c))
+	if parseErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: parseErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: parseErr.Pointer},
+		}})
+	}
+	if len(crews) == 0 {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "roster_detail is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/roster_detail"},
+		}})
+	}
+	deletedRows, err := h.svc.DeleteCrews(c.UserContext(), id, crews, actorUserID(c))
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Delete failed", err, "hems duty roster not found")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if len(deletedRows) == 0 {
+		return writeDutyRosterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "no crew assignment matched delete filter",
+		}})
+	}
+	h.logCrewAudit(c, "duty_roster.crew.remove", id, "hems", crews, "remove crew assignments")
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "duty_roster_crew_delete", Attributes: map[string]any{"deleted": true, "deleted_count": len(deletedRows), "deleted_items": dutyRosterDeletedCrewItems(deletedRows)}})
+}
+
+// ListDutyRoster godoc
+// @Summary List HEMS duty roster
+// @Description Grouped by base. Includes empty bases with `rosters: []`.
+// @Description Query: `hems_base_id` (optional), `base_name` (optional), `from` and `to` (`YYYY-MM-DD`, optional).
+// @Description Response grouping key is `attributes.hems_bases`.
+// @Tags Flights - HEMS Duty Roster
+// @Produce json
+// @Param hems_base_id query string false "HEMS base UUID"
+// @Param base_name query string false "Filter by HEMS base name (contains, case-insensitive)"
+// @Param from query string false "Start date (YYYY-MM-DD)"
+// @Param to query string false "End date (YYYY-MM-DD)"
+// @Success 200 {object} responsedto.DutyRosterGroupedListResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/hems-roster/get-all
+func (h *DutyRosterHandler) List(c *fiber.Ctx) error {
+	hemsBaseRaw := strings.TrimSpace(c.Query("hems_base_id"))
+	var baseID []byte
+	var err error
+	if hemsBaseRaw != "" {
+		baseID, err = uuidv7.ParseString(hemsBaseRaw)
+		if err != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "hems_base_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/hems_base_id"},
+			}})
+		}
+	}
+	from, to, rangeErr := service.ParseDutyRosterDateRangeOrDefault(c.Query("from"), c.Query("to"), time.Now().UTC())
+	if rangeErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: rangeErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: rangeErr.Pointer},
+		}})
+	}
+	if to.Before(from) {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "to must be >= from",
+			Source: &jsonapi.ErrorSource{Pointer: "/query/to"},
+		}})
+	}
+	baseName := strings.TrimSpace(c.Query("base_name"))
+
+	grouped, err := loadRosterGroups(c.UserContext(), h.svc, baseID, from, to, baseName, "hems")
+	if err != nil {
+		status, errObj := buildServiceErrorObject("List failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	h.attachFlightIDsToHEMSGroups(c.UserContext(), grouped)
+	return response.WriteWithMeta(c, fiber.StatusOK, grouped, map[string]any{"from": from.UTC().Format("2006-01-02"), "to": to.UTC().Format("2006-01-02"), "timezone": "UTC", "total_bases": len(grouped)})
+}
+
+// ListDutyRosterDatatable godoc
+// @Summary List HEMS duty roster (datatable)
+// @Description Datatable format with grouped rows and pagination metadata.
+// @Description Query: `hems_base_id`, `base_name`, `from`, `to`, `page`, `size`, `limit`, `draw`.
+// @Description Response grouping key is `attributes.hems_bases`.
+// @Tags Flights - HEMS Duty Roster
+// @Produce json
+// @Param hems_base_id query string false "HEMS base UUID"
+// @Param base_name query string false "Filter by HEMS base name (contains, case-insensitive)"
+// @Param from query string false "Start date (YYYY-MM-DD)"
+// @Param to query string false "End date (YYYY-MM-DD)"
+// @Param page query int false "Page number"
+// @Param size query int false "Page size"
+// @Param limit query int false "Page size override"
+// @Param draw query int false "Draw counter"
+// @Success 200 {object} responsedto.DutyRosterGroupedDataTableResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/hems-roster/get-all/dt
+func (h *DutyRosterHandler) ListDatatable(c *fiber.Ctx) error {
+	hemsBaseRaw := strings.TrimSpace(c.Query("hems_base_id"))
+	var baseID []byte
+	var err error
+	if hemsBaseRaw != "" {
+		baseID, err = uuidv7.ParseString(hemsBaseRaw)
+		if err != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "hems_base_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/hems_base_id"},
+			}})
+		}
+	}
+	from, to, rangeErr := service.ParseDutyRosterDateRangeOrDefault(c.Query("from"), c.Query("to"), time.Now().UTC())
+	if rangeErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: rangeErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: rangeErr.Pointer},
+		}})
+	}
+	if to.Before(from) {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "to must be >= from",
+			Source: &jsonapi.ErrorSource{Pointer: "/query/to"},
+		}})
+	}
+	baseName := strings.TrimSpace(c.Query("base_name"))
+
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+
+	grouped, err := loadRosterGroups(c.UserContext(), h.svc, baseID, from, to, baseName, "hems")
+	if err != nil {
+		status, errObj := buildServiceErrorObject("List failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	h.attachFlightIDsToHEMSGroups(c.UserContext(), grouped)
+	pagedGroups, total := paginateRosterGroups(grouped, start, length)
+	meta := map[string]any{"draw": draw, "records_total": total, "records_filtered": total, "from": from.UTC().Format("2006-01-02"), "to": to.UTC().Format("2006-01-02"), "timezone": "UTC"}
+	return response.WriteWithMeta(c, fiber.StatusOK, pagedGroups, meta)
+}
+
+// CreateDutyRosterUnified godoc
+// @Summary Create duty roster
+// @Description Unified endpoint for all base categories.
+// @Tags Flights - Duty Roster
+// @Accept json
+// @Produce json
+// @Param request body requestdto.DutyRosterCreateRequest true "Create request payload"
+// @Success 201 {object} responsedto.DutyRosterResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/duty-roster/create [post]
+func (h *DutyRosterHandler) CreateAny(c *fiber.Ctx) error {
+	var req requestdto.DutyRosterCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	baseID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.BaseID))
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "base_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/base_id"},
+		}})
+	}
+	baseType, err := h.resolveBaseTypeByBaseID(c.UserContext(), baseID)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "base_id not found")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if baseType == "base" {
+		return h.CreateBase(c)
+	}
+	return h.Create(c)
+}
+
+// ListDutyRosterUnifiedDatatable godoc
+// @Summary List duty roster (datatable)
+// @Description Unified datatable endpoint. Optional `base_type` filter: `hems` or `base`.
+// @Tags Flights - Duty Roster
+// @Produce json
+// @Param base_type query string false "Base type filter (hems|base)"
+// @Param base_id query string false "Base UUID"
+// @Param base_name query string false "Filter by base name"
+// @Param from query string false "Start date (YYYY-MM-DD)"
+// @Param to query string false "End date (YYYY-MM-DD)"
+// @Param page query int false "Page number"
+// @Param size query int false "Page size"
+// @Param limit query int false "Page size override"
+// @Param draw query int false "Draw counter"
+// @Success 200 {object} responsedto.DutyRosterGroupedDataTableResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/duty-roster/get-all/dt [get]
+func (h *DutyRosterHandler) ListAnyDatatable(c *fiber.Ctx) error {
+	if strings.EqualFold(strings.TrimSpace(c.Query("base_type")), "base") {
+		return h.ListBaseDatatable(c)
+	}
+	return h.ListDatatable(c)
+}
+
+// DeleteDutyRosterUnified godoc
+// @Summary Delete duty roster
+// @Description Unified delete endpoint by `data.id`.
+// @Tags Flights - Duty Roster
+// @Accept json
+// @Produce json
+// @Param request body requestdto.DutyRosterAnyDeleteRequest true "Delete request payload"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/duty-roster/delete [delete]
+func (h *DutyRosterHandler) DeleteAny(c *fiber.Ctx) error {
+	var req struct {
+		Data struct {
+			ID string `json:"id"`
+		} `json:"data"`
+	}
+	if err := c.BodyParser(&req); err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	id, err := h.resolveDutyRosterIDFromInput(c, strings.TrimSpace(req.Data.ID))
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: safeInternalDetail(),
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		status, errObj := buildServiceErrorObject("Delete failed", err, "duty roster not found")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "duty_roster_delete", Attributes: map[string]any{"deleted": true}})
+}
+
+// DeleteDutyRosterUnifiedCrew godoc
+// @Summary Remove duty roster crew assignment
+// @Description Unified crew delete endpoint by `data.id` and `roster_detail`.
+// @Tags Flights - Duty Roster
+// @Accept json
+// @Produce json
+// @Param request body requestdto.DutyRosterDeleteCrewByIDRequest true "Crew delete request payload"
+// @Success 200 {object} responsedto.DutyRosterCrewDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/duty-roster/crew [delete]
+func (h *DutyRosterHandler) DeleteAnyCrew(c *fiber.Ctx) error {
+	var req struct {
+		Data struct {
+			ID string `json:"id"`
+		} `json:"data"`
+	}
+	if err := c.BodyParser(&req); err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	id, err := h.resolveDutyRosterIDFromInput(c, strings.TrimSpace(req.Data.ID))
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: safeInternalDetail(),
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	crews, parseErr := service.BuildDutyRosterDeleteCrews(c.Body(), actorUserID(c))
+	if parseErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: parseErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: parseErr.Pointer},
+		}})
+	}
+	if len(crews) == 0 {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "roster_detail is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/roster_detail"},
+		}})
+	}
+	deletedRows, delErr := h.svc.DeleteCrews(c.UserContext(), id, crews, actorUserID(c))
+	if delErr != nil {
+		status, errObj := buildServiceErrorObject("Delete failed", delErr, "duty roster not found")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if len(deletedRows) == 0 {
+		return writeDutyRosterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "no crew assignment matched delete filter",
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "duty_roster_crew_delete", Attributes: map[string]any{"deleted": true, "deleted_count": len(deletedRows), "deleted_items": dutyRosterDeletedCrewItems(deletedRows)}})
+}
+
+// CreateBaseDutyRoster godoc
+// @Summary Create Base duty roster
+// @Description Create roster by regular `base_id` and `duty_date`.
+// @Description Base endpoints use `base_id` in request and `bases` in response attributes.
+// @Description Time input accepts `HH:MM` or `HH:MM:SS` and is normalized.
+// @Description `roster_detail` buckets: `pilot`, `doctor`, `rescuer`, `helper`, `other_person`.
+// @Description For pilot: `crew_type` can be `main` or `additional`.
+// @Description Pilot flags (`flight_instructor`, `line_checker`, `supervisor`, `examiner`, `co_pilot`) are only applied when `crew_type=additional`; for `main` they are ignored.
+// @Description For doctor/rescuer/helper, `crew_type` is always treated as `main`.
+// @Description For `other_person`, `id` must be empty and `name` is required.
+// @Description If roster shift_time is omitted, system uses base default shift; fallback `06:00:00-21:00:00`.
+// @Description `data.type` must be `base_duty_roster_create` (or `base_duty_roster` for backward compatibility).
+// @Tags Flights - Base Duty Roster
+// @Accept json
+// @Produce json
+// @Param request body requestdto.DutyRosterCreateRequest true "Create request payload"
+// @Success 201 {object} responsedto.DutyRosterResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/base-roster/create
+func (h *DutyRosterHandler) CreateBase(c *fiber.Ctx) error {
+	var req requestdto.DutyRosterCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	baseID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.BaseID))
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "base_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/base_id"},
+		}})
+	}
+	dutyDate, err := service.ParseDutyRosterDateOnly(req.Data.Attributes.DutyDate)
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "duty_date must be YYYY-MM-DD",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/duty_date"},
+		}})
+	}
+
+	row := &dutyroster.DutyRoster{BaseID: baseID, DutyDate: dutyDate, CreatedBy: actorUserID(c), UpdatedBy: actorUserID(c)}
+	defaultShiftStart, defaultShiftEnd, err := h.svc.ResolveBaseDefaultShiftRange(c.UserContext(), baseID, "base")
+	if err != nil {
+		if wrote := h.writeBaseTypeValidationError(c, err, baseID, "base", "/data/attributes/base_id"); wrote {
+			return nil
+		}
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	rowShiftStart, shiftErr := service.NormalizeDutyRosterClockInput(req.Data.Attributes.ShiftTime.ShiftStart, defaultShiftStart, "/data/attributes/shift_time/shift_start")
+	if shiftErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: shiftErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: shiftErr.Pointer},
+		}})
+	}
+	rowShiftEnd, shiftErr := service.NormalizeDutyRosterClockInput(req.Data.Attributes.ShiftTime.ShiftEnd, defaultShiftEnd, "/data/attributes/shift_time/shift_end")
+	if shiftErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: shiftErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: shiftErr.Pointer},
+		}})
+	}
+	_ = rowShiftStart
+	_ = rowShiftEnd
+	detail := toCoreDutyRosterDetailsInput(req.Data.Attributes.Detail)
+	crews, crewErr := service.BuildDutyRosterCrewRows(detail, actorUserID(c))
+	if crewErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: crewErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: crewErr.Pointer},
+		}})
+	}
+	clearCrewShiftDateForCreate(crews)
+	if err := h.svc.Create(c.UserContext(), row, crews); err != nil {
+		status, errObj := buildServiceErrorObject("Create failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+
+	flightID, err := h.createFlightForBaseRoster(c, row)
+	if err != nil {
+		_ = h.svc.HardDelete(c.UserContext(), row.ID)
+		return writeDutyRosterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return h.respondByIDBaseTypeWithFlight(c, fiber.StatusCreated, row.ID, "base", flightID)
+}
+
+func (h *DutyRosterHandler) createFlightForBaseRoster(c *fiber.Ctx, roster *dutyroster.DutyRoster) ([]byte, error) {
+	if h.flight == nil {
+		return nil, nil
+	}
+
+	flightRow := &flight.Flight{
+		Date:         roster.DutyDate.UTC(),
+		DutyRosterID: append([]byte(nil), roster.ID...),
+		CreatedBy:    actorUserID(c),
+		UpdatedBy:    actorUserID(c),
+	}
+
+	if err := h.flight.Create(c.UserContext(), flightRow); err != nil {
+		return nil, err
+	}
+	return flightRow.ID, nil
+}
+
+// GetBaseDutyRoster godoc
+// @Summary Get Base duty roster by UUID
+// @Tags Flights - Base Duty Roster
+// @Produce json
+// @Param uuid path string true "Roster UUID"
+// @Success 200 {object} responsedto.DutyRosterResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/base-roster/get/{uuid}
+func (h *DutyRosterHandler) GetBase(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(dutyRosterPathID(c))
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	// Backward-compatible fallback: allow :uuid as flight_uuid.
+	if h.flight != nil {
+		flightRow, flightErr := h.flight.GetByID(c.UserContext(), id)
+		if flightErr != nil {
+			status, errObj := buildServiceErrorObject("Get failed", flightErr, "")
+			return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+		}
+		if flightRow != nil && len(flightRow.DutyRosterID) == 16 {
+			return h.respondByIDBaseTypeWithFlight(c, fiber.StatusOK, flightRow.DutyRosterID, "base", flightRow.ID)
+		}
+	}
+
+	return h.respondByIDBaseType(c, fiber.StatusOK, id, "base")
+}
+
+func (h *DutyRosterHandler) GetBaseByAuthUser(c *fiber.Ctx) error {
+	userID := actorUserID(c)
+	if len(userID) == 0 {
+		return writeDutyRosterErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+	rosterID, err := h.findLatestRosterIDByUser(c.UserContext(), userID, "base")
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if len(rosterID) != 16 {
+		return writeDutyRosterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "base duty roster not found",
+		}})
+	}
+	return h.respondByIDBaseType(c, fiber.StatusOK, rosterID, "base")
+}
+
+// UpdateBaseDutyRoster godoc
+// @Summary Update Base duty roster (partial)
+// @Description If `roster_detail` is omitted, only header is updated.
+// @Description Crew update is additive by default; same role+crew_type+user in same roster is replaced.
+// @Description For pilot rows, extra flags (`flight_instructor`, `line_checker`, `supervisor`, `examiner`, `co_pilot`) are only applied for `crew_type=additional`.
+// @Description `data.type` must be `base_duty_roster_update` (or `base_duty_roster` for backward compatibility).
+// @Tags Flights - Base Duty Roster
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Roster UUID"
+// @Param request body requestdto.DutyRosterUpdateRequest true "Update request payload"
+// @Success 200 {object} responsedto.DutyRosterResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/base-roster/update/{uuid}
+func (h *DutyRosterHandler) UpdateBase(c *fiber.Ctx) error {
+	var req requestdto.DutyRosterUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	uuidStr := strings.TrimSpace(dutyRosterPathID(c))
+	bodyID := strings.TrimSpace(req.Data.ID)
+	if uuidStr == "" && bodyID == "" {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if uuidStr != "" && bodyID != "" && bodyID != uuidStr {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path id",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	targetID := bodyID
+	if targetID == "" {
+		targetID = uuidStr
+	}
+	id, err := h.resolveDutyRosterIDFromInput(c, targetID)
+	if err != nil {
+		sourcePtr := "/data/id"
+		if targetID == uuidStr && uuidStr != "" && bodyID == "" {
+			sourcePtr = "/path/id"
+		}
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: safeInternalDetail(),
+			Source: &jsonapi.ErrorSource{Pointer: sourcePtr},
+		}})
+	}
+
+	existing, err := h.svc.GetHeaderByIDByBaseType(c.UserContext(), id, "base")
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if existing == nil {
+		return writeDutyRosterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "base duty roster not found",
+		}})
+	}
+
+	row := &dutyroster.DutyRoster{ID: id, BaseID: append([]byte(nil), existing.BaseID...), DutyDate: existing.DutyDate, UpdatedBy: actorUserID(c)}
+	attrs := req.Data.Attributes
+	if attrs.BaseID != nil && strings.TrimSpace(*attrs.BaseID) != "" {
+		baseID, err := uuidv7.ParseString(strings.TrimSpace(*attrs.BaseID))
+		if err != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "base_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/base_id"},
+			}})
+		}
+		row.BaseID = baseID
+	}
+	if attrs.DutyDate != nil && strings.TrimSpace(*attrs.DutyDate) != "" {
+		d, err := service.ParseDutyRosterDateOnly(*attrs.DutyDate)
+		if err != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "duty_date must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/duty_date"},
+			}})
+		}
+		row.DutyDate = d
+	}
+	if attrs.ShiftTime != nil {
+		defaultShiftStart, defaultShiftEnd, err := service.ResolveDutyRosterShiftDefaultsForUpdate(c.UserContext(), h.svc, row.BaseID, "base", "", "")
+		if err != nil {
+			status, errObj := buildServiceErrorObject("Get failed", err, "")
+			return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+		}
+		shiftStart, shiftErr := service.NormalizeDutyRosterClockInput(attrs.ShiftTime.ShiftStart, defaultShiftStart, "/data/attributes/shift_time/shift_start")
+		if shiftErr != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: shiftErr.Detail,
+				Source: &jsonapi.ErrorSource{Pointer: shiftErr.Pointer},
+			}})
+		}
+		shiftEnd, shiftErr := service.NormalizeDutyRosterClockInput(attrs.ShiftTime.ShiftEnd, defaultShiftEnd, "/data/attributes/shift_time/shift_end")
+		if shiftErr != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: shiftErr.Detail,
+				Source: &jsonapi.ErrorSource{Pointer: shiftErr.Pointer},
+			}})
+		}
+		_ = shiftStart
+		_ = shiftEnd
+	}
+	crews := []dutyroster.DutyRosterCrew{}
+	if detail := toCoreDutyRosterDetailsInputPtr(attrs.Detail); detail != nil {
+		built, crewErr := service.BuildDutyRosterCrewRows(*detail, actorUserID(c))
+		if crewErr != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: crewErr.Detail,
+				Source: &jsonapi.ErrorSource{Pointer: crewErr.Pointer},
+			}})
+		}
+		crews = built
+	}
+	if err := h.svc.Update(c.UserContext(), row, crews); err != nil {
+		status, errObj := buildServiceErrorObject("Update failed", err, "base duty roster not found")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	h.logCrewAudit(c, "duty_roster.crew.append", id, "base", crews, "append crew assignments")
+	return h.respondByIDBaseType(c, fiber.StatusOK, id, "base")
+}
+
+// UpdateDutyRosterUnified godoc
+// @Summary Update duty roster (partial)
+// @Description Unified update endpoint by `data.id`.
+// @Tags Flights - Duty Roster
+// @Accept json
+// @Produce json
+// @Param request body requestdto.DutyRosterUpdateRequest true "Update request payload"
+// @Success 200 {object} responsedto.DutyRosterResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/duty-roster/update [patch]
+func (h *DutyRosterHandler) UpdateAny(c *fiber.Ctx) error {
+	var req struct {
+		Data struct {
+			Type       string `json:"type"`
+			ID         string `json:"id"`
+			Attributes struct {
+				BaseID *string `json:"base_id,omitempty"`
+			} `json:"attributes"`
+		} `json:"data"`
+	}
+	if err := c.BodyParser(&req); err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if req.Data.Attributes.BaseID != nil && strings.TrimSpace(*req.Data.Attributes.BaseID) != "" {
+		baseID, err := uuidv7.ParseString(strings.TrimSpace(*req.Data.Attributes.BaseID))
+		if err != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "base_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/base_id"},
+			}})
+		}
+		baseType, err := h.resolveBaseTypeByBaseID(c.UserContext(), baseID)
+		if err != nil {
+			status, errObj := buildServiceErrorObject("Get failed", err, "base_id not found")
+			return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+		}
+		if baseType == "base" {
+			return h.UpdateBase(c)
+		}
+		return h.Update(c)
+	}
+
+	targetID := strings.TrimSpace(req.Data.ID)
+	if targetID != "" {
+		rosterID, err := h.resolveDutyRosterIDFromInput(c, targetID)
+		if err == nil && len(rosterID) == 16 {
+			if hdr, _ := h.svc.GetHeaderByIDByBaseType(c.UserContext(), rosterID, "base"); hdr != nil {
+				return h.UpdateBase(c)
+			}
+			return h.Update(c)
+		}
+	}
+	t := strings.ToLower(strings.TrimSpace(req.Data.Type))
+	if strings.HasPrefix(t, "base_") {
+		return h.UpdateBase(c)
+	}
+	return h.Update(c)
+}
+
+func (h *DutyRosterHandler) resolveDutyRosterIDFromInput(c *fiber.Ctx, rawID string) ([]byte, error) {
+	parsedID, err := uuidv7.ParseString(strings.TrimSpace(rawID))
+	if err != nil {
+		return nil, errors.New("id is invalid UUID")
+	}
+
+	if h.flight != nil {
+		flightRow, flightErr := h.flight.GetByID(c.UserContext(), parsedID)
+		if flightErr != nil {
+			return nil, flightErr
+		}
+		if flightRow != nil {
+			if len(flightRow.DutyRosterID) != 16 {
+				return nil, errors.New("flight_id is not linked to duty roster")
+			}
+			return append([]byte(nil), flightRow.DutyRosterID...), nil
+		}
+	}
+
+	// Backward compatibility: allow direct duty_roster_id.
+	return parsedID, nil
+}
+
+func (h *DutyRosterHandler) findLatestRosterIDByUser(ctx context.Context, userID []byte, baseType string) ([]byte, error) {
+	if h.flight == nil || len(userID) != 16 {
+		return nil, nil
+	}
+	rows, _, err := h.flight.ListByUserID(ctx, userID, 100, 0)
+	if err != nil {
+		return nil, err
+	}
+	for i := range rows {
+		if len(rows[i].DutyRosterID) != 16 {
+			continue
+		}
+		header, err := h.svc.GetHeaderByIDByBaseType(ctx, rows[i].DutyRosterID, baseType)
+		if err != nil {
+			return nil, err
+		}
+		if header != nil {
+			return append([]byte(nil), rows[i].DutyRosterID...), nil
+		}
+	}
+	return nil, nil
+}
+
+// DeleteBaseDutyRoster godoc
+// @Summary Delete Base duty roster
+// @Tags Flights - Base Duty Roster
+// @Produce json
+// @Param uuid path string true "Roster UUID"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/base-roster/delete/{uuid}
+func (h *DutyRosterHandler) DeleteBase(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(dutyRosterPathID(c))
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		status, errObj := buildServiceErrorObject("Delete failed", err, "base duty roster not found")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "base_duty_roster_delete", Attributes: map[string]any{"deleted": true}})
+}
+
+// DeleteBaseDutyRosterCrew godoc
+// @Summary Remove crew assignment from Base duty roster
+// @Description Remove selected crew rows from roster UUID by filter in `roster_detail`.
+// @Description This endpoint removes crew only; header roster stays.
+// @Description For operational roles (pilot/doctor/rescuer/helper), if one `shift_date` boundary is sent then both are required.
+// @Description If `shift_date` is omitted, filter applies to roster day only.
+// @Description `data.type` should be `base_duty_roster_crew_delete` (also accepts `base_duty_roster_update`/`base_duty_roster` for compatibility).
+// @Tags Flights - Base Duty Roster
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Roster UUID"
+// @Param request body requestdto.DutyRosterDeleteCrewRequest true "Crew delete filter payload (use `roster_detail`)"
+// @Success 200 {object} responsedto.DutyRosterCrewDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/base-roster/{uuid}/crew
+func (h *DutyRosterHandler) DeleteBaseCrew(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(dutyRosterPathID(c))
+	if err != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+	crews, parseErr := service.BuildDutyRosterDeleteCrews(c.Body(), actorUserID(c))
+	if parseErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: parseErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: parseErr.Pointer},
+		}})
+	}
+	if len(crews) == 0 {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "roster_detail is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/roster_detail"},
+		}})
+	}
+	deletedRows, err := h.svc.DeleteCrews(c.UserContext(), id, crews, actorUserID(c))
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Delete failed", err, "base duty roster not found")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if len(deletedRows) == 0 {
+		return writeDutyRosterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "no crew assignment matched delete filter",
+		}})
+	}
+	h.logCrewAudit(c, "duty_roster.crew.remove", id, "base", crews, "remove crew assignments")
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "base_duty_roster_crew_delete", Attributes: map[string]any{"deleted": true, "deleted_count": len(deletedRows), "deleted_items": dutyRosterDeletedCrewItems(deletedRows)}})
+}
+
+// ListBaseDutyRoster godoc
+// @Summary List Base duty roster
+// @Description Query: `base_id` (optional), `base_name` (optional), `from` and `to` (`YYYY-MM-DD`, optional).
+// @Description Response grouping key is `attributes.bases`.
+// @Tags Flights - Base Duty Roster
+// @Produce json
+// @Param base_id query string false "Base UUID"
+// @Param base_name query string false "Filter by base name (contains, case-insensitive)"
+// @Param from query string false "Start date (YYYY-MM-DD)"
+// @Param to query string false "End date (YYYY-MM-DD)"
+// @Success 200 {object} responsedto.DutyRosterGroupedListResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/base-roster/get-all
+func (h *DutyRosterHandler) ListBase(c *fiber.Ctx) error {
+	baseRaw := strings.TrimSpace(c.Query("base_id"))
+	var baseID []byte
+	var err error
+	if baseRaw != "" {
+		baseID, err = uuidv7.ParseString(baseRaw)
+		if err != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "base_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/base_id"},
+			}})
+		}
+	}
+	from, to, rangeErr := service.ParseDutyRosterDateRangeOrDefault(c.Query("from"), c.Query("to"), time.Now().UTC())
+	if rangeErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: rangeErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: rangeErr.Pointer},
+		}})
+	}
+	if to.Before(from) {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "to must be >= from",
+			Source: &jsonapi.ErrorSource{Pointer: "/query/to"},
+		}})
+	}
+	baseName := strings.TrimSpace(c.Query("base_name"))
+
+	grouped, err := loadRosterGroups(c.UserContext(), h.svc, baseID, from, to, baseName, "base")
+	if err != nil {
+		status, errObj := buildServiceErrorObject("List failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	h.attachFlightIDsToBaseGroups(c.UserContext(), grouped)
+	return response.WriteWithMeta(c, fiber.StatusOK, grouped, map[string]any{"from": from.UTC().Format("2006-01-02"), "to": to.UTC().Format("2006-01-02"), "timezone": "UTC", "total_bases": len(grouped)})
+}
+
+// ListBaseDutyRosterDatatable godoc
+// @Summary List Base duty roster (datatable)
+// @Description Query: `base_id`, `base_name`, `from`, `to`, `page`, `size`, `limit`, `draw`.
+// @Description Response grouping key is `attributes.bases`.
+// @Tags Flights - Base Duty Roster
+// @Produce json
+// @Param base_id query string false "Base UUID"
+// @Param base_name query string false "Filter by base name (contains, case-insensitive)"
+// @Param from query string false "Start date (YYYY-MM-DD)"
+// @Param to query string false "End date (YYYY-MM-DD)"
+// @Param page query int false "Page number"
+// @Param size query int false "Page size"
+// @Param limit query int false "Page size override"
+// @Param draw query int false "Draw counter"
+// @Success 200 {object} responsedto.DutyRosterGroupedDataTableResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Legacy docs route removed: /api/v1/base-roster/get-all/dt
+func (h *DutyRosterHandler) ListBaseDatatable(c *fiber.Ctx) error {
+	baseRaw := strings.TrimSpace(c.Query("base_id"))
+	var baseID []byte
+	var err error
+	if baseRaw != "" {
+		baseID, err = uuidv7.ParseString(baseRaw)
+		if err != nil {
+			return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "base_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/base_id"},
+			}})
+		}
+	}
+	from, to, rangeErr := service.ParseDutyRosterDateRangeOrDefault(c.Query("from"), c.Query("to"), time.Now().UTC())
+	if rangeErr != nil {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: rangeErr.Detail,
+			Source: &jsonapi.ErrorSource{Pointer: rangeErr.Pointer},
+		}})
+	}
+	if to.Before(from) {
+		return writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "to must be >= from",
+			Source: &jsonapi.ErrorSource{Pointer: "/query/to"},
+		}})
+	}
+	baseName := strings.TrimSpace(c.Query("base_name"))
+
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+
+	grouped, err := loadRosterGroups(c.UserContext(), h.svc, baseID, from, to, baseName, "base")
+	if err != nil {
+		status, errObj := buildServiceErrorObject("List failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	h.attachFlightIDsToBaseGroups(c.UserContext(), grouped)
+	pagedGroups, total := paginateRosterGroups(grouped, start, length)
+	meta := map[string]any{"draw": draw, "records_total": total, "records_filtered": total, "from": from.UTC().Format("2006-01-02"), "to": to.UTC().Format("2006-01-02"), "timezone": "UTC"}
+	return response.WriteWithMeta(c, fiber.StatusOK, pagedGroups, meta)
+}
+
+func (h *DutyRosterHandler) respondByIDBaseType(c *fiber.Ctx, status int, id []byte, baseType string) error {
+	return h.respondByIDBaseTypeWithFlight(c, status, id, baseType, nil)
+}
+
+func (h *DutyRosterHandler) respondByIDBaseTypeWithFlight(c *fiber.Ctx, status int, id []byte, baseType string, flightID []byte) error {
+	header, err := h.svc.GetHeaderByIDByBaseType(c.UserContext(), id, baseType)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if header == nil {
+		return writeDutyRosterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "duty roster not found",
+		}})
+	}
+	crews, err := h.svc.GetCrewsByRosterIDs(c.UserContext(), [][]byte{id})
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	flightMeta := rosterFlightMeta{}
+	if len(flightID) == 16 {
+		flightMeta.FlightID = idString(flightID)
+	} else {
+		flightMeta, _ = h.findFlightMetaByRosterID(c.UserContext(), id)
+	}
+	if strings.EqualFold(strings.TrimSpace(baseType), "base") {
+		res := dutyRosterResource(c.UserContext(), *header, crews, "base")
+		if strings.TrimSpace(flightMeta.FlightID) != "" {
+			res.Attributes.FlightID = strings.TrimSpace(flightMeta.FlightID)
+		}
+		if !isEmptyRosterHelicopter(flightMeta.Helicopter) {
+			res.Attributes.Helicopter = flightMeta.Helicopter
+		}
+		return response.Write(c, status, res)
+	}
+	res := dutyRosterResource(c.UserContext(), *header, crews, "hems")
+	if strings.TrimSpace(flightMeta.FlightID) != "" {
+		res.Attributes.FlightID = strings.TrimSpace(flightMeta.FlightID)
+	}
+	if !isEmptyRosterHelicopter(flightMeta.Helicopter) {
+		res.Attributes.Helicopter = flightMeta.Helicopter
+	}
+	return response.Write(c, status, res)
+}
+
+func (h *DutyRosterHandler) respondByID(c *fiber.Ctx, status int, id []byte) error {
+	header, err := h.svc.GetHeaderByID(c.UserContext(), id)
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	if header == nil {
+		return writeDutyRosterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "hems duty roster not found",
+		}})
+	}
+	crews, err := h.svc.GetCrewsByRosterIDs(c.UserContext(), [][]byte{id})
+	if err != nil {
+		status, errObj := buildServiceErrorObject("Get failed", err, "")
+		return writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+	res := dutyRosterResource(c.UserContext(), *header, crews, "hems")
+	if flightMeta, findErr := h.findFlightMetaByRosterID(c.UserContext(), id); findErr == nil {
+		if strings.TrimSpace(flightMeta.FlightID) != "" {
+			res.Attributes.FlightID = strings.TrimSpace(flightMeta.FlightID)
+		}
+		if !isEmptyRosterHelicopter(flightMeta.Helicopter) {
+			res.Attributes.Helicopter = flightMeta.Helicopter
+		}
+	}
+	return response.Write(c, status, res)
+}
+
+func (h *DutyRosterHandler) findFlightMetaByRosterID(ctx context.Context, rosterID []byte) (rosterFlightMeta, error) {
+	if h.flight == nil || len(rosterID) != 16 {
+		return rosterFlightMeta{}, nil
+	}
+	row, err := h.flight.GetByDutyRosterID(ctx, rosterID)
+	if err != nil || row == nil {
+		return rosterFlightMeta{}, err
+	}
+	return rosterFlightMeta{
+		FlightID:   idString(row.ID),
+		Helicopter: buildRosterHelicopter(*row),
+	}, nil
+}
+
+func (h *DutyRosterHandler) buildFlightMetaByRosterMap(ctx context.Context, rosterIDs [][]byte) map[string]rosterFlightMeta {
+	out := map[string]rosterFlightMeta{}
+	if h.flight == nil || len(rosterIDs) == 0 {
+		return out
+	}
+	rows, err := h.flight.ListByDutyRosterIDs(ctx, rosterIDs)
+	if err != nil {
+		return out
+	}
+	for i := range rows {
+		rosterKey := idString(rows[i].DutyRosterID)
+		if rosterKey == "" {
+			continue
+		}
+		next := rosterFlightMeta{
+			FlightID:   idString(rows[i].ID),
+			Helicopter: buildRosterHelicopter(rows[i]),
+		}
+		prev, exists := out[rosterKey]
+		if !exists || shouldReplaceRosterFlightMeta(prev, next) {
+			out[rosterKey] = next
+		}
+	}
+	return out
+}
+
+func (h *DutyRosterHandler) attachFlightIDsToHEMSGroups(ctx context.Context, groups []responsedto.DutyRosterBaseGroupResource) {
+	rosterIDs := make([][]byte, 0)
+	for i := range groups {
+		for j := range groups[i].Attributes.Rosters {
+			id, err := uuidv7.ParseString(strings.TrimSpace(groups[i].Attributes.Rosters[j].ID))
+			if err == nil {
+				rosterIDs = append(rosterIDs, id)
+			}
+		}
+	}
+	flightByRoster := h.buildFlightMetaByRosterMap(ctx, rosterIDs)
+	for i := range groups {
+		for j := range groups[i].Attributes.Rosters {
+			rosterID := strings.TrimSpace(groups[i].Attributes.Rosters[j].ID)
+			meta := flightByRoster[rosterID]
+			if strings.TrimSpace(meta.FlightID) != "" {
+				groups[i].Attributes.Rosters[j].FlightID = strings.TrimSpace(meta.FlightID)
+			}
+			if !isEmptyRosterHelicopter(meta.Helicopter) {
+				groups[i].Attributes.Rosters[j].Helicopter = meta.Helicopter
+			}
+		}
+	}
+}
+
+func (h *DutyRosterHandler) attachFlightIDsToBaseGroups(ctx context.Context, groups []responsedto.DutyRosterBaseGroupResource) {
+	rosterIDs := make([][]byte, 0)
+	for i := range groups {
+		for j := range groups[i].Attributes.Rosters {
+			id, err := uuidv7.ParseString(strings.TrimSpace(groups[i].Attributes.Rosters[j].ID))
+			if err == nil {
+				rosterIDs = append(rosterIDs, id)
+			}
+		}
+	}
+	flightByRoster := h.buildFlightMetaByRosterMap(ctx, rosterIDs)
+	for i := range groups {
+		for j := range groups[i].Attributes.Rosters {
+			rosterID := strings.TrimSpace(groups[i].Attributes.Rosters[j].ID)
+			meta := flightByRoster[rosterID]
+			if strings.TrimSpace(meta.FlightID) != "" {
+				groups[i].Attributes.Rosters[j].FlightID = strings.TrimSpace(meta.FlightID)
+			}
+			if !isEmptyRosterHelicopter(meta.Helicopter) {
+				groups[i].Attributes.Rosters[j].Helicopter = meta.Helicopter
+			}
+		}
+	}
+}
+
+func buildRosterHelicopter(row flight.Flight) responsedto.DutyRosterHelicopterSummary {
+	if row.Takeover == nil {
+		return responsedto.DutyRosterHelicopterSummary{}
+	}
+	return responsedto.DutyRosterHelicopterSummary{
+		ID: idString(row.Takeover.ReserveAcID),
+	}
+}
+
+func shouldReplaceRosterFlightMeta(prev, next rosterFlightMeta) bool {
+	if isEmptyRosterHelicopter(prev.Helicopter) && !isEmptyRosterHelicopter(next.Helicopter) {
+		return true
+	}
+	if !isEmptyRosterHelicopter(prev.Helicopter) && isEmptyRosterHelicopter(next.Helicopter) {
+		return false
+	}
+	if strings.TrimSpace(prev.FlightID) == "" && strings.TrimSpace(next.FlightID) != "" {
+		return true
+	}
+	return false
+}
+
+func isEmptyRosterHelicopter(h responsedto.DutyRosterHelicopterSummary) bool {
+	return strings.TrimSpace(h.ID) == "" &&
+		strings.TrimSpace(h.Designation) == "" &&
+		strings.TrimSpace(h.Identifier) == "" &&
+		strings.TrimSpace(h.Type) == ""
+}
+
+func dateToString(t *time.Time) string {
+	if t == nil || t.IsZero() {
+		return ""
+	}
+	return t.UTC().Format("2006-01-02")
+}
+
+func bytesEqualUUID(a, b []byte) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
+
+func dutyRosterPathID(c *fiber.Ctx) string {
+	id := strings.TrimSpace(c.Params("id"))
+	if id != "" {
+		return id
+	}
+	return strings.TrimSpace(c.Params("uuid"))
+}
+
+func dutyRosterPathFlightID(c *fiber.Ctx) string {
+	id := strings.TrimSpace(c.Params("flight_id"))
+	if id != "" {
+		return id
+	}
+	return strings.TrimSpace(c.Params("flight_uuid"))
+}
+
+func writeDutyRosterErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		if strings.TrimSpace(e.Code) == "" || strings.TrimSpace(e.ErrorCode) == "" {
+			code, errorCode := inferDutyRosterErrorCode(status, e.Title, e.Detail)
+			if strings.TrimSpace(e.Code) == "" {
+				e.Code = code
+			}
+			if strings.TrimSpace(e.ErrorCode) == "" {
+				e.ErrorCode = errorCode
+			}
+		}
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferDutyRosterErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusUnauthorized:
+		return apperrorsx.CodeDutyRosterUnauthorized, apperrorsx.ErrDutyRosterUnauthorized.ErrorCode
+	case fiber.StatusNotFound:
+		return apperrorsx.CodeDutyRosterNotFound, apperrorsx.ErrDutyRosterNotFound.ErrorCode
+	case fiber.StatusConflict:
+		if strings.Contains(lowerDetail, "cannot delete") || strings.Contains(lowerDetail, "relation") || strings.Contains(lowerDetail, "foreign key") || strings.Contains(lowerDetail, "constraint") {
+			return apperrorsx.CodeDutyRosterRelationDeleteConflict, apperrorsx.ErrDutyRosterRelationDeleteConflict.ErrorCode
+		}
+		return apperrorsx.CodeDutyRosterConflict, apperrorsx.ErrDutyRosterConflict.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid"), strings.Contains(lowerDetail, "invalid id"):
+			return apperrorsx.CodeDutyRosterInvalidUUID, apperrorsx.ErrDutyRosterInvalidUUID.ErrorCode
+		case strings.Contains(lowerDetail, "base type"), strings.Contains(lowerDetail, "not hems base"), strings.Contains(lowerDetail, "not regular base"):
+			return apperrorsx.CodeDutyRosterBaseTypeInvalid, apperrorsx.ErrDutyRosterBaseTypeInvalid.ErrorCode
+		case strings.Contains(lowerTitle, "validation error"):
+			return apperrorsx.CodeDutyRosterValidationFailed, apperrorsx.ErrDutyRosterValidationFailed.ErrorCode
+		default:
+			return apperrorsx.CodeDutyRosterInvalidPayload, apperrorsx.ErrDutyRosterInvalidPayload.ErrorCode
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.CodeDutyRosterInvalidJSON, apperrorsx.ErrDutyRosterInvalidJSON.ErrorCode
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.CodeDutyRosterCreateFailed, apperrorsx.ErrDutyRosterCreateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.CodeDutyRosterUpdateFailed, apperrorsx.ErrDutyRosterUpdateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.CodeDutyRosterDeleteFailed, apperrorsx.ErrDutyRosterDeleteFailed.ErrorCode
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.CodeDutyRosterListFailed, apperrorsx.ErrDutyRosterListFailed.ErrorCode
+		default:
+			return apperrorsx.CodeDutyRosterInvalidPayload, apperrorsx.ErrDutyRosterInvalidPayload.ErrorCode
+		}
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
+
+func buildServiceErrorObject(title string, err error, notFoundDetail string) (int, jsonapi.ErrorObject) {
+	if err == nil {
+		status := fiber.StatusBadRequest
+		return status, jsonapi.ErrorObject{
+			Status: strconv.Itoa(status),
+			Title:  title,
+			Detail: title,
+		}
+	}
+	detail := strings.TrimSpace(err.Error())
+
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		status := fiber.StatusNotFound
+		if strings.TrimSpace(notFoundDetail) != "" {
+			detail = strings.TrimSpace(notFoundDetail)
+		} else if detail == "" {
+			detail = "resource not found"
+		}
+		return status, jsonapi.ErrorObject{
+			Status: strconv.Itoa(status),
+			Title:  title,
+			Detail: detail,
+		}
+	}
+
+	if errors.Is(err, context.Canceled) {
+		status := fiber.StatusRequestTimeout
+		if detail == "" {
+			detail = "request canceled"
+		}
+		return status, jsonapi.ErrorObject{
+			Status: strconv.Itoa(status),
+			Title:  title,
+			Detail: detail,
+		}
+	}
+
+	if errors.Is(err, context.DeadlineExceeded) {
+		status := fiber.StatusRequestTimeout
+		if detail == "" {
+			detail = "request timeout"
+		}
+		return status, jsonapi.ErrorObject{
+			Status: strconv.Itoa(status),
+			Title:  title,
+			Detail: detail,
+		}
+	}
+
+	status, detail, mysqlMapped := mapDutyRosterMySQLError(err, detail)
+	if !mysqlMapped {
+		status, detail = mapDutyRosterGenericError(detail, title)
+	}
+	if detail == "" {
+		detail = title
+	}
+	return status, jsonapi.ErrorObject{
+		Status: strconv.Itoa(status),
+		Title:  title,
+		Detail: detail,
+	}
+}
+
+func (h *DutyRosterHandler) writeBaseTypeValidationError(
+	c *fiber.Ctx,
+	err error,
+	baseID []byte,
+	expectedBaseType string,
+	pointer string,
+) bool {
+	if !errors.Is(err, gorm.ErrRecordNotFound) {
+		return false
+	}
+
+	var oppositeType string
+	var mismatchDetail string
+	switch strings.ToLower(strings.TrimSpace(expectedBaseType)) {
+	case "base":
+		oppositeType = "hems"
+		mismatchDetail = "base_id is not regular base"
+	default:
+		oppositeType = "base"
+		mismatchDetail = "base_id is not HEMS base"
+	}
+
+	rows, listErr := h.svc.ListBasesByType(c.UserContext(), baseID, expectedBaseType)
+	if listErr != nil {
+		status, errObj := buildServiceErrorObject("Get failed", listErr, "")
+		_ = writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+		return true
+	}
+	if len(rows) > 0 {
+		return false
+	}
+
+	oppositeRows, oppositeErr := h.svc.ListBasesByType(c.UserContext(), baseID, oppositeType)
+	if oppositeErr != nil {
+		status, errObj := buildServiceErrorObject("Get failed", oppositeErr, "")
+		_ = writeDutyRosterErrors(c, status, []jsonapi.ErrorObject{errObj})
+		return true
+	}
+	if len(oppositeRows) > 0 {
+		_ = writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: mismatchDetail,
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}})
+		return true
+	}
+
+	_ = writeDutyRosterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+		Status: "422",
+		Title:  "Validation error",
+		Detail: "base_id not found",
+		Source: &jsonapi.ErrorSource{Pointer: pointer},
+	}})
+	return true
+}
+
+func (h *DutyRosterHandler) resolveBaseTypeByBaseID(ctx context.Context, baseID []byte) (string, error) {
+	rows, err := h.svc.ListBasesByType(ctx, baseID, "hems")
+	if err != nil {
+		return "", err
+	}
+	if len(rows) > 0 {
+		return "hems", nil
+	}
+	rows, err = h.svc.ListBasesByType(ctx, baseID, "base")
+	if err != nil {
+		return "", err
+	}
+	if len(rows) > 0 {
+		return "base", nil
+	}
+	return "", gorm.ErrRecordNotFound
+}
+
+func mapDutyRosterMySQLError(err error, fallbackDetail string) (int, string, bool) {
+	status := fiber.StatusBadRequest
+	detail := strings.TrimSpace(fallbackDetail)
+
+	var mysqlErr *mysqldriver.MySQLError
+	if !errors.As(err, &mysqlErr) {
+		return status, detail, false
+	}
+
+	switch mysqlErr.Number {
+	case 1045:
+		status = fiber.StatusUnauthorized
+		detail = "authentication failed"
+	case 1142, 1227:
+		status = fiber.StatusForbidden
+		detail = "insufficient permission to perform this action"
+	case 1205, 1213:
+		status = fiber.StatusConflict
+		detail = "request conflicted with another transaction; please retry"
+	case 2006:
+		status = fiber.StatusServiceUnavailable
+		detail = "service temporarily unavailable"
+	case 1062:
+		status = fiber.StatusConflict
+		detail = dutyRosterDuplicateDetail(mysqlErr.Message)
+	case 1048, 1292, 1366, 1451, 1452, 3819, 4025:
+		status = fiber.StatusUnprocessableEntity
+		detail = dutyRosterFriendlyMySQLError(mysqlErr.Number)
+	default:
+		status = fiber.StatusBadRequest
+		detail = "invalid request payload"
+	}
+	return status, detail, true
+}
+
+func mapDutyRosterGenericError(detail, title string) (int, string) {
+	msg := strings.ToLower(strings.TrimSpace(detail))
+	cleanDetail := strings.TrimSpace(detail)
+	switch {
+	case strings.Contains(msg, "forbidden"), strings.Contains(msg, "permission denied"), strings.Contains(msg, "not allowed"):
+		if cleanDetail != "" {
+			return fiber.StatusForbidden, cleanDetail
+		}
+		return fiber.StatusForbidden, "forbidden"
+	case strings.Contains(msg, "unauthorized"), strings.Contains(msg, "invalid token"), strings.Contains(msg, "authentication failed"):
+		if cleanDetail != "" {
+			return fiber.StatusUnauthorized, cleanDetail
+		}
+		return fiber.StatusUnauthorized, "unauthorized"
+	case strings.Contains(msg, "too many requests"), strings.Contains(msg, "rate limit"):
+		if cleanDetail != "" {
+			return fiber.StatusTooManyRequests, cleanDetail
+		}
+		return fiber.StatusTooManyRequests, "too many requests"
+	case strings.Contains(msg, "conflict"), strings.Contains(msg, "already exists"), strings.Contains(msg, "duplicate"):
+		if cleanDetail != "" {
+			return fiber.StatusConflict, cleanDetail
+		}
+		return fiber.StatusConflict, "data conflict"
+	case strings.Contains(msg, "internal server error"), strings.Contains(msg, "panic"):
+		return fiber.StatusInternalServerError, "internal server error"
+	case strings.Contains(msg, "unavailable"), strings.Contains(msg, "connection refused"):
+		return fiber.StatusServiceUnavailable, "service temporarily unavailable"
+	default:
+		_ = title
+		if cleanDetail != "" {
+			return fiber.StatusBadRequest, cleanDetail
+		}
+		return fiber.StatusBadRequest, "invalid request payload"
+	}
+}
+
+var mysqlDuplicateKeyRe = regexp.MustCompile(`(?i)Duplicate entry '.*' for key '([^']+)'`)
+
+func dutyRosterDuplicateDetail(raw string) string {
+	key := mysqlDuplicateKey(raw)
+	if key == "" {
+		return "data conflict: a record with the same unique combination already exists"
+	}
+	switch key {
+	case "idx_roster_base_date":
+		return "roster already exists for the selected base and duty date"
+	case "idx_roster_crew_unique":
+		return "crew assignment already exists for the selected role and shift range"
+	default:
+		return "data conflict: a record with the same unique combination already exists"
+	}
+}
+
+func mysqlDuplicateKey(raw string) string {
+	msg := strings.TrimSpace(raw)
+	if msg == "" {
+		return ""
+	}
+	m := mysqlDuplicateKeyRe.FindStringSubmatch(msg)
+	if len(m) < 2 {
+		return ""
+	}
+	key := strings.TrimSpace(m[1])
+	if i := strings.LastIndex(key, "."); i >= 0 && i+1 < len(key) {
+		key = key[i+1:]
+	}
+	return strings.Trim(key, "`")
+}
+
+func dutyRosterFriendlyMySQLError(code uint16) string {
+	switch code {
+	case 1048:
+		return "required field must not be empty"
+	case 1292:
+		return "invalid date or time format"
+	case 1366:
+		return "invalid value for one of the fields"
+	case 1451:
+		return "cannot delete data because it is still referenced"
+	case 1452:
+		return "referenced data was not found"
+	case 3819, 4025:
+		return "data violates one of the validation constraints"
+	default:
+		return "invalid request payload"
+	}
+}
+
+func (h *DutyRosterHandler) logCrewAudit(
+	c *fiber.Ctx,
+	action string,
+	rosterID []byte,
+	baseType string,
+	crews []dutyroster.DutyRosterCrew,
+	message string,
+) {
+	if h.audit == nil || len(crews) == 0 {
+		return
+	}
+	h.audit.Log(c.UserContext(), service.AuditLogInput{
+		RequestID:   requestIDFromCtx(c),
+		ActorUserID: actorUserID(c),
+		Layer:       "handler",
+		Module:      "duty_roster",
+		Action:      action,
+		Method:      c.Method(),
+		Path:        c.Path(),
+		StatusCode:  fiber.StatusOK,
+		Success:     true,
+		IP:          c.IP(),
+		UserAgent:   c.Get("User-Agent"),
+		Message:     message,
+		Metadata:    dutyRosterCrewAuditMetadata(rosterID, baseType, crews),
+	})
+}
+
+func requestIDFromCtx(c *fiber.Ctx) string {
+	if v, ok := c.Locals("requestid").(string); ok {
+		return strings.TrimSpace(v)
+	}
+	return strings.TrimSpace(c.Get("X-Request-ID"))
+}
+
+func clearCrewShiftDateForCreate(crews []dutyroster.DutyRosterCrew) {
+	for i := range crews {
+		crews[i].DateStart = nil
+		crews[i].DateEnd = nil
+	}
+}
diff --git a/internal/transport/http/handlers/duty_roster_handler_test.go b/internal/transport/http/handlers/duty_roster_handler_test.go
new file mode 100644
index 0000000..dddb0b9
--- /dev/null
+++ b/internal/transport/http/handlers/duty_roster_handler_test.go
@@ -0,0 +1,2260 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	dutyroster "wucher/internal/domain/duty_roster"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+)
+
+type hemsDutyRosterServiceMock struct {
+	getHeaderByIDFn      func(id []byte) (*dutyroster.HeaderView, error)
+	getCrewsByRosterIDFn func(ids [][]byte) ([]dutyroster.CrewView, error)
+	listHeadersByRangeFn func(baseID []byte, from, to time.Time) ([]dutyroster.HeaderView, error)
+	listHEMSBasesFn      func(baseID []byte) ([]dutyroster.BaseView, error)
+	getBaseShiftFn       func(baseID []byte, baseType string) (string, error)
+	deleteCrewsFn        func(ctx context.Context, id []byte, crews []dutyroster.DutyRosterCrew, deletedBy []byte) ([]dutyroster.DeletedCrewResult, error)
+
+	createErr error
+	updateErr error
+	deleteErr error
+
+	lastCreateRow   *dutyroster.DutyRoster
+	lastCreateCrews []dutyroster.DutyRosterCrew
+	lastUpdateRow   *dutyroster.DutyRoster
+	lastUpdateCrews []dutyroster.DutyRosterCrew
+	lastListBaseID  []byte
+	lastListFrom    time.Time
+	lastListTo      time.Time
+	lastRosterIDs   [][]byte
+}
+
+type dutyRosterEmptyErr struct{}
+
+func (dutyRosterEmptyErr) Error() string { return "" }
+
+func (m *hemsDutyRosterServiceMock) Create(_ context.Context, row *dutyroster.DutyRoster, crews []dutyroster.DutyRosterCrew) error {
+	m.lastCreateRow = row
+	m.lastCreateCrews = crews
+	if m.createErr != nil {
+		return m.createErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+func (m *hemsDutyRosterServiceMock) Update(_ context.Context, row *dutyroster.DutyRoster, crews []dutyroster.DutyRosterCrew) error {
+	m.lastUpdateRow = row
+	m.lastUpdateCrews = crews
+	if m.updateErr != nil {
+		return m.updateErr
+	}
+	return nil
+}
+
+func (m *hemsDutyRosterServiceMock) Delete(_ context.Context, _ []byte, _ []byte) error {
+	return m.deleteErr
+}
+
+func (m *hemsDutyRosterServiceMock) HardDelete(_ context.Context, _ []byte) error {
+	return m.deleteErr
+}
+
+func (m *hemsDutyRosterServiceMock) DeleteCrews(ctx context.Context, id []byte, crews []dutyroster.DutyRosterCrew, deletedBy []byte) ([]dutyroster.DeletedCrewResult, error) {
+	if m.deleteCrewsFn != nil {
+		return m.deleteCrewsFn(ctx, id, crews, deletedBy)
+	}
+	return []dutyroster.DeletedCrewResult{}, m.deleteErr
+}
+
+func (m *hemsDutyRosterServiceMock) GetBaseDefaultShift(_ context.Context, baseID []byte, baseType string) (string, error) {
+	if m.getBaseShiftFn != nil {
+		return m.getBaseShiftFn(baseID, baseType)
+	}
+	return "", nil
+}
+
+func (m *hemsDutyRosterServiceMock) ResolveBaseDefaultShiftRange(_ context.Context, baseID []byte, baseType string) (string, string, error) {
+	raw, err := m.GetBaseDefaultShift(context.Background(), baseID, baseType)
+	if err != nil {
+		return "", "", err
+	}
+	start, end := service.ParseDutyRosterShiftRange(raw)
+	return start, end, nil
+}
+
+func (m *hemsDutyRosterServiceMock) GetHeaderByID(_ context.Context, id []byte) (*dutyroster.HeaderView, error) {
+	if m.getHeaderByIDFn != nil {
+		return m.getHeaderByIDFn(id)
+	}
+	return nil, nil
+}
+
+func (m *hemsDutyRosterServiceMock) GetCrewsByRosterIDs(_ context.Context, ids [][]byte) ([]dutyroster.CrewView, error) {
+	m.lastRosterIDs = ids
+	if m.getCrewsByRosterIDFn != nil {
+		return m.getCrewsByRosterIDFn(ids)
+	}
+	return []dutyroster.CrewView{}, nil
+}
+
+func (m *hemsDutyRosterServiceMock) ListHeadersByRange(_ context.Context, baseID []byte, from, to time.Time) ([]dutyroster.HeaderView, error) {
+	m.lastListBaseID = baseID
+	m.lastListFrom = from
+	m.lastListTo = to
+	if m.listHeadersByRangeFn != nil {
+		return m.listHeadersByRangeFn(baseID, from, to)
+	}
+	return []dutyroster.HeaderView{}, nil
+}
+
+func (m *hemsDutyRosterServiceMock) ListHEMSBases(_ context.Context, baseID []byte) ([]dutyroster.BaseView, error) {
+	if m.listHEMSBasesFn != nil {
+		return m.listHEMSBasesFn(baseID)
+	}
+	return []dutyroster.BaseView{}, nil
+}
+
+func (m *hemsDutyRosterServiceMock) GetHeaderByIDByBaseType(_ context.Context, id []byte, _ string) (*dutyroster.HeaderView, error) {
+	return m.GetHeaderByID(context.Background(), id)
+}
+
+func (m *hemsDutyRosterServiceMock) ListHeadersByRangeByBaseType(_ context.Context, baseID []byte, from, to time.Time, _ string) ([]dutyroster.HeaderView, error) {
+	return m.ListHeadersByRange(context.Background(), baseID, from, to)
+}
+
+func (m *hemsDutyRosterServiceMock) ListBasesByType(_ context.Context, baseID []byte, baseType string) ([]dutyroster.BaseView, error) {
+	if m.listHEMSBasesFn != nil {
+		return m.listHEMSBasesFn(baseID)
+	}
+	if strings.EqualFold(strings.TrimSpace(baseType), "base") {
+		return []dutyroster.BaseView{}, nil
+	}
+	return []dutyroster.BaseView{{ID: append([]byte(nil), baseID...)}}, nil
+}
+
+func newHemsDutyRosterTestApp(h *DutyRosterHandler) *fiber.App {
+	app := fiber.New()
+	app.Post("/api/v1/hems-roster/create", h.Create)
+	app.Patch("/api/v1/hems-roster/update/:uuid", h.Update)
+	app.Patch("/api/v1/base-roster/update/:uuid", h.UpdateBase)
+	app.Get("/api/v1/hems-roster/get-all", h.List)
+	app.Get("/api/v1/hems-roster/get-all/dt", h.ListDatatable)
+	return app
+}
+
+func newDutyRosterFullTestApp(h *DutyRosterHandler) *fiber.App {
+	app := fiber.New()
+	app.Post("/api/v1/hems-roster/create", h.Create)
+	app.Get("/api/v1/hems-roster/get/:uuid", h.Get)
+	app.Patch("/api/v1/hems-roster/update/:uuid", h.Update)
+	app.Delete("/api/v1/hems-roster/delete/:id", h.Delete)
+	app.Delete("/api/v1/hems-roster/:uuid/crew", h.DeleteCrew)
+	app.Get("/api/v1/hems-roster/get-all", h.List)
+	app.Get("/api/v1/hems-roster/get-all/dt", h.ListDatatable)
+
+	app.Post("/api/v1/base-roster/create", h.CreateBase)
+	app.Get("/api/v1/base-roster/get/:uuid", h.GetBase)
+	app.Patch("/api/v1/base-roster/update/:uuid", h.UpdateBase)
+	app.Delete("/api/v1/base-roster/delete/:id", h.DeleteBase)
+	app.Delete("/api/v1/base-roster/:uuid/crew", h.DeleteBaseCrew)
+	app.Get("/api/v1/base-roster/get-all", h.ListBase)
+	app.Get("/api/v1/base-roster/get-all/dt", h.ListBaseDatatable)
+	return app
+}
+
+func doJSONRequestHemsDutyRoster(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDStringHemsDutyRoster(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestHemsDutyRosterHandlerUpdate_AllowsMissingDataID(t *testing.T) {
+	id := uuidv7.MustBytes()
+	svc := &hemsDutyRosterServiceMock{
+		getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+			return &dutyroster.HeaderView{
+				ID:        append([]byte(nil), id...),
+				BaseID:    uuidv7.MustBytes(),
+				DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+				CreatedAt: time.Now().UTC(),
+				UpdatedAt: time.Now().UTC(),
+			}, nil
+		},
+	}
+	h := NewDutyRosterHandler(svc)
+	app := newHemsDutyRosterTestApp(h)
+
+	body := []byte(`{
+		"data": {
+			"type": "duty_roster_update",
+			"attributes": {
+				"shift_time": {"shift_start":"10:00","shift_end":"22:00"}
+			}
+		}
+	}`)
+	resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+mustUUIDStringHemsDutyRoster(t, id), body)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+	if svc.lastUpdateRow == nil {
+		t.Fatalf("expected update row captured")
+	}
+}
+
+func TestHemsDutyRosterHandlerUpdate_IDMismatch(t *testing.T) {
+	id := uuidv7.MustBytes()
+	otherID := uuidv7.MustBytes()
+	svc := &hemsDutyRosterServiceMock{}
+	h := NewDutyRosterHandler(svc)
+	app := newHemsDutyRosterTestApp(h)
+
+	body := []byte(`{
+		"data": {
+			"type": "duty_roster_update",
+			"id": "` + mustUUIDStringHemsDutyRoster(t, otherID) + `",
+			"attributes": {}
+		}
+	}`)
+	resp, respBody := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+mustUUIDStringHemsDutyRoster(t, id), body)
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", resp.StatusCode)
+	}
+	if !strings.Contains(string(respBody), "id does not match path id") {
+		t.Fatalf("expected mismatch error, got %s", string(respBody))
+	}
+}
+
+func TestHemsDutyRosterHandlerUpdate_RejectsInvalidShiftTimeFormat(t *testing.T) {
+	id := uuidv7.MustBytes()
+	svc := &hemsDutyRosterServiceMock{
+		getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+			return &dutyroster.HeaderView{
+				ID:        append([]byte(nil), id...),
+				BaseID:    uuidv7.MustBytes(),
+				DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+				CreatedAt: time.Now().UTC(),
+				UpdatedAt: time.Now().UTC(),
+			}, nil
+		},
+	}
+	h := NewDutyRosterHandler(svc)
+	app := newHemsDutyRosterTestApp(h)
+
+	body := []byte(`{
+		"data": {
+			"type": "duty_roster_update",
+			"attributes": {
+				"shift_time": {"shift_start":"10-00","shift_end":"22:00"}
+			}
+		}
+	}`)
+	resp, respBody := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+mustUUIDStringHemsDutyRoster(t, id), body)
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", resp.StatusCode)
+	}
+	if !strings.Contains(string(respBody), "time must be HH:MM or HH:MM:SS") {
+		t.Fatalf("expected not found response, got %s", string(respBody))
+	}
+}
+
+func TestHemsDutyRosterHandlerUpdate_PartialShiftTimeKeepsExistingOtherSide(t *testing.T) {
+	id := uuidv7.MustBytes()
+	svc := &hemsDutyRosterServiceMock{
+		getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+			return &dutyroster.HeaderView{
+				ID:        append([]byte(nil), id...),
+				BaseID:    uuidv7.MustBytes(),
+				DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+				CreatedAt: time.Now().UTC(),
+				UpdatedAt: time.Now().UTC(),
+			}, nil
+		},
+		getBaseShiftFn: func(_ []byte, _ string) (string, error) {
+			return "06:00-21:00", nil
+		},
+	}
+	h := NewDutyRosterHandler(svc)
+	app := newHemsDutyRosterTestApp(h)
+	body := []byte(`{
+		"data": {
+			"type": "duty_roster_update",
+			"attributes": {
+				"shift_time": {"shift_start":"10:00"}
+			}
+		}
+	}`)
+	resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+mustUUIDStringHemsDutyRoster(t, id), body)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+	if svc.lastUpdateRow == nil {
+		t.Fatalf("expected update row captured")
+	}
+}
+
+func TestBaseDutyRosterHandlerUpdate_PartialShiftTimeKeepsExistingOtherSide(t *testing.T) {
+	id := uuidv7.MustBytes()
+	svc := &hemsDutyRosterServiceMock{
+		getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+			return &dutyroster.HeaderView{
+				ID:        append([]byte(nil), id...),
+				BaseID:    uuidv7.MustBytes(),
+				DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+				CreatedAt: time.Now().UTC(),
+				UpdatedAt: time.Now().UTC(),
+			}, nil
+		},
+		getBaseShiftFn: func(_ []byte, baseType string) (string, error) {
+			if baseType != "base" {
+				t.Fatalf("expected baseType=base, got %q", baseType)
+			}
+			return "06:00-21:00", nil
+		},
+	}
+	h := NewDutyRosterHandler(svc)
+	app := newHemsDutyRosterTestApp(h)
+	body := []byte(`{
+		"data": {
+			"type": "duty_roster_update",
+			"attributes": {
+				"shift_time": {"shift_end":"18:30"}
+			}
+		}
+	}`)
+	resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/base-roster/update/"+mustUUIDStringHemsDutyRoster(t, id), body)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+	if svc.lastUpdateRow == nil {
+		t.Fatalf("expected update row captured")
+	}
+}
+
+func TestHemsDutyRosterHandlerCreate_RejectsInvalidCrewShiftTime(t *testing.T) {
+	svc := &hemsDutyRosterServiceMock{}
+	h := NewDutyRosterHandler(svc)
+	app := newHemsDutyRosterTestApp(h)
+
+	body := []byte(`{
+		"data": {
+			"type": "duty_roster_create",
+			"attributes": {
+				"base_id": "` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `",
+				"duty_date": "2026-03-20",
+				"shift_time": {"shift_start":"06:00","shift_end":"21:00"},
+				"roster_detail": {
+					"pilot": [{
+						"id":"` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `",
+						"shift_time":{"shift_start":"oops","shift_end":"21:00"}
+					}],
+					"doctor": [],
+					"rescuer": [],
+					"helper": [],
+					"other_person": []
+				}
+			}
+		}
+	}`)
+	resp, respBody := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/hems-roster/create", body)
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", resp.StatusCode)
+	}
+	if !strings.Contains(string(respBody), "hems duty roster not found") {
+		t.Fatalf("expected not found response, got %s", string(respBody))
+	}
+}
+
+func TestBuildCrewRows_ShiftTimeBehavior(t *testing.T) {
+	actor := uuidv7.MustBytes()
+
+	rows, errObj := service.BuildDutyRosterCrewRows(dtoHemsDetail(
+		mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()),
+		"",
+	), actor)
+	if errObj != nil {
+		t.Fatalf("unexpected err: %#v", errObj)
+	}
+	if len(rows) != 1 {
+		t.Fatalf("expected 1 row, got %d", len(rows))
+	}
+	if rows[0].ShiftStart != "" || rows[0].ShiftEnd != "" {
+		t.Fatalf("expected empty shift on crew without override, got %q %q", rows[0].ShiftStart, rows[0].ShiftEnd)
+	}
+
+	rows, errObj = service.BuildDutyRosterCrewRows(dtoHemsDetail(
+		mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()),
+		"10:00",
+	), actor)
+	if errObj != nil {
+		t.Fatalf("unexpected err: %#v", errObj)
+	}
+	if rows[0].ShiftStart != "" {
+		t.Fatalf("expected empty crew shift start, got %q", rows[0].ShiftStart)
+	}
+}
+
+func TestHemsDutyRosterResource_UsesHeaderShiftWhenCrewShiftEmpty(t *testing.T) {
+	header := dutyroster.HeaderView{
+		ID:        uuidv7.MustBytes(),
+		BaseID:    uuidv7.MustBytes(),
+		DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}
+	crews := []dutyroster.CrewView{
+		{
+			ID:       uuidv7.MustBytes(),
+			RoleCode: "doctor",
+			Role:     "doctor",
+			Name:     "Doc",
+		},
+	}
+	resource := service.DutyRosterResource(context.Background(), header, crews)
+	if len(resource.Attributes.Detail.Doctor) != 1 {
+		t.Fatalf("expected 1 doctor crew")
+	}
+	shift := resource.Attributes.Detail.Doctor[0].ShiftTime
+	if shift != nil {
+		t.Fatalf("expected fallback shift from header, got %#v", shift)
+	}
+}
+
+func TestNormalizeClockInput(t *testing.T) {
+	t.Run("accept HHMM", func(t *testing.T) {
+		out, errObj := service.NormalizeDutyRosterClockInput("10:00", "06:00:00", "/x")
+		if errObj != nil {
+			t.Fatalf("unexpected error: %#v", errObj)
+		}
+		if out != "10:00:00" {
+			t.Fatalf("expected normalized HH:MM:SS, got %q", out)
+		}
+	})
+
+	t.Run("empty uses default", func(t *testing.T) {
+		out, errObj := service.NormalizeDutyRosterClockInput("", "06:00:00", "/x")
+		if errObj != nil {
+			t.Fatalf("unexpected error: %#v", errObj)
+		}
+		if out != "06:00:00" {
+			t.Fatalf("expected default, got %q", out)
+		}
+	})
+
+	t.Run("invalid rejected", func(t *testing.T) {
+		_, errObj := service.NormalizeDutyRosterClockInput("xx:yy", "06:00:00", "/x")
+		if errObj == nil {
+			t.Fatalf("expected validation error")
+		}
+	})
+}
+
+func TestHemsDutyRosterHandlerList_IncludesEmptyBases(t *testing.T) {
+	baseA := uuidv7.MustBytes()
+	baseB := uuidv7.MustBytes()
+	rosterID := uuidv7.MustBytes()
+	baseAIDStr := mustUUIDStringHemsDutyRoster(t, baseA)
+	baseBIDStr := mustUUIDStringHemsDutyRoster(t, baseB)
+
+	svc := &hemsDutyRosterServiceMock{
+		listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+			return []dutyroster.HeaderView{{
+				ID:               rosterID,
+				BaseID:           baseA,
+				BaseName:         "Base A",
+				BaseAbbreviation: "A",
+				DutyDate:         time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+				CreatedAt:        time.Now().UTC(),
+				UpdatedAt:        time.Now().UTC(),
+			}}, nil
+		},
+		listHEMSBasesFn: func(_ []byte) ([]dutyroster.BaseView, error) {
+			return []dutyroster.BaseView{
+				{ID: baseA, BaseName: "Base A", BaseAbbreviation: "A"},
+				{ID: baseB, BaseName: "Base B", BaseAbbreviation: "B"},
+			}, nil
+		},
+	}
+	h := NewDutyRosterHandler(svc)
+	app := newHemsDutyRosterTestApp(h)
+
+	resp, body := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all?from=2026-03-01&to=2026-03-31", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(body))
+	}
+	if !strings.Contains(string(body), `"total_bases":2`) {
+		t.Fatalf("expected total_bases 2, got %s", string(body))
+	}
+	if !strings.Contains(string(body), `"id":"`+baseAIDStr+`"`) {
+		t.Fatalf("expected base A group in response, got %s", string(body))
+	}
+	if !strings.Contains(string(body), `"id":"`+baseBIDStr+`"`) {
+		t.Fatalf("expected base B group in response, got %s", string(body))
+	}
+	if !strings.Contains(string(body), `"rosters":[]`) {
+		t.Fatalf("expected empty roster group for base without roster, got %s", string(body))
+	}
+}
+
+func TestHemsDutyRosterHandlerListDatatable_DefaultDateRangeMeta(t *testing.T) {
+	svc := &hemsDutyRosterServiceMock{}
+	h := NewDutyRosterHandler(svc)
+	app := newHemsDutyRosterTestApp(h)
+
+	resp, body := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all/dt", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(body))
+	}
+	if !strings.Contains(string(body), `"records_total":0`) {
+		t.Fatalf("expected datatable meta, got %s", string(body))
+	}
+	if !strings.Contains(string(body), `"timezone":"UTC"`) {
+		t.Fatalf("expected timezone meta, got %s", string(body))
+	}
+}
+
+func TestHemsDutyRosterHandlerGetAndDelete(t *testing.T) {
+	t.Run("get invalid uuid", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		app.Get("/api/v1/hems-roster/get/:uuid", h.Get)
+
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get/not-a-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("get success", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+				return &dutyroster.HeaderView{
+					ID:        id,
+					BaseID:    uuidv7.MustBytes(),
+					DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		app.Get("/api/v1/hems-roster/get/:uuid", h.Get)
+
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get/"+mustUUIDStringHemsDutyRoster(t, id), nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete not found", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{deleteErr: gorm.ErrRecordNotFound}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		app.Delete("/api/v1/hems-roster/delete/:id", h.Delete)
+
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/hems-roster/delete/"+mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHemsDutyRosterHandlerCreateAndUpdate_ErrorBranches(t *testing.T) {
+	t.Run("create invalid json", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/hems-roster/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create service error", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{createErr: errors.New("boom")}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+
+		body := []byte(`{
+			"data":{"type":"duty_roster_create","attributes":{
+				"base_id":"` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `",
+				"duty_date":"2026-03-20",
+				"shift_time":{"shift_start":"06:00","shift_end":"21:00"},
+				"roster_detail":{"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}
+			}}
+		}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/hems-roster/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update existing not found", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) { return nil, nil }}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		id := mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes())
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+id, body)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update service not found", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			updateErr: gorm.ErrRecordNotFound,
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+				return &dutyroster.HeaderView{
+					ID:        id,
+					BaseID:    uuidv7.MustBytes(),
+					DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+mustUUIDStringHemsDutyRoster(t, id), body)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHemsDutyRosterHandlerList_ValidationErrors(t *testing.T) {
+	svc := &hemsDutyRosterServiceMock{}
+	h := NewDutyRosterHandler(svc)
+	app := newHemsDutyRosterTestApp(h)
+
+	resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all?from=2026-03-10&to=2026-03-01", nil)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+
+	resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all?from=x&to=2026-03-10", nil)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestBuildCrewRows_ErrorBranches(t *testing.T) {
+	actor := uuidv7.MustBytes()
+	pilotID := mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes())
+
+	_ = pilotID
+
+	_, errObj := service.BuildDutyRosterCrewRows(requestdto.DutyRosterDetailsInput{
+		OtherPerson: []requestdto.DutyRosterOtherPersonInput{{}},
+	}, actor)
+	if errObj == nil || !strings.Contains(errObj.Detail, "other_person name is required") {
+		t.Fatalf("expected other_person name required, got %#v", errObj)
+	}
+
+	_, errObj = service.BuildDutyRosterCrewRows(requestdto.DutyRosterDetailsInput{
+		Pilot: []requestdto.DutyRosterPilotCrewInput{{ID: "not-uuid"}},
+	}, actor)
+	if errObj == nil || !strings.Contains(errObj.Detail, "crew id is invalid UUID") {
+		t.Fatalf("expected invalid crew id, got %#v", errObj)
+	}
+}
+
+func TestDutyRosterHelperFunctionsCoverage(t *testing.T) {
+	if dateToString(nil) != "" {
+		t.Fatalf("expected empty date string")
+	}
+	now := time.Now().UTC()
+	if dateToString(&now) == "" {
+		t.Fatalf("expected non-empty date string")
+	}
+	if bytesEqualUUID([]byte{1, 2}, []byte{1, 2}) != true || bytesEqualUUID([]byte{1, 2}, []byte{1, 3}) != false {
+		t.Fatalf("unexpected bytesEqualUUID")
+	}
+	if bytesEqualUUID([]byte{1}, []byte{1, 2}) {
+		t.Fatalf("expected false on different length")
+	}
+}
+
+func TestDutyRosterHandler_WithAuditAndRequestIDHelpers(t *testing.T) {
+	svc := &hemsDutyRosterServiceMock{}
+	h := NewDutyRosterHandler(svc)
+	if h.WithAudit(&service.AuditLogService{}) != h {
+		t.Fatalf("expected WithAudit to return same handler pointer")
+	}
+
+	app := fiber.New()
+	app.Get("/reqid-locals", func(c *fiber.Ctx) error {
+		c.Locals("requestid", " req-123 ")
+		return c.SendString(requestIDFromCtx(c))
+	})
+	app.Get("/reqid-header", func(c *fiber.Ctx) error {
+		return c.SendString(requestIDFromCtx(c))
+	})
+
+	resp, body := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/reqid-locals", nil)
+	if resp.StatusCode != http.StatusOK || strings.TrimSpace(string(body)) != "req-123" {
+		t.Fatalf("expected request id from locals, got status=%d body=%s", resp.StatusCode, string(body))
+	}
+
+	req, _ := http.NewRequest(http.MethodGet, "/reqid-header", nil)
+	req.Header.Set("X-Request-ID", " hdr-456 ")
+	resp2, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	body2, _ := io.ReadAll(resp2.Body)
+	if resp2.StatusCode != http.StatusOK || strings.TrimSpace(string(body2)) != "hdr-456" {
+		t.Fatalf("expected request id from header, got status=%d body=%s", resp2.StatusCode, string(body2))
+	}
+}
+
+func TestDutyRosterHandler_DeleteCrewBranches(t *testing.T) {
+	rosterID := uuidv7.MustBytes()
+	rosterIDStr := mustUUIDStringHemsDutyRoster(t, rosterID)
+
+	t.Run("invalid uuid", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Delete("/api/v1/hems-roster/:uuid/crew", h.DeleteCrew)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/hems-roster/not-uuid/crew", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid body", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Delete("/api/v1/hems-roster/:uuid/crew", h.DeleteCrew)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/hems-roster/"+rosterIDStr+"/crew", []byte(`{`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("empty crews", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Delete("/api/v1/hems-roster/:uuid/crew", h.DeleteCrew)
+		body := []byte(`{"data":{"attributes":{"roster_detail":{"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/hems-roster/"+rosterIDStr+"/crew", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service error", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			deleteCrewsFn: func(_ context.Context, _ []byte, _ []dutyroster.DutyRosterCrew, _ []byte) ([]dutyroster.DeletedCrewResult, error) {
+				return nil, gorm.ErrRecordNotFound
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Delete("/api/v1/hems-roster/:uuid/crew", h.DeleteCrew)
+		body := []byte(`{"data":{"attributes":{"roster_detail":{"pilot":[{"id":"` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `"}]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/hems-roster/"+rosterIDStr+"/crew", body)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no matched rows", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			deleteCrewsFn: func(_ context.Context, _ []byte, _ []dutyroster.DutyRosterCrew, _ []byte) ([]dutyroster.DeletedCrewResult, error) {
+				return []dutyroster.DeletedCrewResult{}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Delete("/api/v1/hems-roster/:uuid/crew", h.DeleteCrew)
+		body := []byte(`{"data":{"attributes":{"roster_detail":{"pilot":[{"id":"` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `"}]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/hems-roster/"+rosterIDStr+"/crew", body)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success delete crew", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			deleteCrewsFn: func(_ context.Context, _ []byte, _ []dutyroster.DutyRosterCrew, _ []byte) ([]dutyroster.DeletedCrewResult, error) {
+				return []dutyroster.DeletedCrewResult{
+					{ID: uuidv7.MustBytes(), RosterID: rosterID, UserID: uuidv7.MustBytes(), Name: "Pilot X", RoleCode: "pilot", CrewType: "main"},
+				}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Delete("/api/v1/hems-roster/:uuid/crew", h.DeleteCrew)
+		body := []byte(`{"data":{"attributes":{"roster_detail":{"pilot":[{"id":"` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `"}]}}}}`)
+		resp, respBody := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/hems-roster/"+rosterIDStr+"/crew", body)
+		if resp.StatusCode != http.StatusOK || !strings.Contains(string(respBody), `"deleted_count":1`) {
+			t.Fatalf("expected 200 with deleted_count, got status=%d body=%s", resp.StatusCode, string(respBody))
+		}
+	})
+}
+
+func TestDutyRosterHandler_BuildServiceErrorObjectAndMySQLMappings(t *testing.T) {
+	type tc struct {
+		name     string
+		err      error
+		detail   string
+		expected int
+	}
+	cases := []tc{
+		{name: "record not found", err: gorm.ErrRecordNotFound, detail: "not found x", expected: http.StatusNotFound},
+		{name: "context canceled", err: context.Canceled, expected: http.StatusRequestTimeout},
+		{name: "context deadline", err: context.DeadlineExceeded, expected: http.StatusRequestTimeout},
+		{name: "mysql duplicate", err: &mysqldriver.MySQLError{Number: 1062, Message: "Duplicate entry 'x' for key 'idx_roster_base_date'"}, expected: http.StatusConflict},
+		{name: "mysql validation", err: &mysqldriver.MySQLError{Number: 1292, Message: "bad date"}, expected: http.StatusUnprocessableEntity},
+		{name: "mysql default", err: &mysqldriver.MySQLError{Number: 9999, Message: "x"}, expected: http.StatusBadRequest},
+	}
+	for _, cse := range cases {
+		t.Run(cse.name, func(t *testing.T) {
+			app := fiber.New()
+			app.Get("/", func(c *fiber.Ctx) error {
+				status, errObj := buildServiceErrorObject("X", cse.err, cse.detail)
+				return response.WriteErrors(c, status, []jsonapi.ErrorObject{errObj})
+			})
+			resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/", nil)
+			if resp.StatusCode != cse.expected {
+				t.Fatalf("expected %d, got %d", cse.expected, resp.StatusCode)
+			}
+		})
+	}
+
+	appNil := fiber.New()
+	appNil.Get("/", func(c *fiber.Ctx) error {
+		status, errObj := buildServiceErrorObject("X", nil, "")
+		return response.WriteErrors(c, status, []jsonapi.ErrorObject{errObj})
+	})
+	resp, _ := doJSONRequestHemsDutyRoster(t, appNil, http.MethodGet, "/", nil)
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 for nil error branch, got %d", resp.StatusCode)
+	}
+
+	appEmpty := fiber.New()
+	appEmpty.Get("/", func(c *fiber.Ctx) error {
+		status, errObj := buildServiceErrorObject("fallback title", dutyRosterEmptyErr{}, "")
+		return response.WriteErrors(c, status, []jsonapi.ErrorObject{errObj})
+	})
+	resp2, body2 := doJSONRequestHemsDutyRoster(t, appEmpty, http.MethodGet, "/", nil)
+	if resp2.StatusCode != http.StatusBadRequest || !strings.Contains(string(body2), "fallback title") {
+		t.Fatalf("expected fallback title detail, got status=%d body=%s", resp2.StatusCode, string(body2))
+	}
+
+	if dutyRosterFriendlyMySQLError(1452) == "" || mysqlDuplicateKey("x") != "" {
+		t.Fatalf("expected helper mappings to work")
+	}
+
+	for _, code := range []uint16{1048, 1292, 1366, 1451, 1452, 3819, 4025, 9999} {
+		if strings.TrimSpace(dutyRosterFriendlyMySQLError(code)) == "" {
+			t.Fatalf("expected friendly message for mysql code %d", code)
+		}
+	}
+}
+
+func TestDutyRosterHandler_BaseEndpointValidationBranches(t *testing.T) {
+	svc := &hemsDutyRosterServiceMock{}
+	h := NewDutyRosterHandler(svc)
+	app := newDutyRosterFullTestApp(h)
+
+	resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/base-roster/get/not-uuid", nil)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422 for invalid get base uuid, got %d", resp.StatusCode)
+	}
+
+	resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/base-roster/delete/not-uuid", nil)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422 for invalid delete base uuid, got %d", resp.StatusCode)
+	}
+
+	resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/base-roster/not-uuid/crew", []byte(`{}`))
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422 for invalid delete base crew uuid, got %d", resp.StatusCode)
+	}
+
+	resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/base-roster/get-all?base_id=not-uuid", nil)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422 for invalid base_id query, got %d", resp.StatusCode)
+	}
+	resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/base-roster/get-all/dt?base_id=not-uuid", nil)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422 for invalid dt base_id query, got %d", resp.StatusCode)
+	}
+}
+
+func TestDutyRosterHandler_UpdateBaseMoreBranches(t *testing.T) {
+	rosterID := uuidv7.MustBytes()
+	rosterIDStr := mustUUIDStringHemsDutyRoster(t, rosterID)
+	baseID := uuidv7.MustBytes()
+
+	baseHeader := &dutyroster.HeaderView{
+		ID:        rosterID,
+		BaseID:    baseID,
+		DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}
+
+	t.Run("not found existing roster", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) { return nil, nil },
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Patch("/api/v1/base-roster/update/:uuid", h.UpdateBase)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/base-roster/update/"+rosterIDStr, body)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid base id", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) { return baseHeader, nil },
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Patch("/api/v1/base-roster/update/:uuid", h.UpdateBase)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{"base_id":"bad"}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/base-roster/update/"+rosterIDStr, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for bad base_id, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service update error", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			updateErr: errors.New("update failed"),
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+				return baseHeader, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Patch("/api/v1/base-roster/update/:uuid", h.UpdateBase)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/base-roster/update/"+rosterIDStr, body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid duty date and shift time", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) { return baseHeader, nil },
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Patch("/api/v1/base-roster/update/:uuid", h.UpdateBase)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{"duty_date":"bad"}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/base-roster/update/"+rosterIDStr, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid duty_date, got %d", resp.StatusCode)
+		}
+
+		body = []byte(`{"data":{"type":"duty_roster_update","attributes":{"shift_time":{"shift_start":"xx","shift_end":"22:00"}}}}`)
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/base-roster/update/"+rosterIDStr, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid shift, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("resolve default shift error", func(t *testing.T) {
+		emptyShiftHeader := *baseHeader
+		emptyShiftHeader.ShiftStart = ""
+		emptyShiftHeader.ShiftEnd = ""
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) { return &emptyShiftHeader, nil },
+			getBaseShiftFn:  func(_ []byte, _ string) (string, error) { return "", errors.New("shift lookup failed") },
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Patch("/api/v1/base-roster/update/:uuid", h.UpdateBase)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{"shift_time":{"shift_start":"08:00","shift_end":"22:00"}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/base-roster/update/"+rosterIDStr, body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 on shift lookup error, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid crew detail payload", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) { return baseHeader, nil },
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Patch("/api/v1/base-roster/update/:uuid", h.UpdateBase)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{"roster_detail":{"pilot":[{"id":"bad"}]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/base-roster/update/"+rosterIDStr, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid crew id, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestDutyRosterHandler_LogCrewAuditBranch(t *testing.T) {
+	h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{}).WithAudit(&service.AuditLogService{})
+	app := fiber.New()
+	app.Post("/audit", func(c *fiber.Ctx) error {
+		h.logCrewAudit(c, "duty_roster.crew.append", uuidv7.MustBytes(), "hems", []dutyroster.DutyRosterCrew{{RoleCode: "pilot"}}, "msg")
+		return c.SendStatus(http.StatusOK)
+	})
+	resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/audit", []byte(`{}`))
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestDutyRosterHandler_RespondByIDBaseTypeBranches(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr := mustUUIDStringHemsDutyRoster(t, id)
+	baseID := uuidv7.MustBytes()
+	header := &dutyroster.HeaderView{
+		ID:               id,
+		BaseID:           baseID,
+		BaseName:         "Base A",
+		BaseAbbreviation: "BA",
+		DutyDate:         time.Date(2026, 3, 21, 0, 0, 0, 0, time.UTC),
+		CreatedAt:        time.Now().UTC(),
+		UpdatedAt:        time.Now().UTC(),
+	}
+
+	t.Run("header error", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) { return nil, errors.New("boom") }}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Get("/x/:uuid", func(c *fiber.Ctx) error { return h.respondByIDBaseType(c, http.StatusOK, id, "base") })
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/x/"+idStr, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("header nil", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) { return nil, nil }}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Get("/x/:uuid", func(c *fiber.Ctx) error { return h.respondByIDBaseType(c, http.StatusOK, id, "base") })
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/x/"+idStr, nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("crews error", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn:      func(_ []byte) (*dutyroster.HeaderView, error) { return header, nil },
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) { return nil, errors.New("boom") },
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Get("/x/:uuid", func(c *fiber.Ctx) error { return h.respondByIDBaseType(c, http.StatusOK, id, "base") })
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/x/"+idStr, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("base and hems response", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn:      func(_ []byte) (*dutyroster.HeaderView, error) { return header, nil },
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) { return []dutyroster.CrewView{}, nil },
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Get("/x-base/:uuid", func(c *fiber.Ctx) error { return h.respondByIDBaseType(c, http.StatusOK, id, "base") })
+		app.Get("/x-hems/:uuid", func(c *fiber.Ctx) error { return h.respondByIDBaseType(c, http.StatusOK, id, "hems") })
+		resp, body := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/x-base/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK || !strings.Contains(string(body), `"type":"base_duty_roster"`) {
+			t.Fatalf("expected base type response, got status=%d body=%s", resp.StatusCode, string(body))
+		}
+		resp, body = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/x-hems/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK || !strings.Contains(string(body), `"type":"duty_roster"`) {
+			t.Fatalf("expected duty roster type response, got status=%d body=%s", resp.StatusCode, string(body))
+		}
+	})
+}
+
+func TestDutyRosterHandler_RespondByIDBranches(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr := mustUUIDStringHemsDutyRoster(t, id)
+	baseID := uuidv7.MustBytes()
+	header := &dutyroster.HeaderView{
+		ID:               id,
+		BaseID:           baseID,
+		BaseName:         "HB",
+		BaseAbbreviation: "HB",
+		DutyDate:         time.Date(2026, 3, 22, 0, 0, 0, 0, time.UTC),
+		CreatedAt:        time.Now().UTC(),
+		UpdatedAt:        time.Now().UTC(),
+	}
+
+	t.Run("header nil", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) { return nil, nil }})
+		app := fiber.New()
+		app.Get("/x/:uuid", func(c *fiber.Ctx) error { return h.respondByID(c, http.StatusOK, id) })
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/x/"+idStr, nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("crews error", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{
+			getHeaderByIDFn:      func(_ []byte) (*dutyroster.HeaderView, error) { return header, nil },
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) { return nil, errors.New("boom") },
+		})
+		app := fiber.New()
+		app.Get("/x/:uuid", func(c *fiber.Ctx) error { return h.respondByID(c, http.StatusOK, id) })
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/x/"+idStr, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{
+			getHeaderByIDFn:      func(_ []byte) (*dutyroster.HeaderView, error) { return header, nil },
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) { return []dutyroster.CrewView{}, nil },
+		})
+		app := fiber.New()
+		app.Get("/x/:uuid", func(c *fiber.Ctx) error { return h.respondByID(c, http.StatusOK, id) })
+		resp, body := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/x/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK || !strings.Contains(string(body), `"type":"duty_roster"`) {
+			t.Fatalf("expected duty roster response, got status=%d body=%s", resp.StatusCode, string(body))
+		}
+	})
+}
+
+func TestDutyRosterHandler_CreateBaseMoreBranches(t *testing.T) {
+	baseID := mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes())
+	svc := &hemsDutyRosterServiceMock{
+		getHeaderByIDFn:      func(_ []byte) (*dutyroster.HeaderView, error) { return nil, nil },
+		getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) { return []dutyroster.CrewView{}, nil },
+	}
+	h := NewDutyRosterHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/base-roster/create", h.CreateBase)
+
+	resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/base-roster/create", []byte(`{`))
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 invalid json, got %d", resp.StatusCode)
+	}
+
+	body := []byte(`{"data":{"type":"duty_roster_create","attributes":{"base_id":"bad","duty_date":"2026-03-20","roster_detail":{"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}}}}`)
+	resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/base-roster/create", body)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422 invalid base_id, got %d", resp.StatusCode)
+	}
+
+	body = []byte(`{"data":{"type":"duty_roster_create","attributes":{"base_id":"` + baseID + `","duty_date":"bad","roster_detail":{"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}}}}`)
+	resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/base-roster/create", body)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422 invalid duty_date, got %d", resp.StatusCode)
+	}
+
+	svcShiftErr := &hemsDutyRosterServiceMock{
+		getBaseShiftFn: func(_ []byte, _ string) (string, error) { return "", errors.New("base shift error") },
+	}
+	hShiftErr := NewDutyRosterHandler(svcShiftErr)
+	appShiftErr := fiber.New()
+	appShiftErr.Post("/api/v1/base-roster/create", hShiftErr.CreateBase)
+	body = []byte(`{"data":{"type":"duty_roster_create","attributes":{"base_id":"` + baseID + `","duty_date":"2026-03-20","roster_detail":{"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}}}}`)
+	resp, _ = doJSONRequestHemsDutyRoster(t, appShiftErr, http.MethodPost, "/api/v1/base-roster/create", body)
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 on base shift lookup error, got %d", resp.StatusCode)
+	}
+
+	svcCreateErr := &hemsDutyRosterServiceMock{
+		createErr: errors.New("create fail"),
+	}
+	hCreateErr := NewDutyRosterHandler(svcCreateErr)
+	appCreateErr := fiber.New()
+	appCreateErr.Post("/api/v1/base-roster/create", hCreateErr.CreateBase)
+	resp, _ = doJSONRequestHemsDutyRoster(t, appCreateErr, http.MethodPost, "/api/v1/base-roster/create", body)
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 on create error, got %d", resp.StatusCode)
+	}
+}
+
+func TestDutyRosterHandler_DeleteBaseCrewMoreBranches(t *testing.T) {
+	rosterID := mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes())
+
+	t.Run("invalid payload", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := fiber.New()
+		app.Delete("/api/v1/base-roster/:uuid/crew", h.DeleteBaseCrew)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/base-roster/"+rosterID+"/crew", []byte(`{`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid payload, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service error and not found", func(t *testing.T) {
+		svcErr := &hemsDutyRosterServiceMock{
+			deleteCrewsFn: func(_ context.Context, _ []byte, _ []dutyroster.DutyRosterCrew, _ []byte) ([]dutyroster.DeletedCrewResult, error) {
+				return nil, errors.New("delete failed")
+			},
+		}
+		hErr := NewDutyRosterHandler(svcErr)
+		appErr := fiber.New()
+		appErr.Delete("/api/v1/base-roster/:uuid/crew", hErr.DeleteBaseCrew)
+		body := []byte(`{"data":{"attributes":{"roster_detail":{"pilot":[{"id":"` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `"}]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, appErr, http.MethodDelete, "/api/v1/base-roster/"+rosterID+"/crew", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 service error, got %d", resp.StatusCode)
+		}
+
+		svcNotFound := &hemsDutyRosterServiceMock{
+			deleteCrewsFn: func(_ context.Context, _ []byte, _ []dutyroster.DutyRosterCrew, _ []byte) ([]dutyroster.DeletedCrewResult, error) {
+				return []dutyroster.DeletedCrewResult{}, nil
+			},
+		}
+		hNotFound := NewDutyRosterHandler(svcNotFound)
+		appNotFound := fiber.New()
+		appNotFound.Delete("/api/v1/base-roster/:uuid/crew", hNotFound.DeleteBaseCrew)
+		resp, _ = doJSONRequestHemsDutyRoster(t, appNotFound, http.MethodDelete, "/api/v1/base-roster/"+rosterID+"/crew", body)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 no match, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestDutyRosterHandler_ListBaseMoreBranches(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	baseIDStr := mustUUIDStringHemsDutyRoster(t, baseID)
+	headerID := uuidv7.MustBytes()
+
+	t.Run("to before from", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := fiber.New()
+		app.Get("/api/v1/base-roster/get-all", h.ListBase)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/base-roster/get-all?from=2026-03-20&to=2026-03-10", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 to<from, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("list headers error", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+				return nil, errors.New("list headers failed")
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Get("/api/v1/base-roster/get-all", h.ListBase)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/base-roster/get-all?base_id="+baseIDStr+"&from=2026-03-01&to=2026-03-31", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 list headers error, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("list bases or crews error", func(t *testing.T) {
+		svcBases := &hemsDutyRosterServiceMock{
+			listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+				return []dutyroster.HeaderView{{ID: headerID, BaseID: baseID, DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)}}, nil
+			},
+			listHEMSBasesFn: func(_ []byte) ([]dutyroster.BaseView, error) { return nil, errors.New("bases failed") },
+		}
+		hBases := NewDutyRosterHandler(svcBases)
+		appBases := fiber.New()
+		appBases.Get("/api/v1/base-roster/get-all", hBases.ListBase)
+		resp, _ := doJSONRequestHemsDutyRoster(t, appBases, http.MethodGet, "/api/v1/base-roster/get-all?from=2026-03-01&to=2026-03-31", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 list bases error, got %d", resp.StatusCode)
+		}
+
+		svcCrews := &hemsDutyRosterServiceMock{
+			listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+				return []dutyroster.HeaderView{{ID: headerID, BaseID: baseID, DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)}}, nil
+			},
+			listHEMSBasesFn: func(_ []byte) ([]dutyroster.BaseView, error) {
+				return []dutyroster.BaseView{{ID: baseID, BaseName: "B1", BaseAbbreviation: "B1"}}, nil
+			},
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) { return nil, errors.New("crews failed") },
+		}
+		hCrews := NewDutyRosterHandler(svcCrews)
+		appCrews := fiber.New()
+		appCrews.Get("/api/v1/base-roster/get-all", hCrews.ListBase)
+		resp, _ = doJSONRequestHemsDutyRoster(t, appCrews, http.MethodGet, "/api/v1/base-roster/get-all?from=2026-03-01&to=2026-03-31", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 list crews error, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("datatable list errors", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+				return nil, errors.New("list failed")
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := fiber.New()
+		app.Get("/api/v1/base-roster/get-all/dt", h.ListBaseDatatable)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/base-roster/get-all/dt?from=2026-03-01&to=2026-03-31", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 list dt headers error, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHemsDutyRosterHandlerGetDeleteAndRespondByID_Branches(t *testing.T) {
+	t.Run("get service error", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) { return nil, errors.New("boom") },
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		app.Get("/api/v1/hems-roster/get/:uuid", h.Get)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get/"+mustUUIDStringHemsDutyRoster(t, id), nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete invalid uuid", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		app.Delete("/api/v1/hems-roster/delete/:id", h.Delete)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/hems-roster/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete generic error", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{deleteErr: errors.New("x")}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		app.Delete("/api/v1/hems-roster/delete/:id", h.Delete)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/hems-roster/delete/"+mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()), nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete success", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		app.Delete("/api/v1/hems-roster/delete/:id", h.Delete)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/hems-roster/delete/"+mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHemsDutyRosterHandlerUpdate_Branches(t *testing.T) {
+	t.Run("invalid path uuid", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := newHemsDutyRosterTestApp(h)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid body json", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := newHemsDutyRosterTestApp(h)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()), []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid data id uuid", func(t *testing.T) {
+		id := mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes())
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_update","id":"not-uuid","attributes":{}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+}
+
+func TestBuildCrewRows_MoreBranches(t *testing.T) {
+	actor := uuidv7.MustBytes()
+	id := mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes())
+
+	_, errObj := service.BuildDutyRosterCrewRows(requestdto.DutyRosterDetailsInput{
+		Pilot: []requestdto.DutyRosterPilotCrewInput{
+			{ID: id},
+			{ID: id},
+		},
+	}, actor)
+	if errObj == nil || !strings.Contains(errObj.Detail, "duplicate crew assignment") {
+		t.Fatalf("expected duplicate error, got %#v", errObj)
+	}
+
+	_, errObj = service.BuildDutyRosterCrewRows(requestdto.DutyRosterDetailsInput{
+		Pilot: []requestdto.DutyRosterPilotCrewInput{
+			{
+				ID: id,
+				ShiftDate: &requestdto.DutyRosterShiftDate{
+					DateStart: "bad-date",
+				},
+			},
+		},
+	}, actor)
+	if errObj == nil || !strings.Contains(errObj.Detail, "ERR_DUTY_ROSTER_SHIFT_DATE_START_FORMAT") {
+		t.Fatalf("expected date_start error, got %#v", errObj)
+	}
+
+	_, errObj = service.BuildDutyRosterCrewRows(requestdto.DutyRosterDetailsInput{
+		Pilot: []requestdto.DutyRosterPilotCrewInput{
+			{
+				ID: id,
+				ShiftDate: &requestdto.DutyRosterShiftDate{
+					DateEnd: "bad-date",
+				},
+			},
+		},
+	}, actor)
+	if errObj == nil || !strings.Contains(errObj.Detail, "ERR_DUTY_ROSTER_SHIFT_DATE_END_FORMAT") {
+		t.Fatalf("expected date_end error, got %#v", errObj)
+	}
+}
+
+func TestGroupAndMergeHelpers_Branches(t *testing.T) {
+	items := []responsedto.DutyRosterResource{
+		{
+			ID: "r1",
+			Attributes: responsedto.DutyRosterAttributes{
+				Bases: responsedto.DutyRosterBaseInfo{BaseName: "Unknown"},
+			},
+		},
+	}
+	grouped := service.GroupRostersByBase(items)
+	if len(grouped) != 1 {
+		t.Fatalf("unexpected grouped result: %#v", grouped)
+	}
+
+	merged := service.MergeEmptyBaseGroups(grouped, []dutyroster.BaseView{
+		{ID: uuidv7.MustBytes(), BaseName: "Base X"},
+	})
+	if len(merged) != 2 {
+		t.Fatalf("expected merged groups 2, got %d", len(merged))
+	}
+
+	merged = service.MergeEmptyBaseGroups(grouped, []dutyroster.BaseView{
+		{ID: nil, BaseName: "No ID"},
+	})
+	if len(merged) != 1 {
+		t.Fatalf("expected groups unchanged when base id empty, got %d", len(merged))
+	}
+}
+
+func dtoHemsDetail(userID, shiftStart string) requestdto.DutyRosterDetailsInput {
+	item := requestdto.DutyRosterPilotCrewInput{ID: userID}
+	return requestdto.DutyRosterDetailsInput{
+		Pilot:       []requestdto.DutyRosterPilotCrewInput{item},
+		Doctor:      []requestdto.DutyRosterCrewInput{},
+		Rescuer:     []requestdto.DutyRosterCrewInput{},
+		Helper:      []requestdto.DutyRosterCrewInput{},
+		OtherPerson: []requestdto.DutyRosterOtherPersonInput{},
+	}
+}
+
+func TestHemsDutyRosterHandlerCreate_MoreBranches(t *testing.T) {
+	t.Run("validation error", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := newHemsDutyRosterTestApp(h)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/hems-roster/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid base uuid", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_create","attributes":{"base_id":"x","duty_date":"2026-03-20","roster_detail":{"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/hems-roster/create", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid duty date", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_create","attributes":{"base_id":"` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `","duty_date":"20-03-2026","roster_detail":{"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/hems-roster/create", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid header shift start", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_create","attributes":{"base_id":"` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `","duty_date":"2026-03-20","shift_time":{"shift_start":"bad","shift_end":"21:00"},"roster_detail":{"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/hems-roster/create", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid header shift end", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_create","attributes":{"base_id":"` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `","duty_date":"2026-03-20","shift_time":{"shift_start":"06:00","shift_end":"bad"},"roster_detail":{"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/hems-roster/create", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+				return &dutyroster.HeaderView{
+					ID:        append([]byte(nil), id...),
+					BaseID:    uuidv7.MustBytes(),
+					DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}, nil
+			},
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) {
+				return []dutyroster.CrewView{}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_create","attributes":{"base_id":"` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `","duty_date":"2026-03-20","shift_time":{"shift_start":"10:00","shift_end":"22:00"},"roster_detail":{"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/hems-roster/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if svc.lastCreateRow == nil {
+			t.Fatalf("expected create row")
+		}
+	},
+	)
+
+	t.Run("fallback shift from base default", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		baseID := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			getBaseShiftFn: func(_ []byte, _ string) (string, error) {
+				return "09:30-20:15", nil
+			},
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+				return &dutyroster.HeaderView{
+					ID:        append([]byte(nil), id...),
+					BaseID:    append([]byte(nil), baseID...),
+					DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}, nil
+			},
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) {
+				return []dutyroster.CrewView{}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_create","attributes":{"base_id":"` + mustUUIDStringHemsDutyRoster(t, baseID) + `","duty_date":"2026-03-20","roster_detail":{"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/hems-roster/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if svc.lastCreateRow == nil {
+			t.Fatalf("expected create row")
+		}
+	})
+}
+
+func TestHemsDutyRosterHandlerUpdate_MoreBranches(t *testing.T) {
+	t.Run("validation error", func(t *testing.T) {
+		id := mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes())
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := newHemsDutyRosterTestApp(h)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+id, []byte(`{}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("existing fetch error", func(t *testing.T) {
+		id := mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes())
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) { return nil, errors.New("get failed") },
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+id, []byte(`{"data":{"type":"duty_roster_update","attributes":{}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid base id in attrs", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+				return &dutyroster.HeaderView{ID: id, BaseID: uuidv7.MustBytes(), DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{"base_id":"bad"}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+mustUUIDStringHemsDutyRoster(t, id), body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid duty date in attrs", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+				return &dutyroster.HeaderView{ID: id, BaseID: uuidv7.MustBytes(), DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{"duty_date":"20-03-2026"}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+mustUUIDStringHemsDutyRoster(t, id), body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid shift end in attrs", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+				return &dutyroster.HeaderView{
+					ID:       id,
+					BaseID:   uuidv7.MustBytes(),
+					DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+				}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{"shift_time":{"shift_start":"10:00","shift_end":"bad"}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+mustUUIDStringHemsDutyRoster(t, id), body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid hems_detail payload", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+				return &dutyroster.HeaderView{ID: id, BaseID: uuidv7.MustBytes(), DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{"roster_detail":{"pilot":[{"id":"` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `","shift_time":{"shift_start":"10:00","shift_end":"bad"}}],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+mustUUIDStringHemsDutyRoster(t, id), body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("service generic error", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			updateErr: errors.New("boom"),
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+				return &dutyroster.HeaderView{ID: id, BaseID: uuidv7.MustBytes(), DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+mustUUIDStringHemsDutyRoster(t, id), body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with attrs", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		newBaseID := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+				return &dutyroster.HeaderView{
+					ID:        id,
+					BaseID:    uuidv7.MustBytes(),
+					DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}, nil
+			},
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) {
+				return []dutyroster.CrewView{}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		body := []byte(`{"data":{"type":"duty_roster_update","attributes":{"base_id":"` + mustUUIDStringHemsDutyRoster(t, newBaseID) + `","duty_date":"2026-03-21","roster_detail":{"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}}}}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPatch, "/api/v1/hems-roster/update/"+mustUUIDStringHemsDutyRoster(t, id), body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.lastUpdateRow == nil || !bytesEqualUUID(svc.lastUpdateRow.BaseID, newBaseID) {
+			t.Fatalf("expected base id updated")
+		}
+	})
+}
+
+func TestHemsDutyRosterHandlerListAndDatatable_MoreBranches(t *testing.T) {
+	t.Run("list invalid base query", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := newHemsDutyRosterTestApp(h)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all?hems_base_id=bad", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("list service errors", func(t *testing.T) {
+		svc := &hemsDutyRosterServiceMock{
+			listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) { return nil, errors.New("h") },
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all?from=2026-03-01&to=2026-03-31", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+
+		svc = &hemsDutyRosterServiceMock{
+			listHEMSBasesFn: func(_ []byte) ([]dutyroster.BaseView, error) { return nil, errors.New("b") },
+			listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+				return []dutyroster.HeaderView{}, nil
+			},
+		}
+		h = NewDutyRosterHandler(svc)
+		app = newHemsDutyRosterTestApp(h)
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all?from=2026-03-01&to=2026-03-31", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+
+		headerID := uuidv7.MustBytes()
+		svc = &hemsDutyRosterServiceMock{
+			listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+				return []dutyroster.HeaderView{{ID: headerID, BaseID: uuidv7.MustBytes(), DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)}}, nil
+			},
+			listHEMSBasesFn:      func(_ []byte) ([]dutyroster.BaseView, error) { return []dutyroster.BaseView{}, nil },
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) { return nil, errors.New("c") },
+		}
+		h = NewDutyRosterHandler(svc)
+		app = newHemsDutyRosterTestApp(h)
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all?from=2026-03-01&to=2026-03-31", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("list with crew mapping", func(t *testing.T) {
+		headerID := uuidv7.MustBytes()
+		baseID := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+				return []dutyroster.HeaderView{{
+					ID:        headerID,
+					BaseID:    baseID,
+					DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}}, nil
+			},
+			listHEMSBasesFn: func(_ []byte) ([]dutyroster.BaseView, error) {
+				return []dutyroster.BaseView{{ID: baseID, BaseName: "B", BaseAbbreviation: "B"}}, nil
+			},
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) {
+				return []dutyroster.CrewView{{RosterID: headerID, RoleCode: "doctor", Role: "doctor", Name: "Doc"}}, nil
+			},
+		}
+		h := NewDutyRosterHandler(svc)
+		app := newHemsDutyRosterTestApp(h)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all?from=2026-03-01&to=2026-03-31", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("datatable more branches", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{})
+		app := newHemsDutyRosterTestApp(h)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all/dt?hems_base_id=bad", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all/dt?from=bad", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all/dt?from=2026-03-01&to=bad", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all/dt?from=2026-03-10&to=2026-03-01", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+
+		baseID := uuidv7.MustBytes()
+		headerID := uuidv7.MustBytes()
+		svc := &hemsDutyRosterServiceMock{
+			listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+				return []dutyroster.HeaderView{{
+					ID:        headerID,
+					BaseID:    baseID,
+					DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}}, nil
+			},
+			listHEMSBasesFn: func(_ []byte) ([]dutyroster.BaseView, error) {
+				return []dutyroster.BaseView{{ID: baseID, BaseName: "B"}}, nil
+			},
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) {
+				return []dutyroster.CrewView{{RosterID: headerID, RoleCode: "rescuer", Role: "rescuer"}}, nil
+			},
+		}
+		h = NewDutyRosterHandler(svc)
+		app = newHemsDutyRosterTestApp(h)
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all/dt?page=0&size=-1&draw=7", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all/dt?limit=101", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all/dt?page=99&limit=20", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+
+		svc = &hemsDutyRosterServiceMock{
+			listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) { return nil, errors.New("headers") },
+		}
+		h = NewDutyRosterHandler(svc)
+		app = newHemsDutyRosterTestApp(h)
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+
+		svc = &hemsDutyRosterServiceMock{
+			listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+				return []dutyroster.HeaderView{}, nil
+			},
+			listHEMSBasesFn: func(_ []byte) ([]dutyroster.BaseView, error) { return nil, errors.New("bases") },
+		}
+		h = NewDutyRosterHandler(svc)
+		app = newHemsDutyRosterTestApp(h)
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+
+		headerID = uuidv7.MustBytes()
+		svc = &hemsDutyRosterServiceMock{
+			listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+				return []dutyroster.HeaderView{{ID: headerID, BaseID: uuidv7.MustBytes(), DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)}}, nil
+			},
+			listHEMSBasesFn:      func(_ []byte) ([]dutyroster.BaseView, error) { return []dutyroster.BaseView{}, nil },
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) { return nil, errors.New("crews") },
+		}
+		h = NewDutyRosterHandler(svc)
+		app = newHemsDutyRosterTestApp(h)
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestRespondByID_MoreBranches(t *testing.T) {
+	t.Run("not found", func(t *testing.T) {
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) { return nil, nil },
+		})
+		app := fiber.New()
+		app.Get("/x/:id", func(c *fiber.Ctx) error { return h.respondByID(c, http.StatusOK, uuidv7.MustBytes()) })
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/x/1", nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("crew fetch error", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		h := NewDutyRosterHandler(&hemsDutyRosterServiceMock{
+			getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+				return &dutyroster.HeaderView{ID: id, BaseID: uuidv7.MustBytes(), DutyDate: time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)}, nil
+			},
+			getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) { return nil, errors.New("x") },
+		})
+		app := fiber.New()
+		app.Get("/x/:id", func(c *fiber.Ctx) error { return h.respondByID(c, http.StatusOK, id) })
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/x/1", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHemsDutyRosterResource_AllRoleBuckets(t *testing.T) {
+	dStart := time.Date(2026, 3, 19, 0, 0, 0, 0, time.UTC)
+	dEnd := time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC)
+	header := dutyroster.HeaderView{
+		ID:        uuidv7.MustBytes(),
+		BaseID:    uuidv7.MustBytes(),
+		DutyDate:  time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}
+	crews := []dutyroster.CrewView{
+		{
+			ID:               uuidv7.MustBytes(),
+			RoleCode:         "pilot",
+			Role:             "pilot",
+			CrewType:         "additional",
+			Name:             "Pilot A",
+			FlightInstructor: true,
+			LineChecker:      true,
+			Supervisor:       true,
+			Examiner:         true,
+			CoPilot:          true,
+			DateStart:        &dStart,
+			DateEnd:          &dEnd,
+		},
+		{ID: uuidv7.MustBytes(), RoleCode: "doctor", Role: "doctor"},
+		{ID: uuidv7.MustBytes(), RoleCode: "doctor", Role: "doctor"},
+		{ID: uuidv7.MustBytes(), RoleCode: "air_rescuer", Role: "rescuer"},
+		{ID: uuidv7.MustBytes(), RoleCode: "flight_assistant", Role: "helper"},
+		{ID: uuidv7.MustBytes(), RoleCode: "other_person", Role: "other", DateStart: &dStart},
+		{ID: uuidv7.MustBytes(), RoleCode: "other_person", Role: "other", DateStart: &dStart},
+	}
+	out := service.DutyRosterResource(context.Background(), header, crews)
+	if len(out.Attributes.Detail.Pilot) != 1 || len(out.Attributes.Detail.Doctor) != 2 || len(out.Attributes.Detail.Rescuer) != 1 || len(out.Attributes.Detail.Helper) != 1 || len(out.Attributes.Detail.OtherPerson) != 2 {
+		t.Fatalf("unexpected crew buckets: %#v", out.Attributes.Detail)
+	}
+	pilot := out.Attributes.Detail.Pilot[0]
+	if pilot.FlightInstructor == nil || !*pilot.FlightInstructor {
+		t.Fatalf("expected pilot flags, got %#v", pilot)
+	}
+	if out.Attributes.Detail.Doctor[0].ShiftTime != nil {
+		t.Fatalf("expected doctor own shift to be omitted")
+	}
+	if out.Attributes.Detail.OtherPerson[0].ShiftTime != nil || out.Attributes.Detail.OtherPerson[0].ShiftDate != nil {
+		t.Fatalf("expected other_person shift/date omitted")
+	}
+}
+
+func TestBuildCrewRows_SuccessBranches(t *testing.T) {
+	actor := uuidv7.MustBytes()
+	id := mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes())
+	rows, errObj := service.BuildDutyRosterCrewRows(requestdto.DutyRosterDetailsInput{
+		Pilot: []requestdto.DutyRosterPilotCrewInput{
+			{
+				ID:               id,
+				CrewType:         "additional",
+				FlightInstructor: true,
+				LineChecker:      true,
+				Supervisor:       true,
+				Examiner:         true,
+				CoPilot:          true,
+				ShiftDate:        &requestdto.DutyRosterShiftDate{DateStart: "2026-03-20", DateEnd: "2026-03-21"},
+			},
+		},
+		OtherPerson: []requestdto.DutyRosterOtherPersonInput{
+			{
+				Name: "Guest",
+			},
+		},
+	}, actor)
+	if errObj != nil {
+		t.Fatalf("unexpected err: %#v", errObj)
+	}
+	if len(rows) != 2 {
+		t.Fatalf("expected 2 rows, got %d", len(rows))
+	}
+	if !rows[0].FlightInstructor || !rows[0].LineChecker || !rows[0].Supervisor || !rows[0].Examiner || !rows[0].CoPilot {
+		t.Fatalf("expected additional pilot flags set")
+	}
+	if rows[0].DateStart == nil || rows[0].DateEnd == nil {
+		t.Fatalf("expected pilot date range set")
+	}
+	if rows[1].RoleCode != "other_person" || rows[1].DateStart != nil || rows[1].ShiftStart != "" {
+		t.Fatalf("expected other_person shift/date cleared, got %#v", rows[1])
+	}
+}
+
+func TestBuildCrewRows_RescuerAndHelperDefaultMain(t *testing.T) {
+	actor := uuidv7.MustBytes()
+	id := mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes())
+
+	rows, errObj := service.BuildDutyRosterCrewRows(requestdto.DutyRosterDetailsInput{
+		Rescuer: []requestdto.DutyRosterCrewInput{{ID: id}},
+		Helper:  []requestdto.DutyRosterCrewInput{{ID: id}},
+	}, actor)
+	if errObj != nil {
+		t.Fatalf("unexpected error: %#v", errObj)
+	}
+	for i := range rows {
+		if rows[i].RoleCode != "rescuer" && rows[i].RoleCode != "helper" {
+			continue
+		}
+		if rows[i].CrewType != "main" {
+			t.Fatalf("expected non-pilot crew_type main, got %q", rows[i].CrewType)
+		}
+	}
+}
+
+func TestDutyRosterDuplicateDetail(t *testing.T) {
+	t.Run("known roster key", func(t *testing.T) {
+		got := dutyRosterDuplicateDetail("Error 1062 (23000): Duplicate entry 'x' for key 'idx_roster_base_date'")
+		if !strings.Contains(got, "selected base and duty date") {
+			t.Fatalf("unexpected detail: %s", got)
+		}
+	})
+
+	t.Run("known crew key with table prefix", func(t *testing.T) {
+		got := dutyRosterDuplicateDetail("Error 1062 (23000): Duplicate entry 'x' for key 'duty_roster_crews.idx_roster_crew_unique'")
+		if !strings.Contains(got, "crew assignment already exists") {
+			t.Fatalf("unexpected detail: %s", got)
+		}
+	})
+
+	t.Run("unknown key fallback", func(t *testing.T) {
+		got := dutyRosterDuplicateDetail("Error 1062 (23000): Duplicate entry 'x' for key 'uniq_anything'")
+		if !strings.Contains(got, "data conflict") {
+			t.Fatalf("unexpected detail: %s", got)
+		}
+	})
+}
+
+func TestDutyRosterHandler_BaseEndpointsCoverage(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	rosterID := uuidv7.MustBytes()
+	baseIDStr := mustUUIDStringHemsDutyRoster(t, baseID)
+	rosterIDStr := mustUUIDStringHemsDutyRoster(t, rosterID)
+	svc := &hemsDutyRosterServiceMock{
+		getBaseShiftFn: func(_ []byte, _ string) (string, error) { return "06:00-21:00", nil },
+		getHeaderByIDFn: func(_ []byte) (*dutyroster.HeaderView, error) {
+			return &dutyroster.HeaderView{
+				ID:               rosterID,
+				BaseID:           baseID,
+				BaseName:         "Base Alpha",
+				BaseAbbreviation: "BA",
+				DutyDate:         time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+				CreatedAt:        time.Now().UTC(),
+				UpdatedAt:        time.Now().UTC(),
+			}, nil
+		},
+		getCrewsByRosterIDFn: func(_ [][]byte) ([]dutyroster.CrewView, error) {
+			return []dutyroster.CrewView{
+				{ID: uuidv7.MustBytes(), UserID: uuidv7.MustBytes(), Name: "Pilot Base", RoleCode: "pilot", Role: "pilot", CrewType: "main"},
+			}, nil
+		},
+		listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+			return []dutyroster.HeaderView{
+				{
+					ID:               rosterID,
+					BaseID:           baseID,
+					BaseName:         "Base Alpha",
+					BaseAbbreviation: "BA",
+					DutyDate:         time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+					CreatedAt:        time.Now().UTC(),
+					UpdatedAt:        time.Now().UTC(),
+				},
+			}, nil
+		},
+		listHEMSBasesFn: func(_ []byte) ([]dutyroster.BaseView, error) {
+			return []dutyroster.BaseView{{ID: baseID, BaseName: "Base Alpha", BaseAbbreviation: "BA"}}, nil
+		},
+		deleteCrewsFn: func(_ context.Context, _ []byte, _ []dutyroster.DutyRosterCrew, _ []byte) ([]dutyroster.DeletedCrewResult, error) {
+			return []dutyroster.DeletedCrewResult{
+				{ID: uuidv7.MustBytes(), RosterID: rosterID, UserID: uuidv7.MustBytes(), Name: "Pilot Base", RoleCode: "pilot", CrewType: "main"},
+			}, nil
+		},
+	}
+
+	h := NewDutyRosterHandler(svc)
+	app := newDutyRosterFullTestApp(h)
+
+	t.Run("create base", func(t *testing.T) {
+		body := []byte(`{
+			"data": {
+				"type": "duty_roster_create",
+				"attributes": {
+					"base_id": "` + baseIDStr + `",
+					"duty_date": "2026-03-20",
+					"roster_detail": {"pilot":[],"doctor":[],"rescuer":[],"helper":[],"other_person":[]}
+				}
+			}
+		}`)
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodPost, "/api/v1/base-roster/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("get base", func(t *testing.T) {
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/base-roster/get/"+rosterIDStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete base", func(t *testing.T) {
+		resp, _ := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/base-roster/delete/"+rosterIDStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete base crew", func(t *testing.T) {
+		body := []byte(`{"data":{"type":"duty_roster_crew_delete","attributes":{"roster_detail":{"pilot":[{"id":"` + mustUUIDStringHemsDutyRoster(t, uuidv7.MustBytes()) + `","shift_date":{"date_start":"2026-03-20","date_end":"2026-03-20"}}]}}}}`)
+		resp, respBody := doJSONRequestHemsDutyRoster(t, app, http.MethodDelete, "/api/v1/base-roster/"+rosterIDStr+"/crew", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		if !strings.Contains(string(respBody), `"name":"Pilot Base"`) {
+			t.Fatalf("expected deleted crew name in response, got %s", string(respBody))
+		}
+	})
+
+	t.Run("list base and dt", func(t *testing.T) {
+		resp, body := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/base-roster/get-all?from=2026-03-01&to=2026-03-31&base_name=alpha", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if !strings.Contains(strings.ToLower(string(body)), "base alpha") {
+			t.Fatalf("expected filtered base name in response, got %s", string(body))
+		}
+		resp, _ = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/base-roster/get-all/dt?from=2026-03-01&to=2026-03-31&page=1&size=10&base_name=alpha", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHemsDutyRosterHandlerList_FilterByBaseName(t *testing.T) {
+	baseAlpha := uuidv7.MustBytes()
+	baseZulu := uuidv7.MustBytes()
+	rosterID := uuidv7.MustBytes()
+	svc := &hemsDutyRosterServiceMock{
+		listHeadersByRangeFn: func(_ []byte, _, _ time.Time) ([]dutyroster.HeaderView, error) {
+			return []dutyroster.HeaderView{
+				{
+					ID:               rosterID,
+					BaseID:           baseAlpha,
+					BaseName:         "Alpha HEMS Base",
+					BaseAbbreviation: "A1",
+					DutyDate:         time.Date(2026, 3, 20, 0, 0, 0, 0, time.UTC),
+					CreatedAt:        time.Now().UTC(),
+					UpdatedAt:        time.Now().UTC(),
+				},
+			}, nil
+		},
+		listHEMSBasesFn: func(_ []byte) ([]dutyroster.BaseView, error) {
+			return []dutyroster.BaseView{
+				{ID: baseAlpha, BaseName: "Alpha HEMS Base", BaseAbbreviation: "A1"},
+				{ID: baseZulu, BaseName: "Zulu HEMS Base", BaseAbbreviation: "Z1"},
+			}, nil
+		},
+	}
+	h := NewDutyRosterHandler(svc)
+	app := newDutyRosterFullTestApp(h)
+
+	resp, body := doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all?from=2026-03-01&to=2026-03-31&base_name=zulu", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	lower := strings.ToLower(string(body))
+	if !strings.Contains(lower, "zulu hems base") {
+		t.Fatalf("expected zulu base in response, got %s", string(body))
+	}
+	if strings.Contains(lower, "alpha hems base") {
+		t.Fatalf("expected alpha base excluded by filter, got %s", string(body))
+	}
+
+	resp, body = doJSONRequestHemsDutyRoster(t, app, http.MethodGet, "/api/v1/hems-roster/get-all/dt?from=2026-03-01&to=2026-03-31&base_name=zulu&page=1&size=10", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	lower = strings.ToLower(string(body))
+	if !strings.Contains(lower, "zulu hems base") {
+		t.Fatalf("expected zulu base in dt response, got %s", string(body))
+	}
+}
diff --git a/internal/transport/http/handlers/duty_roster_presenter.go b/internal/transport/http/handlers/duty_roster_presenter.go
new file mode 100644
index 0000000..e3a08f4
--- /dev/null
+++ b/internal/transport/http/handlers/duty_roster_presenter.go
@@ -0,0 +1,313 @@
+package handlers
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	dutyroster "wucher/internal/domain/duty_roster"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	responsedto "wucher/internal/transport/http/dto/response"
+)
+
+func loadRosterGroups(ctx context.Context, svc dutyroster.Service, baseID []byte, from, to time.Time, baseName, baseType string) ([]responsedto.DutyRosterBaseGroupResource, error) {
+	bt := normalizeRosterBaseType(baseType)
+	var (
+		headers []dutyroster.HeaderView
+		bases   []dutyroster.BaseView
+		err     error
+	)
+	if bt == "base" {
+		headers, err = svc.ListHeadersByRangeByBaseType(ctx, baseID, from, to, "base")
+		if err != nil {
+			return nil, err
+		}
+		bases, err = svc.ListBasesByType(ctx, baseID, "base")
+	} else {
+		headers, err = svc.ListHeadersByRange(ctx, baseID, from, to)
+		if err != nil {
+			return nil, err
+		}
+		bases, err = svc.ListHEMSBases(ctx, baseID)
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	rosterIDs := make([][]byte, 0, len(headers))
+	for i := range headers {
+		rosterIDs = append(rosterIDs, headers[i].ID)
+	}
+	crews, err := svc.GetCrewsByRosterIDs(ctx, rosterIDs)
+	if err != nil {
+		return nil, err
+	}
+
+	byRoster := make(map[string][]dutyroster.CrewView)
+	for i := range crews {
+		k, _ := uuidv7.BytesToString(crews[i].RosterID)
+		byRoster[k] = append(byRoster[k], crews[i])
+	}
+	out := make([]responsedto.DutyRosterResource, 0, len(headers))
+	for i := range headers {
+		k, _ := uuidv7.BytesToString(headers[i].ID)
+		out = append(out, dutyRosterResource(ctx, headers[i], byRoster[k], bt))
+	}
+	grouped := mergeEmptyRosterGroups(groupRostersByBase(out, bt), bases, bt)
+
+	needle := strings.ToLower(strings.TrimSpace(baseName))
+	if needle == "" {
+		return grouped, nil
+	}
+	filtered := make([]responsedto.DutyRosterBaseGroupResource, 0, len(grouped))
+	for i := range grouped {
+		name := strings.ToLower(strings.TrimSpace(grouped[i].Attributes.Bases.BaseName))
+		if strings.Contains(name, needle) {
+			filtered = append(filtered, grouped[i])
+		}
+	}
+	return filtered, nil
+}
+
+func paginateRosterGroups(groups []responsedto.DutyRosterBaseGroupResource, start, length int) ([]responsedto.DutyRosterBaseGroupResource, int) {
+	total := len(groups)
+	if start > total {
+		start = total
+	}
+	end := start + length
+	if end > total {
+		end = total
+	}
+	return groups[start:end], total
+}
+
+func paginateUnifiedRosterGroups(
+	hems []responsedto.DutyRosterBaseGroupResource,
+	base []responsedto.DutyRosterBaseGroupResource,
+	start, length int,
+) ([]responsedto.DutyRosterBaseGroupResource, []responsedto.DutyRosterBaseGroupResource, int) {
+	total := len(hems) + len(base)
+	if start > total {
+		start = total
+	}
+	end := start + length
+	if end > total {
+		end = total
+	}
+	if start >= end {
+		return []responsedto.DutyRosterBaseGroupResource{}, []responsedto.DutyRosterBaseGroupResource{}, total
+	}
+
+	outHEMS := []responsedto.DutyRosterBaseGroupResource{}
+	outBase := []responsedto.DutyRosterBaseGroupResource{}
+
+	hemsTotal := len(hems)
+	if start < hemsTotal {
+		hemsEnd := end
+		if hemsEnd > hemsTotal {
+			hemsEnd = hemsTotal
+		}
+		outHEMS = hems[start:hemsEnd]
+	}
+
+	baseStart := start - hemsTotal
+	if baseStart < 0 {
+		baseStart = 0
+	}
+	if end > hemsTotal && baseStart < len(base) {
+		baseEnd := end - hemsTotal
+		if baseEnd > len(base) {
+			baseEnd = len(base)
+		}
+		if baseStart < baseEnd {
+			outBase = base[baseStart:baseEnd]
+		}
+	}
+
+	return outHEMS, outBase, total
+}
+
+func dutyRosterResource(ctx context.Context, header dutyroster.HeaderView, crews []dutyroster.CrewView, baseType string) responsedto.DutyRosterResource {
+	bt := normalizeRosterBaseType(baseType)
+	details := responsedto.DutyRosterDetailsResponse{Pilot: []responsedto.DutyRosterPilotCrew{}, Doctor: []responsedto.DutyRosterCrew{}, Rescuer: []responsedto.DutyRosterCrew{}, Helper: []responsedto.DutyRosterCrew{}, OtherPerson: []responsedto.DutyRosterCrew{}}
+	for i := range crews {
+		baseItem := responsedto.DutyRosterCrew{ID: firstNonEmptyString(idString(crews[i].UserID), idString(crews[i].ID)), Name: strings.TrimSpace(crews[i].Name), Role: strings.TrimSpace(crews[i].Role), MobilePhone: strings.TrimSpace(crews[i].MobilePhone), Email: strings.TrimSpace(crews[i].Email)}
+		if roleNeedsShiftDateForDelete(crews[i].RoleCode) {
+			baseItem.ShiftDate = &responsedto.DutyRosterShiftDate{DateStart: dateToString(crews[i].DateStart), DateEnd: dateToString(crews[i].DateEnd)}
+		}
+		effectiveShiftStart := strings.TrimSpace(crews[i].ShiftStart)
+		effectiveShiftEnd := strings.TrimSpace(crews[i].ShiftEnd)
+		if effectiveShiftStart == "" {
+			effectiveShiftStart = strings.TrimSpace(header.ShiftStart)
+		}
+		if effectiveShiftEnd == "" {
+			effectiveShiftEnd = strings.TrimSpace(header.ShiftEnd)
+		}
+		switch strings.ToLower(strings.TrimSpace(crews[i].RoleCode)) {
+		case "pilot":
+			pilotItem := responsedto.DutyRosterPilotCrew{ID: baseItem.ID, Name: baseItem.Name, Role: firstNonEmptyString(baseItem.Role, "pilot"), MobilePhone: baseItem.MobilePhone, Email: baseItem.Email, ShiftDate: baseItem.ShiftDate, CrewType: strings.ToLower(strings.TrimSpace(crews[i].CrewType)), FlightInstructor: boolPtrDR(crews[i].FlightInstructor), LineChecker: boolPtrDR(crews[i].LineChecker), Supervisor: boolPtrDR(crews[i].Supervisor), Examiner: boolPtrDR(crews[i].Examiner), CoPilot: boolPtrDR(crews[i].CoPilot)}
+			details.Pilot = append(details.Pilot, pilotItem)
+		case "doctor":
+			if effectiveShiftStart != "" || effectiveShiftEnd != "" {
+				baseItem.ShiftTime = &responsedto.DutyRosterShiftTime{ShiftStart: effectiveShiftStart, ShiftEnd: effectiveShiftEnd}
+			}
+			baseItem.Role = firstNonEmptyString(baseItem.Role, "doctor")
+			details.Doctor = append(details.Doctor, baseItem)
+		case "rescuer", "air_rescuer":
+			if effectiveShiftStart != "" || effectiveShiftEnd != "" {
+				baseItem.ShiftTime = &responsedto.DutyRosterShiftTime{ShiftStart: effectiveShiftStart, ShiftEnd: effectiveShiftEnd}
+			}
+			baseItem.Role = firstNonEmptyString(baseItem.Role, "rescuer")
+			details.Rescuer = append(details.Rescuer, baseItem)
+		case "helper", "flight_assistant":
+			if effectiveShiftStart != "" || effectiveShiftEnd != "" {
+				baseItem.ShiftTime = &responsedto.DutyRosterShiftTime{ShiftStart: effectiveShiftStart, ShiftEnd: effectiveShiftEnd}
+			}
+			baseItem.Role = firstNonEmptyString(baseItem.Role, "helper")
+			details.Helper = append(details.Helper, baseItem)
+		default:
+			baseItem.Role = firstNonEmptyString(baseItem.Role, "other")
+			details.OtherPerson = append(details.OtherPerson, baseItem)
+		}
+	}
+	return responsedto.DutyRosterResource{Type: rosterResourceTypeFor(bt), ID: idString(header.ID), Attributes: responsedto.DutyRosterAttributes{Bases: responsedto.DutyRosterBaseInfo{ID: idString(header.BaseID), Type: bt, BaseName: strings.TrimSpace(header.BaseName), BaseAbbreviation: strings.TrimSpace(header.BaseAbbreviation)}, Helicopter: buildRosterHelicopterFromHeader(header), DutyDate: header.DutyDate.UTC().Format("2006-01-02"), ShiftTime: responsedto.DutyRosterShiftTime{ShiftStart: header.ShiftStart, ShiftEnd: header.ShiftEnd}, Detail: details, CreatedBy: uuidStringOrEmptyDR(ctx, header.CreatedBy), CreatedAt: header.CreatedAt.UTC().Format(time.RFC3339), UpdatedAt: header.UpdatedAt.UTC().Format(time.RFC3339)}}
+}
+
+func groupRostersByBase(items []responsedto.DutyRosterResource, baseType string) []responsedto.DutyRosterBaseGroupResource {
+	bt := normalizeRosterBaseType(baseType)
+	groupType := rosterGroupTypeFor(bt)
+	out := make([]responsedto.DutyRosterBaseGroupResource, 0)
+	indexByBase := map[string]int{}
+	for i := range items {
+		baseID := strings.TrimSpace(items[i].Attributes.Bases.ID)
+		if baseID == "" {
+			baseID = "unknown"
+		}
+		idx, ok := indexByBase[baseID]
+		if !ok {
+			idx = len(out)
+			indexByBase[baseID] = idx
+			out = append(out, responsedto.DutyRosterBaseGroupResource{Type: groupType, Attributes: responsedto.DutyRosterBaseGroupAttributes{Bases: items[i].Attributes.Bases, Rosters: []responsedto.DutyRosterGroupRoster{}}})
+		}
+		out[idx].Attributes.Rosters = append(out[idx].Attributes.Rosters, responsedto.DutyRosterGroupRoster{ID: items[i].ID, FlightID: items[i].Attributes.FlightID, Helicopter: items[i].Attributes.Helicopter, DutyDate: items[i].Attributes.DutyDate, ShiftTime: items[i].Attributes.ShiftTime, Detail: items[i].Attributes.Detail, CreatedBy: items[i].Attributes.CreatedBy, CreatedAt: items[i].Attributes.CreatedAt, UpdatedAt: items[i].Attributes.UpdatedAt})
+	}
+	return out
+}
+
+func mergeEmptyRosterGroups(groups []responsedto.DutyRosterBaseGroupResource, bases []dutyroster.BaseView, baseType string) []responsedto.DutyRosterBaseGroupResource {
+	bt := normalizeRosterBaseType(baseType)
+	groupType := rosterGroupTypeFor(bt)
+	indexByBase := make(map[string]int, len(groups))
+	for i := range groups {
+		baseID := strings.TrimSpace(groups[i].Attributes.Bases.ID)
+		if baseID == "" || baseID == "unknown" {
+			continue
+		}
+		indexByBase[baseID] = i
+	}
+	for i := range bases {
+		baseID := idString(bases[i].ID)
+		if baseID == "" {
+			continue
+		}
+		if _, exists := indexByBase[baseID]; exists {
+			continue
+		}
+		groups = append(groups, responsedto.DutyRosterBaseGroupResource{Type: groupType, Attributes: responsedto.DutyRosterBaseGroupAttributes{Bases: responsedto.DutyRosterBaseInfo{ID: baseID, Type: bt, BaseName: strings.TrimSpace(bases[i].BaseName), BaseAbbreviation: strings.TrimSpace(bases[i].BaseAbbreviation)}, Rosters: []responsedto.DutyRosterGroupRoster{}}})
+	}
+	return groups
+}
+
+func dutyRosterDeletedCrewItems(rows []dutyroster.DeletedCrewResult) []map[string]any {
+	out := make([]map[string]any, 0, len(rows))
+	for i := range rows {
+		out = append(out, map[string]any{"id": idString(rows[i].ID), "roster_id": idString(rows[i].RosterID), "user_id": idString(rows[i].UserID), "name": strings.TrimSpace(rows[i].Name), "role_code": strings.TrimSpace(rows[i].RoleCode), "crew_type": strings.TrimSpace(rows[i].CrewType), "date_start": dateToString(rows[i].DateStart), "date_end": dateToString(rows[i].DateEnd)})
+	}
+	return out
+}
+
+func dutyRosterCrewAuditMetadata(rosterID []byte, baseType string, crews []dutyroster.DutyRosterCrew) map[string]any {
+	roles := make([]string, 0, len(crews))
+	for i := range crews {
+		roles = append(roles, roleBucket(crews[i].RoleCode))
+	}
+	return map[string]any{"roster_id": idString(rosterID), "base_type": strings.ToLower(strings.TrimSpace(baseType)), "roles": roles, "crew_count": len(crews)}
+}
+
+func buildRosterHelicopterFromHeader(header dutyroster.HeaderView) responsedto.DutyRosterHelicopterSummary {
+	return responsedto.DutyRosterHelicopterSummary{ID: idString(header.HelicopterID), Designation: strings.TrimSpace(header.HelicopterDesignation), Identifier: strings.TrimSpace(header.HelicopterIdentifier), Type: strings.TrimSpace(header.HelicopterType)}
+}
+
+func uuidStringOrEmptyDR(ctx context.Context, id []byte) string {
+	if len(id) == 0 {
+		return ""
+	}
+	if name := getLastNameFromPresenterGetter(ctx, id); name != "" {
+		return name
+	}
+	return idString(id)
+}
+
+func getLastNameFromPresenterGetter(ctx context.Context, id []byte) string {
+	if name := userctx.GetDisplayName(ctx, id); name != "" {
+		return name
+	}
+	return ""
+}
+
+func firstNonEmptyString(a, b string) string {
+	if strings.TrimSpace(a) != "" {
+		return strings.TrimSpace(a)
+	}
+	return strings.TrimSpace(b)
+}
+
+func roleBucket(code string) string {
+	switch strings.ToLower(strings.TrimSpace(code)) {
+	case "pilot":
+		return "pilot"
+	case "doctor":
+		return "doctor"
+	case "rescuer", "air_rescuer":
+		return "rescuer"
+	case "helper", "flight_assistant":
+		return "helper"
+	default:
+		return "other_person"
+	}
+}
+
+func roleNeedsShiftDateForDelete(roleCode string) bool {
+	switch strings.ToLower(strings.TrimSpace(roleCode)) {
+	case "other_person", "other":
+		return false
+	default:
+		return true
+	}
+}
+
+func boolPtrDR(v bool) *bool {
+	return &v
+}
+
+func normalizeRosterBaseType(baseType string) string {
+	if strings.EqualFold(strings.TrimSpace(baseType), "base") {
+		return "base"
+	}
+	return "hems"
+}
+
+func rosterResourceTypeFor(baseType string) string {
+	if normalizeRosterBaseType(baseType) == "base" {
+		return "base_duty_roster"
+	}
+	return "duty_roster"
+}
+
+func rosterGroupTypeFor(baseType string) string {
+	if normalizeRosterBaseType(baseType) == "base" {
+		return "base_roster_group"
+	}
+	return "hems_base_roster_group"
+}
diff --git a/internal/transport/http/handlers/easa_release_handler.go b/internal/transport/http/handlers/easa_release_handler.go
new file mode 100644
index 0000000..5603138
--- /dev/null
+++ b/internal/transport/http/handlers/easa_release_handler.go
@@ -0,0 +1,603 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	actionsignoff "wucher/internal/domain/action_signoff"
+	complaint "wucher/internal/domain/complaint"
+	contact "wucher/internal/domain/contact"
+	easarelease "wucher/internal/domain/easa_release"
+	fleethistory "wucher/internal/domain/fleet_history"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type EASAReleaseHandler struct {
+	svc              easarelease.Service
+	complaintChecker complaintActionChecker
+	signoffChecker   easaSignoffChecker
+	historySvc       fleetHistoryRecorder
+	contactSvc       contactNameResolver
+	aogRecalc        aogRecalculator
+	validate         *validators.Validator
+}
+
+// easaSignoffChecker resolves corrective-action sign-offs so the release can be gated
+// on them: a release requires the open complaint (via complaint_id) to be signed off,
+// or — when there is no open complaint — a standalone (fleet) sign-off.
+type easaSignoffChecker interface {
+	GetByFlight(ctx context.Context, flightID []byte) (*actionsignoff.ActionSignoff, error)
+	GetByComplaintIDs(ctx context.Context, complaintIDs [][]byte) (map[string]*actionsignoff.ActionSignoff, error)
+	// Unsign consumes the flight's standalone sign-off after a release, so the next
+	// complaint-independent release requires a fresh signature (no stale sign-off).
+	Unsign(ctx context.Context, flightID []byte, actor []byte) (*actionsignoff.ActionSignoff, error)
+}
+
+// consumeStandaloneSignoff clears the fleet (complaint-independent) sign-off after a
+// release. No-op when unwired or when there is no standalone sign-off. Complaint-linked
+// sign-offs are not touched — they are spent when the complaint closes/reopens.
+func (h *EASAReleaseHandler) consumeStandaloneSignoff(ctx context.Context, flightID, actor []byte) {
+	if h.signoffChecker == nil || len(flightID) != 16 {
+		return
+	}
+	_, _ = h.signoffChecker.Unsign(ctx, flightID, actor)
+}
+
+// contactNameResolver looks up a contact (the EASA signer) by id to resolve its name.
+type contactNameResolver interface {
+	GetContactByID(ctx context.Context, userID []byte) (*contact.ContactListItem, error)
+}
+
+func (h *EASAReleaseHandler) WithHistoryService(svc fleetHistoryRecorder) *EASAReleaseHandler {
+	h.historySvc = svc
+	return h
+}
+
+func (h *EASAReleaseHandler) WithContactResolver(svc contactNameResolver) *EASAReleaseHandler {
+	h.contactSvc = svc
+	return h
+}
+
+func (h *EASAReleaseHandler) signerNameAndShort(ctx context.Context, signerID *string) (name *string, short *string) {
+	if h.contactSvc == nil || signerID == nil || strings.TrimSpace(*signerID) == "" {
+		return nil, nil
+	}
+	idBytes, err := uuidv7.ParseString(strings.TrimSpace(*signerID))
+	if err != nil {
+		return nil, nil
+	}
+	ct, err := h.contactSvc.GetContactByID(ctx, idBytes)
+	if err != nil || ct == nil {
+		return nil, nil
+	}
+	n := strings.TrimSpace(strings.TrimSpace(ct.FirstName) + " " + strings.TrimSpace(ct.LastName))
+	if n == "" {
+		n = strings.TrimSpace(ct.ShortName)
+	}
+	if n != "" {
+		name = &n
+	}
+	if s := strings.TrimSpace(ct.ShortName); s != "" {
+		short = &s
+	}
+	return name, short
+}
+
+type complaintActionChecker interface {
+	ActiveGroundingByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) ([]complaint.Complaint, error)
+	MarkFixedByHelicopter(ctx context.Context, helicopterID []byte, easaID []byte, actor []byte) error
+	MarkFixedByComplaint(ctx context.Context, complaintID []byte, easaID []byte, actor []byte) error
+	MarkFixedByFlight(ctx context.Context, flightID []byte, easaID []byte, actor []byte) error
+}
+
+// closeComplaintsForRelease closes the defect(s) the signed release resolves, at the
+// scope the release was created with (most specific first):
+//   - complaint_id set → close only that complaint;
+//   - else flight_id set → close every open complaint reported on that flight;
+//   - else (standalone / whole-aircraft) → close all of the helicopter's open complaints.
+//
+// complaint_id and flight_id are mutually exclusive at create time, so at most one of
+// the first two branches applies. Then it recomputes the helicopter's AOG state.
+func (h *EASAReleaseHandler) closeComplaintsForRelease(ctx context.Context, row *easarelease.EASARelease, actor []byte) {
+	if h.complaintChecker == nil || row == nil {
+		return
+	}
+	switch {
+	case len(row.ComplaintID) == 16:
+		_ = h.complaintChecker.MarkFixedByComplaint(ctx, row.ComplaintID, row.ID, actor)
+	case len(row.FlightID) == 16:
+		_ = h.complaintChecker.MarkFixedByFlight(ctx, row.FlightID, row.ID, actor)
+	default:
+		_ = h.complaintChecker.MarkFixedByHelicopter(ctx, row.HelicopterID, row.ID, actor)
+	}
+	if h.aogRecalc != nil {
+		_ = h.aogRecalc.RecalculateAOGByHelicopter(ctx, row.HelicopterID)
+	}
+}
+
+func NewEASAReleaseHandler(svc easarelease.Service) *EASAReleaseHandler {
+	return &EASAReleaseHandler{svc: svc, validate: validators.New()}
+}
+
+func (h *EASAReleaseHandler) WithComplaintActionChecker(checker complaintActionChecker) *EASAReleaseHandler {
+	h.complaintChecker = checker
+	return h
+}
+
+func (h *EASAReleaseHandler) WithActionSignoffChecker(checker easaSignoffChecker) *EASAReleaseHandler {
+	h.signoffChecker = checker
+	return h
+}
+
+// requireActionSignoff gates a release on the corrective-action sign-off: when the
+// helicopter has open (non-NSR) complaints, each must have a signed sign-off (linked by
+// complaint_id); when there are none, a standalone (fleet) sign-off must be signed.
+// Returns nil (gate passes) when the checkers are not wired.
+func (h *EASAReleaseHandler) requireActionSignoff(ctx context.Context, flightID, helicopterID []byte) *apperrorsx.AppError {
+	if h.signoffChecker == nil || h.complaintChecker == nil {
+		return nil
+	}
+	open, err := h.complaintChecker.ActiveGroundingByHelicopterIDs(ctx, [][]byte{helicopterID})
+	if err != nil {
+		return apperrorsx.New(apperrorsx.ErrEASAReleaseCreateFailed).WithCause(err)
+	}
+	if len(open) > 0 {
+		ids := make([][]byte, 0, len(open))
+		for i := range open {
+			ids = append(ids, open[i].ID)
+		}
+		signoffs, serr := h.signoffChecker.GetByComplaintIDs(ctx, ids)
+		if serr != nil {
+			return apperrorsx.New(apperrorsx.ErrEASAReleaseCreateFailed).WithCause(serr)
+		}
+		for i := range open {
+			if so := signoffs[string(open[i].ID)]; so == nil || !so.IsSigned() {
+				return apperrorsx.New(apperrorsx.ErrEASAReleaseSignoffRequired)
+			}
+		}
+		return nil
+	}
+	standalone, serr := h.signoffChecker.GetByFlight(ctx, flightID)
+	if serr != nil {
+		return apperrorsx.New(apperrorsx.ErrEASAReleaseCreateFailed).WithCause(serr)
+	}
+	if standalone == nil || !standalone.IsSigned() {
+		return apperrorsx.New(apperrorsx.ErrEASAReleaseSignoffRequired)
+	}
+	return nil
+}
+
+func (h *EASAReleaseHandler) WithAOGRecalculator(svc aogRecalculator) *EASAReleaseHandler {
+	h.aogRecalc = svc
+	return h
+}
+
+func parseEASADate(s *string) (*time.Time, error) {
+	if s == nil || strings.TrimSpace(*s) == "" {
+		return nil, nil
+	}
+	t, err := time.Parse("2006-01-02", strings.TrimSpace(*s))
+	if err != nil {
+		return nil, err
+	}
+	return &t, nil
+}
+
+func writeEASAReleaseServiceError(c *fiber.Ctx, err error, fallback apperrorsx.Def) error {
+	switch {
+	case errors.Is(err, easarelease.ErrNotFound):
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrEASAReleaseNotFound).WithCause(err))
+	case errors.Is(err, easarelease.ErrAlreadySigned):
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrEASAReleaseAlreadySigned).WithCause(err))
+	case errors.Is(err, easarelease.ErrIncompleteForSign):
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrEASAReleaseIncompleteForSign).WithCause(err))
+	default:
+		return apperrorsx.Write(c, apperrorsx.New(fallback).WithCause(err))
+	}
+}
+
+func (h *EASAReleaseHandler) easaResource(ctx context.Context, row *easarelease.EASARelease) responsedto.EASAReleaseResource {
+	res := easaReleaseResource(row)
+	if row != nil {
+		res.Attributes.EASASignerName, res.Attributes.EASASignerShort = h.signerNameAndShort(ctx, row.EASASignerID)
+	}
+	return res
+}
+
+func easaReleaseResource(row *easarelease.EASARelease) responsedto.EASAReleaseResource {
+	if row == nil {
+		return responsedto.EASAReleaseResource{}
+	}
+	id, _ := uuidv7.BytesToString(row.ID)
+	out := responsedto.EASAReleaseResource{
+		Type: "easa_release",
+		ID:   id,
+		Attributes: responsedto.EASAReleaseAttributes{
+			HelicopterID:               idString(row.HelicopterID),
+			ComplaintID:                idString(row.ComplaintID),
+			FlightID:                   idString(row.FlightID),
+			EASAACHours:                row.EASAACHours,
+			EASALocation:               row.EASALocation,
+			EASAWONo:                   row.EASAWONo,
+			EASAMaintManualRevAirframe: row.EASAMaintManualRevAirframe,
+			EASAMaintManualRevEngine:   row.EASAMaintManualRevEngine,
+			EASASignerID:               row.EASASignerID,
+			EASAPermitNo:               row.EASAPermitNo,
+			IsSigned:                   row.IsSigned(),
+			SignedBy:                   idString(row.SignedBy),
+			MissingSignFields:          row.MissingSignFields(),
+		},
+	}
+	if row.EASADate != nil {
+		v := row.EASADate.UTC().Format("2006-01-02")
+		out.Attributes.EASADate = &v
+	}
+	if row.SignedAt != nil {
+		v := row.SignedAt.UTC().Format(time.RFC3339)
+		out.Attributes.SignedAt = &v
+	}
+	if !row.CreatedAt.IsZero() {
+		out.Attributes.CreatedAt = row.CreatedAt.UTC().Format(time.RFC3339)
+	}
+	if !row.UpdatedAt.IsZero() {
+		out.Attributes.UpdatedAt = row.UpdatedAt.UTC().Format(time.RFC3339)
+	}
+	return out
+}
+
+// Create godoc
+// @Summary Create EASA maintenance release (draft) for a helicopter
+// @Tags EASA Releases
+// @Accept json
+// @Produce json
+// @Param request body requestdto.EASAReleaseCreateRequest true "JSON:API EASA release create request"
+// @Success 201 {object} responsedto.EASAReleaseResponse
+// @Router /api/v1/easa-releases/create [post]
+func (h *EASAReleaseHandler) Create(c *fiber.Ctx) error {
+	var req requestdto.EASAReleaseCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeBodyParseError(c, err, apperrorsx.ErrEASAReleaseInvalidJSON)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return jsonapi.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	helicopterID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.HelicopterID))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/helicopter_id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	var flightID []byte
+	if s := strings.TrimSpace(req.Data.Attributes.FlightID); s != "" {
+		flightID, err = uuidv7.ParseString(s)
+		if err != nil {
+			appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidUUID).WithCause(err)
+			appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_id"}
+			return apperrorsx.Write(c, appErr)
+		}
+	}
+	var complaintID []byte
+	if s := strings.TrimSpace(req.Data.Attributes.ComplaintID); s != "" {
+		complaintID, err = uuidv7.ParseString(s)
+		if err != nil {
+			appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidUUID).WithCause(err)
+			appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/complaint_id"}
+			return apperrorsx.Write(c, appErr)
+		}
+	}
+	// complaint_id and flight_id are mutually exclusive: a release either closes one
+	// specific complaint or all of a flight's complaints, never both.
+	if len(complaintID) == 16 && len(flightID) == 16 {
+		appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidPayload)
+		appErr.Detail = "complaint_id and flight_id are mutually exclusive; provide at most one"
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/complaint_id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	if aerr := h.requireActionSignoff(c.UserContext(), flightID, helicopterID); aerr != nil {
+		return apperrorsx.Write(c, aerr)
+	}
+	easaDate, err := parseEASADate(req.Data.Attributes.EASADate)
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidPayload).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/easa_date"}
+		return apperrorsx.Write(c, appErr)
+	}
+	row := &easarelease.EASARelease{
+		HelicopterID:               helicopterID,
+		ComplaintID:                complaintID,
+		FlightID:                   flightID,
+		EASADate:                   easaDate,
+		EASAACHours:                emptyToNilString(req.Data.Attributes.EASAACHours),
+		EASALocation:               emptyToNilString(req.Data.Attributes.EASALocation),
+		EASAWONo:                   emptyToNilString(req.Data.Attributes.EASAWONo),
+		EASAMaintManualRevAirframe: emptyToNilString(req.Data.Attributes.EASAMaintManualRevAirframe),
+		EASAMaintManualRevEngine:   emptyToNilString(req.Data.Attributes.EASAMaintManualRevEngine),
+		EASASignerID:               emptyToNilString(req.Data.Attributes.EASASignerID),
+		EASAPermitNo:               emptyToNilString(req.Data.Attributes.EASAPermitNo),
+		CreatedBy:                  actorUserID(c),
+		UpdatedBy:                  actorUserID(c),
+	}
+	if req.Data.Attributes.Sign {
+		if len(row.MissingSignFields()) > 0 {
+			appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseIncompleteForSign)
+			appErr.Detail = map[string]any{"missing_sign_fields": row.MissingSignFields()}
+			return apperrorsx.Write(c, appErr)
+		}
+		now := time.Now().UTC()
+		row.SignedAt = &now
+		row.SignedBy = actorUserID(c)
+	}
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeEASAReleaseServiceError(c, err, apperrorsx.ErrEASAReleaseCreateFailed)
+	}
+	created, _ := h.svc.GetByID(c.UserContext(), row.ID)
+	if created == nil {
+		created = row
+	}
+	actor := actorUserID(c)
+	if created.IsSigned() {
+		h.closeComplaintsForRelease(c.UserContext(), created, actor)
+		h.consumeStandaloneSignoff(c.UserContext(), created.FlightID, actor)
+	}
+	if h.historySvc != nil {
+		_ = h.historySvc.Record(c.UserContext(), created.HelicopterID, fleethistory.EntityEASARelease, created.ID, fleethistory.ActionEASACreated, "EASA release created (draft)", actor)
+		if created.IsSigned() {
+			_ = h.historySvc.Record(c.UserContext(), created.HelicopterID, fleethistory.EntityEASARelease, created.ID, fleethistory.ActionEASASigned, "Release to Service (EASA signed)", actor)
+		}
+	}
+	return response.Write(c, fiber.StatusCreated, h.easaResource(c.UserContext(), created))
+}
+
+// GetByID godoc
+// @Summary Get EASA release by ID
+// @Tags EASA Releases
+// @Produce json
+// @Param id path string true "EASA release ID (UUIDv7)"
+// @Success 200 {object} responsedto.EASAReleaseResponse
+// @Router /api/v1/easa-releases/get/{id} [get]
+func (h *EASAReleaseHandler) GetByID(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return writeEASAReleaseServiceError(c, err, apperrorsx.ErrEASAReleaseNotFound)
+	}
+	if row == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrEASAReleaseNotFound))
+	}
+	return response.Write(c, fiber.StatusOK, h.easaResource(c.UserContext(), row))
+}
+
+// GetByFlight godoc
+// @Summary Get the current EASA release for a flight
+// @Tags EASA Releases
+// @Produce json
+// @Param flight_id path string true "Flight ID (UUIDv7)"
+// @Success 200 {object} responsedto.EASAReleaseResponse
+// @Router /api/v1/easa-releases/get-by-flight/{flight_id} [get]
+func (h *EASAReleaseHandler) GetByFlight(c *fiber.Ctx) error {
+	flightID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("flight_id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/flight_id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	row, err := h.svc.GetByFlightID(c.UserContext(), flightID)
+	if err != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrEASAReleaseListFailed).WithCause(err))
+	}
+	if row == nil {
+		// No release for this flight yet — return an empty resource (not 404).
+		return response.Write(c, fiber.StatusOK, responsedto.EASAReleaseResource{})
+	}
+	return response.Write(c, fiber.StatusOK, h.easaResource(c.UserContext(), row))
+}
+
+// GetByComplaint godoc
+// @Summary Get the current EASA release for a complaint
+// @Tags EASA Releases
+// @Produce json
+// @Param complaint_id path string true "Complaint ID (UUIDv7)"
+// @Success 200 {object} responsedto.EASAReleaseResponse
+// @Router /api/v1/easa-releases/get-by-complaint/{complaint_id} [get]
+func (h *EASAReleaseHandler) GetByComplaint(c *fiber.Ctx) error {
+	complaintID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("complaint_id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/complaint_id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	row, err := h.svc.GetByComplaintID(c.UserContext(), complaintID)
+	if err != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrEASAReleaseListFailed).WithCause(err))
+	}
+	if row == nil {
+		// No release for this complaint yet — return an empty resource (not 404).
+		return response.Write(c, fiber.StatusOK, responsedto.EASAReleaseResource{})
+	}
+	return response.Write(c, fiber.StatusOK, h.easaResource(c.UserContext(), row))
+}
+
+// ListByHelicopter godoc
+// @Summary List EASA releases for a helicopter
+// @Tags EASA Releases
+// @Produce json
+// @Param helicopter_id path string true "Helicopter ID (UUIDv7)"
+// @Success 200 {object} responsedto.EASAReleaseListResponse
+// @Router /api/v1/easa-releases/get-by-helicopter/{helicopter_id} [get]
+func (h *EASAReleaseHandler) ListByHelicopter(c *fiber.Ctx) error {
+	helicopterID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("helicopter_id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/helicopter_id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	rows, err := h.svc.ListByHelicopter(c.UserContext(), helicopterID)
+	if err != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrEASAReleaseListFailed).WithCause(err))
+	}
+	data := make([]responsedto.EASAReleaseResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, h.easaResource(c.UserContext(), &rows[i]))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{
+		"total": int64(len(data)),
+	})
+}
+
+// Update godoc
+// @Summary Update EASA release (draft fields)
+// @Tags EASA Releases
+// @Accept json
+// @Produce json
+// @Param id path string true "EASA release ID (UUIDv7)"
+// @Param request body requestdto.EASAReleaseUpdateRequest true "JSON:API EASA release update request"
+// @Success 200 {object} responsedto.EASAReleaseResponse
+// @Router /api/v1/easa-releases/update/{id} [patch]
+func (h *EASAReleaseHandler) Update(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	var req requestdto.EASAReleaseUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeBodyParseError(c, err, apperrorsx.ErrEASAReleaseInvalidJSON)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return jsonapi.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if strings.TrimSpace(req.Data.ID) != "" && strings.TrimSpace(req.Data.ID) != strings.TrimSpace(c.Params("id")) {
+		appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidPayload)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return writeEASAReleaseServiceError(c, err, apperrorsx.ErrEASAReleaseNotFound)
+	}
+	if row == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrEASAReleaseNotFound))
+	}
+	a := req.Data.Attributes
+	if a.EASADate != nil {
+		d, perr := parseEASADate(a.EASADate)
+		if perr != nil {
+			appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidPayload).WithCause(perr)
+			appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/easa_date"}
+			return apperrorsx.Write(c, appErr)
+		}
+		row.EASADate = d
+	}
+	if a.EASAACHours != nil {
+		row.EASAACHours = emptyToNilString(a.EASAACHours)
+	}
+	if a.EASALocation != nil {
+		row.EASALocation = emptyToNilString(a.EASALocation)
+	}
+	if a.EASAWONo != nil {
+		row.EASAWONo = emptyToNilString(a.EASAWONo)
+	}
+	if a.EASAMaintManualRevAirframe != nil {
+		row.EASAMaintManualRevAirframe = emptyToNilString(a.EASAMaintManualRevAirframe)
+	}
+	if a.EASAMaintManualRevEngine != nil {
+		row.EASAMaintManualRevEngine = emptyToNilString(a.EASAMaintManualRevEngine)
+	}
+	if a.EASASignerID != nil {
+		row.EASASignerID = emptyToNilString(a.EASASignerID)
+	}
+	if a.EASAPermitNo != nil {
+		row.EASAPermitNo = emptyToNilString(a.EASAPermitNo)
+	}
+	row.UpdatedBy = actorUserID(c)
+	if err := h.svc.Update(c.UserContext(), row); err != nil {
+		return writeEASAReleaseServiceError(c, err, apperrorsx.ErrEASAReleaseUpdateFailed)
+	}
+	updated, _ := h.svc.GetByID(c.UserContext(), id)
+	if updated == nil {
+		updated = row
+	}
+	return response.Write(c, fiber.StatusOK, h.easaResource(c.UserContext(), updated))
+}
+
+// Sign godoc
+// @Summary Sign the EASA maintenance release (closes the helicopter's open complaints)
+// @Description Signs the release and closes the helicopter's open complaints. The corrective-action sign-off is re-checked at sign time: if the sign-off was invalidated since the draft was created (e.g. its complaint was reopened) it returns 422 `EASA_RELEASE_SIGNOFF_REQUIRED` and does not sign.
+// @Tags EASA Releases
+// @Produce json
+// @Param id path string true "EASA release ID (UUIDv7)"
+// @Success 200 {object} responsedto.EASAReleaseResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/easa-releases/sign/{id} [post]
+func (h *EASAReleaseHandler) Sign(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	// Re-check the sign-off gate at sign time: a draft created earlier may have had its
+	// corrective-action sign-off invalidated since (e.g. its complaint was reopened), so
+	// signing must not bypass the requirement.
+	existing, gerr := h.svc.GetByID(c.UserContext(), id)
+	if gerr != nil {
+		return writeEASAReleaseServiceError(c, gerr, apperrorsx.ErrEASAReleaseSignFailed)
+	}
+	if existing == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrEASAReleaseNotFound))
+	}
+	if aerr := h.requireActionSignoff(c.UserContext(), existing.FlightID, existing.HelicopterID); aerr != nil {
+		return apperrorsx.Write(c, aerr)
+	}
+	if err := h.svc.Sign(c.UserContext(), id, actorUserID(c)); err != nil {
+		return writeEASAReleaseServiceError(c, err, apperrorsx.ErrEASAReleaseSignFailed)
+	}
+	row, _ := h.svc.GetByID(c.UserContext(), id)
+	if row == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrEASAReleaseNotFound))
+	}
+	actor := actorUserID(c)
+	h.closeComplaintsForRelease(c.UserContext(), row, actor)
+	h.consumeStandaloneSignoff(c.UserContext(), row.FlightID, actor)
+	if h.historySvc != nil {
+		_ = h.historySvc.Record(c.UserContext(), row.HelicopterID, fleethistory.EntityEASARelease, row.ID, fleethistory.ActionEASASigned, "Release to Service (EASA signed)", actor)
+	}
+	return response.Write(c, fiber.StatusOK, h.easaResource(c.UserContext(), row))
+}
+
+// Delete godoc
+// @Summary Delete (void) an EASA release
+// @Tags EASA Releases
+// @Produce json
+// @Param id path string true "EASA release ID (UUIDv7)"
+// @Success 200 {object} responsedto.EASAReleaseDeleteResponse
+// @Router /api/v1/easa-releases/delete/{id} [delete]
+func (h *EASAReleaseHandler) Delete(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrEASAReleaseInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		return writeEASAReleaseServiceError(c, err, apperrorsx.ErrEASAReleaseDeleteFailed)
+	}
+	return response.Write(c, fiber.StatusOK, map[string]any{"data": map[string]any{"type": "easa_release_delete", "attributes": map[string]bool{"deleted": true}}})
+}
diff --git a/internal/transport/http/handlers/easa_release_handler_test.go b/internal/transport/http/handlers/easa_release_handler_test.go
new file mode 100644
index 0000000..c0a8c1d
--- /dev/null
+++ b/internal/transport/http/handlers/easa_release_handler_test.go
@@ -0,0 +1,307 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	actionsignoff "wucher/internal/domain/action_signoff"
+	complaint "wucher/internal/domain/complaint"
+	easarelease "wucher/internal/domain/easa_release"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type easaComplaintCheckerMock struct {
+	activeGroundingFn func(context.Context, [][]byte) ([]complaint.Complaint, error)
+}
+
+func (m *easaComplaintCheckerMock) HelicopterHasUnactionedComplaint(context.Context, []byte) (bool, error) {
+	return false, nil
+}
+func (m *easaComplaintCheckerMock) ActiveGroundingByHelicopterIDs(ctx context.Context, ids [][]byte) ([]complaint.Complaint, error) {
+	if m.activeGroundingFn != nil {
+		return m.activeGroundingFn(ctx, ids)
+	}
+	return nil, nil
+}
+func (m *easaComplaintCheckerMock) MarkFixedByHelicopter(context.Context, []byte, []byte, []byte) error {
+	return nil
+}
+func (m *easaComplaintCheckerMock) MarkFixedByComplaint(context.Context, []byte, []byte, []byte) error {
+	return nil
+}
+func (m *easaComplaintCheckerMock) MarkFixedByFlight(context.Context, []byte, []byte, []byte) error {
+	return nil
+}
+
+type easaSignoffCheckerMock struct {
+	getByHelicopterFn   func(context.Context, []byte) (*actionsignoff.ActionSignoff, error)
+	getByComplaintIDsFn func(context.Context, [][]byte) (map[string]*actionsignoff.ActionSignoff, error)
+	unsignFn            func(context.Context, []byte, []byte) (*actionsignoff.ActionSignoff, error)
+}
+
+func (m *easaSignoffCheckerMock) GetByFlight(ctx context.Context, id []byte) (*actionsignoff.ActionSignoff, error) {
+	if m.getByHelicopterFn != nil {
+		return m.getByHelicopterFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *easaSignoffCheckerMock) GetByComplaintIDs(ctx context.Context, ids [][]byte) (map[string]*actionsignoff.ActionSignoff, error) {
+	if m.getByComplaintIDsFn != nil {
+		return m.getByComplaintIDsFn(ctx, ids)
+	}
+	return map[string]*actionsignoff.ActionSignoff{}, nil
+}
+
+func (m *easaSignoffCheckerMock) Unsign(ctx context.Context, helicopterID []byte, actor []byte) (*actionsignoff.ActionSignoff, error) {
+	if m.unsignFn != nil {
+		return m.unsignFn(ctx, helicopterID, actor)
+	}
+	return nil, nil
+}
+
+type easaServiceMock struct {
+	getByIDFn func(context.Context, []byte) (*easarelease.EASARelease, error)
+	signFn    func(context.Context, []byte, []byte) error
+}
+
+func (m *easaServiceMock) Create(context.Context, *easarelease.EASARelease) error { return nil }
+func (m *easaServiceMock) Update(context.Context, *easarelease.EASARelease) error { return nil }
+func (m *easaServiceMock) Delete(context.Context, []byte, []byte) error           { return nil }
+func (m *easaServiceMock) GetByID(ctx context.Context, id []byte) (*easarelease.EASARelease, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *easaServiceMock) GetByFlightID(_ context.Context, _ []byte) (*easarelease.EASARelease, error) {
+	return nil, nil
+}
+func (m *easaServiceMock) GetByComplaintID(_ context.Context, _ []byte) (*easarelease.EASARelease, error) {
+	return nil, nil
+}
+func (m *easaServiceMock) ListByHelicopter(context.Context, []byte) ([]easarelease.EASARelease, error) {
+	return nil, nil
+}
+func (m *easaServiceMock) GetActiveByHelicopter(context.Context, []byte) (*easarelease.EASARelease, error) {
+	return nil, nil
+}
+func (m *easaServiceMock) Sign(ctx context.Context, id []byte, actor []byte) error {
+	if m.signFn != nil {
+		return m.signFn(ctx, id, actor)
+	}
+	return nil
+}
+func (m *easaServiceMock) Amend(context.Context, []byte, string, []byte) ([]byte, error) {
+	return nil, nil
+}
+
+// Single-resource responses must be a single `data` envelope carrying the
+// resource (with its id). A double `data.data` wrap makes the frontend parse the
+// id off the wrong level and send POST /easa-releases/sign/ with an empty id →
+// 404. This guards the Create/GetByID/Update/Sign shape.
+func TestEASAReleaseSingleResponseIsSingleDataEnvelopeWithID(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+
+	svc := &easaServiceMock{
+		getByIDFn: func(_ context.Context, _ []byte) (*easarelease.EASARelease, error) {
+			return &easarelease.EASARelease{ID: id, HelicopterID: uuidv7.MustBytes()}, nil
+		},
+	}
+	app := fiber.New()
+	app.Get("/api/v1/easa-releases/get/:id", NewEASAReleaseHandler(svc).GetByID)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/easa-releases/get/"+idStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(body))
+	}
+
+	var body map[string]any
+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+		t.Fatal(err)
+	}
+	data, ok := body["data"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected object at data, got %#v", body["data"])
+	}
+	if _, nested := data["data"]; nested {
+		t.Fatalf("response is double-wrapped (data.data present): %#v", data)
+	}
+	if gotID, _ := data["id"].(string); gotID != idStr {
+		t.Fatalf("expected data.id=%q, got %#v", idStr, data["id"])
+	}
+}
+
+// The release is gated on the corrective-action sign-off: an open complaint must be
+// signed off (via complaint_id); with no open complaint a standalone sign-off must exist.
+func TestEASAReleaseRequireActionSignoff(t *testing.T) {
+	helicopterID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	complaintID := uuidv7.MustBytes()
+	signedAt := time.Now().UTC()
+
+	newHandler := func(complaintMock *easaComplaintCheckerMock, signoffMock *easaSignoffCheckerMock) *EASAReleaseHandler {
+		return NewEASAReleaseHandler(&easaServiceMock{}).
+			WithComplaintActionChecker(complaintMock).
+			WithActionSignoffChecker(signoffMock)
+	}
+
+	t.Run("open complaint without sign-off is blocked", func(t *testing.T) {
+		h := newHandler(
+			&easaComplaintCheckerMock{activeGroundingFn: func(context.Context, [][]byte) ([]complaint.Complaint, error) {
+				return []complaint.Complaint{{ID: complaintID, HelicopterID: helicopterID}}, nil
+			}},
+			&easaSignoffCheckerMock{}, // no sign-off for the complaint
+		)
+		aerr := h.requireActionSignoff(context.Background(), flightID, helicopterID)
+		if aerr == nil || aerr.Code != apperrorsx.CodeEASAReleaseSignoffRequired {
+			t.Fatalf("expected SIGNOFF_REQUIRED, got %#v", aerr)
+		}
+	})
+
+	t.Run("open complaint with signed sign-off passes", func(t *testing.T) {
+		h := newHandler(
+			&easaComplaintCheckerMock{activeGroundingFn: func(context.Context, [][]byte) ([]complaint.Complaint, error) {
+				return []complaint.Complaint{{ID: complaintID, HelicopterID: helicopterID}}, nil
+			}},
+			&easaSignoffCheckerMock{getByComplaintIDsFn: func(context.Context, [][]byte) (map[string]*actionsignoff.ActionSignoff, error) {
+				return map[string]*actionsignoff.ActionSignoff{
+					string(complaintID): {ComplaintID: complaintID, HelicopterID: helicopterID, SignedAt: &signedAt},
+				}, nil
+			}},
+		)
+		if aerr := h.requireActionSignoff(context.Background(), flightID, helicopterID); aerr != nil {
+			t.Fatalf("expected pass, got %#v", aerr)
+		}
+	})
+
+	t.Run("no complaint without standalone sign-off is blocked", func(t *testing.T) {
+		h := newHandler(&easaComplaintCheckerMock{}, &easaSignoffCheckerMock{})
+		aerr := h.requireActionSignoff(context.Background(), flightID, helicopterID)
+		if aerr == nil || aerr.Code != apperrorsx.CodeEASAReleaseSignoffRequired {
+			t.Fatalf("expected SIGNOFF_REQUIRED, got %#v", aerr)
+		}
+	})
+
+	t.Run("no complaint with standalone signed sign-off passes", func(t *testing.T) {
+		h := newHandler(&easaComplaintCheckerMock{}, &easaSignoffCheckerMock{
+			getByHelicopterFn: func(context.Context, []byte) (*actionsignoff.ActionSignoff, error) {
+				return &actionsignoff.ActionSignoff{HelicopterID: helicopterID, SignedAt: &signedAt}, nil
+			},
+		})
+		if aerr := h.requireActionSignoff(context.Background(), flightID, helicopterID); aerr != nil {
+			t.Fatalf("expected pass, got %#v", aerr)
+		}
+	})
+
+	t.Run("gate is skipped when checkers are not wired", func(t *testing.T) {
+		h := NewEASAReleaseHandler(&easaServiceMock{})
+		if aerr := h.requireActionSignoff(context.Background(), flightID, helicopterID); aerr != nil {
+			t.Fatalf("expected nil when unwired, got %#v", aerr)
+		}
+	})
+}
+
+// The gate is re-checked at sign time too: a draft whose sign-off was invalidated (e.g.
+// its complaint was reopened) cannot be signed without a fresh sign-off.
+func TestEASAReleaseSign_ReChecksSignoffGate(t *testing.T) {
+	releaseID := uuidv7.MustBytes()
+	releaseIDStr, _ := uuidv7.BytesToString(releaseID)
+	helicopterID := uuidv7.MustBytes()
+	complaintID := uuidv7.MustBytes()
+
+	var signCalled bool
+	svc := &easaServiceMock{
+		getByIDFn: func(_ context.Context, _ []byte) (*easarelease.EASARelease, error) {
+			return &easarelease.EASARelease{ID: releaseID, HelicopterID: helicopterID}, nil
+		},
+		signFn: func(context.Context, []byte, []byte) error { signCalled = true; return nil },
+	}
+	// Open complaint whose sign-off is NOT signed → gate must block.
+	complaintMock := &easaComplaintCheckerMock{activeGroundingFn: func(context.Context, [][]byte) ([]complaint.Complaint, error) {
+		return []complaint.Complaint{{ID: complaintID, HelicopterID: helicopterID}}, nil
+	}}
+	signoffMock := &easaSignoffCheckerMock{} // GetByComplaintIDs → empty → unsigned
+
+	h := NewEASAReleaseHandler(svc).
+		WithComplaintActionChecker(complaintMock).
+		WithActionSignoffChecker(signoffMock)
+	app := fiber.New()
+	app.Post("/api/v1/easa-releases/sign/:id", h.Sign)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/easa-releases/sign/"+releaseIDStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bodyBytes, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	if signCalled {
+		t.Fatal("svc.Sign must not be called when the sign-off gate blocks")
+	}
+	if !strings.Contains(string(bodyBytes), apperrorsx.CodeEASAReleaseSignoffRequired) {
+		t.Fatalf("expected SIGNOFF_REQUIRED, got %s", string(bodyBytes))
+	}
+}
+
+// Signing a release consumes the fleet (standalone) sign-off so the next
+// complaint-independent release requires a fresh signature (fixes staleness).
+func TestEASAReleaseSign_ConsumesStandaloneSignoff(t *testing.T) {
+	releaseID := uuidv7.MustBytes()
+	releaseIDStr, _ := uuidv7.BytesToString(releaseID)
+	helicopterID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	signedAt := time.Now().UTC()
+
+	svc := &easaServiceMock{
+		getByIDFn: func(_ context.Context, _ []byte) (*easarelease.EASARelease, error) {
+			return &easarelease.EASARelease{ID: releaseID, HelicopterID: helicopterID, FlightID: flightID}, nil
+		},
+	}
+	// No open complaint → gate uses the standalone sign-off, which is signed → passes.
+	complaintMock := &easaComplaintCheckerMock{}
+	var consumed []byte
+	signoffMock := &easaSignoffCheckerMock{
+		getByHelicopterFn: func(context.Context, []byte) (*actionsignoff.ActionSignoff, error) {
+			return &actionsignoff.ActionSignoff{HelicopterID: helicopterID, SignedAt: &signedAt}, nil
+		},
+		unsignFn: func(_ context.Context, hid []byte, _ []byte) (*actionsignoff.ActionSignoff, error) {
+			consumed = hid
+			return &actionsignoff.ActionSignoff{HelicopterID: hid}, nil
+		},
+	}
+
+	h := NewEASAReleaseHandler(svc).
+		WithComplaintActionChecker(complaintMock).
+		WithActionSignoffChecker(signoffMock)
+	app := fiber.New()
+	app.Post("/api/v1/easa-releases/sign/:id", h.Sign)
+
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/easa-releases/sign/"+releaseIDStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		bodyBytes, _ := io.ReadAll(resp.Body)
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	if string(consumed) != string(flightID) {
+		t.Fatalf("expected standalone sign-off consumed for flight, got %x", consumed)
+	}
+}
diff --git a/internal/transport/http/handlers/error_helpers.go b/internal/transport/http/handlers/error_helpers.go
new file mode 100644
index 0000000..fe43a13
--- /dev/null
+++ b/internal/transport/http/handlers/error_helpers.go
@@ -0,0 +1,93 @@
+package handlers
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/transport/http/jsonapi"
+)
+
+// bodyParseError maps a request-body JSON parse error to a precise app error. It returns
+// a non-nil *AppError only for a data-type mismatch (INVALID_DATA_TYPE, pointing at the
+// offending field); for any other parse error it returns nil so the caller can fall back
+// to its module-specific invalid-json error.
+func bodyParseError(err error) *apperrorsx.AppError {
+	var typeErr *json.UnmarshalTypeError
+	if !errors.As(err, &typeErr) {
+		return nil
+	}
+	appErr := apperrorsx.New(apperrorsx.ErrInvalidDataType).WithCause(err)
+	if typeErr.Field != "" {
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/" + strings.ReplaceAll(typeErr.Field, ".", "/")}
+		appErr.Message = fmt.Sprintf("field %q expects type %s", typeErr.Field, typeErr.Type.String())
+	} else {
+		appErr.Message = fmt.Sprintf("expected type %s", typeErr.Type.String())
+	}
+	return appErr
+}
+
+// writeBodyParseError writes a precise INVALID_DATA_TYPE error for a data-type mismatch,
+// or falls back to the given module invalid-json def for any other parse error.
+func writeBodyParseError(c *fiber.Ctx, err error, fallback apperrorsx.Def) error {
+	if appErr := bodyParseError(err); appErr != nil {
+		return apperrorsx.Write(c, appErr)
+	}
+	return apperrorsx.Write(c, apperrorsx.New(fallback).WithCause(err))
+}
+
+func writeInternalHandlerError(c *fiber.Ctx, operation string, err error) error {
+	return writeInternalHandlerErrorWithStatus(c, fiber.StatusInternalServerError, operation, err)
+}
+
+func writeHandlerErrorDef(c *fiber.Ctx, operation string, def apperrorsx.Def, err error) error {
+	logHandlerError(c, operation, def.Status, def.Code, def.ErrorCode, err)
+	appErr := apperrorsx.New(def)
+	if err != nil {
+		appErr.Cause = err
+	}
+	return apperrorsx.Write(c, appErr)
+}
+
+func writeHandlerErrorDefWithStatus(c *fiber.Ctx, operation string, status int, def apperrorsx.Def, err error) error {
+	logHandlerError(c, operation, status, def.Code, def.ErrorCode, err)
+	appErr := apperrorsx.New(def)
+	appErr.Status = status
+	if err != nil {
+		appErr.Cause = err
+	}
+	return apperrorsx.Write(c, appErr)
+}
+
+func writeInternalHandlerErrorWithStatus(c *fiber.Ctx, status int, operation string, err error) error {
+	logHandlerError(c, operation, status, apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode, err)
+	appErr := apperrorsx.New(apperrorsx.ErrInternal)
+	appErr.Status = status
+	return apperrorsx.Write(c, appErr)
+}
+
+func safeInternalDetail() string {
+	return apperrorsx.ErrInternal.Message
+}
+
+func logHandlerError(c *fiber.Ctx, operation string, status int, code, errorCode string, err error) {
+	args := []any{
+		slog.String("request_id", requestIDFromCtx(c)),
+		slog.String("operation", strings.TrimSpace(operation)),
+		slog.Int("status", status),
+		slog.String("code", strings.TrimSpace(code)),
+		slog.String("error_code", strings.TrimSpace(errorCode)),
+		slog.String("path", c.Path()),
+		slog.Any("cause", err),
+	}
+	if status >= fiber.StatusInternalServerError {
+		slog.ErrorContext(c.UserContext(), "handler error", args...)
+		return
+	}
+	slog.WarnContext(c.UserContext(), "handler error", args...)
+}
diff --git a/internal/transport/http/handlers/facility_handler.go b/internal/transport/http/handlers/facility_handler.go
new file mode 100644
index 0000000..a601f7d
--- /dev/null
+++ b/internal/transport/http/handlers/facility_handler.go
@@ -0,0 +1,532 @@
+package handlers
+
+import (
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/facility"
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type FacilityHandler struct {
+	svc      facility.Service
+	validate *validators.Validator
+}
+
+func NewFacilityHandler(svc facility.Service) *FacilityHandler {
+	return &FacilityHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateFacility godoc
+// @Summary Create facility
+// @Description Create a facility row using one shared table. Flight-data SPO references now expect categories like `heslo-rope-label`, `heslo-rope-length`, `heslo-hook`, `hec-rope-label`, and `hec-rope-length`.
+// @Tags Facility - Facilities
+// @Accept json
+// @Produce json
+// @Param request body dto.FacilityCreateRequest true "JSON:API Facility create request"
+// @Success 201 {object} dto.FacilityResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/facilities/create [post]
+func (h *FacilityHandler) Create(c *fiber.Ctx) error {
+	var req dto.FacilityCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFacilityErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeFacilityErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	category := strings.TrimSpace(req.Data.Attributes.Category)
+	name := strings.TrimSpace(req.Data.Attributes.Name)
+	facilityType := strings.TrimSpace(req.Data.Attributes.Type)
+	if category == "" || name == "" {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "category and name are required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	row := &facility.Facility{
+		Category:  category,
+		Name:      name,
+		Type:      facilityType,
+		SortKey:   cloneIntPointerFacility(req.Data.Attributes.SortKey),
+		Length:    strings.TrimSpace(stringOrDefault(req.Data.Attributes.Length, "")),
+		Weight:    strings.TrimSpace(stringOrDefault(req.Data.Attributes.Weight, "")),
+		Electric:  strings.TrimSpace(stringOrDefault(req.Data.Attributes.Electric, "")),
+		Note:      strings.TrimSpace(stringOrDefault(req.Data.Attributes.Note, "")),
+		IsActive:  boolOrDefault(req.Data.Attributes.IsActive, true),
+		CreatedBy: actorUserID(c),
+		UpdatedBy: actorUserID(c),
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeFacilityErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, facilityResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, facilityResource(row))
+}
+
+// UpdateFacility godoc
+// @Summary Update facility (partial)
+// @Description Patch facility by ID.
+// @Tags Facility - Facilities
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Facility UUID (UUIDv7)"
+// @Param request body dto.FacilityUpdateRequest true "JSON:API Facility update request"
+// @Success 200 {object} dto.FacilityResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/facilities/update/{uuid} [patch]
+func (h *FacilityHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeFacilityErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.FacilityUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFacilityErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeFacilityErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeFacilityErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeFacilityErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Category == nil && attrs.Name == nil && attrs.Type == nil && !attrs.SortKey.Set && attrs.Length == nil && attrs.Weight == nil &&
+		attrs.Electric == nil && attrs.Note == nil && attrs.IsActive == nil {
+		return writeFacilityErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeFacilityErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "facility not found",
+		}})
+	}
+
+	if attrs.Category != nil {
+		v := strings.TrimSpace(*attrs.Category)
+		if v == "" {
+			return writeFacilityErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "category cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/category"},
+			}})
+		}
+		existing.Category = v
+	}
+	if attrs.Name != nil {
+		v := strings.TrimSpace(*attrs.Name)
+		if v == "" {
+			return writeFacilityErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+			}})
+		}
+		existing.Name = v
+	}
+	if attrs.Type != nil {
+		existing.Type = strings.TrimSpace(*attrs.Type)
+	}
+	if attrs.SortKey.Set {
+		if attrs.SortKey.Valid {
+			sortKey := attrs.SortKey.Value
+			existing.SortKey = &sortKey
+		} else {
+			existing.SortKey = nil
+		}
+	}
+	if attrs.Length != nil {
+		existing.Length = strings.TrimSpace(*attrs.Length)
+	}
+	if attrs.Weight != nil {
+		existing.Weight = strings.TrimSpace(*attrs.Weight)
+	}
+	if attrs.Electric != nil {
+		existing.Electric = strings.TrimSpace(*attrs.Electric)
+	}
+	if attrs.Note != nil {
+		existing.Note = strings.TrimSpace(*attrs.Note)
+	}
+	if attrs.IsActive != nil {
+		existing.IsActive = *attrs.IsActive
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeFacilityErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, facilityResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, facilityResource(existing))
+}
+
+// DeleteFacility godoc
+// @Summary Delete facility
+// @Tags Facility - Facilities
+// @Produce json
+// @Param uuid path string true "Facility UUID (UUIDv7)"
+// @Success 200 {object} dto.FacilityDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/facilities/delete/{uuid} [delete]
+func (h *FacilityHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeFacilityErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeFacilityErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "facility not found",
+			}})
+		}
+		if conflict, ok := apperrors.AsDeleteConflict(err); ok {
+			return writeFacilityErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "Conflict",
+				Detail: conflict.Error(),
+			}})
+		}
+		return writeFacilityErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "facility_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// GetFacilityByID godoc
+// @Summary Get facility by ID
+// @Tags Facility - Facilities
+// @Produce json
+// @Param uuid path string true "Facility UUID (UUIDv7)"
+// @Success 200 {object} dto.FacilityResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/facilities/get/{uuid} [get]
+func (h *FacilityHandler) Get(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeFacilityErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || row == nil {
+		return writeFacilityErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "facility not found",
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, facilityResource(row))
+}
+
+// ListFacilities godoc
+// @Summary List facilities
+// @Description JSON:API list with pagination, filtering and sorting. Supports one shared table with category discriminator (e.g. `heslo-rope-label`, `heslo-hook`, `hec-rope-label`).
+// @Tags Facility - Facilities
+// @Produce json
+// @Param search query string false "Search by name/type/length/weight"
+// @Param category query string false "Filter by category (e.g. heslo-rope-label, heslo-hook, hec-rope-label)"
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.FacilityListResponse
+// @Router /api/v1/facilities/get-all [get]
+func (h *FacilityHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("search")
+	category := strings.TrimSpace(c.Query("category"))
+
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	pageSize := parseIntDefault(c.Query("limit"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, category, sort, 0, 0)
+	if err != nil {
+		return writeFacilityErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.FacilityResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, facilityResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListFacilitiesDatatable godoc
+// @Summary List facilities (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags Facility - Facilities
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Param category query string false "Facility category"
+// @Success 200 {object} dto.FacilityDataTableResponse
+// @Router /api/v1/facilities/get-all/dt [get]
+func (h *FacilityHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+	category := strings.TrimSpace(c.Query("category"))
+
+	rows, total, err := h.svc.List(c.UserContext(), search, category, "", length, start)
+	if err != nil {
+		return writeFacilityErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.FacilityResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, facilityResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func facilityResource(f *facility.Facility) dto.FacilityResource {
+	id, _ := uuidv7.BytesToString(f.ID)
+	return dto.FacilityResource{
+		Type: "facility",
+		ID:   id,
+		Attributes: dto.FacilityAttributes{
+			Category:  f.Category,
+			Name:      f.Name,
+			Type:      f.Type,
+			SortKey:   cloneIntPointerFacility(f.SortKey),
+			Length:    f.Length,
+			Weight:    f.Weight,
+			Electric:  f.Electric,
+			Note:      f.Note,
+			IsActive:  f.IsActive,
+			CreatedBy: uuidStringOrEmpty(f.CreatedBy),
+			UpdatedBy: uuidStringOrEmpty(f.UpdatedBy),
+			CreatedAt: f.CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedAt: f.UpdatedAt.UTC().Format(time.RFC3339),
+		},
+	}
+}
+
+func cloneIntPointerFacility(v *int) *int {
+	if v == nil {
+		return nil
+	}
+	copied := *v
+	return &copied
+}
+
+func writeFacilityErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	statusStr := strconv.Itoa(status)
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferFacilityDef(status, e.Title, e.Detail)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		e.Detail = def.Message
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferFacilityErrorCode(status int, title, detail string) (string, string) {
+	def := inferFacilityDef(status, title, detail)
+	return def.Code, def.ErrorCode
+}
+
+func inferFacilityDef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.ErrFacilityNotFound
+	case fiber.StatusConflict:
+		return apperrorsx.ErrFacilityRelationDelete
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid uuid"), strings.Contains(lowerDetail, "invalid uuid"):
+			return apperrorsx.ErrFacilityInvalidUUID
+		case strings.Contains(lowerDetail, "at least one attribute must be provided"):
+			return apperrorsx.ErrFacilityAttributesRequired
+		case strings.Contains(lowerDetail, "category"):
+			return apperrorsx.ErrFacilityCategoryRequired
+		case strings.Contains(lowerDetail, "name"):
+			return apperrorsx.ErrFacilityNameRequired
+		case strings.Contains(lowerDetail, "type"):
+			return apperrorsx.ErrFacilityTypeRequired
+		default:
+			return apperrorsx.ErrFacilityInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrFacilityInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.ErrFacilityCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrFacilityUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrFacilityDeleteFailed
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.ErrFacilityListFailed
+		default:
+			return apperrorsx.ErrFacilityInvalidPayload
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
diff --git a/internal/transport/http/handlers/facility_handler_test.go b/internal/transport/http/handlers/facility_handler_test.go
new file mode 100644
index 0000000..57287f1
--- /dev/null
+++ b/internal/transport/http/handlers/facility_handler_test.go
@@ -0,0 +1,676 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/facility"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type memFacilityRepo struct {
+	rows map[string]*facility.Facility
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+
+	listRows  []facility.Facility
+	listTotal int64
+
+	getByIDFn func(id []byte, call int) (*facility.Facility, error)
+	getCalls  int
+
+	lastCreate       *facility.Facility
+	lastUpdate       *facility.Facility
+	lastDeleteID     []byte
+	lastListFilter   string
+	lastListCategory string
+	lastListSort     string
+	lastListLimit    int
+	lastListOffset   int
+}
+
+func newMemFacilityRepo() *memFacilityRepo {
+	return &memFacilityRepo{rows: map[string]*facility.Facility{}}
+}
+
+func (r *memFacilityRepo) Create(_ context.Context, row *facility.Facility) error {
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.rows[string(row.ID)] = row
+	r.lastCreate = row
+	return nil
+}
+
+func (r *memFacilityRepo) Update(_ context.Context, row *facility.Facility) error {
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	r.rows[string(row.ID)] = row
+	r.lastUpdate = row
+	return nil
+}
+
+func (r *memFacilityRepo) Delete(_ context.Context, id []byte, _ []byte) error {
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	r.lastDeleteID = append([]byte(nil), id...)
+	delete(r.rows, string(id))
+	return nil
+}
+
+func (r *memFacilityRepo) GetByID(_ context.Context, id []byte) (*facility.Facility, error) {
+	r.getCalls++
+	if r.getByIDFn != nil {
+		return r.getByIDFn(id, r.getCalls)
+	}
+	if r.getByIDErr != nil {
+		return nil, r.getByIDErr
+	}
+	return r.rows[string(id)], nil
+}
+
+func (r *memFacilityRepo) List(_ context.Context, filter, category, sort string, limit, offset int) ([]facility.Facility, int64, error) {
+	r.lastListFilter = filter
+	r.lastListCategory = category
+	r.lastListSort = sort
+	r.lastListLimit = limit
+	r.lastListOffset = offset
+	if r.listErr != nil {
+		return nil, 0, r.listErr
+	}
+	return r.listRows, r.listTotal, nil
+}
+
+func newFacilityTestApp(h *FacilityHandler) *fiber.App {
+	app := fiber.New()
+	app.Post("/api/v1/facilities/create", h.Create)
+	app.Patch("/api/v1/facilities/update/:uuid", h.Update)
+	app.Delete("/api/v1/facilities/delete/:uuid", h.Delete)
+	app.Get("/api/v1/facilities/get/:uuid", h.Get)
+	app.Get("/api/v1/facilities/get-all", h.List)
+	app.Get("/api/v1/facilities/get-all/dt", h.ListDatatable)
+	return app
+}
+
+func doJSONRequestFacility(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDStringFacility(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestNewFacilityHandler(t *testing.T) {
+	h := NewFacilityHandler(service.NewFacilityService(newMemFacilityRepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+func TestFacilityHandlerCreate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPost, "/api/v1/facilities/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPost, "/api/v1/facilities/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("required attrs cannot be empty after trim", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		body := []byte(`{"data":{"type":"facility","attributes":{"category":"   ","name":"A","type":"B"}}}`)
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPost, "/api/v1/facilities/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		repo.createErr = errors.New("create failed")
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		body := []byte(`{"data":{"type":"facility","attributes":{"category":"HEMS","name":"HEC Sling","type":"Sling"}}}`)
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPost, "/api/v1/facilities/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		actor := uuidv7.MustBytes()
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", actor)
+			return c.Next()
+		})
+		app.Post("/api/v1/facilities/create", h.Create)
+
+		body := []byte(`{"data":{"type":"facility","attributes":{"category":" HEMS ","name":" HEC Sling ","type":" Sling ","sortkey":3,"length":" 10m ","weight":" 20kg ","electric":" yes ","note":" note ","is_active":false}}}`)
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPost, "/api/v1/facilities/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected row created")
+		}
+		if repo.lastCreate.Category != "HEMS" || repo.lastCreate.Name != "HEC Sling" || repo.lastCreate.Type != "Sling" {
+			t.Fatalf("expected trimmed required fields")
+		}
+		if repo.lastCreate.SortKey == nil || *repo.lastCreate.SortKey != 3 {
+			t.Fatalf("expected sortkey mapped on create")
+		}
+		if repo.lastCreate.Length != "10m" || repo.lastCreate.Weight != "20kg" || repo.lastCreate.Electric != "yes" || repo.lastCreate.Note != "note" || repo.lastCreate.IsActive {
+			t.Fatalf("expected optional fields mapped and trimmed")
+		}
+		if string(repo.lastCreate.CreatedBy) != string(actor) || string(repo.lastCreate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected created_by and updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback when refetch fails and defaults", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		repo.getByIDFn = func(_ []byte, call int) (*facility.Facility, error) {
+			if call > 0 {
+				return nil, errors.New("lookup failed")
+			}
+			return nil, nil
+		}
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		body := []byte(`{"data":{"type":"facility","attributes":{"category":"DRY_LEASE","name":"Fuel Truck","type":"Ground"}}}`)
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPost, "/api/v1/facilities/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected row created")
+		}
+		if repo.lastCreate.Length != "" || repo.lastCreate.Weight != "" || repo.lastCreate.Electric != "" || repo.lastCreate.Note != "" || !repo.lastCreate.IsActive {
+			t.Fatalf("expected default optional values")
+		}
+	})
+}
+
+func TestFacilityHandlerUpdate(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		id := mustUUIDStringFacility(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/"+id, []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		id := mustUUIDStringFacility(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/"+id, []byte(`{"data":{"type":"x","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		id := mustUUIDStringFacility(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/"+id, []byte(`{"data":{"type":"facility","id":"","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		id := mustUUIDStringFacility(t, uuidv7.MustBytes())
+		other := mustUUIDStringFacility(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/"+id, []byte(`{"data":{"type":"facility","id":"`+other+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no attributes", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		id := mustUUIDStringFacility(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/"+id, []byte(`{"data":{"type":"facility","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		id := mustUUIDStringFacility(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/"+id, []byte(`{"data":{"type":"facility","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("category empty", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &facility.Facility{ID: id, Category: "HEMS", Name: "Old", Type: "Sling"}
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		idStr := mustUUIDStringFacility(t, id)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/"+idStr, []byte(`{"data":{"type":"facility","id":"`+idStr+`","attributes":{"category":"  "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &facility.Facility{ID: id, Category: "HEMS", Name: "Old", Type: "Sling"}
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		idStr := mustUUIDStringFacility(t, id)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/"+idStr, []byte(`{"data":{"type":"facility","id":"`+idStr+`","attributes":{"name":"  "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("type empty allowed", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &facility.Facility{ID: id, Category: "HEMS", Name: "Old", Type: "Sling"}
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		idStr := mustUUIDStringFacility(t, id)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/"+idStr, []byte(`{"data":{"type":"facility","id":"`+idStr+`","attributes":{"type":"  "}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.Type != "" {
+			t.Fatalf("expected type updated to empty string")
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &facility.Facility{ID: id, Category: "HEMS", Name: "Old", Type: "Sling"}
+		repo.updateErr = errors.New("update failed")
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		idStr := mustUUIDStringFacility(t, id)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/"+idStr, []byte(`{"data":{"type":"facility","id":"`+idStr+`","attributes":{"name":"New"}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &facility.Facility{ID: id, Category: "HEMS", Name: "Old", Type: "Sling", Length: "1m", Weight: "1kg", Electric: "", Note: "old", IsActive: true}
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		actor := uuidv7.MustBytes()
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", actor)
+			return c.Next()
+		})
+		app.Patch("/api/v1/facilities/update/:uuid", h.Update)
+		idStr := mustUUIDStringFacility(t, id)
+
+		body := []byte(`{"data":{"type":"facility","id":"` + idStr + `","attributes":{"category":" DRY_LEASE ","name":" New Name ","type":" Truck ","sortkey":7,"length":" 12m ","weight":" 50kg ","electric":" AC ","note":" updated ","is_active":false}}}`)
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/"+idStr, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil {
+			t.Fatalf("expected row updated")
+		}
+		if repo.lastUpdate.Category != "DRY_LEASE" || repo.lastUpdate.Name != "New Name" || repo.lastUpdate.Type != "Truck" {
+			t.Fatalf("expected trimmed required fields")
+		}
+		if repo.lastUpdate.SortKey == nil || *repo.lastUpdate.SortKey != 7 {
+			t.Fatalf("expected sortkey mapped on update")
+		}
+		if repo.lastUpdate.Length != "12m" || repo.lastUpdate.Weight != "50kg" || repo.lastUpdate.Electric != "AC" || repo.lastUpdate.Note != "updated" || repo.lastUpdate.IsActive {
+			t.Fatalf("expected updated optional values")
+		}
+		if string(repo.lastUpdate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		id := uuidv7.MustBytes()
+		existing := &facility.Facility{ID: id, Category: "HEMS", Name: "Old", Type: "Sling"}
+		repo.getByIDFn = func(_ []byte, call int) (*facility.Facility, error) {
+			if call == 1 {
+				return existing, nil
+			}
+			return nil, errors.New("second lookup failed")
+		}
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		idStr := mustUUIDStringFacility(t, id)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodPatch, "/api/v1/facilities/update/"+idStr, []byte(`{"data":{"type":"facility","id":"`+idStr+`","attributes":{"note":" only note "}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.Note != "only note" {
+			t.Fatalf("expected note updated in fallback path")
+		}
+	})
+}
+
+func TestFacilityHandlerDelete(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodDelete, "/api/v1/facilities/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete error", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		repo.deleteErr = errors.New("delete failed")
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		id := mustUUIDStringFacility(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodDelete, "/api/v1/facilities/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		id := uuidv7.MustBytes()
+		idStr := mustUUIDStringFacility(t, id)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodDelete, "/api/v1/facilities/delete/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(repo.lastDeleteID) != string(id) {
+			t.Fatalf("expected deleted id captured")
+		}
+	})
+}
+
+func TestFacilityHandlerGet(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodGet, "/api/v1/facilities/get/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		id := mustUUIDStringFacility(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodGet, "/api/v1/facilities/get/"+id, nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &facility.Facility{ID: id, Category: "HEMS", Name: "HEC Sling", Type: "Sling", CreatedAt: time.Now(), UpdatedAt: time.Now()}
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+		idStr := mustUUIDStringFacility(t, id)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodGet, "/api/v1/facilities/get/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestFacilityHandlerList(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodGet, "/api/v1/facilities/get-all", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with category trim and clamp max", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		repo.listRows = []facility.Facility{{ID: uuidv7.MustBytes(), Category: "HEMS", Name: "HEC Sling", Type: "Sling", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodGet, "/api/v1/facilities/get-all?search=abc&category=%20HEMS%20&page=0&limit=101&sort=-sortkey", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListCategory != "HEMS" || repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q category=%q sort=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListCategory, repo.lastListSort, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success with clamp min", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		repo.listRows = []facility.Facility{}
+		repo.listTotal = 0
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodGet, "/api/v1/facilities/get-all?page=2&limit=0&size=-1&search=needle", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "needle" || repo.lastListCategory != "" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q category=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListCategory, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestFacilityHandlerListDatatable(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodGet, "/api/v1/facilities/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success clamp max and page floor", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		repo.listRows = []facility.Facility{{ID: uuidv7.MustBytes(), Category: "DRY_LEASE", Name: "Fuel Truck", Type: "Ground", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodGet, "/api/v1/facilities/get-all/dt?page=0&limit=0&size=101&draw=7&search=abc&category=%20DRY_LEASE%20", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListCategory != "DRY_LEASE" || repo.lastListSort != "" || repo.lastListLimit != 100 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q category=%q sort=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListCategory, repo.lastListSort, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success clamp min", func(t *testing.T) {
+		repo := newMemFacilityRepo()
+		repo.listRows = []facility.Facility{}
+		repo.listTotal = 0
+		h := NewFacilityHandler(service.NewFacilityService(repo))
+		app := newFacilityTestApp(h)
+
+		resp, _ := doJSONRequestFacility(t, app, http.MethodGet, "/api/v1/facilities/get-all/dt?page=2&limit=0&size=-1", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListLimit != 20 || repo.lastListOffset != 20 {
+			t.Fatalf("unexpected list params: limit=%d offset=%d", repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestFacilityResource(t *testing.T) {
+	now := time.Now().UTC().Truncate(time.Second)
+	row := &facility.Facility{
+		ID:        uuidv7.MustBytes(),
+		Category:  "HEMS",
+		Name:      "HEC Sling",
+		Type:      "Sling",
+		SortKey:   intPtrFacilityHandler(5),
+		Length:    "10m",
+		Weight:    "20kg",
+		Electric:  "yes",
+		Note:      "ready",
+		IsActive:  true,
+		CreatedBy: uuidv7.MustBytes(),
+		UpdatedBy: uuidv7.MustBytes(),
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+
+	res := facilityResource(row)
+	if res.Type != "facility" {
+		t.Fatalf("unexpected type: %s", res.Type)
+	}
+	if res.ID == "" {
+		t.Fatalf("expected resource id")
+	}
+	if res.Attributes.Category != "HEMS" || res.Attributes.Name != "HEC Sling" || res.Attributes.Type != "Sling" {
+		t.Fatalf("expected required attributes in resource")
+	}
+	if res.Attributes.Length != "10m" || res.Attributes.Weight != "20kg" || res.Attributes.Electric != "yes" || res.Attributes.Note != "ready" || !res.Attributes.IsActive {
+		t.Fatalf("expected optional attributes in resource")
+	}
+	if res.Attributes.SortKey == nil || *res.Attributes.SortKey != 5 {
+		t.Fatalf("expected sortkey in resource")
+	}
+	if res.Attributes.CreatedAt == "" || res.Attributes.UpdatedAt == "" {
+		t.Fatalf("expected timestamp attributes in resource")
+	}
+	if res.Attributes.CreatedBy == "" {
+		t.Fatalf("expected created_by in resource")
+	}
+	if res.Attributes.UpdatedBy == "" {
+		t.Fatalf("expected updated_by in resource")
+	}
+}
+
+func intPtrFacilityHandler(v int) *int { return &v }
diff --git a/internal/transport/http/handlers/federal_state_handler.go b/internal/transport/http/handlers/federal_state_handler.go
new file mode 100644
index 0000000..f75a923
--- /dev/null
+++ b/internal/transport/http/handlers/federal_state_handler.go
@@ -0,0 +1,526 @@
+package handlers
+
+import (
+	"bytes"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/federal_state"
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type FederalStateHandler struct {
+	svc      federal_state.Service
+	validate *validators.Validator
+}
+
+func NewFederalStateHandler(svc federal_state.Service) *FederalStateHandler {
+	return &FederalStateHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateFederalState godoc
+// @Summary Create federal state
+// @Description Create a federal state row.
+// @Tags Hospital - Federal State
+// @Accept json
+// @Produce json
+// @Param request body dto.FederalStateCreateRequest true "JSON:API federal state create request"
+// @Success 201 {object} dto.FederalStateResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/federal-state/create [post]
+func (h *FederalStateHandler) Create(c *fiber.Ctx) error {
+	var req dto.FederalStateCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFederalStateErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	name := strings.TrimSpace(req.Data.Attributes.Name)
+	if name == "" {
+		return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+		}})
+	}
+	landID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.LandID))
+	if err != nil {
+		return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "land_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/land_id"},
+		}})
+	}
+
+	row := &federal_state.FederalState{
+		Name:      name,
+		Note:      strings.TrimSpace(stringOrDefault(req.Data.Attributes.Note, "")),
+		LandID:    landID,
+		SortKey:   cloneIntPointer(req.Data.Attributes.SortKey),
+		IsActive:  boolOrDefault(req.Data.Attributes.IsActive, true),
+		CreatedBy: actorUserID(c),
+		UpdatedBy: actorUserID(c),
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeFederalStateErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, federalStateResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, federalStateResource(row))
+}
+
+// UpdateFederalState godoc
+// @Summary Update federal state (partial)
+// @Description Patch federal state by ID.
+// @Tags Hospital - Federal State
+// @Accept json
+// @Produce json
+// @Param id path string true "Federal State ID (UUIDv7)"
+// @Param request body dto.FederalStateUpdateRequest true "JSON:API federal state update request"
+// @Success 200 {object} dto.FederalStateResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/federal-state/update/{id} [patch]
+func (h *FederalStateHandler) Update(c *fiber.Ctx) error {
+	idStr := c.Params("id")
+	id, err := uuidv7.ParseString(idStr)
+	if err != nil {
+		return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	var req dto.FederalStateUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFederalStateErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != idStr {
+		return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path id",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Name == nil && attrs.Note == nil && attrs.LandID == nil && !attrs.SortKey.Set && attrs.IsActive == nil {
+		return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeFederalStateErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "federal state not found",
+		}})
+	}
+
+	if attrs.Name != nil {
+		v := strings.TrimSpace(*attrs.Name)
+		if v == "" {
+			return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+			}})
+		}
+		existing.Name = v
+	}
+	if attrs.Note != nil {
+		existing.Note = strings.TrimSpace(*attrs.Note)
+	}
+	if attrs.LandID != nil {
+		parsed, parseErr := uuidv7.ParseString(strings.TrimSpace(*attrs.LandID))
+		if parseErr != nil {
+			return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "land_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/land_id"},
+			}})
+		}
+		existing.LandID = parsed
+		// Prevent stale preloaded belongs-to association from overriding new foreign key on Save.
+		if existing.Land != nil && !bytes.Equal(existing.Land.ID, parsed) {
+			existing.Land = nil
+		}
+	}
+	if attrs.SortKey.Set {
+		if attrs.SortKey.Valid {
+			sortKey := attrs.SortKey.Value
+			existing.SortKey = &sortKey
+		} else {
+			existing.SortKey = nil
+		}
+	}
+	if attrs.IsActive != nil {
+		existing.IsActive = *attrs.IsActive
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeFederalStateErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, federalStateResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, federalStateResource(existing))
+}
+
+// DeleteFederalState godoc
+// @Summary Delete federal state
+// @Tags Hospital - Federal State
+// @Produce json
+// @Param id path string true "Federal State ID (UUIDv7)"
+// @Success 200 {object} dto.FederalStateDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/federal-state/delete/{id} [delete]
+func (h *FederalStateHandler) Delete(c *fiber.Ctx) error {
+	idStr := c.Params("id")
+	id, err := uuidv7.ParseString(idStr)
+	if err != nil {
+		return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeFederalStateErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "federal state not found",
+			}})
+		}
+		if conflict, ok := apperrors.AsDeleteConflict(err); ok {
+			return writeFederalStateErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "Conflict",
+				Detail: conflict.Error(),
+			}})
+		}
+		return writeFederalStateErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "federal_state_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListFederalState godoc
+// @Summary List federal state
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.
+// @Tags Hospital - Federal State
+// @Produce json
+// @Param filter[search] query string false "Search by name"
+// @Param land_id query string false "Filter federal state by land UUID"
+// @Param land_name query string false "Filter federal state by land name"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.FederalStateListResponse
+// @Router /api/v1/federal-state/get-all [get]
+func (h *FederalStateHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("filter[name]")
+	}
+	landName := c.Query("land_name")
+	if landName == "" {
+		landName = c.Query("filter[land_name]")
+	}
+
+	landIDQuery := c.Query("land_id")
+	landID, landIDErr := parseOptionalUUID(&landIDQuery, "/query/land_id")
+	if landIDErr != nil {
+		landIDErr.Detail = "land_id is invalid UUID"
+		return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*landIDErr})
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 1)
+	pageSize := parseIntDefault(c.Query("page[size]"), 20)
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0, landID, landName)
+	if err != nil {
+		return writeFederalStateErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.FederalStateResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, federalStateResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListFederalStateDatatable godoc
+// @Summary List federal state (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags Hospital - Federal State
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Param filter[search] query string false "Search by name"
+// @Param land_id query string false "Filter federal state by land UUID"
+// @Param land_name query string false "Filter federal state by land name"
+// @Success 200 {object} dto.FederalStateDataTableResponse
+// @Router /api/v1/federal-state/get-all/dt [get]
+func (h *FederalStateHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+	if search == "" {
+		search = c.Query("filter[search]")
+	}
+	if search == "" {
+		search = c.Query("filter[name]")
+	}
+	landName := c.Query("land_name")
+	if landName == "" {
+		landName = c.Query("filter[land_name]")
+	}
+	landIDQuery := c.Query("land_id")
+	landID, landIDErr := parseOptionalUUID(&landIDQuery, "/query/land_id")
+	if landIDErr != nil {
+		landIDErr.Detail = "land_id is invalid UUID"
+		return writeFederalStateErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*landIDErr})
+	}
+
+	rows, total, err := h.svc.List(c.UserContext(), search, "", length, start, landID, landName)
+	if err != nil {
+		return writeFederalStateErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.FederalStateResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, federalStateResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func federalStateResource(row *federal_state.FederalState) dto.FederalStateResource {
+	return dto.FederalStateResource{
+		Type: "federal_state",
+		ID:   idString(row.ID),
+		Attributes: dto.FederalStateAttributes{
+			Name:        row.Name,
+			Note:        row.Note,
+			LandID:      idString(row.LandID),
+			LandName:    landNameFromFederalState(row),
+			LandISOCode: landISOCodeFromFederalState(row),
+			SortKey:     cloneIntPointer(row.SortKey),
+			IsActive:    row.IsActive,
+			CreatedAt:   row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:   uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:   row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:   uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt:   timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:   uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func landNameFromFederalState(row *federal_state.FederalState) string {
+	if row == nil || row.Land == nil {
+		return ""
+	}
+	return row.Land.Name
+}
+
+func landISOCodeFromFederalState(row *federal_state.FederalState) string {
+	if row == nil || row.Land == nil {
+		return ""
+	}
+	return row.Land.LandISOCode
+}
+
+func writeFederalStateErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	statusStr := strconv.Itoa(status)
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferFederalStateDef(status, e.Title, e.Detail)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		e.Detail = def.Message
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferFederalStateErrorCode(status int, title, detail string) (string, string) {
+	def := inferFederalStateDef(status, title, detail)
+	return def.Code, def.ErrorCode
+}
+
+func inferFederalStateDef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.ErrFederalStateNotFound
+	case fiber.StatusConflict:
+		return apperrorsx.ErrFederalStateRelationDelete
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "land_id is invalid uuid"):
+			return apperrorsx.ErrFederalStateLandIDInvalid
+		case strings.Contains(lowerDetail, "id is invalid uuid"), strings.Contains(lowerDetail, "invalid uuid"):
+			return apperrorsx.ErrFederalStateInvalidID
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.ErrFederalStateIDRequired
+		case strings.Contains(lowerDetail, "id does not match path id"):
+			return apperrorsx.ErrFederalStateIDMismatch
+		case strings.Contains(lowerDetail, "at least one attribute must be provided"):
+			return apperrorsx.ErrFederalStateAttributesRequired
+		case strings.Contains(lowerDetail, "name is required"), strings.Contains(lowerDetail, "name cannot be empty"):
+			return apperrorsx.ErrFederalStateNameRequired
+		default:
+			return apperrorsx.ErrFederalStateInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrFederalStateInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.ErrFederalStateCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrFederalStateUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrFederalStateDeleteFailed
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.ErrFederalStateListFailed
+		default:
+			return apperrorsx.ErrFederalStateInvalidPayload
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
diff --git a/internal/transport/http/handlers/federal_state_handler_test.go b/internal/transport/http/handlers/federal_state_handler_test.go
new file mode 100644
index 0000000..962725a
--- /dev/null
+++ b/internal/transport/http/handlers/federal_state_handler_test.go
@@ -0,0 +1,728 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/federal_state"
+	"wucher/internal/domain/land"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type memFederalStateRepo struct {
+	rows map[string]*federal_state.FederalState
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+
+	listRows  []federal_state.FederalState
+	listTotal int64
+
+	getByIDFn func(id []byte, call int) (*federal_state.FederalState, error)
+	getCalls  int
+
+	lastCreate     *federal_state.FederalState
+	lastUpdate     *federal_state.FederalState
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+	lastListLandID []byte
+	lastLandName   string
+}
+
+func newMemFederalStateRepo() *memFederalStateRepo {
+	return &memFederalStateRepo{
+		rows: map[string]*federal_state.FederalState{},
+	}
+}
+
+func (r *memFederalStateRepo) Create(_ context.Context, row *federal_state.FederalState) error {
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.rows[string(row.ID)] = row
+	r.lastCreate = row
+	return nil
+}
+
+func (r *memFederalStateRepo) Update(_ context.Context, row *federal_state.FederalState) error {
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	r.rows[string(row.ID)] = row
+	r.lastUpdate = row
+	return nil
+}
+
+func (r *memFederalStateRepo) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	r.lastDeleteID = append([]byte(nil), id...)
+	r.lastDeleteBy = append([]byte(nil), deletedBy...)
+	delete(r.rows, string(id))
+	return nil
+}
+
+func (r *memFederalStateRepo) GetByID(_ context.Context, id []byte) (*federal_state.FederalState, error) {
+	r.getCalls++
+	if r.getByIDFn != nil {
+		return r.getByIDFn(id, r.getCalls)
+	}
+	if r.getByIDErr != nil {
+		return nil, r.getByIDErr
+	}
+	return r.rows[string(id)], nil
+}
+
+func (r *memFederalStateRepo) List(_ context.Context, filter, sort string, limit, offset int, landID []byte, landName string) ([]federal_state.FederalState, int64, error) {
+	r.lastListFilter = filter
+	r.lastListSort = sort
+	r.lastListLimit = limit
+	r.lastListOffset = offset
+	r.lastListLandID = append([]byte(nil), landID...)
+	r.lastLandName = landName
+	if r.listErr != nil {
+		return nil, 0, r.listErr
+	}
+	return r.listRows, r.listTotal, nil
+}
+
+func newFederalStateTestApp(h *FederalStateHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", actor)
+		}
+		return c.Next()
+	})
+	app.Post("/api/v1/federal-state/create", h.Create)
+	app.Patch("/api/v1/federal-state/update/:id", h.Update)
+	app.Delete("/api/v1/federal-state/delete/:id", h.Delete)
+	app.Get("/api/v1/federal-state/get-all", h.List)
+	app.Get("/api/v1/federal-state/get-all/dt", h.ListDatatable)
+	return app
+}
+
+func doJSONRequestFederalState(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDStringFederalState(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestNewFederalStateHandler(t *testing.T) {
+	h := NewFederalStateHandler(service.NewFederalStateService(newMemFederalStateRepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+func TestFederalStateHandlerCreate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPost, "/api/v1/federal-state/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPost, "/api/v1/federal-state/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"federal_state","attributes":{"name":"  ","land_id":"019df658-8b00-74ce-9db0-2bdae4ea15fb"}}}`)
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPost, "/api/v1/federal-state/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		repo.createErr = errors.New("create failed")
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"federal_state","attributes":{"name":"Main","land_id":"019df658-8b00-74ce-9db0-2bdae4ea15fb"}}}`)
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPost, "/api/v1/federal-state/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid land_id", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"federal_state","attributes":{"name":"Main","land_id":"not-uuid"}}}`)
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPost, "/api/v1/federal-state/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		actor := uuidv7.MustBytes()
+		app := newFederalStateTestApp(h, actor)
+
+		body := []byte(`{"data":{"type":"federal_state","attributes":{"name":"Main","note":"  Important note  ","land_id":"019df658-8b00-74ce-9db0-2bdae4ea15fb","sortkey":9,"is_active":false}}}`)
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPost, "/api/v1/federal-state/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected row created")
+		}
+		if len(repo.lastCreate.LandID) == 0 {
+			t.Fatalf("expected land_id mapped")
+		}
+		if repo.lastCreate.SortKey == nil || *repo.lastCreate.SortKey != 9 || repo.lastCreate.IsActive {
+			t.Fatalf("expected sortkey/is_active mapped correctly")
+		}
+		if repo.lastCreate.Note != "Important note" {
+			t.Fatalf("expected note mapped and trimmed")
+		}
+		if string(repo.lastCreate.CreatedBy) != string(actor) || string(repo.lastCreate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected created_by and updated_by from actor")
+		}
+	})
+
+	t.Run("success clear sortkey with null", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &federal_state.FederalState{
+			ID:      id,
+			Name:    "Old",
+			LandID:  uuidv7.MustBytes(),
+			SortKey: intPtr(7),
+		}
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		idStr := mustUUIDStringFederalState(t, id)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+idStr, []byte(`{"data":{"type":"federal_state","id":"`+idStr+`","attributes":{"sortkey":null}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.SortKey != nil {
+			t.Fatalf("expected sortkey cleared")
+		}
+	})
+
+	t.Run("success fallback when refetch error", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		repo.getByIDFn = func(_ []byte, call int) (*federal_state.FederalState, error) {
+			if call > 0 {
+				return nil, errors.New("lookup failed")
+			}
+			return nil, nil
+		}
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"federal_state","attributes":{"name":"Main","land_id":"019df658-8b00-74ce-9db0-2bdae4ea15fb"}}}`)
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPost, "/api/v1/federal-state/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestFederalStateHandlerUpdate(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		id := mustUUIDStringFederalState(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+id, []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		id := mustUUIDStringFederalState(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+id, []byte(`{"data":{"type":"x","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		id := mustUUIDStringFederalState(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+id, []byte(`{"data":{"type":"federal_state","id":"","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		id := mustUUIDStringFederalState(t, uuidv7.MustBytes())
+		other := mustUUIDStringFederalState(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+id, []byte(`{"data":{"type":"federal_state","id":"`+other+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no attributes", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		id := mustUUIDStringFederalState(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+id, []byte(`{"data":{"type":"federal_state","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		id := mustUUIDStringFederalState(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+id, []byte(`{"data":{"type":"federal_state","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &federal_state.FederalState{ID: id, Name: "Old"}
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		idStr := mustUUIDStringFederalState(t, id)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+idStr, []byte(`{"data":{"type":"federal_state","id":"`+idStr+`","attributes":{"name":"  "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &federal_state.FederalState{ID: id, Name: "Old"}
+		repo.updateErr = errors.New("update failed")
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		idStr := mustUUIDStringFederalState(t, id)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+idStr, []byte(`{"data":{"type":"federal_state","id":"`+idStr+`","attributes":{"name":"New"}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid land_id", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &federal_state.FederalState{ID: id, Name: "Old"}
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		idStr := mustUUIDStringFederalState(t, id)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+idStr, []byte(`{"data":{"type":"federal_state","id":"`+idStr+`","attributes":{"land_id":"not-uuid"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &federal_state.FederalState{ID: id, Name: "Old"}
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		actor := uuidv7.MustBytes()
+		app := newFederalStateTestApp(h, actor)
+		idStr := mustUUIDStringFederalState(t, id)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+idStr, []byte(`{"data":{"type":"federal_state","id":"`+idStr+`","attributes":{"name":"New","note":"  Updated note  ","land_id":"019df658-8b00-74ce-9db0-2bdae4ea15fb","sortkey":2,"is_active":false}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.Name != "New" {
+			t.Fatalf("expected updated values")
+		}
+		if len(repo.lastUpdate.LandID) == 0 {
+			t.Fatalf("expected land_id updated")
+		}
+		if repo.lastUpdate.SortKey == nil || *repo.lastUpdate.SortKey != 2 || repo.lastUpdate.IsActive {
+			t.Fatalf("expected sortkey/is_active updated")
+		}
+		if repo.lastUpdate.Note != "Updated note" {
+			t.Fatalf("expected note updated and trimmed")
+		}
+		if string(repo.lastUpdate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected updated_by from actor")
+		}
+	})
+
+	t.Run("success change land_id clears stale land association", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		id := uuidv7.MustBytes()
+		oldLandID := uuidv7.MustBytes()
+		repo.rows[string(id)] = &federal_state.FederalState{
+			ID:     id,
+			Name:   "Old",
+			LandID: oldLandID,
+			Land:   &land.Land{ID: oldLandID, Name: "Old Land"},
+		}
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		idStr := mustUUIDStringFederalState(t, id)
+		newLandID := mustUUIDStringFederalState(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+idStr, []byte(`{"data":{"type":"federal_state","id":"`+idStr+`","attributes":{"land_id":"`+newLandID+`"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil {
+			t.Fatalf("expected update called")
+		}
+		if repo.lastUpdate.Land != nil {
+			t.Fatalf("expected stale land association cleared when land_id changes")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		id := uuidv7.MustBytes()
+		existing := &federal_state.FederalState{ID: id, Name: "Old"}
+		repo.getByIDFn = func(_ []byte, call int) (*federal_state.FederalState, error) {
+			if call == 1 {
+				return existing, nil
+			}
+			return nil, errors.New("second lookup failed")
+		}
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		idStr := mustUUIDStringFederalState(t, id)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodPatch, "/api/v1/federal-state/update/"+idStr, []byte(`{"data":{"type":"federal_state","id":"`+idStr+`","attributes":{"name":"Only","land_id":"019df658-8b00-74ce-9db0-2bdae4ea15fb"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestFederalStateHandlerDelete(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodDelete, "/api/v1/federal-state/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete error", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		repo.deleteErr = errors.New("delete failed")
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		id := mustUUIDStringFederalState(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodDelete, "/api/v1/federal-state/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		actor := uuidv7.MustBytes()
+		app := newFederalStateTestApp(h, actor)
+		id := uuidv7.MustBytes()
+		idStr := mustUUIDStringFederalState(t, id)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodDelete, "/api/v1/federal-state/delete/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(repo.lastDeleteBy) != string(actor) {
+			t.Fatalf("expected deleted_by from actor")
+		}
+	})
+}
+
+func TestFederalStateHandlerList(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodGet, "/api/v1/federal-state/get-all", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with filter name and clamp max", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		repo.listRows = []federal_state.FederalState{{ID: uuidv7.MustBytes(), Name: "A", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodGet, "/api/v1/federal-state/get-all?filter[name]=abc&page[number]=0&page[size]=101&sort=-name", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListSort != "name DESC" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q sort=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListSort, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success with filter search and pagination", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		repo.listRows = []federal_state.FederalState{}
+		repo.listTotal = 0
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodGet, "/api/v1/federal-state/get-all?filter[search]=needle&page[number]=2&page[size]=20", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "needle" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("invalid land_id", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodGet, "/api/v1/federal-state/get-all?land_id=not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("land filters forwarded", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		repo.listRows = []federal_state.FederalState{}
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		landID := mustUUIDStringFederalState(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodGet, "/api/v1/federal-state/get-all?filter[land_name]=Ger&land_id="+landID, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if len(repo.lastListLandID) == 0 || repo.lastLandName != "Ger" {
+			t.Fatalf("expected land filter mapped")
+		}
+	})
+}
+
+func TestFederalStateHandlerListDatatable(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodGet, "/api/v1/federal-state/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success clamp max and page floor", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		repo.listRows = []federal_state.FederalState{{ID: uuidv7.MustBytes(), Name: "A", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodGet, "/api/v1/federal-state/get-all/dt?page=0&limit=0&size=101&draw=7&search=abc", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListLimit != 100 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success clamp min", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		repo.listRows = []federal_state.FederalState{}
+		repo.listTotal = 0
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodGet, "/api/v1/federal-state/get-all/dt?page=2&limit=0&size=-1", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListLimit != 20 || repo.lastListOffset != 20 {
+			t.Fatalf("unexpected list params: limit=%d offset=%d", repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("invalid land_id", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodGet, "/api/v1/federal-state/get-all/dt?land_id=not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("land_name direct forwarded", func(t *testing.T) {
+		repo := newMemFederalStateRepo()
+		repo.listRows = []federal_state.FederalState{}
+		h := NewFederalStateHandler(service.NewFederalStateService(repo))
+		app := newFederalStateTestApp(h, nil)
+		landID := mustUUIDStringFederalState(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFederalState(t, app, http.MethodGet, "/api/v1/federal-state/get-all/dt?land_name=Germany&land_id="+landID, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastLandName != "Germany" || len(repo.lastListLandID) == 0 {
+			t.Fatalf("expected land_name and land_id forwarded")
+		}
+	})
+}
+
+func TestFederalStateResource(t *testing.T) {
+	id := uuidv7.MustBytes()
+	createdBy := uuidv7.MustBytes()
+	updatedBy := uuidv7.MustBytes()
+	deletedBy := uuidv7.MustBytes()
+	now := time.Now().UTC().Truncate(time.Second)
+	deletedAt := now.Add(time.Hour)
+
+	row := &federal_state.FederalState{
+		ID:        id,
+		Name:      "Main",
+		Note:      "Important note",
+		LandID:    uuidv7.MustBytes(),
+		Land:      &land.Land{Name: "Germany", LandISOCode: "DE"},
+		SortKey:   intPtr(4),
+		IsActive:  true,
+		CreatedAt: now,
+		CreatedBy: createdBy,
+		UpdatedAt: now,
+		UpdatedBy: updatedBy,
+		DeletedAt: &deletedAt,
+		DeletedBy: deletedBy,
+	}
+
+	res := federalStateResource(row)
+	if res.Type != "federal_state" {
+		t.Fatalf("unexpected type: %s", res.Type)
+	}
+	if res.ID == "" || res.Attributes.CreatedBy == "" || res.Attributes.UpdatedBy == "" || res.Attributes.DeletedBy == "" {
+		t.Fatalf("expected UUID fields in resource")
+	}
+	if res.Attributes.CreatedAt == "" || res.Attributes.UpdatedAt == "" || res.Attributes.DeletedAt == "" {
+		t.Fatalf("expected time fields in resource")
+	}
+	if res.Attributes.SortKey == nil || *res.Attributes.SortKey != 4 || !res.Attributes.IsActive {
+		t.Fatalf("expected sortkey/is_active in resource")
+	}
+	if res.Attributes.LandID == "" {
+		t.Fatalf("expected land_id in resource")
+	}
+	if res.Attributes.LandName != "Germany" || res.Attributes.LandISOCode != "DE" {
+		t.Fatalf("expected land preload fields in resource")
+	}
+	if res.Attributes.Note != "Important note" {
+		t.Fatalf("expected note in resource")
+	}
+}
diff --git a/internal/transport/http/handlers/file_lifecycle_hooks.go b/internal/transport/http/handlers/file_lifecycle_hooks.go
new file mode 100644
index 0000000..7bd9055
--- /dev/null
+++ b/internal/transport/http/handlers/file_lifecycle_hooks.go
@@ -0,0 +1,136 @@
+package handlers
+
+import (
+	"context"
+
+	filemanager "wucher/internal/domain/file_manager"
+)
+
+func resolveFileIDFromAttachment(ctx context.Context, svc filemanager.Service, attachmentID []byte) ([]byte, error) {
+	if len(attachmentID) != 16 || svc == nil {
+		return nil, nil
+	}
+	attachment, err := svc.GetAttachmentByID(ctx, attachmentID)
+	if err != nil || attachment == nil {
+		return nil, err
+	}
+	return attachment.FileID, nil
+}
+
+func syncAttachmentLifecycleSwap(
+	ctx context.Context,
+	svc filemanager.Service,
+	oldAttachmentID []byte,
+	newAttachmentID []byte,
+	actorID []byte,
+) error {
+	lifecycle, ok := svc.(filemanager.LifecycleManager)
+	if !ok {
+		return nil
+	}
+	oldFileID, err := resolveFileIDFromAttachment(ctx, svc, oldAttachmentID)
+	if err != nil {
+		return err
+	}
+	newFileID, err := resolveFileIDFromAttachment(ctx, svc, newAttachmentID)
+	if err != nil {
+		return err
+	}
+	if len(newFileID) == 16 {
+		if err := lifecycle.MarkFileActive(ctx, newFileID, actorID); err != nil {
+			return err
+		}
+	}
+	if len(oldFileID) == 16 && (len(newFileID) != 16 || string(oldFileID) != string(newFileID)) {
+		if err := lifecycle.ReconcileFileLifecycle(ctx, oldFileID, actorID); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func syncAttachmentLifecycleClear(
+	ctx context.Context,
+	svc filemanager.Service,
+	oldAttachmentID []byte,
+	actorID []byte,
+) error {
+	return syncAttachmentLifecycleSwap(ctx, svc, oldAttachmentID, nil, actorID)
+}
+
+func syncFileLifecycleSwap(
+	ctx context.Context,
+	svc filemanager.Service,
+	oldFileID []byte,
+	newFileID []byte,
+	actorID []byte,
+) error {
+	lifecycle, ok := svc.(filemanager.LifecycleManager)
+	if !ok {
+		return nil
+	}
+	if len(newFileID) == 16 {
+		if err := lifecycle.MarkFileActive(ctx, newFileID, actorID); err != nil {
+			return err
+		}
+	}
+	if len(oldFileID) == 16 && (len(newFileID) != 16 || string(oldFileID) != string(newFileID)) {
+		if err := lifecycle.ReconcileFileLifecycle(ctx, oldFileID, actorID); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func syncAttachmentLifecycleSet(
+	ctx context.Context,
+	svc filemanager.Service,
+	oldAttachmentIDs [][]byte,
+	newAttachmentIDs [][]byte,
+	actorID []byte,
+) error {
+	lifecycle, ok := svc.(filemanager.LifecycleManager)
+	if !ok {
+		return nil
+	}
+	oldMap := make(map[string][]byte, len(oldAttachmentIDs))
+	newMap := make(map[string][]byte, len(newAttachmentIDs))
+	for i := range oldAttachmentIDs {
+		if len(oldAttachmentIDs[i]) == 16 {
+			oldMap[string(oldAttachmentIDs[i])] = oldAttachmentIDs[i]
+		}
+	}
+	for i := range newAttachmentIDs {
+		if len(newAttachmentIDs[i]) == 16 {
+			newMap[string(newAttachmentIDs[i])] = newAttachmentIDs[i]
+		}
+	}
+
+	for _, attachmentID := range newMap {
+		fileID, err := resolveFileIDFromAttachment(ctx, svc, attachmentID)
+		if err != nil {
+			return err
+		}
+		if len(fileID) == 16 {
+			if err := lifecycle.MarkFileActive(ctx, fileID, actorID); err != nil {
+				return err
+			}
+		}
+	}
+
+	for key, attachmentID := range oldMap {
+		if _, keep := newMap[key]; keep {
+			continue
+		}
+		fileID, err := resolveFileIDFromAttachment(ctx, svc, attachmentID)
+		if err != nil {
+			return err
+		}
+		if len(fileID) == 16 {
+			if err := lifecycle.ReconcileFileLifecycle(ctx, fileID, actorID); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
diff --git a/internal/transport/http/handlers/file_manager_action_helpers.go b/internal/transport/http/handlers/file_manager_action_helpers.go
new file mode 100644
index 0000000..8d5b3da
--- /dev/null
+++ b/internal/transport/http/handlers/file_manager_action_helpers.go
@@ -0,0 +1,26 @@
+package handlers
+
+import (
+	"strings"
+
+	responsedto "wucher/internal/transport/http/dto/response"
+)
+
+func fileManagerActionResultResource(resourceType string, id []byte, status string, locationFolderID string) responsedto.FileManagerActionResultResource {
+	result := responsedto.FileManagerActionResultResource{
+		Type: resourceType,
+		ID:   uuidStringOrEmpty(id),
+		Attributes: responsedto.FileManagerActionResultAttributes{
+			Status: strings.TrimSpace(status),
+		},
+	}
+
+	locationFolderID = strings.TrimSpace(locationFolderID)
+	if locationFolderID != "" {
+		result.Attributes.Location = &responsedto.FileManagerActionLocation{
+			FolderID: locationFolderID,
+		}
+	}
+
+	return result
+}
diff --git a/internal/transport/http/handlers/file_manager_attachment_events_test.go b/internal/transport/http/handlers/file_manager_attachment_events_test.go
new file mode 100644
index 0000000..a17dbef
--- /dev/null
+++ b/internal/transport/http/handlers/file_manager_attachment_events_test.go
@@ -0,0 +1,650 @@
+package handlers
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+	"unsafe"
+
+	"github.com/gofiber/fiber/v2"
+	"github.com/valyala/fasthttp"
+
+	filemanager "wucher/internal/domain/file_manager"
+	filemanagerrealtime "wucher/internal/realtime/filemanager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type fileManagerAttachmentHandlerServiceMock struct {
+	filemanager.Service
+
+	createAttachmentFn func(context.Context, filemanager.CreateAttachmentParams) (*filemanager.Attachment, error)
+	getAttachmentFn    func(context.Context, []byte) (*filemanager.Attachment, error)
+	getFileFn          func(context.Context, []byte) (*filemanager.File, error)
+	listAttachmentsFn  func(context.Context, filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error)
+	deleteAttachmentFn func(context.Context, []byte) error
+}
+
+func (m *fileManagerAttachmentHandlerServiceMock) CreateAttachment(ctx context.Context, params filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+	if m.createAttachmentFn != nil {
+		return m.createAttachmentFn(ctx, params)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerAttachmentHandlerServiceMock) GetAttachmentByID(ctx context.Context, id []byte) (*filemanager.Attachment, error) {
+	if m.getAttachmentFn != nil {
+		return m.getAttachmentFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerAttachmentHandlerServiceMock) GetFileByID(ctx context.Context, id []byte) (*filemanager.File, error) {
+	if m.getFileFn != nil {
+		return m.getFileFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerAttachmentHandlerServiceMock) ListAttachmentsByReference(ctx context.Context, params filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error) {
+	if m.listAttachmentsFn != nil {
+		return m.listAttachmentsFn(ctx, params)
+	}
+	return nil, 0, nil
+}
+
+func (m *fileManagerAttachmentHandlerServiceMock) DeleteAttachment(ctx context.Context, id []byte) error {
+	if m.deleteAttachmentFn != nil {
+		return m.deleteAttachmentFn(ctx, id)
+	}
+	return nil
+}
+
+func newFileManagerAttachmentHandlerTestApp(h *FileManagerAttachmentHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", append([]byte(nil), actor...))
+		}
+		return c.Next()
+	})
+	app.Post("/api/v1/file-manager/attachments/create", h.CreateAttachment)
+	app.Get("/api/v1/file-manager/attachments/get/:uuid", h.GetAttachment)
+	app.Get("/api/v1/file-manager/attachments/get-all", h.ListAttachments)
+	app.Delete("/api/v1/file-manager/attachments/delete/:uuid", h.DeleteAttachment)
+	return app
+}
+
+func newFileManagerEventsHandlerTestApp(h *FileManagerEventsHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if actor != nil {
+			c.Locals("user_id", append([]byte(nil), actor...))
+		}
+		return c.Next()
+	})
+	app.Get("/api/v1/file-manager/events", h.Stream)
+	return app
+}
+
+func TestFileManagerActionAndErrorHelpers(t *testing.T) {
+	id := uuidv7.MustBytes()
+	resource := fileManagerActionResultResource("file_manager_delete_result", id, " trashed ", " "+mustUUIDStringFileManager(t, uuidv7.MustBytes())+" ")
+	if resource.Type != "file_manager_delete_result" || resource.ID == "" || resource.Attributes.Status != "trashed" {
+		t.Fatalf("unexpected action resource: %#v", resource)
+	}
+	if resource.Attributes.Location == nil || resource.Attributes.Location.FolderID == "" {
+		t.Fatalf("expected action location")
+	}
+	noLocation := fileManagerActionResultResource("file_manager_restore_result", id, "ready", " ")
+	if noLocation.Attributes.Location != nil {
+		t.Fatalf("expected nil location")
+	}
+
+	tests := []struct {
+		err        error
+		wantStatus int
+		wantTitle  string
+	}{
+		{err: errors.New("plain"), wantStatus: http.StatusBadRequest, wantTitle: "Action failed"},
+		{err: filemanager.ErrStorageUnavailable, wantStatus: http.StatusServiceUnavailable, wantTitle: "Storage unavailable"},
+		{err: filemanager.ErrFileProcessingQueueDisabled, wantStatus: http.StatusServiceUnavailable, wantTitle: "Queue unavailable"},
+		{err: filemanager.ErrUploadIntentRepositoryDisabled, wantStatus: http.StatusServiceUnavailable, wantTitle: "Upload intent unavailable"},
+		{err: filemanager.ErrFolderNotFound, wantStatus: http.StatusNotFound, wantTitle: "Not found"},
+		{err: filemanager.ErrFileNotFound, wantStatus: http.StatusNotFound, wantTitle: "Not found"},
+		{err: filemanager.ErrAttachmentNotFound, wantStatus: http.StatusNotFound, wantTitle: "Attachment not found"},
+		{err: filemanager.ErrUploadIntentNotFound, wantStatus: http.StatusNotFound, wantTitle: "Upload intent not found"},
+		{err: filemanager.ErrFileStatusConflict, wantStatus: http.StatusConflict, wantTitle: "Conflict"},
+		{err: filemanager.ErrUploadIntentExpired, wantStatus: http.StatusConflict, wantTitle: "Upload intent conflict"},
+		{err: filemanager.ErrDuplicateName, wantStatus: http.StatusUnprocessableEntity, wantTitle: "Validation error"},
+		{err: filemanager.ErrAttachmentRepositoryDisabled, wantStatus: http.StatusServiceUnavailable, wantTitle: "Attachment service unavailable"},
+	}
+	for _, tc := range tests {
+		status, title, detail, _, _ := mapFileManagerActionError("Action failed", tc.err)
+		if status != tc.wantStatus || title != tc.wantTitle || detail == "" {
+			t.Fatalf("unexpected map result for %v: %d %q %q", tc.err, status, title, detail)
+		}
+	}
+}
+
+func TestFileManagerAttachmentHandler(t *testing.T) {
+	t.Run("create attachment", func(t *testing.T) {
+		fileID := uuidv7.MustBytes()
+		attachmentID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		category := "document"
+		sortOrder := 2
+		isPrimary := true
+		svc := &fileManagerAttachmentHandlerServiceMock{
+			createAttachmentFn: func(_ context.Context, params filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+				return &filemanager.Attachment{
+					ID:         attachmentID,
+					FileID:     params.FileID,
+					RefType:    params.RefType,
+					RefID:      params.RefID,
+					Category:   params.Category,
+					SortOrder:  params.SortOrder,
+					IsPrimary:  params.IsPrimary,
+					AttachedBy: params.ActorID,
+					CreatedAt:  now,
+					UpdatedAt:  now,
+				}, nil
+			},
+		}
+		app := newFileManagerAttachmentHandlerTestApp(NewFileManagerAttachmentHandler(svc), uuidv7.MustBytes())
+		body := []byte(`{"data":{"type":"file_manager_attachment_create","attributes":{"file_id":"` + mustUUIDStringFileManager(t, fileID) + `","ref_type":"helicopter","ref_id":"abc","category":"` + category + `","sort_order":` + "2" + `,"is_primary":true}}}`)
+		resp, raw := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/attachments/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		out := decodeJSONMapFileManagerFile(t, raw)
+		data := mapField(t, out["data"], "data")
+		if data["type"] != "file_manager_attachment" {
+			t.Fatalf("unexpected type: %#v", data["type"])
+		}
+		attrs := mapField(t, data["attributes"], "attributes")
+		if attrs["sort_order"] != float64(sortOrder) || attrs["is_primary"] != isPrimary {
+			t.Fatalf("unexpected attachment attrs: %#v", attrs)
+		}
+	})
+
+	t.Run("attachment validations and errors", func(t *testing.T) {
+		attachmentID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		category := "image"
+		svc := &fileManagerAttachmentHandlerServiceMock{
+			createAttachmentFn: func(context.Context, filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+				return nil, filemanager.ErrAttachmentAlreadyExists
+			},
+			getAttachmentFn: func(_ context.Context, id []byte) (*filemanager.Attachment, error) {
+				if bytes.Equal(id, attachmentID) {
+					return &filemanager.Attachment{
+						ID:         id,
+						FileID:     fileID,
+						RefType:    "helicopter",
+						RefID:      "ref-1",
+						Category:   &category,
+						SortOrder:  1,
+						IsPrimary:  true,
+						AttachedBy: uuidv7.MustBytes(),
+						CreatedAt:  now,
+						UpdatedAt:  now,
+					}, nil
+				}
+				return nil, filemanager.ErrAttachmentNotFound
+			},
+			listAttachmentsFn: func(_ context.Context, params filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error) {
+				if params.RefType == "boom" {
+					return nil, 0, filemanager.ErrAttachmentRepositoryDisabled
+				}
+				return []filemanager.Attachment{{
+					ID:         attachmentID,
+					FileID:     fileID,
+					RefType:    params.RefType,
+					RefID:      params.RefID,
+					Category:   params.Category,
+					SortOrder:  1,
+					IsPrimary:  true,
+					AttachedBy: uuidv7.MustBytes(),
+					CreatedAt:  now,
+					UpdatedAt:  now,
+				}}, 1, nil
+			},
+			deleteAttachmentFn: func(_ context.Context, id []byte) error {
+				if bytes.Equal(id, attachmentID) {
+					return nil
+				}
+				return filemanager.ErrAttachmentNotFound
+			},
+		}
+		app := newFileManagerAttachmentHandlerTestApp(NewFileManagerAttachmentHandler(svc), uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/attachments/create", []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid json, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/attachments/create", []byte(`{"data":{"type":"file_manager_attachment_create","attributes":{"file_id":"bad","ref_type":"helicopter","ref_id":"abc"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid file id, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/attachments/create", []byte(`{"data":{"type":"file_manager_attachment_create","attributes":{"file_id":"`+mustUUIDStringFileManager(t, fileID)+`","ref_type":"helicopter","ref_id":"abc","sort_order":-1}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid sort_order, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/attachments/create", []byte(`{"data":{"type":"file_manager_attachment_create","attributes":{"file_id":"`+mustUUIDStringFileManager(t, fileID)+`","ref_type":"helicopter","ref_id":"abc"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 create action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/attachments/get/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz", nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 invalid uuid path handling, got %d", resp.StatusCode)
+		}
+		resp, raw := doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/attachments/get/"+mustUUIDStringFileManager(t, attachmentID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 get attachment, got %d", resp.StatusCode)
+		}
+		if mapField(t, decodeJSONMapFileManagerFile(t, raw)["data"], "data")["type"] != "file_manager_attachment" {
+			t.Fatalf("expected attachment resource")
+		}
+		nilRowID := mustUUIDStringFileManager(t, uuidv7.MustBytes())
+		svc.getAttachmentFn = func(_ context.Context, id []byte) (*filemanager.Attachment, error) {
+			if bytes.Equal(id, attachmentID) {
+				return &filemanager.Attachment{
+					ID:         id,
+					FileID:     fileID,
+					RefType:    "helicopter",
+					RefID:      "ref-1",
+					Category:   &category,
+					SortOrder:  1,
+					IsPrimary:  true,
+					AttachedBy: uuidv7.MustBytes(),
+					CreatedAt:  now,
+					UpdatedAt:  now,
+				}, nil
+			}
+			if idString(id) == nilRowID {
+				return nil, nil
+			}
+			return nil, filemanager.ErrAttachmentNotFound
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/attachments/get/"+nilRowID, nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 nil row, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/attachments/get/"+mustUUIDStringFileManager(t, uuidv7.MustBytes()), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 get attachment not found, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/attachments/get-all", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 list attachments missing ref, got %d", resp.StatusCode)
+		}
+		resp, raw = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/attachments/get-all?ref_type=helicopter&ref_id=ref-1&page[number]=0&page[size]=999", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 list attachments, got %d", resp.StatusCode)
+		}
+		meta := mapField(t, decodeJSONMapFileManagerFile(t, raw)["meta"], "meta")
+		if meta["total"] == nil {
+			t.Fatalf("expected total in meta, got %#v", meta)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/attachments/get-all?ref_type=boom&ref_id=ref-1", nil)
+		if resp.StatusCode != http.StatusServiceUnavailable {
+			t.Fatalf("expected 503 list attachments action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/attachments/delete/"+mustUUIDStringFileManager(t, attachmentID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 delete attachment, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/attachments/delete/"+mustUUIDStringFileManager(t, uuidv7.MustBytes()), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 delete attachment not found, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/attachments/delete/zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz", nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 invalid delete uuid path handling, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("attachment helpers", func(t *testing.T) {
+		app := fiber.New()
+		h := NewFileManagerAttachmentHandler(&fileManagerAttachmentHandlerServiceMock{})
+		app.Get("/:uuid", func(c *fiber.Ctx) error {
+			if _, err := h.parseUUIDParam(c, "uuid", "/path/uuid"); err != nil {
+				return err
+			}
+			page, size, offset := parseFileManagerAttachmentPagination(c)
+			if page != 1 || size != 100 || offset != 0 {
+				t.Fatalf("unexpected pagination %d %d %d", page, size, offset)
+			}
+			return nil
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/"+mustUUIDStringFileManager(t, uuidv7.MustBytes())+"?page[number]=0&page[size]=999", nil)
+		resp, err := app.Test(req)
+		if err != nil || resp.StatusCode != http.StatusOK {
+			t.Fatalf("unexpected app.Test result: %v %v", resp, err)
+		}
+
+		category := " doc "
+		row := &filemanager.Attachment{
+			ID:         uuidv7.MustBytes(),
+			FileID:     uuidv7.MustBytes(),
+			RefType:    " helicopter ",
+			RefID:      " ref-1 ",
+			Category:   &category,
+			SortOrder:  3,
+			IsPrimary:  true,
+			AttachedBy: uuidv7.MustBytes(),
+			CreatedAt:  time.Now().UTC(),
+			UpdatedAt:  time.Now().UTC(),
+		}
+		if fileManagerAttachmentResource(nil).Type != "file_manager_attachment" {
+			t.Fatalf("expected nil attachment fallback type")
+		}
+		resource := fileManagerAttachmentResource(row)
+		if resource.Attributes.Category != "doc" || resource.Attributes.RefType != "helicopter" || resource.Attributes.RefID != "ref-1" {
+			t.Fatalf("unexpected attachment resource attrs: %#v", resource.Attributes)
+		}
+	})
+}
+
+func TestFileManagerEventsHandlerAndHelpers(t *testing.T) {
+	t.Run("stream guard rails", func(t *testing.T) {
+		appNil := newFileManagerEventsHandlerTestApp(NewFileManagerEventsHandler(nil), nil)
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/file-manager/events", nil)
+		resp, err := appNil.Test(req)
+		if err != nil {
+			t.Fatalf("unexpected nil-hub app.Test error: %v", err)
+		}
+		if resp.StatusCode != http.StatusServiceUnavailable {
+			t.Fatalf("expected 503 nil hub, got %d", resp.StatusCode)
+		}
+
+		appShortActor := newFileManagerEventsHandlerTestApp(NewFileManagerEventsHandler(filemanagerrealtime.NewHub(1, slog.Default())), []byte("short"))
+		req, _ = http.NewRequest(http.MethodGet, "/api/v1/file-manager/events", nil)
+		resp, err = appShortActor.Test(req)
+		if err != nil {
+			t.Fatalf("unexpected short-actor app.Test error: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401 invalid actor, got %d", resp.StatusCode)
+		}
+
+		appBadFilter := fiber.New()
+		fctx := &fasthttp.RequestCtx{}
+		fctx.Request.SetRequestURI("/api/v1/file-manager/events?folder_id=zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz")
+		c := appBadFilter.AcquireCtx(fctx)
+		c.Locals("user_id", uuidv7.MustBytes())
+		err = NewFileManagerEventsHandler(filemanagerrealtime.NewHub(1, slog.Default())).Stream(c)
+		appBadFilter.ReleaseCtx(c)
+		if err != nil {
+			t.Fatalf("unexpected direct stream filter error return: %v", err)
+		}
+		if fctx.Response.StatusCode() != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid folder filter, got %d", fctx.Response.StatusCode())
+		}
+
+		app := newFileManagerEventsHandlerTestApp(NewFileManagerEventsHandler(filemanagerrealtime.NewHub(1, slog.Default())), uuidv7.MustBytes())
+		req, _ = http.NewRequest(http.MethodGet, "/api/v1/file-manager/events", nil)
+		_, err = app.Test(req, 50)
+		if err == nil {
+			t.Fatalf("expected streaming request timeout to stop test request")
+		}
+
+		hub := filemanagerrealtime.NewHub(1, slog.Default())
+		actor := uuidv7.MustBytes()
+		userUUID, _ := uuidv7.BytesToString(actor)
+		appDirect := fiber.New()
+		fctx2 := &fasthttp.RequestCtx{}
+		fctx2.Request.SetRequestURI("/api/v1/file-manager/events")
+		c2 := appDirect.AcquireCtx(fctx2)
+		c2.Locals("user_id", actor)
+		if err := NewFileManagerEventsHandler(hub).Stream(c2); err != nil {
+			t.Fatalf("unexpected direct stream setup error: %v", err)
+		}
+		folderID := mustUUIDStringFileManager(t, uuidv7.MustBytes())
+		hub.PublishToUsers([]string{userUUID}, filemanagerrealtime.FileStatusEvent{
+			FileUUID:   mustUUIDStringFileManager(t, uuidv7.MustBytes()),
+			FolderUUID: &folderID,
+			Status:     "ready",
+			Name:       "image.png",
+			MimeType:   "image/png",
+			UpdatedAt:  time.Now().UTC().Format(time.RFC3339),
+		})
+		go func() {
+			time.Sleep(10 * time.Millisecond)
+			closeFirstHubSubscriberForUser(hub, userUUID)
+		}()
+		respStr := c2.Context().Response.String()
+		appDirect.ReleaseCtx(c2)
+		if !strings.Contains(respStr, ": connected") || !strings.Contains(respStr, "event: "+fileManagerSSEEventName) {
+			t.Fatalf("unexpected stream response output: %q", respStr)
+		}
+
+		filteredHub := filemanagerrealtime.NewHub(2, slog.Default())
+		filterActor := uuidv7.MustBytes()
+		filterUserUUID, _ := uuidv7.BytesToString(filterActor)
+		filterFileID := mustUUIDStringFileManager(t, uuidv7.MustBytes())
+		appFiltered := fiber.New()
+		filterCtx := &fasthttp.RequestCtx{}
+		filterCtx.Request.SetRequestURI("/api/v1/file-manager/events?file_id=" + filterFileID)
+		c3 := appFiltered.AcquireCtx(filterCtx)
+		c3.Locals("user_id", filterActor)
+		if err := NewFileManagerEventsHandler(filteredHub).Stream(c3); err != nil {
+			t.Fatalf("unexpected filtered stream setup error: %v", err)
+		}
+		filteredHub.PublishToUsers([]string{filterUserUUID}, filemanagerrealtime.FileStatusEvent{
+			FileUUID:  mustUUIDStringFileManager(t, uuidv7.MustBytes()),
+			Status:    "processing",
+			Name:      "skip.png",
+			UpdatedAt: time.Now().UTC().Format(time.RFC3339),
+		})
+		filteredHub.PublishToUsers([]string{filterUserUUID}, filemanagerrealtime.FileStatusEvent{
+			FileUUID:  filterFileID,
+			Status:    "ready",
+			Name:      "keep.png",
+			UpdatedAt: time.Now().UTC().Format(time.RFC3339),
+		})
+		go func() {
+			time.Sleep(10 * time.Millisecond)
+			closeFirstHubSubscriberForUser(filteredHub, filterUserUUID)
+		}()
+		filteredRespStr := c3.Context().Response.String()
+		appFiltered.ReleaseCtx(c3)
+		if strings.Contains(filteredRespStr, "skip.png") || !strings.Contains(filteredRespStr, "keep.png") {
+			t.Fatalf("unexpected filtered stream response output: %q", filteredRespStr)
+		}
+
+		doneHub := filemanagerrealtime.NewHub(1, slog.Default())
+		doneActor := uuidv7.MustBytes()
+		doneUserUUID, _ := uuidv7.BytesToString(doneActor)
+		appDone := fiber.New()
+		doneCtx := &fasthttp.RequestCtx{}
+		doneCtx.Request.SetRequestURI("/api/v1/file-manager/events")
+		c4 := appDone.AcquireCtx(doneCtx)
+		c4.Locals("user_id", doneActor)
+		if err := NewFileManagerEventsHandler(doneHub).Stream(c4); err != nil {
+			t.Fatalf("unexpected done stream setup error: %v", err)
+		}
+		go func() {
+			time.Sleep(10 * time.Millisecond)
+			signalDoneFirstHubSubscriberForUser(doneHub, doneUserUUID)
+		}()
+		doneRespStr := c4.Context().Response.String()
+		appDone.ReleaseCtx(c4)
+		if !strings.Contains(doneRespStr, ": connected") {
+			t.Fatalf("unexpected done stream response output: %q", doneRespStr)
+		}
+	})
+
+	t.Run("parse filter match payload and sse writers", func(t *testing.T) {
+		fileID1 := mustUUIDStringFileManager(t, uuidv7.MustBytes())
+		fileID2 := mustUUIDStringFileManager(t, uuidv7.MustBytes())
+		folderID := mustUUIDStringFileManager(t, uuidv7.MustBytes())
+		app := fiber.New()
+		fctx := &fasthttp.RequestCtx{}
+		fctx.Request.URI().SetQueryString("folder_id=" + folderID + "&file_id=" + fileID1 + "&file_ids=" + fileID1 + "," + fileID2)
+		c := app.AcquireCtx(fctx)
+		filter, err := parseFileManagerSSEFilter(c)
+		app.ReleaseCtx(c)
+		if err != nil {
+			t.Fatalf("unexpected parse filter error: %v", err)
+		}
+		matched := filter.folderID != nil && len(filter.fileIDs) == 2 && filter.match(filemanagerrealtime.FileStatusEvent{FileUUID: strings.ToUpper(fileID1), FolderUUID: filter.folderID})
+		unmatchedEmpty := filter.match(filemanagerrealtime.FileStatusEvent{FileUUID: ""})
+		unmatchedFolderless := filter.match(filemanagerrealtime.FileStatusEvent{FileUUID: fileID1})
+		if !matched || unmatchedEmpty || unmatchedFolderless {
+			t.Fatalf("unexpected match results matched=%v empty=%v folderless=%v", matched, unmatchedEmpty, unmatchedFolderless)
+		}
+
+		payload := mapFileStatusEventToSSEPayload(filemanagerrealtime.FileStatusEvent{
+			FileUUID:   " file-id ",
+			FolderUUID: filter.folderID,
+			Status:     " ready ",
+			Name:       " name ",
+			MimeType:   " image/png ",
+			UpdatedAt:  " now ",
+		})
+		payloadFolder := ""
+		if payload.FolderID != nil {
+			payloadFolder = *payload.FolderID
+		}
+		payloadFileID := payload.FileID
+		payloadStatus := payload.Status
+		if payloadFileID != "file-id" || payloadStatus != "ready" || payloadFolder != folderID {
+			t.Fatalf("unexpected payload values: file=%q status=%q folder=%q", payloadFileID, payloadStatus, payloadFolder)
+		}
+
+		emptyCtx := &fasthttp.RequestCtx{}
+		emptyCtx.Request.SetRequestURI("/")
+		c = app.AcquireCtx(emptyCtx)
+		emptyFilter, err := parseFileManagerSSEFilter(c)
+		app.ReleaseCtx(c)
+		if err != nil || emptyFilter.folderID != nil || len(emptyFilter.fileIDs) != 0 {
+			t.Fatalf("unexpected empty filter result: %#v err=%v", emptyFilter, err)
+		}
+
+		var buf bytes.Buffer
+		writer := bufio.NewWriter(&buf)
+		if !writeSSEComment(writer, " connected ") {
+			t.Fatalf("expected comment write success")
+		}
+		if !strings.Contains(buf.String(), ": connected") {
+			t.Fatalf("unexpected comment output %q", buf.String())
+		}
+		buf.Reset()
+		writer = bufio.NewWriter(&buf)
+		if !writeSSEDataEvent(writer, " file.updated ", map[string]any{"status": "ready"}) {
+			t.Fatalf("expected data event write success")
+		}
+		if !strings.Contains(buf.String(), "event: file.updated") || !strings.Contains(buf.String(), "\"status\":\"ready\"") {
+			t.Fatalf("unexpected data event output %q", buf.String())
+		}
+	})
+
+	t.Run("sse writer failures", func(t *testing.T) {
+		bw := bufio.NewWriter(errWriter{})
+		if writeSSEComment(bw, "x") {
+			t.Fatalf("expected comment writer failure")
+		}
+		bw = bufio.NewWriterSize(&failOnWriteWriter{failOn: 1}, 1)
+		if writeSSEComment(bw, strings.Repeat("x", 32)) {
+			t.Fatalf("expected comment immediate write failure")
+		}
+		bw = bufio.NewWriter(errWriter{})
+		if writeSSEDataEvent(bw, "event", map[string]any{"status": "ready"}) {
+			t.Fatalf("expected data writer failure")
+		}
+		bw = bufio.NewWriterSize(&failOnWriteWriter{failOn: 1}, 1)
+		if writeSSEDataEvent(bw, strings.Repeat("e", 32), map[string]any{"status": "ready"}) {
+			t.Fatalf("expected data event first write failure")
+		}
+		bw = bufio.NewWriterSize(&failOnWriteWriter{failOn: 2}, 1)
+		if writeSSEDataEvent(bw, "event", map[string]any{"status": "ready"}) {
+			t.Fatalf("expected data event second write failure")
+		}
+		bw = bufio.NewWriter(io.Discard)
+		if writeSSEDataEvent(bw, "event", func() {}) {
+			t.Fatalf("expected marshal failure")
+		}
+	})
+}
+
+type errWriter struct{}
+
+func (errWriter) Write([]byte) (int, error) {
+	return 0, errors.New("write fail")
+}
+
+type failOnWriteWriter struct {
+	failOn int
+	calls  int
+}
+
+func (w *failOnWriteWriter) Write(p []byte) (int, error) {
+	w.calls++
+	if w.calls >= w.failOn {
+		return 0, errors.New("write fail")
+	}
+	return len(p), nil
+}
+
+func closeFirstHubSubscriberForUser(hub *filemanagerrealtime.Hub, userUUID string) {
+	if hub == nil {
+		return
+	}
+	hubValue := reflect.ValueOf(hub).Elem()
+	subscribersField := reflect.NewAt(hubValue.FieldByName("subscribers").Type(), unsafe.Pointer(hubValue.FieldByName("subscribers").UnsafeAddr())).Elem()
+	byUser := subscribersField.MapIndex(reflect.ValueOf(strings.ToLower(strings.TrimSpace(userUUID))))
+	if !byUser.IsValid() || byUser.Len() == 0 {
+		return
+	}
+	iter := byUser.MapRange()
+	if !iter.Next() {
+		return
+	}
+	sub := iter.Value()
+	if sub.IsNil() {
+		return
+	}
+	subElem := sub.Elem()
+	eventsField := reflect.NewAt(subElem.FieldByName("events").Type(), unsafe.Pointer(subElem.FieldByName("events").UnsafeAddr())).Elem()
+	eventsField.Close()
+}
+
+func signalDoneFirstHubSubscriberForUser(hub *filemanagerrealtime.Hub, userUUID string) {
+	if hub == nil {
+		return
+	}
+	hubValue := reflect.ValueOf(hub).Elem()
+	subscribersField := reflect.NewAt(hubValue.FieldByName("subscribers").Type(), unsafe.Pointer(hubValue.FieldByName("subscribers").UnsafeAddr())).Elem()
+	byUser := subscribersField.MapIndex(reflect.ValueOf(strings.ToLower(strings.TrimSpace(userUUID))))
+	if !byUser.IsValid() || byUser.Len() == 0 {
+		return
+	}
+	iter := byUser.MapRange()
+	if !iter.Next() {
+		return
+	}
+	sub := iter.Value()
+	if sub.IsNil() {
+		return
+	}
+	subElem := sub.Elem()
+	closeOnceField := reflect.NewAt(subElem.FieldByName("closeOnce").Type(), unsafe.Pointer(subElem.FieldByName("closeOnce").UnsafeAddr())).Elem()
+	closeOncePtr := (*sync.Once)(unsafe.Pointer(closeOnceField.UnsafeAddr()))
+	closeOncePtr.Do(func() {})
+	doneField := reflect.NewAt(subElem.FieldByName("done").Type(), unsafe.Pointer(subElem.FieldByName("done").UnsafeAddr())).Elem()
+	doneField.Close()
+}
diff --git a/internal/transport/http/handlers/file_manager_attachment_handler.go b/internal/transport/http/handlers/file_manager_attachment_handler.go
new file mode 100644
index 0000000..789f680
--- /dev/null
+++ b/internal/transport/http/handlers/file_manager_attachment_handler.go
@@ -0,0 +1,265 @@
+package handlers
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+	dto "wucher/internal/transport/http/dto"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type FileManagerAttachmentHandler struct {
+	svc      filemanager.Service
+	validate *validators.Validator
+}
+
+var (
+	_ = dto.ErrorResponse{}
+	_ = dto.GenericDeleteResponse{}
+)
+
+func NewFileManagerAttachmentHandler(svc filemanager.Service) *FileManagerAttachmentHandler {
+	return &FileManagerAttachmentHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateAttachment godoc
+// @Summary Attach file to business reference
+// @ID FileManagerCreateAttachment
+// @Description Create generic attachment relation between a file and business reference (ref_type/ref_id).
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerAttachmentCreateRequest true "JSON:API attachment create request"
+// @Success 201 {object} responsedto.FileManagerAttachmentResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/attachments/create [post]
+func (h *FileManagerAttachmentHandler) CreateAttachment(c *fiber.Ctx) error {
+	var req requestdto.FileManagerAttachmentCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "invalid attachment payload", nil)
+	}
+
+	fileID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.FileID))
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "file_id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/data/attributes/file_id"})
+	}
+
+	sortOrder := 0
+	if req.Data.Attributes.SortOrder != nil {
+		sortOrder = *req.Data.Attributes.SortOrder
+	}
+	if sortOrder < 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "sort_order must be greater than or equal to 0", &jsonapi.ErrorSource{Pointer: "/data/attributes/sort_order"})
+	}
+
+	isPrimary := false
+	if req.Data.Attributes.IsPrimary != nil {
+		isPrimary = *req.Data.Attributes.IsPrimary
+	}
+
+	created, err := h.svc.CreateAttachment(c.Context(), filemanager.CreateAttachmentParams{
+		FileID:    fileID,
+		RefType:   req.Data.Attributes.RefType,
+		RefID:     req.Data.Attributes.RefID,
+		Category:  req.Data.Attributes.Category,
+		SortOrder: sortOrder,
+		IsPrimary: isPrimary,
+		ActorID:   actorUserID(c),
+	})
+	if err != nil {
+		return writeFileManagerActionError(c, "Attach failed", err)
+	}
+
+	return response.Write(c, fiber.StatusCreated, fileManagerAttachmentResource(created))
+}
+
+// GetAttachment godoc
+// @Summary Get attachment detail
+// @ID FileManagerGetAttachment
+// @Description Get one generic attachment relation by UUID.
+// @Tags File Manager
+// @Produce json
+// @Param uuid path string true "Attachment UUID (UUIDv7)"
+// @Success 200 {object} responsedto.FileManagerAttachmentResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/attachments/get/{uuid} [get]
+func (h *FileManagerAttachmentHandler) GetAttachment(c *fiber.Ctx) error {
+	id, err := h.parseUUIDParam(c, "uuid", "/path/uuid")
+	if err != nil {
+		return err
+	}
+
+	row, err := h.svc.GetAttachmentByID(c.Context(), id)
+	if err != nil {
+		return writeFileManagerActionError(c, "Get failed", err)
+	}
+	if row == nil {
+		return writeFileManagerError(c, fiber.StatusNotFound, "Not found", "attachment not found", nil)
+	}
+
+	return response.Write(c, fiber.StatusOK, fileManagerAttachmentResource(row))
+}
+
+// ListAttachments godoc
+// @Summary List attachments by business reference
+// @ID FileManagerListAttachmentsByReference
+// @Description List generic attachment relations by ref_type and ref_id.
+// @Tags File Manager
+// @Produce json
+// @Param ref_type query string true "Business reference type, e.g. helicopter"
+// @Param ref_id query string true "Business reference ID"
+// @Param category query string false "Optional attachment category"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort values: sort_order,-sort_order,created_at,-created_at,updated_at,-updated_at"
+// @Success 200 {object} responsedto.FileManagerAttachmentListResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/attachments/get-all [get]
+func (h *FileManagerAttachmentHandler) ListAttachments(c *fiber.Ctx) error {
+	refType := strings.TrimSpace(c.Query("ref_type"))
+	refID := strings.TrimSpace(c.Query("ref_id"))
+	if refType == "" || refID == "" {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "ref_type and ref_id are required", &jsonapi.ErrorSource{Pointer: "/query/ref_type"})
+	}
+
+	var category *string
+	rawCategory := strings.TrimSpace(c.Query("category"))
+	if rawCategory != "" {
+		category = &rawCategory
+	}
+
+	_, _, _ = parseFileManagerAttachmentPagination(c)
+	rows, total, err := h.svc.ListAttachmentsByReference(c.Context(), filemanager.ListAttachmentsParams{
+		RefType:  refType,
+		RefID:    refID,
+		Category: category,
+		Sort:     c.Query("sort"),
+		Limit:    0,
+		Offset:   0,
+	})
+	if err != nil {
+		return writeFileManagerActionError(c, "List failed", err)
+	}
+
+	data := make([]responsedto.FileManagerAttachmentResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, fileManagerAttachmentResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"total": total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// DeleteAttachment godoc
+// @Summary Detach attachment relation
+// @ID FileManagerDeleteAttachment
+// @Description Remove generic attachment relation by UUID.
+// @Tags File Manager
+// @Produce json
+// @Param uuid path string true "Attachment UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/attachments/delete/{uuid} [delete]
+func (h *FileManagerAttachmentHandler) DeleteAttachment(c *fiber.Ctx) error {
+	id, err := h.parseUUIDParam(c, "uuid", "/path/uuid")
+	if err != nil {
+		return err
+	}
+
+	if err := h.svc.DeleteAttachment(c.Context(), id); err != nil {
+		return writeFileManagerActionError(c, "Detach failed", err)
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "file_manager_attachment_delete",
+		Attributes: map[string]any{
+			"detached": true,
+		},
+	})
+}
+
+func (h *FileManagerAttachmentHandler) parseUUIDParam(c *fiber.Ctx, paramName, sourcePointer string) ([]byte, error) {
+	uuidStr := strings.TrimSpace(c.Params(paramName))
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return nil, writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", fmt.Sprintf("%s is invalid UUID", paramName), &jsonapi.ErrorSource{Pointer: sourcePointer})
+	}
+	return id, nil
+}
+
+func parseFileManagerAttachmentPagination(c *fiber.Ctx) (pageNumber int, pageSize int, offset int) {
+	pageNumber = parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	pageSize = parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	offset = (pageNumber - 1) * pageSize
+	return
+}
+
+func fileManagerAttachmentResource(row *filemanager.Attachment) responsedto.FileManagerAttachmentResource {
+	if row == nil {
+		return responsedto.FileManagerAttachmentResource{
+			Type: "file_manager_attachment",
+		}
+	}
+
+	category := ""
+	if row.Category != nil {
+		category = strings.TrimSpace(*row.Category)
+	}
+
+	attributes := shareddto.FileManagerAttachmentAttributes{
+		FileID:     idString(row.FileID),
+		RefType:    strings.TrimSpace(row.RefType),
+		RefID:      strings.TrimSpace(row.RefID),
+		Category:   category,
+		SortOrder:  row.SortOrder,
+		IsPrimary:  row.IsPrimary,
+		AttachedBy: uuidStringOrEmpty(row.AttachedBy),
+		CreatedAt:  timeStringOrEmpty(&row.CreatedAt),
+		UpdatedAt:  timeStringOrEmpty(&row.UpdatedAt),
+	}
+
+	return responsedto.FileManagerAttachmentResource{
+		Type:       "file_manager_attachment",
+		ID:         idString(row.ID),
+		Attributes: attributes,
+	}
+}
diff --git a/internal/transport/http/handlers/file_manager_error_mapper.go b/internal/transport/http/handlers/file_manager_error_mapper.go
new file mode 100644
index 0000000..3c5e33d
--- /dev/null
+++ b/internal/transport/http/handlers/file_manager_error_mapper.go
@@ -0,0 +1,183 @@
+package handlers
+
+import (
+	"errors"
+	"strconv"
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/transport/http/jsonapi"
+)
+
+func writeMissionFileError(c *fiber.Ctx, def apperrorsx.Def, detail string, source *jsonapi.ErrorSource) error {
+	msg := strings.TrimSpace(detail)
+	if msg == "" {
+		msg = def.Message
+	}
+	c.Locals(apperrorsx.ContextKeyHTTPErrorDetail, msg)
+	return jsonapi.WriteErrors(c, def.Status, []jsonapi.ErrorObject{{
+		Status:    strconv.Itoa(def.Status),
+		Code:      def.Code,
+		ErrorCode: def.ErrorCode,
+		Title:     def.Title,
+		Detail:    msg,
+		Source:    source,
+	}})
+}
+
+func writeFileManagerActionError(c *fiber.Ctx, action string, err error) error {
+	def := mapFileManagerActionDef(action, err)
+	logHandlerError(c, action, def.Status, def.Code, def.ErrorCode, err)
+
+	appErr := apperrorsx.New(def)
+	if err != nil {
+		appErr.Cause = err
+	}
+	return apperrorsx.Write(c, appErr)
+}
+
+func writeFileManagerError(c *fiber.Ctx, statusCode int, title, detail string, source *jsonapi.ErrorSource) error {
+	def := inferFileManagerDef(statusCode, title, detail)
+	appErr := apperrorsx.New(def)
+	appErr.Status = statusCode
+	appErr.Source = source
+	return apperrorsx.Write(c, appErr)
+}
+
+func inferFileManagerCode(statusCode int, title, detail string) (string, string) {
+	def := inferFileManagerDef(statusCode, title, detail)
+	return def.Code, def.ErrorCode
+}
+
+func inferFileManagerDef(statusCode int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch statusCode {
+	case fiber.StatusServiceUnavailable:
+		switch {
+		case strings.Contains(lowerTitle, "storage"):
+			return apperrorsx.ErrFileManagerStorageUnavailable
+		case strings.Contains(lowerTitle, "queue"):
+			return apperrorsx.ErrFileManagerQueueUnavailable
+		case strings.Contains(lowerTitle, "upload intent"):
+			return apperrorsx.ErrFileManagerUploadIntentUnavailable
+		case strings.Contains(lowerTitle, "attachment"):
+			return apperrorsx.ErrFileManagerAttachmentServiceUnavailable
+		default:
+			return apperrorsx.ErrFileManagerActionFailed
+		}
+	case fiber.StatusNotFound:
+		switch {
+		case strings.Contains(lowerDetail, "folder"):
+			return apperrorsx.ErrFileManagerFolderNotFound
+		case strings.Contains(lowerDetail, "attachment"):
+			return apperrorsx.ErrFileManagerAttachmentNotFound
+		case strings.Contains(lowerDetail, "upload intent"):
+			return apperrorsx.ErrFileManagerUploadIntentNotFound
+		default:
+			return apperrorsx.ErrFileManagerFileNotFound
+		}
+	case fiber.StatusConflict:
+		if strings.Contains(lowerTitle, "upload intent") || strings.Contains(lowerDetail, "upload intent") {
+			return apperrorsx.ErrFileManagerUploadIntentConflict
+		}
+		return apperrorsx.ErrFileManagerStatusConflict
+	case fiber.StatusUnprocessableEntity:
+		return apperrorsx.ErrFileManagerValidationFailed
+	case fiber.StatusUnauthorized:
+		return apperrorsx.ErrUserUnauthorized
+	case fiber.StatusBadRequest:
+		if strings.Contains(lowerTitle, "invalid json") {
+			return apperrorsx.ErrInvalidRequest
+		}
+		return apperrorsx.ErrFileManagerActionFailed
+	default:
+		return apperrorsx.ErrFileManagerActionFailed
+	}
+}
+
+func mapFileManagerActionDef(action string, err error) apperrorsx.Def {
+	statusCode := fiber.StatusBadRequest
+	title := action
+	def := apperrorsx.ErrFileManagerActionFailed
+
+	switch {
+	case errors.Is(err, filemanager.ErrStorageUnavailable):
+		statusCode = fiber.StatusServiceUnavailable
+		title = "Storage unavailable"
+		def = apperrorsx.ErrFileManagerStorageUnavailable
+	case errors.Is(err, filemanager.ErrFileProcessingQueueDisabled):
+		statusCode = fiber.StatusServiceUnavailable
+		title = "Queue unavailable"
+		def = apperrorsx.ErrFileManagerQueueUnavailable
+	case errors.Is(err, filemanager.ErrUploadIntentRepositoryDisabled):
+		statusCode = fiber.StatusServiceUnavailable
+		title = "Upload intent unavailable"
+		def = apperrorsx.ErrFileManagerUploadIntentUnavailable
+	case errors.Is(err, filemanager.ErrFolderNotFound), errors.Is(err, filemanager.ErrFileNotFound):
+		statusCode = fiber.StatusNotFound
+		title = "Not found"
+		if errors.Is(err, filemanager.ErrFolderNotFound) {
+			def = apperrorsx.ErrFileManagerFolderNotFound
+		} else {
+			def = apperrorsx.ErrFileManagerFileNotFound
+		}
+	case errors.Is(err, filemanager.ErrAttachmentNotFound):
+		statusCode = fiber.StatusNotFound
+		title = "Attachment not found"
+		def = apperrorsx.ErrFileManagerAttachmentNotFound
+	case errors.Is(err, filemanager.ErrUploadIntentNotFound):
+		statusCode = fiber.StatusNotFound
+		title = "Upload intent not found"
+		def = apperrorsx.ErrFileManagerUploadIntentNotFound
+	case errors.Is(err, filemanager.ErrFileStatusConflict):
+		statusCode = fiber.StatusConflict
+		title = "Conflict"
+		def = apperrorsx.ErrFileManagerStatusConflict
+	case errors.Is(err, filemanager.ErrUploadIntentExpired),
+		errors.Is(err, filemanager.ErrUploadIntentAlreadyComplete),
+		errors.Is(err, filemanager.ErrUploadIntentStatusConflict):
+		statusCode = fiber.StatusConflict
+		title = "Upload intent conflict"
+		def = apperrorsx.ErrFileManagerUploadIntentConflict
+	case errors.Is(err, filemanager.ErrDuplicateName),
+		errors.Is(err, filemanager.ErrInvalidMove),
+		errors.Is(err, filemanager.ErrFolderNotEmpty),
+		errors.Is(err, filemanager.ErrFolderNotInTrash),
+		errors.Is(err, filemanager.ErrFileNotInTrash),
+		errors.Is(err, filemanager.ErrAttachmentAlreadyExists),
+		errors.Is(err, filemanager.ErrAttachmentRefRequired),
+		errors.Is(err, filemanager.ErrFileNotReadyForAttachment),
+		errors.Is(err, filemanager.ErrFileAlreadyFinalized),
+		errors.Is(err, filemanager.ErrFileNotEligibleForFinalize),
+		errors.Is(err, filemanager.ErrInvalidFileStatusTransition),
+		errors.Is(err, filemanager.ErrFileTooLarge),
+		errors.Is(err, filemanager.ErrFileMimeTypeNotAllowed),
+		errors.Is(err, filemanager.ErrFileExtensionNotAllowed),
+		errors.Is(err, filemanager.ErrEmptyFileNotAllowed),
+		errors.Is(err, filemanager.ErrFileNameTooLong),
+		errors.Is(err, filemanager.ErrUploadObjectNotFound),
+		errors.Is(err, filemanager.ErrUploadObjectMismatch),
+		errors.Is(err, filemanager.ErrInvalidName),
+		errors.Is(err, filemanager.ErrReservedName):
+		statusCode = fiber.StatusUnprocessableEntity
+		title = "Validation error"
+		def = apperrorsx.ErrFileManagerValidationFailed
+	case errors.Is(err, filemanager.ErrAttachmentRepositoryDisabled):
+		statusCode = fiber.StatusServiceUnavailable
+		title = "Attachment service unavailable"
+		def = apperrorsx.ErrFileManagerAttachmentServiceUnavailable
+	}
+
+	def.Status = statusCode
+	def.Title = title
+	return def
+}
+
+func mapFileManagerActionError(action string, err error) (int, string, string, string, string) {
+	def := mapFileManagerActionDef(action, err)
+	return def.Status, def.Title, def.Message, def.Code, def.ErrorCode
+}
diff --git a/internal/transport/http/handlers/file_manager_events_handler.go b/internal/transport/http/handlers/file_manager_events_handler.go
new file mode 100644
index 0000000..9b87be6
--- /dev/null
+++ b/internal/transport/http/handlers/file_manager_events_handler.go
@@ -0,0 +1,203 @@
+package handlers
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanagerrealtime "wucher/internal/realtime/filemanager"
+	"wucher/internal/shared/pkg/uuidv7"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+)
+
+const (
+	fileManagerSSEEventName = "file.updated"
+)
+
+type FileManagerEventsHandler struct {
+	hub *filemanagerrealtime.Hub
+}
+
+type fileManagerSSEFilter struct {
+	folderID *string
+	fileIDs  map[string]struct{}
+}
+
+func NewFileManagerEventsHandler(hub *filemanagerrealtime.Hub) *FileManagerEventsHandler {
+	return &FileManagerEventsHandler{hub: hub}
+}
+
+func (h *FileManagerEventsHandler) Stream(c *fiber.Ctx) error {
+	if h.hub == nil {
+		return writeFileManagerError(c, fiber.StatusServiceUnavailable, "Service unavailable", "file events stream is not configured", nil)
+	}
+
+	actorID := actorUserID(c)
+	if len(actorID) != 16 {
+		return writeFileManagerError(c, fiber.StatusUnauthorized, "Unauthorized", "invalid user context", nil)
+	}
+	userUUID, err := uuidv7.BytesToString(actorID)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusUnauthorized, "Unauthorized", "invalid user context", nil)
+	}
+
+	filter, err := parseFileManagerSSEFilter(c)
+	if err != nil {
+		return err
+	}
+
+	sub, err := h.hub.SubscribeWithFilter(userUUID, filter.match)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusServiceUnavailable, "Service unavailable", "cannot subscribe to file events stream", nil)
+	}
+
+	c.Set(fiber.HeaderContentType, "text/event-stream")
+	c.Set(fiber.HeaderCacheControl, "no-cache, no-transform")
+	c.Set(fiber.HeaderConnection, "keep-alive")
+	c.Set("X-Accel-Buffering", "no")
+
+	c.Context().SetBodyStreamWriter(func(w *bufio.Writer) {
+		defer sub.Close()
+
+		if !writeSSEComment(w, "connected") {
+			return
+		}
+
+		heartbeat := time.NewTicker(20 * time.Second)
+		defer heartbeat.Stop()
+
+		for {
+			select {
+			case <-sub.Done():
+				return
+			case <-heartbeat.C:
+				if !writeSSEComment(w, "ping") {
+					return
+				}
+			case event, ok := <-sub.Events():
+				if !ok {
+					return
+				}
+				if !filter.match(event) {
+					continue
+				}
+				payload := mapFileStatusEventToSSEPayload(event)
+				if !writeSSEDataEvent(w, fileManagerSSEEventName, payload) {
+					return
+				}
+			}
+		}
+	})
+
+	return nil
+}
+
+func parseFileManagerSSEFilter(c *fiber.Ctx) (fileManagerSSEFilter, error) {
+	filter := fileManagerSSEFilter{
+		fileIDs: make(map[string]struct{}),
+	}
+
+	if rawFolderID := strings.TrimSpace(c.Query("folder_id")); rawFolderID != "" {
+		parsed, err := uuidv7.ParseString(rawFolderID)
+		if err != nil {
+			return fileManagerSSEFilter{}, writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "folder_id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/query/folder_id"})
+		}
+		canonical, err := uuidv7.BytesToString(parsed)
+		if err != nil {
+			return fileManagerSSEFilter{}, writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "folder_id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/query/folder_id"})
+		}
+		canonical = strings.ToLower(strings.TrimSpace(canonical))
+		filter.folderID = &canonical
+	}
+
+	rawTokens := make([]string, 0, 8)
+	if rawFileID := strings.TrimSpace(c.Query("file_id")); rawFileID != "" {
+		rawTokens = append(rawTokens, rawFileID)
+	}
+	if rawFileIDs := strings.TrimSpace(c.Query("file_ids")); rawFileIDs != "" {
+		for _, token := range strings.Split(rawFileIDs, ",") {
+			token = strings.TrimSpace(token)
+			if token != "" {
+				rawTokens = append(rawTokens, token)
+			}
+		}
+	}
+	for i := range rawTokens {
+		parsed, err := uuidv7.ParseString(rawTokens[i])
+		if err != nil {
+			return fileManagerSSEFilter{}, writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "file_id/file_ids contains invalid UUID", &jsonapi.ErrorSource{Pointer: "/query/file_ids"})
+		}
+		canonical, err := uuidv7.BytesToString(parsed)
+		if err != nil {
+			return fileManagerSSEFilter{}, writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "file_id/file_ids contains invalid UUID", &jsonapi.ErrorSource{Pointer: "/query/file_ids"})
+		}
+		filter.fileIDs[strings.ToLower(strings.TrimSpace(canonical))] = struct{}{}
+	}
+
+	return filter, nil
+}
+
+func (f fileManagerSSEFilter) match(event filemanagerrealtime.FileStatusEvent) bool {
+	fileUUID := strings.ToLower(strings.TrimSpace(event.FileUUID))
+	if fileUUID == "" {
+		return false
+	}
+	if len(f.fileIDs) > 0 {
+		if _, ok := f.fileIDs[fileUUID]; !ok {
+			return false
+		}
+	}
+	if f.folderID != nil {
+		if event.FolderUUID == nil {
+			return false
+		}
+		eventFolderID := strings.ToLower(strings.TrimSpace(*event.FolderUUID))
+		if eventFolderID == "" || !strings.EqualFold(eventFolderID, *f.folderID) {
+			return false
+		}
+	}
+	return true
+}
+
+func mapFileStatusEventToSSEPayload(event filemanagerrealtime.FileStatusEvent) responsedto.FileManagerFileUpdatedSSEPayload {
+	payload := responsedto.FileManagerFileUpdatedSSEPayload{
+		FileID:    strings.TrimSpace(event.FileUUID),
+		Status:    strings.TrimSpace(event.Status),
+		Name:      strings.TrimSpace(event.Name),
+		MimeType:  strings.TrimSpace(event.MimeType),
+		UpdatedAt: strings.TrimSpace(event.UpdatedAt),
+	}
+	if event.FolderUUID != nil {
+		folderID := strings.TrimSpace(*event.FolderUUID)
+		if folderID != "" {
+			payload.FolderID = &folderID
+		}
+	}
+	return payload
+}
+
+func writeSSEComment(w *bufio.Writer, comment string) bool {
+	if _, err := fmt.Fprintf(w, ": %s\n\n", strings.TrimSpace(comment)); err != nil {
+		return false
+	}
+	return w.Flush() == nil
+}
+
+func writeSSEDataEvent(w *bufio.Writer, eventName string, payload any) bool {
+	raw, err := json.Marshal(payload)
+	if err != nil {
+		return false
+	}
+	if _, err := fmt.Fprintf(w, "event: %s\n", strings.TrimSpace(eventName)); err != nil {
+		return false
+	}
+	if _, err := fmt.Fprintf(w, "data: %s\n\n", string(raw)); err != nil {
+		return false
+	}
+	return w.Flush() == nil
+}
diff --git a/internal/transport/http/handlers/file_manager_file_handler.go b/internal/transport/http/handlers/file_manager_file_handler.go
new file mode 100644
index 0000000..3ea30c7
--- /dev/null
+++ b/internal/transport/http/handlers/file_manager_file_handler.go
@@ -0,0 +1,2430 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	authdomain "wucher/internal/domain/auth"
+	"wucher/internal/domain/base"
+	"wucher/internal/domain/dul"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/helicopter"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	missiondomain "wucher/internal/domain/mission"
+	takeoverdomain "wucher/internal/domain/takeover"
+	"wucher/internal/domain/user"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/appctx"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	dto "wucher/internal/transport/http/dto"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type FileManagerFileHandler struct {
+	svc                  filemanager.Service
+	wopi                 *service.WOPIService
+	heliFile             helicopterfile.Service
+	aircraft             helicopter.Service
+	base                 base.Service
+	dul                  dul.Service
+	takeover             takeoverFileService
+	mission              missionFileService
+	user                 user.Service
+	fleetStatusFile      *service.FleetStatusFileService
+	helicopterFileEvents helicopterFileEventPublisher
+	auth                 fileManagerAuthService
+	validate             *validators.Validator
+	storage              filemanager.ObjectStorage
+}
+
+type fileManagerAuthService interface {
+	GetUserByID(context.Context, []byte) (*authdomain.User, error)
+}
+
+type takeoverFileService interface {
+	GetByID(context.Context, []byte) (*takeoverdomain.TakeoverAc, error)
+	List(context.Context, int, int) ([]takeoverdomain.TakeoverAc, int64, error)
+	AttachFile(context.Context, []byte, []byte) error
+}
+
+type missionFileService interface {
+	GetByID(context.Context, []byte) (*missiondomain.Mission, error)
+	AttachFile(context.Context, []byte, []byte) error
+}
+
+const aircraftImageFolderName = "aircraft"
+const baseImageFolderName = "bases"
+const dulImageFolderName = "duls"
+const takeoverFileFolderName = "takeovers"
+const missionFileFolderName = "missions"
+const userImageFolderName = "user"
+
+var (
+	_ = dto.ErrorResponse{}
+	_ = dto.GenericDeleteResponse{}
+)
+
+func NewFileManagerFileHandler(svc filemanager.Service, storage filemanager.ObjectStorage) *FileManagerFileHandler {
+	return &FileManagerFileHandler{
+		svc:      svc,
+		validate: validators.New(),
+		storage:  storage,
+	}
+}
+
+func (h *FileManagerFileHandler) WithWOPIService(wopiSvc *service.WOPIService) *FileManagerFileHandler {
+	h.wopi = wopiSvc
+	return h
+}
+
+func (h *FileManagerFileHandler) WithHelicopterFileService(heliFileSvc helicopterfile.Service) *FileManagerFileHandler {
+	h.heliFile = heliFileSvc
+	return h
+}
+
+func (h *FileManagerFileHandler) WithAircraftService(aircraftSvc helicopter.Service) *FileManagerFileHandler {
+	h.aircraft = aircraftSvc
+	return h
+}
+
+func (h *FileManagerFileHandler) WithBaseService(baseSvc base.Service) *FileManagerFileHandler {
+	h.base = baseSvc
+	return h
+}
+
+func (h *FileManagerFileHandler) WithDULService(dulSvc dul.Service) *FileManagerFileHandler {
+	h.dul = dulSvc
+	return h
+}
+
+func (h *FileManagerFileHandler) WithTakeoverService(takeoverSvc takeoverFileService) *FileManagerFileHandler {
+	h.takeover = takeoverSvc
+	return h
+}
+
+func (h *FileManagerFileHandler) WithMissionService(missionSvc missionFileService) *FileManagerFileHandler {
+	h.mission = missionSvc
+	return h
+}
+
+func (h *FileManagerFileHandler) WithAuthService(authSvc fileManagerAuthService) *FileManagerFileHandler {
+	h.auth = authSvc
+	return h
+}
+
+func (h *FileManagerFileHandler) takeoverUserHasGlobalAccess(ctx context.Context) bool {
+	return h.takeoverUserHasGlobalAccessForUserID(ctx, appctx.GetUserID(ctx))
+}
+
+func (h *FileManagerFileHandler) takeoverUserHasGlobalAccessForUserID(ctx context.Context, userID []byte) bool {
+	if h == nil || h.auth == nil {
+		return false
+	}
+	if len(userID) != 16 {
+		return false
+	}
+	user, err := h.auth.GetUserByID(ctx, userID)
+	if err != nil || user == nil {
+		return false
+	}
+	for i := range user.Roles {
+		if strings.EqualFold(strings.TrimSpace(user.Roles[i].Name), "admin") {
+			return true
+		}
+	}
+	return false
+}
+
+func (h *FileManagerFileHandler) WithUserService(userSvc user.Service) *FileManagerFileHandler {
+	h.user = userSvc
+	return h
+}
+
+func (h *FileManagerFileHandler) WithFleetStatusFileService(svc *service.FleetStatusFileService) *FileManagerFileHandler {
+	h.fleetStatusFile = svc
+	return h
+}
+
+func (h *FileManagerFileHandler) WithHelicopterFileEvents(publisher helicopterFileEventPublisher) *FileManagerFileHandler {
+	h.helicopterFileEvents = publisher
+	return h
+}
+
+// CreateFile godoc
+// @Summary Create file record from uploaded object
+// @ID FileManagerCreateFileFromUploadedObject
+// @Description Final public control-plane step after direct PUT upload to S3 (bulk contract).
+// @Description Verifies uploaded object per item from upload intent, then persists metadata+outbox durably and emits lifecycle status.
+// @Description This endpoint does not upload binary data.
+// @Description Public flow: POST /files/upload (intent+presign) -> PUT to S3 -> POST /files/create.
+// @Description folder_id is optional; null/omitted means create in root folder.
+// @Description Canonical JSON:API data.type is "file_manager_file_create" (legacy "file_manager_file" remains accepted for backward compatibility).
+// @Description Bulk payload accepts one or many items.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileUserBulkCreateRequest true "Bulk create payload for user profile image"
+// @Success 200 {object} responsedto.FileManagerFileBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/create [post]
+func (h *FileManagerFileHandler) CreateFile(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if !isBulk {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must be an array", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+	return h.createFilesBulk(c)
+}
+
+// UploadFile godoc
+// @Summary Request upload intents + presigned PUT URLs
+// @ID FileManagerRequestUploadIntent
+// @Description Control-plane endpoint to create upload intents and presigned PUT URLs for direct upload to S3 (bulk contract).
+// @Description Binary does not flow through backend upload endpoint.
+// @Description After successful PUT to S3, call POST /api/v1/file-manager/files/create with upload_intent_uuid.
+// @Description Presigned URL TTL is controlled by backend storage config.
+// @Description Bulk payload accepts one or many items. Response is item-based and supports partial success.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileUploadIntentBulkRequest true "Bulk upload intent request"
+// @Success 200 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/upload [post]
+func (h *FileManagerFileHandler) UploadFile(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if !isBulk {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must be an array", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	var req requestdto.FileManagerFileUploadIntentBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	actorID := actorUserID(c)
+	items := make([]responsedto.FileManagerFileUploadIntentBulkItem, len(req.Data))
+
+	for i := range req.Data {
+		item := req.Data[i]
+		typ := strings.TrimSpace(item.Type)
+		if typ != "file_manager_file_upload_intent" {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "type must be file_manager_file_upload_intent")
+			continue
+		}
+
+		name := strings.TrimSpace(item.Attributes.Name)
+		if name == "" {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "name is required")
+			continue
+		}
+
+		contentType := strings.TrimSpace(item.Attributes.ContentType)
+		if contentType == "" {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "content_type is required")
+			continue
+		}
+
+		if item.Attributes.SizeBytes < 0 {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "size_bytes must be greater than or equal to 0")
+			continue
+		}
+
+		grant, grantErr := h.svc.RequestFileUploadIntent(c.Context(), filemanager.RequestFileUploadIntentParams{
+			Name:        name,
+			ContentType: contentType,
+			SizeBytes:   item.Attributes.SizeBytes,
+			ActorID:     actorID,
+		})
+		if grantErr != nil {
+			items[i] = fileManagerUploadIntentBulkActionErrorItem(i, "Upload intent failed", grantErr)
+			continue
+		}
+
+		resource := fileManagerFileUploadIntentResource(grant)
+		items[i] = responsedto.FileManagerFileUploadIntentBulkItem{
+			Index:    i,
+			Success:  true,
+			Resource: &resource,
+		}
+	}
+
+	return writeFileManagerUploadIntentBulkResponse(c, items)
+}
+
+// UploadTakeoverFile godoc
+// @Summary Request upload intents for takeover files
+// @Description Dedicated upload-intent endpoint for takeover file flow.
+// @Description Use together with /api/v1/file-manager/files/create-takeover-file to persist the takeover file relation.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileUploadIntentBulkRequest true "Bulk upload intent request"
+// @Success 200 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/upload-takeover-file [post]
+func (h *FileManagerFileHandler) UploadTakeoverFile(c *fiber.Ctx) error {
+	return h.UploadFile(c)
+}
+
+// UploadMissionFile godoc
+// @Summary Request upload intents for mission files
+// @ID FileManagerRequestMissionFileUploadIntent
+// @Description Dedicated upload-intent endpoint for mission file flow.
+// @Description Use together with /api/v1/file-manager/files/create-mission-file to attach the file to a mission.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileUploadIntentBulkRequest true "Bulk upload intent request"
+// @Success 200 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/upload-mission-file [post]
+func (h *FileManagerFileHandler) UploadMissionFile(c *fiber.Ctx) error {
+	return h.UploadFile(c)
+}
+
+// CreateMissionFile godoc
+// @Summary Create mission file record from uploaded object
+// @ID FileManagerCreateMissionFileFromUploadedObject
+// @Description Materializes uploaded objects into folder "missions/<mission-uuid>", creates attachments (ref_type=mission), and links them to the mission so they appear in GET mission.
+// @Description mission_uuid is required per item.
+// @Description Possible error code: MISSION_FILE_INVALID_JSON, MISSION_FILE_VALIDATION, MISSION_FILE_INVALID_MISSION_UUID, MISSION_FILE_MISSION_NOT_FOUND, MISSION_FILE_SERVICE_UNAVAILABLE, MISSION_FILE_ACTION_FAILED, FILE_MANAGER_UPLOAD_INTENT_NOT_FOUND, FILE_MANAGER_STORAGE_UNAVAILABLE, FILE_MANAGER_ACTION_FAILED.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileMissionBulkCreateRequest true "Bulk create payload for mission file"
+// @Success 200 {object} responsedto.FileManagerFileBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/create-mission-file [post]
+func (h *FileManagerFileHandler) CreateMissionFile(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeMissionFileError(c, apperrorsx.ErrMissionFileInvalidJSON, "mission file request body is not valid JSON", nil)
+	}
+	if !isBulk {
+		return writeMissionFileError(c, apperrorsx.ErrMissionFileValidation, "data must be an array", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	var req requestdto.FileManagerFileMissionBulkCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMissionFileError(c, apperrorsx.ErrMissionFileInvalidJSON, "mission file request body is not valid JSON", nil)
+	}
+	if len(req.Data) == 0 {
+		return writeMissionFileError(c, apperrorsx.ErrMissionFileValidation, "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	actorID := actorUserID(c)
+	if h.mission == nil {
+		return writeMissionFileError(c, apperrorsx.ErrMissionFileServiceUnavailable, "mission service is not configured", nil)
+	}
+
+	items := make([]responsedto.FileManagerFileBulkItem, len(req.Data))
+	validParams := make([]filemanager.CreateFileFromUploadIntentParams, 0, len(req.Data))
+	validIndexes := make([]int, 0, len(req.Data))
+
+	for i := range req.Data {
+		item := req.Data[i]
+		typ := strings.TrimSpace(item.Type)
+		if typ != "file_manager_file_create" && typ != "file_manager_file" {
+			items[i] = missionFileBulkErrorItem(i, apperrorsx.ErrMissionFileValidation, "type must be file_manager_file_create or file_manager_file")
+			continue
+		}
+
+		uploadIntentUUID := strings.TrimSpace(item.Attributes.UploadIntentUUID)
+		uploadIntentID, parseUploadErr := uuidv7.ParseString(uploadIntentUUID)
+		if parseUploadErr != nil {
+			items[i] = missionFileBulkErrorItem(i, apperrorsx.ErrMissionFileValidation, "upload_intent_uuid is invalid UUID")
+			continue
+		}
+
+		name := strings.TrimSpace(item.Attributes.Name)
+		if name == "" {
+			items[i] = missionFileBulkErrorItem(i, apperrorsx.ErrMissionFileValidation, "name is required")
+			continue
+		}
+
+		missionUUID := strings.TrimSpace(item.Attributes.MissionUUID)
+		missionID, parseMissionErr := uuidv7.ParseString(missionUUID)
+		if parseMissionErr != nil {
+			items[i] = missionFileBulkErrorItem(i, apperrorsx.ErrMissionFileInvalidMissionUUID, "mission_uuid is invalid UUID")
+			continue
+		}
+
+		missionRow, missionErr := h.mission.GetByID(c.UserContext(), missionID)
+		if missionErr != nil {
+			items[i] = missionFileBulkErrorItem(i, apperrorsx.ErrMissionFileActionFailed, "failed to load mission")
+			continue
+		}
+		if missionRow == nil {
+			items[i] = missionFileBulkErrorItem(i, apperrorsx.ErrMissionFileMissionNotFound, "mission not found")
+			continue
+		}
+
+		folderID, folderErr := h.ensureMissionFileFolder(c.UserContext(), actorID, missionID)
+		if folderErr != nil {
+			items[i] = fileManagerBulkActionErrorItem(i, "Create failed", folderErr)
+			continue
+		}
+
+		validParams = append(validParams, filemanager.CreateFileFromUploadIntentParams{
+			UploadIntentID: uploadIntentID,
+			FolderID:       folderID,
+			FolderProvided: true,
+			Name:           name,
+			ActorID:        actorID,
+		})
+		validIndexes = append(validIndexes, i)
+	}
+
+	for i := range validParams {
+		idx := validIndexes[i]
+		created, createErr := h.svc.CreateFileNodeFromUploadIntent(c.UserContext(), validParams[i])
+		if createErr != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Create failed", createErr)
+			continue
+		}
+		missionUUID := strings.TrimSpace(req.Data[idx].Attributes.MissionUUID)
+		missionID, parseMissionErr := uuidv7.ParseString(missionUUID)
+		if parseMissionErr != nil {
+			items[idx] = missionFileBulkErrorItem(idx, apperrorsx.ErrMissionFileInvalidMissionUUID, "mission_uuid is invalid UUID")
+			continue
+		}
+		attachment, attachErr := h.svc.CreateAttachment(c.UserContext(), filemanager.CreateAttachmentParams{
+			FileID:    created.ID,
+			RefType:   "mission",
+			RefID:     missionUUID,
+			SortOrder: 0,
+			IsPrimary: false,
+			ActorID:   actorID,
+		})
+		if attachErr != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Create failed", attachErr)
+			continue
+		}
+		if err := h.mission.AttachFile(c.UserContext(), missionID, attachment.ID); err != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Create failed", err)
+			continue
+		}
+		items[idx] = fileManagerBulkSuccessItem(idx, "created", created)
+	}
+
+	return writeFileManagerBulkResponse(c, items)
+}
+
+func (h *FileManagerFileHandler) ensureMissionFileFolder(ctx context.Context, actorID []byte, missionID []byte) ([]byte, error) {
+	return ensureMissionFileFolderPath(ctx, h.svc, missionID, actorID)
+}
+
+// UploadAircraftImage godoc
+// @Summary Request upload intents for aircraft drag-drop images
+// @ID FileManagerRequestAircraftImageUploadIntent
+// @Description Same flow as file upload intent, but dedicated for aircraft image drag-drop flow.
+// @Description Use together with /api/v1/file-manager/files/create-aircraft-image to force target folder "aircraft".
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileUploadIntentBulkRequest true "Bulk upload intent request"
+// @Success 200 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/upload-aircraft-image [post]
+func (h *FileManagerFileHandler) UploadAircraftImage(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if !isBulk {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must be an array", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	var req requestdto.FileManagerFileUploadIntentBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	actorID := actorUserID(c)
+	items := make([]responsedto.FileManagerFileUploadIntentBulkItem, len(req.Data))
+	for i := range req.Data {
+		item := req.Data[i]
+		typ := strings.TrimSpace(item.Type)
+		if typ != "file_manager_file_upload_intent" {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "type must be file_manager_file_upload_intent")
+			continue
+		}
+
+		name := strings.TrimSpace(item.Attributes.Name)
+		if name == "" {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "name is required")
+			continue
+		}
+
+		contentType := strings.TrimSpace(item.Attributes.ContentType)
+		if contentType == "" {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "content_type is required")
+			continue
+		}
+		if !strings.HasPrefix(strings.ToLower(contentType), "image/") {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "content_type must be image/* for aircraft image upload")
+			continue
+		}
+
+		if item.Attributes.SizeBytes < 0 {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "size_bytes must be greater than or equal to 0")
+			continue
+		}
+
+		grant, grantErr := h.svc.RequestFileUploadIntent(c.Context(), filemanager.RequestFileUploadIntentParams{
+			Name:        name,
+			ContentType: contentType,
+			SizeBytes:   item.Attributes.SizeBytes,
+			ActorID:     actorID,
+		})
+		if grantErr != nil {
+			items[i] = fileManagerUploadIntentBulkActionErrorItem(i, "Upload intent failed", grantErr)
+			continue
+		}
+
+		resource := fileManagerFileUploadIntentResource(grant)
+		items[i] = responsedto.FileManagerFileUploadIntentBulkItem{
+			Index:    i,
+			Success:  true,
+			Resource: &resource,
+		}
+	}
+
+	return writeFileManagerUploadIntentBulkResponse(c, items)
+}
+
+// UploadBaseImage godoc
+// @Summary Request upload intents for base images
+// @ID FileManagerRequestBaseImageUploadIntent
+// @Description Same flow as file upload intent, but dedicated for base image flow.
+// @Description Use together with /api/v1/file-manager/files/create-base-image to force target folder under bases hierarchy.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileUploadIntentBulkRequest true "Bulk upload intent request"
+// @Success 200 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/upload-base-image [post]
+func (h *FileManagerFileHandler) UploadBaseImage(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if !isBulk {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must be an array", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	var req requestdto.FileManagerFileUploadIntentBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	actorID := actorUserID(c)
+	items := make([]responsedto.FileManagerFileUploadIntentBulkItem, len(req.Data))
+	for i := range req.Data {
+		item := req.Data[i]
+		typ := strings.TrimSpace(item.Type)
+		if typ != "file_manager_file_upload_intent" {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "type must be file_manager_file_upload_intent")
+			continue
+		}
+
+		name := strings.TrimSpace(item.Attributes.Name)
+		if name == "" {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "name is required")
+			continue
+		}
+
+		contentType := strings.TrimSpace(item.Attributes.ContentType)
+		if contentType == "" {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "content_type is required")
+			continue
+		}
+		if !strings.HasPrefix(strings.ToLower(contentType), "image/") {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "content_type must be image/* for base image upload")
+			continue
+		}
+
+		if item.Attributes.SizeBytes < 0 {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "size_bytes must be greater than or equal to 0")
+			continue
+		}
+
+		grant, grantErr := h.svc.RequestFileUploadIntent(c.Context(), filemanager.RequestFileUploadIntentParams{
+			Name:        name,
+			ContentType: contentType,
+			SizeBytes:   item.Attributes.SizeBytes,
+			ActorID:     actorID,
+		})
+		if grantErr != nil {
+			items[i] = fileManagerUploadIntentBulkActionErrorItem(i, "Upload intent failed", grantErr)
+			continue
+		}
+
+		resource := fileManagerFileUploadIntentResource(grant)
+		items[i] = responsedto.FileManagerFileUploadIntentBulkItem{
+			Index:    i,
+			Success:  true,
+			Resource: &resource,
+		}
+	}
+
+	return writeFileManagerUploadIntentBulkResponse(c, items)
+}
+
+// UploadDULImage godoc
+// @Summary Request upload intents for DUL images
+// @Description Dedicated upload-intent endpoint for DUL image flow.
+// @Description Possible status: 201 (all success), 207 (partial success), 400 (invalid json), 401 (unauthorized), 403 (forbidden), 422 (validation), 503 (storage/queue/upload-intent service unavailable).
+// @Description Possible error code: INVALID_REQUEST, USER_UNAUTHORIZED, FORBIDDEN_ACCESS, FILE_MANAGER_VALIDATION_FAILED, FILE_MANAGER_STORAGE_UNAVAILABLE, FILE_MANAGER_QUEUE_UNAVAILABLE, FILE_MANAGER_UPLOAD_INTENT_UNAVAILABLE, FILE_MANAGER_ACTION_FAILED.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileUploadIntentBulkRequest true "Bulk upload intent request"
+// @Success 200 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 403 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/upload-dul-image [post]
+func (h *FileManagerFileHandler) UploadDULImage(c *fiber.Ctx) error {
+	return h.UploadBaseImage(c)
+}
+
+// UploadUserImage godoc
+// @Summary Request upload intents for user profile images
+// @ID FileManagerRequestUserImageUploadIntent
+// @Description Same flow as file upload intent, but dedicated for user profile image flow.
+// @Description Use together with /api/v1/file-manager/files/create-user-image to force target folder under user hierarchy.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileUploadIntentBulkRequest true "Bulk upload intent request"
+// @Success 200 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileUploadIntentBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/upload-user-image [post]
+func (h *FileManagerFileHandler) UploadUserImage(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if !isBulk {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must be an array", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	var req requestdto.FileManagerFileUploadIntentBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	actorID := actorUserID(c)
+	items := make([]responsedto.FileManagerFileUploadIntentBulkItem, len(req.Data))
+	for i := range req.Data {
+		item := req.Data[i]
+		if strings.TrimSpace(item.Type) != "file_manager_file_upload_intent" {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "type must be file_manager_file_upload_intent")
+			continue
+		}
+		name := strings.TrimSpace(item.Attributes.Name)
+		if name == "" {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "name is required")
+			continue
+		}
+		contentType := strings.TrimSpace(item.Attributes.ContentType)
+		if contentType == "" {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "content_type is required")
+			continue
+		}
+		if !strings.HasPrefix(strings.ToLower(contentType), "image/") {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "content_type must be image/* for user image upload")
+			continue
+		}
+		if item.Attributes.SizeBytes < 0 {
+			items[i] = fileManagerUploadIntentBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "size_bytes must be greater than or equal to 0")
+			continue
+		}
+		grant, grantErr := h.svc.RequestFileUploadIntent(c.Context(), filemanager.RequestFileUploadIntentParams{
+			Name:        name,
+			ContentType: contentType,
+			SizeBytes:   item.Attributes.SizeBytes,
+			ActorID:     actorID,
+		})
+		if grantErr != nil {
+			items[i] = fileManagerUploadIntentBulkActionErrorItem(i, "Upload intent failed", grantErr)
+			continue
+		}
+		resource := fileManagerFileUploadIntentResource(grant)
+		items[i] = responsedto.FileManagerFileUploadIntentBulkItem{Index: i, Success: true, Resource: &resource}
+	}
+	return writeFileManagerUploadIntentBulkResponse(c, items)
+}
+
+// CancelUpload godoc
+// @Summary Cancel upload intent (bulk)
+// @ID FileManagerCancelUploadIntentBulk
+// @Description Cancel pending upload intents before file entity creation.
+// @Description This endpoint is intended for pre-create cleanup when FE uploaded to object storage but user cancels flow.
+// @Description Bulk payload accepts one or many items.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileCancelUploadBulkRequest true "Bulk cancel upload intent request"
+// @Success 200 {object} responsedto.FileManagerFileCancelUploadBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/cancel-upload [delete]
+func (h *FileManagerFileHandler) CancelUpload(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if !isBulk {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must be an array", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	var req requestdto.FileManagerFileCancelUploadBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	items := make([]responsedto.FileManagerFileCancelUploadBulkItem, len(req.Data))
+	for i := range req.Data {
+		item := req.Data[i]
+		if strings.TrimSpace(item.Type) != "file_manager_file_cancel_upload" {
+			items[i] = fileManagerCancelUploadBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "type must be file_manager_file_cancel_upload")
+			continue
+		}
+
+		uploadIntentID, err := uuidv7.ParseString(strings.TrimSpace(item.Attributes.UploadIntentUUID))
+		if err != nil {
+			items[i] = fileManagerCancelUploadBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "upload_intent_uuid is invalid UUID")
+			continue
+		}
+
+		if err := h.svc.CancelFileUploadIntent(c.UserContext(), filemanager.CancelFileUploadIntentParams{
+			UploadIntentID: uploadIntentID,
+			ActorID:        actorUserID(c),
+		}); err != nil {
+			items[i] = fileManagerCancelUploadBulkActionErrorItem(i, "Cancel upload failed", err)
+			continue
+		}
+
+		items[i] = fileManagerCancelUploadBulkSuccessItem(i, uploadIntentID)
+	}
+
+	return writeFileManagerCancelUploadBulkResponse(c, items)
+}
+
+// CompleteUploadFile completes a direct upload intent.
+// Deprecated: this method is kept for internal compatibility and is not exposed in public routes.
+func (h *FileManagerFileHandler) CompleteUploadFile(c *fiber.Ctx) error {
+	var req requestdto.FileManagerFileUploadCompleteRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	uploadIntentID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.UploadIntentUUID))
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "upload_intent_uuid is invalid UUID", &jsonapi.ErrorSource{Pointer: "/data/attributes/upload_intent_uuid"})
+	}
+
+	uploaded, err := h.svc.CompleteFileUploadIntent(c.UserContext(), filemanager.CompleteFileUploadIntentParams{
+		UploadIntentID: uploadIntentID,
+		ActorID:        actorUserID(c),
+	})
+	if err != nil {
+		return writeFileManagerActionError(c, "Complete upload failed", err)
+	}
+	return response.Write(c, fiber.StatusOK, fileManagerFileResource(uploaded))
+}
+
+func (h *FileManagerFileHandler) createFilesBulk(c *fiber.Ctx) error {
+	var req requestdto.FileManagerFileBulkCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	items := make([]responsedto.FileManagerFileBulkItem, len(req.Data))
+	validParams := make([]filemanager.CreateFileFromUploadIntentParams, 0, len(req.Data))
+	validIndexes := make([]int, 0, len(req.Data))
+
+	for i := range req.Data {
+		item := req.Data[i]
+		typ := strings.TrimSpace(item.Type)
+		if typ != "file_manager_file_create" && typ != "file_manager_file" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "type must be file_manager_file_create or file_manager_file")
+			continue
+		}
+
+		uploadIntentUUID := strings.TrimSpace(item.Attributes.UploadIntentUUID)
+		uploadIntentID, err := uuidv7.ParseString(uploadIntentUUID)
+		if err != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "upload_intent_uuid is invalid UUID")
+			continue
+		}
+
+		var folderID []byte
+		folderProvided := false
+		if item.Attributes.FolderID != nil {
+			folderProvided = true
+			folderUUID := strings.TrimSpace(*item.Attributes.FolderID)
+			if folderUUID != "" {
+				parsed, parseErr := uuidv7.ParseString(folderUUID)
+				if parseErr != nil {
+					items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "folder_id is invalid UUID")
+					continue
+				}
+				folderID = parsed
+			}
+		}
+
+		name := strings.TrimSpace(item.Attributes.Name)
+		if name == "" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "name is required")
+			continue
+		}
+
+		validParams = append(validParams, filemanager.CreateFileFromUploadIntentParams{
+			UploadIntentID: uploadIntentID,
+			FolderID:       folderID,
+			FolderProvided: folderProvided,
+			Name:           name,
+			ActorID:        actorUserID(c),
+		})
+		validIndexes = append(validIndexes, i)
+	}
+
+	for i := range validParams {
+		idx := validIndexes[i]
+		created, err := h.svc.CreateFileNodeFromUploadIntent(c.UserContext(), validParams[i])
+		if err != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Create failed", err)
+			continue
+		}
+		items[idx] = fileManagerBulkSuccessItem(idx, "created", created)
+	}
+
+	return writeFileManagerBulkResponse(c, items)
+}
+
+func (h *FileManagerFileHandler) UploadFleetStatusFile(c *fiber.Ctx) error {
+	return h.UploadFile(c)
+}
+
+func (h *FileManagerFileHandler) CreateFleetStatusFile(c *fiber.Ctx) error {
+	return h.createFilesBulk(c)
+}
+
+// CreateAircraftImage godoc
+// @Summary Create aircraft image file record from uploaded object
+// @ID FileManagerCreateAircraftImageFromUploadedObject
+// @Description Same as bulk create, but folder is resolved using hierarchy "__system_root_files__" -> "aircraft" -> "<aircraft designation>".
+// @Description aircraft_uuid is required per item to resolve designation.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileAircraftBulkCreateRequest true "Bulk create payload for aircraft image"
+// @Success 200 {object} responsedto.FileManagerFileBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/create-aircraft-image [post]
+func (h *FileManagerFileHandler) CreateAircraftImage(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if !isBulk {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must be an array", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	var req requestdto.FileManagerFileAircraftBulkCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	actorID := actorUserID(c)
+	if h.aircraft == nil {
+		return writeFileManagerError(c, fiber.StatusServiceUnavailable, "Aircraft service unavailable", "aircraft service is not configured", nil)
+	}
+
+	items := make([]responsedto.FileManagerFileBulkItem, len(req.Data))
+	validParams := make([]filemanager.CreateFileFromUploadIntentParams, 0, len(req.Data))
+	validIndexes := make([]int, 0, len(req.Data))
+	for i := range req.Data {
+		item := req.Data[i]
+		typ := strings.TrimSpace(item.Type)
+		if typ != "file_manager_file_create" && typ != "file_manager_file" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "type must be file_manager_file_create or file_manager_file")
+			continue
+		}
+
+		uploadIntentUUID := strings.TrimSpace(item.Attributes.UploadIntentUUID)
+		uploadIntentID, err := uuidv7.ParseString(uploadIntentUUID)
+		if err != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "upload_intent_uuid is invalid UUID")
+			continue
+		}
+
+		name := strings.TrimSpace(item.Attributes.Name)
+		if name == "" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "name is required")
+			continue
+		}
+
+		aircraftUUID := strings.TrimSpace(item.Attributes.AircraftUUID)
+		aircraftID, parseAircraftErr := uuidv7.ParseString(aircraftUUID)
+		if parseAircraftErr != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "aircraft_uuid is invalid UUID")
+			continue
+		}
+
+		aircraftRow, getAircraftErr := h.aircraft.GetByID(c.UserContext(), aircraftID)
+		if getAircraftErr != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusBadRequest, "Create failed", getAircraftErr.Error())
+			continue
+		}
+		if aircraftRow == nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusNotFound, "Not found", "aircraft not found")
+			continue
+		}
+
+		designation := strings.TrimSpace(aircraftRow.Designation)
+		if designation == "" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "aircraft designation cannot be empty")
+			continue
+		}
+
+		aircraftDesignationFolderID, resolveErr := h.ensureAircraftDesignationFolder(c.UserContext(), actorID, designation)
+		if resolveErr != nil {
+			items[i] = fileManagerBulkActionErrorItem(i, "Create failed", resolveErr)
+			continue
+		}
+
+		validParams = append(validParams, filemanager.CreateFileFromUploadIntentParams{
+			UploadIntentID: uploadIntentID,
+			FolderID:       aircraftDesignationFolderID,
+			FolderProvided: true,
+			Name:           name,
+			ActorID:        actorID,
+		})
+		validIndexes = append(validIndexes, i)
+	}
+
+	for i := range validParams {
+		idx := validIndexes[i]
+		existingRows, _, listErr := h.svc.ListFilesByFolder(c.UserContext(), validParams[i].FolderID, "name ASC", 0, 0)
+		if listErr != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Replace failed", listErr)
+			continue
+		}
+		replaceFailed := false
+		for j := range existingRows {
+			if len(existingRows[j].ID) != 16 {
+				continue
+			}
+			now := time.Now().UTC()
+			if deleteErr := h.svc.DeleteFile(c.UserContext(), existingRows[j].ID, actorID, &now); deleteErr != nil {
+				items[idx] = fileManagerBulkActionErrorItem(idx, "Replace failed", deleteErr)
+				replaceFailed = true
+				break
+			}
+			if purgeErr := h.svc.PurgeFileNode(c.UserContext(), existingRows[j].ID); purgeErr != nil {
+				items[idx] = fileManagerBulkActionErrorItem(idx, "Replace failed", purgeErr)
+				replaceFailed = true
+				break
+			}
+		}
+		if replaceFailed {
+			continue
+		}
+
+		created, err := h.svc.CreateFileNodeFromUploadIntent(c.UserContext(), validParams[i])
+		if err != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Create failed", err)
+			continue
+		}
+		items[idx] = fileManagerBulkSuccessItem(idx, "created", created)
+	}
+
+	return writeFileManagerBulkResponse(c, items)
+}
+
+// CreateBaseImage godoc
+// @Summary Create base image file record from uploaded object
+// @ID FileManagerCreateBaseImageFromUploadedObject
+// @Description Same as bulk create, but folder is resolved using hierarchy "__system_root_files__" -> "bases" -> "<base-type>" -> "<base-name>".
+// @Description base_uuid is required per item.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileBaseBulkCreateRequest true "Bulk create payload for base image"
+// @Success 200 {object} responsedto.FileManagerFileBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/create-base-image [post]
+func (h *FileManagerFileHandler) CreateBaseImage(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if !isBulk {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must be an array", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	var req requestdto.FileManagerFileBaseBulkCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	actorID := actorUserID(c)
+	if h.base == nil {
+		return writeFileManagerError(c, fiber.StatusServiceUnavailable, "Base service unavailable", "base service is not configured", nil)
+	}
+
+	items := make([]responsedto.FileManagerFileBulkItem, len(req.Data))
+	validParams := make([]filemanager.CreateFileFromUploadIntentParams, 0, len(req.Data))
+	validIndexes := make([]int, 0, len(req.Data))
+	for i := range req.Data {
+		item := req.Data[i]
+		typ := strings.TrimSpace(item.Type)
+		if typ != "file_manager_file_create" && typ != "file_manager_file" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "type must be file_manager_file_create or file_manager_file")
+			continue
+		}
+
+		uploadIntentUUID := strings.TrimSpace(item.Attributes.UploadIntentUUID)
+		uploadIntentID, parseUploadErr := uuidv7.ParseString(uploadIntentUUID)
+		if parseUploadErr != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "upload_intent_uuid is invalid UUID")
+			continue
+		}
+
+		name := strings.TrimSpace(item.Attributes.Name)
+		if name == "" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "name is required")
+			continue
+		}
+
+		baseUUID := strings.TrimSpace(item.Attributes.BaseUUID)
+		baseID, parseBaseErr := uuidv7.ParseString(baseUUID)
+		if parseBaseErr != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "base_uuid is invalid UUID")
+			continue
+		}
+
+		baseRow, baseType, getBaseErr := h.getBaseByIDAnyType(c.UserContext(), baseID)
+		if getBaseErr != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusBadRequest, "Create failed", getBaseErr.Error())
+			continue
+		}
+		if baseRow == nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusNotFound, "Not found", "base not found")
+			continue
+		}
+
+		baseName := strings.TrimSpace(baseRow.BaseName)
+		if baseName == "" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "base name cannot be empty")
+			continue
+		}
+
+		baseFolderID, resolveErr := h.ensureBaseImageFolder(c.UserContext(), actorID, baseType, baseName)
+		if resolveErr != nil {
+			items[i] = fileManagerBulkActionErrorItem(i, "Create failed", resolveErr)
+			continue
+		}
+
+		validParams = append(validParams, filemanager.CreateFileFromUploadIntentParams{
+			UploadIntentID: uploadIntentID,
+			FolderID:       baseFolderID,
+			FolderProvided: true,
+			Name:           name,
+			ActorID:        actorID,
+		})
+		validIndexes = append(validIndexes, i)
+	}
+
+	for i := range validParams {
+		idx := validIndexes[i]
+		existingRows, _, listErr := h.svc.ListFilesByFolder(c.UserContext(), validParams[i].FolderID, "name ASC", 0, 0)
+		if listErr != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Replace failed", listErr)
+			continue
+		}
+
+		replaceFailed := false
+		for j := range existingRows {
+			if len(existingRows[j].ID) != 16 {
+				continue
+			}
+			now := time.Now().UTC()
+			if deleteErr := h.svc.DeleteFile(c.UserContext(), existingRows[j].ID, actorID, &now); deleteErr != nil {
+				items[idx] = fileManagerBulkActionErrorItem(idx, "Replace failed", deleteErr)
+				replaceFailed = true
+				break
+			}
+			if purgeErr := h.svc.PurgeFileNode(c.UserContext(), existingRows[j].ID); purgeErr != nil {
+				items[idx] = fileManagerBulkActionErrorItem(idx, "Replace failed", purgeErr)
+				replaceFailed = true
+				break
+			}
+		}
+		if replaceFailed {
+			continue
+		}
+
+		created, createErr := h.svc.CreateFileNodeFromUploadIntent(c.UserContext(), validParams[i])
+		if createErr != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Create failed", createErr)
+			continue
+		}
+		items[idx] = fileManagerBulkSuccessItem(idx, "created", created)
+	}
+
+	return writeFileManagerBulkResponse(c, items)
+}
+
+// CreateDULImage godoc
+// @Summary Create DUL image file record from uploaded object
+// @Description Finalize uploaded DUL image file(s) from upload intent.
+// @Description If dul_uuid is provided, file is created under DUL folder hierarchy.
+// @Description If dul_uuid is omitted, file is still created (unassigned), then can be attached during /api/v1/dul/create via file_uuid.
+// @Description Possible status: 201 (all success), 207 (partial success), 400 (invalid json/create failed), 401 (unauthorized), 403 (forbidden), 404 (dul or file resources not found), 409 (upload-intent conflict), 422 (validation), 503 (DUL or file-manager service unavailable).
+// @Description Possible error code: INVALID_REQUEST, USER_UNAUTHORIZED, FORBIDDEN_ACCESS, FILE_MANAGER_VALIDATION_FAILED, FILE_MANAGER_FILE_NOT_FOUND, FILE_MANAGER_UPLOAD_INTENT_NOT_FOUND, FILE_MANAGER_UPLOAD_INTENT_CONFLICT, DUL_NOT_FOUND, FILE_MANAGER_STORAGE_UNAVAILABLE, FILE_MANAGER_QUEUE_UNAVAILABLE, FILE_MANAGER_ATTACHMENT_SERVICE_UNAVAILABLE, FILE_MANAGER_ACTION_FAILED.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileDULBulkCreateRequest true "Bulk create payload for DUL image"
+// @Success 200 {object} responsedto.FileManagerFileBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileBulkResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 403 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 409 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/create-dul-image [post]
+func (h *FileManagerFileHandler) CreateDULImage(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if !isBulk {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must be an array", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	var req requestdto.FileManagerFileDULBulkCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+	actorID := actorUserID(c)
+	items := make([]responsedto.FileManagerFileBulkItem, len(req.Data))
+	validParams := make([]filemanager.CreateFileFromUploadIntentParams, 0, len(req.Data))
+	validIndexes := make([]int, 0, len(req.Data))
+
+	for i := range req.Data {
+		item := req.Data[i]
+		if strings.TrimSpace(item.Type) != "file_manager_file_create" && strings.TrimSpace(item.Type) != "file_manager_file" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "type must be file_manager_file_create or file_manager_file")
+			continue
+		}
+		uploadIntentID, parseUploadErr := uuidv7.ParseString(strings.TrimSpace(item.Attributes.UploadIntentUUID))
+		if parseUploadErr != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "upload_intent_uuid is invalid UUID")
+			continue
+		}
+		name := strings.TrimSpace(item.Attributes.Name)
+		if name == "" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "name is required")
+			continue
+		}
+
+		rawDULUUID := strings.TrimSpace(item.Attributes.DULUUID)
+		if rawDULUUID == "" {
+			validParams = append(validParams, filemanager.CreateFileFromUploadIntentParams{
+				UploadIntentID: uploadIntentID,
+				Name:           name,
+				FolderProvided: false,
+				ActorID:        actorID,
+			})
+			validIndexes = append(validIndexes, i)
+			continue
+		}
+
+		dulID, parseDULErr := uuidv7.ParseString(rawDULUUID)
+		if parseDULErr != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "dul_uuid is invalid UUID")
+			continue
+		}
+		if h.dul == nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusServiceUnavailable, "DUL service unavailable", "dul service is not configured")
+			continue
+		}
+		dulRow, getErr := h.dul.GetByID(c.UserContext(), dulID)
+		if getErr != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusBadRequest, "Create failed", getErr.Error())
+			continue
+		}
+		if dulRow == nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusNotFound, "Not found", "dul not found")
+			continue
+		}
+		folderID, folderErr := h.ensureDULImageFolder(c.UserContext(), actorID, strings.TrimSpace(dulRow.Name), dulID)
+		if folderErr != nil {
+			items[i] = fileManagerBulkActionErrorItem(i, "Create failed", folderErr)
+			continue
+		}
+		validParams = append(validParams, filemanager.CreateFileFromUploadIntentParams{
+			UploadIntentID: uploadIntentID,
+			FolderID:       folderID,
+			FolderProvided: true,
+			Name:           name,
+			ActorID:        actorID,
+		})
+		validIndexes = append(validIndexes, i)
+	}
+
+	for i := range validParams {
+		idx := validIndexes[i]
+		created, createErr := h.svc.CreateFileNodeFromUploadIntent(c.UserContext(), validParams[i])
+		if createErr != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Create failed", createErr)
+			continue
+		}
+		if _, _, sanitizeErr := h.sanitizeStoredXLSXObject(c.UserContext(), created, created.ObjectKey, created.Name, created.MimeType, "create-takeover-file"); sanitizeErr != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Create failed", sanitizeErr)
+			continue
+		}
+		items[idx] = fileManagerBulkSuccessItem(idx, "created", created)
+	}
+	return writeFileManagerBulkResponse(c, items)
+}
+
+// CreateTakeoverFile godoc
+// @Summary Create takeover file node from uploaded object
+// @Description Finalize uploaded takeover file(s) from upload intent. The takeover relation is attached later from file_id during takeover create/update.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileTakeoverBulkCreateRequest true "Bulk create payload for takeover file"
+// @Success 200 {object} responsedto.FileManagerFileBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/create-takeover-file [post]
+func (h *FileManagerFileHandler) CreateTakeoverFile(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if !isBulk {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must be an array", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	var req requestdto.FileManagerFileTakeoverBulkCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	actorID := actorUserID(c)
+
+	items := make([]responsedto.FileManagerFileBulkItem, len(req.Data))
+	validParams := make([]filemanager.CreateFileFromUploadIntentParams, 0, len(req.Data))
+	validIndexes := make([]int, 0, len(req.Data))
+
+	for i := range req.Data {
+		item := req.Data[i]
+		typ := strings.TrimSpace(item.Type)
+		if typ != "file_manager_file_create" && typ != "file_manager_file" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "type must be file_manager_file_create or file_manager_file")
+			continue
+		}
+
+		uploadIntentUUID := strings.TrimSpace(item.Attributes.UploadIntentUUID)
+		uploadIntentID, parseUploadErr := uuidv7.ParseString(uploadIntentUUID)
+		if parseUploadErr != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "upload_intent_uuid is invalid UUID")
+			continue
+		}
+
+		name := strings.TrimSpace(item.Attributes.Name)
+		if name == "" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "name is required")
+			continue
+		}
+
+		validParams = append(validParams, filemanager.CreateFileFromUploadIntentParams{
+			UploadIntentID: uploadIntentID,
+			FolderProvided: false,
+			Name:           name,
+			ActorID:        actorID,
+		})
+		validIndexes = append(validIndexes, i)
+	}
+
+	for i := range validParams {
+		idx := validIndexes[i]
+		created, createErr := h.svc.CreateFileNodeFromUploadIntent(c.UserContext(), validParams[i])
+		if createErr != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Create failed", createErr)
+			continue
+		}
+		items[idx] = fileManagerBulkSuccessItem(idx, "created", created)
+	}
+
+	return writeFileManagerBulkResponse(c, items)
+}
+
+// CreateUserImage godoc
+// @Summary Create user profile image file record from uploaded object
+// @ID FileManagerCreateUserImageFromUploadedObject
+// @Description Same as bulk create, but folder is resolved using hierarchy "__system_root_files__" -> "user" -> "<username>-<user-uuid>".
+// @Description user_uuid is required per item to resolve target user folder.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileUserBulkCreateRequest true "Bulk create payload for user profile image"
+// @Success 200 {object} responsedto.FileManagerFileBulkResponse
+// @Success 207 {object} responsedto.FileManagerFileBulkResponse
+// @Success 201 {object} responsedto.FileManagerFileBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/create-user-image [post]
+func (h *FileManagerFileHandler) CreateUserImage(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if !isBulk {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must be an array", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+	var req requestdto.FileManagerFileUserBulkCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+	actorID := actorUserID(c)
+	if h.user == nil {
+		return writeFileManagerError(c, fiber.StatusServiceUnavailable, "User service unavailable", "user service is not configured", nil)
+	}
+
+	items := make([]responsedto.FileManagerFileBulkItem, len(req.Data))
+	validParams := make([]filemanager.CreateFileFromUploadIntentParams, 0, len(req.Data))
+	validIndexes := make([]int, 0, len(req.Data))
+	for i := range req.Data {
+		item := req.Data[i]
+		typ := strings.TrimSpace(item.Type)
+		if typ != "file_manager_file_create" && typ != "file_manager_file" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "type must be file_manager_file_create or file_manager_file")
+			continue
+		}
+		uploadIntentID, parseUploadErr := uuidv7.ParseString(strings.TrimSpace(item.Attributes.UploadIntentUUID))
+		if parseUploadErr != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "upload_intent_uuid is invalid UUID")
+			continue
+		}
+		name := strings.TrimSpace(item.Attributes.Name)
+		if name == "" {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "name is required")
+			continue
+		}
+		userID, parseUserErr := uuidv7.ParseString(strings.TrimSpace(item.Attributes.UserUUID))
+		if parseUserErr != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "user_uuid is invalid UUID")
+			continue
+		}
+		userRow, userErr := h.user.GetByID(c.UserContext(), userID)
+		if userErr != nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusBadRequest, "Create failed", userErr.Error())
+			continue
+		}
+		if userRow == nil {
+			items[i] = fileManagerBulkSystemErrorItem(i, fiber.StatusNotFound, "Not found", "user not found")
+			continue
+		}
+		username := strings.TrimSpace(userRow.Username)
+		if username == "" {
+			username = strings.TrimSpace(userRow.FirstName + "-" + userRow.LastName)
+		}
+		if username == "" {
+			username = "user"
+		}
+		userFolderID, resolveErr := h.ensureUserImageFolder(c.UserContext(), actorID, username, userID)
+		if resolveErr != nil {
+			items[i] = fileManagerBulkActionErrorItem(i, "Create failed", resolveErr)
+			continue
+		}
+		validParams = append(validParams, filemanager.CreateFileFromUploadIntentParams{
+			UploadIntentID: uploadIntentID,
+			FolderID:       userFolderID,
+			FolderProvided: true,
+			Name:           name,
+			ActorID:        actorID,
+		})
+		validIndexes = append(validIndexes, i)
+	}
+	for i := range validParams {
+		idx := validIndexes[i]
+		existingRows, _, listErr := h.svc.ListFilesByFolder(c.UserContext(), validParams[i].FolderID, "name ASC", 0, 0)
+		if listErr != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Replace failed", listErr)
+			continue
+		}
+		replaceFailed := false
+		for j := range existingRows {
+			if len(existingRows[j].ID) != 16 {
+				continue
+			}
+			now := time.Now().UTC()
+			if deleteErr := h.svc.DeleteFile(c.UserContext(), existingRows[j].ID, actorID, &now); deleteErr != nil {
+				items[idx] = fileManagerBulkActionErrorItem(idx, "Replace failed", deleteErr)
+				replaceFailed = true
+				break
+			}
+			if purgeErr := h.svc.PurgeFileNode(c.UserContext(), existingRows[j].ID); purgeErr != nil {
+				items[idx] = fileManagerBulkActionErrorItem(idx, "Replace failed", purgeErr)
+				replaceFailed = true
+				break
+			}
+		}
+		if replaceFailed {
+			continue
+		}
+		created, createErr := h.svc.CreateFileNodeFromUploadIntent(c.UserContext(), validParams[i])
+		if createErr != nil {
+			items[idx] = fileManagerBulkActionErrorItem(idx, "Create failed", createErr)
+			continue
+		}
+		items[idx] = fileManagerBulkSuccessItem(idx, "created", created)
+	}
+	return writeFileManagerBulkResponse(c, items)
+}
+
+func isJSONAPIDataArrayPayload(body []byte) (bool, error) {
+	var envelope struct {
+		Data json.RawMessage `json:"data"`
+	}
+	if err := json.Unmarshal(body, &envelope); err != nil {
+		return false, err
+	}
+	data := bytes.TrimSpace(envelope.Data)
+	if len(data) == 0 {
+		return false, nil
+	}
+	return data[0] == '[', nil
+}
+
+// isFileManagerCreateBulkPayload is kept for backward compatibility with existing tests/helpers.
+func isFileManagerCreateBulkPayload(body []byte) (bool, error) {
+	return isJSONAPIDataArrayPayload(body)
+}
+
+func parseUploadNameOverrides(formValues map[string][]string, filesCount int) ([]string, error) {
+	nameOverrides := formValues["names"]
+	if len(nameOverrides) == 0 {
+		nameOverrides = formValues["name"]
+	}
+	if len(nameOverrides) > 0 && len(nameOverrides) != filesCount {
+		return nil, errors.New("names count must match files count")
+	}
+	return nameOverrides, nil
+}
+
+func (h *FileManagerFileHandler) ensureAircraftDesignationFolder(ctx context.Context, actorID []byte, designation string) ([]byte, error) {
+	rootFolder, err := h.svc.GetOrCreateSystemRootFolder(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if rootFolder == nil || len(rootFolder.ID) != 16 {
+		return nil, filemanager.ErrFolderNotFound
+	}
+
+	aircraftFolderID, err := h.ensureFolderByParentAndName(ctx, rootFolder.ID, aircraftImageFolderName, actorID)
+	if err != nil {
+		return nil, err
+	}
+
+	return h.ensureFolderByParentAndName(ctx, aircraftFolderID, designation, actorID)
+}
+
+func (h *FileManagerFileHandler) ensureBaseImageFolder(ctx context.Context, actorID []byte, baseType, baseName string) ([]byte, error) {
+	rootFolder, err := h.svc.GetOrCreateSystemRootFolder(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if rootFolder == nil || len(rootFolder.ID) != 16 {
+		return nil, filemanager.ErrFolderNotFound
+	}
+
+	basesFolderID, err := h.ensureFolderByParentAndName(ctx, rootFolder.ID, baseImageFolderName, actorID)
+	if err != nil {
+		return nil, err
+	}
+	baseTypeFolderID, err := h.ensureFolderByParentAndName(ctx, basesFolderID, strings.TrimSpace(baseType), actorID)
+	if err != nil {
+		return nil, err
+	}
+	return h.ensureFolderByParentAndName(ctx, baseTypeFolderID, strings.TrimSpace(baseName), actorID)
+}
+
+func (h *FileManagerFileHandler) ensureUserImageFolder(ctx context.Context, actorID []byte, username string, userID []byte) ([]byte, error) {
+	rootFolder, err := h.svc.GetOrCreateSystemRootFolder(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if rootFolder == nil || len(rootFolder.ID) != 16 {
+		return nil, filemanager.ErrFolderNotFound
+	}
+	usersFolderID, err := h.ensureFolderByParentAndName(ctx, rootFolder.ID, userImageFolderName, actorID)
+	if err != nil {
+		return nil, err
+	}
+	userUUID := idString(userID)
+	folderName := fmt.Sprintf("%s-%s", sanitizeFolderName(username), userUUID)
+	return h.ensureFolderByParentAndName(ctx, usersFolderID, folderName, actorID)
+}
+
+func (h *FileManagerFileHandler) ensureDULImageFolder(ctx context.Context, actorID []byte, dulName string, dulID []byte) ([]byte, error) {
+	rootFolder, err := h.svc.GetOrCreateSystemRootFolder(ctx)
+	if err != nil {
+		return nil, err
+	}
+	dulsFolderID, err := h.ensureFolderByParentAndName(ctx, rootFolder.ID, dulImageFolderName, actorID)
+	if err != nil {
+		return nil, err
+	}
+	folderName := strings.TrimSpace(dulName)
+	if folderName == "" {
+		folderName = "dul"
+	}
+	if id := idString(dulID); id != "" {
+		folderName += "-" + id
+	}
+	return h.ensureFolderByParentAndName(ctx, dulsFolderID, folderName, actorID)
+}
+
+func (h *FileManagerFileHandler) ensureTakeoverFileFolder(ctx context.Context, actorID []byte, takeoverID []byte) ([]byte, error) {
+	rootFolder, err := h.svc.GetOrCreateSystemRootFolder(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if rootFolder == nil || len(rootFolder.ID) != 16 {
+		return nil, filemanager.ErrFolderNotFound
+	}
+	takeoversFolderID, err := h.ensureFolderByParentAndName(ctx, rootFolder.ID, takeoverFileFolderName, actorID)
+	if err != nil {
+		return nil, err
+	}
+	return h.ensureFolderByParentAndName(ctx, takeoversFolderID, idString(takeoverID), actorID)
+}
+
+func sanitizeFolderName(in string) string {
+	name := strings.ToLower(strings.TrimSpace(in))
+	if name == "" {
+		return "user"
+	}
+	var b strings.Builder
+	lastDash := false
+	for _, r := range name {
+		isAZ := r >= 'a' && r <= 'z'
+		is09 := r >= '0' && r <= '9'
+		if isAZ || is09 {
+			b.WriteRune(r)
+			lastDash = false
+			continue
+		}
+		if !lastDash {
+			b.WriteByte('-')
+			lastDash = true
+		}
+	}
+	out := strings.Trim(b.String(), "-")
+	if out == "" {
+		return "user"
+	}
+	return out
+}
+
+func (h *FileManagerFileHandler) getBaseByIDAnyType(ctx context.Context, id []byte) (*base.Base, string, error) {
+	for _, categoryType := range []string{base.CategoryKeyHEMS, base.CategoryKeyRegular} {
+		row, err := h.base.GetBaseByID(ctx, id, categoryType)
+		if err != nil {
+			return nil, "", err
+		}
+		if row != nil {
+			return row, categoryType, nil
+		}
+	}
+	return nil, "", nil
+}
+
+func ensureFileManagerFolder(ctx context.Context, svc filemanager.Service, parentID []byte, folderName string, actorID []byte) ([]byte, error) {
+	normalizedName := strings.ToLower(strings.TrimSpace(folderName))
+	if normalizedName == "" {
+		return nil, filemanager.ErrInvalidName
+	}
+
+	row, err := svc.GetFolderByParentAndName(ctx, parentID, normalizedName)
+	if err != nil {
+		return nil, err
+	}
+	if row != nil && len(row.ID) == 16 {
+		return row.ID, nil
+	}
+
+	created, err := svc.CreateFolderNode(ctx, filemanager.CreateFolderParams{
+		Name:     folderName,
+		ParentID: parentID,
+		ActorID:  actorID,
+	})
+	if err == nil && created != nil && len(created.ID) == 16 {
+		return created.ID, nil
+	}
+	if !errors.Is(err, filemanager.ErrDuplicateName) {
+		return nil, err
+	}
+
+	row, err = svc.GetFolderByParentAndName(ctx, parentID, normalizedName)
+	if err != nil {
+		return nil, err
+	}
+	if row == nil || len(row.ID) != 16 {
+		return nil, filemanager.ErrFolderNotFound
+	}
+	return row.ID, nil
+}
+
+func (h *FileManagerFileHandler) ensureFolderByParentAndName(ctx context.Context, parentID []byte, folderName string, actorID []byte) ([]byte, error) {
+	return ensureFileManagerFolder(ctx, h.svc, parentID, folderName, actorID)
+}
+
+func ensureMissionFileFolderPath(ctx context.Context, svc filemanager.Service, missionID []byte, actorID []byte) ([]byte, error) {
+	rootFolder, err := svc.GetOrCreateSystemRootFolder(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if rootFolder == nil || len(rootFolder.ID) != 16 {
+		return nil, filemanager.ErrFolderNotFound
+	}
+	missionsFolderID, err := ensureFileManagerFolder(ctx, svc, rootFolder.ID, missionFileFolderName, actorID)
+	if err != nil {
+		return nil, err
+	}
+	return ensureFileManagerFolder(ctx, svc, missionsFolderID, idString(missionID), actorID)
+}
+
+// GetFile godoc
+// @Summary Get file detail
+// @ID FileManagerGetFile
+// @Description Return file metadata by UUID.
+// @Tags File Manager
+// @Produce json
+// @Param uuid path string true "File UUID (UUIDv7)"
+// @Success 200 {object} responsedto.FileManagerFileDetailResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/get/{uuid} [get]
+func (h *FileManagerFileHandler) GetFile(c *fiber.Ctx) error {
+	id, err := h.parseUUIDParam(c, "uuid", "/path/uuid")
+	if err != nil {
+		return err
+	}
+
+	row, err := h.svc.GetFileByID(c.UserContext(), id)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Get failed", err.Error(), nil)
+	}
+	if row == nil {
+		return writeFileManagerError(c, fiber.StatusNotFound, "Not found", "file not found", nil)
+	}
+
+	isRootFile := false
+	root, rootErr := h.svc.GetOrCreateSystemRootFolder(c.Context())
+	if rootErr != nil {
+		return writeFileManagerActionError(c, "Get failed", rootErr)
+	}
+	if root != nil && len(root.ID) == len(row.FolderID) && bytes.Equal(root.ID, row.FolderID) {
+		isRootFile = true
+	}
+
+	return response.Write(c, fiber.StatusOK, fileManagerFileDetailResource(c.UserContext(), h.storage, row, isRootFile))
+}
+
+func (h *FileManagerFileHandler) ListFiles(c *fiber.Ctx) error {
+	folderUUID := strings.TrimSpace(c.Query("folder_uuid"))
+	var folderID []byte
+	if folderUUID != "" {
+		parsed, err := uuidv7.ParseString(folderUUID)
+		if err != nil {
+			return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "folder_uuid is invalid UUID", &jsonapi.ErrorSource{Pointer: "/query/folder_uuid"})
+		}
+		folderID = parsed
+	} else {
+		root, err := h.svc.GetOrCreateSystemRootFolder(c.UserContext())
+		if err != nil {
+			return writeFileManagerActionError(c, "List failed", err)
+		}
+		folderID = root.ID
+	}
+
+	pageNumber, pageSize, offset := parseFileManagerFilePagination(c)
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.ListFilesByFolder(c.UserContext(), folderID, sort, 0, 0)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "List failed", err.Error(), nil)
+	}
+
+	data := make([]responsedto.FileManagerFileListResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, fileManagerFileListResource(c.UserContext(), h.storage, &rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func (h *FileManagerFileHandler) ListTrashFiles(c *fiber.Ctx) error {
+	var folderID []byte
+	folderUUID := strings.TrimSpace(c.Query("folder_uuid"))
+	if folderUUID != "" {
+		id, err := uuidv7.ParseString(folderUUID)
+		if err != nil {
+			return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "folder_uuid is invalid UUID", &jsonapi.ErrorSource{Pointer: "/query/folder_uuid"})
+		}
+		folderID = id
+	}
+
+	pageNumber, pageSize, offset := parseFileManagerFilePagination(c)
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.ListTrashFilesByFolder(c.UserContext(), folderID, sort, 0, 0)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "List failed", err.Error(), nil)
+	}
+
+	data := make([]responsedto.FileManagerFileListResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, fileManagerFileListResource(c.UserContext(), h.storage, &rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// UpdateFile godoc
+// @Summary Update file entity (rename and/or move)
+// @ID FileManagerUpdateFileEntity
+// @Description Update file metadata by UUID (rename and/or move folder).
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param uuid path string true "File UUID (UUIDv7)"
+// @Param request body requestdto.FileManagerFileUpdateRequest true "JSON:API file manager file update request"
+// @Success 200 {object} responsedto.FileManagerFileResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/update/{uuid} [patch]
+func (h *FileManagerFileHandler) UpdateFile(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "uuid is invalid UUID", &jsonapi.ErrorSource{Pointer: "/path/uuid"})
+	}
+
+	var req requestdto.FileManagerFileUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if strings.TrimSpace(req.Data.ID) == "" || req.Data.ID != uuidStr {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "id does not match path uuid", &jsonapi.ErrorSource{Pointer: "/data/id"})
+	}
+	attrs := req.Data.Attributes
+	if attrs.Name == nil && attrs.FolderID == nil {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "at least one attribute must be provided", &jsonapi.ErrorSource{Pointer: "/data/attributes"})
+	}
+
+	var folderID []byte
+	folderProvided := attrs.FolderID != nil
+	if folderProvided && strings.TrimSpace(*attrs.FolderID) != "" {
+		parsed, err := uuidv7.ParseString(strings.TrimSpace(*attrs.FolderID))
+		if err != nil {
+			return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "folder_id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/data/attributes/folder_id"})
+		}
+		folderID = parsed
+	}
+
+	updated, err := h.svc.MoveFileNode(c.UserContext(), id, filemanager.MoveFileParams{
+		Name:           attrs.Name,
+		FolderID:       folderID,
+		FolderProvided: folderProvided,
+		ActorID:        actorUserID(c),
+	})
+	if err != nil {
+		return writeFileManagerActionError(c, "Update failed", err)
+	}
+	return response.Write(c, fiber.StatusOK, fileManagerFileResource(updated))
+}
+
+func (h *FileManagerFileHandler) DeleteFile(c *fiber.Ctx) error {
+	id, err := h.parseUUIDParam(c, "uuid", "/path/uuid")
+	if err != nil {
+		return err
+	}
+	if err := h.svc.DeleteFile(c.UserContext(), id, actorUserID(c), nil); err != nil {
+		return writeFileManagerActionError(c, "Delete failed", err)
+	}
+
+	return response.Write(c, fiber.StatusOK, fileManagerActionResultResource("file_manager_delete_result", id, "trashed", ""))
+}
+
+// RestoreFile restores a trashed file by ID to its original location.
+func (h *FileManagerFileHandler) RestoreFile(c *fiber.Ctx) error {
+	id, err := h.parseUUIDParam(c, "uuid", "/path/uuid")
+	if err != nil {
+		return err
+	}
+
+	if err := h.svc.RestoreFile(c.Context(), id, nil, false, actorUserID(c)); err != nil {
+		return writeFileManagerActionError(c, "Restore failed", err)
+	}
+
+	row, err := h.svc.GetFileByID(c.Context(), id)
+	if err != nil {
+		return writeFileManagerActionError(c, "Restore failed", err)
+	}
+	if row == nil {
+		return writeFileManagerActionError(c, "Restore failed", filemanager.ErrFileNotFound)
+	}
+
+	root, rootErr := h.svc.GetOrCreateSystemRootFolder(c.Context())
+	if rootErr != nil {
+		return writeFileManagerActionError(c, "Restore failed", rootErr)
+	}
+	locationFolderID := ""
+	if root == nil || !bytes.Equal(row.FolderID, root.ID) {
+		locationFolderID = idString(row.FolderID)
+	}
+
+	return response.Write(c, fiber.StatusOK, fileManagerActionResultResource("file_manager_restore_result", id, filemanager.FileStatusReady, locationFolderID))
+}
+
+func fileManagerFileResource(row *filemanager.File) responsedto.FileManagerFileResource {
+	return responsedto.FileManagerFileResource{
+		Type: "file_manager_file",
+		ID:   idString(row.ID),
+		Attributes: shareddto.FileManagerFileAttributes{
+			FileUUID:            idString(row.ID),
+			FolderID:            idString(row.FolderID),
+			Name:                row.Name,
+			NameNormalized:      row.NameNormalized,
+			Extension:           row.Extension,
+			SizeBytes:           row.SizeBytes,
+			MimeType:            row.MimeType,
+			IsTemplate:          row.IsTemplate,
+			Status:              row.Status,
+			FailureReason:       firstNonEmpty(strings.TrimSpace(row.FailureReason), strings.TrimSpace(row.UploadError)),
+			UploadError:         firstNonEmpty(strings.TrimSpace(row.UploadError), strings.TrimSpace(row.FailureReason)),
+			ProcessingStartedAt: timeStringOrEmpty(row.ProcessingStartedAt),
+			ProcessedAt:         timeStringOrEmpty(row.ProcessedAt),
+			ValidatedAt:         timeStringOrEmpty(row.ValidatedAt),
+			FailedAt:            timeStringOrEmpty(row.FailedAt),
+			CreatedAt:           row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:           uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:           row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:           uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt:           timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:           uuidStringOrEmpty(row.DeletedBy),
+			TrashedAt:           timeStringOrEmpty(row.TrashedAt),
+			PurgeAt:             timeStringOrEmpty(row.PurgeAt),
+		},
+	}
+}
+
+func fileManagerFileDetailResource(ctx context.Context, storage filemanager.ObjectStorage, row *filemanager.File, isRootFile bool) responsedto.FileManagerFileDetailResource {
+	urls := resolveFileManagerDownloadURLs(ctx, storage, row)
+	detail := responsedto.FileManagerFileDetailResource{
+		Type: "file_manager_file",
+		ID:   idString(row.ID),
+		Attributes: shareddto.FileManagerFileDetailAttributes{
+			Name:           row.Name,
+			NameNormalized: row.NameNormalized,
+			Extension:      row.Extension,
+			SizeBytes:      row.SizeBytes,
+			MimeType:       row.MimeType,
+			IsTemplate:     row.IsTemplate,
+			DownloadURL:    urls.OriginalURL,
+			PreviewURL:     urls.PreviewURL,
+			Status:         row.Status,
+			Audit: shareddto.FileManagerFileAuditAttributes{
+				CreatedAt: row.CreatedAt.UTC().Format(time.RFC3339),
+				CreatedBy: uuidStringOrEmpty(row.CreatedBy),
+				UpdatedAt: row.UpdatedAt.UTC().Format(time.RFC3339),
+				UpdatedBy: uuidStringOrEmpty(row.UpdatedBy),
+			},
+		},
+	}
+
+	if !isRootFile {
+		folderID := strings.TrimSpace(idString(row.FolderID))
+		if folderID != "" {
+			detail.Attributes.Location = &shareddto.FileManagerFileLocationAttributes{
+				FolderID: folderID,
+			}
+		}
+	}
+
+	processing := shareddto.FileManagerFileProcessingAttributes{
+		ProcessingStartedAt: timeStringOrEmpty(row.ProcessingStartedAt),
+		ProcessedAt:         timeStringOrEmpty(row.ProcessedAt),
+		ValidatedAt:         timeStringOrEmpty(row.ValidatedAt),
+		FailedAt:            timeStringOrEmpty(row.FailedAt),
+		FailureReason:       firstNonEmpty(strings.TrimSpace(row.FailureReason), strings.TrimSpace(row.UploadError)),
+	}
+	if processing.ProcessingStartedAt != "" ||
+		processing.ProcessedAt != "" ||
+		processing.ValidatedAt != "" ||
+		processing.FailedAt != "" ||
+		processing.FailureReason != "" {
+		detail.Attributes.Processing = &processing
+	}
+
+	return detail
+}
+
+func fileManagerFileListResource(ctx context.Context, storage filemanager.ObjectStorage, row *filemanager.File) responsedto.FileManagerFileListResource {
+	return responsedto.FileManagerFileListResource{
+		Type: "file_manager_file",
+		ID:   idString(row.ID),
+		Attributes: shareddto.FileManagerFileListAttributes{
+			Name:           row.Name,
+			NameNormalized: row.NameNormalized,
+			Extension:      row.Extension,
+			SizeBytes:      row.SizeBytes,
+			MimeType:       row.MimeType,
+			IsTemplate:     row.IsTemplate,
+			DownloadURL:    resolveFileManagerDownloadURL(ctx, storage, row),
+			Status:         row.Status,
+			CreatedAt:      row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:      uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:      row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:      uuidStringOrEmpty(row.UpdatedBy),
+		},
+	}
+}
+
+func fileManagerFileUploadIntentResource(grant *filemanager.FileUploadIntentGrant) responsedto.FileManagerFileUploadIntentResource {
+	if grant == nil {
+		return responsedto.FileManagerFileUploadIntentResource{Type: "file_manager_file_upload_intent"}
+	}
+
+	expiresAt := grant.ExpiresAt.UTC()
+	expiresAtRaw := ""
+	expiresInSeconds := int64(0)
+	if !expiresAt.IsZero() {
+		expiresAtRaw = expiresAt.Format(time.RFC3339)
+		expiresInSeconds = int64(time.Until(expiresAt).Seconds())
+		if expiresInSeconds < 0 {
+			expiresInSeconds = 0
+		}
+	}
+
+	attributes := shareddto.FileManagerFileUploadIntentAttributes{
+		UploadIntentID:  idString(grant.UploadIntentID),
+		UploadURL:       strings.TrimSpace(grant.UploadURL),
+		Method:          strings.ToUpper(strings.TrimSpace(grant.Method)),
+		RequiredHeaders: sanitizeUploadRequiredHeaders(grant.Headers),
+		Object: shareddto.FileUploadObject{
+			Bucket: strings.TrimSpace(grant.Bucket),
+			Key:    strings.TrimSpace(grant.ObjectKey),
+		},
+		File: shareddto.FileUploadFile{
+			Name:      strings.TrimSpace(grant.Name),
+			MimeType:  strings.TrimSpace(grant.MimeType),
+			SizeBytes: grant.SizeBytes,
+		},
+		ExpiresAt:        expiresAtRaw,
+		ExpiresInSeconds: expiresInSeconds,
+	}
+
+	return responsedto.FileManagerFileUploadIntentResource{
+		Type:       "file_manager_file_upload_intent",
+		ID:         idString(grant.UploadIntentID),
+		Attributes: attributes,
+	}
+}
+
+func sanitizeUploadRequiredHeaders(headers map[string]string) map[string]string {
+	if len(headers) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(headers))
+	for key, value := range headers {
+		k := strings.TrimSpace(strings.ToLower(key))
+		if k == "" || k == "host" || k == "content-length" || k == "x-amz-meta-file_name" {
+			continue
+		}
+		v := strings.TrimSpace(value)
+		if v == "" {
+			continue
+		}
+		out[k] = v
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func writeFileManagerBulkResponse(c *fiber.Ctx, items []responsedto.FileManagerFileBulkItem) error {
+	normalizeFileManagerBulkItems(items)
+
+	total := len(items)
+	success := 0
+	for i := range items {
+		if items[i].Success {
+			success++
+		}
+	}
+	failed := total - success
+
+	meta := map[string]any{
+		"total":           total,
+		"success":         success,
+		"failed":          failed,
+		"partial_success": success > 0 && failed > 0,
+	}
+
+	statusCode := fiber.StatusOK
+	if failed == 0 {
+		statusCode = fiber.StatusCreated
+	} else if success > 0 {
+		statusCode = fiber.StatusMultiStatus
+	} else if success == 0 && total == 1 {
+		if itemStatus := items[0].Error.Status; itemStatus >= 400 {
+			statusCode = itemStatus
+		}
+	}
+
+	return response.WriteWithMeta(c, statusCode, items, meta)
+}
+
+func writeFileManagerUploadIntentBulkResponse(c *fiber.Ctx, items []responsedto.FileManagerFileUploadIntentBulkItem) error {
+	normalizeFileManagerUploadIntentBulkItems(items)
+
+	total := len(items)
+	success := 0
+	for i := range items {
+		if items[i].Success {
+			success++
+		}
+	}
+	failed := total - success
+
+	meta := map[string]any{
+		"total":           total,
+		"success":         success,
+		"failed":          failed,
+		"partial_success": success > 0 && failed > 0,
+	}
+
+	statusCode := fiber.StatusOK
+	if failed == 0 {
+		statusCode = fiber.StatusCreated
+	} else if success > 0 {
+		statusCode = fiber.StatusMultiStatus
+	} else if success == 0 && total == 1 {
+		if itemStatus := items[0].Error.Status; itemStatus >= 400 {
+			statusCode = itemStatus
+		}
+	}
+
+	return response.WriteWithMeta(c, statusCode, items, meta)
+}
+
+func writeFileManagerCancelUploadBulkResponse(c *fiber.Ctx, items []responsedto.FileManagerFileCancelUploadBulkItem) error {
+	normalizeFileManagerCancelUploadBulkItems(items)
+
+	total := len(items)
+	success := 0
+	for i := range items {
+		if items[i].Success {
+			success++
+		}
+	}
+	failed := total - success
+
+	meta := map[string]any{
+		"total":           total,
+		"success":         success,
+		"failed":          failed,
+		"partial_success": success > 0 && failed > 0,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, items, meta)
+}
+
+func normalizeFileManagerBulkItems(items []responsedto.FileManagerFileBulkItem) {
+	for i := range items {
+		if items[i].Success {
+			items[i].Error = nil
+			if items[i].Resource == nil {
+				items[i].Success = false
+				items[i].Message = ""
+				items[i].Error = &responsedto.FileManagerFileBulkError{
+					Status:    fiber.StatusInternalServerError,
+					Code:      apperrorsx.CodeInternalServerError,
+					ErrorCode: apperrorsx.ErrInternal.ErrorCode,
+					Title:     "Internal error",
+					Detail:    "missing success resource",
+				}
+			}
+			continue
+		}
+
+		items[i].Resource = nil
+		items[i].Message = ""
+		if items[i].Error == nil {
+			items[i].Error = &responsedto.FileManagerFileBulkError{
+				Status:    fiber.StatusInternalServerError,
+				Code:      apperrorsx.CodeInternalServerError,
+				ErrorCode: apperrorsx.ErrInternal.ErrorCode,
+				Title:     "Internal error",
+				Detail:    "missing item error",
+			}
+		}
+	}
+}
+
+func normalizeFileManagerUploadIntentBulkItems(items []responsedto.FileManagerFileUploadIntentBulkItem) {
+	for i := range items {
+		if items[i].Success {
+			items[i].Error = nil
+			if items[i].Resource == nil {
+				items[i].Success = false
+				items[i].Error = &responsedto.FileManagerFileBulkError{
+					Status:    fiber.StatusInternalServerError,
+					Code:      apperrorsx.CodeInternalServerError,
+					ErrorCode: apperrorsx.ErrInternal.ErrorCode,
+					Title:     "Internal error",
+					Detail:    "missing success resource",
+				}
+			}
+			continue
+		}
+
+		items[i].Resource = nil
+		if items[i].Error == nil {
+			items[i].Error = &responsedto.FileManagerFileBulkError{
+				Status:    fiber.StatusInternalServerError,
+				Code:      apperrorsx.CodeInternalServerError,
+				ErrorCode: apperrorsx.ErrInternal.ErrorCode,
+				Title:     "Internal error",
+				Detail:    "missing item error",
+			}
+		}
+	}
+}
+
+func normalizeFileManagerCancelUploadBulkItems(items []responsedto.FileManagerFileCancelUploadBulkItem) {
+	for i := range items {
+		if items[i].Success {
+			items[i].Error = nil
+			if items[i].Resource == nil {
+				items[i].Success = false
+				items[i].Error = &responsedto.FileManagerFileBulkError{
+					Status:    fiber.StatusInternalServerError,
+					Code:      apperrorsx.CodeInternalServerError,
+					ErrorCode: apperrorsx.ErrInternal.ErrorCode,
+					Title:     "Internal error",
+					Detail:    "missing success resource",
+				}
+			}
+			continue
+		}
+
+		items[i].Resource = nil
+		if items[i].Error == nil {
+			items[i].Error = &responsedto.FileManagerFileBulkError{
+				Status:    fiber.StatusInternalServerError,
+				Code:      apperrorsx.CodeInternalServerError,
+				ErrorCode: apperrorsx.ErrInternal.ErrorCode,
+				Title:     "Internal error",
+				Detail:    "missing item error",
+			}
+		}
+	}
+}
+
+func fileManagerBulkSuccessItem(index int, message string, row *filemanager.File) responsedto.FileManagerFileBulkItem {
+	resource := fileManagerFileResource(row)
+	return responsedto.FileManagerFileBulkItem{
+		Index:    index,
+		Success:  true,
+		Message:  message,
+		Resource: &resource,
+	}
+}
+
+func fileManagerBulkSystemErrorItem(index int, status int, title, detail string) responsedto.FileManagerFileBulkItem {
+	def := inferFileManagerDef(status, title, detail)
+	return responsedto.FileManagerFileBulkItem{
+		Index:    index,
+		Success:  false,
+		Resource: nil,
+		Error: &responsedto.FileManagerFileBulkError{
+			Status:    status,
+			Code:      def.Code,
+			ErrorCode: def.ErrorCode,
+			Title:     def.Title,
+			Detail:    def.Message,
+		},
+	}
+}
+
+func missionFileBulkErrorItem(index int, def apperrorsx.Def, detail string) responsedto.FileManagerFileBulkItem {
+	msg := strings.TrimSpace(detail)
+	if msg == "" {
+		msg = def.Message
+	}
+	return responsedto.FileManagerFileBulkItem{
+		Index:    index,
+		Success:  false,
+		Resource: nil,
+		Error: &responsedto.FileManagerFileBulkError{
+			Status:    def.Status,
+			Code:      def.Code,
+			ErrorCode: def.ErrorCode,
+			Title:     def.Title,
+			Detail:    msg,
+		},
+	}
+}
+
+func fileManagerBulkActionErrorItem(index int, action string, err error) responsedto.FileManagerFileBulkItem {
+	def := mapFileManagerActionDef(action, err)
+	statusCode := def.Status
+	item := fileManagerBulkSystemErrorItem(index, statusCode, def.Title, def.Message)
+	if item.Error != nil {
+		item.Error.Code = def.Code
+		item.Error.ErrorCode = def.ErrorCode
+	}
+	return item
+}
+
+func fileManagerUploadIntentBulkSystemErrorItem(index int, status int, title, detail string) responsedto.FileManagerFileUploadIntentBulkItem {
+	def := inferFileManagerDef(status, title, detail)
+	return responsedto.FileManagerFileUploadIntentBulkItem{
+		Index:    index,
+		Success:  false,
+		Resource: nil,
+		Error: &responsedto.FileManagerFileBulkError{
+			Status:    status,
+			Code:      def.Code,
+			ErrorCode: def.ErrorCode,
+			Title:     def.Title,
+			Detail:    def.Message,
+		},
+	}
+}
+
+func fileManagerUploadIntentBulkActionErrorItem(index int, action string, err error) responsedto.FileManagerFileUploadIntentBulkItem {
+	def := mapFileManagerActionDef(action, err)
+	statusCode := def.Status
+	title := def.Title
+	detail := def.Message
+	item := fileManagerUploadIntentBulkSystemErrorItem(index, statusCode, title, detail)
+	if item.Error != nil {
+		item.Error.Code = def.Code
+		item.Error.ErrorCode = def.ErrorCode
+	}
+	return item
+}
+
+func fileManagerCancelUploadBulkSuccessItem(index int, uploadIntentID []byte) responsedto.FileManagerFileCancelUploadBulkItem {
+	resource := responsedto.FileManagerFileCancelUploadResource{
+		Type: "file_manager_file_cancel_upload_result",
+		ID:   idString(uploadIntentID),
+	}
+	resource.Attributes.Status = "canceled"
+
+	return responsedto.FileManagerFileCancelUploadBulkItem{
+		Index:    index,
+		Success:  true,
+		Resource: &resource,
+	}
+}
+
+func fileManagerCancelUploadBulkSystemErrorItem(index int, status int, title, detail string) responsedto.FileManagerFileCancelUploadBulkItem {
+	def := inferFileManagerDef(status, title, detail)
+	return responsedto.FileManagerFileCancelUploadBulkItem{
+		Index:    index,
+		Success:  false,
+		Resource: nil,
+		Error: &responsedto.FileManagerFileBulkError{
+			Status:    status,
+			Code:      def.Code,
+			ErrorCode: def.ErrorCode,
+			Title:     def.Title,
+			Detail:    def.Message,
+		},
+	}
+}
+
+func fileManagerCancelUploadBulkActionErrorItem(index int, action string, err error) responsedto.FileManagerFileCancelUploadBulkItem {
+	def := mapFileManagerActionDef(action, err)
+	statusCode := def.Status
+	title := def.Title
+	detail := def.Message
+	item := fileManagerCancelUploadBulkSystemErrorItem(index, statusCode, title, detail)
+	if item.Error != nil {
+		item.Error.Code = def.Code
+		item.Error.ErrorCode = def.ErrorCode
+	}
+	return item
+}
+
+func (h *FileManagerFileHandler) parseUUIDParam(c *fiber.Ctx, paramName, sourcePointer string) ([]byte, error) {
+	uuidStr := c.Params(paramName)
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return nil, writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", fmt.Sprintf("%s is invalid UUID", paramName), &jsonapi.ErrorSource{Pointer: sourcePointer})
+	}
+	return id, nil
+}
+
+func parseFileManagerFilePagination(c *fiber.Ctx) (pageNumber int, pageSize int, offset int) {
+	pageNumber = parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	pageSize = parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	offset = (pageNumber - 1) * pageSize
+	return
+}
+
+func firstNonEmpty(values ...string) string {
+	for i := range values {
+		if strings.TrimSpace(values[i]) != "" {
+			return values[i]
+		}
+	}
+	return ""
+}
diff --git a/internal/transport/http/handlers/file_manager_file_handler_test.go b/internal/transport/http/handlers/file_manager_file_handler_test.go
new file mode 100644
index 0000000..41ae0b6
--- /dev/null
+++ b/internal/transport/http/handlers/file_manager_file_handler_test.go
@@ -0,0 +1,2201 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/base"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/helicopter"
+	"wucher/internal/shared/pkg/uuidv7"
+	responsedto "wucher/internal/transport/http/dto/response"
+)
+
+type fileManagerFileHandlerServiceMock struct {
+	filemanager.Service
+
+	requestUploadIntentFn func(context.Context, filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error)
+	completeUploadFn      func(context.Context, filemanager.CompleteFileUploadIntentParams) (*filemanager.File, error)
+	cancelUploadFn        func(context.Context, filemanager.CancelFileUploadIntentParams) error
+	createFromIntentFn    func(context.Context, filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error)
+	getOrCreateRootFn     func(context.Context) (*filemanager.Folder, error)
+	getFolderByParentFn   func(context.Context, []byte, string) (*filemanager.Folder, error)
+	createFolderNodeFn    func(context.Context, filemanager.CreateFolderParams) (*filemanager.Folder, error)
+	getFileByIDFn         func(context.Context, []byte) (*filemanager.File, error)
+	getFileByFolderNameFn func(context.Context, []byte, string) (*filemanager.File, error)
+	listFilesByFolderFn   func(context.Context, []byte, string, int, int) ([]filemanager.File, int64, error)
+	listTrashFilesFn      func(context.Context, []byte, string, int, int) ([]filemanager.File, int64, error)
+	moveFileFn            func(context.Context, []byte, filemanager.MoveFileParams) (*filemanager.File, error)
+	deleteFileFn          func(context.Context, []byte, []byte, *time.Time) error
+	purgeFileNodeFn       func(context.Context, []byte) error
+	restoreFileFn         func(context.Context, []byte, []byte, bool, []byte) error
+
+	requestUploadIntentCalls int
+	completeUploadCalls      int
+	cancelUploadCalls        int
+	createFromIntentCalls    int
+
+	lastRequestUploadIntent *filemanager.RequestFileUploadIntentParams
+	lastCompleteUpload      *filemanager.CompleteFileUploadIntentParams
+	lastCancelUpload        *filemanager.CancelFileUploadIntentParams
+	lastCreateFromIntent    *filemanager.CreateFileFromUploadIntentParams
+	lastCreateFolderNode    *filemanager.CreateFolderParams
+}
+
+func (m *fileManagerFileHandlerServiceMock) RequestFileUploadIntent(ctx context.Context, params filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+	m.requestUploadIntentCalls++
+	copied := params
+	copied.ActorID = append([]byte(nil), params.ActorID...)
+	m.lastRequestUploadIntent = &copied
+
+	if m.requestUploadIntentFn != nil {
+		return m.requestUploadIntentFn(ctx, params)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerFileHandlerServiceMock) CompleteFileUploadIntent(ctx context.Context, params filemanager.CompleteFileUploadIntentParams) (*filemanager.File, error) {
+	m.completeUploadCalls++
+	copied := params
+	copied.UploadIntentID = append([]byte(nil), params.UploadIntentID...)
+	copied.ActorID = append([]byte(nil), params.ActorID...)
+	m.lastCompleteUpload = &copied
+
+	if m.completeUploadFn != nil {
+		return m.completeUploadFn(ctx, params)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerFileHandlerServiceMock) CancelFileUploadIntent(ctx context.Context, params filemanager.CancelFileUploadIntentParams) error {
+	m.cancelUploadCalls++
+	copied := params
+	copied.UploadIntentID = append([]byte(nil), params.UploadIntentID...)
+	copied.ActorID = append([]byte(nil), params.ActorID...)
+	m.lastCancelUpload = &copied
+
+	if m.cancelUploadFn != nil {
+		return m.cancelUploadFn(ctx, params)
+	}
+	return nil
+}
+
+func (m *fileManagerFileHandlerServiceMock) CreateFileNodeFromUploadIntent(ctx context.Context, params filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+	m.createFromIntentCalls++
+	copied := params
+	copied.UploadIntentID = append([]byte(nil), params.UploadIntentID...)
+	copied.FolderID = append([]byte(nil), params.FolderID...)
+	copied.ActorID = append([]byte(nil), params.ActorID...)
+	m.lastCreateFromIntent = &copied
+
+	if m.createFromIntentFn != nil {
+		return m.createFromIntentFn(ctx, params)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerFileHandlerServiceMock) GetOrCreateSystemRootFolder(ctx context.Context) (*filemanager.Folder, error) {
+	if m.getOrCreateRootFn != nil {
+		return m.getOrCreateRootFn(ctx)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerFileHandlerServiceMock) GetFolderByParentAndName(ctx context.Context, parentID []byte, nameNormalized string) (*filemanager.Folder, error) {
+	if m.getFolderByParentFn != nil {
+		return m.getFolderByParentFn(ctx, parentID, nameNormalized)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerFileHandlerServiceMock) CreateFolderNode(ctx context.Context, params filemanager.CreateFolderParams) (*filemanager.Folder, error) {
+	copied := params
+	copied.ParentID = append([]byte(nil), params.ParentID...)
+	copied.ActorID = append([]byte(nil), params.ActorID...)
+	m.lastCreateFolderNode = &copied
+
+	if m.createFolderNodeFn != nil {
+		return m.createFolderNodeFn(ctx, params)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerFileHandlerServiceMock) GetFileByID(ctx context.Context, id []byte) (*filemanager.File, error) {
+	if m.getFileByIDFn != nil {
+		return m.getFileByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerFileHandlerServiceMock) GetFileByFolderAndName(ctx context.Context, folderID []byte, nameNormalized string) (*filemanager.File, error) {
+	if m.getFileByFolderNameFn != nil {
+		return m.getFileByFolderNameFn(ctx, folderID, nameNormalized)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerFileHandlerServiceMock) ListFilesByFolder(ctx context.Context, folderID []byte, sort string, limit, offset int) ([]filemanager.File, int64, error) {
+	if m.listFilesByFolderFn != nil {
+		return m.listFilesByFolderFn(ctx, folderID, sort, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func (m *fileManagerFileHandlerServiceMock) ListTrashFilesByFolder(ctx context.Context, folderID []byte, sort string, limit, offset int) ([]filemanager.File, int64, error) {
+	if m.listTrashFilesFn != nil {
+		return m.listTrashFilesFn(ctx, folderID, sort, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func (m *fileManagerFileHandlerServiceMock) MoveFileNode(ctx context.Context, id []byte, params filemanager.MoveFileParams) (*filemanager.File, error) {
+	if m.moveFileFn != nil {
+		return m.moveFileFn(ctx, id, params)
+	}
+	return nil, filemanager.ErrFileNotFound
+}
+
+func (m *fileManagerFileHandlerServiceMock) DeleteFile(ctx context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error {
+	if m.deleteFileFn != nil {
+		return m.deleteFileFn(ctx, id, deletedBy, purgeAt)
+	}
+	return filemanager.ErrFileNotFound
+}
+
+func (m *fileManagerFileHandlerServiceMock) PurgeFileNode(ctx context.Context, id []byte) error {
+	if m.purgeFileNodeFn != nil {
+		return m.purgeFileNodeFn(ctx, id)
+	}
+	return nil
+}
+
+func (m *fileManagerFileHandlerServiceMock) RestoreFile(ctx context.Context, id []byte, targetFolderID []byte, targetProvided bool, restoredBy []byte) error {
+	if m.restoreFileFn != nil {
+		return m.restoreFileFn(ctx, id, targetFolderID, targetProvided, restoredBy)
+	}
+	return filemanager.ErrFileNotFound
+}
+
+type fileManagerFileHandlerAircraftServiceMock struct {
+	helicopter.Service
+	getByIDFn func(context.Context, []byte) (*helicopter.Helicopter, error)
+}
+
+func (m *fileManagerFileHandlerAircraftServiceMock) GetByID(ctx context.Context, id []byte) (*helicopter.Helicopter, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+type fileManagerFileHandlerBaseServiceMock struct {
+	base.Service
+	getByIDFn func(context.Context, []byte, string) (*base.Base, error)
+}
+
+func (m *fileManagerFileHandlerBaseServiceMock) GetBaseByID(ctx context.Context, id []byte, categoryType string) (*base.Base, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id, categoryType)
+	}
+	return nil, nil
+}
+
+func newFileManagerFileHandlerTestApp(h *FileManagerFileHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", append([]byte(nil), actor...))
+		}
+		return c.Next()
+	})
+	app.Post("/api/v1/file-manager/files/create", h.CreateFile)
+	app.Post("/api/v1/file-manager/files/create-aircraft-image", h.CreateAircraftImage)
+	app.Post("/api/v1/file-manager/files/create-base-image", h.CreateBaseImage)
+	app.Post("/api/v1/file-manager/files/create-dul-image", h.CreateDULImage)
+	app.Post("/api/v1/file-manager/files/upload", h.UploadFile)
+	app.Post("/api/v1/file-manager/files/upload-aircraft-image", h.UploadAircraftImage)
+	app.Post("/api/v1/file-manager/files/upload-base-image", h.UploadBaseImage)
+	app.Delete("/api/v1/file-manager/files/cancel-upload", h.CancelUpload)
+	app.Get("/api/v1/file-manager/files/get/:uuid", h.GetFile)
+	app.Get("/api/v1/file-manager/files/get-all", h.ListFiles)
+	app.Get("/api/v1/file-manager/files/trash/get-all", h.ListTrashFiles)
+	app.Patch("/api/v1/file-manager/files/update/:uuid", h.UpdateFile)
+	app.Delete("/api/v1/file-manager/files/delete/:uuid", h.DeleteFile)
+	app.Patch("/api/v1/file-manager/files/restore/:uuid", h.RestoreFile)
+	return app
+}
+
+func newFileManagerFileHandlerInternalCompatTestApp(h *FileManagerFileHandler, actor []byte) *fiber.App {
+	app := newFileManagerFileHandlerTestApp(h, actor)
+	app.Post("/api/v1/file-manager/files/upload/complete", h.CompleteUploadFile)
+	return app
+}
+
+func doJSONRequestFileManagerFile(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read response body: %v", err)
+	}
+
+	return resp, respBody
+}
+
+func decodeJSONMapFileManagerFile(t *testing.T, body []byte) map[string]any {
+	t.Helper()
+
+	var out map[string]any
+	if err := json.Unmarshal(body, &out); err != nil {
+		t.Fatalf("decode json: %v\nbody=%s", err, string(body))
+	}
+	return out
+}
+
+func mapField(t *testing.T, raw any, name string) map[string]any {
+	t.Helper()
+
+	m, ok := raw.(map[string]any)
+	if !ok {
+		t.Fatalf("%s is not object: %#v", name, raw)
+	}
+	return m
+}
+
+func arrayField(t *testing.T, raw any, name string) []any {
+	t.Helper()
+
+	arr, ok := raw.([]any)
+	if !ok {
+		t.Fatalf("%s is not array: %#v", name, raw)
+	}
+	return arr
+}
+
+func stringField(t *testing.T, m map[string]any, key string) string {
+	t.Helper()
+
+	v, ok := m[key]
+	if !ok {
+		t.Fatalf("missing %s", key)
+	}
+	s, ok := v.(string)
+	if !ok {
+		t.Fatalf("%s is not string: %#v", key, v)
+	}
+	return s
+}
+
+func numberField(t *testing.T, m map[string]any, key string) float64 {
+	t.Helper()
+
+	v, ok := m[key]
+	if !ok {
+		t.Fatalf("missing %s", key)
+	}
+	n, ok := v.(float64)
+	if !ok {
+		t.Fatalf("%s is not number: %#v", key, v)
+	}
+	return n
+}
+
+func mustUUIDStringFileManager(t *testing.T, id []byte) string {
+	t.Helper()
+
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestFileManagerFileHandlerUploadFile(t *testing.T) {
+	t.Run("success returns presigned upload intent", func(t *testing.T) {
+		actorID := uuidv7.MustBytes()
+		uploadIntentID := uuidv7.MustBytes()
+		expiresAt := time.Now().UTC().Add(15 * time.Minute)
+
+		svc := &fileManagerFileHandlerServiceMock{
+			requestUploadIntentFn: func(_ context.Context, _ filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+				return &filemanager.FileUploadIntentGrant{
+					UploadIntentID: uploadIntentID,
+					Bucket:         "wucher-file-dev",
+					ObjectKey:      "files/2026/04/05/test-policy.pdf",
+					Name:           "policy.pdf",
+					MimeType:       "application/pdf",
+					SizeBytes:      1024,
+					Method:         "put",
+					UploadURL:      "https://s3.localhost.localstack.cloud:4566/wucher-file-dev/files/2026/04/05/test-policy.pdf",
+					Headers: map[string]string{
+						"Content-Type": "application/pdf",
+					},
+					ExpiresAt: expiresAt,
+				}, nil
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, actorID)
+
+		body := []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"policy.pdf","content_type":"application/pdf","size_bytes":1024}}]}`)
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+
+		if svc.lastRequestUploadIntent == nil {
+			t.Fatalf("expected request upload intent to be called")
+		}
+		if svc.lastRequestUploadIntent.Name != "policy.pdf" {
+			t.Fatalf("unexpected name: %q", svc.lastRequestUploadIntent.Name)
+		}
+		if svc.lastRequestUploadIntent.ContentType != "application/pdf" {
+			t.Fatalf("unexpected content_type: %q", svc.lastRequestUploadIntent.ContentType)
+		}
+		if svc.lastRequestUploadIntent.SizeBytes != 1024 {
+			t.Fatalf("unexpected size_bytes: %d", svc.lastRequestUploadIntent.SizeBytes)
+		}
+		if !bytes.Equal(svc.lastRequestUploadIntent.ActorID, actorID) {
+			t.Fatalf("unexpected actor_id")
+		}
+
+		payload := decodeJSONMapFileManagerFile(t, respBody)
+		dataItems := arrayField(t, payload["data"], "data")
+		if len(dataItems) != 1 {
+			t.Fatalf("expected one data item, got %d", len(dataItems))
+		}
+		item := mapField(t, dataItems[0], "data[0]")
+		if v, ok := item["success"].(bool); !ok || !v {
+			t.Fatalf("expected success=true, got %#v", item["success"])
+		}
+		resource := mapField(t, item["resource"], "data[0].resource")
+		attrs := mapField(t, resource["attributes"], "data[0].resource.attributes")
+
+		if got := stringField(t, resource, "type"); got != "file_manager_file_upload_intent" {
+			t.Fatalf("unexpected data[0].resource.type: %q", got)
+		}
+
+		if got := stringField(t, attrs, "upload_intent_uuid"); got == "" {
+			t.Fatalf("upload_intent_uuid should not be empty")
+		}
+		if got := stringField(t, attrs, "upload_url"); got == "" {
+			t.Fatalf("upload_url should not be empty")
+		}
+		if got := stringField(t, attrs, "method"); got != "PUT" {
+			t.Fatalf("unexpected method: %q", got)
+		}
+		object := mapField(t, attrs["object"], "data.attributes.object")
+		if got := stringField(t, object, "bucket"); got != "wucher-file-dev" {
+			t.Fatalf("unexpected bucket: %q", got)
+		}
+		if got := stringField(t, object, "key"); got == "" {
+			t.Fatalf("object.key should not be empty")
+		}
+		if got := stringField(t, attrs, "expires_at"); got == "" {
+			t.Fatalf("expires_at should not be empty")
+		}
+		fileInfo := mapField(t, attrs["file"], "data.attributes.file")
+		if got := stringField(t, fileInfo, "name"); got != "policy.pdf" {
+			t.Fatalf("unexpected file.name: %q", got)
+		}
+		if got := stringField(t, fileInfo, "mime_type"); got != "application/pdf" {
+			t.Fatalf("unexpected file.mime_type: %q", got)
+		}
+		if got := numberField(t, fileInfo, "size_bytes"); got != 1024 {
+			t.Fatalf("unexpected file.size_bytes in response: %.0f", got)
+		}
+		expiresIn := numberField(t, attrs, "expires_in_seconds")
+		if expiresIn <= 0 || expiresIn > 900 {
+			t.Fatalf("unexpected expires_in_seconds: %v", expiresIn)
+		}
+
+		headers := mapField(t, attrs["required_headers"], "data.attributes.required_headers")
+		if got := stringField(t, headers, "content-type"); got != "application/pdf" {
+			t.Fatalf("unexpected required_headers.content-type: %q", got)
+		}
+
+		meta := mapField(t, payload["meta"], "meta")
+		if got := numberField(t, meta, "total"); got != 1 {
+			t.Fatalf("unexpected meta.total: %.0f", got)
+		}
+		if got := numberField(t, meta, "success"); got != 1 {
+			t.Fatalf("unexpected meta.success: %.0f", got)
+		}
+		if got := numberField(t, meta, "failed"); got != 0 {
+			t.Fatalf("unexpected meta.failed: %.0f", got)
+		}
+	})
+
+	t.Run("invalid body returns 422", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, nil)
+
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+		if svc.requestUploadIntentCalls != 0 {
+			t.Fatalf("request upload intent should not be called")
+		}
+	})
+
+	t.Run("storage unavailable maps to 503", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{
+			requestUploadIntentFn: func(context.Context, filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+				return nil, filemanager.ErrStorageUnavailable
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, nil)
+
+		body := []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"policy.pdf","content_type":"application/pdf","size_bytes":1024}}]}`)
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload", body)
+		if resp.StatusCode != http.StatusServiceUnavailable {
+			t.Fatalf("expected 503, got %d", resp.StatusCode)
+		}
+
+		payload := decodeJSONMapFileManagerFile(t, respBody)
+		dataItems := arrayField(t, payload["data"], "data")
+		if len(dataItems) != 1 {
+			t.Fatalf("expected one data item, got %d", len(dataItems))
+		}
+		item := mapField(t, dataItems[0], "data[0]")
+		errObj := mapField(t, item["error"], "data[0].error")
+		if got := numberField(t, errObj, "status"); got != 503 {
+			t.Fatalf("expected item error status 503, got %.0f", got)
+		}
+	})
+
+	t.Run("partial success returns 207", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{
+			requestUploadIntentFn: func(_ context.Context, _ filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+				return &filemanager.FileUploadIntentGrant{
+					UploadIntentID: uuidv7.MustBytes(),
+					Bucket:         "wucher-file-dev",
+					ObjectKey:      "files/2026/04/05/test-policy.pdf",
+					Name:           "policy.pdf",
+					MimeType:       "application/pdf",
+					SizeBytes:      1024,
+					Method:         "PUT",
+					UploadURL:      "https://example.local/upload",
+					ExpiresAt:      time.Now().UTC().Add(15 * time.Minute),
+				}, nil
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, nil)
+
+		body := []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"policy.pdf","content_type":"application/pdf","size_bytes":1024}},{"type":"invalid_type","attributes":{"name":"bad.pdf","content_type":"application/pdf","size_bytes":1}}]}`)
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload", body)
+		if resp.StatusCode != http.StatusMultiStatus {
+			t.Fatalf("expected 207, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		payload := decodeJSONMapFileManagerFile(t, respBody)
+		meta := mapField(t, payload["meta"], "meta")
+		if partial, ok := meta["partial_success"].(bool); !ok || !partial {
+			t.Fatalf("expected meta.partial_success=true, got %#v", meta["partial_success"])
+		}
+	})
+}
+
+func TestFileManagerFileHandlerCompleteUploadFile(t *testing.T) {
+	t.Run("success completes upload intent", func(t *testing.T) {
+		actorID := uuidv7.MustBytes()
+		uploadIntentID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		folderID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+
+		svc := &fileManagerFileHandlerServiceMock{
+			completeUploadFn: func(_ context.Context, _ filemanager.CompleteFileUploadIntentParams) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:             fileID,
+					FolderID:       folderID,
+					Name:           "policy.pdf",
+					NameNormalized: "policy.pdf",
+					Extension:      "pdf",
+					SizeBytes:      1024,
+					MimeType:       "application/pdf",
+					Status:         filemanager.FileStatusUploaded,
+					CreatedAt:      now,
+					CreatedBy:      actorID,
+					UpdatedAt:      now,
+					UpdatedBy:      actorID,
+				}, nil
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerInternalCompatTestApp(h, actorID)
+
+		uploadIntentUUID, err := uuidv7.BytesToString(uploadIntentID)
+		if err != nil {
+			t.Fatalf("upload intent uuid string: %v", err)
+		}
+		body := []byte(`{"data":{"type":"file_manager_file_upload_complete","attributes":{"upload_intent_uuid":"` + uploadIntentUUID + `"}}}`)
+
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload/complete", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+
+		if svc.lastCompleteUpload == nil {
+			t.Fatalf("expected complete upload to be called")
+		}
+		if !bytes.Equal(svc.lastCompleteUpload.UploadIntentID, uploadIntentID) {
+			t.Fatalf("unexpected upload_intent_id")
+		}
+		if !bytes.Equal(svc.lastCompleteUpload.ActorID, actorID) {
+			t.Fatalf("unexpected actor_id")
+		}
+
+		payload := decodeJSONMapFileManagerFile(t, respBody)
+		data := mapField(t, payload["data"], "data")
+		attrs := mapField(t, data["attributes"], "data.attributes")
+		if got := stringField(t, data, "type"); got != "file_manager_file" {
+			t.Fatalf("unexpected data.type: %q", got)
+		}
+		if got := stringField(t, attrs, "status"); got != filemanager.FileStatusUploaded {
+			t.Fatalf("unexpected file status: %q", got)
+		}
+		if got := numberField(t, attrs, "size_bytes"); got != 1024 {
+			t.Fatalf("unexpected size_bytes: %.0f", got)
+		}
+	})
+
+	t.Run("invalid upload_intent_uuid returns 422", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerInternalCompatTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"file_manager_file_upload_complete","attributes":{"upload_intent_uuid":"not-uuid"}}}`)
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload/complete", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+		if svc.completeUploadCalls != 0 {
+			t.Fatalf("complete upload should not be called")
+		}
+	})
+
+	t.Run("upload intent not found maps to 404", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{
+			completeUploadFn: func(context.Context, filemanager.CompleteFileUploadIntentParams) (*filemanager.File, error) {
+				return nil, filemanager.ErrUploadIntentNotFound
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerInternalCompatTestApp(h, nil)
+
+		uploadIntentUUID := mustUUIDStringFileManager(t, uuidv7.MustBytes())
+		body := []byte(`{"data":{"type":"file_manager_file_upload_complete","attributes":{"upload_intent_uuid":"` + uploadIntentUUID + `"}}}`)
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload/complete", body)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("object mismatch maps to 422", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{
+			completeUploadFn: func(context.Context, filemanager.CompleteFileUploadIntentParams) (*filemanager.File, error) {
+				return nil, filemanager.ErrUploadObjectMismatch
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerInternalCompatTestApp(h, nil)
+
+		uploadIntentUUID := mustUUIDStringFileManager(t, uuidv7.MustBytes())
+		body := []byte(`{"data":{"type":"file_manager_file_upload_complete","attributes":{"upload_intent_uuid":"` + uploadIntentUUID + `"}}}`)
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload/complete", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("expired upload intent maps to 409", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{
+			completeUploadFn: func(context.Context, filemanager.CompleteFileUploadIntentParams) (*filemanager.File, error) {
+				return nil, filemanager.ErrUploadIntentExpired
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerInternalCompatTestApp(h, nil)
+
+		uploadIntentUUID := mustUUIDStringFileManager(t, uuidv7.MustBytes())
+		body := []byte(`{"data":{"type":"file_manager_file_upload_complete","attributes":{"upload_intent_uuid":"` + uploadIntentUUID + `"}}}`)
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload/complete", body)
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestFileManagerFileHandlerCreateFile_FromUploadIntent(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		actorID := uuidv7.MustBytes()
+		uploadIntentID := uuidv7.MustBytes()
+		folderID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+
+		svc := &fileManagerFileHandlerServiceMock{
+			createFromIntentFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:             fileID,
+					FolderID:       folderID,
+					Name:           "policy-final.pdf",
+					NameNormalized: "policy-final.pdf",
+					Extension:      "pdf",
+					SizeBytes:      1024,
+					MimeType:       "application/pdf",
+					Status:         filemanager.FileStatusUploaded,
+					CreatedAt:      now,
+					CreatedBy:      actorID,
+					UpdatedAt:      now,
+					UpdatedBy:      actorID,
+				}, nil
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, actorID)
+
+		body := []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"` + mustUUIDStringFileManager(t, uploadIntentID) + `","folder_id":"` + mustUUIDStringFileManager(t, folderID) + `","name":"policy-final.pdf"}}]}`)
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		if svc.createFromIntentCalls != 1 {
+			t.Fatalf("expected create from intent called once, got %d", svc.createFromIntentCalls)
+		}
+		if svc.lastCreateFromIntent == nil {
+			t.Fatalf("expected create params")
+		}
+		if !bytes.Equal(svc.lastCreateFromIntent.UploadIntentID, uploadIntentID) {
+			t.Fatalf("unexpected upload intent id")
+		}
+		if !bytes.Equal(svc.lastCreateFromIntent.FolderID, folderID) {
+			t.Fatalf("unexpected folder id")
+		}
+		if svc.lastCreateFromIntent.Name != "policy-final.pdf" {
+			t.Fatalf("unexpected name: %q", svc.lastCreateFromIntent.Name)
+		}
+		if svc.lastCreateFromIntent.IsTemplate {
+			t.Fatalf("expected create-from-template flow to keep is_template=false")
+		}
+	})
+
+	t.Run("folder omitted defaults to root semantics", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{
+			createFromIntentFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return &filemanager.File{ID: uuidv7.MustBytes(), FolderID: uuidv7.MustBytes(), Name: "policy.pdf", NameNormalized: "policy.pdf", Status: filemanager.FileStatusUploaded, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, uuidv7.MustBytes())
+
+		body := []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"` + mustUUIDStringFileManager(t, uuidv7.MustBytes()) + `","name":"policy.pdf"}}]}`)
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if svc.lastCreateFromIntent == nil {
+			t.Fatalf("expected create params")
+		}
+		if svc.lastCreateFromIntent.FolderProvided {
+			t.Fatalf("expected folder_provided=false when folder_id omitted")
+		}
+	})
+
+	t.Run("invalid upload_intent_uuid returns 422", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, nil)
+
+		body := []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"bad-uuid","name":"policy.pdf"}}]}`)
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+
+		payload := decodeJSONMapFileManagerFile(t, respBody)
+		dataItems := arrayField(t, payload["data"], "data")
+		if len(dataItems) != 1 {
+			t.Fatalf("expected one data item, got %d", len(dataItems))
+		}
+		item := mapField(t, dataItems[0], "data[0]")
+		errObj := mapField(t, item["error"], "data[0].error")
+		if got := numberField(t, errObj, "status"); got != 422 {
+			t.Fatalf("expected item error status 422, got %.0f", got)
+		}
+		if svc.createFromIntentCalls != 0 {
+			t.Fatalf("create should not be called on invalid uuid")
+		}
+	})
+
+	t.Run("partial success returns 207", func(t *testing.T) {
+		uploadIntentID := uuidv7.MustBytes()
+		folderID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+
+		svc := &fileManagerFileHandlerServiceMock{
+			createFromIntentFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:             uuidv7.MustBytes(),
+					FolderID:       folderID,
+					Name:           "ok.pdf",
+					NameNormalized: "ok.pdf",
+					Extension:      "pdf",
+					SizeBytes:      100,
+					MimeType:       "application/pdf",
+					Status:         filemanager.FileStatusUploaded,
+					CreatedAt:      now,
+					UpdatedAt:      now,
+				}, nil
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, nil)
+
+		body := []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"` + mustUUIDStringFileManager(t, uploadIntentID) + `","name":"ok.pdf"}},{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"bad-uuid","name":"bad.pdf"}}]}`)
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create", body)
+		if resp.StatusCode != http.StatusMultiStatus {
+			t.Fatalf("expected 207, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		payload := decodeJSONMapFileManagerFile(t, respBody)
+		meta := mapField(t, payload["meta"], "meta")
+		if partial, ok := meta["partial_success"].(bool); !ok || !partial {
+			t.Fatalf("expected meta.partial_success=true, got %#v", meta["partial_success"])
+		}
+	})
+}
+
+func TestFileManagerFileHandlerCreateAircraftImage(t *testing.T) {
+	t.Run("success stores file under root-aircraft-designation hierarchy", func(t *testing.T) {
+		actorID := uuidv7.MustBytes()
+		aircraftID := uuidv7.MustBytes()
+		uploadIntentID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		aircraftFolderID := uuidv7.MustBytes()
+		designationFolderID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+
+		svc := &fileManagerFileHandlerServiceMock{
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: rootID, Name: filemanager.SystemRootFolderName, NameNormalized: filemanager.SystemRootFolderName}, nil
+			},
+			getFolderByParentFn: func(_ context.Context, parentID []byte, nameNormalized string) (*filemanager.Folder, error) {
+				if bytes.Equal(parentID, rootID) && nameNormalized == "aircraft" {
+					return &filemanager.Folder{ID: aircraftFolderID, ParentID: rootID, Name: "aircraft", NameNormalized: "aircraft"}, nil
+				}
+				if bytes.Equal(parentID, aircraftFolderID) && nameNormalized == "oe-xhz" {
+					return &filemanager.Folder{ID: designationFolderID, ParentID: aircraftFolderID, Name: "OE-XHZ", NameNormalized: "oe-xhz"}, nil
+				}
+				return nil, nil
+			},
+			createFromIntentFn: func(_ context.Context, params filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				if !bytes.Equal(params.FolderID, designationFolderID) {
+					t.Fatalf("expected designation folder id used, got %x", params.FolderID)
+				}
+				return &filemanager.File{
+					ID:             fileID,
+					FolderID:       designationFolderID,
+					Name:           "xhz.png",
+					NameNormalized: "xhz.png",
+					Extension:      "png",
+					SizeBytes:      1024,
+					MimeType:       "image/png",
+					Status:         filemanager.FileStatusUploaded,
+					CreatedAt:      now,
+					UpdatedAt:      now,
+					CreatedBy:      actorID,
+					UpdatedBy:      actorID,
+				}, nil
+			},
+		}
+
+		aircraftSvc := &fileManagerFileHandlerAircraftServiceMock{
+			getByIDFn: func(_ context.Context, id []byte) (*helicopter.Helicopter, error) {
+				if !bytes.Equal(id, aircraftID) {
+					t.Fatalf("unexpected aircraft id: %x", id)
+				}
+				return &helicopter.Helicopter{ID: aircraftID, Designation: "OE-XHZ"}, nil
+			},
+		}
+
+		h := NewFileManagerFileHandler(svc, nil).WithAircraftService(aircraftSvc)
+		app := newFileManagerFileHandlerTestApp(h, actorID)
+
+		body := []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"` + mustUUIDStringFileManager(t, uploadIntentID) + `","aircraft_uuid":"` + mustUUIDStringFileManager(t, aircraftID) + `","name":"xhz.png"}}]}`)
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		if svc.lastCreateFromIntent == nil {
+			t.Fatalf("expected create from upload intent called")
+		}
+		if !bytes.Equal(svc.lastCreateFromIntent.FolderID, designationFolderID) {
+			t.Fatalf("unexpected folder id used: %x", svc.lastCreateFromIntent.FolderID)
+		}
+	})
+
+	t.Run("invalid aircraft_uuid returns per-item validation error", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{}
+		aircraftSvc := &fileManagerFileHandlerAircraftServiceMock{}
+		h := NewFileManagerFileHandler(svc, nil).WithAircraftService(aircraftSvc)
+		app := newFileManagerFileHandlerTestApp(h, uuidv7.MustBytes())
+
+		body := []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"` + mustUUIDStringFileManager(t, uuidv7.MustBytes()) + `","aircraft_uuid":"bad-uuid","name":"xhz.png"}}]}`)
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		payload := decodeJSONMapFileManagerFile(t, respBody)
+		dataItems := arrayField(t, payload["data"], "data")
+		item := mapField(t, dataItems[0], "data[0]")
+		errObj := mapField(t, item["error"], "data[0].error")
+		if got := numberField(t, errObj, "status"); got != 422 {
+			t.Fatalf("expected item error status 422, got %.0f", got)
+		}
+		if svc.createFromIntentCalls != 0 {
+			t.Fatalf("create should not be called")
+		}
+	})
+
+	t.Run("replaces existing file with same name in designation folder", func(t *testing.T) {
+		actorID := uuidv7.MustBytes()
+		aircraftID := uuidv7.MustBytes()
+		uploadIntentID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		aircraftFolderID := uuidv7.MustBytes()
+		designationFolderID := uuidv7.MustBytes()
+		oldFileID := uuidv7.MustBytes()
+		newFileID := uuidv7.MustBytes()
+
+		deleteCalls := 0
+		purgeCalls := 0
+		svc := &fileManagerFileHandlerServiceMock{
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: rootID, Name: filemanager.SystemRootFolderName, NameNormalized: filemanager.SystemRootFolderName}, nil
+			},
+			getFolderByParentFn: func(_ context.Context, parentID []byte, nameNormalized string) (*filemanager.Folder, error) {
+				if bytes.Equal(parentID, rootID) && nameNormalized == "aircraft" {
+					return &filemanager.Folder{ID: aircraftFolderID, ParentID: rootID, Name: "aircraft", NameNormalized: "aircraft"}, nil
+				}
+				if bytes.Equal(parentID, aircraftFolderID) && nameNormalized == "oe-abc" {
+					return &filemanager.Folder{ID: designationFolderID, ParentID: aircraftFolderID, Name: "OE-ABC", NameNormalized: "oe-abc"}, nil
+				}
+				return nil, nil
+			},
+			listFilesByFolderFn: func(_ context.Context, folderID []byte, sort string, limit, offset int) ([]filemanager.File, int64, error) {
+				if !bytes.Equal(folderID, designationFolderID) {
+					t.Fatalf("unexpected folder id lookup: %x", folderID)
+				}
+				if sort != "name ASC" {
+					t.Fatalf("unexpected sort: %s", sort)
+				}
+				return []filemanager.File{{
+					ID:             oldFileID,
+					FolderID:       designationFolderID,
+					Name:           "photo.png",
+					NameNormalized: "photo.png",
+				}}, 1, nil
+			},
+			deleteFileFn: func(_ context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error {
+				deleteCalls++
+				if !bytes.Equal(id, oldFileID) {
+					t.Fatalf("unexpected deleted file id: %x", id)
+				}
+				if !bytes.Equal(deletedBy, actorID) {
+					t.Fatalf("unexpected actor on delete: %x", deletedBy)
+				}
+				if purgeAt == nil {
+					t.Fatalf("expected purgeAt to force immediate purge")
+				}
+				return nil
+			},
+			purgeFileNodeFn: func(_ context.Context, id []byte) error {
+				purgeCalls++
+				if !bytes.Equal(id, oldFileID) {
+					t.Fatalf("unexpected purged file id: %x", id)
+				}
+				return nil
+			},
+			createFromIntentFn: func(_ context.Context, params filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				if !bytes.Equal(params.FolderID, designationFolderID) {
+					t.Fatalf("expected designation folder id used, got %x", params.FolderID)
+				}
+				return &filemanager.File{
+					ID:             newFileID,
+					FolderID:       designationFolderID,
+					Name:           "photo.png",
+					NameNormalized: "photo.png",
+					Extension:      "png",
+					MimeType:       "image/png",
+					Status:         filemanager.FileStatusUploaded,
+					CreatedAt:      time.Now().UTC(),
+					UpdatedAt:      time.Now().UTC(),
+					CreatedBy:      actorID,
+					UpdatedBy:      actorID,
+				}, nil
+			},
+		}
+		aircraftSvc := &fileManagerFileHandlerAircraftServiceMock{
+			getByIDFn: func(_ context.Context, id []byte) (*helicopter.Helicopter, error) {
+				if !bytes.Equal(id, aircraftID) {
+					t.Fatalf("unexpected aircraft id: %x", id)
+				}
+				return &helicopter.Helicopter{ID: aircraftID, Designation: "OE-ABC"}, nil
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil).WithAircraftService(aircraftSvc)
+		app := newFileManagerFileHandlerTestApp(h, actorID)
+
+		body := []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"` + mustUUIDStringFileManager(t, uploadIntentID) + `","aircraft_uuid":"` + mustUUIDStringFileManager(t, aircraftID) + `","name":"photo.png"}}]}`)
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		if deleteCalls != 1 {
+			t.Fatalf("expected delete old file called once, got %d", deleteCalls)
+		}
+		if purgeCalls != 1 {
+			t.Fatalf("expected purge old file called once, got %d", purgeCalls)
+		}
+		if svc.createFromIntentCalls != 1 {
+			t.Fatalf("expected create called once, got %d", svc.createFromIntentCalls)
+		}
+	})
+}
+
+func TestFileManagerFileHandlerCreateDULImage_WithoutDULUUID(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	uploadIntentID := uuidv7.MustBytes()
+	createdID := uuidv7.MustBytes()
+
+	svc := &fileManagerFileHandlerServiceMock{
+		createFromIntentFn: func(_ context.Context, params filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+			if params.FolderProvided {
+				t.Fatalf("expected FolderProvided=false when dul_uuid omitted")
+			}
+			if params.Name != "shared image.jpeg" {
+				t.Fatalf("unexpected name: %s", params.Name)
+			}
+			return &filemanager.File{
+				ID:        createdID,
+				Name:      params.Name,
+				ObjectKey: "objects/shared-image.jpeg",
+				Status:    filemanager.FileStatusUploaded,
+			}, nil
+		},
+	}
+
+	h := NewFileManagerFileHandler(svc, nil)
+	app := newFileManagerFileHandlerTestApp(h, actorID)
+
+	body := []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"name":"shared image.jpeg","upload_intent_uuid":"` + mustUUIDStringFileManager(t, uploadIntentID) + `"}}]}`)
+	resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-dul-image", body)
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201, got %d body=%s", resp.StatusCode, string(respBody))
+	}
+
+	var out responsedto.FileManagerFileBulkResponse
+	if err := json.Unmarshal(respBody, &out); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+	if len(out.Data) != 1 || !out.Data[0].Success {
+		t.Fatalf("expected one successful item, got %+v", out.Data)
+	}
+	if svc.createFromIntentCalls != 1 {
+		t.Fatalf("expected createFromIntent called once, got %d", svc.createFromIntentCalls)
+	}
+}
+
+func TestFileManagerFileHandlerBaseImageFlow(t *testing.T) {
+	t.Run("upload base image rejects non-array and empty array payload", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-base-image", []byte(`{"data":{"type":"file_manager_file_upload_intent","attributes":{"name":"a.png","content_type":"image/png","size_bytes":1}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 non-array payload, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-base-image", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 empty array, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("upload base image validates image content type", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-base-image", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"base.pdf","content_type":"application/pdf","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid base image content type, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("upload base image validates type, name, content type, and size", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-base-image", []byte(`{"data":[{"type":"wrong","attributes":{"name":"a.png","content_type":"image/png","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 wrong type, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-base-image", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"","content_type":"image/png","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 missing name, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-base-image", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"a.png","content_type":"","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 missing content_type, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-base-image", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"a.png","content_type":"image/png","size_bytes":-1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid size_bytes, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("upload base image success and action error", func(t *testing.T) {
+		actorID := uuidv7.MustBytes()
+		svc := &fileManagerFileHandlerServiceMock{
+			requestUploadIntentFn: func(_ context.Context, params filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+				if params.ContentType == "image/bad" {
+					return nil, errors.New("upload intent failed")
+				}
+				return &filemanager.FileUploadIntentGrant{
+					UploadIntentID: uuidv7.MustBytes(),
+					Name:           params.Name,
+					MimeType:       params.ContentType,
+					SizeBytes:      params.SizeBytes,
+					UploadURL:      "https://upload.example/base",
+				}, nil
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, actorID)
+
+		okBody := []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"base.png","content_type":"image/png","size_bytes":12}}]}`)
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-base-image", okBody)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+
+		failBody := []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"base.png","content_type":"image/bad","size_bytes":12}}]}`)
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-base-image", failBody)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 action error, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create base image resolves forced folder and performs hard replace", func(t *testing.T) {
+		actorID := uuidv7.MustBytes()
+		baseID := uuidv7.MustBytes()
+		uploadIntentID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		basesFolderID := uuidv7.MustBytes()
+		baseTypeFolderID := uuidv7.MustBytes()
+		baseNameFolderID := uuidv7.MustBytes()
+		oldFileID := uuidv7.MustBytes()
+		newFileID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+
+		var deleteCalls int
+		var purgeCalls int
+
+		svc := &fileManagerFileHandlerServiceMock{
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: rootID, Name: filemanager.SystemRootFolderName, NameNormalized: filemanager.SystemRootFolderName}, nil
+			},
+			getFolderByParentFn: func(_ context.Context, parentID []byte, nameNormalized string) (*filemanager.Folder, error) {
+				if bytes.Equal(parentID, rootID) && nameNormalized == "bases" {
+					return &filemanager.Folder{ID: basesFolderID, ParentID: rootID, Name: "bases", NameNormalized: "bases"}, nil
+				}
+				if bytes.Equal(parentID, basesFolderID) && nameNormalized == base.CategoryKeyHEMS {
+					return &filemanager.Folder{ID: baseTypeFolderID, ParentID: basesFolderID, Name: base.CategoryKeyHEMS, NameNormalized: base.CategoryKeyHEMS}, nil
+				}
+				if bytes.Equal(parentID, baseTypeFolderID) && nameNormalized == "hems 1" {
+					return &filemanager.Folder{ID: baseNameFolderID, ParentID: baseTypeFolderID, Name: "HEMS 1", NameNormalized: "hems 1"}, nil
+				}
+				return nil, nil
+			},
+			listFilesByFolderFn: func(_ context.Context, folderID []byte, _ string, _, _ int) ([]filemanager.File, int64, error) {
+				if !bytes.Equal(folderID, baseNameFolderID) {
+					t.Fatalf("expected list to use base-name folder")
+				}
+				return []filemanager.File{{ID: oldFileID, FolderID: folderID, Name: "old.png"}}, 1, nil
+			},
+			deleteFileFn: func(_ context.Context, id []byte, _ []byte, _ *time.Time) error {
+				if !bytes.Equal(id, oldFileID) {
+					t.Fatalf("expected delete old file id")
+				}
+				deleteCalls++
+				return nil
+			},
+			purgeFileNodeFn: func(_ context.Context, id []byte) error {
+				if !bytes.Equal(id, oldFileID) {
+					t.Fatalf("expected purge old file id")
+				}
+				purgeCalls++
+				return nil
+			},
+			createFromIntentFn: func(_ context.Context, params filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				if !bytes.Equal(params.FolderID, baseNameFolderID) {
+					t.Fatalf("expected create to use base-name folder")
+				}
+				if !bytes.Equal(params.UploadIntentID, uploadIntentID) {
+					t.Fatalf("unexpected upload intent")
+				}
+				return &filemanager.File{
+					ID:             newFileID,
+					FolderID:       baseNameFolderID,
+					Name:           "new.png",
+					NameNormalized: "new.png",
+					Extension:      "png",
+					SizeBytes:      100,
+					MimeType:       "image/png",
+					Status:         filemanager.FileStatusUploaded,
+					CreatedAt:      now,
+					UpdatedAt:      now,
+				}, nil
+			},
+		}
+		baseSvc := &fileManagerFileHandlerBaseServiceMock{
+			getByIDFn: func(_ context.Context, id []byte, categoryType string) (*base.Base, error) {
+				if !bytes.Equal(id, baseID) {
+					return nil, nil
+				}
+				if categoryType == base.CategoryKeyHEMS {
+					return &base.Base{ID: id, BaseName: "HEMS 1"}, nil
+				}
+				return nil, nil
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil).WithBaseService(baseSvc)
+		app := newFileManagerFileHandlerTestApp(h, actorID)
+
+		body := []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"` + mustUUIDStringFileManager(t, uploadIntentID) + `","name":"new.png","base_uuid":"` + mustUUIDStringFileManager(t, baseID) + `"}}]}`)
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-base-image", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201 base image create, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		if deleteCalls != 1 || purgeCalls != 1 {
+			t.Fatalf("expected hard replace delete+purge once, got delete=%d purge=%d", deleteCalls, purgeCalls)
+		}
+	})
+}
+
+func TestFileManagerFileHandlerCancelUpload(t *testing.T) {
+	t.Run("success cancels upload intent in bulk", func(t *testing.T) {
+		actorID := uuidv7.MustBytes()
+		intentID := uuidv7.MustBytes()
+
+		svc := &fileManagerFileHandlerServiceMock{}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, actorID)
+
+		body := []byte(`{"data":[{"type":"file_manager_file_cancel_upload","attributes":{"upload_intent_uuid":"` + mustUUIDStringFileManager(t, intentID) + `"}}]}`)
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/files/cancel-upload", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		if svc.cancelUploadCalls != 1 {
+			t.Fatalf("expected cancel called once, got %d", svc.cancelUploadCalls)
+		}
+		if svc.lastCancelUpload == nil {
+			t.Fatalf("expected cancel params")
+		}
+		if !bytes.Equal(svc.lastCancelUpload.UploadIntentID, intentID) {
+			t.Fatalf("unexpected upload_intent_id")
+		}
+		if !bytes.Equal(svc.lastCancelUpload.ActorID, actorID) {
+			t.Fatalf("unexpected actor_id")
+		}
+
+		payload := decodeJSONMapFileManagerFile(t, respBody)
+		items := arrayField(t, payload["data"], "data")
+		if len(items) != 1 {
+			t.Fatalf("expected one item, got %d", len(items))
+		}
+		item := mapField(t, items[0], "data[0]")
+		if v, ok := item["success"].(bool); !ok || !v {
+			t.Fatalf("expected success=true, got %#v", item["success"])
+		}
+		resource := mapField(t, item["resource"], "resource")
+		if got := stringField(t, resource, "type"); got != "file_manager_file_cancel_upload_result" {
+			t.Fatalf("unexpected resource type %q", got)
+		}
+		attrs := mapField(t, resource["attributes"], "attributes")
+		if got := stringField(t, attrs, "status"); got != "canceled" {
+			t.Fatalf("unexpected status %q", got)
+		}
+	})
+
+	t.Run("invalid item type returns item validation error", func(t *testing.T) {
+		svc := &fileManagerFileHandlerServiceMock{}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, nil)
+
+		body := []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"upload_intent_uuid":"` + mustUUIDStringFileManager(t, uuidv7.MustBytes()) + `"}}]}`)
+		resp, respBody := doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/files/cancel-upload", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		if svc.cancelUploadCalls != 0 {
+			t.Fatalf("cancel should not be called on invalid type")
+		}
+		payload := decodeJSONMapFileManagerFile(t, respBody)
+		items := arrayField(t, payload["data"], "data")
+		item := mapField(t, items[0], "data[0]")
+		if v, ok := item["success"].(bool); !ok || v {
+			t.Fatalf("expected success=false, got %#v", item["success"])
+		}
+		errObj := mapField(t, item["error"], "error")
+		if got := numberField(t, errObj, "status"); got != 422 {
+			t.Fatalf("expected status 422, got %.0f", got)
+		}
+	})
+}
+
+type fileManagerDownloadURLStorageMock struct {
+	presignedURL string
+	presignErr   error
+	lastObject   string
+	lastTTL      time.Duration
+}
+
+func (m *fileManagerDownloadURLStorageMock) EnsureBucket(context.Context) error {
+	return nil
+}
+
+func (m *fileManagerDownloadURLStorageMock) PutObject(context.Context, filemanager.PutObjectInput) (filemanager.ObjectMetadata, error) {
+	return filemanager.ObjectMetadata{}, nil
+}
+
+func (m *fileManagerDownloadURLStorageMock) DeleteObject(context.Context, string) error {
+	return nil
+}
+
+func (m *fileManagerDownloadURLStorageMock) HeadObject(context.Context, string) (filemanager.ObjectMetadata, error) {
+	return filemanager.ObjectMetadata{}, nil
+}
+
+func (m *fileManagerDownloadURLStorageMock) PresignPutObject(context.Context, filemanager.PresignPutObjectInput) (filemanager.PresignedPutObject, error) {
+	return filemanager.PresignedPutObject{}, nil
+}
+
+func (m *fileManagerDownloadURLStorageMock) PresignGetObject(_ context.Context, objectKey string, ttl time.Duration) (string, error) {
+	m.lastObject = objectKey
+	m.lastTTL = ttl
+	if m.presignErr != nil {
+		return "", m.presignErr
+	}
+	return m.presignedURL, nil
+}
+
+func TestResolveFileManagerDownloadURL(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	row := &filemanager.File{
+		ID:        fileID,
+		ObjectKey: "files/2026/04/12/manual.pdf",
+	}
+
+	t.Run("returns presigned url when storage succeeds", func(t *testing.T) {
+		storage := &fileManagerDownloadURLStorageMock{
+			presignedURL: "https://signed.example/files/manual.pdf?sig=abc",
+		}
+		got := resolveFileManagerDownloadURL(context.Background(), storage, row)
+		if got != storage.presignedURL {
+			t.Fatalf("expected presigned url, got %q", got)
+		}
+		if storage.lastObject != row.ObjectKey {
+			t.Fatalf("expected object key %q, got %q", row.ObjectKey, storage.lastObject)
+		}
+		if storage.lastTTL != fileManagerDownloadURLTTL {
+			t.Fatalf("expected ttl %s, got %s", fileManagerDownloadURLTTL, storage.lastTTL)
+		}
+	})
+
+	t.Run("returns empty when storage nil", func(t *testing.T) {
+		got := resolveFileManagerDownloadURL(context.Background(), nil, row)
+		if got != "" {
+			t.Fatalf("expected empty download_url when storage nil, got %q", got)
+		}
+	})
+
+	t.Run("returns empty when presign fails", func(t *testing.T) {
+		storage := &fileManagerDownloadURLStorageMock{
+			presignErr: errors.New("presign failed"),
+		}
+		got := resolveFileManagerDownloadURL(context.Background(), storage, row)
+		if got != "" {
+			t.Fatalf("expected empty download_url on presign error, got %q", got)
+		}
+	})
+}
+
+func TestFileManagerFileHandlerReadAndMutateEndpoints(t *testing.T) {
+	t.Run("get file success and not found", func(t *testing.T) {
+		fileID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		svc := &fileManagerFileHandlerServiceMock{
+			getFileByIDFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+				if bytes.Equal(id, fileID) {
+					return &filemanager.File{
+						ID:        fileID,
+						FolderID:  rootID,
+						Name:      "manual.pdf",
+						ObjectKey: "files/manual.pdf",
+						SizeBytes: 100,
+						MimeType:  "application/pdf",
+						Status:    filemanager.FileStatusReady,
+						CreatedAt: now,
+						UpdatedAt: now,
+					}, nil
+				}
+				return nil, nil
+			},
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: rootID}, nil
+			},
+		}
+		h := NewFileManagerFileHandler(svc, &fileManagerDownloadURLStorageMock{presignedURL: "https://signed/manual.pdf"})
+		app := newFileManagerFileHandlerTestApp(h, nil)
+
+		resp, body := doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/files/get/"+mustUUIDStringFileManager(t, fileID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(body))
+		}
+		payload := decodeJSONMapFileManagerFile(t, body)
+		data := mapField(t, payload["data"], "data")
+		attrs := mapField(t, data["attributes"], "attributes")
+		if stringField(t, attrs, "download_url") == "" {
+			t.Fatalf("expected download_url")
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/files/get/"+mustUUIDStringFileManager(t, uuidv7.MustBytes()), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("list files and trash files", func(t *testing.T) {
+		rootID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		trashAt := now.Add(-time.Hour)
+		svc := &fileManagerFileHandlerServiceMock{
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: rootID}, nil
+			},
+			listFilesByFolderFn: func(_ context.Context, folderID []byte, sort string, limit, offset int) ([]filemanager.File, int64, error) {
+				return []filemanager.File{{
+					ID:        uuidv7.MustBytes(),
+					FolderID:  folderID,
+					Name:      "a.pdf",
+					ObjectKey: "files/a.pdf",
+					SizeBytes: 10,
+					MimeType:  "application/pdf",
+					Status:    filemanager.FileStatusReady,
+					CreatedAt: now,
+					UpdatedAt: now,
+				}}, 1, nil
+			},
+			listTrashFilesFn: func(_ context.Context, folderID []byte, sort string, limit, offset int) ([]filemanager.File, int64, error) {
+				return []filemanager.File{{
+					ID:        uuidv7.MustBytes(),
+					FolderID:  folderID,
+					Name:      "trash.pdf",
+					ObjectKey: "files/trash.pdf",
+					SizeBytes: 20,
+					MimeType:  "application/pdf",
+					Status:    filemanager.FileStatusTrashed,
+					CreatedAt: now,
+					UpdatedAt: now,
+					DeletedAt: &trashAt,
+				}}, 1, nil
+			},
+		}
+		h := NewFileManagerFileHandler(svc, &fileManagerDownloadURLStorageMock{presignedURL: "https://signed/file.pdf"})
+		app := newFileManagerFileHandlerTestApp(h, nil)
+
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/files/get-all?page[number]=0&page[size]=999", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 list files, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/files/trash/get-all?folder_uuid="+mustUUIDStringFileManager(t, rootID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 list trash files, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update delete restore file", func(t *testing.T) {
+		fileID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		svc := &fileManagerFileHandlerServiceMock{
+			moveFileFn: func(_ context.Context, id []byte, params filemanager.MoveFileParams) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:        id,
+					FolderID:  params.FolderID,
+					Name:      "renamed.pdf",
+					ObjectKey: "files/renamed.pdf",
+					MimeType:  "application/pdf",
+					Status:    filemanager.FileStatusReady,
+					CreatedAt: now,
+					UpdatedAt: now,
+				}, nil
+			},
+			deleteFileFn:  func(context.Context, []byte, []byte, *time.Time) error { return nil },
+			restoreFileFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFileByIDFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:        id,
+					FolderID:  rootID,
+					Name:      "renamed.pdf",
+					ObjectKey: "files/renamed.pdf",
+					MimeType:  "application/pdf",
+					Status:    filemanager.FileStatusReady,
+					CreatedAt: now,
+					UpdatedAt: now,
+				}, nil
+			},
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: rootID}, nil
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, uuidv7.MustBytes())
+
+		updateBody := []byte(`{"data":{"type":"file_manager_file","id":"` + mustUUIDStringFileManager(t, fileID) + `","attributes":{"name":"renamed.pdf"}}}`)
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/files/update/"+mustUUIDStringFileManager(t, fileID), updateBody)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 update, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/files/delete/"+mustUUIDStringFileManager(t, fileID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 delete, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/files/restore/"+mustUUIDStringFileManager(t, fileID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 restore, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestFileManagerFileHandlerHelpers(t *testing.T) {
+	t.Run("detail and list resources", func(t *testing.T) {
+		fileID := uuidv7.MustBytes()
+		folderID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		processingAt := now.Add(-time.Minute)
+		row := &filemanager.File{
+			ID:                  fileID,
+			FolderID:            folderID,
+			Name:                "manual.pdf",
+			NameNormalized:      "manual.pdf",
+			Extension:           "pdf",
+			SizeBytes:           55,
+			MimeType:            "application/pdf",
+			ObjectKey:           "files/manual.pdf",
+			Status:              filemanager.FileStatusFailed,
+			FailureReason:       "failed",
+			ProcessingStartedAt: &processingAt,
+			CreatedAt:           now,
+			UpdatedAt:           now,
+		}
+		storage := &fileManagerDownloadURLStorageMock{presignedURL: "https://signed/manual.pdf"}
+		detail := fileManagerFileDetailResource(context.Background(), storage, row, false)
+		if detail.Attributes.Location == nil || detail.Attributes.Location.FolderID == "" {
+			t.Fatalf("expected location in detail resource")
+		}
+		if detail.Attributes.Processing == nil || detail.Attributes.Processing.FailureReason == "" {
+			t.Fatalf("expected processing block")
+		}
+		list := fileManagerFileListResource(context.Background(), storage, row)
+		if list.Attributes.DownloadURL == "" {
+			t.Fatalf("expected list download url")
+		}
+	})
+
+	t.Run("upload intent resource and header sanitization", func(t *testing.T) {
+		grant := &filemanager.FileUploadIntentGrant{
+			UploadIntentID: uuidv7.MustBytes(),
+			Bucket:         "bucket",
+			ObjectKey:      "objects/key",
+			Name:           "manual.pdf",
+			MimeType:       "application/pdf",
+			SizeBytes:      20,
+			Method:         "put",
+			UploadURL:      "https://upload",
+			Headers: map[string]string{
+				"Content-Type":         " application/pdf ",
+				"Host":                 "x",
+				"Content-Length":       "10",
+				"X-Amz-Meta-File_Name": "skip",
+				"X-Test":               " ok ",
+			},
+			ExpiresAt: time.Now().UTC().Add(time.Minute),
+		}
+		resource := fileManagerFileUploadIntentResource(grant)
+		if resource.Attributes.Method != "PUT" {
+			t.Fatalf("expected uppercased method")
+		}
+		if resource.Attributes.RequiredHeaders["content-type"] != "application/pdf" {
+			t.Fatalf("expected sanitized content-type header")
+		}
+		if _, ok := resource.Attributes.RequiredHeaders["host"]; ok {
+			t.Fatalf("host header should be removed")
+		}
+		if fileManagerFileUploadIntentResource(nil).Type != "file_manager_file_upload_intent" {
+			t.Fatalf("expected nil resource fallback type")
+		}
+		if sanitizeUploadRequiredHeaders(map[string]string{"Host": "x"}) != nil {
+			t.Fatalf("expected nil sanitized headers when all filtered")
+		}
+	})
+
+	t.Run("bulk item normalization and helpers", func(t *testing.T) {
+		items := []responsedto.FileManagerFileBulkItem{{Index: 0, Success: true}, {Index: 1, Success: false}}
+		normalizeFileManagerBulkItems(items)
+		if items[0].Success || items[0].Error == nil {
+			t.Fatalf("expected missing success resource normalized to error")
+		}
+		if items[1].Error == nil {
+			t.Fatalf("expected missing error normalized")
+		}
+
+		uploadItems := []responsedto.FileManagerFileUploadIntentBulkItem{{Index: 0, Success: true}, {Index: 1, Success: false}}
+		normalizeFileManagerUploadIntentBulkItems(uploadItems)
+		if uploadItems[0].Success || uploadItems[0].Error == nil {
+			t.Fatalf("expected upload success item normalized to error when resource missing")
+		}
+		if uploadItems[1].Error == nil {
+			t.Fatalf("expected upload missing error normalized")
+		}
+
+		cancelItems := []responsedto.FileManagerFileCancelUploadBulkItem{{Index: 0, Success: true}, {Index: 1, Success: false}}
+		normalizeFileManagerCancelUploadBulkItems(cancelItems)
+		if cancelItems[0].Success || cancelItems[0].Error == nil {
+			t.Fatalf("expected cancel success item normalized to error when resource missing")
+		}
+		if cancelItems[1].Error == nil {
+			t.Fatalf("expected cancel missing error normalized")
+		}
+
+		if fileManagerBulkActionErrorItem(0, "Create failed", filemanager.ErrFileNotFound).Error.Status != http.StatusNotFound {
+			t.Fatalf("expected bulk action mapped not found status")
+		}
+		if fileManagerCancelUploadBulkActionErrorItem(0, "Cancel upload failed", filemanager.ErrFileNotFound).Error.Status != http.StatusNotFound {
+			t.Fatalf("expected mapped not found status")
+		}
+	})
+
+	t.Run("uuid param pagination thumbnail and first non empty", func(t *testing.T) {
+		app := fiber.New()
+		h := NewFileManagerFileHandler(&fileManagerFileHandlerServiceMock{}, nil)
+		app.Get("/:uuid", func(c *fiber.Ctx) error {
+			if _, err := h.parseUUIDParam(c, "uuid", "/path/uuid"); err != nil {
+				return err
+			}
+			page, size, offset := parseFileManagerFilePagination(c)
+			if page != 1 || size != 100 || offset != 0 {
+				t.Fatalf("unexpected pagination %d %d %d", page, size, offset)
+			}
+			row := &filemanager.File{ThumbnailObjectKey: ptrString("thumb/key")}
+			if got := resolveFileManagerThumbnailDownloadURL(c.Context(), &fileManagerDownloadURLStorageMock{presignedURL: "https://signed/thumb"}, row); got == "" {
+				t.Fatalf("expected thumbnail url")
+			}
+			if got := firstNonEmpty(" ", "b"); got != "b" {
+				t.Fatalf("unexpected firstNonEmpty %q", got)
+			}
+			return nil
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/bad?page[number]=0&page[size]=999", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestFileManagerFileHandlerValidationAndErrorCoverage(t *testing.T) {
+	t.Run("create upload cancel list update delete restore validation paths", func(t *testing.T) {
+		rootID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		actorID := uuidv7.MustBytes()
+		svc := &fileManagerFileHandlerServiceMock{
+			requestUploadIntentFn: func(context.Context, filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+				return nil, filemanager.ErrFileStatusConflict
+			},
+			cancelUploadFn: func(context.Context, filemanager.CancelFileUploadIntentParams) error {
+				return filemanager.ErrFileNotFound
+			},
+			createFromIntentFn: func(context.Context, filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return nil, filemanager.ErrFileStatusConflict
+			},
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: rootID}, nil
+			},
+			listFilesByFolderFn: func(context.Context, []byte, string, int, int) ([]filemanager.File, int64, error) {
+				return nil, 0, errors.New("list failure")
+			},
+			moveFileFn: func(context.Context, []byte, filemanager.MoveFileParams) (*filemanager.File, error) {
+				return nil, filemanager.ErrFileNotFound
+			},
+			deleteFileFn: func(context.Context, []byte, []byte, *time.Time) error {
+				return filemanager.ErrFileNotFound
+			},
+			restoreFileFn: func(context.Context, []byte, []byte, bool, []byte) error {
+				return filemanager.ErrFileNotFound
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil)
+		app := newFileManagerFileHandlerTestApp(h, actorID)
+
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create", []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid create json, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create", []byte(`{"data":{"type":"file_manager_file_create"}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 create single payload, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 create empty data, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create", []byte(`{"data":[{"type":"bad","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uuidv7.MustBytes())+`","name":"a.pdf"}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 create invalid type, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"bad","name":"a.pdf"}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 create invalid upload uuid, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uuidv7.MustBytes())+`","name":"a.pdf"}}]}`))
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409 create action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 upload empty data, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload", []byte(`{"data":[{"type":"bad","attributes":{"name":"a.pdf","content_type":"application/pdf","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 upload invalid type, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":" ","content_type":"application/pdf","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 upload missing name, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"a.pdf","content_type":"","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 upload missing content type, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"a.pdf","content_type":"application/pdf","size_bytes":-1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 upload invalid size, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"a.pdf","content_type":"application/pdf","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409 upload action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/files/cancel-upload", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 cancel empty data, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/files/cancel-upload", []byte(`{"data":[{"type":"bad","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uuidv7.MustBytes())+`"}}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 cancel bulk with item error, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/files/cancel-upload", []byte(`{"data":[{"type":"file_manager_file_cancel_upload","attributes":{"upload_intent_uuid":"bad"}}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 cancel invalid uuid item, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/files/cancel-upload", []byte(`{"data":[{"type":"file_manager_file_cancel_upload","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uuidv7.MustBytes())+`"}}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 cancel action error item, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/files/get-all?folder_uuid=not-a-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid folder uuid, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/files/get-all?folder_uuid="+mustUUIDStringFileManager(t, rootID), nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 list service error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/files/update/not-a-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid update uuid, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/files/update/"+mustUUIDStringFileManager(t, fileID), []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid update json, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/files/update/"+mustUUIDStringFileManager(t, fileID), []byte(`{"data":{"type":"file_manager_file","id":"other","attributes":{"name":"x"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 id mismatch, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/files/update/"+mustUUIDStringFileManager(t, fileID), []byte(`{"data":{"type":"file_manager_file","id":"`+mustUUIDStringFileManager(t, fileID)+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 no attributes, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/files/update/"+mustUUIDStringFileManager(t, fileID), []byte(`{"data":{"type":"file_manager_file","id":"`+mustUUIDStringFileManager(t, fileID)+`","attributes":{"folder_id":"bad"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid folder id, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/files/update/"+mustUUIDStringFileManager(t, fileID), []byte(`{"data":{"type":"file_manager_file","id":"`+mustUUIDStringFileManager(t, fileID)+`","attributes":{"name":"x"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 update action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/files/delete/not-a-uuid", nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 invalid delete uuid path handling, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/files/delete/"+mustUUIDStringFileManager(t, fileID), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 delete action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/files/restore/not-a-uuid", nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 invalid restore uuid path handling, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/files/restore/"+mustUUIDStringFileManager(t, fileID), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 restore action error, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("upload aircraft image and create aircraft image branches", func(t *testing.T) {
+		actorID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		aircraftFolderID := uuidv7.MustBytes()
+		designationFolderID := uuidv7.MustBytes()
+		uploadIntentID := uuidv7.MustBytes()
+		aircraftID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		folderLookups := 0
+		svc := &fileManagerFileHandlerServiceMock{
+			requestUploadIntentFn: func(_ context.Context, params filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+				return &filemanager.FileUploadIntentGrant{
+					UploadIntentID: uploadIntentID,
+					Name:           params.Name,
+					MimeType:       params.ContentType,
+					SizeBytes:      params.SizeBytes,
+					Method:         "put",
+					UploadURL:      "https://upload",
+					ExpiresAt:      now.Add(time.Minute),
+				}, nil
+			},
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: rootID}, nil
+			},
+			getFolderByParentFn: func(_ context.Context, parentID []byte, normalized string) (*filemanager.Folder, error) {
+				folderLookups++
+				if bytes.Equal(parentID, rootID) && normalized == aircraftImageFolderName {
+					return &filemanager.Folder{ID: aircraftFolderID}, nil
+				}
+				if bytes.Equal(parentID, aircraftFolderID) && normalized == "aw169" {
+					return nil, nil
+				}
+				if bytes.Equal(parentID, aircraftFolderID) && normalized == "duplicate" {
+					if folderLookups%2 == 1 {
+						return nil, nil
+					}
+					return &filemanager.Folder{ID: designationFolderID}, nil
+				}
+				return nil, nil
+			},
+			createFolderNodeFn: func(_ context.Context, params filemanager.CreateFolderParams) (*filemanager.Folder, error) {
+				if params.Name == "AW169" {
+					return &filemanager.Folder{ID: designationFolderID}, nil
+				}
+				if params.Name == "duplicate" {
+					return nil, filemanager.ErrDuplicateName
+				}
+				return nil, errors.New("create folder failure")
+			},
+			createFromIntentFn: func(_ context.Context, params filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				if params.Name == "conflict.png" {
+					return nil, filemanager.ErrFileStatusConflict
+				}
+				return &filemanager.File{
+					ID:        fileID,
+					FolderID:  params.FolderID,
+					Name:      params.Name,
+					ObjectKey: "images/" + params.Name,
+					MimeType:  "image/png",
+					Status:    filemanager.FileStatusReady,
+					CreatedAt: now,
+					UpdatedAt: now,
+				}, nil
+			},
+		}
+		aircraftSvc := &fileManagerFileHandlerAircraftServiceMock{
+			getByIDFn: func(_ context.Context, id []byte) (*helicopter.Helicopter, error) {
+				switch {
+				case bytes.Equal(id, aircraftID):
+					return &helicopter.Helicopter{ID: id, Designation: "AW169"}, nil
+				default:
+					return nil, nil
+				}
+			},
+		}
+		h := NewFileManagerFileHandler(svc, nil).WithAircraftService(aircraftSvc)
+		app := newFileManagerFileHandlerTestApp(h, actorID)
+
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"image.png","content_type":"application/pdf","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid aircraft upload content type, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-aircraft-image", []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid aircraft upload json, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-aircraft-image", []byte(`{"data":{"type":"file_manager_file_upload_intent"}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 aircraft upload single payload, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-aircraft-image", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 aircraft upload empty data, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-aircraft-image", []byte(`{"data":[{"type":"bad","attributes":{"name":"image.png","content_type":"image/png","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 aircraft upload invalid type, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":" ","content_type":"image/png","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 aircraft upload missing name, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"image.png","content_type":"","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 aircraft upload missing content type, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"image.png","content_type":"image/png","size_bytes":-1}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 aircraft upload invalid size, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/upload-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_upload_intent","attributes":{"name":"image.png","content_type":"image/png","size_bytes":1}}]}`))
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201 aircraft upload success, got %d", resp.StatusCode)
+		}
+
+		noAircraftApp := newFileManagerFileHandlerTestApp(NewFileManagerFileHandler(svc, nil), actorID)
+		resp, _ = doJSONRequestFileManagerFile(t, noAircraftApp, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uploadIntentID)+`","name":"image.png","aircraft_uuid":"`+mustUUIDStringFileManager(t, aircraftID)+`"}}]}`))
+		if resp.StatusCode != http.StatusServiceUnavailable {
+			t.Fatalf("expected 503 when aircraft service missing, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uploadIntentID)+`","name":"image.png","aircraft_uuid":"bad"}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid aircraft uuid, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid create aircraft image json, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":{"type":"file_manager_file_create"}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 create aircraft image single payload, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 create aircraft image empty data, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[{"type":"bad","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uploadIntentID)+`","name":"image.png","aircraft_uuid":"`+mustUUIDStringFileManager(t, aircraftID)+`"}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 create aircraft image invalid type, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"bad-uuid","name":"image.png","aircraft_uuid":"`+mustUUIDStringFileManager(t, aircraftID)+`"}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 create aircraft image invalid upload intent, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uploadIntentID)+`","name":" ","aircraft_uuid":"`+mustUUIDStringFileManager(t, aircraftID)+`"}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 create aircraft image missing name, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uploadIntentID)+`","name":"image.png","aircraft_uuid":"`+mustUUIDStringFileManager(t, uuidv7.MustBytes())+`"}}]}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 aircraft not found, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uploadIntentID)+`","name":"image.png","aircraft_uuid":"`+mustUUIDStringFileManager(t, aircraftID)+`"}}]}`))
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201 create aircraft image success, got %d", resp.StatusCode)
+		}
+
+		aircraftSvcDuplicate := &fileManagerFileHandlerAircraftServiceMock{
+			getByIDFn: func(_ context.Context, id []byte) (*helicopter.Helicopter, error) {
+				if bytes.Equal(id, aircraftID) {
+					return &helicopter.Helicopter{ID: id, Designation: "duplicate"}, nil
+				}
+				return nil, nil
+			},
+		}
+		hDuplicate := NewFileManagerFileHandler(svc, nil).WithAircraftService(aircraftSvcDuplicate)
+		appDuplicate := newFileManagerFileHandlerTestApp(hDuplicate, actorID)
+		resp, _ = doJSONRequestFileManagerFile(t, appDuplicate, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uploadIntentID)+`","name":"image.png","aircraft_uuid":"`+mustUUIDStringFileManager(t, aircraftID)+`"}}]}`))
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201 duplicate folder recovery success, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uploadIntentID)+`","name":"conflict.png","aircraft_uuid":"`+mustUUIDStringFileManager(t, aircraftID)+`"}}]}`))
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409 create aircraft image action error, got %d", resp.StatusCode)
+		}
+
+		errorAircraftSvc := &fileManagerFileHandlerAircraftServiceMock{
+			getByIDFn: func(context.Context, []byte) (*helicopter.Helicopter, error) {
+				return nil, errors.New("aircraft lookup failure")
+			},
+		}
+		appAircraftErr := newFileManagerFileHandlerTestApp(NewFileManagerFileHandler(svc, nil).WithAircraftService(errorAircraftSvc), actorID)
+		resp, _ = doJSONRequestFileManagerFile(t, appAircraftErr, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uploadIntentID)+`","name":"image.png","aircraft_uuid":"`+mustUUIDStringFileManager(t, aircraftID)+`"}}]}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 aircraft lookup error, got %d", resp.StatusCode)
+		}
+
+		emptyDesignationSvc := &fileManagerFileHandlerAircraftServiceMock{
+			getByIDFn: func(_ context.Context, id []byte) (*helicopter.Helicopter, error) {
+				return &helicopter.Helicopter{ID: id, Designation: " "}, nil
+			},
+		}
+		appEmptyDesignation := newFileManagerFileHandlerTestApp(NewFileManagerFileHandler(svc, nil).WithAircraftService(emptyDesignationSvc), actorID)
+		resp, _ = doJSONRequestFileManagerFile(t, appEmptyDesignation, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uploadIntentID)+`","name":"image.png","aircraft_uuid":"`+mustUUIDStringFileManager(t, aircraftID)+`"}}]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 empty aircraft designation, got %d", resp.StatusCode)
+		}
+
+		svcResolveErr := &fileManagerFileHandlerServiceMock{
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) {
+				return nil, errors.New("root lookup failure")
+			},
+		}
+		appResolveErr := newFileManagerFileHandlerTestApp(NewFileManagerFileHandler(svcResolveErr, nil).WithAircraftService(aircraftSvc), actorID)
+		resp, _ = doJSONRequestFileManagerFile(t, appResolveErr, http.MethodPost, "/api/v1/file-manager/files/create-aircraft-image", []byte(`{"data":[{"type":"file_manager_file_create","attributes":{"upload_intent_uuid":"`+mustUUIDStringFileManager(t, uploadIntentID)+`","name":"image.png","aircraft_uuid":"`+mustUUIDStringFileManager(t, aircraftID)+`"}}]}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 aircraft designation folder resolve error, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("folder helper edge cases", func(t *testing.T) {
+		parentID := uuidv7.MustBytes()
+		actorID := uuidv7.MustBytes()
+		existingID := uuidv7.MustBytes()
+		createID := uuidv7.MustBytes()
+		h := NewFileManagerFileHandler(&fileManagerFileHandlerServiceMock{
+			getFolderByParentFn: func(_ context.Context, _ []byte, normalized string) (*filemanager.Folder, error) {
+				switch normalized {
+				case "existing":
+					return &filemanager.Folder{ID: existingID}, nil
+				case "lookup-fail":
+					return nil, errors.New("lookup fail")
+				default:
+					return nil, nil
+				}
+			},
+			createFolderNodeFn: func(_ context.Context, params filemanager.CreateFolderParams) (*filemanager.Folder, error) {
+				switch params.Name {
+				case "Created":
+					return &filemanager.Folder{ID: createID}, nil
+				case "broken":
+					return nil, errors.New("broken")
+				default:
+					return nil, nil
+				}
+			},
+		}, nil)
+
+		if _, err := h.ensureFolderByParentAndName(context.Background(), parentID, " ", actorID); !errors.Is(err, filemanager.ErrInvalidName) {
+			t.Fatalf("expected invalid name error, got %v", err)
+		}
+		if got, err := h.ensureFolderByParentAndName(context.Background(), parentID, "existing", actorID); err != nil || !bytes.Equal(got, existingID) {
+			t.Fatalf("expected existing folder id, got %x err=%v", got, err)
+		}
+		if got, err := h.ensureFolderByParentAndName(context.Background(), parentID, "Created", actorID); err != nil || !bytes.Equal(got, createID) {
+			t.Fatalf("expected created folder id, got %x err=%v", got, err)
+		}
+		if _, err := h.ensureFolderByParentAndName(context.Background(), parentID, "lookup-fail", actorID); err == nil {
+			t.Fatalf("expected lookup error")
+		}
+		if _, err := h.ensureFolderByParentAndName(context.Background(), parentID, "broken", actorID); err == nil {
+			t.Fatalf("expected create error")
+		}
+
+		hNoRoot := NewFileManagerFileHandler(&fileManagerFileHandlerServiceMock{
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) {
+				return nil, nil
+			},
+		}, nil)
+		if _, err := hNoRoot.ensureAircraftDesignationFolder(context.Background(), actorID, "AW169"); !errors.Is(err, filemanager.ErrFolderNotFound) {
+			t.Fatalf("expected root not found, got %v", err)
+		}
+
+		hRootErr := NewFileManagerFileHandler(&fileManagerFileHandlerServiceMock{
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) {
+				return nil, errors.New("root fail")
+			},
+		}, nil)
+		if _, err := hRootErr.ensureAircraftDesignationFolder(context.Background(), actorID, "AW169"); err == nil {
+			t.Fatalf("expected root lookup error")
+		}
+
+		hDuplicateMissing := NewFileManagerFileHandler(&fileManagerFileHandlerServiceMock{
+			getFolderByParentFn: func(_ context.Context, _ []byte, normalized string) (*filemanager.Folder, error) {
+				if normalized == "dup-missing" {
+					return nil, nil
+				}
+				return nil, nil
+			},
+			createFolderNodeFn: func(_ context.Context, params filemanager.CreateFolderParams) (*filemanager.Folder, error) {
+				if params.Name == "dup-missing" {
+					return nil, filemanager.ErrDuplicateName
+				}
+				return nil, nil
+			},
+		}, nil)
+		if _, err := hDuplicateMissing.ensureFolderByParentAndName(context.Background(), parentID, "dup-missing", actorID); !errors.Is(err, filemanager.ErrFolderNotFound) {
+			t.Fatalf("expected duplicate follow-up not found, got %v", err)
+		}
+
+		hDuplicateLookupErr := NewFileManagerFileHandler(&fileManagerFileHandlerServiceMock{
+			getFolderByParentFn: func(_ context.Context, _ []byte, normalized string) (*filemanager.Folder, error) {
+				if normalized == "dup-err" {
+					return nil, errors.New("lookup err")
+				}
+				return nil, nil
+			},
+			createFolderNodeFn: func(_ context.Context, params filemanager.CreateFolderParams) (*filemanager.Folder, error) {
+				if params.Name == "dup-err" {
+					return nil, filemanager.ErrDuplicateName
+				}
+				return nil, nil
+			},
+		}, nil)
+		if _, err := hDuplicateLookupErr.ensureFolderByParentAndName(context.Background(), parentID, "dup-err", actorID); err == nil {
+			t.Fatalf("expected duplicate follow-up lookup error")
+		}
+
+		hCreateNil := NewFileManagerFileHandler(&fileManagerFileHandlerServiceMock{
+			getFolderByParentFn: func(context.Context, []byte, string) (*filemanager.Folder, error) { return nil, nil },
+			createFolderNodeFn: func(context.Context, filemanager.CreateFolderParams) (*filemanager.Folder, error) {
+				return nil, nil
+			},
+		}, nil)
+		gotNil, err := hCreateNil.ensureFolderByParentAndName(context.Background(), parentID, "nil-create", actorID)
+		if err != nil || gotNil != nil {
+			t.Fatalf("expected nil folder id and nil error when create returns nil,nil; got %x err=%v", gotNil, err)
+		}
+
+		hDuplicateInvalidID := NewFileManagerFileHandler(&fileManagerFileHandlerServiceMock{
+			getFolderByParentFn: func(_ context.Context, _ []byte, normalized string) (*filemanager.Folder, error) {
+				if normalized == "dup-short" {
+					return &filemanager.Folder{ID: []byte("short")}, nil
+				}
+				return nil, nil
+			},
+			createFolderNodeFn: func(_ context.Context, params filemanager.CreateFolderParams) (*filemanager.Folder, error) {
+				if params.Name == "dup-short" {
+					return nil, filemanager.ErrDuplicateName
+				}
+				return nil, nil
+			},
+		}, nil)
+		if _, err := hDuplicateInvalidID.ensureFolderByParentAndName(context.Background(), parentID, "dup-short", actorID); !errors.Is(err, filemanager.ErrFolderNotFound) {
+			t.Fatalf("expected duplicate follow-up invalid id to return folder not found, got %v", err)
+		}
+	})
+
+	t.Run("restore file remaining branches", func(t *testing.T) {
+		fileID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		nonRootID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+
+		appGetErr := newFileManagerFileHandlerTestApp(NewFileManagerFileHandler(&fileManagerFileHandlerServiceMock{
+			restoreFileFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFileByIDFn: func(context.Context, []byte) (*filemanager.File, error) { return nil, errors.New("get fail") },
+		}, nil), uuidv7.MustBytes())
+		resp, _ := doJSONRequestFileManagerFile(t, appGetErr, http.MethodPatch, "/api/v1/file-manager/files/restore/"+mustUUIDStringFileManager(t, fileID), nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 restore get error, got %d", resp.StatusCode)
+		}
+
+		appNilRow := newFileManagerFileHandlerTestApp(NewFileManagerFileHandler(&fileManagerFileHandlerServiceMock{
+			restoreFileFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFileByIDFn: func(context.Context, []byte) (*filemanager.File, error) { return nil, nil },
+		}, nil), uuidv7.MustBytes())
+		resp, _ = doJSONRequestFileManagerFile(t, appNilRow, http.MethodPatch, "/api/v1/file-manager/files/restore/"+mustUUIDStringFileManager(t, fileID), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 restore missing row, got %d", resp.StatusCode)
+		}
+
+		appRootErr := newFileManagerFileHandlerTestApp(NewFileManagerFileHandler(&fileManagerFileHandlerServiceMock{
+			restoreFileFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFileByIDFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+				return &filemanager.File{ID: id, FolderID: nonRootID, Name: "a.png", CreatedAt: now, UpdatedAt: now}, nil
+			},
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) { return nil, errors.New("root fail") },
+		}, nil), uuidv7.MustBytes())
+		resp, _ = doJSONRequestFileManagerFile(t, appRootErr, http.MethodPatch, "/api/v1/file-manager/files/restore/"+mustUUIDStringFileManager(t, fileID), nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 restore root error, got %d", resp.StatusCode)
+		}
+
+		appNonRoot := newFileManagerFileHandlerTestApp(NewFileManagerFileHandler(&fileManagerFileHandlerServiceMock{
+			restoreFileFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFileByIDFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+				return &filemanager.File{ID: id, FolderID: nonRootID, Name: "a.png", CreatedAt: now, UpdatedAt: now}, nil
+			},
+			getOrCreateRootFn: func(context.Context) (*filemanager.Folder, error) { return &filemanager.Folder{ID: rootID}, nil },
+		}, nil), uuidv7.MustBytes())
+		resp, body := doJSONRequestFileManagerFile(t, appNonRoot, http.MethodPatch, "/api/v1/file-manager/files/restore/"+mustUUIDStringFileManager(t, fileID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 restore non-root success, got %d", resp.StatusCode)
+		}
+		out := decodeJSONMapFileManagerFile(t, body)
+		attrs := mapField(t, out["data"], "data")["attributes"]
+		location := mapField(t, mapField(t, attrs, "attributes")["location"], "location")
+		if location["folder_id"] != mustUUIDStringFileManager(t, nonRootID) {
+			t.Fatalf("expected non-root folder id in restore response")
+		}
+	})
+}
diff --git a/internal/transport/http/handlers/file_manager_folder_handler.go b/internal/transport/http/handlers/file_manager_folder_handler.go
new file mode 100644
index 0000000..05f785b
--- /dev/null
+++ b/internal/transport/http/handlers/file_manager_folder_handler.go
@@ -0,0 +1,1186 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	dto "wucher/internal/transport/http/dto"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type FileManagerFolderHandler struct {
+	svc      filemanager.Service
+	validate *validators.Validator
+	storage  filemanager.ObjectStorage
+}
+
+var (
+	_                          = dto.ErrorResponse{}
+	_                          = dto.GenericDeleteResponse{}
+	errFileManagerNodeNotFound = errors.New("node not found")
+)
+
+func NewFileManagerFolderHandler(svc filemanager.Service, storage filemanager.ObjectStorage) *FileManagerFolderHandler {
+	return &FileManagerFolderHandler{
+		svc:      svc,
+		validate: validators.New(),
+		storage:  storage,
+	}
+}
+
+// CreateFolder godoc
+// @Summary Create folder node
+// @ID FileManagerCreateFolder
+// @Description Create one folder metadata node under root or under provided parent_id.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFolderCreateRequest true "JSON:API file manager folder create request"
+// @Success 201 {object} responsedto.FileManagerFolderResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/folders/create [post]
+func (h *FileManagerFolderHandler) CreateFolder(c *fiber.Ctx) error {
+	var req requestdto.FileManagerFolderCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	var parentID []byte
+	if req.Data.Attributes.ParentID != nil && strings.TrimSpace(*req.Data.Attributes.ParentID) != "" {
+		pid, err := uuidv7.ParseString(strings.TrimSpace(*req.Data.Attributes.ParentID))
+		if err != nil {
+			return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "parent_id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/data/attributes/parent_id"})
+		}
+		parentID = pid
+	}
+
+	created, err := h.svc.CreateFolderNode(c.UserContext(), filemanager.CreateFolderParams{
+		Name:     req.Data.Attributes.Name,
+		ParentID: parentID,
+		ActorID:  actorUserID(c),
+	})
+	if err != nil {
+		return writeFileManagerActionError(c, "Create failed", err)
+	}
+	return response.Write(c, fiber.StatusCreated, fileManagerFolderResource(created))
+}
+
+// GetFolder godoc
+// @Summary Get folder detail
+// @ID FileManagerGetFolder
+// @Description Return folder metadata by UUID.
+// @Tags File Manager
+// @Produce json
+// @Param uuid path string true "Folder UUID (UUIDv7)"
+// @Success 200 {object} responsedto.FileManagerFolderDetailResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/folders/get/{uuid} [get]
+func (h *FileManagerFolderHandler) GetFolder(c *fiber.Ctx) error {
+	id, err := h.parseUUIDParam(c, "uuid", "/path/uuid")
+	if err != nil {
+		return err
+	}
+
+	row, err := h.svc.GetFolderByID(c.UserContext(), id)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Get failed", err.Error(), nil)
+	}
+	if row == nil {
+		return writeFileManagerError(c, fiber.StatusNotFound, "Not found", "folder not found", nil)
+	}
+
+	return response.Write(c, fiber.StatusOK, fileManagerFolderDetailResource(row))
+}
+
+func (h *FileManagerFolderHandler) ListFolders(c *fiber.Ctx) error {
+	var parentID []byte
+	parentUUID := strings.TrimSpace(c.Query("parent_uuid"))
+	if parentUUID != "" {
+		id, err := uuidv7.ParseString(parentUUID)
+		if err != nil {
+			return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "parent_uuid is invalid UUID", &jsonapi.ErrorSource{Pointer: "/query/parent_uuid"})
+		}
+		parentID = id
+	}
+
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.ListFoldersByParent(c.UserContext(), parentID, sort, 0, 0)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "List failed", err.Error(), nil)
+	}
+
+	data := make([]responsedto.FileManagerFolderResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, fileManagerFolderResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"total": total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListAll godoc
+// @Summary List merged explorer nodes
+// @ID FileManagerListMergedExplorerNodes
+// @Description Return merged direct children (folders + files) for optional parent_uuid (non-recursive).
+// @Description If parent_uuid is omitted, response returns root level nodes.
+// @Description If search is provided, performs a global name search across all folders and files (parent_uuid is ignored).
+// @Tags File Manager
+// @Produce json
+// @Param parent_uuid query string false "Parent folder UUID"
+// @Param search query string false "Search keyword (global name search across all folders and files)"
+// @Success 200 {object} responsedto.FileManagerNodeListResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/get-all [get]
+func (h *FileManagerFolderHandler) ListAll(c *fiber.Ctx) error {
+	search := strings.TrimSpace(c.Query("search"))
+	if search != "" {
+		folders, files, err := h.svc.SearchNodes(c.UserContext(), search)
+		if err != nil {
+			return writeFileManagerActionError(c, "Search failed", err)
+		}
+
+		data := make([]responsedto.FileManagerNodeResource, 0, len(folders)+len(files))
+		for i := range folders {
+			data = append(data, fileManagerNodeFromFolder(&folders[i], false))
+		}
+		for i := range files {
+			downloadURL := resolveFileManagerDownloadURL(c.UserContext(), h.storage, &files[i])
+			data = append(data, fileManagerNodeFromFile(&files[i], false, downloadURL))
+		}
+
+		meta := map[string]any{
+			"is_root": false,
+			"folders": len(folders),
+			"files":   len(files),
+			"total":   len(data),
+			"search":  search,
+		}
+		return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+	}
+
+	var parentID []byte
+	parentUUID := strings.TrimSpace(c.Query("parent_uuid"))
+	if parentUUID != "" {
+		id, err := uuidv7.ParseString(parentUUID)
+		if err != nil {
+			return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "parent_uuid is invalid UUID", &jsonapi.ErrorSource{Pointer: "/query/parent_uuid"})
+		}
+		parentID = id
+	}
+
+	folders, files, err := h.svc.ListNodesByParent(c.UserContext(), parentID)
+	if err != nil {
+		return writeFileManagerActionError(c, "List failed", err)
+	}
+
+	isRoot := len(parentID) == 0
+	data := make([]responsedto.FileManagerNodeResource, 0, len(folders)+len(files))
+	for i := range folders {
+		data = append(data, fileManagerNodeFromFolder(&folders[i], isRoot))
+	}
+	for i := range files {
+		downloadURL := resolveFileManagerDownloadURL(c.UserContext(), h.storage, &files[i])
+		data = append(data, fileManagerNodeFromFile(&files[i], isRoot, downloadURL))
+	}
+
+	var parentUUIDValue *string
+	if !isRoot {
+		parentUUID := idString(parentID)
+		if strings.TrimSpace(parentUUID) != "" {
+			parentUUIDValue = &parentUUID
+		}
+	}
+
+	meta := map[string]any{
+		"is_root": isRoot,
+		"folders": len(folders),
+		"files":   len(files),
+		"total":   len(data),
+	}
+	if !isRoot && parentUUIDValue != nil {
+		meta["parent_uuid"] = *parentUUIDValue
+		breadcrumb, err := h.buildExplorerBreadcrumb(c.UserContext(), parentID)
+		if err != nil {
+			return writeFileManagerActionError(c, "List failed", err)
+		}
+		if len(breadcrumb) > 0 {
+			meta["breadcrumb"] = breadcrumb
+		}
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func (h *FileManagerFolderHandler) ListTrashFolders(c *fiber.Ctx) error {
+	var parentID []byte
+	parentUUID := strings.TrimSpace(c.Query("parent_uuid"))
+	if parentUUID != "" {
+		id, err := uuidv7.ParseString(parentUUID)
+		if err != nil {
+			return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "parent_uuid is invalid UUID", &jsonapi.ErrorSource{Pointer: "/query/parent_uuid"})
+		}
+		parentID = id
+	}
+
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.ListTrashFoldersByParent(c.UserContext(), parentID, sort, 0, 0)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "List failed", err.Error(), nil)
+	}
+
+	data := make([]responsedto.FileManagerFolderResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, fileManagerFolderResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"total": total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListTrashItems godoc
+// @Summary List merged trash items
+// @ID FileManagerListMergedTrashItems
+// @Description Return merged trashed nodes (folders + files) for trash explorer.
+// @Tags File Manager
+// @Produce json
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort values: deleted_at,-deleted_at,name,-name,type,-type,size_bytes,-size_bytes"
+// @Success 200 {object} responsedto.FileManagerTrashListResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/trash/get-all [get]
+func (h *FileManagerFolderHandler) ListTrashItems(c *fiber.Ctx) error {
+	folders, files, err := h.svc.ListTrashNodes(c.UserContext())
+	if err != nil {
+		return writeFileManagerActionError(c, "List failed", err)
+	}
+
+	items := make([]fileManagerTrashItemView, 0, len(folders)+len(files))
+	folderCount := 0
+	fileCount := 0
+
+	for i := range folders {
+		row := &folders[i]
+		if row.DeletedAt == nil {
+			continue
+		}
+		if len(row.ParentID) == 0 && strings.EqualFold(strings.TrimSpace(row.NameNormalized), filemanager.SystemRootFolderName) {
+			continue
+		}
+		folderCount++
+		items = append(items, fileManagerTrashItemView{
+			NodeType:  "folder",
+			UUID:      idString(row.ID),
+			Name:      row.Name,
+			PathCache: row.PathCache,
+			DeletedAt: row.DeletedAt.UTC(),
+			CreatedAt: row.CreatedAt.UTC(),
+			UpdatedAt: row.UpdatedAt.UTC(),
+		})
+	}
+
+	for i := range files {
+		row := &files[i]
+		if row.DeletedAt == nil {
+			continue
+		}
+		fileCount++
+		items = append(items, fileManagerTrashItemView{
+			NodeType:    "file",
+			UUID:        idString(row.ID),
+			Name:        row.Name,
+			Extension:   row.Extension,
+			MimeType:    row.MimeType,
+			DownloadURL: resolveFileManagerDownloadURL(c.UserContext(), h.storage, row),
+			SizeBytes:   row.SizeBytes,
+			DeletedAt:   row.DeletedAt.UTC(),
+			CreatedAt:   row.CreatedAt.UTC(),
+			UpdatedAt:   row.UpdatedAt.UTC(),
+		})
+	}
+
+	sortFileManagerTrashItems(items, c.Query("sort"))
+
+	total := len(items)
+	data := make([]responsedto.FileManagerTrashNodeResource, 0, len(items))
+	for i := range items {
+		data = append(data, responsedto.FileManagerTrashNodeResource{
+			Type: "file_manager_trash_node",
+			ID:   items[i].UUID,
+			Attributes: responsedto.FileManagerTrashNodeAttributes{
+				NodeType:    items[i].NodeType,
+				Name:        items[i].Name,
+				Extension:   items[i].Extension,
+				SizeBytes:   items[i].SizeBytes,
+				MimeType:    items[i].MimeType,
+				DownloadURL: items[i].DownloadURL,
+				PathCache:   items[i].PathCache,
+				TrashedAt:   items[i].DeletedAt.Format(time.RFC3339),
+				CreatedAt:   items[i].CreatedAt.Format(time.RFC3339),
+				UpdatedAt:   items[i].UpdatedAt.Format(time.RFC3339),
+			},
+		})
+	}
+
+	meta := map[string]any{
+		"total":   total,
+		"folders": folderCount,
+		"files":   fileCount,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// UpdateFolder godoc
+// @Summary Update folder node
+// @ID FileManagerUpdateFolder
+// @Description Update folder metadata by UUID (rename and/or move parent).
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Folder UUID (UUIDv7)"
+// @Param request body requestdto.FileManagerFolderUpdateRequest true "JSON:API file manager folder update request"
+// @Success 200 {object} responsedto.FileManagerFolderResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/folders/update/{uuid} [patch]
+func (h *FileManagerFolderHandler) UpdateFolder(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "uuid is invalid UUID", &jsonapi.ErrorSource{Pointer: "/path/uuid"})
+	}
+
+	var req requestdto.FileManagerFolderUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if strings.TrimSpace(req.Data.ID) == "" || req.Data.ID != uuidStr {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "id does not match path uuid", &jsonapi.ErrorSource{Pointer: "/data/id"})
+	}
+	attrs := req.Data.Attributes
+	if attrs.Name == nil && attrs.ParentID == nil {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "at least one attribute must be provided", &jsonapi.ErrorSource{Pointer: "/data/attributes"})
+	}
+	var parentID []byte
+	parentProvided := attrs.ParentID != nil
+	if parentProvided && strings.TrimSpace(*attrs.ParentID) != "" {
+		parsed, err := uuidv7.ParseString(strings.TrimSpace(*attrs.ParentID))
+		if err != nil {
+			return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "parent_id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/data/attributes/parent_id"})
+		}
+		parentID = parsed
+	}
+
+	updated, err := h.svc.MoveFolderNode(c.UserContext(), id, filemanager.MoveFolderParams{
+		Name:           attrs.Name,
+		ParentID:       parentID,
+		ParentProvided: parentProvided,
+		ActorID:        actorUserID(c),
+	})
+	if err != nil {
+		return writeFileManagerActionError(c, "Update failed", err)
+	}
+	return response.Write(c, fiber.StatusOK, fileManagerFolderResource(updated))
+}
+
+// MoveNodes godoc
+// @Summary Move nodes (file/folder) in bulk
+// @ID FileManagerMoveNodesBulk
+// @Description Unified move endpoint. Each item UUID can be either folder UUID or file UUID.
+// @Description destination_folder_uuid null/empty means move to root.
+// @Description Bulk payload accepts one or many items.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerNodeMoveBulkRequest true "Bulk move request"
+// @Success 200 {object} responsedto.FileManagerMoveNodeBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/move [patch]
+func (h *FileManagerFolderHandler) MoveNodes(c *fiber.Ctx) error {
+	var req requestdto.FileManagerNodeMoveBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	actorID := actorUserID(c)
+	items := make([]responsedto.FileManagerMoveNodeBulkItem, len(req.Data))
+	for i := range req.Data {
+		item := req.Data[i]
+		nodeUUID := strings.TrimSpace(item.UUID)
+		if nodeUUID == "" {
+			items[i] = fileManagerMoveBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "uuid is required")
+			continue
+		}
+
+		nodeID, err := uuidv7.ParseString(nodeUUID)
+		if err != nil {
+			items[i] = fileManagerMoveBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "uuid is invalid UUID")
+			continue
+		}
+
+		var destinationID []byte
+		destinationUUID := ""
+		if item.DestinationFolderUUID != nil && strings.TrimSpace(*item.DestinationFolderUUID) != "" {
+			destinationUUID = strings.TrimSpace(*item.DestinationFolderUUID)
+			parsed, err := uuidv7.ParseString(destinationUUID)
+			if err != nil {
+				items[i] = fileManagerMoveBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "destination_folder_uuid is invalid UUID")
+				continue
+			}
+			destinationID = parsed
+		}
+
+		nodeType, moveErr := h.moveNodeAutoDetect(c.UserContext(), nodeID, destinationID, actorID)
+		if moveErr != nil {
+			items[i] = fileManagerMoveBulkActionErrorItem(i, moveErr)
+			continue
+		}
+		items[i] = fileManagerMoveBulkSuccessItem(i, nodeID, nodeType, destinationUUID)
+	}
+
+	return writeFileManagerMoveBulkResponse(c, items)
+}
+
+// DeleteNodesBulk godoc
+// @Summary Delete nodes (file/folder) in bulk
+// @ID FileManagerDeleteNodesBulk
+// @Description Soft-delete multiple nodes by UUID. UUID can be folder or file.
+// @Description Bulk payload accepts one or many items.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerNodePurgeBulkRequest true "Bulk delete request"
+// @Success 200 {object} responsedto.FileManagerMoveNodeBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/delete [delete]
+func (h *FileManagerFolderHandler) DeleteNodesBulk(c *fiber.Ctx) error {
+	var req requestdto.FileManagerNodePurgeBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	actorID := actorUserID(c)
+	items := make([]responsedto.FileManagerMoveNodeBulkItem, len(req.Data))
+	for i := range req.Data {
+		nodeUUID := strings.TrimSpace(req.Data[i].UUID)
+		if nodeUUID == "" {
+			items[i] = fileManagerMoveBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "uuid is required")
+			continue
+		}
+
+		nodeID, err := uuidv7.ParseString(nodeUUID)
+		if err != nil {
+			items[i] = fileManagerMoveBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "uuid is invalid UUID")
+			continue
+		}
+
+		nodeType, err := h.deleteNodeAutoDetect(c.UserContext(), nodeID, actorID)
+		if err != nil {
+			if errors.Is(err, errFileManagerNodeNotFound) {
+				items[i] = fileManagerMoveBulkSystemErrorItem(i, fiber.StatusNotFound, "Not found", apperrorsx.ErrDataNotFound.Message)
+				continue
+			}
+			def := mapFileManagerActionDef("Delete failed", err)
+			items[i] = fileManagerMoveBulkSystemErrorItem(i, def.Status, def.Title, def.Message)
+			continue
+		}
+
+		resource := responsedto.FileManagerMoveNodeResultResource{
+			Type: "file_manager_delete_result",
+			ID:   idString(nodeID),
+			Attributes: responsedto.FileManagerMoveNodeResultAttributes{
+				NodeType: nodeType,
+				Status:   "trashed",
+			},
+		}
+		items[i] = responsedto.FileManagerMoveNodeBulkItem{
+			Index:    i,
+			Success:  true,
+			Resource: &resource,
+		}
+	}
+
+	return writeFileManagerMoveBulkResponse(c, items)
+}
+
+// RestoreNodesBulk godoc
+// @Summary Restore nodes (file/folder) in bulk
+// @ID FileManagerRestoreNodesBulk
+// @Description Restore multiple trashed nodes by UUID to original location.
+// @Description Bulk payload accepts one or many items.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerNodePurgeBulkRequest true "Bulk restore request"
+// @Success 200 {object} responsedto.FileManagerMoveNodeBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/restore [patch]
+func (h *FileManagerFolderHandler) RestoreNodesBulk(c *fiber.Ctx) error {
+	var req requestdto.FileManagerNodePurgeBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	actorID := actorUserID(c)
+	items := make([]responsedto.FileManagerMoveNodeBulkItem, len(req.Data))
+	for i := range req.Data {
+		nodeUUID := strings.TrimSpace(req.Data[i].UUID)
+		if nodeUUID == "" {
+			items[i] = fileManagerMoveBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "uuid is required")
+			continue
+		}
+
+		nodeID, err := uuidv7.ParseString(nodeUUID)
+		if err != nil {
+			items[i] = fileManagerMoveBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "uuid is invalid UUID")
+			continue
+		}
+
+		nodeType, locationFolderID, err := h.restoreNodeAutoDetect(c.UserContext(), nodeID, actorID)
+		if err != nil {
+			if errors.Is(err, errFileManagerNodeNotFound) {
+				items[i] = fileManagerMoveBulkSystemErrorItem(i, fiber.StatusNotFound, "Not found", apperrorsx.ErrDataNotFound.Message)
+				continue
+			}
+			def := mapFileManagerActionDef("Restore failed", err)
+			items[i] = fileManagerMoveBulkSystemErrorItem(i, def.Status, def.Title, def.Message)
+			continue
+		}
+
+		resource := responsedto.FileManagerMoveNodeResultResource{
+			Type: "file_manager_restore_result",
+			ID:   idString(nodeID),
+			Attributes: responsedto.FileManagerMoveNodeResultAttributes{
+				NodeType: nodeType,
+				Status:   "ready",
+			},
+		}
+		if strings.TrimSpace(locationFolderID) != "" {
+			resource.Attributes.Location = &responsedto.FileManagerActionLocation{
+				FolderID: locationFolderID,
+			}
+		}
+		items[i] = responsedto.FileManagerMoveNodeBulkItem{
+			Index:    i,
+			Success:  true,
+			Resource: &resource,
+		}
+	}
+
+	return writeFileManagerMoveBulkResponse(c, items)
+}
+
+func (h *FileManagerFolderHandler) moveNodeAutoDetect(ctx context.Context, nodeID, destinationID, actorID []byte) (string, error) {
+	if _, err := h.svc.MoveFolderNode(ctx, nodeID, filemanager.MoveFolderParams{
+		ParentID:       destinationID,
+		ParentProvided: true,
+		ActorID:        actorID,
+	}); err == nil {
+		return "folder", nil
+	} else if !errors.Is(err, filemanager.ErrFolderNotFound) {
+		return "", err
+	}
+
+	targetFolderID := destinationID
+	if len(targetFolderID) == 0 {
+		root, err := h.svc.GetOrCreateSystemRootFolder(ctx)
+		if err != nil {
+			return "", err
+		}
+		if root == nil || len(root.ID) == 0 {
+			return "", errFileManagerNodeNotFound
+		}
+		targetFolderID = root.ID
+	}
+
+	if _, err := h.svc.MoveFileNode(ctx, nodeID, filemanager.MoveFileParams{
+		FolderID:       targetFolderID,
+		FolderProvided: true,
+		ActorID:        actorID,
+	}); err != nil {
+		if errors.Is(err, filemanager.ErrFileNotFound) {
+			return "", errFileManagerNodeNotFound
+		}
+		return "", err
+	}
+
+	return "file", nil
+}
+
+func (h *FileManagerFolderHandler) deleteNodeAutoDetect(ctx context.Context, nodeID, actorID []byte) (string, error) {
+	if err := h.svc.DeleteFolder(ctx, nodeID, actorID, nil); err == nil {
+		return "folder", nil
+	} else if !errors.Is(err, filemanager.ErrFolderNotFound) {
+		return "", err
+	}
+
+	if err := h.svc.DeleteFile(ctx, nodeID, actorID, nil); err != nil {
+		if errors.Is(err, filemanager.ErrFileNotFound) {
+			return "", errFileManagerNodeNotFound
+		}
+		return "", err
+	}
+	return "file", nil
+}
+
+func (h *FileManagerFolderHandler) restoreNodeAutoDetect(ctx context.Context, nodeID, actorID []byte) (string, string, error) {
+	if err := h.svc.RestoreFolder(ctx, nodeID, nil, false, actorID); err == nil {
+		row, getErr := h.svc.GetFolderByID(ctx, nodeID)
+		if getErr != nil {
+			return "", "", getErr
+		}
+		if row == nil {
+			return "", "", errFileManagerNodeNotFound
+		}
+		locationFolderID := idString(row.ParentID)
+		if strings.TrimSpace(locationFolderID) != "" {
+			root, rootErr := h.svc.GetOrCreateSystemRootFolder(ctx)
+			if rootErr != nil {
+				return "", "", rootErr
+			}
+			if root != nil && bytes.Equal(row.ParentID, root.ID) {
+				locationFolderID = ""
+			}
+		}
+		return "folder", locationFolderID, nil
+	} else if !errors.Is(err, filemanager.ErrFolderNotFound) {
+		return "", "", err
+	}
+
+	if err := h.svc.RestoreFile(ctx, nodeID, nil, false, actorID); err != nil {
+		if errors.Is(err, filemanager.ErrFileNotFound) {
+			return "", "", errFileManagerNodeNotFound
+		}
+		return "", "", err
+	}
+	row, getErr := h.svc.GetFileByID(ctx, nodeID)
+	if getErr != nil {
+		return "", "", getErr
+	}
+	if row == nil {
+		return "", "", errFileManagerNodeNotFound
+	}
+	root, rootErr := h.svc.GetOrCreateSystemRootFolder(ctx)
+	if rootErr != nil {
+		return "", "", rootErr
+	}
+	locationFolderID := ""
+	if root == nil || !bytes.Equal(row.FolderID, root.ID) {
+		locationFolderID = idString(row.FolderID)
+	}
+	return "file", locationFolderID, nil
+}
+
+func writeFileManagerMoveBulkResponse(c *fiber.Ctx, items []responsedto.FileManagerMoveNodeBulkItem) error {
+	success := 0
+	for i := range items {
+		if items[i].Success {
+			success++
+		}
+	}
+
+	resp := responsedto.FileManagerMoveNodeBulkResponse{
+		Data: items,
+	}
+	resp.Meta.Total = len(items)
+	resp.Meta.Success = success
+	resp.Meta.Failed = len(items) - success
+	resp.Meta.PartialSuccess = resp.Meta.Success > 0 && resp.Meta.Failed > 0
+
+	return c.Status(fiber.StatusOK).JSON(resp)
+}
+
+func fileManagerMoveBulkSuccessItem(index int, nodeID []byte, nodeType, destinationUUID string) responsedto.FileManagerMoveNodeBulkItem {
+	resource := responsedto.FileManagerMoveNodeResultResource{
+		Type: "file_manager_move_result",
+		ID:   idString(nodeID),
+		Attributes: responsedto.FileManagerMoveNodeResultAttributes{
+			NodeType: nodeType,
+			Status:   "moved",
+		},
+	}
+	if strings.TrimSpace(destinationUUID) != "" {
+		resource.Attributes.Location = &responsedto.FileManagerActionLocation{
+			FolderID: destinationUUID,
+		}
+	}
+
+	return responsedto.FileManagerMoveNodeBulkItem{
+		Index:    index,
+		Success:  true,
+		Resource: &resource,
+	}
+}
+
+func fileManagerMoveBulkSystemErrorItem(index int, status int, title, detail string) responsedto.FileManagerMoveNodeBulkItem {
+	def := inferFileManagerDef(status, title, detail)
+	return responsedto.FileManagerMoveNodeBulkItem{
+		Index:   index,
+		Success: false,
+		Error: &responsedto.FileManagerActionBulkError{
+			Status:    status,
+			Code:      def.Code,
+			ErrorCode: def.ErrorCode,
+			Title:     def.Title,
+			Detail:    def.Message,
+		},
+	}
+}
+
+func fileManagerMoveBulkActionErrorItem(index int, err error) responsedto.FileManagerMoveNodeBulkItem {
+	if errors.Is(err, errFileManagerNodeNotFound) {
+		return fileManagerMoveBulkSystemErrorItem(index, fiber.StatusNotFound, "Not found", apperrorsx.ErrDataNotFound.Message)
+	}
+
+	def := mapFileManagerActionDef("Move failed", err)
+	return fileManagerMoveBulkSystemErrorItem(index, def.Status, def.Title, def.Message)
+}
+
+func (h *FileManagerFolderHandler) buildExplorerBreadcrumb(ctx context.Context, parentID []byte) ([]responsedto.FileManagerBreadcrumbItem, error) {
+	if len(parentID) == 0 {
+		return nil, nil
+	}
+
+	breadcrumb := make([]responsedto.FileManagerBreadcrumbItem, 0, 8)
+	currentID := append([]byte(nil), parentID...)
+	for len(currentID) != 0 {
+		row, err := h.svc.GetFolderByID(ctx, currentID)
+		if err != nil {
+			return nil, err
+		}
+		if row == nil {
+			break
+		}
+
+		item := responsedto.FileManagerBreadcrumbItem{
+			ID:   idString(row.ID),
+			Name: row.Name,
+		}
+		breadcrumb = append([]responsedto.FileManagerBreadcrumbItem{item}, breadcrumb...)
+		currentID = append([]byte(nil), row.ParentID...)
+	}
+
+	return breadcrumb, nil
+}
+
+func (h *FileManagerFolderHandler) DeleteFolder(c *fiber.Ctx) error {
+	id, err := h.parseUUIDParam(c, "uuid", "/path/uuid")
+	if err != nil {
+		return err
+	}
+
+	if err := h.svc.DeleteFolder(c.UserContext(), id, actorUserID(c), nil); err != nil {
+		return writeFileManagerActionError(c, "Delete failed", err)
+	}
+
+	return response.Write(c, fiber.StatusOK, fileManagerActionResultResource("file_manager_delete_result", id, "trashed", ""))
+}
+
+// RestoreFolder restores a trashed folder by ID to its original location.
+func (h *FileManagerFolderHandler) RestoreFolder(c *fiber.Ctx) error {
+	id, err := h.parseUUIDParam(c, "uuid", "/path/uuid")
+	if err != nil {
+		return err
+	}
+
+	if err := h.svc.RestoreFolder(c.Context(), id, nil, false, actorUserID(c)); err != nil {
+		return writeFileManagerActionError(c, "Restore failed", err)
+	}
+
+	row, err := h.svc.GetFolderByID(c.Context(), id)
+	if err != nil {
+		return writeFileManagerActionError(c, "Restore failed", err)
+	}
+	if row == nil {
+		return writeFileManagerActionError(c, "Restore failed", filemanager.ErrFolderNotFound)
+	}
+
+	locationFolderID := idString(row.ParentID)
+	if strings.TrimSpace(locationFolderID) != "" {
+		root, rootErr := h.svc.GetOrCreateSystemRootFolder(c.Context())
+		if rootErr != nil {
+			return writeFileManagerActionError(c, "Restore failed", rootErr)
+		}
+		if root != nil && bytes.Equal(row.ParentID, root.ID) {
+			locationFolderID = ""
+		}
+	}
+	return response.Write(c, fiber.StatusOK, fileManagerActionResultResource("file_manager_restore_result", id, "ready", locationFolderID))
+}
+
+// PurgeNodesBulk godoc
+// @Summary Purge nodes (file/folder) from trash in bulk
+// @ID FileManagerPurgeNodesBulkFromTrash
+// @Description Permanently delete multiple trashed nodes by UUID. UUID can be folder or file.
+// @Description Bulk payload accepts one or many items.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerNodePurgeBulkRequest true "Bulk purge request"
+// @Success 200 {object} responsedto.FileManagerPurgeNodeBulkResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/purge-delete [delete]
+func (h *FileManagerFolderHandler) PurgeNodesBulk(c *fiber.Ctx) error {
+	var req requestdto.FileManagerNodePurgeBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if len(req.Data) == 0 {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "data must contain at least one item", &jsonapi.ErrorSource{Pointer: "/data"})
+	}
+
+	items := make([]responsedto.FileManagerPurgeNodeBulkItem, len(req.Data))
+	for i := range req.Data {
+		item := req.Data[i]
+		nodeUUID := strings.TrimSpace(item.UUID)
+		if nodeUUID == "" {
+			items[i] = fileManagerPurgeBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "uuid is required")
+			continue
+		}
+
+		nodeID, err := uuidv7.ParseString(nodeUUID)
+		if err != nil {
+			items[i] = fileManagerPurgeBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "uuid is invalid UUID")
+			continue
+		}
+
+		nodeType, err := h.purgeNodeAutoDetect(c.UserContext(), nodeID)
+		if err != nil {
+			def := mapFileManagerActionDef("Purge failed", err)
+			items[i] = fileManagerPurgeBulkSystemErrorItem(i, def.Status, def.Title, def.Message)
+			continue
+		}
+		items[i] = fileManagerPurgeBulkSuccessItem(i, nodeID, nodeType)
+	}
+
+	return writeFileManagerPurgeBulkResponse(c, items)
+}
+
+func (h *FileManagerFolderHandler) purgeNodeAutoDetect(ctx context.Context, id []byte) (string, error) {
+	if err := h.svc.PurgeFolderNode(ctx, id); err == nil {
+		return "folder", nil
+	} else if !errors.Is(err, filemanager.ErrFolderNotFound) {
+		return "", err
+	}
+
+	if err := h.svc.PurgeFileNode(ctx, id); err != nil {
+		if errors.Is(err, filemanager.ErrFileNotFound) {
+			return "", filemanager.ErrFileNotFound
+		}
+		return "", err
+	}
+	return "file", nil
+}
+
+func writeFileManagerPurgeBulkResponse(c *fiber.Ctx, items []responsedto.FileManagerPurgeNodeBulkItem) error {
+	success := 0
+	for i := range items {
+		if items[i].Success {
+			success++
+		}
+	}
+
+	resp := responsedto.FileManagerPurgeNodeBulkResponse{
+		Data: items,
+	}
+	resp.Meta.Total = len(items)
+	resp.Meta.Success = success
+	resp.Meta.Failed = len(items) - success
+	resp.Meta.PartialSuccess = resp.Meta.Success > 0 && resp.Meta.Failed > 0
+
+	return c.Status(fiber.StatusOK).JSON(resp)
+}
+
+func fileManagerPurgeBulkSuccessItem(index int, nodeID []byte, nodeType string) responsedto.FileManagerPurgeNodeBulkItem {
+	resource := responsedto.FileManagerPurgeNodeResultResource{
+		Type: "file_manager_purge_result",
+		ID:   idString(nodeID),
+		Attributes: responsedto.FileManagerPurgeNodeResultAttributes{
+			NodeType: nodeType,
+			Status:   "purged",
+		},
+	}
+	return responsedto.FileManagerPurgeNodeBulkItem{
+		Index:    index,
+		Success:  true,
+		Resource: &resource,
+	}
+}
+
+func fileManagerPurgeBulkSystemErrorItem(index int, status int, title, detail string) responsedto.FileManagerPurgeNodeBulkItem {
+	def := inferFileManagerDef(status, title, detail)
+	return responsedto.FileManagerPurgeNodeBulkItem{
+		Index:   index,
+		Success: false,
+		Error: &responsedto.FileManagerActionBulkError{
+			Status:    status,
+			Code:      def.Code,
+			ErrorCode: def.ErrorCode,
+			Title:     def.Title,
+			Detail:    def.Message,
+		},
+	}
+}
+
+func (h *FileManagerFolderHandler) parseUUIDParam(c *fiber.Ctx, paramName, sourcePointer string) ([]byte, error) {
+	uuidStr := c.Params(paramName)
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return nil, writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", fmt.Sprintf("%s is invalid UUID", paramName), &jsonapi.ErrorSource{Pointer: sourcePointer})
+	}
+	return id, nil
+}
+
+func parseFileManagerFolderPagination(c *fiber.Ctx) (pageNumber int, pageSize int, offset int) {
+	pageNumber = parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	pageSize = parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	offset = (pageNumber - 1) * pageSize
+	return
+}
+
+func replacePathPrefix(pathCache string, oldPrefix string, newPrefix string) string {
+	if oldPrefix == "" {
+		return pathCache
+	}
+	if pathCache == oldPrefix {
+		return newPrefix
+	}
+	prefixWithSlash := oldPrefix + "/"
+	if strings.HasPrefix(pathCache, prefixWithSlash) {
+		return newPrefix + strings.TrimPrefix(pathCache, oldPrefix)
+	}
+	return pathCache
+}
+
+type fileManagerTrashItemView struct {
+	NodeType    string
+	UUID        string
+	Name        string
+	Extension   string
+	PathCache   string
+	MimeType    string
+	DownloadURL string
+	SizeBytes   int64
+	DeletedAt   time.Time
+	CreatedAt   time.Time
+	UpdatedAt   time.Time
+}
+
+func sortFileManagerTrashItems(items []fileManagerTrashItemView, sortParam string) {
+	sortParam = strings.TrimSpace(sortParam)
+	if sortParam == "" {
+		sortParam = "-deleted_at"
+	}
+	desc := strings.HasPrefix(sortParam, "-")
+	key := strings.TrimPrefix(sortParam, "-")
+
+	sort.SliceStable(items, func(i, j int) bool {
+		a := items[i]
+		b := items[j]
+
+		compare := 0
+		switch key {
+		case "name":
+			compare = strings.Compare(strings.ToLower(a.Name), strings.ToLower(b.Name))
+		case "type":
+			compare = strings.Compare(strings.ToLower(a.NodeType), strings.ToLower(b.NodeType))
+		case "size_bytes":
+			switch {
+			case a.SizeBytes < b.SizeBytes:
+				compare = -1
+			case a.SizeBytes > b.SizeBytes:
+				compare = 1
+			}
+		case "deleted_at":
+			fallthrough
+		default:
+			switch {
+			case a.DeletedAt.Before(b.DeletedAt):
+				compare = -1
+			case a.DeletedAt.After(b.DeletedAt):
+				compare = 1
+			}
+		}
+
+		if compare == 0 {
+			compare = strings.Compare(strings.ToLower(a.Name), strings.ToLower(b.Name))
+		}
+
+		if desc {
+			return compare > 0
+		}
+		return compare < 0
+	})
+}
+
+func parentPathFromCache(pathCache string) string {
+	pathCache = strings.TrimSpace(pathCache)
+	pathCache = strings.TrimRight(pathCache, "/")
+	if pathCache == "" || pathCache == "/" {
+		return ""
+	}
+	lastSlash := strings.LastIndex(pathCache, "/")
+	if lastSlash <= 0 {
+		return ""
+	}
+	return pathCache[:lastSlash]
+}
+
+func fileManagerFolderResource(row *filemanager.Folder) responsedto.FileManagerFolderResource {
+	return responsedto.FileManagerFolderResource{
+		Type: "file_manager_folder",
+		ID:   idString(row.ID),
+		Attributes: shareddto.FileManagerFolderAttributes{
+			ParentID:       idString(row.ParentID),
+			Name:           row.Name,
+			NameNormalized: row.NameNormalized,
+			Depth:          row.Depth,
+			PathCache:      row.PathCache,
+			CreatedAt:      row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:      uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:      row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:      uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt:      timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:      uuidStringOrEmpty(row.DeletedBy),
+			PurgeAt:        timeStringOrEmpty(row.PurgeAt),
+		},
+	}
+}
+
+func fileManagerFolderDetailResource(row *filemanager.Folder) responsedto.FileManagerFolderDetailResource {
+	resource := responsedto.FileManagerFolderDetailResource{
+		Type: "file_manager_folder",
+		ID:   idString(row.ID),
+		Attributes: shareddto.FileManagerFolderDetailAttributes{
+			Name:           row.Name,
+			NameNormalized: row.NameNormalized,
+			PathCache:      row.PathCache,
+			Audit: shareddto.FileManagerFolderAuditAttributes{
+				CreatedAt: row.CreatedAt.UTC().Format(time.RFC3339),
+				CreatedBy: uuidStringOrEmpty(row.CreatedBy),
+				UpdatedAt: row.UpdatedAt.UTC().Format(time.RFC3339),
+				UpdatedBy: uuidStringOrEmpty(row.UpdatedBy),
+			},
+		},
+	}
+
+	if row.Depth > 0 {
+		depth := row.Depth
+		resource.Attributes.Depth = &depth
+	}
+
+	parentID := strings.TrimSpace(idString(row.ParentID))
+	if parentID != "" {
+		resource.Attributes.Location = &shareddto.FileManagerFolderLocationAttributes{
+			ParentID: parentID,
+		}
+	}
+
+	return resource
+}
+
+func fileManagerNodeFromFolder(row *filemanager.Folder, isRoot bool) responsedto.FileManagerNodeResource {
+	return responsedto.FileManagerNodeResource{
+		Type: "file_manager_node",
+		ID:   idString(row.ID),
+		Attributes: responsedto.FileManagerNodeAttributes{
+			NodeType:  "folder",
+			ParentID:  fileManagerNodeParentID(row.ParentID, isRoot),
+			Name:      row.Name,
+			PathCache: row.PathCache,
+			Status:    "ready",
+			CreatedAt: row.CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedAt: row.UpdatedAt.UTC().Format(time.RFC3339),
+		},
+	}
+}
+
+func fileManagerNodeFromFile(row *filemanager.File, isRoot bool, downloadURL string) responsedto.FileManagerNodeResource {
+	return responsedto.FileManagerNodeResource{
+		Type: "file_manager_node",
+		ID:   idString(row.ID),
+		Attributes: responsedto.FileManagerNodeAttributes{
+			NodeType:    "file",
+			ParentID:    fileManagerNodeParentID(row.FolderID, isRoot),
+			Name:        row.Name,
+			Extension:   row.Extension,
+			SizeBytes:   row.SizeBytes,
+			MimeType:    row.MimeType,
+			DownloadURL: strings.TrimSpace(downloadURL),
+			Status:      row.Status,
+			CreatedAt:   row.CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedAt:   row.UpdatedAt.UTC().Format(time.RFC3339),
+		},
+	}
+}
+
+func fileManagerNodeParentID(parentID []byte, isRoot bool) *string {
+	if isRoot {
+		return nil
+	}
+	id := idString(parentID)
+	if strings.TrimSpace(id) == "" {
+		return nil
+	}
+	return &id
+}
diff --git a/internal/transport/http/handlers/file_manager_folder_handler_test.go b/internal/transport/http/handlers/file_manager_folder_handler_test.go
new file mode 100644
index 0000000..dda215f
--- /dev/null
+++ b/internal/transport/http/handlers/file_manager_folder_handler_test.go
@@ -0,0 +1,1190 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type fileManagerFolderHandlerServiceMock struct {
+	filemanager.Service
+
+	createFolderFn     func(context.Context, filemanager.CreateFolderParams) (*filemanager.Folder, error)
+	moveFolderFn       func(context.Context, []byte, filemanager.MoveFolderParams) (*filemanager.Folder, error)
+	moveFileFn         func(context.Context, []byte, filemanager.MoveFileParams) (*filemanager.File, error)
+	deleteFolderFn     func(context.Context, []byte, []byte, *time.Time) error
+	deleteFileFn       func(context.Context, []byte, []byte, *time.Time) error
+	restoreFolderFn    func(context.Context, []byte, []byte, bool, []byte) error
+	restoreFileFn      func(context.Context, []byte, []byte, bool, []byte) error
+	getFolderFn        func(context.Context, []byte) (*filemanager.Folder, error)
+	getFileFn          func(context.Context, []byte) (*filemanager.File, error)
+	getRootFn          func(context.Context) (*filemanager.Folder, error)
+	purgeFolderFn      func(context.Context, []byte) error
+	purgeFileFn        func(context.Context, []byte) error
+	listFoldersFn      func(context.Context, []byte, string, int, int) ([]filemanager.Folder, int64, error)
+	listNodesFn        func(context.Context, []byte) ([]filemanager.Folder, []filemanager.File, error)
+	listTrashFoldersFn func(context.Context, []byte, string, int, int) ([]filemanager.Folder, int64, error)
+	listTrashNodesFn   func(context.Context) ([]filemanager.Folder, []filemanager.File, error)
+}
+
+func (m *fileManagerFolderHandlerServiceMock) CreateFolderNode(ctx context.Context, params filemanager.CreateFolderParams) (*filemanager.Folder, error) {
+	if m.createFolderFn != nil {
+		return m.createFolderFn(ctx, params)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerFolderHandlerServiceMock) MoveFolderNode(ctx context.Context, id []byte, params filemanager.MoveFolderParams) (*filemanager.Folder, error) {
+	if m.moveFolderFn != nil {
+		return m.moveFolderFn(ctx, id, params)
+	}
+	return nil, filemanager.ErrFolderNotFound
+}
+
+func (m *fileManagerFolderHandlerServiceMock) MoveFileNode(ctx context.Context, id []byte, params filemanager.MoveFileParams) (*filemanager.File, error) {
+	if m.moveFileFn != nil {
+		return m.moveFileFn(ctx, id, params)
+	}
+	return nil, filemanager.ErrFileNotFound
+}
+
+func (m *fileManagerFolderHandlerServiceMock) DeleteFolder(ctx context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error {
+	if m.deleteFolderFn != nil {
+		return m.deleteFolderFn(ctx, id, deletedBy, purgeAt)
+	}
+	return filemanager.ErrFolderNotFound
+}
+
+func (m *fileManagerFolderHandlerServiceMock) DeleteFile(ctx context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error {
+	if m.deleteFileFn != nil {
+		return m.deleteFileFn(ctx, id, deletedBy, purgeAt)
+	}
+	return filemanager.ErrFileNotFound
+}
+
+func (m *fileManagerFolderHandlerServiceMock) RestoreFolder(ctx context.Context, id []byte, targetParentID []byte, targetProvided bool, restoredBy []byte) error {
+	if m.restoreFolderFn != nil {
+		return m.restoreFolderFn(ctx, id, targetParentID, targetProvided, restoredBy)
+	}
+	return filemanager.ErrFolderNotFound
+}
+
+func (m *fileManagerFolderHandlerServiceMock) RestoreFile(ctx context.Context, id []byte, targetFolderID []byte, targetProvided bool, restoredBy []byte) error {
+	if m.restoreFileFn != nil {
+		return m.restoreFileFn(ctx, id, targetFolderID, targetProvided, restoredBy)
+	}
+	return filemanager.ErrFileNotFound
+}
+
+func (m *fileManagerFolderHandlerServiceMock) GetFolderByID(ctx context.Context, id []byte) (*filemanager.Folder, error) {
+	if m.getFolderFn != nil {
+		return m.getFolderFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerFolderHandlerServiceMock) GetFileByID(ctx context.Context, id []byte) (*filemanager.File, error) {
+	if m.getFileFn != nil {
+		return m.getFileFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerFolderHandlerServiceMock) GetOrCreateSystemRootFolder(ctx context.Context) (*filemanager.Folder, error) {
+	if m.getRootFn != nil {
+		return m.getRootFn(ctx)
+	}
+	return &filemanager.Folder{ID: uuidv7.MustBytes()}, nil
+}
+
+func (m *fileManagerFolderHandlerServiceMock) PurgeFolderNode(ctx context.Context, id []byte) error {
+	if m.purgeFolderFn != nil {
+		return m.purgeFolderFn(ctx, id)
+	}
+	return filemanager.ErrFolderNotFound
+}
+
+func (m *fileManagerFolderHandlerServiceMock) PurgeFileNode(ctx context.Context, id []byte) error {
+	if m.purgeFileFn != nil {
+		return m.purgeFileFn(ctx, id)
+	}
+	return filemanager.ErrFileNotFound
+}
+
+func (m *fileManagerFolderHandlerServiceMock) ListFoldersByParent(ctx context.Context, parentID []byte, sort string, limit, offset int) ([]filemanager.Folder, int64, error) {
+	if m.listFoldersFn != nil {
+		return m.listFoldersFn(ctx, parentID, sort, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func (m *fileManagerFolderHandlerServiceMock) ListNodesByParent(ctx context.Context, parentID []byte) ([]filemanager.Folder, []filemanager.File, error) {
+	if m.listNodesFn != nil {
+		return m.listNodesFn(ctx, parentID)
+	}
+	return nil, nil, nil
+}
+
+func (m *fileManagerFolderHandlerServiceMock) ListTrashFoldersByParent(ctx context.Context, parentID []byte, sort string, limit, offset int) ([]filemanager.Folder, int64, error) {
+	if m.listTrashFoldersFn != nil {
+		return m.listTrashFoldersFn(ctx, parentID, sort, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func (m *fileManagerFolderHandlerServiceMock) ListTrashNodes(ctx context.Context) ([]filemanager.Folder, []filemanager.File, error) {
+	if m.listTrashNodesFn != nil {
+		return m.listTrashNodesFn(ctx)
+	}
+	return nil, nil, nil
+}
+
+func newFileManagerFolderHandlerMoveTestApp(h *FileManagerFolderHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", append([]byte(nil), actor...))
+		}
+		return c.Next()
+	})
+	app.Patch("/api/v1/file-manager/move", h.MoveNodes)
+	app.Delete("/api/v1/file-manager/delete", h.DeleteNodesBulk)
+	app.Patch("/api/v1/file-manager/restore", h.RestoreNodesBulk)
+	app.Delete("/api/v1/file-manager/purge-delete", h.PurgeNodesBulk)
+	app.Post("/api/v1/file-manager/folders/create", h.CreateFolder)
+	app.Get("/api/v1/file-manager/folders/get/:uuid", h.GetFolder)
+	app.Get("/api/v1/file-manager/folders/get-all", h.ListFolders)
+	app.Get("/api/v1/file-manager/get-all", h.ListAll)
+	app.Get("/api/v1/file-manager/folders/trash/get-all", h.ListTrashFolders)
+	app.Get("/api/v1/file-manager/trash/get-all", h.ListTrashItems)
+	app.Patch("/api/v1/file-manager/folders/update/:uuid", h.UpdateFolder)
+	app.Delete("/api/v1/file-manager/folders/delete/:uuid", h.DeleteFolder)
+	app.Patch("/api/v1/file-manager/folders/restore/:uuid", h.RestoreFolder)
+	return app
+}
+
+func TestReplacePathPrefix(t *testing.T) {
+	tests := []struct {
+		name      string
+		pathCache string
+		oldPrefix string
+		newPrefix string
+		want      string
+	}{
+		{name: "same path", pathCache: "/root/a", oldPrefix: "/root/a", newPrefix: "/x/a", want: "/x/a"},
+		{name: "descendant path", pathCache: "/root/a/b/c", oldPrefix: "/root/a", newPrefix: "/x/a", want: "/x/a/b/c"},
+		{name: "unrelated path", pathCache: "/other/a", oldPrefix: "/root/a", newPrefix: "/x/a", want: "/other/a"},
+		{name: "empty old prefix", pathCache: "/root/a", oldPrefix: "", newPrefix: "/x/a", want: "/root/a"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := replacePathPrefix(tc.pathCache, tc.oldPrefix, tc.newPrefix); got != tc.want {
+				t.Fatalf("replacePathPrefix() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestParentPathFromCache(t *testing.T) {
+	tests := []struct {
+		name string
+		path string
+		want string
+	}{
+		{name: "root node", path: "/root", want: ""},
+		{name: "nested node", path: "/root/ops", want: "/root"},
+		{name: "deep nested", path: "/root/ops/dev", want: "/root/ops"},
+		{name: "with trailing slash", path: "/root/ops/", want: "/root"},
+		{name: "empty", path: "", want: ""},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := parentPathFromCache(tc.path); got != tc.want {
+				t.Fatalf("parentPathFromCache() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestParseUploadNameOverrides(t *testing.T) {
+	tests := []struct {
+		name       string
+		formValues map[string][]string
+		filesCount int
+		wantLen    int
+		wantErr    bool
+	}{
+		{
+			name:       "use names",
+			formValues: map[string][]string{"names": {"a.pdf", "b.pdf"}},
+			filesCount: 2,
+			wantLen:    2,
+		},
+		{
+			name:       "fallback to name",
+			formValues: map[string][]string{"name": {"a.pdf"}},
+			filesCount: 1,
+			wantLen:    1,
+		},
+		{
+			name:       "mismatch count",
+			formValues: map[string][]string{"names": {"a.pdf"}},
+			filesCount: 2,
+			wantErr:    true,
+		},
+		{
+			name:       "empty override allowed",
+			formValues: map[string][]string{},
+			filesCount: 3,
+			wantLen:    0,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := parseUploadNameOverrides(tc.formValues, tc.filesCount)
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got nil")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if len(got) != tc.wantLen {
+				t.Fatalf("len(overrides) = %d, want %d", len(got), tc.wantLen)
+			}
+		})
+	}
+}
+
+func TestIsFileManagerCreateBulkPayload(t *testing.T) {
+	tests := []struct {
+		name    string
+		body    string
+		want    bool
+		wantErr bool
+	}{
+		{name: "single object", body: `{"data":{"type":"file_manager_file_create","attributes":{"upload_file_uuid":"x"}}}`, want: false},
+		{name: "bulk array", body: `{"data":[{"type":"file_manager_file_create","attributes":{"upload_file_uuid":"x"}}]}`, want: true},
+		{name: "empty data", body: `{"data":null}`, want: false},
+		{name: "invalid json", body: `{`, wantErr: true},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := isFileManagerCreateBulkPayload([]byte(tc.body))
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got nil")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if got != tc.want {
+				t.Fatalf("isFileManagerCreateBulkPayload() = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestFileManagerFolderHandlerMoveNodes(t *testing.T) {
+	t.Run("moves folder and file in one bulk request", func(t *testing.T) {
+		actorID := uuidv7.MustBytes()
+		folderID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		destinationID := uuidv7.MustBytes()
+		destinationUUID := mustUUIDStringFileManager(t, destinationID)
+
+		svc := &fileManagerFolderHandlerServiceMock{
+			moveFolderFn: func(_ context.Context, id []byte, _ filemanager.MoveFolderParams) (*filemanager.Folder, error) {
+				if bytes.Equal(id, folderID) {
+					return &filemanager.Folder{ID: folderID}, nil
+				}
+				return nil, filemanager.ErrFolderNotFound
+			},
+			moveFileFn: func(_ context.Context, id []byte, _ filemanager.MoveFileParams) (*filemanager.File, error) {
+				if bytes.Equal(id, fileID) {
+					return &filemanager.File{ID: fileID}, nil
+				}
+				return nil, filemanager.ErrFileNotFound
+			},
+		}
+
+		h := NewFileManagerFolderHandler(svc, nil)
+		app := newFileManagerFolderHandlerMoveTestApp(h, actorID)
+
+		body := []byte(`{"data":[{"uuid":"` + mustUUIDStringFileManager(t, folderID) + `","destination_folder_uuid":"` + destinationUUID + `"},{"uuid":"` + mustUUIDStringFileManager(t, fileID) + `","destination_folder_uuid":null}]}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/file-manager/move", bytes.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+
+		var out map[string]any
+		if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+			t.Fatalf("decode response: %v", err)
+		}
+		data, ok := out["data"].([]any)
+		if !ok || len(data) != 2 {
+			t.Fatalf("expected 2 data items, got %#v", out["data"])
+		}
+
+		first, _ := data[0].(map[string]any)
+		if success, _ := first["success"].(bool); !success {
+			t.Fatalf("first item should succeed: %#v", first)
+		}
+		firstRes, _ := first["resource"].(map[string]any)
+		firstAttrs, _ := firstRes["attributes"].(map[string]any)
+		if firstAttrs["node_type"] != "folder" {
+			t.Fatalf("first node_type should be folder, got %#v", firstAttrs["node_type"])
+		}
+		firstLoc, _ := firstAttrs["location"].(map[string]any)
+		if firstLoc["folder_id"] != destinationUUID {
+			t.Fatalf("first folder_id mismatch: %#v", firstLoc["folder_id"])
+		}
+
+		second, _ := data[1].(map[string]any)
+		if success, _ := second["success"].(bool); !success {
+			t.Fatalf("second item should succeed: %#v", second)
+		}
+		secondRes, _ := second["resource"].(map[string]any)
+		secondAttrs, _ := secondRes["attributes"].(map[string]any)
+		if secondAttrs["node_type"] != "file" {
+			t.Fatalf("second node_type should be file, got %#v", secondAttrs["node_type"])
+		}
+		if _, exists := secondAttrs["location"]; exists {
+			t.Fatalf("location should be omitted for root move")
+		}
+	})
+
+	t.Run("returns item error for invalid uuid", func(t *testing.T) {
+		h := NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{}, nil)
+		app := newFileManagerFolderHandlerMoveTestApp(h, nil)
+
+		body := []byte(`{"data":[{"uuid":"invalid-uuid","destination_folder_uuid":null}]}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/file-manager/move", bytes.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+
+		var out map[string]any
+		if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+			t.Fatalf("decode response: %v", err)
+		}
+		data, _ := out["data"].([]any)
+		item, _ := data[0].(map[string]any)
+		if success, _ := item["success"].(bool); success {
+			t.Fatalf("item should fail for invalid uuid")
+		}
+		errObj, _ := item["error"].(map[string]any)
+		if errObj["status"] != float64(422) {
+			t.Fatalf("status should be 422, got %#v", errObj["status"])
+		}
+	})
+
+	t.Run("treats destination null as system root for file move", func(t *testing.T) {
+		fileID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		var capturedFolderID []byte
+		var capturedFolderProvided bool
+
+		svc := &fileManagerFolderHandlerServiceMock{
+			moveFolderFn: func(_ context.Context, _ []byte, _ filemanager.MoveFolderParams) (*filemanager.Folder, error) {
+				return nil, filemanager.ErrFolderNotFound
+			},
+			moveFileFn: func(_ context.Context, id []byte, params filemanager.MoveFileParams) (*filemanager.File, error) {
+				if !bytes.Equal(id, fileID) {
+					return nil, filemanager.ErrFileNotFound
+				}
+				capturedFolderID = append([]byte(nil), params.FolderID...)
+				capturedFolderProvided = params.FolderProvided
+				return &filemanager.File{ID: fileID}, nil
+			},
+			getRootFn: func(_ context.Context) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: rootID}, nil
+			},
+		}
+
+		h := NewFileManagerFolderHandler(svc, nil)
+		app := newFileManagerFolderHandlerMoveTestApp(h, nil)
+
+		body := []byte(`{"data":[{"uuid":"` + mustUUIDStringFileManager(t, fileID) + `","destination_folder_uuid":null}]}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/file-manager/move", bytes.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+
+		if !capturedFolderProvided {
+			t.Fatalf("expected folder move to be provided")
+		}
+		if !bytes.Equal(capturedFolderID, rootID) {
+			t.Fatalf("expected root folder id %q, got %q", mustUUIDStringFileManager(t, rootID), mustUUIDStringFileManager(t, capturedFolderID))
+		}
+	})
+}
+
+func TestFileManagerFolderHandlerPurgeNodesBulk(t *testing.T) {
+	t.Run("purges folder and file in one bulk request", func(t *testing.T) {
+		folderID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+
+		svc := &fileManagerFolderHandlerServiceMock{
+			purgeFolderFn: func(_ context.Context, id []byte) error {
+				if bytes.Equal(id, folderID) {
+					return nil
+				}
+				return filemanager.ErrFolderNotFound
+			},
+			purgeFileFn: func(_ context.Context, id []byte) error {
+				if bytes.Equal(id, fileID) {
+					return nil
+				}
+				return filemanager.ErrFileNotFound
+			},
+		}
+
+		h := NewFileManagerFolderHandler(svc, nil)
+		app := newFileManagerFolderHandlerMoveTestApp(h, nil)
+
+		body := []byte(`{"data":[{"uuid":"` + mustUUIDStringFileManager(t, folderID) + `"},{"uuid":"` + mustUUIDStringFileManager(t, fileID) + `"}]}`)
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/file-manager/purge-delete", bytes.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+
+		var out map[string]any
+		if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+			t.Fatalf("decode response: %v", err)
+		}
+		data, _ := out["data"].([]any)
+		if len(data) != 2 {
+			t.Fatalf("expected 2 items, got %d", len(data))
+		}
+
+		first, _ := data[0].(map[string]any)
+		firstRes, _ := first["resource"].(map[string]any)
+		firstAttrs, _ := firstRes["attributes"].(map[string]any)
+		if firstAttrs["node_type"] != "folder" {
+			t.Fatalf("expected first node_type folder, got %#v", firstAttrs["node_type"])
+		}
+
+		second, _ := data[1].(map[string]any)
+		secondRes, _ := second["resource"].(map[string]any)
+		secondAttrs, _ := secondRes["attributes"].(map[string]any)
+		if secondAttrs["node_type"] != "file" {
+			t.Fatalf("expected second node_type file, got %#v", secondAttrs["node_type"])
+		}
+	})
+}
+
+func TestFileManagerFolderHandlerDeleteNodesBulk(t *testing.T) {
+	folderID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	svc := &fileManagerFolderHandlerServiceMock{
+		deleteFolderFn: func(_ context.Context, id []byte, _ []byte, _ *time.Time) error {
+			if bytes.Equal(id, folderID) {
+				return nil
+			}
+			return filemanager.ErrFolderNotFound
+		},
+		deleteFileFn: func(_ context.Context, id []byte, _ []byte, _ *time.Time) error {
+			if bytes.Equal(id, fileID) {
+				return nil
+			}
+			return filemanager.ErrFileNotFound
+		},
+	}
+	h := NewFileManagerFolderHandler(svc, nil)
+	app := newFileManagerFolderHandlerMoveTestApp(h, uuidv7.MustBytes())
+	body := []byte(`{"data":[{"uuid":"` + mustUUIDStringFileManager(t, folderID) + `"},{"uuid":"` + mustUUIDStringFileManager(t, fileID) + `"}]}`)
+	req, _ := http.NewRequest(http.MethodDelete, "/api/v1/file-manager/delete", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestFileManagerFolderHandlerRestoreNodesBulk(t *testing.T) {
+	folderID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	parentID := uuidv7.MustBytes()
+	rootID := uuidv7.MustBytes()
+	svc := &fileManagerFolderHandlerServiceMock{
+		restoreFolderFn: func(_ context.Context, id []byte, _ []byte, _ bool, _ []byte) error {
+			if bytes.Equal(id, folderID) {
+				return nil
+			}
+			return filemanager.ErrFolderNotFound
+		},
+		restoreFileFn: func(_ context.Context, id []byte, _ []byte, _ bool, _ []byte) error {
+			if bytes.Equal(id, fileID) {
+				return nil
+			}
+			return filemanager.ErrFileNotFound
+		},
+		getFolderFn: func(_ context.Context, id []byte) (*filemanager.Folder, error) {
+			if bytes.Equal(id, folderID) {
+				return &filemanager.Folder{ID: folderID, ParentID: parentID}, nil
+			}
+			return nil, nil
+		},
+		getFileFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+			if bytes.Equal(id, fileID) {
+				return &filemanager.File{ID: fileID, FolderID: rootID}, nil
+			}
+			return nil, nil
+		},
+		getRootFn: func(_ context.Context) (*filemanager.Folder, error) {
+			return &filemanager.Folder{ID: rootID}, nil
+		},
+	}
+	h := NewFileManagerFolderHandler(svc, nil)
+	app := newFileManagerFolderHandlerMoveTestApp(h, uuidv7.MustBytes())
+	body := []byte(`{"data":[{"uuid":"` + mustUUIDStringFileManager(t, folderID) + `"},{"uuid":"` + mustUUIDStringFileManager(t, fileID) + `"}]}`)
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/file-manager/restore", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestFileManagerFolderHandlerReadAndHelperCoverage(t *testing.T) {
+	t.Run("create get list update delete restore", func(t *testing.T) {
+		folderID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+		svc := &fileManagerFolderHandlerServiceMock{
+			createFolderFn: func(_ context.Context, params filemanager.CreateFolderParams) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: folderID, ParentID: params.ParentID, Name: params.Name, NameNormalized: strings.ToLower(params.Name), CreatedAt: now, UpdatedAt: now}, nil
+			},
+			getFolderFn: func(_ context.Context, id []byte) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: id, ParentID: rootID, Name: "Ops", NameNormalized: "ops", Depth: 1, CreatedAt: now, UpdatedAt: now}, nil
+			},
+			listFoldersFn: func(_ context.Context, _ []byte, _ string, _ int, _ int) ([]filemanager.Folder, int64, error) {
+				return []filemanager.Folder{{ID: folderID, ParentID: rootID, Name: "Ops", NameNormalized: "ops", CreatedAt: now, UpdatedAt: now}}, 1, nil
+			},
+			listNodesFn: func(_ context.Context, _ []byte) ([]filemanager.Folder, []filemanager.File, error) {
+				return []filemanager.Folder{{ID: folderID, ParentID: rootID, Name: "Ops", PathCache: "/Ops", CreatedAt: now, UpdatedAt: now}},
+					[]filemanager.File{{ID: uuidv7.MustBytes(), FolderID: rootID, Name: "a.pdf", ObjectKey: "files/a.pdf", MimeType: "application/pdf", Status: filemanager.FileStatusReady, CreatedAt: now, UpdatedAt: now}}, nil
+			},
+			listTrashFoldersFn: func(_ context.Context, _ []byte, _ string, _ int, _ int) ([]filemanager.Folder, int64, error) {
+				deletedAt := now.Add(-time.Hour)
+				return []filemanager.Folder{{ID: folderID, ParentID: rootID, Name: "Trash", NameNormalized: "trash", CreatedAt: now, UpdatedAt: now, DeletedAt: &deletedAt}}, 1, nil
+			},
+			listTrashNodesFn: func(_ context.Context) ([]filemanager.Folder, []filemanager.File, error) {
+				deletedAt := now.Add(-time.Hour)
+				return []filemanager.Folder{{ID: folderID, ParentID: rootID, Name: "Trash", PathCache: "/Trash", CreatedAt: now, UpdatedAt: now, DeletedAt: &deletedAt}},
+					[]filemanager.File{{ID: uuidv7.MustBytes(), FolderID: rootID, Name: "gone.pdf", ObjectKey: "files/gone.pdf", MimeType: "application/pdf", SizeBytes: 10, CreatedAt: now, UpdatedAt: now, DeletedAt: &deletedAt}}, nil
+			},
+			moveFolderFn: func(_ context.Context, id []byte, _ filemanager.MoveFolderParams) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: id, ParentID: rootID, Name: "Renamed", NameNormalized: "renamed", CreatedAt: now, UpdatedAt: now}, nil
+			},
+			deleteFolderFn:  func(context.Context, []byte, []byte, *time.Time) error { return nil },
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getRootFn:       func(context.Context) (*filemanager.Folder, error) { return &filemanager.Folder{ID: rootID}, nil },
+		}
+		h := NewFileManagerFolderHandler(svc, &fileManagerDownloadURLStorageMock{presignedURL: "https://signed/file.pdf"})
+		app := newFileManagerFolderHandlerMoveTestApp(h, uuidv7.MustBytes())
+
+		createBody := []byte(`{"data":{"type":"file_manager_folder","attributes":{"name":"Ops"}}}`)
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/folders/create", createBody)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201 create, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/folders/get/"+mustUUIDStringFileManager(t, folderID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 get, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/folders/get-all", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 list folders, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/get-all", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 list all, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/folders/trash/get-all", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 list trash folders, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/trash/get-all?sort=name", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 list trash items, got %d", resp.StatusCode)
+		}
+
+		updateBody := []byte(`{"data":{"type":"file_manager_folder","id":"` + mustUUIDStringFileManager(t, folderID) + `","attributes":{"name":"Renamed"}}}`)
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/folders/update/"+mustUUIDStringFileManager(t, folderID), updateBody)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 update, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/folders/delete/"+mustUUIDStringFileManager(t, folderID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 delete folder, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/folders/restore/"+mustUUIDStringFileManager(t, folderID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 restore folder, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("helper resources and sorting", func(t *testing.T) {
+		now := time.Now().UTC()
+		deletedAt := now.Add(-time.Hour)
+		folder := &filemanager.Folder{ID: uuidv7.MustBytes(), ParentID: uuidv7.MustBytes(), Name: "Ops", NameNormalized: "ops", PathCache: "/Ops", Depth: 1, CreatedAt: now, UpdatedAt: now, DeletedAt: &deletedAt}
+		file := &filemanager.File{ID: uuidv7.MustBytes(), FolderID: folder.ID, Name: "a.pdf", Extension: "pdf", MimeType: "application/pdf", SizeBytes: 10, Status: filemanager.FileStatusReady, CreatedAt: now, UpdatedAt: now}
+		if fileManagerFolderResource(folder).Type != "file_manager_folder" {
+			t.Fatalf("unexpected folder resource type")
+		}
+		if fileManagerFolderDetailResource(folder).Attributes.Location == nil {
+			t.Fatalf("expected folder detail location")
+		}
+		if fileManagerNodeFromFolder(folder, false).Attributes.ParentID == nil {
+			t.Fatalf("expected node parent id")
+		}
+		if fileManagerNodeFromFile(file, true, "https://signed").Attributes.ParentID != nil {
+			t.Fatalf("expected nil parent id at root")
+		}
+		parentID := fileManagerNodeParentID(folder.ID, false)
+		if parentID == nil || *parentID == "" {
+			t.Fatalf("expected non-empty parent id")
+		}
+
+		items := []fileManagerTrashItemView{
+			{Name: "b", NodeType: "file", SizeBytes: 1, DeletedAt: now},
+			{Name: "a", NodeType: "folder", SizeBytes: 2, DeletedAt: deletedAt},
+		}
+		sortFileManagerTrashItems(items, "name")
+		if items[0].Name != "a" {
+			t.Fatalf("expected sorted by name")
+		}
+		sortFileManagerTrashItems(items, "-type")
+		sortFileManagerTrashItems(items, "size_bytes")
+		sortFileManagerTrashItems(items, "")
+	})
+
+	t.Run("breadcrumb parse uuid and pagination", func(t *testing.T) {
+		now := time.Now().UTC()
+		rootID := uuidv7.MustBytes()
+		childID := uuidv7.MustBytes()
+		svc := &fileManagerFolderHandlerServiceMock{
+			getFolderFn: func(_ context.Context, id []byte) (*filemanager.Folder, error) {
+				if bytes.Equal(id, childID) {
+					return &filemanager.Folder{ID: childID, ParentID: rootID, Name: "Child", CreatedAt: now, UpdatedAt: now}, nil
+				}
+				if bytes.Equal(id, rootID) {
+					return &filemanager.Folder{ID: rootID, Name: "Root", CreatedAt: now, UpdatedAt: now}, nil
+				}
+				return nil, nil
+			},
+		}
+		h := NewFileManagerFolderHandler(svc, nil)
+		app := fiber.New()
+		app.Get("/:uuid", func(c *fiber.Ctx) error {
+			if _, err := h.parseUUIDParam(c, "uuid", "/path/uuid"); err != nil {
+				return err
+			}
+			page, size, offset := parseFileManagerFolderPagination(c)
+			if page != 1 || size != 100 || offset != 0 {
+				t.Fatalf("unexpected pagination %d %d %d", page, size, offset)
+			}
+			breadcrumb, err := h.buildExplorerBreadcrumb(c.Context(), childID)
+			if err != nil || len(breadcrumb) != 2 {
+				t.Fatalf("unexpected breadcrumb len=%d err=%v", len(breadcrumb), err)
+			}
+			if replacePathPrefix("/root/a", "/root", "/new") != "/new/a" {
+				t.Fatalf("unexpected replacePathPrefix")
+			}
+			if parentPathFromCache("/root/a/b") != "/root/a" {
+				t.Fatalf("unexpected parentPathFromCache")
+			}
+			return nil
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/bad?page[number]=0&page[size]=999", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestFileManagerFolderHandlerValidationAndErrorCoverage(t *testing.T) {
+	t.Run("folder endpoint validation and action errors", func(t *testing.T) {
+		folderID := uuidv7.MustBytes()
+		parentID := uuidv7.MustBytes()
+		svc := &fileManagerFolderHandlerServiceMock{
+			createFolderFn: func(context.Context, filemanager.CreateFolderParams) (*filemanager.Folder, error) {
+				return nil, filemanager.ErrDuplicateName
+			},
+			getFolderFn: func(context.Context, []byte) (*filemanager.Folder, error) {
+				return nil, errors.New("get failure")
+			},
+			listFoldersFn: func(context.Context, []byte, string, int, int) ([]filemanager.Folder, int64, error) {
+				return nil, 0, errors.New("list folders failure")
+			},
+			listNodesFn: func(context.Context, []byte) ([]filemanager.Folder, []filemanager.File, error) {
+				return nil, nil, errors.New("list nodes failure")
+			},
+			listTrashFoldersFn: func(context.Context, []byte, string, int, int) ([]filemanager.Folder, int64, error) {
+				return nil, 0, errors.New("list trash folders failure")
+			},
+			moveFolderFn: func(context.Context, []byte, filemanager.MoveFolderParams) (*filemanager.Folder, error) {
+				return nil, filemanager.ErrFolderNotFound
+			},
+			deleteFolderFn: func(context.Context, []byte, []byte, *time.Time) error {
+				return filemanager.ErrFolderNotFound
+			},
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error {
+				return filemanager.ErrFolderNotFound
+			},
+		}
+		h := NewFileManagerFolderHandler(svc, nil)
+		app := newFileManagerFolderHandlerMoveTestApp(h, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/folders/create", []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid create folder json, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/folders/create", []byte(`{"data":{"type":"file_manager_folder","attributes":{"name":"Ops","parent_id":"not-a-uuid"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid parent id, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPost, "/api/v1/file-manager/folders/create", []byte(`{"data":{"type":"file_manager_folder","attributes":{"name":"Ops","parent_id":"`+mustUUIDStringFileManager(t, parentID)+`"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 create folder action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/folders/get/not-a-uuid", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid get folder uuid path handling, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/folders/get/"+mustUUIDStringFileManager(t, folderID), nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 get folder action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/folders/get-all?parent_uuid=not-a-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid list parent uuid, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/folders/get-all?parent_uuid="+mustUUIDStringFileManager(t, parentID), nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 list folders action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/get-all?parent_uuid=not-a-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid list all parent uuid, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/get-all?parent_uuid="+mustUUIDStringFileManager(t, parentID), nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 list all action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/folders/trash/get-all?parent_uuid=not-a-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid trash parent uuid, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/folders/trash/get-all?parent_uuid="+mustUUIDStringFileManager(t, parentID), nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 list trash folders action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/folders/update/not-a-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid update folder uuid, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/folders/update/"+mustUUIDStringFileManager(t, folderID), []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid update folder json, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/folders/update/"+mustUUIDStringFileManager(t, folderID), []byte(`{"data":{"type":"file_manager_folder","id":"other","attributes":{"name":"Renamed"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 update folder id mismatch, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/folders/update/"+mustUUIDStringFileManager(t, folderID), []byte(`{"data":{"type":"file_manager_folder","id":"`+mustUUIDStringFileManager(t, folderID)+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 update folder no attrs, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/folders/update/"+mustUUIDStringFileManager(t, folderID), []byte(`{"data":{"type":"file_manager_folder","id":"`+mustUUIDStringFileManager(t, folderID)+`","attributes":{"parent_id":"not-a-uuid"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid update folder parent id, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/folders/update/"+mustUUIDStringFileManager(t, folderID), []byte(`{"data":{"type":"file_manager_folder","id":"`+mustUUIDStringFileManager(t, folderID)+`","attributes":{"name":"Renamed"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 update folder action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/folders/delete/not-a-uuid", nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 invalid delete folder uuid path handling, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/folders/delete/"+mustUUIDStringFileManager(t, folderID), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 delete folder action error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/folders/restore/not-a-uuid", nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 invalid restore folder uuid path handling, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/folders/restore/"+mustUUIDStringFileManager(t, folderID), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 restore folder action error, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("bulk handlers and helper error branches", func(t *testing.T) {
+		folderID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		parentID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		svc := &fileManagerFolderHandlerServiceMock{
+			moveFolderFn: func(_ context.Context, id []byte, _ filemanager.MoveFolderParams) (*filemanager.Folder, error) {
+				if bytes.Equal(id, folderID) {
+					return nil, errors.New("move folder failure")
+				}
+				return nil, filemanager.ErrFolderNotFound
+			},
+			moveFileFn: func(_ context.Context, id []byte, _ filemanager.MoveFileParams) (*filemanager.File, error) {
+				if bytes.Equal(id, fileID) {
+					return nil, errors.New("move file failure")
+				}
+				return nil, filemanager.ErrFileNotFound
+			},
+			deleteFolderFn: func(_ context.Context, id []byte, _ []byte, _ *time.Time) error {
+				if bytes.Equal(id, folderID) {
+					return errors.New("delete folder failure")
+				}
+				return filemanager.ErrFolderNotFound
+			},
+			deleteFileFn: func(_ context.Context, id []byte, _ []byte, _ *time.Time) error {
+				if bytes.Equal(id, fileID) {
+					return errors.New("delete file failure")
+				}
+				return filemanager.ErrFileNotFound
+			},
+			restoreFolderFn: func(_ context.Context, id []byte, _ []byte, _ bool, _ []byte) error {
+				if bytes.Equal(id, folderID) {
+					return errors.New("restore folder failure")
+				}
+				return filemanager.ErrFolderNotFound
+			},
+			restoreFileFn: func(_ context.Context, id []byte, _ []byte, _ bool, _ []byte) error {
+				if bytes.Equal(id, fileID) {
+					return nil
+				}
+				return filemanager.ErrFileNotFound
+			},
+			getFileFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+				if bytes.Equal(id, fileID) {
+					return nil, errors.New("get file failure")
+				}
+				return nil, nil
+			},
+			getFolderFn: func(_ context.Context, id []byte) (*filemanager.Folder, error) {
+				if bytes.Equal(id, parentID) {
+					return nil, errors.New("breadcrumb failure")
+				}
+				return nil, nil
+			},
+			getRootFn: func(context.Context) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: rootID}, nil
+			},
+			purgeFolderFn: func(_ context.Context, id []byte) error {
+				if bytes.Equal(id, folderID) {
+					return errors.New("purge folder failure")
+				}
+				return filemanager.ErrFolderNotFound
+			},
+			purgeFileFn: func(_ context.Context, id []byte) error {
+				if bytes.Equal(id, fileID) {
+					return filemanager.ErrFileNotFound
+				}
+				return errors.New("purge file failure")
+			},
+		}
+		h := NewFileManagerFolderHandler(svc, nil)
+		app := newFileManagerFolderHandlerMoveTestApp(h, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/move", []byte(`{"data":[{"uuid":"`+mustUUIDStringFileManager(t, folderID)+`","destination_folder_uuid":"`+mustUUIDStringFileManager(t, parentID)+`"},{"uuid":"`+mustUUIDStringFileManager(t, fileID)+`","destination_folder_uuid":null},{"uuid":"not-a-uuid","destination_folder_uuid":null}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 move bulk mixed errors, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/delete", []byte(`{"data":[{"uuid":"`+mustUUIDStringFileManager(t, folderID)+`"},{"uuid":"`+mustUUIDStringFileManager(t, fileID)+`"}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 delete bulk mixed errors, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodPatch, "/api/v1/file-manager/restore", []byte(`{"data":[{"uuid":"`+mustUUIDStringFileManager(t, folderID)+`"},{"uuid":"`+mustUUIDStringFileManager(t, fileID)+`"}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 restore bulk mixed errors, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodDelete, "/api/v1/file-manager/purge-delete", []byte(`{"data":[{"uuid":"`+mustUUIDStringFileManager(t, folderID)+`"},{"uuid":"`+mustUUIDStringFileManager(t, fileID)+`"}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 purge bulk mixed errors, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doJSONRequestFileManagerFile(t, app, http.MethodGet, "/api/v1/file-manager/get-all?parent_uuid="+mustUUIDStringFileManager(t, parentID), nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 breadcrumb error, got %d", resp.StatusCode)
+		}
+
+		if fileManagerMoveBulkActionErrorItem(0, errFileManagerNodeNotFound).Error.Status != http.StatusNotFound {
+			t.Fatalf("expected move action helper to map not found")
+		}
+		item := fileManagerPurgeBulkSystemErrorItem(0, http.StatusConflict, "Conflict", "duplicate")
+		if item.Error == nil || item.Error.Status != http.StatusConflict {
+			t.Fatalf("expected purge helper error item")
+		}
+	})
+
+	t.Run("remaining folder branches", func(t *testing.T) {
+		folderID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		parentID := uuidv7.MustBytes()
+		now := time.Now().UTC()
+
+		appNotFound := newFileManagerFolderHandlerMoveTestApp(NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			getFolderFn: func(context.Context, []byte) (*filemanager.Folder, error) { return nil, nil },
+		}, nil), uuidv7.MustBytes())
+		resp, _ := doJSONRequestFileManagerFile(t, appNotFound, http.MethodGet, "/api/v1/file-manager/folders/get/"+mustUUIDStringFileManager(t, folderID), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 get folder not found, got %d", resp.StatusCode)
+		}
+
+		appRestoreRootErr := newFileManagerFolderHandlerMoveTestApp(NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFolderFn: func(_ context.Context, id []byte) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: id, ParentID: parentID, Name: "Ops", CreatedAt: now, UpdatedAt: now}, nil
+			},
+			getRootFn: func(context.Context) (*filemanager.Folder, error) { return nil, errors.New("root fail") },
+		}, nil), uuidv7.MustBytes())
+		resp, _ = doJSONRequestFileManagerFile(t, appRestoreRootErr, http.MethodPatch, "/api/v1/file-manager/folders/restore/"+mustUUIDStringFileManager(t, folderID), nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 restore folder root error, got %d", resp.StatusCode)
+		}
+
+		appRestoreNonRoot := newFileManagerFolderHandlerMoveTestApp(NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFolderFn: func(_ context.Context, id []byte) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: id, ParentID: parentID, Name: "Ops", CreatedAt: now, UpdatedAt: now}, nil
+			},
+			getRootFn: func(context.Context) (*filemanager.Folder, error) { return &filemanager.Folder{ID: rootID}, nil },
+		}, nil), uuidv7.MustBytes())
+		resp, body := doJSONRequestFileManagerFile(t, appRestoreNonRoot, http.MethodPatch, "/api/v1/file-manager/folders/restore/"+mustUUIDStringFileManager(t, folderID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 restore folder non-root, got %d", resp.StatusCode)
+		}
+		out := decodeJSONMapFileManagerFile(t, body)
+		data := mapField(t, out["data"], "data")
+		attrs := mapField(t, data["attributes"], "attributes")
+		location := mapField(t, attrs["location"], "location")
+		if location["folder_id"] != mustUUIDStringFileManager(t, parentID) {
+			t.Fatalf("expected restore folder location")
+		}
+
+		appRestoreMissing := newFileManagerFolderHandlerMoveTestApp(NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFolderFn:     func(context.Context, []byte) (*filemanager.Folder, error) { return nil, nil },
+		}, nil), uuidv7.MustBytes())
+		resp, _ = doJSONRequestFileManagerFile(t, appRestoreMissing, http.MethodPatch, "/api/v1/file-manager/folders/restore/"+mustUUIDStringFileManager(t, folderID), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 restore folder missing row, got %d", resp.StatusCode)
+		}
+
+		appDeleteValidation := newFileManagerFolderHandlerMoveTestApp(NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{}, nil), uuidv7.MustBytes())
+		resp, _ = doJSONRequestFileManagerFile(t, appDeleteValidation, http.MethodDelete, "/api/v1/file-manager/delete", []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 delete bulk invalid json, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, appDeleteValidation, http.MethodDelete, "/api/v1/file-manager/delete", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 delete bulk empty data, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, appDeleteValidation, http.MethodDelete, "/api/v1/file-manager/delete", []byte(`{"data":[{"uuid":""}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 delete bulk item validation error, got %d", resp.StatusCode)
+		}
+
+		appRestoreValidation := newFileManagerFolderHandlerMoveTestApp(NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return filemanager.ErrFolderNotFound },
+			restoreFileFn:   func(context.Context, []byte, []byte, bool, []byte) error { return filemanager.ErrFileNotFound },
+		}, nil), uuidv7.MustBytes())
+		resp, _ = doJSONRequestFileManagerFile(t, appRestoreValidation, http.MethodPatch, "/api/v1/file-manager/restore", []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 restore bulk invalid json, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, appRestoreValidation, http.MethodPatch, "/api/v1/file-manager/restore", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 restore bulk empty data, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, appRestoreValidation, http.MethodPatch, "/api/v1/file-manager/restore", []byte(`{"data":[{"uuid":"`+mustUUIDStringFileManager(t, folderID)+`"}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 restore bulk not found item, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, appRestoreValidation, http.MethodPatch, "/api/v1/file-manager/restore", []byte(`{"data":[{"uuid":"not-a-uuid"}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 restore bulk invalid uuid item, got %d", resp.StatusCode)
+		}
+
+		appPurgeValidation := newFileManagerFolderHandlerMoveTestApp(NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{}, nil), uuidv7.MustBytes())
+		resp, _ = doJSONRequestFileManagerFile(t, appPurgeValidation, http.MethodDelete, "/api/v1/file-manager/purge-delete", []byte(`{`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 purge bulk invalid json, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, appPurgeValidation, http.MethodDelete, "/api/v1/file-manager/purge-delete", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 purge bulk empty data, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, appPurgeValidation, http.MethodDelete, "/api/v1/file-manager/purge-delete", []byte(`{"data":[{"uuid":""}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 purge bulk item validation error, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, appDeleteValidation, http.MethodDelete, "/api/v1/file-manager/delete", []byte(`{"data":[{"uuid":"not-a-uuid"}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 delete bulk invalid uuid item, got %d", resp.StatusCode)
+		}
+		resp, _ = doJSONRequestFileManagerFile(t, appPurgeValidation, http.MethodDelete, "/api/v1/file-manager/purge-delete", []byte(`{"data":[{"uuid":"not-a-uuid"}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 purge bulk invalid uuid item, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("restore node helper edge cases", func(t *testing.T) {
+		nodeID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		parentID := uuidv7.MustBytes()
+
+		hFolderGetErr := NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFolderFn:     func(context.Context, []byte) (*filemanager.Folder, error) { return nil, errors.New("get folder fail") },
+		}, nil)
+		if _, _, err := hFolderGetErr.restoreNodeAutoDetect(context.Background(), nodeID, nil); err == nil {
+			t.Fatalf("expected restore folder get error")
+		}
+
+		hFolderNil := NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFolderFn:     func(context.Context, []byte) (*filemanager.Folder, error) { return nil, nil },
+		}, nil)
+		if _, _, err := hFolderNil.restoreNodeAutoDetect(context.Background(), nodeID, nil); !errors.Is(err, errFileManagerNodeNotFound) {
+			t.Fatalf("expected restore folder missing node, got %v", err)
+		}
+
+		hFolderRootErr := NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFolderFn: func(_ context.Context, id []byte) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: id, ParentID: parentID}, nil
+			},
+			getRootFn: func(context.Context) (*filemanager.Folder, error) { return nil, errors.New("root fail") },
+		}, nil)
+		if _, _, err := hFolderRootErr.restoreNodeAutoDetect(context.Background(), nodeID, nil); err == nil {
+			t.Fatalf("expected restore folder root error")
+		}
+
+		hFolderRoot := NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFolderFn: func(_ context.Context, id []byte) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: id, ParentID: rootID}, nil
+			},
+			getRootFn: func(context.Context) (*filemanager.Folder, error) { return &filemanager.Folder{ID: rootID}, nil },
+		}, nil)
+		nodeType, location, err := hFolderRoot.restoreNodeAutoDetect(context.Background(), nodeID, nil)
+		if err != nil || nodeType != "folder" || location != "" {
+			t.Fatalf("expected restore folder root success, got type=%s location=%s err=%v", nodeType, location, err)
+		}
+
+		hFileNil := NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return filemanager.ErrFolderNotFound },
+			restoreFileFn:   func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFileFn:       func(context.Context, []byte) (*filemanager.File, error) { return nil, nil },
+		}, nil)
+		if _, _, err := hFileNil.restoreNodeAutoDetect(context.Background(), nodeID, nil); !errors.Is(err, errFileManagerNodeNotFound) {
+			t.Fatalf("expected restore file missing node, got %v", err)
+		}
+
+		hFileRootErr := NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return filemanager.ErrFolderNotFound },
+			restoreFileFn:   func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFileFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+				return &filemanager.File{ID: id, FolderID: parentID}, nil
+			},
+			getRootFn: func(context.Context) (*filemanager.Folder, error) { return nil, errors.New("root fail") },
+		}, nil)
+		if _, _, err := hFileRootErr.restoreNodeAutoDetect(context.Background(), nodeID, nil); err == nil {
+			t.Fatalf("expected restore file root error")
+		}
+
+		hFileGetErr := NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return filemanager.ErrFolderNotFound },
+			restoreFileFn:   func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFileFn:       func(context.Context, []byte) (*filemanager.File, error) { return nil, errors.New("get file fail") },
+		}, nil)
+		if _, _, err := hFileGetErr.restoreNodeAutoDetect(context.Background(), nodeID, nil); err == nil {
+			t.Fatalf("expected restore file get error")
+		}
+
+		hRestoreFileErr := NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return filemanager.ErrFolderNotFound },
+			restoreFileFn:   func(context.Context, []byte, []byte, bool, []byte) error { return errors.New("restore file fail") },
+		}, nil)
+		if _, _, err := hRestoreFileErr.restoreNodeAutoDetect(context.Background(), nodeID, nil); err == nil {
+			t.Fatalf("expected restore file action error")
+		}
+
+		hFileNonRoot := NewFileManagerFolderHandler(&fileManagerFolderHandlerServiceMock{
+			restoreFolderFn: func(context.Context, []byte, []byte, bool, []byte) error { return filemanager.ErrFolderNotFound },
+			restoreFileFn:   func(context.Context, []byte, []byte, bool, []byte) error { return nil },
+			getFileFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+				return &filemanager.File{ID: id, FolderID: parentID}, nil
+			},
+			getRootFn: func(context.Context) (*filemanager.Folder, error) { return &filemanager.Folder{ID: rootID}, nil },
+		}, nil)
+		nodeType2, location2, err := hFileNonRoot.restoreNodeAutoDetect(context.Background(), nodeID, nil)
+		if err != nil || nodeType2 != "file" || location2 != mustUUIDStringFileManager(t, parentID) {
+			t.Fatalf("expected restore file non-root location, got type=%s location=%s err=%v", nodeType2, location2, err)
+		}
+	})
+}
diff --git a/internal/transport/http/handlers/file_manager_request_helpers.go b/internal/transport/http/handlers/file_manager_request_helpers.go
new file mode 100644
index 0000000..4f620de
--- /dev/null
+++ b/internal/transport/http/handlers/file_manager_request_helpers.go
@@ -0,0 +1,98 @@
+package handlers
+
+import (
+	"context"
+	"strings"
+	"sync"
+	"time"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/metrics"
+)
+
+const fileManagerDownloadURLTTL = 15 * time.Minute
+
+type fileManagerDownloadURLStorage interface {
+	PresignGetObject(ctx context.Context, objectKey string, ttl time.Duration) (string, error)
+}
+
+type fileManagerDownloadURLs struct {
+	OriginalURL       string
+	ThumbnailURL      string
+	PreviewURL        string
+	OriginalSizeBytes int64
+}
+
+func resolveFileManagerDownloadURLs(ctx context.Context, storage fileManagerDownloadURLStorage, row *filemanager.File) fileManagerDownloadURLs {
+	if row == nil {
+		return fileManagerDownloadURLs{}
+	}
+
+	result := fileManagerDownloadURLs{
+		OriginalSizeBytes: row.SizeBytes,
+	}
+	if storage == nil {
+		return result
+	}
+
+	var wg sync.WaitGroup
+
+	if key := strings.TrimSpace(row.ObjectKey); key != "" {
+		wg.Add(1)
+		go func(k string) {
+			defer wg.Done()
+			presigned, err := storage.PresignGetObject(ctx, k, fileManagerDownloadURLTTL)
+			if err == nil && strings.TrimSpace(presigned) != "" {
+				result.OriginalURL = presigned
+				metrics.ObserveAWSTransferredBytes("api", "s3", "GetObject", "download", row.SizeBytes)
+			}
+		}(key)
+	}
+
+	if row.ThumbnailObjectKey != nil {
+		if thumbKey := strings.TrimSpace(*row.ThumbnailObjectKey); thumbKey != "" {
+			wg.Add(1)
+			go func(tk string) {
+				defer wg.Done()
+				presigned, err := storage.PresignGetObject(ctx, tk, fileManagerDownloadURLTTL)
+				if err == nil && strings.TrimSpace(presigned) != "" {
+					result.ThumbnailURL = presigned
+					metrics.ObserveAWSTransferredBytes("api", "s3", "GetObject", "download_thumbnail", row.ThumbnailSizeBytes)
+				}
+			}(thumbKey)
+		}
+	}
+
+	// Preview URL: for Office docs use the converted preview_object_key;
+	// for PDF use the original object key directly (no conversion needed).
+	if row.PreviewObjectKey != nil {
+		if previewKey := strings.TrimSpace(*row.PreviewObjectKey); previewKey != "" {
+			wg.Add(1)
+			go func(pk string) {
+				defer wg.Done()
+				presigned, err := storage.PresignGetObject(ctx, pk, fileManagerDownloadURLTTL)
+				if err == nil && strings.TrimSpace(presigned) != "" {
+					result.PreviewURL = presigned
+					metrics.ObserveAWSTransferredBytes("api", "s3", "GetObject", "download_preview", row.PreviewSizeBytes)
+				}
+			}(previewKey)
+		}
+	} else if strings.EqualFold(strings.TrimSpace(row.MimeType), "application/pdf") {
+		// PDF files are directly previewable — reuse the original presigned URL.
+		// We wait for the original URL goroutine to finish before reading it.
+		wg.Wait()
+		result.PreviewURL = result.OriginalURL
+		return result
+	}
+
+	wg.Wait()
+	return result
+}
+
+func resolveFileManagerDownloadURL(ctx context.Context, storage fileManagerDownloadURLStorage, row *filemanager.File) string {
+	return resolveFileManagerDownloadURLs(ctx, storage, row).OriginalURL
+}
+
+func resolveFileManagerThumbnailDownloadURL(ctx context.Context, storage fileManagerDownloadURLStorage, row *filemanager.File) string {
+	return resolveFileManagerDownloadURLs(ctx, storage, row).ThumbnailURL
+}
diff --git a/internal/transport/http/handlers/file_manager_template_wopi_handler.go b/internal/transport/http/handlers/file_manager_template_wopi_handler.go
new file mode 100644
index 0000000..f2cab78
--- /dev/null
+++ b/internal/transport/http/handlers/file_manager_template_wopi_handler.go
@@ -0,0 +1,1036 @@
+package handlers
+
+import (
+	"archive/zip"
+	"bytes"
+	"context"
+	"encoding/xml"
+	"errors"
+	"io"
+	"net/http"
+	"path"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanager "wucher/internal/domain/file_manager"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	takeoverdomain "wucher/internal/domain/takeover"
+	helicopterfilerealtime "wucher/internal/realtime/helicopterfile"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+	dto "wucher/internal/transport/http/dto"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+)
+
+type templateCopyStorage interface {
+	CopyObject(ctx context.Context, sourceObjectKey, destinationObjectKey string) (filemanager.ObjectMetadata, error)
+	GetObject(ctx context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error)
+	HeadObject(ctx context.Context, objectKey string) (filemanager.ObjectMetadata, error)
+	DeleteObject(ctx context.Context, objectKey string) error
+}
+
+type templateTakeoverFileLookupService interface {
+	GetFileByTemplateAndTakeover(ctx context.Context, templateUUID, takeoverID []byte) (*filemanager.File, error)
+}
+
+type uploadIntentSizeUpdater interface {
+	UpdateUploadIntentSize(ctx context.Context, params filemanager.FileUploadIntentSizeUpdateParams) error
+}
+
+type helicopterFileEventPublisher interface {
+	PublishToUsers(userUUIDs []string, event helicopterfilerealtime.Event) int
+}
+
+const (
+	wopiStorageReadyAttempts = 5
+	wopiStorageReadyDelay    = 200 * time.Millisecond
+)
+
+var _ = dto.ErrorResponse{}
+
+// CreateFromTemplate godoc
+// @Summary Create file from template and start a WOPI edit session
+// @Description Copies a helicopter template file into a new draft file and returns a Collabora/WOPI write session for the newly created file.
+// @Description This endpoint always marks the created file as `is_template=false` because the result is a normal working document, not a reusable template.
+// @Description The source template must be a helicopter file that belongs to the same `helicopter_id` provided in the request.
+// @Description `template_uuid` is the helicopter-file UUID, not the file UUID.
+// @Description Request fields: `template_uuid`, `helicopter_id`, optional `takeover_id`, and `name`.
+// @Description Success response includes the new `file_id`, Collabora editor action URL, an access token, and the token TTL in milliseconds.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FileManagerFileTemplateCreateRequest true "Create-from-template payload"
+// @Success 200 {object} responsedto.FileManagerFileWOPISessionResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 403 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/create-from-template [post]
+func (h *FileManagerFileHandler) CreateFromTemplate(c *fiber.Ctx) error {
+	if h == nil || h.svc == nil || h.heliFile == nil || h.wopi == nil || h.storage == nil {
+		return writeFileManagerError(c, fiber.StatusServiceUnavailable, "Create failed", "file manager service is not configured", nil)
+	}
+
+	var req requestdto.FileManagerFileTemplateCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFileManagerError(c, fiber.StatusBadRequest, "Invalid JSON", err.Error(), nil)
+	}
+	if strings.TrimSpace(req.Data.Type) != "file_manager_file_create_from_template" && strings.TrimSpace(req.Data.Type) != "file_manager_file_create" {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "type must be file_manager_file_create_from_template or file_manager_file_create", nil)
+	}
+
+	attrs := req.Data.Attributes
+	templateID, err := uuidv7.ParseString(strings.TrimSpace(attrs.TemplateUUID))
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "template_uuid is invalid UUID", nil)
+	}
+	helicopterID, err := uuidv7.ParseString(strings.TrimSpace(attrs.HelicopterID))
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "helicopter_id is invalid UUID", nil)
+	}
+	var takeoverID []byte
+	if takeoverRaw := strings.TrimSpace(attrs.TakeoverID); takeoverRaw != "" {
+		takeoverID, err = uuidv7.ParseString(takeoverRaw)
+		if err != nil {
+			return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "takeover_id is invalid UUID", nil)
+		}
+	}
+	name := strings.TrimSpace(attrs.Name)
+	if name == "" {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "name is required", nil)
+	}
+
+	actorID := actorUserID(c)
+	templateHeliFile, err := h.heliFile.GetByID(c.UserContext(), templateID)
+	if err != nil {
+		return writeFileManagerActionError(c, "Create from template failed", err)
+	}
+	if templateHeliFile == nil || len(templateHeliFile.HelicopterID) != 16 || !bytes.Equal(templateHeliFile.HelicopterID, helicopterID) {
+		return writeFileManagerError(c, fiber.StatusForbidden, "Forbidden", "forbidden access", nil)
+	}
+
+	templateRow, err := h.resolveHelicopterTemplateSourceFile(c.UserContext(), templateHeliFile)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusForbidden, "Forbidden", "forbidden access", nil)
+	}
+
+	copyStorage, ok := any(h.storage).(templateCopyStorage)
+	if !ok {
+		return writeFileManagerError(c, fiber.StatusServiceUnavailable, "Storage unavailable", "storage is not configured for copy", nil)
+	}
+	if err := validateWOPITemplateCandidate(templateRow, copyStorage); err != nil {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", err.Error(), nil)
+	}
+
+	var takeoverRow *takeoverdomain.TakeoverAc
+	if len(takeoverID) == 16 {
+		if h.takeover == nil {
+			return writeFileManagerError(c, fiber.StatusServiceUnavailable, "Create failed", "takeover service is not configured", nil)
+		}
+		takeoverRow, err = h.takeover.GetByID(c.UserContext(), takeoverID)
+		if err != nil {
+			return writeFileManagerActionError(c, "Create from template failed", err)
+		}
+		if takeoverRow == nil || (!takeoverHasUserAccess(takeoverRow, actorID) && !h.takeoverUserHasGlobalAccessForUserID(c.UserContext(), actorID)) {
+			return writeFileManagerError(c, fiber.StatusForbidden, "Forbidden", "forbidden access", nil)
+		}
+		existing, lookupErr := h.findExistingTemplateTakeoverFile(c.UserContext(), templateID, takeoverID, takeoverRow, name, strings.TrimSpace(templateRow.MimeType))
+		if lookupErr != nil {
+			return writeFileManagerActionError(c, "Create from template failed", lookupErr)
+		}
+		if existing != nil {
+			if err := waitStoredWOPIFileReady(c.UserContext(), copyStorage, existing); err != nil {
+				return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", err.Error(), nil)
+			}
+			if _, _, err := h.sanitizeStoredXLSXObject(c.UserContext(), existing, existing.ObjectKey, existing.Name, existing.MimeType, "create-from-template-existing"); err != nil {
+				return writeFileManagerActionError(c, "Create from template failed", err)
+			}
+			if err := h.ensureTemplateTakeoverMetadata(c.UserContext(), existing, templateID, takeoverID, actorID); err != nil {
+				return writeFileManagerActionError(c, "Create from template failed", err)
+			}
+			if err := h.ensureTakeoverAttachment(c.UserContext(), takeoverRow, existing.ID, takeoverID, actorID); err != nil {
+				return writeFileManagerActionError(c, "Create from template failed", err)
+			}
+			childRow, childCreated, err := h.ensureHelicopterFileChild(c.UserContext(), helicopterID, existing.ID, actorID)
+			if err != nil {
+				return writeFileManagerActionError(c, "Create from template failed", err)
+			}
+			if childCreated {
+				h.publishHelicopterFileCreated(actorID, helicopterID, childRow, name, templateRow.MimeType, childRow.Section, childRow.Position, childRow.IsMandatory, true)
+			}
+			token, ttl, err := h.wopi.MintAccessToken(existing.ID, actorID, takeoverID, service.WOPIPermissionWrite)
+			if err != nil {
+				return writeFileManagerActionError(c, "Create from template failed", err)
+			}
+			fileID := idString(existing.ID)
+			actionURL, err := h.wopi.BuildActionURLWithToken(c.UserContext(), fileID, token, ttl)
+			if err != nil {
+				return writeFileManagerActionError(c, "Create from template failed", err)
+			}
+
+			return c.Status(fiber.StatusOK).JSON(responsedto.FileManagerFileWOPISessionResponse{
+				Data: responsedto.FileManagerFileWOPISessionData{
+					FileID:          fileID,
+					CollaboraAction: actionURL,
+					AccessToken:     token,
+					AccessTokenTTL:  ttl,
+				},
+			})
+		}
+	}
+
+	grant, err := h.svc.RequestFileUploadIntent(c.UserContext(), filemanager.RequestFileUploadIntentParams{
+		Name:        name,
+		ContentType: strings.TrimSpace(templateRow.MimeType),
+		SizeBytes:   templateRow.SizeBytes,
+		ActorID:     actorID,
+	})
+	if err != nil {
+		return writeFileManagerActionError(c, "Create from template failed", err)
+	}
+
+	templateObjectKey := strings.TrimSpace(templateRow.ObjectKey)
+	if templateObjectKey == "" {
+		return writeFileManagerError(c, fiber.StatusNotFound, "Not found", "template object not found", nil)
+	}
+	if _, err := copyStorage.CopyObject(c.UserContext(), templateObjectKey, grant.ObjectKey); err != nil {
+		_ = copyStorageDelete(copyStorage, grant.ObjectKey)
+		return writeFileManagerActionError(c, "Create from template failed", err)
+	}
+	if err := waitStoredWOPIFileReady(c.UserContext(), copyStorage, &filemanager.File{
+		Name:      name,
+		ObjectKey: grant.ObjectKey,
+		MimeType:  strings.TrimSpace(templateRow.MimeType),
+	}); err != nil {
+		_ = copyStorageDelete(copyStorage, grant.ObjectKey)
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", err.Error(), nil)
+	}
+	changed, sanitizedSize, err := h.sanitizeStoredXLSXObject(c.UserContext(), nil, grant.ObjectKey, name, templateRow.MimeType, "create-from-template-copy")
+	if err != nil {
+		_ = copyStorageDelete(copyStorage, grant.ObjectKey)
+		return writeFileManagerActionError(c, "Create from template failed", err)
+	}
+	if changed {
+		updater, ok := any(h.svc).(uploadIntentSizeUpdater)
+		if !ok {
+			_ = copyStorageDelete(copyStorage, grant.ObjectKey)
+			return writeFileManagerError(c, fiber.StatusServiceUnavailable, "Create failed", "file manager service does not support upload intent size updates", nil)
+		}
+		if err := updater.UpdateUploadIntentSize(c.UserContext(), filemanager.FileUploadIntentSizeUpdateParams{
+			ID:        grant.UploadIntentID,
+			SizeBytes: sanitizedSize,
+			UpdatedBy: actorID,
+		}); err != nil {
+			_ = copyStorageDelete(copyStorage, grant.ObjectKey)
+			return writeFileManagerActionError(c, "Create from template failed", err)
+		}
+	}
+
+	created, err := h.svc.CreateFileNodeFromUploadIntent(c.UserContext(), filemanager.CreateFileFromUploadIntentParams{
+		UploadIntentID: grant.UploadIntentID,
+		FolderProvided: false,
+		Name:           name,
+		ActorID:        actorID,
+		IsTemplate:     false,
+	})
+	if err != nil {
+		_ = copyStorageDelete(copyStorage, grant.ObjectKey)
+		return writeFileManagerActionError(c, "Create from template failed", err)
+	}
+
+	now := time.Now().UTC()
+	created.Status = filemanager.FileStatusReady
+	created.LifecycleStatus = filemanager.FileLifecycleStatusDraft
+	created.NameSlot = "draft"
+	created.Name = name
+	created.NameNormalized = strings.ToLower(strings.TrimSpace(name))
+	created.TemplateUUID = append([]byte(nil), templateID...)
+	created.TakeoverID = append([]byte(nil), takeoverID...)
+	created.UpdatedAt = now
+	created.UpdatedBy = actorID
+	if err := h.svc.UpdateFile(c.UserContext(), created); err != nil {
+		_ = copyStorageDelete(copyStorage, grant.ObjectKey)
+		_ = h.svc.DeleteFile(c.UserContext(), created.ID, actorID, nil)
+		return writeFileManagerActionError(c, "Create from template failed", err)
+	}
+	if err := h.ensureTakeoverAttachment(c.UserContext(), takeoverRow, created.ID, takeoverID, actorID); err != nil {
+		_ = copyStorageDelete(copyStorage, grant.ObjectKey)
+		_ = h.svc.DeleteFile(c.UserContext(), created.ID, actorID, nil)
+		return writeFileManagerActionError(c, "Create from template failed", err)
+	}
+	childRow, childCreated, err := h.ensureHelicopterFileChild(c.UserContext(), helicopterID, created.ID, actorID)
+	if err != nil {
+		_ = copyStorageDelete(copyStorage, grant.ObjectKey)
+		_ = h.svc.DeleteFile(c.UserContext(), created.ID, actorID, nil)
+		return writeFileManagerActionError(c, "Create from template failed", err)
+	}
+	if childCreated {
+		h.publishHelicopterFileCreated(actorID, helicopterID, childRow, name, templateRow.MimeType, childRow.Section, childRow.Position, childRow.IsMandatory, true)
+	}
+
+	token, ttl, err := h.wopi.MintAccessToken(created.ID, actorID, takeoverID, service.WOPIPermissionWrite)
+	if err != nil {
+		return writeFileManagerActionError(c, "Create from template failed", err)
+	}
+	fileID := idString(created.ID)
+	actionURL, err := h.wopi.BuildActionURLWithToken(c.UserContext(), fileID, token, ttl)
+	if err != nil {
+		return writeFileManagerActionError(c, "Create from template failed", err)
+	}
+
+	return c.Status(fiber.StatusOK).JSON(responsedto.FileManagerFileWOPISessionResponse{
+		Data: responsedto.FileManagerFileWOPISessionData{
+			FileID:          fileID,
+			CollaboraAction: actionURL,
+			AccessToken:     token,
+			AccessTokenTTL:  ttl,
+		},
+	})
+}
+
+func (h *FileManagerFileHandler) findExistingTemplateTakeoverFile(ctx context.Context, templateID, takeoverID []byte, takeoverRow *takeoverdomain.TakeoverAc, requestedName, requestedMime string) (*filemanager.File, error) {
+	if h != nil && h.svc != nil {
+		if lookupSvc, ok := any(h.svc).(templateTakeoverFileLookupService); ok {
+			row, err := lookupSvc.GetFileByTemplateAndTakeover(ctx, templateID, takeoverID)
+			if err != nil || row != nil {
+				return row, err
+			}
+		}
+	}
+	return nil, nil
+}
+
+func (h *FileManagerFileHandler) ensureTemplateTakeoverMetadata(ctx context.Context, row *filemanager.File, templateID, takeoverID, actorID []byte) error {
+	if h == nil || h.svc == nil || row == nil || len(templateID) != 16 || len(takeoverID) != 16 {
+		return nil
+	}
+	if bytes.Equal(row.TemplateUUID, templateID) && bytes.Equal(row.TakeoverID, takeoverID) {
+		return nil
+	}
+	row.TemplateUUID = append([]byte(nil), templateID...)
+	row.TakeoverID = append([]byte(nil), takeoverID...)
+	row.UpdatedAt = time.Now().UTC()
+	row.UpdatedBy = append([]byte(nil), actorID...)
+	return h.svc.UpdateFile(ctx, row)
+}
+
+func (h *FileManagerFileHandler) ensureTakeoverAttachment(ctx context.Context, takeoverRow *takeoverdomain.TakeoverAc, fileID, takeoverID, actorID []byte) error {
+	if h == nil || h.svc == nil || h.takeover == nil || len(fileID) != 16 || len(takeoverID) != 16 {
+		return nil
+	}
+	if takeoverRow == nil {
+		row, err := h.takeover.GetByID(ctx, takeoverID)
+		if err != nil {
+			return err
+		}
+		takeoverRow = row
+	}
+	if takeoverRow != nil && takeoverHasFile(takeoverRow, fileID) {
+		return nil
+	}
+
+	attachment, err := h.svc.CreateAttachment(ctx, filemanager.CreateAttachmentParams{
+		FileID:    append([]byte(nil), fileID...),
+		RefType:   "takeover",
+		RefID:     idString(takeoverID),
+		SortOrder: 0,
+		IsPrimary: false,
+		ActorID:   append([]byte(nil), actorID...),
+	})
+	if err != nil {
+		if !errors.Is(err, filemanager.ErrAttachmentAlreadyExists) {
+			return err
+		}
+		attachments, _, listErr := h.svc.ListAttachmentsByReference(ctx, filemanager.ListAttachmentsParams{
+			RefType: "takeover",
+			RefID:   idString(takeoverID),
+			Sort:    "-created_at",
+			Limit:   100,
+		})
+		if listErr != nil {
+			return listErr
+		}
+		for i := range attachments {
+			if bytes.Equal(attachments[i].FileID, fileID) {
+				attachment = &attachments[i]
+				break
+			}
+		}
+		if attachment == nil {
+			return filemanager.ErrAttachmentAlreadyExists
+		}
+	}
+
+	if attachment == nil {
+		return nil
+	}
+	return h.takeover.AttachFile(ctx, takeoverID, attachment.ID)
+}
+
+func (h *FileManagerFileHandler) ensureHelicopterFileChild(ctx context.Context, helicopterID, sourceFileID, actorID []byte) (*helicopterfile.HelicopterFile, bool, error) {
+	if h == nil || h.heliFile == nil || len(helicopterID) != 16 || len(sourceFileID) != 16 {
+		return nil, false, nil
+	}
+
+	rows, err := h.heliFile.ListByHelicopterAndSection(ctx, helicopterID, helicopterfile.SectionFlightPreparationAndWB)
+	if err != nil {
+		return nil, false, err
+	}
+	for i := range rows {
+		row := rows[i]
+		if bytes.Equal(row.SourceFileID, sourceFileID) {
+			return &row, false, nil
+		}
+		if row.FileAttachment != nil && row.FileAttachment.File != nil && bytes.Equal(row.FileAttachment.File.ID, sourceFileID) {
+			return &row, false, nil
+		}
+	}
+
+	row := &helicopterfile.HelicopterFile{
+		Section:      helicopterfile.SectionFlightPreparationAndWB,
+		HelicopterID: append([]byte(nil), helicopterID...),
+		SourceFileID: append([]byte(nil), sourceFileID...),
+		CreatedBy:    append([]byte(nil), actorID...),
+		UpdatedBy:    append([]byte(nil), actorID...),
+	}
+	if err := h.heliFile.Create(ctx, row); err != nil {
+		return nil, false, err
+	}
+	return row, true, nil
+}
+
+func (h *FileManagerFileHandler) publishHelicopterFileCreated(actorID, helicopterID []byte, row *helicopterfile.HelicopterFile, name, mimeType, section string, position int, isMandatory, attachmentPending bool) {
+	if h == nil || h.helicopterFileEvents == nil || row == nil || len(actorID) != 16 || len(helicopterID) != 16 {
+		return
+	}
+	userUUID, err := uuidv7.BytesToString(actorID)
+	if err != nil || strings.TrimSpace(userUUID) == "" {
+		return
+	}
+	helicopterUUID, err := uuidv7.BytesToString(helicopterID)
+	if err != nil || strings.TrimSpace(helicopterUUID) == "" {
+		return
+	}
+	helicopterFileID := idString(row.ID)
+	fileID := idString(row.SourceFileID)
+	event := helicopterfilerealtime.Event{
+		EventType:         helicopterfilerealtime.DefaultEventType,
+		HelicopterID:      helicopterUUID,
+		HelicopterFileID:  helicopterFileID,
+		FileID:            fileID,
+		Section:           strings.TrimSpace(section),
+		Name:              strings.TrimSpace(name),
+		MimeType:          strings.TrimSpace(mimeType),
+		AttachmentPending: attachmentPending,
+		Position:          position,
+		IsMandatory:       isMandatory,
+		UpdatedAt:         time.Now().UTC().Format(time.RFC3339),
+	}
+	h.helicopterFileEvents.PublishToUsers([]string{userUUID}, event)
+}
+
+func findTakeoverTemplateFileByName(row *takeoverdomain.TakeoverAc, requestedName, requestedMime string) *filemanager.File {
+	if row == nil {
+		return nil
+	}
+	nameNormalized := normalizeWOPIRequestedName(requestedName)
+	mimeType := strings.TrimSpace(requestedMime)
+	var match *filemanager.File
+	for i := range row.Files {
+		attachment := row.Files[i].FileAttachment
+		if attachment == nil || attachment.File == nil {
+			continue
+		}
+		fileRow := attachment.File
+		if strings.TrimSpace(fileRow.NameNormalized) != nameNormalized {
+			continue
+		}
+		if mimeType != "" && !strings.EqualFold(strings.TrimSpace(fileRow.MimeType), mimeType) {
+			continue
+		}
+		if filemanager.NormalizeFileStatus(fileRow.Status) != filemanager.FileStatusReady {
+			continue
+		}
+		if fileRow.DeletedAt != nil {
+			continue
+		}
+		if match != nil && !bytes.Equal(match.ID, fileRow.ID) {
+			return nil
+		}
+		match = fileRow
+	}
+	return match
+}
+
+func normalizeWOPIRequestedName(raw string) string {
+	name := strings.TrimSpace(raw)
+	if name == "" {
+		return ""
+	}
+	name = strings.ReplaceAll(name, "\\", "/")
+	name = filepath.Base(name)
+	return strings.ToLower(name)
+}
+
+func (h *FileManagerFileHandler) resolveHelicopterTemplateSourceFile(ctx context.Context, row *helicopterfile.HelicopterFile) (*filemanager.File, error) {
+	if h == nil || h.svc == nil || row == nil {
+		return nil, errors.New("template file not found")
+	}
+	if row.SourceFile != nil {
+		return row.SourceFile, nil
+	}
+	if row.FileAttachment != nil && row.FileAttachment.File != nil {
+		return row.FileAttachment.File, nil
+	}
+	if len(row.SourceFileID) == 16 {
+		sourceFile, err := h.svc.GetFileByIDAny(ctx, row.SourceFileID)
+		if err != nil {
+			return nil, err
+		}
+		if sourceFile != nil {
+			return sourceFile, nil
+		}
+	}
+	return nil, errors.New("template file not found")
+}
+
+// EditSession godoc
+// @Summary Start a WOPI edit session for an existing file
+// @Description Returns a Collabora/WOPI write session for an already existing file that belongs to the authenticated user's takeover scope or to the authenticated user as an unattached draft.
+// @Description This endpoint does not create or copy files. It only resolves the file, checks access, and mints a new access token.
+// @Description Use this when reopening an existing file for editing.
+// @Description Path param `fileId` must be a valid UUIDv7.
+// @Tags File Manager
+// @Accept json
+// @Produce json
+// @Param fileId path string true "File UUID (UUIDv7)"
+// @Success 200 {object} responsedto.FileManagerFileWOPISessionResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 401 {object} dto.ErrorResponse
+// @Failure 403 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/file-manager/files/{fileId}/edit-session [get]
+func (h *FileManagerFileHandler) EditSession(c *fiber.Ctx) error {
+	if h == nil || h.svc == nil || h.wopi == nil {
+		return writeFileManagerError(c, fiber.StatusServiceUnavailable, "Create failed", "file manager service is not configured", nil)
+	}
+
+	fileID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("fileId")))
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "fileId is invalid UUID", nil)
+	}
+
+	fileRow, err := h.svc.GetFileByIDAny(c.UserContext(), fileID)
+	if err != nil {
+		return writeFileManagerActionError(c, "Edit session failed", err)
+	}
+	if fileRow == nil {
+		return writeFileManagerError(c, fiber.StatusNotFound, "Not found", "file not found", nil)
+	}
+	if storage, ok := any(h.storage).(templateCopyStorage); ok {
+		if err := waitStoredWOPIFileReady(c.UserContext(), storage, fileRow); err != nil {
+			return writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", err.Error(), nil)
+		}
+	}
+
+	actorID := actorUserID(c)
+	takeoverRow, takeoverID, err := h.findTakeoverForFile(c.UserContext(), fileID)
+	if err != nil {
+		if !errors.Is(err, filemanager.ErrFileNotFound) {
+			return writeFileManagerActionError(c, "Edit session failed", err)
+		}
+		if !bytes.Equal(fileRow.CreatedBy, actorID) {
+			return writeFileManagerError(c, fiber.StatusForbidden, "Forbidden", "forbidden access", nil)
+		}
+		takeoverID = nil
+	} else if takeoverRow == nil || len(takeoverID) != 16 || (!takeoverHasUserAccess(takeoverRow, actorID) && !h.takeoverUserHasGlobalAccessForUserID(c.UserContext(), actorID)) {
+		return writeFileManagerError(c, fiber.StatusForbidden, "Forbidden", "forbidden access", nil)
+	}
+
+	if _, _, err := h.sanitizeStoredXLSXObject(c.UserContext(), fileRow, fileRow.ObjectKey, fileRow.Name, fileRow.MimeType, "edit-session"); err != nil {
+		return writeFileManagerActionError(c, "Edit session failed", err)
+	}
+
+	token, ttl, err := h.wopi.MintAccessToken(fileRow.ID, actorID, takeoverID, service.WOPIPermissionWrite)
+	if err != nil {
+		return writeFileManagerActionError(c, "Edit session failed", err)
+	}
+	actionURL, err := h.wopi.BuildActionURLWithToken(c.UserContext(), idString(fileRow.ID), token, ttl)
+	if err != nil {
+		return writeFileManagerActionError(c, "Edit session failed", err)
+	}
+
+	return c.Status(fiber.StatusOK).JSON(responsedto.FileManagerFileWOPISessionResponse{
+		Data: responsedto.FileManagerFileWOPISessionData{
+			FileID:          idString(fileRow.ID),
+			CollaboraAction: actionURL,
+			AccessToken:     token,
+			AccessTokenTTL:  ttl,
+		},
+	})
+}
+
+func (h *FileManagerFileHandler) fileManagerFileForTakeover(row *takeoverdomain.TakeoverAc, fileID []byte) (*filemanager.File, error) {
+	attachmentFile, err := takeoverFindFileByID(row, fileID)
+	if err != nil {
+		return nil, err
+	}
+	if attachmentFile == nil {
+		return nil, filemanager.ErrFileNotFound
+	}
+	return attachmentFile, nil
+}
+
+func (h *FileManagerFileHandler) findTakeoverForFile(ctx context.Context, fileID []byte) (*takeoverdomain.TakeoverAc, []byte, error) {
+	if h.takeover == nil || len(fileID) != 16 {
+		return nil, nil, filemanager.ErrFileNotFound
+	}
+
+	const pageSize = 100
+	for offset := 0; ; offset += pageSize {
+		rows, total, err := h.takeover.List(ctx, pageSize, offset)
+		if err != nil {
+			return nil, nil, err
+		}
+		for i := range rows {
+			row := rows[i]
+			if !takeoverHasFile(&row, fileID) {
+				continue
+			}
+			return &row, append([]byte(nil), row.ID...), nil
+		}
+		if total <= int64(offset+len(rows)) || len(rows) == 0 {
+			break
+		}
+	}
+	return nil, nil, filemanager.ErrFileNotFound
+}
+
+func takeoverHasFile(row *takeoverdomain.TakeoverAc, fileID []byte) bool {
+	if row == nil || len(fileID) != 16 {
+		return false
+	}
+	for i := range row.Files {
+		attachment := row.Files[i].FileAttachment
+		if attachment == nil || attachment.File == nil {
+			continue
+		}
+		if bytes.Equal(attachment.File.ID, fileID) {
+			return true
+		}
+	}
+	return false
+}
+
+func validateWOPITemplateCandidate(row *filemanager.File, storage templateCopyStorage) error {
+	if row == nil {
+		return errors.New("template file not found")
+	}
+	name := strings.TrimSpace(row.Name)
+	ext := strings.ToLower(strings.TrimPrefix(filepath.Ext(name), "."))
+	if ext == "" {
+		ext = strings.ToLower(strings.TrimPrefix(filepath.Ext(strings.TrimSpace(row.ObjectKey)), "."))
+	}
+	if ext == "" {
+		return errors.New("template file extension is required")
+	}
+	switch ext {
+	case "docx", "xlsx", "pptx", "odt", "ods", "odp", "doc", "xls", "ppt", "rtf":
+		if storage == nil {
+			return nil
+		}
+		return waitStoredWOPIFileReady(context.Background(), storage, row)
+	default:
+		return errors.New("template file extension is not allowed")
+	}
+}
+
+func validateWOPISaveContent(name, declaredMime string, payload []byte) error {
+	ext := strings.ToLower(strings.TrimPrefix(filepath.Ext(strings.TrimSpace(name)), "."))
+	if ext == "" {
+		return errors.New("file extension is required")
+	}
+	switch ext {
+	case "docx", "xlsx", "pptx", "odt", "ods", "odp":
+		if err := validateOfficeContentSample(ext, declaredMime, payload); err != nil {
+			return err
+		}
+		return validateOfficeZipStructure(ext, payload)
+	case "doc", "xls", "ppt", "rtf":
+		return validateOfficeContentSample(ext, declaredMime, payload)
+	default:
+		return errors.New("file extension is not allowed")
+	}
+}
+
+func validateOfficeContentSample(ext, declaredMime string, sample []byte) error {
+	if len(sample) == 0 {
+		return errors.New("file content is empty")
+	}
+	detected := strings.ToLower(http.DetectContentType(sample))
+	declared := strings.ToLower(strings.TrimSpace(declaredMime))
+	switch ext {
+	case "docx", "xlsx", "pptx", "odt", "ods", "odp":
+		if strings.HasPrefix(detected, "text/") {
+			return errors.New("file content is not a supported office document")
+		}
+		if declared != "" && !isAllowedOfficeContentType(declared) {
+			return errors.New("file content type is not allowed")
+		}
+	case "rtf":
+		if !strings.Contains(detected, "rtf") && !strings.HasPrefix(detected, "text/") {
+			return errors.New("file content is not rtf")
+		}
+	default:
+		_ = declared
+	}
+	return nil
+}
+
+func isAllowedOfficeContentType(contentType string) bool {
+	contentType = strings.ToLower(strings.TrimSpace(strings.Split(contentType, ";")[0]))
+	if contentType == "" {
+		return true
+	}
+	switch contentType {
+	case "application/octet-stream", "binary/octet-stream", "application/download", "application/x-download":
+		return true
+	}
+	return strings.Contains(contentType, "officedocument") ||
+		strings.Contains(contentType, "opendocument") ||
+		strings.Contains(contentType, "zip")
+}
+
+func canonicalOfficeContentType(name string) string {
+	switch strings.ToLower(strings.TrimPrefix(filepath.Ext(strings.TrimSpace(name)), ".")) {
+	case "docx":
+		return "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+	case "xlsx":
+		return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+	case "pptx":
+		return "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+	case "odt":
+		return "application/vnd.oasis.opendocument.text"
+	case "ods":
+		return "application/vnd.oasis.opendocument.spreadsheet"
+	case "odp":
+		return "application/vnd.oasis.opendocument.presentation"
+	case "doc":
+		return "application/msword"
+	case "xls":
+		return "application/vnd.ms-excel"
+	case "ppt":
+		return "application/vnd.ms-powerpoint"
+	case "rtf":
+		return "application/rtf"
+	default:
+		return ""
+	}
+}
+
+func waitStoredWOPIFileReady(ctx context.Context, storage templateCopyStorage, row *filemanager.File) error {
+	if storage == nil || row == nil {
+		return nil
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	var lastErr error
+	for attempt := 0; attempt < wopiStorageReadyAttempts; attempt++ {
+		if err := validateStoredWOPIFile(ctx, storage, row); err != nil {
+			lastErr = err
+			if attempt < wopiStorageReadyAttempts-1 {
+				select {
+				case <-ctx.Done():
+					return ctx.Err()
+				case <-time.After(wopiStorageReadyDelay):
+				}
+			}
+			continue
+		}
+		return nil
+	}
+	return lastErr
+}
+
+func validateStoredWOPIFile(ctx context.Context, storage templateCopyStorage, row *filemanager.File) error {
+	if storage == nil || row == nil {
+		return nil
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	name := strings.TrimSpace(row.Name)
+	ext := strings.ToLower(strings.TrimPrefix(filepath.Ext(name), "."))
+	if ext == "" {
+		ext = strings.ToLower(strings.TrimPrefix(filepath.Ext(strings.TrimSpace(row.ObjectKey)), "."))
+	}
+	if ext == "" {
+		return errors.New("file extension is required")
+	}
+	body, meta, err := storage.GetObject(ctx, row.ObjectKey)
+	if err != nil {
+		return err
+	}
+	defer body.Close()
+
+	payload, err := io.ReadAll(body)
+	if err != nil {
+		return err
+	}
+	if meta.SizeBytes > 0 && int64(len(payload)) != meta.SizeBytes {
+		return errors.New("file content is incomplete")
+	}
+	if err := validateOfficeContentSample(ext, firstNonEmpty(meta.ContentType, row.MimeType), payload); err != nil {
+		return err
+	}
+	switch ext {
+	case "docx", "xlsx", "pptx", "odt", "ods", "odp":
+		return validateOfficeZipStructure(ext, payload)
+	default:
+		return nil
+	}
+}
+
+func validateOfficeZipStructure(ext string, payload []byte) error {
+	reader, err := zip.NewReader(bytes.NewReader(payload), int64(len(payload)))
+	if err != nil {
+		return errors.New("file content is not a valid office zip document")
+	}
+	requiredEntries := officeZipRequiredEntries(ext)
+	if len(requiredEntries) == 0 {
+		return nil
+	}
+	seen := make(map[string]struct{}, len(reader.File))
+	files := make(map[string]*zip.File, len(reader.File))
+	for _, file := range reader.File {
+		entryName := strings.TrimSpace(file.Name)
+		seen[entryName] = struct{}{}
+		files[entryName] = file
+		if err := validateOfficeZipEntry(file, ext); err != nil {
+			return err
+		}
+	}
+	for _, entry := range requiredEntries {
+		if _, ok := seen[entry]; !ok {
+			return errors.New("file content is corrupt or incomplete")
+		}
+	}
+	for _, prefix := range officeZipRequiredEntryPrefixes(ext) {
+		if !officeZipHasEntryPrefix(seen, prefix) {
+			return errors.New("file content is corrupt or incomplete")
+		}
+	}
+	if ext == "xlsx" {
+		if err := validateXLSXWorkbook(files); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+type xlsxWorkbookXML struct {
+	Sheets []xlsxSheetXML `xml:"sheets>sheet"`
+}
+
+type xlsxSheetXML struct {
+	ID string `xml:"http://schemas.openxmlformats.org/officeDocument/2006/relationships id,attr"`
+}
+
+type officeRelationshipsXML struct {
+	Relationships []officeRelationshipXML `xml:"Relationship"`
+}
+
+type officeRelationshipXML struct {
+	ID     string `xml:"Id,attr"`
+	Type   string `xml:"Type,attr"`
+	Target string `xml:"Target,attr"`
+}
+
+func validateXLSXWorkbook(files map[string]*zip.File) error {
+	workbookPayload, err := readOfficeZipEntry(files, "xl/workbook.xml")
+	if err != nil {
+		return err
+	}
+	var workbook xlsxWorkbookXML
+	if err := xml.Unmarshal(workbookPayload, &workbook); err != nil {
+		return errors.New("file content is corrupt or incomplete")
+	}
+	if len(workbook.Sheets) == 0 {
+		return errors.New("file content is corrupt or incomplete")
+	}
+
+	relsPayload, err := readOfficeZipEntry(files, "xl/_rels/workbook.xml.rels")
+	if err != nil {
+		return err
+	}
+	var rels officeRelationshipsXML
+	if err := xml.Unmarshal(relsPayload, &rels); err != nil {
+		return errors.New("file content is corrupt or incomplete")
+	}
+	byID := make(map[string]officeRelationshipXML, len(rels.Relationships))
+	for _, rel := range rels.Relationships {
+		id := strings.TrimSpace(rel.ID)
+		if id != "" {
+			byID[id] = rel
+		}
+	}
+	for _, sheet := range workbook.Sheets {
+		rel, ok := byID[strings.TrimSpace(sheet.ID)]
+		if !ok || !strings.Contains(strings.ToLower(rel.Type), "/worksheet") {
+			return errors.New("file content is corrupt or incomplete")
+		}
+		worksheetName := resolveOfficeRelationshipTarget("xl/workbook.xml", rel.Target)
+		if _, err := readOfficeZipEntry(files, worksheetName); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func readOfficeZipEntry(files map[string]*zip.File, name string) ([]byte, error) {
+	file := files[strings.TrimSpace(name)]
+	if file == nil {
+		return nil, errors.New("file content is corrupt or incomplete")
+	}
+	rc, err := file.Open()
+	if err != nil {
+		return nil, errors.New("file content is corrupt or incomplete")
+	}
+	defer rc.Close()
+	payload, err := io.ReadAll(rc)
+	if err != nil {
+		return nil, errors.New("file content is corrupt or incomplete")
+	}
+	return payload, nil
+}
+
+func resolveOfficeRelationshipTarget(source, target string) string {
+	target = strings.TrimSpace(strings.ReplaceAll(target, "\\", "/"))
+	if target == "" {
+		return target
+	}
+	if strings.HasPrefix(target, "/") {
+		return strings.TrimPrefix(path.Clean(target), "/")
+	}
+	base := path.Dir(strings.TrimSpace(source))
+	if base == "." || base == "/" {
+		return strings.TrimPrefix(path.Clean(target), "/")
+	}
+	return strings.TrimPrefix(path.Clean(path.Join(base, target)), "/")
+}
+
+func validateOfficeZipEntry(file *zip.File, ext string) error {
+	if file == nil {
+		return nil
+	}
+	name := strings.TrimSpace(file.Name)
+	if name == "" || strings.HasSuffix(name, "/") {
+		return nil
+	}
+	rc, err := file.Open()
+	if err != nil {
+		return errors.New("file content is corrupt or incomplete")
+	}
+	defer rc.Close()
+
+	payload, err := io.ReadAll(rc)
+	if err != nil {
+		return errors.New("file content is corrupt or incomplete")
+	}
+	if shouldValidateOfficeXML(ext, name) {
+		if err := validateXMLPayload(payload); err != nil {
+			return errors.New("file content is corrupt or incomplete")
+		}
+	}
+	return nil
+}
+
+func shouldValidateOfficeXML(ext, name string) bool {
+	name = strings.ToLower(strings.TrimSpace(name))
+	if name == "" || (!strings.HasSuffix(name, ".xml") && !strings.HasSuffix(name, ".rels")) {
+		return false
+	}
+	switch ext {
+	case "docx":
+		return name == "[content_types].xml" || strings.HasPrefix(name, "word/")
+	case "xlsx":
+		return name == "[content_types].xml" || strings.HasPrefix(name, "xl/")
+	case "pptx":
+		return name == "[content_types].xml" || strings.HasPrefix(name, "ppt/")
+	case "odt", "ods", "odp":
+		return name == "content.xml" || name == "styles.xml" || name == "meta.xml" || name == "settings.xml"
+	default:
+		return false
+	}
+}
+
+func validateXMLPayload(payload []byte) error {
+	if len(bytes.TrimSpace(payload)) == 0 {
+		return errors.New("empty xml")
+	}
+	decoder := xml.NewDecoder(bytes.NewReader(payload))
+	for {
+		if _, err := decoder.Token(); err != nil {
+			if errors.Is(err, io.EOF) {
+				return nil
+			}
+			return err
+		}
+	}
+}
+
+func officeZipRequiredEntries(ext string) []string {
+	switch ext {
+	case "docx":
+		return []string{"[Content_Types].xml", "word/document.xml"}
+	case "xlsx":
+		return []string{"[Content_Types].xml", "xl/workbook.xml", "xl/_rels/workbook.xml.rels"}
+	case "pptx":
+		return []string{"[Content_Types].xml", "ppt/presentation.xml"}
+	case "odt", "ods", "odp":
+		return []string{"mimetype", "content.xml"}
+	default:
+		return nil
+	}
+}
+
+func officeZipRequiredEntryPrefixes(ext string) []string {
+	switch ext {
+	case "xlsx":
+		return []string{"xl/worksheets/"}
+	default:
+		return nil
+	}
+}
+
+func officeZipHasEntryPrefix(entries map[string]struct{}, prefix string) bool {
+	prefix = strings.TrimSpace(prefix)
+	if prefix == "" {
+		return true
+	}
+	for entry := range entries {
+		if strings.HasPrefix(entry, prefix) && strings.HasSuffix(strings.ToLower(entry), ".xml") {
+			return true
+		}
+	}
+	return false
+}
+
+func copyStorageDelete(storage any, objectKey string) error {
+	deleter, ok := storage.(interface {
+		DeleteObject(context.Context, string) error
+	})
+	if !ok {
+		return nil
+	}
+	return deleter.DeleteObject(context.Background(), objectKey)
+}
diff --git a/internal/transport/http/handlers/file_manager_template_wopi_handler_test.go b/internal/transport/http/handlers/file_manager_template_wopi_handler_test.go
new file mode 100644
index 0000000..b3c61e1
--- /dev/null
+++ b/internal/transport/http/handlers/file_manager_template_wopi_handler_test.go
@@ -0,0 +1,1356 @@
+package handlers
+
+import (
+	"archive/zip"
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"path"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanager "wucher/internal/domain/file_manager"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	takeoverdomain "wucher/internal/domain/takeover"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type fileManagerTemplateServiceMock struct {
+	filemanager.Service
+
+	requestUploadIntentFn    func(context.Context, filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error)
+	createFromIntentFn       func(context.Context, filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error)
+	createAttachmentFn       func(context.Context, filemanager.CreateAttachmentParams) (*filemanager.Attachment, error)
+	updateFileFn             func(context.Context, *filemanager.File) error
+	deleteFileFn             func(context.Context, []byte, []byte, *time.Time) error
+	deleteAttachmentFn       func(context.Context, []byte) error
+	getFileByIDAnyFn         func(context.Context, []byte) (*filemanager.File, error)
+	getByTemplateTakeoverFn  func(context.Context, []byte, []byte) (*filemanager.File, error)
+	updateUploadIntentSizeFn func(context.Context, filemanager.FileUploadIntentSizeUpdateParams) error
+
+	requestUploadIntentCalls int
+	createFromIntentCalls    int
+	createAttachmentCalls    int
+	updateFileCalls          int
+	updateUploadIntentCalls  int
+}
+
+func (m *fileManagerTemplateServiceMock) RequestFileUploadIntent(ctx context.Context, params filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+	m.requestUploadIntentCalls++
+	if m.requestUploadIntentFn != nil {
+		return m.requestUploadIntentFn(ctx, params)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerTemplateServiceMock) CreateFileNodeFromUploadIntent(ctx context.Context, params filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+	m.createFromIntentCalls++
+	if m.createFromIntentFn != nil {
+		return m.createFromIntentFn(ctx, params)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerTemplateServiceMock) UpdateUploadIntentSize(ctx context.Context, params filemanager.FileUploadIntentSizeUpdateParams) error {
+	m.updateUploadIntentCalls++
+	if m.updateUploadIntentSizeFn != nil {
+		return m.updateUploadIntentSizeFn(ctx, params)
+	}
+	return nil
+}
+
+func (m *fileManagerTemplateServiceMock) CreateAttachment(ctx context.Context, params filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+	m.createAttachmentCalls++
+	if m.createAttachmentFn != nil {
+		return m.createAttachmentFn(ctx, params)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerTemplateServiceMock) UpdateFile(ctx context.Context, row *filemanager.File) error {
+	m.updateFileCalls++
+	if m.updateFileFn != nil {
+		return m.updateFileFn(ctx, row)
+	}
+	return nil
+}
+
+func (m *fileManagerTemplateServiceMock) DeleteFile(ctx context.Context, id []byte, deletedBy []byte, purgeAt *time.Time) error {
+	if m.deleteFileFn != nil {
+		return m.deleteFileFn(ctx, id, deletedBy, purgeAt)
+	}
+	return nil
+}
+
+func (m *fileManagerTemplateServiceMock) DeleteAttachment(ctx context.Context, id []byte) error {
+	if m.deleteAttachmentFn != nil {
+		return m.deleteAttachmentFn(ctx, id)
+	}
+	return nil
+}
+
+func (m *fileManagerTemplateServiceMock) GetFileByIDAny(ctx context.Context, id []byte) (*filemanager.File, error) {
+	if m.getFileByIDAnyFn != nil {
+		return m.getFileByIDAnyFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *fileManagerTemplateServiceMock) GetFileByTemplateAndTakeover(ctx context.Context, templateUUID, takeoverID []byte) (*filemanager.File, error) {
+	if m.getByTemplateTakeoverFn != nil {
+		return m.getByTemplateTakeoverFn(ctx, templateUUID, takeoverID)
+	}
+	return nil, nil
+}
+
+type helicopterFileTemplateServiceMock struct {
+	helicopterfile.Service
+	getByIDFn                    func(context.Context, []byte) (*helicopterfile.HelicopterFile, error)
+	createFn                     func(context.Context, *helicopterfile.HelicopterFile) error
+	listByHelicopterAndSectionFn func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error)
+	createCalls                  int
+	listCalls                    int
+}
+
+func (m *helicopterFileTemplateServiceMock) GetByID(ctx context.Context, id []byte) (*helicopterfile.HelicopterFile, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *helicopterFileTemplateServiceMock) Create(ctx context.Context, row *helicopterfile.HelicopterFile) error {
+	m.createCalls++
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return nil
+}
+
+func (m *helicopterFileTemplateServiceMock) ListByHelicopterAndSection(ctx context.Context, helicopterID []byte, section string) ([]helicopterfile.HelicopterFile, error) {
+	m.listCalls++
+	if m.listByHelicopterAndSectionFn != nil {
+		return m.listByHelicopterAndSectionFn(ctx, helicopterID, section)
+	}
+	return nil, nil
+}
+
+type takeoverTemplateServiceMock struct {
+	getByIDFn func(context.Context, []byte) (*takeoverdomain.TakeoverAc, error)
+	attachFn  func(context.Context, []byte, []byte) error
+	listFn    func(context.Context, int, int) ([]takeoverdomain.TakeoverAc, int64, error)
+}
+
+func (m *takeoverTemplateServiceMock) Create(context.Context, *takeoverdomain.TakeoverAc) error {
+	return nil
+}
+
+func (m *takeoverTemplateServiceMock) Update(context.Context, *takeoverdomain.TakeoverAc) error {
+	return nil
+}
+
+func (m *takeoverTemplateServiceMock) Delete(context.Context, []byte, []byte) error {
+	return nil
+}
+
+func (m *takeoverTemplateServiceMock) GetByID(ctx context.Context, id []byte) (*takeoverdomain.TakeoverAc, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *takeoverTemplateServiceMock) List(ctx context.Context, limit, offset int) ([]takeoverdomain.TakeoverAc, int64, error) {
+	if m.listFn != nil {
+		return m.listFn(ctx, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func (m *takeoverTemplateServiceMock) AttachFile(ctx context.Context, takeoverID, attachmentID []byte) error {
+	if m.attachFn != nil {
+		return m.attachFn(ctx, takeoverID, attachmentID)
+	}
+	return nil
+}
+
+type templateCopyStorageMock struct {
+	copyFn       func(context.Context, string, string) (filemanager.ObjectMetadata, error)
+	getFn        func(context.Context, string) (io.ReadCloser, filemanager.ObjectMetadata, error)
+	objects      map[string][]byte
+	contentTypes map[string]string
+}
+
+func (m *templateCopyStorageMock) EnsureBucket(ctx context.Context) error {
+	return nil
+}
+
+func (m *templateCopyStorageMock) PutObject(ctx context.Context, input filemanager.PutObjectInput) (filemanager.ObjectMetadata, error) {
+	if m.objects == nil {
+		m.objects = map[string][]byte{}
+	}
+	if m.contentTypes == nil {
+		m.contentTypes = map[string]string{}
+	}
+	payload, err := io.ReadAll(input.Body)
+	if err != nil {
+		return filemanager.ObjectMetadata{}, err
+	}
+	key := strings.TrimSpace(input.ObjectKey)
+	m.objects[key] = append([]byte(nil), payload...)
+	m.contentTypes[key] = strings.TrimSpace(input.ContentType)
+	now := time.Now().UTC()
+	return filemanager.ObjectMetadata{
+		Bucket:       "bucket",
+		ObjectKey:    key,
+		ETag:         "etag-" + key,
+		VersionID:    "version-" + key,
+		SizeBytes:    int64(len(payload)),
+		LastModified: &now,
+		ContentType:  strings.TrimSpace(input.ContentType),
+	}, nil
+}
+
+func (m *templateCopyStorageMock) CopyObject(ctx context.Context, sourceObjectKey, destinationObjectKey string) (filemanager.ObjectMetadata, error) {
+	if m.copyFn != nil {
+		return m.copyFn(ctx, sourceObjectKey, destinationObjectKey)
+	}
+	return filemanager.ObjectMetadata{}, nil
+}
+
+func (m *templateCopyStorageMock) HeadObject(ctx context.Context, objectKey string) (filemanager.ObjectMetadata, error) {
+	key := strings.TrimSpace(objectKey)
+	if m.objects != nil {
+		if payload, ok := m.objects[key]; ok {
+			now := time.Now().UTC()
+			return filemanager.ObjectMetadata{
+				Bucket:       "bucket",
+				ObjectKey:    key,
+				ETag:         "etag-" + key,
+				VersionID:    "version-" + key,
+				SizeBytes:    int64(len(payload)),
+				LastModified: &now,
+				ContentType:  m.contentTypes[key],
+			}, nil
+		}
+	}
+	return filemanager.ObjectMetadata{}, nil
+}
+
+func (m *templateCopyStorageMock) PresignPutObject(ctx context.Context, input filemanager.PresignPutObjectInput) (filemanager.PresignedPutObject, error) {
+	return filemanager.PresignedPutObject{}, nil
+}
+
+func (m *templateCopyStorageMock) PresignGetObject(ctx context.Context, objectKey string, ttl time.Duration) (string, error) {
+	return "https://example.com/" + objectKey, nil
+}
+
+func (m *templateCopyStorageMock) GetObject(ctx context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+	if m.objects != nil {
+		if payload, ok := m.objects[strings.TrimSpace(objectKey)]; ok {
+			now := time.Now().UTC()
+			return io.NopCloser(bytes.NewReader(payload)), filemanager.ObjectMetadata{
+				Bucket:       "bucket",
+				ObjectKey:    strings.TrimSpace(objectKey),
+				ETag:         "etag-" + strings.TrimSpace(objectKey),
+				VersionID:    "version-" + strings.TrimSpace(objectKey),
+				SizeBytes:    int64(len(payload)),
+				LastModified: &now,
+				ContentType:  m.contentTypes[strings.TrimSpace(objectKey)],
+			}, nil
+		}
+	}
+	if m.getFn != nil {
+		return m.getFn(ctx, objectKey)
+	}
+	return io.NopCloser(strings.NewReader("")), filemanager.ObjectMetadata{}, nil
+}
+
+func (m *templateCopyStorageMock) DeleteObject(ctx context.Context, objectKey string) error {
+	return nil
+}
+
+func TestFileManagerCreateFromTemplate_UsesHelicopterFileSource(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	templateHeliFileID := uuidv7.MustBytes()
+	sourceFileID := uuidv7.MustBytes()
+	uploadIntentID := uuidv7.MustBytes()
+	createdFileID := uuidv7.MustBytes()
+
+	svc := &fileManagerTemplateServiceMock{
+		requestUploadIntentFn: func(_ context.Context, params filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+			if params.Name != "draft.docx" {
+				t.Fatalf("unexpected upload intent name: %q", params.Name)
+			}
+			return &filemanager.FileUploadIntentGrant{
+				UploadIntentID: uploadIntentID,
+				ObjectKey:      "objects/new-draft.docx",
+			}, nil
+		},
+		createFromIntentFn: func(_ context.Context, params filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+			if params.IsTemplate {
+				t.Fatal("expected created file to be a normal file, not template")
+			}
+			return &filemanager.File{
+				ID:        createdFileID,
+				ObjectKey: "objects/new-draft.docx",
+				MimeType:  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+				SizeBytes: 1024,
+			}, nil
+		},
+	}
+
+	heliSvc := &helicopterFileTemplateServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*helicopterfile.HelicopterFile, error) {
+			if !bytes.Equal(id, templateHeliFileID) {
+				t.Fatal("unexpected helicopter file id lookup")
+			}
+			return &helicopterfile.HelicopterFile{
+				ID:           templateHeliFileID,
+				HelicopterID: helicopterID,
+				SourceFile: &filemanager.File{
+					ID:         sourceFileID,
+					Name:       "template.docx",
+					ObjectKey:  "templates/template.docx",
+					MimeType:   "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+					SizeBytes:  2048,
+					IsTemplate: true,
+				},
+			}, nil
+		},
+		listByHelicopterAndSectionFn: func(_ context.Context, gotHelicopterID []byte, section string) ([]helicopterfile.HelicopterFile, error) {
+			if !bytes.Equal(gotHelicopterID, helicopterID) {
+				t.Fatal("unexpected helicopter id lookup")
+			}
+			if section != helicopterfile.SectionFlightPreparationAndWB {
+				t.Fatalf("unexpected section %q", section)
+			}
+			return nil, nil
+		},
+		createFn: func(_ context.Context, row *helicopterfile.HelicopterFile) error {
+			if row == nil {
+				t.Fatal("expected helicopter file row")
+			}
+			if !bytes.Equal(row.HelicopterID, helicopterID) {
+				t.Fatal("unexpected helicopter id on child row")
+			}
+			if !bytes.Equal(row.SourceFileID, createdFileID) {
+				t.Fatal("unexpected source file id on child row")
+			}
+			if row.Section != helicopterfile.SectionFlightPreparationAndWB {
+				t.Fatalf("unexpected section %q", row.Section)
+			}
+			return nil
+		},
+	}
+
+	docxPayload := testOfficeZip(t, []string{
+		"[Content_Types].xml",
+		"word/document.xml",
+	})
+	handler := NewFileManagerFileHandler(svc, &templateCopyStorageMock{
+		copyFn: func(_ context.Context, sourceObjectKey, destinationObjectKey string) (filemanager.ObjectMetadata, error) {
+			if sourceObjectKey != "templates/template.docx" {
+				t.Fatalf("unexpected source object key %q", sourceObjectKey)
+			}
+			if destinationObjectKey != "objects/new-draft.docx" {
+				t.Fatalf("unexpected destination object key %q", destinationObjectKey)
+			}
+			return filemanager.ObjectMetadata{}, nil
+		},
+		getFn: func(_ context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+			if objectKey != "templates/template.docx" && objectKey != "objects/new-draft.docx" {
+				t.Fatalf("unexpected object key %q", objectKey)
+			}
+			return io.NopCloser(bytes.NewReader(docxPayload)), filemanager.ObjectMetadata{
+				SizeBytes:   int64(len(docxPayload)),
+				ContentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+			}, nil
+		},
+	}).
+		WithHelicopterFileService(heliSvc).
+		WithWOPIService(service.NewWOPIService(service.WOPIConfig{
+			TokenSecret:   "test-secret",
+			EditActionURL: "https://collabora.example.com/loleaflet/{WOPISrc}",
+			PublicBaseURL: "https://api.example.com",
+			TokenTTL:      30 * time.Minute,
+		}))
+
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", actorID)
+		return c.Next()
+	})
+	app.Post("/api/v1/file-manager/files/create-from-template", handler.CreateFromTemplate)
+
+	body := `{"data":{"type":"file_manager_file_create_from_template","attributes":{"template_uuid":"` + uuidString(templateHeliFileID) + `","helicopter_id":"` + uuidString(helicopterID) + `","name":"draft.docx"}}}`
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/file-manager/files/create-from-template", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app test failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d", resp.StatusCode)
+	}
+	var out struct {
+		Data struct {
+			FileID          string `json:"file_id"`
+			CollaboraAction string `json:"collabora_action"`
+			AccessToken     string `json:"access_token"`
+			AccessTokenTTL  int64  `json:"access_token_ttl"`
+		} `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Data.FileID != uuidString(createdFileID) {
+		t.Fatalf("unexpected file id %q", out.Data.FileID)
+	}
+	assertWOPIActionContainsAccessToken(t, out.Data.CollaboraAction, out.Data.AccessToken)
+	if out.Data.AccessTokenTTL <= 0 {
+		t.Fatalf("expected positive access token ttl, got %d", out.Data.AccessTokenTTL)
+	}
+	if svc.requestUploadIntentCalls != 1 || svc.createFromIntentCalls != 1 || svc.createAttachmentCalls != 0 || svc.updateFileCalls != 1 {
+		t.Fatalf("unexpected service call counts: upload=%d create=%d attach=%d update=%d", svc.requestUploadIntentCalls, svc.createFromIntentCalls, svc.createAttachmentCalls, svc.updateFileCalls)
+	}
+	if heliSvc.createCalls != 1 || heliSvc.listCalls != 1 {
+		t.Fatalf("unexpected helicopter file call counts: create=%d list=%d", heliSvc.createCalls, heliSvc.listCalls)
+	}
+}
+
+func TestFileManagerCreateFromTemplate_UpdatesUploadIntentSizeAfterXLSXSanitize(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	templateHeliFileID := uuidv7.MustBytes()
+	sourceFileID := uuidv7.MustBytes()
+	uploadIntentID := uuidv7.MustBytes()
+	createdFileID := uuidv7.MustBytes()
+
+	originalPayload := testMalformedXLSXZip(t)
+	sanitizedPayload, _, changed, err := sanitizeXLSXPayload(originalPayload)
+	if err != nil {
+		t.Fatalf("sanitize payload: %v", err)
+	}
+	if !changed {
+		t.Fatal("expected malformed xlsx payload to be sanitized")
+	}
+	expectedSize := int64(len(sanitizedPayload))
+
+	var updatedUploadIntentSize int64
+	svc := &fileManagerTemplateServiceMock{
+		requestUploadIntentFn: func(_ context.Context, params filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+			if params.SizeBytes != int64(len(originalPayload)) {
+				t.Fatalf("unexpected upload intent size: %d", params.SizeBytes)
+			}
+			return &filemanager.FileUploadIntentGrant{
+				UploadIntentID: uploadIntentID,
+				ObjectKey:      "objects/new-draft.xlsx",
+			}, nil
+		},
+		updateUploadIntentSizeFn: func(_ context.Context, params filemanager.FileUploadIntentSizeUpdateParams) error {
+			updatedUploadIntentSize = params.SizeBytes
+			if !bytes.Equal(params.ID, uploadIntentID) {
+				t.Fatalf("unexpected upload intent id: %x", params.ID)
+			}
+			if params.SizeBytes != expectedSize {
+				t.Fatalf("unexpected sanitized size: got %d want %d", params.SizeBytes, expectedSize)
+			}
+			return nil
+		},
+		createFromIntentFn: func(_ context.Context, params filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+			if updatedUploadIntentSize != expectedSize {
+				t.Fatalf("expected upload intent size update before finalize, got %d want %d", updatedUploadIntentSize, expectedSize)
+			}
+			return &filemanager.File{
+				ID:        createdFileID,
+				ObjectKey: "objects/new-draft.xlsx",
+				MimeType:  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+				SizeBytes: expectedSize,
+			}, nil
+		},
+	}
+
+	heliSvc := &helicopterFileTemplateServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*helicopterfile.HelicopterFile, error) {
+			if !bytes.Equal(id, templateHeliFileID) {
+				t.Fatal("unexpected helicopter file id lookup")
+			}
+			return &helicopterfile.HelicopterFile{
+				ID:           templateHeliFileID,
+				HelicopterID: helicopterID,
+				SourceFile: &filemanager.File{
+					ID:         sourceFileID,
+					Name:       "template.xlsx",
+					ObjectKey:  "templates/template.xlsx",
+					MimeType:   "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+					SizeBytes:  int64(len(originalPayload)),
+					IsTemplate: true,
+				},
+			}, nil
+		},
+		listByHelicopterAndSectionFn: func(_ context.Context, gotHelicopterID []byte, section string) ([]helicopterfile.HelicopterFile, error) {
+			if !bytes.Equal(gotHelicopterID, helicopterID) {
+				t.Fatal("unexpected helicopter id lookup")
+			}
+			if section != helicopterfile.SectionFlightPreparationAndWB {
+				t.Fatalf("unexpected section %q", section)
+			}
+			return nil, nil
+		},
+		createFn: func(_ context.Context, row *helicopterfile.HelicopterFile) error {
+			if row == nil {
+				t.Fatal("expected helicopter file row")
+			}
+			if !bytes.Equal(row.HelicopterID, helicopterID) {
+				t.Fatal("unexpected helicopter id on child row")
+			}
+			if !bytes.Equal(row.SourceFileID, createdFileID) {
+				t.Fatal("unexpected source file id on child row")
+			}
+			return nil
+		},
+	}
+
+	handler := NewFileManagerFileHandler(svc, &templateCopyStorageMock{
+		copyFn: func(_ context.Context, sourceObjectKey, destinationObjectKey string) (filemanager.ObjectMetadata, error) {
+			if sourceObjectKey != "templates/template.xlsx" {
+				t.Fatalf("unexpected source object key %q", sourceObjectKey)
+			}
+			if destinationObjectKey != "objects/new-draft.xlsx" {
+				t.Fatalf("unexpected destination object key %q", destinationObjectKey)
+			}
+			return filemanager.ObjectMetadata{}, nil
+		},
+		getFn: func(_ context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+			if objectKey != "templates/template.xlsx" && objectKey != "objects/new-draft.xlsx" {
+				t.Fatalf("unexpected object key %q", objectKey)
+			}
+			return io.NopCloser(bytes.NewReader(originalPayload)), filemanager.ObjectMetadata{
+				SizeBytes:   int64(len(originalPayload)),
+				ContentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+			}, nil
+		},
+	}).
+		WithHelicopterFileService(heliSvc).
+		WithWOPIService(service.NewWOPIService(service.WOPIConfig{
+			TokenSecret:   "test-secret",
+			EditActionURL: "https://collabora.example.com/loleaflet/{WOPISrc}",
+			PublicBaseURL: "https://api.example.com",
+			TokenTTL:      30 * time.Minute,
+		}))
+
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", actorID)
+		return c.Next()
+	})
+	app.Post("/api/v1/file-manager/files/create-from-template", handler.CreateFromTemplate)
+
+	body := `{"data":{"type":"file_manager_file_create_from_template","attributes":{"template_uuid":"` + uuidString(templateHeliFileID) + `","helicopter_id":"` + uuidString(helicopterID) + `","name":"draft.xlsx"}}}`
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/file-manager/files/create-from-template", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app test failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d", resp.StatusCode)
+	}
+	if svc.requestUploadIntentCalls != 1 || svc.updateUploadIntentCalls != 1 || svc.createFromIntentCalls != 1 {
+		t.Fatalf("unexpected service call counts: upload=%d update_intent=%d create=%d", svc.requestUploadIntentCalls, svc.updateUploadIntentCalls, svc.createFromIntentCalls)
+	}
+	if updatedUploadIntentSize != expectedSize {
+		t.Fatalf("unexpected updated upload intent size: got %d want %d", updatedUploadIntentSize, expectedSize)
+	}
+}
+
+func TestFileManagerCreateFromTemplate_AttachesNewTakeoverFile(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	templateHeliFileID := uuidv7.MustBytes()
+	sourceFileID := uuidv7.MustBytes()
+	createdFileID := uuidv7.MustBytes()
+	attachmentID := uuidv7.MustBytes()
+	attachCalls := 0
+
+	svc := &fileManagerTemplateServiceMock{
+		requestUploadIntentFn: func(_ context.Context, params filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+			if params.Name != "draft.docx" {
+				t.Fatalf("unexpected upload intent name %q", params.Name)
+			}
+			return &filemanager.FileUploadIntentGrant{
+				UploadIntentID: uuidv7.MustBytes(),
+				ObjectKey:      "objects/new-draft.docx",
+			}, nil
+		},
+		createFromIntentFn: func(_ context.Context, params filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+			if params.Name != "draft.docx" {
+				t.Fatalf("unexpected create-from-intent name %q", params.Name)
+			}
+			return &filemanager.File{
+				ID:             createdFileID,
+				Name:           "draft.docx",
+				NameNormalized: "draft.docx",
+				ObjectKey:      "objects/new-draft.docx",
+				MimeType:       "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+				SizeBytes:      1024,
+				Status:         filemanager.FileStatusReady,
+			}, nil
+		},
+		createAttachmentFn: func(_ context.Context, params filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+			if !bytes.Equal(params.FileID, createdFileID) {
+				t.Fatalf("unexpected attachment file id")
+			}
+			if params.RefType != "takeover" {
+				t.Fatalf("unexpected attachment ref type %q", params.RefType)
+			}
+			if params.RefID != uuidString(takeoverID) {
+				t.Fatalf("unexpected attachment ref id %q", params.RefID)
+			}
+			return &filemanager.Attachment{ID: attachmentID, FileID: createdFileID, RefType: "takeover", RefID: uuidString(takeoverID)}, nil
+		},
+	}
+	heliSvc := &helicopterFileTemplateServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*helicopterfile.HelicopterFile, error) {
+			if !bytes.Equal(id, templateHeliFileID) {
+				t.Fatal("unexpected helicopter file id lookup")
+			}
+			return &helicopterfile.HelicopterFile{
+				ID:           templateHeliFileID,
+				HelicopterID: helicopterID,
+				SourceFile: &filemanager.File{
+					ID:        sourceFileID,
+					Name:      "template.docx",
+					ObjectKey: "templates/template.docx",
+					MimeType:  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+					SizeBytes: 2048,
+				},
+			}, nil
+		},
+		listByHelicopterAndSectionFn: func(_ context.Context, gotHelicopterID []byte, section string) ([]helicopterfile.HelicopterFile, error) {
+			if !bytes.Equal(gotHelicopterID, helicopterID) {
+				t.Fatal("unexpected helicopter id lookup")
+			}
+			if section != helicopterfile.SectionFlightPreparationAndWB {
+				t.Fatalf("unexpected section %q", section)
+			}
+			return []helicopterfile.HelicopterFile{}, nil
+		},
+	}
+	takeoverSvc := &takeoverTemplateServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*takeoverdomain.TakeoverAc, error) {
+			if !bytes.Equal(id, takeoverID) {
+				t.Fatal("unexpected takeover id lookup")
+			}
+			return &takeoverdomain.TakeoverAc{ID: takeoverID, CreatedBy: actorID}, nil
+		},
+		attachFn: func(_ context.Context, gotTakeoverID, gotAttachmentID []byte) error {
+			attachCalls++
+			if !bytes.Equal(gotTakeoverID, takeoverID) {
+				t.Fatal("unexpected takeover attach id")
+			}
+			if !bytes.Equal(gotAttachmentID, attachmentID) {
+				t.Fatal("unexpected attachment attach id")
+			}
+			return nil
+		},
+	}
+
+	docxPayload := testOfficeZip(t, []string{
+		"[Content_Types].xml",
+		"word/document.xml",
+	})
+	handler := NewFileManagerFileHandler(svc, &templateCopyStorageMock{
+		copyFn: func(_ context.Context, sourceObjectKey, destinationObjectKey string) (filemanager.ObjectMetadata, error) {
+			if sourceObjectKey != "templates/template.docx" {
+				t.Fatalf("unexpected source object key %q", sourceObjectKey)
+			}
+			if destinationObjectKey != "objects/new-draft.docx" {
+				t.Fatalf("unexpected destination object key %q", destinationObjectKey)
+			}
+			return filemanager.ObjectMetadata{}, nil
+		},
+		getFn: func(_ context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+			if objectKey != "templates/template.docx" && objectKey != "objects/new-draft.docx" {
+				t.Fatalf("unexpected object key %q", objectKey)
+			}
+			return io.NopCloser(bytes.NewReader(docxPayload)), filemanager.ObjectMetadata{
+				SizeBytes:   int64(len(docxPayload)),
+				ContentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+			}, nil
+		},
+	}).
+		WithHelicopterFileService(heliSvc).
+		WithTakeoverService(takeoverSvc).
+		WithWOPIService(service.NewWOPIService(service.WOPIConfig{
+			TokenSecret:   "test-secret",
+			EditActionURL: "https://collabora.example.com/loleaflet/{WOPISrc}",
+			PublicBaseURL: "https://api.example.com",
+			TokenTTL:      30 * time.Minute,
+		}))
+
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", actorID)
+		return c.Next()
+	})
+	app.Post("/api/v1/file-manager/files/create-from-template", handler.CreateFromTemplate)
+
+	body := `{"data":{"type":"file_manager_file_create_from_template","attributes":{"template_uuid":"` + uuidString(templateHeliFileID) + `","helicopter_id":"` + uuidString(helicopterID) + `","takeover_id":"` + uuidString(takeoverID) + `","name":"draft.docx"}}}`
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/file-manager/files/create-from-template", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app test failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d", resp.StatusCode)
+	}
+	var out struct {
+		Data struct {
+			FileID          string `json:"file_id"`
+			CollaboraAction string `json:"collabora_action"`
+			AccessToken     string `json:"access_token"`
+			AccessTokenTTL  int64  `json:"access_token_ttl"`
+		} `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Data.FileID != uuidString(createdFileID) {
+		t.Fatalf("unexpected file id %q", out.Data.FileID)
+	}
+	assertWOPIActionContainsAccessToken(t, out.Data.CollaboraAction, out.Data.AccessToken)
+	if out.Data.AccessTokenTTL <= 0 {
+		t.Fatalf("expected positive access token ttl, got %d", out.Data.AccessTokenTTL)
+	}
+	if svc.requestUploadIntentCalls != 1 || svc.createFromIntentCalls != 1 || svc.createAttachmentCalls != 1 || svc.updateFileCalls != 1 {
+		t.Fatalf("unexpected service call counts: upload=%d create=%d attach=%d update=%d", svc.requestUploadIntentCalls, svc.createFromIntentCalls, svc.createAttachmentCalls, svc.updateFileCalls)
+	}
+	if heliSvc.createCalls != 1 || heliSvc.listCalls != 1 {
+		t.Fatalf("unexpected helicopter file call counts: create=%d list=%d", heliSvc.createCalls, heliSvc.listCalls)
+	}
+	if attachCalls != 1 {
+		t.Fatalf("expected one takeover attach call, got %d", attachCalls)
+	}
+}
+
+func TestFileManagerCreateFromTemplate_ReusesExistingTakeoverFile(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	templateHeliFileID := uuidv7.MustBytes()
+	sourceFileID := uuidv7.MustBytes()
+	existingFileID := uuidv7.MustBytes()
+	attachmentID := uuidv7.MustBytes()
+	attachCalls := 0
+
+	svc := &fileManagerTemplateServiceMock{
+		createAttachmentFn: func(_ context.Context, params filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+			if !bytes.Equal(params.FileID, existingFileID) {
+				t.Fatal("unexpected attachment file id")
+			}
+			if params.RefType != "takeover" {
+				t.Fatalf("unexpected attachment ref type %q", params.RefType)
+			}
+			if params.RefID != uuidString(takeoverID) {
+				t.Fatalf("unexpected attachment ref id %q", params.RefID)
+			}
+			return &filemanager.Attachment{ID: attachmentID, FileID: existingFileID, RefType: "takeover", RefID: uuidString(takeoverID)}, nil
+		},
+	}
+	svc.getByTemplateTakeoverFn = func(_ context.Context, gotTemplateID, gotTakeoverID []byte) (*filemanager.File, error) {
+		if !bytes.Equal(gotTemplateID, templateHeliFileID) {
+			t.Fatal("unexpected template lookup id")
+		}
+		if !bytes.Equal(gotTakeoverID, takeoverID) {
+			t.Fatal("unexpected takeover lookup id")
+		}
+		return &filemanager.File{
+			ID:             existingFileID,
+			Name:           "draft.docx",
+			NameNormalized: "draft.docx",
+			NameSlot:       "draft",
+			ObjectKey:      "objects/existing-draft.docx",
+			MimeType:       "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+			SizeBytes:      1024,
+			Status:         filemanager.FileStatusReady,
+			TemplateUUID:   templateHeliFileID,
+			TakeoverID:     takeoverID,
+		}, nil
+	}
+	heliSvc := &helicopterFileTemplateServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*helicopterfile.HelicopterFile, error) {
+			if !bytes.Equal(id, templateHeliFileID) {
+				t.Fatal("unexpected helicopter file id lookup")
+			}
+			return &helicopterfile.HelicopterFile{
+				ID:           templateHeliFileID,
+				HelicopterID: helicopterID,
+				SourceFile: &filemanager.File{
+					ID:        sourceFileID,
+					Name:      "template.docx",
+					ObjectKey: "templates/template.docx",
+					MimeType:  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+					SizeBytes: 2048,
+				},
+			}, nil
+		},
+		listByHelicopterAndSectionFn: func(_ context.Context, gotHelicopterID []byte, section string) ([]helicopterfile.HelicopterFile, error) {
+			if !bytes.Equal(gotHelicopterID, helicopterID) {
+				t.Fatal("unexpected helicopter id lookup")
+			}
+			if section != helicopterfile.SectionFlightPreparationAndWB {
+				t.Fatalf("unexpected section %q", section)
+			}
+			return []helicopterfile.HelicopterFile{
+				{
+					ID:           uuidv7.MustBytes(),
+					Section:      helicopterfile.SectionFlightPreparationAndWB,
+					HelicopterID: helicopterID,
+					SourceFileID: existingFileID,
+				},
+			}, nil
+		},
+	}
+	takeoverSvc := &takeoverTemplateServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*takeoverdomain.TakeoverAc, error) {
+			if !bytes.Equal(id, takeoverID) {
+				t.Fatal("unexpected takeover id lookup")
+			}
+			return &takeoverdomain.TakeoverAc{
+				ID:        takeoverID,
+				CreatedBy: actorID,
+			}, nil
+		},
+		attachFn: func(_ context.Context, gotTakeoverID, gotAttachmentID []byte) error {
+			attachCalls++
+			if !bytes.Equal(gotTakeoverID, takeoverID) {
+				t.Fatal("unexpected takeover attach id")
+			}
+			if !bytes.Equal(gotAttachmentID, attachmentID) {
+				t.Fatal("unexpected attachment attach id")
+			}
+			return nil
+		},
+	}
+
+	docxPayload := testOfficeZip(t, []string{
+		"[Content_Types].xml",
+		"word/document.xml",
+	})
+	handler := NewFileManagerFileHandler(svc, &templateCopyStorageMock{
+		getFn: func(_ context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+			if objectKey != "templates/template.docx" && objectKey != "objects/existing-draft.docx" {
+				t.Fatalf("unexpected object key %q", objectKey)
+			}
+			return io.NopCloser(bytes.NewReader(docxPayload)), filemanager.ObjectMetadata{
+				SizeBytes:   int64(len(docxPayload)),
+				ContentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+			}, nil
+		},
+	}).
+		WithHelicopterFileService(heliSvc).
+		WithTakeoverService(takeoverSvc).
+		WithWOPIService(service.NewWOPIService(service.WOPIConfig{
+			TokenSecret:   "test-secret",
+			EditActionURL: "https://collabora.example.com/loleaflet/{WOPISrc}",
+			PublicBaseURL: "https://api.example.com",
+			TokenTTL:      30 * time.Minute,
+		}))
+
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", actorID)
+		return c.Next()
+	})
+	app.Post("/api/v1/file-manager/files/create-from-template", handler.CreateFromTemplate)
+
+	body := `{"data":{"type":"file_manager_file_create_from_template","attributes":{"template_uuid":"` + uuidString(templateHeliFileID) + `","helicopter_id":"` + uuidString(helicopterID) + `","takeover_id":"` + uuidString(takeoverID) + `","name":"draft.docx"}}}`
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/file-manager/files/create-from-template", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app test failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d", resp.StatusCode)
+	}
+	var out struct {
+		Data struct {
+			FileID          string `json:"file_id"`
+			CollaboraAction string `json:"collabora_action"`
+			AccessToken     string `json:"access_token"`
+			AccessTokenTTL  int64  `json:"access_token_ttl"`
+		} `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Data.FileID != uuidString(existingFileID) {
+		t.Fatalf("unexpected file id %q", out.Data.FileID)
+	}
+	assertWOPIActionContainsAccessToken(t, out.Data.CollaboraAction, out.Data.AccessToken)
+	if out.Data.AccessTokenTTL <= 0 {
+		t.Fatalf("expected positive access token ttl, got %d", out.Data.AccessTokenTTL)
+	}
+	if svc.requestUploadIntentCalls != 0 || svc.createFromIntentCalls != 0 || svc.createAttachmentCalls != 1 || svc.updateFileCalls != 0 {
+		t.Fatalf("unexpected service call counts: upload=%d create=%d attach=%d update=%d", svc.requestUploadIntentCalls, svc.createFromIntentCalls, svc.createAttachmentCalls, svc.updateFileCalls)
+	}
+	if heliSvc.createCalls != 0 || heliSvc.listCalls != 1 {
+		t.Fatalf("unexpected helicopter file call counts: create=%d list=%d", heliSvc.createCalls, heliSvc.listCalls)
+	}
+	if attachCalls != 1 {
+		t.Fatalf("expected one takeover attach call, got %d", attachCalls)
+	}
+}
+
+func TestFileManagerCreateFromTemplate_DoesNotReuseNameMatchedTakeoverFileWithoutTemplateMetadata(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	templateHeliFileID := uuidv7.MustBytes()
+	sourceFileID := uuidv7.MustBytes()
+	createdFileID := uuidv7.MustBytes()
+
+	svc := &fileManagerTemplateServiceMock{
+		requestUploadIntentFn: func(_ context.Context, params filemanager.RequestFileUploadIntentParams) (*filemanager.FileUploadIntentGrant, error) {
+			if params.Name != "draft.xlsx" {
+				t.Fatalf("unexpected upload intent name %q", params.Name)
+			}
+			return &filemanager.FileUploadIntentGrant{
+				UploadIntentID: uuidv7.MustBytes(),
+				ObjectKey:      "objects/new-draft.xlsx",
+				Name:           "draft.xlsx",
+				MimeType:       "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+				SizeBytes:      int64(len(testXLSXZip(t))),
+			}, nil
+		},
+		createFromIntentFn: func(_ context.Context, params filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+			if params.Name != "draft.xlsx" {
+				t.Fatalf("unexpected create-from-intent name %q", params.Name)
+			}
+			return &filemanager.File{
+				ID:        createdFileID,
+				Name:      "draft.xlsx",
+				ObjectKey: "objects/new-draft.xlsx",
+				MimeType:  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+				SizeBytes: int64(len(testXLSXZip(t))),
+				Status:    filemanager.FileStatusReady,
+			}, nil
+		},
+		createAttachmentFn: func(_ context.Context, params filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+			return &filemanager.Attachment{ID: uuidv7.MustBytes(), FileID: params.FileID, RefType: params.RefType, RefID: params.RefID}, nil
+		},
+		getByTemplateTakeoverFn: func(_ context.Context, gotTemplateID, gotTakeoverID []byte) (*filemanager.File, error) {
+			if !bytes.Equal(gotTemplateID, templateHeliFileID) || !bytes.Equal(gotTakeoverID, takeoverID) {
+				t.Fatal("unexpected template/takeover lookup args")
+			}
+			return nil, nil
+		},
+	}
+
+	heliSvc := &helicopterFileTemplateServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*helicopterfile.HelicopterFile, error) {
+			if !bytes.Equal(id, templateHeliFileID) {
+				t.Fatal("unexpected helicopter file id lookup")
+			}
+			return &helicopterfile.HelicopterFile{
+				ID:           templateHeliFileID,
+				HelicopterID: helicopterID,
+				SourceFile: &filemanager.File{
+					ID:        sourceFileID,
+					Name:      "template.xlsx",
+					ObjectKey: "templates/template.xlsx",
+					MimeType:  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+					SizeBytes: int64(len(testXLSXZip(t))),
+				},
+			}, nil
+		},
+		listByHelicopterAndSectionFn: func(_ context.Context, gotHelicopterID []byte, section string) ([]helicopterfile.HelicopterFile, error) {
+			if !bytes.Equal(gotHelicopterID, helicopterID) {
+				t.Fatal("unexpected helicopter id lookup")
+			}
+			if section != helicopterfile.SectionFlightPreparationAndWB {
+				t.Fatalf("unexpected section %q", section)
+			}
+			return nil, nil
+		},
+	}
+
+	takeoverSvc := &takeoverTemplateServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*takeoverdomain.TakeoverAc, error) {
+			if !bytes.Equal(id, takeoverID) {
+				t.Fatal("unexpected takeover id lookup")
+			}
+			return &takeoverdomain.TakeoverAc{
+				ID:        takeoverID,
+				CreatedBy: actorID,
+				Files: []takeoverdomain.TakeoverFile{
+					{
+						FileAttachment: &filemanager.Attachment{
+							File: &filemanager.File{
+								ID:             uuidv7.MustBytes(),
+								Name:           "draft.xlsx",
+								NameNormalized: "draft.xlsx",
+								ObjectKey:      "objects/blank-draft.xlsx",
+								MimeType:       "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+								Status:         filemanager.FileStatusReady,
+							},
+						},
+					},
+				},
+			}, nil
+		},
+		attachFn: func(_ context.Context, gotTakeoverID, _ []byte) error {
+			if !bytes.Equal(gotTakeoverID, takeoverID) {
+				t.Fatal("unexpected takeover attach id")
+			}
+			return nil
+		},
+	}
+
+	templatePayload := testXLSXZip(t)
+	wopiSvc := service.NewWOPIService(service.WOPIConfig{
+		TokenSecret:   "test-secret",
+		EditActionURL: "https://collabora.example.com/loleaflet/{WOPISrc}",
+		PublicBaseURL: "https://api.example.com",
+		TokenTTL:      30 * time.Minute,
+	})
+	handler := NewFileManagerFileHandler(svc, &templateCopyStorageMock{
+		copyFn: func(_ context.Context, sourceObjectKey, destinationObjectKey string) (filemanager.ObjectMetadata, error) {
+			if sourceObjectKey != "templates/template.xlsx" || destinationObjectKey != "objects/new-draft.xlsx" {
+				t.Fatalf("unexpected copy %q -> %q", sourceObjectKey, destinationObjectKey)
+			}
+			return filemanager.ObjectMetadata{}, nil
+		},
+		getFn: func(_ context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+			switch objectKey {
+			case "templates/template.xlsx", "objects/new-draft.xlsx":
+				return io.NopCloser(bytes.NewReader(templatePayload)), filemanager.ObjectMetadata{
+					SizeBytes:   int64(len(templatePayload)),
+					ContentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+				}, nil
+			default:
+				t.Fatalf("unexpected object key %q", objectKey)
+				return nil, filemanager.ObjectMetadata{}, nil
+			}
+		},
+	}).
+		WithHelicopterFileService(heliSvc).
+		WithTakeoverService(takeoverSvc).
+		WithWOPIService(wopiSvc)
+
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", actorID)
+		return c.Next()
+	})
+	app.Post("/api/v1/file-manager/files/create-from-template", handler.CreateFromTemplate)
+
+	body := `{"data":{"type":"file_manager_file_create_from_template","attributes":{"template_uuid":"` + uuidString(templateHeliFileID) + `","helicopter_id":"` + uuidString(helicopterID) + `","takeover_id":"` + uuidString(takeoverID) + `","name":"draft.xlsx"}}}`
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/file-manager/files/create-from-template", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app test failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d", resp.StatusCode)
+	}
+
+	var out struct {
+		Data struct {
+			FileID      string `json:"file_id"`
+			AccessToken string `json:"access_token"`
+		} `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Data.FileID != uuidString(createdFileID) {
+		t.Fatalf("expected a fresh template copy, got file id %q", out.Data.FileID)
+	}
+	if svc.requestUploadIntentCalls != 1 || svc.createFromIntentCalls != 1 {
+		t.Fatalf("expected fresh copy path, got upload=%d create=%d", svc.requestUploadIntentCalls, svc.createFromIntentCalls)
+	}
+	claims, err := wopiSvc.VerifyAccessToken(out.Data.AccessToken, createdFileID)
+	if err != nil {
+		t.Fatalf("verify response token: %v", err)
+	}
+	if claims.TakeoverID != uuidString(takeoverID) {
+		t.Fatalf("expected takeover-scoped wopi token, got takeover_id %q", claims.TakeoverID)
+	}
+}
+
+func TestFileManagerCreateFromTemplate_RejectsHelicopterMismatch(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	otherHelicopterID := uuidv7.MustBytes()
+	templateHeliFileID := uuidv7.MustBytes()
+
+	svc := &fileManagerTemplateServiceMock{}
+	heliSvc := &helicopterFileTemplateServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*helicopterfile.HelicopterFile, error) {
+			if !bytes.Equal(id, templateHeliFileID) {
+				t.Fatal("unexpected helicopter file id lookup")
+			}
+			return &helicopterfile.HelicopterFile{
+				ID:           templateHeliFileID,
+				HelicopterID: otherHelicopterID,
+				SourceFile: &filemanager.File{
+					ID:        uuidv7.MustBytes(),
+					Name:      "template.docx",
+					ObjectKey: "templates/template.docx",
+					MimeType:  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+					SizeBytes: 2048,
+				},
+			}, nil
+		},
+	}
+	handler := NewFileManagerFileHandler(svc, &templateCopyStorageMock{}).
+		WithHelicopterFileService(heliSvc).
+		WithWOPIService(service.NewWOPIService(service.WOPIConfig{
+			TokenSecret:   "test-secret",
+			EditActionURL: "https://collabora.example.com/loleaflet/{WOPISrc}",
+			PublicBaseURL: "https://api.example.com",
+			TokenTTL:      30 * time.Minute,
+		}))
+
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", actorID)
+		return c.Next()
+	})
+	app.Post("/api/v1/file-manager/files/create-from-template", handler.CreateFromTemplate)
+
+	body := `{"data":{"type":"file_manager_file_create_from_template","attributes":{"template_uuid":"` + uuidString(templateHeliFileID) + `","helicopter_id":"` + uuidString(helicopterID) + `","name":"draft.docx"}}}`
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/file-manager/files/create-from-template", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app test failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("unexpected status %d", resp.StatusCode)
+	}
+	if svc.requestUploadIntentCalls != 0 {
+		t.Fatalf("expected no upload intent call, got %d", svc.requestUploadIntentCalls)
+	}
+}
+
+func TestFileManagerEditSession_AllowsDraftOwnerWithoutTakeover(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	docxPayload := testOfficeZip(t, []string{
+		"[Content_Types].xml",
+		"word/document.xml",
+	})
+
+	svc := &fileManagerTemplateServiceMock{
+		getFileByIDAnyFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+			if !bytes.Equal(id, fileID) {
+				t.Fatal("unexpected file id lookup")
+			}
+			return &filemanager.File{
+				ID:        fileID,
+				Name:      "draft.docx",
+				ObjectKey: "objects/draft.docx",
+				MimeType:  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+				CreatedBy: actorID,
+			}, nil
+		},
+	}
+
+	handler := NewFileManagerFileHandler(svc, &templateCopyStorageMock{
+		getFn: func(_ context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+			if objectKey != "objects/draft.docx" {
+				t.Fatalf("unexpected object key %q", objectKey)
+			}
+			return io.NopCloser(bytes.NewReader(docxPayload)), filemanager.ObjectMetadata{
+				SizeBytes:   int64(len(docxPayload)),
+				ContentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+			}, nil
+		},
+	}).
+		WithTakeoverService(&takeoverTemplateServiceMock{}).
+		WithWOPIService(service.NewWOPIService(service.WOPIConfig{
+			TokenSecret:   "test-secret",
+			EditActionURL: "https://collabora.example.com/loleaflet/{WOPISrc}",
+			PublicBaseURL: "https://api.example.com",
+			TokenTTL:      30 * time.Minute,
+		}))
+
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", actorID)
+		return c.Next()
+	})
+	app.Get("/api/v1/file-manager/files/:fileId/edit-session", handler.EditSession)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/file-manager/files/"+uuidString(fileID)+"/edit-session", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app test failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d", resp.StatusCode)
+	}
+	var out struct {
+		Data struct {
+			FileID          string `json:"file_id"`
+			CollaboraAction string `json:"collabora_action"`
+			AccessToken     string `json:"access_token"`
+			AccessTokenTTL  int64  `json:"access_token_ttl"`
+		} `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Data.FileID != uuidString(fileID) {
+		t.Fatalf("unexpected file id %q", out.Data.FileID)
+	}
+	assertWOPIActionContainsAccessToken(t, out.Data.CollaboraAction, out.Data.AccessToken)
+	if out.Data.AccessTokenTTL <= 0 {
+		t.Fatalf("expected positive access token ttl, got %d", out.Data.AccessTokenTTL)
+	}
+}
+
+func TestValidateWOPISaveContent_AllowsGenericCollaboraContentType(t *testing.T) {
+	xlsxPayload := testXLSXZip(t)
+
+	if err := validateWOPISaveContent("draft.xlsx", "application/octet-stream", xlsxPayload); err != nil {
+		t.Fatalf("expected generic Collabora content type to be accepted: %v", err)
+	}
+}
+
+func TestValidateWOPISaveContent_RejectsIncompleteXLSX(t *testing.T) {
+	xlsxPayload := testOfficeZip(t, []string{
+		"[Content_Types].xml",
+		"xl/workbook.xml",
+		"xl/_rels/workbook.xml.rels",
+	})
+
+	if err := validateWOPISaveContent("draft.xlsx", "application/octet-stream", xlsxPayload); err == nil {
+		t.Fatal("expected incomplete xlsx to be rejected")
+	}
+}
+
+func assertWOPIActionContainsAccessToken(t *testing.T, actionURL, expectedToken string) {
+	t.Helper()
+	if strings.TrimSpace(actionURL) == "" {
+		t.Fatal("expected collabora action url")
+	}
+	if strings.TrimSpace(expectedToken) == "" {
+		t.Fatal("expected access token in response")
+	}
+	parsed, err := url.Parse(actionURL)
+	if err != nil {
+		t.Fatalf("parse collabora action url: %v", err)
+	}
+	// access_token and access_token_ttl must be SEPARATE top-level query params of
+	// the action URL (WOPI/Collabora contract), NOT embedded inside WOPISrc.
+	if got := parsed.Query().Get("access_token"); got != expectedToken {
+		t.Fatalf("unexpected access token in action url: got %q want %q", got, expectedToken)
+	}
+	if got := strings.TrimSpace(parsed.Query().Get("access_token_ttl")); got == "" {
+		t.Fatal("expected access_token_ttl in action url")
+	}
+
+	// WOPISrc must be present and must be the BARE file URL with no embedded token.
+	wopiSrcEncoded := strings.TrimSpace(parsed.Query().Get("WOPISrc"))
+	if wopiSrcEncoded == "" {
+		wopiSrcEncoded = strings.TrimSpace(path.Base(parsed.EscapedPath()))
+	}
+	if wopiSrcEncoded == "" {
+		t.Fatal("expected WOPISrc in collabora action url")
+	}
+	wopiSrc, err := url.QueryUnescape(wopiSrcEncoded)
+	if err != nil {
+		t.Fatalf("unescape WOPISrc: %v", err)
+	}
+	wopiParsed, err := url.Parse(wopiSrc)
+	if err != nil {
+		t.Fatalf("parse WOPISrc: %v", err)
+	}
+	if got := wopiParsed.Query().Get("access_token"); got != "" {
+		t.Fatalf("WOPISrc must not embed access_token, got %q", got)
+	}
+}
+
+func uuidString(id []byte) string {
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		return ""
+	}
+	return s
+}
+
+func testOfficeZip(t *testing.T, entries []string) []byte {
+	t.Helper()
+
+	contents := make(map[string]string, len(entries))
+	for _, entry := range entries {
+		contents[entry] = "<xml/>"
+	}
+	return testOfficeZipWithContents(t, contents)
+}
+
+func testXLSXZip(t *testing.T) []byte {
+	t.Helper()
+	return testOfficeZipWithContents(t, map[string]string{
+		"[Content_Types].xml": `<?xml version="1.0" encoding="UTF-8"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+  <Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>
+  <Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
+</Types>`,
+		"xl/workbook.xml": `<?xml version="1.0" encoding="UTF-8"?>
+<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+  xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+  <sheets>
+    <sheet name="Sheet1" sheetId="1" r:id="rId1"/>
+  </sheets>
+</workbook>`,
+		"xl/_rels/workbook.xml.rels": `<?xml version="1.0" encoding="UTF-8"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>
+</Relationships>`,
+		"xl/worksheets/sheet1.xml": `<?xml version="1.0" encoding="UTF-8"?>
+<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
+  <sheetData/>
+</worksheet>`,
+	})
+}
+
+func testOfficeZipWithContents(t *testing.T, contents map[string]string) []byte {
+	t.Helper()
+
+	var buf bytes.Buffer
+	writer := zip.NewWriter(&buf)
+	for entry, content := range contents {
+		w, err := writer.Create(entry)
+		if err != nil {
+			t.Fatalf("create zip entry %q: %v", entry, err)
+		}
+		if _, err := w.Write([]byte(content)); err != nil {
+			t.Fatalf("write zip entry %q: %v", entry, err)
+		}
+	}
+	if err := writer.Close(); err != nil {
+		t.Fatalf("close zip: %v", err)
+	}
+	return buf.Bytes()
+}
diff --git a/internal/transport/http/handlers/fleet_history.go b/internal/transport/http/handlers/fleet_history.go
new file mode 100644
index 0000000..15271e0
--- /dev/null
+++ b/internal/transport/http/handlers/fleet_history.go
@@ -0,0 +1,20 @@
+package handlers
+
+import (
+	"context"
+
+	fleethistory "wucher/internal/domain/fleet_history"
+)
+
+// fleetHistoryRecorder appends append-only events to a helicopter's timeline.
+// Logging is best-effort: callers ignore the returned error so a logging failure
+// never blocks the underlying action.
+type fleetHistoryRecorder interface {
+	Record(ctx context.Context, helicopterID []byte, entityType string, entityID []byte, action, message string, actor []byte) error
+	RecordByInspection(ctx context.Context, inspectionID []byte, entityType string, entityID []byte, action, message string, actor []byte) error
+}
+
+// fleetHistoryLister reads a helicopter's timeline events (for the merged history).
+type fleetHistoryLister interface {
+	ListByHelicopter(ctx context.Context, helicopterID []byte, limit, offset int) ([]fleethistory.FleetHistory, int64, error)
+}
diff --git a/internal/transport/http/handlers/fleet_status_handler.go b/internal/transport/http/handlers/fleet_status_handler.go
new file mode 100644
index 0000000..cd845ae
--- /dev/null
+++ b/internal/transport/http/handlers/fleet_status_handler.go
@@ -0,0 +1,634 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	complaint "wucher/internal/domain/complaint"
+	easarelease "wucher/internal/domain/easa_release"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	"wucher/internal/domain/helicopter"
+	"wucher/internal/domain/mcf"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type FleetStatusHandler struct {
+	svc           fleetstatus.Service
+	helicopterSvc helicopter.Service
+	complaintSvc  complaintLister
+	easaSvc       easaReleaseLister
+	historySvc    fleetHistoryLister
+	mcfSvc        fleetMCFService
+	signoffSvc    complaintSignoffLookup
+	storage       fileManagerDownloadURLStorage
+	validate      *validators.Validator
+}
+
+type FleetStatusDeps struct {
+	Helicopter helicopter.Service
+	Complaint  complaintLister
+	EASA       easaReleaseLister
+	History    fleetHistoryLister
+	MCF        fleetMCFService
+	Signoff    complaintSignoffLookup
+	Storage    fileManagerDownloadURLStorage
+}
+type complaintLister interface {
+	ListByHelicopter(ctx context.Context, helicopterID []byte, limit, offset int) ([]complaint.Complaint, int64, error)
+	ResolveUserNames(ctx context.Context, complaints []complaint.Complaint) (map[string]string, error)
+	ActiveGroundingByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) ([]complaint.Complaint, error)
+	OpenByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) ([]complaint.Complaint, error)
+}
+
+// fleetMCFService is the MCF access the fleet page needs: pending flags (for status)
+// plus the latest MCF per helicopter (for the mcf object / placeholder).
+type fleetMCFService interface {
+	mcfPendingChecker
+	LatestByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]*mcf.MaintenanceCheckFlight, error)
+}
+
+type easaReleaseLister interface {
+	GetLatestByHelicopter(ctx context.Context, helicopterID []byte) (*easarelease.EASARelease, error)
+}
+
+func NewFleetStatusHandler(svc fleetstatus.Service, deps FleetStatusDeps) *FleetStatusHandler {
+	if svc == nil || deps.Helicopter == nil || deps.Complaint == nil || deps.EASA == nil ||
+		deps.History == nil || deps.MCF == nil || deps.Storage == nil {
+		panic("fleet status handler: missing required dependency")
+	}
+	return &FleetStatusHandler{
+		svc:           svc,
+		helicopterSvc: deps.Helicopter,
+		complaintSvc:  deps.Complaint,
+		easaSvc:       deps.EASA,
+		historySvc:    deps.History,
+		mcfSvc:        deps.MCF,
+		signoffSvc:    deps.Signoff,
+		storage:       deps.Storage,
+		validate:      validators.New(),
+	}
+}
+
+// CreateFleetStatus godoc
+// @Summary Create fleet status
+// @Description Create fleet status with maintenance schedules and file attachments.
+// @Tags Fleet Status
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FleetStatusCreateRequest true "Fleet status create request"
+// @Success 201 {object} responsedto.FleetStatusResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fleet-status/create [post]
+func (h *FleetStatusHandler) Create(c *fiber.Ctx) error {
+	var req requestdto.FleetStatusCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusInvalidJSON, "", nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeFleetStatusValidationErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	row, err := mapFleetStatusPayload(req.Data.Attributes, actorUserID(c))
+	if err != nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusInvalidPayload, "", nil)
+	}
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeFleetStatusServiceError(c, "FleetStatusHandler.Create", err)
+	}
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err != nil {
+		slog.WarnContext(c.UserContext(), "fleet status re-fetch after create failed", slog.Any("error", err), slog.String("id", idString(row.ID)))
+	}
+	if created == nil {
+		created = row
+	}
+	createdStatus := h.deriveHelicopterStatus(c.UserContext(), created.Helicopter, created.HelicopterID)
+	return response.Write(c, fiber.StatusCreated, fleetStatusDetailResource(c.UserContext(), h, created, createdStatus))
+}
+
+// UpdateFleetStatus godoc
+// @Summary Update fleet status
+// @Description Update fleet status by ID with full replacement for schedules and files.
+// @Tags Fleet Status
+// @Accept json
+// @Produce json
+// @Param id path string true "Fleet status ID (UUIDv7)"
+// @Param request body requestdto.FleetStatusUpdateRequest true "Fleet status update request"
+// @Success 200 {object} responsedto.FleetStatusResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fleet-status/update/{id} [patch]
+func (h *FleetStatusHandler) Update(c *fiber.Ctx) error {
+	idStr := c.Params("id")
+	id, err := uuidv7.ParseString(idStr)
+	if err != nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusInvalidID, "", &jsonapi.ErrorSource{Pointer: "/path/id"})
+	}
+	var req requestdto.FleetStatusUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusInvalidJSON, "", nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeFleetStatusValidationErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusIDRequired, "", &jsonapi.ErrorSource{Pointer: "/data/id"})
+	}
+	if strings.TrimSpace(req.Data.ID) != idStr {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusIDMismatch, "", &jsonapi.ErrorSource{Pointer: "/data/id"})
+	}
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusNotFound, "", nil)
+	}
+	row, err := mergeFleetStatusPatch(existing, req.Data.Attributes, actorUserID(c))
+	if err != nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusInvalidPayload, "", nil)
+	}
+	if err := h.svc.Update(c.UserContext(), row); err != nil {
+		return writeFleetStatusServiceError(c, "FleetStatusHandler.Update", err)
+	}
+	if req.Data.Attributes.Summary != nil {
+		if err := h.svc.ReviseSummary(c.UserContext(), row.HelicopterID, fleetSummaryManualInput(req.Data.Attributes.Summary), actorUserID(c)); err != nil {
+			return writeFleetStatusServiceError(c, "FleetStatusHandler.Update", err)
+		}
+	}
+	updated, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		slog.WarnContext(c.UserContext(), "fleet status re-fetch after update failed", slog.Any("error", err), slog.String("id", idString(id)))
+	}
+	if updated == nil {
+		updated = row
+	}
+	updatedStatus := h.deriveHelicopterStatus(c.UserContext(), updated.Helicopter, updated.HelicopterID)
+	return response.Write(c, fiber.StatusOK, fleetStatusDetailResource(c.UserContext(), h, updated, updatedStatus))
+}
+
+// DeleteFleetStatus godoc
+// @Summary Delete fleet status
+// @Description Soft delete fleet status by ID.
+// @Tags Fleet Status
+// @Produce json
+// @Param id path string true "Fleet status ID (UUIDv7)"
+// @Success 200 {object} responsedto.FleetStatusDeleteResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fleet-status/delete/{id} [delete]
+func (h *FleetStatusHandler) Delete(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("id"))
+	if err != nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusInvalidID, "", &jsonapi.ErrorSource{Pointer: "/path/id"})
+	}
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		return writeFleetStatusServiceError(c, "FleetStatusHandler.Delete", err)
+	}
+	return response.Write(c, fiber.StatusOK, map[string]any{"data": map[string]any{"type": "fleet_status_delete", "attributes": map[string]bool{"deleted": true}}})
+}
+
+// GetFleetStatusByID godoc
+// @Summary Get fleet status by ID
+// @Tags Fleet Status
+// @Produce json
+// @Param id path string true "Fleet status ID (UUIDv7)"
+// @Success 200 {object} responsedto.FleetStatusResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fleet-status/get/{id} [get]
+func (h *FleetStatusHandler) GetByID(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("id"))
+	if err != nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusInvalidID, "", &jsonapi.ErrorSource{Pointer: "/path/id"})
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || row == nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusNotFound, "", nil)
+	}
+	rowStatus := h.deriveHelicopterStatus(c.UserContext(), row.Helicopter, row.HelicopterID)
+	return response.Write(c, fiber.StatusOK, fleetStatusDetailResource(c.UserContext(), h, row, rowStatus))
+}
+
+// GetFleetStatusByHelicopterID godoc
+// @Summary Get latest fleet status by helicopter ID
+// @Tags Fleet Status
+// @Produce json
+// @Param helicopter_id path string true "Helicopter ID (UUIDv7)"
+// @Success 200 {object} responsedto.FleetStatusResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fleet-status/get-by-helicopter/{helicopter_id} [get]
+func (h *FleetStatusHandler) GetByHelicopterID(c *fiber.Ctx) error {
+	helicopterID, err := uuidv7.ParseString(c.Params("helicopter_id"))
+	if err != nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusInvalidID, "helicopter_id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/path/helicopter_id"})
+	}
+	latest, err := h.svc.LatestByHelicopterIDs(c.UserContext(), [][]byte{helicopterID})
+	if err != nil {
+		return writeFleetStatusServiceError(c, "FleetStatusHandler.GetByHelicopterID", err)
+	}
+	row := latest[string(helicopterID)]
+	if row == nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusNotFound, "fleet status not found for helicopter", nil)
+	}
+	rowStatus := h.deriveHelicopterStatus(c.UserContext(), row.Helicopter, row.HelicopterID)
+	return response.Write(c, fiber.StatusOK, fleetStatusDetailResource(c.UserContext(), h, row, rowStatus))
+}
+
+// ListFleetStatus godoc
+// @Summary List fleet status
+// @Description Lists every helicopter from the master, each with its latest fleet status (or empty data when it has none). Paginated by helicopter.
+// @Tags Fleet Status
+// @Produce json
+// @Param page query int false "Page number" default(1)
+// @Param page_size query int false "Page size" default(20)
+// @Param filter query string false "Search helicopters by designation/identifier/type"
+// @Param sort query string false "Sort helicopters, example: designation"
+// @Param status query string false "Filter by operational status; comma-separated for multiple (e.g. available,booked). Values: available, booked, aog, mcf"
+// @Param helicopter_id query string false "Filter by helicopter ID (UUIDv7); combined with status uses AND logic"
+// @Success 200 {object} responsedto.FleetStatusListResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fleet-status/get-all [get]
+func (h *FleetStatusHandler) List(c *fiber.Ctx) error {
+	page, _ := strconv.Atoi(c.Query("page", "1"))
+	if page < 1 {
+		page = 1
+	}
+	size, _ := strconv.Atoi(c.Query("page_size", "20"))
+	if size < 1 {
+		size = 20
+	}
+	offset := (page - 1) * size
+
+	statuses, err := parseHelicopterStatusFilter(c.Query("status"))
+	if err != nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrInvalidRequest, "invalid status filter", nil)
+	}
+
+	// If helicopter_id is provided, fetch that single helicopter and apply status
+	// filter in Go (AND logic). Pagination is irrelevant for a single result.
+	if raw := strings.TrimSpace(c.Query("helicopter_id")); raw != "" {
+		heliID, err := uuidv7.ParseString(raw)
+		if err != nil {
+			return writeFleetStatusAppError(c, apperrorsx.ErrInvalidRequest, "invalid helicopter_id", &jsonapi.ErrorSource{Pointer: "/query/helicopter_id"})
+		}
+		resources, err := h.singleHelicopterResources(c.UserContext(), heliID, statuses)
+		if err != nil {
+			return writeFleetStatusServiceError(c, "FleetStatusHandler.List", err)
+		}
+		return response.WriteWithMeta(c, fiber.StatusOK, resources, map[string]any{
+			"page_number": page,
+			"page_size":   size,
+			"total":       int64(len(resources)),
+		})
+	}
+
+	var groundedIDs [][]byte
+	if len(statuses) > 0 {
+		groundedIDs = groundedHelicopterIDs(c.UserContext(), h.complaintSvc, time.Now().UTC())
+	}
+
+	// Drive the listing from the helicopter master so each helicopter carries its
+	// latest fleet status (or empty data when it has none).
+	helis, total, err := h.helicopterSvc.List(c.UserContext(), c.Query("filter"), statuses, c.Query("sort"), size, offset, groundedIDs)
+	if err != nil {
+		return writeFleetStatusServiceError(c, "FleetStatusHandler.List", err)
+	}
+	resources, err := h.fleetStatusResourcesForHelicopters(c.UserContext(), helis)
+	if err != nil {
+		return writeFleetStatusServiceError(c, "FleetStatusHandler.List", err)
+	}
+	sortFleetStatusResourcesByStatus(resources)
+	meta := map[string]any{
+		"page_number": page,
+		"page_size":   size,
+		"total":       total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, resources, meta)
+}
+
+// ListFleetStatusDatatable godoc
+// @Summary List fleet status (datatable)
+// @Description Lists every helicopter from the master, each with its latest fleet status (or empty data when it has none). Paginated by helicopter.
+// @Tags Fleet Status
+// @Produce json
+// @Param draw query int false "Datatable draw counter" default(1)
+// @Param start query int false "Datatable start offset" default(0)
+// @Param length query int false "Datatable page length" default(10)
+// @Param search query string false "Search helicopters by designation/identifier/type"
+// @Param sort query string false "Sort helicopters, example: designation"
+// @Param status query string false "Filter by operational status; comma-separated for multiple (e.g. available,booked). Values: available, booked, aog, mcf"
+// @Param helicopter_id query string false "Filter by helicopter ID (UUIDv7); combined with status uses AND logic"
+// @Success 200 {object} responsedto.FleetStatusDataTableResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fleet-status/get-all/dt [get]
+func (h *FleetStatusHandler) ListDatatable(c *fiber.Ctx) error {
+	start, _ := strconv.Atoi(c.Query("start", "0"))
+	length, _ := strconv.Atoi(c.Query("length", "10"))
+	draw, _ := strconv.Atoi(c.Query("draw", "1"))
+	if length < 1 {
+		length = 10
+	}
+
+	statuses, err := parseHelicopterStatusFilter(c.Query("status"))
+	if err != nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrInvalidRequest, "invalid status filter", nil)
+	}
+
+	// If helicopter_id is provided, fetch that single helicopter and apply status
+	// filter in Go (AND logic).
+	if raw := strings.TrimSpace(c.Query("helicopter_id")); raw != "" {
+		heliID, err := uuidv7.ParseString(raw)
+		if err != nil {
+			return writeFleetStatusAppError(c, apperrorsx.ErrInvalidRequest, "invalid helicopter_id", &jsonapi.ErrorSource{Pointer: "/query/helicopter_id"})
+		}
+		resources, err := h.singleHelicopterResources(c.UserContext(), heliID, statuses)
+		if err != nil {
+			return writeFleetStatusServiceError(c, "FleetStatusHandler.ListDatatable", err)
+		}
+		total := int64(len(resources))
+		return response.WriteWithMeta(c, fiber.StatusOK, resources, map[string]any{
+			"draw":             draw,
+			"records_total":    total,
+			"records_filtered": total,
+		})
+	}
+
+	var groundedIDs [][]byte
+	if len(statuses) > 0 {
+		groundedIDs = groundedHelicopterIDs(c.UserContext(), h.complaintSvc, time.Now().UTC())
+	}
+
+	helis, total, err := h.helicopterSvc.List(c.UserContext(), c.Query("search"), statuses, c.Query("sort"), length, start, groundedIDs)
+	if err != nil {
+		return writeFleetStatusServiceError(c, "FleetStatusHandler.ListDatatable", err)
+	}
+	resources, err := h.fleetStatusResourcesForHelicopters(c.UserContext(), helis)
+	if err != nil {
+		return writeFleetStatusServiceError(c, "FleetStatusHandler.ListDatatable", err)
+	}
+	sortFleetStatusResourcesByStatus(resources)
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, resources, meta)
+}
+
+func fleetStatusResourceStatus(r responsedto.FleetStatusResource) string {
+	if r.Attributes.Helicopter != nil {
+		return r.Attributes.Helicopter.Status
+	}
+	return ""
+}
+
+// sortFleetStatusResourcesByStatus stably orders the resources by status rank, keeping
+// the incoming (designation/sort) order within the same status.
+func sortFleetStatusResourcesByStatus(resources []responsedto.FleetStatusResource) {
+	sort.SliceStable(resources, func(i, j int) bool {
+		return helicopter.StatusRank(fleetStatusResourceStatus(resources[i])) < helicopter.StatusRank(fleetStatusResourceStatus(resources[j]))
+	})
+}
+
+// MarkFleetStatusServiced godoc
+// @Summary Mark fleet status serviced
+// @Description Move current maintenance schedules into service logs, then clear active schedules.
+// @Tags Fleet Status
+// @Produce json
+// @Param id path string true "Fleet status ID (UUIDv7)"
+// @Success 200 {object} responsedto.FleetStatusMarkServicedResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fleet-status/mark-serviced/{id} [post]
+func (h *FleetStatusHandler) MarkServiced(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("id"))
+	if err != nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusInvalidID, "", &jsonapi.ErrorSource{Pointer: "/path/id"})
+	}
+
+	if err := h.svc.MarkServiced(c.UserContext(), id, time.Now().UTC(), actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusNotFound, "", nil)
+		}
+		return writeFleetStatusServiceError(c, "FleetStatusHandler.MarkServiced", err)
+	}
+
+	return response.Write(c, fiber.StatusOK, map[string]any{
+		"data": map[string]any{
+			"type": "fleet_status_mark_serviced",
+			"attributes": map[string]any{
+				"serviced": true,
+			},
+		},
+	})
+}
+
+// ListFleetStatusServiceHistory godoc
+// @Summary List fleet history (timeline) by helicopter
+// @Description Unified timeline: maintenance servicing events merged with complaint/MEL/NSR/action/MCF/EASA/AOG action events, newest first.
+// @Tags Fleet Status
+// @Produce json
+// @Param helicopter_id path string true "Helicopter ID (UUIDv7)"
+// @Param page query int false "Page number" default(1)
+// @Param page_size query int false "Page size" default(20)
+// @Success 200 {object} responsedto.FleetHistoryListResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fleet-status/history/{helicopter_id} [get]
+func (h *FleetStatusHandler) ListHistoryByHelicopter(c *fiber.Ctx) error {
+	helicopterID, err := uuidv7.ParseString(c.Params("helicopter_id"))
+	if err != nil {
+		return writeFleetStatusAppError(c, apperrorsx.ErrFleetStatusInvalidID, "helicopter_id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/path/helicopter_id"})
+	}
+
+	page, _ := strconv.Atoi(c.Query("page", "1"))
+	if page < 1 {
+		page = 1
+	}
+	size, _ := strconv.Atoi(c.Query("page_size", "20"))
+	if size < 1 {
+		size = 20
+	}
+	offset := (page - 1) * size
+
+	type timedEntry struct {
+		at    time.Time
+		entry responsedto.FleetHistoryEntry
+	}
+	items := make([]timedEntry, 0)
+
+	logs, _, err := h.svc.ListServiceHistoryByHelicopterID(c.UserContext(), helicopterID, 1000, 0)
+	if err != nil {
+		return writeFleetStatusServiceError(c, "FleetStatusHandler.ListHistoryByHelicopter", err)
+	}
+	for i := range logs {
+		l := &logs[i]
+		items = append(items, timedEntry{at: l.ServicedAt.UTC(), entry: responsedto.FleetHistoryEntry{
+			At:         l.ServicedAt.UTC().Format(time.RFC3339),
+			EntityType: "fleet_status",
+			EntityID:   idString(l.FleetStatusID),
+			Action:     "serviced",
+			Message:    "Serviced " + strings.TrimSpace(l.InspectionType+" "+l.Type),
+			Actor:      idString(l.CreatedBy),
+			ActorName:  userctx.GetDisplayName(c.UserContext(), l.CreatedBy),
+		}})
+	}
+
+	events, _, herr := h.historySvc.ListByHelicopter(c.UserContext(), helicopterID, 0, 0)
+	if herr == nil {
+		for i := range events {
+			e := &events[i]
+			items = append(items, timedEntry{at: e.CreatedAt.UTC(), entry: responsedto.FleetHistoryEntry{
+				At:         e.CreatedAt.UTC().Format(time.RFC3339),
+				EntityType: e.EntityType,
+				EntityID:   idString(e.EntityID),
+				Action:     e.Action,
+				Message:    e.Message,
+				Actor:      idString(e.Actor),
+				ActorName:  userctx.GetDisplayName(c.UserContext(), e.Actor),
+			}})
+		}
+	}
+
+	sort.SliceStable(items, func(i, j int) bool { return items[i].at.After(items[j].at) })
+
+	total := int64(len(items))
+	start := offset
+	if start > len(items) {
+		start = len(items)
+	}
+	end := start + size
+	if end > len(items) {
+		end = len(items)
+	}
+	data := make([]responsedto.FleetHistoryEntry, 0, end-start)
+	for _, it := range items[start:end] {
+		data = append(data, it.entry)
+	}
+	res := responsedto.FleetHistoryListResponse{Data: data}
+	res.Meta.PageNumber = page
+	res.Meta.PageSize = size
+	res.Meta.Total = total
+	return response.Write(c, fiber.StatusOK, res)
+}
+
+// singleHelicopterResources fetches one helicopter by ID, builds its fleet
+// status resource, and applies an optional status filter (AND logic). Returns
+// an empty slice when the helicopter is not found or the status does not match.
+func (h *FleetStatusHandler) singleHelicopterResources(ctx context.Context, helicopterID []byte, statuses []string) ([]responsedto.FleetStatusResource, error) {
+	heli, err := h.helicopterSvc.GetByID(ctx, helicopterID)
+	if err != nil {
+		return nil, err
+	}
+	if heli == nil {
+		return []responsedto.FleetStatusResource{}, nil
+	}
+	resources, err := h.fleetStatusResourcesForHelicopters(ctx, []helicopter.Helicopter{*heli})
+	if err != nil {
+		return nil, err
+	}
+	if len(statuses) > 0 && len(resources) > 0 {
+		heliStatus := ""
+		if resources[0].Attributes.Helicopter != nil {
+			heliStatus = resources[0].Attributes.Helicopter.Status
+		}
+		for _, s := range statuses {
+			if s == heliStatus {
+				return resources, nil
+			}
+		}
+		return []responsedto.FleetStatusResource{}, nil
+	}
+	return resources, nil
+}
+
+func writeFleetStatusAppError(c *fiber.Ctx, def apperrorsx.Def, detail string, source *jsonapi.ErrorSource) error {
+	appErr := apperrorsx.New(def)
+	if strings.TrimSpace(detail) != "" {
+		appErr.Message = detail
+	}
+	if source != nil {
+		appErr.Source = source
+	}
+	return apperrorsx.Write(c, appErr)
+}
+
+func writeFleetStatusValidationErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	statusStr := strconv.Itoa(status)
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		if strings.TrimSpace(e.Code) == "" || strings.TrimSpace(e.ErrorCode) == "" {
+			code, errorCode := inferFleetStatusErrorCode(status, e.Title, e.Detail)
+			if strings.TrimSpace(e.Code) == "" {
+				e.Code = code
+			}
+			if strings.TrimSpace(e.ErrorCode) == "" {
+				e.ErrorCode = errorCode
+			}
+		}
+		enriched = append(enriched, e)
+	}
+	return jsonapi.WriteErrors(c, status, enriched)
+}
+
+func writeFleetStatusServiceError(c *fiber.Ctx, operation string, err error) error {
+	mapped := apperrorsx.Translate(apperrorsx.ModuleFleetStatus, err)
+	if mapped != nil && mapped.Code != apperrorsx.CodeInternalServerError {
+		logFleetStatusServiceError(c, operation, mapped.Status, mapped.Code, mapped.ErrorCode, err)
+		return apperrorsx.Write(c, mapped)
+	}
+
+	logFleetStatusServiceError(c, operation, fiber.StatusInternalServerError, apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode, err)
+	appErr := apperrorsx.New(apperrorsx.ErrInternal)
+	appErr.Message = "an internal error occurred"
+	return apperrorsx.Write(c, appErr)
+}
+
+func logFleetStatusServiceError(c *fiber.Ctx, operation string, status int, code, errorCode string, err error) {
+	requestID := requestIDFromCtx(c)
+	args := []any{
+		slog.String("request_id", requestID),
+		slog.String("operation", strings.TrimSpace(operation)),
+		slog.Int("status", status),
+		slog.String("code", strings.TrimSpace(code)),
+		slog.String("error_code", strings.TrimSpace(errorCode)),
+		slog.String("path", c.Path()),
+		slog.Any("cause", err),
+	}
+	if status >= fiber.StatusInternalServerError {
+		slog.ErrorContext(c.UserContext(), "fleet status service error", args...)
+		return
+	}
+	slog.WarnContext(c.UserContext(), "fleet status service error", args...)
+}
+
+func inferFleetStatusErrorCode(status int, _ string, _ string) (string, string) {
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.CodeFleetStatusNotFound, apperrorsx.ErrFleetStatusNotFound.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		return apperrorsx.CodeFleetStatusInvalidPayload, apperrorsx.ErrFleetStatusInvalidPayload.ErrorCode
+	case fiber.StatusBadRequest:
+		return apperrorsx.CodeFleetStatusInvalidJSON, apperrorsx.ErrFleetStatusInvalidJSON.ErrorCode
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
diff --git a/internal/transport/http/handlers/fleet_status_handler_test.go b/internal/transport/http/handlers/fleet_status_handler_test.go
new file mode 100644
index 0000000..0f5ddbb
--- /dev/null
+++ b/internal/transport/http/handlers/fleet_status_handler_test.go
@@ -0,0 +1,322 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	complaint "wucher/internal/domain/complaint"
+	easarelease "wucher/internal/domain/easa_release"
+	fleethistory "wucher/internal/domain/fleet_history"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+	"wucher/internal/domain/mcf"
+	"wucher/internal/shared/pkg/uuidv7"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+)
+
+func TestBuildFleetMCF(t *testing.T) {
+	f64 := func(v float64) *float64 { return &v }
+	summary := shareddto.FleetStatusSummary{
+		Airframe: shareddto.FleetStatusSummaryAirframe{Hours: f64(1245.3)},
+		Landings: f64(320),
+	}
+
+	t.Run("placeholder when no MCF is empty (no signed values)", func(t *testing.T) {
+		got := buildFleetMCF(context.Background(), nil, summary)
+		if got.ID != "" || got.Sign {
+			t.Fatalf("placeholder must have empty id + unsigned, got %#v", got)
+		}
+		if got.AFHours != nil || got.LandingCount != nil {
+			t.Fatalf("unsigned MCF must omit af_hours/landing_count, got %#v", got)
+		}
+	})
+
+	t.Run("completed MCF stays with its snapshot + signer", func(t *testing.T) {
+		completedAt := time.Now().UTC()
+		row := &mcf.MaintenanceCheckFlight{ID: uuidv7.MustBytes(), AFHours: "1300", LandingCount: 5, CompletedAt: &completedAt, CompletedBy: uuidv7.MustBytes()}
+		got := buildFleetMCF(context.Background(), row, summary)
+		if got.ID == "" || !got.Sign {
+			t.Fatalf("completed MCF must stay visible with id + sign=true, got %#v", got)
+		}
+		if got.AFHours == nil || *got.AFHours != "1300" || got.LandingCount == nil || *got.LandingCount != 5 {
+			t.Fatalf("completed MCF should show its own snapshot, got %#v", got)
+		}
+		if got.SignedBy == "" {
+			t.Fatalf("completed MCF should expose signed_by, got %#v", got)
+		}
+	})
+
+	t.Run("draft MCF is unsigned and omits af_hours/landing", func(t *testing.T) {
+		got := buildFleetMCF(context.Background(), &mcf.MaintenanceCheckFlight{ID: uuidv7.MustBytes(), AFHours: "9999", LandingCount: 7}, summary)
+		if got.Sign {
+			t.Fatal("draft (not completed) MCF must be unsigned")
+		}
+		if got.SignedBy != "" {
+			t.Fatal("draft MCF must not have a signer")
+		}
+		// Unsigned → af_hours/landing are the signed values, so they are omitted here.
+		if got.AFHours != nil || got.LandingCount != nil {
+			t.Fatalf("unsigned draft must omit af_hours/landing_count, got %#v", got)
+		}
+	})
+
+	t.Run("cancelled MCF stays visible as a cancelled record", func(t *testing.T) {
+		cancelledAt := time.Now().UTC()
+		d := time.Date(2026, 7, 7, 0, 0, 0, 0, time.UTC)
+		row := &mcf.MaintenanceCheckFlight{ID: uuidv7.MustBytes(), Date: &d, AFHours: "1300", LandingCount: 5, CancelledAt: &cancelledAt}
+		got := buildFleetMCF(context.Background(), row, summary)
+		if got.ID == "" {
+			t.Fatal("cancelled MCF must surface its id (visible in fleet, not a blank placeholder)")
+		}
+		if got.Active || got.Sign {
+			t.Fatalf("cancelled MCF must be active=false and sign=false, got %#v", got)
+		}
+		if got.Date == nil || *got.Date != "2026-07-07" {
+			t.Fatalf("cancelled MCF should surface its date, got %#v", got.Date)
+		}
+		// Unsigned (cancelled) → af_hours/landing omitted.
+		if got.AFHours != nil || got.LandingCount != nil {
+			t.Fatalf("cancelled MCF must omit af_hours/landing_count, got %#v", got)
+		}
+	})
+
+	t.Run("active flag reflects MCF status", func(t *testing.T) {
+		now := time.Now().UTC()
+		passed, failed := mcf.ResultPassed, mcf.ResultFailed
+		cases := []struct {
+			name string
+			row  *mcf.MaintenanceCheckFlight
+			want bool
+		}{
+			{"no MCF", nil, false},
+			{"draft", &mcf.MaintenanceCheckFlight{ID: uuidv7.MustBytes()}, true},
+			{"signed passed (done)", &mcf.MaintenanceCheckFlight{ID: uuidv7.MustBytes(), CompletedAt: &now, Result: &passed}, false},
+			{"signed failed (done — once signed, done)", &mcf.MaintenanceCheckFlight{ID: uuidv7.MustBytes(), CompletedAt: &now, Result: &failed}, false},
+			{"cancelled", &mcf.MaintenanceCheckFlight{ID: uuidv7.MustBytes(), CancelledAt: &now}, false},
+		}
+		for _, tc := range cases {
+			if got := buildFleetMCF(context.Background(), tc.row, summary); got.Active != tc.want {
+				t.Fatalf("%s: active = %v, want %v", tc.name, got.Active, tc.want)
+			}
+		}
+	})
+}
+
+func TestSortFleetStatusResourcesByStatus(t *testing.T) {
+	mk := func(status string) responsedto.FleetStatusResource {
+		return responsedto.FleetStatusResource{
+			Attributes: responsedto.FleetStatusAttributes{
+				Helicopter: &shareddto.FleetStatusHelicopter{Status: status},
+			},
+		}
+	}
+	// Scrambled input including an unknown status (sorts last).
+	resources := []responsedto.FleetStatusResource{
+		mk("aog"), mk("mcf"), mk(""), mk("available"), mk("booked"),
+	}
+	sortFleetStatusResourcesByStatus(resources)
+	want := []string{"mcf", "aog", "booked", "available", ""}
+	for i, w := range want {
+		if got := resources[i].Attributes.Helicopter.Status; got != w {
+			t.Fatalf("index %d: want %q, got %q", i, w, got)
+		}
+	}
+}
+
+type fsStubComplaints struct{}
+
+func (fsStubComplaints) ListByHelicopter(context.Context, []byte, int, int) ([]complaint.Complaint, int64, error) {
+	return nil, 0, nil
+}
+func (fsStubComplaints) ResolveUserNames(context.Context, []complaint.Complaint) (map[string]string, error) {
+	return nil, nil
+}
+func (fsStubComplaints) ActiveGroundingByHelicopterIDs(context.Context, [][]byte) ([]complaint.Complaint, error) {
+	return nil, nil
+}
+func (fsStubComplaints) OpenByHelicopterIDs(context.Context, [][]byte) ([]complaint.Complaint, error) {
+	return nil, nil
+}
+
+type fsStubEASA struct{}
+
+func (fsStubEASA) GetLatestByHelicopter(context.Context, []byte) (*easarelease.EASARelease, error) {
+	return nil, nil
+}
+
+type fsStubHistory struct{}
+
+func (fsStubHistory) ListByHelicopter(context.Context, []byte, int, int) ([]fleethistory.FleetHistory, int64, error) {
+	return nil, 0, nil
+}
+
+func fleetStatusTestDeps() FleetStatusDeps {
+	return FleetStatusDeps{
+		Helicopter: &helicopterServiceMock{},
+		Complaint:  fsStubComplaints{},
+		EASA:       fsStubEASA{},
+		History:    fsStubHistory{},
+		MCF:        &stubMCFSvc{},
+		Storage:    &helicopterPresignStorageMock{},
+	}
+}
+
+type fleetStatusServiceMock struct {
+	createErr       error
+	updateErr       error
+	markServicedErr error
+	getByID         *fleetstatus.FleetStatus
+}
+
+func (m *fleetStatusServiceMock) Create(context.Context, *fleetstatus.FleetStatus) error {
+	return m.createErr
+}
+
+func (m *fleetStatusServiceMock) Update(context.Context, *fleetstatus.FleetStatus) error {
+	return m.updateErr
+}
+
+func (m *fleetStatusServiceMock) Delete(context.Context, []byte, []byte) error {
+	return nil
+}
+
+func (m *fleetStatusServiceMock) GetByID(context.Context, []byte) (*fleetstatus.FleetStatus, error) {
+	if m.getByID != nil {
+		row := *m.getByID
+		return &row, nil
+	}
+	return nil, nil
+}
+
+func (m *fleetStatusServiceMock) List(context.Context, string, string, int, int) ([]fleetstatus.FleetStatus, int64, error) {
+	return nil, 0, nil
+}
+
+func (m *fleetStatusServiceMock) LatestByHelicopterIDs(context.Context, [][]byte) (map[string]*fleetstatus.FleetStatus, error) {
+	return nil, nil
+}
+
+func (m *fleetStatusServiceMock) MarkServiced(context.Context, []byte, time.Time, []byte) error {
+	return m.markServicedErr
+}
+
+func (m *fleetStatusServiceMock) ListServiceHistoryByHelicopterID(context.Context, []byte, int, int) ([]fleetstatus.FleetStatusServiceLog, int64, error) {
+	return nil, 0, nil
+}
+
+func (m *fleetStatusServiceMock) GetSummaryByHelicopterID(context.Context, []byte) (*shareddto.FleetStatusSummary, error) {
+	return nil, nil
+}
+
+func (m *fleetStatusServiceMock) ReviseSummary(context.Context, []byte, helicopterusage.ManualSummaryInput, []byte) error {
+	return nil
+}
+
+func (m *fleetStatusServiceMock) IsInUse(context.Context, []byte) (bool, error) {
+	return false, nil
+}
+
+func (m *fleetStatusServiceMock) OverdueInspections(context.Context, []byte) ([]fleetstatus.OverdueInspection, error) {
+	return nil, nil
+}
+
+func TestFleetStatusHandler_CreateAndUpdateHideRawErrors(t *testing.T) {
+	t.Run("create", func(t *testing.T) {
+		svc := &fleetStatusServiceMock{createErr: errors.New("insert into fleet_status (helicopter_id) values (...)")}
+		h := NewFleetStatusHandler(svc, fleetStatusTestDeps())
+		app := fiber.New()
+		app.Post("/api/v1/fleet-status/create", h.Create)
+
+		heliID := uuidv7.MustBytes()
+		heliStr, _ := uuidv7.BytesToString(heliID)
+		payload := []byte(`{"data":{"type":"fleet_status_create","attributes":{"helicopter_id":"` + heliStr + `"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/fleet-status/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if resp.StatusCode != http.StatusInternalServerError {
+			t.Fatalf("expected 500, got %d", resp.StatusCode)
+		}
+		if strings.Contains(string(body), "insert into fleet_status") {
+			t.Fatalf("expected raw error to be hidden, got %s", string(body))
+		}
+		if !strings.Contains(string(body), "an internal error occurred") {
+			t.Fatalf("expected generic internal message, got %s", string(body))
+		}
+	})
+
+	t.Run("update", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		heliID := uuidv7.MustBytes()
+		svc := &fleetStatusServiceMock{
+			updateErr: errors.New("update fleet_status set helicopter_id = ..."),
+			getByID: &fleetstatus.FleetStatus{
+				ID:           id,
+				HelicopterID: heliID,
+			},
+		}
+		h := NewFleetStatusHandler(svc, fleetStatusTestDeps())
+		app := fiber.New()
+		app.Patch("/api/v1/fleet-status/update/:id", h.Update)
+
+		idStr, _ := uuidv7.BytesToString(id)
+		heliStr, _ := uuidv7.BytesToString(heliID)
+		payload := []byte(`{"data":{"type":"fleet_status_update","id":"` + idStr + `","attributes":{"helicopter_id":"` + heliStr + `"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/fleet-status/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if resp.StatusCode != http.StatusInternalServerError {
+			t.Fatalf("expected 500, got %d", resp.StatusCode)
+		}
+		if strings.Contains(string(body), "update fleet_status set") {
+			t.Fatalf("expected raw error to be hidden, got %s", string(body))
+		}
+		if !strings.Contains(string(body), "an internal error occurred") {
+			t.Fatalf("expected generic internal message, got %s", string(body))
+		}
+	})
+}
+
+func TestFleetStatusHandler_MarkServicedReturns404ForRecordNotFound(t *testing.T) {
+	svc := &fleetStatusServiceMock{
+		markServicedErr: errors.Join(errors.New("wrapped service error"), gorm.ErrRecordNotFound),
+	}
+	h := NewFleetStatusHandler(svc, fleetStatusTestDeps())
+	app := fiber.New()
+	app.Post("/api/v1/fleet-status/mark-serviced/:id", h.MarkServiced)
+
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/fleet-status/mark-serviced/"+idStr, nil)
+
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", resp.StatusCode)
+	}
+	if !strings.Contains(string(body), `"detail":"not found"`) {
+		t.Fatalf("expected generic not found detail, got %s", string(body))
+	}
+}
diff --git a/internal/transport/http/handlers/fleet_status_update_http_test.go b/internal/transport/http/handlers/fleet_status_update_http_test.go
new file mode 100644
index 0000000..ca0b431
--- /dev/null
+++ b/internal/transport/http/handlers/fleet_status_update_http_test.go
@@ -0,0 +1,113 @@
+package handlers
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	"wucher/internal/domain/helicopter"
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+	"wucher/internal/repository/mysql"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+// TestFleetStatusUpdateHTTPReflectsSummary drives the REAL PATCH handler over sqlite and
+// asserts the response reflects the patched summary — the exact flow the user reports.
+func TestFleetStatusUpdateHTTPReflectsSummary(t *testing.T) {
+	dsn := fmt.Sprintf("file:fs_http_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{NowFunc: func() time.Time { return time.Now().UTC() }})
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	if err := db.AutoMigrate(
+		&filemanager.Folder{}, &filemanager.File{}, &filemanager.Attachment{},
+		&helicopter.Helicopter{},
+		&fleetstatus.FleetStatus{}, &fleetstatus.MaintenanceSchedule{}, &fleetstatus.FleetStatusFile{},
+		&helicopterusage.HelicopterUsage{},
+	); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+
+	heliRepo := mysql.NewHelicopterRepository(db)
+	heli := &helicopter.Helicopter{Designation: "H1", Identifier: "PK-H1", Type: "Twin", NR1: true, NR2: true, IsActive: true}
+	if err := heliRepo.Create(nil, heli); err != nil {
+		t.Fatalf("create heli: %v", err)
+	}
+	fsRepo := mysql.NewFleetStatusRepository(db)
+	fs := &fleetstatus.FleetStatus{HelicopterID: heli.ID, Status: fleetstatus.StatusActive}
+	if err := fsRepo.Create(nil, fs); err != nil {
+		t.Fatalf("create fs: %v", err)
+	}
+
+	usageSvc := service.NewHelicopterUsageService(mysql.NewHelicopterUsageRepository(db))
+	fleetSvc := service.NewFleetStatusService(fsRepo, nil, service.NewHelicopterService(heliRepo), nil).WithUsage(usageSvc)
+
+	h := NewFleetStatusHandler(fleetSvc, fleetStatusTestDeps())
+	app := fiber.New()
+	app.Patch("/fleet-status/update/:id", h.Update)
+
+	idStr, _ := uuidv7.BytesToString(fs.ID)
+	body := fmt.Sprintf(`{"data":{"type":"fleet_status_update","id":"%s","attributes":{"summary":{"airframe":{"hours":1234,"cycles":-1},"engine_1":{"hours":1234,"gpc_ng_n1":23.23,"ptc_nf_n2":23.59,"ccc":-8},"engine_2":{"hours":234,"gpc_ng_n1":123,"ptc_nf_n2":1230,"ccc":123},"flight_reports":1,"hook_releases":1,"landings":1,"rotor_brake_cycles":1},"maintenance_schedules":[{"inspection_type":"A/F","type":"","due":"","ext":""}]}}}`, idStr)
+
+	req, _ := http.NewRequest(http.MethodPatch, "/fleet-status/update/"+idStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req, -1)
+	if err != nil {
+		t.Fatalf("request: %v", err)
+	}
+	raw, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("PATCH status = %d, body = %s", resp.StatusCode, string(raw))
+	}
+
+	var out struct {
+		Data struct {
+			Attributes struct {
+				Summary struct {
+					Airframe struct {
+						Hours  *float64 `json:"hours"`
+						Cycles *float64 `json:"cycles"`
+					} `json:"airframe"`
+					Engine1 struct {
+						Hours *float64 `json:"hours"`
+					} `json:"engine_1"`
+				} `json:"summary"`
+			} `json:"attributes"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(raw, &out); err != nil {
+		t.Fatalf("unmarshal: %v (%s)", err, string(raw))
+	}
+	af := out.Data.Attributes.Summary.Airframe
+	if af.Hours == nil || *af.Hours != 1234 {
+		t.Fatalf("PATCH response airframe hours = %v, want 1234\nbody=%s", af.Hours, string(raw))
+	}
+	if af.Cycles == nil || *af.Cycles != -1 {
+		t.Fatalf("PATCH response airframe cycles = %v, want -1", af.Cycles)
+	}
+	t.Logf("PATCH response reflects summary: hours=%v cycles=%v", *af.Hours, *af.Cycles)
+
+	// Second PATCH with a new value.
+	body2 := strings.Replace(body, `"hours":1234,"cycles":-1`, `"hours":5555,"cycles":7`, 1)
+	req2, _ := http.NewRequest(http.MethodPatch, "/fleet-status/update/"+idStr, strings.NewReader(body2))
+	req2.Header.Set("Content-Type", "application/json")
+	resp2, _ := app.Test(req2, -1)
+	raw2, _ := io.ReadAll(resp2.Body)
+	var out2 = out
+	_ = json.Unmarshal(raw2, &out2)
+	if out2.Data.Attributes.Summary.Airframe.Hours == nil || *out2.Data.Attributes.Summary.Airframe.Hours != 5555 {
+		t.Fatalf("second PATCH hours = %v, want 5555 (VALUE DID NOT CHANGE)\nbody=%s", out2.Data.Attributes.Summary.Airframe.Hours, string(raw2))
+	}
+	t.Logf("second PATCH reflects new value: hours=%v", *out2.Data.Attributes.Summary.Airframe.Hours)
+}
diff --git a/internal/transport/http/handlers/flight_data_handler.go b/internal/transport/http/handlers/flight_data_handler.go
new file mode 100644
index 0000000..ea4f74c
--- /dev/null
+++ b/internal/transport/http/handlers/flight_data_handler.go
@@ -0,0 +1,1585 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	facilitydomain "wucher/internal/domain/facility"
+	flightdata "wucher/internal/domain/flight_data"
+	hospitaldomain "wucher/internal/domain/hospital"
+	icaodomain "wucher/internal/domain/icao"
+	missiondomain "wucher/internal/domain/mission"
+	userdomain "wucher/internal/domain/user"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type FlightDataHandler struct {
+	svc      flightdata.Service
+	mission  missionService
+	hospital hospitalService
+	icao     icaoService
+	user     userService
+	facility facilityService
+	validate *validators.Validator
+}
+
+func NewFlightDataHandler(svc flightdata.Service) *FlightDataHandler {
+	return &FlightDataHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+type hospitalService interface {
+	GetByID(context.Context, []byte) (*hospitaldomain.Hospital, error)
+}
+
+type missionService interface {
+	GetByID(context.Context, []byte) (*missiondomain.Mission, error)
+}
+
+type icaoService interface {
+	GetByID(context.Context, []byte) (*icaodomain.ICAO, error)
+}
+
+type userService interface {
+	GetByID(context.Context, []byte) (*userdomain.User, error)
+}
+
+type facilityService interface {
+	GetByID(context.Context, []byte) (*facilitydomain.Facility, error)
+}
+
+func (h *FlightDataHandler) WithHospitalService(svc hospitalService) *FlightDataHandler {
+	if h != nil {
+		h.hospital = svc
+	}
+	return h
+}
+
+func (h *FlightDataHandler) WithMissionService(svc missionService) *FlightDataHandler {
+	if h != nil {
+		h.mission = svc
+	}
+	return h
+}
+
+func (h *FlightDataHandler) WithICAOService(svc icaoService) *FlightDataHandler {
+	if h != nil {
+		h.icao = svc
+	}
+	return h
+}
+
+func (h *FlightDataHandler) WithUserService(svc userService) *FlightDataHandler {
+	if h != nil {
+		h.user = svc
+	}
+	return h
+}
+
+func (h *FlightDataHandler) WithFacilityService(svc facilityService) *FlightDataHandler {
+	if h != nil {
+		h.facility = svc
+	}
+	return h
+}
+
+func (h *FlightDataHandler) validateFlightDataReferences(ctx context.Context, missionID, coPilotID, fromICAOID, fromHospitalID, toICAOID, toHospitalID []byte) error {
+	if len(missionID) == 16 && h != nil && h.mission != nil {
+		row, err := h.mission.GetByID(ctx, missionID)
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return flightdata.ErrMissionReference
+			}
+			return err
+		}
+		if row == nil {
+			return flightdata.ErrMissionReference
+		}
+	}
+	if len(coPilotID) == 16 && h != nil && h.user != nil {
+		row, err := h.user.GetByID(ctx, coPilotID)
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return flightdata.ErrCoPilotReference
+			}
+			return err
+		}
+		if row == nil {
+			return flightdata.ErrCoPilotReference
+		}
+	}
+	if len(fromICAOID) == 16 && h != nil && h.icao != nil {
+		row, err := h.icao.GetByID(ctx, fromICAOID)
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return flightdata.ErrOriginLocationReference
+			}
+			return err
+		}
+		if row == nil {
+			return flightdata.ErrOriginLocationReference
+		}
+	}
+	if len(toICAOID) == 16 && h != nil && h.icao != nil {
+		row, err := h.icao.GetByID(ctx, toICAOID)
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return flightdata.ErrDestinationLocationReference
+			}
+			return err
+		}
+		if row == nil {
+			return flightdata.ErrDestinationLocationReference
+		}
+	}
+	if len(fromHospitalID) == 16 && h != nil && h.hospital != nil {
+		row, err := h.hospital.GetByID(ctx, fromHospitalID)
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return flightdata.ErrOriginLocationReference
+			}
+			return err
+		}
+		if row == nil {
+			return flightdata.ErrOriginLocationReference
+		}
+	}
+	if len(toHospitalID) == 16 && h != nil && h.hospital != nil {
+		row, err := h.hospital.GetByID(ctx, toHospitalID)
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return flightdata.ErrDestinationLocationReference
+			}
+			return err
+		}
+		if row == nil {
+			return flightdata.ErrDestinationLocationReference
+		}
+	}
+	return nil
+}
+
+func (h *FlightDataHandler) validateSPOFacilityReferences(ctx context.Context, attrs requestdto.FlightDataCreateAttributes) *jsonapi.ErrorObject {
+	if h == nil || h.facility == nil {
+		return nil
+	}
+
+	check := func(pointer, raw, expectedCategory string) *jsonapi.ErrorObject {
+		id, err := uuidv7.ParseString(strings.TrimSpace(raw))
+		if err != nil || len(id) != 16 {
+			return nil
+		}
+		row, err := h.facility.GetByID(ctx, id)
+		if err != nil || row == nil || !strings.EqualFold(strings.TrimSpace(row.Category), expectedCategory) {
+			return &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: flightdata.ErrorMessageFacilityReference,
+				Source: &jsonapi.ErrorSource{Pointer: pointer},
+			}
+		}
+		return nil
+	}
+
+	if attrs.HESLO != nil {
+		for i, f := range attrs.HESLO.Flights {
+			if errObj := check("/data/attributes/heslo/flights/"+strconv.Itoa(i)+"/heslo_rope_label_id", f.HESLORopeLabelID, sharedconst.FlightDataFacilityCategoryHesloRopeLabel); errObj != nil {
+				return errObj
+			}
+			for j, s := range f.Slings {
+				if errObj := check("/data/attributes/heslo/flights/"+strconv.Itoa(i)+"/slings/"+strconv.Itoa(j)+"/sling_id", s.SlingID, sharedconst.FlightDataFacilityCategoryHesloRopeLength); errObj != nil {
+					return errObj
+				}
+			}
+		}
+	}
+
+	if attrs.Logging != nil {
+		for i, s := range attrs.Logging.Slings {
+			if errObj := check("/data/attributes/logging/slings/"+strconv.Itoa(i)+"/sling_id", s.SlingID, sharedconst.FlightDataFacilityCategoryHesloHook); errObj != nil {
+				return errObj
+			}
+		}
+	}
+
+	if attrs.HEC != nil {
+		for i, f := range attrs.HEC.Flights {
+			if errObj := check("/data/attributes/hec/flights/"+strconv.Itoa(i)+"/equipment_id", f.EquipmentID, sharedconst.FlightDataFacilityCategoryHecRopeLabel); errObj != nil {
+				return errObj
+			}
+		}
+		for i, s := range attrs.HEC.Slings {
+			if errObj := check("/data/attributes/hec/slings/"+strconv.Itoa(i)+"/sling_id", s.SlingID, sharedconst.FlightDataFacilityCategoryHecRopeLength); errObj != nil {
+				return errObj
+			}
+		}
+	}
+
+	return nil
+}
+
+// ListFlightData godoc
+// @Summary List flight data
+// @Description List flight data rows. Supports `date` for exact flight take-off date filtering (`YYYY-MM-DD`), plus `mission_id` and `flight_data_id` filters.
+// @Description SPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.
+// @Tags Mission - Flight Data
+// @Produce json
+// @Param date query string false "Filter by flight take-off date (YYYY-MM-DD)"
+// @Param mission_id query string false "Filter by mission UUID"
+// @Param flight_data_id query string false "Filter by flight-data UUID"
+// @Param page[number] query int false "Page number"
+// @Param page[size] query int false "Page size"
+// @Param page query int false "Page number (fallback)"
+// @Param size query int false "Page size (fallback)"
+// @Param limit query int false "Page size override"
+// @Success 200 {object} responsedto.FlightDataListResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/flight-data/get-all [get]
+func (h *FlightDataHandler) List(c *fiber.Ctx) error {
+	dateFilter := strings.TrimSpace(c.Query("date"))
+	if dateFilter != "" {
+		if _, err := time.Parse("2006-01-02", dateFilter); err != nil {
+			return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "date must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: "/date"},
+			}})
+		}
+	}
+	missionQuery := c.Query("mission_id")
+	missionID, errObj := parseOptionalUUIDFlightData(&missionQuery, "/query/mission_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	flightDataQuery := c.Query("flight_data_id")
+	flightDataID, errObj := parseOptionalUUIDFlightData(&flightDataQuery, "/query/flight_data_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	rows, total, err := h.svc.List(c.UserContext(), dateFilter, missionID, flightDataID, 0, 0)
+	if err != nil {
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]responsedto.FlightDataResource, 0, len(rows))
+	for i := range rows {
+		resource, buildErr := h.buildFlightDataResource(c, &rows[i])
+		if buildErr != nil {
+			return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "List failed",
+				Detail: buildErr.Error(),
+			}})
+		}
+		data = append(data, resource)
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{
+		"total": total,
+	})
+}
+
+// ListFlightDataDatatable godoc
+// @Summary List flight data (datatable)
+// @Description Datatable-friendly list of flight data rows. Supports `date` for exact flight take-off date filtering (`YYYY-MM-DD`), plus `mission_id` and `flight_data_id` filters.
+// @Description Same payload shape as `get-all`, but with DataTables paging params (`start`, `length`, `draw`).
+// @Description SPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.
+// @Tags Mission - Flight Data
+// @Produce json
+// @Param draw query int false "DataTables draw counter"
+// @Param start query int false "Paging start offset"
+// @Param length query int false "Paging length"
+// @Param page[number] query int false "Page number"
+// @Param page[size] query int false "Page size"
+// @Param page query int false "Page number (fallback)"
+// @Param size query int false "Page size (fallback)"
+// @Param limit query int false "Page size override"
+// @Param date query string false "Filter by flight take-off date (YYYY-MM-DD)"
+// @Param mission_id query string false "Filter by mission UUID"
+// @Param flight_data_id query string false "Filter by flight-data UUID"
+// @Success 200 {object} responsedto.FlightDataListResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/flight-data/get-all/dt [get]
+func (h *FlightDataHandler) ListDatatable(c *fiber.Ctx) error {
+	dateFilter := strings.TrimSpace(c.Query("date"))
+	if dateFilter != "" {
+		if _, err := time.Parse("2006-01-02", dateFilter); err != nil {
+			return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "date must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: "/date"},
+			}})
+		}
+	}
+	missionQuery := c.Query("mission_id")
+	missionID, errObj := parseOptionalUUIDFlightData(&missionQuery, "/query/mission_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	flightDataQuery := c.Query("flight_data_id")
+	flightDataID, errObj := parseOptionalUUIDFlightData(&flightDataQuery, "/query/flight_data_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	if start := parseIntDefault(c.Query("start"), -1); start >= 0 && c.Query("length") != "" {
+		pageSize = parseIntDefault(c.Query("length"), pageSize)
+		if pageSize < 1 {
+			pageSize = 20
+		}
+		pageNumber = (start / pageSize) + 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	rows, total, err := h.svc.List(c.UserContext(), dateFilter, missionID, flightDataID, pageSize, offset)
+	if err != nil {
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]responsedto.FlightDataResource, 0, len(rows))
+	for i := range rows {
+		resource, buildErr := h.buildFlightDataResource(c, &rows[i])
+		if buildErr != nil {
+			return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "List failed",
+				Detail: buildErr.Error(),
+			}})
+		}
+		data = append(data, resource)
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	})
+}
+
+// CreateFlightData godoc
+// @Summary Create flight data
+// @Description Create a flight data row.
+// @Description Required field: `mission_id`. `co_pilot_id` is optional.
+// @Description Swagger request example shows the complete common payload for an `SPO` mission. `SPO` is the default example shape, and for other mission types (`CAT` and `NCO`) you do not need to send the `hec`, `heslo`, or `logging` blocks. `rotor_brake_cycle` is optional for `SPO`, `CAT`, and `NCO`.
+// @Description SPO facility references must point to facilities with categories: `heslo_rope_label_id -> heslo-rope-label`, `heslo.slings -> heslo-rope-length`, `logging.slings -> heslo-hook`, `hec.flights -> hec-rope-label`, and `hec.slings -> hec-rope-length`.
+// @Description SPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.
+// @Description Example request: {"data":{"type":"flight_data_create","attributes":{"mission_id":"019d6774-98e8-7fba-9ef4-3795c0da8a13"}}}
+// @Tags  Mission - Flight Data
+// @Accept json
+// @Produce json
+// @Param request body requestdto.FlightDataCreateRequest true "JSON:API flight data create request. Example is for SPO; CAT/NCO can omit SPO-only blocks and other optional fields." SchemaExample({"data":{"type":"flight_data_create","attributes":{"mission_id":"019d6774-98e8-7fba-9ef4-3795c0da8a13","flight_take_off":"2026-04-20T08:00:00Z","flight_landing":"2026-04-20T09:15:00Z","from_icao_id":"019d6774-98e8-7fba-9ef4-3795c0da8a13","to_icao_id":"019d6774-98e8-7fba-9ef4-3795c0da8a13","hook_releases":0,"ticket_no":"SPO-001","engine":"AIRBUS H145","delivery_note_number":"DN-2026-0001","customer_name":"Patient Transfer","other_information":"SPO mission sample","landing_count":1,"heslo":{"flights":[{"id":"string","rot":0,"heslo_rope_label_id":"string","heslo_rope_label_name":"string"}],"slings":[{"id":"string","heslo_flight_id":"string","sling_id":"string","sling_name":"string"}]},"logging":{"slings":[{"id":"string","sling_id":"string","sling_name":"string"}]},"hec":{"flights":[{"equipment_id":"string","equipment_name":"string","hec_cycle":0,"id":"string","rot":0}],"loads":[{"id":"string","load_category":"string","quantity":0}],"slings":[{"id":"string","sling_id":"string","sling_name":"string"}]}}}})
+// @Success 201 {object} responsedto.FlightDataResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/flight-data/create [post]
+func (h *FlightDataHandler) Create(c *fiber.Ctx) error {
+	var req requestdto.FlightDataCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	attrs := req.Data.Attributes
+
+	missionID, errObj := parseRequiredUUID(attrs.MissionID, "/data/attributes/mission_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	coPilotID, errObj := parseOptionalUUIDFlightData(attrs.CoPilotID, "/data/attributes/co_pilot_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	fromICAOID, errObj := parseOptionalUUIDFlightData(attrs.FromICAOID, "/data/attributes/from_icao_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	fromHospitalID, errObj := parseOptionalUUIDFlightData(attrs.FromHospitalID, "/data/attributes/from_hospital_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	toICAOID, errObj := parseOptionalUUIDFlightData(attrs.ToICAOID, "/data/attributes/to_icao_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	toHospitalID, errObj := parseOptionalUUIDFlightData(attrs.ToHospitalID, "/data/attributes/to_hospital_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	if err := h.validateFlightDataReferences(c.UserContext(), missionID, coPilotID, fromICAOID, fromHospitalID, toICAOID, toHospitalID); err != nil {
+		return writeFlightDataServiceError(c, err, missionID, coPilotID, fromICAOID, fromHospitalID, toICAOID, toHospitalID)
+	}
+
+	row := &flightdata.FlightData{
+		MissionID:          missionID,
+		CoPilotID:          coPilotID,
+		FromICAOID:         fromICAOID,
+		FromHospitalID:     fromHospitalID,
+		ToICAOID:           toICAOID,
+		ToHospitalID:       toHospitalID,
+		CreatedBy:          actorUserID(c),
+		UpdatedBy:          actorUserID(c),
+		TicketNo:           stringPtrOrEmpty(attrs.TicketNo),
+		Engine:             stringPtrOrEmpty(attrs.Engine),
+		DeliveryNoteNumber: stringPtrOrEmpty(attrs.DeliveryNoteNumber),
+		CustomerName:       stringPtrOrEmpty(attrs.CustomerName),
+		OtherInformation:   stringPtrOrEmpty(attrs.OtherInformation),
+	}
+	if attrs.FlightTakeOff != nil {
+		v, err := parseRFC3339(*attrs.FlightTakeOff, "/data/attributes/flight_take_off")
+		if err != nil {
+			return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*err})
+		}
+		row.FlightTakeOff = v
+	}
+	if attrs.FlightLanding != nil {
+		v, err := parseRFC3339(*attrs.FlightLanding, "/data/attributes/flight_landing")
+		if err != nil {
+			return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*err})
+		}
+		row.FlightLanding = v
+	}
+	if attrs.FlightDurationSecs != nil {
+		row.FlightDuration = time.Duration(*attrs.FlightDurationSecs) * time.Second
+	}
+	if attrs.FlightREDSecs != nil {
+		row.FlightRED = time.Duration(*attrs.FlightREDSecs) * time.Second
+	}
+	if attrs.MaxN1 != nil {
+		row.MaxN1 = *attrs.MaxN1
+	}
+	if attrs.MaxN2 != nil {
+		row.MaxN2 = *attrs.MaxN2
+	}
+	if attrs.PaxCount != nil {
+		row.PaxCount = *attrs.PaxCount
+	}
+	if attrs.LandingCount != nil {
+		row.LandingCount = *attrs.LandingCount
+	}
+	if attrs.RotorBrakeCycle != nil {
+		row.RotorBrakeCycle = *attrs.RotorBrakeCycle
+	}
+	if attrs.HookReleases != nil {
+		row.HookReleases = *attrs.HookReleases
+	}
+	if attrs.FlightPlanDistance != nil {
+		row.FlightPlanDistance = *attrs.FlightPlanDistance
+	}
+	if attrs.FlightPlanTimeSecs != nil {
+		row.FlightPlanTime = time.Duration(*attrs.FlightPlanTimeSecs) * time.Second
+	}
+	if attrs.FlightPlanTrueCourse != nil {
+		row.FlightPlanTrueCourse = *attrs.FlightPlanTrueCourse
+	}
+	if attrs.FuelBeforeFlight != nil {
+		row.FuelBeforeFlight = *attrs.FuelBeforeFlight
+	}
+	if attrs.FuelUpload != nil {
+		row.FuelUpload = *attrs.FuelUpload
+	}
+	if attrs.FuelAfterFlight != nil {
+		row.FuelAfterFlight = *attrs.FuelAfterFlight
+	}
+	if attrs.FuelPlanning != nil {
+		row.FuelPlanning = *attrs.FuelPlanning
+	}
+	if attrs.FlightPositioning != nil {
+		row.FlightPositioning = *attrs.FlightPositioning
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeFlightDataServiceError(c, err, row.MissionID, row.CoPilotID, row.FromICAOID, row.FromHospitalID, row.ToICAOID, row.ToHospitalID)
+	}
+
+	if spoData := parseSPOUpsertData(attrs); spoData != nil {
+		if errObj := h.validateSPOFacilityReferences(c.UserContext(), attrs); errObj != nil {
+			return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		if err := h.svc.UpsertSPODetails(c.UserContext(), row.ID, spoData); err != nil {
+			return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Create failed",
+				Detail: safeInternalDetail(),
+			}})
+		}
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		resource, buildErr := h.buildFlightDataResource(c, created)
+		if buildErr != nil {
+			return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Create failed",
+				Detail: buildErr.Error(),
+			}})
+		}
+		return response.Write(c, fiber.StatusCreated, resource)
+	}
+	if rowByMission, lookupErr := h.svc.GetByMissionID(c.UserContext(), row.MissionID); lookupErr == nil && rowByMission != nil {
+		resource, buildErr := h.buildFlightDataResource(c, rowByMission)
+		if buildErr != nil {
+			return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Create failed",
+				Detail: buildErr.Error(),
+			}})
+		}
+		return response.Write(c, fiber.StatusCreated, resource)
+	}
+	resource, buildErr := h.buildFlightDataResource(c, row)
+	if buildErr != nil {
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: buildErr.Error(),
+		}})
+	}
+	return response.Write(c, fiber.StatusCreated, resource)
+}
+
+// GetFlightData godoc
+// @Summary Get flight data by ID
+// @Description Get flight data detail by ID. Path `id` can be mission UUID, flight-data UUID, or flight UUID.
+// @Description SPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.
+// @Tags  Mission - Flight Data
+// @Produce json
+// @Param id path string true "Mission UUID / Flight Data UUID / Flight UUID (UUIDv7)"
+// @Success 200 {object} responsedto.FlightDataResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/flight-data/get/{id} [get]
+func (h *FlightDataHandler) Get(c *fiber.Ctx) error {
+	rawID := strings.TrimSpace(c.Params("id"))
+	parsedID, err := uuidv7.ParseString(rawID)
+	if err != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: flightdata.ErrorMessageInvalidPathUUID,
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	// Primary flow: mission UUID -> flight_data by mission relation.
+	row, err := h.svc.GetByMissionID(c.UserContext(), parsedID)
+	if err != nil {
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if row == nil {
+		// Backward compatibility for older consumers.
+		row, err = h.svc.GetByID(c.UserContext(), parsedID)
+	}
+	if err != nil {
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if row == nil {
+		row, err = h.svc.GetByFlightID(c.UserContext(), parsedID)
+	}
+	if err != nil {
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if row == nil {
+		return writeFlightDataErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: flightdata.ErrorMessageNotFound,
+		}})
+	}
+	resource, buildErr := h.buildFlightDataResource(c, row)
+	if buildErr != nil {
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: buildErr.Error(),
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, resource)
+}
+
+// UpdateFlightData godoc
+// @Summary Update flight data by ID
+// @Description Update a flight data row by UUID.
+// @Description Required field: `mission_id`. `co_pilot_id` is optional.
+// @Description Swagger request example uses the same SPO-shaped payload as create, but this endpoint updates an existing flight-data row.
+// @Description SPO facility references must point to facilities with categories: `heslo_rope_label_id -> heslo-rope-label`, `heslo.slings -> heslo-rope-length`, `logging.slings -> heslo-hook`, `hec.flights -> hec-rope-label`, and `hec.slings -> hec-rope-length`.
+// @Description For frontend usage, send only the fields that need to change; omitted fields stay unchanged. `SPO` is the default example shape, and for `CAT`/`NCO` you do not need to send the `hec`, `heslo`, or `logging` blocks. `rotor_brake_cycle` is optional for `SPO`, `CAT`, and `NCO`.
+// @Description SPO-specific response fields (`heslo`, `logging`, and `hec`) are returned only when the related mission type is `SPO`.
+// @Description Example request: {"data":{"type":"flight_data_create","attributes":{"mission_id":"019d6774-98e8-7fba-9ef4-3795c0da8a13"}}}
+// @Tags Mission - Flight Data
+// @Accept json
+// @Produce json
+// @Param id path string true "Flight Data UUID (UUIDv7)"
+// @Param request body requestdto.FlightDataUpdateRequest true "JSON:API flight data update request. Send only fields you want to change; omit the rest." SchemaExample({"data":{"type":"flight_data_update","attributes":{"mission_id":"019d6774-98e8-7fba-9ef4-3795c0da8a13","flight_take_off":"2026-04-20T08:00:00Z","flight_landing":"2026-04-20T09:15:00Z","from_icao_id":"019d6774-98e8-7fba-9ef4-3795c0da8a13","to_icao_id":"019d6774-98e8-7fba-9ef4-3795c0da8a13","hook_releases":0,"ticket_no":"SPO-001","engine":"AIRBUS H145","delivery_note_number":"DN-2026-0001","customer_name":"Patient Transfer","other_information":"SPO mission sample","landing_count":1,"heslo":{"flights":[{"id":"string","rot":0,"heslo_rope_label_id":"string","heslo_rope_label_name":"string"}],"slings":[{"id":"string","heslo_flight_id":"string","sling_id":"string","sling_name":"string"}]},"logging":{"slings":[{"id":"string","sling_id":"string","sling_name":"string"}]},"hec":{"flights":[{"equipment_id":"string","equipment_name":"string","hec_cycle":0,"id":"string","rot":0}],"loads":[{"id":"string","load_category":"string","quantity":0}],"slings":[{"id":"string","sling_id":"string","sling_name":"string"}]}}}})
+// @Success 200 {object} responsedto.FlightDataResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/flight-data/update/{id} [patch]
+func (h *FlightDataHandler) Update(c *fiber.Ctx) error {
+	rawID := strings.TrimSpace(c.Params("id"))
+	id, err := uuidv7.ParseString(rawID)
+	if err != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: flightdata.ErrorMessageInvalidPathUUID,
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	var req requestdto.FlightDataUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	attrs := req.Data.Attributes
+	missionID, errObj := parseRequiredUUID(attrs.MissionID, "/data/attributes/mission_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	coPilotID, errObj := parseOptionalUUIDFlightData(attrs.CoPilotID, "/data/attributes/co_pilot_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	fromICAOID, errObj := parseOptionalUUIDFlightData(attrs.FromICAOID, "/data/attributes/from_icao_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	fromHospitalID, errObj := parseOptionalUUIDFlightData(attrs.FromHospitalID, "/data/attributes/from_hospital_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	toICAOID, errObj := parseOptionalUUIDFlightData(attrs.ToICAOID, "/data/attributes/to_icao_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	toHospitalID, errObj := parseOptionalUUIDFlightData(attrs.ToHospitalID, "/data/attributes/to_hospital_id")
+	if errObj != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	if err := h.validateFlightDataReferences(c.UserContext(), missionID, coPilotID, fromICAOID, fromHospitalID, toICAOID, toHospitalID); err != nil {
+		return writeFlightDataServiceError(c, err, missionID, coPilotID, fromICAOID, fromHospitalID, toICAOID, toHospitalID)
+	}
+
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if row == nil {
+		return writeFlightDataErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: flightdata.ErrorMessageNotFound,
+		}})
+	}
+
+	row.MissionID = missionID
+	if len(coPilotID) > 0 {
+		row.CoPilotID = coPilotID
+	}
+	row.FromICAOID = fromICAOID
+	row.FromHospitalID = fromHospitalID
+	row.ToICAOID = toICAOID
+	row.ToHospitalID = toHospitalID
+	row.UpdatedBy = actorUserID(c)
+	if attrs.TicketNo != nil {
+		row.TicketNo = stringPtrOrEmpty(attrs.TicketNo)
+	}
+	if attrs.Engine != nil {
+		row.Engine = stringPtrOrEmpty(attrs.Engine)
+	}
+	if attrs.DeliveryNoteNumber != nil {
+		row.DeliveryNoteNumber = stringPtrOrEmpty(attrs.DeliveryNoteNumber)
+	}
+	if attrs.CustomerName != nil {
+		row.CustomerName = stringPtrOrEmpty(attrs.CustomerName)
+	}
+	if attrs.OtherInformation != nil {
+		row.OtherInformation = stringPtrOrEmpty(attrs.OtherInformation)
+	}
+	if attrs.FlightTakeOff != nil {
+		v, err := parseRFC3339(*attrs.FlightTakeOff, "/data/attributes/flight_take_off")
+		if err != nil {
+			return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*err})
+		}
+		row.FlightTakeOff = v
+	}
+	if attrs.FlightLanding != nil {
+		v, err := parseRFC3339(*attrs.FlightLanding, "/data/attributes/flight_landing")
+		if err != nil {
+			return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*err})
+		}
+		row.FlightLanding = v
+	}
+	if attrs.FlightDurationSecs != nil {
+		row.FlightDuration = time.Duration(*attrs.FlightDurationSecs) * time.Second
+	}
+	if attrs.FlightREDSecs != nil {
+		row.FlightRED = time.Duration(*attrs.FlightREDSecs) * time.Second
+	}
+	if attrs.MaxN1 != nil {
+		row.MaxN1 = *attrs.MaxN1
+	}
+	if attrs.MaxN2 != nil {
+		row.MaxN2 = *attrs.MaxN2
+	}
+	if attrs.PaxCount != nil {
+		row.PaxCount = *attrs.PaxCount
+	}
+	if attrs.LandingCount != nil {
+		row.LandingCount = *attrs.LandingCount
+	}
+	if attrs.RotorBrakeCycle != nil {
+		row.RotorBrakeCycle = *attrs.RotorBrakeCycle
+	}
+	if attrs.HookReleases != nil {
+		row.HookReleases = *attrs.HookReleases
+	}
+	if attrs.FlightPlanDistance != nil {
+		row.FlightPlanDistance = *attrs.FlightPlanDistance
+	}
+	if attrs.FlightPlanTimeSecs != nil {
+		row.FlightPlanTime = time.Duration(*attrs.FlightPlanTimeSecs) * time.Second
+	}
+	if attrs.FlightPlanTrueCourse != nil {
+		row.FlightPlanTrueCourse = *attrs.FlightPlanTrueCourse
+	}
+	if attrs.FuelBeforeFlight != nil {
+		row.FuelBeforeFlight = *attrs.FuelBeforeFlight
+	}
+	if attrs.FuelUpload != nil {
+		row.FuelUpload = *attrs.FuelUpload
+	}
+	if attrs.FuelAfterFlight != nil {
+		row.FuelAfterFlight = *attrs.FuelAfterFlight
+	}
+	if attrs.FuelPlanning != nil {
+		row.FuelPlanning = *attrs.FuelPlanning
+	}
+	if attrs.FlightPositioning != nil {
+		row.FlightPositioning = *attrs.FlightPositioning
+	}
+
+	if err := h.svc.Update(c.UserContext(), row); err != nil {
+		return writeFlightDataServiceError(c, err, row.MissionID, row.CoPilotID, row.FromICAOID, row.FromHospitalID, row.ToICAOID, row.ToHospitalID)
+	}
+
+	if spoData := parseSPOUpsertData(attrs); spoData != nil {
+		if errObj := h.validateSPOFacilityReferences(c.UserContext(), attrs); errObj != nil {
+			return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		if err := h.svc.UpsertSPODetails(c.UserContext(), row.ID, spoData); err != nil {
+			return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Update failed",
+				Detail: safeInternalDetail(),
+			}})
+		}
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && updated != nil {
+		resource, buildErr := h.buildFlightDataResource(c, updated)
+		if buildErr != nil {
+			return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Update failed",
+				Detail: buildErr.Error(),
+			}})
+		}
+		return response.Write(c, fiber.StatusOK, resource)
+	}
+	resource, buildErr := h.buildFlightDataResource(c, row)
+	if buildErr != nil {
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: buildErr.Error(),
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, resource)
+}
+
+// DeleteFlightData godoc
+// @Summary Delete flight data by ID
+// @Description Soft delete flight data by UUID.
+// @Tags Mission - Flight Data
+// @Produce json
+// @Param id path string true "Flight Data UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/flight-data/delete/{id} [delete]
+func (h *FlightDataHandler) Delete(c *fiber.Ctx) error {
+	rawID := strings.TrimSpace(c.Params("id"))
+	id, err := uuidv7.ParseString(rawID)
+	if err != nil {
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: flightdata.ErrorMessageInvalidPathUUID,
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeFlightDataErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "flight data not found",
+			}})
+		}
+		return writeFlightDataServiceError(c, err)
+	}
+	return response.Write(c, fiber.StatusOK, dto.NewGenericDeleteResponse("flight_data_delete"))
+}
+
+func flightDataResource(row *flightdata.FlightData) responsedto.FlightDataResource {
+	resource := responsedto.FlightDataResource{
+		Type:       sharedconst.FlightDataResourceType,
+		ID:         idString(row.ID),
+		Attributes: buildBaseFlightDataAttributes(row),
+	}
+
+	return resource
+}
+
+func (h *FlightDataHandler) buildFlightDataResource(c *fiber.Ctx, row *flightdata.FlightData) (responsedto.FlightDataResource, error) {
+	return buildFlightDataResourceWithService(c.UserContext(), h.svc, row)
+}
+
+func (h *FlightDataHandler) buildSPODetails(c *fiber.Ctx, row *flightdata.FlightData) (
+	*responsedto.FlightDataSPOHESLODetails,
+	*responsedto.FlightDataSPOLoggingDetails,
+	*responsedto.FlightDataSPOHECDetails,
+	error,
+) {
+	return buildFlightDataSPODetails(c.UserContext(), h.svc, row)
+}
+
+func missionRefFlightData(row *flightdata.FlightData) *responsedto.FlightDataMissionRef {
+	if row == nil {
+		return nil
+	}
+	if row.Mission == nil && len(row.MissionID) == 0 {
+		return nil
+	}
+	out := &responsedto.FlightDataMissionRef{
+		ID: idString(row.MissionID),
+	}
+	if row.Mission != nil {
+		out.ID = idString(row.Mission.ID)
+		out.Type = strings.TrimSpace(row.Mission.Type)
+	}
+	return out
+}
+
+func coPilotRefFlightData(row *flightdata.FlightData) *responsedto.FlightDataCoPilotRef {
+	if row == nil {
+		return nil
+	}
+	if row.CoPilot == nil && len(row.CoPilotID) == 0 {
+		return nil
+	}
+	out := &responsedto.FlightDataCoPilotRef{
+		ID: idString(row.CoPilotID),
+	}
+	if row.CoPilot != nil {
+		out.ID = idString(row.CoPilot.ID)
+		out.FirstName = strings.TrimSpace(row.CoPilot.FirstName)
+		out.LastName = strings.TrimSpace(row.CoPilot.LastName)
+		out.Email = strings.TrimSpace(row.CoPilot.Email)
+	}
+	return out
+}
+
+func fromLocationRefFlightData(row *flightdata.FlightData) *responsedto.FlightDataLocationRef {
+	if row == nil {
+		return nil
+	}
+	if row.FromICAO != nil {
+		code := strings.TrimSpace(row.FromICAO.ICAOCode)
+		return &responsedto.FlightDataLocationRef{
+			Type:  sharedconst.FlightDataLocationTypeICAO,
+			ID:    idString(row.FromICAO.ID),
+			Code:  code,
+			Label: code,
+		}
+	}
+	if row.FromHospital != nil {
+		name := strings.TrimSpace(row.FromHospital.Name)
+		return &responsedto.FlightDataLocationRef{
+			Type:  sharedconst.FlightDataLocationTypeHospital,
+			ID:    idString(row.FromHospital.ID),
+			Name:  name,
+			Label: name,
+		}
+	}
+	if len(row.FromICAOID) > 0 {
+		return &responsedto.FlightDataLocationRef{Type: sharedconst.FlightDataLocationTypeICAO, ID: idString(row.FromICAOID)}
+	}
+	if len(row.FromHospitalID) > 0 {
+		return &responsedto.FlightDataLocationRef{Type: sharedconst.FlightDataLocationTypeHospital, ID: idString(row.FromHospitalID)}
+	}
+	return nil
+}
+
+func toLocationRefFlightData(row *flightdata.FlightData) *responsedto.FlightDataLocationRef {
+	if row == nil {
+		return nil
+	}
+	if row.ToICAO != nil {
+		code := strings.TrimSpace(row.ToICAO.ICAOCode)
+		return &responsedto.FlightDataLocationRef{
+			Type:  sharedconst.FlightDataLocationTypeICAO,
+			ID:    idString(row.ToICAO.ID),
+			Code:  code,
+			Label: code,
+		}
+	}
+	if row.ToHospital != nil {
+		name := strings.TrimSpace(row.ToHospital.Name)
+		return &responsedto.FlightDataLocationRef{
+			Type:  sharedconst.FlightDataLocationTypeHospital,
+			ID:    idString(row.ToHospital.ID),
+			Name:  name,
+			Label: name,
+		}
+	}
+	if len(row.ToICAOID) > 0 {
+		return &responsedto.FlightDataLocationRef{Type: sharedconst.FlightDataLocationTypeICAO, ID: idString(row.ToICAOID)}
+	}
+	if len(row.ToHospitalID) > 0 {
+		return &responsedto.FlightDataLocationRef{Type: sharedconst.FlightDataLocationTypeHospital, ID: idString(row.ToHospitalID)}
+	}
+	return nil
+}
+
+func parseRequiredUUID(raw, pointer string) ([]byte, *jsonapi.ErrorObject) {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" {
+		return nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: flightdata.ErrorMessageFieldRequired,
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	v, err := uuidv7.ParseString(trimmed)
+	if err != nil {
+		return nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: flightdata.ErrorMessageInvalidUUID,
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	return v, nil
+}
+
+func parseOptionalUUIDFlightData(raw *string, pointer string) ([]byte, *jsonapi.ErrorObject) {
+	if raw == nil {
+		return nil, nil
+	}
+	trimmed := strings.TrimSpace(*raw)
+	if trimmed == "" {
+		return nil, nil
+	}
+	v, err := uuidv7.ParseString(trimmed)
+	if err != nil {
+		return nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: flightdata.ErrorMessageInvalidUUID,
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	return v, nil
+}
+
+func parseRFC3339(raw, pointer string) (time.Time, *jsonapi.ErrorObject) {
+	v, err := time.Parse(time.RFC3339, strings.TrimSpace(raw))
+	if err != nil {
+		return time.Time{}, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: flightdata.ErrorMessageInvalidRFC3339,
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	return v.UTC(), nil
+}
+
+func writeFlightDataServiceError(c *fiber.Ctx, err error, refs ...[]byte) error {
+	var (
+		fromICAOID     []byte
+		fromHospitalID []byte
+		toICAOID       []byte
+		toHospitalID   []byte
+	)
+	if len(refs) > 2 {
+		fromICAOID = refs[2]
+	}
+	if len(refs) > 3 {
+		fromHospitalID = refs[3]
+	}
+	if len(refs) > 4 {
+		toICAOID = refs[4]
+	}
+	if len(refs) > 5 {
+		toHospitalID = refs[5]
+	}
+
+	switch {
+	case errors.Is(err, flightdata.ErrMissionReference):
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: flightdata.ErrorMessageMissionReference,
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/mission_id"},
+		}})
+	case errors.Is(err, flightdata.ErrOriginLocationReference):
+		pointer := "/data/attributes/from_icao_id"
+		if len(fromICAOID) == 0 && len(fromHospitalID) > 0 {
+			pointer = "/data/attributes/from_hospital_id"
+		}
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: flightdata.ErrorMessageOriginLocationReference,
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}})
+	case errors.Is(err, flightdata.ErrDestinationLocationReference):
+		pointer := "/data/attributes/to_icao_id"
+		if len(toICAOID) == 0 && len(toHospitalID) > 0 {
+			pointer = "/data/attributes/to_hospital_id"
+		}
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: flightdata.ErrorMessageDestinationLocationReference,
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}})
+	case errors.Is(err, flightdata.ErrCoPilotReference):
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: flightdata.ErrorMessageCoPilotReference,
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/co_pilot_id"},
+		}})
+	case errors.Is(err, flightdata.ErrCreateBlocked):
+		return writeFlightDataErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+			Status: "409",
+			Title:  "Conflict",
+			Detail: flightdata.ErrorMessageCreateBlocked,
+		}})
+	case errors.Is(err, flightdata.ErrLocked):
+		return writeFlightDataErrors(c, fiber.StatusLocked, []jsonapi.ErrorObject{{
+			Status: "423",
+			Title:  "Locked",
+			Detail: flightdata.ErrorMessageLocked,
+		}})
+	case errors.Is(err, flightdata.ErrLockedAfterFlightInspection):
+		return writeFlightDataErrors(c, fiber.StatusLocked, []jsonapi.ErrorObject{{
+			Status: "423",
+			Title:  "Locked",
+			Detail: flightdata.ErrorMessageLockedAfterFlightInspection,
+		}})
+	case errors.Is(err, flightdata.ErrRequired):
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: flightdata.ErrorMessageRequired,
+		}})
+	case flightDataFKError(err) != nil:
+		obj := flightDataFKError(err)
+		return writeFlightDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*obj})
+	default:
+		return writeFlightDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+}
+
+func flightDataFKError(err error) *jsonapi.ErrorObject {
+	if err == nil {
+		return nil
+	}
+	var mysqlErr *mysqldriver.MySQLError
+	if !errors.As(err, &mysqlErr) || mysqlErr.Number != 1452 {
+		return nil
+	}
+
+	if _, errs, ok := mapOperationRelationError(err, map[string]relationFieldError{
+		"(`mission_id`)":       {Pointer: "/data/attributes/mission_id", Detail: flightdata.ErrorMessageMissionReference},
+		"(`from_icao_id`)":     {Pointer: "/data/attributes/from_icao_id", Detail: flightdata.ErrorMessageOriginLocationReference},
+		"(`from_hospital_id`)": {Pointer: "/data/attributes/from_hospital_id", Detail: flightdata.ErrorMessageOriginLocationReference},
+		"(`to_icao_id`)":       {Pointer: "/data/attributes/to_icao_id", Detail: flightdata.ErrorMessageDestinationLocationReference},
+		"(`to_hospital_id`)":   {Pointer: "/data/attributes/to_hospital_id", Detail: flightdata.ErrorMessageDestinationLocationReference},
+		"(`pilot_id`)":         {Pointer: "/data/attributes/co_pilot_id", Detail: flightdata.ErrorMessageCoPilotReference},
+		"(`co_pilot_id`)":      {Pointer: "/data/attributes/co_pilot_id", Detail: flightdata.ErrorMessageCoPilotReference},
+	}); ok && len(errs) > 0 {
+		return &errs[0]
+	}
+
+	return &jsonapi.ErrorObject{
+		Status: "422",
+		Title:  "Validation error",
+		Detail: "referenced relation data was not found",
+	}
+}
+
+func writeFlightDataErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferFlightDataDef(status, e.Title, e.Detail, e.Source)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		if strings.TrimSpace(e.Title) == "" {
+			e.Title = def.Title
+		}
+		e.Detail = def.Message
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferFlightDataDef(status int, title, detail string, source *jsonapi.ErrorSource) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	pointer := ""
+	if source != nil {
+		pointer = strings.ToLower(strings.TrimSpace(source.Pointer))
+	}
+
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.ErrFlightDataNotFound
+	case fiber.StatusLocked:
+		switch {
+		case strings.Contains(lowerDetail, "after flight inspection already exists"):
+			return apperrorsx.ErrFlightDataLockedAfterFlightInspection
+		case strings.Contains(lowerDetail, "fm report is completed"),
+			strings.Contains(lowerDetail, "flight data is locked because fm report is completed"):
+			return apperrorsx.ErrFlightDataLocked
+		default:
+			return apperrorsx.ErrFlightDataLocked
+		}
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "invalid path uuid"), pointer == "/path/uuid":
+			return apperrorsx.ErrFlightDataInvalidPathUUID
+		case strings.Contains(lowerDetail, "field is required"), pointer == "/data/attributes/mission_id":
+			return apperrorsx.ErrFlightDataMissionIDRequired
+		case strings.Contains(lowerDetail, "mission reference"):
+			return apperrorsx.ErrFlightDataMissionReference
+		case strings.Contains(lowerDetail, "field is required"), pointer == "/data/attributes/co_pilot_id", pointer == "/data/attributes/pilot_id":
+			return apperrorsx.ErrFlightDataPilotIDRequired
+		case strings.Contains(lowerDetail, "pilot must reference an existing user"):
+			return apperrorsx.ErrFlightDataPilotIDRequired
+		case strings.Contains(lowerDetail, "invalid uuid"):
+			return apperrorsx.ErrFlightDataInvalidUUID
+		case strings.Contains(lowerDetail, "invalid rfc3339"):
+			return apperrorsx.ErrFlightDataInvalidRFC3339
+		case strings.Contains(lowerDetail, "origin location reference"):
+			return apperrorsx.ErrFlightDataOriginLocationReference
+		case strings.Contains(lowerDetail, "destination location reference"):
+			return apperrorsx.ErrFlightDataDestinationLocationReference
+		case strings.Contains(lowerDetail, "pilot reference"):
+			return apperrorsx.ErrFlightDataPilotReference
+		case strings.Contains(lowerDetail, "facility reference"):
+			return apperrorsx.ErrFlightDataFacilityReference
+		case strings.Contains(lowerDetail, "cannot be created"), strings.Contains(lowerDetail, "already exists"):
+			return apperrorsx.ErrFlightDataCreateBlocked
+		default:
+			return apperrorsx.ErrFlightDataInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrFlightDataInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			if strings.Contains(lowerDetail, "required data is missing") {
+				return apperrorsx.ErrFlightDataRequired
+			}
+			return apperrorsx.ErrFlightDataCreateFailed
+		case strings.Contains(lowerTitle, "get failed"):
+			return apperrorsx.ErrFlightDataGetFailed
+		default:
+			return apperrorsx.ErrInvalidRequest
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
+
+func inferFlightDataErrorCode(status int, title, detail string, source *jsonapi.ErrorSource) (string, string) {
+	def := inferFlightDataDef(status, title, detail, source)
+	return def.Code, def.ErrorCode
+}
+
+func parseSPOUpsertData(attrs requestdto.FlightDataCreateAttributes) *flightdata.SPOUpsertData {
+	if attrs.HESLO == nil && attrs.Logging == nil && attrs.HEC == nil {
+		return nil
+	}
+	data := &flightdata.SPOUpsertData{}
+
+	if attrs.HESLO != nil {
+		heslo := &flightdata.SPOHESLOUpsert{
+			Flights: make([]flightdata.SPOHESLOFlightUpsert, 0, len(attrs.HESLO.Flights)),
+		}
+		for _, f := range attrs.HESLO.Flights {
+			fu := flightdata.SPOHESLOFlightUpsert{ROT: f.ROT}
+			if id, err := uuidv7.ParseString(f.HESLORopeLabelID); err == nil {
+				fu.FuelTruckID = id
+			}
+			for _, s := range f.Slings {
+				if id, err := uuidv7.ParseString(s.SlingID); err == nil {
+					fu.Slings = append(fu.Slings, flightdata.SPOHESLOSlingUpsert{SlingID: id})
+				}
+			}
+			heslo.Flights = append(heslo.Flights, fu)
+		}
+		data.HESLO = heslo
+	}
+
+	if attrs.Logging != nil {
+		logging := &flightdata.SPOLoggingUpsert{
+			Slings: make([]flightdata.SPOLoggingSlingUpsert, 0, len(attrs.Logging.Slings)),
+		}
+		for _, s := range attrs.Logging.Slings {
+			if id, err := uuidv7.ParseString(s.SlingID); err == nil {
+				logging.Slings = append(logging.Slings, flightdata.SPOLoggingSlingUpsert{SlingID: id})
+			}
+		}
+		data.Logging = logging
+	}
+
+	if attrs.HEC != nil {
+		hec := &flightdata.SPOHECUpsert{
+			Flights: make([]flightdata.SPOHECFlightUpsert, 0, len(attrs.HEC.Flights)),
+			Slings:  make([]flightdata.SPOHECSlingUpsert, 0, len(attrs.HEC.Slings)),
+			Loads:   make([]flightdata.SPOHECLoadUpsert, 0, len(attrs.HEC.Loads)),
+		}
+		for _, f := range attrs.HEC.Flights {
+			fu := flightdata.SPOHECFlightUpsert{ROT: f.ROT, HECCycle: f.HECCycle}
+			if id, err := uuidv7.ParseString(f.EquipmentID); err == nil {
+				fu.EquipmentID = id
+			}
+			hec.Flights = append(hec.Flights, fu)
+		}
+		for _, s := range attrs.HEC.Slings {
+			if id, err := uuidv7.ParseString(s.SlingID); err == nil {
+				hec.Slings = append(hec.Slings, flightdata.SPOHECSlingUpsert{SlingID: id})
+			}
+		}
+		for _, l := range attrs.HEC.Loads {
+			hec.Loads = append(hec.Loads, flightdata.SPOHECLoadUpsert{
+				LoadCategory: l.LoadCategory,
+				Quantity:     l.Quantity,
+			})
+		}
+		data.HEC = hec
+	}
+
+	return data
+}
+
+// --- Response building (flight data → JSON:API resource) ---
+
+func buildFlightDataResourceWithService(ctx context.Context, svc flightdata.Service, row *flightdata.FlightData) (responsedto.FlightDataResource, error) {
+	resource := responsedto.FlightDataResource{
+		Type:       sharedconst.FlightDataResourceType,
+		ID:         idString(row.ID),
+		Attributes: buildBaseFlightDataAttributes(row),
+	}
+
+	heslo, logging, hec, err := buildFlightDataSPODetails(ctx, svc, row)
+	if err != nil {
+		return responsedto.FlightDataResource{}, err
+	}
+	resource.Attributes.HESLO = heslo
+	resource.Attributes.Logging = logging
+	resource.Attributes.HEC = hec
+	return resource, nil
+}
+
+func buildBaseFlightDataAttributes(row *flightdata.FlightData) responsedto.FlightDataAttributes {
+	return responsedto.FlightDataAttributes{
+		Status: func() string {
+			if status := strings.TrimSpace(row.Status); status != "" {
+				return status
+			}
+			return flightdata.StatusInProgress
+		}(),
+		Mission:               missionRefFlightData(row),
+		RosterDetails:         rosterDetailsFromFlightData(row),
+		CoPilot:               coPilotRefFlightData(row),
+		From:                  fromLocationRefFlightData(row),
+		To:                    toLocationRefFlightData(row),
+		FlightTakeOff:         formatTimeOrEmpty(row.FlightTakeOff),
+		FlightLanding:         formatTimeOrEmpty(row.FlightLanding),
+		FlightDuration:        int64(row.FlightDuration.Seconds()),
+		FlightRED:             int64(row.FlightRED.Seconds()),
+		MaxN1:                 row.MaxN1,
+		MaxN2:                 row.MaxN2,
+		PaxCount:              row.PaxCount,
+		LandingCount:          row.LandingCount,
+		RotorBrakeCycle:       row.RotorBrakeCycle,
+		HookReleases:          row.HookReleases,
+		TicketNo:              row.TicketNo,
+		Engine:                row.Engine,
+		DeliveryNoteNumber:    row.DeliveryNoteNumber,
+		CustomerName:          row.CustomerName,
+		FlightPlanDistance:    row.FlightPlanDistance,
+		FlightPlanTimeSeconds: int64(row.FlightPlanTime.Seconds()),
+		FlightPlanTrueCourse:  row.FlightPlanTrueCourse,
+		FuelBeforeFlight:      row.FuelBeforeFlight,
+		FuelUpload:            row.FuelUpload,
+		FuelAfterFlight:       row.FuelAfterFlight,
+		FuelPlanning:          row.FuelPlanning,
+		FlightPositioning:     row.FlightPositioning,
+		OtherInformation:      row.OtherInformation,
+		CreatedAt:             formatTimeOrEmpty(row.CreatedAt),
+		CreatedBy:             uuidStringOrEmpty(row.CreatedBy),
+		UpdatedAt:             formatTimeOrEmpty(row.UpdatedAt),
+		UpdatedBy:             uuidStringOrEmpty(row.UpdatedBy),
+	}
+}
+
+func rosterDetailsFromFlightData(row *flightdata.FlightData) *responsedto.TakeoverDutyRosterDetailsResponse {
+	if row == nil || row.Mission == nil || row.Mission.Flight == nil || row.Mission.Flight.Takeover == nil {
+		return nil
+	}
+	takeoverRow := row.Mission.Flight.Takeover
+	if len(takeoverRow.RosterCrews) == 0 && len(takeoverRow.OtherPeople) == 0 {
+		return nil
+	}
+	resource := responsedto.DutyRosterResource{
+		Attributes: responsedto.DutyRosterAttributes{
+			Detail: responsedto.DutyRosterDetailsResponse{
+				Pilot:       []responsedto.DutyRosterPilotCrew{},
+				Doctor:      []responsedto.DutyRosterCrew{},
+				Rescuer:     []responsedto.DutyRosterCrew{},
+				Helper:      []responsedto.DutyRosterCrew{},
+				OtherPerson: []responsedto.DutyRosterCrew{},
+			},
+		},
+	}
+	resource = buildDutyRosterResourceFromTakeoverRows(resource, takeoverRow.RosterCrews, row.Mission.Flight)
+	resource = buildDutyRosterResourceFromOtherPeople(resource, takeoverRow.OtherPeople)
+	detail := takeoverDutyRosterDetailsFromRosterDetails(resource.Attributes.Detail)
+	return &detail
+}
+
+func formatTimeOrEmpty(value time.Time) string {
+	if value.IsZero() {
+		return ""
+	}
+	return value.UTC().Format(time.RFC3339)
+}
+
+func buildFlightDataSPODetails(
+	ctx context.Context,
+	svc flightdata.Service,
+	row *flightdata.FlightData,
+) (
+	*responsedto.FlightDataSPOHESLODetails,
+	*responsedto.FlightDataSPOLoggingDetails,
+	*responsedto.FlightDataSPOHECDetails,
+	error,
+) {
+	if svc == nil || row == nil || row.Mission == nil || strings.ToUpper(strings.TrimSpace(row.Mission.Type)) != "SPO" {
+		return nil, nil, nil, nil
+	}
+	if len(row.ID) != 16 {
+		return nil, nil, nil, nil
+	}
+
+	details, err := svc.GetSPODetailsByFlightDataID(ctx, row.ID)
+	if err != nil || details == nil {
+		return nil, nil, nil, err
+	}
+
+	heslo := &responsedto.FlightDataSPOHESLODetails{
+		Flights: make([]responsedto.FlightDataSPOHESLOFlight, 0, len(details.HESLO.Flights)),
+	}
+	logging := &responsedto.FlightDataSPOLoggingDetails{
+		Slings: make([]responsedto.FlightDataSPOLoggingSling, 0, len(details.Logging.Slings)),
+	}
+	hec := &responsedto.FlightDataSPOHECDetails{
+		Flights: make([]responsedto.FlightDataSPOHECFlight, 0, len(details.HEC.Flights)),
+		Slings:  make([]responsedto.FlightDataSPOHECSling, 0, len(details.HEC.Slings)),
+		Loads:   make([]responsedto.FlightDataSPOHECLoad, 0, len(details.HEC.Loads)),
+	}
+
+	slingsByFlightID := make(map[string][]responsedto.FlightDataSPOHESLOSling, len(details.HESLO.Slings))
+	for i := range details.HESLO.Slings {
+		flightID := idString(details.HESLO.Slings[i].HESLOFlightID)
+		slingsByFlightID[flightID] = append(slingsByFlightID[flightID], responsedto.FlightDataSPOHESLOSling{
+			ID:        idString(details.HESLO.Slings[i].ID),
+			SlingID:   idString(details.HESLO.Slings[i].SlingID),
+			SlingName: strings.TrimSpace(details.HESLO.Slings[i].SlingName),
+		})
+	}
+
+	for i := range details.HESLO.Flights {
+		flightID := idString(details.HESLO.Flights[i].ID)
+		heslo.Flights = append(heslo.Flights, responsedto.FlightDataSPOHESLOFlight{
+			ID:                 flightID,
+			ROT:                details.HESLO.Flights[i].ROT,
+			HESLORopeLabelID:   idString(details.HESLO.Flights[i].FuelTruckID),
+			HESLORopeLabelName: strings.TrimSpace(details.HESLO.Flights[i].FuelTruckName),
+			Slings:             slingsByFlightID[flightID],
+		})
+	}
+	for i := range details.Logging.Slings {
+		logging.Slings = append(logging.Slings, responsedto.FlightDataSPOLoggingSling{
+			ID:        idString(details.Logging.Slings[i].ID),
+			SlingID:   idString(details.Logging.Slings[i].SlingID),
+			SlingName: strings.TrimSpace(details.Logging.Slings[i].SlingName),
+		})
+	}
+	for i := range details.HEC.Flights {
+		hec.Flights = append(hec.Flights, responsedto.FlightDataSPOHECFlight{
+			ID:            idString(details.HEC.Flights[i].ID),
+			ROT:           details.HEC.Flights[i].ROT,
+			HECCycle:      details.HEC.Flights[i].HECCycle,
+			EquipmentID:   idString(details.HEC.Flights[i].EquipmentID),
+			EquipmentName: strings.TrimSpace(details.HEC.Flights[i].EquipmentName),
+		})
+	}
+	for i := range details.HEC.Slings {
+		hec.Slings = append(hec.Slings, responsedto.FlightDataSPOHECSling{
+			ID:        idString(details.HEC.Slings[i].ID),
+			SlingID:   idString(details.HEC.Slings[i].SlingID),
+			SlingName: strings.TrimSpace(details.HEC.Slings[i].SlingName),
+		})
+	}
+	for i := range details.HEC.Loads {
+		hec.Loads = append(hec.Loads, responsedto.FlightDataSPOHECLoad{
+			ID:           idString(details.HEC.Loads[i].ID),
+			LoadCategory: strings.TrimSpace(details.HEC.Loads[i].LoadCategory),
+			Quantity:     details.HEC.Loads[i].Quantity,
+		})
+	}
+
+	return heslo, logging, hec, nil
+}
diff --git a/internal/transport/http/handlers/flight_data_handler_test.go b/internal/transport/http/handlers/flight_data_handler_test.go
new file mode 100644
index 0000000..9d9aac8
--- /dev/null
+++ b/internal/transport/http/handlers/flight_data_handler_test.go
@@ -0,0 +1,857 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	facilitydomain "wucher/internal/domain/facility"
+	flightdata "wucher/internal/domain/flight_data"
+	hospitaldomain "wucher/internal/domain/hospital"
+	icaodomain "wucher/internal/domain/icao"
+	missiondomain "wucher/internal/domain/mission"
+	userdomain "wucher/internal/domain/user"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type flightDataServiceMock struct {
+	createFn      func(context.Context, *flightdata.FlightData) error
+	updateFn      func(context.Context, *flightdata.FlightData) error
+	deleteFn      func(context.Context, []byte, []byte) error
+	getByIDFn     func(context.Context, []byte) (*flightdata.FlightData, error)
+	getByFlightFn func(context.Context, []byte) (*flightdata.FlightData, error)
+	getByMisFn    func(context.Context, []byte) (*flightdata.FlightData, error)
+	listFn        func(context.Context, string, []byte, []byte, int, int) ([]flightdata.FlightData, int64, error)
+	getSpoFn      func(context.Context, []byte) (*flightdata.SPODetails, error)
+}
+
+type userServiceMock struct {
+	getByIDFn func(context.Context, []byte) (*userdomain.User, error)
+}
+
+type facilityServiceMock struct {
+	getByIDFn func(context.Context, []byte) (*facilitydomain.Facility, error)
+}
+
+type flightDataMissionServiceMock struct {
+	getByIDFn func(context.Context, []byte) (*missiondomain.Mission, error)
+}
+
+type hospitalServiceMock struct {
+	getByIDFn func(context.Context, []byte) (*hospitaldomain.Hospital, error)
+}
+
+type icaoServiceMock struct {
+	getByIDFn func(context.Context, []byte) (*icaodomain.ICAO, error)
+}
+
+func (m *flightDataServiceMock) Create(ctx context.Context, row *flightdata.FlightData) error {
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return nil
+}
+func (m *flightDataServiceMock) CreatePlaceholder(ctx context.Context, row *flightdata.FlightData) error {
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return nil
+}
+func (m *flightDataServiceMock) Update(ctx context.Context, row *flightdata.FlightData) error {
+	if m.updateFn != nil {
+		return m.updateFn(ctx, row)
+	}
+	return nil
+}
+func (m *flightDataServiceMock) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if m.deleteFn != nil {
+		return m.deleteFn(ctx, id, deletedBy)
+	}
+	return nil
+}
+func (m *flightDataServiceMock) GetByID(ctx context.Context, id []byte) (*flightdata.FlightData, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *flightDataServiceMock) GetByFlightID(ctx context.Context, id []byte) (*flightdata.FlightData, error) {
+	if m.getByFlightFn != nil {
+		return m.getByFlightFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *flightDataServiceMock) GetByMissionID(ctx context.Context, id []byte) (*flightdata.FlightData, error) {
+	if m.getByMisFn != nil {
+		return m.getByMisFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *flightDataServiceMock) ListByMissionID(ctx context.Context, missionID []byte) ([]flightdata.FlightData, error) {
+	if m.listFn != nil {
+		rows, _, err := m.listFn(ctx, "", missionID, nil, 0, 0)
+		return rows, err
+	}
+	return nil, nil
+}
+func (m *flightDataServiceMock) List(ctx context.Context, date string, missionID, flightDataID []byte, limit, offset int) ([]flightdata.FlightData, int64, error) {
+	if m.listFn != nil {
+		return m.listFn(ctx, date, missionID, flightDataID, limit, offset)
+	}
+	return nil, 0, nil
+}
+func (m *flightDataServiceMock) GetSPODetailsByFlightDataID(ctx context.Context, id []byte) (*flightdata.SPODetails, error) {
+	if m.getSpoFn != nil {
+		return m.getSpoFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *flightDataServiceMock) UpsertSPODetails(context.Context, []byte, *flightdata.SPOUpsertData) error {
+	return nil
+}
+
+func (m *userServiceMock) GetByID(ctx context.Context, id []byte) (*userdomain.User, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *facilityServiceMock) GetByID(ctx context.Context, id []byte) (*facilitydomain.Facility, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *flightDataMissionServiceMock) GetByID(ctx context.Context, id []byte) (*missiondomain.Mission, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *hospitalServiceMock) GetByID(ctx context.Context, id []byte) (*hospitaldomain.Hospital, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *icaoServiceMock) GetByID(ctx context.Context, id []byte) (*icaodomain.ICAO, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func newFlightDataApp(h *FlightDataHandler) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", uuidv7.MustBytes())
+		return c.Next()
+	})
+	app.Post("/flight-data", h.Create)
+	app.Get("/flight-data/get-all", h.List)
+	app.Get("/flight-data/get-all/dt", h.ListDatatable)
+	app.Get("/flight-data/:id", h.Get)
+	app.Patch("/flight-data/:id", h.Update)
+	app.Delete("/flight-data/:id", h.Delete)
+	return app
+}
+
+func doReqFD(t *testing.T, app *fiber.App, method, path string, body []byte) (int, string) {
+	t.Helper()
+	var rdr io.Reader
+	if body != nil {
+		rdr = bytes.NewReader(body)
+	}
+	req, _ := http.NewRequest(method, path, rdr)
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	defer resp.Body.Close()
+	b, _ := io.ReadAll(resp.Body)
+	return resp.StatusCode, string(b)
+}
+
+func TestFlightDataHandler(t *testing.T) {
+	t.Run("new", func(t *testing.T) {
+		h := NewFlightDataHandler(&flightDataServiceMock{})
+		if h == nil || h.validate == nil {
+			t.Fatal("expected handler initialized")
+		}
+	})
+
+	t.Run("create parse and validation errors", func(t *testing.T) {
+		h := NewFlightDataHandler(&flightDataServiceMock{})
+		code, _ := doReqFD(t, newFlightDataApp(h), http.MethodPost, "/flight-data", []byte(`{"data":`))
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+		code, _ = doReqFD(t, newFlightDataApp(h), http.MethodPost, "/flight-data", []byte(`{}`))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		body := `{"data":{"type":"flight_data","attributes":{"mission_id":"bad","co_pilot_id":"bad"}}}`
+		code, _ = doReqFD(t, newFlightDataApp(h), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		body = `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"bad"}}}`
+		code, _ = doReqFD(t, newFlightDataApp(h), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+	})
+
+	t.Run("create optional and datetime validation", func(t *testing.T) {
+		h := NewFlightDataHandler(&flightDataServiceMock{})
+		body := `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","from_icao_id":"bad"}}}`
+		code, _ := doReqFD(t, newFlightDataApp(h), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		body = `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","flight_take_off":"bad"}}}`
+		code, _ = doReqFD(t, newFlightDataApp(h), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		body = `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","from_hospital_id":"bad"}}}`
+		code, _ = doReqFD(t, newFlightDataApp(h), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		body = `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","to_icao_id":"bad"}}}`
+		code, _ = doReqFD(t, newFlightDataApp(h), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		body = `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","to_hospital_id":"bad"}}}`
+		code, _ = doReqFD(t, newFlightDataApp(h), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		body = `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","flight_landing":"bad"}}}`
+		code, _ = doReqFD(t, newFlightDataApp(h), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		hRef := NewFlightDataHandler(&flightDataServiceMock{}).
+			WithUserService(&userServiceMock{getByIDFn: func(context.Context, []byte) (*userdomain.User, error) {
+				return &userdomain.User{ID: uuidv7.MustBytes()}, nil
+			}}).
+			WithHospitalService(&hospitalServiceMock{getByIDFn: func(context.Context, []byte) (*hospitaldomain.Hospital, error) {
+				return nil, nil
+			}}).
+			WithICAOService(&icaoServiceMock{getByIDFn: func(context.Context, []byte) (*icaodomain.ICAO, error) {
+				return &icaodomain.ICAO{ID: uuidv7.MustBytes()}, nil
+			}})
+		body = `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","from_hospital_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `"}}}`
+		code, _ = doReqFD(t, newFlightDataApp(hRef), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+	})
+
+	t.Run("create allows omitting co_pilot_id", func(t *testing.T) {
+		var gotPilotID []byte
+		h := NewFlightDataHandler(&flightDataServiceMock{
+			createFn: func(_ context.Context, row *flightdata.FlightData) error {
+				gotPilotID = append([]byte(nil), row.CoPilotID...)
+				row.ID = uuidv7.MustBytes()
+				row.CreatedAt = time.Now().UTC()
+				row.UpdatedAt = row.CreatedAt
+				return nil
+			},
+			getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+				return &flightdata.FlightData{ID: id, MissionID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		})
+		body := `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `"}}}`
+		code, _ := doReqFD(t, newFlightDataApp(h), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusCreated {
+			t.Fatalf("expected 201 got %d", code)
+		}
+		if len(gotPilotID) != 0 {
+			t.Fatalf("expected empty pilot_id when co_pilot_id is omitted, got %x", gotPilotID)
+		}
+	})
+
+	t.Run("create service errors and success fallback", func(t *testing.T) {
+		h1 := NewFlightDataHandler(&flightDataServiceMock{
+			createFn: func(context.Context, *flightdata.FlightData) error { return flightdata.ErrOriginLocationReference },
+		})
+		body := `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `"}}}`
+		code, _ := doReqFD(t, newFlightDataApp(h1), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		body = `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","from_hospital_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `"}}}`
+		h1Hospital := NewFlightDataHandler(&flightDataServiceMock{
+			createFn: func(context.Context, *flightdata.FlightData) error { return flightdata.ErrOriginLocationReference },
+		})
+		code, respBody := doReqFD(t, newFlightDataApp(h1Hospital), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		if !strings.Contains(respBody, `"pointer":"/data/attributes/from_hospital_id"`) {
+			t.Fatalf("expected origin hospital pointer, got %s", respBody)
+		}
+		h1Missing := NewFlightDataHandler(&flightDataServiceMock{}).
+			WithHospitalService(&hospitalServiceMock{getByIDFn: func(context.Context, []byte) (*hospitaldomain.Hospital, error) {
+				return nil, gorm.ErrRecordNotFound
+			}})
+		body = `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","from_hospital_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `"}}}`
+		code, respBody = doReqFD(t, newFlightDataApp(h1Missing), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		if !strings.Contains(respBody, `"pointer":"/data/attributes/from_hospital_id"`) {
+			t.Fatalf("expected record-not-found origin hospital pointer, got %s", respBody)
+		}
+		hMission := NewFlightDataHandler(&flightDataServiceMock{}).
+			WithMissionService(&flightDataMissionServiceMock{getByIDFn: func(context.Context, []byte) (*missiondomain.Mission, error) {
+				return nil, gorm.ErrRecordNotFound
+			}})
+		body = `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `"}}}`
+		code, respBody = doReqFD(t, newFlightDataApp(hMission), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		if !strings.Contains(respBody, `"pointer":"/data/attributes/mission_id"`) {
+			t.Fatalf("expected mission pointer, got %s", respBody)
+		}
+		h2 := NewFlightDataHandler(&flightDataServiceMock{
+			createFn: func(context.Context, *flightdata.FlightData) error { return errors.New("x") },
+		})
+		code, _ = doReqFD(t, newFlightDataApp(h2), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+		h3 := NewFlightDataHandler(&flightDataServiceMock{
+			createFn: func(_ context.Context, row *flightdata.FlightData) error {
+				row.ID = uuidv7.MustBytes()
+				row.CreatedAt = time.Now().UTC()
+				row.UpdatedAt = row.CreatedAt
+				return nil
+			},
+			getByIDFn: func(context.Context, []byte) (*flightdata.FlightData, error) { return nil, errors.New("no") },
+		})
+		code, _ = doReqFD(t, newFlightDataApp(h3), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusCreated {
+			t.Fatalf("expected 201 got %d", code)
+		}
+		hSuccessCreated := NewFlightDataHandler(&flightDataServiceMock{
+			createFn: func(_ context.Context, row *flightdata.FlightData) error {
+				row.ID = uuidv7.MustBytes()
+				row.CreatedAt = time.Now().UTC()
+				row.UpdatedAt = row.CreatedAt
+				return nil
+			},
+			getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+				return &flightdata.FlightData{ID: id, MissionID: uuidv7.MustBytes(), CoPilotID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		})
+		code, _ = doReqFD(t, newFlightDataApp(hSuccessCreated), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusCreated {
+			t.Fatalf("expected 201 got %d", code)
+		}
+
+		h4 := NewFlightDataHandler(&flightDataServiceMock{
+			createFn: func(_ context.Context, row *flightdata.FlightData) error {
+				row.ID = uuidv7.MustBytes()
+				row.CreatedAt = time.Now().UTC()
+				row.UpdatedAt = row.CreatedAt
+				return nil
+			},
+			getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+				return &flightdata.FlightData{
+					ID:        id,
+					MissionID: uuidv7.MustBytes(),
+					CoPilotID: uuidv7.MustBytes(),
+					Mission:   &missiondomain.Mission{Type: "SPO"},
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}, nil
+			},
+			getSpoFn: func(context.Context, []byte) (*flightdata.SPODetails, error) { return nil, errors.New("spo err") },
+		})
+		code, _ = doReqFD(t, newFlightDataApp(h4), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+		h5 := NewFlightDataHandler(&flightDataServiceMock{
+			createFn: func(_ context.Context, row *flightdata.FlightData) error {
+				row.ID = uuidv7.MustBytes()
+				row.CreatedAt = time.Now().UTC()
+				row.UpdatedAt = row.CreatedAt
+				row.Mission = &missiondomain.Mission{Type: "SPO"}
+				return nil
+			},
+			getByIDFn: func(context.Context, []byte) (*flightdata.FlightData, error) { return nil, errors.New("x") },
+			getSpoFn: func(context.Context, []byte) (*flightdata.SPODetails, error) {
+				return nil, errors.New("spo fallback err")
+			},
+		})
+		code, _ = doReqFD(t, newFlightDataApp(h5), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+	})
+
+	t.Run("get flows", func(t *testing.T) {
+		h := NewFlightDataHandler(&flightDataServiceMock{})
+		code, _ := doReqFD(t, newFlightDataApp(h), http.MethodGet, "/flight-data/bad", nil)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+
+		id := mustUUIDStringHospital(t, uuidv7.MustBytes())
+		hErr := NewFlightDataHandler(&flightDataServiceMock{
+			getByMisFn: func(context.Context, []byte) (*flightdata.FlightData, error) { return nil, errors.New("x") },
+		})
+		code, _ = doReqFD(t, newFlightDataApp(hErr), http.MethodGet, "/flight-data/"+id, nil)
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+
+		hNot := NewFlightDataHandler(&flightDataServiceMock{
+			getByMisFn:    func(context.Context, []byte) (*flightdata.FlightData, error) { return nil, nil },
+			getByIDFn:     func(context.Context, []byte) (*flightdata.FlightData, error) { return nil, nil },
+			getByFlightFn: func(context.Context, []byte) (*flightdata.FlightData, error) { return nil, nil },
+		})
+		code, _ = doReqFD(t, newFlightDataApp(hNot), http.MethodGet, "/flight-data/"+id, nil)
+		if code != http.StatusNotFound {
+			t.Fatalf("expected 404 got %d", code)
+		}
+
+		row := &flightdata.FlightData{
+			ID:         uuidv7.MustBytes(),
+			MissionID:  uuidv7.MustBytes(),
+			CoPilotID:  uuidv7.MustBytes(),
+			Mission:    &missiondomain.Mission{ID: uuidv7.MustBytes(), Type: "SPO"},
+			CoPilot:    &userdomain.User{ID: uuidv7.MustBytes(), FirstName: "A", LastName: "B", Email: "a@b.c"},
+			FromICAO:   &icaodomain.ICAO{ID: uuidv7.MustBytes(), ICAOCode: "WIII"},
+			ToHospital: &hospitaldomain.Hospital{ID: uuidv7.MustBytes(), Name: "RS"},
+			CreatedAt:  time.Now().UTC(),
+			UpdatedAt:  time.Now().UTC(),
+		}
+		hOK := NewFlightDataHandler(&flightDataServiceMock{
+			getByMisFn: func(context.Context, []byte) (*flightdata.FlightData, error) { return row, nil },
+			getSpoFn:   func(context.Context, []byte) (*flightdata.SPODetails, error) { return &flightdata.SPODetails{}, nil },
+		})
+		code, body := doReqFD(t, newFlightDataApp(hOK), http.MethodGet, "/flight-data/"+id, nil)
+		if code != http.StatusOK || !strings.Contains(body, `"flight_data"`) {
+			t.Fatalf("expected 200 got %d body=%s", code, body)
+		}
+
+		hByIDErr := NewFlightDataHandler(&flightDataServiceMock{
+			getByMisFn: func(context.Context, []byte) (*flightdata.FlightData, error) { return nil, nil },
+			getByIDFn:  func(context.Context, []byte) (*flightdata.FlightData, error) { return nil, errors.New("x") },
+		})
+		code, _ = doReqFD(t, newFlightDataApp(hByIDErr), http.MethodGet, "/flight-data/"+id, nil)
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+		hByFlightErr := NewFlightDataHandler(&flightDataServiceMock{
+			getByMisFn:    func(context.Context, []byte) (*flightdata.FlightData, error) { return nil, nil },
+			getByIDFn:     func(context.Context, []byte) (*flightdata.FlightData, error) { return nil, nil },
+			getByFlightFn: func(context.Context, []byte) (*flightdata.FlightData, error) { return nil, errors.New("x") },
+		})
+		code, _ = doReqFD(t, newFlightDataApp(hByFlightErr), http.MethodGet, "/flight-data/"+id, nil)
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+		hBuildErr := NewFlightDataHandler(&flightDataServiceMock{
+			getByMisFn: func(context.Context, []byte) (*flightdata.FlightData, error) {
+				return &flightdata.FlightData{ID: uuidv7.MustBytes(), Mission: &missiondomain.Mission{Type: "SPO"}, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+			getSpoFn: func(context.Context, []byte) (*flightdata.SPODetails, error) { return nil, errors.New("x") },
+		})
+		code, _ = doReqFD(t, newFlightDataApp(hBuildErr), http.MethodGet, "/flight-data/"+id, nil)
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+	})
+
+	t.Run("update and delete flows", func(t *testing.T) {
+		id := mustUUIDStringHospital(t, uuidv7.MustBytes())
+		body := `{"data":{"type":"flight_data_update","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `"}}}`
+		refBody := `{"data":{"type":"flight_data_update","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","from_hospital_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `"}}}`
+
+		hUpdateBadID := NewFlightDataHandler(&flightDataServiceMock{})
+		code, _ := doReqFD(t, newFlightDataApp(hUpdateBadID), http.MethodPatch, "/flight-data/bad", []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+
+		hUpdateValidate := NewFlightDataHandler(&flightDataServiceMock{})
+		code, _ = doReqFD(t, newFlightDataApp(hUpdateValidate), http.MethodPatch, "/flight-data/"+id, []byte(`{}`))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		noPilotBody := `{"data":{"type":"flight_data_update","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `"}}}`
+		hUpdateNoPilot := NewFlightDataHandler(&flightDataServiceMock{
+			updateFn: func(_ context.Context, row *flightdata.FlightData) error {
+				if len(row.CoPilotID) != 16 {
+					t.Fatalf("expected existing pilot_id to stay unchanged, got %d bytes", len(row.CoPilotID))
+				}
+				row.UpdatedAt = time.Now().UTC()
+				return nil
+			},
+			getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+				now := time.Now().UTC()
+				return &flightdata.FlightData{ID: id, MissionID: uuidv7.MustBytes(), CoPilotID: uuidv7.MustBytes(), CreatedAt: now, UpdatedAt: now}, nil
+			},
+		})
+		code, _ = doReqFD(t, newFlightDataApp(hUpdateNoPilot), http.MethodPatch, "/flight-data/"+id, []byte(noPilotBody))
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		hUpdateRef := NewFlightDataHandler(&flightDataServiceMock{}).
+			WithUserService(&userServiceMock{getByIDFn: func(context.Context, []byte) (*userdomain.User, error) {
+				return &userdomain.User{ID: uuidv7.MustBytes()}, nil
+			}}).
+			WithHospitalService(&hospitalServiceMock{getByIDFn: func(context.Context, []byte) (*hospitaldomain.Hospital, error) {
+				return nil, nil
+			}}).
+			WithICAOService(&icaoServiceMock{getByIDFn: func(context.Context, []byte) (*icaodomain.ICAO, error) {
+				return &icaodomain.ICAO{ID: uuidv7.MustBytes()}, nil
+			}})
+		code, _ = doReqFD(t, newFlightDataApp(hUpdateRef), http.MethodPatch, "/flight-data/"+id, []byte(refBody))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+
+		spoBody := `{"data":{"type":"flight_data_update","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","logging":{"slings":[{"sling_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `"}]}}}}`
+		hUpdateSPORef := NewFlightDataHandler(&flightDataServiceMock{
+			updateFn: func(_ context.Context, row *flightdata.FlightData) error {
+				row.UpdatedAt = time.Now().UTC()
+				return nil
+			},
+			getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+				now := time.Now().UTC()
+				return &flightdata.FlightData{ID: id, MissionID: uuidv7.MustBytes(), CoPilotID: uuidv7.MustBytes(), CreatedAt: now, UpdatedAt: now}, nil
+			},
+		}).WithFacilityService(&facilityServiceMock{
+			getByIDFn: func(context.Context, []byte) (*facilitydomain.Facility, error) {
+				return nil, gorm.ErrRecordNotFound
+			},
+		})
+		code, respBody := doReqFD(t, newFlightDataApp(hUpdateSPORef), http.MethodPatch, "/flight-data/"+id, []byte(spoBody))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		if !strings.Contains(respBody, `"pointer":"/data/attributes/logging/slings/0/sling_id"`) {
+			t.Fatalf("expected logging sling pointer, got %s", respBody)
+		}
+
+		hUpdateSPOWrongCategory := NewFlightDataHandler(&flightDataServiceMock{
+			updateFn: func(_ context.Context, row *flightdata.FlightData) error {
+				row.UpdatedAt = time.Now().UTC()
+				return nil
+			},
+			getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+				now := time.Now().UTC()
+				return &flightdata.FlightData{ID: id, MissionID: uuidv7.MustBytes(), CoPilotID: uuidv7.MustBytes(), CreatedAt: now, UpdatedAt: now}, nil
+			},
+		}).WithFacilityService(&facilityServiceMock{
+			getByIDFn: func(context.Context, []byte) (*facilitydomain.Facility, error) {
+				return &facilitydomain.Facility{ID: uuidv7.MustBytes(), Category: "wrong-category"}, nil
+			},
+		})
+		code, _ = doReqFD(t, newFlightDataApp(hUpdateSPOWrongCategory), http.MethodPatch, "/flight-data/"+id, []byte(spoBody))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+
+		hUpdateErr := NewFlightDataHandler(&flightDataServiceMock{
+			updateFn: func(context.Context, *flightdata.FlightData) error { return errors.New("x") },
+			getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+				now := time.Now().UTC()
+				return &flightdata.FlightData{ID: id, MissionID: uuidv7.MustBytes(), CoPilotID: uuidv7.MustBytes(), CreatedAt: now, UpdatedAt: now}, nil
+			},
+		})
+		code, _ = doReqFD(t, newFlightDataApp(hUpdateErr), http.MethodPatch, "/flight-data/"+id, []byte(body))
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+
+		hUpdateFKErr := NewFlightDataHandler(&flightDataServiceMock{
+			updateFn: func(context.Context, *flightdata.FlightData) error {
+				return &mysqldriver.MySQLError{
+					Number:  1452,
+					Message: "Cannot add or update a child row: a foreign key constraint fails (`wucher`.`flight_data`, CONSTRAINT `fk_flight_data_from_hospital` FOREIGN KEY (`from_hospital_id`) REFERENCES `hospitals` (`id`) ON DELETE SET NULL ON UPDATE CASCADE)",
+				}
+			},
+			getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+				now := time.Now().UTC()
+				return &flightdata.FlightData{ID: id, MissionID: uuidv7.MustBytes(), CoPilotID: uuidv7.MustBytes(), CreatedAt: now, UpdatedAt: now}, nil
+			},
+		})
+		code, _ = doReqFD(t, newFlightDataApp(hUpdateFKErr), http.MethodPatch, "/flight-data/"+id, []byte(body))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+
+		hUpdateOK := NewFlightDataHandler(&flightDataServiceMock{
+			updateFn: func(_ context.Context, row *flightdata.FlightData) error {
+				if row.CreatedAt.IsZero() {
+					t.Fatal("expected created_at preserved on update")
+				}
+				row.UpdatedAt = time.Now().UTC()
+				return nil
+			},
+			getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+				now := time.Now().UTC()
+				return &flightdata.FlightData{ID: id, MissionID: uuidv7.MustBytes(), CoPilotID: uuidv7.MustBytes(), CreatedAt: now, UpdatedAt: now}, nil
+			},
+		})
+		code, _ = doReqFD(t, newFlightDataApp(hUpdateOK), http.MethodPatch, "/flight-data/"+id, []byte(body))
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+
+		hDeleteBadID := NewFlightDataHandler(&flightDataServiceMock{})
+		code, _ = doReqFD(t, newFlightDataApp(hDeleteBadID), http.MethodDelete, "/flight-data/bad", nil)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+
+		hDeleteErr := NewFlightDataHandler(&flightDataServiceMock{
+			deleteFn: func(context.Context, []byte, []byte) error { return errors.New("x") },
+		})
+		code, _ = doReqFD(t, newFlightDataApp(hDeleteErr), http.MethodDelete, "/flight-data/"+id, nil)
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+
+		hDeleteOK := NewFlightDataHandler(&flightDataServiceMock{
+			deleteFn: func(context.Context, []byte, []byte) error { return nil },
+		})
+		code, bodyResp := doReqFD(t, newFlightDataApp(hDeleteOK), http.MethodDelete, "/flight-data/"+id, nil)
+		if code != http.StatusOK || !strings.Contains(bodyResp, `"deleted":true`) {
+			t.Fatalf("expected 200 deleted response got %d body=%s", code, bodyResp)
+		}
+	})
+
+	t.Run("helpers and mappings", func(t *testing.T) {
+		if r := missionRefFlightData(nil); r != nil {
+			t.Fatal("expected nil")
+		}
+		if r := coPilotRefFlightData(nil); r != nil {
+			t.Fatal("expected nil")
+		}
+		if r := fromLocationRefFlightData(nil); r != nil {
+			t.Fatal("expected nil")
+		}
+		if r := toLocationRefFlightData(nil); r != nil {
+			t.Fatal("expected nil")
+		}
+		r1 := missionRefFlightData(&flightdata.FlightData{MissionID: uuidv7.MustBytes()})
+		if r1 == nil || r1.ID == "" {
+			t.Fatal("expected mission id ref")
+		}
+		r2 := coPilotRefFlightData(&flightdata.FlightData{CoPilotID: uuidv7.MustBytes()})
+		if r2 == nil || r2.ID == "" {
+			t.Fatal("expected pilot id ref")
+		}
+		if missionRefFlightData(&flightdata.FlightData{}) != nil {
+			t.Fatal("expected nil ref for empty")
+		}
+		fromHosp := fromLocationRefFlightData(&flightdata.FlightData{FromHospital: &hospitaldomain.Hospital{ID: uuidv7.MustBytes(), Name: " x "}})
+		if fromHosp == nil || fromHosp.Name != "x" {
+			t.Fatal("expected hospital from")
+		}
+		fromID := fromLocationRefFlightData(&flightdata.FlightData{FromICAOID: uuidv7.MustBytes()})
+		if fromID == nil || fromID.ID == "" {
+			t.Fatal("expected from id")
+		}
+		fromID2 := fromLocationRefFlightData(&flightdata.FlightData{FromHospitalID: uuidv7.MustBytes()})
+		if fromID2 == nil || fromID2.ID == "" {
+			t.Fatal("expected from hospital id")
+		}
+		toIcao := toLocationRefFlightData(&flightdata.FlightData{ToICAO: &icaodomain.ICAO{ID: uuidv7.MustBytes(), ICAOCode: " WIII "}})
+		if toIcao == nil || toIcao.Code != "WIII" {
+			t.Fatal("expected to icao")
+		}
+		toID := toLocationRefFlightData(&flightdata.FlightData{ToICAOID: uuidv7.MustBytes()})
+		if toID == nil || toID.ID == "" {
+			t.Fatal("expected to id")
+		}
+		toID2 := toLocationRefFlightData(&flightdata.FlightData{ToHospitalID: uuidv7.MustBytes()})
+		if toID2 == nil || toID2.ID == "" {
+			t.Fatal("expected to hospital id")
+		}
+
+		if _, errObj := parseRequiredUUID(" ", "/x"); errObj == nil {
+			t.Fatal("expected required err")
+		}
+		if _, errObj := parseRequiredUUID("bad", "/x"); errObj == nil {
+			t.Fatal("expected invalid uuid err")
+		}
+		if id, errObj := parseRequiredUUID(mustUUIDStringHospital(t, uuidv7.MustBytes()), "/x"); errObj != nil || len(id) != 16 {
+			t.Fatal("expected valid id")
+		}
+		if _, errObj := parseOptionalUUIDFlightData(nil, "/x"); errObj != nil {
+			t.Fatal("expected nil err")
+		}
+		raw := " "
+		if id, errObj := parseOptionalUUIDFlightData(&raw, "/x"); errObj != nil || id != nil {
+			t.Fatal("expected nil")
+		}
+		raw = "bad"
+		if _, errObj := parseOptionalUUIDFlightData(&raw, "/x"); errObj == nil {
+			t.Fatal("expected err")
+		}
+		raw = mustUUIDStringHospital(t, uuidv7.MustBytes())
+		if id, errObj := parseOptionalUUIDFlightData(&raw, "/x"); errObj != nil || len(id) != 16 {
+			t.Fatal("expected valid optional uuid")
+		}
+		if _, errObj := parseRFC3339("bad", "/x"); errObj == nil {
+			t.Fatal("expected err")
+		}
+		if _, errObj := parseRFC3339("2026-04-20T08:00:00Z", "/x"); errObj != nil {
+			t.Fatal("expected ok")
+		}
+
+		app := fiber.New()
+		_ = app.Get("/", func(c *fiber.Ctx) error {
+			if err := writeFlightDataServiceError(c, flightdata.ErrDestinationLocationReference); err != nil {
+				return err
+			}
+			return nil
+		})
+		code, _ := doReqFD(t, app, http.MethodGet, "/", nil)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		app2 := fiber.New()
+		_ = app2.Get("/", func(c *fiber.Ctx) error { return writeFlightDataServiceError(c, flightdata.ErrRequired) })
+		code, _ = doReqFD(t, app2, http.MethodGet, "/", nil)
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+
+		app3 := fiber.New()
+		_ = app3.Get("/", func(c *fiber.Ctx) error {
+			return writeFlightDataServiceError(c, errors.Join(
+				errors.New("wrapped service error"),
+				&mysqldriver.MySQLError{
+					Number:  1452,
+					Message: "Cannot add or update a child row: a foreign key constraint fails (`wucher`.`flight_data`, CONSTRAINT `fk_flight_data_to_hospital` FOREIGN KEY (`to_hospital_id`) REFERENCES `hospitals` (`id`) ON DELETE SET NULL ON UPDATE CASCADE)",
+				},
+			))
+		})
+		code, body := doReqFD(t, app3, http.MethodGet, "/", nil)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d body=%s", code, body)
+		}
+		if !strings.Contains(body, `"pointer":"/data/attributes/to_hospital_id"`) {
+			t.Fatalf("expected mapped destination pointer, got %s", body)
+		}
+
+		svc := &flightDataServiceMock{
+			getSpoFn: func(context.Context, []byte) (*flightdata.SPODetails, error) {
+				flightID := uuidv7.MustBytes()
+				slingID := uuidv7.MustBytes()
+				return &flightdata.SPODetails{
+					HESLO: flightdata.SPOHESLODetails{
+						Flights: []flightdata.SPOHESLOFlight{{ID: flightID, FuelTruckID: uuidv7.MustBytes(), FuelTruckName: " a ", LoggingSlingID: uuidv7.MustBytes(), LoggingSlingName: " b "}},
+						Slings:  []flightdata.SPOHESLOSling{{ID: uuidv7.MustBytes(), HESLOFlightID: flightID, SlingID: slingID, SlingName: " c "}},
+					},
+					Logging: flightdata.SPOLoggingDetails{
+						Slings: []flightdata.SPOLoggingSling{{ID: uuidv7.MustBytes(), SlingID: uuidv7.MustBytes(), SlingName: " d "}},
+					},
+					HEC: flightdata.SPOHECDetails{
+						Flights: []flightdata.SPOHECFlight{{ID: uuidv7.MustBytes(), EquipmentID: uuidv7.MustBytes(), EquipmentName: " e "}},
+						Slings:  []flightdata.SPOHECSling{{ID: uuidv7.MustBytes(), SlingID: uuidv7.MustBytes(), SlingName: " f "}},
+						Loads:   []flightdata.SPOHECLoad{{ID: uuidv7.MustBytes(), LoadCategory: " g ", Quantity: 1}},
+					},
+				}, nil
+			},
+		}
+		h := NewFlightDataHandler(svc)
+		app4 := fiber.New()
+		_ = app4.Get("/", func(c *fiber.Ctx) error {
+			row := &flightdata.FlightData{ID: uuidv7.MustBytes(), Mission: &missiondomain.Mission{Type: "SPO"}, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}
+			heslo, _, _, err := h.buildSPODetails(c, row)
+			if err != nil {
+				return err
+			}
+			if heslo == nil || len(heslo.Flights) != 1 || len(heslo.Flights[0].Slings) != 1 {
+				return errors.New("unexpected heslo response shape")
+			}
+			_, _, _, _ = h.buildSPODetails(c, &flightdata.FlightData{})
+			_, _, _, _ = h.buildSPODetails(c, &flightdata.FlightData{ID: []byte{1}, Mission: &missiondomain.Mission{Type: "SPO"}})
+			return c.SendStatus(http.StatusOK)
+		})
+		code, _ = doReqFD(t, app4, http.MethodGet, "/", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+	})
+
+	t.Run("create full optional coverage", func(t *testing.T) {
+		h := NewFlightDataHandler(&flightDataServiceMock{
+			createFn: func(_ context.Context, row *flightdata.FlightData) error {
+				row.ID = uuidv7.MustBytes()
+				row.CreatedAt = time.Now().UTC()
+				row.UpdatedAt = row.CreatedAt
+				return nil
+			},
+			getByIDFn: func(context.Context, []byte) (*flightdata.FlightData, error) { return nil, errors.New("x") },
+		})
+		body := `{"data":{"type":"flight_data","attributes":{"mission_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","co_pilot_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","flight_take_off":"2026-04-20T08:00:00Z","flight_landing":"2026-04-20T09:00:00Z","flight_duration_seconds":3600,"flight_red_seconds":10,"max_n1":1.2,"max_n2":2.3,"pax_count":4,"landing_count":2,"rotor_brake_cycle":3,"hook_releases":5,"ticket_no":" A ","engine":" B ","delivery_note_number":" C ","customer_name":" D ","flight_plan_distance":1.2,"flight_plan_time_seconds":100,"flight_plan_true_course":2.4,"fuel_before_flight":1.1,"fuel_upload":2.2,"fuel_after_flight":3.3,"fuel_planning":4.4,"other_information":" E "}}}`
+		code, _ := doReqFD(t, newFlightDataApp(h), http.MethodPost, "/flight-data", []byte(body))
+		if code != http.StatusCreated {
+			t.Fatalf("expected 201 got %d", code)
+		}
+	})
+
+	t.Run("list and datatable", func(t *testing.T) {
+		now := time.Date(2026, 6, 4, 10, 44, 36, 0, time.UTC)
+		rowID := uuidv7.MustBytes()
+		h := NewFlightDataHandler(&flightDataServiceMock{
+			listFn: func(context.Context, string, []byte, []byte, int, int) ([]flightdata.FlightData, int64, error) {
+				return []flightdata.FlightData{{
+					ID:        rowID,
+					MissionID: uuidv7.MustBytes(),
+					CoPilotID: uuidv7.MustBytes(),
+					CreatedAt: now,
+					UpdatedAt: now,
+				}}, 1, nil
+			},
+		})
+		code, body := doReqFD(t, newFlightDataApp(h), http.MethodGet, "/flight-data/get-all?date=2026-06-04", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d body=%s", code, body)
+		}
+		if !strings.Contains(body, `"total":1`) {
+			t.Fatalf("expected total meta, got %s", body)
+		}
+		if !strings.Contains(body, `"type":"flight_data"`) {
+			t.Fatalf("expected flight_data item, got %s", body)
+		}
+
+		code, body = doReqFD(t, newFlightDataApp(h), http.MethodGet, "/flight-data/get-all/dt?date=bad", nil)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d body=%s", code, body)
+		}
+	})
+}
diff --git a/internal/transport/http/handlers/flight_handler.go b/internal/transport/http/handlers/flight_handler.go
new file mode 100644
index 0000000..fde00a1
--- /dev/null
+++ b/internal/transport/http/handlers/flight_handler.go
@@ -0,0 +1,1079 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	authdomain "wucher/internal/domain/auth"
+	"wucher/internal/domain/flight"
+	flightdata "wucher/internal/domain/flight_data"
+	fmreport "wucher/internal/domain/fm_report"
+	helicopterdomain "wucher/internal/domain/helicopter"
+	"wucher/internal/domain/mission"
+	reserveac "wucher/internal/domain/reserve_ac"
+	"wucher/internal/service"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/appctx"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/reserveacutil"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type FlightHandler struct {
+	svc                   flight.FlightService
+	afterFlightInspection afterflightinspection.Service
+	fmReport              fmreport.Service
+	takeover              takeoverLookupService
+	reserveAc             reserveac.ReserveAcService
+	helicopter            helicopterdomain.Service
+	mission               mission.Service
+	flightData            flightdata.Service
+	auth                  *service.AuthService
+	validate              *validators.Validator
+}
+
+func NewFlightHandler(svc flight.FlightService) *FlightHandler {
+	return &FlightHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+func (h *FlightHandler) WithReserveAcService(reserveAcSvc reserveac.ReserveAcService) *FlightHandler {
+	h.reserveAc = reserveAcSvc
+	return h
+}
+
+func (h *FlightHandler) WithAfterFlightInspectionService(afterSvc afterflightinspection.Service) *FlightHandler {
+	h.afterFlightInspection = afterSvc
+	return h
+}
+
+func (h *FlightHandler) WithFMReportService(reportSvc fmreport.Service) *FlightHandler {
+	h.fmReport = reportSvc
+	return h
+}
+
+func (h *FlightHandler) WithTakeoverService(takeoverSvc takeoverLookupService) *FlightHandler {
+	h.takeover = takeoverSvc
+	return h
+}
+
+func (h *FlightHandler) WithHelicopterService(heliSvc helicopterdomain.Service) *FlightHandler {
+	h.helicopter = heliSvc
+	return h
+}
+
+func (h *FlightHandler) WithMissionService(missionSvc mission.Service) *FlightHandler {
+	h.mission = missionSvc
+	return h
+}
+
+func (h *FlightHandler) WithFlightDataService(flightDataSvc flightdata.Service) *FlightHandler {
+	h.flightData = flightDataSvc
+	return h
+}
+
+func (h *FlightHandler) WithAuthService(authSvc *service.AuthService) *FlightHandler {
+	h.auth = authSvc
+	return h
+}
+
+// Create keeps internal compatibility but is no longer exposed as public HTTP route.
+func (h *FlightHandler) Create(c *fiber.Ctx) error {
+	var req requestdto.FlightCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFlightErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeFlightErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	date, err := time.Parse("2006-01-02", strings.TrimSpace(req.Data.Attributes.Date))
+	if err != nil {
+		return writeFlightErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "date must be YYYY-MM-DD",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/date"},
+		}})
+	}
+	if _, errObj := parseOptionalUUIDFlight(req.Data.Attributes.DutyRosterID, "/data/attributes/duty_roster_id"); errObj != nil {
+		return writeFlightErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	if _, errObj := parseOptionalUUIDFlight(req.Data.Attributes.ReserveAcID, "/data/attributes/reserve_ac_id"); errObj != nil {
+		return writeFlightErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	row := &flight.Flight{
+		Date:      date.UTC(),
+		CreatedBy: actorUserID(c),
+		UpdatedBy: actorUserID(c),
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeFlightErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, h.flightMutationResource(c.UserContext(), created))
+	}
+	return response.Write(c, fiber.StatusCreated, h.flightMutationResource(c.UserContext(), row))
+}
+
+// GetFlightsByAuthUser godoc
+// @Summary Get flights for current auth user (from duty roster assignment)
+// @Tags Flight
+// @Produce json
+// @Description Returns flights assigned to current auth user, including workflow steps (`duty_roster`, `reserve_ac`, `mission`, `after_flight_inspection`, `fm_report`).
+// @Description Each step includes `status`, `completed_at`, and `completed_by` for consistent FE rendering.
+// @Param page[number] query int false "Page number"
+// @Param page[size] query int false "Page size"
+// @Param page query int false "Page number (fallback)"
+// @Param size query int false "Page size (fallback)"
+// @Param limit query int false "Page size override"
+// @Success 200 {object} responsedto.FlightListResponse
+// @Failure 401 {object} jsonapi.ErrorDocument
+// @Router /api/v1/flights/get [get]
+func (h *FlightHandler) GetByAuthUser(c *fiber.Ctx) error {
+	userID := actorUserID(c)
+	if len(userID) == 0 {
+		return writeFlightErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	rows, total, err := h.svc.ListByUserID(c.UserContext(), userID, pageSize, offset)
+	if err != nil {
+		return writeFlightErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	missionsByFlightID, err := h.prefetchMissionsByFlightID(c.UserContext(), rows)
+	if err != nil {
+		return writeFlightErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	dailyInspectionCache := make(map[string]*responsedto.FlightDailyInspectionSummary)
+	afterFlightCache := make(map[string]responsedto.FlightStepItem)
+	fmReportCache := make(map[string]responsedto.FlightStepItem)
+
+	data := make([]responsedto.FlightResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, h.flightResourceForList(c.UserContext(), c, &rows[i], missionsByFlightID[string(rows[i].ID)], dailyInspectionCache, afterFlightCache, fmReportCache))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{
+		"total": total,
+	})
+}
+
+// ListFlights godoc
+// @Summary List flights
+// @Description Supports `search`, `filter[search]`, `sort`, `page[number]`, `page[size]`, `page`, `size`, and `limit`.
+// @Description Supports `date` and `filter[date]` for exact flight date filtering (`YYYY-MM-DD`).
+// @Description Returns paginated flights with workflow steps (`takeover`, `mission`, `after_flight_inspection`, `fm_report`).
+// @Description Each step includes `status`, `completed_at`, and `completed_by` for consistent FE rendering.
+// @Tags Flight
+// @Produce json
+// @Param search query string false "Search text"
+// @Param filter[search] query string false "Search text (JSON:API style)"
+// @Param date query string false "Filter by flight date (YYYY-MM-DD)"
+// @Param filter[date] query string false "Filter by flight date (YYYY-MM-DD) (JSON:API style)"
+// @Param sort query string false "Sort field"
+// @Param page[number] query int false "Page number"
+// @Param page[size] query int false "Page size"
+// @Param page query int false "Page number (fallback)"
+// @Param size query int false "Page size (fallback)"
+// @Param limit query int false "Page size override"
+// @Success 200 {object} responsedto.FlightListResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/flights/get-all [get]
+func (h *FlightHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("search")
+	}
+	dateFilter := strings.TrimSpace(c.Query("filter[date]"))
+	if dateFilter == "" {
+		dateFilter = strings.TrimSpace(c.Query("date"))
+	}
+	if dateFilter != "" {
+		if _, err := time.Parse("2006-01-02", dateFilter); err != nil {
+			return writeFlightErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "date must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: "/date"},
+			}})
+		}
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+	rows, total, err := h.listFlightsForCurrentUser(c, filter, dateFilter, sort, 0, 0)
+	if err != nil {
+		return writeFlightErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]responsedto.FlightResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, h.flightResource(c.UserContext(), c, &rows[i]))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{
+		"total": total,
+	})
+}
+
+func (h *FlightHandler) listFlightsForCurrentUser(c *fiber.Ctx, filter, date, sort string, limit, offset int) ([]flight.Flight, int64, error) {
+	if h == nil || h.svc == nil {
+		return nil, 0, errors.New("flight service not configured")
+	}
+	if h.auth == nil {
+		return h.svc.List(c.UserContext(), filter, date, sort, limit, offset)
+	}
+	userID := appctx.GetUserID(c.UserContext())
+	if len(userID) == 0 {
+		return nil, 0, errors.New("missing auth context")
+	}
+	user, err := h.auth.GetUserByID(c.UserContext(), userID)
+	if err != nil {
+		return nil, 0, err
+	}
+	if user == nil {
+		return nil, 0, errors.New("user not found")
+	}
+	if flightUserHasRole(user, "admin") {
+		return h.svc.List(c.UserContext(), filter, date, sort, limit, offset)
+	}
+	return h.svc.ListByCreatedBy(c.UserContext(), userID, filter, date, sort, limit, offset)
+}
+
+func flightUserHasRole(user *authdomain.User, roleName string) bool {
+	if user == nil {
+		return false
+	}
+	for i := range user.Roles {
+		if strings.EqualFold(strings.TrimSpace(user.Roles[i].Name), roleName) {
+			return true
+		}
+	}
+	return false
+}
+
+func (h *FlightHandler) flightResource(ctx context.Context, c *fiber.Ctx, row *flight.Flight) responsedto.FlightResource {
+	missionStep := flightMissionStep(row)
+	takeoverStep := flightTakeoverStep(c.Context(), row, h.takeover)
+	afterFlightInspectionStep := h.flightAfterFlightInspectionStep(ctx, row)
+	fmReportStep := h.flightFMReportStep(ctx, row)
+	var takeover *responsedto.FlightTakeoverSummary
+	var draft []responsedto.FlightDraftGroup
+	totalDraft := 0
+	if row != nil && len(row.TakeoverAcID) == 16 {
+		takeover = flightTakeoverSummary(ctx, h.reserveAc, row)
+		if takeover == nil {
+			takeover = &responsedto.FlightTakeoverSummary{}
+		}
+		takeover.ID = idString(row.TakeoverAcID)
+		takeover.Helicopter = h.helicopterSummaryFromTakeover(ctx, row)
+		takeover.RosterDetail = h.takeoverRosterDetailSummary(ctx, row)
+	}
+	missionID := ""
+	if h != nil && h.mission != nil && row != nil && len(row.ID) == 16 {
+		rows, err := h.mission.ListByFlightID(ctx, row.ID)
+		if err == nil && len(rows) > 0 {
+			missionID = idString(rows[0].ID)
+			grouped := make(map[string][]responsedto.FlightDraftItem)
+			summaries := make(map[string]responsedto.FlightMissionTypeSummary)
+			missionComplete := true
+			var completedAt time.Time
+			var completedBy []byte
+			for i := range rows {
+				rowComplete := h.missionFlightDataComplete(ctx, rows[i].ID)
+				if !rowComplete {
+					missionComplete = false
+				}
+				if rowComplete && rows[i].UpdatedAt.After(completedAt) {
+					completedAt = rows[i].UpdatedAt
+					completedBy = rows[i].UpdatedBy
+				}
+				missionType := strings.ToUpper(strings.TrimSpace(rows[i].Type))
+				status := mission.StatusDraft
+				if rowComplete {
+					status = mission.StatusCompleted
+				}
+				grouped[missionType] = append(grouped[missionType], responsedto.FlightDraftItem{
+					ID:           idString(rows[i].ID),
+					Type:         missionType,
+					Status:       status,
+					FlightDataID: idString(rows[i].FlightDataID),
+				})
+				sum := summaries[missionType]
+				sum.Type = missionType
+				sum.Draft++
+				if status == mission.StatusCompleted {
+					sum.Completed++
+				}
+				summaries[missionType] = sum
+			}
+			for _, missionType := range []string{sharedconst.MissionTypeHEMS, sharedconst.MissionTypeCAT, sharedconst.MissionTypeSPO, sharedconst.MissionTypeNCO} {
+				items := grouped[missionType]
+				if len(items) == 0 {
+					continue
+				}
+				draft = append(draft, responsedto.FlightDraftGroup{
+					Type:  missionType,
+					Items: items,
+				})
+				totalDraft += len(items)
+			}
+			missionStep.ID = missionID
+			missionStep.Status = "in_progress"
+			if missionComplete {
+				missionStep.Status = "completed"
+			}
+			missionStep.Complete = missionComplete
+			if missionComplete && !completedAt.IsZero() {
+				missionStep.CompletedAt = completedAt.UTC().Format(time.RFC3339)
+				missionStep.CompletedBy = userctx.GetDisplayName(ctx, completedBy)
+			}
+			missionStep.MissionType = make([]responsedto.FlightMissionTypeSummary, 0, len(draft))
+			for _, missionType := range []string{sharedconst.MissionTypeHEMS, sharedconst.MissionTypeCAT, sharedconst.MissionTypeSPO, sharedconst.MissionTypeNCO} {
+				if sum, ok := summaries[missionType]; ok {
+					missionStep.MissionType = append(missionStep.MissionType, sum)
+				}
+			}
+		}
+	}
+	steps := []responsedto.FlightStepItem{missionStep}
+	if row != nil && len(row.TakeoverAcID) == 16 {
+		steps = []responsedto.FlightStepItem{takeoverStep, missionStep}
+		if afterFlightInspectionStep.Phase != "" {
+			steps = append(steps, afterFlightInspectionStep)
+		}
+		if fmReportStep.Phase != "" {
+			steps = append(steps, fmReportStep)
+		}
+	}
+
+	updatedAt, updatedBy := updatedAuditOrCreated(row.UpdatedAt, row.CreatedAt, row.UpdatedBy, row.UpdatedByName, row.CreatedBy, row.CreatedByName)
+	return responsedto.FlightResource{
+		Type: "flight",
+		ID:   idString(row.ID),
+		Attributes: responsedto.FlightAttributes{
+			MissionID:  missionID,
+			Code:       stringPtrOrEmpty(row.MissionCode),
+			Date:       row.Date.UTC().Format("2006-01-02"),
+			TotalDraft: totalDraft,
+			Takeover:   takeover,
+			Steps:      steps,
+			Draft:      draft,
+			CreatedAt:  row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:  userRef(row.CreatedBy, row.CreatedByName),
+			UpdatedAt:  updatedAt,
+			UpdatedBy:  updatedBy,
+			DeletedAt:  timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:  userRef(row.DeletedBy, ""),
+		},
+	}
+}
+
+func (h *FlightHandler) flightResourceForList(ctx context.Context, c *fiber.Ctx, row *flight.Flight, missions []mission.Mission, dailyInspectionCache map[string]*responsedto.FlightDailyInspectionSummary, afterFlightCache map[string]responsedto.FlightStepItem, fmReportCache map[string]responsedto.FlightStepItem) responsedto.FlightResource {
+	missionStep := flightMissionStep(row)
+	takeoverStep := flightTakeoverStep(c.Context(), row, nil)
+	afterFlightInspectionStep := h.flightAfterFlightInspectionStepCached(ctx, row, afterFlightCache)
+	fmReportStep := h.flightFMReportStepCached(ctx, row, fmReportCache)
+	var takeover *responsedto.FlightTakeoverSummary
+	var draft []responsedto.FlightDraftGroup
+	totalDraft := 0
+	if row != nil && len(row.TakeoverAcID) == 16 {
+		takeover = flightTakeoverSummaryForList(ctx, h.reserveAc, row, dailyInspectionCache)
+		if takeover == nil {
+			takeover = &responsedto.FlightTakeoverSummary{}
+		}
+		takeover.ID = idString(row.TakeoverAcID)
+		takeover.Helicopter = h.helicopterSummaryFromTakeoverForList(ctx, row)
+		takeover.RosterDetail = h.takeoverRosterDetailSummary(ctx, row)
+	}
+	missionID := ""
+	if len(missions) > 0 {
+		missionID = idString(missions[0].ID)
+		grouped := make(map[string][]responsedto.FlightDraftItem)
+		summaries := make(map[string]responsedto.FlightMissionTypeSummary)
+		missionComplete := true
+		var completedAt time.Time
+		var completedBy []byte
+		for i := range missions {
+			rowComplete := strings.EqualFold(strings.TrimSpace(missions[i].FlightDataStatus), flightdata.StatusCompleted)
+			if !rowComplete {
+				missionComplete = false
+			}
+			if rowComplete && missions[i].UpdatedAt.After(completedAt) {
+				completedAt = missions[i].UpdatedAt
+				completedBy = missions[i].UpdatedBy
+			}
+			missionType := strings.ToUpper(strings.TrimSpace(missions[i].Type))
+			status := mission.StatusDraft
+			if rowComplete {
+				status = mission.StatusCompleted
+			}
+			grouped[missionType] = append(grouped[missionType], responsedto.FlightDraftItem{
+				ID:           idString(missions[i].ID),
+				Type:         missionType,
+				Status:       status,
+				FlightDataID: idString(missions[i].FlightDataID),
+			})
+			sum := summaries[missionType]
+			sum.Type = missionType
+			sum.Draft++
+			if status == mission.StatusCompleted {
+				sum.Completed++
+			}
+			summaries[missionType] = sum
+		}
+		for _, missionType := range []string{sharedconst.MissionTypeHEMS, sharedconst.MissionTypeCAT, sharedconst.MissionTypeSPO, sharedconst.MissionTypeNCO} {
+			items := grouped[missionType]
+			if len(items) == 0 {
+				continue
+			}
+			draft = append(draft, responsedto.FlightDraftGroup{
+				Type:  missionType,
+				Items: items,
+			})
+			totalDraft += len(items)
+		}
+		missionStep.ID = missionID
+		missionStep.Status = "in_progress"
+		if missionComplete {
+			missionStep.Status = "completed"
+		}
+		missionStep.Complete = missionComplete
+		if missionComplete && !completedAt.IsZero() {
+			missionStep.CompletedAt = completedAt.UTC().Format(time.RFC3339)
+			missionStep.CompletedBy = userctx.GetDisplayName(ctx, completedBy)
+		}
+		missionStep.MissionType = make([]responsedto.FlightMissionTypeSummary, 0, len(draft))
+		for _, missionType := range []string{sharedconst.MissionTypeHEMS, sharedconst.MissionTypeCAT, sharedconst.MissionTypeSPO, sharedconst.MissionTypeNCO} {
+			if sum, ok := summaries[missionType]; ok {
+				missionStep.MissionType = append(missionStep.MissionType, sum)
+			}
+		}
+	}
+	steps := []responsedto.FlightStepItem{missionStep}
+	if row != nil && len(row.TakeoverAcID) == 16 {
+		steps = []responsedto.FlightStepItem{takeoverStep, missionStep}
+		if afterFlightInspectionStep.Phase != "" {
+			steps = append(steps, afterFlightInspectionStep)
+		}
+		if fmReportStep.Phase != "" {
+			steps = append(steps, fmReportStep)
+		}
+	}
+
+	updatedAt, updatedBy := updatedAuditOrCreated(row.UpdatedAt, row.CreatedAt, row.UpdatedBy, row.UpdatedByName, row.CreatedBy, row.CreatedByName)
+	return responsedto.FlightResource{
+		Type: "flight",
+		ID:   idString(row.ID),
+		Attributes: responsedto.FlightAttributes{
+			MissionID:  missionID,
+			Code:       stringPtrOrEmpty(row.MissionCode),
+			Date:       row.Date.UTC().Format("2006-01-02"),
+			TotalDraft: totalDraft,
+			Takeover:   takeover,
+			Steps:      steps,
+			Draft:      draft,
+			CreatedAt:  row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:  userRef(row.CreatedBy, row.CreatedByName),
+			UpdatedAt:  updatedAt,
+			UpdatedBy:  updatedBy,
+			DeletedAt:  timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:  userRef(row.DeletedBy, ""),
+		},
+	}
+}
+
+func (h *FlightHandler) prefetchMissionsByFlightID(ctx context.Context, rows []flight.Flight) (map[string][]mission.Mission, error) {
+	if h == nil || h.mission == nil || len(rows) == 0 {
+		return map[string][]mission.Mission{}, nil
+	}
+	flightIDs := make([][]byte, 0, len(rows))
+	for i := range rows {
+		if len(rows[i].ID) == 16 {
+			flightIDs = append(flightIDs, rows[i].ID)
+		}
+	}
+	if len(flightIDs) == 0 {
+		return map[string][]mission.Mission{}, nil
+	}
+	missions, err := h.mission.ListByFlightIDs(ctx, flightIDs)
+	if err != nil {
+		return nil, err
+	}
+	grouped := make(map[string][]mission.Mission, len(flightIDs))
+	for i := range missions {
+		key := string(missions[i].FlightID)
+		grouped[key] = append(grouped[key], missions[i])
+	}
+	return grouped, nil
+}
+
+func (h *FlightHandler) flightAfterFlightInspectionStepCached(ctx context.Context, row *flight.Flight, cache map[string]responsedto.FlightStepItem) responsedto.FlightStepItem {
+	if row == nil || row.Takeover == nil || row.Takeover.ReserveAc == nil || row.Takeover.ReserveAc.Inspection == nil || len(row.Takeover.ReserveAc.Inspection.ID) != 16 {
+		return responsedto.FlightStepItem{}
+	}
+	inspectionID := string(row.Takeover.ReserveAc.Inspection.ID)
+	if cache != nil {
+		if step, ok := cache[inspectionID]; ok {
+			return step
+		}
+	}
+	step := h.flightAfterFlightInspectionStep(ctx, row)
+	if cache != nil {
+		cache[inspectionID] = step
+	}
+	return step
+}
+
+func (h *FlightHandler) flightFMReportStepCached(ctx context.Context, row *flight.Flight, cache map[string]responsedto.FlightStepItem) responsedto.FlightStepItem {
+	if row == nil || row.Takeover == nil || len(row.ID) != 16 {
+		return responsedto.FlightStepItem{}
+	}
+	flightID := string(row.ID)
+	if cache != nil {
+		if step, ok := cache[flightID]; ok {
+			return step
+		}
+	}
+	step := h.flightFMReportStep(ctx, row)
+	if cache != nil {
+		cache[flightID] = step
+	}
+	return step
+}
+
+func flightTakeoverSummaryForList(ctx context.Context, reserveAcSvc reserveac.ReserveAcService, row *flight.Flight, cache map[string]*responsedto.FlightDailyInspectionSummary) *responsedto.FlightTakeoverSummary {
+	if row == nil || row.Takeover == nil {
+		return nil
+	}
+	reserveRow := row.Takeover.ReserveAc
+	if reserveRow == nil || len(reserveRow.AircraftID) == 0 {
+		if reserveAcSvc == nil || len(row.Takeover.ReserveAcID) != 16 {
+			return nil
+		}
+		var err error
+		reserveRow, err = reserveAcSvc.GetByID(ctx, row.Takeover.ReserveAcID)
+		if err != nil || reserveRow == nil || len(reserveRow.AircraftID) == 0 {
+			return nil
+		}
+	}
+	out := &responsedto.FlightTakeoverSummary{}
+	heliID := string(reserveRow.AircraftID)
+	if cache != nil {
+		if daily, ok := cache[heliID]; ok {
+			out.DailyInspection = daily
+		}
+	}
+	if out.DailyInspection == nil && reserveAcSvc != nil {
+		lastDaily, _ := reserveAcSvc.GetLastDailyInspectionByHelicopterID(ctx, reserveRow.AircraftID)
+		if lastDaily != nil {
+			out.DailyInspection = &responsedto.FlightDailyInspectionSummary{
+				ID:        idString(lastDaily.ID),
+				Name:      strings.TrimSpace(lastDaily.Name),
+				ShortName: strings.TrimSpace(lastDaily.ShortName),
+				Date:      lastDaily.At.UTC().Format("02.01.2006"),
+				UTCTime:   lastDaily.At.UTC().Format("15:04"),
+			}
+			if cache != nil {
+				cache[heliID] = out.DailyInspection
+			}
+		}
+	}
+	return out
+}
+
+func (h *FlightHandler) helicopterSummaryFromTakeoverForList(ctx context.Context, row *flight.Flight) *responsedto.FlightHelicopterSummary {
+	if row == nil || row.Takeover == nil || row.Takeover.ReserveAc == nil {
+		return h.helicopterSummaryFromTakeover(ctx, row)
+	}
+	reserveRow := row.Takeover.ReserveAc
+	if reserveRow.Aircraft == nil {
+		return h.helicopterSummaryFromTakeover(ctx, row)
+	}
+	heliRow := reserveRow.Aircraft
+	return &responsedto.FlightHelicopterSummary{
+		AOG:         heliRow.AirOnGround,
+		Designation: strings.TrimSpace(heliRow.Designation),
+		ID:          idString(heliRow.ID),
+		Identifier:  strings.TrimSpace(heliRow.Identifier),
+		IsActive:    heliRow.IsActive,
+		Type:        strings.TrimSpace(heliRow.Type),
+	}
+}
+
+func (h *FlightHandler) missionFlightDataComplete(ctx context.Context, missionID []byte) bool {
+	if h == nil || h.flightData == nil || len(missionID) != 16 {
+		return false
+	}
+	fd, err := h.flightData.GetByMissionID(ctx, missionID)
+	if err != nil || fd == nil {
+		return false
+	}
+	return flightdata.IsComplete(fd)
+}
+
+func (h *FlightHandler) flightMutationResource(ctx context.Context, row *flight.Flight) responsedto.FlightResource {
+	if row == nil {
+		return responsedto.FlightResource{}
+	}
+	takeover := &responsedto.FlightTakeoverSummary{
+		ID: idString(row.TakeoverAcID),
+	}
+	missionID := h.flightMissionID(ctx, row)
+	updatedAt, updatedBy := updatedAuditOrCreated(row.UpdatedAt, row.CreatedAt, row.UpdatedBy, row.UpdatedByName, row.CreatedBy, row.CreatedByName)
+	return responsedto.FlightResource{
+		Type: "flight",
+		ID:   idString(row.ID),
+		Attributes: responsedto.FlightAttributes{
+			MissionID:  missionID,
+			Code:       stringPtrOrEmpty(row.MissionCode),
+			Date:       row.Date.UTC().Format("2006-01-02"),
+			TotalDraft: 0,
+			Takeover:   takeover,
+			Steps:      nil,
+			Draft:      nil,
+			CreatedAt:  row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:  userRef(row.CreatedBy, row.CreatedByName),
+			UpdatedAt:  updatedAt,
+			UpdatedBy:  updatedBy,
+			DeletedAt:  timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:  userRef(row.DeletedBy, ""),
+		},
+	}
+}
+
+func (h *FlightHandler) flightMissionID(ctx context.Context, row *flight.Flight) string {
+	if h == nil || h.mission == nil || row == nil || len(row.ID) != 16 {
+		return ""
+	}
+	rows, err := h.mission.ListByFlightID(ctx, row.ID)
+	if err != nil || len(rows) == 0 {
+		return ""
+	}
+	return idString(rows[0].ID)
+}
+
+func flightMissionStep(row *flight.Flight) responsedto.FlightStepItem {
+	if row == nil {
+		return responsedto.FlightStepItem{Phase: "mission", Step: 2, Status: "unassigned"}
+	}
+	return responsedto.FlightStepItem{Phase: "mission", Step: 2, Status: "unassigned"}
+}
+
+func (h *FlightHandler) flightAfterFlightInspectionStep(ctx context.Context, row *flight.Flight) responsedto.FlightStepItem {
+	if row == nil || row.Takeover == nil || row.Takeover.ReserveAc == nil || row.Takeover.ReserveAc.Inspection == nil || len(row.Takeover.ReserveAc.Inspection.ID) != 16 {
+		return responsedto.FlightStepItem{}
+	}
+
+	inspectionID := row.Takeover.ReserveAc.Inspection.ID
+	if h == nil || h.afterFlightInspection == nil {
+		return responsedto.FlightStepItem{}
+	}
+
+	afterRow, err := h.afterFlightInspection.GetByFlightInspectionID(ctx, inspectionID)
+	if err != nil || afterRow == nil {
+		return responsedto.FlightStepItem{}
+	}
+
+	return responsedto.FlightStepItem{
+		Phase:       "after_flight_inspection",
+		Step:        3,
+		ID:          idString(afterRow.ID),
+		Status:      "completed",
+		Complete:    true,
+		CompletedAt: timeStringOrEmptyRefTime(&afterRow.UpdatedAt),
+		CompletedBy: uuidStringOrEmpty(afterRow.UpdatedBy),
+	}
+}
+
+func (h *FlightHandler) flightFMReportStep(ctx context.Context, row *flight.Flight) responsedto.FlightStepItem {
+	if row == nil || row.Takeover == nil || h == nil || h.fmReport == nil || len(row.ID) != 16 {
+		return responsedto.FlightStepItem{}
+	}
+
+	reportRow, err := h.fmReport.GetByFlightID(ctx, row.ID)
+	if err != nil || reportRow == nil {
+		return responsedto.FlightStepItem{}
+	}
+
+	step := responsedto.FlightStepItem{
+		Phase:  "fm_report",
+		Step:   4,
+		ID:     idString(reportRow.ID),
+		Status: "in_progress",
+	}
+	if reportRow.CompletedAt != nil {
+		step.Status = "completed"
+		step.Complete = true
+		step.CompletedAt = timeStringOrEmpty(reportRow.CompletedAt)
+		step.CompletedBy = uuidStringOrEmpty(reportRow.CompletedBy)
+	}
+	return step
+}
+
+// ResolveHelicopterIDByTakeover resolves the flown aircraft's helicopter id from
+// a takeover id via takeover -> reserve_ac -> aircraft. Returns nil when it
+// cannot be resolved.
+func (h *FlightHandler) ResolveHelicopterIDByTakeover(ctx context.Context, takeoverID []byte) []byte {
+	if h == nil || h.takeover == nil || h.reserveAc == nil || len(takeoverID) != 16 {
+		return nil
+	}
+	takeoverRow, err := h.takeover.GetByID(ctx, takeoverID)
+	if err != nil || takeoverRow == nil || len(takeoverRow.ReserveAcID) != 16 {
+		return nil
+	}
+	reserveRow, err := h.reserveAc.GetByID(ctx, takeoverRow.ReserveAcID)
+	if err != nil || reserveRow == nil || len(reserveRow.AircraftID) != 16 {
+		return nil
+	}
+	return reserveRow.AircraftID
+}
+
+func (h *FlightHandler) ResolveHelicopterForReportCode(ctx context.Context, takeoverID []byte) ([]byte, string) {
+	helicopterID := h.ResolveHelicopterIDByTakeover(ctx, takeoverID)
+	if len(helicopterID) != 16 || h.helicopter == nil {
+		return nil, ""
+	}
+	heliRow, err := h.helicopter.GetByID(ctx, helicopterID)
+	if err != nil || heliRow == nil {
+		return helicopterID, ""
+	}
+	return helicopterID, strings.TrimSpace(heliRow.Identifier)
+}
+
+func (h *FlightHandler) helicopterSummaryFromTakeover(ctx context.Context, row *flight.Flight) *responsedto.FlightHelicopterSummary {
+	if row == nil || row.Takeover == nil || h == nil || h.helicopter == nil || h.reserveAc == nil {
+		return nil
+	}
+	reserveID := row.Takeover.ReserveAcID
+	if len(reserveID) != 16 {
+		return nil
+	}
+	reserveRow, err := h.reserveAc.GetByID(ctx, reserveID)
+	if err != nil || reserveRow == nil || len(reserveRow.AircraftID) != 16 {
+		return nil
+	}
+	heliRow, err := h.helicopter.GetByID(ctx, reserveRow.AircraftID)
+	if err != nil || heliRow == nil {
+		return nil
+	}
+	return &responsedto.FlightHelicopterSummary{
+		AOG:         heliRow.AirOnGround,
+		Designation: strings.TrimSpace(heliRow.Designation),
+		ID:          idString(heliRow.ID),
+		Identifier:  strings.TrimSpace(heliRow.Identifier),
+		IsActive:    heliRow.IsActive,
+		Type:        strings.TrimSpace(heliRow.Type),
+	}
+}
+
+func stringOrFallback(name string, id []byte) string {
+	if trimmed := strings.TrimSpace(name); trimmed != "" {
+		return trimmed
+	}
+	return uuidStringOrEmpty(id)
+}
+
+func flightTakeoverSummary(ctx context.Context, reserveAcSvc reserveac.ReserveAcService, row *flight.Flight) *responsedto.FlightTakeoverSummary {
+	if row == nil || reserveAcSvc == nil {
+		return nil
+	}
+	var reserveID []byte
+	if row.Takeover != nil && len(row.Takeover.ReserveAcID) == 16 {
+		reserveID = row.Takeover.ReserveAcID
+	}
+	if len(reserveID) != 16 {
+		return nil
+	}
+	reserveRow, err := reserveAcSvc.GetByID(ctx, reserveID)
+	if err != nil || reserveRow == nil || len(reserveRow.AircraftID) == 0 {
+		return nil
+	}
+	out := &responsedto.FlightTakeoverSummary{}
+	lastDaily, _ := reserveAcSvc.GetLastDailyInspectionByHelicopterID(ctx, reserveRow.AircraftID)
+	if lastDaily != nil {
+		out.DailyInspection = &responsedto.FlightDailyInspectionSummary{
+			ID:        idString(lastDaily.ID),
+			Name:      strings.TrimSpace(lastDaily.Name),
+			ShortName: strings.TrimSpace(lastDaily.ShortName),
+			Date:      lastDaily.At.UTC().Format("02.01.2006"),
+			UTCTime:   lastDaily.At.UTC().Format("15:04"),
+		}
+	}
+	return out
+}
+
+func (h *FlightHandler) takeoverRosterDetailSummary(ctx context.Context, row *flight.Flight) *responsedto.TakeoverDutyRosterDetailsResponse {
+	if h == nil || h.takeover == nil || row == nil || len(row.TakeoverAcID) != 16 {
+		return nil
+	}
+
+	takeoverRow := row.Takeover
+	if takeoverRow == nil || len(takeoverRow.RosterCrews) == 0 && len(takeoverRow.OtherPeople) == 0 {
+		loaded, err := h.takeover.GetByID(ctx, row.TakeoverAcID)
+		if err != nil || loaded == nil {
+			return nil
+		}
+		takeoverRow = loaded
+	}
+	if takeoverRow == nil {
+		return nil
+	}
+
+	resource := responsedto.DutyRosterResource{
+		Attributes: responsedto.DutyRosterAttributes{
+			Detail: responsedto.DutyRosterDetailsResponse{
+				Pilot:       []responsedto.DutyRosterPilotCrew{},
+				Doctor:      []responsedto.DutyRosterCrew{},
+				Rescuer:     []responsedto.DutyRosterCrew{},
+				Helper:      []responsedto.DutyRosterCrew{},
+				OtherPerson: []responsedto.DutyRosterCrew{},
+			},
+		},
+	}
+	resource = buildDutyRosterResourceFromTakeoverRows(resource, takeoverRow.RosterCrews, row)
+	resource = buildDutyRosterResourceFromOtherPeople(resource, takeoverRow.OtherPeople)
+
+	detail := takeoverDutyRosterDetailsFromRosterDetails(resource.Attributes.Detail)
+	return &detail
+}
+
+func flightDutyRosterStep(row *flight.Flight) responsedto.FlightStepItem {
+	if row == nil || len(row.TakeoverAcID) != 16 {
+		return responsedto.FlightStepItem{
+			Phase:  "duty_roster",
+			ID:     "",
+			Status: "unassigned",
+		}
+	}
+	return responsedto.FlightStepItem{
+		Phase:       "duty_roster",
+		Status:      "completed",
+		CompletedAt: row.CreatedAt.UTC().Format(time.RFC3339),
+		CompletedBy: uuidStringOrEmpty(row.CreatedBy),
+	}
+}
+
+func flightReserveAcStep(row *flight.Flight) responsedto.FlightStepItem {
+	if row == nil {
+		return responsedto.FlightStepItem{
+			Phase:  "reserve_ac",
+			ID:     "",
+			Status: "unassigned",
+		}
+	}
+	var reserveRow *reserveac.ReserveAc
+	var reserveID []byte
+	if row.Takeover != nil {
+		reserveRow = row.Takeover.ReserveAc
+		reserveID = row.Takeover.ReserveAcID
+	}
+	if len(reserveID) != 16 {
+		return responsedto.FlightStepItem{
+			Phase:  "reserve_ac",
+			ID:     "",
+			Status: "unassigned",
+		}
+	}
+	step := responsedto.FlightStepItem{
+		Phase:  "reserve_ac",
+		ID:     idString(reserveID),
+		Status: "in_progress",
+	}
+	status := ""
+	if reserveRow != nil {
+		status = reserveRow.Status
+	}
+	switch reserveacutil.NormalizeStatus(status) {
+	case reserveacutil.StatusApproved:
+		step.Status = "completed"
+		if reserveRow != nil && !reserveRow.UpdatedAt.IsZero() {
+			step.CompletedAt = reserveRow.UpdatedAt.UTC().Format(time.RFC3339)
+		}
+		if reserveRow != nil {
+			step.CompletedBy = uuidStringOrEmpty(reserveRow.UpdatedBy)
+		}
+	case reserveacutil.StatusOnProgress:
+		step.Status = "in_progress"
+	case reserveacutil.StatusPending:
+		step.Status = "pending"
+	default:
+		step.Status = "in_progress"
+	}
+	return step
+}
+
+func timeStringOrEmptyRefTime(v *time.Time) string {
+	if v == nil || v.IsZero() {
+		return ""
+	}
+	return v.UTC().Format(time.RFC3339)
+}
+
+func stringPtrOrEmpty(v *string) string {
+	if v == nil {
+		return ""
+	}
+	return strings.TrimSpace(*v)
+}
+
+func parseOptionalUUIDFlight(v *string, pointer string) ([]byte, *jsonapi.ErrorObject) {
+	if v == nil {
+		return nil, nil
+	}
+	raw := strings.TrimSpace(*v)
+	if raw == "" {
+		return nil, nil
+	}
+	id, err := uuidv7.ParseString(raw)
+	if err != nil {
+		return nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: strings.TrimPrefix(pointer, "/data/attributes/") + " is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	return id, nil
+}
+
+func writeFlightErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		if strings.TrimSpace(e.Code) == "" || strings.TrimSpace(e.ErrorCode) == "" {
+			code, errorCode := inferFlightErrorCode(status, e.Title, e.Detail)
+			if strings.TrimSpace(e.Code) == "" {
+				e.Code = code
+			}
+			if strings.TrimSpace(e.ErrorCode) == "" {
+				e.ErrorCode = errorCode
+			}
+		}
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferFlightErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusUnauthorized:
+		return apperrorsx.CodeFlightUnauthorized, apperrorsx.ErrFlightUnauthorized.ErrorCode
+	case fiber.StatusNotFound:
+		return apperrorsx.CodeFlightNotFound, apperrorsx.ErrFlightNotFound.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "date must be yyyy-mm-dd"):
+			return apperrorsx.CodeFlightDateInvalid, apperrorsx.ErrFlightDateInvalid.ErrorCode
+		case strings.Contains(lowerDetail, "invalid uuid"):
+			return apperrorsx.CodeFlightInvalidUUID, apperrorsx.ErrFlightInvalidUUID.ErrorCode
+		default:
+			return apperrorsx.CodeFlightValidationFailed, apperrorsx.ErrFlightValidationFailed.ErrorCode
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.CodeFlightInvalidJSON, apperrorsx.ErrFlightInvalidJSON.ErrorCode
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.CodeFlightCreateFailed, apperrorsx.ErrFlightCreateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "get failed"):
+			return apperrorsx.CodeFlightGetFailed, apperrorsx.ErrFlightGetFailed.ErrorCode
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.CodeFlightListFailed, apperrorsx.ErrFlightListFailed.ErrorCode
+		default:
+			return apperrorsx.CodeFlightInvalidPayload, apperrorsx.ErrFlightInvalidPayload.ErrorCode
+		}
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
diff --git a/internal/transport/http/handlers/flight_handler_test.go b/internal/transport/http/handlers/flight_handler_test.go
new file mode 100644
index 0000000..288c362
--- /dev/null
+++ b/internal/transport/http/handlers/flight_handler_test.go
@@ -0,0 +1,675 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	"wucher/internal/domain/flight"
+	flightdata "wucher/internal/domain/flight_data"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	"wucher/internal/domain/mission"
+	reserveac "wucher/internal/domain/reserve_ac"
+	takeoverdomain "wucher/internal/domain/takeover"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type flightServiceMock struct {
+	createFn       func(context.Context, *flight.Flight) error
+	getByIDFn      func(context.Context, []byte) (*flight.Flight, error)
+	listByUserIDFn func(context.Context, []byte, int, int) ([]flight.Flight, int64, error)
+	listFn         func(context.Context, string, string, string, int, int) ([]flight.Flight, int64, error)
+}
+
+type missionServiceMock struct {
+	listByFlightIDFn  func(context.Context, []byte) ([]mission.Mission, error)
+	listByFlightIDsFn func(context.Context, [][]byte) ([]mission.Mission, error)
+	listFn            func(context.Context, string, string, []byte, int, int) ([]mission.Mission, int64, error)
+	listDTFn          func(context.Context, mission.ListFilter, int, int) ([]mission.Mission, int64, int64, error)
+	deleteByIDFn      func(context.Context, []byte, []byte) error
+}
+
+type afterFlightInspectionServiceMock struct {
+	getByFlightInspectionIDFn func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error)
+}
+
+type takeoverServiceMock struct {
+	getByIDFn func(context.Context, []byte) (*takeoverdomain.TakeoverAc, error)
+}
+
+func (m *flightServiceMock) Create(ctx context.Context, row *flight.Flight) error {
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return nil
+}
+func (m *flightServiceMock) Update(context.Context, *flight.Flight) error { return nil }
+func (m *flightServiceMock) Delete(context.Context, []byte, []byte) error { return nil }
+func (m *flightServiceMock) GetByID(ctx context.Context, id []byte) (*flight.Flight, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *flightServiceMock) ListByUserID(ctx context.Context, userID []byte, limit, offset int) ([]flight.Flight, int64, error) {
+	if m.listByUserIDFn != nil {
+		return m.listByUserIDFn(ctx, userID, limit, offset)
+	}
+	return nil, 0, nil
+}
+func (m *flightServiceMock) ListByCreatedBy(context.Context, []byte, string, string, string, int, int) ([]flight.Flight, int64, error) {
+	return nil, 0, nil
+}
+func (m *flightServiceMock) GetByReserveAcID(context.Context, []byte) (*flight.Flight, error) {
+	return nil, nil
+}
+func (m *flightServiceMock) ListByReserveAcID(context.Context, []byte) ([]flight.Flight, error) {
+	return nil, nil
+}
+func (m *flightServiceMock) GetByTakeoverAcID(context.Context, []byte) (*flight.Flight, error) {
+	return nil, nil
+}
+func (m *flightServiceMock) ListByTakeoverAcIDs(context.Context, [][]byte) ([]flight.Flight, error) {
+	return nil, nil
+}
+func (m *flightServiceMock) GetByDutyRosterID(context.Context, []byte) (*flight.Flight, error) {
+	return nil, nil
+}
+func (m *flightServiceMock) ListByDutyRosterIDs(context.Context, [][]byte) ([]flight.Flight, error) {
+	return nil, nil
+}
+func (m *flightServiceMock) List(ctx context.Context, filter string, date string, sort string, limit, offset int) ([]flight.Flight, int64, error) {
+	if m.listFn != nil {
+		return m.listFn(ctx, filter, date, sort, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func (m *missionServiceMock) Create(context.Context, *mission.Mission) error { return nil }
+func (m *missionServiceMock) CreateType(context.Context, *mission.MissionCategory) error {
+	return nil
+}
+func (m *missionServiceMock) UpdateByID(context.Context, []byte, string, []byte, string, []byte) error {
+	return nil
+}
+func (m *missionServiceMock) DeleteByFlightID(context.Context, []byte, []byte) error { return nil }
+func (m *missionServiceMock) AttachFile(context.Context, []byte, []byte) error       { return nil }
+func (m *missionServiceMock) DetachFile(context.Context, []byte, []byte) error       { return nil }
+func (m *missionServiceMock) DeleteByID(ctx context.Context, missionID []byte, deletedBy []byte) error {
+	if m.deleteByIDFn != nil {
+		return m.deleteByIDFn(ctx, missionID, deletedBy)
+	}
+	return nil
+}
+func (m *missionServiceMock) ListByFlightID(ctx context.Context, flightID []byte) ([]mission.Mission, error) {
+	if m.listByFlightIDFn != nil {
+		return m.listByFlightIDFn(ctx, flightID)
+	}
+	return nil, nil
+}
+func (m *missionServiceMock) ListByFlightIDs(ctx context.Context, flightIDs [][]byte) ([]mission.Mission, error) {
+	if m.listByFlightIDsFn != nil {
+		return m.listByFlightIDsFn(ctx, flightIDs)
+	}
+	return nil, nil
+}
+func (m *missionServiceMock) GetByID(context.Context, []byte) (*mission.Mission, error) {
+	return nil, nil
+}
+func (m *missionServiceMock) GetByFlightID(context.Context, []byte) (*mission.Mission, error) {
+	return nil, nil
+}
+func (m *missionServiceMock) List(ctx context.Context, filter string, sort string, flightID []byte, flightDataStatus string, limit, offset int) ([]mission.Mission, int64, error) {
+	if m.listFn != nil {
+		return m.listFn(ctx, filter, sort, flightID, limit, offset)
+	}
+	return nil, 0, nil
+}
+func (m *missionServiceMock) ListDatatable(ctx context.Context, filter mission.ListFilter, limit, offset int) ([]mission.Mission, int64, int64, error) {
+	if m.listDTFn != nil {
+		return m.listDTFn(ctx, filter, limit, offset)
+	}
+	return nil, 0, 0, nil
+}
+func (m *missionServiceMock) ListTypes(context.Context) ([]mission.MissionCategory, error) {
+	return nil, nil
+}
+
+func (m *afterFlightInspectionServiceMock) Upsert(context.Context, []byte, *afterflightinspection.UpsertRequest) (*afterflightinspection.AfterFlightInspection, error) {
+	return nil, nil
+}
+func (m *afterFlightInspectionServiceMock) GetByFlightInspectionID(ctx context.Context, id []byte) (*afterflightinspection.AfterFlightInspection, error) {
+	if m.getByFlightInspectionIDFn != nil {
+		return m.getByFlightInspectionIDFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *afterFlightInspectionServiceMock) DeleteByFlightInspectionID(context.Context, []byte) error {
+	return nil
+}
+
+func (m *takeoverServiceMock) Create(context.Context, *takeoverdomain.TakeoverAc) error { return nil }
+func (m *takeoverServiceMock) Update(context.Context, *takeoverdomain.TakeoverAc) error { return nil }
+func (m *takeoverServiceMock) Delete(context.Context, []byte, []byte) error             { return nil }
+func (m *takeoverServiceMock) AttachFile(context.Context, []byte, []byte) error         { return nil }
+func (m *takeoverServiceMock) GetByID(ctx context.Context, id []byte) (*takeoverdomain.TakeoverAc, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *takeoverServiceMock) List(context.Context, int, int) ([]takeoverdomain.TakeoverAc, int64, error) {
+	return nil, 0, nil
+}
+
+func newFlightApp(h *FlightHandler, withActor bool) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if withActor {
+			c.Locals("user_id", uuidv7.MustBytes())
+		}
+		return c.Next()
+	})
+	app.Post("/flights", h.Create)
+	app.Get("/flights/me", h.GetByAuthUser)
+	app.Get("/flights", h.List)
+	return app
+}
+
+func doReqFlight(t *testing.T, app *fiber.App, method, path string, body []byte) (int, string) {
+	t.Helper()
+	var rdr io.Reader
+	if body != nil {
+		rdr = bytes.NewReader(body)
+	}
+	req, err := http.NewRequest(method, path, rdr)
+	if err != nil {
+		t.Fatalf("new req: %v", err)
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	defer resp.Body.Close()
+	b, _ := io.ReadAll(resp.Body)
+	return resp.StatusCode, string(b)
+}
+
+func TestFlightHandler(t *testing.T) {
+	t.Run("new and with reserve ac", func(t *testing.T) {
+		h := NewFlightHandler(&flightServiceMock{})
+		if h == nil || h.validate == nil {
+			t.Fatal("expected handler initialized")
+		}
+		if h.WithReserveAcService(nil) != h {
+			t.Fatal("expected same pointer")
+		}
+	})
+
+	t.Run("create invalid json", func(t *testing.T) {
+		h := NewFlightHandler(&flightServiceMock{})
+		code, _ := doReqFlight(t, newFlightApp(h, true), http.MethodPost, "/flights", []byte(`{"data":`))
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+	})
+
+	t.Run("create validation", func(t *testing.T) {
+		h := NewFlightHandler(&flightServiceMock{})
+		code, _ := doReqFlight(t, newFlightApp(h, true), http.MethodPost, "/flights", []byte(`{}`))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+	})
+
+	t.Run("create date invalid", func(t *testing.T) {
+		h := NewFlightHandler(&flightServiceMock{})
+		body := []byte(`{"data":{"type":"flight","attributes":{"date":"x"}}}`)
+		code, _ := doReqFlight(t, newFlightApp(h, true), http.MethodPost, "/flights", body)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+	})
+
+	t.Run("create optional uuid invalid", func(t *testing.T) {
+		h := NewFlightHandler(&flightServiceMock{})
+		body := []byte(`{"data":{"type":"flight","attributes":{"date":"2026-04-14","duty_roster_id":"bad"}}}`)
+		code, _ := doReqFlight(t, newFlightApp(h, true), http.MethodPost, "/flights", body)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		body = []byte(`{"data":{"type":"flight","attributes":{"date":"2026-04-14","reserve_ac_id":"bad"}}}`)
+		code, _ = doReqFlight(t, newFlightApp(h, true), http.MethodPost, "/flights", body)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+	})
+
+	t.Run("create service error", func(t *testing.T) {
+		h := NewFlightHandler(&flightServiceMock{
+			createFn: func(context.Context, *flight.Flight) error { return errors.New("boom") },
+		})
+		body := []byte(`{"data":{"type":"flight","attributes":{"date":"2026-04-14"}}}`)
+		code, _ := doReqFlight(t, newFlightApp(h, true), http.MethodPost, "/flights", body)
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+	})
+
+	t.Run("create success with refetch and fallback", func(t *testing.T) {
+		var createdID []byte
+		h := NewFlightHandler(&flightServiceMock{
+			createFn: func(_ context.Context, row *flight.Flight) error {
+				row.ID = uuidv7.MustBytes()
+				createdID = append([]byte(nil), row.ID...)
+				return nil
+			},
+			getByIDFn: func(_ context.Context, id []byte) (*flight.Flight, error) {
+				if string(id) != string(createdID) {
+					t.Fatal("unexpected id")
+				}
+				return &flight.Flight{
+					ID:        id,
+					Date:      time.Date(2026, 4, 14, 0, 0, 0, 0, time.UTC),
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}, nil
+			},
+		})
+		body := []byte(`{"data":{"type":"flight","attributes":{"date":"2026-04-14","duty_roster_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `","reserve_ac_id":"` + mustUUIDStringHospital(t, uuidv7.MustBytes()) + `"}}}`)
+		code, _ := doReqFlight(t, newFlightApp(h, true), http.MethodPost, "/flights", body)
+		if code != http.StatusCreated {
+			t.Fatalf("expected 201 got %d", code)
+		}
+
+		h2 := NewFlightHandler(&flightServiceMock{
+			createFn: func(_ context.Context, row *flight.Flight) error {
+				row.ID = uuidv7.MustBytes()
+				row.CreatedAt = time.Now().UTC()
+				row.UpdatedAt = row.CreatedAt
+				return nil
+			},
+			getByIDFn: func(context.Context, []byte) (*flight.Flight, error) { return nil, errors.New("x") },
+		})
+		code, _ = doReqFlight(t, newFlightApp(h2, true), http.MethodPost, "/flights", []byte(`{"data":{"type":"flight","attributes":{"date":"2026-04-14"}}}`))
+		if code != http.StatusCreated {
+			t.Fatalf("expected 201 got %d", code)
+		}
+	})
+
+	t.Run("get by auth user branches", func(t *testing.T) {
+		h := NewFlightHandler(&flightServiceMock{})
+		code, _ := doReqFlight(t, newFlightApp(h, false), http.MethodGet, "/flights/me", nil)
+		if code != http.StatusUnauthorized {
+			t.Fatalf("expected 401 got %d", code)
+		}
+
+		hErr := NewFlightHandler(&flightServiceMock{
+			listByUserIDFn: func(context.Context, []byte, int, int) ([]flight.Flight, int64, error) {
+				return nil, 0, errors.New("err")
+			},
+		})
+		code, _ = doReqFlight(t, newFlightApp(hErr, true), http.MethodGet, "/flights/me?page[number]=0&page[size]=500", nil)
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+
+		row := flight.Flight{
+			ID:           uuidv7.MustBytes(),
+			Date:         time.Date(2026, 4, 14, 0, 0, 0, 0, time.UTC),
+			DutyRosterID: uuidv7.MustBytes(),
+			ReserveAcID:  uuidv7.MustBytes(),
+			CreatedAt:    time.Now().UTC(),
+			UpdatedAt:    time.Now().UTC(),
+		}
+
+		hOK := NewFlightHandler(&flightServiceMock{
+			listByUserIDFn: func(_ context.Context, _ []byte, limit, offset int) ([]flight.Flight, int64, error) {
+				if limit != 100 || offset != 0 {
+					t.Fatalf("unexpected paging %d %d", limit, offset)
+				}
+				return []flight.Flight{row}, 1, nil
+			},
+		})
+		code, body := doReqFlight(t, newFlightApp(hOK, true), http.MethodGet, "/flights/me?page[number]=0&page[size]=500", nil)
+		if code != http.StatusOK || !strings.Contains(body, `"flight"`) {
+			t.Fatalf("expected 200 flight body, got %d %s", code, body)
+		}
+
+		hPg := NewFlightHandler(&flightServiceMock{
+			listByUserIDFn: func(_ context.Context, _ []byte, limit, offset int) ([]flight.Flight, int64, error) {
+				if limit <= 0 || offset != 0 {
+					t.Fatalf("unexpected paging")
+				}
+				return nil, 0, nil
+			},
+		})
+		code, _ = doReqFlight(t, newFlightApp(hPg, true), http.MethodGet, "/flights/me?page=1&limit=5", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		code, _ = doReqFlight(t, newFlightApp(hPg, true), http.MethodGet, "/flights/me?page=1&size=7", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		code, _ = doReqFlight(t, newFlightApp(hPg, true), http.MethodGet, "/flights/me?page=-1&page[size]=-1", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		code, _ = doReqFlight(t, newFlightApp(hPg, true), http.MethodGet, "/flights/me?page=1&page[size]=-1&limit=-1&size=-1", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+	})
+
+	t.Run("list branches", func(t *testing.T) {
+		hErr := NewFlightHandler(&flightServiceMock{
+			listFn: func(context.Context, string, string, string, int, int) ([]flight.Flight, int64, error) {
+				return nil, 0, errors.New("no")
+			},
+		})
+		code, _ := doReqFlight(t, newFlightApp(hErr, true), http.MethodGet, "/flights?search=x", nil)
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+
+		hOK := NewFlightHandler(&flightServiceMock{
+			listFn: func(_ context.Context, filter, date, sort string, limit, offset int) ([]flight.Flight, int64, error) {
+				if filter != "abc" || sort != "-date" || limit != 0 || offset != 0 {
+					t.Fatalf("unexpected args")
+				}
+				return []flight.Flight{{ID: uuidv7.MustBytes(), Date: time.Now().UTC(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}}, 1, nil
+			},
+		}).WithMissionService(&missionServiceMock{
+			listByFlightIDFn: func(_ context.Context, _ []byte) ([]mission.Mission, error) {
+				return []mission.Mission{{ID: uuidv7.MustBytes(), Type: "CAT", CreatedAt: time.Now().UTC()}}, nil
+			},
+		})
+		code, body := doReqFlight(t, newFlightApp(hOK, true), http.MethodGet, "/flights?filter[search]=abc&sort=-date&page[number]=0&page[size]=0", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		if !strings.Contains(body, `"mission_id"`) {
+			t.Fatalf("expected mission_id in response, got %s", body)
+		}
+
+		hProgress := NewFlightHandler(&flightServiceMock{
+			listFn: func(_ context.Context, filter, date, sort string, limit, offset int) ([]flight.Flight, int64, error) {
+				if filter != "" || date != "" || sort != "" || limit != 0 || offset != 0 {
+					t.Fatalf("unexpected args")
+				}
+				return []flight.Flight{{
+					ID:           uuidv7.MustBytes(),
+					Date:         time.Now().UTC(),
+					TakeoverAcID: uuidv7.MustBytes(),
+					Takeover: &takeoverdomain.TakeoverAc{
+						ReserveAcID: uuidv7.MustBytes(),
+						ReserveAc:   &reserveac.ReserveAc{Status: "onprogress"},
+					},
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}}, 1, nil
+			},
+		})
+		code, body = doReqFlight(t, newFlightApp(hProgress, true), http.MethodGet, "/flights", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		if !strings.Contains(body, `"status":"in_progress"`) {
+			t.Fatalf("expected on_progress status, got %s", body)
+		}
+		if !strings.Contains(body, `"complete":false`) {
+			t.Fatalf("expected complete=false in response, got %s", body)
+		}
+
+		inspectionID := uuidv7.MustBytes()
+		afterID := uuidv7.MustBytes()
+		hAfter := NewFlightHandler(&flightServiceMock{
+			listFn: func(_ context.Context, filter, date, sort string, limit, offset int) ([]flight.Flight, int64, error) {
+				if filter != "" || date != "" || sort != "" || limit != 0 || offset != 0 {
+					t.Fatalf("unexpected args")
+				}
+				return []flight.Flight{{
+					ID:           uuidv7.MustBytes(),
+					Date:         time.Now().UTC(),
+					TakeoverAcID: uuidv7.MustBytes(),
+					Takeover: &takeoverdomain.TakeoverAc{
+						ReserveAcID: uuidv7.MustBytes(),
+						ReserveAc: &reserveac.ReserveAc{
+							Inspection: &flightinspection.FlightInspection{ID: inspectionID},
+						},
+					},
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}}, 1, nil
+			},
+		}).WithMissionService(&missionServiceMock{
+			listByFlightIDFn: func(_ context.Context, _ []byte) ([]mission.Mission, error) {
+				return []mission.Mission{{ID: uuidv7.MustBytes(), Type: "CAT", CreatedAt: time.Now().UTC()}}, nil
+			},
+		}).WithAfterFlightInspectionService(&afterFlightInspectionServiceMock{
+			getByFlightInspectionIDFn: func(_ context.Context, id []byte) (*afterflightinspection.AfterFlightInspection, error) {
+				if string(id) != string(inspectionID) {
+					t.Fatalf("unexpected inspection id")
+				}
+				now := time.Now().UTC()
+				return &afterflightinspection.AfterFlightInspection{
+					ID:                 afterID,
+					FlightInspectionID: inspectionID,
+					CreatedAt:          now,
+					CreatedBy:          uuidv7.MustBytes(),
+					UpdatedAt:          now,
+					UpdatedBy:          uuidv7.MustBytes(),
+				}, nil
+			},
+		}).WithTakeoverService(&takeoverServiceMock{
+			getByIDFn: func(_ context.Context, id []byte) (*takeoverdomain.TakeoverAc, error) {
+				if len(id) != 16 {
+					t.Fatalf("unexpected takeover id")
+				}
+				return &takeoverdomain.TakeoverAc{
+					ID:     id,
+					BaseID: uuidv7.MustBytes(),
+					ReserveAc: &reserveac.ReserveAc{
+						AircraftID: uuidv7.MustBytes(),
+						Inspection: &flightinspection.FlightInspection{ID: inspectionID},
+					},
+					RosterCrews: []takeoverdomain.TakeoverRosterCrew{{ID: uuidv7.MustBytes()}},
+					OtherPeople: []takeoverdomain.TakeoverOtherPerson{{ID: uuidv7.MustBytes()}},
+				}, nil
+			},
+		})
+		code, body = doReqFlight(t, newFlightApp(hAfter, true), http.MethodGet, "/flights", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		if !strings.Contains(body, `"phase":"after_flight_inspection"`) {
+			t.Fatalf("expected after_flight_inspection step, got %s", body)
+		}
+		if !strings.Contains(body, `"step":3`) {
+			t.Fatalf("expected step 3 in response, got %s", body)
+		}
+		if !strings.Contains(body, `"complete":true`) {
+			t.Fatalf("expected complete=true in response, got %s", body)
+		}
+
+		code, _ = doReqFlight(t, newFlightApp(hOK, true), http.MethodGet, "/flights?page=1&limit=5&search=abc&sort=-date", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		code, _ = doReqFlight(t, newFlightApp(hOK, true), http.MethodGet, "/flights?page=1&size=7&search=abc&sort=-date", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		code, _ = doReqFlight(t, newFlightApp(hOK, true), http.MethodGet, "/flights?page=-1&page[size]=-1&search=abc&sort=-date", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		code, _ = doReqFlight(t, newFlightApp(hOK, true), http.MethodGet, "/flights?page=1&page[size]=-1&limit=-1&size=-1&search=abc&sort=-date", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		code, _ = doReqFlight(t, newFlightApp(hOK, true), http.MethodGet, "/flights?page=1&page[size]=200&search=abc&sort=-date", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+	})
+
+	t.Run("helpers", func(t *testing.T) {
+		if stringPtrOrEmpty(nil) != "" {
+			t.Fatal("expected empty")
+		}
+		v := "  x "
+		if stringPtrOrEmpty(&v) != "x" {
+			t.Fatal("expected trimmed")
+		}
+		if timeStringOrEmptyRefTime(nil) != "" || timeStringOrEmptyRefTime(&time.Time{}) != "" {
+			t.Fatal("expected empty")
+		}
+		now := time.Now().UTC()
+		if timeStringOrEmptyRefTime(&now) == "" {
+			t.Fatal("expected time")
+		}
+		raw := "bad"
+		if _, errObj := parseOptionalUUIDFlight(&raw, "/data/attributes/duty_roster_id"); errObj == nil {
+			t.Fatal("expected err")
+		}
+		raw = " "
+		if id, errObj := parseOptionalUUIDFlight(&raw, "/data/attributes/duty_roster_id"); errObj != nil || id != nil {
+			t.Fatal("expected nil")
+		}
+		raw = mustUUIDStringHospital(t, uuidv7.MustBytes())
+		if id, errObj := parseOptionalUUIDFlight(&raw, "/data/attributes/duty_roster_id"); errObj != nil || len(id) != 16 {
+			t.Fatal("expected id")
+		}
+		if s := flightMissionStep(nil); s.Status != "unassigned" {
+			t.Fatal("expected unassigned")
+		}
+		if s := flightDutyRosterStep(nil); s.Status != "unassigned" {
+			t.Fatal("expected unassigned")
+		}
+		if s := flightReserveAcStep(nil); s.Status != "unassigned" {
+			t.Fatal("expected unassigned")
+		}
+		if s := flightReserveAcStep(&flight.Flight{Takeover: &takeoverdomain.TakeoverAc{ReserveAcID: uuidv7.MustBytes(), ReserveAc: &reserveac.ReserveAc{Status: "pending"}}}); s.Status != "pending" {
+			t.Fatal("expected pending")
+		}
+		if s := flightReserveAcStep(&flight.Flight{Takeover: &takeoverdomain.TakeoverAc{ReserveAcID: uuidv7.MustBytes(), ReserveAc: &reserveac.ReserveAc{Status: "onprogress"}}}); s.Status != "in_progress" {
+			t.Fatal("expected on progress")
+		}
+		if s := flightReserveAcStep(&flight.Flight{Takeover: &takeoverdomain.TakeoverAc{ReserveAcID: uuidv7.MustBytes(), ReserveAc: &reserveac.ReserveAc{Status: "approved", UpdatedAt: time.Now().UTC(), UpdatedBy: uuidv7.MustBytes()}}}); s.Status != "completed" {
+			t.Fatal("expected completed")
+		}
+		if s := flightMissionStep(&flight.Flight{}); s.Status != "unassigned" {
+			t.Fatal("expected mission unassigned")
+		}
+	})
+}
+
+func TestFlightHandlerList_MissionStepShowsInProgressUntilFlightDataComplete(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	missionID := uuidv7.MustBytes()
+
+	h := NewFlightHandler(&flightServiceMock{
+		listFn: func(context.Context, string, string, string, int, int) ([]flight.Flight, int64, error) {
+			return []flight.Flight{{
+				ID:        flightID,
+				Date:      time.Date(2026, time.June, 26, 0, 0, 0, 0, time.UTC),
+				CreatedAt: time.Date(2026, time.June, 24, 4, 31, 37, 0, time.UTC),
+				CreatedBy: []byte("creator-id-12345"),
+			}}, 1, nil
+		},
+	}).WithMissionService(&missionServiceMock{
+		listByFlightIDFn: func(context.Context, []byte) ([]mission.Mission, error) {
+			return []mission.Mission{{
+				ID:        missionID,
+				FlightID:  flightID,
+				Type:      "CAT",
+				CreatedAt: time.Date(2026, time.June, 24, 5, 23, 3, 0, time.UTC),
+				UpdatedAt: time.Date(2026, time.June, 24, 5, 23, 3, 0, time.UTC),
+			}}, nil
+		},
+	}).WithFlightDataService(&flightDataServiceMock{
+		getByMisFn: func(context.Context, []byte) (*flightdata.FlightData, error) {
+			return &flightdata.FlightData{Status: flightdata.StatusInProgress}, nil
+		},
+	})
+
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", uuidv7.MustBytes())
+		return c.Next()
+	})
+	app.Get("/flights", h.List)
+
+	code, body := doReqFlight(t, app, http.MethodGet, "/flights?date=2026-06-26&limit=2000", nil)
+	if code != http.StatusOK {
+		t.Fatalf("unexpected status: %d body=%s", code, body)
+	}
+	if !strings.Contains(body, `"phase":"mission"`) {
+		t.Fatalf("expected mission step in body: %s", body)
+	}
+	if !strings.Contains(body, `"status":"in_progress"`) {
+		t.Fatalf("expected mission step in_progress: %s", body)
+	}
+}
+
+func TestFlightHandlerList_MissionStepShowsCompletedWhenFlightDataComplete(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	missionID := uuidv7.MustBytes()
+
+	h := NewFlightHandler(&flightServiceMock{
+		listFn: func(context.Context, string, string, string, int, int) ([]flight.Flight, int64, error) {
+			return []flight.Flight{{
+				ID:        flightID,
+				Date:      time.Date(2026, time.June, 26, 0, 0, 0, 0, time.UTC),
+				CreatedAt: time.Date(2026, time.June, 24, 4, 31, 37, 0, time.UTC),
+				CreatedBy: []byte("creator-id-12345"),
+			}}, 1, nil
+		},
+	}).WithMissionService(&missionServiceMock{
+		listByFlightIDFn: func(context.Context, []byte) ([]mission.Mission, error) {
+			return []mission.Mission{{
+				ID:        missionID,
+				FlightID:  flightID,
+				Type:      "CAT",
+				CreatedAt: time.Date(2026, time.June, 24, 5, 23, 3, 0, time.UTC),
+				UpdatedAt: time.Date(2026, time.June, 24, 6, 41, 45, 0, time.UTC),
+				UpdatedBy: []byte("test test"),
+			}}, nil
+		},
+	}).WithFlightDataService(&flightDataServiceMock{
+		getByMisFn: func(context.Context, []byte) (*flightdata.FlightData, error) {
+			return &flightdata.FlightData{Status: flightdata.StatusCompleted}, nil
+		},
+	})
+
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", uuidv7.MustBytes())
+		return c.Next()
+	})
+	app.Get("/flights", h.List)
+
+	code, body := doReqFlight(t, app, http.MethodGet, "/flights?date=2026-06-26&limit=2000", nil)
+	if code != http.StatusOK {
+		t.Fatalf("unexpected status: %d body=%s", code, body)
+	}
+	if !strings.Contains(body, `"phase":"mission"`) {
+		t.Fatalf("expected mission step in body: %s", body)
+	}
+	if !strings.Contains(body, `"status":"completed"`) {
+		t.Fatalf("expected mission step completed: %s", body)
+	}
+}
diff --git a/internal/transport/http/handlers/flight_inspection_handler.go b/internal/transport/http/handlers/flight_inspection_handler.go
new file mode 100644
index 0000000..4d2b34f
--- /dev/null
+++ b/internal/transport/http/handlers/flight_inspection_handler.go
@@ -0,0 +1,287 @@
+package handlers
+
+import (
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	flightinspection "wucher/internal/domain/flight_inspection"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type FlightInspectionHandler struct {
+	svc      flightinspection.FlightInspectionService
+	validate *validators.Validator
+}
+
+func NewFlightInspectionHandler(svc flightinspection.FlightInspectionService) *FlightInspectionHandler {
+	return &FlightInspectionHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateFlightInspection godoc
+// @Summary Create flight inspection draft
+// @Tags Flight Inspection
+// @Accept json
+// @Produce json
+// @Param request body dto.FlightInspectionCreateRequest true "JSON:API flight inspection create request"
+// @Success 201 {object} dto.FlightInspectionResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// Public route disabled (managed via reserve AC flow).
+func (h *FlightInspectionHandler) Create(c *fiber.Ctx) error {
+	var req dto.FlightInspectionCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	inspectionDate, err := time.Parse("2006-01-02", strings.TrimSpace(req.Data.Attributes.InspectionDate))
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "inspection_date must be YYYY-MM-DD",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/inspection_date"},
+		}})
+	}
+
+	model := &flightinspection.FlightInspection{
+		InspectionDate: inspectionDate.UTC(),
+		CreatedBy:      actorUserID(c),
+		UpdatedBy:      actorUserID(c),
+	}
+	if err := h.svc.CreateDraft(c.UserContext(), model); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	return response.Write(c, fiber.StatusCreated, flightInspectionResource(model))
+}
+
+// GetFlightInspection godoc
+// @Summary Get flight inspection by ID
+// @Tags Flight Inspection
+// @Produce json
+// @Param id path string true "Flight inspection UUID (UUIDv7)"
+// @Success 200 {object} dto.FlightInspectionResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// Public route disabled (managed via reserve AC flow).
+func (h *FlightInspectionHandler) GetByID(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if row == nil {
+		return response.WriteErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "flight inspection not found",
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, flightInspectionResource(row))
+}
+
+// UpdateFlightInspection godoc
+// @Summary Update flight inspection
+// @Tags Flight Inspection
+// @Accept json
+// @Produce json
+// @Param id path string true "Flight inspection UUID (UUIDv7)"
+// @Param request body dto.FlightInspectionUpdateRequest true "JSON:API flight inspection update request"
+// @Success 200 {object} dto.FlightInspectionResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// Public route disabled (managed via reserve AC flow).
+func (h *FlightInspectionHandler) Update(c *fiber.Ctx) error {
+	idStr := strings.TrimSpace(c.Params("id"))
+	id, err := uuidv7.ParseString(idStr)
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	var req dto.FlightInspectionUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if strings.TrimSpace(req.Data.ID) == "" || req.Data.ID != idStr {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required and must match path id",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	if req.Data.Attributes.InspectionDate == nil && req.Data.Attributes.Status == nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if row == nil {
+		return response.WriteErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "flight inspection not found",
+		}})
+	}
+
+	if req.Data.Attributes.InspectionDate != nil {
+		inspectionDate, parseErr := time.Parse("2006-01-02", strings.TrimSpace(*req.Data.Attributes.InspectionDate))
+		if parseErr != nil {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "inspection_date must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/inspection_date"},
+			}})
+		}
+		row.InspectionDate = inspectionDate.UTC()
+	}
+
+	if req.Data.Attributes.Status != nil {
+		nextStatus := strings.TrimSpace(*req.Data.Attributes.Status)
+		switch nextStatus {
+		case flightinspection.StatusDraft, flightinspection.StatusInProgress, flightinspection.StatusCompleted:
+			row.Status = nextStatus
+		default:
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "status must be one of: Draft, InProgress, Completed",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/status"},
+			}})
+		}
+	}
+
+	row.UpdatedBy = actorUserID(c)
+	if err := h.svc.Update(c.UserContext(), row); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), id)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, flightInspectionResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, flightInspectionResource(row))
+}
+
+// ListFlightInspections godoc
+// @Summary List flight inspections
+// @Tags Flight Inspection
+// @Produce json
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.FlightInspectionListResponse
+// @Failure 422 {object} dto.ErrorResponse
+// Public route disabled (managed via reserve AC flow).
+func (h *FlightInspectionHandler) List(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page[number]"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), 20)
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+
+	rows, total, err := h.svc.List(c.UserContext(), c.Query("sort"), 0, 0)
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.FlightInspectionResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, flightInspectionResource(&rows[i]))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	})
+}
+
+func flightInspectionResource(row *flightinspection.FlightInspection) dto.FlightInspectionResource {
+	id, _ := uuidv7.BytesToString(row.ID)
+	return dto.FlightInspectionResource{
+		Type: "flight_inspection",
+		ID:   id,
+		Attributes: dto.FlightInspectionAttributes{
+			InspectionDate: row.InspectionDate.UTC().Format("2006-01-02"),
+			Status:         row.Status,
+			CreatedAt:      row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:      uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:      row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:      uuidStringOrEmpty(row.UpdatedBy),
+		},
+	}
+}
diff --git a/internal/transport/http/handlers/flight_inspection_handler_test.go b/internal/transport/http/handlers/flight_inspection_handler_test.go
new file mode 100644
index 0000000..a6b76c3
--- /dev/null
+++ b/internal/transport/http/handlers/flight_inspection_handler_test.go
@@ -0,0 +1,321 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	flightinspection "wucher/internal/domain/flight_inspection"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type flightInspectionServiceMock struct {
+	createFn func(context.Context, *flightinspection.FlightInspection) error
+	updateFn func(context.Context, *flightinspection.FlightInspection) error
+	getFn    func(context.Context, []byte) (*flightinspection.FlightInspection, error)
+	listFn   func(context.Context, string, int, int) ([]flightinspection.FlightInspection, int64, error)
+}
+
+func (m *flightInspectionServiceMock) CreateDraft(ctx context.Context, row *flightinspection.FlightInspection) error {
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return nil
+}
+func (m *flightInspectionServiceMock) Update(ctx context.Context, row *flightinspection.FlightInspection) error {
+	if m.updateFn != nil {
+		return m.updateFn(ctx, row)
+	}
+	return nil
+}
+func (m *flightInspectionServiceMock) GetByID(ctx context.Context, id []byte) (*flightinspection.FlightInspection, error) {
+	if m.getFn != nil {
+		return m.getFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *flightInspectionServiceMock) List(ctx context.Context, sort string, limit, offset int) ([]flightinspection.FlightInspection, int64, error) {
+	if m.listFn != nil {
+		return m.listFn(ctx, sort, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func newFIApp(h *FlightInspectionHandler) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", uuidv7.MustBytes())
+		return c.Next()
+	})
+	app.Post("/fi", h.Create)
+	app.Get("/fi/:id", h.GetByID)
+	app.Patch("/fi/:id", h.Update)
+	app.Get("/fi", h.List)
+	return app
+}
+
+func doReqFI(t *testing.T, app *fiber.App, method, path string, body []byte) (int, string) {
+	t.Helper()
+	var rdr io.Reader
+	if body != nil {
+		rdr = bytes.NewReader(body)
+	}
+	req, _ := http.NewRequest(method, path, rdr)
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	defer resp.Body.Close()
+	b, _ := io.ReadAll(resp.Body)
+	return resp.StatusCode, string(b)
+}
+
+func TestFlightInspectionHandler(t *testing.T) {
+	t.Run("new", func(t *testing.T) {
+		h := NewFlightInspectionHandler(&flightInspectionServiceMock{})
+		if h == nil || h.validate == nil {
+			t.Fatal("expected initialized")
+		}
+	})
+
+	t.Run("create branches", func(t *testing.T) {
+		h := NewFlightInspectionHandler(&flightInspectionServiceMock{})
+		code, _ := doReqFI(t, newFIApp(h), http.MethodPost, "/fi", []byte(`{"data":`))
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+		code, _ = doReqFI(t, newFIApp(h), http.MethodPost, "/fi", []byte(`{}`))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		code, _ = doReqFI(t, newFIApp(h), http.MethodPost, "/fi", []byte(`{"data":{"type":"flight_inspection","attributes":{"inspection_date":"x"}}}`))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		hErr := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			createFn: func(context.Context, *flightinspection.FlightInspection) error { return errors.New("x") },
+		})
+		code, _ = doReqFI(t, newFIApp(hErr), http.MethodPost, "/fi", []byte(`{"data":{"type":"flight_inspection","attributes":{"inspection_date":"2026-04-09"}}}`))
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+		hOK := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			createFn: func(_ context.Context, row *flightinspection.FlightInspection) error {
+				row.ID = uuidv7.MustBytes()
+				row.Status = flightinspection.StatusDraft
+				row.CreatedAt = time.Now().UTC()
+				row.UpdatedAt = row.CreatedAt
+				return nil
+			},
+		})
+		code, _ = doReqFI(t, newFIApp(hOK), http.MethodPost, "/fi", []byte(`{"data":{"type":"flight_inspection","attributes":{"inspection_date":"2026-04-09"}}}`))
+		if code != http.StatusCreated {
+			t.Fatalf("expected 201 got %d", code)
+		}
+	})
+
+	t.Run("get branches", func(t *testing.T) {
+		h := NewFlightInspectionHandler(&flightInspectionServiceMock{})
+		code, _ := doReqFI(t, newFIApp(h), http.MethodGet, "/fi/bad", nil)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		id := mustUUIDStringHospital(t, uuidv7.MustBytes())
+		hErr := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			getFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) { return nil, errors.New("x") },
+		})
+		code, _ = doReqFI(t, newFIApp(hErr), http.MethodGet, "/fi/"+id, nil)
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+		hNil := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			getFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) { return nil, nil },
+		})
+		code, _ = doReqFI(t, newFIApp(hNil), http.MethodGet, "/fi/"+id, nil)
+		if code != http.StatusNotFound {
+			t.Fatalf("expected 404 got %d", code)
+		}
+		hOK := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			getFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+				return &flightinspection.FlightInspection{
+					ID:             uuidv7.MustBytes(),
+					InspectionDate: time.Date(2026, 4, 9, 0, 0, 0, 0, time.UTC),
+					Status:         flightinspection.StatusDraft,
+					CreatedAt:      time.Now().UTC(),
+					UpdatedAt:      time.Now().UTC(),
+				}, nil
+			},
+		})
+		code, body := doReqFI(t, newFIApp(hOK), http.MethodGet, "/fi/"+id, nil)
+		if code != http.StatusOK || !strings.Contains(body, `"flight_inspection"`) {
+			t.Fatalf("expected 200 got %d body=%s", code, body)
+		}
+	})
+
+	t.Run("update branches", func(t *testing.T) {
+		h := NewFlightInspectionHandler(&flightInspectionServiceMock{})
+		code, _ := doReqFI(t, newFIApp(h), http.MethodPatch, "/fi/bad", []byte(`{}`))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		id := mustUUIDStringHospital(t, uuidv7.MustBytes())
+		code, _ = doReqFI(t, newFIApp(h), http.MethodPatch, "/fi/"+id, []byte(`{"data":`))
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+		code, _ = doReqFI(t, newFIApp(h), http.MethodPatch, "/fi/"+id, []byte(`{}`))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		code, _ = doReqFI(t, newFIApp(h), http.MethodPatch, "/fi/"+id, []byte(`{"data":{"type":"flight_inspection","id":"","attributes":{"status":"Draft"}}}`))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+		code, _ = doReqFI(t, newFIApp(h), http.MethodPatch, "/fi/"+id, []byte(`{"data":{"type":"flight_inspection","id":"`+id+`","attributes":{}}}`))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+
+		hGetErr := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			getFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) { return nil, errors.New("x") },
+		})
+		code, _ = doReqFI(t, newFIApp(hGetErr), http.MethodPatch, "/fi/"+id, []byte(`{"data":{"type":"flight_inspection","id":"`+id+`","attributes":{"status":"Draft"}}}`))
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+
+		hNot := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			getFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) { return nil, nil },
+		})
+		code, _ = doReqFI(t, newFIApp(hNot), http.MethodPatch, "/fi/"+id, []byte(`{"data":{"type":"flight_inspection","id":"`+id+`","attributes":{"status":"Draft"}}}`))
+		if code != http.StatusNotFound {
+			t.Fatalf("expected 404 got %d", code)
+		}
+
+		row := &flightinspection.FlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC(), Status: flightinspection.StatusDraft}
+		hBadDate := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			getFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) { return row, nil },
+		})
+		code, _ = doReqFI(t, newFIApp(hBadDate), http.MethodPatch, "/fi/"+id, []byte(`{"data":{"type":"flight_inspection","id":"`+id+`","attributes":{"inspection_date":"x"}}}`))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+
+		hBadStatus := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			getFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) { return row, nil },
+		})
+		code, _ = doReqFI(t, newFIApp(hBadStatus), http.MethodPatch, "/fi/"+id, []byte(`{"data":{"type":"flight_inspection","id":"`+id+`","attributes":{"status":"BAD"}}}`))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", code)
+		}
+
+		hUpdErr := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			getFn:    func(context.Context, []byte) (*flightinspection.FlightInspection, error) { return row, nil },
+			updateFn: func(context.Context, *flightinspection.FlightInspection) error { return errors.New("x") },
+		})
+		code, _ = doReqFI(t, newFIApp(hUpdErr), http.MethodPatch, "/fi/"+id, []byte(`{"data":{"type":"flight_inspection","id":"`+id+`","attributes":{"status":"Draft"}}}`))
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+
+		hOK := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			getFn: func(_ context.Context, _ []byte) (*flightinspection.FlightInspection, error) {
+				return &flightinspection.FlightInspection{
+					ID:             uuidv7.MustBytes(),
+					InspectionDate: time.Date(2026, 4, 9, 0, 0, 0, 0, time.UTC),
+					Status:         flightinspection.StatusDraft,
+					CreatedAt:      time.Now().UTC(),
+					UpdatedAt:      time.Now().UTC(),
+				}, nil
+			},
+			updateFn: func(context.Context, *flightinspection.FlightInspection) error { return nil },
+		})
+		code, _ = doReqFI(t, newFIApp(hOK), http.MethodPatch, "/fi/"+id, []byte(`{"data":{"type":"flight_inspection","id":"`+id+`","attributes":{"status":"Completed"}}}`))
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		code, _ = doReqFI(t, newFIApp(hOK), http.MethodPatch, "/fi/"+id, []byte(`{"data":{"type":"flight_inspection","id":"`+id+`","attributes":{"inspection_date":"2026-04-10"}}}`))
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+
+		calls := 0
+		hFallback := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			getFn: func(_ context.Context, _ []byte) (*flightinspection.FlightInspection, error) {
+				calls++
+				if calls == 1 {
+					return &flightinspection.FlightInspection{
+						ID:             uuidv7.MustBytes(),
+						InspectionDate: time.Date(2026, 4, 9, 0, 0, 0, 0, time.UTC),
+						Status:         flightinspection.StatusDraft,
+						CreatedAt:      time.Now().UTC(),
+						UpdatedAt:      time.Now().UTC(),
+					}, nil
+				}
+				return nil, errors.New("reload failed")
+			},
+			updateFn: func(context.Context, *flightinspection.FlightInspection) error { return nil },
+		})
+		code, _ = doReqFI(t, newFIApp(hFallback), http.MethodPatch, "/fi/"+id, []byte(`{"data":{"type":"flight_inspection","id":"`+id+`","attributes":{"status":"InProgress"}}}`))
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+	})
+
+	t.Run("list branches and resource helper", func(t *testing.T) {
+		hErr := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			listFn: func(context.Context, string, int, int) ([]flightinspection.FlightInspection, int64, error) {
+				return nil, 0, errors.New("x")
+			},
+		})
+		code, _ := doReqFI(t, newFIApp(hErr), http.MethodGet, "/fi?page[number]=0&page[size]=200", nil)
+		if code != http.StatusBadRequest {
+			t.Fatalf("expected 400 got %d", code)
+		}
+
+		hOK := NewFlightInspectionHandler(&flightInspectionServiceMock{
+			listFn: func(_ context.Context, _ string, limit, offset int) ([]flightinspection.FlightInspection, int64, error) {
+				if offset != 0 {
+					t.Fatalf("unexpected page args")
+				}
+				return []flightinspection.FlightInspection{{
+					ID:             uuidv7.MustBytes(),
+					InspectionDate: time.Date(2026, 4, 9, 0, 0, 0, 0, time.UTC),
+					Status:         flightinspection.StatusDraft,
+					CreatedAt:      time.Now().UTC(),
+					UpdatedAt:      time.Now().UTC(),
+				}}, 1, nil
+			},
+		})
+		code, _ = doReqFI(t, newFIApp(hOK), http.MethodGet, "/fi?page[number]=0&page[size]=200", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+		code, _ = doReqFI(t, newFIApp(hOK), http.MethodGet, "/fi?page[number]=-1&page[size]=-1", nil)
+		if code != http.StatusOK {
+			t.Fatalf("expected 200 got %d", code)
+		}
+
+		now := time.Now().UTC()
+		ref := flightInspectionResource(&flightinspection.FlightInspection{
+			ID:             uuidv7.MustBytes(),
+			InspectionDate: now,
+			Status:         flightinspection.StatusInProgress,
+			CreatedAt:      now,
+			UpdatedAt:      now,
+		})
+		if ref.Type != "flight_inspection" || ref.Attributes.Status == "" {
+			t.Fatal("expected resource mapped")
+		}
+	})
+}
diff --git a/internal/transport/http/handlers/flight_prep_check_handler.go b/internal/transport/http/handlers/flight_prep_check_handler.go
new file mode 100644
index 0000000..fb44938
--- /dev/null
+++ b/internal/transport/http/handlers/flight_prep_check_handler.go
@@ -0,0 +1,117 @@
+package handlers
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	flightprepcheck "wucher/internal/domain/flight_prep_check"
+	"wucher/internal/shared/pkg/appctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+)
+
+type FlightPrepCheckHandler struct {
+	service flightprepcheck.Service
+	repo    flightprepcheck.Repository
+}
+
+func NewFlightPrepCheckHandler(service flightprepcheck.Service, repo flightprepcheck.Repository) *FlightPrepCheckHandler {
+	return &FlightPrepCheckHandler{service: service, repo: repo}
+}
+
+// InitializeChecks creates initial flight prep checks for an inspection.
+func (h *FlightPrepCheckHandler) InitializeChecks(c *fiber.Ctx) error {
+	flightInspectionID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("flight_inspection_id", "")))
+	if err != nil {
+		return c.Status(http.StatusBadRequest).JSON(fiber.Map{"errors": []fiber.Map{{"code": 400, "title": "Invalid ID", "detail": "flight_inspection_id must be a valid UUID"}}})
+	}
+	userID, _ := c.Locals("user_id").([]byte)
+	ctx := appctx.WithUserID(c.Context(), userID)
+	created, svcErr := h.service.InitializeChecks(ctx, flightInspectionID)
+	if svcErr != nil {
+		if ve, ok := svcErr.(*flightprepcheck.ValidationError); ok {
+			return c.Status(ve.Status).JSON(fiber.Map{"errors": []fiber.Map{{"code": ve.Status, "title": ve.Title, "detail": ve.Detail}}})
+		}
+		return c.Status(http.StatusInternalServerError).JSON(fiber.Map{"errors": []fiber.Map{{"code": 500, "title": "Internal Error", "detail": svcErr.Error()}}})
+	}
+	return c.Status(http.StatusCreated).JSON(fiber.Map{"data": fiber.Map{"created": created}})
+}
+
+// ListChecks returns flight prep checks for an inspection.
+func (h *FlightPrepCheckHandler) ListChecks(c *fiber.Ctx) error {
+	flightInspectionID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("flight_inspection_id", "")))
+	if err != nil {
+		return c.Status(http.StatusBadRequest).JSON(fiber.Map{"errors": []fiber.Map{{"code": 400, "title": "Invalid ID", "detail": "flight_inspection_id must be a valid UUID"}}})
+	}
+	userID, _ := c.Locals("user_id").([]byte)
+	ctx := appctx.WithUserID(c.Context(), userID)
+	row, svcErr := h.service.GetByFlightInspection(ctx, flightInspectionID)
+	if svcErr != nil {
+		if ve, ok := svcErr.(*flightprepcheck.ValidationError); ok {
+			return c.Status(ve.Status).JSON(fiber.Map{"errors": []fiber.Map{{"code": ve.Status, "title": ve.Title, "detail": ve.Detail}}})
+		}
+		return c.Status(http.StatusInternalServerError).JSON(fiber.Map{"errors": []fiber.Map{{"code": 500, "title": "Internal Error", "detail": svcErr.Error()}}})
+	}
+	if row == nil {
+		return c.Status(http.StatusNotFound).JSON(fiber.Map{"errors": []fiber.Map{{"code": 404, "title": "Not Found", "detail": "flight prep inspection not found"}}})
+	}
+	return c.Status(http.StatusOK).JSON(fiber.Map{"data": dto.ToFlightPrepCheckDTO(row)})
+}
+
+// UpdateCheck updates a single flight prep check row.
+func (h *FlightPrepCheckHandler) UpdateCheck(c *fiber.Ctx) error {
+	checkID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("check_id", "")))
+	if err != nil {
+		return c.Status(http.StatusBadRequest).JSON(fiber.Map{"errors": []fiber.Map{{"code": 400, "title": "Invalid ID", "detail": "check_id must be a valid UUID"}}})
+	}
+
+	var req dto.FlightPrepCheckUpsertRequest
+	if parseErr := c.BodyParser(&req); parseErr != nil {
+		return c.Status(http.StatusBadRequest).JSON(fiber.Map{"errors": []fiber.Map{{"code": 400, "title": "Invalid Request", "detail": parseErr.Error()}}})
+	}
+
+	userID, _ := c.Locals("user_id").([]byte)
+	ctx := appctx.WithUserID(c.Context(), userID)
+	row, svcErr := h.service.UpdateCheck(ctx, checkID, &flightprepcheck.UpsertRequest{
+		NOTAMBriefing:         req.Data.Attributes.NotamBriefing,
+		WeatherBriefing:       req.Data.Attributes.WeatherBriefing,
+		OperationalFlightPlan: req.Data.Attributes.OperationalFlightPlan,
+	})
+	if svcErr != nil {
+		if ve, ok := svcErr.(*flightprepcheck.ValidationError); ok {
+			return c.Status(ve.Status).JSON(fiber.Map{"errors": []fiber.Map{{"code": ve.Status, "title": ve.Title, "detail": ve.Detail}}})
+		}
+		return c.Status(http.StatusInternalServerError).JSON(fiber.Map{"errors": []fiber.Map{{"code": 500, "title": "Internal Error", "detail": svcErr.Error()}}})
+	}
+	return c.Status(http.StatusOK).JSON(fiber.Map{"data": dto.ToFlightPrepCheckDTO(row)})
+}
+
+// BulkUpdateChecks updates flight prep checks by inspection id.
+func (h *FlightPrepCheckHandler) BulkUpdateChecks(c *fiber.Ctx) error {
+	flightInspectionID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("flight_inspection_id", "")))
+	if err != nil {
+		return c.Status(http.StatusBadRequest).JSON(fiber.Map{"errors": []fiber.Map{{"code": 400, "title": "Invalid ID", "detail": "flight_inspection_id must be a valid UUID"}}})
+	}
+
+	var req dto.FlightPrepCheckUpsertRequest
+	if parseErr := c.BodyParser(&req); parseErr != nil {
+		return c.Status(http.StatusBadRequest).JSON(fiber.Map{"errors": []fiber.Map{{"code": 400, "title": "Invalid Request", "detail": parseErr.Error()}}})
+	}
+
+	userID, _ := c.Locals("user_id").([]byte)
+	ctx := appctx.WithUserID(c.Context(), userID)
+	row, svcErr := h.service.UpsertByFlightInspection(ctx, flightInspectionID, &flightprepcheck.UpsertRequest{
+		NOTAMBriefing:         req.Data.Attributes.NotamBriefing,
+		WeatherBriefing:       req.Data.Attributes.WeatherBriefing,
+		OperationalFlightPlan: req.Data.Attributes.OperationalFlightPlan,
+	})
+	if svcErr != nil {
+		if ve, ok := svcErr.(*flightprepcheck.ValidationError); ok {
+			return c.Status(ve.Status).JSON(fiber.Map{"errors": []fiber.Map{{"code": ve.Status, "title": ve.Title, "detail": ve.Detail}}})
+		}
+		return c.Status(http.StatusInternalServerError).JSON(fiber.Map{"errors": []fiber.Map{{"code": 500, "title": "Internal Error", "detail": svcErr.Error()}}})
+	}
+	return c.Status(http.StatusOK).JSON(fiber.Map{"data": dto.ToFlightPrepCheckDTO(row)})
+}
diff --git a/internal/transport/http/handlers/flight_prep_check_handler_test.go b/internal/transport/http/handlers/flight_prep_check_handler_test.go
new file mode 100644
index 0000000..ed65ec5
--- /dev/null
+++ b/internal/transport/http/handlers/flight_prep_check_handler_test.go
@@ -0,0 +1,380 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	flightprepcheck "wucher/internal/domain/flight_prep_check"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type flightPrepServiceMock struct {
+	initFn   func(context.Context, []byte) (int, error)
+	getFn    func(context.Context, []byte) (*flightprepcheck.FlightPrepCheck, error)
+	updateFn func(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error)
+	upsertFn func(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error)
+}
+
+func (m *flightPrepServiceMock) InitializeChecks(ctx context.Context, id []byte) (int, error) {
+	if m.initFn != nil {
+		return m.initFn(ctx, id)
+	}
+	return 0, nil
+}
+
+func (m *flightPrepServiceMock) GetByFlightInspection(ctx context.Context, id []byte) (*flightprepcheck.FlightPrepCheck, error) {
+	if m.getFn != nil {
+		return m.getFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *flightPrepServiceMock) UpdateCheck(ctx context.Context, id []byte, req *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+	if m.updateFn != nil {
+		return m.updateFn(ctx, id, req)
+	}
+	return nil, nil
+}
+
+func (m *flightPrepServiceMock) UpsertByFlightInspection(ctx context.Context, id []byte, req *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+	if m.upsertFn != nil {
+		return m.upsertFn(ctx, id, req)
+	}
+	return nil, nil
+}
+
+type flightPrepRepoMock struct{}
+
+func (flightPrepRepoMock) Create(context.Context, *flightprepcheck.FlightPrepCheck) error { return nil }
+func (flightPrepRepoMock) Update(context.Context, *flightprepcheck.FlightPrepCheck) error { return nil }
+func (flightPrepRepoMock) GetByID(context.Context, []byte) (*flightprepcheck.FlightPrepCheck, error) {
+	return nil, nil
+}
+func (flightPrepRepoMock) GetByFlightInspectionID(context.Context, []byte) (*flightprepcheck.FlightPrepCheck, error) {
+	return nil, nil
+}
+
+func newFlightPrepApp(h *FlightPrepCheckHandler) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", uuidv7.MustBytes())
+		return c.Next()
+	})
+	app.Post("/inspection/:flight_inspection_id/init", h.InitializeChecks)
+	app.Get("/inspection/:flight_inspection_id", h.ListChecks)
+	app.Patch("/check/:check_id", h.UpdateCheck)
+	app.Patch("/inspection/:flight_inspection_id/bulk", h.BulkUpdateChecks)
+	return app
+}
+
+func mustUUIDStr(t *testing.T) string {
+	t.Helper()
+	s, err := uuidv7.String(uuidv7.MustNew())
+	if err != nil {
+		t.Fatalf("uuid: %v", err)
+	}
+	return s
+}
+
+func doReq(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, string) {
+	t.Helper()
+	var rdr io.Reader
+	if body != nil {
+		rdr = bytes.NewReader(body)
+	}
+	req, err := http.NewRequest(method, path, rdr)
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	defer resp.Body.Close()
+	out, _ := io.ReadAll(resp.Body)
+	return resp, string(out)
+}
+
+func TestFlightPrepCheckHandler_New(t *testing.T) {
+	h := NewFlightPrepCheckHandler(&flightPrepServiceMock{}, flightPrepRepoMock{})
+	if h == nil || h.service == nil || h.repo == nil {
+		t.Fatal("expected handler initialized")
+	}
+}
+
+func TestFlightPrepCheckHandler_InitializeChecks(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		h := NewFlightPrepCheckHandler(&flightPrepServiceMock{}, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		resp, _ := doReq(t, app, http.MethodPost, "/inspection/bad/init", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			initFn: func(context.Context, []byte) (int, error) {
+				return 0, &flightprepcheck.ValidationError{Status: http.StatusUnprocessableEntity, Title: "X", Detail: "y"}
+			},
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		id := mustUUIDStr(t)
+		resp, _ := doReq(t, app, http.MethodPost, "/inspection/"+id+"/init", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("internal error", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			initFn: func(context.Context, []byte) (int, error) {
+				return 0, errors.New("boom")
+			},
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		id := mustUUIDStr(t)
+		resp, _ := doReq(t, app, http.MethodPost, "/inspection/"+id+"/init", nil)
+		if resp.StatusCode != http.StatusInternalServerError {
+			t.Fatalf("expected 500, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			initFn: func(context.Context, []byte) (int, error) { return 3, nil },
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		id := mustUUIDStr(t)
+		resp, body := doReq(t, app, http.MethodPost, "/inspection/"+id+"/init", nil)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d body=%s", resp.StatusCode, body)
+		}
+		if !strings.Contains(body, `"created":3`) {
+			t.Fatalf("expected created=3 in body, got %s", body)
+		}
+	})
+}
+
+func TestFlightPrepCheckHandler_ListChecks(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		h := NewFlightPrepCheckHandler(&flightPrepServiceMock{}, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		resp, _ := doReq(t, app, http.MethodGet, "/inspection/bad", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			getFn: func(context.Context, []byte) (*flightprepcheck.FlightPrepCheck, error) {
+				return nil, &flightprepcheck.ValidationError{Status: http.StatusUnprocessableEntity, Title: "X", Detail: "y"}
+			},
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		resp, _ := doReq(t, app, http.MethodGet, "/inspection/"+mustUUIDStr(t), nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("internal error", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			getFn: func(context.Context, []byte) (*flightprepcheck.FlightPrepCheck, error) {
+				return nil, errors.New("boom")
+			},
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		resp, _ := doReq(t, app, http.MethodGet, "/inspection/"+mustUUIDStr(t), nil)
+		if resp.StatusCode != http.StatusInternalServerError {
+			t.Fatalf("expected 500, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			getFn: func(context.Context, []byte) (*flightprepcheck.FlightPrepCheck, error) {
+				return nil, nil
+			},
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		resp, _ := doReq(t, app, http.MethodGet, "/inspection/"+mustUUIDStr(t), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			getFn: func(context.Context, []byte) (*flightprepcheck.FlightPrepCheck, error) {
+				return &flightprepcheck.FlightPrepCheck{
+					ID:                 uuidv7.MustBytes(),
+					FlightInspectionID: uuidv7.MustBytes(),
+					NOTAMBriefing:      true,
+					CreatedAt:          time.Now().UTC(),
+					UpdatedAt:          time.Now().UTC(),
+				}, nil
+			},
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		resp, body := doReq(t, app, http.MethodGet, "/inspection/"+mustUUIDStr(t), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, body)
+		}
+		if !strings.Contains(body, `"flight_prep_check"`) {
+			t.Fatalf("expected resource type in body: %s", body)
+		}
+	})
+}
+
+func TestFlightPrepCheckHandler_UpdateCheck(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		h := NewFlightPrepCheckHandler(&flightPrepServiceMock{}, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		resp, _ := doReq(t, app, http.MethodPatch, "/check/bad", []byte(`{}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		h := NewFlightPrepCheckHandler(&flightPrepServiceMock{}, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		resp, _ := doReq(t, app, http.MethodPatch, "/check/"+mustUUIDStr(t), []byte(`{not-json`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			updateFn: func(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+				return nil, &flightprepcheck.ValidationError{Status: http.StatusUnprocessableEntity, Title: "X", Detail: "y"}
+			},
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		body := []byte(`{"data":{"type":"flight_prep_check_upsert","attributes":{"notam_briefing":true}}}`)
+		resp, _ := doReq(t, app, http.MethodPatch, "/check/"+mustUUIDStr(t), body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("internal error", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			updateFn: func(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+				return nil, errors.New("boom")
+			},
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		body := []byte(`{"data":{"type":"flight_prep_check_upsert","attributes":{"notam_briefing":true}}}`)
+		resp, _ := doReq(t, app, http.MethodPatch, "/check/"+mustUUIDStr(t), body)
+		if resp.StatusCode != http.StatusInternalServerError {
+			t.Fatalf("expected 500, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			updateFn: func(_ context.Context, _ []byte, r *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+				if r.NOTAMBriefing == nil || !*r.NOTAMBriefing {
+					t.Fatal("expected NOTAMBriefing true")
+				}
+				return &flightprepcheck.FlightPrepCheck{ID: uuidv7.MustBytes(), FlightInspectionID: uuidv7.MustBytes()}, nil
+			},
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		body := []byte(`{"data":{"type":"flight_prep_check_upsert","attributes":{"notam_briefing":true,"weather_briefing":false,"operational_flight_plan":true}}}`)
+		resp, b := doReq(t, app, http.MethodPatch, "/check/"+mustUUIDStr(t), body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, b)
+		}
+	})
+}
+
+func TestFlightPrepCheckHandler_BulkUpdateChecks(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		h := NewFlightPrepCheckHandler(&flightPrepServiceMock{}, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		resp, _ := doReq(t, app, http.MethodPatch, "/inspection/bad/bulk", []byte(`{}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		h := NewFlightPrepCheckHandler(&flightPrepServiceMock{}, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		resp, _ := doReq(t, app, http.MethodPatch, "/inspection/"+mustUUIDStr(t)+"/bulk", []byte(`{not-json`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			upsertFn: func(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+				return nil, &flightprepcheck.ValidationError{Status: http.StatusUnprocessableEntity, Title: "X", Detail: "y"}
+			},
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		body := []byte(`{"data":{"type":"flight_prep_check_upsert","attributes":{"notam_briefing":true}}}`)
+		resp, _ := doReq(t, app, http.MethodPatch, "/inspection/"+mustUUIDStr(t)+"/bulk", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("internal error", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			upsertFn: func(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+				return nil, errors.New("boom")
+			},
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		body := []byte(`{"data":{"type":"flight_prep_check_upsert","attributes":{"notam_briefing":true}}}`)
+		resp, _ := doReq(t, app, http.MethodPatch, "/inspection/"+mustUUIDStr(t)+"/bulk", body)
+		if resp.StatusCode != http.StatusInternalServerError {
+			t.Fatalf("expected 500, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		svc := &flightPrepServiceMock{
+			upsertFn: func(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+				return &flightprepcheck.FlightPrepCheck{ID: uuidv7.MustBytes(), FlightInspectionID: uuidv7.MustBytes()}, nil
+			},
+		}
+		h := NewFlightPrepCheckHandler(svc, flightPrepRepoMock{})
+		app := newFlightPrepApp(h)
+		body := []byte(`{"data":{"type":"flight_prep_check_upsert","attributes":{"notam_briefing":true}}}`)
+		resp, b := doReq(t, app, http.MethodPatch, "/inspection/"+mustUUIDStr(t)+"/bulk", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, b)
+		}
+	})
+}
diff --git a/internal/transport/http/handlers/fm_report_breakdown_test.go b/internal/transport/http/handlers/fm_report_breakdown_test.go
new file mode 100644
index 0000000..8f48145
--- /dev/null
+++ b/internal/transport/http/handlers/fm_report_breakdown_test.go
@@ -0,0 +1,128 @@
+package handlers
+
+import (
+	"testing"
+
+	fmreport "wucher/internal/domain/fm_report"
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+)
+
+func strptr(s string) *string { return &s }
+
+func approx(a, b float64) bool { d := a - b; return d < 1e-9 && d > -1e-9 }
+
+func TestBuildFMReportUsageBreakdown(t *testing.T) {
+	usage := &helicopterusage.HelicopterUsage{
+		TotalAirframeHours:  1523.5,
+		TotalAirframeCycles: 320,
+		TotalEngine1Hours:   1523.5,
+		TotalEngine1GpcNgN1: 200.0,
+		TotalEngine1PtcNfN2: 150.0,
+		TotalEngine1Ccc:     44,
+		TotalEngine2Hours:   1523.5,
+		TotalEngine2GpcNgN1: 100.0,
+	}
+	today := helicopterusage.FlightDayStats{AirframeHours: 11.2, AirframeCycles: 2}
+	report := &fmreport.Report{
+		Engine1GpcN1: strptr("GPC/N1 63.2"), // must parse 63.2, not the "1" of N1
+		Engine1PtcN2: strptr("PTC/N2 61.8"),
+		Engine2GpcN1: strptr("GPC/N1 40.5"),
+	}
+
+	bd := buildFMReportUsageBreakdown(usage, today, report, true, true)
+
+	// Grouped by row: Total / Today / Prev(=Total-Today).
+	if bd.Total.Airframe.Hours != 1523.5 || bd.Total.Airframe.Cycles != 320 {
+		t.Fatalf("total airframe = %+v", bd.Total.Airframe)
+	}
+	if bd.Today.Airframe.Hours != 11.2 || bd.Today.Airframe.Cycles != 2 {
+		t.Fatalf("today airframe = %+v", bd.Today.Airframe)
+	}
+	if !approx(bd.Prev.Airframe.Hours, 1523.5-11.2) || bd.Prev.Airframe.Cycles != 318 {
+		t.Fatalf("prev airframe = %+v", bd.Prev.Airframe)
+	}
+	// Engine1 hours mirror airframe today.
+	if bd.Today.Engine1.Hours != 11.2 {
+		t.Fatalf("today engine1 hours = %v, want 11.2", bd.Today.Engine1.Hours)
+	}
+	// Engine1 GPC parsed 63.2 (NOT the "1" of N1); prev = 200 - 63.2.
+	if bd.Today.Engine1.GpcNgN1 != 63.2 {
+		t.Fatalf("today engine1 gpc = %v, want 63.2 (parser grabbed label digit?)", bd.Today.Engine1.GpcNgN1)
+	}
+	if !approx(bd.Prev.Engine1.GpcNgN1, 200.0-63.2) {
+		t.Fatalf("prev engine1 gpc = %v, want %v", bd.Prev.Engine1.GpcNgN1, 200.0-63.2)
+	}
+	if bd.Today.Engine1.PtcNfN2 != 61.8 {
+		t.Fatalf("today engine1 ptc = %v, want 61.8", bd.Today.Engine1.PtcNfN2)
+	}
+	// CCC: no flight contribution -> today 0, total 44, prev 44.
+	if bd.Today.Engine1.Ccc != 0 || bd.Total.Engine1.Ccc != 44 || bd.Prev.Engine1.Ccc != 44 {
+		t.Fatalf("engine1 ccc rows: today=%v total=%v prev=%v", bd.Today.Engine1.Ccc, bd.Total.Engine1.Ccc, bd.Prev.Engine1.Ccc)
+	}
+	if bd.Today.Engine2.GpcNgN1 != 40.5 {
+		t.Fatalf("today engine2 gpc = %v, want 40.5", bd.Today.Engine2.GpcNgN1)
+	}
+	// Counters: total from usage, today = this flight (+1 flight report), prev = total - today.
+	if bd.Total.Counters.Landings != 0 { // usage above has no landings set
+		t.Fatalf("total landings = %v, want 0", bd.Total.Counters.Landings)
+	}
+	if bd.Today.Counters.FlightReports != 1 {
+		t.Fatalf("today flight_reports = %v, want 1", bd.Today.Counters.FlightReports)
+	}
+}
+
+func TestBuildFMReportUsageBreakdownCounters(t *testing.T) {
+	usage := &helicopterusage.HelicopterUsage{
+		TotalLanding:         10,
+		TotalFlightReport:    5,
+		TotalHookRelease:     3,
+		TotalRotorBrakeCycle: 2,
+	}
+	today := helicopterusage.FlightDayStats{Landing: 1, HookRelease: 1, RotorBrakeCycle: 1}
+	bd := buildFMReportUsageBreakdown(usage, today, &fmreport.Report{}, true, true)
+
+	if bd.Total.Counters.Landings != 10 || bd.Today.Counters.Landings != 1 || bd.Prev.Counters.Landings != 9 {
+		t.Fatalf("landings rows: total=%v today=%v prev=%v", bd.Total.Counters.Landings, bd.Today.Counters.Landings, bd.Prev.Counters.Landings)
+	}
+	// flight_reports: total 5, today 1 (this report), prev 4.
+	if bd.Total.Counters.FlightReports != 5 || bd.Today.Counters.FlightReports != 1 || bd.Prev.Counters.FlightReports != 4 {
+		t.Fatalf("flight_reports rows: total=%v today=%v prev=%v", bd.Total.Counters.FlightReports, bd.Today.Counters.FlightReports, bd.Prev.Counters.FlightReports)
+	}
+	if bd.Prev.Counters.HookReleases != 2 || bd.Prev.Counters.RotorBrakeCycles != 1 {
+		t.Fatalf("hook/rotor prev: %v / %v", bd.Prev.Counters.HookReleases, bd.Prev.Counters.RotorBrakeCycles)
+	}
+}
+
+func TestBuildFMReportUsageBreakdownSingleEngine(t *testing.T) {
+	usage := &helicopterusage.HelicopterUsage{
+		TotalAirframeHours: 1523.5,
+		TotalEngine1Hours:  1523.5,
+		TotalEngine2Hours:  1523.5, // stored, but must be hidden for single-engine
+	}
+	today := helicopterusage.FlightDayStats{AirframeHours: 11.2}
+	report := &fmreport.Report{Engine2GpcN1: strptr("GPC/N1 40.5")}
+
+	bd := buildFMReportUsageBreakdown(usage, today, report, true, false)
+	if bd.Today.Engine1.Hours != 11.2 {
+		t.Fatalf("engine1 should still be populated, got %+v", bd.Today.Engine1)
+	}
+	// Engine 2 empty across all three rows.
+	if bd.Total.Engine2.Hours != 0 || bd.Today.Engine2.Hours != 0 || bd.Prev.Engine2.Hours != 0 ||
+		bd.Today.Engine2.GpcNgN1 != 0 {
+		t.Fatalf("engine2 must be empty for single-engine: total=%+v today=%+v prev=%+v",
+			bd.Total.Engine2, bd.Today.Engine2, bd.Prev.Engine2)
+	}
+}
+
+func TestBuildFMReportUsageBreakdownNilUsage(t *testing.T) {
+	today := helicopterusage.FlightDayStats{AirframeHours: 11.2, AirframeCycles: 2}
+	bd := buildFMReportUsageBreakdown(nil, today, &fmreport.Report{}, true, true)
+	// No cumulative yet: total 0, today = flight, prev = -today.
+	if bd.Total.Airframe.Hours != 0 || bd.Today.Airframe.Hours != 11.2 || bd.Prev.Airframe.Hours != -11.2 {
+		t.Fatalf("nil-usage airframe hours rows: total=%v today=%v prev=%v",
+			bd.Total.Airframe.Hours, bd.Today.Airframe.Hours, bd.Prev.Airframe.Hours)
+	}
+	if bd.Prev.Airframe.Cycles != -2 {
+		t.Fatalf("nil-usage prev cycles = %v, want -2", bd.Prev.Airframe.Cycles)
+	}
+}
diff --git a/internal/transport/http/handlers/fm_report_handler.go b/internal/transport/http/handlers/fm_report_handler.go
new file mode 100644
index 0000000..004a76b
--- /dev/null
+++ b/internal/transport/http/handlers/fm_report_handler.go
@@ -0,0 +1,1562 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	filemanager "wucher/internal/domain/file_manager"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	fmreport "wucher/internal/domain/fm_report"
+	helicopterdomain "wucher/internal/domain/helicopter"
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+	takeoverdomain "wucher/internal/domain/takeover"
+	"wucher/internal/shared/pkg/metricparse"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	rootdto "wucher/internal/transport/http/dto"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type helicopterLookupService interface {
+	GetByID(context.Context, []byte) (*helicopterdomain.Helicopter, error)
+}
+
+type FMReportHandler struct {
+	svc                   fmreport.Service
+	flight                *FlightHandler
+	mission               *MissionHandler
+	flightInspection      flightinspection.FlightInspectionService
+	afterFlightInspection afterflightinspection.Service
+	fleetStatus           *FleetStatusHandler
+	helicopterUsage       helicopterusage.Service
+	helicopter            helicopterLookupService
+	takeover              takeoverLookupService
+	storage               fileManagerDownloadURLStorage
+	fileManager           filemanager.Service
+	validate              *validators.Validator
+}
+
+type takeoverLookupService interface {
+	GetByID(context.Context, []byte) (*takeoverdomain.TakeoverAc, error)
+}
+
+type fmReportCompleter interface {
+	Complete(context.Context, []byte) (*fmreport.Report, error)
+}
+
+func NewFMReportHandler(svc fmreport.Service) *FMReportHandler {
+	return &FMReportHandler{svc: svc, validate: validators.New()}
+}
+
+func (h *FMReportHandler) WithFlightHandler(flightHandler *FlightHandler) *FMReportHandler {
+	h.flight = flightHandler
+	return h
+}
+
+func (h *FMReportHandler) WithMissionHandler(missionHandler *MissionHandler) *FMReportHandler {
+	h.mission = missionHandler
+	return h
+}
+
+func (h *FMReportHandler) WithFlightInspectionService(svc flightinspection.FlightInspectionService) *FMReportHandler {
+	h.flightInspection = svc
+	return h
+}
+
+func (h *FMReportHandler) WithAfterFlightInspectionService(svc afterflightinspection.Service) *FMReportHandler {
+	h.afterFlightInspection = svc
+	return h
+}
+
+func (h *FMReportHandler) WithHelicopterUsageService(svc helicopterusage.Service) *FMReportHandler {
+	h.helicopterUsage = svc
+	return h
+}
+
+func (h *FMReportHandler) WithFleetStatusHandler(fleetStatusHandler *FleetStatusHandler) *FMReportHandler {
+	h.fleetStatus = fleetStatusHandler
+	return h
+}
+
+func (h *FMReportHandler) WithTakeoverService(takeoverSvc takeoverLookupService) *FMReportHandler {
+	h.takeover = takeoverSvc
+	return h
+}
+
+func (h *FMReportHandler) WithFileStorage(storage fileManagerDownloadURLStorage) *FMReportHandler {
+	h.storage = storage
+	return h
+}
+
+func (h *FMReportHandler) WithFileManagerService(fileManager filemanager.Service) *FMReportHandler {
+	h.fileManager = fileManager
+	return h
+}
+
+func (h *FMReportHandler) WithHelicopterService(svc helicopterLookupService) *FMReportHandler {
+	h.helicopter = svc
+	return h
+}
+
+// GetFMReport godoc
+// @Summary Get FM report by flight ID
+// @Description Returns a complete FM report for a flight. The persisted table keeps only the report keys; the response preloads flight, missions, flight inspection, and after-flight inspection details. It also embeds `fleet_status` (next inspection / maintenance schedules + base hours, component summary, EASA maintenance release) — a snapshot frozen when the report was created at after-flight inspection, so later complaints / maintenance changes do not alter a historical report. `fleet_status` is omitted when the helicopter has no fleet status.
+// @Tags Flight Report
+// @Produce json
+// @Param flight_id path string true "Flight ID (UUIDv7)"
+// @Success 200 {object} rootdto.FMReportResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fm-reports/get/{flight_id} [get]
+func (h *FMReportHandler) GetByFlightID(c *fiber.Ctx) error {
+	flightRaw := strings.TrimSpace(c.Params("flight_id"))
+	flightID, err := uuidv7.ParseString(flightRaw)
+	if err != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "flight_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/flight_id"},
+		}})
+	}
+	if h == nil || h.svc == nil || h.flight == nil || h.flight.svc == nil || h.mission == nil || h.mission.svc == nil {
+		return writeFMReportErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	report, err := h.svc.GetByFlightID(c.UserContext(), flightID)
+	if err != nil {
+		return writeFMReportErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if report == nil {
+		return writeFMReportErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "fm report not found for flight",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/flight_id"},
+		}})
+	}
+	payload, err := h.buildFMReportResponse(c, report)
+	if err != nil {
+		return err
+	}
+	return response.Write(c, fiber.StatusOK, payload.Data)
+}
+
+// ListFMReports godoc
+// @Summary List FM reports
+// @Description Returns a paginated list of FM reports. Supports `search`, `filter[search]`, `filter[flight_id]`, `filter[takeover_id]`, `filter[flight_inspection_id]`, `filter[flight_date]`, `filter[has_engine1_gpc_n1]`, `filter[has_engine1_ptc_n2]`, `filter[has_engine2_gpc_n1]`, `filter[has_engine2_ptc_n2]`, `sort`, `page[number]`, `page[size]`, `page`, `size`, and `limit`.
+// @Tags Flight Report
+// @Produce json
+// @Param search query string false "Search text"
+// @Param filter[search] query string false "Search text (JSON:API style)"
+// @Param filter[flight_id] query string false "Filter by flight ID"
+// @Param filter[takeover_id] query string false "Filter by takeover ID"
+// @Param filter[flight_inspection_id] query string false "Filter by flight inspection ID"
+// @Param filter[flight_date] query string false "Filter by flight date (YYYY-MM-DD)"
+// @Param filter[has_engine1_gpc_n1] query bool false "Filter reports with or without engine1_gpc_n1"
+// @Param filter[has_engine1_ptc_n2] query bool false "Filter reports with or without engine1_ptc_n2"
+// @Param filter[has_engine2_gpc_n1] query bool false "Filter reports with or without engine2_gpc_n1"
+// @Param filter[has_engine2_ptc_n2] query bool false "Filter reports with or without engine2_ptc_n2"
+// @Param sort query string false "Sort order: flight_date, -flight_date, created_at, -created_at, updated_at, -updated_at, engine1_gpc_n1, -engine1_gpc_n1, engine1_ptc_n2, -engine1_ptc_n2, engine2_gpc_n1, -engine2_gpc_n1, engine2_ptc_n2, -engine2_ptc_n2"
+// @Param page[number] query int false "Page number"
+// @Param page[size] query int false "Page size"
+// @Param page query int false "Page number (fallback)"
+// @Param size query int false "Page size (fallback)"
+// @Param limit query int false "Page size override"
+// @Success 200 {object} rootdto.FMReportListResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fm-reports/get-all [get]
+func (h *FMReportHandler) List(c *fiber.Ctx) error {
+	if h == nil || h.svc == nil {
+		return writeFMReportErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	offset := (pageNumber - 1) * pageSize
+
+	search := strings.TrimSpace(c.Query("filter[search]"))
+	if search == "" {
+		search = strings.TrimSpace(c.Query("search"))
+	}
+	flightDate := strings.TrimSpace(c.Query("filter[flight_date]"))
+	if flightDate == "" {
+		flightDate = strings.TrimSpace(c.Query("flight_date"))
+	}
+	if flightDate != "" {
+		if _, err := time.Parse("2006-01-02", flightDate); err != nil {
+			return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "flight_date must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/filter[flight_date]"},
+			}})
+		}
+	}
+	fromDate := strings.TrimSpace(c.Query("filter[from_date]"))
+	if fromDate != "" {
+		if _, err := time.Parse("2006-01-02", fromDate); err != nil {
+			return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "from_date must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/filter[from_date]"},
+			}})
+		}
+	}
+	toDate := strings.TrimSpace(c.Query("filter[to_date]"))
+	if toDate != "" {
+		if _, err := time.Parse("2006-01-02", toDate); err != nil {
+			return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "to_date must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/filter[to_date]"},
+			}})
+		}
+	}
+	helicopterIdentifier := strings.TrimSpace(c.Query("filter[helicopter_identifier]"))
+	pilotName := strings.TrimSpace(c.Query("filter[pilot_name]"))
+
+	flightIDRaw := strings.TrimSpace(c.Query("filter[flight_id]"))
+	takeoverIDRaw := strings.TrimSpace(c.Query("filter[takeover_id]"))
+	inspectionIDRaw := strings.TrimSpace(c.Query("filter[flight_inspection_id]"))
+	flightID, errObj := parseOptionalUUID(&flightIDRaw, "/query/filter[flight_id]")
+	if errObj != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	takeoverID, errObj := parseOptionalUUID(&takeoverIDRaw, "/query/filter[takeover_id]")
+	if errObj != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	inspectionID, errObj := parseOptionalUUID(&inspectionIDRaw, "/query/filter[flight_inspection_id]")
+	if errObj != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+
+	var hasEngine1GpcN1 *bool
+	if raw := strings.TrimSpace(c.Query("filter[has_engine1_gpc_n1]")); raw != "" {
+		v, err := strconv.ParseBool(raw)
+		if err != nil {
+			return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "filter[has_engine1_gpc_n1] must be true or false",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/filter[has_engine1_gpc_n1]"},
+			}})
+		}
+		hasEngine1GpcN1 = &v
+	}
+
+	var hasEngine1PtcN2 *bool
+	if raw := strings.TrimSpace(c.Query("filter[has_engine1_ptc_n2]")); raw != "" {
+		v, err := strconv.ParseBool(raw)
+		if err != nil {
+			return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "filter[has_engine1_ptc_n2] must be true or false",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/filter[has_engine1_ptc_n2]"},
+			}})
+		}
+		hasEngine1PtcN2 = &v
+	}
+
+	var hasEngine2GpcN1 *bool
+	if raw := strings.TrimSpace(c.Query("filter[has_engine2_gpc_n1]")); raw != "" {
+		v, err := strconv.ParseBool(raw)
+		if err != nil {
+			return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "filter[has_engine2_gpc_n1] must be true or false",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/filter[has_engine2_gpc_n1]"},
+			}})
+		}
+		hasEngine2GpcN1 = &v
+	}
+
+	var hasEngine2PtcN2 *bool
+	if raw := strings.TrimSpace(c.Query("filter[has_engine2_ptc_n2]")); raw != "" {
+		v, err := strconv.ParseBool(raw)
+		if err != nil {
+			return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "filter[has_engine2_ptc_n2] must be true or false",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/filter[has_engine2_ptc_n2]"},
+			}})
+		}
+		hasEngine2PtcN2 = &v
+	}
+
+	rows, total, err := h.svc.List(c.UserContext(), fmreport.ListFilter{
+		Search:               search,
+		FlightID:             flightID,
+		TakeoverID:           takeoverID,
+		FlightInspectionID:   inspectionID,
+		FlightDate:           flightDate,
+		HasEngine1GpcN1:      hasEngine1GpcN1,
+		HasEngine1PtcN2:      hasEngine1PtcN2,
+		HasEngine2GpcN1:      hasEngine2GpcN1,
+		HasEngine2PtcN2:      hasEngine2PtcN2,
+		Sort:                 strings.TrimSpace(c.Query("sort")),
+		FromDate:             fromDate,
+		ToDate:               toDate,
+		HelicopterIdentifier: helicopterIdentifier,
+		PilotName:            pilotName,
+	}, pageSize, offset)
+	if err != nil {
+		return writeFMReportErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]rootdto.FMReportResource, 0, len(rows))
+	for i := range rows {
+		payload, buildErr := h.buildFMReportResponse(c, &rows[i])
+		if buildErr != nil {
+			return buildErr
+		}
+		data = append(data, payload.Data)
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	})
+}
+
+// UpdateFMReport godoc
+// @Summary Update FM report metrics
+// @Description Update only the engine metric fields for an existing FM report. All other FM report fields stay read-only on this endpoint. The response mirrors the GET FM report and embeds the frozen `fleet_status` snapshot (next inspection / maintenance schedules + base hours, component summary, EASA maintenance release).
+// @Tags Flight Report
+// @Accept json
+// @Produce json
+// @Param flight_id path string true "Flight ID (UUIDv7)"
+// @Param request body requestdto.FMReportUpdateRequest true "JSON:API FM report update request"
+// @Success 200 {object} rootdto.FMReportResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fm-reports/update/{flight_id} [patch]
+func (h *FMReportHandler) UpdateByFlightID(c *fiber.Ctx) error {
+	if h == nil || h.svc == nil {
+		return writeFMReportErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	flightRaw := strings.TrimSpace(c.Params("flight_id"))
+	flightID, err := uuidv7.ParseString(flightRaw)
+	if err != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "flight_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/flight_id"},
+		}})
+	}
+
+	var req requestdto.FMReportUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeFMReportErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	report, err := h.svc.UpdateForFlight(
+		c.UserContext(),
+		flightID,
+		req.Data.Attributes.Engine1GpcN1,
+		req.Data.Attributes.Engine1PtcN2,
+		req.Data.Attributes.Engine2GpcN1,
+		req.Data.Attributes.Engine2PtcN2,
+	)
+	if err != nil {
+		if errors.Is(err, fmreport.ErrCompleted) {
+			return writeFMReportErrors(c, fiber.StatusLocked, []jsonapi.ErrorObject{{
+				Status: "423",
+				Title:  "Locked",
+				Detail: "fm report is completed and can no longer be edited",
+				Source: &jsonapi.ErrorSource{Pointer: "/path/flight_id"},
+			}})
+		}
+		if strings.Contains(strings.ToLower(err.Error()), "not found") {
+			return writeFMReportErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "fm report not found for flight",
+				Source: &jsonapi.ErrorSource{Pointer: "/path/flight_id"},
+			}})
+		}
+		return writeFMReportErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	payload, err := h.buildFMReportResponse(c, report)
+	if err != nil {
+		return err
+	}
+	return response.Write(c, fiber.StatusOK, payload.Data)
+}
+
+// CompleteFMReport godoc
+// @Summary Complete FM report
+// @Description Mark an FM report as completed for a flight. Once completed, the report becomes read-only and flight data edits are locked. Requires a verified security PIN: send the one-time token from POST /auth/pin/verify (action 1a75135b-430a-4592-83e1-6d27814185af) in the X-PIN-Verification-Token header.
+// @Tags Flight Report
+// @Produce json
+// @Param flight_id path string true "Flight ID (UUIDv7)"
+// @Param X-PIN-Verification-Token header string true "One-time security-PIN action token"
+// @Success 200 {object} rootdto.FMReportResponse
+// @Failure 202 {object} jsonapi.ErrorDocument "PIN verification required"
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fm-reports/complete/{flight_id} [post]
+func (h *FMReportHandler) Complete(c *fiber.Ctx) error {
+	if h == nil || h.svc == nil {
+		return writeFMReportErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Complete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	completer, ok := h.svc.(fmReportCompleter)
+	if !ok {
+		return writeFMReportErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Complete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	flightRaw := strings.TrimSpace(c.Params("flight_id"))
+	flightID, err := uuidv7.ParseString(flightRaw)
+	if err != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "flight_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/flight_id"},
+		}})
+	}
+
+	report, err := completer.Complete(c.UserContext(), flightID)
+	if err != nil {
+		if errors.Is(err, fmreport.ErrNotFound) {
+			return writeFMReportErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "fm report not found for flight",
+				Source: &jsonapi.ErrorSource{Pointer: "/path/flight_id"},
+			}})
+		}
+		return writeFMReportErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Complete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	payload, err := h.buildFMReportResponse(c, report)
+	if err != nil {
+		return err
+	}
+	return response.Write(c, fiber.StatusOK, payload.Data)
+}
+
+func (h *FMReportHandler) buildFMReportResponse(c *fiber.Ctx, report *fmreport.Report) (*rootdto.FMReportResponse, error) {
+	if h == nil || h.flight == nil || h.flight.svc == nil || h.mission == nil || h.mission.svc == nil {
+		return nil, writeFMReportErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if report == nil {
+		return nil, writeFMReportErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "fm report not found for flight",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/flight_id"},
+		}})
+	}
+
+	flightRow, err := h.flight.svc.GetByID(c.UserContext(), report.FlightID)
+	if err != nil || flightRow == nil {
+		return nil, writeFMReportErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "flight not found",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/flight_id"},
+		}})
+	}
+
+	flightResource := h.flight.flightResource(c.UserContext(), c, flightRow)
+	missionRows, err := h.mission.svc.ListByFlightID(c.UserContext(), report.FlightID)
+	if err != nil {
+		return nil, writeFMReportErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	missions := make([]responsedto.MissionResource, 0, len(missionRows))
+	for i := range missionRows {
+		resource, buildErr := h.mission.missionResource(c.UserContext(), &missionRows[i])
+		if buildErr != nil {
+			return nil, writeFMReportErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Get failed",
+				Detail: buildErr.Error(),
+			}})
+		}
+		missions = append(missions, resource)
+	}
+
+	var flightInspectionResource *rootdto.FlightInspectionResource
+	if h.flightInspection != nil && len(report.FlightInspectionID) == 16 {
+		if inspectionRow, inspectionErr := h.flightInspection.GetByID(c.UserContext(), report.FlightInspectionID); inspectionErr == nil && inspectionRow != nil {
+			flightInspectionResource = &rootdto.FlightInspectionResource{
+				Type: "flight_inspection",
+				ID:   idString(inspectionRow.ID),
+				Attributes: rootdto.FlightInspectionAttributes{
+					InspectionDate: inspectionRow.InspectionDate.UTC().Format("2006-01-02"),
+					Status:         inspectionRow.Status,
+					CreatedAt:      inspectionRow.CreatedAt.UTC().Format(time.RFC3339),
+					CreatedBy:      uuidStringOrEmpty(inspectionRow.CreatedBy),
+					UpdatedAt:      inspectionRow.UpdatedAt.UTC().Format(time.RFC3339),
+					UpdatedBy:      uuidStringOrEmpty(inspectionRow.UpdatedBy),
+				},
+			}
+		}
+	}
+
+	var afterFlightInspectionResource *rootdto.AfterFlightInspectionResource
+	if h.afterFlightInspection != nil && len(report.FlightInspectionID) == 16 {
+		if afterRow, afterErr := h.afterFlightInspection.GetByFlightInspectionID(c.UserContext(), report.FlightInspectionID); afterErr == nil && afterRow != nil {
+			afterFlightInspectionResource = buildAfterFlightInspectionResource(afterRow, report.FlightInspectionID, flightInspectionResource)
+		}
+	}
+
+	// Prefer the fleet status snapshot frozen when the report was created; fall
+	// back to a live build only for legacy reports created before snapshots existed.
+	var fleetStatusResource *responsedto.FleetStatusResource
+	var helicopterUsageSnapshot *rootdto.HelicopterUsageResource
+	var helicopterID []byte
+	if h.flight != nil {
+		helicopterID = h.flight.ResolveHelicopterIDByTakeover(c.UserContext(), report.TakeoverID)
+	}
+	// While the report is still OPEN, show LIVE fleet status so fleet updates (maintenance
+	// schedules, summary, …) reflect immediately. Once the report is COMPLETED, show the
+	// snapshot frozen at completion.
+	if report.CompletedAt != nil {
+		if history, histErr := h.svc.GetFleetHistory(c.UserContext(), report.ID); histErr == nil && history != nil {
+			fleetStatusResource = fmReportFleetHistoryResource(history)
+		}
+	}
+	if fleetStatusResource == nil && h.fleetStatus != nil {
+		if len(helicopterID) == 16 {
+			fleetStatusResource = h.fleetStatus.FMReportFleetStatus(c.UserContext(), helicopterID)
+		}
+	}
+	var usageBreakdown *rootdto.FMReportUsageBreakdown
+	if len(helicopterID) == 16 {
+		resource := helicopterUsageZeroResource(helicopterID)
+		helicopterUsageSnapshot = &resource
+		if h.helicopterUsage != nil {
+			var usageRow *helicopterusage.HelicopterUsage
+			if r, usageErr := h.helicopterUsage.GetByHelicopterID(c.UserContext(), helicopterID); usageErr == nil && r != nil {
+				usageRow = r
+				resource = helicopterUsageResource(usageRow)
+				helicopterUsageSnapshot = &resource
+			}
+			today, _ := h.helicopterUsage.FlightStatsByFlightID(c.UserContext(), report.FlightID)
+			// Absent engines (single-engine aircraft) are left empty, not mirrored from airframe.
+			hasE1, hasE2 := true, true
+			if h.fleetStatus != nil && h.fleetStatus.helicopterSvc != nil {
+				if heli, herr := h.fleetStatus.helicopterSvc.GetByID(c.UserContext(), helicopterID); herr == nil && heli != nil {
+					hasE1, hasE2 = heli.NR1, heli.NR2
+				}
+			}
+			breakdown := buildFMReportUsageBreakdown(usageRow, today, report, hasE1, hasE2)
+			usageBreakdown = &breakdown
+		}
+	}
+
+	var takeoverFiles []responsedto.TakeoverFileResource
+	var pilotName *string
+	var helicopterIdentifier *string
+	if h.takeover != nil && len(report.TakeoverID) == 16 {
+		if takeoverRow, takeoverErr := h.takeover.GetByID(c.UserContext(), report.TakeoverID); takeoverErr == nil && takeoverRow != nil {
+			takeoverFiles = takeoverFileResources(c.UserContext(), h.storage, takeoverRow.Files)
+			var pilotNames []string
+			for _, crew := range takeoverRow.RosterCrews {
+				if strings.EqualFold(crew.RoleCode, "PILOT") {
+					name := strings.TrimSpace(crew.NameLabel)
+					if name == "" && crew.User != nil {
+						name = strings.TrimSpace(crew.User.FirstName + " " + crew.User.LastName)
+					}
+					if name != "" {
+						pilotNames = append(pilotNames, name)
+					}
+				}
+			}
+			if len(pilotNames) > 0 {
+				joined := strings.Join(pilotNames, ", ")
+				pilotName = &joined
+			}
+			if takeoverRow.ReserveAc != nil && takeoverRow.ReserveAc.Aircraft != nil {
+				ident := takeoverRow.ReserveAc.Aircraft.Identifier
+				helicopterIdentifier = &ident
+			}
+		}
+	}
+
+	var fmReportAttachments *rootdto.FMReportAttachments
+	if h.fileManager != nil && len(report.ID) == 16 {
+		refID := idString(report.ID)
+		atts, _, attErr := h.fileManager.ListAttachmentsByReference(c.UserContext(), filemanager.ListAttachmentsParams{
+			RefType: "fm_report",
+			RefID:   refID,
+			Limit:   1000,
+		})
+		if attErr == nil && len(atts) > 0 {
+			fmReportAttachments = &rootdto.FMReportAttachments{}
+			for i := range atts {
+				att := &atts[i]
+				item := rootdto.FMReportAttachmentItem{
+					ID:     idString(att.ID),
+					FileID: idString(att.FileID),
+				}
+				if att.File != nil {
+					url := resolveFileManagerDownloadURL(c.UserContext(), h.storage, att.File)
+					if url != "" {
+						item.DownloadURL = &url
+					}
+				}
+				cat := ""
+				if att.Category != nil {
+					cat = *att.Category
+				}
+				switch cat {
+				case "additional_fm_report":
+					fmReportAttachments.AdditionalFMReport = append(fmReportAttachments.AdditionalFMReport, item)
+				case "briefing":
+					fmReportAttachments.Briefing = append(fmReportAttachments.Briefing, item)
+				case "weight_balance":
+					fmReportAttachments.WeightBalance = append(fmReportAttachments.WeightBalance, item)
+				case "ofp":
+					fmReportAttachments.OFP = append(fmReportAttachments.OFP, item)
+				}
+			}
+		}
+
+		// Auto-fetch OFP attachments from takeover (uploaded in Step 1 with category="ofp").
+		if len(report.TakeoverID) == 16 {
+			takeoverRefID := idString(report.TakeoverID)
+			ofpCategory := "ofp"
+			ofpAtts, _, ofpErr := h.fileManager.ListAttachmentsByReference(c.UserContext(), filemanager.ListAttachmentsParams{
+				RefType:  "takeover",
+				RefID:    takeoverRefID,
+				Category: &ofpCategory,
+				Limit:    1000,
+			})
+			if ofpErr == nil && len(ofpAtts) > 0 {
+				if fmReportAttachments == nil {
+					fmReportAttachments = &rootdto.FMReportAttachments{}
+				}
+				existingOFPFileIDs := make(map[string]struct{})
+				for _, existing := range fmReportAttachments.OFP {
+					existingOFPFileIDs[existing.FileID] = struct{}{}
+				}
+				for i := range ofpAtts {
+					att := &ofpAtts[i]
+					fileIDStr := idString(att.FileID)
+					if _, dup := existingOFPFileIDs[fileIDStr]; dup {
+						continue
+					}
+					item := rootdto.FMReportAttachmentItem{
+						ID:     idString(att.ID),
+						FileID: fileIDStr,
+					}
+					if att.File != nil {
+						url := resolveFileManagerDownloadURL(c.UserContext(), h.storage, att.File)
+						if url != "" {
+							item.DownloadURL = &url
+						}
+					}
+					fmReportAttachments.OFP = append(fmReportAttachments.OFP, item)
+				}
+			}
+		}
+
+		// Auto-fetch edited W&B template files from takeover (set by pencil-icon edits in Step 1).
+		// These live in file_files with takeover_id+template_uuid set but have no fm_report attachment record.
+		if len(report.TakeoverID) == 16 {
+			wbFiles, wbErr := h.fileManager.ListEditedWBFilesByTakeoverID(c.UserContext(), report.TakeoverID)
+			if wbErr == nil && len(wbFiles) > 0 {
+				// Build a set of file IDs already present in WeightBalance to avoid duplicates.
+				existingWBFileIDs := make(map[string]struct{})
+				if fmReportAttachments != nil {
+					for _, existing := range fmReportAttachments.WeightBalance {
+						existingWBFileIDs[existing.FileID] = struct{}{}
+					}
+				}
+				if fmReportAttachments == nil {
+					fmReportAttachments = &rootdto.FMReportAttachments{}
+				}
+				for i := range wbFiles {
+					f := &wbFiles[i]
+					fileIDStr := idString(f.ID)
+					if _, dup := existingWBFileIDs[fileIDStr]; dup {
+						continue
+					}
+					item := rootdto.FMReportAttachmentItem{
+						ID:     fileIDStr,
+						FileID: fileIDStr,
+					}
+					url := resolveFileManagerDownloadURL(c.UserContext(), h.storage, f)
+					if url != "" {
+						item.DownloadURL = &url
+					}
+					fmReportAttachments.WeightBalance = append(fmReportAttachments.WeightBalance, item)
+				}
+			}
+		}
+	}
+
+	payload := &rootdto.FMReportResponse{
+		Data: rootdto.FMReportResource{
+			Type: "fm_report",
+			ID:   idString(report.ID),
+			Attributes: rootdto.FMReportAttributes{
+				ID:                    idString(report.ID),
+				ReportCode:            report.ReportCode,
+				TakeoverID:            idString(report.TakeoverID),
+				FlightID:              idString(report.FlightID),
+				FlightInspectionID:    idString(report.FlightInspectionID),
+				Engine1GpcN1:          report.Engine1GpcN1,
+				Engine1PtcN2:          report.Engine1PtcN2,
+				Engine2GpcN1:          report.Engine2GpcN1,
+				Engine2PtcN2:          report.Engine2PtcN2,
+				CompletedAt:           timeStringOrEmpty(report.CompletedAt),
+				CompletedBy:           uuidStringOrEmpty(report.CompletedBy),
+				PilotName:             pilotName,
+				HelicopterIdentifier:  helicopterIdentifier,
+				Flight:                &flightResource,
+				Missions:              missions,
+				FlightInspection:      flightInspectionResource,
+				AfterFlightInspection: afterFlightInspectionResource,
+				FleetStatus:           fleetStatusResource,
+				HelicopterUsage:       helicopterUsageSnapshot,
+				UsageBreakdown:        usageBreakdown,
+				TakeoverFiles:         takeoverFiles,
+				FMReportAttachments:   fmReportAttachments,
+				CreatedAt:             report.CreatedAt.UTC().Format(time.RFC3339),
+				UpdatedAt:             report.UpdatedAt.UTC().Format(time.RFC3339),
+			},
+		},
+	}
+	return payload, nil
+}
+
+const fmReportFileFolderName = "fm-reports"
+
+var validFMReportAttachmentCategories = map[string]bool{
+	"additional_fm_report": true,
+	"briefing":             true,
+	"weight_balance":       true,
+	"ofp":                  true,
+}
+
+// ensureFMReportFileFolderPath ensures the folder structure:
+// __system_root_files__ / fm-reports / {helicopterIdentifier}
+// Returns the innermost folder ID.
+func ensureFMReportFileFolderPath(ctx context.Context, svc filemanager.Service, helicopterIdentifier string, actorID []byte) ([]byte, error) {
+	rootFolder, err := svc.GetOrCreateSystemRootFolder(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if rootFolder == nil || len(rootFolder.ID) != 16 {
+		return nil, filemanager.ErrFolderNotFound
+	}
+	fmReportsFolderID, err := ensureFileManagerFolder(ctx, svc, rootFolder.ID, fmReportFileFolderName, actorID)
+	if err != nil {
+		return nil, err
+	}
+	return ensureFileManagerFolder(ctx, svc, fmReportsFolderID, helicopterIdentifier, actorID)
+}
+
+// RequestAttachmentUploadIntent godoc
+// @Summary Request upload intent for FM report attachment
+// @Description Returns a presigned PUT URL and upload_intent_uuid. After uploading the file to the presigned URL, call POST /fm-reports/{id}/attachments with the upload_intent_uuid to create the file node and attach it to the report.
+// @Tags Flight Report
+// @Accept json
+// @Produce json
+// @Param id path string true "FM Report ID (UUIDv7)"
+// @Param request body object true "body with name, content_type, size_bytes"
+// @Success 201 {object} object
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fm-reports/{id}/attachments/upload-intent [post]
+func (h *FMReportHandler) RequestAttachmentUploadIntent(c *fiber.Ctx) error {
+	if h.fileManager == nil {
+		return writeFMReportErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Upload failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	idRaw := strings.TrimSpace(c.Params("id"))
+	if _, err := uuidv7.ParseString(idRaw); err != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	var body struct {
+		Name        string `json:"name"`
+		ContentType string `json:"content_type"`
+		SizeBytes   int64  `json:"size_bytes"`
+	}
+	if err := c.BodyParser(&body); err != nil {
+		return writeFMReportErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	name := strings.TrimSpace(body.Name)
+	contentType := strings.TrimSpace(body.ContentType)
+	if name == "" {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/body/name"},
+		}})
+	}
+	if contentType == "" {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "content_type is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/body/content_type"},
+		}})
+	}
+
+	grant, err := h.fileManager.RequestFileUploadIntent(c.UserContext(), filemanager.RequestFileUploadIntentParams{
+		Name:        name,
+		ContentType: contentType,
+		SizeBytes:   body.SizeBytes,
+		ActorID:     actorUserID(c),
+	})
+	if err != nil {
+		return writeFileManagerActionError(c, "Upload intent failed", err)
+	}
+
+	return response.Write(c, fiber.StatusCreated, map[string]interface{}{
+		"upload_intent_uuid": idString(grant.UploadIntentID),
+		"upload_url":         grant.UploadURL,
+		"method":             grant.Method,
+		"required_headers":   grant.Headers,
+		"expires_at":         grant.ExpiresAt,
+		"name":               grant.Name,
+		"mime_type":          grant.MimeType,
+		"size_bytes":         grant.SizeBytes,
+	})
+}
+
+// UploadAttachment godoc
+// @Summary Create FM report attachment from upload intent
+// @Description After uploading the file to the presigned URL (from /attachments/upload-intent), call this endpoint with the upload_intent_uuid, name, and category to create the file node and attach it to the FM report. Valid categories: additional_fm_report, briefing, weight_balance, ofp.
+// @Tags Flight Report
+// @Accept json
+// @Produce json
+// @Param id path string true "FM Report ID (UUIDv7)"
+// @Param request body object true "body with upload_intent_uuid, name, and category"
+// @Success 201 {object} object
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fm-reports/{id}/attachments [post]
+func (h *FMReportHandler) UploadAttachment(c *fiber.Ctx) error {
+	if h.fileManager == nil {
+		return writeFMReportErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Upload failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	idRaw := strings.TrimSpace(c.Params("id"))
+	reportID, err := uuidv7.ParseString(idRaw)
+	if err != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	var body struct {
+		UploadIntentUUID string `json:"upload_intent_uuid"`
+		Name             string `json:"name"`
+		Category         string `json:"category"`
+	}
+	if err := c.BodyParser(&body); err != nil {
+		return writeFMReportErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	uploadIntentID, err := uuidv7.ParseString(strings.TrimSpace(body.UploadIntentUUID))
+	if err != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "upload_intent_uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/body/upload_intent_uuid"},
+		}})
+	}
+
+	name := strings.TrimSpace(body.Name)
+	if name == "" {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/body/name"},
+		}})
+	}
+
+	category := strings.TrimSpace(body.Category)
+	if !validFMReportAttachmentCategories[category] {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "category must be one of: additional_fm_report, briefing, weight_balance, ofp",
+			Source: &jsonapi.ErrorSource{Pointer: "/body/category"},
+		}})
+	}
+
+	// Fetch FM report to get HelicopterID for folder naming.
+	report, err := h.svc.GetByID(c.UserContext(), reportID)
+	if err != nil || report == nil {
+		return writeFMReportErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "FM report not found",
+		}})
+	}
+
+	// Resolve helicopter identifier for folder name.
+	// Priority: heli.Identifier → idString(HelicopterID) → idString(reportID)
+	// Sanitize slashes/backslashes since they are invalid in folder names.
+	helicopterIdentifier := ""
+	if h.helicopter != nil && len(report.HelicopterID) == 16 {
+		if heli, heliErr := h.helicopter.GetByID(c.UserContext(), report.HelicopterID); heliErr == nil && heli != nil {
+			helicopterIdentifier = strings.TrimSpace(heli.Identifier)
+		}
+	}
+	if helicopterIdentifier == "" {
+		helicopterIdentifier = idString(report.HelicopterID)
+	}
+	if helicopterIdentifier == "" {
+		helicopterIdentifier = idString(reportID)
+	}
+	helicopterIdentifier = strings.NewReplacer("/", "-", "\\", "-").Replace(helicopterIdentifier)
+
+	// Ensure folder: __system_root_files__ / fm-reports / {helicopterIdentifier}
+	folderID, folderErr := ensureFMReportFileFolderPath(c.UserContext(), h.fileManager, helicopterIdentifier, actorUserID(c))
+	if folderErr != nil {
+		logHandlerError(c, "Ensure FM report folder", fiber.StatusInternalServerError, "INTERNAL_SERVER_ERROR", "5000005", folderErr)
+		return writeFMReportErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Upload failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	// Create file node from upload intent inside the folder.
+	created, createErr := h.fileManager.CreateFileNodeFromUploadIntent(c.UserContext(), filemanager.CreateFileFromUploadIntentParams{
+		UploadIntentID: uploadIntentID,
+		FolderID:       folderID,
+		FolderProvided: true,
+		Name:           name,
+		ActorID:        actorUserID(c),
+	})
+	if createErr != nil {
+		if errors.Is(createErr, filemanager.ErrDuplicateName) {
+			existing, exErr := h.fileManager.GetFileByFolderAndName(c.UserContext(), folderID, strings.ToLower(name))
+			if exErr != nil || existing == nil {
+				return writeFMReportErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+					Status: "409",
+					Title:  "Conflict",
+					Detail: "a file with this name already exists in the folder",
+				}})
+			}
+			created = existing
+		} else {
+			return writeFileManagerActionError(c, "Create file failed", createErr)
+		}
+	}
+	if created == nil {
+		return writeFMReportErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Upload failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	// Create attachment linking the file to this FM report.
+	// The file finishes processing asynchronously — retry briefly for readiness (bounded ~10s).
+	refID := idString(reportID)
+	attachParams := filemanager.CreateAttachmentParams{
+		FileID:  created.ID,
+		RefType: "fm_report",
+		RefID:   refID,
+		Category: &category,
+		ActorID: actorUserID(c),
+	}
+	var att *filemanager.Attachment
+	var attachErr error
+	for attempt := 0; attempt < 40; attempt++ {
+		att, attachErr = h.fileManager.CreateAttachment(c.UserContext(), attachParams)
+		if attachErr == nil || !errors.Is(attachErr, filemanager.ErrFileNotReadyForAttachment) {
+			break
+		}
+		if c.UserContext().Err() != nil {
+			break
+		}
+		time.Sleep(250 * time.Millisecond)
+	}
+	if attachErr != nil {
+		if errors.Is(attachErr, filemanager.ErrAttachmentAlreadyExists) {
+			return writeFMReportErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "Conflict",
+				Detail: "attachment already exists for this file and reference",
+			}})
+		}
+		return writeFMReportErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Upload failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	item := rootdto.FMReportAttachmentItem{
+		ID:     idString(att.ID),
+		FileID: idString(att.FileID),
+	}
+	return response.Write(c, fiber.StatusCreated, item)
+}
+
+// DeleteAttachment godoc
+// @Summary Delete attachment from FM report
+// @Description Remove a specific attachment from an FM report. Verifies ownership before deletion.
+// @Tags Flight Report
+// @Produce json
+// @Param id path string true "FM Report ID (UUIDv7)"
+// @Param att_id path string true "Attachment ID (UUIDv7)"
+// @Success 204
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fm-reports/{id}/attachments/{att_id} [delete]
+func (h *FMReportHandler) DeleteAttachment(c *fiber.Ctx) error {
+	if h.fileManager == nil {
+		return writeFMReportErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	idRaw := strings.TrimSpace(c.Params("id"))
+	reportID, err := uuidv7.ParseString(idRaw)
+	if err != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	attIDRaw := strings.TrimSpace(c.Params("att_id"))
+	attID, err := uuidv7.ParseString(attIDRaw)
+	if err != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "att_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/att_id"},
+		}})
+	}
+
+	att, err := h.fileManager.GetAttachmentByID(c.UserContext(), attID)
+	if err != nil || att == nil {
+		return writeFMReportErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "attachment not found",
+		}})
+	}
+
+	expectedRefID := idString(reportID)
+	if att.RefType != "fm_report" || att.RefID != expectedRefID {
+		return writeFMReportErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "attachment not found for this fm report",
+		}})
+	}
+
+	if err := h.fileManager.DeleteAttachment(c.UserContext(), attID); err != nil {
+		return writeFMReportErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return c.SendStatus(fiber.StatusNoContent)
+}
+
+// DeleteFMReport godoc
+// @Summary Delete FM report
+// @Description Soft-delete an FM report by ID. Requires a verified security PIN.
+// @Tags Flight Report
+// @Produce json
+// @Param id path string true "FM Report ID (UUIDv7)"
+// @Param X-PIN-Verification-Token header string true "One-time security-PIN action token"
+// @Success 204
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/fm-reports/{id} [delete]
+func (h *FMReportHandler) Delete(c *fiber.Ctx) error {
+	if h == nil || h.svc == nil {
+		return writeFMReportErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	idRaw := strings.TrimSpace(c.Params("id"))
+	reportID, err := uuidv7.ParseString(idRaw)
+	if err != nil {
+		return writeFMReportErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), reportID); err != nil {
+		if errors.Is(err, fmreport.ErrNotFound) {
+			return writeFMReportErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "fm report not found",
+				Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+			}})
+		}
+		return writeFMReportErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return c.SendStatus(fiber.StatusNoContent)
+}
+
+func buildAfterFlightInspectionResource(row *afterflightinspection.AfterFlightInspection, inspectionID []byte, inspection *rootdto.FlightInspectionResource) *rootdto.AfterFlightInspectionResource {
+	if row == nil {
+		return nil
+	}
+	out := &rootdto.AfterFlightInspectionResource{
+		Type: "after_flight_inspection",
+		ID:   idString(row.ID),
+		Attributes: rootdto.AfterFlightInspectionAttributes{
+			ID:                        idString(row.ID),
+			FlightInspectionID:        idString(inspectionID),
+			FlightInspection:          inspection,
+			MissionType:               []string{},
+			Route:                     []string{},
+			Total:                     0,
+			Completed:                 0,
+			DoneFileChecklist:         []rootdto.AfterFlightInspectionFileChecklistItem{},
+			FileChecklist:             []rootdto.AfterFlightInspectionFileChecklistItem{},
+			OilEngineNR1Checked:       row.OilEngineNR1Checked,
+			OilEngineNR2Checked:       row.OilEngineNR2Checked,
+			HydraulicLHChecked:        row.HydraulicLHChecked,
+			HydraulicRHChecked:        row.HydraulicRHChecked,
+			OilTransmissionMGBChecked: row.OilTransmissionMGBChecked,
+			OilTransmissionIGBChecked: row.OilTransmissionIGBChecked,
+			OilTransmissionTGBChecked: row.OilTransmissionTGBChecked,
+			Note:                      row.Note,
+			CreatedAt:                 row.CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedAt:                 row.UpdatedAt.UTC().Format(time.RFC3339),
+		},
+	}
+	return out
+}
+
+// subtractFMReportSnapshot computes prev = total - today, field by field. Values can go
+// negative when the total was manually adjusted below the derived value (matches the page).
+func subtractFMReportSnapshot(total, today rootdto.FMReportUsageSnapshot) rootdto.FMReportUsageSnapshot {
+	sub := func(a, b rootdto.FMReportEngineValues) rootdto.FMReportEngineValues {
+		return rootdto.FMReportEngineValues{
+			Hours:   a.Hours - b.Hours,
+			GpcNgN1: a.GpcNgN1 - b.GpcNgN1,
+			PtcNfN2: a.PtcNfN2 - b.PtcNfN2,
+			Ccc:     a.Ccc - b.Ccc,
+		}
+	}
+	return rootdto.FMReportUsageSnapshot{
+		Airframe: rootdto.FMReportAirframeValues{
+			Hours:  total.Airframe.Hours - today.Airframe.Hours,
+			Cycles: total.Airframe.Cycles - today.Airframe.Cycles,
+		},
+		Engine1: sub(total.Engine1, today.Engine1),
+		Engine2: sub(total.Engine2, today.Engine2),
+		Counters: rootdto.FMReportCountersValues{
+			Landings:         total.Counters.Landings - today.Counters.Landings,
+			FlightReports:    total.Counters.FlightReports - today.Counters.FlightReports,
+			HookReleases:     total.Counters.HookReleases - today.Counters.HookReleases,
+			RotorBrakeCycles: total.Counters.RotorBrakeCycles - today.Counters.RotorBrakeCycles,
+		},
+	}
+}
+
+// buildFMReportUsageBreakdown groups the table by row: total (cumulative), today (this
+// flight's contribution), and prev = total - today. Engine hours mirror airframe hours;
+// engine GPC/PTC "today" are parsed from THIS report with the shared parser; CCC has no
+// flight contribution. hasE1/hasE2 reflect installed engines — an absent engine (single-
+// engine aircraft) stays zero-valued across all three rows.
+func buildFMReportUsageBreakdown(usage *helicopterusage.HelicopterUsage, today helicopterusage.FlightDayStats, report *fmreport.Report, hasE1, hasE2 bool) rootdto.FMReportUsageBreakdown {
+	var u helicopterusage.HelicopterUsage
+	if usage != nil {
+		u = *usage
+	}
+
+	total := rootdto.FMReportUsageSnapshot{
+		Airframe: rootdto.FMReportAirframeValues{Hours: u.TotalAirframeHours, Cycles: u.TotalAirframeCycles},
+		Counters: rootdto.FMReportCountersValues{
+			Landings:         u.TotalLanding,
+			FlightReports:    u.TotalFlightReport,
+			HookReleases:     u.TotalHookRelease,
+			RotorBrakeCycles: u.TotalRotorBrakeCycle,
+		},
+	}
+	todaySnap := rootdto.FMReportUsageSnapshot{
+		Airframe: rootdto.FMReportAirframeValues{Hours: today.AirframeHours, Cycles: today.AirframeCycles},
+		Counters: rootdto.FMReportCountersValues{
+			Landings:         today.Landing,
+			FlightReports:    1, // this report contributes one flight report to the total
+			HookReleases:     today.HookRelease,
+			RotorBrakeCycles: today.RotorBrakeCycle,
+		},
+	}
+	if hasE1 {
+		total.Engine1 = rootdto.FMReportEngineValues{
+			Hours:   u.TotalEngine1Hours,
+			GpcNgN1: u.TotalEngine1GpcNgN1,
+			PtcNfN2: u.TotalEngine1PtcNfN2,
+			Ccc:     u.TotalEngine1Ccc,
+		}
+		todaySnap.Engine1 = rootdto.FMReportEngineValues{
+			Hours:   today.AirframeHours,
+			GpcNgN1: metricparse.Parse(report.Engine1GpcN1),
+			PtcNfN2: metricparse.Parse(report.Engine1PtcN2),
+		}
+	}
+	if hasE2 {
+		total.Engine2 = rootdto.FMReportEngineValues{
+			Hours:   u.TotalEngine2Hours,
+			GpcNgN1: u.TotalEngine2GpcNgN1,
+			PtcNfN2: u.TotalEngine2PtcNfN2,
+			Ccc:     u.TotalEngine2Ccc,
+		}
+		todaySnap.Engine2 = rootdto.FMReportEngineValues{
+			Hours:   today.AirframeHours,
+			GpcNgN1: metricparse.Parse(report.Engine2GpcN1),
+			PtcNfN2: metricparse.Parse(report.Engine2PtcN2),
+		}
+	}
+
+	return rootdto.FMReportUsageBreakdown{
+		Prev:  subtractFMReportSnapshot(total, todaySnap),
+		Today: todaySnap,
+		Total: total,
+	}
+}
+
+func helicopterUsageZeroResource(helicopterID []byte) rootdto.HelicopterUsageResource {
+	return rootdto.HelicopterUsageResource{
+		Type: "helicopter_usage",
+		ID:   "",
+		Attributes: rootdto.HelicopterUsageAttributes{
+			HelicopterID:         idString(helicopterID),
+			TotalLanding:         0,
+			TotalAirframeHours:   0,
+			TotalAirframeCycles:  0,
+			TotalEngine1Hours:    0,
+			TotalEngine1GpcNgN1:  0,
+			TotalEngine1PtcNfN2:  0,
+			TotalEngine1Ccc:      0,
+			TotalEngine2Hours:    0,
+			TotalEngine2GpcNgN1:  0,
+			TotalEngine2PtcNfN2:  0,
+			TotalEngine2Ccc:      0,
+			TotalFlightReport:    0,
+			TotalHookRelease:     0,
+			TotalRotorBrakeCycle: 0,
+		},
+	}
+}
+
+func writeFMReportErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	return response.WriteErrors(c, status, errs)
+}
+
+type FMReportFleetHistoryBuilder struct {
+	fleetStatus *FleetStatusHandler
+	flight      *FlightHandler
+}
+
+func NewFMReportFleetHistoryBuilder(fleetStatus *FleetStatusHandler, flight *FlightHandler) *FMReportFleetHistoryBuilder {
+	return &FMReportFleetHistoryBuilder{fleetStatus: fleetStatus, flight: flight}
+}
+
+func (b *FMReportFleetHistoryBuilder) BuildFleetHistory(ctx context.Context, takeoverID []byte) *fmreport.FleetHistory {
+	if b == nil || b.fleetStatus == nil || b.flight == nil {
+		return nil
+	}
+	helicopterID := b.flight.ResolveHelicopterIDByTakeover(ctx, takeoverID)
+	if len(helicopterID) != 16 {
+		return nil
+	}
+	fsh := b.fleetStatus
+	if fsh.svc == nil {
+		return nil
+	}
+	latest, err := fsh.svc.LatestByHelicopterIDs(ctx, [][]byte{helicopterID})
+	if err != nil {
+		return nil
+	}
+	row := latest[string(helicopterID)]
+	if row == nil {
+		return nil
+	}
+
+	history := &fmreport.FleetHistory{
+		HelicopterStatus: fsh.deriveHelicopterStatus(ctx, row.Helicopter, row.HelicopterID),
+	}
+	if summary, sErr := fsh.svc.GetSummaryByHelicopterID(ctx, row.HelicopterID); sErr == nil && summary != nil {
+		history.AirframeHours = derefFloat64(summary.Airframe.Hours)
+		history.Engine1Hours = derefFloat64(summary.Engine1.Hours)
+		history.Engine2Hours = derefFloat64(summary.Engine2.Hours)
+	}
+	for i := range row.MaintenanceSchedules {
+		ms := row.MaintenanceSchedules[i]
+		switch ms.InspectionType {
+		case fleetstatus.InspectionTypeAF:
+			history.AFType, history.AFDue, history.AFExt = ms.Type, ms.Due, ms.Ext
+		case fleetstatus.InspectionTypeENG1:
+			history.Eng1Type, history.Eng1Due, history.Eng1Ext = ms.Type, ms.Due, ms.Ext
+		case fleetstatus.InspectionTypeENG2:
+			history.Eng2Type, history.Eng2Due, history.Eng2Ext = ms.Type, ms.Due, ms.Ext
+		case fleetstatus.InspectionTypeMAIN1:
+			history.Main1Type, history.Main1Due, history.Main1Ext = ms.Type, ms.Due, ms.Ext
+		case fleetstatus.InspectionTypeMAIN2:
+			history.Main2Type, history.Main2Due, history.Main2Ext = ms.Type, ms.Due, ms.Ext
+		}
+	}
+	if fsh.easaSvc != nil {
+		if rel, relErr := fsh.easaSvc.GetLatestByHelicopter(ctx, helicopterID); relErr == nil && rel != nil {
+			history.EASAReleaseID = rel.ID
+			history.EASAIsSigned = rel.IsSigned()
+			history.EASADate = rel.EASADate
+			history.EASAACHours = rel.EASAACHours
+			history.EASALocation = rel.EASALocation
+			history.EASAWONo = rel.EASAWONo
+			history.EASAMaintManualRevAirframe = rel.EASAMaintManualRevAirframe
+			history.EASAMaintManualRevEngine = rel.EASAMaintManualRevEngine
+			history.EASASignerID = rel.EASASignerID
+			history.EASAPermitNo = rel.EASAPermitNo
+			history.EASASignedAt = rel.SignedAt
+			history.EASASignedBy = rel.SignedBy
+		}
+	}
+	// Capture the helicopter's latest MCF so the report keeps "MCF signed" even after the
+	// live fleet page resets its display.
+	if fsh.mcfSvc != nil {
+		if m, mErr := fsh.mcfSvc.LatestByHelicopterIDs(ctx, [][]byte{helicopterID}); mErr == nil {
+			if row := m[string(helicopterID)]; row != nil {
+				history.MCFID = row.ID
+				history.MCFIsSigned = row.IsComplete()
+				history.MCFDate = row.Date
+				if af := strings.TrimSpace(row.AFHours); af != "" {
+					history.MCFAFHours = &af
+				}
+				lc := row.LandingCount
+				history.MCFLandingCount = &lc
+				history.MCFSignedBy = row.CompletedBy
+				history.MCFSignedByName = userctx.GetDisplayName(ctx, row.CompletedBy)
+			}
+		}
+	}
+	return history
+}
+
+func fmReportFleetHistoryResource(h *fmreport.FleetHistory) *responsedto.FleetStatusResource {
+	if h == nil {
+		return nil
+	}
+	res := &responsedto.FleetStatusResource{
+		Type: "fleet_status",
+		Attributes: responsedto.FleetStatusAttributes{
+			Helicopter: &shareddto.FleetStatusHelicopter{Status: h.HelicopterStatus},
+			Summary: shareddto.FleetStatusSummary{
+				Airframe: shareddto.FleetStatusSummaryAirframe{Hours: float64Ptr(h.AirframeHours)},
+				Engine1:  shareddto.FleetStatusSummaryEngine{Hours: float64Ptr(h.Engine1Hours)},
+				Engine2:  shareddto.FleetStatusSummaryEngine{Hours: float64Ptr(h.Engine2Hours)},
+			},
+			MaintenanceSchedules: fmReportFleetHistorySchedules(h),
+		},
+	}
+	if h.HasEASA() {
+		res.Attributes.EASARelease = &shareddto.FleetStatusEASARelease{
+			ID:                         idString(h.EASAReleaseID),
+			IsSigned:                   h.EASAIsSigned,
+			EASADate:                   timeDatePtrOrNil(h.EASADate),
+			EASAACHours:                h.EASAACHours,
+			EASALocation:               h.EASALocation,
+			EASAWONo:                   h.EASAWONo,
+			EASAMaintManualRevAirframe: h.EASAMaintManualRevAirframe,
+			EASAMaintManualRevEngine:   h.EASAMaintManualRevEngine,
+			EASASignerID:               h.EASASignerID,
+			EASAPermitNo:               h.EASAPermitNo,
+			SignedAt:                   timePtrOrNil(h.EASASignedAt),
+			SignedBy:                   idString(h.EASASignedBy),
+		}
+	}
+	if h.HasMCF() {
+		m := &shareddto.FleetStatusMCF{
+			ID:           idString(h.MCFID),
+			Sign:         h.MCFIsSigned,
+			Date:         timeDatePtrOrNil(h.MCFDate),
+			AFHours:      h.MCFAFHours,
+			LandingCount: h.MCFLandingCount,
+			SignedBy:     idString(h.MCFSignedBy),
+		}
+		if h.MCFSignedByName != "" {
+			name := h.MCFSignedByName
+			m.SignedByName = &name
+		}
+		res.Attributes.MCF = m
+	}
+	return res
+}
+
+func fmReportFleetHistorySchedules(h *fmreport.FleetHistory) []shareddto.MaintenanceScheduleAttributes {
+	out := make([]shareddto.MaintenanceScheduleAttributes, 0, 5)
+	add := func(inspectionType, t, due, ext string) {
+		if t == "" && due == "" && ext == "" {
+			return
+		}
+		out = append(out, shareddto.MaintenanceScheduleAttributes{
+			InspectionType: inspectionType,
+			Type:           t,
+			Due:            due,
+			Ext:            ext,
+		})
+	}
+	add(fleetstatus.InspectionTypeAF, h.AFType, h.AFDue, h.AFExt)
+	add(fleetstatus.InspectionTypeENG1, h.Eng1Type, h.Eng1Due, h.Eng1Ext)
+	add(fleetstatus.InspectionTypeENG2, h.Eng2Type, h.Eng2Due, h.Eng2Ext)
+	add(fleetstatus.InspectionTypeMAIN1, h.Main1Type, h.Main1Due, h.Main1Ext)
+	add(fleetstatus.InspectionTypeMAIN2, h.Main2Type, h.Main2Due, h.Main2Ext)
+	return out
+}
+
+func float64Ptr(v float64) *float64 { return &v }
+
+func derefFloat64(v *float64) float64 {
+	if v == nil {
+		return 0
+	}
+	return *v
+}
diff --git a/internal/transport/http/handlers/fm_report_handler_test.go b/internal/transport/http/handlers/fm_report_handler_test.go
new file mode 100644
index 0000000..21dddbc
--- /dev/null
+++ b/internal/transport/http/handlers/fm_report_handler_test.go
@@ -0,0 +1,622 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	"wucher/internal/domain/flight"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	fmreport "wucher/internal/domain/fm_report"
+	"wucher/internal/domain/mission"
+	takeoverdomain "wucher/internal/domain/takeover"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type fmReportServiceMock struct {
+	updateFn          func(context.Context, []byte, *string, *string, *string, *string) (*fmreport.Report, error)
+	upsertFn          func(context.Context, *fmreport.Report) (*fmreport.Report, error)
+	getByFlightFn     func(context.Context, []byte) (*fmreport.Report, error)
+	listFn            func(context.Context, fmreport.ListFilter, int, int) ([]fmreport.Report, int64, error)
+	getFleetHistoryFn func(context.Context, []byte) (*fmreport.FleetHistory, error)
+	completeFn        func(context.Context, []byte) (*fmreport.Report, error)
+}
+
+func (m *fmReportServiceMock) GetFleetHistory(ctx context.Context, reportID []byte) (*fmreport.FleetHistory, error) {
+	if m.getFleetHistoryFn != nil {
+		return m.getFleetHistoryFn(ctx, reportID)
+	}
+	return nil, nil
+}
+
+func (m *fmReportServiceMock) UpsertForFlight(ctx context.Context, flightRow *flight.Flight, flightInspectionID []byte) (*fmreport.Report, error) {
+	if m.upsertFn != nil {
+		row := &fmreport.Report{FlightID: flightRow.ID, FlightInspectionID: flightInspectionID}
+		return m.upsertFn(ctx, row)
+	}
+	return nil, nil
+}
+
+func (m *fmReportServiceMock) UpdateForFlight(ctx context.Context, flightID []byte, engine1GpcN1, engine1PtcN2, engine2GpcN1, engine2PtcN2 *string) (*fmreport.Report, error) {
+	if m.updateFn != nil {
+		return m.updateFn(ctx, flightID, engine1GpcN1, engine1PtcN2, engine2GpcN1, engine2PtcN2)
+	}
+	return nil, nil
+}
+
+func stringPtr(v string) *string { return &v }
+
+func (m *fmReportServiceMock) GetByFlightID(ctx context.Context, flightID []byte) (*fmreport.Report, error) {
+	if m.getByFlightFn != nil {
+		return m.getByFlightFn(ctx, flightID)
+	}
+	return nil, nil
+}
+
+func (m *fmReportServiceMock) List(ctx context.Context, filter fmreport.ListFilter, limit, offset int) ([]fmreport.Report, int64, error) {
+	if m.listFn != nil {
+		return m.listFn(ctx, filter, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func (m *fmReportServiceMock) Complete(ctx context.Context, flightID []byte) (*fmreport.Report, error) {
+	if m.completeFn != nil {
+		return m.completeFn(ctx, flightID)
+	}
+	return nil, nil
+}
+
+func (m *fmReportServiceMock) Delete(_ context.Context, _ []byte) error { return nil }
+
+func TestFMReportHandler_GetByFlightID_IncludesAfterFlightInspectionOilFields(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	reportID := uuidv7.MustBytes()
+	afterID := uuidv7.MustBytes()
+	now := time.Date(2026, 6, 25, 10, 0, 0, 0, time.UTC)
+	engineOil := "1"
+	hydraulicLH := "1"
+	transmissionMGB := "1"
+	transmissionTGB := "1"
+	note := "Optional note about the inspection"
+
+	h := NewFMReportHandler(&fmReportServiceMock{
+		getByFlightFn: func(_ context.Context, gotFlightID []byte) (*fmreport.Report, error) {
+			if string(gotFlightID) != string(flightID) {
+				t.Fatalf("unexpected flight id: %x", gotFlightID)
+			}
+			return &fmreport.Report{
+				ID:                 reportID,
+				FlightID:           flightID,
+				TakeoverID:         takeoverID,
+				FlightInspectionID: inspectionID,
+				CreatedAt:          now,
+				UpdatedAt:          now,
+			}, nil
+		},
+	}).
+		WithFlightHandler(NewFlightHandler(&flightServiceMock{
+			getByIDFn: func(_ context.Context, gotFlightID []byte) (*flight.Flight, error) {
+				if string(gotFlightID) != string(flightID) {
+					t.Fatalf("unexpected flight lookup id: %x", gotFlightID)
+				}
+				return &flight.Flight{
+					ID:        flightID,
+					Date:      now,
+					CreatedAt: now,
+					UpdatedAt: now,
+				}, nil
+			},
+		})).
+		WithMissionHandler(NewMissionHandler(&missionServiceMock{
+			listByFlightIDFn: func(_ context.Context, gotFlightID []byte) ([]mission.Mission, error) {
+				if string(gotFlightID) != string(flightID) {
+					t.Fatalf("unexpected mission lookup id: %x", gotFlightID)
+				}
+				return nil, nil
+			},
+		})).
+		WithFlightInspectionService(&flightInspectionServiceMock{
+			getFn: func(_ context.Context, gotInspectionID []byte) (*flightinspection.FlightInspection, error) {
+				if string(gotInspectionID) != string(inspectionID) {
+					t.Fatalf("unexpected inspection lookup id: %x", gotInspectionID)
+				}
+				return &flightinspection.FlightInspection{
+					ID:             inspectionID,
+					InspectionDate: now,
+					Status:         "Draft",
+					CreatedAt:      now,
+					UpdatedAt:      now,
+				}, nil
+			},
+		}).
+		WithAfterFlightInspectionService(&afterFlightInspectionServiceMock{
+			getByFlightInspectionIDFn: func(_ context.Context, gotInspectionID []byte) (*afterflightinspection.AfterFlightInspection, error) {
+				if string(gotInspectionID) != string(inspectionID) {
+					t.Fatalf("unexpected after flight inspection lookup id: %x", gotInspectionID)
+				}
+				return &afterflightinspection.AfterFlightInspection{
+					ID:                        afterID,
+					FlightInspectionID:        inspectionID,
+					OilEngineNR1Checked:       &engineOil,
+					HydraulicLHChecked:        &hydraulicLH,
+					OilTransmissionMGBChecked: &transmissionMGB,
+					OilTransmissionTGBChecked: &transmissionTGB,
+					Note:                      &note,
+					CreatedAt:                 now,
+					UpdatedAt:                 now,
+				}, nil
+			},
+		})
+
+	app := fiber.New()
+	app.Get("/api/v1/fm-reports/get/:flight_id", h.GetByFlightID)
+
+	flightIDString, err := uuidv7.BytesToString(flightID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp, body := doJSONRequestFMReport(t, app, http.MethodGet, "/api/v1/fm-reports/get/"+flightIDString, nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d body=%s", resp.StatusCode, string(body))
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(body, &payload); err != nil {
+		t.Fatal(err)
+	}
+	data := payload["data"].(map[string]any)
+	attrs := data["attributes"].(map[string]any)
+	after := attrs["after_flight_inspection"].(map[string]any)
+	afterAttrs := after["attributes"].(map[string]any)
+
+	expectedKeys := []string{
+		"oil_engine_nr1_checked",
+		"oil_engine_nr2_checked",
+		"hydraulic_lh_checked",
+		"hydraulic_rh_checked",
+		"oil_transmission_mgb_checked",
+		"oil_transmission_igb_checked",
+		"oil_transmission_tgb_checked",
+		"note",
+	}
+	for _, key := range expectedKeys {
+		if _, ok := afterAttrs[key]; !ok {
+			t.Fatalf("expected after_flight_inspection.%s in response, body=%s", key, string(body))
+		}
+	}
+	if afterAttrs["oil_engine_nr1_checked"] != engineOil {
+		t.Fatalf("unexpected oil_engine_nr1_checked: %#v", afterAttrs["oil_engine_nr1_checked"])
+	}
+	if afterAttrs["hydraulic_lh_checked"] != hydraulicLH {
+		t.Fatalf("unexpected hydraulic_lh_checked: %#v", afterAttrs["hydraulic_lh_checked"])
+	}
+	if afterAttrs["oil_transmission_mgb_checked"] != transmissionMGB {
+		t.Fatalf("unexpected oil_transmission_mgb_checked: %#v", afterAttrs["oil_transmission_mgb_checked"])
+	}
+	if afterAttrs["oil_transmission_tgb_checked"] != transmissionTGB {
+		t.Fatalf("unexpected oil_transmission_tgb_checked: %#v", afterAttrs["oil_transmission_tgb_checked"])
+	}
+	if afterAttrs["oil_engine_nr2_checked"] != nil {
+		t.Fatalf("expected oil_engine_nr2_checked to be null, got %#v", afterAttrs["oil_engine_nr2_checked"])
+	}
+	if afterAttrs["hydraulic_rh_checked"] != nil {
+		t.Fatalf("expected hydraulic_rh_checked to be null, got %#v", afterAttrs["hydraulic_rh_checked"])
+	}
+	if afterAttrs["oil_transmission_igb_checked"] != nil {
+		t.Fatalf("expected oil_transmission_igb_checked to be null, got %#v", afterAttrs["oil_transmission_igb_checked"])
+	}
+}
+
+func TestFMReportHandler_GetByFlightID_IncludesAllTakeoverPilots(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	reportID := uuidv7.MustBytes()
+	now := time.Date(2026, 6, 30, 10, 0, 0, 0, time.UTC)
+	pilotOneID := uuidv7.MustBytes()
+	pilotTwoID := uuidv7.MustBytes()
+
+	h := NewFMReportHandler(&fmReportServiceMock{
+		getByFlightFn: func(_ context.Context, gotFlightID []byte) (*fmreport.Report, error) {
+			if string(gotFlightID) != string(flightID) {
+				t.Fatalf("unexpected flight id: %x", gotFlightID)
+			}
+			return &fmreport.Report{
+				ID:                 reportID,
+				FlightID:           flightID,
+				TakeoverID:         takeoverID,
+				FlightInspectionID: uuidv7.MustBytes(),
+				CreatedAt:          now,
+				UpdatedAt:          now,
+			}, nil
+		},
+	}).
+		WithFlightHandler(NewFlightHandler(&flightServiceMock{
+			getByIDFn: func(_ context.Context, gotFlightID []byte) (*flight.Flight, error) {
+				if string(gotFlightID) != string(flightID) {
+					t.Fatalf("unexpected flight lookup id: %x", gotFlightID)
+				}
+				return &flight.Flight{
+					ID:           flightID,
+					TakeoverAcID: takeoverID,
+					Date:         now,
+					CreatedAt:    now,
+					UpdatedAt:    now,
+				}, nil
+			},
+		}).WithTakeoverService(&takeoverServiceMock{
+			getByIDFn: func(_ context.Context, gotTakeoverID []byte) (*takeoverdomain.TakeoverAc, error) {
+				if string(gotTakeoverID) != string(takeoverID) {
+					t.Fatalf("unexpected takeover lookup id: %x", gotTakeoverID)
+				}
+				return &takeoverdomain.TakeoverAc{
+					ID: takeoverID,
+					RosterCrews: []takeoverdomain.TakeoverRosterCrew{
+						{UserID: pilotOneID, NameLabel: "Jennifer C", RoleCode: "pilot", CrewType: "main"},
+						{UserID: pilotTwoID, NameLabel: "rar lesmana", RoleCode: "pilot", CrewType: "main"},
+					},
+				}, nil
+			},
+		})).
+		WithMissionHandler(NewMissionHandler(&missionServiceMock{
+			listByFlightIDFn: func(_ context.Context, gotFlightID []byte) ([]mission.Mission, error) {
+				if string(gotFlightID) != string(flightID) {
+					t.Fatalf("unexpected mission lookup id: %x", gotFlightID)
+				}
+				return nil, nil
+			},
+		}))
+
+	app := fiber.New()
+	app.Get("/api/v1/fm-reports/get/:flight_id", h.GetByFlightID)
+
+	flightIDString, err := uuidv7.BytesToString(flightID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp, body := doJSONRequestFMReport(t, app, http.MethodGet, "/api/v1/fm-reports/get/"+flightIDString, nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d body=%s", resp.StatusCode, string(body))
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(body, &payload); err != nil {
+		t.Fatal(err)
+	}
+	data := payload["data"].(map[string]any)
+	attrs := data["attributes"].(map[string]any)
+	flightAttrs := attrs["flight"].(map[string]any)["attributes"].(map[string]any)
+	takeoverAttrs := flightAttrs["takeover"].(map[string]any)
+	rosterDetail := takeoverAttrs["roster_detail"].(map[string]any)
+	pilots := rosterDetail["pilot"].([]any)
+
+	if len(pilots) != 2 {
+		t.Fatalf("expected 2 pilots in fm report, got %#v", pilots)
+	}
+	firstPilot := pilots[0].(map[string]any)
+	secondPilot := pilots[1].(map[string]any)
+	if firstPilot["name"] != "Jennifer C" {
+		t.Fatalf("unexpected first pilot: %#v", firstPilot)
+	}
+	if secondPilot["name"] != "rar lesmana" {
+		t.Fatalf("unexpected second pilot: %#v", secondPilot)
+	}
+}
+
+func TestFMReportHandler_UpdateByFlightID(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	reportID := uuidv7.MustBytes()
+	now := time.Date(2026, 6, 18, 10, 0, 0, 0, time.UTC)
+
+	svc := &fmReportServiceMock{
+		updateFn: func(_ context.Context, gotFlightID []byte, engine1GpcN1, engine1PtcN2, engine2GpcN1, engine2PtcN2 *string) (*fmreport.Report, error) {
+			if string(gotFlightID) != string(flightID) {
+				t.Fatalf("unexpected flight id: %x", gotFlightID)
+			}
+			if engine1GpcN1 == nil || engine1PtcN2 == nil || engine2GpcN1 == nil || engine2PtcN2 == nil {
+				t.Fatalf("unexpected update payload: %#v %#v %#v %#v", engine1GpcN1, engine1PtcN2, engine2GpcN1, engine2PtcN2)
+			}
+			if *engine1GpcN1 != "engine1-gpc-value" || *engine1PtcN2 != "engine1-ptc-value" || *engine2GpcN1 != "engine2-gpc-value" || *engine2PtcN2 != "engine2-ptc-value" {
+				t.Fatalf("unexpected update payload: %q %q %q %q", *engine1GpcN1, *engine1PtcN2, *engine2GpcN1, *engine2PtcN2)
+			}
+			return &fmreport.Report{
+				ID:                 reportID,
+				FlightID:           flightID,
+				TakeoverID:         uuidv7.MustBytes(),
+				FlightInspectionID: uuidv7.MustBytes(),
+				Engine1GpcN1:       engine1GpcN1,
+				Engine1PtcN2:       engine1PtcN2,
+				Engine2GpcN1:       engine2GpcN1,
+				Engine2PtcN2:       engine2PtcN2,
+				CreatedAt:          now,
+				UpdatedAt:          now,
+			}, nil
+		},
+	}
+
+	h := NewFMReportHandler(svc).
+		WithFlightHandler(NewFlightHandler(&flightServiceMock{
+			getByIDFn: func(_ context.Context, gotFlightID []byte) (*flight.Flight, error) {
+				if string(gotFlightID) != string(flightID) {
+					t.Fatalf("unexpected flight lookup id: %x", gotFlightID)
+				}
+				return &flight.Flight{
+					ID:        flightID,
+					Date:      now,
+					CreatedAt: now,
+					UpdatedAt: now,
+				}, nil
+			},
+		})).
+		WithMissionHandler(NewMissionHandler(&missionServiceMock{
+			listByFlightIDFn: func(_ context.Context, gotFlightID []byte) ([]mission.Mission, error) {
+				if string(gotFlightID) != string(flightID) {
+					t.Fatalf("unexpected mission lookup id: %x", gotFlightID)
+				}
+				return nil, nil
+			},
+		}))
+
+	app := fiber.New()
+	app.Patch("/api/v1/fm-reports/update/:flight_id", h.UpdateByFlightID)
+
+	body := `{"data":{"type":"fm_report_update","attributes":{"engine1_gpc_n1":"engine1-gpc-value","engine1_ptc_n2":"engine1-ptc-value","engine2_gpc_n1":"engine2-gpc-value","engine2_ptc_n2":"engine2-ptc-value"}}}`
+	flightIDString, err := uuidv7.BytesToString(flightID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req, err := http.NewRequest(http.MethodPatch, "/api/v1/fm-reports/update/"+flightIDString, strings.NewReader(body))
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bodyBytes, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d body=%s", resp.StatusCode, string(bodyBytes))
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(bodyBytes, &payload); err != nil {
+		t.Fatal(err)
+	}
+	dataRaw, ok := payload["data"]
+	if !ok {
+		t.Fatalf("missing data key in response: %s", string(bodyBytes))
+	}
+	data := dataRaw.(map[string]any)
+	attrsRaw, ok := data["attributes"]
+	if !ok {
+		t.Fatalf("missing attributes key in response: %s", string(bodyBytes))
+	}
+	attrs := attrsRaw.(map[string]any)
+	if attrs["engine1_gpc_n1"] != "engine1-gpc-value" || attrs["engine1_ptc_n2"] != "engine1-ptc-value" || attrs["engine2_gpc_n1"] != "engine2-gpc-value" || attrs["engine2_ptc_n2"] != "engine2-ptc-value" {
+		t.Fatalf("unexpected response attrs: %#v", attrs)
+	}
+}
+
+func TestFMReportHandler_Complete(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	reportID := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+	now := time.Date(2026, 6, 18, 11, 0, 0, 0, time.UTC)
+
+	svc := &fmReportServiceMock{
+		completeFn: func(_ context.Context, gotFlightID []byte) (*fmreport.Report, error) {
+			if string(gotFlightID) != string(flightID) {
+				t.Fatalf("unexpected flight id: %x", gotFlightID)
+			}
+			return &fmreport.Report{
+				ID:                 reportID,
+				FlightID:           flightID,
+				TakeoverID:         uuidv7.MustBytes(),
+				FlightInspectionID: uuidv7.MustBytes(),
+				CompletedAt:        &now,
+				CompletedBy:        userID,
+				CreatedAt:          now,
+				UpdatedAt:          now,
+			}, nil
+		},
+	}
+
+	h := NewFMReportHandler(svc).
+		WithFlightHandler(NewFlightHandler(&flightServiceMock{
+			getByIDFn: func(_ context.Context, gotFlightID []byte) (*flight.Flight, error) {
+				if string(gotFlightID) != string(flightID) {
+					t.Fatalf("unexpected flight lookup id: %x", gotFlightID)
+				}
+				return &flight.Flight{
+					ID:        flightID,
+					Date:      now,
+					CreatedAt: now,
+					UpdatedAt: now,
+				}, nil
+			},
+		})).
+		WithMissionHandler(NewMissionHandler(&missionServiceMock{
+			listByFlightIDFn: func(_ context.Context, gotFlightID []byte) ([]mission.Mission, error) {
+				if string(gotFlightID) != string(flightID) {
+					t.Fatalf("unexpected mission lookup id: %x", gotFlightID)
+				}
+				return nil, nil
+			},
+		}))
+
+	app := fiber.New()
+	app.Post("/api/v1/fm-reports/complete/:flight_id", h.Complete)
+
+	flightIDString, err := uuidv7.BytesToString(flightID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp, body := doJSONRequestFMReport(t, app, http.MethodPost, "/api/v1/fm-reports/complete/"+flightIDString, nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d body=%s", resp.StatusCode, body)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal([]byte(body), &payload); err != nil {
+		t.Fatal(err)
+	}
+	data, ok := payload["data"].(map[string]any)
+	if !ok {
+		t.Fatalf("unexpected data payload: %#v", payload["data"])
+	}
+	attrs, ok := data["attributes"].(map[string]any)
+	if !ok {
+		t.Fatalf("unexpected attributes payload: %#v", data["attributes"])
+	}
+	if attrs["completed_at"] == "" {
+		t.Fatalf("expected completed_at to be present, got %#v", attrs)
+	}
+	if attrs["completed_by"] == "" {
+		t.Fatalf("expected completed_by to be present, got %#v", attrs)
+	}
+}
+
+func TestFMReportHandler_Complete_NotFound(t *testing.T) {
+	h := NewFMReportHandler(&fmReportServiceMock{
+		completeFn: func(context.Context, []byte) (*fmreport.Report, error) {
+			return nil, fmreport.ErrNotFound
+		},
+	})
+
+	app := fiber.New()
+	app.Post("/api/v1/fm-reports/complete/:flight_id", h.Complete)
+
+	resp, body := doJSONRequestFMReport(t, app, http.MethodPost, "/api/v1/fm-reports/complete/019ef332-1111-7777-8888-999999999999", nil)
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("unexpected status %d body=%s", resp.StatusCode, body)
+	}
+}
+
+func doJSONRequestFMReport(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	var rdr io.Reader
+	if body != nil {
+		rdr = strings.NewReader(string(body))
+	}
+	req, err := http.NewRequest(method, path, rdr)
+	if err != nil {
+		t.Fatalf("new req: %v", err)
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	b, _ := io.ReadAll(resp.Body)
+	_ = resp.Body.Close()
+	return resp, b
+}
+
+func TestFMReportHandler_List(t *testing.T) {
+	flightID := uuidv7.MustBytes()
+	reportID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	now := time.Date(2026, 6, 18, 10, 0, 0, 0, time.UTC)
+
+	svc := &fmReportServiceMock{
+		listFn: func(_ context.Context, filter fmreport.ListFilter, limit, offset int) ([]fmreport.Report, int64, error) {
+			if string(filter.FlightID) != string(flightID) {
+				t.Fatalf("unexpected flight filter: %x", filter.FlightID)
+			}
+			if filter.FlightDate != "2026-06-18" {
+				t.Fatalf("unexpected flight date filter: %q", filter.FlightDate)
+			}
+			if filter.HasEngine1GpcN1 == nil || !*filter.HasEngine1GpcN1 {
+				t.Fatalf("expected has_engine1_gpc_n1=true filter")
+			}
+			if filter.HasEngine1PtcN2 == nil || *filter.HasEngine1PtcN2 {
+				t.Fatalf("expected has_engine1_ptc_n2=false filter")
+			}
+			if filter.HasEngine2GpcN1 == nil || !*filter.HasEngine2GpcN1 {
+				t.Fatalf("expected has_engine2_gpc_n1=true filter")
+			}
+			if filter.HasEngine2PtcN2 == nil || *filter.HasEngine2PtcN2 {
+				t.Fatalf("expected has_engine2_ptc_n2=false filter")
+			}
+			if limit != 5 || offset != 5 {
+				t.Fatalf("unexpected paging: limit=%d offset=%d", limit, offset)
+			}
+			return []fmreport.Report{{
+				ID:                 reportID,
+				FlightID:           flightID,
+				TakeoverID:         takeoverID,
+				FlightInspectionID: inspectionID,
+				Engine1GpcN1:       stringPtr("engine1-gpc-value"),
+				Engine1PtcN2:       nil,
+				Engine2GpcN1:       stringPtr("engine2-gpc-value"),
+				Engine2PtcN2:       nil,
+				CreatedAt:          now,
+				UpdatedAt:          now,
+			}}, 1, nil
+		},
+	}
+
+	h := NewFMReportHandler(svc).
+		WithFlightHandler(NewFlightHandler(&flightServiceMock{
+			getByIDFn: func(_ context.Context, gotFlightID []byte) (*flight.Flight, error) {
+				if string(gotFlightID) != string(flightID) {
+					t.Fatalf("unexpected flight lookup id: %x", gotFlightID)
+				}
+				return &flight.Flight{
+					ID:        flightID,
+					Date:      now,
+					CreatedAt: now,
+					UpdatedAt: now,
+				}, nil
+			},
+		})).
+		WithMissionHandler(NewMissionHandler(&missionServiceMock{
+			listByFlightIDFn: func(_ context.Context, gotFlightID []byte) ([]mission.Mission, error) {
+				if string(gotFlightID) != string(flightID) {
+					t.Fatalf("unexpected mission lookup id: %x", gotFlightID)
+				}
+				return nil, nil
+			},
+		}))
+
+	app := fiber.New()
+	app.Get("/api/v1/fm-reports/get-all", h.List)
+
+	flightIDString, err := uuidv7.BytesToString(flightID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp, body := doJSONRequestFMReport(t, app, http.MethodGet, "/api/v1/fm-reports/get-all?filter[flight_id]="+flightIDString+"&filter[flight_date]=2026-06-18&filter[has_engine1_gpc_n1]=true&filter[has_engine1_ptc_n2]=false&filter[has_engine2_gpc_n1]=true&filter[has_engine2_ptc_n2]=false&page[number]=2&page[size]=5", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d body=%s", resp.StatusCode, body)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal([]byte(body), &payload); err != nil {
+		t.Fatal(err)
+	}
+	data, ok := payload["data"].([]any)
+	if !ok || len(data) != 1 {
+		t.Fatalf("unexpected data payload: %#v", payload["data"])
+	}
+	meta, ok := payload["meta"].(map[string]any)
+	if !ok {
+		t.Fatalf("unexpected meta payload: %#v", payload["meta"])
+	}
+	if meta["page_number"] != float64(2) || meta["page_size"] != float64(5) || meta["total"] != float64(1) {
+		t.Fatalf("unexpected meta: %#v", meta)
+	}
+}
diff --git a/internal/transport/http/handlers/forces_present_handler.go b/internal/transport/http/handlers/forces_present_handler.go
new file mode 100644
index 0000000..ab377c5
--- /dev/null
+++ b/internal/transport/http/handlers/forces_present_handler.go
@@ -0,0 +1,455 @@
+package handlers
+
+import (
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/forces_present"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type ForcesPresentHandler struct {
+	svc      forces_present.Service
+	validate *validators.Validator
+}
+
+func NewForcesPresentHandler(svc forces_present.Service) *ForcesPresentHandler {
+	return &ForcesPresentHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateForcesPresent godoc
+// @Summary Create forces present
+// @Description Create a forces present row.
+// @Tags OPC - Forces Present
+// @Accept json
+// @Produce json
+// @Param request body dto.ForcesPresentCreateRequest true "JSON:API forces present create request"
+// @Success 201 {object} dto.ForcesPresentResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/forces-present/create [post]
+func (h *ForcesPresentHandler) Create(c *fiber.Ctx) error {
+	var req dto.ForcesPresentCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeForcesPresentErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeForcesPresentErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	name := strings.TrimSpace(req.Data.Attributes.Name)
+	if name == "" {
+		return writeForcesPresentErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+		}})
+	}
+
+	row := &forces_present.ForcesPresent{
+		Name:      name,
+		SortKey:   cloneIntPointer(req.Data.Attributes.SortKey),
+		Note:      strings.TrimSpace(stringOrDefault(req.Data.Attributes.Note, "")),
+		IsActive:  boolOrDefault(req.Data.Attributes.IsActive, true),
+		CreatedBy: actorUserID(c),
+		UpdatedBy: actorUserID(c),
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeForcesPresentErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, forcesPresentResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, forcesPresentResource(row))
+}
+
+// UpdateForcesPresent godoc
+// @Summary Update forces present (partial)
+// @Description Patch forces present by ID.
+// @Tags OPC - Forces Present
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Forces Present UUID (UUIDv7)"
+// @Param request body dto.ForcesPresentUpdateRequest true "JSON:API forces present update request"
+// @Success 200 {object} dto.ForcesPresentResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/forces-present/update/{uuid} [patch]
+func (h *ForcesPresentHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeForcesPresentErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.ForcesPresentUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeForcesPresentErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeForcesPresentErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeForcesPresentErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeForcesPresentErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Name == nil && !attrs.SortKey.Set && attrs.Note == nil && attrs.IsActive == nil {
+		return writeForcesPresentErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeForcesPresentErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "forces present not found",
+		}})
+	}
+
+	if attrs.Name != nil {
+		v := strings.TrimSpace(*attrs.Name)
+		if v == "" {
+			return writeForcesPresentErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+			}})
+		}
+		existing.Name = v
+	}
+	if attrs.SortKey.Set {
+		if attrs.SortKey.Valid {
+			sortKey := attrs.SortKey.Value
+			existing.SortKey = &sortKey
+		} else {
+			existing.SortKey = nil
+		}
+	}
+	if attrs.Note != nil {
+		existing.Note = strings.TrimSpace(*attrs.Note)
+	}
+	if attrs.IsActive != nil {
+		existing.IsActive = *attrs.IsActive
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeForcesPresentErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, forcesPresentResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, forcesPresentResource(existing))
+}
+
+// DeleteForcesPresent godoc
+// @Summary Delete forces present
+// @Tags OPC - Forces Present
+// @Produce json
+// @Param uuid path string true "Forces Present UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/forces-present/delete/{uuid} [delete]
+func (h *ForcesPresentHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeForcesPresentErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeForcesPresentErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "forces present not found",
+			}})
+		}
+		return writeForcesPresentErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "forces_present_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListForcesPresent godoc
+// @Summary List forces present
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.
+// @Tags OPC - Forces Present
+// @Produce json
+// @Param filter[search] query string false "Search by name/note"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.ForcesPresentListResponse
+// @Router /api/v1/forces-present/get-all [get]
+func (h *ForcesPresentHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("filter[name]")
+	}
+	if filter == "" {
+		filter = c.Query("search")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return writeForcesPresentErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.ForcesPresentResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, forcesPresentResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListForcesPresentDatatable godoc
+// @Summary List forces present (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags OPC - Forces Present
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.ForcesPresentDataTableResponse
+// @Router /api/v1/forces-present/get-all/dt [get]
+func (h *ForcesPresentHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return writeForcesPresentErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.ForcesPresentResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, forcesPresentResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func forcesPresentResource(row *forces_present.ForcesPresent) dto.ForcesPresentResource {
+	return dto.ForcesPresentResource{
+		Type: "forces_present",
+		ID:   idString(row.ID),
+		Attributes: dto.ForcesPresentAttributes{
+			Name:      row.Name,
+			SortKey:   cloneIntPointer(row.SortKey),
+			Note:      row.Note,
+			IsActive:  row.IsActive,
+			CreatedAt: row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy: uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt: row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy: uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt: timeStringOrEmpty(row.DeletedAt),
+			DeletedBy: uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func writeForcesPresentErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		if strings.TrimSpace(e.Code) == "" || strings.TrimSpace(e.ErrorCode) == "" {
+			code, errorCode := inferForcesPresentErrorCode(status, e.Title, e.Detail)
+			if strings.TrimSpace(e.Code) == "" {
+				e.Code = code
+			}
+			if strings.TrimSpace(e.ErrorCode) == "" {
+				e.ErrorCode = errorCode
+			}
+		}
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferForcesPresentErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.CodeForcesPresentNotFound, apperrorsx.ErrForcesPresentNotFound.ErrorCode
+	case fiber.StatusConflict:
+		return apperrorsx.CodeForcesPresentRelationDelete, apperrorsx.ErrForcesPresentRelationDelete.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid"):
+			return apperrorsx.CodeForcesPresentInvalidUUID, apperrorsx.ErrForcesPresentInvalidUUID.ErrorCode
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.CodeForcesPresentIDRequired, apperrorsx.ErrForcesPresentIDRequired.ErrorCode
+		case strings.Contains(lowerDetail, "id does not match"):
+			return apperrorsx.CodeForcesPresentIDMismatch, apperrorsx.ErrForcesPresentIDMismatch.ErrorCode
+		case strings.Contains(lowerDetail, "at least one attribute"):
+			return apperrorsx.CodeForcesPresentAttributesRequired, apperrorsx.ErrForcesPresentAttributesRequired.ErrorCode
+		case strings.Contains(lowerDetail, "name is required"), strings.Contains(lowerDetail, "name cannot be empty"):
+			return apperrorsx.CodeForcesPresentNameRequired, apperrorsx.ErrForcesPresentNameRequired.ErrorCode
+		default:
+			return apperrorsx.CodeForcesPresentInvalidPayload, apperrorsx.ErrForcesPresentInvalidPayload.ErrorCode
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.CodeForcesPresentInvalidJSON, apperrorsx.ErrForcesPresentInvalidJSON.ErrorCode
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.CodeForcesPresentCreateFailed, apperrorsx.ErrForcesPresentCreateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.CodeForcesPresentUpdateFailed, apperrorsx.ErrForcesPresentUpdateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "delete failed"):
+			if strings.Contains(lowerDetail, "relation") || strings.Contains(lowerDetail, "foreign key") || strings.Contains(lowerDetail, "constraint") {
+				return apperrorsx.CodeForcesPresentRelationDelete, apperrorsx.ErrForcesPresentRelationDelete.ErrorCode
+			}
+			return apperrorsx.CodeForcesPresentDeleteFailed, apperrorsx.ErrForcesPresentDeleteFailed.ErrorCode
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.CodeForcesPresentListFailed, apperrorsx.ErrForcesPresentListFailed.ErrorCode
+		default:
+			return apperrorsx.CodeForcesPresentInvalidPayload, apperrorsx.ErrForcesPresentInvalidPayload.ErrorCode
+		}
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
diff --git a/internal/transport/http/handlers/forces_present_handler_test.go b/internal/transport/http/handlers/forces_present_handler_test.go
new file mode 100644
index 0000000..dae463b
--- /dev/null
+++ b/internal/transport/http/handlers/forces_present_handler_test.go
@@ -0,0 +1,606 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/forces_present"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type memForcesPresentRepo struct {
+	rows map[string]*forces_present.ForcesPresent
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+
+	listRows  []forces_present.ForcesPresent
+	listTotal int64
+
+	getByIDFn func(id []byte, call int) (*forces_present.ForcesPresent, error)
+	getCalls  int
+
+	lastCreate     *forces_present.ForcesPresent
+	lastUpdate     *forces_present.ForcesPresent
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+}
+
+func newMemForcesPresentRepo() *memForcesPresentRepo {
+	return &memForcesPresentRepo{rows: map[string]*forces_present.ForcesPresent{}}
+}
+
+func (r *memForcesPresentRepo) Create(_ context.Context, row *forces_present.ForcesPresent) error {
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.rows[string(row.ID)] = row
+	r.lastCreate = row
+	return nil
+}
+
+func (r *memForcesPresentRepo) Update(_ context.Context, row *forces_present.ForcesPresent) error {
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	r.rows[string(row.ID)] = row
+	r.lastUpdate = row
+	return nil
+}
+
+func (r *memForcesPresentRepo) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	r.lastDeleteID = append([]byte(nil), id...)
+	r.lastDeleteBy = append([]byte(nil), deletedBy...)
+	delete(r.rows, string(id))
+	return nil
+}
+
+func (r *memForcesPresentRepo) GetByID(_ context.Context, id []byte) (*forces_present.ForcesPresent, error) {
+	r.getCalls++
+	if r.getByIDFn != nil {
+		return r.getByIDFn(id, r.getCalls)
+	}
+	if r.getByIDErr != nil {
+		return nil, r.getByIDErr
+	}
+	return r.rows[string(id)], nil
+}
+
+func (r *memForcesPresentRepo) List(_ context.Context, filter, sort string, limit, offset int) ([]forces_present.ForcesPresent, int64, error) {
+	r.lastListFilter = filter
+	r.lastListSort = sort
+	r.lastListLimit = limit
+	r.lastListOffset = offset
+	if r.listErr != nil {
+		return nil, 0, r.listErr
+	}
+	return r.listRows, r.listTotal, nil
+}
+
+func newForcesPresentTestApp(h *ForcesPresentHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", actor)
+		}
+		return c.Next()
+	})
+	app.Post("/api/v1/forces-present/create", h.Create)
+	app.Patch("/api/v1/forces-present/update/:uuid", h.Update)
+	app.Delete("/api/v1/forces-present/delete/:uuid", h.Delete)
+	app.Get("/api/v1/forces-present/get-all", h.List)
+	app.Get("/api/v1/forces-present/get-all/dt", h.ListDatatable)
+	return app
+}
+
+func doJSONRequestForcesPresent(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDStringForcesPresent(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestNewForcesPresentHandler(t *testing.T) {
+	h := NewForcesPresentHandler(service.NewForcesPresentService(newMemForcesPresentRepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+func TestForcesPresentHandlerCreate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPost, "/api/v1/forces-present/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPost, "/api/v1/forces-present/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"forces_present","attributes":{"name":"  "}}}`)
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPost, "/api/v1/forces-present/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		repo.createErr = errors.New("create failed")
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"forces_present","attributes":{"name":"Team A"}}}`)
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPost, "/api/v1/forces-present/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		actor := uuidv7.MustBytes()
+		app := newForcesPresentTestApp(h, actor)
+
+		body := []byte(`{"data":{"type":"forces_present","attributes":{"name":"Team A","sortkey":3,"note":"On-site","is_active":false}}}`)
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPost, "/api/v1/forces-present/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected row created")
+		}
+		if repo.lastCreate.Name != "Team A" || repo.lastCreate.Note != "On-site" {
+			t.Fatalf("expected created values")
+		}
+		if repo.lastCreate.SortKey == nil || *repo.lastCreate.SortKey != 3 {
+			t.Fatalf("expected sortkey value")
+		}
+		if repo.lastCreate.IsActive {
+			t.Fatalf("expected is_active false")
+		}
+		if string(repo.lastCreate.CreatedBy) != string(actor) || string(repo.lastCreate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected created_by and updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback when refetch error", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		repo.getByIDFn = func(_ []byte, call int) (*forces_present.ForcesPresent, error) {
+			if call > 0 {
+				return nil, errors.New("lookup failed")
+			}
+			return nil, nil
+		}
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"forces_present","attributes":{"name":"Team B"}}}`)
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPost, "/api/v1/forces-present/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected fallback create with empty description")
+		}
+	})
+}
+
+func TestForcesPresentHandlerUpdate(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPatch, "/api/v1/forces-present/update/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+		id := mustUUIDStringForcesPresent(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPatch, "/api/v1/forces-present/update/"+id, []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+		id := mustUUIDStringForcesPresent(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPatch, "/api/v1/forces-present/update/"+id, []byte(`{"data":{"type":"x","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+		id := mustUUIDStringForcesPresent(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPatch, "/api/v1/forces-present/update/"+id, []byte(`{"data":{"type":"forces_present","id":"","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+		id := mustUUIDStringForcesPresent(t, uuidv7.MustBytes())
+		other := mustUUIDStringForcesPresent(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPatch, "/api/v1/forces-present/update/"+id, []byte(`{"data":{"type":"forces_present","id":"`+other+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no attributes", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+		id := mustUUIDStringForcesPresent(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPatch, "/api/v1/forces-present/update/"+id, []byte(`{"data":{"type":"forces_present","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+		id := mustUUIDStringForcesPresent(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPatch, "/api/v1/forces-present/update/"+id, []byte(`{"data":{"type":"forces_present","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &forces_present.ForcesPresent{ID: id, Name: "Old"}
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+		idStr := mustUUIDStringForcesPresent(t, id)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPatch, "/api/v1/forces-present/update/"+idStr, []byte(`{"data":{"type":"forces_present","id":"`+idStr+`","attributes":{"name":"  "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &forces_present.ForcesPresent{ID: id, Name: "Old"}
+		repo.updateErr = errors.New("update failed")
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+		idStr := mustUUIDStringForcesPresent(t, id)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPatch, "/api/v1/forces-present/update/"+idStr, []byte(`{"data":{"type":"forces_present","id":"`+idStr+`","attributes":{"name":"New"}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &forces_present.ForcesPresent{ID: id, Name: "Old"}
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		actor := uuidv7.MustBytes()
+		app := newForcesPresentTestApp(h, actor)
+		idStr := mustUUIDStringForcesPresent(t, id)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPatch, "/api/v1/forces-present/update/"+idStr, []byte(`{"data":{"type":"forces_present","id":"`+idStr+`","attributes":{"name":"New","note":"Desc"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.Name != "New" || repo.lastUpdate.Note != "Desc" {
+			t.Fatalf("expected updated values")
+		}
+		if string(repo.lastUpdate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected updated_by from actor")
+		}
+	})
+
+	t.Run("success update sortkey note and is_active", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &forces_present.ForcesPresent{ID: id, Name: "Old", Note: "Old", IsActive: true}
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+		idStr := mustUUIDStringForcesPresent(t, id)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPatch, "/api/v1/forces-present/update/"+idStr, []byte(`{"data":{"type":"forces_present","id":"`+idStr+`","attributes":{"sortkey":2,"note":"New note","is_active":false}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil {
+			t.Fatalf("expected update called")
+		}
+		if repo.lastUpdate.SortKey == nil || *repo.lastUpdate.SortKey != 2 {
+			t.Fatalf("expected sortkey updated")
+		}
+		if repo.lastUpdate.Note != "New note" {
+			t.Fatalf("expected note updated")
+		}
+		if repo.lastUpdate.IsActive {
+			t.Fatalf("expected is_active false")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		id := uuidv7.MustBytes()
+		existing := &forces_present.ForcesPresent{ID: id, Name: "Old"}
+		repo.getByIDFn = func(_ []byte, call int) (*forces_present.ForcesPresent, error) {
+			if call == 1 {
+				return existing, nil
+			}
+			return nil, errors.New("second lookup failed")
+		}
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+		idStr := mustUUIDStringForcesPresent(t, id)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodPatch, "/api/v1/forces-present/update/"+idStr, []byte(`{"data":{"type":"forces_present","id":"`+idStr+`","attributes":{"note":"Only note"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestForcesPresentHandlerDelete(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodDelete, "/api/v1/forces-present/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete error", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		repo.deleteErr = errors.New("delete failed")
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+		id := mustUUIDStringForcesPresent(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodDelete, "/api/v1/forces-present/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		actor := uuidv7.MustBytes()
+		app := newForcesPresentTestApp(h, actor)
+		id := uuidv7.MustBytes()
+		idStr := mustUUIDStringForcesPresent(t, id)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodDelete, "/api/v1/forces-present/delete/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(repo.lastDeleteBy) != string(actor) {
+			t.Fatalf("expected deleted_by from actor")
+		}
+	})
+}
+
+func TestForcesPresentHandlerList(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodGet, "/api/v1/forces-present/get-all", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with filter name and clamp max", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		repo.listRows = []forces_present.ForcesPresent{{ID: uuidv7.MustBytes(), Name: "Team A", SortKey: intPtrForcesPresentHandler(3), Note: "On-site", IsActive: true, CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodGet, "/api/v1/forces-present/get-all?filter[name]=abc&page[number]=0&page=0&page[size]=0&limit=101&sort=-sortkey", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q sort=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListSort, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success with search and clamp min", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		repo.listRows = []forces_present.ForcesPresent{}
+		repo.listTotal = 0
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodGet, "/api/v1/forces-present/get-all?page=2&size=-1&search=needle", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "needle" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestForcesPresentHandlerListDatatable(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodGet, "/api/v1/forces-present/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success clamp max and page floor", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		repo.listRows = []forces_present.ForcesPresent{{ID: uuidv7.MustBytes(), Name: "Team A", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodGet, "/api/v1/forces-present/get-all/dt?page=0&limit=0&size=101&draw=7&search=abc", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListLimit != 100 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success clamp min", func(t *testing.T) {
+		repo := newMemForcesPresentRepo()
+		repo.listRows = []forces_present.ForcesPresent{}
+		repo.listTotal = 0
+		h := NewForcesPresentHandler(service.NewForcesPresentService(repo))
+		app := newForcesPresentTestApp(h, nil)
+
+		resp, _ := doJSONRequestForcesPresent(t, app, http.MethodGet, "/api/v1/forces-present/get-all/dt?page=2&limit=0&size=-1", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListLimit != 20 || repo.lastListOffset != 20 {
+			t.Fatalf("unexpected list params: limit=%d offset=%d", repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestForcesPresentResource(t *testing.T) {
+	id := uuidv7.MustBytes()
+	createdBy := uuidv7.MustBytes()
+	updatedBy := uuidv7.MustBytes()
+	deletedBy := uuidv7.MustBytes()
+	now := time.Now().UTC().Truncate(time.Second)
+	deletedAt := now.Add(time.Hour)
+
+	row := &forces_present.ForcesPresent{
+		ID:        id,
+		Name:      "Team A",
+		SortKey:   intPtrForcesPresentHandler(2),
+		Note:      "On-site",
+		IsActive:  true,
+		CreatedAt: now,
+		CreatedBy: createdBy,
+		UpdatedAt: now,
+		UpdatedBy: updatedBy,
+		DeletedAt: &deletedAt,
+		DeletedBy: deletedBy,
+	}
+
+	res := forcesPresentResource(row)
+	if res.Type != "forces_present" {
+		t.Fatalf("unexpected type: %s", res.Type)
+	}
+	if res.Attributes.SortKey == nil || *res.Attributes.SortKey != 2 {
+		t.Fatalf("expected sortkey in resource")
+	}
+	if res.Attributes.Note != "On-site" || !res.Attributes.IsActive {
+		t.Fatalf("expected note and is_active in resource")
+	}
+	if res.ID == "" || res.Attributes.CreatedBy == "" || res.Attributes.UpdatedBy == "" || res.Attributes.DeletedBy == "" {
+		t.Fatalf("expected UUID fields in resource")
+	}
+	if res.Attributes.CreatedAt == "" || res.Attributes.UpdatedAt == "" || res.Attributes.DeletedAt == "" {
+		t.Fatalf("expected time fields in resource")
+	}
+}
+
+func intPtrForcesPresentHandler(v int) *int { return &v }
diff --git a/internal/transport/http/handlers/health_handler.go b/internal/transport/http/handlers/health_handler.go
new file mode 100644
index 0000000..73b170e
--- /dev/null
+++ b/internal/transport/http/handlers/health_handler.go
@@ -0,0 +1,22 @@
+package handlers
+
+import (
+	"github.com/gofiber/fiber/v2"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+)
+
+type HealthHandler struct{}
+
+func NewHealthHandler() *HealthHandler {
+	return &HealthHandler{}
+}
+
+func (h *HealthHandler) Handle(c *fiber.Ctx) error {
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "health",
+		Attributes: map[string]any{
+			"status": "ok",
+		},
+	})
+}
diff --git a/internal/transport/http/handlers/health_handler_test.go b/internal/transport/http/handlers/health_handler_test.go
new file mode 100644
index 0000000..f5c2c13
--- /dev/null
+++ b/internal/transport/http/handlers/health_handler_test.go
@@ -0,0 +1,40 @@
+package handlers
+
+import (
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/gofiber/fiber/v2"
+)
+
+func TestNewHealthHandler(t *testing.T) {
+	h := NewHealthHandler()
+	if h == nil {
+		t.Fatalf("expected health handler instance")
+	}
+}
+
+func TestHealthHandler_Handle(t *testing.T) {
+	h := NewHealthHandler()
+	app := fiber.New()
+	app.Get("/health", h.Handle)
+
+	req, _ := http.NewRequest(http.MethodGet, "/health", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+
+	body, _ := io.ReadAll(resp.Body)
+	if !strings.Contains(string(body), `"type":"health"`) {
+		t.Fatalf("expected health type in body, got %s", string(body))
+	}
+	if !strings.Contains(string(body), `"status":"ok"`) {
+		t.Fatalf("expected status ok in body, got %s", string(body))
+	}
+}
diff --git a/internal/transport/http/handlers/health_insurance_companies_handler.go b/internal/transport/http/handlers/health_insurance_companies_handler.go
new file mode 100644
index 0000000..61e403f
--- /dev/null
+++ b/internal/transport/http/handlers/health_insurance_companies_handler.go
@@ -0,0 +1,562 @@
+package handlers
+
+import (
+	"encoding/hex"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/health_insurance_companies"
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type HealthInsuranceCompaniesHandler struct {
+	svc      health_insurance_companies.Service
+	validate *validators.Validator
+}
+
+func NewHealthInsuranceCompaniesHandler(svc health_insurance_companies.Service) *HealthInsuranceCompaniesHandler {
+	return &HealthInsuranceCompaniesHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateHealthInsuranceCompany godoc
+// @Summary Create health insurance company
+// @Description Create a health insurance company row.
+// @Tags Hospital - Health Insurance Companies
+// @Accept json
+// @Produce json
+// @Param request body dto.HealthInsuranceCompanyCreateRequest true "JSON:API health insurance company create request"
+// @Success 201 {object} dto.HealthInsuranceCompanyResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/health-insurance-companies/create [post]
+func (h *HealthInsuranceCompaniesHandler) Create(c *fiber.Ctx) error {
+	var req dto.HealthInsuranceCompanyCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHealthInsuranceErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHealthInsuranceErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	name := strings.TrimSpace(req.Data.Attributes.Name)
+	if name == "" {
+		return writeHealthInsuranceErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+		}})
+	}
+
+	row := &health_insurance_companies.HealthInsuranceCompany{
+		Name:         name,
+		SortKey:      cloneIntPointer(req.Data.Attributes.SortKey),
+		State:        strings.TrimSpace(stringOrDefault(req.Data.Attributes.State, "")),
+		Address:      strings.TrimSpace(stringOrDefault(req.Data.Attributes.Address, "")),
+		MobileNumber: strings.TrimSpace(stringOrDefault(req.Data.Attributes.MobileNumber, "")),
+		Email:        strings.TrimSpace(stringOrDefault(req.Data.Attributes.Email, "")),
+		Note:         strings.TrimSpace(stringOrDefault(req.Data.Attributes.Note, "")),
+		IsActive:     boolOrDefault(req.Data.Attributes.IsActive, true),
+		CreatedBy:    actorUserID(c),
+		UpdatedBy:    actorUserID(c),
+	}
+	if req.Data.Attributes.LandID != nil {
+		landID, parseErr := parseNullableUUID(*req.Data.Attributes.LandID)
+		if parseErr != nil {
+			return writeHealthInsuranceErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "land_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/land_id"},
+			}})
+		}
+		row.LandID = landID
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeHealthInsuranceErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	stateDetails, _ := h.svc.ResolveStateDetails(c.UserContext(), []string{row.State})
+	landDetails, _ := h.svc.ResolveLandDetails(c.UserContext(), collectHealthInsuranceLandIDs([]health_insurance_companies.HealthInsuranceCompany{*row}))
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, healthInsuranceCompanyResource(created, stateDetails, landDetails))
+	}
+	return response.Write(c, fiber.StatusCreated, healthInsuranceCompanyResource(row, stateDetails, landDetails))
+}
+
+// UpdateHealthInsuranceCompany godoc
+// @Summary Update health insurance company (partial)
+// @Description Patch health insurance company by ID.
+// @Tags Hospital - Health Insurance Companies
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Health Insurance Company UUID (UUIDv7)"
+// @Param request body dto.HealthInsuranceCompanyUpdateRequest true "JSON:API health insurance company update request"
+// @Success 200 {object} dto.HealthInsuranceCompanyResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/health-insurance-companies/update/{uuid} [patch]
+func (h *HealthInsuranceCompaniesHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeHealthInsuranceErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.HealthInsuranceCompanyUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHealthInsuranceErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHealthInsuranceErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeHealthInsuranceErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeHealthInsuranceErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Name == nil && !attrs.SortKey.Set && attrs.LandID == nil && attrs.State == nil && attrs.Address == nil && attrs.MobileNumber == nil && attrs.Email == nil && attrs.Note == nil && attrs.IsActive == nil {
+		return writeHealthInsuranceErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeHealthInsuranceErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "health insurance company not found",
+		}})
+	}
+
+	if attrs.Name != nil {
+		v := strings.TrimSpace(*attrs.Name)
+		if v == "" {
+			return writeHealthInsuranceErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+			}})
+		}
+		existing.Name = v
+	}
+	if attrs.SortKey.Set {
+		if attrs.SortKey.Valid {
+			sortKey := attrs.SortKey.Value
+			existing.SortKey = &sortKey
+		} else {
+			existing.SortKey = nil
+		}
+	}
+	if attrs.LandID != nil {
+		landID, parseErr := parseNullableUUID(*attrs.LandID)
+		if parseErr != nil {
+			return writeHealthInsuranceErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "land_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/land_id"},
+			}})
+		}
+		existing.LandID = landID
+	}
+	if attrs.State != nil {
+		existing.State = strings.TrimSpace(*attrs.State)
+	}
+	if attrs.Address != nil {
+		existing.Address = strings.TrimSpace(*attrs.Address)
+	}
+	if attrs.MobileNumber != nil {
+		existing.MobileNumber = strings.TrimSpace(*attrs.MobileNumber)
+	}
+	if attrs.Email != nil {
+		existing.Email = strings.TrimSpace(*attrs.Email)
+	}
+	if attrs.Note != nil {
+		existing.Note = strings.TrimSpace(*attrs.Note)
+	}
+	if attrs.IsActive != nil {
+		existing.IsActive = *attrs.IsActive
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeHealthInsuranceErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	stateDetails, _ := h.svc.ResolveStateDetails(c.UserContext(), []string{existing.State})
+	landDetails, _ := h.svc.ResolveLandDetails(c.UserContext(), collectHealthInsuranceLandIDs([]health_insurance_companies.HealthInsuranceCompany{*existing}))
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, healthInsuranceCompanyResource(updated, stateDetails, landDetails))
+	}
+	return response.Write(c, fiber.StatusOK, healthInsuranceCompanyResource(existing, stateDetails, landDetails))
+}
+
+// DeleteHealthInsuranceCompany godoc
+// @Summary Delete health insurance company
+// @Tags Hospital - Health Insurance Companies
+// @Produce json
+// @Param uuid path string true "Health Insurance Company UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/health-insurance-companies/delete/{uuid} [delete]
+func (h *HealthInsuranceCompaniesHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeHealthInsuranceErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeHealthInsuranceErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "health insurance company not found"}})
+		}
+		if _, ok := apperrors.AsDeleteConflict(err); ok {
+			return writeHealthInsuranceErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{Status: "409", Title: "Conflict", Detail: safeInternalDetail()}})
+		}
+		return writeHealthInsuranceErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Delete failed", Detail: safeInternalDetail()}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "health_insurance_company_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListHealthInsuranceCompanies godoc
+// @Summary List health insurance companies
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, state, -state, address, -address, mobile_number, -mobile_number, email, -email, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.
+// @Tags Hospital - Health Insurance Companies
+// @Produce json
+// @Param filter[search] query string false "Search by name/state/address/mobile/email"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.HealthInsuranceCompanyListResponse
+// @Router /api/v1/health-insurance-companies/get-all [get]
+func (h *HealthInsuranceCompaniesHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("filter[name]")
+	}
+	if filter == "" {
+		filter = c.Query("search")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return writeHealthInsuranceErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	stateDetails, _ := h.svc.ResolveStateDetails(c.UserContext(), collectHealthInsuranceStateNames(rows))
+	landDetails, _ := h.svc.ResolveLandDetails(c.UserContext(), collectHealthInsuranceLandIDs(rows))
+	data := make([]dto.HealthInsuranceCompanyResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, healthInsuranceCompanyResource(&rows[i], stateDetails, landDetails))
+	}
+
+	meta := map[string]any{
+		"total": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListHealthInsuranceCompaniesDatatable godoc
+// @Summary List health insurance companies (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags Hospital - Health Insurance Companies
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.HealthInsuranceCompanyDataTableResponse
+// @Router /api/v1/health-insurance-companies/get-all/dt [get]
+func (h *HealthInsuranceCompaniesHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return writeHealthInsuranceErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	stateDetails, _ := h.svc.ResolveStateDetails(c.UserContext(), collectHealthInsuranceStateNames(rows))
+	landDetails, _ := h.svc.ResolveLandDetails(c.UserContext(), collectHealthInsuranceLandIDs(rows))
+	data := make([]dto.HealthInsuranceCompanyResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, healthInsuranceCompanyResource(&rows[i], stateDetails, landDetails))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func healthInsuranceCompanyResource(row *health_insurance_companies.HealthInsuranceCompany, stateDetails map[string]health_insurance_companies.StateDetail, landDetails map[string]health_insurance_companies.LandDetail) dto.HealthInsuranceCompanyResource {
+	stateDetail := resolveHealthInsuranceStateDetail(row.State, stateDetails)
+	landDetail := resolveHealthInsuranceLandDetail(row.LandID, landDetails)
+	if stateDetail.LandID == "" {
+		stateDetail.LandID = landDetail.LandID
+	}
+	if stateDetail.LandName == "" {
+		stateDetail.LandName = landDetail.LandName
+	}
+	if stateDetail.LandISOCode == "" {
+		stateDetail.LandISOCode = landDetail.LandISOCode
+	}
+	return dto.HealthInsuranceCompanyResource{
+		Type: "health_insurance_company",
+		ID:   idString(row.ID),
+		Attributes: dto.HealthInsuranceCompanyAttributes{
+			LandID:         landIDString(row, stateDetail),
+			FederalStateID: stateDetail.FederalStateID,
+			FederalState:   stateDetail.FederalState,
+			LandName:       stateDetail.LandName,
+			LandISOCode:    stateDetail.LandISOCode,
+			Name:           row.Name,
+			SortKey:        cloneIntPointer(row.SortKey),
+			State:          row.State,
+			Address:        row.Address,
+			MobileNumber:   row.MobileNumber,
+			Email:          row.Email,
+			Note:           row.Note,
+			IsActive:       row.IsActive,
+			CreatedAt:      row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:      uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:      row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:      uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt:      timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:      uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func collectHealthInsuranceStateNames(rows []health_insurance_companies.HealthInsuranceCompany) []string {
+	out := make([]string, 0, len(rows))
+	for i := range rows {
+		out = append(out, rows[i].State)
+	}
+	return out
+}
+
+func collectHealthInsuranceLandIDs(rows []health_insurance_companies.HealthInsuranceCompany) []string {
+	out := make([]string, 0, len(rows))
+	for i := range rows {
+		if len(rows[i].LandID) == 0 {
+			continue
+		}
+		out = append(out, strings.ToLower(hex.EncodeToString(rows[i].LandID)))
+	}
+	return out
+}
+
+func resolveHealthInsuranceStateDetail(state string, details map[string]health_insurance_companies.StateDetail) health_insurance_companies.StateDetail {
+	key := strings.ToLower(strings.TrimSpace(state))
+	if key == "" || details == nil {
+		return health_insurance_companies.StateDetail{}
+	}
+	return details[key]
+}
+
+func resolveHealthInsuranceLandDetail(landID []byte, details map[string]health_insurance_companies.LandDetail) health_insurance_companies.LandDetail {
+	if len(landID) == 0 || details == nil {
+		return health_insurance_companies.LandDetail{}
+	}
+	return details[strings.ToLower(hex.EncodeToString(landID))]
+}
+
+func landIDString(row *health_insurance_companies.HealthInsuranceCompany, detail health_insurance_companies.StateDetail) string {
+	if row != nil && len(row.LandID) > 0 {
+		return idString(row.LandID)
+	}
+	return detail.LandID
+}
+
+func writeHealthInsuranceErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferHealthInsuranceDef(status, e.Title, e.Detail)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		e.Detail = def.Message
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferHealthInsuranceErrorCode(status int, title, detail string) (string, string) {
+	def := inferHealthInsuranceDef(status, title, detail)
+	return def.Code, def.ErrorCode
+}
+
+func inferHealthInsuranceDef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.ErrHealthInsuranceNotFound
+	case fiber.StatusConflict:
+		return apperrorsx.ErrHealthInsuranceRelationDelete
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid"):
+			return apperrorsx.ErrHealthInsuranceInvalidUUID
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.ErrHealthInsuranceIDRequired
+		case strings.Contains(lowerDetail, "id does not match"):
+			return apperrorsx.ErrHealthInsuranceIDMismatch
+		case strings.Contains(lowerDetail, "at least one attribute"):
+			return apperrorsx.ErrHealthInsuranceAttributesRequired
+		case strings.Contains(lowerDetail, "name is required"), strings.Contains(lowerDetail, "name cannot be empty"):
+			return apperrorsx.ErrHealthInsuranceNameRequired
+		case strings.Contains(lowerDetail, "land_id is invalid"):
+			return apperrorsx.ErrHealthInsuranceLandIDInvalid
+		default:
+			return apperrorsx.ErrHealthInsuranceInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrHealthInsuranceInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.ErrHealthInsuranceCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrHealthInsuranceUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrHealthInsuranceDeleteFailed
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.ErrHealthInsuranceListFailed
+		default:
+			return apperrorsx.ErrHealthInsuranceInvalidPayload
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
diff --git a/internal/transport/http/handlers/health_insurance_companies_handler_test.go b/internal/transport/http/handlers/health_insurance_companies_handler_test.go
new file mode 100644
index 0000000..c89a4fc
--- /dev/null
+++ b/internal/transport/http/handlers/health_insurance_companies_handler_test.go
@@ -0,0 +1,699 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/health_insurance_companies"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type memHealthInsuranceCompaniesRepo struct {
+	rows map[string]*health_insurance_companies.HealthInsuranceCompany
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+
+	listRows  []health_insurance_companies.HealthInsuranceCompany
+	listTotal int64
+
+	getByIDFn func(id []byte, call int) (*health_insurance_companies.HealthInsuranceCompany, error)
+	getCalls  int
+
+	lastCreate     *health_insurance_companies.HealthInsuranceCompany
+	lastUpdate     *health_insurance_companies.HealthInsuranceCompany
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+}
+
+func newMemHealthInsuranceCompaniesRepo() *memHealthInsuranceCompaniesRepo {
+	return &memHealthInsuranceCompaniesRepo{
+		rows: map[string]*health_insurance_companies.HealthInsuranceCompany{},
+	}
+}
+
+func (r *memHealthInsuranceCompaniesRepo) Create(_ context.Context, row *health_insurance_companies.HealthInsuranceCompany) error {
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.rows[string(row.ID)] = row
+	r.lastCreate = row
+	return nil
+}
+
+func (r *memHealthInsuranceCompaniesRepo) Update(_ context.Context, row *health_insurance_companies.HealthInsuranceCompany) error {
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	r.rows[string(row.ID)] = row
+	r.lastUpdate = row
+	return nil
+}
+
+func (r *memHealthInsuranceCompaniesRepo) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	r.lastDeleteID = append([]byte(nil), id...)
+	r.lastDeleteBy = append([]byte(nil), deletedBy...)
+	delete(r.rows, string(id))
+	return nil
+}
+
+func (r *memHealthInsuranceCompaniesRepo) GetByID(_ context.Context, id []byte) (*health_insurance_companies.HealthInsuranceCompany, error) {
+	r.getCalls++
+	if r.getByIDFn != nil {
+		return r.getByIDFn(id, r.getCalls)
+	}
+	if r.getByIDErr != nil {
+		return nil, r.getByIDErr
+	}
+	return r.rows[string(id)], nil
+}
+
+func (r *memHealthInsuranceCompaniesRepo) List(_ context.Context, filter, sort string, limit, offset int) ([]health_insurance_companies.HealthInsuranceCompany, int64, error) {
+	r.lastListFilter = filter
+	r.lastListSort = sort
+	r.lastListLimit = limit
+	r.lastListOffset = offset
+	if r.listErr != nil {
+		return nil, 0, r.listErr
+	}
+	return r.listRows, r.listTotal, nil
+}
+
+func (r *memHealthInsuranceCompaniesRepo) ResolveStateDetails(_ context.Context, stateNames []string) (map[string]health_insurance_companies.StateDetail, error) {
+	out := map[string]health_insurance_companies.StateDetail{}
+	for i := range stateNames {
+		if stateNames[i] == "Berlin" {
+			out["berlin"] = health_insurance_companies.StateDetail{
+				FederalStateID: "019dfb03-afc1-7ad0-8606-715fe5fdc57f",
+				FederalState:   "Berlin",
+				LandName:       "Deutschland",
+				LandISOCode:    "DE",
+			}
+		}
+	}
+	return out, nil
+}
+
+func (r *memHealthInsuranceCompaniesRepo) ResolveLandDetails(_ context.Context, landIDs []string) (map[string]health_insurance_companies.LandDetail, error) {
+	out := map[string]health_insurance_companies.LandDetail{}
+	for i := range landIDs {
+		key := strings.ToLower(strings.ReplaceAll(strings.TrimSpace(landIDs[i]), "-", ""))
+		if key == "018f3a5c7a6f7c2a8d4a4b5b1f6c8e9d" {
+			out[key] = health_insurance_companies.LandDetail{
+				LandID:      key,
+				LandName:    "Deutschland",
+				LandISOCode: "DE",
+			}
+		}
+	}
+	return out, nil
+}
+
+func newHealthInsuranceCompaniesTestApp(h *HealthInsuranceCompaniesHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", actor)
+		}
+		return c.Next()
+	})
+	app.Post("/api/v1/health-insurance-companies/create", h.Create)
+	app.Patch("/api/v1/health-insurance-companies/update/:uuid", h.Update)
+	app.Delete("/api/v1/health-insurance-companies/delete/:uuid", h.Delete)
+	app.Get("/api/v1/health-insurance-companies/get-all", h.List)
+	app.Get("/api/v1/health-insurance-companies/get-all/dt", h.ListDatatable)
+	return app
+}
+
+func doJSONRequestHealthInsuranceCompanies(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDStringHealthInsuranceCompanies(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestNewHealthInsuranceCompaniesHandler(t *testing.T) {
+	h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(newMemHealthInsuranceCompaniesRepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+func TestHealthInsuranceCompaniesHandlerCreate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPost, "/api/v1/health-insurance-companies/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPost, "/api/v1/health-insurance-companies/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"health_insurance_company","attributes":{"name":"  "}}}`)
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPost, "/api/v1/health-insurance-companies/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		repo.createErr = errors.New("create failed")
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"health_insurance_company","attributes":{"name":"Main"}}}`)
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPost, "/api/v1/health-insurance-companies/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		actor := uuidv7.MustBytes()
+		app := newHealthInsuranceCompaniesTestApp(h, actor)
+
+		body := []byte(`{"data":{"type":"health_insurance_company","attributes":{"name":"Main","sortkey":3,"state":"Berlin","address":"Main Street","mobile_number":"+491234","email":"main@hic.local","is_active":false}}}`)
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPost, "/api/v1/health-insurance-companies/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected row created")
+		}
+		if repo.lastCreate.State != "Berlin" || repo.lastCreate.Address != "Main Street" || repo.lastCreate.MobileNumber != "+491234" || repo.lastCreate.Email != "main@hic.local" {
+			t.Fatalf("expected optional attributes to be mapped")
+		}
+		if repo.lastCreate.SortKey == nil || *repo.lastCreate.SortKey != 3 {
+			t.Fatalf("expected sortkey mapped")
+		}
+		if repo.lastCreate.IsActive {
+			t.Fatalf("expected is_active false")
+		}
+		if string(repo.lastCreate.CreatedBy) != string(actor) || string(repo.lastCreate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected created_by and updated_by from actor")
+		}
+	})
+
+	t.Run("success with land_id fallback", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"health_insurance_company","attributes":{"name":"Main","land_id":"018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d"}}}`)
+		resp, body := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPost, "/api/v1/health-insurance-companies/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+
+		var doc struct {
+			Data struct {
+				Attributes struct {
+					LandID   string `json:"land_id"`
+					LandName string `json:"land_name"`
+				} `json:"attributes"`
+			} `json:"data"`
+		}
+		if err := json.Unmarshal(body, &doc); err != nil {
+			t.Fatalf("unmarshal body: %v", err)
+		}
+		if doc.Data.Attributes.LandID != "018f3a5c-7a6f-7c2a-8d4a-4b5b1f6c8e9d" {
+			t.Fatalf("expected land_id returned")
+		}
+		if doc.Data.Attributes.LandName != "Deutschland" {
+			t.Fatalf("expected land_name Deutschland, got %q", doc.Data.Attributes.LandName)
+		}
+	})
+	t.Run("success fallback when refetch error", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		repo.getByIDFn = func(_ []byte, call int) (*health_insurance_companies.HealthInsuranceCompany, error) {
+			if call > 0 {
+				return nil, errors.New("lookup failed")
+			}
+			return nil, nil
+		}
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"health_insurance_company","attributes":{"name":"Main"}}}`)
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPost, "/api/v1/health-insurance-companies/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHealthInsuranceCompaniesHandlerUpdate(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPatch, "/api/v1/health-insurance-companies/update/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+		id := mustUUIDStringHealthInsuranceCompanies(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPatch, "/api/v1/health-insurance-companies/update/"+id, []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+		id := mustUUIDStringHealthInsuranceCompanies(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPatch, "/api/v1/health-insurance-companies/update/"+id, []byte(`{"data":{"type":"x","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+		id := mustUUIDStringHealthInsuranceCompanies(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPatch, "/api/v1/health-insurance-companies/update/"+id, []byte(`{"data":{"type":"health_insurance_company","id":"","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+		id := mustUUIDStringHealthInsuranceCompanies(t, uuidv7.MustBytes())
+		other := mustUUIDStringHealthInsuranceCompanies(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPatch, "/api/v1/health-insurance-companies/update/"+id, []byte(`{"data":{"type":"health_insurance_company","id":"`+other+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no attributes", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+		id := mustUUIDStringHealthInsuranceCompanies(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPatch, "/api/v1/health-insurance-companies/update/"+id, []byte(`{"data":{"type":"health_insurance_company","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+		id := mustUUIDStringHealthInsuranceCompanies(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPatch, "/api/v1/health-insurance-companies/update/"+id, []byte(`{"data":{"type":"health_insurance_company","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &health_insurance_companies.HealthInsuranceCompany{ID: id, Name: "Old"}
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+		idStr := mustUUIDStringHealthInsuranceCompanies(t, id)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPatch, "/api/v1/health-insurance-companies/update/"+idStr, []byte(`{"data":{"type":"health_insurance_company","id":"`+idStr+`","attributes":{"name":"  "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &health_insurance_companies.HealthInsuranceCompany{ID: id, Name: "Old"}
+		repo.updateErr = errors.New("update failed")
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+		idStr := mustUUIDStringHealthInsuranceCompanies(t, id)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPatch, "/api/v1/health-insurance-companies/update/"+idStr, []byte(`{"data":{"type":"health_insurance_company","id":"`+idStr+`","attributes":{"name":"New"}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &health_insurance_companies.HealthInsuranceCompany{ID: id, Name: "Old"}
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		actor := uuidv7.MustBytes()
+		app := newHealthInsuranceCompaniesTestApp(h, actor)
+		idStr := mustUUIDStringHealthInsuranceCompanies(t, id)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPatch, "/api/v1/health-insurance-companies/update/"+idStr, []byte(`{"data":{"type":"health_insurance_company","id":"`+idStr+`","attributes":{"name":"New","state":"Bayern","address":"Street 1","mobile_number":"+49888","email":"new@hic.local"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.Name != "New" || repo.lastUpdate.State != "Bayern" || repo.lastUpdate.Address != "Street 1" || repo.lastUpdate.MobileNumber != "+49888" || repo.lastUpdate.Email != "new@hic.local" {
+			t.Fatalf("expected updated values")
+		}
+		if string(repo.lastUpdate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected updated_by from actor")
+		}
+	})
+
+	t.Run("success update sortkey and is_active", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &health_insurance_companies.HealthInsuranceCompany{ID: id, Name: "Old", IsActive: true}
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+		idStr := mustUUIDStringHealthInsuranceCompanies(t, id)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPatch, "/api/v1/health-insurance-companies/update/"+idStr, []byte(`{"data":{"type":"health_insurance_company","id":"`+idStr+`","attributes":{"sortkey":2,"is_active":false}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil {
+			t.Fatalf("expected update called")
+		}
+		if repo.lastUpdate.SortKey == nil || *repo.lastUpdate.SortKey != 2 {
+			t.Fatalf("expected sortkey updated")
+		}
+		if repo.lastUpdate.IsActive {
+			t.Fatalf("expected is_active false")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		id := uuidv7.MustBytes()
+		existing := &health_insurance_companies.HealthInsuranceCompany{ID: id, Name: "Old"}
+		repo.getByIDFn = func(_ []byte, call int) (*health_insurance_companies.HealthInsuranceCompany, error) {
+			if call == 1 {
+				return existing, nil
+			}
+			return nil, errors.New("second lookup failed")
+		}
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+		idStr := mustUUIDStringHealthInsuranceCompanies(t, id)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodPatch, "/api/v1/health-insurance-companies/update/"+idStr, []byte(`{"data":{"type":"health_insurance_company","id":"`+idStr+`","attributes":{"state":"Only state"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHealthInsuranceCompaniesHandlerDelete(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodDelete, "/api/v1/health-insurance-companies/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete error", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		repo.deleteErr = errors.New("delete failed")
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+		id := mustUUIDStringHealthInsuranceCompanies(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodDelete, "/api/v1/health-insurance-companies/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		actor := uuidv7.MustBytes()
+		app := newHealthInsuranceCompaniesTestApp(h, actor)
+		id := uuidv7.MustBytes()
+		idStr := mustUUIDStringHealthInsuranceCompanies(t, id)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodDelete, "/api/v1/health-insurance-companies/delete/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(repo.lastDeleteBy) != string(actor) {
+			t.Fatalf("expected deleted_by from actor")
+		}
+	})
+}
+
+func TestHealthInsuranceCompaniesHandlerList(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodGet, "/api/v1/health-insurance-companies/get-all", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with filter name and clamp max", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		expectedID := uuidv7.MustBytes()
+		expectedIDStr := mustUUIDStringHealthInsuranceCompanies(t, expectedID)
+		repo.listRows = []health_insurance_companies.HealthInsuranceCompany{{ID: expectedID, Name: "A", State: "Berlin", SortKey: intPtrHICHandler(3), IsActive: true, CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		resp, body := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodGet, "/api/v1/health-insurance-companies/get-all?filter[name]=abc&page[number]=0&page=0&page[size]=0&limit=101&sort=-sortkey", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q sort=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListSort, repo.lastListLimit, repo.lastListOffset)
+		}
+		var doc struct {
+			Data []struct {
+				Type       string `json:"type"`
+				ID         string `json:"id"`
+				Attributes struct {
+					LandName string `json:"land_name"`
+				} `json:"attributes"`
+			} `json:"data"`
+		}
+		if err := json.Unmarshal(body, &doc); err != nil {
+			t.Fatalf("unmarshal body: %v", err)
+		}
+		if len(doc.Data) != 1 {
+			t.Fatalf("expected 1 row, got %d", len(doc.Data))
+		}
+		if doc.Data[0].Type != "health_insurance_company" {
+			t.Fatalf("unexpected type: %s", doc.Data[0].Type)
+		}
+		if doc.Data[0].ID != expectedIDStr {
+			t.Fatalf("expected id %s, got %s", expectedIDStr, doc.Data[0].ID)
+		}
+		if doc.Data[0].Attributes.LandName != "Deutschland" {
+			t.Fatalf("expected land_name Deutschland, got %q", doc.Data[0].Attributes.LandName)
+		}
+	})
+
+	t.Run("success with search and clamp min", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		repo.listRows = []health_insurance_companies.HealthInsuranceCompany{}
+		repo.listTotal = 0
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodGet, "/api/v1/health-insurance-companies/get-all?page=2&size=-1&search=needle", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "needle" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestHealthInsuranceCompaniesHandlerListDatatable(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodGet, "/api/v1/health-insurance-companies/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success clamp max and page floor", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		repo.listRows = []health_insurance_companies.HealthInsuranceCompany{{ID: uuidv7.MustBytes(), Name: "A", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodGet, "/api/v1/health-insurance-companies/get-all/dt?page=0&limit=0&size=101&draw=7&search=abc", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListLimit != 100 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success clamp min", func(t *testing.T) {
+		repo := newMemHealthInsuranceCompaniesRepo()
+		repo.listRows = []health_insurance_companies.HealthInsuranceCompany{}
+		repo.listTotal = 0
+		h := NewHealthInsuranceCompaniesHandler(service.NewHealthInsuranceCompaniesService(repo))
+		app := newHealthInsuranceCompaniesTestApp(h, nil)
+
+		resp, _ := doJSONRequestHealthInsuranceCompanies(t, app, http.MethodGet, "/api/v1/health-insurance-companies/get-all/dt?page=2&limit=0&size=-1", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListLimit != 20 || repo.lastListOffset != 20 {
+			t.Fatalf("unexpected list params: limit=%d offset=%d", repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestHealthInsuranceCompaniesResource(t *testing.T) {
+	id := uuidv7.MustBytes()
+	createdBy := uuidv7.MustBytes()
+	updatedBy := uuidv7.MustBytes()
+	deletedBy := uuidv7.MustBytes()
+	now := time.Now().UTC().Truncate(time.Second)
+	deletedAt := now.Add(time.Hour)
+
+	row := &health_insurance_companies.HealthInsuranceCompany{
+		ID:           id,
+		Name:         "Main",
+		SortKey:      intPtrHICHandler(2),
+		State:        "Berlin",
+		Address:      "Street 1",
+		MobileNumber: "+491234",
+		Email:        "main@hic.local",
+		IsActive:     true,
+		CreatedAt:    now,
+		CreatedBy:    createdBy,
+		UpdatedAt:    now,
+		UpdatedBy:    updatedBy,
+		DeletedAt:    &deletedAt,
+		DeletedBy:    deletedBy,
+	}
+
+	res := healthInsuranceCompanyResource(row, map[string]health_insurance_companies.StateDetail{
+		"berlin": {
+			FederalStateID: "019dfb03-afc1-7ad0-8606-715fe5fdc57f",
+			FederalState:   "Berlin",
+			LandName:       "Deutschland",
+			LandISOCode:    "DE",
+		},
+	}, nil)
+	if res.Type != "health_insurance_company" {
+		t.Fatalf("unexpected type: %s", res.Type)
+	}
+	if res.Attributes.SortKey == nil || *res.Attributes.SortKey != 2 || !res.Attributes.IsActive {
+		t.Fatalf("expected sortkey and is_active in resource")
+	}
+	if res.ID == "" || res.Attributes.CreatedBy == "" || res.Attributes.UpdatedBy == "" || res.Attributes.DeletedBy == "" {
+		t.Fatalf("expected UUID fields in resource")
+	}
+	if res.Attributes.CreatedAt == "" || res.Attributes.UpdatedAt == "" || res.Attributes.DeletedAt == "" {
+		t.Fatalf("expected time fields in resource")
+	}
+	if res.Attributes.FederalStateID == "" || res.Attributes.FederalState == "" || res.Attributes.LandName == "" || res.Attributes.LandISOCode == "" {
+		t.Fatalf("expected federal state details in resource")
+	}
+}
+
+func intPtrHICHandler(v int) *int { return &v }
diff --git a/internal/transport/http/handlers/helicopter_error_mapping_test.go b/internal/transport/http/handlers/helicopter_error_mapping_test.go
new file mode 100644
index 0000000..906cde9
--- /dev/null
+++ b/internal/transport/http/handlers/helicopter_error_mapping_test.go
@@ -0,0 +1,83 @@
+package handlers
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestInferHelicopterErrorCode_StatusPrefixSync(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name   string
+		status int
+		title  string
+		detail string
+		prefix string
+		code   string
+	}{
+		{
+			name:   "duplicate uses conflict",
+			status: http.StatusConflict,
+			title:  "Conflict",
+			detail: "Serial number already exists",
+			prefix: "409",
+			code:   "HELICOPTER_DUPLICATE",
+		},
+		{
+			name:   "validation payload",
+			status: http.StatusUnprocessableEntity,
+			title:  "Validation error",
+			detail: "designation, identifier, and type are required",
+			prefix: "422",
+			code:   "HELICOPTER_INVALID_PAYLOAD",
+		},
+		{
+			name:   "validation invalid type",
+			status: http.StatusUnprocessableEntity,
+			title:  "Validation error",
+			detail: "type is oneof",
+			prefix: "422",
+			code:   "HELICOPTER_INVALID_TYPE",
+		},
+		{
+			name:   "bad request create failed",
+			status: http.StatusBadRequest,
+			title:  "Create failed",
+			detail: "some low-level error",
+			prefix: "400",
+			code:   "HELICOPTER_CREATE_FAILED",
+		},
+		{
+			name:   "not found",
+			status: http.StatusNotFound,
+			title:  "Not found",
+			detail: "helicopter not found",
+			prefix: "404",
+			code:   "HELICOPTER_NOT_FOUND",
+		},
+	}
+
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			code, errorCode := inferHelicopterErrorCode(tt.status, tt.title, tt.detail)
+			if code != tt.code {
+				t.Fatalf("unexpected code: got=%s want=%s", code, tt.code)
+			}
+			if !strings.HasPrefix(errorCode, tt.prefix) {
+				t.Fatalf("error_code prefix mismatch: status=%d code=%s error_code=%s", tt.status, code, errorCode)
+			}
+		})
+	}
+}
+
+func TestInferHelicopterErrorCode_400NeverReturns409Code(t *testing.T) {
+	t.Parallel()
+
+	_, errorCode := inferHelicopterErrorCode(http.StatusBadRequest, "Create failed", "already exists")
+	if strings.HasPrefix(errorCode, "409") {
+		t.Fatalf("bad request must not map to 409-prefixed error_code, got=%s", errorCode)
+	}
+}
diff --git a/internal/transport/http/handlers/helicopter_file_events_handler.go b/internal/transport/http/handlers/helicopter_file_events_handler.go
new file mode 100644
index 0000000..bcb273d
--- /dev/null
+++ b/internal/transport/http/handlers/helicopter_file_events_handler.go
@@ -0,0 +1,141 @@
+package handlers
+
+import (
+	"bufio"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	helicopterfilerealtime "wucher/internal/realtime/helicopterfile"
+	"wucher/internal/shared/pkg/uuidv7"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+)
+
+const (
+	helicopterFileSSEEventName = "helicopter.file.created"
+)
+
+type HelicopterFileEventsHandler struct {
+	hub *helicopterfilerealtime.Hub
+}
+
+type helicopterFileSSEFilter struct {
+	helicopterID *string
+}
+
+func NewHelicopterFileEventsHandler(hub *helicopterfilerealtime.Hub) *HelicopterFileEventsHandler {
+	return &HelicopterFileEventsHandler{hub: hub}
+}
+
+func (h *HelicopterFileEventsHandler) Stream(c *fiber.Ctx) error {
+	if h.hub == nil {
+		return writeFileManagerError(c, fiber.StatusServiceUnavailable, "Service unavailable", "helicopter file events stream is not configured", nil)
+	}
+
+	actorID := actorUserID(c)
+	if len(actorID) != 16 {
+		return writeFileManagerError(c, fiber.StatusUnauthorized, "Unauthorized", "invalid user context", nil)
+	}
+	userUUID, err := uuidv7.BytesToString(actorID)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusUnauthorized, "Unauthorized", "invalid user context", nil)
+	}
+
+	filter, err := parseHelicopterFileSSEFilter(c)
+	if err != nil {
+		return err
+	}
+
+	sub, err := h.hub.SubscribeWithFilter(userUUID, filter.match)
+	if err != nil {
+		return writeFileManagerError(c, fiber.StatusServiceUnavailable, "Service unavailable", "cannot subscribe to helicopter file events stream", nil)
+	}
+
+	c.Set(fiber.HeaderContentType, "text/event-stream")
+	c.Set(fiber.HeaderCacheControl, "no-cache, no-transform")
+	c.Set(fiber.HeaderConnection, "keep-alive")
+	c.Set("X-Accel-Buffering", "no")
+
+	c.Context().SetBodyStreamWriter(func(w *bufio.Writer) {
+		defer sub.Close()
+
+		if !writeSSEComment(w, "connected") {
+			return
+		}
+
+		heartbeat := time.NewTicker(20 * time.Second)
+		defer heartbeat.Stop()
+
+		for {
+			select {
+			case <-sub.Done():
+				return
+			case <-heartbeat.C:
+				if !writeSSEComment(w, "ping") {
+					return
+				}
+			case event, ok := <-sub.Events():
+				if !ok {
+					return
+				}
+				if !filter.match(event) {
+					continue
+				}
+				payload := mapHelicopterFileCreatedEventToSSEPayload(event)
+				if !writeSSEDataEvent(w, helicopterFileSSEEventName, payload) {
+					return
+				}
+			}
+		}
+	})
+
+	return nil
+}
+
+func parseHelicopterFileSSEFilter(c *fiber.Ctx) (helicopterFileSSEFilter, error) {
+	filter := helicopterFileSSEFilter{}
+
+	if rawHelicopterID := strings.TrimSpace(c.Query("helicopter_id")); rawHelicopterID != "" {
+		parsed, err := uuidv7.ParseString(rawHelicopterID)
+		if err != nil {
+			return helicopterFileSSEFilter{}, writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "helicopter_id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/query/helicopter_id"})
+		}
+		canonical, err := uuidv7.BytesToString(parsed)
+		if err != nil {
+			return helicopterFileSSEFilter{}, writeFileManagerError(c, fiber.StatusUnprocessableEntity, "Validation error", "helicopter_id is invalid UUID", &jsonapi.ErrorSource{Pointer: "/query/helicopter_id"})
+		}
+		canonical = strings.ToLower(strings.TrimSpace(canonical))
+		filter.helicopterID = &canonical
+	}
+
+	return filter, nil
+}
+
+func (f helicopterFileSSEFilter) match(event helicopterfilerealtime.Event) bool {
+	helicopterID := strings.ToLower(strings.TrimSpace(event.HelicopterID))
+	if helicopterID == "" {
+		return false
+	}
+	if f.helicopterID != nil && helicopterID != *f.helicopterID {
+		return false
+	}
+	return true
+}
+
+func mapHelicopterFileCreatedEventToSSEPayload(event helicopterfilerealtime.Event) responsedto.HelicopterFileCreatedSSEPayload {
+	payload := responsedto.HelicopterFileCreatedSSEPayload{
+		HelicopterID:      strings.TrimSpace(event.HelicopterID),
+		HelicopterFileID:  strings.TrimSpace(event.HelicopterFileID),
+		FileID:            strings.TrimSpace(event.FileID),
+		Section:           strings.TrimSpace(event.Section),
+		Position:          event.Position,
+		IsMandatory:       event.IsMandatory,
+		AttachmentPending: event.AttachmentPending,
+		Name:              strings.TrimSpace(event.Name),
+		MimeType:          strings.TrimSpace(event.MimeType),
+		UpdatedAt:         strings.TrimSpace(event.UpdatedAt),
+	}
+	return payload
+}
diff --git a/internal/transport/http/handlers/helicopter_file_handler.go b/internal/transport/http/handlers/helicopter_file_handler.go
new file mode 100644
index 0000000..8f4edba
--- /dev/null
+++ b/internal/transport/http/handlers/helicopter_file_handler.go
@@ -0,0 +1,1819 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/helicopter"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	takeoverdomain "wucher/internal/domain/takeover"
+	helicopterfilerealtime "wucher/internal/realtime/helicopterfile"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+const (
+	helicopterFileBulkMaxItems = 20
+)
+
+var (
+	_ responsedto.HelicopterFileResponse
+	_ responsedto.HelicopterFileListResponse
+)
+
+type HelicopterFileHandler struct {
+	svc                  helicopterfile.Service
+	helicopter           helicopter.Service
+	takeover             helicopterFileTakeoverLookup
+	fileManager          filemanager.Service
+	helicopterFileEvents helicopterFileEventPublisher
+	storage              fileManagerDownloadURLStorage
+	validate             *validators.Validator
+}
+
+type helicopterFileTakeoverLookup interface {
+	GetByID(ctx context.Context, id []byte) (*takeoverdomain.TakeoverAc, error)
+}
+
+func NewHelicopterFileHandler(svc helicopterfile.Service) *HelicopterFileHandler {
+	return &HelicopterFileHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+func (h *HelicopterFileHandler) WithFileManagerService(fileManagerSvc filemanager.Service) *HelicopterFileHandler {
+	h.fileManager = fileManagerSvc
+	return h
+}
+
+func (h *HelicopterFileHandler) WithHelicopterService(helicopterSvc helicopter.Service) *HelicopterFileHandler {
+	h.helicopter = helicopterSvc
+	return h
+}
+
+func (h *HelicopterFileHandler) WithTakeoverService(takeoverSvc helicopterFileTakeoverLookup) *HelicopterFileHandler {
+	h.takeover = takeoverSvc
+	return h
+}
+
+func (h *HelicopterFileHandler) WithFileStorage(storage fileManagerDownloadURLStorage) *HelicopterFileHandler {
+	h.storage = storage
+	return h
+}
+
+func (h *HelicopterFileHandler) WithHelicopterFileEvents(publisher helicopterFileEventPublisher) *HelicopterFileHandler {
+	h.helicopterFileEvents = publisher
+	return h
+}
+
+// UploadHelicopterFile godoc
+// @Summary Request upload intents + presigned PUT URLs (helicopter file)
+// @Description Control-plane endpoint for helicopter file upload intent + presigned URL flow.
+// @Description Public flow: POST /api/v1/helicopter-files/upload -> PUT to presigned URL -> POST /api/v1/helicopter-files/create.
+// @Description Canonical type is `helicopter_file_upload`.
+// @Description `required_headers` must be sent exactly as returned when doing PUT to `upload_url`.
+// @Description Example `required_headers`: `{"content-type":"application/pdf","x-amz-acl":"private"}`
+// @Description Supports single and bulk payload.
+// @Description Single payload example: `{"data":{"type":"helicopter_file_upload","attributes":{"name":"A.pdf","content_type":"application/pdf","size_bytes":12345}}}`
+// @Description Bulk payload example: `{"data":[{"type":"helicopter_file_upload","attributes":{"name":"A.pdf","content_type":"application/pdf","size_bytes":12345}}]}`
+// @Description Note: OpenAPI 2.0 cannot express object-or-array union in one schema; request schema below represents bulk envelope.
+// @Tags Helicopter - Master File
+// @Accept json
+// @Produce json
+// @Param request body requestdto.HelicopterFileUploadBulkRequest true "Helicopter file upload intent request (single object or bulk array)"
+// @Success 201 {object} responsedto.HelicopterFileUploadIntentResponse
+// @Success 200 {object} responsedto.HelicopterFileUploadIntentBulkResponse
+// @Success 207 {object} responsedto.HelicopterFileUploadIntentBulkResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/helicopter-files/upload [post]
+func (h *HelicopterFileHandler) Upload(c *fiber.Ctx) error {
+	if h.fileManager == nil {
+		writeHelicopterFileBadRequestError(c, "Upload failed", "file manager service is not configured")
+		return nil
+	}
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if isBulk {
+		return h.uploadBulk(c)
+	}
+
+	var req requestdto.HelicopterFileUploadRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	typ := strings.TrimSpace(req.Data.Type)
+	if typ != "helicopter_file_upload" {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "type must be helicopter_file_upload",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/type"},
+		}})
+	}
+
+	name := strings.TrimSpace(req.Data.Attributes.Name)
+	contentType := strings.TrimSpace(req.Data.Attributes.ContentType)
+	sizeBytes := req.Data.Attributes.SizeBytes
+
+	grant, grantErr := h.fileManager.RequestFileUploadIntent(c.Context(), filemanager.RequestFileUploadIntentParams{
+		Name:        name,
+		ContentType: contentType,
+		SizeBytes:   sizeBytes,
+		ActorID:     actorUserID(c),
+	})
+	if grantErr != nil {
+		return writeFileManagerActionError(c, "Upload intent failed", grantErr)
+	}
+
+	baseResource := fileManagerFileUploadIntentResource(grant)
+	resource := responsedto.HelicopterFileUploadIntentResource{
+		Type:       "helicopter_file_upload_intent",
+		ID:         baseResource.ID,
+		Attributes: baseResource.Attributes,
+	}
+	return response.Write(c, fiber.StatusCreated, resource)
+}
+
+func (h *HelicopterFileHandler) uploadBulk(c *fiber.Ctx) error {
+	var req requestdto.HelicopterFileUploadBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if len(req.Data) == 0 {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "data must contain at least one item",
+			Source: &jsonapi.ErrorSource{Pointer: "/data"},
+		}})
+	}
+	if len(req.Data) > helicopterFileBulkMaxItems {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "too many items in one request",
+			Source: &jsonapi.ErrorSource{Pointer: "/data"},
+		}})
+	}
+
+	inputs := make([]helicopterfile.UploadIntentBulkInput, len(req.Data))
+	for i := range req.Data {
+		item := req.Data[i]
+		inputs[i] = helicopterfile.UploadIntentBulkInput{
+			Type:        strings.TrimSpace(item.Type),
+			Name:        strings.TrimSpace(item.Attributes.Name),
+			ContentType: strings.TrimSpace(item.Attributes.ContentType),
+			SizeBytes:   item.Attributes.SizeBytes,
+		}
+	}
+
+	results := h.svc.RequestUploadIntentsBulk(c.Context(), inputs, actorUserID(c))
+	items := make([]responsedto.HelicopterFileUploadIntentBulkItem, len(results))
+	for i := range results {
+		result := results[i]
+		if result.Success && result.Grant != nil {
+			baseResource := fileManagerFileUploadIntentResource(result.Grant)
+			resource := responsedto.HelicopterFileUploadIntentResource{
+				Type:       "helicopter_file_upload_intent",
+				ID:         baseResource.ID,
+				Attributes: baseResource.Attributes,
+			}
+			items[i] = responsedto.HelicopterFileUploadIntentBulkItem{
+				Index:    result.Index,
+				Success:  true,
+				Resource: &resource,
+			}
+			continue
+		}
+
+		errStatus := fiber.StatusInternalServerError
+		errTitle := "Internal error"
+		errDetail := "missing item error"
+		if result.Error != nil {
+			errStatus = result.Error.Status
+			errTitle = result.Error.Title
+			errDetail = result.Error.Detail
+		}
+		items[i] = helicopterFileUploadBulkErrorItem(result.Index, errStatus, errTitle, errDetail)
+	}
+
+	return writeHelicopterFileUploadIntentBulkResponse(c, items)
+}
+
+// CancelUploadHelicopterFile godoc
+// @Summary Cancel helicopter file upload intent (bulk)
+// @Description Cancel pending upload intents from helicopter file upload flow.
+// @Description Bulk payload accepts one or many items.
+// @Tags Helicopter - Master File
+// @Accept json
+// @Produce json
+// @Param request body requestdto.HelicopterFileCancelUploadBulkRequest true "Bulk helicopter file cancel upload intent request"
+// @Success 200 {object} responsedto.FileManagerFileCancelUploadBulkResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/helicopter-files/cancel-upload [post]
+func (h *HelicopterFileHandler) CancelUpload(c *fiber.Ctx) error {
+	if h.fileManager == nil {
+		writeHelicopterFileBadRequestError(c, "Cancel upload failed", "file manager service is not configured")
+		return nil
+	}
+
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if !isBulk {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "data must be an array",
+			Source: &jsonapi.ErrorSource{Pointer: "/data"},
+		}})
+	}
+
+	var req requestdto.HelicopterFileCancelUploadBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if len(req.Data) == 0 {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "data must contain at least one item",
+			Source: &jsonapi.ErrorSource{Pointer: "/data"},
+		}})
+	}
+
+	items := make([]responsedto.FileManagerFileCancelUploadBulkItem, len(req.Data))
+	for i := range req.Data {
+		item := req.Data[i]
+		if strings.TrimSpace(item.Type) != "helicopter_file_cancel_upload" {
+			items[i] = fileManagerCancelUploadBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "type must be helicopter_file_cancel_upload")
+			continue
+		}
+
+		uploadIntentID, parseErr := uuidv7.ParseString(strings.TrimSpace(item.Attributes.UploadIntentUUID))
+		if parseErr != nil {
+			items[i] = fileManagerCancelUploadBulkSystemErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", "upload_intent_uuid is invalid UUID")
+			continue
+		}
+
+		if cancelErr := h.fileManager.CancelFileUploadIntent(c.UserContext(), filemanager.CancelFileUploadIntentParams{
+			UploadIntentID: uploadIntentID,
+			ActorID:        actorUserID(c),
+		}); cancelErr != nil {
+			items[i] = fileManagerCancelUploadBulkActionErrorItem(i, "Cancel upload failed", cancelErr)
+			continue
+		}
+
+		items[i] = fileManagerCancelUploadBulkSuccessItem(i, uploadIntentID)
+	}
+
+	return writeFileManagerCancelUploadBulkResponse(c, items)
+}
+
+// CreateHelicopterFile godoc
+// @Summary Create helicopter file
+// @Description Create helicopter file template record from upload intent.
+// @Description Section allowed values: `bfi` (Before First Flight Inspection), `fpwb` (Flight Preparation and WB), `afi` (After Last Flight Inspection).
+// @Description Required attributes: `section`, `helicopter_id`, `upload_intent_uuid`, `file_name`.
+// @Description Optional attributes: `position`, `is_required`, `folder_uuid` (if omitted, file is created in root folder).
+// @Description When `position` is omitted (or <= 0), backend auto-assigns next position per `helicopter_id + section`.
+// @Description If file name already exists in target folder, existing file is reused and attached.
+// @Description Supports single and bulk payload.
+// @Description Single payload example: `{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","position":1,"is_required":true,"helicopter_id":"019d6771-5fb5-7337-837f-bc5ed85181a1","upload_intent_uuid":"019d6d0d-2de2-7db1-80a2-2862d43af620","file_name":"A.pdf"}}}`
+// @Description Bulk payload example: `{"data":[{"type":"helicopter_file_create","attributes":{"section":"bfi","position":1,"is_required":true,"helicopter_id":"019d6771-5fb5-7337-837f-bc5ed85181a1","upload_intent_uuid":"019d6d0d-2de2-7db1-80a2-2862d43af620","file_name":"A.pdf"}}]}`
+// @Description Note: OpenAPI 2.0 cannot express object-or-array union in one schema; request schema below represents bulk envelope.
+// @Tags Helicopter - Master File
+// @Accept json
+// @Produce json
+// @Param request body requestdto.HelicopterFileCreateBulkRequest true "JSON:API helicopter file create request (single object or bulk array)"
+// @Success 201 {object} responsedto.HelicopterFileResponse
+// @Success 200 {object} responsedto.HelicopterFileCreateBulkResponse
+// @Success 207 {object} responsedto.HelicopterFileCreateBulkResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/helicopter-files/create [post]
+func (h *HelicopterFileHandler) Create(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if isBulk {
+		return h.createBulk(c)
+	}
+
+	var req requestdto.HelicopterFileCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	section := strings.TrimSpace(req.Data.Attributes.Section)
+	if !isValidHelicopterFileSection(section) {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "section is invalid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/section"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	helicopterRaw := strings.TrimSpace(attrs.HelicopterID)
+	if helicopterRaw == "" {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "helicopter_id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/helicopter_id"},
+		}})
+	}
+	helicopterID, err := uuidv7.ParseString(helicopterRaw)
+	if err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "helicopter_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/helicopter_id"},
+		}})
+	}
+	exists, err := h.svc.HelicopterExists(c.UserContext(), helicopterID)
+	if err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if !exists {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "helicopter_id not found",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/helicopter_id"},
+		}})
+	}
+
+	uploadIntentUUID := strings.TrimSpace(attrs.UploadIntentUUID)
+	fileName := strings.TrimSpace(attrs.FileName)
+	uploadIntentID, parseErr := uuidv7.ParseString(uploadIntentUUID)
+	if parseErr != nil {
+		writeHelicopterFileValidationError(c, "upload_intent_uuid is invalid UUID", "/data/attributes/upload_intent_uuid")
+		return nil
+	}
+	if fileName == "" {
+		writeHelicopterFileValidationError(c, "file_name is required", "/data/attributes/file_name")
+		return nil
+	}
+	if h.fileManager == nil {
+		writeHelicopterFileBadRequestError(c, "Create failed", "file manager service is not configured")
+		return nil
+	}
+
+	var folderID []byte
+	folderProvided := false
+	if attrs.FolderUUID != nil {
+		folderProvided = true
+		folderUUID := strings.TrimSpace(*attrs.FolderUUID)
+		if folderUUID != "" {
+			parsedFolderID, folderErr := uuidv7.ParseString(folderUUID)
+			if folderErr != nil {
+				writeHelicopterFileValidationError(c, "folder_uuid is invalid UUID", "/data/attributes/folder_uuid")
+				return nil
+			}
+			folderID = parsedFolderID
+		}
+	} else {
+		root, rootErr := h.fileManager.GetOrCreateSystemRootFolder(c.UserContext())
+		if rootErr == nil && root != nil && len(root.ID) == 16 {
+			folderID = root.ID
+			folderProvided = true
+		}
+	}
+	reusedExistingFile := false
+	createdFile, createErr := h.fileManager.CreateFileNodeFromUploadIntent(c.UserContext(), filemanager.CreateFileFromUploadIntentParams{
+		UploadIntentID: uploadIntentID,
+		FolderID:       folderID,
+		FolderProvided: folderProvided,
+		Name:           fileName,
+		ActorID:        actorUserID(c),
+		IsTemplate:     true,
+	})
+	if createErr != nil {
+		if errors.Is(createErr, filemanager.ErrDuplicateName) {
+			reusedExistingFile = true
+			targetFolderID := folderID
+			if !folderProvided || len(targetFolderID) == 0 {
+				root, rootErr := h.fileManager.GetOrCreateSystemRootFolder(c.UserContext())
+				if rootErr != nil || root == nil {
+					detail := "unable to resolve target folder"
+					if rootErr != nil {
+						detail = rootErr.Error()
+					}
+					writeHelicopterFileBadRequestError(c, "Create failed", detail)
+					return nil
+				}
+				targetFolderID = root.ID
+			}
+
+			nameNormalized := strings.ToLower(filepath.Base(strings.TrimSpace(fileName)))
+			if nameNormalized == "" {
+				writeHelicopterFileValidationError(c, "file_name is invalid", "/data/attributes/file_name")
+				return nil
+			}
+			existingFile, existingErr := h.fileManager.GetFileByFolderAndName(c.UserContext(), targetFolderID, nameNormalized)
+			if existingErr != nil || existingFile == nil {
+				detail := "duplicate file exists but cannot be resolved"
+				if existingErr != nil {
+					detail = existingErr.Error()
+				}
+				writeHelicopterFileBadRequestError(c, "Create failed", detail)
+				return nil
+			}
+			createdFile = existingFile
+		} else {
+			writeHelicopterFileBadRequestError(c, "Create failed", createErr.Error())
+			return nil
+		}
+	}
+	if createdFile == nil {
+		writeHelicopterFileBadRequestError(c, "Create failed", "unable to create file from upload intent")
+		return nil
+	}
+
+	if err := h.validateStoredHelicopterFileContent(c.UserContext(), createdFile); err != nil {
+		// Freshly uploaded corrupt files are removed; a reused existing template is left
+		// intact (it may be referenced elsewhere) and only reported.
+		if !reusedExistingFile {
+			_ = h.fileManager.DeleteFile(c.UserContext(), createdFile.ID, actorUserID(c), nil)
+		}
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uploaded file content is corrupt or unsupported",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/upload_intent_uuid"},
+		}})
+	}
+
+	row := &helicopterfile.HelicopterFile{
+		Section:      section,
+		Position:     intOrDefault(attrs.Position, 0),
+		IsMandatory:  boolOrDefault(attrs.IsMandatory, false),
+		HelicopterID: helicopterID,
+		SourceFileID: append([]byte(nil), createdFile.ID...),
+		CreatedBy:    actorUserID(c),
+		UpdatedBy:    actorUserID(c),
+	}
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	h.publishHelicopterFileCreated(actorUserID(c), row, createdFile)
+
+	createdRow, getErr := h.svc.GetByID(c.UserContext(), row.ID)
+	if getErr == nil && createdRow != nil {
+		return response.Write(c, fiber.StatusCreated, helicopterFileResource(c.UserContext(), h.storage, createdRow))
+	}
+
+	return response.Write(c, fiber.StatusCreated, helicopterFileResource(c.UserContext(), h.storage, row))
+}
+
+func (h *HelicopterFileHandler) createBulk(c *fiber.Ctx) error {
+	var req requestdto.HelicopterFileCreateBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if len(req.Data) == 0 {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "data must contain at least one item",
+			Source: &jsonapi.ErrorSource{Pointer: "/data"},
+		}})
+	}
+	if len(req.Data) > helicopterFileBulkMaxItems {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "too many items in one request",
+			Source: &jsonapi.ErrorSource{Pointer: "/data"},
+		}})
+	}
+
+	inputs := make([]helicopterfile.CreateBulkInput, len(req.Data))
+	for i := range req.Data {
+		item := req.Data[i]
+		inputs[i] = helicopterfile.CreateBulkInput{
+			Type:             strings.TrimSpace(item.Type),
+			Section:          strings.TrimSpace(item.Attributes.Section),
+			Position:         item.Attributes.Position,
+			IsMandatory:      item.Attributes.IsMandatory,
+			HelicopterID:     strings.TrimSpace(item.Attributes.HelicopterID),
+			UploadIntentUUID: strings.TrimSpace(item.Attributes.UploadIntentUUID),
+			FileName:         strings.TrimSpace(item.Attributes.FileName),
+			FolderUUID:       item.Attributes.FolderUUID,
+		}
+	}
+
+	if h.fileManager != nil {
+		rootCache := make(map[string][]byte)
+		for i := range inputs {
+			if inputs[i].FolderUUID != nil {
+				continue
+			}
+			rootKey := "root"
+			rootID, ok := rootCache[rootKey]
+			if !ok {
+				root, rootErr := h.fileManager.GetOrCreateSystemRootFolder(c.UserContext())
+				if rootErr != nil || root == nil || len(root.ID) != 16 {
+					continue
+				}
+				rootID = append([]byte(nil), root.ID...)
+				rootCache[rootKey] = rootID
+			}
+			folderStr, strErr := uuidv7.BytesToString(rootID)
+			if strErr != nil {
+				continue
+			}
+			inputs[i].FolderUUID = &folderStr
+		}
+	}
+
+	results := h.svc.CreateFromUploadIntentsBulk(c.UserContext(), inputs, actorUserID(c))
+	items := make([]responsedto.HelicopterFileCreateBulkItem, len(results))
+	for i := range results {
+		result := results[i]
+		if result.Success && result.Row != nil {
+			if err := h.validateStoredHelicopterFileContent(c.UserContext(), result.Row.SourceFile); err != nil {
+				// Reject corrupt uploads: drop the helicopter file row we just created and
+				// report the item as failed. The now-unreferenced file is reclaimed by GC.
+				_ = h.svc.Delete(c.UserContext(), result.Row.ID)
+				items[i] = helicopterFileCreateBulkErrorItem(
+					result.Index,
+					fiber.StatusUnprocessableEntity,
+					"Validation error",
+					"uploaded file content is corrupt or unsupported",
+				)
+				continue
+			}
+			h.publishHelicopterFileCreated(actorUserID(c), result.Row, result.Row.SourceFile)
+			res := helicopterFileResource(c.UserContext(), h.storage, result.Row)
+			items[i] = responsedto.HelicopterFileCreateBulkItem{
+				Index:    result.Index,
+				Success:  true,
+				Resource: &res,
+			}
+			continue
+		}
+
+		errStatus := fiber.StatusInternalServerError
+		errTitle := "Internal error"
+		errDetail := "missing item error"
+		if result.Error != nil {
+			errStatus = result.Error.Status
+			errTitle = result.Error.Title
+			errDetail = result.Error.Detail
+		}
+		items[i] = helicopterFileCreateBulkErrorItem(result.Index, errStatus, errTitle, errDetail)
+	}
+
+	return writeHelicopterFileCreateBulkResponse(c, items)
+}
+
+// UpdateHelicopterFile godoc
+// @Summary Update helicopter file
+// @Description Update a helicopter file template record.
+// @Description Section allowed values: `bfi` (Before First Flight Inspection), `fpwb` (Flight Preparation and WB), `afi` (After Last Flight Inspection).
+// @Description Optional attributes: `section`, `position`, `is_required`, `helicopter_id`, `file_name`.
+// @Tags Helicopter - Master File
+// @Accept json
+// @Produce json
+// @Param request body requestdto.HelicopterFileUpdateBulkRequest true "JSON:API helicopter file update request (single object or bulk array)"
+// @Success 200 {object} responsedto.HelicopterFileResponse
+// @Success 207 {object} responsedto.HelicopterFileUpdateBulkResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/helicopter-files/update [patch]
+func (h *HelicopterFileHandler) Update(c *fiber.Ctx) error {
+	isBulk, err := isJSONAPIDataArrayPayload(c.Body())
+	if err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if isBulk {
+		return h.updateBulk(c)
+	}
+
+	var req requestdto.HelicopterFileUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	resource, errItem := h.updateOne(c, req.Data)
+	if errItem != nil {
+		return writeHelicopterFileErrors(c, errItem.Status, []jsonapi.ErrorObject{{
+			Status: strconv.Itoa(errItem.Status),
+			Title:  errItem.Title,
+			Detail: errItem.Detail,
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, *resource)
+}
+
+func (h *HelicopterFileHandler) updateBulk(c *fiber.Ctx) error {
+	var req requestdto.HelicopterFileUpdateBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if len(req.Data) == 0 {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "data must contain at least one item",
+			Source: &jsonapi.ErrorSource{Pointer: "/data"},
+		}})
+	}
+	if len(req.Data) > helicopterFileBulkMaxItems {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "too many items in one request",
+			Source: &jsonapi.ErrorSource{Pointer: "/data"},
+		}})
+	}
+
+	items := make([]responsedto.HelicopterFileUpdateBulkItem, len(req.Data))
+	for i := range req.Data {
+		itemReq := requestdto.HelicopterFileUpdateRequest{Data: req.Data[i]}
+		if errs := h.validate.ValidateStruct(itemReq); errs != nil {
+			detail := "invalid request item"
+			if len(errs) > 0 && strings.TrimSpace(errs[0].Detail) != "" {
+				detail = errs[0].Detail
+			}
+			items[i] = helicopterFileUpdateBulkErrorItem(i, fiber.StatusUnprocessableEntity, "Validation error", detail)
+			continue
+		}
+
+		resource, errItem := h.updateOne(c, req.Data[i])
+		if errItem != nil {
+			items[i] = helicopterFileUpdateBulkErrorItem(i, errItem.Status, errItem.Title, errItem.Detail)
+			continue
+		}
+
+		items[i] = responsedto.HelicopterFileUpdateBulkItem{
+			Index:    i,
+			Success:  true,
+			Resource: resource,
+		}
+	}
+
+	return writeHelicopterFileUpdateBulkResponse(c, items)
+}
+
+func (h *HelicopterFileHandler) updateOne(c *fiber.Ctx, data requestdto.HelicopterFileUpdateData) (*jsonapi.Resource, *responsedto.HelicopterFileBulkError) {
+	id, err := uuidv7.ParseString(strings.TrimSpace(data.ID))
+	if err != nil {
+		return nil, helicopterFileBulkErrorFromDef(fiber.StatusUnprocessableEntity, "Validation error", "id is invalid UUID")
+	}
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return nil, helicopterFileBulkErrorFromError("Get failed", err)
+	}
+	if existing == nil {
+		return nil, helicopterFileBulkErrorFromDef(fiber.StatusNotFound, "Not found", "helicopter file not found")
+	}
+	prevAttachmentID := append([]byte(nil), existing.FileAttachmentID...)
+
+	if data.Attributes.Section != nil {
+		section := strings.TrimSpace(*data.Attributes.Section)
+		if !isValidHelicopterFileSection(section) {
+			return nil, helicopterFileBulkErrorFromDef(fiber.StatusUnprocessableEntity, "Validation error", "section is invalid")
+		}
+		existing.Section = section
+	}
+	if data.Attributes.Position != nil {
+		existing.Position = *data.Attributes.Position
+	}
+	if data.Attributes.IsMandatory != nil {
+		existing.IsMandatory = *data.Attributes.IsMandatory
+	}
+
+	helicopterIDRaw := strings.TrimSpace(optionalStringValue(data.Attributes.HelicopterID))
+	if helicopterIDRaw != "" {
+		helicopterID, parseErr := uuidv7.ParseString(helicopterIDRaw)
+		if parseErr != nil {
+			return nil, helicopterFileBulkErrorFromDef(fiber.StatusUnprocessableEntity, "Validation error", "helicopter_id is invalid UUID")
+		}
+		exists, existsErr := h.svc.HelicopterExists(c.UserContext(), helicopterID)
+		if existsErr != nil {
+			return nil, helicopterFileBulkErrorFromError("Update failed", existsErr)
+		}
+		if !exists {
+			return nil, helicopterFileBulkErrorFromDef(fiber.StatusUnprocessableEntity, "Validation error", "helicopter_id not found")
+		}
+		existing.HelicopterID = helicopterID
+	}
+
+	if data.Attributes.FileName != nil {
+		fileName := strings.TrimSpace(*data.Attributes.FileName)
+		if fileName == "" {
+			return nil, helicopterFileBulkErrorFromDef(fiber.StatusUnprocessableEntity, "Validation error", "file_name is required")
+		}
+		if h.fileManager == nil {
+			return nil, helicopterFileBulkErrorFromDef(fiber.StatusBadRequest, "Update failed", "file manager service is not configured")
+		}
+		fileID := append([]byte(nil), existing.SourceFileID...)
+		if len(fileID) != 16 {
+			attachment, attachmentErr := h.fileManager.GetAttachmentByID(c.UserContext(), existing.FileAttachmentID)
+			if attachmentErr != nil {
+				return nil, helicopterFileBulkErrorFromError("Update failed", attachmentErr)
+			}
+			if attachment == nil || len(attachment.FileID) == 0 {
+				return nil, helicopterFileBulkErrorFromDef(fiber.StatusNotFound, "Not found", "file attachment not found")
+			}
+			fileID = attachment.FileID
+		}
+		if _, moveErr := h.fileManager.MoveFileNode(c.UserContext(), fileID, filemanager.MoveFileParams{
+			Name:    &fileName,
+			ActorID: actorUserID(c),
+		}); moveErr != nil {
+			return nil, helicopterFileBulkErrorFromError("Update failed", moveErr)
+		}
+	}
+
+	existing.UpdatedBy = actorUserID(c)
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return nil, helicopterFileBulkErrorFromError("Update failed", err)
+	}
+	if err := syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, prevAttachmentID, existing.FileAttachmentID, actorUserID(c)); err != nil {
+		return nil, helicopterFileBulkErrorFromError("Update failed", err)
+	}
+
+	updatedRow, getErr := h.svc.GetByID(c.UserContext(), existing.ID)
+	if getErr == nil && updatedRow != nil {
+		res := helicopterFileResource(c.UserContext(), h.storage, updatedRow)
+		return &res, nil
+	}
+
+	res := helicopterFileResource(c.UserContext(), h.storage, existing)
+	return &res, nil
+}
+
+func helicopterFileBulkErrorFromDef(status int, title, detail string) *responsedto.HelicopterFileBulkError {
+	def := inferHelicopterFileDef(status, title, detail)
+	return &responsedto.HelicopterFileBulkError{
+		Status:    status,
+		Code:      def.Code,
+		ErrorCode: def.ErrorCode,
+		Title:     def.Title,
+		Detail:    def.Message,
+	}
+}
+
+func helicopterFileBulkErrorFromError(title string, err error) *responsedto.HelicopterFileBulkError {
+	def := inferHelicopterFileDef(fiber.StatusBadRequest, title, "")
+	if errors.Is(err, filemanager.ErrFileNotFound) {
+		def = inferHelicopterFileDef(fiber.StatusNotFound, title, "not found")
+	}
+	if errors.Is(err, filemanager.ErrDuplicateName) {
+		def = inferHelicopterFileDef(fiber.StatusUnprocessableEntity, "Validation error", "duplicate name")
+	}
+	return &responsedto.HelicopterFileBulkError{
+		Status:    def.Status,
+		Code:      def.Code,
+		ErrorCode: def.ErrorCode,
+		Title:     def.Title,
+		Detail:    def.Message,
+	}
+}
+
+// GetHelicopterFile godoc
+// @Summary Get helicopter files by helicopter ID
+// @Description Return helicopter file template collection for selected helicopter
+// @Tags Helicopter - Master File
+// @Produce json
+// @Param helicopter_id path string true "Helicopter ID"
+// @Success 200 {object} responsedto.HelicopterFileCollectionResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/helicopter-files/get/{helicopter_id} [get]
+func (h *HelicopterFileHandler) Get(c *fiber.Ctx) error {
+	helicopterID := strings.TrimSpace(c.Params("helicopter_id"))
+	id, err := uuidv7.ParseString(helicopterID)
+	if err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "helicopter_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/helicopter_id"},
+		}})
+	}
+
+	exists, err := h.svc.HelicopterExists(c.UserContext(), id)
+	if err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if !exists {
+		return writeHelicopterFileErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "helicopter not found",
+		}})
+	}
+
+	rows, err := h.svc.ListByHelicopter(c.UserContext(), id)
+	if err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	rows = h.filterVisibleHelicopterFileRows(c.UserContext(), actorUserID(c), rows)
+
+	groupedFiles := responsedto.HelicopterFileCollectionSections{
+		Before:  make([]responsedto.HelicopterFileCollectionItem, 0),
+		Prepare: make([]responsedto.HelicopterFileCollectionItem, 0),
+		After:   make([]responsedto.HelicopterFileCollectionItem, 0),
+	}
+	for i := range rows {
+		item := helicopterFileCollectionItem(c.UserContext(), h.storage, &rows[i])
+		switch strings.TrimSpace(rows[i].Section) {
+		case helicopterfile.SectionBeforeFirstFlightInspection:
+			groupedFiles.Before = append(groupedFiles.Before, item)
+		case helicopterfile.SectionFlightPreparationAndWB:
+			groupedFiles.Prepare = append(groupedFiles.Prepare, item)
+		case helicopterfile.SectionAfterLastFlightInspection:
+			groupedFiles.After = append(groupedFiles.After, item)
+		}
+	}
+
+	helicopterSummary := responsedto.HelicopterFileCollectionHelicopter{
+		ID: idString(id),
+	}
+	if len(rows) > 0 && rows[0].Helicopter != nil {
+		helicopterSummary.Name = strings.TrimSpace(rows[0].Helicopter.Designation)
+	} else if h.helicopter != nil {
+		if helicopterRow, heliErr := h.helicopter.GetByID(c.UserContext(), id); heliErr == nil && helicopterRow != nil {
+			helicopterSummary.Name = strings.TrimSpace(helicopterRow.Designation)
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, responsedto.HelicopterFileCollectionResponse{
+		Type: "helicopter_file_collection",
+		Attributes: responsedto.HelicopterFileCollectionAttributes{
+			Helicopter: helicopterSummary,
+			Files:      groupedFiles,
+		},
+	})
+}
+
+// ListHelicopterFiles godoc
+// @Summary List helicopter files
+// @Description List helicopter file template records grouped by helicopter.
+// @Description Pagination is applied per helicopter group (not per file row), so one helicopter's files stay in the same page.
+// @Tags Helicopter - Master File
+// @Produce json
+// @Param filter[search] query string false "Search text"
+// @Param search query string false "Search text (fallback)"
+// @Param sort query string false "Sort field"
+// @Param page[number] query int false "Page number"
+// @Param page[size] query int false "Page size"
+// @Param page query int false "Page number (fallback)"
+// @Param size query int false "Page size (fallback)"
+// @Success 200 {object} responsedto.HelicopterFileCollectionListResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/helicopter-files/get-all [get]
+func (h *HelicopterFileHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("search")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	sort := c.Query("sort")
+
+	allRows, _, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	allRows = h.filterVisibleHelicopterFileRows(c.UserContext(), actorUserID(c), allRows)
+
+	grouped := make([]responsedto.HelicopterFileCollectionResponse, 0)
+	indexByHelicopterID := make(map[string]int)
+	for i := range allRows {
+		helicopterID := idString(allRows[i].HelicopterID)
+		idx, ok := indexByHelicopterID[helicopterID]
+		if !ok {
+			helicopterName := ""
+			if allRows[i].Helicopter != nil {
+				helicopterName = strings.TrimSpace(allRows[i].Helicopter.Designation)
+			}
+			grouped = append(grouped, responsedto.HelicopterFileCollectionResponse{
+				Type: "helicopter_file_collection",
+				Attributes: responsedto.HelicopterFileCollectionAttributes{
+					Helicopter: responsedto.HelicopterFileCollectionHelicopter{
+						ID:   helicopterID,
+						Name: helicopterName,
+					},
+					Files: responsedto.HelicopterFileCollectionSections{
+						Before:  make([]responsedto.HelicopterFileCollectionItem, 0),
+						Prepare: make([]responsedto.HelicopterFileCollectionItem, 0),
+						After:   make([]responsedto.HelicopterFileCollectionItem, 0),
+					},
+				},
+			})
+			idx = len(grouped) - 1
+			indexByHelicopterID[helicopterID] = idx
+		}
+
+		item := helicopterFileCollectionItem(c.UserContext(), h.storage, &allRows[i])
+		switch strings.TrimSpace(allRows[i].Section) {
+		case helicopterfile.SectionBeforeFirstFlightInspection:
+			grouped[idx].Attributes.Files.Before = append(grouped[idx].Attributes.Files.Before, item)
+		case helicopterfile.SectionFlightPreparationAndWB:
+			grouped[idx].Attributes.Files.Prepare = append(grouped[idx].Attributes.Files.Prepare, item)
+		case helicopterfile.SectionAfterLastFlightInspection:
+			grouped[idx].Attributes.Files.After = append(grouped[idx].Attributes.Files.After, item)
+		}
+	}
+
+	totalGroups := len(grouped)
+	start := (pageNumber - 1) * pageSize
+	if start > totalGroups {
+		start = totalGroups
+	}
+	end := start + pageSize
+	if end > totalGroups {
+		end = totalGroups
+	}
+	paged := make([]responsedto.HelicopterFileCollectionResponse, 0)
+	if start < end {
+		paged = grouped[start:end]
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, paged, map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       totalGroups,
+	})
+}
+
+// DeleteHelicopterFile godoc
+// @Summary Delete helicopter file
+// @Description Delete helicopter file template record
+// @Tags Helicopter - Master File
+// @Accept json
+// @Produce json
+// @Param request body requestdto.HelicopterFileDeleteRequest true "JSON:API helicopter file delete request"
+// @Success 200 {object} responsedto.HelicopterFileDeleteResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/helicopter-files/delete [delete]
+func (h *HelicopterFileHandler) Delete(c *fiber.Ctx) error {
+	var req requestdto.HelicopterFileDeleteRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	id, err := uuidv7.ParseString(strings.TrimSpace(req.Data.ID))
+	if err != nil {
+		return writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	existing, _ := h.svc.GetByID(c.UserContext(), id)
+	var prevAttachmentID []byte
+	var prevSourceFileID []byte
+	if existing != nil {
+		prevAttachmentID = append([]byte(nil), existing.FileAttachmentID...)
+		prevSourceFileID = append([]byte(nil), existing.SourceFileID...)
+	}
+	if err := h.svc.Delete(c.UserContext(), id); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeHelicopterFileErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "helicopter file not found",
+			}})
+		}
+		return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if len(prevAttachmentID) == 16 {
+		if err := syncAttachmentLifecycleClear(c.UserContext(), h.fileManager, prevAttachmentID, actorUserID(c)); err != nil {
+			return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Delete failed",
+				Detail: safeInternalDetail(),
+			}})
+		}
+	}
+	if len(prevAttachmentID) != 16 && len(prevSourceFileID) == 16 {
+		if err := syncFileLifecycleSwap(c.UserContext(), h.fileManager, prevSourceFileID, nil, actorUserID(c)); err != nil {
+			return writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Delete failed",
+				Detail: safeInternalDetail(),
+			}})
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "helicopter_file_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+func helicopterFileResource(
+	ctx context.Context,
+	storage fileManagerDownloadURLStorage,
+	row *helicopterfile.HelicopterFile,
+) jsonapi.Resource {
+	return jsonapi.Resource{
+		Type:       "helicopter_file",
+		ID:         idString(row.ID),
+		Attributes: helicopterFileItemAttributesMap(ctx, storage, row),
+	}
+}
+
+func (h *HelicopterFileHandler) publishHelicopterFileCreated(actorID []byte, row *helicopterfile.HelicopterFile, sourceFile *filemanager.File) {
+	if h == nil || h.helicopterFileEvents == nil || row == nil || len(actorID) != 16 || len(row.ID) != 16 || len(row.HelicopterID) != 16 {
+		return
+	}
+	if sourceFile == nil {
+		sourceFile = row.SourceFile
+	}
+	if sourceFile == nil {
+		return
+	}
+
+	actorUUID, err := uuidv7.BytesToString(actorID)
+	if err != nil || strings.TrimSpace(actorUUID) == "" {
+		return
+	}
+	helicopterUUID, err := uuidv7.BytesToString(row.HelicopterID)
+	if err != nil || strings.TrimSpace(helicopterUUID) == "" {
+		return
+	}
+	updatedAt := row.UpdatedAt.UTC()
+	if updatedAt.IsZero() {
+		updatedAt = time.Now().UTC()
+	}
+
+	event := helicopterfilerealtime.Event{
+		EventType:         helicopterfilerealtime.DefaultEventType,
+		HelicopterID:      helicopterUUID,
+		HelicopterFileID:  idString(row.ID),
+		FileID:            idString(row.SourceFileID),
+		Section:           strings.TrimSpace(row.Section),
+		Name:              strings.TrimSpace(sourceFile.Name),
+		MimeType:          strings.TrimSpace(sourceFile.MimeType),
+		AttachmentPending: row != nil && len(row.FileAttachmentID) != 16 && len(row.SourceFileID) == 16,
+		Position:          row.Position,
+		IsMandatory:       row.IsMandatory,
+		UpdatedAt:         updatedAt.Format(time.RFC3339),
+	}
+	h.helicopterFileEvents.PublishToUsers([]string{actorUUID}, event)
+}
+
+func helicopterFileItemAttributesMap(
+	ctx context.Context,
+	storage fileManagerDownloadURLStorage,
+	row *helicopterfile.HelicopterFile,
+) map[string]any {
+	fileName := ""
+	downloadURL := ""
+	helicopterName := ""
+	if row != nil && row.Helicopter != nil {
+		helicopterName = strings.TrimSpace(row.Helicopter.Designation)
+	}
+	if row != nil && row.FileAttachment != nil && row.FileAttachment.File != nil {
+		fileName = strings.TrimSpace(row.FileAttachment.File.Name)
+		downloadURL = strings.TrimSpace(resolveFileManagerDownloadURL(ctx, storage, row.FileAttachment.File))
+	}
+	attachmentPending := row != nil && len(row.FileAttachmentID) != 16 && len(row.SourceFileID) == 16
+	isTemplate := helicopterFileIsTemplate(row)
+	attachmentID := idString(row.FileAttachmentID)
+	if attachmentPending {
+		attachmentID = idString(row.SourceFileID)
+		if fileName == "" && row.SourceFile != nil {
+			fileName = strings.TrimSpace(row.SourceFile.Name)
+		}
+	}
+
+	return map[string]any{
+		"section":      strings.TrimSpace(row.Section),
+		"position":     row.Position,
+		"is_mandatory": row.IsMandatory,
+		"is_template":  isTemplate,
+		"helicopter": map[string]any{
+			"id":   idString(row.HelicopterID),
+			"name": helicopterName,
+		},
+		"attachment_pending": attachmentPending,
+		"attachment": map[string]any{
+			"id":           attachmentID,
+			"file_name":    fileName,
+			"download_url": downloadURL,
+		},
+		"created_at": row.CreatedAt.UTC().Format(time.RFC3339),
+		"created_by": uuidStringOrEmpty(row.CreatedBy),
+		"updated_at": row.UpdatedAt.UTC().Format(time.RFC3339),
+		"updated_by": uuidStringOrEmpty(row.UpdatedBy),
+	}
+}
+
+func (h *HelicopterFileHandler) filterVisibleHelicopterFileRows(ctx context.Context, actorID []byte, rows []helicopterfile.HelicopterFile) []helicopterfile.HelicopterFile {
+	if len(rows) == 0 {
+		return rows
+	}
+	filtered := make([]helicopterfile.HelicopterFile, 0, len(rows))
+	for i := range rows {
+		// Documents created from a template (e.g. via /files/create-from-template) are
+		// persisted as helicopter_files rows for takeover/WOPI use, but must not surface
+		// in the helicopter files listing.
+		if helicopterFileCreatedFromTemplate(&rows[i]) {
+			continue
+		}
+		if h.canViewHelicopterFileRow(ctx, actorID, &rows[i]) {
+			filtered = append(filtered, rows[i])
+		}
+	}
+	return filtered
+}
+
+func (h *HelicopterFileHandler) canViewHelicopterFileRow(ctx context.Context, actorID []byte, row *helicopterfile.HelicopterFile) bool {
+	if row == nil {
+		return false
+	}
+	takeoverID := helicopterFileTakeoverID(row)
+	if len(takeoverID) != 16 {
+		return true
+	}
+	if h == nil || h.takeover == nil || len(actorID) != 16 {
+		return false
+	}
+	takeoverRow, err := h.takeover.GetByID(ctx, takeoverID)
+	if err != nil || takeoverRow == nil {
+		return false
+	}
+	return takeoverHasUserAccess(takeoverRow, actorID)
+}
+
+func helicopterFileTakeoverID(row *helicopterfile.HelicopterFile) []byte {
+	if row == nil {
+		return nil
+	}
+	if row.SourceFile != nil && len(row.SourceFile.TakeoverID) == 16 {
+		return row.SourceFile.TakeoverID
+	}
+	if row.FileAttachment != nil && row.FileAttachment.File != nil && len(row.FileAttachment.File.TakeoverID) == 16 {
+		return row.FileAttachment.File.TakeoverID
+	}
+	return nil
+}
+
+func helicopterFileCollectionItem(
+	ctx context.Context,
+	storage fileManagerDownloadURLStorage,
+	row *helicopterfile.HelicopterFile,
+) responsedto.HelicopterFileCollectionItem {
+	fileName := ""
+	downloadURL := ""
+	if row != nil && row.FileAttachment != nil && row.FileAttachment.File != nil {
+		fileName = strings.TrimSpace(row.FileAttachment.File.Name)
+		downloadURL = strings.TrimSpace(resolveFileManagerDownloadURL(ctx, storage, row.FileAttachment.File))
+	}
+	attachmentPending := row != nil && len(row.FileAttachmentID) != 16 && len(row.SourceFileID) == 16
+	isTemplate := helicopterFileIsTemplate(row)
+	attachmentID := idString(row.FileAttachmentID)
+	if attachmentPending {
+		attachmentID = idString(row.SourceFileID)
+		if fileName == "" && row.SourceFile != nil {
+			fileName = strings.TrimSpace(row.SourceFile.Name)
+		}
+	}
+	return responsedto.HelicopterFileCollectionItem{
+		HelicopterFileID:  idString(row.ID),
+		Section:           strings.TrimSpace(row.Section),
+		Position:          row.Position,
+		IsMandatory:       row.IsMandatory,
+		IsTemplate:        isTemplate,
+		AttachmentPending: attachmentPending,
+		Attachment: responsedto.HelicopterFileCollectionAttachment{
+			ID:          attachmentID,
+			FileName:    fileName,
+			DownloadURL: downloadURL,
+		},
+		CreatedAt: row.CreatedAt.UTC().Format(time.RFC3339),
+		CreatedBy: uuidStringOrEmpty(row.CreatedBy),
+		UpdatedAt: row.UpdatedAt.UTC().Format(time.RFC3339),
+		UpdatedBy: uuidStringOrEmpty(row.UpdatedBy),
+	}
+}
+
+func helicopterFileIsTemplate(row *helicopterfile.HelicopterFile) bool {
+	if row == nil {
+		return false
+	}
+	if row.SourceFile != nil {
+		return row.SourceFile.IsTemplate
+	}
+	if row.FileAttachment != nil && row.FileAttachment.File != nil {
+		return row.FileAttachment.File.IsTemplate
+	}
+	return false
+}
+
+// helicopterFileCreatedFromTemplate reports whether the row points to a document
+// instantiated from a template via the WOPI create-from-template flow (identified by
+// a non-empty template_uuid on the underlying file). These rows stay in the database
+// for takeover/WOPI use but are excluded from the helicopter files listing, which only
+// surfaces templates and regular files — not template-derived working copies.
+// officeEditableExtensions are the file types Collabora edits and whose byte-level
+// integrity must hold before they can be registered as templates.
+var officeEditableExtensions = map[string]struct{}{
+	"docx": {}, "xlsx": {}, "pptx": {}, "odt": {}, "ods": {}, "odp": {},
+	"doc": {}, "xls": {}, "ppt": {}, "rtf": {},
+}
+
+// validateStoredHelicopterFileContent rejects office documents whose stored bytes are
+// corrupt or incomplete, so they can never be registered as templates and later surface
+// as corrupt Collabora sessions on create-from-template. Non-office files pass through.
+func (h *HelicopterFileHandler) validateStoredHelicopterFileContent(ctx context.Context, file *filemanager.File) error {
+	if file == nil {
+		return nil
+	}
+	ext := strings.ToLower(strings.TrimPrefix(filepath.Ext(strings.TrimSpace(file.Name)), "."))
+	if ext == "" {
+		ext = strings.ToLower(strings.TrimPrefix(filepath.Ext(strings.TrimSpace(file.ObjectKey)), "."))
+	}
+	if _, ok := officeEditableExtensions[ext]; !ok {
+		return nil
+	}
+	storage, ok := any(h.storage).(templateCopyStorage)
+	if !ok {
+		return nil
+	}
+
+	body, meta, err := storage.GetObject(ctx, file.ObjectKey)
+	if err != nil {
+		return err
+	}
+	defer body.Close()
+
+	payload, err := io.ReadAll(body)
+	if err != nil {
+		return err
+	}
+
+	declaredMime := firstNonEmpty(meta.ContentType, file.MimeType)
+	if ext == "xlsx" {
+		if sanitizeStorage, ok := any(h.storage).(xlsxSanitizerStorage); ok {
+			sanitizedPayload, _, changed, err := sanitizeXLSXPayload(payload)
+			if err != nil {
+				return err
+			}
+			if changed {
+				contentType := strings.TrimSpace(firstNonEmpty(declaredMime, canonicalOfficeContentType(file.Name)))
+				if contentType == "" {
+					contentType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+				}
+				newMeta, err := sanitizeStorage.PutObject(ctx, filemanager.PutObjectInput{
+					ObjectKey:   file.ObjectKey,
+					ContentType: contentType,
+					SizeBytes:   int64(len(sanitizedPayload)),
+					Body:        bytes.NewReader(sanitizedPayload),
+				})
+				if err != nil {
+					return err
+				}
+
+				file.SizeBytes = int64(len(sanitizedPayload))
+				file.MimeType = contentType
+				if strings.TrimSpace(newMeta.Bucket) != "" {
+					file.Bucket = newMeta.Bucket
+				}
+				if strings.TrimSpace(newMeta.ObjectKey) != "" {
+					file.ObjectKey = newMeta.ObjectKey
+				}
+				if strings.TrimSpace(newMeta.ETag) != "" {
+					file.ETag = newMeta.ETag
+				}
+				if strings.TrimSpace(newMeta.VersionID) != "" {
+					file.ObjectVersion = newMeta.VersionID
+				}
+				if updater := h.fileManager; updater != nil {
+					if err := updater.UpdateFile(ctx, file); err != nil {
+						return err
+					}
+				}
+			}
+			payload = sanitizedPayload
+		}
+	}
+
+	if err := validateOfficeContentSample(ext, declaredMime, payload); err != nil {
+		return err
+	}
+	switch ext {
+	case "docx", "xlsx", "pptx", "odt", "ods", "odp":
+		return validateOfficeZipStructure(ext, payload)
+	default:
+		return nil
+	}
+}
+
+func helicopterFileCreatedFromTemplate(row *helicopterfile.HelicopterFile) bool {
+	if row == nil {
+		return false
+	}
+	if row.SourceFile != nil {
+		return len(row.SourceFile.TemplateUUID) == 16
+	}
+	if row.FileAttachment != nil && row.FileAttachment.File != nil {
+		return len(row.FileAttachment.File.TemplateUUID) == 16
+	}
+	return false
+}
+
+func writeHelicopterFileErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferHelicopterFileDef(status, e.Title, e.Detail)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		if strings.TrimSpace(e.Title) == "" {
+			e.Title = def.Title
+		}
+		e.Detail = def.Message
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferHelicopterFileDef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.ErrHelicopterFileNotFound
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "invalid uuid"):
+			return apperrorsx.ErrHelicopterFileInvalidUUID
+		case strings.Contains(lowerDetail, "section is invalid"):
+			return apperrorsx.ErrHelicopterFileSectionInvalid
+		case strings.Contains(lowerDetail, "file_name is required"):
+			return apperrorsx.ErrHelicopterFileFileNameRequired
+		default:
+			return apperrorsx.ErrHelicopterFileInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrHelicopterFileInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"), strings.Contains(lowerTitle, "upload"), strings.Contains(lowerTitle, "cancel upload"):
+			return apperrorsx.ErrHelicopterFileCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrHelicopterFileUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrHelicopterFileDeleteFailed
+		case strings.Contains(lowerTitle, "get failed"):
+			return apperrorsx.ErrHelicopterFileGetFailed
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.ErrHelicopterFileListFailed
+		default:
+			if strings.Contains(lowerDetail, "get failed") {
+				return apperrorsx.ErrHelicopterFileGetFailed
+			}
+			return apperrorsx.ErrHelicopterFileInvalidPayload
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
+
+func inferHelicopterFileCode(status int, title, detail string) (string, string) {
+	def := inferHelicopterFileDef(status, title, detail)
+	return def.Code, def.ErrorCode
+}
+
+func writeHelicopterFileBadRequestError(c *fiber.Ctx, title, detail string) {
+	_ = writeHelicopterFileErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+		Status: "400",
+		Title:  title,
+		Detail: detail,
+	}})
+}
+
+func writeHelicopterFileValidationError(c *fiber.Ctx, detail, pointer string) {
+	_ = writeHelicopterFileErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+		Status: "422",
+		Title:  "Validation error",
+		Detail: detail,
+		Source: &jsonapi.ErrorSource{
+			Pointer: pointer,
+		},
+	}})
+}
+
+func isValidHelicopterFileSection(section string) bool {
+	switch strings.TrimSpace(section) {
+	case helicopterfile.SectionBeforeFirstFlightInspection,
+		helicopterfile.SectionFlightPreparationAndWB,
+		helicopterfile.SectionAfterLastFlightInspection:
+		return true
+	default:
+		return false
+	}
+}
+
+func optionalStringValue(v *string) string {
+	if v == nil {
+		return ""
+	}
+	return *v
+}
+
+func helicopterFileUploadBulkErrorItem(index int, status int, title, detail string) responsedto.HelicopterFileUploadIntentBulkItem {
+	def := inferHelicopterFileDef(status, title, detail)
+	return responsedto.HelicopterFileUploadIntentBulkItem{
+		Index:   index,
+		Success: false,
+		Error: &responsedto.HelicopterFileBulkError{
+			Status:    status,
+			Code:      def.Code,
+			ErrorCode: def.ErrorCode,
+			Title:     def.Title,
+			Detail:    def.Message,
+		},
+	}
+}
+
+func helicopterFileCreateBulkErrorItem(index int, status int, title, detail string) responsedto.HelicopterFileCreateBulkItem {
+	def := inferHelicopterFileDef(status, title, detail)
+	return responsedto.HelicopterFileCreateBulkItem{
+		Index:   index,
+		Success: false,
+		Error: &responsedto.HelicopterFileBulkError{
+			Status:    status,
+			Code:      def.Code,
+			ErrorCode: def.ErrorCode,
+			Title:     def.Title,
+			Detail:    def.Message,
+		},
+	}
+}
+
+func helicopterFileUpdateBulkErrorItem(index int, status int, title, detail string) responsedto.HelicopterFileUpdateBulkItem {
+	def := inferHelicopterFileDef(status, title, detail)
+	return responsedto.HelicopterFileUpdateBulkItem{
+		Index:   index,
+		Success: false,
+		Error: &responsedto.HelicopterFileBulkError{
+			Status:    status,
+			Code:      def.Code,
+			ErrorCode: def.ErrorCode,
+			Title:     def.Title,
+			Detail:    def.Message,
+		},
+	}
+}
+
+func writeHelicopterFileUploadIntentBulkResponse(c *fiber.Ctx, items []responsedto.HelicopterFileUploadIntentBulkItem) error {
+	total := len(items)
+	success := 0
+	for i := range items {
+		if items[i].Success {
+			success++
+			items[i].Error = nil
+			continue
+		}
+		items[i].Resource = nil
+		if items[i].Error == nil {
+			def := inferHelicopterFileDef(fiber.StatusInternalServerError, "Internal error", "missing item error")
+			items[i].Error = &responsedto.HelicopterFileBulkError{
+				Status:    fiber.StatusInternalServerError,
+				Code:      def.Code,
+				ErrorCode: def.ErrorCode,
+				Title:     def.Title,
+				Detail:    def.Message,
+			}
+		}
+	}
+	failed := total - success
+
+	meta := map[string]any{
+		"total":           total,
+		"success":         success,
+		"failed":          failed,
+		"partial_success": success > 0 && failed > 0,
+	}
+
+	var statusCode int
+	if failed == 0 {
+		statusCode = fiber.StatusCreated
+	} else if success > 0 {
+		statusCode = fiber.StatusMultiStatus
+	} else {
+		statusCode = fiber.StatusUnprocessableEntity
+		for i := range items {
+			if items[i].Error != nil && items[i].Error.Status >= 400 {
+				statusCode = items[i].Error.Status
+				break
+			}
+		}
+	}
+
+	return response.WriteWithMeta(c, statusCode, items, meta)
+}
+
+func writeHelicopterFileCreateBulkResponse(c *fiber.Ctx, items []responsedto.HelicopterFileCreateBulkItem) error {
+	total := len(items)
+	success := 0
+	for i := range items {
+		if items[i].Success {
+			success++
+			items[i].Error = nil
+			continue
+		}
+		items[i].Resource = nil
+		if items[i].Error == nil {
+			def := inferHelicopterFileDef(fiber.StatusInternalServerError, "Internal error", "missing item error")
+			items[i].Error = &responsedto.HelicopterFileBulkError{
+				Status:    fiber.StatusInternalServerError,
+				Code:      def.Code,
+				ErrorCode: def.ErrorCode,
+				Title:     def.Title,
+				Detail:    def.Message,
+			}
+		}
+	}
+	failed := total - success
+
+	meta := map[string]any{
+		"total":           total,
+		"success":         success,
+		"failed":          failed,
+		"partial_success": success > 0 && failed > 0,
+	}
+
+	var statusCode int
+	if failed == 0 {
+		statusCode = fiber.StatusCreated
+	} else if success > 0 {
+		statusCode = fiber.StatusMultiStatus
+	} else {
+		statusCode = fiber.StatusUnprocessableEntity
+		for i := range items {
+			if items[i].Error != nil && items[i].Error.Status >= 400 {
+				statusCode = items[i].Error.Status
+				break
+			}
+		}
+	}
+
+	return response.WriteWithMeta(c, statusCode, items, meta)
+}
+
+func helicopterSectionFolderName(section string) (string, bool) {
+	switch strings.TrimSpace(section) {
+	case helicopterfile.SectionBeforeFirstFlightInspection:
+		return "Before First Flight Inspection", true
+	case helicopterfile.SectionFlightPreparationAndWB:
+		return "Flight Preparation and W&B", true
+	case helicopterfile.SectionAfterLastFlightInspection:
+		return "After Last Flight Inspection", true
+	default:
+		return "", false
+	}
+}
+
+func (h *HelicopterFileHandler) ensureHelicopterSectionFolder(ctx context.Context, actorID, helicopterID []byte, section string) ([]byte, error) {
+	folderName, ok := helicopterSectionFolderName(section)
+	if !ok {
+		return nil, nil
+	}
+
+	heli, err := h.helicopter.GetByID(ctx, helicopterID)
+	if err != nil || heli == nil {
+		return nil, err
+	}
+
+	designation := strings.TrimSpace(heli.Designation)
+	if designation == "" {
+		return nil, nil
+	}
+
+	root, err := h.fileManager.GetOrCreateSystemRootFolder(ctx)
+	if err != nil || root == nil {
+		return nil, err
+	}
+
+	aircraftFolderID, err := h.ensureHelicopterFolderByParentAndName(ctx, root.ID, "aircraft", actorID)
+	if err != nil {
+		return nil, err
+	}
+
+	designationFolderID, err := h.ensureHelicopterFolderByParentAndName(ctx, aircraftFolderID, designation, actorID)
+	if err != nil {
+		return nil, err
+	}
+
+	return h.ensureHelicopterFolderByParentAndName(ctx, designationFolderID, folderName, actorID)
+}
+
+func (h *HelicopterFileHandler) ensureHelicopterFolderByParentAndName(ctx context.Context, parentID []byte, name string, actorID []byte) ([]byte, error) {
+	normalized := strings.ToLower(name)
+	existing, err := h.fileManager.GetFolderByParentAndName(ctx, parentID, normalized)
+	if err != nil {
+		return nil, err
+	}
+	if existing != nil {
+		return existing.ID, nil
+	}
+	created, err := h.fileManager.CreateFolderNode(ctx, filemanager.CreateFolderParams{
+		Name:     name,
+		ParentID: parentID,
+		ActorID:  actorID,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return created.ID, nil
+}
+
+func writeHelicopterFileUpdateBulkResponse(c *fiber.Ctx, items []responsedto.HelicopterFileUpdateBulkItem) error {
+	total := len(items)
+	success := 0
+	for i := range items {
+		if items[i].Success {
+			success++
+			items[i].Error = nil
+			continue
+		}
+		items[i].Resource = nil
+		if items[i].Error == nil {
+			def := inferHelicopterFileDef(fiber.StatusInternalServerError, "Internal error", "missing item error")
+			items[i].Error = &responsedto.HelicopterFileBulkError{
+				Status:    fiber.StatusInternalServerError,
+				Code:      def.Code,
+				ErrorCode: def.ErrorCode,
+				Title:     def.Title,
+				Detail:    def.Message,
+			}
+		}
+	}
+	failed := total - success
+
+	meta := map[string]any{
+		"total":           total,
+		"success":         success,
+		"failed":          failed,
+		"partial_success": success > 0 && failed > 0,
+	}
+
+	var statusCode int
+	if failed == 0 {
+		statusCode = fiber.StatusOK
+	} else if success > 0 {
+		statusCode = fiber.StatusMultiStatus
+	} else {
+		statusCode = fiber.StatusUnprocessableEntity
+		for i := range items {
+			if items[i].Error != nil && items[i].Error.Status >= 400 {
+				statusCode = items[i].Error.Status
+				break
+			}
+		}
+	}
+
+	return response.WriteWithMeta(c, statusCode, items, meta)
+}
diff --git a/internal/transport/http/handlers/helicopter_file_handler_test.go b/internal/transport/http/handlers/helicopter_file_handler_test.go
new file mode 100644
index 0000000..1109bab
--- /dev/null
+++ b/internal/transport/http/handlers/helicopter_file_handler_test.go
@@ -0,0 +1,1721 @@
+package handlers
+
+import (
+	"archive/zip"
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+	"unsafe"
+
+	"github.com/gofiber/fiber/v2"
+	"github.com/valyala/fasthttp"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/helicopter"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	takeoverdomain "wucher/internal/domain/takeover"
+	helicopterfilerealtime "wucher/internal/realtime/helicopterfile"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+	responsedto "wucher/internal/transport/http/dto/response"
+)
+
+type helicopterFileServiceMock struct {
+	createErr           error
+	createFn            func(context.Context, *helicopterfile.HelicopterFile) error
+	updateErr           error
+	deleteErr           error
+	getErr              error
+	listErr             error
+	helicopterExists    bool
+	helicopterExistsErr error
+	attachmentExists    bool
+
+	getRow     *helicopterfile.HelicopterFile
+	listRows   []helicopterfile.HelicopterFile
+	listTotal  int64
+	byHeliRows []helicopterfile.HelicopterFile
+	byHeliErr  error
+	uploadBulk []helicopterfile.UploadIntentBulkItemResult
+	createBulk []helicopterfile.CreateBulkItemResult
+}
+
+func (m *helicopterFileServiceMock) Create(ctx context.Context, row *helicopterfile.HelicopterFile) error {
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return m.createErr
+}
+
+func (m *helicopterFileServiceMock) Update(context.Context, *helicopterfile.HelicopterFile) error {
+	return m.updateErr
+}
+
+func (m *helicopterFileServiceMock) Delete(context.Context, []byte) error {
+	return m.deleteErr
+}
+
+func (m *helicopterFileServiceMock) GetByID(context.Context, []byte) (*helicopterfile.HelicopterFile, error) {
+	return m.getRow, m.getErr
+}
+
+func (m *helicopterFileServiceMock) List(context.Context, string, string, int, int) ([]helicopterfile.HelicopterFile, int64, error) {
+	return m.listRows, m.listTotal, m.listErr
+}
+
+func (m *helicopterFileServiceMock) ListByHelicopter(context.Context, []byte) ([]helicopterfile.HelicopterFile, error) {
+	return m.byHeliRows, m.byHeliErr
+}
+
+func (m *helicopterFileServiceMock) ListByHelicopterAndSection(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+	return nil, nil
+}
+
+func (m *helicopterFileServiceMock) HelicopterExists(context.Context, []byte) (bool, error) {
+	return m.helicopterExists, m.helicopterExistsErr
+}
+
+func (m *helicopterFileServiceMock) AttachmentExists(context.Context, []byte) (bool, error) {
+	return m.attachmentExists, nil
+}
+
+func (m *helicopterFileServiceMock) RequestUploadIntentsBulk(context.Context, []helicopterfile.UploadIntentBulkInput, []byte) []helicopterfile.UploadIntentBulkItemResult {
+	return m.uploadBulk
+}
+
+func (m *helicopterFileServiceMock) CreateFromUploadIntentsBulk(context.Context, []helicopterfile.CreateBulkInput, []byte) []helicopterfile.CreateBulkItemResult {
+	return m.createBulk
+}
+
+type helicopterServiceMock struct {
+	row *helicopter.Helicopter
+	err error
+}
+
+type helicopterFileTakeoverServiceMock struct {
+	row *takeoverdomain.TakeoverAc
+	err error
+}
+
+type helicopterFileEventsMock struct {
+	publishedUsers []string
+	event          *helicopterfilerealtime.Event
+	publishCalls   int
+}
+
+func (m *helicopterFileEventsMock) PublishToUsers(userUUIDs []string, event helicopterfilerealtime.Event) int {
+	m.publishCalls++
+	m.publishedUsers = append([]string(nil), userUUIDs...)
+	copied := event
+	m.event = &copied
+	return len(userUUIDs)
+}
+
+type helicopterFileManagerMock struct {
+	filemanager.Service
+	createFileFn        func(context.Context, filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error)
+	createAttachmentFn  func(context.Context, filemanager.CreateAttachmentParams) (*filemanager.Attachment, error)
+	listAttachmentRefFn func(context.Context, filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error)
+	getAttachmentByIDFn func(context.Context, []byte) (*filemanager.Attachment, error)
+	getRootFn           func(context.Context) (*filemanager.Folder, error)
+	getByFolderNameFn   func(context.Context, []byte, string) (*filemanager.File, error)
+	getFileByIDFn       func(context.Context, []byte) (*filemanager.File, error)
+	moveFileFn          func(context.Context, []byte, filemanager.MoveFileParams) (*filemanager.File, error)
+	updateFileFn        func(context.Context, *filemanager.File) error
+	markActiveErr       error
+	reconcileErr        error
+	lastCreateFile      *filemanager.CreateFileFromUploadIntentParams
+	updateFileCalls     int
+}
+
+func (m *helicopterFileManagerMock) CreateFileNodeFromUploadIntent(ctx context.Context, p filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+	copied := p
+	copied.UploadIntentID = append([]byte(nil), p.UploadIntentID...)
+	copied.FolderID = append([]byte(nil), p.FolderID...)
+	copied.ActorID = append([]byte(nil), p.ActorID...)
+	m.lastCreateFile = &copied
+	if m.createFileFn != nil {
+		return m.createFileFn(ctx, p)
+	}
+	return nil, nil
+}
+
+func (m *helicopterFileManagerMock) CreateAttachment(ctx context.Context, p filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+	if m.createAttachmentFn != nil {
+		return m.createAttachmentFn(ctx, p)
+	}
+	return nil, nil
+}
+
+func (m *helicopterFileManagerMock) ListAttachmentsByReference(ctx context.Context, p filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error) {
+	if m.listAttachmentRefFn != nil {
+		return m.listAttachmentRefFn(ctx, p)
+	}
+	return nil, 0, nil
+}
+
+func (m *helicopterFileManagerMock) GetAttachmentByID(ctx context.Context, id []byte) (*filemanager.Attachment, error) {
+	if m.getAttachmentByIDFn != nil {
+		return m.getAttachmentByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *helicopterFileManagerMock) GetOrCreateSystemRootFolder(ctx context.Context) (*filemanager.Folder, error) {
+	if m.getRootFn != nil {
+		return m.getRootFn(ctx)
+	}
+	return nil, nil
+}
+
+func (m *helicopterFileManagerMock) GetFileByFolderAndName(ctx context.Context, folderID []byte, name string) (*filemanager.File, error) {
+	if m.getByFolderNameFn != nil {
+		return m.getByFolderNameFn(ctx, folderID, name)
+	}
+	return nil, nil
+}
+
+func (m *helicopterFileManagerMock) GetFileByID(ctx context.Context, id []byte) (*filemanager.File, error) {
+	if m.getFileByIDFn != nil {
+		return m.getFileByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func (m *helicopterFileManagerMock) MoveFileNode(ctx context.Context, id []byte, p filemanager.MoveFileParams) (*filemanager.File, error) {
+	if m.moveFileFn != nil {
+		return m.moveFileFn(ctx, id, p)
+	}
+	return nil, nil
+}
+
+func (m *helicopterFileManagerMock) UpdateFile(ctx context.Context, row *filemanager.File) error {
+	m.updateFileCalls++
+	if m.updateFileFn != nil {
+		return m.updateFileFn(ctx, row)
+	}
+	return nil
+}
+
+func (m *helicopterFileManagerMock) MarkFileActive(context.Context, []byte, []byte) error {
+	return m.markActiveErr
+}
+
+func (m *helicopterFileManagerMock) ReconcileFileLifecycle(context.Context, []byte, []byte) error {
+	return m.reconcileErr
+}
+
+func (m *helicopterFileManagerMock) CleanupOrphanPendingFiles(context.Context, time.Time, time.Duration, int, bool) (filemanager.FileCleanupStats, error) {
+	return filemanager.FileCleanupStats{}, nil
+}
+
+func (m *helicopterServiceMock) Create(context.Context, *helicopter.Helicopter) error { return nil }
+func (m *helicopterServiceMock) Update(context.Context, *helicopter.Helicopter) error { return nil }
+func (m *helicopterServiceMock) ApplySortKeyPatch(*helicopter.Helicopter, helicopter.SortKeyPatch) {
+}
+func (m *helicopterServiceMock) Delete(context.Context, []byte) error { return nil }
+func (m *helicopterServiceMock) GetByID(context.Context, []byte) (*helicopter.Helicopter, error) {
+	return m.row, m.err
+}
+func (m *helicopterServiceMock) List(context.Context, string, []string, string, int, int, [][]byte) ([]helicopter.Helicopter, int64, error) {
+	return nil, 0, nil
+}
+func (m *helicopterServiceMock) NextReportNumber(context.Context, []byte) (string, int, error) {
+	return "", 0, nil
+}
+func (m *helicopterServiceMock) IsInUse(context.Context, []byte) (bool, error) {
+	return false, nil
+}
+func (m *helicopterServiceMock) InUseByAircraftIDs(context.Context, [][]byte) (map[string]bool, error) {
+	return map[string]bool{}, nil
+}
+func (m *helicopterServiceMock) ActiveFlightIDByAircraftIDs(context.Context, [][]byte) (map[string][]byte, error) {
+	return map[string][]byte{}, nil
+}
+func (m *helicopterServiceMock) ExistsByIdentifier(context.Context, string, []byte) (bool, error) {
+	return false, nil
+}
+
+func (m *helicopterFileTakeoverServiceMock) GetByID(context.Context, []byte) (*takeoverdomain.TakeoverAc, error) {
+	return m.row, m.err
+}
+
+func newHelicopterFileTestApp(h *HelicopterFileHandler) *fiber.App {
+	app := fiber.New()
+	app.Post("/upload", h.Upload)
+	app.Post("/cancel-upload", h.CancelUpload)
+	app.Post("/create", h.Create)
+	app.Patch("/update", h.Update)
+	app.Get("/get/:helicopter_id", h.Get)
+	app.Get("/list", h.List)
+	app.Delete("/delete", h.Delete)
+	return app
+}
+
+func newHelicopterFileTestAppWithUser(h *HelicopterFileHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", append([]byte(nil), actor...))
+		}
+		return c.Next()
+	})
+	app.Post("/upload", h.Upload)
+	app.Post("/cancel-upload", h.CancelUpload)
+	app.Post("/create", h.Create)
+	app.Patch("/update", h.Update)
+	app.Get("/get/:helicopter_id", h.Get)
+	app.Get("/list", h.List)
+	app.Delete("/delete", h.Delete)
+	return app
+}
+
+func newHelicopterFileEventsTestApp(h *FileManagerEventsHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if actor != nil {
+			c.Locals("user_id", append([]byte(nil), actor...))
+		}
+		return c.Next()
+	})
+	app.Get("/api/v1/helicopter-files/events", h.Stream)
+	return app
+}
+
+func doHelicopterFileRequest(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func TestHelicopterFileEventsStream(t *testing.T) {
+	hub := helicopterfilerealtime.NewHub(1, nil)
+	actor := uuidv7.MustBytes()
+	userUUID, _ := uuidv7.BytesToString(actor)
+	helicopterID := uuidv7.MustBytes()
+	helicopterFileID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+
+	app := fiber.New()
+	fctx := &fasthttp.RequestCtx{}
+	fctx.Request.SetRequestURI("/api/v1/helicopter-files/events?helicopter_id=" + mustUUIDString(t, helicopterID))
+	c := app.AcquireCtx(fctx)
+	c.Locals("user_id", actor)
+	if err := NewHelicopterFileEventsHandler(hub).Stream(c); err != nil {
+		t.Fatalf("unexpected stream setup error: %v", err)
+	}
+
+	hub.PublishToUsers([]string{userUUID}, helicopterfilerealtime.Event{
+		HelicopterID:      mustUUIDString(t, helicopterID),
+		HelicopterFileID:  mustUUIDString(t, helicopterFileID),
+		FileID:            mustUUIDString(t, fileID),
+		Section:           helicopterfile.SectionFlightPreparationAndWB,
+		Name:              "helicopter.pdf",
+		MimeType:          "application/pdf",
+		AttachmentPending: true,
+		Position:          3,
+		UpdatedAt:         time.Now().UTC().Format(time.RFC3339),
+	})
+	go func() {
+		time.Sleep(10 * time.Millisecond)
+		closeFirstHelicopterFileHubSubscriberForUser(hub, userUUID)
+	}()
+
+	bodyStr := c.Context().Response.String()
+	app.ReleaseCtx(c)
+	if !strings.Contains(bodyStr, ": connected") {
+		t.Fatalf("expected connected comment in body: %q", bodyStr)
+	}
+	if !strings.Contains(bodyStr, "event: helicopter.file.created") {
+		t.Fatalf("expected helicopter.file.created event in body: %q", bodyStr)
+	}
+	if !strings.Contains(bodyStr, "\"file_id\"") || !strings.Contains(bodyStr, "\"helicopter_id\"") || !strings.Contains(bodyStr, "\"section\":\"fpwb\"") {
+		t.Fatalf("expected helicopter file payload in body: %q", bodyStr)
+	}
+}
+
+func closeFirstHelicopterFileHubSubscriberForUser(hub *helicopterfilerealtime.Hub, userUUID string) {
+	if hub == nil {
+		return
+	}
+	hubValue := reflect.ValueOf(hub).Elem()
+	subscribersField := reflect.NewAt(hubValue.FieldByName("subscribers").Type(), unsafe.Pointer(hubValue.FieldByName("subscribers").UnsafeAddr())).Elem()
+	byUser := subscribersField.MapIndex(reflect.ValueOf(strings.ToLower(strings.TrimSpace(userUUID))))
+	if !byUser.IsValid() || byUser.Len() == 0 {
+		return
+	}
+	iter := byUser.MapRange()
+	if !iter.Next() {
+		return
+	}
+	sub := iter.Value()
+	if sub.IsNil() {
+		return
+	}
+	subElem := sub.Elem()
+	closeOnceField := reflect.NewAt(subElem.FieldByName("closeOnce").Type(), unsafe.Pointer(subElem.FieldByName("closeOnce").UnsafeAddr())).Elem()
+	closeOncePtr := (*sync.Once)(unsafe.Pointer(closeOnceField.UnsafeAddr()))
+	closeOncePtr.Do(func() {})
+	doneField := reflect.NewAt(subElem.FieldByName("done").Type(), unsafe.Pointer(subElem.FieldByName("done").UnsafeAddr())).Elem()
+	doneField.Close()
+}
+
+func withHelicopterFileCtx(t *testing.T, fn func(*fiber.Ctx)) {
+	t.Helper()
+	app := fiber.New()
+	app.Get("/", func(c *fiber.Ctx) error {
+		fn(c)
+		return c.SendStatus(fiber.StatusOK)
+	})
+	req, _ := http.NewRequest(http.MethodGet, "/", nil)
+	if _, err := app.Test(req); err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+}
+
+func TestHelicopterFileHandler_HelperCoverage(t *testing.T) {
+	t.Run("constructor and fluent setters", func(t *testing.T) {
+		h := NewHelicopterFileHandler(&helicopterFileServiceMock{})
+		if h == nil || h.validate == nil {
+			t.Fatalf("expected handler initialized")
+		}
+		if h.WithFileManagerService(nil) != h {
+			t.Fatalf("expected WithFileManagerService to return same handler")
+		}
+		if h.WithHelicopterService(nil) != h {
+			t.Fatalf("expected WithHelicopterService to return same handler")
+		}
+		if h.WithFileStorage(nil) != h {
+			t.Fatalf("expected WithFileStorage to return same handler")
+		}
+	})
+
+	t.Run("section validation helper", func(t *testing.T) {
+		if !isValidHelicopterFileSection(helicopterfile.SectionBeforeFirstFlightInspection) {
+			t.Fatalf("expected before section valid")
+		}
+		if !isValidHelicopterFileSection(helicopterfile.SectionFlightPreparationAndWB) {
+			t.Fatalf("expected prepare section valid")
+		}
+		if !isValidHelicopterFileSection(helicopterfile.SectionAfterLastFlightInspection) {
+			t.Fatalf("expected after section valid")
+		}
+		if isValidHelicopterFileSection("other") {
+			t.Fatalf("expected invalid section rejected")
+		}
+	})
+
+	t.Run("bulk item helpers", func(t *testing.T) {
+		uploadErr := helicopterFileUploadBulkErrorItem(1, http.StatusBadRequest, "Upload failed", "detail")
+		if uploadErr.Success || uploadErr.Error == nil || uploadErr.Error.Status != http.StatusBadRequest {
+			t.Fatalf("unexpected upload bulk error item: %#v", uploadErr)
+		}
+		createErr := helicopterFileCreateBulkErrorItem(2, http.StatusUnprocessableEntity, "Create failed", "detail")
+		if createErr.Success || createErr.Error == nil || createErr.Error.Status != http.StatusUnprocessableEntity {
+			t.Fatalf("unexpected create bulk error item: %#v", createErr)
+		}
+	})
+}
+
+func TestHelicopterFileHandler_Endpoints(t *testing.T) {
+	t.Run("upload returns 400 when file manager missing", func(t *testing.T) {
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(&helicopterFileServiceMock{}))
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/upload", []byte(`{"data":{"type":"helicopter_file_upload","attributes":{"name":"a.pdf","content_type":"application/pdf","size_bytes":1}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("upload bulk validation and multi-status response", func(t *testing.T) {
+		svc := &helicopterFileServiceMock{
+			uploadBulk: []helicopterfile.UploadIntentBulkItemResult{
+				{Index: 0, Success: true, Grant: &filemanager.FileUploadIntentGrant{
+					UploadIntentID: uuidv7.MustBytes(),
+					Name:           "a.pdf",
+					MimeType:       "application/pdf",
+					SizeBytes:      10,
+					UploadURL:      "https://upload",
+					Headers: map[string]string{
+						"content-type": "application/pdf",
+					},
+				}},
+				{Index: 1, Success: false, Error: &helicopterfile.BulkItemError{Status: http.StatusBadRequest, Title: "Upload failed", Detail: "invalid"}}},
+		}
+		h := NewHelicopterFileHandler(svc).WithFileManagerService(service.NewFileManagerService(nil, nil, nil, service.FileManagerServiceDependencies{}))
+		app := newHelicopterFileTestApp(h)
+
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/upload", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for empty bulk, got %d", resp.StatusCode)
+		}
+
+		body := []byte(`{"data":[{"type":"helicopter_file_upload","attributes":{"name":"a.pdf","content_type":"application/pdf","size_bytes":10}},{"type":"helicopter_file_upload","attributes":{"name":"b.pdf","content_type":"application/pdf","size_bytes":20}}]}`)
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/upload", body)
+		if resp.StatusCode != http.StatusMultiStatus {
+			t.Fatalf("expected 207, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("upload single early branches", func(t *testing.T) {
+		fileSvc := service.NewFileManagerService(nil, nil, nil, service.FileManagerServiceDependencies{})
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(&helicopterFileServiceMock{}).WithFileManagerService(fileSvc))
+
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/upload", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid json, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/upload", []byte(`{"data":{"type":"wrong","attributes":{"name":"a.pdf","content_type":"application/pdf","size_bytes":1}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid type, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/upload", []byte(`{"data":{"type":"helicopter_file_upload","attributes":{"name":"a.pdf","content_type":"application/pdf","size_bytes":1}}}`))
+		if resp.StatusCode != http.StatusServiceUnavailable {
+			t.Fatalf("expected 503 upload intent action error, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("cancel upload validation", func(t *testing.T) {
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(&helicopterFileServiceMock{}))
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/cancel-upload", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 without file manager, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("cancel upload with configured file manager covers early branches", func(t *testing.T) {
+		fileSvc := service.NewFileManagerService(nil, nil, nil, service.FileManagerServiceDependencies{})
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(&helicopterFileServiceMock{}).WithFileManagerService(fileSvc))
+
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/cancel-upload", []byte(`{"data":{"type":"x"}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 non-array payload, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/cancel-upload", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 empty array, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/cancel-upload", []byte(`{"data":[{"type":"wrong","attributes":{"upload_intent_uuid":"bad"}}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 invalid type item bulk response, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("cancel upload invalid json invalid uuid action error and success", func(t *testing.T) {
+		cancelErr := errors.New("cancel failed")
+		fileSvc := &fileManagerFileHandlerServiceMock{
+			cancelUploadFn: func(_ context.Context, params filemanager.CancelFileUploadIntentParams) error {
+				if strings.HasPrefix(mustUUIDString(t, params.UploadIntentID), "0") {
+					return nil
+				}
+				return cancelErr
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(&helicopterFileServiceMock{}).WithFileManagerService(fileSvc))
+
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/cancel-upload", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid json, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/cancel-upload", []byte(`{"data":[{"type":"helicopter_file_cancel_upload","attributes":{"upload_intent_uuid":"bad"}}]}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 bulk response for invalid upload_intent_uuid item, got %d", resp.StatusCode)
+		}
+
+		firstID := mustUUIDString(t, uuidv7.MustBytes())
+		secondID := mustUUIDString(t, uuidv7.MustBytes())
+		body := []byte(`{"data":[{"type":"helicopter_file_cancel_upload","attributes":{"upload_intent_uuid":"` + firstID + `"}},{"type":"helicopter_file_cancel_upload","attributes":{"upload_intent_uuid":"` + secondID + `"}}]}`)
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/cancel-upload", body)
+		if resp.StatusCode != http.StatusMultiStatus && resp.StatusCode != http.StatusServiceUnavailable && resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected mapped bulk response status, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create validation branches", func(t *testing.T) {
+		svc := &helicopterFileServiceMock{}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc))
+
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid json, got %d", resp.StatusCode)
+		}
+
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bad","helicopter_id":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid section, got %d", resp.StatusCode)
+		}
+
+		validHeli := mustUUIDString(t, uuidv7.MustBytes())
+		body = []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + validHeli + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 helicopter not found, got %d", resp.StatusCode)
+		}
+
+		svc.helicopterExists = true
+		body = []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + validHeli + `","upload_intent_uuid":"bad","file_name":"A.pdf"}}}`)
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid upload_intent_uuid, got %d", resp.StatusCode)
+		}
+
+		body = []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + validHeli + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":""}}}`)
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 empty file_name, got %d", resp.StatusCode)
+		}
+
+		body = []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + validHeli + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 when file manager not configured, got %d", resp.StatusCode)
+		}
+
+		svc.helicopterExistsErr = errors.New("lookup failed")
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 helicopter lookup error, got %d", resp.StatusCode)
+		}
+		svc.helicopterExistsErr = nil
+		svc.helicopterExists = true
+
+		body = []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + validHeli + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf","folder_uuid":"bad"}}}`)
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusBadRequest && resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 400/422 invalid folder_uuid, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create bulk multi-status", func(t *testing.T) {
+		row := &helicopterfile.HelicopterFile{
+			ID:               uuidv7.MustBytes(),
+			HelicopterID:     uuidv7.MustBytes(),
+			FileAttachmentID: uuidv7.MustBytes(),
+			Section:          helicopterfile.SectionBeforeFirstFlightInspection,
+			CreatedAt:        time.Now().UTC(),
+			UpdatedAt:        time.Now().UTC(),
+		}
+		svc := &helicopterFileServiceMock{
+			createBulk: []helicopterfile.CreateBulkItemResult{
+				{Index: 0, Success: true, Row: row},
+				{Index: 1, Success: false, Error: &helicopterfile.BulkItemError{Status: http.StatusBadRequest, Title: "Create failed", Detail: "invalid"}},
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc))
+		body := []byte(`{"data":[{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}},{"type":"helicopter_file_create","attributes":{"section":"afi","helicopter_id":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"B.pdf"}}]}`)
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusMultiStatus {
+			t.Fatalf("expected 207, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create single success", func(t *testing.T) {
+		heliID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		attachmentID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{
+			helicopterExists: true,
+			createFn: func(_ context.Context, row *helicopterfile.HelicopterFile) error {
+				if row != nil && len(row.ID) == 0 {
+					row.ID = fileID
+				}
+				if row != nil && row.UpdatedAt.IsZero() {
+					now := time.Now().UTC()
+					row.CreatedAt = now
+					row.UpdatedAt = now
+				}
+				return nil
+			},
+		}
+		fm := &helicopterFileManagerMock{
+			createFileFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:        fileID,
+					Status:    filemanager.FileStatusReady,
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}, nil
+			},
+			createAttachmentFn: func(_ context.Context, _ filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+				return &filemanager.Attachment{ID: attachmentID, FileID: fileID}, nil
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, heliID) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, respBody := doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		if fm.lastCreateFile == nil || !fm.lastCreateFile.IsTemplate {
+			t.Fatalf("expected helicopter file create flow to mark is_template=true")
+		}
+	})
+
+	t.Run("create publishes helicopter file event", func(t *testing.T) {
+		actorID := uuidv7.MustBytes()
+		heliID := uuidv7.MustBytes()
+		helicopterFileID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{
+			helicopterExists: true,
+			createFn: func(_ context.Context, row *helicopterfile.HelicopterFile) error {
+				if row != nil && len(row.ID) == 0 {
+					row.ID = helicopterFileID
+				}
+				if row != nil && row.UpdatedAt.IsZero() {
+					now := time.Now().UTC()
+					row.CreatedAt = now
+					row.UpdatedAt = now
+				}
+				return nil
+			},
+		}
+		fm := &helicopterFileManagerMock{
+			createFileFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:        fileID,
+					Name:      "A.pdf",
+					MimeType:  "application/pdf",
+					Status:    filemanager.FileStatusReady,
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}, nil
+			},
+		}
+		events := &helicopterFileEventsMock{}
+		app := newHelicopterFileTestAppWithUser(
+			NewHelicopterFileHandler(svc).
+				WithFileManagerService(fm).
+				WithHelicopterFileEvents(events),
+			actorID,
+		)
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, heliID) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, respBody := doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		if events.publishCalls != 1 {
+			t.Fatalf("expected one helicopter file event publish, got %d", events.publishCalls)
+		}
+		if len(events.publishedUsers) != 1 {
+			t.Fatalf("expected one published user, got %v", events.publishedUsers)
+		}
+		expectedUser, _ := uuidv7.BytesToString(actorID)
+		if events.publishedUsers[0] != expectedUser {
+			t.Fatalf("expected event for user %s, got %s", expectedUser, events.publishedUsers[0])
+		}
+		if events.event == nil {
+			t.Fatalf("expected published event")
+		}
+		expectedHeli, _ := uuidv7.BytesToString(heliID)
+		expectedHeliFileID, _ := uuidv7.BytesToString(helicopterFileID)
+		expectedFile, _ := uuidv7.BytesToString(fileID)
+		if events.event.HelicopterID != expectedHeli || events.event.FileID != expectedFile || events.event.HelicopterFileID != expectedHeliFileID {
+			t.Fatalf("unexpected published event: %+v", events.event)
+		}
+		if events.event.EventType != helicopterfilerealtime.DefaultEventType {
+			t.Fatalf("expected default helicopter file event type, got %s", events.event.EventType)
+		}
+		if !events.event.AttachmentPending {
+			t.Fatalf("expected attachment pending event, got %+v", events.event)
+		}
+	})
+
+	t.Run("create sanitizes malformed xlsx templates before validation", func(t *testing.T) {
+		heliID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		objectKey := "files/template.xlsx"
+		original := testMalformedXLSXZip(t)
+		storage := &templateCopyStorageMock{
+			objects: map[string][]byte{
+				objectKey: append([]byte(nil), original...),
+			},
+			contentTypes: map[string]string{
+				objectKey: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+			},
+		}
+		svc := &helicopterFileServiceMock{helicopterExists: true}
+		fm := &helicopterFileManagerMock{
+			createFileFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:        fileID,
+					Name:      "template.xlsx",
+					ObjectKey: objectKey,
+					MimeType:  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+					SizeBytes: int64(len(original)),
+					Status:    filemanager.FileStatusReady,
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}, nil
+			},
+		}
+		app := newHelicopterFileTestApp(
+			NewHelicopterFileHandler(svc).
+				WithFileManagerService(fm).
+				WithFileStorage(storage),
+		)
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, heliID) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"template.xlsx"}}}`)
+		resp, respBody := doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d body=%s", resp.StatusCode, string(respBody))
+		}
+		if fm.updateFileCalls != 1 {
+			t.Fatalf("expected sanitized xlsx metadata to be persisted once, got %d", fm.updateFileCalls)
+		}
+		vml := zipEntryPayload(t, storage.objects[objectKey], "xl/drawings/vmlDrawing1.vml")
+		if !bytes.Contains(vml, []byte(`margin-left:73.5pt`)) {
+			t.Fatalf("expected uploaded template to be sanitized, got: %s", string(vml))
+		}
+	})
+
+	t.Run("create duplicate name resolves existing file", func(t *testing.T) {
+		heliID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		attachmentID := uuidv7.MustBytes()
+		rootID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{helicopterExists: true}
+		fm := &helicopterFileManagerMock{
+			createFileFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return nil, filemanager.ErrDuplicateName
+			},
+			getRootFn: func(_ context.Context) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: rootID}, nil
+			},
+			getByFolderNameFn: func(_ context.Context, folderID []byte, _ string) (*filemanager.File, error) {
+				return &filemanager.File{ID: fileID, Status: filemanager.FileStatusReady, FolderID: folderID, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+			createAttachmentFn: func(_ context.Context, _ filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+				return &filemanager.Attachment{ID: attachmentID, FileID: fileID}, nil
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, heliID) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create service write error", func(t *testing.T) {
+		heliID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		attachmentID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{
+			helicopterExists: true,
+			createErr:        errors.New("insert failed"),
+		}
+		fm := &helicopterFileManagerMock{
+			createFileFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:        fileID,
+					Status:    filemanager.FileStatusReady,
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}, nil
+			},
+			createAttachmentFn: func(_ context.Context, _ filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+				return &filemanager.Attachment{ID: attachmentID, FileID: fileID}, nil
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, heliID) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/create", bytes.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req, 7000)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create resolves attachment from existing list when already attached", func(t *testing.T) {
+		heliID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		attachmentID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{helicopterExists: true}
+		fm := &helicopterFileManagerMock{
+			createFileFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:        fileID,
+					Status:    filemanager.FileStatusReady,
+					CreatedAt: time.Now().UTC(),
+					UpdatedAt: time.Now().UTC(),
+				}, nil
+			},
+			createAttachmentFn: func(_ context.Context, _ filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+				return nil, filemanager.ErrAttachmentAlreadyExists
+			},
+			listAttachmentRefFn: func(_ context.Context, _ filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error) {
+				return []filemanager.Attachment{{ID: attachmentID, FileID: fileID}}, 1, nil
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, heliID) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create returns processing failed when file pipeline fails", func(t *testing.T) {
+		heliID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{helicopterExists: true}
+		fm := &helicopterFileManagerMock{
+			createFileFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return &filemanager.File{ID: fileID, Status: filemanager.FileStatusProcessing}, nil
+			},
+			getFileByIDFn: func(_ context.Context, _ []byte) (*filemanager.File, error) {
+				return &filemanager.File{ID: fileID, Status: filemanager.FileStatusFailed, FailureReason: "pipeline failed"}, nil
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, heliID) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201 pending create, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create processing poll get file error", func(t *testing.T) {
+		heliID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{helicopterExists: true}
+		fm := &helicopterFileManagerMock{
+			createFileFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return &filemanager.File{ID: fileID, Status: filemanager.FileStatusProcessing}, nil
+			},
+			getFileByIDFn: func(_ context.Context, _ []byte) (*filemanager.File, error) {
+				return nil, errors.New("poll failed")
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, heliID) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201 pending create, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create returns processing retry when file stays processing", func(t *testing.T) {
+		t.Skip("fiber test timeout too short for processing retry branch")
+		heliID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{helicopterExists: true}
+		fm := &helicopterFileManagerMock{
+			createFileFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return &filemanager.File{ID: fileID, Status: filemanager.FileStatusProcessing}, nil
+			},
+			getFileByIDFn: func(_ context.Context, _ []byte) (*filemanager.File, error) {
+				return &filemanager.File{ID: fileID, Status: filemanager.FileStatusProcessing}, nil
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, heliID) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create duplicate root resolve error", func(t *testing.T) {
+		heliID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{helicopterExists: true}
+		fm := &helicopterFileManagerMock{
+			createFileFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return nil, filemanager.ErrDuplicateName
+			},
+			getRootFn: func(_ context.Context) (*filemanager.Folder, error) {
+				return nil, errors.New("root failed")
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, heliID) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create duplicate unresolved existing file", func(t *testing.T) {
+		heliID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{helicopterExists: true}
+		fm := &helicopterFileManagerMock{
+			createFileFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return nil, filemanager.ErrDuplicateName
+			},
+			getRootFn: func(_ context.Context) (*filemanager.Folder, error) {
+				return &filemanager.Folder{ID: uuidv7.MustBytes()}, nil
+			},
+			getByFolderNameFn: func(_ context.Context, _ []byte, _ string) (*filemanager.File, error) {
+				return nil, errors.New("lookup failed")
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, heliID) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create returns bad request when file node missing", func(t *testing.T) {
+		heliID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{helicopterExists: true}
+		fm := &helicopterFileManagerMock{
+			createFileFn: func(_ context.Context, _ filemanager.CreateFileFromUploadIntentParams) (*filemanager.File, error) {
+				return nil, nil
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+		body := []byte(`{"data":{"type":"helicopter_file_create","attributes":{"section":"bfi","helicopter_id":"` + mustUUIDString(t, heliID) + `","upload_intent_uuid":"` + mustUUIDString(t, uuidv7.MustBytes()) + `","file_name":"A.pdf"}}}`)
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPost, "/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update validation branches", func(t *testing.T) {
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(&helicopterFileServiceMock{}))
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPatch, "/update", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid json, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"bad","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid id, got %d", resp.StatusCode)
+		}
+
+		id := mustUUIDString(t, uuidv7.MustBytes())
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 not found, got %d", resp.StatusCode)
+		}
+
+		svc := &helicopterFileServiceMock{
+			getRow: &helicopterfile.HelicopterFile{
+				ID:               uuidv7.MustBytes(),
+				HelicopterID:     uuidv7.MustBytes(),
+				FileAttachmentID: uuidv7.MustBytes(),
+			},
+		}
+		appWithRow := newHelicopterFileTestApp(NewHelicopterFileHandler(svc))
+		resp, _ = doHelicopterFileRequest(t, appWithRow, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+id+`","attributes":{"section":"wrong"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid section, got %d", resp.StatusCode)
+		}
+
+		rawBadHeli := "bad-heli"
+		resp, _ = doHelicopterFileRequest(t, appWithRow, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+id+`","attributes":{"helicopter_id":"`+rawBadHeli+`"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid helicopter_id, got %d", resp.StatusCode)
+		}
+
+		svc.helicopterExistsErr = errors.New("exists failed")
+		validHeli := mustUUIDString(t, uuidv7.MustBytes())
+		resp, _ = doHelicopterFileRequest(t, appWithRow, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+id+`","attributes":{"helicopter_id":"`+validHeli+`"}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 helicopter exists error, got %d", resp.StatusCode)
+		}
+		svc.helicopterExistsErr = nil
+		svc.helicopterExists = false
+		resp, _ = doHelicopterFileRequest(t, appWithRow, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+id+`","attributes":{"helicopter_id":"`+validHeli+`"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 helicopter not found, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, appWithRow, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+id+`","attributes":{"file_name":" "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 empty file_name, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, appWithRow, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+id+`","attributes":{"file_name":"A.pdf"}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 when file manager missing, got %d", resp.StatusCode)
+		}
+
+		svc.updateErr = errors.New("update failed")
+		resp, _ = doHelicopterFileRequest(t, appWithRow, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 update error, got %d", resp.StatusCode)
+		}
+		svc.updateErr = nil
+		svc.getErr = errors.New("get failed")
+		resp, _ = doHelicopterFileRequest(t, appWithRow, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 get failed, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update success minimal", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{
+			getRow: &helicopterfile.HelicopterFile{
+				ID:               id,
+				HelicopterID:     uuidv7.MustBytes(),
+				FileAttachmentID: uuidv7.MustBytes(),
+				Section:          helicopterfile.SectionBeforeFirstFlightInspection,
+				CreatedAt:        time.Now().UTC(),
+				UpdatedAt:        time.Now().UTC(),
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc))
+		resp, body := doHelicopterFileRequest(t, app, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+mustUUIDString(t, id)+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(body))
+		}
+	})
+
+	t.Run("update file_name path success", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		attID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{
+			getRow: &helicopterfile.HelicopterFile{
+				ID:               id,
+				HelicopterID:     uuidv7.MustBytes(),
+				FileAttachmentID: attID,
+				Section:          helicopterfile.SectionBeforeFirstFlightInspection,
+				CreatedAt:        time.Now().UTC(),
+				UpdatedAt:        time.Now().UTC(),
+			},
+		}
+		fm := &helicopterFileManagerMock{
+			getAttachmentByIDFn: func(_ context.Context, _ []byte) (*filemanager.Attachment, error) {
+				return &filemanager.Attachment{ID: attID, FileID: fileID}, nil
+			},
+			moveFileFn: func(_ context.Context, _ []byte, _ filemanager.MoveFileParams) (*filemanager.File, error) {
+				return &filemanager.File{ID: fileID}, nil
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+mustUUIDString(t, id)+`","attributes":{"file_name":"Renamed.pdf"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update bulk mixed results", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{
+			getRow: &helicopterfile.HelicopterFile{
+				ID:               id,
+				HelicopterID:     uuidv7.MustBytes(),
+				FileAttachmentID: uuidv7.MustBytes(),
+				Section:          helicopterfile.SectionBeforeFirstFlightInspection,
+				CreatedAt:        time.Now().UTC(),
+				UpdatedAt:        time.Now().UTC(),
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc))
+
+		body := []byte(`{
+				"data": [
+					{"type":"helicopter_file_update","id":"` + mustUUIDString(t, id) + `","attributes":{"position":2}},
+					{"type":"helicopter_file_update","id":"bad-id","attributes":{"position":3}}
+				]
+			}`)
+		resp, raw := doHelicopterFileRequest(t, app, http.MethodPatch, "/update", body)
+		if resp.StatusCode != http.StatusMultiStatus {
+			t.Fatalf("expected 207, got %d body=%s", resp.StatusCode, string(raw))
+		}
+		if !strings.Contains(string(raw), `"partial_success":true`) {
+			t.Fatalf("expected partial_success true, got %s", string(raw))
+		}
+	})
+
+	t.Run("update bulk invalid envelope branches", func(t *testing.T) {
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(&helicopterFileServiceMock{}))
+
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodPatch, "/update", []byte(`{"data":[]}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for empty bulk, got %d", resp.StatusCode)
+		}
+
+		items := make([]string, 0, 101)
+		for i := 0; i < 101; i++ {
+			items = append(items, `{"type":"helicopter_file_update","id":"`+mustUUIDString(t, uuidv7.MustBytes())+`","attributes":{}}`)
+		}
+		body := []byte(`{"data":[` + strings.Join(items, ",") + `]}`)
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodPatch, "/update", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 for too many bulk items, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update one file rename and lifecycle error branches", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		attID := uuidv7.MustBytes()
+		baseRow := &helicopterfile.HelicopterFile{
+			ID:               id,
+			HelicopterID:     uuidv7.MustBytes(),
+			FileAttachmentID: attID,
+			Section:          helicopterfile.SectionBeforeFirstFlightInspection,
+			CreatedAt:        time.Now().UTC(),
+			UpdatedAt:        time.Now().UTC(),
+		}
+
+		t.Run("attachment lookup error", func(t *testing.T) {
+			svc := &helicopterFileServiceMock{getRow: baseRow}
+			fm := &helicopterFileManagerMock{
+				getAttachmentByIDFn: func(context.Context, []byte) (*filemanager.Attachment, error) {
+					return nil, errors.New("attachment failed")
+				},
+			}
+			app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+			resp, _ := doHelicopterFileRequest(t, app, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+mustUUIDString(t, id)+`","attributes":{"file_name":"Renamed.pdf"}}}`))
+			if resp.StatusCode != http.StatusBadRequest {
+				t.Fatalf("expected 400, got %d", resp.StatusCode)
+			}
+		})
+
+		t.Run("attachment not found", func(t *testing.T) {
+			svc := &helicopterFileServiceMock{getRow: baseRow}
+			fm := &helicopterFileManagerMock{
+				getAttachmentByIDFn: func(context.Context, []byte) (*filemanager.Attachment, error) {
+					return nil, nil
+				},
+			}
+			app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+			resp, _ := doHelicopterFileRequest(t, app, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+mustUUIDString(t, id)+`","attributes":{"file_name":"Renamed.pdf"}}}`))
+			if resp.StatusCode != http.StatusNotFound {
+				t.Fatalf("expected 404, got %d", resp.StatusCode)
+			}
+		})
+
+		t.Run("move file error", func(t *testing.T) {
+			svc := &helicopterFileServiceMock{getRow: baseRow}
+			fm := &helicopterFileManagerMock{
+				getAttachmentByIDFn: func(context.Context, []byte) (*filemanager.Attachment, error) {
+					return &filemanager.Attachment{ID: attID, FileID: uuidv7.MustBytes()}, nil
+				},
+				moveFileFn: func(context.Context, []byte, filemanager.MoveFileParams) (*filemanager.File, error) {
+					return nil, errors.New("move failed")
+				},
+			}
+			app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc).WithFileManagerService(fm))
+			resp, _ := doHelicopterFileRequest(t, app, http.MethodPatch, "/update", []byte(`{"data":{"type":"helicopter_file","id":"`+mustUUIDString(t, id)+`","attributes":{"file_name":"Renamed.pdf"}}}`))
+			if resp.StatusCode != http.StatusBadRequest {
+				t.Fatalf("expected 400, got %d", resp.StatusCode)
+			}
+		})
+	})
+
+	t.Run("update bulk success", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{
+			getRow: &helicopterfile.HelicopterFile{
+				ID:               id,
+				HelicopterID:     uuidv7.MustBytes(),
+				FileAttachmentID: uuidv7.MustBytes(),
+				Section:          helicopterfile.SectionBeforeFirstFlightInspection,
+				CreatedAt:        time.Now().UTC(),
+				UpdatedAt:        time.Now().UTC(),
+			},
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc))
+
+		body := []byte(`{
+				"data": [
+					{"type":"helicopter_file_update","id":"` + mustUUIDString(t, id) + `","attributes":{"position":2}}
+				]
+			}`)
+		resp, raw := doHelicopterFileRequest(t, app, http.MethodPatch, "/update", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(raw))
+		}
+		if !strings.Contains(string(raw), `"success":1`) {
+			t.Fatalf("expected bulk meta success 1, got %s", string(raw))
+		}
+	})
+
+	t.Run("get list and delete", func(t *testing.T) {
+		helicopterID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		attachmentID := uuidv7.MustBytes()
+		rows := []helicopterfile.HelicopterFile{
+			{
+				ID:               uuidv7.MustBytes(),
+				HelicopterID:     helicopterID,
+				FileAttachmentID: attachmentID,
+				Section:          helicopterfile.SectionBeforeFirstFlightInspection,
+				CreatedAt:        time.Now().UTC(),
+				UpdatedAt:        time.Now().UTC(),
+				FileAttachment: &filemanager.Attachment{
+					ID: attachmentID,
+					File: &filemanager.File{
+						ID:        fileID,
+						Name:      "A.pdf",
+						ObjectKey: "files/A.pdf",
+						SizeBytes: 11,
+					},
+				},
+			},
+		}
+		svc := &helicopterFileServiceMock{
+			helicopterExists: true,
+			byHeliRows:       rows,
+			listRows:         rows,
+			listTotal:        1,
+		}
+		h := NewHelicopterFileHandler(svc).
+			WithHelicopterService(&helicopterServiceMock{row: &helicopter.Helicopter{ID: helicopterID, Designation: "OE-XHZ"}}).
+			WithFileStorage(&fileManagerDownloadURLStorageMock{presignedURL: "https://signed/file.pdf"})
+		app := newHelicopterFileTestApp(h)
+
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodGet, "/get/bad", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid helicopter uuid, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodGet, "/get/"+mustUUIDString(t, helicopterID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 get success, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodGet, "/list?page[number]=0&page[size]=101", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 list success, got %d", resp.StatusCode)
+		}
+
+		takeoverID := uuidv7.MustBytes()
+		actorID := uuidv7.MustBytes()
+		filterRows := []helicopterfile.HelicopterFile{
+			{
+				ID:           uuidv7.MustBytes(),
+				HelicopterID: helicopterID,
+				SourceFileID: uuidv7.MustBytes(),
+				Section:      helicopterfile.SectionFlightPreparationAndWB,
+				CreatedAt:    time.Now().UTC(),
+				UpdatedAt:    time.Now().UTC(),
+				SourceFile: &filemanager.File{
+					ID:         uuidv7.MustBytes(),
+					Name:       "takeover-only.pdf",
+					ObjectKey:  "files/takeover-only.pdf",
+					SizeBytes:  11,
+					TakeoverID: takeoverID,
+				},
+			},
+			{
+				ID:           uuidv7.MustBytes(),
+				HelicopterID: helicopterID,
+				SourceFileID: uuidv7.MustBytes(),
+				Section:      helicopterfile.SectionFlightPreparationAndWB,
+				CreatedAt:    time.Now().UTC(),
+				UpdatedAt:    time.Now().UTC(),
+				SourceFile: &filemanager.File{
+					ID:        uuidv7.MustBytes(),
+					Name:      "public.pdf",
+					ObjectKey: "files/public.pdf",
+					SizeBytes: 12,
+				},
+			},
+		}
+		filterSvc := &helicopterFileServiceMock{
+			helicopterExists: true,
+			byHeliRows:       filterRows,
+			listRows:         filterRows,
+			listTotal:        1,
+		}
+		filterApp := newHelicopterFileTestAppWithUser(
+			NewHelicopterFileHandler(filterSvc).
+				WithTakeoverService(&helicopterFileTakeoverServiceMock{
+					row: &takeoverdomain.TakeoverAc{
+						ID:        takeoverID,
+						CreatedBy: uuidv7.MustBytes(),
+					},
+				}).
+				WithHelicopterService(&helicopterServiceMock{row: &helicopter.Helicopter{ID: helicopterID, Designation: "OE-XHZ"}}).
+				WithFileStorage(&fileManagerDownloadURLStorageMock{presignedURL: "https://signed/file.pdf"}),
+			actorID,
+		)
+
+		resp, raw := doHelicopterFileRequest(t, filterApp, http.MethodGet, "/get/"+mustUUIDString(t, helicopterID), nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 filtered get, got %d body=%s", resp.StatusCode, string(raw))
+		}
+		var filteredGet struct {
+			Data struct {
+				Attributes struct {
+					Files struct {
+						Prepare []responsedto.HelicopterFileCollectionItem `json:"prepare"`
+					} `json:"files"`
+				} `json:"attributes"`
+			} `json:"data"`
+		}
+		if err := json.Unmarshal(raw, &filteredGet); err != nil {
+			t.Fatalf("unmarshal filtered get: %v", err)
+		}
+		if len(filteredGet.Data.Attributes.Files.Prepare) != 1 {
+			t.Fatalf("expected 1 visible prepare item, got %#v", filteredGet.Data.Attributes.Files.Prepare)
+		}
+		if got := filteredGet.Data.Attributes.Files.Prepare[0].Attachment.FileName; got != "public.pdf" {
+			t.Fatalf("expected public file, got %q", got)
+		}
+
+		resp, raw = doHelicopterFileRequest(t, filterApp, http.MethodGet, "/list", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 filtered list, got %d body=%s", resp.StatusCode, string(raw))
+		}
+		var filteredList struct {
+			Data []struct {
+				Attributes struct {
+					Files struct {
+						Prepare []responsedto.HelicopterFileCollectionItem `json:"prepare"`
+					} `json:"files"`
+				} `json:"attributes"`
+			} `json:"data"`
+		}
+		if err := json.Unmarshal(raw, &filteredList); err != nil {
+			t.Fatalf("unmarshal filtered list: %v", err)
+		}
+		if len(filteredList.Data) != 1 || len(filteredList.Data[0].Attributes.Files.Prepare) != 1 {
+			t.Fatalf("expected only visible helicopter file in list, got %#v", filteredList.Data)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodDelete, "/delete", []byte(`{"data":{"type":"helicopter_file_delete","id":"bad"}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 invalid delete id, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodDelete, "/delete", []byte(`{"data":{"type":"helicopter_file_delete","id":"`+mustUUIDString(t, uuidv7.MustBytes())+`"}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200 delete success, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("get and delete error branches", func(t *testing.T) {
+		helicopterID := uuidv7.MustBytes()
+		svc := &helicopterFileServiceMock{
+			helicopterExistsErr: errors.New("lookup failed"),
+			deleteErr:           errors.New("delete failed"),
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc))
+
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodGet, "/get/"+mustUUIDString(t, helicopterID), nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 get error, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodDelete, "/delete", []byte(`{"data":{"type":"helicopter_file_delete","id":"`+mustUUIDString(t, uuidv7.MustBytes())+`"}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 delete error, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete invalid json and validation error", func(t *testing.T) {
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(&helicopterFileServiceMock{}))
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodDelete, "/delete", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 invalid json, got %d", resp.StatusCode)
+		}
+
+		resp, _ = doHelicopterFileRequest(t, app, http.MethodDelete, "/delete", []byte(`{"data":{"type":"","id":""}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 validation error, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("get not found and list error", func(t *testing.T) {
+		svc := &helicopterFileServiceMock{
+			helicopterExists: false,
+			listErr:          errors.New("list failed"),
+		}
+		app := newHelicopterFileTestApp(NewHelicopterFileHandler(svc))
+
+		resp, _ := doHelicopterFileRequest(t, app, http.MethodGet, "/get/"+mustUUIDString(t, uuidv7.MustBytes()), nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 helicopter not found, got %d", resp.StatusCode)
+		}
+
+		resp, body := doHelicopterFileRequest(t, app, http.MethodGet, "/list", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400 list error, got %d body=%s", resp.StatusCode, string(body))
+		}
+	})
+}
+
+func TestHelicopterFileHandler_validateStoredHelicopterFileContent(t *testing.T) {
+	corruptStorage := &templateCopyStorageMock{
+		getFn: func(_ context.Context, _ string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+			// Not a valid office document (plain text bytes).
+			return io.NopCloser(strings.NewReader("this is not a docx")), filemanager.ObjectMetadata{}, nil
+		},
+	}
+	h := NewHelicopterFileHandler(&helicopterFileServiceMock{}).WithFileStorage(corruptStorage)
+
+	// A corrupt office document is rejected.
+	if err := h.validateStoredHelicopterFileContent(context.Background(), &filemanager.File{
+		Name:      "broken.docx",
+		ObjectKey: "files/broken.docx",
+	}); err == nil {
+		t.Fatalf("expected corrupt docx to be rejected")
+	}
+
+	// A non-office file is not inspected and passes through.
+	if err := h.validateStoredHelicopterFileContent(context.Background(), &filemanager.File{
+		Name:      "photo.pdf",
+		ObjectKey: "files/photo.pdf",
+	}); err != nil {
+		t.Fatalf("expected non-office file to pass, got %v", err)
+	}
+
+	// A nil file is a no-op.
+	if err := h.validateStoredHelicopterFileContent(context.Background(), nil); err != nil {
+		t.Fatalf("expected nil file to pass, got %v", err)
+	}
+}
+
+func TestHelicopterFileHandler_validateStoredHelicopterFileContent_XLSXUsesSingleRead(t *testing.T) {
+	var getCalls int
+	storage := &templateCopyStorageMock{
+		getFn: func(_ context.Context, _ string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+			getCalls++
+			return io.NopCloser(bytes.NewReader(createValidXLSXPayload(t))), filemanager.ObjectMetadata{}, nil
+		},
+	}
+	h := NewHelicopterFileHandler(&helicopterFileServiceMock{}).WithFileStorage(storage)
+
+	if err := h.validateStoredHelicopterFileContent(context.Background(), &filemanager.File{
+		Name:      "template.xlsx",
+		ObjectKey: "files/template.xlsx",
+	}); err != nil {
+		t.Fatalf("expected xlsx to pass validation, got %v", err)
+	}
+	if getCalls != 1 {
+		t.Fatalf("expected one storage read for xlsx, got %d", getCalls)
+	}
+}
+
+func createValidXLSXPayload(t *testing.T) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	zw := zip.NewWriter(&buf)
+	entries := map[string]string{
+		"[Content_Types].xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
+			`<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">` +
+			`<Default Extension="xml" ContentType="application/xml"/>` +
+			`<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>` +
+			`<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>` +
+			`</Types>`,
+		"xl/workbook.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
+			`<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"` +
+			` xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">` +
+			`<sheets><sheet name="Sheet1" sheetId="1" r:id="rId1"/></sheets>` +
+			`</workbook>`,
+		"xl/_rels/workbook.xml.rels": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
+			`<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">` +
+			`<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>` +
+			`</Relationships>`,
+		"xl/worksheets/sheet1.xml": `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
+			`<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">` +
+			`<sheetData></sheetData>` +
+			`</worksheet>`,
+	}
+	for name, content := range entries {
+		w, err := zw.Create(name)
+		if err != nil {
+			t.Fatalf("create %s: %v", name, err)
+		}
+		if _, err := w.Write([]byte(content)); err != nil {
+			t.Fatalf("write %s: %v", name, err)
+		}
+	}
+	if err := zw.Close(); err != nil {
+		t.Fatalf("close xlsx: %v", err)
+	}
+	return buf.Bytes()
+}
+
+func TestHelicopterFileHandler_HidesTemplateDerivedFiles(t *testing.T) {
+	helicopterID := uuidv7.MustBytes()
+	rows := []helicopterfile.HelicopterFile{
+		{ // a real template — must stay visible
+			ID:           uuidv7.MustBytes(),
+			HelicopterID: helicopterID,
+			SourceFileID: uuidv7.MustBytes(),
+			Section:      helicopterfile.SectionFlightPreparationAndWB,
+			CreatedAt:    time.Now().UTC(),
+			UpdatedAt:    time.Now().UTC(),
+			SourceFile: &filemanager.File{
+				ID:         uuidv7.MustBytes(),
+				Name:       "template.pdf",
+				ObjectKey:  "files/template.pdf",
+				SizeBytes:  10,
+				IsTemplate: true,
+			},
+		},
+		{ // a document created from a template — must be hidden (kept in DB)
+			ID:           uuidv7.MustBytes(),
+			HelicopterID: helicopterID,
+			SourceFileID: uuidv7.MustBytes(),
+			Section:      helicopterfile.SectionFlightPreparationAndWB,
+			CreatedAt:    time.Now().UTC(),
+			UpdatedAt:    time.Now().UTC(),
+			SourceFile: &filemanager.File{
+				ID:           uuidv7.MustBytes(),
+				Name:         "created-from-template.pdf",
+				ObjectKey:    "files/created-from-template.pdf",
+				SizeBytes:    11,
+				TemplateUUID: uuidv7.MustBytes(),
+			},
+		},
+	}
+	svc := &helicopterFileServiceMock{
+		helicopterExists: true,
+		byHeliRows:       rows,
+		listRows:         rows,
+		listTotal:        1,
+	}
+	h := NewHelicopterFileHandler(svc).
+		WithHelicopterService(&helicopterServiceMock{row: &helicopter.Helicopter{ID: helicopterID, Designation: "OE-XHZ"}}).
+		WithFileStorage(&fileManagerDownloadURLStorageMock{presignedURL: "https://signed/file.pdf"})
+	app := newHelicopterFileTestApp(h)
+
+	resp, raw := doHelicopterFileRequest(t, app, http.MethodGet, "/get/"+mustUUIDString(t, helicopterID), nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(raw))
+	}
+	var got struct {
+		Data struct {
+			Attributes struct {
+				Files struct {
+					Prepare []responsedto.HelicopterFileCollectionItem `json:"prepare"`
+				} `json:"files"`
+			} `json:"attributes"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(raw, &got); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if len(got.Data.Attributes.Files.Prepare) != 1 {
+		t.Fatalf("expected only the template to be visible, got %#v", got.Data.Attributes.Files.Prepare)
+	}
+	if name := got.Data.Attributes.Files.Prepare[0].Attachment.FileName; name != "template.pdf" {
+		t.Fatalf("expected template.pdf visible, got %q", name)
+	}
+}
+
+func TestHelicopterFileHandler_ResourceHelpers(t *testing.T) {
+	row := &helicopterfile.HelicopterFile{
+		ID:               uuidv7.MustBytes(),
+		HelicopterID:     uuidv7.MustBytes(),
+		FileAttachmentID: uuidv7.MustBytes(),
+		Section:          helicopterfile.SectionAfterLastFlightInspection,
+		CreatedBy:        uuidv7.MustBytes(),
+		UpdatedBy:        uuidv7.MustBytes(),
+		CreatedAt:        time.Now().UTC(),
+		UpdatedAt:        time.Now().UTC(),
+		Helicopter:       &helicopter.Helicopter{Designation: "OE-XHZ"},
+		FileAttachment: &filemanager.Attachment{
+			File: &filemanager.File{
+				ID:        uuidv7.MustBytes(),
+				Name:      "report.pdf",
+				ObjectKey: "files/report.pdf",
+				SizeBytes: 100,
+			},
+		},
+	}
+	storage := &fileManagerDownloadURLStorageMock{presignedURL: "https://signed/report.pdf"}
+	res := helicopterFileResource(context.Background(), storage, row)
+	if res.Type != "helicopter_file" {
+		t.Fatalf("unexpected resource type %q", res.Type)
+	}
+	attrs := helicopterFileItemAttributesMap(context.Background(), storage, row)
+	if attrs["section"] != helicopterfile.SectionAfterLastFlightInspection {
+		t.Fatalf("unexpected section in attributes: %#v", attrs)
+	}
+	item := helicopterFileCollectionItem(context.Background(), storage, row)
+	if item.Attachment.DownloadURL != "https://signed/report.pdf" {
+		t.Fatalf("expected presigned download url, got %#v", item.Attachment)
+	}
+}
+
+func TestHelicopterFileHandler_BulkResponseHelpers(t *testing.T) {
+	withHelicopterFileCtx(t, func(c *fiber.Ctx) {
+		items := []responsedto.HelicopterFileUploadIntentBulkItem{
+			{Index: 0, Success: true},
+			{Index: 1, Success: false, Error: &responsedto.HelicopterFileBulkError{Status: http.StatusBadRequest, Title: "bad", Detail: "bad"}},
+		}
+		if err := writeHelicopterFileUploadIntentBulkResponse(c, items); err != nil {
+			t.Fatalf("write upload bulk response: %v", err)
+		}
+	})
+
+	withHelicopterFileCtx(t, func(c *fiber.Ctx) {
+		items := []responsedto.HelicopterFileUploadIntentBulkItem{
+			{Index: 0, Success: true},
+		}
+		if err := writeHelicopterFileUploadIntentBulkResponse(c, items); err != nil {
+			t.Fatalf("write upload bulk all-success response: %v", err)
+		}
+	})
+
+	withHelicopterFileCtx(t, func(c *fiber.Ctx) {
+		items := []responsedto.HelicopterFileCreateBulkItem{
+			{Index: 0, Success: false, Error: &responsedto.HelicopterFileBulkError{Status: http.StatusUnprocessableEntity, Title: "bad", Detail: "bad"}},
+		}
+		if err := writeHelicopterFileCreateBulkResponse(c, items); err != nil {
+			t.Fatalf("write create bulk response: %v", err)
+		}
+	})
+
+	withHelicopterFileCtx(t, func(c *fiber.Ctx) {
+		items := []responsedto.HelicopterFileUploadIntentBulkItem{
+			{Index: 0, Success: false},
+		}
+		if err := writeHelicopterFileUploadIntentBulkResponse(c, items); err != nil {
+			t.Fatalf("write upload bulk default error response: %v", err)
+		}
+	})
+
+	t.Run("write upload bulk all-failed uses item status", func(t *testing.T) {
+		app := fiber.New()
+		app.Get("/", func(c *fiber.Ctx) error {
+			items := []responsedto.HelicopterFileUploadIntentBulkItem{
+				{Index: 0, Success: false, Error: &responsedto.HelicopterFileBulkError{Status: http.StatusBadRequest, Title: "bad", Detail: "bad"}},
+			}
+			return writeHelicopterFileUploadIntentBulkResponse(c, items)
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if !strings.Contains(string(body), `"partial_success":false`) {
+			t.Fatalf("expected partial_success false, got %s", string(body))
+		}
+	})
+}
diff --git a/internal/transport/http/handlers/helicopter_handler.go b/internal/transport/http/handlers/helicopter_handler.go
new file mode 100644
index 0000000..a428ac7
--- /dev/null
+++ b/internal/transport/http/handlers/helicopter_handler.go
@@ -0,0 +1,1627 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanager "wucher/internal/domain/file_manager"
+	fleethistory "wucher/internal/domain/fleet_history"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	"wucher/internal/domain/helicopter"
+	appservice "wucher/internal/service"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/attachmentresolver"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+
+	"gorm.io/gorm"
+)
+
+const (
+	helicopterPhotoAttachmentRefType  = "helicopter_photo"
+	helicopterPhotoAttachmentCategory = "photo"
+)
+
+type helicopterPINVerifier interface {
+	ConsumeSecurityPINActionToken(ctx context.Context, userID []byte, action, token string) error
+}
+
+type helicopterPINSessionVerifier interface {
+	AccessCookieName() string
+	ParseAccessTokenSessionID(ctx context.Context, accessToken string) (string, error)
+	ConsumeSecurityPINActionTokenInSession(ctx context.Context, userID []byte, action, token, sessionID string) error
+}
+
+type helicopterDetailedWriter interface {
+	CreateDetailed(context.Context, appservice.HelicopterCreateInput) (*appservice.HelicopterWriteResult, error)
+	UpdateDetailed(context.Context, appservice.HelicopterUpdateInput) (*appservice.HelicopterWriteResult, error)
+}
+
+// helicopterFleetStatusProvider exposes just the fleet status lookup the
+// helicopter handler needs to attach maintenance schedules to responses.
+type helicopterFleetStatusProvider interface {
+	LatestByHelicopterIDs(ctx context.Context, helicopterIDs [][]byte) (map[string]*fleetstatus.FleetStatus, error)
+}
+
+type HelicopterHandler struct {
+	svc          helicopter.Service
+	fileManager  filemanager.Service
+	storage      fileManagerDownloadURLStorage
+	reserveAc    helicopterLastDailyInspectionProvider
+	fleetStatus  helicopterFleetStatusProvider
+	pinVerifier  helicopterPINVerifier
+	complaintSvc complaintGroundingLister
+	mcfSvc       mcfPendingChecker
+	historySvc   fleetHistoryRecorder
+	validate     *validators.Validator
+}
+
+func (h *HelicopterHandler) WithHistoryService(svc fleetHistoryRecorder) *HelicopterHandler {
+	h.historySvc = svc
+	return h
+}
+
+// recordManualAOG logs a manual AOG set/clear when the request explicitly toggled
+// the persisted air_on_ground flag. aog is nil when the request didn't touch it.
+func (h *HelicopterHandler) recordManualAOG(c *fiber.Ctx, row *helicopter.Helicopter, aog *bool) {
+	if h.historySvc == nil || row == nil || aog == nil {
+		return
+	}
+	action := fleethistory.ActionAOGCleared
+	msg := "AOG cleared (manual)"
+	if *aog {
+		action = fleethistory.ActionAOGSet
+		msg = "AOG set (manual)"
+		if r := strings.TrimSpace(row.AOGReason); r != "" {
+			msg = "AOG set (manual) — " + r
+		}
+	}
+	_ = h.historySvc.Record(c.UserContext(), row.ID, fleethistory.EntityHelicopter, row.ID, action, msg, actorUserID(c))
+}
+
+type helicopterLastDailyInspectionProvider interface {
+	GetLastDailyInspectionSummaryByHelicopterID(ctx context.Context, helicopterID []byte) (*shareddto.LastDailyInspectionSummary, error)
+}
+
+func NewHelicopterHandler(svc helicopter.Service) *HelicopterHandler {
+	return &HelicopterHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+func (h *HelicopterHandler) WithFileManagerService(fileManagerSvc filemanager.Service) *HelicopterHandler {
+	h.fileManager = fileManagerSvc
+	return h
+}
+
+func (h *HelicopterHandler) WithFileStorage(storage fileManagerDownloadURLStorage) *HelicopterHandler {
+	h.storage = storage
+	return h
+}
+
+func (h *HelicopterHandler) WithReserveAcService(reserveAcSvc helicopterLastDailyInspectionProvider) *HelicopterHandler {
+	h.reserveAc = reserveAcSvc
+	return h
+}
+
+func (h *HelicopterHandler) WithPINVerifier(verifier helicopterPINVerifier) *HelicopterHandler {
+	h.pinVerifier = verifier
+	return h
+}
+
+func (h *HelicopterHandler) WithFleetStatusService(fleetStatusSvc helicopterFleetStatusProvider) *HelicopterHandler {
+	h.fleetStatus = fleetStatusSvc
+	return h
+}
+
+func (h *HelicopterHandler) WithMCFService(svc mcfPendingChecker) *HelicopterHandler {
+	h.mcfSvc = svc
+	return h
+}
+
+func (h *HelicopterHandler) WithComplaintService(svc complaintGroundingLister) *HelicopterHandler {
+	h.complaintSvc = svc
+	return h
+}
+
+// latestFleetStatusByHelicopter returns, per helicopter id, that helicopter's
+// latest fleet status (nil map when no fleet status service is wired). Indexing a
+// missing/nil entry yields nil, which callers treat as "no fleet status".
+func (h *HelicopterHandler) latestFleetStatusByHelicopter(ctx context.Context, ids [][]byte) map[string]*fleetstatus.FleetStatus {
+	if h.fleetStatus == nil || len(ids) == 0 {
+		return nil
+	}
+	latest, err := h.fleetStatus.LatestByHelicopterIDs(ctx, ids)
+	if err != nil {
+		return nil
+	}
+	return latest
+}
+
+// applyHelicopterFleetStatus attaches the helicopter's latest fleet status data
+// to the resource: the full maintenance schedule set and the MCF-aware
+// operational status. Without a fleet status the default empty schedules are
+// kept and status is recomputed with MCF=false.
+func applyHelicopterFleetStatus(res *responsedto.HelicopterResource, row *helicopter.Helicopter, isInUse bool, groundReason string, mcfPending bool, fs *fleetstatus.FleetStatus) {
+	grounded := strings.TrimSpace(groundReason) != ""
+	if fs != nil {
+		res.Attributes.MaintenanceSchedules = fleetStatusMaintenanceSchedules(fs.MaintenanceSchedules)
+	}
+	res.Attributes.Status = row.DeriveStatus(helicopter.StatusInput{IsBook: isInUse, IsMCF: mcfPending, ComplaintGrounded: grounded})
+	if res.Attributes.Status == helicopter.StatusAOG {
+		res.Attributes.AOG = true
+		// A grounded helicopter is inactive, mirroring EnforceAOGInactive. Read-time
+		// grounding (open complaint / expired MEL) is not persisted in air_on_ground,
+		// so reflect the inactive state in the response regardless of the stored flag.
+		res.Attributes.IsActive = false
+		if !row.AirOnGround {
+			res.Attributes.AOGReason = groundReason
+		}
+	}
+}
+
+// helicopterResourceWithSchedules builds a single helicopter resource enriched
+// with its latest fleet status (maintenance schedules + MCF-aware status).
+func (h *HelicopterHandler) helicopterResourceWithSchedules(ctx context.Context, row *helicopter.Helicopter, isInUse bool) responsedto.HelicopterResource {
+	res := h.helicopterResource(ctx, row, isInUse)
+	fs := h.latestFleetStatusByHelicopter(ctx, [][]byte{row.ID})[string(row.ID)]
+	groundReason := groundingReasonHelicopterSet(ctx, h.complaintSvc, [][]byte{row.ID}, time.Now().UTC())[string(row.ID)]
+	mcfPending := mcfPendingHelicopterSet(ctx, h.mcfSvc, [][]byte{row.ID})[string(row.ID)]
+	applyHelicopterFleetStatus(&res, row, isInUse, groundReason, mcfPending, fs)
+	return res
+}
+
+func (h *HelicopterHandler) writeHelicopterWriteServiceError(c *fiber.Ctx, err error) error {
+	var writeErr *appservice.HelicopterWriteError
+	if !errors.As(err, &writeErr) {
+		return h.writeHelicopterServiceError(c, "HelicopterHandler.CreateDetailed", err)
+	}
+	switch writeErr.Status {
+	case fiber.StatusNotFound, fiber.StatusConflict, fiber.StatusUnprocessableEntity, fiber.StatusAccepted, fiber.StatusUnauthorized:
+		errs := []jsonapi.ErrorObject{{
+			Title:  writeErr.Title,
+			Detail: writeErr.Detail,
+		}}
+		if strings.TrimSpace(writeErr.Pointer) != "" {
+			errs[0].Source = &jsonapi.ErrorSource{Pointer: writeErr.Pointer}
+		}
+		return writeHelicopterErrors(c, writeErr.Status, errs)
+	default:
+		return h.writeHelicopterServiceError(c, "HelicopterHandler.CreateDetailed", err)
+	}
+}
+
+func (h *HelicopterHandler) writeHelicopterServiceError(c *fiber.Ctx, operation string, err error) error {
+	mapped := apperrorsx.Translate(apperrorsx.ModuleHelicopter, err)
+	if mapped != nil && mapped.Code != apperrorsx.CodeInternalServerError {
+		logHelicopterServiceError(c, operation, mapped.Status, mapped.Code, mapped.ErrorCode, err)
+		return apperrorsx.Write(c, mapped)
+	}
+
+	logHelicopterServiceError(c, operation, fiber.StatusInternalServerError, apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode, err)
+	appErr := apperrorsx.New(apperrorsx.ErrInternal)
+	appErr.Message = "an internal error occurred"
+	return apperrorsx.Write(c, appErr)
+}
+
+func (h *HelicopterHandler) createHelicopterWithService(c *fiber.Ctx, svc helicopterDetailedWriter) bool {
+	var req requestdto.HelicopterCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		_ = apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrHelicopterInvalidJSON))
+		return true
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, errs)
+		return true
+	}
+
+	designation := strings.TrimSpace(req.Data.Attributes.Designation)
+	identifierInput := normalizeHelicopterIdentifier(req.Data.Attributes.Identifier)
+	heliType := strings.TrimSpace(req.Data.Attributes.Type)
+	if designation == "" || identifierInput == "" || heliType == "" {
+		_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "designation, identifier, and type are required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+		return true
+	}
+
+	modelID := uuidv7.MustBytes()
+	fotoAttachmentID := []byte(nil)
+	if req.Data.Attributes.FileUUID != nil {
+		resolved, handled := h.resolveFotoAttachmentID(c, modelID, req.Data.Attributes.FileUUID, "Create failed")
+		if handled {
+			return true
+		}
+		fotoAttachmentID = resolved
+	}
+
+	var accessToken string
+	if sessionVerifier, ok := h.pinVerifier.(helicopterPINSessionVerifier); ok {
+		for _, candidate := range appservice.CookieValues(c.Get(fiber.HeaderCookie), sessionVerifier.AccessCookieName()) {
+			if _, err := sessionVerifier.ParseAccessTokenSessionID(c.UserContext(), candidate); err == nil {
+				accessToken = candidate
+				break
+			}
+		}
+	}
+	res, err := svc.CreateDetailed(c.UserContext(), appservice.HelicopterCreateInput{
+		ID:               modelID,
+		Designation:      designation,
+		Identifier:       identifierInput,
+		Type:             heliType,
+		SortKey:          cloneIntPointer(req.Data.Attributes.SortKey),
+		Engine1:          strings.TrimSpace(stringOrDefault(req.Data.Attributes.Engine1, "")),
+		Engine2:          strings.TrimSpace(stringOrDefault(req.Data.Attributes.Engine2, "")),
+		Consumption:      floatOrDefault(req.Data.Attributes.Consumption, 0),
+		NR1:              boolOrDefault(req.Data.Attributes.NR1, false),
+		NR2:              boolOrDefault(req.Data.Attributes.NR2, false),
+		LH:               boolOrDefault(req.Data.Attributes.LH, false),
+		RH:               boolOrDefault(req.Data.Attributes.RH, false),
+		MGB:              boolOrDefault(req.Data.Attributes.MGB, false),
+		IGB:              boolOrDefault(req.Data.Attributes.IGB, false),
+		TGB:              boolOrDefault(req.Data.Attributes.TGB, false),
+		UTCOffset:        intOrDefault(req.Data.Attributes.UTCOffset, 0),
+		FotoAttachmentID: fotoAttachmentID,
+		Dry:              boolOrDefault(req.Data.Attributes.Dry, false),
+		AirOnGround:      boolOrDefault(req.Data.Attributes.AOG, false),
+		AOGReason:        strings.TrimSpace(stringOrDefault(req.Data.Attributes.AOGReason, "")),
+		Note:             strings.TrimSpace(stringOrDefault(req.Data.Attributes.Note, "")),
+		IsActive:         boolOrDefault(req.Data.Attributes.IsActive, true),
+		ActorUserID:      actorUserID(c),
+		PINVerifier:      h.pinVerifier,
+		PINToken:         strings.TrimSpace(c.Get(pinVerificationHeader)),
+		AccessToken:      accessToken,
+	})
+	if err != nil {
+		_ = h.writeHelicopterWriteServiceError(c, err)
+		return true
+	}
+	if len(res.PreviousFotoAttachmentID) == 16 {
+		_ = syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, res.PreviousFotoAttachmentID, res.Row.FotoAttachmentID, actorUserID(c))
+	}
+	if res.Row != nil && res.Row.AirOnGround {
+		on := true
+		h.recordManualAOG(c, res.Row, &on)
+	}
+	_ = response.Write(c, fiber.StatusCreated, h.helicopterResourceWithSchedules(c.UserContext(), res.Row, res.IsInUse))
+	return true
+}
+
+func (h *HelicopterHandler) updateHelicopterWithService(c *fiber.Ctx, svc helicopterDetailedWriter) bool {
+	idStr := strings.TrimSpace(c.Params("id"))
+	id, err := uuidv7.ParseString(idStr)
+	if err != nil {
+		_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+		return true
+	}
+
+	var req requestdto.HelicopterUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		_ = writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+		return true
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, errs)
+		return true
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+		return true
+	}
+	if req.Data.ID != idStr {
+		_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path id",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+		return true
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Designation == nil && attrs.Identifier == nil && attrs.Type == nil && !attrs.SortKey.Set && attrs.Engine1 == nil &&
+		attrs.Engine2 == nil && attrs.Consumption == nil && attrs.NR1 == nil && attrs.NR2 == nil && attrs.LH == nil && attrs.RH == nil &&
+		attrs.MGB == nil && attrs.IGB == nil && attrs.TGB == nil && attrs.UTCOffset == nil && attrs.FileUUID == nil &&
+		attrs.Dry == nil && attrs.AOG == nil && attrs.AOGReason == nil && attrs.Note == nil && attrs.IsActive == nil {
+		_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+		return true
+	}
+
+	var fotoAttachmentID []byte
+	fotoAttachmentSet := false
+	if attrs.FileUUID != nil {
+		fotoAttachmentSet = true
+		if hasBlankOptionalString(attrs.FileUUID) {
+			fotoAttachmentID = nil
+		} else {
+			resolved, handled := h.resolveExistingFotoAttachmentOrFileID(c, id, attrs.FileUUID, "Update failed")
+			if handled {
+				return true
+			}
+			fotoAttachmentID = resolved
+		}
+	}
+
+	var accessToken string
+	if sessionVerifier, ok := h.pinVerifier.(helicopterPINSessionVerifier); ok {
+		for _, candidate := range appservice.CookieValues(c.Get(fiber.HeaderCookie), sessionVerifier.AccessCookieName()) {
+			if _, err := sessionVerifier.ParseAccessTokenSessionID(c.UserContext(), candidate); err == nil {
+				accessToken = candidate
+				break
+			}
+		}
+	}
+	sortKeyPatch := helicopter.SortKeyPatch{Set: attrs.SortKey.Set}
+	if attrs.SortKey.Set && attrs.SortKey.Valid {
+		v := attrs.SortKey.Value
+		sortKeyPatch.Value = &v
+	}
+
+	res, err := svc.UpdateDetailed(c.UserContext(), appservice.HelicopterUpdateInput{
+		ID:                id,
+		Designation:       attrs.Designation,
+		Identifier:        attrs.Identifier,
+		Type:              attrs.Type,
+		SortKey:           sortKeyPatch,
+		Engine1:           attrs.Engine1,
+		Engine2:           attrs.Engine2,
+		Consumption:       attrs.Consumption,
+		NR1:               attrs.NR1,
+		NR2:               attrs.NR2,
+		LH:                attrs.LH,
+		RH:                attrs.RH,
+		MGB:               attrs.MGB,
+		IGB:               attrs.IGB,
+		TGB:               attrs.TGB,
+		UTCOffset:         attrs.UTCOffset,
+		FotoAttachmentID:  fotoAttachmentID,
+		FotoAttachmentSet: fotoAttachmentSet,
+		Dry:               attrs.Dry,
+		AirOnGround:       attrs.AOG,
+		AOGReason:         attrs.AOGReason,
+		Note:              attrs.Note,
+		IsActive:          attrs.IsActive,
+		ActorUserID:       actorUserID(c),
+		PINVerifier:       h.pinVerifier,
+		PINToken:          strings.TrimSpace(c.Get(pinVerificationHeader)),
+		AccessToken:       accessToken,
+	})
+	if err != nil {
+		_ = h.writeHelicopterWriteServiceError(c, err)
+		return true
+	}
+	if err := syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, res.PreviousFotoAttachmentID, res.Row.FotoAttachmentID, actorUserID(c)); err != nil {
+		_ = writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+		return true
+	}
+	h.recordManualAOG(c, res.Row, attrs.AOG)
+	_ = response.Write(c, fiber.StatusOK, h.helicopterResourceWithSchedules(c.UserContext(), res.Row, res.IsInUse))
+	return true
+}
+
+// CreateHelicopter godoc
+// @Summary Create helicopter
+// @Description Create a helicopter configuration row.
+// @Tags Facility - Helicopters
+// @Accept json
+// @Produce json
+// @Param request body requestdto.HelicopterCreateRequest true "JSON:API Helicopter create request"
+// @Success 201 {object} responsedto.HelicopterResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/helicopters/create [post]
+func (h *HelicopterHandler) Create(c *fiber.Ctx) error {
+	svc, ok := h.svc.(helicopterDetailedWriter)
+	if !ok {
+		return writeHelicopterErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Create failed",
+			Detail: "helicopter service is not configured",
+		}})
+	}
+	if h.createHelicopterWithService(c, svc) {
+		return nil
+	}
+
+	var req requestdto.HelicopterCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrHelicopterInvalidJSON))
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	designation := strings.TrimSpace(req.Data.Attributes.Designation)
+	identifierInput := normalizeHelicopterIdentifier(req.Data.Attributes.Identifier)
+	heliType := strings.TrimSpace(req.Data.Attributes.Type)
+	if designation == "" || identifierInput == "" || heliType == "" {
+		return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "designation, identifier, and type are required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	exists, err := h.svc.ExistsByIdentifier(c.UserContext(), identifierInput, nil)
+	if err != nil {
+		return h.writeHelicopterServiceError(c, "HelicopterHandler.Create.ExistsByIdentifier", err)
+	}
+	if exists {
+		return writeHelicopterErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+			Status: "409",
+			Title:  "Conflict",
+			Detail: "Serial number already exists",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/identifier"},
+		}})
+	}
+
+	model := &helicopter.Helicopter{
+		ID:               uuidv7.MustBytes(),
+		Designation:      designation,
+		Identifier:       identifierInput,
+		ReportSequence:   0,
+		Type:             heliType,
+		SortKey:          cloneIntPointer(req.Data.Attributes.SortKey),
+		Engine1:          strings.TrimSpace(stringOrDefault(req.Data.Attributes.Engine1, "")),
+		Engine2:          strings.TrimSpace(stringOrDefault(req.Data.Attributes.Engine2, "")),
+		Consumption:      floatOrDefault(req.Data.Attributes.Consumption, 0),
+		NR1:              boolOrDefault(req.Data.Attributes.NR1, false),
+		NR2:              boolOrDefault(req.Data.Attributes.NR2, false),
+		LH:               boolOrDefault(req.Data.Attributes.LH, false),
+		RH:               boolOrDefault(req.Data.Attributes.RH, false),
+		MGB:              boolOrDefault(req.Data.Attributes.MGB, false),
+		IGB:              boolOrDefault(req.Data.Attributes.IGB, false),
+		TGB:              boolOrDefault(req.Data.Attributes.TGB, false),
+		UTCOffset:        intOrDefault(req.Data.Attributes.UTCOffset, 0),
+		FotoAttachmentID: nil,
+		Dry:              boolOrDefault(req.Data.Attributes.Dry, false),
+		AirOnGround:      boolOrDefault(req.Data.Attributes.AOG, false),
+		AOGReason:        strings.TrimSpace(stringOrDefault(req.Data.Attributes.AOGReason, "")),
+		Note:             strings.TrimSpace(stringOrDefault(req.Data.Attributes.Note, "")),
+		IsActive:         boolOrDefault(req.Data.Attributes.IsActive, true),
+		CreatedBy:        actorUserID(c),
+		UpdatedBy:        actorUserID(c),
+	}
+	if errObj := validateAOGReason(model.AirOnGround, model.AOGReason); errObj != nil {
+		return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	if model.AirOnGround {
+		if h.requireAOGPINVerification(c) {
+			return nil
+		}
+	}
+	if req.Data.Attributes.FileUUID != nil {
+		fotoAttachmentID, handled := h.resolveFotoAttachmentID(c, model.ID, req.Data.Attributes.FileUUID, "Create failed")
+		if handled {
+			return nil
+		}
+		model.FotoAttachmentID = fotoAttachmentID
+	}
+
+	if err := h.svc.Create(c.UserContext(), model); err != nil {
+		return h.writeHelicopterServiceError(c, "HelicopterHandler.Create", err)
+	}
+	if len(model.FotoAttachmentID) == 16 {
+		if err := syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, nil, model.FotoAttachmentID, actorUserID(c)); err != nil {
+			return h.writeHelicopterServiceError(c, "HelicopterHandler.Create.Attachments", err)
+		}
+	}
+
+	isInUse, _ := h.svc.IsInUse(c.UserContext(), model.ID)
+	created, err := h.svc.GetByID(c.UserContext(), model.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, h.helicopterResourceWithSchedules(c.UserContext(), created, isInUse))
+	}
+	return response.Write(c, fiber.StatusCreated, h.helicopterResourceWithSchedules(c.UserContext(), model, isInUse))
+}
+
+// UpdateHelicopter godoc
+// @Summary Update helicopter (partial)
+// @Description Patch helicopter by ID.
+// @Tags Facility - Helicopters
+// @Accept json
+// @Produce json
+// @Param id path string true "Helicopter ID (UUIDv7)"
+// @Param request body requestdto.HelicopterUpdateRequest true "JSON:API Helicopter update request"
+// @Success 200 {object} responsedto.HelicopterResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Router /api/v1/helicopters/update/{id} [patch]
+func (h *HelicopterHandler) Update(c *fiber.Ctx) error {
+	svc, ok := h.svc.(helicopterDetailedWriter)
+	if !ok {
+		return writeHelicopterErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Update failed",
+			Detail: "helicopter service is not configured",
+		}})
+	}
+	if h.updateHelicopterWithService(c, svc) {
+		return nil
+	}
+
+	idStr := strings.TrimSpace(c.Params("id"))
+	id, err := uuidv7.ParseString(idStr)
+	if err != nil {
+		return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	var req requestdto.HelicopterUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != idStr {
+		return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path id",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Designation == nil && attrs.Identifier == nil && attrs.Type == nil && !attrs.SortKey.Set && attrs.Engine1 == nil &&
+		attrs.Engine2 == nil && attrs.Consumption == nil && attrs.NR1 == nil && attrs.NR2 == nil && attrs.LH == nil && attrs.RH == nil &&
+		attrs.MGB == nil && attrs.IGB == nil && attrs.TGB == nil && attrs.UTCOffset == nil && attrs.FileUUID == nil &&
+		attrs.Dry == nil && attrs.AOG == nil && attrs.AOGReason == nil && attrs.Note == nil && attrs.IsActive == nil {
+		return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeHelicopterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "helicopter not found",
+		}})
+	}
+	prevFotoAttachmentID := append([]byte(nil), existing.FotoAttachmentID...)
+	currentAOG := existing.AirOnGround
+
+	if attrs.Designation != nil {
+		v := strings.TrimSpace(*attrs.Designation)
+		if v == "" {
+			return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "designation cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/designation"},
+			}})
+		}
+		existing.Designation = v
+	}
+	if attrs.Identifier != nil {
+		raw := normalizeHelicopterIdentifier(*attrs.Identifier)
+		if raw == "" {
+			return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "identifier cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/identifier"},
+			}})
+		}
+
+		exists, existsErr := h.svc.ExistsByIdentifier(c.UserContext(), raw, existing.ID)
+		if existsErr != nil {
+			return writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Update failed",
+				Detail: existsErr.Error(),
+			}})
+		}
+		if exists {
+			return writeHelicopterErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "Conflict",
+				Detail: "Serial number already exists",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/identifier"},
+			}})
+		}
+
+		existing.Identifier = raw
+	}
+	if attrs.Type != nil {
+		v := strings.TrimSpace(*attrs.Type)
+		if v == "" {
+			return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "type cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/type"},
+			}})
+		}
+		existing.Type = v
+	}
+	sortKeyPatch := helicopter.SortKeyPatch{Set: attrs.SortKey.Set}
+	if attrs.SortKey.Set && attrs.SortKey.Valid {
+		v := attrs.SortKey.Value
+		sortKeyPatch.Value = &v
+	}
+	h.svc.ApplySortKeyPatch(existing, sortKeyPatch)
+	if attrs.Engine1 != nil {
+		existing.Engine1 = strings.TrimSpace(*attrs.Engine1)
+	}
+	if attrs.Engine2 != nil {
+		existing.Engine2 = strings.TrimSpace(*attrs.Engine2)
+	}
+	if attrs.Consumption != nil {
+		existing.Consumption = *attrs.Consumption
+	}
+	if attrs.NR1 != nil {
+		existing.NR1 = *attrs.NR1
+	}
+	if attrs.NR2 != nil {
+		existing.NR2 = *attrs.NR2
+	}
+	if attrs.LH != nil {
+		existing.LH = *attrs.LH
+	}
+	if attrs.RH != nil {
+		existing.RH = *attrs.RH
+	}
+	if attrs.MGB != nil {
+		existing.MGB = *attrs.MGB
+	}
+	if attrs.IGB != nil {
+		existing.IGB = *attrs.IGB
+	}
+	if attrs.TGB != nil {
+		existing.TGB = *attrs.TGB
+	}
+	if attrs.UTCOffset != nil {
+		existing.UTCOffset = *attrs.UTCOffset
+	}
+	if attrs.FileUUID != nil {
+		if hasBlankOptionalString(attrs.FileUUID) {
+			existing.FotoAttachmentID = nil
+		} else {
+			fotoAttachmentID, handled := h.resolveExistingFotoAttachmentOrFileID(c, existing.ID, attrs.FileUUID, "Update failed")
+			if handled {
+				return nil
+			}
+			existing.FotoAttachmentID = fotoAttachmentID
+		}
+	}
+	if attrs.Dry != nil {
+		existing.Dry = *attrs.Dry
+	}
+	if attrs.AOG != nil {
+		existing.AirOnGround = *attrs.AOG
+	}
+	if attrs.AOGReason != nil {
+		existing.AOGReason = strings.TrimSpace(*attrs.AOGReason)
+	}
+	if errObj := validateAOGReason(existing.AirOnGround, existing.AOGReason); errObj != nil {
+		return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	if attrs.AOG != nil && *attrs.AOG != currentAOG {
+		if h.requireAOGPINVerification(c) {
+			return nil
+		}
+	}
+	if attrs.Note != nil {
+		existing.Note = strings.TrimSpace(*attrs.Note)
+	}
+	if attrs.IsActive != nil {
+		existing.IsActive = *attrs.IsActive
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		appErr := mapHelicopterServiceErrorWithFallback(err, apperrorsx.ErrHelicopterUpdateFailed)
+		if appErr != nil && appErr.Code == apperrorsx.CodeHelicopterDuplicate {
+			appErr.Title = "Conflict"
+			appErr.Message = "Serial number already exists"
+			appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/identifier"}
+		}
+		return apperrorsx.Write(c, appErr)
+	}
+	if err := syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, prevFotoAttachmentID, existing.FotoAttachmentID, actorUserID(c)); err != nil {
+		return writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	isInUse, _ := h.svc.IsInUse(c.UserContext(), existing.ID)
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, h.helicopterResourceWithSchedules(c.UserContext(), updated, isInUse))
+	}
+	return response.Write(c, fiber.StatusOK, h.helicopterResourceWithSchedules(c.UserContext(), existing, isInUse))
+}
+
+// DeleteHelicopter godoc
+// @Summary Delete helicopter
+// @Tags Facility - Helicopters
+// @Produce json
+// @Param id path string true "Helicopter ID (UUIDv7)"
+// @Success 200 {object} jsonapi.Document
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Router /api/v1/helicopters/delete/{id} [delete]
+func (h *HelicopterHandler) Delete(c *fiber.Ctx) error {
+	idStr := strings.TrimSpace(c.Params("id"))
+	id, err := uuidv7.ParseString(idStr)
+	if err != nil {
+		return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+	existing, _ := h.svc.GetByID(c.UserContext(), id)
+	if existing == nil {
+		return writeHelicopterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "helicopter not found",
+		}})
+	}
+	var previousFotoAttachmentID []byte
+	previousFotoAttachmentID = append([]byte(nil), existing.FotoAttachmentID...)
+
+	if err := h.svc.Delete(c.UserContext(), id); err != nil {
+		return apperrorsx.Write(c, mapHelicopterServiceErrorWithFallback(err, apperrorsx.ErrHelicopterDeleteFailed))
+	}
+	if len(previousFotoAttachmentID) == 16 {
+		if err := syncAttachmentLifecycleClear(c.UserContext(), h.fileManager, previousFotoAttachmentID, actorUserID(c)); err != nil {
+			return writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Delete failed",
+				Detail: safeInternalDetail(),
+			}})
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "helicopter_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// GenerateHelicopterNextReportNumber godoc
+// @Summary Generate next helicopter report number
+// @Description Returns report number format <identifier>-NNNN (example: SN0901-0001). The identifier is used as the report-code prefix and the numeric suffix is auto-incremented by backend per helicopter.
+// @Tags Facility - Helicopters
+// @Produce json
+// @Param id path string true "Helicopter ID (UUIDv7)"
+// @Success 200 {object} responsedto.HelicopterNextReportNumberResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/helicopters/{id}/reports/next-number [post]
+func (h *HelicopterHandler) NextReportNumber(c *fiber.Ctx) error {
+	idStr := strings.TrimSpace(c.Params("id"))
+	id, err := uuidv7.ParseString(idStr)
+	if err != nil {
+		return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	reportNumber, sequence, err := h.svc.NextReportNumber(c.UserContext(), id)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeHelicopterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "helicopter not found",
+			}})
+		}
+		return writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Generate failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeHelicopterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "helicopter not found",
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, responsedto.HelicopterNextReportNumberResponse{
+		Data: responsedto.HelicopterNextReportNumberResource{
+			Type: "helicopter_report_number",
+			ID:   idStr,
+			Attributes: responsedto.HelicopterNextReportNumberAttributes{
+				Identifier:   existing.Identifier,
+				Sequence:     sequence,
+				ReportNumber: reportNumber,
+			},
+		},
+	})
+}
+
+// GetHelicopterByID godoc
+// @Summary Get helicopter by ID
+// @Tags Facility - Helicopters
+// @Produce json
+// @Param id path string true "Helicopter ID (UUIDv7)"
+// @Success 200 {object} responsedto.HelicopterResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Router /api/v1/helicopters/get/{id} [get]
+func (h *HelicopterHandler) Get(c *fiber.Ctx) error {
+	idStr := strings.TrimSpace(c.Params("id"))
+	id, err := uuidv7.ParseString(idStr)
+	if err != nil {
+		return writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	model, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || model == nil {
+		return writeHelicopterErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "helicopter not found",
+		}})
+	}
+
+	isInUse, _ := h.svc.IsInUse(c.UserContext(), model.ID)
+	return response.Write(c, fiber.StatusOK, h.helicopterResourceWithSchedules(c.UserContext(), model, isInUse))
+}
+
+// ListHelicopters godoc
+// @Summary List helicopters
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: designation, -designation, sortkey, -sortkey.
+// @Tags Facility - Helicopters
+// @Produce json
+// @Param filter[search] query string false "Search by designation/identifier/type"
+// @Param filter[status] query string false "Filter by operational status; comma-separated for multiple (e.g. available,booked). Values: available, booked, aog, mcf"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} responsedto.HelicopterListResponse
+// @Router /api/v1/helicopters/get-all [get]
+func (h *HelicopterHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("filter[name]")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 1)
+	pageSize := parseIntDefault(c.Query("page[size]"), 20)
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	statuses, err := parseHelicopterStatusFilter(c.Query("filter[status]"))
+	if err != nil {
+		return writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid status filter",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	var groundedIDs [][]byte
+	if len(statuses) > 0 {
+		groundedIDs = groundedHelicopterIDs(c.UserContext(), h.complaintSvc, time.Now().UTC())
+	}
+	rows, total, err := h.svc.List(c.UserContext(), filter, statuses, sort, 0, 0, groundedIDs)
+	if err != nil {
+		return writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	ids := make([][]byte, 0, len(rows))
+	for i := range rows {
+		ids = append(ids, rows[i].ID)
+	}
+	inUseByID, err := h.svc.InUseByAircraftIDs(c.UserContext(), ids)
+	if err != nil {
+		return writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	fsByID := h.latestFleetStatusByHelicopter(c.UserContext(), ids)
+	groundReasons := groundingReasonHelicopterSet(c.UserContext(), h.complaintSvc, ids, time.Now().UTC())
+	mcfPending := mcfPendingHelicopterSet(c.UserContext(), h.mcfSvc, ids)
+	data := make([]responsedto.HelicopterResource, 0, len(rows))
+	for i := range rows {
+		inUse := inUseByID[string(rows[i].ID)]
+		res := h.helicopterResource(c.UserContext(), &rows[i], inUse)
+		applyHelicopterFleetStatus(&res, &rows[i], inUse, groundReasons[string(rows[i].ID)], mcfPending[string(rows[i].ID)], fsByID[string(rows[i].ID)])
+		data = append(data, res)
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListHelicoptersDatatable godoc
+// @Summary List helicopters (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags Facility - Helicopters
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Param status query string false "Filter by operational status; comma-separated for multiple (e.g. available,booked). Values: available, booked, aog, mcf"
+// @Success 200 {object} responsedto.HelicopterDataTableResponse
+// @Router /api/v1/helicopters/get-all/dt [get]
+func (h *HelicopterHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	statuses, err := parseHelicopterStatusFilter(c.Query("status"))
+	if err != nil {
+		return writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid status filter",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	var groundedIDs [][]byte
+	if len(statuses) > 0 {
+		groundedIDs = groundedHelicopterIDs(c.UserContext(), h.complaintSvc, time.Now().UTC())
+	}
+	rows, total, err := h.svc.List(c.UserContext(), search, statuses, "", length, start, groundedIDs)
+	if err != nil {
+		return writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	ids := make([][]byte, 0, len(rows))
+	for i := range rows {
+		ids = append(ids, rows[i].ID)
+	}
+	inUseByID, err := h.svc.InUseByAircraftIDs(c.UserContext(), ids)
+	if err != nil {
+		return writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	fsByID := h.latestFleetStatusByHelicopter(c.UserContext(), ids)
+	groundReasons := groundingReasonHelicopterSet(c.UserContext(), h.complaintSvc, ids, time.Now().UTC())
+	mcfPending := mcfPendingHelicopterSet(c.UserContext(), h.mcfSvc, ids)
+	data := make([]responsedto.HelicopterResource, 0, len(rows))
+	for i := range rows {
+		inUse := inUseByID[string(rows[i].ID)]
+		res := h.helicopterResource(c.UserContext(), &rows[i], inUse)
+		applyHelicopterFleetStatus(&res, &rows[i], inUse, groundReasons[string(rows[i].ID)], mcfPending[string(rows[i].ID)], fsByID[string(rows[i].ID)])
+		data = append(data, res)
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func (h *HelicopterHandler) helicopterResource(ctx context.Context, row *helicopter.Helicopter, isInUse bool) responsedto.HelicopterResource {
+	return helicopterResourceWithStorage(ctx, h.storage, h.reserveAc, row, isInUse)
+}
+
+func helicopterResource(h *helicopter.Helicopter) responsedto.HelicopterResource {
+	return helicopterResourceWithStorage(context.Background(), nil, nil, h, false)
+}
+
+func helicopterResourceWithStorage(ctx context.Context, storage fileManagerDownloadURLStorage, reserveAcSvc helicopterLastDailyInspectionProvider, row *helicopter.Helicopter, isInUse bool) responsedto.HelicopterResource {
+	id, _ := uuidv7.BytesToString(row.ID)
+	var foto *shareddto.HelicopterFoto
+	fotoUUID := idString(row.FotoAttachmentID)
+	fotoDownloadURL := ""
+	fotoThumbnailURL := ""
+	var fotoOriginalSizeBytes *int64
+	if row.FotoAttachment != nil && row.FotoAttachment.File != nil {
+		asset := resolveFileManagerDownloadURLs(ctx, storage, row.FotoAttachment.File)
+		fotoDownloadURL = strings.TrimSpace(asset.OriginalURL)
+		fotoThumbnailURL = strings.TrimSpace(asset.ThumbnailURL)
+		fotoOriginalSizeBytes = int64Ptr(asset.OriginalSizeBytes)
+	}
+	if fotoUUID != "" || fotoDownloadURL != "" || fotoThumbnailURL != "" || fotoOriginalSizeBytes != nil {
+		foto = &shareddto.HelicopterFoto{
+			UUID:                 fotoUUID,
+			DownloadURL:          fotoDownloadURL,
+			ThumbnailDownloadURL: fotoThumbnailURL,
+			OriginalSizeBytes:    fotoOriginalSizeBytes,
+		}
+	}
+	return responsedto.HelicopterResource{
+		Type: "helicopter",
+		ID:   id,
+		Attributes: responsedto.HelicopterAttributes{
+			Designation:         row.Designation,
+			Identifier:          row.Identifier,
+			Type:                row.Type,
+			SortKey:             cloneIntPointer(row.SortKey),
+			Engine1:             row.Engine1,
+			Engine2:             row.Engine2,
+			Consumption:         row.Consumption,
+			NR1:                 row.NR1,
+			NR2:                 row.NR2,
+			LH:                  row.LH,
+			RH:                  row.RH,
+			MGB:                 row.MGB,
+			IGB:                 row.IGB,
+			TGB:                 row.TGB,
+			UTCOffset:           row.UTCOffset,
+			Foto:                foto,
+			Dry:                 row.Dry,
+			AOG:                 row.AirOnGround,
+			IsInUse:             isInUse,
+			Status:              row.DeriveStatus(helicopter.StatusInput{IsBook: isInUse}),
+			AOGReason:           row.AOGReason,
+			Note:                row.Note,
+			IsActive:            row.IsActive,
+			CreatedBy:           helicopterAuditUser(row.CreatedBy, row.CreatedByName),
+			CreatedAt:           row.CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:           helicopterAuditUser(row.UpdatedBy, row.UpdatedByName),
+			UpdatedAt:           row.UpdatedAt.UTC().Format(time.RFC3339),
+			LastDailyInspection: helicopterLastDailyInspectionResource(ctx, reserveAcSvc, row.ID),
+			// Default to the full empty inspection set; handlers with a fleet
+			// status service enrich this with the helicopter's actual schedules.
+			MaintenanceSchedules: fleetStatusMaintenanceSchedules(nil),
+		},
+	}
+}
+
+// parseHelicopterStatusFilter parses a comma-separated status filter (e.g.
+// "available,booked") into a validated, de-duplicated slice. Empty entries are
+// ignored; an empty input yields a nil slice (no filtering). Unrecognised
+// values produce an error so the caller can reject the request.
+func parseHelicopterStatusFilter(raw string) ([]string, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return nil, nil
+	}
+	out := make([]string, 0)
+	seen := make(map[string]struct{})
+	invalid := make([]string, 0)
+	for _, part := range strings.Split(raw, ",") {
+		s := strings.ToLower(strings.TrimSpace(part))
+		if s == "" {
+			continue
+		}
+		if !helicopter.IsValidStatus(s) {
+			invalid = append(invalid, s)
+			continue
+		}
+		if _, ok := seen[s]; ok {
+			continue
+		}
+		seen[s] = struct{}{}
+		out = append(out, s)
+	}
+	if len(invalid) > 0 {
+		return nil, fmt.Errorf("unknown status value(s): %s", strings.Join(invalid, ", "))
+	}
+	return out, nil
+}
+
+func helicopterLastDailyInspectionResource(ctx context.Context, provider helicopterLastDailyInspectionProvider, helicopterID []byte) *shareddto.HelicopterLastDailyInspection {
+	if provider == nil || len(helicopterID) != 16 {
+		return nil
+	}
+	lastDaily, err := provider.GetLastDailyInspectionSummaryByHelicopterID(ctx, helicopterID)
+	if err != nil || lastDaily == nil {
+		return nil
+	}
+	return &shareddto.HelicopterLastDailyInspection{
+		InspectionID: lastDaily.InspectionID,
+		Status:       lastDaily.Status,
+		Inspector: shareddto.HelicopterLastDailyInspector{
+			ID:        lastDaily.InspectorID,
+			Name:      lastDaily.InspectorName,
+			LicenseNo: lastDaily.InspectorLicenseNo,
+		},
+		Base: shareddto.HelicopterLastDailyBase{
+			ID:               lastDaily.BaseID,
+			BaseAbbreviation: lastDaily.BaseAbbreviation,
+			BaseName:         lastDaily.BaseName,
+			Type:             lastDaily.BaseType,
+		},
+		InspectedAt: lastDaily.InspectedAt.UTC().Format(time.RFC3339),
+		UTCTime:     lastDaily.InspectedAt.UTC().Format("15:04"),
+		InspectionFilesChecklist: shareddto.HelicopterInspectionFilesChecklist{
+			Completed: lastDaily.InspectionFilesChecklistCompleted,
+			Total:     lastDaily.InspectionFilesChecklistTotal,
+		},
+	}
+}
+
+func helicopterAuditUser(id []byte, name string) *shareddto.HelicopterAuditUser {
+	return &shareddto.HelicopterAuditUser{
+		ID:   idString(id),
+		Name: strings.TrimSpace(name),
+	}
+}
+
+func (h *HelicopterHandler) resolveFotoAttachmentID(
+	c *fiber.Ctx,
+	helicopterID []byte,
+	rawFileUUID *string,
+	errorTitle string,
+) ([]byte, bool) {
+	return h.resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+		FileManager: h.fileManager,
+
+		RawFileID: rawFileUUID,
+
+		FileField:    "file_uuid",
+		RequireValue: false,
+
+		RefType:  helicopterPhotoAttachmentRefType,
+		RefID:    idString(helicopterID),
+		Category: ptrString(helicopterPhotoAttachmentCategory),
+
+		IsPrimary: true,
+		ActorID:   actorUserID(c),
+
+		ValidateAttachmentExists: false,
+	}, errorTitle)
+}
+
+func (h *HelicopterHandler) resolveExistingFotoAttachmentOrFileID(
+	c *fiber.Ctx,
+	helicopterID []byte,
+	rawUUID *string,
+	errorTitle string,
+) ([]byte, bool) {
+	if hasNonEmptyOptionalString(rawUUID) && h.fileManager != nil {
+		candidateID, err := uuidv7.ParseString(strings.TrimSpace(*rawUUID))
+		if err == nil {
+			attachment, getErr := h.fileManager.GetAttachmentByID(c.UserContext(), candidateID)
+			if getErr != nil {
+				_ = writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+					Status: "400",
+					Title:  errorTitle,
+					Detail: getErr.Error(),
+				}})
+				return nil, true
+			}
+			if attachment != nil {
+				return candidateID, false
+			}
+		}
+	}
+	return h.resolveFotoAttachmentID(c, helicopterID, rawUUID, errorTitle)
+}
+
+func (h *HelicopterHandler) resolveAttachmentIDFromInput(
+	c *fiber.Ctx,
+	params attachmentresolver.Params,
+	errorTitle string,
+) ([]byte, bool) {
+	attachmentID, err := attachmentresolver.Resolve(c.UserContext(), params)
+	if err == nil {
+		return attachmentID, false
+	}
+
+	var resolveErr *attachmentresolver.ResolveError
+	if errors.As(err, &resolveErr) {
+		switch resolveErr.Code {
+		case attachmentresolver.ErrorInvalidAttachmentUUID:
+			_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("%s is invalid UUID", fieldOrDefault(resolveErr.AttachmentField, "attachment_id")),
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/" + fieldOrDefault(resolveErr.AttachmentField, "attachment_id")},
+			}})
+			return nil, true
+		case attachmentresolver.ErrorInvalidFileUUID:
+			_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("%s is invalid UUID", fieldOrDefault(resolveErr.FileField, "file_id")),
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/" + fieldOrDefault(resolveErr.FileField, "file_id")},
+			}})
+			return nil, true
+		case attachmentresolver.ErrorAttachmentNotFound:
+			_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("%s not found", fieldOrDefault(resolveErr.AttachmentField, "attachment_id")),
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/" + fieldOrDefault(resolveErr.AttachmentField, "attachment_id")},
+			}})
+			return nil, true
+		case attachmentresolver.ErrorRequireValue:
+			_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("%s or %s is required", fieldOrDefault(resolveErr.AttachmentField, "attachment_id"), fieldOrDefault(resolveErr.FileField, "file_id")),
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+			}})
+			return nil, true
+		case attachmentresolver.ErrorCannotResolveFromFile:
+			_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("cannot resolve attachment from %s", fieldOrDefault(resolveErr.FileField, "file_id")),
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/" + fieldOrDefault(resolveErr.FileField, "file_id")},
+			}})
+			return nil, true
+		case attachmentresolver.ErrorFileNotReadyForAttachment:
+			_ = writeHelicopterErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: fmt.Sprintf("%s is not ready yet; wait for file.updated SSE event", fieldOrDefault(resolveErr.FileField, "file_id")),
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/" + fieldOrDefault(resolveErr.FileField, "file_id")},
+			}})
+			return nil, true
+		case attachmentresolver.ErrorFileManagerUnavailable:
+			_ = writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  errorTitle,
+				Detail: resolveErr.Error(),
+			}})
+			return nil, true
+		}
+	}
+
+	_ = writeHelicopterErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+		Status: "400",
+		Title:  errorTitle,
+		Detail: safeInternalDetail(),
+	}})
+	return nil, true
+}
+
+func (h *HelicopterHandler) requireAOGPINVerification(c *fiber.Ctx) bool {
+	if h.pinVerifier == nil {
+		_ = writeHelicopterErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "auth service not configured",
+		}})
+		return true
+	}
+
+	userID := actorUserID(c)
+	if len(userID) == 0 {
+		_ = writeHelicopterErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+		return true
+	}
+
+	token := c.Get(pinVerificationHeader)
+	if sessionVerifier, ok := h.pinVerifier.(helicopterPINSessionVerifier); ok {
+		sessionID := ""
+		for _, accessToken := range appservice.CookieValues(c.Get(fiber.HeaderCookie), sessionVerifier.AccessCookieName()) {
+			sid, err := sessionVerifier.ParseAccessTokenSessionID(c.UserContext(), accessToken)
+			if err == nil {
+				sessionID = sid
+				break
+			}
+		}
+		if sessionID == "" {
+			_ = writeHelicopterErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+				Status: "401",
+				Title:  "Unauthorized",
+				Detail: "invalid or expired token",
+			}})
+			return true
+		}
+
+		if err := sessionVerifier.ConsumeSecurityPINActionTokenInSession(c.UserContext(), userID, sharedconst.PinActionHelicopterAOGChange, token, sessionID); err != nil {
+			_ = writeHelicopterErrors(c, fiber.StatusAccepted, []jsonapi.ErrorObject{{
+				Status: "202",
+				Title:  "PIN verification required",
+				Detail: "valid PIN action token is required",
+				Source: &jsonapi.ErrorSource{Pointer: "/headers/X-PIN-Verification-Token"},
+			}})
+			return true
+		}
+		return false
+	}
+
+	if err := h.pinVerifier.ConsumeSecurityPINActionToken(c.UserContext(), userID, sharedconst.PinActionHelicopterAOGChange, token); err != nil {
+		_ = writeHelicopterErrors(c, fiber.StatusAccepted, []jsonapi.ErrorObject{{
+			Status: "202",
+			Title:  "PIN verification required",
+			Detail: "valid PIN action token is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/headers/X-PIN-Verification-Token"},
+		}})
+		return true
+	}
+	return false
+}
+
+func boolOrDefault(v *bool, def bool) bool {
+	if v == nil {
+		return def
+	}
+	return *v
+}
+
+func intOrDefault(v *int, def int) int {
+	if v == nil {
+		return def
+	}
+	return *v
+}
+
+func floatOrDefault(v *float64, def float64) float64 {
+	if v == nil {
+		return def
+	}
+	return *v
+}
+
+func stringOrDefault(v *string, def string) string {
+	if v == nil {
+		return def
+	}
+	return *v
+}
+
+func validateAOGReason(aog bool, reason string) *jsonapi.ErrorObject {
+	if !aog {
+		return nil
+	}
+	if strings.TrimSpace(reason) != "" {
+		return nil
+	}
+	return &jsonapi.ErrorObject{
+		Status: "422",
+		Title:  "AOG reason required",
+		Detail: "AOG reason must be provided when AOG is active (`aog=true`).",
+		Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/aog_reason"},
+	}
+}
+
+func int64Ptr(v int64) *int64 {
+	return &v
+}
+
+func cloneIntPointer(v *int) *int {
+	if v == nil {
+		return nil
+	}
+	out := *v
+	return &out
+}
+
+func normalizeHelicopterIdentifier(raw string) string {
+	return strings.ToUpper(strings.TrimSpace(raw))
+}
+
+func writeHelicopterErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		// Keep JSON:API error.status fully synchronized with HTTP status from handler.
+		e.Status = statusStr
+		if strings.TrimSpace(e.Code) == "" || strings.TrimSpace(e.ErrorCode) == "" {
+			code, errorCode := inferHelicopterErrorCode(status, e.Title, e.Detail)
+			if strings.TrimSpace(e.Code) == "" {
+				e.Code = code
+			}
+			if strings.TrimSpace(e.ErrorCode) == "" {
+				e.ErrorCode = errorCode
+			}
+		}
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func logHelicopterServiceError(c *fiber.Ctx, operation string, status int, code, errorCode string, err error) {
+	requestID := requestIDFromCtx(c)
+	args := []any{
+		slog.String("request_id", requestID),
+		slog.String("operation", strings.TrimSpace(operation)),
+		slog.Int("status", status),
+		slog.String("code", strings.TrimSpace(code)),
+		slog.String("error_code", strings.TrimSpace(errorCode)),
+		slog.String("path", c.Path()),
+		slog.Any("cause", err),
+	}
+	if status >= fiber.StatusInternalServerError {
+		slog.ErrorContext(c.UserContext(), "helicopter service error", args...)
+		return
+	}
+	slog.WarnContext(c.UserContext(), "helicopter service error", args...)
+}
+
+func mapHelicopterServiceErrorWithFallback(err error, fallback apperrorsx.Def) *apperrorsx.AppError {
+	mapped := apperrorsx.Translate(apperrorsx.ModuleHelicopter, err)
+	if mapped == nil {
+		return apperrorsx.New(fallback).WithCause(err)
+	}
+
+	switch mapped.Code {
+	case apperrorsx.CodeHelicopterDuplicate,
+		apperrorsx.CodeHelicopterRelationDelete,
+		apperrorsx.CodeHelicopterInvalidPayload,
+		apperrorsx.CodeHelicopterNotFound:
+		return mapped
+	default:
+		return apperrorsx.New(fallback).WithCause(err)
+	}
+}
+
+func inferHelicopterErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+
+	switch status {
+	case fiber.StatusAccepted:
+		return apperrorsx.CodeHelicopterPinVerificationRequired, apperrorsx.ErrHelicopterPinVerificationRequired.ErrorCode
+	case fiber.StatusUnauthorized:
+		if strings.Contains(lowerDetail, "token") {
+			return apperrorsx.CodeTokenInvalid, apperrorsx.ErrTokenInvalid.ErrorCode
+		}
+		return apperrorsx.CodeHelicopterUnauthorized, apperrorsx.ErrHelicopterUnauthorized.ErrorCode
+	case fiber.StatusNotFound:
+		return apperrorsx.CodeHelicopterNotFound, apperrorsx.ErrHelicopterNotFound.ErrorCode
+	case fiber.StatusConflict:
+		if strings.Contains(lowerDetail, "relation") || strings.Contains(lowerDetail, "referenced") {
+			return apperrorsx.CodeHelicopterRelationDelete, apperrorsx.ErrHelicopterRelationDelete.ErrorCode
+		}
+		return apperrorsx.CodeHelicopterDuplicate, apperrorsx.ErrHelicopterDuplicate.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		if strings.Contains(lowerDetail, "type is oneof") || strings.Contains(lowerDetail, "type must be one of") {
+			return apperrorsx.CodeHelicopterInvalidType, apperrorsx.ErrHelicopterInvalidType.ErrorCode
+		}
+		if strings.Contains(lowerDetail, "id is invalid uuid") {
+			return apperrorsx.CodeHelicopterInvalidID, apperrorsx.ErrHelicopterInvalidID.ErrorCode
+		}
+		if strings.Contains(lowerDetail, "id is required") {
+			return apperrorsx.CodeHelicopterIDRequired, apperrorsx.ErrHelicopterIDRequired.ErrorCode
+		}
+		if strings.Contains(lowerDetail, "id does not match path id") {
+			return apperrorsx.CodeHelicopterIDMismatch, apperrorsx.ErrHelicopterIDMismatch.ErrorCode
+		}
+		if strings.Contains(lowerDetail, "at least one attribute must be provided") {
+			return apperrorsx.CodeHelicopterAttributesRequired, apperrorsx.ErrHelicopterAttributesRequired.ErrorCode
+		}
+		return apperrorsx.CodeHelicopterInvalidPayload, apperrorsx.ErrHelicopterInvalidPayload.ErrorCode
+	case fiber.StatusBadRequest:
+		if strings.Contains(lowerTitle, "invalid json") {
+			return apperrorsx.CodeHelicopterInvalidJSON, apperrorsx.ErrHelicopterInvalidJSON.ErrorCode
+		}
+		if strings.Contains(lowerTitle, "create failed") {
+			return apperrorsx.CodeHelicopterCreateFailed, apperrorsx.ErrHelicopterCreateFailed.ErrorCode
+		}
+		if strings.Contains(lowerTitle, "update failed") {
+			return apperrorsx.CodeHelicopterUpdateFailed, apperrorsx.ErrHelicopterUpdateFailed.ErrorCode
+		}
+		if strings.Contains(lowerTitle, "delete failed") {
+			return apperrorsx.CodeHelicopterDeleteFailed, apperrorsx.ErrHelicopterDeleteFailed.ErrorCode
+		}
+		if strings.Contains(lowerTitle, "generate failed") {
+			return apperrorsx.CodeHelicopterGenerateFailed, apperrorsx.ErrHelicopterGenerateFailed.ErrorCode
+		}
+		if strings.Contains(lowerTitle, "list failed") {
+			return apperrorsx.CodeHelicopterListFailed, apperrorsx.ErrHelicopterListFailed.ErrorCode
+		}
+		return apperrorsx.CodeHelicopterCreateFailed, apperrorsx.ErrHelicopterCreateFailed.ErrorCode
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
diff --git a/internal/transport/http/handlers/helicopter_handler_test.go b/internal/transport/http/handlers/helicopter_handler_test.go
new file mode 100644
index 0000000..1ece28d
--- /dev/null
+++ b/internal/transport/http/handlers/helicopter_handler_test.go
@@ -0,0 +1,1555 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	complaint "wucher/internal/domain/complaint"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/helicopter"
+	"wucher/internal/service"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/uuidv7"
+	responsedto "wucher/internal/transport/http/dto/response"
+)
+
+func TestApplyHelicopterFleetStatus_GroundedSetsInactive(t *testing.T) {
+	res := responsedto.HelicopterResource{}
+	res.Attributes.IsActive = true
+	row := &helicopter.Helicopter{IsActive: true, AirOnGround: false}
+
+	// A non-empty groundReason simulates an open-complaint grounding (not persisted
+	// in air_on_ground), and is reflected verbatim as the AOG reason.
+	reason := "Grounded due to an open complaint — MEL A grace period expired"
+	applyHelicopterFleetStatus(&res, row, false, reason, false, nil)
+
+	if res.Attributes.Status != helicopter.StatusAOG {
+		t.Fatalf("expected status AOG, got %q", res.Attributes.Status)
+	}
+	if !res.Attributes.AOG {
+		t.Fatal("expected aog=true")
+	}
+	if res.Attributes.IsActive {
+		t.Fatal("expected is_active=false for a grounded (AOG) helicopter")
+	}
+	if res.Attributes.AOGReason != reason {
+		t.Fatalf("expected enriched AOG reason %q, got %q", reason, res.Attributes.AOGReason)
+	}
+}
+
+func TestApplyHelicopterFleetStatus_AvailableStaysActive(t *testing.T) {
+	res := responsedto.HelicopterResource{}
+	res.Attributes.IsActive = true
+	row := &helicopter.Helicopter{IsActive: true, AirOnGround: false}
+
+	applyHelicopterFleetStatus(&res, row, false, "", false, nil)
+
+	if res.Attributes.Status != helicopter.StatusAvailable {
+		t.Fatalf("expected status available, got %q", res.Attributes.Status)
+	}
+	if !res.Attributes.IsActive {
+		t.Fatal("expected is_active=true for an available helicopter")
+	}
+}
+
+func TestComplaintGroundingReason_MELvsNonMEL(t *testing.T) {
+	mel := complaint.Complaint{MELSeverity: complaint.MELSeverityA}
+	if got := complaintGroundingReason(mel); !strings.Contains(got, "MEL A") || !strings.Contains(got, "grace period expired") {
+		t.Fatalf("unexpected MEL reason: %q", got)
+	}
+	nonMEL := complaint.Complaint{MELSeverity: complaint.MELSeverityNonMEL}
+	if got := complaintGroundingReason(nonMEL); !strings.Contains(got, "non-MEL") {
+		t.Fatalf("unexpected non-MEL reason: %q", got)
+	}
+}
+
+type memHelicopterRepo struct {
+	rows map[string]*helicopter.Helicopter
+
+	createErr error
+	updateErr error
+	deleteErr error
+	getErr    error
+	listErr   error
+	nextErr   error
+	existsErr error
+
+	listRows  []helicopter.Helicopter
+	listTotal int64
+}
+
+type helicopterPresignStorageMock struct {
+	url string
+	err error
+}
+
+type helicopterAttachmentRepoMock struct {
+	getByIDFn func(id []byte) (*filemanager.Attachment, error)
+}
+
+type helicopterPINVerifierMock struct {
+	consumeFn func(ctx context.Context, userID []byte, action, token string) error
+}
+
+type helicopterPINSessionVerifierMock struct {
+	helicopterPINVerifierMock
+	accessCookieName string
+	parseSessionFn   func(ctx context.Context, accessToken string) (string, error)
+	consumeSessionFn func(ctx context.Context, userID []byte, action, token, sessionID string) error
+}
+
+func intPtr(v int) *int {
+	return &v
+}
+
+func (m *helicopterAttachmentRepoMock) Create(context.Context, *filemanager.Attachment) error {
+	return nil
+}
+
+func (m *helicopterAttachmentRepoMock) Delete(context.Context, []byte) error {
+	return nil
+}
+
+func (m *helicopterAttachmentRepoMock) GetByID(_ context.Context, id []byte) (*filemanager.Attachment, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(id)
+	}
+	return nil, nil
+}
+
+func (m *helicopterAttachmentRepoMock) GetByRefAndFile(context.Context, string, string, []byte) (*filemanager.Attachment, error) {
+	return nil, nil
+}
+
+func (m *helicopterAttachmentRepoMock) ListByReference(context.Context, filemanager.AttachmentListFilter) ([]filemanager.Attachment, int64, error) {
+	return nil, 0, nil
+}
+
+func (m *helicopterPINVerifierMock) ConsumeSecurityPINActionToken(ctx context.Context, userID []byte, action, token string) error {
+	if m.consumeFn != nil {
+		return m.consumeFn(ctx, userID, action, token)
+	}
+	return nil
+}
+
+func (m *helicopterPINSessionVerifierMock) AccessCookieName() string {
+	if strings.TrimSpace(m.accessCookieName) == "" {
+		return "access_token"
+	}
+	return m.accessCookieName
+}
+
+func (m *helicopterPINSessionVerifierMock) ParseAccessTokenSessionID(ctx context.Context, accessToken string) (string, error) {
+	if m.parseSessionFn != nil {
+		return m.parseSessionFn(ctx, accessToken)
+	}
+	return "", nil
+}
+
+func (m *helicopterPINSessionVerifierMock) ConsumeSecurityPINActionTokenInSession(ctx context.Context, userID []byte, action, token, sessionID string) error {
+	if m.consumeSessionFn != nil {
+		return m.consumeSessionFn(ctx, userID, action, token, sessionID)
+	}
+	return nil
+}
+
+func (m *helicopterPresignStorageMock) PresignGetObject(_ context.Context, _ string, _ time.Duration) (string, error) {
+	if m.err != nil {
+		return "", m.err
+	}
+	return m.url, nil
+}
+
+func newMemHelicopterRepo() *memHelicopterRepo {
+	return &memHelicopterRepo{rows: map[string]*helicopter.Helicopter{}}
+}
+
+func (r *memHelicopterRepo) Create(_ context.Context, h *helicopter.Helicopter) error {
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if len(h.ID) == 0 {
+		h.ID = uuidv7.MustBytes()
+	}
+	now := time.Now().UTC()
+	if h.CreatedAt.IsZero() {
+		h.CreatedAt = now
+	}
+	h.UpdatedAt = now
+	clone := *h
+	r.rows[string(clone.ID)] = &clone
+	return nil
+}
+
+func (r *memHelicopterRepo) Update(_ context.Context, h *helicopter.Helicopter) error {
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	if existing, ok := r.rows[string(h.ID)]; ok {
+		_ = existing
+	}
+	h.UpdatedAt = time.Now().UTC()
+	clone := *h
+	r.rows[string(clone.ID)] = &clone
+	return nil
+}
+
+func (r *memHelicopterRepo) Delete(_ context.Context, id []byte) error {
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	delete(r.rows, string(id))
+	return nil
+}
+
+func (r *memHelicopterRepo) GetByID(_ context.Context, id []byte) (*helicopter.Helicopter, error) {
+	if r.getErr != nil {
+		return nil, r.getErr
+	}
+	h := r.rows[string(id)]
+	if h == nil {
+		return nil, nil
+	}
+	clone := *h
+	return &clone, nil
+}
+
+func (r *memHelicopterRepo) List(_ context.Context, _ string, _ []string, _ string, _ int, _ int, _ [][]byte) ([]helicopter.Helicopter, int64, error) {
+	if r.listErr != nil {
+		return nil, 0, r.listErr
+	}
+	if r.listRows != nil {
+		return r.listRows, r.listTotal, nil
+	}
+	out := make([]helicopter.Helicopter, 0, len(r.rows))
+	for _, row := range r.rows {
+		out = append(out, *row)
+	}
+	return out, int64(len(out)), nil
+}
+
+func (r *memHelicopterRepo) NextReportNumber(_ context.Context, id []byte) (string, int, error) {
+	if r.nextErr != nil {
+		return "", 0, r.nextErr
+	}
+	h := r.rows[string(id)]
+	if h == nil {
+		return "", 0, gorm.ErrRecordNotFound
+	}
+	h.ReportSequence++
+	return fmt.Sprintf("%s-%04d", h.Identifier, h.ReportSequence), h.ReportSequence, nil
+}
+
+func (r *memHelicopterRepo) ExistsByIdentifier(_ context.Context, identifier string, excludeID []byte) (bool, error) {
+	if r.existsErr != nil {
+		return false, r.existsErr
+	}
+	target := strings.ToUpper(strings.TrimSpace(identifier))
+	for _, row := range r.rows {
+		if len(excludeID) > 0 && string(row.ID) == string(excludeID) {
+			continue
+		}
+		if strings.ToUpper(strings.TrimSpace(row.Identifier)) == target {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+func (r *memHelicopterRepo) IsInUse(_ context.Context, id []byte) (bool, error) {
+	_ = id
+	return false, nil
+}
+
+func (r *memHelicopterRepo) InUseByAircraftIDs(_ context.Context, ids [][]byte) (map[string]bool, error) {
+	_ = ids
+	return map[string]bool{}, nil
+}
+func (r *memHelicopterRepo) ActiveFlightIDByAircraftIDs(_ context.Context, _ [][]byte) (map[string][]byte, error) {
+	return map[string][]byte{}, nil
+}
+
+func TestNewHelicopterHandler(t *testing.T) {
+	h := NewHelicopterHandler(service.NewHelicopterService(newMemHelicopterRepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+func TestHelicopterHandler_Create(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		h := NewHelicopterHandler(service.NewHelicopterService(repo))
+		app := fiber.New()
+		actor := uuidv7.MustBytes()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", actor)
+			return c.Next()
+		})
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":" OE-XHZ ","identifier":"1234","type":" EC-13 ","sortkey":3,"visible":true}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+
+		if len(repo.rows) != 1 {
+			t.Fatalf("expected 1 created row, got %d", len(repo.rows))
+		}
+		for _, row := range repo.rows {
+			if row.Designation != "OE-XHZ" {
+				t.Fatalf("expected designation trimmed, got %q", row.Designation)
+			}
+			if row.Identifier != "1234" {
+				t.Fatalf("expected identifier unchanged, got %q", row.Identifier)
+			}
+			if row.ReportSequence != 0 {
+				t.Fatalf("expected report_sequence initialized to 0, got %d", row.ReportSequence)
+			}
+			if row.SortKey == nil || *row.SortKey != 3 {
+				t.Fatalf("expected sortkey set, got %#v", row.SortKey)
+			}
+			if string(row.CreatedBy) != string(actor) {
+				t.Fatalf("expected created_by from actor")
+			}
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		h := NewHelicopterHandler(service.NewHelicopterService(repo))
+		app := fiber.New()
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader([]byte(`{"data":`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		h := NewHelicopterHandler(service.NewHelicopterService(repo))
+		app := fiber.New()
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader([]byte(`{"data":{"type":"","attributes":{}}}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("duplicate identifier (case-insensitive) is denied", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		repo.rows[string(uuidv7.MustBytes())] = &helicopter.Helicopter{
+			ID:             uuidv7.MustBytes(),
+			Designation:    "OLD",
+			Identifier:     "SN-0001",
+			ReportSequence: 1,
+			Type:           "EC-13",
+			IsActive:       true,
+		}
+		h := NewHelicopterHandler(service.NewHelicopterService(repo))
+		app := fiber.New()
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":" OE-NEW ","identifier":"sn-0001","type":" EC-13 "}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409, got %d", resp.StatusCode)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if !strings.Contains(string(body), "Serial number already exists") {
+			t.Fatalf("expected duplicate serial number message, got %s", string(body))
+		}
+		if !strings.Contains(string(body), "/data/attributes/identifier") {
+			t.Fatalf("expected identifier pointer in error source, got %s", string(body))
+		}
+		if len(repo.rows) != 1 {
+			t.Fatalf("expected no additional row on duplicate identifier")
+		}
+	})
+
+	t.Run("missing required attributes", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		h := NewHelicopterHandler(service.NewHelicopterService(repo))
+		app := fiber.New()
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":"","identifier":"","type":""}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		repo.createErr = errors.New("db error")
+		h := NewHelicopterHandler(service.NewHelicopterService(repo))
+		app := fiber.New()
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":"OE-XHZ","identifier":"1234","type":"EC-13"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		body, _ := io.ReadAll(resp.Body)
+		if resp.StatusCode != http.StatusInternalServerError {
+			t.Fatalf("expected 500, got %d", resp.StatusCode)
+		}
+		if strings.Contains(string(body), "db error") {
+			t.Fatalf("expected raw error to be hidden, got %s", string(body))
+		}
+		if !strings.Contains(string(body), "an internal error occurred") {
+			t.Fatalf("expected generic internal message, got %s", string(body))
+		}
+	})
+
+	t.Run("aog true requires reason", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		h := NewHelicopterHandler(service.NewHelicopterService(repo))
+		app := fiber.New()
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":"OE-XHZ","identifier":"1234","type":"EC-13","aog":true}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHelicopterHandler_Update(t *testing.T) {
+	repo := newMemHelicopterRepo()
+	id := uuidv7.MustBytes()
+	repo.rows[string(id)] = &helicopter.Helicopter{
+		ID:             id,
+		Designation:    "OE-XHZ",
+		Identifier:     "1234",
+		ReportSequence: 1,
+		Type:           "EC-13",
+		IsActive:       true,
+	}
+
+	h := NewHelicopterHandler(service.NewHelicopterService(repo))
+	app := fiber.New()
+	app.Patch("/api/v1/helicopters/update/:id", h.Update)
+
+	t.Run("success", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{"designation":"OE-NEW","identifier":"9876","sortkey":7}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		updated := repo.rows[string(id)]
+		if updated.Designation != "OE-NEW" {
+			t.Fatalf("expected designation updated, got %q", updated.Designation)
+		}
+		if updated.Identifier != "9876" {
+			t.Fatalf("expected identifier unchanged, got %q", updated.Identifier)
+		}
+		if updated.ReportSequence != 1 {
+			t.Fatalf("expected report_sequence unchanged, got %d", updated.ReportSequence)
+		}
+		if updated.SortKey == nil || *updated.SortKey != 7 {
+			t.Fatalf("expected sortkey updated, got %#v", updated.SortKey)
+		}
+	})
+
+	t.Run("empty file_uuid clears existing attachment", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		fotoID := uuidv7.MustBytes()
+		repo.rows[string(id)].FotoAttachmentID = append([]byte(nil), fotoID...)
+
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{"designation":"OE-KEEP","file_uuid":""}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.rows[string(id)].FotoAttachmentID != nil {
+			t.Fatalf("expected foto attachment to be cleared")
+		}
+	})
+
+	t.Run("existing attachment uuid is accepted on update", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		attachmentID := uuidv7.MustBytes()
+		attachmentIDStr, _ := uuidv7.BytesToString(attachmentID)
+		fileSvc := service.NewFileManagerService(nil, nil, &helicopterAttachmentRepoMock{
+			getByIDFn: func(gotID []byte) (*filemanager.Attachment, error) {
+				if string(gotID) != string(attachmentID) {
+					return nil, nil
+				}
+				return &filemanager.Attachment{ID: append([]byte(nil), attachmentID...)}, nil
+			},
+		}, service.FileManagerServiceDependencies{})
+		hWithFileManager := NewHelicopterHandler(service.NewHelicopterService(repo)).WithFileManagerService(fileSvc)
+		appWithFileManager := fiber.New()
+		appWithFileManager.Patch("/api/v1/helicopters/update/:id", hWithFileManager.Update)
+
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{"designation":"OE-ATTACH","file_uuid":"` + attachmentIDStr + `"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := appWithFileManager.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(repo.rows[string(id)].FotoAttachmentID) != string(attachmentID) {
+			t.Fatalf("expected existing attachment uuid to be accepted")
+		}
+	})
+
+	t.Run("invalid path uuid", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/bad-uuid", bytes.NewReader([]byte(`{}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader([]byte(`{"data":`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		payload := []byte(`{"data":{"type":"helicopter","id":"","attributes":{"designation":"X"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		other, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + other + `","attributes":{"designation":"X"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no attrs", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		missing := uuidv7.MustBytes()
+		missingStr, _ := uuidv7.BytesToString(missing)
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + missingStr + `","attributes":{"designation":"X"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+missingStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid designation", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{"designation":" "}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid identifier", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{"identifier":"   "}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid type", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{"type":"   "}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success update all fields", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{"designation":"OE-ALL","identifier":"4321","type":"EC-145","engine_1":"TM1","engine_2":"TM2","consumption_lt_min":8.8,"nr1":true,"nr2":false,"lh":true,"rh":false,"mgb":true,"igb":false,"tgb":true,"utc_offset":2,"dry":true,"note":"all fields updated","is_active":false}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+
+		updated := repo.rows[string(id)]
+		if updated.Type != "EC-145" || updated.Engine1 != "TM1" || updated.Engine2 != "TM2" {
+			t.Fatalf("expected scalar fields updated, got %+v", *updated)
+		}
+		if !updated.Dry || updated.IsActive {
+			t.Fatalf("expected boolean fields updated, got %+v", *updated)
+		}
+		if updated.Note != "all fields updated" || updated.Identifier != "4321" {
+			t.Fatalf("expected note/identifier updated, got %+v", *updated)
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		repo.updateErr = errors.New("update failed")
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{"designation":"OE-ZZZ"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		repo.updateErr = nil
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("aog true requires reason", func(t *testing.T) {
+		idNoReason := uuidv7.MustBytes()
+		repo.rows[string(idNoReason)] = &helicopter.Helicopter{
+			ID:          idNoReason,
+			Designation: "OE-NOREASON",
+			Identifier:  "2000-0001",
+			Type:        "EC-13",
+			AirOnGround: false,
+			AOGReason:   "",
+			IsActive:    true,
+		}
+		idStr, _ := uuidv7.BytesToString(idNoReason)
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{"aog":true}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHelicopterHandler_AOGPINVerification(t *testing.T) {
+	t.Run("create aog false does not require pin", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		actor := uuidv7.MustBytes()
+		h := NewHelicopterHandler(service.NewHelicopterService(repo)).WithPINVerifier(&helicopterPINVerifierMock{
+			consumeFn: func(_ context.Context, _ []byte, _ string, _ string) error {
+				t.Fatalf("expected pin verifier not to be called when aog is false")
+				return nil
+			},
+		})
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", actor)
+			return c.Next()
+		})
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":"OE-NO-PIN","identifier":"7778","type":"EC-145","aog":false}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if len(repo.rows) != 1 {
+			t.Fatalf("expected helicopter created without pin when aog is false")
+		}
+	})
+
+	t.Run("create aog true requires pin", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		actor := uuidv7.MustBytes()
+		h := NewHelicopterHandler(service.NewHelicopterService(repo)).WithPINVerifier(&helicopterPINVerifierMock{
+			consumeFn: func(_ context.Context, userID []byte, action, token string) error {
+				if string(userID) != string(actor) {
+					t.Fatalf("unexpected actor passed to pin verifier")
+				}
+				if action != sharedconst.PinActionHelicopterAOGChange {
+					t.Fatalf("unexpected pin action %q", action)
+				}
+				if token == "" {
+					return errors.New("missing token")
+				}
+				return nil
+			},
+		})
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", actor)
+			return c.Next()
+		})
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":"OE-AOG","identifier":"7777","type":"EC-145","aog":true,"aog_reason":"grounded"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusAccepted {
+			t.Fatalf("expected 202, got %d", resp.StatusCode)
+		}
+		if len(repo.rows) != 0 {
+			t.Fatalf("expected no helicopter created without pin verification")
+		}
+	})
+
+	t.Run("update aog change requires pin", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		actor := uuidv7.MustBytes()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &helicopter.Helicopter{
+			ID:          id,
+			Designation: "OE-XHZ",
+			Identifier:  "1234-0001",
+			Type:        "EC-13",
+			AirOnGround: false,
+			IsActive:    true,
+		}
+		h := NewHelicopterHandler(service.NewHelicopterService(repo)).WithPINVerifier(&helicopterPINVerifierMock{
+			consumeFn: func(_ context.Context, userID []byte, action, token string) error {
+				if string(userID) != string(actor) {
+					t.Fatalf("unexpected actor passed to pin verifier")
+				}
+				if action != sharedconst.PinActionHelicopterAOGChange {
+					t.Fatalf("unexpected pin action %q", action)
+				}
+				if token == "" {
+					return errors.New("missing token")
+				}
+				return nil
+			},
+		})
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", actor)
+			return c.Next()
+		})
+		app.Patch("/api/v1/helicopters/update/:id", h.Update)
+
+		idStr, _ := uuidv7.BytesToString(id)
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{"aog":true,"aog_reason":"grounded"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusAccepted {
+			t.Fatalf("expected 202, got %d", resp.StatusCode)
+		}
+		if repo.rows[string(id)].AirOnGround {
+			t.Fatalf("expected aog state not to change without pin verification")
+		}
+	})
+
+	t.Run("update without touching aog does not require pin", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &helicopter.Helicopter{
+			ID:          id,
+			Designation: "OE-XHZ",
+			Identifier:  "1234-0001",
+			Type:        "EC-13",
+			AirOnGround: false,
+			IsActive:    true,
+		}
+		pinVerifierCalled := false
+		h := NewHelicopterHandler(service.NewHelicopterService(repo)).WithPINVerifier(&helicopterPINVerifierMock{
+			consumeFn: func(_ context.Context, _ []byte, _ string, _ string) error {
+				pinVerifierCalled = true
+				return nil
+			},
+		})
+		app := fiber.New()
+		app.Patch("/api/v1/helicopters/update/:id", h.Update)
+
+		idStr, _ := uuidv7.BytesToString(id)
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{"designation":"OE-UPDATED"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if pinVerifierCalled {
+			t.Fatalf("expected pin verifier not to be called when aog is untouched")
+		}
+	})
+
+	t.Run("update aog uses session-bound token when verifier supports it", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		actor := uuidv7.MustBytes()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &helicopter.Helicopter{
+			ID:          id,
+			Designation: "OE-XHZ",
+			Identifier:  "1234-0001",
+			Type:        "EC-13",
+			AirOnGround: false,
+			IsActive:    true,
+		}
+		h := NewHelicopterHandler(service.NewHelicopterService(repo)).WithPINVerifier(&helicopterPINSessionVerifierMock{
+			accessCookieName: "access_token",
+			parseSessionFn: func(_ context.Context, accessToken string) (string, error) {
+				if accessToken != "access.jwt.token" {
+					t.Fatalf("unexpected access token %q", accessToken)
+				}
+				return "sid-123", nil
+			},
+			consumeSessionFn: func(_ context.Context, userID []byte, action, token, sessionID string) error {
+				if string(userID) != string(actor) {
+					t.Fatalf("unexpected actor passed to pin verifier")
+				}
+				if action != sharedconst.PinActionHelicopterAOGChange {
+					t.Fatalf("unexpected pin action %q", action)
+				}
+				if token != "pin-token" {
+					t.Fatalf("unexpected pin token %q", token)
+				}
+				if sessionID != "sid-123" {
+					t.Fatalf("unexpected session id %q", sessionID)
+				}
+				return nil
+			},
+		})
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", actor)
+			return c.Next()
+		})
+		app.Patch("/api/v1/helicopters/update/:id", h.Update)
+
+		idStr, _ := uuidv7.BytesToString(id)
+		payload := []byte(`{"data":{"type":"helicopter","id":"` + idStr + `","attributes":{"aog":true,"aog_reason":"grounded"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/helicopters/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set(pinVerificationHeader, "pin-token")
+		req.AddCookie(&http.Cookie{Name: "access_token", Value: "access.jwt.token"})
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if !repo.rows[string(id)].AirOnGround {
+			t.Fatalf("expected aog state to change after valid session-bound pin verification")
+		}
+	})
+}
+
+func TestHelicopterHandler_GetWithFoto(t *testing.T) {
+	repo := newMemHelicopterRepo()
+	id := uuidv7.MustBytes()
+	fotoID := uuidv7.MustBytes()
+	repo.rows[string(id)] = &helicopter.Helicopter{
+		ID:               id,
+		Designation:      "OE-XHZ",
+		Identifier:       "1234-0001",
+		Type:             "EC-13",
+		FotoAttachmentID: fotoID,
+		FotoAttachment: &filemanager.Attachment{
+			ID:     fotoID,
+			FileID: uuidv7.MustBytes(),
+			File:   &filemanager.File{ID: uuidv7.MustBytes(), ObjectKey: "helicopter/oe-xhz.jpg"},
+		},
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}
+
+	h := NewHelicopterHandler(service.NewHelicopterService(repo)).WithFileStorage(&helicopterPresignStorageMock{
+		url: "https://signed.example/helicopter/oe-xhz.jpg?sig=abc",
+	})
+	app := fiber.New()
+	app.Get("/api/v1/helicopters/get/:id", h.Get)
+
+	idStr, _ := uuidv7.BytesToString(id)
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/helicopters/get/"+idStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	fotoIDStr, _ := uuidv7.BytesToString(fotoID)
+	bodyStr := string(body)
+	if !strings.Contains(bodyStr, `"uuid":"`+fotoIDStr+`"`) {
+		t.Fatalf("expected foto uuid in response, body=%s", bodyStr)
+	}
+	if !strings.Contains(bodyStr, `"download_url":"https://signed.example/helicopter/oe-xhz.jpg?sig=abc"`) {
+		t.Fatalf("expected foto download_url in response, body=%s", bodyStr)
+	}
+	if !strings.Contains(bodyStr, `"original_size_bytes":0`) {
+		t.Fatalf("expected foto original_size_bytes in response, body=%s", bodyStr)
+	}
+}
+
+func TestHelicopterHandler_Delete(t *testing.T) {
+	repo := newMemHelicopterRepo()
+	id := uuidv7.MustBytes()
+	repo.rows[string(id)] = &helicopter.Helicopter{ID: id, Identifier: "1234"}
+
+	h := NewHelicopterHandler(service.NewHelicopterService(repo))
+	app := fiber.New()
+	app.Delete("/api/v1/helicopters/delete/:id", h.Delete)
+
+	t.Run("success", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/helicopters/delete/"+idStr, nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid uuid", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/helicopters/delete/bad", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		h := NewHelicopterHandler(service.NewHelicopterService(repo))
+		app := fiber.New()
+		app.Delete("/api/v1/helicopters/delete/:id", h.Delete)
+
+		id := uuidv7.MustBytes()
+		idStr, _ := uuidv7.BytesToString(id)
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/helicopters/delete/"+idStr, nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete error", func(t *testing.T) {
+		repo.deleteErr = errors.New("delete failed")
+		id2 := uuidv7.MustBytes()
+		repo.rows[string(id2)] = &helicopter.Helicopter{ID: id2, Identifier: "ERR-DEL"}
+		id2Str, _ := uuidv7.BytesToString(id2)
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/helicopters/delete/"+id2Str, nil)
+		resp, _ := app.Test(req)
+		repo.deleteErr = nil
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete relation conflict", func(t *testing.T) {
+		repo.deleteErr = &mysqldriver.MySQLError{
+			Number:  1451,
+			Message: "Cannot delete or update a parent row: a foreign key constraint fails",
+		}
+		id2 := uuidv7.MustBytes()
+		repo.rows[string(id2)] = &helicopter.Helicopter{ID: id2, Identifier: "REL-DEL"}
+		id2Str, _ := uuidv7.BytesToString(id2)
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/helicopters/delete/"+id2Str, nil)
+		resp, _ := app.Test(req)
+		repo.deleteErr = nil
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409, got %d", resp.StatusCode)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		bodyStr := string(body)
+		if !strings.Contains(bodyStr, `"code":"HELICOPTER_RELATION_DELETE_ERROR"`) {
+			t.Fatalf("expected HELICOPTER_RELATION_DELETE_ERROR, got %s", bodyStr)
+		}
+		if !strings.Contains(bodyStr, `"error_code":"4090303"`) {
+			t.Fatalf("expected 4090303, got %s", bodyStr)
+		}
+	})
+
+	t.Run("identifier lookup error", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		repo.existsErr = errors.New("lookup failed")
+		h := NewHelicopterHandler(service.NewHelicopterService(repo))
+		app := fiber.New()
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":"OE-ERR","identifier":"SN-ERR","type":"EC-13"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("aog requires reason", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		h := NewHelicopterHandler(service.NewHelicopterService(repo))
+		app := fiber.New()
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":"OE-XHZ","identifier":"SN-1","type":"EC-13","aog":true,"aog_reason":""}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("aog requires pin token", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		h := NewHelicopterHandler(service.NewHelicopterService(repo))
+		app := fiber.New()
+		actor := uuidv7.MustBytes()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", actor)
+			return c.Next()
+		})
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":"OE-XHZ","identifier":"SN-2","type":"EC-13","aog":true,"aog_reason":"maintenance"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("aog pin verifier rejects token", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		pin := &helicopterPINVerifierMock{
+			consumeFn: func(_ context.Context, _ []byte, _ string, _ string) error {
+				return errors.New("pin required")
+			},
+		}
+		h := NewHelicopterHandler(service.NewHelicopterService(repo)).WithPINVerifier(pin)
+		app := fiber.New()
+		actor := uuidv7.MustBytes()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", actor)
+			return c.Next()
+		})
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":"OE-XHZ","identifier":"SN-3","type":"EC-13","aog":true,"aog_reason":"maintenance"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusAccepted {
+			t.Fatalf("expected 202, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("aog pin verifier accepted continues create", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		pin := &helicopterPINVerifierMock{
+			consumeFn: func(_ context.Context, _ []byte, _ string, _ string) error {
+				return nil
+			},
+		}
+		h := NewHelicopterHandler(service.NewHelicopterService(repo)).WithPINVerifier(pin)
+		app := fiber.New()
+		actor := uuidv7.MustBytes()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", actor)
+			return c.Next()
+		})
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":"OE-XHZ","identifier":"SN-4","type":"EC-13","aog":true,"aog_reason":"maintenance"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("file_uuid invalid returns validation error", func(t *testing.T) {
+		repo := newMemHelicopterRepo()
+		h := NewHelicopterHandler(service.NewHelicopterService(repo))
+		app := fiber.New()
+		app.Post("/api/v1/helicopters/create", h.Create)
+
+		payload := []byte(`{"data":{"type":"helicopter","attributes":{"designation":"OE-XHZ","identifier":"SN-5","type":"EC-13","file_uuid":"bad-uuid"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest && resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 400/422, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHelicopterHandler_NextReportNumber(t *testing.T) {
+	repo := newMemHelicopterRepo()
+	id := uuidv7.MustBytes()
+	repo.rows[string(id)] = &helicopter.Helicopter{ID: id, Identifier: "1234"}
+
+	h := NewHelicopterHandler(service.NewHelicopterService(repo))
+	app := fiber.New()
+	app.Post("/api/v1/helicopters/:id/reports/next-number", h.NextReportNumber)
+
+	t.Run("success", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/"+idStr+"/reports/next-number", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if !strings.Contains(string(body), "1234-0001") {
+			t.Fatalf("expected report number in response body, got %s", string(body))
+		}
+	})
+
+	t.Run("invalid uuid", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/bad/reports/next-number", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found from generator", func(t *testing.T) {
+		missing := uuidv7.MustBytes()
+		missingStr, _ := uuidv7.BytesToString(missing)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/"+missingStr+"/reports/next-number", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("generate failed", func(t *testing.T) {
+		repo.nextErr = errors.New("boom")
+		idStr, _ := uuidv7.BytesToString(id)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/"+idStr+"/reports/next-number", nil)
+		resp, _ := app.Test(req)
+		repo.nextErr = nil
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found on post-check", func(t *testing.T) {
+		repo.nextErr = nil
+		repo.getErr = errors.New("gone")
+		idStr, _ := uuidv7.BytesToString(id)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/helicopters/"+idStr+"/reports/next-number", nil)
+		resp, _ := app.Test(req)
+		repo.getErr = nil
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHelicopterHandler_Get(t *testing.T) {
+	repo := newMemHelicopterRepo()
+	id := uuidv7.MustBytes()
+	repo.rows[string(id)] = &helicopter.Helicopter{ID: id, Designation: "OE-XHZ", Identifier: "1234", Type: "EC-13"}
+
+	h := NewHelicopterHandler(service.NewHelicopterService(repo))
+	app := fiber.New()
+	app.Get("/api/v1/helicopters/get/:id", h.Get)
+
+	t.Run("success", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(id)
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/helicopters/get/"+idStr, nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid uuid", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/helicopters/get/bad", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		missing := uuidv7.MustBytes()
+		missingStr, _ := uuidv7.BytesToString(missing)
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/helicopters/get/"+missingStr, nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHelicopterHandler_List(t *testing.T) {
+	repo := newMemHelicopterRepo()
+	repo.listRows = []helicopter.Helicopter{{ID: uuidv7.MustBytes(), Designation: "OE-XHZ", Identifier: "1234", Type: "EC-13", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+	repo.listTotal = 1
+
+	h := NewHelicopterHandler(service.NewHelicopterService(repo))
+	app := fiber.New()
+	app.Get("/api/v1/helicopters/get-all", h.List)
+
+	t.Run("success", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/helicopters/get-all?filter[search]=OE&page[number]=1&page[size]=20", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("list failed", func(t *testing.T) {
+		repo.listErr = errors.New("list failed")
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/helicopters/get-all", nil)
+		resp, _ := app.Test(req)
+		repo.listErr = nil
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHelicopterHandler_ListDatatable(t *testing.T) {
+	repo := newMemHelicopterRepo()
+	repo.listRows = []helicopter.Helicopter{{ID: uuidv7.MustBytes(), Designation: "OE-XHZ", Identifier: "1234", Type: "EC-13", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+	repo.listTotal = 1
+
+	h := NewHelicopterHandler(service.NewHelicopterService(repo))
+	app := fiber.New()
+	app.Get("/api/v1/helicopters/get-all/dt", h.ListDatatable)
+
+	t.Run("success", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/helicopters/get-all/dt?page=1&limit=10&draw=3&search=OE", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("list failed", func(t *testing.T) {
+		repo.listErr = errors.New("list failed")
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/helicopters/get-all/dt", nil)
+		resp, _ := app.Test(req)
+		repo.listErr = nil
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHelicopterResource(t *testing.T) {
+	id := uuidv7.MustBytes()
+	row := &helicopter.Helicopter{
+		ID:          id,
+		Designation: "OE-XHZ",
+		Identifier:  "1234",
+		Type:        "EC-13",
+		SortKey:     intPtr(10),
+		Engine1:     "TM",
+		Engine2:     "TM",
+		Consumption: 4.1,
+		NR1:         true,
+		NR2:         true,
+		LH:          true,
+		RH:          true,
+		MGB:         true,
+		IGB:         false,
+		TGB:         true,
+		UTCOffset:   -1,
+		Dry:         false,
+		Note:        "primary",
+		IsActive:    true,
+		CreatedBy:   uuidv7.MustBytes(),
+		CreatedAt:   time.Now().UTC(),
+		UpdatedAt:   time.Now().UTC(),
+	}
+
+	res := helicopterResource(row)
+	if res.Type != "helicopter" {
+		t.Fatalf("expected resource type helicopter, got %s", res.Type)
+	}
+	if res.Attributes.Identifier != "1234" {
+		t.Fatalf("expected identifier mapped, got %q", res.Attributes.Identifier)
+	}
+	if res.Attributes.SortKey == nil || *res.Attributes.SortKey != 10 {
+		t.Fatalf("expected sortkey mapped, got %#v", res.Attributes.SortKey)
+	}
+	if res.Attributes.IsInUse {
+		t.Fatalf("expected is_in_use default false")
+	}
+	if res.Attributes.CreatedBy == nil || res.Attributes.CreatedBy.ID == "" {
+		t.Fatalf("expected created_by mapped")
+	}
+	if res.Attributes.CreatedAt == "" || res.Attributes.UpdatedAt == "" {
+		t.Fatalf("expected created_at and updated_at mapped")
+	}
+}
+
+func TestHelicopterHandler_DefaultHelpers(t *testing.T) {
+	if boolOrDefault(nil, true) != true {
+		t.Fatalf("expected bool default")
+	}
+	vBool := false
+	if boolOrDefault(&vBool, true) != false {
+		t.Fatalf("expected bool pointer value")
+	}
+
+	if intOrDefault(nil, 7) != 7 {
+		t.Fatalf("expected int default")
+	}
+	vInt := 12
+	if intOrDefault(&vInt, 7) != 12 {
+		t.Fatalf("expected int pointer value")
+	}
+
+	if floatOrDefault(nil, 1.5) != 1.5 {
+		t.Fatalf("expected float default")
+	}
+	vFloat := 9.9
+	if floatOrDefault(&vFloat, 1.5) != 9.9 {
+		t.Fatalf("expected float pointer value")
+	}
+
+	if stringOrDefault(nil, "a") != "a" {
+		t.Fatalf("expected string default")
+	}
+	vStr := "b"
+	if stringOrDefault(&vStr, "a") != "b" {
+		t.Fatalf("expected string pointer value")
+	}
+}
+
+func TestNormalizeHelicopterIdentifier(t *testing.T) {
+	tests := []struct {
+		name string
+		raw  string
+		want string
+	}{
+		{name: "empty", raw: "", want: ""},
+		{name: "plain", raw: "1234", want: "1234"},
+		{name: "trim spaces", raw: "  ABC  ", want: "ABC"},
+		{name: "keep free text", raw: "s/n 1234", want: "S/N 1234"},
+		{name: "keep free text upper", raw: "S/N 1234", want: "S/N 1234"},
+		{name: "spaces only", raw: "   ", want: ""},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := normalizeHelicopterIdentifier(tc.raw)
+			if got != tc.want {
+				t.Fatalf("normalizeHelicopterIdentifier(%q) = %q, want %q", tc.raw, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestHelicopterHandler_HelperBranches(t *testing.T) {
+	t.Run("with setters return same handler", func(t *testing.T) {
+		h := NewHelicopterHandler(service.NewHelicopterService(newMemHelicopterRepo()))
+		if h.WithFileManagerService(nil) != h {
+			t.Fatalf("expected WithFileManagerService to return same handler")
+		}
+		if h.WithFileStorage(nil) != h {
+			t.Fatalf("expected WithFileStorage to return same handler")
+		}
+	})
+
+	t.Run("resolve foto attachment via file uuid without file manager writes validation error", func(t *testing.T) {
+		h := NewHelicopterHandler(service.NewHelicopterService(newMemHelicopterRepo()))
+		app := fiber.New()
+		app.Get("/", func(c *fiber.Ctx) error {
+			raw := "bad-uuid"
+			_, handled := h.resolveFotoAttachmentID(c, uuidv7.MustBytes(), &raw, "Create failed")
+			if !handled {
+				t.Fatalf("expected invalid uuid to be handled")
+			}
+			return nil
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("resolve existing foto attachment returns direct attachment id", func(t *testing.T) {
+		attachmentID := uuidv7.MustBytes()
+		fileManagerSvc := service.NewFileManagerService(nil, nil, &helicopterAttachmentRepoMock{
+			getByIDFn: func(id []byte) (*filemanager.Attachment, error) {
+				return &filemanager.Attachment{ID: id}, nil
+			},
+		}, service.FileManagerServiceDependencies{})
+		h := NewHelicopterHandler(service.NewHelicopterService(newMemHelicopterRepo())).WithFileManagerService(fileManagerSvc)
+		app := fiber.New()
+		app.Get("/", func(c *fiber.Ctx) error {
+			raw := mustUUIDStringHelicopter(attachmentID)
+			got, handled := h.resolveExistingFotoAttachmentOrFileID(c, uuidv7.MustBytes(), &raw, "Update failed")
+			if handled {
+				t.Fatalf("expected existing attachment path to succeed")
+			}
+			if string(got) != string(attachmentID) {
+				t.Fatalf("expected direct attachment id returned")
+			}
+			return c.SendStatus(fiber.StatusOK)
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/", nil)
+		if _, err := app.Test(req); err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+	})
+
+	t.Run("resolve existing foto attachment surfaces repository error", func(t *testing.T) {
+		fileManagerSvc := service.NewFileManagerService(nil, nil, &helicopterAttachmentRepoMock{
+			getByIDFn: func([]byte) (*filemanager.Attachment, error) {
+				return nil, errors.New("attachment lookup failed")
+			},
+		}, service.FileManagerServiceDependencies{})
+		h := NewHelicopterHandler(service.NewHelicopterService(newMemHelicopterRepo())).WithFileManagerService(fileManagerSvc)
+		app := fiber.New()
+		app.Get("/", func(c *fiber.Ctx) error {
+			raw := mustUUIDStringHelicopter(uuidv7.MustBytes())
+			_, handled := h.resolveExistingFotoAttachmentOrFileID(c, uuidv7.MustBytes(), &raw, "Update failed")
+			if !handled {
+				t.Fatalf("expected repository error to be handled")
+			}
+			return nil
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("require AOG pin verification branches", func(t *testing.T) {
+		h := NewHelicopterHandler(service.NewHelicopterService(newMemHelicopterRepo()))
+		app := fiber.New()
+		app.Get("/missing-config", func(c *fiber.Ctx) error {
+			if !h.requireAOGPINVerification(c) {
+				t.Fatalf("expected missing pin verifier to block request")
+			}
+			return nil
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/missing-config", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+
+		h.pinVerifier = &helicopterPINVerifierMock{}
+		app.Get("/missing-user", func(c *fiber.Ctx) error {
+			if !h.requireAOGPINVerification(c) {
+				t.Fatalf("expected missing actor to block request")
+			}
+			return nil
+		})
+		req, _ = http.NewRequest(http.MethodGet, "/missing-user", nil)
+		resp, _ = app.Test(req)
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", uuidv7.MustBytes())
+			return c.Next()
+		})
+		h.pinVerifier = &helicopterPINVerifierMock{
+			consumeFn: func(context.Context, []byte, string, string) error { return errors.New("missing pin") },
+		}
+		app.Get("/pin-required", func(c *fiber.Ctx) error {
+			if !h.requireAOGPINVerification(c) {
+				t.Fatalf("expected invalid token to require pin")
+			}
+			return nil
+		})
+		req, _ = http.NewRequest(http.MethodGet, "/pin-required", nil)
+		resp, _ = app.Test(req)
+		if resp.StatusCode != http.StatusAccepted {
+			t.Fatalf("expected 202, got %d", resp.StatusCode)
+		}
+
+		h.pinVerifier = &helicopterPINVerifierMock{
+			consumeFn: func(context.Context, []byte, string, string) error { return nil },
+		}
+		app.Get("/pin-ok", func(c *fiber.Ctx) error {
+			if h.requireAOGPINVerification(c) {
+				t.Fatalf("expected valid token to pass")
+			}
+			return c.SendStatus(fiber.StatusOK)
+		})
+		req, _ = http.NewRequest(http.MethodGet, "/pin-ok", nil)
+		req.Header.Set(pinVerificationHeader, "token")
+		resp, _ = app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func mustUUIDStringHelicopter(id []byte) string {
+	v, err := uuidv7.BytesToString(id)
+	if err != nil {
+		panic(err)
+	}
+	return v
+}
diff --git a/internal/transport/http/handlers/helicopter_usage_handler.go b/internal/transport/http/handlers/helicopter_usage_handler.go
new file mode 100644
index 0000000..5c5dbb6
--- /dev/null
+++ b/internal/transport/http/handlers/helicopter_usage_handler.go
@@ -0,0 +1,446 @@
+package handlers
+
+import (
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type HelicopterUsageHandler struct {
+	svc      helicopterusage.Service
+	validate *validators.Validator
+}
+
+func NewHelicopterUsageHandler(svc helicopterusage.Service) *HelicopterUsageHandler {
+	return &HelicopterUsageHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateHelicopterUsage godoc
+// @Summary Create helicopter usage
+// @Description Create helicopter usage counters for a helicopter.
+// @Tags Helicopter - Helicopter Usage
+// @Accept json
+// @Produce json
+// @Param request body dto.HelicopterUsageCreateRequest true "JSON:API helicopter usage create request"
+// @Success 201 {object} dto.HelicopterUsageResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/helicopter-usage/create [post]
+func (h *HelicopterUsageHandler) Create(c *fiber.Ctx) error {
+	var req dto.HelicopterUsageCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	helicopterID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.HelicopterID))
+	if err != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "helicopter_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/helicopter_id"},
+		}})
+	}
+
+	row := helicopterUsageFromCreate(req.Data.Attributes)
+	row.HelicopterID = helicopterID
+	row.CreatedBy = actorUserID(c)
+	row.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, helicopterUsageResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, helicopterUsageResource(row))
+}
+
+// GetHelicopterUsage godoc
+// @Summary Get helicopter usage
+// @Tags Helicopter - Helicopter Usage
+// @Produce json
+// @Param uuid path string true "Helicopter Usage UUID (UUIDv7)"
+// @Success 200 {object} dto.HelicopterUsageResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/helicopter-usage/get/{uuid} [get]
+func (h *HelicopterUsageHandler) Get(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if row == nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "helicopter usage not found",
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, helicopterUsageResource(row))
+}
+
+// UpdateHelicopterUsage godoc
+// @Summary Update helicopter usage (partial)
+// @Tags Helicopter - Helicopter Usage
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Helicopter Usage UUID (UUIDv7)"
+// @Param request body dto.HelicopterUsageUpdateRequest true "JSON:API helicopter usage update request"
+// @Success 200 {object} dto.HelicopterUsageResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/helicopter-usage/update/{uuid} [patch]
+func (h *HelicopterUsageHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.HelicopterUsageUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeHelicopterUsageErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeHelicopterUsageErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.HelicopterID == nil &&
+		attrs.TotalLanding == nil &&
+		attrs.TotalAirframeHours == nil &&
+		attrs.TotalAirframeCycles == nil &&
+		attrs.TotalEngine1Hours == nil &&
+		attrs.TotalEngine1GpcNgN1 == nil &&
+		attrs.TotalEngine1PtcNfN2 == nil &&
+		attrs.TotalEngine1Ccc == nil &&
+		attrs.TotalEngine2Hours == nil &&
+		attrs.TotalEngine2GpcNgN1 == nil &&
+		attrs.TotalEngine2PtcNfN2 == nil &&
+		attrs.TotalEngine2Ccc == nil &&
+		attrs.TotalFlightReport == nil &&
+		attrs.TotalHookRelease == nil &&
+		attrs.TotalRotorBrakeCycle == nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "helicopter usage not found",
+		}})
+	}
+
+	if attrs.HelicopterID != nil {
+		helicopterID, parseErr := uuidv7.ParseString(strings.TrimSpace(*attrs.HelicopterID))
+		if parseErr != nil {
+			return writeHelicopterUsageErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "helicopter_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/helicopter_id"},
+			}})
+		}
+		existing.HelicopterID = helicopterID
+	}
+	existing.ApplyManualSummary(helicopterUsageManualInput(attrs))
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, helicopterUsageResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, helicopterUsageResource(existing))
+}
+
+// DeleteHelicopterUsage godoc
+// @Summary Delete helicopter usage
+// @Tags Helicopter - Helicopter Usage
+// @Produce json
+// @Param uuid path string true "Helicopter Usage UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/helicopter-usage/delete/{uuid} [delete]
+func (h *HelicopterUsageHandler) Delete(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeHelicopterUsageErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "helicopter usage not found",
+			}})
+		}
+		return writeHelicopterUsageErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "helicopter_usage_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListHelicopterUsage godoc
+// @Summary List helicopter usage
+// @Description JSON:API list without pagination. Sort values: helicopter_id, -helicopter_id, total_landing, -total_landing, total_airframe_hours, -total_airframe_hours, total_airframe_cycles, -total_airframe_cycles, total_engine_1_hours, -total_engine_1_hours, total_engine_1_gpc_ng_n1, -total_engine_1_gpc_ng_n1, total_engine_1_ptc_nf_n2, -total_engine_1_ptc_nf_n2, total_engine_1_ccc, -total_engine_1_ccc, total_engine_2_hours, -total_engine_2_hours, total_engine_2_gpc_ng_n1, -total_engine_2_gpc_ng_n1, total_engine_2_ptc_nf_n2, -total_engine_2_ptc_nf_n2, total_engine_2_ccc, -total_engine_2_ccc, total_flight_report, -total_flight_report, total_hook_release, -total_hook_release, total_rotor_brake_cycle, -total_rotor_brake_cycle, created_at, -created_at, updated_at, -updated_at.
+// @Tags Helicopter - Helicopter Usage
+// @Produce json
+// @Param search query string false "Search by helicopter or usage ID"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.HelicopterUsageListResponse
+// @Router /api/v1/helicopter-usage/get-all [get]
+func (h *HelicopterUsageHandler) List(c *fiber.Ctx) error {
+	filter := strings.TrimSpace(c.Query("search"))
+	sort := strings.TrimSpace(c.Query("sort"))
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.HelicopterUsageResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, helicopterUsageResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"total": total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListHelicopterUsageDatatable godoc
+// @Summary List helicopter usage (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags Helicopter - Helicopter Usage
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.HelicopterUsageListResponse
+// @Router /api/v1/helicopter-usage/get-all/dt [get]
+func (h *HelicopterUsageHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := strings.TrimSpace(c.Query("search"))
+	sort := strings.TrimSpace(c.Query("sort"))
+
+	rows, total, err := h.svc.List(c.UserContext(), search, sort, length, start)
+	if err != nil {
+		return writeHelicopterUsageErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.HelicopterUsageResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, helicopterUsageResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func helicopterUsageFromCreate(attrs dto.HelicopterUsageCreateAttributes) *helicopterusage.HelicopterUsage {
+	row := &helicopterusage.HelicopterUsage{}
+	row.ApplyManualSummary(helicopterusage.ManualSummaryInput{
+		AirframeHours:   attrs.TotalAirframeHours,
+		AirframeCycles:  attrs.TotalAirframeCycles,
+		Engine1Hours:    attrs.TotalEngine1Hours,
+		Engine1GpcNgN1:  attrs.TotalEngine1GpcNgN1,
+		Engine1PtcNfN2:  attrs.TotalEngine1PtcNfN2,
+		Engine1Ccc:      attrs.TotalEngine1Ccc,
+		Engine2Hours:    attrs.TotalEngine2Hours,
+		Engine2GpcNgN1:  attrs.TotalEngine2GpcNgN1,
+		Engine2PtcNfN2:  attrs.TotalEngine2PtcNfN2,
+		Engine2Ccc:      attrs.TotalEngine2Ccc,
+		Landing:         attrs.TotalLanding,
+		FlightReport:    attrs.TotalFlightReport,
+		HookRelease:     attrs.TotalHookRelease,
+		RotorBrakeCycle: attrs.TotalRotorBrakeCycle,
+	})
+	return row
+}
+
+func helicopterUsageManualInput(attrs dto.HelicopterUsageUpdateAttributes) helicopterusage.ManualSummaryInput {
+	return helicopterusage.ManualSummaryInput{
+		AirframeHours:   attrs.TotalAirframeHours,
+		AirframeCycles:  attrs.TotalAirframeCycles,
+		Engine1Hours:    attrs.TotalEngine1Hours,
+		Engine1GpcNgN1:  attrs.TotalEngine1GpcNgN1,
+		Engine1PtcNfN2:  attrs.TotalEngine1PtcNfN2,
+		Engine1Ccc:      attrs.TotalEngine1Ccc,
+		Engine2Hours:    attrs.TotalEngine2Hours,
+		Engine2GpcNgN1:  attrs.TotalEngine2GpcNgN1,
+		Engine2PtcNfN2:  attrs.TotalEngine2PtcNfN2,
+		Engine2Ccc:      attrs.TotalEngine2Ccc,
+		Landing:         attrs.TotalLanding,
+		FlightReport:    attrs.TotalFlightReport,
+		HookRelease:     attrs.TotalHookRelease,
+		RotorBrakeCycle: attrs.TotalRotorBrakeCycle,
+	}
+}
+
+func helicopterUsageResource(row *helicopterusage.HelicopterUsage) dto.HelicopterUsageResource {
+	if row == nil {
+		return dto.HelicopterUsageResource{}
+	}
+	return dto.HelicopterUsageResource{
+		Type: "helicopter_usage",
+		ID:   idString(row.ID),
+		Attributes: dto.HelicopterUsageAttributes{
+			HelicopterID:         idString(row.HelicopterID),
+			TotalLanding:         row.TotalLanding,
+			TotalAirframeHours:   row.TotalAirframeHours,
+			TotalAirframeCycles:  row.TotalAirframeCycles,
+			TotalEngine1Hours:    row.TotalEngine1Hours,
+			TotalEngine1GpcNgN1:  row.TotalEngine1GpcNgN1,
+			TotalEngine1PtcNfN2:  row.TotalEngine1PtcNfN2,
+			TotalEngine1Ccc:      row.TotalEngine1Ccc,
+			TotalEngine2Hours:    row.TotalEngine2Hours,
+			TotalEngine2GpcNgN1:  row.TotalEngine2GpcNgN1,
+			TotalEngine2PtcNfN2:  row.TotalEngine2PtcNfN2,
+			TotalEngine2Ccc:      row.TotalEngine2Ccc,
+			TotalFlightReport:    row.TotalFlightReport,
+			TotalHookRelease:     row.TotalHookRelease,
+			TotalRotorBrakeCycle: row.TotalRotorBrakeCycle,
+			CreatedAt:            row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:            uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:            row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:            uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt:            timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:            uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func writeHelicopterUsageErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	for i := range errs {
+		errs[i].Status = strconv.Itoa(status)
+	}
+	return response.WriteErrors(c, status, errs)
+}
diff --git a/internal/transport/http/handlers/hems_operation_category_handler.go b/internal/transport/http/handlers/hems_operation_category_handler.go
new file mode 100644
index 0000000..b6d09b3
--- /dev/null
+++ b/internal/transport/http/handlers/hems_operation_category_handler.go
@@ -0,0 +1,384 @@
+package handlers
+
+import (
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/operation"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type HEMSOperationCategoryHandler struct {
+	svc      operation.HEMSOperationCategoryService
+	validate *validators.Validator
+}
+
+func NewHEMSOperationCategoryHandler(svc operation.HEMSOperationCategoryService) *HEMSOperationCategoryHandler {
+	return &HEMSOperationCategoryHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateHEMSOperationCategory godoc
+// @Summary Create HEMS operation category
+// @Description Create a HEMS operation category.
+// @Tags Operation - Category
+// @Accept json
+// @Produce json
+// @Param request body dto.HEMSOperationCategoryCreateRequest true "JSON:API HEMS operation category create request"
+// @Success 201 {object} dto.HEMSOperationCategoryResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/hems-operation-category/create [post]
+func (h *HEMSOperationCategoryHandler) Create(c *fiber.Ctx) error {
+	var req dto.HEMSOperationCategoryCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	name := strings.TrimSpace(req.Data.Attributes.Name)
+	if name == "" {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+		}})
+	}
+	typeValue := strings.ToLower(strings.TrimSpace(req.Data.Attributes.Type))
+	if !operation.IsValidHEMSOperationCategoryType(typeValue) {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "type must be one of: first, secondary, misuse",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/type"},
+		}})
+	}
+
+	row := &operation.HEMSOperationCategory{
+		Name:      name,
+		Type:      typeValue,
+		CreatedBy: actorUserID(c),
+		UpdatedBy: actorUserID(c),
+	}
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, hemsOperationCategoryResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, hemsOperationCategoryResource(row))
+}
+
+// GetHEMSOperationCategory godoc
+// @Summary Get HEMS operation category by ID
+// @Tags Operation - Category
+// @Produce json
+// @Param uuid path string true "HEMS operation category UUID (UUIDv7)"
+// @Success 200 {object} dto.HEMSOperationCategoryResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/hems-operation-category/get/{uuid} [get]
+func (h *HEMSOperationCategoryHandler) Get(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || row == nil {
+		return response.WriteErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "hems operation category not found",
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, hemsOperationCategoryResource(row))
+}
+
+// UpdateHEMSOperationCategory godoc
+// @Summary Update HEMS operation category (partial)
+// @Tags Operation - Category
+// @Accept json
+// @Produce json
+// @Param uuid path string true "HEMS operation category UUID (UUIDv7)"
+// @Param request body dto.HEMSOperationCategoryUpdateRequest true "JSON:API HEMS operation category update request"
+// @Success 200 {object} dto.HEMSOperationCategoryResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/hems-operation-category/update/{uuid} [patch]
+func (h *HEMSOperationCategoryHandler) Update(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.HEMSOperationCategoryUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Name == nil && attrs.Type == nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return response.WriteErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "hems operation category not found",
+		}})
+	}
+	if attrs.Name != nil {
+		v := strings.TrimSpace(*attrs.Name)
+		if v == "" {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+			}})
+		}
+		existing.Name = v
+	}
+	if attrs.Type != nil {
+		v := strings.ToLower(strings.TrimSpace(*attrs.Type))
+		if !operation.IsValidHEMSOperationCategoryType(v) {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "type must be one of: first, secondary, misuse",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/type"},
+			}})
+		}
+		existing.Type = v
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, hemsOperationCategoryResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, hemsOperationCategoryResource(existing))
+}
+
+// DeleteHEMSOperationCategory godoc
+// @Summary Delete HEMS operation category
+// @Tags Operation - Category
+// @Produce json
+// @Param uuid path string true "HEMS operation category UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/hems-operation-category/delete/{uuid} [delete]
+func (h *HEMSOperationCategoryHandler) Delete(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		return writeDeleteError(c, err)
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "hems_operation_category_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListHEMSOperationCategory godoc
+// @Summary List HEMS operation categories
+// @Tags Operation - Category
+// @Produce json
+// @Param filter[search] query string false "Search by name/type"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.HEMSOperationCategoryListResponse
+// @Router /api/v1/hems-operation-category/get-all [get]
+func (h *HEMSOperationCategoryHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("search")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.HEMSOperationCategoryResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, hemsOperationCategoryResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListHEMSOperationCategoryDatatable godoc
+// @Summary List HEMS operation categories (datatable)
+// @Tags Operation - Category
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.HEMSOperationCategoryDataTableResponse
+// @Router /api/v1/hems-operation-category/get-all/dt [get]
+func (h *HEMSOperationCategoryHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.HEMSOperationCategoryResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, hemsOperationCategoryResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func hemsOperationCategoryResource(row *operation.HEMSOperationCategory) dto.HEMSOperationCategoryResource {
+	return dto.HEMSOperationCategoryResource{
+		Type: "hems_operation_category",
+		ID:   idString(row.ID),
+		Attributes: dto.HEMSOperationCategoryAttributes{
+			Name:      row.Name,
+			Type:      row.Type,
+			CreatedAt: row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy: uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt: row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy: uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt: timeStringOrEmpty(row.DeletedAt),
+			DeletedBy: uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
diff --git a/internal/transport/http/handlers/hems_operation_handler.go b/internal/transport/http/handlers/hems_operation_handler.go
new file mode 100644
index 0000000..9181f18
--- /dev/null
+++ b/internal/transport/http/handlers/hems_operation_handler.go
@@ -0,0 +1,430 @@
+package handlers
+
+import (
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/operation"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type HEMSOperationHandler struct {
+	svc      operation.HEMSOperationService
+	validate *validators.Validator
+}
+
+func NewHEMSOperationHandler(svc operation.HEMSOperationService) *HEMSOperationHandler {
+	return &HEMSOperationHandler{svc: svc, validate: validators.New()}
+}
+
+// CreateHEMSOperation godoc
+// @Summary Create HEMS operation
+// @Tags Operation - HEMS Operation
+// @Accept json
+// @Produce json
+// @Param request body dto.HEMSOperationCreateRequest true "JSON:API HEMS operation create request"
+// @Success 201 {object} dto.HEMSOperationResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/hems-operation/create [post]
+func (h *HEMSOperationHandler) Create(c *fiber.Ctx) error {
+	var req dto.HEMSOperationCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHEMSOperationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: safeInternalDetail()}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	dt, err := time.Parse(time.RFC3339, strings.TrimSpace(req.Data.Attributes.Date))
+	if err != nil {
+		return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422", Title: "Validation error", Detail: "date must be in RFC3339 format", Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/date"},
+		}})
+	}
+
+	row := &operation.HEMSOperation{Date: dt, CreatedBy: actorUserID(c), UpdatedBy: actorUserID(c)}
+	if req.Data.Attributes.OperationalDataID != nil {
+		parsed, errObj := parseOptionalUUID(req.Data.Attributes.OperationalDataID, "/data/attributes/operational_data_id")
+		if errObj != nil {
+			return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		row.OperationalDataID = parsed
+	}
+	if req.Data.Attributes.MissionID != nil {
+		parsed, errObj := parseOptionalUUID(req.Data.Attributes.MissionID, "/data/attributes/mission_id")
+		if errObj != nil {
+			return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		row.MissionID = parsed
+	}
+	if req.Data.Attributes.HEMSOperationCategoryID != nil {
+		parsed, errObj := parseOptionalUUID(req.Data.Attributes.HEMSOperationCategoryID, "/data/attributes/hems_operation_category_id")
+		if errObj != nil {
+			return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		row.HEMSOperationCategoryID = parsed
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		if status, errs, ok := mapOperationRelationError(err, map[string]relationFieldError{
+			"(`operational_data_id`)":                {Pointer: "/data/attributes/operational_data_id", Detail: "operational_data_id references data that does not exist"},
+			"(`hems_operation_category_id`)":         {Pointer: "/data/attributes/hems_operation_category_id", Detail: "hems_operation_category_id references data that does not exist"},
+			"(`mission_id`)":                         {Pointer: "/data/attributes/mission_id", Detail: "mission_id references data that does not exist"},
+			"references `hems_operational_data`":     {Pointer: "/data/attributes/operational_data_id", Detail: "operational_data_id references data that does not exist"},
+			"references `hems_operation_categories`": {Pointer: "/data/attributes/hems_operation_category_id", Detail: "hems_operation_category_id references data that does not exist"},
+			"references `missions`":                  {Pointer: "/data/attributes/mission_id", Detail: "mission_id references data that does not exist"},
+		}); ok {
+			return writeHEMSOperationErrors(c, status, errs)
+		}
+		return writeHEMSOperationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Create failed", Detail: safeInternalDetail()}})
+	}
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, hemsOperationResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, hemsOperationResource(row))
+}
+
+// GetHEMSOperation godoc
+// @Summary Get HEMS operation by ID
+// @Tags Operation - HEMS Operation
+// @Produce json
+// @Param uuid path string true "HEMS operation UUID (UUIDv7)"
+// @Success 200 {object} dto.HEMSOperationResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/hems-operation/get/{uuid} [get]
+func (h *HEMSOperationHandler) Get(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "uuid is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"}}})
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || row == nil {
+		return writeHEMSOperationErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "hems operation not found"}})
+	}
+	return response.Write(c, fiber.StatusOK, hemsOperationResource(row))
+}
+
+// UpdateHEMSOperation godoc
+// @Summary Update HEMS operation (partial)
+// @Tags Operation - HEMS Operation
+// @Accept json
+// @Produce json
+// @Param uuid path string true "HEMS operation UUID (UUIDv7)"
+// @Param request body dto.HEMSOperationUpdateRequest true "JSON:API HEMS operation update request"
+// @Success 200 {object} dto.HEMSOperationResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/hems-operation/update/{uuid} [patch]
+func (h *HEMSOperationHandler) Update(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "uuid is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"}}})
+	}
+
+	var req dto.HEMSOperationUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHEMSOperationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: safeInternalDetail()}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Date == nil && attrs.OperationalDataID == nil && attrs.MissionID == nil && attrs.HEMSOperationCategoryID == nil {
+		return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422", Title: "Validation error", Detail: "at least one attribute must be provided", Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeHEMSOperationErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "hems operation not found"}})
+	}
+
+	if attrs.Date != nil {
+		dt, err := time.Parse(time.RFC3339, strings.TrimSpace(*attrs.Date))
+		if err != nil {
+			return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422", Title: "Validation error", Detail: "date must be in RFC3339 format", Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/date"},
+			}})
+		}
+		existing.Date = dt
+	}
+	if attrs.OperationalDataID != nil {
+		parsed, errObj := parseOptionalUUID(attrs.OperationalDataID, "/data/attributes/operational_data_id")
+		if errObj != nil {
+			return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.OperationalDataID = parsed
+	}
+	if attrs.MissionID != nil {
+		parsed, errObj := parseOptionalUUID(attrs.MissionID, "/data/attributes/mission_id")
+		if errObj != nil {
+			return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.MissionID = parsed
+	}
+	if attrs.HEMSOperationCategoryID != nil {
+		parsed, errObj := parseOptionalUUID(attrs.HEMSOperationCategoryID, "/data/attributes/hems_operation_category_id")
+		if errObj != nil {
+			return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.HEMSOperationCategoryID = parsed
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		if status, errs, ok := mapOperationRelationError(err, map[string]relationFieldError{
+			"(`operational_data_id`)":                {Pointer: "/data/attributes/operational_data_id", Detail: "operational_data_id references data that does not exist"},
+			"(`hems_operation_category_id`)":         {Pointer: "/data/attributes/hems_operation_category_id", Detail: "hems_operation_category_id references data that does not exist"},
+			"(`mission_id`)":                         {Pointer: "/data/attributes/mission_id", Detail: "mission_id references data that does not exist"},
+			"references `hems_operational_data`":     {Pointer: "/data/attributes/operational_data_id", Detail: "operational_data_id references data that does not exist"},
+			"references `hems_operation_categories`": {Pointer: "/data/attributes/hems_operation_category_id", Detail: "hems_operation_category_id references data that does not exist"},
+			"references `missions`":                  {Pointer: "/data/attributes/mission_id", Detail: "mission_id references data that does not exist"},
+		}); ok {
+			return writeHEMSOperationErrors(c, status, errs)
+		}
+		return writeHEMSOperationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Update failed", Detail: safeInternalDetail()}})
+	}
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, hemsOperationResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, hemsOperationResource(existing))
+}
+
+// DeleteHEMSOperation godoc
+// @Summary Delete HEMS operation
+// @Tags Operation - HEMS Operation
+// @Produce json
+// @Param uuid path string true "HEMS operation UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/hems-operation/delete/{uuid} [delete]
+func (h *HEMSOperationHandler) Delete(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return writeHEMSOperationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "uuid is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"}}})
+	}
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeHEMSOperationErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "hems operation not found"}})
+		}
+		if status, errs, ok := mapOperationRelationError(err, nil); ok {
+			return writeHEMSOperationErrors(c, status, errs)
+		}
+		return writeHEMSOperationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Delete failed", Detail: safeInternalDetail()}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "hems_operation_delete", Attributes: map[string]any{"deleted": true}})
+}
+
+// ListHEMSOperation godoc
+// @Summary List HEMS operations
+// @Tags Operation - HEMS Operation
+// @Produce json
+// @Param filter[search] query string false "Search by date"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.HEMSOperationListResponse
+// @Router /api/v1/hems-operation/get-all [get]
+func (h *HEMSOperationHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("search")
+	}
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return writeHEMSOperationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "List failed", Detail: safeInternalDetail()}})
+	}
+	data := make([]dto.HEMSOperationResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, hemsOperationResource(&rows[i]).Data)
+	}
+	meta := map[string]any{"page_number": pageNumber, "page_size": pageSize, "total": total}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListHEMSOperationDatatable godoc
+// @Summary List HEMS operations (datatable)
+// @Tags Operation - HEMS Operation
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.HEMSOperationDataTableResponse
+// @Router /api/v1/hems-operation/get-all/dt [get]
+func (h *HEMSOperationHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return writeHEMSOperationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "List failed", Detail: safeInternalDetail()}})
+	}
+	data := make([]dto.HEMSOperationResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, hemsOperationResource(&rows[i]).Data)
+	}
+	meta := map[string]any{"draw": draw, "records_total": total, "records_filtered": total}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func hemsOperationResource(row *operation.HEMSOperation) dto.HEMSOperationResponse {
+	if row == nil {
+		return dto.HEMSOperationResponse{Data: dto.HEMSOperationResource{Type: "hems_operation"}}
+	}
+	operationalDataID := uuidStringOrEmpty(row.OperationalDataID)
+	missionID := uuidStringOrEmpty(row.MissionID)
+	categoryID := uuidStringOrEmpty(row.HEMSOperationCategoryID)
+
+	var operationalData *dto.HEMSOperationOperationalDataRef
+	if row.OperationalData != nil && len(row.OperationalData.ID) > 0 {
+		operationalData = &dto.HEMSOperationOperationalDataRef{ID: idString(row.OperationalData.ID)}
+	}
+	var mission *dto.HEMSOperationMissionRef
+	if row.Mission != nil && len(row.Mission.ID) > 0 {
+		mission = &dto.HEMSOperationMissionRef{
+			ID:       idString(row.Mission.ID),
+			FlightID: uuidStringOrEmpty(row.Mission.FlightID),
+			Type:     row.Mission.Type,
+		}
+	}
+	var category *dto.HEMSOperationCategoryRef
+	if row.HEMSOperationCategory != nil && len(row.HEMSOperationCategory.ID) > 0 {
+		category = &dto.HEMSOperationCategoryRef{ID: idString(row.HEMSOperationCategory.ID), Name: row.HEMSOperationCategory.Name, Type: row.HEMSOperationCategory.Type}
+	}
+
+	attrs := dto.HEMSOperationAttributes{
+		Date:                    row.Date.UTC().Format(time.RFC3339),
+		OperationalDataID:       operationalDataID,
+		MissionID:               missionID,
+		HEMSOperationCategoryID: categoryID,
+		OperationalData:         operationalData,
+		Mission:                 mission,
+		HEMSOperationCategory:   category,
+		CreatedAt:               row.CreatedAt.UTC().Format(time.RFC3339),
+		CreatedBy:               uuidStringOrEmpty(row.CreatedBy),
+		UpdatedAt:               row.UpdatedAt.UTC().Format(time.RFC3339),
+		UpdatedBy:               uuidStringOrEmpty(row.UpdatedBy),
+		DeletedAt:               timeStringOrEmpty(row.DeletedAt),
+		DeletedBy:               uuidStringOrEmpty(row.DeletedBy),
+	}
+
+	return dto.HEMSOperationResponse{Data: dto.HEMSOperationResource{Type: "hems_operation", ID: idString(row.ID), Attributes: attrs}}
+}
+
+func writeHEMSOperationErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		if strings.TrimSpace(e.Code) == "" || strings.TrimSpace(e.ErrorCode) == "" {
+			code, errorCode := inferHEMSOperationErrorCode(status, e.Title, e.Detail)
+			if strings.TrimSpace(e.Code) == "" {
+				e.Code = code
+			}
+			if strings.TrimSpace(e.ErrorCode) == "" {
+				e.ErrorCode = errorCode
+			}
+		}
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferHEMSOperationErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.CodeHEMSOperationNotFound, apperrorsx.ErrHEMSOperationNotFound.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid"):
+			return apperrorsx.CodeHEMSOperationInvalidUUID, apperrorsx.ErrHEMSOperationInvalidUUID.ErrorCode
+		case strings.Contains(lowerDetail, "at least one attribute"):
+			return apperrorsx.CodeHEMSOperationAttributesRequired, apperrorsx.ErrHEMSOperationAttributesRequired.ErrorCode
+		case strings.Contains(lowerDetail, "date must be in rfc3339"):
+			return apperrorsx.CodeHEMSOperationDateInvalidRFC3339, apperrorsx.ErrHEMSOperationDateInvalidRFC3339.ErrorCode
+		case strings.Contains(lowerDetail, "references data that does not exist"), strings.Contains(lowerDetail, "invalid uuid"):
+			return apperrorsx.CodeHEMSOperationRelationReferenceInvalid, apperrorsx.ErrHEMSOperationRelationReferenceInvalid.ErrorCode
+		default:
+			return apperrorsx.CodeHEMSOperationInvalidPayload, apperrorsx.ErrHEMSOperationInvalidPayload.ErrorCode
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.CodeHEMSOperationInvalidJSON, apperrorsx.ErrHEMSOperationInvalidJSON.ErrorCode
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.CodeHEMSOperationCreateFailed, apperrorsx.ErrHEMSOperationCreateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.CodeHEMSOperationUpdateFailed, apperrorsx.ErrHEMSOperationUpdateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.CodeHEMSOperationDeleteFailed, apperrorsx.ErrHEMSOperationDeleteFailed.ErrorCode
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.CodeHEMSOperationListFailed, apperrorsx.ErrHEMSOperationListFailed.ErrorCode
+		default:
+			return apperrorsx.CodeInvalidRequest, apperrorsx.ErrInvalidRequest.ErrorCode
+		}
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
diff --git a/internal/transport/http/handlers/hems_operational_data_handler.go b/internal/transport/http/handlers/hems_operational_data_handler.go
new file mode 100644
index 0000000..5961966
--- /dev/null
+++ b/internal/transport/http/handlers/hems_operational_data_handler.go
@@ -0,0 +1,759 @@
+package handlers
+
+import (
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/operation"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type HEMSOperationalDataHandler struct {
+	svc      operation.HEMSOperationalDataService
+	fileSvc  filemanager.Service
+	validate *validators.Validator
+}
+
+func NewHEMSOperationalDataHandler(svc operation.HEMSOperationalDataService) *HEMSOperationalDataHandler {
+	return &HEMSOperationalDataHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+func (h *HEMSOperationalDataHandler) WithFileManagerService(fileSvc filemanager.Service) *HEMSOperationalDataHandler {
+	h.fileSvc = fileSvc
+	return h
+}
+
+// CreateHEMSOperationalData godoc
+// @Summary Create HEMS operational data
+// @Description Create a HEMS operational data record.
+// @Tags Operation - HEMS Operational Data
+// @Accept json
+// @Produce json
+// @Param request body dto.HEMSOperationalDataCreateRequest true "JSON:API HEMS operational data create request"
+// @Success 201 {object} dto.HEMSOperationalDataResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/hems-operational-data/create [post]
+func (h *HEMSOperationalDataHandler) Create(c *fiber.Ctx) error {
+	var req dto.HEMSOperationalDataCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	attrs := req.Data.Attributes
+	tm, err := time.Parse(time.RFC3339, strings.TrimSpace(attrs.Time))
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "time must be in RFC3339 format",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/time"},
+		}})
+	}
+
+	location := strings.TrimSpace(attrs.Location)
+	if location == "" {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "location is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/location"},
+		}})
+	}
+
+	row := &operation.HEMSOperationalData{
+		Time:           tm,
+		Location:       location,
+		Postcode:       strings.TrimSpace(stringOrDefault(attrs.Postcode, "")),
+		Notes:          strings.TrimSpace(stringOrDefault(attrs.Notes, "")),
+		TerrainIndex:   strings.TrimSpace(stringOrDefault(attrs.TerrainIndex, "")),
+		AdditionalInfo: strings.TrimSpace(stringOrDefault(attrs.AdditionalInfo, "")),
+		CreatedBy:      actorUserID(c),
+		UpdatedBy:      actorUserID(c),
+	}
+
+	if attrs.Darkness != nil {
+		row.Darkness = *attrs.Darkness
+	}
+	if attrs.FalseInformation != nil {
+		row.FalseInformation = *attrs.FalseInformation
+	}
+	if attrs.Fog != nil {
+		row.Fog = *attrs.Fog
+	}
+	if attrs.Precipitation != nil {
+		row.Precipitation = *attrs.Precipitation
+	}
+	if attrs.MountainUse != nil {
+		row.MountainUse = *attrs.MountainUse
+	}
+	if attrs.Wind != nil {
+		row.Wind = *attrs.Wind
+	}
+	if attrs.NFOSearch != nil {
+		row.NFOSearch = *attrs.NFOSearch
+	}
+	if attrs.LandingSiteSearch != nil {
+		row.LandingSiteSearch = *attrs.LandingSiteSearch
+	}
+	if attrs.Temperature != nil {
+		row.Temperature = *attrs.Temperature
+	}
+	if attrs.Altitude != nil {
+		row.Altitude = *attrs.Altitude
+	}
+	if attrs.RopeRecovery != nil {
+		row.RopeRecovery = *attrs.RopeRecovery
+	}
+	if attrs.NightFlight != nil {
+		row.NightFlight = *attrs.NightFlight
+	}
+	if attrs.InstrumentFlight != nil {
+		row.InstrumentFlight = *attrs.InstrumentFlight
+	}
+
+	if attrs.LandID != nil {
+		parsed, errObj := parseOptionalUUID(attrs.LandID, "/data/attributes/land_id")
+		if errObj != nil {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		row.LandID = parsed
+	}
+	if attrs.VocationID != nil {
+		parsed, errObj := parseOptionalUUID(attrs.VocationID, "/data/attributes/vocation_id")
+		if errObj != nil {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		row.VocationID = parsed
+	}
+	seenForcePresent := make(map[string]struct{}, len(attrs.ForcePresentIDs))
+	for i := range attrs.ForcePresentIDs {
+		raw := strings.TrimSpace(attrs.ForcePresentIDs[i])
+		if raw == "" {
+			continue
+		}
+		if _, ok := seenForcePresent[raw]; ok {
+			continue
+		}
+		id, err := uuidv7.ParseString(raw)
+		if err != nil {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "force_present_ids contains invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/force_present_ids"},
+			}})
+		}
+		seenForcePresent[raw] = struct{}{}
+		row.ForcePresents = append(row.ForcePresents, operation.OperationalDataForcePresent{ForcePresentID: id})
+	}
+	if attrs.StateID != nil {
+		parsed, errObj := parseOptionalUUID(attrs.StateID, "/data/attributes/state_id")
+		if errObj != nil {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		row.StateID = parsed
+	}
+
+	seen := make(map[string]struct{}, len(attrs.FileAttachmentIDs))
+	for i := range attrs.FileAttachmentIDs {
+		raw := strings.TrimSpace(attrs.FileAttachmentIDs[i])
+		if raw == "" {
+			continue
+		}
+		if _, ok := seen[raw]; ok {
+			continue
+		}
+		attachmentID, err := uuidv7.ParseString(raw)
+		if err != nil {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "file_attachment_ids contains invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/file_attachment_ids"},
+			}})
+		}
+		seen[raw] = struct{}{}
+		row.Files = append(row.Files, operation.OperationalFile{FileAttachmentID: attachmentID})
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		if status, errs, ok := mapOperationRelationError(err, map[string]relationFieldError{
+			"(`land_id`)":                 {Pointer: "/data/attributes/land_id", Detail: "land_id references data that does not exist"},
+			"(`vocation_id`)":             {Pointer: "/data/attributes/vocation_id", Detail: "vocation_id references data that does not exist"},
+			"(`state_id`)":                {Pointer: "/data/attributes/state_id", Detail: "state_id references data that does not exist"},
+			"(`force_present_id`)":        {Pointer: "/data/attributes/force_present_ids", Detail: "one or more force_present_ids reference data that does not exist"},
+			"(`file_attachment_id`)":      {Pointer: "/data/attributes/file_attachment_ids", Detail: "one or more file_attachment_ids reference data that does not exist"},
+			"references `lands`":          {Pointer: "/data/attributes/land_id", Detail: "land_id references data that does not exist"},
+			"references `vocations`":      {Pointer: "/data/attributes/vocation_id", Detail: "vocation_id references data that does not exist"},
+			"references `federal_states`": {Pointer: "/data/attributes/state_id", Detail: "state_id references data that does not exist"},
+			"references `forces_present`": {Pointer: "/data/attributes/force_present_ids", Detail: "one or more force_present_ids reference data that does not exist"},
+			"references `attachments`":    {Pointer: "/data/attributes/file_attachment_ids", Detail: "one or more file_attachment_ids reference data that does not exist"},
+		}); ok {
+			return response.WriteErrors(c, status, errs)
+		}
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if err := syncAttachmentLifecycleSet(c.UserContext(), h.fileSvc, nil, operationalFileAttachmentIDs(row.Files), actorUserID(c)); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, hemsOperationalDataResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, hemsOperationalDataResource(row))
+}
+
+// GetHEMSOperationalData godoc
+// @Summary Get HEMS operational data by ID
+// @Tags Operation - HEMS Operational Data
+// @Produce json
+// @Param uuid path string true "HEMS operational data UUID (UUIDv7)"
+// @Success 200 {object} dto.HEMSOperationalDataResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/hems-operational-data/get/{uuid} [get]
+func (h *HEMSOperationalDataHandler) Get(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || row == nil {
+		return response.WriteErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "hems operational data not found",
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, hemsOperationalDataResource(row))
+}
+
+// UpdateHEMSOperationalData godoc
+// @Summary Update HEMS operational data (partial)
+// @Tags Operation - HEMS Operational Data
+// @Accept json
+// @Produce json
+// @Param uuid path string true "HEMS operational data UUID (UUIDv7)"
+// @Param request body dto.HEMSOperationalDataUpdateRequest true "JSON:API HEMS operational data update request"
+// @Success 200 {object} dto.HEMSOperationalDataResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/hems-operational-data/update/{uuid} [patch]
+func (h *HEMSOperationalDataHandler) Update(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.HEMSOperationalDataUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Time == nil && attrs.LandID == nil && attrs.VocationID == nil &&
+		attrs.ForcePresentIDs == nil && attrs.StateID == nil && attrs.Location == nil &&
+		attrs.Postcode == nil && attrs.Notes == nil && attrs.Darkness == nil &&
+		attrs.FalseInformation == nil && attrs.Fog == nil && attrs.Precipitation == nil &&
+		attrs.MountainUse == nil && attrs.Wind == nil && attrs.NFOSearch == nil &&
+		attrs.LandingSiteSearch == nil && attrs.Temperature == nil && attrs.Altitude == nil &&
+		attrs.TerrainIndex == nil && attrs.RopeRecovery == nil && attrs.NightFlight == nil &&
+		attrs.InstrumentFlight == nil && attrs.AdditionalInfo == nil && attrs.FileAttachmentIDs == nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return response.WriteErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "hems operational data not found",
+		}})
+	}
+	prevAttachmentIDs := operationalFileAttachmentIDs(existing.Files)
+
+	if attrs.Time != nil {
+		tm, err := time.Parse(time.RFC3339, strings.TrimSpace(*attrs.Time))
+		if err != nil {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "time must be in RFC3339 format",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/time"},
+			}})
+		}
+		existing.Time = tm
+	}
+	if attrs.LandID != nil {
+		parsed, errObj := parseOptionalUUID(attrs.LandID, "/data/attributes/land_id")
+		if errObj != nil {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.LandID = parsed
+	}
+	if attrs.VocationID != nil {
+		parsed, errObj := parseOptionalUUID(attrs.VocationID, "/data/attributes/vocation_id")
+		if errObj != nil {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.VocationID = parsed
+	}
+	if attrs.ForcePresentIDs != nil {
+		existing.ForcePresents = existing.ForcePresents[:0]
+		seen := make(map[string]struct{}, len(*attrs.ForcePresentIDs))
+		for i := range *attrs.ForcePresentIDs {
+			raw := strings.TrimSpace((*attrs.ForcePresentIDs)[i])
+			if raw == "" {
+				continue
+			}
+			if _, ok := seen[raw]; ok {
+				continue
+			}
+			id, err := uuidv7.ParseString(raw)
+			if err != nil {
+				return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+					Status: "422",
+					Title:  "Validation error",
+					Detail: "force_present_ids contains invalid UUID",
+					Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/force_present_ids"},
+				}})
+			}
+			seen[raw] = struct{}{}
+			existing.ForcePresents = append(existing.ForcePresents, operation.OperationalDataForcePresent{ForcePresentID: id})
+		}
+	}
+	if attrs.StateID != nil {
+		parsed, errObj := parseOptionalUUID(attrs.StateID, "/data/attributes/state_id")
+		if errObj != nil {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		existing.StateID = parsed
+	}
+	if attrs.Location != nil {
+		v := strings.TrimSpace(*attrs.Location)
+		if v == "" {
+			return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "location cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/location"},
+			}})
+		}
+		existing.Location = v
+	}
+	if attrs.Postcode != nil {
+		existing.Postcode = strings.TrimSpace(*attrs.Postcode)
+	}
+	if attrs.Notes != nil {
+		existing.Notes = strings.TrimSpace(*attrs.Notes)
+	}
+	if attrs.Darkness != nil {
+		existing.Darkness = *attrs.Darkness
+	}
+	if attrs.FalseInformation != nil {
+		existing.FalseInformation = *attrs.FalseInformation
+	}
+	if attrs.Fog != nil {
+		existing.Fog = *attrs.Fog
+	}
+	if attrs.Precipitation != nil {
+		existing.Precipitation = *attrs.Precipitation
+	}
+	if attrs.MountainUse != nil {
+		existing.MountainUse = *attrs.MountainUse
+	}
+	if attrs.Wind != nil {
+		existing.Wind = *attrs.Wind
+	}
+	if attrs.NFOSearch != nil {
+		existing.NFOSearch = *attrs.NFOSearch
+	}
+	if attrs.LandingSiteSearch != nil {
+		existing.LandingSiteSearch = *attrs.LandingSiteSearch
+	}
+	if attrs.Temperature != nil {
+		existing.Temperature = *attrs.Temperature
+	}
+	if attrs.Altitude != nil {
+		existing.Altitude = *attrs.Altitude
+	}
+	if attrs.TerrainIndex != nil {
+		existing.TerrainIndex = strings.TrimSpace(*attrs.TerrainIndex)
+	}
+	if attrs.RopeRecovery != nil {
+		existing.RopeRecovery = *attrs.RopeRecovery
+	}
+	if attrs.NightFlight != nil {
+		existing.NightFlight = *attrs.NightFlight
+	}
+	if attrs.InstrumentFlight != nil {
+		existing.InstrumentFlight = *attrs.InstrumentFlight
+	}
+	if attrs.AdditionalInfo != nil {
+		existing.AdditionalInfo = strings.TrimSpace(*attrs.AdditionalInfo)
+	}
+
+	if attrs.FileAttachmentIDs != nil {
+		existing.Files = existing.Files[:0]
+		seen := make(map[string]struct{}, len(*attrs.FileAttachmentIDs))
+		for i := range *attrs.FileAttachmentIDs {
+			raw := strings.TrimSpace((*attrs.FileAttachmentIDs)[i])
+			if raw == "" {
+				continue
+			}
+			if _, ok := seen[raw]; ok {
+				continue
+			}
+			attachmentID, err := uuidv7.ParseString(raw)
+			if err != nil {
+				return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+					Status: "422",
+					Title:  "Validation error",
+					Detail: "file_attachment_ids contains invalid UUID",
+					Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/file_attachment_ids"},
+				}})
+			}
+			seen[raw] = struct{}{}
+			existing.Files = append(existing.Files, operation.OperationalFile{FileAttachmentID: attachmentID})
+		}
+	}
+
+	existing.UpdatedBy = actorUserID(c)
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		if status, errs, ok := mapOperationRelationError(err, map[string]relationFieldError{
+			"(`land_id`)":                 {Pointer: "/data/attributes/land_id", Detail: "land_id references data that does not exist"},
+			"(`vocation_id`)":             {Pointer: "/data/attributes/vocation_id", Detail: "vocation_id references data that does not exist"},
+			"(`state_id`)":                {Pointer: "/data/attributes/state_id", Detail: "state_id references data that does not exist"},
+			"(`force_present_id`)":        {Pointer: "/data/attributes/force_present_ids", Detail: "one or more force_present_ids reference data that does not exist"},
+			"(`file_attachment_id`)":      {Pointer: "/data/attributes/file_attachment_ids", Detail: "one or more file_attachment_ids reference data that does not exist"},
+			"references `lands`":          {Pointer: "/data/attributes/land_id", Detail: "land_id references data that does not exist"},
+			"references `vocations`":      {Pointer: "/data/attributes/vocation_id", Detail: "vocation_id references data that does not exist"},
+			"references `federal_states`": {Pointer: "/data/attributes/state_id", Detail: "state_id references data that does not exist"},
+			"references `forces_present`": {Pointer: "/data/attributes/force_present_ids", Detail: "one or more force_present_ids reference data that does not exist"},
+			"references `attachments`":    {Pointer: "/data/attributes/file_attachment_ids", Detail: "one or more file_attachment_ids reference data that does not exist"},
+		}); ok {
+			return response.WriteErrors(c, status, errs)
+		}
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if err := syncAttachmentLifecycleSet(c.UserContext(), h.fileSvc, prevAttachmentIDs, operationalFileAttachmentIDs(existing.Files), actorUserID(c)); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, hemsOperationalDataResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, hemsOperationalDataResource(existing))
+}
+
+// DeleteHEMSOperationalData godoc
+// @Summary Delete HEMS operational data
+// @Tags Operation - HEMS Operational Data
+// @Produce json
+// @Param uuid path string true "HEMS operational data UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/hems-operational-data/delete/{uuid} [delete]
+func (h *HEMSOperationalDataHandler) Delete(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+	existing, _ := h.svc.GetByID(c.UserContext(), id)
+	var prevAttachmentIDs [][]byte
+	if existing != nil {
+		prevAttachmentIDs = operationalFileAttachmentIDs(existing.Files)
+	}
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return response.WriteErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "hems operational data not found",
+			}})
+		}
+		if status, errs, ok := mapOperationRelationError(err, nil); ok {
+			return response.WriteErrors(c, status, errs)
+		}
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if err := syncAttachmentLifecycleSet(c.UserContext(), h.fileSvc, prevAttachmentIDs, nil, actorUserID(c)); err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "hems_operational_data_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+func operationalFileAttachmentIDs(files []operation.OperationalFile) [][]byte {
+	out := make([][]byte, 0, len(files))
+	for i := range files {
+		if len(files[i].FileAttachmentID) != 16 {
+			continue
+		}
+		out = append(out, append([]byte(nil), files[i].FileAttachmentID...))
+	}
+	return out
+}
+
+// ListHEMSOperationalData godoc
+// @Summary List HEMS operational data
+// @Tags Operation - HEMS Operational Data
+// @Produce json
+// @Param filter[search] query string false "Search by location/notes/additional_info/terrain_index"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.HEMSOperationalDataListResponse
+// @Router /api/v1/hems-operational-data/get-all [get]
+func (h *HEMSOperationalDataHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("search")
+	}
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	data := make([]dto.HEMSOperationalDataResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, hemsOperationalDataResource(&rows[i]).Data)
+	}
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListHEMSOperationalDataDatatable godoc
+// @Summary List HEMS operational data (datatable)
+// @Tags Operation - HEMS Operational Data
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.HEMSOperationalDataDataTableResponse
+// @Router /api/v1/hems-operational-data/get-all/dt [get]
+func (h *HEMSOperationalDataHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return response.WriteErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	data := make([]dto.HEMSOperationalDataResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, hemsOperationalDataResource(&rows[i]).Data)
+	}
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func hemsOperationalDataResource(row *operation.HEMSOperationalData) dto.HEMSOperationalDataResponse {
+	if row == nil {
+		return dto.HEMSOperationalDataResponse{Data: dto.HEMSOperationalDataResource{Type: "hems_operational_data"}}
+	}
+
+	id, _ := uuidv7.BytesToString(row.ID)
+	landID, _ := uuidv7.BytesToString(row.LandID)
+	vocationID, _ := uuidv7.BytesToString(row.VocationID)
+	stateID, _ := uuidv7.BytesToString(row.StateID)
+	createdBy, _ := uuidv7.BytesToString(row.CreatedBy)
+	updatedBy, _ := uuidv7.BytesToString(row.UpdatedBy)
+	deletedBy, _ := uuidv7.BytesToString(row.DeletedBy)
+
+	files := make([]dto.HEMSOperationalDataFileAttributes, 0, len(row.Files))
+	for i := range row.Files {
+		fileID, _ := uuidv7.BytesToString(row.Files[i].ID)
+		attachmentID, _ := uuidv7.BytesToString(row.Files[i].FileAttachmentID)
+		files = append(files, dto.HEMSOperationalDataFileAttributes{
+			ID:               fileID,
+			FileAttachmentID: attachmentID,
+		})
+	}
+	forcePresentIDs := make([]string, 0, len(row.ForcePresents))
+	for i := range row.ForcePresents {
+		forcePresentIDs = append(forcePresentIDs, uuidStringOrEmpty(row.ForcePresents[i].ForcePresentID))
+	}
+
+	attrs := dto.HEMSOperationalDataAttributes{
+		Time:              row.Time.UTC().Format(time.RFC3339),
+		LandID:            landID,
+		VocationID:        vocationID,
+		ForcePresentIDs:   forcePresentIDs,
+		StateID:           stateID,
+		Location:          row.Location,
+		Postcode:          row.Postcode,
+		Notes:             row.Notes,
+		Darkness:          row.Darkness,
+		FalseInformation:  row.FalseInformation,
+		Fog:               row.Fog,
+		Precipitation:     row.Precipitation,
+		MountainUse:       row.MountainUse,
+		Wind:              row.Wind,
+		NFOSearch:         row.NFOSearch,
+		LandingSiteSearch: row.LandingSiteSearch,
+		Temperature:       row.Temperature,
+		Altitude:          row.Altitude,
+		TerrainIndex:      row.TerrainIndex,
+		RopeRecovery:      row.RopeRecovery,
+		NightFlight:       row.NightFlight,
+		InstrumentFlight:  row.InstrumentFlight,
+		AdditionalInfo:    row.AdditionalInfo,
+		Files:             files,
+		CreatedBy:         createdBy,
+		UpdatedBy:         updatedBy,
+		DeletedBy:         deletedBy,
+	}
+	if !row.CreatedAt.IsZero() {
+		attrs.CreatedAt = row.CreatedAt.UTC().Format(time.RFC3339)
+	}
+	if !row.UpdatedAt.IsZero() {
+		attrs.UpdatedAt = row.UpdatedAt.UTC().Format(time.RFC3339)
+	}
+	if row.DeletedAt != nil {
+		attrs.DeletedAt = row.DeletedAt.UTC().Format(time.RFC3339)
+	}
+
+	return dto.HEMSOperationalDataResponse{
+		Data: dto.HEMSOperationalDataResource{
+			Type:       "hems_operational_data",
+			ID:         id,
+			Attributes: attrs,
+		},
+	}
+}
diff --git a/internal/transport/http/handlers/hospital_handler.go b/internal/transport/http/handlers/hospital_handler.go
new file mode 100644
index 0000000..c4df7c4
--- /dev/null
+++ b/internal/transport/http/handlers/hospital_handler.go
@@ -0,0 +1,460 @@
+package handlers
+
+import (
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/hospital"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type HospitalHandler struct {
+	svc      hospital.Service
+	validate *validators.Validator
+}
+
+func NewHospitalHandler(svc hospital.Service) *HospitalHandler {
+	return &HospitalHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateHospital godoc
+// @Summary Create hospital
+// @Description Create a hospital row.
+// @Tags Hospital - Hospital
+// @Accept json
+// @Produce json
+// @Param request body dto.HospitalCreateRequest true "JSON:API hospital create request"
+// @Success 201 {object} dto.HospitalResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/hospital/create [post]
+func (h *HospitalHandler) Create(c *fiber.Ctx) error {
+	var req dto.HospitalCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHospitalErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHospitalErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	name := strings.TrimSpace(req.Data.Attributes.Name)
+	if name == "" {
+		return writeHospitalErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+		}})
+	}
+
+	row := &hospital.Hospital{
+		Name:           name,
+		SortKey:        cloneIntPointer(req.Data.Attributes.SortKey),
+		Address:        strings.TrimSpace(stringOrDefault(req.Data.Attributes.Address, "")),
+		LandlineNumber: strings.TrimSpace(stringOrDefault(req.Data.Attributes.LandlineNumber, "")),
+		MobileNumber:   strings.TrimSpace(stringOrDefault(req.Data.Attributes.MobileNumber, "")),
+		Email:          strings.TrimSpace(stringOrDefault(req.Data.Attributes.Email, "")),
+		Note:           strings.TrimSpace(stringOrDefault(req.Data.Attributes.Note, "")),
+		IsActive:       boolOrDefault(req.Data.Attributes.IsActive, true),
+		CreatedBy:      actorUserID(c),
+		UpdatedBy:      actorUserID(c),
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return apperrorsx.Write(c, mapHospitalServiceErrorWithFallback(err, apperrorsx.ErrHospitalCreateFailed))
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, hospitalResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, hospitalResource(row))
+}
+
+// UpdateHospital godoc
+// @Summary Update hospital (partial)
+// @Description Patch hospital by ID.
+// @Tags Hospital - Hospital
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Hospital UUID (UUIDv7)"
+// @Param request body dto.HospitalUpdateRequest true "JSON:API hospital update request"
+// @Success 200 {object} dto.HospitalResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/hospital/update/{uuid} [patch]
+func (h *HospitalHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeHospitalErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.HospitalUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeHospitalErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeHospitalErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeHospitalErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeHospitalErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Name == nil && !attrs.SortKey.Set && attrs.Address == nil && attrs.LandlineNumber == nil && attrs.MobileNumber == nil && attrs.Email == nil && attrs.Note == nil && attrs.IsActive == nil {
+		return writeHospitalErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeHospitalErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "hospital not found",
+		}})
+	}
+
+	if attrs.Name != nil {
+		v := strings.TrimSpace(*attrs.Name)
+		if v == "" {
+			return writeHospitalErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+			}})
+		}
+		existing.Name = v
+	}
+	if attrs.SortKey.Set {
+		if attrs.SortKey.Valid {
+			sortKey := attrs.SortKey.Value
+			existing.SortKey = &sortKey
+		} else {
+			existing.SortKey = nil
+		}
+	}
+	if attrs.Address != nil {
+		existing.Address = strings.TrimSpace(*attrs.Address)
+	}
+	if attrs.LandlineNumber != nil {
+		existing.LandlineNumber = strings.TrimSpace(*attrs.LandlineNumber)
+	}
+	if attrs.MobileNumber != nil {
+		existing.MobileNumber = strings.TrimSpace(*attrs.MobileNumber)
+	}
+	if attrs.Email != nil {
+		existing.Email = strings.TrimSpace(*attrs.Email)
+	}
+	if attrs.Note != nil {
+		existing.Note = strings.TrimSpace(*attrs.Note)
+	}
+	if attrs.IsActive != nil {
+		existing.IsActive = *attrs.IsActive
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return apperrorsx.Write(c, mapHospitalServiceErrorWithFallback(err, apperrorsx.ErrHospitalUpdateFailed))
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, hospitalResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, hospitalResource(existing))
+}
+
+// DeleteHospital godoc
+// @Summary Delete hospital
+// @Tags Hospital - Hospital
+// @Produce json
+// @Param uuid path string true "Hospital UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/hospital/delete/{uuid} [delete]
+func (h *HospitalHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeHospitalErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		return apperrorsx.Write(c, mapHospitalServiceErrorWithFallback(err, apperrorsx.ErrHospitalDeleteFailed))
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "hospital_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListHospital godoc
+// @Summary List hospital
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: name, -name, hospital_name, -hospital_name, sortkey, -sortkey, address, -address, landline_number, -landline_number, mobile_number, -mobile_number, email, -email, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.
+// @Tags Hospital - Hospital
+// @Produce json
+// @Param filter[search] query string false "Search by hospital name/address/contact"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.HospitalListResponse
+// @Router /api/v1/hospital/get-all [get]
+func (h *HospitalHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("filter[name]")
+	}
+	if filter == "" {
+		filter = c.Query("search")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return apperrorsx.Write(c, mapHospitalServiceErrorWithFallback(err, apperrorsx.ErrHospitalListFailed))
+	}
+
+	data := make([]dto.HospitalResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, hospitalResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListHospitalDatatable godoc
+// @Summary List hospital (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags Hospital - Hospital
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.HospitalDataTableResponse
+// @Router /api/v1/hospital/get-all/dt [get]
+func (h *HospitalHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return apperrorsx.Write(c, mapHospitalServiceErrorWithFallback(err, apperrorsx.ErrHospitalListFailed))
+	}
+
+	data := make([]dto.HospitalResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, hospitalResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func hospitalResource(row *hospital.Hospital) dto.HospitalResource {
+	return dto.HospitalResource{
+		Type: "hospital",
+		ID:   idString(row.ID),
+		Attributes: dto.HospitalAttributes{
+			Name:           row.Name,
+			SortKey:        cloneIntPointer(row.SortKey),
+			Address:        row.Address,
+			LandlineNumber: row.LandlineNumber,
+			MobileNumber:   row.MobileNumber,
+			Email:          row.Email,
+			Note:           row.Note,
+			IsActive:       row.IsActive,
+			CreatedAt:      row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:      uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:      row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:      uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt:      timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:      uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func writeHospitalErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	statusStr := strconv.Itoa(status)
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		if strings.TrimSpace(e.Code) == "" || strings.TrimSpace(e.ErrorCode) == "" {
+			code, errorCode := inferHospitalErrorCode(status, e.Title, e.Detail)
+			if strings.TrimSpace(e.Code) == "" {
+				e.Code = code
+			}
+			if strings.TrimSpace(e.ErrorCode) == "" {
+				e.ErrorCode = errorCode
+			}
+		}
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferHospitalErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.CodeHospitalNotFound, apperrorsx.ErrHospitalNotFound.ErrorCode
+	case fiber.StatusConflict:
+		return apperrorsx.CodeHospitalRelationDelete, apperrorsx.ErrHospitalRelationDelete.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid uuid"):
+			return apperrorsx.CodeHospitalInvalidUUID, apperrorsx.ErrHospitalInvalidUUID.ErrorCode
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.CodeHospitalIDRequired, apperrorsx.ErrHospitalIDRequired.ErrorCode
+		case strings.Contains(lowerDetail, "id does not match path uuid"):
+			return apperrorsx.CodeHospitalIDMismatch, apperrorsx.ErrHospitalIDMismatch.ErrorCode
+		case strings.Contains(lowerDetail, "at least one attribute must be provided"):
+			return apperrorsx.CodeHospitalAttributesRequired, apperrorsx.ErrHospitalAttributesRequired.ErrorCode
+		case strings.Contains(lowerDetail, "name is required"), strings.Contains(lowerDetail, "name cannot be empty"):
+			return apperrorsx.CodeHospitalNameRequired, apperrorsx.ErrHospitalNameRequired.ErrorCode
+		default:
+			return apperrorsx.CodeHospitalInvalidPayload, apperrorsx.ErrHospitalInvalidPayload.ErrorCode
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.CodeHospitalInvalidJSON, apperrorsx.ErrHospitalInvalidJSON.ErrorCode
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.CodeHospitalCreateFailed, apperrorsx.ErrHospitalCreateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.CodeHospitalUpdateFailed, apperrorsx.ErrHospitalUpdateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.CodeHospitalDeleteFailed, apperrorsx.ErrHospitalDeleteFailed.ErrorCode
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.CodeHospitalListFailed, apperrorsx.ErrHospitalListFailed.ErrorCode
+		default:
+			return apperrorsx.CodeHospitalInvalidPayload, apperrorsx.ErrHospitalInvalidPayload.ErrorCode
+		}
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
+
+func mapHospitalServiceErrorWithFallback(err error, fallback apperrorsx.Def) *apperrorsx.AppError {
+	mapped := apperrorsx.Translate(apperrorsx.ModuleHospital, err)
+	if mapped == nil {
+		return apperrorsx.New(fallback).WithCause(err)
+	}
+
+	switch mapped.Code {
+	case apperrorsx.CodeHospitalNotFound,
+		apperrorsx.CodeHospitalRelationDelete,
+		apperrorsx.CodeHospitalInvalidPayload:
+		return mapped
+	default:
+		return apperrorsx.New(fallback).WithCause(err)
+	}
+}
diff --git a/internal/transport/http/handlers/hospital_handler_test.go b/internal/transport/http/handlers/hospital_handler_test.go
new file mode 100644
index 0000000..e0b7324
--- /dev/null
+++ b/internal/transport/http/handlers/hospital_handler_test.go
@@ -0,0 +1,643 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/hospital"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type memHospitalRepo struct {
+	rows map[string]*hospital.Hospital
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+
+	listRows  []hospital.Hospital
+	listTotal int64
+
+	getByIDFn func(id []byte, call int) (*hospital.Hospital, error)
+	getCalls  int
+
+	lastCreate     *hospital.Hospital
+	lastUpdate     *hospital.Hospital
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+}
+
+func newMemHospitalRepo() *memHospitalRepo {
+	return &memHospitalRepo{rows: map[string]*hospital.Hospital{}}
+}
+
+func (r *memHospitalRepo) Create(_ context.Context, row *hospital.Hospital) error {
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.rows[string(row.ID)] = row
+	r.lastCreate = row
+	return nil
+}
+
+func (r *memHospitalRepo) Update(_ context.Context, row *hospital.Hospital) error {
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	r.rows[string(row.ID)] = row
+	r.lastUpdate = row
+	return nil
+}
+
+func (r *memHospitalRepo) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	r.lastDeleteID = append([]byte(nil), id...)
+	r.lastDeleteBy = append([]byte(nil), deletedBy...)
+	delete(r.rows, string(id))
+	return nil
+}
+
+func (r *memHospitalRepo) GetByID(_ context.Context, id []byte) (*hospital.Hospital, error) {
+	r.getCalls++
+	if r.getByIDFn != nil {
+		return r.getByIDFn(id, r.getCalls)
+	}
+	if r.getByIDErr != nil {
+		return nil, r.getByIDErr
+	}
+	return r.rows[string(id)], nil
+}
+
+func (r *memHospitalRepo) List(_ context.Context, filter, sort string, limit, offset int) ([]hospital.Hospital, int64, error) {
+	r.lastListFilter = filter
+	r.lastListSort = sort
+	r.lastListLimit = limit
+	r.lastListOffset = offset
+	if r.listErr != nil {
+		return nil, 0, r.listErr
+	}
+	return r.listRows, r.listTotal, nil
+}
+
+func newHospitalTestApp(h *HospitalHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", actor)
+		}
+		return c.Next()
+	})
+	app.Post("/api/v1/hospital/create", h.Create)
+	app.Patch("/api/v1/hospital/update/:uuid", h.Update)
+	app.Delete("/api/v1/hospital/delete/:uuid", h.Delete)
+	app.Get("/api/v1/hospital/get-all", h.List)
+	app.Get("/api/v1/hospital/get-all/dt", h.ListDatatable)
+	return app
+}
+
+func doJSONRequestHospital(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func assertContainsHospital(t *testing.T, body []byte, substr string) {
+	t.Helper()
+	if !strings.Contains(string(body), substr) {
+		t.Fatalf("expected response contain %q, got %s", substr, string(body))
+	}
+}
+
+func mustUUIDStringHospital(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestNewHospitalHandler(t *testing.T) {
+	h := NewHospitalHandler(service.NewHospitalService(newMemHospitalRepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+func TestHospitalHandlerCreate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		resp, body := doJSONRequestHospital(t, app, http.MethodPost, "/api/v1/hospital/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+		assertContainsHospital(t, body, `"code":"NO_ICAO_CODE_INVALID_JSON"`)
+		assertContainsHospital(t, body, `"error_code":"4001104"`)
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodPost, "/api/v1/hospital/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"hospital","attributes":{"name":"  "}}}`)
+		resp, body := doJSONRequestHospital(t, app, http.MethodPost, "/api/v1/hospital/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+		assertContainsHospital(t, body, `"code":"NO_ICAO_CODE_NAME_REQUIRED"`)
+		assertContainsHospital(t, body, `"error_code":"4221109"`)
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		repo.createErr = errors.New("create failed")
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"hospital","attributes":{"name":"RSUD Kota"}}}`)
+		resp, body := doJSONRequestHospital(t, app, http.MethodPost, "/api/v1/hospital/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+		assertContainsHospital(t, body, `"code":"NO_ICAO_CODE_CREATE_FAILED"`)
+		assertContainsHospital(t, body, `"error_code":"4001110"`)
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		actor := uuidv7.MustBytes()
+		app := newHospitalTestApp(h, actor)
+
+		body := []byte(`{"data":{"type":"hospital","attributes":{"name":"RSUD Kota","sortkey":3,"address":"Jl. Merdeka","landline_number":"021123456","mobile_number":"08123456","email":"rsud@hospital.local"}}}`)
+		resp, _ := doJSONRequestHospital(t, app, http.MethodPost, "/api/v1/hospital/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected row created")
+		}
+		if repo.lastCreate.Name != "RSUD Kota" || repo.lastCreate.Address != "Jl. Merdeka" || repo.lastCreate.LandlineNumber != "021123456" || repo.lastCreate.MobileNumber != "08123456" || repo.lastCreate.Email != "rsud@hospital.local" {
+			t.Fatalf("expected created values")
+		}
+		if repo.lastCreate.SortKey == nil || *repo.lastCreate.SortKey != 3 {
+			t.Fatalf("expected sortkey mapped")
+		}
+		if !repo.lastCreate.IsActive {
+			t.Fatalf("expected default is_active=true on create")
+		}
+		if string(repo.lastCreate.CreatedBy) != string(actor) || string(repo.lastCreate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected created_by and updated_by from actor")
+		}
+	})
+
+	t.Run("create with inactive flag", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"hospital","attributes":{"name":"RS Inactive","is_active":false}}}`)
+		resp, _ := doJSONRequestHospital(t, app, http.MethodPost, "/api/v1/hospital/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil || repo.lastCreate.IsActive {
+			t.Fatalf("expected created row is_active=false")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		repo.getByIDFn = func(_ []byte, _ int) (*hospital.Hospital, error) {
+			return nil, errors.New("lookup failed")
+		}
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"hospital","attributes":{"name":"RSUD Kota"}}}`)
+		resp, _ := doJSONRequestHospital(t, app, http.MethodPost, "/api/v1/hospital/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected create to be called")
+		}
+	})
+}
+
+func TestHospitalHandlerUpdate(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		resp, body := doJSONRequestHospital(t, app, http.MethodPatch, "/api/v1/hospital/update/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+		assertContainsHospital(t, body, `"code":"NO_ICAO_CODE_INVALID_UUID"`)
+		assertContainsHospital(t, body, `"error_code":"4221105"`)
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+		id := mustUUIDStringHospital(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodPatch, "/api/v1/hospital/update/"+id, []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+		id := mustUUIDStringHospital(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodPatch, "/api/v1/hospital/update/"+id, []byte(`{"data":{"type":"x","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+		id := mustUUIDStringHospital(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodPatch, "/api/v1/hospital/update/"+id, []byte(`{"data":{"type":"hospital","id":"","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+		id := mustUUIDStringHospital(t, uuidv7.MustBytes())
+		other := mustUUIDStringHospital(t, uuidv7.MustBytes())
+
+		resp, body := doJSONRequestHospital(t, app, http.MethodPatch, "/api/v1/hospital/update/"+id, []byte(`{"data":{"type":"hospital","id":"`+other+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+		assertContainsHospital(t, body, `"code":"NO_ICAO_CODE_ID_MISMATCH"`)
+		assertContainsHospital(t, body, `"error_code":"4221107"`)
+	})
+
+	t.Run("no attributes", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+		id := mustUUIDStringHospital(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodPatch, "/api/v1/hospital/update/"+id, []byte(`{"data":{"type":"hospital","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+		id := mustUUIDStringHospital(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodPatch, "/api/v1/hospital/update/"+id, []byte(`{"data":{"type":"hospital","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &hospital.Hospital{ID: id, Name: "Old", Address: "Old"}
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+		idStr := mustUUIDStringHospital(t, id)
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodPatch, "/api/v1/hospital/update/"+idStr, []byte(`{"data":{"type":"hospital","id":"`+idStr+`","attributes":{"name":"  "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &hospital.Hospital{ID: id, Name: "Old", Address: "Old"}
+		repo.updateErr = errors.New("update failed")
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+		idStr := mustUUIDStringHospital(t, id)
+
+		resp, body := doJSONRequestHospital(t, app, http.MethodPatch, "/api/v1/hospital/update/"+idStr, []byte(`{"data":{"type":"hospital","id":"`+idStr+`","attributes":{"name":"New"}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+		assertContainsHospital(t, body, `"code":"NO_ICAO_CODE_UPDATE_FAILED"`)
+		assertContainsHospital(t, body, `"error_code":"4001111"`)
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &hospital.Hospital{ID: id, Name: "Old", Address: "Old", LandlineNumber: "1", MobileNumber: "2", Email: "old@h.local", IsActive: true}
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		actor := uuidv7.MustBytes()
+		app := newHospitalTestApp(h, actor)
+		idStr := mustUUIDStringHospital(t, id)
+
+		body := `{"data":{"type":"hospital","id":"` + idStr + `","attributes":{"name":"New","sortkey":2,"address":"New Addr","landline_number":"021999","mobile_number":"089999","email":"new@hospital.local","is_active":false}}}`
+		resp, _ := doJSONRequestHospital(t, app, http.MethodPatch, "/api/v1/hospital/update/"+idStr, []byte(body))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.Name != "New" || repo.lastUpdate.Address != "New Addr" || repo.lastUpdate.LandlineNumber != "021999" || repo.lastUpdate.MobileNumber != "089999" || repo.lastUpdate.Email != "new@hospital.local" {
+			t.Fatalf("expected updated values")
+		}
+		if repo.lastUpdate.SortKey == nil || *repo.lastUpdate.SortKey != 2 {
+			t.Fatalf("expected updated sortkey=2")
+		}
+		if repo.lastUpdate.IsActive {
+			t.Fatalf("expected updated is_active=false")
+		}
+		if string(repo.lastUpdate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		id := uuidv7.MustBytes()
+		existing := &hospital.Hospital{ID: id, Name: "Old", Address: "Old"}
+		repo.getByIDFn = func(_ []byte, call int) (*hospital.Hospital, error) {
+			if call == 1 {
+				return existing, nil
+			}
+			return nil, errors.New("second lookup failed")
+		}
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+		idStr := mustUUIDStringHospital(t, id)
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodPatch, "/api/v1/hospital/update/"+idStr, []byte(`{"data":{"type":"hospital","id":"`+idStr+`","attributes":{"address":"Only addr"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestHospitalHandlerDelete(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodDelete, "/api/v1/hospital/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete error", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		repo.deleteErr = errors.New("delete failed")
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+		id := mustUUIDStringHospital(t, uuidv7.MustBytes())
+
+		resp, body := doJSONRequestHospital(t, app, http.MethodDelete, "/api/v1/hospital/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+		assertContainsHospital(t, body, `"code":"NO_ICAO_CODE_DELETE_FAILED"`)
+		assertContainsHospital(t, body, `"error_code":"4001112"`)
+	})
+
+	t.Run("delete relation conflict", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		repo.deleteErr = apperrors.NewDeleteConflictError("flight_data")
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+		id := mustUUIDStringHospital(t, uuidv7.MustBytes())
+
+		resp, body := doJSONRequestHospital(t, app, http.MethodDelete, "/api/v1/hospital/delete/"+id, nil)
+		if resp.StatusCode != http.StatusConflict {
+			t.Fatalf("expected 409, got %d", resp.StatusCode)
+		}
+		assertContainsHospital(t, body, `"code":"NO_ICAO_CODE_RELATION_DELETE_ERROR"`)
+		assertContainsHospital(t, body, `"error_code":"4091102"`)
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		actor := uuidv7.MustBytes()
+		app := newHospitalTestApp(h, actor)
+		id := uuidv7.MustBytes()
+		idStr := mustUUIDStringHospital(t, id)
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodDelete, "/api/v1/hospital/delete/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(repo.lastDeleteBy) != string(actor) {
+			t.Fatalf("expected deleted_by from actor")
+		}
+	})
+}
+
+func TestHospitalHandlerList(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodGet, "/api/v1/hospital/get-all", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with filter name and clamp max", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		repo.listRows = []hospital.Hospital{{ID: uuidv7.MustBytes(), Name: "RSUD Kota", SortKey: intPtrHospitalHandler(3), Address: "Jl. Merdeka", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodGet, "/api/v1/hospital/get-all?filter[name]=abc&page[number]=0&page=0&page[size]=0&limit=101&sort=-sortkey", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, hospital_name ASC" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q sort=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListSort, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success with search and clamp min", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		repo.listRows = []hospital.Hospital{}
+		repo.listTotal = 0
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodGet, "/api/v1/hospital/get-all?page=2&size=-1&search=needle", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "needle" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestHospitalHandlerListDatatable(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodGet, "/api/v1/hospital/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success clamp max and page floor", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		repo.listRows = []hospital.Hospital{{ID: uuidv7.MustBytes(), Name: "RSUD Kota", Address: "Jl. Merdeka", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodGet, "/api/v1/hospital/get-all/dt?page=0&limit=0&size=101&draw=7&search=abc", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListLimit != 100 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success clamp min", func(t *testing.T) {
+		repo := newMemHospitalRepo()
+		repo.listRows = []hospital.Hospital{}
+		repo.listTotal = 0
+		h := NewHospitalHandler(service.NewHospitalService(repo))
+		app := newHospitalTestApp(h, nil)
+
+		resp, _ := doJSONRequestHospital(t, app, http.MethodGet, "/api/v1/hospital/get-all/dt?page=2&limit=0&size=-1", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListLimit != 20 || repo.lastListOffset != 20 {
+			t.Fatalf("unexpected list params: limit=%d offset=%d", repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestHospitalResource(t *testing.T) {
+	id := uuidv7.MustBytes()
+	createdBy := uuidv7.MustBytes()
+	updatedBy := uuidv7.MustBytes()
+	deletedBy := uuidv7.MustBytes()
+	now := time.Now().UTC().Truncate(time.Second)
+	deletedAt := now.Add(time.Hour)
+
+	row := &hospital.Hospital{
+		ID:             id,
+		Name:           "RSUD Kota",
+		SortKey:        intPtrHospitalHandler(2),
+		Address:        "Jl. Merdeka",
+		LandlineNumber: "021123456",
+		MobileNumber:   "08123456",
+		Email:          "rsud@hospital.local",
+		IsActive:       true,
+		CreatedAt:      now,
+		CreatedBy:      createdBy,
+		UpdatedAt:      now,
+		UpdatedBy:      updatedBy,
+		DeletedAt:      &deletedAt,
+		DeletedBy:      deletedBy,
+	}
+
+	res := hospitalResource(row)
+	if res.Type != "hospital" {
+		t.Fatalf("unexpected type: %s", res.Type)
+	}
+	if res.ID == "" || res.Attributes.CreatedBy == "" || res.Attributes.UpdatedBy == "" || res.Attributes.DeletedBy == "" {
+		t.Fatalf("expected UUID fields in resource")
+	}
+	if res.Attributes.Name != "RSUD Kota" || res.Attributes.Address != "Jl. Merdeka" || res.Attributes.LandlineNumber != "021123456" || res.Attributes.MobileNumber != "08123456" || res.Attributes.Email != "rsud@hospital.local" {
+		t.Fatalf("expected hospital fields in resource")
+	}
+	if res.Attributes.SortKey == nil || *res.Attributes.SortKey != 2 {
+		t.Fatalf("expected sortkey mapped in resource")
+	}
+	if !res.Attributes.IsActive {
+		t.Fatalf("expected is_active mapped in resource")
+	}
+	if res.Attributes.CreatedAt == "" || res.Attributes.UpdatedAt == "" || res.Attributes.DeletedAt == "" {
+		t.Fatalf("expected time fields in resource")
+	}
+}
+
+func intPtrHospitalHandler(v int) *int { return &v }
diff --git a/internal/transport/http/handlers/icao_handler.go b/internal/transport/http/handlers/icao_handler.go
new file mode 100644
index 0000000..cd717f7
--- /dev/null
+++ b/internal/transport/http/handlers/icao_handler.go
@@ -0,0 +1,578 @@
+package handlers
+
+import (
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/icao"
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type ICAOHandler struct {
+	svc      icao.Service
+	validate *validators.Validator
+}
+
+func NewICAOHandler(svc icao.Service) *ICAOHandler {
+	return &ICAOHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateICAO godoc
+// @Summary Create ICAO
+// @Description Create an ICAO row.
+// @Tags Hospital - ICAO
+// @Accept json
+// @Produce json
+// @Param request body dto.ICAOCreateRequest true "JSON:API ICAO create request"
+// @Success 201 {object} dto.ICAOResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/icao/create [post]
+func (h *ICAOHandler) Create(c *fiber.Ctx) error {
+	var req dto.ICAOCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeICAOErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeICAOErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	code := strings.TrimSpace(req.Data.Attributes.ICAOCode)
+	if code == "" {
+		return writeICAOErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "icao_code is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/icao_code"},
+		}})
+	}
+
+	row := &icao.ICAO{
+		ICAOCode:       code,
+		Name:           strings.TrimSpace(stringOrDefault(req.Data.Attributes.Name, "")),
+		SortKey:        cloneIntPointer(req.Data.Attributes.SortKey),
+		Address:        strings.TrimSpace(stringOrDefault(req.Data.Attributes.Address, "")),
+		LandlineNumber: strings.TrimSpace(stringOrDefault(req.Data.Attributes.LandlineNumber, "")),
+		MobileNumber:   strings.TrimSpace(stringOrDefault(req.Data.Attributes.MobileNumber, "")),
+		Email:          strings.TrimSpace(stringOrDefault(req.Data.Attributes.Email, "")),
+		Note:           strings.TrimSpace(stringOrDefault(req.Data.Attributes.Note, "")),
+		IsActive:       boolOrDefault(req.Data.Attributes.IsActive, true),
+		CreatedBy:      actorUserID(c),
+		UpdatedBy:      actorUserID(c),
+	}
+	if req.Data.Attributes.LandID != nil {
+		landID, parseErr := parseNullableUUID(*req.Data.Attributes.LandID)
+		if parseErr != nil {
+			return writeICAOErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "land_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/land_id"},
+			}})
+		}
+		row.LandID = landID
+	}
+	if req.Data.Attributes.FederalStateID != nil {
+		federalStateID, parseErr := parseNullableUUID(*req.Data.Attributes.FederalStateID)
+		if parseErr != nil {
+			return writeICAOErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "federal_state_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/federal_state_id"},
+			}})
+		}
+		row.FederalStateID = federalStateID
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeICAOErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, icaoResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, icaoResource(row))
+}
+
+// UpdateICAO godoc
+// @Summary Update ICAO (partial)
+// @Description Patch ICAO by ID.
+// @Tags Hospital - ICAO
+// @Accept json
+// @Produce json
+// @Param uuid path string true "ICAO UUID (UUIDv7)"
+// @Param request body dto.ICAOUpdateRequest true "JSON:API ICAO update request"
+// @Success 200 {object} dto.ICAOResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/icao/update/{uuid} [patch]
+func (h *ICAOHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeICAOErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.ICAOUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeICAOErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeICAOErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeICAOErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeICAOErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.ICAOCode == nil && attrs.LandID == nil && attrs.FederalStateID == nil && !attrs.SortKey.Set && attrs.Address == nil && attrs.LandlineNumber == nil && attrs.MobileNumber == nil && attrs.Email == nil && attrs.Note == nil && attrs.IsActive == nil {
+		return writeICAOErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeICAOErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "icao not found",
+		}})
+	}
+
+	if attrs.ICAOCode != nil {
+		v := strings.TrimSpace(*attrs.ICAOCode)
+		if v == "" {
+			return writeICAOErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "icao_code cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/icao_code"},
+			}})
+		}
+		existing.ICAOCode = v
+	}
+	if attrs.Name != nil {
+		existing.Name = strings.TrimSpace(*attrs.Name)
+	}
+	if attrs.FederalStateID != nil {
+		federalStateID, parseErr := parseNullableUUID(*attrs.FederalStateID)
+		if parseErr != nil {
+			return writeICAOErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "federal_state_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/federal_state_id"},
+			}})
+		}
+		existing.FederalStateID = federalStateID
+	}
+	if attrs.LandID != nil {
+		landID, parseErr := parseNullableUUID(*attrs.LandID)
+		if parseErr != nil {
+			return writeICAOErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "land_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/land_id"},
+			}})
+		}
+		existing.LandID = landID
+	}
+	if attrs.SortKey.Set {
+		if attrs.SortKey.Valid {
+			sortKey := attrs.SortKey.Value
+			existing.SortKey = &sortKey
+		} else {
+			existing.SortKey = nil
+		}
+	}
+	if attrs.Address != nil {
+		existing.Address = strings.TrimSpace(*attrs.Address)
+	}
+	if attrs.LandlineNumber != nil {
+		existing.LandlineNumber = strings.TrimSpace(*attrs.LandlineNumber)
+	}
+	if attrs.MobileNumber != nil {
+		existing.MobileNumber = strings.TrimSpace(*attrs.MobileNumber)
+	}
+	if attrs.Email != nil {
+		existing.Email = strings.TrimSpace(*attrs.Email)
+	}
+	if attrs.Note != nil {
+		existing.Note = strings.TrimSpace(*attrs.Note)
+	}
+	if attrs.IsActive != nil {
+		existing.IsActive = *attrs.IsActive
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeICAOErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, icaoResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, icaoResource(existing))
+}
+
+// DeleteICAO godoc
+// @Summary Delete ICAO
+// @Tags Hospital - ICAO
+// @Produce json
+// @Param uuid path string true "ICAO UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/icao/delete/{uuid} [delete]
+func (h *ICAOHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeICAOErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if conflict, ok := apperrors.AsDeleteConflict(err); ok {
+			return writeICAOErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "Conflict",
+				Detail: conflict.Error(),
+			}})
+		}
+		return writeICAOErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "icao_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListICAO godoc
+// @Summary List ICAO
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: icao_code, -icao_code, sortkey, -sortkey, address, -address, landline_number, -landline_number, mobile_number, -mobile_number, email, -email, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.
+// @Tags Hospital - ICAO
+// @Produce json
+// @Param filter[search] query string false "Search by icao_code/address/contact"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.ICAOListResponse
+// @Router /api/v1/icao/get-all [get]
+func (h *ICAOHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("filter[name]")
+	}
+	if filter == "" {
+		filter = c.Query("search")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return writeICAOErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.ICAOResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, icaoResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListICAODatatable godoc
+// @Summary List ICAO (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags Hospital - ICAO
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.ICAODataTableResponse
+// @Router /api/v1/icao/get-all/dt [get]
+func (h *ICAOHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return writeICAOErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.ICAOResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, icaoResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func icaoResource(row *icao.ICAO) dto.ICAOResource {
+	return dto.ICAOResource{
+		Type: "icao",
+		ID:   idString(row.ID),
+		Attributes: dto.ICAOAttributes{
+			LandID:         idString(row.LandID),
+			FederalStateID: idString(row.FederalStateID),
+			FederalState:   federalStateNameOrEmpty(row),
+			LandName:       landNameOrEmpty(row),
+			LandISOCode:    landISOCodeOrEmpty(row),
+			ICAOCode:       row.ICAOCode,
+			Name:           row.Name,
+			SortKey:        cloneIntPointer(row.SortKey),
+			Address:        row.Address,
+			LandlineNumber: row.LandlineNumber,
+			MobileNumber:   row.MobileNumber,
+			Email:          row.Email,
+			Note:           row.Note,
+			IsActive:       row.IsActive,
+			CreatedAt:      row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:      uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:      row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:      uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt:      timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:      uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func parseNullableUUID(raw string) ([]byte, error) {
+	value := strings.TrimSpace(raw)
+	if value == "" {
+		return nil, nil
+	}
+	return uuidv7.ParseString(value)
+}
+
+func federalStateNameOrEmpty(row *icao.ICAO) string {
+	if row == nil || row.FederalState == nil {
+		return ""
+	}
+	return row.FederalState.Name
+}
+
+func landNameOrEmpty(row *icao.ICAO) string {
+	if row == nil {
+		return ""
+	}
+	if row.Land != nil {
+		return row.Land.Name
+	}
+	if row.FederalState == nil || row.FederalState.Land == nil {
+		return ""
+	}
+	return row.FederalState.Land.Name
+}
+
+func landISOCodeOrEmpty(row *icao.ICAO) string {
+	if row == nil {
+		return ""
+	}
+	if row.Land != nil {
+		return row.Land.LandISOCode
+	}
+	if row.FederalState == nil || row.FederalState.Land == nil {
+		return ""
+	}
+	return row.FederalState.Land.LandISOCode
+}
+
+func writeICAOErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	statusStr := strconv.Itoa(status)
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferICAODef(status, e.Title, e.Detail)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		e.Detail = def.Message
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferICAOErrorCode(status int, title, detail string) (string, string) {
+	def := inferICAODef(status, title, detail)
+	return def.Code, def.ErrorCode
+}
+
+func inferICAODef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.ErrICAONotFound
+	case fiber.StatusConflict:
+		return apperrorsx.ErrICAORelationDelete
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid uuid"), strings.Contains(lowerDetail, "invalid uuid"):
+			return apperrorsx.ErrICAOInvalidUUID
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.ErrICAOIDRequired
+		case strings.Contains(lowerDetail, "id does not match path uuid"):
+			return apperrorsx.ErrICAOIDMismatch
+		case strings.Contains(lowerDetail, "at least one attribute must be provided"):
+			return apperrorsx.ErrICAOAttributesRequired
+		case strings.Contains(lowerDetail, "icao_code is required"), strings.Contains(lowerDetail, "icao_code cannot be empty"):
+			return apperrorsx.ErrICAOCodeRequired
+		case strings.Contains(lowerDetail, "land_id is invalid uuid"):
+			return apperrorsx.ErrICAOLandIDInvalid
+		case strings.Contains(lowerDetail, "federal_state_id is invalid uuid"):
+			return apperrorsx.ErrICAOFederalStateInvalid
+		default:
+			return apperrorsx.ErrICAOInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrICAOInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.ErrICAOCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrICAOUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrICAODeleteFailed
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.ErrICAOListFailed
+		default:
+			return apperrorsx.ErrICAOInvalidPayload
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
diff --git a/internal/transport/http/handlers/icao_handler_test.go b/internal/transport/http/handlers/icao_handler_test.go
new file mode 100644
index 0000000..aaaa2c5
--- /dev/null
+++ b/internal/transport/http/handlers/icao_handler_test.go
@@ -0,0 +1,803 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/federal_state"
+	"wucher/internal/domain/icao"
+	"wucher/internal/domain/land"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type memICAORepo struct {
+	rows map[string]*icao.ICAO
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+
+	listRows  []icao.ICAO
+	listTotal int64
+
+	getByIDFn func(id []byte, call int) (*icao.ICAO, error)
+	getCalls  int
+
+	lastCreate     *icao.ICAO
+	lastUpdate     *icao.ICAO
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+}
+
+func newMemICAORepo() *memICAORepo {
+	return &memICAORepo{
+		rows: map[string]*icao.ICAO{},
+	}
+}
+
+func (r *memICAORepo) Create(_ context.Context, row *icao.ICAO) error {
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.rows[string(row.ID)] = row
+	r.lastCreate = row
+	return nil
+}
+
+func (r *memICAORepo) Update(_ context.Context, row *icao.ICAO) error {
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	r.rows[string(row.ID)] = row
+	r.lastUpdate = row
+	return nil
+}
+
+func (r *memICAORepo) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	r.lastDeleteID = append([]byte(nil), id...)
+	r.lastDeleteBy = append([]byte(nil), deletedBy...)
+	delete(r.rows, string(id))
+	return nil
+}
+
+func (r *memICAORepo) GetByID(_ context.Context, id []byte) (*icao.ICAO, error) {
+	r.getCalls++
+	if r.getByIDFn != nil {
+		return r.getByIDFn(id, r.getCalls)
+	}
+	if r.getByIDErr != nil {
+		return nil, r.getByIDErr
+	}
+	return r.rows[string(id)], nil
+}
+
+func (r *memICAORepo) List(_ context.Context, filter, sort string, limit, offset int) ([]icao.ICAO, int64, error) {
+	r.lastListFilter = filter
+	r.lastListSort = sort
+	r.lastListLimit = limit
+	r.lastListOffset = offset
+	if r.listErr != nil {
+		return nil, 0, r.listErr
+	}
+	return r.listRows, r.listTotal, nil
+}
+
+func newICAOTestApp(h *ICAOHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", actor)
+		}
+		return c.Next()
+	})
+	app.Post("/api/v1/icao/create", h.Create)
+	app.Patch("/api/v1/icao/update/:uuid", h.Update)
+	app.Delete("/api/v1/icao/delete/:uuid", h.Delete)
+	app.Get("/api/v1/icao/get-all", h.List)
+	app.Get("/api/v1/icao/get-all/dt", h.ListDatatable)
+	return app
+}
+
+func doJSONRequestICAO(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDStringICAO(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestNewICAOHandler(t *testing.T) {
+	h := NewICAOHandler(service.NewICAOService(newMemICAORepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+func TestICAOHandlerCreate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPost, "/api/v1/icao/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPost, "/api/v1/icao/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"icao","attributes":{"icao_code":"  "}}}`)
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPost, "/api/v1/icao/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		repo := newMemICAORepo()
+		repo.createErr = errors.New("create failed")
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"icao","attributes":{"icao_code":"EDDB"}}}`)
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPost, "/api/v1/icao/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid federal_state_id", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"icao","attributes":{"icao_code":"EDDB","federal_state_id":"not-uuid"}}}`)
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPost, "/api/v1/icao/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		actor := uuidv7.MustBytes()
+		app := newICAOTestApp(h, actor)
+
+		body := []byte(`{"data":{"type":"icao","attributes":{"icao_code":"EDDB","sortkey":3,"address":"Main Street","landline_number":"021123456","mobile_number":"+491234","email":"main@hic.local","is_active":false}}}`)
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPost, "/api/v1/icao/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected row created")
+		}
+		if repo.lastCreate.ICAOCode != "EDDB" || repo.lastCreate.Address != "Main Street" || repo.lastCreate.LandlineNumber != "021123456" || repo.lastCreate.MobileNumber != "+491234" || repo.lastCreate.Email != "main@hic.local" {
+			t.Fatalf("expected optional attributes to be mapped")
+		}
+		if repo.lastCreate.SortKey == nil || *repo.lastCreate.SortKey != 3 {
+			t.Fatalf("expected sortkey mapped")
+		}
+		if repo.lastCreate.IsActive {
+			t.Fatalf("expected is_active false")
+		}
+		if string(repo.lastCreate.CreatedBy) != string(actor) || string(repo.lastCreate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected created_by and updated_by from actor")
+		}
+	})
+
+	t.Run("success with federal_state_id", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		fsID := mustUUIDStringICAO(t, uuidv7.MustBytes())
+
+		body := []byte(`{"data":{"type":"icao","attributes":{"icao_code":"EDDF","federal_state_id":"` + fsID + `","note":"  test note  "}}}`)
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPost, "/api/v1/icao/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil || len(repo.lastCreate.FederalStateID) == 0 {
+			t.Fatalf("expected federal_state_id mapped")
+		}
+		if repo.lastCreate.Note != "test note" {
+			t.Fatalf("expected note trimmed")
+		}
+	})
+
+	t.Run("success fallback when refetch error", func(t *testing.T) {
+		repo := newMemICAORepo()
+		repo.getByIDFn = func(_ []byte, call int) (*icao.ICAO, error) {
+			if call > 0 {
+				return nil, errors.New("lookup failed")
+			}
+			return nil, nil
+		}
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"icao","attributes":{"icao_code":"EDDB"}}}`)
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPost, "/api/v1/icao/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestICAOHandlerUpdate(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		id := mustUUIDStringICAO(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+id, []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		id := mustUUIDStringICAO(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+id, []byte(`{"data":{"type":"x","id":"`+id+`","attributes":{"icao_code":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		id := mustUUIDStringICAO(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+id, []byte(`{"data":{"type":"icao","id":"","attributes":{"icao_code":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		id := mustUUIDStringICAO(t, uuidv7.MustBytes())
+		other := mustUUIDStringICAO(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+id, []byte(`{"data":{"type":"icao","id":"`+other+`","attributes":{"icao_code":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no attributes", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		id := mustUUIDStringICAO(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+id, []byte(`{"data":{"type":"icao","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		repo := newMemICAORepo()
+		repo.getByIDErr = errors.New("lookup failed")
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		id := mustUUIDStringICAO(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+id, []byte(`{"data":{"type":"icao","id":"`+id+`","attributes":{"icao_code":"A"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemICAORepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &icao.ICAO{ID: id, ICAOCode: "OLD"}
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		idStr := mustUUIDStringICAO(t, id)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+idStr, []byte(`{"data":{"type":"icao","id":"`+idStr+`","attributes":{"icao_code":"  "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		repo := newMemICAORepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &icao.ICAO{ID: id, ICAOCode: "OLD"}
+		repo.updateErr = errors.New("update failed")
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		idStr := mustUUIDStringICAO(t, id)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+idStr, []byte(`{"data":{"type":"icao","id":"`+idStr+`","attributes":{"icao_code":"NEW"}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid federal_state_id", func(t *testing.T) {
+		repo := newMemICAORepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &icao.ICAO{ID: id, ICAOCode: "OLD"}
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		idStr := mustUUIDStringICAO(t, id)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+idStr, []byte(`{"data":{"type":"icao","id":"`+idStr+`","attributes":{"federal_state_id":"not-uuid"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("clear federal_state_id by empty string", func(t *testing.T) {
+		repo := newMemICAORepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &icao.ICAO{
+			ID:             id,
+			ICAOCode:       "OLD",
+			FederalStateID: uuidv7.MustBytes(),
+		}
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		idStr := mustUUIDStringICAO(t, id)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+idStr, []byte(`{"data":{"type":"icao","id":"`+idStr+`","attributes":{"federal_state_id":"   "}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil {
+			t.Fatalf("expected update called")
+		}
+		if repo.lastUpdate.FederalStateID != nil {
+			t.Fatalf("expected federal_state_id to be cleared")
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemICAORepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &icao.ICAO{ID: id, ICAOCode: "OLD"}
+		h := NewICAOHandler(service.NewICAOService(repo))
+		actor := uuidv7.MustBytes()
+		app := newICAOTestApp(h, actor)
+		idStr := mustUUIDStringICAO(t, id)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+idStr, []byte(`{"data":{"type":"icao","id":"`+idStr+`","attributes":{"icao_code":"NEW","address":"Street 1","landline_number":"021999","mobile_number":"+49888","email":"new@hic.local"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.ICAOCode != "NEW" || repo.lastUpdate.Address != "Street 1" || repo.lastUpdate.LandlineNumber != "021999" || repo.lastUpdate.MobileNumber != "+49888" || repo.lastUpdate.Email != "new@hic.local" {
+			t.Fatalf("expected updated values")
+		}
+		if string(repo.lastUpdate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected updated_by from actor")
+		}
+	})
+
+	t.Run("success update sortkey and is_active", func(t *testing.T) {
+		repo := newMemICAORepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &icao.ICAO{ID: id, ICAOCode: "OLD", IsActive: true}
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		idStr := mustUUIDStringICAO(t, id)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+idStr, []byte(`{"data":{"type":"icao","id":"`+idStr+`","attributes":{"sortkey":2,"is_active":false}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil {
+			t.Fatalf("expected update called")
+		}
+		if repo.lastUpdate.SortKey == nil || *repo.lastUpdate.SortKey != 2 {
+			t.Fatalf("expected sortkey updated")
+		}
+		if repo.lastUpdate.IsActive {
+			t.Fatalf("expected is_active false")
+		}
+	})
+
+	t.Run("success clear sortkey with null", func(t *testing.T) {
+		repo := newMemICAORepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &icao.ICAO{ID: id, ICAOCode: "OLD", SortKey: intPtrICAOHandler(7)}
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		idStr := mustUUIDStringICAO(t, id)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+idStr, []byte(`{"data":{"type":"icao","id":"`+idStr+`","attributes":{"sortkey":null}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.SortKey != nil {
+			t.Fatalf("expected sortkey cleared")
+		}
+	})
+
+	t.Run("success set federal_state_id", func(t *testing.T) {
+		repo := newMemICAORepo()
+		id := uuidv7.MustBytes()
+		oldFSID := uuidv7.MustBytes()
+		repo.rows[string(id)] = &icao.ICAO{
+			ID:             id,
+			ICAOCode:       "OLD",
+			FederalStateID: oldFSID,
+			FederalState:   &federal_state.FederalState{ID: oldFSID, Name: "Old FS"},
+		}
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		idStr := mustUUIDStringICAO(t, id)
+		fsID := mustUUIDStringICAO(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+idStr, []byte(`{"data":{"type":"icao","id":"`+idStr+`","attributes":{"federal_state_id":"`+fsID+`"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || len(repo.lastUpdate.FederalStateID) == 0 {
+			t.Fatalf("expected federal_state_id set")
+		}
+	})
+
+	t.Run("success update note", func(t *testing.T) {
+		repo := newMemICAORepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &icao.ICAO{ID: id, ICAOCode: "OLD", Note: "old"}
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		idStr := mustUUIDStringICAO(t, id)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+idStr, []byte(`{"data":{"type":"icao","id":"`+idStr+`","attributes":{"note":"  updated note  "}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.Note != "updated note" {
+			t.Fatalf("expected note updated and trimmed")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		repo := newMemICAORepo()
+		id := uuidv7.MustBytes()
+		existing := &icao.ICAO{ID: id, ICAOCode: "OLD"}
+		repo.getByIDFn = func(_ []byte, call int) (*icao.ICAO, error) {
+			if call == 1 {
+				return existing, nil
+			}
+			return nil, errors.New("second lookup failed")
+		}
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		idStr := mustUUIDStringICAO(t, id)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodPatch, "/api/v1/icao/update/"+idStr, []byte(`{"data":{"type":"icao","id":"`+idStr+`","attributes":{"address":"Only addr"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestICAOHandlerDelete(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodDelete, "/api/v1/icao/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete error", func(t *testing.T) {
+		repo := newMemICAORepo()
+		repo.deleteErr = errors.New("delete failed")
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+		id := mustUUIDStringICAO(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodDelete, "/api/v1/icao/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemICAORepo()
+		h := NewICAOHandler(service.NewICAOService(repo))
+		actor := uuidv7.MustBytes()
+		app := newICAOTestApp(h, actor)
+		id := uuidv7.MustBytes()
+		idStr := mustUUIDStringICAO(t, id)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodDelete, "/api/v1/icao/delete/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(repo.lastDeleteBy) != string(actor) {
+			t.Fatalf("expected deleted_by from actor")
+		}
+	})
+}
+
+func TestICAOHandlerList(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemICAORepo()
+		repo.listErr = errors.New("list failed")
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodGet, "/api/v1/icao/get-all", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with filter name and clamp max", func(t *testing.T) {
+		repo := newMemICAORepo()
+		repo.listRows = []icao.ICAO{{ID: uuidv7.MustBytes(), ICAOCode: "A", SortKey: intPtrICAOHandler(3), IsActive: true, CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodGet, "/api/v1/icao/get-all?filter[name]=abc&page[number]=0&page=0&page[size]=0&limit=101&sort=-sortkey", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, icao_code ASC" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q sort=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListSort, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success with search and clamp min", func(t *testing.T) {
+		repo := newMemICAORepo()
+		repo.listRows = []icao.ICAO{}
+		repo.listTotal = 0
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodGet, "/api/v1/icao/get-all?page=2&size=-1&search=needle", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "needle" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestICAOHandlerListDatatable(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemICAORepo()
+		repo.listErr = errors.New("list failed")
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodGet, "/api/v1/icao/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success clamp max and page floor", func(t *testing.T) {
+		repo := newMemICAORepo()
+		repo.listRows = []icao.ICAO{{ID: uuidv7.MustBytes(), ICAOCode: "A", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodGet, "/api/v1/icao/get-all/dt?page=0&limit=0&size=101&draw=7&search=abc", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListLimit != 100 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success clamp min", func(t *testing.T) {
+		repo := newMemICAORepo()
+		repo.listRows = []icao.ICAO{}
+		repo.listTotal = 0
+		h := NewICAOHandler(service.NewICAOService(repo))
+		app := newICAOTestApp(h, nil)
+
+		resp, _ := doJSONRequestICAO(t, app, http.MethodGet, "/api/v1/icao/get-all/dt?page=2&limit=0&size=-1", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListLimit != 20 || repo.lastListOffset != 20 {
+			t.Fatalf("unexpected list params: limit=%d offset=%d", repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestICAOResource(t *testing.T) {
+	id := uuidv7.MustBytes()
+	createdBy := uuidv7.MustBytes()
+	updatedBy := uuidv7.MustBytes()
+	deletedBy := uuidv7.MustBytes()
+	now := time.Now().UTC().Truncate(time.Second)
+	deletedAt := now.Add(time.Hour)
+
+	row := &icao.ICAO{
+		ID:             id,
+		ICAOCode:       "EDDB",
+		Name:           "Berlin Brandenburg Airport",
+		SortKey:        intPtrICAOHandler(2),
+		Address:        "Street 1",
+		LandlineNumber: "021123456",
+		MobileNumber:   "+491234",
+		Email:          "main@hic.local",
+		IsActive:       true,
+		CreatedAt:      now,
+		CreatedBy:      createdBy,
+		UpdatedAt:      now,
+		UpdatedBy:      updatedBy,
+		DeletedAt:      &deletedAt,
+		DeletedBy:      deletedBy,
+		FederalState: &federal_state.FederalState{
+			Name: "Bayern",
+			Land: &land.Land{Name: "Germany", LandISOCode: "DE"},
+		},
+	}
+
+	res := icaoResource(row)
+	if res.Type != "icao" {
+		t.Fatalf("unexpected type: %s", res.Type)
+	}
+	if res.Attributes.SortKey == nil || *res.Attributes.SortKey != 2 || !res.Attributes.IsActive {
+		t.Fatalf("expected sortkey and is_active in resource")
+	}
+	if res.Attributes.Name != "Berlin Brandenburg Airport" {
+		t.Fatalf("expected name in resource")
+	}
+	if res.Attributes.FederalState != "Bayern" || res.Attributes.LandName != "Germany" || res.Attributes.LandISOCode != "DE" {
+		t.Fatalf("expected federal and land fields in resource")
+	}
+	if res.ID == "" || res.Attributes.CreatedBy == "" || res.Attributes.UpdatedBy == "" || res.Attributes.DeletedBy == "" {
+		t.Fatalf("expected UUID fields in resource")
+	}
+	if res.Attributes.CreatedAt == "" || res.Attributes.UpdatedAt == "" || res.Attributes.DeletedAt == "" {
+		t.Fatalf("expected time fields in resource")
+	}
+}
+
+func TestParseNullableUUID(t *testing.T) {
+	t.Run("empty becomes nil", func(t *testing.T) {
+		got, err := parseNullableUUID("  ")
+		if err != nil {
+			t.Fatalf("unexpected err: %v", err)
+		}
+		if got != nil {
+			t.Fatalf("expected nil")
+		}
+	})
+
+	t.Run("valid uuid", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		idStr := mustUUIDStringICAO(t, id)
+		got, err := parseNullableUUID(idStr)
+		if err != nil {
+			t.Fatalf("unexpected err: %v", err)
+		}
+		if string(got) != string(id) {
+			t.Fatalf("expected same bytes")
+		}
+	})
+
+	t.Run("invalid uuid", func(t *testing.T) {
+		if _, err := parseNullableUUID("not-uuid"); err == nil {
+			t.Fatalf("expected err")
+		}
+	})
+}
+
+func TestICAOFederalStateLandNameHelpers(t *testing.T) {
+	if federalStateNameOrEmpty(nil) != "" || landNameOrEmpty(nil) != "" || landISOCodeOrEmpty(nil) != "" {
+		t.Fatalf("expected empty for nil row")
+	}
+	rowWithoutFS := &icao.ICAO{}
+	if federalStateNameOrEmpty(rowWithoutFS) != "" || landNameOrEmpty(rowWithoutFS) != "" || landISOCodeOrEmpty(rowWithoutFS) != "" {
+		t.Fatalf("expected empty when relation missing")
+	}
+	rowWithoutLand := &icao.ICAO{FederalState: &federal_state.FederalState{Name: "Bayern"}}
+	if federalStateNameOrEmpty(rowWithoutLand) != "Bayern" {
+		t.Fatalf("expected federal state name")
+	}
+	if landNameOrEmpty(rowWithoutLand) != "" || landISOCodeOrEmpty(rowWithoutLand) != "" {
+		t.Fatalf("expected empty land fields")
+	}
+	rowWithLand := &icao.ICAO{
+		FederalState: &federal_state.FederalState{
+			Name: "Bayern",
+			Land: &land.Land{Name: "Germany", LandISOCode: "DE"},
+		},
+	}
+	if federalStateNameOrEmpty(rowWithLand) != "Bayern" || landNameOrEmpty(rowWithLand) != "Germany" || landISOCodeOrEmpty(rowWithLand) != "DE" {
+		t.Fatalf("expected names from relation")
+	}
+	if strings.TrimSpace(federalStateNameOrEmpty(rowWithLand)) == "" {
+		t.Fatalf("sanity check non-empty federal state")
+	}
+}
+
+func intPtrICAOHandler(v int) *int { return &v }
diff --git a/internal/transport/http/handlers/insurance_patient_data_handler.go b/internal/transport/http/handlers/insurance_patient_data_handler.go
new file mode 100644
index 0000000..d507c7c
--- /dev/null
+++ b/internal/transport/http/handlers/insurance_patient_data_handler.go
@@ -0,0 +1,518 @@
+package handlers
+
+import (
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	insurancepatientdata "wucher/internal/domain/insurance_patient_data"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type InsurancePatientDataHandler struct {
+	svc      insurancepatientdata.Service
+	validate *validators.Validator
+}
+
+func NewInsurancePatientDataHandler(svc insurancepatientdata.Service) *InsurancePatientDataHandler {
+	return &InsurancePatientDataHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateInsurancePatientData godoc
+// @Summary Create insurance patient data
+// @Description Create an InsurancePatientData record.
+// @Tags PatientData - InsurancePatientData
+// @Accept json
+// @Produce json
+// @Param request body dto.InsurancePatientDataCreateRequest true "JSON:API InsurancePatientData create request"
+// @Success 201 {object} dto.InsurancePatientDataResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/insurance-patient-data/create [post]
+func (h *InsurancePatientDataHandler) Create(c *fiber.Ctx) error {
+	var req dto.InsurancePatientDataCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	healthInsuranceID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.HealthInsuranceCompaniesId))
+	if err != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "health_insurance_companies_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/health_insurance_companies_id"},
+		}})
+	}
+	federalStateID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.FederalStateId))
+	if err != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "federal_state_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/federal_state_id"},
+		}})
+	}
+
+	row := &insurancepatientdata.InsurancePatientData{
+		HealthInsuranceCompaniesId: healthInsuranceID,
+		FederalStateId:             federalStateID,
+		CreatedBy:                  actorUserID(c),
+		UpdatedBy:                  actorUserID(c),
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, insurancePatientDataResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, insurancePatientDataResource(row))
+}
+
+// GetInsurancePatientData godoc
+// @Summary Get insurance patient data by ID
+// @Description Get a single InsurancePatientData record by UUID.
+// @Tags PatientData - InsurancePatientData
+// @Produce json
+// @Param uuid path string true "InsurancePatientData UUID (UUIDv7)"
+// @Success 200 {object} dto.InsurancePatientDataResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/insurance-patient-data/get/{uuid} [get]
+func (h *InsurancePatientDataHandler) Get(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || row == nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "insurance patient data not found",
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, insurancePatientDataResource(row))
+}
+
+// UpdateInsurancePatientData godoc
+// @Summary Update insurance patient data (partial)
+// @Description Patch InsurancePatientData by ID.
+// @Tags PatientData - InsurancePatientData
+// @Accept json
+// @Produce json
+// @Param uuid path string true "InsurancePatientData UUID (UUIDv7)"
+// @Param request body dto.InsurancePatientDataUpdateRequest true "JSON:API InsurancePatientData update request"
+// @Success 200 {object} dto.InsurancePatientDataResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/insurance-patient-data/update/{uuid} [patch]
+func (h *InsurancePatientDataHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.InsurancePatientDataUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeInsurancePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeInsurancePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.HealthInsuranceCompaniesId == nil && attrs.FederalStateId == nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "insurance patient data not found",
+		}})
+	}
+
+	if attrs.HealthInsuranceCompaniesId != nil {
+		parsed, parseErr := uuidv7.ParseString(strings.TrimSpace(*attrs.HealthInsuranceCompaniesId))
+		if parseErr != nil {
+			return writeInsurancePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "health_insurance_companies_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/health_insurance_companies_id"},
+			}})
+		}
+		existing.HealthInsuranceCompaniesId = parsed
+	}
+	if attrs.FederalStateId != nil {
+		parsed, parseErr := uuidv7.ParseString(strings.TrimSpace(*attrs.FederalStateId))
+		if parseErr != nil {
+			return writeInsurancePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "federal_state_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/federal_state_id"},
+			}})
+		}
+		existing.FederalStateId = parsed
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, insurancePatientDataResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, insurancePatientDataResource(existing))
+}
+
+// DeleteInsurancePatientData godoc
+// @Summary Delete insurance patient data
+// @Description Soft delete InsurancePatientData by ID.
+// @Tags PatientData - InsurancePatientData
+// @Produce json
+// @Param uuid path string true "InsurancePatientData UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/insurance-patient-data/delete/{uuid} [delete]
+func (h *InsurancePatientDataHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeInsurancePatientDataErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "insurance patient data not found",
+			}})
+		}
+		return writeInsurancePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "insurance_patient_data_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListInsurancePatientData godoc
+// @Summary List insurance patient data
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: created_at, -created_at, updated_at, -updated_at.
+// @Tags PatientData - InsurancePatientData
+// @Produce json
+// @Param filter[search] query string false "Search"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.InsurancePatientDataListResponse
+// @Router /api/v1/insurance-patient-data/get-all [get]
+func (h *InsurancePatientDataHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("search")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.InsurancePatientDataResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, insurancePatientDataResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListInsurancePatientDataDatatable godoc
+// @Summary List insurance patient data (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags PatientData - InsurancePatientData
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.InsurancePatientDataDataTableResponse
+// @Router /api/v1/insurance-patient-data/get-all/dt [get]
+func (h *InsurancePatientDataHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return writeInsurancePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.InsurancePatientDataResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, insurancePatientDataResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func insurancePatientDataResource(row *insurancepatientdata.InsurancePatientData) dto.InsurancePatientDataResource {
+	attrs := dto.InsurancePatientDataAttributes{
+		HealthInsuranceCompaniesId: idString(row.HealthInsuranceCompaniesId),
+		FederalStateId:             idString(row.FederalStateId),
+		CreatedAt:                  row.CreatedAt.UTC().Format(time.RFC3339),
+		CreatedBy:                  uuidStringOrEmpty(row.CreatedBy),
+		UpdatedAt:                  row.UpdatedAt.UTC().Format(time.RFC3339),
+		UpdatedBy:                  uuidStringOrEmpty(row.UpdatedBy),
+		DeletedAt:                  timeStringOrEmpty(row.DeletedAt),
+		DeletedBy:                  uuidStringOrEmpty(row.DeletedBy),
+	}
+
+	if row.HealthInsuranceCompanies != nil {
+		attrs.HealthInsuranceCompany = &dto.InsurancePatientDataHealthInsuranceCompany{
+			ID:           idString(row.HealthInsuranceCompanies.ID),
+			Name:         row.HealthInsuranceCompanies.Name,
+			State:        row.HealthInsuranceCompanies.State,
+			Address:      row.HealthInsuranceCompanies.Address,
+			MobileNumber: row.HealthInsuranceCompanies.MobileNumber,
+			Email:        row.HealthInsuranceCompanies.Email,
+		}
+	}
+
+	if row.FederalState != nil {
+		attrs.FederalState = &dto.InsurancePatientDataFederalState{
+			ID:   idString(row.FederalState.ID),
+			Name: row.FederalState.Name,
+		}
+	}
+
+	return dto.InsurancePatientDataResource{
+		Type:       "insurance_patient_data",
+		ID:         idString(row.ID),
+		Attributes: attrs,
+	}
+}
+
+func writeInsurancePatientDataErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferInsurancePatientDataDef(status, e.Title, e.Detail)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		if strings.TrimSpace(e.Title) == "" {
+			e.Title = def.Title
+		}
+		e.Detail = def.Message
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferInsurancePatientDataDef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.ErrInsurancePatientDataNotFound
+	case fiber.StatusConflict:
+		return apperrorsx.ErrInsurancePatientDataRelationDelete
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid"):
+			return apperrorsx.ErrInsurancePatientDataInvalidUUID
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.ErrInsurancePatientDataIDRequired
+		case strings.Contains(lowerDetail, "id does not match"):
+			return apperrorsx.ErrInsurancePatientDataIDMismatch
+		case strings.Contains(lowerDetail, "at least one attribute"):
+			return apperrorsx.ErrInsurancePatientDataAttributesRequired
+		case strings.Contains(lowerDetail, "health_insurance_companies_id is invalid"):
+			return apperrorsx.ErrInsurancePatientDataHealthInsuranceIDInvalid
+		case strings.Contains(lowerDetail, "federal_state_id is invalid"):
+			return apperrorsx.ErrInsurancePatientDataFederalStateIDInvalid
+		default:
+			return apperrorsx.ErrInsurancePatientDataInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrInsurancePatientDataInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.ErrInsurancePatientDataCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrInsurancePatientDataUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrInsurancePatientDataDeleteFailed
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.ErrInsurancePatientDataListFailed
+		default:
+			return apperrorsx.ErrInsurancePatientDataInvalidPayload
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
+
+func inferInsurancePatientDataErrorCode(status int, title, detail string) (string, string) {
+	def := inferInsurancePatientDataDef(status, title, detail)
+	return def.Code, def.ErrorCode
+}
diff --git a/internal/transport/http/handlers/insurance_patient_data_handler_test.go b/internal/transport/http/handlers/insurance_patient_data_handler_test.go
new file mode 100644
index 0000000..6eced5c
--- /dev/null
+++ b/internal/transport/http/handlers/insurance_patient_data_handler_test.go
@@ -0,0 +1,384 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	federalstate "wucher/internal/domain/federal_state"
+	healthinsurancecompanies "wucher/internal/domain/health_insurance_companies"
+	insurancepatientdata "wucher/internal/domain/insurance_patient_data"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type insurancePatientDataServiceMock struct {
+	createFn func(context.Context, *insurancepatientdata.InsurancePatientData) error
+	updateFn func(context.Context, *insurancepatientdata.InsurancePatientData) error
+	deleteFn func(context.Context, []byte, []byte) error
+	getByID  func(context.Context, []byte) (*insurancepatientdata.InsurancePatientData, error)
+	listFn   func(context.Context, string, string, int, int) ([]insurancepatientdata.InsurancePatientData, int64, error)
+}
+
+func (m *insurancePatientDataServiceMock) Create(ctx context.Context, row *insurancepatientdata.InsurancePatientData) error {
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return nil
+}
+func (m *insurancePatientDataServiceMock) Update(ctx context.Context, row *insurancepatientdata.InsurancePatientData) error {
+	if m.updateFn != nil {
+		return m.updateFn(ctx, row)
+	}
+	return nil
+}
+func (m *insurancePatientDataServiceMock) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if m.deleteFn != nil {
+		return m.deleteFn(ctx, id, deletedBy)
+	}
+	return nil
+}
+func (m *insurancePatientDataServiceMock) GetByID(ctx context.Context, id []byte) (*insurancepatientdata.InsurancePatientData, error) {
+	if m.getByID != nil {
+		return m.getByID(ctx, id)
+	}
+	return nil, nil
+}
+func (m *insurancePatientDataServiceMock) List(ctx context.Context, filter, sort string, limit, offset int) ([]insurancepatientdata.InsurancePatientData, int64, error) {
+	if m.listFn != nil {
+		return m.listFn(ctx, filter, sort, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func newInsurancePatientDataApp(h *InsurancePatientDataHandler) *fiber.App {
+	app := fiber.New()
+	app.Post("/create", h.Create)
+	app.Get("/get/:uuid", h.Get)
+	app.Patch("/update/:uuid", h.Update)
+	app.Delete("/delete/:uuid", h.Delete)
+	app.Get("/list", h.List)
+	app.Get("/dt", h.ListDatatable)
+	return app
+}
+
+func TestInsurancePatientDataHandler_CRUDAndLists(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	row := &insurancepatientdata.InsurancePatientData{
+		ID:                         id,
+		HealthInsuranceCompaniesId: id,
+		FederalStateId:             id,
+		CreatedAt:                  time.Now().UTC(),
+		UpdatedAt:                  time.Now().UTC(),
+	}
+	svc := &insurancePatientDataServiceMock{
+		createFn: func(_ context.Context, in *insurancepatientdata.InsurancePatientData) error {
+			in.ID = id
+			return nil
+		},
+		getByID: func(_ context.Context, _ []byte) (*insurancepatientdata.InsurancePatientData, error) {
+			return row, nil
+		},
+		updateFn: func(_ context.Context, _ *insurancepatientdata.InsurancePatientData) error { return nil },
+		deleteFn: func(_ context.Context, _, _ []byte) error { return nil },
+		listFn: func(_ context.Context, _, _ string, _, _ int) ([]insurancepatientdata.InsurancePatientData, int64, error) {
+			return []insurancepatientdata.InsurancePatientData{*row}, 1, nil
+		},
+	}
+	h := NewInsurancePatientDataHandler(svc)
+	app := newInsurancePatientDataApp(h)
+
+	req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(`{"data":{"type":"insurance_patient_data_create","attributes":{"health_insurance_companies_id":"`+idStr+`","federal_state_id":"`+idStr+`"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ := app.Test(req)
+	if res.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201 got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodGet, "/get/"+idStr, nil)
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(`{"data":{"type":"insurance_patient_data_update","id":"`+idStr+`","attributes":{"health_insurance_companies_id":"`+idStr+`","federal_state_id":"`+idStr+`"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodDelete, "/delete/"+idStr, nil)
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodGet, "/list?page[number]=2&page[size]=5&sort=created_at&filter[search]=x", nil)
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodGet, "/dt?page=2&size=5&draw=7&search=x", nil)
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 got %d", res.StatusCode)
+	}
+}
+
+func TestInsurancePatientDataHandler_ErrorBranches(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	svc := &insurancePatientDataServiceMock{
+		getByID: func(_ context.Context, _ []byte) (*insurancepatientdata.InsurancePatientData, error) {
+			return nil, errors.New("not found")
+		},
+		createFn: func(_ context.Context, _ *insurancepatientdata.InsurancePatientData) error { return errors.New("boom") },
+		updateFn: func(_ context.Context, _ *insurancepatientdata.InsurancePatientData) error { return errors.New("boom") },
+		deleteFn: func(_ context.Context, _, _ []byte) error { return errors.New("boom") },
+		listFn: func(_ context.Context, _, _ string, _, _ int) ([]insurancepatientdata.InsurancePatientData, int64, error) {
+			return nil, 0, errors.New("boom")
+		},
+	}
+	h := NewInsurancePatientDataHandler(svc)
+	app := newInsurancePatientDataApp(h)
+
+	cases := []struct {
+		method, path, body string
+		want               int
+	}{
+		{http.MethodPost, "/create", "{bad", 400},
+		{http.MethodPost, "/create", `{"data":{"type":"insurance_patient_data_create","attributes":{"health_insurance_companies_id":"bad","federal_state_id":"` + idStr + `"}}}`, 422},
+		{http.MethodPost, "/create", `{"data":{"type":"insurance_patient_data_create","attributes":{"health_insurance_companies_id":"` + idStr + `","federal_state_id":"bad"}}}`, 422},
+		{http.MethodPost, "/create", `{"data":{"type":"insurance_patient_data_create","attributes":{"health_insurance_companies_id":"` + idStr + `","federal_state_id":"` + idStr + `"}}}`, 400},
+		{http.MethodGet, "/get/bad", "", 422},
+		{http.MethodGet, "/get/" + idStr, "", 404},
+		{http.MethodPatch, "/update/bad", `{}`, 422},
+		{http.MethodPatch, "/update/" + idStr, "{bad", 400},
+		{http.MethodPatch, "/update/" + idStr, `{"data":{"type":"insurance_patient_data_update","id":"","attributes":{}}}`, 422},
+		{http.MethodPatch, "/update/" + idStr, `{"data":{"type":"insurance_patient_data_update","id":"` + mustNewUUIDForReserve(t) + `","attributes":{}}}`, 422},
+		{http.MethodPatch, "/update/" + idStr, `{"data":{"type":"insurance_patient_data_update","id":"` + idStr + `","attributes":{}}}`, 422},
+		{http.MethodDelete, "/delete/bad", "", 422},
+		{http.MethodDelete, "/delete/" + idStr, "", 400},
+		{http.MethodGet, "/list", "", 400},
+		{http.MethodGet, "/dt", "", 400},
+	}
+
+	for _, tc := range cases {
+		req, _ := http.NewRequest(tc.method, tc.path, strings.NewReader(tc.body))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != tc.want {
+			t.Fatalf("%s %s expected %d got %d", tc.method, tc.path, tc.want, res.StatusCode)
+		}
+	}
+}
+
+func TestInsurancePatientDataHandler_UpdateValidationSpecific(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	svc := &insurancePatientDataServiceMock{
+		getByID: func(_ context.Context, _ []byte) (*insurancepatientdata.InsurancePatientData, error) {
+			return &insurancepatientdata.InsurancePatientData{
+				ID:                         id,
+				HealthInsuranceCompaniesId: id,
+				FederalStateId:             id,
+				CreatedAt:                  time.Now().UTC(),
+				UpdatedAt:                  time.Now().UTC(),
+			}, nil
+		},
+		updateFn: func(_ context.Context, _ *insurancepatientdata.InsurancePatientData) error { return nil },
+	}
+	h := NewInsurancePatientDataHandler(svc)
+	app := newInsurancePatientDataApp(h)
+
+	for _, body := range []string{
+		`{"data":{"type":"insurance_patient_data_update","id":"` + idStr + `","attributes":{"health_insurance_companies_id":"bad"}}}`,
+		`{"data":{"type":"insurance_patient_data_update","id":"` + idStr + `","attributes":{"federal_state_id":"bad"}}}`,
+	} {
+		req, _ := http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ := app.Test(req)
+		if res.StatusCode != 422 {
+			t.Fatalf("expected 422 got %d body=%s", res.StatusCode, body)
+		}
+	}
+}
+
+func TestInsurancePatientDataResource(t *testing.T) {
+	id := uuidv7.MustBytes()
+	row := &insurancepatientdata.InsurancePatientData{
+		ID:                         id,
+		HealthInsuranceCompaniesId: id,
+		FederalStateId:             id,
+		HealthInsuranceCompanies: &healthinsurancecompanies.HealthInsuranceCompany{
+			ID:           id,
+			Name:         "H",
+			State:        "S",
+			Address:      "A",
+			MobileNumber: "M",
+			Email:        "E",
+		},
+		FederalState: &federalstate.FederalState{
+			ID:   id,
+			Name: "F",
+		},
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}
+	res := insurancePatientDataResource(row)
+	if res.Type != "insurance_patient_data" || res.Attributes.HealthInsuranceCompany == nil || res.Attributes.FederalState == nil {
+		t.Fatal("resource mapping failed")
+	}
+}
+
+func TestInsurancePatientDataHandler_FallbackAndPaginationBranches(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	svc := &insurancePatientDataServiceMock{
+		createFn: func(_ context.Context, row *insurancepatientdata.InsurancePatientData) error {
+			row.ID = id
+			return nil
+		},
+		getByID: func(_ context.Context, _ []byte) (*insurancepatientdata.InsurancePatientData, error) {
+			// cover Create fallback path
+			return nil, errors.New("fallback")
+		},
+		updateFn: func(_ context.Context, _ *insurancepatientdata.InsurancePatientData) error { return nil },
+		listFn: func(_ context.Context, _ string, _ string, limit, offset int) ([]insurancepatientdata.InsurancePatientData, int64, error) {
+			if limit < 1 || limit > 100 || offset < 0 {
+				t.Fatalf("unexpected pagination limit=%d offset=%d", limit, offset)
+			}
+			return []insurancepatientdata.InsurancePatientData{}, 0, nil
+		},
+	}
+	h := NewInsurancePatientDataHandler(svc)
+	app := newInsurancePatientDataApp(h)
+
+	req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(`{"data":{"type":"insurance_patient_data_create","attributes":{"health_insurance_companies_id":"`+idStr+`","federal_state_id":"`+idStr+`"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ := app.Test(req)
+	if res.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201 got %d", res.StatusCode)
+	}
+
+	// separate service for Update fallback branch: existing found, updated fetch fails
+	updateCalls := 0
+	h.svc = &insurancePatientDataServiceMock{
+		getByID: func(_ context.Context, _ []byte) (*insurancepatientdata.InsurancePatientData, error) {
+			updateCalls++
+			if updateCalls == 1 {
+				return &insurancepatientdata.InsurancePatientData{
+					ID:                         id,
+					HealthInsuranceCompaniesId: id,
+					FederalStateId:             id,
+					CreatedAt:                  time.Now().UTC(),
+					UpdatedAt:                  time.Now().UTC(),
+				}, nil
+			}
+			if updateCalls == 2 {
+				return nil, errors.New("fallback")
+			}
+			return &insurancepatientdata.InsurancePatientData{
+				ID:                         id,
+				HealthInsuranceCompaniesId: id,
+				FederalStateId:             id,
+				CreatedAt:                  time.Now().UTC(),
+				UpdatedAt:                  time.Now().UTC(),
+			}, nil
+		},
+		updateFn: func(_ context.Context, _ *insurancepatientdata.InsurancePatientData) error { return nil },
+		listFn:   svc.listFn,
+	}
+
+	req, _ = http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(`{"data":{"type":"insurance_patient_data_update","id":"`+idStr+`","attributes":{"health_insurance_companies_id":"`+idStr+`"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 got %d", res.StatusCode)
+	}
+
+	for _, path := range []string{
+		"/list?page[number]=-1&page[size]=1000",
+		"/list?page=0&limit=0&size=0",
+		"/dt?page=-1&size=1000",
+		"/dt?page=0&limit=0&size=0",
+	} {
+		req, _ = http.NewRequest(http.MethodGet, path, nil)
+		res, _ = app.Test(req)
+		if res.StatusCode != http.StatusOK {
+			t.Fatalf("%s expected 200 got %d", path, res.StatusCode)
+		}
+	}
+}
+
+func TestInsurancePatientDataHandler_CreateValidateAndUpdateFailedBranch(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	svc := &insurancePatientDataServiceMock{
+		getByID: func(_ context.Context, _ []byte) (*insurancepatientdata.InsurancePatientData, error) {
+			return &insurancepatientdata.InsurancePatientData{
+				ID:                         id,
+				HealthInsuranceCompaniesId: id,
+				FederalStateId:             id,
+				CreatedAt:                  time.Now().UTC(),
+				UpdatedAt:                  time.Now().UTC(),
+			}, nil
+		},
+		updateFn: func(_ context.Context, _ *insurancepatientdata.InsurancePatientData) error {
+			return errors.New("update failed")
+		},
+	}
+	h := NewInsurancePatientDataHandler(svc)
+	app := newInsurancePatientDataApp(h)
+
+	req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(`{}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ := app.Test(req)
+	if res.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422 got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(`{"data":{"type":"insurance_patient_data_update","id":"`+idStr+`","attributes":{"federal_state_id":"`+idStr+`"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400 got %d", res.StatusCode)
+	}
+}
+
+func TestInsurancePatientDataHandler_UpdateValidatorAndNilExistingBranches(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+
+	// validator error path
+	svc := &insurancePatientDataServiceMock{}
+	h := NewInsurancePatientDataHandler(svc)
+	app := newInsurancePatientDataApp(h)
+	req, _ := http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(`{"data":{"type":"bad_type","id":"`+idStr+`","attributes":{"health_insurance_companies_id":"`+idStr+`"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ := app.Test(req)
+	if res.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422 got %d", res.StatusCode)
+	}
+
+	// existing == nil path
+	h.svc = &insurancePatientDataServiceMock{
+		getByID: func(_ context.Context, _ []byte) (*insurancepatientdata.InsurancePatientData, error) { return nil, nil },
+	}
+	req, _ = http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(`{"data":{"type":"insurance_patient_data_update","id":"`+idStr+`","attributes":{"health_insurance_companies_id":"`+idStr+`"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404 got %d", res.StatusCode)
+	}
+}
diff --git a/internal/transport/http/handlers/land_handler.go b/internal/transport/http/handlers/land_handler.go
new file mode 100644
index 0000000..1e6623e
--- /dev/null
+++ b/internal/transport/http/handlers/land_handler.go
@@ -0,0 +1,608 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/land"
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type LandHandler struct {
+	svc      land.Service
+	validate *validators.Validator
+}
+
+func NewLandHandler(svc land.Service) *LandHandler {
+	return &LandHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateLand godoc
+// @Summary Create land
+// @Description Create a land row.
+// @Tags Hospital - Land
+// @Accept json
+// @Produce json
+// @Param request body dto.LandCreateRequest true "JSON:API land create request"
+// @Success 201 {object} dto.LandResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/land/create [post]
+func (h *LandHandler) Create(c *fiber.Ctx) error {
+	var req dto.LandCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeLandErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeLandErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	name := strings.TrimSpace(req.Data.Attributes.Name)
+	if name == "" {
+		return writeLandErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+		}})
+	}
+	isoCode, isoOK := normalizeOptionalISOCode(req.Data.Attributes.ISOCode)
+	if !isoOK {
+		return writeLandErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "iso_code must be empty or 2 uppercase letters (A-Z)",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/iso_code"},
+		}})
+	}
+
+	row := &land.Land{
+		Name:        name,
+		Note:        strings.TrimSpace(stringOrDefault(req.Data.Attributes.Note, "")),
+		LandISOCode: isoCode,
+		BMDExportID: normalizeOptionalBMDExportID(req.Data.Attributes.BMDExportID),
+		SortKey:     cloneIntPointer(req.Data.Attributes.SortKey),
+		IsActive:    boolOrDefault(req.Data.Attributes.IsActive, true),
+		CreatedBy:   actorUserID(c),
+		UpdatedBy:   actorUserID(c),
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		if isLandISOCodeDuplicateError(err) {
+			return writeLandErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "iso_code already exists",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/iso_code"},
+			}})
+		}
+		return writeLandErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.getByIDView(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, landResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, landResource(&dto.LandView{Row: *row}))
+}
+
+// UpdateLand godoc
+// @Summary Update land (partial)
+// @Description Patch land by ID.
+// @Tags Hospital - Land
+// @Accept json
+// @Produce json
+// @Param id path string true "Land ID (UUIDv7)"
+// @Param request body dto.LandUpdateRequest true "JSON:API land update request"
+// @Success 200 {object} dto.LandResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/land/update/{id} [patch]
+func (h *LandHandler) Update(c *fiber.Ctx) error {
+	idStr := c.Params("id")
+	id, err := uuidv7.ParseString(idStr)
+	if err != nil {
+		return writeLandErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	var req dto.LandUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeLandErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeLandErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeLandErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != idStr {
+		return writeLandErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path id",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Name == nil && attrs.Note == nil && attrs.ISOCode == nil && attrs.BMDExportID == nil && !attrs.SortKey.Set && attrs.IsActive == nil {
+		return writeLandErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeLandErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "land not found",
+		}})
+	}
+
+	if attrs.Name != nil {
+		v := strings.TrimSpace(*attrs.Name)
+		if v == "" {
+			return writeLandErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+			}})
+		}
+		existing.Name = v
+	}
+	if attrs.Note != nil {
+		existing.Note = strings.TrimSpace(*attrs.Note)
+	}
+	if attrs.ISOCode != nil {
+		isoCode, isoOK := normalizeOptionalISOCode(*attrs.ISOCode)
+		if !isoOK {
+			return writeLandErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "iso_code must be empty or 2 uppercase letters (A-Z)",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/iso_code"},
+			}})
+		}
+		existing.LandISOCode = isoCode
+	}
+	if attrs.BMDExportID != nil {
+		existing.BMDExportID = normalizeOptionalBMDExportID(attrs.BMDExportID)
+	}
+	if attrs.SortKey.Set {
+		if attrs.SortKey.Valid {
+			sortKey := attrs.SortKey.Value
+			existing.SortKey = &sortKey
+		} else {
+			existing.SortKey = nil
+		}
+	}
+	if attrs.IsActive != nil {
+		existing.IsActive = *attrs.IsActive
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		if isLandISOCodeDuplicateError(err) {
+			return writeLandErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "iso_code already exists",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/iso_code"},
+			}})
+		}
+		return writeLandErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.getByIDView(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, landResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, landResource(&dto.LandView{Row: *existing}))
+}
+
+// DeleteLand godoc
+// @Summary Delete land
+// @Tags Hospital - Land
+// @Produce json
+// @Param id path string true "Land ID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/land/delete/{id} [delete]
+func (h *LandHandler) Delete(c *fiber.Ctx) error {
+	idStr := c.Params("id")
+	id, err := uuidv7.ParseString(idStr)
+	if err != nil {
+		return writeLandErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeLandErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "land not found",
+			}})
+		}
+		if conflict, ok := apperrors.AsDeleteConflict(err); ok {
+			return writeLandErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{
+				Status: "409",
+				Title:  "Conflict",
+				Detail: conflict.Error(),
+			}})
+		}
+		return writeLandErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "land_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListLand godoc
+// @Summary List land
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.
+// @Tags Hospital - Land
+// @Produce json
+// @Param filter[search] query string false "Search by name"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.LandListResponse
+// @Router /api/v1/land/get-all [get]
+func (h *LandHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("filter[name]")
+	}
+	if filter == "" {
+		filter = c.Query("search")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	sort := c.Query("sort")
+
+	rows, total, err := h.listView(c.UserContext(), filter, sort, pageSize, offset)
+	if err != nil {
+		return writeLandErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.LandResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, landResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListLandDatatable godoc
+// @Summary List land (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags Hospital - Land
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 1000)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.LandDataTableResponse
+// @Router /api/v1/land/get-all/dt [get]
+func (h *LandHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 1000 {
+		length = 1000
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.listView(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return writeLandErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.LandResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, landResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func landResource(row *dto.LandView) dto.LandResource {
+	return dto.LandResource{
+		Type: "land",
+		ID:   idString(row.Row.ID),
+		Attributes: dto.LandAttributes{
+			Name:              row.Row.Name,
+			Note:              row.Row.Note,
+			ISOCode:           row.Row.LandISOCode,
+			BMDExportID:       cloneStringPointer(row.Row.BMDExportID),
+			FederalStateTotal: row.FederalStateTotal,
+			FederalStateList:  landFederalStateDTOs(row.FederalStateList),
+			SortKey:           cloneIntPointer(row.Row.SortKey),
+			IsActive:          row.Row.IsActive,
+			CreatedAt:         row.Row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:         uuidStringOrEmpty(row.Row.CreatedBy),
+			UpdatedAt:         row.Row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:         uuidStringOrEmpty(row.Row.UpdatedBy),
+			DeletedAt:         timeStringOrEmpty(row.Row.DeletedAt),
+			DeletedBy:         uuidStringOrEmpty(row.Row.DeletedBy),
+		},
+	}
+}
+
+func normalizeOptionalBMDExportID(raw *string) *string {
+	if raw == nil {
+		return nil
+	}
+	v := strings.TrimSpace(*raw)
+	if v == "" {
+		return nil
+	}
+	return &v
+}
+
+func cloneStringPointer(v *string) *string {
+	if v == nil {
+		return nil
+	}
+	out := *v
+	return &out
+}
+
+func normalizeOptionalISOCode(raw string) (string, bool) {
+	code := strings.ToUpper(strings.TrimSpace(raw))
+	if code == "" {
+		return "", true
+	}
+	if len(code) != 2 {
+		return "", false
+	}
+	for _, ch := range code {
+		if ch < 'A' || ch > 'Z' {
+			return "", false
+		}
+	}
+	return code, true
+}
+
+func landFederalStateDTOs(rows []dto.LandFederalStateView) []dto.LandFederalStateDTO {
+	if len(rows) == 0 {
+		return nil
+	}
+	out := make([]dto.LandFederalStateDTO, 0, len(rows))
+	for i := range rows {
+		out = append(out, dto.LandFederalStateDTO{
+			ID:   idString(rows[i].ID),
+			Name: rows[i].Name,
+		})
+	}
+	return out
+}
+
+func (h *LandHandler) getByIDView(ctx context.Context, id []byte) (*dto.LandView, error) {
+	if svc, ok := h.svc.(interface {
+		GetByIDView(context.Context, []byte) (*dto.LandView, error)
+	}); ok {
+		return svc.GetByIDView(ctx, id)
+	}
+	row, err := h.svc.GetByID(ctx, id)
+	if err != nil || row == nil {
+		return nil, err
+	}
+	return &dto.LandView{Row: *row}, nil
+}
+
+func isLandISOCodeDuplicateError(err error) bool {
+	if errors.Is(err, gorm.ErrDuplicatedKey) {
+		return true
+	}
+
+	var mysqlErr *mysqldriver.MySQLError
+	if !errors.As(err, &mysqlErr) || mysqlErr.Number != 1062 {
+		return false
+	}
+
+	msg := strings.ToLower(mysqlErr.Message)
+	return strings.Contains(msg, "uq_lands_land_iso_code") || strings.Contains(msg, "land_iso_code")
+}
+
+func (h *LandHandler) listView(ctx context.Context, filter, sort string, limit, offset int) ([]dto.LandView, int64, error) {
+	if svc, ok := h.svc.(interface {
+		ListView(context.Context, string, string, int, int) ([]dto.LandView, int64, error)
+	}); ok {
+		return svc.ListView(ctx, filter, sort, limit, offset)
+	}
+	rows, total, err := h.svc.List(ctx, filter, sort, limit, offset)
+	if err != nil {
+		return nil, 0, err
+	}
+	views := make([]dto.LandView, 0, len(rows))
+	for i := range rows {
+		views = append(views, dto.LandView{Row: rows[i]})
+	}
+	return views, total, nil
+}
+
+func writeLandErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	statusStr := strconv.Itoa(status)
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferLandDef(status, e.Title, e.Detail)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		e.Detail = def.Message
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferLandErrorCode(status int, title, detail string) (string, string) {
+	def := inferLandDef(status, title, detail)
+	return def.Code, def.ErrorCode
+}
+
+func inferLandDef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.ErrLandNotFound
+	case fiber.StatusConflict:
+		return apperrorsx.ErrLandRelationDelete
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "id is invalid uuid"), strings.Contains(lowerDetail, "invalid uuid"):
+			return apperrorsx.ErrLandInvalidID
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.ErrLandIDRequired
+		case strings.Contains(lowerDetail, "id does not match path id"):
+			return apperrorsx.ErrLandIDMismatch
+		case strings.Contains(lowerDetail, "at least one attribute must be provided"):
+			return apperrorsx.ErrLandAttributesRequired
+		case strings.Contains(lowerDetail, "name is required"), strings.Contains(lowerDetail, "name cannot be empty"):
+			return apperrorsx.ErrLandNameRequired
+		case strings.Contains(lowerDetail, "iso_code must"):
+			return apperrorsx.ErrLandISOCodeInvalid
+		case strings.Contains(lowerDetail, "iso_code already exists"):
+			return apperrorsx.ErrLandISOCodeDuplicate
+		default:
+			return apperrorsx.ErrLandInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrLandInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.ErrLandCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrLandUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrLandDeleteFailed
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.ErrLandListFailed
+		default:
+			return apperrorsx.ErrLandInvalidPayload
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
diff --git a/internal/transport/http/handlers/land_handler_test.go b/internal/transport/http/handlers/land_handler_test.go
new file mode 100644
index 0000000..810655a
--- /dev/null
+++ b/internal/transport/http/handlers/land_handler_test.go
@@ -0,0 +1,746 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/land"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+)
+
+type memLandRepo struct {
+	rows map[string]*land.Land
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+
+	listRows  []land.Land
+	listTotal int64
+
+	getByIDFn func(id []byte, call int) (*land.Land, error)
+	getCalls  int
+
+	lastCreate     *land.Land
+	lastUpdate     *land.Land
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+}
+
+func newMemLandRepo() *memLandRepo {
+	return &memLandRepo{
+		rows: map[string]*land.Land{},
+	}
+}
+
+func (r *memLandRepo) Create(_ context.Context, row *land.Land) error {
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.rows[string(row.ID)] = row
+	r.lastCreate = row
+	return nil
+}
+
+func (r *memLandRepo) Update(_ context.Context, row *land.Land) error {
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	r.rows[string(row.ID)] = row
+	r.lastUpdate = row
+	return nil
+}
+
+func (r *memLandRepo) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	r.lastDeleteID = append([]byte(nil), id...)
+	r.lastDeleteBy = append([]byte(nil), deletedBy...)
+	delete(r.rows, string(id))
+	return nil
+}
+
+func (r *memLandRepo) GetByID(_ context.Context, id []byte) (*land.Land, error) {
+	r.getCalls++
+	if r.getByIDFn != nil {
+		return r.getByIDFn(id, r.getCalls)
+	}
+	if r.getByIDErr != nil {
+		return nil, r.getByIDErr
+	}
+	return r.rows[string(id)], nil
+}
+
+func (r *memLandRepo) List(_ context.Context, filter, sort string, limit, offset int) ([]land.Land, int64, error) {
+	r.lastListFilter = filter
+	r.lastListSort = sort
+	r.lastListLimit = limit
+	r.lastListOffset = offset
+	if r.listErr != nil {
+		return nil, 0, r.listErr
+	}
+	return r.listRows, r.listTotal, nil
+}
+
+func newLandTestApp(h *LandHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", actor)
+		}
+		return c.Next()
+	})
+	app.Post("/api/v1/land/create", h.Create)
+	app.Patch("/api/v1/land/update/:id", h.Update)
+	app.Delete("/api/v1/land/delete/:id", h.Delete)
+	app.Get("/api/v1/land/get-all", h.List)
+	app.Get("/api/v1/land/get-all/dt", h.ListDatatable)
+	return app
+}
+
+func doJSONRequestLand(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDStringLand(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestNewLandHandler(t *testing.T) {
+	h := NewLandHandler(service.NewLandService(newMemLandRepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+type landViewServiceMock struct {
+	land.Service
+	getByIDViewFn func(context.Context, []byte) (*dto.LandView, error)
+	listViewFn    func(context.Context, string, string, int, int) ([]dto.LandView, int64, error)
+}
+
+func (m *landViewServiceMock) GetByIDView(ctx context.Context, id []byte) (*dto.LandView, error) {
+	return m.getByIDViewFn(ctx, id)
+}
+
+func (m *landViewServiceMock) ListView(ctx context.Context, filter, sort string, limit, offset int) ([]dto.LandView, int64, error) {
+	return m.listViewFn(ctx, filter, sort, limit, offset)
+}
+
+func TestLandHandlerViewHelpers(t *testing.T) {
+	t.Run("getByIDView via extended interface", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		want := &dto.LandView{Row: land.Land{ID: id, Name: "Austria"}}
+		h := NewLandHandler(&landViewServiceMock{
+			getByIDViewFn: func(_ context.Context, gotID []byte) (*dto.LandView, error) {
+				if string(gotID) != string(id) {
+					t.Fatalf("unexpected id")
+				}
+				return want, nil
+			},
+		})
+		got, err := h.getByIDView(context.Background(), id)
+		if err != nil || got == nil || got.Row.Name != "Austria" {
+			t.Fatalf("expected extended getByIDView path")
+		}
+	})
+
+	t.Run("getByIDView fallback via base service", func(t *testing.T) {
+		repo := newMemLandRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &land.Land{ID: id, Name: "Germany"}
+		h := NewLandHandler(service.NewLandService(repo))
+		got, err := h.getByIDView(context.Background(), id)
+		if err != nil || got == nil || got.Row.Name != "Germany" {
+			t.Fatalf("expected fallback getByIDView")
+		}
+	})
+
+	t.Run("listView via extended interface", func(t *testing.T) {
+		h := NewLandHandler(&landViewServiceMock{
+			listViewFn: func(_ context.Context, filter, sort string, limit, offset int) ([]dto.LandView, int64, error) {
+				if filter != "eu" || sort != "name ASC" || limit != 10 || offset != 5 {
+					t.Fatalf("unexpected list args")
+				}
+				return []dto.LandView{{Row: land.Land{Name: "Italy"}}}, 1, nil
+			},
+		})
+		rows, total, err := h.listView(context.Background(), "eu", "name ASC", 10, 5)
+		if err != nil || total != 1 || len(rows) != 1 || rows[0].Row.Name != "Italy" {
+			t.Fatalf("expected extended listView")
+		}
+	})
+
+	t.Run("listView fallback via base service", func(t *testing.T) {
+		repo := newMemLandRepo()
+		repo.listRows = []land.Land{{ID: uuidv7.MustBytes(), Name: "France"}}
+		repo.listTotal = 1
+		h := NewLandHandler(service.NewLandService(repo))
+		rows, total, err := h.listView(context.Background(), "", "name ASC", 20, 0)
+		if err != nil || total != 1 || len(rows) != 1 || rows[0].Row.Name != "France" {
+			t.Fatalf("expected fallback listView")
+		}
+	})
+}
+
+func TestLandHandlerCreate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPost, "/api/v1/land/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPost, "/api/v1/land/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"land","attributes":{"name":"  "}}}`)
+		resp, _ := doJSONRequestLand(t, app, http.MethodPost, "/api/v1/land/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		repo := newMemLandRepo()
+		repo.createErr = errors.New("create failed")
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"land","attributes":{"name":"Germany"}}}`)
+		resp, _ := doJSONRequestLand(t, app, http.MethodPost, "/api/v1/land/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("duplicate iso_code", func(t *testing.T) {
+		repo := newMemLandRepo()
+		repo.createErr = &mysqldriver.MySQLError{
+			Number:  1062,
+			Message: "Duplicate entry 'DE' for key 'uq_lands_land_iso_code'",
+		}
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"land","attributes":{"name":"Germany","iso_code":"DE"}}}`)
+		resp, respBody := doJSONRequestLand(t, app, http.MethodPost, "/api/v1/land/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+		if !bytes.Contains(respBody, []byte(`"iso_code already exists"`)) {
+			t.Fatalf("expected duplicate iso_code detail, got %s", string(respBody))
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		actor := uuidv7.MustBytes()
+		app := newLandTestApp(h, actor)
+
+		body := []byte(`{"data":{"type":"land","attributes":{"name":"Germany","note":"  EU region  ","iso_code":"de","bmd_export_id":" DE001 ","sortkey":3,"is_active":false}}}`)
+		resp, _ := doJSONRequestLand(t, app, http.MethodPost, "/api/v1/land/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected row created")
+		}
+		if repo.lastCreate.Name != "Germany" {
+			t.Fatalf("expected attributes to be mapped and trimmed")
+		}
+		if repo.lastCreate.LandISOCode != "DE" {
+			t.Fatalf("expected iso_code normalized")
+		}
+		if repo.lastCreate.BMDExportID == nil || *repo.lastCreate.BMDExportID != "DE001" {
+			t.Fatalf("expected bmd_export_id normalized")
+		}
+		if repo.lastCreate.Note != "EU region" {
+			t.Fatalf("expected note normalized")
+		}
+		if repo.lastCreate.SortKey == nil || *repo.lastCreate.SortKey != 3 {
+			t.Fatalf("expected sortkey=3 to be mapped")
+		}
+		if repo.lastCreate.IsActive {
+			t.Fatalf("expected is_active=false to be mapped")
+		}
+		if string(repo.lastCreate.CreatedBy) != string(actor) || string(repo.lastCreate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected created_by and updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback when refetch error", func(t *testing.T) {
+		repo := newMemLandRepo()
+		repo.getByIDFn = func(_ []byte, call int) (*land.Land, error) {
+			if call > 0 {
+				return nil, errors.New("lookup failed")
+			}
+			return nil, nil
+		}
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"land","attributes":{"name":"Germany"}}}`)
+		resp, _ := doJSONRequestLand(t, app, http.MethodPost, "/api/v1/land/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestLandHandlerUpdate(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPatch, "/api/v1/land/update/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+		id := mustUUIDStringLand(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPatch, "/api/v1/land/update/"+id, []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+		id := mustUUIDStringLand(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPatch, "/api/v1/land/update/"+id, []byte(`{"data":{"type":"x","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+		id := mustUUIDStringLand(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPatch, "/api/v1/land/update/"+id, []byte(`{"data":{"type":"land","id":"","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+		id := mustUUIDStringLand(t, uuidv7.MustBytes())
+		other := mustUUIDStringLand(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPatch, "/api/v1/land/update/"+id, []byte(`{"data":{"type":"land","id":"`+other+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no attributes", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+		id := mustUUIDStringLand(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPatch, "/api/v1/land/update/"+id, []byte(`{"data":{"type":"land","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+		id := mustUUIDStringLand(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPatch, "/api/v1/land/update/"+id, []byte(`{"data":{"type":"land","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemLandRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &land.Land{ID: id, Name: "Old"}
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+		idStr := mustUUIDStringLand(t, id)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPatch, "/api/v1/land/update/"+idStr, []byte(`{"data":{"type":"land","id":"`+idStr+`","attributes":{"name":"  "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		repo := newMemLandRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &land.Land{ID: id, Name: "Old"}
+		repo.updateErr = errors.New("update failed")
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+		idStr := mustUUIDStringLand(t, id)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPatch, "/api/v1/land/update/"+idStr, []byte(`{"data":{"type":"land","id":"`+idStr+`","attributes":{"name":"New"}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemLandRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &land.Land{ID: id, Name: "Old"}
+		h := NewLandHandler(service.NewLandService(repo))
+		actor := uuidv7.MustBytes()
+		app := newLandTestApp(h, actor)
+		idStr := mustUUIDStringLand(t, id)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPatch, "/api/v1/land/update/"+idStr, []byte(`{"data":{"type":"land","id":"`+idStr+`","attributes":{"name":"  New  ","note":"  updated note  ","iso_code":"id","bmd_export_id":" ID123 ","sortkey":2,"is_active":false}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.Name != "New" {
+			t.Fatalf("expected updated values")
+		}
+		if repo.lastUpdate.LandISOCode != "ID" {
+			t.Fatalf("expected updated iso_code")
+		}
+		if repo.lastUpdate.BMDExportID == nil || *repo.lastUpdate.BMDExportID != "ID123" {
+			t.Fatalf("expected updated bmd_export_id")
+		}
+		if repo.lastUpdate.Note != "updated note" {
+			t.Fatalf("expected updated note")
+		}
+		if repo.lastUpdate.SortKey == nil || *repo.lastUpdate.SortKey != 2 {
+			t.Fatalf("expected updated sortkey=2")
+		}
+		if repo.lastUpdate.IsActive {
+			t.Fatalf("expected is_active=false updated")
+		}
+		if string(repo.lastUpdate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		repo := newMemLandRepo()
+		id := uuidv7.MustBytes()
+		existing := &land.Land{ID: id, Name: "Old"}
+		repo.getByIDFn = func(_ []byte, call int) (*land.Land, error) {
+			if call == 1 {
+				return existing, nil
+			}
+			return nil, errors.New("second lookup failed")
+		}
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+		idStr := mustUUIDStringLand(t, id)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodPatch, "/api/v1/land/update/"+idStr, []byte(`{"data":{"type":"land","id":"`+idStr+`","attributes":{"name":"Only"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("duplicate iso_code", func(t *testing.T) {
+		repo := newMemLandRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &land.Land{
+			ID:          id,
+			Name:        "Germany",
+			LandISOCode: "DE",
+			IsActive:    true,
+		}
+		repo.updateErr = &mysqldriver.MySQLError{
+			Number:  1062,
+			Message: "Duplicate entry 'ID' for key 'uq_lands_land_iso_code'",
+		}
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+		idStr := mustUUIDStringLand(t, id)
+
+		resp, respBody := doJSONRequestLand(t, app, http.MethodPatch, "/api/v1/land/update/"+idStr, []byte(`{"data":{"type":"land","id":"`+idStr+`","attributes":{"iso_code":"ID"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+		if !bytes.Contains(respBody, []byte(`"iso_code already exists"`)) {
+			t.Fatalf("expected duplicate iso_code detail, got %s", string(respBody))
+		}
+	})
+}
+
+func TestLandHandlerDelete(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodDelete, "/api/v1/land/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete error", func(t *testing.T) {
+		repo := newMemLandRepo()
+		repo.deleteErr = errors.New("delete failed")
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+		id := mustUUIDStringLand(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodDelete, "/api/v1/land/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemLandRepo()
+		h := NewLandHandler(service.NewLandService(repo))
+		actor := uuidv7.MustBytes()
+		app := newLandTestApp(h, actor)
+		id := uuidv7.MustBytes()
+		idStr := mustUUIDStringLand(t, id)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodDelete, "/api/v1/land/delete/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(repo.lastDeleteBy) != string(actor) {
+			t.Fatalf("expected deleted_by from actor")
+		}
+	})
+}
+
+func TestLandHandlerList(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemLandRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodGet, "/api/v1/land/get-all", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with filter name and clamp max", func(t *testing.T) {
+		repo := newMemLandRepo()
+		repo.listRows = []land.Land{{ID: uuidv7.MustBytes(), Name: "A", SortKey: intPtrLandHandler(3), CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodGet, "/api/v1/land/get-all?filter[name]=abc&page[number]=0&page=0&page[size]=0&limit=101&sort=-sortkey", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q sort=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListSort, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success with search and clamp min", func(t *testing.T) {
+		repo := newMemLandRepo()
+		repo.listRows = []land.Land{}
+		repo.listTotal = 0
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodGet, "/api/v1/land/get-all?page=2&size=-1&search=needle", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "needle" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestLandHandlerListDatatable(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemLandRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodGet, "/api/v1/land/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success page floor without clamping small custom size", func(t *testing.T) {
+		repo := newMemLandRepo()
+		repo.listRows = []land.Land{{ID: uuidv7.MustBytes(), Name: "A", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodGet, "/api/v1/land/get-all/dt?page=0&limit=0&size=101&draw=7&search=abc", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListLimit != 101 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success clamp min", func(t *testing.T) {
+		repo := newMemLandRepo()
+		repo.listRows = []land.Land{}
+		repo.listTotal = 0
+		h := NewLandHandler(service.NewLandService(repo))
+		app := newLandTestApp(h, nil)
+
+		resp, _ := doJSONRequestLand(t, app, http.MethodGet, "/api/v1/land/get-all/dt?page=2&limit=0&size=-1", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListLimit != 20 || repo.lastListOffset != 20 {
+			t.Fatalf("unexpected list params: limit=%d offset=%d", repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestLandResource(t *testing.T) {
+	id := uuidv7.MustBytes()
+	createdBy := uuidv7.MustBytes()
+	updatedBy := uuidv7.MustBytes()
+	deletedBy := uuidv7.MustBytes()
+	now := time.Now().UTC().Truncate(time.Second)
+	deletedAt := now.Add(time.Hour)
+
+	row := &dto.LandView{
+		Row: land.Land{
+			ID:          id,
+			Name:        "Germany",
+			Note:        "EU region",
+			LandISOCode: "DE",
+			BMDExportID: strPtrLandHandler("DE001"),
+			SortKey:     intPtrLandHandler(2),
+			IsActive:    true,
+			CreatedAt:   now,
+			CreatedBy:   createdBy,
+			UpdatedAt:   now,
+			UpdatedBy:   updatedBy,
+			DeletedAt:   &deletedAt,
+			DeletedBy:   deletedBy,
+		},
+		FederalStateTotal: 2,
+		FederalStateList: []dto.LandFederalStateView{
+			{ID: uuidv7.MustBytes(), Name: "Bayern"},
+			{ID: uuidv7.MustBytes(), Name: "Berlin"},
+		},
+	}
+
+	res := landResource(row)
+	if res.Type != "land" {
+		t.Fatalf("unexpected type: %s", res.Type)
+	}
+	if res.ID == "" || res.Attributes.CreatedBy == "" || res.Attributes.UpdatedBy == "" || res.Attributes.DeletedBy == "" {
+		t.Fatalf("expected UUID fields to be mapped")
+	}
+	if res.Attributes.Name != "Germany" {
+		t.Fatalf("unexpected attribute mapping")
+	}
+	if res.Attributes.Note != "EU region" {
+		t.Fatalf("expected note mapped")
+	}
+	if res.Attributes.ISOCode != "DE" {
+		t.Fatalf("expected iso_code mapped")
+	}
+	if res.Attributes.BMDExportID == nil || *res.Attributes.BMDExportID != "DE001" {
+		t.Fatalf("expected bmd_export_id mapped")
+	}
+	if res.Attributes.FederalStateTotal != 2 || len(res.Attributes.FederalStateList) != 2 {
+		t.Fatalf("expected federal_state aggregate fields mapped")
+	}
+	if res.Attributes.SortKey == nil || *res.Attributes.SortKey != 2 {
+		t.Fatalf("expected sortkey mapped")
+	}
+	if !res.Attributes.IsActive {
+		t.Fatalf("expected is_active mapped")
+	}
+	if res.Attributes.CreatedAt == "" || res.Attributes.UpdatedAt == "" || res.Attributes.DeletedAt == "" {
+		t.Fatalf("expected time fields to be mapped")
+	}
+}
+
+func intPtrLandHandler(v int) *int { return &v }
+
+func strPtrLandHandler(v string) *string { return &v }
diff --git a/internal/transport/http/handlers/master_settings_handler.go b/internal/transport/http/handlers/master_settings_handler.go
new file mode 100644
index 0000000..ee18fc7
--- /dev/null
+++ b/internal/transport/http/handlers/master_settings_handler.go
@@ -0,0 +1,752 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	mastersettings "wucher/internal/domain/master_settings"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type MasterSettingsHandler struct {
+	svc      mastersettings.Service
+	fileSvc  filemanager.Service
+	storage  filemanager.ObjectStorage
+	validate *validators.Validator
+}
+
+type managedFileAsset struct {
+	OriginalURL       *string
+	ThumbnailURL      *string
+	OriginalSizeBytes *int64
+}
+
+func NewMasterSettingsHandler(svc mastersettings.Service, fileSvc filemanager.Service, storage filemanager.ObjectStorage) *MasterSettingsHandler {
+	return &MasterSettingsHandler{
+		svc:      svc,
+		fileSvc:  fileSvc,
+		storage:  storage,
+		validate: validators.New(),
+	}
+}
+
+// CreateMasterSettings godoc
+// @Summary Create master settings
+// @Description Create a master settings row.
+// @Tags Master Settings
+// @Accept json
+// @Produce json
+// @Param request body requestdto.MasterSettingsCreateRequest true "JSON:API master settings create request"
+// @Success 201 {object} responsedto.MasterSettingsResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/master-settings/create [post]
+func (h *MasterSettingsHandler) Create(c *fiber.Ctx) error {
+	var req requestdto.MasterSettingsCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	companyName := strings.TrimSpace(req.Data.Attributes.CompanyName)
+	if companyName == "" {
+		return writeMasterSettingsErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "company_name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/company_name"},
+		}})
+	}
+
+	logoFileID, statusCode, errObj := h.resolveLogoFileID(c.UserContext(), req.Data.Attributes.LogoFileUUID, "/data/attributes/logo_file_uuid")
+	if errObj != nil {
+		return writeMasterSettingsErrors(c, statusCode, []jsonapi.ErrorObject{*errObj})
+	}
+	coverFileID, statusCode, errObj := h.resolveCoverFileID(c.UserContext(), req.Data.Attributes.CoverFileUUID, "/data/attributes/cover_file_uuid")
+	if errObj != nil {
+		return writeMasterSettingsErrors(c, statusCode, []jsonapi.ErrorObject{*errObj})
+	}
+
+	row := &mastersettings.MasterSettings{
+		CompanyName: companyName,
+		Title:       optionalTrimmedString(req.Data.Attributes.Title),
+		Subtitle:    optionalTrimmedString(req.Data.Attributes.Subtitle),
+		LogoFileID:  logoFileID,
+		CoverFileID: coverFileID,
+		LogoURL:     nil,
+		CreatedBy:   actorUserID(c),
+		UpdatedBy:   actorUserID(c),
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if err := syncFileLifecycleSwap(c.UserContext(), h.fileSvc, nil, row.LogoFileID, actorUserID(c)); err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if err := syncFileLifecycleSwap(c.UserContext(), h.fileSvc, nil, row.CoverFileID, actorUserID(c)); err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, h.masterSettingsResource(c, created))
+	}
+	return response.Write(c, fiber.StatusCreated, h.masterSettingsResource(c, row))
+}
+
+// GetMasterSettings godoc
+// @Summary Get current master settings
+// @Description Return singleton master settings object (latest active row).
+// @Tags Master Settings
+// @Produce json
+// @Success 200 {object} responsedto.MasterSettingsResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/master-settings/get [get]
+func (h *MasterSettingsHandler) Get(c *fiber.Ctx) error {
+	rows, _, err := h.svc.List(c.UserContext(), "", "-updated_at", 1, 0)
+	if err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	if len(rows) == 0 {
+		return response.Write(c, fiber.StatusOK, responsedto.MasterSettingsResponse{
+			Data: responsedto.MasterSettingsResource{
+				Type: "master_settings",
+				ID:   "",
+				Attributes: responsedto.MasterSettingsAttributes{
+					CompanyName: "",
+				},
+			},
+		})
+	}
+
+	return response.Write(c, fiber.StatusOK, h.masterSettingsResource(c, &rows[0]))
+}
+
+// UpsertMicrosoftEntraSSO godoc
+// @Summary Upsert Microsoft Entra SSO settings
+// @Description Create or update Microsoft Entra SSO settings as master settings.
+// @Tags Master Settings
+// @Accept json
+// @Produce json
+// @Param request body requestdto.MasterSettingsMicrosoftEntraUpsertRequest true "JSON:API Microsoft Entra SSO upsert request"
+// @Success 200 {object} responsedto.MasterSettingsMicrosoftEntraResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/master-settings/sso/microsoft [put]
+func (h *MasterSettingsHandler) UpsertMicrosoftEntraSSO(c *fiber.Ctx) error {
+	var req requestdto.MasterSettingsMicrosoftEntraUpsertRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	view, err := h.svc.UpsertMicrosoftEntraConfig(c.UserContext(), mastersettings.MicrosoftEntraConfigInput{
+		TenantID:     req.Data.Attributes.TenantID,
+		ClientID:     req.Data.Attributes.ClientID,
+		ClientSecret: req.Data.Attributes.ClientSecret,
+		RedirectURL:  req.Data.Attributes.RedirectURL,
+		Authority:    req.Data.Attributes.Authority,
+		Scopes:       req.Data.Attributes.Scopes,
+	}, actorUserID(c))
+	if err != nil {
+		status := fiber.StatusBadRequest
+		title := "Upsert failed"
+		if isMicrosoftEntraValidationError(err) {
+			status = fiber.StatusUnprocessableEntity
+			title = "Validation error"
+		}
+		return writeMasterSettingsErrors(c, status, []jsonapi.ErrorObject{{
+			Status: strconv.Itoa(status),
+			Title:  title,
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, h.microsoftEntraResource(view))
+}
+
+// GetMicrosoftEntraSSO godoc
+// @Summary Get Microsoft Entra SSO settings
+// @Description Get Microsoft Entra SSO settings from master settings.
+// @Tags Master Settings
+// @Produce json
+// @Success 200 {object} responsedto.MasterSettingsMicrosoftEntraResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/master-settings/sso/microsoft [get]
+func (h *MasterSettingsHandler) GetMicrosoftEntraSSO(c *fiber.Ctx) error {
+	view, err := h.svc.GetMicrosoftEntraConfig(c.UserContext())
+	if err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if view == nil {
+		return writeMasterSettingsErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "microsoft entra sso settings not found",
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, h.microsoftEntraResource(view))
+}
+
+// UpdateMasterSettings godoc
+// @Summary Update master settings (partial)
+// @Description Patch master settings by ID.
+// @Tags Master Settings
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Master Settings UUID (UUIDv7)"
+// @Param request body requestdto.MasterSettingsUpdateRequest true "JSON:API master settings update request"
+// @Success 200 {object} responsedto.MasterSettingsResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Router /api/v1/master-settings/update/{uuid} [patch]
+func (h *MasterSettingsHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req requestdto.MasterSettingsUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeMasterSettingsErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeMasterSettingsErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.CompanyName == nil &&
+		attrs.Title == nil &&
+		attrs.Subtitle == nil &&
+		attrs.LogoFileUUID == nil &&
+		attrs.CoverFileUUID == nil {
+		return writeMasterSettingsErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeMasterSettingsErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "master settings not found",
+		}})
+	}
+	prevLogoFileID := append([]byte(nil), existing.LogoFileID...)
+	prevCoverFileID := append([]byte(nil), existing.CoverFileID...)
+
+	if attrs.CompanyName != nil {
+		v := strings.TrimSpace(*attrs.CompanyName)
+		if v == "" {
+			return writeMasterSettingsErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "company_name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/company_name"},
+			}})
+		}
+		existing.CompanyName = v
+	}
+	if attrs.Title != nil {
+		existing.Title = strings.TrimSpace(*attrs.Title)
+	}
+	if attrs.Subtitle != nil {
+		existing.Subtitle = strings.TrimSpace(*attrs.Subtitle)
+	}
+	if attrs.LogoFileUUID != nil {
+		if hasBlankOptionalString(attrs.LogoFileUUID) {
+			existing.LogoFileID = nil
+		} else {
+			logoFileID, statusCode, errObj := h.resolveLogoFileID(c.UserContext(), attrs.LogoFileUUID, "/data/attributes/logo_file_uuid")
+			if errObj != nil {
+				return writeMasterSettingsErrors(c, statusCode, []jsonapi.ErrorObject{*errObj})
+			}
+			existing.LogoFileID = logoFileID
+			// Keep manual URL disabled once logo is managed by file manager metadata.
+			existing.LogoURL = nil
+		}
+	}
+	if attrs.CoverFileUUID != nil {
+		if hasBlankOptionalString(attrs.CoverFileUUID) {
+			existing.CoverFileID = nil
+		} else {
+			coverFileID, statusCode, errObj := h.resolveCoverFileID(c.UserContext(), attrs.CoverFileUUID, "/data/attributes/cover_file_uuid")
+			if errObj != nil {
+				return writeMasterSettingsErrors(c, statusCode, []jsonapi.ErrorObject{*errObj})
+			}
+			existing.CoverFileID = coverFileID
+		}
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if err := syncFileLifecycleSwap(c.UserContext(), h.fileSvc, prevLogoFileID, existing.LogoFileID, actorUserID(c)); err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if err := syncFileLifecycleSwap(c.UserContext(), h.fileSvc, prevCoverFileID, existing.CoverFileID, actorUserID(c)); err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, h.masterSettingsResource(c, updated))
+	}
+	return response.Write(c, fiber.StatusOK, h.masterSettingsResource(c, existing))
+}
+
+// DeleteMasterSettings godoc
+// @Summary Delete master settings
+// @Tags Master Settings
+// @Produce json
+// @Param uuid path string true "Master Settings UUID (UUIDv7)"
+// @Success 200 {object} jsonapi.Resource
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Router /api/v1/master-settings/delete/{uuid} [delete]
+func (h *MasterSettingsHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+	existing, _ := h.svc.GetByID(c.UserContext(), id)
+	var prevLogoFileID []byte
+	var prevCoverFileID []byte
+	if existing != nil {
+		prevLogoFileID = append([]byte(nil), existing.LogoFileID...)
+		prevCoverFileID = append([]byte(nil), existing.CoverFileID...)
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeMasterSettingsErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "master settings not found",
+			}})
+		}
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if err := syncFileLifecycleSwap(c.UserContext(), h.fileSvc, prevLogoFileID, nil, actorUserID(c)); err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if err := syncFileLifecycleSwap(c.UserContext(), h.fileSvc, prevCoverFileID, nil, actorUserID(c)); err != nil {
+		return writeMasterSettingsErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "master_settings_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+func (h *MasterSettingsHandler) masterSettingsResource(c *fiber.Ctx, row *mastersettings.MasterSettings) responsedto.MasterSettingsResource {
+	logoFileUUID := uuidStringPtrOrNil(row.LogoFileID)
+	logoURL := h.resolveLogoURL(c, row, logoFileUUID)
+	logoThumbURL := h.resolveLogoThumbnailURL(c, row, logoFileUUID)
+	logoSize := h.resolveLogoOriginalSize(c, row, logoFileUUID)
+	coverFileUUID := uuidStringPtrOrNil(row.CoverFileID)
+	coverURL := h.resolveCoverURL(c, row, coverFileUUID)
+	coverThumbURL := h.resolveCoverThumbnailURL(c, row, coverFileUUID)
+	coverSize := h.resolveCoverOriginalSize(c, row, coverFileUUID)
+
+	return responsedto.MasterSettingsResource{
+		Type: "master_settings",
+		ID:   idString(row.ID),
+		Attributes: responsedto.MasterSettingsAttributes{
+			CompanyName:    row.CompanyName,
+			Title:          row.Title,
+			Subtitle:       row.Subtitle,
+			LogoFileUUID:   logoFileUUID,
+			LogoURL:        logoURL,
+			LogoThumbURL:   logoThumbURL,
+			LogoSizeBytes:  logoSize,
+			CoverFileUUID:  coverFileUUID,
+			CoverURL:       coverURL,
+			CoverThumbURL:  coverThumbURL,
+			CoverSizeBytes: coverSize,
+			CreatedAt:      row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:      uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:      row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:      uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt:      timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:      uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func optionalTrimmedString(v *string) string {
+	if v == nil {
+		return ""
+	}
+	return strings.TrimSpace(*v)
+}
+
+func (h *MasterSettingsHandler) resolveLogoURL(c *fiber.Ctx, row *mastersettings.MasterSettings, logoFileUUID *string) *string {
+	legacyURL := strings.TrimSpace(masterSettingsDerefString(row.LogoURL))
+	if logoFileUUID == nil || strings.TrimSpace(*logoFileUUID) == "" {
+		if legacyURL == "" {
+			return nil
+		}
+		return stringPointer(legacyURL)
+	}
+
+	return h.resolveManagedFileAsset(c, row.LogoFileID, logoFileUUID).OriginalURL
+}
+
+func (h *MasterSettingsHandler) resolveCoverURL(c *fiber.Ctx, row *mastersettings.MasterSettings, coverFileUUID *string) *string {
+	return h.resolveManagedFileAsset(c, row.CoverFileID, coverFileUUID).OriginalURL
+}
+
+func (h *MasterSettingsHandler) resolveManagedFileURL(c *fiber.Ctx, fileID []byte, fileUUID *string) *string {
+	return h.resolveManagedFileAsset(c, fileID, fileUUID).OriginalURL
+}
+
+func (h *MasterSettingsHandler) resolveLogoThumbnailURL(c *fiber.Ctx, row *mastersettings.MasterSettings, logoFileUUID *string) *string {
+	if row == nil {
+		return nil
+	}
+	return h.resolveManagedFileAsset(c, row.LogoFileID, logoFileUUID).ThumbnailURL
+}
+
+func (h *MasterSettingsHandler) resolveCoverThumbnailURL(c *fiber.Ctx, row *mastersettings.MasterSettings, coverFileUUID *string) *string {
+	if row == nil {
+		return nil
+	}
+	return h.resolveManagedFileAsset(c, row.CoverFileID, coverFileUUID).ThumbnailURL
+}
+
+func (h *MasterSettingsHandler) resolveLogoOriginalSize(c *fiber.Ctx, row *mastersettings.MasterSettings, logoFileUUID *string) *int64 {
+	if row == nil {
+		return nil
+	}
+	return h.resolveManagedFileAsset(c, row.LogoFileID, logoFileUUID).OriginalSizeBytes
+}
+
+func (h *MasterSettingsHandler) resolveCoverOriginalSize(c *fiber.Ctx, row *mastersettings.MasterSettings, coverFileUUID *string) *int64 {
+	if row == nil {
+		return nil
+	}
+	return h.resolveManagedFileAsset(c, row.CoverFileID, coverFileUUID).OriginalSizeBytes
+}
+
+func (h *MasterSettingsHandler) resolveManagedFileAsset(c *fiber.Ctx, fileID []byte, fileUUID *string) managedFileAsset {
+	if fileUUID == nil || strings.TrimSpace(*fileUUID) == "" {
+		return managedFileAsset{}
+	}
+
+	if h.fileSvc == nil {
+		return managedFileAsset{}
+	}
+
+	fileRow, err := h.fileSvc.GetFileByID(c.UserContext(), fileID)
+	if err != nil || fileRow == nil {
+		return managedFileAsset{}
+	}
+
+	resolved := resolveFileManagerDownloadURLs(c.UserContext(), h.storage, fileRow)
+	asset := managedFileAsset{
+		OriginalSizeBytes: int64Ptr(resolved.OriginalSizeBytes),
+	}
+	if url := strings.TrimSpace(resolved.OriginalURL); url != "" {
+		asset.OriginalURL = stringPointer(url)
+	}
+	if url := strings.TrimSpace(resolved.ThumbnailURL); url != "" {
+		asset.ThumbnailURL = stringPointer(url)
+	}
+	return asset
+}
+
+func stringPointer(v string) *string {
+	return &v
+}
+
+func masterSettingsDerefString(v *string) string {
+	if v == nil {
+		return ""
+	}
+	return *v
+}
+
+func uuidStringPtrOrNil(id []byte) *string {
+	v := idString(id)
+	if strings.TrimSpace(v) == "" {
+		return nil
+	}
+	return &v
+}
+
+func (h *MasterSettingsHandler) microsoftEntraResource(view *mastersettings.MicrosoftEntraConfigView) responsedto.MasterSettingsMicrosoftEntraResource {
+	if view == nil {
+		return responsedto.MasterSettingsMicrosoftEntraResource{Type: "master_settings_microsoft_entra_sso"}
+	}
+	return responsedto.MasterSettingsMicrosoftEntraResource{
+		Type: "master_settings_microsoft_entra_sso",
+		Attributes: responsedto.MasterSettingsMicrosoftEntraAttributes{
+			TenantID:           view.TenantID,
+			ClientID:           view.ClientID,
+			ClientSecretMasked: view.ClientSecretMasked,
+			RedirectURL:        view.RedirectURL,
+			Authority:          view.Authority,
+			Scopes:             view.Scopes,
+		},
+	}
+}
+
+func isMicrosoftEntraValidationError(err error) bool {
+	if err == nil {
+		return false
+	}
+	msg := err.Error()
+	return strings.Contains(msg, "MS_ENTRA_") ||
+		strings.Contains(msg, "required") ||
+		strings.Contains(msg, "valid absolute URL")
+}
+
+func (h *MasterSettingsHandler) resolveLogoFileID(ctx context.Context, raw *string, pointer string) ([]byte, int, *jsonapi.ErrorObject) {
+	return h.resolveManagedFileID(ctx, raw, pointer, "logo_file_uuid")
+}
+
+func (h *MasterSettingsHandler) resolveCoverFileID(ctx context.Context, raw *string, pointer string) ([]byte, int, *jsonapi.ErrorObject) {
+	return h.resolveManagedFileID(ctx, raw, pointer, "cover_file_uuid")
+}
+
+func (h *MasterSettingsHandler) resolveManagedFileID(ctx context.Context, raw *string, pointer, fieldName string) ([]byte, int, *jsonapi.ErrorObject) {
+	if raw == nil {
+		return nil, 0, nil
+	}
+
+	v := strings.TrimSpace(*raw)
+	if v == "" {
+		return nil, 0, nil
+	}
+
+	id, err := uuidv7.ParseString(v)
+	if err != nil {
+		return nil, fiber.StatusUnprocessableEntity, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: fieldName + " is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+
+	if h.fileSvc == nil {
+		return nil, fiber.StatusServiceUnavailable, &jsonapi.ErrorObject{
+			Status: "503",
+			Title:  "File manager unavailable",
+			Detail: "file manager service is not configured",
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+
+	fileRow, err := h.fileSvc.GetFileByID(ctx, id)
+	if err != nil {
+		return nil, fiber.StatusBadRequest, &jsonapi.ErrorObject{
+			Status: "400",
+			Title:  "Validation error",
+			Detail: safeInternalDetail(),
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	if fileRow == nil {
+		return nil, fiber.StatusUnprocessableEntity, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: fieldName + " is not found",
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	if !strings.EqualFold(strings.TrimSpace(fileRow.Status), filemanager.FileStatusReady) {
+		return nil, fiber.StatusUnprocessableEntity, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: fieldName + " is not ready. finalize upload via /api/v1/file-manager/files/create",
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+
+	return id, 0, nil
+}
+
+func writeMasterSettingsErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferMasterSettingsDef(status, e.Title, e.Detail)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		if strings.TrimSpace(e.Title) == "" {
+			e.Title = def.Title
+		}
+		e.Detail = def.Message
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferMasterSettingsDef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.ErrMasterSettingsNotFound
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid"):
+			return apperrorsx.ErrMasterSettingsInvalidUUID
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.ErrMasterSettingsIDRequired
+		case strings.Contains(lowerDetail, "id does not match"):
+			return apperrorsx.ErrMasterSettingsIDMismatch
+		case strings.Contains(lowerDetail, "at least one attribute"):
+			return apperrorsx.ErrMasterSettingsAttributesRequired
+		case strings.Contains(lowerDetail, "company_name is required"), strings.Contains(lowerDetail, "company_name cannot be empty"):
+			return apperrorsx.ErrMasterSettingsCompanyNameRequired
+		case strings.Contains(lowerDetail, "logo_file_uuid"):
+			return apperrorsx.ErrMasterSettingsLogoFileInvalid
+		case strings.Contains(lowerDetail, "cover_file_uuid"):
+			return apperrorsx.ErrMasterSettingsCoverFileInvalid
+		default:
+			return apperrorsx.ErrMasterSettingsInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrMasterSettingsInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.ErrMasterSettingsCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrMasterSettingsUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrMasterSettingsDeleteFailed
+		case strings.Contains(lowerTitle, "get failed"):
+			return apperrorsx.ErrMasterSettingsGetFailed
+		case strings.Contains(lowerTitle, "upsert failed"):
+			return apperrorsx.ErrMasterSettingsMicrosoftUpsert
+		default:
+			return apperrorsx.ErrMasterSettingsInvalidPayload
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
diff --git a/internal/transport/http/handlers/master_settings_handler_test.go b/internal/transport/http/handlers/master_settings_handler_test.go
new file mode 100644
index 0000000..81ead79
--- /dev/null
+++ b/internal/transport/http/handlers/master_settings_handler_test.go
@@ -0,0 +1,1421 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanager "wucher/internal/domain/file_manager"
+	mastersettings "wucher/internal/domain/master_settings"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type masterSettingsServiceMock struct {
+	createErr error
+	updateErr error
+	deleteErr error
+	getErr    error
+	listErr   error
+
+	lastCreate   *mastersettings.MasterSettings
+	lastUpdate   *mastersettings.MasterSettings
+	lastDeleteID []byte
+	lastDeleteBy []byte
+	lastGetID    []byte
+
+	getByIDCall int
+	getByIDFn   func(id []byte, call int) (*mastersettings.MasterSettings, error)
+	getRow      *mastersettings.MasterSettings
+
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+	listRows       []mastersettings.MasterSettings
+	listTotal      int64
+
+	upsertMicrosoftFn  func(input mastersettings.MicrosoftEntraConfigInput, actor []byte) (*mastersettings.MicrosoftEntraConfigView, error)
+	getMicrosoftFn     func() (*mastersettings.MicrosoftEntraConfigView, error)
+	lastMicrosoftIn    mastersettings.MicrosoftEntraConfigInput
+	lastMicrosoftActor []byte
+}
+
+func (m *masterSettingsServiceMock) Create(_ context.Context, row *mastersettings.MasterSettings) error {
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	m.lastCreate = row
+	return m.createErr
+}
+
+func (m *masterSettingsServiceMock) Update(_ context.Context, row *mastersettings.MasterSettings) error {
+	m.lastUpdate = row
+	return m.updateErr
+}
+
+func (m *masterSettingsServiceMock) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	m.lastDeleteID = append([]byte(nil), id...)
+	m.lastDeleteBy = append([]byte(nil), deletedBy...)
+	return m.deleteErr
+}
+
+func (m *masterSettingsServiceMock) GetByID(_ context.Context, id []byte) (*mastersettings.MasterSettings, error) {
+	m.lastGetID = append([]byte(nil), id...)
+	m.getByIDCall++
+	if m.getByIDFn != nil {
+		return m.getByIDFn(id, m.getByIDCall)
+	}
+	return m.getRow, m.getErr
+}
+
+func (m *masterSettingsServiceMock) List(_ context.Context, filter, sort string, limit, offset int) ([]mastersettings.MasterSettings, int64, error) {
+	m.lastListFilter = filter
+	m.lastListSort = sort
+	m.lastListLimit = limit
+	m.lastListOffset = offset
+	return m.listRows, m.listTotal, m.listErr
+}
+
+func (m *masterSettingsServiceMock) UpsertMicrosoftEntraConfig(_ context.Context, input mastersettings.MicrosoftEntraConfigInput, actor []byte) (*mastersettings.MicrosoftEntraConfigView, error) {
+	m.lastMicrosoftIn = input
+	m.lastMicrosoftActor = append([]byte(nil), actor...)
+	if m.upsertMicrosoftFn != nil {
+		return m.upsertMicrosoftFn(input, actor)
+	}
+	return nil, nil
+}
+
+func (m *masterSettingsServiceMock) GetMicrosoftEntraConfig(_ context.Context) (*mastersettings.MicrosoftEntraConfigView, error) {
+	if m.getMicrosoftFn != nil {
+		return m.getMicrosoftFn()
+	}
+	return nil, nil
+}
+
+type masterSettingsFileRepoMock struct {
+	getByIDErr error
+	getByIDRow *filemanager.File
+	getByIDFn  func(id []byte) (*filemanager.File, error)
+	lastGetID  []byte
+}
+
+func (m *masterSettingsFileRepoMock) Create(context.Context, *filemanager.File) error { return nil }
+func (m *masterSettingsFileRepoMock) Update(context.Context, *filemanager.File) error { return nil }
+func (m *masterSettingsFileRepoMock) TransitionStatus(context.Context, filemanager.FileStatusTransitionParams) error {
+	return nil
+}
+func (m *masterSettingsFileRepoMock) Finalize(context.Context, filemanager.FileFinalizeParams) error {
+	return nil
+}
+func (m *masterSettingsFileRepoMock) Delete(context.Context, []byte, []byte, *time.Time) error {
+	return nil
+}
+func (m *masterSettingsFileRepoMock) Restore(context.Context, []byte, []byte) error { return nil }
+func (m *masterSettingsFileRepoMock) Purge(context.Context, []byte) error           { return nil }
+func (m *masterSettingsFileRepoMock) SearchByName(context.Context, string, string, int, int) ([]filemanager.File, int64, error) {
+	return nil, 0, nil
+}
+func (m *masterSettingsFileRepoMock) GetByID(_ context.Context, id []byte) (*filemanager.File, error) {
+	m.lastGetID = append([]byte(nil), id...)
+	if m.getByIDFn != nil {
+		return m.getByIDFn(id)
+	}
+	return m.getByIDRow, m.getByIDErr
+}
+func (m *masterSettingsFileRepoMock) GetByIDAny(context.Context, []byte) (*filemanager.File, error) {
+	return nil, nil
+}
+func (m *masterSettingsFileRepoMock) GetByObjectKey(context.Context, string) (*filemanager.File, error) {
+	return nil, nil
+}
+func (m *masterSettingsFileRepoMock) GetByFolderAndName(context.Context, []byte, string) (*filemanager.File, error) {
+	return nil, nil
+}
+func (m *masterSettingsFileRepoMock) GetByTemplateAndTakeover(context.Context, []byte, []byte) (*filemanager.File, error) {
+	return nil, nil
+}
+func (m *masterSettingsFileRepoMock) ListByFolder(context.Context, []byte, string, int, int) ([]filemanager.File, int64, error) {
+	return nil, 0, nil
+}
+func (m *masterSettingsFileRepoMock) ListTrashByFolder(context.Context, []byte, string, int, int) ([]filemanager.File, int64, error) {
+	return nil, 0, nil
+}
+
+type masterSettingsStorageMock struct {
+	presignURL string
+	presignErr error
+	lastKey    string
+}
+
+type masterSettingsLifecycleServiceMock struct {
+	filemanager.Service
+	markErr      error
+	reconcileErr error
+}
+
+func (m *masterSettingsLifecycleServiceMock) MarkFileActive(context.Context, []byte, []byte) error {
+	return m.markErr
+}
+func (m *masterSettingsLifecycleServiceMock) ReconcileFileLifecycle(context.Context, []byte, []byte) error {
+	return m.reconcileErr
+}
+func (m *masterSettingsLifecycleServiceMock) CleanupOrphanPendingFiles(context.Context, time.Time, time.Duration, int, bool) (filemanager.FileCleanupStats, error) {
+	return filemanager.FileCleanupStats{}, nil
+}
+
+func (m *masterSettingsStorageMock) EnsureBucket(context.Context) error { return nil }
+func (m *masterSettingsStorageMock) PutObject(context.Context, filemanager.PutObjectInput) (filemanager.ObjectMetadata, error) {
+	return filemanager.ObjectMetadata{}, nil
+}
+func (m *masterSettingsStorageMock) DeleteObject(context.Context, string) error { return nil }
+func (m *masterSettingsStorageMock) HeadObject(context.Context, string) (filemanager.ObjectMetadata, error) {
+	return filemanager.ObjectMetadata{}, nil
+}
+func (m *masterSettingsStorageMock) PresignPutObject(context.Context, filemanager.PresignPutObjectInput) (filemanager.PresignedPutObject, error) {
+	return filemanager.PresignedPutObject{}, nil
+}
+func (m *masterSettingsStorageMock) PresignGetObject(_ context.Context, objectKey string, _ time.Duration) (string, error) {
+	m.lastKey = objectKey
+	return m.presignURL, m.presignErr
+}
+
+func newMasterSettingsFileService(fileRepo *masterSettingsFileRepoMock) filemanager.Service {
+	return service.NewFileManagerService(nil, fileRepo, nil, service.FileManagerServiceDependencies{})
+}
+
+func newMasterSettingsTestApp(h *MasterSettingsHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", actor)
+		}
+		return c.Next()
+	})
+	app.Post("/api/v1/master-settings/create", h.Create)
+	app.Get("/api/v1/master-settings/get", h.Get)
+	app.Get("/api/v1/master-settings/sso/microsoft", h.GetMicrosoftEntraSSO)
+	app.Put("/api/v1/master-settings/sso/microsoft", h.UpsertMicrosoftEntraSSO)
+	app.Patch("/api/v1/master-settings/update/:uuid", h.Update)
+	app.Delete("/api/v1/master-settings/delete/:uuid", h.Delete)
+	return app
+}
+
+func doJSONRequestMasterSettings(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDStringMasterSettings(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func strPtrMasterSettings(v string) *string { return &v }
+
+func TestNewMasterSettingsHandler(t *testing.T) {
+	h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, nil, nil)
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+func TestMasterSettingsHandlerCreate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPost, "/api/v1/master-settings/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPost, "/api/v1/master-settings/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("company name empty after trim", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"master_settings_create","attributes":{"company_name":"   "}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPost, "/api/v1/master-settings/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("logo file uuid invalid", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"master_settings_create","attributes":{"company_name":"Wucher","logo_file_uuid":"not-uuid"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPost, "/api/v1/master-settings/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("cover file uuid invalid", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"master_settings_create","attributes":{"company_name":"Wucher","cover_file_uuid":"not-uuid"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPost, "/api/v1/master-settings/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("file manager unavailable", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		id := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+
+		body := []byte(`{"data":{"type":"master_settings_create","attributes":{"company_name":"Wucher","logo_file_uuid":"` + id + `"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPost, "/api/v1/master-settings/create", body)
+		if resp.StatusCode != http.StatusServiceUnavailable {
+			t.Fatalf("expected 503, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("file lookup error", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		fileRepo := &masterSettingsFileRepoMock{getByIDErr: errors.New("lookup failed")}
+		h := NewMasterSettingsHandler(svc, newMasterSettingsFileService(fileRepo), nil)
+		app := newMasterSettingsTestApp(h, nil)
+		id := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+
+		body := []byte(`{"data":{"type":"master_settings_create","attributes":{"company_name":"Wucher","logo_file_uuid":"` + id + `"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPost, "/api/v1/master-settings/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("file not found", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		fileRepo := &masterSettingsFileRepoMock{getByIDRow: nil}
+		h := NewMasterSettingsHandler(svc, newMasterSettingsFileService(fileRepo), nil)
+		app := newMasterSettingsTestApp(h, nil)
+		id := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+
+		body := []byte(`{"data":{"type":"master_settings_create","attributes":{"company_name":"Wucher","logo_file_uuid":"` + id + `"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPost, "/api/v1/master-settings/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("file not ready", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		fileRepo := &masterSettingsFileRepoMock{
+			getByIDRow: &filemanager.File{
+				ID:     uuidv7.MustBytes(),
+				Status: filemanager.FileStatusUploaded,
+			},
+		}
+		h := NewMasterSettingsHandler(svc, newMasterSettingsFileService(fileRepo), nil)
+		app := newMasterSettingsTestApp(h, nil)
+		id := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+
+		body := []byte(`{"data":{"type":"master_settings_create","attributes":{"company_name":"Wucher","logo_file_uuid":"` + id + `"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPost, "/api/v1/master-settings/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{createErr: errors.New("create failed")}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"master_settings_create","attributes":{"company_name":"Wucher"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPost, "/api/v1/master-settings/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		actor := uuidv7.MustBytes()
+		logoID := uuidv7.MustBytes()
+		coverID := uuidv7.MustBytes()
+		fileRepo := &masterSettingsFileRepoMock{
+			getByIDFn: func(id []byte) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:        id,
+					Status:    filemanager.FileStatusReady,
+					ObjectKey: "obj-" + mustUUIDStringMasterSettings(t, id),
+				}, nil
+			},
+		}
+		svc := &masterSettingsServiceMock{
+			getByIDFn: func(id []byte, _ int) (*mastersettings.MasterSettings, error) {
+				return &mastersettings.MasterSettings{
+					ID:          id,
+					CompanyName: "Wucher",
+					Title:       "Welcome",
+					Subtitle:    "Ops",
+					LogoFileID:  logoID,
+					CoverFileID: coverID,
+					CreatedAt:   time.Now().UTC(),
+					UpdatedAt:   time.Now().UTC(),
+				}, nil
+			},
+		}
+		h := NewMasterSettingsHandler(svc, newMasterSettingsFileService(fileRepo), nil)
+		app := newMasterSettingsTestApp(h, actor)
+		logoIDStr := mustUUIDStringMasterSettings(t, logoID)
+		coverIDStr := mustUUIDStringMasterSettings(t, coverID)
+		body := []byte(`{"data":{"type":"master_settings_create","attributes":{"company_name":" Wucher ","title":" Welcome ","subtitle":" Ops ","logo_file_uuid":"` + logoIDStr + `","cover_file_uuid":"` + coverIDStr + `"}}}`)
+
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPost, "/api/v1/master-settings/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if svc.lastCreate == nil {
+			t.Fatalf("expected row created")
+		}
+		if svc.lastCreate.CompanyName != "Wucher" || svc.lastCreate.Title != "Welcome" || svc.lastCreate.Subtitle != "Ops" {
+			t.Fatalf("expected trimmed values saved")
+		}
+		if string(svc.lastCreate.CreatedBy) != string(actor) || string(svc.lastCreate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected created_by and updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{
+			getByIDFn: func(_ []byte, _ int) (*mastersettings.MasterSettings, error) {
+				return nil, errors.New("lookup failed")
+			},
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"master_settings_create","attributes":{"company_name":"Wucher"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPost, "/api/v1/master-settings/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestMasterSettingsHandlerGet(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{listErr: errors.New("list failed")}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodGet, "/api/v1/master-settings/get", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{listRows: nil, listTotal: 0}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		resp, body := doJSONRequestMasterSettings(t, app, http.MethodGet, "/api/v1/master-settings/get", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if !bytes.Contains(body, []byte(`"company_name":""`)) {
+			t.Fatalf("expected empty company_name in response, body=%s", string(body))
+		}
+	})
+
+	t.Run("success with nil logo and cover url when file resolver unavailable", func(t *testing.T) {
+		logoID := uuidv7.MustBytes()
+		coverID := uuidv7.MustBytes()
+		row := mastersettings.MasterSettings{
+			ID:          uuidv7.MustBytes(),
+			CompanyName: "Wucher",
+			Title:       "Welcome",
+			Subtitle:    "Ops",
+			LogoFileID:  logoID,
+			CoverFileID: coverID,
+			CreatedAt:   time.Now().UTC(),
+			UpdatedAt:   time.Now().UTC(),
+		}
+		svc := &masterSettingsServiceMock{listRows: []mastersettings.MasterSettings{row}, listTotal: 1}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		resp, body := doJSONRequestMasterSettings(t, app, http.MethodGet, "/api/v1/master-settings/get", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if bytes.Contains(body, []byte(`"logo_url":"`)) {
+			t.Fatalf("expected logo_url omitted when resolver unavailable, body=%s", string(body))
+		}
+		if bytes.Contains(body, []byte(`"cover_url":"`)) {
+			t.Fatalf("expected cover_url omitted when resolver unavailable, body=%s", string(body))
+		}
+		if svc.lastListSort != "-updated_at" || svc.lastListLimit != 1 || svc.lastListOffset != 0 {
+			t.Fatalf("expected list called with singleton params")
+		}
+	})
+}
+
+func TestMasterSettingsHandlerUpdate(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		id := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		id := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		id := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+
+		body := []byte(`{"data":{"type":"master_settings_update","attributes":{"title":"Welcome"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		pathID := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+		otherID := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+
+		body := []byte(`{"data":{"type":"master_settings_update","id":"` + otherID + `","attributes":{"title":"Welcome"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+pathID, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no attributes provided", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		id := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+
+		body := []byte(`{"data":{"type":"master_settings_update","id":"` + id + `","attributes":{}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found when get fails", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{getErr: errors.New("db error")}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		id := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+
+		body := []byte(`{"data":{"type":"master_settings_update","id":"` + id + `","attributes":{"title":"Welcome"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, body)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found when get nil", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{getRow: nil}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		id := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+
+		body := []byte(`{"data":{"type":"master_settings_update","id":"` + id + `","attributes":{"title":"Welcome"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, body)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("company name empty", func(t *testing.T) {
+		idBytes := uuidv7.MustBytes()
+		id := mustUUIDStringMasterSettings(t, idBytes)
+		svc := &masterSettingsServiceMock{
+			getRow: &mastersettings.MasterSettings{ID: idBytes, CompanyName: "Wucher"},
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"master_settings_update","id":"` + id + `","attributes":{"company_name":"   "}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("logo file uuid invalid", func(t *testing.T) {
+		idBytes := uuidv7.MustBytes()
+		id := mustUUIDStringMasterSettings(t, idBytes)
+		svc := &masterSettingsServiceMock{
+			getRow: &mastersettings.MasterSettings{ID: idBytes, CompanyName: "Wucher"},
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"master_settings_update","id":"` + id + `","attributes":{"logo_file_uuid":"bad"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("cover file uuid invalid", func(t *testing.T) {
+		idBytes := uuidv7.MustBytes()
+		id := mustUUIDStringMasterSettings(t, idBytes)
+		svc := &masterSettingsServiceMock{
+			getRow: &mastersettings.MasterSettings{ID: idBytes, CompanyName: "Wucher"},
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"master_settings_update","id":"` + id + `","attributes":{"cover_file_uuid":"bad"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		idBytes := uuidv7.MustBytes()
+		id := mustUUIDStringMasterSettings(t, idBytes)
+		svc := &masterSettingsServiceMock{
+			getRow:    &mastersettings.MasterSettings{ID: idBytes, CompanyName: "Wucher"},
+			updateErr: errors.New("update failed"),
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"master_settings_update","id":"` + id + `","attributes":{"title":"Welcome"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success update with cover file uuid", func(t *testing.T) {
+		idBytes := uuidv7.MustBytes()
+		id := mustUUIDStringMasterSettings(t, idBytes)
+		coverID := uuidv7.MustBytes()
+		coverIDStr := mustUUIDStringMasterSettings(t, coverID)
+		fileRepo := &masterSettingsFileRepoMock{
+			getByIDFn: func(fid []byte) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:        fid,
+					Status:    filemanager.FileStatusReady,
+					ObjectKey: "cover.png",
+				}, nil
+			},
+		}
+		svc := &masterSettingsServiceMock{
+			getByIDFn: func(gotID []byte, call int) (*mastersettings.MasterSettings, error) {
+				if call == 1 {
+					return &mastersettings.MasterSettings{ID: gotID, CompanyName: "Wucher"}, nil
+				}
+				return &mastersettings.MasterSettings{
+					ID:          gotID,
+					CompanyName: "Wucher",
+					CoverFileID: coverID,
+					CreatedAt:   time.Now().UTC(),
+					UpdatedAt:   time.Now().UTC(),
+				}, nil
+			},
+		}
+		h := NewMasterSettingsHandler(svc, newMasterSettingsFileService(fileRepo), nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"master_settings_update","id":"` + id + `","attributes":{"cover_file_uuid":"` + coverIDStr + `"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.lastUpdate == nil || string(svc.lastUpdate.CoverFileID) != string(coverID) {
+			t.Fatalf("expected cover_file_id updated")
+		}
+	})
+
+	t.Run("empty logo_file_uuid clears existing file", func(t *testing.T) {
+		idBytes := uuidv7.MustBytes()
+		id := mustUUIDStringMasterSettings(t, idBytes)
+		logoID := uuidv7.MustBytes()
+		svc := &masterSettingsServiceMock{
+			getByIDFn: func(gotID []byte, call int) (*mastersettings.MasterSettings, error) {
+				if call == 1 {
+					return &mastersettings.MasterSettings{
+						ID:          gotID,
+						CompanyName: "Wucher",
+						LogoFileID:  append([]byte(nil), logoID...),
+					}, nil
+				}
+				return &mastersettings.MasterSettings{
+					ID:          gotID,
+					CompanyName: "Wucher",
+					LogoFileID:  append([]byte(nil), logoID...),
+					UpdatedAt:   time.Now().UTC(),
+				}, nil
+			},
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"master_settings_update","id":"` + id + `","attributes":{"company_name":"Wucher","logo_file_uuid":""}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.lastUpdate == nil || svc.lastUpdate.LogoFileID != nil {
+			t.Fatalf("expected logo_file_id to be cleared")
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		idBytes := uuidv7.MustBytes()
+		id := mustUUIDStringMasterSettings(t, idBytes)
+		logoID := uuidv7.MustBytes()
+		logoIDStr := mustUUIDStringMasterSettings(t, logoID)
+		actor := uuidv7.MustBytes()
+		fileRepo := &masterSettingsFileRepoMock{
+			getByIDFn: func(fid []byte) (*filemanager.File, error) {
+				return &filemanager.File{
+					ID:        fid,
+					Status:    filemanager.FileStatusReady,
+					ObjectKey: "obj",
+				}, nil
+			},
+		}
+		svc := &masterSettingsServiceMock{
+			getByIDFn: func(gotID []byte, call int) (*mastersettings.MasterSettings, error) {
+				if call == 1 {
+					legacy := "https://legacy/logo.png"
+					return &mastersettings.MasterSettings{
+						ID:          gotID,
+						CompanyName: "Old",
+						Title:       "Old",
+						Subtitle:    "Old",
+						LogoURL:     &legacy,
+					}, nil
+				}
+				return &mastersettings.MasterSettings{
+					ID:          gotID,
+					CompanyName: "Wucher",
+					Title:       "Welcome",
+					Subtitle:    "Ops",
+					LogoFileID:  logoID,
+					CreatedAt:   time.Now().UTC(),
+					UpdatedAt:   time.Now().UTC(),
+				}, nil
+			},
+		}
+		h := NewMasterSettingsHandler(svc, newMasterSettingsFileService(fileRepo), nil)
+		app := newMasterSettingsTestApp(h, actor)
+
+		body := []byte(`{"data":{"type":"master_settings_update","id":"` + id + `","attributes":{"company_name":" Wucher ","title":" Welcome ","subtitle":" Ops ","logo_file_uuid":"` + logoIDStr + `"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.lastUpdate == nil {
+			t.Fatalf("expected update called")
+		}
+		if svc.lastUpdate.CompanyName != "Wucher" || svc.lastUpdate.Title != "Welcome" || svc.lastUpdate.Subtitle != "Ops" {
+			t.Fatalf("expected trimmed update values")
+		}
+		if svc.lastUpdate.LogoURL != nil {
+			t.Fatalf("expected legacy logo_url cleared when logo_file_uuid provided")
+		}
+		if string(svc.lastUpdate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		idBytes := uuidv7.MustBytes()
+		id := mustUUIDStringMasterSettings(t, idBytes)
+		svc := &masterSettingsServiceMock{
+			getByIDFn: func(gotID []byte, call int) (*mastersettings.MasterSettings, error) {
+				if call == 1 {
+					return &mastersettings.MasterSettings{ID: gotID, CompanyName: "Wucher"}, nil
+				}
+				return nil, errors.New("lookup failed")
+			},
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"master_settings_update","id":"` + id + `","attributes":{"title":"Welcome"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPatch, "/api/v1/master-settings/update/"+id, body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestMasterSettingsHandlerDelete(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodDelete, "/api/v1/master-settings/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete error", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{deleteErr: errors.New("delete failed")}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		id := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodDelete, "/api/v1/master-settings/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		actor := uuidv7.MustBytes()
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, actor)
+		idBytes := uuidv7.MustBytes()
+		id := mustUUIDStringMasterSettings(t, idBytes)
+
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodDelete, "/api/v1/master-settings/delete/"+id, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(svc.lastDeleteID) != string(idBytes) {
+			t.Fatalf("expected delete called with id")
+		}
+		if string(svc.lastDeleteBy) != string(actor) {
+			t.Fatalf("expected delete called with actor")
+		}
+	})
+
+	t.Run("fails when sync previous logo lifecycle fails", func(t *testing.T) {
+		idBytes := uuidv7.MustBytes()
+		id := mustUUIDStringMasterSettings(t, idBytes)
+		svc := &masterSettingsServiceMock{
+			getRow: &mastersettings.MasterSettings{
+				ID:         idBytes,
+				LogoFileID: uuidv7.MustBytes(),
+			},
+		}
+		fileSvc := &masterSettingsLifecycleServiceMock{reconcileErr: errors.New("reconcile failed")}
+		h := NewMasterSettingsHandler(svc, fileSvc, nil)
+		app := newMasterSettingsTestApp(h, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodDelete, "/api/v1/master-settings/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("fails when sync previous cover lifecycle fails", func(t *testing.T) {
+		idBytes := uuidv7.MustBytes()
+		id := mustUUIDStringMasterSettings(t, idBytes)
+		svc := &masterSettingsServiceMock{
+			getRow: &mastersettings.MasterSettings{
+				ID:          idBytes,
+				CoverFileID: uuidv7.MustBytes(),
+			},
+		}
+		fileSvc := &masterSettingsLifecycleServiceMock{reconcileErr: errors.New("reconcile failed")}
+		h := NewMasterSettingsHandler(svc, fileSvc, nil)
+		app := newMasterSettingsTestApp(h, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodDelete, "/api/v1/master-settings/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestMasterSettingsHandlerHelperFunctions(t *testing.T) {
+	if got := optionalTrimmedString(nil); got != "" {
+		t.Fatalf("expected empty string for nil, got %q", got)
+	}
+	if got := optionalTrimmedString(strPtrMasterSettings("  hi  ")); got != "hi" {
+		t.Fatalf("expected trimmed string, got %q", got)
+	}
+	if got := masterSettingsDerefString(nil); got != "" {
+		t.Fatalf("expected empty string for nil ptr")
+	}
+	if got := masterSettingsDerefString(strPtrMasterSettings("abc")); got != "abc" {
+		t.Fatalf("unexpected deref value: %q", got)
+	}
+	if got := stringPointer("x"); got == nil || *got != "x" {
+		t.Fatalf("expected pointer value")
+	}
+	if got := uuidStringPtrOrNil(nil); got != nil {
+		t.Fatalf("expected nil for empty uuid bytes")
+	}
+	id := uuidv7.MustBytes()
+	if got := uuidStringPtrOrNil(id); got == nil || strings.TrimSpace(*got) == "" {
+		t.Fatalf("expected non-empty uuid string pointer")
+	}
+}
+
+func TestMasterSettingsHandlerResolveManagedFileID(t *testing.T) {
+	t.Run("raw nil", func(t *testing.T) {
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, nil, nil)
+		id, status, errObj := h.resolveManagedFileID(context.Background(), nil, "/x", "logo_file_uuid")
+		if len(id) != 0 || status != 0 || errObj != nil {
+			t.Fatalf("expected nil id without error")
+		}
+	})
+
+	t.Run("raw empty", func(t *testing.T) {
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, nil, nil)
+		raw := "   "
+		id, status, errObj := h.resolveManagedFileID(context.Background(), &raw, "/x", "logo_file_uuid")
+		if len(id) != 0 || status != 0 || errObj != nil {
+			t.Fatalf("expected nil id without error")
+		}
+	})
+
+	t.Run("invalid uuid", func(t *testing.T) {
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, nil, nil)
+		raw := "bad"
+		_, status, errObj := h.resolveManagedFileID(context.Background(), &raw, "/x", "logo_file_uuid")
+		if status != http.StatusUnprocessableEntity || errObj == nil {
+			t.Fatalf("expected 422 validation error")
+		}
+	})
+
+	t.Run("file service unavailable", func(t *testing.T) {
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, nil, nil)
+		raw := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+		_, status, errObj := h.resolveManagedFileID(context.Background(), &raw, "/x", "logo_file_uuid")
+		if status != http.StatusServiceUnavailable || errObj == nil {
+			t.Fatalf("expected 503 when file service is nil")
+		}
+	})
+
+	t.Run("lookup error", func(t *testing.T) {
+		repo := &masterSettingsFileRepoMock{getByIDErr: errors.New("lookup failed")}
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, newMasterSettingsFileService(repo), nil)
+		raw := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+		_, status, errObj := h.resolveManagedFileID(context.Background(), &raw, "/x", "logo_file_uuid")
+		if status != http.StatusBadRequest || errObj == nil {
+			t.Fatalf("expected 400 lookup error")
+		}
+	})
+
+	t.Run("file not found", func(t *testing.T) {
+		repo := &masterSettingsFileRepoMock{getByIDRow: nil}
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, newMasterSettingsFileService(repo), nil)
+		raw := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+		_, status, errObj := h.resolveManagedFileID(context.Background(), &raw, "/x", "logo_file_uuid")
+		if status != http.StatusUnprocessableEntity || errObj == nil {
+			t.Fatalf("expected 422 not found")
+		}
+	})
+
+	t.Run("file not ready", func(t *testing.T) {
+		repo := &masterSettingsFileRepoMock{
+			getByIDRow: &filemanager.File{
+				ID:     uuidv7.MustBytes(),
+				Status: filemanager.FileStatusUploaded,
+			},
+		}
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, newMasterSettingsFileService(repo), nil)
+		raw := mustUUIDStringMasterSettings(t, uuidv7.MustBytes())
+		_, status, errObj := h.resolveManagedFileID(context.Background(), &raw, "/x", "logo_file_uuid")
+		if status != http.StatusUnprocessableEntity || errObj == nil {
+			t.Fatalf("expected 422 not ready")
+		}
+	})
+
+	t.Run("success ready file", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		repo := &masterSettingsFileRepoMock{
+			getByIDFn: func(gotID []byte) (*filemanager.File, error) {
+				return &filemanager.File{ID: gotID, Status: filemanager.FileStatusReady}, nil
+			},
+		}
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, newMasterSettingsFileService(repo), nil)
+		raw := mustUUIDStringMasterSettings(t, id)
+		got, status, errObj := h.resolveManagedFileID(context.Background(), &raw, "/x", "logo_file_uuid")
+		if status != 0 || errObj != nil {
+			t.Fatalf("expected success, got status=%d err=%v", status, errObj)
+		}
+		if string(got) != string(id) {
+			t.Fatalf("expected parsed id returned")
+		}
+	})
+
+	t.Run("resolve wrappers use field names", func(t *testing.T) {
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, nil, nil)
+		raw := "bad"
+
+		_, _, logoErr := h.resolveLogoFileID(context.Background(), &raw, "/logo")
+		if logoErr == nil || !strings.Contains(logoErr.Detail, "logo_file_uuid") {
+			t.Fatalf("expected logo wrapper detail contains logo_file_uuid")
+		}
+		_, _, coverErr := h.resolveCoverFileID(context.Background(), &raw, "/cover")
+		if coverErr == nil || !strings.Contains(coverErr.Detail, "cover_file_uuid") {
+			t.Fatalf("expected cover wrapper detail contains cover_file_uuid")
+		}
+	})
+}
+
+func TestMasterSettingsHandlerResolveManagedFileURL(t *testing.T) {
+	withFiberCtx := func(t *testing.T, fn func(*fiber.Ctx)) {
+		t.Helper()
+		app := fiber.New()
+		app.Get("/", func(c *fiber.Ctx) error {
+			fn(c)
+			return c.SendStatus(fiber.StatusOK)
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/", nil)
+		if _, err := app.Test(req); err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+	}
+
+	t.Run("nil file uuid returns nil", func(t *testing.T) {
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, nil, nil)
+		withFiberCtx(t, func(c *fiber.Ctx) {
+			if got := h.resolveManagedFileURL(c, nil, nil); got != nil {
+				t.Fatalf("expected nil url")
+			}
+		})
+	})
+
+	t.Run("nil when file service and storage unavailable", func(t *testing.T) {
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, nil, nil)
+		fileUUID := "abc"
+		withFiberCtx(t, func(c *fiber.Ctx) {
+			got := h.resolveManagedFileURL(c, nil, &fileUUID)
+			if got != nil {
+				t.Fatalf("expected nil, got %v", got)
+			}
+		})
+	})
+
+	t.Run("presign success", func(t *testing.T) {
+		fileID := uuidv7.MustBytes()
+		fileUUID := mustUUIDStringMasterSettings(t, fileID)
+		fileRepo := &masterSettingsFileRepoMock{
+			getByIDRow: &filemanager.File{
+				ID:        fileID,
+				Status:    filemanager.FileStatusReady,
+				ObjectKey: "logos/logo.png",
+			},
+		}
+		storage := &masterSettingsStorageMock{presignURL: "https://signed.example/logo.png"}
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, newMasterSettingsFileService(fileRepo), storage)
+
+		withFiberCtx(t, func(c *fiber.Ctx) {
+			got := h.resolveManagedFileURL(c, fileID, &fileUUID)
+			if got == nil || *got != "https://signed.example/logo.png" {
+				t.Fatalf("expected presigned url")
+			}
+			if storage.lastKey != "logos/logo.png" {
+				t.Fatalf("expected object key passed to presign")
+			}
+		})
+	})
+
+	t.Run("nil when file lookup error", func(t *testing.T) {
+		fileID := uuidv7.MustBytes()
+		fileUUID := mustUUIDStringMasterSettings(t, fileID)
+		fileRepo := &masterSettingsFileRepoMock{getByIDErr: errors.New("lookup failed")}
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, newMasterSettingsFileService(fileRepo), &masterSettingsStorageMock{})
+
+		withFiberCtx(t, func(c *fiber.Ctx) {
+			got := h.resolveManagedFileURL(c, fileID, &fileUUID)
+			if got != nil {
+				t.Fatalf("expected nil on lookup error")
+			}
+		})
+	})
+
+	t.Run("nil when file row missing object key", func(t *testing.T) {
+		fileID := uuidv7.MustBytes()
+		fileUUID := mustUUIDStringMasterSettings(t, fileID)
+		fileRepo := &masterSettingsFileRepoMock{
+			getByIDRow: &filemanager.File{
+				ID:        fileID,
+				Status:    filemanager.FileStatusReady,
+				ObjectKey: "   ",
+			},
+		}
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, newMasterSettingsFileService(fileRepo), &masterSettingsStorageMock{})
+
+		withFiberCtx(t, func(c *fiber.Ctx) {
+			got := h.resolveManagedFileURL(c, fileID, &fileUUID)
+			if got != nil {
+				t.Fatalf("expected nil when object key empty")
+			}
+		})
+	})
+
+	t.Run("nil when presign error", func(t *testing.T) {
+		fileID := uuidv7.MustBytes()
+		fileUUID := mustUUIDStringMasterSettings(t, fileID)
+		fileRepo := &masterSettingsFileRepoMock{
+			getByIDRow: &filemanager.File{
+				ID:        fileID,
+				Status:    filemanager.FileStatusReady,
+				ObjectKey: "logos/logo.png",
+			},
+		}
+		storage := &masterSettingsStorageMock{presignErr: errors.New("presign failed")}
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, newMasterSettingsFileService(fileRepo), storage)
+
+		withFiberCtx(t, func(c *fiber.Ctx) {
+			got := h.resolveManagedFileURL(c, fileID, &fileUUID)
+			if got != nil {
+				t.Fatalf("expected nil on presign error")
+			}
+		})
+	})
+
+	t.Run("resolve logo url legacy and managed branches", func(t *testing.T) {
+		legacy := "https://legacy.example/logo.png"
+		row := &mastersettings.MasterSettings{LogoURL: &legacy}
+		hLegacy := NewMasterSettingsHandler(&masterSettingsServiceMock{}, nil, nil)
+		withFiberCtx(t, func(c *fiber.Ctx) {
+			got := hLegacy.resolveLogoURL(c, row, nil)
+			if got == nil || *got != legacy {
+				t.Fatalf("expected legacy logo url")
+			}
+		})
+
+		fileID := uuidv7.MustBytes()
+		fileUUID := mustUUIDStringMasterSettings(t, fileID)
+		fileRepo := &masterSettingsFileRepoMock{
+			getByIDRow: &filemanager.File{
+				ID:        fileID,
+				Status:    filemanager.FileStatusReady,
+				ObjectKey: "logos/logo.png",
+			},
+		}
+		hManaged := NewMasterSettingsHandler(&masterSettingsServiceMock{}, newMasterSettingsFileService(fileRepo), &masterSettingsStorageMock{presignURL: "https://signed/logo.png"})
+		managedRow := &mastersettings.MasterSettings{
+			LogoFileID:  fileID,
+			CoverFileID: fileID,
+		}
+		withFiberCtx(t, func(c *fiber.Ctx) {
+			logo := hManaged.resolveLogoURL(c, managedRow, &fileUUID)
+			cover := hManaged.resolveCoverURL(c, managedRow, &fileUUID)
+			if logo == nil || *logo != "https://signed/logo.png" {
+				t.Fatalf("expected managed logo url")
+			}
+			if cover == nil || *cover != "https://signed/logo.png" {
+				t.Fatalf("expected managed cover url")
+			}
+		})
+	})
+}
+
+func TestMasterSettingsHandlerMicrosoftEntra(t *testing.T) {
+	t.Run("upsert success", func(t *testing.T) {
+		actor := []byte("abcdefghijklmnop")
+		svc := &masterSettingsServiceMock{
+			upsertMicrosoftFn: func(_ mastersettings.MicrosoftEntraConfigInput, _ []byte) (*mastersettings.MicrosoftEntraConfigView, error) {
+				return &mastersettings.MicrosoftEntraConfigView{
+					TenantID:           "tenant",
+					ClientID:           "client",
+					ClientSecretMasked: "********",
+					RedirectURL:        "https://example.com/callback",
+					Authority:          "https://login.microsoftonline.com/",
+					Scopes:             "openid,profile,email",
+				}, nil
+			},
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, actor)
+		body := []byte(`{"data":{"type":"master_settings_microsoft_entra_upsert","attributes":{"MS_ENTRA_TENANT_ID":"tenant","MS_ENTRA_CLIENT_ID":"client","MS_ENTRA_CLIENT_SECRET":"top-secret","MS_ENTRA_REDIRECT_URL":"https://example.com/callback","MS_ENTRA_AUTHORITY":"https://login.microsoftonline.com/","MS_ENTRA_SCOPES":"openid,profile,email"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPut, "/api/v1/master-settings/sso/microsoft", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.lastMicrosoftIn.ClientSecret != "top-secret" {
+			t.Fatalf("expected secret forwarded")
+		}
+		if string(svc.lastMicrosoftActor) != string(actor) {
+			t.Fatalf("expected actor forwarded")
+		}
+	})
+
+	t.Run("upsert success with empty secret", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{
+			upsertMicrosoftFn: func(_ mastersettings.MicrosoftEntraConfigInput, _ []byte) (*mastersettings.MicrosoftEntraConfigView, error) {
+				return &mastersettings.MicrosoftEntraConfigView{
+					TenantID:           "tenant",
+					ClientID:           "client",
+					ClientSecretMasked: "********",
+					RedirectURL:        "https://example.com/callback",
+					Authority:          "https://login.microsoftonline.com/",
+					Scopes:             "openid,profile,email",
+				}, nil
+			},
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		body := []byte(`{"data":{"type":"master_settings_microsoft_entra_upsert","attributes":{"MS_ENTRA_TENANT_ID":"tenant","MS_ENTRA_CLIENT_ID":"client","MS_ENTRA_CLIENT_SECRET":"","MS_ENTRA_REDIRECT_URL":"https://example.com/callback","MS_ENTRA_AUTHORITY":"https://login.microsoftonline.com/","MS_ENTRA_SCOPES":"openid,profile,email"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPut, "/api/v1/master-settings/sso/microsoft", body)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if svc.lastMicrosoftIn.ClientSecret != "" {
+			t.Fatalf("expected empty secret forwarded")
+		}
+	})
+
+	t.Run("upsert validation error", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		body := []byte(`{"data":{"type":"master_settings_microsoft_entra_upsert","attributes":{"MS_ENTRA_TENANT_ID":"","MS_ENTRA_CLIENT_ID":"client","MS_ENTRA_CLIENT_SECRET":"secret","MS_ENTRA_REDIRECT_URL":"https://example.com/callback","MS_ENTRA_AUTHORITY":"https://login.microsoftonline.com/","MS_ENTRA_SCOPES":"openid"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPut, "/api/v1/master-settings/sso/microsoft", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("get success", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{
+			getMicrosoftFn: func() (*mastersettings.MicrosoftEntraConfigView, error) {
+				return &mastersettings.MicrosoftEntraConfigView{
+					TenantID:           "tenant",
+					ClientID:           "client",
+					ClientSecretMasked: "********",
+					RedirectURL:        "https://example.com/callback",
+					Authority:          "https://login.microsoftonline.com/",
+					Scopes:             "openid,profile,email",
+				}, nil
+			},
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodGet, "/api/v1/master-settings/sso/microsoft", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("get not found", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{
+			getMicrosoftFn: func() (*mastersettings.MicrosoftEntraConfigView, error) {
+				return nil, nil
+			},
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodGet, "/api/v1/master-settings/sso/microsoft", nil)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("upsert invalid json", func(t *testing.T) {
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPut, "/api/v1/master-settings/sso/microsoft", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("upsert service validation error is treated as 422", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{
+			upsertMicrosoftFn: func(_ mastersettings.MicrosoftEntraConfigInput, _ []byte) (*mastersettings.MicrosoftEntraConfigView, error) {
+				return nil, errors.New("MS_ENTRA_REDIRECT_URL must be valid absolute URL")
+			},
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		body := []byte(`{"data":{"type":"master_settings_microsoft_entra_upsert","attributes":{"MS_ENTRA_TENANT_ID":"tenant","MS_ENTRA_CLIENT_ID":"client","MS_ENTRA_CLIENT_SECRET":"secret","MS_ENTRA_REDIRECT_URL":"https://example.com/callback","MS_ENTRA_AUTHORITY":"https://login.microsoftonline.com/","MS_ENTRA_SCOPES":"openid"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPut, "/api/v1/master-settings/sso/microsoft", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("upsert service generic error is treated as 400", func(t *testing.T) {
+		svc := &masterSettingsServiceMock{
+			upsertMicrosoftFn: func(_ mastersettings.MicrosoftEntraConfigInput, _ []byte) (*mastersettings.MicrosoftEntraConfigView, error) {
+				return nil, errors.New("storage unavailable")
+			},
+		}
+		h := NewMasterSettingsHandler(svc, nil, nil)
+		app := newMasterSettingsTestApp(h, nil)
+		body := []byte(`{"data":{"type":"master_settings_microsoft_entra_upsert","attributes":{"MS_ENTRA_TENANT_ID":"tenant","MS_ENTRA_CLIENT_ID":"client","MS_ENTRA_CLIENT_SECRET":"secret","MS_ENTRA_REDIRECT_URL":"https://example.com/callback","MS_ENTRA_AUTHORITY":"https://login.microsoftonline.com/","MS_ENTRA_SCOPES":"openid"}}}`)
+		resp, _ := doJSONRequestMasterSettings(t, app, http.MethodPut, "/api/v1/master-settings/sso/microsoft", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("microsoft entra helper functions", func(t *testing.T) {
+		resource := NewMasterSettingsHandler(&masterSettingsServiceMock{}, nil, nil).microsoftEntraResource(nil)
+		if resource.Type != "master_settings_microsoft_entra_sso" {
+			t.Fatalf("unexpected resource type %q", resource.Type)
+		}
+		if !isMicrosoftEntraValidationError(errors.New("required field missing")) {
+			t.Fatalf("expected required error to be validation error")
+		}
+		if !isMicrosoftEntraValidationError(errors.New("MS_ENTRA_CLIENT_ID invalid")) {
+			t.Fatalf("expected MS_ENTRA error to be validation error")
+		}
+		if isMicrosoftEntraValidationError(errors.New("network failed")) {
+			t.Fatalf("expected generic error to be non-validation")
+		}
+	})
+
+	t.Run("managed file asset helpers expose thumbnail and size", func(t *testing.T) {
+		fileID := uuidv7.MustBytes()
+		fileUUID := mustUUIDStringMasterSettings(t, fileID)
+		thumbKey := "images/logo-thumb.png"
+		fileRepo := &masterSettingsFileRepoMock{
+			getByIDRow: &filemanager.File{
+				ID:                 fileID,
+				Status:             filemanager.FileStatusReady,
+				ObjectKey:          "images/logo.png",
+				ThumbnailObjectKey: &thumbKey,
+				SizeBytes:          400,
+				ThumbnailSizeBytes: 120,
+			},
+		}
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, newMasterSettingsFileService(fileRepo), &masterSettingsStorageMock{presignURL: "https://signed/logo.png"})
+		row := &mastersettings.MasterSettings{LogoFileID: fileID, CoverFileID: fileID}
+		withFiberCtx := func(t *testing.T, fn func(*fiber.Ctx)) {
+			t.Helper()
+			app := fiber.New()
+			app.Get("/", func(c *fiber.Ctx) error {
+				fn(c)
+				return c.SendStatus(fiber.StatusOK)
+			})
+			req, _ := http.NewRequest(http.MethodGet, "/", nil)
+			if _, err := app.Test(req); err != nil {
+				t.Fatalf("app.Test: %v", err)
+			}
+		}
+		withFiberCtx(t, func(c *fiber.Ctx) {
+			if got := h.resolveLogoThumbnailURL(c, row, &fileUUID); got == nil || *got == "" {
+				t.Fatalf("expected logo thumbnail url")
+			}
+			if got := h.resolveCoverThumbnailURL(c, row, &fileUUID); got == nil || *got == "" {
+				t.Fatalf("expected cover thumbnail url")
+			}
+			if got := h.resolveLogoOriginalSize(c, row, &fileUUID); got == nil || *got != 400 {
+				t.Fatalf("expected logo original size 400, got %v", got)
+			}
+			if got := h.resolveCoverOriginalSize(c, row, &fileUUID); got == nil || *got != 400 {
+				t.Fatalf("expected cover original size 400, got %v", got)
+			}
+		})
+	})
+
+	t.Run("managed file helper nil branches", func(t *testing.T) {
+		h := NewMasterSettingsHandler(&masterSettingsServiceMock{}, nil, nil)
+		withFiberCtx := func(t *testing.T, fn func(*fiber.Ctx)) {
+			t.Helper()
+			app := fiber.New()
+			app.Get("/", func(c *fiber.Ctx) error {
+				fn(c)
+				return c.SendStatus(fiber.StatusOK)
+			})
+			req, _ := http.NewRequest(http.MethodGet, "/", nil)
+			if _, err := app.Test(req); err != nil {
+				t.Fatalf("app.Test: %v", err)
+			}
+		}
+		withFiberCtx(t, func(c *fiber.Ctx) {
+			if got := h.resolveLogoThumbnailURL(c, nil, nil); got != nil {
+				t.Fatalf("expected nil logo thumbnail for nil row")
+			}
+			if got := h.resolveCoverThumbnailURL(c, nil, nil); got != nil {
+				t.Fatalf("expected nil cover thumbnail for nil row")
+			}
+			if got := h.resolveLogoOriginalSize(c, nil, nil); got != nil {
+				t.Fatalf("expected nil logo size for nil row")
+			}
+			if got := h.resolveCoverOriginalSize(c, nil, nil); got != nil {
+				t.Fatalf("expected nil cover size for nil row")
+			}
+		})
+		if isMicrosoftEntraValidationError(nil) {
+			t.Fatalf("expected nil error to be non-validation")
+		}
+	})
+}
diff --git a/internal/transport/http/handlers/mcf_handler.go b/internal/transport/http/handlers/mcf_handler.go
new file mode 100644
index 0000000..d8c69dc
--- /dev/null
+++ b/internal/transport/http/handlers/mcf_handler.go
@@ -0,0 +1,450 @@
+package handlers
+
+import (
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	fleethistory "wucher/internal/domain/fleet_history"
+	"wucher/internal/domain/mcf"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type MCFHandler struct {
+	svc        mcf.Service
+	historySvc fleetHistoryRecorder
+	validate   *validators.Validator
+}
+
+func NewMCFHandler(svc mcf.Service) *MCFHandler {
+	return &MCFHandler{svc: svc, validate: validators.New()}
+}
+
+func (h *MCFHandler) WithHistoryService(svc fleetHistoryRecorder) *MCFHandler {
+	h.historySvc = svc
+	return h
+}
+
+func writeMCFServiceError(c *fiber.Ctx, err error, fallback apperrorsx.Def) error {
+	if errors.Is(err, mcf.ErrNotFound) {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrMCFNotFound).WithCause(err))
+	}
+	return apperrorsx.Write(c, apperrorsx.New(fallback).WithCause(err))
+}
+
+func mcfResource(row *mcf.MaintenanceCheckFlight) responsedto.MCFResource {
+	if row == nil {
+		return responsedto.MCFResource{}
+	}
+	id, _ := uuidv7.BytesToString(row.ID)
+	out := responsedto.MCFResource{
+		Type: "mcf",
+		ID:   id,
+		Attributes: responsedto.MCFAttributes{
+			HelicopterID: idString(row.HelicopterID),
+			FlightID:     idString(row.FlightID),
+			AFHours:      row.AFHours,
+			LandingCount: row.LandingCount,
+			DecidedBy:    idString(row.DecidedBy),
+			Result:       row.Result,
+			Notes:        row.Notes,
+			CompletedBy:  idString(row.CompletedBy),
+			IsComplete:   row.IsComplete(),
+			IsCleared:    row.IsCleared(),
+			IsPending:    row.IsPending(),
+		},
+	}
+	if row.Date != nil && !row.Date.IsZero() {
+		out.Attributes.Date = row.Date.UTC().Format("2006-01-02")
+	}
+	if row.UTCtime != nil && !row.UTCtime.IsZero() {
+		v := row.UTCtime.UTC().Format(time.RFC3339)
+		out.Attributes.UTCTime = &v
+	}
+	if row.DecidedAt != nil {
+		v := row.DecidedAt.UTC().Format(time.RFC3339)
+		out.Attributes.DecidedAt = &v
+	}
+	if row.CompletedAt != nil {
+		v := row.CompletedAt.UTC().Format(time.RFC3339)
+		out.Attributes.CompletedAt = &v
+	}
+	if !row.CreatedAt.IsZero() {
+		out.Attributes.CreatedAt = row.CreatedAt.UTC().Format(time.RFC3339)
+	}
+	if !row.UpdatedAt.IsZero() {
+		out.Attributes.UpdatedAt = row.UpdatedAt.UTC().Format(time.RFC3339)
+	}
+	return out
+}
+
+// Set godoc
+// @Summary Set a helicopter's MCF Yes/No — draft work endpoint (create/update or cancel)
+// @Description Toggles and edits a helicopter's MCF. `active:true` (or omitted) ACTIVATES/EDITS it — creates the draft if none is open (201), or UPDATES the open draft with the provided check-flight fields (200; af_hours, landing_count, utc_time, date, result, notes — all optional, partial edits allowed). Finalize it via POST /mcf/sign/{id} (sign:true). `active:false` DEACTIVATES it — cancels the open (unsigned) draft ("tidak jadi") and releases the MCF status; the cancelled record stays in the list. A signed MCF is a real event and is not cancelled.
+// @Tags MCF
+// @Accept json
+// @Produce json
+// @Param helicopter_id path string true "Helicopter ID (UUIDv7)"
+// @Param request body requestdto.MCFSetRequest true "JSON:API MCF set request"
+// @Success 201 {object} responsedto.MCFResponse
+// @Success 200 {object} responsedto.MCFResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/mcf/set/{helicopter_id} [post]
+func (h *MCFHandler) Set(c *fiber.Ctx) error {
+	helicopterID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("helicopter_id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrMCFInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/helicopter_id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	var req requestdto.MCFSetRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeBodyParseError(c, err, apperrorsx.ErrMCFInvalidJSON)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return jsonapi.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	attr := req.Data.Attributes
+	active := attr.Active == nil || *attr.Active
+	now := time.Now().UTC()
+	actor := actorUserID(c)
+
+	// Deactivate (No): cancel the helicopter's open (unsigned) draft → release MCF status.
+	// A signed MCF is a real event and is left untouched.
+	if !active {
+		row, gerr := h.svc.GetLatestByHelicopter(c.UserContext(), helicopterID)
+		if gerr != nil {
+			return writeMCFServiceError(c, gerr, apperrorsx.ErrMCFCreateFailed)
+		}
+		if row == nil {
+			// No MCF at all — already "No" (idempotent no-op).
+			return response.Write(c, fiber.StatusOK, map[string]any{"data": map[string]any{"type": "mcf_set", "attributes": map[string]bool{"active": false}}})
+		}
+		if !row.IsOpen() {
+			// Signed (or already cancelled) MCF is a real record — NOT cancelled by set:false.
+			// Return it as-is so the client/fleet still shows the completed data.
+			return response.Write(c, fiber.StatusOK, responsedto.MCFResponse{Data: mcfResource(row)})
+		}
+		row.CancelledAt = &now
+		row.CancelledBy = actor
+		row.UpdatedBy = actor
+		if err := h.svc.Update(c.UserContext(), row); err != nil {
+			return writeMCFServiceError(c, err, apperrorsx.ErrMCFCreateFailed)
+		}
+		updated, _ := h.svc.GetByID(c.UserContext(), row.ID)
+		if updated == nil {
+			updated = row
+		}
+		return response.Write(c, fiber.StatusOK, responsedto.MCFResponse{Data: mcfResource(updated)})
+	}
+
+	// Activate (Yes): the draft work endpoint — create the draft if none is open, or
+	// UPDATE the open draft with the provided check-flight fields. Finalize via /mcf/sign.
+	var flightID []byte
+	if s := strings.TrimSpace(attr.FlightID); s != "" {
+		flightID, err = uuidv7.ParseString(s)
+		if err != nil {
+			appErr := apperrorsx.New(apperrorsx.ErrMCFInvalidUUID).WithCause(err)
+			appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_id"}
+			return apperrorsx.Write(c, appErr)
+		}
+	}
+	draftFields := mcfSignFields{
+		Result:       attr.Result,
+		AFHours:      attr.AFHours,
+		LandingCount: attr.LandingCount,
+		UTCTime:      attr.UTCTime,
+		Date:         attr.Date,
+		Notes:        attr.Notes,
+	}
+
+	// Update the open draft in place if one exists.
+	if existing, gerr := h.svc.GetLatestByHelicopter(c.UserContext(), helicopterID); gerr != nil {
+		return writeMCFServiceError(c, gerr, apperrorsx.ErrMCFCreateFailed)
+	} else if existing != nil && existing.IsOpen() {
+		if aerr := applyMCFDraftFields(existing, draftFields); aerr != nil {
+			return apperrorsx.Write(c, aerr)
+		}
+		if len(flightID) == 16 {
+			existing.FlightID = flightID
+		}
+		existing.UpdatedBy = actor
+		if err := h.svc.Update(c.UserContext(), existing); err != nil {
+			return writeMCFServiceError(c, err, apperrorsx.ErrMCFCreateFailed)
+		}
+		updated, _ := h.svc.GetByID(c.UserContext(), existing.ID)
+		if updated == nil {
+			updated = existing
+		}
+		return response.Write(c, fiber.StatusOK, responsedto.MCFResponse{Data: mcfResource(updated)})
+	}
+
+	// No open draft → create a new one (with any provided data).
+	row := &mcf.MaintenanceCheckFlight{
+		HelicopterID: helicopterID,
+		FlightID:     flightID,
+		DecidedBy:    actor,
+		DecidedAt:    &now,
+		CreatedBy:    actor,
+		UpdatedBy:    actor,
+	}
+	if aerr := applyMCFDraftFields(row, draftFields); aerr != nil {
+		return apperrorsx.Write(c, aerr)
+	}
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeMCFServiceError(c, err, apperrorsx.ErrMCFCreateFailed)
+	}
+	created, _ := h.svc.GetByID(c.UserContext(), row.ID)
+	if created == nil {
+		created = row
+	}
+	return response.Write(c, fiber.StatusCreated, responsedto.MCFResponse{Data: mcfResource(created)})
+}
+
+// GetByID godoc
+// @Summary Get MCF by ID
+// @Tags MCF
+// @Produce json
+// @Param id path string true "MCF ID (UUIDv7)"
+// @Success 200 {object} responsedto.MCFResponse
+// @Router /api/v1/mcf/get/{id} [get]
+func (h *MCFHandler) GetByID(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrMCFInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return writeMCFServiceError(c, err, apperrorsx.ErrMCFNotFound)
+	}
+	if row == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrMCFNotFound))
+	}
+	return response.Write(c, fiber.StatusOK, responsedto.MCFResponse{Data: mcfResource(row)})
+}
+
+// ListByHelicopter godoc
+// @Summary List MCFs for a helicopter
+// @Tags MCF
+// @Produce json
+// @Param helicopter_id path string true "Helicopter ID (UUIDv7)"
+// @Success 200 {object} responsedto.MCFListResponse
+// @Router /api/v1/mcf/get-by-helicopter/{helicopter_id} [get]
+func (h *MCFHandler) ListByHelicopter(c *fiber.Ctx) error {
+	helicopterID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("helicopter_id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrMCFInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/helicopter_id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	rows, err := h.svc.ListByHelicopter(c.UserContext(), helicopterID)
+	if err != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrMCFListFailed).WithCause(err))
+	}
+	data := make([]responsedto.MCFResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, mcfResource(&rows[i]))
+	}
+	resp := responsedto.MCFListResponse{Data: data}
+	resp.Meta.Total = int64(len(data))
+	return response.Write(c, fiber.StatusOK, resp)
+}
+
+// mcfSignFields is the check-flight data recorded when an MCF is signed (completed).
+type mcfSignFields struct {
+	Result       string
+	AFHours      string
+	LandingCount *int
+	UTCTime      string
+	Date         string
+	Notes        *string
+}
+
+// stampMCFSign validates the check-flight fields and stamps the row as signed/completed.
+// Returns a non-nil AppError (422, pointing at the offending field) on invalid input.
+func stampMCFSign(row *mcf.MaintenanceCheckFlight, f mcfSignFields, actor []byte) *apperrorsx.AppError {
+	missing := ""
+	switch {
+	case strings.TrimSpace(f.Result) == "":
+		missing = "result"
+	case strings.TrimSpace(f.AFHours) == "":
+		missing = "af_hours"
+	case f.LandingCount == nil:
+		missing = "landing_count"
+	case strings.TrimSpace(f.UTCTime) == "":
+		missing = "utc_time"
+	case strings.TrimSpace(f.Date) == "":
+		missing = "date"
+	}
+	if missing != "" {
+		appErr := apperrorsx.New(apperrorsx.ErrMCFInvalidPayload)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/" + missing}
+		return appErr
+	}
+	result := strings.TrimSpace(f.Result)
+	if result != mcf.ResultPassed && result != mcf.ResultFailed {
+		appErr := apperrorsx.New(apperrorsx.ErrMCFInvalidPayload)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/result"}
+		return appErr
+	}
+	mcfDate, err := time.Parse("2006-01-02", strings.TrimSpace(f.Date))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrMCFInvalidPayload).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/date"}
+		return appErr
+	}
+	utcTime, err := time.Parse(time.RFC3339, strings.TrimSpace(f.UTCTime))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrMCFInvalidPayload).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/utc_time"}
+		return appErr
+	}
+	now := time.Now().UTC()
+	d := mcfDate.UTC()
+	utc := utcTime.UTC()
+	row.Date = &d
+	row.AFHours = strings.TrimSpace(f.AFHours)
+	row.LandingCount = *f.LandingCount
+	row.UTCtime = &utc
+	row.Result = &result
+	if f.Notes != nil {
+		row.Notes = emptyToNilString(f.Notes)
+	}
+	row.CompletedAt = &now
+	row.CompletedBy = append([]byte(nil), actor...)
+	return nil
+}
+
+// applyMCFDraftFields saves the PROVIDED check-flight fields onto the row without
+// completing it (a draft save — partial input allowed). Only non-empty fields are
+// written; a bad date/utc_time/result → 422 pointing at the field.
+func applyMCFDraftFields(row *mcf.MaintenanceCheckFlight, f mcfSignFields) *apperrorsx.AppError {
+	if s := strings.TrimSpace(f.Date); s != "" {
+		d, err := time.Parse("2006-01-02", s)
+		if err != nil {
+			appErr := apperrorsx.New(apperrorsx.ErrMCFInvalidPayload).WithCause(err)
+			appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/date"}
+			return appErr
+		}
+		du := d.UTC()
+		row.Date = &du
+	}
+	if s := strings.TrimSpace(f.UTCTime); s != "" {
+		u, err := time.Parse(time.RFC3339, s)
+		if err != nil {
+			appErr := apperrorsx.New(apperrorsx.ErrMCFInvalidPayload).WithCause(err)
+			appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/utc_time"}
+			return appErr
+		}
+		uu := u.UTC()
+		row.UTCtime = &uu
+	}
+	if s := strings.TrimSpace(f.AFHours); s != "" {
+		row.AFHours = s
+	}
+	if f.LandingCount != nil {
+		row.LandingCount = *f.LandingCount
+	}
+	if s := strings.TrimSpace(f.Result); s != "" {
+		if s != mcf.ResultPassed && s != mcf.ResultFailed {
+			appErr := apperrorsx.New(apperrorsx.ErrMCFInvalidPayload)
+			appErr.Source = &jsonapi.ErrorSource{Pointer: "/data/attributes/result"}
+			return appErr
+		}
+		row.Result = &s
+	}
+	if f.Notes != nil {
+		row.Notes = emptyToNilString(f.Notes)
+	}
+	return nil
+}
+
+// Sign godoc
+// @Summary Sign (finalize) or unsign an MCF — toggle by MCF id
+// @Description Finalizes an MCF's check-flight. `sign` (optional, default true): true FINALIZES it — af_hours, landing_count, utc_time, date, result required; "passed" clears the aircraft from MCF, "failed" keeps it grounded. false UNSIGNS it — reverts a signed MCF back to a draft (keeps the recorded data). Editing draft fields is done via /mcf/set; cancelling via /mcf/set (active:false).
+// @Tags MCF
+// @Accept json
+// @Produce json
+// @Param id path string true "MCF ID (UUIDv7)"
+// @Param request body requestdto.MCFCompleteRequest true "JSON:API MCF sign request"
+// @Success 200 {object} responsedto.MCFResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/mcf/sign/{id} [post]
+func (h *MCFHandler) Sign(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		appErr := apperrorsx.New(apperrorsx.ErrMCFInvalidUUID).WithCause(err)
+		appErr.Source = &jsonapi.ErrorSource{Pointer: "/path/id"}
+		return apperrorsx.Write(c, appErr)
+	}
+	var req requestdto.MCFCompleteRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeBodyParseError(c, err, apperrorsx.ErrMCFInvalidJSON)
+	}
+	attr := req.Data.Attributes
+	signWanted := attr.Sign == nil || *attr.Sign
+
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return writeMCFServiceError(c, err, apperrorsx.ErrMCFCompleteFailed)
+	}
+	if row == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrMCFNotFound))
+	}
+
+	// Unsign (sign:false): revert a signed MCF back to a draft — clears the signature but
+	// KEEPS the recorded data. Editing draft data is done via /mcf/set; cancelling via
+	// /mcf/set (active:false).
+	if !signWanted {
+		row.CompletedAt = nil
+		row.CompletedBy = nil
+		row.UpdatedBy = actorUserID(c)
+		if err := h.svc.Update(c.UserContext(), row); err != nil {
+			return writeMCFServiceError(c, err, apperrorsx.ErrMCFCompleteFailed)
+		}
+		updated, _ := h.svc.GetByID(c.UserContext(), id)
+		if updated == nil {
+			updated = row
+		}
+		return response.Write(c, fiber.StatusOK, responsedto.MCFResponse{Data: mcfResource(updated)})
+	}
+
+	// Sign: the check-flight fields are required.
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return jsonapi.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if aerr := stampMCFSign(row, mcfSignFields{
+		Result:       attr.Result,
+		AFHours:      attr.AFHours,
+		LandingCount: attr.LandingCount,
+		UTCTime:      attr.UTCTime,
+		Date:         attr.Date,
+		Notes:        attr.Notes,
+	}, actorUserID(c)); aerr != nil {
+		return apperrorsx.Write(c, aerr)
+	}
+	row.UpdatedBy = actorUserID(c)
+	if err := h.svc.Update(c.UserContext(), row); err != nil {
+		return writeMCFServiceError(c, err, apperrorsx.ErrMCFCompleteFailed)
+	}
+	updated, _ := h.svc.GetByID(c.UserContext(), row.ID)
+	if updated == nil {
+		updated = row
+	}
+	if h.historySvc != nil {
+		_ = h.historySvc.Record(c.UserContext(), updated.HelicopterID, fleethistory.EntityMCF, updated.ID, fleethistory.ActionMCFResult, "MCF result: "+strings.TrimSpace(attr.Result), actorUserID(c))
+	}
+	return response.Write(c, fiber.StatusOK, responsedto.MCFResponse{Data: mcfResource(updated)})
+}
+
diff --git a/internal/transport/http/handlers/mcf_handler_test.go b/internal/transport/http/handlers/mcf_handler_test.go
new file mode 100644
index 0000000..7ececf0
--- /dev/null
+++ b/internal/transport/http/handlers/mcf_handler_test.go
@@ -0,0 +1,430 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/mcf"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type stubMCFSvc struct {
+	created   *mcf.MaintenanceCheckFlight
+	updated   *mcf.MaintenanceCheckFlight
+	latest    *mcf.MaintenanceCheckFlight
+	byID      *mcf.MaintenanceCheckFlight
+	createErr error
+	updateErr error
+	deleteErr error
+	listErr   error
+	latestErr error
+	hasOpen   bool
+}
+
+type stubHistoryRec struct{ n int }
+
+func (s *stubHistoryRec) Record(_ context.Context, _ []byte, _ string, _ []byte, _, _ string, _ []byte) error {
+	s.n++
+	return nil
+}
+func (s *stubHistoryRec) RecordByInspection(_ context.Context, _ []byte, _ string, _ []byte, _, _ string, _ []byte) error {
+	return nil
+}
+
+func (s *stubMCFSvc) Create(_ context.Context, row *mcf.MaintenanceCheckFlight) error {
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	s.created = row
+	return s.createErr
+}
+func (s *stubMCFSvc) Update(_ context.Context, row *mcf.MaintenanceCheckFlight) error {
+	s.updated = row
+	return s.updateErr
+}
+func (s *stubMCFSvc) Delete(_ context.Context, _, _ []byte) error { return s.deleteErr }
+func (s *stubMCFSvc) GetByID(_ context.Context, _ []byte) (*mcf.MaintenanceCheckFlight, error) {
+	if s.byID != nil {
+		return s.byID, nil
+	}
+	if s.updated != nil {
+		return s.updated, nil
+	}
+	return s.created, nil
+}
+func (s *stubMCFSvc) ListByHelicopter(_ context.Context, _ []byte) ([]mcf.MaintenanceCheckFlight, error) {
+	if s.listErr != nil {
+		return nil, s.listErr
+	}
+	if s.latest != nil {
+		return []mcf.MaintenanceCheckFlight{*s.latest}, nil
+	}
+	return nil, nil
+}
+func (s *stubMCFSvc) GetLatestByHelicopter(_ context.Context, _ []byte) (*mcf.MaintenanceCheckFlight, error) {
+	return s.latest, s.latestErr
+}
+func (s *stubMCFSvc) PendingHelicopterIDs(_ context.Context, _ [][]byte) (map[string]bool, error) {
+	return nil, nil
+}
+
+func (s *stubMCFSvc) LatestByHelicopterIDs(_ context.Context, _ [][]byte) (map[string]*mcf.MaintenanceCheckFlight, error) {
+	return nil, nil
+}
+
+func (s *stubMCFSvc) HelicopterHasOpenMCF(_ context.Context, _ []byte) (bool, error) {
+	return s.hasOpen, nil
+}
+
+func newMCFApp(svc mcf.Service) *fiber.App {
+	h := NewMCFHandler(svc)
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", []byte("actor0123456789a"))
+		return c.Next()
+	})
+	app.Post("/mcf/set/:helicopter_id", h.Set)
+	app.Post("/mcf/sign/:id", h.Sign)
+	app.Get("/mcf/get/:id", h.GetByID)
+	app.Get("/mcf/get-by-helicopter/:helicopter_id", h.ListByHelicopter)
+	return app
+}
+
+func doMCF(t *testing.T, app *fiber.App, method, path, body string) (int, map[string]any) {
+	t.Helper()
+	req, _ := http.NewRequest(method, path, bytes.NewReader([]byte(body)))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	raw, _ := io.ReadAll(resp.Body)
+	var out map[string]any
+	_ = json.Unmarshal(raw, &out)
+	return resp.StatusCode, out
+}
+
+func mcfUUID() string {
+	s, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	return s
+}
+
+func openMCF() *mcf.MaintenanceCheckFlight {
+	return &mcf.MaintenanceCheckFlight{ID: uuidv7.MustBytes(), HelicopterID: uuidv7.MustBytes()}
+}
+
+func TestMCFHandlerSet(t *testing.T) {
+	hid := mcfUUID()
+
+	t.Run("activate creates a draft", func(t *testing.T) {
+		svc := &stubMCFSvc{}
+		code, _ := doMCF(t, newMCFApp(svc), http.MethodPost, "/mcf/set/"+hid,
+			`{"data":{"type":"mcf_set","attributes":{"active":true}}}`)
+		if code != http.StatusCreated {
+			t.Fatalf("want 201, got %d", code)
+		}
+		if svc.created == nil || len(svc.created.HelicopterID) == 0 {
+			t.Fatal("activate should persist a draft with helicopter id")
+		}
+		if svc.created.Result != nil || svc.created.CompletedAt != nil {
+			t.Fatal("a draft must not be completed/signed")
+		}
+	})
+
+	t.Run("omitted active defaults to activate", func(t *testing.T) {
+		svc := &stubMCFSvc{}
+		code, _ := doMCF(t, newMCFApp(svc), http.MethodPost, "/mcf/set/"+hid,
+			`{"data":{"type":"mcf_set","attributes":{}}}`)
+		if code != http.StatusCreated || svc.created == nil {
+			t.Fatalf("omitted active should create a draft, got %d %#v", code, svc.created)
+		}
+	})
+
+	t.Run("activate with flight_id stores it", func(t *testing.T) {
+		svc := &stubMCFSvc{}
+		fid := mcfUUID()
+		code, _ := doMCF(t, newMCFApp(svc), http.MethodPost, "/mcf/set/"+hid,
+			`{"data":{"type":"mcf_set","attributes":{"active":true,"flight_id":"`+fid+`"}}}`)
+		if code != http.StatusCreated || svc.created == nil || len(svc.created.FlightID) != 16 {
+			t.Fatalf("activate should persist flight id, got %d %#v", code, svc.created)
+		}
+	})
+
+	t.Run("activate updates the open draft (in place)", func(t *testing.T) {
+		draft := &mcf.MaintenanceCheckFlight{ID: uuidv7.MustBytes(), HelicopterID: uuidv7.MustBytes()} // open draft
+		svc := &stubMCFSvc{latest: draft}
+		code, _ := doMCF(t, newMCFApp(svc), http.MethodPost, "/mcf/set/"+hid,
+			`{"data":{"type":"mcf_set","attributes":{"active":true,"af_hours":"1245.3","landing_count":3}}}`)
+		if code != http.StatusOK {
+			t.Fatalf("want 200 (update open draft), got %d", code)
+		}
+		if svc.updated == nil || svc.updated.AFHours != "1245.3" || svc.updated.LandingCount != 3 {
+			t.Fatalf("activate should update the open draft with the data, got %#v", svc.updated)
+		}
+		if svc.updated.CompletedAt != nil {
+			t.Fatalf("updating a draft must not sign it, got %#v", svc.updated)
+		}
+		if svc.created != nil {
+			t.Fatal("must not create a second MCF when a draft is already open")
+		}
+	})
+
+	t.Run("deactivate cancels the open draft", func(t *testing.T) {
+		draft := &mcf.MaintenanceCheckFlight{ID: uuidv7.MustBytes(), HelicopterID: uuidv7.MustBytes()} // open draft
+		svc := &stubMCFSvc{latest: draft}
+		code, _ := doMCF(t, newMCFApp(svc), http.MethodPost, "/mcf/set/"+hid,
+			`{"data":{"type":"mcf_set","attributes":{"active":false}}}`)
+		if code != http.StatusOK {
+			t.Fatalf("want 200, got %d", code)
+		}
+		if svc.updated == nil || svc.updated.CancelledAt == nil || len(svc.updated.CancelledBy) == 0 {
+			t.Fatalf("deactivate must mark the draft cancelled, got %#v", svc.updated)
+		}
+	})
+
+	t.Run("deactivate does not cancel a signed MCF", func(t *testing.T) {
+		done := time.Now().UTC()
+		signed := &mcf.MaintenanceCheckFlight{ID: uuidv7.MustBytes(), HelicopterID: uuidv7.MustBytes(), CompletedAt: &done}
+		svc := &stubMCFSvc{latest: signed}
+		code, _ := doMCF(t, newMCFApp(svc), http.MethodPost, "/mcf/set/"+hid,
+			`{"data":{"type":"mcf_set","attributes":{"active":false}}}`)
+		if code != http.StatusOK {
+			t.Fatalf("want 200, got %d", code)
+		}
+		if svc.updated != nil {
+			t.Fatalf("a signed MCF (real event) must not be cancelled, got %#v", svc.updated)
+		}
+	})
+
+	t.Run("deactivate no-op when nothing open", func(t *testing.T) {
+		svc := &stubMCFSvc{latest: nil}
+		code, _ := doMCF(t, newMCFApp(svc), http.MethodPost, "/mcf/set/"+hid,
+			`{"data":{"type":"mcf_set","attributes":{"active":false}}}`)
+		if code != http.StatusOK {
+			t.Fatalf("want 200, got %d", code)
+		}
+		if svc.updated != nil {
+			t.Fatal("no open MCF -> nothing to cancel")
+		}
+	})
+
+	t.Run("invalid helicopter_id path -> 422", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{}), http.MethodPost, "/mcf/set/not-a-uuid",
+			`{"data":{"type":"mcf_set","attributes":{"active":true}}}`)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("want 422, got %d", code)
+		}
+	})
+
+	t.Run("invalid json -> 400", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{}), http.MethodPost, "/mcf/set/"+hid, `{"data":`)
+		if code != http.StatusBadRequest {
+			t.Fatalf("want 400, got %d", code)
+		}
+	})
+
+	t.Run("wrong data type -> INVALID_DATA_TYPE", func(t *testing.T) {
+		// flight_id is a string; sending a number is a data-type mismatch.
+		code, body := doMCF(t, newMCFApp(&stubMCFSvc{}), http.MethodPost, "/mcf/set/"+hid,
+			`{"data":{"type":"mcf_set","attributes":{"active":true,"flight_id":123}}}`)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("want 422, got %d body=%#v", code, body)
+		}
+		errs, _ := body["errors"].([]any)
+		if len(errs) == 0 || errs[0].(map[string]any)["code"] != "INVALID_DATA_TYPE" {
+			t.Fatalf("expected INVALID_DATA_TYPE, got %#v", body)
+		}
+	})
+}
+
+func completeBody(result string) string {
+	return `{"data":{"type":"mcf","attributes":{"af_hours":"1245.3","landing_count":3,"utc_time":"2026-06-17T08:30:00Z","date":"2026-06-17","result":"` + result + `"}}}`
+}
+
+func TestMCFHandlerSign(t *testing.T) {
+	id := mcfUUID()
+
+	t.Run("sign passed clears", func(t *testing.T) {
+		svc := &stubMCFSvc{byID: openMCF()}
+		code, _ := doMCF(t, newMCFApp(svc), http.MethodPost, "/mcf/sign/"+id, completeBody("passed"))
+		if code != http.StatusOK {
+			t.Fatalf("want 200, got %d", code)
+		}
+		if svc.updated == nil || svc.updated.Result == nil || *svc.updated.Result != mcf.ResultPassed {
+			t.Fatal("expected result=passed persisted")
+		}
+		if svc.updated.CompletedAt == nil || svc.updated.CompletedBy == nil || svc.updated.Date == nil || svc.updated.LandingCount != 3 {
+			t.Fatal("expected check-flight fields + signer stamped")
+		}
+	})
+
+	t.Run("sign failed stays grounded", func(t *testing.T) {
+		svc := &stubMCFSvc{byID: openMCF()}
+		code, _ := doMCF(t, newMCFApp(svc), http.MethodPost, "/mcf/sign/"+id, completeBody("failed"))
+		if code != http.StatusOK || svc.updated == nil || *svc.updated.Result != mcf.ResultFailed {
+			t.Fatalf("want 200 with failed result, got %d", code)
+		}
+	})
+
+	t.Run("unsign reverts to draft but keeps data", func(t *testing.T) {
+		passed := mcf.ResultPassed
+		now := time.Now().UTC()
+		signed := openMCF()
+		signed.Result = &passed
+		signed.AFHours = "1300"
+		signed.CompletedAt = &now
+		signed.CompletedBy = []byte("actor0123456789a")
+		svc := &stubMCFSvc{byID: signed}
+		code, _ := doMCF(t, newMCFApp(svc), http.MethodPost, "/mcf/sign/"+id,
+			`{"data":{"type":"mcf","attributes":{"sign":false}}}`)
+		if code != http.StatusOK {
+			t.Fatalf("want 200, got %d", code)
+		}
+		// completed_at cleared (back to draft), but the saved data is kept.
+		if svc.updated == nil || svc.updated.CompletedAt != nil || len(svc.updated.CompletedBy) != 0 {
+			t.Fatalf("unsign must clear completion, got %#v", svc.updated)
+		}
+		if svc.updated.Result == nil || *svc.updated.Result != mcf.ResultPassed || svc.updated.AFHours != "1300" {
+			t.Fatalf("unsign must KEEP the saved data, got %#v", svc.updated)
+		}
+	})
+
+
+	t.Run("sign on missing mcf -> 404", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{}), http.MethodPost, "/mcf/sign/"+id, completeBody("passed"))
+		if code != http.StatusNotFound {
+			t.Fatalf("want 404, got %d", code)
+		}
+	})
+
+	t.Run("sign missing required field -> 422", func(t *testing.T) {
+		body := `{"data":{"type":"mcf","attributes":{"sign":true,"landing_count":3,"utc_time":"2026-06-17T08:30:00Z","date":"2026-06-17","result":"passed"}}}` // no af_hours
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{byID: openMCF()}), http.MethodPost, "/mcf/sign/"+id, body)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("want 422, got %d", code)
+		}
+	})
+
+	t.Run("sign invalid result -> 422", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{byID: openMCF()}), http.MethodPost, "/mcf/sign/"+id, completeBody("maybe"))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("want 422, got %d", code)
+		}
+	})
+
+	t.Run("sign bad date -> 422", func(t *testing.T) {
+		body := `{"data":{"type":"mcf","attributes":{"af_hours":"1","landing_count":1,"utc_time":"2026-06-17T08:30:00Z","date":"17-06-2026","result":"passed"}}}`
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{byID: openMCF()}), http.MethodPost, "/mcf/sign/"+id, body)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("want 422, got %d", code)
+		}
+	})
+
+	t.Run("sign bad utc_time -> 422", func(t *testing.T) {
+		body := `{"data":{"type":"mcf","attributes":{"af_hours":"1","landing_count":1,"utc_time":"nope","date":"2026-06-17","result":"passed"}}}`
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{byID: openMCF()}), http.MethodPost, "/mcf/sign/"+id, body)
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("want 422, got %d", code)
+		}
+	})
+
+	t.Run("invalid id path -> 422", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{}), http.MethodPost, "/mcf/sign/not-a-uuid", completeBody("passed"))
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("want 422, got %d", code)
+		}
+	})
+}
+
+func TestMCFHandlerGetListDelete(t *testing.T) {
+	id := mcfUUID()
+	hid := mcfUUID()
+
+	t.Run("get by id", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{byID: openMCF()}), http.MethodGet, "/mcf/get/"+id, "")
+		if code != http.StatusOK {
+			t.Fatalf("want 200, got %d", code)
+		}
+	})
+	t.Run("get not found", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{}), http.MethodGet, "/mcf/get/"+id, "")
+		if code != http.StatusNotFound {
+			t.Fatalf("want 404, got %d", code)
+		}
+	})
+	t.Run("get invalid uuid", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{}), http.MethodGet, "/mcf/get/bad", "")
+		if code != http.StatusUnprocessableEntity {
+			t.Fatalf("want 422, got %d", code)
+		}
+	})
+	t.Run("list by helicopter", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{latest: openMCF()}), http.MethodGet, "/mcf/get-by-helicopter/"+hid, "")
+		if code != http.StatusOK {
+			t.Fatalf("want 200, got %d", code)
+		}
+	})
+	t.Run("list error", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{listErr: context.DeadlineExceeded}), http.MethodGet, "/mcf/get-by-helicopter/"+hid, "")
+		if code != http.StatusBadRequest {
+			t.Fatalf("want 400, got %d", code)
+		}
+	})
+}
+
+func TestMCFHandlerErrorAndHistoryBranches(t *testing.T) {
+	t.Run("activate service error -> 400", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{createErr: context.DeadlineExceeded}), http.MethodPost, "/mcf/set/"+mcfUUID(),
+			`{"data":{"type":"mcf_set","attributes":{"active":true}}}`)
+		if code != http.StatusBadRequest {
+			t.Fatalf("want 400, got %d", code)
+		}
+	})
+
+	t.Run("activate not-found maps to 404", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{createErr: mcf.ErrNotFound}), http.MethodPost, "/mcf/set/"+mcfUUID(),
+			`{"data":{"type":"mcf_set","attributes":{"active":true}}}`)
+		if code != http.StatusNotFound {
+			t.Fatalf("want 404, got %d", code)
+		}
+	})
+
+	t.Run("sign update error -> 400", func(t *testing.T) {
+		code, _ := doMCF(t, newMCFApp(&stubMCFSvc{byID: openMCF(), updateErr: context.DeadlineExceeded}), http.MethodPost, "/mcf/sign/"+mcfUUID(), completeBody("passed"))
+		if code != http.StatusBadRequest {
+			t.Fatalf("want 400, got %d", code)
+		}
+	})
+
+	t.Run("sign with notes", func(t *testing.T) {
+		svc := &stubMCFSvc{byID: openMCF()}
+		body := `{"data":{"type":"mcf","attributes":{"af_hours":"1","landing_count":2,"utc_time":"2026-06-17T08:30:00Z","date":"2026-06-17","result":"passed","notes":"vibration ok"}}}`
+		code, _ := doMCF(t, newMCFApp(svc), http.MethodPost, "/mcf/sign/"+mcfUUID(), body)
+		if code != http.StatusOK || svc.updated == nil || svc.updated.Notes == nil || *svc.updated.Notes != "vibration ok" {
+			t.Fatalf("want 200 with notes recorded, got %d", code)
+		}
+	})
+
+	t.Run("sign records history", func(t *testing.T) {
+		svc := &stubMCFSvc{byID: openMCF()}
+		hist := &stubHistoryRec{}
+		h := NewMCFHandler(svc).WithHistoryService(hist)
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error { c.Locals("user_id", []byte("actor0123456789a")); return c.Next() })
+		app.Post("/mcf/sign/:id", h.Sign)
+		code, _ := doMCF(t, app, http.MethodPost, "/mcf/sign/"+mcfUUID(), completeBody("failed"))
+		if code != http.StatusOK {
+			t.Fatalf("want 200, got %d", code)
+		}
+		if hist.n != 1 {
+			t.Fatalf("expected 1 history record, got %d", hist.n)
+		}
+	})
+}
diff --git a/internal/transport/http/handlers/medicine_handler.go b/internal/transport/http/handlers/medicine_handler.go
new file mode 100644
index 0000000..230fa90
--- /dev/null
+++ b/internal/transport/http/handlers/medicine_handler.go
@@ -0,0 +1,1134 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/medicine"
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type MedicineHandler struct {
+	svc      medicine.Service
+	validate *validators.Validator
+}
+
+func NewMedicineHandler(svc medicine.Service) *MedicineHandler {
+	return &MedicineHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateMedicine godoc
+// @Summary Create medicine
+// @Description Create a medicine row.
+// @Tags OPC - Medicine
+// @Accept json
+// @Produce json
+// @Param request body dto.MedicineCreateRequest true "JSON:API medicine create request"
+// @Success 201 {object} dto.MedicineResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/medicine/create [post]
+func (h *MedicineHandler) Create(c *fiber.Ctx) error {
+	var req dto.MedicineCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	name := strings.TrimSpace(req.Data.Attributes.Name)
+	if name == "" {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+		}})
+	}
+
+	row := &medicine.Medicine{
+		Name:      name,
+		SortKey:   cloneIntPointer(req.Data.Attributes.SortKey),
+		Note:      strings.TrimSpace(stringOrDefault(req.Data.Attributes.Note, "")),
+		Pack:      strings.TrimSpace(stringOrDefault(req.Data.Attributes.Pack, "")),
+		Unit:      strings.TrimSpace(stringOrDefault(req.Data.Attributes.Unit, "")),
+		Column:    intOrDefault64(req.Data.Attributes.Column, 0),
+		IsActive:  boolOrDefault(req.Data.Attributes.IsActive, true),
+		CreatedBy: actorUserID(c),
+		UpdatedBy: actorUserID(c),
+	}
+	if req.Data.Attributes.MedicineGroupID != nil && strings.TrimSpace(*req.Data.Attributes.MedicineGroupID) != "" {
+		groupID, err := uuidv7.ParseString(strings.TrimSpace(*req.Data.Attributes.MedicineGroupID))
+		if err != nil {
+			return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "medicine_group_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/medicine_group_id"},
+			}})
+		}
+		row.MedicineGroupID = groupID
+	}
+	if req.Data.Attributes.MotorReactionID != nil && strings.TrimSpace(*req.Data.Attributes.MotorReactionID) != "" {
+		reactionID, err := uuidv7.ParseString(strings.TrimSpace(*req.Data.Attributes.MotorReactionID))
+		if err != nil {
+			return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "motor_reaction_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/motor_reaction_id"},
+			}})
+		}
+		row.MotorReactionID = reactionID
+	}
+	reactionIDs, err := parseReactionIDs(req.Data.Attributes.MotorReactionIDs)
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "motor_reaction_ids contains invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/motor_reaction_ids"},
+		}})
+	}
+	if len(reactionIDs) > 0 {
+		row.MotorReactions = make([]medicine.MotorReaction, 0, len(reactionIDs))
+		for i := range reactionIDs {
+			row.MotorReactions = append(row.MotorReactions, medicine.MotorReaction{ID: reactionIDs[i]})
+		}
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, medicineResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, medicineResource(row))
+}
+
+// UpdateMedicine godoc
+// @Summary Update medicine (partial)
+// @Description Patch medicine by ID.
+// @Tags OPC - Medicine
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Medicine UUID (UUIDv7)"
+// @Param request body dto.MedicineUpdateRequest true "JSON:API medicine update request"
+// @Success 200 {object} dto.MedicineResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/medicine/update/{uuid} [patch]
+func (h *MedicineHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.MedicineUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Name == nil && !attrs.SortKey.Set && attrs.Note == nil && attrs.Pack == nil && attrs.Unit == nil && attrs.Column == nil && !attrs.MedicineGroupID.Set && !attrs.MotorReactionID.Set && attrs.MotorReactionIDs == nil && attrs.IsActive == nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeMedicineErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "medicine not found",
+		}})
+	}
+
+	if attrs.Name != nil {
+		v := strings.TrimSpace(*attrs.Name)
+		if v == "" {
+			return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+			}})
+		}
+		existing.Name = v
+	}
+	if attrs.SortKey.Set {
+		if attrs.SortKey.Valid {
+			sortKey := attrs.SortKey.Value
+			existing.SortKey = &sortKey
+		} else {
+			existing.SortKey = nil
+		}
+	}
+	if attrs.Note != nil {
+		existing.Note = strings.TrimSpace(*attrs.Note)
+	}
+	if attrs.Pack != nil {
+		existing.Pack = strings.TrimSpace(*attrs.Pack)
+	}
+	if attrs.Unit != nil {
+		existing.Unit = strings.TrimSpace(*attrs.Unit)
+	}
+	if attrs.Column != nil {
+		existing.Column = *attrs.Column
+	}
+	if attrs.MedicineGroupID.Set {
+		// Prevent stale preloaded association from overriding FK on save.
+		existing.MedicineGroup = nil
+		if attrs.MedicineGroupID.Valid {
+			groupIDStr := strings.TrimSpace(attrs.MedicineGroupID.Value)
+			if groupIDStr == "" {
+				existing.MedicineGroupID = nil
+			} else {
+				groupID, err := uuidv7.ParseString(groupIDStr)
+				if err != nil {
+					return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+						Status: "422",
+						Title:  "Validation error",
+						Detail: "medicine_group_id is invalid UUID",
+						Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/medicine_group_id"},
+					}})
+				}
+				existing.MedicineGroupID = groupID
+			}
+		} else {
+			existing.MedicineGroupID = nil
+		}
+	}
+	if attrs.MotorReactionID.Set {
+		// Prevent stale preloaded association from overriding FK on save.
+		existing.MotorReaction = nil
+		if attrs.MotorReactionID.Valid {
+			reactionIDStr := strings.TrimSpace(attrs.MotorReactionID.Value)
+			if reactionIDStr == "" {
+				existing.MotorReactionID = nil
+			} else {
+				reactionID, err := uuidv7.ParseString(reactionIDStr)
+				if err != nil {
+					return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+						Status: "422",
+						Title:  "Validation error",
+						Detail: "motor_reaction_id is invalid UUID",
+						Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/motor_reaction_id"},
+					}})
+				}
+				existing.MotorReactionID = reactionID
+			}
+		} else {
+			existing.MotorReactionID = nil
+		}
+	}
+	if attrs.MotorReactionIDs != nil {
+		reactionIDs, err := parseReactionIDs(attrs.MotorReactionIDs)
+		if err != nil {
+			return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "motor_reaction_ids contains invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/motor_reaction_ids"},
+			}})
+		}
+		existing.MotorReactions = make([]medicine.MotorReaction, 0, len(reactionIDs))
+		for i := range reactionIDs {
+			existing.MotorReactions = append(existing.MotorReactions, medicine.MotorReaction{ID: reactionIDs[i]})
+		}
+	}
+	if attrs.IsActive != nil {
+		existing.IsActive = *attrs.IsActive
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, medicineResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, medicineResource(existing))
+}
+
+// DeleteMedicine godoc
+// @Summary Delete medicine
+// @Tags OPC - Medicine
+// @Produce json
+// @Param uuid path string true "Medicine UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/medicine/delete/{uuid} [delete]
+func (h *MedicineHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeMedicineErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "medicine not found"}})
+		}
+		if _, ok := apperrors.AsDeleteConflict(err); ok {
+			return writeMedicineErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{Status: "409", Title: "Conflict", Detail: "an internal error occurred"}})
+		}
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Delete failed", Detail: "an internal error occurred"}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "medicine_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListMedicine godoc
+// @Summary List medicine
+// @Description JSON:API list with pagination, filtering and sorting. Search covers name, note, pack, unit, and column. Sort values: name, -name, sortkey, -sortkey, note, -note, pack, -pack, unit, -unit, column, -column, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.
+// @Tags OPC - Medicine
+// @Produce json
+// @Param filter[search] query string false "Search by name/note/pack/unit/column"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.MedicineListResponse
+// @Router /api/v1/medicine/get-all [get]
+func (h *MedicineHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("filter[name]")
+	}
+	if filter == "" {
+		filter = c.Query("search")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	data := make([]dto.MedicineResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, medicineResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListMedicineDatatable godoc
+// @Summary List medicine (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags OPC - Medicine
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.MedicineDataTableResponse
+// @Router /api/v1/medicine/get-all/dt [get]
+func (h *MedicineHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	data := make([]dto.MedicineResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, medicineResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func medicineResource(row *medicine.Medicine) dto.MedicineResource {
+	var groupResource *dto.MedicineGroupResource
+	var motorReactionResource *dto.MotorReactionResource
+	if row.MedicineGroup != nil {
+		g := groupResourceFromMedicine(row.MedicineGroup)
+		groupResource = &g
+	}
+	if row.MotorReaction != nil {
+		r := reactionResourceFromMedicine(row.MotorReaction)
+		motorReactionResource = &r
+	}
+	motorReactions := make([]dto.MotorReactionResource, 0, len(row.MotorReactions))
+	for i := range row.MotorReactions {
+		motorReactions = append(motorReactions, reactionResourceFromMedicine(&row.MotorReactions[i]))
+	}
+	motorReactionIDs := make([]string, 0, len(row.MotorReactions))
+	for i := range row.MotorReactions {
+		motorReactionIDs = append(motorReactionIDs, idString(row.MotorReactions[i].ID))
+	}
+	if len(motorReactionIDs) == 0 && len(row.MotorReactionID) > 0 {
+		motorReactionIDs = []string{idString(row.MotorReactionID)}
+	}
+	return dto.MedicineResource{
+		Type: "medicine",
+		ID:   idString(row.ID),
+		Attributes: dto.MedicineAttributes{
+			Name:             row.Name,
+			SortKey:          cloneIntPointer(row.SortKey),
+			Note:             row.Note,
+			Pack:             row.Pack,
+			Unit:             row.Unit,
+			Column:           row.Column,
+			MedicineGroupID:  idString(row.MedicineGroupID),
+			MotorReactionID:  idString(row.MotorReactionID),
+			MotorReactionIDs: motorReactionIDs,
+			MedicineGroup:    groupResource,
+			MotorReaction:    motorReactionResource,
+			MotorReactions:   motorReactions,
+			IsActive:         row.IsActive,
+			CreatedAt:        row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:        uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:        row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:        uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt:        timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:        uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func parseReactionIDs(in []string) ([][]byte, error) {
+	ids := make([][]byte, 0, len(in))
+	seen := make(map[string]struct{}, len(in))
+	for i := range in {
+		raw := strings.TrimSpace(in[i])
+		if raw == "" {
+			continue
+		}
+		id, err := uuidv7.ParseString(raw)
+		if err != nil {
+			return nil, err
+		}
+		key := string(id)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		ids = append(ids, id)
+	}
+	return ids, nil
+}
+
+func reactionResourceFromMedicine(row *medicine.MotorReaction) dto.MotorReactionResource {
+	return dto.MotorReactionResource{
+		Type: "motor_reaction",
+		ID:   idString(row.ID),
+		Attributes: dto.MotorReactionAttributes{
+			Name:      row.Name,
+			Score:     row.Score,
+			CreatedAt: row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy: uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt: row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy: uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt: timeStringOrEmpty(row.DeletedAt),
+			DeletedBy: uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func groupResourceFromMedicine(row *medicine.MedicineGroup) dto.MedicineGroupResource {
+	return dto.MedicineGroupResource{
+		Type: "medicine_group",
+		ID:   idString(row.ID),
+		Attributes: dto.MedicineGroupAttributes{
+			Name:      row.Name,
+			CreatedAt: row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy: uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt: row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy: uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt: timeStringOrEmpty(row.DeletedAt),
+			DeletedBy: uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func intOrDefault64(v *int64, def int64) int64 {
+	if v == nil {
+		return def
+	}
+	return *v
+}
+
+type medicineGroupService interface {
+	CreateGroup(context.Context, *medicine.MedicineGroup) error
+	UpdateGroup(context.Context, *medicine.MedicineGroup) error
+	DeleteGroup(context.Context, []byte, []byte) error
+	GetGroupByID(context.Context, []byte) (*medicine.MedicineGroup, error)
+	ListGroups(context.Context, string, string, int, int) ([]medicine.MedicineGroup, int64, error)
+}
+
+type motorReactionService interface {
+	CreateReaction(context.Context, *medicine.MotorReaction) error
+	UpdateReaction(context.Context, *medicine.MotorReaction) error
+	DeleteReaction(context.Context, []byte, []byte) error
+	GetReactionByID(context.Context, []byte) (*medicine.MotorReaction, error)
+	ListReactions(context.Context, string, string, int, int) ([]medicine.MotorReaction, int64, error)
+}
+
+func (h *MedicineHandler) groupSvc() (medicineGroupService, error) {
+	svc, ok := h.svc.(medicineGroupService)
+	if !ok {
+		return nil, fiber.NewError(fiber.StatusServiceUnavailable, "medicine group service is not configured")
+	}
+	return svc, nil
+}
+
+func (h *MedicineHandler) reactionSvc() (motorReactionService, error) {
+	svc, ok := h.svc.(motorReactionService)
+	if !ok {
+		return nil, fiber.NewError(fiber.StatusServiceUnavailable, "motor reaction service is not configured")
+	}
+	return svc, nil
+}
+
+// CreateMedicineGroup godoc
+// @Summary Create medicine group
+// @Description Create a medicine group row.
+// @Tags OPC - Medicine Group
+// @Accept json
+// @Produce json
+// @Param request body dto.MedicineGroupCreateRequest true "JSON:API medicine group create request"
+// @Success 201 {object} dto.MedicineGroupResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/medicine-group/create [post]
+func (h *MedicineHandler) CreateGroup(c *fiber.Ctx) error {
+	var req dto.MedicineGroupCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	name := strings.TrimSpace(req.Data.Attributes.Name)
+	if name == "" {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "name is required", Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"}}})
+	}
+	svc, err := h.groupSvc()
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Service unavailable", Detail: "an internal error occurred"}})
+	}
+	row := &medicine.MedicineGroup{Name: name, CreatedBy: actorUserID(c), UpdatedBy: actorUserID(c)}
+	if err := svc.CreateGroup(c.UserContext(), row); err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Create failed", Detail: "an internal error occurred"}})
+	}
+	created, _ := svc.GetGroupByID(c.UserContext(), row.ID)
+	if created != nil {
+		return response.Write(c, fiber.StatusCreated, groupResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, groupResource(row))
+}
+
+// UpdateMedicineGroup godoc
+// @Summary Update medicine group (partial)
+// @Description Patch medicine group by ID.
+// @Tags OPC - Medicine Group
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Medicine Group UUID (UUIDv7)"
+// @Param request body dto.MedicineGroupUpdateRequest true "JSON:API medicine group update request"
+// @Success 200 {object} dto.MedicineGroupResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/medicine-group/update/{uuid} [patch]
+func (h *MedicineHandler) UpdateGroup(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "uuid is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"}}})
+	}
+	var req dto.MedicineGroupUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	svc, svcErr := h.groupSvc()
+	if svcErr != nil {
+		return writeMedicineErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Service unavailable", Detail: svcErr.Error()}})
+	}
+	row, err := svc.GetGroupByID(c.UserContext(), id)
+	if err != nil || row == nil {
+		return writeMedicineErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "medicine group not found"}})
+	}
+	if req.Data.Attributes.Name != nil {
+		name := strings.TrimSpace(*req.Data.Attributes.Name)
+		if name == "" {
+			return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "name cannot be empty", Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"}}})
+		}
+		row.Name = name
+	}
+	row.UpdatedBy = actorUserID(c)
+	if err := svc.UpdateGroup(c.UserContext(), row); err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Update failed", Detail: "an internal error occurred"}})
+	}
+	updated, _ := svc.GetGroupByID(c.UserContext(), row.ID)
+	if updated != nil {
+		return response.Write(c, fiber.StatusOK, groupResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, groupResource(row))
+}
+
+// DeleteMedicineGroup godoc
+// @Summary Delete medicine group
+// @Tags OPC - Medicine Group
+// @Produce json
+// @Param uuid path string true "Medicine Group UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/medicine-group/delete/{uuid} [delete]
+func (h *MedicineHandler) DeleteGroup(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "uuid is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"}}})
+	}
+	svc, svcErr := h.groupSvc()
+	if svcErr != nil {
+		return writeMedicineErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Service unavailable", Detail: svcErr.Error()}})
+	}
+	if err := svc.DeleteGroup(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeMedicineErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "medicine group not found"}})
+		}
+		if _, ok := apperrors.AsDeleteConflict(err); ok {
+			return writeMedicineErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{Status: "409", Title: "Conflict", Detail: "an internal error occurred"}})
+		}
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Delete failed", Detail: "an internal error occurred"}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "medicine_group_delete", Attributes: map[string]any{"deleted": true}})
+}
+
+// ListMedicineGroups godoc
+// @Summary List medicine groups
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: name, -name, created_at, -created_at, updated_at, -updated_at.
+// @Tags OPC - Medicine Group
+// @Produce json
+// @Param filter[search] query string false "Search by group name"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.MedicineGroupListResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/medicine-group/get-all [get]
+func (h *MedicineHandler) ListGroups(c *fiber.Ctx) error {
+	svc, err := h.groupSvc()
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Service unavailable", Detail: "an internal error occurred"}})
+	}
+	pageNumber := parseIntDefault(c.Query("page[number]"), parseIntDefault(c.Query("page"), 1))
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), parseIntDefault(c.Query("limit"), parseIntDefault(c.Query("size"), 20)))
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("search")
+	}
+	rows, total, listErr := svc.ListGroups(c.UserContext(), filter, c.Query("sort"), pageSize, (pageNumber-1)*pageSize)
+	if listErr != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "List failed", Detail: listErr.Error()}})
+	}
+	data := make([]dto.MedicineGroupResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, groupResource(&rows[i]))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{"total": total})
+}
+
+// ListMedicineGroupsDatatable godoc
+// @Summary List medicine groups (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags OPC - Medicine Group
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.MedicineGroupDataTableResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/medicine-group/get-all/dt [get]
+func (h *MedicineHandler) ListGroupsDatatable(c *fiber.Ctx) error {
+	svc, err := h.groupSvc()
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Service unavailable", Detail: "an internal error occurred"}})
+	}
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	size := parseIntDefault(c.Query("limit"), parseIntDefault(c.Query("size"), 20))
+	if size < 1 {
+		size = 20
+	}
+	if size > 100 {
+		size = 100
+	}
+	rows, total, listErr := svc.ListGroups(c.UserContext(), c.Query("search"), "", size, (pageNumber-1)*size)
+	if listErr != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "List failed", Detail: listErr.Error()}})
+	}
+	data := make([]dto.MedicineGroupResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, groupResource(&rows[i]))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{"draw": parseIntDefault(c.Query("draw"), pageNumber), "records_total": total, "records_filtered": total})
+}
+
+// CreateMotorReaction godoc
+// @Summary Create motor reaction
+// @Description Create a motor reaction row.
+// @Tags OPC - Motor Reaction
+// @Accept json
+// @Produce json
+// @Param request body dto.MotorReactionCreateRequest true "JSON:API motor reaction create request"
+// @Success 201 {object} dto.MotorReactionResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/motor-reaction/create [post]
+func (h *MedicineHandler) CreateReaction(c *fiber.Ctx) error {
+	var req dto.MotorReactionCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	name := strings.TrimSpace(req.Data.Attributes.Name)
+	if name == "" {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "name is required", Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"}}})
+	}
+	svc, err := h.reactionSvc()
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Service unavailable", Detail: "an internal error occurred"}})
+	}
+	row := &medicine.MotorReaction{Name: name, Score: req.Data.Attributes.Score, CreatedBy: actorUserID(c), UpdatedBy: actorUserID(c)}
+	if err := svc.CreateReaction(c.UserContext(), row); err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Create failed", Detail: "an internal error occurred"}})
+	}
+	created, _ := svc.GetReactionByID(c.UserContext(), row.ID)
+	if created != nil {
+		return response.Write(c, fiber.StatusCreated, reactionResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, reactionResource(row))
+}
+
+// UpdateMotorReaction godoc
+// @Summary Update motor reaction (partial)
+// @Description Patch motor reaction by ID.
+// @Tags OPC - Motor Reaction
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Motor Reaction UUID (UUIDv7)"
+// @Param request body dto.MotorReactionUpdateRequest true "JSON:API motor reaction update request"
+// @Success 200 {object} dto.MotorReactionResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/motor-reaction/update/{uuid} [patch]
+func (h *MedicineHandler) UpdateReaction(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "uuid is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"}}})
+	}
+	var req dto.MotorReactionUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: "an internal error occurred"}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	svc, svcErr := h.reactionSvc()
+	if svcErr != nil {
+		return writeMedicineErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Service unavailable", Detail: svcErr.Error()}})
+	}
+	row, err := svc.GetReactionByID(c.UserContext(), id)
+	if err != nil || row == nil {
+		return writeMedicineErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "motor reaction not found"}})
+	}
+	if req.Data.Attributes.Name != nil {
+		name := strings.TrimSpace(*req.Data.Attributes.Name)
+		if name == "" {
+			return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "name cannot be empty", Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"}}})
+		}
+		row.Name = name
+	}
+	if req.Data.Attributes.Score.Set {
+		if req.Data.Attributes.Score.Valid {
+			score := req.Data.Attributes.Score.Value
+			row.Score = &score
+		} else {
+			row.Score = nil
+		}
+	}
+	row.UpdatedBy = actorUserID(c)
+	if err := svc.UpdateReaction(c.UserContext(), row); err != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Update failed", Detail: "an internal error occurred"}})
+	}
+	updated, _ := svc.GetReactionByID(c.UserContext(), row.ID)
+	if updated != nil {
+		return response.Write(c, fiber.StatusOK, reactionResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, reactionResource(row))
+}
+
+// DeleteMotorReaction godoc
+// @Summary Delete motor reaction
+// @Tags OPC - Motor Reaction
+// @Produce json
+// @Param uuid path string true "Motor Reaction UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/motor-reaction/delete/{uuid} [delete]
+func (h *MedicineHandler) DeleteReaction(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(c.Params("uuid"))
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "uuid is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"}}})
+	}
+	svc, svcErr := h.reactionSvc()
+	if svcErr != nil {
+		return writeMedicineErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Service unavailable", Detail: svcErr.Error()}})
+	}
+	if err := svc.DeleteReaction(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeMedicineErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "motor reaction not found"}})
+		}
+		if _, ok := apperrors.AsDeleteConflict(err); ok {
+			return writeMedicineErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{Status: "409", Title: "Conflict", Detail: "an internal error occurred"}})
+		}
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Delete failed", Detail: "an internal error occurred"}})
+	}
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{Type: "motor_reaction_delete", Attributes: map[string]any{"deleted": true}})
+}
+
+// ListMotorReactions godoc
+// @Summary List motor reactions
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: name, -name, score, -score, created_at, -created_at, updated_at, -updated_at.
+// @Tags OPC - Motor Reaction
+// @Produce json
+// @Param filter[search] query string false "Search by reaction name or score"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.MotorReactionListResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/motor-reaction/get-all [get]
+func (h *MedicineHandler) ListReactions(c *fiber.Ctx) error {
+	svc, err := h.reactionSvc()
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Service unavailable", Detail: "an internal error occurred"}})
+	}
+	pageNumber := parseIntDefault(c.Query("page[number]"), parseIntDefault(c.Query("page"), 1))
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), parseIntDefault(c.Query("limit"), parseIntDefault(c.Query("size"), 20)))
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("search")
+	}
+	rows, total, listErr := svc.ListReactions(c.UserContext(), filter, c.Query("sort"), pageSize, (pageNumber-1)*pageSize)
+	if listErr != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "List failed", Detail: listErr.Error()}})
+	}
+	data := make([]dto.MotorReactionResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, reactionResource(&rows[i]))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{"total": total})
+}
+
+// ListMotorReactionsDatatable godoc
+// @Summary List motor reactions (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags OPC - Motor Reaction
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.MotorReactionDataTableResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 503 {object} dto.ErrorResponse
+// @Router /api/v1/motor-reaction/get-all/dt [get]
+func (h *MedicineHandler) ListReactionsDatatable(c *fiber.Ctx) error {
+	svc, err := h.reactionSvc()
+	if err != nil {
+		return writeMedicineErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Service unavailable", Detail: "an internal error occurred"}})
+	}
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	size := parseIntDefault(c.Query("limit"), parseIntDefault(c.Query("size"), 20))
+	if size < 1 {
+		size = 20
+	}
+	if size > 100 {
+		size = 100
+	}
+	rows, total, listErr := svc.ListReactions(c.UserContext(), c.Query("search"), "", size, (pageNumber-1)*size)
+	if listErr != nil {
+		return writeMedicineErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "List failed", Detail: listErr.Error()}})
+	}
+	data := make([]dto.MotorReactionResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, reactionResource(&rows[i]))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{"draw": parseIntDefault(c.Query("draw"), pageNumber), "records_total": total, "records_filtered": total})
+}
+
+func groupResource(row *medicine.MedicineGroup) dto.MedicineGroupResource {
+	return dto.MedicineGroupResource{
+		Type: "medicine_group",
+		ID:   idString(row.ID),
+		Attributes: dto.MedicineGroupAttributes{
+			Name:      row.Name,
+			CreatedAt: row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy: uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt: row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy: uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt: timeStringOrEmpty(row.DeletedAt),
+			DeletedBy: uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func reactionResource(row *medicine.MotorReaction) dto.MotorReactionResource {
+	return dto.MotorReactionResource{
+		Type: "motor_reaction",
+		ID:   idString(row.ID),
+		Attributes: dto.MotorReactionAttributes{
+			Name:      row.Name,
+			Score:     row.Score,
+			CreatedAt: row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy: uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt: row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy: uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt: timeStringOrEmpty(row.DeletedAt),
+			DeletedBy: uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func writeMedicineErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	return response.WriteErrors(c, status, apperrorsx.EnrichErrorObjects(status, errs))
+}
+
+func inferMedicineErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		if strings.Contains(lowerDetail, "group") || strings.Contains(lowerDetail, "reaction") {
+			return apperrorsx.CodeDataNotFound, apperrorsx.ErrDataNotFound.ErrorCode
+		}
+		return apperrorsx.CodeMedicineNotFound, apperrorsx.ErrMedicineNotFound.ErrorCode
+	case fiber.StatusConflict:
+		return apperrorsx.CodeMedicineRelationDelete, apperrorsx.ErrMedicineRelationDelete.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid"):
+			return apperrorsx.CodeMedicineInvalidUUID, apperrorsx.ErrMedicineInvalidUUID.ErrorCode
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.CodeMedicineIDRequired, apperrorsx.ErrMedicineIDRequired.ErrorCode
+		case strings.Contains(lowerDetail, "id does not match"):
+			return apperrorsx.CodeMedicineIDMismatch, apperrorsx.ErrMedicineIDMismatch.ErrorCode
+		case strings.Contains(lowerDetail, "at least one attribute"):
+			return apperrorsx.CodeMedicineAttributesRequired, apperrorsx.ErrMedicineAttributesRequired.ErrorCode
+		case strings.Contains(lowerDetail, "name is required"), strings.Contains(lowerDetail, "name cannot be empty"):
+			return apperrorsx.CodeMedicineNameRequired, apperrorsx.ErrMedicineNameRequired.ErrorCode
+		case strings.Contains(lowerDetail, "medicine_group_id is invalid"):
+			return apperrorsx.CodeMedicineGroupIDInvalid, apperrorsx.ErrMedicineGroupIDInvalid.ErrorCode
+		case strings.Contains(lowerDetail, "motor_reaction_id is invalid"):
+			return apperrorsx.CodeMedicineMotorReactionIDInvalid, apperrorsx.ErrMedicineMotorReactionIDInvalid.ErrorCode
+		case strings.Contains(lowerDetail, "motor_reaction_ids"):
+			return apperrorsx.CodeMedicineMotorReactionIDsInvalid, apperrorsx.ErrMedicineMotorReactionIDsInvalid.ErrorCode
+		default:
+			return apperrorsx.CodeMedicineInvalidPayload, apperrorsx.ErrMedicineInvalidPayload.ErrorCode
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.CodeMedicineInvalidJSON, apperrorsx.ErrMedicineInvalidJSON.ErrorCode
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.CodeMedicineCreateFailed, apperrorsx.ErrMedicineCreateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.CodeMedicineUpdateFailed, apperrorsx.ErrMedicineUpdateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.CodeMedicineDeleteFailed, apperrorsx.ErrMedicineDeleteFailed.ErrorCode
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.CodeMedicineListFailed, apperrorsx.ErrMedicineListFailed.ErrorCode
+		default:
+			return apperrorsx.CodeMedicineInvalidPayload, apperrorsx.ErrMedicineInvalidPayload.ErrorCode
+		}
+	case fiber.StatusServiceUnavailable:
+		return apperrorsx.CodeBusinessRuleFailed, apperrorsx.ErrBusinessRuleFailed.ErrorCode
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
diff --git a/internal/transport/http/handlers/medicine_handler_test.go b/internal/transport/http/handlers/medicine_handler_test.go
new file mode 100644
index 0000000..1f06ed8
--- /dev/null
+++ b/internal/transport/http/handlers/medicine_handler_test.go
@@ -0,0 +1,900 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/medicine"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type memMedicineRepo struct {
+	rows         map[string]*medicine.Medicine
+	groupRows    map[string]*medicine.MedicineGroup
+	reactionRows map[string]*medicine.MotorReaction
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+
+	listRows  []medicine.Medicine
+	listTotal int64
+
+	getByIDFn func(id []byte, call int) (*medicine.Medicine, error)
+	getCalls  int
+
+	lastCreate     *medicine.Medicine
+	lastUpdate     *medicine.Medicine
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+}
+
+func newMemMedicineRepo() *memMedicineRepo {
+	return &memMedicineRepo{
+		rows:         map[string]*medicine.Medicine{},
+		groupRows:    map[string]*medicine.MedicineGroup{},
+		reactionRows: map[string]*medicine.MotorReaction{},
+	}
+}
+
+func (r *memMedicineRepo) Create(_ context.Context, row *medicine.Medicine) error {
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.rows[string(row.ID)] = row
+	r.lastCreate = row
+	return nil
+}
+
+func (r *memMedicineRepo) Update(_ context.Context, row *medicine.Medicine) error {
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	r.rows[string(row.ID)] = row
+	r.lastUpdate = row
+	return nil
+}
+
+func (r *memMedicineRepo) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	r.lastDeleteID = append([]byte(nil), id...)
+	r.lastDeleteBy = append([]byte(nil), deletedBy...)
+	delete(r.rows, string(id))
+	return nil
+}
+
+func (r *memMedicineRepo) GetByID(_ context.Context, id []byte) (*medicine.Medicine, error) {
+	r.getCalls++
+	if r.getByIDFn != nil {
+		return r.getByIDFn(id, r.getCalls)
+	}
+	if r.getByIDErr != nil {
+		return nil, r.getByIDErr
+	}
+	return r.rows[string(id)], nil
+}
+
+func (r *memMedicineRepo) List(_ context.Context, filter, sort string, limit, offset int) ([]medicine.Medicine, int64, error) {
+	r.lastListFilter = filter
+	r.lastListSort = sort
+	r.lastListLimit = limit
+	r.lastListOffset = offset
+	if r.listErr != nil {
+		return nil, 0, r.listErr
+	}
+	return r.listRows, r.listTotal, nil
+}
+
+func (r *memMedicineRepo) CreateGroup(_ context.Context, row *medicine.MedicineGroup) error {
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.groupRows[string(row.ID)] = row
+	return nil
+}
+
+func (r *memMedicineRepo) UpdateGroup(_ context.Context, row *medicine.MedicineGroup) error {
+	r.groupRows[string(row.ID)] = row
+	return nil
+}
+
+func (r *memMedicineRepo) DeleteGroup(_ context.Context, id []byte, _ []byte) error {
+	delete(r.groupRows, string(id))
+	return nil
+}
+
+func (r *memMedicineRepo) GetGroupByID(_ context.Context, id []byte) (*medicine.MedicineGroup, error) {
+	return r.groupRows[string(id)], nil
+}
+
+func (r *memMedicineRepo) ListGroups(_ context.Context, _ string, _ string, _ int, _ int) ([]medicine.MedicineGroup, int64, error) {
+	out := make([]medicine.MedicineGroup, 0, len(r.groupRows))
+	for _, v := range r.groupRows {
+		out = append(out, *v)
+	}
+	return out, int64(len(out)), nil
+}
+
+func (r *memMedicineRepo) CreateReaction(_ context.Context, row *medicine.MotorReaction) error {
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.reactionRows[string(row.ID)] = row
+	return nil
+}
+
+func (r *memMedicineRepo) UpdateReaction(_ context.Context, row *medicine.MotorReaction) error {
+	r.reactionRows[string(row.ID)] = row
+	return nil
+}
+
+func (r *memMedicineRepo) DeleteReaction(_ context.Context, id []byte, _ []byte) error {
+	delete(r.reactionRows, string(id))
+	return nil
+}
+
+func (r *memMedicineRepo) GetReactionByID(_ context.Context, id []byte) (*medicine.MotorReaction, error) {
+	return r.reactionRows[string(id)], nil
+}
+
+func (r *memMedicineRepo) ListReactions(_ context.Context, _ string, _ string, _ int, _ int) ([]medicine.MotorReaction, int64, error) {
+	out := make([]medicine.MotorReaction, 0, len(r.reactionRows))
+	for _, v := range r.reactionRows {
+		out = append(out, *v)
+	}
+	return out, int64(len(out)), nil
+}
+
+func newMedicineTestApp(h *MedicineHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", actor)
+		}
+		return c.Next()
+	})
+	app.Post("/api/v1/medicine/create", h.Create)
+	app.Patch("/api/v1/medicine/update/:uuid", h.Update)
+	app.Delete("/api/v1/medicine/delete/:uuid", h.Delete)
+	app.Get("/api/v1/medicine/get-all", h.List)
+	app.Get("/api/v1/medicine/get-all/dt", h.ListDatatable)
+	app.Post("/api/v1/medicine-group/create", h.CreateGroup)
+	app.Patch("/api/v1/medicine-group/update/:uuid", h.UpdateGroup)
+	app.Delete("/api/v1/medicine-group/delete/:uuid", h.DeleteGroup)
+	app.Get("/api/v1/medicine-group/get-all", h.ListGroups)
+	app.Get("/api/v1/medicine-group/get-all/dt", h.ListGroupsDatatable)
+	app.Post("/api/v1/motor-reaction/create", h.CreateReaction)
+	app.Patch("/api/v1/motor-reaction/update/:uuid", h.UpdateReaction)
+	app.Delete("/api/v1/motor-reaction/delete/:uuid", h.DeleteReaction)
+	app.Get("/api/v1/motor-reaction/get-all", h.ListReactions)
+	app.Get("/api/v1/motor-reaction/get-all/dt", h.ListReactionsDatatable)
+	return app
+}
+
+func doJSONRequestMedicine(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDStringMedicine(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func mustParseUUIDMedicine(t *testing.T, raw string) []byte {
+	t.Helper()
+	id, err := uuidv7.ParseString(raw)
+	if err != nil {
+		t.Fatalf("parse uuid: %v", err)
+	}
+	return id
+}
+
+func TestNewMedicineHandler(t *testing.T) {
+	h := NewMedicineHandler(service.NewMedicineService(newMemMedicineRepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+func TestMedicineHandlerCreate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPost, "/api/v1/medicine/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPost, "/api/v1/medicine/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"medicine","attributes":{"name":"  ","pack":"500mg","column":2}}}`)
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPost, "/api/v1/medicine/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		repo.createErr = errors.New("create failed")
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"medicine","attributes":{"name":"Paracetamol","pack":"500mg","column":2}}}`)
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPost, "/api/v1/medicine/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		actor := uuidv7.MustBytes()
+		app := newMedicineTestApp(h, actor)
+
+		body := []byte(`{"data":{"type":"medicine","attributes":{"name":"Paracetamol","note":"Main stock","pack":"500mg","unit":"tablet","column":2,"is_active":false}}}`)
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPost, "/api/v1/medicine/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil || repo.lastCreate.Name != "Paracetamol" || repo.lastCreate.Note != "Main stock" || repo.lastCreate.Pack != "500mg" || repo.lastCreate.Unit != "tablet" || repo.lastCreate.Column != 2 {
+			t.Fatalf("expected created row values")
+		}
+		if repo.lastCreate.IsActive {
+			t.Fatalf("expected is_active false")
+		}
+		if string(repo.lastCreate.CreatedBy) != string(actor) || string(repo.lastCreate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected created_by and updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback and default column", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		repo.getByIDFn = func(_ []byte, call int) (*medicine.Medicine, error) {
+			if call > 0 {
+				return nil, errors.New("lookup failed")
+			}
+			return nil, nil
+		}
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"medicine","attributes":{"name":"Ibuprofen","pack":"200mg"}}}`)
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPost, "/api/v1/medicine/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil || repo.lastCreate.Column != 0 {
+			t.Fatalf("expected default column 0")
+		}
+	})
+
+	t.Run("success without sortkey", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"medicine","attributes":{"name":"Ibuprofen","pack":"200mg","column":1}}}`)
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPost, "/api/v1/medicine/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected create called")
+		}
+	})
+}
+
+func TestMedicineHandlerUpdate(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		id := mustUUIDStringMedicine(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+id, []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		id := mustUUIDStringMedicine(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+id, []byte(`{"data":{"type":"x","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		id := mustUUIDStringMedicine(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+id, []byte(`{"data":{"type":"medicine","id":"","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		id := mustUUIDStringMedicine(t, uuidv7.MustBytes())
+		other := mustUUIDStringMedicine(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+id, []byte(`{"data":{"type":"medicine","id":"`+other+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no attributes", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		id := mustUUIDStringMedicine(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+id, []byte(`{"data":{"type":"medicine","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		id := mustUUIDStringMedicine(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+id, []byte(`{"data":{"type":"medicine","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &medicine.Medicine{ID: id, Name: "Old", Pack:"100mg", Column: 1}
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		idStr := mustUUIDStringMedicine(t, id)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+idStr, []byte(`{"data":{"type":"medicine","id":"`+idStr+`","attributes":{"name":"  "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &medicine.Medicine{ID: id, Name: "Old", Pack:"100mg", Column: 1}
+		repo.updateErr = errors.New("update failed")
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		idStr := mustUUIDStringMedicine(t, id)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+idStr, []byte(`{"data":{"type":"medicine","id":"`+idStr+`","attributes":{"name":"New"}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &medicine.Medicine{ID: id, Name: "Old", Pack: "100mg", Column: 1}
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		actor := uuidv7.MustBytes()
+		app := newMedicineTestApp(h, actor)
+		idStr := mustUUIDStringMedicine(t, id)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+idStr, []byte(`{"data":{"type":"medicine","id":"`+idStr+`","attributes":{"name":"New","pack":"250mg","column":3}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.Name != "New" || repo.lastUpdate.Pack != "250mg" || repo.lastUpdate.Column != 3 {
+			t.Fatalf("expected updated values")
+		}
+		if string(repo.lastUpdate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected updated_by from actor")
+		}
+	})
+
+	t.Run("success update note and is_active", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &medicine.Medicine{ID: id, Name: "Old", Pack: "100mg", Column: 1, Note: "Old", IsActive: true}
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		idStr := mustUUIDStringMedicine(t, id)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+idStr, []byte(`{"data":{"type":"medicine","id":"`+idStr+`","attributes":{"note":"Updated note","unit":"inhalation","is_active":false}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil {
+			t.Fatalf("expected update called")
+		}
+		if repo.lastUpdate.Note != "Updated note" {
+			t.Fatalf("expected note updated")
+		}
+		if repo.lastUpdate.Unit != "inhalation" {
+			t.Fatalf("expected unit updated")
+		}
+		if repo.lastUpdate.IsActive {
+			t.Fatalf("expected is_active false")
+		}
+	})
+
+	t.Run("success update is_active only", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &medicine.Medicine{ID: id, Name: "Old", Pack:"100mg", Column: 1}
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		idStr := mustUUIDStringMedicine(t, id)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+idStr, []byte(`{"data":{"type":"medicine","id":"`+idStr+`","attributes":{"is_active":false}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil {
+			t.Fatalf("expected update called")
+		}
+	})
+
+	t.Run("accept empty motor_reaction_id as clear value", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		id := uuidv7.MustBytes()
+		reactionID := uuidv7.MustBytes()
+		repo.rows[string(id)] = &medicine.Medicine{
+			ID:              id,
+			Name:            "Old",
+			Pack:           "100mg",
+			Column:          1,
+			MotorReactionID: append([]byte(nil), reactionID...),
+		}
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		idStr := mustUUIDStringMedicine(t, id)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+idStr, []byte(`{"data":{"type":"medicine","id":"`+idStr+`","attributes":{"motor_reaction_id":""}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil {
+			t.Fatalf("expected update called")
+		}
+		if repo.lastUpdate.MotorReactionID != nil {
+			t.Fatalf("expected motor_reaction_id cleared on empty string")
+		}
+	})
+
+	t.Run("success update medicine_group_id", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		id := uuidv7.MustBytes()
+		oldGroupID := uuidv7.MustBytes()
+		newGroupID := uuidv7.MustBytes()
+		repo.rows[string(id)] = &medicine.Medicine{
+			ID:              id,
+			Name:            "Old",
+			Pack:           "100mg",
+			Column:          1,
+			MedicineGroupID: append([]byte(nil), oldGroupID...),
+			MedicineGroup:   &medicine.MedicineGroup{ID: append([]byte(nil), oldGroupID...), Name: "Old Group"},
+		}
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		idStr := mustUUIDStringMedicine(t, id)
+		newGroupIDStr := mustUUIDStringMedicine(t, newGroupID)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+idStr, []byte(`{"data":{"type":"medicine","id":"`+idStr+`","attributes":{"medicine_group_id":"`+newGroupIDStr+`"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil {
+			t.Fatalf("expected update called")
+		}
+		if string(repo.lastUpdate.MedicineGroupID) != string(newGroupID) {
+			t.Fatalf("expected medicine_group_id updated")
+		}
+		if repo.lastUpdate.MedicineGroup != nil {
+			t.Fatalf("expected medicine_group association reset on FK update")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		id := uuidv7.MustBytes()
+		existing := &medicine.Medicine{ID: id, Name: "Old", Pack:"100mg", Column: 1}
+		repo.getByIDFn = func(_ []byte, call int) (*medicine.Medicine, error) {
+			if call == 1 {
+				return existing, nil
+			}
+			return nil, errors.New("second lookup failed")
+		}
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		idStr := mustUUIDStringMedicine(t, id)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine/update/"+idStr, []byte(`{"data":{"type":"medicine","id":"`+idStr+`","attributes":{"pack":"Only pack"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestMedicineHandlerDelete(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodDelete, "/api/v1/medicine/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete error", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		repo.deleteErr = errors.New("delete failed")
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+		id := mustUUIDStringMedicine(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodDelete, "/api/v1/medicine/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		actor := uuidv7.MustBytes()
+		app := newMedicineTestApp(h, actor)
+		id := uuidv7.MustBytes()
+		idStr := mustUUIDStringMedicine(t, id)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodDelete, "/api/v1/medicine/delete/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(repo.lastDeleteBy) != string(actor) {
+			t.Fatalf("expected deleted_by from actor")
+		}
+	})
+}
+
+func TestMedicineHandlerList(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodGet, "/api/v1/medicine/get-all", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with filter name fallback and clamp max", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		repo.listRows = []medicine.Medicine{{ID: uuidv7.MustBytes(), Name: "Paracetamol", Note: "Main stock", Pack:"500mg", Column: 2, IsActive: true, CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodGet, "/api/v1/medicine/get-all?filter[name]=abc&page[number]=0&page=0&page[size]=0&limit=101&sort=-name", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListSort != "name DESC" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q sort=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListSort, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success with search and clamp min", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		repo.listRows = []medicine.Medicine{}
+		repo.listTotal = 0
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodGet, "/api/v1/medicine/get-all?page=2&size=-1&search=needle", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "needle" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestMedicineHandlerListDatatable(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodGet, "/api/v1/medicine/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success clamp max and page floor", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		repo.listRows = []medicine.Medicine{{ID: uuidv7.MustBytes(), Name: "Paracetamol", Pack:"500mg", Column: 2, CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodGet, "/api/v1/medicine/get-all/dt?page=0&limit=0&size=101&draw=7&search=abc", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListLimit != 100 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success clamp min", func(t *testing.T) {
+		repo := newMemMedicineRepo()
+		repo.listRows = []medicine.Medicine{}
+		repo.listTotal = 0
+		h := NewMedicineHandler(service.NewMedicineService(repo))
+		app := newMedicineTestApp(h, nil)
+
+		resp, _ := doJSONRequestMedicine(t, app, http.MethodGet, "/api/v1/medicine/get-all/dt?page=2&limit=0&size=-1", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListLimit != 20 || repo.lastListOffset != 20 {
+			t.Fatalf("unexpected list params: limit=%d offset=%d", repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestMedicineHandler_GroupAndReactionEndpoints(t *testing.T) {
+	repo := newMemMedicineRepo()
+	h := NewMedicineHandler(service.NewMedicineService(repo))
+	app := newMedicineTestApp(h, uuidv7.MustBytes())
+
+	groupCreate := []byte(`{"data":{"type":"medicine_group_create","attributes":{"name":"Spritze","is_active":true}}}`)
+	resp, body := doJSONRequestMedicine(t, app, http.MethodPost, "/api/v1/medicine-group/create", groupCreate)
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201 group create, got %d body=%s", resp.StatusCode, string(body))
+	}
+	var groupID string
+	for _, g := range repo.groupRows {
+		groupID = mustUUIDStringMedicine(t, g.ID)
+		break
+	}
+	if groupID == "" {
+		t.Fatalf("expected group id")
+	}
+	resp, _ = doJSONRequestMedicine(t, app, http.MethodGet, "/api/v1/medicine-group/get-all", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 group list, got %d", resp.StatusCode)
+	}
+	resp, _ = doJSONRequestMedicine(t, app, http.MethodGet, "/api/v1/medicine-group/get-all/dt", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 group datatable, got %d", resp.StatusCode)
+	}
+	groupUpdate := []byte(`{"data":{"type":"medicine_group_update","id":"` + groupID + `","attributes":{"name":"Monitoring"}}}`)
+	resp, _ = doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/medicine-group/update/"+groupID, groupUpdate)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 group update, got %d", resp.StatusCode)
+	}
+	resp, _ = doJSONRequestMedicine(t, app, http.MethodDelete, "/api/v1/medicine-group/delete/"+groupID, nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 group delete, got %d", resp.StatusCode)
+	}
+
+	reactionCreate := []byte(`{"data":{"type":"motor_reaction_create","attributes":{"name":"gezielt auf Schmerzreiz","score":5,"is_active":true}}}`)
+	resp, body = doJSONRequestMedicine(t, app, http.MethodPost, "/api/v1/motor-reaction/create", reactionCreate)
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201 reaction create, got %d body=%s", resp.StatusCode, string(body))
+	}
+	var reactionID string
+	for _, r := range repo.reactionRows {
+		reactionID = mustUUIDStringMedicine(t, r.ID)
+		break
+	}
+	if reactionID == "" {
+		t.Fatalf("expected reaction id")
+	}
+	if stored := repo.reactionRows[string(mustParseUUIDMedicine(t, reactionID))]; stored == nil || stored.Score == nil || *stored.Score != 5 {
+		t.Fatalf("expected created reaction score=5")
+	}
+	resp, _ = doJSONRequestMedicine(t, app, http.MethodGet, "/api/v1/motor-reaction/get-all", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 reaction list, got %d", resp.StatusCode)
+	}
+	resp, _ = doJSONRequestMedicine(t, app, http.MethodGet, "/api/v1/motor-reaction/get-all/dt", nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 reaction datatable, got %d", resp.StatusCode)
+	}
+	reactionUpdate := []byte(`{"data":{"type":"motor_reaction_update","id":"` + reactionID + `","attributes":{"name":"keine Reaktion","score":1}}}`)
+	resp, _ = doJSONRequestMedicine(t, app, http.MethodPatch, "/api/v1/motor-reaction/update/"+reactionID, reactionUpdate)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 reaction update, got %d", resp.StatusCode)
+	}
+	if stored := repo.reactionRows[string(mustParseUUIDMedicine(t, reactionID))]; stored == nil || stored.Score == nil || *stored.Score != 1 {
+		t.Fatalf("expected updated reaction score=1")
+	}
+	resp, _ = doJSONRequestMedicine(t, app, http.MethodDelete, "/api/v1/motor-reaction/delete/"+reactionID, nil)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 reaction delete, got %d", resp.StatusCode)
+	}
+}
+
+func TestMedicineHandler_MotorReactionScoreNullable(t *testing.T) {
+	repo := newMemMedicineRepo()
+	svc := service.NewMedicineService(repo)
+	h := NewMedicineHandler(svc)
+	app := newMedicineTestApp(h, uuidv7.MustBytes())
+
+	t.Run("create score null", func(t *testing.T) {
+		resp, body := doJSONRequestMedicine(t, app, http.MethodPost, "/api/v1/motor-reaction/create", []byte(`{"data":{"type":"motor_reaction_create","attributes":{"name":"no score","score":null}}}`))
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d body=%s", resp.StatusCode, string(body))
+		}
+		for _, row := range repo.reactionRows {
+			if row.Name == "no score" {
+				if row.Score != nil {
+					t.Fatalf("expected score nil when payload score=null")
+				}
+				return
+			}
+		}
+		t.Fatalf("created reaction not found")
+	})
+
+	t.Run("create score zero", func(t *testing.T) {
+		resp, body := doJSONRequestMedicine(t, app, http.MethodPost, "/api/v1/motor-reaction/create", []byte(`{"data":{"type":"motor_reaction_create","attributes":{"name":"zero score","score":0}}}`))
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d body=%s", resp.StatusCode, string(body))
+		}
+		for _, row := range repo.reactionRows {
+			if row.Name == "zero score" {
+				if row.Score == nil || *row.Score != 0 {
+					t.Fatalf("expected score pointer with value 0")
+				}
+				return
+			}
+		}
+		t.Fatalf("created reaction not found")
+	})
+}
+
+func TestMedicineResource(t *testing.T) {
+	id := uuidv7.MustBytes()
+	createdBy := uuidv7.MustBytes()
+	updatedBy := uuidv7.MustBytes()
+	deletedBy := uuidv7.MustBytes()
+	now := time.Now().UTC().Truncate(time.Second)
+	deletedAt := now.Add(time.Hour)
+
+	row := &medicine.Medicine{
+		ID:        id,
+		Name:      "Paracetamol",
+		Note:      "Main stock",
+		Pack:      "500mg",
+		Unit:      "tablet",
+		Column:    2,
+		IsActive:  true,
+		CreatedAt: now,
+		CreatedBy: createdBy,
+		UpdatedAt: now,
+		UpdatedBy: updatedBy,
+		DeletedAt: &deletedAt,
+		DeletedBy: deletedBy,
+	}
+
+	res := medicineResource(row)
+	if res.Type != "medicine" {
+		t.Fatalf("unexpected type: %s", res.Type)
+	}
+	if res.Attributes.Note != "Main stock" || res.Attributes.Unit != "tablet" || !res.Attributes.IsActive {
+		t.Fatalf("expected note and is_active in resource")
+	}
+	if res.ID == "" || res.Attributes.CreatedBy == "" || res.Attributes.UpdatedBy == "" || res.Attributes.DeletedBy == "" {
+		t.Fatalf("expected UUID fields in resource")
+	}
+	if res.Attributes.Column != 2 {
+		t.Fatalf("expected column in resource")
+	}
+	if res.Attributes.CreatedAt == "" || res.Attributes.UpdatedAt == "" || res.Attributes.DeletedAt == "" {
+		t.Fatalf("expected time fields in resource")
+	}
+}
+
+func TestIntOrDefault64(t *testing.T) {
+	if got := intOrDefault64(nil, 99); got != 99 {
+		t.Fatalf("expected default for nil pointer")
+	}
+	v := int64(7)
+	if got := intOrDefault64(&v, 99); got != 7 {
+		t.Fatalf("expected pointer value when not nil")
+	}
+}
diff --git a/internal/transport/http/handlers/mission_handler.go b/internal/transport/http/handlers/mission_handler.go
new file mode 100644
index 0000000..1fc9336
--- /dev/null
+++ b/internal/transport/http/handlers/mission_handler.go
@@ -0,0 +1,956 @@
+package handlers
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	flightdata "wucher/internal/domain/flight_data"
+	"wucher/internal/domain/mission"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type MissionHandler struct {
+	svc           mission.Service
+	flightDataSvc flightdata.Service
+	fileManager   filemanager.Service
+	storage       fileManagerDownloadURLStorage
+	validate      *validators.Validator
+}
+
+func NewMissionHandler(svc mission.Service) *MissionHandler {
+	return &MissionHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+func (h *MissionHandler) WithFlightDataService(svc flightdata.Service) *MissionHandler {
+	h.flightDataSvc = svc
+	return h
+}
+
+func (h *MissionHandler) WithFileStorage(storage fileManagerDownloadURLStorage) *MissionHandler {
+	h.storage = storage
+	return h
+}
+
+func (h *MissionHandler) WithFileManagerService(svc filemanager.Service) *MissionHandler {
+	h.fileManager = svc
+	return h
+}
+
+func (h *MissionHandler) attachMissionFiles(ctx context.Context, missionID []byte, files []requestdto.MissionFileInput, actorID []byte) {
+	if len(files) == 0 || h.fileManager == nil {
+		return
+	}
+	folderID, err := ensureMissionFileFolderPath(ctx, h.fileManager, missionID, actorID)
+	if err != nil {
+		return
+	}
+	missionRefID := idString(missionID)
+	for i := range files {
+		uploadIntentRaw := strings.TrimSpace(files[i].UploadIntentUUID)
+		if uploadIntentRaw == "" {
+			continue
+		}
+		uploadIntentID, parseErr := uuidv7.ParseString(uploadIntentRaw)
+		if parseErr != nil {
+			continue
+		}
+		name := strings.TrimSpace(files[i].Name)
+		created, createErr := h.fileManager.CreateFileNodeFromUploadIntent(ctx, filemanager.CreateFileFromUploadIntentParams{
+			UploadIntentID: uploadIntentID,
+			FolderID:       folderID,
+			FolderProvided: true,
+			Name:           name,
+			ActorID:        actorID,
+		})
+		if createErr != nil {
+			if !errors.Is(createErr, filemanager.ErrDuplicateName) {
+				continue
+			}
+			existing, exErr := h.fileManager.GetFileByFolderAndName(ctx, folderID, strings.ToLower(name))
+			if exErr != nil || existing == nil {
+				continue
+			}
+			created = existing
+		}
+		if created == nil {
+			continue
+		}
+		attachParams := filemanager.CreateAttachmentParams{
+			FileID:    created.ID,
+			RefType:   "mission",
+			RefID:     missionRefID,
+			SortOrder: 0,
+			IsPrimary: false,
+			ActorID:   actorID,
+		}
+		// The file finishes processing (→ ready) asynchronously, shortly after
+		// the upload intent is finalized above. CreateAttachment rejects a
+		// not-yet-ready file, so wait briefly for readiness instead of silently
+		// dropping the attachment (bounded ~10s; processing is normally ~1-2s).
+		var attachment *filemanager.Attachment
+		var attachErr error
+		for attempt := 0; attempt < 40; attempt++ {
+			attachment, attachErr = h.fileManager.CreateAttachment(ctx, attachParams)
+			if attachErr == nil || !errors.Is(attachErr, filemanager.ErrFileNotReadyForAttachment) {
+				break
+			}
+			if ctx.Err() != nil {
+				break
+			}
+			time.Sleep(250 * time.Millisecond)
+		}
+		if attachErr != nil || attachment == nil {
+			continue
+		}
+		_ = h.svc.AttachFile(ctx, missionID, attachment.ID)
+	}
+}
+
+// CreateMission godoc
+// @Summary Create mission
+// @Description Create a mission and link it to a flight.
+// @Description `type` must be one of: `HEMS`, `CAT`, `SPO`, `NCO`.
+// @Description `subtype_id` is required when `type=HEMS` and must reference mission subcategory under `HEMS` category.
+// @Description `subtype_id` must be empty when `type` is not `HEMS`.
+// @Tags Flights - Mission
+// @Accept json
+// @Produce json
+// @Param request body requestdto.MissionCreateRequest true "JSON:API mission create request"
+// @Success 201 {object} responsedto.MissionResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 409 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/mission/create [post]
+func (h *MissionHandler) Create(c *fiber.Ctx) error {
+	var req requestdto.MissionCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidJSON, err.Error(), nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeMissionValidationErrors(c, errs)
+	}
+
+	flightID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.FlightID))
+	if err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidFlightUUID, mission.ErrorMessageInvalidFlightID, &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_id"})
+	}
+
+	var subtypeID []byte
+	subtypeRaw := strings.TrimSpace(req.Data.Attributes.SubtypeID)
+	if subtypeRaw != "" {
+		subtypeID, err = uuidv7.ParseString(subtypeRaw)
+		if err != nil {
+			return writeMissionError(c, apperrorsx.ErrMissionSubtypeInvalid, mission.ErrorMessageSubtypeInvalid, &jsonapi.ErrorSource{Pointer: "/data/attributes/subtype_id"})
+		}
+	}
+
+	row := &mission.Mission{
+		FlightID:  flightID,
+		Type:      strings.ToUpper(strings.TrimSpace(req.Data.Attributes.Type)),
+		SubtypeID: subtypeID,
+		Note:      strings.TrimSpace(req.Data.Attributes.Note),
+		CreatedBy: actorUserID(c),
+		UpdatedBy: actorUserID(c),
+	}
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeMissionServiceError(c, err, "/data/attributes/flight_id")
+	}
+
+	h.attachMissionFiles(c.UserContext(), row.ID, req.Data.Attributes.Files, actorUserID(c))
+	if created, getErr := h.svc.GetByID(c.UserContext(), row.ID); getErr == nil && created != nil {
+		row = created
+	}
+
+	doc, err := h.missionDocument(c.UserContext(), row)
+	if err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionCreateFailed, err.Error(), nil)
+	}
+	return response.Write(c, fiber.StatusCreated, doc)
+}
+
+// CreateMissionType godoc
+// @Summary Create mission type
+// @Description Create a mission category master record for use in mission flow.
+// @Tags Flights - Mission
+// @Accept json
+// @Produce json
+// @Param request body requestdto.MissionTypeCreateRequest true "JSON:API mission type create request"
+// @Success 201 {object} responsedto.MissionTypeResource
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/mission-type/create [post]
+func (h *MissionHandler) CreateType(c *fiber.Ctx) error {
+	var req requestdto.MissionTypeCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidJSON, err.Error(), nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeMissionValidationErrors(c, errs)
+	}
+
+	row := &mission.MissionCategory{
+		CodeType: strings.ToUpper(strings.TrimSpace(req.Data.Attributes.CodeType)),
+		TypeName: strings.TrimSpace(req.Data.Attributes.TypeName),
+	}
+	if err := h.svc.CreateType(c.UserContext(), row); err != nil {
+		return writeMissionServiceError(c, err, "/data/attributes/code_type")
+	}
+
+	return response.Write(c, fiber.StatusCreated, missionTypeResource(row))
+}
+
+// UpdateMission godoc
+// @Summary Update mission
+// @Description Update mission type/subtype/note by mission ID, and optionally attach files already uploaded via `upload-mission-file`.
+// @Description `type` must be one of: `HEMS`, `CAT`, `SPO`, `NCO`.
+// @Description `subtype_id` is required when `type=HEMS` and must reference mission subcategory under `HEMS` category.
+// @Description `subtype_id` must be empty when `type` is not `HEMS`.
+// @Description `files[]` items reference an `upload_intent_uuid` (from `upload-mission-file`) and an optional display `name`.
+// @Tags Flights - Mission
+// @Accept json
+// @Produce json
+// @Param mission_id path string true "Mission ID (UUIDv7)"
+// @Param request body requestdto.MissionUpdateRequest true "JSON:API mission update request"
+// @Success 200 {object} responsedto.MissionResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/mission/update/{mission_id} [patch]
+func (h *MissionHandler) Update(c *fiber.Ctx) error {
+	missionRaw := strings.TrimSpace(c.Params("mission_id"))
+	missionID, err := uuidv7.ParseString(missionRaw)
+	if err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidMissionUUID, mission.ErrorMessageInvalidMissionID, &jsonapi.ErrorSource{Pointer: "/path/mission_id"})
+	}
+
+	var req requestdto.MissionUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidJSON, err.Error(), nil)
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeMissionValidationErrors(c, errs)
+	}
+
+	var subtypeID []byte
+	subtypeRaw := strings.TrimSpace(req.Data.Attributes.SubtypeID)
+	if subtypeRaw != "" {
+		subtypeID, err = uuidv7.ParseString(subtypeRaw)
+		if err != nil {
+			return writeMissionError(c, apperrorsx.ErrMissionSubtypeInvalid, mission.ErrorMessageSubtypeInvalid, &jsonapi.ErrorSource{Pointer: "/data/attributes/subtype_id"})
+		}
+	}
+
+	if err := h.svc.UpdateByID(
+		c.UserContext(),
+		missionID,
+		strings.ToUpper(strings.TrimSpace(req.Data.Attributes.Type)),
+		subtypeID,
+		strings.TrimSpace(req.Data.Attributes.Note),
+		actorUserID(c),
+	); err != nil {
+		return writeMissionServiceError(c, err, "/path/mission_id")
+	}
+
+	h.attachMissionFiles(c.UserContext(), missionID, req.Data.Attributes.Files, actorUserID(c))
+
+	row, err := h.svc.GetByID(c.UserContext(), missionID)
+	if err != nil {
+		return writeMissionServiceError(c, err, "/path/mission_id")
+	}
+	if row == nil {
+		return writeMissionError(c, apperrorsx.ErrMissionNotFound, mission.ErrorMessageNotFound, nil)
+	}
+	doc, buildErr := h.missionDocument(c.UserContext(), row)
+	if buildErr != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionUpdateFailed, buildErr.Error(), nil)
+	}
+	return response.Write(c, fiber.StatusOK, doc)
+}
+
+// RemoveFile godoc
+// @Summary Remove a file from a mission
+// @Description Detaches the file (by its attachment id) from the mission and deletes the attachment.
+// @Tags Flights - Mission
+// @Produce json
+// @Param mission_id path string true "Mission UUID"
+// @Param attachment_id path string true "Attachment UUID (the file's attachment_id)"
+// @Success 200 {object} responsedto.MissionResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/mission/file/{mission_id}/{attachment_id} [delete]
+func (h *MissionHandler) RemoveFile(c *fiber.Ctx) error {
+	missionID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("mission_id")))
+	if err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidMissionUUID, mission.ErrorMessageInvalidMissionID, &jsonapi.ErrorSource{Pointer: "/path/mission_id"})
+	}
+	attachmentID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("attachment_id")))
+	if err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidMissionUUID, "invalid attachment id", &jsonapi.ErrorSource{Pointer: "/path/attachment_id"})
+	}
+
+	if err := h.svc.DetachFile(c.UserContext(), missionID, attachmentID); err != nil {
+		return writeMissionServiceError(c, err, "/path/attachment_id")
+	}
+	if h.fileManager != nil {
+		// Best-effort: the junction row is already gone; an orphaned attachment
+		// is harmless and is cleaned up by lifecycle jobs.
+		_ = h.fileManager.DeleteAttachment(c.UserContext(), attachmentID)
+	}
+
+	row, err := h.svc.GetByID(c.UserContext(), missionID)
+	if err != nil {
+		return writeMissionServiceError(c, err, "/path/mission_id")
+	}
+	if row == nil {
+		return writeMissionError(c, apperrorsx.ErrMissionNotFound, mission.ErrorMessageNotFound, nil)
+	}
+	doc, buildErr := h.missionDocument(c.UserContext(), row)
+	if buildErr != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionUpdateFailed, buildErr.Error(), nil)
+	}
+	return response.Write(c, fiber.StatusOK, doc)
+}
+
+// DeleteMission godoc
+// @Summary Delete mission
+// @Description Soft delete mission by linked flight ID.
+// @Tags Flights - Mission
+// @Produce json
+// @Param flight_id path string true "Flight ID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/mission/delete/{flight_id} [delete]
+func (h *MissionHandler) Delete(c *fiber.Ctx) error {
+	flightRaw := strings.TrimSpace(c.Params("flight_id"))
+	flightID, err := uuidv7.ParseString(flightRaw)
+	if err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidFlightUUID, mission.ErrorMessageInvalidFlightID, &jsonapi.ErrorSource{Pointer: "/path/flight_id"})
+	}
+
+	if err := h.svc.DeleteByFlightID(c.UserContext(), flightID, actorUserID(c)); err != nil {
+		return writeMissionServiceError(c, err, "/path/flight_id")
+	}
+
+	return response.Write(c, fiber.StatusOK, dto.NewGenericDeleteResponse("mission_delete"))
+}
+
+// DeleteByIDMission godoc
+// @Summary Delete mission by mission ID
+// @Description Soft delete mission by its mission UUID. This also soft deletes flight data rows linked to the mission.
+// @Tags Flights - Mission
+// @Produce json
+// @Param mission_id path string true "Mission ID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/mission/delete-by-id/{mission_id} [delete]
+func (h *MissionHandler) DeleteByID(c *fiber.Ctx) error {
+	missionRaw := strings.TrimSpace(c.Params("mission_id"))
+	missionID, err := uuidv7.ParseString(missionRaw)
+	if err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidMissionUUID, mission.ErrorMessageInvalidMissionID, &jsonapi.ErrorSource{Pointer: "/path/mission_id"})
+	}
+
+	if err := h.svc.DeleteByID(c.UserContext(), missionID, actorUserID(c)); err != nil {
+		return writeMissionServiceError(c, err, "/path/mission_id")
+	}
+
+	return response.Write(c, fiber.StatusOK, dto.NewGenericDeleteResponse("mission_delete"))
+}
+
+// GetMissionByFlightID godoc
+// @Summary Get mission by flight ID
+// @Description Get mission detail by linked flight ID.
+// @Tags Flights - Mission
+// @Produce json
+// @Param flight_id path string true "Flight ID (UUIDv7)"
+// @Success 200 {object} responsedto.MissionResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/mission/get/{flight_id} [get]
+func (h *MissionHandler) GetByFlightID(c *fiber.Ctx) error {
+	flightRaw := strings.TrimSpace(c.Params("flight_id"))
+	if flightRaw == "" {
+		flightRaw = strings.TrimSpace(c.Params("flight_uuid"))
+	}
+	flightID, err := uuidv7.ParseString(flightRaw)
+	if err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidFlightUUID, mission.ErrorMessageInvalidFlight, &jsonapi.ErrorSource{Pointer: "/path/flight_id"})
+	}
+
+	rows, err := h.svc.ListByFlightID(c.UserContext(), flightID)
+	if err != nil {
+		return writeMissionServiceError(c, err, "/path/flight_id")
+	}
+	if len(rows) == 0 {
+		return writeMissionError(c, apperrorsx.ErrMissionNotFound, mission.ErrorMessageNotFound, nil)
+	}
+
+	doc, buildErr := h.missionDocuments(c.UserContext(), rows)
+	if buildErr != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionGetFailed, buildErr.Error(), nil)
+	}
+	return response.Write(c, fiber.StatusOK, doc)
+}
+
+// ListMissions godoc
+// @Summary List missions
+// @Description Supports `search`, `filter[search]`, `flight_id`, `sort`, `page[number]`, `page[size]`, `page`, `size`, and `limit`.
+// @Tags Flights - Mission
+// @Produce json
+// @Param search query string false "Search text"
+// @Param filter[search] query string false "Search text (JSON:API style)"
+// @Param flight_id query string false "Filter by flight UUID"
+// @Param flight_data_status query string false "Filter missions by flight data status: draft, in_progress, or completed"
+// @Param sort query string false "Sort field: type|-type|flight_date|-flight_date|created_at|-created_at|updated_at|-updated_at"
+// @Param page[number] query int false "Page number"
+// @Param page[size] query int false "Page size"
+// @Param page query int false "Page number (fallback)"
+// @Param size query int false "Page size (fallback)"
+// @Param limit query int false "Page size override"
+// @Success 200 {object} responsedto.MissionListResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/mission/get-all [get]
+func (h *MissionHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("search")
+	}
+	flightQuery := strings.TrimSpace(c.Query("flight_id"))
+	var flightID []byte
+	if flightQuery != "" {
+		parsedFlightID, err := uuidv7.ParseString(flightQuery)
+		if err != nil {
+			return writeMissionError(c, apperrorsx.ErrMissionInvalidFlightUUID, mission.ErrorMessageInvalidFlightID, &jsonapi.ErrorSource{Pointer: "/query/flight_id"})
+		}
+		flightID = parsedFlightID
+	}
+	flightDataStatus := strings.TrimSpace(c.Query("flight_data_status"))
+	if flightDataStatus != "" &&
+		flightDataStatus != mission.StatusDraft &&
+		flightDataStatus != mission.StatusInProgress &&
+		flightDataStatus != mission.StatusCompleted {
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidPayload, "flight_data_status must be one of: draft, in_progress, completed", &jsonapi.ErrorSource{Pointer: "/query/flight_data_status"})
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), sharedconst.MissionDefaultPageSize)
+	}
+	if pageSize > sharedconst.MissionMaxPageSize {
+		pageSize = sharedconst.MissionMaxPageSize
+	}
+	if pageSize < 1 {
+		pageSize = sharedconst.MissionDefaultPageSize
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, flightID, flightDataStatus, 0, 0)
+	if err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionListFailed, err.Error(), nil)
+	}
+
+	data := make([]responsedto.MissionResource, 0, len(rows))
+	for i := range rows {
+		resource, buildErr := h.missionResource(c.UserContext(), &rows[i])
+		if buildErr != nil {
+			return writeMissionError(c, apperrorsx.ErrMissionListFailed, buildErr.Error(), nil)
+		}
+		data = append(data, resource)
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	})
+}
+
+// ListMissionDatatable godoc
+// @Summary List missions (datatable)
+// @Description Supports `search`, `filter[search]`, `date_from`, `date_to`, `mission_type`, `pilot_id`, `helicopter_id`, `sort`, `start`, `length`, `draw`, `page[number]`, `page[size]`, `page`, `size`, and `limit`.
+// @Description `date_from` and `date_to` filter flights by their mission date range (`YYYY-MM-DD`).
+// @Description `mission_type` accepts `HEMS`, `CAT`, `SPO`, or `NCO`.
+// @Description `pilot_id` filters missions where the pilot is assigned on the linked flight roster.
+// @Description `helicopter_id` filters missions by the helicopter used in the linked flight takeover.
+// @Tags Flights - Mission
+// @Produce json
+// @Param search query string false "Search text"
+// @Param filter[search] query string false "Search text (JSON:API style)"
+// @Param flight_id query string false "Filter by linked flight UUID"
+// @Param date_from query string false "Mission date lower bound (YYYY-MM-DD)"
+// @Param date_to query string false "Mission date upper bound (YYYY-MM-DD)"
+// @Param mission_type query string false "Mission type: HEMS|CAT|SPO|NCO"
+// @Param pilot_id query string false "Pilot user UUID"
+// @Param helicopter_id query string false "Helicopter UUID"
+// @Param sort query string false "Sort field: type|-type|flight_date|-flight_date|created_at|-created_at|updated_at|-updated_at"
+// @Param start query int false "DataTables start index"
+// @Param length query int false "DataTables page size"
+// @Param draw query int false "DataTables draw counter"
+// @Param page[number] query int false "Page number"
+// @Param page[size] query int false "Page size"
+// @Param page query int false "Page number (fallback)"
+// @Param size query int false "Page size (fallback)"
+// @Param limit query int false "Page size override"
+// @Success 200 {object} responsedto.MissionDataTableResponse
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/mission/get-all/dt [get]
+func (h *MissionHandler) ListDatatable(c *fiber.Ctx) error {
+	filter, errObj := missionListFilterFromQuery(c)
+	if errObj != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidPayload, errObj.Detail, errObj.Source)
+	}
+
+	draw := parseIntDefault(c.Query("draw"), 1)
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), sharedconst.MissionDefaultPageSize)
+	}
+	if pageSize > sharedconst.MissionMaxPageSize {
+		pageSize = sharedconst.MissionMaxPageSize
+	}
+	if pageSize < 1 {
+		pageSize = sharedconst.MissionDefaultPageSize
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	if start := parseIntDefault(c.Query("start"), -1); start >= 0 && c.Query("length") != "" {
+		length := parseIntDefault(c.Query("length"), pageSize)
+		if length < 1 {
+			length = sharedconst.MissionDefaultPageSize
+		}
+		if length > sharedconst.MissionMaxPageSize {
+			length = sharedconst.MissionMaxPageSize
+		}
+		pageSize = length
+		pageNumber = (start / pageSize) + 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	rows, total, filtered, err := h.svc.ListDatatable(c.UserContext(), filter, pageSize, offset)
+	if err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionListFailed, err.Error(), nil)
+	}
+
+	data := make([]responsedto.MissionResource, 0, len(rows))
+	for i := range rows {
+		resource, buildErr := h.missionResource(c.UserContext(), &rows[i])
+		if buildErr != nil {
+			return writeMissionError(c, apperrorsx.ErrMissionListFailed, buildErr.Error(), nil)
+		}
+		data = append(data, resource)
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": filtered,
+	})
+}
+
+// ListMissionTypes godoc
+// @Summary List mission types with subtypes
+// @Description Returns all mission categories and their available subtypes.
+// @Tags Flights - Mission
+// @Produce json
+// @Success 200 {object} responsedto.MissionTypeListResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/mission-type/get-all [get]
+func (h *MissionHandler) ListTypes(c *fiber.Ctx) error {
+	rows, err := h.svc.ListTypes(c.UserContext())
+	if err != nil {
+		return writeMissionError(c, apperrorsx.ErrMissionListFailed, err.Error(), nil)
+	}
+
+	data := make([]responsedto.MissionTypeResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, missionTypeResource(&rows[i]))
+	}
+	return response.Write(c, fiber.StatusOK, data)
+}
+
+func missionListFilterFromQuery(c *fiber.Ctx) (mission.ListFilter, *jsonapi.ErrorObject) {
+	q := func(keys ...string) string {
+		for _, key := range keys {
+			if value := strings.TrimSpace(c.Query(key)); value != "" {
+				return value
+			}
+		}
+		return ""
+	}
+
+	filter := mission.ListFilter{
+		Search: q("filter[search]", "search"),
+		Sort:   strings.TrimSpace(c.Query("sort")),
+	}
+
+	if flightRaw := q("flight_id"); flightRaw != "" {
+		flightID, err := uuidv7.ParseString(flightRaw)
+		if err != nil {
+			return filter, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "flight_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/flight_id"},
+			}
+		}
+		filter.FlightID = flightID
+	}
+
+	if dateFromRaw := q("date_from", "start_date", "from"); dateFromRaw != "" {
+		dateFrom, err := time.Parse("2006-01-02", dateFromRaw)
+		if err != nil {
+			return filter, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "date_from must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/date_from"},
+			}
+		}
+		filter.StartDate = &dateFrom
+	}
+
+	if dateToRaw := q("date_to", "end_date", "to"); dateToRaw != "" {
+		dateTo, err := time.Parse("2006-01-02", dateToRaw)
+		if err != nil {
+			return filter, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "date_to must be YYYY-MM-DD",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/date_to"},
+			}
+		}
+		filter.EndDate = &dateTo
+	}
+
+	if filter.StartDate != nil && filter.EndDate != nil && filter.EndDate.Before(*filter.StartDate) {
+		return filter, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "date_to must be >= date_from",
+			Source: &jsonapi.ErrorSource{Pointer: "/query/date_to"},
+		}
+	}
+
+	filter.MissionType = strings.ToUpper(strings.TrimSpace(q("mission_type", "type")))
+	switch filter.MissionType {
+	case "", sharedconst.MissionTypeHEMS, sharedconst.MissionTypeCAT, sharedconst.MissionTypeSPO, sharedconst.MissionTypeNCO:
+	default:
+		return filter, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "mission_type must be one of: HEMS, CAT, SPO, NCO",
+			Source: &jsonapi.ErrorSource{Pointer: "/query/mission_type"},
+		}
+	}
+
+	if pilotRaw := q("pilot_id"); pilotRaw != "" {
+		pilotID, err := uuidv7.ParseString(pilotRaw)
+		if err != nil {
+			return filter, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "pilot_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/pilot_id"},
+			}
+		}
+		filter.PilotID = pilotID
+	}
+
+	if heliRaw := q("helicopter_id"); heliRaw != "" {
+		helicopterID, err := uuidv7.ParseString(heliRaw)
+		if err != nil {
+			return filter, &jsonapi.ErrorObject{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "helicopter_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/query/helicopter_id"},
+			}
+		}
+		filter.HelicopterID = helicopterID
+	}
+
+	return filter, nil
+}
+
+func (h *MissionHandler) missionDocument(ctx context.Context, row *mission.Mission) (responsedto.MissionResponse, error) {
+	resource, err := h.missionResource(ctx, row)
+	if err != nil {
+		return responsedto.MissionResponse{}, err
+	}
+	return responsedto.MissionResponse{Data: resource}, nil
+}
+
+func (h *MissionHandler) missionDocuments(ctx context.Context, rows []mission.Mission) (responsedto.MissionListResponse, error) {
+	data := make([]responsedto.MissionResource, 0, len(rows))
+	for i := range rows {
+		resource, err := h.missionResource(ctx, &rows[i])
+		if err != nil {
+			return responsedto.MissionListResponse{}, err
+		}
+		data = append(data, resource)
+	}
+	return responsedto.MissionListResponse{Data: data}, nil
+}
+
+func (h *MissionHandler) missionResource(ctx context.Context, row *mission.Mission) (responsedto.MissionResource, error) {
+	missionType := strings.ToUpper(strings.TrimSpace(row.Type))
+	flightDataRows, flightDataResources, err := h.missionFlightDataResources(ctx, row)
+	if err != nil {
+		return responsedto.MissionResource{}, err
+	}
+	flightDataStatus := mission.StatusDraft
+	if len(flightDataRows) > 0 {
+		flightDataStatus = mission.StatusInProgress
+		allComplete := true
+		for i := range flightDataRows {
+			if !flightdata.IsComplete(&flightDataRows[i]) {
+				allComplete = false
+				break
+			}
+		}
+		if allComplete {
+			flightDataStatus = mission.StatusCompleted
+		}
+	}
+	formStates := mission.BuildForms(missionType, mission.FormFacts{
+		mission.FormKeyFlightData: flightDataStatus,
+	})
+
+	formData := &responsedto.MissionForms{}
+	if len(flightDataResources) > 0 {
+		formData.FlightData = flightDataResources
+	}
+
+	return responsedto.MissionResource{
+		Type: sharedconst.MissionResourceType,
+		ID:   idString(row.ID),
+		Attributes: responsedto.MissionAttributes{
+			Flight:      missionFlightRef(row),
+			Type:        missionType,
+			MissionCode: strings.TrimSpace(row.Code),
+			Subtypes:    missionSubtypeRef(row),
+			Note:        strings.TrimSpace(row.Note),
+			StartTime:   normalizeMissionClockDisplay(row.StartTime),
+			EndTime:     normalizeMissionClockDisplay(row.EndTime),
+			Status:      mission.ComputeStatus(formStates),
+			Forms:       formData,
+			Files:       h.missionFiles(ctx, row),
+			CreatedAt:   row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:   uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:   row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:   uuidStringOrEmpty(row.UpdatedBy),
+		},
+	}, nil
+}
+
+func (h *MissionHandler) missionFiles(ctx context.Context, row *mission.Mission) []responsedto.MissionFileItem {
+	if row == nil || len(row.Files) == 0 {
+		return nil
+	}
+	files := make([]responsedto.MissionFileItem, 0, len(row.Files))
+	for i := range row.Files {
+		f := &row.Files[i]
+		item := responsedto.MissionFileItem{
+			ID:           idString(f.FileAttachmentID),
+			AttachmentID: idString(f.FileAttachmentID),
+		}
+		if f.FileAttachment != nil && f.FileAttachment.File != nil {
+			// Expose the underlying file uuid as the item id so it matches the
+			// `file_id` carried by `file.updated` SSE events — letting the
+			// frontend resolve per-file processing readiness in real time.
+			item.ID = idString(f.FileAttachment.File.ID)
+			item.FileName = strings.TrimSpace(f.FileAttachment.File.Name)
+			urls := resolveFileManagerDownloadURLs(ctx, h.storage, f.FileAttachment.File)
+			item.DownloadURL = urls.OriginalURL
+			item.ThumbnailURL = urls.ThumbnailURL
+		}
+		files = append(files, item)
+	}
+	return files
+}
+
+func missionSubtypeRef(row *mission.Mission) *responsedto.MissionSubtypeRef {
+	if row == nil || len(row.SubtypeID) == 0 {
+		return nil
+	}
+	subtype := ""
+	subtypeName := ""
+	if row.MissionSubCategory != nil {
+		subtype = row.MissionSubCategory.SubCodeType
+		subtypeName = row.MissionSubCategory.SubTypeName
+	}
+	return &responsedto.MissionSubtypeRef{
+		ID:          idString(row.SubtypeID),
+		Subtype:     strings.TrimSpace(subtype),
+		SubtypeName: strings.TrimSpace(subtypeName),
+	}
+}
+
+func normalizeMissionClockDisplay(raw string) string {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" {
+		return ""
+	}
+	if len(trimmed) >= 5 {
+		return trimmed[:5]
+	}
+	return trimmed
+}
+
+func missionFlightRef(row *mission.Mission) *responsedto.MissionFlightRef {
+	if row == nil {
+		return nil
+	}
+	if row.Flight == nil && len(row.FlightID) == 0 {
+		return nil
+	}
+	out := &responsedto.MissionFlightRef{ID: idString(row.FlightID)}
+	if row.Flight != nil {
+		out.ID = idString(row.Flight.ID)
+		out.Code = strings.TrimSpace(stringPtrOrEmpty(row.Flight.MissionCode))
+		if !row.Flight.Date.IsZero() {
+			out.Date = row.Flight.Date.UTC().Format("2006-01-02")
+		}
+	}
+	return out
+}
+
+func missionTypeResource(row *mission.MissionCategory) responsedto.MissionTypeResource {
+	subtypes := make([]responsedto.MissionTypeSubtypeItem, 0, len(row.SubCategory))
+	for i := range row.SubCategory {
+		subtypes = append(subtypes, responsedto.MissionTypeSubtypeItem{
+			ID:       idString(row.SubCategory[i].ID),
+			Code:     strings.TrimSpace(row.SubCategory[i].SubCodeType),
+			Name:     strings.TrimSpace(row.SubCategory[i].SubTypeName),
+			TaskName: strings.TrimSpace(row.SubCategory[i].TaskName),
+		})
+	}
+	return responsedto.MissionTypeResource{
+		Type: "mission_type",
+		ID:   idString(row.ID),
+		Attributes: responsedto.MissionTypeAttributes{
+			Code:     strings.TrimSpace(row.CodeType),
+			Name:     strings.TrimSpace(row.TypeName),
+			Subtypes: subtypes,
+		},
+	}
+}
+
+func (h *MissionHandler) missionFlightDataResources(ctx context.Context, row *mission.Mission) ([]flightdata.FlightData, []responsedto.FlightDataResource, error) {
+	if h == nil || h.flightDataSvc == nil || row == nil || len(row.ID) != 16 {
+		return make([]flightdata.FlightData, 0), make([]responsedto.FlightDataResource, 0), nil
+	}
+
+	rows, err := h.flightDataSvc.ListByMissionID(ctx, row.ID)
+	if err != nil {
+		return nil, nil, err
+	}
+	if len(rows) == 0 {
+		return make([]flightdata.FlightData, 0), make([]responsedto.FlightDataResource, 0), nil
+	}
+	flightDataResources := make([]responsedto.FlightDataResource, 0, len(rows))
+	for i := range rows {
+		resource, err := buildFlightDataResourceWithService(ctx, h.flightDataSvc, &rows[i])
+		if err != nil {
+			return nil, nil, err
+		}
+		flightDataResources = append(flightDataResources, resource)
+	}
+	return rows, flightDataResources, nil
+}
+
+func writeMissionError(c *fiber.Ctx, def apperrorsx.Def, detail string, source *jsonapi.ErrorSource) error {
+	return response.WriteErrors(c, def.Status, []jsonapi.ErrorObject{{
+		Code:   def.Code,
+		Detail: detail,
+		Source: source,
+	}})
+}
+
+func writeMissionValidationErrors(c *fiber.Ctx, errs []jsonapi.ErrorObject) error {
+	for i := range errs {
+		if errs[i].Code == "" {
+			errs[i].Code = apperrorsx.CodeMissionInvalidPayload
+		}
+	}
+	return response.WriteErrors(c, fiber.StatusUnprocessableEntity, errs)
+}
+
+func writeMissionServiceError(c *fiber.Ctx, err error, pointer string) error {
+	switch {
+	case errors.Is(err, mission.ErrTypeInvalid):
+		return writeMissionError(c, apperrorsx.ErrMissionTypeInvalid, mission.ErrorMessageTypeInvalid, &jsonapi.ErrorSource{Pointer: "/data/attributes/type"})
+	case errors.Is(err, mission.ErrFlightIDRequired):
+		return writeMissionError(c, apperrorsx.ErrMissionFlightIDRequired, mission.ErrorMessageFlightIDRequired, &jsonapi.ErrorSource{Pointer: pointer})
+	case errors.Is(err, mission.ErrMissionIDRequired):
+		return writeMissionError(c, apperrorsx.ErrMissionMissionIDRequired, mission.ErrorMessageMissionIDRequired, &jsonapi.ErrorSource{Pointer: pointer})
+	case errors.Is(err, mission.ErrSubtypeRequired):
+		return writeMissionError(c, apperrorsx.ErrMissionSubtypeRequired, mission.ErrorMessageSubtypeRequired, &jsonapi.ErrorSource{Pointer: "/data/attributes/subtype_id"})
+	case errors.Is(err, mission.ErrSubtypeInvalid):
+		return writeMissionError(c, apperrorsx.ErrMissionSubtypeInvalid, mission.ErrorMessageSubtypeInvalid, &jsonapi.ErrorSource{Pointer: "/data/attributes/subtype_id"})
+	case errors.Is(err, mission.ErrSubtypeForbidden):
+		return writeMissionError(c, apperrorsx.ErrMissionSubtypeForbidden, mission.ErrorMessageSubtypeForbidden, &jsonapi.ErrorSource{Pointer: "/data/attributes/subtype_id"})
+	case errors.Is(err, mission.ErrRequired):
+		return writeMissionError(c, apperrorsx.ErrMissionCreateFailed, mission.ErrorMessageRequired, nil)
+	case errors.Is(err, mission.ErrDuplicateFlight):
+		return writeMissionError(c, apperrorsx.ErrMissionDuplicateFlight, mission.ErrorMessageDuplicateFlight, &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_id"})
+	case errors.Is(err, mission.ErrLockedAfterFlightInspection):
+		return writeMissionError(c, apperrorsx.ErrMissionLockedAfterFlightInspection, mission.ErrorMessageLockedAfterFlightInspection, &jsonapi.ErrorSource{Pointer: pointer})
+	case errors.Is(err, mission.ErrScheduleMissing):
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidPayload, mission.ErrorMessageScheduleMissing, &jsonapi.ErrorSource{Pointer: pointer})
+	case errors.Is(err, mission.ErrBaseMissing):
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidPayload, mission.ErrorMessageBaseMissing, &jsonapi.ErrorSource{Pointer: pointer})
+	case errors.Is(err, mission.ErrTwilightMissing):
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidPayload, mission.ErrorMessageTwilightMissing, &jsonapi.ErrorSource{Pointer: pointer})
+	case errors.Is(err, mission.ErrCoordinatesInvalid):
+		return writeMissionError(c, apperrorsx.ErrMissionInvalidPayload, mission.ErrorMessageCoordinatesInvalid, &jsonapi.ErrorSource{Pointer: pointer})
+	case errors.Is(err, gorm.ErrRecordNotFound):
+		return writeMissionError(c, apperrorsx.ErrMissionNotFound, mission.ErrorMessageNotFound, &jsonapi.ErrorSource{Pointer: pointer})
+	default:
+		return writeMissionError(c, apperrorsx.ErrMissionDeleteFailed, err.Error(), nil)
+	}
+}
diff --git a/internal/transport/http/handlers/mission_handler_test.go b/internal/transport/http/handlers/mission_handler_test.go
new file mode 100644
index 0000000..c56d0c2
--- /dev/null
+++ b/internal/transport/http/handlers/mission_handler_test.go
@@ -0,0 +1,341 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	flightdata "wucher/internal/domain/flight_data"
+	"wucher/internal/domain/mission"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func doReqMission(t *testing.T, app *fiber.App, method, path string, body []byte) (int, string) {
+	t.Helper()
+	var rdr io.Reader
+	if body != nil {
+		rdr = bytes.NewReader(body)
+	}
+	req, err := http.NewRequest(method, path, rdr)
+	if err != nil {
+		t.Fatalf("new req: %v", err)
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	defer resp.Body.Close()
+	b, _ := io.ReadAll(resp.Body)
+	return resp.StatusCode, string(b)
+}
+
+func TestMissionHandlerDeleteByID(t *testing.T) {
+	missionID := uuidv7.MustBytes()
+	deletedBy := uuidv7.MustBytes()
+	called := false
+
+	h := NewMissionHandler(&missionServiceMock{
+		deleteByIDFn: func(_ context.Context, gotMissionID []byte, gotDeletedBy []byte) error {
+			called = true
+			if string(gotMissionID) != string(missionID) {
+				t.Fatalf("unexpected mission id: %x", gotMissionID)
+			}
+			if string(gotDeletedBy) != string(deletedBy) {
+				t.Fatalf("unexpected deleted by: %x", gotDeletedBy)
+			}
+			return nil
+		},
+	})
+
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", deletedBy)
+		return c.Next()
+	})
+	app.Delete("/api/v1/mission/delete-by-id/:mission_id", h.DeleteByID)
+
+	missionIDStr, err := uuidv7.BytesToString(missionID)
+	if err != nil {
+		t.Fatalf("mission id string: %v", err)
+	}
+	code, body := doReqMission(t, app, http.MethodDelete, "/api/v1/mission/delete-by-id/"+missionIDStr, nil)
+	if code != http.StatusOK {
+		t.Fatalf("unexpected status: %d body=%s", code, body)
+	}
+	if !strings.Contains(body, `"type":"mission_delete"`) || !strings.Contains(body, `"deleted":true`) {
+		t.Fatalf("unexpected body: %s", body)
+	}
+	if !called {
+		t.Fatal("expected service DeleteByID to be called")
+	}
+}
+
+func TestMissionHandlerDeleteByIDValidation(t *testing.T) {
+	h := NewMissionHandler(&missionServiceMock{})
+	app := fiber.New()
+	app.Delete("/api/v1/mission/delete-by-id/:mission_id", h.DeleteByID)
+
+	code, body := doReqMission(t, app, http.MethodDelete, "/api/v1/mission/delete-by-id/bad", nil)
+	if code != http.StatusUnprocessableEntity {
+		t.Fatalf("unexpected status: %d body=%s", code, body)
+	}
+	if !strings.Contains(body, mission.ErrorMessageInvalidMissionID) {
+		t.Fatalf("unexpected validation body: %s", body)
+	}
+}
+
+func TestMissionHandlerList_ReturnsKeyedFlightDataForms(t *testing.T) {
+	missionID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	flightDataID := uuidv7.MustBytes()
+
+	h := NewMissionHandler(&missionServiceMock{
+		listFn: func(context.Context, string, string, []byte, int, int) ([]mission.Mission, int64, error) {
+			return []mission.Mission{{
+				ID:        missionID,
+				FlightID:  flightID,
+				Type:      "CAT",
+				CreatedAt: time.Date(2026, time.June, 8, 8, 0, 0, 0, time.UTC),
+				UpdatedAt: time.Date(2026, time.June, 8, 8, 30, 0, 0, time.UTC),
+			}}, 1, nil
+		},
+	}).WithFlightDataService(&flightDataServiceMock{
+		listFn: func(_ context.Context, _ string, gotMissionID []byte, _ []byte, _ int, _ int) ([]flightdata.FlightData, int64, error) {
+			if string(gotMissionID) != string(missionID) {
+				t.Fatalf("unexpected mission id: %x", gotMissionID)
+			}
+			return []flightdata.FlightData{{
+				ID:        flightDataID,
+				MissionID: gotMissionID,
+				Mission:   &mission.Mission{Type: "CAT"},
+				Status:    flightdata.StatusCompleted,
+				CreatedAt: time.Date(2026, time.June, 8, 8, 28, 20, 0, time.UTC),
+				UpdatedAt: time.Date(2026, time.June, 8, 8, 28, 14, 0, time.UTC),
+			}}, 1, nil
+		},
+	})
+
+	app := fiber.New()
+	app.Get("/api/v1/mission/get-all", h.List)
+
+	flightIDStr, err := uuidv7.BytesToString(flightID)
+	if err != nil {
+		t.Fatalf("flight id string: %v", err)
+	}
+	code, body := doReqMission(t, app, http.MethodGet, "/api/v1/mission/get-all?flight_id="+flightIDStr, nil)
+	if code != http.StatusOK {
+		t.Fatalf("unexpected status: %d body=%s", code, body)
+	}
+
+	var doc map[string]any
+	if err := json.Unmarshal([]byte(body), &doc); err != nil {
+		t.Fatalf("unmarshal response: %v body=%s", err, body)
+	}
+
+	data, ok := doc["data"].([]any)
+	if !ok || len(data) != 1 {
+		t.Fatalf("unexpected data payload: %#v", doc["data"])
+	}
+	resource, ok := data[0].(map[string]any)
+	if !ok {
+		t.Fatalf("unexpected resource payload: %#v", data[0])
+	}
+	attributes, ok := resource["attributes"].(map[string]any)
+	if !ok {
+		t.Fatalf("unexpected attributes payload: %#v", resource["attributes"])
+	}
+	if _, ok := attributes["flight_data"]; ok {
+		t.Fatalf("expected top-level flight_data to be removed: %s", body)
+	}
+	if got := attributes["status"]; got != "completed" {
+		t.Fatalf("unexpected status: %#v", got)
+	}
+	forms, ok := attributes["forms"].(map[string]any)
+	if !ok {
+		t.Fatalf("unexpected forms payload: %#v", attributes["forms"])
+	}
+	items, ok := forms["flight_data"].([]any)
+	if !ok {
+		t.Fatalf("unexpected flight_data form payload: %#v", forms["flight_data"])
+	}
+	if len(items) != 1 {
+		t.Fatalf("expected 1 flight_data item, got %d", len(items))
+	}
+	formItem, ok := items[0].(map[string]any)
+	if !ok {
+		t.Fatalf("unexpected flight_data item payload: %#v", items[0])
+	}
+	if got := formItem["type"]; got != "flight_data" {
+		t.Fatalf("unexpected flight_data type: %#v", got)
+	}
+}
+
+func TestMissionHandlerList_StaysInProgressUntilAllFlightDataComplete(t *testing.T) {
+	missionID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	flightDataID := uuidv7.MustBytes()
+
+	h := NewMissionHandler(&missionServiceMock{
+		listFn: func(context.Context, string, string, []byte, int, int) ([]mission.Mission, int64, error) {
+			return []mission.Mission{{
+				ID:        missionID,
+				FlightID:  flightID,
+				Type:      "CAT",
+				CreatedAt: time.Date(2026, time.June, 8, 8, 0, 0, 0, time.UTC),
+				UpdatedAt: time.Date(2026, time.June, 8, 8, 30, 0, 0, time.UTC),
+			}}, 1, nil
+		},
+	}).WithFlightDataService(&flightDataServiceMock{
+		listFn: func(_ context.Context, _ string, gotMissionID []byte, _ []byte, _ int, _ int) ([]flightdata.FlightData, int64, error) {
+			if string(gotMissionID) != string(missionID) {
+				t.Fatalf("unexpected mission id: %x", gotMissionID)
+			}
+			return []flightdata.FlightData{{
+				ID:        flightDataID,
+				MissionID: gotMissionID,
+				Mission:   &mission.Mission{Type: "CAT"},
+				Status:    flightdata.StatusInProgress,
+				CreatedAt: time.Date(2026, time.June, 8, 8, 28, 20, 0, time.UTC),
+				UpdatedAt: time.Date(2026, time.June, 8, 8, 28, 14, 0, time.UTC),
+			}}, 1, nil
+		},
+	})
+
+	app := fiber.New()
+	app.Get("/api/v1/mission/get-all", h.List)
+
+	flightIDStr, err := uuidv7.BytesToString(flightID)
+	if err != nil {
+		t.Fatalf("flight id string: %v", err)
+	}
+	code, body := doReqMission(t, app, http.MethodGet, "/api/v1/mission/get-all?flight_id="+flightIDStr, nil)
+	if code != http.StatusOK {
+		t.Fatalf("unexpected status: %d body=%s", code, body)
+	}
+
+	var doc map[string]any
+	if err := json.Unmarshal([]byte(body), &doc); err != nil {
+		t.Fatalf("unmarshal response: %v body=%s", err, body)
+	}
+
+	data, ok := doc["data"].([]any)
+	if !ok || len(data) != 1 {
+		t.Fatalf("unexpected data payload: %#v", doc["data"])
+	}
+	resource, ok := data[0].(map[string]any)
+	if !ok {
+		t.Fatalf("unexpected resource payload: %#v", data[0])
+	}
+	attributes, ok := resource["attributes"].(map[string]any)
+	if !ok {
+		t.Fatalf("unexpected attributes payload: %#v", resource["attributes"])
+	}
+	if got := attributes["status"]; got != "in_progress" {
+		t.Fatalf("unexpected status: %#v", got)
+	}
+	forms, ok := attributes["forms"].(map[string]any)
+	if !ok {
+		t.Fatalf("unexpected forms payload: %#v", attributes["forms"])
+	}
+	items, ok := forms["flight_data"].([]any)
+	if !ok || len(items) != 1 {
+		t.Fatalf("unexpected flight_data form payload: %#v", forms["flight_data"])
+	}
+}
+
+func TestMissionHandlerListDatatable_FiltersAndMeta(t *testing.T) {
+	missionID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	pilotID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+
+	h := NewMissionHandler(&missionServiceMock{
+		listDTFn: func(_ context.Context, got mission.ListFilter, limit, offset int) ([]mission.Mission, int64, int64, error) {
+			if got.Search != "needle" {
+				t.Fatalf("unexpected search: %q", got.Search)
+			}
+			if got.MissionType != "CAT" {
+				t.Fatalf("unexpected mission type: %q", got.MissionType)
+			}
+			if got.StartDate == nil || got.StartDate.Format("2006-01-02") != "2026-06-01" {
+				t.Fatalf("unexpected start date: %#v", got.StartDate)
+			}
+			if got.EndDate == nil || got.EndDate.Format("2006-01-02") != "2026-06-30" {
+				t.Fatalf("unexpected end date: %#v", got.EndDate)
+			}
+			if string(got.PilotID) != string(pilotID) {
+				t.Fatalf("unexpected pilot id: %x", got.PilotID)
+			}
+			if string(got.HelicopterID) != string(helicopterID) {
+				t.Fatalf("unexpected helicopter id: %x", got.HelicopterID)
+			}
+			if limit != 20 || offset != 0 {
+				t.Fatalf("unexpected pagination: limit=%d offset=%d", limit, offset)
+			}
+			return []mission.Mission{{
+				ID:        missionID,
+				FlightID:  flightID,
+				Type:      "CAT",
+				CreatedAt: time.Date(2026, time.June, 8, 8, 0, 0, 0, time.UTC),
+				UpdatedAt: time.Date(2026, time.June, 8, 8, 30, 0, 0, time.UTC),
+			}}, 10, 2, nil
+		},
+	}).WithFlightDataService(&flightDataServiceMock{
+		listFn: func(_ context.Context, _ string, gotMissionID []byte, _ []byte, _ int, _ int) ([]flightdata.FlightData, int64, error) {
+			if string(gotMissionID) != string(missionID) {
+				t.Fatalf("unexpected mission id: %x", gotMissionID)
+			}
+			return nil, 0, nil
+		},
+	})
+
+	app := fiber.New()
+	app.Get("/api/v1/mission/get-all/dt", h.ListDatatable)
+
+	flightIDStr, err := uuidv7.BytesToString(flightID)
+	if err != nil {
+		t.Fatalf("flight id string: %v", err)
+	}
+	pilotIDStr, err := uuidv7.BytesToString(pilotID)
+	if err != nil {
+		t.Fatalf("pilot id string: %v", err)
+	}
+	helicopterIDStr, err := uuidv7.BytesToString(helicopterID)
+	if err != nil {
+		t.Fatalf("helicopter id string: %v", err)
+	}
+	code, body := doReqMission(t, app, http.MethodGet, "/api/v1/mission/get-all/dt?search=needle&date_from=2026-06-01&date_to=2026-06-30&mission_type=CAT&pilot_id="+pilotIDStr+"&helicopter_id="+helicopterIDStr+"&flight_id="+flightIDStr+"&draw=7&start=0&length=20", nil)
+	if code != http.StatusOK {
+		t.Fatalf("unexpected status: %d body=%s", code, body)
+	}
+
+	var doc map[string]any
+	if err := json.Unmarshal([]byte(body), &doc); err != nil {
+		t.Fatalf("unmarshal response: %v body=%s", err, body)
+	}
+
+	meta, ok := doc["meta"].(map[string]any)
+	if !ok {
+		t.Fatalf("unexpected meta payload: %#v", doc["meta"])
+	}
+	if meta["draw"] != float64(7) {
+		t.Fatalf("unexpected draw: %#v", meta["draw"])
+	}
+	if meta["records_total"] != float64(10) || meta["records_filtered"] != float64(2) {
+		t.Fatalf("unexpected meta counts: %#v", meta)
+	}
+	data, ok := doc["data"].([]any)
+	if !ok || len(data) != 1 {
+		t.Fatalf("unexpected data payload: %#v", doc["data"])
+	}
+}
diff --git a/internal/transport/http/handlers/office_xlsx_sanitizer.go b/internal/transport/http/handlers/office_xlsx_sanitizer.go
new file mode 100644
index 0000000..c360407
--- /dev/null
+++ b/internal/transport/http/handlers/office_xlsx_sanitizer.go
@@ -0,0 +1,511 @@
+package handlers
+
+import (
+	"archive/zip"
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+
+	filemanager "wucher/internal/domain/file_manager"
+)
+
+var (
+	xlsxVMLStyleAttrRE   = regexp.MustCompile(`(?i)(style\s*=\s*["'])([^"']*)(["'])`)
+	xlsxVMLLengthTokenRE = regexp.MustCompile(`^[+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:pt|px|in|cm|mm|pc|em|ex|%)$`)
+	xlsxVMLShapeTagRE    = regexp.MustCompile(`(?is)<v:shape\b[^>]*>`)
+	xlsxVMLShapeIDAttrRE = regexp.MustCompile(`(?i)(\bid\s*=\s*["'])(_x0000_s\d+)(["'])`)
+	xlsxVMLShapeIDNumRE  = regexp.MustCompile(`(?i)^_x0000_s(\d+)$`)
+	xlsxVMLShapeTypeRE   = regexp.MustCompile(`(?i)<v:shapetype\b`)
+	xlsxVMLNoteTypeRefRE = regexp.MustCompile(`(?i)type\s*=\s*["']#_x0000_t202["']`)
+	xlsxVMLRootTagRE     = regexp.MustCompile(`(?is)<xml\b[^>]*>`)
+)
+
+// xlsxVMLNoteShapeTypeHeader is the standard <o:shapelayout>/<v:shapetype>
+// preamble that Excel writes at the top of every comment/note VML drawing.
+// Some producers (and files that have been round-tripped through other tools)
+// omit it while still emitting shapes that reference type="#_x0000_t202";
+// LibreOffice/Collabora then flags the package as corrupt and offers a repair.
+// Injecting the missing definition makes the shape reference resolve and
+// removes the repair prompt.
+const xlsxVMLNoteShapeTypeHeader = `<o:shapelayout v:ext="edit"><o:idmap v:ext="edit" data="1"/></o:shapelayout>` +
+	`<v:shapetype id="_x0000_t202" coordsize="21600,21600" o:spt="202" path="m,l,21600r21600,l21600,xe">` +
+	`<v:stroke joinstyle="miter"/><v:path gradientshapeok="t" o:connecttype="rect"/></v:shapetype>`
+
+type xlsxSanitizerStorage interface {
+	GetObject(context.Context, string) (io.ReadCloser, filemanager.ObjectMetadata, error)
+	PutObject(context.Context, filemanager.PutObjectInput) (filemanager.ObjectMetadata, error)
+}
+
+type xlsxSanitizerFileUpdater interface {
+	UpdateFile(context.Context, *filemanager.File) error
+}
+
+func sanitizeXLSXPayload(payload []byte) ([]byte, int, bool, error) {
+	reader, err := zip.NewReader(bytes.NewReader(payload), int64(len(payload)))
+	if err != nil {
+		return nil, 0, false, errors.New("file content is not a valid office zip document")
+	}
+
+	var buf bytes.Buffer
+	writer := zip.NewWriter(&buf)
+	if reader.Comment != "" {
+		if err := writer.SetComment(reader.Comment); err != nil {
+			_ = writer.Close()
+			return nil, 0, false, err
+		}
+	}
+
+	totalStyleFixes := 0
+	changed := false
+
+	for _, file := range reader.File {
+		header := file.FileHeader
+		header.Name = file.Name
+		header.Comment = file.Comment
+		header.NonUTF8 = file.NonUTF8
+
+		if file.FileInfo().IsDir() {
+			entry, err := writer.CreateHeader(&header)
+			if err != nil {
+				_ = writer.Close()
+				return nil, 0, false, err
+			}
+			if _, err := entry.Write(nil); err != nil {
+				_ = writer.Close()
+				return nil, 0, false, err
+			}
+			continue
+		}
+
+		if !isVMLDrawingEntry(file.Name) {
+			raw, err := file.OpenRaw()
+			if err != nil {
+				_ = writer.Close()
+				return nil, 0, false, err
+			}
+			entry, err := writer.CreateRaw(&header)
+			if err != nil {
+				_ = writer.Close()
+				return nil, 0, false, err
+			}
+			if _, err := io.Copy(entry, raw); err != nil {
+				_ = writer.Close()
+				return nil, 0, false, err
+			}
+			continue
+		}
+
+		rc, err := file.Open()
+		if err != nil {
+			_ = writer.Close()
+			return nil, 0, false, err
+		}
+		filePayload, readErr := io.ReadAll(rc)
+		_ = rc.Close()
+		if readErr != nil {
+			_ = writer.Close()
+			return nil, 0, false, readErr
+		}
+
+		sanitizedPayload, styleFixes, fileChanged, err := sanitizeVMLDrawingPayload(filePayload)
+		if err != nil {
+			_ = writer.Close()
+			return nil, 0, false, err
+		}
+		if dedupedPayload, idFixes, idChanged := dedupeVMLShapeIDs(sanitizedPayload); idChanged {
+			sanitizedPayload = dedupedPayload
+			fileChanged = true
+			totalStyleFixes += idFixes
+		}
+		if shapeTypePayload, shapeTypeFixes, shapeTypeChanged := ensureVMLNoteShapeType(sanitizedPayload); shapeTypeChanged {
+			sanitizedPayload = shapeTypePayload
+			fileChanged = true
+			totalStyleFixes += shapeTypeFixes
+		}
+		if fileChanged {
+			changed = true
+			totalStyleFixes += styleFixes
+		}
+
+		if !fileChanged {
+			raw, err := file.OpenRaw()
+			if err != nil {
+				_ = writer.Close()
+				return nil, 0, false, err
+			}
+			entry, err := writer.CreateRaw(&header)
+			if err != nil {
+				_ = writer.Close()
+				return nil, 0, false, err
+			}
+			if _, err := io.Copy(entry, raw); err != nil {
+				_ = writer.Close()
+				return nil, 0, false, err
+			}
+			continue
+		}
+
+		entry, err := writer.CreateHeader(&header)
+		if err != nil {
+			_ = writer.Close()
+			return nil, 0, false, err
+		}
+		if _, err := entry.Write(sanitizedPayload); err != nil {
+			_ = writer.Close()
+			return nil, 0, false, err
+		}
+	}
+
+	if err := writer.Close(); err != nil {
+		return nil, 0, false, err
+	}
+	if !changed {
+		return payload, 0, false, nil
+	}
+	return buf.Bytes(), totalStyleFixes, true, nil
+}
+
+func sanitizeVMLDrawingPayload(payload []byte) ([]byte, int, bool, error) {
+	totalFixes := 0
+	changed := false
+
+	rewritten := xlsxVMLStyleAttrRE.ReplaceAllFunc(payload, func(match []byte) []byte {
+		sub := xlsxVMLStyleAttrRE.FindSubmatch(match)
+		if len(sub) != 4 {
+			return match
+		}
+
+		normalized, styleFixes, fileChanged := sanitizeVMLStyleValue(string(sub[2]))
+		if !fileChanged {
+			return match
+		}
+
+		totalFixes += styleFixes
+		changed = true
+		out := make([]byte, 0, len(sub[1])+len(normalized)+len(sub[3]))
+		out = append(out, sub[1]...)
+		out = append(out, normalized...)
+		out = append(out, sub[3]...)
+		return out
+	})
+
+	if !changed {
+		return payload, 0, false, nil
+	}
+	return rewritten, totalFixes, true, nil
+}
+
+func dedupeVMLShapeIDs(payload []byte) ([]byte, int, bool) {
+	if len(payload) == 0 {
+		return payload, 0, false
+	}
+
+	source := string(payload)
+	tags := xlsxVMLShapeTagRE.FindAllStringIndex(source, -1)
+	if len(tags) == 0 {
+		return payload, 0, false
+	}
+
+	maxID := 0
+	for _, match := range xlsxVMLShapeIDAttrRE.FindAllStringSubmatch(source, -1) {
+		if len(match) < 3 {
+			continue
+		}
+		if sub := xlsxVMLShapeIDNumRE.FindStringSubmatch(match[2]); len(sub) == 2 {
+			if n, err := strconv.Atoi(sub[1]); err == nil && n > maxID {
+				maxID = n
+			}
+		}
+	}
+	if maxID == 0 {
+		return payload, 0, false
+	}
+
+	seen := make(map[string]struct{}, len(tags))
+	var buf strings.Builder
+	buf.Grow(len(source) + len(tags)*8)
+	last := 0
+	nextID := maxID + 1
+	fixCount := 0
+
+	for _, loc := range tags {
+		tag := source[loc[0]:loc[1]]
+		newTag, changed := dedupeVMLShapeIDTag(tag, seen, &nextID)
+		if changed {
+			fixCount++
+		}
+		buf.WriteString(source[last:loc[0]])
+		buf.WriteString(newTag)
+		last = loc[1]
+	}
+	buf.WriteString(source[last:])
+
+	if fixCount == 0 {
+		return payload, 0, false
+	}
+	return []byte(buf.String()), fixCount, true
+}
+
+func dedupeVMLShapeIDTag(tag string, seen map[string]struct{}, nextID *int) (string, bool) {
+	match := xlsxVMLShapeIDAttrRE.FindStringSubmatchIndex(tag)
+	if len(match) < 8 {
+		return tag, false
+	}
+	currentID := tag[match[4]:match[5]]
+	if _, ok := seen[currentID]; !ok {
+		seen[currentID] = struct{}{}
+		return tag, false
+	}
+	if nextID == nil {
+		return tag, false
+	}
+	newID := "_x0000_s" + strconv.Itoa(*nextID)
+	*nextID = *nextID + 1
+	return tag[:match[4]] + newID + tag[match[5]:], true
+}
+
+// ensureVMLNoteShapeType injects the standard note <v:shapetype> definition
+// (and its <o:shapelayout> preamble) when the drawing references
+// type="#_x0000_t202" but never defines it. Returns the payload unchanged when
+// a shapetype already exists, when no note shape references it, or when the
+// root <xml> element lacks the o:/v: namespaces the injected markup needs.
+func ensureVMLNoteShapeType(payload []byte) ([]byte, int, bool) {
+	if len(payload) == 0 {
+		return payload, 0, false
+	}
+	if xlsxVMLShapeTypeRE.Match(payload) {
+		return payload, 0, false
+	}
+	if !xlsxVMLNoteTypeRefRE.Match(payload) {
+		return payload, 0, false
+	}
+
+	root := xlsxVMLRootTagRE.FindIndex(payload)
+	if root == nil {
+		return payload, 0, false
+	}
+	rootTag := bytes.ToLower(payload[root[0]:root[1]])
+	if !bytes.Contains(rootTag, []byte("xmlns:o")) || !bytes.Contains(rootTag, []byte("xmlns:v")) {
+		return payload, 0, false
+	}
+
+	out := make([]byte, 0, len(payload)+len(xlsxVMLNoteShapeTypeHeader))
+	out = append(out, payload[:root[1]]...)
+	out = append(out, xlsxVMLNoteShapeTypeHeader...)
+	out = append(out, payload[root[1]:]...)
+	return out, 1, true
+}
+
+func sanitizeVMLStyleValue(raw string) (string, int, bool) {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" {
+		return raw, 0, false
+	}
+
+	tokens := strings.Split(trimmed, ";")
+	if len(tokens) == 0 {
+		return raw, 0, false
+	}
+
+	positionIndex := -1
+	for i := range tokens {
+		if isVMLAbsolutePositionToken(tokens[i]) {
+			positionIndex = i
+			break
+		}
+	}
+	if positionIndex < 0 {
+		return raw, 0, false
+	}
+
+	leadingLengths := make([]string, 0, 2)
+	nextIndex := positionIndex + 1
+	for nextIndex < len(tokens) && len(leadingLengths) < 2 {
+		token := strings.TrimSpace(tokens[nextIndex])
+		if token == "" {
+			nextIndex++
+			continue
+		}
+		if !isVMLLengthToken(token) {
+			break
+		}
+		leadingLengths = append(leadingLengths, token)
+		nextIndex++
+	}
+
+	if len(leadingLengths) == 0 {
+		return raw, 0, false
+	}
+
+	remaining := make([]string, 0, len(tokens)-nextIndex+3)
+	for ; nextIndex < len(tokens); nextIndex++ {
+		token := strings.TrimSpace(tokens[nextIndex])
+		if token == "" {
+			continue
+		}
+		remaining = append(remaining, token)
+	}
+
+	styleParts := make([]string, 0, len(tokens)+2)
+	for i := 0; i < positionIndex; i++ {
+		token := strings.TrimSpace(tokens[i])
+		if token == "" {
+			continue
+		}
+		styleParts = append(styleParts, token)
+	}
+	styleParts = append(styleParts, "position:absolute")
+	styleParts = append(styleParts, "margin-left:"+leadingLengths[0])
+	if len(leadingLengths) >= 2 {
+		styleParts = append(styleParts, "margin-top:"+leadingLengths[1])
+	} else {
+		styleParts = append(styleParts, "margin-top:0pt")
+	}
+	styleParts = append(styleParts, remaining...)
+
+	return strings.Join(styleParts, ";"), len(leadingLengths), true
+}
+
+func isVMLDrawingEntry(name string) bool {
+	name = strings.ToLower(strings.TrimSpace(strings.ReplaceAll(name, "\\", "/")))
+	if name == "" {
+		return false
+	}
+	return strings.HasPrefix(name, "xl/drawings/vmldrawing") && strings.HasSuffix(name, ".vml")
+}
+
+func isVMLAbsolutePositionToken(token string) bool {
+	token = strings.ToLower(strings.ReplaceAll(strings.TrimSpace(token), " ", ""))
+	return token == "position:absolute"
+}
+
+func isVMLLengthToken(token string) bool {
+	return xlsxVMLLengthTokenRE.MatchString(strings.ToLower(strings.TrimSpace(token)))
+}
+
+func (h *FileManagerFileHandler) sanitizeStoredXLSXObject(ctx context.Context, row *filemanager.File, objectKey, nameHint, mimeHint, operation string) (bool, int64, error) {
+	if h == nil || h.storage == nil {
+		return false, 0, nil
+	}
+	storage, ok := any(h.storage).(xlsxSanitizerStorage)
+	if !ok {
+		return false, 0, errors.New("storage does not support office sanitization")
+	}
+	return sanitizeStoredXLSXObject(ctx, storage, h.svc, row, objectKey, nameHint, mimeHint, operation)
+}
+
+func sanitizeStoredXLSXObject(
+	ctx context.Context,
+	storage xlsxSanitizerStorage,
+	updater xlsxSanitizerFileUpdater,
+	row *filemanager.File,
+	objectKey,
+	nameHint,
+	mimeHint,
+	operation string,
+) (bool, int64, error) {
+	if storage == nil {
+		return false, 0, nil
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+
+	objectKey = strings.TrimSpace(objectKey)
+	if objectKey == "" && row != nil {
+		objectKey = strings.TrimSpace(row.ObjectKey)
+	}
+	if objectKey == "" {
+		return false, 0, nil
+	}
+
+	name := strings.TrimSpace(nameHint)
+	if name == "" && row != nil {
+		name = strings.TrimSpace(row.Name)
+	}
+	ext := strings.ToLower(strings.TrimPrefix(filepath.Ext(name), "."))
+	if ext == "" {
+		ext = strings.ToLower(strings.TrimPrefix(filepath.Ext(objectKey), "."))
+	}
+	if ext != "xlsx" {
+		return false, 0, nil
+	}
+
+	body, meta, err := storage.GetObject(ctx, objectKey)
+	if err != nil {
+		return false, 0, err
+	}
+	defer body.Close()
+
+	payload, err := io.ReadAll(body)
+	if err != nil {
+		return false, 0, err
+	}
+
+	sanitizedPayload, styleFixes, changed, err := sanitizeXLSXPayload(payload)
+	if err != nil {
+		return false, 0, err
+	}
+	if !changed {
+		return false, int64(len(payload)), nil
+	}
+
+	contentType := strings.TrimSpace(firstNonEmpty(mimeHint, meta.ContentType, canonicalOfficeContentType(name)))
+	if contentType == "" {
+		contentType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+	}
+
+	newMeta, err := storage.PutObject(ctx, filemanager.PutObjectInput{
+		ObjectKey:   objectKey,
+		ContentType: contentType,
+		SizeBytes:   int64(len(sanitizedPayload)),
+		Body:        bytes.NewReader(sanitizedPayload),
+	})
+	if err != nil {
+		return true, int64(len(sanitizedPayload)), err
+	}
+
+	logArgs := []any{
+		slog.String("operation", strings.TrimSpace(operation)),
+		slog.String("object_key", objectKey),
+		slog.String("mime_type", contentType),
+		slog.Int("style_fix_count", styleFixes),
+		slog.Int("before_bytes", len(payload)),
+		slog.Int("after_bytes", len(sanitizedPayload)),
+	}
+	if row != nil {
+		logArgs = append(logArgs, slog.String("file_id", idString(row.ID)))
+		logArgs = append(logArgs, slog.String("file_name", strings.TrimSpace(row.Name)))
+	}
+	slog.WarnContext(ctx, "sanitized malformed xlsx VML drawing", logArgs...)
+
+	if row != nil {
+		row.SizeBytes = int64(len(sanitizedPayload))
+		row.MimeType = contentType
+		if strings.TrimSpace(newMeta.Bucket) != "" {
+			row.Bucket = newMeta.Bucket
+		}
+		if strings.TrimSpace(newMeta.ObjectKey) != "" {
+			row.ObjectKey = newMeta.ObjectKey
+		}
+		if strings.TrimSpace(newMeta.ETag) != "" {
+			row.ETag = newMeta.ETag
+		}
+		if strings.TrimSpace(newMeta.VersionID) != "" {
+			row.ObjectVersion = newMeta.VersionID
+		}
+		if updater != nil {
+			if err := updater.UpdateFile(ctx, row); err != nil {
+				return true, int64(len(sanitizedPayload)), err
+			}
+		}
+	}
+
+	return true, int64(len(sanitizedPayload)), nil
+}
diff --git a/internal/transport/http/handlers/office_xlsx_sanitizer_roundtrip_test.go b/internal/transport/http/handlers/office_xlsx_sanitizer_roundtrip_test.go
new file mode 100644
index 0000000..67d7e76
--- /dev/null
+++ b/internal/transport/http/handlers/office_xlsx_sanitizer_roundtrip_test.go
@@ -0,0 +1,169 @@
+package handlers
+
+import (
+	"archive/zip"
+	"bytes"
+	"io"
+	"strings"
+	"testing"
+)
+
+func buildXLSX(t *testing.T, entries map[string]string) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	zw := zip.NewWriter(&buf)
+	for name, content := range entries {
+		w, err := zw.Create(name)
+		if err != nil {
+			t.Fatalf("zip create %s: %v", name, err)
+		}
+		if _, err := io.WriteString(w, content); err != nil {
+			t.Fatalf("zip write %s: %v", name, err)
+		}
+	}
+	if err := zw.Close(); err != nil {
+		t.Fatalf("zip close: %v", err)
+	}
+	return buf.Bytes()
+}
+
+func readZipEntry(t *testing.T, payload []byte, name string) string {
+	t.Helper()
+	zr, err := zip.NewReader(bytes.NewReader(payload), int64(len(payload)))
+	if err != nil {
+		t.Fatalf("output is not a valid zip: %v", err)
+	}
+	for _, f := range zr.File {
+		if f.Name != name {
+			continue
+		}
+		rc, err := f.Open()
+		if err != nil {
+			t.Fatalf("open entry %s: %v", name, err)
+		}
+		defer rc.Close()
+		b, err := io.ReadAll(rc)
+		if err != nil {
+			t.Fatalf("read entry %s: %v", name, err)
+		}
+		return string(b)
+	}
+	t.Fatalf("entry %s not found in output zip", name)
+	return ""
+}
+
+const sampleWorkbookXML = `<?xml version="1.0"?><workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"><sheets><sheet name="Sheet1" sheetId="1"/></sheets></workbook>`
+
+// A template with no VML drawings must pass through byte-for-byte and stay a
+// valid ZIP — the sanitizer must never touch non-target entries.
+func TestSanitizeXLSXPayload_NoVML_Unchanged(t *testing.T) {
+	src := buildXLSX(t, map[string]string{
+		"[Content_Types].xml": `<?xml version="1.0"?><Types/>`,
+		"xl/workbook.xml":     sampleWorkbookXML,
+	})
+
+	out, fixes, changed, err := sanitizeXLSXPayload(src)
+	if err != nil {
+		t.Fatalf("sanitize error: %v", err)
+	}
+	if changed {
+		t.Fatalf("expected changed=false for a payload without VML drawings")
+	}
+	if fixes != 0 {
+		t.Fatalf("expected 0 style fixes, got %d", fixes)
+	}
+	if !bytes.Equal(out, src) {
+		t.Fatalf("payload without VML must be returned verbatim")
+	}
+	if _, err := zip.NewReader(bytes.NewReader(out), int64(len(out))); err != nil {
+		t.Fatalf("output not a valid zip: %v", err)
+	}
+}
+
+// A malformed VML style must be rewritten, and the result must remain a valid
+// ZIP whose OTHER entries are preserved intact.
+func TestSanitizeXLSXPayload_MalformedVML_RewrittenAndValid(t *testing.T) {
+	malformedVML := `<xml xmlns:v="urn:schemas-microsoft-com:vml"><v:shape style='position:absolute;12pt;24pt;width:100pt'/></xml>`
+	src := buildXLSX(t, map[string]string{
+		"[Content_Types].xml":         `<?xml version="1.0"?><Types/>`,
+		"xl/workbook.xml":             sampleWorkbookXML,
+		"xl/drawings/vmlDrawing1.vml": malformedVML,
+	})
+
+	out, fixes, changed, err := sanitizeXLSXPayload(src)
+	if err != nil {
+		t.Fatalf("sanitize error: %v", err)
+	}
+	if !changed {
+		t.Fatalf("expected changed=true for malformed VML style")
+	}
+	if fixes == 0 {
+		t.Fatalf("expected style fixes > 0")
+	}
+
+	// Output must be a valid ZIP.
+	if _, err := zip.NewReader(bytes.NewReader(out), int64(len(out))); err != nil {
+		t.Fatalf("output not a valid zip: %v", err)
+	}
+	// The VML entry must now carry the normalized margin properties.
+	vml := readZipEntry(t, out, "xl/drawings/vmlDrawing1.vml")
+	if !bytes.Contains([]byte(vml), []byte("margin-left:12pt")) ||
+		!bytes.Contains([]byte(vml), []byte("margin-top:24pt")) {
+		t.Fatalf("VML not normalized as expected: %s", vml)
+	}
+	// A non-target entry must be preserved byte-for-byte.
+	if got := readZipEntry(t, out, "xl/workbook.xml"); got != sampleWorkbookXML {
+		t.Fatalf("non-VML entry mutated:\n got: %s\nwant: %s", got, sampleWorkbookXML)
+	}
+}
+
+func TestSanitizeXLSXPayload_MalformedVML_WithPrefix_Rewritten(t *testing.T) {
+	malformedVML := `<xml xmlns:v="urn:schemas-microsoft-com:vml"><v:shape style='mso-position-horizontal-relative:page;position:absolute;12pt;24pt;width:100pt'/></xml>`
+	src := buildXLSX(t, map[string]string{
+		"[Content_Types].xml":         `<?xml version="1.0"?><Types/>`,
+		"xl/workbook.xml":             sampleWorkbookXML,
+		"xl/drawings/vmlDrawing1.vml": malformedVML,
+	})
+
+	out, _, changed, err := sanitizeXLSXPayload(src)
+	if err != nil {
+		t.Fatalf("sanitize error: %v", err)
+	}
+	if !changed {
+		t.Fatalf("expected changed=true for prefixed malformed VML style")
+	}
+
+	vml := readZipEntry(t, out, "xl/drawings/vmlDrawing1.vml")
+	if !strings.Contains(vml, "mso-position-horizontal-relative:page;position:absolute;margin-left:12pt;margin-top:24pt") {
+		t.Fatalf("prefixed VML not normalized as expected: %s", vml)
+	}
+}
+
+func TestSanitizeXLSXPayload_DuplicateVMLShapeIDs_AreUniqued(t *testing.T) {
+	vml := `<xml xmlns:v="urn:schemas-microsoft-com:vml">
+  <v:shape id="_x0000_s1025" type="#_x0000_t202" style="position:absolute;12pt;24pt;width:100pt"/>
+  <v:shape id="_x0000_s1025" type="#_x0000_t202" style="position:absolute;12pt;24pt;width:100pt"/>
+  <v:shape id="_x0000_s1025" type="#_x0000_t202" style="position:absolute;12pt;24pt;width:100pt"/>
+</xml>`
+	src := buildXLSX(t, map[string]string{
+		"[Content_Types].xml":         `<?xml version="1.0"?><Types/>`,
+		"xl/workbook.xml":             sampleWorkbookXML,
+		"xl/drawings/vmlDrawing1.vml": vml,
+	})
+
+	out, _, changed, err := sanitizeXLSXPayload(src)
+	if err != nil {
+		t.Fatalf("sanitize error: %v", err)
+	}
+	if !changed {
+		t.Fatalf("expected changed=true for duplicate VML shape IDs")
+	}
+
+	outVML := readZipEntry(t, out, "xl/drawings/vmlDrawing1.vml")
+	if strings.Count(outVML, `id="_x0000_s1025"`) != 1 {
+		t.Fatalf("expected original shape id to appear once, got: %s", outVML)
+	}
+	if strings.Count(outVML, `id="_x0000_s1026"`) != 1 || strings.Count(outVML, `id="_x0000_s1027"`) != 1 {
+		t.Fatalf("expected duplicate ids to be uniqued, got: %s", outVML)
+	}
+}
diff --git a/internal/transport/http/handlers/office_xlsx_sanitizer_test.go b/internal/transport/http/handlers/office_xlsx_sanitizer_test.go
new file mode 100644
index 0000000..d8bf033
--- /dev/null
+++ b/internal/transport/http/handlers/office_xlsx_sanitizer_test.go
@@ -0,0 +1,510 @@
+package handlers
+
+import (
+	"archive/zip"
+	"bytes"
+	"context"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type officeSanitizerStorageMock struct {
+	objects        map[string][]byte
+	contentTypes   map[string]string
+	putObjectCalls int
+}
+
+type officeSanitizerServiceMock struct {
+	filemanager.Service
+	updateFileFn    func(context.Context, *filemanager.File) error
+	updateFileCalls int
+}
+
+func (m *officeSanitizerStorageMock) EnsureBucket(context.Context) error {
+	return nil
+}
+
+func (m *officeSanitizerStorageMock) PutObject(_ context.Context, input filemanager.PutObjectInput) (filemanager.ObjectMetadata, error) {
+	if m.objects == nil {
+		m.objects = map[string][]byte{}
+	}
+	if m.contentTypes == nil {
+		m.contentTypes = map[string]string{}
+	}
+
+	payload, err := io.ReadAll(input.Body)
+	if err != nil {
+		return filemanager.ObjectMetadata{}, err
+	}
+	m.putObjectCalls++
+	key := strings.TrimSpace(input.ObjectKey)
+	m.objects[key] = append([]byte(nil), payload...)
+	m.contentTypes[key] = strings.TrimSpace(input.ContentType)
+	now := time.Now().UTC()
+	return filemanager.ObjectMetadata{
+		Bucket:       "bucket",
+		ObjectKey:    key,
+		ETag:         "etag-" + key,
+		VersionID:    "version-" + key,
+		SizeBytes:    int64(len(payload)),
+		LastModified: &now,
+		ContentType:  strings.TrimSpace(input.ContentType),
+	}, nil
+}
+
+func (m *officeSanitizerStorageMock) DeleteObject(_ context.Context, objectKey string) error {
+	delete(m.objects, strings.TrimSpace(objectKey))
+	delete(m.contentTypes, strings.TrimSpace(objectKey))
+	return nil
+}
+
+func (m *officeSanitizerStorageMock) HeadObject(_ context.Context, objectKey string) (filemanager.ObjectMetadata, error) {
+	key := strings.TrimSpace(objectKey)
+	payload, ok := m.objects[key]
+	if !ok {
+		return filemanager.ObjectMetadata{}, filemanager.ErrUploadObjectNotFound
+	}
+	now := time.Now().UTC()
+	return filemanager.ObjectMetadata{
+		Bucket:       "bucket",
+		ObjectKey:    key,
+		ETag:         "etag-" + key,
+		VersionID:    "version-" + key,
+		SizeBytes:    int64(len(payload)),
+		LastModified: &now,
+		ContentType:  m.contentTypes[key],
+	}, nil
+}
+
+func (m *officeSanitizerStorageMock) PresignPutObject(context.Context, filemanager.PresignPutObjectInput) (filemanager.PresignedPutObject, error) {
+	return filemanager.PresignedPutObject{}, nil
+}
+
+func (m *officeSanitizerStorageMock) PresignGetObject(context.Context, string, time.Duration) (string, error) {
+	return "https://example.com/object", nil
+}
+
+func (m *officeSanitizerStorageMock) GetObject(_ context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+	key := strings.TrimSpace(objectKey)
+	payload, ok := m.objects[key]
+	if !ok {
+		return nil, filemanager.ObjectMetadata{}, filemanager.ErrUploadObjectNotFound
+	}
+	now := time.Now().UTC()
+	return io.NopCloser(bytes.NewReader(payload)), filemanager.ObjectMetadata{
+		Bucket:       "bucket",
+		ObjectKey:    key,
+		ETag:         "etag-" + key,
+		VersionID:    "version-" + key,
+		SizeBytes:    int64(len(payload)),
+		LastModified: &now,
+		ContentType:  m.contentTypes[key],
+	}, nil
+}
+
+func (m *officeSanitizerServiceMock) UpdateFile(ctx context.Context, row *filemanager.File) error {
+	m.updateFileCalls++
+	if m.updateFileFn != nil {
+		return m.updateFileFn(ctx, row)
+	}
+	return nil
+}
+
+func TestSanitizeXLSXPayload_FixesMalformedVMLStyleAndPreservesEntries(t *testing.T) {
+	original := testMalformedXLSXZip(t)
+
+	sanitized, fixCount, changed, err := sanitizeXLSXPayload(original)
+	if err != nil {
+		t.Fatalf("sanitize payload: %v", err)
+	}
+	if !changed {
+		t.Fatal("expected payload to be sanitized")
+	}
+	if fixCount == 0 {
+		t.Fatal("expected at least one style fix")
+	}
+
+	originalNames := zipEntryNames(t, original)
+	sanitizedNames := zipEntryNames(t, sanitized)
+	if len(originalNames) != len(sanitizedNames) {
+		t.Fatalf("zip entry count changed: %d -> %d", len(originalNames), len(sanitizedNames))
+	}
+	for i := range originalNames {
+		if originalNames[i] != sanitizedNames[i] {
+			t.Fatalf("zip entry order changed at %d: %q -> %q", i, originalNames[i], sanitizedNames[i])
+		}
+	}
+
+	vmlPayload := zipEntryPayload(t, sanitized, "xl/drawings/vmlDrawing1.vml")
+	if !bytes.Contains(vmlPayload, []byte(`margin-left:73.5pt`)) {
+		t.Fatalf("sanitized VML is missing margin-left fix: %s", string(vmlPayload))
+	}
+	if !bytes.Contains(vmlPayload, []byte(`margin-top:0pt`)) {
+		t.Fatalf("sanitized VML is missing margin-top fix: %s", string(vmlPayload))
+	}
+	if bytes.Contains(vmlPayload, []byte(`position:absolute;73.5pt;`)) {
+		t.Fatalf("sanitized VML still contains malformed style: %s", string(vmlPayload))
+	}
+}
+
+func TestSanitizeXLSXPayload_InjectsMissingVMLNoteShapeType(t *testing.T) {
+	original := testMalformedXLSXZip(t)
+
+	sanitized, _, changed, err := sanitizeXLSXPayload(original)
+	if err != nil {
+		t.Fatalf("sanitize payload: %v", err)
+	}
+	if !changed {
+		t.Fatal("expected payload to be sanitized")
+	}
+
+	vmlPayload := zipEntryPayload(t, sanitized, "xl/drawings/vmlDrawing1.vml")
+	if !bytes.Contains(vmlPayload, []byte(`<v:shapetype id="_x0000_t202"`)) {
+		t.Fatalf("sanitized VML is missing injected shapetype: %s", string(vmlPayload))
+	}
+	if !bytes.Contains(vmlPayload, []byte(`<o:shapelayout`)) {
+		t.Fatalf("sanitized VML is missing injected shapelayout: %s", string(vmlPayload))
+	}
+	// The injected shapetype must precede the shape that references it.
+	if bytes.Index(vmlPayload, []byte(`<v:shapetype`)) > bytes.Index(vmlPayload, []byte(`<v:shape id=`)) {
+		t.Fatalf("shapetype must be declared before the shape: %s", string(vmlPayload))
+	}
+}
+
+func TestEnsureVMLNoteShapeType_NoChangeWhenShapeTypePresent(t *testing.T) {
+	payload := []byte(`<xml xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">` +
+		`<v:shapetype id="_x0000_t202"></v:shapetype>` +
+		`<v:shape id="_x0000_s1025" type="#_x0000_t202"></v:shape></xml>`)
+
+	out, fixes, changed := ensureVMLNoteShapeType(payload)
+	if changed || fixes != 0 {
+		t.Fatalf("expected no change when shapetype already present, got changed=%v fixes=%d", changed, fixes)
+	}
+	if !bytes.Equal(out, payload) {
+		t.Fatal("payload should be returned unchanged")
+	}
+}
+
+func TestSanitizeStoredXLSXObject_RewritesStorageAndUpdatesRow(t *testing.T) {
+	original := testMalformedXLSXZip(t)
+	objectKey := "files/sample.xlsx"
+
+	storage := &officeSanitizerStorageMock{
+		objects: map[string][]byte{
+			objectKey: append([]byte(nil), original...),
+		},
+		contentTypes: map[string]string{
+			objectKey: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+		},
+	}
+
+	rowID := uuidv7.MustBytes()
+	updatedCalls := 0
+	var updatedRow *filemanager.File
+	svc := &officeSanitizerServiceMock{
+		updateFileFn: func(_ context.Context, row *filemanager.File) error {
+			updatedCalls++
+			if row == nil {
+				t.Fatal("expected row")
+			}
+			copyRow := *row
+			updatedRow = &copyRow
+			return nil
+		},
+	}
+	handler := NewFileManagerFileHandler(svc, storage)
+
+	row := &filemanager.File{
+		ID:            rowID,
+		Name:          "sample.xlsx",
+		ObjectKey:     objectKey,
+		MimeType:      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+		SizeBytes:     int64(len(original)),
+		Bucket:        "bucket",
+		ObjectVersion: "before-version",
+		ETag:          "before-etag",
+	}
+
+	changed, sizeBytes, err := handler.sanitizeStoredXLSXObject(context.Background(), row, row.ObjectKey, row.Name, row.MimeType, "test-upload")
+	if err != nil {
+		t.Fatalf("sanitize stored object: %v", err)
+	}
+	if !changed {
+		t.Fatal("expected storage object to be rewritten")
+	}
+	if sizeBytes != int64(len(storage.objects[objectKey])) {
+		t.Fatalf("expected sanitized size to match rewritten object, got %d want %d", sizeBytes, len(storage.objects[objectKey]))
+	}
+	if storage.putObjectCalls != 1 {
+		t.Fatalf("expected one PutObject call, got %d", storage.putObjectCalls)
+	}
+	if updatedCalls != 1 {
+		t.Fatalf("expected one UpdateFile call, got %d", updatedCalls)
+	}
+	if row.SizeBytes == int64(len(original)) {
+		t.Fatal("expected row size to change after sanitization")
+	}
+	if row.ObjectVersion == "before-version" || row.ETag == "before-etag" {
+		t.Fatal("expected row storage metadata to be refreshed")
+	}
+	if updatedRow == nil || updatedRow.SizeBytes != row.SizeBytes {
+		t.Fatal("expected updated row to reflect sanitized size")
+	}
+	if !bytes.Contains(zipEntryPayload(t, storage.objects[objectKey], "xl/drawings/vmlDrawing1.vml"), []byte(`margin-left:73.5pt`)) {
+		t.Fatal("stored object was not sanitized")
+	}
+}
+
+func TestSanitizeXLSXPayload_LibreOfficeRoundTrip_NoRepairWarning(t *testing.T) {
+	sofficePath, err := exec.LookPath("soffice")
+	if err != nil {
+		t.Skip("soffice not available")
+	}
+
+	original := testMalformedXLSXZip(t)
+	sanitized, _, changed, err := sanitizeXLSXPayload(original)
+	if err != nil {
+		t.Fatalf("sanitize payload: %v", err)
+	}
+	if !changed {
+		t.Fatal("expected payload to be sanitized")
+	}
+
+	tempDir := t.TempDir()
+	inputPath := filepath.Join(tempDir, "sample.xlsx")
+	if err := os.WriteFile(inputPath, sanitized, 0o600); err != nil {
+		t.Fatalf("write sanitized file: %v", err)
+	}
+
+	outDir := filepath.Join(tempDir, "out")
+	if err := os.Mkdir(outDir, 0o755); err != nil {
+		t.Fatalf("mkdir out dir: %v", err)
+	}
+
+	cmd := exec.Command(sofficePath, "--headless", "--convert-to", "xlsx", "--outdir", outDir, inputPath)
+	output, runErr := cmd.CombinedOutput()
+	if runErr != nil {
+		t.Fatalf("soffice convert failed: %v\n%s", runErr, string(output))
+	}
+	lowerOutput := strings.ToLower(string(output))
+	if strings.Contains(lowerOutput, "repair") || strings.Contains(lowerOutput, "corrupt") {
+		t.Fatalf("unexpected repair warning from soffice: %s", string(output))
+	}
+
+	outputPath := filepath.Join(outDir, "sample.xlsx")
+	if _, err := os.Stat(outputPath); err != nil {
+		t.Fatalf("expected converted file: %v", err)
+	}
+
+	wantComments := zipPartCountByPrefixBytes(t, sanitized, "xl/comments")
+	if got := zipPartCountByPrefix(t, outputPath, "xl/comments"); got != wantComments {
+		t.Fatalf("unexpected comments part count: got %d want %d", got, wantComments)
+	}
+	wantVML := zipPartCountByPrefixBytes(t, sanitized, "xl/drawings/vmlDrawing")
+	if got := zipPartCountByPrefix(t, outputPath, "xl/drawings/vmlDrawing"); got != wantVML {
+		t.Fatalf("unexpected vml drawing part count: got %d want %d", got, wantVML)
+	}
+}
+
+func testMalformedXLSXZip(t *testing.T) []byte {
+	t.Helper()
+
+	return orderedOfficeZip(t, []zipEntry{
+		{
+			name: "[Content_Types].xml",
+			body: `<?xml version="1.0" encoding="UTF-8"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+  <Default Extension="vml" ContentType="application/vnd.openxmlformats-officedocument.vmlDrawing"/>
+  <Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>
+  <Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>
+  <Override PartName="/xl/comments1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.comments+xml"/>
+</Types>`,
+		},
+		{
+			name: "_rels/.rels",
+			body: `<?xml version="1.0" encoding="UTF-8"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>
+</Relationships>`,
+		},
+		{
+			name: "xl/workbook.xml",
+			body: `<?xml version="1.0" encoding="UTF-8"?>
+<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+  xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+  <sheets>
+    <sheet name="Sheet1" sheetId="1" r:id="rId1"/>
+  </sheets>
+</workbook>`,
+		},
+		{
+			name: "xl/_rels/workbook.xml.rels",
+			body: `<?xml version="1.0" encoding="UTF-8"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>
+</Relationships>`,
+		},
+		{
+			name: "xl/worksheets/sheet1.xml",
+			body: `<?xml version="1.0" encoding="UTF-8"?>
+<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+  xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
+  <sheetData/>
+  <legacyDrawing r:id="rId1"/>
+</worksheet>`,
+		},
+		{
+			name: "xl/worksheets/_rels/sheet1.xml.rels",
+			body: `<?xml version="1.0" encoding="UTF-8"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments" Target="../comments1.xml"/>
+  <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/vmlDrawing" Target="../drawings/vmlDrawing1.vml"/>
+</Relationships>`,
+		},
+		{
+			name: "xl/comments1.xml",
+			body: `<?xml version="1.0" encoding="UTF-8"?>
+<comments xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
+  <authors><author>OpenAI</author></authors>
+  <commentList>
+    <comment ref="A1" authorId="0">
+      <text><t>Example note</t></text>
+    </comment>
+  </commentList>
+</comments>`,
+		},
+		{
+			name: "xl/drawings/vmlDrawing1.vml",
+			body: `<?xml version="1.0" encoding="UTF-8"?>
+<xml xmlns:v="urn:schemas-microsoft-com:vml"
+     xmlns:o="urn:schemas-microsoft-com:office:office">
+  <v:shape id="_x0000_s1025" type="#_x0000_t202"
+    style="position:absolute;73.5pt;width:108pt;height:59.25pt;z-index:1;visibility:hidden">
+    <v:textbox>
+      <div>Example note</div>
+    </v:textbox>
+  </v:shape>
+</xml>`,
+		},
+		{
+			name: "xl/styles.xml",
+			body: `<?xml version="1.0" encoding="UTF-8"?>
+<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">
+  <fonts count="1"><font/></fonts>
+  <fills count="1"><fill/></fills>
+  <borders count="1"><border/></borders>
+  <cellStyleXfs count="1"><xf/></cellStyleXfs>
+  <cellXfs count="1"><xf xfId="0"/></cellXfs>
+</styleSheet>`,
+		},
+	})
+}
+
+func orderedOfficeZip(t *testing.T, entries []zipEntry) []byte {
+	t.Helper()
+
+	var buf bytes.Buffer
+	writer := zip.NewWriter(&buf)
+	for _, entry := range entries {
+		w, err := writer.Create(entry.name)
+		if err != nil {
+			t.Fatalf("create zip entry %q: %v", entry.name, err)
+		}
+		if _, err := w.Write([]byte(entry.body)); err != nil {
+			t.Fatalf("write zip entry %q: %v", entry.name, err)
+		}
+	}
+	if err := writer.Close(); err != nil {
+		t.Fatalf("close zip: %v", err)
+	}
+	return buf.Bytes()
+}
+
+type zipEntry struct {
+	name string
+	body string
+}
+
+func zipEntryNames(t *testing.T, payload []byte) []string {
+	t.Helper()
+
+	reader := mustOpenZipReader(t, payload)
+	names := make([]string, 0, len(reader.File))
+	for _, file := range reader.File {
+		names = append(names, file.Name)
+	}
+	return names
+}
+
+func zipEntryPayload(t *testing.T, payload []byte, name string) []byte {
+	t.Helper()
+
+	reader := mustOpenZipReader(t, payload)
+	for _, file := range reader.File {
+		if file.Name != name {
+			continue
+		}
+		rc, err := file.Open()
+		if err != nil {
+			t.Fatalf("open zip entry %q: %v", name, err)
+		}
+		defer rc.Close()
+		data, err := io.ReadAll(rc)
+		if err != nil {
+			t.Fatalf("read zip entry %q: %v", name, err)
+		}
+		return data
+	}
+	t.Fatalf("missing zip entry %q", name)
+	return nil
+}
+
+func zipPartCountByPrefix(t *testing.T, path string, prefix string) int {
+	t.Helper()
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read zip file: %v", err)
+	}
+	reader := mustOpenZipReader(t, data)
+	count := 0
+	for _, file := range reader.File {
+		if strings.HasPrefix(file.Name, prefix) {
+			count++
+		}
+	}
+	return count
+}
+
+func zipPartCountByPrefixBytes(t *testing.T, payload []byte, prefix string) int {
+	t.Helper()
+
+	reader := mustOpenZipReader(t, payload)
+	count := 0
+	for _, file := range reader.File {
+		if strings.HasPrefix(file.Name, prefix) {
+			count++
+		}
+	}
+	return count
+}
+
+func mustOpenZipReader(t *testing.T, payload []byte) *zip.Reader {
+	t.Helper()
+
+	reader, err := zip.NewReader(bytes.NewReader(payload), int64(len(payload)))
+	if err != nil {
+		t.Fatalf("open zip: %v", err)
+	}
+	return reader
+}
diff --git a/internal/transport/http/handlers/opc_handler.go b/internal/transport/http/handlers/opc_handler.go
new file mode 100644
index 0000000..88a09fc
--- /dev/null
+++ b/internal/transport/http/handlers/opc_handler.go
@@ -0,0 +1,452 @@
+package handlers
+
+import (
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/opc"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type OpcHandler struct {
+	svc      opc.Service
+	validate *validators.Validator
+}
+
+func NewOpcHandler(svc opc.Service) *OpcHandler {
+	return &OpcHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateOpc godoc
+// @Summary Create opc
+// @Description Create an OPC row.
+// @Tags OPC - OPC
+// @Accept json
+// @Produce json
+// @Param request body dto.OpcCreateRequest true "JSON:API OPC create request"
+// @Success 201 {object} dto.OpcResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/opc/create [post]
+func (h *OpcHandler) Create(c *fiber.Ctx) error {
+	var req dto.OpcCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeOpcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeOpcErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	title := strings.TrimSpace(req.Data.Attributes.Title)
+	if title == "" {
+		return writeOpcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "title is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/title"},
+		}})
+	}
+
+	row := &opc.Opc{
+		Title:     title,
+		SortKey:   cloneIntPointer(req.Data.Attributes.SortKey),
+		Note:      strings.TrimSpace(stringOrDefault(req.Data.Attributes.Note, "")),
+		IsActive:  boolOrDefault(req.Data.Attributes.IsActive, true),
+		CreatedBy: actorUserID(c),
+		UpdatedBy: actorUserID(c),
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeOpcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, opcResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, opcResource(row))
+}
+
+// UpdateOpc godoc
+// @Summary Update opc (partial)
+// @Description Patch opc by ID.
+// @Tags OPC - OPC
+// @Accept json
+// @Produce json
+// @Param uuid path string true "OPC UUID (UUIDv7)"
+// @Param request body dto.OpcUpdateRequest true "JSON:API OPC update request"
+// @Success 200 {object} dto.OpcResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/opc/update/{uuid} [patch]
+func (h *OpcHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeOpcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.OpcUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeOpcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeOpcErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeOpcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeOpcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Title == nil && !attrs.SortKey.Set && attrs.Note == nil && attrs.IsActive == nil {
+		return writeOpcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeOpcErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "opc not found",
+		}})
+	}
+
+	if attrs.Title != nil {
+		v := strings.TrimSpace(*attrs.Title)
+		if v == "" {
+			return writeOpcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "title cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/title"},
+			}})
+		}
+		existing.Title = v
+	}
+	if attrs.SortKey.Set {
+		if attrs.SortKey.Valid {
+			sortKey := attrs.SortKey.Value
+			existing.SortKey = &sortKey
+		} else {
+			existing.SortKey = nil
+		}
+	}
+	if attrs.Note != nil {
+		existing.Note = strings.TrimSpace(*attrs.Note)
+	}
+	if attrs.IsActive != nil {
+		existing.IsActive = *attrs.IsActive
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeOpcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, opcResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, opcResource(existing))
+}
+
+// DeleteOpc godoc
+// @Summary Delete opc
+// @Tags OPC - OPC
+// @Produce json
+// @Param uuid path string true "OPC UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/opc/delete/{uuid} [delete]
+func (h *OpcHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeOpcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeOpcErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "opc not found",
+			}})
+		}
+		return writeOpcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "opc_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListOpc godoc
+// @Summary List opc
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: title, -title, sortkey, -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.
+// @Tags OPC - OPC
+// @Produce json
+// @Param filter[search] query string false "Search by title/note"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.OpcListResponse
+// @Router /api/v1/opc/get-all [get]
+func (h *OpcHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("filter[name]")
+	}
+	if filter == "" {
+		filter = c.Query("search")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return writeOpcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.OpcResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, opcResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListOpcDatatable godoc
+// @Summary List opc (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags OPC - OPC
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.OpcDataTableResponse
+// @Router /api/v1/opc/get-all/dt [get]
+func (h *OpcHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return writeOpcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.OpcResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, opcResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func opcResource(o *opc.Opc) dto.OpcResource {
+	return dto.OpcResource{
+		Type: "opc",
+		ID:   idString(o.ID),
+		Attributes: dto.OpcAttributes{
+			Title:     o.Title,
+			SortKey:   cloneIntPointer(o.SortKey),
+			Note:      o.Note,
+			IsActive:  o.IsActive,
+			CreatedAt: o.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy: uuidStringOrEmpty(o.CreatedBy),
+			UpdatedAt: o.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy: uuidStringOrEmpty(o.UpdatedBy),
+			DeletedAt: timeStringOrEmpty(o.DeletedAt),
+			DeletedBy: uuidStringOrEmpty(o.DeletedBy),
+		},
+	}
+}
+
+func writeOpcErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		if strings.TrimSpace(e.Code) == "" || strings.TrimSpace(e.ErrorCode) == "" {
+			code, errorCode := inferOpcErrorCode(status, e.Title, e.Detail)
+			if strings.TrimSpace(e.Code) == "" {
+				e.Code = code
+			}
+			if strings.TrimSpace(e.ErrorCode) == "" {
+				e.ErrorCode = errorCode
+			}
+		}
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferOpcErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.CodeOPCNotFound, apperrorsx.ErrOPCNotFound.ErrorCode
+	case fiber.StatusConflict:
+		return apperrorsx.CodeOPCRelationDelete, apperrorsx.ErrOPCRelationDelete.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid"):
+			return apperrorsx.CodeOPCInvalidUUID, apperrorsx.ErrOPCInvalidUUID.ErrorCode
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.CodeOPCIDRequired, apperrorsx.ErrOPCIDRequired.ErrorCode
+		case strings.Contains(lowerDetail, "id does not match"):
+			return apperrorsx.CodeOPCIDMismatch, apperrorsx.ErrOPCIDMismatch.ErrorCode
+		case strings.Contains(lowerDetail, "at least one attribute"):
+			return apperrorsx.CodeOPCAttributesRequired, apperrorsx.ErrOPCAttributesRequired.ErrorCode
+		case strings.Contains(lowerDetail, "title is required"), strings.Contains(lowerDetail, "title cannot be empty"):
+			return apperrorsx.CodeOPCTitleRequired, apperrorsx.ErrOPCTitleRequired.ErrorCode
+		default:
+			return apperrorsx.CodeOPCInvalidPayload, apperrorsx.ErrOPCInvalidPayload.ErrorCode
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.CodeOPCInvalidJSON, apperrorsx.ErrOPCInvalidJSON.ErrorCode
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.CodeOPCCreateFailed, apperrorsx.ErrOPCCreateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.CodeOPCUpdateFailed, apperrorsx.ErrOPCUpdateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.CodeOPCDeleteFailed, apperrorsx.ErrOPCDeleteFailed.ErrorCode
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.CodeOPCListFailed, apperrorsx.ErrOPCListFailed.ErrorCode
+		default:
+			return apperrorsx.CodeOPCInvalidPayload, apperrorsx.ErrOPCInvalidPayload.ErrorCode
+		}
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
diff --git a/internal/transport/http/handlers/opc_handler_test.go b/internal/transport/http/handlers/opc_handler_test.go
new file mode 100644
index 0000000..2e16eef
--- /dev/null
+++ b/internal/transport/http/handlers/opc_handler_test.go
@@ -0,0 +1,585 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/opc"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type memOpcRepo struct {
+	rows map[string]*opc.Opc
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+
+	listRows  []opc.Opc
+	listTotal int64
+
+	getByIDFn func(id []byte, call int) (*opc.Opc, error)
+	getCalls  int
+
+	lastCreate     *opc.Opc
+	lastUpdate     *opc.Opc
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+}
+
+func newMemOpcRepo() *memOpcRepo {
+	return &memOpcRepo{
+		rows: map[string]*opc.Opc{},
+	}
+}
+
+func (r *memOpcRepo) Create(_ context.Context, row *opc.Opc) error {
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.rows[string(row.ID)] = row
+	r.lastCreate = row
+	return nil
+}
+
+func (r *memOpcRepo) Update(_ context.Context, row *opc.Opc) error {
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	r.rows[string(row.ID)] = row
+	r.lastUpdate = row
+	return nil
+}
+
+func (r *memOpcRepo) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	r.lastDeleteID = append([]byte(nil), id...)
+	r.lastDeleteBy = append([]byte(nil), deletedBy...)
+	delete(r.rows, string(id))
+	return nil
+}
+
+func (r *memOpcRepo) GetByID(_ context.Context, id []byte) (*opc.Opc, error) {
+	r.getCalls++
+	if r.getByIDFn != nil {
+		return r.getByIDFn(id, r.getCalls)
+	}
+	if r.getByIDErr != nil {
+		return nil, r.getByIDErr
+	}
+	return r.rows[string(id)], nil
+}
+
+func (r *memOpcRepo) List(_ context.Context, filter, sort string, limit, offset int) ([]opc.Opc, int64, error) {
+	r.lastListFilter = filter
+	r.lastListSort = sort
+	r.lastListLimit = limit
+	r.lastListOffset = offset
+	if r.listErr != nil {
+		return nil, 0, r.listErr
+	}
+	return r.listRows, r.listTotal, nil
+}
+
+func newOpcTestApp(h *OpcHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", actor)
+		}
+		return c.Next()
+	})
+	app.Post("/api/v1/opc/create", h.Create)
+	app.Patch("/api/v1/opc/update/:uuid", h.Update)
+	app.Delete("/api/v1/opc/delete/:uuid", h.Delete)
+	app.Get("/api/v1/opc/get-all", h.List)
+	app.Get("/api/v1/opc/get-all/dt", h.ListDatatable)
+	return app
+}
+
+func doJSONRequest(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDString(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestNewOpcHandler(t *testing.T) {
+	h := NewOpcHandler(service.NewOpcService(newMemOpcRepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+func TestOpcHandlerCreate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		resp, _ := doJSONRequest(t, app, http.MethodPost, "/api/v1/opc/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		resp, _ := doJSONRequest(t, app, http.MethodPost, "/api/v1/opc/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("title empty", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"opc","attributes":{"title":"  "}}}`)
+		resp, _ := doJSONRequest(t, app, http.MethodPost, "/api/v1/opc/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		repo.createErr = errors.New("create failed")
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"opc","attributes":{"title":"Main"}}}`)
+		resp, _ := doJSONRequest(t, app, http.MethodPost, "/api/v1/opc/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		actor := uuidv7.MustBytes()
+		app := newOpcTestApp(h, actor)
+
+		body := []byte(`{"data":{"type":"opc","attributes":{"title":"Main","sortkey":3,"note":"Center","is_active":false}}}`)
+		resp, _ := doJSONRequest(t, app, http.MethodPost, "/api/v1/opc/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected row created")
+		}
+		if repo.lastCreate.SortKey == nil || *repo.lastCreate.SortKey != 3 {
+			t.Fatalf("expected sortkey mapped on create")
+		}
+		if repo.lastCreate.Note != "Center" {
+			t.Fatalf("expected note/description mapped on create")
+		}
+		if repo.lastCreate.IsActive {
+			t.Fatalf("expected is_active=false to be mapped")
+		}
+		if string(repo.lastCreate.CreatedBy) != string(actor) || string(repo.lastCreate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected created_by and updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback when refetch error", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		repo.getByIDFn = func(_ []byte, call int) (*opc.Opc, error) {
+			if call > 0 {
+				return nil, errors.New("lookup failed")
+			}
+			return nil, nil
+		}
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"opc","attributes":{"title":"Main"}}}`)
+		resp, _ := doJSONRequest(t, app, http.MethodPost, "/api/v1/opc/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestOpcHandlerUpdate(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		resp, _ := doJSONRequest(t, app, http.MethodPatch, "/api/v1/opc/update/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+		id := mustUUIDString(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequest(t, app, http.MethodPatch, "/api/v1/opc/update/"+id, []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+		id := mustUUIDString(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequest(t, app, http.MethodPatch, "/api/v1/opc/update/"+id, []byte(`{"data":{"type":"x","id":"`+id+`","attributes":{"title":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+		id := mustUUIDString(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequest(t, app, http.MethodPatch, "/api/v1/opc/update/"+id, []byte(`{"data":{"type":"opc","id":"","attributes":{"title":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+		id := mustUUIDString(t, uuidv7.MustBytes())
+		other := mustUUIDString(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequest(t, app, http.MethodPatch, "/api/v1/opc/update/"+id, []byte(`{"data":{"type":"opc","id":"`+other+`","attributes":{"title":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no attributes", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+		id := mustUUIDString(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequest(t, app, http.MethodPatch, "/api/v1/opc/update/"+id, []byte(`{"data":{"type":"opc","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+		id := mustUUIDString(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequest(t, app, http.MethodPatch, "/api/v1/opc/update/"+id, []byte(`{"data":{"type":"opc","id":"`+id+`","attributes":{"title":"A"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("title empty", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &opc.Opc{ID: id, Title: "Old"}
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+		idStr := mustUUIDString(t, id)
+
+		resp, _ := doJSONRequest(t, app, http.MethodPatch, "/api/v1/opc/update/"+idStr, []byte(`{"data":{"type":"opc","id":"`+idStr+`","attributes":{"title":"  "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &opc.Opc{ID: id, Title: "Old"}
+		repo.updateErr = errors.New("update failed")
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+		idStr := mustUUIDString(t, id)
+
+		resp, _ := doJSONRequest(t, app, http.MethodPatch, "/api/v1/opc/update/"+idStr, []byte(`{"data":{"type":"opc","id":"`+idStr+`","attributes":{"title":"New"}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &opc.Opc{ID: id, Title: "Old"}
+		h := NewOpcHandler(service.NewOpcService(repo))
+		actor := uuidv7.MustBytes()
+		app := newOpcTestApp(h, actor)
+		idStr := mustUUIDString(t, id)
+
+		resp, _ := doJSONRequest(t, app, http.MethodPatch, "/api/v1/opc/update/"+idStr, []byte(`{"data":{"type":"opc","id":"`+idStr+`","attributes":{"title":"New","sortkey":7,"note":"Desc","is_active":false}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.Title != "New" {
+			t.Fatalf("expected updated values")
+		}
+		if repo.lastUpdate.SortKey == nil || *repo.lastUpdate.SortKey != 7 || repo.lastUpdate.Note != "Desc" {
+			t.Fatalf("expected sortkey/note updated values")
+		}
+		if repo.lastUpdate.IsActive {
+			t.Fatalf("expected is_active=false updated")
+		}
+		if string(repo.lastUpdate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		id := uuidv7.MustBytes()
+		existing := &opc.Opc{ID: id, Title: "Old"}
+		repo.getByIDFn = func(_ []byte, call int) (*opc.Opc, error) {
+			if call == 1 {
+				return existing, nil
+			}
+			return nil, errors.New("second lookup failed")
+		}
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+		idStr := mustUUIDString(t, id)
+
+		resp, _ := doJSONRequest(t, app, http.MethodPatch, "/api/v1/opc/update/"+idStr, []byte(`{"data":{"type":"opc","id":"`+idStr+`","attributes":{"note":"Only note"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestOpcHandlerDelete(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		resp, _ := doJSONRequest(t, app, http.MethodDelete, "/api/v1/opc/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete error", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		repo.deleteErr = errors.New("delete failed")
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+		id := mustUUIDString(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequest(t, app, http.MethodDelete, "/api/v1/opc/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		h := NewOpcHandler(service.NewOpcService(repo))
+		actor := uuidv7.MustBytes()
+		app := newOpcTestApp(h, actor)
+		id := uuidv7.MustBytes()
+		idStr := mustUUIDString(t, id)
+
+		resp, _ := doJSONRequest(t, app, http.MethodDelete, "/api/v1/opc/delete/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(repo.lastDeleteBy) != string(actor) {
+			t.Fatalf("expected deleted_by from actor")
+		}
+	})
+}
+
+func TestOpcHandlerList(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		resp, _ := doJSONRequest(t, app, http.MethodGet, "/api/v1/opc/get-all", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with filter name and clamp max", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		repo.listRows = []opc.Opc{{ID: uuidv7.MustBytes(), Title: "A", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		resp, _ := doJSONRequest(t, app, http.MethodGet, "/api/v1/opc/get-all?filter[name]=abc&page[number]=0&page=0&page[size]=0&limit=101&sort=-sortkey", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q sort=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListSort, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success with search and clamp min", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		repo.listRows = []opc.Opc{}
+		repo.listTotal = 0
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		resp, _ := doJSONRequest(t, app, http.MethodGet, "/api/v1/opc/get-all?page=2&size=-1&search=needle", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "needle" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestOpcHandlerListDatatable(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		resp, _ := doJSONRequest(t, app, http.MethodGet, "/api/v1/opc/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success clamp max and page floor", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		repo.listRows = []opc.Opc{{ID: uuidv7.MustBytes(), Title: "A", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		resp, _ := doJSONRequest(t, app, http.MethodGet, "/api/v1/opc/get-all/dt?page=0&limit=0&size=101&draw=7&search=abc", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListLimit != 100 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success clamp min", func(t *testing.T) {
+		repo := newMemOpcRepo()
+		repo.listRows = []opc.Opc{}
+		repo.listTotal = 0
+		h := NewOpcHandler(service.NewOpcService(repo))
+		app := newOpcTestApp(h, nil)
+
+		resp, _ := doJSONRequest(t, app, http.MethodGet, "/api/v1/opc/get-all/dt?page=2&limit=0&size=-1", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListLimit != 20 || repo.lastListOffset != 20 {
+			t.Fatalf("unexpected list params: limit=%d offset=%d", repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestOpcResource(t *testing.T) {
+	id := uuidv7.MustBytes()
+	createdBy := uuidv7.MustBytes()
+	updatedBy := uuidv7.MustBytes()
+	deletedBy := uuidv7.MustBytes()
+	now := time.Now().UTC().Truncate(time.Second)
+	deletedAt := now.Add(time.Hour)
+
+	row := &opc.Opc{
+		ID:        id,
+		Title:     "Main",
+		SortKey:   intPtrOpcHandler(5),
+		Note:      "Center",
+		IsActive:  true,
+		CreatedAt: now,
+		CreatedBy: createdBy,
+		UpdatedAt: now,
+		UpdatedBy: updatedBy,
+		DeletedAt: &deletedAt,
+		DeletedBy: deletedBy,
+	}
+
+	res := opcResource(row)
+	if res.Type != "opc" {
+		t.Fatalf("unexpected type: %s", res.Type)
+	}
+	if res.ID == "" || res.Attributes.CreatedBy == "" || res.Attributes.UpdatedBy == "" || res.Attributes.DeletedBy == "" {
+		t.Fatalf("expected UUID fields in resource")
+	}
+	if !res.Attributes.IsActive {
+		t.Fatalf("expected is_active mapped")
+	}
+	if res.Attributes.SortKey == nil || *res.Attributes.SortKey != 5 || res.Attributes.Note != "Center" {
+		t.Fatalf("expected sortkey/note mapped")
+	}
+	if res.Attributes.CreatedAt == "" || res.Attributes.UpdatedAt == "" || res.Attributes.DeletedAt == "" {
+		t.Fatalf("expected time fields in resource")
+	}
+}
+
+func intPtrOpcHandler(v int) *int { return &v }
diff --git a/internal/transport/http/handlers/operation_relation_error_mapper.go b/internal/transport/http/handlers/operation_relation_error_mapper.go
new file mode 100644
index 0000000..021c2e0
--- /dev/null
+++ b/internal/transport/http/handlers/operation_relation_error_mapper.go
@@ -0,0 +1,52 @@
+package handlers
+
+import (
+	"errors"
+	"strings"
+
+	mysqldriver "github.com/go-sql-driver/mysql"
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/transport/http/jsonapi"
+)
+
+type relationFieldError struct {
+	Pointer string
+	Detail  string
+}
+
+func mapOperationRelationError(err error, relationMap map[string]relationFieldError) (int, []jsonapi.ErrorObject, bool) {
+	var mysqlErr *mysqldriver.MySQLError
+	if !errors.As(err, &mysqlErr) {
+		return 0, nil, false
+	}
+
+	msg := strings.ToLower(strings.TrimSpace(mysqlErr.Message))
+	switch mysqlErr.Number {
+	case 1452:
+		for token, rel := range relationMap {
+			t := strings.ToLower(strings.TrimSpace(token))
+			if t != "" && strings.Contains(msg, t) {
+				return fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+					Status: "422",
+					Title:  "Validation error",
+					Detail: rel.Detail,
+					Source: &jsonapi.ErrorSource{Pointer: rel.Pointer},
+				}}, true
+			}
+		}
+		return fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "referenced relation data was not found",
+		}}, true
+	case 1451:
+		return fiber.StatusConflict, []jsonapi.ErrorObject{{
+			Status: "409",
+			Title:  "Conflict",
+			Detail: "cannot delete because this data is still referenced by other records",
+		}}, true
+	default:
+		return 0, nil, false
+	}
+}
diff --git a/internal/transport/http/handlers/other_person_handler.go b/internal/transport/http/handlers/other_person_handler.go
new file mode 100644
index 0000000..0b517f8
--- /dev/null
+++ b/internal/transport/http/handlers/other_person_handler.go
@@ -0,0 +1,185 @@
+package handlers
+
+import (
+	"errors"
+	"strconv"
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	otherperson "wucher/internal/domain/other_person"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	"wucher/internal/transport/http/response"
+)
+
+// OtherPersonHandler serves the reusable, non-staff "other person" master (a picker for
+// takeover other-people). It never mixes with contacts/staff.
+type OtherPersonHandler struct {
+	svc otherperson.Service
+}
+
+func NewOtherPersonHandler(svc otherperson.Service) *OtherPersonHandler {
+	return &OtherPersonHandler{svc: svc}
+}
+
+func otherPersonResource(p *otherperson.OtherPerson) responsedto.OtherPersonResource {
+	return responsedto.OtherPersonResource{
+		Type: "other_person",
+		ID:   idString(p.ID),
+		Attributes: responsedto.OtherPersonAttributes{
+			Name:        p.Name,
+			MobilePhone: p.MobilePhone,
+			Email:       p.Email,
+		},
+	}
+}
+
+// writeOtherPersonError maps service/domain errors to the right HTTP status.
+func writeOtherPersonError(c *fiber.Ctx, err error) error {
+	switch {
+	case errors.Is(err, otherperson.ErrNameRequired):
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrValidation).WithCause(err))
+	case errors.Is(err, otherperson.ErrDuplicate):
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrBusinessRuleFailed).WithCause(err))
+	case errors.Is(err, otherperson.ErrNotFound):
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrDataNotFound).WithCause(err))
+	default:
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrInternal).WithCause(err))
+	}
+}
+
+// Search godoc
+// @Summary Search reusable "other people" (non-staff) for the takeover picker
+// @Description Lists master other-people whose name/mobile_phone/email matches `q` (empty `q` = most recent). Pick one and pass its id as `other_person_id` in a takeover's other_person to reuse without re-entering the data.
+// @Tags Contact - Other People
+// @Produce json
+// @Param q query string false "Search text (name / mobile_phone / email)"
+// @Param limit query int false "Max results (default 20)"
+// @Param offset query int false "Offset"
+// @Success 200 {object} responsedto.OtherPersonListResponse
+// @Router /api/v1/contact/other [get]
+func (h *OtherPersonHandler) Search(c *fiber.Ctx) error {
+	q := strings.TrimSpace(c.Query("q"))
+	limit, _ := strconv.Atoi(c.Query("limit"))
+	offset, _ := strconv.Atoi(c.Query("offset"))
+	rows, total, err := h.svc.Search(c.UserContext(), q, limit, offset)
+	if err != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrInternal).WithCause(err))
+	}
+	data := make([]responsedto.OtherPersonResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, otherPersonResource(&rows[i]))
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, data, map[string]any{"total": total})
+}
+
+// Get godoc
+// @Summary Get one reusable "other person"
+// @Tags Contact - Other People
+// @Produce json
+// @Param id path string true "Other person id"
+// @Success 200 {object} responsedto.OtherPersonResponse
+// @Router /api/v1/contact/other/get/{id} [get]
+func (h *OtherPersonHandler) Get(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrInvalidRequest).WithCause(err))
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrInternal).WithCause(err))
+	}
+	if row == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrDataNotFound))
+	}
+	return response.Write(c, fiber.StatusOK, otherPersonResource(row))
+}
+
+// Create godoc
+// @Summary Create a reusable "other person" (non-staff)
+// @Description Registers a person in the other-people master so it can be reused across takeovers. The (name, mobile_phone, email) identity must be unique.
+// @Tags Contact - Other People
+// @Accept json
+// @Produce json
+// @Param request body requestdto.OtherPersonRequest true "Other person"
+// @Success 201 {object} responsedto.OtherPersonResponse
+// @Router /api/v1/contact/other/create [post]
+func (h *OtherPersonHandler) Create(c *fiber.Ctx) error {
+	var req requestdto.OtherPersonRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeBodyParseError(c, err, apperrorsx.ErrInvalidRequest)
+	}
+	actor := actorUserID(c)
+	p := &otherperson.OtherPerson{
+		Name:        req.Data.Attributes.Name,
+		MobilePhone: req.Data.Attributes.MobilePhone,
+		Email:       req.Data.Attributes.Email,
+		CreatedBy:   actor,
+		UpdatedBy:   actor,
+	}
+	if err := h.svc.Create(c.UserContext(), p); err != nil {
+		return writeOtherPersonError(c, err)
+	}
+	return response.Write(c, fiber.StatusCreated, otherPersonResource(p))
+}
+
+// Update godoc
+// @Summary Update a reusable "other person"
+// @Description Replaces the name/mobile_phone/email of a master person. The new identity must not collide with another person.
+// @Tags Contact - Other People
+// @Accept json
+// @Produce json
+// @Param id path string true "Other person id"
+// @Param request body requestdto.OtherPersonRequest true "Other person"
+// @Success 200 {object} responsedto.OtherPersonResponse
+// @Router /api/v1/contact/other/update/{id} [patch]
+func (h *OtherPersonHandler) Update(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrInvalidRequest).WithCause(err))
+	}
+	var req requestdto.OtherPersonRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeBodyParseError(c, err, apperrorsx.ErrInvalidRequest)
+	}
+	p := &otherperson.OtherPerson{
+		ID:          id,
+		Name:        req.Data.Attributes.Name,
+		MobilePhone: req.Data.Attributes.MobilePhone,
+		Email:       req.Data.Attributes.Email,
+		UpdatedBy:   actorUserID(c),
+	}
+	if err := h.svc.Update(c.UserContext(), p); err != nil {
+		return writeOtherPersonError(c, err)
+	}
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrInternal).WithCause(err))
+	}
+	if row == nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrDataNotFound))
+	}
+	return response.Write(c, fiber.StatusOK, otherPersonResource(row))
+}
+
+// Delete godoc
+// @Summary Delete a reusable "other person"
+// @Description Soft-deletes a master person. Existing takeover snapshots keep their own copy of the data.
+// @Tags Contact - Other People
+// @Produce json
+// @Param id path string true "Other person id"
+// @Success 200 {object} map[string]interface{}
+// @Router /api/v1/contact/other/delete/{id} [delete]
+func (h *OtherPersonHandler) Delete(c *fiber.Ctx) error {
+	id, err := uuidv7.ParseString(strings.TrimSpace(c.Params("id")))
+	if err != nil {
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrInvalidRequest).WithCause(err))
+	}
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		return writeOtherPersonError(c, err)
+	}
+	return response.Write(c, fiber.StatusOK, map[string]any{"id": idString(id), "deleted": true})
+}
diff --git a/internal/transport/http/handlers/other_person_handler_test.go b/internal/transport/http/handlers/other_person_handler_test.go
new file mode 100644
index 0000000..685dffa
--- /dev/null
+++ b/internal/transport/http/handlers/other_person_handler_test.go
@@ -0,0 +1,265 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/gofiber/fiber/v2"
+
+	otherperson "wucher/internal/domain/other_person"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type fakeOtherPersonService struct {
+	rows  []otherperson.OtherPerson
+	total int64
+	err   error
+
+	lastQ      string
+	lastLimit  int
+	lastOffset int
+
+	lastCreate   *otherperson.OtherPerson
+	lastUpdate   *otherperson.OtherPerson
+	lastDeleteID []byte
+}
+
+func (f *fakeOtherPersonService) Upsert(context.Context, *otherperson.OtherPerson) error { return nil }
+
+func (f *fakeOtherPersonService) Create(_ context.Context, p *otherperson.OtherPerson) error {
+	f.lastCreate = p
+	if f.err != nil {
+		return f.err
+	}
+	if len(p.ID) == 0 {
+		p.ID = uuidv7.MustBytes()
+	}
+	return nil
+}
+
+func (f *fakeOtherPersonService) Update(_ context.Context, p *otherperson.OtherPerson) error {
+	f.lastUpdate = p
+	return f.err
+}
+
+func (f *fakeOtherPersonService) Delete(_ context.Context, id, actor []byte) error {
+	f.lastDeleteID = id
+	return f.err
+}
+
+func (f *fakeOtherPersonService) GetByID(_ context.Context, id []byte) (*otherperson.OtherPerson, error) {
+	if f.err != nil {
+		return nil, f.err
+	}
+	if len(f.rows) == 0 {
+		return nil, nil
+	}
+	row := f.rows[0]
+	return &row, nil
+}
+func (f *fakeOtherPersonService) Search(_ context.Context, q string, limit, offset int) ([]otherperson.OtherPerson, int64, error) {
+	f.lastQ, f.lastLimit, f.lastOffset = q, limit, offset
+	if f.err != nil {
+		return nil, 0, f.err
+	}
+	return f.rows, f.total, nil
+}
+
+func TestOtherPersonHandlerSearch(t *testing.T) {
+	id := uuidv7.MustBytes()
+	svc := &fakeOtherPersonService{
+		rows: []otherperson.OtherPerson{
+			{ID: id, Name: "Guest One", MobilePhone: "+43-1", Email: "a@x.io"},
+		},
+		total: 1,
+	}
+	h := NewOtherPersonHandler(svc)
+
+	app := fiber.New()
+	app.Get("/api/v1/contact/other", h.Search)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/contact/other?q=guest&limit=5&offset=2", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("request: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if svc.lastQ != "guest" || svc.lastLimit != 5 || svc.lastOffset != 2 {
+		t.Fatalf("query not forwarded: q=%q limit=%d offset=%d", svc.lastQ, svc.lastLimit, svc.lastOffset)
+	}
+
+	body, _ := io.ReadAll(resp.Body)
+	var out struct {
+		Data []struct {
+			Type       string `json:"type"`
+			ID         string `json:"id"`
+			Attributes struct {
+				Name        string `json:"name"`
+				MobilePhone string `json:"mobile_phone"`
+				Email       string `json:"email"`
+			} `json:"attributes"`
+		} `json:"data"`
+		Meta struct {
+			Total int64 `json:"total"`
+		} `json:"meta"`
+	}
+	if err := json.Unmarshal(body, &out); err != nil {
+		t.Fatalf("unmarshal: %v (%s)", err, string(body))
+	}
+	if out.Meta.Total != 1 {
+		t.Fatalf("expected meta.total 1, got %d", out.Meta.Total)
+	}
+	if len(out.Data) != 1 {
+		t.Fatalf("expected 1 row, got %d", len(out.Data))
+	}
+	d := out.Data[0]
+	if d.Type != "other_person" || d.ID != idString(id) {
+		t.Fatalf("unexpected resource type/id: %q/%q", d.Type, d.ID)
+	}
+	if d.Attributes.Name != "Guest One" || d.Attributes.MobilePhone != "+43-1" || d.Attributes.Email != "a@x.io" {
+		t.Fatalf("unexpected attributes: %+v", d.Attributes)
+	}
+}
+
+func TestOtherPersonHandlerCreate(t *testing.T) {
+	svc := &fakeOtherPersonService{}
+	h := NewOtherPersonHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/contact/other/create", h.Create)
+
+	body := `{"data":{"type":"other_person","attributes":{"name":"New Guest","mobile_phone":"+43-9","email":"new@x.io"}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/contact/other/create", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("request: %v", err)
+	}
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201, got %d", resp.StatusCode)
+	}
+	if svc.lastCreate == nil || svc.lastCreate.Name != "New Guest" || svc.lastCreate.Email != "new@x.io" {
+		t.Fatalf("service not called with attributes: %+v", svc.lastCreate)
+	}
+
+	out := struct {
+		Data struct {
+			Type       string `json:"type"`
+			Attributes struct {
+				Name string `json:"name"`
+			} `json:"attributes"`
+		} `json:"data"`
+	}{}
+	raw, _ := io.ReadAll(resp.Body)
+	if err := json.Unmarshal(raw, &out); err != nil {
+		t.Fatalf("unmarshal: %v (%s)", err, string(raw))
+	}
+	if out.Data.Type != "other_person" || out.Data.Attributes.Name != "New Guest" {
+		t.Fatalf("unexpected response: %s", string(raw))
+	}
+}
+
+func TestOtherPersonHandlerCreateDuplicateConflict(t *testing.T) {
+	svc := &fakeOtherPersonService{err: otherperson.ErrDuplicate}
+	h := NewOtherPersonHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/contact/other/create", h.Create)
+
+	body := `{"data":{"attributes":{"name":"Dup"}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/contact/other/create", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("request: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422 for duplicate, got %d", resp.StatusCode)
+	}
+}
+
+func TestOtherPersonHandlerUpdate(t *testing.T) {
+	id := uuidv7.MustBytes()
+	svc := &fakeOtherPersonService{
+		rows: []otherperson.OtherPerson{{ID: id, Name: "Edited", MobilePhone: "+43-1", Email: "e@x.io"}},
+	}
+	h := NewOtherPersonHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/contact/other/update/:id", h.Update)
+
+	idStr, _ := uuidv7.BytesToString(id)
+	body := `{"data":{"attributes":{"name":"Edited","mobile_phone":"+43-1","email":"e@x.io"}}}`
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/contact/other/update/"+idStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("request: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if svc.lastUpdate == nil || string(svc.lastUpdate.ID) != string(id) || svc.lastUpdate.Name != "Edited" {
+		t.Fatalf("update not forwarded: %+v", svc.lastUpdate)
+	}
+}
+
+func TestOtherPersonHandlerUpdateNotFound(t *testing.T) {
+	svc := &fakeOtherPersonService{err: otherperson.ErrNotFound}
+	h := NewOtherPersonHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/contact/other/update/:id", h.Update)
+
+	idStr, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	body := `{"data":{"attributes":{"name":"X"}}}`
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/contact/other/update/"+idStr, strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("request: %v", err)
+	}
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", resp.StatusCode)
+	}
+}
+
+func TestOtherPersonHandlerDelete(t *testing.T) {
+	id := uuidv7.MustBytes()
+	svc := &fakeOtherPersonService{}
+	h := NewOtherPersonHandler(svc)
+	app := fiber.New()
+	app.Delete("/api/v1/contact/other/delete/:id", h.Delete)
+
+	idStr, _ := uuidv7.BytesToString(id)
+	req, _ := http.NewRequest(http.MethodDelete, "/api/v1/contact/other/delete/"+idStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("request: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if string(svc.lastDeleteID) != string(id) {
+		t.Fatalf("delete id not forwarded")
+	}
+}
+
+func TestOtherPersonHandlerGetNotFound(t *testing.T) {
+	svc := &fakeOtherPersonService{} // rows empty -> GetByID returns nil,nil
+	h := NewOtherPersonHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/contact/other/get/:id", h.Get)
+
+	idStr, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/contact/other/get/"+idStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("request: %v", err)
+	}
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", resp.StatusCode)
+	}
+}
diff --git a/internal/transport/http/handlers/parse.go b/internal/transport/http/handlers/parse.go
new file mode 100644
index 0000000..34527e5
--- /dev/null
+++ b/internal/transport/http/handlers/parse.go
@@ -0,0 +1,14 @@
+package handlers
+
+import "strconv"
+
+func parseIntDefault(v string, def int) int {
+	if v == "" {
+		return def
+	}
+	n, err := strconv.Atoi(v)
+	if err != nil {
+		return def
+	}
+	return n
+}
diff --git a/internal/transport/http/handlers/patient_data_handler.go b/internal/transport/http/handlers/patient_data_handler.go
new file mode 100644
index 0000000..95cf272
--- /dev/null
+++ b/internal/transport/http/handlers/patient_data_handler.go
@@ -0,0 +1,663 @@
+package handlers
+
+import (
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	patientdata "wucher/internal/domain/patient_data"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type PatientDataHandler struct {
+	svc      patientdata.Service
+	validate *validators.Validator
+}
+
+func NewPatientDataHandler(svc patientdata.Service) *PatientDataHandler {
+	return &PatientDataHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreatePatientData godoc
+// @Summary Create patient data
+// @Description Create a PatientData record.
+// @Tags PatientData - PatientData
+// @Accept json
+// @Produce json
+// @Param request body dto.PatientDataCreateRequest true "JSON:API PatientData create request"
+// @Success 201 {object} dto.PatientDataResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/patient-data/create [post]
+func (h *PatientDataHandler) Create(c *fiber.Ctx) error {
+	var req dto.PatientDataCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	familyName := strings.TrimSpace(req.Data.Attributes.FamilyName)
+	if familyName == "" {
+		return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "family_name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/family_name"},
+		}})
+	}
+	firstName := strings.TrimSpace(req.Data.Attributes.FirstName)
+	if firstName == "" {
+		return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "first_name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/first_name"},
+		}})
+	}
+
+	row := &patientdata.PatientData{
+		FamilyName: familyName,
+		FirstName:  firstName,
+		Gender:     req.Data.Attributes.Gender,
+		Street:     strings.TrimSpace(stringOrDefault(req.Data.Attributes.Street, "")),
+		SVNR:       strings.TrimSpace(stringOrDefault(req.Data.Attributes.SVNR, "")),
+		Email:      strings.TrimSpace(stringOrDefault(req.Data.Attributes.Email, "")),
+		Phone:      strings.TrimSpace(stringOrDefault(req.Data.Attributes.Phone, "")),
+		CreatedBy:  actorUserID(c),
+		UpdatedBy:  actorUserID(c),
+	}
+
+	if req.Data.Attributes.CoInsured != nil {
+		row.CoInsured = *req.Data.Attributes.CoInsured
+	}
+
+	if req.Data.Attributes.BirthDate != nil {
+		bd, err := time.Parse("2006-01-02", strings.TrimSpace(*req.Data.Attributes.BirthDate))
+		if err != nil {
+			return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "birth_date must be in YYYY-MM-DD format",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/birth_date"},
+			}})
+		}
+		row.BirthDate = &bd
+	}
+
+	if req.Data.Attributes.OPCId != nil {
+		parsed, err := uuidv7.ParseString(strings.TrimSpace(*req.Data.Attributes.OPCId))
+		if err != nil {
+			return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "opc_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/opc_id"},
+			}})
+		}
+		row.OPCId = parsed
+	}
+	if req.Data.Attributes.InsurancePatientDataId != nil {
+		parsed, err := uuidv7.ParseString(strings.TrimSpace(*req.Data.Attributes.InsurancePatientDataId))
+		if err != nil {
+			return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "insurance_patient_data_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/insurance_patient_data_id"},
+			}})
+		}
+		row.InsurancePatientDataId = parsed
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, patientDataResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, patientDataResource(row))
+}
+
+// GetPatientData godoc
+// @Summary Get patient data by ID
+// @Description Get a single PatientData record by UUID.
+// @Tags PatientData - PatientData
+// @Produce json
+// @Param uuid path string true "PatientData UUID (UUIDv7)"
+// @Success 200 {object} dto.PatientDataResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/patient-data/get/{uuid} [get]
+func (h *PatientDataHandler) Get(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || row == nil {
+		return writePatientDataErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "patient data not found",
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, patientDataResource(row))
+}
+
+// UpdatePatientData godoc
+// @Summary Update patient data (partial)
+// @Description Patch PatientData by ID.
+// @Tags PatientData - PatientData
+// @Accept json
+// @Produce json
+// @Param uuid path string true "PatientData UUID (UUIDv7)"
+// @Param request body dto.PatientDataUpdateRequest true "JSON:API PatientData update request"
+// @Success 200 {object} dto.PatientDataResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/patient-data/update/{uuid} [patch]
+func (h *PatientDataHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.PatientDataUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.FamilyName == nil && attrs.FirstName == nil && attrs.OPCId == nil &&
+		attrs.BirthDate == nil && attrs.Gender == nil && attrs.Street == nil &&
+		attrs.SVNR == nil && attrs.Email == nil && attrs.Phone == nil &&
+		attrs.CoInsured == nil &&
+		attrs.InsurancePatientDataId == nil {
+		return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writePatientDataErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "patient data not found",
+		}})
+	}
+
+	if attrs.FamilyName != nil {
+		v := strings.TrimSpace(*attrs.FamilyName)
+		if v == "" {
+			return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "family_name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/family_name"},
+			}})
+		}
+		existing.FamilyName = v
+	}
+	if attrs.FirstName != nil {
+		v := strings.TrimSpace(*attrs.FirstName)
+		if v == "" {
+			return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "first_name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/first_name"},
+			}})
+		}
+		existing.FirstName = v
+	}
+	if attrs.Gender != nil {
+		if !patientdata.IsValidGender(*attrs.Gender) {
+			return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "gender must be male or female",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/gender"},
+			}})
+		}
+		existing.Gender = *attrs.Gender
+	}
+	if attrs.Street != nil {
+		existing.Street = strings.TrimSpace(*attrs.Street)
+	}
+	if attrs.SVNR != nil {
+		existing.SVNR = strings.TrimSpace(*attrs.SVNR)
+	}
+	if attrs.Email != nil {
+		existing.Email = strings.TrimSpace(*attrs.Email)
+	}
+	if attrs.Phone != nil {
+		existing.Phone = strings.TrimSpace(*attrs.Phone)
+	}
+	if attrs.CoInsured != nil {
+		existing.CoInsured = *attrs.CoInsured
+	}
+	if attrs.BirthDate != nil {
+		bd, parseErr := time.Parse("2006-01-02", strings.TrimSpace(*attrs.BirthDate))
+		if parseErr != nil {
+			return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "birth_date must be in YYYY-MM-DD format",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/birth_date"},
+			}})
+		}
+		existing.BirthDate = &bd
+	}
+	if attrs.OPCId != nil {
+		parsed, parseErr := uuidv7.ParseString(strings.TrimSpace(*attrs.OPCId))
+		if parseErr != nil {
+			return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "opc_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/opc_id"},
+			}})
+		}
+		existing.OPCId = parsed
+	}
+	if attrs.InsurancePatientDataId != nil {
+		parsed, parseErr := uuidv7.ParseString(strings.TrimSpace(*attrs.InsurancePatientDataId))
+		if parseErr != nil {
+			return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "insurance_patient_data_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/insurance_patient_data_id"},
+			}})
+		}
+		existing.InsurancePatientDataId = parsed
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, patientDataResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, patientDataResource(existing))
+}
+
+// DeletePatientData godoc
+// @Summary Delete patient data
+// @Description Soft delete PatientData by ID.
+// @Tags PatientData - PatientData
+// @Produce json
+// @Param uuid path string true "PatientData UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/patient-data/delete/{uuid} [delete]
+func (h *PatientDataHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writePatientDataErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		return writeDeleteError(c, err)
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "patient_data_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListPatientData godoc
+// @Summary List patient data
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: family_name, -family_name, first_name, -first_name, birth_date, -birth_date, gender, -gender, created_at, -created_at, updated_at, -updated_at.
+// @Tags PatientData - PatientData
+// @Produce json
+// @Param filter[search] query string false "Search by family_name/first_name/svnr/email/phone/street"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.PatientDataListResponse
+// @Router /api/v1/patient-data/get-all [get]
+func (h *PatientDataHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("search")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return writePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.PatientDataResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, patientDataResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListPatientDataDatatable godoc
+// @Summary List patient data (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags PatientData - PatientData
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search by family_name/first_name/svnr/email/phone/street"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.PatientDataDataTableResponse
+// @Router /api/v1/patient-data/get-all/dt [get]
+func (h *PatientDataHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), search, sort, length, start)
+	if err != nil {
+		return writePatientDataErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.PatientDataResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, patientDataResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// computeAge calculates the age in whole years from birthDate to now.
+func computeAge(birthDate time.Time) int {
+	now := time.Now().UTC()
+	years := now.Year() - birthDate.Year()
+	if now.Month() < birthDate.Month() ||
+		(now.Month() == birthDate.Month() && now.Day() < birthDate.Day()) {
+		years--
+	}
+	return years
+}
+
+func patientDataResource(row *patientdata.PatientData) dto.PatientDataResource {
+	attrs := dto.PatientDataAttributes{
+		FamilyName:             row.FamilyName,
+		FirstName:              row.FirstName,
+		OPCId:                  idString(row.OPCId),
+		Gender:                 row.Gender,
+		Street:                 row.Street,
+		SVNR:                   row.SVNR,
+		Email:                  row.Email,
+		Phone:                  row.Phone,
+		CoInsured:              row.CoInsured,
+		InsurancePatientDataId: idString(row.InsurancePatientDataId),
+		CreatedAt:              row.CreatedAt.UTC().Format(time.RFC3339),
+		CreatedBy:              uuidStringOrEmpty(row.CreatedBy),
+		UpdatedAt:              row.UpdatedAt.UTC().Format(time.RFC3339),
+		UpdatedBy:              uuidStringOrEmpty(row.UpdatedBy),
+		DeletedAt:              timeStringOrEmpty(row.DeletedAt),
+		DeletedBy:              uuidStringOrEmpty(row.DeletedBy),
+	}
+
+	if row.OPC != nil {
+		attrs.OPC = &dto.PatientDataOPC{
+			ID:    idString(row.OPC.ID),
+			Title: row.OPC.Title,
+		}
+	}
+
+	if row.InsurancePatientData != nil {
+		insurance := &dto.PatientDataInsuranceDetail{
+			ID:                       idString(row.InsurancePatientData.ID),
+			HealthInsuranceCompanyID: idString(row.InsurancePatientData.HealthInsuranceCompaniesId),
+			FederalStateID:           idString(row.InsurancePatientData.FederalStateId),
+		}
+
+		if row.InsurancePatientData.HealthInsuranceCompanies != nil {
+			insurance.HealthInsuranceCompany = &dto.InsurancePatientDataHealthInsuranceCompany{
+				ID:           idString(row.InsurancePatientData.HealthInsuranceCompanies.ID),
+				Name:         row.InsurancePatientData.HealthInsuranceCompanies.Name,
+				State:        row.InsurancePatientData.HealthInsuranceCompanies.State,
+				Address:      row.InsurancePatientData.HealthInsuranceCompanies.Address,
+				MobileNumber: row.InsurancePatientData.HealthInsuranceCompanies.MobileNumber,
+				Email:        row.InsurancePatientData.HealthInsuranceCompanies.Email,
+			}
+		}
+
+		if row.InsurancePatientData.FederalState != nil {
+			insurance.FederalState = &dto.InsurancePatientDataFederalState{
+				ID:   idString(row.InsurancePatientData.FederalState.ID),
+				Name: row.InsurancePatientData.FederalState.Name,
+			}
+		}
+
+		attrs.InsurancePatientData = insurance
+	}
+
+	if row.BirthDate != nil {
+		attrs.BirthDate = row.BirthDate.Format("2006-01-02")
+		age := computeAge(*row.BirthDate)
+		attrs.Age = &age
+	}
+
+	return dto.PatientDataResource{
+		Type:       "patient_data",
+		ID:         idString(row.ID),
+		Attributes: attrs,
+	}
+}
+
+func writePatientDataErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		if strings.TrimSpace(e.Code) == "" || strings.TrimSpace(e.ErrorCode) == "" {
+			code, errorCode := inferPatientDataErrorCode(status, e.Title, e.Detail)
+			if strings.TrimSpace(e.Code) == "" {
+				e.Code = code
+			}
+			if strings.TrimSpace(e.ErrorCode) == "" {
+				e.ErrorCode = errorCode
+			}
+		}
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferPatientDataErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.CodePatientDataNotFound, apperrorsx.ErrPatientDataNotFound.ErrorCode
+	case fiber.StatusConflict:
+		return apperrorsx.CodePatientDataRelationDelete, apperrorsx.ErrPatientDataRelationDelete.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid"):
+			return apperrorsx.CodePatientDataInvalidUUID, apperrorsx.ErrPatientDataInvalidUUID.ErrorCode
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.CodePatientDataIDRequired, apperrorsx.ErrPatientDataIDRequired.ErrorCode
+		case strings.Contains(lowerDetail, "id does not match"):
+			return apperrorsx.CodePatientDataIDMismatch, apperrorsx.ErrPatientDataIDMismatch.ErrorCode
+		case strings.Contains(lowerDetail, "at least one attribute"):
+			return apperrorsx.CodePatientDataAttributesRequired, apperrorsx.ErrPatientDataAttributesRequired.ErrorCode
+		case strings.Contains(lowerDetail, "family_name is required"), strings.Contains(lowerDetail, "family_name cannot be empty"):
+			return apperrorsx.CodePatientDataFamilyNameRequired, apperrorsx.ErrPatientDataFamilyNameRequired.ErrorCode
+		case strings.Contains(lowerDetail, "first_name is required"), strings.Contains(lowerDetail, "first_name cannot be empty"):
+			return apperrorsx.CodePatientDataFirstNameRequired, apperrorsx.ErrPatientDataFirstNameRequired.ErrorCode
+		case strings.Contains(lowerDetail, "birth_date must be"):
+			return apperrorsx.CodePatientDataBirthDateInvalid, apperrorsx.ErrPatientDataBirthDateInvalid.ErrorCode
+		case strings.Contains(lowerDetail, "gender must be"):
+			return apperrorsx.CodePatientDataGenderInvalid, apperrorsx.ErrPatientDataGenderInvalid.ErrorCode
+		case strings.Contains(lowerDetail, "opc_id is invalid"):
+			return apperrorsx.CodePatientDataOPCIDInvalid, apperrorsx.ErrPatientDataOPCIDInvalid.ErrorCode
+		case strings.Contains(lowerDetail, "insurance_patient_data_id is invalid"):
+			return apperrorsx.CodePatientDataInsurancePatientDataIDInvalid, apperrorsx.ErrPatientDataInsurancePatientDataIDInvalid.ErrorCode
+		default:
+			return apperrorsx.CodePatientDataInvalidPayload, apperrorsx.ErrPatientDataInvalidPayload.ErrorCode
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.CodePatientDataInvalidJSON, apperrorsx.ErrPatientDataInvalidJSON.ErrorCode
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.CodePatientDataCreateFailed, apperrorsx.ErrPatientDataCreateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.CodePatientDataUpdateFailed, apperrorsx.ErrPatientDataUpdateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.CodePatientDataDeleteFailed, apperrorsx.ErrPatientDataDeleteFailed.ErrorCode
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.CodePatientDataListFailed, apperrorsx.ErrPatientDataListFailed.ErrorCode
+		default:
+			return apperrorsx.CodePatientDataInvalidPayload, apperrorsx.ErrPatientDataInvalidPayload.ErrorCode
+		}
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
diff --git a/internal/transport/http/handlers/patient_data_handler_test.go b/internal/transport/http/handlers/patient_data_handler_test.go
new file mode 100644
index 0000000..5724c74
--- /dev/null
+++ b/internal/transport/http/handlers/patient_data_handler_test.go
@@ -0,0 +1,596 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	federalstate "wucher/internal/domain/federal_state"
+	healthinsurancecompanies "wucher/internal/domain/health_insurance_companies"
+	insurancepatientdata "wucher/internal/domain/insurance_patient_data"
+	"wucher/internal/domain/opc"
+	patientdata "wucher/internal/domain/patient_data"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type patientDataServiceMock struct {
+	createFn func(context.Context, *patientdata.PatientData) error
+	updateFn func(context.Context, *patientdata.PatientData) error
+	deleteFn func(context.Context, []byte, []byte) error
+	getByID  func(context.Context, []byte) (*patientdata.PatientData, error)
+	listFn   func(context.Context, string, string, int, int) ([]patientdata.PatientData, int64, error)
+}
+
+func (m *patientDataServiceMock) Create(ctx context.Context, row *patientdata.PatientData) error {
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return nil
+}
+func (m *patientDataServiceMock) Update(ctx context.Context, row *patientdata.PatientData) error {
+	if m.updateFn != nil {
+		return m.updateFn(ctx, row)
+	}
+	return nil
+}
+func (m *patientDataServiceMock) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if m.deleteFn != nil {
+		return m.deleteFn(ctx, id, deletedBy)
+	}
+	return nil
+}
+func (m *patientDataServiceMock) GetByID(ctx context.Context, id []byte) (*patientdata.PatientData, error) {
+	if m.getByID != nil {
+		return m.getByID(ctx, id)
+	}
+	return nil, nil
+}
+func (m *patientDataServiceMock) List(ctx context.Context, filter, sort string, limit, offset int) ([]patientdata.PatientData, int64, error) {
+	if m.listFn != nil {
+		return m.listFn(ctx, filter, sort, limit, offset)
+	}
+	return nil, 0, nil
+}
+
+func mustNewUUIDString(t *testing.T) string {
+	t.Helper()
+	u := uuidv7.MustNew()
+	s, err := uuidv7.String(u)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return s
+}
+
+func newPatientDataApp(h *PatientDataHandler) *fiber.App {
+	app := fiber.New()
+	app.Post("/create", h.Create)
+	app.Get("/get/:uuid", h.Get)
+	app.Patch("/update/:uuid", h.Update)
+	app.Delete("/delete/:uuid", h.Delete)
+	app.Get("/list", h.List)
+	app.Get("/dt", h.ListDatatable)
+	return app
+}
+
+func TestPatientDataHandler_CRUDAndList(t *testing.T) {
+	patientID := uuidv7.MustBytes()
+	row := &patientdata.PatientData{
+		ID:         patientID,
+		FamilyName: "Doe",
+		FirstName:  "John",
+		Gender:     patientdata.GenderMale,
+		CreatedAt:  time.Now().UTC(),
+		UpdatedAt:  time.Now().UTC(),
+	}
+	svc := &patientDataServiceMock{
+		createFn: func(_ context.Context, in *patientdata.PatientData) error {
+			in.ID = patientID
+			return nil
+		},
+		getByID: func(_ context.Context, _ []byte) (*patientdata.PatientData, error) {
+			return row, nil
+		},
+		updateFn: func(_ context.Context, in *patientdata.PatientData) error {
+			if in.FamilyName == "Updated" {
+				row.FamilyName = in.FamilyName
+			}
+			return nil
+		},
+		listFn: func(_ context.Context, _, _ string, _, _ int) ([]patientdata.PatientData, int64, error) {
+			return []patientdata.PatientData{*row}, 1, nil
+		},
+	}
+	h := NewPatientDataHandler(svc)
+	app := newPatientDataApp(h)
+
+	createBody := `{"data":{"type":"patient_data_create","attributes":{"family_name":"Doe","first_name":"John","gender":"male"}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(createBody))
+	req.Header.Set("Content-Type", "application/json")
+	res, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201, got %d", res.StatusCode)
+	}
+
+	idStr, _ := uuidv7.BytesToString(patientID)
+	req, _ = http.NewRequest(http.MethodGet, "/get/"+idStr, nil)
+	res, err = app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", res.StatusCode)
+	}
+
+	updateBody := `{"data":{"type":"patient_data_update","id":"` + idStr + `","attributes":{"family_name":"Updated"}}}`
+	req, _ = http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(updateBody))
+	req.Header.Set("Content-Type", "application/json")
+	res, err = app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodGet, "/list?page[number]=2&page[size]=5&sort=family_name&filter[search]=abc", nil)
+	res, err = app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodGet, "/dt?page=2&size=3&draw=7&search=abc", nil)
+	res, err = app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", res.StatusCode)
+	}
+}
+
+func TestPatientDataHandler_ErrorPaths(t *testing.T) {
+	idStr := mustNewUUIDString(t)
+	idBytes, _ := uuidv7.ParseString(idStr)
+	svc := &patientDataServiceMock{
+		getByID: func(_ context.Context, _ []byte) (*patientdata.PatientData, error) {
+			return &patientdata.PatientData{ID: idBytes, FamilyName: "A", FirstName: "B", Gender: patientdata.GenderMale, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+		},
+	}
+	h := NewPatientDataHandler(svc)
+	app := newPatientDataApp(h)
+
+	cases := []struct {
+		name   string
+		method string
+		path   string
+		body   string
+		want   int
+	}{
+		{"create bad json", http.MethodPost, "/create", "{bad", http.StatusBadRequest},
+		{"create required family", http.MethodPost, "/create", `{"data":{"type":"patient_data_create","attributes":{"family_name":" ","first_name":"A","gender":"male"}}}`, http.StatusUnprocessableEntity},
+		{"create invalid birth date", http.MethodPost, "/create", `{"data":{"type":"patient_data_create","attributes":{"family_name":"A","first_name":"B","gender":"male","birth_date":"wrong"}}}`, http.StatusUnprocessableEntity},
+		{"get invalid uuid", http.MethodGet, "/get/abc", "", http.StatusUnprocessableEntity},
+		{"update invalid uuid", http.MethodPatch, "/update/abc", `{}`, http.StatusUnprocessableEntity},
+		{"update bad json", http.MethodPatch, "/update/" + idStr, "{bad", http.StatusBadRequest},
+		{"update mismatched id", http.MethodPatch, "/update/" + idStr, `{"data":{"type":"patient_data_update","id":"` + mustNewUUIDString(t) + `","attributes":{"family_name":"X"}}}`, http.StatusUnprocessableEntity},
+		{"delete invalid uuid", http.MethodDelete, "/delete/abc", "", http.StatusUnprocessableEntity},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var bodyReader *strings.Reader
+			if tc.body == "" {
+				bodyReader = strings.NewReader("")
+			} else {
+				bodyReader = strings.NewReader(tc.body)
+			}
+			req, _ := http.NewRequest(tc.method, tc.path, bodyReader)
+			req.Header.Set("Content-Type", "application/json")
+			res, err := app.Test(req)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if res.StatusCode != tc.want {
+				t.Fatalf("expected %d, got %d", tc.want, res.StatusCode)
+			}
+		})
+	}
+}
+
+func TestPatientDataHandler_ServiceErrors(t *testing.T) {
+	idStr := mustNewUUIDString(t)
+	idBytes, _ := uuidv7.ParseString(idStr)
+	svc := &patientDataServiceMock{
+		createFn: func(_ context.Context, _ *patientdata.PatientData) error { return errors.New("boom") },
+		getByID: func(_ context.Context, _ []byte) (*patientdata.PatientData, error) {
+			return nil, errors.New("not found")
+		},
+		updateFn: func(_ context.Context, _ *patientdata.PatientData) error { return errors.New("boom") },
+		deleteFn: func(_ context.Context, _, _ []byte) error { return errors.New("boom") },
+		listFn: func(_ context.Context, _, _ string, _, _ int) ([]patientdata.PatientData, int64, error) {
+			return nil, 0, errors.New("boom")
+		},
+	}
+	h := NewPatientDataHandler(svc)
+	app := newPatientDataApp(h)
+
+	req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(`{"data":{"type":"patient_data_create","attributes":{"family_name":"A","first_name":"B","gender":"male"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ := app.Test(req)
+	if res.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodGet, "/get/"+idStr, nil)
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(`{"data":{"type":"patient_data_update","id":"`+idStr+`","attributes":{"family_name":"A"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", res.StatusCode)
+	}
+
+	svc.getByID = func(_ context.Context, _ []byte) (*patientdata.PatientData, error) {
+		return &patientdata.PatientData{ID: idBytes, FamilyName: "A", FirstName: "B", Gender: patientdata.GenderMale, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+	}
+	req, _ = http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(`{"data":{"type":"patient_data_update","id":"`+idStr+`","attributes":{"family_name":"A"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodDelete, "/delete/"+idStr, nil)
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", res.StatusCode)
+	}
+
+	svc.deleteFn = func(_ context.Context, _ []byte, _ []byte) error { return gorm.ErrRecordNotFound }
+	req, _ = http.NewRequest(http.MethodDelete, "/delete/"+idStr, nil)
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodGet, "/list", nil)
+	res, _ = app.Test(req)
+	if res.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", res.StatusCode)
+	}
+}
+
+func TestPatientDataHandler_ResourceHelpers(t *testing.T) {
+	now := time.Now().UTC()
+	birth := now.AddDate(-30, 0, 0)
+	row := &patientdata.PatientData{
+		ID:         uuidv7.MustBytes(),
+		FamilyName: "Doe",
+		FirstName:  "Jane",
+		Gender:     patientdata.GenderFemale,
+		BirthDate:  &birth,
+		OPC: &opc.Opc{
+			ID:    uuidv7.MustBytes(),
+			Title: "OPC",
+		},
+		InsurancePatientData: &insurancepatientdata.InsurancePatientData{
+			ID:                         uuidv7.MustBytes(),
+			HealthInsuranceCompaniesId: uuidv7.MustBytes(),
+			FederalStateId:             uuidv7.MustBytes(),
+		},
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+
+	res := patientDataResource(row)
+	if res.Type != "patient_data" {
+		t.Fatalf("unexpected type: %s", res.Type)
+	}
+	if res.Attributes.Age == nil || *res.Attributes.Age < 0 {
+		t.Fatalf("expected age to be set")
+	}
+
+	_ = computeAge(now.AddDate(-10, 0, 1))
+
+	b, err := json.Marshal(res)
+	if err != nil || len(b) == 0 {
+		t.Fatalf("resource marshal failed: %v", err)
+	}
+}
+
+func TestPatientDataHandler_UpdateValidationBranches(t *testing.T) {
+	idStr := mustNewUUIDString(t)
+	idBytes, _ := uuidv7.ParseString(idStr)
+	baseRow := &patientdata.PatientData{ID: idBytes, FamilyName: "A", FirstName: "B", Gender: patientdata.GenderMale, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}
+	svc := &patientDataServiceMock{
+		getByID:  func(_ context.Context, _ []byte) (*patientdata.PatientData, error) { return baseRow, nil },
+		updateFn: func(_ context.Context, _ *patientdata.PatientData) error { return nil },
+	}
+	h := NewPatientDataHandler(svc)
+	app := newPatientDataApp(h)
+
+	tests := []string{
+		`{"data":{"type":"patient_data_update","id":"` + idStr + `","attributes":{}}}`,
+		`{"data":{"type":"patient_data_update","id":"` + idStr + `","attributes":{"family_name":" "}}}`,
+		`{"data":{"type":"patient_data_update","id":"` + idStr + `","attributes":{"first_name":" "}}}`,
+		`{"data":{"type":"patient_data_update","id":"` + idStr + `","attributes":{"gender":"other"}}}`,
+		`{"data":{"type":"patient_data_update","id":"` + idStr + `","attributes":{"birth_date":"x"}}}`,
+		`{"data":{"type":"patient_data_update","id":"` + idStr + `","attributes":{"opc_id":"x"}}}`,
+		`{"data":{"type":"patient_data_update","id":"` + idStr + `","attributes":{"insurance_patient_data_id":"x"}}}`,
+	}
+	for _, body := range tests {
+		req := httptest.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d for %s", res.StatusCode, body)
+		}
+	}
+}
+
+func TestPatientDataHandler_CreateAdditionalBranches(t *testing.T) {
+	baseID := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(baseID)
+	svc := &patientDataServiceMock{
+		createFn: func(_ context.Context, in *patientdata.PatientData) error {
+			in.ID = baseID
+			return nil
+		},
+		getByID: func(_ context.Context, _ []byte) (*patientdata.PatientData, error) {
+			return nil, errors.New("fallback")
+		},
+	}
+	h := NewPatientDataHandler(svc)
+	app := newPatientDataApp(h)
+
+	t.Run("create with optional fields success", func(t *testing.T) {
+		body := `{"data":{"type":"patient_data_create","attributes":{"family_name":"Doe","first_name":"John","gender":"male","co_insured":true,"birth_date":"2020-01-01","opc_id":"` + idStr + `","insurance_patient_data_id":"` + idStr + `","street":"A","svnr":"S","email":"e@x.com","phone":"1"}}}`
+		req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("create validator error", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(`{}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", res.StatusCode)
+		}
+	})
+
+	for _, tc := range []struct {
+		name, body string
+	}{
+		{"empty first name", `{"data":{"type":"patient_data_create","attributes":{"family_name":"Doe","first_name":" ","gender":"male"}}}`},
+		{"bad opc", `{"data":{"type":"patient_data_create","attributes":{"family_name":"Doe","first_name":"John","gender":"male","opc_id":"bad"}}}`},
+
+		{"bad insurance", `{"data":{"type":"patient_data_create","attributes":{"family_name":"Doe","first_name":"John","gender":"male","insurance_patient_data_id":"bad"}}}`},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(tc.body))
+			req.Header.Set("Content-Type", "application/json")
+			res, err := app.Test(req)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if res.StatusCode != http.StatusUnprocessableEntity {
+				t.Fatalf("expected 422, got %d", res.StatusCode)
+			}
+		})
+	}
+}
+
+func TestPatientDataHandler_DeleteAndListBranches(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	svc := &patientDataServiceMock{
+		deleteFn: func(_ context.Context, _, _ []byte) error { return nil },
+		listFn: func(_ context.Context, filter, sort string, limit, offset int) ([]patientdata.PatientData, int64, error) {
+			if !((limit == 0 || limit == 20 || limit == 100) && offset == 0) {
+				t.Fatalf("unexpected pagination limit=%d offset=%d", limit, offset)
+			}
+			_ = filter
+			_ = sort
+			return []patientdata.PatientData{}, 0, nil
+		},
+	}
+	h := NewPatientDataHandler(svc)
+	app := newPatientDataApp(h)
+
+	req, _ := http.NewRequest(http.MethodDelete, "/delete/"+idStr, nil)
+	res, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", res.StatusCode)
+	}
+
+	for _, path := range []string{
+		"/list?page[number]=-1&page[size]=1000",
+		"/list?page=0&limit=0&size=0",
+		"/dt?page=-1&size=1000",
+		"/dt?page=0&limit=0&size=0",
+	} {
+		req, _ = http.NewRequest(http.MethodGet, path, nil)
+		res, err = app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != http.StatusOK {
+			t.Fatalf("%s expected 200, got %d", path, res.StatusCode)
+		}
+	}
+}
+
+func TestPatientDataHandler_UpdateAdditionalBranches(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	svc := &patientDataServiceMock{
+		getByID: func(_ context.Context, _ []byte) (*patientdata.PatientData, error) {
+			return &patientdata.PatientData{ID: id, FamilyName: "A", FirstName: "B", Gender: patientdata.GenderMale, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+		},
+		updateFn: func(_ context.Context, _ *patientdata.PatientData) error { return nil },
+	}
+	h := NewPatientDataHandler(svc)
+	app := newPatientDataApp(h)
+
+	req, _ := http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(`{"data":{"type":"patient_data_update","attributes":{"family_name":"X"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", res.StatusCode)
+	}
+
+	fullBody := `{"data":{"type":"patient_data_update","id":"` + idStr + `","attributes":{"family_name":"FN","first_name":"LN","gender":"female","birth_date":"2020-01-01","street":"S","svnr":"V","email":"a@b.com","phone":"1","co_insured":true,"opc_id":"` + idStr + `","insurance_patient_data_id":"` + idStr + `"}}}`
+	req, _ = http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(fullBody))
+	req.Header.Set("Content-Type", "application/json")
+	res, err = app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(`{"data":{"type":"patient_data_update","id":"`+idStr+`","attributes":{"gender":"invalid"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, err = app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(`{"data":{"type":"bad_type","id":"`+idStr+`","attributes":{"family_name":"FN"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, err = app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", res.StatusCode)
+	}
+}
+
+func TestPatientDataHandler_ListDatatableErrorAndResourceBranches(t *testing.T) {
+	svc := &patientDataServiceMock{
+		listFn: func(_ context.Context, _, _ string, _, _ int) ([]patientdata.PatientData, int64, error) {
+			return nil, 0, errors.New("boom")
+		},
+	}
+	h := NewPatientDataHandler(svc)
+	app := newPatientDataApp(h)
+
+	req, _ := http.NewRequest(http.MethodGet, "/dt", nil)
+	res, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", res.StatusCode)
+	}
+
+	row := &patientdata.PatientData{
+		ID:         uuidv7.MustBytes(),
+		FamilyName: "X",
+		FirstName:  "Y",
+		Gender:     patientdata.GenderMale,
+		InsurancePatientData: &insurancepatientdata.InsurancePatientData{
+			ID:                         uuidv7.MustBytes(),
+			HealthInsuranceCompaniesId: uuidv7.MustBytes(),
+			FederalStateId:             uuidv7.MustBytes(),
+			HealthInsuranceCompanies: &healthinsurancecompanies.HealthInsuranceCompany{
+				ID:           uuidv7.MustBytes(),
+				Name:         "H",
+				State:        "S",
+				Address:      "A",
+				MobileNumber: "M",
+				Email:        "E",
+			},
+			FederalState: &federalstate.FederalState{
+				ID:   uuidv7.MustBytes(),
+				Name: "F",
+			},
+		},
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}
+	resRow := patientDataResource(row)
+	if resRow.Attributes.InsurancePatientData == nil ||
+		resRow.Attributes.InsurancePatientData.HealthInsuranceCompany == nil ||
+		resRow.Attributes.InsurancePatientData.FederalState == nil {
+		t.Fatal("expected nested insurance resources to be mapped")
+	}
+}
+
+func TestPatientDataHandler_UpdateFallbackResponseBranch(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	calls := 0
+	svc := &patientDataServiceMock{
+		getByID: func(_ context.Context, _ []byte) (*patientdata.PatientData, error) {
+			calls++
+			if calls == 1 {
+				return &patientdata.PatientData{
+					ID:         id,
+					FamilyName: "A",
+					FirstName:  "B",
+					Gender:     patientdata.GenderMale,
+					CreatedAt:  time.Now().UTC(),
+					UpdatedAt:  time.Now().UTC(),
+				}, nil
+			}
+			return nil, errors.New("reload failed")
+		},
+		updateFn: func(_ context.Context, _ *patientdata.PatientData) error { return nil },
+	}
+	h := NewPatientDataHandler(svc)
+	app := newPatientDataApp(h)
+
+	req, _ := http.NewRequest(http.MethodPatch, "/update/"+idStr, strings.NewReader(`{"data":{"type":"patient_data_update","id":"`+idStr+`","attributes":{"family_name":"Z"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", res.StatusCode)
+	}
+}
diff --git a/internal/transport/http/handlers/presenter_fleet_status.go b/internal/transport/http/handlers/presenter_fleet_status.go
new file mode 100644
index 0000000..d895a96
--- /dev/null
+++ b/internal/transport/http/handlers/presenter_fleet_status.go
@@ -0,0 +1,715 @@
+package handlers
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"strings"
+	"time"
+
+	actionsignoff "wucher/internal/domain/action_signoff"
+	complaint "wucher/internal/domain/complaint"
+	easarelease "wucher/internal/domain/easa_release"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	"wucher/internal/domain/helicopter"
+	"wucher/internal/domain/mcf"
+	helicopterusage "wucher/internal/domain/helicopter_usage"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+)
+
+func fleetSummaryManualInput(s *requestdto.FleetStatusSummaryUpdate) helicopterusage.ManualSummaryInput {
+	in := helicopterusage.ManualSummaryInput{
+		Landing:         s.Landings,
+		FlightReport:    s.FlightReports,
+		HookRelease:     s.HookReleases,
+		RotorBrakeCycle: s.RotorBrakeCycles,
+	}
+	if s.Airframe != nil {
+		in.AirframeHours = s.Airframe.Hours
+		in.AirframeCycles = s.Airframe.Cycles
+	}
+	if s.Engine1 != nil {
+		in.Engine1Hours = s.Engine1.Hours
+		in.Engine1GpcNgN1 = s.Engine1.GpcNgN1
+		in.Engine1PtcNfN2 = s.Engine1.PtcNfN2
+		in.Engine1Ccc = s.Engine1.Ccc
+	}
+	if s.Engine2 != nil {
+		in.Engine2Hours = s.Engine2.Hours
+		in.Engine2GpcNgN1 = s.Engine2.GpcNgN1
+		in.Engine2PtcNfN2 = s.Engine2.PtcNfN2
+		in.Engine2Ccc = s.Engine2.Ccc
+	}
+	return in
+}
+
+func mapFleetStatusPayload(attrs requestdto.FleetStatusCreateAttributes, actor []byte) (*fleetstatus.FleetStatus, error) {
+	helicopterID, err := uuidv7.ParseString(strings.TrimSpace(attrs.HelicopterID))
+	if err != nil {
+		return nil, err
+	}
+	row := &fleetstatus.FleetStatus{HelicopterID: helicopterID, CreatedBy: actor, UpdatedBy: actor}
+	for i := range attrs.MaintenanceSchedules {
+		item := attrs.MaintenanceSchedules[i]
+		row.MaintenanceSchedules = append(row.MaintenanceSchedules, fleetstatus.MaintenanceSchedule{
+			FleetStatusID:  row.ID,
+			InspectionType: strings.TrimSpace(item.InspectionType),
+			Type:           strings.TrimSpace(item.Type),
+			Due:            strings.TrimSpace(item.Due),
+			Ext:            strings.TrimSpace(item.Ext),
+		})
+	}
+	for i := range attrs.Files {
+		fileID, parseErr := uuidv7.ParseString(strings.TrimSpace(attrs.Files[i].FileID))
+		if parseErr != nil {
+			return nil, parseErr
+		}
+		row.Files = append(row.Files, fleetstatus.FleetStatusFile{
+			FleetStatusID: row.ID,
+			FileID:        fileID,
+			Category:      strings.TrimSpace(attrs.Files[i].Category),
+			IsMandatory:   attrs.Files[i].IsMandatory != nil && *attrs.Files[i].IsMandatory,
+		})
+	}
+	return row, nil
+}
+
+func mergeFleetStatusPatch(existing *fleetstatus.FleetStatus, attrs requestdto.FleetStatusUpdateAttributes, actor []byte) (*fleetstatus.FleetStatus, error) {
+	row := &fleetstatus.FleetStatus{
+		ID:           existing.ID,
+		HelicopterID: existing.HelicopterID,
+		Status:       existing.Status,
+		ServicedAt:   existing.ServicedAt,
+		CreatedAt:    existing.CreatedAt,
+		CreatedBy:    existing.CreatedBy,
+		UpdatedBy:    actor,
+	}
+
+	if attrs.HelicopterID != nil && strings.TrimSpace(*attrs.HelicopterID) != "" {
+		helicopterID, err := uuidv7.ParseString(strings.TrimSpace(*attrs.HelicopterID))
+		if err != nil {
+			return nil, err
+		}
+		row.HelicopterID = helicopterID
+	}
+	if attrs.MaintenanceSchedules != nil {
+		row.MaintenanceSchedules = make([]fleetstatus.MaintenanceSchedule, 0, len(attrs.MaintenanceSchedules))
+		for i := range attrs.MaintenanceSchedules {
+			item := attrs.MaintenanceSchedules[i]
+			row.MaintenanceSchedules = append(row.MaintenanceSchedules, fleetstatus.MaintenanceSchedule{
+				FleetStatusID:  row.ID,
+				InspectionType: strings.TrimSpace(item.InspectionType),
+				Type:           strings.TrimSpace(item.Type),
+				Due:            strings.TrimSpace(item.Due),
+				Ext:            strings.TrimSpace(item.Ext),
+			})
+		}
+	} else {
+		row.MaintenanceSchedules = existing.MaintenanceSchedules
+	}
+	if attrs.Files != nil {
+		row.Files = make([]fleetstatus.FleetStatusFile, 0, len(attrs.Files))
+		for i := range attrs.Files {
+			fileID, parseErr := uuidv7.ParseString(strings.TrimSpace(attrs.Files[i].FileID))
+			if parseErr != nil {
+				return nil, parseErr
+			}
+			row.Files = append(row.Files, fleetstatus.FleetStatusFile{
+				FleetStatusID: row.ID,
+				FileID:        fileID,
+				Category:      strings.TrimSpace(attrs.Files[i].Category),
+				IsMandatory:   attrs.Files[i].IsMandatory != nil && *attrs.Files[i].IsMandatory,
+			})
+		}
+	} else {
+		row.Files = existing.Files
+	}
+
+	return row, nil
+}
+
+func fleetStatusMaintenanceSchedules(schedules []fleetstatus.MaintenanceSchedule) []shareddto.MaintenanceScheduleAttributes {
+	byType := make(map[string][]fleetstatus.MaintenanceSchedule, len(schedules))
+	for i := range schedules {
+		t := schedules[i].InspectionType
+		byType[t] = append(byType[t], schedules[i])
+	}
+
+	out := make([]shareddto.MaintenanceScheduleAttributes, 0, len(fleetstatus.InspectionTypeOrder)+len(schedules))
+	for _, t := range fleetstatus.InspectionTypeOrder {
+		items := byType[t]
+		if len(items) == 0 {
+			out = append(out, shareddto.MaintenanceScheduleAttributes{InspectionType: t})
+			continue
+		}
+		for i := range items {
+			out = append(out, maintenanceScheduleAttributes(items[i]))
+		}
+		delete(byType, t)
+	}
+
+	for i := range schedules {
+		items, ok := byType[schedules[i].InspectionType]
+		if !ok {
+			continue
+		}
+		for j := range items {
+			out = append(out, maintenanceScheduleAttributes(items[j]))
+		}
+		delete(byType, schedules[i].InspectionType)
+	}
+	return out
+}
+
+func maintenanceScheduleAttributes(s fleetstatus.MaintenanceSchedule) shareddto.MaintenanceScheduleAttributes {
+	return shareddto.MaintenanceScheduleAttributes{
+		InspectionType: s.InspectionType,
+		Type:           s.Type,
+		Due:            s.Due,
+		Ext:            s.Ext,
+	}
+}
+
+func fleetStatusFiles(ctx context.Context, storage fileManagerDownloadURLStorage, files []fleetstatus.FleetStatusFile) []responsedto.FleetStatusFile {
+	out := make([]responsedto.FleetStatusFile, 0, len(files))
+	for i := range files {
+		item := responsedto.FleetStatusFile{
+			ID:               idString(files[i].ID),
+			FileAttachmentID: idString(files[i].FileAttachmentID),
+			Category:         files[i].Category,
+			IsMandatory:      files[i].IsMandatory,
+		}
+		if files[i].Attachment != nil && files[i].Attachment.File != nil {
+			file := files[i].Attachment.File
+			item.Name = strings.TrimSpace(file.Name)
+			asset := resolveFileManagerDownloadURLs(ctx, storage, file)
+			item.DownloadURL = strings.TrimSpace(asset.OriginalURL)
+			item.ThumbnailDownloadURL = strings.TrimSpace(asset.ThumbnailURL)
+			item.SizeBytes = int64Ptr(asset.OriginalSizeBytes)
+		}
+		out = append(out, item)
+	}
+	return out
+}
+
+func fleetStatusResource(ctx context.Context, svc fleetstatus.Service, storage fileManagerDownloadURLStorage, row *fleetstatus.FleetStatus, helicopterStatus string) responsedto.FleetStatusResource {
+	res := responsedto.FleetStatusResource{Type: "fleet_status", ID: idString(row.ID), Attributes: responsedto.FleetStatusAttributes{Helicopter: fleetStatusHelicopterResource(row.Helicopter, helicopterStatus)}}
+	res.Attributes.Status = row.Status
+	res.Attributes.ServicedAt = timeStringOrEmpty(row.ServicedAt)
+	res.Attributes.Summary = fleetStatusSummary(ctx, svc, row)
+	res.Attributes.MaintenanceSchedules = fleetStatusMaintenanceSchedules(row.MaintenanceSchedules)
+	res.Attributes.Files = fleetStatusFiles(ctx, storage, row.Files)
+	res.Attributes.CreatedAt = row.CreatedAt.UTC().Format(time.RFC3339)
+	res.Attributes.CreatedBy = bytesUUIDToString(row.CreatedBy)
+	res.Attributes.UpdatedAt = row.UpdatedAt.UTC().Format(time.RFC3339)
+	res.Attributes.UpdatedBy = bytesUUIDToString(row.UpdatedBy)
+	return res
+}
+
+func (h *FleetStatusHandler) FMReportFleetStatus(ctx context.Context, helicopterID []byte) *responsedto.FleetStatusResource {
+	if h == nil || h.svc == nil || len(helicopterID) != 16 {
+		return nil
+	}
+	latest, err := h.svc.LatestByHelicopterIDs(ctx, [][]byte{helicopterID})
+	if err != nil {
+		return nil
+	}
+	row := latest[string(helicopterID)]
+	if row == nil {
+		return nil
+	}
+	status := h.deriveHelicopterStatus(ctx, row.Helicopter, row.HelicopterID)
+	res := fleetStatusResource(ctx, h.svc, h.storage, row, status)
+	res.Attributes.EASARelease = resolveEASARelease(ctx, h.easaSvc, row.HelicopterID)
+	return &res
+}
+
+func fleetStatusDetailResource(ctx context.Context, h *FleetStatusHandler, row *fleetstatus.FleetStatus, helicopterStatus string) responsedto.FleetStatusResource {
+	res := fleetStatusResource(ctx, h.svc, h.storage, row, helicopterStatus)
+	if h == nil {
+		return res
+	}
+	// Current active flight (when in use / booked) so the fleet page can create an EASA
+	// release scoped to the flight.
+	if af, err := h.helicopterSvc.ActiveFlightIDByAircraftIDs(ctx, [][]byte{row.HelicopterID}); err == nil {
+		if fid := af[string(row.HelicopterID)]; len(fid) == 16 && res.Attributes.Helicopter != nil {
+			res.Attributes.Helicopter.FlightID = idString(fid)
+		}
+	}
+	// Surface open defects regardless of the derived status label: a complaint must show
+	// even when the aircraft reads MCF/available. MCF is checked before AOG in
+	// DeriveStatus (so a grounding complaint can be masked by MCF), and NSR-deferred /
+	// MEL-within-grace items don't ground at all yet are still open hold items.
+	// Every OPEN defect, plus the FIXED defects from this helicopter's latest flight (so a
+	// just-resolved defect stays visible as the last state until a newer flight reports).
+	// Same rule as the fleet list — one source of truth in OpenByHelicopterIDs.
+	complaints := make([]complaint.Complaint, 0)
+	if rows, err := h.complaintSvc.OpenByHelicopterIDs(ctx, [][]byte{row.HelicopterID}); err == nil {
+		complaints = rows
+	}
+	if len(complaints) > 0 {
+		res.Attributes.Complaints = mapComplaintListToFleetStatusDTO(ctx, h.complaintSvc, h.signoffSvc, complaints)
+	}
+	// The release form + status reasons accompany a defect (or a non-complaint AOG such
+	// as a maintenance next-due); skip the extra lookups for a clean, non-AOG aircraft.
+	if len(complaints) > 0 || helicopterStatus == helicopter.StatusAOG {
+		res.Attributes.EASARelease = resolveEASARelease(ctx, h.easaSvc, row.HelicopterID)
+		if row.Helicopter != nil {
+			overdue, oErr := h.svc.OverdueInspections(ctx, row.HelicopterID)
+			if oErr != nil {
+				slog.WarnContext(ctx, "fleet status: overdue inspections lookup failed", slog.Any("error", oErr))
+			}
+			res.Attributes.Helicopter.StatusReasons = buildHelicopterStatusReasons(row.Helicopter, complaints, overdue, time.Now().UTC())
+		}
+	}
+	return res
+}
+
+func mapComplaintListToFleetStatusDTO(ctx context.Context, svc complaintLister, signoffSvc complaintSignoffLookup, rows []complaint.Complaint) []shareddto.FleetStatusComplaint {
+	out := make([]shareddto.FleetStatusComplaint, 0, len(rows))
+	names := map[string]string{}
+	if svc != nil && len(rows) > 0 {
+		if resolved, err := svc.ResolveUserNames(ctx, rows); err == nil {
+			names = resolved
+		}
+	}
+	signoffs := resolveSignoffsByComplaint(ctx, signoffSvc, rows, names)
+	for i := range rows {
+		out = append(out, mapComplaintToFleetStatusDTO(ctx, &rows[i], names, signoffs))
+	}
+	return out
+}
+
+func mapComplaintToFleetStatusDTO(ctx context.Context, c *complaint.Complaint, names map[string]string, signoffs map[string]*actionsignoff.ActionSignoff) shareddto.FleetStatusComplaint {
+	if c == nil {
+		return shareddto.FleetStatusComplaint{}
+	}
+	signoff := signoffs[string(c.ID)]
+	dto := shareddto.FleetStatusComplaint{
+		ID:                    idString(c.ID),
+		FlightID:              idString(c.FlightID),
+		Description:           c.Description,
+		Status:                c.Status(),
+		ReportedAt:            c.ReportedAt.UTC().Format(time.RFC3339),
+		AircraftHoursAtReport: c.AircraftHoursAtReport,
+		MEL:                   shareddto.FleetStatusComplaintMEL{Severity: c.MELSeverity},
+		NSR:                   shareddto.FleetStatusComplaintNSR{IsNSR: c.IsNSR},
+		Action:                shareddto.FleetStatusComplaintAction{Taken: c.ActionTaken, AircraftHoursAtFix: c.AircraftHoursAtFix},
+	}
+	dto.ReportedBy = idString(c.ReportedBy)
+	dto.ReportedByName = names[string(c.ReportedBy)]
+	dto.ReportedByShort = userctx.GetShortName(ctx, c.ReportedBy)
+	dto.MEL.ClassifiedBy = idString(c.MELClassifiedBy)
+	dto.MEL.ClassifiedByName = names[string(c.MELClassifiedBy)]
+	dto.MEL.ClassifiedByShort = userctx.GetShortName(ctx, c.MELClassifiedBy)
+	dto.MEL.ClassifiedAt = timePtrOrNil(c.MELClassifiedAt)
+	// Only label severity once classified — pending complaints (mel_classified_at NULL)
+	// keep severity 0 as a default, which is not a "Non-MEL" decision.
+	if c.MELClassifiedAt != nil {
+		if label := complaintSeverityLabel(c.MELSeverity); label != "" {
+			dto.MEL.SeverityLabel = &label
+		}
+	}
+	if dl := c.MELDeadline(); dl != nil {
+		v := dl.UTC().Format(time.RFC3339)
+		dto.MEL.Deadline = &v
+	}
+	dto.NSR.DecidedAt = timePtrOrNil(c.NSRDecidedAt)
+	dto.NSR.DecidedBy = idString(c.NSRDecidedBy)
+	dto.NSR.DecidedByName = names[string(c.NSRDecidedBy)]
+	dto.NSR.DecidedByShort = userctx.GetShortName(ctx, c.NSRDecidedBy)
+	dto.NSR.Reason = c.NSRReason
+	if signoff != nil {
+		dto.Action.SignedAt = timePtrOrNil(signoff.SignedAt)
+		dto.Action.SignedBy = idString(signoff.SignedBy)
+		dto.Action.SignedByName = names[string(signoff.SignedBy)]
+		dto.Action.SignedByShort = userctx.GetShortName(ctx, signoff.SignedBy)
+	}
+	return dto
+}
+
+func resolveEASARelease(ctx context.Context, svc easaReleaseLister, helicopterID []byte) *shareddto.FleetStatusEASARelease {
+	if svc == nil || len(helicopterID) != 16 {
+		return nil
+	}
+	rel, err := svc.GetLatestByHelicopter(ctx, helicopterID)
+	if err == nil && rel != nil {
+		return mapEASAReleaseToDTO(ctx, rel)
+	}
+	return nil
+}
+
+func mapEASAReleaseToDTO(ctx context.Context, r *easarelease.EASARelease) *shareddto.FleetStatusEASARelease {
+	if r == nil {
+		return nil
+	}
+	dto := &shareddto.FleetStatusEASARelease{
+		ID:                         idString(r.ID),
+		IsSigned:                   r.IsSigned(),
+		EASADate:                   timeDatePtrOrNil(r.EASADate),
+		EASAACHours:                r.EASAACHours,
+		EASALocation:               r.EASALocation,
+		EASAWONo:                   r.EASAWONo,
+		EASAMaintManualRevAirframe: r.EASAMaintManualRevAirframe,
+		EASAMaintManualRevEngine:   r.EASAMaintManualRevEngine,
+		EASASignerID:               r.EASASignerID,
+		EASAPermitNo:               r.EASAPermitNo,
+		SignedAt:                   timePtrOrNil(r.SignedAt),
+		SignedBy:                   idString(r.SignedBy),
+		SignedByName:               userctx.GetDisplayName(ctx, r.SignedBy),
+		SignedByShort:              userctx.GetShortName(ctx, r.SignedBy),
+		MissingSignFields:          r.MissingSignFields(),
+	}
+	return dto
+}
+
+func buildHelicopterStatusReasons(h *helicopter.Helicopter, complaints []complaint.Complaint, overdue []fleetstatus.OverdueInspection, now time.Time) []shareddto.FleetStatusHelicopterReason {
+	reasons := make([]shareddto.FleetStatusHelicopterReason, 0)
+	if h != nil && h.AirOnGround {
+		src := strings.TrimSpace(h.AOGSource)
+		if src != helicopter.AOGSourceComplaint && src != helicopter.AOGSourceAuto {
+			detail := strings.TrimSpace(h.AOGReason)
+			if detail == "" {
+				detail = "Manual AOG"
+			}
+			reasons = append(reasons, shareddto.FleetStatusHelicopterReason{Code: shareddto.ReasonCodeManualAOG, Detail: detail})
+		}
+	}
+	for i := range complaints {
+		c := complaints[i]
+		if !c.IsGrounding(now) {
+			continue
+		}
+		short := shortenText(c.Description, 40)
+		if c.MELSeverity > 0 {
+			reason := shareddto.FleetStatusHelicopterReason{
+				Code:   shareddto.ReasonCodeMELExpired,
+				Detail: fmt.Sprintf("MEL %s for %q overdue", complaintSeverityLabel(c.MELSeverity), short),
+			}
+			if deadline := c.MELDeadline(); deadline != nil {
+				since := deadline.UTC().Format(time.RFC3339)
+				reason.Since = &since
+			}
+			reasons = append(reasons, reason)
+			continue
+		}
+		since := c.ReportedAt.UTC().Format(time.RFC3339)
+		reasons = append(reasons, shareddto.FleetStatusHelicopterReason{
+			Code:   shareddto.ReasonCodeNonMELPending,
+			Detail: fmt.Sprintf("NON-MEL %q pending technician sign", short),
+			Since:  &since,
+		})
+	}
+	for i := range overdue {
+		reasons = append(reasons, shareddto.FleetStatusHelicopterReason{
+			Code:   shareddto.ReasonCodeInspectionOverdue,
+			Detail: overdue[i].Detail,
+		})
+	}
+	if len(reasons) == 0 {
+		return nil
+	}
+	return reasons
+}
+
+func complaintSeverityLabel(severity int8) string {
+	switch severity {
+	case complaint.MELSeverityNonMEL:
+		return "NON-MEL"
+	case complaint.MELSeverityA:
+		return "A"
+	case complaint.MELSeverityB:
+		return "B"
+	case complaint.MELSeverityC:
+		return "C"
+	case complaint.MELSeverityD:
+		return "D"
+	default:
+		return ""
+	}
+}
+
+func shortenText(v string, n int) string {
+	v = strings.TrimSpace(v)
+	if n <= 0 || len(v) <= n {
+		return v
+	}
+	return v[:n]
+}
+
+func timePtrOrNil(v *time.Time) *string {
+	if v == nil || v.IsZero() {
+		return nil
+	}
+	s := v.UTC().Format(time.RFC3339)
+	return &s
+}
+
+func timeDatePtrOrNil(v *time.Time) *string {
+	if v == nil || v.IsZero() {
+		return nil
+	}
+	s := v.UTC().Format("2006-01-02")
+	return &s
+}
+
+func fleetStatusListResourceWithSummaryCache(ctx context.Context, svc fleetstatus.Service, storage fileManagerDownloadURLStorage, row *fleetstatus.FleetStatus, helicopterStatus string, cache map[string]shareddto.FleetStatusSummary) responsedto.FleetStatusResource {
+	if row == nil {
+		return responsedto.FleetStatusResource{}
+	}
+	resource := responsedto.FleetStatusResource{Type: "fleet_status", ID: idString(row.ID), Attributes: responsedto.FleetStatusAttributes{Helicopter: fleetStatusHelicopterResource(row.Helicopter, helicopterStatus)}}
+	resource.Attributes.Status = row.Status
+	resource.Attributes.ServicedAt = timeStringOrEmpty(row.ServicedAt)
+	resource.Attributes.Summary = fleetStatusSummaryWithCache(ctx, svc, row, cache)
+	resource.Attributes.MaintenanceSchedules = fleetStatusMaintenanceSchedules(row.MaintenanceSchedules)
+	resource.Attributes.Files = fleetStatusFiles(ctx, storage, row.Files)
+	resource.Attributes.CreatedAt = row.CreatedAt.UTC().Format(time.RFC3339)
+	resource.Attributes.CreatedBy = bytesUUIDToString(row.CreatedBy)
+	resource.Attributes.UpdatedAt = row.UpdatedAt.UTC().Format(time.RFC3339)
+	resource.Attributes.UpdatedBy = bytesUUIDToString(row.UpdatedBy)
+	return resource
+}
+
+func fleetStatusSummaryWithCache(ctx context.Context, svc fleetstatus.Service, row *fleetstatus.FleetStatus, cache map[string]shareddto.FleetStatusSummary) shareddto.FleetStatusSummary {
+	if svc == nil || row == nil || len(row.HelicopterID) != 16 {
+		return shareddto.FleetStatusSummary{}
+	}
+	key := idString(row.HelicopterID)
+	if cache != nil {
+		if cached, ok := cache[key]; ok {
+			return cached
+		}
+	}
+	summary := fleetStatusSummary(ctx, svc, row)
+	if cache != nil {
+		cache[key] = summary
+	}
+	return summary
+}
+
+func fleetStatusSummary(ctx context.Context, svc fleetstatus.Service, row *fleetstatus.FleetStatus) shareddto.FleetStatusSummary {
+	if svc == nil || row == nil || len(row.HelicopterID) != 16 {
+		return shareddto.FleetStatusSummary{}
+	}
+	summary, err := svc.GetSummaryByHelicopterID(ctx, row.HelicopterID)
+	if err != nil || summary == nil {
+		return shareddto.FleetStatusSummary{}
+	}
+	return *summary
+}
+
+func fleetStatusServiceLogResource(row *fleetstatus.FleetStatusServiceLog) responsedto.FleetStatusServiceLogResource {
+	return responsedto.FleetStatusServiceLogResource{
+		Type: "fleet_status_service_log",
+		ID:   idString(row.ID),
+		Attributes: responsedto.FleetStatusServiceLogAttributes{
+			FleetStatusID:     idString(row.FleetStatusID),
+			HelicopterID:      idString(row.HelicopterID),
+			Helicopter:        fleetStatusHelicopterResource(row.Helicopter, ""),
+			FleetStatusStatus: fleetstatus.StatusServiced,
+			InspectionType:    row.InspectionType,
+			Type:              row.Type,
+			Due:               row.Due,
+			Ext:               row.Ext,
+			ServicedAt:        row.ServicedAt.UTC().Format(time.RFC3339),
+			CreatedAt:         row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:         bytesUUIDToString(row.CreatedBy),
+		},
+	}
+}
+
+func fleetStatusHelicopterResource(row *helicopter.Helicopter, status string) *shareddto.FleetStatusHelicopter {
+	if row == nil {
+		return nil
+	}
+	return &shareddto.FleetStatusHelicopter{
+		ID:          idString(row.ID),
+		Designation: row.Designation,
+		Identifier:  row.Identifier,
+		Type:        row.Type,
+		Status:      status,
+	}
+}
+
+// openComplaintsByHelicopter loads every open (fixed_at IS NULL) complaint for the fleet
+// in a single query and groups them per helicopter (raw-bytes string key), so the list
+// view can fill the Complaints column for each aircraft without an N+1. Returns an empty
+// map on a nil service or query error.
+func openComplaintsByHelicopter(ctx context.Context, svc complaintLister, ids [][]byte) map[string][]complaint.Complaint {
+	out := map[string][]complaint.Complaint{}
+	if svc == nil || len(ids) == 0 {
+		return out
+	}
+	rows, err := svc.OpenByHelicopterIDs(ctx, ids)
+	if err != nil {
+		slog.WarnContext(ctx, "fleet status list: open complaints lookup failed", slog.Any("error", err))
+		return out
+	}
+	for i := range rows {
+		k := string(rows[i].HelicopterID)
+		out[k] = append(out[k], rows[i])
+	}
+	return out
+}
+
+func (h *FleetStatusHandler) fleetStatusResourcesForHelicopters(ctx context.Context, helis []helicopter.Helicopter) ([]responsedto.FleetStatusResource, error) {
+	ids := make([][]byte, 0, len(helis))
+	for i := range helis {
+		ids = append(ids, helis[i].ID)
+	}
+	latest, err := h.svc.LatestByHelicopterIDs(ctx, ids)
+	if err != nil {
+		return nil, err
+	}
+	inUse, err := h.helicopterSvc.InUseByAircraftIDs(ctx, ids)
+	if err != nil {
+		slog.WarnContext(ctx, "fleet status list: in-use lookup failed", slog.Any("error", err))
+	}
+	// Current active flight per in-use aircraft — exposed so the fleet page can create an
+	// EASA release scoped to the flight (e.g. a standalone release for a booked aircraft).
+	activeFlight, err := h.helicopterSvc.ActiveFlightIDByAircraftIDs(ctx, ids)
+	if err != nil {
+		slog.WarnContext(ctx, "fleet status list: active-flight lookup failed", slog.Any("error", err))
+	}
+	grounded := groundingHelicopterSet(ctx, h.complaintSvc, ids, time.Now().UTC())
+	mcfPending := mcfPendingHelicopterSet(ctx, h.mcfSvc, ids)
+	mcfLatest, err := h.mcfSvc.LatestByHelicopterIDs(ctx, ids)
+	if err != nil {
+		slog.WarnContext(ctx, "fleet status list: latest-mcf lookup failed", slog.Any("error", err))
+		mcfLatest = map[string]*mcf.MaintenanceCheckFlight{}
+	}
+	// One batch query for the whole fleet's open defects, grouped per helicopter, so the
+	// Complaints column can be filled for every aircraft that has one — not just AOG ones.
+	openByHeli := openComplaintsByHelicopter(ctx, h.complaintSvc, ids)
+
+	cache := make(map[string]shareddto.FleetStatusSummary, len(helis))
+	render := fleetStatusRender{svc: h.svc, storage: h.storage, cache: cache}
+	now := time.Now().UTC()
+	out := make([]responsedto.FleetStatusResource, 0, len(helis))
+	for i := range helis {
+		heli := &helis[i]
+		key := string(heli.ID)
+		status := heli.DeriveStatus(helicopter.StatusInput{IsBook: inUse[key], IsMCF: mcfPending[key], ComplaintGrounded: grounded[key]})
+		res := fleetStatusResourceForHelicopter(ctx, render, heli, latest[key], status)
+		if fid := activeFlight[key]; len(fid) == 16 && res.Attributes.Helicopter != nil {
+			res.Attributes.Helicopter.FlightID = idString(fid)
+		}
+		res.Attributes.MCF = buildFleetMCF(ctx, mcfLatest[key], res.Attributes.Summary)
+		open := openByHeli[key]
+		if len(open) > 0 {
+			res.Attributes.Complaints = mapComplaintListToFleetStatusDTO(ctx, h.complaintSvc, h.signoffSvc, open)
+		}
+		// Load the release form + status reasons when there is a defect, or a non-complaint
+		// AOG (e.g. maintenance next-due). Clean, non-AOG aircraft skip the extra lookups.
+		if len(open) > 0 || status == helicopter.StatusAOG {
+			res.Attributes.EASARelease = resolveEASARelease(ctx, h.easaSvc, heli.ID)
+			overdue, oErr := h.svc.OverdueInspections(ctx, heli.ID)
+			if oErr != nil {
+				slog.WarnContext(ctx, "fleet status: overdue inspections lookup failed", slog.Any("error", oErr))
+			}
+			if res.Attributes.Helicopter != nil {
+				res.Attributes.Helicopter.StatusReasons = buildHelicopterStatusReasons(heli, open, overdue, now)
+			}
+		}
+		out = append(out, res)
+	}
+	return out, nil
+}
+
+type fleetStatusRender struct {
+	svc     fleetstatus.Service
+	storage fileManagerDownloadURLStorage
+	cache   map[string]shareddto.FleetStatusSummary
+}
+
+func fleetStatusResourceForHelicopter(ctx context.Context, r fleetStatusRender, heli *helicopter.Helicopter, latest *fleetstatus.FleetStatus, status string) responsedto.FleetStatusResource {
+	if latest != nil {
+		res := fleetStatusListResourceWithSummaryCache(ctx, r.svc, r.storage, latest, status, r.cache)
+		res.Attributes.Helicopter = fleetStatusHelicopterResource(heli, status)
+		return res
+	}
+	return responsedto.FleetStatusResource{
+		Type: "fleet_status",
+		Attributes: responsedto.FleetStatusAttributes{
+			Helicopter:           fleetStatusHelicopterResource(heli, status),
+			MaintenanceSchedules: fleetStatusMaintenanceSchedules(nil),
+			Files:                fleetStatusFiles(ctx, r.storage, nil),
+		},
+	}
+}
+
+// buildFleetMCF renders the helicopter's MCF for the fleet page. When there is a real
+// MCF it uses its values (sign = completed). When there is none it returns a placeholder
+// (empty id, unsigned) pre-filled from the aircraft's current airframe hours / landings.
+func buildFleetMCF(ctx context.Context, row *mcf.MaintenanceCheckFlight, summary shareddto.FleetStatusSummary) *shareddto.FleetStatusMCF {
+	// The fleet shows the helicopter's LATEST MCF. When none exists — or the MCF is still a
+	// draft — af_hours / landing_count pre-fill from the aircraft's current (flight-derived)
+	// totals (like legacy). A signed (completed) MCF stays visible with its own recorded
+	// snapshot + signer, until a new MCF replaces it.
+	// af_hours / landing_count are the SIGNED check-flight values — only present once the MCF
+	// is signed. Unsigned states (none / draft / cancelled) omit them.
+	out := &shareddto.FleetStatusMCF{}
+	if row == nil {
+		return out
+	}
+	// Surface the record (id + date) for any real MCF — including a cancelled one — so the
+	// fleet distinguishes it from "no MCF".
+	out.ID = idString(row.ID)
+	if row.Date != nil && !row.Date.IsZero() {
+		d := row.Date.UTC().Format("2006-01-02")
+		out.Date = &d
+	}
+	// A cancelled MCF ("tidak jadi") releases the status — active:false, sign:false — but the
+	// record stays visible (id/date) so it shows as a cancelled MCF, not "no MCF".
+	if row.IsCancelled() {
+		return out
+	}
+	out.Sign = row.IsComplete()
+	// Active only while the MCF is an open draft. Once signed it is considered done
+	// (regardless of pass/fail) and the helicopter leaves MCF → not active.
+	out.Active = row.IsPending()
+	if row.IsComplete() {
+		if af := strings.TrimSpace(row.AFHours); af != "" {
+			out.AFHours = &af
+		}
+		lc := row.LandingCount
+		out.LandingCount = &lc
+		out.SignedBy = idString(row.CompletedBy)
+		if n := userctx.GetDisplayName(ctx, row.CompletedBy); n != "" {
+			out.SignedByName = &n
+		}
+		if s := userctx.GetShortName(ctx, row.CompletedBy); s != "" {
+			out.SignedByShort = &s
+		}
+	}
+	return out
+}
+
+
+func (h *FleetStatusHandler) deriveHelicopterStatus(ctx context.Context, heli *helicopter.Helicopter, helicopterID []byte) string {
+	if heli == nil {
+		return ""
+	}
+	inUse := false
+	if len(helicopterID) == 16 {
+		got, err := h.helicopterSvc.IsInUse(ctx, helicopterID)
+		if err != nil {
+			slog.WarnContext(ctx, "fleet status: in-use lookup failed",
+				slog.Any("error", err),
+				slog.String("helicopter_id",
+					idString(helicopterID)))
+		}
+		inUse = got
+	}
+	grounded := false
+	mcfPending := false
+	if len(helicopterID) == 16 {
+		grounded = groundingHelicopterSet(ctx, h.complaintSvc, [][]byte{helicopterID}, time.Now().UTC())[string(helicopterID)]
+		mcfPending = mcfPendingHelicopterSet(ctx, h.mcfSvc, [][]byte{helicopterID})[string(helicopterID)]
+	}
+	return heli.DeriveStatus(helicopter.StatusInput{IsBook: inUse, IsMCF: mcfPending, ComplaintGrounded: grounded})
+}
diff --git a/internal/transport/http/handlers/reserve_ac_handler.go b/internal/transport/http/handlers/reserve_ac_handler.go
new file mode 100644
index 0000000..f63eb3b
--- /dev/null
+++ b/internal/transport/http/handlers/reserve_ac_handler.go
@@ -0,0 +1,3135 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	beforeflightinspection "wucher/internal/domain/before_flight_inspection"
+	"wucher/internal/domain/duty_roster"
+	"wucher/internal/domain/flight"
+	flightdata "wucher/internal/domain/flight_data"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	flightinspectionfilechecklist "wucher/internal/domain/flight_inspection_file_checklist"
+	flightprepcheck "wucher/internal/domain/flight_prep_check"
+	fmreport "wucher/internal/domain/fm_report"
+	"wucher/internal/domain/helicopter"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	"wucher/internal/domain/mission"
+	reserveac "wucher/internal/domain/reserve_ac"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	rootdto "wucher/internal/transport/http/dto"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type ReserveAcHandler struct {
+	svc        reserveac.ReserveAcService
+	auth       *service.AuthService
+	flight     flight.FlightService
+	flightData flightdata.Service
+	mission    mission.Service
+	aircraft   helicopter.Service
+	inspect    flightinspection.FlightInspectionService
+	before     beforeflightinspection.Service
+	prep       flightprepcheck.Service
+	after      afterflightinspection.Service
+	fmReport   fmreport.Service
+	heliFile   helicopterfile.Service
+	fileCk     flightinspectionfilechecklist.Service
+	dutyRoster dutyroster.Service
+	storage    fileManagerDownloadURLStorage
+	takeover   *service.TakeoverService
+	validate   *validators.Validator
+}
+
+func NewReserveAcHandler(svc reserveac.ReserveAcService) *ReserveAcHandler {
+	return &ReserveAcHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+func (h *ReserveAcHandler) WithFlightService(flightSvc flight.FlightService) *ReserveAcHandler {
+	h.flight = flightSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithFlightDataService(flightDataSvc flightdata.Service) *ReserveAcHandler {
+	h.flightData = flightDataSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithMissionService(missionSvc mission.Service) *ReserveAcHandler {
+	h.mission = missionSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithAuthService(authSvc *service.AuthService) *ReserveAcHandler {
+	h.auth = authSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithHelicopterService(aircraftSvc helicopter.Service) *ReserveAcHandler {
+	h.aircraft = aircraftSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithFlightInspectionService(inspectionSvc flightinspection.FlightInspectionService) *ReserveAcHandler {
+	h.inspect = inspectionSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithBeforeFlightInspectionService(beforeSvc beforeflightinspection.Service) *ReserveAcHandler {
+	h.before = beforeSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithFlightPrepCheckService(prepSvc flightprepcheck.Service) *ReserveAcHandler {
+	h.prep = prepSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithAfterFlightInspectionService(afterSvc afterflightinspection.Service) *ReserveAcHandler {
+	h.after = afterSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithFMReportService(reportSvc fmreport.Service) *ReserveAcHandler {
+	h.fmReport = reportSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithHelicopterFileService(heliFileSvc helicopterfile.Service) *ReserveAcHandler {
+	h.heliFile = heliFileSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithFlightInspectionFileChecklistService(fileChecklistSvc flightinspectionfilechecklist.Service) *ReserveAcHandler {
+	h.fileCk = fileChecklistSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithDutyRosterService(dutyRosterSvc dutyroster.Service) *ReserveAcHandler {
+	h.dutyRoster = dutyRosterSvc
+	return h
+}
+
+func (h *ReserveAcHandler) WithFileStorage(storage fileManagerDownloadURLStorage) *ReserveAcHandler {
+	h.storage = storage
+	return h
+}
+
+func writeReserveAcErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	return response.WriteErrors(c, status, apperrorsx.EnrichErrorObjects(status, errs))
+}
+
+type reserveAcUpdateCoordinator interface {
+	UpdateDetailed(context.Context, service.ReserveAcUpdateInput) (*reserveac.ReserveAc, error)
+}
+
+type reserveAcCreateCoordinator interface {
+	CreateDetailed(context.Context, service.ReserveAcCreateInput) (*reserveac.ReserveAc, error)
+}
+
+func normalizeTakeoverDutyRosterDetail(resource *responsedto.DutyRosterResource) {
+	if resource == nil {
+		return
+	}
+	resource.Attributes.ShiftTime = responsedto.DutyRosterShiftTime{}
+	detail := &resource.Attributes.Detail
+	if detail.Pilot == nil {
+		detail.Pilot = []responsedto.DutyRosterPilotCrew{}
+	}
+	if detail.Doctor == nil {
+		detail.Doctor = []responsedto.DutyRosterCrew{}
+	}
+	if detail.Rescuer == nil {
+		detail.Rescuer = []responsedto.DutyRosterCrew{}
+	}
+	if detail.Helper == nil {
+		detail.Helper = []responsedto.DutyRosterCrew{}
+	}
+	if detail.OtherPerson == nil {
+		detail.OtherPerson = []responsedto.DutyRosterCrew{}
+	}
+	for i := range detail.Doctor {
+		detail.Doctor[i].ShiftTime = nil
+	}
+	for i := range detail.Rescuer {
+		detail.Rescuer[i].ShiftTime = nil
+	}
+	for i := range detail.Helper {
+		detail.Helper[i].ShiftTime = nil
+	}
+	for i := range detail.OtherPerson {
+		detail.OtherPerson[i].ShiftTime = nil
+	}
+}
+
+func parseTakeoverUUID(v string, pointer string) ([]byte, *jsonapi.ErrorObject) {
+	id, err := uuidv7.ParseString(strings.TrimSpace(v))
+	if err != nil {
+		return nil, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: strings.TrimSpace(pointer) + " is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}
+	}
+	return id, nil
+}
+
+func parseTakeoverDate(v string) (time.Time, *jsonapi.ErrorObject) {
+	d, err := service.ParseDutyRosterDateOnly(v)
+	if err != nil {
+		return time.Time{}, &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "duty_date must be YYYY-MM-DD",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/duty_date"},
+		}
+	}
+	return d, nil
+}
+
+// CreateReserveAc godoc
+// @Summary Create reserve aircraft assignment
+// @Description Create reserve AC, create draft inspection, fill before + prepare inspection payload, and assign to flight.
+// @Tags Flights - Reserve AC
+// @Accept json
+// @Produce json
+// @Param request body requestdto.ReserveAcCreateRequest true "Create reserve AC request"
+// @Success 201 {object} responsedto.ReserveAcResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Router /api/v1/reserve-acs/create [post]
+func (h *ReserveAcHandler) Create(c *fiber.Ctx) error {
+	var req requestdto.ReserveAcCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	helicopterID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.AircraftID))
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "helicopter_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/helicopter_id"},
+		}})
+	}
+
+	inspectionDate, err := time.Parse("2006-01-02", strings.TrimSpace(req.Data.Attributes.Inspection.InspectionDate))
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "inspection.inspection_date must be YYYY-MM-DD",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/inspection/inspection_date"},
+		}})
+	}
+	if !hasReserveAcBeforePayload(req.Data.Attributes.Inspection.Before) {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "inspection.before is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/inspection/before"},
+		}})
+	}
+	if !hasReserveAcPreparePayload(req.Data.Attributes.Inspection.Prepare) {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "inspection.prepare is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/inspection/prepare"},
+		}})
+	}
+	flightID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.FlightID))
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "flight_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_id"},
+		}})
+	}
+	if creator, ok := h.svc.(reserveAcCreateCoordinator); ok {
+		created, createErr := creator.CreateDetailed(c.UserContext(), service.ReserveAcCreateInput{
+			HelicopterID:   helicopterID,
+			FlightID:       flightID,
+			InspectionDate: inspectionDate,
+			Before:         &req.Data.Attributes.Inspection.Before,
+			Prepare:        &req.Data.Attributes.Inspection.Prepare,
+			ActorUserID:    actorUserID(c),
+			Flight:         h.flight,
+			Inspect:        h.inspect,
+			BeforeSvc:      h.before,
+			Prep:           h.prep,
+			HeliFile:       h.heliFile,
+			FileChecklist:  h.fileCk,
+		})
+		if createErr != nil {
+			return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "ReserveAcHandler.CreateDetailed", createErr)
+		}
+		return h.writeReserveAcCreateResponse(c, created, flightID)
+	}
+
+	if h.flight == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Create failed",
+			Detail: "flight service is not configured",
+		}})
+	}
+	if h.inspect == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Create failed",
+			Detail: "flight inspection service is not configured",
+		}})
+	}
+	if h.before == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Create failed",
+			Detail: "before flight inspection service is not configured",
+		}})
+	}
+	if h.prep == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Create failed",
+			Detail: "flight prep check service is not configured",
+		}})
+	}
+	if h.heliFile == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Create failed",
+			Detail: "helicopter file service is not configured",
+		}})
+	}
+	if h.fileCk == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Create failed",
+			Detail: "flight inspection file checklist service is not configured",
+		}})
+	}
+	flightRow, err := h.flight.GetByID(c.UserContext(), flightID)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if flightRow == nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "flight_id does not exist",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_id"},
+		}})
+	}
+	if len(flightRow.ReserveAcID) == 16 {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "flight already has reserve_ac assigned",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_id"},
+		}})
+	}
+
+	exists, err := h.svc.AircraftExists(c.UserContext(), helicopterID)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if !exists {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "helicopter_id does not exist",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/helicopter_id"},
+		}})
+	}
+
+	inspection := &flightinspection.FlightInspection{
+		InspectionDate: inspectionDate.UTC(),
+		CreatedBy:      actorUserID(c),
+		UpdatedBy:      actorUserID(c),
+	}
+	if err := h.inspect.CreateDraft(c.UserContext(), inspection); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	row := &reserveac.ReserveAc{
+		Status:       reserveac.StatusPending,
+		AircraftID:   helicopterID,
+		InspectionID: inspection.ID,
+		CreatedBy:    actorUserID(c),
+		UpdatedBy:    actorUserID(c),
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	beforeReq := &beforeflightinspection.UpsertRequest{
+		OilEngineNR1Checked:       req.Data.Attributes.Inspection.Before.OilEngineNR1Checked,
+		OilEngineNR2Checked:       req.Data.Attributes.Inspection.Before.OilEngineNR2Checked,
+		HydraulicLHChecked:        req.Data.Attributes.Inspection.Before.HydraulicLHChecked,
+		HydraulicRHChecked:        req.Data.Attributes.Inspection.Before.HydraulicRHChecked,
+		OilTransmissionMGBChecked: req.Data.Attributes.Inspection.Before.OilTransmissionMGBChecked,
+		OilTransmissionIGBChecked: req.Data.Attributes.Inspection.Before.OilTransmissionIGBChecked,
+		OilTransmissionTGBChecked: req.Data.Attributes.Inspection.Before.OilTransmissionTGBChecked,
+		FuelAmount:                req.Data.Attributes.Inspection.Before.FuelAmount,
+		FuelUnit:                  req.Data.Attributes.Inspection.Before.FuelUnit,
+		FuelAddedAmount:           req.Data.Attributes.Inspection.Before.FuelAddedAmount,
+		Note:                      req.Data.Attributes.Inspection.Before.Note,
+	}
+	if _, err := h.before.Upsert(c.UserContext(), inspection.ID, beforeReq); err != nil {
+		_ = h.svc.Delete(c.UserContext(), row.ID, actorUserID(c))
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if _, err := h.prep.InitializeChecks(c.UserContext(), inspection.ID); err != nil {
+		_ = h.svc.Delete(c.UserContext(), row.ID, actorUserID(c))
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if _, err := h.prep.UpsertByFlightInspection(c.UserContext(), inspection.ID, &flightprepcheck.UpsertRequest{
+		NOTAMBriefing:         req.Data.Attributes.Inspection.Prepare.NotamBriefing,
+		WeatherBriefing:       req.Data.Attributes.Inspection.Prepare.WeatherBriefing,
+		OperationalFlightPlan: req.Data.Attributes.Inspection.Prepare.OperationalFlightPlan,
+	}); err != nil {
+		_ = h.svc.Delete(c.UserContext(), row.ID, actorUserID(c))
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if ok, err := h.upsertInspectionFileChecklistSection(
+		c,
+		inspection.ID,
+		helicopterID,
+		helicopterfile.SectionBeforeFirstFlightInspection,
+		req.Data.Attributes.Inspection.Before.FileChecklist,
+		"/data/attributes/inspection/before/file_checklist",
+		row.ID,
+	); err != nil {
+		return err
+	} else if !ok {
+		return nil
+	}
+	if ok, err := h.upsertInspectionFileChecklistSection(
+		c,
+		inspection.ID,
+		helicopterID,
+		helicopterfile.SectionFlightPreparationAndWB,
+		req.Data.Attributes.Inspection.Prepare.FileChecklist,
+		"/data/attributes/inspection/prepare/file_checklist",
+		row.ID,
+	); err != nil {
+		return err
+	} else if !ok {
+		return nil
+	}
+	flightRow.ReserveAcID = append([]byte(nil), row.ID...)
+	flightRow.UpdatedBy = actorUserID(c)
+	if err := h.flight.Update(c.UserContext(), flightRow); err != nil {
+		_ = h.svc.Delete(c.UserContext(), row.ID, actorUserID(c))
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	inspectionSummary, _ := h.buildCreateInspectionSummary(c, inspection.ID, helicopterID)
+	row.Status = h.calculateReserveAcStatus(inspectionSummary)
+	if updateErr := h.svc.Update(c.UserContext(), row); updateErr != nil {
+		_ = h.svc.Delete(c.UserContext(), row.ID, actorUserID(c))
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	aircraftSummary, _ := h.buildAircraftSummary(c, helicopterID)
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, reserveAcResource(created, reserveAcResourceOptions{
+			flightID:   flightID,
+			inspection: inspectionSummary,
+			aircraft:   aircraftSummary,
+		}))
+	}
+	return response.Write(c, fiber.StatusCreated, reserveAcResource(row, reserveAcResourceOptions{
+		flightID:   flightID,
+		inspection: inspectionSummary,
+		aircraft:   aircraftSummary,
+	}))
+}
+
+// GetReserveAc godoc
+// @Summary Get reserve AC by UUID or flight UUID
+// @Description Get reserve AC detail. Path `uuid` accepts reserve_ac id, and supports fallback to flight id.
+// @Tags Flights - Reserve AC
+// @Produce json
+// @Param uuid path string true "Reserve AC UUID or Flight UUID"
+// @Success 200 {object} responsedto.ReserveAcResponse
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/reserve-acs/get/{uuid} [get]
+func (h *ReserveAcHandler) Get(c *fiber.Ctx) error {
+	idRaw := strings.TrimSpace(c.Params("id"))
+	if idRaw == "" {
+		idRaw = strings.TrimSpace(c.Params("uuid"))
+	}
+	id, err := uuidv7.ParseString(idRaw)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/id"},
+		}})
+	}
+
+	row, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || row == nil {
+		if h.flight != nil {
+			flightRow, flightErr := h.flight.GetByID(c.UserContext(), id)
+			if flightErr == nil && flightRow != nil && len(flightRow.ReserveAcID) == 16 {
+				row, err = h.svc.GetByID(c.UserContext(), flightRow.ReserveAcID)
+			}
+		}
+		if err != nil || row == nil {
+			return writeReserveAcErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "reserve_ac not found",
+			}})
+		}
+	}
+
+	inspectionSummary, _ := h.buildCreateInspectionSummary(c, row.InspectionID, row.AircraftID)
+	aircraftSummary, _ := h.buildAircraftSummary(c, row.AircraftID)
+	lastDaily, _ := h.svc.GetLastDailyInspectionByHelicopterID(c.UserContext(), row.AircraftID)
+	return response.Write(c, fiber.StatusOK, reserveAcResource(row, reserveAcResourceOptions{
+		inspection: inspectionSummary,
+		aircraft:   aircraftSummary,
+		lastDaily:  reserveAcLastDailyInfo(lastDaily),
+	}))
+}
+
+// Legacy helper endpoint (no longer routed publicly).
+func (h *ReserveAcHandler) GetAfterFlightInspection(c *fiber.Ctx) error {
+	inspectionID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("inspection_id")))
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "inspection_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/inspection_id"},
+		}})
+	}
+	return h.getAfterFlightInspectionByID(c, inspectionID)
+}
+
+func (h *ReserveAcHandler) getAfterFlightInspectionByID(c *fiber.Ctx, inspectionID []byte) error {
+	if h.after == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Get failed",
+			Detail: "after flight inspection service is not configured",
+		}})
+	}
+	if h.inspect == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Get failed",
+			Detail: "flight inspection service is not configured",
+		}})
+	}
+	if h.heliFile == nil || h.fileCk == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Get failed",
+			Detail: "helicopter file checklist service is not configured",
+		}})
+	}
+
+	reserveAcRow, err := h.svc.GetActiveByInspectionID(c.UserContext(), inspectionID)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if reserveAcRow == nil {
+		return writeReserveAcErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "reserve_ac not found for inspection_id",
+		}})
+	}
+
+	row, err := h.after.GetByFlightInspectionID(c.UserContext(), inspectionID)
+	if err != nil {
+		if mapped := apperrorsx.Translate(apperrorsx.ModuleAfterFlightInspection, err); mapped != nil && mapped.Code != apperrorsx.CodeInternalServerError {
+			return apperrorsx.Write(c, mapped)
+		}
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	inspectionRow, _ := h.inspect.GetByID(c.UserContext(), inspectionID)
+	afterSection, err := h.buildInspectionChecklistSection(c, inspectionID, reserveAcRow.AircraftID, helicopterfile.SectionAfterLastFlightInspection)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Get failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	helicopterRow := h.afterFlightInspectionHelicopterResource(c.UserContext(), reserveAcRow)
+	summary := h.buildAfterFlightInspectionSummary(c.UserContext(), reserveAcRow)
+
+	return c.Status(fiber.StatusOK).JSON(afterFlightInspectionPayload(inspectionID, inspectionRow, helicopterRow, row, afterSection, summary))
+}
+
+// Legacy helper endpoint (no longer routed publicly).
+func (h *ReserveAcHandler) UpsertAfterFlightInspection(c *fiber.Ctx) error {
+	inspectionID, err := uuidv7.ParseString(strings.TrimSpace(c.Params("inspection_id")))
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "inspection_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/inspection_id"},
+		}})
+	}
+
+	var req requestdto.ReserveAcAfterFlightInspectionUpsertRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	return h.upsertAfterFlightInspectionByID(c, inspectionID, req.Data.Attributes)
+}
+
+func (h *ReserveAcHandler) upsertAfterFlightInspectionByID(c *fiber.Ctx, inspectionID []byte, attrs requestdto.ReserveAcAfterFlightInspectionAttributes) error {
+	if h.after == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Update failed",
+			Detail: "after flight inspection service is not configured",
+		}})
+	}
+	if h.inspect == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Update failed",
+			Detail: "flight inspection service is not configured",
+		}})
+	}
+	if h.heliFile == nil || h.fileCk == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Update failed",
+			Detail: "helicopter file checklist service is not configured",
+		}})
+	}
+
+	reserveAcRow, err := h.svc.GetActiveByInspectionID(c.UserContext(), inspectionID)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if reserveAcRow == nil {
+		return writeReserveAcErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "reserve_ac not found for inspection_id",
+		}})
+	}
+
+	if ok, detail, err := h.allFlightMissionsComplete(c.UserContext(), reserveAcRow); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: "an internal error occurred",
+		}})
+	} else if !ok {
+		if strings.TrimSpace(detail) == "" {
+			detail = "all missions in this flight must have complete flight data before after flight inspection"
+		}
+		c.Locals(apperrorsx.ContextKeyHTTPErrorDetail, detail)
+		def := apperrorsx.ErrFlightDataAfterFlightIncomplete
+		return jsonapi.WriteErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status:    strconv.Itoa(def.Status),
+			Code:      def.Code,
+			ErrorCode: def.ErrorCode,
+			Title:     def.Title,
+			Detail:    detail,
+			Source:    &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_inspection_id"},
+		}})
+	}
+
+	if ok, err := h.validateInspectionChecklistSectionComplete(
+		c,
+		reserveAcRow.AircraftID,
+		helicopterfile.SectionAfterLastFlightInspection,
+		attrs.FileChecklist,
+		"/data/attributes/file_checklist",
+	); err != nil {
+		return err
+	} else if !ok {
+		return nil
+	}
+
+	upsertReq := &afterflightinspection.UpsertRequest{
+		OilEngineNR1Checked:       attrs.OilEngineNR1Checked,
+		OilEngineNR2Checked:       attrs.OilEngineNR2Checked,
+		HydraulicLHChecked:        attrs.HydraulicLHChecked,
+		HydraulicRHChecked:        attrs.HydraulicRHChecked,
+		OilTransmissionMGBChecked: attrs.OilTransmissionMGBChecked,
+		OilTransmissionIGBChecked: attrs.OilTransmissionIGBChecked,
+		OilTransmissionTGBChecked: attrs.OilTransmissionTGBChecked,
+		Note:                      attrs.Note,
+	}
+	row, err := h.after.Upsert(c.UserContext(), inspectionID, upsertReq)
+	if err != nil {
+		if mapped := apperrorsx.Translate(apperrorsx.ModuleAfterFlightInspection, err); mapped != nil && mapped.Code != apperrorsx.CodeInternalServerError {
+			return apperrorsx.Write(c, mapped)
+		}
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	if ok, err := h.upsertInspectionFileChecklistSection(
+		c,
+		inspectionID,
+		reserveAcRow.AircraftID,
+		helicopterfile.SectionAfterLastFlightInspection,
+		attrs.FileChecklist,
+		"/data/attributes/file_checklist",
+		nil,
+	); err != nil {
+		return err
+	} else if !ok {
+		return nil
+	}
+
+	if h.fmReport != nil {
+		flightRow, flightErr := h.flight.GetByReserveAcID(c.UserContext(), reserveAcRow.ID)
+		if flightErr != nil || flightRow == nil {
+			return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+				Status: "500",
+				Title:  "Internal Server Error",
+				Detail: "failed to load flight for fm report",
+			}})
+		}
+		if _, reportErr := h.fmReport.UpsertForFlight(c.UserContext(), flightRow, inspectionID); reportErr != nil {
+			return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+				Status: "500",
+				Title:  "Internal Server Error",
+				Detail: "failed to upsert fm report",
+			}})
+		}
+	}
+
+	// The after-flight inspection has already been persisted above; this only
+	// re-reads data to build the response. A failure here is a server-side
+	// rendering error, not a failed update, so return 500 (not 400).
+	inspectionRow, _ := h.inspect.GetByID(c.UserContext(), inspectionID)
+	afterSection, err := h.buildInspectionChecklistSection(c, inspectionID, reserveAcRow.AircraftID, helicopterfile.SectionAfterLastFlightInspection)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Internal Server Error",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	helicopterRow := h.afterFlightInspectionHelicopterResource(c.UserContext(), reserveAcRow)
+	summary := h.buildAfterFlightInspectionSummary(c.UserContext(), reserveAcRow)
+
+	return c.Status(fiber.StatusOK).JSON(afterFlightInspectionPayload(inspectionID, inspectionRow, helicopterRow, row, afterSection, summary))
+}
+
+func (h *ReserveAcHandler) allFlightMissionsComplete(ctx context.Context, reserveAcRow *reserveac.ReserveAc) (bool, string, error) {
+	if h == nil || h.flight == nil || h.mission == nil || h.flightData == nil || reserveAcRow == nil || len(reserveAcRow.ID) != 16 {
+		return false, "", nil
+	}
+
+	flightRow, err := h.flight.GetByReserveAcID(ctx, reserveAcRow.ID)
+	if err != nil {
+		return false, "", err
+	}
+	if flightRow == nil || len(flightRow.ID) != 16 {
+		return false, "", nil
+	}
+
+	missions, err := h.mission.ListByFlightID(ctx, flightRow.ID)
+	if err != nil {
+		return false, "", err
+	}
+	if len(missions) == 0 {
+		return false, "cannot submit after-flight: this flight has no missions", nil
+	}
+
+	missing := make([]string, 0, len(missions))
+	for i := range missions {
+		fd, ok := h.loadMissionFlightData(ctx, missions[i])
+		if !ok || !flightdata.IsComplete(fd) {
+			missionID, _ := uuidv7.BytesToString(missions[i].ID)
+			label := "mission"
+			if missionID != "" {
+				label = "mission " + missionID
+			}
+			if t := strings.TrimSpace(missions[i].Type); t != "" {
+				label += " (" + strings.ToUpper(t) + ")"
+			}
+			if !ok || fd == nil {
+				label += " has no flight data"
+			} else {
+				label += " has incomplete flight data"
+			}
+			missing = append(missing, label)
+		}
+	}
+
+	if len(missing) > 0 {
+		return false, "cannot submit after-flight: " + strings.Join(missing, "; "), nil
+	}
+
+	return true, "", nil
+}
+
+// GetLastFlightsInspection godoc
+// @Summary Get last flights inspection
+// @Description Get after-flight inspection detail and AFI file checklist by query `inspection_id`.
+// @Tags Flights - After Flights Inspection
+// @Produce json
+// @Param inspection_id query string true "Flight Inspection UUID"
+// @Success 200 {object} rootdto.AfterFlightInspectionResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/after-flight-inspection/get [get]
+func (h *ReserveAcHandler) GetLastFlightsInspection(c *fiber.Ctx) error {
+	inspectionID, err := uuidv7.ParseString(strings.TrimSpace(c.Query("inspection_id")))
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "inspection_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/query/inspection_id"},
+		}})
+	}
+	return h.getAfterFlightInspectionByID(c, inspectionID)
+}
+
+// CreateLastFlightsInspection godoc
+// @Summary Create last flights inspection
+// @Description Create after-flight inspection and AFI file checklist for a flight inspection.
+// @Tags Flights - After Flights Inspection
+// @Accept json
+// @Produce json
+// @Param request body requestdto.LastFlightsInspectionCreateRequest true "Create last flights inspection request"
+// @Success 200 {object} rootdto.AfterFlightInspectionResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/after-flight-inspection/create [post]
+func (h *ReserveAcHandler) CreateLastFlightsInspection(c *fiber.Ctx) error {
+	if h.after == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Create failed",
+			Detail: "after flight inspection service is not configured",
+		}})
+	}
+	var req requestdto.LastFlightsInspectionCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	inspectionID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.FlightInspectionID))
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "flight_inspection_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_inspection_id"},
+		}})
+	}
+	existing, err := h.after.GetByFlightInspectionID(c.UserContext(), inspectionID)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if existing != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "after flight inspection already exists",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_inspection_id"},
+		}})
+	}
+	return h.upsertAfterFlightInspectionByID(c, inspectionID, req.Data.Attributes.ReserveAcAfterFlightInspectionAttributes)
+}
+
+// UpdateLastFlightsInspection godoc
+// @Summary Update last flights inspection
+// @Description Update after-flight inspection and AFI file checklist for a flight inspection.
+// @Tags Flights - After Flights Inspection
+// @Accept json
+// @Produce json
+// @Param request body requestdto.LastFlightsInspectionUpdateRequest true "Update last flights inspection request"
+// @Success 200 {object} rootdto.AfterFlightInspectionResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/after-flight-inspection/update [patch]
+func (h *ReserveAcHandler) UpdateLastFlightsInspection(c *fiber.Ctx) error {
+	if h.after == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Update failed",
+			Detail: "after flight inspection service is not configured",
+		}})
+	}
+	var req requestdto.LastFlightsInspectionUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	inspectionID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.FlightInspectionID))
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "flight_inspection_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_inspection_id"},
+		}})
+	}
+	existing, err := h.after.GetByFlightInspectionID(c.UserContext(), inspectionID)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if existing == nil {
+		return writeReserveAcErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "after flight inspection not found",
+		}})
+	}
+	return h.upsertAfterFlightInspectionByID(c, inspectionID, req.Data.Attributes.ReserveAcAfterFlightInspectionAttributes)
+}
+
+// DeleteLastFlightsInspection godoc
+// @Summary Delete last flights inspection
+// @Description Delete after-flight inspection and AFI checklist rows by `flight_inspection_id`.
+// @Tags Flights - After Flights Inspection
+// @Accept json
+// @Produce json
+// @Param request body requestdto.LastFlightsInspectionDeleteRequest true "Delete last flights inspection request"
+// @Success 200 {object} jsonapi.Document
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/after-flight-inspection/delete [delete]
+func (h *ReserveAcHandler) DeleteLastFlightsInspection(c *fiber.Ctx) error {
+	var req requestdto.LastFlightsInspectionDeleteRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	inspectionID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.FlightInspectionID))
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "flight_inspection_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/flight_inspection_id"},
+		}})
+	}
+	if h.after == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Delete failed",
+			Detail: "after flight inspection service is not configured",
+		}})
+	}
+	if h.heliFile == nil || h.fileCk == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Delete failed",
+			Detail: "helicopter file checklist service is not configured",
+		}})
+	}
+
+	existing, err := h.after.GetByFlightInspectionID(c.UserContext(), inspectionID)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if existing == nil {
+		return writeReserveAcErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "after flight inspection not found",
+		}})
+	}
+
+	reserveAcRow, err := h.svc.GetActiveByInspectionID(c.UserContext(), inspectionID)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if reserveAcRow == nil {
+		return writeReserveAcErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "reserve_ac not found for inspection_id",
+		}})
+	}
+
+	if err := h.after.DeleteByFlightInspectionID(c.UserContext(), inspectionID); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if err := h.deleteInspectionFileChecklistSection(c, inspectionID, reserveAcRow.AircraftID, helicopterfile.SectionAfterLastFlightInspection); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "last_flights_inspection",
+		ID:   idString(inspectionID),
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// UpdateReserveAc godoc
+// @Summary Update reserve AC
+// @Description Update reserve AC using body `data.id`.
+// @Tags Flights - Reserve AC
+// @Accept json
+// @Produce json
+// @Param request body requestdto.ReserveAcUpdateRequest true "Update reserve AC request"
+// @Success 200 {object} responsedto.ReserveAcResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/reserve-acs/update [patch]
+func (h *ReserveAcHandler) Update(c *fiber.Ctx) error {
+	var req requestdto.ReserveAcUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	pathID := strings.TrimSpace(c.Params("id"))
+	if pathID == "" {
+		pathID = strings.TrimSpace(c.Params("uuid"))
+	}
+	bodyID := strings.TrimSpace(req.Data.ID)
+	if pathID == "" && bodyID == "" {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if pathID != "" && bodyID != "" && bodyID != pathID {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path id",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	targetID := bodyID
+	if targetID == "" {
+		targetID = pathID
+	}
+	id, err := uuidv7.ParseString(targetID)
+	if err != nil {
+		sourcePtr := "/data/id"
+		if targetID == pathID && pathID != "" && bodyID == "" {
+			sourcePtr = "/path/id"
+		}
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: sourcePtr},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	flightRaw, flightPointer, hasFlight := reserveAcUpdateFlightInput(attrs)
+	if attrs.AircraftID == nil && attrs.Inspection == nil && !hasFlight {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	if updater, ok := h.svc.(reserveAcUpdateCoordinator); ok {
+		updated, updateErr := updater.UpdateDetailed(c.UserContext(), service.ReserveAcUpdateInput{
+			ID:            id,
+			ActorUserID:   actorUserID(c),
+			AircraftID:    attrs.AircraftID,
+			FlightID:      attrs.FlightID,
+			Inspection:    attrs.Inspection,
+			Flight:        h.flight,
+			Inspect:       h.inspect,
+			Before:        h.before,
+			Prep:          h.prep,
+			HeliFile:      h.heliFile,
+			FileChecklist: h.fileCk,
+		})
+		if updateErr != nil {
+			return writeReserveAcUpdateError(c, updateErr)
+		}
+		return h.writeReserveAcUpdateResponse(c, updated)
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeReserveAcErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "reserve_ac not found",
+		}})
+	}
+
+	if hasFlight {
+		if h.flight == nil {
+			return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+				Status: "500",
+				Title:  "Update failed",
+				Detail: "flight service is not configured",
+			}})
+		}
+		flightID, parseErr := uuidv7.ParseString(flightRaw)
+		if parseErr != nil {
+			return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "flight_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: flightPointer},
+			}})
+		}
+
+		targetFlight, flightErr := h.flight.GetByID(c.UserContext(), flightID)
+		if flightErr != nil {
+			return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Update failed",
+				Detail: flightErr.Error(),
+			}})
+		}
+		if targetFlight == nil {
+			return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "flight_id does not exist",
+				Source: &jsonapi.ErrorSource{Pointer: flightPointer},
+			}})
+		}
+		if len(targetFlight.ReserveAcID) == 16 && !bytes.Equal(targetFlight.ReserveAcID, existing.ID) {
+			return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "flight already has reserve_ac assigned",
+				Source: &jsonapi.ErrorSource{Pointer: flightPointer},
+			}})
+		}
+
+		currentFlight, currentErr := h.flight.GetByReserveAcID(c.UserContext(), existing.ID)
+		if currentErr != nil {
+			return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Update failed",
+				Detail: currentErr.Error(),
+			}})
+		}
+		if currentFlight != nil && !bytes.Equal(currentFlight.ID, targetFlight.ID) {
+			currentFlight.ReserveAcID = nil
+			currentFlight.UpdatedBy = actorUserID(c)
+			if updateErr := h.flight.Update(c.UserContext(), currentFlight); updateErr != nil {
+				return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+					Status: "400",
+					Title:  "Update failed",
+					Detail: "an internal error occurred",
+				}})
+			}
+		}
+
+		if len(targetFlight.ReserveAcID) != 16 || !bytes.Equal(targetFlight.ReserveAcID, existing.ID) {
+			targetFlight.ReserveAcID = append([]byte(nil), existing.ID...)
+			targetFlight.UpdatedBy = actorUserID(c)
+			if updateErr := h.flight.Update(c.UserContext(), targetFlight); updateErr != nil {
+				return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+					Status: "400",
+					Title:  "Update failed",
+					Detail: "an internal error occurred",
+				}})
+			}
+		}
+	}
+
+	if attrs.AircraftID != nil && strings.TrimSpace(*attrs.AircraftID) != "" {
+		aircraftValue := strings.TrimSpace(*attrs.AircraftID)
+		helicopterID, parseErr := uuidv7.ParseString(aircraftValue)
+		if parseErr != nil {
+			return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "helicopter_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/helicopter_id"},
+			}})
+		}
+		exists, existsErr := h.svc.AircraftExists(c.UserContext(), helicopterID)
+		if existsErr != nil {
+			return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Update failed",
+				Detail: existsErr.Error(),
+			}})
+		}
+		if !exists {
+			return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "helicopter_id does not exist",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/helicopter_id"},
+			}})
+		}
+		existing.AircraftID = helicopterID
+	}
+
+	if attrs.Inspection != nil {
+		inspectionRow, getErr := h.inspect.GetByID(c.UserContext(), existing.InspectionID)
+		if getErr != nil {
+			return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Update failed",
+				Detail: "an internal error occurred",
+			}})
+		}
+		if inspectionRow == nil {
+			return writeReserveAcErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "flight inspection not found",
+			}})
+		}
+
+		if attrs.Inspection.InspectionDate != nil {
+			inspectionDate, parseErr := time.Parse("2006-01-02", strings.TrimSpace(*attrs.Inspection.InspectionDate))
+			if parseErr != nil {
+				return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+					Status: "422",
+					Title:  "Validation error",
+					Detail: "inspection.inspection_date must be YYYY-MM-DD",
+					Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/inspection/inspection_date"},
+				}})
+			}
+			inspectionRow.InspectionDate = inspectionDate.UTC()
+			inspectionRow.UpdatedBy = actorUserID(c)
+			if updateErr := h.inspect.Update(c.UserContext(), inspectionRow); updateErr != nil {
+				return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+					Status: "400",
+					Title:  "Update failed",
+					Detail: "an internal error occurred",
+				}})
+			}
+		}
+
+		if attrs.Inspection.Before != nil {
+			beforeReq := &beforeflightinspection.UpsertRequest{
+				OilEngineNR1Checked:       attrs.Inspection.Before.OilEngineNR1Checked,
+				OilEngineNR2Checked:       attrs.Inspection.Before.OilEngineNR2Checked,
+				HydraulicLHChecked:        attrs.Inspection.Before.HydraulicLHChecked,
+				HydraulicRHChecked:        attrs.Inspection.Before.HydraulicRHChecked,
+				OilTransmissionMGBChecked: attrs.Inspection.Before.OilTransmissionMGBChecked,
+				OilTransmissionIGBChecked: attrs.Inspection.Before.OilTransmissionIGBChecked,
+				OilTransmissionTGBChecked: attrs.Inspection.Before.OilTransmissionTGBChecked,
+				FuelAmount:                attrs.Inspection.Before.FuelAmount,
+				FuelUnit:                  attrs.Inspection.Before.FuelUnit,
+				FuelAddedAmount:           attrs.Inspection.Before.FuelAddedAmount,
+				Note:                      attrs.Inspection.Before.Note,
+			}
+			if _, upsertErr := h.before.Upsert(c.UserContext(), existing.InspectionID, beforeReq); upsertErr != nil {
+				return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+					Status: "400",
+					Title:  "Update failed",
+					Detail: upsertErr.Error(),
+				}})
+			}
+			if attrs.Inspection.Before.FileChecklist != nil {
+				if ok, err := h.upsertInspectionFileChecklistSection(
+					c,
+					existing.InspectionID,
+					existing.AircraftID,
+					helicopterfile.SectionBeforeFirstFlightInspection,
+					attrs.Inspection.Before.FileChecklist,
+					"/data/attributes/inspection/before/file_checklist",
+					nil,
+				); err != nil {
+					return err
+				} else if !ok {
+					return nil
+				}
+			}
+		}
+
+		if attrs.Inspection.Prepare != nil {
+			if _, upsertErr := h.prep.UpsertByFlightInspection(c.UserContext(), existing.InspectionID, &flightprepcheck.UpsertRequest{
+				NOTAMBriefing:         attrs.Inspection.Prepare.NotamBriefing,
+				WeatherBriefing:       attrs.Inspection.Prepare.WeatherBriefing,
+				OperationalFlightPlan: attrs.Inspection.Prepare.OperationalFlightPlan,
+			}); upsertErr != nil {
+				return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+					Status: "400",
+					Title:  "Update failed",
+					Detail: upsertErr.Error(),
+				}})
+			}
+
+			if attrs.Inspection.Prepare.FileChecklist != nil {
+				if ok, err := h.upsertInspectionFileChecklistSection(
+					c,
+					existing.InspectionID,
+					existing.AircraftID,
+					helicopterfile.SectionFlightPreparationAndWB,
+					attrs.Inspection.Prepare.FileChecklist,
+					"/data/attributes/inspection/prepare/file_checklist",
+					nil,
+				); err != nil {
+					return err
+				} else if !ok {
+					return nil
+				}
+			}
+		}
+	}
+
+	existing.UpdatedBy = actorUserID(c)
+	updatedInspectionSummary, _ := h.buildCreateInspectionSummary(c, existing.InspectionID, existing.AircraftID)
+	existing.Status = h.calculateReserveAcStatus(updatedInspectionSummary)
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), id)
+	if err == nil && updated != nil {
+		inspectionSummary, _ := h.buildCreateInspectionSummary(c, updated.InspectionID, updated.AircraftID)
+		aircraftSummary, _ := h.buildAircraftSummary(c, updated.AircraftID)
+		return response.Write(c, fiber.StatusOK, reserveAcResource(updated, reserveAcResourceOptions{
+			inspection: inspectionSummary,
+			aircraft:   aircraftSummary,
+		}))
+	}
+	inspectionSummary, _ := h.buildCreateInspectionSummary(c, existing.InspectionID, existing.AircraftID)
+	aircraftSummary, _ := h.buildAircraftSummary(c, existing.AircraftID)
+	return response.Write(c, fiber.StatusOK, reserveAcResource(existing, reserveAcResourceOptions{
+		inspection: inspectionSummary,
+		aircraft:   aircraftSummary,
+	}))
+}
+
+func (h *ReserveAcHandler) writeReserveAcUpdateResponse(c *fiber.Ctx, row *reserveac.ReserveAc) error {
+	if row == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Update failed",
+			Detail: "reserve_ac update returned no row",
+		}})
+	}
+
+	inspectionSummary, _ := h.buildCreateInspectionSummary(c, row.InspectionID, row.AircraftID)
+	aircraftSummary, _ := h.buildAircraftSummary(c, row.AircraftID)
+	return response.Write(c, fiber.StatusOK, reserveAcResource(row, reserveAcResourceOptions{
+		inspection: inspectionSummary,
+		aircraft:   aircraftSummary,
+	}))
+}
+
+func (h *ReserveAcHandler) writeReserveAcCreateResponse(c *fiber.Ctx, row *reserveac.ReserveAc, flightID []byte) error {
+	if row == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Create failed",
+			Detail: "reserve_ac create returned no row",
+		}})
+	}
+
+	inspectionSummary, _ := h.buildCreateInspectionSummary(c, row.InspectionID, row.AircraftID)
+	aircraftSummary, _ := h.buildAircraftSummary(c, row.AircraftID)
+	return response.Write(c, fiber.StatusCreated, reserveAcResource(row, reserveAcResourceOptions{
+		flightID:   flightID,
+		inspection: inspectionSummary,
+		aircraft:   aircraftSummary,
+	}))
+}
+
+func writeReserveAcUpdateError(c *fiber.Ctx, err error) error {
+	if err == nil {
+		return writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Update failed",
+			Detail: "reserve_ac update failed",
+		}})
+	}
+
+	var updateErr *service.ReserveAcUpdateError
+	if !errors.As(err, &updateErr) {
+		return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "ReserveAcHandler.Update", err)
+	}
+
+	obj := jsonapi.ErrorObject{
+		Status: strconv.Itoa(updateErr.Status),
+		Title:  updateErr.Title,
+		Detail: updateErr.Detail,
+	}
+	if updateErr.Pointer != "" {
+		obj.Source = &jsonapi.ErrorSource{Pointer: updateErr.Pointer}
+	}
+	return writeReserveAcErrors(c, updateErr.Status, []jsonapi.ErrorObject{obj})
+}
+
+// DeleteReserveAc godoc
+// @Summary Delete reserve AC
+// @Description Delete reserve AC by body `data.id`.
+// @Tags Flights - Reserve AC
+// @Accept json
+// @Produce json
+// @Param request body requestdto.ReserveAcDeleteRequest true "Delete reserve AC request"
+// @Success 200 {object} jsonapi.Document
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Router /api/v1/reserve-acs/delete [delete]
+func (h *ReserveAcHandler) Delete(c *fiber.Ctx) error {
+	var req requestdto.ReserveAcDeleteRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	idRaw := strings.TrimSpace(req.Data.ID)
+	id, err := uuidv7.ParseString(idRaw)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		status, errObj := buildServiceErrorObject("Delete failed", err, "reserve ac not found")
+		return writeReserveAcErrors(c, status, []jsonapi.ErrorObject{errObj})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "reserve_ac_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListReserveAc godoc
+// @Summary List reserve AC
+// @Description Supports `search`, `filter[search]`, `sort`, `page[number]`, `page[size]`, `page`, `size`, and `limit`.
+// @Tags Flights - Reserve AC
+// @Produce json
+// @Param search query string false "Search text"
+// @Param filter[search] query string false "Search text (JSON:API style)"
+// @Param id query string false "Reserve AC UUID (exact match)"
+// @Param flight_id query string false "Flight UUID (exact match)"
+// @Param sort query string false "Sort field"
+// @Param page[number] query int false "Page number"
+// @Param page[size] query int false "Page size"
+// @Param page query int false "Page number (fallback)"
+// @Param size query int false "Page size (fallback)"
+// @Param limit query int false "Page size override"
+// @Success 200 {object} responsedto.ReserveAcListResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/reserve-acs/get-all [get]
+func (h *ReserveAcHandler) List(c *fiber.Ctx) error {
+	userID := actorUserID(c)
+	if len(userID) == 0 {
+		return writeReserveAcErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	search := strings.TrimSpace(c.Query("filter[search]"))
+	if search == "" {
+		search = strings.TrimSpace(c.Query("search"))
+	}
+	from := strings.TrimSpace(c.Query("from"))
+	to := strings.TrimSpace(c.Query("to"))
+	if from == "" {
+		from = time.Now().UTC().Format("2006-01-02")
+	}
+	if to == "" {
+		to = from
+	}
+
+	groups, total, booked, err := h.buildReserveAcHelicopterGroups(c.UserContext(), userID, search, from, to, 0, 0)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, groups, map[string]any{
+		"page_number":       pageNumber,
+		"page_size":         pageSize,
+		"total":             total,
+		"from":              from,
+		"to":                to,
+		"timezone":          "UTC",
+		"booked_count":      booked,
+		"available_count":   total - booked,
+		"total_helicopters": total,
+	})
+}
+
+// ListReserveAcDatatable godoc
+// @Summary List reserve AC (datatable)
+// @Description Datatable list scoped by auth user. Admin can see all rows; non-admin only sees reserve AC linked to own flight assignments.
+// @Tags Flights - Reserve AC
+// @Produce json
+// @Param search query string false "Search text"
+// @Param filter[search] query string false "Search text (JSON:API style)"
+// @Param id query string false "Reserve AC UUID (exact match)"
+// @Param flight_id query string false "Flight UUID (exact match)"
+// @Param sort query string false "Sort field"
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override"
+// @Param draw query int false "Draw counter (optional)"
+// @Success 200 {object} responsedto.ReserveAcListResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 401 {object} jsonapi.ErrorDocument
+// @Router /api/v1/reserve-acs/get-all/dt [get]
+func (h *ReserveAcHandler) ListDatatable(c *fiber.Ctx) error {
+	userID := actorUserID(c)
+	if len(userID) == 0 {
+		return writeReserveAcErrors(c, fiber.StatusUnauthorized, []jsonapi.ErrorObject{{
+			Status: "401",
+			Title:  "Unauthorized",
+			Detail: "missing auth context",
+		}})
+	}
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	pageSize := parseIntDefault(c.Query("limit"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := strings.TrimSpace(c.Query("filter[search]"))
+	if search == "" {
+		search = strings.TrimSpace(c.Query("search"))
+	}
+	from := strings.TrimSpace(c.Query("from"))
+	to := strings.TrimSpace(c.Query("to"))
+	if from == "" {
+		from = time.Now().UTC().Format("2006-01-02")
+	}
+	if to == "" {
+		to = from
+	}
+	groups, total, booked, err := h.buildReserveAcHelicopterGroups(c.UserContext(), userID, search, from, to, 0, 0)
+	if err != nil {
+		return writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, groups, map[string]any{
+		"draw":              draw,
+		"records_total":     total,
+		"records_filtered":  total,
+		"page_number":       pageNumber,
+		"page_size":         pageSize,
+		"total":             total,
+		"from":              from,
+		"to":                to,
+		"timezone":          "UTC",
+		"booked_count":      booked,
+		"available_count":   total - booked,
+		"total_helicopters": total,
+	})
+}
+
+func (h *ReserveAcHandler) buildReserveAcHelicopterGroups(ctx context.Context, userID []byte, search, fromRaw, toRaw string, limit, offset int) ([]responsedto.ReserveAcHelicopterGroupResource, int64, int64, error) {
+	if h.aircraft == nil || h.flight == nil {
+		return []responsedto.ReserveAcHelicopterGroupResource{}, 0, 0, nil
+	}
+	from, err := time.Parse("2006-01-02", fromRaw)
+	if err != nil {
+		return nil, 0, 0, err
+	}
+	to, err := time.Parse("2006-01-02", toRaw)
+	if err != nil {
+		return nil, 0, 0, err
+	}
+	if to.Before(from) {
+		to = from
+	}
+
+	helicopters, _, err := h.aircraft.List(ctx, "", nil, "", 0, 0, nil)
+	if err != nil {
+		return nil, 0, 0, err
+	}
+	flights := make([]flight.Flight, 0)
+	if h.isReserveAcAdmin(ctx, userID) {
+		flights, _, err = h.flight.List(ctx, "", "", "flights.date DESC", 0, 0)
+	} else {
+		flights, _, err = h.flight.ListByUserID(ctx, userID, 0, 0)
+	}
+	if err != nil {
+		return nil, 0, 0, err
+	}
+
+	search = strings.ToLower(strings.TrimSpace(search))
+	flightByHelicopter := make(map[string]flight.Flight, len(flights))
+	for i := range flights {
+		if flights[i].Date.Before(from) || flights[i].Date.After(to.Add(24*time.Hour-time.Nanosecond)) {
+			continue
+		}
+		heliKey := idString(flights[i].TakeoverAcID)
+		if heliKey == "" {
+			continue
+		}
+		existing, ok := flightByHelicopter[heliKey]
+		if !ok || flights[i].Date.After(existing.Date) {
+			flightByHelicopter[heliKey] = flights[i]
+		}
+	}
+
+	groups := make([]responsedto.ReserveAcHelicopterGroupResource, 0, len(helicopters))
+	var bookedCount int64
+	for i := range helicopters {
+		heli := helicopters[i]
+		if search != "" {
+			hay := strings.ToLower(strings.TrimSpace(heli.Designation + " " + heli.Identifier + " " + heli.Type))
+			if !strings.Contains(hay, search) {
+				continue
+			}
+		}
+		heliID := idString(heli.ID)
+		flightRow, booked := flightByHelicopter[heliID]
+		if booked {
+			bookedCount++
+		}
+
+		reserveID := ""
+		status := "available"
+		bookedAt := any(nil)
+		var bookedBy map[string]any
+		var bfiFields *beforeflightinspection.BeforeFlightInspection
+		var fpwbFields *flightprepcheck.FlightPrepCheck
+		var reserveRow *reserveac.ReserveAc
+		if booked {
+			status = "booked"
+			reserveID = idString(flightRow.ReserveAcID)
+			if len(flightRow.ReserveAcID) == 16 {
+				if currentReserve, getErr := h.svc.GetByID(ctx, flightRow.ReserveAcID); getErr == nil && currentReserve != nil {
+					reserveRow = currentReserve
+					bookedAt = reserveRow.UpdatedAt.UTC().Format(time.RFC3339)
+					if h.before != nil {
+						bfiFields, _ = h.before.GetByFlightInspectionID(ctx, reserveRow.InspectionID)
+					}
+					if h.prep != nil {
+						fpwbFields, _ = h.prep.GetByFlightInspection(ctx, reserveRow.InspectionID)
+					}
+					if name := h.resolveReserveAcUserName(ctx, reserveRow.UpdatedBy); name != "" {
+						bookedBy = map[string]any{"id": idString(reserveRow.UpdatedBy), "name": name}
+					}
+				}
+			}
+		}
+		if heli.AirOnGround {
+			status = "aog"
+		}
+
+		lastDailyRaw, _ := h.svc.GetLastDailyInspectionByHelicopterID(ctx, heli.ID)
+		lastDaily := responsedto.ReserveAcLastDailyInspectionDTO{
+			ID: nil,
+			InspectionBy: responsedto.ReserveAcInspectionBySummary{
+				ID:        nil,
+				Name:      "",
+				ShortName: "",
+			},
+			InspectionAt: nil,
+		}
+		if lastDailyRaw != nil {
+			lastDaily.ID = nullIfEmpty(idString(flightRow.ReserveAcID))
+			lastDaily.InspectionBy.Name = strings.TrimSpace(lastDailyRaw.Name)
+			lastDaily.InspectionBy.ShortName = strings.TrimSpace(lastDailyRaw.ShortName)
+			lastDaily.InspectionAt = lastDailyRaw.At.UTC().Format(time.RFC3339)
+		} else if reserveRow != nil {
+			// Fallback: if this is the first reserve for this helicopter, expose reserve actor/time as last inspection baseline.
+			lastDaily.ID = nullIfEmpty(idString(reserveRow.ID))
+			lastDaily.InspectionBy.ID = nullIfEmpty(idString(reserveRow.UpdatedBy))
+			if userName := h.resolveReserveAcUserName(ctx, reserveRow.UpdatedBy); userName != "" {
+				lastDaily.InspectionBy.Name = userName
+				lastDaily.InspectionBy.ShortName = shortNameFromFullName(userName)
+			}
+			lastDaily.InspectionAt = reserveRow.UpdatedAt.UTC().Format(time.RFC3339)
+		}
+
+		var bookingDetails *responsedto.ReserveAcBookingDetailsDTO
+		if booked {
+			bookingDetails = &responsedto.ReserveAcBookingDetailsDTO{
+				ReserveAcID: nullIfEmpty(reserveID),
+				FlightID:    nullIfEmpty(idString(flightRow.ID)),
+				MissionCode: nullIfEmpty(ptrStringOrEmpty(flightRow.MissionCode)),
+				DutyDate:    nullIfEmpty(dateStringOrEmpty(flightRow.Date)),
+				BookedAt:    bookedAt,
+				BookedBy:    bookedBy,
+			}
+		}
+
+		bfi := h.buildReserveAcHelicopterFileItems(ctx, heli.ID, helicopterfile.SectionBeforeFirstFlightInspection)
+		fpwb := h.buildReserveAcHelicopterFileItems(ctx, heli.ID, helicopterfile.SectionFlightPreparationAndWB)
+
+		groups = append(groups, responsedto.ReserveAcHelicopterGroupResource{
+			Type: "helicopter_reserve_group",
+			Attributes: responsedto.ReserveAcHelicopterGroupAttributes{
+				Helicopter: responsedto.ReserveAcHelicopterIdentity{
+					ID:             heliID,
+					Designation:    strings.TrimSpace(heli.Designation),
+					Identifier:     strings.TrimSpace(heli.Identifier),
+					Type:           strings.TrimSpace(heli.Type),
+					Status:         status,
+					BookingDetails: bookingDetails,
+				},
+				LastDailyInspection: lastDaily,
+				BFI:                 reserveAcBFISectionDTO(bfiFields, bfi),
+				FPWB:                reserveAcFPWBSectionDTO(fpwbFields, fpwb),
+			},
+		})
+	}
+
+	total := int64(len(groups))
+	paged := groups
+	if limit > 0 {
+		if offset < 0 {
+			offset = 0
+		}
+		if offset >= len(groups) {
+			paged = []responsedto.ReserveAcHelicopterGroupResource{}
+		} else {
+			end := offset + limit
+			if end > len(groups) {
+				end = len(groups)
+			}
+			paged = groups[offset:end]
+		}
+	}
+	return paged, total, bookedCount, nil
+}
+
+func (h *ReserveAcHandler) buildReserveAcHelicopterFileItems(ctx context.Context, helicopterID []byte, section string) []responsedto.ReserveAcHelicopterFileItem {
+	if h.heliFile == nil {
+		return []responsedto.ReserveAcHelicopterFileItem{}
+	}
+	files, err := h.heliFile.ListByHelicopterAndSection(ctx, helicopterID, section)
+	if err != nil {
+		return []responsedto.ReserveAcHelicopterFileItem{}
+	}
+	out := make([]responsedto.ReserveAcHelicopterFileItem, 0, len(files))
+	for i := range files {
+		fileName := ""
+		url := ""
+		if files[i].FileAttachment != nil && files[i].FileAttachment.File != nil {
+			fileName = strings.TrimSpace(files[i].FileAttachment.File.Name)
+			url = resolveFileManagerDownloadURL(ctx, h.storage, files[i].FileAttachment.File)
+		}
+		out = append(out, responsedto.ReserveAcHelicopterFileItem{
+			ID:         idString(files[i].ID),
+			FileName:   fileName,
+			URL:        url,
+			UploadedAt: files[i].UpdatedAt.UTC().Format(time.RFC3339),
+			UploadedBy: idString(files[i].UpdatedBy),
+		})
+	}
+	return out
+}
+
+func (h *ReserveAcHandler) resolveReserveAcUserName(ctx context.Context, userID []byte) string {
+	if h.auth == nil || len(userID) != 16 {
+		return ""
+	}
+	u, err := h.auth.GetUserByID(ctx, userID)
+	if err != nil || u == nil {
+		return ""
+	}
+	return strings.TrimSpace(strings.TrimSpace(u.FirstName) + " " + strings.TrimSpace(u.LastName))
+}
+
+func nullIfEmpty(v string) any {
+	if strings.TrimSpace(v) == "" {
+		return nil
+	}
+	return v
+}
+
+func ptrStringOrEmpty(v *string) string {
+	if v == nil {
+		return ""
+	}
+	return strings.TrimSpace(*v)
+}
+
+func dateStringOrEmpty(v time.Time) string {
+	if v.IsZero() {
+		return ""
+	}
+	return v.UTC().Format("2006-01-02")
+}
+
+func shortNameFromFullName(fullName string) string {
+	parts := strings.Fields(strings.TrimSpace(fullName))
+	if len(parts) == 0 {
+		return ""
+	}
+	if len(parts) == 1 {
+		r := []rune(parts[0])
+		if len(r) == 0 {
+			return ""
+		}
+		return strings.ToUpper(string(r[0]))
+	}
+	first := []rune(parts[0])
+	last := []rune(parts[len(parts)-1])
+	if len(first) == 0 || len(last) == 0 {
+		return ""
+	}
+	return strings.ToUpper(string(first[0]) + string(last[0]))
+}
+
+func reserveAcBFISectionDTO(v *beforeflightinspection.BeforeFlightInspection, files []responsedto.ReserveAcHelicopterFileItem) responsedto.ReserveAcBFISection {
+	out := responsedto.ReserveAcBFISection{Files: files}
+	if v == nil {
+		return out
+	}
+	out.FuelAddedAmount = v.FuelAddedAmount
+	out.FuelAmount = v.FuelAmount
+	out.FuelUnit = strings.TrimSpace(v.FuelUnit)
+	out.HydraulicLHChecked = v.HydraulicLHChecked
+	out.HydraulicRHChecked = v.HydraulicRHChecked
+	out.OilEngineNR1Checked = v.OilEngineNR1Checked
+	out.OilEngineNR2Checked = v.OilEngineNR2Checked
+	out.OilTransmissionIGBChecked = v.OilTransmissionIGBChecked
+	out.OilTransmissionMGBChecked = v.OilTransmissionMGBChecked
+	out.OilTransmissionTGBChecked = v.OilTransmissionTGBChecked
+	return out
+}
+
+func reserveAcFPWBSectionDTO(v *flightprepcheck.FlightPrepCheck, files []responsedto.ReserveAcHelicopterFileItem) responsedto.ReserveAcFPWBSection {
+	out := responsedto.ReserveAcFPWBSection{Files: files}
+	if v == nil {
+		return out
+	}
+	out.NotamBriefing = boolPtr(v.NOTAMBriefing)
+	out.WeatherBriefing = boolPtr(v.WeatherBriefing)
+	out.OperationalFlightPlan = boolPtr(v.OperationalFlightPlan)
+	return out
+}
+
+func (h *ReserveAcHandler) isReserveAcAdmin(ctx context.Context, userID []byte) bool {
+	if h.auth == nil || len(userID) != 16 {
+		return false
+	}
+	user, err := h.auth.GetUserByID(ctx, userID)
+	if err != nil || user == nil {
+		return false
+	}
+	roleIDs := make([][]byte, 0, 1+len(user.RoleIDs))
+	if len(user.RoleID) == 16 {
+		roleIDs = append(roleIDs, user.RoleID)
+	}
+	roleIDs = append(roleIDs, user.RoleIDs...)
+	seen := make(map[string]struct{}, len(roleIDs))
+	for i := range roleIDs {
+		if len(roleIDs[i]) != 16 {
+			continue
+		}
+		key := idString(roleIDs[i])
+		if key == "" {
+			continue
+		}
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		role, err := h.auth.GetRoleByID(ctx, roleIDs[i])
+		if err != nil || role == nil {
+			continue
+		}
+		code := strings.ToLower(strings.TrimSpace(role.Code))
+		name := strings.ToLower(strings.TrimSpace(role.Name))
+		if code == "admin" || name == "admin" {
+			return true
+		}
+	}
+	return false
+}
+
+type reserveAcListItem struct {
+	row         reserveac.ReserveAc
+	flightID    []byte
+	placeholder bool
+}
+
+func (h *ReserveAcHandler) listReserveAcByAuthUser(ctx context.Context, userID []byte, filter, sortParam string, limit, offset int, idFilterKey, flightIDFilterKey string) ([]reserveAcListItem, int64, error) {
+	if h.flight == nil || len(userID) != 16 {
+		return []reserveAcListItem{}, 0, nil
+	}
+	flights, _, err := h.flight.ListByUserID(ctx, userID, 100, 0)
+	if err != nil {
+		return nil, 0, err
+	}
+	items := h.buildReserveAcListItemsFromFlights(ctx, flights)
+	items = filterReserveAcListItemsByExact(items, idFilterKey, flightIDFilterKey)
+	items = filterReserveAcListItemsBySearch(items, filter)
+	sortReserveAcListItems(items, sortParam)
+	total := int64(len(items))
+	return paginateReserveAcListItems(items, limit, offset), total, nil
+}
+
+func (h *ReserveAcHandler) collectReserveAcRowsByScope(
+	ctx context.Context,
+	userID []byte,
+	isAdmin bool,
+	filter string,
+	sortParam string,
+	limit int,
+	offset int,
+	idFilter []byte,
+	idFilterKey string,
+	flightIDFilter []byte,
+	flightIDFilterKey string,
+) ([]reserveAcListItem, int64, error) {
+	_ = idFilter
+	_ = flightIDFilter
+	if isAdmin {
+		if h.flight == nil {
+			return []reserveAcListItem{}, 0, nil
+		}
+		flights, _, err := h.flight.List(ctx, "", "", "flights.date DESC", 0, 0)
+		if err != nil {
+			return nil, 0, err
+		}
+		items := h.buildReserveAcListItemsFromFlights(ctx, flights)
+		items = filterReserveAcListItemsByExact(items, idFilterKey, flightIDFilterKey)
+		items = filterReserveAcListItemsBySearch(items, filter)
+		sortReserveAcListItems(items, sortParam)
+		total := int64(len(items))
+		return paginateReserveAcListItems(items, limit, offset), total, nil
+	}
+	return h.listReserveAcByAuthUser(ctx, userID, filter, sortParam, limit, offset, idFilterKey, flightIDFilterKey)
+}
+
+func (h *ReserveAcHandler) buildReserveAcListItemsFromFlights(ctx context.Context, flights []flight.Flight) []reserveAcListItem {
+	items := make([]reserveAcListItem, 0, len(flights))
+	seenReserve := make(map[string]struct{}, len(flights))
+	for i := range flights {
+		flightID := append([]byte(nil), flights[i].ID...)
+		if len(flights[i].ReserveAcID) == 16 {
+			key := idString(flights[i].ReserveAcID)
+			if key != "" {
+				if _, ok := seenReserve[key]; ok {
+					continue
+				}
+				seenReserve[key] = struct{}{}
+				if row, err := h.svc.GetByID(ctx, flights[i].ReserveAcID); err == nil && row != nil {
+					items = append(items, reserveAcListItem{row: *row, flightID: flightID})
+					continue
+				}
+			}
+		}
+		items = append(items, reserveAcListItem{
+			row: reserveac.ReserveAc{
+				Status:     reserveac.StatusPending,
+				AircraftID: append([]byte(nil), flights[i].ReserveAcID...),
+			},
+			flightID:    flightID,
+			placeholder: true,
+		})
+	}
+	return items
+}
+
+func filterReserveAcListItemsByExact(items []reserveAcListItem, reserveIDFilterKey, flightIDFilterKey string) []reserveAcListItem {
+	if reserveIDFilterKey == "" && flightIDFilterKey == "" {
+		return items
+	}
+	out := make([]reserveAcListItem, 0, len(items))
+	for i := range items {
+		if reserveIDFilterKey != "" && idString(items[i].row.ID) != reserveIDFilterKey {
+			continue
+		}
+		if flightIDFilterKey != "" && idString(items[i].flightID) != flightIDFilterKey {
+			continue
+		}
+		out = append(out, items[i])
+	}
+	return out
+}
+
+func filterReserveAcListItemsBySearch(items []reserveAcListItem, filter string) []reserveAcListItem {
+	filter = strings.ToLower(strings.TrimSpace(filter))
+	if filter == "" {
+		return items
+	}
+	out := make([]reserveAcListItem, 0, len(items))
+	for i := range items {
+		if reserveAcMatchFilter(items[i].row, idString(items[i].flightID), filter) {
+			out = append(out, items[i])
+		}
+	}
+	return out
+}
+
+func paginateReserveAcListItems(items []reserveAcListItem, limit, offset int) []reserveAcListItem {
+	if limit <= 0 {
+		return items
+	}
+	if offset < 0 {
+		offset = 0
+	}
+	if offset >= len(items) {
+		return []reserveAcListItem{}
+	}
+	end := offset + limit
+	if end > len(items) {
+		end = len(items)
+	}
+	return items[offset:end]
+}
+
+func sortReserveAcListItems(items []reserveAcListItem, sortParam string) {
+	field := strings.TrimSpace(sortParam)
+	desc := false
+	if strings.HasPrefix(field, "-") {
+		desc = true
+		field = strings.TrimPrefix(field, "-")
+	}
+	switch field {
+	case "status", "created_at", "updated_at":
+	default:
+		field = "created_at"
+		desc = true
+	}
+	sort.SliceStable(items, func(i, j int) bool {
+		left := items[i].row
+		right := items[j].row
+		cmp := 0
+		switch field {
+		case "status":
+			ls := strings.ToLower(strings.TrimSpace(left.Status))
+			rs := strings.ToLower(strings.TrimSpace(right.Status))
+			switch {
+			case ls < rs:
+				cmp = -1
+			case ls > rs:
+				cmp = 1
+			default:
+				cmp = bytes.Compare(items[i].flightID, items[j].flightID)
+			}
+		case "updated_at":
+			switch {
+			case left.UpdatedAt.Before(right.UpdatedAt):
+				cmp = -1
+			case left.UpdatedAt.After(right.UpdatedAt):
+				cmp = 1
+			default:
+				cmp = bytes.Compare(items[i].flightID, items[j].flightID)
+			}
+		default:
+			switch {
+			case left.CreatedAt.Before(right.CreatedAt):
+				cmp = -1
+			case left.CreatedAt.After(right.CreatedAt):
+				cmp = 1
+			default:
+				cmp = bytes.Compare(items[i].flightID, items[j].flightID)
+			}
+		}
+		if cmp == 0 {
+			return false
+		}
+		if desc {
+			return cmp > 0
+		}
+		return cmp < 0
+	})
+}
+
+func parseOptionalReserveAcUUIDFilter(raw, sourcePointer string) ([]byte, string, *jsonapi.ErrorObject) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return nil, "", nil
+	}
+	id, err := uuidv7.ParseString(raw)
+	if err != nil {
+		return nil, "", &jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: sourcePointer},
+		}
+	}
+	return id, idString(id), nil
+}
+
+func reserveAcMatchFilter(row reserveac.ReserveAc, flightID, filter string) bool {
+	if filter == "" {
+		return true
+	}
+	haystacks := []string{
+		strings.ToLower(strings.TrimSpace(row.Status)),
+		strings.ToLower(strings.TrimSpace(idString(row.ID))),
+		strings.ToLower(strings.TrimSpace(idString(row.AircraftID))),
+		strings.ToLower(strings.TrimSpace(idString(row.InspectionID))),
+		strings.ToLower(strings.TrimSpace(flightID)),
+	}
+	for i := range haystacks {
+		if strings.Contains(haystacks[i], filter) {
+			return true
+		}
+	}
+	return false
+}
+
+func sortReserveAcRows(rows []reserveac.ReserveAc, sortParam string) {
+	field := strings.TrimSpace(sortParam)
+	desc := false
+	if strings.HasPrefix(field, "-") {
+		desc = true
+		field = strings.TrimPrefix(field, "-")
+	}
+	switch field {
+	case "status", "created_at", "updated_at":
+	default:
+		field = "created_at"
+		desc = true
+	}
+	sort.SliceStable(rows, func(i, j int) bool {
+		left := rows[i]
+		right := rows[j]
+		cmp := 0
+		switch field {
+		case "status":
+			ls := strings.ToLower(strings.TrimSpace(left.Status))
+			rs := strings.ToLower(strings.TrimSpace(right.Status))
+			switch {
+			case ls < rs:
+				cmp = -1
+			case ls > rs:
+				cmp = 1
+			default:
+				switch {
+				case left.CreatedAt.Before(right.CreatedAt):
+					cmp = -1
+				case left.CreatedAt.After(right.CreatedAt):
+					cmp = 1
+				default:
+					cmp = 0
+				}
+			}
+		case "updated_at":
+			switch {
+			case left.UpdatedAt.Before(right.UpdatedAt):
+				cmp = -1
+			case left.UpdatedAt.After(right.UpdatedAt):
+				cmp = 1
+			default:
+				cmp = 0
+			}
+		default:
+			switch {
+			case left.CreatedAt.Before(right.CreatedAt):
+				cmp = -1
+			case left.CreatedAt.After(right.CreatedAt):
+				cmp = 1
+			default:
+				cmp = 0
+			}
+		}
+		if cmp == 0 {
+			return false
+		}
+		if desc {
+			return cmp > 0
+		}
+		return cmp < 0
+	})
+}
+
+type reserveAcResourceOptions struct {
+	flightID   []byte
+	inspection *shareddto.ReserveAcInspectionSummary
+	aircraft   *shareddto.ReserveAcAircraftSummary
+	lastDaily  *shareddto.ReserveAcLastDailyInfo
+}
+
+func reserveAcResource(row *reserveac.ReserveAc, opts reserveAcResourceOptions) responsedto.ReserveAcResource {
+	return responsedto.ReserveAcResource{
+		Type: "reserve_ac",
+		ID:   idString(row.ID),
+		Attributes: shareddto.ReserveAcAttributes{
+			Status:     row.Status,
+			AircraftID: idString(row.AircraftID),
+			Aircraft:   opts.aircraft,
+			LastDaily:  opts.lastDaily,
+			FlightID:   idString(opts.flightID),
+			Inspection: opts.inspection,
+			CreatedAt:  row.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy:  uuidStringOrEmpty(row.CreatedBy),
+			UpdatedAt:  row.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy:  uuidStringOrEmpty(row.UpdatedBy),
+			DeletedAt:  timeStringOrEmpty(row.DeletedAt),
+			DeletedBy:  uuidStringOrEmpty(row.DeletedBy),
+		},
+	}
+}
+
+func reserveAcLastDailyInfo(v *shareddto.LastDailyInspection) *shareddto.ReserveAcLastDailyInfo {
+	if v == nil {
+		return &shareddto.ReserveAcLastDailyInfo{
+			Name:      "",
+			ShortName: "",
+			Date:      "",
+			UTCTime:   "",
+		}
+	}
+	t := v.At.UTC()
+	return &shareddto.ReserveAcLastDailyInfo{
+		Name:      strings.TrimSpace(v.Name),
+		ShortName: strings.TrimSpace(v.ShortName),
+		Date:      t.Format("02.01.2006"),
+		UTCTime:   t.Format("15:04"),
+	}
+}
+
+func hasReserveAcBeforePayload(v requestdto.ReserveAcBeforeInspectionAttributes) bool {
+	if v.OilEngineNR1Checked != nil || v.OilEngineNR2Checked != nil || v.HydraulicLHChecked != nil || v.HydraulicRHChecked != nil {
+		return true
+	}
+	if v.OilTransmissionMGBChecked != nil || v.OilTransmissionIGBChecked != nil || v.OilTransmissionTGBChecked != nil {
+		return true
+	}
+	if v.FuelAmount != nil || v.FuelUnit != nil || v.FuelAddedAmount != nil || v.Note != nil {
+		return true
+	}
+	return false
+}
+
+func hasReserveAcPreparePayload(v requestdto.ReserveAcPrepareInspectionAttributes) bool {
+	return v.NotamBriefing != nil || v.WeatherBriefing != nil || v.OperationalFlightPlan != nil
+}
+
+func reserveAcUpdateFlightInput(attrs requestdto.ReserveAcUpdateAttributes) (string, string, bool) {
+	if attrs.FlightID != nil {
+		return strings.TrimSpace(*attrs.FlightID), "/data/attributes/flight_id", true
+	}
+	return "", "", false
+}
+
+func boolPtr(v bool) *bool { return &v }
+
+func (h *ReserveAcHandler) buildCreateInspectionSummary(c *fiber.Ctx, inspectionID []byte, helicopterID []byte) (*shareddto.ReserveAcInspectionSummary, error) {
+	inspection, err := h.inspect.GetByID(c.UserContext(), inspectionID)
+	if err != nil || inspection == nil {
+		return nil, err
+	}
+	ckRows, err := h.fileCk.ListByInspectionID(c.UserContext(), inspectionID)
+	if err != nil {
+		return nil, err
+	}
+
+	isDoneByHeliFileID := make(map[string]bool, len(ckRows))
+	for i := range ckRows {
+		isDoneByHeliFileID[idString(ckRows[i].HelicopterFileID)] = ckRows[i].IsDone
+	}
+
+	beforeRows, err := h.heliFile.ListByHelicopterAndSection(c.UserContext(), helicopterID, helicopterfile.SectionBeforeFirstFlightInspection)
+	if err != nil {
+		return nil, err
+	}
+	prepareRows, err := h.heliFile.ListByHelicopterAndSection(c.UserContext(), helicopterID, helicopterfile.SectionFlightPreparationAndWB)
+	if err != nil {
+		return nil, err
+	}
+	beforeData, _ := h.before.GetByFlightInspectionID(c.UserContext(), inspectionID)
+	prepareData, _ := h.prep.GetByFlightInspection(c.UserContext(), inspectionID)
+
+	beforeSection := h.buildChecklistSectionSummary(c, beforeRows, isDoneByHeliFileID)
+	prepareSection := h.buildChecklistSectionSummary(c, prepareRows, isDoneByHeliFileID)
+	out := &shareddto.ReserveAcInspectionSummary{
+		ID:             idString(inspection.ID),
+		InspectionDate: inspection.InspectionDate.UTC().Format("2006-01-02"),
+		Before: shareddto.ReserveAcBeforeSectionDTO{
+			Total:         beforeSection.Total,
+			Completed:     beforeSection.Completed,
+			DoneFiles:     beforeSection.DoneFiles,
+			FileChecklist: beforeSection.FileChecklist,
+		},
+		Prepare: shareddto.ReserveAcPrepareSectionDTO{
+			Total:         prepareSection.Total,
+			Completed:     prepareSection.Completed,
+			DoneFiles:     prepareSection.DoneFiles,
+			FileChecklist: prepareSection.FileChecklist,
+		},
+	}
+	if beforeData != nil {
+		out.Before.Fields = &shareddto.ReserveAcBeforeInspectionFields{
+			OilEngineNR1Checked:       beforeData.OilEngineNR1Checked,
+			OilEngineNR2Checked:       beforeData.OilEngineNR2Checked,
+			HydraulicLHChecked:        beforeData.HydraulicLHChecked,
+			HydraulicRHChecked:        beforeData.HydraulicRHChecked,
+			OilTransmissionMGBChecked: beforeData.OilTransmissionMGBChecked,
+			OilTransmissionIGBChecked: beforeData.OilTransmissionIGBChecked,
+			OilTransmissionTGBChecked: beforeData.OilTransmissionTGBChecked,
+			FuelAmount:                beforeData.FuelAmount,
+			FuelUnit:                  strings.TrimSpace(beforeData.FuelUnit),
+			FuelAddedAmount:           beforeData.FuelAddedAmount,
+		}
+	}
+	if prepareData != nil {
+		out.Prepare.PrepareFields = &shareddto.ReserveAcPrepareFields{
+			NotamBriefing:         boolPtr(prepareData.NOTAMBriefing),
+			WeatherBriefing:       boolPtr(prepareData.WeatherBriefing),
+			OperationalFlightPlan: boolPtr(prepareData.OperationalFlightPlan),
+		}
+	}
+	return out, nil
+}
+
+type reserveAcChecklistSectionCommon struct {
+	Total         int
+	Completed     int
+	DoneFiles     []shareddto.ReserveAcFileChecklistItemDTO
+	FileChecklist []shareddto.ReserveAcFileChecklistItemDTO
+}
+
+func (h *ReserveAcHandler) buildChecklistSectionSummary(c *fiber.Ctx, files []helicopterfile.HelicopterFile, isDoneByHeliFileID map[string]bool) reserveAcChecklistSectionCommon {
+	out := reserveAcChecklistSectionCommon{
+		FileChecklist: make([]shareddto.ReserveAcFileChecklistItemDTO, 0, len(files)),
+		DoneFiles:     make([]shareddto.ReserveAcFileChecklistItemDTO, 0, len(files)),
+	}
+	for i := range files {
+		if reserveAcChecklistFileCreatedFromTemplate(&files[i]) {
+			continue
+		}
+		fileID := idString(files[i].ID)
+		isDone := isDoneByHeliFileID[fileID]
+		if isDone {
+			out.Completed++
+		}
+		out.Total++
+		fileAttachmentID := ""
+		fileName := ""
+		if files[i].FileAttachment != nil {
+			fileAttachmentID = idString(files[i].FileAttachment.ID)
+			if files[i].FileAttachment.File != nil {
+				fileName = strings.TrimSpace(files[i].FileAttachment.File.Name)
+			}
+		}
+		downloadURL := ""
+		if files[i].FileAttachment != nil && files[i].FileAttachment.File != nil {
+			downloadURL = resolveFileManagerDownloadURL(c.UserContext(), h.storage, files[i].FileAttachment.File)
+		}
+		item := shareddto.ReserveAcFileChecklistItemDTO{
+			HelicopterFileID: fileID,
+			FileAttachmentID: fileAttachmentID,
+			FileName:         fileName,
+			DownloadURL:      downloadURL,
+			IsDone:           isDone,
+		}
+		out.FileChecklist = append(out.FileChecklist, item)
+		if item.IsDone {
+			out.DoneFiles = append(out.DoneFiles, item)
+		}
+	}
+	return out
+}
+
+// reserveAcChecklistFileCreatedFromTemplate reports whether a helicopter file row is a
+// document instantiated from a template. Those rows should stay hidden from the
+// checklist summary so only catalog template entries appear in the UI.
+func reserveAcChecklistFileCreatedFromTemplate(row *helicopterfile.HelicopterFile) bool {
+	if row == nil {
+		return false
+	}
+	if row.SourceFile != nil {
+		return len(row.SourceFile.TemplateUUID) == 16
+	}
+	if row.FileAttachment != nil && row.FileAttachment.File != nil {
+		return len(row.FileAttachment.File.TemplateUUID) == 16
+	}
+	return false
+}
+
+func (h *ReserveAcHandler) buildInspectionChecklistSection(c *fiber.Ctx, inspectionID []byte, helicopterID []byte, section string) (reserveAcChecklistSectionCommon, error) {
+	ckRows, err := h.fileCk.ListByInspectionID(c.UserContext(), inspectionID)
+	if err != nil {
+		return reserveAcChecklistSectionCommon{}, err
+	}
+	isDoneByHeliFileID := make(map[string]bool, len(ckRows))
+	for i := range ckRows {
+		isDoneByHeliFileID[idString(ckRows[i].HelicopterFileID)] = ckRows[i].IsDone
+	}
+
+	templateFiles, err := h.heliFile.ListByHelicopterAndSection(c.UserContext(), helicopterID, section)
+	if err != nil {
+		return reserveAcChecklistSectionCommon{}, err
+	}
+	return h.buildChecklistSectionSummary(c, templateFiles, isDoneByHeliFileID), nil
+}
+
+type afterFlightInspectionSummary struct {
+	MissionCode       string
+	MissionType       []string
+	TotalFlight       int
+	FlightDataCount   int
+	FlightTimeSeconds int64
+	Route             []string
+}
+
+func afterFlightInspectionPayload(
+	inspectionID []byte,
+	inspectionRow *flightinspection.FlightInspection,
+	helicopterRow *responsedto.HelicopterResource,
+	row *afterflightinspection.AfterFlightInspection,
+	section reserveAcChecklistSectionCommon,
+	summary *afterFlightInspectionSummary,
+) rootdto.AfterFlightInspectionResponse {
+	inspectionIDStr := idString(inspectionID)
+	payload := rootdto.AfterFlightInspectionResponse{
+		Data: rootdto.AfterFlightInspectionResource{
+			Type: "after_flight_inspection",
+			Attributes: rootdto.AfterFlightInspectionAttributes{
+				FlightInspectionID: inspectionIDStr,
+				Total:              section.Total,
+				Completed:          section.Completed,
+				DoneFileChecklist:  toAfterFlightChecklistItems(section.DoneFiles),
+				FileChecklist:      toAfterFlightChecklistItems(section.FileChecklist),
+				Helicopter:         helicopterRow,
+				MissionType:        []string{},
+				Route:              []string{},
+			},
+		},
+	}
+	if inspectionRow != nil {
+		payload.Data.Attributes.FlightInspection = afterFlightInspectionResource(inspectionRow)
+	}
+	if summary != nil {
+		payload.Data.Attributes.MissionCode = summary.MissionCode
+		payload.Data.Attributes.MissionType = append([]string(nil), summary.MissionType...)
+		payload.Data.Attributes.TotalFlight = summary.TotalFlight
+		payload.Data.Attributes.FlightDataCount = summary.FlightDataCount
+		payload.Data.Attributes.FlightTimeSeconds = summary.FlightTimeSeconds
+		payload.Data.Attributes.Route = append([]string(nil), summary.Route...)
+	}
+	if row == nil {
+		return payload
+	}
+
+	rowID := idString(row.ID)
+	payload.Data.ID = rowID
+	payload.Data.Attributes.ID = rowID
+	payload.Data.Attributes.OilEngineNR1Checked = row.OilEngineNR1Checked
+	payload.Data.Attributes.OilEngineNR2Checked = row.OilEngineNR2Checked
+	payload.Data.Attributes.HydraulicLHChecked = row.HydraulicLHChecked
+	payload.Data.Attributes.HydraulicRHChecked = row.HydraulicRHChecked
+	payload.Data.Attributes.OilTransmissionMGBChecked = row.OilTransmissionMGBChecked
+	payload.Data.Attributes.OilTransmissionIGBChecked = row.OilTransmissionIGBChecked
+	payload.Data.Attributes.OilTransmissionTGBChecked = row.OilTransmissionTGBChecked
+	payload.Data.Attributes.Note = row.Note
+	payload.Data.Attributes.CreatedAt = row.CreatedAt.UTC().Format(time.RFC3339)
+	payload.Data.Attributes.UpdatedAt = row.UpdatedAt.UTC().Format(time.RFC3339)
+
+	return payload
+}
+
+func (h *ReserveAcHandler) afterFlightInspectionHelicopterResource(ctx context.Context, reserveAcRow *reserveac.ReserveAc) *responsedto.HelicopterResource {
+	if h == nil || reserveAcRow == nil || len(reserveAcRow.AircraftID) != 16 {
+		return nil
+	}
+
+	helicopterRow := reserveAcRow.Aircraft
+	if h.aircraft != nil {
+		if fullRow, err := h.aircraft.GetByID(ctx, reserveAcRow.AircraftID); err == nil && fullRow != nil {
+			helicopterRow = fullRow
+		}
+	}
+	if helicopterRow == nil {
+		return nil
+	}
+
+	isInUse := false
+	if h.aircraft != nil {
+		if inUse, err := h.aircraft.IsInUse(ctx, reserveAcRow.AircraftID); err == nil {
+			isInUse = inUse
+		}
+	}
+
+	var reserveAcProvider helicopterLastDailyInspectionProvider
+	if provider, ok := h.svc.(helicopterLastDailyInspectionProvider); ok {
+		reserveAcProvider = provider
+	}
+	res := helicopterResourceWithStorage(ctx, h.storage, reserveAcProvider, helicopterRow, isInUse)
+	return &res
+}
+
+func (h *ReserveAcHandler) buildAfterFlightInspectionSummary(ctx context.Context, reserveAcRow *reserveac.ReserveAc) *afterFlightInspectionSummary {
+	summary := &afterFlightInspectionSummary{}
+	if h == nil || h.flight == nil || reserveAcRow == nil || len(reserveAcRow.ID) != 16 {
+		return summary
+	}
+
+	flights, err := h.flight.ListByReserveAcID(ctx, reserveAcRow.ID)
+	if err != nil || len(flights) == 0 {
+		return summary
+	}
+
+	if h.mission == nil {
+		return summary
+	}
+
+	missionTypeSeen := make(map[string]struct{})
+	route := make([]string, 0)
+	for f := range flights {
+		if len(flights[f].ID) != 16 {
+			continue
+		}
+		if summary.MissionCode == "" {
+			summary.MissionCode = strings.TrimSpace(stringPtrOrEmpty(flights[f].MissionCode))
+		}
+
+		missions, missErr := h.mission.ListByFlightID(ctx, flights[f].ID)
+		if missErr != nil {
+			continue
+		}
+
+		for i := range missions {
+			missionType := strings.ToUpper(strings.TrimSpace(missions[i].Type))
+			if missionType != "" {
+				if _, ok := missionTypeSeen[missionType]; !ok {
+					missionTypeSeen[missionType] = struct{}{}
+					summary.MissionType = append(summary.MissionType, missionType)
+				}
+			}
+			if h.flightData == nil || len(missions[i].ID) != 16 {
+				continue
+			}
+			fds, fdErr := h.flightData.ListByMissionID(ctx, missions[i].ID)
+			if fdErr != nil {
+				continue
+			}
+			summary.TotalFlight += len(fds)
+			for j := range fds {
+				summary.FlightDataCount++
+				summary.FlightTimeSeconds += flightDataFlightTimeSeconds(&fds[j])
+
+				fromLabel := flightDataLocationLabel(fromLocationRefFlightData(&fds[j]))
+				if fromLabel != "" {
+					route = appendRoutePoint(route, fromLabel)
+				}
+				toLabel := flightDataLocationLabel(toLocationRefFlightData(&fds[j]))
+				if toLabel != "" {
+					route = appendRoutePoint(route, toLabel)
+				}
+			}
+		}
+	}
+	summary.Route = route
+	return summary
+}
+
+func (h *ReserveAcHandler) loadMissionFlightData(ctx context.Context, row mission.Mission) (*flightdata.FlightData, bool) {
+	hasFlightData := len(row.FlightDataID) == 16
+	if h == nil || h.flightData == nil {
+		return nil, hasFlightData
+	}
+
+	if len(row.ID) == 16 {
+		if fd, err := h.flightData.GetByMissionID(ctx, row.ID); err == nil && fd != nil {
+			return fd, true
+		}
+	}
+	if len(row.FlightDataID) == 16 {
+		if fd, err := h.flightData.GetByID(ctx, row.FlightDataID); err == nil && fd != nil {
+			return fd, true
+		}
+	}
+	return nil, hasFlightData
+}
+
+func appendRoutePoint(route []string, point string) []string {
+	point = strings.TrimSpace(point)
+	if point == "" {
+		return route
+	}
+	if len(route) == 0 || route[len(route)-1] != point {
+		return append(route, point)
+	}
+	return route
+}
+
+func flightDataLocationLabel(ref *responsedto.FlightDataLocationRef) string {
+	if ref == nil {
+		return ""
+	}
+	for _, candidate := range []string{ref.Label, ref.Code, ref.Name, ref.ID} {
+		if trimmed := strings.TrimSpace(candidate); trimmed != "" {
+			return trimmed
+		}
+	}
+	return ""
+}
+
+func flightDataFlightTimeSeconds(row *flightdata.FlightData) int64 {
+	if row == nil {
+		return 0
+	}
+	if !row.FlightTakeOff.IsZero() && !row.FlightLanding.IsZero() && row.FlightLanding.After(row.FlightTakeOff) {
+		return int64(row.FlightLanding.Sub(row.FlightTakeOff).Seconds())
+	}
+	if row.FlightDuration > 0 {
+		return int64(row.FlightDuration.Seconds())
+	}
+	return 0
+}
+
+func toAfterFlightChecklistItems(items []shareddto.ReserveAcFileChecklistItemDTO) []rootdto.AfterFlightInspectionFileChecklistItem {
+	if len(items) == 0 {
+		return []rootdto.AfterFlightInspectionFileChecklistItem{}
+	}
+	out := make([]rootdto.AfterFlightInspectionFileChecklistItem, 0, len(items))
+	for i := range items {
+		out = append(out, rootdto.AfterFlightInspectionFileChecklistItem{
+			HelicopterFileID: items[i].HelicopterFileID,
+			FileName:         items[i].FileName,
+			DownloadURL:      items[i].DownloadURL,
+			IsDone:           items[i].IsDone,
+		})
+	}
+	return out
+}
+
+func (h *ReserveAcHandler) calculateReserveAcStatus(summary *shareddto.ReserveAcInspectionSummary) string {
+	if summary == nil {
+		return reserveac.StatusPending
+	}
+
+	totalChecklist := summary.Before.Total + summary.Prepare.Total
+	doneChecklist := summary.Before.Completed + summary.Prepare.Completed
+
+	if totalChecklist > 0 {
+		if doneChecklist == 0 {
+			return reserveac.StatusPending
+		}
+		if doneChecklist < totalChecklist {
+			return reserveac.StatusOnProgress
+		}
+		return reserveac.StatusApproved
+	}
+
+	// Fallback when no checklist templates exist: use inspection field presence as progress signal.
+	if summary.Before.Fields != nil || summary.Prepare.PrepareFields != nil {
+		return reserveac.StatusOnProgress
+	}
+
+	return reserveac.StatusPending
+}
+
+func (h *ReserveAcHandler) buildAircraftSummary(c *fiber.Ctx, aircraftID []byte) (*shareddto.ReserveAcAircraftSummary, error) {
+	if h.aircraft == nil || len(aircraftID) != 16 {
+		return nil, nil
+	}
+	row, err := h.aircraft.GetByID(c.UserContext(), aircraftID)
+	if err != nil || row == nil {
+		return nil, err
+	}
+	return &shareddto.ReserveAcAircraftSummary{
+		ID:          idString(row.ID),
+		Designation: strings.TrimSpace(row.Designation),
+		Identifier:  strings.TrimSpace(row.Identifier),
+		Type:        strings.TrimSpace(row.Type),
+		AOG:         row.AirOnGround,
+		IsActive:    row.IsActive,
+	}, nil
+}
+
+func (h *ReserveAcHandler) upsertInspectionFileChecklistSection(
+	c *fiber.Ctx,
+	inspectionID []byte,
+	helicopterID []byte,
+	section string,
+	payload []requestdto.ReserveAcFileChecklistItem,
+	payloadPointer string,
+	reserveAcID []byte,
+) (bool, error) {
+	templateFiles, err := h.heliFile.ListByHelicopterAndSection(c.UserContext(), helicopterID, section)
+	if err != nil {
+		if len(reserveAcID) == 16 {
+			_ = h.svc.Delete(c.UserContext(), reserveAcID, actorUserID(c))
+		}
+		if err := writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}}); err != nil {
+			return false, err
+		}
+		return false, nil
+	}
+
+	type requestedChecklist struct {
+		fileID []byte
+		isDone bool
+	}
+	requested := make([]requestedChecklist, 0, len(payload))
+	for i := range payload {
+		fileID, parseErr := uuidv7.ParseString(strings.TrimSpace(payload[i].HelicopterFileID))
+		if parseErr != nil {
+			if len(reserveAcID) == 16 {
+				_ = h.svc.Delete(c.UserContext(), reserveAcID, actorUserID(c))
+			}
+			if err := writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "helicopter_file_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: payloadPointer},
+			}}); err != nil {
+				return false, err
+			}
+			return false, nil
+		}
+		requested = append(requested, requestedChecklist{
+			fileID: fileID,
+			isDone: payload[i].IsDone,
+		})
+	}
+	requestedByFileID := make(map[string]bool, len(requested))
+	for i := range requested {
+		requestedByFileID[string(requested[i].fileID)] = requested[i].isDone
+	}
+
+	existingRows, err := h.fileCk.ListByInspectionID(c.UserContext(), inspectionID)
+	if err != nil {
+		if len(reserveAcID) == 16 {
+			_ = h.svc.Delete(c.UserContext(), reserveAcID, actorUserID(c))
+		}
+		if err := writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: "an internal error occurred",
+		}}); err != nil {
+			return false, err
+		}
+		return false, nil
+	}
+	existingByFileID := make(map[string]*flightinspectionfilechecklist.FlightInspectionFileChecklist, len(existingRows))
+	for i := range existingRows {
+		fileID := string(existingRows[i].HelicopterFileID)
+		existingByFileID[fileID] = &existingRows[i]
+	}
+
+	templateSet := make(map[string]struct{}, len(templateFiles))
+	for i := range templateFiles {
+		fileKey := string(templateFiles[i].ID)
+		templateSet[fileKey] = struct{}{}
+
+		current := existingByFileID[fileKey]
+		targetDone, hasOverride := requestedByFileID[fileKey]
+
+		if templateFiles[i].IsMandatory && !targetDone {
+			if len(reserveAcID) == 16 {
+				_ = h.svc.Delete(c.UserContext(), reserveAcID, actorUserID(c))
+			}
+			if err := writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "file_checklist must be fully checked",
+				Source: &jsonapi.ErrorSource{Pointer: payloadPointer},
+			}}); err != nil {
+				return false, err
+			}
+			return false, nil
+		}
+
+		if current == nil {
+			// New row defaults to false unless explicitly provided in payload.
+			if !hasOverride {
+				targetDone = false
+			}
+			newRow := &flightinspectionfilechecklist.FlightInspectionFileChecklist{
+				FlightInspectionID: inspectionID,
+				HelicopterFileID:   templateFiles[i].ID,
+				IsDone:             targetDone,
+				CreatedBy:          actorUserID(c),
+				UpdatedBy:          actorUserID(c),
+			}
+			if err := h.fileCk.Create(c.UserContext(), newRow); err != nil {
+				if len(reserveAcID) == 16 {
+					_ = h.svc.Delete(c.UserContext(), reserveAcID, actorUserID(c))
+				}
+				if err := writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+					Status: "400",
+					Title:  "Create failed",
+					Detail: "an internal error occurred",
+				}}); err != nil {
+					return false, err
+				}
+				return false, nil
+			}
+			continue
+		}
+
+		// Partial update behavior: keep existing value if file is omitted.
+		if !hasOverride {
+			targetDone = current.IsDone
+		}
+
+		if current.IsDone != targetDone {
+			current.IsDone = targetDone
+			current.UpdatedBy = actorUserID(c)
+			if err := h.fileCk.Update(c.UserContext(), current); err != nil {
+				if len(reserveAcID) == 16 {
+					_ = h.svc.Delete(c.UserContext(), reserveAcID, actorUserID(c))
+				}
+				if err := writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+					Status: "400",
+					Title:  "Create failed",
+					Detail: "an internal error occurred",
+				}}); err != nil {
+					return false, err
+				}
+				return false, nil
+			}
+		}
+	}
+
+	for i := range requested {
+		if _, ok := templateSet[string(requested[i].fileID)]; ok {
+			continue
+		}
+		if len(reserveAcID) == 16 {
+			_ = h.svc.Delete(c.UserContext(), reserveAcID, actorUserID(c))
+		}
+		if err := writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "helicopter_file_id does not belong to selected helicopter/section",
+			Source: &jsonapi.ErrorSource{Pointer: payloadPointer},
+		}}); err != nil {
+			return false, err
+		}
+		return false, nil
+	}
+
+	return true, nil
+}
+
+func (h *ReserveAcHandler) validateInspectionChecklistSectionComplete(
+	c *fiber.Ctx,
+	helicopterID []byte,
+	section string,
+	payload []requestdto.ReserveAcFileChecklistItem,
+	payloadPointer string,
+) (bool, error) {
+	if h == nil || h.heliFile == nil {
+		if err := writeReserveAcErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Validation failed",
+			Detail: "helicopter file service is not configured",
+		}}); err != nil {
+			return false, err
+		}
+		return false, nil
+	}
+
+	templateFiles, err := h.heliFile.ListByHelicopterAndSection(c.UserContext(), helicopterID, section)
+	if err != nil {
+		if err := writeReserveAcErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Validation failed",
+			Detail: "an internal error occurred",
+		}}); err != nil {
+			return false, err
+		}
+		return false, nil
+	}
+
+	templateSet := make(map[string]struct{}, len(templateFiles))
+	for i := range templateFiles {
+		templateSet[string(templateFiles[i].ID)] = struct{}{}
+	}
+	payloadByFileID := make(map[string]bool, len(payload))
+	seen := make(map[string]struct{}, len(payload))
+	for i := range payload {
+		fileID, parseErr := uuidv7.ParseString(strings.TrimSpace(payload[i].HelicopterFileID))
+		if parseErr != nil {
+			if err := writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "helicopter_file_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: payloadPointer},
+			}}); err != nil {
+				return false, err
+			}
+			return false, nil
+		}
+		key := string(fileID)
+		if _, ok := templateSet[key]; !ok {
+			if err := writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "helicopter_file_id does not belong to selected helicopter/section",
+				Source: &jsonapi.ErrorSource{Pointer: payloadPointer},
+			}}); err != nil {
+				return false, err
+			}
+			return false, nil
+		}
+		if _, ok := seen[key]; ok {
+			if err := writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "helicopter_file_id is duplicated",
+				Source: &jsonapi.ErrorSource{Pointer: payloadPointer},
+			}}); err != nil {
+				return false, err
+			}
+			return false, nil
+		}
+		seen[key] = struct{}{}
+		payloadByFileID[key] = payload[i].IsDone
+	}
+
+	for i := range templateFiles {
+		fileKey := string(templateFiles[i].ID)
+		done, ok := payloadByFileID[fileKey]
+		if !ok {
+			done = false
+		}
+		if templateFiles[i].IsMandatory && !done {
+			if err := writeReserveAcErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "file_checklist must be fully checked",
+				Source: &jsonapi.ErrorSource{Pointer: payloadPointer},
+			}}); err != nil {
+				return false, err
+			}
+			return false, nil
+		}
+	}
+	return true, nil
+}
+
+func (h *ReserveAcHandler) deleteInspectionFileChecklistSection(
+	c *fiber.Ctx,
+	inspectionID []byte,
+	helicopterID []byte,
+	section string,
+) error {
+	templateFiles, err := h.heliFile.ListByHelicopterAndSection(c.UserContext(), helicopterID, section)
+	if err != nil {
+		return err
+	}
+	templateSet := make(map[string]struct{}, len(templateFiles))
+	for i := range templateFiles {
+		templateSet[string(templateFiles[i].ID)] = struct{}{}
+	}
+
+	existingRows, err := h.fileCk.ListByInspectionID(c.UserContext(), inspectionID)
+	if err != nil {
+		return err
+	}
+	for i := range existingRows {
+		if _, ok := templateSet[string(existingRows[i].HelicopterFileID)]; !ok {
+			continue
+		}
+		if err := h.fileCk.Delete(c.UserContext(), existingRows[i].ID); err != nil {
+			return err
+		}
+	}
+	return nil
+}
diff --git a/internal/transport/http/handlers/reserve_ac_handler_test.go b/internal/transport/http/handlers/reserve_ac_handler_test.go
new file mode 100644
index 0000000..da94273
--- /dev/null
+++ b/internal/transport/http/handlers/reserve_ac_handler_test.go
@@ -0,0 +1,3089 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	afterflightinspection "wucher/internal/domain/after_flight_inspection"
+	beforeflightinspection "wucher/internal/domain/before_flight_inspection"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/flight"
+	flightdata "wucher/internal/domain/flight_data"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	flightinspectionfilechecklist "wucher/internal/domain/flight_inspection_file_checklist"
+	flightprepcheck "wucher/internal/domain/flight_prep_check"
+	"wucher/internal/domain/helicopter"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	hospitaldomain "wucher/internal/domain/hospital"
+	icaodomain "wucher/internal/domain/icao"
+	"wucher/internal/domain/mission"
+	reserveac "wucher/internal/domain/reserve_ac"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+)
+
+type reserveAcServiceMock struct {
+	createFn          func(context.Context, *reserveac.ReserveAc) error
+	updateFn          func(context.Context, *reserveac.ReserveAc) error
+	deleteFn          func(context.Context, []byte, []byte) error
+	listFn            func(context.Context, string, string, int, int) ([]reserveac.ReserveAc, int64, error)
+	getByIDFn         func(context.Context, []byte) (*reserveac.ReserveAc, error)
+	getActiveByInspFn func(context.Context, []byte) (*reserveac.ReserveAc, error)
+	aircraftExistsFn  func(context.Context, []byte) (bool, error)
+}
+
+func (m *reserveAcServiceMock) Create(ctx context.Context, row *reserveac.ReserveAc) error {
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return nil
+}
+func (m *reserveAcServiceMock) Update(ctx context.Context, row *reserveac.ReserveAc) error {
+	if m.updateFn != nil {
+		return m.updateFn(ctx, row)
+	}
+	return nil
+}
+func (m *reserveAcServiceMock) Delete(ctx context.Context, id []byte, deletedBy []byte) error {
+	if m.deleteFn != nil {
+		return m.deleteFn(ctx, id, deletedBy)
+	}
+	return nil
+}
+func (m *reserveAcServiceMock) GetByID(ctx context.Context, id []byte) (*reserveac.ReserveAc, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *reserveAcServiceMock) GetActiveByInspectionID(ctx context.Context, inspectionID []byte) (*reserveac.ReserveAc, error) {
+	if m.getActiveByInspFn != nil {
+		return m.getActiveByInspFn(ctx, inspectionID)
+	}
+	return nil, nil
+}
+func (m *reserveAcServiceMock) List(ctx context.Context, filter string, sort string, limit, offset int) ([]reserveac.ReserveAc, int64, error) {
+	if m.listFn != nil {
+		return m.listFn(ctx, filter, sort, limit, offset)
+	}
+	return nil, 0, nil
+}
+func (m *reserveAcServiceMock) AircraftExists(ctx context.Context, helicopterID []byte) (bool, error) {
+	if m.aircraftExistsFn != nil {
+		return m.aircraftExistsFn(ctx, helicopterID)
+	}
+	return true, nil
+}
+func (m *reserveAcServiceMock) FlightInspectionExists(context.Context, []byte) (bool, error) {
+	return true, nil
+}
+func (m *reserveAcServiceMock) ExistsActiveByInspectionID(context.Context, []byte, []byte) (bool, error) {
+	return false, nil
+}
+func (m *reserveAcServiceMock) GetLastDailyInspectionByHelicopterID(context.Context, []byte) (*shareddto.LastDailyInspection, error) {
+	return nil, nil
+}
+
+type fileStorageMock struct{}
+
+func (fileStorageMock) PresignGetObject(_ context.Context, objectKey string, _ time.Duration) (string, error) {
+	return "https://example.com/" + objectKey, nil
+}
+
+func TestReserveAcHandler_BasicHelpers(t *testing.T) {
+	svc := &reserveAcServiceMock{}
+	h := NewReserveAcHandler(svc)
+	if h == nil || h.validate == nil {
+		t.Fatal("handler not initialized")
+	}
+
+	if got := h.WithFileStorage(fileStorageMock{}); got != h {
+		t.Fatal("expected fluent API to return same handler")
+	}
+
+	if !hasReserveAcBeforePayload(requestdto.ReserveAcBeforeInspectionAttributes{FuelAmount: ptrFloat(1)}) {
+		t.Fatal("expected before payload detected")
+	}
+	if hasReserveAcBeforePayload(requestdto.ReserveAcBeforeInspectionAttributes{}) {
+		t.Fatal("expected empty before payload false")
+	}
+	if !hasReserveAcPreparePayload(requestdto.ReserveAcPrepareInspectionAttributes{NotamBriefing: ptrBool(true)}) {
+		t.Fatal("expected prepare payload detected")
+	}
+	if hasReserveAcPreparePayload(requestdto.ReserveAcPrepareInspectionAttributes{}) {
+		t.Fatal("expected empty prepare payload false")
+	}
+
+	flightID := " abc "
+	gotID, ptr, ok := reserveAcUpdateFlightInput(requestdto.ReserveAcUpdateAttributes{FlightID: &flightID})
+	if !ok || gotID != "abc" || ptr != "/data/attributes/flight_id" {
+		t.Fatalf("unexpected update flight result: %q %q %v", gotID, ptr, ok)
+	}
+	_, _, ok = reserveAcUpdateFlightInput(requestdto.ReserveAcUpdateAttributes{})
+	if ok {
+		t.Fatal("expected no flight update")
+	}
+}
+
+func TestReserveAcHandler_ResourceAndStatusHelpers(t *testing.T) {
+	row := &reserveac.ReserveAc{
+		ID:         uuidv7.MustBytes(),
+		AircraftID: uuidv7.MustBytes(),
+		Status:     reserveac.StatusPending,
+		CreatedAt:  time.Now().UTC(),
+		UpdatedAt:  time.Now().UTC(),
+	}
+	res := reserveAcResource(row, reserveAcResourceOptions{})
+	if res.Type != "reserve_ac" {
+		t.Fatalf("unexpected type %q", res.Type)
+	}
+
+	nilDaily := reserveAcLastDailyInfo(nil)
+	if nilDaily == nil || nilDaily.Name != "" {
+		t.Fatal("unexpected nil last daily conversion")
+	}
+	nonNil := reserveAcLastDailyInfo(&shareddto.LastDailyInspection{Name: " Test ", ShortName: " D ", At: time.Date(2026, 5, 6, 9, 30, 0, 0, time.UTC)})
+	if nonNil.Name != "Test" || nonNil.ShortName != "D" {
+		t.Fatal("unexpected trim result")
+	}
+
+	items := toAfterFlightChecklistItems([]shareddto.ReserveAcFileChecklistItemDTO{{HelicopterFileID: "x", FileName: "f", DownloadURL: "u", IsDone: true}})
+	if len(items) != 1 || !items[0].IsDone {
+		t.Fatal("unexpected checklist map")
+	}
+	empty := toAfterFlightChecklistItems(nil)
+	if len(empty) != 0 {
+		t.Fatal("expected empty array")
+	}
+
+	payload := afterFlightInspectionPayload(uuidv7.MustBytes(), &flightinspection.FlightInspection{ID: uuidv7.MustBytes()}, &responsedto.HelicopterResource{Type: "helicopter", ID: "heli-1"}, &afterflightinspection.AfterFlightInspection{
+		ID:        uuidv7.MustBytes(),
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}, reserveAcChecklistSectionCommon{Total: 1, Completed: 1}, &afterFlightInspectionSummary{MissionCode: "M-123", TotalFlight: 4, FlightDataCount: 2})
+	if payload.Data.Type != "after_flight_inspection" {
+		t.Fatal("unexpected payload type")
+	}
+	if payload.Data.Attributes.MissionCode != "M-123" || payload.Data.Attributes.TotalFlight != 4 || payload.Data.Attributes.FlightDataCount != 2 {
+		t.Fatal("unexpected flight summary payload")
+	}
+	if payload.Data.Attributes.Helicopter == nil || payload.Data.Attributes.Helicopter.ID != "heli-1" {
+		t.Fatal("unexpected helicopter payload")
+	}
+
+	h := NewReserveAcHandler(&reserveAcServiceMock{})
+	if got := h.calculateReserveAcStatus(nil); got != reserveac.StatusPending {
+		t.Fatalf("expected pending, got %s", got)
+	}
+	if got := h.calculateReserveAcStatus(&shareddto.ReserveAcInspectionSummary{
+		Before:  shareddto.ReserveAcBeforeSectionDTO{Total: 2, Completed: 1},
+		Prepare: shareddto.ReserveAcPrepareSectionDTO{Total: 0, Completed: 0},
+	}); got != reserveac.StatusOnProgress {
+		t.Fatalf("expected on_progress, got %s", got)
+	}
+}
+
+func TestReserveAcHandler_BuildAfterFlightInspectionSummaryRoute(t *testing.T) {
+	reserveAcID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	flightDataOneID := uuidv7.MustBytes()
+	flightDataTwoID := uuidv7.MustBytes()
+	missionCode := "M-060326-001"
+
+	h := NewReserveAcHandler(&reserveAcServiceMock{})
+	h.flight = &reserveFlightServiceMock{
+		getByReserveAcFn: func(context.Context, []byte) (*flight.Flight, error) {
+			return &flight.Flight{ID: flightID, MissionCode: &missionCode}, nil
+		},
+	}
+	h.mission = reserveMissionServiceMock{
+		listByFlightIDFn: func(_ context.Context, _ []byte) ([]mission.Mission, error) {
+			return []mission.Mission{
+				{ID: uuidv7.MustBytes(), FlightID: flightID, FlightDataID: flightDataOneID, Type: "HEMS"},
+				{ID: uuidv7.MustBytes(), FlightID: flightID, FlightDataID: flightDataTwoID, Type: "HEMS"},
+			}, nil
+		},
+	}
+	h.flightData = reserveFlightDataServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+			switch string(id) {
+			case string(flightDataOneID):
+				takeoff := time.Date(2026, 6, 8, 8, 0, 0, 0, time.UTC)
+				landing := takeoff.Add(10 * time.Minute)
+				return &flightdata.FlightData{
+					ID:            flightDataOneID,
+					FromHospital:  &hospitaldomain.Hospital{ID: uuidv7.MustBytes(), Name: "A"},
+					ToICAO:        &icaodomain.ICAO{ID: uuidv7.MustBytes(), ICAOCode: "B"},
+					FlightTakeOff: takeoff,
+					FlightLanding: landing,
+				}, nil
+			case string(flightDataTwoID):
+				takeoff := time.Date(2026, 6, 8, 8, 20, 0, 0, time.UTC)
+				landing := takeoff.Add(15 * time.Minute)
+				return &flightdata.FlightData{
+					ID:            flightDataTwoID,
+					FromICAO:      &icaodomain.ICAO{ID: uuidv7.MustBytes(), ICAOCode: "B"},
+					ToHospital:    &hospitaldomain.Hospital{ID: uuidv7.MustBytes(), Name: "C"},
+					FlightTakeOff: takeoff,
+					FlightLanding: landing,
+				}, nil
+			default:
+				return nil, nil
+			}
+		},
+	}
+
+	summary := h.buildAfterFlightInspectionSummary(context.Background(), &reserveac.ReserveAc{ID: reserveAcID})
+	if summary == nil {
+		t.Fatal("expected summary")
+	}
+	if summary.MissionCode != missionCode {
+		t.Fatalf("unexpected mission code: %q", summary.MissionCode)
+	}
+	if summary.FlightDataCount != 2 {
+		t.Fatalf("expected flight data count 2, got %d", summary.FlightDataCount)
+	}
+	if summary.FlightTimeSeconds != int64(25*time.Minute/time.Second) {
+		t.Fatalf("unexpected flight time seconds: got %d", summary.FlightTimeSeconds)
+	}
+	if !reflect.DeepEqual(summary.MissionType, []string{"HEMS"}) {
+		t.Fatalf("unexpected mission types: got %#v", summary.MissionType)
+	}
+	wantRoute := []string{"A", "B", "C"}
+	if !reflect.DeepEqual(summary.Route, wantRoute) {
+		t.Fatalf("unexpected route: got %#v want %#v", summary.Route, wantRoute)
+	}
+
+	payload := afterFlightInspectionPayload(reserveAcID, nil, nil, nil, reserveAcChecklistSectionCommon{}, summary)
+	if !reflect.DeepEqual(payload.Data.Attributes.MissionType, []string{"HEMS"}) {
+		t.Fatalf("unexpected payload mission types: got %#v", payload.Data.Attributes.MissionType)
+	}
+	if payload.Data.Attributes.FlightTimeSeconds != int64(25*time.Minute/time.Second) {
+		t.Fatalf("unexpected payload flight time seconds: got %d", payload.Data.Attributes.FlightTimeSeconds)
+	}
+	if !reflect.DeepEqual(payload.Data.Attributes.Route, wantRoute) {
+		t.Fatalf("unexpected payload route: got %#v want %#v", payload.Data.Attributes.Route, wantRoute)
+	}
+}
+
+func TestReserveAcHandler_DeleteAndListValidation(t *testing.T) {
+	svc := &reserveAcServiceMock{
+		listFn: func(_ context.Context, _, _ string, _, _ int) ([]reserveac.ReserveAc, int64, error) {
+			return []reserveac.ReserveAc{{ID: uuidv7.MustBytes(), AircraftID: uuidv7.MustBytes(), Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}}, 1, nil
+		},
+	}
+	h := NewReserveAcHandler(svc)
+	app := fiber.New()
+	app.Delete("/reserve/:id", h.Delete)
+	app.Get("/reserve", h.List)
+
+	req, _ := http.NewRequest(http.MethodDelete, "/reserve/bad", nil)
+	res, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", res.StatusCode)
+	}
+
+	u := uuidv7.MustNew()
+	id, _ := uuidv7.String(u)
+	req, _ = http.NewRequest(http.MethodDelete, "/reserve/"+id, nil)
+	res, err = app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", res.StatusCode)
+	}
+
+	req, _ = http.NewRequest(http.MethodGet, "/reserve?page[number]=2&page[size]=5&sort=created_at&filter[search]=x", nil)
+	res, err = app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("expected 401, got %d", res.StatusCode)
+	}
+}
+
+func TestReserveAcHandler_ChecklistBuilderHelpers(t *testing.T) {
+	h := NewReserveAcHandler(&reserveAcServiceMock{})
+
+	fileID := uuidv7.MustBytes()
+	attachmentID := uuidv7.MustBytes()
+	files := []helicopterfile.HelicopterFile{{ID: fileID}, {ID: attachmentID}}
+
+	out := h.buildChecklistSectionSummary(&fiber.Ctx{}, files, map[string]bool{idString(fileID): true})
+	if out.Total != 2 || out.Completed != 1 || len(out.DoneFiles) != 1 {
+		t.Fatal("unexpected checklist summary")
+	}
+
+	_ = flightinspectionfilechecklist.FlightInspectionFileChecklist{}
+}
+
+func TestReserveAcHandler_ChecklistBuilderHidesTemplateDerivedFiles(t *testing.T) {
+	h := NewReserveAcHandler(&reserveAcServiceMock{})
+
+	visibleID := uuidv7.MustBytes()
+	derivedID := uuidv7.MustBytes()
+	files := []helicopterfile.HelicopterFile{
+		{ID: visibleID},
+		{
+			ID: derivedID,
+			SourceFile: &filemanager.File{
+				TemplateUUID: uuidv7.MustBytes(),
+			},
+		},
+	}
+
+	out := h.buildChecklistSectionSummary(&fiber.Ctx{}, files, map[string]bool{idString(visibleID): true, idString(derivedID): true})
+	if out.Total != 1 || out.Completed != 1 || len(out.FileChecklist) != 1 || len(out.DoneFiles) != 1 {
+		t.Fatalf("unexpected filtered checklist summary: %#v", out)
+	}
+	if out.FileChecklist[0].HelicopterFileID != idString(visibleID) {
+		t.Fatalf("expected only visible file in checklist, got %#v", out.FileChecklist[0])
+	}
+}
+
+func ptrBool(v bool) *bool        { return &v }
+func ptrFloat(v float64) *float64 { return &v }
+
+type reserveFlightServiceMock struct {
+	getByIDFn        func(context.Context, []byte) (*flight.Flight, error)
+	getByReserveAcFn func(context.Context, []byte) (*flight.Flight, error)
+	updateFn         func(context.Context, *flight.Flight) error
+}
+
+func (m *reserveFlightServiceMock) Create(context.Context, *flight.Flight) error { return nil }
+func (m *reserveFlightServiceMock) Update(ctx context.Context, row *flight.Flight) error {
+	if m.updateFn != nil {
+		return m.updateFn(ctx, row)
+	}
+	return nil
+}
+func (m *reserveFlightServiceMock) Delete(context.Context, []byte, []byte) error { return nil }
+func (m *reserveFlightServiceMock) GetByID(ctx context.Context, id []byte) (*flight.Flight, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *reserveFlightServiceMock) ListByUserID(context.Context, []byte, int, int) ([]flight.Flight, int64, error) {
+	return nil, 0, nil
+}
+func (m *reserveFlightServiceMock) ListByCreatedBy(context.Context, []byte, string, string, string, int, int) ([]flight.Flight, int64, error) {
+	return nil, 0, nil
+}
+func (m *reserveFlightServiceMock) GetByReserveAcID(ctx context.Context, reserveAcID []byte) (*flight.Flight, error) {
+	if m.getByReserveAcFn != nil {
+		return m.getByReserveAcFn(ctx, reserveAcID)
+	}
+	return nil, nil
+}
+func (m *reserveFlightServiceMock) ListByReserveAcID(context.Context, []byte) ([]flight.Flight, error) {
+	return nil, nil
+}
+func (m *reserveFlightServiceMock) GetByTakeoverAcID(context.Context, []byte) (*flight.Flight, error) {
+	return nil, nil
+}
+func (m *reserveFlightServiceMock) ListByTakeoverAcIDs(context.Context, [][]byte) ([]flight.Flight, error) {
+	return nil, nil
+}
+func (m *reserveFlightServiceMock) GetByDutyRosterID(context.Context, []byte) (*flight.Flight, error) {
+	return nil, nil
+}
+func (m *reserveFlightServiceMock) ListByDutyRosterIDs(context.Context, [][]byte) ([]flight.Flight, error) {
+	return nil, nil
+}
+func (m *reserveFlightServiceMock) List(context.Context, string, string, string, int, int) ([]flight.Flight, int64, error) {
+	return nil, 0, nil
+}
+
+type reserveMissionServiceMock struct {
+	listByFlightIDFn  func(context.Context, []byte) ([]mission.Mission, error)
+	listByFlightIDsFn func(context.Context, [][]byte) ([]mission.Mission, error)
+}
+
+func (reserveMissionServiceMock) Create(context.Context, *mission.Mission) error { return nil }
+func (reserveMissionServiceMock) CreateType(context.Context, *mission.MissionCategory) error {
+	return nil
+}
+func (reserveMissionServiceMock) UpdateByID(context.Context, []byte, string, []byte, string, []byte) error {
+	return nil
+}
+func (reserveMissionServiceMock) DeleteByID(context.Context, []byte, []byte) error       { return nil }
+func (reserveMissionServiceMock) DeleteByFlightID(context.Context, []byte, []byte) error { return nil }
+func (reserveMissionServiceMock) AttachFile(context.Context, []byte, []byte) error       { return nil }
+func (reserveMissionServiceMock) DetachFile(context.Context, []byte, []byte) error       { return nil }
+func (m reserveMissionServiceMock) ListByFlightID(ctx context.Context, flightID []byte) ([]mission.Mission, error) {
+	if m.listByFlightIDFn != nil {
+		return m.listByFlightIDFn(ctx, flightID)
+	}
+	return nil, nil
+}
+func (m reserveMissionServiceMock) ListByFlightIDs(ctx context.Context, flightIDs [][]byte) ([]mission.Mission, error) {
+	if m.listByFlightIDsFn != nil {
+		return m.listByFlightIDsFn(ctx, flightIDs)
+	}
+	return nil, nil
+}
+func (reserveMissionServiceMock) GetByID(context.Context, []byte) (*mission.Mission, error) {
+	return nil, nil
+}
+func (reserveMissionServiceMock) GetByFlightID(context.Context, []byte) (*mission.Mission, error) {
+	return nil, nil
+}
+func (reserveMissionServiceMock) List(context.Context, string, string, []byte, string, int, int) ([]mission.Mission, int64, error) {
+	return nil, 0, nil
+}
+func (reserveMissionServiceMock) ListDatatable(context.Context, mission.ListFilter, int, int) ([]mission.Mission, int64, int64, error) {
+	return nil, 0, 0, nil
+}
+func (reserveMissionServiceMock) ListTypes(context.Context) ([]mission.MissionCategory, error) {
+	return nil, nil
+}
+
+type reserveFlightDataServiceMock struct {
+	getByIDFn        func(context.Context, []byte) (*flightdata.FlightData, error)
+	getByMissionIDFn func(context.Context, []byte) (*flightdata.FlightData, error)
+}
+
+func (reserveFlightDataServiceMock) Create(context.Context, *flightdata.FlightData) error {
+	return nil
+}
+func (reserveFlightDataServiceMock) CreatePlaceholder(context.Context, *flightdata.FlightData) error {
+	return nil
+}
+func (reserveFlightDataServiceMock) Update(context.Context, *flightdata.FlightData) error {
+	return nil
+}
+func (reserveFlightDataServiceMock) Delete(context.Context, []byte, []byte) error { return nil }
+func (m reserveFlightDataServiceMock) GetByID(ctx context.Context, id []byte) (*flightdata.FlightData, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+func (reserveFlightDataServiceMock) GetByFlightID(context.Context, []byte) (*flightdata.FlightData, error) {
+	return nil, nil
+}
+func (m reserveFlightDataServiceMock) GetByMissionID(ctx context.Context, id []byte) (*flightdata.FlightData, error) {
+	if m.getByMissionIDFn != nil {
+		return m.getByMissionIDFn(ctx, id)
+	}
+	return nil, nil
+}
+func (reserveFlightDataServiceMock) ListByMissionID(context.Context, []byte) ([]flightdata.FlightData, error) {
+	return nil, nil
+}
+func (reserveFlightDataServiceMock) List(context.Context, string, []byte, []byte, int, int) ([]flightdata.FlightData, int64, error) {
+	return nil, 0, nil
+}
+func (reserveFlightDataServiceMock) GetSPODetailsByFlightDataID(context.Context, []byte) (*flightdata.SPODetails, error) {
+	return nil, nil
+}
+func (reserveFlightDataServiceMock) UpsertSPODetails(context.Context, []byte, *flightdata.SPOUpsertData) error {
+	return nil
+}
+
+type inspectionServiceMock struct {
+	createDraftFn func(context.Context, *flightinspection.FlightInspection) error
+	updateFn      func(context.Context, *flightinspection.FlightInspection) error
+	getByIDFn     func(context.Context, []byte) (*flightinspection.FlightInspection, error)
+}
+
+func (m *inspectionServiceMock) CreateDraft(ctx context.Context, row *flightinspection.FlightInspection) error {
+	if m.createDraftFn != nil {
+		return m.createDraftFn(ctx, row)
+	}
+	row.ID = uuidv7.MustBytes()
+	return nil
+}
+func (m *inspectionServiceMock) Update(ctx context.Context, row *flightinspection.FlightInspection) error {
+	if m.updateFn != nil {
+		return m.updateFn(ctx, row)
+	}
+	return nil
+}
+func (m *inspectionServiceMock) GetByID(ctx context.Context, id []byte) (*flightinspection.FlightInspection, error) {
+	if m.getByIDFn != nil {
+		return m.getByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+func (m *inspectionServiceMock) List(context.Context, string, int, int) ([]flightinspection.FlightInspection, int64, error) {
+	return nil, 0, nil
+}
+
+type beforeServiceMock struct{}
+
+func (beforeServiceMock) Upsert(context.Context, []byte, *beforeflightinspection.UpsertRequest) (*beforeflightinspection.BeforeFlightInspection, error) {
+	return &beforeflightinspection.BeforeFlightInspection{}, nil
+}
+func (beforeServiceMock) GetByFlightInspectionID(context.Context, []byte) (*beforeflightinspection.BeforeFlightInspection, error) {
+	return nil, nil
+}
+
+type beforeServiceFnMock struct {
+	upsertFn func(context.Context, []byte, *beforeflightinspection.UpsertRequest) (*beforeflightinspection.BeforeFlightInspection, error)
+}
+
+func (m beforeServiceFnMock) Upsert(ctx context.Context, id []byte, req *beforeflightinspection.UpsertRequest) (*beforeflightinspection.BeforeFlightInspection, error) {
+	if m.upsertFn != nil {
+		return m.upsertFn(ctx, id, req)
+	}
+	return &beforeflightinspection.BeforeFlightInspection{}, nil
+}
+func (beforeServiceFnMock) GetByFlightInspectionID(context.Context, []byte) (*beforeflightinspection.BeforeFlightInspection, error) {
+	return nil, nil
+}
+
+type prepServiceMock struct{}
+
+func (prepServiceMock) InitializeChecks(context.Context, []byte) (int, error) { return 0, nil }
+func (prepServiceMock) GetByFlightInspection(context.Context, []byte) (*flightprepcheck.FlightPrepCheck, error) {
+	return nil, nil
+}
+func (prepServiceMock) UpdateCheck(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+	return nil, nil
+}
+func (prepServiceMock) UpsertByFlightInspection(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+	return &flightprepcheck.FlightPrepCheck{}, nil
+}
+
+type prepServiceFnMock struct {
+	initFn   func(context.Context, []byte) (int, error)
+	upsertFn func(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error)
+}
+
+func (m prepServiceFnMock) InitializeChecks(ctx context.Context, id []byte) (int, error) {
+	if m.initFn != nil {
+		return m.initFn(ctx, id)
+	}
+	return 0, nil
+}
+func (prepServiceFnMock) GetByFlightInspection(context.Context, []byte) (*flightprepcheck.FlightPrepCheck, error) {
+	return nil, nil
+}
+func (prepServiceFnMock) UpdateCheck(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+	return nil, nil
+}
+func (m prepServiceFnMock) UpsertByFlightInspection(ctx context.Context, id []byte, req *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+	if m.upsertFn != nil {
+		return m.upsertFn(ctx, id, req)
+	}
+	return &flightprepcheck.FlightPrepCheck{}, nil
+}
+
+type afterServiceMock struct {
+	getFn    func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error)
+	upsertFn func(context.Context, []byte, *afterflightinspection.UpsertRequest) (*afterflightinspection.AfterFlightInspection, error)
+	delFn    func(context.Context, []byte) error
+}
+
+func (m *afterServiceMock) Upsert(ctx context.Context, id []byte, req *afterflightinspection.UpsertRequest) (*afterflightinspection.AfterFlightInspection, error) {
+	if m.upsertFn != nil {
+		return m.upsertFn(ctx, id, req)
+	}
+	return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+}
+func (m *afterServiceMock) GetByFlightInspectionID(ctx context.Context, id []byte) (*afterflightinspection.AfterFlightInspection, error) {
+	if m.getFn != nil {
+		return m.getFn(ctx, id)
+	}
+	return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+}
+func (m *afterServiceMock) DeleteByFlightInspectionID(ctx context.Context, id []byte) error {
+	if m.delFn != nil {
+		return m.delFn(ctx, id)
+	}
+	return nil
+}
+
+type heliFileServiceMock struct {
+	listBySectionFn func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error)
+}
+
+func (heliFileServiceMock) Create(context.Context, *helicopterfile.HelicopterFile) error { return nil }
+func (heliFileServiceMock) Update(context.Context, *helicopterfile.HelicopterFile) error { return nil }
+func (heliFileServiceMock) Delete(context.Context, []byte) error                         { return nil }
+func (heliFileServiceMock) GetByID(context.Context, []byte) (*helicopterfile.HelicopterFile, error) {
+	return nil, nil
+}
+func (heliFileServiceMock) List(context.Context, string, string, int, int) ([]helicopterfile.HelicopterFile, int64, error) {
+	return nil, 0, nil
+}
+func (heliFileServiceMock) ListByHelicopter(context.Context, []byte) ([]helicopterfile.HelicopterFile, error) {
+	return nil, nil
+}
+func (m heliFileServiceMock) ListByHelicopterAndSection(ctx context.Context, id []byte, section string) ([]helicopterfile.HelicopterFile, error) {
+	if m.listBySectionFn != nil {
+		return m.listBySectionFn(ctx, id, section)
+	}
+	return nil, nil
+}
+func (heliFileServiceMock) HelicopterExists(context.Context, []byte) (bool, error) { return true, nil }
+func (heliFileServiceMock) AttachmentExists(context.Context, []byte) (bool, error) { return true, nil }
+func (heliFileServiceMock) RequestUploadIntentsBulk(context.Context, []helicopterfile.UploadIntentBulkInput, []byte) []helicopterfile.UploadIntentBulkItemResult {
+	return nil
+}
+func (heliFileServiceMock) CreateFromUploadIntentsBulk(context.Context, []helicopterfile.CreateBulkInput, []byte) []helicopterfile.CreateBulkItemResult {
+	return nil
+}
+
+type fileChecklistServiceMock struct {
+	listByInspectionFn func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error)
+	createFn           func(context.Context, *flightinspectionfilechecklist.FlightInspectionFileChecklist) error
+	updateFn           func(context.Context, *flightinspectionfilechecklist.FlightInspectionFileChecklist) error
+	deleteFn           func(context.Context, []byte) error
+}
+
+func (m fileChecklistServiceMock) Create(ctx context.Context, row *flightinspectionfilechecklist.FlightInspectionFileChecklist) error {
+	if m.createFn != nil {
+		return m.createFn(ctx, row)
+	}
+	return nil
+}
+func (m fileChecklistServiceMock) Update(ctx context.Context, row *flightinspectionfilechecklist.FlightInspectionFileChecklist) error {
+	if m.updateFn != nil {
+		return m.updateFn(ctx, row)
+	}
+	return nil
+}
+func (m fileChecklistServiceMock) Delete(ctx context.Context, id []byte) error {
+	if m.deleteFn != nil {
+		return m.deleteFn(ctx, id)
+	}
+	return nil
+}
+func (fileChecklistServiceMock) GetByID(context.Context, []byte) (*flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+	return nil, nil
+}
+func (fileChecklistServiceMock) List(context.Context, string, string, int, int) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, int64, error) {
+	return nil, 0, nil
+}
+func (m fileChecklistServiceMock) ListByInspectionID(ctx context.Context, id []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+	if m.listByInspectionFn != nil {
+		return m.listByInspectionFn(ctx, id)
+	}
+	return nil, nil
+}
+func (fileChecklistServiceMock) FlightInspectionExists(context.Context, []byte) (bool, error) {
+	return true, nil
+}
+func (fileChecklistServiceMock) HelicopterFileExists(context.Context, []byte) (bool, error) {
+	return true, nil
+}
+
+type reserveAcHelicopterServiceMock struct{}
+
+func (reserveAcHelicopterServiceMock) Create(context.Context, *helicopter.Helicopter) error {
+	return nil
+}
+func (reserveAcHelicopterServiceMock) Update(context.Context, *helicopter.Helicopter) error {
+	return nil
+}
+func (reserveAcHelicopterServiceMock) ExistsByIdentifier(context.Context, string, []byte) (bool, error) {
+	return false, nil
+}
+func (reserveAcHelicopterServiceMock) ApplySortKeyPatch(*helicopter.Helicopter, helicopter.SortKeyPatch) {
+}
+func (reserveAcHelicopterServiceMock) Delete(context.Context, []byte) error { return nil }
+func (reserveAcHelicopterServiceMock) GetByID(context.Context, []byte) (*helicopter.Helicopter, error) {
+	return nil, nil
+}
+func (reserveAcHelicopterServiceMock) List(context.Context, string, []string, string, int, int, [][]byte) ([]helicopter.Helicopter, int64, error) {
+	return nil, 0, nil
+}
+func (reserveAcHelicopterServiceMock) NextReportNumber(context.Context, []byte) (string, int, error) {
+	return "", 0, nil
+}
+func (reserveAcHelicopterServiceMock) IsInUse(context.Context, []byte) (bool, error) {
+	return false, nil
+}
+func (reserveAcHelicopterServiceMock) InUseByAircraftIDs(context.Context, [][]byte) (map[string]bool, error) {
+	return map[string]bool{}, nil
+}
+func (reserveAcHelicopterServiceMock) ActiveFlightIDByAircraftIDs(context.Context, [][]byte) (map[string][]byte, error) {
+	return map[string][]byte{}, nil
+}
+
+type reserveAcHelicopterServiceWithGet struct {
+	getFn func(context.Context, []byte) (*helicopter.Helicopter, error)
+}
+
+func (reserveAcHelicopterServiceWithGet) Create(context.Context, *helicopter.Helicopter) error {
+	return nil
+}
+func (reserveAcHelicopterServiceWithGet) Update(context.Context, *helicopter.Helicopter) error {
+	return nil
+}
+func (reserveAcHelicopterServiceWithGet) ExistsByIdentifier(context.Context, string, []byte) (bool, error) {
+	return false, nil
+}
+func (reserveAcHelicopterServiceWithGet) ApplySortKeyPatch(*helicopter.Helicopter, helicopter.SortKeyPatch) {
+}
+func (reserveAcHelicopterServiceWithGet) Delete(context.Context, []byte) error { return nil }
+func (m reserveAcHelicopterServiceWithGet) GetByID(ctx context.Context, id []byte) (*helicopter.Helicopter, error) {
+	if m.getFn != nil {
+		return m.getFn(ctx, id)
+	}
+	return nil, nil
+}
+func (reserveAcHelicopterServiceWithGet) List(context.Context, string, []string, string, int, int, [][]byte) ([]helicopter.Helicopter, int64, error) {
+	return nil, 0, nil
+}
+func (reserveAcHelicopterServiceWithGet) NextReportNumber(context.Context, []byte) (string, int, error) {
+	return "", 0, nil
+}
+func (reserveAcHelicopterServiceWithGet) IsInUse(context.Context, []byte) (bool, error) {
+	return false, nil
+}
+func (reserveAcHelicopterServiceWithGet) InUseByAircraftIDs(context.Context, [][]byte) (map[string]bool, error) {
+	return map[string]bool{}, nil
+}
+func (reserveAcHelicopterServiceWithGet) ActiveFlightIDByAircraftIDs(context.Context, [][]byte) (map[string][]byte, error) {
+	return map[string][]byte{}, nil
+}
+
+func TestReserveAcHandler_MethodValidationAndGuards(t *testing.T) {
+	svc := &reserveAcServiceMock{}
+	h := NewReserveAcHandler(svc)
+	app := fiber.New()
+	app.Post("/create", h.Create)
+	app.Get("/get/:id", h.Get)
+	app.Get("/get-after/:inspection_id", h.GetAfterFlightInspection)
+	app.Post("/upsert-after/:inspection_id", h.UpsertAfterFlightInspection)
+	app.Get("/last", h.GetLastFlightsInspection)
+	app.Post("/last", h.CreateLastFlightsInspection)
+	app.Patch("/last", h.UpdateLastFlightsInspection)
+	app.Delete("/last", h.DeleteLastFlightsInspection)
+	app.Patch("/update/:id", h.Update)
+
+	cases := []struct {
+		method, path, body string
+		want               int
+	}{
+		{http.MethodPost, "/create", "{bad", 400},
+		{http.MethodGet, "/get/bad", "", 422},
+		{http.MethodGet, "/get-after/bad", "", 422},
+		{http.MethodPost, "/upsert-after/bad", `{}`, 422},
+		{http.MethodGet, "/last?inspection_id=bad", "", 422},
+		{http.MethodPost, "/last", "{bad", 500},
+		{http.MethodPatch, "/last", "{bad", 500},
+		{http.MethodDelete, "/last", "{bad", 400},
+		{http.MethodPatch, "/update/bad", `{"data":{"type":"reserve_ac_update","id":"bad","attributes":{"helicopter_id":"x"}}}`, 422},
+	}
+	for _, tc := range cases {
+		req, _ := http.NewRequest(tc.method, tc.path, strings.NewReader(tc.body))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != tc.want {
+			t.Fatalf("%s %s expected %d got %d", tc.method, tc.path, tc.want, res.StatusCode)
+		}
+	}
+
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	createBody := `{"data":{"type":"reserve_ac_create","attributes":{"helicopter_id":"` + idStr + `","flight_id":"` + idStr + `","inspection":{"inspection_date":"2026-05-06","before":{"fuel_amount":1},"prepare":{"notam_briefing":true}}}}}`
+	req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(createBody))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ := app.Test(req)
+	if res.StatusCode != 500 {
+		t.Fatalf("expected 500 when service not configured, got %d", res.StatusCode)
+	}
+
+	h.after = &afterServiceMock{}
+	req, _ = http.NewRequest(http.MethodPatch, "/last", strings.NewReader(`{"data":{"type":"last_flights_inspection_update","attributes":{"flight_inspection_id":"`+idStr+`"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	_, _ = app.Test(req)
+}
+
+func TestReserveAcHandler_WithMethodsAndErrorBranches(t *testing.T) {
+	h := NewReserveAcHandler(&reserveAcServiceMock{})
+	h.WithFlightService(&reserveFlightServiceMock{}).
+		WithHelicopterService(reserveAcHelicopterServiceMock{}).
+		WithFlightInspectionService(&inspectionServiceMock{}).
+		WithBeforeFlightInspectionService(beforeServiceMock{}).
+		WithFlightPrepCheckService(prepServiceMock{}).
+		WithAfterFlightInspectionService(&afterServiceMock{}).
+		WithHelicopterFileService(heliFileServiceMock{}).
+		WithFlightInspectionFileChecklistService(fileChecklistServiceMock{})
+
+	app := fiber.New()
+	app.Get("/after/:inspection_id", h.GetAfterFlightInspection)
+	app.Post("/after/:inspection_id", h.UpsertAfterFlightInspection)
+
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	req, _ := http.NewRequest(http.MethodGet, "/after/"+idStr, nil)
+	res, _ := app.Test(req)
+	if res.StatusCode != 404 {
+		t.Fatalf("expected 404, got %d", res.StatusCode)
+	}
+
+	h.svc = &reserveAcServiceMock{
+		getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+			return nil, errors.New("boom")
+		},
+	}
+	req, _ = http.NewRequest(http.MethodGet, "/after/"+idStr, nil)
+	res, _ = app.Test(req)
+	if res.StatusCode != 400 {
+		t.Fatalf("expected 400, got %d", res.StatusCode)
+	}
+}
+
+func TestReserveAcHandler_InternalHelpers(t *testing.T) {
+	inspectionID := uuidv7.MustBytes()
+	heliID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	h := NewReserveAcHandler(&reserveAcServiceMock{})
+	h.inspect = &inspectionServiceMock{
+		getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+			return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Date(2026, 5, 6, 0, 0, 0, 0, time.UTC)}, nil
+		},
+	}
+	h.heliFile = heliFileServiceMock{
+		listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+			return []helicopterfile.HelicopterFile{{ID: fileID}}, nil
+		},
+	}
+	h.fileCk = fileChecklistServiceMock{
+		listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return []flightinspectionfilechecklist.FlightInspectionFileChecklist{{HelicopterFileID: fileID, IsDone: true}}, nil
+		},
+	}
+	h.before = beforeServiceMock{}
+	h.prep = prepServiceMock{}
+
+	app := fiber.New()
+	app.Get("/x", func(c *fiber.Ctx) error {
+		_, err := h.buildCreateInspectionSummary(c, inspectionID, heliID)
+		if err != nil {
+			return err
+		}
+		_, err = h.buildInspectionChecklistSection(c, inspectionID, heliID, helicopterfile.SectionBeforeFirstFlightInspection)
+		if err != nil {
+			return err
+		}
+		if v := boolPtr(true); v == nil || !*v {
+			t.Fatal("boolPtr failed")
+		}
+		return c.SendStatus(200)
+	})
+	req, _ := http.NewRequest(http.MethodGet, "/x", nil)
+	res, err := app.Test(req)
+	if err != nil || res.StatusCode != 200 {
+		t.Fatalf("expected 200, got %v %d", err, res.StatusCode)
+	}
+}
+
+func TestReserveAcHandler_FileChecklistUpsertAndDelete(t *testing.T) {
+	inspectionID := uuidv7.MustBytes()
+	heliID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	h := NewReserveAcHandler(&reserveAcServiceMock{})
+	h.heliFile = heliFileServiceMock{
+		listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+			return []helicopterfile.HelicopterFile{{ID: fileID}}, nil
+		},
+	}
+	created := 0
+	deleted := 0
+	h.fileCk = fileChecklistServiceMock{
+		listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return []flightinspectionfilechecklist.FlightInspectionFileChecklist{{ID: uuidv7.MustBytes(), HelicopterFileID: fileID, IsDone: false}}, nil
+		},
+		createFn: func(context.Context, *flightinspectionfilechecklist.FlightInspectionFileChecklist) error {
+			created++
+			return nil
+		},
+		updateFn: func(context.Context, *flightinspectionfilechecklist.FlightInspectionFileChecklist) error { return nil },
+		deleteFn: func(context.Context, []byte) error { deleted++; return nil },
+	}
+
+	fileIDStr, _ := uuidv7.BytesToString(fileID)
+	app := fiber.New()
+	app.Post("/u", func(c *fiber.Ctx) error {
+		if ok, err := h.upsertInspectionFileChecklistSection(c, inspectionID, heliID, helicopterfile.SectionBeforeFirstFlightInspection, []requestdto.ReserveAcFileChecklistItem{
+			{HelicopterFileID: fileIDStr, IsDone: true},
+		}, "/ptr", nil); err != nil {
+			return err
+		} else if !ok {
+			return nil
+		}
+		if err := h.deleteInspectionFileChecklistSection(c, inspectionID, heliID, helicopterfile.SectionBeforeFirstFlightInspection); err != nil {
+			return err
+		}
+		return c.SendStatus(200)
+	})
+	req, _ := http.NewRequest(http.MethodPost, "/u", strings.NewReader(`{}`))
+	res, err := app.Test(req)
+	if err != nil || res.StatusCode != 200 {
+		t.Fatalf("expected 200, got %v %d", err, res.StatusCode)
+	}
+	if created < 0 || deleted == 0 {
+		t.Fatalf("unexpected counters: created=%d deleted=%d", created, deleted)
+	}
+}
+
+func TestReserveAcHandler_StatusAndAircraftSummaryBranches(t *testing.T) {
+	h := NewReserveAcHandler(&reserveAcServiceMock{})
+	if !hasReserveAcBeforePayload(requestdto.ReserveAcBeforeInspectionAttributes{FuelUnit: reserveStrPtr("L")}) {
+		t.Fatal("expected before payload true for fuel unit")
+	}
+	if !hasReserveAcBeforePayload(requestdto.ReserveAcBeforeInspectionAttributes{Note: reserveStrPtr("n")}) {
+		t.Fatal("expected before payload true for note")
+	}
+
+	if got := h.calculateReserveAcStatus(&shareddto.ReserveAcInspectionSummary{
+		Before:  shareddto.ReserveAcBeforeSectionDTO{Total: 1, Completed: 0},
+		Prepare: shareddto.ReserveAcPrepareSectionDTO{Total: 0, Completed: 0},
+	}); got != reserveac.StatusPending {
+		t.Fatalf("expected pending, got %s", got)
+	}
+	if got := h.calculateReserveAcStatus(&shareddto.ReserveAcInspectionSummary{
+		Before:  shareddto.ReserveAcBeforeSectionDTO{Total: 1, Completed: 1},
+		Prepare: shareddto.ReserveAcPrepareSectionDTO{Total: 1, Completed: 1},
+	}); got != reserveac.StatusApproved {
+		t.Fatalf("expected approved, got %s", got)
+	}
+	if got := h.calculateReserveAcStatus(&shareddto.ReserveAcInspectionSummary{
+		Before: shareddto.ReserveAcBeforeSectionDTO{
+			Fields: &shareddto.ReserveAcBeforeInspectionFields{},
+		},
+	}); got != reserveac.StatusOnProgress {
+		t.Fatalf("expected on_progress, got %s", got)
+	}
+
+	aircraftID := uuidv7.MustBytes()
+	app := fiber.New()
+	app.Get("/x", func(c *fiber.Ctx) error {
+		// nil aircraft service
+		sum, err := h.buildAircraftSummary(c, aircraftID)
+		if err != nil || sum != nil {
+			t.Fatalf("expected nil summary, got err=%v sum=%v", err, sum)
+		}
+		h.aircraft = reserveAcHelicopterServiceWithGet{
+			getFn: func(context.Context, []byte) (*helicopter.Helicopter, error) { return nil, errors.New("boom") },
+		}
+		_, err = h.buildAircraftSummary(c, aircraftID)
+		if err == nil {
+			t.Fatal("expected error")
+		}
+		h.aircraft = reserveAcHelicopterServiceWithGet{
+			getFn: func(context.Context, []byte) (*helicopter.Helicopter, error) {
+				return &helicopter.Helicopter{
+					ID:          aircraftID,
+					Designation: "D",
+					Identifier:  "I",
+					Type:        "T",
+					AirOnGround: true,
+					IsActive:    true,
+				}, nil
+			},
+		}
+		sum, err = h.buildAircraftSummary(c, aircraftID)
+		if err != nil || sum == nil || sum.ID == "" {
+			t.Fatalf("expected aircraft summary, err=%v sum=%+v", err, sum)
+		}
+		return c.SendStatus(200)
+	})
+	req, _ := http.NewRequest(http.MethodGet, "/x", nil)
+	res, err := app.Test(req)
+	if err != nil || res.StatusCode != 200 {
+		t.Fatalf("expected 200, got err=%v code=%d", err, res.StatusCode)
+	}
+}
+
+func reserveStrPtr(v string) *string { return &v }
+
+func TestReserveAcHandler_CreateAndUpdateValidationMatrix(t *testing.T) {
+	h := NewReserveAcHandler(&reserveAcServiceMock{})
+	app := fiber.New()
+	app.Post("/create", h.Create)
+	app.Patch("/update/:id", h.Update)
+
+	validUUID := uuidv7.MustBytes()
+	validUUIDStr, _ := uuidv7.BytesToString(validUUID)
+
+	createCases := []struct {
+		name, body string
+		want       int
+	}{
+		{"bad helicopter uuid", `{"data":{"type":"reserve_ac_create","attributes":{"helicopter_id":"bad","flight_id":"` + validUUIDStr + `","inspection":{"inspection_date":"2026-05-06","before":{"fuel_amount":1},"prepare":{"notam_briefing":true}}}}}`, 422},
+		{"bad inspection date", `{"data":{"type":"reserve_ac_create","attributes":{"helicopter_id":"` + validUUIDStr + `","flight_id":"` + validUUIDStr + `","inspection":{"inspection_date":"x","before":{"fuel_amount":1},"prepare":{"notam_briefing":true}}}}}`, 422},
+		{"missing before payload", `{"data":{"type":"reserve_ac_create","attributes":{"helicopter_id":"` + validUUIDStr + `","flight_id":"` + validUUIDStr + `","inspection":{"inspection_date":"2026-05-06","before":{},"prepare":{"notam_briefing":true}}}}}`, 422},
+		{"missing prepare payload", `{"data":{"type":"reserve_ac_create","attributes":{"helicopter_id":"` + validUUIDStr + `","flight_id":"` + validUUIDStr + `","inspection":{"inspection_date":"2026-05-06","before":{"fuel_amount":1},"prepare":{}}}}}`, 422},
+		{"bad flight uuid", `{"data":{"type":"reserve_ac_create","attributes":{"helicopter_id":"` + validUUIDStr + `","flight_id":"bad","inspection":{"inspection_date":"2026-05-06","before":{"fuel_amount":1},"prepare":{"notam_briefing":true}}}}}`, 422},
+	}
+	for _, tc := range createCases {
+		req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(tc.body))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != tc.want {
+			t.Fatalf("%s expected %d got %d", tc.name, tc.want, res.StatusCode)
+		}
+	}
+
+	updateCases := []struct {
+		name, path, body string
+		want             int
+	}{
+		{"id required", "/update/", `{"data":{"type":"reserve_ac_update","attributes":{"helicopter_id":"` + validUUIDStr + `"}}}`, 404},
+		{"path-body mismatch", "/update/" + validUUIDStr, `{"data":{"type":"reserve_ac_update","id":"` + mustNewUUIDForReserve(t) + `","attributes":{"helicopter_id":"` + validUUIDStr + `"}}}`, 422},
+		{"at least one attr", "/update/" + validUUIDStr, `{"data":{"type":"reserve_ac_update","id":"` + validUUIDStr + `","attributes":{}}}`, 422},
+	}
+	for _, tc := range updateCases {
+		req, _ := http.NewRequest(http.MethodPatch, tc.path, strings.NewReader(tc.body))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != tc.want {
+			t.Fatalf("%s expected %d got %d", tc.name, tc.want, res.StatusCode)
+		}
+	}
+}
+
+func TestReserveAcHandler_UpsertChecklistErrorBranches(t *testing.T) {
+	inspectionID := uuidv7.MustBytes()
+	heliID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	fileIDStr, _ := uuidv7.BytesToString(fileID)
+
+	base := NewReserveAcHandler(&reserveAcServiceMock{})
+	base.heliFile = heliFileServiceMock{
+		listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+			return []helicopterfile.HelicopterFile{{ID: fileID}}, nil
+		},
+	}
+	base.fileCk = fileChecklistServiceMock{
+		listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return []flightinspectionfilechecklist.FlightInspectionFileChecklist{}, nil
+		},
+	}
+
+	app := fiber.New()
+	app.Post("/bad-uuid", func(c *fiber.Ctx) error {
+		if ok, err := base.upsertInspectionFileChecklistSection(c, inspectionID, heliID, helicopterfile.SectionBeforeFirstFlightInspection, []requestdto.ReserveAcFileChecklistItem{
+			{HelicopterFileID: "bad", IsDone: true},
+		}, "/p", nil); err != nil {
+			return err
+		} else if !ok {
+			return nil
+		}
+		return nil
+	})
+	app.Post("/not-in-template", func(c *fiber.Ctx) error {
+		other := uuidv7.MustBytes()
+		otherStr, _ := uuidv7.BytesToString(other)
+		if ok, err := base.upsertInspectionFileChecklistSection(c, inspectionID, heliID, helicopterfile.SectionBeforeFirstFlightInspection, []requestdto.ReserveAcFileChecklistItem{
+			{HelicopterFileID: otherStr, IsDone: true},
+		}, "/p", nil); err != nil {
+			return err
+		} else if !ok {
+			return nil
+		}
+		return nil
+	})
+	app.Post("/create-failed", func(c *fiber.Ctx) error {
+		base.fileCk = fileChecklistServiceMock{
+			listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+				return nil, nil
+			},
+			createFn: func(context.Context, *flightinspectionfilechecklist.FlightInspectionFileChecklist) error {
+				return errors.New("boom")
+			},
+		}
+		if ok, err := base.upsertInspectionFileChecklistSection(c, inspectionID, heliID, helicopterfile.SectionBeforeFirstFlightInspection, []requestdto.ReserveAcFileChecklistItem{
+			{HelicopterFileID: fileIDStr, IsDone: true},
+		}, "/p", nil); err != nil {
+			return err
+		} else if !ok {
+			return nil
+		}
+		return nil
+	})
+
+	for _, path := range []string{"/bad-uuid", "/not-in-template", "/create-failed"} {
+		req, _ := http.NewRequest(http.MethodPost, path, strings.NewReader(`{}`))
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != 422 && res.StatusCode != 400 {
+			t.Fatalf("%s expected 422/400 got %d", path, res.StatusCode)
+		}
+	}
+}
+
+func mustNewUUIDForReserve(t *testing.T) string {
+	t.Helper()
+	u := uuidv7.MustNew()
+	s, err := uuidv7.String(u)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return s
+}
+
+func validReserveCreateBody(heliID, flightID string) string {
+	return `{"data":{"type":"reserve_ac_create","attributes":{"helicopter_id":"` + heliID + `","flight_id":"` + flightID + `","inspection":{"inspection_date":"2026-05-06","before":{"fuel_amount":1},"prepare":{"notam_briefing":true}}}}}`
+}
+
+func TestReserveAcHandler_CreateStepErrors(t *testing.T) {
+	heliID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	heliStr, _ := uuidv7.BytesToString(heliID)
+	flightStr, _ := uuidv7.BytesToString(flightID)
+	baseFlight := &flight.Flight{ID: flightID}
+
+	newHandler := func() *ReserveAcHandler {
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			aircraftExistsFn: func(context.Context, []byte) (bool, error) { return true, nil },
+			getByIDFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+				return &reserveac.ReserveAc{ID: uuidv7.MustBytes(), AircraftID: heliID, InspectionID: uuidv7.MustBytes(), Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+			updateFn: func(context.Context, *reserveac.ReserveAc) error { return nil },
+		})
+		h.flight = &reserveFlightServiceMock{
+			getByIDFn: func(context.Context, []byte) (*flight.Flight, error) { return baseFlight, nil },
+			updateFn:  func(context.Context, *flight.Flight) error { return nil },
+		}
+		h.inspect = &inspectionServiceMock{
+			createDraftFn: func(_ context.Context, row *flightinspection.FlightInspection) error {
+				row.ID = uuidv7.MustBytes()
+				return nil
+			},
+			getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+				return &flightinspection.FlightInspection{ID: uuidv7.MustBytes(), InspectionDate: time.Now().UTC()}, nil
+			},
+		}
+		h.before = beforeServiceMock{}
+		h.prep = prepServiceMock{}
+		h.heliFile = heliFileServiceMock{listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) { return nil, nil }}
+		h.fileCk = fileChecklistServiceMock{listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return nil, nil
+		}}
+		return h
+	}
+
+	cases := []struct {
+		name string
+		mut  func(*ReserveAcHandler)
+		want int
+	}{
+		{"flight get error", func(h *ReserveAcHandler) {
+			h.flight = &reserveFlightServiceMock{getByIDFn: func(context.Context, []byte) (*flight.Flight, error) { return nil, errors.New("x") }}
+		}, 400},
+		{"flight nil", func(h *ReserveAcHandler) {
+			h.flight = &reserveFlightServiceMock{getByIDFn: func(context.Context, []byte) (*flight.Flight, error) { return nil, nil }}
+		}, 422},
+		{"aircraft exists error", func(h *ReserveAcHandler) {
+			h.svc = &reserveAcServiceMock{aircraftExistsFn: func(context.Context, []byte) (bool, error) { return false, errors.New("x") }}
+			h.flight = &reserveFlightServiceMock{getByIDFn: func(context.Context, []byte) (*flight.Flight, error) { return baseFlight, nil }}
+		}, 400},
+		{"aircraft not exists", func(h *ReserveAcHandler) {
+			h.svc = &reserveAcServiceMock{aircraftExistsFn: func(context.Context, []byte) (bool, error) { return false, nil }}
+			h.flight = &reserveFlightServiceMock{getByIDFn: func(context.Context, []byte) (*flight.Flight, error) { return baseFlight, nil }}
+		}, 422},
+		{"draft error", func(h *ReserveAcHandler) {
+			h.inspect = &inspectionServiceMock{createDraftFn: func(context.Context, *flightinspection.FlightInspection) error { return errors.New("x") }}
+		}, 400},
+		{"svc create error", func(h *ReserveAcHandler) {
+			h.svc = &reserveAcServiceMock{
+				aircraftExistsFn: func(context.Context, []byte) (bool, error) { return true, nil },
+				createFn:         func(context.Context, *reserveac.ReserveAc) error { return errors.New("x") },
+			}
+		}, 400},
+		{"before upsert error", func(h *ReserveAcHandler) {
+			h.before = beforeServiceFnMock{upsertFn: func(context.Context, []byte, *beforeflightinspection.UpsertRequest) (*beforeflightinspection.BeforeFlightInspection, error) {
+				return nil, errors.New("x")
+			}}
+		}, 400},
+		{"prep init error", func(h *ReserveAcHandler) {
+			h.prep = prepServiceFnMock{initFn: func(context.Context, []byte) (int, error) { return 0, errors.New("x") }}
+		}, 400},
+		{"prep upsert error", func(h *ReserveAcHandler) {
+			h.prep = prepServiceFnMock{upsertFn: func(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+				return nil, errors.New("x")
+			}}
+		}, 400},
+		{"flight update error", func(h *ReserveAcHandler) {
+			h.flight = &reserveFlightServiceMock{
+				getByIDFn: func(context.Context, []byte) (*flight.Flight, error) { return baseFlight, nil },
+				updateFn:  func(context.Context, *flight.Flight) error { return errors.New("x") },
+			}
+		}, 400},
+	}
+
+	for _, tc := range cases {
+		h := newHandler()
+		tc.mut(h)
+		app := fiber.New()
+		app.Post("/create", h.Create)
+		req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(validReserveCreateBody(heliStr, flightStr)))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != tc.want {
+			t.Fatalf("%s expected %d got %d", tc.name, tc.want, res.StatusCode)
+		}
+	}
+}
+
+func TestReserveAcHandler_UpdateBranchMatrix(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	inspectionID := uuidv7.MustBytes()
+	aircraftID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	flightIDStr, _ := uuidv7.BytesToString(flightID)
+
+	newHandler := func() *ReserveAcHandler {
+		svc := &reserveAcServiceMock{
+			getByIDFn: func(_ context.Context, q []byte) (*reserveac.ReserveAc, error) {
+				if string(q) == string(id) {
+					return &reserveac.ReserveAc{
+						ID:           id,
+						AircraftID:   aircraftID,
+						InspectionID: inspectionID,
+						Status:       reserveac.StatusPending,
+						CreatedAt:    time.Now().UTC(),
+						UpdatedAt:    time.Now().UTC(),
+					}, nil
+				}
+				return nil, nil
+			},
+			updateFn:         func(context.Context, *reserveac.ReserveAc) error { return nil },
+			aircraftExistsFn: func(context.Context, []byte) (bool, error) { return true, nil },
+		}
+		h := NewReserveAcHandler(svc)
+		h.flight = &reserveFlightServiceMock{
+			getByIDFn: func(_ context.Context, q []byte) (*flight.Flight, error) {
+				return &flight.Flight{ID: q}, nil
+			},
+			getByReserveAcFn: func(context.Context, []byte) (*flight.Flight, error) { return nil, nil },
+			updateFn:         func(context.Context, *flight.Flight) error { return nil },
+		}
+		h.inspect = &inspectionServiceMock{
+			getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+				return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Now().UTC()}, nil
+			},
+			updateFn: func(context.Context, *flightinspection.FlightInspection) error { return nil },
+		}
+		h.before = beforeServiceMock{}
+		h.prep = prepServiceMock{}
+		h.heliFile = heliFileServiceMock{
+			listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) { return nil, nil },
+		}
+		h.fileCk = fileChecklistServiceMock{
+			listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+				return nil, nil
+			},
+		}
+		return h
+	}
+
+	run := func(h *ReserveAcHandler, body string) int {
+		app := fiber.New()
+		app.Patch("/u/:id", h.Update)
+		req, _ := http.NewRequest(http.MethodPatch, "/u/"+idStr, strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return res.StatusCode
+	}
+
+	if got := run(newHandler(), "{bad"); got != 400 {
+		t.Fatalf("invalid json expected 400 got %d", got)
+	}
+	if got := run(newHandler(), `{"data":{"type":"bad_type","id":"`+idStr+`","attributes":{"flight_id":"`+flightIDStr+`"}}}`); got != 422 {
+		t.Fatalf("validator expected 422 got %d", got)
+	}
+	if got := run(newHandler(), `{"data":{"type":"reserve_ac_update","id":"bad","attributes":{"flight_id":"`+flightIDStr+`"}}}`); got != 422 {
+		t.Fatalf("id invalid expected 422 got %d", got)
+	}
+	if got := run(newHandler(), `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{}}}`); got != 422 {
+		t.Fatalf("attrs empty expected 422 got %d", got)
+	}
+
+	// hasFlight branch coverage
+	{
+		h := newHandler()
+		h.svc = &reserveAcServiceMock{getByIDFn: h.svc.(*reserveAcServiceMock).getByIDFn}
+		h.flight = nil
+		if got := run(h, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"flight_id":"`+flightIDStr+`"}}}`); got != 500 {
+			t.Fatalf("flight nil expected 500 got %d", got)
+		}
+	}
+	{
+		h := newHandler()
+		h.flight = &reserveFlightServiceMock{getByIDFn: func(context.Context, []byte) (*flight.Flight, error) { return nil, errors.New("x") }}
+		if got := run(h, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"flight_id":"`+flightIDStr+`"}}}`); got != 400 {
+			t.Fatalf("flight get err expected 400 got %d", got)
+		}
+	}
+	{
+		h := newHandler()
+		h.flight = &reserveFlightServiceMock{getByIDFn: func(context.Context, []byte) (*flight.Flight, error) { return nil, nil }}
+		if got := run(h, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"flight_id":"`+flightIDStr+`"}}}`); got != 422 {
+			t.Fatalf("flight nil expected 422 got %d", got)
+		}
+	}
+	{
+		h := newHandler()
+		h.flight = &reserveFlightServiceMock{
+			getByIDFn: func(context.Context, []byte) (*flight.Flight, error) {
+				return &flight.Flight{ID: flightID, ReserveAcID: uuidv7.MustBytes()}, nil
+			},
+		}
+		if got := run(h, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"flight_id":"`+flightIDStr+`"}}}`); got != 422 {
+			t.Fatalf("flight already has reserve expected 422 got %d", got)
+		}
+	}
+	{
+		h := newHandler()
+		h.flight = &reserveFlightServiceMock{
+			getByIDFn:        func(context.Context, []byte) (*flight.Flight, error) { return &flight.Flight{ID: flightID}, nil },
+			getByReserveAcFn: func(context.Context, []byte) (*flight.Flight, error) { return nil, errors.New("x") },
+		}
+		if got := run(h, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"flight_id":"`+flightIDStr+`"}}}`); got != 400 {
+			t.Fatalf("current flight err expected 400 got %d", got)
+		}
+	}
+
+	// aircraft branch coverage
+	{
+		h := newHandler()
+		if got := run(h, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"helicopter_id":"bad"}}}`); got != 422 {
+			t.Fatalf("aircraft parse expected 422 got %d", got)
+		}
+	}
+	{
+		h := newHandler()
+		h.svc.(*reserveAcServiceMock).aircraftExistsFn = func(context.Context, []byte) (bool, error) { return false, errors.New("x") }
+		if got := run(h, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"helicopter_id":"`+idStr+`"}}}`); got != 400 {
+			t.Fatalf("aircraft exists err expected 400 got %d", got)
+		}
+	}
+	{
+		h := newHandler()
+		h.svc.(*reserveAcServiceMock).aircraftExistsFn = func(context.Context, []byte) (bool, error) { return false, nil }
+		if got := run(h, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"helicopter_id":"`+idStr+`"}}}`); got != 422 {
+			t.Fatalf("aircraft not exists expected 422 got %d", got)
+		}
+	}
+
+	// inspection branch coverage
+	{
+		h := newHandler()
+		h.inspect = &inspectionServiceMock{getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) { return nil, errors.New("x") }}
+		if got := run(h, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"inspection":{"inspection_date":"2026-05-06"}}}}`); got != 400 {
+			t.Fatalf("inspection get err expected 400 got %d", got)
+		}
+	}
+	{
+		h := newHandler()
+		h.inspect = &inspectionServiceMock{getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) { return nil, nil }}
+		if got := run(h, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"inspection":{"inspection_date":"2026-05-06"}}}}`); got != 404 {
+			t.Fatalf("inspection nil expected 404 got %d", got)
+		}
+	}
+	{
+		h := newHandler()
+		if got := run(h, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"inspection":{"inspection_date":"bad"}}}}`); got != 422 {
+			t.Fatalf("inspection date parse expected 422 got %d", got)
+		}
+	}
+}
+
+func TestReserveAcHandler_UpdateDeepBranches(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	inspectionID := uuidv7.MustBytes()
+	aircraftID := uuidv7.MustBytes()
+	targetFlightID := uuidv7.MustBytes()
+	targetFlightStr, _ := uuidv7.BytesToString(targetFlightID)
+
+	makeHandler := func() *ReserveAcHandler {
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			getByIDFn: func(_ context.Context, q []byte) (*reserveac.ReserveAc, error) {
+				if len(q) == 16 {
+					return &reserveac.ReserveAc{ID: id, AircraftID: aircraftID, InspectionID: inspectionID, Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+				}
+				return nil, nil
+			},
+			aircraftExistsFn: func(context.Context, []byte) (bool, error) { return true, nil },
+			updateFn:         func(context.Context, *reserveac.ReserveAc) error { return nil },
+		})
+		h.flight = &reserveFlightServiceMock{
+			getByIDFn: func(_ context.Context, q []byte) (*flight.Flight, error) { return &flight.Flight{ID: q}, nil },
+			getByReserveAcFn: func(context.Context, []byte) (*flight.Flight, error) {
+				return &flight.Flight{ID: uuidv7.MustBytes(), ReserveAcID: id}, nil
+			},
+			updateFn: func(context.Context, *flight.Flight) error { return nil },
+		}
+		h.inspect = &inspectionServiceMock{
+			getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+				return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Now().UTC()}, nil
+			},
+			updateFn: func(context.Context, *flightinspection.FlightInspection) error { return nil },
+		}
+		h.before = beforeServiceMock{}
+		h.prep = prepServiceMock{}
+		h.heliFile = heliFileServiceMock{listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) { return nil, nil }}
+		h.fileCk = fileChecklistServiceMock{listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return nil, nil
+		}}
+		return h
+	}
+
+	run := func(app *fiber.App, path, body string) int {
+		req, _ := http.NewRequest(http.MethodPatch, path, strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return res.StatusCode
+	}
+
+	// pathID empty -> use uuid param
+	{
+		h := makeHandler()
+		app := fiber.New()
+		app.Patch("/u/:uuid", h.Update)
+		status := run(app, "/u/"+idStr, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"flight_id":"`+targetFlightStr+`"}}}`)
+		if status != 200 {
+			t.Fatalf("uuid param path expected 200 got %d", status)
+		}
+	}
+
+	// id required when no path param and no body id
+	{
+		h := makeHandler()
+		app := fiber.New()
+		app.Patch("/u", h.Update)
+		status := run(app, "/u", `{"data":{"type":"reserve_ac_update","attributes":{"flight_id":"`+targetFlightStr+`"}}}`)
+		if status != 422 {
+			t.Fatalf("id required expected 422 got %d", status)
+		}
+	}
+
+	// not found path
+	{
+		h := makeHandler()
+		h.svc = &reserveAcServiceMock{getByIDFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) { return nil, nil }}
+		app := fiber.New()
+		app.Patch("/u/:id", h.Update)
+		status := run(app, "/u/"+idStr, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"flight_id":"`+targetFlightStr+`"}}}`)
+		if status != 404 {
+			t.Fatalf("not found expected 404 got %d", status)
+		}
+	}
+
+	// current flight update error branch
+	{
+		h := makeHandler()
+		h.flight = &reserveFlightServiceMock{
+			getByIDFn: func(_ context.Context, q []byte) (*flight.Flight, error) { return &flight.Flight{ID: q}, nil },
+			getByReserveAcFn: func(context.Context, []byte) (*flight.Flight, error) {
+				return &flight.Flight{ID: uuidv7.MustBytes(), ReserveAcID: id}, nil
+			},
+			updateFn: func(context.Context, *flight.Flight) error { return errors.New("x") },
+		}
+		app := fiber.New()
+		app.Patch("/u/:id", h.Update)
+		status := run(app, "/u/"+idStr, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"flight_id":"`+targetFlightStr+`"}}}`)
+		if status != 400 {
+			t.Fatalf("current flight update err expected 400 got %d", status)
+		}
+	}
+
+	// inspection update error + before/prepare errors
+	{
+		h := makeHandler()
+		h.inspect = &inspectionServiceMock{
+			getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+				return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Now().UTC()}, nil
+			},
+			updateFn: func(context.Context, *flightinspection.FlightInspection) error { return errors.New("x") },
+		}
+		app := fiber.New()
+		app.Patch("/u/:id", h.Update)
+		status := run(app, "/u/"+idStr, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"inspection":{"inspection_date":"2026-05-06"}}}}`)
+		if status != 400 {
+			t.Fatalf("inspection update err expected 400 got %d", status)
+		}
+	}
+	{
+		h := makeHandler()
+		h.before = beforeServiceFnMock{upsertFn: func(context.Context, []byte, *beforeflightinspection.UpsertRequest) (*beforeflightinspection.BeforeFlightInspection, error) {
+			return nil, errors.New("x")
+		}}
+		app := fiber.New()
+		app.Patch("/u/:id", h.Update)
+		status := run(app, "/u/"+idStr, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"inspection":{"before":{"fuel_amount":1}}}}}`)
+		if status != 400 {
+			t.Fatalf("before upsert err expected 400 got %d", status)
+		}
+	}
+	{
+		h := makeHandler()
+		h.prep = prepServiceFnMock{upsertFn: func(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+			return nil, errors.New("x")
+		}}
+		app := fiber.New()
+		app.Patch("/u/:id", h.Update)
+		status := run(app, "/u/"+idStr, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"inspection":{"prepare":{"notam_briefing":true}}}}}`)
+		if status != 400 {
+			t.Fatalf("prepare upsert err expected 400 got %d", status)
+		}
+	}
+
+	// final update error and final fallback response
+	{
+		h := makeHandler()
+		h.svc.(*reserveAcServiceMock).updateFn = func(context.Context, *reserveac.ReserveAc) error { return errors.New("x") }
+		app := fiber.New()
+		app.Patch("/u/:id", h.Update)
+		status := run(app, "/u/"+idStr, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"helicopter_id":"`+idStr+`"}}}`)
+		if status != 400 {
+			t.Fatalf("svc update err expected 400 got %d", status)
+		}
+	}
+	{
+		h := makeHandler()
+		calls := 0
+		h.svc.(*reserveAcServiceMock).getByIDFn = func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+			calls++
+			if calls == 1 {
+				return &reserveac.ReserveAc{ID: id, AircraftID: aircraftID, InspectionID: inspectionID, Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			}
+			return nil, errors.New("fallback")
+		}
+		app := fiber.New()
+		app.Patch("/u/:id", h.Update)
+		status := run(app, "/u/"+idStr, `{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"helicopter_id":"`+idStr+`"}}}`)
+		if status != 200 {
+			t.Fatalf("fallback response expected 200 got %d", status)
+		}
+	}
+}
+
+func TestReserveAcHandler_GetFallbackByFlightID(t *testing.T) {
+	reserveID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	flightIDStr, _ := uuidv7.BytesToString(flightID)
+	h := NewReserveAcHandler(&reserveAcServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*reserveac.ReserveAc, error) {
+			if string(id) == string(reserveID) {
+				return &reserveac.ReserveAc{ID: reserveID, AircraftID: uuidv7.MustBytes(), InspectionID: uuidv7.MustBytes(), Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			}
+			return nil, errors.New("not found")
+		},
+	})
+	h.flight = &reserveFlightServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*flight.Flight, error) {
+			if string(id) == string(flightID) {
+				return &flight.Flight{ID: id, ReserveAcID: reserveID}, nil
+			}
+			return nil, nil
+		},
+	}
+	h.inspect = &inspectionServiceMock{
+		getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+			return &flightinspection.FlightInspection{ID: uuidv7.MustBytes(), InspectionDate: time.Now().UTC()}, nil
+		},
+	}
+	h.before = beforeServiceMock{}
+	h.prep = prepServiceMock{}
+	h.heliFile = heliFileServiceMock{
+		listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) { return nil, nil },
+	}
+	h.fileCk = fileChecklistServiceMock{
+		listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return nil, nil
+		},
+	}
+	app := fiber.New()
+	app.Get("/get/:id", h.Get)
+	req, _ := http.NewRequest(http.MethodGet, "/get/"+flightIDStr, nil)
+	res, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", res.StatusCode)
+	}
+}
+
+func TestReserveAcHandler_UpdateServiceNilAndBadFlightID(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	h := NewReserveAcHandler(&reserveAcServiceMock{
+		getByIDFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+			return &reserveac.ReserveAc{ID: id, AircraftID: uuidv7.MustBytes(), InspectionID: uuidv7.MustBytes(), Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+		},
+	})
+	app := fiber.New()
+	app.Patch("/u/:id", h.Update)
+
+	req, _ := http.NewRequest(http.MethodPatch, "/u/"+idStr, strings.NewReader(`{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"flight_id":"`+idStr+`"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, err := app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != 500 {
+		t.Fatalf("expected 500, got %d", res.StatusCode)
+	}
+
+	h.flight = &reserveFlightServiceMock{
+		getByIDFn: func(context.Context, []byte) (*flight.Flight, error) { return nil, nil },
+	}
+	req, _ = http.NewRequest(http.MethodPatch, "/u/"+idStr, strings.NewReader(`{"data":{"type":"reserve_ac_update","id":"`+idStr+`","attributes":{"flight_id":"bad"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, err = app.Test(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.StatusCode != 422 {
+		t.Fatalf("expected 422, got %d", res.StatusCode)
+	}
+}
+
+func TestReserveAcHandler_AfterFlightEndpointBranches(t *testing.T) {
+	inspectionID := uuidv7.MustBytes()
+	inspectionIDStr, _ := uuidv7.BytesToString(inspectionID)
+	aircraftID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+
+	t.Run("getAfter service guards", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{})
+		app := fiber.New()
+		app.Get("/after/:inspection_id", h.GetAfterFlightInspection)
+
+		req, _ := http.NewRequest(http.MethodGet, "/after/"+inspectionIDStr, nil)
+		res, _ := app.Test(req)
+		if res.StatusCode != 500 {
+			t.Fatalf("expected 500, got %d", res.StatusCode)
+		}
+
+		h.after = &afterServiceMock{}
+		req, _ = http.NewRequest(http.MethodGet, "/after/"+inspectionIDStr, nil)
+		res, _ = app.Test(req)
+		if res.StatusCode != 500 {
+			t.Fatalf("expected 500, got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("getAfter validation and notfound mapping", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+				return &reserveac.ReserveAc{ID: uuidv7.MustBytes(), AircraftID: aircraftID, InspectionID: inspectionID, Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		})
+		h.after = &afterServiceMock{
+			getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+				return nil, afterflightinspection.ErrCapabilitiesUnavailable
+			},
+		}
+		h.inspect = &inspectionServiceMock{
+			getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+				return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Now().UTC()}, nil
+			},
+		}
+		h.heliFile = heliFileServiceMock{
+			listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+				return []helicopterfile.HelicopterFile{{ID: fileID}}, nil
+			},
+		}
+		h.fileCk = fileChecklistServiceMock{
+			listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+				return nil, nil
+			},
+		}
+		app := fiber.New()
+		app.Get("/after/:inspection_id", h.GetAfterFlightInspection)
+		req, _ := http.NewRequest(http.MethodGet, "/after/"+inspectionIDStr, nil)
+		res, _ := app.Test(req)
+		if res.StatusCode != 422 {
+			t.Fatalf("expected 422, got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("createLast/updateLast/deleteLast branches", func(t *testing.T) {
+		fileIDStr, _ := uuidv7.BytesToString(fileID)
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+				return &reserveac.ReserveAc{ID: uuidv7.MustBytes(), AircraftID: aircraftID, InspectionID: inspectionID, Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		})
+		h.after = &afterServiceMock{
+			getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) { return nil, nil },
+			upsertFn: func(context.Context, []byte, *afterflightinspection.UpsertRequest) (*afterflightinspection.AfterFlightInspection, error) {
+				return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+			delFn: func(context.Context, []byte) error { return errors.New("del failed") },
+		}
+		h.inspect = &inspectionServiceMock{
+			getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+				return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Now().UTC()}, nil
+			},
+		}
+		h.heliFile = heliFileServiceMock{
+			listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+				return []helicopterfile.HelicopterFile{{ID: fileID}}, nil
+			},
+		}
+		h.fileCk = fileChecklistServiceMock{
+			listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+				return nil, nil
+			},
+		}
+
+		app := fiber.New()
+		app.Post("/last", h.CreateLastFlightsInspection)
+		app.Patch("/last", h.UpdateLastFlightsInspection)
+		app.Delete("/last", h.DeleteLastFlightsInspection)
+
+		createBody := `{"data":{"type":"last_flights_inspection_create","attributes":{"flight_inspection_id":"` + inspectionIDStr + `","file_checklist":[{"helicopter_file_id":"` + fileIDStr + `","is_done":true}]}}}`
+		req, _ := http.NewRequest(http.MethodPost, "/last", strings.NewReader(createBody))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ := app.Test(req)
+		if res.StatusCode != 200 {
+			t.Fatalf("expected 200, got %d", res.StatusCode)
+		}
+
+		updateBody := `{"data":{"type":"last_flights_inspection_update","attributes":{"flight_inspection_id":"` + inspectionIDStr + `"}}}`
+		req, _ = http.NewRequest(http.MethodPatch, "/last", strings.NewReader(updateBody))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ = app.Test(req)
+		if res.StatusCode != 404 {
+			t.Fatalf("expected 404 when existing nil, got %d", res.StatusCode)
+		}
+
+		h.after = &afterServiceMock{
+			getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+				return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+			delFn: func(context.Context, []byte) error { return errors.New("del failed") },
+		}
+		deleteBody := `{"data":{"type":"last_flights_inspection_delete","attributes":{"flight_inspection_id":"` + inspectionIDStr + `"}}}`
+		req, _ = http.NewRequest(http.MethodDelete, "/last", strings.NewReader(deleteBody))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ = app.Test(req)
+		if res.StatusCode != 400 {
+			t.Fatalf("expected 400 delete failure, got %d", res.StatusCode)
+		}
+	})
+}
+
+func TestReserveAcHandler_AfterFlightWrapperValidationBranches(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+
+	h := NewReserveAcHandler(&reserveAcServiceMock{
+		getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+			return &reserveac.ReserveAc{ID: uuidv7.MustBytes(), AircraftID: uuidv7.MustBytes(), InspectionID: id, Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+		},
+	})
+	h.after = &afterServiceMock{}
+	h.inspect = &inspectionServiceMock{
+		getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+			return &flightinspection.FlightInspection{ID: id, InspectionDate: time.Now().UTC()}, nil
+		},
+	}
+	h.heliFile = heliFileServiceMock{listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) { return nil, nil }}
+	h.fileCk = fileChecklistServiceMock{listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+		return nil, nil
+	}}
+
+	app := fiber.New()
+	app.Post("/upsert/:inspection_id", h.UpsertAfterFlightInspection)
+	app.Post("/create-last", h.CreateLastFlightsInspection)
+	app.Patch("/update-last", h.UpdateLastFlightsInspection)
+	app.Delete("/delete-last", h.DeleteLastFlightsInspection)
+
+	// UpsertAfter wrappers
+	req, _ := http.NewRequest(http.MethodPost, "/upsert/"+idStr, strings.NewReader("{bad"))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ := app.Test(req)
+	if res.StatusCode != 400 {
+		t.Fatalf("expected 400 got %d", res.StatusCode)
+	}
+	req, _ = http.NewRequest(http.MethodPost, "/upsert/"+idStr, strings.NewReader(`{}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != 422 {
+		t.Fatalf("expected 422 got %d", res.StatusCode)
+	}
+
+	// CreateLast wrapper validation paths
+	req, _ = http.NewRequest(http.MethodPost, "/create-last", strings.NewReader("{bad"))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != 400 {
+		t.Fatalf("expected 400 got %d", res.StatusCode)
+	}
+	req, _ = http.NewRequest(http.MethodPost, "/create-last", strings.NewReader(`{"data":{"type":"last_flights_inspection_create","attributes":{"flight_inspection_id":"bad"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != 422 {
+		t.Fatalf("expected 422 got %d", res.StatusCode)
+	}
+
+	// UpdateLast wrapper validation paths
+	req, _ = http.NewRequest(http.MethodPatch, "/update-last", strings.NewReader("{bad"))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != 400 {
+		t.Fatalf("expected 400 got %d", res.StatusCode)
+	}
+	req, _ = http.NewRequest(http.MethodPatch, "/update-last", strings.NewReader(`{"data":{"type":"last_flights_inspection_update","attributes":{"flight_inspection_id":"bad"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != 422 {
+		t.Fatalf("expected 422 got %d", res.StatusCode)
+	}
+
+	// DeleteLast wrapper validation paths
+	req, _ = http.NewRequest(http.MethodDelete, "/delete-last", strings.NewReader("{bad"))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != 400 {
+		t.Fatalf("expected 400 got %d", res.StatusCode)
+	}
+	req, _ = http.NewRequest(http.MethodDelete, "/delete-last", strings.NewReader(`{"data":{"type":"last_flights_inspection_delete","attributes":{"flight_inspection_id":"bad"}}}`))
+	req.Header.Set("Content-Type", "application/json")
+	res, _ = app.Test(req)
+	if res.StatusCode != 422 {
+		t.Fatalf("expected 422 got %d", res.StatusCode)
+	}
+
+	t.Run("create-last allows optional afi file checklist to be false", func(t *testing.T) {
+		inspectionID := uuidv7.MustBytes()
+		inspectionIDStr, _ := uuidv7.BytesToString(inspectionID)
+		aircraftID := uuidv7.MustBytes()
+		file1 := uuidv7.MustBytes()
+		file2 := uuidv7.MustBytes()
+		file1Str, _ := uuidv7.BytesToString(file1)
+		file2Str, _ := uuidv7.BytesToString(file2)
+
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+				return &reserveac.ReserveAc{ID: uuidv7.MustBytes(), AircraftID: aircraftID, InspectionID: inspectionID, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		})
+		h.after = &afterServiceMock{
+			getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) { return nil, nil },
+			upsertFn: func(context.Context, []byte, *afterflightinspection.UpsertRequest) (*afterflightinspection.AfterFlightInspection, error) {
+				t.Fatal("after upsert should not be called for incomplete checklist")
+				return nil, nil
+			},
+		}
+		h.inspect = &inspectionServiceMock{
+			getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+				return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Now().UTC()}, nil
+			},
+		}
+		h.heliFile = heliFileServiceMock{
+			listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+				return []helicopterfile.HelicopterFile{
+					{ID: file1, IsMandatory: true},
+					{ID: file2, IsMandatory: false},
+				}, nil
+			},
+		}
+		h.fileCk = fileChecklistServiceMock{
+			listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+				return nil, nil
+			},
+		}
+		h.after = &afterServiceMock{
+			upsertFn: func(context.Context, []byte, *afterflightinspection.UpsertRequest) (*afterflightinspection.AfterFlightInspection, error) {
+				return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		}
+
+		app := fiber.New()
+		app.Post("/create-last", h.CreateLastFlightsInspection)
+
+		body := `{"data":{"type":"last_flights_inspection_create","attributes":{"flight_inspection_id":"` + inspectionIDStr + `","file_checklist":[{"helicopter_file_id":"` + file1Str + `","is_done":true},{"helicopter_file_id":"` + file2Str + `","is_done":false}]}}}`
+		req, _ := http.NewRequest(http.MethodPost, "/create-last", strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ := app.Test(req)
+		if res.StatusCode != 200 {
+			t.Fatalf("expected 200 for optional false checklist, got %d", res.StatusCode)
+		}
+
+		body = `{"data":{"type":"last_flights_inspection_create","attributes":{"flight_inspection_id":"` + inspectionIDStr + `","file_checklist":[{"helicopter_file_id":"` + file1Str + `","is_done":false},{"helicopter_file_id":"` + file2Str + `","is_done":false}]}}}`
+		req, _ = http.NewRequest(http.MethodPost, "/create-last", strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ = app.Test(req)
+		if res.StatusCode != 422 {
+			t.Fatalf("expected 422 for mandatory unchecked checklist item, got %d", res.StatusCode)
+		}
+	})
+}
+
+func TestReserveAcHandler_CreateServiceGuardBranches(t *testing.T) {
+	heliID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	heliStr, _ := uuidv7.BytesToString(heliID)
+	flightStr, _ := uuidv7.BytesToString(flightID)
+
+	runCreate := func(h *ReserveAcHandler) int {
+		app := fiber.New()
+		app.Post("/create", h.Create)
+		req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(validReserveCreateBody(heliStr, flightStr)))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return res.StatusCode
+	}
+
+	newBase := func() *ReserveAcHandler {
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			aircraftExistsFn: func(context.Context, []byte) (bool, error) { return true, nil },
+		})
+		h.flight = &reserveFlightServiceMock{
+			getByIDFn: func(context.Context, []byte) (*flight.Flight, error) {
+				return &flight.Flight{ID: flightID}, nil
+			},
+			updateFn: func(context.Context, *flight.Flight) error { return nil },
+		}
+		return h
+	}
+
+	h := newBase()
+	if got := runCreate(h); got != 500 {
+		t.Fatalf("expected 500 when inspect nil, got %d", got)
+	}
+	h.inspect = &inspectionServiceMock{}
+	if got := runCreate(h); got != 500 {
+		t.Fatalf("expected 500 when before nil, got %d", got)
+	}
+	h.before = beforeServiceMock{}
+	if got := runCreate(h); got != 500 {
+		t.Fatalf("expected 500 when prep nil, got %d", got)
+	}
+	h.prep = prepServiceMock{}
+	if got := runCreate(h); got != 500 {
+		t.Fatalf("expected 500 when heliFile nil, got %d", got)
+	}
+	h.heliFile = heliFileServiceMock{}
+	if got := runCreate(h); got != 500 {
+		t.Fatalf("expected 500 when file checklist nil, got %d", got)
+	}
+
+	h = newBase()
+	h.inspect = &inspectionServiceMock{}
+	h.before = beforeServiceMock{}
+	h.prep = prepServiceMock{}
+	h.heliFile = heliFileServiceMock{}
+	h.fileCk = fileChecklistServiceMock{}
+	h.flight = &reserveFlightServiceMock{
+		getByIDFn: func(context.Context, []byte) (*flight.Flight, error) {
+			return &flight.Flight{ID: flightID, ReserveAcID: uuidv7.MustBytes()}, nil
+		},
+	}
+	if got := runCreate(h); got != 422 {
+		t.Fatalf("expected 422 when flight already linked, got %d", got)
+	}
+}
+
+func TestReserveAcHandler_GetDeleteListAdditionalBranches(t *testing.T) {
+	id := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(id)
+	aircraftID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	row := &reserveac.ReserveAc{ID: id, AircraftID: aircraftID, InspectionID: inspectionID, Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}
+
+	t.Run("get id from uuid param", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			getByIDFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) { return row, nil },
+		})
+		h.inspect = &inspectionServiceMock{
+			getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+				return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Now().UTC()}, nil
+			},
+		}
+		h.before = beforeServiceMock{}
+		h.prep = prepServiceMock{}
+		h.heliFile = heliFileServiceMock{
+			listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) { return nil, nil },
+		}
+		h.fileCk = fileChecklistServiceMock{
+			listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+				return nil, nil
+			},
+		}
+		app := fiber.New()
+		app.Get("/get/:uuid", h.Get)
+		req, _ := http.NewRequest(http.MethodGet, "/get/"+idStr, nil)
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != 200 {
+			t.Fatalf("expected 200 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("get fallback still 404 when svc err persists", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			getByIDFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) { return nil, errors.New("boom") },
+		})
+		h.flight = &reserveFlightServiceMock{
+			getByIDFn: func(context.Context, []byte) (*flight.Flight, error) {
+				return &flight.Flight{ID: id, ReserveAcID: uuidv7.MustBytes()}, nil
+			},
+		}
+		app := fiber.New()
+		app.Get("/get/:id", h.Get)
+		req, _ := http.NewRequest(http.MethodGet, "/get/"+idStr, nil)
+		res, _ := app.Test(req)
+		if res.StatusCode != 404 {
+			t.Fatalf("expected 404 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("delete id from uuid and delete error", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			deleteFn: func(context.Context, []byte, []byte) error { return errors.New("x") },
+		})
+		app := fiber.New()
+		app.Delete("/del/:uuid", h.Delete)
+		req, _ := http.NewRequest(http.MethodDelete, "/del/"+idStr, strings.NewReader(`{"data":{"id":"`+idStr+`"}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != 400 {
+			t.Fatalf("expected 400 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("delete not found returns 404", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			deleteFn: func(context.Context, []byte, []byte) error { return gorm.ErrRecordNotFound },
+		})
+		app := fiber.New()
+		app.Delete("/del/:uuid", h.Delete)
+		req, _ := http.NewRequest(http.MethodDelete, "/del/"+idStr, strings.NewReader(`{"data":{"id":"`+idStr+`"}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("list sizing and svc error", func(t *testing.T) {
+		calls := 0
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			listFn: func(_ context.Context, _ string, _ string, limit, offset int) ([]reserveac.ReserveAc, int64, error) {
+				calls++
+				if calls == 1 {
+					if limit != 20 || offset != 0 {
+						t.Fatalf("expected fallback limit=20 offset=0, got %d/%d", limit, offset)
+					}
+					return []reserveac.ReserveAc{*row}, 1, nil
+				}
+				if limit != 100 {
+					t.Fatalf("expected capped limit=100, got %d", limit)
+				}
+				return nil, 0, errors.New("list fail")
+			},
+		})
+		app := fiber.New()
+		app.Get("/list", h.List)
+
+		req, _ := http.NewRequest(http.MethodGet, "/list?page[number]=0&page[size]=0&size=0", nil)
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != 401 {
+			t.Fatalf("expected 401 got %d", res.StatusCode)
+		}
+
+		req, _ = http.NewRequest(http.MethodGet, "/list?page[number]=2&page[size]=101", nil)
+		res, _ = app.Test(req)
+		if res.StatusCode != 401 {
+			t.Fatalf("expected 401 got %d", res.StatusCode)
+		}
+	})
+}
+
+func TestReserveAcHandler_DeleteLastAndHelperErrorBranches(t *testing.T) {
+	inspectionID := uuidv7.MustBytes()
+	inspectionIDStr, _ := uuidv7.BytesToString(inspectionID)
+	aircraftID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	row := &reserveac.ReserveAc{ID: uuidv7.MustBytes(), AircraftID: aircraftID, InspectionID: inspectionID, Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}
+
+	t.Run("deleteLast after service not configured", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{})
+		app := fiber.New()
+		app.Delete("/delete-last", h.DeleteLastFlightsInspection)
+		req, _ := http.NewRequest(http.MethodDelete, "/delete-last", strings.NewReader(`{"data":{"type":"last_flights_inspection_delete","attributes":{"flight_inspection_id":"`+inspectionIDStr+`"}}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ := app.Test(req)
+		if res.StatusCode != 500 {
+			t.Fatalf("expected 500 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("deleteLast heli/file checklist guard", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{})
+		h.after = &afterServiceMock{
+			getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+				return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		}
+		app := fiber.New()
+		app.Delete("/delete-last", h.DeleteLastFlightsInspection)
+		req, _ := http.NewRequest(http.MethodDelete, "/delete-last", strings.NewReader(`{"data":{"type":"last_flights_inspection_delete","attributes":{"flight_inspection_id":"`+inspectionIDStr+`"}}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ := app.Test(req)
+		if res.StatusCode != 500 {
+			t.Fatalf("expected 500 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("getAfter generic error + checklist build error", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) { return row, nil },
+		})
+		h.after = &afterServiceMock{
+			getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+				return nil, errors.New("get failed")
+			},
+		}
+		h.inspect = &inspectionServiceMock{getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) { return nil, nil }}
+		h.heliFile = heliFileServiceMock{listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) { return nil, nil }}
+		h.fileCk = fileChecklistServiceMock{listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return nil, nil
+		}}
+		app := fiber.New()
+		app.Get("/after/:inspection_id", h.GetAfterFlightInspection)
+		req, _ := http.NewRequest(http.MethodGet, "/after/"+inspectionIDStr, nil)
+		res, _ := app.Test(req)
+		if res.StatusCode != 400 {
+			t.Fatalf("expected 400 got %d", res.StatusCode)
+		}
+
+		h.after = &afterServiceMock{
+			getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+				return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		}
+		h.heliFile = heliFileServiceMock{
+			listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+				return nil, errors.New("list section fail")
+			},
+		}
+		req, _ = http.NewRequest(http.MethodGet, "/after/"+inspectionIDStr, nil)
+		res, _ = app.Test(req)
+		if res.StatusCode != 400 {
+			t.Fatalf("expected 400 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("upsert checklist update error branch", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{})
+		h.heliFile = heliFileServiceMock{
+			listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+				return []helicopterfile.HelicopterFile{{ID: fileID}}, nil
+			},
+		}
+		h.fileCk = fileChecklistServiceMock{
+			listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+				return []flightinspectionfilechecklist.FlightInspectionFileChecklist{{ID: uuidv7.MustBytes(), HelicopterFileID: fileID, IsDone: false}}, nil
+			},
+			updateFn: func(context.Context, *flightinspectionfilechecklist.FlightInspectionFileChecklist) error {
+				return errors.New("update checklist fail")
+			},
+		}
+		fileIDStr, _ := uuidv7.BytesToString(fileID)
+		app := fiber.New()
+		app.Get("/upsert", func(c *fiber.Ctx) error {
+			if ok, err := h.upsertInspectionFileChecklistSection(
+				c,
+				inspectionID,
+				aircraftID,
+				helicopterfile.SectionAfterLastFlightInspection,
+				[]requestdto.ReserveAcFileChecklistItem{{
+					HelicopterFileID: fileIDStr,
+					IsDone:           true,
+				}},
+				"/data/attributes/file_checklist",
+				nil,
+			); err != nil {
+				return err
+			} else if !ok {
+				return nil
+			}
+			return nil
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/upsert", nil)
+		res, _ := app.Test(req)
+		if res.StatusCode != 400 {
+			t.Fatalf("expected 400 got %d", res.StatusCode)
+		}
+	})
+}
+
+func TestReserveAcHandler_UpsertAfterByIDBranchMatrix(t *testing.T) {
+	inspectionID := uuidv7.MustBytes()
+	aircraftID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	fileIDStr, _ := uuidv7.BytesToString(fileID)
+	validAttrs := requestdto.ReserveAcAfterFlightInspectionAttributes{
+		OilEngineNR1Checked:       reserveStrPtr("checked"),
+		OilEngineNR2Checked:       reserveStrPtr("checked"),
+		HydraulicLHChecked:        reserveStrPtr("checked"),
+		HydraulicRHChecked:        reserveStrPtr("checked"),
+		OilTransmissionMGBChecked: reserveStrPtr("checked"),
+		OilTransmissionIGBChecked: reserveStrPtr("checked"),
+		OilTransmissionTGBChecked: reserveStrPtr("checked"),
+		FileChecklist: []requestdto.ReserveAcFileChecklistItem{{
+			HelicopterFileID: fileIDStr,
+			IsDone:           true,
+		}},
+	}
+
+	run := func(h *ReserveAcHandler, attrs requestdto.ReserveAcAfterFlightInspectionAttributes) int {
+		app := fiber.New()
+		app.Get("/x", func(c *fiber.Ctx) error {
+			return h.upsertAfterFlightInspectionByID(c, inspectionID, attrs)
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/x", nil)
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return res.StatusCode
+	}
+
+	h := NewReserveAcHandler(&reserveAcServiceMock{})
+	if got := run(h, requestdto.ReserveAcAfterFlightInspectionAttributes{}); got != 500 {
+		t.Fatalf("expected 500 when after nil, got %d", got)
+	}
+	h.after = &afterServiceMock{}
+	if got := run(h, requestdto.ReserveAcAfterFlightInspectionAttributes{}); got != 500 {
+		t.Fatalf("expected 500 when inspect nil, got %d", got)
+	}
+	h.inspect = &inspectionServiceMock{}
+	if got := run(h, requestdto.ReserveAcAfterFlightInspectionAttributes{}); got != 500 {
+		t.Fatalf("expected 500 when checklist services nil, got %d", got)
+	}
+
+	h.heliFile = heliFileServiceMock{}
+	h.fileCk = fileChecklistServiceMock{}
+	h.svc = &reserveAcServiceMock{
+		getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) { return nil, errors.New("boom") },
+	}
+	if got := run(h, requestdto.ReserveAcAfterFlightInspectionAttributes{}); got != 400 {
+		t.Fatalf("expected 400 on active lookup error, got %d", got)
+	}
+	h.svc = &reserveAcServiceMock{
+		getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) { return nil, nil },
+	}
+	if got := run(h, requestdto.ReserveAcAfterFlightInspectionAttributes{}); got != 404 {
+		t.Fatalf("expected 404 on active lookup nil, got %d", got)
+	}
+
+	flightID := uuidv7.MustBytes()
+	missionID := uuidv7.MustBytes()
+	flightDataID := uuidv7.MustBytes()
+	h.flight = &reserveFlightServiceMock{
+		getByReserveAcFn: func(context.Context, []byte) (*flight.Flight, error) {
+			return &flight.Flight{ID: flightID}, nil
+		},
+	}
+	h.mission = reserveMissionServiceMock{
+		listByFlightIDFn: func(context.Context, []byte) ([]mission.Mission, error) {
+			return []mission.Mission{{
+				ID:           missionID,
+				FlightID:     flightID,
+				FlightDataID: flightDataID,
+				Type:         "HEMS",
+			}}, nil
+		},
+	}
+	h.flightData = reserveFlightDataServiceMock{
+		getByIDFn: func(context.Context, []byte) (*flightdata.FlightData, error) {
+			now := time.Now().UTC()
+			return &flightdata.FlightData{
+				ID:              flightDataID,
+				MissionID:       missionID,
+				CoPilotID:       uuidv7.MustBytes(),
+				FromHospitalID:  uuidv7.MustBytes(),
+				ToICAOID:        uuidv7.MustBytes(),
+				FlightTakeOff:   now.Add(-10 * time.Minute),
+				FlightLanding:   now,
+				FlightDuration:  10 * time.Minute,
+				FlightType:      "HEMS",
+				LandingCount:    1,
+				RotorBrakeCycle: 1,
+				Status:          flightdata.StatusCompleted,
+				FromHospital:    &hospitaldomain.Hospital{ID: uuidv7.MustBytes(), Name: "A"},
+				ToICAO:          &icaodomain.ICAO{ID: uuidv7.MustBytes(), ICAOCode: "B"},
+			}, nil
+		},
+	}
+
+	h.heliFile = heliFileServiceMock{
+		listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+			return []helicopterfile.HelicopterFile{{ID: fileID}}, nil
+		},
+	}
+	h.fileCk = fileChecklistServiceMock{
+		listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return nil, nil
+		},
+	}
+	h.svc = &reserveAcServiceMock{
+		getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+			return &reserveac.ReserveAc{ID: uuidv7.MustBytes(), AircraftID: aircraftID, InspectionID: inspectionID, Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+		},
+	}
+	h.after = &afterServiceMock{
+		upsertFn: func(context.Context, []byte, *afterflightinspection.UpsertRequest) (*afterflightinspection.AfterFlightInspection, error) {
+			return nil, afterflightinspection.ErrCapabilitiesUnavailable
+		},
+	}
+	if got := run(h, validAttrs); got != 422 {
+		t.Fatalf("expected 422 validation error, got %d", got)
+	}
+
+	h.after = &afterServiceMock{
+		upsertFn: func(context.Context, []byte, *afterflightinspection.UpsertRequest) (*afterflightinspection.AfterFlightInspection, error) {
+			return nil, errors.New("upsert fail")
+		},
+	}
+	if got := run(h, validAttrs); got != 400 {
+		t.Fatalf("expected 400 generic upsert error, got %d", got)
+	}
+
+	h.after = &afterServiceMock{
+		upsertFn: func(context.Context, []byte, *afterflightinspection.UpsertRequest) (*afterflightinspection.AfterFlightInspection, error) {
+			return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+		},
+	}
+	h.inspect = &inspectionServiceMock{
+		getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+			return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Now().UTC()}, nil
+		},
+	}
+	h.fileCk = fileChecklistServiceMock{
+		listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return nil, errors.New("ck list fail")
+		},
+	}
+	if got := run(h, validAttrs); got != 400 {
+		t.Fatalf("expected 400 checklist section error, got %d", got)
+	}
+}
+
+func TestReserveAcHandler_DeleteChecklistSectionBranches(t *testing.T) {
+	inspectionID := uuidv7.MustBytes()
+	aircraftID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+
+	h := NewReserveAcHandler(&reserveAcServiceMock{})
+	h.heliFile = heliFileServiceMock{
+		listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+			return nil, errors.New("template error")
+		},
+	}
+	h.fileCk = fileChecklistServiceMock{}
+
+	app := fiber.New()
+	app.Get("/d", func(c *fiber.Ctx) error {
+		return h.deleteInspectionFileChecklistSection(c, inspectionID, aircraftID, helicopterfile.SectionAfterLastFlightInspection)
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/d", nil)
+	res, _ := app.Test(req)
+	if res.StatusCode != 500 {
+		t.Fatalf("expected 500 when template list error bubbles, got %d", res.StatusCode)
+	}
+
+	h.heliFile = heliFileServiceMock{
+		listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+			return []helicopterfile.HelicopterFile{{ID: fileID}}, nil
+		},
+	}
+	h.fileCk = fileChecklistServiceMock{
+		listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return nil, errors.New("existing error")
+		},
+	}
+	req, _ = http.NewRequest(http.MethodGet, "/d", nil)
+	res, _ = app.Test(req)
+	if res.StatusCode != 500 {
+		t.Fatalf("expected 500 when existing list error bubbles, got %d", res.StatusCode)
+	}
+
+	h.fileCk = fileChecklistServiceMock{
+		listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return []flightinspectionfilechecklist.FlightInspectionFileChecklist{{ID: uuidv7.MustBytes(), HelicopterFileID: fileID}}, nil
+		},
+		deleteFn: func(context.Context, []byte) error { return errors.New("delete fail") },
+	}
+	req, _ = http.NewRequest(http.MethodGet, "/d", nil)
+	res, _ = app.Test(req)
+	if res.StatusCode != 500 {
+		t.Fatalf("expected 500 when delete error bubbles, got %d", res.StatusCode)
+	}
+}
+
+func TestReserveAcHandler_CreateLateBranchesAndValidation(t *testing.T) {
+	heliID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	rowID := uuidv7.MustBytes()
+	fileBefore := uuidv7.MustBytes()
+	filePrepare := uuidv7.MustBytes()
+	heliStr, _ := uuidv7.BytesToString(heliID)
+	flightStr, _ := uuidv7.BytesToString(flightID)
+	fileBeforeStr, _ := uuidv7.BytesToString(fileBefore)
+	filePrepareStr, _ := uuidv7.BytesToString(filePrepare)
+
+	validBody := `{"data":{"type":"reserve_ac_create","attributes":{"helicopter_id":"` + heliStr + `","flight_id":"` + flightStr + `","inspection":{"inspection_date":"2026-05-06","before":{"fuel_amount":1,"file_checklist":[{"helicopter_file_id":"` + fileBeforeStr + `","is_done":true}]},"prepare":{"notam_briefing":true,"file_checklist":[{"helicopter_file_id":"` + filePrepareStr + `","is_done":true}]}}}}}`
+
+	run := func(h *ReserveAcHandler, body string) int {
+		app := fiber.New()
+		app.Post("/create", h.Create)
+		req, _ := http.NewRequest(http.MethodPost, "/create", strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		res, err := app.Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return res.StatusCode
+	}
+
+	t.Run("validate struct error", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{})
+		if got := run(h, `{"data":{"type":"reserve_ac_create","attributes":{}}}`); got != 422 {
+			t.Fatalf("expected 422 got %d", got)
+		}
+	})
+
+	newFullHandler := func() *ReserveAcHandler {
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			createFn: func(context.Context, *reserveac.ReserveAc) error { return nil },
+			updateFn: func(context.Context, *reserveac.ReserveAc) error { return nil },
+			getByIDFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+				return &reserveac.ReserveAc{ID: rowID, AircraftID: heliID, InspectionID: inspectionID, Status: reserveac.StatusPending, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+			aircraftExistsFn: func(context.Context, []byte) (bool, error) { return true, nil },
+		})
+		h.flight = &reserveFlightServiceMock{
+			getByIDFn: func(context.Context, []byte) (*flight.Flight, error) { return &flight.Flight{ID: flightID}, nil },
+			updateFn:  func(context.Context, *flight.Flight) error { return nil },
+		}
+		h.inspect = &inspectionServiceMock{
+			createDraftFn: func(context.Context, *flightinspection.FlightInspection) error { return nil },
+			getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+				return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Now().UTC()}, nil
+			},
+		}
+		h.before = beforeServiceFnMock{
+			upsertFn: func(context.Context, []byte, *beforeflightinspection.UpsertRequest) (*beforeflightinspection.BeforeFlightInspection, error) {
+				return &beforeflightinspection.BeforeFlightInspection{}, nil
+			},
+		}
+		h.prep = prepServiceFnMock{
+			initFn: func(context.Context, []byte) (int, error) {
+				return 1, nil
+			},
+			upsertFn: func(context.Context, []byte, *flightprepcheck.UpsertRequest) (*flightprepcheck.FlightPrepCheck, error) {
+				return &flightprepcheck.FlightPrepCheck{NOTAMBriefing: true, WeatherBriefing: true, OperationalFlightPlan: true}, nil
+			},
+		}
+		h.heliFile = heliFileServiceMock{
+			listBySectionFn: func(_ context.Context, _ []byte, section string) ([]helicopterfile.HelicopterFile, error) {
+				switch section {
+				case helicopterfile.SectionBeforeFirstFlightInspection:
+					return []helicopterfile.HelicopterFile{{ID: fileBefore}}, nil
+				case helicopterfile.SectionFlightPreparationAndWB:
+					return []helicopterfile.HelicopterFile{{ID: filePrepare}}, nil
+				default:
+					return nil, nil
+				}
+			},
+		}
+		h.fileCk = fileChecklistServiceMock{
+			listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+				return nil, nil
+			},
+			createFn: func(context.Context, *flightinspectionfilechecklist.FlightInspectionFileChecklist) error { return nil },
+			updateFn: func(context.Context, *flightinspectionfilechecklist.FlightInspectionFileChecklist) error { return nil },
+		}
+		return h
+	}
+
+	t.Run("before checklist upsert error", func(t *testing.T) {
+		h := newFullHandler()
+		badBefore := `{"data":{"type":"reserve_ac_create","attributes":{"helicopter_id":"` + heliStr + `","flight_id":"` + flightStr + `","inspection":{"inspection_date":"2026-05-06","before":{"fuel_amount":1,"file_checklist":[{"helicopter_file_id":"bad","is_done":true}]},"prepare":{"notam_briefing":true}}}}}`
+		var parsed requestdto.ReserveAcCreateRequest
+		if err := json.Unmarshal([]byte(badBefore), &parsed); err != nil {
+			t.Fatal(err)
+		}
+		if len(parsed.Data.Attributes.Inspection.Before.FileChecklist) == 0 {
+			t.Fatal("expected before checklist parsed")
+		}
+		if got := run(h, badBefore); got != 422 {
+			t.Fatalf("expected 422 got %d", got)
+		}
+	})
+
+	t.Run("prepare checklist upsert error", func(t *testing.T) {
+		h := newFullHandler()
+		badPrepare := `{"data":{"type":"reserve_ac_create","attributes":{"helicopter_id":"` + heliStr + `","flight_id":"` + flightStr + `","inspection":{"inspection_date":"2026-05-06","before":{"fuel_amount":1,"file_checklist":[{"helicopter_file_id":"` + fileBeforeStr + `","is_done":true}]},"prepare":{"notam_briefing":true,"file_checklist":[{"helicopter_file_id":"bad","is_done":true}]}}}}}`
+		var parsed requestdto.ReserveAcCreateRequest
+		if err := json.Unmarshal([]byte(badPrepare), &parsed); err != nil {
+			t.Fatal(err)
+		}
+		if len(parsed.Data.Attributes.Inspection.Prepare.FileChecklist) == 0 {
+			t.Fatal("expected prepare checklist parsed")
+		}
+		if got := run(h, badPrepare); got != 422 {
+			t.Fatalf("expected 422 got %d", got)
+		}
+	})
+
+	t.Run("svc update failed after status compute", func(t *testing.T) {
+		h := newFullHandler()
+		h.svc = &reserveAcServiceMock{
+			createFn:          func(context.Context, *reserveac.ReserveAc) error { return nil },
+			updateFn:          func(context.Context, *reserveac.ReserveAc) error { return errors.New("update fail") },
+			getByIDFn:         func(context.Context, []byte) (*reserveac.ReserveAc, error) { return nil, nil },
+			aircraftExistsFn:  func(context.Context, []byte) (bool, error) { return true, nil },
+			getActiveByInspFn: nil,
+		}
+		if got := run(h, validBody); got != 400 {
+			t.Fatalf("expected 400 got %d", got)
+		}
+	})
+
+	t.Run("created row preferred and fallback row", func(t *testing.T) {
+		h := newFullHandler()
+		if got := run(h, validBody); got != 201 {
+			t.Fatalf("expected 201 got %d", got)
+		}
+
+		h = newFullHandler()
+		h.svc = &reserveAcServiceMock{
+			createFn: func(context.Context, *reserveac.ReserveAc) error { return nil },
+			updateFn: func(context.Context, *reserveac.ReserveAc) error { return nil },
+			getByIDFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+				return nil, errors.New("not found created")
+			},
+			aircraftExistsFn: func(context.Context, []byte) (bool, error) { return true, nil },
+		}
+		if got := run(h, validBody); got != 201 {
+			t.Fatalf("expected 201 got %d", got)
+		}
+	})
+}
+
+func TestReserveAcHandler_WrapperAndHelperBranches(t *testing.T) {
+	t.Run("upsert wrapper reaches delegation", func(t *testing.T) {
+		inspectionID := uuidv7.MustBytes()
+		inspectionIDStr, _ := uuidv7.BytesToString(inspectionID)
+		aircraftID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		fileIDStr, _ := uuidv7.BytesToString(fileID)
+
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+				return &reserveac.ReserveAc{ID: uuidv7.MustBytes(), AircraftID: aircraftID, InspectionID: inspectionID, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		})
+		h.after = &afterServiceMock{
+			upsertFn: func(context.Context, []byte, *afterflightinspection.UpsertRequest) (*afterflightinspection.AfterFlightInspection, error) {
+				return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		}
+		h.inspect = &inspectionServiceMock{getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+			return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Now().UTC()}, nil
+		}}
+		h.heliFile = heliFileServiceMock{listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+			return []helicopterfile.HelicopterFile{{ID: fileID}}, nil
+		}}
+		h.fileCk = fileChecklistServiceMock{listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return nil, nil
+		}}
+		app := fiber.New()
+		app.Post("/upsert/:inspection_id", h.UpsertAfterFlightInspection)
+		body := `{"data":{"type":"after_flight_inspection_upsert","attributes":{"file_checklist":[{"helicopter_file_id":"` + fileIDStr + `","is_done":true}]}}}`
+		req, _ := http.NewRequest(http.MethodPost, "/upsert/"+inspectionIDStr, strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ := app.Test(req)
+		if res.StatusCode != 200 {
+			t.Fatalf("expected 200 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("get-last delegates success", func(t *testing.T) {
+		inspectionID := uuidv7.MustBytes()
+		inspectionIDStr, _ := uuidv7.BytesToString(inspectionID)
+		aircraftID := uuidv7.MustBytes()
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+				return &reserveac.ReserveAc{ID: uuidv7.MustBytes(), AircraftID: aircraftID, InspectionID: inspectionID, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		})
+		h.after = &afterServiceMock{getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+			return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+		}}
+		h.inspect = &inspectionServiceMock{getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+			return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Now().UTC()}, nil
+		}}
+		h.heliFile = heliFileServiceMock{listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) { return nil, nil }}
+		h.fileCk = fileChecklistServiceMock{listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return nil, nil
+		}}
+		app := fiber.New()
+		app.Get("/get-last", h.GetLastFlightsInspection)
+		req, _ := http.NewRequest(http.MethodGet, "/get-last?inspection_id="+inspectionIDStr, nil)
+		res, _ := app.Test(req)
+		if res.StatusCode != 200 {
+			t.Fatalf("expected 200 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("create/update/delete last service error branches", func(t *testing.T) {
+		inspectionID := uuidv7.MustBytes()
+		inspectionIDStr, _ := uuidv7.BytesToString(inspectionID)
+		app := fiber.New()
+
+		// CreateLast validation errs path + existing duplicate
+		h := NewReserveAcHandler(&reserveAcServiceMock{})
+		h.after = &afterServiceMock{getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+			return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes()}, nil
+		}}
+		app.Post("/create-last", h.CreateLastFlightsInspection)
+		req, _ := http.NewRequest(http.MethodPost, "/create-last", strings.NewReader(`{"data":{"type":"last_flights_inspection_create","attributes":{"flight_inspection_id":"`+inspectionIDStr+`"}}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ := app.Test(req)
+		if res.StatusCode != 422 {
+			t.Fatalf("expected 422 got %d", res.StatusCode)
+		}
+
+		// UpdateLast get error branch
+		h = NewReserveAcHandler(&reserveAcServiceMock{})
+		h.after = &afterServiceMock{getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+			return nil, errors.New("get failed")
+		}}
+		app.Patch("/update-last2", h.UpdateLastFlightsInspection)
+		req, _ = http.NewRequest(http.MethodPatch, "/update-last2", strings.NewReader(`{"data":{"type":"last_flights_inspection_update","attributes":{"flight_inspection_id":"`+inspectionIDStr+`"}}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ = app.Test(req)
+		if res.StatusCode != 400 {
+			t.Fatalf("expected 400 got %d", res.StatusCode)
+		}
+
+		// DeleteLast downstream branches
+		h = NewReserveAcHandler(&reserveAcServiceMock{
+			getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+				return &reserveac.ReserveAc{ID: uuidv7.MustBytes(), AircraftID: uuidv7.MustBytes(), InspectionID: inspectionID, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		})
+		h.after = &afterServiceMock{
+			getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+				return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+			delFn: func(context.Context, []byte) error { return nil },
+		}
+		h.heliFile = heliFileServiceMock{listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+			return []helicopterfile.HelicopterFile{{ID: uuidv7.MustBytes()}}, nil
+		}}
+		h.fileCk = fileChecklistServiceMock{
+			listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+				return []flightinspectionfilechecklist.FlightInspectionFileChecklist{}, nil
+			},
+			deleteFn: func(context.Context, []byte) error { return nil },
+		}
+		app.Delete("/delete-last2", h.DeleteLastFlightsInspection)
+		req, _ = http.NewRequest(http.MethodDelete, "/delete-last2", strings.NewReader(`{"data":{"type":"last_flights_inspection_delete","attributes":{"flight_inspection_id":"`+inspectionIDStr+`"}}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ = app.Test(req)
+		if res.StatusCode != 200 {
+			t.Fatalf("expected 200 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("create-last rejects incomplete mission flight data", func(t *testing.T) {
+		inspectionID := uuidv7.MustBytes()
+		inspectionIDStr, _ := uuidv7.BytesToString(inspectionID)
+		reserveID := uuidv7.MustBytes()
+		flightID := uuidv7.MustBytes()
+		completeMissionID := uuidv7.MustBytes()
+		incompleteMissionID := uuidv7.MustBytes()
+		completeFlightDataID := uuidv7.MustBytes()
+		incompleteFlightDataID := uuidv7.MustBytes()
+
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+				return &reserveac.ReserveAc{ID: reserveID, AircraftID: uuidv7.MustBytes(), InspectionID: inspectionID}, nil
+			},
+		})
+		h.flight = &reserveFlightServiceMock{
+			getByReserveAcFn: func(context.Context, []byte) (*flight.Flight, error) {
+				return &flight.Flight{ID: flightID}, nil
+			},
+		}
+		h.mission = reserveMissionServiceMock{
+			listByFlightIDFn: func(context.Context, []byte) ([]mission.Mission, error) {
+				return []mission.Mission{
+					{ID: completeMissionID, FlightDataID: completeFlightDataID, Type: "CAT"},
+					{ID: incompleteMissionID, FlightDataID: incompleteFlightDataID, Type: "CAT"},
+				}, nil
+			},
+		}
+		h.flightData = reserveFlightDataServiceMock{
+			getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+				switch {
+				case bytes.Equal(id, completeFlightDataID):
+					takeoff := time.Date(2026, 6, 15, 8, 0, 0, 0, time.UTC)
+					landing := takeoff.Add(10 * time.Minute)
+					return &flightdata.FlightData{
+						ID:              completeFlightDataID,
+						MissionID:       completeMissionID,
+						CoPilotID:       uuidv7.MustBytes(),
+						FromHospitalID:  uuidv7.MustBytes(),
+						ToHospitalID:    uuidv7.MustBytes(),
+						FlightTakeOff:   takeoff,
+						FlightLanding:   landing,
+						FlightDuration:  10 * time.Minute,
+						LandingCount:    1,
+						RotorBrakeCycle: 1,
+						Status:          flightdata.StatusCompleted,
+						Mission:         &mission.Mission{Type: "CAT"},
+					}, nil
+				case bytes.Equal(id, incompleteFlightDataID):
+					takeoff := time.Date(2026, 6, 15, 8, 30, 0, 0, time.UTC)
+					landing := takeoff.Add(10 * time.Minute)
+					return &flightdata.FlightData{
+						ID:             incompleteFlightDataID,
+						MissionID:      incompleteMissionID,
+						CoPilotID:      uuidv7.MustBytes(),
+						FromHospitalID: uuidv7.MustBytes(),
+						ToHospitalID:   uuidv7.MustBytes(),
+						FlightTakeOff:  takeoff,
+						FlightLanding:  landing,
+						FlightDuration: 10 * time.Minute,
+						// incomplete on purpose
+						Status:  flightdata.StatusInProgress,
+						Mission: &mission.Mission{Type: "CAT"},
+					}, nil
+				default:
+					return nil, nil
+				}
+			},
+		}
+		h.after = &afterServiceMock{}
+		h.inspect = &inspectionServiceMock{getByIDFn: func(context.Context, []byte) (*flightinspection.FlightInspection, error) {
+			return &flightinspection.FlightInspection{ID: inspectionID, InspectionDate: time.Now().UTC()}, nil
+		}}
+		h.heliFile = heliFileServiceMock{listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+			return []helicopterfile.HelicopterFile{{ID: uuidv7.MustBytes()}}, nil
+		}}
+		h.fileCk = fileChecklistServiceMock{listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+			return nil, nil
+		}}
+
+		app := fiber.New()
+		app.Post("/create-last", h.CreateLastFlightsInspection)
+		body := `{"data":{"type":"last_flights_inspection_create","attributes":{"flight_inspection_id":"` + inspectionIDStr + `"}}}`
+		req, _ := http.NewRequest(http.MethodPost, "/create-last", strings.NewReader(body))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ := app.Test(req)
+		if res.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422 got %d", res.StatusCode)
+		}
+		bodyBytes, _ := io.ReadAll(res.Body)
+		bodyStr := string(bodyBytes)
+		if !strings.Contains(bodyStr, "cannot submit after-flight: mission") {
+			t.Fatalf("expected detailed after-flight validation message, got %s", bodyStr)
+		}
+		if !strings.Contains(bodyStr, `"code":"FLIGHT_DATA_AFTER_FLIGHT_INCOMPLETE"`) {
+			t.Fatalf("expected flight data error code, got %s", bodyStr)
+		}
+		if !strings.Contains(bodyStr, `"error_code":"4222616"`) {
+			t.Fatalf("expected flight data error code id, got %s", bodyStr)
+		}
+	})
+
+	t.Run("helper branches for before payload and summaries", func(t *testing.T) {
+		if !hasReserveAcBeforePayload(requestdto.ReserveAcBeforeInspectionAttributes{OilTransmissionMGBChecked: ptrBool(true)}) {
+			t.Fatal("expected transmission payload true")
+		}
+		if !hasReserveAcBeforePayload(requestdto.ReserveAcBeforeInspectionAttributes{FuelAddedAmount: ptrFloat(1)}) {
+			t.Fatal("expected fuel_added payload true")
+		}
+
+		h := NewReserveAcHandler(&reserveAcServiceMock{}).WithFileStorage(fileStorageMock{})
+		app := fiber.New()
+		app.Get("/x", func(c *fiber.Ctx) error {
+			file := &filemanager.File{ID: uuidv7.MustBytes(), Name: " doc.pdf ", Bucket: "b", ObjectKey: "k"}
+			att := &filemanager.Attachment{ID: uuidv7.MustBytes(), File: file}
+			files := []helicopterfile.HelicopterFile{
+				{ID: uuidv7.MustBytes(), FileAttachment: att},
+				{ID: uuidv7.MustBytes()},
+			}
+			out := h.buildChecklistSectionSummary(c, files, map[string]bool{idString(files[0].ID): true})
+			if out.Completed != 1 || len(out.DoneFiles) != 1 || out.FileChecklist[0].DownloadURL == "" {
+				t.Fatal("expected checklist with done + download url")
+			}
+			payload := afterFlightInspectionPayload(uuidv7.MustBytes(), nil, nil, nil, reserveAcChecklistSectionCommon{Total: 0, Completed: 0}, nil)
+			if payload.Data.Attributes.Total != 0 {
+				t.Fatal("expected zero total")
+			}
+			return c.SendStatus(200)
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/x", nil)
+		res, err := app.Test(req)
+		if err != nil || res.StatusCode != 200 {
+			t.Fatalf("expected 200 got err=%v code=%d", err, res.StatusCode)
+		}
+	})
+
+	t.Run("load mission flight data prefers latest mission row", func(t *testing.T) {
+		missionID := uuidv7.MustBytes()
+		staleFlightDataID := uuidv7.MustBytes()
+		latestFlightDataID := uuidv7.MustBytes()
+
+		h := NewReserveAcHandler(&reserveAcServiceMock{})
+		h.flightData = reserveFlightDataServiceMock{
+			getByIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+				if bytes.Equal(id, staleFlightDataID) {
+					return &flightdata.FlightData{
+						ID:        staleFlightDataID,
+						MissionID: missionID,
+						Status:    flightdata.StatusInProgress,
+						Mission:   &mission.Mission{Type: "CAT"},
+					}, nil
+				}
+				return nil, nil
+			},
+			getByMissionIDFn: func(_ context.Context, id []byte) (*flightdata.FlightData, error) {
+				if bytes.Equal(id, missionID) {
+					return &flightdata.FlightData{
+						ID:        latestFlightDataID,
+						MissionID: missionID,
+						Status:    flightdata.StatusCompleted,
+						Mission:   &mission.Mission{Type: "CAT"},
+					}, nil
+				}
+				return nil, nil
+			},
+		}
+
+		fd, ok := h.loadMissionFlightData(context.Background(), mission.Mission{ID: missionID, FlightDataID: staleFlightDataID, Type: "CAT"})
+		if !ok {
+			t.Fatal("expected flight data to be found")
+		}
+		if fd == nil || !bytes.Equal(fd.ID, latestFlightDataID) {
+			t.Fatalf("expected latest mission row, got %+v", fd)
+		}
+		if !flightdata.IsComplete(fd) {
+			t.Fatalf("expected latest mission row to be complete, got %+v", fd)
+		}
+	})
+}
+
+func TestReserveAcHandler_LastInspectionAndListMoreBranches(t *testing.T) {
+	inspectionID := uuidv7.MustBytes()
+	inspectionIDStr, _ := uuidv7.BytesToString(inspectionID)
+
+	t.Run("create-last get existing error", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{})
+		h.after = &afterServiceMock{
+			getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+				return nil, errors.New("err")
+			},
+		}
+		app := fiber.New()
+		app.Post("/create-last", h.CreateLastFlightsInspection)
+		req, _ := http.NewRequest(http.MethodPost, "/create-last", strings.NewReader(`{"data":{"type":"last_flights_inspection_create","attributes":{"flight_inspection_id":"`+inspectionIDStr+`"}}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ := app.Test(req)
+		if res.StatusCode != 400 {
+			t.Fatalf("expected 400 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("update-last validation error", func(t *testing.T) {
+		h := NewReserveAcHandler(&reserveAcServiceMock{})
+		h.after = &afterServiceMock{}
+		app := fiber.New()
+		app.Patch("/update-last", h.UpdateLastFlightsInspection)
+		req, _ := http.NewRequest(http.MethodPatch, "/update-last", strings.NewReader(`{"data":{"type":"wrong","attributes":{"flight_inspection_id":"`+inspectionIDStr+`"}}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ := app.Test(req)
+		if res.StatusCode != 422 {
+			t.Fatalf("expected 422 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("delete-last full error matrix", func(t *testing.T) {
+		aircraftID := uuidv7.MustBytes()
+		fileID := uuidv7.MustBytes()
+		app := fiber.New()
+
+		// existing fetch error
+		h := NewReserveAcHandler(&reserveAcServiceMock{})
+		h.after = &afterServiceMock{
+			getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+				return nil, errors.New("get err")
+			},
+		}
+		h.heliFile = heliFileServiceMock{}
+		h.fileCk = fileChecklistServiceMock{}
+		app.Delete("/d1", h.DeleteLastFlightsInspection)
+		req, _ := http.NewRequest(http.MethodDelete, "/d1", strings.NewReader(`{"data":{"type":"last_flights_inspection_delete","attributes":{"flight_inspection_id":"`+inspectionIDStr+`"}}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ := app.Test(req)
+		if res.StatusCode != 400 {
+			t.Fatalf("expected 400 got %d", res.StatusCode)
+		}
+
+		// existing not found
+		h = NewReserveAcHandler(&reserveAcServiceMock{})
+		h.after = &afterServiceMock{getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) { return nil, nil }}
+		h.heliFile = heliFileServiceMock{}
+		h.fileCk = fileChecklistServiceMock{}
+		app.Delete("/d2", h.DeleteLastFlightsInspection)
+		req, _ = http.NewRequest(http.MethodDelete, "/d2", strings.NewReader(`{"data":{"type":"last_flights_inspection_delete","attributes":{"flight_inspection_id":"`+inspectionIDStr+`"}}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ = app.Test(req)
+		if res.StatusCode != 404 {
+			t.Fatalf("expected 404 got %d", res.StatusCode)
+		}
+
+		// get active error and nil
+		h = NewReserveAcHandler(&reserveAcServiceMock{
+			getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) { return nil, errors.New("active err") },
+		})
+		h.after = &afterServiceMock{getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+			return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+		}}
+		h.heliFile = heliFileServiceMock{}
+		h.fileCk = fileChecklistServiceMock{}
+		app.Delete("/d3", h.DeleteLastFlightsInspection)
+		req, _ = http.NewRequest(http.MethodDelete, "/d3", strings.NewReader(`{"data":{"type":"last_flights_inspection_delete","attributes":{"flight_inspection_id":"`+inspectionIDStr+`"}}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ = app.Test(req)
+		if res.StatusCode != 400 {
+			t.Fatalf("expected 400 got %d", res.StatusCode)
+		}
+
+		h = NewReserveAcHandler(&reserveAcServiceMock{
+			getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) { return nil, nil },
+		})
+		h.after = &afterServiceMock{getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+			return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+		}}
+		h.heliFile = heliFileServiceMock{}
+		h.fileCk = fileChecklistServiceMock{}
+		app.Delete("/d4", h.DeleteLastFlightsInspection)
+		req, _ = http.NewRequest(http.MethodDelete, "/d4", strings.NewReader(`{"data":{"type":"last_flights_inspection_delete","attributes":{"flight_inspection_id":"`+inspectionIDStr+`"}}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ = app.Test(req)
+		if res.StatusCode != 404 {
+			t.Fatalf("expected 404 got %d", res.StatusCode)
+		}
+
+		// delete checklist error
+		h = NewReserveAcHandler(&reserveAcServiceMock{
+			getActiveByInspFn: func(context.Context, []byte) (*reserveac.ReserveAc, error) {
+				return &reserveac.ReserveAc{ID: uuidv7.MustBytes(), AircraftID: aircraftID, InspectionID: inspectionID, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+		})
+		h.after = &afterServiceMock{
+			getFn: func(context.Context, []byte) (*afterflightinspection.AfterFlightInspection, error) {
+				return &afterflightinspection.AfterFlightInspection{ID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}, nil
+			},
+			delFn: func(context.Context, []byte) error { return nil },
+		}
+		h.heliFile = heliFileServiceMock{
+			listBySectionFn: func(context.Context, []byte, string) ([]helicopterfile.HelicopterFile, error) {
+				return []helicopterfile.HelicopterFile{{ID: fileID}}, nil
+			},
+		}
+		h.fileCk = fileChecklistServiceMock{
+			listByInspectionFn: func(context.Context, []byte) ([]flightinspectionfilechecklist.FlightInspectionFileChecklist, error) {
+				return []flightinspectionfilechecklist.FlightInspectionFileChecklist{{ID: uuidv7.MustBytes(), HelicopterFileID: fileID}}, nil
+			},
+			deleteFn: func(context.Context, []byte) error { return errors.New("delete ck fail") },
+		}
+		app.Delete("/d5", h.DeleteLastFlightsInspection)
+		req, _ = http.NewRequest(http.MethodDelete, "/d5", strings.NewReader(`{"data":{"type":"last_flights_inspection_delete","attributes":{"flight_inspection_id":"`+inspectionIDStr+`"}}}`))
+		req.Header.Set("Content-Type", "application/json")
+		res, _ = app.Test(req)
+		if res.StatusCode != 400 {
+			t.Fatalf("expected 400 got %d", res.StatusCode)
+		}
+	})
+
+	t.Run("list fallback branches", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		aircraftID := uuidv7.MustBytes()
+		h := NewReserveAcHandler(&reserveAcServiceMock{
+			listFn: func(context.Context, string, string, int, int) ([]reserveac.ReserveAc, int64, error) {
+				return []reserveac.ReserveAc{{ID: id, AircraftID: aircraftID, InspectionID: uuidv7.MustBytes(), CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}}, 1, nil
+			},
+		})
+		// leave h.flight nil and other deps nil to hit guard branches
+		app := fiber.New()
+		app.Get("/list", h.List)
+		req, _ := http.NewRequest(http.MethodGet, "/list?page[number]=-10&page[size]=-1", nil)
+		res, _ := app.Test(req)
+		if res.StatusCode != 401 {
+			t.Fatalf("expected 401 got %d", res.StatusCode)
+		}
+	})
+}
diff --git a/internal/transport/http/handlers/role_handler.go b/internal/transport/http/handlers/role_handler.go
new file mode 100644
index 0000000..1cb299c
--- /dev/null
+++ b/internal/transport/http/handlers/role_handler.go
@@ -0,0 +1,1029 @@
+package handlers
+
+import (
+	"errors"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type RoleHandler struct {
+	svc      *service.RoleService
+	validate *validators.Validator
+}
+
+func NewRoleHandler(svc *service.RoleService) *RoleHandler {
+	return &RoleHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateRole godoc
+// @Summary Create role
+// @Description Create a new role. Name is required and must be unique.
+// @Tags Roles
+// @Accept json
+// @Produce json
+// @Param request body dto.RoleCreateRequest true "JSON:API Role create request"
+// @Success 201 {object} dto.RoleResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/roles/create [post]
+func (h *RoleHandler) Create(c *fiber.Ctx) error {
+	var req dto.RoleCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	role := &auth.Role{
+		Name:        strings.TrimSpace(req.Data.Attributes.Name),
+		Description: strings.TrimSpace(req.Data.Attributes.Description),
+		CreatedBy:   actorUserID(c),
+	}
+
+	if err := h.svc.Create(c.UserContext(), role); err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusCreated, roleResource(role))
+}
+
+// UpdateRole godoc
+// @Summary Update role (partial)
+// @Description Patch role by ID. Provide at least one of: name, description. Name must be unique if provided.
+// @Tags Roles
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Role UUID (UUIDv7)"
+// @Param request body dto.RoleUpdateRequest true "JSON:API Role update request"
+// @Success 200 {object} dto.RoleResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/roles/update/{uuid} [patch]
+func (h *RoleHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	roleID, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.RoleUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	if req.Data.Attributes.Name == nil && req.Data.Attributes.Description == nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), roleID)
+	if err != nil || existing == nil {
+		return writeRoleErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "role not found",
+		}})
+	}
+
+	if req.Data.Attributes.Name != nil {
+		name := strings.TrimSpace(*req.Data.Attributes.Name)
+		if name == "" {
+			return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+			}})
+		}
+		existing.Name = name
+	}
+	if req.Data.Attributes.Description != nil {
+		existing.Description = strings.TrimSpace(*req.Data.Attributes.Description)
+	}
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, roleResource(existing))
+}
+
+// DeleteRole godoc
+// @Summary Delete role
+// @Tags Roles
+// @Produce json
+// @Param uuid path string true "Role UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/roles/delete/{uuid} [delete]
+func (h *RoleHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	roleID, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), roleID); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeRoleErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "role not found",
+			}})
+		}
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "role_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// AssignPermission godoc
+// @Summary Assign permission to role
+// @Description Assign one permission to a role. Idempotent if already assigned.
+// @Tags Roles
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Role UUID (UUIDv7)"
+// @Param request body dto.RolePermissionAssignRequest true "JSON:API role permission assign request"
+// @Success 200 {object} dto.RolePermissionResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/roles/{uuid}/permissions [post]
+func (h *RoleHandler) AssignPermission(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	roleID, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.RolePermissionAssignRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	permissionID, err := uuidv7.ParseString(strings.TrimSpace(req.Data.Attributes.PermissionID))
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "permission_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/permission_id"},
+		}})
+	}
+
+	role, err := h.svc.GetByID(c.UserContext(), roleID)
+	if err != nil || role == nil {
+		return writeRoleErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "role not found",
+		}})
+	}
+
+	perm, err := h.svc.GetPermissionByID(c.UserContext(), permissionID)
+	if err != nil || perm == nil {
+		return writeRoleErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "permission not found",
+		}})
+	}
+
+	rp, err := h.svc.AssignPermission(c.UserContext(), roleID, permissionID)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Assign failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, rolePermissionResource(rp))
+}
+
+// RemovePermission godoc
+// @Summary Remove permission from role
+// @Description Remove one permission from role.
+// @Tags Roles
+// @Produce json
+// @Param uuid path string true "Role UUID (UUIDv7)"
+// @Param permission_uuid path string true "Permission UUID (UUIDv7)"
+// @Success 200 {object} dto.RolePermissionResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/roles/{uuid}/permissions/{permission_uuid} [delete]
+func (h *RoleHandler) RemovePermission(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	roleID, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	permissionIDStr := c.Params("permission_uuid")
+	permissionID, err := uuidv7.ParseString(permissionIDStr)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "permission_uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/permission_uuid"},
+		}})
+	}
+
+	role, err := h.svc.GetByID(c.UserContext(), roleID)
+	if err != nil || role == nil {
+		return writeRoleErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "role not found",
+		}})
+	}
+
+	if err := h.svc.RemovePermission(c.UserContext(), roleID, permissionID); err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Remove failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	rp := &auth.RolePermission{
+		RoleID:       roleID,
+		PermissionID: permissionID,
+	}
+	return response.Write(c, fiber.StatusOK, rolePermissionResource(rp))
+}
+
+// AssignPermissionsBulk godoc
+// @Summary Assign permissions to role (bulk)
+// @Description Assign multiple permissions to role. Idempotent for duplicates/already assigned.
+// @Tags Roles
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Role UUID (UUIDv7)"
+// @Param request body dto.RolePermissionAssignBulkRequest true "JSON:API role permission bulk request"
+// @Success 200 {object} dto.RolePermissionListResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/roles/{uuid}/permissions/assign-bulk [post]
+func (h *RoleHandler) AssignPermissionsBulk(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	roleID, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.RolePermissionAssignBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if len(req.Data.Attributes.PermissionIDs) == 0 {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "permission_ids must not be empty",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/permission_ids"},
+		}})
+	}
+
+	role, err := h.svc.GetByID(c.UserContext(), roleID)
+	if err != nil || role == nil {
+		return writeRoleErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "role not found",
+		}})
+	}
+
+	seen := map[string]struct{}{}
+	out := make([]dto.RolePermissionResource, 0, len(req.Data.Attributes.PermissionIDs))
+	for i, raw := range req.Data.Attributes.PermissionIDs {
+		pidStr := strings.TrimSpace(raw)
+		if pidStr == "" {
+			return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "permission_id cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/permission_ids/" + parseIntToString(i)},
+			}})
+		}
+		if _, ok := seen[pidStr]; ok {
+			continue
+		}
+		seen[pidStr] = struct{}{}
+
+		permissionID, err := uuidv7.ParseString(pidStr)
+		if err != nil {
+			return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "permission_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/permission_ids/" + parseIntToString(i)},
+			}})
+		}
+
+		perm, err := h.svc.GetPermissionByID(c.UserContext(), permissionID)
+		if err != nil || perm == nil {
+			return writeRoleErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "permission not found",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/permission_ids/" + parseIntToString(i)},
+			}})
+		}
+
+		rp, err := h.svc.AssignPermission(c.UserContext(), roleID, permissionID)
+		if err != nil {
+			return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Assign failed",
+				Detail: safeInternalDetail(),
+			}})
+		}
+		out = append(out, rolePermissionResource(rp))
+	}
+
+	return response.Write(c, fiber.StatusOK, out)
+}
+
+// RemovePermissionsBulk godoc
+// @Summary Remove permissions from role (bulk)
+// @Description Remove multiple permissions from role.
+// @Tags Roles
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Role UUID (UUIDv7)"
+// @Param request body dto.RolePermissionRemoveBulkRequest true "JSON:API role permission bulk request"
+// @Success 200 {object} dto.RolePermissionListResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/roles/{uuid}/permissions/remove-bulk [post]
+func (h *RoleHandler) RemovePermissionsBulk(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	roleID, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.RolePermissionRemoveBulkRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if len(req.Data.Attributes.PermissionIDs) == 0 {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "permission_ids must not be empty",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/permission_ids"},
+		}})
+	}
+
+	role, err := h.svc.GetByID(c.UserContext(), roleID)
+	if err != nil || role == nil {
+		return writeRoleErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "role not found",
+		}})
+	}
+
+	seen := map[string]struct{}{}
+	out := make([]dto.RolePermissionResource, 0, len(req.Data.Attributes.PermissionIDs))
+	for i, raw := range req.Data.Attributes.PermissionIDs {
+		pidStr := strings.TrimSpace(raw)
+		if pidStr == "" {
+			return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "permission_id cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/permission_ids/" + parseIntToString(i)},
+			}})
+		}
+		if _, ok := seen[pidStr]; ok {
+			continue
+		}
+		seen[pidStr] = struct{}{}
+
+		permissionID, err := uuidv7.ParseString(pidStr)
+		if err != nil {
+			return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "permission_id is invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/permission_ids/" + parseIntToString(i)},
+			}})
+		}
+
+		if err := h.svc.RemovePermission(c.UserContext(), roleID, permissionID); err != nil {
+			return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Remove failed",
+				Detail: safeInternalDetail(),
+			}})
+		}
+
+		out = append(out, rolePermissionResource(&auth.RolePermission{
+			RoleID:       roleID,
+			PermissionID: permissionID,
+		}))
+	}
+
+	return response.Write(c, fiber.StatusOK, out)
+}
+
+// UpdatePermission godoc
+// @Summary Update permission
+// @Description Patch permission by ID. Currently supports updating requires_pin.
+// @Tags Roles
+// @Accept json
+// @Produce json
+// @Param permission_uuid path string true "Permission UUID (UUIDv7)"
+// @Param request body dto.PermissionUpdateRequest true "JSON:API permission update request"
+// @Success 200 {object} dto.PermissionResource
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/roles/permissions/{permission_uuid} [patch]
+func (h *RoleHandler) UpdatePermission(c *fiber.Ctx) error {
+	permissionUUID := c.Params("permission_uuid")
+	permissionID, err := uuidv7.ParseString(permissionUUID)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "permission_uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/permission_uuid"},
+		}})
+	}
+
+	var req dto.PermissionUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != permissionUUID {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path permission_uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.Attributes.RequiresPIN == nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "requires_pin is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/requires_pin"},
+		}})
+	}
+
+	perm, err := h.svc.GetPermissionByID(c.UserContext(), permissionID)
+	if err != nil || perm == nil {
+		return writeRoleErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "permission not found",
+		}})
+	}
+
+	perm.RequiresPIN = *req.Data.Attributes.RequiresPIN
+	if err := h.svc.UpdatePermission(c.UserContext(), perm); err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, permissionResource(perm))
+}
+
+// GetRoleByID godoc
+// @Summary Get role by ID
+// @Tags Roles
+// @Produce json
+// @Param uuid path string true "Role UUID (UUIDv7)"
+// @Success 200 {object} dto.RoleResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/roles/get/{uuid} [get]
+func (h *RoleHandler) GetByID(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	roleID, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	role, err := h.svc.GetByID(c.UserContext(), roleID)
+	if err != nil || role == nil {
+		return writeRoleErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "role not found",
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, roleResource(role))
+}
+
+// ListRolePermissions godoc
+// @Summary List a role's assigned permissions
+// @Description Returns the permissions currently assigned to the given role. Pair with /roles/permissions/get-all to pre-check a role-permission editor.
+// @Tags Roles
+// @Produce json
+// @Param uuid path string true "Role UUID (UUIDv7)"
+// @Success 200 {object} dto.PermissionListResponse
+// @Router /api/v1/roles/{uuid}/permissions [get]
+func (h *RoleHandler) ListRolePermissions(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	roleID, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	perms, err := h.svc.ListPermissionsByRoleID(c.UserContext(), roleID)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.PermissionResource, 0, len(perms))
+	for i := range perms {
+		data = append(data, permissionResource(&perms[i]))
+	}
+	return response.Write(c, fiber.StatusOK, data)
+}
+
+// ListPermissions godoc
+// @Summary List permissions grouped by module
+// @Description Returns every permission grouped by its module, ordered by the module registry. Optional filter[name] narrows by permission name/key.
+// @Tags Roles
+// @Produce json
+// @Param filter[name] query string false "Filter by name/key (contains)"
+// @Success 200 {object} dto.PermissionGroupedResponse
+// @Router /api/v1/roles/permissions/get-all [get]
+func (h *RoleHandler) ListPermissions(c *fiber.Ctx) error {
+	perms, _, err := h.svc.ListPermissions(c.UserContext(), c.Query("filter[name]"), "", 0, 0)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, groupPermissionsByModule(perms))
+}
+
+func groupPermissionsByModule(perms []auth.Permission) []dto.PermissionGroupResource {
+	byModule := make(map[string][]dto.PermissionResource)
+	for i := range perms {
+		module := perms[i].Module
+		if module == "" {
+			module = auth.ModuleForKey(perms[i].Key)
+		}
+		byModule[module] = append(byModule[module], permissionResource(&perms[i]))
+	}
+
+	modules := make([]string, 0, len(byModule))
+	for module := range byModule {
+		modules = append(modules, module)
+	}
+	sort.Slice(modules, func(i, j int) bool {
+		oi, oj := auth.ModuleSortIndex(modules[i]), auth.ModuleSortIndex(modules[j])
+		if oi != oj {
+			return oi < oj
+		}
+		return modules[i] < modules[j]
+	})
+
+	groups := make([]dto.PermissionGroupResource, 0, len(modules))
+	for _, module := range modules {
+		items := byModule[module]
+		sort.Slice(items, func(i, j int) bool {
+			return items[i].Attributes.Key < items[j].Attributes.Key
+		})
+		groups = append(groups, dto.PermissionGroupResource{
+			Module:      module,
+			ModuleLabel: auth.ModuleLabel(module),
+			Permissions: items,
+		})
+	}
+	return groups
+}
+
+// ListRoles godoc
+// @Summary List roles
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: name, -name, created_at, -created_at, updated_at, -updated_at.
+// @Tags Roles
+// @Produce json
+// @Param filter[name] query string false "Filter by name (contains)"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Param include query string false "Set to 'permissions' to embed each role's assigned permissions"
+// @Success 200 {object} dto.RoleListResponse
+// @Router /api/v1/roles/get-all [get]
+func (h *RoleHandler) List(c *fiber.Ctx) error {
+	filterName := c.Query("filter[name]")
+	pageNumber := parseIntDefault(c.Query("page[number]"), 1)
+	pageSize := parseIntDefault(c.Query("page[size]"), 20)
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	roles, total, err := h.svc.List(c.UserContext(), filterName, sort, 0, 0)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	withPermissions := strings.Contains(c.Query("include"), "permissions")
+
+	data := make([]dto.RoleResource, 0, len(roles))
+	for i := range roles {
+		res := roleResource(&roles[i])
+		if withPermissions {
+			perms, permErr := h.svc.ListPermissionsByRoleID(c.UserContext(), roles[i].ID)
+			if permErr != nil {
+				return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+					Status: "400",
+					Title:  "List failed",
+					Detail: safeInternalDetail(),
+				}})
+			}
+			res.Permissions = make([]dto.PermissionResource, 0, len(perms))
+			for j := range perms {
+				res.Permissions = append(res.Permissions, permissionResource(&perms[j]))
+			}
+		}
+		data = append(data, res)
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListRolesDatatable godoc
+// @Summary List roles (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags Roles
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.RoleDataTableResponse
+// @Router /api/v1/roles/get-all/dt [get]
+func (h *RoleHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	roles, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return writeRoleErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.RoleResource, 0, len(roles))
+	for i := range roles {
+		data = append(data, roleResource(&roles[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func roleResource(role *auth.Role) dto.RoleResource {
+	id, _ := uuidv7.BytesToString(role.ID)
+	return dto.RoleResource{
+		Type: "role",
+		ID:   id,
+		Attributes: dto.RoleAttributes{
+			Name:        role.Name,
+			Description: role.Description,
+			CreatedBy:   uuidStringOrEmpty(role.CreatedBy),
+			CreatedAt:   role.CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedAt:   role.UpdatedAt.UTC().Format(time.RFC3339),
+		},
+	}
+}
+
+func rolePermissionResource(rp *auth.RolePermission) dto.RolePermissionResource {
+	id, _ := uuidv7.BytesToString(rp.ID)
+	roleID, _ := uuidv7.BytesToString(rp.RoleID)
+	permissionID, _ := uuidv7.BytesToString(rp.PermissionID)
+	return dto.RolePermissionResource{
+		Type: "role_permission",
+		ID:   id,
+		Attributes: dto.RolePermissionAttributes{
+			RoleID:       roleID,
+			PermissionID: permissionID,
+		},
+	}
+}
+
+func permissionResource(permission *auth.Permission) dto.PermissionResource {
+	id, _ := uuidv7.BytesToString(permission.ID)
+	return dto.PermissionResource{
+		Type: "permission",
+		ID:   id,
+		Attributes: dto.PermissionAttributes{
+			Name:        permission.Name,
+			Key:         permission.Key,
+			Description: permission.Description,
+			RequiresPIN: permission.RequiresPIN,
+			CreatedAt:   permission.CreatedAt.UTC().Format(time.RFC3339),
+			UpdatedAt:   permission.UpdatedAt.UTC().Format(time.RFC3339),
+		},
+	}
+}
+
+func parseIntToString(i int) string {
+	if i == 0 {
+		return "0"
+	}
+	buf := make([]byte, 0, 12)
+	for i > 0 {
+		buf = append(buf, byte('0'+i%10))
+		i /= 10
+	}
+	for left, right := 0, len(buf)-1; left < right; left, right = left+1, right-1 {
+		buf[left], buf[right] = buf[right], buf[left]
+	}
+	return string(buf)
+}
+
+func writeRoleErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferRoleDef(status, e.Title, e.Detail)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		if strings.TrimSpace(e.Title) == "" {
+			e.Title = def.Title
+		}
+		e.Detail = def.Message
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferRoleDef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		if strings.Contains(lowerDetail, "permission not found") {
+			return apperrorsx.ErrRolePermissionNotFound
+		}
+		return apperrorsx.ErrRoleNotFound
+	case fiber.StatusConflict:
+		return apperrorsx.ErrRoleRelationDelete
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "permission_uuid is invalid"), strings.Contains(lowerDetail, "permission_id is invalid uuid"):
+			return apperrorsx.ErrRoleInvalidPermissionUUID
+		case strings.Contains(lowerDetail, "uuid is invalid"):
+			return apperrorsx.ErrRoleInvalidUUID
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.ErrRoleIDRequired
+		case strings.Contains(lowerDetail, "id does not match"):
+			return apperrorsx.ErrRoleIDMismatch
+		case strings.Contains(lowerDetail, "at least one attribute"):
+			return apperrorsx.ErrRoleAttributesRequired
+		case strings.Contains(lowerDetail, "name cannot be empty"):
+			return apperrorsx.ErrRoleNameRequired
+		case strings.Contains(lowerDetail, "permission_id cannot be empty"):
+			return apperrorsx.ErrRolePermissionIDRequired
+		case strings.Contains(lowerDetail, "permission_ids must not be empty"):
+			return apperrorsx.ErrRolePermissionIDsEmpty
+		case strings.Contains(lowerDetail, "requires_pin is required"):
+			return apperrorsx.ErrRolePermissionRequiresPINReq
+		default:
+			return apperrorsx.ErrRoleInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrRoleInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.ErrRoleCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrRoleUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrRoleDeleteFailed
+		case strings.Contains(lowerTitle, "assign failed"):
+			return apperrorsx.ErrRoleAssignFailed
+		case strings.Contains(lowerTitle, "remove failed"):
+			return apperrorsx.ErrRoleRemoveFailed
+		case strings.Contains(lowerTitle, "list failed"):
+			if strings.Contains(lowerDetail, "permission") {
+				return apperrorsx.ErrRolePermissionListFailed
+			}
+			return apperrorsx.ErrRoleListFailed
+		default:
+			if strings.Contains(lowerTitle, "update failed") && strings.Contains(lowerDetail, "permission") {
+				return apperrorsx.ErrRolePermissionUpdateFailed
+			}
+			return apperrorsx.ErrRoleInvalidPayload
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
+
+func inferRoleErrorCode(status int, title, detail string) (string, string) {
+	def := inferRoleDef(status, title, detail)
+	return def.Code, def.ErrorCode
+}
diff --git a/internal/transport/http/handlers/role_handler_test.go b/internal/transport/http/handlers/role_handler_test.go
new file mode 100644
index 0000000..1b87729
--- /dev/null
+++ b/internal/transport/http/handlers/role_handler_test.go
@@ -0,0 +1,1102 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/auth"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type memRoleRepo struct {
+	roles                map[string]*auth.Role
+	permissions          map[string]*auth.Permission
+	listRoles            []auth.Role
+	listTotal            int64
+	listErr              error
+	listPermissions      []auth.Permission
+	listPermissionsTotal int64
+	listPermissionsErr   error
+
+	createErr           error
+	updateErr           error
+	deleteErr           error
+	getByIDErr          error
+	getPermissionErr    error
+	permissionNotFound  bool
+	assignPermissionErr error
+	removePermissionErr error
+}
+
+func newMemRoleRepo() *memRoleRepo {
+	return &memRoleRepo{
+		roles:       map[string]*auth.Role{},
+		permissions: map[string]*auth.Permission{},
+	}
+}
+
+func (r *memRoleRepo) CreateRole(_ context.Context, role *auth.Role) error {
+	if len(role.ID) == 0 {
+		role.ID = uuidv7.MustBytes()
+	}
+	r.roles[string(role.ID)] = role
+	return r.createErr
+}
+
+func (r *memRoleRepo) UpdateRole(_ context.Context, role *auth.Role) error {
+	r.roles[string(role.ID)] = role
+	return r.updateErr
+}
+
+func (r *memRoleRepo) DeleteRole(_ context.Context, id []byte) error {
+	delete(r.roles, string(id))
+	return r.deleteErr
+}
+
+func (r *memRoleRepo) GetRoleByID(_ context.Context, id []byte) (*auth.Role, error) {
+	return r.roles[string(id)], r.getByIDErr
+}
+
+func (r *memRoleRepo) GetRoleByName(_ context.Context, name string) (*auth.Role, error) {
+	for _, role := range r.roles {
+		if role.Name == name {
+			return role, nil
+		}
+	}
+	return nil, nil
+}
+
+func (r *memRoleRepo) ListRoles(_ context.Context, _ string, _ string, _ int, _ int) ([]auth.Role, int64, error) {
+	return r.listRoles, r.listTotal, r.listErr
+}
+
+func (r *memRoleRepo) ListPermissions(_ context.Context, _ string, _ string, _ int, _ int) ([]auth.Permission, int64, error) {
+	return r.listPermissions, r.listPermissionsTotal, r.listPermissionsErr
+}
+func (r *memRoleRepo) ListPermissionsByRoleID(_ context.Context, _ []byte) ([]auth.Permission, error) {
+	return []auth.Permission{}, nil
+}
+
+func (r *memRoleRepo) HasRolePermission(_ context.Context, _ []byte, _ string) (bool, error) {
+	return true, nil
+}
+
+func (r *memRoleRepo) GetPermissionByID(_ context.Context, id []byte) (*auth.Permission, error) {
+	if r.permissionNotFound {
+		return nil, r.getPermissionErr
+	}
+	if permission, ok := r.permissions[string(id)]; ok {
+		return permission, r.getPermissionErr
+	}
+	return &auth.Permission{}, r.getPermissionErr
+}
+
+func (r *memRoleRepo) GetPermissionByKey(_ context.Context, key string) (*auth.Permission, error) {
+	if r.permissionNotFound {
+		return nil, r.getPermissionErr
+	}
+	for _, permission := range r.permissions {
+		if permission.Key == key {
+			return permission, r.getPermissionErr
+		}
+	}
+	return &auth.Permission{}, r.getPermissionErr
+}
+
+func (r *memRoleRepo) UpdatePermission(_ context.Context, permission *auth.Permission) error {
+	if permission != nil {
+		r.permissions[string(permission.ID)] = permission
+	}
+	return r.updateErr
+}
+
+func (r *memRoleRepo) AssignPermission(_ context.Context, roleID, permissionID []byte) (*auth.RolePermission, error) {
+	return &auth.RolePermission{ID: uuidv7.MustBytes(), RoleID: roleID, PermissionID: permissionID}, r.assignPermissionErr
+}
+
+func (r *memRoleRepo) RemovePermission(_ context.Context, _ []byte, _ []byte) error {
+	return r.removePermissionErr
+}
+
+func TestRoleHandler_Update_MissingBodyID(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/roles/update/:uuid", h.Update)
+
+	payload := []byte(`{"data":{"type":"role","attributes":{"name":"test_role"}}}`)
+	idStr, _ := uuidv7.BytesToString(roleID)
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/update/"+idStr, bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_Update_IDMismatch(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/roles/update/:uuid", h.Update)
+
+	pathID, _ := uuidv7.BytesToString(roleID)
+	otherID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	payload := []byte(`{"data":{"type":"role","id":"` + otherID + `","attributes":{"name":"test_role"}}}`)
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/update/"+pathID, bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_Update_Success(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/roles/update/:uuid", h.Update)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	payload := []byte(`{"data":{"type":"role","id":"` + idStr + `","attributes":{"name":"test_role"}}}`)
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/update/"+idStr, bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if repo.roles[string(roleID)].Name != "test_role" {
+		t.Fatalf("expected role name updated")
+	}
+}
+
+func TestRoleHandler_Create_Success(t *testing.T) {
+	repo := newMemRoleRepo()
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	actor := uuidv7.MustBytes()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", actor)
+		return c.Next()
+	})
+	app.Post("/api/v1/roles/create", h.Create)
+
+	payload := []byte(`{"data":{"type":"role","attributes":{"name":"admin","description":"full"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/create", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201, got %d", resp.StatusCode)
+	}
+	for _, created := range repo.roles {
+		if string(created.CreatedBy) != string(actor) {
+			t.Fatalf("expected created_by from actor")
+		}
+	}
+}
+
+func TestRoleHandler_Create_InvalidJSON(t *testing.T) {
+	repo := newMemRoleRepo()
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/roles/create", h.Create)
+
+	payload := []byte(`{"data":`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/create", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_Create_ValidationError(t *testing.T) {
+	repo := newMemRoleRepo()
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/roles/create", h.Create)
+
+	payload := []byte(`{"data":{"type":"role","attributes":{"name":""}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/create", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_Create_ServiceError(t *testing.T) {
+	repo := newMemRoleRepo()
+	repo.createErr = errors.New("db error")
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/roles/create", h.Create)
+
+	payload := []byte(`{"data":{"type":"role","attributes":{"name":"admin"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/create", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_Delete_Success(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Delete("/api/v1/roles/delete/:uuid", h.Delete)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	req, _ := http.NewRequest(http.MethodDelete, "/api/v1/roles/delete/"+idStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_Delete_InvalidID(t *testing.T) {
+	repo := newMemRoleRepo()
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Delete("/api/v1/roles/delete/:uuid", h.Delete)
+
+	req, _ := http.NewRequest(http.MethodDelete, "/api/v1/roles/delete/not-a-uuid", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_Delete_ServiceError(t *testing.T) {
+	repo := newMemRoleRepo()
+	repo.deleteErr = errors.New("db error")
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Delete("/api/v1/roles/delete/:uuid", h.Delete)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	req, _ := http.NewRequest(http.MethodDelete, "/api/v1/roles/delete/"+idStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_GetByID_Success(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/roles/get/:uuid", h.GetByID)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/roles/get/"+idStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_GetByID_NotFound(t *testing.T) {
+	repo := newMemRoleRepo()
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/roles/get/:uuid", h.GetByID)
+
+	idStr, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/roles/get/"+idStr, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_List_Success(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.listRoles = []auth.Role{{ID: roleID, Name: "admin"}}
+	repo.listTotal = 1
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/roles/get-all", h.List)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/roles/get-all?page[number]=1&page[size]=10&filter[name]=ad", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_ListDatatable_Success(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.listRoles = []auth.Role{{ID: roleID, Name: "admin"}}
+	repo.listTotal = 1
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/roles/get-all/dt", h.ListDatatable)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/roles/get-all/dt?page=1&size=10&search=ad", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestParseIntDefault(t *testing.T) {
+	if got := parseIntDefault("", 7); got != 7 {
+		t.Fatalf("expected default value")
+	}
+	if got := parseIntDefault("abc", 7); got != 7 {
+		t.Fatalf("expected default on invalid")
+	}
+	if got := parseIntDefault("9", 7); got != 9 {
+		t.Fatalf("expected parsed value")
+	}
+}
+
+func TestRoleHandler_Update_InvalidID(t *testing.T) {
+	repo := newMemRoleRepo()
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/roles/update/:uuid", h.Update)
+
+	payload := []byte(`{"data":{"type":"role","id":"bad","attributes":{"name":"test_role"}}}`)
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/update/not-a-uuid", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_Update_NoAttributes(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/roles/update/:uuid", h.Update)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	payload := []byte(`{"data":{"type":"role","id":"` + idStr + `","attributes":{}}}`)
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/update/"+idStr, bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_Update_ServiceError(t *testing.T) {
+	repo := newMemRoleRepo()
+	repo.updateErr = errors.New("db error")
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/roles/update/:uuid", h.Update)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	payload := []byte(`{"data":{"type":"role","id":"` + idStr + `","attributes":{"name":"test_role"}}}`)
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/update/"+idStr, bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_AssignPermission_Success(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/roles/:uuid/permissions", h.AssignPermission)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	permID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	payload := []byte(`{"data":{"type":"role_permission","attributes":{"permission_id":"` + permID + `"}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_RemovePermission_Success(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Delete("/api/v1/roles/:uuid/permissions/:permission_uuid", h.RemovePermission)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	permID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	req, _ := http.NewRequest(http.MethodDelete, "/api/v1/roles/"+idStr+"/permissions/"+permID, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_AssignPermissionsBulk_Success(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/roles/:uuid/permissions/assign-bulk", h.AssignPermissionsBulk)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	permID1, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	permID2, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	payload := []byte(`{"data":{"type":"role_assign_permission_bulk","attributes":{"permission_ids":["` + permID1 + `","` + permID2 + `"]}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions/assign-bulk", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_RemovePermissionsBulk_Success(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/roles/:uuid/permissions/remove-bulk", h.RemovePermissionsBulk)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	permID1, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	permID2, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	payload := []byte(`{"data":{"type":"role_remove_permission_bulk","attributes":{"permission_ids":["` + permID1 + `","` + permID2 + `"]}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions/remove-bulk", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_AssignPermission_InvalidAndErrorPaths(t *testing.T) {
+	t.Run("invalid role id", func(t *testing.T) {
+		repo := newMemRoleRepo()
+		svc := service.NewRoleService(repo)
+		h := NewRoleHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/roles/:uuid/permissions", h.AssignPermission)
+
+		payload := []byte(`{"data":{"type":"role_permission","attributes":{"permission_id":"bad"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/not-uuid/permissions", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("permission not found", func(t *testing.T) {
+		repo := newMemRoleRepo()
+		repo.permissionNotFound = true
+		roleID := uuidv7.MustBytes()
+		repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+		svc := service.NewRoleService(repo)
+		h := NewRoleHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/roles/:uuid/permissions", h.AssignPermission)
+
+		idStr, _ := uuidv7.BytesToString(roleID)
+		permID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"role_permission","attributes":{"permission_id":"` + permID + `"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("assign service error", func(t *testing.T) {
+		repo := newMemRoleRepo()
+		repo.assignPermissionErr = errors.New("db error")
+		roleID := uuidv7.MustBytes()
+		repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+		svc := service.NewRoleService(repo)
+		h := NewRoleHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/roles/:uuid/permissions", h.AssignPermission)
+
+		idStr, _ := uuidv7.BytesToString(roleID)
+		permID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"role_permission","attributes":{"permission_id":"` + permID + `"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestRoleHandler_RemovePermission_ErrorPaths(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+	repo.removePermissionErr = errors.New("db error")
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Delete("/api/v1/roles/:uuid/permissions/:permission_uuid", h.RemovePermission)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	permID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	req, _ := http.NewRequest(http.MethodDelete, "/api/v1/roles/"+idStr+"/permissions/"+permID, nil)
+	resp, _ := app.Test(req)
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_RemovePermission_InvalidPermissionID(t *testing.T) {
+	repo := newMemRoleRepo()
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Delete("/api/v1/roles/:uuid/permissions/:permission_uuid", h.RemovePermission)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	req, _ := http.NewRequest(http.MethodDelete, "/api/v1/roles/"+idStr+"/permissions/not-uuid", nil)
+	resp, _ := app.Test(req)
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_AssignPermissionsBulk_ErrorPaths(t *testing.T) {
+	t.Run("empty list", func(t *testing.T) {
+		repo := newMemRoleRepo()
+		roleID := uuidv7.MustBytes()
+		repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+		svc := service.NewRoleService(repo)
+		h := NewRoleHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/roles/:uuid/permissions/assign-bulk", h.AssignPermissionsBulk)
+
+		idStr, _ := uuidv7.BytesToString(roleID)
+		payload := []byte(`{"data":{"type":"role_assign_permission_bulk","attributes":{"permission_ids":[]}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions/assign-bulk", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid permission id", func(t *testing.T) {
+		repo := newMemRoleRepo()
+		roleID := uuidv7.MustBytes()
+		repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+		svc := service.NewRoleService(repo)
+		h := NewRoleHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/roles/:uuid/permissions/assign-bulk", h.AssignPermissionsBulk)
+
+		idStr, _ := uuidv7.BytesToString(roleID)
+		payload := []byte(`{"data":{"type":"role_assign_permission_bulk","attributes":{"permission_ids":["bad"]}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions/assign-bulk", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("assign error", func(t *testing.T) {
+		repo := newMemRoleRepo()
+		repo.assignPermissionErr = errors.New("db error")
+		roleID := uuidv7.MustBytes()
+		repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+		svc := service.NewRoleService(repo)
+		h := NewRoleHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/roles/:uuid/permissions/assign-bulk", h.AssignPermissionsBulk)
+
+		idStr, _ := uuidv7.BytesToString(roleID)
+		permID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"role_assign_permission_bulk","attributes":{"permission_ids":["` + permID + `"]}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions/assign-bulk", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+	t.Run("invalid type", func(t *testing.T) {
+		repo := newMemRoleRepo()
+		roleID := uuidv7.MustBytes()
+		repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+		svc := service.NewRoleService(repo)
+		h := NewRoleHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/roles/:uuid/permissions/assign-bulk", h.AssignPermissionsBulk)
+
+		idStr, _ := uuidv7.BytesToString(roleID)
+		permID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"role_remove_permission_bulk","attributes":{"permission_ids":["` + permID + `"]}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions/assign-bulk", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestRoleHandler_RemovePermissionsBulk_ErrorPaths(t *testing.T) {
+	t.Run("remove error", func(t *testing.T) {
+		repo := newMemRoleRepo()
+		repo.removePermissionErr = errors.New("db error")
+		roleID := uuidv7.MustBytes()
+		repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+		svc := service.NewRoleService(repo)
+		h := NewRoleHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/roles/:uuid/permissions/remove-bulk", h.RemovePermissionsBulk)
+
+		idStr, _ := uuidv7.BytesToString(roleID)
+		permID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"role_remove_permission_bulk","attributes":{"permission_ids":["` + permID + `"]}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions/remove-bulk", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid type", func(t *testing.T) {
+		repo := newMemRoleRepo()
+		roleID := uuidv7.MustBytes()
+		repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+		svc := service.NewRoleService(repo)
+		h := NewRoleHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/roles/:uuid/permissions/remove-bulk", h.RemovePermissionsBulk)
+
+		idStr, _ := uuidv7.BytesToString(roleID)
+		permID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"role_assign_permission_bulk","attributes":{"permission_ids":["` + permID + `"]}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions/remove-bulk", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestRoleHandler_AssignPermissionsBulk_InvalidIDAndRoleNotFound(t *testing.T) {
+	repo := newMemRoleRepo()
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/roles/:uuid/permissions/assign-bulk", h.AssignPermissionsBulk)
+
+	req1, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/not-uuid/permissions/assign-bulk", bytes.NewReader([]byte(`{}`)))
+	req1.Header.Set("Content-Type", "application/json")
+	resp1, _ := app.Test(req1)
+	if resp1.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp1.StatusCode)
+	}
+
+	roleID := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(roleID)
+	permID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	payload := []byte(`{"data":{"type":"role_assign_permission_bulk","attributes":{"permission_ids":["` + permID + `"]}}}`)
+	req2, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions/assign-bulk", bytes.NewReader(payload))
+	req2.Header.Set("Content-Type", "application/json")
+	resp2, _ := app.Test(req2)
+	if resp2.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", resp2.StatusCode)
+	}
+}
+
+func TestRoleHandler_AssignPermissionsBulk_PermissionNotFound(t *testing.T) {
+	repo := newMemRoleRepo()
+	repo.permissionNotFound = true
+	roleID := uuidv7.MustBytes()
+	repo.roles[string(roleID)] = &auth.Role{ID: roleID, Name: "admin"}
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/roles/:uuid/permissions/assign-bulk", h.AssignPermissionsBulk)
+
+	idStr, _ := uuidv7.BytesToString(roleID)
+	permID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	payload := []byte(`{"data":{"type":"role_assign_permission_bulk","attributes":{"permission_ids":["` + permID + `"]}}}`)
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions/assign-bulk", bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, _ := app.Test(req)
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_RemovePermissionsBulk_ValidationAndNotFoundPaths(t *testing.T) {
+	repo := newMemRoleRepo()
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Post("/api/v1/roles/:uuid/permissions/remove-bulk", h.RemovePermissionsBulk)
+
+	req1, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/not-uuid/permissions/remove-bulk", bytes.NewReader([]byte(`{}`)))
+	req1.Header.Set("Content-Type", "application/json")
+	resp1, _ := app.Test(req1)
+	if resp1.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp1.StatusCode)
+	}
+
+	roleID := uuidv7.MustBytes()
+	idStr, _ := uuidv7.BytesToString(roleID)
+	payloadEmpty := []byte(`{"data":{"type":"role_remove_permission_bulk","attributes":{"permission_ids":[]}}}`)
+	req2, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions/remove-bulk", bytes.NewReader(payloadEmpty))
+	req2.Header.Set("Content-Type", "application/json")
+	resp2, _ := app.Test(req2)
+	if resp2.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp2.StatusCode)
+	}
+
+	permID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	payload := []byte(`{"data":{"type":"role_remove_permission_bulk","attributes":{"permission_ids":["` + permID + `"]}}}`)
+	req3, _ := http.NewRequest(http.MethodPost, "/api/v1/roles/"+idStr+"/permissions/remove-bulk", bytes.NewReader(payload))
+	req3.Header.Set("Content-Type", "application/json")
+	resp3, _ := app.Test(req3)
+	if resp3.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", resp3.StatusCode)
+	}
+}
+
+func TestRoleHandler_ListPermissions_Success(t *testing.T) {
+	repo := newMemRoleRepo()
+	repo.listPermissions = []auth.Permission{
+		{
+			ID:          uuidv7.MustBytes(),
+			Name:        "Read User",
+			Key:         "user.read",
+			Description: "Read users",
+		},
+	}
+	repo.listPermissionsTotal = 1
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/roles/permissions/get-all", h.ListPermissions)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/roles/permissions/get-all?page[number]=1&page[size]=10&filter[name]=read&sort=name", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_ListPermissions_Error(t *testing.T) {
+	repo := newMemRoleRepo()
+	repo.listPermissionsErr = errors.New("db error")
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Get("/api/v1/roles/permissions/get-all", h.ListPermissions)
+
+	req, _ := http.NewRequest(http.MethodGet, "/api/v1/roles/permissions/get-all", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_UpdatePermission_Success(t *testing.T) {
+	repo := newMemRoleRepo()
+	permissionID := uuidv7.MustBytes()
+	repo.permissions[string(permissionID)] = &auth.Permission{
+		ID:          permissionID,
+		Name:        "Delete User",
+		Key:         "user.delete",
+		Description: "Delete users",
+		RequiresPIN: false,
+	}
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/roles/permissions/:permission_uuid", h.UpdatePermission)
+
+	permissionIDStr, _ := uuidv7.BytesToString(permissionID)
+	payload := []byte(`{"data":{"type":"permission_update","id":"` + permissionIDStr + `","attributes":{"requires_pin":true}}}`)
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/permissions/"+permissionIDStr, bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	if !repo.permissions[string(permissionID)].RequiresPIN {
+		t.Fatalf("expected permission requires_pin updated")
+	}
+}
+
+func TestRoleHandler_UpdatePermission_NotFound(t *testing.T) {
+	repo := newMemRoleRepo()
+	repo.permissionNotFound = true
+
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/roles/permissions/:permission_uuid", h.UpdatePermission)
+
+	permissionIDStr, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+	payload := []byte(`{"data":{"type":"permission_update","id":"` + permissionIDStr + `","attributes":{"requires_pin":true}}}`)
+	req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/permissions/"+permissionIDStr, bytes.NewReader(payload))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", resp.StatusCode)
+	}
+}
+
+func TestRoleHandler_UpdatePermission_ErrorBranches(t *testing.T) {
+	repo := newMemRoleRepo()
+	svc := service.NewRoleService(repo)
+	h := NewRoleHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/roles/permissions/:permission_uuid", h.UpdatePermission)
+
+	t.Run("invalid path id", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/permissions/not-a-uuid", bytes.NewReader([]byte(`{"data":{"type":"permission_update","id":"x","attributes":{"requires_pin":true}}}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/permissions/"+idStr, bytes.NewReader([]byte(`{"data":`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("missing data id", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/permissions/"+idStr, bytes.NewReader([]byte(`{"data":{"type":"permission_update","attributes":{"requires_pin":true}}}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		pathID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		otherID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/permissions/"+pathID, bytes.NewReader([]byte(`{"data":{"type":"permission_update","id":"`+otherID+`","attributes":{"requires_pin":true}}}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("missing requires_pin", func(t *testing.T) {
+		pathID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/permissions/"+pathID, bytes.NewReader([]byte(`{"data":{"type":"permission_update","id":"`+pathID+`","attributes":{}}}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update service error", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		idStr, _ := uuidv7.BytesToString(id)
+		repo.permissions[string(id)] = &auth.Permission{ID: id, Key: "x", Name: "x"}
+		repo.updateErr = errors.New("update failed")
+		defer func() { repo.updateErr = nil }()
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/roles/permissions/"+idStr, bytes.NewReader([]byte(`{"data":{"type":"permission_update","id":"`+idStr+`","attributes":{"requires_pin":true}}}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestParseIntToString(t *testing.T) {
+	if got := parseIntToString(0); got != "0" {
+		t.Fatalf("expected 0, got %s", got)
+	}
+	if got := parseIntToString(123); got != "123" {
+		t.Fatalf("expected 123, got %s", got)
+	}
+}
+
+func TestRoleResource(t *testing.T) {
+	now := time.Now().UTC()
+	role := &auth.Role{
+		ID:          uuidv7.MustBytes(),
+		Name:        "admin",
+		Description: "full access",
+		CreatedBy:   uuidv7.MustBytes(),
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	}
+
+	res := roleResource(role)
+	if res.Type != "role" || res.ID == "" {
+		t.Fatalf("expected role resource type/id")
+	}
+	if res.Attributes.CreatedBy == "" {
+		t.Fatalf("expected created_by in role resource")
+	}
+}
diff --git a/internal/transport/http/handlers/takeover_handler.go b/internal/transport/http/handlers/takeover_handler.go
new file mode 100644
index 0000000..d5ae957
--- /dev/null
+++ b/internal/transport/http/handlers/takeover_handler.go
@@ -0,0 +1,2028 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	authdomain "wucher/internal/domain/auth"
+	basedomain "wucher/internal/domain/base"
+	beforeflightinspection "wucher/internal/domain/before_flight_inspection"
+	dutyroster "wucher/internal/domain/duty_roster"
+	filemanager "wucher/internal/domain/file_manager"
+	fleetstatus "wucher/internal/domain/fleet_status"
+	"wucher/internal/domain/flight"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	flightinspectionfilechecklist "wucher/internal/domain/flight_inspection_file_checklist"
+	flightprepcheck "wucher/internal/domain/flight_prep_check"
+	"wucher/internal/domain/helicopter"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	reserveac "wucher/internal/domain/reserve_ac"
+	takeover "wucher/internal/domain/takeover"
+	"wucher/internal/repository/mysql"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/appctx"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	requestdto "wucher/internal/transport/http/dto/request"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+// takeoverHelicopterChecker exposes the helicopter availability check the
+// takeover handler needs to reject already-booked helicopters.
+type takeoverHelicopterChecker interface {
+	IsInUse(ctx context.Context, id []byte) (bool, error)
+	GetByID(ctx context.Context, id []byte) (*helicopter.Helicopter, error)
+}
+
+type TakeoverHandler struct {
+	flight       flight.FlightService
+	base         basedomain.Service
+	reserveAc    reserveac.ReserveAcService
+	dutyRoster   dutyroster.Service
+	db           *gorm.DB
+	takeoverAc   *service.TakeoverModuleService
+	inspect      flightinspection.FlightInspectionService
+	before       beforeflightinspection.Service
+	prep         flightprepcheck.Service
+	heliFile     helicopterfile.Service
+	fileCk       flightinspectionfilechecklist.Service
+	fileManager  filemanager.Service
+	helicopter   takeoverHelicopterChecker
+	fleetStatus  helicopterFleetStatusProvider
+	complaintSvc complaintGroundingLister
+	mcfSvc       mcfPendingChecker
+	storage      fileManagerDownloadURLStorage
+	auth         takeoverAuthService
+	validate     *validators.Validator
+}
+
+type takeoverAuthService interface {
+	GetUserByID(ctx context.Context, id []byte) (*authdomain.User, error)
+}
+
+func NewTakeoverHandler(db *gorm.DB) *TakeoverHandler {
+	return &TakeoverHandler{
+		db:       db,
+		validate: validators.New(),
+	}
+}
+
+func (h *TakeoverHandler) WithDB(db *gorm.DB) *TakeoverHandler {
+	h.db = db
+	return h
+}
+
+func (h *TakeoverHandler) takeoverService() *service.TakeoverService {
+	if h != nil && h.db != nil {
+		return service.NewTakeoverService(h.db).
+			WithChecklistTemplateRepository(mysql.NewTakeoverRepository(h.db))
+	}
+	return nil
+}
+
+func (h *TakeoverHandler) WithFlightService(flightSvc flight.FlightService) *TakeoverHandler {
+	h.flight = flightSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithAuthService(authSvc takeoverAuthService) *TakeoverHandler {
+	h.auth = authSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithBaseService(baseSvc basedomain.Service) *TakeoverHandler {
+	h.base = baseSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithReserveAcService(reserveAcSvc reserveac.ReserveAcService) *TakeoverHandler {
+	h.reserveAc = reserveAcSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithDutyRosterService(dutyRosterSvc dutyroster.Service) *TakeoverHandler {
+	h.dutyRoster = dutyRosterSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithFleetStatusService(fleetStatusSvc helicopterFleetStatusProvider) *TakeoverHandler {
+	h.fleetStatus = fleetStatusSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithHelicopterService(helicopterSvc takeoverHelicopterChecker) *TakeoverHandler {
+	h.helicopter = helicopterSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithComplaintService(complaintSvc complaintGroundingLister) *TakeoverHandler {
+	h.complaintSvc = complaintSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithMCFService(mcfSvc mcfPendingChecker) *TakeoverHandler {
+	h.mcfSvc = mcfSvc
+	return h
+}
+
+// existingTakeoverHelicopterID resolves the helicopter currently assigned to the
+// takeover behind the given flight (via its reserve AC), used to skip the
+// availability check when the helicopter is not being changed.
+func (h *TakeoverHandler) existingTakeoverHelicopterID(ctx context.Context, fl *flight.Flight) []byte {
+	if fl == nil || h.reserveAc == nil || len(fl.ReserveAcID) != 16 {
+		return nil
+	}
+	rac, err := h.reserveAc.GetByID(ctx, fl.ReserveAcID)
+	if err != nil || rac == nil {
+		return nil
+	}
+	return rac.AircraftID
+}
+
+// helicopterBookedError returns a conflict error when the requested helicopter is
+// already booked (in use by an active flight/takeover). When current is the same
+// helicopter (no change on update) the check is skipped.
+func (h *TakeoverHandler) helicopterBookedError(ctx context.Context, requested, current []byte) *apperrorsx.AppError {
+	if h.helicopter == nil || len(requested) != 16 {
+		return nil
+	}
+	if len(current) == 16 && bytes.Equal(requested, current) {
+		return nil
+	}
+	inUse, err := h.helicopter.IsInUse(ctx, requested)
+	if err != nil || !inUse {
+		return nil
+	}
+	return apperrorsx.New(apperrorsx.ErrTakeoverHelicopterInUse)
+}
+
+func (h *TakeoverHandler) helicopterGroundedError(ctx context.Context, requested, current []byte) *apperrorsx.AppError {
+	if len(requested) != 16 {
+		return nil
+	}
+	if len(current) == 16 && bytes.Equal(requested, current) {
+		return nil
+	}
+	if h.mcfSvc != nil && mcfPendingHelicopterSet(ctx, h.mcfSvc, [][]byte{requested})[string(requested)] {
+		return apperrorsx.New(apperrorsx.ErrTakeoverHelicopterMCF)
+	}
+	grounded := false
+	if h.helicopter != nil {
+		if heli, err := h.helicopter.GetByID(ctx, requested); err == nil && heli != nil && heli.AirOnGround {
+			grounded = true
+		}
+	}
+	if !grounded && h.complaintSvc != nil {
+		grounded = groundingHelicopterSet(ctx, h.complaintSvc, [][]byte{requested}, time.Now().UTC())[string(requested)]
+	}
+	if grounded {
+		return apperrorsx.New(apperrorsx.ErrTakeoverHelicopterAOG)
+	}
+	return nil
+}
+
+func (h *TakeoverHandler) takeoverUserHasGlobalAccess(ctx context.Context) bool {
+	return h.takeoverUserHasGlobalAccessForUserID(ctx, appctx.GetUserID(ctx))
+}
+
+func (h *TakeoverHandler) takeoverUserHasGlobalAccessForUserID(ctx context.Context, userID []byte) bool {
+	if h == nil || h.auth == nil {
+		return false
+	}
+	if len(userID) != 16 {
+		return false
+	}
+	user, err := h.auth.GetUserByID(ctx, userID)
+	if err != nil || user == nil {
+		return false
+	}
+	return takeoverUserHasRole(user, "admin")
+}
+
+func takeoverUserHasRole(user *authdomain.User, roleName string) bool {
+	if user == nil {
+		return false
+	}
+	for i := range user.Roles {
+		if strings.EqualFold(strings.TrimSpace(user.Roles[i].Name), roleName) {
+			return true
+		}
+	}
+	return false
+}
+
+func (h *TakeoverHandler) hasAfterFlightInspection(ctx context.Context, flightInspectionID []byte) bool {
+	if h == nil || h.db == nil || len(flightInspectionID) != 16 {
+		return false
+	}
+	var count int64
+	if err := h.db.WithContext(ctx).
+		Table("after_flight_inspections").
+		Where("flight_inspection_id = ?", flightInspectionID).
+		Count(&count).Error; err != nil {
+		return false
+	}
+	return count > 0
+}
+
+func (h *TakeoverHandler) WithFlightInspectionService(inspectionSvc flightinspection.FlightInspectionService) *TakeoverHandler {
+	h.inspect = inspectionSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithBeforeFlightInspectionService(beforeSvc beforeflightinspection.Service) *TakeoverHandler {
+	h.before = beforeSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithFlightPrepCheckService(prepSvc flightprepcheck.Service) *TakeoverHandler {
+	h.prep = prepSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithHelicopterFileService(heliFileSvc helicopterfile.Service) *TakeoverHandler {
+	h.heliFile = heliFileSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithFileManagerService(fileManagerSvc filemanager.Service) *TakeoverHandler {
+	h.fileManager = fileManagerSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithFlightInspectionFileChecklistService(fileChecklistSvc flightinspectionfilechecklist.Service) *TakeoverHandler {
+	h.fileCk = fileChecklistSvc
+	return h
+}
+
+func (h *TakeoverHandler) WithFileStorage(storage fileManagerDownloadURLStorage) *TakeoverHandler {
+	h.storage = storage
+	return h
+}
+
+func (h *TakeoverHandler) WithTakeoverAcService(takeoverAcSvc *service.TakeoverModuleService) *TakeoverHandler {
+	h.takeoverAc = takeoverAcSvc
+	return h
+}
+
+func logTakeoverError(c *fiber.Ctx, action string, err error) {
+	if err == nil {
+		return
+	}
+	if c != nil {
+		c.Locals(apperrorsx.ContextKeyHTTPErrorInternalDetail, buildTakeoverErrorDetail(action, err))
+	}
+	attrs := []any{
+		"action", action,
+		"method", c.Method(),
+		"path", c.Path(),
+		"request_id", c.Get("X-Request-Id"),
+		"error", err.Error(),
+		"error_type", fmt.Sprintf("%T", err),
+		"error_chain", buildErrorChain(err),
+	}
+	var appErr *apperrorsx.AppError
+	if errors.As(err, &appErr) && appErr != nil {
+		attrs = append(attrs,
+			"app_error_status", appErr.Status,
+			"app_error_code", appErr.Code,
+			"app_error_error_code", appErr.ErrorCode,
+			"app_error_title", appErr.Title,
+			"app_error_message", appErr.Message,
+			"app_error_detail", appErr.Detail,
+		)
+		if appErr.Cause != nil {
+			attrs = append(attrs, "app_error_cause", appErr.Cause.Error())
+		}
+	}
+	slog.Error("takeover handler error", attrs...)
+}
+
+func buildTakeoverErrorDetail(action string, err error) string {
+	if err == nil {
+		return ""
+	}
+	parts := make([]string, 0, 8)
+	if strings.TrimSpace(action) != "" {
+		parts = append(parts, "action="+action)
+	}
+	parts = append(parts, "error="+err.Error())
+	if chain := buildErrorChain(err); len(chain) > 0 {
+		parts = append(parts, "chain="+strings.Join(chain, " <- "))
+	}
+	var appErr *apperrorsx.AppError
+	if errors.As(err, &appErr) && appErr != nil {
+		parts = append(parts,
+			fmt.Sprintf("app_error_status=%d", appErr.Status),
+			fmt.Sprintf("app_error_code=%s", appErr.Code),
+			fmt.Sprintf("app_error_error_code=%s", appErr.ErrorCode),
+			fmt.Sprintf("app_error_title=%s", appErr.Title),
+			fmt.Sprintf("app_error_message=%s", appErr.Message),
+		)
+		if appErr.Cause != nil {
+			parts = append(parts, "app_error_cause="+appErr.Cause.Error())
+		}
+	}
+	return strings.Join(parts, " | ")
+}
+
+func buildErrorChain(err error) []string {
+	if err == nil {
+		return nil
+	}
+	chain := make([]string, 0, 8)
+	seen := map[string]struct{}{}
+	for current := err; current != nil; current = errors.Unwrap(current) {
+		msg := current.Error()
+		if msg == "" {
+			msg = fmt.Sprintf("%T", current)
+		}
+		key := fmt.Sprintf("%T:%s", current, msg)
+		if _, ok := seen[key]; ok {
+			break
+		}
+		seen[key] = struct{}{}
+		chain = append(chain, fmt.Sprintf("%T: %s", current, msg))
+	}
+	return chain
+}
+
+func writeTakeoverErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferTakeoverDef(status, e.Title, e.Detail)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		if strings.TrimSpace(e.Title) == "" {
+			e.Title = def.Title
+		}
+		e.Detail = def.Message
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferTakeoverDef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		switch {
+		case strings.Contains(lowerDetail, "flight"):
+			return apperrorsx.ErrTakeoverNotFound
+		default:
+			return apperrorsx.ErrTakeoverNotFound
+		}
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "helicopter_file_id does not belong"):
+			return apperrorsx.ErrTakeoverFileSectionInvalid
+		case strings.Contains(lowerDetail, "invalid uuid"):
+			return apperrorsx.ErrTakeoverInvalidUUID
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.ErrTakeoverIDRequired
+		case strings.Contains(lowerDetail, "id does not match"):
+			return apperrorsx.ErrTakeoverIDMismatch
+		case strings.Contains(lowerTitle, "validation error"):
+			return apperrorsx.ErrTakeoverInvalidPayload
+		default:
+			return apperrorsx.ErrTakeoverInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrTakeoverInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.ErrTakeoverCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrTakeoverUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrTakeoverDeleteFailed
+		case strings.Contains(lowerTitle, "get failed"):
+			return apperrorsx.ErrTakeoverGetFailed
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.ErrTakeoverListFailed
+		default:
+			return apperrorsx.ErrTakeoverCreateFailed
+		}
+	case fiber.StatusConflict:
+		return apperrorsx.ErrTakeoverHelicopterInUse
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
+
+func takeoverAppErrorFromServiceErr(err error) *apperrorsx.AppError {
+	if err == nil {
+		return nil
+	}
+	detail := strings.ToLower(strings.TrimSpace(err.Error()))
+	switch {
+	case strings.Contains(detail, "helicopter_file_id does not belong to helicopter and section"),
+		strings.Contains(detail, "helicopter_file_id does not belong to selected helicopter/section"):
+		return apperrorsx.New(apperrorsx.ErrTakeoverFileSectionInvalid).WithCause(err)
+	case strings.Contains(detail, "must include all helicopter files"),
+		strings.Contains(detail, "must be fully checked"),
+		strings.Contains(detail, "edited template file must be included in the flight preparation file checklist"),
+		strings.Contains(detail, "is required"),
+		strings.Contains(detail, "invalid helicopter_file_id"),
+		strings.Contains(detail, "must be a valid uuid"),
+		strings.Contains(detail, "invalid roster_detail"):
+		return apperrorsx.New(apperrorsx.ErrTakeoverInvalidPayload).WithCause(err)
+	case strings.Contains(detail, "helicopter is already booked"):
+		return apperrorsx.New(apperrorsx.ErrTakeoverHelicopterInUse).WithCause(err)
+	case strings.Contains(detail, "not found"):
+		return apperrorsx.New(apperrorsx.ErrTakeoverNotFound).WithCause(err)
+	case strings.Contains(detail, "create failed"):
+		return apperrorsx.New(apperrorsx.ErrTakeoverCreateFailed).WithCause(err)
+	case strings.Contains(detail, "update failed"):
+		return apperrorsx.New(apperrorsx.ErrTakeoverUpdateFailed).WithCause(err)
+	default:
+		return nil
+	}
+}
+
+// CreateTakeover godoc
+// @Summary Create takeover in one request
+// @Description Atomic create for duty roster + crews + reserve AC + pre-flight inspection + flight. The takeover inspection payload also includes fleet status files under `inspection.fleet_status_file`.
+// @Description Optional takeover file uploads can be included via `data.attributes.files[*]` using upload intent UUIDs.
+// @Description Edited template draft files created earlier can be linked by passing `data.attributes.edited_template_file_ids[*]`.
+// @Tags Flight - Takeovers
+// @Accept json
+// @Produce json
+// @Param request body requestdto.TakeoverCreateRequest true "Create takeover request"
+// @Success 201 {object} responsedto.TakeoverResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 422 {object} jsonapi.ErrorDocument
+// @Router /api/v1/takeovers/create [post]
+func (h *TakeoverHandler) CreateTakeover(c *fiber.Ctx) error {
+	takeoverSvc := h.takeoverService()
+	if h == nil || takeoverSvc == nil {
+		logTakeoverError(c, "CreateTakeover", errors.New("takeover service is not configured"))
+		return writeTakeoverErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{Status: "500", Title: "Create failed", Detail: "takeover service is not configured"}})
+	}
+	var req requestdto.TakeoverCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		logTakeoverError(c, "CreateTakeover", err)
+		return writeTakeoverErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: safeInternalDetail()}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	var errObj *jsonapi.ErrorObject
+	var baseID []byte
+	hasBaseID := false
+	if req.Data.Attributes.BaseID != nil && strings.TrimSpace(*req.Data.Attributes.BaseID) != "" {
+		baseID, errObj = parseTakeoverUUID(*req.Data.Attributes.BaseID, "/data/attributes/base_id")
+		if errObj != nil {
+			return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		hasBaseID = true
+	}
+	dutyDate, errObj := parseTakeoverDate(req.Data.Attributes.DutyDate)
+	if errObj != nil {
+		return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+	}
+	var helicopterID []byte
+	if req.Data.Attributes.AircraftID != nil && strings.TrimSpace(*req.Data.Attributes.AircraftID) != "" {
+		helicopterID, errObj = parseTakeoverUUID(*req.Data.Attributes.AircraftID, "/data/attributes/helicopter_id")
+		if errObj != nil {
+			return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+	}
+	if appErr := h.helicopterGroundedError(c.UserContext(), helicopterID, nil); appErr != nil {
+		return apperrorsx.Write(c, appErr)
+	}
+	var inspection *requestdto.ReserveAcInspectionCreateAttributes
+	if req.Data.Attributes.Inspection != nil {
+		inspection = req.Data.Attributes.Inspection
+	}
+	out, err := takeoverSvc.Create(c.UserContext(), service.TakeoverCreateInput{
+		BaseID:          baseID,
+		HasBaseID:       hasBaseID,
+		DutyDate:        dutyDate,
+		HasDutyDate:     true,
+		Notes:           req.Data.Attributes.Notes,
+		RosterDetail:    takeoverRosterDetailInput(req.Data.Attributes.Detail),
+		HasRosterDetail: req.Data.Attributes.Detail != nil,
+		HelicopterID:    helicopterID,
+		HasHelicopterID: helicopterID != nil,
+		Inspection:      inspection,
+		HasInspection:   inspection != nil,
+		ActorUserID:     actorUserID(c),
+	})
+	if err != nil {
+		logTakeoverError(c, "CreateTakeover", err)
+		if appErr := takeoverAppErrorFromServiceErr(err); appErr != nil {
+			return apperrorsx.Write(c, appErr)
+		}
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTakeoverCreateFailed).WithCause(err))
+	}
+	if err := h.attachTakeoverCreateFiles(c, takeoverSvc, out.TakeoverAcID, req.Data.Attributes.Files); err != nil {
+		return err
+	}
+	if err := h.attachTakeoverEditedTemplateFiles(c, takeoverSvc, out.TakeoverAcID, req.Data.Attributes.EditedTemplateFileIDs); err != nil {
+		return err
+	}
+	outResp, respErr := h.buildTakeoverResponse(c, out.TakeoverAcID)
+	if respErr != nil {
+		logTakeoverError(c, "CreateTakeover.buildResponse", respErr)
+		return writeTakeoverErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Create failed", Detail: respErr.Error()}})
+	}
+	if outResp == nil {
+		return writeTakeoverErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{Status: "500", Title: "Create failed", Detail: "takeover response not available"}})
+	}
+	return response.Write(c, fiber.StatusCreated, outResp.Data)
+}
+
+func takeoverRosterDetailInput(in *requestdto.TakeoverRosterDetailsInput) *requestdto.DutyRosterDetailsInput {
+	if in == nil {
+		return nil
+	}
+	out := requestdto.DutyRosterDetailsInput{
+		Pilot:       make([]requestdto.DutyRosterPilotCrewInput, 0, len(in.Pilot)),
+		Doctor:      make([]requestdto.DutyRosterCrewInput, 0, len(in.Doctor)),
+		Rescuer:     make([]requestdto.DutyRosterCrewInput, 0, len(in.Rescuer)),
+		Helper:      make([]requestdto.DutyRosterCrewInput, 0, len(in.Helper)),
+		OtherPerson: make([]requestdto.DutyRosterOtherPersonInput, 0, len(in.OtherPerson)),
+	}
+	for _, item := range in.Pilot {
+		out.Pilot = append(out.Pilot, requestdto.DutyRosterPilotCrewInput{
+			ID:               item.ID,
+			FlightInstructor: item.FlightInstructor,
+			LineChecker:      item.LineChecker,
+			Supervisor:       item.Supervisor,
+			Examiner:         item.Examiner,
+			CoPilot:          item.CoPilot,
+			CrewType:         item.CrewType,
+		})
+	}
+	for _, item := range in.Doctor {
+		out.Doctor = append(out.Doctor, requestdto.DutyRosterCrewInput{ID: item.ID})
+	}
+	for _, item := range in.Rescuer {
+		out.Rescuer = append(out.Rescuer, requestdto.DutyRosterCrewInput{ID: item.ID})
+	}
+	for _, item := range in.Helper {
+		out.Helper = append(out.Helper, requestdto.DutyRosterCrewInput{ID: item.ID})
+	}
+	for _, item := range in.OtherPerson {
+		out.OtherPerson = append(out.OtherPerson, requestdto.DutyRosterOtherPersonInput{
+			Name:        item.Name,
+			MobilePhone: item.MobilePhone,
+			Email:       item.Email,
+		})
+	}
+	return &out
+}
+
+func takeoverRosterDetailResponse(in requestdto.DutyRosterDetailsInput) responsedto.TakeoverDutyRosterDetailsResponse {
+	out := responsedto.TakeoverDutyRosterDetailsResponse{
+		Pilot:       make([]responsedto.TakeoverDutyRosterPilotCrew, 0, len(in.Pilot)),
+		Doctor:      make([]responsedto.TakeoverDutyRosterCrew, 0, len(in.Doctor)),
+		Rescuer:     make([]responsedto.TakeoverDutyRosterCrew, 0, len(in.Rescuer)),
+		Helper:      make([]responsedto.TakeoverDutyRosterCrew, 0, len(in.Helper)),
+		OtherPerson: make([]responsedto.TakeoverDutyRosterCrew, 0, len(in.OtherPerson)),
+	}
+	for _, item := range in.Pilot {
+		out.Pilot = append(out.Pilot, responsedto.TakeoverDutyRosterPilotCrew{
+			ID:               item.ID,
+			CrewType:         item.CrewType,
+			FlightInstructor: takeoverBoolPtr(item.FlightInstructor),
+			LineChecker:      takeoverBoolPtr(item.LineChecker),
+			Supervisor:       takeoverBoolPtr(item.Supervisor),
+			Examiner:         takeoverBoolPtr(item.Examiner),
+			CoPilot:          takeoverBoolPtr(item.CoPilot),
+			Role:             "pilot",
+		})
+	}
+	for _, item := range in.Doctor {
+		out.Doctor = append(out.Doctor, responsedto.TakeoverDutyRosterCrew{
+			ID:   item.ID,
+			Role: "doctor",
+		})
+	}
+	for _, item := range in.Rescuer {
+		out.Rescuer = append(out.Rescuer, responsedto.TakeoverDutyRosterCrew{
+			ID:   item.ID,
+			Role: "rescuer",
+		})
+	}
+	for _, item := range in.Helper {
+		out.Helper = append(out.Helper, responsedto.TakeoverDutyRosterCrew{
+			ID:   item.ID,
+			Role: "helper",
+		})
+	}
+	for _, item := range in.OtherPerson {
+		out.OtherPerson = append(out.OtherPerson, responsedto.TakeoverDutyRosterCrew{
+			Name:        item.Name,
+			MobilePhone: item.MobilePhone,
+			Email:       item.Email,
+		})
+	}
+	return out
+}
+
+func takeoverDutyRosterDetailsFromRosterDetails(in responsedto.DutyRosterDetailsResponse) responsedto.TakeoverDutyRosterDetailsResponse {
+	out := responsedto.TakeoverDutyRosterDetailsResponse{
+		Pilot:       make([]responsedto.TakeoverDutyRosterPilotCrew, 0, len(in.Pilot)),
+		Doctor:      make([]responsedto.TakeoverDutyRosterCrew, 0, len(in.Doctor)),
+		Rescuer:     make([]responsedto.TakeoverDutyRosterCrew, 0, len(in.Rescuer)),
+		Helper:      make([]responsedto.TakeoverDutyRosterCrew, 0, len(in.Helper)),
+		OtherPerson: make([]responsedto.TakeoverDutyRosterCrew, 0, len(in.OtherPerson)),
+	}
+	for _, item := range in.Pilot {
+		out.Pilot = append(out.Pilot, responsedto.TakeoverDutyRosterPilotCrew{
+			ID:               item.ID,
+			Name:             item.Name,
+			Role:             item.Role,
+			CrewType:         item.CrewType,
+			FlightInstructor: item.FlightInstructor,
+			LineChecker:      item.LineChecker,
+			Supervisor:       item.Supervisor,
+			Examiner:         item.Examiner,
+			CoPilot:          item.CoPilot,
+		})
+	}
+	for _, item := range in.Doctor {
+		out.Doctor = append(out.Doctor, responsedto.TakeoverDutyRosterCrew{
+			ID:          item.ID,
+			Name:        item.Name,
+			Role:        item.Role,
+			MobilePhone: item.MobilePhone,
+			Email:       item.Email,
+		})
+	}
+	for _, item := range in.Rescuer {
+		out.Rescuer = append(out.Rescuer, responsedto.TakeoverDutyRosterCrew{
+			ID:          item.ID,
+			Name:        item.Name,
+			Role:        item.Role,
+			MobilePhone: item.MobilePhone,
+			Email:       item.Email,
+		})
+	}
+	for _, item := range in.Helper {
+		out.Helper = append(out.Helper, responsedto.TakeoverDutyRosterCrew{
+			ID:          item.ID,
+			Name:        item.Name,
+			Role:        item.Role,
+			MobilePhone: item.MobilePhone,
+			Email:       item.Email,
+		})
+	}
+	for _, item := range in.OtherPerson {
+		out.OtherPerson = append(out.OtherPerson, responsedto.TakeoverDutyRosterCrew{
+			Name:        item.Name,
+			MobilePhone: item.MobilePhone,
+			Email:       item.Email,
+		})
+	}
+	return out
+}
+
+func takeoverBoolPtr(v bool) *bool {
+	if !v {
+		return nil
+	}
+	out := true
+	return &out
+}
+
+func loadTakeoverRosterCrewRows(ctx context.Context, db *gorm.DB, takeoverID []byte) ([]takeover.TakeoverRosterCrew, error) {
+	rows := make([]takeover.TakeoverRosterCrew, 0)
+	if err := db.WithContext(ctx).
+		Where("takeover_id = ? AND deleted_at IS NULL", takeoverID).
+		Preload("User").
+		Order("created_at ASC").
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func loadTakeoverOtherPeopleRows(ctx context.Context, db *gorm.DB, takeoverID []byte) ([]takeover.TakeoverOtherPerson, error) {
+	rows := make([]takeover.TakeoverOtherPerson, 0)
+	if err := db.WithContext(ctx).
+		Where("takeover_id = ? AND deleted_at IS NULL", takeoverID).
+		Order("created_at ASC").
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func buildDutyRosterResourceFromTakeoverRows(resource responsedto.DutyRosterResource, rows []takeover.TakeoverRosterCrew, flightRow *flight.Flight) responsedto.DutyRosterResource {
+	for i := range rows {
+		item := rows[i]
+		if item.User != nil && len(item.User.FirstName+item.User.LastName) > 0 {
+			item.NameLabel = item.User.FirstName + " " + item.User.LastName
+		}
+		switch strings.ToLower(strings.TrimSpace(item.RoleCode)) {
+		case "pilot":
+			resource.Attributes.Detail.Pilot = append(resource.Attributes.Detail.Pilot, responsedto.DutyRosterPilotCrew{
+				ID:               idString(item.UserID),
+				Name:             item.NameLabel,
+				Role:             "pilot",
+				MobilePhone:      item.MobilePhone,
+				Email:            item.Email,
+				CrewType:         item.CrewType,
+				FlightInstructor: boolPtr(item.FlightInstructor),
+				LineChecker:      boolPtr(item.LineChecker),
+				Supervisor:       boolPtr(item.Supervisor),
+				Examiner:         boolPtr(item.Examiner),
+				CoPilot:          boolPtr(item.CoPilot),
+			})
+		case "doctor":
+			resource.Attributes.Detail.Doctor = append(resource.Attributes.Detail.Doctor, responsedto.DutyRosterCrew{
+				ID:          firstNonEmptyString(idString(item.UserID), idString(item.ID)),
+				Name:        item.NameLabel,
+				Role:        "doctor",
+				MobilePhone: item.MobilePhone,
+				Email:       item.Email,
+			})
+		case "rescuer":
+			resource.Attributes.Detail.Rescuer = append(resource.Attributes.Detail.Rescuer, responsedto.DutyRosterCrew{
+				ID:          firstNonEmptyString(idString(item.UserID), idString(item.ID)),
+				Name:        item.NameLabel,
+				Role:        "rescuer",
+				MobilePhone: item.MobilePhone,
+				Email:       item.Email,
+			})
+		case "helper":
+			resource.Attributes.Detail.Helper = append(resource.Attributes.Detail.Helper, responsedto.DutyRosterCrew{
+				ID:          firstNonEmptyString(idString(item.UserID), idString(item.ID)),
+				Name:        item.NameLabel,
+				Role:        "helper",
+				MobilePhone: item.MobilePhone,
+				Email:       item.Email,
+			})
+		}
+	}
+	if flightRow != nil {
+		resource.ID = idString(flightRow.TakeoverAcID)
+		resource.Attributes.FlightID = idString(flightRow.ID)
+		resource.Attributes.DutyDate = calendarDateString(flightRow.Date)
+	}
+	return resource
+}
+
+func buildDutyRosterResourceFromOtherPeople(resource responsedto.DutyRosterResource, rows []takeover.TakeoverOtherPerson) responsedto.DutyRosterResource {
+	for i := range rows {
+		resource.Attributes.Detail.OtherPerson = append(resource.Attributes.Detail.OtherPerson, responsedto.DutyRosterCrew{
+			ID:          idString(rows[i].ID),
+			Name:        rows[i].Name,
+			Role:        "other_person",
+			MobilePhone: rows[i].MobilePhone,
+			Email:       rows[i].Email,
+		})
+	}
+	return resource
+}
+
+func softDeleteTakeoverRosterChildren(ctx context.Context, db *gorm.DB, takeoverID []byte, deletedBy []byte) error {
+	now := time.Now().UTC()
+	if err := db.WithContext(ctx).Model(&takeover.TakeoverRosterCrew{}).
+		Where("takeover_id = ? AND deleted_at IS NULL", takeoverID).
+		Updates(map[string]any{"deleted_at": now, "deleted_by": deletedBy, "updated_by": deletedBy}).Error; err != nil {
+		return err
+	}
+	if err := db.WithContext(ctx).Model(&takeover.TakeoverOtherPerson{}).
+		Where("takeover_id = ? AND deleted_at IS NULL", takeoverID).
+		Updates(map[string]any{"deleted_at": now, "deleted_by": deletedBy, "updated_by": deletedBy}).Error; err != nil {
+		return err
+	}
+	return nil
+}
+
+// ListTakeovers godoc
+// @Summary List takeovers
+// @Description Return composite takeover records built from flight, reserve AC, duty roster, and inspection. The inspection payload includes `before`, `prepare`, and `fleet_status_file`.
+// @Tags Flight - Takeovers
+// @Produce json
+// @Success 200 {object} map[string]any
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Router /api/v1/takeovers/get-all [get]
+func (h *TakeoverHandler) ListTakeovers(c *fiber.Ctx) error {
+	if h.takeoverAc == nil || h.flight == nil {
+		logTakeoverError(c, "ListTakeovers", errors.New("takeover service is not configured"))
+		return writeTakeoverErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{Status: "500", Title: "Get failed", Detail: "takeover service is not configured"}})
+	}
+	rows, _, err := h.takeoverAc.List(c.UserContext(), 100, 0)
+	if err != nil {
+		logTakeoverError(c, "ListTakeovers", err)
+		return writeTakeoverErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Get failed", Detail: safeInternalDetail()}})
+	}
+	takeoverIDs := make([][]byte, 0, len(rows))
+	for i := range rows {
+		takeoverIDs = append(takeoverIDs, rows[i].ID)
+	}
+	flights, err := h.flight.ListByTakeoverAcIDs(c.UserContext(), takeoverIDs)
+	if err != nil {
+		logTakeoverError(c, "ListTakeovers", err)
+		return writeTakeoverErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Get failed", Detail: safeInternalDetail()}})
+	}
+	flightByTakeoverID := make(map[string]flight.Flight, len(flights))
+	for i := range flights {
+		flightByTakeoverID[idString(flights[i].TakeoverAcID)] = flights[i]
+	}
+	out := make([]responsedto.TakeoverResource, 0, len(rows))
+	for i := range rows {
+		if flightRow, ok := flightByTakeoverID[idString(rows[i].ID)]; ok {
+			item, err := h.buildTakeoverResponseFromRows(c, &rows[i], &flightRow)
+			if err != nil || item == nil {
+				continue
+			}
+			out = append(out, item.Data)
+			continue
+		}
+		item, err := h.buildTakeoverResponse(c, rows[i].ID)
+		if err != nil || item == nil {
+			continue
+		}
+		out = append(out, item.Data)
+	}
+	return response.WriteWithMeta(c, fiber.StatusOK, out, map[string]any{"total": len(out)})
+}
+
+// GetTakeover godoc
+// @Summary Get takeover by flight UUID
+// @Tags Flight - Takeovers
+// @Produce json
+// @Param id path string true "Flight UUID"
+// @Success 200 {object} responsedto.TakeoverResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Router /api/v1/takeovers/get/{id} [get]
+func (h *TakeoverHandler) GetTakeover(c *fiber.Ctx) error {
+	idRaw := strings.TrimSpace(c.Params("id"))
+	id, err := uuidv7.ParseString(idRaw)
+	if err != nil {
+		return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "id is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/data/id"}}})
+	}
+	out, err := h.buildTakeoverResponse(c, id)
+	if err != nil {
+		logTakeoverError(c, "GetTakeover", err)
+		return writeTakeoverErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Get failed", Detail: safeInternalDetail()}})
+	}
+	if out == nil {
+		return writeTakeoverErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "takeover not found"}})
+	}
+	return response.Write(c, fiber.StatusOK, out.Data)
+}
+
+// UpdateTakeover godoc
+// @Summary Replace takeover by flight UUID
+// @Tags Flight - Takeovers
+// @Accept json
+// @Produce json
+// @Param id path string true "Flight UUID"
+// @Param request body requestdto.TakeoverUpdateRequest true "Update takeover request"
+// @Success 200 {object} responsedto.TakeoverResponse
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Router /api/v1/takeovers/update/{id} [patch]
+func (h *TakeoverHandler) UpdateTakeover(c *fiber.Ctx) error {
+	takeoverSvc := h.takeoverService()
+	if h == nil || takeoverSvc == nil {
+		logTakeoverError(c, "UpdateTakeover", errors.New("takeover service is not configured"))
+		return writeTakeoverErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{Status: "500", Title: "Update failed", Detail: "takeover service is not configured"}})
+	}
+	idRaw := strings.TrimSpace(c.Params("id"))
+	id, err := uuidv7.ParseString(idRaw)
+	if err != nil {
+		return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "id is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/data/id"}}})
+	}
+	existingFlight, err := h.flight.GetByID(c.UserContext(), id)
+	if err != nil || existingFlight == nil {
+		return writeTakeoverErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "takeover not found"}})
+	}
+	var req requestdto.TakeoverUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		logTakeoverError(c, "UpdateTakeover", err)
+		return writeTakeoverErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Invalid JSON", Detail: safeInternalDetail()}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	var errObj *jsonapi.ErrorObject
+	var baseID []byte
+	if req.Data.Attributes.BaseID != nil && strings.TrimSpace(*req.Data.Attributes.BaseID) != "" {
+		baseID, errObj = parseTakeoverUUID(*req.Data.Attributes.BaseID, "/data/attributes/base_id")
+		if errObj != nil {
+			return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+	}
+	var dutyDate time.Time
+	if req.Data.Attributes.DutyDate != nil && strings.TrimSpace(*req.Data.Attributes.DutyDate) != "" {
+		dutyDate, errObj = parseTakeoverDate(*req.Data.Attributes.DutyDate)
+		if errObj != nil {
+			return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+	}
+	var helicopterID []byte
+	if req.Data.Attributes.AircraftID != nil && strings.TrimSpace(*req.Data.Attributes.AircraftID) != "" {
+		helicopterID, errObj = parseTakeoverUUID(*req.Data.Attributes.AircraftID, "/data/attributes/helicopter_id")
+		if errObj != nil {
+			return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+	}
+	var inspection *requestdto.ReserveAcInspectionCreateAttributes
+	if req.Data.Attributes.Inspection != nil {
+		inspection = req.Data.Attributes.Inspection
+	}
+	filesAdd := takeoverFileCreateInputs(req.Data.Attributes.Files, req.Data.Attributes.FilesAdd)
+	filesRemove := req.Data.Attributes.FilesRemove
+	filesReplace := req.Data.Attributes.FilesReplace
+	if len(filesReplace) > 0 && (len(filesAdd) > 0 || len(filesRemove) > 0) {
+		return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "files_replace cannot be combined with files, files_add, or files_remove",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/files_replace"},
+		}})
+	}
+	if appErr := h.helicopterGroundedError(c.UserContext(), helicopterID, h.existingTakeoverHelicopterID(c.UserContext(), existingFlight)); appErr != nil {
+		return apperrorsx.Write(c, appErr)
+	}
+	if len(existingFlight.ReserveAcID) == 16 && h.hasAfterFlightInspection(c.UserContext(), existingFlight.ReserveAcID) {
+		if req.Data.Attributes.BaseID != nil || req.Data.Attributes.Bases != nil {
+			return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "base_id cannot be changed after after_flight_inspection exists",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/base_id"},
+			}})
+		}
+		if req.Data.Attributes.Detail != nil || req.Data.Attributes.RosterDetail != nil {
+			return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "roster_detail cannot be changed after after_flight_inspection exists",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/roster_detail"},
+			}})
+		}
+	}
+	out, err := takeoverSvc.Replace(c.UserContext(), existingFlight.ID, service.TakeoverCreateInput{
+		BaseID:          baseID,
+		HasBaseID:       baseID != nil,
+		DutyDate:        dutyDate,
+		HasDutyDate:     req.Data.Attributes.DutyDate != nil && strings.TrimSpace(*req.Data.Attributes.DutyDate) != "",
+		Notes:           req.Data.Attributes.Notes,
+		RosterDetail:    takeoverRosterDetailInput(req.Data.Attributes.Detail),
+		HasRosterDetail: req.Data.Attributes.Detail != nil,
+		HelicopterID:    helicopterID,
+		HasHelicopterID: helicopterID != nil,
+		Inspection:      inspection,
+		HasInspection:   inspection != nil,
+		ActorUserID:     actorUserID(c),
+	})
+	if err != nil {
+		logTakeoverError(c, "UpdateTakeover", err)
+		if appErr := takeoverAppErrorFromServiceErr(err); appErr != nil {
+			return apperrorsx.Write(c, appErr)
+		}
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTakeoverUpdateFailed).WithCause(err))
+	}
+	if err := h.applyTakeoverUpdateFiles(c, takeoverSvc, existingFlight.TakeoverAcID, filesAdd, filesRemove, filesReplace); err != nil {
+		return err
+	}
+	responseTakeoverID := out.TakeoverAcID
+	if len(responseTakeoverID) != 16 {
+		responseTakeoverID = existingFlight.TakeoverAcID
+	}
+	outResp, respErr := h.buildTakeoverResponse(c, responseTakeoverID)
+	if respErr != nil {
+		logTakeoverError(c, "UpdateTakeover.buildResponse", respErr)
+		return writeTakeoverErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Update failed", Detail: respErr.Error()}})
+	}
+	if outResp == nil {
+		return writeTakeoverErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{Status: "500", Title: "Update failed", Detail: "takeover response not available"}})
+	}
+	return response.Write(c, fiber.StatusOK, outResp.Data)
+}
+
+func takeoverFileCreateInputs(primary, fallback []requestdto.TakeoverCreateFileInput) []requestdto.TakeoverCreateFileInput {
+	total := len(primary) + len(fallback)
+	if total == 0 {
+		return nil
+	}
+	out := make([]requestdto.TakeoverCreateFileInput, 0, total)
+	out = append(out, primary...)
+	out = append(out, fallback...)
+	return out
+}
+
+func (h *TakeoverHandler) applyTakeoverUpdateFiles(
+	c *fiber.Ctx,
+	takeoverSvc *service.TakeoverService,
+	takeoverID []byte,
+	filesAdd []requestdto.TakeoverCreateFileInput,
+	filesRemove []string,
+	filesReplace []requestdto.TakeoverCreateFileInput,
+) error {
+	if len(filesAdd) == 0 && len(filesRemove) == 0 && len(filesReplace) == 0 {
+		return nil
+	}
+	if h.fileManager == nil {
+		logTakeoverError(c, "TakeoverFiles.FileManager", errors.New("file manager service is not configured"))
+		return writeTakeoverErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Update failed", Detail: "file manager service is not configured"}})
+	}
+
+	current, err := takeoverSvc.GetByID(c.UserContext(), takeoverID)
+	if err != nil {
+		logTakeoverError(c, "TakeoverFiles.GetByID", err)
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTakeoverUpdateFailed).WithCause(err))
+	}
+	if current == nil {
+		return writeTakeoverErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "takeover not found"}})
+	}
+
+	existingFiles := make(map[string]takeover.TakeoverFile, len(current.Files))
+	for i := range current.Files {
+		existingFiles[idString(current.Files[i].FileAttachmentID)] = current.Files[i]
+	}
+
+	if len(filesReplace) > 0 {
+		filesAdd = filesReplace
+		filesRemove = filesRemove[:0]
+		for i := range current.Files {
+			filesRemove = append(filesRemove, idString(current.Files[i].FileAttachmentID))
+		}
+	}
+
+	for i := range filesRemove {
+		attachmentID, errObj := parseTakeoverUUID(filesRemove[i], "/data/attributes/files_remove/"+strconv.Itoa(i))
+		if errObj != nil {
+			return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		attachmentKey := idString(attachmentID)
+		if _, ok := existingFiles[attachmentKey]; !ok {
+			return writeTakeoverErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "takeover file not found",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/files_remove/" + strconv.Itoa(i)},
+			}})
+		}
+		if err := takeoverSvc.DetachFile(c.UserContext(), takeoverID, attachmentID); err != nil {
+			logTakeoverError(c, "TakeoverFiles.DetachFile", err)
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return writeTakeoverErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+					Status: "404",
+					Title:  "Not found",
+					Detail: "takeover file not found",
+					Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/files_remove/" + strconv.Itoa(i)},
+				}})
+			}
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTakeoverUpdateFailed).WithCause(err))
+		}
+		if err := h.fileManager.DeleteAttachment(c.UserContext(), attachmentID); err != nil {
+			logTakeoverError(c, "TakeoverFiles.DeleteAttachment", err)
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTakeoverUpdateFailed).WithCause(err))
+		}
+	}
+
+	if len(filesAdd) == 0 {
+		return nil
+	}
+	return h.attachTakeoverCreateFiles(c, takeoverSvc, takeoverID, filesAdd)
+}
+
+func (h *TakeoverHandler) attachTakeoverCreateFiles(c *fiber.Ctx, takeoverSvc *service.TakeoverService, takeoverID []byte, files []requestdto.TakeoverCreateFileInput) error {
+	if len(files) == 0 {
+		return nil
+	}
+	if h.fileManager == nil {
+		logTakeoverError(c, "TakeoverFiles.FileManager", errors.New("file manager service is not configured"))
+		return writeTakeoverErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Create failed", Detail: "file manager service is not configured"}})
+	}
+	for i := range files {
+		item := files[i]
+		var fileID []byte
+		if strings.TrimSpace(item.FileID) != "" {
+			parsedFileID, errObj := parseTakeoverUUID(item.FileID, "/data/attributes/files/"+strconv.Itoa(i)+"/file_id")
+			if errObj != nil {
+				return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+			}
+			fileID = parsedFileID
+		} else {
+			if strings.TrimSpace(item.UploadIntentUUID) == "" {
+				return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+					Status: "422",
+					Title:  "Validation error",
+					Detail: "file_id or upload_intent_uuid is required",
+					Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/files/" + strconv.Itoa(i)},
+				}})
+			}
+			uploadIntentID, errObj := parseTakeoverUUID(item.UploadIntentUUID, "/data/attributes/files/"+strconv.Itoa(i)+"/upload_intent_uuid")
+			if errObj != nil {
+				return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+			}
+			createdFile, createErr := h.fileManager.CreateFileNodeFromUploadIntent(c.UserContext(), filemanager.CreateFileFromUploadIntentParams{
+				UploadIntentID: uploadIntentID,
+				Name:           strings.TrimSpace(item.Name),
+				ActorID:        actorUserID(c),
+			})
+			if createErr != nil {
+				logTakeoverError(c, "TakeoverFiles.CreateFile", createErr)
+				return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTakeoverCreateFailed).WithCause(createErr))
+			}
+			fileID = createdFile.ID
+		}
+		attachment, attachErr := h.fileManager.CreateAttachment(c.UserContext(), filemanager.CreateAttachmentParams{
+			FileID:    fileID,
+			RefType:   "takeover",
+			RefID:     idString(takeoverID),
+			SortOrder: 0,
+			IsPrimary: false,
+			ActorID:   actorUserID(c),
+		})
+		if attachErr != nil {
+			logTakeoverError(c, "TakeoverFiles.CreateAttachment", attachErr)
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTakeoverCreateFailed).WithCause(attachErr))
+		}
+		if err := takeoverSvc.AttachFile(c.UserContext(), takeoverID, attachment.ID); err != nil {
+			logTakeoverError(c, "TakeoverFiles.AttachFile", err)
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTakeoverCreateFailed).WithCause(err))
+		}
+	}
+	return nil
+}
+
+func (h *TakeoverHandler) attachTakeoverEditedTemplateFiles(c *fiber.Ctx, takeoverSvc *service.TakeoverService, takeoverID []byte, fileIDs []string) error {
+	if len(fileIDs) == 0 {
+		return nil
+	}
+	if h.fileManager == nil {
+		logTakeoverError(c, "TakeoverEditedTemplateFiles.FileManager", errors.New("file manager service is not configured"))
+		return writeTakeoverErrors(c, fiber.StatusServiceUnavailable, []jsonapi.ErrorObject{{Status: "503", Title: "Create failed", Detail: "file manager service is not configured"}})
+	}
+	for i := range fileIDs {
+		fileID, errObj := parseTakeoverUUID(fileIDs[i], "/data/attributes/edited_template_file_ids/"+strconv.Itoa(i))
+		if errObj != nil {
+			return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{*errObj})
+		}
+		row, err := h.fileManager.GetFileByIDAny(c.UserContext(), fileID)
+		if err != nil {
+			logTakeoverError(c, "TakeoverEditedTemplateFiles.GetFile", err)
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTakeoverCreateFailed).WithCause(err))
+		}
+		if row == nil {
+			return writeTakeoverErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "edited template file not found",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/edited_template_file_ids/" + strconv.Itoa(i)},
+			}})
+		}
+		if !takeoverEditedTemplateFileBelongsToTakeover(row, takeoverID) {
+			return writeTakeoverErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "edited template file not found",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/edited_template_file_ids/" + strconv.Itoa(i)},
+			}})
+		}
+		if !bytes.Equal(row.CreatedBy, actorUserID(c)) {
+			return writeTakeoverErrors(c, fiber.StatusForbidden, []jsonapi.ErrorObject{{
+				Status: "403",
+				Title:  "Forbidden",
+				Detail: "forbidden access",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/edited_template_file_ids/" + strconv.Itoa(i)},
+			}})
+		}
+		attachment, attachErr := h.fileManager.CreateAttachment(c.UserContext(), filemanager.CreateAttachmentParams{
+			FileID:    fileID,
+			RefType:   "takeover",
+			RefID:     idString(takeoverID),
+			SortOrder: 0,
+			IsPrimary: false,
+			ActorID:   actorUserID(c),
+		})
+		if attachErr != nil {
+			logTakeoverError(c, "TakeoverEditedTemplateFiles.CreateAttachment", attachErr)
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTakeoverCreateFailed).WithCause(attachErr))
+		}
+		if err := takeoverSvc.AttachFile(c.UserContext(), takeoverID, attachment.ID); err != nil {
+			logTakeoverError(c, "TakeoverEditedTemplateFiles.AttachFile", err)
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTakeoverCreateFailed).WithCause(err))
+		}
+	}
+	return nil
+}
+
+func takeoverEditedTemplateFileBelongsToTakeover(row *filemanager.File, takeoverID []byte) bool {
+	if row == nil {
+		return false
+	}
+	if len(row.TakeoverID) == 0 {
+		return true
+	}
+	return len(row.TakeoverID) == 16 && len(takeoverID) == 16 && bytes.Equal(row.TakeoverID, takeoverID)
+}
+
+// DeleteTakeover godoc
+// @Summary Delete takeover by flight UUID
+// @Tags Flight - Takeovers
+// @Produce json
+// @Param id path string true "Flight UUID"
+// @Success 200 {object} map[string]any
+// @Failure 400 {object} jsonapi.ErrorDocument
+// @Failure 404 {object} jsonapi.ErrorDocument
+// @Router /api/v1/takeovers/delete/{id} [delete]
+func (h *TakeoverHandler) DeleteTakeover(c *fiber.Ctx) error {
+	idRaw := strings.TrimSpace(c.Params("id"))
+	id, err := uuidv7.ParseString(idRaw)
+	if err != nil {
+		return writeTakeoverErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{Status: "422", Title: "Validation error", Detail: "id is invalid UUID", Source: &jsonapi.ErrorSource{Pointer: "/path/id"}}})
+	}
+	flightRow, err := h.flight.GetByID(c.UserContext(), id)
+	if err != nil || flightRow == nil {
+		if err != nil {
+			logTakeoverError(c, "DeleteTakeover", err)
+		}
+		return writeTakeoverErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "takeover not found"}})
+	}
+	takeoverAcID := flightRow.TakeoverAcID
+	if len(takeoverAcID) != 16 {
+		return writeTakeoverErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "takeover not found"}})
+	}
+	if err := h.flight.Delete(c.UserContext(), flightRow.ID, actorUserID(c)); err != nil {
+		logTakeoverError(c, "DeleteTakeover", err)
+		return writeTakeoverErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Delete failed", Detail: safeInternalDetail()}})
+	}
+	if row, _ := h.reserveAc.GetByID(c.UserContext(), flightRow.ReserveAcID); row != nil {
+		_ = h.reserveAc.Delete(c.UserContext(), row.ID, actorUserID(c))
+	}
+	if h.db != nil && len(takeoverAcID) == 16 {
+		_ = softDeleteTakeoverRosterChildren(c.UserContext(), h.db, takeoverAcID, actorUserID(c))
+	}
+	if h.takeoverAc != nil {
+		_ = h.takeoverAc.Delete(c.UserContext(), takeoverAcID, actorUserID(c))
+	}
+	return response.Write(c, fiber.StatusOK, map[string]any{"data": map[string]any{"deleted": true, "takeover_ac_id": idString(takeoverAcID), "flight_id": idString(flightRow.ID)}})
+}
+
+func (h *TakeoverHandler) buildTakeoverResponse(c *fiber.Ctx, flightID []byte) (*responsedto.TakeoverResponse, error) {
+	if h.takeoverAc == nil {
+		return nil, errors.New("takeover service is not configured")
+	}
+	takeoverRow, err := h.takeoverAc.GetByID(c.UserContext(), flightID)
+	if err != nil {
+		logTakeoverError(c, "buildTakeoverResponse.takeoverAc.GetByID", err)
+		return nil, err
+	}
+	if takeoverRow == nil && h.flight != nil {
+		flightRow, ferr := h.flight.GetByID(c.UserContext(), flightID)
+		if ferr != nil || flightRow == nil || len(flightRow.TakeoverAcID) != 16 {
+			return nil, nil
+		}
+		takeoverRow, err = h.takeoverAc.GetByID(c.UserContext(), flightRow.TakeoverAcID)
+		if err != nil || takeoverRow == nil {
+			if err != nil {
+				logTakeoverError(c, "buildTakeoverResponse.takeoverAc.GetByIDFallback", err)
+			}
+			return nil, err
+		}
+	}
+	if takeoverRow == nil {
+		return nil, nil
+	}
+	var flightRow *flight.Flight
+	if h.flight != nil {
+		flightRow, _ = h.flight.GetByTakeoverAcID(c.UserContext(), takeoverRow.ID)
+	}
+	reserveRow := h.resolveTakeoverReserveRow(c, takeoverRow, flightRow)
+	inspectionSummary := h.resolveTakeoverInspectionSummary(c, reserveRow)
+	dutyResource := h.resolveTakeoverDutyResource(c, flightRow)
+	attrs := h.buildTakeoverResponseAttributes(c, takeoverRow, flightRow, reserveRow, inspectionSummary, dutyResource)
+	return &responsedto.TakeoverResponse{
+		Data: responsedto.TakeoverResource{
+			Type:       "takeover",
+			Attributes: attrs,
+		},
+	}, nil
+}
+
+func (h *TakeoverHandler) buildTakeoverResponseFromRows(c *fiber.Ctx, takeoverRow *takeover.TakeoverAc, flightRow *flight.Flight) (*responsedto.TakeoverResponse, error) {
+	if takeoverRow == nil || flightRow == nil {
+		return nil, nil
+	}
+	reserveRow := h.resolveTakeoverReserveRow(c, takeoverRow, flightRow)
+	inspectionSummary := h.resolveTakeoverInspectionSummary(c, reserveRow)
+	dutyResource := h.resolveTakeoverDutyResource(c, flightRow)
+	attrs := h.buildTakeoverResponseAttributes(c, takeoverRow, flightRow, reserveRow, inspectionSummary, dutyResource)
+	return &responsedto.TakeoverResponse{
+		Data: responsedto.TakeoverResource{
+			Type:       "takeover",
+			Attributes: attrs,
+		},
+	}, nil
+}
+
+func (h *TakeoverHandler) resolveTakeoverReserveRow(c *fiber.Ctx, takeoverRow *takeover.TakeoverAc, flightRow *flight.Flight) *reserveac.ReserveAc {
+	if takeoverRow != nil && takeoverRow.ReserveAc != nil {
+		return takeoverRow.ReserveAc
+	}
+	if flightRow == nil || h == nil || h.reserveAc == nil || len(flightRow.ReserveAcID) != 16 {
+		return nil
+	}
+	reserveRow, _ := h.reserveAc.GetByID(c.UserContext(), flightRow.ReserveAcID)
+	return reserveRow
+}
+
+func (h *TakeoverHandler) resolveTakeoverInspectionSummary(c *fiber.Ctx, reserveRow *reserveac.ReserveAc) *shareddto.ReserveAcInspectionSummary {
+	if reserveRow == nil {
+		return nil
+	}
+	summary, _ := h.buildCreateInspectionSummary(c, reserveRow.InspectionID, reserveRow.AircraftID)
+	return summary
+}
+
+func (h *TakeoverHandler) resolveTakeoverDutyResource(c *fiber.Ctx, flightRow *flight.Flight) responsedto.DutyRosterResource {
+	dutyResource := responsedto.DutyRosterResource{
+		Type: "duty_roster",
+		Attributes: responsedto.DutyRosterAttributes{
+			Bases:     responsedto.DutyRosterBaseInfo{},
+			ShiftTime: responsedto.DutyRosterShiftTime{},
+			Detail:    responsedto.DutyRosterDetailsResponse{Pilot: []responsedto.DutyRosterPilotCrew{}, Doctor: []responsedto.DutyRosterCrew{}, Rescuer: []responsedto.DutyRosterCrew{}, Helper: []responsedto.DutyRosterCrew{}, OtherPerson: []responsedto.DutyRosterCrew{}},
+		},
+	}
+	if h == nil || h.db == nil || flightRow == nil || len(flightRow.TakeoverAcID) != 16 {
+		return dutyResource
+	}
+	if rows, err := loadTakeoverRosterCrewRows(c.UserContext(), h.db, flightRow.TakeoverAcID); err == nil {
+		dutyResource = buildDutyRosterResourceFromTakeoverRows(dutyResource, rows, flightRow)
+	}
+	if others, err := loadTakeoverOtherPeopleRows(c.UserContext(), h.db, flightRow.TakeoverAcID); err == nil {
+		dutyResource = buildDutyRosterResourceFromOtherPeople(dutyResource, others)
+	}
+	if takeoverRow, err := h.takeoverAc.GetByID(c.UserContext(), flightRow.TakeoverAcID); err == nil && takeoverRow != nil {
+		shiftTime := h.resolveTakeoverShiftTime(c, takeoverRow.BaseID, flightRow.Date)
+		if takeoverRow.Base != nil {
+			dutyResource.Attributes.Bases = responsedto.DutyRosterBaseInfo{
+				ID:               idString(takeoverRow.BaseID),
+				Type:             "hems",
+				BaseName:         strings.TrimSpace(takeoverRow.Base.BaseName),
+				BaseAbbreviation: strings.TrimSpace(takeoverRow.Base.BaseAbbreviation),
+				ShiftTime:        shiftTime,
+			}
+		} else if baseInfo := h.takeoverBaseInfo(c, &dutyResource, takeoverRow.BaseID); baseInfo != nil {
+			dutyResource.Attributes.Bases = *baseInfo
+		}
+		if shiftTime != (responsedto.DutyRosterShiftTime{}) {
+			dutyResource.Attributes.ShiftTime = shiftTime
+		} else if len(takeoverRow.BaseID) == 16 && h.db != nil {
+			if shiftStart, shiftEnd, serr := service.ResolveBaseShiftRangeTx(h.db.WithContext(c.UserContext()), takeoverRow.BaseID, flightRow.Date); serr == nil {
+				dutyResource.Attributes.ShiftTime = responsedto.DutyRosterShiftTime{ShiftStart: shiftStart, ShiftEnd: shiftEnd}
+			}
+		}
+	}
+	normalizeTakeoverDutyRosterDetail(&dutyResource)
+	return dutyResource
+}
+
+func (h *TakeoverHandler) buildTakeoverResponseAttributes(
+	c *fiber.Ctx,
+	takeoverRow *takeover.TakeoverAc,
+	flightRow *flight.Flight,
+	reserveRow *reserveac.ReserveAc,
+	inspectionSummary *shareddto.ReserveAcInspectionSummary,
+	dutyResource responsedto.DutyRosterResource,
+) responsedto.TakeoverResponseAttributes {
+	shiftTime := dutyResource.Attributes.ShiftTime
+	if shiftTime == (responsedto.DutyRosterShiftTime{}) {
+		var dutyDate time.Time
+		if flightRow != nil {
+			dutyDate = flightRow.Date
+		}
+		shiftTime = h.resolveTakeoverShiftTime(c, takeoverRow.BaseID, dutyDate)
+	}
+	attrs := responsedto.TakeoverResponseAttributes{
+		ID:           idString(takeoverRow.ID),
+		ShiftStart:   shiftTime.ShiftStart,
+		ShiftEnd:     shiftTime.ShiftEnd,
+		BaseID:       idString(takeoverRow.BaseID),
+		DutyDate:     dutyResource.Attributes.DutyDate,
+		RosterDetail: takeoverDutyRosterDetailsFromRosterDetails(dutyResource.Attributes.Detail),
+		CreatedBy:    uuidStringOrEmpty(takeoverRow.CreatedBy),
+		UpdatedBy:    uuidStringOrEmpty(takeoverRow.UpdatedBy),
+	}
+	if !takeoverRow.CreatedAt.IsZero() {
+		attrs.CreatedAt = takeoverRow.CreatedAt.UTC().Format(time.RFC3339)
+	}
+	if !takeoverRow.UpdatedAt.IsZero() {
+		attrs.UpdatedAt = takeoverRow.UpdatedAt.UTC().Format(time.RFC3339)
+	}
+	if takeoverRow.Base != nil {
+		attrs.Base = &responsedto.DutyRosterBaseInfo{
+			ID:               idString(takeoverRow.BaseID),
+			Type:             "hems",
+			BaseName:         strings.TrimSpace(takeoverRow.Base.BaseName),
+			BaseAbbreviation: strings.TrimSpace(takeoverRow.Base.BaseAbbreviation),
+			ShiftTime:        shiftTime,
+		}
+	} else {
+		attrs.Base = h.takeoverBaseInfo(c, &dutyResource, takeoverRow.BaseID)
+	}
+	if flightRow != nil {
+		attrs.FlightID = idString(flightRow.ID)
+	}
+	attrs.Notes = takeoverRow.Notes
+	if reserveRow != nil {
+		attrs.ReserveAcID = idString(reserveRow.ID)
+		attrs.FlightInspectionID = idString(reserveRow.InspectionID)
+		if reserveRow.Aircraft != nil {
+			attrs.HelicopterID = idString(reserveRow.Aircraft.ID)
+		} else {
+			attrs.HelicopterID = idString(reserveRow.AircraftID)
+		}
+		ctx := context.Background()
+		if c != nil {
+			ctx = c.UserContext()
+		}
+		attrs.Helicopter = h.takeoverHelicopterResource(ctx, reserveRow)
+	}
+	if inspectionSummary != nil {
+		attrs.Inspection = *inspectionSummary
+	}
+	ctx := context.Background()
+	if c != nil {
+		ctx = c.UserContext()
+	}
+	files := takeoverRow.Files
+	if len(files) == 0 && h != nil && h.db != nil {
+		if loaded, err := loadTakeoverFilesByTakeoverID(ctx, h.db, takeoverRow.ID); err == nil && len(loaded) > 0 {
+			files = loaded
+		}
+	}
+	if len(files) == 0 && h != nil && h.db != nil {
+		if loaded, err := loadTakeoverFilesByAttachmentRef(ctx, h.db, takeoverRow.ID); err == nil && len(loaded) > 0 {
+			files = takeoverFilesFromAttachments(loaded)
+		}
+	}
+	attrs.Files = takeoverFileResources(ctx, h.storage, files)
+	return attrs
+}
+
+func loadTakeoverFilesByTakeoverID(ctx context.Context, db *gorm.DB, takeoverID []byte) ([]takeover.TakeoverFile, error) {
+	rows := make([]takeover.TakeoverFile, 0)
+	if db == nil || len(takeoverID) != 16 {
+		return rows, nil
+	}
+	if err := db.WithContext(ctx).
+		Where("takeover_id = ?", takeoverID).
+		Order("id ASC").
+		Preload("FileAttachment").
+		Preload("FileAttachment.File").
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func loadTakeoverFilesByAttachmentRef(ctx context.Context, db *gorm.DB, takeoverID []byte) ([]filemanager.Attachment, error) {
+	rows := make([]filemanager.Attachment, 0)
+	if db == nil || len(takeoverID) != 16 {
+		return rows, nil
+	}
+	if err := db.WithContext(ctx).
+		Where("ref_type = ? AND ref_id = ?", "takeover", idString(takeoverID)).
+		Order("sort_order ASC, created_at ASC, id ASC").
+		Preload("File").
+		Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	return rows, nil
+}
+
+func takeoverFilesFromAttachments(attachments []filemanager.Attachment) []takeover.TakeoverFile {
+	if len(attachments) == 0 {
+		return nil
+	}
+	out := make([]takeover.TakeoverFile, 0, len(attachments))
+	for i := range attachments {
+		att := attachments[i]
+		clone := att
+		out = append(out, takeover.TakeoverFile{
+			ID:               append([]byte(nil), att.ID...),
+			FileAttachmentID: append([]byte(nil), att.ID...),
+			FileAttachment:   &clone,
+		})
+	}
+	return out
+}
+
+func takeoverFileResources(ctx context.Context, storage fileManagerDownloadURLStorage, files []takeover.TakeoverFile) []responsedto.TakeoverFileResource {
+	if len(files) == 0 {
+		return nil
+	}
+	out := make([]responsedto.TakeoverFileResource, 0, len(files))
+	for i := range files {
+		// Documents created from a template (via /files/create-from-template) are attached
+		// to the takeover for WOPI editing, but must not surface in the takeover files
+		// listing — only regular attached files are shown there.
+		if takeoverFileCreatedFromTemplate(&files[i]) {
+			continue
+		}
+		item := responsedto.TakeoverFileResource{
+			Type: "takeover_file",
+			ID:   idString(files[i].ID),
+			Attributes: responsedto.TakeoverFileAttributes{
+				FileAttachmentID: idString(files[i].FileAttachmentID),
+			},
+		}
+		if files[i].FileAttachment != nil && files[i].FileAttachment.File != nil {
+			file := files[i].FileAttachment.File
+			item.Attributes.FileName = strings.TrimSpace(file.Name)
+			item.Attributes.DownloadURL = resolveFileManagerDownloadURL(ctx, storage, file)
+		}
+		out = append(out, item)
+	}
+	return out
+}
+
+// takeoverFileCreatedFromTemplate reports whether a takeover file points to a document
+// instantiated from a template (identified by a non-empty template_uuid on the underlying
+// file). Such files stay attached in the database for WOPI editing but are hidden from the
+// takeover files listing.
+func takeoverFileCreatedFromTemplate(row *takeover.TakeoverFile) bool {
+	if row == nil || row.FileAttachment == nil || row.FileAttachment.File == nil {
+		return false
+	}
+	return len(row.FileAttachment.File.TemplateUUID) == 16
+}
+
+func (h *TakeoverHandler) buildCreateInspectionSummary(c *fiber.Ctx, inspectionID []byte, helicopterID []byte) (*shareddto.ReserveAcInspectionSummary, error) {
+	if h.inspect == nil || h.fileCk == nil || h.heliFile == nil || h.before == nil || h.prep == nil {
+		return nil, errors.New("inspection services are not configured")
+	}
+	inspection, err := h.inspect.GetByID(c.UserContext(), inspectionID)
+	if err != nil || inspection == nil {
+		return nil, err
+	}
+	ckRows, err := h.fileCk.ListByInspectionID(c.UserContext(), inspectionID)
+	if err != nil {
+		return nil, err
+	}
+	isDoneByHeliFileID := make(map[string]bool, len(ckRows))
+	for i := range ckRows {
+		isDoneByHeliFileID[idString(ckRows[i].HelicopterFileID)] = ckRows[i].IsDone
+	}
+	beforeRows, err := h.heliFile.ListByHelicopterAndSection(c.UserContext(), helicopterID, helicopterfile.SectionBeforeFirstFlightInspection)
+	if err != nil {
+		return nil, err
+	}
+	prepareRows, err := h.heliFile.ListByHelicopterAndSection(c.UserContext(), helicopterID, helicopterfile.SectionFlightPreparationAndWB)
+	if err != nil {
+		return nil, err
+	}
+	beforeData, _ := h.before.GetByFlightInspectionID(c.UserContext(), inspectionID)
+	prepareData, _ := h.prep.GetByFlightInspection(c.UserContext(), inspectionID)
+	beforeSection := h.buildChecklistSectionSummary(c, beforeRows, isDoneByHeliFileID)
+	prepareSection := h.buildChecklistSectionSummary(c, prepareRows, isDoneByHeliFileID)
+	fleetStatusFileSection := h.buildFleetStatusFileSection(c, helicopterID)
+	out := &shareddto.ReserveAcInspectionSummary{
+		ID:             idString(inspection.ID),
+		InspectionDate: calendarDateString(inspection.InspectionDate),
+		Before: shareddto.ReserveAcBeforeSectionDTO{
+			Total:         beforeSection.Total,
+			Completed:     beforeSection.Completed,
+			DoneFiles:     beforeSection.DoneFiles,
+			FileChecklist: beforeSection.FileChecklist,
+		},
+		Prepare: shareddto.ReserveAcPrepareSectionDTO{
+			Total:         prepareSection.Total,
+			Completed:     prepareSection.Completed,
+			DoneFiles:     prepareSection.DoneFiles,
+			FileChecklist: prepareSection.FileChecklist,
+		},
+		FleetStatusFile: fleetStatusFileSection,
+	}
+	if beforeData != nil {
+		out.Before.Fields = &shareddto.ReserveAcBeforeInspectionFields{
+			OilEngineNR1Checked:       beforeData.OilEngineNR1Checked,
+			OilEngineNR2Checked:       beforeData.OilEngineNR2Checked,
+			HydraulicLHChecked:        beforeData.HydraulicLHChecked,
+			HydraulicRHChecked:        beforeData.HydraulicRHChecked,
+			OilTransmissionMGBChecked: beforeData.OilTransmissionMGBChecked,
+			OilTransmissionIGBChecked: beforeData.OilTransmissionIGBChecked,
+			OilTransmissionTGBChecked: beforeData.OilTransmissionTGBChecked,
+			FuelAmount:                beforeData.FuelAmount,
+			FuelUnit:                  strings.TrimSpace(beforeData.FuelUnit),
+			FuelAddedAmount:           beforeData.FuelAddedAmount,
+		}
+	}
+	if prepareData != nil {
+		out.Prepare.PrepareFields = &shareddto.ReserveAcPrepareFields{
+			NotamBriefing:         boolPtr(prepareData.NOTAMBriefing),
+			WeatherBriefing:       boolPtr(prepareData.WeatherBriefing),
+			OperationalFlightPlan: boolPtr(prepareData.OperationalFlightPlan),
+		}
+	}
+	return out, nil
+}
+
+func (h *TakeoverHandler) buildFleetStatusFileSection(c *fiber.Ctx, helicopterID []byte) shareddto.ReserveAcFleetStatusFileSectionDTO {
+	if h == nil || h.fleetStatus == nil || len(helicopterID) != 16 {
+		return shareddto.ReserveAcFleetStatusFileSectionDTO{}
+	}
+	latest, err := h.fleetStatus.LatestByHelicopterIDs(c.UserContext(), [][]byte{helicopterID})
+	if err != nil || latest == nil {
+		return shareddto.ReserveAcFleetStatusFileSectionDTO{}
+	}
+	row := latest[string(helicopterID)]
+	if row == nil || len(row.Files) == 0 {
+		return shareddto.ReserveAcFleetStatusFileSectionDTO{}
+	}
+	out := shareddto.ReserveAcFleetStatusFileSectionDTO{
+		Total:         len(row.Files),
+		Completed:     len(row.Files),
+		FileChecklist: make([]shareddto.ReserveAcFileChecklistItemDTO, 0, len(row.Files)),
+		DoneFiles:     make([]shareddto.ReserveAcFileChecklistItemDTO, 0, len(row.Files)),
+	}
+	for i := range row.Files {
+		item := shareddto.ReserveAcFileChecklistItemDTO{
+			HelicopterFileID: idString(row.Files[i].ID),
+			FileAttachmentID: idString(row.Files[i].FileAttachmentID),
+			IsDone:           true,
+			IsMandatory:      row.Files[i].IsMandatory,
+		}
+		if row.Files[i].Attachment != nil && row.Files[i].Attachment.File != nil {
+			file := row.Files[i].Attachment.File
+			item.FileName = strings.TrimSpace(file.Name)
+			if h.storage != nil {
+				asset := resolveFileManagerDownloadURLs(c.UserContext(), h.storage, file)
+				item.DownloadURL = strings.TrimSpace(asset.OriginalURL)
+			}
+		}
+		out.FileChecklist = append(out.FileChecklist, item)
+		out.DoneFiles = append(out.DoneFiles, item)
+	}
+	return out
+}
+
+func flightTakeoverStep(ctx context.Context, row *flight.Flight, takeoverSvc takeoverLookupService) responsedto.FlightStepItem {
+	if row == nil || len(row.TakeoverAcID) != 16 {
+		return responsedto.FlightStepItem{
+			Phase:    "takeover",
+			Position: "takeover",
+			Step:     1,
+			Complete: false,
+			Status:   "unassigned",
+		}
+	}
+	takeoverRow := resolveTakeoverRow(ctx, row, takeoverSvc)
+	if !takeoverRowIsComplete(takeoverRow) {
+		return responsedto.FlightStepItem{
+			Phase:    "takeover",
+			Position: "takeover",
+			Step:     1,
+			Complete: false,
+			Status:   "in_progress",
+			ID:       idString(row.TakeoverAcID),
+		}
+	}
+	return responsedto.FlightStepItem{
+		Phase:       "takeover",
+		Position:    "takeover",
+		Step:        1,
+		Complete:    true,
+		Status:      "completed",
+		ID:          idString(row.TakeoverAcID),
+		CompletedAt: row.CreatedAt.UTC().Format(time.RFC3339),
+		CompletedBy: takeoverCompletedBy(takeoverRow),
+	}
+}
+
+func takeoverCompletedBy(takeoverRow *takeover.TakeoverAc) string {
+	if takeoverRow == nil {
+		return ""
+	}
+	if short := strings.TrimSpace(userctx.GetShortName(context.Background(), takeoverRow.UpdatedBy)); short != "" {
+		return short
+	}
+	if short := strings.TrimSpace(userctx.GetShortName(context.Background(), takeoverRow.CreatedBy)); short != "" {
+		return short
+	}
+	for i := range takeoverRow.RosterCrews {
+		crew := takeoverRow.RosterCrews[i]
+		if !strings.EqualFold(strings.TrimSpace(crew.RoleCode), "pilot") {
+			continue
+		}
+		if short := strings.TrimSpace(userctx.GetShortName(context.Background(), crew.UserID)); short != "" {
+			return short
+		}
+		if label := strings.TrimSpace(crew.NameLabel); label != "" {
+			return label
+		}
+	}
+	return ""
+}
+
+// resolveTakeoverRow loads the takeover record for a flight, preferring the
+// lookup service and falling back to the row's eagerly-loaded association.
+// Returns nil when the id is missing or the lookup errors.
+func resolveTakeoverRow(ctx context.Context, row *flight.Flight, takeoverSvc takeoverLookupService) *takeover.TakeoverAc {
+	if row == nil || len(row.TakeoverAcID) != 16 {
+		return nil
+	}
+	var takeoverRow *takeover.TakeoverAc
+	if takeoverSvc != nil {
+		var err error
+		takeoverRow, err = takeoverSvc.GetByID(ctx, row.TakeoverAcID)
+		if err != nil {
+			return nil
+		}
+	}
+	if takeoverRow == nil {
+		takeoverRow = row.Takeover
+	}
+	return takeoverRow
+}
+
+func takeoverRowIsComplete(takeoverRow *takeover.TakeoverAc) bool {
+	if takeoverRow == nil {
+		return false
+	}
+	if len(takeoverRow.BaseID) != 16 {
+		return false
+	}
+	if len(takeoverRow.RosterCrews) == 0 && len(takeoverRow.OtherPeople) == 0 {
+		return false
+	}
+	if takeoverRow.ReserveAc == nil {
+		return false
+	}
+	if len(takeoverRow.ReserveAc.AircraftID) != 16 || takeoverRow.ReserveAc.Aircraft == nil {
+		return false
+	}
+	if takeoverRow.ReserveAc.Inspection == nil {
+		return false
+	}
+	return true
+}
+
+func takeoverDutyRosterResponse(resource *responsedto.DutyRosterResource, flightRow *flight.Flight) *responsedto.TakeoverDutyRosterResource {
+	if resource == nil {
+		return nil
+	}
+	helicopter := resource.Attributes.Helicopter
+	if helicopter.ID == "" && helicopter.Designation == "" && helicopter.Identifier == "" && helicopter.Type == "" {
+		if fallback := takeoverHelicopterFromFlight(flightRow); fallback != nil {
+			helicopter = *fallback
+		}
+	}
+	return &responsedto.TakeoverDutyRosterResource{
+		Type: resource.Type,
+		ID:   resource.ID,
+		Attributes: responsedto.TakeoverDutyRosterAttributes{
+			Bases:      resource.Attributes.Bases,
+			FlightID:   resource.Attributes.FlightID,
+			Helicopter: helicopter,
+			DutyDate:   resource.Attributes.DutyDate,
+			Detail:     takeoverDutyRosterDetailsFromRosterDetails(resource.Attributes.Detail),
+			CreatedBy:  resource.Attributes.CreatedBy,
+			CreatedAt:  resource.Attributes.CreatedAt,
+			UpdatedAt:  resource.Attributes.UpdatedAt,
+		},
+	}
+}
+
+func (h *TakeoverHandler) takeoverBaseInfo(c *fiber.Ctx, resource *responsedto.DutyRosterResource, baseID []byte) *responsedto.DutyRosterBaseInfo {
+	if resource != nil {
+		base := resource.Attributes.Bases
+		if base.ID != "" || base.Type != "" || base.BaseName != "" || base.BaseAbbreviation != "" {
+			if base.ShiftTime == (responsedto.DutyRosterShiftTime{}) {
+				if shift := h.resolveTakeoverShiftTime(c, baseID, parseDutyRosterDate(resource.Attributes.DutyDate)); shift != (responsedto.DutyRosterShiftTime{}) {
+					base.ShiftTime = shift
+				}
+			}
+			if base.ShiftTime == (responsedto.DutyRosterShiftTime{}) {
+				base.ShiftTime = resource.Attributes.ShiftTime
+			}
+			return &base
+		}
+	}
+	if len(baseID) == 0 {
+		return nil
+	}
+	out := &responsedto.DutyRosterBaseInfo{ID: idString(baseID)}
+	if row := h.takeoverBaseRow(c, baseID, "hems", "regular"); row != nil {
+		out.Type = takeoverBaseType(row)
+		out.BaseName = strings.TrimSpace(row.BaseName)
+		out.BaseAbbreviation = strings.TrimSpace(row.BaseAbbreviation)
+	}
+	if resource != nil {
+		out.ShiftTime = h.resolveTakeoverShiftTime(c, baseID, parseDutyRosterDate(resource.Attributes.DutyDate))
+		if out.ShiftTime == (responsedto.DutyRosterShiftTime{}) {
+			out.ShiftTime = resource.Attributes.ShiftTime
+		}
+	}
+	return out
+}
+
+func (h *TakeoverHandler) takeoverBaseRow(c *fiber.Ctx, baseID []byte, categories ...string) *basedomain.Base {
+	if h == nil || h.base == nil || len(baseID) != 16 {
+		return nil
+	}
+	ctx := context.Background()
+	if c != nil {
+		ctx = c.UserContext()
+	}
+	tried := map[string]struct{}{}
+	for _, category := range categories {
+		category = strings.TrimSpace(category)
+		if category == "" {
+			continue
+		}
+		if _, ok := tried[category]; ok {
+			continue
+		}
+		tried[category] = struct{}{}
+		row, err := h.base.GetBaseByID(ctx, baseID, category)
+		if err == nil && row != nil {
+			return row
+		}
+	}
+	return nil
+}
+
+func takeoverBaseType(row *basedomain.Base) string {
+	if row == nil {
+		return ""
+	}
+	if normalized, ok := basedomain.NormalizeCategoryType(row.BaseCategory.Key); ok {
+		return normalized
+	}
+	return ""
+}
+
+func (h *TakeoverHandler) resolveTakeoverShiftTime(c *fiber.Ctx, baseID []byte, dutyDate time.Time) responsedto.DutyRosterShiftTime {
+	if h == nil || h.db == nil || len(baseID) != 16 || dutyDate.IsZero() {
+		return responsedto.DutyRosterShiftTime{}
+	}
+	ctx := context.Background()
+	if c != nil {
+		ctx = c.UserContext()
+	}
+	shiftStart, shiftEnd, err := service.ResolveBaseShiftRangeTx(h.db.WithContext(ctx), baseID, dutyDate)
+	if err != nil || shiftStart == "" || shiftEnd == "" {
+		return responsedto.DutyRosterShiftTime{}
+	}
+	return responsedto.DutyRosterShiftTime{ShiftStart: shiftStart, ShiftEnd: shiftEnd}
+}
+
+func parseDutyRosterDate(value string) time.Time {
+	parsed, err := time.Parse("2006-01-02", strings.TrimSpace(value))
+	if err != nil {
+		return time.Time{}
+	}
+	return parsed
+}
+
+func calendarDateString(value time.Time) string {
+	if value.IsZero() {
+		return ""
+	}
+	return time.Date(value.Year(), value.Month(), value.Day(), 0, 0, 0, 0, time.UTC).Format("2006-01-02")
+}
+
+func takeoverHelicopterInfo(resource *responsedto.DutyRosterResource, helicopterID []byte) *responsedto.DutyRosterHelicopterSummary {
+	if resource != nil {
+		heli := resource.Attributes.Helicopter
+		if heli.ID != "" || heli.Designation != "" || heli.Identifier != "" || heli.Type != "" {
+			return &heli
+		}
+	}
+	if len(helicopterID) == 0 {
+		return nil
+	}
+	return &responsedto.DutyRosterHelicopterSummary{ID: idString(helicopterID)}
+}
+
+// takeoverHelicopterResource builds the selected helicopter for a takeover,
+// enriched with its last daily inspection and its maintenance schedule (the
+// "next due" per inspection type) from the helicopter's latest fleet status.
+func (h *TakeoverHandler) takeoverHelicopterResource(ctx context.Context, row *reserveac.ReserveAc) *responsedto.TakeoverHelicopter {
+	if row == nil {
+		return nil
+	}
+	helicopterID := row.AircraftID
+	heli := responsedto.TakeoverHelicopter{ID: idString(row.AircraftID)}
+	if row.Aircraft != nil {
+		helicopterID = row.Aircraft.ID
+		heli.ID = idString(row.Aircraft.ID)
+		heli.Designation = strings.TrimSpace(row.Aircraft.Designation)
+		heli.Identifier = strings.TrimSpace(row.Aircraft.Identifier)
+		heli.Type = strings.TrimSpace(row.Aircraft.Type)
+	}
+	if heli.ID == "" && heli.Designation == "" && heli.Identifier == "" && heli.Type == "" {
+		return nil
+	}
+	// Last daily inspection: reserveAc concretely implements the provider.
+	if provider, ok := h.reserveAc.(helicopterLastDailyInspectionProvider); ok {
+		heli.LastDailyInspection = helicopterLastDailyInspectionResource(ctx, provider, helicopterID)
+	}
+	heli.MaintenanceSchedules = h.takeoverMaintenanceSchedules(ctx, helicopterID)
+	return &heli
+}
+
+// takeoverMaintenanceSchedules returns the full inspection-type set (with due/ext)
+// from the helicopter's latest fleet status; empty entries when none exists.
+func (h *TakeoverHandler) takeoverMaintenanceSchedules(ctx context.Context, helicopterID []byte) []shareddto.MaintenanceScheduleAttributes {
+	var schedules []fleetstatus.MaintenanceSchedule
+	if h.fleetStatus != nil && len(helicopterID) == 16 {
+		if latest, err := h.fleetStatus.LatestByHelicopterIDs(ctx, [][]byte{helicopterID}); err == nil {
+			if fs := latest[string(helicopterID)]; fs != nil {
+				schedules = fs.MaintenanceSchedules
+			}
+		}
+	}
+	return fleetStatusMaintenanceSchedules(schedules)
+}
+
+func takeoverHelicopterFromFlight(row *flight.Flight) *responsedto.DutyRosterHelicopterSummary {
+	return nil
+}
+
+func (h *TakeoverHandler) buildChecklistSectionSummary(c *fiber.Ctx, files []helicopterfile.HelicopterFile, isDoneByHeliFileID map[string]bool) reserveAcChecklistSectionCommon {
+	out := reserveAcChecklistSectionCommon{
+		FileChecklist: make([]shareddto.ReserveAcFileChecklistItemDTO, 0, len(files)),
+		DoneFiles:     make([]shareddto.ReserveAcFileChecklistItemDTO, 0, len(files)),
+	}
+	for i := range files {
+		if takeoverChecklistFileCreatedFromTemplate(&files[i]) {
+			continue
+		}
+		fileID := idString(files[i].ID)
+		isDone := isDoneByHeliFileID[fileID]
+		if isDone {
+			out.Completed++
+		}
+		out.Total++
+		fileAttachmentID := ""
+		fileName := ""
+		if files[i].FileAttachment != nil {
+			fileAttachmentID = idString(files[i].FileAttachment.ID)
+			if files[i].FileAttachment.File != nil {
+				fileName = strings.TrimSpace(files[i].FileAttachment.File.Name)
+			}
+		}
+		downloadURL := ""
+		if files[i].FileAttachment != nil && files[i].FileAttachment.File != nil {
+			downloadURL = resolveFileManagerDownloadURL(c.UserContext(), h.storage, files[i].FileAttachment.File)
+		}
+		item := shareddto.ReserveAcFileChecklistItemDTO{
+			HelicopterFileID: fileID,
+			FileAttachmentID: fileAttachmentID,
+			FileName:         fileName,
+			DownloadURL:      downloadURL,
+			IsDone:           isDone,
+		}
+		out.FileChecklist = append(out.FileChecklist, item)
+		if item.IsDone {
+			out.DoneFiles = append(out.DoneFiles, item)
+		}
+	}
+	return out
+}
+
+// takeoverChecklistFileCreatedFromTemplate reports whether a helicopter file row is a
+// document instantiated from a template. Those rows should remain hidden from checklist
+// summaries, which only surface the template catalog entries themselves.
+func takeoverChecklistFileCreatedFromTemplate(row *helicopterfile.HelicopterFile) bool {
+	if row == nil {
+		return false
+	}
+	if row.SourceFile != nil {
+		return len(row.SourceFile.TemplateUUID) == 16
+	}
+	if row.FileAttachment != nil && row.FileAttachment.File != nil {
+		return len(row.FileAttachment.File.TemplateUUID) == 16
+	}
+	return false
+}
diff --git a/internal/transport/http/handlers/takeover_handler_test.go b/internal/transport/http/handlers/takeover_handler_test.go
new file mode 100644
index 0000000..0cfa70e
--- /dev/null
+++ b/internal/transport/http/handlers/takeover_handler_test.go
@@ -0,0 +1,625 @@
+package handlers
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/base"
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/flight"
+	flightinspection "wucher/internal/domain/flight_inspection"
+	helicopterdomain "wucher/internal/domain/helicopter"
+	helicopterfile "wucher/internal/domain/helicopter_file"
+	reserveac "wucher/internal/domain/reserve_ac"
+	takeoverdomain "wucher/internal/domain/takeover"
+	mysqlrepo "wucher/internal/repository/mysql"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+	responsedto "wucher/internal/transport/http/dto/response"
+	shareddto "wucher/internal/transport/http/dto/shared"
+)
+
+type takeoverTestUserNameGetter struct {
+	names map[string]string
+}
+
+func (g takeoverTestUserNameGetter) GetLastName(_ context.Context, userID []byte) (string, error) {
+	return "", nil
+}
+
+func (g takeoverTestUserNameGetter) GetShortName(_ context.Context, userID []byte) (string, error) {
+	if len(userID) == 0 {
+		return "", nil
+	}
+	if name, ok := g.names[idString(userID)]; ok {
+		return name, nil
+	}
+	return "", nil
+}
+
+func TestTakeoverHandler_buildTakeoverResponseAttributes_MapsReserveAcRelations(t *testing.T) {
+	h := &TakeoverHandler{}
+	takeoverID := uuidv7.MustBytes()
+	baseID := uuidv7.MustBytes()
+	flightID := uuidv7.MustBytes()
+	reserveID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	notes := " take-over notes "
+	inspectionSummary := &shareddto.ReserveAcInspectionSummary{ID: idString(inspectionID), InspectionDate: "2026-04-20"}
+	dutyResource := responsedto.DutyRosterResource{
+		Attributes: responsedto.DutyRosterAttributes{
+			ShiftTime: responsedto.DutyRosterShiftTime{ShiftStart: "06:00", ShiftEnd: "14:00"},
+			DutyDate:  "2026-04-20",
+			Detail: responsedto.DutyRosterDetailsResponse{
+				Pilot: []responsedto.DutyRosterPilotCrew{{ID: idString(uuidv7.MustBytes()), Role: "pilot"}},
+			},
+		},
+	}
+	takeoverRow := &takeoverdomain.TakeoverAc{ID: takeoverID, BaseID: baseID, Notes: &notes}
+	createdBy := uuidv7.MustBytes()
+	updatedBy := uuidv7.MustBytes()
+	takeoverRow.CreatedBy = createdBy
+	takeoverRow.UpdatedBy = updatedBy
+	takeoverRow.CreatedAt = time.Date(2026, 3, 12, 3, 4, 5, 0, time.UTC)
+	takeoverRow.UpdatedAt = time.Date(2026, 7, 6, 8, 12, 18, 0, time.UTC)
+	flightRow := &flight.Flight{ID: flightID}
+	reserveRow := &reserveac.ReserveAc{
+		ID:           reserveID,
+		InspectionID: inspectionID,
+		AircraftID:   helicopterID,
+		Aircraft:     &helicopterdomain.Helicopter{ID: helicopterID, Designation: "H145", Identifier: "D-HAAA", Type: "H145"},
+	}
+
+	attrs := h.buildTakeoverResponseAttributes(nil, takeoverRow, flightRow, reserveRow, inspectionSummary, dutyResource)
+
+	if got, want := attrs.ID, idString(takeoverID); got != want {
+		t.Fatalf("unexpected takeover id: got %s want %s", got, want)
+	}
+	if got, want := attrs.FlightID, idString(flightID); got != want {
+		t.Fatalf("unexpected flight id: got %s want %s", got, want)
+	}
+	if got, want := attrs.ReserveAcID, idString(reserveID); got != want {
+		t.Fatalf("unexpected reserve_ac_id: got %s want %s", got, want)
+	}
+	if got, want := attrs.FlightInspectionID, idString(inspectionID); got != want {
+		t.Fatalf("unexpected flight_inspection_id: got %s want %s", got, want)
+	}
+	if got, want := attrs.HelicopterID, idString(helicopterID); got != want {
+		t.Fatalf("unexpected helicopter_id: got %s want %s", got, want)
+	}
+	if attrs.Notes == nil || *attrs.Notes != notes {
+		t.Fatalf("unexpected notes: %#v", attrs.Notes)
+	}
+	if attrs.Inspection.ID != idString(inspectionID) {
+		t.Fatalf("unexpected inspection summary: %#v", attrs.Inspection)
+	}
+	if attrs.Base == nil || attrs.Base.ID != idString(baseID) {
+		t.Fatalf("unexpected base: %#v", attrs.Base)
+	}
+	if attrs.Base.ShiftTime.ShiftStart != "06:00" || attrs.Base.ShiftTime.ShiftEnd != "14:00" {
+		t.Fatalf("unexpected base shift time: %#v", attrs.Base.ShiftTime)
+	}
+	if attrs.CreatedBy != uuidStringOrEmpty(createdBy) {
+		t.Fatalf("unexpected created_by: %q", attrs.CreatedBy)
+	}
+	if attrs.UpdatedBy != uuidStringOrEmpty(updatedBy) {
+		t.Fatalf("unexpected updated_by: %q", attrs.UpdatedBy)
+	}
+	if attrs.CreatedAt != takeoverRow.CreatedAt.UTC().Format(time.RFC3339) {
+		t.Fatalf("unexpected created_at: %q", attrs.CreatedAt)
+	}
+	if attrs.UpdatedAt != takeoverRow.UpdatedAt.UTC().Format(time.RFC3339) {
+		t.Fatalf("unexpected updated_at: %q", attrs.UpdatedAt)
+	}
+}
+
+func TestFlightTakeoverStep_UsesUpdatedByShortName(t *testing.T) {
+	prev := userctx.GlobalUserNameGetter
+	updatedBy := uuidv7.MustBytes()
+	createdBy := uuidv7.MustBytes()
+	userctx.WireUserNameGetter(takeoverTestUserNameGetter{
+		names: map[string]string{
+			idString(updatedBy): "JON",
+			idString(createdBy): "GAN",
+		},
+	})
+	t.Cleanup(func() {
+		userctx.WireUserNameGetter(prev)
+	})
+
+	pilotID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	baseID := uuidv7.MustBytes()
+	reserveID := uuidv7.MustBytes()
+	inspectionID := uuidv7.MustBytes()
+	helicopterID := uuidv7.MustBytes()
+	row := &flight.Flight{
+		ID:           uuidv7.MustBytes(),
+		TakeoverAcID: takeoverID,
+		CreatedAt:    time.Date(2026, 6, 18, 10, 0, 0, 0, time.UTC),
+	}
+	takeoverRow := &takeoverdomain.TakeoverAc{
+		ID:        takeoverID,
+		BaseID:    baseID,
+		CreatedBy: createdBy,
+		UpdatedBy: updatedBy,
+		ReserveAc: &reserveac.ReserveAc{
+			ID:           reserveID,
+			AircraftID:   helicopterID,
+			InspectionID: inspectionID,
+			Aircraft:     &helicopterdomain.Helicopter{ID: helicopterID, Designation: "H145", Identifier: "D-HAAA", Type: "H145"},
+			Inspection:   &flightinspection.FlightInspection{ID: inspectionID},
+		},
+		RosterCrews: []takeoverdomain.TakeoverRosterCrew{
+			{
+				RoleCode:  "pilot",
+				UserID:    pilotID,
+				NameLabel: "Pilot Full Name",
+			},
+		},
+	}
+
+	step := flightTakeoverStep(context.Background(), row, &takeoverServiceMock{
+		getByIDFn: func(context.Context, []byte) (*takeoverdomain.TakeoverAc, error) {
+			return takeoverRow, nil
+		},
+	})
+
+	if step.CompletedBy != "JON" {
+		t.Fatalf("expected updated_by short name, got %q", step.CompletedBy)
+	}
+}
+
+func TestTakeoverHandler_buildTakeoverResponseAttributes_MapsFiles(t *testing.T) {
+	h := &TakeoverHandler{}
+	takeoverID := uuidv7.MustBytes()
+	attachmentID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	takeoverRow := &takeoverdomain.TakeoverAc{
+		ID: takeoverID,
+		Files: []takeoverdomain.TakeoverFile{
+			{
+				ID:               uuidv7.MustBytes(),
+				TakeoverID:       takeoverID,
+				FileAttachmentID: attachmentID,
+				FileAttachment: &filemanager.Attachment{
+					ID:     attachmentID,
+					FileID: fileID,
+					File: &filemanager.File{
+						ID:        fileID,
+						Name:      "takeover-report.pdf",
+						ObjectKey: "files/2026/06/23/takeover-report.pdf",
+						Bucket:    "bucket",
+					},
+				},
+			},
+		},
+	}
+
+	attrs := h.buildTakeoverResponseAttributes(nil, takeoverRow, &flight.Flight{ID: uuidv7.MustBytes()}, nil, nil, responsedto.DutyRosterResource{Attributes: responsedto.DutyRosterAttributes{Detail: responsedto.DutyRosterDetailsResponse{}}})
+
+	if len(attrs.Files) != 1 {
+		t.Fatalf("expected 1 takeover file, got %d", len(attrs.Files))
+	}
+	if attrs.Files[0].Attributes.FileAttachmentID != idString(attachmentID) {
+		t.Fatalf("unexpected attachment id: %#v", attrs.Files[0])
+	}
+	if attrs.Files[0].Attributes.FileName != "takeover-report.pdf" {
+		t.Fatalf("unexpected file name: %#v", attrs.Files[0])
+	}
+}
+
+func TestTakeoverHandler_buildTakeoverResponseAttributes_HidesTemplateDerivedFiles(t *testing.T) {
+	h := &TakeoverHandler{}
+	takeoverID := uuidv7.MustBytes()
+	regularAttID := uuidv7.MustBytes()
+	regularFileID := uuidv7.MustBytes()
+	templateAttID := uuidv7.MustBytes()
+	templateFileID := uuidv7.MustBytes()
+	takeoverRow := &takeoverdomain.TakeoverAc{
+		ID: takeoverID,
+		Files: []takeoverdomain.TakeoverFile{
+			{ // regular attached file — must stay visible
+				ID:               uuidv7.MustBytes(),
+				TakeoverID:       takeoverID,
+				FileAttachmentID: regularAttID,
+				FileAttachment: &filemanager.Attachment{
+					ID:     regularAttID,
+					FileID: regularFileID,
+					File: &filemanager.File{
+						ID:        regularFileID,
+						Name:      "evidence.pdf",
+						ObjectKey: "files/evidence.pdf",
+						Bucket:    "bucket",
+					},
+				},
+			},
+			{ // created from a template — must be hidden (kept in DB)
+				ID:               uuidv7.MustBytes(),
+				TakeoverID:       takeoverID,
+				FileAttachmentID: templateAttID,
+				FileAttachment: &filemanager.Attachment{
+					ID:     templateAttID,
+					FileID: templateFileID,
+					File: &filemanager.File{
+						ID:           templateFileID,
+						Name:         "from-template.pdf",
+						ObjectKey:    "files/from-template.pdf",
+						Bucket:       "bucket",
+						TemplateUUID: uuidv7.MustBytes(),
+					},
+				},
+			},
+		},
+	}
+
+	attrs := h.buildTakeoverResponseAttributes(nil, takeoverRow, &flight.Flight{ID: uuidv7.MustBytes()}, nil, nil, responsedto.DutyRosterResource{Attributes: responsedto.DutyRosterAttributes{Detail: responsedto.DutyRosterDetailsResponse{}}})
+
+	if len(attrs.Files) != 1 {
+		t.Fatalf("expected only the regular file to be visible, got %d: %#v", len(attrs.Files), attrs.Files)
+	}
+	if attrs.Files[0].Attributes.FileName != "evidence.pdf" {
+		t.Fatalf("expected evidence.pdf visible, got %#v", attrs.Files[0])
+	}
+}
+
+func TestTakeoverHandler_ChecklistBuilderHidesTemplateDerivedFiles(t *testing.T) {
+	h := &TakeoverHandler{}
+
+	visibleID := uuidv7.MustBytes()
+	derivedID := uuidv7.MustBytes()
+	files := []helicopterfile.HelicopterFile{
+		{ID: visibleID},
+		{
+			ID: derivedID,
+			SourceFile: &filemanager.File{
+				TemplateUUID: uuidv7.MustBytes(),
+			},
+		},
+	}
+
+	out := h.buildChecklistSectionSummary(&fiber.Ctx{}, files, map[string]bool{idString(visibleID): true, idString(derivedID): true})
+	if out.Total != 1 || out.Completed != 1 || len(out.FileChecklist) != 1 || len(out.DoneFiles) != 1 {
+		t.Fatalf("unexpected filtered checklist summary: %#v", out)
+	}
+	if out.FileChecklist[0].HelicopterFileID != idString(visibleID) {
+		t.Fatalf("expected only visible file in checklist, got %#v", out.FileChecklist[0])
+	}
+}
+
+func TestTakeoverHandler_buildTakeoverResponseAttributes_LoadsFilesFromDBFallback(t *testing.T) {
+	db := openTakeoverHandlerTestDB(t)
+	if err := db.AutoMigrate(&filemanager.Folder{}, &filemanager.File{}, &filemanager.Attachment{}, &takeoverdomain.TakeoverAc{}, &takeoverdomain.TakeoverFile{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	rootFolderID := uuidv7.MustBytes()
+	if err := db.Create(&filemanager.Folder{
+		ID:             rootFolderID,
+		Name:           "takeovers",
+		NameNormalized: "takeovers",
+		Depth:          0,
+		PathCache:      "/takeovers",
+		CreatedAt:      time.Now().UTC(),
+		UpdatedAt:      time.Now().UTC(),
+	}).Error; err != nil {
+		t.Fatalf("create folder: %v", err)
+	}
+
+	takeoverID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	attachmentID := uuidv7.MustBytes()
+	if err := db.Create(&takeoverdomain.TakeoverAc{ID: takeoverID, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}).Error; err != nil {
+		t.Fatalf("create takeover: %v", err)
+	}
+	if err := db.Create(&filemanager.File{
+		ID:              fileID,
+		FolderID:        rootFolderID,
+		Name:            "takeover-report.pdf",
+		NameNormalized:  "takeover-report-pdf",
+		SizeBytes:       1,
+		MimeType:        "application/pdf",
+		Bucket:          "bucket",
+		ObjectKey:       "files/2026/06/23/takeover-report.pdf",
+		ChecksumSHA256:  strings.Repeat("a", 64),
+		Status:          filemanager.FileStatusReady,
+		LifecycleStatus: filemanager.FileLifecycleStatusActive,
+		CreatedAt:       time.Now().UTC(),
+		UpdatedAt:       time.Now().UTC(),
+	}).Error; err != nil {
+		t.Fatalf("create file: %v", err)
+	}
+	if err := db.Create(&filemanager.Attachment{
+		ID:        attachmentID,
+		FileID:    fileID,
+		RefType:   "takeover",
+		RefID:     idString(takeoverID),
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}).Error; err != nil {
+		t.Fatalf("create attachment: %v", err)
+	}
+	if err := db.Create(&takeoverdomain.TakeoverFile{
+		ID:               uuidv7.MustBytes(),
+		TakeoverID:       takeoverID,
+		FileAttachmentID: attachmentID,
+	}).Error; err != nil {
+		t.Fatalf("create takeover file: %v", err)
+	}
+
+	h := &TakeoverHandler{db: db}
+	attrs := h.buildTakeoverResponseAttributes(nil, &takeoverdomain.TakeoverAc{ID: takeoverID}, &flight.Flight{ID: uuidv7.MustBytes()}, nil, nil, responsedto.DutyRosterResource{Attributes: responsedto.DutyRosterAttributes{Detail: responsedto.DutyRosterDetailsResponse{}}})
+
+	if len(attrs.Files) != 1 {
+		t.Fatalf("expected 1 takeover file from db fallback, got %d", len(attrs.Files))
+	}
+	if attrs.Files[0].Attributes.FileAttachmentID != idString(attachmentID) {
+		t.Fatalf("unexpected file attachment id: %#v", attrs.Files[0])
+	}
+	if attrs.Files[0].Attributes.FileName != "takeover-report.pdf" {
+		t.Fatalf("unexpected file name from db fallback: %#v", attrs.Files[0])
+	}
+}
+
+func TestTakeoverHandler_buildTakeoverResponseAttributes_LoadsFilesFromAttachmentFallback(t *testing.T) {
+	db := openTakeoverHandlerTestDB(t)
+	if err := db.AutoMigrate(&filemanager.Folder{}, &filemanager.File{}, &filemanager.Attachment{}, &takeoverdomain.TakeoverAc{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+
+	rootFolderID := uuidv7.MustBytes()
+	if err := db.Create(&filemanager.Folder{
+		ID:             rootFolderID,
+		Name:           "takeovers",
+		NameNormalized: "takeovers",
+		Depth:          0,
+		PathCache:      "/takeovers",
+		CreatedAt:      time.Now().UTC(),
+		UpdatedAt:      time.Now().UTC(),
+	}).Error; err != nil {
+		t.Fatalf("create folder: %v", err)
+	}
+
+	takeoverID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	attachmentID := uuidv7.MustBytes()
+	if err := db.Create(&takeoverdomain.TakeoverAc{ID: takeoverID, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}).Error; err != nil {
+		t.Fatalf("create takeover: %v", err)
+	}
+	if err := db.Create(&filemanager.File{
+		ID:              fileID,
+		FolderID:        rootFolderID,
+		Name:            "takeover-report.pdf",
+		NameNormalized:  "takeover-report-pdf",
+		SizeBytes:       1,
+		MimeType:        "application/pdf",
+		Bucket:          "bucket",
+		ObjectKey:       "files/2026/06/23/takeover-report.pdf",
+		ChecksumSHA256:  strings.Repeat("b", 64),
+		Status:          filemanager.FileStatusReady,
+		LifecycleStatus: filemanager.FileLifecycleStatusActive,
+		CreatedAt:       time.Now().UTC(),
+		UpdatedAt:       time.Now().UTC(),
+	}).Error; err != nil {
+		t.Fatalf("create file: %v", err)
+	}
+	if err := db.Create(&filemanager.Attachment{
+		ID:        attachmentID,
+		FileID:    fileID,
+		RefType:   "takeover",
+		RefID:     idString(takeoverID),
+		CreatedAt: time.Now().UTC(),
+		UpdatedAt: time.Now().UTC(),
+	}).Error; err != nil {
+		t.Fatalf("create attachment: %v", err)
+	}
+
+	h := &TakeoverHandler{db: db}
+	attrs := h.buildTakeoverResponseAttributes(nil, &takeoverdomain.TakeoverAc{ID: takeoverID}, &flight.Flight{ID: uuidv7.MustBytes()}, nil, nil, responsedto.DutyRosterResource{Attributes: responsedto.DutyRosterAttributes{Detail: responsedto.DutyRosterDetailsResponse{}}})
+
+	if len(attrs.Files) != 1 {
+		t.Fatalf("expected 1 takeover file from attachment fallback, got %d", len(attrs.Files))
+	}
+	if attrs.Files[0].Attributes.FileAttachmentID != idString(attachmentID) {
+		t.Fatalf("unexpected file attachment id: %#v", attrs.Files[0])
+	}
+	if attrs.Files[0].Attributes.FileName != "takeover-report.pdf" {
+		t.Fatalf("unexpected file name from attachment fallback: %#v", attrs.Files[0])
+	}
+}
+
+func TestTakeoverEditedTemplateFileBelongsToTakeover(t *testing.T) {
+	takeoverA := uuidv7.MustBytes()
+	takeoverB := uuidv7.MustBytes()
+
+	tests := []struct {
+		name string
+		row  *filemanager.File
+		want bool
+	}{
+		{
+			name: "allows unattached draft",
+			row:  &filemanager.File{},
+			want: true,
+		},
+		{
+			name: "allows matching takeover draft",
+			row:  &filemanager.File{TakeoverID: append([]byte(nil), takeoverA...)},
+			want: true,
+		},
+		{
+			name: "rejects different takeover draft",
+			row:  &filemanager.File{TakeoverID: append([]byte(nil), takeoverB...)},
+			want: false,
+		},
+		{
+			name: "rejects invalid stored takeover id",
+			row:  &filemanager.File{TakeoverID: []byte("bad")},
+			want: false,
+		},
+		{
+			name: "rejects nil row",
+			row:  nil,
+			want: false,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := takeoverEditedTemplateFileBelongsToTakeover(tc.row, takeoverA); got != tc.want {
+				t.Fatalf("unexpected result: got %v want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestTakeoverHandler_buildTakeoverResponseAttributes_ResolvesShiftTimeFromDB(t *testing.T) {
+	db := openTakeoverHandlerTestDB(t)
+	now := time.Now().UTC()
+
+	category := &base.BaseCategory{
+		ID:        uuidv7.MustBytes(),
+		Key:       base.CategoryKeyHEMS,
+		Name:      "HEMS",
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	if err := db.Create(category).Error; err != nil {
+		t.Fatalf("create category: %v", err)
+	}
+	repo := mysqlrepo.NewBaseRepository(db)
+	baseID := uuidv7.MustBytes()
+	row := &base.Base{
+		ID:                   baseID,
+		BaseCategoryID:       category.ID,
+		BaseName:             "Lude",
+		BaseAbbreviation:     "LOIG",
+		DefaultStartTimeType: base.ShiftTimeTypeBMCT,
+		DefaultEndTimeType:   base.ShiftTimeTypeECET,
+		DefaultShiftStart:    "06:00:00",
+		DefaultShiftEnd:      "21:00:00",
+		OperationalShiftTimes: []base.BaseOperationalShiftTime{
+			{
+				DateStart:  func() *time.Time { t := time.Date(2026, 6, 10, 0, 0, 0, 0, time.UTC); return &t }(),
+				DateEnd:    func() *time.Time { t := time.Date(2026, 6, 10, 0, 0, 0, 0, time.UTC); return &t }(),
+				ShiftStart: "09:00:00",
+				ShiftEnd:   "18:00:00",
+			},
+		},
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+	if err := repo.CreateBase(context.Background(), row, base.CategoryKeyHEMS); err != nil {
+		t.Fatalf("create base: %v", err)
+	}
+
+	h := &TakeoverHandler{
+		db:   db,
+		base: service.NewBaseService(repo),
+	}
+	flightRow := &flight.Flight{
+		ID:   uuidv7.MustBytes(),
+		Date: time.Date(2026, 6, 12, 0, 0, 0, 0, time.UTC),
+	}
+	takeoverRow := &takeoverdomain.TakeoverAc{
+		ID:     uuidv7.MustBytes(),
+		BaseID: baseID,
+		Base: &base.Base{
+			ID:               baseID,
+			BaseName:         "Lude",
+			BaseAbbreviation: "LOIG",
+		},
+	}
+	dutyResource := responsedto.DutyRosterResource{
+		Attributes: responsedto.DutyRosterAttributes{
+			DutyDate: "2026-06-12",
+			Detail:   responsedto.DutyRosterDetailsResponse{},
+		},
+	}
+
+	attrs := h.buildTakeoverResponseAttributes(nil, takeoverRow, flightRow, nil, nil, dutyResource)
+	resolved := h.resolveTakeoverShiftTime(nil, baseID, flightRow.Date)
+	if resolved.ShiftStart == "" || resolved.ShiftEnd == "" {
+		t.Fatalf("expected resolved shift time from takeover handler")
+	}
+	wantStart, wantEnd, err := service.ResolveBaseShiftRangeTx(db, baseID, flightRow.Date)
+	if err != nil {
+		t.Fatalf("resolve shift window: %v", err)
+	}
+
+	if attrs.Base == nil {
+		t.Fatalf("expected base in takeover response")
+	}
+	if attrs.Base.ShiftTime.ShiftStart != wantStart || attrs.Base.ShiftTime.ShiftEnd != wantEnd {
+		t.Fatalf("unexpected base shift time: got=%#v want=%s %s", attrs.Base.ShiftTime, wantStart, wantEnd)
+	}
+	if attrs.ShiftStart != wantStart || attrs.ShiftEnd != wantEnd {
+		t.Fatalf("unexpected top-level shift time: %#v %#v", attrs.ShiftStart, attrs.ShiftEnd)
+	}
+}
+
+func TestBuildDutyRosterResourceFromTakeoverRows_PreservesCalendarDutyDate(t *testing.T) {
+	jakarta := time.FixedZone("UTC+7", 7*60*60)
+	flightRow := &flight.Flight{
+		ID:           uuidv7.MustBytes(),
+		TakeoverAcID: uuidv7.MustBytes(),
+		Date:         time.Date(2026, time.June, 1, 0, 0, 0, 0, jakarta),
+	}
+
+	resource := buildDutyRosterResourceFromTakeoverRows(
+		responsedto.DutyRosterResource{
+			Attributes: responsedto.DutyRosterAttributes{
+				Detail: responsedto.DutyRosterDetailsResponse{},
+			},
+		},
+		nil,
+		flightRow,
+	)
+
+	if got, want := resource.Attributes.DutyDate, "2026-06-01"; got != want {
+		t.Fatalf("unexpected duty date: got %s want %s", got, want)
+	}
+}
+
+func TestCalendarDateString_PreservesCalendarDate(t *testing.T) {
+	jakarta := time.FixedZone("UTC+7", 7*60*60)
+	value := time.Date(2026, time.June, 1, 0, 0, 0, 0, jakarta)
+
+	if got, want := calendarDateString(value), "2026-06-01"; got != want {
+		t.Fatalf("unexpected calendar date string: got %s want %s", got, want)
+	}
+}
+
+func TestTakeoverHandler_resolveTakeoverReserveRow_PrefersPreloadedReserveAc(t *testing.T) {
+	h := &TakeoverHandler{}
+	expected := &reserveac.ReserveAc{ID: uuidv7.MustBytes(), InspectionID: uuidv7.MustBytes()}
+	takeoverRow := &takeoverdomain.TakeoverAc{ReserveAc: expected}
+	flightRow := &flight.Flight{ReserveAcID: uuidv7.MustBytes()}
+
+	got := h.resolveTakeoverReserveRow(nil, takeoverRow, flightRow)
+	if got != expected {
+		t.Fatalf("expected preloaded reserve_ac to win, got %#v", got)
+	}
+}
+
+func openTakeoverHandlerTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dsn := fmt.Sprintf("file:takeover_handler_test_%d?mode=memory&cache=shared", time.Now().UnixNano())
+	db, err := gorm.Open(sqlite.Open(dsn), &gorm.Config{NowFunc: func() time.Time { return time.Now().UTC() }})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	if err := db.AutoMigrate(&base.BaseCategory{}, &base.Base{}, &base.BaseOperationalShiftTime{}, &base.BaseContactRole{}); err != nil {
+		t.Fatalf("auto migrate: %v", err)
+	}
+	return db
+}
diff --git a/internal/transport/http/handlers/takeover_wopi_handler.go b/internal/transport/http/handlers/takeover_wopi_handler.go
new file mode 100644
index 0000000..0f7579a
--- /dev/null
+++ b/internal/transport/http/handlers/takeover_wopi_handler.go
@@ -0,0 +1,92 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"strings"
+	"time"
+
+	filemanager "wucher/internal/domain/file_manager"
+	takeoverdomain "wucher/internal/domain/takeover"
+)
+
+type takeoverWOPIStorage interface {
+	GetObject(ctx context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error)
+	HeadObject(ctx context.Context, objectKey string) (filemanager.ObjectMetadata, error)
+	PutObject(ctx context.Context, input filemanager.PutObjectInput) (filemanager.ObjectMetadata, error)
+	CopyObject(ctx context.Context, sourceObjectKey, destinationObjectKey string) (filemanager.ObjectMetadata, error)
+	DeleteObject(ctx context.Context, objectKey string) error
+}
+
+type takeoverWOPIFileInfo struct {
+	BaseFileName               string `json:"BaseFileName"`
+	Version                    string `json:"Version"`
+	OwnerId                    string `json:"OwnerId,omitempty"`
+	UserId                     string `json:"UserId,omitempty"`
+	UserFriendlyName           string `json:"UserFriendlyName,omitempty"`
+	Size                       int64  `json:"Size"`
+	ReadOnly                   bool   `json:"ReadOnly"`
+	UserCanWrite               bool   `json:"UserCanWrite"`
+	SupportsUpdate             bool   `json:"SupportsUpdate"`
+	SupportsLocks              bool   `json:"SupportsLocks"`
+	SupportsGetLock            bool   `json:"SupportsGetLock"`
+	SupportsRename             bool   `json:"SupportsRename"`
+	SupportsExtendedLockLength bool   `json:"SupportsExtendedLockLength"`
+	LastModifiedTime           string `json:"LastModifiedTime,omitempty"`
+}
+
+func takeoverHasUserAccess(row *takeoverdomain.TakeoverAc, userID []byte) bool {
+	if row == nil || len(userID) != 16 {
+		return false
+	}
+	if bytes.Equal(row.CreatedBy, userID) {
+		return true
+	}
+	for i := range row.RosterCrews {
+		crew := row.RosterCrews[i]
+		if len(crew.UserID) != 16 || crew.DeletedAt != nil {
+			continue
+		}
+		if bytes.Equal(crew.UserID, userID) {
+			return true
+		}
+	}
+	return false
+}
+
+func takeoverHasUserAccessOrAdmin(h *TakeoverHandler, row *takeoverdomain.TakeoverAc, userID []byte) bool {
+	if h != nil && h.takeoverUserHasGlobalAccessForUserID(context.Background(), userID) {
+		return true
+	}
+	return takeoverHasUserAccess(row, userID)
+}
+
+func takeoverFindFileByID(row *takeoverdomain.TakeoverAc, fileID []byte) (*filemanager.File, error) {
+	if row == nil || len(fileID) != 16 {
+		return nil, filemanager.ErrFileNotFound
+	}
+	for i := range row.Files {
+		fileAttachment := row.Files[i].FileAttachment
+		if fileAttachment == nil || fileAttachment.File == nil {
+			continue
+		}
+		if bytes.Equal(fileAttachment.File.ID, fileID) {
+			return fileAttachment.File, nil
+		}
+	}
+	return nil, filemanager.ErrFileNotFound
+}
+
+func wopiFileVersion(row *filemanager.File) string {
+	if row == nil {
+		return ""
+	}
+	if version := strings.TrimSpace(row.ObjectVersion); version != "" {
+		return version
+	}
+	if etag := strings.TrimSpace(row.ETag); etag != "" {
+		return etag
+	}
+	return row.UpdatedAt.UTC().Format(time.RFC3339Nano)
+}
diff --git a/internal/transport/http/handlers/takeover_wopi_public_handler.go b/internal/transport/http/handlers/takeover_wopi_public_handler.go
new file mode 100644
index 0000000..058c2af
--- /dev/null
+++ b/internal/transport/http/handlers/takeover_wopi_public_handler.go
@@ -0,0 +1,631 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"path"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	filemanager "wucher/internal/domain/file_manager"
+	takeoverdomain "wucher/internal/domain/takeover"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const wopiSaveTimestampSkew = 30 * time.Second
+
+func (h *TakeoverHandler) CheckWOPIFileInfo(c *fiber.Ctx) error {
+	row, fileRow, claims, err := h.resolveWOPIFileByToken(c)
+	if err != nil {
+		return h.writeWOPIByTokenError(c, "CheckWOPIFileInfo", err)
+	}
+	meta, err := h.wopiHeadObject(c, fileRow)
+	if err != nil {
+		return h.writeWOPIByTokenError(c, "CheckWOPIFileInfo", err)
+	}
+	userID := tokenUserID(claims)
+	ownerID := uuidStringOrEmpty(fileRow.CreatedBy)
+	if row != nil {
+		ownerID = firstNonEmpty(uuidStringOrEmpty(row.CreatedBy), ownerID)
+	}
+	info := takeoverWOPIFileInfo{
+		BaseFileName:               strings.TrimSpace(fileRow.Name),
+		Version:                    wopiFileVersion(fileRow),
+		OwnerId:                    ownerID,
+		UserId:                     uuidStringOrEmpty(userID),
+		UserFriendlyName:           strings.TrimSpace(userctx.GetDisplayName(c.UserContext(), userID)),
+		Size:                       firstPositiveInt64(meta.SizeBytes, fileRow.SizeBytes),
+		ReadOnly:                   !claimsCanWrite(claims),
+		UserCanWrite:               claimsCanWrite(claims),
+		SupportsUpdate:             true,
+		SupportsLocks:              true,
+		SupportsGetLock:            true,
+		SupportsRename:             false,
+		SupportsExtendedLockLength: false,
+		LastModifiedTime:           lastModifiedRFC3339(meta.LastModified, fileRow.UpdatedAt),
+	}
+	return c.Status(fiber.StatusOK).JSON(info)
+}
+
+func (h *TakeoverHandler) GetWOPIContents(c *fiber.Ctx) error {
+	_, fileRow, _, err := h.resolveWOPIFileByToken(c)
+	if err != nil {
+		return h.writeWOPIByTokenError(c, "GetWOPIContents", err)
+	}
+	if h.storage == nil {
+		return h.writeWOPIByTokenError(c, "GetWOPIContents", filemanager.ErrStorageUnavailable)
+	}
+
+	rawStorage, ok := any(h.storage).(takeoverWOPIStorage)
+	if !ok {
+		return h.writeWOPIByTokenError(c, "GetWOPIContents", filemanager.ErrStorageUnavailable)
+	}
+
+	objectKey := strings.TrimSpace(fileRow.ObjectKey)
+	if objectKey == "" {
+		return h.writeWOPIByTokenError(c, "GetWOPIContents", filemanager.ErrFileNotFound)
+	}
+
+	body, meta, err := rawStorage.GetObject(c.UserContext(), objectKey)
+	if err != nil {
+		if errors.Is(err, filemanager.ErrUploadObjectNotFound) {
+			return h.writeWOPIByTokenError(c, "GetWOPIContents", filemanager.ErrFileNotFound)
+		}
+		return h.writeWOPIByTokenError(c, "GetWOPIContents", err)
+	}
+	defer body.Close()
+
+	// Read the object fully while the request context is still alive. fasthttp's
+	// SetBodyStream writes the reader to the socket AFTER the handler returns, by
+	// which point requestTimeoutMiddleware's defer cancel() has torn the
+	// context-bound storage reader down — shipping a committed 200 + full
+	// Content-Length with a truncated body that Collabora saves verbatim as a
+	// corrupt document. Buffering here keeps any read/size failure a non-200 that
+	// is written before headers are committed. WOPI office docs are small and
+	// bounded, so buffering the GET is safe.
+	payload, err := io.ReadAll(body)
+	if err != nil {
+		slog.ErrorContext(c.UserContext(), "wopi get contents read failed",
+			slog.String("file_id", idString(fileRow.ID)),
+			slog.String("object_key", objectKey),
+			slog.String("error", err.Error()),
+		)
+		return h.writeWOPIByTokenError(c, "GetWOPIContents", err)
+	}
+	if meta.SizeBytes > 0 && int64(len(payload)) != meta.SizeBytes {
+		slog.ErrorContext(c.UserContext(), "wopi get contents body size mismatch",
+			slog.String("file_id", idString(fileRow.ID)),
+			slog.String("object_key", objectKey),
+			slog.Int64("expected_bytes", meta.SizeBytes),
+			slog.Int64("actual_bytes", int64(len(payload))),
+		)
+		return h.writeWOPIByTokenError(c, "GetWOPIContents", errors.New("wopi get contents body truncated: storage returned fewer bytes than advertised size"))
+	}
+
+	contentType := strings.TrimSpace(meta.ContentType)
+	if contentType == "" {
+		contentType = strings.TrimSpace(fileRow.MimeType)
+	}
+	if contentType == "" {
+		contentType = "application/octet-stream"
+	}
+	c.Set(fiber.HeaderContentType, contentType)
+	if etag := strings.TrimSpace(meta.ETag); etag != "" {
+		c.Set(fiber.HeaderETag, etag)
+	}
+	if modified := meta.LastModified; modified != nil && !modified.IsZero() {
+		c.Set(fiber.HeaderLastModified, modified.UTC().Format(http.TimeFormat))
+	}
+	c.Set("X-WOPI-ItemVersion", wopiFileVersion(fileRow))
+
+	slog.InfoContext(c.UserContext(), "wopi get contents",
+		slog.String("file_id", idString(fileRow.ID)),
+		slog.String("object_key", objectKey),
+		slog.Int64("size_bytes", int64(len(payload))),
+		slog.String("content_type", contentType),
+	)
+	// Content-Length is derived from the validated buffer.
+	return c.Status(fiber.StatusOK).Send(payload)
+}
+
+func (h *TakeoverHandler) PutWOPIContents(c *fiber.Ctx) error {
+	row, fileRow, claims, err := h.resolveWOPIFileByToken(c)
+	if err != nil {
+		return h.writeWOPIByTokenError(c, "PutWOPIContents", err)
+	}
+	if !claimsCanWrite(claims) {
+		return h.writeWOPIByTokenError(c, "PutWOPIContents", apperrorsx.New(apperrorsx.ErrForbiddenAccess))
+	}
+	if h.fileManager == nil || h.storage == nil {
+		return h.writeWOPIByTokenError(c, "PutWOPIContents", filemanager.ErrStorageUnavailable)
+	}
+
+	rawStorage, ok := any(h.storage).(takeoverWOPIStorage)
+	if !ok {
+		return h.writeWOPIByTokenError(c, "PutWOPIContents", filemanager.ErrStorageUnavailable)
+	}
+
+	objectKey := strings.TrimSpace(fileRow.ObjectKey)
+	if objectKey == "" {
+		return h.writeWOPIByTokenError(c, "PutWOPIContents", filemanager.ErrFileNotFound)
+	}
+
+	currentLock := strings.TrimSpace(fileRow.WOPILockID)
+	incomingLock := strings.TrimSpace(c.Get("X-WOPI-Lock"))
+	if currentLock != "" && incomingLock != "" && !strings.EqualFold(currentLock, incomingLock) {
+		c.Set("X-WOPI-Lock", currentLock)
+		return c.Status(fiber.StatusConflict).JSON(map[string]any{"error": "lock mismatch"})
+	}
+
+	timestampHeader := firstNonEmpty(strings.TrimSpace(c.Get("X-COOL-WOPI-Timestamp")), strings.TrimSpace(c.Get("X-LOOL-WOPI-Timestamp")))
+	if timestampHeader != "" {
+		if modified, ok := parseWOPITimestamp(timestampHeader); ok {
+			meta, headErr := rawStorage.HeadObject(c.UserContext(), objectKey)
+			if headErr != nil {
+				if errors.Is(headErr, filemanager.ErrUploadObjectNotFound) {
+					return h.writeWOPIByTokenError(c, "PutWOPIContents", filemanager.ErrFileNotFound)
+				}
+				return h.writeWOPIByTokenError(c, "PutWOPIContents", headErr)
+			}
+			stored := firstNonZeroTime(meta.LastModified, &fileRow.UpdatedAt)
+			if stored.After(modified.Add(wopiSaveTimestampSkew)) {
+				return c.Status(fiber.StatusConflict).JSON(map[string]any{"COOLStatusCode": 1010})
+			}
+		}
+	}
+
+	contentType := strings.TrimSpace(c.Get(fiber.HeaderContentType))
+	if contentType == "" {
+		contentType = strings.TrimSpace(fileRow.MimeType)
+	}
+	if contentType == "" {
+		contentType = "application/octet-stream"
+	}
+
+	payload := append([]byte(nil), c.Body()...)
+	ext := strings.ToLower(strings.TrimPrefix(filepath.Ext(fileRow.Name), "."))
+	if ext == "" {
+		ext = strings.ToLower(strings.TrimPrefix(filepath.Ext(objectKey), "."))
+	}
+	if ext == "" {
+		ext = strings.ToLower(strings.TrimPrefix(filepath.Ext(fileRow.ObjectKey), "."))
+	}
+	if ext == "xlsx" {
+		beforeLen := len(payload)
+		beforeSum := sha256.Sum256(payload)
+		if sanitizedPayload, styleFixes, changed, err := sanitizeXLSXPayload(payload); err != nil {
+			return h.writeWOPIByTokenError(c, "PutWOPIContents", apperrorsx.New(apperrorsx.ErrFileManagerWOPIValidationFailed).WithCause(err))
+		} else if changed {
+			afterSum := sha256.Sum256(sanitizedPayload)
+			slog.InfoContext(c.UserContext(), "wopi put contents sanitized xlsx",
+				slog.String("object_key", objectKey),
+				slog.Int("before_bytes", beforeLen),
+				slog.Int("after_bytes", len(sanitizedPayload)),
+				slog.Int("style_fixes", styleFixes),
+				slog.Bool("changed", true),
+				slog.String("before_sha256", hex.EncodeToString(beforeSum[:])),
+				slog.String("after_sha256", hex.EncodeToString(afterSum[:])),
+			)
+			payload = sanitizedPayload
+		}
+	}
+	if err := validateWOPISaveContent(fileRow.Name, contentType, payload); err != nil {
+		return h.writeWOPIByTokenError(c, "PutWOPIContents", apperrorsx.New(apperrorsx.ErrFileManagerWOPIValidationFailed).WithCause(err))
+	}
+	if normalized := canonicalOfficeContentType(fileRow.Name); normalized != "" {
+		contentType = normalized
+	}
+	tempObjectKey := wopiTemporaryObjectKey(objectKey)
+	tempMeta, putErr := rawStorage.PutObject(c.UserContext(), filemanager.PutObjectInput{
+		ObjectKey:   tempObjectKey,
+		ContentType: contentType,
+		SizeBytes:   int64(len(payload)),
+		Body:        bytes.NewReader(payload),
+	})
+	if putErr != nil {
+		return h.writeWOPIByTokenError(c, "PutWOPIContents", putErr)
+	}
+	if err := validateWOPISavedObject(rawStorage, c.UserContext(), fileRow, tempObjectKey, tempMeta); err != nil {
+		_ = rawStorage.DeleteObject(c.UserContext(), tempObjectKey)
+		return h.writeWOPIByTokenError(c, "PutWOPIContents", apperrorsx.New(apperrorsx.ErrFileManagerWOPIValidationFailed).WithCause(err))
+	}
+	if _, err := rawStorage.CopyObject(c.UserContext(), tempObjectKey, objectKey); err != nil {
+		_ = rawStorage.DeleteObject(c.UserContext(), tempObjectKey)
+		return h.writeWOPIByTokenError(c, "PutWOPIContents", err)
+	}
+	meta, err := rawStorage.HeadObject(c.UserContext(), objectKey)
+	if err != nil {
+		_ = rawStorage.DeleteObject(c.UserContext(), tempObjectKey)
+		return h.writeWOPIByTokenError(c, "PutWOPIContents", err)
+	}
+	_ = rawStorage.DeleteObject(c.UserContext(), tempObjectKey)
+
+	now := time.Now().UTC()
+	fileRow.SizeBytes = int64(len(payload))
+	fileRow.MimeType = contentType
+	fileRow.ObjectVersion = nextWOPIVersion(fileRow.ObjectVersion)
+	fileRow.ETag = strings.TrimSpace(meta.ETag)
+	if strings.TrimSpace(meta.Bucket) != "" {
+		fileRow.Bucket = meta.Bucket
+	}
+	if strings.TrimSpace(meta.ObjectKey) != "" {
+		fileRow.ObjectKey = meta.ObjectKey
+	}
+	if isTrueish(c.Get("X-WOPI-IsModifiedByUser"), c.Get("X-COOL-WOPI-IsModifiedByUser"), c.Get("X-LOOL-WOPI-IsModifiedByUser")) {
+		fileRow.LifecycleStatus = filemanager.FileLifecycleStatusActive
+	}
+	if isTrueish(c.Get("X-WOPI-IsExitSave"), c.Get("X-COOL-WOPI-IsExitSave"), c.Get("X-LOOL-WOPI-IsExitSave")) {
+		fileRow.LifecycleStatus = filemanager.FileLifecycleStatusFinal
+		fileRow.NameSlot = "live"
+	}
+	if currentLock != "" {
+		lockExpires := now.Add(30 * time.Minute)
+		fileRow.WOPILockID = currentLock
+		fileRow.WOPILockedAt = &now
+		fileRow.WOPILockExpiresAt = &lockExpires
+	}
+	fileRow.UpdatedAt = now
+	fileRow.UpdatedBy = tokenUserID(claims)
+	if err := h.fileManager.UpdateFile(c.UserContext(), fileRow); err != nil {
+		return h.writeWOPIByTokenError(c, "PutWOPIContents", err)
+	}
+
+	c.Set("X-WOPI-ItemVersion", wopiFileVersion(fileRow))
+	_ = row
+	return c.Status(fiber.StatusOK).JSON(map[string]string{
+		"LastModifiedTime": now.UTC().Format(time.RFC3339Nano),
+	})
+}
+
+func wopiTemporaryObjectKey(objectKey string) string {
+	objectKey = strings.TrimSpace(objectKey)
+	suffix := idString(uuidv7.MustBytes())
+	if objectKey == "" {
+		return "wopi/tmp/.wopi-tmp-" + suffix
+	}
+	if idx := strings.LastIndex(objectKey, "/"); idx >= 0 {
+		return objectKey[:idx+1] + ".wopi-tmp-" + suffix + path.Ext(objectKey)
+	}
+	return ".wopi-tmp-" + suffix + "-" + objectKey
+}
+
+func validateWOPISavedObject(storage takeoverWOPIStorage, ctx context.Context, fileRow *filemanager.File, objectKey string, meta filemanager.ObjectMetadata) error {
+	if storage == nil || fileRow == nil {
+		return nil
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	tempRow := &filemanager.File{
+		Name:      fileRow.Name,
+		ObjectKey: objectKey,
+		MimeType:  firstNonEmpty(meta.ContentType, fileRow.MimeType),
+	}
+	return validateStoredWOPIFile(ctx, storage, tempRow)
+}
+
+func (h *TakeoverHandler) PostWOPIFile(c *fiber.Ctx) error {
+	override := strings.ToUpper(strings.TrimSpace(c.Get("X-WOPI-Override")))
+	switch override {
+	case "LOCK":
+		return h.wopiLock(c)
+	case "UNLOCK":
+		return h.wopiUnlock(c)
+	case "REFRESH_LOCK":
+		return h.wopiRefreshLock(c)
+	case "GET_LOCK":
+		return h.wopiGetLock(c)
+	default:
+		return h.writeWOPIByTokenError(c, "PostWOPIFile", apperrorsx.New(apperrorsx.ErrInvalidRequest))
+	}
+}
+
+func (h *TakeoverHandler) wopiLock(c *fiber.Ctx) error {
+	_, fileRow, claims, err := h.resolveWOPIFileByToken(c)
+	if err != nil {
+		return h.writeWOPIByTokenError(c, "LOCK", err)
+	}
+	if !claimsCanWrite(claims) {
+		return h.writeWOPIByTokenError(c, "LOCK", apperrorsx.New(apperrorsx.ErrForbiddenAccess))
+	}
+	lockID := strings.TrimSpace(c.Get("X-WOPI-Lock"))
+	if lockID == "" {
+		return c.Status(fiber.StatusBadRequest).JSON(map[string]any{"error": "missing lock"})
+	}
+	if current := strings.TrimSpace(fileRow.WOPILockID); current != "" && !strings.EqualFold(current, lockID) {
+		c.Set("X-WOPI-Lock", current)
+		return c.Status(fiber.StatusConflict).JSON(map[string]any{"error": "lock mismatch"})
+	}
+	now := time.Now().UTC()
+	exp := now.Add(30 * time.Minute)
+	fileRow.WOPILockID = lockID
+	fileRow.WOPILockJTI = claims.ID
+	fileRow.WOPILockedAt = &now
+	fileRow.WOPILockExpiresAt = &exp
+	fileRow.UpdatedAt = now
+	fileRow.UpdatedBy = tokenUserID(claims)
+	if err := h.fileManager.UpdateFile(c.UserContext(), fileRow); err != nil {
+		return h.writeWOPIByTokenError(c, "LOCK", err)
+	}
+	return c.SendStatus(fiber.StatusOK)
+}
+
+func (h *TakeoverHandler) wopiUnlock(c *fiber.Ctx) error {
+	_, fileRow, claims, err := h.resolveWOPIFileByToken(c)
+	if err != nil {
+		return h.writeWOPIByTokenError(c, "UNLOCK", err)
+	}
+	if !claimsCanWrite(claims) {
+		return h.writeWOPIByTokenError(c, "UNLOCK", apperrorsx.New(apperrorsx.ErrForbiddenAccess))
+	}
+	lockID := strings.TrimSpace(c.Get("X-WOPI-Lock"))
+	if current := strings.TrimSpace(fileRow.WOPILockID); current != "" && !strings.EqualFold(current, lockID) {
+		c.Set("X-WOPI-Lock", current)
+		return c.Status(fiber.StatusConflict).JSON(map[string]any{"error": "lock mismatch"})
+	}
+	fileRow.WOPILockID = ""
+	fileRow.WOPILockJTI = ""
+	fileRow.WOPILockedAt = nil
+	fileRow.WOPILockExpiresAt = nil
+	fileRow.UpdatedAt = time.Now().UTC()
+	fileRow.UpdatedBy = tokenUserID(claims)
+	if err := h.fileManager.UpdateFile(c.UserContext(), fileRow); err != nil {
+		return h.writeWOPIByTokenError(c, "UNLOCK", err)
+	}
+	return c.SendStatus(fiber.StatusOK)
+}
+
+func (h *TakeoverHandler) wopiRefreshLock(c *fiber.Ctx) error {
+	_, fileRow, claims, err := h.resolveWOPIFileByToken(c)
+	if err != nil {
+		return h.writeWOPIByTokenError(c, "REFRESH_LOCK", err)
+	}
+	lockID := strings.TrimSpace(c.Get("X-WOPI-Lock"))
+	if current := strings.TrimSpace(fileRow.WOPILockID); current != "" && !strings.EqualFold(current, lockID) {
+		c.Set("X-WOPI-Lock", current)
+		return c.Status(fiber.StatusConflict).JSON(map[string]any{"error": "lock mismatch"})
+	}
+	now := time.Now().UTC()
+	exp := now.Add(30 * time.Minute)
+	fileRow.WOPILockID = lockID
+	fileRow.WOPILockJTI = claims.ID
+	fileRow.WOPILockedAt = &now
+	fileRow.WOPILockExpiresAt = &exp
+	fileRow.UpdatedAt = now
+	fileRow.UpdatedBy = tokenUserID(claims)
+	if err := h.fileManager.UpdateFile(c.UserContext(), fileRow); err != nil {
+		return h.writeWOPIByTokenError(c, "REFRESH_LOCK", err)
+	}
+	return c.SendStatus(fiber.StatusOK)
+}
+
+func (h *TakeoverHandler) wopiGetLock(c *fiber.Ctx) error {
+	_, fileRow, _, err := h.resolveWOPIFileByToken(c)
+	if err != nil {
+		return h.writeWOPIByTokenError(c, "GET_LOCK", err)
+	}
+	if strings.TrimSpace(fileRow.WOPILockID) == "" {
+		return c.SendStatus(fiber.StatusNotFound)
+	}
+	c.Set("X-WOPI-Lock", strings.TrimSpace(fileRow.WOPILockID))
+	return c.SendStatus(fiber.StatusOK)
+}
+
+func (h *TakeoverHandler) resolveWOPIFileByToken(c *fiber.Ctx) (*takeoverdomain.TakeoverAc, *filemanager.File, *service.WOPIClaims, error) {
+	claims := currentWOPIClaims(c)
+	if claims == nil {
+		return nil, nil, nil, apperrorsx.New(apperrorsx.ErrForbiddenAccess)
+	}
+	fileID, err := resolveWOPIFileIDFromRequest(c)
+	if err != nil {
+		return nil, nil, nil, filemanager.ErrFileNotFound
+	}
+	if !strings.EqualFold(claims.FileID, idString(fileID)) {
+		return nil, nil, nil, apperrorsx.New(apperrorsx.ErrForbiddenAccess)
+	}
+	if strings.TrimSpace(claims.TakeoverID) == "" {
+		if h.fileManager == nil {
+			return nil, nil, nil, apperrorsx.New(apperrorsx.ErrInternal)
+		}
+		fileRow, err := h.fileManager.GetFileByIDAny(c.UserContext(), fileID)
+		if err != nil {
+			return nil, nil, nil, err
+		}
+		if fileRow == nil || !bytes.Equal(fileRow.CreatedBy, tokenUserID(claims)) {
+			return nil, nil, nil, apperrorsx.New(apperrorsx.ErrForbiddenAccess)
+		}
+		return nil, fileRow, claims, nil
+	}
+	takeoverID, err := uuidv7.ParsePathLikeString(claims.TakeoverID)
+	if err != nil {
+		return nil, nil, nil, apperrorsx.New(apperrorsx.ErrForbiddenAccess)
+	}
+	if h.takeoverAc == nil {
+		return nil, nil, nil, apperrorsx.New(apperrorsx.ErrInternal)
+	}
+	row, err := h.takeoverAc.GetByID(c.UserContext(), takeoverID)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+	userID := tokenUserID(claims)
+	if row == nil || (!takeoverHasUserAccess(row, userID) && !h.takeoverUserHasGlobalAccessForUserID(c.UserContext(), userID)) {
+		return nil, nil, nil, apperrorsx.New(apperrorsx.ErrForbiddenAccess)
+	}
+	fileRow, err := takeoverFindFileByID(row, fileID)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+	if fileRow == nil {
+		return nil, nil, nil, filemanager.ErrFileNotFound
+	}
+	return row, fileRow, claims, nil
+}
+
+func resolveWOPIFileIDFromRequest(c *fiber.Ctx) ([]byte, error) {
+	if c == nil {
+		return nil, fiber.ErrBadRequest
+	}
+	candidates := []string{
+		c.Params("fileId"),
+		c.Path(),
+		c.OriginalURL(),
+		c.Query("WOPISrc"),
+	}
+	for _, candidate := range candidates {
+		if fileID, err := uuidv7.ParsePathLikeString(candidate); err == nil {
+			return fileID, nil
+		}
+	}
+	return nil, fiber.ErrBadRequest
+}
+
+func (h *TakeoverHandler) wopiHeadObject(c *fiber.Ctx, fileRow *filemanager.File) (filemanager.ObjectMetadata, error) {
+	if h.storage == nil {
+		return filemanager.ObjectMetadata{}, filemanager.ErrStorageUnavailable
+	}
+	rawStorage, ok := any(h.storage).(takeoverWOPIStorage)
+	if !ok {
+		return filemanager.ObjectMetadata{}, filemanager.ErrStorageUnavailable
+	}
+	objectKey := strings.TrimSpace(fileRow.ObjectKey)
+	if objectKey == "" {
+		return filemanager.ObjectMetadata{}, filemanager.ErrFileNotFound
+	}
+	return rawStorage.HeadObject(c.UserContext(), objectKey)
+}
+
+func currentWOPIClaims(c *fiber.Ctx) *service.WOPIClaims {
+	if c == nil {
+		return nil
+	}
+	raw := c.Locals("wopi_claims")
+	claims, _ := raw.(*service.WOPIClaims)
+	return claims
+}
+
+func claimsCanWrite(claims *service.WOPIClaims) bool {
+	if claims == nil {
+		return false
+	}
+	return strings.EqualFold(strings.TrimSpace(claims.Permission), string(service.WOPIPermissionWrite))
+}
+
+func tokenUserID(claims *service.WOPIClaims) []byte {
+	if claims == nil {
+		return nil
+	}
+	userID, err := uuidv7.ParsePathLikeString(claims.UserID)
+	if err != nil {
+		return nil
+	}
+	return userID
+}
+
+func parseWOPITimestamp(raw string) (time.Time, bool) {
+	v, err := strconv.ParseInt(strings.TrimSpace(raw), 10, 64)
+	if err != nil {
+		return time.Time{}, false
+	}
+	if v > 1e12 {
+		return time.UnixMilli(v).UTC(), true
+	}
+	return time.Unix(v, 0).UTC(), true
+}
+
+func firstNonZeroTime(values ...*time.Time) time.Time {
+	for i := range values {
+		if values[i] != nil && !values[i].IsZero() {
+			return values[i].UTC()
+		}
+	}
+	return time.Time{}
+}
+
+func lastModifiedRFC3339(values ...any) string {
+	for i := range values {
+		switch v := values[i].(type) {
+		case *time.Time:
+			if v != nil && !v.IsZero() {
+				return v.UTC().Format(time.RFC3339Nano)
+			}
+		case time.Time:
+			if !v.IsZero() {
+				return v.UTC().Format(time.RFC3339Nano)
+			}
+		}
+	}
+	return ""
+}
+
+func firstPositiveInt64(values ...int64) int64 {
+	for i := range values {
+		if values[i] > 0 {
+			return values[i]
+		}
+	}
+	return 0
+}
+
+func isTrueish(values ...string) bool {
+	for i := range values {
+		switch strings.ToLower(strings.TrimSpace(values[i])) {
+		case "1", "true", "yes", "on":
+			return true
+		}
+	}
+	return false
+}
+
+func nextWOPIVersion(current string) string {
+	current = strings.TrimSpace(current)
+	if current == "" {
+		return "1"
+	}
+	if n, err := strconv.ParseInt(current, 10, 64); err == nil {
+		return strconv.FormatInt(n+1, 10)
+	}
+	return strconv.FormatInt(time.Now().UTC().UnixNano(), 10)
+}
+
+func (h *TakeoverHandler) writeWOPIByTokenError(c *fiber.Ctx, action string, err error) error {
+	if err == nil {
+		err = errors.New("wopi request failed")
+	}
+	logTakeoverError(c, action, err)
+	def := apperrorsx.ErrInternal
+	switch {
+	case appErrorCodeMatches(err, apperrorsx.ErrForbiddenAccess.Code), appErrorCodeMatches(err, apperrorsx.ErrUserUnauthorized.Code):
+		def = apperrorsx.ErrFileManagerWOPIPermissionDenied
+	case errors.Is(err, filemanager.ErrFileNotFound), errors.Is(err, filemanager.ErrUploadObjectNotFound):
+		def = apperrorsx.ErrFileManagerWOPIFileNotFound
+	case errors.Is(err, filemanager.ErrStorageUnavailable):
+		def = apperrorsx.ErrFileManagerWOPIServiceUnavailable
+	case appErrorCodeMatches(err, apperrorsx.ErrFileManagerWOPIValidationFailed.Code):
+		def = apperrorsx.ErrFileManagerWOPIValidationFailed
+	}
+	return apperrorsx.Write(c, apperrorsx.New(def).WithCause(err))
+}
+
+func appErrorCodeMatches(err error, code string) bool {
+	if err == nil || strings.TrimSpace(code) == "" {
+		return false
+	}
+	var appErr *apperrorsx.AppError
+	if !errors.As(err, &appErr) || appErr == nil {
+		return false
+	}
+	return strings.EqualFold(strings.TrimSpace(appErr.Code), strings.TrimSpace(code))
+}
diff --git a/internal/transport/http/handlers/takeover_wopi_public_handler_test.go b/internal/transport/http/handlers/takeover_wopi_public_handler_test.go
new file mode 100644
index 0000000..a7ed8ce
--- /dev/null
+++ b/internal/transport/http/handlers/takeover_wopi_public_handler_test.go
@@ -0,0 +1,555 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	authdomain "wucher/internal/domain/auth"
+	filemanager "wucher/internal/domain/file_manager"
+	takeoverdomain "wucher/internal/domain/takeover"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/middleware"
+)
+
+type takeoverWOPIStorageMock struct {
+	objects map[string]takeoverWOPIStoredObject
+}
+
+type takeoverWOPIStoredObject struct {
+	payload     []byte
+	contentType string
+	lastMod     time.Time
+	etag        string
+	// advertisedSize, when > 0, overrides the SizeBytes reported in object
+	// metadata so a test can simulate storage that claims a larger size than the
+	// body actually delivers (a truncated read).
+	advertisedSize int64
+}
+
+func (o takeoverWOPIStoredObject) sizeBytes() int64 {
+	if o.advertisedSize > 0 {
+		return o.advertisedSize
+	}
+	return int64(len(o.payload))
+}
+
+func (m *takeoverWOPIStorageMock) GetObject(_ context.Context, objectKey string) (io.ReadCloser, filemanager.ObjectMetadata, error) {
+	obj, ok := m.objects[strings.TrimSpace(objectKey)]
+	if !ok {
+		return nil, filemanager.ObjectMetadata{}, filemanager.ErrUploadObjectNotFound
+	}
+	return io.NopCloser(bytes.NewReader(obj.payload)), filemanager.ObjectMetadata{
+		ObjectKey:    objectKey,
+		SizeBytes:    obj.sizeBytes(),
+		ContentType:  obj.contentType,
+		LastModified: &obj.lastMod,
+		ETag:         obj.etag,
+	}, nil
+}
+
+func (m *takeoverWOPIStorageMock) HeadObject(_ context.Context, objectKey string) (filemanager.ObjectMetadata, error) {
+	obj, ok := m.objects[strings.TrimSpace(objectKey)]
+	if !ok {
+		return filemanager.ObjectMetadata{}, filemanager.ErrUploadObjectNotFound
+	}
+	return filemanager.ObjectMetadata{
+		ObjectKey:    objectKey,
+		SizeBytes:    obj.sizeBytes(),
+		ContentType:  obj.contentType,
+		LastModified: &obj.lastMod,
+		ETag:         obj.etag,
+	}, nil
+}
+
+func (m *takeoverWOPIStorageMock) PutObject(_ context.Context, input filemanager.PutObjectInput) (filemanager.ObjectMetadata, error) {
+	payload, err := io.ReadAll(input.Body)
+	if err != nil {
+		return filemanager.ObjectMetadata{}, err
+	}
+	m.objects[strings.TrimSpace(input.ObjectKey)] = takeoverWOPIStoredObject{
+		payload:     append([]byte(nil), payload...),
+		contentType: strings.TrimSpace(input.ContentType),
+		lastMod:     time.Now().UTC(),
+		etag:        "etag-" + strings.TrimSpace(input.ObjectKey),
+	}
+	obj := m.objects[strings.TrimSpace(input.ObjectKey)]
+	return filemanager.ObjectMetadata{
+		ObjectKey:    strings.TrimSpace(input.ObjectKey),
+		SizeBytes:    int64(len(payload)),
+		ContentType:  obj.contentType,
+		LastModified: &obj.lastMod,
+		ETag:         obj.etag,
+	}, nil
+}
+
+func (m *takeoverWOPIStorageMock) CopyObject(_ context.Context, sourceObjectKey, destinationObjectKey string) (filemanager.ObjectMetadata, error) {
+	src, ok := m.objects[strings.TrimSpace(sourceObjectKey)]
+	if !ok {
+		return filemanager.ObjectMetadata{}, filemanager.ErrUploadObjectNotFound
+	}
+	m.objects[strings.TrimSpace(destinationObjectKey)] = src
+	obj := m.objects[strings.TrimSpace(destinationObjectKey)]
+	return filemanager.ObjectMetadata{
+		ObjectKey:    strings.TrimSpace(destinationObjectKey),
+		SizeBytes:    int64(len(obj.payload)),
+		ContentType:  obj.contentType,
+		LastModified: &obj.lastMod,
+		ETag:         obj.etag,
+	}, nil
+}
+
+func (m *takeoverWOPIStorageMock) DeleteObject(_ context.Context, objectKey string) error {
+	delete(m.objects, strings.TrimSpace(objectKey))
+	return nil
+}
+
+func (m *takeoverWOPIStorageMock) PresignGetObject(_ context.Context, objectKey string, _ time.Duration) (string, error) {
+	return "https://example.com/" + strings.TrimSpace(objectKey), nil
+}
+
+type takeoverWOPIAuthMock struct {
+	getUserByIDFn func(context.Context, []byte) (*authdomain.User, error)
+}
+
+func (m *takeoverWOPIAuthMock) GetUserByID(ctx context.Context, id []byte) (*authdomain.User, error) {
+	if m.getUserByIDFn != nil {
+		return m.getUserByIDFn(ctx, id)
+	}
+	return nil, nil
+}
+
+func TestTakeoverWOPIPutContentsReturnsLastModifiedTimeJSON(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+
+	fileSvc := &fileManagerTemplateServiceMock{
+		getFileByIDAnyFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+			if !bytes.Equal(id, fileID) {
+				t.Fatalf("unexpected file id lookup: %x", id)
+			}
+			return &filemanager.File{
+				ID:        fileID,
+				Name:      "purchase_orders.xlsx",
+				ObjectKey: "files/purchase_orders.xlsx",
+				MimeType:  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+				CreatedBy: actorID,
+			}, nil
+		},
+		updateFileFn: func(_ context.Context, row *filemanager.File) error {
+			if row == nil || row.ObjectKey != "files/purchase_orders.xlsx" {
+				t.Fatalf("unexpected updated row: %#v", row)
+			}
+			return nil
+		},
+	}
+
+	xlsxPayload := testXLSXZip(t)
+	storage := &takeoverWOPIStorageMock{
+		objects: map[string]takeoverWOPIStoredObject{
+			"files/purchase_orders.xlsx": {
+				payload:     xlsxPayload,
+				contentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+				lastMod:     time.Now().UTC().Add(-time.Minute),
+				etag:        "etag-final",
+			},
+		},
+	}
+
+	wopiSvc := service.NewWOPIService(service.WOPIConfig{
+		TokenSecret:   "test-secret",
+		PublicBaseURL: "https://api.example.com",
+		EditActionURL: "https://collabora.example.com/loleaflet/{WOPISrc}",
+		TokenTTL:      30 * time.Minute,
+	})
+	token, _, err := wopiSvc.MintAccessToken(fileID, actorID, nil, service.WOPIPermissionWrite)
+	if err != nil {
+		t.Fatalf("mint access token: %v", err)
+	}
+
+	handler := &TakeoverHandler{
+		fileManager: fileSvc,
+		storage:     storage,
+	}
+
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", actorID)
+		return c.Next()
+	})
+	app.Use(middleware.WOPIRequired(wopiSvc))
+	app.Post("/wopi/files/:fileId/contents", handler.PutWOPIContents)
+
+	req := httptest.NewRequest(http.MethodPost, "/wopi/files/"+uuidString(fileID)+"/contents?access_token="+token, bytes.NewReader(xlsxPayload))
+	req.Header.Set("Content-Type", "application/octet-stream")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app test failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d", resp.StatusCode)
+	}
+	var out struct {
+		LastModifiedTime string `json:"LastModifiedTime"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if strings.TrimSpace(out.LastModifiedTime) == "" {
+		t.Fatal("expected last modified time in response body")
+	}
+}
+
+func TestTakeoverWOPIPutContentsAllowsSmallTimestampSkew(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	now := time.Now().UTC()
+
+	fileSvc := &fileManagerTemplateServiceMock{
+		getFileByIDAnyFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+			if !bytes.Equal(id, fileID) {
+				t.Fatalf("unexpected file id lookup: %x", id)
+			}
+			return &filemanager.File{
+				ID:        fileID,
+				Name:      "purchase_orders.xlsx",
+				ObjectKey: "files/purchase_orders.xlsx",
+				MimeType:  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+				CreatedBy: actorID,
+			}, nil
+		},
+	}
+
+	xlsxPayload := testXLSXZip(t)
+	storage := &takeoverWOPIStorageMock{
+		objects: map[string]takeoverWOPIStoredObject{
+			"files/purchase_orders.xlsx": {
+				payload:     xlsxPayload,
+				contentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+				lastMod:     now,
+				etag:        "etag-final",
+			},
+		},
+	}
+
+	wopiSvc := service.NewWOPIService(service.WOPIConfig{
+		TokenSecret:   "test-secret",
+		PublicBaseURL: "https://api.example.com",
+		EditActionURL: "https://collabora.example.com/loleaflet/{WOPISrc}",
+		TokenTTL:      30 * time.Minute,
+	})
+	token, _, err := wopiSvc.MintAccessToken(fileID, actorID, nil, service.WOPIPermissionWrite)
+	if err != nil {
+		t.Fatalf("mint access token: %v", err)
+	}
+
+	handler := &TakeoverHandler{
+		fileManager: fileSvc,
+		storage:     storage,
+	}
+
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		c.Locals("user_id", actorID)
+		return c.Next()
+	})
+	app.Use(middleware.WOPIRequired(wopiSvc))
+	app.Post("/wopi/files/:fileId/contents", handler.PutWOPIContents)
+
+	req := httptest.NewRequest(http.MethodPost, "/wopi/files/"+uuidString(fileID)+"/contents?access_token="+token, bytes.NewReader(xlsxPayload))
+	req.Header.Set("Content-Type", "application/octet-stream")
+	req.Header.Set("X-COOL-WOPI-Timestamp", strconv.FormatInt(now.Add(-5*time.Second).UnixMilli(), 10))
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app test failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d", resp.StatusCode)
+	}
+}
+
+func TestTakeoverWOPIPutContentsAllowsAdminTakeoverAccess(t *testing.T) {
+	adminID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	otherUserID := uuidv7.MustBytes()
+
+	fileSvc := &fileManagerTemplateServiceMock{
+		getFileByIDAnyFn: func(_ context.Context, id []byte) (*filemanager.File, error) {
+			if !bytes.Equal(id, fileID) {
+				t.Fatalf("unexpected file id lookup: %x", id)
+			}
+			return &filemanager.File{
+				ID:        fileID,
+				Name:      "purchase_orders.xlsx",
+				ObjectKey: "files/purchase_orders.xlsx",
+				MimeType:  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+				CreatedBy: otherUserID,
+			}, nil
+		},
+	}
+
+	xlsxPayload := testXLSXZip(t)
+	storage := &takeoverWOPIStorageMock{
+		objects: map[string]takeoverWOPIStoredObject{
+			"files/purchase_orders.xlsx": {
+				payload:     xlsxPayload,
+				contentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+				lastMod:     time.Now().UTC().Add(-time.Minute),
+				etag:        "etag-final",
+			},
+		},
+	}
+
+	wopiSvc := service.NewWOPIService(service.WOPIConfig{
+		TokenSecret:   "test-secret",
+		PublicBaseURL: "https://api.example.com",
+		EditActionURL: "https://collabora.example.com/loleaflet/{WOPISrc}",
+		TokenTTL:      30 * time.Minute,
+	})
+	token, _, err := wopiSvc.MintAccessToken(fileID, adminID, takeoverID, service.WOPIPermissionWrite)
+	if err != nil {
+		t.Fatalf("mint access token: %v", err)
+	}
+
+	handler := &TakeoverHandler{
+		fileManager: fileSvc,
+		storage:     storage,
+		auth: &takeoverWOPIAuthMock{
+			getUserByIDFn: func(_ context.Context, id []byte) (*authdomain.User, error) {
+				if !bytes.Equal(id, adminID) {
+					t.Fatalf("unexpected auth lookup id: %x", id)
+				}
+				return &authdomain.User{
+					ID: adminID,
+					Roles: []authdomain.Role{
+						{Name: "admin"},
+					},
+				}, nil
+			},
+		},
+	}
+
+	takeoverSvc := &takeoverTemplateServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*takeoverdomain.TakeoverAc, error) {
+			if !bytes.Equal(id, takeoverID) {
+				t.Fatalf("unexpected takeover id lookup: %x", id)
+			}
+			return &takeoverdomain.TakeoverAc{
+				ID: takeoverID,
+				Files: []takeoverdomain.TakeoverFile{
+					{
+						FileAttachment: &filemanager.Attachment{
+							File: &filemanager.File{
+								ID:        fileID,
+								Name:      "purchase_orders.xlsx",
+								ObjectKey: "files/purchase_orders.xlsx",
+								MimeType:  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+								CreatedBy: otherUserID,
+							},
+						},
+					},
+				},
+			}, nil
+		},
+	}
+	handler.takeoverAc = service.NewTakeoverModuleService(takeoverSvc)
+
+	app := fiber.New()
+	app.Use(middleware.WOPIRequired(wopiSvc))
+	app.Post("/wopi/files/:fileId/contents", handler.PutWOPIContents)
+
+	req := httptest.NewRequest(http.MethodPost, "/wopi/files/"+uuidString(fileID)+"/contents?access_token="+token, bytes.NewReader(xlsxPayload))
+	req.Header.Set("Content-Type", "application/octet-stream")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app test failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d", resp.StatusCode)
+	}
+}
+
+func TestTakeoverWOPIGetContentsReadsTakeoverScopedTemplateFile(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	payload := testXLSXZip(t)
+
+	storage := &takeoverWOPIStorageMock{
+		objects: map[string]takeoverWOPIStoredObject{
+			"files/purchase_orders.xlsx": {
+				payload:     payload,
+				contentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+				lastMod:     time.Now().UTC().Add(-time.Minute),
+				etag:        "etag-template-copy",
+			},
+		},
+	}
+	wopiSvc := service.NewWOPIService(service.WOPIConfig{
+		TokenSecret:   "test-secret",
+		PublicBaseURL: "https://api.example.com",
+		EditActionURL: "https://collabora.example.com/loleaflet/{WOPISrc}",
+		TokenTTL:      30 * time.Minute,
+	})
+	token, _, err := wopiSvc.MintAccessToken(fileID, actorID, takeoverID, service.WOPIPermissionWrite)
+	if err != nil {
+		t.Fatalf("mint access token: %v", err)
+	}
+
+	takeoverSvc := &takeoverTemplateServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*takeoverdomain.TakeoverAc, error) {
+			if !bytes.Equal(id, takeoverID) {
+				t.Fatalf("unexpected takeover id lookup: %x", id)
+			}
+			return &takeoverdomain.TakeoverAc{
+				ID:        takeoverID,
+				CreatedBy: actorID,
+				Files: []takeoverdomain.TakeoverFile{
+					{
+						FileAttachment: &filemanager.Attachment{
+							File: &filemanager.File{
+								ID:        fileID,
+								Name:      "purchase_orders.xlsx",
+								ObjectKey: "files/purchase_orders.xlsx",
+								MimeType:  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+								SizeBytes: int64(len(payload)),
+								CreatedBy: actorID,
+								UpdatedAt: time.Now().UTC().Add(-time.Minute),
+							},
+						},
+					},
+				},
+			}, nil
+		},
+	}
+	handler := &TakeoverHandler{
+		storage:    storage,
+		takeoverAc: service.NewTakeoverModuleService(takeoverSvc),
+	}
+
+	app := fiber.New()
+	app.Use(middleware.WOPIRequired(wopiSvc))
+	app.Get("/wopi/files/:fileId", handler.CheckWOPIFileInfo)
+	app.Get("/wopi/files/:fileId/contents", handler.GetWOPIContents)
+
+	infoReq := httptest.NewRequest(http.MethodGet, "/wopi/files/"+uuidString(fileID)+"?access_token="+token, nil)
+	infoResp, err := app.Test(infoReq)
+	if err != nil {
+		t.Fatalf("check info app test failed: %v", err)
+	}
+	if infoResp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected check info status %d", infoResp.StatusCode)
+	}
+
+	contentReq := httptest.NewRequest(http.MethodGet, "/wopi/files/"+uuidString(fileID)+"/contents?access_token="+token, nil)
+	contentResp, err := app.Test(contentReq)
+	if err != nil {
+		t.Fatalf("get contents app test failed: %v", err)
+	}
+	if contentResp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected get contents status %d", contentResp.StatusCode)
+	}
+	got, err := io.ReadAll(contentResp.Body)
+	if err != nil {
+		t.Fatalf("read contents body: %v", err)
+	}
+	if !bytes.Equal(got, payload) {
+		t.Fatalf("unexpected WOPI contents length got %d want %d", len(got), len(payload))
+	}
+	if ct := strings.TrimSpace(contentResp.Header.Get("Content-Type")); !strings.Contains(ct, "spreadsheetml.sheet") {
+		t.Fatalf("unexpected content type %q", ct)
+	}
+}
+
+// TestTakeoverWOPIGetContentsRejectsTruncatedBody guards the read-fully-and-
+// validate-size convention: when the storage body delivers fewer bytes than the
+// object metadata advertises, GetWOPIContents must fail with a non-200 error
+// rather than silently sending a corrupt 200 that Collabora would save verbatim.
+func TestTakeoverWOPIGetContentsRejectsTruncatedBody(t *testing.T) {
+	actorID := uuidv7.MustBytes()
+	fileID := uuidv7.MustBytes()
+	takeoverID := uuidv7.MustBytes()
+	payload := testXLSXZip(t)
+
+	storage := &takeoverWOPIStorageMock{
+		objects: map[string]takeoverWOPIStoredObject{
+			"files/purchase_orders.xlsx": {
+				payload:     payload,
+				contentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+				lastMod:     time.Now().UTC().Add(-time.Minute),
+				etag:        "etag-truncated",
+				// Advertise more bytes than the body actually returns.
+				advertisedSize: int64(len(payload)) + 4096,
+			},
+		},
+	}
+	wopiSvc := service.NewWOPIService(service.WOPIConfig{
+		TokenSecret:   "test-secret",
+		PublicBaseURL: "https://api.example.com",
+		EditActionURL: "https://collabora.example.com/loleaflet/{WOPISrc}",
+		TokenTTL:      30 * time.Minute,
+	})
+	token, _, err := wopiSvc.MintAccessToken(fileID, actorID, takeoverID, service.WOPIPermissionWrite)
+	if err != nil {
+		t.Fatalf("mint access token: %v", err)
+	}
+
+	takeoverSvc := &takeoverTemplateServiceMock{
+		getByIDFn: func(_ context.Context, id []byte) (*takeoverdomain.TakeoverAc, error) {
+			if !bytes.Equal(id, takeoverID) {
+				t.Fatalf("unexpected takeover id lookup: %x", id)
+			}
+			return &takeoverdomain.TakeoverAc{
+				ID:        takeoverID,
+				CreatedBy: actorID,
+				Files: []takeoverdomain.TakeoverFile{
+					{
+						FileAttachment: &filemanager.Attachment{
+							File: &filemanager.File{
+								ID:        fileID,
+								Name:      "purchase_orders.xlsx",
+								ObjectKey: "files/purchase_orders.xlsx",
+								MimeType:  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+								SizeBytes: int64(len(payload)) + 4096,
+								CreatedBy: actorID,
+								UpdatedAt: time.Now().UTC().Add(-time.Minute),
+							},
+						},
+					},
+				},
+			}, nil
+		},
+	}
+	handler := &TakeoverHandler{
+		storage:    storage,
+		takeoverAc: service.NewTakeoverModuleService(takeoverSvc),
+	}
+
+	app := fiber.New()
+	app.Use(middleware.WOPIRequired(wopiSvc))
+	app.Get("/wopi/files/:fileId/contents", handler.GetWOPIContents)
+
+	contentReq := httptest.NewRequest(http.MethodGet, "/wopi/files/"+uuidString(fileID)+"/contents?access_token="+token, nil)
+	contentResp, err := app.Test(contentReq)
+	if err != nil {
+		t.Fatalf("get contents app test failed: %v", err)
+	}
+	if contentResp.StatusCode == http.StatusOK {
+		body, _ := io.ReadAll(contentResp.Body)
+		t.Fatalf("expected non-200 for truncated body, got 200 with %d bytes (would corrupt the document)", len(body))
+	}
+	if contentResp.StatusCode < 400 {
+		t.Fatalf("expected error status >= 400 for truncated body, got %d", contentResp.StatusCode)
+	}
+}
diff --git a/internal/transport/http/handlers/timezone_helper.go b/internal/transport/http/handlers/timezone_helper.go
new file mode 100644
index 0000000..e8656bc
--- /dev/null
+++ b/internal/transport/http/handlers/timezone_helper.go
@@ -0,0 +1,21 @@
+package handlers
+
+import (
+	"errors"
+
+	tzpkg "wucher/internal/shared/pkg/timezone"
+	"wucher/internal/transport/http/jsonapi"
+)
+
+func timezoneValidationError(pointer string, err error) []jsonapi.ErrorObject {
+	detail := "timezone must be a valid IANA timezone"
+	if errors.Is(err, tzpkg.ErrEmpty) {
+		detail = "timezone cannot be empty"
+	}
+	return []jsonapi.ErrorObject{{
+		Status: "422",
+		Title:  "Validation error",
+		Detail: detail,
+		Source: &jsonapi.ErrorSource{Pointer: pointer},
+	}}
+}
diff --git a/internal/transport/http/handlers/user_getter.go b/internal/transport/http/handlers/user_getter.go
new file mode 100644
index 0000000..79fd4b0
--- /dev/null
+++ b/internal/transport/http/handlers/user_getter.go
@@ -0,0 +1,9 @@
+package handlers
+
+import "wucher/internal/shared/pkg/userctx"
+
+// WireUserNameGetter is a convenience wrapper around userctx.WireUserNameGetter.
+// Call this once during application startup to enable LastName resolution in handlers.
+func WireUserNameGetter(getter userctx.UserNameGetter) {
+	userctx.WireUserNameGetter(getter)
+}
diff --git a/internal/transport/http/handlers/user_handler.go b/internal/transport/http/handlers/user_handler.go
new file mode 100644
index 0000000..e27c913
--- /dev/null
+++ b/internal/transport/http/handlers/user_handler.go
@@ -0,0 +1,1131 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/user"
+	appservice "wucher/internal/service"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/attachmentresolver"
+	tzpkg "wucher/internal/shared/pkg/timezone"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+const (
+	userProfileAttachmentRefType  = "user_profile"
+	userProfileAttachmentCategory = "profile_picture"
+)
+
+type UserHandler struct {
+	svc         user.Service
+	fileManager filemanager.Service
+	storage     fileManagerDownloadURLStorage
+	validate    *validators.Validator
+}
+
+type userDetailedWriter interface {
+	CreateDetailed(context.Context, appservice.UserCreateInput) (*appservice.UserWriteResult, error)
+	UpdateDetailed(context.Context, appservice.UserUpdateInput) (*appservice.UserWriteResult, error)
+}
+
+func NewUserHandler(svc user.Service) *UserHandler {
+	return &UserHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+func (h *UserHandler) WithFileManagerService(fileManagerSvc filemanager.Service) *UserHandler {
+	h.fileManager = fileManagerSvc
+	return h
+}
+
+func (h *UserHandler) WithFileStorage(storage fileManagerDownloadURLStorage) *UserHandler {
+	h.storage = storage
+	return h
+}
+
+func (h *UserHandler) createUserWithService(c *fiber.Ctx, svc userDetailedWriter) bool {
+	var req dto.UserCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		_ = writeUserErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "invalid json",
+		}})
+		return true
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		_ = writeUserErrors(c, fiber.StatusUnprocessableEntity, errs)
+		return true
+	}
+	if strings.TrimSpace(req.Data.Attributes.Username) == "" {
+		_ = writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "username is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/username"},
+		}})
+		return true
+	}
+	roleID, err := uuidv7.ParseString(req.Data.Attributes.RoleID)
+	if err != nil {
+		_ = writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "role_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/role_id"},
+		}})
+		return true
+	}
+	roleIDs, roleErrs := parseRoleIDs(req.Data.Attributes.RoleIDs, "/data/attributes/role_ids")
+	if len(roleErrs) > 0 {
+		_ = writeUserErrors(c, fiber.StatusUnprocessableEntity, roleErrs)
+		return true
+	}
+	roleIDs = normalizeRoleIDs(roleID, roleIDs)
+
+	userTimezone := tzpkg.Default
+	if req.Data.Attributes.Timezone != nil {
+		normalized, err := tzpkg.Normalize(*req.Data.Attributes.Timezone)
+		if err != nil {
+			_ = writeUserErrors(c, fiber.StatusUnprocessableEntity, timezoneValidationError("/data/attributes/timezone", err))
+			return true
+		}
+		userTimezone = normalized
+	}
+
+	modelID := uuidv7.MustBytes()
+	imageAttachmentID, imageResolveErr := h.resolveProfileImageAttachmentID(c, modelID, req.Data.Attributes.ImageUUID)
+	if imageResolveErr {
+		return true
+	}
+	res, err := svc.CreateDetailed(c.UserContext(), appservice.UserCreateInput{
+		ID:                  modelID,
+		Email:               strings.TrimSpace(req.Data.Attributes.Email),
+		Username:            strings.TrimSpace(req.Data.Attributes.Username),
+		FirstName:           strings.TrimSpace(req.Data.Attributes.FirstName),
+		LastName:            strings.TrimSpace(req.Data.Attributes.LastName),
+		MobilePhone:         strings.TrimSpace(req.Data.Attributes.MobilePhone),
+		Timezone:            userTimezone,
+		RoleID:              roleID,
+		RoleIDs:             roleIDs,
+		ProfileAttachmentID: imageAttachmentID,
+		CreatedBy:           actorUserID(c),
+		UpdatedBy:           actorUserID(c),
+	})
+	if err != nil {
+		var writeErr *appservice.UserWriteError
+		if errors.As(err, &writeErr) {
+			errObj := jsonapi.ErrorObject{
+				Status: strconv.Itoa(writeErr.Status),
+				Title:  writeErr.Title,
+				Detail: writeErr.Detail,
+			}
+			if strings.TrimSpace(writeErr.Pointer) != "" {
+				errObj.Source = &jsonapi.ErrorSource{Pointer: writeErr.Pointer}
+			}
+			_ = writeUserErrors(c, writeErr.Status, []jsonapi.ErrorObject{errObj})
+			return true
+		}
+		_ = writeHandlerErrorDefWithStatus(c, "UserHandler.Create", fiber.StatusBadRequest, apperrorsx.ErrInternal, err)
+		return true
+	}
+	if len(res.Row.ProfileAttachmentID) == 16 {
+		_ = syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, nil, res.Row.ProfileAttachmentID, actorUserID(c))
+	}
+	_ = response.Write(c, fiber.StatusCreated, h.userResource(c.UserContext(), res.Row))
+	return true
+}
+
+func (h *UserHandler) updateUserWithService(c *fiber.Ctx, svc userDetailedWriter) bool {
+	uuidStr := c.Params("uuid")
+	userID, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		_ = writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+		return true
+	}
+
+	rawBody := append([]byte(nil), c.Body()...)
+	var req dto.UserUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		_ = writeUserErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "invalid json",
+		}})
+		return true
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		_ = writeUserErrors(c, fiber.StatusUnprocessableEntity, errs)
+		return true
+	}
+	imagePatch := parseOptionalStringFieldFromJSONBody(rawBody, "image_uuid")
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		_ = writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+		return true
+	}
+	if req.Data.ID != uuidStr {
+		_ = writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+		return true
+	}
+
+	if req.Data.Attributes.Email == nil &&
+		req.Data.Attributes.FirstName == nil &&
+		req.Data.Attributes.LastName == nil &&
+		req.Data.Attributes.MobilePhone == nil &&
+		req.Data.Attributes.Timezone == nil &&
+		!imagePatch.Set {
+		_ = writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+		return true
+	}
+
+	var imageAttachmentID []byte
+	imageAttachmentSet := false
+	if imagePatch.Set {
+		imageAttachmentSet = true
+		if !imagePatch.Valid || strings.TrimSpace(imagePatch.Value) == "" {
+			imageAttachmentID = nil
+		} else {
+			rawImageUUID := strings.TrimSpace(imagePatch.Value)
+			resolved, handled := h.resolveProfileImageAttachmentID(c, userID, &rawImageUUID)
+			if handled {
+				return true
+			}
+			imageAttachmentID = resolved
+		}
+	}
+
+	var timezone *string
+	if req.Data.Attributes.Timezone != nil {
+		normalized, err := tzpkg.Normalize(*req.Data.Attributes.Timezone)
+		if err != nil {
+			_ = writeUserErrors(c, fiber.StatusUnprocessableEntity, timezoneValidationError("/data/attributes/timezone", err))
+			return true
+		}
+		timezone = &normalized
+	}
+
+	res, err := svc.UpdateDetailed(c.UserContext(), appservice.UserUpdateInput{
+		ID:                   userID,
+		Email:                req.Data.Attributes.Email,
+		FirstName:            req.Data.Attributes.FirstName,
+		LastName:             req.Data.Attributes.LastName,
+		MobilePhone:          req.Data.Attributes.MobilePhone,
+		Timezone:             timezone,
+		ProfileAttachmentSet: imageAttachmentSet,
+		ProfileAttachmentID:  imageAttachmentID,
+		ActorUserID:          actorUserID(c),
+	})
+	if err != nil {
+		var writeErr *appservice.UserWriteError
+		if errors.As(err, &writeErr) {
+			errObj := jsonapi.ErrorObject{
+				Status: strconv.Itoa(writeErr.Status),
+				Title:  writeErr.Title,
+				Detail: writeErr.Detail,
+			}
+			if strings.TrimSpace(writeErr.Pointer) != "" {
+				errObj.Source = &jsonapi.ErrorSource{Pointer: writeErr.Pointer}
+			}
+			_ = writeUserErrors(c, writeErr.Status, []jsonapi.ErrorObject{errObj})
+			return true
+		}
+		_ = writeHandlerErrorDefWithStatus(c, "UserHandler.Update", fiber.StatusBadRequest, apperrorsx.ErrInternal, err)
+		return true
+	}
+	if err := syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, res.PreviousProfileAttachmentID, res.Row.ProfileAttachmentID, actorUserID(c)); err != nil {
+		_ = writeHandlerErrorDefWithStatus(c, "UserHandler.Update.Attachments", fiber.StatusBadRequest, apperrorsx.ErrInternal, err)
+		return true
+	}
+	_ = response.Write(c, fiber.StatusOK, h.userResource(c.UserContext(), res.Row))
+	return true
+}
+
+// CreateUser godoc
+// @Summary Create user
+// @Description Create a new user. Email, username, first name, last name and role_id are required. Use role_ids to assign additional roles.
+// @Tags Users
+// @Accept json
+// @Produce json
+// @Param request body dto.UserCreateRequest true "JSON:API User create request"
+// @Success 201 {object} dto.UserResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/users/create [post]
+func (h *UserHandler) Create(c *fiber.Ctx) error {
+	svc, ok := h.svc.(userDetailedWriter)
+	if !ok {
+		return writeUserErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Create failed",
+			Detail: "user service is not configured",
+		}})
+	}
+	if h.createUserWithService(c, svc) {
+		return nil
+	}
+
+	var req dto.UserCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeUserErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "invalid json",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeUserErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	if strings.TrimSpace(req.Data.Attributes.Username) == "" {
+		return writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "username is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/username"},
+		}})
+	}
+
+	roleID, err := uuidv7.ParseString(req.Data.Attributes.RoleID)
+	if err != nil {
+		return writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "role_id is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/role_id"},
+		}})
+	}
+	roleIDs, roleErrs := parseRoleIDs(req.Data.Attributes.RoleIDs, "/data/attributes/role_ids")
+	if len(roleErrs) > 0 {
+		return writeUserErrors(c, fiber.StatusUnprocessableEntity, roleErrs)
+	}
+	roleIDs = normalizeRoleIDs(roleID, roleIDs)
+
+	userTimezone := tzpkg.Default
+	if req.Data.Attributes.Timezone != nil {
+		normalized, err := tzpkg.Normalize(*req.Data.Attributes.Timezone)
+		if err != nil {
+			return writeUserErrors(c, fiber.StatusUnprocessableEntity, timezoneValidationError("/data/attributes/timezone", err))
+		}
+		userTimezone = normalized
+	}
+
+	u := &user.User{
+		ID:          uuidv7.MustBytes(),
+		Email:       strings.TrimSpace(req.Data.Attributes.Email),
+		Username:    strings.TrimSpace(req.Data.Attributes.Username),
+		FirstName:   strings.TrimSpace(req.Data.Attributes.FirstName),
+		LastName:    strings.TrimSpace(req.Data.Attributes.LastName),
+		MobilePhone: strings.TrimSpace(req.Data.Attributes.MobilePhone),
+		Timezone:    userTimezone,
+		RoleID:      roleID,
+		RoleIDs:     roleIDs,
+		CreatedBy:   actorUserID(c),
+	}
+	imageAttachmentID, imageResolveErr := h.resolveProfileImageAttachmentID(
+		c,
+		u.ID,
+		req.Data.Attributes.ImageUUID,
+	)
+	if imageResolveErr {
+		return nil
+	}
+	u.ProfileAttachmentID = imageAttachmentID
+
+	if err := h.svc.Create(c.UserContext(), u); err != nil {
+		return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "UserHandler.Create", err)
+	}
+	if len(u.ProfileAttachmentID) == 16 {
+		if err := syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, nil, u.ProfileAttachmentID, actorUserID(c)); err != nil {
+			return writeInternalHandlerErrorWithStatus(c, fiber.StatusBadRequest, "UserHandler.Create.Attachments", err)
+		}
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), u.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, h.userResource(c.UserContext(), created))
+	}
+	return response.Write(c, fiber.StatusCreated, h.userResource(c.UserContext(), u))
+}
+
+// UpdateUser godoc
+// @Summary Update user (partial)
+// @Description Patch user by ID. Provide at least one attribute to update.
+// @Tags Users
+// @Accept json
+// @Produce json
+// @Param uuid path string true "User UUID (UUIDv7)"
+// @Param request body dto.UserUpdateRequest true "JSON:API User update request"
+// @Success 200 {object} dto.UserResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/users/update/{uuid} [patch]
+func (h *UserHandler) Update(c *fiber.Ctx) error {
+	svc, ok := h.svc.(userDetailedWriter)
+	if !ok {
+		return writeUserErrors(c, fiber.StatusInternalServerError, []jsonapi.ErrorObject{{
+			Status: "500",
+			Title:  "Update failed",
+			Detail: "user service is not configured",
+		}})
+	}
+	if h.updateUserWithService(c, svc) {
+		return nil
+	}
+
+	uuidStr := c.Params("uuid")
+	userID, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	rawBody := append([]byte(nil), c.Body()...)
+	var req dto.UserUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeUserErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: "invalid json",
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeUserErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+	imagePatch := parseOptionalStringFieldFromJSONBody(rawBody, "image_uuid")
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	if req.Data.Attributes.Email == nil &&
+		req.Data.Attributes.FirstName == nil &&
+		req.Data.Attributes.LastName == nil &&
+		req.Data.Attributes.MobilePhone == nil &&
+		req.Data.Attributes.Timezone == nil &&
+		!imagePatch.Set {
+		return writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), userID)
+	if err != nil || existing == nil {
+		return writeUserErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "user not found",
+		}})
+	}
+	prevImageAttachmentID := append([]byte(nil), existing.ProfileAttachmentID...)
+
+	if req.Data.Attributes.Email != nil {
+		email := strings.TrimSpace(*req.Data.Attributes.Email)
+		if email == "" {
+			return writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "email cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/email"},
+			}})
+		}
+		existing.Email = email
+	}
+	if req.Data.Attributes.FirstName != nil {
+		firstName := strings.TrimSpace(*req.Data.Attributes.FirstName)
+		if firstName == "" {
+			return writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "first_name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/first_name"},
+			}})
+		}
+
+		existing.FirstName = firstName
+	}
+	if req.Data.Attributes.LastName != nil {
+		lastName := strings.TrimSpace(*req.Data.Attributes.LastName)
+		if lastName == "" {
+			return writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "last_name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/last_name"},
+			}})
+		}
+		existing.LastName = lastName
+	}
+	if req.Data.Attributes.MobilePhone != nil {
+		existing.MobilePhone = strings.TrimSpace(*req.Data.Attributes.MobilePhone)
+	}
+	if req.Data.Attributes.Timezone != nil {
+		normalized, err := tzpkg.Normalize(*req.Data.Attributes.Timezone)
+		if err != nil {
+			return writeUserErrors(c, fiber.StatusUnprocessableEntity, timezoneValidationError("/data/attributes/timezone", err))
+		}
+		existing.Timezone = normalized
+	}
+	if imagePatch.Set {
+		existing.ProfileAttachmentPatchSet = true
+		if !imagePatch.Valid || strings.TrimSpace(imagePatch.Value) == "" {
+			existing.ProfileAttachmentID = nil
+			existing.ImageAttachmentID = nil
+		} else {
+			rawImageUUID := strings.TrimSpace(imagePatch.Value)
+			imageAttachmentID, imageResolveErr := h.resolveProfileImageAttachmentID(c, existing.ID, &rawImageUUID)
+			if imageResolveErr {
+				return nil
+			}
+			existing.ProfileAttachmentID = imageAttachmentID
+			existing.ImageAttachmentID = append([]byte(nil), imageAttachmentID...)
+		}
+	}
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeUserErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if err := syncAttachmentLifecycleSwap(c.UserContext(), h.fileManager, prevImageAttachmentID, existing.ProfileAttachmentID, actorUserID(c)); err != nil {
+		return writeUserErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, h.userResource(c.UserContext(), updated))
+	}
+	return response.Write(c, fiber.StatusOK, h.userResource(c.UserContext(), existing))
+}
+
+// DeleteUser godoc
+// @Summary Delete user
+// @Tags Users
+// @Produce json
+// @Param uuid path string true "User UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/users/delete/{uuid} [delete]
+func (h *UserHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	userID, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	existing, _ := h.svc.GetByID(c.UserContext(), userID)
+	var previousImageFileID []byte
+	if existing != nil {
+		previousImageFileID, _ = resolveFileIDFromAttachment(c.UserContext(), h.fileManager, existing.ProfileAttachmentID)
+	}
+
+	if err := h.svc.Delete(c.UserContext(), userID); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeUserErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+				Status: "404",
+				Title:  "Not found",
+				Detail: "user not found",
+			}})
+		}
+		return writeUserErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Delete failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+	if len(previousImageFileID) == 16 {
+		if err := syncFileLifecycleSwap(c.UserContext(), h.fileManager, previousImageFileID, nil, actorUserID(c)); err != nil {
+			return writeUserErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+				Status: "400",
+				Title:  "Delete failed",
+				Detail: "an internal error occurred",
+			}})
+		}
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "user_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// GetUserByID godoc
+// @Summary Get user by ID
+// @Tags Users
+// @Produce json
+// @Param uuid path string true "User UUID (UUIDv7)"
+// @Success 200 {object} dto.UserResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/users/get/{uuid} [get]
+func (h *UserHandler) Get(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	userID, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeUserErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	u, err := h.svc.GetByID(c.UserContext(), userID)
+	if err != nil || u == nil {
+		return writeUserErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "user not found",
+		}})
+	}
+
+	return response.Write(c, fiber.StatusOK, h.userResource(c.UserContext(), u))
+}
+
+// ListUsers godoc
+// @Summary List users
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: email, -email, first_name, -first_name, last_name, -last_name, created_at, -created_at, updated_at, -updated_at.
+// @Tags Users
+// @Produce json
+// @Param filter[search] query string false "Search by username/email/first_name/last_name (contains)"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.UserListResponse
+// @Router /api/v1/users/get-all [get]
+func (h *UserHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("filter[name]")
+	}
+	if filter == "" {
+		filter = c.Query("filter[email]")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 1)
+	pageSize := parseIntDefault(c.Query("page[size]"), 20)
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	users, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return writeUserErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	data := make([]dto.UserResource, 0, len(users))
+	for i := range users {
+		data = append(data, h.userResource(c.UserContext(), &users[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListUsersDatatable godoc
+// @Summary List users (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags Users
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.UserDataTableResponse
+// @Router /api/v1/users/get-all/dt [get]
+func (h *UserHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	users, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return writeUserErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: "an internal error occurred",
+		}})
+	}
+
+	data := make([]dto.UserResource, 0, len(users))
+	for i := range users {
+		data = append(data, h.userResource(c.UserContext(), &users[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func (h *UserHandler) userResource(ctx context.Context, u *user.User) dto.UserResource {
+	id, _ := uuidv7.BytesToString(u.ID)
+	imageUUID := uuidBytesToStringOrEmpty(u.ProfileAttachmentID)
+	imageDownloadURL := ""
+	imageThumbnailDownloadURL := ""
+	var imageOriginalSizeBytes *int64
+	if u.ProfileAttachment != nil && u.ProfileAttachment.File != nil {
+		asset := resolveFileManagerDownloadURLs(ctx, h.storage, u.ProfileAttachment.File)
+		imageDownloadURL = strings.TrimSpace(asset.OriginalURL)
+		imageThumbnailDownloadURL = strings.TrimSpace(asset.ThumbnailURL)
+		imageOriginalSizeBytes = int64Ptr(asset.OriginalSizeBytes)
+	}
+	var profilePicture *dto.UserImage
+	if imageUUID != "" || imageDownloadURL != "" || imageThumbnailDownloadURL != "" {
+		profilePicture = &dto.UserImage{
+			UUID:                 imageUUID,
+			DownloadURL:          imageDownloadURL,
+			ThumbnailDownloadURL: imageThumbnailDownloadURL,
+			OriginalSizeBytes:    imageOriginalSizeBytes,
+		}
+	}
+	roleID, roleIDs, primaryRole, roles := buildUserRoleResource(u)
+	if len(roleIDs) > 1 {
+		roleID = ""
+	} else {
+		roleIDs = nil
+	}
+	var emailVerifiedAt string
+	if u.EmailVerifiedAt != nil {
+		emailVerifiedAt = u.EmailVerifiedAt.UTC().Format(time.RFC3339)
+	}
+	return dto.UserResource{
+		Type: "user",
+		ID:   id,
+		Attributes: dto.UserAttributes{
+			Email:           u.Email,
+			Username:        u.Username,
+			FirstName:       u.FirstName,
+			LastName:        u.LastName,
+			MobilePhone:     u.MobilePhone,
+			Timezone:        tzpkg.WithDefault(u.Timezone),
+			ProfilePicture:  profilePicture,
+			RoleID:          roleID,
+			RoleIDs:         roleIDs,
+			CreatedBy:       uuidStringOrEmpty(u.CreatedBy),
+			EmailVerifiedAt: emailVerifiedAt,
+			Role:            primaryRole,
+			Roles:           roles,
+		},
+	}
+}
+
+func uuidBytesToStringOrEmpty(raw []byte) string {
+	if len(raw) != 16 {
+		return ""
+	}
+	s, err := uuidv7.BytesToString(raw)
+	if err != nil {
+		return ""
+	}
+	return s
+}
+
+func (h *UserHandler) resolveProfileImageAttachmentID(
+	c *fiber.Ctx,
+	userID []byte,
+	rawFileUUID *string,
+) ([]byte, bool) {
+	if rawFileUUID == nil || strings.TrimSpace(*rawFileUUID) == "" {
+		return nil, false
+	}
+
+	raw := strings.TrimSpace(*rawFileUUID)
+
+	if hasNonEmptyOptionalString(rawFileUUID) && h.fileManager != nil {
+		candidateID, err := uuidv7.ParseString(raw)
+		if err == nil {
+			attachment, getErr := h.fileManager.GetAttachmentByID(c.UserContext(), candidateID)
+			if getErr != nil {
+				_ = writeHandlerErrorDefWithStatus(c, "UserHandler.ResolveProfileImageAttachment.GetAttachment", fiber.StatusBadRequest, apperrorsx.ErrInternal, getErr)
+				return nil, true
+			}
+			if attachment != nil {
+				return candidateID, false
+			}
+		}
+	}
+
+	if h.fileManager != nil {
+		fileID, fileIDErr := uuidv7.ParseString(raw)
+		if fileIDErr == nil {
+			refID := idString(userID)
+			existing, _, listErr := h.fileManager.ListAttachmentsByReference(c.UserContext(), filemanager.ListAttachmentsParams{
+				RefType: userProfileAttachmentRefType,
+				RefID:   refID,
+				Limit:   100,
+				Offset:  0,
+			})
+			if listErr != nil {
+				_ = writeHandlerErrorDefWithStatus(c, "UserHandler.ResolveProfileImageAttachment.ListAttachments", fiber.StatusBadRequest, apperrorsx.ErrInternal, listErr)
+				return nil, true
+			}
+
+			for i := range existing {
+				if string(existing[i].FileID) == string(fileID) {
+					return existing[i].ID, false
+				}
+			}
+
+			for i := range existing {
+				if delErr := h.fileManager.DeleteAttachment(c.UserContext(), existing[i].ID); delErr != nil {
+					_ = writeHandlerErrorDefWithStatus(c, "UserHandler.ResolveProfileImageAttachment.DeleteAttachment", fiber.StatusBadRequest, apperrorsx.ErrInternal, delErr)
+					return nil, true
+				}
+			}
+
+			attachmentID, handled := resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+				FileManager: h.fileManager,
+
+				RawFileID: rawFileUUID,
+
+				AttachmentField: "profile_attachment_id",
+				FileField:       "image_uuid",
+
+				RequireValue: false,
+
+				RefType:  userProfileAttachmentRefType,
+				RefID:    refID,
+				Category: ptrString(userProfileAttachmentCategory),
+
+				IsPrimary: true,
+				ActorID:   actorUserID(c),
+
+				ValidateAttachmentExists: false,
+			}, "Update failed")
+			if handled {
+				return nil, true
+			}
+			return attachmentID, false
+		}
+	}
+
+	return resolveAttachmentIDFromInput(c, attachmentresolver.Params{
+		FileManager: h.fileManager,
+
+		RawFileID: rawFileUUID,
+
+		AttachmentField: "profile_attachment_id",
+		FileField:       "image_uuid",
+
+		RequireValue: false,
+
+		RefType:  userProfileAttachmentRefType,
+		RefID:    idString(userID),
+		Category: ptrString(userProfileAttachmentCategory),
+
+		IsPrimary: true,
+		ActorID:   actorUserID(c),
+
+		ValidateAttachmentExists: false,
+	}, "Update failed")
+}
+
+func ptrString(v string) *string { return &v }
+
+func parseOptionalStringFieldFromJSONBody(raw []byte, field string) dto.NullString {
+	out := dto.NullString{}
+	if len(raw) == 0 || strings.TrimSpace(field) == "" {
+		return out
+	}
+
+	var body map[string]any
+	if err := json.Unmarshal(raw, &body); err != nil {
+		return out
+	}
+	data, ok := body["data"].(map[string]any)
+	if !ok {
+		return out
+	}
+	attrs, ok := data["attributes"].(map[string]any)
+	if !ok {
+		return out
+	}
+	v, exists := attrs[field]
+	if !exists {
+		return out
+	}
+
+	out.Set = true
+	if v == nil {
+		out.Valid = false
+		out.Value = ""
+		return out
+	}
+	s, ok := v.(string)
+	if !ok {
+		out.Valid = false
+		out.Value = ""
+		return out
+	}
+	out.Valid = true
+	out.Value = s
+	return out
+}
+
+func writeUserErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		if strings.TrimSpace(e.Code) == "" || strings.TrimSpace(e.ErrorCode) == "" {
+			code, errorCode := inferUserErrorCode(status, e.Title, e.Detail)
+			if strings.TrimSpace(e.Code) == "" {
+				e.Code = code
+			}
+			if strings.TrimSpace(e.ErrorCode) == "" {
+				e.ErrorCode = errorCode
+			}
+		}
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferUserErrorCode(status int, title, detail string) (string, string) {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.CodeUserNotFound, apperrorsx.ErrUserNotFound.ErrorCode
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "timezone"):
+			return apperrorsx.CodeUserTimezoneInvalid, apperrorsx.ErrUserTimezoneInvalid.ErrorCode
+		case strings.Contains(lowerDetail, "role_ids contains"):
+			return apperrorsx.CodeUserRoleIDsInvalid, apperrorsx.ErrUserRoleIDsInvalid.ErrorCode
+		case strings.Contains(lowerDetail, "role_ids must contain"):
+			return apperrorsx.CodeUserRoleIDsRequired, apperrorsx.ErrUserRoleIDsRequired.ErrorCode
+		case strings.Contains(lowerDetail, "primary role"):
+			return apperrorsx.CodeUserPrimaryRoleInvalid, apperrorsx.ErrUserPrimaryRoleInvalid.ErrorCode
+		default:
+			return apperrorsx.CodeUserValidationFailed, apperrorsx.ErrUserValidationFailed.ErrorCode
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.CodeUserInvalidJSON, apperrorsx.ErrUserInvalidJSON.ErrorCode
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.CodeUserCreateFailed, apperrorsx.ErrUserCreateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.CodeUserUpdateFailed, apperrorsx.ErrUserUpdateFailed.ErrorCode
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.CodeUserDeleteFailed, apperrorsx.ErrUserDeleteFailed.ErrorCode
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.CodeUserListFailed, apperrorsx.ErrUserListFailed.ErrorCode
+		default:
+			if strings.Contains(lowerDetail, "uuid") {
+				return apperrorsx.CodeUserInvalidUUID, apperrorsx.ErrUserInvalidUUID.ErrorCode
+			}
+			return apperrorsx.CodeUserInvalidPayload, apperrorsx.ErrUserInvalidPayload.ErrorCode
+		}
+	default:
+		return apperrorsx.CodeInternalServerError, apperrorsx.ErrInternal.ErrorCode
+	}
+}
+
+func parseRoleIDs(raw []string, pointer string) ([][]byte, []jsonapi.ErrorObject) {
+	if raw == nil {
+		return nil, nil
+	}
+	if len(raw) == 0 {
+		return nil, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "role_ids must contain at least one role",
+			Source: &jsonapi.ErrorSource{Pointer: pointer},
+		}}
+	}
+
+	roleIDs := make([][]byte, 0, len(raw))
+	for i := range raw {
+		roleID, err := uuidv7.ParseString(strings.TrimSpace(raw[i]))
+		if err != nil {
+			return nil, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "role_ids contains an invalid UUID",
+				Source: &jsonapi.ErrorSource{Pointer: pointer},
+			}}
+		}
+		roleIDs = append(roleIDs, roleID)
+	}
+	return roleIDs, nil
+}
+
+func normalizeRoleIDs(primaryRoleID []byte, roleIDs [][]byte) [][]byte {
+	out := make([][]byte, 0, len(roleIDs)+1)
+	seen := make(map[string]struct{}, len(roleIDs)+1)
+
+	appendRole := func(roleID []byte) {
+		if len(roleID) != 16 {
+			return
+		}
+		key := string(roleID)
+		if _, exists := seen[key]; exists {
+			return
+		}
+		seen[key] = struct{}{}
+		out = append(out, append([]byte(nil), roleID...))
+	}
+
+	appendRole(primaryRoleID)
+	for i := range roleIDs {
+		appendRole(roleIDs[i])
+	}
+	return out
+}
+
+func containsRoleID(roleIDs [][]byte, roleID []byte) bool {
+	if len(roleID) != 16 {
+		return false
+	}
+	target := string(roleID)
+	for i := range roleIDs {
+		if string(roleIDs[i]) == target {
+			return true
+		}
+	}
+	return false
+}
+
+func buildUserRoleResource(u *user.User) (string, []string, dto.RoleMini, []dto.RoleMini) {
+	roleIDs := make([]string, 0, len(u.RoleIDs)+1)
+	roles := make([]dto.RoleMini, 0, len(u.Roles)+1)
+	seen := make(map[string]struct{}, len(u.RoleIDs)+1)
+
+	appendRole := func(roleID []byte, name, description string) {
+		if len(roleID) != 16 {
+			return
+		}
+		roleIDStr, _ := uuidv7.BytesToString(roleID)
+		if _, exists := seen[roleIDStr]; exists {
+			return
+		}
+		seen[roleIDStr] = struct{}{}
+		roleIDs = append(roleIDs, roleIDStr)
+		roles = append(roles, dto.RoleMini{
+			ID:          roleIDStr,
+			Name:        name,
+			Description: description,
+		})
+	}
+
+	for i := range u.Roles {
+		appendRole(u.Roles[i].ID, u.Roles[i].Name, u.Roles[i].Description)
+	}
+	appendRole(u.RoleID, u.RoleName, u.RoleDescription)
+	for i := range u.RoleIDs {
+		appendRole(u.RoleIDs[i], "", "")
+	}
+
+	primaryRole := dto.RoleMini{}
+	roleID := ""
+	if len(roles) > 0 {
+		primaryRole = roles[0]
+		roleID = primaryRole.ID
+	}
+
+	return roleID, roleIDs, primaryRole, roles
+}
diff --git a/internal/transport/http/handlers/user_handler_test.go b/internal/transport/http/handlers/user_handler_test.go
new file mode 100644
index 0000000..eb1e0fe
--- /dev/null
+++ b/internal/transport/http/handlers/user_handler_test.go
@@ -0,0 +1,856 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"github.com/valyala/fasthttp"
+
+	filemanager "wucher/internal/domain/file_manager"
+	"wucher/internal/domain/user"
+	filemanagerrealtime "wucher/internal/realtime/filemanager"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/userctx"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type memUserRepo struct {
+	users map[string]*user.User
+
+	createErr error
+	updateErr error
+	deleteErr error
+	getErr    error
+	listErr   error
+
+	listUsers []user.User
+	listTotal int64
+}
+
+func newMemUserRepo() *memUserRepo {
+	return &memUserRepo{users: map[string]*user.User{}}
+}
+
+func (r *memUserRepo) Create(_ context.Context, u *user.User) error {
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if len(u.ID) == 0 {
+		u.ID = uuidv7.MustBytes()
+	}
+	r.users[string(u.ID)] = u
+	return nil
+}
+
+func (r *memUserRepo) Update(_ context.Context, u *user.User) error {
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	r.users[string(u.ID)] = u
+	return nil
+}
+
+func (r *memUserRepo) Delete(_ context.Context, id []byte) error {
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	delete(r.users, string(id))
+	return nil
+}
+
+func (r *memUserRepo) GetByID(_ context.Context, id []byte) (*user.User, error) {
+	if r.getErr != nil {
+		return nil, r.getErr
+	}
+	return r.users[string(id)], nil
+}
+
+func (r *memUserRepo) GetByEmail(_ context.Context, _ string) (*user.User, error)    { return nil, nil }
+func (r *memUserRepo) GetByUsername(_ context.Context, _ string) (*user.User, error) { return nil, nil }
+
+func (r *memUserRepo) List(_ context.Context, _ string, _ string, _ int, _ int) ([]user.User, int64, error) {
+	if r.listErr != nil {
+		return nil, 0, r.listErr
+	}
+	return r.listUsers, r.listTotal, nil
+}
+
+func (r *memUserRepo) GetLastNameByID(_ context.Context, _ []byte) (string, error) {
+	return "", nil
+}
+
+func TestNewUserHandler(t *testing.T) {
+	h := NewUserHandler(service.NewUserService(newMemUserRepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+func TestUserHandler_Create(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		repo := newMemUserRepo()
+		svc := service.NewUserService(repo)
+		h := NewUserHandler(svc)
+		app := fiber.New()
+		actor := uuidv7.MustBytes()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", actor)
+			return c.Next()
+		})
+		app.Post("/api/v1/users/create", h.Create)
+
+		roleID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"user","attributes":{"email":"u@e.com","username":"john.doe","first_name":"John","last_name":"Doe","role_id":"` + roleID + `"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/users/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if !bytes.Contains(body, []byte(`"username":"john.doe"`)) {
+			t.Fatalf("expected response to include username, got %s", string(body))
+		}
+		if len(repo.users) != 1 {
+			t.Fatalf("expected 1 created user, got %d", len(repo.users))
+		}
+		for _, created := range repo.users {
+			if created.Username != "john.doe" {
+				t.Fatalf("expected username persisted, got %q", created.Username)
+			}
+			if created.Timezone != "UTC" {
+				t.Fatalf("expected default timezone UTC, got %q", created.Timezone)
+			}
+			if string(created.CreatedBy) != string(actor) {
+				t.Fatalf("expected created_by from actor")
+			}
+		}
+	})
+
+	t.Run("success with role_ids", func(t *testing.T) {
+		repo := newMemUserRepo()
+		svc := service.NewUserService(repo)
+		h := NewUserHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/users/create", h.Create)
+
+		roleID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		extraRoleID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"user","attributes":{"email":"roles@e.com","username":"roles.user","first_name":"Roles","last_name":"User","role_id":"` + roleID + `","role_ids":["` + roleID + `","` + extraRoleID + `"]}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/users/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		for _, created := range repo.users {
+			if len(created.RoleIDs) != 2 {
+				t.Fatalf("expected 2 role ids persisted, got %d", len(created.RoleIDs))
+			}
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemUserRepo()
+		svc := service.NewUserService(repo)
+		h := NewUserHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/users/create", h.Create)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/users/create", bytes.NewReader([]byte(`{"data":`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid role id", func(t *testing.T) {
+		repo := newMemUserRepo()
+		svc := service.NewUserService(repo)
+		h := NewUserHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/users/create", h.Create)
+		payload := []byte(`{"data":{"type":"user","attributes":{"email":"u@e.com","username":"john.doe","first_name":"John","last_name":"Doe","role_id":"bad"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/users/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid image_uuid requires file manager and returns bad request", func(t *testing.T) {
+		repo := newMemUserRepo()
+		svc := service.NewUserService(repo)
+		h := NewUserHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/users/create", h.Create)
+		roleID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"user","attributes":{"email":"u@e.com","username":"john.doe","first_name":"John","last_name":"Doe","role_id":"` + roleID + `","image_uuid":"bad"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/users/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("image_uuid requires file manager service", func(t *testing.T) {
+		repo := newMemUserRepo()
+		svc := service.NewUserService(repo)
+		h := NewUserHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/users/create", h.Create)
+		roleID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		fileUUID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"user","attributes":{"email":"u@e.com","username":"john.doe","first_name":"John","last_name":"Doe","role_id":"` + roleID + `","image_uuid":"` + fileUUID + `"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/users/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid role_ids", func(t *testing.T) {
+		repo := newMemUserRepo()
+		svc := service.NewUserService(repo)
+		h := NewUserHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/users/create", h.Create)
+		roleID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"user","attributes":{"email":"u@e.com","username":"john.doe","first_name":"John","last_name":"Doe","role_id":"` + roleID + `","role_ids":["bad"]}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/users/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid timezone", func(t *testing.T) {
+		repo := newMemUserRepo()
+		svc := service.NewUserService(repo)
+		h := NewUserHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/users/create", h.Create)
+		roleID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"user","attributes":{"email":"u@e.com","username":"john.doe","first_name":"John","last_name":"Doe","timezone":"UTC+7","role_id":"` + roleID + `"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/users/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create service error", func(t *testing.T) {
+		repo := newMemUserRepo()
+		repo.createErr = errors.New("db error")
+		svc := service.NewUserService(repo)
+		h := NewUserHandler(svc)
+		app := fiber.New()
+		app.Post("/api/v1/users/create", h.Create)
+		roleID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"user","attributes":{"email":"u@e.com","username":"john.doe","first_name":"John","last_name":"Doe","role_id":"` + roleID + `"}}}`)
+		req, _ := http.NewRequest(http.MethodPost, "/api/v1/users/create", bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestUserEventsStream(t *testing.T) {
+	hub := filemanagerrealtime.NewHub(1, nil)
+	actor := uuidv7.MustBytes()
+	userUUID, _ := uuidv7.BytesToString(actor)
+
+	app := fiber.New()
+	fctx := &fasthttp.RequestCtx{}
+	fctx.Request.SetRequestURI("/api/v1/users/events")
+	c := app.AcquireCtx(fctx)
+	c.Locals("user_id", actor)
+	if err := NewFileManagerEventsHandler(hub).Stream(c); err != nil {
+		t.Fatalf("unexpected stream setup error: %v", err)
+	}
+
+	hub.PublishToUsers([]string{userUUID}, filemanagerrealtime.FileStatusEvent{
+		FileUUID:  mustUUIDStringBase(t, uuidv7.MustBytes()),
+		Status:    "ready",
+		Name:      "avatar.png",
+		MimeType:  "image/png",
+		UpdatedAt: time.Now().UTC().Format(time.RFC3339),
+	})
+	go func() {
+		time.Sleep(10 * time.Millisecond)
+		closeFirstHubSubscriberForUser(hub, userUUID)
+	}()
+
+	bodyStr := c.Context().Response.String()
+	app.ReleaseCtx(c)
+	if !strings.Contains(bodyStr, ": connected") {
+		t.Fatalf("expected connected comment in body: %q", bodyStr)
+	}
+	if !strings.Contains(bodyStr, "event: file.updated") {
+		t.Fatalf("expected file.updated event in body: %q", bodyStr)
+	}
+	if !strings.Contains(bodyStr, "\"file_id\"") || !strings.Contains(bodyStr, "\"status\":\"ready\"") {
+		t.Fatalf("expected file.updated payload in body: %q", bodyStr)
+	}
+}
+
+func TestUserHandler_Update(t *testing.T) {
+	repo := newMemUserRepo()
+	userID := uuidv7.MustBytes()
+	roleID := uuidv7.MustBytes()
+	repo.users[string(userID)] = &user.User{ID: userID, Email: "u@e.com", FirstName: "John", LastName: "Doe", RoleID: roleID}
+
+	svc := service.NewUserService(repo)
+	h := NewUserHandler(svc)
+	app := fiber.New()
+	app.Patch("/api/v1/users/update/:uuid", h.Update)
+
+	t.Run("success", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"first_name":"Jane"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("empty image_uuid clears existing attachment", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		imageID := uuidv7.MustBytes()
+		repo.users[string(userID)].ProfileAttachmentID = append([]byte(nil), imageID...)
+
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"first_name":"Jane","image_uuid":""}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.users[string(userID)].ProfileAttachmentID != nil {
+			t.Fatalf("expected profile attachment to be cleared")
+		}
+	})
+
+	t.Run("null image_uuid clears existing attachment", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		imageID := uuidv7.MustBytes()
+		repo.users[string(userID)].ProfileAttachmentID = append([]byte(nil), imageID...)
+
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"first_name":"Jane","image_uuid":null}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.users[string(userID)].ProfileAttachmentID != nil {
+			t.Fatalf("expected profile attachment to be cleared on null image_uuid")
+		}
+	})
+
+	t.Run("invalid id", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/not-uuid", bytes.NewReader([]byte(`{}`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader([]byte(`{"data":`)))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		other, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"user","id":"` + other + `","attributes":{"first_name":"Jane"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		payload := []byte(`{"data":{"type":"user","id":"","attributes":{"first_name":"Jane"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no attrs", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid image_uuid requires file manager and returns bad request", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"image_uuid":"bad"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("image_uuid requires file manager service", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		fileUUID, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"image_uuid":"` + fileUUID + `"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("image_uuid accepts existing attachment id", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		attachmentID := uuidv7.MustBytes()
+		attachmentIDStr, _ := uuidv7.BytesToString(attachmentID)
+		h.WithFileManagerService(&fileManagerAttachmentHandlerServiceMock{
+			getAttachmentFn: func(_ context.Context, id []byte) (*filemanager.Attachment, error) {
+				if string(id) == string(attachmentID) {
+					return &filemanager.Attachment{ID: attachmentID, FileID: uuidv7.MustBytes()}, nil
+				}
+				return nil, nil
+			},
+		})
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"image_uuid":"` + attachmentIDStr + `"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(repo.users[string(userID)].ProfileAttachmentID) != string(attachmentID) {
+			t.Fatalf("expected profile_attachment_id updated with attachment id")
+		}
+	})
+
+	t.Run("image_uuid file uuid replaces existing profile attachment", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		oldAttachmentID := uuidv7.MustBytes()
+		newAttachmentID := uuidv7.MustBytes()
+		newFileID := uuidv7.MustBytes()
+		newFileIDStr, _ := uuidv7.BytesToString(newFileID)
+		repo.users[string(userID)].ProfileAttachmentID = append([]byte(nil), oldAttachmentID...)
+
+		h.WithFileManagerService(&fileManagerAttachmentHandlerServiceMock{
+			getAttachmentFn: func(_ context.Context, id []byte) (*filemanager.Attachment, error) {
+				// Incoming image_uuid is file UUID, not attachment UUID.
+				if string(id) == string(newFileID) {
+					return nil, nil
+				}
+				return nil, nil
+			},
+			listAttachmentsFn: func(_ context.Context, _ filemanager.ListAttachmentsParams) ([]filemanager.Attachment, int64, error) {
+				return []filemanager.Attachment{{ID: oldAttachmentID, FileID: uuidv7.MustBytes()}}, 1, nil
+			},
+			deleteAttachmentFn: func(_ context.Context, id []byte) error {
+				if string(id) != string(oldAttachmentID) {
+					t.Fatalf("unexpected deleted attachment id")
+				}
+				return nil
+			},
+			createAttachmentFn: func(_ context.Context, p filemanager.CreateAttachmentParams) (*filemanager.Attachment, error) {
+				if string(p.FileID) != string(newFileID) {
+					t.Fatalf("expected create attachment from new file id")
+				}
+				return &filemanager.Attachment{ID: newAttachmentID, FileID: newFileID}, nil
+			},
+		})
+
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"image_uuid":"` + newFileIDStr + `"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			body, _ := io.ReadAll(resp.Body)
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(body))
+		}
+		if string(repo.users[string(userID)].ProfileAttachmentID) != string(newAttachmentID) {
+			t.Fatalf("expected profile_attachment_id replaced with new attachment id")
+		}
+	})
+
+	t.Run("email empty", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"email":" "}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("first_name empty", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"first_name":" "}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("last_name empty", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"last_name":" "}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		repo.updateErr = errors.New("db error")
+		idStr, _ := uuidv7.BytesToString(userID)
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"first_name":"X"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+		repo.updateErr = nil
+	})
+
+	t.Run("invalid timezone", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"timezone":"UTC+7"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update timezone success", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"timezone":"Asia/Jakarta"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if got := repo.users[string(userID)].Timezone; got != "Asia/Jakarta" {
+			t.Fatalf("expected timezone updated, got %q", got)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		payload := []byte(`{"data":{"type":"user","id":"` + idStr + `","attributes":{"first_name":"Jane"}}}`)
+		req, _ := http.NewRequest(http.MethodPatch, "/api/v1/users/update/"+idStr, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestUserHandler_DeleteGetListDatatable(t *testing.T) {
+	repo := newMemUserRepo()
+	roleID := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+	repo.users[string(userID)] = &user.User{ID: userID, Email: "u@e.com", FirstName: "John", LastName: "Doe", RoleID: roleID}
+	repo.listUsers = []user.User{{ID: userID, Email: "u@e.com", FirstName: "John", LastName: "Doe", RoleID: roleID}}
+	repo.listTotal = 1
+
+	svc := service.NewUserService(repo)
+	h := NewUserHandler(svc)
+	app := fiber.New()
+	app.Delete("/api/v1/users/delete/:uuid", h.Delete)
+	app.Get("/api/v1/users/get/:uuid", h.Get)
+	app.Get("/api/v1/users/get-all", h.List)
+	app.Get("/api/v1/users/get-all/dt", h.ListDatatable)
+
+	t.Run("delete invalid id", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/users/delete/not-uuid", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete success", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(userID)
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/users/delete/"+idStr, nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete service error", func(t *testing.T) {
+		failingID := uuidv7.MustBytes()
+		repo.users[string(failingID)] = &user.User{ID: failingID, Email: "fail@e.com", RoleID: roleID}
+		repo.deleteErr = errors.New("delete failed")
+		defer func() { repo.deleteErr = nil }()
+
+		idStr, _ := uuidv7.BytesToString(failingID)
+		req, _ := http.NewRequest(http.MethodDelete, "/api/v1/users/delete/"+idStr, nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("get not found", func(t *testing.T) {
+		idStr, _ := uuidv7.BytesToString(uuidv7.MustBytes())
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/users/get/"+idStr, nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("get success", func(t *testing.T) {
+		id := uuidv7.MustBytes()
+		repo.users[string(id)] = &user.User{ID: id, Email: "a@b.com", FirstName: "A", LastName: "B", RoleID: roleID}
+		idStr, _ := uuidv7.BytesToString(id)
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/users/get/"+idStr, nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("list success", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/users/get-all?page[number]=1&page[size]=10&filter[search]=u", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("list error", func(t *testing.T) {
+		repo.listErr = errors.New("db error")
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/users/get-all", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+		repo.listErr = nil
+	})
+
+	t.Run("datatable success", func(t *testing.T) {
+		req, _ := http.NewRequest(http.MethodGet, "/api/v1/users/get-all/dt?page=1&size=10&search=u", nil)
+		resp, _ := app.Test(req)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestUserResource(t *testing.T) {
+	now := time.Now()
+	primaryRoleID := uuidv7.MustBytes()
+	extraRoleID := uuidv7.MustBytes()
+	u := &user.User{
+		ID:                  uuidv7.MustBytes(),
+		Email:               "u@e.com",
+		FirstName:           "John",
+		LastName:            "Doe",
+		MobilePhone:         "08123",
+		ProfileAttachmentID: uuidv7.MustBytes(),
+		RoleID:              primaryRoleID,
+		RoleName:            "staff",
+		RoleDescription:     "Staff role",
+		RoleIDs:             [][]byte{primaryRoleID, extraRoleID},
+		Roles: []user.RoleSummary{
+			{ID: primaryRoleID, Name: "staff", Description: "Staff role"},
+			{ID: extraRoleID, Name: "chief_pilot", Description: "Chief Pilot role"},
+		},
+		CreatedBy:       uuidv7.MustBytes(),
+		EmailVerifiedAt: &now,
+	}
+	h := NewUserHandler(service.NewUserService(newMemUserRepo()))
+	r := h.userResource(context.Background(), u)
+	if r.Type != "user" || r.Attributes.Role.Name != "staff" || r.Attributes.EmailVerifiedAt == "" {
+		t.Fatalf("unexpected user resource: %#v", r)
+	}
+	if len(r.Attributes.RoleIDs) == 0 || len(r.Attributes.Roles) == 0 {
+		t.Fatalf("expected role_ids and roles in response: %#v", r.Attributes)
+	}
+	if r.Attributes.Timezone != "UTC" {
+		t.Fatalf("expected default timezone UTC, got %q", r.Attributes.Timezone)
+	}
+	if r.Attributes.CreatedBy == "" {
+		t.Fatalf("expected created_by in response")
+	}
+	if r.Attributes.ProfilePicture == nil || r.Attributes.ProfilePicture.UUID == "" {
+		t.Fatalf("expected profile_picture in response")
+	}
+}
+
+type staticUserNameGetter struct {
+	lastName string
+}
+
+func (g staticUserNameGetter) GetLastName(context.Context, []byte) (string, error) {
+	return g.lastName, nil
+}
+
+func TestUserHandler_HelperBranches(t *testing.T) {
+	t.Run("with setters return same handler", func(t *testing.T) {
+		h := NewUserHandler(service.NewUserService(newMemUserRepo()))
+		if h.WithFileManagerService(nil) != h {
+			t.Fatalf("expected WithFileManagerService to return same handler")
+		}
+		if h.WithFileStorage(nil) != h {
+			t.Fatalf("expected WithFileStorage to return same handler")
+		}
+	})
+
+	t.Run("resolve profile image with nil file uuid is ignored", func(t *testing.T) {
+		h := NewUserHandler(service.NewUserService(newMemUserRepo()))
+		app := fiber.New()
+		app.Get("/", func(c *fiber.Ctx) error {
+			got, handled := h.resolveProfileImageAttachmentID(c, uuidv7.MustBytes(), nil)
+			if handled {
+				t.Fatalf("expected nil file uuid to be ignored")
+			}
+			if got != nil {
+				t.Fatalf("expected nil attachment id")
+			}
+			return c.SendStatus(fiber.StatusOK)
+		})
+		req, _ := http.NewRequest(http.MethodGet, "/", nil)
+		if _, err := app.Test(req); err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+	})
+
+	t.Run("parse optional image_uuid from raw body", func(t *testing.T) {
+		state := parseOptionalStringFieldFromJSONBody([]byte(`{"data":{"attributes":{"image_uuid":null}}}`), "image_uuid")
+		if !state.Set || state.Valid {
+			t.Fatalf("expected image_uuid null to be set+invalid, got %+v", state)
+		}
+
+		state = parseOptionalStringFieldFromJSONBody([]byte(`{"data":{"attributes":{"image_uuid":"abc"}}}`), "image_uuid")
+		if !state.Set || !state.Valid || state.Value != "abc" {
+			t.Fatalf("expected image_uuid string to be set+valid, got %+v", state)
+		}
+
+		state = parseOptionalStringFieldFromJSONBody([]byte(`{"data":{"attributes":{"other":"x"}}}`), "image_uuid")
+		if state.Set {
+			t.Fatalf("expected image_uuid absent to be unset, got %+v", state)
+		}
+	})
+
+	t.Run("contains role id matches only valid uuid bytes", func(t *testing.T) {
+		roleID := uuidv7.MustBytes()
+		if !containsRoleID([][]byte{roleID}, roleID) {
+			t.Fatalf("expected containsRoleID to match")
+		}
+		if containsRoleID([][]byte{roleID}, []byte("short")) {
+			t.Fatalf("expected invalid role id bytes to fail")
+		}
+		if containsRoleID([][]byte{roleID}, uuidv7.MustBytes()) {
+			t.Fatalf("expected non-member role id to fail")
+		}
+	})
+
+	t.Run("wire user name getter forwards to userctx", func(t *testing.T) {
+		prev := userctx.GlobalUserNameGetter
+		defer func() { userctx.GlobalUserNameGetter = prev }()
+
+		getter := staticUserNameGetter{lastName: "Doe"}
+		WireUserNameGetter(getter)
+		if userctx.GlobalUserNameGetter == nil {
+			t.Fatalf("expected global getter configured")
+		}
+		got, err := userctx.GlobalUserNameGetter.GetLastName(context.Background(), uuidv7.MustBytes())
+		if err != nil {
+			t.Fatalf("GetLastName: %v", err)
+		}
+		if got != "Doe" {
+			t.Fatalf("expected wired getter result, got %q", got)
+		}
+	})
+
+	t.Run("profile picture download url resolves when storage exists", func(t *testing.T) {
+		fileID := uuidv7.MustBytes()
+		attachmentID := uuidv7.MustBytes()
+		thumbnailKey := "avatars/avatar.thumb.png"
+		u := &user.User{
+			ID:                  uuidv7.MustBytes(),
+			Email:               "u@e.com",
+			FirstName:           "John",
+			LastName:            "Doe",
+			ProfileAttachmentID: attachmentID,
+			ProfileAttachment: &filemanager.Attachment{
+				ID: attachmentID,
+				File: &filemanager.File{
+					ID:                 fileID,
+					Name:               "avatar.png",
+					ObjectKey:          "avatars/avatar.png",
+					ThumbnailObjectKey: &thumbnailKey,
+					SizeBytes:          123,
+				},
+			},
+		}
+		h := NewUserHandler(service.NewUserService(newMemUserRepo())).WithFileStorage(&fileManagerDownloadURLStorageMock{presignedURL: "https://signed/avatar.png"})
+		res := h.userResource(context.Background(), u)
+		if res.Attributes.ProfilePicture == nil || res.Attributes.ProfilePicture.DownloadURL != "https://signed/avatar.png" {
+			t.Fatalf("expected signed profile picture download url, got %#v", res.Attributes.ProfilePicture)
+		}
+		if res.Attributes.ProfilePicture.ThumbnailDownloadURL != "https://signed/avatar.png" {
+			t.Fatalf("expected signed profile picture thumbnail url, got %#v", res.Attributes.ProfilePicture)
+		}
+		if res.Attributes.ProfilePicture.OriginalSizeBytes == nil || *res.Attributes.ProfilePicture.OriginalSizeBytes != 123 {
+			t.Fatalf("expected original size bytes 123, got %#v", res.Attributes.ProfilePicture)
+		}
+	})
+}
diff --git a/internal/transport/http/handlers/vocation_handler.go b/internal/transport/http/handlers/vocation_handler.go
new file mode 100644
index 0000000..891fa28
--- /dev/null
+++ b/internal/transport/http/handlers/vocation_handler.go
@@ -0,0 +1,452 @@
+package handlers
+
+import (
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+	"gorm.io/gorm"
+
+	"wucher/internal/domain/vocation"
+	"wucher/internal/shared/pkg/apperrors"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+	"wucher/internal/transport/http/dto"
+	"wucher/internal/transport/http/jsonapi"
+	"wucher/internal/transport/http/response"
+	"wucher/internal/transport/http/validators"
+)
+
+type VocationHandler struct {
+	svc      vocation.Service
+	validate *validators.Validator
+}
+
+func NewVocationHandler(svc vocation.Service) *VocationHandler {
+	return &VocationHandler{
+		svc:      svc,
+		validate: validators.New(),
+	}
+}
+
+// CreateVocation godoc
+// @Summary Create vocation
+// @Description Create a vocation row.
+// @Tags OPC - Vocation
+// @Accept json
+// @Produce json
+// @Param request body dto.VocationCreateRequest true "JSON:API vocation create request"
+// @Success 201 {object} dto.VocationResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Router /api/v1/vocation/create [post]
+func (h *VocationHandler) Create(c *fiber.Ctx) error {
+	var req dto.VocationCreateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeVocationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeVocationErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	name := strings.TrimSpace(req.Data.Attributes.Name)
+	if name == "" {
+		return writeVocationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "name is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+		}})
+	}
+
+	row := &vocation.Vocation{
+		Name:      name,
+		SortKey:   cloneIntPointer(req.Data.Attributes.SortKey),
+		Note:      strings.TrimSpace(stringOrDefault(req.Data.Attributes.Note, "")),
+		IsActive:  boolOrDefault(req.Data.Attributes.IsActive, true),
+		CreatedBy: actorUserID(c),
+		UpdatedBy: actorUserID(c),
+	}
+
+	if err := h.svc.Create(c.UserContext(), row); err != nil {
+		return writeVocationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Create failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	created, err := h.svc.GetByID(c.UserContext(), row.ID)
+	if err == nil && created != nil {
+		return response.Write(c, fiber.StatusCreated, vocationResource(created))
+	}
+	return response.Write(c, fiber.StatusCreated, vocationResource(row))
+}
+
+// UpdateVocation godoc
+// @Summary Update vocation (partial)
+// @Description Patch vocation by ID.
+// @Tags OPC - Vocation
+// @Accept json
+// @Produce json
+// @Param uuid path string true "Vocation UUID (UUIDv7)"
+// @Param request body dto.VocationUpdateRequest true "JSON:API vocation update request"
+// @Success 200 {object} dto.VocationResponse
+// @Failure 422 {object} dto.ErrorResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/vocation/update/{uuid} [patch]
+func (h *VocationHandler) Update(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeVocationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	var req dto.VocationUpdateRequest
+	if err := c.BodyParser(&req); err != nil {
+		return writeVocationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid JSON",
+			Detail: safeInternalDetail(),
+		}})
+	}
+	if errs := h.validate.ValidateStruct(req); errs != nil {
+		return writeVocationErrors(c, fiber.StatusUnprocessableEntity, errs)
+	}
+
+	if strings.TrimSpace(req.Data.ID) == "" {
+		return writeVocationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id is required",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+	if req.Data.ID != uuidStr {
+		return writeVocationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "id does not match path uuid",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/id"},
+		}})
+	}
+
+	attrs := req.Data.Attributes
+	if attrs.Name == nil && !attrs.SortKey.Set && attrs.Note == nil && attrs.IsActive == nil {
+		return writeVocationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "at least one attribute must be provided",
+			Source: &jsonapi.ErrorSource{Pointer: "/data/attributes"},
+		}})
+	}
+
+	existing, err := h.svc.GetByID(c.UserContext(), id)
+	if err != nil || existing == nil {
+		return writeVocationErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{
+			Status: "404",
+			Title:  "Not found",
+			Detail: "vocation not found",
+		}})
+	}
+
+	if attrs.Name != nil {
+		v := strings.TrimSpace(*attrs.Name)
+		if v == "" {
+			return writeVocationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+				Status: "422",
+				Title:  "Validation error",
+				Detail: "name cannot be empty",
+				Source: &jsonapi.ErrorSource{Pointer: "/data/attributes/name"},
+			}})
+		}
+		existing.Name = v
+	}
+	if attrs.SortKey.Set {
+		if attrs.SortKey.Valid {
+			sortKey := attrs.SortKey.Value
+			existing.SortKey = &sortKey
+		} else {
+			existing.SortKey = nil
+		}
+	}
+	if attrs.Note != nil {
+		existing.Note = strings.TrimSpace(*attrs.Note)
+	}
+	if attrs.IsActive != nil {
+		existing.IsActive = *attrs.IsActive
+	}
+	existing.UpdatedBy = actorUserID(c)
+
+	if err := h.svc.Update(c.UserContext(), existing); err != nil {
+		return writeVocationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Update failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	updated, err := h.svc.GetByID(c.UserContext(), existing.ID)
+	if err == nil && updated != nil {
+		return response.Write(c, fiber.StatusOK, vocationResource(updated))
+	}
+	return response.Write(c, fiber.StatusOK, vocationResource(existing))
+}
+
+// DeleteVocation godoc
+// @Summary Delete vocation
+// @Tags OPC - Vocation
+// @Produce json
+// @Param uuid path string true "Vocation UUID (UUIDv7)"
+// @Success 200 {object} dto.GenericDeleteResponse
+// @Failure 404 {object} dto.ErrorResponse
+// @Router /api/v1/vocation/delete/{uuid} [delete]
+func (h *VocationHandler) Delete(c *fiber.Ctx) error {
+	uuidStr := c.Params("uuid")
+	id, err := uuidv7.ParseString(uuidStr)
+	if err != nil {
+		return writeVocationErrors(c, fiber.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "uuid is invalid UUID",
+			Source: &jsonapi.ErrorSource{Pointer: "/path/uuid"},
+		}})
+	}
+
+	if err := h.svc.Delete(c.UserContext(), id, actorUserID(c)); err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return writeVocationErrors(c, fiber.StatusNotFound, []jsonapi.ErrorObject{{Status: "404", Title: "Not found", Detail: "vocation not found"}})
+		}
+		if _, ok := apperrors.AsDeleteConflict(err); ok {
+			return writeVocationErrors(c, fiber.StatusConflict, []jsonapi.ErrorObject{{Status: "409", Title: "Conflict", Detail: safeInternalDetail()}})
+		}
+		return writeVocationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{Status: "400", Title: "Delete failed", Detail: safeInternalDetail()}})
+	}
+
+	return response.Write(c, fiber.StatusOK, jsonapi.Resource{
+		Type: "vocation_delete",
+		Attributes: map[string]any{
+			"deleted": true,
+		},
+	})
+}
+
+// ListVocation godoc
+// @Summary List vocation
+// @Description JSON:API list with pagination, filtering and sorting. Sort values: name, -name, sortkey, -sortkey, note, -note, is_active, -is_active, created_at, -created_at, updated_at, -updated_at.
+// @Tags OPC - Vocation
+// @Produce json
+// @Param filter[search] query string false "Search by name/note"
+// @Param page[number] query int false "Page number (default 1)"
+// @Param page[size] query int false "Page size (default 20, max 100)"
+// @Param sort query string false "Sort order"
+// @Success 200 {object} dto.VocationListResponse
+// @Router /api/v1/vocation/get-all [get]
+func (h *VocationHandler) List(c *fiber.Ctx) error {
+	filter := c.Query("filter[search]")
+	if filter == "" {
+		filter = c.Query("filter[name]")
+	}
+	if filter == "" {
+		filter = c.Query("search")
+	}
+
+	pageNumber := parseIntDefault(c.Query("page[number]"), 0)
+	if pageNumber <= 0 {
+		pageNumber = parseIntDefault(c.Query("page"), 1)
+	}
+
+	pageSize := parseIntDefault(c.Query("page[size]"), 0)
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("limit"), 0)
+	}
+	if pageSize <= 0 {
+		pageSize = parseIntDefault(c.Query("size"), 20)
+	}
+	if pageSize > 100 {
+		pageSize = 100
+	}
+	if pageSize < 1 {
+		pageSize = 20
+	}
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+
+	offset := (pageNumber - 1) * pageSize
+	_ = offset
+	sort := c.Query("sort")
+
+	rows, total, err := h.svc.List(c.UserContext(), filter, sort, 0, 0)
+	if err != nil {
+		return writeVocationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.VocationResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, vocationResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"page_number": pageNumber,
+		"page_size":   pageSize,
+		"total":       total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+// ListVocationDatatable godoc
+// @Summary List vocation (datatable)
+// @Description Datatable response with simple pagination params.
+// @Tags OPC - Vocation
+// @Produce json
+// @Param page query int false "Page number (default 1)"
+// @Param size query int false "Page size (default 20, max 100)"
+// @Param limit query int false "Page size override (same as size)"
+// @Param draw query int false "Draw counter (optional)"
+// @Param search query string false "Search term"
+// @Success 200 {object} dto.VocationDataTableResponse
+// @Router /api/v1/vocation/get-all/dt [get]
+func (h *VocationHandler) ListDatatable(c *fiber.Ctx) error {
+	pageNumber := parseIntDefault(c.Query("page"), 1)
+	if pageNumber < 1 {
+		pageNumber = 1
+	}
+	length := parseIntDefault(c.Query("limit"), 0)
+	if length <= 0 {
+		length = parseIntDefault(c.Query("size"), 20)
+	}
+	if length > 100 {
+		length = 100
+	}
+	if length < 1 {
+		length = 20
+	}
+	start := (pageNumber - 1) * length
+	draw := parseIntDefault(c.Query("draw"), pageNumber)
+	search := c.Query("search")
+
+	rows, total, err := h.svc.List(c.UserContext(), search, "", length, start)
+	if err != nil {
+		return writeVocationErrors(c, fiber.StatusBadRequest, []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "List failed",
+			Detail: safeInternalDetail(),
+		}})
+	}
+
+	data := make([]dto.VocationResource, 0, len(rows))
+	for i := range rows {
+		data = append(data, vocationResource(&rows[i]))
+	}
+
+	meta := map[string]any{
+		"draw":             draw,
+		"records_total":    total,
+		"records_filtered": total,
+	}
+
+	return response.WriteWithMeta(c, fiber.StatusOK, data, meta)
+}
+
+func vocationResource(v *vocation.Vocation) dto.VocationResource {
+	return dto.VocationResource{
+		Type: "vocation",
+		ID:   idString(v.ID),
+		Attributes: dto.VocationAttributes{
+			Name:      v.Name,
+			SortKey:   cloneIntPointer(v.SortKey),
+			Note:      v.Note,
+			IsActive:  v.IsActive,
+			CreatedAt: v.CreatedAt.UTC().Format(time.RFC3339),
+			CreatedBy: uuidStringOrEmpty(v.CreatedBy),
+			UpdatedAt: v.UpdatedAt.UTC().Format(time.RFC3339),
+			UpdatedBy: uuidStringOrEmpty(v.UpdatedBy),
+			DeletedAt: timeStringOrEmpty(v.DeletedAt),
+			DeletedBy: uuidStringOrEmpty(v.DeletedBy),
+		},
+	}
+}
+
+func writeVocationErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	enriched := make([]jsonapi.ErrorObject, 0, len(errs))
+	statusStr := strconv.Itoa(status)
+	for i := range errs {
+		e := errs[i]
+		e.Status = statusStr
+		def := inferVocationDef(status, e.Title, e.Detail)
+		if strings.TrimSpace(e.Code) == "" {
+			e.Code = def.Code
+		}
+		if strings.TrimSpace(e.ErrorCode) == "" {
+			e.ErrorCode = def.ErrorCode
+		}
+		e.Detail = def.Message
+		enriched = append(enriched, e)
+	}
+	return response.WriteErrors(c, status, enriched)
+}
+
+func inferVocationErrorCode(status int, title, detail string) (string, string) {
+	def := inferVocationDef(status, title, detail)
+	return def.Code, def.ErrorCode
+}
+
+func inferVocationDef(status int, title, detail string) apperrorsx.Def {
+	lowerTitle := strings.ToLower(strings.TrimSpace(title))
+	lowerDetail := strings.ToLower(strings.TrimSpace(detail))
+	switch status {
+	case fiber.StatusNotFound:
+		return apperrorsx.ErrVocationNotFound
+	case fiber.StatusConflict:
+		return apperrorsx.ErrVocationRelationDelete
+	case fiber.StatusUnprocessableEntity:
+		switch {
+		case strings.Contains(lowerDetail, "uuid is invalid"):
+			return apperrorsx.ErrVocationInvalidUUID
+		case strings.Contains(lowerDetail, "id is required"):
+			return apperrorsx.ErrVocationIDRequired
+		case strings.Contains(lowerDetail, "id does not match"):
+			return apperrorsx.ErrVocationIDMismatch
+		case strings.Contains(lowerDetail, "at least one attribute"):
+			return apperrorsx.ErrVocationAttributesRequired
+		case strings.Contains(lowerDetail, "name is required"), strings.Contains(lowerDetail, "name cannot be empty"):
+			return apperrorsx.ErrVocationNameRequired
+		default:
+			return apperrorsx.ErrVocationInvalidPayload
+		}
+	case fiber.StatusBadRequest:
+		switch {
+		case strings.Contains(lowerTitle, "invalid json"):
+			return apperrorsx.ErrVocationInvalidJSON
+		case strings.Contains(lowerTitle, "create failed"):
+			return apperrorsx.ErrVocationCreateFailed
+		case strings.Contains(lowerTitle, "update failed"):
+			return apperrorsx.ErrVocationUpdateFailed
+		case strings.Contains(lowerTitle, "delete failed"):
+			return apperrorsx.ErrVocationDeleteFailed
+		case strings.Contains(lowerTitle, "list failed"):
+			return apperrorsx.ErrVocationListFailed
+		default:
+			return apperrorsx.ErrVocationInvalidPayload
+		}
+	default:
+		return apperrorsx.ErrInternal
+	}
+}
diff --git a/internal/transport/http/handlers/vocation_handler_test.go b/internal/transport/http/handlers/vocation_handler_test.go
new file mode 100644
index 0000000..4c92873
--- /dev/null
+++ b/internal/transport/http/handlers/vocation_handler_test.go
@@ -0,0 +1,576 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/domain/vocation"
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type memVocationRepo struct {
+	rows map[string]*vocation.Vocation
+
+	createErr  error
+	updateErr  error
+	deleteErr  error
+	getByIDErr error
+	listErr    error
+
+	listRows  []vocation.Vocation
+	listTotal int64
+
+	getByIDFn func(id []byte, call int) (*vocation.Vocation, error)
+	getCalls  int
+
+	lastCreate     *vocation.Vocation
+	lastUpdate     *vocation.Vocation
+	lastDeleteID   []byte
+	lastDeleteBy   []byte
+	lastListFilter string
+	lastListSort   string
+	lastListLimit  int
+	lastListOffset int
+}
+
+func newMemVocationRepo() *memVocationRepo {
+	return &memVocationRepo{
+		rows: map[string]*vocation.Vocation{},
+	}
+}
+
+func (r *memVocationRepo) Create(_ context.Context, row *vocation.Vocation) error {
+	if r.createErr != nil {
+		return r.createErr
+	}
+	if len(row.ID) == 0 {
+		row.ID = uuidv7.MustBytes()
+	}
+	r.rows[string(row.ID)] = row
+	r.lastCreate = row
+	return nil
+}
+
+func (r *memVocationRepo) Update(_ context.Context, row *vocation.Vocation) error {
+	if r.updateErr != nil {
+		return r.updateErr
+	}
+	r.rows[string(row.ID)] = row
+	r.lastUpdate = row
+	return nil
+}
+
+func (r *memVocationRepo) Delete(_ context.Context, id []byte, deletedBy []byte) error {
+	if r.deleteErr != nil {
+		return r.deleteErr
+	}
+	r.lastDeleteID = append([]byte(nil), id...)
+	r.lastDeleteBy = append([]byte(nil), deletedBy...)
+	delete(r.rows, string(id))
+	return nil
+}
+
+func (r *memVocationRepo) GetByID(_ context.Context, id []byte) (*vocation.Vocation, error) {
+	r.getCalls++
+	if r.getByIDFn != nil {
+		return r.getByIDFn(id, r.getCalls)
+	}
+	if r.getByIDErr != nil {
+		return nil, r.getByIDErr
+	}
+	return r.rows[string(id)], nil
+}
+
+func (r *memVocationRepo) List(_ context.Context, filter, sort string, limit, offset int) ([]vocation.Vocation, int64, error) {
+	r.lastListFilter = filter
+	r.lastListSort = sort
+	r.lastListLimit = limit
+	r.lastListOffset = offset
+	if r.listErr != nil {
+		return nil, 0, r.listErr
+	}
+	return r.listRows, r.listTotal, nil
+}
+
+func newVocationTestApp(h *VocationHandler, actor []byte) *fiber.App {
+	app := fiber.New()
+	app.Use(func(c *fiber.Ctx) error {
+		if len(actor) > 0 {
+			c.Locals("user_id", actor)
+		}
+		return c.Next()
+	})
+	app.Post("/api/v1/vocation/create", h.Create)
+	app.Patch("/api/v1/vocation/update/:uuid", h.Update)
+	app.Delete("/api/v1/vocation/delete/:uuid", h.Delete)
+	app.Get("/api/v1/vocation/get-all", h.List)
+	app.Get("/api/v1/vocation/get-all/dt", h.ListDatatable)
+	return app
+}
+
+func doJSONRequestVocation(t *testing.T, app *fiber.App, method, path string, body []byte) (*http.Response, []byte) {
+	t.Helper()
+	req, err := http.NewRequest(method, path, bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("new request: %v", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	return resp, respBody
+}
+
+func mustUUIDStringVocation(t *testing.T, id []byte) string {
+	t.Helper()
+	s, err := uuidv7.BytesToString(id)
+	if err != nil {
+		t.Fatalf("uuid to string: %v", err)
+	}
+	return s
+}
+
+func TestNewVocationHandler(t *testing.T) {
+	h := NewVocationHandler(service.NewVocationService(newMemVocationRepo()))
+	if h == nil || h.validate == nil {
+		t.Fatalf("expected handler and validator initialized")
+	}
+}
+
+func TestVocationHandlerCreate(t *testing.T) {
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPost, "/api/v1/vocation/create", []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPost, "/api/v1/vocation/create", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"vocation","attributes":{"name":"  "}}}`)
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPost, "/api/v1/vocation/create", body)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("create error", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		repo.createErr = errors.New("create failed")
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"vocation","attributes":{"name":"Main"}}}`)
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPost, "/api/v1/vocation/create", body)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		actor := uuidv7.MustBytes()
+		app := newVocationTestApp(h, actor)
+
+		body := []byte(`{"data":{"type":"vocation","attributes":{"name":"Main","sortkey":3,"note":"Center","is_active":false}}}`)
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPost, "/api/v1/vocation/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+		if repo.lastCreate == nil {
+			t.Fatalf("expected row created")
+		}
+		if repo.lastCreate.SortKey == nil || *repo.lastCreate.SortKey != 3 {
+			t.Fatalf("expected sortkey mapped on create")
+		}
+		if repo.lastCreate.Note != "Center" || repo.lastCreate.IsActive {
+			t.Fatalf("expected note/description/is_active mapped on create independently")
+		}
+		if string(repo.lastCreate.CreatedBy) != string(actor) || string(repo.lastCreate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected created_by and updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback when refetch error", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		repo.getByIDFn = func(_ []byte, call int) (*vocation.Vocation, error) {
+			if call > 0 {
+				return nil, errors.New("lookup failed")
+			}
+			return nil, nil
+		}
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		body := []byte(`{"data":{"type":"vocation","attributes":{"name":"Main"}}}`)
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPost, "/api/v1/vocation/create", body)
+		if resp.StatusCode != http.StatusCreated {
+			t.Fatalf("expected 201, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestVocationHandlerUpdate(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPatch, "/api/v1/vocation/update/not-uuid", []byte(`{}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid json", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+		id := mustUUIDStringVocation(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPatch, "/api/v1/vocation/update/"+id, []byte(`{"data":`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("validation error", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+		id := mustUUIDStringVocation(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPatch, "/api/v1/vocation/update/"+id, []byte(`{"data":{"type":"x","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id required", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+		id := mustUUIDStringVocation(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPatch, "/api/v1/vocation/update/"+id, []byte(`{"data":{"type":"vocation","id":"","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("id mismatch", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+		id := mustUUIDStringVocation(t, uuidv7.MustBytes())
+		other := mustUUIDStringVocation(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPatch, "/api/v1/vocation/update/"+id, []byte(`{"data":{"type":"vocation","id":"`+other+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("no attributes", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+		id := mustUUIDStringVocation(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPatch, "/api/v1/vocation/update/"+id, []byte(`{"data":{"type":"vocation","id":"`+id+`","attributes":{}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("not found", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+		id := mustUUIDStringVocation(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPatch, "/api/v1/vocation/update/"+id, []byte(`{"data":{"type":"vocation","id":"`+id+`","attributes":{"name":"A"}}}`))
+		if resp.StatusCode != http.StatusNotFound {
+			t.Fatalf("expected 404, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("name empty", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &vocation.Vocation{ID: id, Name: "Old"}
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+		idStr := mustUUIDStringVocation(t, id)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPatch, "/api/v1/vocation/update/"+idStr, []byte(`{"data":{"type":"vocation","id":"`+idStr+`","attributes":{"name":"  "}}}`))
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("update error", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &vocation.Vocation{ID: id, Name: "Old"}
+		repo.updateErr = errors.New("update failed")
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+		idStr := mustUUIDStringVocation(t, id)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPatch, "/api/v1/vocation/update/"+idStr, []byte(`{"data":{"type":"vocation","id":"`+idStr+`","attributes":{"name":"New"}}}`))
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with refetch", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		id := uuidv7.MustBytes()
+		repo.rows[string(id)] = &vocation.Vocation{ID: id, Name: "Old"}
+		h := NewVocationHandler(service.NewVocationService(repo))
+		actor := uuidv7.MustBytes()
+		app := newVocationTestApp(h, actor)
+		idStr := mustUUIDStringVocation(t, id)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPatch, "/api/v1/vocation/update/"+idStr, []byte(`{"data":{"type":"vocation","id":"`+idStr+`","attributes":{"name":"New","sortkey":7,"note":"Desc","is_active":false}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastUpdate == nil || repo.lastUpdate.Name != "New" {
+			t.Fatalf("expected updated values")
+		}
+		if repo.lastUpdate.SortKey == nil || *repo.lastUpdate.SortKey != 7 || repo.lastUpdate.Note != "Desc" || repo.lastUpdate.IsActive {
+			t.Fatalf("expected sortkey/note/is_active updated values")
+		}
+		if string(repo.lastUpdate.UpdatedBy) != string(actor) {
+			t.Fatalf("expected updated_by from actor")
+		}
+	})
+
+	t.Run("success fallback when refetch fails", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		id := uuidv7.MustBytes()
+		existing := &vocation.Vocation{ID: id, Name: "Old"}
+		repo.getByIDFn = func(_ []byte, call int) (*vocation.Vocation, error) {
+			if call == 1 {
+				return existing, nil
+			}
+			return nil, errors.New("second lookup failed")
+		}
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+		idStr := mustUUIDStringVocation(t, id)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodPatch, "/api/v1/vocation/update/"+idStr, []byte(`{"data":{"type":"vocation","id":"`+idStr+`","attributes":{"note":"Only note"}}}`))
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestVocationHandlerDelete(t *testing.T) {
+	t.Run("invalid uuid", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodDelete, "/api/v1/vocation/delete/not-uuid", nil)
+		if resp.StatusCode != http.StatusUnprocessableEntity {
+			t.Fatalf("expected 422, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("delete error", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		repo.deleteErr = errors.New("delete failed")
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+		id := mustUUIDStringVocation(t, uuidv7.MustBytes())
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodDelete, "/api/v1/vocation/delete/"+id, nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		h := NewVocationHandler(service.NewVocationService(repo))
+		actor := uuidv7.MustBytes()
+		app := newVocationTestApp(h, actor)
+		id := uuidv7.MustBytes()
+		idStr := mustUUIDStringVocation(t, id)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodDelete, "/api/v1/vocation/delete/"+idStr, nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if string(repo.lastDeleteBy) != string(actor) {
+			t.Fatalf("expected deleted_by from actor")
+		}
+	})
+}
+
+func TestVocationHandlerList(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodGet, "/api/v1/vocation/get-all", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success with filter name and clamp max", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		repo.listRows = []vocation.Vocation{{ID: uuidv7.MustBytes(), Name: "A", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodGet, "/api/v1/vocation/get-all?filter[name]=abc&page[number]=0&page=0&page[size]=0&limit=101&sort=-sortkey", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListSort != "is_active DESC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN 0 ELSE 1 END ASC, CASE WHEN is_active = 1 AND sortkey IS NOT NULL AND sortkey >= 0 THEN sortkey END DESC, name ASC" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q sort=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListSort, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success with search and clamp min", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		repo.listRows = []vocation.Vocation{}
+		repo.listTotal = 0
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodGet, "/api/v1/vocation/get-all?page=2&size=-1&search=needle", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "needle" || repo.lastListLimit != 0 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestVocationHandlerListDatatable(t *testing.T) {
+	t.Run("list error", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		repo.listErr = errors.New("list failed")
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodGet, "/api/v1/vocation/get-all/dt", nil)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("expected 400, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success clamp max and page floor", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		repo.listRows = []vocation.Vocation{{ID: uuidv7.MustBytes(), Name: "A", CreatedAt: time.Now(), UpdatedAt: time.Now()}}
+		repo.listTotal = 1
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodGet, "/api/v1/vocation/get-all/dt?page=0&limit=0&size=101&draw=7&search=abc", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListFilter != "abc" || repo.lastListLimit != 100 || repo.lastListOffset != 0 {
+			t.Fatalf("unexpected list params: filter=%q limit=%d offset=%d", repo.lastListFilter, repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+
+	t.Run("success clamp min", func(t *testing.T) {
+		repo := newMemVocationRepo()
+		repo.listRows = []vocation.Vocation{}
+		repo.listTotal = 0
+		h := NewVocationHandler(service.NewVocationService(repo))
+		app := newVocationTestApp(h, nil)
+
+		resp, _ := doJSONRequestVocation(t, app, http.MethodGet, "/api/v1/vocation/get-all/dt?page=2&limit=0&size=-1", nil)
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+		if repo.lastListLimit != 20 || repo.lastListOffset != 20 {
+			t.Fatalf("unexpected list params: limit=%d offset=%d", repo.lastListLimit, repo.lastListOffset)
+		}
+	})
+}
+
+func TestVocationResource(t *testing.T) {
+	id := uuidv7.MustBytes()
+	createdBy := uuidv7.MustBytes()
+	updatedBy := uuidv7.MustBytes()
+	deletedBy := uuidv7.MustBytes()
+	now := time.Now().UTC().Truncate(time.Second)
+	deletedAt := now.Add(time.Hour)
+
+	row := &vocation.Vocation{
+		ID:        id,
+		Name:      "Main",
+		SortKey:   intPtrVocationHandler(5),
+		Note:      "Center",
+		IsActive:  true,
+		CreatedAt: now,
+		CreatedBy: createdBy,
+		UpdatedAt: now,
+		UpdatedBy: updatedBy,
+		DeletedAt: &deletedAt,
+		DeletedBy: deletedBy,
+	}
+
+	res := vocationResource(row)
+	if res.Type != "vocation" {
+		t.Fatalf("unexpected type: %s", res.Type)
+	}
+	if res.ID == "" || res.Attributes.CreatedBy == "" || res.Attributes.UpdatedBy == "" || res.Attributes.DeletedBy == "" {
+		t.Fatalf("expected UUID fields in resource")
+	}
+	if res.Attributes.SortKey == nil || *res.Attributes.SortKey != 5 || res.Attributes.Note != "Center" || !res.Attributes.IsActive {
+		t.Fatalf("expected sortkey/note/is_active fields in resource")
+	}
+	if res.Attributes.CreatedAt == "" || res.Attributes.UpdatedAt == "" || res.Attributes.DeletedAt == "" {
+		t.Fatalf("expected time fields in resource")
+	}
+}
+
+func intPtrVocationHandler(v int) *int { return &v }
diff --git a/internal/transport/http/jsonapi/jsonapi.go b/internal/transport/http/jsonapi/jsonapi.go
new file mode 100644
index 0000000..7280ff6
--- /dev/null
+++ b/internal/transport/http/jsonapi/jsonapi.go
@@ -0,0 +1,43 @@
+package jsonapi
+
+import "github.com/gofiber/fiber/v2"
+
+type Resource struct {
+	Type       string         `json:"type"`
+	ID         string         `json:"id,omitempty"`
+	Attributes map[string]any `json:"attributes,omitempty"`
+}
+
+type Document struct {
+	Data any `json:"data"`
+	Meta any `json:"meta,omitempty"`
+}
+
+type ErrorSource struct {
+	Pointer string `json:"pointer,omitempty"`
+}
+
+type ErrorObject struct {
+	Status    string       `json:"status"`
+	Code      string       `json:"code,omitempty"`
+	ErrorCode string       `json:"error_code,omitempty"`
+	Title     string       `json:"title,omitempty"`
+	Detail    string       `json:"detail,omitempty"`
+	Source    *ErrorSource `json:"source,omitempty"`
+}
+
+type ErrorDocument struct {
+	Errors []ErrorObject `json:"errors"`
+}
+
+func Write(c *fiber.Ctx, status int, data any) error {
+	return c.Status(status).JSON(Document{Data: data})
+}
+
+func WriteWithMeta(c *fiber.Ctx, status int, data any, meta any) error {
+	return c.Status(status).JSON(Document{Data: data, Meta: meta})
+}
+
+func WriteErrors(c *fiber.Ctx, status int, errs []ErrorObject) error {
+	return c.Status(status).JSON(ErrorDocument{Errors: errs})
+}
diff --git a/internal/transport/http/jsonapi/jsonapi_test.go b/internal/transport/http/jsonapi/jsonapi_test.go
new file mode 100644
index 0000000..1bca269
--- /dev/null
+++ b/internal/transport/http/jsonapi/jsonapi_test.go
@@ -0,0 +1,75 @@
+package jsonapi
+
+import (
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/gofiber/fiber/v2"
+)
+
+func TestWrite(t *testing.T) {
+	app := fiber.New()
+	app.Get("/write", func(c *fiber.Ctx) error {
+		return Write(c, http.StatusCreated, Resource{Type: "sample", ID: "1", Attributes: map[string]any{"name": "john"}})
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/write", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusCreated {
+		t.Fatalf("expected 201, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !strings.Contains(string(body), `"data"`) || !strings.Contains(string(body), `"type":"sample"`) {
+		t.Fatalf("unexpected body: %s", string(body))
+	}
+}
+
+func TestWriteWithMeta(t *testing.T) {
+	app := fiber.New()
+	app.Get("/write-meta", func(c *fiber.Ctx) error {
+		return WriteWithMeta(c, http.StatusOK, Resource{Type: "sample"}, map[string]any{"total": 1})
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/write-meta", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !strings.Contains(string(body), `"meta"`) || !strings.Contains(string(body), `"total":1`) {
+		t.Fatalf("unexpected body: %s", string(body))
+	}
+}
+
+func TestWriteErrors(t *testing.T) {
+	app := fiber.New()
+	app.Get("/write-errors", func(c *fiber.Ctx) error {
+		return WriteErrors(c, http.StatusUnprocessableEntity, []ErrorObject{{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: "email is required",
+			Source: &ErrorSource{Pointer: "/data/attributes/email"},
+		}})
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/write-errors", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	if resp.StatusCode != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", resp.StatusCode)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if !strings.Contains(string(body), `"errors"`) || !strings.Contains(string(body), `"email is required"`) {
+		t.Fatalf("unexpected body: %s", string(body))
+	}
+}
diff --git a/internal/transport/http/middleware/auth_middleware.go b/internal/transport/http/middleware/auth_middleware.go
new file mode 100644
index 0000000..d2e9bff
--- /dev/null
+++ b/internal/transport/http/middleware/auth_middleware.go
@@ -0,0 +1,30 @@
+package middleware
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/appctx"
+	"wucher/internal/shared/pkg/apperrorsx"
+)
+
+func AuthRequired(svc *service.AuthService) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		if svc == nil {
+			e := apperrorsx.New(apperrorsx.ErrUserUnauthorized)
+			e.Message = "auth service not configured"
+			return apperrorsx.Write(c, e)
+		}
+
+		ctx := c.UserContext()
+		for _, candidate := range service.CookieValues(c.Get(fiber.HeaderCookie), svc.AccessCookieName()) {
+			userID, err := svc.ParseAccessToken(ctx, candidate)
+			if err == nil {
+				c.Locals("user_id", userID)
+				c.SetUserContext(appctx.WithUserID(ctx, userID))
+				return c.Next()
+			}
+		}
+		return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTokenInvalid))
+	}
+}
diff --git a/internal/transport/http/middleware/middleware_test.go b/internal/transport/http/middleware/middleware_test.go
new file mode 100644
index 0000000..e557cdc
--- /dev/null
+++ b/internal/transport/http/middleware/middleware_test.go
@@ -0,0 +1,949 @@
+package middleware
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/config"
+	"wucher/internal/domain/auth"
+	"wucher/internal/service"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/appctx"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+type middlewareAuthRepo struct {
+	users      map[string]*auth.User
+	getByIDErr error
+}
+
+func newMiddlewareAuthRepo() *middlewareAuthRepo {
+	return &middlewareAuthRepo{users: map[string]*auth.User{}}
+}
+
+func (r *middlewareAuthRepo) CreateUser(_ context.Context, user *auth.User) error {
+	if user != nil && !user.IsActive {
+		user.IsActive = true
+	}
+	r.users[string(user.ID)] = user
+	return nil
+}
+func (r *middlewareAuthRepo) GetUserByID(_ context.Context, id []byte) (*auth.User, error) {
+	if r.getByIDErr != nil {
+		return nil, r.getByIDErr
+	}
+	return r.users[string(id)], nil
+}
+func (r *middlewareAuthRepo) GetUserByEmail(_ context.Context, _ string) (*auth.User, error) {
+	return nil, nil
+}
+func (r *middlewareAuthRepo) GetUserBySSOEmail(_ context.Context, _ string) (*auth.User, error) {
+	return nil, nil
+}
+func (r *middlewareAuthRepo) GetUserByUsername(_ context.Context, _ string) (*auth.User, error) {
+	return nil, nil
+}
+func (r *middlewareAuthRepo) UpdateUserTimezone(_ context.Context, _ []byte, _ string) error {
+	return nil
+}
+func (r *middlewareAuthRepo) SetUserPassword(_ context.Context, _ []byte, _ []byte, _ []byte) error {
+	return nil
+}
+func (r *middlewareAuthRepo) SetUserSecurityPIN(_ context.Context, id []byte, pinHash []byte, setAt time.Time) error {
+	u := r.users[string(id)]
+	if u == nil {
+		return nil
+	}
+	u.SecurityPINHash = append([]byte(nil), pinHash...)
+	ts := setAt.UTC()
+	u.SecurityPINSetAt = &ts
+	return nil
+}
+func (r *middlewareAuthRepo) MarkEmailVerified(_ context.Context, _ []byte) error {
+	return nil
+}
+func (r *middlewareAuthRepo) CreatePasswordResetToken(_ context.Context, _ *auth.PasswordResetToken) error {
+	return nil
+}
+func (r *middlewareAuthRepo) InvalidateActivePasswordResetTokensByUserID(_ context.Context, _ []byte, _ time.Time) error {
+	return nil
+}
+func (r *middlewareAuthRepo) ConsumePasswordResetTokenAndSetPassword(_ context.Context, _ []byte, _ []byte, _ []byte, _ time.Time) ([]byte, bool, error) {
+	return nil, false, nil
+}
+func (r *middlewareAuthRepo) CreateSecurityPINResetToken(_ context.Context, _ *auth.SecurityPINResetToken) error {
+	return nil
+}
+func (r *middlewareAuthRepo) InvalidateActiveSecurityPINResetTokensByUserID(_ context.Context, _ []byte, _ time.Time) error {
+	return nil
+}
+func (r *middlewareAuthRepo) GetActiveSecurityPINResetTokenUser(_ context.Context, _ []byte, _ time.Time) (*auth.User, error) {
+	return nil, nil
+}
+func (r *middlewareAuthRepo) ConsumeSecurityPINResetTokenAndSetPIN(_ context.Context, _ []byte, _ []byte, _ time.Time) ([]byte, bool, error) {
+	return nil, false, nil
+}
+func (r *middlewareAuthRepo) UpsertIdentity(_ context.Context, _ *auth.UserIdentity) error {
+	return nil
+}
+func (r *middlewareAuthRepo) CreateIdentity(_ context.Context, _ *auth.UserIdentity) error {
+	return nil
+}
+func (r *middlewareAuthRepo) GetIdentityByProviderSubject(_ context.Context, _ string, _ string) (*auth.UserIdentity, error) {
+	return nil, nil
+}
+func (r *middlewareAuthRepo) GetIdentityByUserID(_ context.Context, _ []byte) (*auth.UserIdentity, error) {
+	return nil, nil
+}
+func (r *middlewareAuthRepo) DeleteIdentityByUserIDProvider(_ context.Context, _ []byte, _ string) (bool, error) {
+	return false, nil
+}
+func (r *middlewareAuthRepo) GetUserTOTP(_ context.Context, _ []byte) (*auth.UserTOTP, error) {
+	return nil, nil
+}
+func (r *middlewareAuthRepo) UpsertUserTOTP(_ context.Context, _ *auth.UserTOTP) error {
+	return nil
+}
+func (r *middlewareAuthRepo) DisableUserTOTP(_ context.Context, _ []byte) error {
+	return nil
+}
+func (r *middlewareAuthRepo) DeleteUserTOTPSetup(_ context.Context, _ []byte) error {
+	return nil
+}
+func (r *middlewareAuthRepo) UpdateUserTOTPLastUsed(_ context.Context, _ []byte) error {
+	return nil
+}
+func (r *middlewareAuthRepo) GetActiveUserEmailLoginOTP(_ context.Context, _ []byte, _ time.Time) (*auth.UserEmailLoginOTP, error) {
+	return nil, nil
+}
+func (r *middlewareAuthRepo) CountUserEmailLoginOTPSince(_ context.Context, _ []byte, _ time.Time) (int64, error) {
+	return 0, nil
+}
+func (r *middlewareAuthRepo) CreateUserEmailLoginOTP(_ context.Context, _ *auth.UserEmailLoginOTP) error {
+	return nil
+}
+func (r *middlewareAuthRepo) InvalidateActiveUserEmailLoginOTPs(_ context.Context, _ []byte, _ time.Time) error {
+	return nil
+}
+func (r *middlewareAuthRepo) ConsumeUserEmailLoginOTP(_ context.Context, _ []byte, _ []byte, _ time.Time) (bool, int, error) {
+	return false, 0, nil
+}
+func (r *middlewareAuthRepo) ListUserWebAuthnCredentials(_ context.Context, _ []byte) ([]auth.UserWebAuthnCredential, error) {
+	return nil, nil
+}
+func (r *middlewareAuthRepo) CreateUserWebAuthnCredential(_ context.Context, _ *auth.UserWebAuthnCredential) error {
+	return nil
+}
+func (r *middlewareAuthRepo) UpdateUserWebAuthnCredential(_ context.Context, _ []byte, _ []byte, _ []byte, _ time.Time) error {
+	return nil
+}
+func (r *middlewareAuthRepo) DeleteAllUserWebAuthnCredentials(_ context.Context, _ []byte) error {
+	return nil
+}
+
+type middlewareRoleRepo struct {
+	allowed            bool
+	err                error
+	permissionByKey    *auth.Permission
+	permissionByKeyErr error
+}
+
+type middlewareTokenStore struct {
+	store map[string][]byte
+}
+
+func newMiddlewareTokenStore() *middlewareTokenStore {
+	return &middlewareTokenStore{store: map[string][]byte{}}
+}
+
+func (m *middlewareTokenStore) Set(_ context.Context, key string, value []byte, _ time.Duration) error {
+	m.store[key] = append([]byte(nil), value...)
+	return nil
+}
+
+func (m *middlewareTokenStore) SetIfNotExists(_ context.Context, key string, value []byte, _ time.Duration) (bool, error) {
+	if _, ok := m.store[key]; ok {
+		return false, nil
+	}
+	m.store[key] = append([]byte(nil), value...)
+	return true, nil
+}
+
+func (m *middlewareTokenStore) Get(_ context.Context, key string) ([]byte, error) {
+	v, ok := m.store[key]
+	if !ok {
+		return nil, nil
+	}
+	return append([]byte(nil), v...), nil
+}
+
+func (m *middlewareTokenStore) Delete(_ context.Context, key string) error {
+	delete(m.store, key)
+	return nil
+}
+
+func (r *middlewareRoleRepo) CreateRole(_ context.Context, _ *auth.Role) error { return nil }
+func (r *middlewareRoleRepo) UpdateRole(_ context.Context, _ *auth.Role) error { return nil }
+func (r *middlewareRoleRepo) DeleteRole(_ context.Context, _ []byte) error     { return nil }
+func (r *middlewareRoleRepo) GetRoleByID(_ context.Context, _ []byte) (*auth.Role, error) {
+	return nil, nil
+}
+func (r *middlewareRoleRepo) GetRoleByName(_ context.Context, _ string) (*auth.Role, error) {
+	return nil, nil
+}
+func (r *middlewareRoleRepo) HasRolePermission(_ context.Context, _ []byte, _ string) (bool, error) {
+	if r.err != nil {
+		return false, r.err
+	}
+	return r.allowed, nil
+}
+func (r *middlewareRoleRepo) GetPermissionByID(_ context.Context, _ []byte) (*auth.Permission, error) {
+	return nil, nil
+}
+func (r *middlewareRoleRepo) GetPermissionByKey(_ context.Context, _ string) (*auth.Permission, error) {
+	return r.permissionByKey, r.permissionByKeyErr
+}
+func (r *middlewareRoleRepo) UpdatePermission(_ context.Context, _ *auth.Permission) error {
+	return nil
+}
+func (r *middlewareRoleRepo) ListPermissionsByRoleID(_ context.Context, _ []byte) ([]auth.Permission, error) {
+	return nil, nil
+}
+func (r *middlewareRoleRepo) ListPermissions(_ context.Context, _ string, _ string, _ int, _ int) ([]auth.Permission, int64, error) {
+	return nil, 0, nil
+}
+func (r *middlewareRoleRepo) AssignPermission(_ context.Context, roleID, permissionID []byte) (*auth.RolePermission, error) {
+	return &auth.RolePermission{RoleID: roleID, PermissionID: permissionID}, nil
+}
+func (r *middlewareRoleRepo) RemovePermission(_ context.Context, _ []byte, _ []byte) error {
+	return nil
+}
+func (r *middlewareRoleRepo) ListRoles(_ context.Context, _ string, _ string, _ int, _ int) ([]auth.Role, int64, error) {
+	return nil, 0, nil
+}
+
+func TestAuthRequired(t *testing.T) {
+	t.Run("service not configured", func(t *testing.T) {
+		app := fiber.New()
+		app.Use(AuthRequired(nil))
+		app.Get("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid access token", func(t *testing.T) {
+		svc := service.NewAuthService(nil, nil, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			JWTAccessSecret:     "access-secret",
+			JWTRefreshSecret:    "refresh-secret",
+			JWTAccessTTL:        time.Minute,
+			JWTRefreshTTL:       time.Hour,
+			JWTAccessCookieName: "at",
+		}})
+
+		app := fiber.New()
+		app.Use(AuthRequired(svc))
+		app.Get("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		req.AddCookie(&http.Cookie{Name: svc.AccessCookieName(), Value: "not-a-jwt"})
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("success stores user_id and continues", func(t *testing.T) {
+		repo := newMiddlewareAuthRepo()
+		tokens := newMiddlewareTokenStore()
+		svc := service.NewAuthService(repo, nil, tokens, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			JWTAccessSecret:     "access-secret",
+			JWTRefreshSecret:    "refresh-secret",
+			JWTAccessTTL:        time.Minute,
+			JWTRefreshTTL:       time.Hour,
+			JWTAccessCookieName: "at",
+		}})
+		userID := uuidv7.MustBytes()
+		user := &auth.User{ID: userID, IsActive: true}
+		if err := repo.CreateUser(context.Background(), user); err != nil {
+			t.Fatalf("create user: %v", err)
+		}
+		pair, err := svc.IssueTokensWithClientForProvider(context.Background(), user, "", "", "microsoft")
+		if err != nil {
+			t.Fatalf("issue tokens: %v", err)
+		}
+
+		app := fiber.New()
+		app.Use(AuthRequired(svc))
+		app.Get("/protected", func(c *fiber.Ctx) error {
+			raw := c.Locals("user_id")
+			got, ok := raw.([]byte)
+			if !ok || string(got) != string(userID) {
+				return c.Status(http.StatusInternalServerError).SendString("missing user context")
+			}
+			if got := appctx.GetUserID(c.UserContext()); string(got) != string(userID) {
+				return c.Status(http.StatusInternalServerError).SendString("missing user id in request context")
+			}
+			return c.SendStatus(http.StatusOK)
+		})
+
+		req, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		req.AddCookie(&http.Cookie{Name: svc.AccessCookieName(), Value: pair.AccessToken})
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			body, _ := io.ReadAll(resp.Body)
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(body))
+		}
+	})
+
+	t.Run("duplicate access cookies use the valid token", func(t *testing.T) {
+		repo := newMiddlewareAuthRepo()
+		tokens := newMiddlewareTokenStore()
+		svc := service.NewAuthService(repo, nil, tokens, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			JWTAccessSecret:     "access-secret",
+			JWTRefreshSecret:    "refresh-secret",
+			JWTAccessTTL:        time.Minute,
+			JWTRefreshTTL:       time.Hour,
+			JWTAccessCookieName: "at",
+		}})
+		userID := uuidv7.MustBytes()
+		user := &auth.User{ID: userID, IsActive: true}
+		if err := repo.CreateUser(context.Background(), user); err != nil {
+			t.Fatalf("create user: %v", err)
+		}
+		pair, err := svc.IssueTokensWithClientForProvider(context.Background(), user, "", "", "microsoft")
+		if err != nil {
+			t.Fatalf("issue tokens: %v", err)
+		}
+
+		app := fiber.New()
+		app.Use(AuthRequired(svc))
+		app.Get("/protected", func(c *fiber.Ctx) error {
+			raw := c.Locals("user_id")
+			got, ok := raw.([]byte)
+			if !ok || string(got) != string(userID) {
+				return c.Status(http.StatusInternalServerError).SendString("missing user context")
+			}
+			return c.SendStatus(http.StatusOK)
+		})
+
+		req, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		req.Header.Set("Cookie", svc.AccessCookieName()+"=not-a-valid-token; "+svc.AccessCookieName()+"="+pair.AccessToken)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			body, _ := io.ReadAll(resp.Body)
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(body))
+		}
+	})
+
+	t.Run("expired by idle timeout", func(t *testing.T) {
+		repo := newMiddlewareAuthRepo()
+		tokens := newMiddlewareTokenStore()
+		svc := service.NewAuthService(repo, nil, tokens, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{
+			JWTAccessSecret:     "access-secret",
+			JWTRefreshSecret:    "refresh-secret",
+			JWTAccessTTL:        time.Minute,
+			JWTRefreshTTL:       time.Hour,
+			SessionIdleTTL:      time.Millisecond,
+			JWTAccessCookieName: "at",
+		}})
+		userID := uuidv7.MustBytes()
+		user := &auth.User{ID: userID, IsActive: true}
+		if err := repo.CreateUser(context.Background(), user); err != nil {
+			t.Fatalf("create user: %v", err)
+		}
+		pair, err := svc.IssueTokensWithClientForProvider(context.Background(), user, "", "", "microsoft")
+		if err != nil {
+			t.Fatalf("issue tokens: %v", err)
+		}
+		time.Sleep(5 * time.Millisecond)
+
+		app := fiber.New()
+		app.Use(AuthRequired(svc))
+		app.Get("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		req.AddCookie(&http.Cookie{Name: svc.AccessCookieName(), Value: pair.AccessToken})
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401 for idle-expired session, got %d", resp.StatusCode)
+		}
+	})
+}
+
+func TestPermissionRequired(t *testing.T) {
+	t.Run("service not configured", func(t *testing.T) {
+		app := fiber.New()
+		app.Use(PermissionRequired(nil, "users.read"))
+		app.Get("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("missing auth context", func(t *testing.T) {
+		svc := service.NewAuthService(nil, nil, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		app := fiber.New()
+		app.Use(PermissionRequired(svc, "users.read"))
+		app.Get("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("permission check error", func(t *testing.T) {
+		repo := newMiddlewareAuthRepo()
+		roleRepo := &middlewareRoleRepo{err: context.DeadlineExceeded}
+		svc := service.NewAuthService(repo, roleRepo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		userID := uuidv7.MustBytes()
+		roleID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID}
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Use(PermissionRequired(svc, "users.read"))
+		app.Get("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusForbidden {
+			t.Fatalf("expected 403, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("insufficient permission", func(t *testing.T) {
+		repo := newMiddlewareAuthRepo()
+		roleRepo := &middlewareRoleRepo{allowed: false}
+		svc := service.NewAuthService(repo, roleRepo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		userID := uuidv7.MustBytes()
+		roleID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID}
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Use(PermissionRequired(svc, "users.read"))
+		app.Get("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusForbidden {
+			t.Fatalf("expected 403, got %d", resp.StatusCode)
+		}
+		body, _ := io.ReadAll(resp.Body)
+		if !strings.Contains(string(body), "insufficient permission") {
+			t.Fatalf("unexpected body: %s", string(body))
+		}
+	})
+
+	t.Run("allowed permission continues", func(t *testing.T) {
+		repo := newMiddlewareAuthRepo()
+		roleRepo := &middlewareRoleRepo{allowed: true}
+		svc := service.NewAuthService(repo, roleRepo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+
+		userID := uuidv7.MustBytes()
+		roleID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID}
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Use(PermissionRequired(svc, "users.read"))
+		app.Get("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("requires pin without token returns 202", func(t *testing.T) {
+		repo := newMiddlewareAuthRepo()
+		roleRepo := &middlewareRoleRepo{
+			allowed:         true,
+			permissionByKey: &auth.Permission{RequiresPIN: true},
+		}
+		tokens := newMiddlewareTokenStore()
+		svc := service.NewAuthService(
+			repo,
+			roleRepo,
+			tokens,
+			nil,
+			service.AuthServiceDependencies{
+				SSO: nil, Protector: nil, Config: config.AuthConfig{
+					JWTAccessSecret:           "access-secret",
+					JWTRefreshSecret:          "refresh-secret",
+					JWTAccessTTL:              time.Minute,
+					JWTRefreshTTL:             time.Minute * 10,
+					SecurityPINActionTokenTTL: time.Minute,
+				},
+			},
+		)
+
+		userID := uuidv7.MustBytes()
+		roleID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID}
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Use(PermissionRequired(svc, "users.read"))
+		app.Get("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusAccepted {
+			t.Fatalf("expected 202, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("requires pin with mapped action token returns 200", func(t *testing.T) {
+		repo := newMiddlewareAuthRepo()
+		roleRepo := &middlewareRoleRepo{
+			allowed:         true,
+			permissionByKey: &auth.Permission{RequiresPIN: true},
+		}
+		tokens := newMiddlewareTokenStore()
+		svc := service.NewAuthService(
+			repo,
+			roleRepo,
+			tokens,
+			nil,
+			service.AuthServiceDependencies{
+				SSO: nil, Protector: nil, Config: config.AuthConfig{
+					JWTAccessSecret:           "access-secret",
+					JWTRefreshSecret:          "refresh-secret",
+					JWTAccessTTL:              time.Minute,
+					JWTRefreshTTL:             time.Minute * 10,
+					SecurityPINActionTokenTTL: time.Minute,
+				},
+			},
+		)
+
+		userID := uuidv7.MustBytes()
+		roleID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID}
+		if err := svc.SetSecurityPIN(context.Background(), userID, "123456"); err != nil {
+			t.Fatalf("SetSecurityPIN: %v", err)
+		}
+
+		token, err := svc.VerifySecurityPINForAction(context.Background(), userID, "123456", sharedconst.PinActionBaseCreate)
+		if err != nil {
+			t.Fatalf("VerifySecurityPINForAction: %v", err)
+		}
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Use(PermissionRequired(svc, "base.create"))
+		app.Post("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		req.Header.Set(permissionPinVerificationHeader, token)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("reusable variant accepts the same token twice", func(t *testing.T) {
+		repo := newMiddlewareAuthRepo()
+		roleRepo := &middlewareRoleRepo{
+			allowed:         true,
+			permissionByKey: &auth.Permission{RequiresPIN: true},
+		}
+		tokens := newMiddlewareTokenStore()
+		svc := service.NewAuthService(
+			repo,
+			roleRepo,
+			tokens,
+			nil,
+			service.AuthServiceDependencies{
+				SSO: nil, Protector: nil, Config: config.AuthConfig{
+					JWTAccessSecret:           "access-secret",
+					JWTRefreshSecret:          "refresh-secret",
+					JWTAccessTTL:              time.Minute,
+					JWTRefreshTTL:             time.Minute * 10,
+					SecurityPINActionTokenTTL: time.Minute,
+				},
+			},
+		)
+
+		userID := uuidv7.MustBytes()
+		roleID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID}
+		if err := svc.SetSecurityPIN(context.Background(), userID, "123456"); err != nil {
+			t.Fatalf("SetSecurityPIN: %v", err)
+		}
+
+		token, err := svc.VerifySecurityPINForAction(context.Background(), userID, "123456", sharedconst.PinActionAuditLogRead)
+		if err != nil {
+			t.Fatalf("VerifySecurityPINForAction: %v", err)
+		}
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Use(PermissionRequiredReusable(svc, "audit.read"))
+		app.Get("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req1, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		req1.Header.Set(permissionPinVerificationHeader, token)
+		resp1, err := app.Test(req1)
+		if err != nil {
+			t.Fatalf("app.Test first: %v", err)
+		}
+		if resp1.StatusCode != http.StatusOK {
+			t.Fatalf("expected first request 200, got %d", resp1.StatusCode)
+		}
+
+		req2, _ := http.NewRequest(http.MethodGet, "/protected", nil)
+		req2.Header.Set(permissionPinVerificationHeader, token)
+		resp2, err := app.Test(req2)
+		if err != nil {
+			t.Fatalf("app.Test second: %v", err)
+		}
+		if resp2.StatusCode != http.StatusOK {
+			t.Fatalf("expected second request 200, got %d", resp2.StatusCode)
+		}
+	})
+
+	t.Run("consuming variant rejects the same token twice", func(t *testing.T) {
+		repo := newMiddlewareAuthRepo()
+		roleRepo := &middlewareRoleRepo{
+			allowed:         true,
+			permissionByKey: &auth.Permission{RequiresPIN: true},
+		}
+		tokens := newMiddlewareTokenStore()
+		svc := service.NewAuthService(
+			repo,
+			roleRepo,
+			tokens,
+			nil,
+			service.AuthServiceDependencies{
+				SSO: nil, Protector: nil, Config: config.AuthConfig{
+					JWTAccessSecret:           "access-secret",
+					JWTRefreshSecret:          "refresh-secret",
+					JWTAccessTTL:              time.Minute,
+					JWTRefreshTTL:             time.Minute * 10,
+					SecurityPINActionTokenTTL: time.Minute,
+				},
+			},
+		)
+
+		userID := uuidv7.MustBytes()
+		roleID := uuidv7.MustBytes()
+		repo.users[string(userID)] = &auth.User{ID: userID, RoleID: roleID}
+		if err := svc.SetSecurityPIN(context.Background(), userID, "123456"); err != nil {
+			t.Fatalf("SetSecurityPIN: %v", err)
+		}
+
+		token, err := svc.VerifySecurityPINForAction(context.Background(), userID, "123456", sharedconst.PinActionBaseCreate)
+		if err != nil {
+			t.Fatalf("VerifySecurityPINForAction: %v", err)
+		}
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Use(PermissionRequired(svc, "base.create"))
+		app.Post("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req1, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		req1.Header.Set(permissionPinVerificationHeader, token)
+		resp1, err := app.Test(req1)
+		if err != nil {
+			t.Fatalf("app.Test first: %v", err)
+		}
+		if resp1.StatusCode != http.StatusOK {
+			t.Fatalf("expected first request 200, got %d", resp1.StatusCode)
+		}
+
+		req2, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		req2.Header.Set(permissionPinVerificationHeader, token)
+		resp2, err := app.Test(req2)
+		if err != nil {
+			t.Fatalf("app.Test second: %v", err)
+		}
+		if resp2.StatusCode != http.StatusAccepted {
+			t.Fatalf("expected second request 202, got %d", resp2.StatusCode)
+		}
+	})
+}
+
+func TestPinRequired(t *testing.T) {
+	t.Run("service not configured", func(t *testing.T) {
+		app := fiber.New()
+		app.Use(PinRequired(nil, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"))
+		app.Post("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("missing auth context", func(t *testing.T) {
+		svc := service.NewAuthService(nil, nil, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		app := fiber.New()
+		app.Use(PinRequired(svc, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"))
+		app.Post("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusUnauthorized {
+			t.Fatalf("expected 401, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("invalid pin action token", func(t *testing.T) {
+		tokenStore := newMiddlewareTokenStore()
+		svc := service.NewAuthService(nil, nil, tokenStore, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		userID := uuidv7.MustBytes()
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Use(PinRequired(svc, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"))
+		app.Post("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		req.Header.Set(pinVerificationHeader, "bad-token")
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusAccepted {
+			t.Fatalf("expected 202, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("valid pin action token", func(t *testing.T) {
+		tokenStore := newMiddlewareTokenStore()
+		svc := service.NewAuthService(nil, nil, tokenStore, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		userID := uuidv7.MustBytes()
+		userIDStr, err := uuidv7.BytesToString(userID)
+		if err != nil {
+			t.Fatalf("bytes to string: %v", err)
+		}
+		action := "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74"
+		token := "token-ok"
+		key := "auth:pin_action:" + token
+		tokenStore.store[key] = []byte(userIDStr + "|" + action)
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Use(PinRequired(svc, action))
+		app.Post("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		req.Header.Set(pinVerificationHeader, token)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			body, _ := io.ReadAll(resp.Body)
+			t.Fatalf("expected 200, got %d body=%s", resp.StatusCode, string(body))
+		}
+
+		req2, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		req2.Header.Set(pinVerificationHeader, token)
+		resp2, err := app.Test(req2)
+		if err != nil {
+			t.Fatalf("app.Test second: %v", err)
+		}
+		if resp2.StatusCode != http.StatusAccepted {
+			t.Fatalf("expected second request 202, got %d", resp2.StatusCode)
+		}
+	})
+}
+
+func TestPinRequiredForPermission(t *testing.T) {
+	t.Run("skip when permission does not require pin", func(t *testing.T) {
+		roleRepo := &middlewareRoleRepo{permissionByKey: &auth.Permission{RequiresPIN: false}}
+		svc := service.NewAuthService(nil, roleRepo, nil, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		userID := uuidv7.MustBytes()
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Use(PinRequiredForPermission(svc, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", "user.delete"))
+		app.Post("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp.StatusCode)
+		}
+	})
+
+	t.Run("require pin when permission policy enabled", func(t *testing.T) {
+		tokenStore := newMiddlewareTokenStore()
+		roleRepo := &middlewareRoleRepo{permissionByKey: &auth.Permission{RequiresPIN: true}}
+		svc := service.NewAuthService(nil, roleRepo, tokenStore, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		userID := uuidv7.MustBytes()
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Use(PinRequiredForPermission(svc, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", "user.delete"))
+		app.Post("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		req, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		resp, err := app.Test(req)
+		if err != nil {
+			t.Fatalf("app.Test: %v", err)
+		}
+		if resp.StatusCode != http.StatusAccepted {
+			t.Fatalf("expected 202, got %d", resp.StatusCode)
+		}
+
+		userIDStr, err := uuidv7.BytesToString(userID)
+		if err != nil {
+			t.Fatalf("bytes to string: %v", err)
+		}
+		token := "token-ok"
+		tokenStore.store["auth:pin_action:"+token] = []byte(userIDStr + "|a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74")
+
+		req2, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		req2.Header.Set(pinVerificationHeader, token)
+		resp2, err := app.Test(req2)
+		if err != nil {
+			t.Fatalf("app.Test second: %v", err)
+		}
+		if resp2.StatusCode != http.StatusOK {
+			t.Fatalf("expected 200, got %d", resp2.StatusCode)
+		}
+	})
+
+	t.Run("reusable token when permission policy enabled", func(t *testing.T) {
+		tokenStore := newMiddlewareTokenStore()
+		roleRepo := &middlewareRoleRepo{permissionByKey: &auth.Permission{RequiresPIN: true}}
+		svc := service.NewAuthService(nil, roleRepo, tokenStore, nil, service.AuthServiceDependencies{SSO: nil, Protector: nil, Config: config.AuthConfig{}})
+		userID := uuidv7.MustBytes()
+
+		app := fiber.New()
+		app.Use(func(c *fiber.Ctx) error {
+			c.Locals("user_id", userID)
+			return c.Next()
+		})
+		app.Use(PinRequiredReusableForPermission(svc, "a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74", "user.delete"))
+		app.Post("/protected", func(c *fiber.Ctx) error { return c.SendStatus(http.StatusOK) })
+
+		userIDStr, err := uuidv7.BytesToString(userID)
+		if err != nil {
+			t.Fatalf("bytes to string: %v", err)
+		}
+		token := "token-reusable"
+		tokenStore.store["auth:pin_action:"+token] = []byte(userIDStr + "|a546de2f-f1e6-4c2c-ab03-9b4bf39f4d74")
+
+		req1, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		req1.Header.Set(pinVerificationHeader, token)
+		resp1, err := app.Test(req1)
+		if err != nil {
+			t.Fatalf("app.Test first: %v", err)
+		}
+		if resp1.StatusCode != http.StatusOK {
+			t.Fatalf("expected first request 200, got %d", resp1.StatusCode)
+		}
+
+		req2, _ := http.NewRequest(http.MethodPost, "/protected", nil)
+		req2.Header.Set(pinVerificationHeader, token)
+		resp2, err := app.Test(req2)
+		if err != nil {
+			t.Fatalf("app.Test second: %v", err)
+		}
+		if resp2.StatusCode != http.StatusOK {
+			t.Fatalf("expected second request 200, got %d", resp2.StatusCode)
+		}
+	})
+}
diff --git a/internal/transport/http/middleware/permission_middleware.go b/internal/transport/http/middleware/permission_middleware.go
new file mode 100644
index 0000000..5e0500e
--- /dev/null
+++ b/internal/transport/http/middleware/permission_middleware.go
@@ -0,0 +1,84 @@
+package middleware
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	sharedconst "wucher/internal/shared/const"
+	"wucher/internal/shared/pkg/apperrorsx"
+)
+
+const permissionPinVerificationHeader = "X-PIN-Verification-Token"
+
+func PermissionRequired(svc *service.AuthService, permissionKey string) fiber.Handler {
+	return permissionRequired(svc, permissionKey, true)
+}
+
+func PermissionRequiredReusable(svc *service.AuthService, permissionKey string) fiber.Handler {
+	return permissionRequired(svc, permissionKey, false)
+}
+
+func permissionRequired(svc *service.AuthService, permissionKey string, consume bool) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		if svc == nil {
+			e := apperrorsx.New(apperrorsx.ErrUserUnauthorized)
+			e.Message = "auth service not configured"
+			return apperrorsx.Write(c, e)
+		}
+
+		raw := c.Locals("user_id")
+		userID, ok := raw.([]byte)
+		if !ok || len(userID) == 0 {
+			e := apperrorsx.New(apperrorsx.ErrUserUnauthorized)
+			e.Message = "missing auth context"
+			return apperrorsx.Write(c, e)
+		}
+
+		allowed, err := svc.HasPermission(c.UserContext(), userID, permissionKey)
+		if err != nil {
+			e := apperrorsx.New(apperrorsx.ErrForbiddenAccess)
+			e.Message = "failed to verify permission"
+			return apperrorsx.Write(c, e)
+		}
+		if !allowed {
+			e := apperrorsx.New(apperrorsx.ErrForbiddenAccess)
+			e.Message = "insufficient permission"
+			return apperrorsx.Write(c, e)
+		}
+
+		required, err := svc.PermissionRequiresPIN(c.UserContext(), permissionKey)
+		if err != nil {
+			e := apperrorsx.New(apperrorsx.ErrForbiddenAccess)
+			e.Message = "failed to verify PIN requirement"
+			return apperrorsx.Write(c, e)
+		}
+		if required {
+			action := sharedconst.PinActionForPermissionKey(permissionKey)
+			if action == "" {
+				action = permissionKey
+			}
+			token := c.Get(permissionPinVerificationHeader)
+			sessionID := ""
+			for _, accessToken := range service.CookieValues(c.Get(fiber.HeaderCookie), svc.AccessCookieName()) {
+				sid, err := svc.ParseAccessTokenSessionID(c.UserContext(), accessToken)
+				if err == nil {
+					sessionID = sid
+					break
+				}
+			}
+			if sessionID == "" {
+				return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTokenInvalid))
+			}
+			var verifyErr error
+			if consume {
+				verifyErr = svc.ConsumeSecurityPINActionTokenInSession(c.UserContext(), userID, action, token, sessionID)
+			} else {
+				verifyErr = svc.ValidateSecurityPINActionTokenInSession(c.UserContext(), userID, action, token, sessionID)
+			}
+			if verifyErr != nil {
+				return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINVerificationRequired202))
+			}
+		}
+		return c.Next()
+	}
+}
diff --git a/internal/transport/http/middleware/pin_middleware.go b/internal/transport/http/middleware/pin_middleware.go
new file mode 100644
index 0000000..612ede0
--- /dev/null
+++ b/internal/transport/http/middleware/pin_middleware.go
@@ -0,0 +1,80 @@
+package middleware
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/apperrorsx"
+)
+
+const pinVerificationHeader = "X-PIN-Verification-Token"
+
+func PinRequired(svc *service.AuthService, action string) fiber.Handler {
+	return pinRequired(svc, action, "", true)
+}
+
+func PinRequiredForPermission(svc *service.AuthService, action, permissionKey string) fiber.Handler {
+	return pinRequired(svc, action, permissionKey, true)
+}
+
+func PinRequiredReusable(svc *service.AuthService, action string) fiber.Handler {
+	return pinRequired(svc, action, "", false)
+}
+
+func PinRequiredReusableForPermission(svc *service.AuthService, action, permissionKey string) fiber.Handler {
+	return pinRequired(svc, action, permissionKey, false)
+}
+
+func pinRequired(svc *service.AuthService, action, permissionKey string, consume bool) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		if svc == nil {
+			e := apperrorsx.New(apperrorsx.ErrUserUnauthorized)
+			e.Message = "auth service not configured"
+			return apperrorsx.Write(c, e)
+		}
+
+		raw := c.Locals("user_id")
+		userID, ok := raw.([]byte)
+		if !ok || len(userID) == 0 {
+			e := apperrorsx.New(apperrorsx.ErrUserUnauthorized)
+			e.Message = "missing auth context"
+			return apperrorsx.Write(c, e)
+		}
+
+		if permissionKey != "" {
+			required, err := svc.PermissionRequiresPIN(c.UserContext(), permissionKey)
+			if err != nil {
+				e := apperrorsx.New(apperrorsx.ErrForbiddenAccess)
+				e.Message = "failed to verify PIN requirement"
+				return apperrorsx.Write(c, e)
+			}
+			if !required {
+				return c.Next()
+			}
+		}
+
+		token := c.Get(pinVerificationHeader)
+		sessionID := ""
+		for _, accessToken := range service.CookieValues(c.Get(fiber.HeaderCookie), svc.AccessCookieName()) {
+			sid, err := svc.ParseAccessTokenSessionID(c.UserContext(), accessToken)
+			if err == nil {
+				sessionID = sid
+				break
+			}
+		}
+		if sessionID == "" {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrTokenInvalid))
+		}
+
+		var err error
+		if consume {
+			err = svc.ConsumeSecurityPINActionTokenInSession(c.UserContext(), userID, action, token, sessionID)
+		} else {
+			err = svc.ValidateSecurityPINActionTokenInSession(c.UserContext(), userID, action, token, sessionID)
+		}
+		if err != nil {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrPINVerificationRequired202))
+		}
+		return c.Next()
+	}
+}
diff --git a/internal/transport/http/middleware/wopi_middleware.go b/internal/transport/http/middleware/wopi_middleware.go
new file mode 100644
index 0000000..a886ebf
--- /dev/null
+++ b/internal/transport/http/middleware/wopi_middleware.go
@@ -0,0 +1,172 @@
+package middleware
+
+import (
+	"net/http"
+	"net/url"
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+const (
+	wopiAccessTokenQuery = "access_token"
+	wopiFileIDParam      = "fileId"
+)
+
+func WOPIRequired(svc *service.WOPIService) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		if svc == nil {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrFileManagerWOPIServiceUnavailable))
+		}
+
+		fileID, err := parseWOPIFileID(c)
+		if err != nil {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrFileManagerWOPIInvalidFileID))
+		}
+
+		token := firstNonEmptyWOPIQueryValue(c, wopiAccessTokenQuery)
+		if token == "" {
+			token = firstNonEmptyWOPISrcQueryValue(c, wopiAccessTokenQuery)
+		}
+		if token == "" {
+			authz := strings.TrimSpace(c.Get("Authorization"))
+			if strings.HasPrefix(strings.ToLower(authz), "bearer ") {
+				token = strings.TrimSpace(authz[7:])
+			}
+		}
+		claims, err := svc.VerifyAccessToken(token, fileID)
+		if err != nil {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrFileManagerWOPIInvalidToken).WithCause(err))
+		}
+
+		if err := svc.VerifyProof(c.Method(), c.Path(), token, c.Get("X-WOPI-TimeStamp"), c.Get("X-WOPI-Proof"), c.Get("X-WOPI-ProofOld")); err != nil {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrFileManagerWOPIInvalidProof).WithCause(err))
+		}
+
+		userID, _ := uuidv7.ParsePathLikeString(claims.UserID)
+		c.Locals("user_id", userID)
+		c.Locals("wopi_claims", claims)
+		c.Locals("wopi_permission", strings.ToLower(strings.TrimSpace(claims.Permission)))
+		c.Locals("wopi_takeover_id", claims.TakeoverID)
+		c.Locals("wopi_access_token", token)
+		return c.Next()
+	}
+}
+
+func firstNonEmptyWOPIQueryValue(c *fiber.Ctx, key string) string {
+	if c == nil || strings.TrimSpace(key) == "" {
+		return ""
+	}
+	found := ""
+	c.Context().QueryArgs().VisitAll(func(k, v []byte) {
+		if found != "" {
+			return
+		}
+		if !strings.EqualFold(string(k), key) {
+			return
+		}
+		value := strings.TrimSpace(string(v))
+		if value != "" {
+			found = value
+		}
+	})
+	if found != "" {
+		return found
+	}
+	return strings.TrimSpace(c.Query(key))
+}
+
+func firstNonEmptyWOPISrcQueryValue(c *fiber.Ctx, key string) string {
+	if c == nil || strings.TrimSpace(key) == "" {
+		return ""
+	}
+	src := strings.TrimSpace(c.Query("WOPISrc"))
+	if src == "" {
+		return ""
+	}
+	decoded := src
+	if unescaped, err := url.QueryUnescape(src); err == nil && strings.TrimSpace(unescaped) != "" {
+		decoded = strings.TrimSpace(unescaped)
+	}
+	parsed, err := url.Parse(decoded)
+	if err != nil {
+		return ""
+	}
+	query := parsed.Query()
+	if value := strings.TrimSpace(query.Get(key)); value != "" {
+		return value
+	}
+	return ""
+}
+
+func parseWOPIFileID(c *fiber.Ctx) ([]byte, error) {
+	if c == nil {
+		return nil, fiber.ErrBadRequest
+	}
+	candidates := []string{
+		c.Params(wopiFileIDParam),
+		c.Path(),
+		c.OriginalURL(),
+		c.Query("WOPISrc"),
+	}
+	for _, candidate := range candidates {
+		if fileID, err := uuidv7.ParsePathLikeString(candidate); err == nil {
+			return fileID, nil
+		}
+	}
+	return nil, fiber.ErrBadRequest
+}
+
+func WOPIRequestBodyLimit(maxBytes int) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		if maxBytes <= 0 {
+			return c.Next()
+		}
+		if c.Method() == http.MethodPost || c.Method() == http.MethodPut {
+			if c.Request().Header.ContentLength() > maxBytes {
+				return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrFileManagerWOPIValidationFailed))
+			}
+		}
+		return c.Next()
+	}
+}
+
+func WOPIPermissionRequired(required service.WOPIPermission) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		if strings.TrimSpace(string(required)) == "" {
+			return c.Next()
+		}
+		raw := c.Locals("wopi_permission")
+		current, _ := raw.(string)
+		if !wopiPermissionAllowed(current, string(required)) {
+			return apperrorsx.Write(c, apperrorsx.New(apperrorsx.ErrFileManagerWOPIPermissionDenied))
+		}
+		return c.Next()
+	}
+}
+
+func wopiPermissionAllowed(current, required string) bool {
+	switch strings.ToLower(strings.TrimSpace(required)) {
+	case string(service.WOPIPermissionRead):
+		return wopiPermissionRank(current) >= wopiPermissionRank(string(service.WOPIPermissionRead))
+	case string(service.WOPIPermissionWrite):
+		return wopiPermissionRank(current) >= wopiPermissionRank(string(service.WOPIPermissionWrite))
+	default:
+		return false
+	}
+}
+
+func wopiPermissionRank(v string) int {
+	switch strings.ToLower(strings.TrimSpace(v)) {
+	case string(service.WOPIPermissionRead):
+		return 1
+	case string(service.WOPIPermissionWrite):
+		return 2
+	default:
+		return 0
+	}
+}
diff --git a/internal/transport/http/middleware/wopi_middleware_test.go b/internal/transport/http/middleware/wopi_middleware_test.go
new file mode 100644
index 0000000..cd383b9
--- /dev/null
+++ b/internal/transport/http/middleware/wopi_middleware_test.go
@@ -0,0 +1,46 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/service"
+	"wucher/internal/shared/pkg/uuidv7"
+)
+
+func TestWOPIRequiredAcceptsTokenFromWOPISrc(t *testing.T) {
+	fileID := uuidv7.MustBytes()
+	userID := uuidv7.MustBytes()
+	wopiSvc := service.NewWOPIService(service.WOPIConfig{
+		TokenSecret:   "test-secret",
+		PublicBaseURL: "https://api.example.com",
+		TokenTTL:      30 * time.Minute,
+	})
+	token, _, err := wopiSvc.MintAccessToken(fileID, userID, nil, service.WOPIPermissionWrite)
+	if err != nil {
+		t.Fatalf("mint access token: %v", err)
+	}
+
+	app := fiber.New()
+	app.Use(WOPIRequired(wopiSvc))
+	app.Get("/wopi/files/:fileId", func(c *fiber.Ctx) error {
+		return c.SendStatus(http.StatusOK)
+	})
+
+	fileIDString, err := uuidv7.BytesToString(fileID)
+	if err != nil {
+		t.Fatalf("file id string: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodGet, "/wopi/files/"+fileIDString+"?WOPISrc=https%3A%2F%2Fapi.example.com%2Fwopi%2Ffiles%2F"+fileIDString+"%3Faccess_token%3D"+token, nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app test failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("unexpected status %d", resp.StatusCode)
+	}
+}
diff --git a/internal/transport/http/response/response.go b/internal/transport/http/response/response.go
new file mode 100644
index 0000000..fce07f8
--- /dev/null
+++ b/internal/transport/http/response/response.go
@@ -0,0 +1,61 @@
+package response
+
+import (
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/shared/pkg/apperrorsx"
+	"wucher/internal/transport/http/jsonapi"
+)
+
+var (
+	Write         = jsonapi.Write
+	WriteWithMeta = jsonapi.WriteWithMeta
+	WriteErrors   = writeErrors
+)
+
+func writeErrors(c *fiber.Ctx, status int, errs []jsonapi.ErrorObject) error {
+	if detail := collectHTTPErrorDetail(errs); detail != "" {
+		c.Locals(apperrorsx.ContextKeyHTTPErrorDetail, detail)
+	}
+	enriched := apperrorsx.EnrichErrorObjects(status, errs)
+	for i := range enriched {
+		if shouldPreserveDetail(status, errs[i]) {
+			continue
+		}
+		enriched[i].Detail = apperrorsx.PublicDetail(status)
+	}
+	return jsonapi.WriteErrors(c, status, enriched)
+}
+
+func shouldPreserveDetail(status int, err jsonapi.ErrorObject) bool {
+	if status != fiber.StatusUnprocessableEntity {
+		return false
+	}
+	lowerDetail := strings.ToLower(strings.TrimSpace(err.Detail))
+	lowerPointer := ""
+	if err.Source != nil {
+		lowerPointer = strings.ToLower(strings.TrimSpace(err.Source.Pointer))
+	}
+	return strings.Contains(lowerDetail, "shift_time.") ||
+		strings.Contains(lowerDetail, "latitude") ||
+		strings.Contains(lowerDetail, "longitude") ||
+		strings.Contains(lowerDetail, "coordinates") ||
+		strings.Contains(lowerDetail, "twilight") ||
+		strings.HasPrefix(lowerPointer, "/path/") ||
+		strings.Contains(lowerPointer, "operational_shift_times") ||
+		strings.Contains(lowerPointer, "latitude") ||
+		strings.Contains(lowerPointer, "longitude") ||
+		strings.Contains(lowerPointer, "shift_time")
+}
+
+func collectHTTPErrorDetail(errs []jsonapi.ErrorObject) string {
+	parts := make([]string, 0, len(errs))
+	for i := range errs {
+		if detail := strings.TrimSpace(errs[i].Detail); detail != "" {
+			parts = append(parts, detail)
+		}
+	}
+	return strings.Join(parts, "; ")
+}
diff --git a/internal/transport/http/response/response_test.go b/internal/transport/http/response/response_test.go
new file mode 100644
index 0000000..21650c1
--- /dev/null
+++ b/internal/transport/http/response/response_test.go
@@ -0,0 +1,35 @@
+package response
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"testing"
+
+	"github.com/gofiber/fiber/v2"
+
+	"wucher/internal/transport/http/jsonapi"
+)
+
+func TestWriteErrorsSanitizesDetail(t *testing.T) {
+	app := fiber.New()
+	app.Get("/", func(c *fiber.Ctx) error {
+		return WriteErrors(c, http.StatusUnprocessableEntity, []jsonapi.ErrorObject{{
+			Title:  "Validation error",
+			Detail: "raw validation detail",
+		}})
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/", nil)
+	resp, err := app.Test(req)
+	if err != nil {
+		t.Fatalf("app.Test: %v", err)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	if bytes.Contains(body, []byte("raw validation detail")) {
+		t.Fatalf("expected sanitized detail, got %s", string(body))
+	}
+	if !bytes.Contains(body, []byte(`"detail":"validation failed"`)) {
+		t.Fatalf("expected generic validation detail, got %s", string(body))
+	}
+}
diff --git a/internal/transport/http/validators/validator.go b/internal/transport/http/validators/validator.go
new file mode 100644
index 0000000..044ecad
--- /dev/null
+++ b/internal/transport/http/validators/validator.go
@@ -0,0 +1,95 @@
+package validators
+
+import (
+	"fmt"
+	"reflect"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/go-playground/validator/v10"
+
+	"wucher/internal/transport/http/jsonapi"
+)
+
+type Validator struct {
+	validate *validator.Validate
+}
+
+var hoursPattern = regexp.MustCompile(`^\d+(\.\d+)?$`)
+
+// validateHoursOrDate accepts an hours value (e.g. "1200" or "1200.5") or a calendar
+// date "YYYY-MM-DD". Anything else (e.g. "1200 FH") is rejected.
+func validateHoursOrDate(fl validator.FieldLevel) bool {
+	s := strings.TrimSpace(fl.Field().String())
+	if s == "" {
+		return true
+	}
+	if hoursPattern.MatchString(s) {
+		return true
+	}
+	_, err := time.Parse("2006-01-02", s)
+	return err == nil
+}
+
+func New() *Validator {
+	v := validator.New()
+	v.RegisterTagNameFunc(func(fld reflect.StructField) string {
+		name := fld.Tag.Get("json")
+		if name == "" {
+			return fld.Name
+		}
+		if idx := strings.Index(name, ","); idx != -1 {
+			return name[:idx]
+		}
+		return name
+	})
+	_ = v.RegisterValidation("hours_or_date", validateHoursOrDate)
+	return &Validator{validate: v}
+}
+
+func (v *Validator) ValidateStruct(s any) []jsonapi.ErrorObject {
+	if err := v.validate.Struct(s); err != nil {
+		if ve, ok := err.(validator.ValidationErrors); ok {
+			return toJSONAPIErrors(ve)
+		}
+		return []jsonapi.ErrorObject{{
+			Status: "400",
+			Title:  "Invalid request",
+			Detail: err.Error(),
+		}}
+	}
+	return nil
+}
+
+func toJSONAPIErrors(ve validator.ValidationErrors) []jsonapi.ErrorObject {
+	errs := make([]jsonapi.ErrorObject, 0, len(ve))
+	for _, fe := range ve {
+		field := fe.Field()
+		jsonPath := "/data/attributes/" + strings.ReplaceAll(field, ".", "/")
+		errs = append(errs, jsonapi.ErrorObject{
+			Status: "422",
+			Title:  "Validation error",
+			Detail: validationMessage(field, fe),
+			Source: &jsonapi.ErrorSource{Pointer: jsonPath},
+		})
+	}
+	return errs
+}
+
+func validationMessage(field string, fe validator.FieldError) string {
+	switch fe.Tag() {
+	case "required":
+		return field + " is required"
+	case "uuid":
+		return field + " must be a valid UUID"
+	case "email":
+		return field + " must be a valid email address"
+	case "hours_or_date":
+		return field + " must be flight hours (e.g. 1200) or a date in YYYY-MM-DD format"
+	case "oneof":
+		return field + " must be one of: " + fe.Param()
+	default:
+		return fmt.Sprintf("%s is invalid (%s)", field, fe.Tag())
+	}
+}
diff --git a/internal/transport/http/validators/validator_test.go b/internal/transport/http/validators/validator_test.go
new file mode 100644
index 0000000..abfe8d0
--- /dev/null
+++ b/internal/transport/http/validators/validator_test.go
@@ -0,0 +1,119 @@
+package validators
+
+import (
+	"strings"
+	"testing"
+)
+
+type validatorSample struct {
+	Email string `json:"email" validate:"required,email"`
+	Name  string `json:"name" validate:"required"`
+}
+
+type validatorTagNameSample struct {
+	NoTag string `validate:"required"`
+	Nick  string `json:"nick,omitempty" validate:"required"`
+}
+
+func TestNew(t *testing.T) {
+	v := New()
+	if v == nil || v.validate == nil {
+		t.Fatalf("expected validator instance")
+	}
+}
+
+type hoursOrDateSample struct {
+	Due string `json:"due" validate:"omitempty,hours_or_date"`
+}
+
+func TestHoursOrDateValidation(t *testing.T) {
+	cases := []struct {
+		in    string
+		valid bool
+	}{
+		{"", true},
+		{"1200", true},
+		{"1200.5", true},
+		{"2026-06-17", true},
+		{"1200 FH", false},
+		{"1200FH", false},
+		{"FH", false},
+		{"17-06-2026", false},
+		{"abc", false},
+		{"-5", false},
+	}
+	v := New()
+	for _, tc := range cases {
+		t.Run(tc.in, func(t *testing.T) {
+			errs := v.ValidateStruct(hoursOrDateSample{Due: tc.in})
+			if tc.valid && errs != nil {
+				t.Fatalf("%q should be valid, got %+v", tc.in, errs)
+			}
+			if !tc.valid && errs == nil {
+				t.Fatalf("%q should be rejected", tc.in)
+			}
+		})
+	}
+}
+
+func TestValidateStruct(t *testing.T) {
+	t.Run("valid struct", func(t *testing.T) {
+		v := New()
+		errs := v.ValidateStruct(validatorSample{Email: "user@example.com", Name: "John"})
+		if errs != nil {
+			t.Fatalf("expected nil errors, got %+v", errs)
+		}
+	})
+
+	t.Run("validation errors converted to jsonapi", func(t *testing.T) {
+		v := New()
+		errs := v.ValidateStruct(validatorSample{Email: "invalid", Name: ""})
+		if len(errs) < 2 {
+			t.Fatalf("expected at least 2 validation errors, got %+v", errs)
+		}
+		for _, e := range errs {
+			if e.Status != "422" {
+				t.Fatalf("expected status 422, got %q", e.Status)
+			}
+			if e.Title != "Validation error" {
+				t.Fatalf("expected validation title, got %q", e.Title)
+			}
+			if e.Source == nil || !strings.HasPrefix(e.Source.Pointer, "/data/attributes/") {
+				t.Fatalf("expected jsonapi pointer, got %+v", e.Source)
+			}
+		}
+	})
+
+	t.Run("non validation error", func(t *testing.T) {
+		v := New()
+		errs := v.ValidateStruct(123)
+		if len(errs) != 1 {
+			t.Fatalf("expected single error, got %+v", errs)
+		}
+		if errs[0].Status != "400" || errs[0].Title != "Invalid request" {
+			t.Fatalf("unexpected error object: %+v", errs[0])
+		}
+	})
+
+	t.Run("tag name resolver handles empty and comma json tags", func(t *testing.T) {
+		v := New()
+		errs := v.ValidateStruct(validatorTagNameSample{})
+		if len(errs) != 2 {
+			t.Fatalf("expected 2 validation errors, got %+v", errs)
+		}
+
+		var seenNoTag bool
+		var seenNick bool
+		for _, e := range errs {
+			if strings.Contains(e.Detail, "NoTag is required") && e.Source != nil && e.Source.Pointer == "/data/attributes/NoTag" {
+				seenNoTag = true
+			}
+			if strings.Contains(e.Detail, "nick is required") && e.Source != nil && e.Source.Pointer == "/data/attributes/nick" {
+				seenNick = true
+			}
+		}
+		if !seenNoTag || !seenNick {
+			t.Fatalf("expected errors for NoTag and nick fields, got %+v", errs)
+		}
+	})
+}
diff --git a/migrations/20260313_contacts_profiles.sql b/migrations/20260313_contacts_profiles.sql
new file mode 100644
index 0000000..cb82af7
--- /dev/null
+++ b/migrations/20260313_contacts_profiles.sql
@@ -0,0 +1,150 @@
+-- +goose Up
+-- HEMS contacts/users module schema extension
+
+ALTER TABLE roles
+  ADD COLUMN IF NOT EXISTS code VARCHAR(64) NULL,
+  ADD UNIQUE KEY IF NOT EXISTS uq_roles_code (code);
+
+ALTER TABLE users
+  ADD COLUMN IF NOT EXISTS username VARCHAR(100) NULL,
+  ADD UNIQUE KEY IF NOT EXISTS uq_users_username (username),
+  ADD COLUMN IF NOT EXISTS is_active TINYINT(1) NOT NULL DEFAULT 1;
+
+CREATE TABLE IF NOT EXISTS pilot_profiles (
+  user_id BINARY(16) NOT NULL,
+  pilot_category ENUM('regular','freelance','dry_lease') NOT NULL,
+  short_name VARCHAR(120) NULL,
+  license_no VARCHAR(120) NULL,
+  license_issued_at DATETIME NULL,
+  license_expired_at DATETIME NULL,
+  technician_license_no VARCHAR(120) NULL,
+  has_ifr_qualification TINYINT(1) NOT NULL DEFAULT 0,
+  is_chief_pilot TINYINT(1) NOT NULL DEFAULT 0,
+  is_dul TINYINT(1) NOT NULL DEFAULT 0,
+  total_flight_minutes INT NOT NULL DEFAULT 0,
+  responsible_pilot_minutes INT NOT NULL DEFAULT 0,
+  second_pilot_minutes INT NOT NULL DEFAULT 0,
+  double_command_minutes INT NOT NULL DEFAULT 0,
+  flight_instructor_minutes INT NOT NULL DEFAULT 0,
+  night_flight_minutes INT NOT NULL DEFAULT 0,
+  ifr_flight_minutes INT NOT NULL DEFAULT 0,
+  location VARCHAR(255) NULL,
+  postcode VARCHAR(32) NULL,
+  street_line VARCHAR(255) NULL,
+  weight_kg DECIMAL(8,2) NULL,
+  photo_file_id VARCHAR(255) NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  PRIMARY KEY (user_id),
+  KEY idx_pilot_profiles_category (pilot_category),
+  KEY idx_pilot_profiles_license (license_no),
+  CONSTRAINT fk_pilot_profiles_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ON UPDATE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS doctor_profiles (
+  user_id BINARY(16) NOT NULL,
+  short_name VARCHAR(120) NULL,
+  medical_license_no VARCHAR(120) NULL,
+  license_issued_at DATETIME NULL,
+  license_expired_at DATETIME NULL,
+  specialization VARCHAR(120) NULL,
+  sub_specialization VARCHAR(120) NULL,
+  is_chief_physician TINYINT(1) NOT NULL DEFAULT 0,
+  location VARCHAR(255) NULL,
+  postcode VARCHAR(32) NULL,
+  street_line VARCHAR(255) NULL,
+  photo_file_id VARCHAR(255) NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  PRIMARY KEY (user_id),
+  KEY idx_doctor_profiles_medical_license (medical_license_no),
+  CONSTRAINT fk_doctor_profiles_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ON UPDATE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS air_rescuer_profiles (
+  user_id BINARY(16) NOT NULL,
+  short_name VARCHAR(120) NULL,
+  is_chief_physician_in_charge TINYINT(1) NOT NULL DEFAULT 0,
+  responsible_flight_rescuer TINYINT(1) NOT NULL DEFAULT 0,
+  location VARCHAR(255) NULL,
+  postcode VARCHAR(32) NULL,
+  street_line VARCHAR(255) NULL,
+  photo_file_id VARCHAR(255) NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  PRIMARY KEY (user_id),
+  CONSTRAINT fk_air_rescuer_profiles_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ON UPDATE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS technician_profiles (
+  user_id BINARY(16) NOT NULL,
+  short_name VARCHAR(120) NULL,
+  license_no VARCHAR(120) NULL,
+  is_chief_technician TINYINT(1) NOT NULL DEFAULT 0,
+  is_responsible_complaints TINYINT(1) NOT NULL DEFAULT 0,
+  location VARCHAR(255) NULL,
+  postcode VARCHAR(32) NULL,
+  street_line VARCHAR(255) NULL,
+  photo_file_id VARCHAR(255) NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  PRIMARY KEY (user_id),
+  KEY idx_technician_profiles_license (license_no),
+  CONSTRAINT fk_technician_profiles_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ON UPDATE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS flight_assistant_profiles (
+  user_id BINARY(16) NOT NULL,
+  short_name VARCHAR(120) NULL,
+  location VARCHAR(255) NULL,
+  postcode VARCHAR(32) NULL,
+  street_line VARCHAR(255) NULL,
+  photo_file_id VARCHAR(255) NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  PRIMARY KEY (user_id),
+  CONSTRAINT fk_flight_assistant_profiles_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ON UPDATE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS staff_profiles (
+  user_id BINARY(16) NOT NULL,
+  short_name VARCHAR(120) NULL,
+  role_label VARCHAR(120) NULL,
+  location VARCHAR(255) NULL,
+  postcode VARCHAR(32) NULL,
+  street_line VARCHAR(255) NULL,
+  photo_file_id VARCHAR(255) NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  PRIMARY KEY (user_id),
+  CONSTRAINT fk_staff_profiles_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ON UPDATE CASCADE
+);
+
+-- +goose Down
+DROP TABLE IF EXISTS staff_profiles;
+DROP TABLE IF EXISTS flight_assistant_profiles;
+DROP TABLE IF EXISTS technician_profiles;
+DROP TABLE IF EXISTS air_rescuer_profiles;
+DROP TABLE IF EXISTS doctor_profiles;
+DROP TABLE IF EXISTS pilot_profiles;
+
+ALTER TABLE users
+  DROP COLUMN IF EXISTS is_active,
+  DROP INDEX IF EXISTS uq_users_username,
+  DROP COLUMN IF EXISTS username;
+
+ALTER TABLE roles
+  DROP INDEX IF EXISTS uq_roles_code,
+  DROP COLUMN IF EXISTS code;
diff --git a/migrations/20260326_move_responsible_flight_rescuer_to_air_rescuer_profiles.sql b/migrations/20260326_move_responsible_flight_rescuer_to_air_rescuer_profiles.sql
new file mode 100644
index 0000000..ca0e7cc
--- /dev/null
+++ b/migrations/20260326_move_responsible_flight_rescuer_to_air_rescuer_profiles.sql
@@ -0,0 +1,21 @@
+-- +goose Up
+ALTER TABLE air_rescuer_profiles
+  ADD COLUMN IF NOT EXISTS responsible_flight_rescuer TINYINT(1) NOT NULL DEFAULT 0 AFTER is_chief_physician_in_charge;
+
+UPDATE air_rescuer_profiles arp
+JOIN pilot_profiles pp ON pp.user_id = arp.user_id
+SET arp.responsible_flight_rescuer = pp.responsible_flight_rescuer;
+
+ALTER TABLE pilot_profiles
+  DROP COLUMN IF EXISTS responsible_flight_rescuer;
+
+-- +goose Down
+ALTER TABLE pilot_profiles
+  ADD COLUMN IF NOT EXISTS responsible_flight_rescuer TINYINT(1) NOT NULL DEFAULT 0 AFTER is_dul;
+
+UPDATE pilot_profiles pp
+JOIN air_rescuer_profiles arp ON arp.user_id = pp.user_id
+SET pp.responsible_flight_rescuer = arp.responsible_flight_rescuer;
+
+ALTER TABLE air_rescuer_profiles
+  DROP COLUMN IF EXISTS responsible_flight_rescuer;
diff --git a/migrations/20260331_file_manager_tables.sql b/migrations/20260331_file_manager_tables.sql
new file mode 100644
index 0000000..a72140e
--- /dev/null
+++ b/migrations/20260331_file_manager_tables.sql
@@ -0,0 +1,66 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS file_folders (
+  id BINARY(16) NOT NULL,
+  parent_id BINARY(16) NULL,
+  name VARCHAR(128) NOT NULL,
+  name_normalized VARCHAR(128) NOT NULL,
+  depth SMALLINT UNSIGNED NOT NULL DEFAULT 0,
+  path_cache VARCHAR(2048) NULL,
+  name_slot CHAR(36) NOT NULL DEFAULT 'live',
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME(6) NULL,
+  deleted_by BINARY(16) NULL,
+  purge_at DATETIME(6) NULL,
+  PRIMARY KEY (id),
+  CONSTRAINT fk_file_folders_parent
+    FOREIGN KEY (parent_id) REFERENCES file_folders(id)
+    ON UPDATE CASCADE
+    ON DELETE RESTRICT,
+  UNIQUE KEY uq_file_folders_parent_name_slot (parent_id, name_normalized, name_slot),
+  KEY idx_file_folders_parent_active (parent_id, deleted_at),
+  KEY idx_file_folders_deleted_at (deleted_at),
+  KEY idx_file_folders_purge_at (purge_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE IF NOT EXISTS file_files (
+  id BINARY(16) NOT NULL,
+  folder_id BINARY(16) NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  name_normalized VARCHAR(255) NOT NULL,
+  extension VARCHAR(32) NULL,
+  size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0,
+  mime_type VARCHAR(255) NOT NULL,
+  bucket VARCHAR(128) NOT NULL,
+  object_key VARCHAR(512) NOT NULL,
+  object_version VARCHAR(128) NULL,
+  etag VARCHAR(128) NULL,
+  checksum_sha256 CHAR(64) NULL,
+  status VARCHAR(32) NOT NULL DEFAULT 'pending',
+  upload_error TEXT NULL,
+  name_slot CHAR(36) NOT NULL DEFAULT 'live',
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME(6) NULL,
+  deleted_by BINARY(16) NULL,
+  trashed_at DATETIME(6) NULL,
+  purge_at DATETIME(6) NULL,
+  PRIMARY KEY (id),
+  CONSTRAINT fk_file_files_folder
+    FOREIGN KEY (folder_id) REFERENCES file_folders(id)
+    ON UPDATE CASCADE
+    ON DELETE RESTRICT,
+  UNIQUE KEY uq_file_files_object_key (object_key),
+  UNIQUE KEY uq_file_files_folder_name_slot (folder_id, name_normalized, name_slot),
+  KEY idx_file_files_folder_active (folder_id, deleted_at),
+  KEY idx_file_files_status_updated (status, updated_at),
+  KEY idx_file_files_purge_at (purge_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS file_files;
+DROP TABLE IF EXISTS file_folders;
diff --git a/migrations/20260403_file_manager_file_lifecycle_phase1.sql b/migrations/20260403_file_manager_file_lifecycle_phase1.sql
new file mode 100644
index 0000000..fd40087
--- /dev/null
+++ b/migrations/20260403_file_manager_file_lifecycle_phase1.sql
@@ -0,0 +1,42 @@
+-- +goose Up
+ALTER TABLE file_files
+  MODIFY COLUMN status VARCHAR(32) NOT NULL DEFAULT 'uploaded',
+  ADD COLUMN processing_started_at DATETIME(6) NULL AFTER status,
+  ADD COLUMN processed_at DATETIME(6) NULL AFTER processing_started_at,
+  ADD COLUMN validated_at DATETIME(6) NULL AFTER processed_at,
+  ADD COLUMN failed_at DATETIME(6) NULL AFTER validated_at,
+  ADD COLUMN failure_reason TEXT NULL AFTER failed_at;
+
+UPDATE file_files
+SET status = 'validated',
+    processed_at = COALESCE(processed_at, updated_at),
+    validated_at = COALESCE(validated_at, updated_at)
+WHERE status = 'pending';
+
+UPDATE file_files
+SET status = 'processing',
+    processing_started_at = COALESCE(processing_started_at, updated_at)
+WHERE status = 'uploading';
+
+UPDATE file_files
+SET failure_reason = NULLIF(TRIM(upload_error), '')
+WHERE (failure_reason IS NULL OR failure_reason = '')
+  AND upload_error IS NOT NULL
+  AND TRIM(upload_error) <> '';
+
+-- +goose Down
+UPDATE file_files
+SET status = 'pending'
+WHERE status IN ('uploaded', 'validated');
+
+UPDATE file_files
+SET status = 'uploading'
+WHERE status = 'processing';
+
+ALTER TABLE file_files
+  DROP COLUMN failure_reason,
+  DROP COLUMN failed_at,
+  DROP COLUMN validated_at,
+  DROP COLUMN processed_at,
+  DROP COLUMN processing_started_at,
+  MODIFY COLUMN status VARCHAR(32) NOT NULL DEFAULT 'pending';
diff --git a/migrations/20260405_file_processing_outbox.sql b/migrations/20260405_file_processing_outbox.sql
new file mode 100644
index 0000000..4382a8e
--- /dev/null
+++ b/migrations/20260405_file_processing_outbox.sql
@@ -0,0 +1,33 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS file_processing_outbox_messages (
+  id BINARY(16) NOT NULL,
+  message_id VARCHAR(64) NOT NULL,
+  kind VARCHAR(64) NOT NULL,
+  job_type VARCHAR(64) NOT NULL,
+  body LONGBLOB NOT NULL,
+  attributes LONGBLOB NULL,
+  message_group_id VARCHAR(128) NULL,
+  deduplication_id VARCHAR(128) NULL,
+  status VARCHAR(32) NOT NULL DEFAULT 'pending',
+  attempts INT NOT NULL DEFAULT 0,
+  available_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  locked_at DATETIME(6) NULL,
+  locked_by VARCHAR(64) NULL,
+  published_at DATETIME(6) NULL,
+  last_error TEXT NULL,
+  correlation_id VARCHAR(64) NULL,
+  trace_id VARCHAR(64) NULL,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  PRIMARY KEY (id),
+  UNIQUE KEY uq_file_processing_outbox_message_id (message_id),
+  KEY idx_file_processing_outbox_status_available (status, available_at),
+  KEY idx_file_processing_outbox_locked_at (locked_at),
+  KEY idx_file_processing_outbox_kind (kind),
+  KEY idx_file_processing_outbox_job_type (job_type),
+  KEY idx_file_processing_outbox_correlation (correlation_id),
+  KEY idx_file_processing_outbox_trace (trace_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS file_processing_outbox_messages;
diff --git a/migrations/20260406_file_status_realtime_events.sql b/migrations/20260406_file_status_realtime_events.sql
new file mode 100644
index 0000000..3e6c9b1
--- /dev/null
+++ b/migrations/20260406_file_status_realtime_events.sql
@@ -0,0 +1,22 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS file_status_realtime_events (
+  id BINARY(16) NOT NULL,
+  file_id BINARY(16) NOT NULL,
+  user_id BINARY(16) NOT NULL,
+  status VARCHAR(32) NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  failure_reason TEXT NULL,
+  occurred_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  delivered_at DATETIME(6) NULL,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  PRIMARY KEY (id),
+  KEY idx_file_status_realtime_events_file (file_id),
+  KEY idx_file_status_realtime_events_user (user_id),
+  KEY idx_file_status_realtime_events_status (status),
+  KEY idx_file_status_realtime_events_occurred (occurred_at),
+  KEY idx_file_status_realtime_events_delivered (delivered_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS file_status_realtime_events;
diff --git a/migrations/20260406_file_upload_intents.sql b/migrations/20260406_file_upload_intents.sql
new file mode 100644
index 0000000..f2bb9eb
--- /dev/null
+++ b/migrations/20260406_file_upload_intents.sql
@@ -0,0 +1,27 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS file_upload_intents (
+  id BINARY(16) NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  name_normalized VARCHAR(255) NOT NULL,
+  extension VARCHAR(32) NULL,
+  size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0,
+  mime_type VARCHAR(255) NOT NULL,
+  bucket VARCHAR(128) NOT NULL,
+  object_key VARCHAR(512) NOT NULL,
+  status VARCHAR(32) NOT NULL DEFAULT 'pending',
+  expires_at DATETIME(6) NOT NULL,
+  completed_at DATETIME(6) NULL,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  updated_by BINARY(16) NULL,
+  PRIMARY KEY (id),
+  UNIQUE KEY uq_file_upload_intents_object_key (object_key),
+  KEY idx_file_upload_intents_status (status),
+  KEY idx_file_upload_intents_expires_at (expires_at),
+  KEY idx_file_upload_intents_completed_at (completed_at),
+  KEY idx_file_upload_intents_created_by (created_by)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS file_upload_intents;
diff --git a/migrations/20260406_user_roles.sql b/migrations/20260406_user_roles.sql
new file mode 100644
index 0000000..d8c82c4
--- /dev/null
+++ b/migrations/20260406_user_roles.sql
@@ -0,0 +1,35 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS user_roles (
+  id BINARY(16) NOT NULL,
+  user_id BINARY(16) NOT NULL,
+  role_id BINARY(16) NOT NULL,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  updated_by BINARY(16) NULL,
+  PRIMARY KEY (id),
+  UNIQUE KEY ux_user_role (user_id, role_id),
+  KEY idx_user_roles_user_id (user_id),
+  KEY idx_user_roles_role_id (role_id),
+  CONSTRAINT fk_user_roles_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ON UPDATE CASCADE,
+  CONSTRAINT fk_user_roles_role FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE ON UPDATE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+INSERT INTO user_roles (id, user_id, role_id, created_at, updated_at)
+SELECT
+  UNHEX(REPLACE(UUID(), '-', '')),
+  users.id,
+  users.role_id,
+  CURRENT_TIMESTAMP(6),
+  CURRENT_TIMESTAMP(6)
+FROM users
+WHERE users.role_id IS NOT NULL
+  AND NOT EXISTS (
+    SELECT 1
+    FROM user_roles
+    WHERE user_roles.user_id = users.id
+      AND user_roles.role_id = users.role_id
+  );
+
+-- +goose Down
+DROP TABLE IF EXISTS user_roles;
diff --git a/migrations/20260407_enhance_bases_shift_attachment_soft_delete.sql b/migrations/20260407_enhance_bases_shift_attachment_soft_delete.sql
new file mode 100644
index 0000000..495a63c
--- /dev/null
+++ b/migrations/20260407_enhance_bases_shift_attachment_soft_delete.sql
@@ -0,0 +1,265 @@
+-- +goose Up
+SET @col_default_shift_start_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'default_shift_start'
+);
+SET @add_default_shift_start_sql := IF(
+  @col_default_shift_start_exists = 0,
+  'ALTER TABLE bases ADD COLUMN default_shift_start TIME NULL AFTER leg_time',
+  'SELECT 1'
+);
+PREPARE stmt_add_default_shift_start FROM @add_default_shift_start_sql;
+EXECUTE stmt_add_default_shift_start;
+DEALLOCATE PREPARE stmt_add_default_shift_start;
+
+SET @col_default_shift_end_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'default_shift_end'
+);
+SET @add_default_shift_end_sql := IF(
+  @col_default_shift_end_exists = 0,
+  'ALTER TABLE bases ADD COLUMN default_shift_end TIME NULL AFTER default_shift_start',
+  'SELECT 1'
+);
+PREPARE stmt_add_default_shift_end FROM @add_default_shift_end_sql;
+EXECUTE stmt_add_default_shift_end;
+DEALLOCATE PREPARE stmt_add_default_shift_end;
+
+SET @col_foto_attachment_id_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'foto_attachment_id'
+);
+SET @add_foto_attachment_id_sql := IF(
+  @col_foto_attachment_id_exists = 0,
+  'ALTER TABLE bases ADD COLUMN foto_attachment_id BINARY(16) NULL AFTER foto',
+  'SELECT 1'
+);
+PREPARE stmt_add_foto_attachment_id FROM @add_foto_attachment_id_sql;
+EXECUTE stmt_add_foto_attachment_id;
+DEALLOCATE PREPARE stmt_add_foto_attachment_id;
+
+SET @col_deleted_at_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'deleted_at'
+);
+SET @add_deleted_at_sql := IF(
+  @col_deleted_at_exists = 0,
+  'ALTER TABLE bases ADD COLUMN deleted_at DATETIME(3) NULL AFTER updated_at',
+  'SELECT 1'
+);
+PREPARE stmt_add_deleted_at FROM @add_deleted_at_sql;
+EXECUTE stmt_add_deleted_at;
+DEALLOCATE PREPARE stmt_add_deleted_at;
+
+SET @col_deleted_by_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'deleted_by'
+);
+SET @add_deleted_by_sql := IF(
+  @col_deleted_by_exists = 0,
+  'ALTER TABLE bases ADD COLUMN deleted_by BINARY(16) NULL AFTER deleted_at',
+  'SELECT 1'
+);
+PREPARE stmt_add_deleted_by FROM @add_deleted_by_sql;
+EXECUTE stmt_add_deleted_by;
+DEALLOCATE PREPARE stmt_add_deleted_by;
+
+SET @idx_bases_deleted_at_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.statistics
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND index_name = 'idx_bases_deleted_at'
+);
+SET @add_idx_bases_deleted_at_sql := IF(
+  @idx_bases_deleted_at_exists = 0,
+  'ALTER TABLE bases ADD INDEX idx_bases_deleted_at (deleted_at)',
+  'SELECT 1'
+);
+PREPARE stmt_add_idx_bases_deleted_at FROM @add_idx_bases_deleted_at_sql;
+EXECUTE stmt_add_idx_bases_deleted_at;
+DEALLOCATE PREPARE stmt_add_idx_bases_deleted_at;
+
+SET @idx_bases_foto_attachment_id_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.statistics
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND index_name = 'idx_bases_foto_attachment_id'
+);
+SET @add_idx_bases_foto_attachment_id_sql := IF(
+  @idx_bases_foto_attachment_id_exists = 0,
+  'ALTER TABLE bases ADD INDEX idx_bases_foto_attachment_id (foto_attachment_id)',
+  'SELECT 1'
+);
+PREPARE stmt_add_idx_bases_foto_attachment_id FROM @add_idx_bases_foto_attachment_id_sql;
+EXECUTE stmt_add_idx_bases_foto_attachment_id;
+DEALLOCATE PREPARE stmt_add_idx_bases_foto_attachment_id;
+
+SET @attachments_table_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.tables
+  WHERE table_schema = DATABASE()
+    AND table_name = 'attachments'
+);
+SET @fk_bases_foto_attachment_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.table_constraints
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND constraint_name = 'fk_bases_foto_attachment'
+    AND constraint_type = 'FOREIGN KEY'
+);
+SET @add_fk_bases_foto_attachment_sql := IF(
+  @attachments_table_exists > 0 AND @fk_bases_foto_attachment_exists = 0,
+  'ALTER TABLE bases ADD CONSTRAINT fk_bases_foto_attachment FOREIGN KEY (foto_attachment_id) REFERENCES attachments(id) ON UPDATE CASCADE ON DELETE SET NULL',
+  'SELECT 1'
+);
+PREPARE stmt_add_fk_bases_foto_attachment FROM @add_fk_bases_foto_attachment_sql;
+EXECUTE stmt_add_fk_bases_foto_attachment;
+DEALLOCATE PREPARE stmt_add_fk_bases_foto_attachment;
+
+-- +goose Down
+SET @fk_bases_foto_attachment_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.table_constraints
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND constraint_name = 'fk_bases_foto_attachment'
+    AND constraint_type = 'FOREIGN KEY'
+);
+SET @drop_fk_bases_foto_attachment_sql := IF(
+  @fk_bases_foto_attachment_exists > 0,
+  'ALTER TABLE bases DROP FOREIGN KEY fk_bases_foto_attachment',
+  'SELECT 1'
+);
+PREPARE stmt_drop_fk_bases_foto_attachment FROM @drop_fk_bases_foto_attachment_sql;
+EXECUTE stmt_drop_fk_bases_foto_attachment;
+DEALLOCATE PREPARE stmt_drop_fk_bases_foto_attachment;
+
+SET @idx_bases_foto_attachment_id_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.statistics
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND index_name = 'idx_bases_foto_attachment_id'
+);
+SET @drop_idx_bases_foto_attachment_id_sql := IF(
+  @idx_bases_foto_attachment_id_exists > 0,
+  'ALTER TABLE bases DROP INDEX idx_bases_foto_attachment_id',
+  'SELECT 1'
+);
+PREPARE stmt_drop_idx_bases_foto_attachment_id FROM @drop_idx_bases_foto_attachment_id_sql;
+EXECUTE stmt_drop_idx_bases_foto_attachment_id;
+DEALLOCATE PREPARE stmt_drop_idx_bases_foto_attachment_id;
+
+SET @idx_bases_deleted_at_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.statistics
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND index_name = 'idx_bases_deleted_at'
+);
+SET @drop_idx_bases_deleted_at_sql := IF(
+  @idx_bases_deleted_at_exists > 0,
+  'ALTER TABLE bases DROP INDEX idx_bases_deleted_at',
+  'SELECT 1'
+);
+PREPARE stmt_drop_idx_bases_deleted_at FROM @drop_idx_bases_deleted_at_sql;
+EXECUTE stmt_drop_idx_bases_deleted_at;
+DEALLOCATE PREPARE stmt_drop_idx_bases_deleted_at;
+
+SET @col_deleted_by_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'deleted_by'
+);
+SET @drop_deleted_by_sql := IF(
+  @col_deleted_by_exists > 0,
+  'ALTER TABLE bases DROP COLUMN deleted_by',
+  'SELECT 1'
+);
+PREPARE stmt_drop_deleted_by FROM @drop_deleted_by_sql;
+EXECUTE stmt_drop_deleted_by;
+DEALLOCATE PREPARE stmt_drop_deleted_by;
+
+SET @col_deleted_at_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'deleted_at'
+);
+SET @drop_deleted_at_sql := IF(
+  @col_deleted_at_exists > 0,
+  'ALTER TABLE bases DROP COLUMN deleted_at',
+  'SELECT 1'
+);
+PREPARE stmt_drop_deleted_at FROM @drop_deleted_at_sql;
+EXECUTE stmt_drop_deleted_at;
+DEALLOCATE PREPARE stmt_drop_deleted_at;
+
+SET @col_foto_attachment_id_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'foto_attachment_id'
+);
+SET @drop_foto_attachment_id_sql := IF(
+  @col_foto_attachment_id_exists > 0,
+  'ALTER TABLE bases DROP COLUMN foto_attachment_id',
+  'SELECT 1'
+);
+PREPARE stmt_drop_foto_attachment_id FROM @drop_foto_attachment_id_sql;
+EXECUTE stmt_drop_foto_attachment_id;
+DEALLOCATE PREPARE stmt_drop_foto_attachment_id;
+
+SET @col_default_shift_end_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'default_shift_end'
+);
+SET @drop_default_shift_end_sql := IF(
+  @col_default_shift_end_exists > 0,
+  'ALTER TABLE bases DROP COLUMN default_shift_end',
+  'SELECT 1'
+);
+PREPARE stmt_drop_default_shift_end FROM @drop_default_shift_end_sql;
+EXECUTE stmt_drop_default_shift_end;
+DEALLOCATE PREPARE stmt_drop_default_shift_end;
+
+SET @col_default_shift_start_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'default_shift_start'
+);
+SET @drop_default_shift_start_sql := IF(
+  @col_default_shift_start_exists > 0,
+  'ALTER TABLE bases DROP COLUMN default_shift_start',
+  'SELECT 1'
+);
+PREPARE stmt_drop_default_shift_start FROM @drop_default_shift_start_sql;
+EXECUTE stmt_drop_default_shift_start;
+DEALLOCATE PREPARE stmt_drop_default_shift_start;
diff --git a/migrations/20260407_permissions_requires_pin.sql b/migrations/20260407_permissions_requires_pin.sql
new file mode 100644
index 0000000..e8d5c08
--- /dev/null
+++ b/migrations/20260407_permissions_requires_pin.sql
@@ -0,0 +1,81 @@
+-- +goose Up
+ALTER TABLE permissions
+  ADD COLUMN requires_pin TINYINT(1) NOT NULL DEFAULT 0 AFTER description;
+
+UPDATE permissions
+SET requires_pin = 1
+WHERE (updated_by IS NULL OR LENGTH(updated_by) = 0)
+  AND `key` IN (
+    'user.create',
+    'user.update',
+    'user.delete',
+    'role.create',
+    'role.update',
+    'role.delete',
+    'role.permission.assign',
+    'role.permission.remove',
+    'role.permission.update',
+    'helicopter.create',
+    'helicopter.report.generate',
+    'helicopter.update',
+    'helicopter.delete',
+    'facility.create',
+    'facility.update',
+    'facility.delete',
+    'base.create',
+    'base.update',
+    'base.delete',
+    'hems_base.create',
+    'hems_base.update',
+    'hems_base.delete',
+    'bmd.create',
+    'bmd.update',
+    'bmd.delete',
+    'medicine.create',
+    'medicine.update',
+    'medicine.delete',
+    'vocation.create',
+    'vocation.update',
+    'vocation.delete',
+    'opc.create',
+    'opc.update',
+    'opc.delete',
+    'forces_present.create',
+    'forces_present.update',
+    'forces_present.delete',
+    'hospital.create',
+    'hospital.update',
+    'hospital.delete',
+    'health_insurance_companies.create',
+    'health_insurance_companies.update',
+    'health_insurance_companies.delete',
+    'federal_state.create',
+    'federal_state.update',
+    'federal_state.delete',
+    'nationality.create',
+    'nationality.update',
+    'nationality.delete',
+    'icao.create',
+    'icao.update',
+    'icao.delete',
+    'land.create',
+    'land.update',
+    'land.delete',
+    'master_settings.create',
+    'master_settings.update',
+    'master_settings.delete',
+    'file_manager.create',
+    'file_manager.update',
+    'file_manager.delete',
+    'hems_duty_roster.create',
+    'hems_duty_roster.update',
+    'hems_duty_roster.delete',
+    'air_rescuer_checklist.create',
+    'air_rescuer_checklist.update',
+    'air_rescuer_checklist.delete',
+    'audit.read'
+  );
+
+-- +goose Down
+ALTER TABLE permissions
+  DROP COLUMN requires_pin;
diff --git a/migrations/20260408_crew_related_tables.sql b/migrations/20260408_crew_related_tables.sql
new file mode 100644
index 0000000..1e13b13
--- /dev/null
+++ b/migrations/20260408_crew_related_tables.sql
@@ -0,0 +1,85 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS crews (
+    id BINARY(16) PRIMARY KEY,
+    crew_type VARCHAR(32) NOT NULL,
+    user_id BINARY(16) NOT NULL,
+    start_date DATETIME NOT NULL,
+    end_date DATETIME NOT NULL,
+    created_at DATETIME NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME NULL,
+    updated_by BINARY(16) NULL,
+    deleted_at DATETIME NULL,
+    deleted_by BINARY(16) NULL,
+    CONSTRAINT chk_crews_crew_type CHECK (crew_type IN ('main', 'additional')),
+    CONSTRAINT chk_crews_date_range CHECK (start_date <= end_date),
+    CONSTRAINT fk_crews_user FOREIGN KEY (user_id) REFERENCES users(id)
+);
+
+CREATE INDEX idx_crews_user_id ON crews(user_id);
+CREATE INDEX idx_crews_crew_type ON crews(crew_type);
+CREATE INDEX idx_crews_start_date ON crews(start_date);
+CREATE INDEX idx_crews_end_date ON crews(end_date);
+
+CREATE TABLE IF NOT EXISTS roster_crews (
+    id BINARY(16) PRIMARY KEY,
+    roster_id BINARY(16) NOT NULL,
+    crew_id BINARY(16) NOT NULL,
+    confirm_at DATETIME NULL,
+    role VARCHAR(32) NOT NULL,
+    created_at DATETIME NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME NULL,
+    updated_by BINARY(16) NULL,
+    deleted_at DATETIME NULL,
+    deleted_by BINARY(16) NULL,
+    CONSTRAINT chk_roster_crews_role CHECK (role IN ('Pilot', 'Copilot', 'Doctor', 'AirRescuer')),
+    CONSTRAINT fk_roster_crews_roster FOREIGN KEY (roster_id) REFERENCES hems_duty_rosters(id),
+    CONSTRAINT fk_roster_crews_crew FOREIGN KEY (crew_id) REFERENCES crews(id)
+);
+
+CREATE INDEX idx_roster_crews_roster_id ON roster_crews(roster_id);
+CREATE INDEX idx_roster_crews_role ON roster_crews(role);
+CREATE UNIQUE INDEX idx_roster_crews_roster_crew ON roster_crews(roster_id, crew_id);
+
+CREATE TABLE IF NOT EXISTS duty_roster_other_persons (
+    id BINARY(16) PRIMARY KEY,
+    roster_id BINARY(16) NOT NULL,
+    name VARCHAR(191) NOT NULL,
+    mobile_phone VARCHAR(64) NULL,
+    email VARCHAR(191) NULL,
+    created_at DATETIME NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME NULL,
+    updated_by BINARY(16) NULL,
+    deleted_at DATETIME NULL,
+    deleted_by BINARY(16) NULL,
+    CONSTRAINT fk_duty_roster_other_persons_roster FOREIGN KEY (roster_id) REFERENCES hems_duty_rosters(id)
+);
+
+CREATE INDEX idx_duty_roster_other_persons_roster_id ON duty_roster_other_persons(roster_id);
+
+CREATE TABLE IF NOT EXISTS duty_roster_crew_pilot_additionals (
+    id BINARY(16) PRIMARY KEY,
+    crew_id BINARY(16) NOT NULL,
+    flight_instructor TINYINT(1) NOT NULL DEFAULT 0,
+    line_checker TINYINT(1) NOT NULL DEFAULT 0,
+    supervisor TINYINT(1) NOT NULL DEFAULT 0,
+    examiner TINYINT(1) NOT NULL DEFAULT 0,
+    copilot TINYINT(1) NOT NULL DEFAULT 0,
+    created_at DATETIME NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME NULL,
+    updated_by BINARY(16) NULL,
+    deleted_at DATETIME NULL,
+    deleted_by BINARY(16) NULL,
+    CONSTRAINT fk_duty_roster_crew_pilot_additionals_crew FOREIGN KEY (crew_id) REFERENCES crews(id)
+);
+
+CREATE UNIQUE INDEX idx_duty_roster_crew_pilot_additionals_crew_id ON duty_roster_crew_pilot_additionals(crew_id);
+
+-- +goose Down
+DROP TABLE IF EXISTS duty_roster_crew_pilot_additionals;
+DROP TABLE IF EXISTS duty_roster_other_persons;
+DROP TABLE IF EXISTS roster_crews;
+DROP TABLE IF EXISTS crews;
diff --git a/migrations/20260408_file_manager_attachments.sql b/migrations/20260408_file_manager_attachments.sql
new file mode 100644
index 0000000..5e6da5c
--- /dev/null
+++ b/migrations/20260408_file_manager_attachments.sql
@@ -0,0 +1,25 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS attachments (
+  id BINARY(16) NOT NULL,
+  file_id BINARY(16) NOT NULL,
+  ref_type VARCHAR(64) NOT NULL,
+  ref_id VARCHAR(191) NOT NULL,
+  category VARCHAR(64) NULL,
+  sort_order INT NOT NULL DEFAULT 0,
+  is_primary TINYINT(1) NOT NULL DEFAULT 0,
+  attached_by BINARY(16) NULL,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  PRIMARY KEY (id),
+  CONSTRAINT fk_attachments_file
+    FOREIGN KEY (file_id) REFERENCES file_files(id)
+    ON UPDATE CASCADE
+    ON DELETE CASCADE,
+  UNIQUE KEY uq_attachments_ref_file (ref_type, ref_id, file_id),
+  KEY idx_attachments_file_id (file_id),
+  KEY idx_attachments_ref_sort (ref_type, ref_id, sort_order, created_at),
+  KEY idx_attachments_ref_category (ref_type, ref_id, category)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS attachments;
diff --git a/migrations/20260408_hems_duty_roster_crews_confirm_at.sql b/migrations/20260408_hems_duty_roster_crews_confirm_at.sql
new file mode 100644
index 0000000..644a501
--- /dev/null
+++ b/migrations/20260408_hems_duty_roster_crews_confirm_at.sql
@@ -0,0 +1,7 @@
+-- +goose Up
+ALTER TABLE hems_duty_roster_crews
+ADD COLUMN IF NOT EXISTS confirm_at DATETIME NULL AFTER email;
+
+-- +goose Down
+ALTER TABLE hems_duty_roster_crews
+DROP COLUMN IF EXISTS confirm_at;
diff --git a/migrations/20260409_after_flight_inspections.sql b/migrations/20260409_after_flight_inspections.sql
new file mode 100644
index 0000000..b350f8c
--- /dev/null
+++ b/migrations/20260409_after_flight_inspections.sql
@@ -0,0 +1,25 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS after_flight_inspections (
+    id BINARY(16) PRIMARY KEY,
+    flight_inspection_id BINARY(16) NOT NULL,
+    ac_oil_upload_liter DECIMAL(10,2) NULL,
+    oil_engine_nr1_checked TINYINT(1) NULL,
+    oil_engine_nr2_checked TINYINT(1) NULL,
+    hydraulic_lh_checked TINYINT(1) NULL,
+    hydraulic_rh_checked TINYINT(1) NULL,
+    oil_transmission_mgb_checked TINYINT(1) NULL,
+    oil_transmission_igb_checked TINYINT(1) NULL,
+    oil_transmission_tgb_checked TINYINT(1) NULL,
+    note TEXT NULL,
+    created_at DATETIME NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME NULL,
+    updated_by BINARY(16) NULL,
+    CONSTRAINT fk_after_flight_inspections_flight_inspection FOREIGN KEY (flight_inspection_id) REFERENCES flight_inspections(id),
+    CONSTRAINT chk_after_flight_ac_oil_upload_liter CHECK (ac_oil_upload_liter IS NULL OR ac_oil_upload_liter >= 0)
+);
+
+CREATE UNIQUE INDEX idx_after_flight_inspections_flight_inspection_id ON after_flight_inspections(flight_inspection_id);
+
+-- +goose Down
+DROP TABLE IF EXISTS after_flight_inspections;
diff --git a/migrations/20260409_before_flight_inspections.sql b/migrations/20260409_before_flight_inspections.sql
new file mode 100644
index 0000000..4b920b1
--- /dev/null
+++ b/migrations/20260409_before_flight_inspections.sql
@@ -0,0 +1,27 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS before_flight_inspections (
+    id BINARY(16) PRIMARY KEY,
+    flight_inspection_id BINARY(16) NOT NULL,
+    oil_engine_nr1_checked TINYINT(1) NULL,
+    oil_engine_nr2_checked TINYINT(1) NULL,
+    hydraulic_lh_checked TINYINT(1) NULL,
+    hydraulic_rh_checked TINYINT(1) NULL,
+    oil_transmission_mgb_checked TINYINT(1) NULL,
+    oil_transmission_igb_checked TINYINT(1) NULL,
+    oil_transmission_tgb_checked TINYINT(1) NULL,
+    fuel_amount DECIMAL(10,2) NULL,
+    fuel_unit VARCHAR(10) NULL,
+    fuel_added_amount DECIMAL(10,2) NULL,
+    note TEXT NULL,
+    created_at DATETIME NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME NULL,
+    updated_by BINARY(16) NULL,
+    CONSTRAINT fk_before_flight_inspections_flight_inspection FOREIGN KEY (flight_inspection_id) REFERENCES flight_inspections(id),
+    CONSTRAINT chk_before_flight_fuel_unit CHECK (fuel_unit IS NULL OR fuel_unit IN ('LT', 'KG', 'POUND'))
+);
+
+CREATE UNIQUE INDEX idx_before_flight_inspections_flight_inspection_id ON before_flight_inspections(flight_inspection_id);
+
+-- +goose Down
+DROP TABLE IF EXISTS before_flight_inspections;
diff --git a/migrations/20260409_flight_inspections.sql b/migrations/20260409_flight_inspections.sql
new file mode 100644
index 0000000..c93c3a7
--- /dev/null
+++ b/migrations/20260409_flight_inspections.sql
@@ -0,0 +1,30 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS flight_inspections (
+    id BINARY(16) PRIMARY KEY,
+    helicopter_id BINARY(16) NOT NULL,
+    inspection_date DATE NOT NULL,
+    operation_id BINARY(16) NULL,
+    status ENUM('Draft', 'InProgress', 'Completed') NOT NULL DEFAULT 'Draft',
+    before_flight_completed_at DATETIME NULL,
+    before_flight_completed_by BINARY(16) NULL,
+    flight_prep_completed_at DATETIME NULL,
+    flight_prep_completed_by BINARY(16) NULL,
+    after_flight_completed_at DATETIME NULL,
+    after_flight_completed_by BINARY(16) NULL,
+    final_completed_at DATETIME NULL,
+    final_completed_by BINARY(16) NULL,
+    created_at DATETIME NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME NULL,
+    updated_by BINARY(16) NULL,
+    CONSTRAINT fk_flight_inspections_helicopter FOREIGN KEY (helicopter_id) REFERENCES helicopters(id)
+);
+
+CREATE INDEX idx_flight_inspections_helicopter_id ON flight_inspections(helicopter_id);
+CREATE INDEX idx_flight_inspections_inspection_date ON flight_inspections(inspection_date);
+CREATE INDEX idx_flight_inspections_status ON flight_inspections(status);
+CREATE INDEX idx_flight_inspections_operation_id ON flight_inspections(operation_id);
+CREATE INDEX idx_flight_inspections_helicopter_date ON flight_inspections(helicopter_id, inspection_date);
+
+-- +goose Down
+DROP TABLE IF EXISTS flight_inspections;
diff --git a/migrations/20260409_flight_prep_checks.sql b/migrations/20260409_flight_prep_checks.sql
new file mode 100644
index 0000000..be69b8e
--- /dev/null
+++ b/migrations/20260409_flight_prep_checks.sql
@@ -0,0 +1,26 @@
+-- +goose Up
+-- Migration: Create flight_prep_checks table
+-- Date: 2026-04-09
+-- Description: Per-inspection execution data for flight preparation checklist items
+
+CREATE TABLE flight_prep_checks (
+    id BINARY(16) PRIMARY KEY,
+    flight_inspection_id BINARY(16) NOT NULL,
+    flight_prep_item_id BINARY(16) NOT NULL,
+    is_done TINYINT(1) NOT NULL DEFAULT 0,
+    note TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    created_by BINARY(16),
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    updated_by BINARY(16),
+
+    CONSTRAINT fk_flight_prep_checks_flight_inspection FOREIGN KEY (flight_inspection_id) REFERENCES flight_inspections(id) ON DELETE CASCADE,
+    CONSTRAINT fk_flight_prep_checks_flight_prep_item FOREIGN KEY (flight_prep_item_id) REFERENCES flight_prep_items(id) ON DELETE RESTRICT,
+
+    INDEX idx_flight_prep_checks_flight_inspection (flight_inspection_id),
+    INDEX idx_flight_prep_checks_flight_inspection_sorted (flight_inspection_id, is_done),
+    UNIQUE KEY uk_flight_prep_checks_inspection_item (flight_inspection_id, flight_prep_item_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS flight_prep_checks;
diff --git a/migrations/20260409_flight_prep_items.sql b/migrations/20260409_flight_prep_items.sql
new file mode 100644
index 0000000..294c50f
--- /dev/null
+++ b/migrations/20260409_flight_prep_items.sql
@@ -0,0 +1,25 @@
+-- +goose Up
+-- Migration: Create flight_prep_items table
+-- Date: 2026-04-09
+-- Description: Master data table for flight preparation checklist items
+
+CREATE TABLE flight_prep_items (
+    id BINARY(16) PRIMARY KEY,
+    title VARCHAR(255) NOT NULL,
+    section ENUM('FLIGHT_PREPARATION', 'WEIGHT_AND_BALANCE') NOT NULL,
+    sort_order INT NOT NULL DEFAULT 0 CHECK (sort_order >= 0),
+    is_required TINYINT(1) NOT NULL,
+    is_active TINYINT(1) NOT NULL DEFAULT 1,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    created_by BINARY(16),
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    updated_by BINARY(16),
+
+    INDEX idx_flight_prep_items_section_active (section, is_active),
+    INDEX idx_flight_prep_items_sort_order (sort_order),
+    INDEX idx_flight_prep_items_created_at (created_at),
+    UNIQUE KEY uk_flight_prep_items_title_section_active (title, section, is_active)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS flight_prep_items;
diff --git a/migrations/20260410_opcs.sql b/migrations/20260410_opcs.sql
new file mode 100644
index 0000000..fda78ef
--- /dev/null
+++ b/migrations/20260410_opcs.sql
@@ -0,0 +1,20 @@
+-- +goose Up
+-- Create opcs table for OPC (Operation Planning Center) master data
+
+CREATE TABLE IF NOT EXISTS opcs (
+  id BINARY(16) NOT NULL PRIMARY KEY,
+  name VARCHAR(64) NOT NULL UNIQUE,
+  description VARCHAR(255) NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME NULL,
+  deleted_by BINARY(16) NULL,
+
+  KEY idx_opcs_name (name),
+  KEY idx_opcs_deleted_at (deleted_at)
+);
+
+-- +goose Down
+DROP TABLE IF EXISTS opcs;
diff --git a/migrations/20260410_patient_data.sql b/migrations/20260410_patient_data.sql
new file mode 100644
index 0000000..5c7cd72
--- /dev/null
+++ b/migrations/20260410_patient_data.sql
@@ -0,0 +1,57 @@
+-- +goose Up
+-- Create insurance_patient_data table
+
+CREATE TABLE IF NOT EXISTS insurance_patient_data (
+  id BINARY(16) NOT NULL PRIMARY KEY,
+  health_insurance_companies_id BINARY(16) NULL,
+  federal_state_id BINARY(16) NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME NULL,
+  deleted_by BINARY(16) NULL,
+
+  KEY idx_insurance_patient_data_health_insurance_companies_id (health_insurance_companies_id),
+  KEY idx_insurance_patient_data_federal_state_id (federal_state_id),
+  KEY idx_insurance_patient_data_deleted_at (deleted_at)
+);
+
+-- Create patient_data table
+
+CREATE TABLE IF NOT EXISTS patient_data (
+  id BINARY(16) NOT NULL PRIMARY KEY,
+  family_name VARCHAR(128) NOT NULL,
+  first_name VARCHAR(128) NOT NULL,
+  opc_id BINARY(16) NULL,
+  birth_date DATE NULL,
+  gender ENUM('male','female') NOT NULL,
+  street VARCHAR(255) NULL,
+  svnr VARCHAR(64) NULL,
+  email VARCHAR(191) NULL,
+  phone VARCHAR(64) NULL,
+  co_insured TINYINT(1) NOT NULL DEFAULT 0,
+  place_id BINARY(16) NULL,
+  nationality_id BINARY(16) NULL,
+  insurance_patient_data_id BINARY(16) NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME NULL,
+  deleted_by BINARY(16) NULL,
+
+  KEY idx_patient_data_opc_id (opc_id),
+  KEY idx_patient_data_place_id (place_id),
+  KEY idx_patient_data_nationality_id (nationality_id),
+  KEY idx_patient_data_insurance_patient_data_id (insurance_patient_data_id),
+  KEY idx_patient_data_deleted_at (deleted_at),
+
+  CONSTRAINT fk_patient_data_insurance_patient_data
+    FOREIGN KEY (insurance_patient_data_id) REFERENCES insurance_patient_data (id)
+    ON UPDATE CASCADE ON DELETE SET NULL
+);
+
+-- +goose Down
+DROP TABLE IF EXISTS patient_data;
+DROP TABLE IF EXISTS insurance_patient_data;
diff --git a/migrations/20260410_places.sql b/migrations/20260410_places.sql
new file mode 100644
index 0000000..b7af1ba
--- /dev/null
+++ b/migrations/20260410_places.sql
@@ -0,0 +1,28 @@
+-- +goose Up
+-- Create places table
+
+CREATE TABLE IF NOT EXISTS places (
+  id BINARY(16) NOT NULL PRIMARY KEY,
+  state VARCHAR(255) NULL,
+  post_code VARCHAR(32) NULL,
+  location VARCHAR(255) NOT NULL,
+  street VARCHAR(255) NULL,
+  no VARCHAR(50) NULL,
+  country_code VARCHAR(10) NULL,
+  country_name VARCHAR(255) NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME NULL,
+  deleted_by BINARY(16) NULL,
+
+  KEY idx_places_location (location),
+  KEY idx_places_state (state),
+  KEY idx_places_post_code (post_code),
+  KEY idx_places_country_code (country_code),
+  KEY idx_places_deleted_at (deleted_at)
+);
+
+-- +goose Down
+DROP TABLE IF EXISTS places;
diff --git a/migrations/20260414_flight_inspection_reserve_ac_refactor.sql b/migrations/20260414_flight_inspection_reserve_ac_refactor.sql
new file mode 100644
index 0000000..14ecc5d
--- /dev/null
+++ b/migrations/20260414_flight_inspection_reserve_ac_refactor.sql
@@ -0,0 +1,26 @@
+CREATE TABLE IF NOT EXISTS reserve_acs (
+    id BINARY(16) PRIMARY KEY,
+    status VARCHAR(20) NOT NULL DEFAULT 'pending',
+    helicopter_id BINARY(16) NOT NULL,
+    inspection_id BINARY(16) NOT NULL,
+    created_at DATETIME NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME NULL,
+    updated_by BINARY(16) NULL,
+    deleted_at DATETIME NULL,
+    deleted_by BINARY(16) NULL,
+    CONSTRAINT chk_reserve_ac_status CHECK (status IN ('pending', 'approved', 'onprogress')),
+    CONSTRAINT fk_reserve_acs_helicopter FOREIGN KEY (helicopter_id) REFERENCES helicopters(id),
+    CONSTRAINT fk_reserve_acs_inspection FOREIGN KEY (inspection_id) REFERENCES flight_inspections(id)
+);
+
+CREATE INDEX idx_reserve_acs_helicopter_id ON reserve_acs(helicopter_id);
+CREATE INDEX idx_reserve_acs_inspection_id ON reserve_acs(inspection_id);
+CREATE INDEX idx_reserve_acs_deleted_at ON reserve_acs(deleted_at);
+
+ALTER TABLE flight_inspections DROP FOREIGN KEY fk_flight_inspections_helicopter;
+DROP INDEX idx_flight_inspections_helicopter_id ON flight_inspections;
+DROP INDEX idx_flight_inspections_operation_id ON flight_inspections;
+DROP INDEX idx_flight_inspections_helicopter_date ON flight_inspections;
+ALTER TABLE flight_inspections DROP COLUMN helicopter_id;
+ALTER TABLE flight_inspections DROP COLUMN operation_id;
diff --git a/migrations/20260414_flights.sql b/migrations/20260414_flights.sql
new file mode 100644
index 0000000..d50bbbb
--- /dev/null
+++ b/migrations/20260414_flights.sql
@@ -0,0 +1,23 @@
+CREATE TABLE IF NOT EXISTS flights (
+    id BINARY(16) PRIMARY KEY,
+    mission_code VARCHAR(64) NOT NULL,
+    mission_type VARCHAR(32) NOT NULL,
+    date DATE NOT NULL,
+    duty_roster_id BINARY(16) NULL,
+    reserve_ac_id BINARY(16) NULL,
+    created_at DATETIME NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME NULL,
+    updated_by BINARY(16) NULL,
+    deleted_at DATETIME NULL,
+    deleted_by BINARY(16) NULL,
+    CONSTRAINT fk_flights_reserve_ac FOREIGN KEY (reserve_ac_id) REFERENCES reserve_acs(id),
+    CONSTRAINT chk_flights_mission_type CHECK (mission_type IN ('hems', 'cat', 'spo', 'nco'))
+);
+
+CREATE INDEX idx_flights_mission_code ON flights(mission_code);
+CREATE INDEX idx_flights_mission_type ON flights(mission_type);
+CREATE INDEX idx_flights_date ON flights(date);
+CREATE INDEX idx_flights_duty_roster_id ON flights(duty_roster_id);
+CREATE INDEX idx_flights_reserve_ac_id ON flights(reserve_ac_id);
+CREATE INDEX idx_flights_deleted_at ON flights(deleted_at);
diff --git a/migrations/20260414_helicopter_files_and_flight_inspection_file_checklists.sql b/migrations/20260414_helicopter_files_and_flight_inspection_file_checklists.sql
new file mode 100644
index 0000000..d8ff685
--- /dev/null
+++ b/migrations/20260414_helicopter_files_and_flight_inspection_file_checklists.sql
@@ -0,0 +1,41 @@
+CREATE TABLE IF NOT EXISTS helicopter_files (
+    id BINARY(16) PRIMARY KEY,
+    section VARCHAR(64) NOT NULL,
+    helicopter_id BINARY(16) NOT NULL,
+    file_attachment_id BINARY(16) NOT NULL,
+    created_at DATETIME NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME NULL,
+    updated_by BINARY(16) NULL,
+    CONSTRAINT chk_helicopter_files_section CHECK (
+        section IN (
+            'before_first_flight_inspection',
+            'flight_preparation_and_wb',
+            'after_last_flight_inspection'
+        )
+    ),
+    CONSTRAINT fk_helicopter_files_helicopter FOREIGN KEY (helicopter_id) REFERENCES helicopters(id),
+    CONSTRAINT fk_helicopter_files_attachment FOREIGN KEY (file_attachment_id) REFERENCES attachments(id)
+);
+
+CREATE INDEX idx_helicopter_files_section ON helicopter_files(section);
+CREATE INDEX idx_helicopter_files_helicopter_id ON helicopter_files(helicopter_id);
+CREATE INDEX idx_helicopter_files_attachment_id ON helicopter_files(file_attachment_id);
+
+CREATE TABLE IF NOT EXISTS flight_inspection_file_checklists (
+    id BINARY(16) PRIMARY KEY,
+    is_done TINYINT(1) NOT NULL DEFAULT 0,
+    helicopter_file_id BINARY(16) NOT NULL,
+    flight_inspection_id BINARY(16) NOT NULL,
+    created_at DATETIME NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME NULL,
+    updated_by BINARY(16) NULL,
+    CONSTRAINT fk_flight_inspection_file_checklists_helicopter_file FOREIGN KEY (helicopter_file_id) REFERENCES helicopter_files(id),
+    CONSTRAINT fk_flight_inspection_file_checklists_inspection FOREIGN KEY (flight_inspection_id) REFERENCES flight_inspections(id),
+    CONSTRAINT uq_flight_inspection_file_checklists_inspection_file UNIQUE (flight_inspection_id, helicopter_file_id)
+);
+
+CREATE INDEX idx_flight_inspection_file_checklists_file_id ON flight_inspection_file_checklists(helicopter_file_id);
+CREATE INDEX idx_flight_inspection_file_checklists_inspection_id ON flight_inspection_file_checklists(flight_inspection_id);
+CREATE INDEX idx_flight_inspection_file_checklists_inspection_sorted ON flight_inspection_file_checklists(flight_inspection_id, is_done);
diff --git a/migrations/20260414_hems_operations_mission_link.sql b/migrations/20260414_hems_operations_mission_link.sql
new file mode 100644
index 0000000..1a4b5a5
--- /dev/null
+++ b/migrations/20260414_hems_operations_mission_link.sql
@@ -0,0 +1,35 @@
+ALTER TABLE hems_operations
+    ADD COLUMN IF NOT EXISTS mission_id BINARY(16) NULL;
+
+SET @fk_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.table_constraints
+    WHERE table_schema = DATABASE()
+      AND table_name = 'hems_operations'
+      AND constraint_type = 'FOREIGN KEY'
+      AND constraint_name = 'fk_hems_operations_mission'
+);
+SET @fk_sql := IF(
+    @fk_exists = 0,
+    'ALTER TABLE hems_operations ADD CONSTRAINT fk_hems_operations_mission FOREIGN KEY (mission_id) REFERENCES missions(id) ON UPDATE CASCADE ON DELETE SET NULL',
+    'SELECT 1'
+);
+PREPARE stmt_fk FROM @fk_sql;
+EXECUTE stmt_fk;
+DEALLOCATE PREPARE stmt_fk;
+
+SET @idx_exists := (
+    SELECT COUNT(1)
+    FROM information_schema.statistics
+    WHERE table_schema = DATABASE()
+      AND table_name = 'hems_operations'
+      AND index_name = 'uidx_hems_operations_mission_id'
+);
+SET @idx_sql := IF(
+    @idx_exists = 0,
+    'ALTER TABLE hems_operations ADD UNIQUE INDEX uidx_hems_operations_mission_id (mission_id)',
+    'SELECT 1'
+);
+PREPARE stmt_idx FROM @idx_sql;
+EXECUTE stmt_idx;
+DEALLOCATE PREPARE stmt_idx;
diff --git a/migrations/20260414_missions.sql b/migrations/20260414_missions.sql
new file mode 100644
index 0000000..8d4a702
--- /dev/null
+++ b/migrations/20260414_missions.sql
@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS missions (
+    id BINARY(16) PRIMARY KEY,
+    flight_id BINARY(16) NOT NULL,
+    type VARCHAR(20) NOT NULL,
+    created_at DATETIME NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME NULL,
+    updated_by BINARY(16) NULL,
+    deleted_at DATETIME NULL,
+    deleted_by BINARY(16) NULL,
+    CONSTRAINT fk_missions_flight FOREIGN KEY (flight_id) REFERENCES flights(id) ON UPDATE CASCADE ON DELETE CASCADE,
+    CONSTRAINT chk_missions_type CHECK (type IN ('CAT', 'SPO', 'NCO', 'HEMS'))
+);
+
+CREATE UNIQUE INDEX uidx_missions_flight_id ON missions(flight_id);
+CREATE INDEX idx_missions_type ON missions(type);
+CREATE INDEX idx_missions_deleted_at ON missions(deleted_at);
diff --git a/migrations/20260414_reserve_acs_unique_inspection_id.sql b/migrations/20260414_reserve_acs_unique_inspection_id.sql
new file mode 100644
index 0000000..16f1bb1
--- /dev/null
+++ b/migrations/20260414_reserve_acs_unique_inspection_id.sql
@@ -0,0 +1,2 @@
+ALTER TABLE reserve_acs DROP INDEX idx_reserve_acs_inspection_id;
+ALTER TABLE reserve_acs ADD UNIQUE INDEX uidx_reserve_acs_inspection_id (inspection_id);
diff --git a/migrations/20260415_helicopter_files_section_short_codes.sql b/migrations/20260415_helicopter_files_section_short_codes.sql
new file mode 100644
index 0000000..7ea8998
--- /dev/null
+++ b/migrations/20260415_helicopter_files_section_short_codes.sql
@@ -0,0 +1,17 @@
+ALTER TABLE helicopter_files DROP CHECK chk_helicopter_files_section;
+
+UPDATE helicopter_files
+SET section = 'bfi'
+WHERE section = 'before_first_flight_inspection';
+
+UPDATE helicopter_files
+SET section = 'fpwb'
+WHERE section = 'flight_preparation_and_wb';
+
+UPDATE helicopter_files
+SET section = 'afi'
+WHERE section = 'after_last_flight_inspection';
+
+ALTER TABLE helicopter_files
+ADD CONSTRAINT chk_helicopter_files_section
+CHECK (section IN ('bfi', 'fpwb', 'afi'));
diff --git a/migrations/20260416_drop_flight_prep_items.sql b/migrations/20260416_drop_flight_prep_items.sql
new file mode 100644
index 0000000..241177a
--- /dev/null
+++ b/migrations/20260416_drop_flight_prep_items.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS flight_prep_items;
diff --git a/migrations/20260416_flight_prep_checks_static_fields.sql b/migrations/20260416_flight_prep_checks_static_fields.sql
new file mode 100644
index 0000000..153bd52
--- /dev/null
+++ b/migrations/20260416_flight_prep_checks_static_fields.sql
@@ -0,0 +1,14 @@
+ALTER TABLE flight_prep_checks DROP FOREIGN KEY fk_flight_prep_checks_flight_prep_item;
+ALTER TABLE flight_prep_checks DROP INDEX uk_flight_prep_checks_inspection_item;
+ALTER TABLE flight_prep_checks DROP COLUMN flight_prep_item_id;
+ALTER TABLE flight_prep_checks DROP COLUMN is_done;
+ALTER TABLE flight_prep_checks DROP COLUMN note;
+ALTER TABLE flight_prep_checks DROP INDEX idx_flight_prep_checks_flight_inspection_sorted;
+
+ALTER TABLE flight_prep_checks
+  ADD COLUMN notam_briefing TINYINT(1) NOT NULL DEFAULT 0 AFTER id,
+  ADD COLUMN weather_briefing TINYINT(1) NOT NULL DEFAULT 0 AFTER notam_briefing,
+  ADD COLUMN operational_flight_plan TINYINT(1) NOT NULL DEFAULT 0 AFTER weather_briefing;
+
+ALTER TABLE flight_prep_checks
+  ADD UNIQUE KEY uk_flight_prep_checks_inspection (flight_inspection_id);
diff --git a/migrations/20260416_helicopters_foto_attachment.sql b/migrations/20260416_helicopters_foto_attachment.sql
new file mode 100644
index 0000000..b85e3df
--- /dev/null
+++ b/migrations/20260416_helicopters_foto_attachment.sql
@@ -0,0 +1,14 @@
+-- +goose Up
+ALTER TABLE helicopters
+  ADD COLUMN foto_attachment_id BINARY(16) NULL,
+  ADD KEY idx_helicopters_foto_attachment_id (foto_attachment_id),
+  ADD CONSTRAINT fk_helicopters_foto_attachment
+    FOREIGN KEY (foto_attachment_id) REFERENCES attachments(id)
+    ON UPDATE CASCADE
+    ON DELETE SET NULL;
+
+-- +goose Down
+ALTER TABLE helicopters
+  DROP FOREIGN KEY fk_helicopters_foto_attachment,
+  DROP KEY idx_helicopters_foto_attachment_id,
+  DROP COLUMN foto_attachment_id;
diff --git a/migrations/20260416_master_setting_values.sql b/migrations/20260416_master_setting_values.sql
new file mode 100644
index 0000000..f524262
--- /dev/null
+++ b/migrations/20260416_master_setting_values.sql
@@ -0,0 +1,16 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS master_setting_values (
+  setting_key VARCHAR(120) NOT NULL PRIMARY KEY,
+  value TEXT NOT NULL,
+  is_encrypted TINYINT(1) NOT NULL DEFAULT 0,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+
+  KEY idx_master_setting_values_updated_at (updated_at),
+  KEY idx_master_setting_values_is_encrypted (is_encrypted)
+);
+
+-- +goose Down
+DROP TABLE IF EXISTS master_setting_values;
diff --git a/migrations/20260416_users_profile_picture_attachment.sql b/migrations/20260416_users_profile_picture_attachment.sql
new file mode 100644
index 0000000..908cb6d
--- /dev/null
+++ b/migrations/20260416_users_profile_picture_attachment.sql
@@ -0,0 +1,14 @@
+-- +goose Up
+ALTER TABLE users
+  ADD COLUMN image_attachment_id BINARY(16) NULL,
+  ADD KEY idx_users_image_attachment_id (image_attachment_id),
+  ADD CONSTRAINT fk_users_image_attachment
+    FOREIGN KEY (image_attachment_id) REFERENCES attachments(id)
+    ON UPDATE CASCADE
+    ON DELETE SET NULL;
+
+-- +goose Down
+ALTER TABLE users
+  DROP FOREIGN KEY fk_users_image_attachment,
+  DROP KEY idx_users_image_attachment_id,
+  DROP COLUMN image_attachment_id;
diff --git a/migrations/20260421_file_thumbnail_metadata.sql b/migrations/20260421_file_thumbnail_metadata.sql
new file mode 100644
index 0000000..d38653a
--- /dev/null
+++ b/migrations/20260421_file_thumbnail_metadata.sql
@@ -0,0 +1,8 @@
+ALTER TABLE file_files
+  ADD COLUMN thumbnail_mime_type VARCHAR(255) NULL AFTER etag,
+  ADD COLUMN thumbnail_size_bytes BIGINT UNSIGNED NULL AFTER thumbnail_mime_type,
+  ADD COLUMN thumbnail_bucket VARCHAR(128) NULL AFTER thumbnail_size_bytes,
+  ADD COLUMN thumbnail_object_key VARCHAR(512) NULL AFTER thumbnail_bucket,
+  ADD COLUMN thumbnail_object_version VARCHAR(128) NULL AFTER thumbnail_object_key,
+  ADD COLUMN thumbnail_etag VARCHAR(128) NULL AFTER thumbnail_object_version,
+  ADD UNIQUE KEY uq_file_files_thumbnail_object_key (thumbnail_object_key);
diff --git a/migrations/20260421_file_thumbnail_metadata_null_cleanup.sql b/migrations/20260421_file_thumbnail_metadata_null_cleanup.sql
new file mode 100644
index 0000000..b5bcc35
--- /dev/null
+++ b/migrations/20260421_file_thumbnail_metadata_null_cleanup.sql
@@ -0,0 +1,13 @@
+UPDATE file_files
+SET
+  thumbnail_mime_type = NULLIF(TRIM(thumbnail_mime_type), ''),
+  thumbnail_bucket = NULLIF(TRIM(thumbnail_bucket), ''),
+  thumbnail_object_key = NULLIF(TRIM(thumbnail_object_key), ''),
+  thumbnail_object_version = NULLIF(TRIM(thumbnail_object_version), ''),
+  thumbnail_etag = NULLIF(TRIM(thumbnail_etag), '')
+WHERE
+  COALESCE(TRIM(thumbnail_mime_type), '') = ''
+  OR COALESCE(TRIM(thumbnail_bucket), '') = ''
+  OR COALESCE(TRIM(thumbnail_object_key), '') = ''
+  OR COALESCE(TRIM(thumbnail_object_version), '') = ''
+  OR COALESCE(TRIM(thumbnail_etag), '') = '';
diff --git a/migrations/20260422_helicopters_aog_reason.sql b/migrations/20260422_helicopters_aog_reason.sql
new file mode 100644
index 0000000..c30c044
--- /dev/null
+++ b/migrations/20260422_helicopters_aog_reason.sql
@@ -0,0 +1,7 @@
+-- +goose Up
+ALTER TABLE helicopters
+  ADD COLUMN aog_reason TEXT NULL AFTER air_on_ground;
+
+-- +goose Down
+ALTER TABLE helicopters
+  DROP COLUMN aog_reason;
diff --git a/migrations/20260423_backfill_flight_inspection_file_checklists_from_reserve_acs.sql b/migrations/20260423_backfill_flight_inspection_file_checklists_from_reserve_acs.sql
new file mode 100644
index 0000000..4d87250
--- /dev/null
+++ b/migrations/20260423_backfill_flight_inspection_file_checklists_from_reserve_acs.sql
@@ -0,0 +1,31 @@
+-- Backfill checklist rows for existing reserve AC records.
+-- This fixes historical gaps where checklist rows were not inserted.
+
+INSERT INTO flight_inspection_file_checklists (
+    id,
+    is_done,
+    helicopter_file_id,
+    flight_inspection_id,
+    created_at,
+    created_by,
+    updated_at,
+    updated_by
+)
+SELECT
+    UUID_TO_BIN(UUID()) AS id,
+    0 AS is_done,
+    hf.id AS helicopter_file_id,
+    ra.inspection_id AS flight_inspection_id,
+    UTC_TIMESTAMP(3) AS created_at,
+    ra.created_by AS created_by,
+    UTC_TIMESTAMP(3) AS updated_at,
+    ra.updated_by AS updated_by
+FROM reserve_acs ra
+JOIN helicopter_files hf
+  ON hf.helicopter_id = ra.helicopter_id
+ AND hf.section IN ('bfi', 'fpwb')
+LEFT JOIN flight_inspection_file_checklists fck
+  ON fck.flight_inspection_id = ra.inspection_id
+ AND fck.helicopter_file_id = hf.id
+WHERE ra.deleted_at IS NULL
+  AND fck.id IS NULL;
diff --git a/migrations/20260423_fix_flight_inspection_file_checklists_legacy_aircraft_file.sql b/migrations/20260423_fix_flight_inspection_file_checklists_legacy_aircraft_file.sql
new file mode 100644
index 0000000..7955397
--- /dev/null
+++ b/migrations/20260423_fix_flight_inspection_file_checklists_legacy_aircraft_file.sql
@@ -0,0 +1,52 @@
+-- Remove legacy aircraft_file_id from flight_inspection_file_checklists.
+-- Current app writes helicopter_file_id; keeping aircraft_file_id as NOT NULL
+-- causes inserts to fail with:
+--   Error 1364 (HY000): Field 'aircraft_file_id' doesn't have a default value
+
+SET @schema_name := DATABASE();
+
+SELECT COUNT(*) INTO @has_legacy_fk
+FROM information_schema.TABLE_CONSTRAINTS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'flight_inspection_file_checklists'
+  AND CONSTRAINT_TYPE = 'FOREIGN KEY'
+  AND CONSTRAINT_NAME = 'fk_flight_inspection_file_checklists_aircraft_file';
+
+SET @drop_legacy_fk_sql := IF(
+  @has_legacy_fk > 0,
+  'ALTER TABLE flight_inspection_file_checklists DROP FOREIGN KEY fk_flight_inspection_file_checklists_aircraft_file',
+  'SELECT 1'
+);
+PREPARE stmt_drop_legacy_fk FROM @drop_legacy_fk_sql;
+EXECUTE stmt_drop_legacy_fk;
+DEALLOCATE PREPARE stmt_drop_legacy_fk;
+
+SELECT COUNT(*) INTO @has_legacy_index
+FROM information_schema.STATISTICS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'flight_inspection_file_checklists'
+  AND INDEX_NAME = 'fk_flight_inspection_file_checklists_aircraft_file';
+
+SET @drop_legacy_index_sql := IF(
+  @has_legacy_index > 0,
+  'ALTER TABLE flight_inspection_file_checklists DROP INDEX fk_flight_inspection_file_checklists_aircraft_file',
+  'SELECT 1'
+);
+PREPARE stmt_drop_legacy_index FROM @drop_legacy_index_sql;
+EXECUTE stmt_drop_legacy_index;
+DEALLOCATE PREPARE stmt_drop_legacy_index;
+
+SELECT COUNT(*) INTO @has_legacy_column
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'flight_inspection_file_checklists'
+  AND COLUMN_NAME = 'aircraft_file_id';
+
+SET @drop_legacy_column_sql := IF(
+  @has_legacy_column > 0,
+  'ALTER TABLE flight_inspection_file_checklists DROP COLUMN aircraft_file_id',
+  'SELECT 1'
+);
+PREPARE stmt_drop_legacy_column FROM @drop_legacy_column_sql;
+EXECUTE stmt_drop_legacy_column;
+DEALLOCATE PREPARE stmt_drop_legacy_column;
diff --git a/migrations/20260424_bases_sortkey.sql b/migrations/20260424_bases_sortkey.sql
new file mode 100644
index 0000000..8e9f06e
--- /dev/null
+++ b/migrations/20260424_bases_sortkey.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+ALTER TABLE bases
+  ADD COLUMN sortkey INT NULL AFTER position,
+  ADD KEY idx_bases_sortkey (sortkey);
+
+-- +goose Down
+ALTER TABLE bases
+  DROP KEY idx_bases_sortkey,
+  DROP COLUMN sortkey;
diff --git a/migrations/20260424_bmds_note_sortkey_is_active.sql b/migrations/20260424_bmds_note_sortkey_is_active.sql
new file mode 100644
index 0000000..2d04580
--- /dev/null
+++ b/migrations/20260424_bmds_note_sortkey_is_active.sql
@@ -0,0 +1,15 @@
+-- +goose Up
+ALTER TABLE bmds
+  ADD COLUMN note VARCHAR(255) NULL AFTER country_name,
+  ADD COLUMN sortkey INT NULL AFTER country_name,
+  ADD COLUMN is_active TINYINT(1) NOT NULL DEFAULT 1 AFTER sortkey,
+  ADD KEY idx_bmds_sortkey (sortkey),
+  ADD KEY idx_bmds_is_active (is_active);
+
+-- +goose Down
+ALTER TABLE bmds
+  DROP KEY idx_bmds_sortkey,
+  DROP KEY idx_bmds_is_active,
+  DROP COLUMN sortkey,
+  DROP COLUMN note,
+  DROP COLUMN is_active;
diff --git a/migrations/20260424_drop_bases_default_shift_time.sql b/migrations/20260424_drop_bases_default_shift_time.sql
new file mode 100644
index 0000000..0c76be8
--- /dev/null
+++ b/migrations/20260424_drop_bases_default_shift_time.sql
@@ -0,0 +1,51 @@
+-- +goose Up
+SET @bases_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.tables
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+);
+
+SET @col_default_shift_time_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'default_shift_time'
+);
+
+SET @drop_default_shift_time_sql := IF(
+  @bases_exists > 0 AND @col_default_shift_time_exists > 0,
+  'ALTER TABLE bases DROP COLUMN default_shift_time',
+  'SELECT 1'
+);
+
+PREPARE stmt_drop_default_shift_time FROM @drop_default_shift_time_sql;
+EXECUTE stmt_drop_default_shift_time;
+DEALLOCATE PREPARE stmt_drop_default_shift_time;
+
+-- +goose Down
+SET @bases_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.tables
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+);
+
+SET @col_default_shift_time_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'default_shift_time'
+);
+
+SET @add_default_shift_time_sql := IF(
+  @bases_exists > 0 AND @col_default_shift_time_exists = 0,
+  'ALTER TABLE bases ADD COLUMN default_shift_time VARCHAR(64) NULL AFTER default_shift_end',
+  'SELECT 1'
+);
+
+PREPARE stmt_add_default_shift_time FROM @add_default_shift_time_sql;
+EXECUTE stmt_add_default_shift_time;
+DEALLOCATE PREPARE stmt_add_default_shift_time;
diff --git a/migrations/20260424_facilities_sortkey.sql b/migrations/20260424_facilities_sortkey.sql
new file mode 100644
index 0000000..0233e56
--- /dev/null
+++ b/migrations/20260424_facilities_sortkey.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+ALTER TABLE facilities
+  ADD COLUMN sortkey INT NULL AFTER type,
+  ADD KEY idx_facilities_sortkey (sortkey);
+
+-- +goose Down
+ALTER TABLE facilities
+  DROP KEY idx_facilities_sortkey,
+  DROP COLUMN sortkey;
diff --git a/migrations/20260424_forces_present_note_sortkey_is_active.sql b/migrations/20260424_forces_present_note_sortkey_is_active.sql
new file mode 100644
index 0000000..e471297
--- /dev/null
+++ b/migrations/20260424_forces_present_note_sortkey_is_active.sql
@@ -0,0 +1,15 @@
+-- +goose Up
+ALTER TABLE forces_present
+  ADD COLUMN note VARCHAR(255) NULL AFTER description,
+  ADD COLUMN sortkey INT NULL AFTER name,
+  ADD COLUMN is_active TINYINT(1) NOT NULL DEFAULT 1 AFTER sortkey,
+  ADD KEY idx_forces_present_sortkey (sortkey),
+  ADD KEY idx_forces_present_is_active (is_active);
+
+-- +goose Down
+ALTER TABLE forces_present
+  DROP KEY idx_forces_present_sortkey,
+  DROP KEY idx_forces_present_is_active,
+  DROP COLUMN sortkey,
+  DROP COLUMN note,
+  DROP COLUMN is_active;
diff --git a/migrations/20260424_health_insurance_companies_sortkey_is_active.sql b/migrations/20260424_health_insurance_companies_sortkey_is_active.sql
new file mode 100644
index 0000000..ae7c976
--- /dev/null
+++ b/migrations/20260424_health_insurance_companies_sortkey_is_active.sql
@@ -0,0 +1,13 @@
+-- +goose Up
+ALTER TABLE health_insurance_companies
+  ADD COLUMN sortkey INT NULL AFTER name,
+  ADD COLUMN is_active TINYINT(1) NOT NULL DEFAULT 1 AFTER sortkey,
+  ADD KEY idx_health_insurance_companies_sortkey (sortkey),
+  ADD KEY idx_health_insurance_companies_is_active (is_active);
+
+-- +goose Down
+ALTER TABLE health_insurance_companies
+  DROP KEY idx_health_insurance_companies_sortkey,
+  DROP KEY idx_health_insurance_companies_is_active,
+  DROP COLUMN sortkey,
+  DROP COLUMN is_active;
diff --git a/migrations/20260424_helicopters_sortkey.sql b/migrations/20260424_helicopters_sortkey.sql
new file mode 100644
index 0000000..f21b452
--- /dev/null
+++ b/migrations/20260424_helicopters_sortkey.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+ALTER TABLE helicopters
+  ADD COLUMN sortkey INT NULL AFTER type,
+  ADD KEY idx_helicopters_sortkey (sortkey);
+
+-- +goose Down
+ALTER TABLE helicopters
+  DROP KEY idx_helicopters_sortkey,
+  DROP COLUMN sortkey;
diff --git a/migrations/20260424_hospital_contacts_notes.sql b/migrations/20260424_hospital_contacts_notes.sql
new file mode 100644
index 0000000..a44d371
--- /dev/null
+++ b/migrations/20260424_hospital_contacts_notes.sql
@@ -0,0 +1,73 @@
+-- +goose Up
+ALTER TABLE hospitals
+  ADD COLUMN IF NOT EXISTS note TEXT NULL;
+
+ALTER TABLE icaos
+  ADD COLUMN IF NOT EXISTS note TEXT NULL;
+
+ALTER TABLE health_insurance_companies
+  ADD COLUMN IF NOT EXISTS note TEXT NULL;
+
+ALTER TABLE federal_states
+  ADD COLUMN IF NOT EXISTS note TEXT NULL;
+
+ALTER TABLE lands
+  ADD COLUMN IF NOT EXISTS note TEXT NULL;
+
+ALTER TABLE nationalities
+  ADD COLUMN IF NOT EXISTS note TEXT NULL;
+
+ALTER TABLE pilot_profiles
+  ADD COLUMN IF NOT EXISTS note TEXT NULL;
+
+ALTER TABLE doctor_profiles
+  ADD COLUMN IF NOT EXISTS note TEXT NULL;
+
+ALTER TABLE air_rescuer_profiles
+  ADD COLUMN IF NOT EXISTS note TEXT NULL;
+
+ALTER TABLE technician_profiles
+  ADD COLUMN IF NOT EXISTS note TEXT NULL;
+
+ALTER TABLE flight_assistant_profiles
+  ADD COLUMN IF NOT EXISTS note TEXT NULL;
+
+ALTER TABLE staff_profiles
+  ADD COLUMN IF NOT EXISTS note TEXT NULL;
+
+-- +goose Down
+ALTER TABLE hospitals
+  DROP COLUMN IF EXISTS note;
+
+ALTER TABLE icaos
+  DROP COLUMN IF EXISTS note;
+
+ALTER TABLE health_insurance_companies
+  DROP COLUMN IF EXISTS note;
+
+ALTER TABLE federal_states
+  DROP COLUMN IF EXISTS note;
+
+ALTER TABLE lands
+  DROP COLUMN IF EXISTS note;
+
+ALTER TABLE nationalities
+  DROP COLUMN IF EXISTS note;
+
+ALTER TABLE pilot_profiles
+  DROP COLUMN IF EXISTS note;
+
+ALTER TABLE doctor_profiles
+  DROP COLUMN IF EXISTS note;
+
+ALTER TABLE air_rescuer_profiles
+  DROP COLUMN IF EXISTS note;
+
+ALTER TABLE technician_profiles
+  DROP COLUMN IF EXISTS note;
+
+ALTER TABLE flight_assistant_profiles
+  DROP COLUMN IF EXISTS note;
+
+ALTER TABLE staff_profiles
+  DROP COLUMN IF EXISTS note;
diff --git a/migrations/20260424_hospitals_is_active.sql b/migrations/20260424_hospitals_is_active.sql
new file mode 100644
index 0000000..354cb52
--- /dev/null
+++ b/migrations/20260424_hospitals_is_active.sql
@@ -0,0 +1,80 @@
+-- +goose Up
+SET @table_hospitals_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.tables
+  WHERE table_schema = DATABASE()
+    AND table_name = 'hospitals'
+);
+
+SET @col_hospitals_is_active_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'hospitals'
+    AND column_name = 'is_active'
+);
+
+SET @add_hospitals_is_active_sql := IF(
+  @table_hospitals_exists > 0 AND @col_hospitals_is_active_exists = 0,
+  'ALTER TABLE hospitals ADD COLUMN is_active TINYINT(1) NOT NULL DEFAULT 1 AFTER note',
+  'SELECT 1'
+);
+
+PREPARE stmt_add_hospitals_is_active FROM @add_hospitals_is_active_sql;
+EXECUTE stmt_add_hospitals_is_active;
+DEALLOCATE PREPARE stmt_add_hospitals_is_active;
+
+SET @idx_hospitals_is_active_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.statistics
+  WHERE table_schema = DATABASE()
+    AND table_name = 'hospitals'
+    AND index_name = 'idx_hospitals_is_active'
+);
+
+SET @add_idx_hospitals_is_active_sql := IF(
+  @table_hospitals_exists > 0 AND @idx_hospitals_is_active_exists = 0,
+  'ALTER TABLE hospitals ADD INDEX idx_hospitals_is_active (is_active)',
+  'SELECT 1'
+);
+
+PREPARE stmt_add_idx_hospitals_is_active FROM @add_idx_hospitals_is_active_sql;
+EXECUTE stmt_add_idx_hospitals_is_active;
+DEALLOCATE PREPARE stmt_add_idx_hospitals_is_active;
+
+-- +goose Down
+SET @idx_hospitals_is_active_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.statistics
+  WHERE table_schema = DATABASE()
+    AND table_name = 'hospitals'
+    AND index_name = 'idx_hospitals_is_active'
+);
+
+SET @drop_idx_hospitals_is_active_sql := IF(
+  @idx_hospitals_is_active_exists > 0,
+  'ALTER TABLE hospitals DROP INDEX idx_hospitals_is_active',
+  'SELECT 1'
+);
+
+PREPARE stmt_drop_idx_hospitals_is_active FROM @drop_idx_hospitals_is_active_sql;
+EXECUTE stmt_drop_idx_hospitals_is_active;
+DEALLOCATE PREPARE stmt_drop_idx_hospitals_is_active;
+
+SET @col_hospitals_is_active_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'hospitals'
+    AND column_name = 'is_active'
+);
+
+SET @drop_hospitals_is_active_sql := IF(
+  @col_hospitals_is_active_exists > 0,
+  'ALTER TABLE hospitals DROP COLUMN is_active',
+  'SELECT 1'
+);
+
+PREPARE stmt_drop_hospitals_is_active FROM @drop_hospitals_is_active_sql;
+EXECUTE stmt_drop_hospitals_is_active;
+DEALLOCATE PREPARE stmt_drop_hospitals_is_active;
diff --git a/migrations/20260424_icaos_sortkey_is_active.sql b/migrations/20260424_icaos_sortkey_is_active.sql
new file mode 100644
index 0000000..94e67b7
--- /dev/null
+++ b/migrations/20260424_icaos_sortkey_is_active.sql
@@ -0,0 +1,13 @@
+-- +goose Up
+ALTER TABLE icaos
+  ADD COLUMN sortkey INT NULL AFTER icao_code,
+  ADD COLUMN is_active TINYINT(1) NOT NULL DEFAULT 1 AFTER sortkey,
+  ADD KEY idx_icaos_sortkey (sortkey),
+  ADD KEY idx_icaos_is_active (is_active);
+
+-- +goose Down
+ALTER TABLE icaos
+  DROP KEY idx_icaos_sortkey,
+  DROP KEY idx_icaos_is_active,
+  DROP COLUMN sortkey,
+  DROP COLUMN is_active;
diff --git a/migrations/20260424_lands_opcs_is_active.sql b/migrations/20260424_lands_opcs_is_active.sql
new file mode 100644
index 0000000..6d69e3f
--- /dev/null
+++ b/migrations/20260424_lands_opcs_is_active.sql
@@ -0,0 +1,17 @@
+-- +goose Up
+ALTER TABLE lands
+  ADD COLUMN IF NOT EXISTS is_active TINYINT(1) NOT NULL DEFAULT 1,
+  ADD KEY idx_lands_is_active (is_active);
+
+ALTER TABLE opcs
+  ADD COLUMN IF NOT EXISTS is_active TINYINT(1) NOT NULL DEFAULT 1,
+  ADD KEY idx_opcs_is_active (is_active);
+
+-- +goose Down
+ALTER TABLE lands
+  DROP KEY idx_lands_is_active,
+  DROP COLUMN IF EXISTS is_active;
+
+ALTER TABLE opcs
+  DROP KEY idx_opcs_is_active,
+  DROP COLUMN IF EXISTS is_active;
diff --git a/migrations/20260424_medicines_note_sortkey_is_active.sql b/migrations/20260424_medicines_note_sortkey_is_active.sql
new file mode 100644
index 0000000..1bca3b3
--- /dev/null
+++ b/migrations/20260424_medicines_note_sortkey_is_active.sql
@@ -0,0 +1,15 @@
+-- +goose Up
+ALTER TABLE medicines
+  ADD COLUMN note VARCHAR(255) NULL AFTER name,
+  ADD COLUMN sortkey INT NULL AFTER name,
+  ADD COLUMN is_active TINYINT(1) NOT NULL DEFAULT 1 AFTER sortkey,
+  ADD KEY idx_medicines_sortkey (sortkey),
+  ADD KEY idx_medicines_is_active (is_active);
+
+-- +goose Down
+ALTER TABLE medicines
+  DROP KEY idx_medicines_sortkey,
+  DROP KEY idx_medicines_is_active,
+  DROP COLUMN sortkey,
+  DROP COLUMN note,
+  DROP COLUMN is_active;
diff --git a/migrations/20260424_opcs_note_sortkey.sql b/migrations/20260424_opcs_note_sortkey.sql
new file mode 100644
index 0000000..cf91276
--- /dev/null
+++ b/migrations/20260424_opcs_note_sortkey.sql
@@ -0,0 +1,11 @@
+-- +goose Up
+ALTER TABLE opcs
+  ADD COLUMN note VARCHAR(255) NULL AFTER description,
+  ADD COLUMN sortkey INT NULL AFTER name,
+  ADD KEY idx_opcs_sortkey (sortkey);
+
+-- +goose Down
+ALTER TABLE opcs
+  DROP KEY idx_opcs_sortkey,
+  DROP COLUMN sortkey,
+  DROP COLUMN note;
diff --git a/migrations/20260424_remove_places_and_patient_data_place_rel.sql b/migrations/20260424_remove_places_and_patient_data_place_rel.sql
new file mode 100644
index 0000000..2fdca94
--- /dev/null
+++ b/migrations/20260424_remove_places_and_patient_data_place_rel.sql
@@ -0,0 +1,43 @@
+-- +goose Up
+-- Remove deprecated places table and patient_data.place_id relation.
+
+ALTER TABLE patient_data
+  DROP FOREIGN KEY fk_patient_data_place;
+
+ALTER TABLE patient_data
+  DROP COLUMN place_id;
+
+DROP TABLE IF EXISTS places;
+
+-- +goose Down
+-- Recreate places table and patient_data.place_id column.
+
+CREATE TABLE IF NOT EXISTS places (
+  id BINARY(16) NOT NULL PRIMARY KEY,
+  state VARCHAR(255) NULL,
+  post_code VARCHAR(32) NULL,
+  location VARCHAR(255) NOT NULL,
+  street VARCHAR(255) NULL,
+  no VARCHAR(50) NULL,
+  country_code VARCHAR(10) NULL,
+  country_name VARCHAR(255) NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME NULL,
+  deleted_by BINARY(16) NULL,
+
+  KEY idx_places_location (location),
+  KEY idx_places_state (state),
+  KEY idx_places_post_code (post_code),
+  KEY idx_places_country_code (country_code),
+  KEY idx_places_deleted_at (deleted_at)
+);
+
+ALTER TABLE patient_data
+  ADD COLUMN place_id BINARY(16) NULL AFTER co_insured,
+  ADD KEY idx_patient_data_place_id (place_id),
+  ADD CONSTRAINT fk_patient_data_place
+    FOREIGN KEY (place_id) REFERENCES places (id)
+    ON UPDATE CASCADE ON DELETE SET NULL;
diff --git a/migrations/20260424_users_sortkey_for_contacts.sql b/migrations/20260424_users_sortkey_for_contacts.sql
new file mode 100644
index 0000000..79bb307
--- /dev/null
+++ b/migrations/20260424_users_sortkey_for_contacts.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+ALTER TABLE users
+  ADD COLUMN sortkey INT NULL AFTER timezone,
+  ADD KEY idx_users_sortkey (sortkey);
+
+-- +goose Down
+ALTER TABLE users
+  DROP KEY idx_users_sortkey,
+  DROP COLUMN sortkey;
diff --git a/migrations/20260424_vocations_note_sortkey_is_active.sql b/migrations/20260424_vocations_note_sortkey_is_active.sql
new file mode 100644
index 0000000..d5792e2
--- /dev/null
+++ b/migrations/20260424_vocations_note_sortkey_is_active.sql
@@ -0,0 +1,15 @@
+-- +goose Up
+ALTER TABLE vocations
+  ADD COLUMN note VARCHAR(255) NULL AFTER description,
+  ADD COLUMN sortkey INT NULL AFTER name,
+  ADD COLUMN is_active TINYINT(1) NOT NULL DEFAULT 1 AFTER sortkey,
+  ADD KEY idx_vocations_sortkey (sortkey),
+  ADD KEY idx_vocations_is_active (is_active);
+
+-- +goose Down
+ALTER TABLE vocations
+  DROP KEY idx_vocations_sortkey,
+  DROP KEY idx_vocations_is_active,
+  DROP COLUMN sortkey,
+  DROP COLUMN note,
+  DROP COLUMN is_active;
diff --git a/migrations/20260425_federal_states_sortkey_is_active.sql b/migrations/20260425_federal_states_sortkey_is_active.sql
new file mode 100644
index 0000000..0aed4e9
--- /dev/null
+++ b/migrations/20260425_federal_states_sortkey_is_active.sql
@@ -0,0 +1,13 @@
+-- +goose Up
+ALTER TABLE federal_states
+  ADD COLUMN IF NOT EXISTS sortkey INT NULL AFTER name,
+  ADD COLUMN IF NOT EXISTS is_active TINYINT(1) NOT NULL DEFAULT 1 AFTER note,
+  ADD KEY idx_federal_states_sortkey (sortkey),
+  ADD KEY idx_federal_states_is_active (is_active);
+
+-- +goose Down
+ALTER TABLE federal_states
+  DROP KEY idx_federal_states_sortkey,
+  DROP KEY idx_federal_states_is_active,
+  DROP COLUMN IF EXISTS sortkey,
+  DROP COLUMN IF EXISTS is_active;
diff --git a/migrations/20260425_hospitals_sortkey.sql b/migrations/20260425_hospitals_sortkey.sql
new file mode 100644
index 0000000..d6d094b
--- /dev/null
+++ b/migrations/20260425_hospitals_sortkey.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+ALTER TABLE hospitals
+  ADD COLUMN sortkey INT NULL AFTER hospital_name,
+  ADD KEY idx_hospitals_sortkey (sortkey);
+
+-- +goose Down
+ALTER TABLE hospitals
+  DROP KEY idx_hospitals_sortkey,
+  DROP COLUMN sortkey;
diff --git a/migrations/20260425_lands_sortkey.sql b/migrations/20260425_lands_sortkey.sql
new file mode 100644
index 0000000..adccf55
--- /dev/null
+++ b/migrations/20260425_lands_sortkey.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+ALTER TABLE lands
+  ADD COLUMN sortkey INT NULL AFTER name,
+  ADD KEY idx_lands_sortkey (sortkey);
+
+-- +goose Down
+ALTER TABLE lands
+  DROP KEY idx_lands_sortkey,
+  DROP COLUMN sortkey;
diff --git a/migrations/20260425_nationalities_sortkey_is_active.sql b/migrations/20260425_nationalities_sortkey_is_active.sql
new file mode 100644
index 0000000..f7c37ff
--- /dev/null
+++ b/migrations/20260425_nationalities_sortkey_is_active.sql
@@ -0,0 +1,13 @@
+-- +goose Up
+ALTER TABLE nationalities
+  ADD COLUMN sortkey INT NULL AFTER name,
+  ADD COLUMN is_active TINYINT(1) NOT NULL DEFAULT 1 AFTER note,
+  ADD KEY idx_nationalities_sortkey (sortkey),
+  ADD KEY idx_nationalities_is_active (is_active);
+
+-- +goose Down
+ALTER TABLE nationalities
+  DROP KEY idx_nationalities_is_active,
+  DROP KEY idx_nationalities_sortkey,
+  DROP COLUMN is_active,
+  DROP COLUMN sortkey;
diff --git a/migrations/20260427_file_lifecycle_gc.sql b/migrations/20260427_file_lifecycle_gc.sql
new file mode 100644
index 0000000..e3402d3
--- /dev/null
+++ b/migrations/20260427_file_lifecycle_gc.sql
@@ -0,0 +1,30 @@
+-- +goose Up
+ALTER TABLE file_files
+  ADD COLUMN lifecycle_status VARCHAR(32) NOT NULL DEFAULT 'temp' AFTER status,
+  ADD COLUMN attached_at DATETIME(6) NULL AFTER lifecycle_status,
+  ADD COLUMN orphaned_at DATETIME(6) NULL AFTER attached_at,
+  ADD COLUMN lifecycle_deleted_at DATETIME(6) NULL AFTER orphaned_at,
+  ADD KEY idx_file_files_lifecycle_status_orphaned (lifecycle_status, orphaned_at);
+
+UPDATE file_files
+SET lifecycle_status = CASE
+  WHEN deleted_at IS NOT NULL THEN 'deleted'
+  WHEN status = 'ready' AND name_slot = 'live' THEN 'active'
+  ELSE 'temp'
+END,
+attached_at = CASE
+  WHEN status = 'ready' AND name_slot = 'live' AND deleted_at IS NULL THEN COALESCE(attached_at, updated_at)
+  ELSE attached_at
+END,
+lifecycle_deleted_at = CASE
+  WHEN deleted_at IS NOT NULL THEN COALESCE(lifecycle_deleted_at, deleted_at)
+  ELSE lifecycle_deleted_at
+END;
+
+-- +goose Down
+ALTER TABLE file_files
+  DROP KEY idx_file_files_lifecycle_status_orphaned,
+  DROP COLUMN lifecycle_deleted_at,
+  DROP COLUMN orphaned_at,
+  DROP COLUMN attached_at,
+  DROP COLUMN lifecycle_status;
diff --git a/migrations/20260427_flights_mission_type_nullable.sql b/migrations/20260427_flights_mission_type_nullable.sql
new file mode 100644
index 0000000..c7a827a
--- /dev/null
+++ b/migrations/20260427_flights_mission_type_nullable.sql
@@ -0,0 +1,2 @@
+ALTER TABLE flights
+    MODIFY COLUMN mission_type VARCHAR(32) NULL;
diff --git a/migrations/20260429_rename_duty_roster_tables.sql b/migrations/20260429_rename_duty_roster_tables.sql
new file mode 100644
index 0000000..cc92786
--- /dev/null
+++ b/migrations/20260429_rename_duty_roster_tables.sql
@@ -0,0 +1,31 @@
+SET @has_old_rosters := (
+  SELECT COUNT(*) FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'hems_duty_rosters'
+);
+SET @has_new_rosters := (
+  SELECT COUNT(*) FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'duty_rosters'
+);
+SET @sql_rosters := IF(@has_old_rosters = 1 AND @has_new_rosters = 0,
+  'RENAME TABLE hems_duty_rosters TO duty_rosters',
+  'SELECT 1'
+);
+PREPARE stmt_rosters FROM @sql_rosters;
+EXECUTE stmt_rosters;
+DEALLOCATE PREPARE stmt_rosters;
+
+SET @has_old_crews := (
+  SELECT COUNT(*) FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'hems_duty_roster_crews'
+);
+SET @has_new_crews := (
+  SELECT COUNT(*) FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'duty_roster_crews'
+);
+SET @sql_crews := IF(@has_old_crews = 1 AND @has_new_crews = 0,
+  'RENAME TABLE hems_duty_roster_crews TO duty_roster_crews',
+  'SELECT 1'
+);
+PREPARE stmt_crews FROM @sql_crews;
+EXECUTE stmt_crews;
+DEALLOCATE PREPARE stmt_crews;
diff --git a/migrations/20260430_normalize_duty_roster_legacy.sql b/migrations/20260430_normalize_duty_roster_legacy.sql
new file mode 100644
index 0000000..8a36db4
--- /dev/null
+++ b/migrations/20260430_normalize_duty_roster_legacy.sql
@@ -0,0 +1,135 @@
+-- +goose Up
+-- Normalize legacy HEMS duty roster artifacts into neutral duty roster naming.
+
+-- 1) Rename legacy tables when old name exists and new name does not.
+SET @has_old_rosters := (
+  SELECT COUNT(*) FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'hems_duty_rosters'
+);
+SET @has_new_rosters := (
+  SELECT COUNT(*) FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'duty_rosters'
+);
+SET @sql_rename_rosters := IF(@has_old_rosters = 1 AND @has_new_rosters = 0,
+  'RENAME TABLE hems_duty_rosters TO duty_rosters',
+  'SELECT 1'
+);
+PREPARE stmt_rename_rosters FROM @sql_rename_rosters;
+EXECUTE stmt_rename_rosters;
+DEALLOCATE PREPARE stmt_rename_rosters;
+
+SET @has_old_crews := (
+  SELECT COUNT(*) FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'hems_duty_roster_crews'
+);
+SET @has_new_crews := (
+  SELECT COUNT(*) FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'duty_roster_crews'
+);
+SET @sql_rename_crews := IF(@has_old_crews = 1 AND @has_new_crews = 0,
+  'RENAME TABLE hems_duty_roster_crews TO duty_roster_crews',
+  'SELECT 1'
+);
+PREPARE stmt_rename_crews FROM @sql_rename_crews;
+EXECUTE stmt_rename_crews;
+DEALLOCATE PREPARE stmt_rename_crews;
+
+-- 2) Rename legacy header column.
+SET @has_duty_rosters := (
+  SELECT COUNT(*) FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'duty_rosters'
+);
+SET @has_hems_base_id := (
+  SELECT COUNT(*) FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = DATABASE()
+    AND TABLE_NAME = 'duty_rosters'
+    AND COLUMN_NAME = 'hems_base_id'
+);
+SET @has_base_id := (
+  SELECT COUNT(*) FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = DATABASE()
+    AND TABLE_NAME = 'duty_rosters'
+    AND COLUMN_NAME = 'base_id'
+);
+SET @sql_rename_base_col := IF(@has_duty_rosters = 1 AND @has_hems_base_id = 1 AND @has_base_id = 0,
+  'ALTER TABLE duty_rosters RENAME COLUMN hems_base_id TO base_id',
+  'SELECT 1'
+);
+PREPARE stmt_rename_base_col FROM @sql_rename_base_col;
+EXECUTE stmt_rename_base_col;
+DEALLOCATE PREPARE stmt_rename_base_col;
+
+-- 3) Ensure confirm_at exists on normalized crews table.
+SET @has_confirm_at_new_crews := (
+  SELECT COUNT(*) FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = DATABASE()
+    AND TABLE_NAME = 'duty_roster_crews'
+    AND COLUMN_NAME = 'confirm_at'
+);
+SET @sql_add_confirm_at_new_crews := IF(@has_new_crews = 1 AND @has_confirm_at_new_crews = 0,
+  'ALTER TABLE duty_roster_crews ADD COLUMN confirm_at DATETIME NULL AFTER email',
+  'SELECT 1'
+);
+PREPARE stmt_add_confirm_at_new_crews FROM @sql_add_confirm_at_new_crews;
+EXECUTE stmt_add_confirm_at_new_crews;
+DEALLOCATE PREPARE stmt_add_confirm_at_new_crews;
+
+-- 4) If legacy crew table still exists, keep it compatible too.
+SET @has_confirm_at_old_crews := (
+  SELECT COUNT(*) FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = DATABASE()
+    AND TABLE_NAME = 'hems_duty_roster_crews'
+    AND COLUMN_NAME = 'confirm_at'
+);
+SET @sql_add_confirm_at_old_crews := IF(@has_old_crews = 1 AND @has_confirm_at_old_crews = 0,
+  'ALTER TABLE hems_duty_roster_crews ADD COLUMN confirm_at DATETIME NULL AFTER email',
+  'SELECT 1'
+);
+PREPARE stmt_add_confirm_at_old_crews FROM @sql_add_confirm_at_old_crews;
+EXECUTE stmt_add_confirm_at_old_crews;
+DEALLOCATE PREPARE stmt_add_confirm_at_old_crews;
+
+-- 5) Normalize legacy FK references to duty_rosters where needed.
+SET @fk_roster_crews_ref := (
+  SELECT COALESCE(MAX(kcu.REFERENCED_TABLE_NAME), '')
+  FROM information_schema.TABLE_CONSTRAINTS tc
+  JOIN information_schema.KEY_COLUMN_USAGE kcu
+    ON tc.CONSTRAINT_SCHEMA = kcu.CONSTRAINT_SCHEMA
+   AND tc.TABLE_NAME = kcu.TABLE_NAME
+   AND tc.CONSTRAINT_NAME = kcu.CONSTRAINT_NAME
+  WHERE tc.CONSTRAINT_SCHEMA = DATABASE()
+    AND tc.TABLE_NAME = 'roster_crews'
+    AND tc.CONSTRAINT_TYPE = 'FOREIGN KEY'
+    AND tc.CONSTRAINT_NAME = 'fk_roster_crews_roster'
+);
+SET @sql_rewire_roster_crews_fk := IF(@has_new_rosters = 1 AND @fk_roster_crews_ref = 'hems_duty_rosters',
+  'ALTER TABLE roster_crews DROP FOREIGN KEY fk_roster_crews_roster, ADD CONSTRAINT fk_roster_crews_roster FOREIGN KEY (roster_id) REFERENCES duty_rosters(id)',
+  'SELECT 1'
+);
+PREPARE stmt_rewire_roster_crews_fk FROM @sql_rewire_roster_crews_fk;
+EXECUTE stmt_rewire_roster_crews_fk;
+DEALLOCATE PREPARE stmt_rewire_roster_crews_fk;
+
+SET @fk_other_persons_ref := (
+  SELECT COALESCE(MAX(kcu.REFERENCED_TABLE_NAME), '')
+  FROM information_schema.TABLE_CONSTRAINTS tc
+  JOIN information_schema.KEY_COLUMN_USAGE kcu
+    ON tc.CONSTRAINT_SCHEMA = kcu.CONSTRAINT_SCHEMA
+   AND tc.TABLE_NAME = kcu.TABLE_NAME
+   AND tc.CONSTRAINT_NAME = kcu.CONSTRAINT_NAME
+  WHERE tc.CONSTRAINT_SCHEMA = DATABASE()
+    AND tc.TABLE_NAME = 'duty_roster_other_persons'
+    AND tc.CONSTRAINT_TYPE = 'FOREIGN KEY'
+    AND tc.CONSTRAINT_NAME = 'fk_duty_roster_other_persons_roster'
+);
+SET @sql_rewire_other_persons_fk := IF(@has_new_rosters = 1 AND @fk_other_persons_ref = 'hems_duty_rosters',
+  'ALTER TABLE duty_roster_other_persons DROP FOREIGN KEY fk_duty_roster_other_persons_roster, ADD CONSTRAINT fk_duty_roster_other_persons_roster FOREIGN KEY (roster_id) REFERENCES duty_rosters(id)',
+  'SELECT 1'
+);
+PREPARE stmt_rewire_other_persons_fk FROM @sql_rewire_other_persons_fk;
+EXECUTE stmt_rewire_other_persons_fk;
+DEALLOCATE PREPARE stmt_rewire_other_persons_fk;
+
+-- +goose Down
+-- Intentionally no-op: legacy normalization is one-way to keep schema stable.
+SELECT 1;
diff --git a/migrations/20260430_users_sso_email.sql b/migrations/20260430_users_sso_email.sql
new file mode 100644
index 0000000..410f1e8
--- /dev/null
+++ b/migrations/20260430_users_sso_email.sql
@@ -0,0 +1,2 @@
+ALTER TABLE users
+  ADD COLUMN sso_email VARCHAR(191) NULL AFTER email;
diff --git a/migrations/20260502_cleanup_legacy_hems_bases.sql b/migrations/20260502_cleanup_legacy_hems_bases.sql
new file mode 100644
index 0000000..b2da027
--- /dev/null
+++ b/migrations/20260502_cleanup_legacy_hems_bases.sql
@@ -0,0 +1,116 @@
+-- Cleanup legacy hems_bases table after consolidation to unified bases table.
+-- Safe/idempotent behavior:
+-- 1) If only hems_bases exists -> rename to bases.
+-- 2) If both tables exist -> copy missing rows from hems_bases into bases as HEMS category.
+-- 3) Drop hems_bases afterwards when possible.
+
+SET @schema := DATABASE();
+
+SET @has_hems_bases := (
+  SELECT COUNT(*)
+  FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = @schema AND TABLE_NAME = 'hems_bases'
+);
+
+SET @has_bases := (
+  SELECT COUNT(*)
+  FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = @schema AND TABLE_NAME = 'bases'
+);
+
+-- Ensure HEMS category exists when unified bases table is present.
+SET @has_base_categories := (
+  SELECT COUNT(*)
+  FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = @schema AND TABLE_NAME = 'base_categories'
+);
+
+SET @sql_seed_hems_category := IF(@has_bases = 1 AND @has_base_categories = 1,
+  'INSERT INTO base_categories (id, `key`, name, created_at, updated_at)
+   SELECT UUID_TO_BIN(UUID(), true), ''hems'', ''HEMS Base'', UTC_TIMESTAMP(3), UTC_TIMESTAMP(3)
+   WHERE NOT EXISTS (
+     SELECT 1 FROM base_categories WHERE `key` = ''hems''
+   )',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql_seed_hems_category;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+-- Case A: legacy only => rename directly.
+SET @sql_rename_hems_bases := IF(@has_hems_bases = 1 AND @has_bases = 0,
+  'RENAME TABLE hems_bases TO bases',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql_rename_hems_bases;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+-- Re-evaluate after possible rename.
+SET @has_hems_bases := (
+  SELECT COUNT(*)
+  FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = @schema AND TABLE_NAME = 'hems_bases'
+);
+
+SET @has_bases := (
+  SELECT COUNT(*)
+  FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = @schema AND TABLE_NAME = 'bases'
+);
+
+-- Case B: both exist => backfill rows from legacy table into unified table.
+SET @sql_backfill := IF(@has_hems_bases = 1 AND @has_bases = 1,
+  'INSERT INTO bases (
+      id, base, base_category_id, base_abbreviation, address,
+      landline_number, mobile_number, email,
+      position, sms_alert, checklist, leg_time,
+      default_shift_time, utc, foto,
+      dry, control_center, dul, visible,
+      notes, is_active,
+      created_by, updated_by, created_at, updated_at
+    )
+    SELECT
+      hb.id,
+      hb.base,
+      bc.id,
+      hb.base_abbreviation,
+      hb.address,
+      hb.landline_number,
+      hb.mobile_number,
+      hb.email,
+      hb.position,
+      hb.sms_alert,
+      hb.checklist,
+      hb.leg_time,
+      hb.default_shift_time,
+      hb.utc,
+      hb.foto,
+      hb.dry,
+      hb.control_center,
+      hb.dul,
+      hb.visible,
+      hb.notes,
+      hb.is_active,
+      hb.created_by,
+      hb.updated_by,
+      hb.created_at,
+      hb.updated_at
+    FROM hems_bases hb
+    LEFT JOIN base_categories bc ON bc.`key` = ''hems''
+    LEFT JOIN bases b ON b.id = hb.id
+    WHERE b.id IS NULL',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql_backfill;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+-- Drop legacy table if still present.
+SET @sql_drop_hems_bases := IF(@has_hems_bases = 1,
+  'DROP TABLE hems_bases',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql_drop_hems_bases;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
diff --git a/migrations/20260502_duty_roster_permissions_unification.sql b/migrations/20260502_duty_roster_permissions_unification.sql
new file mode 100644
index 0000000..9f4dc83
--- /dev/null
+++ b/migrations/20260502_duty_roster_permissions_unification.sql
@@ -0,0 +1,36 @@
+-- Add canonical duty_roster permissions and map existing role grants from legacy hems_duty_roster keys.
+
+INSERT INTO permissions (id, name, `key`, description, requires_pin, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID(), true), 'Create Duty Roster', 'duty_roster.create', 'Create duty roster', 0, UTC_TIMESTAMP(), UTC_TIMESTAMP()
+WHERE NOT EXISTS (SELECT 1 FROM permissions WHERE `key` = 'duty_roster.create');
+
+INSERT INTO permissions (id, name, `key`, description, requires_pin, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID(), true), 'Read Duty Roster', 'duty_roster.read', 'Read duty roster', 0, UTC_TIMESTAMP(), UTC_TIMESTAMP()
+WHERE NOT EXISTS (SELECT 1 FROM permissions WHERE `key` = 'duty_roster.read');
+
+INSERT INTO permissions (id, name, `key`, description, requires_pin, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID(), true), 'Update Duty Roster', 'duty_roster.update', 'Update duty roster', 0, UTC_TIMESTAMP(), UTC_TIMESTAMP()
+WHERE NOT EXISTS (SELECT 1 FROM permissions WHERE `key` = 'duty_roster.update');
+
+INSERT INTO permissions (id, name, `key`, description, requires_pin, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID(), true), 'Delete Duty Roster', 'duty_roster.delete', 'Delete duty roster', 0, UTC_TIMESTAMP(), UTC_TIMESTAMP()
+WHERE NOT EXISTS (SELECT 1 FROM permissions WHERE `key` = 'duty_roster.delete');
+
+INSERT INTO role_permissions (id, role_id, permission_id, created_at, updated_at)
+SELECT
+  UUID_TO_BIN(UUID(), true),
+  rp.role_id,
+  p_new.id,
+  UTC_TIMESTAMP(),
+  UTC_TIMESTAMP()
+FROM role_permissions rp
+JOIN permissions p_old ON p_old.id = rp.permission_id
+JOIN permissions p_new ON p_new.`key` = CONCAT('duty_roster.', SUBSTRING_INDEX(p_old.`key`, '.', -1))
+LEFT JOIN role_permissions rp_existing ON rp_existing.role_id = rp.role_id AND rp_existing.permission_id = p_new.id
+WHERE p_old.`key` IN (
+  'hems_duty_roster.create',
+  'hems_duty_roster.read',
+  'hems_duty_roster.update',
+  'hems_duty_roster.delete'
+)
+AND rp_existing.id IS NULL;
diff --git a/migrations/20260502_purge_legacy_hems_duty_roster_permissions.sql b/migrations/20260502_purge_legacy_hems_duty_roster_permissions.sql
new file mode 100644
index 0000000..a05381c
--- /dev/null
+++ b/migrations/20260502_purge_legacy_hems_duty_roster_permissions.sql
@@ -0,0 +1,59 @@
+-- Purge legacy hems_duty_roster.* permissions.
+-- Safe flow:
+-- 1) Ensure canonical duty_roster.* permissions exist.
+-- 2) Grant canonical permission to any role that still has legacy permission.
+-- 3) Remove legacy role_permissions rows.
+-- 4) Remove legacy permission rows.
+
+INSERT INTO permissions (id, name, `key`, description, requires_pin, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID(), true), 'Create Duty Roster', 'duty_roster.create', 'Create duty roster', 0, UTC_TIMESTAMP(), UTC_TIMESTAMP()
+WHERE NOT EXISTS (SELECT 1 FROM permissions WHERE `key` = 'duty_roster.create');
+
+INSERT INTO permissions (id, name, `key`, description, requires_pin, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID(), true), 'Read Duty Roster', 'duty_roster.read', 'Read duty roster', 0, UTC_TIMESTAMP(), UTC_TIMESTAMP()
+WHERE NOT EXISTS (SELECT 1 FROM permissions WHERE `key` = 'duty_roster.read');
+
+INSERT INTO permissions (id, name, `key`, description, requires_pin, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID(), true), 'Update Duty Roster', 'duty_roster.update', 'Update duty roster', 0, UTC_TIMESTAMP(), UTC_TIMESTAMP()
+WHERE NOT EXISTS (SELECT 1 FROM permissions WHERE `key` = 'duty_roster.update');
+
+INSERT INTO permissions (id, name, `key`, description, requires_pin, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID(), true), 'Delete Duty Roster', 'duty_roster.delete', 'Delete duty roster', 0, UTC_TIMESTAMP(), UTC_TIMESTAMP()
+WHERE NOT EXISTS (SELECT 1 FROM permissions WHERE `key` = 'duty_roster.delete');
+
+INSERT INTO role_permissions (id, role_id, permission_id, created_at, updated_at)
+SELECT
+  UUID_TO_BIN(UUID(), true),
+  rp.role_id,
+  p_new.id,
+  UTC_TIMESTAMP(),
+  UTC_TIMESTAMP()
+FROM role_permissions rp
+JOIN permissions p_old ON p_old.id = rp.permission_id
+JOIN permissions p_new ON p_new.`key` = CONCAT('duty_roster.', SUBSTRING_INDEX(p_old.`key`, '.', -1))
+LEFT JOIN role_permissions rp_existing ON rp_existing.role_id = rp.role_id AND rp_existing.permission_id = p_new.id
+WHERE p_old.`key` IN (
+  'hems_duty_roster.create',
+  'hems_duty_roster.read',
+  'hems_duty_roster.update',
+  'hems_duty_roster.delete'
+)
+AND rp_existing.id IS NULL;
+
+DELETE rp
+FROM role_permissions rp
+JOIN permissions p ON p.id = rp.permission_id
+WHERE p.`key` IN (
+  'hems_duty_roster.create',
+  'hems_duty_roster.read',
+  'hems_duty_roster.update',
+  'hems_duty_roster.delete'
+);
+
+DELETE FROM permissions
+WHERE `key` IN (
+  'hems_duty_roster.create',
+  'hems_duty_roster.read',
+  'hems_duty_roster.update',
+  'hems_duty_roster.delete'
+);
diff --git a/migrations/20260504_duty_roster_drop_unique_base_date.sql b/migrations/20260504_duty_roster_drop_unique_base_date.sql
new file mode 100644
index 0000000..4c5bd80
--- /dev/null
+++ b/migrations/20260504_duty_roster_drop_unique_base_date.sql
@@ -0,0 +1,9 @@
+-- Allow multiple duty roster headers on the same base and duty date.
+-- Previous schema enforced unique(base_id, duty_date) via idx_roster_base_date.
+
+ALTER TABLE duty_rosters
+  DROP INDEX idx_roster_base_date;
+
+CREATE INDEX idx_roster_base_date
+  ON duty_rosters (base_id, duty_date);
+
diff --git a/migrations/20260505_drop_description_note_federal_states_lands_nationalities.sql b/migrations/20260505_drop_description_note_federal_states_lands_nationalities.sql
new file mode 100644
index 0000000..c3516fb
--- /dev/null
+++ b/migrations/20260505_drop_description_note_federal_states_lands_nationalities.sql
@@ -0,0 +1,169 @@
+-- +goose Up
+SET @sql := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1 FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'federal_states' AND COLUMN_NAME = 'description'
+    ),
+    'ALTER TABLE federal_states DROP COLUMN description',
+    'SELECT 1'
+  )
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+SET @sql := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1 FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'federal_states' AND COLUMN_NAME = 'note'
+    ),
+    'ALTER TABLE federal_states DROP COLUMN note',
+    'SELECT 1'
+  )
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+SET @sql := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1 FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'lands' AND COLUMN_NAME = 'description'
+    ),
+    'ALTER TABLE lands DROP COLUMN description',
+    'SELECT 1'
+  )
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+SET @sql := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1 FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'lands' AND COLUMN_NAME = 'note'
+    ),
+    'ALTER TABLE lands DROP COLUMN note',
+    'SELECT 1'
+  )
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+SET @sql := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1 FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'nationalities' AND COLUMN_NAME = 'description'
+    ),
+    'ALTER TABLE nationalities DROP COLUMN description',
+    'SELECT 1'
+  )
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+SET @sql := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1 FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'nationalities' AND COLUMN_NAME = 'note'
+    ),
+    'ALTER TABLE nationalities DROP COLUMN note',
+    'SELECT 1'
+  )
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+-- +goose Down
+SET @sql := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1 FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'federal_states' AND COLUMN_NAME = 'description'
+    ),
+    'SELECT 1',
+    'ALTER TABLE federal_states ADD COLUMN description VARCHAR(256) NULL AFTER sortkey'
+  )
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+SET @sql := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1 FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'federal_states' AND COLUMN_NAME = 'note'
+    ),
+    'SELECT 1',
+    'ALTER TABLE federal_states ADD COLUMN note TEXT NULL AFTER description'
+  )
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+SET @sql := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1 FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'lands' AND COLUMN_NAME = 'description'
+    ),
+    'SELECT 1',
+    'ALTER TABLE lands ADD COLUMN description VARCHAR(256) NULL AFTER sortkey'
+  )
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+SET @sql := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1 FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'lands' AND COLUMN_NAME = 'note'
+    ),
+    'SELECT 1',
+    'ALTER TABLE lands ADD COLUMN note TEXT NULL AFTER description'
+  )
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+SET @sql := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1 FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'nationalities' AND COLUMN_NAME = 'description'
+    ),
+    'SELECT 1',
+    'ALTER TABLE nationalities ADD COLUMN description VARCHAR(256) NULL AFTER sortkey'
+  )
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+SET @sql := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1 FROM information_schema.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'nationalities' AND COLUMN_NAME = 'note'
+    ),
+    'SELECT 1',
+    'ALTER TABLE nationalities ADD COLUMN note TEXT NULL AFTER description'
+  )
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
diff --git a/migrations/20260505_seed_lands_from_legacy_country.sql b/migrations/20260505_seed_lands_from_legacy_country.sql
new file mode 100644
index 0000000..5e7a789
--- /dev/null
+++ b/migrations/20260505_seed_lands_from_legacy_country.sql
@@ -0,0 +1,265 @@
+-- +goose Up
+INSERT INTO lands (id, name, land_iso_code, sortkey, is_active, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID()), src.name, src.iso_code, src.sortkey, 1, NOW(3), NOW(3)
+FROM (
+  SELECT 'AC' AS iso_code, 'Ascension' AS name, 1 AS sortkey
+  UNION ALL SELECT 'AD', 'Andorra', 2
+  UNION ALL SELECT 'AE', 'Vereinigte Arabische Emirate', 3
+  UNION ALL SELECT 'AF', 'Afghanistan', 4
+  UNION ALL SELECT 'AG', 'Antigua und Barbuda', 5
+  UNION ALL SELECT 'AI', 'Anguilla', 6
+  UNION ALL SELECT 'AL', 'Albanien', 7
+  UNION ALL SELECT 'AM', 'Armenien', 8
+  UNION ALL SELECT 'AN', 'Niederländische Antillen', 9
+  UNION ALL SELECT 'AO', 'Angola', 10
+  UNION ALL SELECT 'AQ', 'Antarktis', 11
+  UNION ALL SELECT 'AR', 'Argentinien', 12
+  UNION ALL SELECT 'AS', 'Amerikanisch Samoa', 13
+  UNION ALL SELECT 'AT', 'Österreich', 14
+  UNION ALL SELECT 'AU', 'Australien', 15
+  UNION ALL SELECT 'AW', 'Aruba', 16
+  UNION ALL SELECT 'AX', 'Aland', 17
+  UNION ALL SELECT 'AZ', 'Aserbaidschan', 18
+  UNION ALL SELECT 'BA', 'Bosnien-Herzegowina', 19
+  UNION ALL SELECT 'BB', 'Barbados', 20
+  UNION ALL SELECT 'BD', 'Bangladesch', 21
+  UNION ALL SELECT 'BE', 'Belgien', 22
+  UNION ALL SELECT 'BF', 'Burkina Faso', 23
+  UNION ALL SELECT 'BG', 'Bulgarien', 24
+  UNION ALL SELECT 'BH', 'Bahrain', 25
+  UNION ALL SELECT 'BJ', 'Benin', 26
+  UNION ALL SELECT 'BL', 'Burundi', 27
+  UNION ALL SELECT 'BM', 'Bermuda', 28
+  UNION ALL SELECT 'BN', 'Brunei Darussalam', 29
+  UNION ALL SELECT 'BO', 'Bolivien', 30
+  UNION ALL SELECT 'BR', 'Brasilien', 31
+  UNION ALL SELECT 'BS', 'Bahamas', 32
+  UNION ALL SELECT 'BT', 'Bhutan', 33
+  UNION ALL SELECT 'BV', 'Bouvetinseln', 34
+  UNION ALL SELECT 'BW', 'Botsuana', 35
+  UNION ALL SELECT 'BY', 'Belarus', 36
+  UNION ALL SELECT 'BZ', 'Belize ', 37
+  UNION ALL SELECT 'CA', 'Kanada', 38
+  UNION ALL SELECT 'CC', 'Kokosinseln', 39
+  UNION ALL SELECT 'CD', 'Demokratische Republik Kongo', 40
+  UNION ALL SELECT 'CF', 'Zentralafrikanische Republik', 41
+  UNION ALL SELECT 'CG', 'Kongo', 42
+  UNION ALL SELECT 'CH', 'Schweiz', 43
+  UNION ALL SELECT 'CI', 'Elfenbeinküste', 44
+  UNION ALL SELECT 'CK', 'Cookinseln', 45
+  UNION ALL SELECT 'CL', 'Chile', 46
+  UNION ALL SELECT 'CM', 'Kamerun', 47
+  UNION ALL SELECT 'CO', 'Kolumbien', 48
+  UNION ALL SELECT 'CR', 'Costa Rica', 49
+  UNION ALL SELECT 'CU', 'Kuba', 50
+  UNION ALL SELECT 'CV', 'Kap Verde', 51
+  UNION ALL SELECT 'CX', 'Weihnachtsinsel', 52
+  UNION ALL SELECT 'CY', 'Zypern', 53
+  UNION ALL SELECT 'CZ', 'Tschechische Republik', 54
+  UNION ALL SELECT 'DB', 'Dubai', 55
+  UNION ALL SELECT 'DE', 'Deutschland', 56
+  UNION ALL SELECT 'DJ', 'Dschibuti', 57
+  UNION ALL SELECT 'DK', 'Dänemark', 58
+  UNION ALL SELECT 'DM', 'Dominica', 59
+  UNION ALL SELECT 'DO', 'Dominikanische Republik', 60
+  UNION ALL SELECT 'DZ', 'Algerien', 61
+  UNION ALL SELECT 'EC', 'Ecuador', 62
+  UNION ALL SELECT 'EE', 'Estland', 63
+  UNION ALL SELECT 'EG', 'Ägypten', 64
+  UNION ALL SELECT 'EH', 'Western Sahara', 65
+  UNION ALL SELECT 'ER', 'Eritrea', 66
+  UNION ALL SELECT 'ES', 'Spanien', 67
+  UNION ALL SELECT 'ET', 'Äthiopien', 68
+  UNION ALL SELECT 'FI', 'Finnland', 69
+  UNION ALL SELECT 'FJ', 'Fidschi', 70
+  UNION ALL SELECT 'FK', 'Falklandinseln', 71
+  UNION ALL SELECT 'FM', 'Mikronesien', 72
+  UNION ALL SELECT 'FO', 'Färöer', 73
+  UNION ALL SELECT 'FR', 'Frankreich', 74
+  UNION ALL SELECT 'GA', 'Gabun', 75
+  UNION ALL SELECT 'GB', 'Vereinigtes Königreich', 76
+  UNION ALL SELECT 'GD', 'Grenada', 77
+  UNION ALL SELECT 'GE', 'Georgien', 78
+  UNION ALL SELECT 'GF', 'Französische Guyana', 79
+  UNION ALL SELECT 'GG', 'Guernsey', 80
+  UNION ALL SELECT 'GH', 'Ghana', 81
+  UNION ALL SELECT 'GI', 'Gibraltar', 82
+  UNION ALL SELECT 'GL', 'Grönland', 83
+  UNION ALL SELECT 'GM', 'Gambia', 84
+  UNION ALL SELECT 'GN', 'Guinea', 85
+  UNION ALL SELECT 'GP', 'Guadeloupe', 86
+  UNION ALL SELECT 'GQ', 'Äquatorialguinea', 87
+  UNION ALL SELECT 'GR', 'Griechenland', 88
+  UNION ALL SELECT 'GS', 'South Georgia and the South Sandwich Islands', 89
+  UNION ALL SELECT 'GT', 'Guatemala', 90
+  UNION ALL SELECT 'GU', 'Guam', 91
+  UNION ALL SELECT 'GW', 'Guinea-Bissau', 92
+  UNION ALL SELECT 'GY', 'Guyana', 93
+  UNION ALL SELECT 'HK', 'Hong Kong', 94
+  UNION ALL SELECT 'HM', 'Heard Island and McDonald Islands', 95
+  UNION ALL SELECT 'HN', 'Honduras', 96
+  UNION ALL SELECT 'HR', 'Kroatien', 97
+  UNION ALL SELECT 'HT', 'Haiti', 98
+  UNION ALL SELECT 'HU', 'Ungarn', 99
+  UNION ALL SELECT 'ID', 'Indonesien', 100
+  UNION ALL SELECT 'IE', 'Irland', 101
+  UNION ALL SELECT 'IL', 'Israel', 102
+  UNION ALL SELECT 'IM', 'Isle of Man', 103
+  UNION ALL SELECT 'IN', 'Indien', 104
+  UNION ALL SELECT 'IO', 'Br.Territ./Ind.Ozean', 105
+  UNION ALL SELECT 'IQ', 'Irak', 106
+  UNION ALL SELECT 'IR', 'Iran', 107
+  UNION ALL SELECT 'IS', 'Island', 108
+  UNION ALL SELECT 'IT', 'Italien', 109
+  UNION ALL SELECT 'JE', 'Jersey', 110
+  UNION ALL SELECT 'JM', 'Jamaika', 111
+  UNION ALL SELECT 'JO', 'Jordanien', 112
+  UNION ALL SELECT 'JP', 'Japan', 113
+  UNION ALL SELECT 'KE', 'Kenien', 114
+  UNION ALL SELECT 'KG', 'Kirgisistan', 115
+  UNION ALL SELECT 'KH', 'Kambodscha', 116
+  UNION ALL SELECT 'KI', 'Kiribati', 117
+  UNION ALL SELECT 'KM', 'Komoren', 118
+  UNION ALL SELECT 'KN', 'St. Kittis und Nevis', 119
+  UNION ALL SELECT 'KO', 'Kosovo', 120
+  UNION ALL SELECT 'KP', 'Korea, Demo. VR', 121
+  UNION ALL SELECT 'KR', 'Korea', 122
+  UNION ALL SELECT 'KW', 'Kuwait', 123
+  UNION ALL SELECT 'KY', 'Kaimaninseln', 124
+  UNION ALL SELECT 'KZ', 'Kasachstan', 125
+  UNION ALL SELECT 'LA', 'Laos', 126
+  UNION ALL SELECT 'LB', 'Libanon', 127
+  UNION ALL SELECT 'LC', 'Sankt Lucia', 128
+  UNION ALL SELECT 'LI', 'Liechtenstein', 129
+  UNION ALL SELECT 'LK', 'Sri Lanka', 130
+  UNION ALL SELECT 'LR', 'Liberia', 131
+  UNION ALL SELECT 'LS', 'Lesotho', 132
+  UNION ALL SELECT 'LT', 'Litauen', 133
+  UNION ALL SELECT 'LU', 'Luxemburg', 134
+  UNION ALL SELECT 'LV', 'Lettland', 135
+  UNION ALL SELECT 'LY', 'Lybien', 136
+  UNION ALL SELECT 'MA', 'Marokko', 137
+  UNION ALL SELECT 'MC', 'Monaco', 138
+  UNION ALL SELECT 'MD', 'Moldova', 139
+  UNION ALL SELECT 'ME', 'Montenegro', 140
+  UNION ALL SELECT 'MG', 'Madagaskar', 141
+  UNION ALL SELECT 'MH', 'Marshallinseln', 142
+  UNION ALL SELECT 'MK', 'Mazedonien', 143
+  UNION ALL SELECT 'ML', 'Mali', 144
+  UNION ALL SELECT 'MM', 'Myanmar', 145
+  UNION ALL SELECT 'MN', 'Mongolei', 146
+  UNION ALL SELECT 'MO', 'Macau', 147
+  UNION ALL SELECT 'MP', 'Marianen', 148
+  UNION ALL SELECT 'MQ', 'Martinique', 149
+  UNION ALL SELECT 'MR', 'Mauretanien', 150
+  UNION ALL SELECT 'MS', 'Montserrat', 151
+  UNION ALL SELECT 'MT', 'Malta', 152
+  UNION ALL SELECT 'MU', 'Mauritius', 153
+  UNION ALL SELECT 'MV', 'Malediven', 154
+  UNION ALL SELECT 'MW', 'Malawi', 155
+  UNION ALL SELECT 'MX', 'Mexiko', 156
+  UNION ALL SELECT 'MY', 'Malaysia', 157
+  UNION ALL SELECT 'MZ', 'Mosambik', 158
+  UNION ALL SELECT 'NA', 'Namibia', 159
+  UNION ALL SELECT 'NC', 'Neukaledonien', 160
+  UNION ALL SELECT 'NE', 'Niger', 161
+  UNION ALL SELECT 'NF', 'Norfolkins', 162
+  UNION ALL SELECT 'NG', 'Nigeria', 163
+  UNION ALL SELECT 'NI', 'Nicaragua', 164
+  UNION ALL SELECT 'NL', 'Niederlande', 165
+  UNION ALL SELECT 'NO', 'Norwegen', 166
+  UNION ALL SELECT 'NP', 'Nepal', 167
+  UNION ALL SELECT 'NR', 'Nauru', 168
+  UNION ALL SELECT 'NU', 'Niue', 169
+  UNION ALL SELECT 'NZ', 'Neuseeland', 170
+  UNION ALL SELECT 'O', 'unbekannt', 171
+  UNION ALL SELECT 'OM', 'Oman', 172
+  UNION ALL SELECT 'PA', 'Panama', 173
+  UNION ALL SELECT 'PE', 'Peru', 174
+  UNION ALL SELECT 'PF', 'Französchisch Polynesien', 175
+  UNION ALL SELECT 'PG', 'Papua Neuguinea', 176
+  UNION ALL SELECT 'PH', 'Philippinen', 177
+  UNION ALL SELECT 'PK', 'Pakistan', 178
+  UNION ALL SELECT 'PL', 'Polen', 179
+  UNION ALL SELECT 'PM', 'St Pierre und Miquelon', 180
+  UNION ALL SELECT 'PN', 'Pitkern', 181
+  UNION ALL SELECT 'PR', 'Puerto Rico', 182
+  UNION ALL SELECT 'PS', 'Palestina', 183
+  UNION ALL SELECT 'PT', 'Portugal', 184
+  UNION ALL SELECT 'PW', 'Palau', 185
+  UNION ALL SELECT 'PY', 'Paraguay', 186
+  UNION ALL SELECT 'Q', 'Katar', 187
+  UNION ALL SELECT 'RE', 'Reunion', 188
+  UNION ALL SELECT 'RM', 'San Marino', 189
+  UNION ALL SELECT 'RO', 'Rumänien', 190
+  UNION ALL SELECT 'RS', 'Serbien', 191
+  UNION ALL SELECT 'RU', 'Russische Föderation', 192
+  UNION ALL SELECT 'RW', 'Ruanda', 193
+  UNION ALL SELECT 'SA', 'Saudi Arabien', 194
+  UNION ALL SELECT 'SB', 'Salomonen', 195
+  UNION ALL SELECT 'SC', 'Seychellen', 196
+  UNION ALL SELECT 'SD', 'Sudan', 197
+  UNION ALL SELECT 'SE', 'Schweden', 198
+  UNION ALL SELECT 'SG', 'Singapur', 199
+  UNION ALL SELECT 'SH', 'Sankt Helena', 200
+  UNION ALL SELECT 'SI', 'Slowenien', 201
+  UNION ALL SELECT 'SJ', 'Svalbard', 202
+  UNION ALL SELECT 'SK', 'Slowakei', 203
+  UNION ALL SELECT 'SL', 'Sierra Leone', 204
+  UNION ALL SELECT 'SN', 'Senegal', 205
+  UNION ALL SELECT 'SO', 'Somalia', 206
+  UNION ALL SELECT 'SR', 'Suriname', 207
+  UNION ALL SELECT 'ST', 'Sao Tome und Pricipe', 208
+  UNION ALL SELECT 'SV', 'El Salvador', 209
+  UNION ALL SELECT 'SY', 'Syrien', 210
+  UNION ALL SELECT 'SZ', 'Swasiland', 211
+  UNION ALL SELECT 'TA', 'Tristan da Cunha', 212
+  UNION ALL SELECT 'TC', 'Turks und Caicosinseln', 213
+  UNION ALL SELECT 'TD', 'Tschad', 214
+  UNION ALL SELECT 'TF', 'French Southern and Antarctic Lands', 215
+  UNION ALL SELECT 'TG', 'Togo', 216
+  UNION ALL SELECT 'TH', 'Thailand', 217
+  UNION ALL SELECT 'TI', 'Timor Leste', 218
+  UNION ALL SELECT 'TJ', 'Tadschikistan', 219
+  UNION ALL SELECT 'TK', 'Tokelau', 220
+  UNION ALL SELECT 'TL', 'Ost-Timor', 221
+  UNION ALL SELECT 'TM', 'Turkmenistan', 222
+  UNION ALL SELECT 'TN', 'Tunesien', 223
+  UNION ALL SELECT 'TO', 'Tonga', 224
+  UNION ALL SELECT 'TP', 'Osttimor', 225
+  UNION ALL SELECT 'TR', 'Türkei', 226
+  UNION ALL SELECT 'TT', 'Trinidad und Tobago', 227
+  UNION ALL SELECT 'TV', 'Tuvalu', 228
+  UNION ALL SELECT 'TW', 'Taiwan', 229
+  UNION ALL SELECT 'TZ', 'Tansania', 230
+  UNION ALL SELECT 'UA', 'Ukraine', 231
+  UNION ALL SELECT 'UG', 'Uganda', 232
+  UNION ALL SELECT 'UK', 'Großbritannien', 233
+  UNION ALL SELECT 'UM', 'Baker Island', 234
+  UNION ALL SELECT 'US', 'Vereinigte Staaten (USA)', 235
+  UNION ALL SELECT 'UY', 'Uruguay', 236
+  UNION ALL SELECT 'UZ', 'Usbekistan', 237
+  UNION ALL SELECT 'V', 'Vatikanstadt', 238
+  UNION ALL SELECT 'VC', 'St. Vincent udn Grenadinen', 239
+  UNION ALL SELECT 'VE', 'Venezuela', 240
+  UNION ALL SELECT 'VG', 'Jungferninseln', 241
+  UNION ALL SELECT 'VI', 'US Jungferninseln', 242
+  UNION ALL SELECT 'VN', 'Vietnam', 243
+  UNION ALL SELECT 'VR', 'China', 244
+  UNION ALL SELECT 'VU', 'Vanuatu', 245
+  UNION ALL SELECT 'WF', 'Wallis und Futuna', 246
+  UNION ALL SELECT 'WS', 'Samoa', 247
+  UNION ALL SELECT 'X', 'Staatenlos', 248
+  UNION ALL SELECT 'YE', 'Jemen', 249
+  UNION ALL SELECT 'YT', 'Mayotte', 250
+  UNION ALL SELECT 'YU', 'ehem. Jugoslawien', 251
+  UNION ALL SELECT 'ZA', 'Südafrika', 252
+  UNION ALL SELECT 'ZM', 'Sambia', 253
+  UNION ALL SELECT 'ZW', 'Simbabwe', 254
+) AS src
+LEFT JOIN lands l ON l.land_iso_code = src.iso_code AND l.deleted_at IS NULL
+WHERE l.id IS NULL;
+
+-- +goose Down
+-- Intentionally no-op to avoid deleting existing production reference data.
+SELECT 1;
diff --git a/migrations/20260505_user_microsoft_oauth_tokens.sql b/migrations/20260505_user_microsoft_oauth_tokens.sql
new file mode 100644
index 0000000..6b58155
--- /dev/null
+++ b/migrations/20260505_user_microsoft_oauth_tokens.sql
@@ -0,0 +1,23 @@
+CREATE TABLE IF NOT EXISTS user_microsoft_oauth_tokens (
+  id BINARY(16) NOT NULL,
+  user_id BINARY(16) NOT NULL,
+  provider VARCHAR(32) NOT NULL,
+  tenant_id VARCHAR(128) NOT NULL,
+  microsoft_object_id VARCHAR(191) NOT NULL,
+  microsoft_subject VARCHAR(191) NOT NULL,
+  refresh_token_encrypted BLOB NOT NULL,
+  access_token_encrypted BLOB NULL,
+  id_token_encrypted BLOB NULL,
+  scope TEXT NULL,
+  token_type VARCHAR(32) NULL,
+  access_token_expires_at DATETIME(3) NULL,
+  refresh_token_rotated_at DATETIME(3) NULL,
+  created_at DATETIME(3) NULL,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(3) NULL,
+  updated_by BINARY(16) NULL,
+  PRIMARY KEY (id),
+  UNIQUE KEY ux_user_ms_oauth_user_provider (user_id, provider),
+  KEY idx_user_ms_oauth_tenant_id (tenant_id),
+  CONSTRAINT fk_user_ms_oauth_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ON UPDATE CASCADE
+);
diff --git a/migrations/20260507_base_contact_roles.sql b/migrations/20260507_base_contact_roles.sql
new file mode 100644
index 0000000..0926124
--- /dev/null
+++ b/migrations/20260507_base_contact_roles.sql
@@ -0,0 +1,22 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS base_contact_roles (
+  id BINARY(16) NOT NULL,
+  base_id BINARY(16) NOT NULL,
+  contact_id BINARY(16) NOT NULL,
+  role_code VARCHAR(64) NOT NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  PRIMARY KEY (id),
+  UNIQUE KEY uq_base_contact_roles_base_contact_role (base_id, contact_id, role_code),
+  KEY idx_base_contact_roles_base_id (base_id),
+  KEY idx_base_contact_roles_contact_id (contact_id),
+  KEY idx_base_contact_roles_role_code (role_code),
+  CONSTRAINT fk_base_contact_roles_base FOREIGN KEY (base_id) REFERENCES bases(id) ON DELETE CASCADE ON UPDATE CASCADE,
+  CONSTRAINT fk_base_contact_roles_contact FOREIGN KEY (contact_id) REFERENCES users(id) ON DELETE CASCADE ON UPDATE CASCADE,
+  CONSTRAINT chk_base_contact_roles_role_code CHECK (role_code IN ('responsible_flight_rescuer', 'chief_physician_in_charge'))
+);
+
+-- +goose Down
+DROP TABLE IF EXISTS base_contact_roles;
diff --git a/migrations/20260508_helicopter_files_position.sql b/migrations/20260508_helicopter_files_position.sql
new file mode 100644
index 0000000..4873ff4
--- /dev/null
+++ b/migrations/20260508_helicopter_files_position.sql
@@ -0,0 +1,8 @@
+ALTER TABLE helicopter_files
+  ADD COLUMN position INT NOT NULL DEFAULT 1 AFTER section,
+  ADD KEY idx_helicopter_files_position (position);
+
+UPDATE helicopter_files
+SET position = 1
+WHERE position IS NULL OR position <= 0;
+
diff --git a/migrations/20260511_drop_flight_inspection_legacy_completion_columns.sql b/migrations/20260511_drop_flight_inspection_legacy_completion_columns.sql
new file mode 100644
index 0000000..f21392d
--- /dev/null
+++ b/migrations/20260511_drop_flight_inspection_legacy_completion_columns.sql
@@ -0,0 +1,124 @@
+-- Drop legacy completion metadata columns from flight_inspections.
+-- Completion is derived from stage tables (before/prep/after) instead.
+
+SET @schema_name := DATABASE();
+
+-- before_flight_completed_at
+SELECT COUNT(*) INTO @has_before_completed_at
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'flight_inspections'
+  AND COLUMN_NAME = 'before_flight_completed_at';
+SET @drop_before_completed_at_sql := IF(
+  @has_before_completed_at > 0,
+  'ALTER TABLE flight_inspections DROP COLUMN before_flight_completed_at',
+  'SELECT 1'
+);
+PREPARE stmt_drop_before_completed_at FROM @drop_before_completed_at_sql;
+EXECUTE stmt_drop_before_completed_at;
+DEALLOCATE PREPARE stmt_drop_before_completed_at;
+
+-- before_flight_completed_by
+SELECT COUNT(*) INTO @has_before_completed_by
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'flight_inspections'
+  AND COLUMN_NAME = 'before_flight_completed_by';
+SET @drop_before_completed_by_sql := IF(
+  @has_before_completed_by > 0,
+  'ALTER TABLE flight_inspections DROP COLUMN before_flight_completed_by',
+  'SELECT 1'
+);
+PREPARE stmt_drop_before_completed_by FROM @drop_before_completed_by_sql;
+EXECUTE stmt_drop_before_completed_by;
+DEALLOCATE PREPARE stmt_drop_before_completed_by;
+
+-- flight_prep_completed_at
+SELECT COUNT(*) INTO @has_prep_completed_at
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'flight_inspections'
+  AND COLUMN_NAME = 'flight_prep_completed_at';
+SET @drop_prep_completed_at_sql := IF(
+  @has_prep_completed_at > 0,
+  'ALTER TABLE flight_inspections DROP COLUMN flight_prep_completed_at',
+  'SELECT 1'
+);
+PREPARE stmt_drop_prep_completed_at FROM @drop_prep_completed_at_sql;
+EXECUTE stmt_drop_prep_completed_at;
+DEALLOCATE PREPARE stmt_drop_prep_completed_at;
+
+-- flight_prep_completed_by
+SELECT COUNT(*) INTO @has_prep_completed_by
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'flight_inspections'
+  AND COLUMN_NAME = 'flight_prep_completed_by';
+SET @drop_prep_completed_by_sql := IF(
+  @has_prep_completed_by > 0,
+  'ALTER TABLE flight_inspections DROP COLUMN flight_prep_completed_by',
+  'SELECT 1'
+);
+PREPARE stmt_drop_prep_completed_by FROM @drop_prep_completed_by_sql;
+EXECUTE stmt_drop_prep_completed_by;
+DEALLOCATE PREPARE stmt_drop_prep_completed_by;
+
+-- after_flight_completed_at
+SELECT COUNT(*) INTO @has_after_completed_at
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'flight_inspections'
+  AND COLUMN_NAME = 'after_flight_completed_at';
+SET @drop_after_completed_at_sql := IF(
+  @has_after_completed_at > 0,
+  'ALTER TABLE flight_inspections DROP COLUMN after_flight_completed_at',
+  'SELECT 1'
+);
+PREPARE stmt_drop_after_completed_at FROM @drop_after_completed_at_sql;
+EXECUTE stmt_drop_after_completed_at;
+DEALLOCATE PREPARE stmt_drop_after_completed_at;
+
+-- after_flight_completed_by
+SELECT COUNT(*) INTO @has_after_completed_by
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'flight_inspections'
+  AND COLUMN_NAME = 'after_flight_completed_by';
+SET @drop_after_completed_by_sql := IF(
+  @has_after_completed_by > 0,
+  'ALTER TABLE flight_inspections DROP COLUMN after_flight_completed_by',
+  'SELECT 1'
+);
+PREPARE stmt_drop_after_completed_by FROM @drop_after_completed_by_sql;
+EXECUTE stmt_drop_after_completed_by;
+DEALLOCATE PREPARE stmt_drop_after_completed_by;
+
+-- final_completed_at
+SELECT COUNT(*) INTO @has_final_completed_at
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'flight_inspections'
+  AND COLUMN_NAME = 'final_completed_at';
+SET @drop_final_completed_at_sql := IF(
+  @has_final_completed_at > 0,
+  'ALTER TABLE flight_inspections DROP COLUMN final_completed_at',
+  'SELECT 1'
+);
+PREPARE stmt_drop_final_completed_at FROM @drop_final_completed_at_sql;
+EXECUTE stmt_drop_final_completed_at;
+DEALLOCATE PREPARE stmt_drop_final_completed_at;
+
+-- final_completed_by
+SELECT COUNT(*) INTO @has_final_completed_by
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'flight_inspections'
+  AND COLUMN_NAME = 'final_completed_by';
+SET @drop_final_completed_by_sql := IF(
+  @has_final_completed_by > 0,
+  'ALTER TABLE flight_inspections DROP COLUMN final_completed_by',
+  'SELECT 1'
+);
+PREPARE stmt_drop_final_completed_by FROM @drop_final_completed_by_sql;
+EXECUTE stmt_drop_final_completed_by;
+DEALLOCATE PREPARE stmt_drop_final_completed_by;
diff --git a/migrations/20260516_drop_nationality_module.sql b/migrations/20260516_drop_nationality_module.sql
new file mode 100644
index 0000000..1095bca
--- /dev/null
+++ b/migrations/20260516_drop_nationality_module.sql
@@ -0,0 +1,119 @@
+-- +goose Up
+-- Remove deprecated nationality module storage.
+
+SET @drop_fk_nationality := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1
+      FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
+      WHERE TABLE_SCHEMA = DATABASE()
+        AND TABLE_NAME = 'patient_data'
+        AND COLUMN_NAME = 'nationality_id'
+        AND REFERENCED_TABLE_NAME IS NOT NULL
+    ),
+    (
+      SELECT CONCAT('ALTER TABLE patient_data DROP FOREIGN KEY ', CONSTRAINT_NAME)
+      FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
+      WHERE TABLE_SCHEMA = DATABASE()
+        AND TABLE_NAME = 'patient_data'
+        AND COLUMN_NAME = 'nationality_id'
+        AND REFERENCED_TABLE_NAME IS NOT NULL
+      LIMIT 1
+    ),
+    'SELECT 1'
+  )
+);
+PREPARE stmt_drop_fk_nationality FROM @drop_fk_nationality;
+EXECUTE stmt_drop_fk_nationality;
+DEALLOCATE PREPARE stmt_drop_fk_nationality;
+
+SET @drop_idx_nationality := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1
+      FROM INFORMATION_SCHEMA.STATISTICS
+      WHERE TABLE_SCHEMA = DATABASE()
+        AND TABLE_NAME = 'patient_data'
+        AND INDEX_NAME = 'idx_patient_data_nationality_id'
+    ),
+    'ALTER TABLE patient_data DROP INDEX idx_patient_data_nationality_id',
+    'SELECT 1'
+  )
+);
+PREPARE stmt_drop_idx_nationality FROM @drop_idx_nationality;
+EXECUTE stmt_drop_idx_nationality;
+DEALLOCATE PREPARE stmt_drop_idx_nationality;
+
+SET @drop_col_nationality := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1
+      FROM INFORMATION_SCHEMA.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE()
+        AND TABLE_NAME = 'patient_data'
+        AND COLUMN_NAME = 'nationality_id'
+    ),
+    'ALTER TABLE patient_data DROP COLUMN nationality_id',
+    'SELECT 1'
+  )
+);
+PREPARE stmt_drop_col_nationality FROM @drop_col_nationality;
+EXECUTE stmt_drop_col_nationality;
+DEALLOCATE PREPARE stmt_drop_col_nationality;
+
+DROP TABLE IF EXISTS nationalities;
+
+-- +goose Down
+-- Recreate minimal nationality storage.
+
+CREATE TABLE IF NOT EXISTS nationalities (
+  id BINARY(16) NOT NULL PRIMARY KEY,
+  land_id BINARY(16) NULL,
+  name VARCHAR(128) NOT NULL,
+  sortkey INT NULL,
+  is_active TINYINT(1) NOT NULL DEFAULT 1,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME NULL,
+  deleted_by BINARY(16) NULL,
+  KEY idx_nationalities_land_id (land_id),
+  KEY idx_nationalities_sortkey (sortkey),
+  KEY idx_nationalities_is_active (is_active),
+  KEY idx_nationalities_deleted_at (deleted_at)
+);
+
+SET @add_col_nationality := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1
+      FROM INFORMATION_SCHEMA.COLUMNS
+      WHERE TABLE_SCHEMA = DATABASE()
+        AND TABLE_NAME = 'patient_data'
+        AND COLUMN_NAME = 'nationality_id'
+    ),
+    'SELECT 1',
+    'ALTER TABLE patient_data ADD COLUMN nationality_id BINARY(16) NULL AFTER co_insured'
+  )
+);
+PREPARE stmt_add_col_nationality FROM @add_col_nationality;
+EXECUTE stmt_add_col_nationality;
+DEALLOCATE PREPARE stmt_add_col_nationality;
+
+SET @add_idx_nationality := (
+  SELECT IF(
+    EXISTS (
+      SELECT 1
+      FROM INFORMATION_SCHEMA.STATISTICS
+      WHERE TABLE_SCHEMA = DATABASE()
+        AND TABLE_NAME = 'patient_data'
+        AND INDEX_NAME = 'idx_patient_data_nationality_id'
+    ),
+    'SELECT 1',
+    'ALTER TABLE patient_data ADD KEY idx_patient_data_nationality_id (nationality_id)'
+  )
+);
+PREPARE stmt_add_idx_nationality FROM @add_idx_nationality;
+EXECUTE stmt_add_idx_nationality;
+DEALLOCATE PREPARE stmt_add_idx_nationality;
diff --git a/migrations/20260517_add_land_id_to_icaos_and_health_insurance_companies.sql b/migrations/20260517_add_land_id_to_icaos_and_health_insurance_companies.sql
new file mode 100644
index 0000000..c1ddaf1
--- /dev/null
+++ b/migrations/20260517_add_land_id_to_icaos_and_health_insurance_companies.sql
@@ -0,0 +1,17 @@
+-- +goose Up
+ALTER TABLE icaos
+  ADD COLUMN land_id BINARY(16) NULL AFTER federal_state_id,
+  ADD KEY idx_icaos_land_id (land_id);
+
+ALTER TABLE health_insurance_companies
+  ADD COLUMN land_id BINARY(16) NULL AFTER sortkey,
+  ADD KEY idx_health_insurance_companies_land_id (land_id);
+
+-- +goose Down
+ALTER TABLE icaos
+  DROP KEY idx_icaos_land_id,
+  DROP COLUMN land_id;
+
+ALTER TABLE health_insurance_companies
+  DROP KEY idx_health_insurance_companies_land_id,
+  DROP COLUMN land_id;
diff --git a/migrations/20260517_remove_bmd_module.sql b/migrations/20260517_remove_bmd_module.sql
new file mode 100644
index 0000000..665ef69
--- /dev/null
+++ b/migrations/20260517_remove_bmd_module.sql
@@ -0,0 +1,48 @@
+-- +goose Up
+-- Remove BMD module artifacts: role-permission links, permissions, and table.
+
+DELETE rp
+FROM role_permissions rp
+INNER JOIN permissions p ON p.id = rp.permission_id
+WHERE p.`key` IN ('bmd.create', 'bmd.read', 'bmd.update', 'bmd.delete');
+
+DELETE FROM permissions
+WHERE `key` IN ('bmd.create', 'bmd.read', 'bmd.update', 'bmd.delete');
+
+DROP TABLE IF EXISTS bmds;
+
+-- +goose Down
+-- Recreate BMD table and baseline permissions (without restoring historical data/links).
+
+CREATE TABLE IF NOT EXISTS bmds (
+  id BINARY(16) PRIMARY KEY,
+  country_name VARCHAR(128) NOT NULL,
+  note VARCHAR(255) NULL,
+  sortkey INT NULL,
+  is_active TINYINT(1) NOT NULL DEFAULT 1,
+  eu_accession_code SMALLINT NOT NULL,
+  created_at DATETIME(3) NULL,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(3) NULL,
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME(3) NULL,
+  deleted_by BINARY(16) NULL,
+  KEY idx_bmds_sortkey (sortkey),
+  KEY idx_bmds_is_active (is_active)
+);
+
+INSERT INTO permissions (id, name, `key`, description, requires_pin, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID()), 'Create BMD', 'bmd.create', 'Create BMD', 1, UTC_TIMESTAMP(3), UTC_TIMESTAMP(3)
+WHERE NOT EXISTS (SELECT 1 FROM permissions WHERE `key` = 'bmd.create');
+
+INSERT INTO permissions (id, name, `key`, description, requires_pin, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID()), 'Read BMD', 'bmd.read', 'Read BMD', 0, UTC_TIMESTAMP(3), UTC_TIMESTAMP(3)
+WHERE NOT EXISTS (SELECT 1 FROM permissions WHERE `key` = 'bmd.read');
+
+INSERT INTO permissions (id, name, `key`, description, requires_pin, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID()), 'Update BMD', 'bmd.update', 'Update BMD', 1, UTC_TIMESTAMP(3), UTC_TIMESTAMP(3)
+WHERE NOT EXISTS (SELECT 1 FROM permissions WHERE `key` = 'bmd.update');
+
+INSERT INTO permissions (id, name, `key`, description, requires_pin, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID()), 'Delete BMD', 'bmd.delete', 'Delete BMD', 1, UTC_TIMESTAMP(3), UTC_TIMESTAMP(3)
+WHERE NOT EXISTS (SELECT 1 FROM permissions WHERE `key` = 'bmd.delete');
diff --git a/migrations/20260518_medicine_groups_motor_reactions.sql b/migrations/20260518_medicine_groups_motor_reactions.sql
new file mode 100644
index 0000000..4910381
--- /dev/null
+++ b/migrations/20260518_medicine_groups_motor_reactions.sql
@@ -0,0 +1,55 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS medicine_groups (
+  id BINARY(16) NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  sortkey INT NULL,
+  is_active TINYINT(1) NOT NULL DEFAULT 1,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME(6) NULL,
+  deleted_by BINARY(16) NULL,
+  PRIMARY KEY (id),
+  KEY idx_medicine_groups_is_active (is_active),
+  KEY idx_medicine_groups_sortkey (sortkey)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+CREATE TABLE IF NOT EXISTS motor_reactions (
+  id BINARY(16) NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  score BIGINT NULL,
+  sortkey INT NULL,
+  is_active TINYINT(1) NOT NULL DEFAULT 1,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME(6) NULL,
+  deleted_by BINARY(16) NULL,
+  PRIMARY KEY (id),
+  KEY idx_motor_reactions_is_active (is_active),
+  KEY idx_motor_reactions_sortkey (sortkey)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+ALTER TABLE medicines
+  ADD COLUMN weight BIGINT NULL AFTER dose,
+  ADD COLUMN medicine_group_id BINARY(16) NULL AFTER `column`,
+  ADD COLUMN motor_reaction_id BINARY(16) NULL AFTER medicine_group_id,
+  ADD KEY idx_medicines_medicine_group_id (medicine_group_id),
+  ADD KEY idx_medicines_motor_reaction_id (motor_reaction_id),
+  ADD CONSTRAINT fk_medicines_medicine_group FOREIGN KEY (medicine_group_id) REFERENCES medicine_groups(id) ON UPDATE CASCADE ON DELETE SET NULL,
+  ADD CONSTRAINT fk_medicines_motor_reaction FOREIGN KEY (motor_reaction_id) REFERENCES motor_reactions(id) ON UPDATE CASCADE ON DELETE SET NULL;
+
+-- +goose Down
+ALTER TABLE medicines
+  DROP FOREIGN KEY fk_medicines_medicine_group,
+  DROP FOREIGN KEY fk_medicines_motor_reaction,
+  DROP KEY idx_medicines_medicine_group_id,
+  DROP KEY idx_medicines_motor_reaction_id,
+  DROP COLUMN medicine_group_id,
+  DROP COLUMN motor_reaction_id,
+  DROP COLUMN weight;
+
+DROP TABLE IF EXISTS motor_reactions;
+DROP TABLE IF EXISTS medicine_groups;
diff --git a/migrations/20260518_medicine_motor_reactions.sql b/migrations/20260518_medicine_motor_reactions.sql
new file mode 100644
index 0000000..43887a6
--- /dev/null
+++ b/migrations/20260518_medicine_motor_reactions.sql
@@ -0,0 +1,17 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS medicine_motor_reactions (
+  medicine_id BINARY(16) NOT NULL,
+  motor_reaction_id BINARY(16) NOT NULL,
+  PRIMARY KEY (medicine_id, motor_reaction_id),
+  KEY idx_mmr_motor_reaction_id (motor_reaction_id),
+  CONSTRAINT fk_mmr_medicine FOREIGN KEY (medicine_id) REFERENCES medicines(id) ON UPDATE CASCADE ON DELETE CASCADE,
+  CONSTRAINT fk_mmr_motor_reaction FOREIGN KEY (motor_reaction_id) REFERENCES motor_reactions(id) ON UPDATE CASCADE ON DELETE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+INSERT IGNORE INTO medicine_motor_reactions (medicine_id, motor_reaction_id)
+SELECT id, motor_reaction_id
+FROM medicines
+WHERE motor_reaction_id IS NOT NULL;
+
+-- +goose Down
+DROP TABLE IF EXISTS medicine_motor_reactions;
diff --git a/migrations/20260518_user_email_login_otps.sql b/migrations/20260518_user_email_login_otps.sql
new file mode 100644
index 0000000..948a41c
--- /dev/null
+++ b/migrations/20260518_user_email_login_otps.sql
@@ -0,0 +1,24 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS user_email_login_otps (
+  id BINARY(16) NOT NULL,
+  user_id BINARY(16) NOT NULL,
+  otp_hash BINARY(32) NOT NULL,
+  expires_at DATETIME(6) NOT NULL,
+  used_at DATETIME(6) NULL,
+  attempt_count INT NOT NULL DEFAULT 0,
+  max_attempts INT NOT NULL DEFAULT 5,
+  resend_count INT NOT NULL DEFAULT 1,
+  last_sent_at DATETIME(6) NOT NULL,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  updated_by BINARY(16) NULL,
+  PRIMARY KEY (id),
+  KEY idx_user_email_login_otps_user_id (user_id),
+  KEY idx_user_email_login_otps_expires_at (expires_at),
+  KEY idx_user_email_login_otps_used_at (used_at),
+  CONSTRAINT fk_user_email_login_otps_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ON UPDATE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS user_email_login_otps;
diff --git a/migrations/20260518_users_role_id_nullable.sql b/migrations/20260518_users_role_id_nullable.sql
new file mode 100644
index 0000000..430db78
--- /dev/null
+++ b/migrations/20260518_users_role_id_nullable.sql
@@ -0,0 +1,3 @@
+ALTER TABLE users
+  MODIFY COLUMN role_id BINARY(16) NULL;
+
diff --git a/migrations/20260519_lands_land_iso_code_unique.sql b/migrations/20260519_lands_land_iso_code_unique.sql
new file mode 100644
index 0000000..25ac1ce
--- /dev/null
+++ b/migrations/20260519_lands_land_iso_code_unique.sql
@@ -0,0 +1,22 @@
+-- +goose Up
+ALTER TABLE lands
+  ADD UNIQUE KEY uq_lands_land_iso_code (land_iso_code);
+
+-- +goose Down
+SET @idx_exists := (
+  SELECT COUNT(1)
+  FROM information_schema.statistics
+  WHERE table_schema = DATABASE()
+    AND table_name = 'lands'
+    AND index_name = 'uq_lands_land_iso_code'
+);
+
+SET @drop_sql := IF(
+  @idx_exists > 0,
+  'ALTER TABLE lands DROP INDEX uq_lands_land_iso_code',
+  'SELECT 1'
+);
+
+PREPARE stmt FROM @drop_sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
diff --git a/migrations/20260520_drop_bases_position_visible.sql b/migrations/20260520_drop_bases_position_visible.sql
new file mode 100644
index 0000000..c66e2dd
--- /dev/null
+++ b/migrations/20260520_drop_bases_position_visible.sql
@@ -0,0 +1,4 @@
+ALTER TABLE bases
+  DROP COLUMN IF EXISTS note,
+  DROP COLUMN IF EXISTS position,
+  DROP COLUMN IF EXISTS visible;
diff --git a/migrations/20260521_drop_sortkey_from_medicine_entities.sql b/migrations/20260521_drop_sortkey_from_medicine_entities.sql
new file mode 100644
index 0000000..9859e21
--- /dev/null
+++ b/migrations/20260521_drop_sortkey_from_medicine_entities.sql
@@ -0,0 +1,13 @@
+-- +goose Up
+ALTER TABLE medicine_groups
+  DROP COLUMN sortkey;
+
+ALTER TABLE motor_reactions
+  DROP COLUMN sortkey;
+
+-- +goose Down
+ALTER TABLE medicine_groups
+  ADD COLUMN sortkey INT NULL AFTER name;
+
+ALTER TABLE motor_reactions
+  ADD COLUMN sortkey INT NULL AFTER score;
diff --git a/migrations/20260522_drop_description_from_opc_forces_present_vocation.sql b/migrations/20260522_drop_description_from_opc_forces_present_vocation.sql
new file mode 100644
index 0000000..0f9d000
--- /dev/null
+++ b/migrations/20260522_drop_description_from_opc_forces_present_vocation.sql
@@ -0,0 +1,23 @@
+-- +goose Up
+-- +goose StatementBegin
+ALTER TABLE opcs
+  DROP COLUMN description;
+
+ALTER TABLE forces_present
+  DROP COLUMN description;
+
+ALTER TABLE vocations
+  DROP COLUMN description;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+ALTER TABLE opcs
+  ADD COLUMN description VARCHAR(255) NULL AFTER note;
+
+ALTER TABLE forces_present
+  ADD COLUMN description VARCHAR(255) NULL AFTER note;
+
+ALTER TABLE vocations
+  ADD COLUMN description VARCHAR(255) NULL AFTER note;
+-- +goose StatementEnd
diff --git a/migrations/20260522_drop_is_active_from_medicine_group_and_motor_reaction.sql b/migrations/20260522_drop_is_active_from_medicine_group_and_motor_reaction.sql
new file mode 100644
index 0000000..7eb10cf
--- /dev/null
+++ b/migrations/20260522_drop_is_active_from_medicine_group_and_motor_reaction.sql
@@ -0,0 +1,21 @@
+-- +goose Up
+-- +goose StatementBegin
+ALTER TABLE medicine_groups
+  DROP INDEX idx_medicine_groups_is_active,
+  DROP COLUMN is_active;
+
+ALTER TABLE motor_reactions
+  DROP INDEX idx_motor_reactions_is_active,
+  DROP COLUMN is_active;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+ALTER TABLE medicine_groups
+  ADD COLUMN is_active TINYINT(1) NOT NULL DEFAULT 1 AFTER name,
+  ADD KEY idx_medicine_groups_is_active (is_active);
+
+ALTER TABLE motor_reactions
+  ADD COLUMN is_active TINYINT(1) NOT NULL DEFAULT 1 AFTER score,
+  ADD KEY idx_motor_reactions_is_active (is_active);
+-- +goose StatementEnd
diff --git a/migrations/20260525_add_date_to_duls.sql b/migrations/20260525_add_date_to_duls.sql
new file mode 100644
index 0000000..5ed30db
--- /dev/null
+++ b/migrations/20260525_add_date_to_duls.sql
@@ -0,0 +1,14 @@
+-- +goose Up
+ALTER TABLE duls
+  ADD COLUMN IF NOT EXISTS date DATE NULL AFTER name;
+
+UPDATE duls
+SET date = COALESCE(date, DATE(created_at), CURRENT_DATE())
+WHERE date IS NULL;
+
+ALTER TABLE duls
+  MODIFY COLUMN date DATE NOT NULL;
+
+-- +goose Down
+ALTER TABLE duls
+  DROP COLUMN IF EXISTS date;
diff --git a/migrations/20260525_create_duls.sql b/migrations/20260525_create_duls.sql
new file mode 100644
index 0000000..f3443b1
--- /dev/null
+++ b/migrations/20260525_create_duls.sql
@@ -0,0 +1,22 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS duls (
+  id BINARY(16) NOT NULL,
+  no BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  name VARCHAR(128) NOT NULL,
+  date DATE NOT NULL,
+  info TEXT NULL,
+  base_id BINARY(16) NOT NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME NULL,
+  deleted_by BINARY(16) NULL,
+  PRIMARY KEY (id),
+  UNIQUE KEY uq_duls_no (no),
+  KEY idx_duls_base_id (base_id),
+  CONSTRAINT fk_duls_base FOREIGN KEY (base_id) REFERENCES bases(id) ON UPDATE CASCADE ON DELETE RESTRICT
+);
+
+-- +goose Down
+DROP TABLE IF EXISTS duls;
diff --git a/migrations/20260526_reserve_acs_add_notes.sql b/migrations/20260526_reserve_acs_add_notes.sql
new file mode 100644
index 0000000..4f08935
--- /dev/null
+++ b/migrations/20260526_reserve_acs_add_notes.sql
@@ -0,0 +1,35 @@
+-- +goose Up
+SET @schema_name := DATABASE();
+
+SELECT COUNT(*) INTO @has_notes
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'reserve_acs'
+  AND COLUMN_NAME = 'notes';
+
+SET @add_notes_sql := IF(
+  @has_notes = 0,
+  'ALTER TABLE reserve_acs ADD COLUMN notes TEXT NULL AFTER base_id',
+  'SELECT 1'
+);
+PREPARE stmt_add_notes FROM @add_notes_sql;
+EXECUTE stmt_add_notes;
+DEALLOCATE PREPARE stmt_add_notes;
+
+-- +goose Down
+SET @schema_name := DATABASE();
+
+SELECT COUNT(*) INTO @has_notes
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'reserve_acs'
+  AND COLUMN_NAME = 'notes';
+
+SET @drop_notes_sql := IF(
+  @has_notes = 1,
+  'ALTER TABLE reserve_acs DROP COLUMN notes',
+  'SELECT 1'
+);
+PREPARE stmt_drop_notes FROM @drop_notes_sql;
+EXECUTE stmt_drop_notes;
+DEALLOCATE PREPARE stmt_drop_notes;
diff --git a/migrations/20260526_takeover_schema_alignment.sql b/migrations/20260526_takeover_schema_alignment.sql
new file mode 100644
index 0000000..0769d63
--- /dev/null
+++ b/migrations/20260526_takeover_schema_alignment.sql
@@ -0,0 +1,114 @@
+-- +goose Up
+-- Align schema for single-request takeover create flow.
+-- Only apply additive changes when columns/constraints are missing.
+
+SET @schema_name := DATABASE();
+
+-- reserve_acs.base_id
+SELECT COUNT(*) INTO @reserve_acs_has_base_id
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'reserve_acs'
+  AND COLUMN_NAME = 'base_id';
+
+SET @add_reserve_acs_base_id_sql := IF(
+  @reserve_acs_has_base_id = 0,
+  'ALTER TABLE reserve_acs ADD COLUMN base_id BINARY(16) NULL AFTER status',
+  'SELECT 1'
+);
+PREPARE stmt_add_reserve_acs_base_id FROM @add_reserve_acs_base_id_sql;
+EXECUTE stmt_add_reserve_acs_base_id;
+DEALLOCATE PREPARE stmt_add_reserve_acs_base_id;
+
+-- Index reserve_acs.base_id
+SELECT COUNT(*) INTO @reserve_acs_has_base_id_idx
+FROM information_schema.STATISTICS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'reserve_acs'
+  AND INDEX_NAME = 'idx_reserve_acs_base_id';
+
+SET @add_reserve_acs_base_id_idx_sql := IF(
+  @reserve_acs_has_base_id_idx = 0,
+  'CREATE INDEX idx_reserve_acs_base_id ON reserve_acs(base_id)',
+  'SELECT 1'
+);
+PREPARE stmt_add_reserve_acs_base_id_idx FROM @add_reserve_acs_base_id_idx_sql;
+EXECUTE stmt_add_reserve_acs_base_id_idx;
+DEALLOCATE PREPARE stmt_add_reserve_acs_base_id_idx;
+
+-- FK reserve_acs.base_id -> bases.id
+SELECT COUNT(*) INTO @reserve_acs_has_base_fk
+FROM information_schema.TABLE_CONSTRAINTS
+WHERE CONSTRAINT_SCHEMA = @schema_name
+  AND TABLE_NAME = 'reserve_acs'
+  AND CONSTRAINT_NAME = 'fk_reserve_acs_base'
+  AND CONSTRAINT_TYPE = 'FOREIGN KEY';
+
+SET @add_reserve_acs_base_fk_sql := IF(
+  @reserve_acs_has_base_fk = 0,
+  'ALTER TABLE reserve_acs ADD CONSTRAINT fk_reserve_acs_base FOREIGN KEY (base_id) REFERENCES bases(id)',
+  'SELECT 1'
+);
+PREPARE stmt_add_reserve_acs_base_fk FROM @add_reserve_acs_base_fk_sql;
+EXECUTE stmt_add_reserve_acs_base_fk;
+DEALLOCATE PREPARE stmt_add_reserve_acs_base_fk;
+
+-- Optional backfill reserve_acs.base_id from linked flight -> duty_roster.
+-- Safe to run repeatedly.
+UPDATE reserve_acs ra
+JOIN flights f ON f.reserve_ac_id = ra.id AND f.deleted_at IS NULL
+JOIN duty_rosters dr ON dr.id = f.duty_roster_id AND dr.deleted_at IS NULL
+SET ra.base_id = dr.base_id
+WHERE ra.base_id IS NULL
+  AND ra.deleted_at IS NULL;
+
+-- +goose Down
+-- Keep data; only drop FK/index/column if present.
+
+SET @schema_name := DATABASE();
+
+SELECT COUNT(*) INTO @reserve_acs_has_base_fk
+FROM information_schema.TABLE_CONSTRAINTS
+WHERE CONSTRAINT_SCHEMA = @schema_name
+  AND TABLE_NAME = 'reserve_acs'
+  AND CONSTRAINT_NAME = 'fk_reserve_acs_base'
+  AND CONSTRAINT_TYPE = 'FOREIGN KEY';
+
+SET @drop_reserve_acs_base_fk_sql := IF(
+  @reserve_acs_has_base_fk = 1,
+  'ALTER TABLE reserve_acs DROP FOREIGN KEY fk_reserve_acs_base',
+  'SELECT 1'
+);
+PREPARE stmt_drop_reserve_acs_base_fk FROM @drop_reserve_acs_base_fk_sql;
+EXECUTE stmt_drop_reserve_acs_base_fk;
+DEALLOCATE PREPARE stmt_drop_reserve_acs_base_fk;
+
+SELECT COUNT(*) INTO @reserve_acs_has_base_id_idx
+FROM information_schema.STATISTICS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'reserve_acs'
+  AND INDEX_NAME = 'idx_reserve_acs_base_id';
+
+SET @drop_reserve_acs_base_id_idx_sql := IF(
+  @reserve_acs_has_base_id_idx = 1,
+  'DROP INDEX idx_reserve_acs_base_id ON reserve_acs',
+  'SELECT 1'
+);
+PREPARE stmt_drop_reserve_acs_base_id_idx FROM @drop_reserve_acs_base_id_idx_sql;
+EXECUTE stmt_drop_reserve_acs_base_id_idx;
+DEALLOCATE PREPARE stmt_drop_reserve_acs_base_id_idx;
+
+SELECT COUNT(*) INTO @reserve_acs_has_base_id
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'reserve_acs'
+  AND COLUMN_NAME = 'base_id';
+
+SET @drop_reserve_acs_base_id_sql := IF(
+  @reserve_acs_has_base_id = 1,
+  'ALTER TABLE reserve_acs DROP COLUMN base_id',
+  'SELECT 1'
+);
+PREPARE stmt_drop_reserve_acs_base_id FROM @drop_reserve_acs_base_id_sql;
+EXECUTE stmt_drop_reserve_acs_base_id;
+DEALLOCATE PREPARE stmt_drop_reserve_acs_base_id;
diff --git a/migrations/20260529_add_name_to_icaos.sql b/migrations/20260529_add_name_to_icaos.sql
new file mode 100644
index 0000000..552826d
--- /dev/null
+++ b/migrations/20260529_add_name_to_icaos.sql
@@ -0,0 +1,26 @@
+-- Add optional name field to ICAO table.
+
+SET @has_table := (
+  SELECT COUNT(*)
+  FROM information_schema.tables
+  WHERE table_schema = DATABASE()
+    AND table_name = 'icaos'
+);
+
+SET @has_column := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'icaos'
+    AND column_name = 'name'
+);
+
+SET @sql := IF(
+  @has_table > 0 AND @has_column = 0,
+  'ALTER TABLE icaos ADD COLUMN name VARCHAR(128) NULL AFTER icao_code',
+  'SELECT 1'
+);
+
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
diff --git a/migrations/20260529_create_fleet_status_service_logs.sql b/migrations/20260529_create_fleet_status_service_logs.sql
new file mode 100644
index 0000000..7a59f48
--- /dev/null
+++ b/migrations/20260529_create_fleet_status_service_logs.sql
@@ -0,0 +1,18 @@
+CREATE TABLE IF NOT EXISTS fleet_status_service_logs (
+    id BINARY(16) PRIMARY KEY,
+    fleet_status_id BINARY(16) NOT NULL,
+    helicopter_id BINARY(16) NOT NULL,
+    inspection_type VARCHAR(16) NOT NULL,
+    type VARCHAR(255) NOT NULL,
+    due VARCHAR(255) NULL,
+    ext VARCHAR(255) NULL,
+    serviced_at DATETIME(3) NOT NULL,
+    created_at DATETIME(3) NULL,
+    created_by BINARY(16) NULL,
+    INDEX idx_fleet_status_service_logs_fleet_status_id (fleet_status_id),
+    INDEX idx_fleet_status_service_logs_helicopter_id (helicopter_id),
+    INDEX idx_fleet_status_service_logs_serviced_at (serviced_at),
+    CONSTRAINT chk_fleet_status_service_logs_inspection_type CHECK (inspection_type IN ('A/F','ENG1','ENG2','MAIN1','MAIN2')),
+    CONSTRAINT fk_fleet_status_service_logs_fleet_status FOREIGN KEY (fleet_status_id) REFERENCES fleet_statuses(id) ON DELETE CASCADE ON UPDATE CASCADE,
+    CONSTRAINT fk_fleet_status_service_logs_helicopter FOREIGN KEY (helicopter_id) REFERENCES helicopters(id)
+);
diff --git a/migrations/20260529_create_fleet_status_tables.sql b/migrations/20260529_create_fleet_status_tables.sql
new file mode 100644
index 0000000..1bc0ee9
--- /dev/null
+++ b/migrations/20260529_create_fleet_status_tables.sql
@@ -0,0 +1,35 @@
+CREATE TABLE IF NOT EXISTS fleet_statuses (
+    id BINARY(16) PRIMARY KEY,
+    helicopter_id BINARY(16) NOT NULL,
+    created_at DATETIME(3) NULL,
+    created_by BINARY(16) NULL,
+    updated_at DATETIME(3) NULL,
+    updated_by BINARY(16) NULL,
+    deleted_at DATETIME(3) NULL,
+    deleted_by BINARY(16) NULL,
+    INDEX idx_fleet_statuses_helicopter_id (helicopter_id),
+    INDEX idx_fleet_statuses_deleted_at (deleted_at),
+    CONSTRAINT fk_fleet_statuses_helicopter FOREIGN KEY (helicopter_id) REFERENCES helicopters(id)
+);
+
+CREATE TABLE IF NOT EXISTS maintenance_schedules (
+    id BINARY(16) PRIMARY KEY,
+    fleet_status_id BINARY(16) NOT NULL,
+    inspection_type VARCHAR(16) NOT NULL,
+    type VARCHAR(255) NOT NULL,
+    due VARCHAR(255) NULL,
+    ext VARCHAR(255) NULL,
+    INDEX idx_maintenance_schedules_fleet_status_id (fleet_status_id),
+    CONSTRAINT chk_maintenance_schedules_inspection_type CHECK (inspection_type IN ('A/F','ENG1','ENG2','MAIN1','MAIN2')),
+    CONSTRAINT fk_maintenance_schedules_fleet_status FOREIGN KEY (fleet_status_id) REFERENCES fleet_statuses(id) ON DELETE CASCADE ON UPDATE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS fleet_status_files (
+    id BINARY(16) PRIMARY KEY,
+    fleet_status_id BINARY(16) NOT NULL,
+    file_attachment_id BINARY(16) NOT NULL,
+    INDEX idx_fleet_status_files_fleet_status_id (fleet_status_id),
+    INDEX idx_fleet_status_files_attachment_id (file_attachment_id),
+    CONSTRAINT fk_fleet_status_files_fleet_status FOREIGN KEY (fleet_status_id) REFERENCES fleet_statuses(id) ON DELETE CASCADE ON UPDATE CASCADE,
+    CONSTRAINT fk_fleet_status_files_attachment FOREIGN KEY (file_attachment_id) REFERENCES attachments(id)
+);
diff --git a/migrations/20260529_motor_reactions_score_nullable.sql b/migrations/20260529_motor_reactions_score_nullable.sql
new file mode 100644
index 0000000..c6bd2e9
--- /dev/null
+++ b/migrations/20260529_motor_reactions_score_nullable.sql
@@ -0,0 +1,11 @@
+-- +goose Up
+ALTER TABLE motor_reactions
+  MODIFY COLUMN score BIGINT NULL;
+
+-- +goose Down
+UPDATE motor_reactions
+SET score = 0
+WHERE score IS NULL;
+
+ALTER TABLE motor_reactions
+  MODIFY COLUMN score BIGINT NOT NULL;
diff --git a/migrations/20260529_rename_hospitals_to_no_icao_codes.sql b/migrations/20260529_rename_hospitals_to_no_icao_codes.sql
new file mode 100644
index 0000000..2c4d4b9
--- /dev/null
+++ b/migrations/20260529_rename_hospitals_to_no_icao_codes.sql
@@ -0,0 +1,26 @@
+-- Rename hospital table to no_icao_codes
+-- This keeps existing data and constraints while moving to the new table name.
+
+SET @has_hospitals := (
+  SELECT COUNT(*)
+  FROM information_schema.tables
+  WHERE table_schema = DATABASE()
+    AND table_name = 'hospitals'
+);
+
+SET @has_no_icao_codes := (
+  SELECT COUNT(*)
+  FROM information_schema.tables
+  WHERE table_schema = DATABASE()
+    AND table_name = 'no_icao_codes'
+);
+
+SET @rename_sql := IF(
+  @has_hospitals > 0 AND @has_no_icao_codes = 0,
+  'RENAME TABLE hospitals TO no_icao_codes',
+  'SELECT 1'
+);
+
+PREPARE stmt FROM @rename_sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
diff --git a/migrations/20260529_rename_opcs_to_hems_opcs.sql b/migrations/20260529_rename_opcs_to_hems_opcs.sql
new file mode 100644
index 0000000..c3977df
--- /dev/null
+++ b/migrations/20260529_rename_opcs_to_hems_opcs.sql
@@ -0,0 +1,25 @@
+-- Rename OPC table to hems_opcs.
+
+SET @has_opcs := (
+  SELECT COUNT(*)
+  FROM information_schema.tables
+  WHERE table_schema = DATABASE()
+    AND table_name = 'opcs'
+);
+
+SET @has_hems_opcs := (
+  SELECT COUNT(*)
+  FROM information_schema.tables
+  WHERE table_schema = DATABASE()
+    AND table_name = 'hems_opcs'
+);
+
+SET @rename_sql := IF(
+  @has_opcs > 0 AND @has_hems_opcs = 0,
+  'RENAME TABLE opcs TO hems_opcs',
+  'SELECT 1'
+);
+
+PREPARE stmt FROM @rename_sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
diff --git a/migrations/20260602_add_flight_id_to_duty_rosters.sql b/migrations/20260602_add_flight_id_to_duty_rosters.sql
new file mode 100644
index 0000000..6df0214
--- /dev/null
+++ b/migrations/20260602_add_flight_id_to_duty_rosters.sql
@@ -0,0 +1,10 @@
+ALTER TABLE duty_rosters
+  ADD COLUMN flight_id BINARY(16) NULL AFTER id;
+
+CREATE UNIQUE INDEX idx_roster_flight_id
+  ON duty_rosters (flight_id);
+
+-- Keep base/date as a non-unique lookup index so existing roster views still work.
+DROP INDEX idx_roster_base_date ON duty_rosters;
+CREATE INDEX idx_roster_base_date
+  ON duty_rosters (base_id, duty_date);
diff --git a/migrations/20260602_add_serviced_at_to_fleet_status_service_logs.sql b/migrations/20260602_add_serviced_at_to_fleet_status_service_logs.sql
new file mode 100644
index 0000000..446d5e7
--- /dev/null
+++ b/migrations/20260602_add_serviced_at_to_fleet_status_service_logs.sql
@@ -0,0 +1,18 @@
+-- Keep fleet status service log schema aligned with service timestamp usage.
+
+SET @has_status_col := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'fleet_status_service_logs'
+    AND column_name = 'serviced_at'
+);
+
+SET @sql := IF(
+  @has_status_col = 0,
+  'ALTER TABLE fleet_status_service_logs ADD COLUMN serviced_at DATETIME(3) NOT NULL AFTER ext',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
diff --git a/migrations/20260602_add_status_serviced_at_to_fleet_statuses.sql b/migrations/20260602_add_status_serviced_at_to_fleet_statuses.sql
new file mode 100644
index 0000000..a6e41cb
--- /dev/null
+++ b/migrations/20260602_add_status_serviced_at_to_fleet_statuses.sql
@@ -0,0 +1,69 @@
+-- Add explicit service state to fleet statuses.
+
+SET @has_status := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'fleet_statuses'
+    AND column_name = 'status'
+);
+
+SET @has_serviced_at := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'fleet_statuses'
+    AND column_name = 'serviced_at'
+);
+
+SET @sql1 := IF(
+  @has_status = 0,
+  'ALTER TABLE fleet_statuses ADD COLUMN status VARCHAR(16) NOT NULL DEFAULT ''active'' AFTER helicopter_id',
+  'SELECT 1'
+);
+PREPARE stmt1 FROM @sql1;
+EXECUTE stmt1;
+DEALLOCATE PREPARE stmt1;
+
+SET @sql2 := IF(
+  @has_serviced_at = 0,
+  'ALTER TABLE fleet_statuses ADD COLUMN serviced_at DATETIME(3) NULL AFTER status',
+  'SELECT 1'
+);
+PREPARE stmt2 FROM @sql2;
+EXECUTE stmt2;
+DEALLOCATE PREPARE stmt2;
+
+SET @idx_status := (
+  SELECT COUNT(*)
+  FROM information_schema.statistics
+  WHERE table_schema = DATABASE()
+    AND table_name = 'fleet_statuses'
+    AND index_name = 'idx_fleet_statuses_status'
+);
+
+SET @sql3 := IF(
+  @idx_status = 0,
+  'ALTER TABLE fleet_statuses ADD INDEX idx_fleet_statuses_status (status)',
+  'SELECT 1'
+);
+PREPARE stmt3 FROM @sql3;
+EXECUTE stmt3;
+DEALLOCATE PREPARE stmt3;
+
+SET @idx_serviced := (
+  SELECT COUNT(*)
+  FROM information_schema.statistics
+  WHERE table_schema = DATABASE()
+    AND table_name = 'fleet_statuses'
+    AND index_name = 'idx_fleet_statuses_serviced_at'
+);
+
+SET @sql4 := IF(
+  @idx_serviced = 0,
+  'ALTER TABLE fleet_statuses ADD INDEX idx_fleet_statuses_serviced_at (serviced_at)',
+  'SELECT 1'
+);
+PREPARE stmt4 FROM @sql4;
+EXECUTE stmt4;
+DEALLOCATE PREPARE stmt4;
diff --git a/migrations/20260602_add_status_to_flights.sql b/migrations/20260602_add_status_to_flights.sql
new file mode 100644
index 0000000..88a3139
--- /dev/null
+++ b/migrations/20260602_add_status_to_flights.sql
@@ -0,0 +1,6 @@
+ALTER TABLE flights
+  ADD COLUMN status VARCHAR(20) NOT NULL DEFAULT 'draft' AFTER id;
+
+UPDATE flights
+SET status = 'draft'
+WHERE status IS NULL OR status = '';
diff --git a/migrations/20260602_add_takeover_ac_id_refs.sql b/migrations/20260602_add_takeover_ac_id_refs.sql
new file mode 100644
index 0000000..6bc5f1c
--- /dev/null
+++ b/migrations/20260602_add_takeover_ac_id_refs.sql
@@ -0,0 +1,12 @@
+ALTER TABLE flights
+  ADD COLUMN takeover_ac_id BINARY(16) NULL AFTER reserve_ac_id,
+  ADD INDEX idx_flights_takeover_ac_id (takeover_ac_id);
+
+ALTER TABLE duty_roster_crews
+  ADD COLUMN takeover_ac_id BINARY(16) NULL AFTER confirm_at,
+  ADD INDEX idx_duty_roster_crews_takeover_ac_id (takeover_ac_id);
+
+ALTER TABLE duty_roster_other_persons
+  ADD COLUMN takeover_ac_id BINARY(16) NULL AFTER email,
+  ADD INDEX idx_duty_roster_other_persons_takeover_ac_id (takeover_ac_id);
+
diff --git a/migrations/20260602_create_takeover_acs.sql b/migrations/20260602_create_takeover_acs.sql
new file mode 100644
index 0000000..14a664c
--- /dev/null
+++ b/migrations/20260602_create_takeover_acs.sql
@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS takeover_acs (
+  id BINARY(16) NOT NULL PRIMARY KEY,
+  base_id BINARY(16) NOT NULL,
+  reserve_ac_id BINARY(16) NOT NULL,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME(6) NULL,
+  deleted_by BINARY(16) NULL,
+  UNIQUE KEY uidx_takeover_acs_reserve_ac_id (reserve_ac_id),
+  KEY idx_takeover_acs_base_id (base_id),
+  KEY idx_takeover_acs_deleted_at (deleted_at)
+);
+
diff --git a/migrations/20260602_create_takeover_children.sql b/migrations/20260602_create_takeover_children.sql
new file mode 100644
index 0000000..1913133
--- /dev/null
+++ b/migrations/20260602_create_takeover_children.sql
@@ -0,0 +1,58 @@
+CREATE TABLE IF NOT EXISTS takeover_acs (
+  id BINARY(16) NOT NULL PRIMARY KEY,
+  takeover_id BINARY(16) NOT NULL,
+  base_id BINARY(16) NULL,
+  reserve_ac_id BINARY(16) NULL,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME(6) NULL,
+  deleted_by BINARY(16) NULL,
+  KEY idx_takeover_acs_takeover_id (takeover_id)
+);
+
+CREATE TABLE IF NOT EXISTS takeover_flights (
+  id BINARY(16) NOT NULL PRIMARY KEY,
+  takeover_id BINARY(16) NOT NULL,
+  date_time DATETIME(6) NOT NULL,
+  status VARCHAR(32) NOT NULL DEFAULT 'draft',
+  alarm_time DATETIME(6) NULL,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME(6) NULL,
+  deleted_by BINARY(16) NULL,
+  KEY idx_takeover_flights_takeover_id (takeover_id)
+);
+
+CREATE TABLE IF NOT EXISTS takeover_roster_crews (
+  id BINARY(16) NOT NULL PRIMARY KEY,
+  takeover_id BINARY(16) NOT NULL,
+  crew_id BINARY(16) NOT NULL,
+  confirm_at DATETIME(6) NULL,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME(6) NULL,
+  deleted_by BINARY(16) NULL,
+  KEY idx_takeover_roster_crews_takeover_id (takeover_id)
+);
+
+CREATE TABLE IF NOT EXISTS takeover_other_people (
+  id BINARY(16) NOT NULL PRIMARY KEY,
+  takeover_id BINARY(16) NOT NULL,
+  name VARCHAR(191) NULL,
+  mobile_phone VARCHAR(64) NULL,
+  email VARCHAR(191) NULL,
+  created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+  created_by BINARY(16) NULL,
+  updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME(6) NULL,
+  deleted_by BINARY(16) NULL,
+  KEY idx_takeover_other_people_takeover_id (takeover_id)
+);
+
diff --git a/migrations/20260604_add_name_to_icaos.sql b/migrations/20260604_add_name_to_icaos.sql
new file mode 100644
index 0000000..cf91dc4
--- /dev/null
+++ b/migrations/20260604_add_name_to_icaos.sql
@@ -0,0 +1,3 @@
+ALTER TABLE icaos
+  ADD COLUMN name varchar(150) NOT NULL DEFAULT '' AFTER icao_code;
+
diff --git a/migrations/20260604_missions_many_per_flight.sql b/migrations/20260604_missions_many_per_flight.sql
new file mode 100644
index 0000000..366a8db
--- /dev/null
+++ b/migrations/20260604_missions_many_per_flight.sql
@@ -0,0 +1,2 @@
+ALTER TABLE missions
+  DROP INDEX uidx_missions_flight_id;
diff --git a/migrations/20260605_medicines_unit_via.sql b/migrations/20260605_medicines_unit_via.sql
new file mode 100644
index 0000000..c300e02
--- /dev/null
+++ b/migrations/20260605_medicines_unit_via.sql
@@ -0,0 +1,3 @@
+ALTER TABLE medicines
+  ADD COLUMN unit VARCHAR(50) NOT NULL DEFAULT '' AFTER dose,
+  ADD COLUMN via VARCHAR(50) NOT NULL DEFAULT '' AFTER unit;
diff --git a/migrations/20260609_fix_duty_roster_crews_fk.sql b/migrations/20260609_fix_duty_roster_crews_fk.sql
new file mode 100644
index 0000000..a17f1be
--- /dev/null
+++ b/migrations/20260609_fix_duty_roster_crews_fk.sql
@@ -0,0 +1,33 @@
+-- +goose Up
+-- Rewire crew FK to point at duty_rosters.
+
+ALTER TABLE duty_roster_crews
+  DROP FOREIGN KEY fk_hems_duty_rosters_crews,
+  ADD CONSTRAINT fk_duty_roster_crews_roster
+    FOREIGN KEY (roster_id) REFERENCES duty_rosters(id)
+    ON DELETE CASCADE
+    ON UPDATE CASCADE;
+
+ALTER TABLE duty_roster_other_persons
+  DROP FOREIGN KEY fk_duty_roster_other_persons_roster,
+  ADD CONSTRAINT fk_duty_roster_other_persons_roster
+    FOREIGN KEY (roster_id) REFERENCES duty_rosters(id)
+    ON DELETE CASCADE
+    ON UPDATE CASCADE;
+
+-- +goose Down
+-- Restore crew FK back to the legacy table.
+
+ALTER TABLE duty_roster_crews
+  DROP FOREIGN KEY fk_duty_roster_crews_roster,
+  ADD CONSTRAINT fk_hems_duty_rosters_crews
+    FOREIGN KEY (roster_id) REFERENCES hems_duty_rosters(id)
+    ON DELETE CASCADE
+    ON UPDATE CASCADE;
+
+ALTER TABLE duty_roster_other_persons
+  DROP FOREIGN KEY fk_duty_roster_other_persons_roster,
+  ADD CONSTRAINT fk_duty_roster_other_persons_roster
+    FOREIGN KEY (roster_id) REFERENCES hems_duty_rosters(id)
+    ON DELETE CASCADE
+    ON UPDATE CASCADE;
diff --git a/migrations/20260609_takeover_acs_base_id_nullable.sql b/migrations/20260609_takeover_acs_base_id_nullable.sql
new file mode 100644
index 0000000..6b8e28f
--- /dev/null
+++ b/migrations/20260609_takeover_acs_base_id_nullable.sql
@@ -0,0 +1,58 @@
+-- +goose Up
+-- Allow takeover_acs.base_id to be nullable so takeover can be created without base data.
+
+SET @schema_name := DATABASE();
+
+SELECT COUNT(*) INTO @takeover_acs_has_base_id
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_acs'
+  AND COLUMN_NAME = 'base_id';
+
+SELECT COUNT(*) INTO @takeover_acs_base_id_is_nullable
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_acs'
+  AND COLUMN_NAME = 'base_id'
+  AND IS_NULLABLE = 'YES';
+
+SET @alter_takeover_acs_base_id_sql := IF(
+  @takeover_acs_has_base_id = 1 AND @takeover_acs_base_id_is_nullable = 0,
+  'ALTER TABLE takeover_acs MODIFY COLUMN base_id BINARY(16) NULL',
+  'SELECT 1'
+);
+PREPARE stmt_alter_takeover_acs_base_id FROM @alter_takeover_acs_base_id_sql;
+EXECUTE stmt_alter_takeover_acs_base_id;
+DEALLOCATE PREPARE stmt_alter_takeover_acs_base_id;
+
+-- +goose Down
+-- Only restore NOT NULL when there are no NULL rows, so rollback stays safe.
+
+SET @schema_name := DATABASE();
+
+SELECT COUNT(*) INTO @takeover_acs_has_base_id
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_acs'
+  AND COLUMN_NAME = 'base_id';
+
+SELECT COUNT(*) INTO @takeover_acs_null_base_rows
+FROM takeover_acs
+WHERE base_id IS NULL
+  AND deleted_at IS NULL;
+
+SELECT COUNT(*) INTO @takeover_acs_base_id_is_nullable
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_acs'
+  AND COLUMN_NAME = 'base_id'
+  AND IS_NULLABLE = 'YES';
+
+SET @restore_takeover_acs_base_id_sql := IF(
+  @takeover_acs_has_base_id = 1 AND @takeover_acs_base_id_is_nullable = 1 AND @takeover_acs_null_base_rows = 0,
+  'ALTER TABLE takeover_acs MODIFY COLUMN base_id BINARY(16) NOT NULL',
+  'SELECT 1'
+);
+PREPARE stmt_restore_takeover_acs_base_id FROM @restore_takeover_acs_base_id_sql;
+EXECUTE stmt_restore_takeover_acs_base_id;
+DEALLOCATE PREPARE stmt_restore_takeover_acs_base_id;
diff --git a/migrations/20260609_takeover_roster_rows.sql b/migrations/20260609_takeover_roster_rows.sql
new file mode 100644
index 0000000..a13353e
--- /dev/null
+++ b/migrations/20260609_takeover_roster_rows.sql
@@ -0,0 +1,378 @@
+-- +goose Up
+-- Expand takeover roster child tables so takeover can store roster_detail without a duty_roster header.
+
+SET @schema_name := DATABASE();
+
+SELECT COUNT(*) INTO @has_takeover_roster_crews
+FROM information_schema.TABLES
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews';
+
+SELECT COUNT(*) INTO @has_col_role_code
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'role_code';
+
+SET @sql_add_role_code := IF(@has_takeover_roster_crews = 1 AND @has_col_role_code = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN role_code VARCHAR(64) NOT NULL DEFAULT ''pilot'' AFTER confirm_at',
+  'SELECT 1'
+);
+PREPARE stmt_add_role_code FROM @sql_add_role_code;
+EXECUTE stmt_add_role_code;
+DEALLOCATE PREPARE stmt_add_role_code;
+
+SELECT COUNT(*) INTO @has_col_crew_type
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'crew_type';
+
+SET @sql_add_crew_type := IF(@has_takeover_roster_crews = 1 AND @has_col_crew_type = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN crew_type VARCHAR(32) NOT NULL DEFAULT ''main'' AFTER role_code',
+  'SELECT 1'
+);
+PREPARE stmt_add_crew_type FROM @sql_add_crew_type;
+EXECUTE stmt_add_crew_type;
+DEALLOCATE PREPARE stmt_add_crew_type;
+
+SELECT COUNT(*) INTO @has_col_user_id
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'user_id';
+
+SET @sql_add_user_id := IF(@has_takeover_roster_crews = 1 AND @has_col_user_id = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN user_id BINARY(16) NULL AFTER crew_type',
+  'SELECT 1'
+);
+PREPARE stmt_add_user_id FROM @sql_add_user_id;
+EXECUTE stmt_add_user_id;
+DEALLOCATE PREPARE stmt_add_user_id;
+
+SELECT COUNT(*) INTO @has_col_name_label
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'name_label';
+
+SET @sql_add_name_label := IF(@has_takeover_roster_crews = 1 AND @has_col_name_label = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN name_label VARCHAR(191) NULL AFTER user_id',
+  'SELECT 1'
+);
+PREPARE stmt_add_name_label FROM @sql_add_name_label;
+EXECUTE stmt_add_name_label;
+DEALLOCATE PREPARE stmt_add_name_label;
+
+SELECT COUNT(*) INTO @has_col_mobile_phone
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'mobile_phone';
+
+SET @sql_add_mobile_phone := IF(@has_takeover_roster_crews = 1 AND @has_col_mobile_phone = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN mobile_phone VARCHAR(64) NULL AFTER name_label',
+  'SELECT 1'
+);
+PREPARE stmt_add_mobile_phone FROM @sql_add_mobile_phone;
+EXECUTE stmt_add_mobile_phone;
+DEALLOCATE PREPARE stmt_add_mobile_phone;
+
+SELECT COUNT(*) INTO @has_col_email
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'email';
+
+SET @sql_add_email := IF(@has_takeover_roster_crews = 1 AND @has_col_email = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN email VARCHAR(191) NULL AFTER mobile_phone',
+  'SELECT 1'
+);
+PREPARE stmt_add_email FROM @sql_add_email;
+EXECUTE stmt_add_email;
+DEALLOCATE PREPARE stmt_add_email;
+
+SELECT COUNT(*) INTO @has_col_date_start
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'date_start';
+
+SET @sql_add_date_start := IF(@has_takeover_roster_crews = 1 AND @has_col_date_start = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN date_start DATE NULL AFTER email',
+  'SELECT 1'
+);
+PREPARE stmt_add_date_start FROM @sql_add_date_start;
+EXECUTE stmt_add_date_start;
+DEALLOCATE PREPARE stmt_add_date_start;
+
+SELECT COUNT(*) INTO @has_col_date_end
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'date_end';
+
+SET @sql_add_date_end := IF(@has_takeover_roster_crews = 1 AND @has_col_date_end = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN date_end DATE NULL AFTER date_start',
+  'SELECT 1'
+);
+PREPARE stmt_add_date_end FROM @sql_add_date_end;
+EXECUTE stmt_add_date_end;
+DEALLOCATE PREPARE stmt_add_date_end;
+
+SELECT COUNT(*) INTO @has_col_shift_start
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'shift_start';
+
+SET @sql_add_shift_start := IF(@has_takeover_roster_crews = 1 AND @has_col_shift_start = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN shift_start TIME NULL AFTER date_end',
+  'SELECT 1'
+);
+PREPARE stmt_add_shift_start FROM @sql_add_shift_start;
+EXECUTE stmt_add_shift_start;
+DEALLOCATE PREPARE stmt_add_shift_start;
+
+SELECT COUNT(*) INTO @has_col_shift_end
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'shift_end';
+
+SET @sql_add_shift_end := IF(@has_takeover_roster_crews = 1 AND @has_col_shift_end = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN shift_end TIME NULL AFTER shift_start',
+  'SELECT 1'
+);
+PREPARE stmt_add_shift_end FROM @sql_add_shift_end;
+EXECUTE stmt_add_shift_end;
+DEALLOCATE PREPARE stmt_add_shift_end;
+
+SELECT COUNT(*) INTO @has_col_flight_instructor
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'flight_instructor';
+
+SET @sql_add_flight_instructor := IF(@has_takeover_roster_crews = 1 AND @has_col_flight_instructor = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN flight_instructor TINYINT(1) NOT NULL DEFAULT 0 AFTER shift_end',
+  'SELECT 1'
+);
+PREPARE stmt_add_flight_instructor FROM @sql_add_flight_instructor;
+EXECUTE stmt_add_flight_instructor;
+DEALLOCATE PREPARE stmt_add_flight_instructor;
+
+SELECT COUNT(*) INTO @has_col_line_checker
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'line_checker';
+
+SET @sql_add_line_checker := IF(@has_takeover_roster_crews = 1 AND @has_col_line_checker = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN line_checker TINYINT(1) NOT NULL DEFAULT 0 AFTER flight_instructor',
+  'SELECT 1'
+);
+PREPARE stmt_add_line_checker FROM @sql_add_line_checker;
+EXECUTE stmt_add_line_checker;
+DEALLOCATE PREPARE stmt_add_line_checker;
+
+SELECT COUNT(*) INTO @has_col_supervisor
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'supervisor';
+
+SET @sql_add_supervisor := IF(@has_takeover_roster_crews = 1 AND @has_col_supervisor = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN supervisor TINYINT(1) NOT NULL DEFAULT 0 AFTER line_checker',
+  'SELECT 1'
+);
+PREPARE stmt_add_supervisor FROM @sql_add_supervisor;
+EXECUTE stmt_add_supervisor;
+DEALLOCATE PREPARE stmt_add_supervisor;
+
+SELECT COUNT(*) INTO @has_col_examiner
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'examiner';
+
+SET @sql_add_examiner := IF(@has_takeover_roster_crews = 1 AND @has_col_examiner = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN examiner TINYINT(1) NOT NULL DEFAULT 0 AFTER supervisor',
+  'SELECT 1'
+);
+PREPARE stmt_add_examiner FROM @sql_add_examiner;
+EXECUTE stmt_add_examiner;
+DEALLOCATE PREPARE stmt_add_examiner;
+
+SELECT COUNT(*) INTO @has_col_co_pilot
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND COLUMN_NAME = 'co_pilot';
+
+SET @sql_add_co_pilot := IF(@has_takeover_roster_crews = 1 AND @has_col_co_pilot = 0,
+  'ALTER TABLE takeover_roster_crews ADD COLUMN co_pilot TINYINT(1) NOT NULL DEFAULT 0 AFTER examiner',
+  'SELECT 1'
+);
+PREPARE stmt_add_co_pilot FROM @sql_add_co_pilot;
+EXECUTE stmt_add_co_pilot;
+DEALLOCATE PREPARE stmt_add_co_pilot;
+
+-- Keep the takeover child lookup fast and idempotent.
+SELECT COUNT(*) INTO @has_takeover_roster_unique
+FROM information_schema.STATISTICS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND INDEX_NAME = 'idx_takeover_roster_crews_unique';
+
+SET @sql_add_takeover_roster_unique := IF(@has_takeover_roster_crews = 1 AND @has_takeover_roster_unique = 0,
+  'CREATE UNIQUE INDEX idx_takeover_roster_crews_unique ON takeover_roster_crews(takeover_id, role_code, crew_type, user_id, name_label, date_start, date_end, shift_start, shift_end)',
+  'SELECT 1'
+);
+PREPARE stmt_add_takeover_roster_unique FROM @sql_add_takeover_roster_unique;
+EXECUTE stmt_add_takeover_roster_unique;
+DEALLOCATE PREPARE stmt_add_takeover_roster_unique;
+
+-- +goose Down
+-- Roll back only the columns/index added for takeover roster normalization.
+
+SET @schema_name := DATABASE();
+
+SELECT COUNT(*) INTO @has_takeover_roster_unique
+FROM information_schema.STATISTICS
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews'
+  AND INDEX_NAME = 'idx_takeover_roster_crews_unique';
+
+SET @sql_drop_takeover_roster_unique := IF(@has_takeover_roster_unique = 1,
+  'DROP INDEX idx_takeover_roster_crews_unique ON takeover_roster_crews',
+  'SELECT 1'
+);
+PREPARE stmt_drop_takeover_roster_unique FROM @sql_drop_takeover_roster_unique;
+EXECUTE stmt_drop_takeover_roster_unique;
+DEALLOCATE PREPARE stmt_drop_takeover_roster_unique;
+
+SELECT COUNT(*) INTO @has_takeover_roster_crews
+FROM information_schema.TABLES
+WHERE TABLE_SCHEMA = @schema_name
+  AND TABLE_NAME = 'takeover_roster_crews';
+
+SET @sql_drop_co_pilot := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'co_pilot'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN co_pilot', 'SELECT 1');
+PREPARE stmt_drop_co_pilot FROM @sql_drop_co_pilot;
+EXECUTE stmt_drop_co_pilot;
+DEALLOCATE PREPARE stmt_drop_co_pilot;
+
+SET @sql_drop_examiner := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'examiner'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN examiner', 'SELECT 1');
+PREPARE stmt_drop_examiner FROM @sql_drop_examiner;
+EXECUTE stmt_drop_examiner;
+DEALLOCATE PREPARE stmt_drop_examiner;
+
+SET @sql_drop_supervisor := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'supervisor'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN supervisor', 'SELECT 1');
+PREPARE stmt_drop_supervisor FROM @sql_drop_supervisor;
+EXECUTE stmt_drop_supervisor;
+DEALLOCATE PREPARE stmt_drop_supervisor;
+
+SET @sql_drop_line_checker := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'line_checker'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN line_checker', 'SELECT 1');
+PREPARE stmt_drop_line_checker FROM @sql_drop_line_checker;
+EXECUTE stmt_drop_line_checker;
+DEALLOCATE PREPARE stmt_drop_line_checker;
+
+SET @sql_drop_flight_instructor := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'flight_instructor'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN flight_instructor', 'SELECT 1');
+PREPARE stmt_drop_flight_instructor FROM @sql_drop_flight_instructor;
+EXECUTE stmt_drop_flight_instructor;
+DEALLOCATE PREPARE stmt_drop_flight_instructor;
+
+SET @sql_drop_shift_end := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'shift_end'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN shift_end', 'SELECT 1');
+PREPARE stmt_drop_shift_end FROM @sql_drop_shift_end;
+EXECUTE stmt_drop_shift_end;
+DEALLOCATE PREPARE stmt_drop_shift_end;
+
+SET @sql_drop_shift_start := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'shift_start'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN shift_start', 'SELECT 1');
+PREPARE stmt_drop_shift_start FROM @sql_drop_shift_start;
+EXECUTE stmt_drop_shift_start;
+DEALLOCATE PREPARE stmt_drop_shift_start;
+
+SET @sql_drop_date_end := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'date_end'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN date_end', 'SELECT 1');
+PREPARE stmt_drop_date_end FROM @sql_drop_date_end;
+EXECUTE stmt_drop_date_end;
+DEALLOCATE PREPARE stmt_drop_date_end;
+
+SET @sql_drop_date_start := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'date_start'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN date_start', 'SELECT 1');
+PREPARE stmt_drop_date_start FROM @sql_drop_date_start;
+EXECUTE stmt_drop_date_start;
+DEALLOCATE PREPARE stmt_drop_date_start;
+
+SET @sql_drop_email := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'email'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN email', 'SELECT 1');
+PREPARE stmt_drop_email FROM @sql_drop_email;
+EXECUTE stmt_drop_email;
+DEALLOCATE PREPARE stmt_drop_email;
+
+SET @sql_drop_mobile_phone := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'mobile_phone'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN mobile_phone', 'SELECT 1');
+PREPARE stmt_drop_mobile_phone FROM @sql_drop_mobile_phone;
+EXECUTE stmt_drop_mobile_phone;
+DEALLOCATE PREPARE stmt_drop_mobile_phone;
+
+SET @sql_drop_name_label := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'name_label'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN name_label', 'SELECT 1');
+PREPARE stmt_drop_name_label FROM @sql_drop_name_label;
+EXECUTE stmt_drop_name_label;
+DEALLOCATE PREPARE stmt_drop_name_label;
+
+SET @sql_drop_user_id := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'user_id'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN user_id', 'SELECT 1');
+PREPARE stmt_drop_user_id FROM @sql_drop_user_id;
+EXECUTE stmt_drop_user_id;
+DEALLOCATE PREPARE stmt_drop_user_id;
+
+SET @sql_drop_crew_type := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'crew_type'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN crew_type', 'SELECT 1');
+PREPARE stmt_drop_crew_type FROM @sql_drop_crew_type;
+EXECUTE stmt_drop_crew_type;
+DEALLOCATE PREPARE stmt_drop_crew_type;
+
+SET @sql_drop_role_code := IF(@has_takeover_roster_crews = 1 AND EXISTS(
+  SELECT 1 FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name AND TABLE_NAME = 'takeover_roster_crews' AND COLUMN_NAME = 'role_code'
+), 'ALTER TABLE takeover_roster_crews DROP COLUMN role_code', 'SELECT 1');
+PREPARE stmt_drop_role_code FROM @sql_drop_role_code;
+EXECUTE stmt_drop_role_code;
+DEALLOCATE PREPARE stmt_drop_role_code;
diff --git a/migrations/20260610_drop_counter_from_helicopters.sql b/migrations/20260610_drop_counter_from_helicopters.sql
new file mode 100644
index 0000000..79d2142
--- /dev/null
+++ b/migrations/20260610_drop_counter_from_helicopters.sql
@@ -0,0 +1,7 @@
+-- +goose Up
+ALTER TABLE helicopters
+  DROP COLUMN counter;
+
+-- +goose Down
+ALTER TABLE helicopters
+  ADD COLUMN counter INT NOT NULL DEFAULT 0 AFTER sortkey;
diff --git a/migrations/20260612_base_operational_shift_times.sql b/migrations/20260612_base_operational_shift_times.sql
new file mode 100644
index 0000000..2468068
--- /dev/null
+++ b/migrations/20260612_base_operational_shift_times.sql
@@ -0,0 +1,54 @@
+-- +goose Up
+-- Legacy/manual migration kept for reference. Canonical goose migration:
+-- migrations/goose/20260613_base_operational_shift_times_date_range.sql
+
+ALTER TABLE base_operational_shift_times
+  ADD COLUMN IF NOT EXISTS date_start DATE NULL AFTER base_id,
+  ADD COLUMN IF NOT EXISTS date_end DATE NULL AFTER date_start;
+
+UPDATE base_operational_shift_times
+SET date_start = COALESCE(date_start, operation_date),
+    date_end = COALESCE(date_end, operation_date)
+WHERE deleted_at IS NULL;
+
+ALTER TABLE base_operational_shift_times
+  DROP FOREIGN KEY fk_base_operational_shift_times_base;
+
+ALTER TABLE base_operational_shift_times
+  DROP INDEX idx_base_operational_shift_times_base_date;
+
+ALTER TABLE base_operational_shift_times
+  DROP COLUMN operation_date;
+
+ALTER TABLE base_operational_shift_times
+  ADD KEY idx_base_operational_shift_times_base_date (base_id, date_start, date_end),
+  MODIFY COLUMN date_start DATE NULL,
+  MODIFY COLUMN date_end DATE NULL,
+  ADD CONSTRAINT fk_base_operational_shift_times_base
+    FOREIGN KEY (base_id) REFERENCES bases(id)
+    ON UPDATE CASCADE
+    ON DELETE CASCADE;
+
+-- +goose Down
+ALTER TABLE base_operational_shift_times
+  ADD COLUMN IF NOT EXISTS operation_date DATE NULL AFTER base_id;
+
+UPDATE base_operational_shift_times
+SET operation_date = COALESCE(operation_date, date_start)
+WHERE deleted_at IS NULL;
+
+ALTER TABLE base_operational_shift_times
+  DROP FOREIGN KEY fk_base_operational_shift_times_base;
+
+ALTER TABLE base_operational_shift_times
+  DROP INDEX idx_base_operational_shift_times_base_date;
+
+ALTER TABLE base_operational_shift_times
+  ADD KEY idx_base_operational_shift_times_base_date (base_id, operation_date),
+  DROP COLUMN date_start,
+  DROP COLUMN date_end,
+  MODIFY COLUMN operation_date DATE NOT NULL,
+  ADD CONSTRAINT fk_base_operational_shift_times_base
+    FOREIGN KEY (base_id) REFERENCES bases(id)
+    ON UPDATE CASCADE
+    ON DELETE CASCADE;
diff --git a/migrations/20260615_add_status_to_flight_data.sql b/migrations/20260615_add_status_to_flight_data.sql
new file mode 100644
index 0000000..4d73525
--- /dev/null
+++ b/migrations/20260615_add_status_to_flight_data.sql
@@ -0,0 +1,41 @@
+-- +goose Up
+SET @has_status := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'flight_data'
+    AND column_name = 'status'
+);
+
+SET @sql := IF(
+  @has_status = 0,
+  'ALTER TABLE flight_data ADD COLUMN status VARCHAR(20) NOT NULL DEFAULT ''on_going'' AFTER id',
+  'SELECT 1'
+);
+
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+UPDATE flight_data
+SET status = 'on_going'
+WHERE status IS NULL OR status = '';
+
+-- +goose Down
+SET @has_status := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'flight_data'
+    AND column_name = 'status'
+);
+
+SET @sql := IF(
+  @has_status = 1,
+  'ALTER TABLE flight_data DROP COLUMN status',
+  'SELECT 1'
+);
+
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
diff --git a/migrations/20260616_create_fm_reports.sql b/migrations/20260616_create_fm_reports.sql
new file mode 100644
index 0000000..56a3839
--- /dev/null
+++ b/migrations/20260616_create_fm_reports.sql
@@ -0,0 +1,23 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS fm_reports (
+  id BINARY(16) NOT NULL,
+  takeover_id BINARY(16) NOT NULL,
+  flight_id BINARY(16) NOT NULL,
+  flight_inspection_id BINARY(16) NOT NULL,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME NULL,
+  deleted_by BINARY(16) NULL,
+  PRIMARY KEY (id),
+  UNIQUE KEY uidx_fm_reports_takeover_id (takeover_id),
+  UNIQUE KEY uidx_fm_reports_flight_id (flight_id),
+  UNIQUE KEY uidx_fm_reports_flight_inspection_id (flight_inspection_id),
+  CONSTRAINT fk_fm_reports_takeover FOREIGN KEY (takeover_id) REFERENCES takeover_acs (id) ON DELETE CASCADE ON UPDATE CASCADE,
+  CONSTRAINT fk_fm_reports_flight FOREIGN KEY (flight_id) REFERENCES flights (id) ON DELETE CASCADE ON UPDATE CASCADE,
+  CONSTRAINT fk_fm_reports_flight_inspection FOREIGN KEY (flight_inspection_id) REFERENCES flight_inspections (id) ON DELETE CASCADE ON UPDATE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS fm_reports;
diff --git a/migrations/20260618_add_gpc_ptc_to_fm_reports.sql b/migrations/20260618_add_gpc_ptc_to_fm_reports.sql
new file mode 100644
index 0000000..18c81ad
--- /dev/null
+++ b/migrations/20260618_add_gpc_ptc_to_fm_reports.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+ALTER TABLE fm_reports
+  ADD COLUMN gpc_n1 VARCHAR(255) NOT NULL DEFAULT '' AFTER flight_inspection_id,
+  ADD COLUMN ptc_n2 VARCHAR(255) NOT NULL DEFAULT '' AFTER gpc_n1;
+
+-- +goose Down
+ALTER TABLE fm_reports
+  DROP COLUMN ptc_n2,
+  DROP COLUMN gpc_n1;
diff --git a/migrations/20260619_mission_twilight_schedule.sql b/migrations/20260619_mission_twilight_schedule.sql
new file mode 100644
index 0000000..37b6144
--- /dev/null
+++ b/migrations/20260619_mission_twilight_schedule.sql
@@ -0,0 +1,29 @@
+-- +goose Up
+ALTER TABLE bases
+  ADD COLUMN IF NOT EXISTS latitude DECIMAL(10,7) NOT NULL DEFAULT 0 AFTER address,
+  ADD COLUMN IF NOT EXISTS longitude DECIMAL(10,7) NOT NULL DEFAULT 0 AFTER latitude;
+
+ALTER TABLE base_operational_shift_times
+  ADD COLUMN IF NOT EXISTS start_time_type VARCHAR(16) NOT NULL DEFAULT 'FIXED' AFTER date_end,
+  ADD COLUMN IF NOT EXISTS end_time_type VARCHAR(16) NOT NULL DEFAULT 'FIXED' AFTER start_time_type;
+
+ALTER TABLE missions
+  ADD COLUMN IF NOT EXISTS start_time TIME NULL AFTER note,
+  ADD COLUMN IF NOT EXISTS end_time TIME NULL AFTER start_time;
+
+ALTER TABLE missions
+  MODIFY COLUMN start_time TIME NULL,
+  MODIFY COLUMN end_time TIME NULL;
+
+-- +goose Down
+ALTER TABLE missions
+  DROP COLUMN IF EXISTS end_time,
+  DROP COLUMN IF EXISTS start_time;
+
+ALTER TABLE base_operational_shift_times
+  DROP COLUMN IF EXISTS end_time_type,
+  DROP COLUMN IF EXISTS start_time_type;
+
+ALTER TABLE bases
+  DROP COLUMN IF EXISTS longitude,
+  DROP COLUMN IF EXISTS latitude;
diff --git a/migrations/20260621_rename_fm_report_engine1_metrics_add_engine2_metrics.sql b/migrations/20260621_rename_fm_report_engine1_metrics_add_engine2_metrics.sql
new file mode 100644
index 0000000..9a74f7c
--- /dev/null
+++ b/migrations/20260621_rename_fm_report_engine1_metrics_add_engine2_metrics.sql
@@ -0,0 +1,17 @@
+-- +goose Up
+ALTER TABLE fm_reports
+  CHANGE COLUMN gpc_n1 engine1_gpc_n1 VARCHAR(255) NULL DEFAULT NULL,
+  CHANGE COLUMN ptc_n2 engine1_ptc_n2 VARCHAR(255) NULL DEFAULT NULL;
+
+ALTER TABLE fm_reports
+  ADD COLUMN engine2_gpc_n1 VARCHAR(255) NULL DEFAULT NULL AFTER engine1_ptc_n2,
+  ADD COLUMN engine2_ptc_n2 VARCHAR(255) NULL DEFAULT NULL AFTER engine2_gpc_n1;
+
+-- +goose Down
+ALTER TABLE fm_reports
+  DROP COLUMN engine2_ptc_n2,
+  DROP COLUMN engine2_gpc_n1;
+
+ALTER TABLE fm_reports
+  CHANGE COLUMN engine1_ptc_n2 ptc_n2 VARCHAR(255) NULL DEFAULT NULL,
+  CHANGE COLUMN engine1_gpc_n1 gpc_n1 VARCHAR(255) NULL DEFAULT NULL;
diff --git a/migrations/20260622_after_flight_inspection_checked_fields_to_string.sql b/migrations/20260622_after_flight_inspection_checked_fields_to_string.sql
new file mode 100644
index 0000000..1aeee94
--- /dev/null
+++ b/migrations/20260622_after_flight_inspection_checked_fields_to_string.sql
@@ -0,0 +1,129 @@
+-- +goose Up
+ALTER TABLE after_flight_inspections
+  ADD COLUMN oil_engine_nr1_checked_tmp VARCHAR(255) NULL DEFAULT NULL,
+  ADD COLUMN oil_engine_nr2_checked_tmp VARCHAR(255) NULL DEFAULT NULL,
+  ADD COLUMN hydraulic_lh_checked_tmp VARCHAR(255) NULL DEFAULT NULL,
+  ADD COLUMN hydraulic_rh_checked_tmp VARCHAR(255) NULL DEFAULT NULL,
+  ADD COLUMN oil_transmission_mgb_checked_tmp VARCHAR(255) NULL DEFAULT NULL,
+  ADD COLUMN oil_transmission_igb_checked_tmp VARCHAR(255) NULL DEFAULT NULL,
+  ADD COLUMN oil_transmission_tgb_checked_tmp VARCHAR(255) NULL DEFAULT NULL;
+
+UPDATE after_flight_inspections
+SET oil_engine_nr1_checked_tmp = CASE
+  WHEN oil_engine_nr1_checked IS NULL THEN NULL
+  WHEN oil_engine_nr1_checked IN (1, TRUE) THEN 'true'
+  ELSE 'false'
+END,
+oil_engine_nr2_checked_tmp = CASE
+  WHEN oil_engine_nr2_checked IS NULL THEN NULL
+  WHEN oil_engine_nr2_checked IN (1, TRUE) THEN 'true'
+  ELSE 'false'
+END,
+hydraulic_lh_checked_tmp = CASE
+  WHEN hydraulic_lh_checked IS NULL THEN NULL
+  WHEN hydraulic_lh_checked IN (1, TRUE) THEN 'true'
+  ELSE 'false'
+END,
+hydraulic_rh_checked_tmp = CASE
+  WHEN hydraulic_rh_checked IS NULL THEN NULL
+  WHEN hydraulic_rh_checked IN (1, TRUE) THEN 'true'
+  ELSE 'false'
+END,
+oil_transmission_mgb_checked_tmp = CASE
+  WHEN oil_transmission_mgb_checked IS NULL THEN NULL
+  WHEN oil_transmission_mgb_checked IN (1, TRUE) THEN 'true'
+  ELSE 'false'
+END,
+oil_transmission_igb_checked_tmp = CASE
+  WHEN oil_transmission_igb_checked IS NULL THEN NULL
+  WHEN oil_transmission_igb_checked IN (1, TRUE) THEN 'true'
+  ELSE 'false'
+END,
+oil_transmission_tgb_checked_tmp = CASE
+  WHEN oil_transmission_tgb_checked IS NULL THEN NULL
+  WHEN oil_transmission_tgb_checked IN (1, TRUE) THEN 'true'
+  ELSE 'false'
+END;
+
+ALTER TABLE after_flight_inspections
+  DROP COLUMN oil_engine_nr1_checked,
+  DROP COLUMN oil_engine_nr2_checked,
+  DROP COLUMN hydraulic_lh_checked,
+  DROP COLUMN hydraulic_rh_checked,
+  DROP COLUMN oil_transmission_mgb_checked,
+  DROP COLUMN oil_transmission_igb_checked,
+  DROP COLUMN oil_transmission_tgb_checked;
+
+ALTER TABLE after_flight_inspections
+  CHANGE COLUMN oil_engine_nr1_checked_tmp oil_engine_nr1_checked VARCHAR(255) NULL DEFAULT NULL,
+  CHANGE COLUMN oil_engine_nr2_checked_tmp oil_engine_nr2_checked VARCHAR(255) NULL DEFAULT NULL,
+  CHANGE COLUMN hydraulic_lh_checked_tmp hydraulic_lh_checked VARCHAR(255) NULL DEFAULT NULL,
+  CHANGE COLUMN hydraulic_rh_checked_tmp hydraulic_rh_checked VARCHAR(255) NULL DEFAULT NULL,
+  CHANGE COLUMN oil_transmission_mgb_checked_tmp oil_transmission_mgb_checked VARCHAR(255) NULL DEFAULT NULL,
+  CHANGE COLUMN oil_transmission_igb_checked_tmp oil_transmission_igb_checked VARCHAR(255) NULL DEFAULT NULL,
+  CHANGE COLUMN oil_transmission_tgb_checked_tmp oil_transmission_tgb_checked VARCHAR(255) NULL DEFAULT NULL;
+
+-- +goose Down
+ALTER TABLE after_flight_inspections
+  ADD COLUMN oil_engine_nr1_checked_tmp TINYINT(1) NULL,
+  ADD COLUMN oil_engine_nr2_checked_tmp TINYINT(1) NULL,
+  ADD COLUMN hydraulic_lh_checked_tmp TINYINT(1) NULL,
+  ADD COLUMN hydraulic_rh_checked_tmp TINYINT(1) NULL,
+  ADD COLUMN oil_transmission_mgb_checked_tmp TINYINT(1) NULL,
+  ADD COLUMN oil_transmission_igb_checked_tmp TINYINT(1) NULL,
+  ADD COLUMN oil_transmission_tgb_checked_tmp TINYINT(1) NULL;
+
+UPDATE after_flight_inspections
+SET oil_engine_nr1_checked_tmp = CASE
+  WHEN oil_engine_nr1_checked IS NULL THEN NULL
+  WHEN LOWER(TRIM(oil_engine_nr1_checked)) IN ('true', 'checked', 'yes', '1') THEN 1
+  ELSE 0
+END,
+oil_engine_nr2_checked_tmp = CASE
+  WHEN oil_engine_nr2_checked IS NULL THEN NULL
+  WHEN LOWER(TRIM(oil_engine_nr2_checked)) IN ('true', 'checked', 'yes', '1') THEN 1
+  ELSE 0
+END,
+hydraulic_lh_checked_tmp = CASE
+  WHEN hydraulic_lh_checked IS NULL THEN NULL
+  WHEN LOWER(TRIM(hydraulic_lh_checked)) IN ('true', 'checked', 'yes', '1') THEN 1
+  ELSE 0
+END,
+hydraulic_rh_checked_tmp = CASE
+  WHEN hydraulic_rh_checked IS NULL THEN NULL
+  WHEN LOWER(TRIM(hydraulic_rh_checked)) IN ('true', 'checked', 'yes', '1') THEN 1
+  ELSE 0
+END,
+oil_transmission_mgb_checked_tmp = CASE
+  WHEN oil_transmission_mgb_checked IS NULL THEN NULL
+  WHEN LOWER(TRIM(oil_transmission_mgb_checked)) IN ('true', 'checked', 'yes', '1') THEN 1
+  ELSE 0
+END,
+oil_transmission_igb_checked_tmp = CASE
+  WHEN oil_transmission_igb_checked IS NULL THEN NULL
+  WHEN LOWER(TRIM(oil_transmission_igb_checked)) IN ('true', 'checked', 'yes', '1') THEN 1
+  ELSE 0
+END,
+oil_transmission_tgb_checked_tmp = CASE
+  WHEN oil_transmission_tgb_checked IS NULL THEN NULL
+  WHEN LOWER(TRIM(oil_transmission_tgb_checked)) IN ('true', 'checked', 'yes', '1') THEN 1
+  ELSE 0
+END;
+
+ALTER TABLE after_flight_inspections
+  DROP COLUMN oil_engine_nr1_checked,
+  DROP COLUMN oil_engine_nr2_checked,
+  DROP COLUMN hydraulic_lh_checked,
+  DROP COLUMN hydraulic_rh_checked,
+  DROP COLUMN oil_transmission_mgb_checked,
+  DROP COLUMN oil_transmission_igb_checked,
+  DROP COLUMN oil_transmission_tgb_checked;
+
+ALTER TABLE after_flight_inspections
+  CHANGE COLUMN oil_engine_nr1_checked_tmp oil_engine_nr1_checked TINYINT(1) NULL,
+  CHANGE COLUMN oil_engine_nr2_checked_tmp oil_engine_nr2_checked TINYINT(1) NULL,
+  CHANGE COLUMN hydraulic_lh_checked_tmp hydraulic_lh_checked TINYINT(1) NULL,
+  CHANGE COLUMN hydraulic_rh_checked_tmp hydraulic_rh_checked TINYINT(1) NULL,
+  CHANGE COLUMN oil_transmission_mgb_checked_tmp oil_transmission_mgb_checked TINYINT(1) NULL,
+  CHANGE COLUMN oil_transmission_igb_checked_tmp oil_transmission_igb_checked TINYINT(1) NULL,
+  CHANGE COLUMN oil_transmission_tgb_checked_tmp oil_transmission_tgb_checked TINYINT(1) NULL;
diff --git a/migrations/20260622_create_takeover_files.sql b/migrations/20260622_create_takeover_files.sql
new file mode 100644
index 0000000..e094801
--- /dev/null
+++ b/migrations/20260622_create_takeover_files.sql
@@ -0,0 +1,11 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS takeover_files (
+  id BINARY(16) NOT NULL PRIMARY KEY,
+  takeover_id BINARY(16) NOT NULL,
+  file_attachment_id BINARY(16) NOT NULL,
+  KEY idx_takeover_files_takeover_id (takeover_id),
+  KEY idx_takeover_files_file_attachment_id (file_attachment_id)
+);
+
+-- +goose Down
+DROP TABLE IF EXISTS takeover_files;
diff --git a/migrations/20260622_drop_after_flight_ac_oil_upload_liter.sql b/migrations/20260622_drop_after_flight_ac_oil_upload_liter.sql
new file mode 100644
index 0000000..d9c6872
--- /dev/null
+++ b/migrations/20260622_drop_after_flight_ac_oil_upload_liter.sql
@@ -0,0 +1,13 @@
+-- +goose Up
+ALTER TABLE after_flight_inspections
+  DROP CHECK chk_after_flight_ac_oil_upload_liter;
+
+ALTER TABLE after_flight_inspections
+  DROP COLUMN ac_oil_upload_liter;
+
+-- +goose Down
+ALTER TABLE after_flight_inspections
+  ADD COLUMN ac_oil_upload_liter DECIMAL(10,2) NULL;
+
+ALTER TABLE after_flight_inspections
+  ADD CONSTRAINT chk_after_flight_ac_oil_upload_liter CHECK (ac_oil_upload_liter IS NULL OR ac_oil_upload_liter >= 0);
diff --git a/migrations/20260623_add_fm_report_completion_columns.sql b/migrations/20260623_add_fm_report_completion_columns.sql
new file mode 100644
index 0000000..07979b5
--- /dev/null
+++ b/migrations/20260623_add_fm_report_completion_columns.sql
@@ -0,0 +1,11 @@
+-- +goose Up
+ALTER TABLE fm_reports
+  ADD COLUMN completed_at DATETIME(3) NULL DEFAULT NULL AFTER engine2_ptc_n2,
+  ADD COLUMN completed_by BINARY(16) NULL DEFAULT NULL AFTER completed_at,
+  ADD KEY idx_fm_reports_completed_at (completed_at);
+
+-- +goose Down
+ALTER TABLE fm_reports
+  DROP KEY idx_fm_reports_completed_at,
+  DROP COLUMN completed_by,
+  DROP COLUMN completed_at;
diff --git a/migrations/20260623_bases_default_shift_required.sql b/migrations/20260623_bases_default_shift_required.sql
new file mode 100644
index 0000000..3678f7c
--- /dev/null
+++ b/migrations/20260623_bases_default_shift_required.sql
@@ -0,0 +1,101 @@
+-- +goose Up
+SET @bases_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.tables
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+);
+
+SET @col_default_shift_start_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'default_shift_start'
+);
+
+SET @col_default_shift_end_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'default_shift_end'
+);
+
+SET @backfill_default_shift_start_sql := IF(
+  @bases_exists > 0 AND @col_default_shift_start_exists > 0,
+  "UPDATE bases SET default_shift_start = '06:00:00' WHERE default_shift_start IS NULL",
+  'SELECT 1'
+);
+PREPARE stmt_backfill_default_shift_start FROM @backfill_default_shift_start_sql;
+EXECUTE stmt_backfill_default_shift_start;
+DEALLOCATE PREPARE stmt_backfill_default_shift_start;
+
+SET @backfill_default_shift_end_sql := IF(
+  @bases_exists > 0 AND @col_default_shift_end_exists > 0,
+  "UPDATE bases SET default_shift_end = '21:00:00' WHERE default_shift_end IS NULL",
+  'SELECT 1'
+);
+PREPARE stmt_backfill_default_shift_end FROM @backfill_default_shift_end_sql;
+EXECUTE stmt_backfill_default_shift_end;
+DEALLOCATE PREPARE stmt_backfill_default_shift_end;
+
+SET @modify_default_shift_start_sql := IF(
+  @bases_exists > 0 AND @col_default_shift_start_exists > 0,
+  'ALTER TABLE bases MODIFY COLUMN default_shift_start TIME NOT NULL',
+  'SELECT 1'
+);
+PREPARE stmt_modify_default_shift_start FROM @modify_default_shift_start_sql;
+EXECUTE stmt_modify_default_shift_start;
+DEALLOCATE PREPARE stmt_modify_default_shift_start;
+
+SET @modify_default_shift_end_sql := IF(
+  @bases_exists > 0 AND @col_default_shift_end_exists > 0,
+  'ALTER TABLE bases MODIFY COLUMN default_shift_end TIME NOT NULL',
+  'SELECT 1'
+);
+PREPARE stmt_modify_default_shift_end FROM @modify_default_shift_end_sql;
+EXECUTE stmt_modify_default_shift_end;
+DEALLOCATE PREPARE stmt_modify_default_shift_end;
+
+-- +goose Down
+SET @bases_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.tables
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+);
+
+SET @col_default_shift_start_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'default_shift_start'
+);
+
+SET @col_default_shift_end_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'bases'
+    AND column_name = 'default_shift_end'
+);
+
+SET @modify_default_shift_start_sql := IF(
+  @bases_exists > 0 AND @col_default_shift_start_exists > 0,
+  'ALTER TABLE bases MODIFY COLUMN default_shift_start TIME NULL',
+  'SELECT 1'
+);
+PREPARE stmt_modify_default_shift_start_down FROM @modify_default_shift_start_sql;
+EXECUTE stmt_modify_default_shift_start_down;
+DEALLOCATE PREPARE stmt_modify_default_shift_start_down;
+
+SET @modify_default_shift_end_sql := IF(
+  @bases_exists > 0 AND @col_default_shift_end_exists > 0,
+  'ALTER TABLE bases MODIFY COLUMN default_shift_end TIME NULL',
+  'SELECT 1'
+);
+PREPARE stmt_modify_default_shift_end_down FROM @modify_default_shift_end_sql;
+EXECUTE stmt_modify_default_shift_end_down;
+DEALLOCATE PREPARE stmt_modify_default_shift_end_down;
diff --git a/migrations/20260623_create_helicopter_usage.sql b/migrations/20260623_create_helicopter_usage.sql
new file mode 100644
index 0000000..d7c8e1b
--- /dev/null
+++ b/migrations/20260623_create_helicopter_usage.sql
@@ -0,0 +1,32 @@
+-- +goose Up
+CREATE TABLE IF NOT EXISTS helicopter_usage (
+  id BINARY(16) NOT NULL,
+  helicopter_id BINARY(16) NOT NULL,
+  total_landing INT NOT NULL DEFAULT 0,
+  total_airframe_hours DECIMAL(12,2) NOT NULL DEFAULT 0,
+  total_airframe_cycles INT NOT NULL DEFAULT 0,
+  total_engine_1_hours DECIMAL(12,2) NOT NULL DEFAULT 0,
+  total_engine_1_gpc_ng_n1 DECIMAL(12,2) NOT NULL DEFAULT 0,
+  total_engine_1_ptc_nf_n2 DECIMAL(12,2) NOT NULL DEFAULT 0,
+  total_engine_1_ccc INT NOT NULL DEFAULT 0,
+  total_engine_2_hours DECIMAL(12,2) NOT NULL DEFAULT 0,
+  total_engine_2_gpc_ng_n1 DECIMAL(12,2) NOT NULL DEFAULT 0,
+  total_engine_2_ptc_nf_n2 DECIMAL(12,2) NOT NULL DEFAULT 0,
+  total_engine_2_ccc INT NOT NULL DEFAULT 0,
+  total_flight_report INT NOT NULL DEFAULT 0,
+  total_hook_release INT NOT NULL DEFAULT 0,
+  total_rotor_brake_cycle INT NOT NULL DEFAULT 0,
+  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  created_by BINARY(16) NULL,
+  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  updated_by BINARY(16) NULL,
+  deleted_at DATETIME NULL,
+  deleted_by BINARY(16) NULL,
+  PRIMARY KEY (id),
+  UNIQUE KEY uidx_helicopter_usage_helicopter_id (helicopter_id),
+  KEY idx_helicopter_usage_deleted_at (deleted_at),
+  CONSTRAINT fk_helicopter_usage_helicopter FOREIGN KEY (helicopter_id) REFERENCES helicopters (id) ON DELETE RESTRICT ON UPDATE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS helicopter_usage;
diff --git a/migrations/20260624_add_manual_seed_to_helicopter_usage.sql b/migrations/20260624_add_manual_seed_to_helicopter_usage.sql
new file mode 100644
index 0000000..3f62249
--- /dev/null
+++ b/migrations/20260624_add_manual_seed_to_helicopter_usage.sql
@@ -0,0 +1,45 @@
+-- +goose Up
+SET @has_manual := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'helicopter_usage'
+    AND column_name = 'manual_airframe_hours'
+);
+
+SET @sql := IF(
+  @has_manual = 0,
+  'ALTER TABLE helicopter_usage
+     ADD COLUMN manual_airframe_hours DECIMAL(12,2) NOT NULL DEFAULT 0,
+     ADD COLUMN manual_airframe_cycles INT NOT NULL DEFAULT 0,
+     ADD COLUMN manual_engine_1_hours DECIMAL(12,2) NOT NULL DEFAULT 0,
+     ADD COLUMN manual_engine_1_gpc_ng_n1 DECIMAL(12,2) NOT NULL DEFAULT 0,
+     ADD COLUMN manual_engine_1_ptc_nf_n2 DECIMAL(12,2) NOT NULL DEFAULT 0,
+     ADD COLUMN manual_engine_2_hours DECIMAL(12,2) NOT NULL DEFAULT 0,
+     ADD COLUMN manual_engine_2_gpc_ng_n1 DECIMAL(12,2) NOT NULL DEFAULT 0,
+     ADD COLUMN manual_engine_2_ptc_nf_n2 DECIMAL(12,2) NOT NULL DEFAULT 0,
+     ADD COLUMN manual_landing INT NOT NULL DEFAULT 0,
+     ADD COLUMN manual_flight_report INT NOT NULL DEFAULT 0,
+     ADD COLUMN manual_hook_release INT NOT NULL DEFAULT 0,
+     ADD COLUMN manual_rotor_brake_cycle INT NOT NULL DEFAULT 0',
+  'SELECT 1'
+);
+
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+-- +goose Down
+ALTER TABLE helicopter_usage
+  DROP COLUMN manual_airframe_hours,
+  DROP COLUMN manual_airframe_cycles,
+  DROP COLUMN manual_engine_1_hours,
+  DROP COLUMN manual_engine_1_gpc_ng_n1,
+  DROP COLUMN manual_engine_1_ptc_nf_n2,
+  DROP COLUMN manual_engine_2_hours,
+  DROP COLUMN manual_engine_2_gpc_ng_n1,
+  DROP COLUMN manual_engine_2_ptc_nf_n2,
+  DROP COLUMN manual_landing,
+  DROP COLUMN manual_flight_report,
+  DROP COLUMN manual_hook_release,
+  DROP COLUMN manual_rotor_brake_cycle;
diff --git a/migrations/20260624_complaint_mel_severity_not_null.sql b/migrations/20260624_complaint_mel_severity_not_null.sql
new file mode 100644
index 0000000..6de0526
--- /dev/null
+++ b/migrations/20260624_complaint_mel_severity_not_null.sql
@@ -0,0 +1,8 @@
+-- +goose Up
+-- Classification is now mandatory at creation, so pending (NULL) no longer occurs.
+-- Backfill any legacy unclassified complaints to NON-MEL (0) before making the column NOT NULL.
+UPDATE complaints SET mel_severity = 0 WHERE mel_severity IS NULL;
+ALTER TABLE complaints MODIFY COLUMN mel_severity TINYINT NOT NULL DEFAULT 0;
+
+-- +goose Down
+ALTER TABLE complaints MODIFY COLUMN mel_severity TINYINT NULL;
diff --git a/migrations/20260625_add_flight_position_to_flight_data.sql b/migrations/20260625_add_flight_position_to_flight_data.sql
new file mode 100644
index 0000000..6640937
--- /dev/null
+++ b/migrations/20260625_add_flight_position_to_flight_data.sql
@@ -0,0 +1,33 @@
+-- +goose Up
+SET @has_col := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'flight_data'
+    AND column_name = 'flight_position'
+);
+SET @sql := IF(
+  @has_col = 0,
+  'ALTER TABLE flight_data ADD COLUMN flight_position TINYINT(1) NOT NULL DEFAULT 0 AFTER fuel_planning',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+-- +goose Down
+SET @has_col := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'flight_data'
+    AND column_name = 'flight_position'
+);
+SET @sql := IF(
+  @has_col = 1,
+  'ALTER TABLE flight_data DROP COLUMN flight_position',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
diff --git a/migrations/20260626_add_wopi_lock_fields_to_file_files.sql b/migrations/20260626_add_wopi_lock_fields_to_file_files.sql
new file mode 100644
index 0000000..15fed23
--- /dev/null
+++ b/migrations/20260626_add_wopi_lock_fields_to_file_files.sql
@@ -0,0 +1,5 @@
+ALTER TABLE file_files
+  ADD COLUMN wopi_lock_id VARCHAR(128) NULL AFTER lifecycle_deleted_at,
+  ADD COLUMN wopi_lock_jti VARCHAR(128) NULL AFTER wopi_lock_id,
+  ADD COLUMN wopi_locked_at DATETIME(6) NULL AFTER wopi_lock_jti,
+  ADD COLUMN wopi_lock_expires_at DATETIME(6) NULL AFTER wopi_locked_at;
diff --git a/migrations/20260626_flight_data_pilot_id_nullable.sql b/migrations/20260626_flight_data_pilot_id_nullable.sql
new file mode 100644
index 0000000..c7b481d
--- /dev/null
+++ b/migrations/20260626_flight_data_pilot_id_nullable.sql
@@ -0,0 +1,33 @@
+-- +goose Up
+SET @has_col := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'flight_data'
+    AND column_name = 'pilot_id'
+);
+SET @sql := IF(
+  @has_col = 1,
+  'ALTER TABLE flight_data MODIFY COLUMN pilot_id BINARY(16) NULL',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+-- +goose Down
+SET @has_col := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'flight_data'
+    AND column_name = 'pilot_id'
+);
+SET @sql := IF(
+  @has_col = 1,
+  'ALTER TABLE flight_data MODIFY COLUMN pilot_id BINARY(16) NOT NULL',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
diff --git a/migrations/20260626_flight_data_rename_pilot_id_to_co_pilot_id.sql b/migrations/20260626_flight_data_rename_pilot_id_to_co_pilot_id.sql
new file mode 100644
index 0000000..7cc042f
--- /dev/null
+++ b/migrations/20260626_flight_data_rename_pilot_id_to_co_pilot_id.sql
@@ -0,0 +1,33 @@
+-- +goose Up
+SET @needs_rename := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'flight_data'
+    AND column_name = 'pilot_id'
+);
+SET @sql := IF(
+  @needs_rename = 1,
+  'ALTER TABLE flight_data CHANGE COLUMN pilot_id co_pilot_id BINARY(16) NULL',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+-- +goose Down
+SET @needs_rename := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'flight_data'
+    AND column_name = 'co_pilot_id'
+);
+SET @sql := IF(
+  @needs_rename = 1,
+  'ALTER TABLE flight_data CHANGE COLUMN co_pilot_id pilot_id BINARY(16) NULL',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
diff --git a/migrations/20260626_helicopters_deleted_at_nullable.sql b/migrations/20260626_helicopters_deleted_at_nullable.sql
new file mode 100644
index 0000000..13175d7
--- /dev/null
+++ b/migrations/20260626_helicopters_deleted_at_nullable.sql
@@ -0,0 +1,43 @@
+-- Add deleted_at to helicopters so takeover and usage queries can safely filter active rows.
+
+SET @schema_name := DATABASE();
+SET @has_helicopters := (
+  SELECT COUNT(*)
+  FROM information_schema.TABLES
+  WHERE TABLE_SCHEMA = @schema_name
+    AND TABLE_NAME = 'helicopters'
+);
+
+SET @has_deleted_at := (
+  SELECT COUNT(*)
+  FROM information_schema.COLUMNS
+  WHERE TABLE_SCHEMA = @schema_name
+    AND TABLE_NAME = 'helicopters'
+    AND COLUMN_NAME = 'deleted_at'
+);
+
+SET @sql_add_deleted_at := IF(
+  @has_helicopters > 0 AND @has_deleted_at = 0,
+  'ALTER TABLE helicopters ADD COLUMN deleted_at DATETIME(6) NULL AFTER updated_at',
+  'SELECT 1'
+);
+PREPARE stmt_add_deleted_at FROM @sql_add_deleted_at;
+EXECUTE stmt_add_deleted_at;
+DEALLOCATE PREPARE stmt_add_deleted_at;
+
+SET @idx_deleted_at_exists := (
+  SELECT COUNT(*)
+  FROM information_schema.STATISTICS
+  WHERE TABLE_SCHEMA = @schema_name
+    AND TABLE_NAME = 'helicopters'
+    AND INDEX_NAME = 'idx_helicopters_deleted_at'
+);
+
+SET @sql_add_deleted_at_idx := IF(
+  @has_helicopters > 0 AND @has_deleted_at > 0 AND @idx_deleted_at_exists = 0,
+  'ALTER TABLE helicopters ADD INDEX idx_helicopters_deleted_at (deleted_at)',
+  'SELECT 1'
+);
+PREPARE stmt_add_deleted_at_idx FROM @sql_add_deleted_at_idx;
+EXECUTE stmt_add_deleted_at_idx;
+DEALLOCATE PREPARE stmt_add_deleted_at_idx;
diff --git a/migrations/20260630_add_is_template_to_file_files.sql b/migrations/20260630_add_is_template_to_file_files.sql
new file mode 100644
index 0000000..a7cd86a
--- /dev/null
+++ b/migrations/20260630_add_is_template_to_file_files.sql
@@ -0,0 +1,21 @@
+-- +goose Up
+ALTER TABLE file_files
+  ADD COLUMN is_template TINYINT(1) NOT NULL DEFAULT 0 AFTER checksum_sha256;
+
+UPDATE file_files
+SET is_template = 1
+WHERE EXISTS (
+  SELECT 1
+  FROM helicopter_files hf
+  WHERE hf.source_file_id = file_files.id
+)
+OR EXISTS (
+  SELECT 1
+  FROM helicopter_files hf
+  INNER JOIN attachments a ON a.id = hf.file_attachment_id
+    AND a.file_id = file_files.id
+);
+
+-- +goose Down
+ALTER TABLE file_files
+  DROP COLUMN is_template;
diff --git a/migrations/20260630_backfill_fm_report_codes_to_identifier.sql b/migrations/20260630_backfill_fm_report_codes_to_identifier.sql
new file mode 100644
index 0000000..f01ec1f
--- /dev/null
+++ b/migrations/20260630_backfill_fm_report_codes_to_identifier.sql
@@ -0,0 +1,29 @@
+-- +goose Up
+UPDATE fm_reports fr
+JOIN helicopters h ON h.id = fr.helicopter_id
+SET fr.report_code = CONCAT(
+  UPPER(TRIM(h.identifier)),
+  '-',
+  LPAD(CAST(SUBSTRING_INDEX(fr.report_code, '-', -1) AS UNSIGNED), 4, '0')
+)
+WHERE fr.deleted_at IS NULL
+  AND fr.report_code IS NOT NULL
+  AND fr.report_code <> ''
+  AND h.identifier IS NOT NULL
+  AND TRIM(h.identifier) <> ''
+  AND SUBSTRING_INDEX(fr.report_code, '-', -1) REGEXP '^[0-9]+$'; 
+
+-- +goose Down
+UPDATE fm_reports fr
+JOIN helicopters h ON h.id = fr.helicopter_id
+SET fr.report_code = CONCAT(
+  UPPER(TRIM(h.type)),
+  '-',
+  LPAD(CAST(SUBSTRING_INDEX(fr.report_code, '-', -1) AS UNSIGNED), 4, '0')
+)
+WHERE fr.deleted_at IS NULL
+  AND fr.report_code IS NOT NULL
+  AND fr.report_code <> ''
+  AND h.type IS NOT NULL
+  AND TRIM(h.type) <> ''
+  AND SUBSTRING_INDEX(fr.report_code, '-', -1) REGEXP '^[0-9]+$';
diff --git a/migrations/20260701_add_flight_id_to_mcf.sql b/migrations/20260701_add_flight_id_to_mcf.sql
new file mode 100644
index 0000000..2e765f3
--- /dev/null
+++ b/migrations/20260701_add_flight_id_to_mcf.sql
@@ -0,0 +1,13 @@
+-- +goose Up
+-- +goose StatementBegin
+ALTER TABLE maintenance_check_flights
+  ADD COLUMN flight_id BINARY(16) NULL AFTER helicopter_id,
+  ADD KEY idx_maintenance_check_flights_flight_id (flight_id);
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+ALTER TABLE maintenance_check_flights
+  DROP KEY idx_maintenance_check_flights_flight_id,
+  DROP COLUMN flight_id;
+-- +goose StatementEnd
diff --git a/migrations/20260701_add_mcf_to_fm_report_fleet_history.sql b/migrations/20260701_add_mcf_to_fm_report_fleet_history.sql
new file mode 100644
index 0000000..ac6dcd1
--- /dev/null
+++ b/migrations/20260701_add_mcf_to_fm_report_fleet_history.sql
@@ -0,0 +1,25 @@
+-- +goose Up
+-- +goose StatementBegin
+-- FM report snapshot captures the helicopter's MCF (kept as "MCF signed" history even
+-- after the live fleet page resets its MCF display).
+ALTER TABLE fm_report_fleet_history
+  ADD COLUMN mcf_id BINARY(16) NULL AFTER easa_signed_by,
+  ADD COLUMN mcf_is_signed TINYINT(1) NOT NULL DEFAULT 0 AFTER mcf_id,
+  ADD COLUMN mcf_date DATE NULL AFTER mcf_is_signed,
+  ADD COLUMN mcf_af_hours VARCHAR(20) NULL AFTER mcf_date,
+  ADD COLUMN mcf_landing_count INT NULL AFTER mcf_af_hours,
+  ADD COLUMN mcf_signed_by BINARY(16) NULL AFTER mcf_landing_count,
+  ADD COLUMN mcf_signed_by_name VARCHAR(255) NULL AFTER mcf_signed_by;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+ALTER TABLE fm_report_fleet_history
+  DROP COLUMN mcf_id,
+  DROP COLUMN mcf_is_signed,
+  DROP COLUMN mcf_date,
+  DROP COLUMN mcf_af_hours,
+  DROP COLUMN mcf_landing_count,
+  DROP COLUMN mcf_signed_by,
+  DROP COLUMN mcf_signed_by_name;
+-- +goose StatementEnd
diff --git a/migrations/20260701_drop_complaint_action_signed_and_signoff_audit_columns.sql b/migrations/20260701_drop_complaint_action_signed_and_signoff_audit_columns.sql
new file mode 100644
index 0000000..fe94ed2
--- /dev/null
+++ b/migrations/20260701_drop_complaint_action_signed_and_signoff_audit_columns.sql
@@ -0,0 +1,30 @@
+-- +goose Up
+-- +goose StatementBegin
+-- The corrective-action sign moved from the complaint to the action_signoffs table,
+-- and action_signoffs became a pure sign record (no action text / audit / soft-delete).
+ALTER TABLE complaints
+  DROP COLUMN action_signed_at,
+  DROP COLUMN action_signed_by;
+
+ALTER TABLE action_signoffs
+  DROP COLUMN action_taken,
+  DROP COLUMN created_by,
+  DROP COLUMN updated_by,
+  DROP COLUMN deleted_at,
+  DROP COLUMN deleted_by;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+ALTER TABLE complaints
+  ADD COLUMN action_signed_at DATETIME(3) NULL AFTER action_taken,
+  ADD COLUMN action_signed_by BINARY(16) NULL AFTER action_signed_at;
+
+ALTER TABLE action_signoffs
+  ADD COLUMN action_taken TEXT NULL AFTER complaint_id,
+  ADD COLUMN created_by BINARY(16) NULL AFTER created_at,
+  ADD COLUMN updated_by BINARY(16) NULL AFTER updated_at,
+  ADD COLUMN deleted_at DATETIME(3) NULL,
+  ADD COLUMN deleted_by BINARY(16) NULL,
+  ADD KEY idx_action_signoffs_deleted_at (deleted_at);
+-- +goose StatementEnd
diff --git a/migrations/20260701_drop_easa_maintenance_program.sql b/migrations/20260701_drop_easa_maintenance_program.sql
new file mode 100644
index 0000000..146cabb
--- /dev/null
+++ b/migrations/20260701_drop_easa_maintenance_program.sql
@@ -0,0 +1,18 @@
+-- +goose Up
+-- +goose StatementBegin
+-- The EASA maintenance program field was removed from the release and its FM-report snapshot.
+ALTER TABLE easa_releases
+  DROP COLUMN easa_maintenance_program;
+
+ALTER TABLE fm_report_fleet_history
+  DROP COLUMN easa_maintenance_program;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+ALTER TABLE easa_releases
+  ADD COLUMN easa_maintenance_program VARCHAR(255) NULL AFTER helicopter_id;
+
+ALTER TABLE fm_report_fleet_history
+  ADD COLUMN easa_maintenance_program VARCHAR(255) NULL AFTER easa_is_signed;
+-- +goose StatementEnd
diff --git a/migrations/20260701_mcf_cancelled.sql b/migrations/20260701_mcf_cancelled.sql
new file mode 100644
index 0000000..f3ad2ed
--- /dev/null
+++ b/migrations/20260701_mcf_cancelled.sql
@@ -0,0 +1,15 @@
+-- +goose Up
+-- +goose StatementBegin
+-- MCF: support "set No" cancellation — a draft that was never signed ("tidak jadi").
+-- flight_id is added separately by 20260701_add_flight_id_to_mcf.sql.
+ALTER TABLE maintenance_check_flights
+  ADD COLUMN cancelled_at DATETIME(3) NULL AFTER completed_by,
+  ADD COLUMN cancelled_by BINARY(16) NULL AFTER cancelled_at;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+ALTER TABLE maintenance_check_flights
+  DROP COLUMN cancelled_at,
+  DROP COLUMN cancelled_by;
+-- +goose StatementEnd
diff --git a/migrations/20260702_drop_medical_license_and_chief_physician_in_charge.sql b/migrations/20260702_drop_medical_license_and_chief_physician_in_charge.sql
new file mode 100644
index 0000000..b059310
--- /dev/null
+++ b/migrations/20260702_drop_medical_license_and_chief_physician_in_charge.sql
@@ -0,0 +1,9 @@
+-- +goose Up
+ALTER TABLE doctor_profiles DROP INDEX idx_doctor_profiles_medical_license;
+ALTER TABLE doctor_profiles DROP COLUMN medical_license_no;
+ALTER TABLE air_rescuer_profiles DROP COLUMN is_chief_physician_in_charge;
+
+-- +goose Down
+ALTER TABLE doctor_profiles ADD COLUMN medical_license_no VARCHAR(120) NULL AFTER short_name;
+ALTER TABLE doctor_profiles ADD INDEX idx_doctor_profiles_medical_license (medical_license_no);
+ALTER TABLE air_rescuer_profiles ADD COLUMN is_chief_physician_in_charge TINYINT(1) NOT NULL DEFAULT 0 AFTER short_name;
diff --git a/migrations/20260703_add_microsoft_session_id_to_ms_oauth.sql b/migrations/20260703_add_microsoft_session_id_to_ms_oauth.sql
new file mode 100644
index 0000000..bcd271f
--- /dev/null
+++ b/migrations/20260703_add_microsoft_session_id_to_ms_oauth.sql
@@ -0,0 +1,19 @@
+-- Add Microsoft Entra sid so front-channel logout can map the IdP session to the app session.
+SET @exists := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'user_microsoft_oauth_tokens'
+    AND column_name = 'microsoft_session_id'
+);
+
+SET @sql := IF(
+  @exists = 0,
+  'ALTER TABLE user_microsoft_oauth_tokens ADD COLUMN microsoft_session_id VARCHAR(191) NULL AFTER microsoft_subject',
+  'SELECT 1'
+);
+
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
diff --git a/migrations/20260703_add_refresh_token_expires_at_to_ms_oauth.sql b/migrations/20260703_add_refresh_token_expires_at_to_ms_oauth.sql
new file mode 100644
index 0000000..ef1ccf9
--- /dev/null
+++ b/migrations/20260703_add_refresh_token_expires_at_to_ms_oauth.sql
@@ -0,0 +1,33 @@
+-- +goose Up
+SET @has_col := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'user_microsoft_oauth_tokens'
+    AND column_name = 'refresh_token_expires_at'
+);
+SET @sql := IF(
+  @has_col = 0,
+  'ALTER TABLE user_microsoft_oauth_tokens ADD COLUMN refresh_token_expires_at DATETIME(3) NULL AFTER access_token_expires_at',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+-- +goose Down
+SET @has_col := (
+  SELECT COUNT(*)
+  FROM information_schema.columns
+  WHERE table_schema = DATABASE()
+    AND table_name = 'user_microsoft_oauth_tokens'
+    AND column_name = 'refresh_token_expires_at'
+);
+SET @sql := IF(
+  @has_col = 1,
+  'ALTER TABLE user_microsoft_oauth_tokens DROP COLUMN refresh_token_expires_at',
+  'SELECT 1'
+);
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
diff --git a/migrations/20260703_medicines_rename_dose_to_pack_drop_via.sql b/migrations/20260703_medicines_rename_dose_to_pack_drop_via.sql
new file mode 100644
index 0000000..be7d414
--- /dev/null
+++ b/migrations/20260703_medicines_rename_dose_to_pack_drop_via.sql
@@ -0,0 +1,7 @@
+-- +goose Up
+ALTER TABLE medicines RENAME COLUMN dose TO pack;
+ALTER TABLE medicines DROP COLUMN via;
+
+-- +goose Down
+ALTER TABLE medicines ADD COLUMN via VARCHAR(50) NOT NULL DEFAULT '' AFTER unit;
+ALTER TABLE medicines RENAME COLUMN pack TO dose;
diff --git a/migrations/20260703_rename_base_contact_roles.sql b/migrations/20260703_rename_base_contact_roles.sql
new file mode 100644
index 0000000..504487c
--- /dev/null
+++ b/migrations/20260703_rename_base_contact_roles.sql
@@ -0,0 +1,15 @@
+-- +goose Up
+UPDATE base_contact_roles SET role_code = 'hems_edc' WHERE role_code = 'responsible_flight_rescuer';
+UPDATE base_contact_roles SET role_code = 'med_pax' WHERE role_code = 'chief_physician_in_charge';
+
+ALTER TABLE base_contact_roles ADD CONSTRAINT chk_base_contact_roles_role_code
+  CHECK (role_code IN ('hems_edc', 'med_pax', 'responsible_pilot', 'dul'));
+
+-- +goose Down
+ALTER TABLE base_contact_roles DROP CHECK chk_base_contact_roles_role_code;
+
+UPDATE base_contact_roles SET role_code = 'responsible_flight_rescuer' WHERE role_code = 'hems_edc';
+UPDATE base_contact_roles SET role_code = 'chief_physician_in_charge' WHERE role_code = 'med_pax';
+
+ALTER TABLE base_contact_roles ADD CONSTRAINT chk_base_contact_roles_role_code
+  CHECK (role_code IN ('responsible_flight_rescuer', 'chief_physician_in_charge', 'responsible_pilot', 'dul'));
diff --git a/migrations/20260706_file_preview_metadata.sql b/migrations/20260706_file_preview_metadata.sql
new file mode 100644
index 0000000..9c275b1
--- /dev/null
+++ b/migrations/20260706_file_preview_metadata.sql
@@ -0,0 +1,8 @@
+ALTER TABLE file_files
+  ADD COLUMN preview_mime_type VARCHAR(255) NULL AFTER thumbnail_etag,
+  ADD COLUMN preview_size_bytes BIGINT UNSIGNED NULL AFTER preview_mime_type,
+  ADD COLUMN preview_bucket VARCHAR(128) NULL AFTER preview_size_bytes,
+  ADD COLUMN preview_object_key VARCHAR(512) NULL AFTER preview_bucket,
+  ADD COLUMN preview_object_version VARCHAR(128) NULL AFTER preview_object_key,
+  ADD COLUMN preview_etag VARCHAR(128) NULL AFTER preview_object_version,
+  ADD UNIQUE KEY uq_file_files_preview_object_key (preview_object_key);
diff --git a/migrations/20260707_drop_doctor_license_dates.sql b/migrations/20260707_drop_doctor_license_dates.sql
new file mode 100644
index 0000000..cbac999
--- /dev/null
+++ b/migrations/20260707_drop_doctor_license_dates.sql
@@ -0,0 +1,7 @@
+-- +goose Up
+ALTER TABLE doctor_profiles DROP COLUMN license_issued_at;
+ALTER TABLE doctor_profiles DROP COLUMN license_expired_at;
+
+-- +goose Down
+ALTER TABLE doctor_profiles ADD COLUMN license_issued_at DATETIME NULL AFTER short_name;
+ALTER TABLE doctor_profiles ADD COLUMN license_expired_at DATETIME NULL AFTER license_issued_at;
diff --git a/migrations/20260707_helicopter_usage_totals_to_decimal.sql b/migrations/20260707_helicopter_usage_totals_to_decimal.sql
new file mode 100644
index 0000000..942628d
--- /dev/null
+++ b/migrations/20260707_helicopter_usage_totals_to_decimal.sql
@@ -0,0 +1,36 @@
+-- +goose Up
+-- +goose StatementBegin
+-- Counts (landings, cycles, ccc, flight reports, hook releases, rotor brake cycles) were
+-- INT; widen the helicopter_usage totals + manual adjustments to DECIMAL(12,2) so manual
+-- summary edits can carry up to 2 decimals, matching the hours/gpc/ptc columns.
+ALTER TABLE helicopter_usage
+  MODIFY COLUMN total_landing            DECIMAL(12,2) NOT NULL DEFAULT 0,
+  MODIFY COLUMN total_airframe_cycles    DECIMAL(12,2) NOT NULL DEFAULT 0,
+  MODIFY COLUMN total_engine_1_ccc       DECIMAL(12,2) NOT NULL DEFAULT 0,
+  MODIFY COLUMN total_engine_2_ccc       DECIMAL(12,2) NOT NULL DEFAULT 0,
+  MODIFY COLUMN total_flight_report      DECIMAL(12,2) NOT NULL DEFAULT 0,
+  MODIFY COLUMN total_hook_release       DECIMAL(12,2) NOT NULL DEFAULT 0,
+  MODIFY COLUMN total_rotor_brake_cycle  DECIMAL(12,2) NOT NULL DEFAULT 0,
+  MODIFY COLUMN manual_airframe_cycles   DECIMAL(12,2) NOT NULL DEFAULT 0,
+  MODIFY COLUMN manual_landing           DECIMAL(12,2) NOT NULL DEFAULT 0,
+  MODIFY COLUMN manual_flight_report     DECIMAL(12,2) NOT NULL DEFAULT 0,
+  MODIFY COLUMN manual_hook_release      DECIMAL(12,2) NOT NULL DEFAULT 0,
+  MODIFY COLUMN manual_rotor_brake_cycle DECIMAL(12,2) NOT NULL DEFAULT 0;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+ALTER TABLE helicopter_usage
+  MODIFY COLUMN total_landing            INT NOT NULL DEFAULT 0,
+  MODIFY COLUMN total_airframe_cycles    INT NOT NULL DEFAULT 0,
+  MODIFY COLUMN total_engine_1_ccc       INT NOT NULL DEFAULT 0,
+  MODIFY COLUMN total_engine_2_ccc       INT NOT NULL DEFAULT 0,
+  MODIFY COLUMN total_flight_report      INT NOT NULL DEFAULT 0,
+  MODIFY COLUMN total_hook_release       INT NOT NULL DEFAULT 0,
+  MODIFY COLUMN total_rotor_brake_cycle  INT NOT NULL DEFAULT 0,
+  MODIFY COLUMN manual_airframe_cycles   INT NOT NULL DEFAULT 0,
+  MODIFY COLUMN manual_landing           INT NOT NULL DEFAULT 0,
+  MODIFY COLUMN manual_flight_report     INT NOT NULL DEFAULT 0,
+  MODIFY COLUMN manual_hook_release      INT NOT NULL DEFAULT 0,
+  MODIFY COLUMN manual_rotor_brake_cycle INT NOT NULL DEFAULT 0;
+-- +goose StatementEnd
diff --git a/migrations/20260707_other_people_master.sql b/migrations/20260707_other_people_master.sql
new file mode 100644
index 0000000..8e4666a
--- /dev/null
+++ b/migrations/20260707_other_people_master.sql
@@ -0,0 +1,34 @@
+-- +goose Up
+-- +goose StatementBegin
+-- Reusable, NON-STAFF person master (distinct from contacts). Lets an "other person" be
+-- reused across takeovers without re-entering their data.
+CREATE TABLE IF NOT EXISTS other_people (
+  id            BINARY(16)   NOT NULL,
+  name          VARCHAR(191) NOT NULL DEFAULT '',
+  mobile_phone  VARCHAR(64)  NOT NULL DEFAULT '',
+  email         VARCHAR(191) NOT NULL DEFAULT '',
+  created_at    DATETIME(3)  NULL,
+  created_by    BINARY(16)   NULL,
+  updated_at    DATETIME(3)  NULL,
+  updated_by    BINARY(16)   NULL,
+  deleted_at    DATETIME(3)  NULL,
+  deleted_by    BINARY(16)   NULL,
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_other_people_identity (name, mobile_phone, email),
+  KEY idx_other_people_deleted_at (deleted_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- takeover_other_people becomes a pivot + snapshot: reference the master, keep the snapshot.
+ALTER TABLE takeover_other_people
+  ADD COLUMN other_person_id BINARY(16) NULL AFTER takeover_id,
+  ADD KEY idx_takeover_other_people_other_person_id (other_person_id);
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+ALTER TABLE takeover_other_people
+  DROP KEY idx_takeover_other_people_other_person_id,
+  DROP COLUMN other_person_id;
+
+DROP TABLE IF EXISTS other_people;
+-- +goose StatementEnd
diff --git a/migrations/goose/20260414_helicopter_import_staging.sql b/migrations/goose/20260414_helicopter_import_staging.sql
new file mode 100644
index 0000000..0a2c62b
--- /dev/null
+++ b/migrations/goose/20260414_helicopter_import_staging.sql
@@ -0,0 +1,37 @@
+-- +goose Up
+-- Prepare staging tables for legacy helicopter dump import.
+
+CREATE TABLE IF NOT EXISTS helicopter_old_import (
+  id int(11) NOT NULL,
+  name varchar(50) NOT NULL,
+  type varchar(20) DEFAULT NULL,
+  counter int(11) DEFAULT NULL,
+  engine1 varchar(50) DEFAULT NULL,
+  engine2 varchar(50) DEFAULT NULL,
+  consumption double(10,2) DEFAULT NULL,
+  service varchar(255) DEFAULT NULL,
+  nr1 tinyint(1) DEFAULT 0,
+  nr2 tinyint(1) DEFAULT 0,
+  lh tinyint(1) DEFAULT 0,
+  rh tinyint(1) DEFAULT 0,
+  mgb tinyint(1) DEFAULT 0,
+  igb tinyint(1) DEFAULT 0,
+  tgb tinyint(1) DEFAULT 0,
+  utc varchar(10) DEFAULT NULL,
+  disabled tinyint(1) DEFAULT 0,
+  visible tinyint(1) DEFAULT 1,
+  dry tinyint(1) DEFAULT 0,
+  docs text,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS helicopter_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_helicopter_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS helicopter_old_id_map;
+DROP TABLE IF EXISTS helicopter_old_import;
diff --git a/migrations/goose/20260415_helicopter_import_apply.sql b/migrations/goose/20260415_helicopter_import_apply.sql
new file mode 100644
index 0000000..2d8c2cc
--- /dev/null
+++ b/migrations/goose/20260415_helicopter_import_apply.sql
@@ -0,0 +1,140 @@
+-- +goose Up
+-- Apply legacy helicopter staging data into `helicopters`.
+-- Expected flow before this migration:
+-- 1) Run previous migration that creates `helicopter_old_import`.
+-- 2) Import old dump rows into `helicopter_old_import`.
+-- This migration maps old integer IDs into BINARY(16) UUIDv7-style IDs,
+-- then upserts into `helicopters` with `is_active` forced to 1.
+
+START TRANSACTION;
+
+-- Self-heal when staging migration is marked applied but tables were dropped/reset manually.
+CREATE TABLE IF NOT EXISTS helicopter_old_import (
+  id int(11) NOT NULL,
+  name varchar(50) NOT NULL,
+  type varchar(20) DEFAULT NULL,
+  counter int(11) DEFAULT NULL,
+  engine1 varchar(50) DEFAULT NULL,
+  engine2 varchar(50) DEFAULT NULL,
+  consumption double(10,2) DEFAULT NULL,
+  service varchar(255) DEFAULT NULL,
+  nr1 tinyint(1) DEFAULT 0,
+  nr2 tinyint(1) DEFAULT 0,
+  lh tinyint(1) DEFAULT 0,
+  rh tinyint(1) DEFAULT 0,
+  mgb tinyint(1) DEFAULT 0,
+  igb tinyint(1) DEFAULT 0,
+  tgb tinyint(1) DEFAULT 0,
+  utc varchar(10) DEFAULT NULL,
+  disabled tinyint(1) DEFAULT 0,
+  visible tinyint(1) DEFAULT 1,
+  dry tinyint(1) DEFAULT 0,
+  docs text,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS helicopter_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_helicopter_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+INSERT INTO helicopter_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      -- UUID layout must be 8-4-4-4-12 (32 hex chars => 16 bytes).
+      -- Put millisecond timestamp (48-bit) in first 8+4 chars for time ordering.
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM helicopter_old_import s
+LEFT JOIN helicopter_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO helicopters (
+  id,
+  designation,
+  identifier,
+  report_sequence,
+  type,
+  counter,
+  engine_1,
+  engine_2,
+  consumption_lt_min,
+  nr1,
+  nr2,
+  lh,
+  rh,
+  mgb,
+  igb,
+  tgb,
+  utc_offset,
+  dry,
+  note,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id,
+  TRIM(s.name) AS designation,
+  TRIM(s.name) AS identifier,
+  0 AS report_sequence,
+  COALESCE(NULLIF(TRIM(s.type), ''), 'Unknown') AS type,
+  0 AS counter,
+  TRIM(COALESCE(s.engine1, '')) AS engine_1,
+  TRIM(COALESCE(s.engine2, '')) AS engine_2,
+  COALESCE(s.consumption, 0) AS consumption_lt_min,
+  COALESCE(s.nr1, 0) AS nr1,
+  COALESCE(s.nr2, 0) AS nr2,
+  COALESCE(s.lh, 0) AS lh,
+  COALESCE(s.rh, 0) AS rh,
+  COALESCE(s.mgb, 0) AS mgb,
+  COALESCE(s.igb, 0) AS igb,
+  COALESCE(s.tgb, 0) AS tgb,
+  COALESCE(CAST(NULLIF(TRIM(s.utc), '') AS SIGNED), 0) AS utc_offset,
+  COALESCE(s.dry, 0) AS dry,
+  s.docs AS note,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM helicopter_old_import s
+JOIN helicopter_old_id_map m ON m.old_id = s.id
+ON DUPLICATE KEY UPDATE
+  designation = VALUES(designation),
+  identifier = VALUES(identifier),
+  type = VALUES(type),
+  engine_1 = VALUES(engine_1),
+  engine_2 = VALUES(engine_2),
+  consumption_lt_min = VALUES(consumption_lt_min),
+  nr1 = VALUES(nr1),
+  nr2 = VALUES(nr2),
+  lh = VALUES(lh),
+  rh = VALUES(rh),
+  mgb = VALUES(mgb),
+  igb = VALUES(igb),
+  tgb = VALUES(tgb),
+  utc_offset = VALUES(utc_offset),
+  dry = VALUES(dry),
+  note = VALUES(note),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+COMMIT;
+
+-- +goose Down
+-- Data migration is intentionally non-reversible.
+-- Keep imported data and ID mapping as audit trail.
+SELECT 1;
diff --git a/migrations/goose/20260505_seed_lands_from_legacy_country.sql b/migrations/goose/20260505_seed_lands_from_legacy_country.sql
new file mode 100644
index 0000000..5e7a789
--- /dev/null
+++ b/migrations/goose/20260505_seed_lands_from_legacy_country.sql
@@ -0,0 +1,265 @@
+-- +goose Up
+INSERT INTO lands (id, name, land_iso_code, sortkey, is_active, created_at, updated_at)
+SELECT UUID_TO_BIN(UUID()), src.name, src.iso_code, src.sortkey, 1, NOW(3), NOW(3)
+FROM (
+  SELECT 'AC' AS iso_code, 'Ascension' AS name, 1 AS sortkey
+  UNION ALL SELECT 'AD', 'Andorra', 2
+  UNION ALL SELECT 'AE', 'Vereinigte Arabische Emirate', 3
+  UNION ALL SELECT 'AF', 'Afghanistan', 4
+  UNION ALL SELECT 'AG', 'Antigua und Barbuda', 5
+  UNION ALL SELECT 'AI', 'Anguilla', 6
+  UNION ALL SELECT 'AL', 'Albanien', 7
+  UNION ALL SELECT 'AM', 'Armenien', 8
+  UNION ALL SELECT 'AN', 'Niederländische Antillen', 9
+  UNION ALL SELECT 'AO', 'Angola', 10
+  UNION ALL SELECT 'AQ', 'Antarktis', 11
+  UNION ALL SELECT 'AR', 'Argentinien', 12
+  UNION ALL SELECT 'AS', 'Amerikanisch Samoa', 13
+  UNION ALL SELECT 'AT', 'Österreich', 14
+  UNION ALL SELECT 'AU', 'Australien', 15
+  UNION ALL SELECT 'AW', 'Aruba', 16
+  UNION ALL SELECT 'AX', 'Aland', 17
+  UNION ALL SELECT 'AZ', 'Aserbaidschan', 18
+  UNION ALL SELECT 'BA', 'Bosnien-Herzegowina', 19
+  UNION ALL SELECT 'BB', 'Barbados', 20
+  UNION ALL SELECT 'BD', 'Bangladesch', 21
+  UNION ALL SELECT 'BE', 'Belgien', 22
+  UNION ALL SELECT 'BF', 'Burkina Faso', 23
+  UNION ALL SELECT 'BG', 'Bulgarien', 24
+  UNION ALL SELECT 'BH', 'Bahrain', 25
+  UNION ALL SELECT 'BJ', 'Benin', 26
+  UNION ALL SELECT 'BL', 'Burundi', 27
+  UNION ALL SELECT 'BM', 'Bermuda', 28
+  UNION ALL SELECT 'BN', 'Brunei Darussalam', 29
+  UNION ALL SELECT 'BO', 'Bolivien', 30
+  UNION ALL SELECT 'BR', 'Brasilien', 31
+  UNION ALL SELECT 'BS', 'Bahamas', 32
+  UNION ALL SELECT 'BT', 'Bhutan', 33
+  UNION ALL SELECT 'BV', 'Bouvetinseln', 34
+  UNION ALL SELECT 'BW', 'Botsuana', 35
+  UNION ALL SELECT 'BY', 'Belarus', 36
+  UNION ALL SELECT 'BZ', 'Belize ', 37
+  UNION ALL SELECT 'CA', 'Kanada', 38
+  UNION ALL SELECT 'CC', 'Kokosinseln', 39
+  UNION ALL SELECT 'CD', 'Demokratische Republik Kongo', 40
+  UNION ALL SELECT 'CF', 'Zentralafrikanische Republik', 41
+  UNION ALL SELECT 'CG', 'Kongo', 42
+  UNION ALL SELECT 'CH', 'Schweiz', 43
+  UNION ALL SELECT 'CI', 'Elfenbeinküste', 44
+  UNION ALL SELECT 'CK', 'Cookinseln', 45
+  UNION ALL SELECT 'CL', 'Chile', 46
+  UNION ALL SELECT 'CM', 'Kamerun', 47
+  UNION ALL SELECT 'CO', 'Kolumbien', 48
+  UNION ALL SELECT 'CR', 'Costa Rica', 49
+  UNION ALL SELECT 'CU', 'Kuba', 50
+  UNION ALL SELECT 'CV', 'Kap Verde', 51
+  UNION ALL SELECT 'CX', 'Weihnachtsinsel', 52
+  UNION ALL SELECT 'CY', 'Zypern', 53
+  UNION ALL SELECT 'CZ', 'Tschechische Republik', 54
+  UNION ALL SELECT 'DB', 'Dubai', 55
+  UNION ALL SELECT 'DE', 'Deutschland', 56
+  UNION ALL SELECT 'DJ', 'Dschibuti', 57
+  UNION ALL SELECT 'DK', 'Dänemark', 58
+  UNION ALL SELECT 'DM', 'Dominica', 59
+  UNION ALL SELECT 'DO', 'Dominikanische Republik', 60
+  UNION ALL SELECT 'DZ', 'Algerien', 61
+  UNION ALL SELECT 'EC', 'Ecuador', 62
+  UNION ALL SELECT 'EE', 'Estland', 63
+  UNION ALL SELECT 'EG', 'Ägypten', 64
+  UNION ALL SELECT 'EH', 'Western Sahara', 65
+  UNION ALL SELECT 'ER', 'Eritrea', 66
+  UNION ALL SELECT 'ES', 'Spanien', 67
+  UNION ALL SELECT 'ET', 'Äthiopien', 68
+  UNION ALL SELECT 'FI', 'Finnland', 69
+  UNION ALL SELECT 'FJ', 'Fidschi', 70
+  UNION ALL SELECT 'FK', 'Falklandinseln', 71
+  UNION ALL SELECT 'FM', 'Mikronesien', 72
+  UNION ALL SELECT 'FO', 'Färöer', 73
+  UNION ALL SELECT 'FR', 'Frankreich', 74
+  UNION ALL SELECT 'GA', 'Gabun', 75
+  UNION ALL SELECT 'GB', 'Vereinigtes Königreich', 76
+  UNION ALL SELECT 'GD', 'Grenada', 77
+  UNION ALL SELECT 'GE', 'Georgien', 78
+  UNION ALL SELECT 'GF', 'Französische Guyana', 79
+  UNION ALL SELECT 'GG', 'Guernsey', 80
+  UNION ALL SELECT 'GH', 'Ghana', 81
+  UNION ALL SELECT 'GI', 'Gibraltar', 82
+  UNION ALL SELECT 'GL', 'Grönland', 83
+  UNION ALL SELECT 'GM', 'Gambia', 84
+  UNION ALL SELECT 'GN', 'Guinea', 85
+  UNION ALL SELECT 'GP', 'Guadeloupe', 86
+  UNION ALL SELECT 'GQ', 'Äquatorialguinea', 87
+  UNION ALL SELECT 'GR', 'Griechenland', 88
+  UNION ALL SELECT 'GS', 'South Georgia and the South Sandwich Islands', 89
+  UNION ALL SELECT 'GT', 'Guatemala', 90
+  UNION ALL SELECT 'GU', 'Guam', 91
+  UNION ALL SELECT 'GW', 'Guinea-Bissau', 92
+  UNION ALL SELECT 'GY', 'Guyana', 93
+  UNION ALL SELECT 'HK', 'Hong Kong', 94
+  UNION ALL SELECT 'HM', 'Heard Island and McDonald Islands', 95
+  UNION ALL SELECT 'HN', 'Honduras', 96
+  UNION ALL SELECT 'HR', 'Kroatien', 97
+  UNION ALL SELECT 'HT', 'Haiti', 98
+  UNION ALL SELECT 'HU', 'Ungarn', 99
+  UNION ALL SELECT 'ID', 'Indonesien', 100
+  UNION ALL SELECT 'IE', 'Irland', 101
+  UNION ALL SELECT 'IL', 'Israel', 102
+  UNION ALL SELECT 'IM', 'Isle of Man', 103
+  UNION ALL SELECT 'IN', 'Indien', 104
+  UNION ALL SELECT 'IO', 'Br.Territ./Ind.Ozean', 105
+  UNION ALL SELECT 'IQ', 'Irak', 106
+  UNION ALL SELECT 'IR', 'Iran', 107
+  UNION ALL SELECT 'IS', 'Island', 108
+  UNION ALL SELECT 'IT', 'Italien', 109
+  UNION ALL SELECT 'JE', 'Jersey', 110
+  UNION ALL SELECT 'JM', 'Jamaika', 111
+  UNION ALL SELECT 'JO', 'Jordanien', 112
+  UNION ALL SELECT 'JP', 'Japan', 113
+  UNION ALL SELECT 'KE', 'Kenien', 114
+  UNION ALL SELECT 'KG', 'Kirgisistan', 115
+  UNION ALL SELECT 'KH', 'Kambodscha', 116
+  UNION ALL SELECT 'KI', 'Kiribati', 117
+  UNION ALL SELECT 'KM', 'Komoren', 118
+  UNION ALL SELECT 'KN', 'St. Kittis und Nevis', 119
+  UNION ALL SELECT 'KO', 'Kosovo', 120
+  UNION ALL SELECT 'KP', 'Korea, Demo. VR', 121
+  UNION ALL SELECT 'KR', 'Korea', 122
+  UNION ALL SELECT 'KW', 'Kuwait', 123
+  UNION ALL SELECT 'KY', 'Kaimaninseln', 124
+  UNION ALL SELECT 'KZ', 'Kasachstan', 125
+  UNION ALL SELECT 'LA', 'Laos', 126
+  UNION ALL SELECT 'LB', 'Libanon', 127
+  UNION ALL SELECT 'LC', 'Sankt Lucia', 128
+  UNION ALL SELECT 'LI', 'Liechtenstein', 129
+  UNION ALL SELECT 'LK', 'Sri Lanka', 130
+  UNION ALL SELECT 'LR', 'Liberia', 131
+  UNION ALL SELECT 'LS', 'Lesotho', 132
+  UNION ALL SELECT 'LT', 'Litauen', 133
+  UNION ALL SELECT 'LU', 'Luxemburg', 134
+  UNION ALL SELECT 'LV', 'Lettland', 135
+  UNION ALL SELECT 'LY', 'Lybien', 136
+  UNION ALL SELECT 'MA', 'Marokko', 137
+  UNION ALL SELECT 'MC', 'Monaco', 138
+  UNION ALL SELECT 'MD', 'Moldova', 139
+  UNION ALL SELECT 'ME', 'Montenegro', 140
+  UNION ALL SELECT 'MG', 'Madagaskar', 141
+  UNION ALL SELECT 'MH', 'Marshallinseln', 142
+  UNION ALL SELECT 'MK', 'Mazedonien', 143
+  UNION ALL SELECT 'ML', 'Mali', 144
+  UNION ALL SELECT 'MM', 'Myanmar', 145
+  UNION ALL SELECT 'MN', 'Mongolei', 146
+  UNION ALL SELECT 'MO', 'Macau', 147
+  UNION ALL SELECT 'MP', 'Marianen', 148
+  UNION ALL SELECT 'MQ', 'Martinique', 149
+  UNION ALL SELECT 'MR', 'Mauretanien', 150
+  UNION ALL SELECT 'MS', 'Montserrat', 151
+  UNION ALL SELECT 'MT', 'Malta', 152
+  UNION ALL SELECT 'MU', 'Mauritius', 153
+  UNION ALL SELECT 'MV', 'Malediven', 154
+  UNION ALL SELECT 'MW', 'Malawi', 155
+  UNION ALL SELECT 'MX', 'Mexiko', 156
+  UNION ALL SELECT 'MY', 'Malaysia', 157
+  UNION ALL SELECT 'MZ', 'Mosambik', 158
+  UNION ALL SELECT 'NA', 'Namibia', 159
+  UNION ALL SELECT 'NC', 'Neukaledonien', 160
+  UNION ALL SELECT 'NE', 'Niger', 161
+  UNION ALL SELECT 'NF', 'Norfolkins', 162
+  UNION ALL SELECT 'NG', 'Nigeria', 163
+  UNION ALL SELECT 'NI', 'Nicaragua', 164
+  UNION ALL SELECT 'NL', 'Niederlande', 165
+  UNION ALL SELECT 'NO', 'Norwegen', 166
+  UNION ALL SELECT 'NP', 'Nepal', 167
+  UNION ALL SELECT 'NR', 'Nauru', 168
+  UNION ALL SELECT 'NU', 'Niue', 169
+  UNION ALL SELECT 'NZ', 'Neuseeland', 170
+  UNION ALL SELECT 'O', 'unbekannt', 171
+  UNION ALL SELECT 'OM', 'Oman', 172
+  UNION ALL SELECT 'PA', 'Panama', 173
+  UNION ALL SELECT 'PE', 'Peru', 174
+  UNION ALL SELECT 'PF', 'Französchisch Polynesien', 175
+  UNION ALL SELECT 'PG', 'Papua Neuguinea', 176
+  UNION ALL SELECT 'PH', 'Philippinen', 177
+  UNION ALL SELECT 'PK', 'Pakistan', 178
+  UNION ALL SELECT 'PL', 'Polen', 179
+  UNION ALL SELECT 'PM', 'St Pierre und Miquelon', 180
+  UNION ALL SELECT 'PN', 'Pitkern', 181
+  UNION ALL SELECT 'PR', 'Puerto Rico', 182
+  UNION ALL SELECT 'PS', 'Palestina', 183
+  UNION ALL SELECT 'PT', 'Portugal', 184
+  UNION ALL SELECT 'PW', 'Palau', 185
+  UNION ALL SELECT 'PY', 'Paraguay', 186
+  UNION ALL SELECT 'Q', 'Katar', 187
+  UNION ALL SELECT 'RE', 'Reunion', 188
+  UNION ALL SELECT 'RM', 'San Marino', 189
+  UNION ALL SELECT 'RO', 'Rumänien', 190
+  UNION ALL SELECT 'RS', 'Serbien', 191
+  UNION ALL SELECT 'RU', 'Russische Föderation', 192
+  UNION ALL SELECT 'RW', 'Ruanda', 193
+  UNION ALL SELECT 'SA', 'Saudi Arabien', 194
+  UNION ALL SELECT 'SB', 'Salomonen', 195
+  UNION ALL SELECT 'SC', 'Seychellen', 196
+  UNION ALL SELECT 'SD', 'Sudan', 197
+  UNION ALL SELECT 'SE', 'Schweden', 198
+  UNION ALL SELECT 'SG', 'Singapur', 199
+  UNION ALL SELECT 'SH', 'Sankt Helena', 200
+  UNION ALL SELECT 'SI', 'Slowenien', 201
+  UNION ALL SELECT 'SJ', 'Svalbard', 202
+  UNION ALL SELECT 'SK', 'Slowakei', 203
+  UNION ALL SELECT 'SL', 'Sierra Leone', 204
+  UNION ALL SELECT 'SN', 'Senegal', 205
+  UNION ALL SELECT 'SO', 'Somalia', 206
+  UNION ALL SELECT 'SR', 'Suriname', 207
+  UNION ALL SELECT 'ST', 'Sao Tome und Pricipe', 208
+  UNION ALL SELECT 'SV', 'El Salvador', 209
+  UNION ALL SELECT 'SY', 'Syrien', 210
+  UNION ALL SELECT 'SZ', 'Swasiland', 211
+  UNION ALL SELECT 'TA', 'Tristan da Cunha', 212
+  UNION ALL SELECT 'TC', 'Turks und Caicosinseln', 213
+  UNION ALL SELECT 'TD', 'Tschad', 214
+  UNION ALL SELECT 'TF', 'French Southern and Antarctic Lands', 215
+  UNION ALL SELECT 'TG', 'Togo', 216
+  UNION ALL SELECT 'TH', 'Thailand', 217
+  UNION ALL SELECT 'TI', 'Timor Leste', 218
+  UNION ALL SELECT 'TJ', 'Tadschikistan', 219
+  UNION ALL SELECT 'TK', 'Tokelau', 220
+  UNION ALL SELECT 'TL', 'Ost-Timor', 221
+  UNION ALL SELECT 'TM', 'Turkmenistan', 222
+  UNION ALL SELECT 'TN', 'Tunesien', 223
+  UNION ALL SELECT 'TO', 'Tonga', 224
+  UNION ALL SELECT 'TP', 'Osttimor', 225
+  UNION ALL SELECT 'TR', 'Türkei', 226
+  UNION ALL SELECT 'TT', 'Trinidad und Tobago', 227
+  UNION ALL SELECT 'TV', 'Tuvalu', 228
+  UNION ALL SELECT 'TW', 'Taiwan', 229
+  UNION ALL SELECT 'TZ', 'Tansania', 230
+  UNION ALL SELECT 'UA', 'Ukraine', 231
+  UNION ALL SELECT 'UG', 'Uganda', 232
+  UNION ALL SELECT 'UK', 'Großbritannien', 233
+  UNION ALL SELECT 'UM', 'Baker Island', 234
+  UNION ALL SELECT 'US', 'Vereinigte Staaten (USA)', 235
+  UNION ALL SELECT 'UY', 'Uruguay', 236
+  UNION ALL SELECT 'UZ', 'Usbekistan', 237
+  UNION ALL SELECT 'V', 'Vatikanstadt', 238
+  UNION ALL SELECT 'VC', 'St. Vincent udn Grenadinen', 239
+  UNION ALL SELECT 'VE', 'Venezuela', 240
+  UNION ALL SELECT 'VG', 'Jungferninseln', 241
+  UNION ALL SELECT 'VI', 'US Jungferninseln', 242
+  UNION ALL SELECT 'VN', 'Vietnam', 243
+  UNION ALL SELECT 'VR', 'China', 244
+  UNION ALL SELECT 'VU', 'Vanuatu', 245
+  UNION ALL SELECT 'WF', 'Wallis und Futuna', 246
+  UNION ALL SELECT 'WS', 'Samoa', 247
+  UNION ALL SELECT 'X', 'Staatenlos', 248
+  UNION ALL SELECT 'YE', 'Jemen', 249
+  UNION ALL SELECT 'YT', 'Mayotte', 250
+  UNION ALL SELECT 'YU', 'ehem. Jugoslawien', 251
+  UNION ALL SELECT 'ZA', 'Südafrika', 252
+  UNION ALL SELECT 'ZM', 'Sambia', 253
+  UNION ALL SELECT 'ZW', 'Simbabwe', 254
+) AS src
+LEFT JOIN lands l ON l.land_iso_code = src.iso_code AND l.deleted_at IS NULL
+WHERE l.id IS NULL;
+
+-- +goose Down
+-- Intentionally no-op to avoid deleting existing production reference data.
+SELECT 1;
diff --git a/migrations/goose/20260506_hospital_import_staging.sql b/migrations/goose/20260506_hospital_import_staging.sql
new file mode 100644
index 0000000..43a1009
--- /dev/null
+++ b/migrations/goose/20260506_hospital_import_staging.sql
@@ -0,0 +1,23 @@
+-- +goose Up
+-- Prepare staging tables for legacy hospital dump import.
+
+CREATE TABLE IF NOT EXISTS hospital_old_import (
+  id int(11) NOT NULL,
+  name varchar(150) DEFAULT NULL,
+  address varchar(255) DEFAULT NULL,
+  office varchar(150) DEFAULT NULL,
+  mobile varchar(150) DEFAULT NULL,
+  email varchar(150) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS hospital_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_hospital_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS hospital_old_id_map;
+DROP TABLE IF EXISTS hospital_old_import;
diff --git a/migrations/goose/20260507_hospital_import_apply.sql b/migrations/goose/20260507_hospital_import_apply.sql
new file mode 100644
index 0000000..9aff312
--- /dev/null
+++ b/migrations/goose/20260507_hospital_import_apply.sql
@@ -0,0 +1,69 @@
+-- +goose Up
+-- Apply legacy hospital staging data into `hospitals`.
+-- Expected flow before this migration:
+-- 1) Run previous migration that creates `hospital_old_import`.
+-- 2) Import old dump rows into `hospital_old_import`.
+-- This migration maps old integer IDs into BINARY(16) UUID-style IDs,
+-- then upserts into `hospitals` with `is_active` forced to 1.
+
+START TRANSACTION;
+
+INSERT INTO hospital_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM hospital_old_import s
+LEFT JOIN hospital_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO hospitals (
+  id,
+  hospital_name,
+  address,
+  landline_number,
+  mobile_number,
+  email,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Hospital ', s.id)), 128) AS hospital_name,
+  LEFT(TRIM(COALESCE(s.address, '')), 256) AS address,
+  LEFT(TRIM(COALESCE(s.office, '')), 20) AS landline_number,
+  LEFT(TRIM(COALESCE(s.mobile, '')), 20) AS mobile_number,
+  LEFT(TRIM(COALESCE(s.email, '')), 128) AS email,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM hospital_old_import s
+JOIN hospital_old_id_map m ON m.old_id = s.id
+ON DUPLICATE KEY UPDATE
+  hospital_name = VALUES(hospital_name),
+  address = VALUES(address),
+  landline_number = VALUES(landline_number),
+  mobile_number = VALUES(mobile_number),
+  email = VALUES(email),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+COMMIT;
+
+-- +goose Down
+-- Data migration is intentionally non-reversible.
+-- Keep imported data and ID mapping as audit trail.
+SELECT 1;
diff --git a/migrations/goose/20260508_icao_import_staging.sql b/migrations/goose/20260508_icao_import_staging.sql
new file mode 100644
index 0000000..9d2adb0
--- /dev/null
+++ b/migrations/goose/20260508_icao_import_staging.sql
@@ -0,0 +1,23 @@
+-- +goose Up
+-- Prepare staging tables for legacy ICAO dump import.
+
+CREATE TABLE IF NOT EXISTS icao_old_import (
+  id int(11) NOT NULL,
+  code varchar(150) NOT NULL,
+  address varchar(255) DEFAULT NULL,
+  phone varchar(50) DEFAULT NULL,
+  mobile varchar(50) DEFAULT NULL,
+  email varchar(50) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS icao_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_icao_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS icao_old_id_map;
+DROP TABLE IF EXISTS icao_old_import;
diff --git a/migrations/goose/20260509_icao_import_apply.sql b/migrations/goose/20260509_icao_import_apply.sql
new file mode 100644
index 0000000..4abbbbc
--- /dev/null
+++ b/migrations/goose/20260509_icao_import_apply.sql
@@ -0,0 +1,69 @@
+-- +goose Up
+-- Apply legacy ICAO staging data into `icaos`.
+-- Expected flow before this migration:
+-- 1) Run previous migration that creates `icao_old_import`.
+-- 2) Import old dump rows into `icao_old_import`.
+-- This migration maps old integer IDs into BINARY(16) UUID-style IDs,
+-- then upserts into `icaos` with `is_active` forced to 1.
+
+START TRANSACTION;
+
+INSERT INTO icao_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM icao_old_import s
+LEFT JOIN icao_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO icaos (
+  id,
+  icao_code,
+  address,
+  landline_number,
+  mobile_number,
+  email,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.code), ''), CONCAT('ICAO-', s.id)), 16) AS icao_code,
+  LEFT(TRIM(COALESCE(s.address, '')), 256) AS address,
+  LEFT(TRIM(COALESCE(s.phone, '')), 20) AS landline_number,
+  LEFT(TRIM(COALESCE(s.mobile, '')), 20) AS mobile_number,
+  LEFT(TRIM(COALESCE(s.email, '')), 128) AS email,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM icao_old_import s
+JOIN icao_old_id_map m ON m.old_id = s.id
+ON DUPLICATE KEY UPDATE
+  icao_code = VALUES(icao_code),
+  address = VALUES(address),
+  landline_number = VALUES(landline_number),
+  mobile_number = VALUES(mobile_number),
+  email = VALUES(email),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+COMMIT;
+
+-- +goose Down
+-- Data migration is intentionally non-reversible.
+-- Keep imported data and ID mapping as audit trail.
+SELECT 1;
diff --git a/migrations/goose/20260510_kassa_import_staging.sql b/migrations/goose/20260510_kassa_import_staging.sql
new file mode 100644
index 0000000..28143d7
--- /dev/null
+++ b/migrations/goose/20260510_kassa_import_staging.sql
@@ -0,0 +1,23 @@
+-- +goose Up
+-- Prepare staging tables for legacy kassa dump import.
+
+CREATE TABLE IF NOT EXISTS kassa_old_import (
+  id int(11) NOT NULL,
+  name varchar(150) DEFAULT NULL,
+  region varchar(255) DEFAULT NULL,
+  address varchar(255) DEFAULT NULL,
+  phone varchar(150) DEFAULT NULL,
+  email varchar(150) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS kassa_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_kassa_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS kassa_old_id_map;
+DROP TABLE IF EXISTS kassa_old_import;
diff --git a/migrations/goose/20260511_kassa_import_apply.sql b/migrations/goose/20260511_kassa_import_apply.sql
new file mode 100644
index 0000000..6ecb040
--- /dev/null
+++ b/migrations/goose/20260511_kassa_import_apply.sql
@@ -0,0 +1,69 @@
+-- +goose Up
+-- Apply legacy kassa staging data into `health_insurance_companies`.
+-- Expected flow before this migration:
+-- 1) Run previous migration that creates `kassa_old_import`.
+-- 2) Import old dump rows into `kassa_old_import`.
+-- This migration maps old integer IDs into BINARY(16) UUID-style IDs,
+-- then upserts into `health_insurance_companies` with `is_active` forced to 1.
+
+START TRANSACTION;
+
+INSERT INTO kassa_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM kassa_old_import s
+LEFT JOIN kassa_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO health_insurance_companies (
+  id,
+  name,
+  state,
+  address,
+  mobile_number,
+  email,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Kassa ', s.id)), 128) AS name,
+  LEFT(TRIM(COALESCE(s.region, '')), 128) AS state,
+  LEFT(TRIM(COALESCE(s.address, '')), 256) AS address,
+  LEFT(TRIM(COALESCE(s.phone, '')), 20) AS mobile_number,
+  LEFT(TRIM(COALESCE(s.email, '')), 128) AS email,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM kassa_old_import s
+JOIN kassa_old_id_map m ON m.old_id = s.id
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  state = VALUES(state),
+  address = VALUES(address),
+  mobile_number = VALUES(mobile_number),
+  email = VALUES(email),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+COMMIT;
+
+-- +goose Down
+-- Data migration is intentionally non-reversible.
+-- Keep imported data and ID mapping as audit trail.
+SELECT 1;
diff --git a/migrations/goose/20260512_nationality_import_staging.sql b/migrations/goose/20260512_nationality_import_staging.sql
new file mode 100644
index 0000000..49a2e03
--- /dev/null
+++ b/migrations/goose/20260512_nationality_import_staging.sql
@@ -0,0 +1,20 @@
+-- +goose Up
+-- Prepare staging tables for legacy nationality dump import.
+
+CREATE TABLE IF NOT EXISTS nationality_old_import (
+  id int(11) NOT NULL,
+  name varchar(150) NOT NULL,
+  description varchar(255) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS nationality_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_nationality_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS nationality_old_id_map;
+DROP TABLE IF EXISTS nationality_old_import;
diff --git a/migrations/goose/20260513_nationality_import_apply.sql b/migrations/goose/20260513_nationality_import_apply.sql
new file mode 100644
index 0000000..1482d02
--- /dev/null
+++ b/migrations/goose/20260513_nationality_import_apply.sql
@@ -0,0 +1,88 @@
+-- +goose Up
+-- Apply legacy nationality staging data into `nationalities`.
+-- Expected flow before this migration:
+-- 1) Run previous migration that creates `nationality_old_import`.
+-- 2) Import old dump rows into `nationality_old_import`.
+-- This migration maps old integer IDs into BINARY(16) UUID-style IDs,
+-- then upserts into `nationalities` with `is_active` forced to 1.
+
+START TRANSACTION;
+
+INSERT INTO nationality_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM nationality_old_import s
+LEFT JOIN nationality_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO lands (
+  id,
+  name,
+  land_iso_code,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  UUID_TO_BIN(UUID()) AS id,
+  src.land_name AS name,
+  '' AS land_iso_code,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM (
+  SELECT DISTINCT
+    LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Nationality ', s.id)), 128) AS land_name
+  FROM nationality_old_import s
+) src
+LEFT JOIN lands l
+  ON LOWER(TRIM(l.name)) = LOWER(src.land_name)
+  AND l.deleted_at IS NULL
+WHERE l.id IS NULL;
+
+INSERT INTO nationalities (
+  id,
+  land_id,
+  name,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id,
+  l.id AS land_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Nationality ', s.id)), 128) AS name,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM nationality_old_import s
+JOIN nationality_old_id_map m ON m.old_id = s.id
+LEFT JOIN lands l
+  ON LOWER(TRIM(l.name)) = LOWER(LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Nationality ', s.id)), 128))
+  AND l.deleted_at IS NULL
+ON DUPLICATE KEY UPDATE
+  land_id = VALUES(land_id),
+  name = VALUES(name),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+COMMIT;
+
+-- +goose Down
+-- Data migration is intentionally non-reversible.
+-- Keep imported data and ID mapping as audit trail.
+SELECT 1;
diff --git a/migrations/goose/20260514_bundesland_import_staging.sql b/migrations/goose/20260514_bundesland_import_staging.sql
new file mode 100644
index 0000000..42722cc
--- /dev/null
+++ b/migrations/goose/20260514_bundesland_import_staging.sql
@@ -0,0 +1,20 @@
+-- +goose Up
+-- Prepare staging tables for legacy bundesland dump import.
+
+CREATE TABLE IF NOT EXISTS bundesland_old_import (
+  id int(11) NOT NULL,
+  name varchar(150) NOT NULL,
+  state varchar(150) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS bundesland_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_bundesland_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS bundesland_old_id_map;
+DROP TABLE IF EXISTS bundesland_old_import;
diff --git a/migrations/goose/20260515_bundesland_import_apply.sql b/migrations/goose/20260515_bundesland_import_apply.sql
new file mode 100644
index 0000000..00442c0
--- /dev/null
+++ b/migrations/goose/20260515_bundesland_import_apply.sql
@@ -0,0 +1,140 @@
+-- +goose Up
+-- Apply legacy bundesland staging data into `federal_states`.
+-- Expected flow before this migration:
+-- 1) Run previous migration that creates `bundesland_old_import`.
+-- 2) Import old dump rows into `bundesland_old_import`.
+-- This migration maps old integer IDs into BINARY(16) UUID-style IDs,
+-- then upserts into `federal_states` with `is_active` forced to 1.
+
+START TRANSACTION;
+
+INSERT INTO bundesland_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM bundesland_old_import s
+LEFT JOIN bundesland_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO lands (
+  id,
+  name,
+  land_iso_code,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  UUID_TO_BIN(UUID()) AS id,
+  src.land_name AS name,
+  '' AS land_iso_code,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM (
+  SELECT DISTINCT
+    LEFT(
+      CASE
+        WHEN NULLIF(TRIM(s.state), '') IS NOT NULL THEN TRIM(s.state)
+        WHEN TRIM(s.name) IN (
+          'Vorarlberg',
+          'Tirol',
+          'Burgenland',
+          'Wien',
+          'Salzburg',
+          'Steiermark',
+          'Kärnten',
+          'Oberösterreich',
+          'Niederösterreich'
+        ) THEN 'Österreich'
+        ELSE ''
+      END,
+      128
+    ) AS land_name
+  FROM bundesland_old_import s
+  WHERE NULLIF(
+    CASE
+      WHEN NULLIF(TRIM(s.state), '') IS NOT NULL THEN TRIM(s.state)
+      WHEN TRIM(s.name) IN (
+        'Vorarlberg',
+        'Tirol',
+        'Burgenland',
+        'Wien',
+        'Salzburg',
+        'Steiermark',
+        'Kärnten',
+        'Oberösterreich',
+        'Niederösterreich'
+      ) THEN 'Österreich'
+      ELSE ''
+    END,
+    ''
+  ) IS NOT NULL
+) src
+LEFT JOIN lands l
+  ON LOWER(TRIM(l.name)) = LOWER(src.land_name)
+  AND l.deleted_at IS NULL
+WHERE l.id IS NULL;
+
+INSERT INTO federal_states (
+  id,
+  land_id,
+  name,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id,
+  l.id AS land_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Federal State ', s.id)), 128) AS name,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM bundesland_old_import s
+JOIN bundesland_old_id_map m ON m.old_id = s.id
+LEFT JOIN lands l
+  ON LOWER(TRIM(l.name)) = LOWER(LEFT(
+    CASE
+      WHEN NULLIF(TRIM(s.state), '') IS NOT NULL THEN TRIM(s.state)
+      WHEN TRIM(s.name) IN (
+        'Vorarlberg',
+        'Tirol',
+        'Burgenland',
+        'Wien',
+        'Salzburg',
+        'Steiermark',
+        'Kärnten',
+        'Oberösterreich',
+        'Niederösterreich'
+      ) THEN 'Österreich'
+      ELSE ''
+    END,
+    128
+  ))
+  AND l.deleted_at IS NULL
+ON DUPLICATE KEY UPDATE
+  land_id = VALUES(land_id),
+  name = VALUES(name),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+COMMIT;
+
+-- +goose Down
+-- Data migration is intentionally non-reversible.
+-- Keep imported data and ID mapping as audit trail.
+SELECT 1;
diff --git a/migrations/goose/20260516_opc_import_staging.sql b/migrations/goose/20260516_opc_import_staging.sql
new file mode 100644
index 0000000..dd352b5
--- /dev/null
+++ b/migrations/goose/20260516_opc_import_staging.sql
@@ -0,0 +1,20 @@
+-- +goose Up
+-- Prepare staging tables for legacy OPC dump import.
+
+CREATE TABLE IF NOT EXISTS opc_old_import (
+  id int(11) NOT NULL,
+  title varchar(150) NOT NULL,
+  description varchar(255) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS opc_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_opc_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS opc_old_id_map;
+DROP TABLE IF EXISTS opc_old_import;
diff --git a/migrations/goose/20260517_opc_import_apply.sql b/migrations/goose/20260517_opc_import_apply.sql
new file mode 100644
index 0000000..367d903
--- /dev/null
+++ b/migrations/goose/20260517_opc_import_apply.sql
@@ -0,0 +1,57 @@
+-- +goose Up
+-- Apply legacy OPC staging data into `opcs`.
+-- Expected flow before this migration:
+-- 1) Run previous migration that creates `opc_old_import`.
+-- 2) Import old dump rows into `opc_old_import`.
+-- This migration maps old integer IDs into BINARY(16) UUID-style IDs,
+-- then upserts into `opcs` with `is_active` forced to 1.
+
+START TRANSACTION;
+
+INSERT INTO opc_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM opc_old_import s
+LEFT JOIN opc_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO opcs (
+  id,
+  name,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.title), ''), CONCAT('OPC ', s.id)), 64) AS name,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM opc_old_import s
+JOIN opc_old_id_map m ON m.old_id = s.id
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+COMMIT;
+
+-- +goose Down
+-- Data migration is intentionally non-reversible.
+-- Keep imported data and ID mapping as audit trail.
+SELECT 1;
diff --git a/migrations/goose/20260518_forces_import_staging.sql b/migrations/goose/20260518_forces_import_staging.sql
new file mode 100644
index 0000000..7cf4a95
--- /dev/null
+++ b/migrations/goose/20260518_forces_import_staging.sql
@@ -0,0 +1,20 @@
+-- +goose Up
+-- Prepare staging tables for legacy forces dump import.
+
+CREATE TABLE IF NOT EXISTS forces_old_import (
+  id int(11) NOT NULL,
+  name varchar(150) NOT NULL,
+  description varchar(255) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS forces_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_forces_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS forces_old_id_map;
+DROP TABLE IF EXISTS forces_old_import;
diff --git a/migrations/goose/20260519_forces_import_apply.sql b/migrations/goose/20260519_forces_import_apply.sql
new file mode 100644
index 0000000..533e860
--- /dev/null
+++ b/migrations/goose/20260519_forces_import_apply.sql
@@ -0,0 +1,57 @@
+-- +goose Up
+-- Apply legacy forces staging data into `forces_present`.
+-- Expected flow before this migration:
+-- 1) Run previous migration that creates `forces_old_import`.
+-- 2) Import old dump rows into `forces_old_import`.
+-- This migration maps old integer IDs into BINARY(16) UUID-style IDs,
+-- then upserts into `forces_present` with `is_active` forced to 1.
+
+START TRANSACTION;
+
+INSERT INTO forces_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM forces_old_import s
+LEFT JOIN forces_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO forces_present (
+  id,
+  name,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Forces ', s.id)), 128) AS name,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM forces_old_import s
+JOIN forces_old_id_map m ON m.old_id = s.id
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+COMMIT;
+
+-- +goose Down
+-- Data migration is intentionally non-reversible.
+-- Keep imported data and ID mapping as audit trail.
+SELECT 1;
diff --git a/migrations/goose/20260520_vocation_import_staging.sql b/migrations/goose/20260520_vocation_import_staging.sql
new file mode 100644
index 0000000..0f3fa8f
--- /dev/null
+++ b/migrations/goose/20260520_vocation_import_staging.sql
@@ -0,0 +1,20 @@
+-- +goose Up
+-- Prepare staging tables for legacy vocation dump import.
+
+CREATE TABLE IF NOT EXISTS vocation_old_import (
+  id int(11) NOT NULL,
+  name varchar(150) NOT NULL,
+  description varchar(255) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS vocation_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_vocation_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS vocation_old_id_map;
+DROP TABLE IF EXISTS vocation_old_import;
diff --git a/migrations/goose/20260521_vocation_import_apply.sql b/migrations/goose/20260521_vocation_import_apply.sql
new file mode 100644
index 0000000..25ae3b7
--- /dev/null
+++ b/migrations/goose/20260521_vocation_import_apply.sql
@@ -0,0 +1,57 @@
+-- +goose Up
+-- Apply legacy vocation staging data into `vocations`.
+-- Expected flow before this migration:
+-- 1) Run previous migration that creates `vocation_old_import`.
+-- 2) Import old dump rows into `vocation_old_import`.
+-- This migration maps old integer IDs into BINARY(16) UUID-style IDs,
+-- then upserts into `vocations` with `is_active` forced to 1.
+
+START TRANSACTION;
+
+INSERT INTO vocation_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM vocation_old_import s
+LEFT JOIN vocation_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO vocations (
+  id,
+  name,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Vocation ', s.id)), 64) AS name,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM vocation_old_import s
+JOIN vocation_old_id_map m ON m.old_id = s.id
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+COMMIT;
+
+-- +goose Down
+-- Data migration is intentionally non-reversible.
+-- Keep imported data and ID mapping as audit trail.
+SELECT 1;
diff --git a/migrations/goose/20260522_medicine_legacy_import_staging.sql b/migrations/goose/20260522_medicine_legacy_import_staging.sql
new file mode 100644
index 0000000..eb5d867
--- /dev/null
+++ b/migrations/goose/20260522_medicine_legacy_import_staging.sql
@@ -0,0 +1,60 @@
+-- +goose Up
+-- Prepare staging tables for legacy medicine import:
+-- - cmedikamente
+-- - cmedikamente_group
+-- - cmotorische_reaktion
+
+CREATE TABLE IF NOT EXISTS medicine_group_old_import (
+  id int(11) NOT NULL,
+  name varchar(255) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS medicine_group_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_medicine_group_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS motor_reaction_old_import (
+  id int(11) NOT NULL,
+  name varchar(255) DEFAULT NULL,
+  ball int(11) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS motor_reaction_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_motor_reaction_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS medicine_old_import (
+  id int(11) NOT NULL,
+  name varchar(255) DEFAULT NULL,
+  dose varchar(255) DEFAULT NULL,
+  weight int(11) DEFAULT NULL,
+  `col` int(11) DEFAULT NULL,
+  cmedikamente_group_id int(11) DEFAULT NULL,
+  motor_reaction_old_id int(11) DEFAULT NULL,
+  PRIMARY KEY (id),
+  KEY idx_medicine_old_import_group (cmedikamente_group_id),
+  KEY idx_medicine_old_import_reaction (motor_reaction_old_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS medicine_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_medicine_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS medicine_old_id_map;
+DROP TABLE IF EXISTS medicine_old_import;
+DROP TABLE IF EXISTS motor_reaction_old_id_map;
+DROP TABLE IF EXISTS motor_reaction_old_import;
+DROP TABLE IF EXISTS medicine_group_old_id_map;
+DROP TABLE IF EXISTS medicine_group_old_import;
diff --git a/migrations/goose/20260523_medicine_legacy_import_apply.sql b/migrations/goose/20260523_medicine_legacy_import_apply.sql
new file mode 100644
index 0000000..c11e898
--- /dev/null
+++ b/migrations/goose/20260523_medicine_legacy_import_apply.sql
@@ -0,0 +1,163 @@
+-- +goose Up
+-- Apply legacy medicine staging data into:
+-- - medicine_groups
+-- - motor_reactions
+-- - medicines
+--
+-- Expected flow before this migration:
+-- 1) Run staging migration that creates *_old_import tables.
+-- 2) Load legacy dump data into:
+--    - medicine_group_old_import
+--    - motor_reaction_old_import
+--    - medicine_old_import
+
+START TRANSACTION;
+
+INSERT INTO medicine_group_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM medicine_group_old_import s
+LEFT JOIN medicine_group_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO motor_reaction_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM motor_reaction_old_import s
+LEFT JOIN motor_reaction_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO medicine_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM medicine_old_import s
+LEFT JOIN medicine_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO medicine_groups (
+  id,
+  name,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Medicine Group ', s.id)), 255) AS name,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM medicine_group_old_import s
+JOIN medicine_group_old_id_map m ON m.old_id = s.id
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+INSERT INTO motor_reactions (
+  id,
+  name,
+  score,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Motor Reaction ', s.id)), 255) AS name,
+  s.ball AS score,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM motor_reaction_old_import s
+JOIN motor_reaction_old_id_map m ON m.old_id = s.id
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  score = VALUES(score),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+INSERT INTO medicines (
+  id,
+  name,
+  dose,
+  weight,
+  `column`,
+  medicine_group_id,
+  motor_reaction_id,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  med_map.new_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Medicine ', s.id)), 128) AS name,
+  LEFT(TRIM(COALESCE(s.dose, '')), 128) AS dose,
+  s.weight AS weight,
+  COALESCE(s.`col`, 0) AS `column`,
+  grp_map.new_id AS medicine_group_id,
+  react_map.new_id AS motor_reaction_id,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM medicine_old_import s
+JOIN medicine_old_id_map med_map ON med_map.old_id = s.id
+LEFT JOIN medicine_group_old_id_map grp_map ON grp_map.old_id = s.cmedikamente_group_id
+LEFT JOIN motor_reaction_old_id_map react_map ON react_map.old_id = s.motor_reaction_old_id
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  dose = VALUES(dose),
+  weight = VALUES(weight),
+  `column` = VALUES(`column`),
+  medicine_group_id = VALUES(medicine_group_id),
+  motor_reaction_id = VALUES(motor_reaction_id),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+COMMIT;
+
+-- +goose Down
+-- Data migration is intentionally non-reversible.
+SELECT 1;
diff --git a/migrations/goose/20260524_medicine_clegacy_import_staging.sql b/migrations/goose/20260524_medicine_clegacy_import_staging.sql
new file mode 100644
index 0000000..beedf9d
--- /dev/null
+++ b/migrations/goose/20260524_medicine_clegacy_import_staging.sql
@@ -0,0 +1,58 @@
+-- +goose Up
+-- Staging table set for legacy medicine dump format:
+-- - cmedikamente_group
+-- - cmotorische_reaktion
+-- - cmedikamente
+
+CREATE TABLE IF NOT EXISTS cmedikamente_group_old_import (
+  id INT(11) NOT NULL,
+  name VARCHAR(255) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS cmotorische_old_import (
+  id INT(11) NOT NULL,
+  name VARCHAR(255) DEFAULT NULL,
+  ball INT(11) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS cmedikamente_old_import (
+  id INT(11) NOT NULL,
+  name VARCHAR(255) DEFAULT NULL,
+  dose VARCHAR(255) DEFAULT NULL,
+  weight INT(11) DEFAULT NULL,
+  col INT(11) DEFAULT NULL,
+  cmedikamente_group_id INT(11) DEFAULT NULL,
+  PRIMARY KEY (id),
+  KEY idx_cmedikamente_old_group_id (cmedikamente_group_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS cmedikamente_group_old_id_map (
+  old_id INT(11) NOT NULL,
+  new_id BINARY(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_cmedikamente_group_old_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS cmotorische_old_id_map (
+  old_id INT(11) NOT NULL,
+  new_id BINARY(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_cmotorische_old_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS cmedikamente_old_id_map (
+  old_id INT(11) NOT NULL,
+  new_id BINARY(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_cmedikamente_old_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS cmedikamente_old_id_map;
+DROP TABLE IF EXISTS cmotorische_old_id_map;
+DROP TABLE IF EXISTS cmedikamente_group_old_id_map;
+DROP TABLE IF EXISTS cmedikamente_old_import;
+DROP TABLE IF EXISTS cmotorische_old_import;
+DROP TABLE IF EXISTS cmedikamente_group_old_import;
diff --git a/migrations/goose/20260525_medicine_clegacy_import_apply.sql b/migrations/goose/20260525_medicine_clegacy_import_apply.sql
new file mode 100644
index 0000000..0839ed1
--- /dev/null
+++ b/migrations/goose/20260525_medicine_clegacy_import_apply.sql
@@ -0,0 +1,165 @@
+-- +goose Up
+-- Apply legacy c* staging data into target tables:
+-- - medicine_groups
+-- - motor_reactions
+-- - medicines
+-- - medicine_motor_reactions (optional backfill via motor_reaction_id)
+
+START TRANSACTION;
+
+CREATE TABLE IF NOT EXISTS cmedikamente_group_old_import (
+  id INT(11) NOT NULL,
+  name VARCHAR(255) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS cmotorische_old_import (
+  id INT(11) NOT NULL,
+  name VARCHAR(255) DEFAULT NULL,
+  ball INT(11) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS cmedikamente_old_import (
+  id INT(11) NOT NULL,
+  name VARCHAR(255) DEFAULT NULL,
+  dose VARCHAR(255) DEFAULT NULL,
+  weight INT(11) DEFAULT NULL,
+  col INT(11) DEFAULT NULL,
+  cmedikamente_group_id INT(11) DEFAULT NULL,
+  PRIMARY KEY (id),
+  KEY idx_cmedikamente_old_import_group_id (cmedikamente_group_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS cmedikamente_group_old_id_map (
+  old_id INT(11) NOT NULL,
+  new_id BINARY(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_cmedikamente_group_old_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS cmotorische_old_id_map (
+  old_id INT(11) NOT NULL,
+  new_id BINARY(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_cmotorische_old_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS cmedikamente_old_id_map (
+  old_id INT(11) NOT NULL,
+  new_id BINARY(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_cmedikamente_old_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+INSERT INTO cmedikamente_group_old_id_map (old_id, new_id)
+SELECT
+  s.id,
+  UNHEX(REPLACE(UUID(), '-', ''))
+FROM cmedikamente_group_old_import s
+LEFT JOIN cmedikamente_group_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO cmotorische_old_id_map (old_id, new_id)
+SELECT
+  s.id,
+  UNHEX(REPLACE(UUID(), '-', ''))
+FROM cmotorische_old_import s
+LEFT JOIN cmotorische_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO cmedikamente_old_id_map (old_id, new_id)
+SELECT
+  s.id,
+  UNHEX(REPLACE(UUID(), '-', ''))
+FROM cmedikamente_old_import s
+LEFT JOIN cmedikamente_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+INSERT INTO medicine_groups (
+  id,
+  name,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  map.new_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Medicine Group ', s.id)), 255),
+  1,
+  UTC_TIMESTAMP(),
+  UTC_TIMESTAMP()
+FROM cmedikamente_group_old_import s
+JOIN cmedikamente_group_old_id_map map ON map.old_id = s.id
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+INSERT INTO motor_reactions (
+  id,
+  name,
+  score,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  map.new_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Motor Reaction ', s.id)), 255),
+  s.ball,
+  1,
+  UTC_TIMESTAMP(),
+  UTC_TIMESTAMP()
+FROM cmotorische_old_import s
+JOIN cmotorische_old_id_map map ON map.old_id = s.id
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  score = VALUES(score),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+INSERT INTO medicines (
+  id,
+  name,
+  dose,
+  weight,
+  `column`,
+  medicine_group_id,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  med_map.new_id,
+  LEFT(COALESCE(NULLIF(TRIM(s.name), ''), CONCAT('Medicine ', s.id)), 128),
+  LEFT(TRIM(COALESCE(s.dose, '')), 128),
+  s.weight,
+  COALESCE(s.col, 0),
+  grp_map.new_id,
+  1,
+  UTC_TIMESTAMP(),
+  UTC_TIMESTAMP()
+FROM cmedikamente_old_import s
+JOIN cmedikamente_old_id_map med_map ON med_map.old_id = s.id
+LEFT JOIN cmedikamente_group_old_id_map grp_map ON grp_map.old_id = s.cmedikamente_group_id
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  dose = VALUES(dose),
+  weight = VALUES(weight),
+  `column` = VALUES(`column`),
+  medicine_group_id = VALUES(medicine_group_id),
+  is_active = 1,
+  updated_at = UTC_TIMESTAMP();
+
+-- Optional compatibility backfill: if medicines.motor_reaction_id exists, sync into join table.
+INSERT IGNORE INTO medicine_motor_reactions (medicine_id, motor_reaction_id)
+SELECT id, motor_reaction_id
+FROM medicines
+WHERE motor_reaction_id IS NOT NULL;
+
+COMMIT;
+
+-- +goose Down
+-- Data migration is intentionally non-reversible.
+SELECT 1;
diff --git a/migrations/goose/20260526_auth_email_otp_toggle.sql b/migrations/goose/20260526_auth_email_otp_toggle.sql
new file mode 100644
index 0000000..3775a99
--- /dev/null
+++ b/migrations/goose/20260526_auth_email_otp_toggle.sql
@@ -0,0 +1,23 @@
+-- +goose Up
+INSERT INTO master_setting_values (
+  setting_key,
+  value,
+  is_encrypted,
+  created_at,
+  updated_at
+)
+VALUES (
+  'AUTH_LOGIN_EMAIL_OTP_ENABLED',
+  'false',
+  0,
+  UTC_TIMESTAMP(),
+  UTC_TIMESTAMP()
+)
+ON DUPLICATE KEY UPDATE
+  value = VALUES(value),
+  is_encrypted = 0,
+  updated_at = UTC_TIMESTAMP();
+
+-- +goose Down
+DELETE FROM master_setting_values
+WHERE setting_key = 'AUTH_LOGIN_EMAIL_OTP_ENABLED';
diff --git a/migrations/goose/20260527_user_import_staging.sql b/migrations/goose/20260527_user_import_staging.sql
new file mode 100644
index 0000000..80bb6da
--- /dev/null
+++ b/migrations/goose/20260527_user_import_staging.sql
@@ -0,0 +1,103 @@
+-- +goose Up
+-- Prepare staging tables for legacy `user` dump import.
+-- Source table in old DB: `user` (not `users`).
+
+CREATE TABLE IF NOT EXISTS user_old_import (
+  id int(11) NOT NULL,
+  state tinyint(1) DEFAULT 0,
+  role int(2) NOT NULL,
+  username varchar(30) DEFAULT NULL,
+  password varchar(150) DEFAULT NULL,
+  fullname varchar(50) DEFAULT NULL,
+  shortName varchar(30) DEFAULT NULL,
+  flightNumber varchar(20) DEFAULT NULL,
+  license varchar(20) DEFAULT NULL,
+  techLicense varchar(20) DEFAULT NULL,
+  airport_pilot varchar(15) DEFAULT NULL,
+  responsible_pilot varchar(15) DEFAULT NULL,
+  second_pilot varchar(15) DEFAULT NULL,
+  double_tax_pilot varchar(15) DEFAULT NULL,
+  flight_instructor_pilot varchar(15) DEFAULT NULL,
+  night_pilot varchar(15) DEFAULT NULL,
+  fir_pilot varchar(15) DEFAULT NULL,
+  start_date varchar(15) DEFAULT NULL,
+  date_active varchar(15) DEFAULT NULL,
+  address varchar(255) DEFAULT NULL,
+  zipCode varchar(15) DEFAULT NULL,
+  street varchar(255) DEFAULT NULL,
+  phone varchar(50) DEFAULT NULL,
+  mobile varchar(50) DEFAULT NULL,
+  email varchar(70) DEFAULT NULL,
+  photo varchar(50) DEFAULT NULL,
+  token varchar(255) DEFAULT NULL,
+  hash varchar(255) DEFAULT NULL,
+  regDate timestamp NULL DEFAULT NULL,
+  lastVisit timestamp NULL DEFAULT NULL,
+  reportDate datetime DEFAULT NULL,
+  deletedAt varchar(32) DEFAULT NULL,
+  isDeleted tinyint(1) DEFAULT 0,
+  visible tinyint(1) DEFAULT 1,
+  lang varchar(5) DEFAULT 'de',
+  bases varchar(255) DEFAULT NULL,
+  legacy_url varchar(255) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS user_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_user_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS legacy_user_role_map (
+  legacy_role int(2) NOT NULL,
+  role_code varchar(64) NOT NULL,
+  staff_role_label varchar(120) DEFAULT NULL,
+  pilot_category varchar(16) DEFAULT NULL,
+  is_chief_pilot tinyint(1) NOT NULL DEFAULT 0,
+  is_chief_physician tinyint(1) NOT NULL DEFAULT 0,
+  is_chief_physician_in_charge tinyint(1) NOT NULL DEFAULT 0,
+  is_chief_technician tinyint(1) NOT NULL DEFAULT 0,
+  PRIMARY KEY (legacy_role)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+INSERT INTO legacy_user_role_map (
+  legacy_role,
+  role_code,
+  staff_role_label,
+  pilot_category,
+  is_chief_pilot,
+  is_chief_physician,
+  is_chief_physician_in_charge,
+  is_chief_technician
+)
+VALUES
+  (1,  'pilot',            NULL,             'regular',   0, 0, 0, 0),
+  (2,  'pilot',            NULL,             'regular',   1, 0, 0, 0),
+  (3,  'doctor',           NULL,             NULL,        0, 0, 0, 0),
+  (4,  'doctor',           NULL,             NULL,        0, 1, 0, 0),
+  (5,  'air_rescuer',      NULL,             NULL,        0, 0, 0, 0),
+  (6,  'air_rescuer',      NULL,             NULL,        0, 0, 1, 0),
+  (7,  'admin',            'administrator',  NULL,        0, 0, 0, 0),
+  (8,  'staff',            'billing',        NULL,        0, 0, 0, 0),
+  (9,  'technician',       NULL,             NULL,        0, 0, 0, 0),
+  (10, 'technician',       NULL,             NULL,        0, 0, 0, 1),
+  (11, 'flight_assistant', NULL,             NULL,        0, 0, 0, 0),
+  (12, 'staff',            'manager',        NULL,        0, 0, 0, 0),
+  (13, 'pilot',            NULL,             'freelance', 0, 0, 0, 0),
+  (14, 'pilot',            NULL,             'dry_lease', 0, 0, 0, 0),
+  (15, 'staff',            'control_center', NULL,        0, 0, 0, 0)
+ON DUPLICATE KEY UPDATE
+  role_code = VALUES(role_code),
+  staff_role_label = VALUES(staff_role_label),
+  pilot_category = VALUES(pilot_category),
+  is_chief_pilot = VALUES(is_chief_pilot),
+  is_chief_physician = VALUES(is_chief_physician),
+  is_chief_physician_in_charge = VALUES(is_chief_physician_in_charge),
+  is_chief_technician = VALUES(is_chief_technician);
+
+-- +goose Down
+DROP TABLE IF EXISTS legacy_user_role_map;
+DROP TABLE IF EXISTS user_old_id_map;
+DROP TABLE IF EXISTS user_old_import;
diff --git a/migrations/goose/20260528_user_import_apply.sql b/migrations/goose/20260528_user_import_apply.sql
new file mode 100644
index 0000000..ef825a5
--- /dev/null
+++ b/migrations/goose/20260528_user_import_apply.sql
@@ -0,0 +1,421 @@
+-- +goose Up
+-- Apply legacy user staging data into new auth/contact schema.
+-- Expected flow before this migration:
+-- 1) Run previous migration that creates `user_old_import` and role map.
+-- 2) Import old dump rows into `user_old_import`.
+-- This migration maps old integer IDs into BINARY(16) UUID-style IDs,
+-- then upserts into `users`, `user_roles`, and role-specific profile tables.
+
+START TRANSACTION;
+
+-- 1) Reuse existing users by normalized email when possible.
+INSERT INTO user_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  u.id AS new_id
+FROM user_old_import s
+JOIN users u
+  ON LOWER(TRIM(u.email)) = LOWER(TRIM(s.email))
+LEFT JOIN user_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL
+  AND s.email IS NOT NULL
+  AND TRIM(s.email) <> '';
+
+-- 2) Generate IDs for remaining legacy users.
+INSERT INTO user_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM user_old_import s
+LEFT JOIN user_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+-- 3) Upsert core users.
+INSERT INTO users (
+  id,
+  role_id,
+  email,
+  username,
+  first_name,
+  last_name,
+  mobile_phone,
+  timezone,
+  is_active,
+  password_hash,
+  salt_value,
+  email_verified_at,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id AS id,
+  r.id AS role_id,
+  CONCAT(
+    COALESCE(
+      NULLIF(LOWER(TRIM(SUBSTRING_INDEX(NULLIF(s.email, ''), '@', 1))), ''),
+      CONCAT('legacy-user-', s.id)
+    ),
+    '+u', s.id,
+    '@mybit-innovation'
+  ) AS email,
+  NULLIF(LEFT(TRIM(COALESCE(s.username, '')), 100), '') AS username,
+  LEFT(SUBSTRING_INDEX(TRIM(COALESCE(NULLIF(s.fullname, ''), NULLIF(s.username, ''), CONCAT('Legacy User ', s.id))), ' ', 1), 100) AS first_name,
+  LEFT(
+    COALESCE(
+      NULLIF(
+        TRIM(
+          SUBSTRING(
+            TRIM(COALESCE(NULLIF(s.fullname, ''), NULLIF(s.username, ''), CONCAT('Legacy User ', s.id))),
+            LENGTH(SUBSTRING_INDEX(TRIM(COALESCE(NULLIF(s.fullname, ''), NULLIF(s.username, ''), CONCAT('Legacy User ', s.id))), ' ', 1)) + 1
+          )
+        ),
+        ''
+      ),
+      '-'
+    ),
+    100
+  ) AS last_name,
+  LEFT(TRIM(COALESCE(s.mobile, s.phone, '')), 32) AS mobile_phone,
+  'UTC' AS timezone,
+  CASE WHEN COALESCE(s.visible, 1) = 1 THEN 1 ELSE 0 END AS is_active,
+  NULL AS password_hash,
+  NULL AS salt_value,
+  NULL AS email_verified_at,
+  COALESCE(s.regDate, UTC_TIMESTAMP()) AS created_at,
+  COALESCE(s.lastVisit, UTC_TIMESTAMP()) AS updated_at
+FROM user_old_import s
+JOIN user_old_id_map m ON m.old_id = s.id
+LEFT JOIN legacy_user_role_map lrm ON lrm.legacy_role = s.role
+JOIN roles r ON r.code = COALESCE(lrm.role_code, 'staff')
+ON DUPLICATE KEY UPDATE
+  role_id = VALUES(role_id),
+  username = VALUES(username),
+  first_name = VALUES(first_name),
+  last_name = VALUES(last_name),
+  mobile_phone = VALUES(mobile_phone),
+  timezone = VALUES(timezone),
+  is_active = VALUES(is_active),
+  password_hash = NULL,
+  salt_value = NULL,
+  email_verified_at = NULL,
+  updated_at = UTC_TIMESTAMP();
+
+-- 4) Ensure user_roles relation exists for mapped role.
+INSERT INTO user_roles (
+  id,
+  user_id,
+  role_id,
+  created_at,
+  updated_at
+)
+SELECT
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS id,
+  m.new_id AS user_id,
+  r.id AS role_id,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM user_old_import s
+JOIN user_old_id_map m ON m.old_id = s.id
+LEFT JOIN legacy_user_role_map lrm ON lrm.legacy_role = s.role
+JOIN roles r ON r.code = COALESCE(lrm.role_code, 'staff')
+ON DUPLICATE KEY UPDATE
+  updated_at = UTC_TIMESTAMP();
+
+-- 5) Pilot profiles.
+INSERT INTO pilot_profiles (
+  user_id,
+  pilot_category,
+  short_name,
+  license_no,
+  technician_license_no,
+  is_chief_pilot,
+  total_flight_minutes,
+  responsible_pilot_minutes,
+  second_pilot_minutes,
+  double_command_minutes,
+  flight_instructor_minutes,
+  night_flight_minutes,
+  ifr_flight_minutes,
+  location,
+  postcode,
+  street_line,
+  photo_file_id,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id AS user_id,
+  COALESCE(NULLIF(lrm.pilot_category, ''), 'regular') AS pilot_category,
+  LEFT(TRIM(COALESCE(s.shortName, '')), 120) AS short_name,
+  LEFT(TRIM(COALESCE(s.license, '')), 120) AS license_no,
+  LEFT(TRIM(COALESCE(s.techLicense, '')), 120) AS technician_license_no,
+  COALESCE(lrm.is_chief_pilot, 0) AS is_chief_pilot,
+  CASE WHEN TRIM(COALESCE(s.airport_pilot, '')) REGEXP '^[0-9]+:[0-9]{1,2}$'
+    THEN CAST(SUBSTRING_INDEX(TRIM(s.airport_pilot), ':', 1) AS UNSIGNED) * 60 + CAST(SUBSTRING_INDEX(TRIM(s.airport_pilot), ':', -1) AS UNSIGNED)
+    ELSE 0 END AS total_flight_minutes,
+  CASE WHEN TRIM(COALESCE(s.responsible_pilot, '')) REGEXP '^[0-9]+:[0-9]{1,2}$'
+    THEN CAST(SUBSTRING_INDEX(TRIM(s.responsible_pilot), ':', 1) AS UNSIGNED) * 60 + CAST(SUBSTRING_INDEX(TRIM(s.responsible_pilot), ':', -1) AS UNSIGNED)
+    ELSE 0 END AS responsible_pilot_minutes,
+  CASE WHEN TRIM(COALESCE(s.second_pilot, '')) REGEXP '^[0-9]+:[0-9]{1,2}$'
+    THEN CAST(SUBSTRING_INDEX(TRIM(s.second_pilot), ':', 1) AS UNSIGNED) * 60 + CAST(SUBSTRING_INDEX(TRIM(s.second_pilot), ':', -1) AS UNSIGNED)
+    ELSE 0 END AS second_pilot_minutes,
+  CASE WHEN TRIM(COALESCE(s.double_tax_pilot, '')) REGEXP '^[0-9]+:[0-9]{1,2}$'
+    THEN CAST(SUBSTRING_INDEX(TRIM(s.double_tax_pilot), ':', 1) AS UNSIGNED) * 60 + CAST(SUBSTRING_INDEX(TRIM(s.double_tax_pilot), ':', -1) AS UNSIGNED)
+    ELSE 0 END AS double_command_minutes,
+  CASE WHEN TRIM(COALESCE(s.flight_instructor_pilot, '')) REGEXP '^[0-9]+:[0-9]{1,2}$'
+    THEN CAST(SUBSTRING_INDEX(TRIM(s.flight_instructor_pilot), ':', 1) AS UNSIGNED) * 60 + CAST(SUBSTRING_INDEX(TRIM(s.flight_instructor_pilot), ':', -1) AS UNSIGNED)
+    ELSE 0 END AS flight_instructor_minutes,
+  CASE WHEN TRIM(COALESCE(s.night_pilot, '')) REGEXP '^[0-9]+:[0-9]{1,2}$'
+    THEN CAST(SUBSTRING_INDEX(TRIM(s.night_pilot), ':', 1) AS UNSIGNED) * 60 + CAST(SUBSTRING_INDEX(TRIM(s.night_pilot), ':', -1) AS UNSIGNED)
+    ELSE 0 END AS night_flight_minutes,
+  CASE WHEN TRIM(COALESCE(s.fir_pilot, '')) REGEXP '^[0-9]+:[0-9]{1,2}$'
+    THEN CAST(SUBSTRING_INDEX(TRIM(s.fir_pilot), ':', 1) AS UNSIGNED) * 60 + CAST(SUBSTRING_INDEX(TRIM(s.fir_pilot), ':', -1) AS UNSIGNED)
+    ELSE 0 END AS ifr_flight_minutes,
+  LEFT(TRIM(COALESCE(s.address, '')), 255) AS location,
+  LEFT(TRIM(COALESCE(s.zipCode, '')), 32) AS postcode,
+  LEFT(TRIM(COALESCE(s.street, '')), 255) AS street_line,
+  LEFT(TRIM(COALESCE(s.photo, '')), 255) AS photo_file_id,
+  COALESCE(s.regDate, UTC_TIMESTAMP()) AS created_at,
+  COALESCE(s.lastVisit, UTC_TIMESTAMP()) AS updated_at
+FROM user_old_import s
+JOIN user_old_id_map m ON m.old_id = s.id
+JOIN users u ON u.id = m.new_id
+JOIN legacy_user_role_map lrm ON lrm.legacy_role = s.role
+WHERE lrm.role_code = 'pilot'
+ON DUPLICATE KEY UPDATE
+  pilot_category = VALUES(pilot_category),
+  short_name = VALUES(short_name),
+  license_no = VALUES(license_no),
+  technician_license_no = VALUES(technician_license_no),
+  is_chief_pilot = VALUES(is_chief_pilot),
+  total_flight_minutes = VALUES(total_flight_minutes),
+  responsible_pilot_minutes = VALUES(responsible_pilot_minutes),
+  second_pilot_minutes = VALUES(second_pilot_minutes),
+  double_command_minutes = VALUES(double_command_minutes),
+  flight_instructor_minutes = VALUES(flight_instructor_minutes),
+  night_flight_minutes = VALUES(night_flight_minutes),
+  ifr_flight_minutes = VALUES(ifr_flight_minutes),
+  location = VALUES(location),
+  postcode = VALUES(postcode),
+  street_line = VALUES(street_line),
+  photo_file_id = VALUES(photo_file_id),
+  updated_at = UTC_TIMESTAMP();
+
+-- 6) Doctor profiles.
+INSERT INTO doctor_profiles (
+  user_id,
+  short_name,
+  medical_license_no,
+  is_chief_physician,
+  location,
+  postcode,
+  street_line,
+  photo_file_id,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id AS user_id,
+  LEFT(TRIM(COALESCE(s.shortName, '')), 120) AS short_name,
+  LEFT(TRIM(COALESCE(s.license, '')), 120) AS medical_license_no,
+  COALESCE(lrm.is_chief_physician, 0) AS is_chief_physician,
+  LEFT(TRIM(COALESCE(s.address, '')), 255) AS location,
+  LEFT(TRIM(COALESCE(s.zipCode, '')), 32) AS postcode,
+  LEFT(TRIM(COALESCE(s.street, '')), 255) AS street_line,
+  LEFT(TRIM(COALESCE(s.photo, '')), 255) AS photo_file_id,
+  COALESCE(s.regDate, UTC_TIMESTAMP()) AS created_at,
+  COALESCE(s.lastVisit, UTC_TIMESTAMP()) AS updated_at
+FROM user_old_import s
+JOIN user_old_id_map m ON m.old_id = s.id
+JOIN users u ON u.id = m.new_id
+JOIN legacy_user_role_map lrm ON lrm.legacy_role = s.role
+WHERE lrm.role_code = 'doctor'
+ON DUPLICATE KEY UPDATE
+  short_name = VALUES(short_name),
+  medical_license_no = VALUES(medical_license_no),
+  is_chief_physician = VALUES(is_chief_physician),
+  location = VALUES(location),
+  postcode = VALUES(postcode),
+  street_line = VALUES(street_line),
+  photo_file_id = VALUES(photo_file_id),
+  updated_at = UTC_TIMESTAMP();
+
+-- 7) Air rescuer profiles.
+INSERT INTO air_rescuer_profiles (
+  user_id,
+  short_name,
+  is_chief_physician_in_charge,
+  responsible_flight_rescuer,
+  location,
+  postcode,
+  street_line,
+  photo_file_id,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id AS user_id,
+  LEFT(TRIM(COALESCE(s.shortName, '')), 120) AS short_name,
+  COALESCE(lrm.is_chief_physician_in_charge, 0) AS is_chief_physician_in_charge,
+  0 AS responsible_flight_rescuer,
+  LEFT(TRIM(COALESCE(s.address, '')), 255) AS location,
+  LEFT(TRIM(COALESCE(s.zipCode, '')), 32) AS postcode,
+  LEFT(TRIM(COALESCE(s.street, '')), 255) AS street_line,
+  LEFT(TRIM(COALESCE(s.photo, '')), 255) AS photo_file_id,
+  COALESCE(s.regDate, UTC_TIMESTAMP()) AS created_at,
+  COALESCE(s.lastVisit, UTC_TIMESTAMP()) AS updated_at
+FROM user_old_import s
+JOIN user_old_id_map m ON m.old_id = s.id
+JOIN users u ON u.id = m.new_id
+JOIN legacy_user_role_map lrm ON lrm.legacy_role = s.role
+WHERE lrm.role_code = 'air_rescuer'
+ON DUPLICATE KEY UPDATE
+  short_name = VALUES(short_name),
+  is_chief_physician_in_charge = VALUES(is_chief_physician_in_charge),
+  responsible_flight_rescuer = VALUES(responsible_flight_rescuer),
+  location = VALUES(location),
+  postcode = VALUES(postcode),
+  street_line = VALUES(street_line),
+  photo_file_id = VALUES(photo_file_id),
+  updated_at = UTC_TIMESTAMP();
+
+-- 8) Technician profiles.
+INSERT INTO technician_profiles (
+  user_id,
+  short_name,
+  license_no,
+  is_chief_technician,
+  location,
+  postcode,
+  street_line,
+  photo_file_id,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id AS user_id,
+  LEFT(TRIM(COALESCE(s.shortName, '')), 120) AS short_name,
+  LEFT(TRIM(COALESCE(s.license, '')), 120) AS license_no,
+  COALESCE(lrm.is_chief_technician, 0) AS is_chief_technician,
+  LEFT(TRIM(COALESCE(s.address, '')), 255) AS location,
+  LEFT(TRIM(COALESCE(s.zipCode, '')), 32) AS postcode,
+  LEFT(TRIM(COALESCE(s.street, '')), 255) AS street_line,
+  LEFT(TRIM(COALESCE(s.photo, '')), 255) AS photo_file_id,
+  COALESCE(s.regDate, UTC_TIMESTAMP()) AS created_at,
+  COALESCE(s.lastVisit, UTC_TIMESTAMP()) AS updated_at
+FROM user_old_import s
+JOIN user_old_id_map m ON m.old_id = s.id
+JOIN users u ON u.id = m.new_id
+JOIN legacy_user_role_map lrm ON lrm.legacy_role = s.role
+WHERE lrm.role_code = 'technician'
+ON DUPLICATE KEY UPDATE
+  short_name = VALUES(short_name),
+  license_no = VALUES(license_no),
+  is_chief_technician = VALUES(is_chief_technician),
+  location = VALUES(location),
+  postcode = VALUES(postcode),
+  street_line = VALUES(street_line),
+  photo_file_id = VALUES(photo_file_id),
+  updated_at = UTC_TIMESTAMP();
+
+-- 9) Flight assistant profiles.
+INSERT INTO flight_assistant_profiles (
+  user_id,
+  short_name,
+  location,
+  postcode,
+  street_line,
+  photo_file_id,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id AS user_id,
+  LEFT(TRIM(COALESCE(s.shortName, '')), 120) AS short_name,
+  LEFT(TRIM(COALESCE(s.address, '')), 255) AS location,
+  LEFT(TRIM(COALESCE(s.zipCode, '')), 32) AS postcode,
+  LEFT(TRIM(COALESCE(s.street, '')), 255) AS street_line,
+  LEFT(TRIM(COALESCE(s.photo, '')), 255) AS photo_file_id,
+  COALESCE(s.regDate, UTC_TIMESTAMP()) AS created_at,
+  COALESCE(s.lastVisit, UTC_TIMESTAMP()) AS updated_at
+FROM user_old_import s
+JOIN user_old_id_map m ON m.old_id = s.id
+JOIN users u ON u.id = m.new_id
+JOIN legacy_user_role_map lrm ON lrm.legacy_role = s.role
+WHERE lrm.role_code = 'flight_assistant'
+ON DUPLICATE KEY UPDATE
+  short_name = VALUES(short_name),
+  location = VALUES(location),
+  postcode = VALUES(postcode),
+  street_line = VALUES(street_line),
+  photo_file_id = VALUES(photo_file_id),
+  updated_at = UTC_TIMESTAMP();
+
+-- 10) Staff profiles.
+INSERT INTO staff_profiles (
+  user_id,
+  short_name,
+  role_label,
+  location,
+  postcode,
+  street_line,
+  photo_file_id,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id AS user_id,
+  LEFT(TRIM(COALESCE(s.shortName, '')), 120) AS short_name,
+  LEFT(TRIM(COALESCE(lrm.staff_role_label, 'staff')), 120) AS role_label,
+  LEFT(TRIM(COALESCE(s.address, '')), 255) AS location,
+  LEFT(TRIM(COALESCE(s.zipCode, '')), 32) AS postcode,
+  LEFT(TRIM(COALESCE(s.street, '')), 255) AS street_line,
+  LEFT(TRIM(COALESCE(s.photo, '')), 255) AS photo_file_id,
+  COALESCE(s.regDate, UTC_TIMESTAMP()) AS created_at,
+  COALESCE(s.lastVisit, UTC_TIMESTAMP()) AS updated_at
+FROM user_old_import s
+JOIN user_old_id_map m ON m.old_id = s.id
+JOIN users u ON u.id = m.new_id
+JOIN legacy_user_role_map lrm ON lrm.legacy_role = s.role
+WHERE lrm.role_code = 'staff'
+ON DUPLICATE KEY UPDATE
+  short_name = VALUES(short_name),
+  role_label = VALUES(role_label),
+  location = VALUES(location),
+  postcode = VALUES(postcode),
+  street_line = VALUES(street_line),
+  photo_file_id = VALUES(photo_file_id),
+  updated_at = UTC_TIMESTAMP();
+
+COMMIT;
+
+-- +goose Down
+-- Data migration is intentionally non-reversible.
+-- Keep imported data and ID mapping as audit trail.
+SELECT 1;
diff --git a/migrations/goose/20260529_bases_import_staging.sql b/migrations/goose/20260529_bases_import_staging.sql
new file mode 100644
index 0000000..00e8492
--- /dev/null
+++ b/migrations/goose/20260529_bases_import_staging.sql
@@ -0,0 +1,35 @@
+-- +goose Up
+-- Prepare staging tables for legacy `bases` import.
+
+CREATE TABLE IF NOT EXISTS bases_old_import (
+  id int(11) NOT NULL,
+  name varchar(50) NOT NULL,
+  code varchar(10) NOT NULL,
+  icao varchar(255) DEFAULT NULL,
+  address varchar(255) DEFAULT NULL,
+  phone varchar(50) DEFAULT NULL,
+  mobile varchar(50) DEFAULT NULL,
+  email varchar(50) DEFAULT NULL,
+  rescue_emails varchar(255) DEFAULT NULL,
+  doctor_emails varchar(255) DEFAULT NULL,
+  sms_alert int(11) NOT NULL DEFAULT 1,
+  check_list tinyint(1) DEFAULT 0,
+  dry tinyint(1) DEFAULT 0,
+  control_center tinyint(1) DEFAULT 0,
+  service_transfer_list tinyint(1) DEFAULT 0,
+  visible tinyint(1) DEFAULT 0,
+  position tinyint(4) NOT NULL,
+  type varchar(255) NOT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS base_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_base_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS base_old_id_map;
+DROP TABLE IF EXISTS bases_old_import;
diff --git a/migrations/goose/20260530_bases_import_apply.sql b/migrations/goose/20260530_bases_import_apply.sql
new file mode 100644
index 0000000..7ce7c4b
--- /dev/null
+++ b/migrations/goose/20260530_bases_import_apply.sql
@@ -0,0 +1,193 @@
+-- +goose Up
+-- Apply legacy base staging data into new bases schema.
+
+START TRANSACTION;
+
+-- 1) Reuse existing base rows by normalized (base, abbreviation) when possible.
+INSERT INTO base_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  b.id AS new_id
+FROM bases_old_import s
+JOIN bases b
+  ON LOWER(TRIM(b.base)) = LOWER(TRIM(s.name))
+ AND LOWER(TRIM(COALESCE(b.base_abbreviation, ''))) = LOWER(TRIM(COALESCE(s.code, '')))
+LEFT JOIN base_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+-- 2) Generate IDs for remaining legacy bases.
+INSERT INTO base_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM bases_old_import s
+LEFT JOIN base_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+-- 3) Upsert base rows.
+INSERT INTO bases (
+  id,
+  base,
+  base_category_id,
+  base_abbreviation,
+  address,
+  landline_number,
+  mobile_number,
+  email,
+  sortkey,
+  sms_alert,
+  checklist,
+  dry,
+  control_center,
+  dul,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id AS id,
+  LEFT(TRIM(COALESCE(s.name, '')), 150) AS base,
+  bc.id AS base_category_id,
+  LEFT(TRIM(COALESCE(s.code, '')), 64) AS base_abbreviation,
+  LEFT(TRIM(COALESCE(s.address, '')), 255) AS address,
+  LEFT(TRIM(COALESCE(s.phone, '')), 64) AS landline_number,
+  LEFT(TRIM(COALESCE(s.mobile, '')), 64) AS mobile_number,
+  LEFT(TRIM(COALESCE(s.email, '')), 191) AS email,
+  COALESCE(s.position, 0) AS sortkey,
+  CASE WHEN COALESCE(s.sms_alert, 0) <> 0 THEN 1 ELSE 0 END AS sms_alert,
+  CASE WHEN COALESCE(s.check_list, 0) <> 0 THEN 1 ELSE 0 END AS checklist,
+  CASE WHEN COALESCE(s.dry, 0) <> 0 THEN 1 ELSE 0 END AS dry,
+  CASE WHEN COALESCE(s.control_center, 0) <> 0 THEN 1 ELSE 0 END AS control_center,
+  CASE WHEN COALESCE(s.service_transfer_list, 0) <> 0 THEN 1 ELSE 0 END AS dul,
+  CASE WHEN COALESCE(s.visible, 0) <> 0 THEN 1 ELSE 0 END AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM bases_old_import s
+JOIN base_old_id_map m ON m.old_id = s.id
+LEFT JOIN base_categories bc
+  ON bc.`key` = CASE WHEN LOWER(TRIM(COALESCE(s.type, ''))) = 'hems' THEN 'hems' ELSE 'regular' END
+ON DUPLICATE KEY UPDATE
+  base = VALUES(base),
+  base_category_id = VALUES(base_category_id),
+  base_abbreviation = VALUES(base_abbreviation),
+  address = VALUES(address),
+  landline_number = VALUES(landline_number),
+  mobile_number = VALUES(mobile_number),
+  email = VALUES(email),
+  sortkey = VALUES(sortkey),
+  sms_alert = VALUES(sms_alert),
+  checklist = VALUES(checklist),
+  dry = VALUES(dry),
+  control_center = VALUES(control_center),
+  dul = VALUES(dul),
+  is_active = VALUES(is_active),
+  updated_at = UTC_TIMESTAMP();
+
+-- 4) Build extracted legacy base-contact links from serialized fields.
+DROP TEMPORARY TABLE IF EXISTS tmp_base_contact_extract;
+CREATE TEMPORARY TABLE tmp_base_contact_extract (
+  old_base_id int(11) NOT NULL,
+  role_code varchar(64) NOT NULL,
+  legacy_user_id int(11) NOT NULL,
+  PRIMARY KEY (old_base_id, role_code, legacy_user_id)
+) ENGINE=MEMORY;
+
+INSERT IGNORE INTO tmp_base_contact_extract (old_base_id, role_code, legacy_user_id)
+WITH RECURSIVE seq AS (
+  SELECT 1 AS n
+  UNION ALL
+  SELECT n + 1 FROM seq WHERE n < 128
+),
+src AS (
+  SELECT
+    b.id AS old_base_id,
+    'responsible_flight_rescuer' AS role_code,
+    COALESCE(b.rescue_emails, '') AS serialized
+  FROM bases_old_import b
+  UNION ALL
+  SELECT
+    b.id AS old_base_id,
+    'chief_physician_in_charge' AS role_code,
+    COALESCE(b.doctor_emails, '') AS serialized
+  FROM bases_old_import b
+)
+SELECT
+  src.old_base_id,
+  src.role_code,
+  CAST(
+    SUBSTRING_INDEX(
+      SUBSTRING_INDEX(
+        REGEXP_SUBSTR(src.serialized, 's:[0-9]+:"[0-9]+"', 1, seq.n),
+        '"',
+        2
+      ),
+      '"',
+      -1
+    ) AS UNSIGNED
+  ) AS legacy_user_id
+FROM src
+JOIN seq
+  ON REGEXP_SUBSTR(src.serialized, 's:[0-9]+:"[0-9]+"', 1, seq.n) IS NOT NULL;
+
+-- 5) Replace base_contact_roles for imported bases (targeted role codes only).
+DELETE bcr
+FROM base_contact_roles bcr
+JOIN base_old_id_map bm ON bm.new_id = bcr.base_id
+WHERE bcr.role_code IN ('responsible_flight_rescuer', 'chief_physician_in_charge');
+
+-- 6) Insert deduplicated base_contact_roles by mapping legacy user IDs to new user IDs.
+INSERT INTO base_contact_roles (
+  id,
+  base_id,
+  contact_id,
+  role_code,
+  created_at,
+  updated_at
+)
+SELECT
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS id,
+  bm.new_id AS base_id,
+  um.new_id AS contact_id,
+  e.role_code AS role_code,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM (
+  SELECT DISTINCT old_base_id, role_code, legacy_user_id
+  FROM tmp_base_contact_extract
+) e
+JOIN base_old_id_map bm ON bm.old_id = e.old_base_id
+JOIN user_old_id_map um ON um.old_id = e.legacy_user_id
+;
+
+DROP TEMPORARY TABLE IF EXISTS tmp_base_contact_extract;
+
+COMMIT;
+
+-- +goose Down
+-- no-op rollback
diff --git a/migrations/goose/20260531_slings_import_staging.sql b/migrations/goose/20260531_slings_import_staging.sql
new file mode 100644
index 0000000..702d09d
--- /dev/null
+++ b/migrations/goose/20260531_slings_import_staging.sql
@@ -0,0 +1,24 @@
+-- +goose Up
+-- Prepare staging tables for legacy `slings` import.
+
+CREATE TABLE IF NOT EXISTS slings_old_import (
+  id int(11) NOT NULL,
+  cat int(11) NOT NULL,
+  name varchar(255) DEFAULT NULL,
+  type varchar(255) DEFAULT NULL,
+  length varchar(255) DEFAULT NULL,
+  weight varchar(255) DEFAULT NULL,
+  electric varchar(255) DEFAULT NULL,
+  PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+CREATE TABLE IF NOT EXISTS slings_old_id_map (
+  old_id int(11) NOT NULL,
+  new_id binary(16) NOT NULL,
+  PRIMARY KEY (old_id),
+  UNIQUE KEY uq_slings_old_id_map_new_id (new_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;
+
+-- +goose Down
+DROP TABLE IF EXISTS slings_old_id_map;
+DROP TABLE IF EXISTS slings_old_import;
diff --git a/migrations/goose/20260532_slings_import_apply.sql b/migrations/goose/20260532_slings_import_apply.sql
new file mode 100644
index 0000000..fbd8aff
--- /dev/null
+++ b/migrations/goose/20260532_slings_import_apply.sql
@@ -0,0 +1,99 @@
+-- +goose Up
+-- Apply legacy sling staging data into new facilities schema.
+
+START TRANSACTION;
+
+-- 1) Reuse existing facilities rows by normalized (category, name, type) when possible.
+INSERT INTO slings_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  f.id AS new_id
+FROM slings_old_import s
+JOIN facilities f
+  ON LOWER(TRIM(f.category)) = LOWER(TRIM(
+    CASE
+      WHEN s.cat = 1 THEN 'hems-hec-sling'
+      WHEN s.cat = 2 THEN 'logging-sling'
+      WHEN s.cat = 3 THEN 'heslo-sling'
+      WHEN s.cat IN (4, 6) THEN 'fuel-truck'
+      WHEN s.cat = 5 THEN 'hec-sling'
+      ELSE 'hec-sling'
+    END
+  ))
+ AND LOWER(TRIM(f.name)) = LOWER(TRIM(COALESCE(s.name, '')))
+ AND LOWER(TRIM(f.type)) = LOWER(TRIM(COALESCE(s.type, '')))
+LEFT JOIN slings_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+-- 2) Generate IDs for remaining legacy sling rows.
+INSERT INTO slings_old_id_map (old_id, new_id)
+SELECT
+  s.id AS old_id,
+  UNHEX(REPLACE(
+    LOWER(CONCAT(
+      LPAD(HEX(FLOOR(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED) / 65536)), 8, '0'),
+      '-',
+      LPAD(HEX(MOD(CAST(UNIX_TIMESTAMP(UTC_TIMESTAMP(3)) * 1000 AS UNSIGNED), 65536)), 4, '0'),
+      '-',
+      '7', LPAD(HEX(FLOOR(RAND() * 4096)), 3, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 16384) + 32768), 4, '0'),
+      '-',
+      LPAD(HEX(FLOOR(RAND() * 281474976710656)), 12, '0')
+    )),
+    '-', ''
+  )) AS new_id
+FROM slings_old_import s
+LEFT JOIN slings_old_id_map m ON m.old_id = s.id
+WHERE m.old_id IS NULL;
+
+-- 3) Upsert into facilities.
+INSERT INTO facilities (
+  id,
+  category,
+  name,
+  type,
+  length,
+  weight,
+  electric,
+  note,
+  is_active,
+  created_at,
+  updated_at
+)
+SELECT
+  m.new_id AS id,
+  CASE
+    WHEN s.cat = 1 THEN 'hems-hec-sling'
+    WHEN s.cat = 2 THEN 'logging-sling'
+    WHEN s.cat = 3 THEN 'heslo-sling'
+    WHEN s.cat IN (4, 6) THEN 'fuel-truck'
+    WHEN s.cat = 5 THEN 'hec-sling'
+    ELSE 'hec-sling'
+  END AS category,
+  LEFT(TRIM(COALESCE(s.name, '')), 150) AS name,
+  LEFT(TRIM(COALESCE(s.type, '')), 100) AS type,
+  LEFT(TRIM(COALESCE(s.length, '')), 64) AS length,
+  LEFT(TRIM(COALESCE(s.weight, '')), 64) AS weight,
+  LEFT(TRIM(COALESCE(s.electric, '')), 255) AS electric,
+  NULL AS note,
+  1 AS is_active,
+  UTC_TIMESTAMP() AS created_at,
+  UTC_TIMESTAMP() AS updated_at
+FROM slings_old_import s
+JOIN slings_old_id_map m ON m.old_id = s.id
+ON DUPLICATE KEY UPDATE
+  category = VALUES(category),
+  name = VALUES(name),
+  type = VALUES(type),
+  length = VALUES(length),
+  weight = VALUES(weight),
+  electric = VALUES(electric),
+  note = VALUES(note),
+  is_active = VALUES(is_active),
+  updated_at = UTC_TIMESTAMP();
+
+COMMIT;
+
+-- +goose Down
+-- no-op rollback
diff --git a/migrations/goose/20260533_facilities_electric_to_string.sql b/migrations/goose/20260533_facilities_electric_to_string.sql
new file mode 100644
index 0000000..3dbdc58
--- /dev/null
+++ b/migrations/goose/20260533_facilities_electric_to_string.sql
@@ -0,0 +1,17 @@
+-- +goose Up
+-- +goose StatementBegin
+ALTER TABLE facilities
+  MODIFY COLUMN electric VARCHAR(255) NOT NULL DEFAULT '';
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+UPDATE facilities
+SET electric = CASE
+  WHEN LOWER(TRIM(electric)) IN ('', '0', 'false', 'no', 'n') THEN '0'
+  ELSE '1'
+END;
+
+ALTER TABLE facilities
+  MODIFY COLUMN electric TINYINT(1) NOT NULL DEFAULT 0;
+-- +goose StatementEnd
diff --git a/migrations/goose/20260602_add_flight_id_to_duty_rosters.sql b/migrations/goose/20260602_add_flight_id_to_duty_rosters.sql
new file mode 100644
index 0000000..3d9444a
--- /dev/null
+++ b/migrations/goose/20260602_add_flight_id_to_duty_rosters.sql
@@ -0,0 +1,26 @@
+-- +goose Up
+-- Align duty roster schema with takeover flow.
+-- A takeover creates a fresh roster row, so base/date must be a lookup index,
+-- not a unique constraint.
+
+ALTER TABLE duty_rosters
+  ADD COLUMN flight_id BINARY(16) NULL AFTER id;
+
+CREATE UNIQUE INDEX idx_roster_flight_id
+  ON duty_rosters (flight_id);
+
+DROP INDEX idx_roster_base_date ON duty_rosters;
+
+CREATE INDEX idx_roster_base_date
+  ON duty_rosters (base_id, duty_date);
+
+-- +goose Down
+DROP INDEX idx_roster_base_date ON duty_rosters;
+
+CREATE UNIQUE INDEX idx_roster_base_date
+  ON duty_rosters (base_id, duty_date);
+
+DROP INDEX idx_roster_flight_id ON duty_rosters;
+
+ALTER TABLE duty_rosters
+  DROP COLUMN flight_id;
diff --git a/migrations/goose/20260610_contact_username_non_unique.sql b/migrations/goose/20260610_contact_username_non_unique.sql
new file mode 100644
index 0000000..b4079bc
--- /dev/null
+++ b/migrations/goose/20260610_contact_username_non_unique.sql
@@ -0,0 +1,15 @@
+-- +goose Up
+-- Username uniqueness is now enforced in the backend for contact flows,
+-- so keep a regular index for lookups instead of a unique constraint.
+
+DROP INDEX IF EXISTS idx_users_username ON users;
+
+CREATE INDEX idx_users_username
+  ON users (username);
+
+-- +goose Down
+DROP INDEX IF EXISTS idx_users_username ON users;
+
+CREATE UNIQUE INDEX idx_users_username
+  ON users (username);
+iya
\ No newline at end of file
diff --git a/migrations/goose/20260613_base_operational_shift_times_date_range.sql b/migrations/goose/20260613_base_operational_shift_times_date_range.sql
new file mode 100644
index 0000000..188e8b7
--- /dev/null
+++ b/migrations/goose/20260613_base_operational_shift_times_date_range.sql
@@ -0,0 +1,53 @@
+-- +goose Up
+-- Normalize base operational shift times to use per-day ranges.
+
+ALTER TABLE base_operational_shift_times
+  ADD COLUMN IF NOT EXISTS date_start DATE NULL AFTER base_id,
+  ADD COLUMN IF NOT EXISTS date_end DATE NULL AFTER date_start;
+
+UPDATE base_operational_shift_times
+SET date_start = COALESCE(date_start, operation_date),
+    date_end = COALESCE(date_end, operation_date)
+WHERE deleted_at IS NULL;
+
+ALTER TABLE base_operational_shift_times
+  DROP FOREIGN KEY fk_base_operational_shift_times_base;
+
+ALTER TABLE base_operational_shift_times
+  DROP INDEX idx_base_operational_shift_times_base_date;
+
+ALTER TABLE base_operational_shift_times
+  DROP COLUMN operation_date;
+
+ALTER TABLE base_operational_shift_times
+  ADD KEY idx_base_operational_shift_times_base_date (base_id, date_start, date_end),
+  MODIFY COLUMN date_start DATE NULL,
+  MODIFY COLUMN date_end DATE NULL,
+  ADD CONSTRAINT fk_base_operational_shift_times_base
+    FOREIGN KEY (base_id) REFERENCES bases(id)
+    ON UPDATE CASCADE
+    ON DELETE CASCADE;
+
+-- +goose Down
+ALTER TABLE base_operational_shift_times
+  ADD COLUMN IF NOT EXISTS operation_date DATE NULL AFTER base_id;
+
+UPDATE base_operational_shift_times
+SET operation_date = COALESCE(operation_date, date_start)
+WHERE deleted_at IS NULL;
+
+ALTER TABLE base_operational_shift_times
+  DROP FOREIGN KEY fk_base_operational_shift_times_base;
+
+ALTER TABLE base_operational_shift_times
+  DROP INDEX idx_base_operational_shift_times_base_date;
+
+ALTER TABLE base_operational_shift_times
+  ADD KEY idx_base_operational_shift_times_base_date (base_id, operation_date),
+  DROP COLUMN date_start,
+  DROP COLUMN date_end,
+  MODIFY COLUMN operation_date DATE NOT NULL,
+  ADD CONSTRAINT fk_base_operational_shift_times_base
+    FOREIGN KEY (base_id) REFERENCES bases(id)
+    ON UPDATE CASCADE
+    ON DELETE CASCADE;
diff --git a/migrations/goose/20260619_mission_twilight_schedule.sql b/migrations/goose/20260619_mission_twilight_schedule.sql
new file mode 100644
index 0000000..a6f1d9c
--- /dev/null
+++ b/migrations/goose/20260619_mission_twilight_schedule.sql
@@ -0,0 +1,31 @@
+-- +goose Up
+
+ALTER TABLE bases
+  ADD COLUMN IF NOT EXISTS latitude DECIMAL(10,7) NOT NULL DEFAULT 0 AFTER address,
+  ADD COLUMN IF NOT EXISTS longitude DECIMAL(10,7) NOT NULL DEFAULT 0 AFTER latitude;
+
+ALTER TABLE base_operational_shift_times
+  ADD COLUMN IF NOT EXISTS start_time_type VARCHAR(16) NOT NULL DEFAULT 'FIXED' AFTER date_end,
+  ADD COLUMN IF NOT EXISTS end_time_type VARCHAR(16) NOT NULL DEFAULT 'FIXED' AFTER start_time_type;
+
+ALTER TABLE missions
+  ADD COLUMN IF NOT EXISTS start_time TIME NULL AFTER note,
+  ADD COLUMN IF NOT EXISTS end_time TIME NULL AFTER start_time;
+
+ALTER TABLE missions
+  MODIFY COLUMN start_time TIME NULL,
+  MODIFY COLUMN end_time TIME NULL;
+
+-- +goose Down
+
+ALTER TABLE missions
+  DROP COLUMN IF EXISTS end_time,
+  DROP COLUMN IF EXISTS start_time;
+
+ALTER TABLE base_operational_shift_times
+  DROP COLUMN IF EXISTS end_time_type,
+  DROP COLUMN IF EXISTS start_time_type;
+
+ALTER TABLE bases
+  DROP COLUMN IF EXISTS longitude,
+  DROP COLUMN IF EXISTS latitude;
diff --git a/migrations/goose/20260630_easa_release_sign_requires_pin.sql b/migrations/goose/20260630_easa_release_sign_requires_pin.sql
new file mode 100644
index 0000000..42eb248
--- /dev/null
+++ b/migrations/goose/20260630_easa_release_sign_requires_pin.sql
@@ -0,0 +1,15 @@
+-- +goose Up
+-- Enable security-PIN confirmation for signing an EASA maintenance release
+-- (Release to Service). Fresh DBs get this via the default PIN policy at seed
+-- time; this backfills existing permission rows. The guard avoids overriding a
+-- value an admin has already customised (updated_by set).
+UPDATE permissions
+SET requires_pin = 1
+WHERE `key` = 'easa_release.sign'
+  AND (updated_by IS NULL OR LENGTH(updated_by) = 0);
+
+-- +goose Down
+UPDATE permissions
+SET requires_pin = 0
+WHERE `key` = 'easa_release.sign'
+  AND (updated_by IS NULL OR LENGTH(updated_by) = 0);
diff --git a/migrations/scripts/migration_helicopter.sql b/migrations/scripts/migration_helicopter.sql
new file mode 100644
index 0000000..a9b4253
--- /dev/null
+++ b/migrations/scripts/migration_helicopter.sql
@@ -0,0 +1,10 @@
+-- Deprecated helper script.
+-- Use versioned goose migrations instead:
+--   1) make migrate-up-to v=20260414
+--   2) import legacy dump rows into table `helicopter_old_import`
+--   3) make migrate-up-to v=20260415
+--
+-- Notes:
+-- - Data is migrated into `helicopters` (backend table name) with UUID bytes (BINARY(16)).
+-- - `counter`, `service`, `disabled`, `visible` from legacy dump are ignored.
+-- - `is_active` is forced to 1.
diff --git a/scripts/infisical-deploy.sh b/scripts/infisical-deploy.sh
new file mode 100644
index 0000000..909adb2
--- /dev/null
+++ b/scripts/infisical-deploy.sh
@@ -0,0 +1,41 @@
+#!/bin/bash
+set -euo pipefail
+
+ENV_FILE="/opt/flight-manager/development/.env"
+TEMPLATE="/opt/flight-manager/development/config.template.json"
+OUTPUT="/opt/flight-manager/development/config.generated.json"
+DOCKER_COMPOSE_PATH="/opt/stacks/..."
+
+echo "[deploy] Secrets changed, reloading..."
+
+# Load new secrets
+set -a; source "$ENV_FILE"; set +a
+
+# Validate all required vars are present
+REQUIRED_VARS=$(grep -o '\${[A-Z0-9_]\+}' "$TEMPLATE" | tr -d '${}' | sort -u)
+MISSING=()
+for var in $REQUIRED_VARS; do
+  [ -z "${!var+set}" ] && MISSING+=("$var")
+done
+if [ ${#MISSING[@]} -gt 0 ]; then
+  echo "[deploy] ERROR: Missing variables: ${MISSING[*]}"
+  exit 1
+fi
+
+# Render config.generated.json
+VARS=$(printf '${%s} ' $REQUIRED_VARS)
+envsubst "$VARS" < "$TEMPLATE" > "$OUTPUT"
+
+# Validate JSON
+if ! jq empty "$OUTPUT" 2>/dev/null; then
+  echo "[deploy] ERROR: Generated config is not valid JSON"
+  rm -f "$OUTPUT"
+  exit 1
+fi
+
+echo "[deploy] Config generated at $OUTPUT"
+
+# Restart docker compose
+docker compose -f "$DOCKER_COMPOSE_PATH" restart
+
+echo "[deploy] Done."
diff --git a/scripts/inject-secrets.sh b/scripts/inject-secrets.sh
new file mode 100644
index 0000000..817c176
--- /dev/null
+++ b/scripts/inject-secrets.sh
@@ -0,0 +1,112 @@
+#!/bin/bash
+set -euo pipefail
+
+# Usage:
+# ./scripts/inject-secrets.sh local
+# ./scripts/inject-secrets.sh staging
+# ./scripts/inject-secrets.sh prod
+
+ENV=${1:-local}
+OUTPUT_PATH=${2:-/tmp/config.generated.json}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+TEMPLATE="$REPO_ROOT/config/$ENV/config.json"
+
+echo "==> Environment: $ENV"
+echo "==> Template: $TEMPLATE"
+echo "==> Output: $OUTPUT_PATH"
+
+# ■■ Validate template exists ■■
+if [ ! -f "$TEMPLATE" ]; then
+  echo "ERROR: Config template not found at $TEMPLATE"
+  exit 1
+fi
+
+# ■■ Load secrets ■■
+if [ "$ENV" = "local" ]; then
+  ENV_FILE="$REPO_ROOT/.env.local"
+
+  if [ ! -f "$ENV_FILE" ]; then
+    echo "ERROR: .env.local not found. Copy .env.local.example and fill in your values."
+    exit 1
+  fi
+
+  echo "==> Loading local env from $ENV_FILE"
+
+  set -a
+  source "$ENV_FILE"
+  set +a
+
+else
+  echo "==> Fetching secrets from AWS Secrets Manager"
+
+  AWS_ARGS=(
+    secretsmanager get-secret-value
+    --secret-id "$ENV/fm-be/config"
+    --query SecretString
+    --output text
+  )
+
+  if [ -n "${AWS_ENDPOINT_URL:-}" ]; then
+    echo "==> Using custom AWS endpoint: $AWS_ENDPOINT_URL"
+    AWS_ARGS+=(--endpoint-url "$AWS_ENDPOINT_URL")
+  fi
+
+  SECRET=$(aws "${AWS_ARGS[@]}")
+
+  eval "$(echo "$SECRET" | jq -r 'to_entries | .[] | "export \(.key)=\(.value)"')"
+fi
+
+# ■■ Extract required variables from template ■■
+REQUIRED_VARS=$(grep -o '\${[A-Z0-9_]\+}' "$TEMPLATE" | tr -d '${}' | sort -u)
+
+echo "==> Validating required variables..."
+
+MISSING=()
+EMPTY=()
+
+for var in $REQUIRED_VARS; do
+  if [ -z "${!var+set}" ]; then
+    MISSING+=("$var")
+  elif [ -z "${!var}" ]; then
+    EMPTY+=("$var")
+  fi
+done
+
+if [ ${#MISSING[@]} -gt 0 ]; then
+  echo "ERROR: The following variables are not set at all:"
+  for v in "${MISSING[@]}"; do
+    echo " - $v"
+  done
+  exit 1
+fi
+
+if [ ${#EMPTY[@]} -gt 0 ]; then
+  echo "WARNING: The following variables are set but empty:"
+  for v in "${EMPTY[@]}"; do
+    echo " - $v"
+  done
+fi
+
+echo "==> All required variables are set"
+
+# ■■ Safe substitution (only replace known vars) ■■
+VARS=$(printf '${%s} ' $REQUIRED_VARS)
+
+envsubst "$VARS" < "$TEMPLATE" > "$OUTPUT_PATH"
+
+echo "==> Config generated at $OUTPUT_PATH"
+
+# ■■ Validate JSON ■■
+if ! jq empty "$OUTPUT_PATH" 2>/dev/null; then
+  echo "ERROR: Generated config is not valid JSON"
+  echo "==> jq diagnostics:"
+  jq empty "$OUTPUT_PATH" || true
+  rm -f "$OUTPUT_PATH"
+  exit 1
+fi
+
+echo "==> JSON validation passed"
+
+echo "==> Done."